@pzy560117/codex-harness 0.1.0 → 0.1.1

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

@@ -0,0 +1,41 @@
+---
+name: promote
+description: 将项目范围内的本能推广到全局范围
+command: true
+---
+
+# 提升命令
+
+在 continuous-learning-v2 中将本能从项目范围提升到全局范围。
+
+## 实现
+
+使用插件根路径运行本能 CLI：
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" promote [instinct-id] [--force] [--dry-run]
+```
+
+或者如果未设置 `CLAUDE_PLUGIN_ROOT`（手动安装）：
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py promote [instinct-id] [--force] [--dry-run]
+```
+
+## 用法
+
+```bash
+/promote                      # Auto-detect promotion candidates
+/promote --dry-run            # Preview auto-promotion candidates
+/promote --force              # Promote all qualified candidates without prompt
+/promote grep-before-edit     # Promote one specific instinct from current project
+```
+
+## 操作步骤
+
+1. 检测当前项目
+2. 如果提供了 `instinct-id`，则仅提升该本能（如果存在于当前项目中）
+3. 否则，查找跨项目候选本能，这些本能：
+   * 出现在至少 2 个项目中
+   * 满足置信度阈值
+4. 将提升后的本能写入 `~/.claude/homunculus/instincts/personal/`，并设置 `scope: global`

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

@@ -0,0 +1,37 @@
+---
+description: 分析一个草稿提示，输出一个经过优化、富含ECC的版本，准备粘贴并运行。不执行任务——仅输出咨询分析。
+---
+
+# /prompt-optimize
+
+分析并优化以下提示语，以实现最大化的ECC杠杆效应。
+
+## 你的任务
+
+对下方用户的输入应用 **prompt-optimizer** 技能。遵循6阶段分析流程：
+
+0. **项目检测** — 读取 CLAUDE.md，从项目文件（package.json, go.mod, pyproject.toml 等）检测技术栈
+1. **意图检测** — 对任务类型进行分类（新功能、错误修复、重构、研究、测试、评审、文档、基础设施、设计）
+2. **范围评估** — 评估复杂度（简单 / 低 / 中 / 高 / 史诗级），如果检测到代码库，则使用其大小作为信号
+3. **ECC组件匹配** — 映射到特定的技能、命令、代理和模型层级
+4. **缺失上下文检测** — 识别信息缺口。如果缺少3个以上关键项，请在生成前请用户澄清
+5. **工作流与模型** — 确定生命周期阶段，推荐模型层级，如果复杂度为高/史诗级，则将其拆分为多个提示语
+
+## 输出要求
+
+* 呈现诊断结果、推荐的ECC组件以及使用 prompt-optimizer 技能中输出格式的优化后提示语
+* 提供 **完整版本**（详细）和 **快速版本**（紧凑，根据意图类型变化）
+* 使用与用户输入相同的语言进行回复
+* 优化后的提示语必须完整且可复制粘贴到新会话中直接使用
+* 以提供调整选项或明确下一步操作（用于启动单独的执行请求）的页脚结束
+
+## 关键
+
+请勿执行用户的任务。仅输出分析结果和优化后的提示语。
+如果用户要求直接执行，请说明 `/prompt-optimize` 仅产生咨询性输出，并告诉他们应启动一个常规的任务请求。
+
+注意：`blueprint` 是一个**技能**，而非斜杠命令。请写作“使用蓝图技能”，而不是将其呈现为 `/...` 命令。
+
+## 用户输入
+
+$ARGUMENTS

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

@@ -0,0 +1,31 @@
+---
+name: prune
+description: 删除超过 30 天且从未被提升的待处理本能
+command: true
+---
+
+# 清理待处理本能
+
+删除那些由系统自动生成、但从未经过审查或提升的过期待处理本能。
+
+## 实现
+
+使用插件根目录路径运行本能 CLI：
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" prune
+```
+
+或者如果 `CLAUDE_PLUGIN_ROOT` 未设置（手动安装）：
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py prune
+```
+
+## 用法
+
+```
+/prune                    # 删除超过 30 天的本能
+/prune --max-age 60       # 自定义年龄阈值（天）
+/prune --dry-run          # 仅预览，不实际删除
+```

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

@@ -0,0 +1,319 @@
+---
+description: 全面的Python代码审查，确保符合PEP 8标准、类型提示、安全性以及Pythonic惯用法。调用python-reviewer代理。
+---
+
+# Python 代码审查
+
+此命令调用 **python-reviewer** 代理进行全面的 Python 专项代码审查。
+
+## 此命令的功能
+
+1. **识别 Python 变更**：通过 `git diff` 查找修改过的 `.py` 文件
+2. **运行静态分析**：执行 `ruff`、`mypy`、`pylint`、`black --check`
+3. **安全扫描**：检查 SQL 注入、命令注入、不安全的反序列化
+4. **类型安全审查**：分析类型提示和 mypy 错误
+5. **Pythonic 代码检查**：验证代码是否遵循 PEP 8 和 Python 最佳实践
+6. **生成报告**：按严重程度对问题进行归类
+
+## 使用时机
+
+在以下情况使用 `/python-review`：
+
+* 编写或修改 Python 代码后
+* 提交 Python 变更前
+* 审查包含 Python 代码的拉取请求时
+* 接手新的 Python 代码库时
+* 学习 Pythonic 模式和惯用法时
+
+## 审查类别
+
+### 关键 (必须修复)
+
+* SQL/命令注入漏洞
+* 不安全的 eval/exec 使用
+* Pickle 不安全反序列化
+* 硬编码的凭证
+* YAML 不安全加载
+* 隐藏错误的裸 except 子句
+
+### 高 (应该修复)
+
+* 公共函数缺少类型提示
+* 可变默认参数
+* 静默吞掉异常
+* 未对资源使用上下文管理器
+* 使用 C 风格循环而非推导式
+* 使用 type() 而非 isinstance()
+* 无锁的竞态条件
+
+### 中 (考虑)
+
+* 违反 PEP 8 格式规范
+* 公共函数缺少文档字符串
+* 使用 print 语句而非 logging
+* 低效的字符串操作
+* 未使用命名常量的魔法数字
+* 未使用 f-strings 进行格式化
+* 不必要的列表创建
+
+## 运行的自动化检查
+
+```bash
+# Type checking
+mypy .
+
+# Linting and formatting
+ruff check .
+black --check .
+isort --check-only .
+
+# Security scanning
+bandit -r .
+
+# Dependency audit
+pip-audit
+safety check
+
+# Testing
+pytest --cov=app --cov-report=term-missing
+```
+
+## 使用示例
+
+````text
+User: /python-review
+
+Agent:
+# Python Code Review Report
+
+## Files Reviewed
+- app/routes/user.py (modified)
+- app/services/auth.py (modified)
+
+## Static Analysis Results
+✓ ruff: No issues
+✓ mypy: No errors
+WARNING: black: 2 files need reformatting
+✓ bandit: No security issues
+
+## Issues Found
+
+[CRITICAL] SQL Injection vulnerability
+File: app/routes/user.py:42
+Issue: User input directly interpolated into SQL query
+```python
+query = f"SELECT * FROM users WHERE id = {user_id}"  # Bad
+````
+
+修复：使用参数化查询
+
+```python
+query = "SELECT * FROM users WHERE id = %s"  # Good
+cursor.execute(query, (user_id,))
+```
+
+\[高] 可变默认参数
+文件：app/services/auth.py:18
+问题：可变默认参数导致共享状态
+
+```python
+def process_items(items=[]):  # Bad
+    items.append("new")
+    return items
+```
+
+修复：使用 None 作为默认值
+
+```python
+def process_items(items=None):  # Good
+    if items is None:
+        items = []
+    items.append("new")
+    return items
+```
+
+\[中] 缺少类型提示
+文件：app/services/auth.py:25
+问题：公共函数缺少类型注解
+
+```python
+def get_user(user_id):  # Bad
+    return db.find(user_id)
+```
+
+修复：添加类型提示
+
+```python
+def get_user(user_id: str) -> Optional[User]:  # Good
+    return db.find(user_id)
+```
+
+\[中] 未使用上下文管理器
+文件：app/routes/user.py:55
+问题：异常时文件未关闭
+
+```python
+f = open("config.json")  # Bad
+data = f.read()
+f.close()
+```
+
+修复：使用上下文管理器
+
+```python
+with open("config.json") as f:  # Good
+    data = f.read()
+```
+
+## 摘要
+
+* 关键：1
+* 高：1
+* 中：2
+
+建议：FAIL: 在关键问题修复前阻止合并
+
+## 所需的格式化
+
+运行：`black app/routes/user.py app/services/auth.py`
+
+````
+## 审批标准
+
+| 状态 | 条件 |
+|--------|-----------|
+| PASS: 批准 | 无 CRITICAL 或 HIGH 级别问题 |
+| WARNING: 警告 | 仅存在 MEDIUM 级别问题（谨慎合并） |
+| FAIL: 阻止 | 发现 CRITICAL 或 HIGH 级别问题 |
+
+## 与其他命令的集成
+
+- 首先使用 `/tdd` 确保测试通过
+- 使用 `/code-review` 处理非 Python 特定问题
+- 在提交前使用 `/python-review`
+- 如果静态分析工具失败，请使用 `/build-fix`
+
+## 框架特定审查
+
+### Django 项目
+审查员检查：
+- N+1 查询问题（使用 `select_related` 和 `prefetch_related`）
+- 模型更改缺少迁移
+- 在 ORM 可用时使用原始 SQL
+- 多步骤操作缺少 `transaction.atomic()`
+
+### FastAPI 项目
+审查员检查：
+- CORS 配置错误
+- 用于请求验证的 Pydantic 模型
+- 响应模型的正确性
+- 正确的 async/await 使用
+- 依赖注入模式
+
+### Flask 项目
+审查员检查：
+- 上下文管理（应用上下文、请求上下文）
+- 正确的错误处理
+- Blueprint 组织
+- 配置管理
+
+## 相关
+
+- Agent: `agents/python-reviewer.md`
+- Skills: `skills/python-patterns/`, `skills/python-testing/`
+
+## 常见修复
+
+### 添加类型提示
+```python
+# Before
+def calculate(x, y):
+    return x + y
+
+# After
+from typing import Union
+
+def calculate(x: Union[int, float], y: Union[int, float]) -> Union[int, float]:
+    return x + y
+````
+
+### 使用上下文管理器
+
+```python
+# Before
+f = open("file.txt")
+data = f.read()
+f.close()
+
+# After
+with open("file.txt") as f:
+    data = f.read()
+```
+
+### 使用列表推导式
+
+```python
+# Before
+result = []
+for item in items:
+    if item.active:
+        result.append(item.name)
+
+# After
+result = [item.name for item in items if item.active]
+```
+
+### 修复可变默认参数
+
+```python
+# Before
+def append(value, items=[]):
+    items.append(value)
+    return items
+
+# After
+def append(value, items=None):
+    if items is None:
+        items = []
+    items.append(value)
+    return items
+```
+
+### 使用 f-strings (Python 3.6+)
+
+```python
+# Before
+name = "Alice"
+greeting = "Hello, " + name + "!"
+greeting2 = "Hello, {}".format(name)
+
+# After
+greeting = f"Hello, {name}!"
+```
+
+### 修复循环中的字符串连接
+
+```python
+# Before
+result = ""
+for item in items:
+    result += str(item)
+
+# After
+result = "".join(str(item) for item in items)
+```
+
+## Python 版本兼容性
+
+审查者会指出代码何时使用了新 Python 版本的功能：
+
+| 功能 | 最低 Python 版本 |
+|---------|----------------|
+| 类型提示 | 3.5+ |
+| f-strings | 3.6+ |
+| 海象运算符 (`:=`) | 3.8+ |
+| 仅限位置参数 | 3.8+ |
+| Match 语句 | 3.10+ |
+| 类型联合 (`x \| None`) | 3.10+ |
+
+确保你的项目 `pyproject.toml` 或 `setup.py` 指定了正确的最低 Python 版本。

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

@@ -0,0 +1,30 @@
+# 质量门命令
+
+按需对文件或项目范围运行 ECC 质量管道。
+
+## 用法
+
+`/quality-gate [path|.] [--fix] [--strict]`
+
+* 默认目标：当前目录 (`.`)
+* `--fix`：在已配置的地方允许自动格式化/修复
+* `--strict`：在支持的地方警告即失败
+
+## 管道
+
+1. 检测目标的语言/工具。
+2. 运行格式化检查。
+3. 在可用时运行代码检查/类型检查。
+4. 生成简洁的修复列表。
+
+## 备注
+
+此命令镜像了钩子行为，但由操作员调用。
+
+## 参数
+
+$ARGUMENTS:
+
+* `[path|.]` 可选的目标路径
+* `--fix` 可选
+* `--strict` 可选

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

@@ -0,0 +1,83 @@
+# 重构清理
+
+通过测试验证安全识别和删除死代码的每一步。
+
+## 步骤 1：检测死代码
+
+根据项目类型运行分析工具：
+
+| 工具 | 查找内容 | 命令 |
+|------|--------------|---------|
+| knip | 未使用的导出、文件、依赖项 | `npx knip` |
+| depcheck | 未使用的 npm 依赖项 | `npx depcheck` |
+| ts-prune | 未使用的 TypeScript 导出 | `npx ts-prune` |
+| vulture | 未使用的 Python 代码 | `vulture src/` |
+| deadcode | 未使用的 Go 代码 | `deadcode ./...` |
+| cargo-udeps | 未使用的 Rust 依赖项 | `cargo +nightly udeps` |
+
+如果没有可用工具，使用 Grep 查找零次导入的导出：
+
+```
+# 查找导出项，然后检查是否有任何地方导入了它们
+```
+
+## 步骤 2：分类发现结果
+
+将发现结果按安全层级分类：
+
+| 层级 | 示例 | 操作 |
+|------|----------|--------|
+| **安全** | 未使用的工具函数、测试辅助函数、内部函数 | 放心删除 |
+| **谨慎** | 组件、API 路由、中间件 | 验证没有动态导入或外部使用者 |
+| **危险** | 配置文件、入口点、类型定义 | 在操作前仔细调查 |
+
+## 步骤 3：安全删除循环
+
+对于每个 **安全** 项：
+
+1. **运行完整测试套件** — 建立基准（全部通过）
+2. **删除死代码** — 使用编辑工具进行精确删除
+3. **重新运行测试套件** — 验证没有破坏任何功能
+4. **如果测试失败** — 立即使用 `git checkout -- <file>` 回滚并跳过此项
+5. **如果测试通过** — 处理下一项
+
+## 步骤 4：处理谨慎项
+
+在删除 **谨慎** 项之前：
+
+* 搜索动态导入：`import()`、`require()`、`__import__`
+* 搜索字符串引用：配置中的路由名称、组件名称
+* 检查是否从公共包 API 导出
+* 验证没有外部使用者（如果已发布，请检查依赖项）
+
+## 步骤 5：合并重复项
+
+删除死代码后，查找：
+
+* 近似的重复函数（>80% 相似）— 合并为一个
+* 冗余的类型定义 — 整合
+* 没有增加价值的包装函数 — 内联它们
+* 没有作用的重新导出 — 移除间接引用
+
+## 步骤 6：总结
+
+报告结果：
+
+```
+无用代码清理
+──────────────────────────────
+已删除：   12 个未使用函数
+           3 个未使用文件
+           5 个未使用依赖项
+已跳过：   2 个项目（测试失败）
+已节省：   ~450 行代码被移除
+──────────────────────────────
+所有测试通过 PASS:
+```
+
+## 规则
+
+* **切勿在不先运行测试的情况下删除代码**
+* **一次只删除一个** — 原子化的变更便于回滚
+* **如果不确定就跳过** — 保留死代码总比破坏生产环境好
+* **清理时不要重构** — 分离关注点（先清理，后重构）

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

@@ -0,0 +1,154 @@
+---
+description: 从 ~/.claude/sessions/ 加载最新的会话文件，并从上次会话结束的地方恢复工作，保留完整上下文。
+---
+
+# 恢复会话命令
+
+加载最后保存的会话状态，并在开始任何工作前完全熟悉情况。
+此命令是 `/save-session` 的对应命令。
+
+## 何时使用
+
+* 开始新会话以继续前一天的工作时
+* 因上下文限制而开始全新会话后
+* 当从其他来源移交会话文件时（只需提供文件路径）
+* 任何拥有会话文件并希望 Claude 在继续前完全吸收其内容的时候
+
+## 用法
+
+```
+/resume-session                                                      # 加载 ~/.claude/sessions/ 目录下最新的文件
+/resume-session 2024-01-15                                           # 加载该日期最新的会话
+/resume-session ~/.claude/sessions/2024-01-15-session.tmp           # 加载特定的旧格式文件
+/resume-session ~/.claude/sessions/2024-01-15-abc123de-session.tmp  # 加载当前短ID格式的会话文件
+```
+
+## 流程
+
+### 步骤 1：查找会话文件
+
+如果未提供参数：
+
+1. 检查 `~/.claude/sessions/`
+2. 选择最近修改的 `*-session.tmp` 文件
+3. 如果文件夹不存在或没有匹配的文件，告知用户：
+   ```
+   在 ~/.claude/sessions/ 中未找到会话文件。
+   请在会话结束时运行 /save-session 来创建一个。
+   ```
+   然后停止。
+
+如果提供了参数：
+
+* 如果看起来像日期 (`YYYY-MM-DD`)，则在 `~/.claude/sessions/` 中搜索匹配
+  `YYYY-MM-DD-session.tmp`（旧格式）或 `YYYY-MM-DD-<shortid>-session.tmp`（当前格式）的文件，
+  并加载该日期最近修改的版本
+* 如果看起来像文件路径，则直接读取该文件
+* 如果未找到，清晰报告并停止
+
+### 步骤 2：读取整个会话文件
+
+读取完整的文件。暂时不要总结。
+
+### 步骤 3：确认理解
+
+使用以下确切格式回复一份结构化简报：
+
+```
+会话已加载：[文件的实际解析路径]
+════════════════════════════════════════════════
+
+项目：[文件中的项目名称/主题]
+
+我们正在构建什么：
+[用你自己的话总结 2-3 句话]
+
+当前状态：
+PASS: 已完成：[数量] 项已确认
+ 进行中：[列出进行中的文件]
+ 未开始：[列出计划但未开始的文件]
+
+不应重试的内容：
+[列出每个失败的方法及其原因——此部分至关重要]
+
+待解决问题/阻碍：
+[列出任何阻碍或未解答的问题]
+
+下一步：
+[如果文件中已定义，则列出确切下一步]
+[如果未定义："未定义下一步——建议在开始前共同回顾'尚未尝试的方法'"]
+
+════════════════════════════════════════════════
+准备就绪。您希望做什么？
+```
+
+### 步骤 4：等待用户
+
+请**不要**自动开始工作。请**不要**触碰任何文件。等待用户指示下一步做什么。
+
+如果会话文件中明确定义了下一步，并且用户说"继续"或"是"或类似内容 — 则执行该确切步骤。
+
+如果未定义下一步 — 询问用户从哪里开始，并可选择性地从"尚未尝试的内容"部分提出建议。
+
+***
+
+## 边界情况
+
+**同一日期有多个会话** (`2024-01-15-session.tmp`, `2024-01-15-abc123de-session.tmp`)：
+加载该日期最近修改的匹配文件，无论其使用的是旧的无ID格式还是当前的短ID格式。
+
+**会话文件引用了已不存在的文件：**
+在简报中注明 — "WARNING: 会话中引用了 `path/to/file.ts`，但在磁盘上未找到。"
+
+**会话文件来自超过7天前：**
+注明时间间隔 — "WARNING: 此会话来自 N 天前（阈值：7天）。情况可能已发生变化。" — 然后正常继续。
+
+**用户直接提供了文件路径（例如，从队友处转发而来）：**
+读取它并遵循相同的简报流程 — 无论来源如何，格式都是相同的。
+
+**会话文件为空或格式错误：**
+报告："找到会话文件，但似乎为空或无法读取。您可能需要使用 /save-session 创建一个新的。"
+
+***
+
+## 示例输出
+
+```
+SESSION LOADED: /Users/you/.claude/sessions/2024-01-15-abc123de-session.tmp
+════════════════════════════════════════════════
+
+项目：my-app — JWT 认证
+
+构建目标：
+使用存储在 httpOnly cookie 中的 JWT 令牌实现用户认证。
+注册和登录端点已部分完成。通过中间件进行路由保护尚未开始。
+
+当前状态：
+PASS: 已完成：3 项（注册端点、JWT 生成、密码哈希）
+ 进行中：app/api/auth/login/route.ts（令牌有效，但 cookie 尚未设置）
+ 未开始：middleware.ts、app/login/page.tsx
+
+需避免的事项：
+FAIL: Next-Auth — 与自定义 Prisma 适配器冲突，每次请求均抛出适配器错误
+FAIL: localStorage 存储 JWT — 导致 SSR 水合不匹配，与 Next.js 不兼容
+
+待解决问题 / 阻碍：
+- cookies().set() 在路由处理器中是否有效，还是仅适用于服务器操作？
+
+下一步：
+在 app/api/auth/login/route.ts 中 — 使用以下方式将 JWT 设置为 httpOnly cookie：
+cookies().set('token', jwt, { httpOnly: true, secure: true, sameSite: 'strict' })
+随后使用 Postman 测试响应中是否包含 Set-Cookie 标头。
+
+════════════════════════════════════════════════
+准备继续。您希望做什么？
+```
+
+***
+
+## 注意事项
+
+* 加载时切勿修改会话文件 — 它是一个只读的历史记录
+* 简报格式是固定的 — 即使某些部分为空，也不要跳过
+* "不应重试的内容"必须始终显示，即使它只是说"无" — 这太重要了，不容遗漏
+* 恢复后，用户可能希望在新的会话结束时再次运行 `/save-session`，以创建一个新的带日期文件