@pzy560117/codex-harness 0.1.4 → 0.1.6

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

@@ -0,0 +1,315 @@
+---
+description: 为Kotlin强制执行TDD工作流程。首先编写Kotest测试，然后实施。使用Kover验证80%以上的覆盖率。
+---
+
+# Kotlin TDD 命令
+
+此命令使用 Kotest、MockK 和 Kover 为 Kotlin 代码强制执行测试驱动开发方法。
+
+## 此命令的作用
+
+1. **定义类型/接口**：首先搭建函数签名
+2. **编写 Kotest 测试**：创建全面的测试规范（RED）
+3. **运行测试**：验证测试因正确原因而失败
+4. **实现代码**：编写最少的代码以通过测试（GREEN）
+5. **重构**：在保持测试通过的同时进行改进
+6. **检查覆盖率**：确保使用 Kover 达到 80% 以上的覆盖率
+
+## 何时使用
+
+在以下情况下使用 `/kotlin-test`：
+
+* 实现新的 Kotlin 函数或类
+* 为现有的 Kotlin 代码添加测试覆盖率
+* 修复错误（首先编写失败的测试）
+* 构建关键业务逻辑
+* 学习 Kotlin 中的 TDD 工作流程
+
+## TDD 循环
+
+```
+RED     -> 编写失败的 Kotest 测试
+GREEN   -> 实现最小化代码以通过测试
+REFACTOR -> 改进代码，测试保持通过状态
+REPEAT  -> 进入下一个测试用例
+```
+
+## 示例会话
+
+````text
+用户：/kotlin-test 我需要一个验证用户注册请求的函数
+
+代理：
+# TDD 会话：注册验证器
+
+## 第一步：定义接口
+
+```kotlin
+// validator/RegistrationValidator.kt
+package com.example.validator
+
+data class RegistrationRequest(
+    val name: String,
+    val email: String,
+    val password: String,
+)
+
+sealed class ValidationResult {
+    data object Valid : ValidationResult()
+    data class Invalid(val errors: List<String>) : ValidationResult()
+}
+
+fun validateRegistration(request: RegistrationRequest): ValidationResult {
+    TODO("not implemented")
+}
+```
+
+## 第二步：编写 Kotest 测试（RED）
+
+```kotlin
+// validator/RegistrationValidatorTest.kt
+package com.example.validator
+
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.types.shouldBeInstanceOf
+
+class RegistrationValidatorTest : FunSpec({
+    test("valid registration returns Valid") {
+        val request = RegistrationRequest(
+            name = "Alice",
+            email = "alice@example.com",
+            password = "SecureP@ss1",
+        )
+
+        val result = validateRegistration(request)
+
+        result.shouldBeInstanceOf<ValidationResult.Valid>()
+    }
+
+    test("blank name returns Invalid") {
+        val request = RegistrationRequest(
+            name = "",
+            email = "alice@example.com",
+            password = "SecureP@ss1",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors shouldBe listOf("Name is required")
+    }
+
+    test("invalid email returns Invalid") {
+        val request = RegistrationRequest(
+            name = "Alice",
+            email = "not-an-email",
+            password = "SecureP@ss1",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors shouldBe listOf("Invalid email format")
+    }
+
+    test("short password returns Invalid") {
+        val request = RegistrationRequest(
+            name = "Alice",
+            email = "alice@example.com",
+            password = "short",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors shouldBe listOf("Password must be at least 8 characters")
+    }
+
+    test("multiple errors returns all errors") {
+        val request = RegistrationRequest(
+            name = "",
+            email = "bad",
+            password = "short",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors.size shouldBe 3
+    }
+})
+```
+
+## 第三步：运行测试 - 验证失败
+
+```bash
+$ ./gradlew test
+
+RegistrationValidatorTest > valid registration returns Valid FAILED
+  kotlin.NotImplementedError: An operation is not implemented
+
+FAILED (5 tests, 0 passed, 5 failed)
+```
+
+✓ 测试按预期失败（NotImplementedError）。
+
+## 第四步：实现最小代码（GREEN）
+
+```kotlin
+// validator/RegistrationValidator.kt
+package com.example.validator
+
+private val EMAIL_REGEX = Regex("^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$")
+private const val MIN_PASSWORD_LENGTH = 8
+
+fun validateRegistration(request: RegistrationRequest): ValidationResult {
+    val errors = buildList {
+        if (request.name.isBlank()) add("Name is required")
+        if (!EMAIL_REGEX.matches(request.email)) add("Invalid email format")
+        if (request.password.length < MIN_PASSWORD_LENGTH) add("Password must be at least $MIN_PASSWORD_LENGTH characters")
+    }
+
+    return if (errors.isEmpty()) ValidationResult.Valid
+    else ValidationResult.Invalid(errors)
+}
+```
+
+## 第五步：运行测试 - 验证通过
+
+```bash
+$ ./gradlew test
+
+RegistrationValidatorTest > valid registration returns Valid PASSED
+RegistrationValidatorTest > blank name returns Invalid PASSED
+RegistrationValidatorTest > invalid email returns Invalid PASSED
+RegistrationValidatorTest > short password returns Invalid PASSED
+RegistrationValidatorTest > multiple errors returns all errors PASSED
+
+PASSED (5 tests, 5 passed, 0 failed)
+```
+
+✓ 所有测试通过！
+
+## 第六步：检查覆盖率
+
+```bash
+$ ./gradlew koverHtmlReport
+
+Coverage: 100.0% of statements
+```
+
+✓ 覆盖率：100%
+
+## TDD 完成！
+````
+
+## 测试模式
+
+### StringSpec（最简单）
+
+```kotlin
+class CalculatorTest : StringSpec({
+    "add two positive numbers" {
+        Calculator.add(2, 3) shouldBe 5
+    }
+})
+```
+
+### BehaviorSpec（BDD）
+
+```kotlin
+class OrderServiceTest : BehaviorSpec({
+    Given("a valid order") {
+        When("placed") {
+            Then("should be confirmed") { /* ... */ }
+        }
+    }
+})
+```
+
+### 数据驱动测试
+
+```kotlin
+class ParserTest : FunSpec({
+    context("valid inputs") {
+        withData("2026-01-15", "2026-12-31", "2000-01-01") { input ->
+            parseDate(input).shouldNotBeNull()
+        }
+    }
+})
+```
+
+### 协程测试
+
+```kotlin
+class AsyncServiceTest : FunSpec({
+    test("concurrent fetch completes") {
+        runTest {
+            val result = service.fetchAll()
+            result.shouldNotBeEmpty()
+        }
+    }
+})
+```
+
+## 覆盖率命令
+
+```bash
+# Run tests with coverage
+./gradlew koverHtmlReport
+
+# Verify coverage thresholds
+./gradlew koverVerify
+
+# XML report for CI
+./gradlew koverXmlReport
+
+# Open HTML report
+open build/reports/kover/html/index.html
+
+# Run specific test class
+./gradlew test --tests "com.example.UserServiceTest"
+
+# Run with verbose output
+./gradlew test --info
+```
+
+## 覆盖率目标
+
+| 代码类型 | 目标 |
+|-----------|--------|
+| 关键业务逻辑 | 100% |
+| 公共 API | 90%+ |
+| 通用代码 | 80%+ |
+| 生成的代码 | 排除 |
+
+## TDD 最佳实践
+
+**应做：**
+
+* 首先编写测试，在任何实现之前
+* 每次更改后运行测试
+* 使用 Kotest 匹配器进行表达性断言
+* 使用 MockK 的 `coEvery`/`coVerify` 来处理挂起函数
+* 测试行为，而非实现细节
+* 包含边界情况（空值、null、最大值）
+
+**不应做：**
+
+* 在测试之前编写实现
+* 跳过 RED 阶段
+* 直接测试私有函数
+* 在协程测试中使用 `Thread.sleep()`
+* 忽略不稳定的测试
+
+## 相关命令
+
+* `/kotlin-build` - 修复构建错误
+* `/kotlin-review` - 在实现后审查代码
+* `/verify` - 运行完整的验证循环
+
+## 相关
+
+* 技能：`skills/kotlin-testing/`
+* 技能：`skills/tdd-workflow/`

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

@@ -0,0 +1,117 @@
+---
+description: "从会话中提取可重用模式，在保存前自我评估质量，并确定正确的保存位置（全局与项目）。"
+---
+
+# /learn-eval - 提取、评估、然后保存
+
+扩展 `/learn`，在编写任何技能文件之前，加入质量门控、保存位置决策和知识放置意识。
+
+## 提取内容
+
+寻找：
+
+1. **错误解决模式** — 根本原因 + 修复方法 + 可重用性
+2. **调试技术** — 非显而易见的步骤、工具组合
+3. **变通方法** — 库的怪癖、API 限制、特定版本的修复
+4. **项目特定模式** — 约定、架构决策、集成模式
+
+## 流程
+
+1. 回顾会话，寻找可提取的模式
+
+2. 识别最有价值/可重用的见解
+
+3. **确定保存位置：**
+   * 提问："这个模式在其他项目中会有用吗？"
+   * **全局** (`~/.claude/skills/learned/`)：可在 2 个以上项目中使用的通用模式（bash 兼容性、LLM API 行为、调试技术等）
+   * **项目** (当前项目中的 `.claude/skills/learned/`)：项目特定的知识（特定配置文件的怪癖、项目特定的架构决策等）
+   * 不确定时，选择全局（将全局 → 项目移动比反向操作更容易）
+
+4. 使用此格式起草技能文件：
+
+```markdown
+---
+name: pattern-name
+description: "Under 130 characters"
+user-invocable: false
+origin: auto-extracted
+---
+
+# [描述性模式名称]
+
+**提取日期：** [日期]
+**上下文：** [简要描述此模式适用的场景]
+
+## 问题
+[此模式解决的具体问题 - 请详细说明]
+
+## 解决方案
+[模式/技术/变通方案 - 附带代码示例]
+
+## 何时使用
+[触发条件]
+```
+
+5. **质量门控 — 清单 + 整体裁决**
+
+   ### 5a. 必需清单（通过实际阅读文件进行验证）
+
+   在评估草案**之前**，执行以下所有操作：
+
+   * \[ ] 使用关键字在 `~/.claude/skills/` 和相关项目的 `.claude/skills/` 文件中进行 grep 搜索，检查内容重叠
+   * \[ ] 检查 MEMORY.md（项目级和全局级）以查找重叠内容
+   * \[ ] 考虑是否追加到现有技能即可满足需求
+   * \[ ] 确认这是一个可复用的模式，而非一次性修复
+
+   ### 5b. 整体裁决
+
+   综合清单结果和草案质量，然后选择**以下一项**：
+
+   | 裁决 | 含义 | 下一步行动 |
+   |---------|---------|-------------|
+   | **保存** | 独特、具体、范围明确 | 进行到步骤 6 |
+   | **改进后保存** | 有价值但需要改进 | 列出改进项 → 修订 → 重新评估（一次） |
+   | **吸收到 \[X]** | 应追加到现有技能 | 显示目标技能和添加内容 → 步骤 6 |
+   | **放弃** | 琐碎、冗余或过于抽象 | 解释原因并停止 |
+
+**指导维度**（用于告知裁决，不进行评分）：
+
+* **具体性和可操作性**：包含可立即使用的代码示例或命令
+* **范围契合度**：名称、触发条件和内容保持一致，并专注于单一模式
+* **独特性**：提供现有技能未涵盖的价值（基于清单结果）
+* **可复用性**：在未来的会话中存在现实的触发场景
+
+6. **裁决特定的确认流程**
+
+   * **改进后保存**：呈现必需的改进项 + 修订后的草案 + 一次重新评估后的更新清单/裁决；如果修订后的裁决是**保存**，则在用户确认后保存，否则遵循新的裁决
+   * **保存**：呈现保存路径 + 清单结果 + 1行裁决理由 + 完整草案 → 在用户确认后保存
+   * **吸收到 \[X]**：呈现目标路径 + 添加内容（diff格式） + 清单结果 + 裁决理由 → 在用户确认后追加
+   * **放弃**：仅显示清单结果 + 推理（无需确认）
+
+7. 保存 / 吸收到确定的位置
+
+## 步骤 5 的输出格式
+
+```
+### 检查清单
+- [x] skills/ grep: 无重叠 (或: 发现重叠 → 详情)
+- [x] MEMORY.md: 无重叠 (或: 发现重叠 → 详情)
+- [x] 现有技能追加: 新文件合适 (或: 应追加到 [X])
+- [x] 可复用性: 已确认 (或: 一次性 → 丢弃)
+
+### 裁决: 保存 / 改进后保存 / 吸收到 [X] / 丢弃
+
+**理由:** (用 1-2 句话解释裁决)
+```
+
+## 设计原理
+
+此版本用基于清单的整体裁决系统取代了之前的 5 维度数字评分标准（具体性、可操作性、范围契合度、非冗余性、覆盖度，评分 1-5）。现代前沿模型（Opus 4.6+）具有强大的情境判断能力 —— 将丰富的定性信号强行压缩为数字评分会丢失细微差别，并可能产生误导性的总分。整体方法让模型自然地权衡所有因素，产生更准确的保存/放弃决策，同时明确的清单确保不会跳过任何关键检查。
+
+## 注意事项
+
+* 不要提取琐碎的修复（拼写错误、简单的语法错误）
+* 不要提取一次性问题（特定的 API 中断等）
+* 专注于那些将在未来会话中节省时间的模式
+* 保持技能聚焦 —— 每个技能一个模式
+* 当裁决为“吸收”时，追加到现有技能，而不是创建新文件

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

@@ -0,0 +1,70 @@
+# /learn - 提取可重用模式
+
+分析当前会话，提取值得保存为技能的任何模式。
+
+## 触发时机
+
+在会话期间的任何时刻，当你解决了一个非平凡问题时，运行 `/learn`。
+
+## 提取内容
+
+寻找：
+
+1. **错误解决模式**
+   * 出现了什么错误？
+   * 根本原因是什么？
+   * 什么方法修复了它？
+   * 这对解决类似错误是否可重用？
+
+2. **调试技术**
+   * 不明显的调试步骤
+   * 有效的工具组合
+   * 诊断模式
+
+3. **变通方法**
+   * 库的怪癖
+   * API 限制
+   * 特定版本的修复
+
+4. **项目特定模式**
+   * 发现的代码库约定
+   * 做出的架构决策
+   * 集成模式
+
+## 输出格式
+
+在 `~/.claude/skills/learned/[pattern-name].md` 创建一个技能文件：
+
+```markdown
+# [Descriptive Pattern Name]
+
+**Extracted:** [Date]
+**Context:** [Brief description of when this applies]
+
+## Problem
+[What problem this solves - be specific]
+
+## Solution
+[The pattern/technique/workaround]
+
+## Example
+[Code example if applicable]
+
+## When to Use
+[Trigger conditions - what should activate this skill]
+```
+
+## 流程
+
+1. 回顾会话，寻找可提取的模式
+2. 识别最有价值/可重用的见解
+3. 起草技能文件
+4. 在保存前请用户确认
+5. 保存到 `~/.claude/skills/learned/`
+
+## 注意事项
+
+* 不要提取琐碎的修复（拼写错误、简单的语法错误）
+* 不要提取一次性问题（特定的 API 中断等）
+* 专注于那些将在未来会话中节省时间的模式
+* 保持技能的专注性 - 一个技能对应一个模式

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

@@ -0,0 +1,33 @@
+# 循环启动命令
+
+使用安全默认设置启动一个受管理的自主循环模式。
+
+## 用法
+
+`/loop-start [pattern] [--mode safe|fast]`
+
+* `pattern`: `sequential`, `continuous-pr`, `rfc-dag`, `infinite`
+* `--mode`:
+  * `safe` (默认): 严格的质量门禁和检查点
+  * `fast`: 为速度而减少门禁
+
+## 流程
+
+1. 确认仓库状态和分支策略。
+2. 选择循环模式和模型层级策略。
+3. 为所选模式启用所需的钩子/配置文件。
+4. 创建循环计划并在 `.claude/plans/` 下编写运行手册。
+5. 打印用于启动和监控循环的命令。
+
+## 必需的安全检查
+
+* 在首次循环迭代前验证测试通过。
+* 确保 `ECC_HOOK_PROFILE` 未在全局范围内被禁用。
+* 确保循环有明确的停止条件。
+
+## 参数
+
+$ARGUMENTS:
+
+* `<pattern>` 可选 (`sequential|continuous-pr|rfc-dag|infinite`)
+* `--mode safe|fast` 可选

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

@@ -0,0 +1,25 @@
+# 循环状态命令
+
+检查活动循环状态、进度和故障信号。
+
+## 用法
+
+`/loop-status [--watch]`
+
+## 报告内容
+
+* 活动循环模式
+* 当前阶段和最后一个成功的检查点
+* 失败的检查（如果有）
+* 预计的时间/成本偏差
+* 建议的干预措施（继续/暂停/停止）
+
+## 监视模式
+
+当 `--watch` 存在时，定期刷新状态并显示状态变化。
+
+## 参数
+
+$ARGUMENTS:
+
+* `--watch` 可选

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

@@ -0,0 +1,27 @@
+# 模型路由命令
+
+根据任务复杂度和预算推荐最佳模型层级。
+
+## 用法
+
+`/model-route [task-description] [--budget low|med|high]`
+
+## 路由启发式规则
+
+* `haiku`: 确定性、低风险的机械性变更
+* `sonnet`: 实现和重构的默认选择
+* `opus`: 架构设计、深度评审、模糊需求
+
+## 必需输出
+
+* 推荐的模型
+* 置信度
+* 该模型适合的原因
+* 如果首次尝试失败，备用的回退模型
+
+## 参数
+
+$ARGUMENTS:
+
+* `[task-description]` 可选，自由文本
+* `--budget low|med|high` 可选