From 4811e8c73bebb7d5300dd706efe9ff34a1173302 Mon Sep 17 00:00:00 2001 From: cjp Date: Mon, 23 Mar 2026 11:48:31 +0800 Subject: [PATCH] docs(zh-CN): add prune command translation --- docs/project-overview.zh-CN.md | 391 +++++++++++++++++++++++++++++++++ 1 file changed, 391 insertions(+) create mode 100644 docs/project-overview.zh-CN.md diff --git a/docs/project-overview.zh-CN.md b/docs/project-overview.zh-CN.md new file mode 100644 index 00000000..9023f445 --- /dev/null +++ b/docs/project-overview.zh-CN.md @@ -0,0 +1,391 @@ +# Everything Claude Code 项目分析 + +## 项目定位 + +这个仓库本质上不是一个“业务应用”,而是一套给 AI 编码代理使用的“工程化运行时 + 能力分发包”。它把提示词、子代理定义、技能库、命令库、hooks、规则、安装器、状态管理、测试与跨平台适配整合在一起,目标是把 Claude Code、Codex、Cursor、OpenCode 这类 agent harness 调教成更稳定、更可控、更像资深工程师的工作流系统。 + +从仓库里的实际内容看,它当前是一个成熟的产品化分发仓库,而不是零散配置集合:有 `25` 个 agents、`57` 个 commands、`108` 个 skills、完整的 hook runtime、选择性安装 manifest、CLI、SQLite 状态查询命令,以及测试与校验链。核心说明在 [README.md](../README.md)、[package.json](../package.json)、[AGENTS.md](../AGENTS.md)。 + +## 它到底在做什么 + +它做的事可以概括成 5 层: + +### 1. 规则层 + +把团队/个人想让 AI 始终遵守的工程规范固化下来,比如 TDD、80% 覆盖率、安全检查、immutability、Git 工作流、性能与上下文管理。这部分在 `rules/` 下面,按 `common + language packs` 组织。 + +### 2. 能力层 + +把不同任务拆成可复用能力单元。 + +- `agents/` 是“角色型子代理”,例如 planner、architect、security-reviewer、code-reviewer、build-error-resolver。 +- `skills/` 是“方法论/领域知识包”,例如 TDD、verification-loop、frontend-patterns、market-research、deep-research、security-review、frontend-slides、x-api 等。 + +### 3. 交互层 + +把常用工作流做成斜杠命令。比如 `/plan`、`/tdd`、`/code-review`、`/verify`、`/quality-gate`、`/loop-start`、`/model-route`、`/sessions`、`/harness-audit`。这部分在 `commands/`。 + +### 4. 自动化运行时 + +通过 hooks 在会话开始、编辑文件、运行命令、会话结束等时机自动触发行为,例如: + +- 加载上下文 +- 保存 session +- 建议 compact +- 格式化代码 +- TypeScript 检查 +- `console.log` 检查 +- 质量门禁 +- 成本跟踪 +- 从会话中提取可学习模式 + +配置在 `hooks/hooks.json`,实现主要在 `scripts/hooks/`。 + +### 5. 安装与适配层 + +它不是只服务 Claude Code,而是做了多平台适配: + +- `.claude-plugin/` 面向 Claude Code 插件 +- `.codex/` 面向 Codex +- `.cursor/` 面向 Cursor +- `.opencode/` 面向 OpenCode + +安装不是硬编码复制,而是 manifest 驱动的 profile/module/component 选择性安装,见: + +- `manifests/install-profiles.json` +- `manifests/install-components.json` +- `manifests/install-modules.json` + +## 主要功能 + +按功能看,这个项目覆盖面非常广: + +- `工程开发工作流` + 规划、TDD、代码评审、构建修复、E2E、覆盖率、重构清理、文档更新、质量门禁。 +- `多语言支持` + TypeScript、Python、Go、Java、Kotlin、Rust、Perl、PHP、Swift、C++ 等都有规则或技能包。 +- `安全能力` + 安全 reviewer、security-review skill、安全扫描、输入校验、secret 管理、提交前检查。 +- `上下文与记忆管理` + SessionStart/Stop hooks、pre-compact、strategic compact、持续学习、instinct import/export/evolve。 +- `多代理编排` + worktree/tmux orchestration、multi-plan、multi-execute、loop-start、loop-status、PM2 工作流。 +- `研究与内容能力` + deep-research、market-research、article-writing、investor-materials、investor-outreach、crosspost、x-api。 +- `媒体与文档能力` + frontend-slides、fal-ai-media、video-editing、visa-doc-translate、document-processing 类技能。 +- `运行状态与诊断` + `ecc` CLI 支持 `install/plan/list-installed/doctor/repair/status/sessions/session-inspect/uninstall`。 + +## 这个仓库的实际架构 + +你可以把它理解成下面这条链路: + +用户请求 +→ 命令或 AGENTS 指令触发 +→ 选择合适 agent / skill / rule +→ hooks 在关键时机做自动检查与状态保存 +→ scripts 负责真正执行安装、审计、诊断、状态查询 +→ 不同平台目录把同一套能力映射到 Claude / Codex / Cursor / OpenCode + +这也是为什么它看起来像“文档很多”,但其实不是文档仓库。Markdown 只是配置载体,真正的产品能力来自: + +- 结构化规则 +- 可组合技能 +- 自动化 hooks +- 安装与运行时脚本 +- 测试和校验链 + +## 最值得注意的几个特点 + +- 它强调“agent-first”,不是单 agent 直接硬做,而是主动委派给 planner、reviewer、security-reviewer 等角色。 +- 它强调“research-first”和“verification-first”,不是只生成代码,还要求验证、评审、学习、沉淀。 +- 它已经从 Claude Code 配置包,演化成“AI agent harness performance system”。 +- 它支持“按需安装”,不是所有用户都要装全量能力。 +- 它把“经验”产品化了:把作者长期使用中总结的流程,固化成规则、命令、hook 和技能。 + +## 适合什么人用 + +最适合这几类人: + +- 想把 Claude Code / Codex / Cursor 调成稳定工程助手的个人开发者 +- 想给团队统一 AI 编码规范和工作流的技术负责人 +- 需要多语言、多框架、多工具链支持的工程团队 +- 想做 AI agent orchestration、持续学习、自动质量门禁的人 + +## 一句话总结 + +这个项目是在做一套“给 AI 编码代理装上的工程操作系统”。它不是帮你开发某个业务功能,而是帮你把 AI 开发这件事本身标准化、自动化、可复用、可审计。 + +## AI 代码正确性保障与自动化测试 + +这个项目保证“AI 生成代码正确”的方式,不是靠某一个单点机制,而是靠一整套分层校验体系。核心思路是:先用规则约束 AI 的行为,再用 hooks 做即时检查,再用命令触发系统性验证,最后用测试和覆盖率把这些机制本身也测住。 + +先说结论:它并不能“数学上保证” AI 代码一定正确,但它把常见错误尽量前移、自动化、制度化了。也就是说,它主要保证的是“高概率正确 + 尽早暴露问题 + 可重复验证”,而不是一次生成就绝对无误。 + +### 一、它如何保证 AI 代码更靠谱 + +#### 1. 规则约束 + +仓库把 TDD 设成默认工作方式,明确要求先写测试,再写实现,再验证覆盖率,最低 80%。这不是建议,而是写进规则和 skill 的硬约束。也就是说,AI 理想状态下不是“先瞎写代码再补测试”,而是按 RED → GREEN → REFACTOR 的节奏工作。 + +#### 2. 任务分工 + +它鼓励把任务分给专门 agent,比如: + +- `tdd-guide` 负责测试优先 +- `code-reviewer` 负责改完后的质量检查 +- `security-reviewer` 负责敏感逻辑 +- `build-error-resolver` 负责构建和类型问题 + +这能降低一个 agent 同时负责“写代码、判断自己对不对、审查自己”的自我偏差。 + +#### 3. Hooks 即时纠偏 + +只要 AI 编辑文件,hooks 就会在后台做一些轻量但高频的自动检查,尽量在错误扩散前拦住。 + +#### 4. 人工触发的深度验证 + +比如 `/verify`、`/quality-gate`、`/test-coverage`、`/eval`,这些命令要求 AI 在关键节点主动跑构建、类型检查、lint、测试、覆盖率、安全扫描、差异审查。 + +#### 5. 项目自身也被测试 + +这个仓库不只是要求别人测试,它自己的 hook、安装器、manifest、命令和适配逻辑都有自动化测试和 CI 校验。 + +### 二、具体自动化机制有哪些 + +#### 1. TDD 机制 + +TDD 是第一道“正确性”防线。它要求: + +- 先写测试 +- 先运行并确认测试失败 +- 再写最小实现让测试通过 +- 再重构 +- 最后检查覆盖率是否达到 80%+ + +它强调三类测试都需要: + +- 单元测试:函数、组件、工具方法 +- 集成测试:API、数据库、服务交互 +- E2E 测试:关键用户路径 + +这意味着它不是只关心“代码能跑”,而是要求对行为、边界条件、错误路径都建立测试样例。 + +#### 2. 编辑后的自动 hook 检查 + +这是最接近“实时守门员”的部分。 + +- `post-edit-format` + 文件编辑后自动格式化 JS/TS,支持 Biome 或 Prettier。 +- `post-edit-typecheck` + 编辑 `.ts/.tsx` 后自动找最近的 `tsconfig.json`,跑 `tsc --noEmit`,并尽量只过滤出和当前文件相关的错误。 +- `quality-gate` + 编辑后跑轻量质量门禁。对不同语言用不同工具: + - JS/TS/JSON/MD 走 Biome 或 Prettier + - Go 走 `gofmt` + - Python 走 `ruff format` +- `check-console-log` + 每次响应结束时检查已修改的 JS/TS 文件里是否残留 `console.log`。 + +这一层解决的是“写完马上出问题”的场景,比如格式错、类型错、调试语句没删掉。 + +#### 3. 系统化验证命令 + +最核心的是 `/verify`。它要求按顺序做: + +1. Build Check +2. Type Check +3. Lint Check +4. Test Suite +5. Security / Secrets / `console.log` 审计 +6. Git diff 审查 + +这里的关键点不是“有这些命令”,而是顺序。比如 build 都不过,就不应该继续往下假装验证通过。 + +另外还有两个辅助命令: + +- `/quality-gate` + 按路径或项目范围手动执行质量管线,适合在 hook 之外主动检查。 +- `/test-coverage` + 专门做覆盖率分析,找出低于 80% 的文件,并按缺口补测试。 + +这说明它不把“测试通过”当成终点,还要求你看覆盖率盲区。 + +#### 4. Eval 机制 + +这是更偏 AI 工程的方法,不只是传统代码测试。 + +它引入几类概念: + +- `Capability eval` + AI 是否具备某个新能力 +- `Regression eval` + 新改动是否破坏旧行为 +- `pass@1 / pass@3 / pass^3` + 用来评估 AI 在多次尝试中的稳定性 + +这和普通单元测试不同。普通测试是“代码对不对”,eval 更像“AI 工作流整体是否稳定地产出对的结果”。 + +#### 5. 会话级持续学习与回放 + +这不是直接验证代码是否正确,但它能减少 AI 因“失忆”导致的错误重复。 + +- `session-start` + 会话开始时加载上次 session 摘要、已学习技能、项目类型等上下文。 +- `session-end` + 每次 Stop 时从 transcript 中提取用户请求、用过的工具、修改过的文件,写入 session 文件。 +- `evaluate-session` + 会话结束时判断这次对话里有没有可抽取的稳定模式,供后续沉淀成 skill。 + +这层对“正确性”的贡献是减少上下文断裂、避免同类错误反复出现。 + +### 三、这个仓库自己做了哪些自动化测试 + +这部分很关键。因为如果这些 hooks、命令、安装器本身不可靠,那整套“保障正确性”的系统就是空的。 + +当前仓库有 50+ 个测试文件,覆盖范围很广,测试类别大致分为: + +- `hooks 测试` + 覆盖 quality-gate、evaluate-session、auto-tmux-dev、hook flags 等行为。 +- `安装与配置测试` + 覆盖 install-plan、install-apply、manifest、install-state 等逻辑。 +- `CLI 和脚本测试` + 覆盖 `ecc`、`harness-audit`、`doctor`、`repair`、`session-inspect` 等命令。 +- `底层库测试` + 覆盖 formatter 解析、包管理器检测、项目类型识别、状态存储等基础能力。 +- `集成级测试` + 验证 hooks 和整体链路在组合情况下是否按预期工作。 + +### 四、除了业务测试,还有“结构正确性”校验 + +这个项目还有一类很实用的自动化:不是测业务逻辑,而是测仓库里的“配置资产”有没有坏掉。也就是 agents、commands、skills、rules、hooks 这些内容是否仍然有效。 + +`npm test` 里会先跑一串 validator,再跑测试,包括: + +- `validate-agents.js` + 检查 agent Markdown 是否有 frontmatter、必需字段、合法模型值。 +- `validate-commands.js` + 检查命令文档非空,以及引用的 command / agent / skill 是否存在。 +- `validate-rules.js` + 检查所有 rule 文件是否非空可读。 +- `validate-skills.js` + 检查每个技能目录是否有 `SKILL.md`。 +- `validate-hooks.js` + 检查 `hooks/hooks.json` 的 schema、事件名、matcher、hook 类型和字段是否合法。 + +这类测试很重要,因为 ECC 本身大量依赖 Markdown 和 JSON 配置文件。少一个字段、拼错一个 agent 名称,普通代码单测未必能及时发现,但 validator 能直接拦住。 + +### 五、覆盖率是怎么要求的 + +它明确要求 80%+ 覆盖率,这既出现在规则里,也出现在 npm 脚本里。 + +`package.json` 中的 `coverage` 脚本使用 `c8`,并设置了硬阈值: + +- lines 80 +- functions 80 +- branches 80 +- statements 80 + +也就是说,不是“跑个 coverage 看看”,而是没到门槛就失败。 + +### 六、它能保证“用户项目里的代码正确”到什么程度 + +这里要区分两件事: + +#### 1. ECC 仓库自身 + +它自己的 hooks、命令、安装器、适配层,是有自动化测试和覆盖率门槛的。 + +#### 2. 用户正在开发的业务项目 + +ECC 并不会天然知道你的业务逻辑是否正确。它做的是提供一套强制工作流,让 AI 去: + +- 先写测试 +- 跑构建、类型、lint、测试 +- 看 coverage +- 做 diff review +- 做安全检查 +- 必要时做 eval + +所以它对用户项目的保障,本质上是“把正确性验证流程自动化和制度化”,而不是“替代业务测试”。 + +换句话说,它更像质量系统,而不是万能判题器。 + +### 七、这套体系的优点和边界 + +优点很明确: + +- 错误暴露得更早,尤其是格式、类型、调试残留这种低级问题 +- AI 不容易跳过测试和验证步骤 +- 支持回归验证,不只是“这次能跑” +- 对复杂 agent 工作流有 eval 思维,不只盯着代码编译通过 +- 这个系统本身也被测试,不是空口宣言 + +但边界也很明确: + +- 它不能自动理解你的业务需求是否“真正满足用户意图” +- 没有业务测试数据时,它无法凭空证明正确性 +- 某些 hook 是“提醒/警告型”,不是强阻断 +- 很多质量检查依赖目标项目本身配置了 `build`、`lint`、`test`、`tsc`、formatter 等工具链 + +### 一句话总结 + +这个项目保证 AI 代码“更正确”的核心,不是靠单次生成更聪明,而是靠“测试优先 + 编辑后即时检查 + 提交前系统验证 + 覆盖率门槛 + eval + 仓库自身被充分测试”的组合拳。 + +## 自动化测试与验证方法总表 + +下表汇总了这个项目中主要的自动化测试与验证方法。这里的“测试”不仅包括传统单元测试,也包括构建检查、类型检查、质量门禁、配置校验、回归评估等自动化验证手段,因为 ECC 的目标本来就不是只测代码函数,而是保障整套 AI 工程流程的正确性。 + +| 什么测试 | 测试的方法 | 为什么要做这个测试 | 能解决什么问题 | +|---|---|---|---| +| 单元测试 | 对单个函数、工具方法、组件逻辑编写独立测试,用最小输入输出断言行为 | 最小粒度验证功能正确性,是发现逻辑错误最快的手段 | 解决函数实现错误、边界条件遗漏、重构后回归问题 | +| 集成测试 | 测 API、数据库、服务交互、模块间协作,验证请求到响应或服务到服务的完整链路 | 很多错误不在单个函数,而在模块之间的拼接处 | 解决接口联调失败、数据库交互错误、服务调用顺序问题 | +| E2E 测试 | 用 Playwright 等浏览器自动化测试关键用户流程 | 最终用户看到的是完整流程,不是单个函数 | 解决页面流程跑不通、按钮可点但业务不成功、前后端联通失败 | +| TDD 红绿重构测试 | 先写失败测试,再写最小实现让其通过,最后重构并保持测试为绿 | 强制 AI 先定义正确行为,再写实现,降低拍脑袋写代码的概率 | 解决“先写代码后补测试”导致的伪验证、需求理解偏差 | +| Build Check | 执行项目构建命令,先确认能完整 build | 如果项目连构建都过不了,其他验证意义很小 | 解决打包失败、缺依赖、构建配置错误、语法级阻断问题 | +| Type Check | 执行 `tsc --noEmit`、`pyright` 等类型检查 | AI 很容易写出语法正确但类型不一致的代码 | 解决类型不匹配、参数传错、返回值不符合约定的问题 | +| Lint Check | 执行 ESLint、Ruff 等静态检查 | 代码不仅要能跑,还要符合项目约定和最佳实践 | 解决潜在坏味道、危险写法、风格不一致、简单逻辑疏漏 | +| 覆盖率检查 | 用 `c8`、Vitest/Jest 覆盖率、pytest-cov 等统计并设置 80% 门槛 | 测试通过不等于测得充分,需要知道哪些代码根本没被触达 | 解决测试盲区、分支未覆盖、表面通过但风险仍高的问题 | +| `/verify` 全量验证 | 按固定顺序执行 build、types、lint、tests、安全检查、diff review | 需要一个统一、可复用的“提交前体检流程” | 解决只做局部检查、漏掉关键验证步骤的问题 | +| `/quality-gate` 质量门禁 | 对文件或项目范围手动执行格式、lint、类型等质量检查 | hook 是自动触发的,但需要人工随时重跑统一质量管线 | 解决改动较多时遗漏局部错误、需要集中复查的问题 | +| `/test-coverage` 覆盖率补强 | 分析低覆盖文件,定位缺失测试并补齐 | 覆盖率不足时,仅看总体数字不够,需要知道缺口在哪 | 解决“知道不够测,但不知道该补哪”的问题 | +| `/eval` 能力/回归评估 | 定义 capability eval 和 regression eval,并记录 pass@k | AI 工程中很多问题不是普通单测能完全表达的 | 解决 prompt/agent 变化后的能力退化、稳定性不足问题 | +| Capability Eval | 为一个新能力定义成功标准并自动检查是否达成 | AI 需要被验证“会不会做这件事”,而不只是“代码能不能跑” | 解决新增能力不可度量、结果模糊、是否达标难判断的问题 | +| Regression Eval | 为已有能力定义基线,更新后重新验证 | 新功能上线最常见的风险是破坏旧功能 | 解决历史行为被破坏、升级后退化、版本回归问题 | +| pass@k / pass^k 评估 | 多次尝试统计成功率和稳定性 | AI 输出存在波动,单次成功不能说明真正可靠 | 解决“偶尔成功但不稳定”的假可靠问题 | +| 编辑后自动格式化 | `post-edit-format` 在文件编辑后自动运行 Biome/Prettier | 很多低级问题不该等到人工发现 | 解决格式漂移、代码风格不统一、格式导致的 review 噪音 | +| 编辑后自动类型检查 | `post-edit-typecheck` 在编辑 TS 文件后自动执行局部类型检查 | 越早看到类型错误,修复成本越低 | 解决刚编辑完就引入的类型错误,避免后续扩散 | +| 编辑后自动质量门禁 | `quality-gate` 按文件类型执行 Biome/Prettier/gofmt/ruff | 需要低延迟的自动化守门,尽快把错误暴露给 AI | 解决语言级格式/质量问题,减少提交前集中爆炸 | +| `console.log` 审计 | Stop hook 自动扫描修改文件中的调试输出 | AI 和人类一样,都会忘删临时调试代码 | 解决调试日志残留、噪音输出、生产代码不干净的问题 | +| 安全扫描 | 搜索 secrets、危险模式,必要时配合安全 skill / reviewer | AI 生成代码时常会忽视 secrets、输入验证等安全问题 | 解决密钥泄漏、明显安全疏漏、调试信息暴露问题 | +| Git diff 审查 | 自动查看变更文件和 diff 范围 | 仅看最终代码不够,需要知道到底改了什么 | 解决误改文件、无关改动混入、遗漏清理的问题 | +| Session Start / End 验证链 | 会话开始加载上下文,会话结束提取摘要、记录变更和工具使用 | AI 的错误很多来自上下文断裂,而不是实现能力本身 | 解决跨会话失忆、重复犯错、接手历史任务时上下文缺失 | +| 持续学习评估 | `evaluate-session` 根据会话长度和内容判断是否可提炼模式 | 好的解决方案应沉淀成可复用能力,而不是每次重学 | 解决经验无法积累、同类问题重复探索的问题 | +| Hook 配置校验 | `validate-hooks.js` 校验 `hooks.json` schema、事件、字段、hook 类型 | hook 是自动化核心,配置一坏,整套机制就失效 | 解决 hook 配置拼写错误、事件名错误、字段不合法的问题 | +| Agent 配置校验 | `validate-agents.js` 校验 agent frontmatter、必填字段、模型合法性 | agent 定义是编排基础,损坏后会直接影响 AI 工作流 | 解决 agent 元数据缺失、配置非法、引用失败的问题 | +| Command 文档校验 | `validate-commands.js` 检查命令文档非空,且引用的 command/agent/skill 存在 | 命令是用户入口,文档失真会导致执行流程错误 | 解决命令引用失效、文档和真实能力脱节的问题 | +| Skill 结构校验 | `validate-skills.js` 校验每个技能目录都存在 `SKILL.md` | skill 是核心知识单元,结构必须稳定 | 解决 skill 缺失、目录不完整、安装后不可用的问题 | +| Rule 文件校验 | `validate-rules.js` 检查规则文件是否可读且非空 | 规则是 AI 行为约束基础,空文件等于失效 | 解决规则丢失、空规则、安装后行为退化的问题 | +| 安装器测试 | 测 `install-plan`、`install-apply`、manifest、install-state 等逻辑 | 安装层错误会让整个系统装不对、装不全、装错位置 | 解决 selective install 失效、路径错误、状态记录异常 | +| CLI 测试 | 测 `ecc`、`doctor`、`repair`、`harness-audit`、`sessions` 等脚本 | CLI 是用户直接操作系统的入口,必须可靠 | 解决命令行参数解析错误、输出不符合预期、功能失效 | +| Hook 脚本测试 | 对 `quality-gate`、`evaluate-session`、`auto-tmux-dev` 等脚本做独立测试 | hook 运行频率高,任何错误都会被快速放大 | 解决 hook 误报、漏报、跨平台行为不一致的问题 | +| 集成级 hook 测试 | 将多个 hook 或相关脚本组合起来验证完整链路 | 单个模块正确,不代表组合后仍然正确 | 解决组合行为异常、事件触发顺序错误、整体链路不通的问题 | +| 状态存储测试 | 测 session aliases、state store、install state 等持久化逻辑 | ECC 很依赖状态记录来支持连续工作 | 解决状态写坏、会话恢复失败、安装状态漂移的问题 | +| 工具解析测试 | 测 formatter 检测、包管理器检测、项目类型识别等基础能力 | 自动化链路依赖环境探测,探测错了后续全错 | 解决检测错误导致执行了错误工具、走错工作流的问题 | +| Harness 审计 | `harness-audit` 检查仓库在工具覆盖、上下文效率、质量门禁等维度是否达标 | 需要从系统层面评估一个 AI harness 是否“配齐了” | 解决功能缺失、能力不完整、质量体系不闭环的问题 | + +### 如何理解这张表 + +这张表里的方法可以分成四组: + +- `开发前与开发中` + TDD、单元测试、集成测试、E2E、编辑后 hooks。 +- `提交前与交付前` + `/verify`、`/quality-gate`、覆盖率、安全扫描、diff review。 +- `AI 工程专项` + `/eval`、Capability Eval、Regression Eval、pass@k、持续学习。 +- `ECC 自身质量` + validators、hook tests、CLI tests、install tests、state/store tests、harness audit。 + +也就是说,这个项目不是只在“代码写完以后”才测,而是把测试和验证铺在了整个 AI 开发生命周期里。