Merge pull request #51 from iflytek/chore/doc-watch-automation

chore: 上游文档每日巡检 doc-watch（抓取+对比+告警，附联网补全 routine）

Author: FenjuFu

.github/workflows/doc-watch.yml

@@ -0,0 +1,76 @@
+name: doc-watch
+
+# 每日抓取上游文档站（Loomy Docs / AstronClaw 使用指南），与仓库基线对比，
+# 发现新增内容或图片时，自动维护一条 [doc-watch] Issue 汇总待补全清单。
+#
+# 触发：每天 01:00 UTC（北京时间 09:00）+ 可手动触发。
+
+on:
+  schedule:
+    - cron: '0 1 * * *'
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  watch:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Run doc-watch
+        id: watch
+        run: |
+          set +e
+          node scripts/doc-watch/check-updates.mjs --report doc-watch-report.md
+          echo "code=$?" >> "$GITHUB_OUTPUT"
+          set -e
+
+      - name: Upsert summary issue on changes
+        if: steps.watch.outputs.code == '1'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          BODY_FILE=doc-watch-report.md
+          {
+            echo ""
+            echo "---"
+            echo "_由 \`doc-watch\` 工作流自动生成 · run [#${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})_"
+            echo ""
+            echo "处理完成后，在补全内容的 PR 里执行 \`node scripts/doc-watch/check-updates.mjs --update\` 刷新基线，本 Issue 即可关闭。"
+          } >> "$BODY_FILE"
+
+          TITLE="[doc-watch] 上游文档有新增内容待补全"
+          EXISTING=$(gh issue list --label doc-watch --state open --json number --jq '.[0].number' 2>/dev/null)
+          if [ -n "$EXISTING" ]; then
+            gh issue edit "$EXISTING" --body-file "$BODY_FILE"
+            gh issue comment "$EXISTING" --body "🔄 巡检报告已于本次 run 更新（run #${{ github.run_number }}）。"
+            echo "Updated issue #$EXISTING"
+          else
+            gh label create doc-watch --color FBCA04 --description "上游文档巡检" 2>/dev/null || true
+            gh issue create --title "$TITLE" --label doc-watch --body-file "$BODY_FILE"
+          fi
+
+      - name: Report capture failure
+        if: steps.watch.outputs.code == '2'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh label create doc-watch --color FBCA04 --description "上游文档巡检" 2>/dev/null || true
+          gh issue create \
+            --title "[doc-watch] ⚠️ 巡检抓取失败" \
+            --label doc-watch \
+            --body "doc-watch 工作流抓取上游文档时出错，请查看 run [#${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) 日志。可能是上游站点改版或网络问题。"
+
+      - name: Upload report artifact
+        if: steps.watch.outputs.code == '1'
+        uses: actions/upload-artifact@v4
+        with:
+          name: doc-watch-report
+          path: doc-watch-report.md

scripts/doc-watch/README.md

@@ -0,0 +1,84 @@
+# doc-watch · 上游文档每日巡检
+
+每天抓取上游文档站，与仓库基线对比，发现**新增内容 / 新增图片**，并辅助把新内容（含配图）补全到本教程站点。
+
+## 监测的源
+
+| 源 | 地址 | 抓取方式 |
+|---|---|---|
+| Loomy Docs | https://loomy.xunfei.cn/docs | VitePress SSG，自动从侧边栏发现全部页面 |
+| AstronClaw 使用指南 | https://www.xfyun.cn/doc/spark/Agent-AstronClaw使用指南.html | 单页 SSR |
+
+## 组成
+
+```
+scripts/doc-watch/
+  check-updates.mjs     # 抓取 + 对比引擎（零依赖，Node 18+ 内置 fetch）
+  baseline/             # 基线快照（每源一个 JSON：页面 / 小节 / 图片 / 正文哈希）
+    loomy.json
+    astronclaw.json
+.github/workflows/doc-watch.yml   # 每日 cron，发现变化时维护一条 [doc-watch] Issue
+```
+
+## 本地用法
+
+```bash
+# 巡检：与基线对比，有变化时退出码 1，并打印 Markdown 报告
+node scripts/doc-watch/check-updates.mjs
+
+# 把报告写到文件
+node scripts/doc-watch/check-updates.mjs --report report.md
+
+# 输出 JSON（便于程序消费）
+node scripts/doc-watch/check-updates.mjs --json
+
+# 首次创建 / 重建基线
+node scripts/doc-watch/check-updates.mjs --init
+
+# 接受当前线上状态为新基线（补全内容后执行，用于关闭巡检告警）
+node scripts/doc-watch/check-updates.mjs --update
+```
+
+退出码：`0` 无变化 · `1` 有新增/变化 · `2` 抓取失败。
+
+## 工作机制
+
+1. Loomy 站点是 VitePress，HTML 里直接含侧边栏全部页面链接 → 自动发现页面清单，无需浏览器。
+2. 每页提取：标题、各级小节标题（h1–h4）、正文图片 URL（已绝对化，过滤站点 logo）、正文文本哈希。
+3. 与 `baseline/*.json` 对比，输出：🆕 新增页面 / ✏️ 内容变化（含新增小节、新增图片）/ 🗑️ 下线页面。
+4. 基线提交在仓库里；补全内容的 PR 顺带 `--update` 刷新基线，避免重复告警。
+
+## 两层自动化
+
+### 第一层：GitHub Actions（确定性巡检，已内置）
+
+`.github/workflows/doc-watch.yml` 每天 01:00 UTC（北京时间 09:00）运行脚本。发现变化时，
+自动维护**一条**带 `doc-watch` 标签的 Issue，列出新增页面 / 小节 / 图片 URL，供后续补全。
+免费、纯确定性，但不含联网搜索与自动起草。
+
+### 第二层：Claude 定时云 agent（联网搜索 + 自动起草 PR）
+
+确定性巡检之上，再用一个每日 Claude routine 完成「联网找新内容 + 抓图 + 起草 PR」。
+routine 的提示词如下（可直接用于 `/schedule` 或定时 agent）：
+
+```
+每天巡检本仓库的上游文档，发现并补全新内容：
+
+1. 运行 `node scripts/doc-watch/check-updates.mjs --report /tmp/doc-watch.md`，读取报告。
+2. 若报告显示有「新增页面 / 新增小节 / 新增图片」：
+   - 对每处新内容，抓取上游对应页面与配图（图片落到 docs/public/loomy/<区域>/ 或
+     docs/public/astronclaw/，本地引用而非外链）。
+   - 按现有页面风格写成中文页面，并补一份等价的英文页面（docs/ 与 docs/en/）。
+   - 需要时更新 docs/.vitepress/config.mts 的中英侧边栏。
+3. 此外，联网搜索 Loomy / 讯飞 AstronClaw 的近期官方更新（发布说明、新功能、新渠道、
+   新技能），判断是否有本站尚未覆盖、且适合补充的内容；有则一并补上并注明来源。
+4. 运行 `npm run docs:build` 确认死链检查通过、搜索索引重新生成。
+5. 运行 `node scripts/doc-watch/check-updates.mjs --update` 刷新基线。
+6. 新建分支并开 PR，标题 `docs: 同步上游文档新增内容 (<日期>)`，PR 描述列出每处新增的来源链接。
+   遵循仓库约定：提交与 PR 不得包含任何 AI 署名。
+   若本次无任何新增，则不创建 PR，仅留一句说明。
+```
+
+> 说明：联网搜索与「读懂新内容→翻译成双语页面→挑选配图」需要判断力，必须由带联网与
+> 写作能力的 agent 完成；纯 CI 只能做到确定性 diff + 告警。两层配合即可覆盖
+> 「抓取 + 对比 + 配图 + 联网补全」的完整需求。

scripts/doc-watch/baseline/astronclaw.json

@@ -0,0 +1,130 @@
+{
+  "source": "astronclaw",
+  "name": "AstronClaw 使用指南",
+  "pageCount": 1,
+  "pages": {
+    "https://www.xfyun.cn/doc/spark/Agent-AstronClaw%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97.html": {
+      "url": "https://www.xfyun.cn/doc/spark/Agent-AstronClaw%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97.html",
+      "title": "AstronClaw：你的云端 AI 助手，全天候在线服务 | 讯飞开放平台文档中心",
+      "headings": [
+        "h1:AstronClaw：你的云端 AI 助手，全天候在线服务",
+        "h2:目录",
+        "h2:AstronClaw核心优势",
+        "h2:AstronClaw对比本地OpenClaw",
+        "h2:如何使用AstronClaw",
+        "h3:第一步：立即部署",
+        "h3:第二步：开始对话",
+        "h3:第三步：安装技能",
+        "h3:第四步：配置消息渠道",
+        "h2:技能系统",
+        "h3:一、技能是什么",
+        "h3:二、技能如何获取",
+        "h4:1️⃣ 技能市场手动安装",
+        "h4:2️⃣ 对话自动安装",
+        "h3:三、技能如何被调用",
+        "h4:1️⃣ 自动调用",
+        "h4:2️⃣ 指定调用",
+        "h4:3️⃣ 多技能链式调用",
+        "h3:四、技能触发机制",
+        "h3:五、技能市场",
+        "h3:六、我的技能（管理）",
+        "h3:七、创建完成后的使用方式",
+        "h2:订阅与积分规则",
+        "h3:1.订阅套餐",
+        "h3:2.积分类型",
+        "h3:3.积分获取",
+        "h3:4.积分消耗",
+        "h3:5.积分抵扣顺序",
+        "h3:6.服务升级和降级",
+        "h3:7.促销优惠和新用户福利",
+        "h3:8.退款与异常处理规则",
+        "h3:9.常见Q&A",
+        "h2:常见问题",
+        "h3:一键部署需要什么条件？",
+        "h3:如果 AstronClaw 不响应怎么办？",
+        "h3:重启、重置、删除有什么区别？",
+        "h3:支持哪些文件上传？",
+        "h3:如何切换对话模型？",
+        "h3:AstronClaw 可以发送文件给我吗？",
+        "h2:实际应用场景",
+        "h3:1. 行业研报",
+        "h3:2. 资讯播客",
+        "h3:3. PPT 自动生成",
+        "h2:飞书渠道配置指南",
+        "h3:前置条件",
+        "h3:操作步骤",
+        "h4:步骤一：创建飞书应用",
+        "h4:步骤二：获取应用凭证",
+        "h4:步骤三：配置应用权限并启用机器人能力",
+        "h4:步骤四：配置事件订阅",
+        "h4:步骤五：发布飞书应用",
+        "h3:测试连接",
+        "h3:推荐使用场景",
+        "h2:钉钉渠道配置指南",
+        "h3:前置条件",
+        "h3:操作步骤",
+        "h4:步骤一：创建钉钉应用",
+        "h4:步骤二：为钉钉应用添加权限",
+        "h4:步骤三：配置钉钉机器人",
+        "h4:步骤四：发布应用版本",
+        "h4:步骤五：获取应用信息",
+        "h4:步骤六：在 AstronClaw 中完成配置",
+        "h2:企业微信渠道配置指南",
+        "h3:前置条件",
+        "h3:操作步骤方法一：",
+        "h4:步骤一：创建企业微信机器人",
+        "h4:步骤二：开启长连接",
+        "h4:步骤三：在 AstronClaw 中完成配置",
+        "h3:操作步骤方法二：",
+        "h4:步骤一：使用企业微信扫码创建机器人",
+        "h4:步骤二：点击自动创建",
+        "h2:微信渠道配置指南",
+        "h3:前置条件",
+        "h3:操作步骤",
+        "h4:步骤一：在AstronClaw中获取二维码",
+        "h4:步骤二：使用微信进行扫码",
+        "h3:添加多账号与解绑",
+        "h2:微博渠道配置指南",
+        "h3:操作步骤：",
+        "h4:步骤一：获取凭证",
+        "h4:步骤二：在 AstronClaw 中完成配置"
+      ],
+      "images": [
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/8f1df446-d2ad-4eb7-a203-2adb61c375ba.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/31652b25-be74-4572-bf34-05a9a2d719c9.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/78ebe6bc-d797-4cc1-afd8-9621714f09af.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/f39bdb4f-9749-410c-82d1-99d7649a683d.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/14db3e34-a75f-4683-b3a4-60abe51bc32b.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/7a15e0f8-f245-4fb5-a7fb-40b510dc3e77.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/0dc10451-5cbb-4a8a-b242-c60a22145d33.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/77875bfb-bae0-4724-948d-53e5b04b3b43.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-05-13/c01fe8e2-5fe0-49d4-a902-d29be5f89e2b.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/1f82fb01-c211-4925-9507-33dc1ff548d3.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-05-13/fa8e4356-126f-45fc-8e8a-168ff2a3116b.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-05-13/e876cf46-94a0-4b3b-8fde-1a27210a21dc.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/195ecb47-6373-4af7-bb68-eb75e45130c3.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-05-13/3cce905d-414d-463a-bb20-763a2274db55.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-05-13/f5216a9f-6ed6-433a-9968-83cad5e93ed7.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/360cda54-f0f3-454a-883d-93b9fb564a66.webp",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/7c71de39-0909-4178-9d19-a7e746e6328c.webp",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/62090a39-a0c5-4167-8d95-7e899b2ff3b3.webp",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/d59e4fa9-eee3-46e5-859b-cdf61599611c.webp",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/9d664481-5ceb-406f-9e78-06375eb9ac32.webp",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-12/67d8b161-46f0-408e-b6fa-3ff5ad06aadb.webp",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-13/2e0f9959-dee9-4b40-92ce-8df194d63f4d.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-13/6effe2f3-6cc0-49dc-b037-7b34ec8a5d68.jpg",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-13/2c5e217b-6129-4b7e-85b8-3f79f4e897e9.jpg",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-30/0efa8092-b8d4-4caf-9c5f-9c9adaa80cbc.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-30/ed272a6b-1952-4e81-beae-0dd92db65767.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-27/aa7fc599-f956-446f-aae6-28b00efbe39d.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-30/1fa6ca11-0d49-4e58-8697-ba20b974795c.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-30/dfc5292c-bdc7-4620-8de5-4ef3f41946b3.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-17/d4f8d3f0-4d65-4703-8ffd-2a0ac0e810df.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-17/d5d25f8b-ef51-4ad3-8b29-576f6f1821aa.png",
+        "https://bjcdn.openstorage.cn/aicontest/2026-03-17/88a48006-063e-4f2d-95df-d4eb949eb004.png"
+      ],
+      "textHash": "c155dc6f637fc84b",
+      "textLen": 9343
+    }
+  }
+}