le-spec v1.0.0：Le SPEC 智能需求分析与 SPEC 生成总控 skill——真实集成 grilling/grill-with-docs(domain-modeling) + think + openspec(CLI 1.16.1 + 7 个 openspec-* skills，均经 skills.sh 装入 ~/.agents/skills 并软链四 runtime)；七阶段工作流（识别/十类分拣/Grill 访谈/Think 挑战/反向验收/OpenSpec 生成/四视角审查）复杂度三档自适应；状态 state.md + 调用账本 ledger.jsonl 双持久化支撑中断恢复与真实调用核验；依赖检查 deps_check.py 分级报缺+精确安装命令，ledger.py append/check/tail；四类回合终止停点（批准前不编码为硬约束）；测试 A-I 九项全过：两场景 fresh-context 子代理多轮实测（4 轮访谈+变更+中断恢复+strict validate 双项目通过），账本 28 条真实调用（grilling×9/think×2/openspec CLI×14），独立子代理审查实测抓出自审遗漏的 2 blocking；已知限制 7 项如实入库（reports/test-report.md）
This commit is contained in:
leroy
@@ -0,0 +1,100 @@
|
||||
# 依赖真实调用协议
|
||||
|
||||
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 的阶段标记，已完成阶段不重做（中断恢复同理）。
|
||||
Reference in New Issue
Block a user