Pilot Shell 架构全景拆解：规则、钩子、技能与MCP如何协同工作-育师

Pilot Shell 架构全景拆解：规则、钩子、技能与MCP如何协同工作

【免费下载链接】pilot-shellProfessional context and harness engineering for Claude Code and OpenAI Codex. Build production-grade software with spec-driven development, TDD, persistent memory, quality gates, code intelligence, human oversight, and end-to-end verification.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shell

Pilot Shell 是一套面向Claude Code 与 OpenAI Codex的专业上下文工程（Context Engineering）与测试框架系统：它通过规则（Rules）、钩子（Hooks）、技能（Skills）与 MCP 服务器四大支柱，把规格驱动开发、TDD、持久化记忆、质量门禁和端到端验证组织成一个完整的工程闭环，帮助新手也能"像职业工程师一样"驾驭 AI 编程代理。

一张图看懂 Pilot Shell 的架构分层

Pilot Shell 的核心理念是：规则和记忆只是上下文供给，真正的产品是"协调整个工程流程的框架"。四个支柱各司其职：

支柱	目录	职责	生效时机
📏 规则 Rules	pilot/rules/	语言标准、测试策略、验证要求	会话启动 / 文件类型相关时
🪝 钩子 Hooks	pilot/hooks/	质量门禁、上下文恢复、记忆同步	会话生命周期的每个节点
🧩 技能 Skills	pilot/skills/	/spec、/build、/fix、/prd 等结构化工作流	用户显式调用
🔌 MCP 服务器	pilot/.mcp.json	代码检索、持久记忆、库文档等外部能力	会话中按需懒加载

规则：8 条常驻 + 9 条按路径触发的工程标准

规则是"每次会话都成立的共识"。Pilot 内置 17 个模块化规则文件，分为三类：

核心框架（3 条）：任务与工作流程、按风险定级的测试策略、与受影响的命令/UI 相匹配的验证证据（verification.md）
开发实践（3 条）：系统化调试、Git 规则、如何接收 Code Review 反馈（code-review-reception.md）
工具与上下文（4 条）：CLI 工具选型、浏览器自动化、MCP 服务器参考（mcp-servers.md）

语言标准（Python、TypeScript、Go、.NET 等 9 个）是路径门控的——只有当相关文件出现在工作中时才加载，避免挤占宝贵的上下文窗口。在任意项目中运行/setup-rules还能从真实代码库生成项目专属规则。

💡 对新手的关键收益：你不需要自己写 CLAUDE.md 规则，Pilot 直接把生产环境验证过的最佳实践加载进每个会话。

钩子：在会话生命线的每个节点自动执法

钩子是整个框架的"强制执行层"。所有钩子统一注册在 pilot/hooks/hooks.json，并有一份可测试的生命周期清单保证声明与实际文件一致。核心节点一览：

生命周期事件	典型钩子	做什么
`SessionStart`	`codegraph_init.py`、`licensed_assets_sync.py`	初始化代码图谱、同步技能资产、异步同步记忆
`UserPromptSubmit`	`spec_mode_guard.py`	检查工作流状态，防止非法进入实现阶段
`PreToolUse`/`PostToolUse`	`file_checker.py`、`context_monitor.py`	文件写入后即时检查、监控上下文用量
`PreCompact`/`compact`	pre_compact.py、`post_compact_restore.py`	压缩前抢救状态、压缩后恢复关键上下文
`Stop`	`spec_stop_guard.py`	停止守卫：义务未完成时，代理不能"看起来做完了"就收工
`SessionEnd`	`session_end.py`	会话收尾、记忆落盘

其中最体现"职业工程师"气质的是Stop 守卫（spec_stop_guard.py）：在 TDD 循环、独立评审和运行时验证全部通过之前，工作流不会被允许关闭，从机制上杜绝了"假装完成"的交付。

技能：把结构化工作流做成可编排的"步骤包"

技能（Skills）是显式调用的工作流引擎，每个技能都是一个编排器 + 步骤文件的结构。以/spec工作流为例，它的manifest.json声明了编排器与执行步骤；而计划阶段技能 spec-plan 则把"生成计划"拆成了 13 个细粒度步骤，从工作区扫描到端到端场景设计再到计划审批，每一步都有明确的输入输出契约。

四大结构化工作流的选择逻辑：

/spec— 任务需要先出方案再实现（计划 → TDD → 独立评审 → 端到端验证）
/build— 目标明确但任务清单需要边做边长（验收标准驱动的多轮构建）
/fix— 行为坏了：复现 → RED 测试 → 根因修复 → 质量门禁 → 审计
/prd— 问题或范围还没想清楚：探索方向并产出可评审的需求文档

MCP：七个懒加载服务器，给代理装上"外置大脑"

MCP 配置文件预置了 7 个服务器，全部懒加载——按关键词发现后再调用，保持上下文精简：

服务器	解决什么问题
CodeGraph	结构问题：符号、调用者/被调用者、影响半径，一次调用返回源码 + 调用路径
Semble	意图问题："X 功能在哪里改的"、跨语言概念检索
mem-search	历史问题：过去的决策与上下文（持久记忆）
context7	库/框架的最新官方文档
web-search / web-fetch	网络检索与完整页面抓取
grep-mcp	公共仓库中的真实代码参照

规则文件 mcp-servers.md 还教代理"什么时候该用哪个"——例如已知文件路径就直接读文件，不要绕道图谱查询，这种比例原则（Proportionality）正是上下文工程的精髓。

协同全景：一次 /spec 请求的完整旅程

把四层串起来，一次典型请求的流转是这样的：

用户输入 "/spec 实现 X 功能" │ ├─ 钩子 UserPromptSubmit：spec_mode_guard 校验进入状态 ├─ 技能 spec-plan 编排：扫描工作区 → 探索（MCP: CodeGraph/Semble） │ → 写计划 → 用户审批（Console 可批注） ├─ 规则 testing.md：按风险决定测试深度 ├─ 技能 spec-implement：TDD 循环，file_checker 钩子逐次校验 ├─ 钩子 Stop：spec_stop_guard 拦截"未完成即停止" └─ 验证通过后：mem-search 记忆落盘，Console 记录验证证据

而人类控制平面由本地 Console（localhost:41777）承担：审阅与批注需求和 Diff、恢复会话、查看进度与成本。所有支柱的状态在这里变成可点击、可检索的界面。

快速上手：两步接入你的项目

git clone https://gitcode.com/GitHub_Trending/cl/pilot-shell cd pilot-shell && bash install.sh

安装器是幂等的 8 步流程（失败自动回滚），会自动为 Claude Code 与 Codex 分别适配资产。装完后直接运行claude或codex即可，框架自动生效。

小结：为什么说这是"框架"而不是"配置合集"

规则供给共识，MCP供给上下文，技能供给流程，钩子供给强制力——四者缺一个，闭环就断了
停止守卫与独立评审把"看起来完成"变成"有证据的完成"
上下文在压缩与长任务中可恢复、跨 Claude Code 与 Codex 持久共享

更多细节可参考仓库内的官方文档：Hooks 管线、规则与标准、MCP 服务器与知识系统。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Pilot Shell 架构全景拆解：规则、钩子、技能与MCP如何协同工作