8.1 KiB
8.1 KiB
依赖真实调用协议
Le SPEC 的价值建立在三个外部能力真实运行之上。本文件定义每个依赖的本体位置、调用条件、调用方式、上下文交接与失败处理。
0. 调用方式总则（skill 类依赖）
所有 skill 类依赖（grilling / domain-modeling / think / openspec-*）按以下顺序选择调用方式：
- 宿主 Skill 工具：若当前 runtime 提供 Skill 工具且该依赖已在可用列表中，用 Skill 工具按名调用。
- 文件直读：否则用 Read 读取依赖原始
SKILL.md全文，把其内容作为当前回合的执行指令遵循。这不是降级——skill 的本质就是指令文档，宿主 Skill 工具内部做的也是加载原文；直读与工具调用在语义上等价，前提是读原文、遵循原义（包括其引用的 references 子文件，如 think 的 mode-evaluation.md）。
两种方式都必须：
- 先记入调用账本（
ledger.py append --dep <name> --kind skill-load --method skill-tool|file-read）； - 遵循原文机制，不自拟替代提示词（例如 grilling 的 frontier 轮次格式 ❓Q/➡️推荐、think 的 Simplicity Gate、openspec-propose 的 artifact 循环）。
1. grilling —— 访谈引擎
| 项 | 值 |
|---|---|
| 来源 | github.com/mattpocock/skills（productivity/grilling） |
| 本体 | ~/.agents/skills/grilling/SKILL.md（软链解析后读真源） |
| 入口语义 | grill-me = 只调 grilling；grill-with-docs = grilling + domain-modeling。Le SPEC 按此原义路由：全新项目 → grilling；已有代码/文档 → grilling + domain-modeling |
| 调用时机 | Phase 2 全程（simple 档也走它，只是轮数少） |
| 输入交接 | state.md 的「已确认决策」「开放问题」两节——已确认项不得再问；开放问题构成 design tree 的初始节点 |
| 原生机制（必须保留） | design tree、frontier（前置决策已定的可问集合）、每轮问整个 frontier 并给推荐答案、答案重塑树、"事实自己查（可派子代理）、决策问用户"、frontier 空且用户确认共识才算完 |
| 产物 | 每轮问题（❓Q1… ➡️推荐格式）；用户回答由 Le SPEC 写入 state.md |
Le SPEC 叠加规则（不与原义冲突）：
- 每轮用户回答后：决策入 state.md，轮次 +1；每约 4 轮做一次检查点（见 workflow.md Phase 2）。
- grilling 的"会话结束条件 = frontier 空"之外，Le SPEC 用需求收敛标准（workflow.md）做结束判定；两者取先到者，且需向用户确认共识后收口。
- 已有项目时叠加 domain-modeling：访谈中发现术语模糊 → 按其"Sharpen fuzzy language"当场澄清；硬决策按其三条件（难逆转/无上下文会困惑/真实取舍）写 ADR。GLOSSARY.md/ADR 由 domain-modeling 机制管理，Le SPEC 不另建。
2. think —— 方案分析引擎
| 项 | 值 |
|---|---|
| 来源 | github.com/tw93/Waza（skills/think） |
| 本体 | ~/.agents/skills/think/SKILL.md |
| 调用时机 | Phase 3：出现重大产品分歧、技术选型、架构取舍、过度设计疑虑、值不值得判断。simple 档且无实质争议 → 跳过并注明 |
| 模式选择（遵循其原生定义） | 定义清楚的修复计划 → Lightweight Mode；价值/存废判断 → 读 references/mode-evaluation.md；批量诉求 → mode-triage.md。默认全模式 |
| 输入交接 | state.md 已确认需求 + 约束 + 已否定方案 + 待选方案。think 的 "Durable Context Preflight" 要求读项目 AGENTS.md/CLAUDE.md 索引——照做 |
| 原生机制（必须保留） | 先查官方方案、推荐单一方案+理由+一个替代、premise collapse（最脆弱假设）、attack angles（外部依赖/并发/迁移时）、Simplicity Gate、批准前不动代码 |
| 产物 | 推荐方案 + 关键决策 + 风险 + 被否替代 → 写入 state.md「已确认决策」（待用户批准的标 [待批准]） |
回流规则：think 发现新的重大需求不确定性（Blocking ambiguities）→ 带回 Phase 2 用 grilling 格式做针对性追问（不是重启访谈），解决后回到 Phase 3 继续。
3. OpenSpec —— 规格工程引擎（CLI + skills 双通道）
| 项 | 值 |
|---|---|
| 来源 | github.com/Fission-AI/OpenSpec（npm: @fission-ai/openspec） |
| CLI | openspec（PATH 中，≥1.3 可用 artifact 工作流；本 skill 按 1.16.x 验证） |
| skills | ~/.agents/skills/openspec-{propose,new-change,update-change,verify-change,archive-change,apply-change,explore}/SKILL.md |
| 调用时机 | Phase 0（context 探测）、Phase 5（生成）、Phase 6（validate）、Phase 7 后的变更与归档 |
Phase 5 标准路径（遵循 openspec-propose 原生步骤，Le SPEC 已备齐输入故跳过其澄清步）：
openspec context --json # 定位根；root:null → 见下"项目初始化"
openspec new change "<kebab-name>" # 脚手架（默认 spec-driven schema）
openspec status --change "<name>" --json # artifact 顺序与路径
openspec instructions <artifact> --change "<name>" --json # 逐个：proposal → specs → design → tasks
# 按 template + instruction 撰写每个 artifact 文件
openspec validate "<name>" # 必须通过
- artifact 分工是 OpenSpec 原生的：
specs/= 产品需求（行为契约、Requirement/Scenario）、design.md= 技术设计（HOW，conditional）、tasks.md= 开发任务（checkbox）、proposal.md= Why/What/Capabilities。不混写。 - 项目初始化边界（遵循其 Project check 原义）：
root:null且用户未提 OpenSpec → 停下问用户：init（openspec init --tools none，工具注入由用户后续决定）/ 走 store / 不用 OpenSpec 本次降级输出。绝不让new change的副作用悄悄创建根。 - 变更管理：SPEC 已批准后的需求变化 → openspec-update-change 工作流（新 change 或修订现有），归档 → openspec-archive-change。Le SPEC 交接到此为止，apply 交给 Coding Agent。
4. 依赖检查与失败处理
scripts/deps_check.py（--json 供脚本、默认人读输出）：
| 依赖 | 级别 | 缺失时 |
|---|---|---|
| grilling skill | required | 停止访谈阶段，输出安装命令（下表），不降级为普通问答 |
| think skill | required（Phase 3 入口） | 方案分歧时停止并提示安装；无分歧场景不受影响 |
| openspec CLI | required（Phase 5 入口） | 停止规格生成，提示 npm install -g @fission-ai/openspec |
| openspec-* skills | recommended | CLI 工作流仍可走（Phase 5 标准路径即 CLI 驱动），但提示安装以获得完整工作流指令 |
| domain-modeling skill | recommended（已有项目时升 required） | 已有项目的访谈照常，但声明"术语沉淀与 ADR 不可用" |
| grill-me / grill-with-docs | optional（入口薄壳） | 不影响——Le SPEC 直接路由到底层组合 |
安装命令（真实可执行，2026-11 验证）：
npx skills@latest add mattpocock/skills --skill grilling grill-me grill-with-docs domain-modeling -g
npx skills@latest add tw93/Waza --skill think -g
npx skills@latest add Fission-AI/OpenSpec --skill openspec-propose openspec-new-change openspec-update-change openspec-verify-change openspec-archive-change openspec-apply-change openspec-explore -g
npm install -g @fission-ai/openspec@latest
失败语义：CLI 非零退出 ≠ 永远失败（如 openspec list 在无根项目返回非零，那是"未初始化"的答案不是崩溃）——读 JSON 输出判断，不盲目重试。skill 加载失败（文件不存在/为空）→ 记账本（method=file-read, exit=1）→ 按缺失处理。任何情况下不得用模拟输出冒充调用成功。
5. 防重复机制
- grilling 问过的 → state.md「已确认决策」，think 直接消费；
- think 已否定的方案 → state.md「已否定方案」，Phase 4/6 审查不再重提，除非发现新证据；
- OpenSpec artifacts 已写内容 → Phase 6 审查对照 state.md 检查一致性，不重新发起需求讨论；
- 每阶段入口先读 state.md 的阶段标记，已完成阶段不重做（中断恢复同理）。