feat: 新增外部条目上游健康检查与每周巡检工作流 (#188)

## 背景
外部条目只存上游指针,上游仓库被删除、分支被重写或技能目录移动时,客户端安装会静默失败,目前没有任何机制能发现(例如
`dingtalk-cli` 的上游已 404,见修复 PR)。

## 变更
- **`scripts/catalog/check_upstream_health.py`**:只读,逐个检查
`skills/`、`agents/`、`teams/` 下的 `entry.json`:
- 失效(退出码 1):`gone` 上游不存在 · `bad-branch` 分支不存在 · `bad-ref` 固定提交无法获取 ·
`bad-path` `source.path`、根 `SKILL.md` 或 children 路径在分支最新提交下缺失
- 提示:`unreachable` 网络错误(不等于失效)· `new-skill` 集合有未声明子技能(发现规则直接复用
`gen-collection-children.py` 的 `discover_children`,两者结论一致)· `outdated`
固定 ref 落后于分支 · `unpinned` 未锁定 ref
  - 只稀疏检出 `SKILL.md`,39 个条目本地全量运行约 12 秒
- **`scripts/catalog/test_check_upstream_health.py`**:9 个基于本地 Git
仓库的单测,已加入 `i18n-validate.yml`。
- **`.github/workflows/upstream-health.yml`**:每周一 01:23 UTC 运行(可手动触发),仅在
`desirecore/market` 运行:
- 报告写入 Job Summary,并维护唯一一个带 `upstream-health` 标签的
Issue:有待处理项时创建或更新,全部正常时评论并关闭
  - 有失效条目时任务标红
- 权限仅 `contents: read` + `issues: write`,**不改写任何目录文件**;修复与 `source.ref`
更新仍通过评审 PR(与固定 ref 的审查语义一致)
- README 中英文补充用法。

## 当前主干的检查结果
- 失效 1:`dingtalk-cli`(已有修复 PR)
- 未声明子技能 3:`khazix-skills`、`marketingskills`、`mattpocock-skills`
- 可更新 21 个,未锁定 1 个
- `amap-jsapi-skill`、`luckin-my-coffee` 在本地因代理显示 `unreachable`,需要 CI
环境确认

## 验证
```
uv run scripts/catalog/test_check_upstream_health.py   # Ran 9 tests OK
uv run scripts/catalog/check_upstream_health.py        # 如上
uv run scripts/i18n/validate-i18n.py                   # 0 error(s)
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_0191D9g1FhRQzEGTefUn6mTb

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Yige <a@wyr.me>
This commit is contained in:
mashagua
2026-09-26 16:13:14 +08:00
committed by GitHub
parent 4dbfd4c563
commit 6cd60a7141
6 changed files with 487 additions and 0 deletions

View File

@@ -209,6 +209,7 @@ uv run scripts/i18n/translate.py --check skills/web-access
uv run scripts/i18n/test_validate_i18n.py
uv run scripts/catalog/test_validate_catalog_metadata.py
uv run scripts/catalog/test_collection_generator.py
uv run scripts/catalog/test_check_upstream_health.py
```
传入技能路径只缩小技能正文的校验范围,市场级与 sidecar 检查仍会执行。应根据改动选择相关测试文件,而不是每次修改文档都运行全部测试。
@@ -221,10 +222,16 @@ uv run scripts/gen-collection-children.py --check
# 可选:在常规校验之外检查来源 URL 是否可访问。
uv run scripts/i18n/validate-i18n.py --online
# 检查所有外部条目:上游是否已删除、分支或固定提交是否失效、技能路径是否移动、
# 集合是否有未声明的子技能,以及是否有可同步的更新。
uv run scripts/catalog/check_upstream_health.py
```
集合检查需要 Git 和网络。可变来源集合会被报告并跳过,因为无法保证生成清单可复现。省略 `--check` 会进入写入模式;提交前应同时检查重新生成的子技能和对应 sidecar 事实。
上游健康检查只读,不改写条目;出现 `gone`、`bad-branch`、`bad-ref` 或 `bad-path` 时以非零状态退出。`unreachable` 表示网络错误,不等于确认失效。[上游健康工作流](.github/workflows/upstream-health.yml)每周运行一次,并维护唯一一个 `upstream-health` Issue;修复条目和更新 `source.ref` 仍需通过经过评审的 PR。
[校验工作流](.github/workflows/i18n-validate.yml)是 CI 行为的权威来源。它会检测相关路径,纯文档改动可能跳过目录校验。跳过后显示成功的任务,不代表 Markdown 链接或中英文文档已被检查;这些内容仍需单独审查。
## 安全与信任边界