AjayIrkal23/agentic-mercy-10x

## 🩸 为什么选择 Agentic Mercy AI 编程代理极其聪明，却**缺乏纪律**。一旦将其放归真实的代码库中，同样的失败就会在每个任务里反复上演。Agentic Mercy 会彻底封死每一个漏洞 —— 默认且永久地： 该系统建立在六大承诺之上。每一个承诺都由代码强制执行，绝非凭空捏造： - **🎯 绝不漏接的路由。** 一个智能路由器只需读取一次你的意图，就能为工作分配精确的技能和专家 —— 由 **1,973 条受保护的触发规则**、去重后的会话清单以及优先级预算提供支持，确保任何可路由的内容都不会被静默丢弃。 - **🧰 218 项精选技能。** 涵盖标准、测试、安全、取证和设计工艺 —— 其中 **128 个上游技能包在安装时被锁定来源并进行了哈希验证**，因此 vendored 的技能可以干净地更新且绝不偏移。 - **🎼 十幕专家特遣队。** 审计师、架构师、规划师、工程师、调试器、设计师、清理器、文档编写器、验证器和安全哨兵 —— 全部通过 **一个参数化的 `/invoke` 命令** 按需组合。 - **🧠 自愈式代码库智能。** 工作区会自动为你当前所在的代码库（符号、依赖项、文档）建立索引 —— **零后台 daemons**。代理绝不会盲目工作。 - **💸 模型成本自动驾驶。** 为每个任务匹配合适的模型：**默认使用 Sonnet，只有在它能发挥真正价值的地方才用 Opus。** 仅凭一个策略文件决定。 - **🛡️ 全程安全护栏。** 失败时安全放行的原子 hooks、会话遥测、一键回滚，以及记录了工作区所保留的所有内容的清单归档。 ## 🎯 绝不漏接的路由 合适的技能或专家会在正确的时机自动出现，无需你发号施令。一个**单一的路由器**坐落于你的 prompt 与实际工作之间。它会**一次性**将你的意图分类为任务画像，根据你正在触碰的文件对技能进行排名，将信号最强的集合打包进一个**优先级预算**中，并对会话已确认的内容进行去重。 _{一个“一次性分类”路由器仅选择你的 prompt 实际需要的技能。其触发面是由校验和保护的 1,973 条逐字规则的底线 —— 绝不漏掉任何可路由的内容。}
| 组件 | 功能描述 | |---|---| | **一次性分类任务画像** | 你的意图和触碰的路径仅被读取一次；所有下游决策都复用该读取结果 | | **排名选拔进入优先级预算** | 仅加载信号最高的技能，按优先级排序并针对会话清单进行去重 | | **触发底线** (`hooks/trigger-floor.json`) | **1,973 条逐字记录**，受校验和保护，并在 CI 中强制执行 *绝不移除* 的原则 —— 确保绝不漏接任何可路由内容的保证 | | **自调优权重** | 权重更新器会学习哪些技能真正起到了帮助，并重新对未来的路由进行排名；底线规则保持与权重无关 | | **唯一真相源** | 每个路由和命令组合都位于 `hooks/autonomous-skill-router.config.json` 中 | 通常你根本不需要输入命令：像 *“修复这个 bug 并在完成后清理”* 这样的纯英文 prompt 会被自动分类，匹配的专家链将自动触发。 ## 🦸 八大超能力，218 项技能 工作区中的每项技能都旨在赋予开发者八大超能力之一。这是一份完整的名册 —— **真实的清单，绝非诱饵** —— 能让你的日常效率提升 10 倍。 _{从 218 项技能中提取的八大能力通道。其中 128 项在安装时进行了上游锁定和逐字节哈希验证，确保 vendored 技能包可以干净地更新。}
### 🔬 ① ANALYZE（分析）—— 一次调用纵览整个代码库 | 技能 / 工具 | 10 倍提升点 | |---|---| | `codebase-intel-first` | 原则：构建代码的结构模型，然后只读取关键内容 | | `jcodemunch-token-saver` | 符号索引 —— **一次调用**即可找到函数、其调用者及其影响范围，无需读取二十次文件 | | `graphify` | 依赖图 —— 瞬间回答“谁依赖了 X？”和“A 和 B 是如何连接的？” | | `project-structure-map` · `project-reference-linkage` | 层级边界，以及陌生代码库中隐藏的跨模块连线 | | `lean-ctx` | 压缩 I/O · 10 种读取模式 · 仅需 **~13 个 token** 即可重新读取文件 | | `caveman` | 输出压缩 —— **减少约 75% 的 token**，保持完整的技术准确性 | ### 🗂️ ② ORGANIZE（组织）—— 保持代码库整洁 | 技能 | 10 倍提升点 | |---|---| | `frontend-structure-standards` · `backend-standards-always-follow` · `service-layer-standards` | 领域优先的前端文件夹，以及清晰的路由/控制器/服务/schema 后端边界 | | `scaffold-standards` · `domain-scaffold-patterns` | 新领域？先获取确切的文件树结构，然后再编写逻辑 | | `api-contract-standards` · `api-and-interface-design` | 稳定的封装结构和跨越前端/后端接缝的强类型契约 | | `dead-code-and-change-audit` | 持续的代码清理 —— 任何孤立的 import、陈旧的引用或半拉子重构都无法存活 | ### 🗺️ ③ EXECUTE（执行）—— 拒绝凭感觉写代码 | 技能 | 10 倍提升点 | |---|---| | `plan-mode-gate` · `workflow-orchestrator` | 强硬的起飞前检查：没有经过检查的计划就不写代码 | | `source-driven-development` | 每一个决策都基于官方文档，而非陈旧的记忆 | | `sequential-thinking` (原则) | 将**所有**推理过程外部化 —— 计划、审计、调试、决策 | | `ponytail` · `doubt-driven-development` | 先寻找最简单的可行方案，然后进行对抗性的自我审查 | | `incremental-implementation` · `subagent-driven-development` | 以安全的切片进行发布，并分发独立的任务 | ### 🧪 ④ TEST（测试）—— 证明它能用，而不是空口无凭 | 技能 | 10 倍提升点 | |---|---| | `test-driven-development` · `golang-testing` | 红、绿、重构；Go 的表驱动测试 | | `webapp-testing` · `browser-testing-with-devtools` | 真实浏览器的 DOM、控制台、网络和视觉检查 | | `verification-loop` · `eval-harness` | 代理必须真正跨越的终点线 | | `systematic-debugging` · `debug-investigation` | 复现、寻找根本原因、最小化修复 —— 没有找到原因绝不修补 | ### 🛡️ ⑤ SECURE（安全）—— 安全无洞地发布 | 技能 / 代理 | 10 倍提升点 | |---|---| | `owasp-security` · `security-and-hardening` | 将 OWASP Top 10 (2025)、ASVS 以及 LLM/代理威胁融入到每次审查中 | | `security-sentinel` (代理) | 对 diff 进行 Semgrep + OWASP 扫描，返回 **BLOCK / PASS** 的结论 | | `backend-error-handling` | 安全的日志记录、密钥脱敏、对客户端安全的错误映射 | ### 📖 ⑥ LEARN（学习）—— 永不遗忘，拒绝重复推导 | 技能 / 系统 | 10 倍提升点 | |---|---| | `memory` (MCP) + 记忆协议 | 跨会话持久化保存模式、决策和脆弱区域的坑 | | `dox-doc-tree` | 在**每一个**目录中放置一个 `CLAUDE.md` + `AGENTS.md` —— 从根目录读到目标目录，然后再进行编辑 | | `update-docs` · `CODEX.md` | 文档和 ADR 与变更保持同步，受门槛强制约束，存放在活态的决策日志中 | ### 🎼 ⑦ CREATE（创造）—— 盒子里的完整专家团队 | 技能 / 代理 | 10 倍提升点 | |---|---| | 十幕专家特遣队 + 参数化 `/invoke` | 审计 · 规格 · 计划 · 实现 · 调试 · 设计 · 清理 · 文档 · 验证 · 安全 —— 按需组合 | | `forensic-hotspot-finder` · `forensic-change-coupling` | 哪些文件导致了最多的 bug；哪些文件在悄悄地同时发生变更 | | `forensic-complexity-trends` · `forensic-debt-quantification` | 质量是否在上升？这笔技术债的代价换算成**美元**是多少？ | ### 🎨 ⑧ DESIGN（设计）—— 不像 AI 生成的 UI | 技能 / 引擎 | 10 倍提升点 | |---|---| | `impeccable` · `taste-skill` · `ui-ux-pro-max` · `huashu-design` | 反劣质代码工艺：token、排版、层级、动效 | | `frontend-ui-engineering` · `design-extract` | 生产级 UI；从任何在线 URL 中提取设计系统 | | **Higgsfield** 素材引擎 | 定制的图像 / 视频 / 3D / 音频 —— 真实素材，绝非占位符 ## 🎼 一条命令，一整支团队 输入 `/invoke audit spec plan impl design`，**一整支跨职能团队将按顺序苏醒** —— 审计师、架构师、规划师、工程师、设计师 —— 每个人都是一个拥有干净上下文的专家，将自己的产物交接给下一个人。 _{一个参数化的 /invoke 组合了这十幕专家团队。背后由二十个命令文件支撑；一句简单的纯英文 prompt 即可自动触发匹配的链条。}
每次调用都运行相同的**三个步骤** —— 这也是为什么它们能组合得如此完美： ``` flowchart LR subgraph ACT1["🎬 ACT 1 · INTEL"] direction TB I["Symbol index
+ dependency graph
produce a codebase brief"]:::a1 end subgraph ACT2["🎬 ACT 2 · DISPATCH"] direction TB D["audit · spec · plan · impl
debug · design · security
run in dependency order"]:::a2 end subgraph ACT3["🎬 ACT 3 · AUTO-CLOSE"] direction TB C["clean · docs · verify
then the stop-gates"]:::a3 end I ==> D ==> C classDef a1 fill:#0EA5E9,stroke:#0369A1,color:#fff classDef a2 fill:#6E56CF,stroke:#4B3B9C,color:#fff classDef a3 fill:#22C55E,stroke:#15803D,color:#052e16 ``` 自由组合这些步骤：`/invoke audit spec plan impl clean` 运行整个主轴；`/invoke debug` 则只运行其中一个步骤。二十个命令文件支撑了这套交互表面，任何命令名称都能通过 invoke 转换器进行解析。 #### 专家团队 GSD、Figma 和 Vercel 辅助代理进一步完善了阵容。 ## 🎬 当你按下回车键时会发生什么 每个任务都运行相同且纪律严明的主轴 —— **理解 · 构建 · 自动收尾 · 证明** —— 伴随着不让任何草率通过的门槛。这是完整的生命周期，从你打开一个项目的那一刻起，直到代理*被允许*说“完成”的那一刻止： ``` flowchart TD A(["🖥️ cd project && claude"]):::start --> S0 subgraph S0["① SESSION START · dispatch.py fires as your session opens"] B["🧠 Active-repo symbol index + dep-graph verified
🗂️ Memory + CODEX working-log loaded
📚 dox doc-tree root verified
🧾 Skill manifest primed · ponytail + caveman on"]:::hook end S0 --> P(["⌨️ Your prompt"]):::start subgraph S1["② UNDERSTAND"] AU["🔬 AUDIT
hotspots · coupling · churn · dead code
cited findings, never vibes"]:::agent SP["📐 SPEC
typed contracts · acceptance criteria
plus an explicit Not-Doing list"]:::agent PL["🗺️ PLAN
dependency-ordered · exact file paths
a TDD cycle per task"]:::agent end P --> AU --> SP --> PL subgraph S2["③ BUILD"] IM["⚙️ IMPLEMENT
task-by-task · test-first · atomic commits"]:::agent DB["🐞 DEBUG
reproduce, demonstrate root cause, minimal fix"]:::agent end PL --> IM IM -->|"tests red / bug"| DB DB -->|"root cause + fix"| IM subgraph S3["④ AUTO-CLOSE · runs every time, no exceptions"] CL["🧹 CLEAN
removes only what this diff orphaned"]:::agent DX["📖 DOCS
syncs docs + the per-dir CLAUDE.md tree"]:::agent VF["✅ VERIFY
runs the real flow · captures real output"]:::agent end IM --> CL --> DX --> VF subgraph GATES["🚧 STOP-GATES · the session cannot end until…"] G["Docs synced ✔ Security scanned ✔ Review passed ✔"]:::gate end VF --> G --> DONE(["🎉 Done — with evidence, not assertions"]):::done classDef start fill:#6E56CF,stroke:#4B3B9C,color:#fff,font-weight:bold classDef hook fill:#0EA5E9,stroke:#0369A1,color:#fff classDef agent fill:#1E293B,stroke:#6E56CF,color:#E2E8F0 classDef gate fill:#F59E0B,stroke:#B45309,color:#1E293B,font-weight:bold classDef done fill:#22C55E,stroke:#15803D,color:#052e16,font-weight:bold ``` 你无需手动运行这些阶段。一个**参数化的 `/invoke `** 命令即可将它们组合起来，而一句简单的纯英文 prompt 会自动触发匹配的链条。 ## 🧠 自愈式代码库智能 每一项超能力都建立在代理**绝不盲目工作**的基础之上 —— 而且这不会让你花费一分钱。一个事件驱动的状态机会**仅针对当前活跃的代码库**，使用带有防抖重新索引机制的**独立单次运行构建器**，保持四个方面（jcodemunch 符号、jdocmunch 文档、graphify 依赖关系和 dox 树）处于最新状态。这里有**零 daemons**，且从结构上讲，它*绝不可能*触碰任何其他代码库。

_{符号索引加上依赖图，在会话和写入事件时刷新 —— 仅限活跃代码库，单次运行构建器，没有常驻的监听器。}
**为什么这很重要：** 原生代理在*每个*任务中都要用 grep 重新推导结构，却依然会漏掉跨模块的边缘情况。而在这里，这是一次调用即可对永远保持最新的映射进行的查询 —— 这正是 [token 节省](#-the-token-economy)的来源所在。 ## 🛡️ Hooks —— 强制执行的所在之处 技能只是*建议。* **Hooks 则是强制执行。** 八个按事件的 `dispatch.py` 编排器驱动着整个生命周期，每个 hook 都保持着自己独立的模块，拥有一个 `type`、一个 `enabled` 标志、一个优先级和一个 token 预算。单个链路崩溃不会拖垮其所在的事件。

_{五个生命周期阶段，每一个均由八个事件分发器之一驱动；每个 hook 都保持为一个独立的文件，并且由一个 link-doctor 合成触发每一个环节。}
有些链路不仅仅是建议 —— 它们负责**管控**。带有风险性的变更会经历重重考验，并且在收尾门槛通过之前，会话甚至无法*结束*：

_{门槛链条 —— 模型路由、智能优先、TDD 卫士、dox 树、安全扫描、审查 —— 全部由写入前分发器和 Stop 分发器内部的独立链路强制执行。}
| 阶段 | 分发器功能 | 独立链路（部分） | |---|---|---| | **① SessionStart** | 启动时即了解代码库 | `jcodemunch-index-guard` · `memory-load-on-start` · `dox-tree-guard` · `tdd-guard-init-guard` | | **② UserPromptSubmit** | 塑造请求 | 统一的 prompt 路由器 · `sequential-thinking-mandate` | | **③ PreToolUse** | 管控并路由每一个操作 | `opus-guard` · `jcodemunch-enforce` · `dox-write-gate` · `tdd-guard-gate` · `security-scan-gate` | | **④ PostToolUse** | 每次写入后进行清理 | `desloppify-cleanup` · `doc-update-enforcer` · `dox-child-scaffold` | | **⑤ Stop** | 证明已完成，然后学习 | `hard-completion-gate` · `santa-method-writer` · `session-memory-writer` | ## 💸 模型成本自动驾驶 每个任务都由合适的模型运行，且仅由一个文件拍板。Sonnet 默认处理一切事务；Opus 则被保留用于真正能发挥其价值的工作。

| 级别 | 触发时机 | 真相源 | |---|---|---| | **Sonnet** | 所有任务的默认选项 | `hooks/model-policy.json` | | **Opus** | UI/UX 工作 · 真正繁重的构建 · **IMPLEMENT** 专项任务 | `invoke_categories.IMPLEMENT: "opus"` | | **Fable** | 仅限用户明确请求 —— 绝不自动触发 | 用户驱动标志 |

`model-policy.json` 是模型选择的**唯一**存在之处。`opus-guard.py` 会根据其 `[sonnet]`/`[opus]`/`[fable]` 前缀锁定各个子代理的模型，而 `workflow-model-guard.py` 则防止工作流子代理继承 Opus 父代理 —— 这正是原生设置永远不会注意到的、悄无声息的 token 消耗。 ## 💰 Token 经济学 这里是能让你回本的部分。原生代理通过**读取文件**来回答问题 —— 它进行 grep 扫描，打开十几个文件，然后淹没在自己制造的上下文里。而本工作区通过**查询预构建的符号索引和依赖图**来回答，随后对所有流转的信息进行压缩。在 prompt 层面，一个“一次性分类”的路由器会将信号最强的技能打包进一个优先级预算中，而不是生成一大堆注入器。

_{两重复合收益：精准的索引查询取代了盲目的文件堆砌；一个“一次性分类”的路由器打包进优先级预算中，取代了多次在 prompt 时的注入器生成。} ``` xychart-beta title "Tokens spent per task — stock agent vs agentic-mercy-10x (illustrative)" x-axis ["Find callers", "Grok a module", "Re-read a file", "Explain change"] y-axis "Tokens" 0 --> 80000 bar [45000, 80000, 3000, 1200] bar [1500, 6000, 13, 300] ```

较高的柱状图代表原生代理 · 较低的柱状图代表本工作区。说明性的估算源自各项技能所标称的节省量。

| 日常任务 | 🐌 原生代理 | ⚡ agentic-mercy-10x | 节省比例 | |---|---:|---:|---:| | “谁调用了 `processPayment`？” | grep + 读取约 15 个文件 ≈ **4.5 万 token** | `find_references` ≈ **0.15 万 token** | **~97%** | | “在编辑前理解这个模块” | 读取整个目录 ≈ **8 万 token** | `assemble_task_context` ≈ **0.6 万 token** | **~92%** | | “编辑后重新读取文件” | 完整重读 ≈ **3 千 token** | `lean-ctx` diff ≈ **13 token** | **~99%** | | “解释你所做的更改” *(输出)* | 冗长的描述 ≈ **1.2 千 token** | `caveman` ≈ **300 token** | **~75%** | ## 🧭 代理永远知道该去哪找 让一个原生代理面对一个陌生的代码库，它只会到处乱逛 —— 打开文件、瞎猜、走回头路。本工作区给了它一个 **GPS**：`codebase-start-point-guide` 设定入口点，而 `project-reference-linkage` + `project-structure-map` 会追踪变更所触碰的确切垂直切片，使其能够径直走向正确的文件并跳过其余部分。

_{从起点，到确切的垂直切片，再到完成。连线映射图保持了链路中每个节点的可追踪性，因此不会遗漏下游的任何内容。}
``` flowchart LR C["🧩 component"]:::fe --> H["🪝 hook"]:::fe --> A["🌐 api client"]:::fe A --> RT["🛣️ route"]:::be --> CT["🎛️ controller"]:::be --> SV["⚙️ service"]:::be SV --> SC["📐 schema"]:::be --> MD["🗄️ model"]:::be H -.->|"UI state"| ST["🗃️ store / slice"]:::fe classDef fe fill:#0EA5E9,stroke:#0369A1,color:#fff classDef be fill:#6E56CF,stroke:#4B3B9C,color:#fff ``` ## 🗂️ 保持代码库的结构化 如果放任不管，AI 代理会把任何代码库变成一团乱麻 —— 文件乱丢、内联类型随便写、到处都是死代码。本工作区让结构变得**不可选**：每个新领域都会以已知的形态落地，每个层级边界都牢不可破，跨模块的连线都提前映射完毕。

_{这是默认的产出，而不是期望的结果：在脚手架阶段、写入阶段和收尾阶段强制执行领域组织化的结构。}
### 标准可视化 四组常驻的技能集决定了*每个文件的去向及其形态* —— 因此上述整洁的结构就是你将得到的默认结果：

Frontend — frontend-structure-standards · frontend-standards-always-follow: domain-first folders, central type ownership, a hard 250-line file ceiling.	Backend — backend-standards-always-follow · service-layer-standards · backend-api-standards: route, controller, service, schema, model — boundaries that never blur.
Scaffold — scaffold-standards · domain-scaffold-patterns: a new domain emits its exact file tree, validated against real Fastify/TS, FastAPI/Python, and Go/chi codebases.	Contract — api-contract-standards · api-and-interface-design: one typed, stable envelope across the frontend/backend seam — no parallel shapes.

三层强制执行机制让它保持原样： - **在脚手架阶段** —— `scaffold-standards` + `domain-scaffold-patterns` 生成确切的文件树。 - **在写入阶段** —— 结构技能在每次编辑时注入；检查 250 行的代码上限和层级边界。 - **在收尾阶段** —— `dead-code-and-change-audit` 清扫孤立项，而 `dox` 树会在你触碰过的任何目录中生成一个 `CLAUDE.md`。 ## 📖 自文档化的代码库 **dox 树**确保每个代码库中的每个目录都带有一个 `CLAUDE.md`（以及一个 `AGENTS.md` 指针） —— 当你创建一个新文件夹时，PostToolUse 分发器内部的一个链路会为其**自动生成**文档骨架。代理在每次编辑前都会从根目录读到目标目录，因此它总是能继承其工作确切位置上的本地规则。

_{在每个文件夹中放置文档，自动为新文件夹生成骨架，并在任何编辑之前从根目录读到目标目录 —— 从而让代理永远不会违反它所不知道的本地规则。} ## 🎨 绝不像 AI 生成的 UI 大多数 AI 编写的都是**劣质 UI** —— 模板化的卡片、千篇一律的紫色渐变、毫无设计意图。本工作区对此说不。一套由六项技能组成的反劣质设计栈 —— 加上 **Higgsfield** 素材引擎 —— 将一份简介转化为看起来经过精心设计的界面。

_{剔除劣质，注入工艺：这套六项技能的栈用刻意的 token、类型和层级取代了模板化的默认样式。}

The stack — impeccable · taste-skill · ui-ux-pro-max · huashu-design · frontend-ui-engineering · design-extract, fed by Higgsfield-generated assets.

The loop — the frontend-uiux-designer agent explores 3 variations, runs a self-critique pass, then captures screenshot proof at real breakpoints ahead of presenting.

## 🏛️ 五个层级，一种准则 ``` flowchart TD L1["🧭 DOCTRINE — CLAUDE.md + rules/
always-in-context operating rules"]:::l1 L2["🎨 CRAFT — 218 skills
how to do the work well"]:::l2 L3["🛡️ ENFORCEMENT — 8 dispatchers · isolated links
makes the doctrine real at write-time"]:::l3 L4["🤖 SPECIALISTS — 10-act corps
one expert per act"]:::l4 L5["🎼 ORCHESTRATION — parametric /invoke
composes specialists into the 3-act flow"]:::l5 L1 --> L2 --> L3 --> L4 --> L5 classDef l1 fill:#4B3B9C,stroke:#312566,color:#fff classDef l2 fill:#6E56CF,stroke:#4B3B9C,color:#fff classDef l3 fill:#0EA5E9,stroke:#0369A1,color:#fff classDef l4 fill:#EC4899,stroke:#9D174D,color:#fff classDef l5 fill:#F59E0B,stroke:#B45309,color:#1E293B ``` | 层级 | 路径 | 职责 | |-------|------|------| | **1 · 原则** | `CLAUDE.md`, `rules/ | 始终处于上下文中的操作规则 —— 模型路由、技能协议、TDD/dox/codebase-intel 原则。 | | **2 · 工艺** | `skills/` | 代理调用的 218 项技能，用于*出色地完成工作*（标准、测试、安全、设计、取证）。 | | **3 · 强制执行** | `hooks/` | 8 个事件分发器，连接着各个独立的链路 —— 技能注入、索引卫士、写入门槛、模型卫士、停止门槛。 | | **4 · 专家** | `agents/` | 十幕专家团队，加上一名 UI/UX 设计师和 GSD/Figma/Vercel 辅助代理。 | | **5 · 编排** | `commands/` | 20 个 `/invoke` 文件，将专家组合成 3 步流程。 | ## 🚀 安装 **一条命令**，适用于 Ubuntu/macOS **或** Windows。`install.py` 是一个仅依赖标准库的引导程序（Python ≥ 3.10），通过 `hooks/lib/platform.py` 自动检测操作系统，具有幂等性且是非破坏性的。 **Ubuntu / macOS** ``` git clone https://github.com/AjayIrkal23/agentic-mercy-10x ~/.claude && python3 ~/.claude/install.py ``` **Windows (PowerShell)** ``` git clone https://github.com/AjayIrkal23/agentic-mercy-10x $env:USERPROFILE\.claude ; py -3 $env:USERPROFILE\.claude\install.py ``` `install.py` 按顺序运行：**检测** OS/python/node/git · 幂等安装**依赖项** · 注册 **MCP servers** · **具现化**技能（复制或 NTFS 连接，绝不使用符号链接） · 从受追踪的 `settings.template.json`（加上可选的 `settings.user.json` 覆盖）**渲染** `settings.json` · **构建并验证**技能目录（触发底线保护 + 上游完整性） · 运行 **doctor**。 ``` python install.py doctor # health + trigger-surface + model-routing verifier python install.py update # git pull --ff-only · deps · re-render · rebuild · doctor ``` 标志（参数）：`--dry-run`（打印计划操作，不进行任何修改） · `--ci`（跳过联网步骤）。每个路径都通过 `hooks/lib/platform.py` 解析 —— **没有硬编码的用户名或驱动器号**，并且**完全没有 `.sh` hooks** —— 因此它适用于任一操作系统上的任何用户。 ## ✅ 每次推送都经过验证的质量 **每次推送都会在 `ubuntu-latest` 和 `windows-latest` 上进行验证。** 这些检查会在 CI 和安装时运行，因此回归问题在出现的瞬间就会被捕获 —— 而不是在会话中途。

| 检查项 | 结果 | |---|---| | **CI 矩阵** | 每次推送在 **Ubuntu + Windows** 上均为绿色（通过） | | **Doctor** (`installer/doctor.py`) | **13 / 13** PASS, 0 WARN, 0 FAIL | | **测试套件** (hook + router + installer) | **136 / 136** 通过 | | **技能验证器** | **0 个严重失败**；**128 个上游锁定的技能哈希干净** | | **触发底线** | **1,973** 条记录，校验和匹配 | | **渲染等价性** | `render(template)` == `settings.json`，逐字节一致 | | **符号链接** | **0**（Windows 安全） | | **SessionStart 墙** | **< 0.8s** |

## 🛡️ 安全性与可逆性 每一层都可以安全触碰，且不会丢失任何内容： - **设计上失败放行** —— 每个 hook 在崩溃时都会降级为 PASS，绝不会卡死会话。 - **一键回滚** —— 一个带有 git 标签的锚点只需一条命令即可恢复整个工作区。 - **绝不清除** —— 任何技能都不会被移除；`attic/` 保留着一个具有清单的归档，因此活跃表面未加载的任何内容仍保留在磁盘上。 - **按需重生** —— `gen-invoke-commands.py --emit-combos` 随时可将每个命令名扩展为其各自的文件。 ## 🧩 不包含的内容 在设计上，该代码库排除了任何属于密钥、会话产物、个人数据或可从其他地方重新安装的内容： - **密钥** —— `.credentials.json`、API 密钥、token 以及 `~/.claude.json`（你的 MCP 配置）永远不会被提交。`settings.json` 改为引用环境变量（例如 `${GITHUB_TOKEN}`）。 - **会话与个人数据** —— `projects/`、`history.jsonl`、`sessions/`、`file-history/`、`todos/`、shell 快照以及每台机器的状态。 - **可重新安装的外部依赖** —— 插件缓存/市场、`skills/gstack/`、`ast-grep-mcp/` 和 GSD（`get-shit-done/`）系统。安装程序和说明会获取这些内容。 安装完成后，请完成以下设置： 1. **插件** —— 添加市场（`anthropics/claude-plugins-official`、`veelenga/claude-mermaid`、`obra/superpowers-marketplace`、`forrestchang/andrej-karpathy-skills`、`DietrichGebert/ponytail`），并使用 `claude plugin install` 安装你想要的插件。 2. **MCP servers** —— 这些 hooks 期望在你自己的 `~/.claude.json` 中配置好 `jcodemunch`、`graphify`、`lean-ctx`、`memory`、`sequential-thinking` 和 `context7`。删减掉你不需要的部分。 3. **代码智能引擎（推荐）** —— 符号和文档索引来自于 [jCodeMunch](https://j.gravelle.us/jCodeMunch/descriptions.php)。通过 uv 安装，然后注册： uv tool install jcodemunch-mcp && uv tool install jdocmunch-mcp # Windows: pipx install claude mcp add --scope user jcodemunch jcodemunch-mcp claude mcp add --scope user jdocmunch jdocmunch-mcp # 或运行 scripts/install-jdocmunch.sh 如果缺少任何一个引擎，安装程序会打印相同的指导；除此之外的其他一切在没有它们的情况下也能正常工作。 4. **密钥** —— 导出你自己的 token；本项目中不提供任何密钥。 ## 🛠️ 自定义 本工作区旨在被 fork 并进行调整。请编辑**真相源**，而不是生成的产物： - **`hooks/autonomous-skill-router.config.json`** —— 决定每个 `/invoke` 类别加载哪些技能以及这些步骤如何组合。 - **`hooks/model-policy.json`** —— 唯一的模型准则（默认 sonnet · UI+繁重任务+IMPLEMENT 用 opus · 仅限明确请求使用 fable）。 - **`hooks/dispatch.config.json`** —— 8 个分发器及其每个链路的启用标志、优先级和预算。 - **`hooks/trigger-floor.json`** —— 绝不漏接的路由表面；由 `hooks/build-trigger-floor.py` 重建。 - **`hooks/gen-invoke-commands.py`** —— 确定性地重新生成 20 个 `/invoke` 命令文件。 - **`hooks/skills-provenance.json`** —— 每一项技能的上游来源和锁定的版本（在此编写与 vendored 的对比）。 - **`settings.template.json`** —— 由 `installer/render.py` 渲染成 `settings.json`；掌握着 hook 的连线、MCP servers 和权限配置。 ## 🚧 Hooks 强制执行的内容 为了避免出现意外 —— 本工作区自带了具有强烈主见的门槛。以下是值得注意的几个： - **技能路由** —— 基于路径排名的技能在写入时注入；会话清单会批量处理你尚未读取的内容。 - **代码库智能优先** —— 将盲目的源码读取引导至 `jcodemunch` 符号索引和 `graphify` 依赖图。 - **TDD 卫士**（警告模式） —— 标记出在没有先经历失败测试的情况下编写的实现。仅供参考，视为一种指导原则。 - **dox 文档树** —— 每个 git 代码库的每个目录中都会有一个 `CLAUDE.md` + `AGENTS.md`；在存在根 `CLAUDE.md` 之前，代码写入都会被拦住。 - **模型路由** —— 除非明确升级（`model-policy.json`），子代理默认使用 Sonnet。 - **停止门槛** —— 文档同步、安全扫描（当 auth 相关文件发生变更时）以及一轮审查 —— 全部作为会话结束的把关条件。 所有的 hooks 在关键环节都会以*放行*的方式失败，但它们改变了代理的行为方式。如果想要更轻量的设置，可以删减 `settings.json` 以及你不想要的分发器链路。 ## 🙏 致谢 本工作区建立在出色的第三方技能之上。**每一项都保留了其各自的上游许可证** —— 请查看每个项目以了解相关条款。128 个上游锁定的技能在安装时经过了逐字节的哈希验证，且 `hooks/skills-provenance.json` 记录了每一项 vendored 技能的确切来源和锁定的版本。向它们的作者致以最诚挚的感谢： | 技能 / 套件 | 上游来源 | |---------------|----------| | Impeccable (UI/UX 工艺) | [pbakaus/impeccable](https://github.com/pbakaus/impeccable) | | Huashu Design (花叔) | [alchaincyf/huashu-design](https://github.com/alchaincyf/huashu-design) | | UI/UX Pro Max | [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | | Taste-Skill (反劣质前端) | [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill) | | gstack (发布/QA/浏览/设计套件) | [garrytan/gstack](https://github.com/garrytan/gstack) | | Superpowers | [obra/superpowers-marketplace](https://github.com/obra/superpowers-marketplace) | | Ponytail (反过度工程) | [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) | | Karpathy 指南 | [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) | | ast-grep MCP | [ast-grep/ast-grep-mcp](https://github.com/ast-grep/ast-grep-mcp) | 前端设计素材由 Higgsfield 生成；GSD（`get-shit-done`）提供了 `gsd-*` 命令系统。 ## 📄 许可证 本工作区自身编写的原创内容（hooks、agents、commands、rules、自主编写的技能以及本文档）均基于 **MIT 许可证** —— 见 [LICENSE](LICENSE)。© 2026 Ajay Irkal。 **`skills/` 下的第三方技能保留了其各自的上游许可证**（见致谢表）。MIT 适用于本代码库中的原创工作，不适用于 vendored 代码。

**如果你的代理曾凭感觉把你逼入绝境 —— 这就是破局之道。** ⭐ *点亮 Star、Fork 它，将其塑造成你喜欢的样子。*

标签：AI智能体, Claude Code, Homebrew安装, SOC Prime, 开发工具, 自动化编排, 自定义脚本