@geminix/gxpm 0.1.0

package/docs/research/everything-claude-code-study.md

@@ -0,0 +1,252 @@
+# everything-claude-code 工程实践研究报告
+
+> 研究日期：2026-05-02
+> 来源：affaan-m/everything-claude-code（本地路径 `/Users/x/Desktop/Project/github/everything-claude-code`）
+> 研究目的：提取对 gxpm 有参考价值的工程实践，建立快速适配索引
+
+---
+
+## 一、项目定位
+
+**everything-claude-code（ECC）** 是一个经过 10+ 个月生产验证、拥有 170+ 贡献者的多 harness（Claude Code / Codex / Cursor / OpenCode / Gemini）代理能力插件包。
+
+核心定位：**Skill 作为最可移植单元的扩展生态**，通过 Manifest 驱动的选择性安装与生命周期管理，为不同宿主平台提供统一的代理能力增强。
+
+ECC 不是独立运行时，而是**共享源 + 适配层**的架构模式：durable behavior 放在共享源，harness-specific 文件仅用于加载和适配。
+
+---
+
+## 二、架构与目录结构
+
+```
+everything-claude-code/
+├── .claude-plugin/          # Claude Code 插件元数据（plugin.json + marketplace.json）
+├── .codex/                  # Codex 适配：config.toml、agents/、AGENTS.md 补充
+├── .cursor/                 # Cursor 适配：hooks/（含 adapter.js）、rules/、agents/
+├── .opencode/               # OpenCode 适配：instructions/、tools/、README
+├── skills/                  # 182 个 SKILL.md（共享源，最可移植单元）
+├── agents/                  # 48 个 Markdown agent 定义（YAML frontmatter）
+├── commands/                # 68 个 legacy slash 命令（兼容面，逐步迁移至 skills）
+├── rules/                   # 分层规则：common/ + typescript/ + python/ + golang/ + ...
+├── hooks/                   # 事件驱动自动化（hooks.json + scripts/hooks/）
+├── scripts/                 # 跨平台 Node.js 工具库（安装、生命周期、hook 实现）
+├── manifests/               # 选择性安装 manifest（install-modules.json / profiles.json）
+├── schemas/                 # JSON Schema 校验
+├── contexts/                # 动态系统提示注入（dev / review / research）
+├── mcp-configs/             # MCP 服务器配置
+├── ecc2/                    # Rust 控制平面原型（alpha，TUI dashboard + SQLite state）
+└── tests/                   # 997+ 内部测试
+```
+
+**核心架构决策**：
+- `skills/` 是 canonical 工作流面，`commands/` 仅作兼容保留
+- AGENTS.md 是跨工具的通用上下文文件
+- 新增宿主 = 新增 manifest 目录 + adapter 层，避免为每个 host 维护完整副本
+
+---
+
+## 三、核心功能模块
+
+| 模块 | 职责 | gxpm 映射参考 |
+|------|------|---------------|
+| **Skills** | 知识/工作流模块，被动上下文激活 | gxpm skills（当前已对齐 SKILL.md 格式） |
+| **Agents** | 专项子代理（planner、code-reviewer 等），显式委派 | gxpm 暂无原生 agent 定义层，值得参考 |
+| **Commands** | 用户主动调用的 slash 命令（如 `/plan`） | gxpm CLI 命令（`gxpm issue` 系列） |
+| **Rules** | 始终生效的约束指南（分层：通用 + 语言） | `docs/governance/` 的规范化表达 |
+| **Hooks** | 事件触发自动化（PreToolUse / PostToolUse / Stop 等） | `.githooks/` + host hook 概念 |
+| **Contexts** | 动态系统提示注入模式 | session hook 的 context injection |
+| **MCP Configs** | 外部工具集成配置 | MCP 集成参考 |
+| **Install System** | 选择性安装、生命周期管理、状态持久化 | **gxpm 最需要借鉴的领域** |
+| **ecc2 (Rust)** | 控制平面原型：TUI、SQLite state、session 管理 | gxpm 未来原生运行时可参考 |
+
+---
+
+## 四、技术栈
+
+- **Node.js + TypeScript**：主运行时与脚本库
+- **Rust**（ecc2）：控制平面原型（TUI dashboard + SQLite state）
+- **JSON Schema**：manifest 和配置校验
+- **纯 Markdown**：skills、agents、rules 的内容层
+- **跨平台 shell + Node.js**：安装脚本和 hook 实现
+
+---
+
+## 五、扩展生态组织方式
+
+### 5.1 跨 Harness 适配模式
+
+```
+共享源                    适配层
+skills/*/SKILL.md   →   Claude plugin / Codex auto-load / Cursor copies / OpenCode plugin
+rules/              →   Claude rules install / Codex AGENTS.md / Cursor rules / OpenCode instructions
+hooks/              →   Claude native / OpenCode plugin events / Cursor adapter.js
+agents/*.md         →   Claude agents / Codex agents/*.toml / Cursor ecc-*.md
+```
+
+**Cursor Hook Adapter** 是关键工程实践：
+- `.cursor/hooks/adapter.js` 将 Cursor 的 stdin JSON 转换为 Claude Code hook 格式
+- 复用 `scripts/hooks/*.js` 的共享实现，无需为 Cursor 重写 hook 逻辑
+- 通过 `run-with-flags.js` 实现 hook runtime profile（minimal/standard/strict）和禁用列表
+
+### 5.2 插件元数据分层
+
+| 文件 | 用途 |
+|------|------|
+| `.claude-plugin/plugin.json` | 声明 skills/commands 路径，**不显式声明 hooks**（v2.1+ 自动加载） |
+| `.claude-plugin/marketplace.json` | 自托管市场配置 |
+| `.codex-plugin/plugin.json` | Codex 插件元数据 |
+| `.cursor/hooks.json` | Cursor hook 配置（预翻译的事件映射） |
+| `.opencode/instructions/INSTRUCTIONS.md` | OpenCode 统一指令入口 |
+
+**关键教训**：ECC 曾因在 `plugin.json` 中显式声明 `"hooks"` 字段导致与 Claude Code v2.1+ 的自动加载机制冲突，引发多次 fix/revert 循环，最终用回归测试锁定"不在 plugin.json 中声明 hooks"。
+
+---
+
+## 六、Skill 定义、发现、加载机制
+
+### 6.1 SKILL.md 标准格式
+
+```markdown
+---
+name: skill-name
+description: 一行描述，用于技能列表和自动激活
+origin: ECC
+---
+
+# Skill Title
+
+## When to Activate
+## Core Concepts
+## Code Examples
+## Anti-Patterns
+## Best Practices
+## Related Skills
+```
+
+### 6.2 发现与加载
+
+- Claude Code：`plugin.json` 的 `"skills": ["./skills/"]` 声明，自动扫描子目录中的 `SKILL.md`
+- Codex：`.agents/skills/` 下的 `SKILL.md` 被自动加载
+- 本地开发：直接复制到 `~/.claude/skills/<name>/SKILL.md`
+
+### 6.3 Skill 审计与治理（skill-stocktake）
+
+- **Quick Scan**：基于 `results.json` 的 mtime 差异扫描，仅审计变更 skill
+- **Full Stocktake**：完整评估所有 skill，输出 `Keep / Improve / Update / Retire / Merge` 判决
+- **评估维度**：Actionability、Scope fit、Uniqueness、Currency
+- **证据要求**：`reason` 字段必须自包含，禁止写 "unchanged" 等空泛结论
+
+---
+
+## 七、配置系统与扩展点
+
+### 7.1 选择性安装架构（Selective Install）
+
+**Manifest 层**：
+- `manifests/install-modules.json`：模块目录（id、kind、paths、targets、dependencies、cost、stability）
+- `manifests/install-profiles.json`：安装配置（core / developer / security / research / full）
+
+**安装流程分层**（已部分实现）：
+1. CLI Surface → 2. Request Normalizer → 3. Module Resolver → 4. Target Planner → 5. Operation Planner → 6. Execution Engine → 7. Install-State Persistence → 8. Lifecycle Services
+
+**安装状态契约**（`install-state.json`）：
+```json
+{
+  "schemaVersion": "ecc.install.v1",
+  "target": { "id": "claude-home", "root": "~/.claude" },
+  "request": { "profile": "developer", "modules": [...] },
+  "resolution": { "selectedModules": [...], "skippedModules": [...] },
+  "operations": [
+    { "kind": "copy", "moduleId": "rules-core", "destination": "...", "digest": "sha256:..." }
+  ]
+}
+```
+
+**生命周期命令**：
+- `ecc list-installed`：查看已安装状态
+- `ecc doctor`：检测缺失或漂移文件
+- `ecc repair`：基于 install-state 修复
+- `ecc uninstall`：仅移除 ECC 管理的文件
+- `ecc consult "security reviews"`：自然语言查询推荐组件
+
+### 7.2 Hook 运行时控制
+
+```bash
+export ECC_HOOK_PROFILE=minimal|standard|strict
+export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
+export ECC_SESSION_START_MAX_CHARS=4000
+export ECC_SESSION_START_CONTEXT=off
+```
+
+Hook 通过 `run-with-flags.js` 统一调度，支持按 profile 启用/禁用。
+
+### 7.3 规则分层架构
+
+```
+rules/
+├── common/           # 语言无关
+├── typescript/       # TS/JS 特定
+├── python/           # Python 特定
+├── golang/           # Go 特定
+└── ...
+```
+
+安装时按需复制，避免一次性加载全部规则消耗上下文。
+
+---
+
+## 八、对 gxpm 的借鉴价值
+
+### 8.1 可直接复用的模式 ✅
+
+| 模式 | ECC 实践 | gxpm 应用点 |
+|------|----------|-------------|
+| **Skill 格式标准化** | YAML frontmatter + Markdown 正文 | 统一 `origin` 字段和反模式章节 |
+| **Agent 定义格式** | Markdown + YAML frontmatter（name, description, tools, model） | 可在 `hosts/` 或新增 `agents/` 引入 |
+| **分层规则** | `common/` + 语言特定目录，按需安装 | `docs/governance/` 可按 host 或语言分层 |
+| **安装状态持久化** | `install-state.json` 记录完整操作链条 | `.gxpm/` 本地 state 可借鉴 operation 概念 |
+| **生命周期 CLI** | `ecc doctor/repair/uninstall/list-installed` | `gxpm cleanup land` 可扩展为 `gxpm doctor/repair` |
+| **Hook Profile** | minimal/standard/strict + 禁用列表 | `.gxpm/config.json` 可增加 hook profile 控制 |
+| **跨 Harness Adapter** | Cursor `adapter.js` 转换事件格式 | `hosts/claude.ts` vs `hosts/codex.ts` 可引入 adapter 层 |
+| **Skill 审计** | `skill-stocktake` 的 verdict/reason 机制 | skill 治理可引入定期审计和淘汰机制 |
+| **Token 优化指南** | `MAX_THINKING_TOKENS` / `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | `AGENTS.md` 可增加 host 特定的 token 管理建议 |
+| **CI 验证严格性** | 校验 agents/commands/rules/skills/hooks/install-manifests 的一致性 | `bun run check` 可扩展类似校验 |
+
+### 8.2 应避免的陷阱 ❌
+
+| 陷阱 | ECC 历史问题 | gxpm 预防措施 |
+|------|--------------|---------------|
+| **安装方法叠加导致重复** | `/plugin install` + `./install.sh` 导致重复加载 | 确保单一安装/发现路径，避免 `skills/` 与 `.gxpm/skills/` 重复 |
+| **Hook 加载与 harness 版本紧耦合** | Claude Code v2.1+ 自动加载导致 duplicate detection error | host adapter 应抽象 hook 注册机制 |
+| **安装状态不可追溯（1.x）** | 早期无 install-state，uninstall/doctor 只能猜测 | `.gxpm/issues/` 和 `.gxpm/local/` 应纳入统一 state |
+| **跨 harness 同步成本过高** | `.cursor/`、`.codex/`、`.opencode/` 需分别维护 | 未来扩展时采用 adapter 模式，避免完整副本 |
+| **Commands 与 Skills 双轨并行** | 维护成本高，commands 逐步 deprecate | 坚持 skills-first，CLI 命令直接调用 skill 逻辑 |
+
+---
+
+## 九、关键文件映射
+
+| ECC 文件/模式 | gxpm 对应位置/建议 |
+|---------------|---------------------|
+| `scripts/lib/install-state.js` | `.gxpm/` state 可引入 `operations` 数组概念 |
+| `manifests/install-modules.json` | capability registry 的分级机制（cost, stability, defaultInstall） |
+| `docs/architecture/cross-harness.md` | 写入 `docs/architecture/host-adapter.md` |
+| `ecc2/` Rust 控制平面 | gxpm 未来原生运行时的技术选型参考 |
+| `.cursor/hooks/adapter.js` | `hosts/` 引入 adapter 层减少 host 特定逻辑重复 |
+| `tests/validate-*.js` | `bun run check` 扩展 catalog 一致性校验 |
+
+---
+
+## 十、适配建议
+
+1. **Install-State 模型**：完整阅读 `scripts/lib/install-state.js`，将 `operations` 数组概念引入 gxpm 的 `.gxpm/` state，使 land/cleanup 能精确追溯文件/分支/worktree 的创建记录。
+2. **Capability Registry 分级**：参考 `manifests/install-modules.json` 的 `cost`、`stability`、`defaultInstall`、`targets` 字段设计 gxpm capability registry。
+3. **Host Adapter 契约**：将 ECC 的 "共享源 + 适配层" 原则写入 `docs/architecture/host-adapter.md`，作为未来扩展 Cursor/OpenCode 的架构基准。
+4. **Hook Profile 控制**：在 `.gxpm/config.json` 中增加 hook profile 和禁用列表配置，避免 hook 过度侵入。
+5. **Catalog 一致性校验**：参考 ECC 的 `validate-agents.js`、`validate-skills.js` 等，在 `bun run check` 中增加 skill/agent 与 manifest 的脱钩检测。
+
+---
+
+## 十一、一句话总结
+
+> ECC 是**经过大规模生产验证的成熟插件生态系统**，其在 **Manifest 驱动的选择性安装、跨 Harness 适配层、Hook 运行时治理、Install-State 持久化** 上的工程实践，可直接补足 gxpm 的扩展生态与运维治理层面；gxpm 应坚持独立产品定位，吸收其分发和治理模式，而非复制其插件包架构。

package/docs/research/from-skills-to-layered-workflow.md

@@ -0,0 +1,322 @@
+# 从 Skills 到分层 Workflow：AI Agent 工程化的下一层抽象
+
+> **作者：** 关木 (@ZeroZ_JQ)  
+> **来源：** https://x.com/ZeroZ_JQ/status/2053004758508843319  
+> **发布时间：** 2026-05-08 23:50  
+> **互动数据：** 2 转发, 22 点赞, 45 收藏, 2,814 浏览
+
+---
+
+很多 AI Agent 项目走到中后期，都会开始沉淀 skills。
+
+一开始，这几乎是必然动作。写代码要有 TDD skill，排查问题要有 debug skill，提交前要有 review skill，写文档要有 writing skill。每一个 skill 都像是在给 Agent 补一块局部能力：让它在某类任务上更稳定、更专业、更符合团队习惯。
+
+但系统一旦继续生长，一个更深的问题就会浮出来：skills 的数量增加，并不必然带来 Agent 行为的稳定性。
+
+表面上看，这是一个能力组织问题；但在机制层面，它其实是一个工程控制问题。小规模时，问题是"有没有合适的 skill"；规模扩大后，真正的问题变成了：这些能力在什么阶段被调用，由什么责任视角调用，依据什么输入推进，留下什么产物，又由什么机制决定是否可以进入下一步。
+
+这也是我设计 Unified Skills 时真正想解决的事情：不是再做一组 skills，而是把 skills 组织成一套分层 workflow。
+
+更准确地说，skills 解决的是"怎么做"，而 workflow 解决的是"什么时候做、由谁做、做到什么程度算通过、失败时退回哪里、过程证据留在哪里"。当 Agent 开始承担连续工程任务时，真正要治理的就不再是能力本身，而是能力进入流程的方式。
+
+---
+
+## 一、Skills Library 的上限，不是能力不足，而是工程失稳
+
+很多团队一开始搭建 skills library，逻辑都很自然：把常见问题抽成一组可复用方法论，需要时调用。
+
+- 需要写测试时，调用 TDD skill；
+- 需要调试时，调用 debug skill；
+- 需要审查时，调用 review skill；
+- 需要写作时，调用 writing skill。
+
+这种方式当然有效。因为它把零散经验变成了可复用结构，让 Agent 至少在局部问题上不再完全依赖临场发挥。
+
+但这套方式的上限也很清楚。问题不在于 skill 没价值，而在于工程工作从来不是一次技能调用，而是一条连续推进的责任链。
+
+当任务复杂度上升，系统会开始暴露出四类典型失稳。
+
+### 1. 时序失稳：Agent 会跳步骤
+
+Agent 很容易从一个模糊想法直接进入实现，然后在最后补一句"已验证"。skill 可以告诉它测试该怎么写，debug 应该怎么做，但 skill 本身并不能天然约束它：什么时候才有资格开始写，什么时候必须先澄清，什么时候必须先停下来做设计。
+
+这意味着，skills library 解决了局部执行质量，却没有解决阶段推进合法性。系统依旧可能以一种"看起来很高效，实际上不断跳过前置条件"的方式运行。
+
+### 2. 责任失稳：Agent 会自证通过
+
+更危险的问题，是 self-confirming loop。
+
+同一个 Agent 可以自己理解需求，自己做设计，自己列计划，自己完成实现，再自己 review，最后得出"没有问题"的结论。问题不在于它不努力，而在于工程系统不能把"提出问题、执行任务、判断通过"全部交给同一个认知视角。
+
+这是工程里最常见却最容易被忽视的风险：不是模型能力不够，而是责任边界没有切开。
+
+### 3. 证据失稳：过程不可追踪
+
+一次对话里，Agent 看起来好像完成了很多工作：澄清了需求、查了资料、做了设计、列了计划、写了实现、通过了 review。
+
+但几天之后回看，往往很难回答以下问题：
+
+- 当时的需求边界到底是什么？
+- 哪些外部资料被采纳，哪些被拒绝？
+- 设计时讨论过哪些替代方案？
+- 计划里哪些任务允许并行，哪些必须串行？
+- review 审的是 spec 完整性，还是只是代码风格？
+- ship 时有没有留下导出、同步、发布和回滚记录？
+
+如果这些问题无法回放，那么整个流程看似完成，实际上却缺少可审计证据。它更像一场即时表演，而不是一个可复盘的工程过程。
+
+### 4. 治理失稳：skills 之间没有组织关系
+
+TDD、review、debug 当然都可以是好 skill，但如果它们只是平铺在一个目录里，Agent 仍然要在运行时临场决定：先调哪个，什么时候切换，什么情况下跳过，失败后回到哪里。
+
+而这个"临场决定顺序"的过程，本身就是最大的随机性来源。
+
+所以，skills library 可以提升局部能力，但不能单独解决工程稳定性。因为它解决的是能力复用问题，不是流程治理问题。
+
+---
+
+## 二、Workflow 不是 Skills 的顺序表，而是阶段协议
+
+从这个角度看，Unified Skills 的第一层升级，并不是多做几个 skill，而是把 skills 放进一个明确的阶段流里。
+
+主路径不是"需要什么就调用什么"，而是：
+
+```
+/refine -> /design -> /plan -> /build -> /review -> /ship
+```
+
+这条路径背后的判断是：工程交付需要状态机，而不是自由联想。
+
+### /refine：把模糊想法收敛成可验证规格
+
+/refine 的任务不是"继续聊一聊需求"，而是把模糊想法压缩成可验证的 spec。它关心的是：
+
+- 问题是什么；
+- 用户是谁；
+- 成功标准是什么；
+- 约束有哪些；
+- 当前缺哪些外部事实；
+- 最终产物类型是什么。
+
+这一阶段如果没有收敛清楚，后面所有实现都可能在错误目标上越跑越快。
+
+### /design：在实现前冻结创作与体验判断
+
+很多系统最容易犯的错，是把 design 偷偷塞进 build。也就是说，边做边想、边写边改、边实现边决定体验。
+
+这在小任务里看起来无伤大雅，但在多产物系统里会迅速失控。UI、文章、deck、视觉稿这些产物，本质上都需要先完成创作和体验层面的判断，再进入生产。否则，build 阶段就会不断替代 design 阶段，最终让整个流程失去边界。
+
+### /plan：定义任务拓扑，而不是写一份待办清单
+
+/plan 真正要做的不是列出一些 todo，而是定义任务拓扑：
+
+- 哪些任务必须串行；
+- 哪些任务可以并行；
+- 哪些文件或模块允许写入；
+- 哪些步骤完成后才能进入下一阶段；
+- 哪些风险需要前置处理。
+
+计划不是形式主义，它的意义在于把"工作如何展开"从运行时 improvisation，变成可审查的结构。
+
+### /build：消费已批准输入，而不是重新发明目标
+
+/build 才是实现和内容生产真正发生的地方。但它最重要的纪律不是"认真执行"，而是：只消费已经批准的 spec、design 和 plan，而不是在实现过程中重新定义目标。
+
+这是很多 Agent workflow 会失效的关键点。因为如果 build 可以随时回写目标、改写边界、替代 review，那前面的阶段就会全部失去约束意义。
+
+### /review：门控，而不是口头确认
+
+/review 也不应该只是"帮我看看"。
+
+真正的 review 是门控。它的职责不是鼓励，不是润色，也不是在明显缺失时给一句"整体不错"。它必须有能力阻断流程：只要发现 blocking 问题，就要明确退回 /build，必要时甚至退回 /plan 或 /refine。
+
+### /ship：交付完成，不等于实现结束
+
+最后的 /ship 处理的不是代码本身，而是交付动作：发布、导出、同步、记录、回滚信息、交付痕迹。工程系统最容易被忽略的一点是：代码写完，并不等于交付完成。
+
+交付真正结束，必须以可追踪的收尾动作为标志。
+
+因此，workflow 的意义不在于给 skills 排一个顺序，而在于把每个阶段变成有输入、有输出、有门控的协议。它解决的不是"快点进入某种能力"，而是"任务如何合法地推进到下一状态"。
+
+---
+
+## 三、真正的升级，不只是阶段流，而是纵向分层
+
+如果只有阶段流，这个系统依然可能退化成一组更长、更复杂的 prompt。真正让 Unified Skills 变成工程系统的，不只是横向阶段，而是纵向分层。
+
+我把它抽象成六层：
+
+```
+CANON
+  -> Command
+  -> Agent
+  -> Skill
+  -> Artifact
+  -> Hook / validate
+```
+
+这不是六种文件分类，而是六种不同的系统职责。每一层都解决一个问题，同时拒绝解决另一个问题。一个方案是否成熟，不看它能不能跑通一次，而看它能不能被复用、治理和演化。
+
+---
+
+## 四、CANON：所有 Workflow 的宪法
+
+最上层是 CANON.md。
+
+它不是某个具体 skill，也不是项目说明书，而是所有阶段、角色和技能都必须继承的全局纪律。它定义的不是某类任务技巧，而是不可放松的底线：先陈述假设、控制范围、验证优先、遇到矛盾先停止并澄清、调试先找根因、不做 yes-machine。
+
+这一层解决的是纪律统一，而不解决具体任务策略。
+
+为什么它必须独立存在？因为如果没有 CANON，每个 skill 都会带着自己的隐含价值观。TDD skill 强调测试，debug skill 强调根因，review skill 强调质量，但它们之间缺少统一的行为合同。久而久之，整个系统会出现一种隐性腐蚀：局部方法论都很认真，整体行为却越来越不一致。
+
+所以 CANON 的作用不是让技能更强，而是让所有局部方法论不能为了局部方便，绕过全局纪律。
+
+> **第一条原则：具体能力可以增加纪律，但不能放松纪律。**
+
+---
+
+## 五、Command：阶段控制器，而不是快捷入口
+
+Command 层回答的问题是：现在处在哪个阶段，这个阶段应该读什么、产出什么、通过条件是什么。
+
+在 Unified Skills 里，Command 不是 prompt shortcut，而更像 workflow controller。
+
+例如 /plan 的职责，不是"调用一个计划类 skill"，而是定义计划阶段的合法输入、合法输出和门控条件。它要消费已经批准的 spec 和 design，产出 03-plan.md，在大型任务里拆出子计划和并行矩阵，并明确写入范围和风险点。
+
+这一层解决的是阶段推进协议，而不解决具体任务的方法论。
+
+换句话说，Command 不负责告诉你"debug 怎么做"，也不负责告诉你"review 怎么看代码"；它负责回答的是：当前阶段是否具备进入条件，当前产物是否达到通过条件。
+
+> **第二条原则：workflow 需要阶段状态机，而不是能力快捷方式。**
+
+---
+
+## 六、Agent：责任视角，而不是人格表演
+
+Agent 层最容易被误解。
+
+很多系统引入 agent，是为了让模型"扮演"产品经理、架构师、设计师、审查员。但如果角色只停留在语气层面，它最多制造一点表演感，并不能真正提升工程质量。
+
+Unified Skills 里的 Agent 层，核心不是角色扮演，而是责任切分。
+
+需求分析、任务计划、软件实现、规格审查、代码质量审查、发布判断，最好不要全部由同一个视角闭环完成。不是因为模型不能同时做这些事，而是因为工程系统不能把"提出问题、执行任务、判断通过"压在同一个认知回路里。
+
+例如：
+
+- review agent 不应该重新定义需求，它应该基于已批准的 spec 判断实现是否完整；
+- software engineer agent 不应该在 build 阶段决定任务拓扑，它应该在 plan 的约束内实现；
+- design reviewer 不应该只说"视觉不错"，它应该阻断缺少证据来源、模式综合和采纳/拒绝理由的设计稿。
+
+这一层解决的是责任分离，而不解决阶段协议定义。
+
+> **第三条原则：Agent 的核心价值是责任分离，不是人格化。**
+
+---
+
+## 七、Skill：真正可复用的方法论单元
+
+Skill 层是最具体的一层，也是最容易被过度简化的一层。
+
+一个合格的 skill，不应该只是一段"请你认真做 X"的提示词。它必须至少说明：
+
+- 什么时候进入；
+- 什么时候退出；
+- 具体步骤是什么；
+- 哪些说法是常见借口；
+- 哪些情况必须停止；
+- 如何验证自己做完了。
+
+这也是为什么 Unified Skills 里的 SKILL.md 往往不只是"做法说明"，而是会包含入口/出口、流程、红旗、常见说辞、验证清单，强纪律技能甚至会定义 Iron Law。
+
+这一层解决的是方法论复用，而不解决整体工作流编排。
+
+也就是说，Skill 负责回答"这一类事情怎么做"，但不负责回答"现在是不是该做这件事"。后者属于 Command 和 Agent 的职责。
+
+> **第四条原则：Skill 是执行方法论，不是工作流总控。**
+
+---
+
+## 八、Artifact：把过程变成证据链
+
+如果只看对话，Agent 的工作很容易变成一段不可回放的即时表演。
+
+今天看起来它澄清了需求、做了设计、写了计划、完成了实现、通过了 review；但过几天回头看时，很多关键信息已经散失在上下文里，既无法复盘，也无法迁移。
+
+所以 Unified Skills 把 artifact 作为 workflow 的一层，而不是一组顺手保存的文档。
+
+01-spec.md、02-design.md、03-plan.md、04-review.md、05-ship.md 这些文件，并不是文档洁癖，而是 Agent 行为的审计轨迹。它们记录的不是"写过什么"，而是"为什么这样推进、为什么这样取舍、为什么允许进入下一阶段"。
+
+这一层解决的是过程审计与复盘，而不解决运行时拦截。
+
+与此同时，artifact 也是多产物 workflow 成立的前提。软件、文档、文章、deck、视觉稿并不共享同一种构建路径。如果没有 artifact_type，系统就很容易用软件工程的方式处理所有产物，或者用内容创作的方式绕开软件质量门控。
+
+> **第五条原则：没有 artifact，workflow 就缺少可审计证据。**
+
+---
+
+## 九、Hook / Validate：把约定变成护栏
+
+只靠提示词约束 Agent，是不稳定的。
+
+提示词可以提醒模型不要做破坏性操作，但运行时 hook 才能拦截破坏性命令。文档可以要求技能命名规范、索引一致、根文档同步，但 validate 才能发现 README、AGENTS、skills-index、锁文件和 hooks 实现之间是否已经发生合同漂移。
+
+这也是 Unified Skills 里 hooks 和 ./validate 的意义所在。
+
+它们不负责替代思考，也不负责替代高层 review；它们负责把一部分纪律从"应该遵守"变成"违反就会暴露"。
+
+这一层解决的是运行时护栏与维护期漂移暴露，而不替代高层判断本身。
+
+这一点非常关键。高层纪律如果没有低层护栏，最终就只是建议。系统最容易发生的腐蚀，不是某个 prompt 突然写错，而是多个合同慢慢表面不一致：README 说一套，AGENTS 说一套，skills-index 还是旧的，hooks 实现又是另一套。等这些漂移积累起来，Agent 在不同入口读到的，就不再是同一个系统真相。
+
+> **第六条原则：高层纪律必须有低层护栏，否则只是建议。**
+
+---
+
+## 十、两阶段 Review：分层门控的一个具体例子
+
+分层 workflow 不是抽象口号，它必须体现在具体门控设计里。Unified Skills 里的 review，就是一个很典型的例子。
+
+这里的 review 不是单阶段"代码看起来怎么样"，而是拆成两关。
+
+### 第一关：Spec Compliance
+
+第一关先检查实现是否覆盖了 spec 中定义的功能需求、边界条件、错误路径和验收标准。它关心的不是"写得漂不漂亮"，而是：实现了什么，是否把该做的事情做全了。
+
+### 第二关：Code Quality
+
+只有在第一关通过后，才进入第二关。第二关才讨论 correctness、readability、architecture、security、performance 等质量维度。它关心的是：这些功能是如何被实现的，代价和质量是否合理。
+
+这个拆分看似简单，但它体现了分层 workflow 的价值。
+
+如果功能都没实现完整，就急着讨论代码风格，审查资源会被浪费；如果功能缺失和质量问题混在一起，反馈也会变得模糊。两阶段 review 的作用，就是把问题类型切开：先确认做没做对，再确认做得好不好。
+
+这不是让 review 更复杂，而是让门控更有顺序、更有边界、更有退回路径。
+
+---
+
+## 十一、从 Prompt 到 Workflow，再到治理结构
+
+回到最开始的问题：AI Agent 工程化到底需要什么？
+
+更长的 prompt 有用，但不够。更多的 skills 有用，但也不够。真正需要设计的，是 skills 之间的组织关系，以及这些组织关系如何进一步沉淀为治理结构。
+
+也就是说：
+
+- 用 CANON 定义不可放松的全局纪律；
+- 用 Command 定义阶段状态机；
+- 用 Agent 定义责任视角；
+- 用 Skill 承载可复用方法论；
+- 用 Artifact 留下过程证据；
+- 用 Hook / validate 把规则变成护栏。
+
+这套结构的目标，不是让 Agent 显得更复杂，而是让它在复杂任务里更可控。一个系统是否工程化，不看它能不能完成一次任务，而看它能不能稳定地推进、回退、审计和复盘。
+
+所以，prompt 是表达，skill 是方法，workflow 是制度，而 layered workflow 才是治理结构。
+
+所谓 Agent 工程化，真正工程化的不是生成能力本身，而是任务推进权、通过判定权、责任边界和证据链的分配方式。
+
+这也是 Unified Skills 想表达的核心判断：AI Agent 的下一层抽象，不是继续堆 skills，而是把 skills 放进一套有阶段状态机、责任分离、证据链和运行护栏的分层 workflow。
+
+进一步而言，真正成熟的 Agent 系统，不应该只是"会做很多事"，而应该知道：在什么阶段，由什么模块，以什么责任，依据什么证据，完成什么结果。
+
+技术方案的价值，不在于提出一个新名词，而在于重新划清问题边界，并给出可落地的系统结构。对 Agent 来说也一样。真正的工程化，不是把能力堆得更多，而是让系统知道自己何时开始、何时停止、何时退回、何时交付。

package/docs/research/gsd-study.md

@@ -0,0 +1,69 @@
+# GSD 调查
+
+日期：2026-05-04
+
+## 调查对象
+
+- GSD (get-shit-done) 主仓库：`/Users/x/Desktop/Project/github/gsd`
+- 本地安装路径：通过 `npx get-shit-done-cc@latest` 分发
+
+## GSD 的核心能力
+
+GSD 是一个**元提示框架（meta-prompting framework）**，夹在用户与 AI coding agent 之间，解决长任务执行中的**上下文腐烂（context rot）**问题。它的核心假设是：当 AI 的上下文窗口被累积对话填满后，输出质量会显著下降，因此必须通过多智能体编排 + 文件化状态来对抗这种衰减。
+
+关键事实：
+
+- **Fresh Context Per Agent**：每个被 orchestrator 派生的 agent 都获得一个干净的 200K 上下文窗口，彻底消除上下文腐烂。
+- **Thin Orchestrators**：workflow 文件（`get-shit-done/workflows/*.md`）不做重活，只负责加载上下文、派生 specialist agent、收集结果、更新状态。
+- **File-Based State**：所有状态保存在 `.planning/` 目录下（Markdown + JSON），无数据库、无服务器、无外部依赖。状态可 survive `/clear`，可提交到 git，可被人类直接阅读。
+- **Spec-Driven Pipeline**：`requirements → research → plans → execution → verification` 的严格流水线。
+- **33-Agent 架构**：21 个 primary agent + 12 个 advanced/specialized agent，每个 agent 有聚焦角色、受限工具权限和特定产物。
+- **两阶段层级路由（v1.40）**：6 个 namespace meta-skill（`gsd-workflow`、`gsd-project`、`gsd-review`、`gsd-context`、`gsd-manage`、`gsd-ideate`）作为第一层路由，把 eager skill listing 的 token 成本从 ~2,150 tokens 降到 ~120 tokens。
+- **Checkpoint / Resume 协议**：debug session 有持久化生命周期（`gathering → investigating → fixing → verifying → awaiting_human_verify → resolved`），状态跨会话保留。
+- **防御纵深**：plan-checker（执行前验证）、atomic commits（原子提交）、post-execution verifier（目标回溯验证）、UAT（人工最终 gate）。
+- **Nyquist Validation**：自动发现测试缺口并生成测试，不修改实现代码。
+- **Cross-AI Peer Review**：支持跨模型（Claude / Codex / Gemini 等）的代码评审。
+- **多 Runtime 支持**：Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、Cline。
+
+## GSD 高价值模块
+
+- `docs/AGENTS.md`：33 个 agent 的完整角色卡，含工具权限矩阵、产物定义和行为约束。
+- `docs/ARCHITECTURE.md`：系统架构、设计原则、组件关系、数据流和文件系统布局。
+- `docs/FEATURES.md`：124+ 个功能的详细参考，按核心 / 规划 / QA / 上下文工程 / 基础设施分类。
+- `docs/COMMANDS.md`：完整命令语法、flags、用例，含 namespace meta-skill 路由表。
+- `agents/gsd-*.md`：每个 agent 的独立角色文件，含 YAML frontmatter（name、description、allowed-tools、triggers）。
+- `references/`：上下文预算、AI eval 框架、doc 冲突引擎、context7 使用指南等参考文档。
+- `gsd-sdk query` / `gsd-tools.cjs`：状态查询 CLI 层，支持 `init.<workflow>`、`state`、`phase`、`roadmap`、`verify`、`intel` 等查询面。
+- `.planning/` 文件契约：
+  - `PROJECT.md` / `REQUIREMENTS.md` / `ROADMAP.md` / `STATE.md` / `CONTEXT.md`
+  - `phases/{N}-*/`：每阶段产物（RESEARCH、PLAN、SUMMARY、VERIFICATION、SECURITY、UI-SPEC、UI-REVIEW）
+  - `.planning/intel/`：可查询代码库知识库（JSON + Markdown）
+  - `.planning/debug/*.md`：持久化调试会话
+- `VERSIONING.md`：Semantic Versioning + npm dist-tag（latest / next）+ hotfix / minor / major 发布工作流。
+
+## GSD 的限制
+
+- **强绑定文件系统状态**：虽然无数据库是优势，但也意味着没有多用户并发或远程状态同步能力。
+- **非 Linear-first**：没有 issue tracker 集成的原生状态机，项目状态全靠 `.planning/` 文件和 ROADMAP.md。
+- **Agent 数量庞大**：33 个 agent 的维护成本高，skill surface 即使经过 v1.40 的合并（86→59）仍然复杂。
+- **CLI 工具层依赖 Node.js/npm**：`gsd-sdk` 和 `gsd-tools.cjs` 需要本地 Node 运行时，对纯 Bun 环境不够友好。
+- **Token 成本敏感**：虽然有两阶段路由和 context-window-aware prompt thinning，但多 agent 派生本身会增加总 token 消耗。
+- **无持久浏览器 runtime**：QA 能力以代码评审和测试生成为主，缺少像 gstack 那样的长期浏览器 daemon。
+
+## gxpm 的借鉴方向
+
+GSD 最核心的贡献是**对抗上下文腐烂的工程学**：
+
+1. **Fresh Context Per Agent**：gxpm 的长任务执行（如 investigate、browser QA、multi-file refactor）应借鉴 GSD 的“派生 specialist + 干净上下文”模式，而不是让一个 agent 在同一会话里无限累积。
+2. **文件化状态与 Checkpoint**：gxpm 的 `.gxpm/issues/<id>/memory/` 和 `resume-packet.json` 应吸收 GSD 的 `.planning/` 文件契约，让状态对人类可读、对 agent 可加载。
+3. **Debug Session 生命周期**：GSD 的 `gathering → investigating → fixing → verifying → resolved` 持久化调试流程，可直接映射到 gxpm 的 investigate capability 和 evidence store。
+4. **Agent 权限矩阵**：GSD 的“Checkers read-only / Executors have Edit / Researchers have web”的最小权限原则，应成为 gxpm subagent 派生的默认约束。
+5. **两阶段路由**：当 gxpm skill 数量膨胀时，GSD 的 namespace meta-skill 模式（6 个路由器替代 86 个平铺 skill）是降低成本的有效参考。
+6. **Nyquist Validation**：gxpm 的 `local-verify` / `ac-check` 阶段可引入“测试缺口自动生成”能力，作为验收的补充证据。
+
+GSD 不应被整体 vendoring，而应被拆成以下 capability source：
+
+- **context-recovery**：checkpoint / resume-packet / session state persistence
+- **multi-agent-orchestration**：specialist dispatch、fresh context、thin orchestrator 模式
+- **spec-driven-pipeline**：requirements → research → plan → execute → verify 的严格阶段
+- **debug-lifecycle**：科学调试循环的持久化状态机