requirement-to-path
从模糊需求出发,定位 GitHub 上整块匹配的成熟模块(发现与核验走 github 连接器的 MCP 工具),深读代码提取事实并裁决优缺点,反推带验证信号的分步实现路径。触发词:帮我实现某个功能/模块、有没有开源项目可以参考、别人是怎么做这个模块的、需求很模糊想落地成方案。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/zxd15978684198--requirement-to-path)HTML
<a href="/listings/zxd15978684198--requirement-to-path"><img src="/api/listings/zxd15978684198--requirement-to-path/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
前置条件(硬性,不是可选项)
本 skill **强依赖 `github` 连接器**(MCP server)。所有检索与读码都走它的工具:
`search_repositories` · `search_code` · `get_file_contents` · `pull_request_read` · `search_issues`
不自研检索脚本——鉴权托管、限流额度高(未认证直连只有 10 次/分钟)、随官方 server 升级零维护。连接器不可用时会走降级路径,并在交付文档里**显式标注候选质量下降**。
把这个连接器配上
需要做到的事只有一件:让你的 agent 能调到上面那 5 个工具。两条路,任选其一。
**A. 用官方托管端点(最省事)**。GitHub 自己有托管的 MCP server,用 PAT 作为 Bearer 鉴权:
{
"mcpServers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer <你的 PAT>" }
}
}
}把这段放进客户端的 MCP 配置即可:Claude Desktop / Cursor 各有自己的配置文件;DSH 走 MCP 连接器面板的「导入 JSON」。
**B. 本地跑官方 server**。
docker run -i --rm \ -e GITHUB_PERSONAL_ACCESS_TOKEN=<你的 PAT> \ ghcr.io/github/github-mcp-server
在客户端里把这条命令注册成 `stdio` 类型的 server。不想用 Docker,也可以从 [`github/github-mcp-server`](https://github.com/github/github-mcp-server) 下二进制。
**PAT 权限按需最小化**。只读公开仓库时,fine-grained token 一个权限都不勾也能用;要读私有仓库,就给对应的那几个仓库 `Contents: Read`。本 skill 全程只读:不写、不开 PR、不发评论。
**接好之后怎么确认**。问一句「你现在能调到哪些 github 工具」,看有没有 `search_repositories`、`search_code`、`get_file_contents`、`pull_request_read`、`search_issues` 这 5 个。
**只暴露了一部分会怎样**。缺 `search_code`:定位阶段退化成只用仓库搜索,候选质量下降;缺 `get_file_contents`:读不到代码,「深读代码提取事实」这一整层失效。这两种情况都会在交付文档里显式标注为降级。
全程不需要 `gh` CLI,也不会调用任何 shell 命令。
Claude Code
git clone https://github.com/zxd15978684198/requirement-to-path.git \ ~/.claude/skills/requirement-to-path
之后在会话里说「**帮我实现 XXX**」或「**有没有开源项目可以参考**」即可触发。
DeepSeek Harness (DSH)
把整个目录放进 `DSH_HOME/skills/requirement-to-path/`,确保 `SKILL.md` 位于该目录根。
其他工具(Cursor / Codex / Gemini CLI / 自建 agent)
本 skill **不绑定任何运行时**:全是 Markdown + 一个只依赖标准库的 Python 脚本。把 `SKILL.md` 作为指令文件喂给你的 agent、把 `references/` 放在它能读到的位置即可。
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 198 lines
- ---
- name: requirement-to-path
- description: 从模糊需求出发,定位 GitHub 上整块匹配的成熟模块(发现与核验走 github 连接器的 MCP 工具),深读代码提取事实并裁决优缺点,反推带验证信号的分步实现路径。触发词:帮我实现某个功能/模块、有没有开源项目可以参考、别人是怎么做这个模块的、需求很模糊想落地成方案。
- agent_created: true
- version: 1.60.8
- last_updated: 2026-10-19
- ---
- # 需求 → 对标 → 路径重构
- > **版本**:见 frontmatter `version:` | **完整账本**见 `references/verification-log.md`。**本行不写版本号与账本区间端点**:值只许出现在唯一权威处——同值写两处、改一处漏另一处,是本 skill 历次翻车的唯一根因。
- >
- > **改本文件前必读 `references/maintainer-notes.md`**(声明唯一性表 + 两条维护纪律:正文不写会随改版变化的值;改完立刻跑 `--skill`)。跑需求的 agent 不需要读它。
- 从一句模糊需求出发,找到 GitHub 上**整块匹配**的成熟模块,读码提取事实、裁决优缺点,反推一条**可照着施工**的实现路径。
- **GitHub 检索一律走 `github` 连接器**(MCP 工具),不自研搜索脚本——见 [L1.0](#l10-前置接通-github-连接器硬前置)。
- ## 适用性判断(先做这一步)
- | 情况 | 处理 |
- | --- | --- |
- | 需求模糊——只有一句话、缺关键决策 | 走完整流程 |
- | 需求已明确,只想立项开工 | **不用本 skill** → `spec-development` |
- | 已有方案,只想压测它站不站得住 | **不用本 skill** → `grill-me` |
- | 只想讨论方案、不需要找对标 | 直接讨论,不走本流程 |
- | **需求明显不会有开源对标**(内部业务逻辑、私有系统) | **开工前就告知**,走 0 候选降级③/④,别耗满轮次(上限见「已知限制」2) |
- > 最后一条是**预判**:核心是「某家公司/系统内部的规则」而非「通用机制」。
- ## 流程总览
- **流程**:L0 三道门禁 → L1 定位 → L2 提取 → 门禁 4 裁决 → L3 分步路径;流程图见 `references/pipeline.md` §一。
- **执行序列 11 步**(按序走,每步输入与产出都写死):适用性判断 → 门禁 1 → L1.0 接通 → L1 半程 → 门禁 2 → 门禁 3 → L1 全程 → L2 提取 → 门禁 4 → L3 重构 → **交付前自检(必跑 `references/self_check.py`、贴输出与退出码;没跑=没交付)**;逐行表见 `references/pipeline.md` §二。
- > ⚠️ **上表是「做什么的先后」,不是「何时开始落盘」**:交付文档**从第 1 步起笔**(读完需求先建文件写 §0,每写完一节立刻写盘)——**半份能读的交付物远好过零份**。原文与两次回流见 `references/pipeline.md` §二附。
- ## 门禁通则(各道门禁共用)
- 1. 每道门禁必须产出**明确的产出物**(文档/清单/表),让用户审阅产出物,**不答开放式问题**;
- 2. 门禁是**硬阻断**:未放行不得进入下一层;
- 3. 用户改答后**必须重跑一致性检查**;未解决项只能以 `[假设]` 显式记录,不得静默通过;
- 4. **闸点标记不许跳过**:放行处标 `🛑 STOP`(停下等显式放行),需自查处标 `🔴 CHECKPOINT`;**不许为推进而自行放行**。
- ### 统一标注(不得混用、不得自造)
- `[代码可读]` 直接可见,必须给文件位置 | `[测试可证]` 有测试覆盖,指出测试函数 | `[推断]` 推测,**必须给验证方法**(以上三者用于 L2 事实表)| `[假设]` 未确认、暂时按此执行(门禁 1–4)| `[待确认]` 需用户裁决(一致性检查)| `[实测-稳定/单次]` 本 skill 自身实测结论的置信度(references 内)。
- ## L0 需求澄清
- > **输入信息量决定产出重心**:需求自带详尽规格 → 重心是「验证与补充」;只有一句话 → 重心才是「澄清」。两种都要走门禁,**不许因为材料多就跳过**。
- **交互硬要求**:**必须用弹窗呈现,禁止把问题写成正文列表**——一弹窗 1–4 题、每题 2–4 选项(开放题改选择题)、显示「第 N / M 题」、**每题标它服务哪道门禁**。细则见 `references/l0-question-bank.md` §六。
- ### L0 段门禁(门禁 1–3)
- **门 1 → 痛点清单**(现象/触发条件/现在怎么绕/量级;每条带 `[假设]`)|**门 2 → 方案决策表**(带痛点去 L1 找候选做法,回来问「A 做法 vs B 做法选哪个」;选项/代价/推荐与理由)|**门 3 → 需求规格**(做什么、**明确不做什么**、验收标准、约束前提,含 `[假设]` 条目)。逐列问法与呈现要求见 `references/l0-question-bank.md` §十四。
- > **门禁 1 之前先判「需求所在的系统是不是就在手边」**——四条判据、本地优先取证顺序、何时才需要去 GitHub,见 §十二——**工作区里的代码就是最强的来源**。
- **L0 与 L1 之间存在回流**:门 2 要候选方案当输入,而候选来自 L1 的搜索能力。实际顺序:
- ```
- 门禁1 → L1.0 接通连接器 → L1 半程(找候选做法)→ 门禁2 → 门禁3 → L1 全程(找最终对标模块)→ …
- ```
- **必须执行,否则门禁 2 悬空**;本地有代码时**先读本地检索入口、权限过滤、写入路径**再去搜。
- **需求方不可达时**(需求来自公开 issue/论坛帖/文档):**不许**跳过 L0 直接开搜,四个门禁各自的降级做法见 §十一。
- **提问语言规范 / 止损规则 / 一致性检查**:**门 2 之前只用需求方语言,禁止方案术语**(实测:用方案语言问,用户答「不太明白」,该题作废);模糊需求里唯一确定的是**痛点**,从痛点问起。话术与检查点见 §四/§五。**总问题数达 12 问(硬上限,不许放宽;本行是该数值的唯一权威处)** → **必须**停止提问、强制收敛到门禁 3;未确认项标 `[假设]` 显式列出。
- ## L1 定位
- ### L1.0 前置:接通 GitHub 连接器(硬前置)
- **加载方式**:接通 `github` 连接器即可调用其 MCP 工具;本环境工具名带前缀(`mcp__github__*`),下文写短名,参数与官方一致。**为什么必须走连接器**:鉴权托管、限流额度高(自研未认证仅 10 次/分钟)、零维护——见 `references/l1-search-recipes.md` §零。
- **工具映射表**(L1、L2 只用这些工具;完整 8 行表见 §九,**别凭记忆选**):反查 `search_code` + 加引号机制短语 + `repo:`;直搜 `search_repositories` 必须 `minimal_output: false`;核验「已实现」看 `pull_request_read` 的 `merged`;`search_issues` 必带 `owner`+`repo`。
- **先探活**:将用到的每个工具各测一次,别只测一个就假定全通;最小调用见 §零,失败按下一节处置。
- ### L1.0-fallback 连接器不可用(详见 `references/l1-search-recipes.md` §六)
- **先判「半通」还是「全断」**:工具面未注册但资源面能列能读(`ListMcpResources`/`ReadMcpResource`)→ **半通,先不降级**;三条通道同时不可用才走终止分支。**不许退回自研脚本**。
- ### 模型型组件的第二搜索面(HuggingFace)
- **触发**:子机制是模型能力(识别/检测/标注/分类/预训练模型)——GitHub 搜码对这类组件**漏召回**,漏斗天然半盲。**做法**:`WebFetch` 打 `https://huggingface.co/api/models?search=<≤2 词机制词>&sort=downloads&direction=-1&limit=10`(长短语命中率低);官方域名实测不可达 → 走镜像 `https://hf-mirror.com/api/models?…`(镜像缺 `lastModified`,活跃度改读 `createdAt`)。配方见 §八。
- ### 漏斗七步(第 0 步先判需求形状)
- **第 0 步:判断需求形状**——**整块匹配型**(需求本身是一件事,如「向量库增量同步」)直接进第 1 步;**组合型任务**(如「竖排古籍→横排+标点+坐标对照」= OCR + 标点 + 版面分析)**先拆子机制,每个各走一遍漏斗**,最后在门禁 4 汇总。**形状判据与深挖配额见 §十**;**深挖 2–3 个子机制**,挑争议最大与完全没做过的,其余只到 L1 定位、不读码。
- 1. **关键词构造**——**动词短语 + 机制名词**,禁用领域名;3–5 组、**≤3 词**、`stars:>=100`。见 §一。
- 2. **捞候选——直搜为主;反查不是发现路径**:发现靠 `search_repositories`(`minimal_output: false`);`search_code` 只在带 `repo:` 时核验。见 §零、§一 1-C。
- 3. **结果分类**——完整模块(🎯 目标)/**参考实现库(📐 读设计抄模式)**/框架(❌)/教程(📎)/平台(❌)。见 §二。
- 4. **匹配度矩阵**——逐项打勾;**缺口清单比匹配分数重要**。见 §三。
- 5. **元信息与成熟度**——全来自连接器,**两维分开报**。见 §四。
- 6. **代码级验证**——`search_code` 带 `repo:` 定位文件,再 `get_file_contents` 读原文;**只读 README 不算数**(实测两条结论读码后被推翻)。见 §五。
- 7. **交付**——进入门禁 4。
- ### 找不到对标时怎么办(0 候选处置)
- 搜索轮次达上限后匹配矩阵仍为空(或只剩教程类)→ 触发本降级,**按顺序走,不许跳级硬凑**。**与第 0 步的分工**:第 0 步**主动**判形状;本降级是**被动**兜底(起初判整块型、搜完才发现是组合型)。级别定义与 ①–④ 的动作见 §十一。
- ## L2 提取
- **四步走:入口主流程 → 数据结构 → 接口契约 → 测试文件**,每步有停手条件,逐行表见 `references/l2-extraction-protocol.md` §六。**第 4 步必须记「它没断言什么」**(盲区)。
- **读取手段**:`get_file_contents` 逐文件读;位置不定时先 `search_code`(机制短语**加引号** + `repo:`)。**产出格式**:每条结论 = 「它怎么做」+「与我的方案差在哪」+ 代码位置,按统一标注打标——**禁止把推断写成事实**。**优先级**:安全边界类最高——跑时不报错、事后才发现丢数据的那类。
- ## 门禁 4 对标裁决
- 对标模块与需求**必然存在差异**,路径重构前必须先裁决。**需求方不可达时** → 三件套(天花板块照旧给理由+备选,其余打包「默认采纳」,交付文档首行写不可达声明)。细则见 `references/gate4-adjudication.md`。
- **产出物 ①:优缺点三分类**——✅ 优于原计划 → 照抄;⚠️ 能用但需改造 → 改造后采纳;❌ 缺陷 → 自己补。
- **产出物 ②:待裁决项清单**——**分级征询**:影响天花板的条目逐条问(给理由+备选),其余打包「默认采纳」**显式列出**、不反对即通过——**清单必须完整可见,不许静默略过**。两张表的区分与冲突处置三步见 `references/gate4-adjudication.md`。
- 🛑 STOP:清单每条都闭合之前,不得进入 L3——**未闭合条目只能标 `[假设]` 并显式列给用户**,不许自行拍板。
- 🔴 CHECKPOINT:进 L3 前复查一次,每条裁决是否都能追溯到 L2 的某段代码或某个坑。产出即 L3 的直接输入(最终设计决策表)。
- ## L3 路径重构
- **每步必须包含三件套**:**指令模板**(可复制的提示词,含"明确不要做什么")/**通过信号**(必须跑出来的输出;**三条附加要求:①可判;②在目标项目现有测试栈里跑得起来;③贴得出真实输出**)/**翻车信号**(出现什么说明走错了 + 处置)。规格见 `references/l3-mode-map.md` §十三。
- **每步标注开发模式**:TDD / Spec / 场景测试,判据与阶段映射见 `references/l3-mode-map.md`。**每步都要能追溯到「L0 的某条裁决」或「L2 的某段代码/某个坑」,禁止无来源步骤**(否则退化为事后合理化)。
- 第 7 节(分步实现路径)**每步带来源列**,取值域封闭、不得自造:
- | 来源标签 | 含义 |
- | --- | --- |
- | **本地文件行号** `path/to/file.py:88`(或`:L12-L30`) | 「门禁 1 之前先读本地代码」的产出落点。**必须带行号或行区间**(裸文件名不可核);扩展名限 `py/md/json/toml/sql/yml/yaml/ini/cfg/txt/env/ts/tsx/js/jsx`(与 `references/self_check.py` 的 `_LOCAL_EVIDENCE` 逐项一致);其余标签与 `cfg`/`txt`/`.env` 的来历见 `references/l3-mode-map.md` §七 |
- **填不出来源的步骤,删除它**——不要补一个勉强的出处;同一来源可被多步引用。
- > **来源格与编号的写法**:`| 步骤 | 来源 |` 的单元格**只放标签,不放说明**(夹带说明会被判违规);否则它**要么被读成标签、要么被悄悄丢掉,两种都不该发生**。编号算「已定义」只有两种形态:①**以它为首格的表行**;②行内定义行(「`L0-P1`:…」)。**封闭域收口**:合法标签的唯一事实来源是 `references/self_check.py` 的 `ALLOWED_SOURCE_PATTERNS`,本文件的枚举只作说明。退出码:`0` 放行/`1` 有硬违规/`2` 有未核项/`64` 用法错误——**`0` 只意味着「脚本没查到问题」**,射程见 `references/delivery-checklist.md` §三、§四。
- **文档结构:0 定位与档位 → 1 业务叙事 → 2 决策表+依据 → 3 量级 → 4 契约 → 5 对标结论 → 6 模块全景 → 7 分步路径 → 8 验收 → 9 已知限制**(逐节规格见 `references/l3-mode-map.md` §十四)。
- > **本行是章节编号的唯一来源**:「第 N 节/§N」一律指本行编号,不许另立第二套(v1.18.3 曾并存三套,根因是「文档结构」写在多处,见 §6.1)。**两处不独立成章**:对标改动并入第 2 节「决策依据」;`K<n>` 坑清单不单列(原位引用 + 附录纯编号索引)。**§0 必须写清层级与档位**,否则会被用错尺子量。
- > **落盘时序(v1.56.18:三次盲跑换来的硬规矩)——§0 先落盘,再进 L1 搜索。** 来历与四条动作见 `references/l3-mode-map.md` §九 与 §6.3;**先落盘的是骨架,不是完整的 §0**。**本行是 `probe_skillref.py` 的锚点,不许改**。
- > **体量用质性判据,不设行数上限**:①**读者能否一次读完**并找到要点;②文档里**有没有出现本不该出现的东西**(实测记录、自证、版本对照这类过程噪音);③同类交付是否**持续变长**(看趋势,不看单份)。撤阈值见 §6.4。
- **叙事线硬约束**:
- > **冻结机制**:本组硬约束**全部列于下,数量即本列表长度**。新增一条必须同时**合并或删除**一条旧约束,禁止只增不减。14 条合并为 9 条的来历与旧→新编号映射见 `references/l3-mode-map.md` §十 与 `references/verification-log.md`。
- 1. **必须从一句模糊需求出发**——即使走富信息路径,开头也要展示原始模糊需求原话 + 缺哪些决策 + 为何转向验证。(§十二.1)
- 2. **两章前置:业务实现叙事章 + 模块全景**(面向读者,整块一章不是小结,模块全景先行)。(§十二.2)
- 3. **交付文档与服务者账本分离**——过程记录一律归 `references/verification-log.md`,**不进交付文档**。(§十二.3)
- 4. **标注与表达规范:数字、公式、术语**(旧 ⑩+⑪ 合并)——根因:**模型的严谨性按「内容难度」分配,而不是按「重要性」分配**。**全文/所有数字**都要带标记;本表数字均带四类标记([实测]/[假设]/[外源]/[推导]);编码完成后须回填者见 §9.1。(§十二.4)
- 5. **论断必须可核查、可被质疑:契约配断言,设计配反向边界**。(§十二.5)
- 6. **决策必须带意图链**——「要什么 → 备选 → 权衡 → 推荐与理由 → 放弃的代价」,代价必须显式写。(§十二.6)
- 7. **对标必须附链接 + 逐仓库取舍**——每个仓库给链接,写「为什么参考+为什么不全抄」。(§十二.7)
- 8. **交付文档必须自洽:内部交叉引用逐对闭合**——交付前按 `references/delivery-checklist.md` §一 的 ⑭ 矩阵逐对核验。(§十二.8)
- 9. **施工路径的写法:三件套 + 提示词可复制 + 步骤从数据流反推**。(§十二.9)
- 🛑 STOP:交付前逐条核对第 8 节验收清单——每条都必须带可观察证据,**「看起来对」不算证据**。
- ## 资源清单
- | 资源 | 何时加载/使用 |
- | --- | --- |
- | **`github` 连接器** | **L1.0 硬前置**:接通后才能用 `search_repositories`/`search_code`/`get_file_contents`;**不内置自研检索脚本** |
- | `references/l0-question-bank.md` | ⚠ **按节读取**(进入 L0 提问前):必读 §一、§四、§五、§十四;再按域读 §二 或 §三 的一类 |
- | `references/l1-search-recipes.md` | ⚠ **按节读取**(进入 L1 搜索前):主链 §零→§一→§二→§三→§四→§五→§七;按需 §六、§八–§十一 |
- | `references/l2-extraction-protocol.md` | ⚠ **强制前置读取**(进入 L2 读码前,整读) |
- | `references/l3-mode-map.md` | ⚠ **强制前置读取**(进入 L3 重构前,整读):模式判据、三件套规格、§五–§十四 细则 |
- | `references/gate4-adjudication.md` | ⚠ **强制前置读取**(进入门禁 4 前):不可达形态、与门禁 2 的区分、冲突处置三步 |
- | `references/delivery-checklist.md` | **交付前必读**:§一 ⑭ 引用关系矩阵、§二 自检清单、§三 脚本射程、§四 机械举证与容易读错的绿灯 |
- | `references/self_check.py` | **交付前必跑**:**十三项机械自检 + 一项提示项**;非交付物可在前 2000 字符内写 `<!-- self_check: genre=reference -->` 跳过交付物专属项 |
- | `references/verification-log.md` | **按需查**,不参与执行:完整账本、未验证分支、环境依赖 |
- | `references/pipeline.md` | **按需查**:流程图、11 步执行序列表、落盘时序提醒原文 |
- | `examples/full-walkthrough.md` | 看一遍端到端产出形态 |
- | `.eval/` | 实测证据,执行时不加载 |
- | `evals/` | 六题 + `harness.py`;`python evals/harness.py --case NN --doc <文档> --root <项目根>`。**机械分是必要条件不是充分条件**,分数必须连命令一起记 |
- > **Windows/PowerShell 跑自检的两个坑**:①控制台默认 GBK,中文输出乱码——先设 `$env:PYTHONIOENCODING="utf-8"`;②**别用内联 `python -c "多行代码"`**(反引号会被 PowerShell 当转义符)——多行写临时 `.py`。
- ## 执行后自检清单(交付前硬核对)
- > 交付前逐项打勾,**任何一项不过不得交付**。机械部分最低举证=跑脚本并贴输出与退出码——**没有脚本输出现场 = 没跑**。但**退出码 `0` 只等于「机械项没查出问题」**,不等于清单打勾完毕。清单表体、两个容易读错的绿灯(`--skill` 不是能力证明;`[实测]`/`[外源]` 的出处必须真能核,核不到报 ⚠️ 未核而非违规)、证据根声明(施工在副本时原项目与副本都要声明)见 `references/delivery-checklist.md` §二、§四。
- ## 验证记录(已外移,见 `references/verification-log.md`)
- > 完整账本、**未验证的分支**(🔴 会卡死流程/🟡 仅降低质量)、已实测部分、环境依赖(HF 官方域名不可达、须走镜像,镜像可用性不由本 skill 保证)都在 `references/verification-log.md`。**设计 ≠ 验证**:当卡点对待,卡住如实告知用户。
- ## 已知限制
- 1. **"用户答不出"的分支尚未实测**——需求方即项目 owner 时止损规则不会被触发;替不懂技术的别人做需求时留意。本 skill 不做代码实现,L3 产出交给 `spec-development` 执行。
- 2. **搜索轮次硬上限 3 轮**——满 3 轮**必须**把已有候选摆给用户裁决,**不得**自行死磕;**本行是该数值的唯一权威处**。配套规则见 `references/l1-search-recipes.md` §七。
- 3. **强依赖 `github` 连接器**——未授权时只能走降级路径,候选完整性与排序质量都会下降;降级结果必须在交付文档里**显式标注**。
README.md · README · 482 lines
- <a id="chinese"></a>
- # requirement-to-path · 需求 → 对标 → 路径重构
- > **从一句模糊需求,走到一条能照着施工的实现路径。**
- **简体中文** | [English ↓](#english)
- [](LICENSE)
- [](https://github.com/zxd15978684198/requirement-to-path)
- [](references/self_check.py)
- [](references/self_check.py)
- [](https://github.com/zxd15978684198/requirement-to-path/actions/workflows/ci.yml)
- 一个给 AI coding agent 用的 **skill**(不是库,不是 CLI)。它把「帮我实现某个模块」这件事拆成五层,每层都有硬门禁,最后交付一份**每步都带通过信号**的施工路径。
- ---
- ## 它和「直接问 ChatGPT」差在哪
- | 常见的做法 | 这个 skill |
- | --- | --- |
- | 你只说得出一句话,AI 立刻开始写代码 | **先问清**:3 道门禁产出痛点清单 → 方案决策表 → 需求规格 |
- | 丢给你十个 GitHub 链接 | 匹配度矩阵 + **逐仓库**「为什么参考 / 为什么不全抄」 |
- | 拿 README 当结论 | **读代码**:`get_file_contents` 看实现,`pull_request_read` 看是否真合并 |
- | 「方案看起来是对的」 | 每步三件套:**指令模板 / 通过信号 / 翻车信号** |
- | 分不清哪句是猜的 | 每条事实标 `[代码可读]` / `[测试可证]` / `[推断]`,推断必须给验证方法 |
- 一句话:**它不替你写代码,它给你一条别人已经踩过坑的路。**
- ---
- ## 什么时候**不该**用它
- 诚实地写在最前面,省得你用错:
- | 情况 | 该用什么 |
- | --- | --- |
- | 需求已明确,只想立项开工 | `spec-development` |
- | 已有方案,只想压测它站不站得住 | `grill-me` |
- | 只想讨论方案,不需要找对标 | 直接聊,别套流程 |
- | 需求是**某家公司内部的业务规则** | 开工前就会告诉你不会有开源对标,别耗满搜索轮次 |
- ---
- ## 流程
- ```
- L0 澄清(门禁 1–3)→ L1 定位 → L2 提取(读码)→ 门禁 4 裁决 → L3 路径重构 → 交付自检
- ```
- - **L0**:需求方语言提问(禁用方案术语),三道门禁各产出一份可审阅的文档,⚙ 硬阻断
- - **L1**:动词短语 + 机制名词构造关键词 → 直搜捞候选 → 分类打标 → 匹配度矩阵 → 代码级验证
- - **L2**:入口主流程 → 数据结构 → 接口契约 → 测试文件,四步都记「它没断言什么」
- - **门禁 4**:优点照抄 / 能用但需改造 / 缺陷自己补,三分类后逐条裁决
- - **L3**:分步路径,每步都要能追溯到「L0 的某条裁决」或「L2 的某段代码」
- 11 步执行序列见 [`references/pipeline.md`](references/pipeline.md),主文件见 [`SKILL.md`](SKILL.md)。
- ---
- ## 安装
- ### 前置条件(硬性,不是可选项)
- 本 skill **强依赖 `github` 连接器**(MCP server)。所有检索与读码都走它的工具:
- `search_repositories` · `search_code` · `get_file_contents` · `pull_request_read` · `search_issues`
- 不自研检索脚本——鉴权托管、限流额度高(未认证直连只有 10 次/分钟)、随官方 server 升级零维护。连接器不可用时会走降级路径,并在交付文档里**显式标注候选质量下降**。
- ### 把这个连接器配上
- 需要做到的事只有一件:让你的 agent 能调到上面那 5 个工具。两条路,任选其一。
- **A. 用官方托管端点(最省事)**。GitHub 自己有托管的 MCP server,用 PAT 作为 Bearer 鉴权:
- ```json
- {
- "mcpServers": {
- "github": {
- "type": "http",
- "url": "https://api.githubcopilot.com/mcp/",
- "headers": { "Authorization": "Bearer <你的 PAT>" }
- }
- }
- }
- ```
- 把这段放进客户端的 MCP 配置即可:Claude Desktop / Cursor 各有自己的配置文件;DSH 走 MCP 连接器面板的「导入 JSON」。
- **B. 本地跑官方 server**。
- ```bash
- docker run -i --rm \
- -e GITHUB_PERSONAL_ACCESS_TOKEN=<你的 PAT> \
- ghcr.io/github/github-mcp-server
- ```
- 在客户端里把这条命令注册成 `stdio` 类型的 server。不想用 Docker,也可以从 [`github/github-mcp-server`](https://github.com/github/github-mcp-server) 下二进制。
- **PAT 权限按需最小化**。只读公开仓库时,fine-grained token 一个权限都不勾也能用;要读私有仓库,就给对应的那几个仓库 `Contents: Read`。本 skill 全程只读:不写、不开 PR、不发评论。
- **接好之后怎么确认**。问一句「你现在能调到哪些 github 工具」,看有没有 `search_repositories`、`search_code`、`get_file_contents`、`pull_request_read`、`search_issues` 这 5 个。
- **只暴露了一部分会怎样**。缺 `search_code`:定位阶段退化成只用仓库搜索,候选质量下降;缺 `get_file_contents`:读不到代码,「深读代码提取事实」这一整层失效。这两种情况都会在交付文档里显式标注为降级。
- 全程不需要 `gh` CLI,也不会调用任何 shell 命令。
- ### Claude Code
- ```bash
- git clone https://github.com/zxd15978684198/requirement-to-path.git \
- ~/.claude/skills/requirement-to-path
- ```
- 之后在会话里说「**帮我实现 XXX**」或「**有没有开源项目可以参考**」即可触发。
- ### DeepSeek Harness (DSH)
- 把整个目录放进 `DSH_HOME/skills/requirement-to-path/`,确保 `SKILL.md` 位于该目录根。
- ### 其他工具(Cursor / Codex / Gemini CLI / 自建 agent)
- 本 skill **不绑定任何运行时**:全是 Markdown + 一个只依赖标准库的 Python 脚本。把 `SKILL.md` 作为指令文件喂给你的 agent、把 `references/` 放在它能读到的位置即可。
- ---
- ## 一次真实调用长什么样
- 需求方原话只有一句:
- > 给内部问答机器人加一层语义缓存——重复或近似的问题别再调模型;但近似但不同的问题不能串答案。
- 产出物(10 节,约 4 万字符):
- ```
- 0 定位与档位 1 业务叙事 2 决策表 + 依据 3 量级 4 契约
- 5 对标结论 6 模块全景 7 分步路径 8 验收 9 已知限制
- ```
- 完整的端到端样例见 [`examples/full-walkthrough.md`](examples/full-walkthrough.md)。
- 第 7 节每一行长这样:
- | 步骤 | 来源 | 指令模板 | 通过信号 | 翻车信号 |
- | --- | --- | --- | --- | --- |
- | 加法缓存条目 | `src/cache.py:88` | … | 该测试能从 4 变 8 | 命中率不涨但延迟降 |
- **来源格填不出来源的步骤,会被删除**——不允许补一个勉强的出处。
- ---
- ## 质量与成本
- ### 成本
- | 项 | 量 |
- | --- | --- |
- | 首次加载 `SKILL.md` | ≈ 10,000 字符 |
- | `references/` | **按层读**,不是一次性全读(L0 前只读题池的 4 节,L1 前只读配方的主链 7 节) |
- | 运行时依赖 | 0(Python 标准库 + 你的 MCP 连接器) |
- ### 可复核的部分
- ```bash
- # SKILL.md 自身一致性:版本对账 / 哨兵位置 / 禁用形态 / 自述项数
- python references/self_check.py --skill SKILL.md # → 0 violations
- # 交付物自检:13 项机械检查(来源封闭域、声明唯一、标记与证据配套……)
- python references/self_check.py <交付文档.md> # 退出码 0/1/2/64
- # 任务级评测:对真实产出物打分,只判「能机械判的那一半」
- python evals/harness.py --case 02 --doc <产出物.md> --root <项目根>
- ```
- | 证据 | 内容 |
- | --- | --- |
- | 13 项机械自检 | 来源封闭域、声明唯一性、估算数字标记、L3 通过信号可判、引用完整性…… |
- | 6 道任务级评测 | [`evals/`](evals/):语义缓存、状态持久化、模糊平台、超时重试、增量重建、设备派发 |
- | 135 条版本账本 | [`references/verification-log.md`](references/verification-log.md):每次实测的版本、验证方式、覆盖范围、**以及跑不通的分支** |
- | CI | [`.github/workflows/ci.yml`](.github/workflows/ci.yml):在 Python 3.10 与 3.13 上跑自洽检查 + 参考文档检查 + 引用完整性 + 用例校验 |
- > **退出码 `0` 只等于「脚本没查到问题」**,不等于交付合格。脚本射程见 [`references/delivery-checklist.md`](references/delivery-checklist.md) §三、§四。这个 skill 对「假绿」有病态般的警惕——账本里记着它自己五次把检查器写成空转的事。
- ---
- ## 仓库结构
- ```
- SKILL.md 主文件:五层流程 + 门禁 + 硬约束(≈10K 字符)
- README.md 你正在读的这份(中文在上,English 在下)
- CHANGELOG.md 只记对外可见的变化
- references/
- pipeline.md 流程图、11 步执行序列
- l0-question-bank.md L0 题池(按域、按门禁)
- l1-search-recipes.md L1 检索配方(连接器映射、漏斗、降级)
- l2-extraction-protocol.md L2 读码协议
- l3-mode-map.md L3 路径规格(三件套、文档结构、叙事线)
- gate4-adjudication.md 门禁 4 裁决细则
- delivery-checklist.md 交付前自检清单与引用矩阵
- maintainer-notes.md **改 SKILL.md 前必读**:声明唯一性表 + 维护纪律
- verification-log.md 135 条版本账本(诚实记录,含失败)
- self_check.py 13 项机械自检(仅标准库)
- examples/full-walkthrough.md 端到端产出样例
- evals/ 6 道任务级评测 + harness.py
- ```
- ---
- ## 已知限制
- 1. **强依赖 `github` 连接器** — 未接通时只能走降级路径,候选完整性与排序质量都会下降,且降级结果会在交付文档里显式标注。
- 2. **搜索轮次硬上限 3 轮** — 满 3 轮必须把已有候选摆给需求方裁决,不允许自行死磕。
- 3. **「需求方答不出」的分支尚未实测** — 需求方就是项目 owner 时止损规则不会被触发;替不懂技术的别人做需求时要留意。
- 4. **本 skill 不做代码实现** — L3 产出交给 `spec-development` 之类的执行型 skill。
- 未验证的分支(🔴 会卡死流程 / 🟡 仅降低质量)逐条记在 [`references/verification-log.md`](references/verification-log.md)。
- ---
- ## 参与维护
- 改 `SKILL.md` 之前**必须**先读 [`references/maintainer-notes.md`](references/maintainer-notes.md),它写着这个仓库最容易翻车的地方:
- - **值只许出现在唯一权威处**——同一个数字写在两处、改一处漏另一处,是本 skill 历次翻车的唯一根因
- - 正文不写会随改版变化的值(版本号、区间端点、条数)
- - 改完立刻跑 `python references/self_check.py --skill SKILL.md`,并**贴出输出与退出码**
- - 判据类改动不执行等于没改(账本里记着 5 次同类事故)
- 提交 PR 时请说明:改了什么、为什么、以及你**实际跑了哪条命令**。
- ---
- ## License
- [MIT](LICENSE) © 2026 zxd15978684198
- ---
- <a id="english"></a>
- # English · requirement → analogue → reconstruct the path
- > **Turn one vague sentence into an implementation path you can build against.**
- [简体中文 ↑](#chinese) | **English**
- [](LICENSE)
- [](https://github.com/zxd15978684198/requirement-to-path)
- [](references/self_check.py)
- [](references/self_check.py)
- [](https://github.com/zxd15978684198/requirement-to-path/actions/workflows/ci.yml)
- A **skill** for AI coding agents — not a library, not a CLI. It splits "build me this module" into five layers, each behind a hard gate, and ends with an implementation path where **every step carries a pass signal**.
- > **Language note.** The skill's own instructions — [`SKILL.md`](SKILL.md) and everything under [`references/`](references/) — are written in Chinese, and so are its trigger phrases. This English README exists so you can judge whether the project is worth reading before you open those files.
- ---
- ## How it differs from "just ask a model"
- | The usual thing | This skill |
- | --- | --- |
- | You can manage one sentence, the model starts writing code | **It asks first**: three gates produce a pain-point list → a decision table → a requirement spec |
- | It dumps ten GitHub links on you | A match matrix plus, per repo, "why reference it / why not copy it wholesale" |
- | It treats a README as evidence | **It reads the code**: `get_file_contents` for the real implementation, `pull_request_read` to check a claim was actually merged |
- | "The plan looks right" | Every step ships as a triple: **instruction template / pass signal / failure signal** |
- | Guesswork is indistinguishable from fact | Each fact is tagged `[code-readable]` / `[test-provable]` / `[inference]`, and an inference must come with a way to verify it |
- In one line: **it doesn't write the code for you — it hands you a path someone else already walked, potholes included.**
- ---
- ## When **not** to use it
- Written up front so you don't reach for the wrong tool:
- | Situation | Use instead |
- | --- | --- |
- | Requirements are settled; you just want to start building | `spec-development` |
- | You have a plan; you want it stress-tested | `grill-me` |
- | You only want to discuss a plan; no analogue needed | Just talk — don't run the pipeline |
- | The requirement is **one company's internal business rule** | It will tell you there's no open-source analogue before you burn search rounds |
- (The two alternatives named above are separate skills in the author's own setup — substitute whatever plays that role in yours.)
- ---
- ## Pipeline
- ```
- L0 clarify (gates 1–3) → L1 locate → L2 extract (read the code) → gate 4 adjudicate → L3 reconstruct the path → self-check before delivery
- ```
- - **L0** — questions phrased in the requester's language (solution jargon banned); each of three gates emits a reviewable document, and ⚙ blocks hard
- - **L1** — verb phrase + mechanism noun build the keywords → direct search harvests candidates → classify and tag → match matrix → code-level verification
- - **L2** — entry point and main flow → data structures → interface contracts → test files; at every step it records "what this does *not* assert"
- - **Gate 4** — copy the strength / usable but needs rework / defect you must fix yourself: three buckets, adjudicated line by line
- - **L3** — a step-by-step path where every step traces back to "a decision from L0" or "a piece of code from L2"
- The 11-step execution sequence lives in [`references/pipeline.md`](references/pipeline.md); the main file is [`SKILL.md`](SKILL.md).
- ---
- ## Install
- ### Prerequisite (hard, not optional)
- This skill **hard-depends on the `github` connector** (an MCP server). All discovery and code reading go through its tools:
- `search_repositories` · `search_code` · `get_file_contents` · `pull_request_read` · `search_issues`
- It does not roll its own search script — auth is managed for you, the rate-limit budget is far higher (unauthenticated direct calls get 10 requests a minute), and it costs nothing to maintain as the official server evolves. If the connector is unavailable the skill falls back to a degraded path and **flags the drop in candidate quality** in the delivered document.
- ### Wiring up the `github` connector
- All the skill needs is for your agent to reach those five tools. Two ways, pick either.
- **A. Hosted endpoint — least setup.** GitHub runs a hosted MCP server; authenticate with a PAT:
- ```json
- {
- "mcpServers": {
- "github": {
- "type": "http",
- "url": "https://api.githubcopilot.com/mcp/",
- "headers": { "Authorization": "Bearer <your PAT>" }
- }
- }
- }
- ```
- Paste that into your client's MCP configuration: Claude Desktop and Cursor use their own config file, and DSH accepts it through the connectors panel's "import JSON".
- **B. Run the official server locally.**
- ```bash
- docker run -i --rm \
- -e GITHUB_PERSONAL_ACCESS_TOKEN=<your PAT> \
- ghcr.io/github/github-mcp-server
- ```
- Register that as a `stdio` server in your client. No Docker? Take a binary from [`github/github-mcp-server`](https://github.com/github/github-mcp-server).
- **Token scope — keep it minimal.** For public repositories only, a fine-grained token needs no permissions at all. To read private repositories, grant `Contents: Read` on just those repositories. This skill never writes, never opens pull requests, never comments.
- **Verify it took.** Ask your agent which `github` tools it can reach. You should see `search_repositories`, `search_code`, `get_file_contents`, `pull_request_read`, `search_issues`.
- **If only some of the tools are exposed:** without `search_code` the discovery stage falls back to repository search and candidate quality drops; without `get_file_contents` the code-reading stage cannot run at all. Both cases are flagged as degraded inside the delivered document.
- No `gh` CLI and no shell commands are involved at any point.
- ### Claude Code
- ```bash
- git clone https://github.com/zxd15978684198/requirement-to-path.git \
- ~/.claude/skills/requirement-to-path
- ```
- Then say "**help me build XXX**" or "**is there an open-source project I can reference?**" in a session to trigger it.
- ### DeepSeek Harness (DSH)
- Drop the whole directory at `DSH_HOME/skills/requirement-to-path/`, keeping `SKILL.md` at the root of that directory.
- ### Any other tool (Cursor / Codex / Gemini CLI / your own agent)
- This skill **is not tied to any runtime**: it is Markdown plus one Python script that uses only the standard library. Feed `SKILL.md` to your agent as an instruction file and put `references/` somewhere it can read.
- ---
- ## What a real run looks like
- The requester's entire brief was one sentence:
- > Add a semantic cache layer to our internal QA bot — stop calling the model for repeated or near-duplicate questions; but near-duplicates that mean different things must not cross answers.
- The deliverable (10 sections, roughly 40,000 characters):
- ```
- 0 framing and mode 1 business narrative 2 decision table + rationale 3 scale
- 4 contracts 5 analogue verdict 6 module landscape 7 step-by-step path
- 8 acceptance 9 known limitations
- ```
- A full end-to-end sample is in [`examples/full-walkthrough.md`](examples/full-walkthrough.md).
- Each row of section 7 looks like this:
- | Step | Source | Instruction template | Pass signal | Failure signal |
- | --- | --- | --- | --- | --- |
- | Add the cache entry | `src/cache.py:88` | … | that test goes from 4 to 8 | hit rate flat but latency drops |
- **A step whose Source cell cannot be filled in gets deleted** — no padding it with a plausible-looking citation.
- ---
- ## Quality and cost
- ### Cost
- | Item | Amount |
- | --- | --- |
- | First load of `SKILL.md` | ≈ 10,000 characters |
- | `references/` | **Read layer by layer**, never all at once (before L0 only 4 sections of the question bank; before L1 only the 7-section main chain of the recipes) |
- | Runtime dependencies | 0 (Python standard library + your MCP connector) |
- ### What you can re-run yourself
- ```bash
- # SKILL.md internal consistency: version reconciliation / sentinel positions / banned shapes / self-declared item count
- python references/self_check.py --skill SKILL.md # → 0 violations
- # Deliverable self-check: 13 mechanical checks (closed source domain, claim uniqueness, tag/evidence pairing, …)
- python references/self_check.py <deliverable.md> # exit 0/1/2/64
- # Task-level evaluation: scores a real deliverable, judging only the half a machine can judge
- python evals/harness.py --case 02 --doc <deliverable.md> --root <project root>
- ```
- | Evidence | What it is |
- | --- | --- |
- | 13 mechanical self-checks | Closed source domain, claim uniqueness, estimates marked as estimates, L3 pass signals must be decidable, reference integrity… |
- | 6 task-level evaluations | [`evals/`](evals/): semantic caching, state persistence, vague platform, timeout-retry, incremental rebuild, device dispatch |
- | A 135-row version ledger | [`references/verification-log.md`](references/verification-log.md): every measured run's version, how it was verified, what it covered — **and which branches still fail** |
- | CI | [`.github/workflows/ci.yml`](.github/workflows/ci.yml): on every push, self-consistency + reference-doc checks + reference integrity + eval-case validation |
- > **Exit code `0` only means "the script found nothing wrong"** — it does not mean the deliverable is good. The script's actual reach is documented in [`references/delivery-checklist.md`](references/delivery-checklist.md) §3–§4. This skill is pathologically wary of false green: the ledger records five separate occasions where it wrote a checker that silently checked nothing.
- ---
- ## Repository layout
- ```
- SKILL.md Main file: five-layer pipeline + gates + hard constraints (≈10K characters)
- README.md You are reading this (Chinese on top, English below)
- CHANGELOG.md User-visible changes only
- references/
- pipeline.md Flow diagram, 11-step execution sequence
- l0-question-bank.md L0 question bank (by domain, by gate)
- l1-search-recipes.md L1 search recipes (connector mapping, funnel, degradation)
- l2-extraction-protocol.md L2 code-reading protocol
- l3-mode-map.md L3 path spec (the triple, document structure, narrative line)
- gate4-adjudication.md Gate-4 adjudication rules
- delivery-checklist.md Pre-delivery checklist and reference matrix
- maintainer-notes.md **Read before editing SKILL.md**: claim-uniqueness table + maintenance discipline
- verification-log.md 135-row version ledger (honest, failures included)
- self_check.py 13 mechanical self-checks (stdlib only)
- examples/full-walkthrough.md End-to-end sample deliverable
- evals/ 6 task-level evaluations + harness.py
- ```
- ---
- ## Known limitations
- 1. **Hard dependency on the `github` connector** — without it only the degraded path runs; candidate coverage and ranking both drop, and the delivered document says so explicitly.
- 2. **Hard cap of 3 search rounds** — at three rounds it must put the candidates it has in front of the requester, not keep grinding on its own.
- 3. **The "requester can't answer" branch is untested** — the stop-loss rules never fire when the requester owns the project; be careful when running requirements for a non-technical third party.
- 4. **This skill does not implement code** — L3 output is handed to an execution-oriented skill such as `spec-development`.
- Unverified branches (🔴 blocks the flow / 🟡 degrades quality only) are listed one by one in [`references/verification-log.md`](references/verification-log.md).
- ---
- ## Contributing
- Before editing `SKILL.md` you **must** read [`references/maintainer-notes.md`](references/maintainer-notes.md). It documents the places this repository fails most often:
- - **A value may live in exactly one authoritative place** — the same number written twice and one copy updated is the single root cause behind every past regression here
- - Don't put values that move between releases (version numbers, interval endpoints, counts) in the body text
- - After any change, run `python references/self_check.py --skill SKILL.md` right away and **paste the output and exit code**
- - A change to a predicate that is never executed is not a change (the ledger records five incidents of exactly this)
- In a PR, say what you changed, why, and **which command you actually ran**.
- ---
- ## License
- [MIT](LICENSE) © 2026 zxd15978684198
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.