@pzy560117/codex-harness 0.1.4 → 0.1.5

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

@@ -0,0 +1,173 @@
+---
+description: 在不打断或丢失当前任务上下文的情况下，快速回答一个附带问题。回答后自动恢复工作。
+---
+
+# 旁述指令
+
+在任务进行中提问，获得即时、聚焦的回答——然后立即从暂停处继续。当前任务、文件和上下文绝不会被修改。
+
+## 何时使用
+
+* 你在 Claude 工作时对某事感到好奇，但又不想打断工作节奏
+* 你需要快速解释 Claude 当前正在编辑的代码
+* 你想就某个决定征求第二意见或进行澄清，而不会使任务偏离方向
+* 在 Claude 继续之前，你需要理解一个错误、概念或模式
+* 你想询问与当前任务无关的事情，而无需开启新会话
+
+## 使用方法
+
+```
+/aside <your question>
+/aside what does this function actually return?
+/aside is this pattern thread-safe?
+/aside why are we using X instead of Y here?
+/aside what's the difference between foo() and bar()?
+/aside should we be worried about the N+1 query we just added?
+```
+
+## 流程
+
+### 步骤 1：冻结当前任务状态
+
+在回答任何问题之前，先在心里记下：
+
+* 当前活动任务是什么？（正在处理哪个文件、功能或问题）
+* 在调用 `/aside` 时，进行到哪一步了？
+* 接下来原本要发生什么？
+
+在旁述期间，**不要**触碰、编辑、创建或删除任何文件。
+
+### 步骤 2：直接回答问题
+
+以最简洁但仍完整有用的形式回答问题。
+
+* 先说答案，再说推理过程
+* 保持简短——如果需要完整解释，请在任务结束后再提供
+* 如果问题涉及当前正在处理的文件或代码，请精确引用（相关时包括文件路径和行号）
+* 如果回答问题需要读取文件，就读它——但只读不写
+
+将响应格式化为：
+
+```
+ASIDE: [restate the question briefly]
+
+[Your answer here]
+
+— Back to task: [one-line description of what was being done]
+```
+
+### 步骤 3：恢复主任务
+
+在给出答案后，立即从暂停的确切点继续执行活动任务。除非旁述回答揭示了阻碍或需要重新考虑当前方法的理由（见边缘情况），否则不要请求恢复许可。
+
+***
+
+## 边缘情况
+
+**未提供问题（`/aside` 后面没有内容）：**
+回复：
+
+```
+ASIDE: no question provided
+
+What would you like to know? (ask your question and I'll answer without losing the current task context)
+
+— Back to task: [one-line description of what was being done]
+```
+
+**问题揭示了当前任务的潜在问题：**
+在恢复之前清楚地标记出来：
+
+```
+ASIDE: [answer]
+
+WARNING: Note: This answer suggests [issue] with the current approach. Want to address this before continuing, or proceed as planned?
+```
+
+等待用户的决定后再恢复。
+
+**问题实际上是任务重定向（而非旁述问题）：**
+如果问题暗示要改变正在构建的内容（例如，`/aside actually, let's use Redis instead`），请澄清：
+
+```
+ASIDE: That sounds like a direction change, not just a side question.
+Do you want to:
+  (a) Answer this as information only and keep the current plan
+  (b) Pause the current task and change approach
+```
+
+等待用户的回答——不要自行假设。
+
+**问题涉及当前打开的文件或代码：**
+根据实时上下文回答。如果该文件在会话早期已被读取，直接引用它。如果尚未读取，现在读取它（只读）并在回答时附带文件:行号引用。
+
+**无活动任务（调用 `/aside` 时没有进行中的任务）：**
+仍然使用标准包装器，以保持响应格式一致：
+
+```
+ASIDE: [restate the question briefly]
+
+[Your answer here]
+
+— Back to task: no active task to resume
+```
+
+**问题需要长篇回答：**
+简洁地给出核心答案，然后提供：
+
+```
+That's the short version. Want a deeper explanation after we finish [current task]?
+```
+
+**连续多个 `/aside` 问题：**
+依次回答每个问题。在回答完最后一个问题后，恢复主任务。不要在一连串旁述中丢失任务状态。
+
+**旁述回答暗示需要进行代码更改：**
+记下所需的更改，但不要在旁述期间进行更改：
+
+```
+ASIDE: [answer]
+
+ Worth fixing: [what should be changed]. I'll flag this after the current task unless you want to address it now.
+```
+
+**问题含糊不清或过于笼统：**
+提出一个澄清性问题——一个能获取回答所需信息的最简短问题。不要提出多个问题。
+
+***
+
+## 示例输出
+
+```
+User: /aside what does fetchWithRetry() actually do?
+
+ASIDE: what does fetchWithRetry() do?
+
+fetchWithRetry() (src/api/retry.ts:12) attempts the request up to 3 times with
+exponential backoff (250ms → 500ms → 1s). It only retries on 5xx responses and
+network errors — 4xx errors are treated as final and not retried.
+
+— Back to task: refactoring the auth middleware in src/middleware/auth.ts
+```
+
+```
+User: /aside is the approach we're taking thread-safe?
+
+ASIDE: is the current approach thread-safe?
+
+No — the shared cache object in src/cache/store.ts:34 is mutated without locking.
+Under concurrent requests this is a race condition. It's low risk in a single-process
+Node.js server but would be a real problem with worker threads or clustering.
+
+WARNING: Note: This could affect the feature we're building. Want to address this now or continue and fix it in a follow-up?
+```
+
+***
+
+## 注意事项
+
+* 在旁述期间**绝不**修改文件——仅限只读访问
+* 旁述是对话暂停，不是新任务——必须始终恢复原始任务
+* 保持回答聚焦：目标是快速为用户扫清障碍，而不是进行长篇大论
+* 如果旁述引发了更广泛的讨论，请先完成当前任务，除非旁述揭示了阻碍
+* 除非明确与任务结果相关，否则旁述内容不会保存到会话文件中

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/build-fix.md

@@ -0,0 +1,64 @@
+# 构建与修复
+
+以最小、安全的更改逐步修复构建和类型错误。
+
+## 步骤 1：检测构建系统
+
+识别项目的构建工具并运行构建：
+
+| 指示器 | 构建命令 |
+|-----------|---------------|
+| `package.json` 包含 `build` 脚本 | `npm run build` 或 `pnpm build` |
+| `tsconfig.json`（仅限 TypeScript） | `npx tsc --noEmit` |
+| `Cargo.toml` | `cargo build 2>&1` |
+| `pom.xml` | `mvn compile` |
+| `build.gradle` | `./gradlew compileJava` |
+| `go.mod` | `go build ./...` |
+| `pyproject.toml` | `python -m py_compile` 或 `mypy .` |
+
+## 步骤 2：解析并分组错误
+
+1. 运行构建命令并捕获 stderr
+2. 按文件路径对错误进行分组
+3. 按依赖顺序排序（先修复导入/类型错误，再修复逻辑错误）
+4. 统计错误总数以跟踪进度
+
+## 步骤 3：修复循环（一次处理一个错误）
+
+对于每个错误：
+
+1. **读取文件** — 使用读取工具查看错误上下文（错误周围的 10 行代码）
+2. **诊断** — 确定根本原因（缺少导入、类型错误、语法错误）
+3. **最小化修复** — 使用编辑工具进行最小的更改以解决错误
+4. **重新运行构建** — 验证错误已消失且未引入新错误
+5. **移至下一个** — 继续处理剩余的错误
+
+## 步骤 4：防护措施
+
+在以下情况下停止并询问用户：
+
+* 一个修复**引入的错误比它解决的更多**
+* **同一错误在 3 次尝试后仍然存在**（可能是更深层次的问题）
+* 修复需要**架构更改**（不仅仅是构建修复）
+* 构建错误源于**缺少依赖项**（需要 `npm install`、`cargo add` 等）
+
+## 步骤 5：总结
+
+显示结果：
+
+* 已修复的错误（包含文件路径）
+* 剩余的错误（如果有）
+* 引入的新错误（应为零）
+* 针对未解决问题的建议后续步骤
+
+## 恢复策略
+
+| 情况 | 操作 |
+|-----------|--------|
+| 缺少模块/导入 | 检查包是否已安装；建议安装命令 |
+| 类型不匹配 | 读取两种类型定义；修复更窄的类型 |
+| 循环依赖 | 使用导入图识别循环；建议提取 |
+| 版本冲突 | 检查 `package.json` / `Cargo.toml` 中的版本约束 |
+| 构建工具配置错误 | 读取配置文件；与有效的默认配置进行比较 |
+
+为了安全起见，一次只修复一个错误。优先使用最小的改动，而不是重构。

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

@@ -0,0 +1,78 @@
+# 检查点命令
+
+在你的工作流中创建或验证一个检查点。
+
+## 用法
+
+`/checkpoint [create|verify|list] [name]`
+
+## 创建检查点
+
+创建检查点时：
+
+1. 运行 `/verify quick` 以确保当前状态是干净的
+2. 使用检查点名称创建一个 git stash 或提交
+3. 将检查点记录到 `.claude/checkpoints.log`：
+
+```bash
+echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)" >> .claude/checkpoints.log
+```
+
+4. 报告检查点已创建
+
+## 验证检查点
+
+根据检查点进行验证时：
+
+1. 从日志中读取检查点
+
+2. 将当前状态与检查点进行比较：
+   * 自检查点以来新增的文件
+   * 自检查点以来修改的文件
+   * 现在的测试通过率与当时对比
+   * 现在的覆盖率与当时对比
+
+3. 报告：
+
+```
+检查点对比：$NAME
+============================
+文件更改数：X
+测试结果：通过数 +Y / 失败数 -Z
+覆盖率：+X% / -Y%
+构建状态：[通过/失败]
+```
+
+## 列出检查点
+
+显示所有检查点，包含：
+
+* 名称
+* 时间戳
+* Git SHA
+* 状态（当前、落后、超前）
+
+## 工作流
+
+典型的检查点流程：
+
+```
+[Start] --> /checkpoint create "feature-start"
+   |
+[Implement] --> /checkpoint create "core-done"
+   |
+[Test] --> /checkpoint verify "core-done"
+   |
+[Refactor] --> /checkpoint create "refactor-done"
+   |
+[PR] --> /checkpoint verify "feature-start"
+```
+
+## 参数
+
+$ARGUMENTS:
+
+* `create <name>` - 创建指定名称的检查点
+* `verify <name>` - 根据指定名称的检查点进行验证
+* `list` - 显示所有检查点
+* `clear` - 删除旧的检查点（保留最后5个）

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

@@ -0,0 +1,51 @@
+---
+description: 启动 NanoClaw v2 — ECC 的持久、零依赖 REPL，具备模型路由、技能热加载、分支、压缩、导出和指标功能。
+---
+
+# Claw 命令
+
+启动一个具有持久化 Markdown 历史记录和操作控制的交互式 AI 代理会话。
+
+## 使用方法
+
+```bash
+node scripts/claw.js
+```
+
+或通过 npm：
+
+```bash
+npm run claw
+```
+
+## 环境变量
+
+| 变量 | 默认值 | 描述 |
+|----------|---------|-------------|
+| `CLAW_SESSION` | `default` | 会话名称（字母数字 + 连字符） |
+| `CLAW_SKILLS` | *(空)* | 启动时加载的以逗号分隔的技能列表 |
+| `CLAW_MODEL` | `sonnet` | 会话的默认模型 |
+
+## REPL 命令
+
+```text
+/help                          显示帮助信息
+/clear                         清除当前会话历史
+/history                       打印完整对话历史
+/sessions                      列出已保存的会话
+/model [name]                  显示/设置模型
+/load <skill-name>             热加载技能到上下文
+/branch <session-name>         分支当前会话
+/search <query>                跨会话搜索查询
+/compact                       压缩旧轮次，保留近期上下文
+/export <md|json|txt> [path]   导出会话
+/metrics                       显示会话指标
+exit                           退出
+```
+
+## 说明
+
+* NanoClaw 保持零依赖。
+* 会话存储在 `~/.claude/claw/<session>.md`。
+* 压缩会保留最近的回合并写入压缩头。
+* 导出支持 Markdown、JSON 回合和纯文本。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/code-review.md

@@ -0,0 +1,43 @@
+# 代码审查
+
+对未提交的更改进行全面的安全性和质量审查：
+
+1. 获取更改的文件：`git diff --name-only HEAD`
+
+2. 对每个更改的文件，检查：
+
+**安全问题（严重）：**
+
+* 硬编码的凭据、API 密钥、令牌
+* SQL 注入漏洞
+* XSS 漏洞
+* 缺少输入验证
+* 不安全的依赖项
+* 路径遍历风险
+
+**代码质量（高）：**
+
+* 函数长度超过 50 行
+* 文件长度超过 800 行
+* 嵌套深度超过 4 层
+* 缺少错误处理
+* `console.log` 语句
+* `TODO`/`FIXME` 注释
+* 公共 API 缺少 JSDoc
+
+**最佳实践（中）：**
+
+* 可变模式（应使用不可变模式）
+* 代码/注释中使用表情符号
+* 新代码缺少测试
+* 无障碍性问题（a11y）
+
+3. 生成报告，包含：
+   * 严重性：严重、高、中、低
+   * 文件位置和行号
+   * 问题描述
+   * 建议的修复方法
+
+4. 如果发现严重或高优先级问题，则阻止提交
+
+绝不允许包含安全漏洞的代码！

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/context-budget.md

@@ -0,0 +1,29 @@
+---
+description: 分析跨代理、技能、MCP服务器和规则的上下文窗口使用情况，以寻找优化机会。有助于减少令牌开销并避免性能警告。
+---
+
+# 上下文预算优化器
+
+分析您的 Claude Code 设置中的上下文窗口消耗，并提供可操作的建议以减少令牌开销。
+
+## 使用方法
+
+```
+/context-budget [--verbose]
+```
+
+* 默认：提供摘要及主要建议
+* `--verbose`：按组件提供完整细分
+
+$ARGUMENTS
+
+## 操作步骤
+
+运行 **context-budget** 技能（`skills/context-budget/SKILL.md`），并输入以下内容：
+
+1. 如果 `$ARGUMENTS` 中存在 `--verbose` 标志，则传递该标志
+2. 除非用户另行指定，否则假设为 200K 上下文窗口（Claude Sonnet 默认值）
+3. 遵循技能的四个阶段：清单 → 分类 → 检测问题 → 报告
+4. 向用户输出格式化的上下文预算报告
+
+该技能负责所有扫描逻辑、令牌估算、问题检测和报告格式化。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/cpp-build.md

@@ -0,0 +1,173 @@
+---
+description: 逐步修复C++构建错误、CMake问题和链接器问题。调用cpp-build-resolver代理进行最小化、精准的修复。
+---
+
+# C++ 构建与修复
+
+此命令调用 **cpp-build-resolver** 代理，以最小的更改逐步修复 C++ 构建错误。
+
+## 此命令的作用
+
+1. **运行诊断**：执行 `cmake --build`、`clang-tidy`、`cppcheck`
+2. **解析错误**：按文件分组并按严重性排序
+3. **逐步修复**：一次修复一个错误
+4. **验证每个修复**：每次更改后重新运行构建
+5. **报告摘要**：显示已修复的内容和剩余的问题
+
+## 何时使用
+
+在以下情况下使用 `/cpp-build`：
+
+* `cmake --build build` 因错误而失败时
+* 链接器错误（未定义的引用，多重定义）
+* 模板实例化失败
+* 包含/依赖项问题
+* 拉取更改后导致构建失败时
+
+## 运行的诊断命令
+
+```bash
+# CMake configure
+cmake -B build -S .
+
+# Build
+cmake --build build 2>&1 | head -100
+
+# Static analysis (if available)
+clang-tidy src/*.cpp -- -std=c++17
+cppcheck --enable=all src/
+```
+
+## 示例会话
+
+````text
+# C++ 构建问题解决
+
+## 初始诊断
+
+```bash
+$ cmake --build build
+src/service/user.cpp:25:15: error: use of undeclared identifier 'UserRepository'
+src/handler/api.cpp:42:9: error: no matching function for call to 'process'
+src/handler/api.cpp:58:1: error: non-void function does not return a value
+
+````
+
+发现的错误：3
+
+## 修复 1：未声明的标识符
+
+文件：src/service/user.cpp:25
+错误：使用了未声明的标识符 'UserRepository'
+原因：缺少包含
+
+```cpp
+// Added include
+#include "repository/user_repository.hpp"
+```
+
+```bash
+$ cmake --build build
+# 2 errors remaining
+```
+
+## 修复 2：无匹配函数
+
+文件：src/handler/api.cpp:42
+错误：没有匹配的函数用于调用 'process'
+
+```cpp
+// Changed
+process(params.get("count"));
+// To
+process(std::stoi(params.get("count")));
+```
+
+```bash
+$ cmake --build build
+# 1 error remaining
+```
+
+## 修复 3：缺少返回
+
+文件：src/handler/api.cpp:58
+错误：非 void 函数未返回值
+
+```cpp
+std::optional<User> getUser(const std::string& id) {
+    if (id.empty()) {
+        return std::nullopt;
+    }
+    auto user = findUser(id);
+    // Added missing return
+    return user;
+}
+```
+
+```bash
+$ cmake --build build
+# Build successful!
+```
+
+## 最终验证
+
+```bash
+$ ctest --test-dir build --output-on-failure
+Test project build
+    1/5 Test #1: unit_tests ........   Passed    0.02 sec
+    2/5 Test #2: integration_tests    Passed    0.15 sec
+All tests passed.
+```
+
+## 摘要
+
+| 指标 | 数量 |
+|--------|-------|
+| 已修复的构建错误 | 3 |
+| 已修复的链接器错误 | 0 |
+| 已修改的文件 | 2 |
+| 剩余问题 | 0 |
+
+构建状态：PASS: 成功
+
+```
+## 常见错误修复
+
+| 错误 | 典型修复方法 |
+|-------|-------------|
+| `undeclared identifier` | 添加 `#include` 或修正拼写错误 |
+| `no matching function` | 修正参数类型或添加重载函数 |
+| `undefined reference` | 链接库或添加实现 |
+| `multiple definition` | 使用 `inline` 或移至 .cpp 文件 |
+| `incomplete type` | 将前向声明替换为 `#include` |
+| `no member named X` | 修正成员名称或包含头文件 |
+| `cannot convert X to Y` | 添加适当的类型转换 |
+| `CMake Error` | 修正 CMakeLists.txt 配置 |
+
+## 修复策略
+
+1. **优先处理编译错误** - 代码必须能够编译
+2. **其次处理链接器错误** - 解决未定义引用
+3. **第三处理警告** - 使用 `-Wall -Wextra` 进行修复
+4. **一次只修复一个问题** - 验证每个更改
+5. **最小化改动** - 仅修复问题，不重构代码
+
+## 停止条件
+
+在以下情况下，代理将停止并报告：
+- 同一错误经过 3 次尝试后仍然存在
+- 修复引入了更多错误
+- 需要架构性更改
+- 缺少外部依赖项
+
+## 相关命令
+
+- `/cpp-test` - 构建成功后运行测试
+- `/cpp-review` - 审查代码质量
+- `/verify` - 完整验证循环
+
+## 相关
+
+- 代理: `agents/cpp-build-resolver.md`
+- 技能: `skills/cpp-coding-standards/`
+```