101 lines
8.1 KiB
Markdown
101 lines
8.1 KiB
Markdown
# 依赖真实调用协议
|
||
|
||
Le SPEC 的价值建立在三个外部能力**真实运行**之上。本文件定义每个依赖的本体位置、调用条件、调用方式、上下文交接与失败处理。
|
||
|
||
## 0. 调用方式总则（skill 类依赖）
|
||
|
||
所有 skill 类依赖（grilling / domain-modeling / think / openspec-*）按以下顺序选择调用方式：
|
||
|
||
1. **宿主 Skill 工具**：若当前 runtime 提供 Skill 工具且该依赖已在可用列表中，用 Skill 工具按名调用。
|
||
2. **文件直读**：否则用 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 已备齐输入故跳过其澄清步）：
|
||
|
||
```bash
|
||
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 验证）：
|
||
|
||
```bash
|
||
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 的阶段标记，已完成阶段不重做（中断恢复同理）。
|