@pzy560117/codex-harness 0.1.0 → 0.1.1

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

@@ -0,0 +1,72 @@
+# 工具链审计命令
+
+运行确定性仓库框架审计并返回优先级评分卡。
+
+## 使用方式
+
+`/harness-audit [scope] [--format text|json]`
+
+* `scope` (可选): `repo` (默认), `hooks`, `skills`, `commands`, `agents`
+* `--format`: 输出样式 (`text` 默认, `json` 用于自动化)
+
+## 确定性引擎
+
+始终运行：
+
+```bash
+node scripts/harness-audit.js <scope> --format <text|json>
+```
+
+此脚本是评分和检查的单一事实来源。不要发明额外的维度或临时添加评分点。
+
+评分标准版本：`2026-03-16`。
+
+该脚本计算 7 个固定类别（每个类别标准化为 `0-10`）：
+
+1. 工具覆盖度
+2. 上下文效率
+3. 质量门禁
+4. 记忆持久化
+5. 评估覆盖度
+6. 安全护栏
+7. 成本效率
+
+分数源自显式的文件/规则检查，并且对于同一提交是可复现的。
+
+## 输出约定
+
+返回：
+
+1. `overall_score` 分（满分 `max_score` 分；`repo` 为 70 分；范围限定审计则分数更小）
+2. 类别分数及具体发现项
+3. 失败的检查及其确切的文件路径
+4. 确定性输出的前 3 项行动（`top_actions`）
+5. 建议接下来应用的 ECC 技能
+
+## 检查清单
+
+* 直接使用脚本输出；不要手动重新评分。
+* 如果请求 `--format json`，则原样返回脚本的 JSON 输出。
+* 如果请求文本输出，则总结失败的检查和首要行动。
+* 包含来自 `checks[]` 和 `top_actions[]` 的确切文件路径。
+
+## 结果示例
+
+```text
+Harness 审计 (代码库): 66/70
+- 工具覆盖率: 10/10 (10/10 分)
+- 上下文效率: 9/10 (9/10 分)
+- 质量门禁: 10/10 (10/10 分)
+
+首要三项行动:
+1) [安全防护] 在 hooks/hooks.json 中添加提示/工具预检安全防护。 (hooks/hooks.json)
+2) [工具覆盖率] 同步 commands/harness-audit.md 和 .opencode/commands/harness-audit.md。 (.opencode/commands/harness-audit.md)
+3) [评估覆盖率] 提升 scripts/hooks/lib 目录下的自动化测试覆盖率。 (tests/)
+```
+
+## 参数
+
+$ARGUMENTS:
+
+* `repo|hooks|skills|commands|agents` (可选范围)
+* `--format text|json` (可选输出格式)

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

@@ -0,0 +1,67 @@
+---
+name: instinct-export
+description: 将项目/全局范围的本能导出到文件
+command: /instinct-export
+---
+
+# 本能导出命令
+
+将本能导出为可共享的格式。非常适合：
+
+* 与团队成员分享
+* 转移到新机器
+* 贡献给项目约定
+
+## 用法
+
+```
+/instinct-export                           # 导出所有个人本能
+/instinct-export --domain testing          # 仅导出测试相关本能
+/instinct-export --min-confidence 0.7      # 仅导出高置信度本能
+/instinct-export --output team-instincts.yaml
+/instinct-export --scope project --output project-instincts.yaml
+```
+
+## 操作步骤
+
+1. 检测当前项目上下文
+2. 按选定范围加载本能：
+   * `project`: 仅限当前项目
+   * `global`: 仅限全局
+   * `all`: 项目与全局合并（默认）
+3. 应用过滤器（`--domain`, `--min-confidence`）
+4. 将 YAML 格式的导出写入文件（如果未提供输出路径，则写入标准输出）
+
+## 输出格式
+
+创建一个 YAML 文件：
+
+```yaml
+# Instincts Export
+# Generated: 2025-01-22
+# Source: personal
+# Count: 12 instincts
+
+---
+id: prefer-functional-style
+trigger: "when writing new functions"
+confidence: 0.8
+domain: code-style
+source: session-observation
+scope: project
+project_id: a1b2c3d4e5f6
+project_name: my-app
+---
+
+# Prefer Functional Style
+
+## Action
+Use functional patterns over classes.
+```
+
+## 标志
+
+* `--domain <name>`: 仅导出指定领域
+* `--min-confidence <n>`: 最低置信度阈值
+* `--output <file>`: 输出文件路径（省略时打印到标准输出）
+* `--scope <project|global|all>`: 导出范围（默认：`all`）

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

@@ -0,0 +1,117 @@
+---
+name: instinct-import
+description: 从文件或URL导入本能到项目/全局作用域
+command: true
+---
+
+# 本能导入命令
+
+## 实现
+
+使用插件根路径运行本能 CLI：
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" import <file-or-url> [--dry-run] [--force] [--min-confidence 0.7] [--scope project|global]
+```
+
+或者，如果 `CLAUDE_PLUGIN_ROOT` 未设置（手动安装）：
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py import <file-or-url>
+```
+
+从本地文件路径或 HTTP(S) URL 导入本能。
+
+## 用法
+
+```
+/instinct-import team-instincts.yaml
+/instinct-import https://github.com/org/repo/instincts.yaml
+/instinct-import team-instincts.yaml --dry-run
+/instinct-import team-instincts.yaml --scope global --force
+```
+
+## 执行步骤
+
+1. 获取本能文件（本地路径或 URL）
+2. 解析并验证格式
+3. 检查与现有本能的重复项
+4. 合并或添加新本能
+5. 保存到继承的本能目录：
+   * 项目范围：`~/.claude/homunculus/projects/<project-id>/instincts/inherited/`
+   * 全局范围：`~/.claude/homunculus/instincts/inherited/`
+
+## 导入过程
+
+```
+ 从 team-instincts.yaml 导入本能
+================================================
+
+发现 12 个待导入的本能。
+
+正在分析冲突...
+
+## 新本能 (8)
+这些将被添加：
+  ✓ use-zod-validation (置信度: 0.7)
+  ✓ prefer-named-exports (置信度: 0.65)
+  ✓ test-async-functions (置信度: 0.8)
+  ...
+
+## 重复本能 (3)
+已存在类似本能：
+  WARNING: prefer-functional-style
+     本地: 0.8 置信度, 12 次观察
+     导入: 0.7 置信度
+     → 保留本地 (置信度更高)
+
+  WARNING: test-first-workflow
+     本地: 0.75 置信度
+     导入: 0.9 置信度
+     → 更新为导入 (置信度更高)
+
+导入 8 个新的，更新 1 个？
+```
+
+## 合并行为
+
+当导入一个已存在 ID 的本能时：
+
+* 置信度更高的导入会成为更新候选
+* 置信度相等或更低的导入将被跳过
+* 除非使用 `--force`，否则需要用户确认
+
+## 来源追踪
+
+导入的本能被标记为：
+
+```yaml
+source: inherited
+scope: project
+imported_from: "team-instincts.yaml"
+project_id: "a1b2c3d4e5f6"
+project_name: "my-project"
+```
+
+## 标志
+
+* `--dry-run`：仅预览而不导入
+* `--force`：跳过确认提示
+* `--min-confidence <n>`：仅导入高于阈值的本能
+* `--scope <project|global>`：选择目标范围（默认：`project`）
+
+## 输出
+
+导入后：
+
+```
+PASS: 导入完成！
+
+新增：8 项本能
+更新：1 项本能
+跳过：3 项本能（已存在同等或更高置信度的版本）
+
+新本能已保存至：~/.claude/homunculus/instincts/inherited/
+
+运行 /instinct-status 以查看所有本能。
+```

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

@@ -0,0 +1,59 @@
+---
+name: instinct-status
+description: 展示已学习的本能（项目+全局）并充满信心
+command: true
+---
+
+# 本能状态命令
+
+显示当前项目学习到的本能以及全局本能，按领域分组。
+
+## 实现
+
+使用插件根路径运行本能 CLI：
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" status
+```
+
+或者，如果未设置 `CLAUDE_PLUGIN_ROOT`（手动安装），则使用：
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py status
+```
+
+## 用法
+
+```
+/instinct-status
+```
+
+## 操作步骤
+
+1. 检测当前项目上下文（git remote/路径哈希）
+2. 从 `~/.claude/homunculus/projects/<project-id>/instincts/` 读取项目本能
+3. 从 `~/.claude/homunculus/instincts/` 读取全局本能
+4. 合并并应用优先级规则（当ID冲突时，项目本能覆盖全局本能）
+5. 按领域分组显示，包含置信度条和观察统计数据
+
+## 输出格式
+
+```
+============================================================
+  INSTINCT 状态 - 总计 12
+============================================================
+
+  项目: my-app (a1b2c3d4e5f6)
+  项目 instincts: 8
+  全局 instincts:  4
+
+## 项目范围内 (my-app)
+  ### 工作流 (3)
+    ███████░░░  70%  grep-before-edit [project]
+              触发条件: 当修改代码时
+
+## 全局 (适用于所有项目)
+  ### 安全 (2)
+    █████████░  85%  validate-user-input [global]
+              触发条件: 当处理用户输入时
+```

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

@@ -0,0 +1,176 @@
+---
+description: 逐步修复 Kotlin/Gradle 构建错误、编译器警告和依赖项问题。调用 kotlin-build-resolver 代理进行最小化、精准的修复。
+---
+
+# Kotlin 构建与修复
+
+此命令调用 **kotlin-build-resolver** 代理，以最小的改动增量修复 Kotlin 构建错误。
+
+## 此命令的作用
+
+1. **运行诊断**：执行 `./gradlew build`、`detekt`、`ktlintCheck`
+2. **解析错误**：按文件分组并按严重性排序
+3. **增量修复**：每次修复一个错误
+4. **验证每次修复**：每次更改后重新运行构建
+5. **报告摘要**：显示已修复的内容和剩余问题
+
+## 何时使用
+
+在以下情况使用 `/kotlin-build`：
+
+* `./gradlew build` 因错误而失败
+* Kotlin 编译器报告错误
+* `./gradlew detekt` 报告违规
+* Gradle 依赖项解析失败
+* 拉取更改后导致构建失败
+
+## 运行的诊断命令
+
+```bash
+# Primary build check
+./gradlew build 2>&1
+
+# Static analysis
+./gradlew detekt 2>&1 || echo "detekt not configured"
+./gradlew ktlintCheck 2>&1 || echo "ktlint not configured"
+
+# Dependency issues
+./gradlew dependencies --configuration runtimeClasspath 2>&1 | head -100
+
+# Optional deep refresh when caches or dependency metadata are suspect
+./gradlew build --refresh-dependencies
+```
+
+## 示例会话
+
+````text
+User: /kotlin-build
+
+Agent:
+# Kotlin Build Resolution
+
+## Initial Diagnostics
+
+```bash
+$ ./gradlew build
+e: src/main/kotlin/com/example/service/UserService.kt:25:15 Unresolved reference: UserRepository
+e: src/main/kotlin/com/example/routes/UserRoutes.kt:42:9 Type mismatch: inferred type is String but Int was expected
+e: src/main/kotlin/com/example/routes/UserRoutes.kt:58:5 'when' expression must be exhaustive
+```
+
+Errors found: 3
+
+## Fix 1: Unresolved Reference
+
+File: src/main/kotlin/com/example/service/UserService.kt:25
+Error: Unresolved reference: UserRepository
+Cause: Missing import
+
+```kotlin
+// Added import
+import com.example.repository.UserRepository
+```
+
+```bash
+$ ./gradlew build
+# 2 errors remaining
+```
+
+## Fix 2: Type Mismatch
+
+File: src/main/kotlin/com/example/routes/UserRoutes.kt:42
+Error: Type mismatch: inferred type is String but Int was expected
+
+```kotlin
+// Changed
+val count = call.parameters["count"]
+// To
+val count = call.parameters["count"]?.toIntOrNull()
+    ?: return@get call.respond(HttpStatusCode.BadRequest, "Invalid count")
+```
+
+```bash
+$ ./gradlew build
+# 1 error remaining
+```
+
+## Fix 3: Non-Exhaustive When
+
+File: src/main/kotlin/com/example/routes/UserRoutes.kt:58
+Error: 'when' expression must be exhaustive
+
+```kotlin
+// Added missing branch
+when (user.role) {
+    Role.ADMIN -> handleAdmin(user)
+    Role.USER -> handleUser(user)
+    Role.MODERATOR -> handleModerator(user) // Added
+}
+```
+
+```bash
+$ ./gradlew build
+# Build successful!
+```
+
+## Final Verification
+
+```bash
+$ ./gradlew detekt
+# No issues
+
+$ ./gradlew test
+# All tests passed
+```
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Build errors fixed | 3 |
+| Detekt issues fixed | 0 |
+| Files modified | 2 |
+| Remaining issues | 0 |
+
+Build Status: PASS: SUCCESS
+````
+
+## 常见的已修复错误
+
+| 错误 | 典型修复方法 |
+|-------|-------------|
+| `Unresolved reference: X` | 添加导入或依赖项 |
+| `Type mismatch` | 修复类型转换或赋值 |
+| `'when' must be exhaustive` | 添加缺失的密封类分支 |
+| `Suspend function can only be called from coroutine` | 添加 `suspend` 修饰符 |
+| `Smart cast impossible` | 使用局部 `val` 或 `let` |
+| `None of the following candidates is applicable` | 修复参数类型 |
+| `Could not resolve dependency` | 修复版本或添加仓库 |
+
+## 修复策略
+
+1. **首先修复构建错误** - 代码必须能够编译
+2. **其次修复 Detekt 违规** - 修复代码质量问题
+3. **再次修复 ktlint 警告** - 修复格式问题
+4. **一次修复一个** - 验证每次更改
+5. **最小化改动** - 不进行重构，仅修复问题
+
+## 停止条件
+
+代理将在以下情况下停止并报告：
+
+* 同一错误尝试修复 3 次后仍然存在
+* 修复引入了更多错误
+* 需要进行架构性更改
+* 缺少外部依赖项
+
+## 相关命令
+
+* `/kotlin-test` - 构建成功后运行测试
+* `/kotlin-review` - 审查代码质量
+* `/verify` - 完整的验证循环
+
+## 相关
+
+* 代理：`agents/kotlin-build-resolver.md`
+* 技能：`skills/kotlin-patterns/`

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

@@ -0,0 +1,144 @@
+---
+description: 全面的Kotlin代码审查，涵盖惯用模式、空安全、协程安全和安全性。调用kotlin-reviewer代理。
+---
+
+# Kotlin 代码审查
+
+此命令调用 **kotlin-reviewer** 代理进行全面的 Kotlin 专项代码审查。
+
+## 此命令的功能
+
+1. **识别 Kotlin 变更**：通过 `git diff` 查找修改过的 `.kt` 和 `.kts` 文件
+2. **运行构建与静态分析**：执行 `./gradlew build`、`detekt`、`ktlintCheck`
+3. **安全扫描**：检查 SQL 注入、命令注入、硬编码的密钥
+4. **空安全审查**：分析 `!!` 的使用、平台类型处理、不安全的转换
+5. **协程审查**：检查结构化并发、调度器使用、取消操作
+6. **生成报告**：按严重性对问题分类
+
+## 使用时机
+
+在以下情况使用 `/kotlin-review`：
+
+* 编写或修改 Kotlin 代码后
+* 提交 Kotlin 变更前
+* 审查包含 Kotlin 代码的拉取请求时
+* 接手新的 Kotlin 代码库时
+* 学习 Kotlin 惯用模式时
+
+## 审查类别
+
+### 严重（必须修复）
+
+* SQL/命令注入漏洞
+* 无正当理由强制解包 `!!`
+* 平台类型空安全违规
+* 使用 GlobalScope（违反结构化并发）
+* 硬编码的凭证
+* 不安全的反序列化
+
+### 高（应该修复）
+
+* 可变状态，而不可变状态即可满足
+* 在协程上下文中进行阻塞调用
+* 长循环中缺少取消检查
+* 对密封类型使用非穷举的 `when`
+* 函数过大（>50 行）
+* 嵌套过深（>4 层）
+
+### 中（考虑修复）
+
+* 非 Kotlin 惯用写法（Java 风格模式）
+* 缺少尾随逗号
+* 误用或嵌套作用域函数
+* 大型集合链中缺少序列化
+* 冗余的显式类型声明
+
+## 运行的自动化检查
+
+```bash
+# Build check
+./gradlew build
+
+# Static analysis
+./gradlew detekt
+
+# Formatting check
+./gradlew ktlintCheck
+
+# Tests
+./gradlew test
+```
+
+## 使用示例
+
+````text
+User: /kotlin-review
+
+Agent:
+# Kotlin Code Review Report
+
+## Files Reviewed
+- src/main/kotlin/com/example/service/UserService.kt (modified)
+- src/main/kotlin/com/example/routes/UserRoutes.kt (modified)
+
+## Static Analysis Results
+✓ Build: Successful
+✓ detekt: No issues
+WARNING: ktlint: 2 formatting warnings
+
+## Issues Found
+
+[CRITICAL] Force-Unwrap Null Safety
+File: src/main/kotlin/com/example/service/UserService.kt:28
+Issue: Using !! on nullable repository result
+```kotlin
+val user = repository.findById(id)!!  // NPE risk
+```
+Fix: Use safe call with error handling
+```kotlin
+val user = repository.findById(id)
+    ?: throw UserNotFoundException("User $id not found")
+```
+
+[HIGH] GlobalScope Usage
+File: src/main/kotlin/com/example/routes/UserRoutes.kt:45
+Issue: Using GlobalScope breaks structured concurrency
+```kotlin
+GlobalScope.launch {
+    notificationService.sendWelcome(user)
+}
+```
+Fix: Use the call's coroutine scope
+```kotlin
+launch {
+    notificationService.sendWelcome(user)
+}
+```
+
+## Summary
+- CRITICAL: 1
+- HIGH: 1
+- MEDIUM: 0
+
+Recommendation: FAIL: Block merge until CRITICAL issue is fixed
+````
+
+## 批准标准
+
+| 状态 | 条件 |
+|--------|-----------|
+| PASS: 批准 | 无严重或高优先级问题 |
+| WARNING: 警告 | 仅存在中优先级问题（谨慎合并） |
+| FAIL: 阻止 | 发现严重或高优先级问题 |
+
+## 与其他命令的集成
+
+* 首先使用 `/kotlin-test` 确保测试通过
+* 如果构建出错，使用 `/kotlin-build`
+* 提交前使用 `/kotlin-review`
+* 对于非 Kotlin 专项问题，使用 `/code-review`
+
+## 相关
+
+* 代理：`agents/kotlin-reviewer.md`
+* 技能：`skills/kotlin-patterns/`、`skills/kotlin-testing/`