code-zhuge · 卧龙军师

把一位"沉稳、证据优先、谋定而后动"的诸葛亮式军师，请进你的 Claude Code 或 Codex。 一条命令安装，persona 自动生效，36 条三十六计被翻译成可执行的工程战法；安装/卸载全程可回滚，除目标根文件（Claude 写 .claude/CLAUDE.md，Codex 写项目根 AGENTS.md）里一个受管激活块外不碰你的文件（卸载只删该块）。

这是什么

code-zhuge 是一个给 AI 编程助手用的 人格 + 技能包。装上之后，你的助手会：

• 用「亮」自称、称你为「主公」，先定胜负条件再动手，每个非平凡改动都自带 风险、验证、回滚；
• 把《三十六计》落成 36 个具体工程锦囊（迁移、调试、灰度、回滚、重构、安全……），按任务自动路由到对应战法；
• 通过一个安全安装器写入 Claude Code / Codex，带 manifest、备份、原子回滚，默认不装任何 hook，绝不静默覆盖你已有的文件。

它不是又一个 prompt 片段，而是一个内容完整、有测试门禁、可一键装卸的配置工程。

30 秒上手

npx code-zhuge@latest

无参数运行即进入交互式向导：

code-zhuge installer (v1.4.0)

Install target:
  1) Claude Code  (writes .claude/)
  2) Codex        (writes .agents/skills/)
  3) Both
Choose [1]: 1
Destination directory [/your/project]:

Plan preview (dry-run, nothing written yet):
  claude: create=45 update=0 overwrite=0 skip=0

Proceed with install? [y/N]: y
  claude: installed and validation passed.

Next steps:
  Claude Code: persona 已自动激活（写入 .claude/CLAUDE.md），重启会话即生效。

向导会先给出 dry-run 预览，确认后才写入，装完自动 validate 并打印「怎么触发」。CI/脚本里无 TTY 时会自动回退打印帮助，不会卡在提问上。

装上之后，回答长这样

主公问：我要做一个多人实时协作白板，该怎么设计？

军师以「隆中对」之势作答（示例，实际随场景变化）：

【天下大势】 实时协作的核心约束是冲突合并与延迟，而非画图本身。
            团队 3 人、要快上线，先求"对"，再求"快"。
【鼎足之势】 前端 Canvas + CRDT(yjs)；后端 WebSocket 网关；
            存储 Postgres 存快照、Redis 中转在线状态；部署单区起步。
【图谶风险】 并发：CRDT 合并幂等需测；性能：大房间广播放大；
            安全：房间鉴权不能只靠前端路由。
【进军路线】 1 先做单房间垂直切片(抛砖引玉) → 2 加鉴权与持久化 →
            3 压测广播路径(打草惊蛇暴露瓶颈)。每阶段带验收与回滚点。

结论先行、分三路落地、风险点和回滚路径都摆在台面上 —— 这就是 36 计在背后路由的效果（此处用到了 抛砖引玉/打草惊蛇 等锦囊）。

三大能力

| | 能力 | 说明 | |---|---|---| | 人格 | 卧龙军师 persona | 沉稳、典故只作隐喻不替代证据；三种输出风格：日常短答、隆中对（架构）、出师表/锦囊（事故与发布）。 | | 技能 | 36 计工程锦囊 | 一个可被发现的 code-zhuge skill，其 SKILL.md 作 router，统领 36 个 references/<nn>-<name>.md 锦囊（同一 skill 的 bundled 参考，非 36 个独立 skill）。 | | 安装 | 安全安装器 | install / uninstall / validate / dry-run，支持 Claude 与 Codex；manifest + sha256 漂移检测 + 备份 + 原子回滚 + 冲突拒绝。 |

三十六计 → 工程战法（节选）

| 计 | 工程含义 | |---|---| | 擒贼擒王 | 直击根因，而非反复打补丁。 | | 趁火打劫 | 事故响应时先抢救日志与现场证据，再动手。 | | 暗度陈仓 | 用 feature flag / 兼容层灰度迁移。 | | 关门捉贼 | 在隔离的测试/预发环境里复现问题。 | | 连环计 | 测试 + 灰度 + 监控 + 回滚组合成发布安全链。 | | 走为上 | 风险大于收益时，回滚、暂停或放弃。 |

完整 36 条映射见 docs/SKILL_MATRIX.md。

安装后怎么触发

• Claude Code：persona 自动生效 —— 安装时会往 .claude/CLAUDE.md（Claude 会话启动时自动加载的路径）写入一个受管 @import 块，重启会话即套用诸葛亮人格；code-zhuge skill 也会被发现用于路由。可选：/config → Output style 选 Kongming Brief / Longzhong Plan / Military Dispatch 之一，套用对应输出格式（一次只能激活一个）。
• Codex：persona 自动生效 —— 安装时会往项目根 AGENTS.md（Codex 从 repo 根向下扫描到 cwd 的路径）写入一个受管块，内联诸葛亮人格并指向 .agents/skills/code-zhuge/ 的可发现 skill。Codex 无 @import 机制，故人格内容直接内联；卸载只删该块，块外内容一字不动。

命令参考（CI / 进阶）

npx code-zhuge dry-run   --target claude --dest <project>   # 只看计划，不写文件
npx code-zhuge install   --target claude --dest <project>
npx code-zhuge validate  --target claude --dest <project>
npx code-zhuge uninstall --target claude --dest <project>   # 按 manifest 回滚

--target 取 claude 或 codex。通用选项：--dest --dry-run --force --json --help --version。 install 另有 --replace-code-zhuge：当目标已存在一个非本包管理的同名 skill 命名空间时，普通 --force 不会覆盖它，必须显式用此标志才会备份并接管（仅限该命名空间内）。

安全设计

• dry-run 与 install 一致：dry-run 说能装，install 就能装；目标处有目录/父路径有文件等阻塞，规划阶段就拒绝（exit 2，--force 也不绕过）。
• 绝不静默覆盖：遇到外部文件或你改动过的文件默认拒绝，--force 才备份并覆盖；卸载时从备份恢复你的原文件。
• 不吞同名 skill：已存在的 .claude/skills/code-zhuge 或 .agents/skills/code-zhuge 视为命名空间冲突，普通 --force 不覆盖，需 --replace-code-zhuge，且作用域仅限该命名空间。
• 卸载可信边界：manifest 路径必须命中本包产物或落在 code-zhuge 命名空间内，backup 必须位于 .code-zhuge/backups/<target>-.../；伪造 manifest 无法把删除/恢复引到别处。支持跨版本卸载旧安装。
• 升级不留尸：升级安装会按同样的可信边界清理旧版托管、而新版已改名/移除的文件（你改动过的保留，需 --force 才删；曾被顶掉的原文件从备份还原）。dry-run 同步报告将清理的内容。
• 默认零 hook：默认不安装 hooks.*，也不注入 UserPromptSubmit / PreToolUse / PostToolUse（中文输入安全约束）。校验器在本包管理的目录内强制此边界；你自己（或插件）放在 .claude/ 别处的 hook 配置与本包无关，不会被误报。
• 激活链路可校验：validate 会沿激活块的 @import 链逐跳解析（按 Claude Code 的规则：相对路径相对于包含 import 的文件），任何一跳断裂都硬性失败 —— persona 静默不生效的故障无法再通过校验。

设计细节见 docs/ARCHITECTURE.md。

写入了什么 / 怎么卸载

• Claude：.claude/code-zhuge/、.claude/output-styles/、.claude/skills/code-zhuge/（36 计在 skills/code-zhuge/references/）；外加 .claude/CLAUDE.md 里一个受管激活块（<!-- code-zhuge:begin --> … end），卸载时只删此块，块外你自己的内容一字不动。
• Codex：.agents/skills/code-zhuge/（Codex 会自工作目录向上扫描 .agents/skills/ 自动发现；36 计在 references/，不含 output-styles 与 CLAUDE.md —— Codex 无此机制）；外加项目根 AGENTS.md 里一个受管激活块，卸载时只删此块。
• 状态：manifest 在 .code-zhuge/<target>.manifest.json，备份在 .code-zhuge/backups/<target>-<timestamp>-<pid>/。
• 卸载：code-zhuge uninstall --target <claude|codex>，按 manifest 回滚，遇到你后续改动的文件会拒绝静默删除。

docs/ 仅为仓库开发文档，不会进入你的安装目标，也不是运行时依赖。

本地开发

npm test            # 发布门禁：结构校验 + CLI 行为测试
npm run validate    # 仅结构校验
npm run test:cli    # 仅 CLI 行为测试

CI 在 Linux / macOS / Windows × Node 20 / 22 / 24 上跑同一套门禁。贡献者可直接从源码运行 CLI：node bin/code-zhuge.js install --target claude --dest <project>。

License

MIT