@pzy560117/codex-harness 0.1.4 → 0.1.6

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

@@ -0,0 +1,118 @@
+# 用户级别 CLAUDE.md 示例
+
+这是一个用户级别 CLAUDE.md 文件的示例。放置在 `~/.claude/CLAUDE.md`。
+
+用户级别配置全局应用于所有项目。用于：
+
+* 个人编码偏好
+* 您始终希望强制执行的全域规则
+* 指向您模块化规则的链接
+
+***
+
+## 核心哲学
+
+您是 Claude Code。我使用专门的代理和技能来处理复杂任务。
+
+**关键原则：**
+
+1. **代理优先**：将复杂工作委托给专门的代理
+2. **并行执行**：尽可能使用具有多个代理的 Task 工具
+3. **先计划后执行**：对复杂操作使用计划模式
+4. **测试驱动**：在实现之前编写测试
+5. **安全第一**：绝不妥协安全性
+
+***
+
+## 模块化规则
+
+详细指南位于 `~/.claude/rules/`：
+
+| 规则文件 | 内容 |
+|-----------|----------|
+| security.md | 安全检查，密钥管理 |
+| coding-style.md | 不可变性，文件组织，错误处理 |
+| testing.md | TDD 工作流，80% 覆盖率要求 |
+| git-workflow.md | 提交格式，PR 工作流 |
+| agents.md | 代理编排，何时使用哪个代理 |
+| patterns.md | API 响应，仓库模式 |
+| performance.md | 模型选择，上下文管理 |
+| hooks.md | 钩子系统 |
+
+***
+
+## 可用代理
+
+位于 `~/.claude/agents/`：
+
+| 代理 | 目的 |
+|-------|---------|
+| planner | 功能实现规划 |
+| architect | 系统设计和架构 |
+| tdd-guide | 测试驱动开发 |
+| code-reviewer | 代码审查以保障质量/安全 |
+| security-reviewer | 安全漏洞分析 |
+| build-error-resolver | 构建错误解决 |
+| e2e-runner | Playwright E2E 测试 |
+| refactor-cleaner | 死代码清理 |
+| doc-updater | 文档更新 |
+
+***
+
+## 个人偏好
+
+### 隐私
+
+* 始终编辑日志；绝不粘贴密钥（API 密钥/令牌/密码/JWT）
+* 分享前审查输出 - 移除任何敏感数据
+
+### 代码风格
+
+* 代码、注释或文档中不使用表情符号
+* 偏好不可变性 - 永不改变对象或数组
+* 许多小文件优于少数大文件
+* 典型 200-400 行，每个文件最多 800 行
+
+### Git
+
+* 约定式提交：`feat:`，`fix:`，`refactor:`，`docs:`，`test:`
+* 提交前始终在本地测试
+* 小型的、专注的提交
+
+### 测试
+
+* TDD：先写测试
+* 最低 80% 覆盖率
+* 关键流程使用单元测试 + 集成测试 + E2E 测试
+
+### 知识捕获
+
+* 个人调试笔记、偏好和临时上下文 → 自动记忆
+* 团队/项目知识（架构决策、API变更、实施操作手册） → 遵循项目现有的文档结构
+* 如果当前任务已生成相关文档、注释或示例，请勿在其他地方重复记录相同知识
+* 如果没有明显的项目文档位置，请在创建新的顶层文档前进行询问
+
+***
+
+## 编辑器集成
+
+我使用 Zed 作为主要编辑器：
+
+* 用于文件跟踪的代理面板
+* CMD+Shift+R 打开命令面板
+* 已启用 Vim 模式
+
+***
+
+## 成功指标
+
+当满足以下条件时，您就是成功的：
+
+* 所有测试通过（覆盖率 80%+）
+* 无安全漏洞
+* 代码可读且可维护
+* 满足用户需求
+
+***
+
+**哲学**：代理优先设计，并行执行，先计划后行动，先测试后编码，安全至上。

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

@@ -0,0 +1,220 @@
+# 钩子
+
+钩子是事件驱动的自动化程序，在 Claude Code 工具执行前后触发。它们用于强制执行代码质量、及早发现错误以及自动化重复性检查。
+
+## 钩子如何工作
+
+```
+用户请求 → Claude 选择工具 → PreToolUse 钩子运行 → 工具执行 → PostToolUse 钩子运行
+```
+
+* **PreToolUse** 钩子在工具执行前运行。它们可以**阻止**（退出码 2）或**警告**（stderr 输出但不阻止）。
+* **PostToolUse** 钩子在工具完成后运行。它们可以分析输出但不能阻止执行。
+* **Stop** 钩子在每次 Claude 响应后运行。
+* **SessionStart/SessionEnd** 钩子在会话生命周期的边界处运行。
+* **PreCompact** 钩子在上下文压缩前运行，适用于保存状态。
+
+## 本插件中的钩子
+
+### PreToolUse 钩子
+
+| 钩子 | 匹配器 | 行为 | 退出码 |
+|------|---------|----------|-----------|
+| **开发服务器拦截器** | `Bash` | 在 tmux 外阻止 `npm run dev` 等命令 — 确保日志可访问 | 2 (拦截) |
+| **Tmux 提醒器** | `Bash` | 对长时间运行命令（npm test、cargo build、docker）建议使用 tmux | 0 (警告) |
+| **Git 推送提醒器** | `Bash` | 在 `git push` 前提醒检查变更 | 0 (警告) |
+| **文档文件警告器** | `Write` | 对非标准 `.md`/`.txt` 文件发出警告（允许 README、CLAUDE、CONTRIBUTING、CHANGELOG、LICENSE、SKILL、docs/、skills/）；跨平台路径处理 | 0 (警告) |
+| **策略性压缩提醒器** | `Edit\|Write` | 建议在逻辑间隔（约每 50 次工具调用）手动执行 `/compact` | 0 (警告) |
+
+### PostToolUse 钩子
+
+| 钩子 | 匹配器 | 功能 |
+|------|---------|-------------|
+| **PR 记录器** | `Bash` | 在 `gh pr create` 后记录 PR URL 和审查命令 |
+| **构建分析** | `Bash` | 构建命令后的后台分析（异步，非阻塞） |
+| **质量门** | `Edit\|Write\|MultiEdit` | 在编辑后运行快速质量检查 |
+| **Prettier 格式化** | `Edit` | 编辑后使用 Prettier 自动格式化 JS/TS 文件 |
+| **TypeScript 检查** | `Edit` | 在编辑 `.ts`/`.tsx` 文件后运行 `tsc --noEmit` |
+| **console.log 警告** | `Edit` | 警告编辑的文件中存在 `console.log` 语句 |
+
+### 生命周期钩子
+
+| 钩子 | 事件 | 功能 |
+|------|-------|-------------|
+| **会话开始** | `SessionStart` | 加载先前上下文并检测包管理器 |
+| **预压缩** | `PreCompact` | 在上下文压缩前保存状态 |
+| **Console.log 审计** | `Stop` | 每次响应后检查所有修改的文件是否有 `console.log` |
+| **会话摘要** | `Stop` | 当转录路径可用时持久化会话状态 |
+| **模式提取** | `Stop` | 评估会话以提取可抽取的模式（持续学习） |
+| **成本追踪器** | `Stop` | 发出轻量级的运行成本遥测标记 |
+| **会话结束标记** | `SessionEnd` | 生命周期标记和清理日志 |
+
+## 自定义钩子
+
+### 禁用钩子
+
+在 `hooks.json` 中移除或注释掉钩子条目。如果作为插件安装，请在您的 `~/.claude/settings.json` 中覆盖：
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [],
+        "description": "Override: allow all .md file creation"
+      }
+    ]
+  }
+}
+```
+
+### 运行时钩子控制（推荐）
+
+使用环境变量控制钩子行为，无需编辑 `hooks.json`：
+
+```bash
+# minimal | standard | strict (default: standard)
+export ECC_HOOK_PROFILE=standard
+
+# Disable specific hook IDs (comma-separated)
+export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
+```
+
+配置文件：
+
+* `minimal` —— 仅保留必要的生命周期和安全钩子。
+* `standard` —— 默认；平衡的质量 + 安全检查。
+* `strict` —— 启用额外的提醒和更严格的防护措施。
+
+### 编写你自己的钩子
+
+钩子是 shell 命令，通过 stdin 接收 JSON 格式的工具输入，并且必须在 stdout 上输出 JSON。
+
+**基本结构：**
+
+```javascript
+// my-hook.js
+let data = '';
+process.stdin.on('data', chunk => data += chunk);
+process.stdin.on('end', () => {
+  const input = JSON.parse(data);
+
+  // Access tool info
+  const toolName = input.tool_name;        // "Edit", "Bash", "Write", etc.
+  const toolInput = input.tool_input;      // Tool-specific parameters
+  const toolOutput = input.tool_output;    // Only available in PostToolUse
+
+  // Warn (non-blocking): write to stderr
+  console.error('[Hook] Warning message shown to Claude');
+
+  // Block (PreToolUse only): exit with code 2
+  // process.exit(2);
+
+  // Always output the original data to stdout
+  console.log(data);
+});
+```
+
+**退出码：**
+
+* `0` —— 成功（继续执行）
+* `2` —— 阻止工具调用（仅限 PreToolUse）
+* 其他非零值 —— 错误（记录日志但不阻止）
+
+### 钩子输入模式
+
+```typescript
+interface HookInput {
+  tool_name: string;          // "Bash", "Edit", "Write", "Read", etc.
+  tool_input: {
+    command?: string;         // Bash: the command being run
+    file_path?: string;       // Edit/Write/Read: target file
+    old_string?: string;      // Edit: text being replaced
+    new_string?: string;      // Edit: replacement text
+    content?: string;         // Write: file content
+  };
+  tool_output?: {             // PostToolUse only
+    output?: string;          // Command/tool output
+  };
+}
+```
+
+### 异步钩子
+
+对于不应阻塞主流程的钩子（例如，后台分析）：
+
+```json
+{
+  "type": "command",
+  "command": "node my-slow-hook.js",
+  "async": true,
+  "timeout": 30
+}
+```
+
+异步钩子在后台运行。它们不能阻止工具执行。
+
+## 常用钩子配方
+
+### 警告 TODO 注释
+
+```json
+{
+  "matcher": "Edit",
+  "hooks": [{
+    "type": "command",
+    "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const ns=i.tool_input?.new_string||'';if(/TODO|FIXME|HACK/.test(ns)){console.error('[Hook] New TODO/FIXME added - consider creating an issue')}console.log(d)})\""
+  }],
+  "description": "Warn when adding TODO/FIXME comments"
+}
+```
+
+### 阻止创建大文件
+
+```json
+{
+  "matcher": "Write",
+  "hooks": [{
+    "type": "command",
+    "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const c=i.tool_input?.content||'';const lines=c.split('\\n').length;if(lines>800){console.error('[Hook] BLOCKED: File exceeds 800 lines ('+lines+' lines)');console.error('[Hook] Split into smaller, focused modules');process.exit(2)}console.log(d)})\""
+  }],
+  "description": "Block creation of files larger than 800 lines"
+}
+```
+
+### 使用 ruff 自动格式化 Python 文件
+
+```json
+{
+  "matcher": "Edit",
+  "hooks": [{
+    "type": "command",
+    "command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path||'';if(/\\.py$/.test(p)){const{execFileSync}=require('child_process');try{execFileSync('ruff',['format',p],{stdio:'pipe'})}catch(e){}}console.log(d)})\""
+  }],
+  "description": "Auto-format Python files with ruff after edits"
+}
+```
+
+### 要求新源文件附带测试文件
+
+```json
+{
+  "matcher": "Write",
+  "hooks": [{
+    "type": "command",
+    "command": "node -e \"const fs=require('fs');let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path||'';if(/src\\/.*\\.(ts|js)$/.test(p)&&!/\\.test\\.|\\.spec\\./.test(p)){const testPath=p.replace(/\\.(ts|js)$/,'.test.$1');if(!fs.existsSync(testPath)){console.error('[Hook] No test file found for: '+p);console.error('[Hook] Expected: '+testPath);console.error('[Hook] Consider writing tests first (/tdd)')}}console.log(d)})\""
+  }],
+  "description": "Remind to create tests when adding new source files"
+}
+```
+
+## 跨平台注意事项
+
+钩子逻辑在 Node.js 脚本中实现，以便在 Windows、macOS 和 Linux 上具有跨平台行为。保留了少量 shell 包装器用于持续学习的观察者钩子；这些包装器受配置文件控制，并具有 Windows 安全的回退行为。
+
+## 相关
+
+* [rules/common/hooks.md](../rules/common/hooks.md) —— 钩子架构指南
+* [skills/strategic-compact/](../../../skills/strategic-compact) —— 策略性压缩技能
+* [scripts/hooks/](../../../scripts/hooks) —— 钩子脚本实现

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

@@ -0,0 +1,89 @@
+# 插件与市场
+
+插件扩展了 Claude Code 的功能，为其添加新工具和能力。本指南仅涵盖安装部分 - 关于何时以及为何使用插件，请参阅[完整文章](https://x.com/affaanmustafa/status/2012378465664745795)。
+
+***
+
+## 市场
+
+市场是可安装插件的存储库。
+
+### 添加市场
+
+```bash
+# Add official Anthropic marketplace
+claude plugin marketplace add https://github.com/anthropics/claude-plugins-official
+
+# Add community marketplaces (mgrep by @mixedbread-ai)
+claude plugin marketplace add https://github.com/mixedbread-ai/mgrep
+```
+
+### 推荐市场
+
+| 市场 | 来源 |
+|-------------|--------|
+| claude-plugins-official | `anthropics/claude-plugins-official` |
+| claude-code-plugins | `anthropics/claude-code` |
+| Mixedbread-Grep (@mixedbread-ai) | `mixedbread-ai/mgrep` |
+
+***
+
+## 安装插件
+
+```bash
+# Open plugins browser
+/plugins
+
+# Or install directly
+claude plugin install typescript-lsp@claude-plugins-official
+```
+
+### 推荐插件
+
+**开发：**
+
+* `typescript-lsp` - TypeScript 智能支持
+* `pyright-lsp` - Python 类型检查
+* `hookify` - 通过对话创建钩子
+* `code-simplifier` - 代码重构
+
+**代码质量：**
+
+* `code-review` - 代码审查
+* `pr-review-toolkit` - PR 自动化
+* `security-guidance` - 安全检查
+
+**搜索：**
+
+* `mgrep` - 增强搜索（优于 ripgrep）
+* `context7` - 实时文档查找
+
+**工作流：**
+
+* `commit-commands` - Git 工作流
+* `frontend-design` - UI 模式
+* `feature-dev` - 功能开发
+
+***
+
+## 快速设置
+
+```bash
+# Add marketplaces
+claude plugin marketplace add https://github.com/anthropics/claude-plugins-official
+claude plugin marketplace add https://github.com/mixedbread-ai/mgrep
+
+# Open /plugins and install what you need
+```
+
+***
+
+## 插件文件位置
+
+```
+~/.claude/plugins/
+|-- cache/                    # 已下载的插件
+|-- installed_plugins.json    # 已安装列表
+|-- known_marketplaces.json   # 已添加的市场
+|-- marketplaces/             # 市场数据
+```