repo-capability-insight

name	repo-capability-insight
description	并行研究一个或多个 GitHub、GitCode 或本地代码仓，基于源码、CodeGraph、仓内文档、模型脚本、已合入 PR/MR 和官方网站构建全量能力证据库，并为每个仓生成模型、算法、优化特性地图、三张 PNG 一图流与需求洞察报告。用于代码仓能力盘点、跨仓对比、模型与算法支持矩阵、模型专项优化与已合入 PR 分析、竞争力分析、需求洞察或可大规模推广特性识别。

仓库全量能力洞察

交付目标

对每个目标仓生成以下文件：

report/<代码仓名>/
├── map.md
├── todo.md
├── model.png
├── alg.png
└── features.png

把用户给出的输出目录视为“输出仓根目录”，始终在其下追加 report/<代码仓名>/；除非用户明确给出的路径已经是 report/。

将事实、推断和未知项分开表达。宁可记录“未发现/待核验”及已检查范围，也不要补写无证据结论。

开始前

1. 完整阅读 references/report-schema.md，严格采用字段、分类和评分标准。
2. 涉及远程仓、多个仓或不熟悉的仓时，完整阅读 references/research-methods.md。
3. 生成一图流前完整阅读 references/diagram-guide.md。
4. 检查工作区中的 AGENTS.md、已有报告和未提交改动，保留用户内容。
5. 用脚手架创建缺失报告；已有报告默认只增量更新：

python3 <skill-dir>/scripts/scaffold_reports.py \
  --workspace <输出仓根目录> \
  --repo <代码仓名> \
  --source-url <仓库URL> \
  --commit <完整提交SHA>

调研流程

1. 固定分析基线

• 规范化每个仓的名称、URL、本地路径、主分支、完整提交 SHA 和分析日期。
• 同名仓使用 <owner>--<repo> 作为报告目录名，并在元数据中保留原名。
• 远程仓下载到临时或缓存目录，不把仓库副本、凭据、CodeGraph 索引提交到输出仓。
• 优先分析固定 SHA；若分析分支动态内容，明确写出结论可能随分支变化。

2. 强制并行分工

• 有两个及以上目标仓时，必须启动子代理并行研究；默认每仓一个子代理。
• 只有一个大型仓时，若存在可独立研究的模型、算法、优化特性三个维度，也应分别交给子代理并行。“大型”指满足任一条件：跟踪的源码/配置/文档超过 500 个文件、存在 3 个以上独立后端、三个维度均有独立目录，或单代理无法在一次上下文中可靠覆盖。
• 主代理始终负责基线固定、任务边界、交叉去重、证据复核、最终报告和图片，不把整项任务完全转交。
• 子代理只返回带来源 URL、文件位置和提交 SHA 的证据表，不直接给出无依据总结。
• 并发槽不足时分波执行：先“模型/算法”，再“优化特性/官网与案例”；不要降低覆盖范围。

3. 建立证据清单

按以下顺序调查，详细操作遵循 references/research-methods.md：

1. 仓内约束：AGENTS.md、贡献指南、版本和发布说明。
2. 总览文档：README、docs/、ai/、官网文档和官方博客。
3. 使用入口：examples、recipes、scripts、train/infer/eval/launch 脚本和配置。
4. 实现证据：模型注册、算法入口、后端适配、调度器、算子与测试。
5. CodeGraph：仓库有 .codegraph/ 时先用 CodeGraph；可安全建立索引时再索引，否则结合 rg、调用链阅读和 Git 历史补齐。
6. 已合入 PR/MR：分页扫描目标分支在基线前已合入的记录，从标题、标签、改动路径和描述筛选模型专项优化，再深读 diff、benchmark、评审讨论、测试和当前代码存续状态。
7. 官方外部证据：官方网站、官方仓库、官方案例和发布说明；网页信息注明访问日期。

只有合入提交可从固定基线到达、未被回退且当前实现仍存在的 PR，才能作为当前能力证据。仅有规划、Issue、未合入 PR 或晚于基线的合入记录不得写成已支持。每条能力至少记录“声称支持”和“实现/脚本证据”之一。

4. 生成全量特性地图

• 在 map.md 中完整列出模型、算法、优化特性三张主表。
• 模型维度覆盖具体名称、参数规模、输入/输出模态、支持算法、GPU/NPU、脚本与文档 URL。
• 算法维度主动核查 SFT、LoRA、GRPO、PPO、OPD 及仓内其他算法，记录数据集模态、支持模型和案例 URL。
• 优化特性按“推理、训练/FSDP、训练/Megatron、调度”分类，再按“并行、资源节约、极致性能”分类；额外记录模型专项触发条件和相关已合入 PR URL。
• 迁移工作量给出代码行区间、涉及文件数、测试/配置工作和估算依据；不得伪造精确值。
• 所有源码链接优先使用固定提交 SHA 的永久 URL。每一行至少附一个可访问 URL；无公开 URL 时解释访问限制并给出仓内相对位置。

5. 生成三张一图流

• model.png：输入/输出模态 → 模型族 → 规模 → 算法与硬件支持。
• alg.png：训练范式 → 算法 → 数据模态 → 支持模型 → 典型案例。
• features.png：推理/训练后端/调度 → 并行/资源节约/极致性能 → 模型专项触发条件 → 机制、收益和范围。
• 图片必须忠实映射 map.md，不得加入表中没有的能力。
• 生成后用图像查看工具逐张检查清晰度、裁切、文字和层级；不合格时重绘。

6. 生成需求洞察报告

• 从特性地图中筛选“不常见、已有有效性证据、适用范围广”的能力，不把普通基线能力列为推广重点。
• 对照其他目标仓、同类主流仓和官方资料判断稀缺性；对照 benchmark、实验、案例或实现机制判断有效性。
• 按 references/report-schema.md 评分。证据强度不足的候选进入“验证池”，不得直接列为大规模推广项。
• 在 todo.md 中给出候选、目标场景、迁移工作量、风险、试点步骤、验收指标和推广顺序。

7. 汇总与验收

• 交叉核对文档声称与源码现实，合并别名，消除重复特性。
• 检查遗漏：模型注册表、训练配置、推理入口、后端目录、调度器、算子、测试、release notes，以及基线前已合入 PR/MR 中的模型专项优化候选。
• 运行校验脚本：

python3 <skill-dir>/scripts/validate_reports.py <输出仓根目录> --repo <代码仓名>

• 修复全部错误后才宣布完成。警告项必须在报告的“覆盖范围与缺口”或“风险与待验证项”中解释。

完成门槛

• 每仓五个文件全部存在，三张图片均为清晰有效的 PNG。
• 表格字段齐全，每个事实行均有证据 URL 或明确的非公开来源说明。
• 模型、算法、优化特性均包含已检查范围和未覆盖项。
• 已记录已合入 PR/MR 的扫描范围、候选数量、深读数量、访问限制，并核验相关合入提交在基线可达且未回退。
• todo.md 中每个推广候选均能追溯到 map.md，并包含量化评分与可执行验证计划。
• 报告不含占位符、凭据、无法区分的推测或与固定提交不一致的链接。