技术调研

输入：一个甲方需求，常常只是三五句话。输出两份 Markdown：

• report.md —— 内部详细报告，带 文件:行 级证据，给自己和写代码的人看。
• 调研汇报.md —— 可交付的调研汇报文档，给项目组内与领导看：项目间横向对比、各候选优秀之处与缺点、值得借鉴的地方、整体设计、怎么实现。一次性交付，不留待办口吻。

外加两者引用的证据目录。

两份是详略之分，不是内容隔离：汇报稿的事实全部取自 report.md，可以与它重复——不必为了"不重复"而删内容。唯一禁止的是写入 report.md 里没有依据的判断。

三个落点，顺序固定：实现逻辑 → 可复现 → 可行。成本与工作量是判"可行"的要素之一，不单列成章。

候选以开源项目为主（GitHub 为主，Gitee 兜底）；商业 SDK 与官方产品只出现在兜底方案里。

路径约定

• 同目录素材直接按文件名读：DIG-BRIEF.md、REPORT-TEMPLATE.md、BRIEFING-TEMPLATE.md。这些是相对 SKILL.md 的文件名，不是 shell 路径。
• 脚本在 scripts/ 下，命令行里必须用绝对路径调：python <skill-dir>/scripts/repo_probe.py ...，其中 <skill-dir> 是本 skill 目录的绝对路径（由加载本 skill 的机制给出）。
• 派 subagent 前，把 brief 里的 <skill-dir> 换成本 skill 的真实绝对路径 —— subagent 不继承本 skill 的上下文，不会替你解析相对路径。

步骤

1. 需求解读 → 能力清单 + 定目录

把需求翻译成能力清单 C1..Cn：每条一个能被"是/否"回答的验收问法。这份清单是后面所有比对的锚点。

需求含糊是常态——甲方未必懂行，项目也可能还在讨论阶段。处理方式固定成三条：

• 甲方原文原样摘录：口径锚点，不改写、不润色。
• 你的解读、补全的假设单独写，与原文分开。
• 歧义进待确认清单，每条标注 影响选型 或 不影响选型。

歧义不阻塞调研：按最可能的解释继续往下走，标了 影响选型 的条目留到确认门单独列出，由用户决定是否回去问甲方。

本步同时把落盘位置定死，后续所有步骤都用它，中途不再改：

• <目录> = 当前项目仓库根的 docs/research/；不在任何仓库内时，用当前工作目录。用户指定则从用户。
• <YYYY-MM-DD> = 当天日期；<需求slug> = 需求的短横线英文或拼音标识。
• 证据根 = <目录>/<YYYY-MM-DD>-<需求slug>/。这个绝对路径要写进第 5 步每个 subagent 的 brief，别让它们自己猜或另起临时目录。

完成判据：每条 Ci 都有验收问法；原文与解读分离；每条歧义都标了是否影响选型；<目录>/<日期>-<slug>/ 已定下并把绝对路径记下来。

2. 宽搜候选（漏斗上口）

搜 5–8 个候选。宽搜便宜，深挖贵。

• 走采集脚本的搜索模式：python <skill-dir>/scripts/repo_probe.py search '<关键词>'（GitHub 侧有鉴权时额度更高）。按能力搜，不按需求原文搜：中文整句几乎必然返回空，用项目名或英文能力词（iot platform、device shadow、mqtt broker）才出结果。
• Gitee：搜索 API 已废（恒返回空数组），改用 web 搜索（site:gitee.com <关键词>）或用户给的 URL。拿到 URL 后 Gitee 的 API、raw、clone 都正常——发现环节难，取证环节不难。
• 国内同类实现单列一栏：投标与交付场合，它是真实信息。

证据落 <证据根>/evidence/_screening/<平台>-<owner>_<name>/——所有材料都在 <证据根> 底下，不要在 cwd 顶层另建 .probe-ev/、_probe/ 之类的目录。筛选期用完即弃；过了确认门的候选，把材料挪到 <证据根>/evidence/<候选slug>/，或重新跑一次脚本（便宜，且省掉搬迁逻辑）。

筛选期每个候选只跑一次脚本、只读 PROBE.md 与 meta.txt，不克隆、不读源码——那些是深挖（第 5 步）的事。候选多到扫不完时，先收敛到 5–8 个再扫，别把漏斗下口当上口用。

只有原始仓库进候选。 gitee.com/mirrors/*、Gitee 极速下载/* 这类转存镜像仓：元数据大面积失真（实测 mirrors/mosquitto 的描述挂在 libwebsockets 上、language 为空、Stars 只有上游的零头），且内容本身是滞后快照。镜像仓只用于确认「国内可达性」，不参与打分、不进矩阵、不下结论；国产项目的原生素材要用它在 Gitee 上的自有仓库，或它的 GitHub 上游。

完成判据：候选 ≥5，每个都有 URL 与一句话来源理由；不足 5 个要写清搜过哪些词、为什么少；候选里没有转存镜像仓。

3. 硬筛除 + 打分

先硬筛除（不满足即出局，仍记录理由），再打分排序，取 Top 2–3 进深挖。规则见下面「硬筛除与打分」。

完成判据：每个候选都有处置——要么一条筛除理由，要么一行分数，没有"待定"。

4. 确认门（停）

交付物是写进 report.md 的第 1、2 节，不是在对话里发一段清单——报告是唯一事实来源，这里的成果必须落盘：

• 第 1 节：需求原文摘录、能力清单、歧义与待确认清单（本步只补「影响选型」的标注）。
• 第 2 节：候选表、筛除记录、打分表、国内同类实现表填齐；结论词与置信度列留空并标「待深挖」。
• 头部状态栏写 状态：确认门。
• 对话里另附：建议深挖的 Top 2–3、建议升级到 跑 档的候选（附理由）、待确认清单里标了 影响选型 的条目。

用户点头前不进入深挖。跑 档不擅自开——有些仓库构建要装一堆环境，工期望。

完成判据：report.md 的第 1、2 节已按上面填到位；用户明确认可深挖范围与档位分配。

5. 并行深挖

参数模板用 DIG-BRIEF.md 里的那份，档位与命令清单也在那份文件里。

派 subagent 时必须把该文件里「候选卡契约」与「给 subagent 的 brief 模板」两节原样贴进 brief —— subagent 不继承本 skill 的上下文，读不到 DIG-BRIEF.md，没有契约定义它就自己编字段。

并发上限 4；超过 4 个候选时分批，先跑分数高的。

完成判据：每张卡都齐了档位成果——C1..Cn 各自有结论、实现逻辑节有 文件:行 引用（读 档为零条并说明依据）、没有"待补充"字样。

6. 写详细报告

按 REPORT-TEMPLATE.md 逐节填 report.md。结论词与置信度只能从下面两张表里选，不自创。

第 2 节在确认门已填过，此处补齐结论词与置信度列，并把国内同类实现的元数据核实一遍（这一节的表进汇报稿，不能失真）；第 3 节起是深挖后的新内容。头部状态栏改为 状态：深挖中。

完成判据：模板每一节都有实质内容；每个候选都有结论词 + 置信度；推荐节给出了首选、备选、兜底三档。

7. 写汇报稿

按 BRIEFING-TEMPLATE.md 写 调研汇报.md（与 report.md 同目录）。

这一份是可独立交付的完整文档，给项目组内与领导看：项目间横向对比、各候选的优秀之处与缺点、值得借鉴的地方、整体设计、怎么实现。

三条硬规矩：

• 事实全部取自 report.md，允许与它重复。 不必为了"不重复"而删内容——那会产出一份缺事实的薄稿。不新增 report.md 里没有依据的判断。
• 删减边界只到实现级：删掉文件名、行号、类名、函数名、配置项名、命令行、clone 路径、代码行数；机制、顺序、数值、结论、风险、许可证义务一律保留。判断标准是"能不能描述一套做法"——能就留，只"指到代码某个位置"才删。两类易误判：「代码行数」删，「文件体积/文件数/内存占用」留；「日志字段名」留，GCONFIG_xxx 这类内部常量名删。
• 一次性交付，不留待办口吻：不写"下一步""请决策""建议立项"。收束章写的是结论与产物形态。
• 内部口径不进交付文档：能力清单编号（C1..Cn）、结论词、置信度、档位、候选 slug 一律删掉，换成人话与证据本身（详见模板 1.1 后的对照表）。

两份文档冲突时以 report.md 为准，并回头修汇报稿。

完成判据：模板每一节都有实质内容；通篇没有 文件:行、命令、配置项名、C1..Cn、结论词、置信度、档位；每个候选都有「能否直接使用」与一句话评价，且四个小节（技术实现方式 / 能力覆盖情况 / 可行性与局限）齐全；逐个候选与 report.md 的事实逐条一致；成品里没有残留的 < > 占位符与模板说明句。

8. 落盘

<目录>/<YYYY-MM-DD>-<需求slug>/
├── report.md          # 内部详细报告
├── 调研汇报.md         # 可交付汇报文档
└── evidence/          # 证据
    ├── <候选slug>/    # 形如 github-owner_name
    └── _screening/    # 筛选期材料，用完可删

落盘后把两份文档的绝对路径和证据目录打给用户。

完成判据：两份文档与证据都已在磁盘上，路径已报出；report.md 头部状态栏已更新为「完成」。

结论词与置信度

置信度只由取证档位决定，不许手动升格：

硬筛除与打分

硬筛除（任一条命中即出局，理由仍写进报告）：

• 需求核心能力明确缺失。
• 许可证与交付形态冲突（例如甲方要闭源交付，而项目是 AGPL/GPL 且无商业授权）。
• 已停止维护，且没有接手的活跃分支。
• 语言栈与团队完全无法承接。
• 转存镜像仓而非项目原始仓库（见第 2 步）。

打分（满分 100，决定深挖顺序）：

信创、离线内网、国产化数据库/中间件这类约束，若需求提到，计入「可复现度」的判定要点，不单列维度。

纪律

• 每个技术判断都能追到 文件:行、官方文档或命令输出；追不到的就写进「未实证假设」。
• 元数据不可信时回落到文件：gh search 与 gh repo view 的 license 字段常为空或 other，许可证以克隆后的 LICENSE 文件为准。Gitee 转存镜像仓的整套元数据都不可信。
• 没实跑就说没实跑，应该可以跑通 不算结论。
• 只读文档得出的判断就是 低 置信度，不要升格。
• 克隆默认用完即删，但先记下 git rev-parse HEAD：证据里存 SHA + 摘录，克隆随时可按 SHA 重取。

素材

• DIG-BRIEF.md — 深挖 subagent 的 brief 模板、候选卡契约、读/挖/跑 三档命令清单。进入第 5 步时读；派 subagent 时把「候选卡契约」与「brief 模板」两节贴进 brief。
• REPORT-TEMPLATE.md — 详细报告骨架。进入第 6 步时读。
• BRIEFING-TEMPLATE.md — 可交付汇报文档骨架（含删减边界）。进入第 7 步时读。
• scripts/repo_probe.py — 采集候选仓库元数据（GitHub 与 Gitee 同一入口，只用标准库）。第 2、5 步用，须用绝对路径调用。