网络案例库建设

把"某类主题的公开网络案例"做成一份可核验、可查询、可持续更新的案例库，并发布为网页。

核心信条：这份数据的价值 = 准确可信 × 可查询 × 可持续。三者缺一，产物就只是"一堆链接"。

0. 适用范围硬性判定（第一步必做，不可跳过）

命中以下全部三条才走本技能，否则立即明确告知用户不属于本技能范围，并说明它实际属于什么：

| # | 条件 | 说明 | |---|---|---| | A | 目标是某类主题的案例集合 | 例如"高校 AI 教学应用案例""中小学跨学科教学案例""企业数字化转型案例"。不是单篇报告、不是某个具体问题的答案 | | B | 案例来源是公开网络页面 | 每条案例最终要落到一个可点击、可回访的具体网页链接上 | | C | 期望产物包含结构化清单 + 可查询发布 | 至少是"一张表"；网页 / 自动更新是可选增值 |

明确排除（须告知用户并给出正确路由）：

| 用户实际想要 | 真实归属 | 回话口径 | |---|---|---| | 某一问题的深度研究报告、文献综述 | 深度研究 / 文献综述类工作流 | 「这是研究报告，不是案例库。我可以按案例库方式做，但结构和你想要的会是两回事」 | | 学术文献（论文）的检索与引用管理 | 文献调研工作流（Crossref / arXiv / DOI 核验） | 「这是文献综述，不是网络案例库」 | | 一份文件、一个网站的内容抽取 | 单次抓取任务 | 「不需要走五步，直接抓即可」 | | 需要登录 / 付费 / 反爬严密的站点数据 | 需先解决授权 | 「这些站点自动化抓取不可靠，建议人工导出后我再入库」 |

判定为不适用时，只说清楚原因和建议，不进入五步流程。

1. 参数收集（1.2）

进入流程前，必须向用户确认以下参数。必填项缺失 → 停下来问，不许猜：

| 参数 | 必填 | 默认 | 说明 | |---|---|---|---| | 主题方向 / 具体要求 | ✅ 必填 | — | 用一句话说清"收集什么样的案例"。含纳入/排除口径、地域范围、时间范围 | | 数量要求 | 选填 | 50 | 不填则默认 50 条 | | 调研的核心网站 | 选填 | 无 | 名称或网址，可多个。给了就必须作为第一优先来源 |

推荐用 AskUserQuestion 收集，选项给具体值而非抽象标签。用户已明确给出全部必填项时，不要重复追问。

2. 五步流程总览

Step 1 需求确认 + 网络调研 ──► cases.csv ──► ⛔ 用户审阅通过
Step 2 幻觉审计（死链/内容不符/非案例页）──► 审计报告 ──► ⛔ 用户同意整改
Step 3 两级分类 ──► 分类建议 ──► ⛔ 用户确认
Step 4 发布为网页案例库 ──► 资料库 database + page ──► 网址 + 二维码
Step 5 建立自动化更新任务 ──► WorkBuddy 自动化

⛔ = 硬门禁。 每步结束必须停下来请用户确认，用户未明确表示通过就不得进入下一步。这是本流程最重要的纪律——前面一步的错误会无损传导到最后一步，返工成本指数上升。

Step 1 · 需求确认 + 网络调研

按 §0 判定适用性（不适用就停）；按 §1 收集参数（缺必填就问）。
来源优先级严格递减： ① 用户指定的核心网站 → ② 这些站点页面中提到的相关链接（顺藤摸瓜，命中率最高）→ ③ 自主 WebSearch / WebFetch 扩展新站点。只有上一优先级数量不够时，才进入下一级；扩大范围前先向用户报告一次当前进度。
每条案例抓取后立即登记，不要攒到最后一起写——中途断流会丢数据。
输出到 cases.csv（UTF-8 BOM，Excel 可直接打开）。字段规范见 assets/csv_schema.md。
提示用户"本步已完成，请审阅并提出修改意见"，附上：总数、来源站点分布、字段完整度。等待明确通过。

👉 详细 SOP：references/step1-collection.md

Step 2 · 幻觉审计

三层核验，缺一不可：

| 层 | 查什么 | 手段 | |---|---|---| | L1 链接层 | 死链、超时、404、跳转到首页 | scripts/check_links.py 批量跑 | | L2 内容层 | 页面内容与表中描述不符；页面不是具体案例（通知、获奖名单、简讯、栏目首页） | 逐条 WebFetch 抓正文，与表中"案例描述"对照 | | L3 事实层 | 发布单位、发布时间、标题张冠李戴 | 抽取页面标题/署名/日期，与表中字段比对 |

判级（沿用既有的颜色编码规范）：

| 级别 | 含义 | 处置 | |---|---|---| | 🟢 绿 | 一字不差 / 恰当 | 保留 | | ⚫ 黑 | 有偏差（数据口径、归因错误、描述夸大） | 按原文修正；修不了则降级或删除 | | 🔴 红 | 编造 / 死链 / 无效页面 | 删除 |

输出审计报告（模板：assets/audit_report_template.html），向用户出示并询问是否按报告整改。

用户同意后整改 CSV，并在表中写入审计状态列（已通过幻觉审计）。整改完成必须向用户输出这句话（原话，不可省略、不可软化）：

⚠️ 用 AI 审计 AI 并不能保证 100% 准确，您应逐条人工核验，才能确保准确！

用户若提出补充新案例等其它要求，一并执行。

👉 详细 SOP 与判级细则：references/step2-audit.md

Step 3 · 两级分类

AI 先给出分类方案建议（一级 5–8 个、每级下 2–5 个二级），请用户确认。
命名规则：一级用中文序号前缀（一、赋能教师备课），二级用编号前缀（2.1 智能备课辅助工具）——模板依赖这个格式做目录渲染。
用户确认后回写 CSV 的 一级分类/二级分类 两列。

👉 详细 SOP：references/step3-classification.md

Step 4 · 发布为网页案例库

先问用户：是否需要将案例库发布为网页供查询？用户同意后再做。

⛔ 确认提示只有两个选项：①「发布（SDK 模式，推荐）」②「暂不发布」。不得出现 "inline 一次性" 选项。详见 §3 硬约束 #3。

标准链路（资料库原生能力）：

CSV ──► database 节点（结构化表，可增删改查）
                  │  ① page_database_relation.py link 建立关联
                  ▼
HTML ──► page 节点（运行时用 __SMART_PAGE__.database SDK 从 database 读数）
                  │  ② publish_page.py 发布
                  ▼
        publishUrl ──► make_qr.py ──► 二维码

关键架构决策（决定了 Step 5 能否成立）：HTML 绝不把数据当作唯一来源硬编码，必须以 SDK 运行时读 database 为主。这样：

用户在资料库里改表 / 自动化任务更新表 → 页面下次加载自动显示最新数据，HTML 一个字都不用改（2026-08-31 实测确认）。
用户要改样式 → 只改 HTML 的 CSS/JS，数据不受影响。
注意：SDK 页面同时内嵌一份同款数据快照兜底（build_site.py 已内置）——这是给"手机端返回后数据桥缺失"场景的保险，不影响"改表即同步"链路，不要把它误解为硬编码。

产物交付：网址 + 二维码（PNG/SVG）。

👉 完整命令与踩坑：references/step4-publish.md

Step 5 · 建立自动化更新任务

先问用户：是否需要为案例库建立自动化任务？同意后再问规则（更新周期、每次最少更新条目数、是否覆盖旧数据）。

用 automation_update 工具创建，prompt 里必须写清：

完整执行 Step1（调研+写入 CSV/database）→ Step2（AI 审计）
审计有问题的条目直接删除，不再补充
每轮审计报告留档（audit/audit_YYYY-MM-DD.html）

👉 prompt 模板与可行性论证：references/step5-automation.md

3. 硬约束（不可协商）

门禁不可跳过：Step1/2/3 每一步都要用户明确通过。
来源优先级不可乱：用户给的站点是第一优先，不许绕过它去自由发挥。
数据以 SDK 运行时读数为主（唯一对外模式）：发布环节只提供 SDK 模式（--mode sdk，页面内嵌快照仅为断桥兜底，不作为数据源）。绝不向用户提供 "inline 一次性" 选项——即便用户说"一次性、不需要更新"，也一律用 SDK 模式（它本就支持只读不改，且能满足所有场景）。inline 仅保留为 §4.3 中"SDK 经三层验证确认完全不可用"时的 AI 技术兜底，不对用户开放、不出现在确认提示里。
审计声明不可省略：Step2 整改后必须原话警告用户人工核验。
不编造：抓不到就写"未获取"，绝不填充看起来合理的内容。宁可少一条，不可错一条。
幻觉审计不是走过场：L1 脚本只是筛死链，L2/L3 必须逐条读页面内容。
绝不删除自动化以外的用户数据：删除条目只发生在 Step2 整改与 Step5 自动审计，且必须有审计结论支撑。

4. 目录约定

在工作空间下建立（可按需改名，但结构保持一致）：

<工作目录>/
├── cases.csv                  # 主数据（唯一事实源，与云端 database 表内容一一对应）
├── audit/
│   ├── check_result.json      # 死链核验机读结果
│   ├── audit_YYYY-MM-DD.html  # 每轮审计报告留档
│   └── README.md              # 审计历史摘要
├── site/
│   ├── index_sdk.html         # 案例库页面（SDK 读数版，发布用这份）
│   └── index.html             # inline 版（仅 SDK 不可用时的 AI 技术兜底，不向用户开放）
└── qrcode.png                 # 访问二维码（+ qrcode.svg 可选）

5. 脚本与模板索引

| 文件 | 用途 | |---|---| | scripts/check_links.py | 批量核验链接可达性与页面内容质量（L1），输出 JSON + 控制台摘要 | | scripts/build_site.py | CSV → 案例库 HTML（--mode sdk 唯一对外模式，含快照兜底；--mode inline 仅 SDK 不可用时的 AI 兜底，不向用户开放） | | scripts/make_qr.py | URL → 二维码 PNG/SVG（按 --out 扩展名，无 --svg 参数） | | scripts/test_pick.js | 改模板取值逻辑后必跑：字段值形态回归测试（12 用例） | | scripts/verify_page.js | 发布后必跑：穿透 iframe 四项校验（总数/未分类/未命名/暂无链接） | | scripts/diag_sdk_fields.js | 某字段全空时：打印 SDK 原始记录结构与字段类型 | | assets/csv_schema.md | CSV 字段规范与取值约定 | | assets/case_library_template.html | 案例库网页模板（两级目录+搜索+卡片+移动端适配，深藏青/金学术风） | | assets/audit_report_template.html | 幻觉审计报告模板（绿/黑/红判级） | | references/step1~5*.md | 各步详细 SOP | | references/pitfalls.md | 实证踩坑清单，动手前先扫一遍 |

6. 用户常见疑问（已知答案，直接回答，不必重新推导）

Q1（Step4）· 我想先把 HTML 放进资料库，这样能自己改样式，这个想法可行吗？ 可行，而且是正确的做法。 但要分清两件事：

✅ HTML 的样式/结构 → 放在 page 节点里，用户可随时让 AI 改（事务协议：拉产物→本地改→增量上传→提交新版），改样式与改数据互不干扰。
✅ 案例数据 → 放在 database 节点里，用户在资料库界面直接增删改查，页面自动跟着变。
⚠️ 边界：HTML 源码本身不能像在线文档那样在浏览器里随手编辑，改代码仍需通过 AI 事务提交（或本地改完重新导入）。真正的"用户自助"体现在数据层自助——这才是设计目标。

Q2（Step5）· 自动化任务里做 AI 审计可行吗？ 可行，但精度低于人工参与的人工审计。 分层看：

L1 死链核验 → 完全可行，脚本确定性执行，与人工版本无差异。
L2/L3 内容核验 → 部分可行：能可靠识别死链、空页、跳转首页、纯通知/名单类页面，也能做标题与描述的相似度比对；但对"描述细微夸大""单位张冠李戴"这类需要跨源交叉验证的判断，误判率明显上升。
因此设计上必须保守：审计判红的直接删除（宁删勿留），判黑的也删除而非自动修正——自动修正等于让 AI 在没有外部真值的情况下重写事实，风险高于收益。只保留判绿的。

Q3（Step5）· 我理解是：自动化任务更新 CSV，访问 HTML 时显示最新案例库。对吗？ 对，但有一个前提：HTML 必须通过 window.__SMART_PAGE__.database SDK 在运行时读 database。满足这个前提时，自动化更新的是 CSV/database，用户刷新页面即见最新数据，HTML 无需重新生成或重新上传。如果当时图省事把数据硬编码进 HTML（内联模式），这条链路就断了——每次更新都得重新生成并上传整个页面。所以发布环节默认且只推荐 SDK 模式。

✅ 已实测确认（2026-08-31）：向 CSV 追加一条记录 → import_csv.py --database-id <原 id> 覆盖导入云端表 → 不重新生成 HTML、不重新导入 page、不重新发布，直接刷新页面，总数由 57 变为 58 且新条目正常显示。即：CSV → 云端表这一步要主动同步，表 → 页面这一步是自动的。

⚠️ 曾因两个隐蔽故障误判"SDK 不可用"，排查前先看 step4-publish.md §2.1 / §4.1 / §4.2： ① import_csv 建出行数正确但单元格全空的表（必须校验非空行数）； ② SDK 的 url 字段返回数组 [{link,text}]，取值函数只按单对象处理 → 链接全丢。

Q4（发布后）· 用户反馈手机微信上"页面蒙黑""点链接无响应""返回空白""部分链接打不开"——是模板/代码的 bug 吗？ 多数不是，是微信 webview 的环境限制，模板已内置对应适配（见 step4-publish.md §5）。排查口径：

| 现象 | 真实原因 | 模板对策 | 状态 | |---|---|---|---| | 整页蒙一层黑（仅手机微信） | 系统深色模式下微信对未声明 color-scheme 的页面强制反色 | <meta name="color-scheme" content="light"> + CSS :root{color-scheme:light} | 已内置 | | 点"查看来源"无响应（仅手机） | 微信 webview 不支持 target="_blank" 开新窗口 | openLink：window.open 优先，失败退当前页跳转 | 已内置 | | 看完文章返回后空白/卡"正在加载" | bfcache 恢复后数据桥失效；纯 SDK 页无兜底数据 | SDK 页内嵌快照兜底 + pageshow 重跑 init + waitForBridge | 已内置 | | 部分外部链接手机打不开（电脑正常） | 微信对站点证书/协议/反爬校验更严（如部分高校站） | 卡片附「📋 复制链接」按钮，粘贴到系统浏览器打开 | 已内置 |

若用户仍报异常，先用 verify_page.js（桌面）+ 手机实测复现，再定位；不要一上来改代码。另：跳转后外部文章页上的深色悬浮物，常是新闻网站自带的广告，与本模板无关（截图对照即可确认）。

7. 环境准备

# 主数据处理（系统 Python 已具备 pandas / openpyxl / requests / bs4）
"C:/Users/jowa/AppData/Local/Programs/Python/Python312/python.exe" -c "import pandas,openpyxl;print('ok')"

# 二维码（纯 Python，无二进制依赖；只需装一次）
"C:/Users/jowa/.workbuddy/binaries/python/versions/3.13.12/python.exe" -m venv "C:/Users/jowa/.workbuddy/binaries/python/envs/netresearch"
"C:/Users/jowa/.workbuddy/binaries/python/envs/netresearch/Scripts/pip.exe" install segno

注：镜像源（如清华源）在部分网络环境下取不到包，用默认 PyPI 源即可。