@pzy560117/codex-harness 0.1.4 → 0.1.5

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

@@ -0,0 +1,53 @@
+# 安全政策
+
+## 支持版本
+
+| 版本     | 支持状态           |
+| -------- | ------------------ |
+| 1.9.x    | :white\_check\_mark: |
+| 1.8.x    | :white\_check\_mark: |
+| < 1.8    | :x:                |
+
+## 报告漏洞
+
+如果您在 ECC 中发现安全漏洞，请负责任地报告。
+
+**请勿为安全漏洞创建公开的 GitHub 议题。**
+
+请将信息发送至 **<security@ecc.tools>**，邮件中需包含：
+
+* 漏洞描述
+* 复现步骤
+* 受影响的版本
+* 任何潜在的影响评估
+
+您可以期待：
+
+* **确认通知**：48 小时内
+* **状态更新**：7 天内
+* **修复或缓解措施**：对于关键问题，30 天内
+
+如果漏洞被采纳，我们将：
+
+* 在发布说明中注明您的贡献（除非您希望匿名）
+* 及时修复问题
+* 与您协调披露时间
+
+如果漏洞被拒绝，我们将解释原因，并提供是否应向其他地方报告的指导。
+
+## 范围
+
+本政策涵盖：
+
+* ECC 插件及此仓库中的所有脚本
+* 在您机器上执行的钩子脚本
+* 安装/卸载/修复生命周期脚本
+* 随 ECC 分发的 MCP 配置
+* AgentShield 安全扫描器 ([github.com/affaan-m/agentshield](https://github.com/affaan-m/agentshield))
+
+## 安全资源
+
+* **AgentShield**：扫描您的代理配置以查找漏洞 — `npx ecc-agentshield scan`
+* **安全指南**：[The Shorthand Guide to Everything Agentic Security](the-security-guide.md)
+* **OWASP MCP Top 10**：[owasp.org/www-project-mcp-top-10](https://owasp.org/www-project-mcp-top-10/)
+* **OWASP Agentic Applications Top 10**：[genai.owasp.org](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/)

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

@@ -0,0 +1,43 @@
+# 赞助 ECC
+
+ECC 作为一个开源智能体性能测试系统，在 Claude Code、Cursor、OpenCode 和 Codex 应用程序/CLI 中得到维护。
+
+## 为何赞助
+
+赞助直接资助以下方面：
+
+* 更快的错误修复和发布周期
+* 跨测试平台的平台一致性工作
+* 为社区免费提供的公共文档、技能和可靠性工具
+
+## 赞助层级
+
+这些是实用的起点，可以根据合作范围进行调整。
+
+| 层级 | 价格 | 最适合 | 包含内容 |
+|------|-------|----------|----------|
+| 试点合作伙伴 | $200/月 | 首次赞助合作 | 月度指标更新、路线图预览、优先维护者反馈 |
+| 成长合作伙伴 | $500/月 | 积极采用 ECC 的团队 | 试点权益 + 月度办公时间同步 + 工作流集成指导 |
+| 战略合作伙伴 | $1,000+/月 | 平台/生态系统合作伙伴 | 成长权益 + 协调发布支持 + 更深入的维护者协作 |
+
+## 赞助报告
+
+每月分享的指标可能包括：
+
+* npm 下载量（`ecc-universal`、`ecc-agentshield`）
+* 仓库采用情况（星标、分叉、贡献者）
+* GitHub 应用安装趋势
+* 发布节奏和可靠性里程碑
+
+有关确切的命令片段和可重复的拉取流程，请参阅 [`docs/business/metrics-and-sponsorship.md`](../business/metrics-and-sponsorship.md)。
+
+## 期望与范围
+
+* 赞助支持维护和加速；不会转移项目所有权。
+* 功能请求根据赞助层级、生态系统影响和维护风险进行优先级排序。
+* 安全性和可靠性修复优先于全新功能。
+
+## 在此赞助
+
+* GitHub Sponsors: <https://github.com/sponsors/affaan-m>
+* 项目网站: <https://ecc.tools>

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

@@ -0,0 +1,59 @@
+# 赞助者
+
+感谢所有赞助本项目的各位！你们的支持让 ECC 生态系统持续成长。
+
+## 企业赞助者
+
+*成为 [企业赞助者](https://github.com/sponsors/affaan-m)，将您的名字展示在此处*
+
+## 商业赞助者
+
+*成为 [商业赞助者](https://github.com/sponsors/affaan-m)，将您的名字展示在此处*
+
+## 团队赞助者
+
+*成为 [团队赞助者](https://github.com/sponsors/affaan-m)，将您的名字展示在此处*
+
+## 个人赞助者
+
+*成为 [赞助者](https://github.com/sponsors/affaan-m)，将您的名字列在此处*
+
+***
+
+## 为什么要赞助？
+
+您的赞助将帮助我们：
+
+* **更快地交付** — 更多时间投入到工具和功能的开发上
+* **保持免费** — 高级功能为所有人的免费层级提供资金支持
+* **更好的支持** — 赞助者获得优先响应
+* **影响路线图** — Pro+ 赞助者可以对功能进行投票
+
+## 赞助者准备度信号
+
+在赞助者对话中使用这些证明点：
+
+* `ecc-universal` 和 `ecc-agentshield` 的实时 npm 安装/下载指标
+* 通过 Marketplace 安装的 GitHub App 分发
+* 公开采用信号：星标、分叉、贡献者、发布节奏
+* 跨平台支持：Claude Code、Cursor、OpenCode、Codex 应用/CLI
+
+有关复制/粘贴指标拉取工作流程，请参阅 [`docs/business/metrics-and-sponsorship.md`](../business/metrics-and-sponsorship.md)。
+
+## 赞助等级
+
+| 层级 | 价格 | 权益 |
+|------|-------|----------|
+| 支持者 | 每月 $5 | 名字出现在 README 中，早期访问 |
+| 构建者 | 每月 $10 | 高级工具访问权限 |
+| 专业版 | 每月 $25 | 优先支持，办公时间 |
+| 团队版 | 每月 $100 | 5 个席位，团队配置 |
+| 平台合作伙伴 | 每月 $200 | 月度路线图同步，优先维护者反馈，发布说明提及 |
+| 商业版 | 每月 $500 | 25 个席位，咨询积分 |
+| 企业版 | 每月 $2K | 无限制席位，自定义工具 |
+
+[**Become a Sponsor →**](https://github.com/sponsors/affaan-m)
+
+***
+
+*自动更新。最后同步：2026年2月*

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

@@ -0,0 +1,446 @@
+# 故障排除指南
+
+Everything Claude Code (ECC) 插件的常见问题与解决方案。
+
+## 目录
+
+* [内存与上下文问题](#内存与上下文问题)
+* [代理工具故障](#代理工具故障)
+* [钩子与工作流错误](#钩子与工作流错误)
+* [安装与设置](#安装与设置)
+* [性能问题](#性能问题)
+* [常见错误信息](#常见错误信息)
+* [获取帮助](#获取帮助)
+
+***
+
+## 内存与上下文问题
+
+### 上下文窗口溢出
+
+**症状：** 出现"上下文过长"错误或响应不完整
+
+**原因：**
+
+* 上传的大文件超出令牌限制
+* 累积的对话历史记录
+* 单次会话中包含多个大型工具输出
+
+**解决方案：**
+
+```bash
+# 1. Clear conversation history and start fresh
+# Use Claude Code: "New Chat" or Cmd/Ctrl+Shift+N
+
+# 2. Reduce file size before analysis
+head -n 100 large-file.log > sample.log
+
+# 3. Use streaming for large outputs
+head -n 50 large-file.txt
+
+# 4. Split tasks into smaller chunks
+# Instead of: "Analyze all 50 files"
+# Use: "Analyze files in src/components/ directory"
+```
+
+### 内存持久化失败
+
+**症状：** 代理不记得先前的上下文或观察结果
+
+**原因：**
+
+* 连续学习钩子被禁用
+* 观察文件损坏
+* 项目检测失败
+
+**解决方案：**
+
+```bash
+# Check if observations are being recorded
+ls ~/.claude/homunculus/projects/*/observations.jsonl
+
+# Find the current project's hash id
+python3 - <<'PY'
+import json, os
+registry_path = os.path.expanduser("~/.claude/homunculus/projects.json")
+with open(registry_path) as f:
+    registry = json.load(f)
+for project_id, meta in registry.items():
+    if meta.get("root") == os.getcwd():
+        print(project_id)
+        break
+else:
+    raise SystemExit("Project hash not found in ~/.claude/homunculus/projects.json")
+PY
+
+# View recent observations for that project
+tail -20 ~/.claude/homunculus/projects/<project-hash>/observations.jsonl
+
+# Back up a corrupted observations file before recreating it
+mv ~/.claude/homunculus/projects/<project-hash>/observations.jsonl \
+  ~/.claude/homunculus/projects/<project-hash>/observations.jsonl.bak.$(date +%Y%m%d-%H%M%S)
+
+# Verify hooks are enabled
+grep -r "observe" ~/.claude/settings.json
+```
+
+***
+
+## 代理工具故障
+
+### 未找到代理
+
+**症状：** 出现"代理未加载"或"未知代理"错误
+
+**原因：**
+
+* 插件未正确安装
+* 代理路径配置错误
+* 市场安装与手动安装不匹配
+
+**解决方案：**
+
+```bash
+# Check plugin installation
+ls ~/.claude/plugins/cache/
+
+# Verify agent exists (marketplace install)
+ls ~/.claude/plugins/cache/*/agents/
+
+# For manual install, agents should be in:
+ls ~/.claude/agents/  # Custom agents only
+
+# Reload plugin
+# Claude Code → Settings → Extensions → Reload
+```
+
+### 工作流执行挂起
+
+**症状：** 代理启动但从未完成
+
+**原因：**
+
+* 代理逻辑中存在无限循环
+* 等待用户输入时被阻塞
+* 等待 API 响应时网络超时
+
+**解决方案：**
+
+```bash
+# 1. Check for stuck processes
+ps aux | grep claude
+
+# 2. Enable debug mode
+export CLAUDE_DEBUG=1
+
+# 3. Set shorter timeouts
+export CLAUDE_TIMEOUT=30
+
+# 4. Check network connectivity
+curl -I https://api.anthropic.com
+```
+
+### 工具使用错误
+
+**症状：** 出现"工具执行失败"或权限被拒绝
+
+**原因：**
+
+* 缺少依赖项（npm、python 等）
+* 文件权限不足
+* 路径未找到
+
+**解决方案：**
+
+```bash
+# Verify required tools are installed
+which node python3 npm git
+
+# Fix permissions on hook scripts
+chmod +x ~/.claude/plugins/cache/*/hooks/*.sh
+chmod +x ~/.claude/plugins/cache/*/skills/*/hooks/*.sh
+
+# Check PATH includes necessary binaries
+echo $PATH
+```
+
+***
+
+## 钩子与工作流错误
+
+### 钩子未触发
+
+**症状：** 前置/后置钩子未执行
+
+**原因：**
+
+* 钩子未在 settings.json 中注册
+* 钩子语法无效
+* 钩子脚本不可执行
+
+**解决方案：**
+
+```bash
+# Check hooks are registered
+grep -A 10 '"hooks"' ~/.claude/settings.json
+
+# Verify hook files exist and are executable
+ls -la ~/.claude/plugins/cache/*/hooks/
+
+# Test hook manually
+bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}'
+
+# Re-register hooks (if using plugin)
+# Disable and re-enable plugin in Claude Code settings
+```
+
+### Python/Node 版本不匹配
+
+**症状：** 出现"未找到 python3"或"node: 命令未找到"
+
+**原因：**
+
+* 缺少 Python/Node 安装
+* PATH 未配置
+* Python 版本错误（Windows）
+
+**解决方案：**
+
+```bash
+# Install Python 3 (if missing)
+# macOS: brew install python3
+# Ubuntu: sudo apt install python3
+# Windows: Download from python.org
+
+# Install Node.js (if missing)
+# macOS: brew install node
+# Ubuntu: sudo apt install nodejs npm
+# Windows: Download from nodejs.org
+
+# Verify installations
+python3 --version
+node --version
+npm --version
+
+# Windows: Ensure python (not python3) works
+python --version
+```
+
+### 开发服务器拦截器误报
+
+**症状：** 钩子拦截了提及"dev"的合法命令
+
+**原因：**
+
+* Heredoc 内容触发模式匹配
+* 参数中包含"dev"的非开发命令
+
+**解决方案：**
+
+```bash
+# This is fixed in v1.8.0+ (PR #371)
+# Upgrade plugin to latest version
+
+# Workaround: Wrap dev servers in tmux
+tmux new-session -d -s dev "npm run dev"
+tmux attach -t dev
+
+# Disable hook temporarily if needed
+# Edit ~/.claude/settings.json and remove pre-bash hook
+```
+
+***
+
+## 安装与设置
+
+### 插件未加载
+
+**症状：** 安装后插件功能不可用
+
+**原因：**
+
+* 市场缓存未更新
+* Claude Code 版本不兼容
+* 插件文件损坏
+
+**解决方案：**
+
+```bash
+# Inspect the plugin cache before changing it
+ls -la ~/.claude/plugins/cache/
+
+# Back up the plugin cache instead of deleting it in place
+mv ~/.claude/plugins/cache ~/.claude/plugins/cache.backup.$(date +%Y%m%d-%H%M%S)
+mkdir -p ~/.claude/plugins/cache
+
+# Reinstall from marketplace
+# Claude Code → Extensions → Everything Claude Code → Uninstall
+# Then reinstall from marketplace
+
+# Check Claude Code version
+claude --version
+# Requires Claude Code 2.0+
+
+# Manual install (if marketplace fails)
+git clone https://github.com/affaan-m/everything-claude-code.git
+cp -r everything-claude-code ~/.claude/plugins/ecc
+```
+
+### 包管理器检测失败
+
+**症状：** 使用了错误的包管理器（用 npm 而不是 pnpm）
+
+**原因：**
+
+* 没有 lock 文件
+* 未设置 CLAUDE\_PACKAGE\_MANAGER
+* 多个 lock 文件导致检测混乱
+
+**解决方案：**
+
+```bash
+# Set preferred package manager globally
+export CLAUDE_PACKAGE_MANAGER=pnpm
+# Add to ~/.bashrc or ~/.zshrc
+
+# Or set per-project
+echo '{"packageManager": "pnpm"}' > .claude/package-manager.json
+
+# Or use package.json field
+npm pkg set packageManager="pnpm@8.15.0"
+
+# Warning: removing lock files can change installed dependency versions.
+# Commit or back up the lock file first, then run a fresh install and re-run CI.
+# Only do this when intentionally switching package managers.
+rm package-lock.json  # If using pnpm/yarn/bun
+```
+
+***
+
+## 性能问题
+
+### 响应时间缓慢
+
+**症状：** 代理需要 30 秒以上才能响应
+
+**原因：**
+
+* 大型观察文件
+* 活动钩子过多
+* 到 API 的网络延迟
+
+**解决方案：**
+
+```bash
+# Archive large observations instead of deleting them
+archive_dir="$HOME/.claude/homunculus/archive/$(date +%Y%m%d)"
+mkdir -p "$archive_dir"
+find ~/.claude/homunculus/projects -name "observations.jsonl" -size +10M -exec sh -c '
+  for file do
+    base=$(basename "$(dirname "$file")")
+    gzip -c "$file" > "'"$archive_dir"'/${base}-observations.jsonl.gz"
+    : > "$file"
+  done
+' sh {} +
+
+# Disable unused hooks temporarily
+# Edit ~/.claude/settings.json
+
+# Keep active observation files small
+# Large archives should live under ~/.claude/homunculus/archive/
+```
+
+### CPU 使用率高
+
+**症状：** Claude Code 占用 100% CPU
+
+**原因：**
+
+* 无限观察循环
+* 对大型目录的文件监视
+* 钩子中的内存泄漏
+
+**解决方案：**
+
+```bash
+# Check for runaway processes
+top -o cpu | grep claude
+
+# Disable continuous learning temporarily
+touch ~/.claude/homunculus/disabled
+
+# Restart Claude Code
+# Cmd/Ctrl+Q then reopen
+
+# Check observation file size
+du -sh ~/.claude/homunculus/*/
+```
+
+***
+
+## 常见错误信息
+
+### "EACCES: permission denied"
+
+```bash
+# Fix hook permissions
+find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;
+
+# Fix observation directory permissions
+chmod -R u+rwX,go+rX ~/.claude/homunculus
+```
+
+### "MODULE\_NOT\_FOUND"
+
+```bash
+# Install plugin dependencies
+cd ~/.claude/plugins/cache/ecc
+npm install
+
+# Or for manual install
+cd ~/.claude/plugins/ecc
+npm install
+```
+
+### "spawn UNKNOWN"
+
+```bash
+# Windows-specific: Ensure scripts use correct line endings
+# Convert CRLF to LF
+find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \;
+
+# Or install dos2unix
+# macOS: brew install dos2unix
+# Ubuntu: sudo apt install dos2unix
+```
+
+***
+
+## 获取帮助
+
+如果您仍然遇到问题：
+
+1. **检查 GitHub Issues**：[github.com/affaan-m/everything-claude-code/issues](https://github.com/affaan-m/everything-claude-code/issues)
+2. **启用调试日志记录**：
+   ```bash
+   export CLAUDE_DEBUG=1
+   export CLAUDE_LOG_LEVEL=debug
+   ```
+3. **收集诊断信息**：
+   ```bash
+   claude --version
+   node --version
+   python3 --version
+   echo $CLAUDE_PACKAGE_MANAGER
+   ls -la ~/.claude/plugins/cache/
+   ```
+4. **提交 Issue**：包括调试日志、错误信息和诊断信息
+
+***
+
+## 相关文档
+
+* [README.md](README.md) - 安装与功能
+* [CONTRIBUTING.md](CONTRIBUTING.md) - 开发指南
+* [docs/](..) - 详细文档
+* [examples/](../../examples) - 使用示例