@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/testing/REGRESSION_PLAN.md

@@ -0,0 +1,28 @@
+# 回归计划
+
+**功能 / 发布版本**:
+**最后更新**:
+**负责人**:
+
+## 受影响测试
+
+-
+
+## 影响面
+
+- 直接影响:
+- 间接影响:
+- 相关接口 / 契约:
+- 相关页面 / 路由:
+- 潜在风险:
+
+## P0 回归集合
+
+-
+
+## 发布证据
+
+- verify 摘要:
+- 契约验证:
+- e2e smoke:
+- 视觉一致性:

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/testing/TEST_STRATEGY.md

@@ -0,0 +1,98 @@
+# 测试策略
+
+**功能 / 项目**:
+**最后更新**:
+**负责人**:
+
+## 测试层级
+
+- 单元:
+- 组件:
+- API / 契约:
+- 集成:
+- E2E:
+- 视觉:
+
+## 开发验证与验收验证分层
+
+Harness 把实现过程中的快速反馈和交付前的完整验收拆成两个独立闸门:
+
+| 闸门 | 目的 | 典型验证 | 完成条件 |
+| --- | --- | --- | --- |
+| 自然语言测试用例 | 把 PRD 每条需求转成可审查、可追溯、可转脚本的测试用例 | `NATURAL_LANGUAGE_TEST_CASES.md`、需求类型覆盖矩阵、Gherkin/步骤化用例、Oracle、测试数据、证据路径、TDD RED 预期失败 | 每条需求都要分类；P0/P1 按需求类型满足最小用例数；P2 需写用例或豁免原因；TDD 候选用例可被 `tdd_contract.red.source_case_ids` 引用 |
+| TDD RED | 在生产代码变更前证明新增或变更行为当前缺失 | 聚焦单元、组件、契约或 API 测试；必须先失败且失败原因匹配预期 | 作为 `tdd_contract.red` 证据进入任务；失败原因不是目标行为缺失时不得进入实现 |
+| TDD GREEN / REFACTOR | 用最小实现让同一聚焦测试通过，并在重构后保持相关验证绿色 | 同一 focused test、affected tests、coverage、lint 或类型检查 | 作为 `tdd_contract.green` 和 `tdd_contract.refactor_guard` 证据进入任务；不能替代最终验收 |
+| 开发验证 | 支撑编码过程中的快速反馈，证明局部改动没有破坏直接相关行为 | 单元、组件、局部 API、契约检查、affected tests、静态检查、类型检查、lint | 作为实现过程证据进入 `development_validation`，但不能单独声明任务完成 |
+| 验收验证 | 从用户、业务闭环或发布候选视角证明当前交付可被验收 | 用户故事完整链路、跨故事主流程、真实入口 E2E、数据副作用、失败态、P0/P1 回归、视觉/可访问性确认 | 作为完成前 fresh evidence 进入 `acceptance_validation`，缺失时任务必须 BLOCKED 或有 owner 批准的 exemption |
+
+开发验证通过只说明局部实现可继续推进，不等于用户验收通过。PRD 完成后、进入实现前必须先生成自然语言测试用例；每个 `feature_impl` 默认要求 TDD：从自然语言用例选择 TDD 候选，先写聚焦测试并确认 RED 失败，再写最小实现确认 GREEN，通过后才允许重构。每个 `feature_impl` 完成前必须在代码写完后重新运行故事级验收链路；每个 `release` 完成前必须运行发布候选级跨故事验收链路。验收验证不得直接复用编码中途的旧日志，除非证据协议明确证明其仍是当前变更集的 fresh evidence。
+
+## 自然语言用例规模规则
+
+自然语言测试用例不是每条需求固定写 1 条，而是先判定需求类型，再按 `NATURAL_LANGUAGE_TEST_CASES.md` 的覆盖矩阵取最小用例数。基础原则:
+
+- P0 需求默认不少于 5 条，P1 需求默认不少于 3 条，P2 可为 1-2 条并说明不进入 TDD 候选的原因。
+- 低于默认数量必须写明豁免原因、替代证据和 owner 批准人。
+- 只读查询至少覆盖正常、空数据和无权限；列表类还要覆盖筛选、分页、排序或组合条件。
+- 新增、编辑、删除等写操作至少覆盖成功副作用、输入失败、权限失败无副作用、非法状态或并发冲突。
+- 权限、状态机、异步链路、外部系统、金额库存、文件处理和安全需求必须按风险路径加量，不能只写 happy path。
+- 一个需求跨多个类型时，按风险最高类型取基准，再补齐其他类型的必需路径。
+- TESTCASE 阶段必须在覆盖检查表中写明“需求类型、风险因子、矩阵基准用例数、风险加量、最终要求用例数、已写用例数、加量理由”，不足时不得进入 `feature_impl`。
+- 非 TDD 自然语言用例必须映射到 `story_full_chain`、`acceptance_validation`、回归或 `verify-matrix`，不能因为不适合作为 RED 种子就从验收链路消失。
+- 业务规则如果会影响状态流转、副作用、金额/库存、权限或幂等，必须至少有一条异常路径或无副作用路径用例。
+
+## QA Harness 最小闭环
+
+测试设计按下面顺序推进，不允许直接从需求跳到测试脚本:
+
+1. 资料输入: 读取需求、代码、API 契约、UI、数据模型、权限规则和历史缺陷。
+2. 风险建模: 输出业务实体、状态、角色权限、接口、数据副作用和外部依赖风险。
+3. 自然语言用例: 按 PRD / Requirement ID 识别需求类型和风险因子，按覆盖矩阵写出目标、来源、前置条件、动作、预期结果、Oracle、测试数据、证据路径和 TDD RED 预期失败。
+4. 测试意图: 将自然语言用例映射到测试层级、风险、数据和可执行验证命令。
+5. Oracle 审查: 通过后才生成或修改测试脚本。
+6. TDD RED: `feature_impl` 从 `NATURAL_LANGUAGE_TEST_CASES.md` 的 TDD 候选用例生成聚焦测试，运行 `tdd_contract.red.command`，确认失败原因匹配目标行为缺失并记录证据。
+7. TDD GREEN: 写最小实现后运行 `tdd_contract.green.command`，确认同一聚焦测试通过。
+8. TDD REFACTOR: 重构后运行 `tdd_contract.refactor_guard.command` 和必要覆盖率命令，确认相关验证仍通过。
+9. 开发验证: 编码过程中运行 affected tests、局部契约、类型检查、lint 或单元 / 组件测试，记录 `development_validation` 证据。
+10. 验收验证: 代码写完后从用户、业务闭环或发布候选视角运行完整链路，记录 `acceptance_validation` fresh evidence。
+11. 证据归档: 把命令、退出码、日志、截图、DB diff、事件、Trace 等写入证据路径。
+12. 失败归因: 区分产品缺陷、测试缺陷、环境问题和数据问题。
+13. 回归沉淀: 真实缺陷修复后补充回归用例或知识候选。
+
+## Oracle 优先规则
+
+每个测试用例必须在写脚本前定义至少一个业务 Oracle。写接口、状态流转、权限和数据一致性场景通常需要多个 Oracle 组合:
+
+| Oracle 类型 | 适用场景 | 最小要求 |
+| --- | --- | --- |
+| 返回值 | API、服务、UI 动作 | 状态码、错误码、关键字段和业务语义 |
+| Schema / Contract | API、事件、文件 | 字段类型、必填、枚举、版本兼容 |
+| 数据库副作用 | POST / PUT / PATCH / DELETE、批处理 | before / after diff、目标字段变化、非目标字段不变 |
+| 缓存 | 读写缓存、权限缓存、多租户 | key 维度、TTL、失效、跨用户隔离 |
+| 事件 / 队列 | 异步链路、Webhook、消息消费 | event type、payload、重试、幂等、DLQ |
+| 审计 | 登录、权限、资金、删除、审批 | actor、action、object、result、time |
+| 权限 | 水平越权、垂直越权、字段级权限 | 允许 / 拒绝符合权限矩阵，拒绝时无副作用 |
+| 状态机 | 订单、审批、发布、退款等状态流转 | 合法转移成功，非法转移失败且无污染 |
+| 不变量 | 金额、库存、次数、唯一性 | 余额 / 库存不为负，总额守恒，唯一业务结果 |
+| Trace / 证据 | E2E、集成、跨服务 | 命中预期链路、日志或 coverage 可证明目标路径 |
+
+## 假测试拦截规则
+
+Stage 2 必须拦截下列测试:
+
+- 只断言 `200`、`truthy`、元素存在或 snapshot，没有业务断言。
+- 写操作没有 DB、缓存、事件、审计、文件或通知等副作用断言。
+- 权限失败只断言 `403`，没有验证目标数据未变化、响应未泄露和缓存未污染。
+- mock 了当前被测 service、权限判断、状态机、数据库写入或核心业务路径。
+- 没有绑定 Requirement ID、代码分支、API 契约、安全风险、状态机转移或历史缺陷来源。
+- 没有执行证据，或证据不是当前变更集产生的 fresh evidence。
+- 测试名称覆盖多个路径，但实际只跑 happy path。
+
+## 阻塞性失败
+
+-
+
+## Fresh Evidence 策略
+
+- Stage 17 只确认 fresh evidence 和回归状态。
+- 缺少验收示例或需求追溯属于实现前缺口，不是 Stage 17 的任务。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/testing/TRACEABILITY_MATRIX.md

@@ -0,0 +1,23 @@
+# 需求追溯矩阵
+
+**功能**:
+**最后更新**:
+**负责人**:
+
+| Req ID | 业务规则 | 页面 / 组件 | 状态 | API / 契约 | 数据 / 副作用 | Oracle | 测试层级 | 测试文件 / 计划 | 证据路径 | 风险 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| REQ-001 | | | 默认 | | | response + db | unit / component / api / e2e | | | P0 |
+| PKG-LAYER-P5-MIGRATE-APPLY | `-MigrateApply` 必须 plan-first、默认 dry-run、`-Confirm` 后只采纳 hash 一致 vendor 文件；drift/unknown/manual-review 阻断写入。 | CLI / PowerShell installer | legacy full / drift / unknown / missing / manual-review / thin no-op | `docs/agent-package-redesign/migration-plan.md`, `docs/harness/install-manifest-governance.md` | `.codex-harness/locks/package.lock.json`, `.agents/`, legacy docs；失败态 lock 不变且不删除文件 | command output + lock hash/managedFiles + no-side-effect filesystem evidence | integration | `tools/harness/tests/test-install-modes.ps1`; `TC-PKG-LAYER-P5-APPLY-001..006` | `traces/`, test-install-modes 输出, doctor 输出, refresh CheckOnly 输出 | P1 |
+| PKG-LAYER-P6-READINESS | doctor readiness gate 必须只读区分 thin、legacy、vendor 和未安装项目并给出修复建议。 | CLI / doctor | thin clean / legacy residue / missing user package / vendor / no config | `docs/architecture/constraints.md`, `docs/harness/install-manifest-governance.md` | 文件系统只读；不得自动安装、迁移或删除 | doctor output + unchanged files + readiness fix command | integration | `tools/harness/tests/test-install-modes.ps1`; `TC-PKG-LAYER-P6-READINESS-001..005`; `docs/testing/TEST_DATA_MATRIX.md` | `traces/LAYERING-P6-READINESS-001/`, doctor 输出, smoke 输出 | P1 |
+| PKG-LAYER-P7-DEFAULT-THIN | 默认无参数安装必须输出 thin project，同时保留显式 legacy full/vendor/user 入口，并保证公开 plan 与实际输出一致。 | CLI / installer | default thin / explicit legacy full / vendor / user/project scope / thin plan / legacy plan | `docs/agent-package-redesign/target-layering-standard.md`, `docs/harness/new-project-usage.md` | `.codex-harness/`, `.codex/`, docs/spec；默认不得复制完整 `.agents`；plan 命令只读 | required/forbidden path assertions + plan output + package lock/config + doctor output | integration | `tools/harness/tests/test-install-modes.ps1`; `TC-PKG-LAYER-P7-DEFAULT-THIN-001..006`; `docs/testing/TEST_DATA_MATRIX.md` | `traces/LAYERING-P7-DEFAULT-THIN-001/`, test-install-modes 输出, doctor 输出, verify 输出 | P1 |
+| PKG-LAYER-P8-CLI-ALIAS | 首选 install-user/init-project 入口必须调用现有 install-agent scope 语义或明确文档化等价入口，不得出现第二套安装逻辑。 | CLI / docs | wrapper path / documented equivalent / no double implementation | `docs/harness/new-project-usage.md`, `docs/agent-package-redesign/target-layering-standard.md` | 输出与 `-Scope user/project` 一致；manifest/lock/doctor 不被绕过 | command output or doc assertion + smoke equivalence | integration / doc check | `tools/harness/tests/test-install-modes.ps1`; `TC-PKG-LAYER-P8-CLI-ALIAS-001..003`; `docs/testing/TEST_DATA_MATRIX.md` | `traces/`, new-project-usage.md, refresh CheckOnly 输出 | P1 |
+
+## 规则
+
+- 每条 P0/P1 需求都必须恰好出现一次，或被明确拆分。
+- 每一行都必须指向至少一个测试层级和一个证据路径。
+- UI 行必须包含所需状态或明确豁免。
+- API / 数据行必须包含契约或 schema 校验证据。
+- 写操作、权限失败、非法状态流转和异步链路必须包含副作用或无副作用 Oracle。
+- 每条 P0/P1 业务规则至少要在矩阵中出现一次，并绑定页面状态、Oracle 和测试层级。
+- 缺少 Oracle 或证据路径的 P0/P1 行不能进入实现。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/testing/verify-matrix.md

@@ -0,0 +1,51 @@
+# 验证矩阵
+
+**功能**:
+**任务 ID**:
+**生成时间**:
+
+| 检查项 | 命令 / 证据 | 必需 | 退出码 / 结论 | 报告路径 |
+| --- | --- | --- | --- | --- |
+| 验收 / 示例 | `ACCEPTANCE_EXAMPLES.md` + `ACCEPTANCE_CRITERIA.md` | P0/P1 必需 | | |
+| 追溯 | `TRACEABILITY_MATRIX.md` | P0/P1 必需 | | |
+| 静态检查 | `git diff --check` | 必需 | | |
+| 类型检查 | | 项目相关 | | |
+| Lint | | 项目相关 | | |
+| 开发验证 | affected tests / unit / component / local contract / typecheck / lint | 代码变更时必需 | | |
+| 单元 | | 代码变更时必需 | | |
+| 组件 | | UI 变更时必需 | | |
+| 契约 | | API / 数据变更时必需 | | |
+| API 集成 | | 后端变更时必需 | | |
+| Oracle 审查 | `TEST_STRATEGY.md` + `test-matrix.md` | P0/P1 / 高风险必需 | | |
+| 副作用断言 | DB diff / cache / event / audit / file evidence | 写操作、状态流转、异步必需 | | |
+| 状态唯一来源检查 | `frontend-architecture.md` 状态表 + CURRENT_TASK 状态决策 | UI / 表单 / 查询状态变更时必需 | | |
+| 缓存失效检查 | cache key / invalidate 证据 / refetch 结果 | 远程数据、列表、详情、统计变更时必需 | | |
+| 权限无副作用 | denied response + unchanged data + no leak | 权限 / 多租户必需 | | |
+| 输入校验检查 | schema / validator + invalid payload response | API / 表单 / 文件上传时必需 | | |
+| 敏感信息脱敏检查 | response/log/trace redaction evidence | 涉及账号、支付、PII、密钥时必需 | | |
+| 风控 / 限流检查 | rate limit / captcha / idempotency evidence | 登录、注册、验证码、支付、上传等高风险入口必需 | | |
+| 假测试检测 | Stage 2 review | 测试改动时必需 | | |
+| 受影响测试 | changed-code-related tests | 业务逻辑变更时必需 | | |
+| 用户验收链路 | story entry + action + business Oracle + side effect / no-side-effect evidence | feature_impl 完成前必需 | | |
+| E2E | | P0/P1 主流程变更时必需 | | |
+| P0 回归 | 核心 P0 场景 | 发布前必需 | | |
+| 发布候选验证 | cross-story flow + P0/P1 regression + contract/API + E2E/visual as applicable | release 完成前必需 | | |
+| 失败态验收 | negative path / denied path / invalid state / downstream failure evidence | P0/P1 / 高风险必需 | | |
+| 视觉一致性 | `visual-parity-review.md` | UI 变更时必需 | | |
+| 覆盖率 | `coverage-summary.json` | 如策略适用 | | |
+| PKG-LAYER-P5-MIGRATE-APPLY 自然语言用例 | `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md` 中 `TC-PKG-LAYER-P5-APPLY-001..006` | P1 必需 | planned | `traces/`, `tools/harness/tests/test-install-modes.ps1` |
+| PKG-LAYER-P5-MIGRATE-APPLY TDD RED/GREEN/REFACTOR | `tools/harness/tests/test-install-modes.ps1` 先补迁移执行失败断言，再实现通过 | P1 必需 | planned | `traces/` |
+| PKG-LAYER-P5-MIGRATE-APPLY 验收链路 | clean legacy full、drift、unknown、missing vendor、manual-review、thin no-op smoke | P1 必需 | planned | `traces/`, doctor 输出, refresh CheckOnly 输出 |
+| PKG-LAYER-P6-READINESS 自然语言用例 | `TC-PKG-LAYER-P6-READINESS-001..005` 覆盖 thin clean、missing user package、legacy residue、vendor、no config | P1 必需 | verified | `traces/LAYERING-P6-READINESS-001/`, doctor/test-install-modes 输出 |
+| PKG-LAYER-P6-READINESS 测试数据矩阵 | `docs/testing/TEST_DATA_MATRIX.md` 中 `readiness-thin-clean`、`readiness-missing-user-package`、`readiness-legacy-residue`、`readiness-vendor-lock`、`readiness-no-config` | P1 必需 | verified | `traces/LAYERING-P6-READINESS-001/`, `tools/harness/tests/test-install-modes.ps1` |
+| PKG-LAYER-P7-DEFAULT-THIN 自然语言用例 | `TC-PKG-LAYER-P7-DEFAULT-THIN-001..006` 覆盖默认 thin、显式 legacy full、project/vendor/user scope、thin plan 和 legacy plan | P1 必需 | verified | `traces/LAYERING-P7-DEFAULT-THIN-001/`, test-install-modes 输出 |
+| PKG-LAYER-P7-DEFAULT-THIN 测试数据矩阵 | `docs/testing/TEST_DATA_MATRIX.md` 中 `p7-default-thin-install`、`p7-legacy-full-install`、`p7-scope-project-install`、`p7-scope-vendor-install`、`p7-scope-user-install`、`p7-install-plan-profiles` | P1 必需 | verified | `traces/LAYERING-P7-DEFAULT-THIN-001/`, `tools/harness/tests/test-install-modes.ps1` |
+| PKG-LAYER-P8-CLI-ALIAS 自然语言用例 | `TC-PKG-LAYER-P8-CLI-ALIAS-001..003` 覆盖等价入口、install-user wrapper、init-project wrapper 和 no-double-implementation 风险 | P1 必需 | planned | `traces/LAYERING-P8-CLI-ALIAS-001/`, docs/harness/new-project-usage.md |
+| PKG-LAYER-P8-CLI-ALIAS 测试数据矩阵 | `docs/testing/TEST_DATA_MATRIX.md` 中 `p8-install-user-wrapper`、`p8-init-project-wrapper`、`p8-wrapper-no-double-implementation` | P1 必需 | planned | `traces/LAYERING-P8-CLI-ALIAS-001/`, `tools/harness/tests/test-install-modes.ps1` |
+
+## 最终规则
+
+最终交付要求每一行必需项都有 fresh evidence，或提供明确的 BLOCKED / exemption 记录并获得 owner 批准。
+开发验证和验收验证是两类独立证据：单元、组件、局部 smoke、类型检查、lint 或 affected tests 不能替代用户验收链路；各子任务局部测试通过也不能替代发布候选验证。
+用户验收链路、发布候选验证和失败态验收必须在实现完成后以当前变更集重新运行，证据需要能回溯到 Requirement ID、入口、测试数据、Oracle 和证据路径。
+Stage 17 只应确认新鲜度与回归状态；缺失的验收示例或首次测试范围定义不应在这里补写。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/AGENTS.md

@@ -0,0 +1,165 @@
+# Everything Claude Code (ECC) — 智能体指令
+
+这是一个**生产就绪的 AI 编码插件**，提供 48 个专业代理、183 项技能、79 条命令以及自动化钩子工作流，用于软件开发。
+
+**版本:** 1.10.0
+
+## 核心原则
+
+1. **智能体优先** — 将领域任务委托给专业智能体
+2. **测试驱动** — 先写测试再实现，要求 80%+ 覆盖率
+3. **安全第一** — 绝不妥协安全；验证所有输入
+4. **不可变性** — 总是创建新对象，永不修改现有对象
+5. **先规划后执行** — 在编写代码前规划复杂功能
+
+## 可用智能体
+
+| 代理 | 用途 | 使用时机 |
+|-------|---------|-------------|
+| planner | 实现规划 | 复杂功能、重构 |
+| architect | 系统设计与可扩展性 | 架构决策 |
+| tdd-guide | 测试驱动开发 | 新功能、错误修复 |
+| code-reviewer | 代码质量与可维护性 | 编写/修改代码后 |
+| security-reviewer | 漏洞检测 | 提交前、敏感代码 |
+| build-error-resolver | 修复构建/类型错误 | 构建失败时 |
+| e2e-runner | 端到端 Playwright 测试 | 关键用户流程 |
+| refactor-cleaner | 死代码清理 | 代码维护 |
+| doc-updater | 文档和代码地图更新 | 更新文档时 |
+| docs-lookup | 文档和 API 参考研究 | 库/API 文档问题 |
+| cpp-reviewer | C++ 代码审查 | C++ 项目 |
+| cpp-build-resolver | C++ 构建错误 | C++ 构建失败 |
+| go-reviewer | Go 代码审查 | Go 项目 |
+| go-build-resolver | Go 构建错误 | Go 构建失败 |
+| kotlin-reviewer | Kotlin 代码审查 | Kotlin/Android/KMP 项目 |
+| kotlin-build-resolver | Kotlin/Gradle 构建错误 | Kotlin 构建失败 |
+| database-reviewer | PostgreSQL/Supabase 专家 | 模式设计、查询优化 |
+| python-reviewer | Python 代码审查 | Python 项目 |
+| java-reviewer | Java 和 Spring Boot 代码审查 | Java/Spring Boot 项目 |
+| java-build-resolver | Java/Maven/Gradle 构建错误 | Java 构建失败 |
+| chief-of-staff | 沟通分类与草拟 | 多渠道邮件、Slack、LINE、Messenger |
+| loop-operator | 自主循环执行 | 安全运行循环、监控停滞、干预 |
+| harness-optimizer | Harness 配置调优 | 可靠性、成本、吞吐量 |
+| rust-reviewer | Rust 代码审查 | Rust 项目 |
+| rust-build-resolver | Rust 构建错误 | Rust 构建失败 |
+| pytorch-build-resolver | PyTorch 运行时/CUDA/训练错误 | PyTorch 构建/训练失败 |
+| typescript-reviewer | TypeScript/JavaScript 代码审查 | TypeScript/JavaScript 项目 |
+
+## 智能体编排
+
+主动使用智能体，无需用户提示：
+
+* 复杂功能请求 → **planner**
+* 刚编写/修改的代码 → **code-reviewer**
+* 错误修复或新功能 → **tdd-guide**
+* 架构决策 → **architect**
+* 安全敏感代码 → **security-reviewer**
+* 多渠道沟通分流 → **chief-of-staff**
+* 自主循环 / 循环监控 → **loop-operator**
+* 线束配置可靠性及成本 → **harness-optimizer**
+
+对于独立操作使用并行执行 — 同时启动多个智能体。
+
+## 安全指南
+
+**在任何提交之前：**
+
+* 没有硬编码的密钥（API 密钥、密码、令牌）
+* 所有用户输入都经过验证
+* 防止 SQL 注入（参数化查询）
+* 防止 XSS（已清理的 HTML）
+* 启用 CSRF 保护
+* 已验证身份验证/授权
+* 所有端点都有限速
+* 错误消息不泄露敏感数据
+
+**密钥管理：** 绝不硬编码密钥。使用环境变量或密钥管理器。在启动时验证所需的密钥。立即轮换任何暴露的密钥。
+
+**如果发现安全问题：** 停止 → 使用 security-reviewer 智能体 → 修复 CRITICAL 问题 → 轮换暴露的密钥 → 审查代码库中的类似问题。
+
+## 编码风格
+
+**不可变性（关键）：** 总是创建新对象，永不修改。返回带有更改的新副本。
+
+**文件组织：** 许多小文件优于少数大文件。通常 200-400 行，最多 800 行。按功能/领域组织，而不是按类型组织。高内聚，低耦合。
+
+**错误处理：** 在每个层级处理错误。在 UI 代码中提供用户友好的消息。在服务器端记录详细的上下文。绝不静默地忽略错误。
+
+**输入验证：** 在系统边界验证所有用户输入。使用基于模式的验证。快速失败并给出清晰的消息。绝不信任外部数据。
+
+**代码质量检查清单：**
+
+* 函数小巧（<50 行），文件专注（<800 行）
+* 没有深层嵌套（>4 层）
+* 适当的错误处理，没有硬编码的值
+* 可读性强、命名良好的标识符
+
+## 测试要求
+
+**最低覆盖率：80%**
+
+测试类型（全部必需）：
+
+1. **单元测试** — 单个函数、工具、组件
+2. **集成测试** — API 端点、数据库操作
+3. **端到端测试** — 关键用户流程
+
+**TDD 工作流（强制）：**
+
+1. 先写测试（RED） — 测试应该失败
+2. 编写最小实现（GREEN） — 测试应该通过
+3. 重构（IMPROVE） — 验证覆盖率 80%+
+
+故障排除：检查测试隔离 → 验证模拟 → 修复实现（而不是测试，除非测试是错误的）。
+
+## 开发工作流
+
+1. **规划** — 使用规划代理，识别依赖关系和风险，分阶段推进
+2. **测试驱动开发** — 使用 tdd-guide 代理，先写测试，再实现和重构
+3. **评审** — 立即使用代码评审代理，解决 CRITICAL/HIGH 级别的问题
+4. **在适当位置记录知识**
+   * 个人调试笔记、偏好和临时上下文 → 自动记忆
+   * 团队/项目知识（架构决策、API 变更、操作手册）→ 项目现有文档结构
+   * 如果当前任务已生成相关文档或代码注释，请勿在其他地方重复相同信息
+   * 如果没有明显的项目文档位置，在创建新的顶层文件前先询问
+5. **提交** — 采用约定式提交格式，提供全面的 PR 摘要
+
+## Git 工作流
+
+**提交格式：** `<type>: <description>` — 类型：feat, fix, refactor, docs, test, chore, perf, ci
+
+**PR 工作流：** 分析完整的提交历史 → 起草全面的摘要 → 包含测试计划 → 使用 `-u` 标志推送。
+
+## 架构模式
+
+**API 响应格式：** 具有成功指示器、数据负载、错误消息和分页元数据的一致信封。
+
+**仓储模式：** 将数据访问封装在标准接口（findAll, findById, create, update, delete）后面。业务逻辑依赖于抽象接口，而不是存储机制。
+
+**骨架项目：** 搜索经过实战检验的模板，使用并行智能体（安全性、可扩展性、相关性）进行评估，克隆最佳匹配，在已验证的结构内迭代。
+
+## 性能
+
+**上下文管理：** 对于大型重构和多文件功能，避免使用上下文窗口的最后 20%。敏感性较低的任务（单次编辑、文档、简单修复）可以容忍较高的利用率。
+
+**构建故障排除：** 使用 build-error-resolver 智能体 → 分析错误 → 增量修复 → 每次修复后验证。
+
+## 项目结构
+
+```
+agents/          — 48 个专业子代理
+skills/          — 183 个工作流技能和领域知识
+commands/        — 79 个斜杠命令
+hooks/           — 基于触发的自动化
+rules/           — 始终遵循的指导方针（通用 + 每种语言）
+scripts/         — 跨平台 Node.js 实用工具
+mcp-configs/     — 14 个 MCP 服务器配置
+tests/           — 测试套件
+```
+
+## 成功指标
+
+* 所有测试通过且覆盖率 80%+
+* 没有安全漏洞
+* 代码可读且可维护
+* 性能可接受
+* 满足用户需求

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/CHANGELOG.md

@@ -0,0 +1,149 @@
+# 更新日志
+
+## 1.9.0 - 2026-03-20
+
+### 亮点
+
+* 选择性安装架构，采用清单驱动流水线和 SQLite 状态存储。
+* 语言覆盖范围扩展至 10 多个生态，新增 6 个代理和语言特定规则。
+* 观察器可靠性增强，包括内存限制、沙箱修复和 5 层循环防护。
+* 自我改进的技能基础，支持技能演进和会话适配器。
+
+### 新代理
+
+* `typescript-reviewer` — TypeScript/JavaScript 代码审查专家 (#647)
+* `pytorch-build-resolver` — PyTorch 运行时、CUDA 及训练错误解决 (#549)
+* `java-build-resolver` — Maven/Gradle 构建错误解决 (#538)
+* `java-reviewer` — Java 和 Spring Boot 代码审查 (#528)
+* `kotlin-reviewer` — Kotlin/Android/KMP 代码审查 (#309)
+* `kotlin-build-resolver` — Kotlin/Gradle 构建错误 (#309)
+* `rust-reviewer` — Rust 代码审查 (#523)
+* `rust-build-resolver` — Rust 构建错误解决 (#523)
+* `docs-lookup` — 文档和 API 参考研究 (#529)
+
+### 新技能
+
+* `pytorch-patterns` — PyTorch 深度学习工作流 (#550)
+* `documentation-lookup` — API 参考和库文档研究 (#529)
+* `bun-runtime` — Bun 运行时模式 (#529)
+* `nextjs-turbopack` — Next.js Turbopack 工作流 (#529)
+* `mcp-server-patterns` — MCP 服务器设计模式 (#531)
+* `data-scraper-agent` — AI 驱动的公共数据收集 (#503)
+* `team-builder` — 团队构成技能 (#501)
+* `ai-regression-testing` — AI 回归测试工作流 (#433)
+* `claude-devfleet` — 多代理编排 (#505)
+* `blueprint` — 多会话构建规划
+* `everything-claude-code` — 自引用 ECC 技能 (#335)
+* `prompt-optimizer` — 提示优化技能 (#418)
+* 8 个 Evos 操作领域技能 (#290)
+* 3 个 Laravel 技能 (#420)
+* VideoDB 技能 (#301)
+
+### 新命令
+
+* `/docs` — 文档查找 (#530)
+* `/aside` — 侧边对话 (#407)
+* `/prompt-optimize` — 提示优化 (#418)
+* `/resume-session`, `/save-session` — 会话管理
+* `learn-eval` 改进，支持基于清单的整体裁决
+
+### 新规则
+
+* Java 语言规则 (#645)
+* PHP 规则包 (#389)
+* Perl 语言规则和技能（模式、安全、测试）
+* Kotlin/Android/KMP 规则 (#309)
+* C++ 语言支持 (#539)
+* Rust 语言支持 (#523)
+
+### 基础设施
+
+* 选择性安装架构，支持清单解析 (`install-plan.js`, `install-apply.js`) (#509, #512)
+* SQLite 状态存储，提供查询 CLI 以跟踪已安装组件 (#510)
+* 会话适配器，用于结构化会话记录 (#511)
+* 技能演进基础，支持自我改进的技能 (#514)
+* 编排框架，支持确定性评分 (#524)
+* CI 中的目录计数强制执行 (#525)
+* 对所有 109 项技能的安装清单验证 (#537)
+* PowerShell 安装器包装器 (#532)
+* 通过 `--target antigravity` 标志支持 Antigravity IDE (#332)
+* Codex CLI 自定义脚本 (#336)
+
+### 错误修复
+
+* 解决了 6 个文件中的 19 个 CI 测试失败 (#519)
+* 修复了安装流水线、编排器和修复工具中的 8 个测试失败 (#564)
+* 观察器内存爆炸问题，通过限制、重入防护和尾部采样解决 (#536)
+* 观察器沙箱访问修复，用于 Haiku 调用 (#661)
+* 工作树项目 ID 不匹配修复 (#665)
+* 观察器延迟启动逻辑 (#508)
+* 观察器 5 层循环预防防护 (#399)
+* 钩子可移植性和 Windows .cmd 支持
+* Biome 钩子优化 — 消除了 npx 开销 (#359)
+* InsAIts 安全钩子改为可选启用 (#370)
+* Windows spawnSync 导出修复 (#431)
+* instinct CLI 的 UTF-8 编码修复 (#353)
+* 钩子中的密钥擦除 (#348)
+
+### 翻译
+
+* 韩语 (ko-KR) 翻译 — README、代理、命令、技能、规则 (#392)
+* 中文 (zh-CN) 文档同步 (#428)
+
+### 鸣谢
+
+* @ymdvsymd — 观察器沙箱和工作树修复
+* @pythonstrup — biome 钩子优化
+* @Nomadu27 — InsAIts 安全钩子
+* @hahmee — 韩语翻译
+* @zdocapp — 中文翻译同步
+* @cookiee339 — Kotlin 生态
+* @pangerlkr — CI 工作流修复
+* @0xrohitgarg — VideoDB 技能
+* @nocodemf — Evos 操作技能
+* @swarnika-cmd — 社区贡献
+
+## 1.8.0 - 2026-03-04
+
+### 亮点
+
+* 首次发布以可靠性、评估规程和自主循环操作为核心的版本。
+* Hook 运行时现在支持基于配置文件的控制和针对性的 Hook 禁用。
+* NanoClaw v2 增加了模型路由、技能热加载、分支、搜索、压缩、导出和指标功能。
+
+### 核心
+
+* 新增命令：`/harness-audit`, `/loop-start`, `/loop-status`, `/quality-gate`, `/model-route`。
+* 新增技能：
+  * `agent-harness-construction`
+  * `agentic-engineering`
+  * `ralphinho-rfc-pipeline`
+  * `ai-first-engineering`
+  * `enterprise-agent-ops`
+  * `nanoclaw-repl`
+  * `continuous-agent-loop`
+* 新增代理：
+  * `harness-optimizer`
+  * `loop-operator`
+
+### Hook 可靠性
+
+* 修复了 SessionStart 的根路径解析，增加了健壮的回退搜索。
+* 将会话摘要持久化移至 `Stop`，此处可获得转录负载。
+* 增加了质量门和成本追踪钩子。
+* 用专门的脚本文件替换了脆弱的单行内联钩子。
+* 增加了 `ECC_HOOK_PROFILE` 和 `ECC_DISABLED_HOOKS` 控制。
+
+### 跨平台
+
+* 改进了文档警告逻辑中 Windows 安全路径的处理。
+* 强化了观察者循环行为，以避免非交互式挂起。
+
+### 备注
+
+* `autonomous-loops` 作为一个兼容性别名保留一个版本；`continuous-agent-loop` 是规范名称。
+
+### 鸣谢
+
+* 灵感来自 [zarazhangrui](https://github.com/zarazhangrui)
+* homunculus 灵感来自 [humanplane](https://github.com/humanplane)

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+本文件为 Claude Code (claude.ai/code) 处理此仓库代码时提供指导。
+
+## 项目概述
+
+这是一个 **Claude Code 插件** - 一个包含生产就绪的代理、技能、钩子、命令、规则和 MCP 配置的集合。该项目提供了使用 Claude Code 进行软件开发的经验证的工作流。
+
+## 运行测试
+
+```bash
+# Run all tests
+node tests/run-all.js
+
+# Run individual test files
+node tests/lib/utils.test.js
+node tests/lib/package-manager.test.js
+node tests/hooks/hooks.test.js
+```
+
+## 架构
+
+项目组织为以下几个核心组件：
+
+* **agents/** - 用于委派的专业化子代理（规划器、代码审查员、TDD 指南等）
+* **skills/** - 工作流定义和领域知识（编码标准、模式、测试）
+* **commands/** - 由用户调用的斜杠命令（/tdd, /plan, /e2e 等）
+* **hooks/** - 基于触发的自动化（会话持久化、工具前后钩子）
+* **rules/** - 始终遵循的指南（安全、编码风格、测试要求）
+* **mcp-configs/** - 用于外部集成的 MCP 服务器配置
+* **scripts/** - 用于钩子和设置的跨平台 Node.js 工具
+* **tests/** - 脚本和工具的测试套件
+
+## 关键命令
+
+* `/tdd` - 测试驱动开发工作流
+* `/plan` - 实施规划
+* `/e2e` - 生成并运行端到端测试
+* `/code-review` - 质量审查
+* `/build-fix` - 修复构建错误
+* `/learn` - 从会话中提取模式
+* `/skill-create` - 从 git 历史记录生成技能
+
+## 开发说明
+
+* 包管理器检测：npm、pnpm、yarn、bun（可通过 `CLAUDE_PACKAGE_MANAGER` 环境变量或项目配置设置）
+* 跨平台：通过 Node.js 脚本支持 Windows、macOS、Linux
+* 代理格式：带有 YAML 前言的 Markdown（名称、描述、工具、模型）
+* 技能格式：带有清晰章节的 Markdown（何时使用、如何工作、示例）
+* 钩子格式：带有匹配器条件和命令/通知钩子的 JSON
+
+## 贡献
+
+遵循 CONTRIBUTING.md 中的格式：
+
+* 代理：带有前言的 Markdown（名称、描述、工具、模型）
+* 技能：清晰的章节（何时使用、如何工作、示例）
+* 命令：带有描述前言的 Markdown
+* 钩子：带有匹配器和钩子数组的 JSON
+
+文件命名：小写字母并用连字符连接（例如 `python-reviewer.md`, `tdd-workflow.md`）