@pzy560117/codex-harness 0.1.4 → 0.1.6

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

@@ -0,0 +1,11 @@
+---
+description: "扫描技能以提取跨领域原则并将其提炼为规则"
+---
+
+# /rules-distill — 从技能中提炼原则为规则
+
+扫描已安装的技能，提取跨领域原则，并将其提炼为规则。
+
+## 流程
+
+遵循 `rules-distill` 技能中定义的完整工作流程。

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

@@ -0,0 +1,189 @@
+---
+description: 逐步修复 Rust 构建错误、借用检查器问题和依赖问题。调用 rust-build-resolver 代理以进行最小化、精确的修复。
+---
+
+# Rust 构建与修复
+
+此命令调用 **rust-build-resolver** 代理，以最小改动逐步修复 Rust 构建错误。
+
+## 此命令的作用
+
+1. **运行诊断**：执行 `cargo check`、`cargo clippy`、`cargo fmt --check`
+2. **解析错误**：识别错误代码和受影响的文件
+3. **逐步修复**：一次修复一个错误
+4. **验证每次修复**：每次更改后重新运行 `cargo check`
+5. **报告摘要**：显示已修复的内容和剩余问题
+
+## 使用时机
+
+在以下情况下使用 `/rust-build`：
+
+* `cargo build` 或 `cargo check` 因错误而失败时
+* `cargo clippy` 报告警告时
+* 借用检查器或生命周期错误阻碍编译时
+* Cargo 依赖项解析失败时
+* 拉取导致构建破坏的更改后
+
+## 运行的诊断命令
+
+```bash
+# Primary build check
+cargo check 2>&1
+
+# Lints and suggestions
+cargo clippy -- -D warnings 2>&1
+
+# Formatting check
+cargo fmt --check 2>&1
+
+# Dependency issues
+cargo tree --duplicates
+
+# Security audit (if available)
+if command -v cargo-audit >/dev/null; then cargo audit; else echo "cargo-audit not installed"; fi
+```
+
+## 示例会话
+
+````text
+User: /rust-build
+
+Agent:
+# Rust Build Resolution
+
+## Initial Diagnostics
+
+```bash
+$ cargo check
+error[E0502]: cannot borrow `map` as mutable because it is also borrowed as immutable
+  --> src/service/cache.rs:25:5
+error[E0308]: mismatched types
+  --> src/handler/api.rs:42:12
+error[E0425]: cannot find value `db` in this scope
+  --> src/handler/api.rs:58:9
+```
+
+Errors found: 3
+
+## Fix 1: Borrow Checker Error
+
+File: src/service/cache.rs:25
+Error: E0502 — cannot borrow `map` as mutable because also borrowed as immutable
+Cause: Immutable borrow still active during mutable insert
+
+```rust
+// Changed: restructured to end immutable borrow before mutable access
+if !map.contains_key("key") {
+    map.insert("key".into(), default);
+}
+```
+
+```bash
+$ cargo check
+# 2 errors remaining
+```
+
+## Fix 2: Type Mismatch
+
+File: src/handler/api.rs:42
+Error: E0308 — mismatched types: expected `usize`, found `&str`
+
+```rust
+// Changed
+let count = params.get("count");
+// To
+let count: usize = params.get("count")
+    .and_then(|s| s.parse().ok())
+    .unwrap_or(0);
+```
+
+```bash
+$ cargo check
+# 1 error remaining
+```
+
+## Fix 3: Unresolved Name
+
+File: src/handler/api.rs:58
+Error: E0425 — cannot find value `db` in this scope
+Cause: Missing import
+
+```rust
+// Added
+use crate::db;
+```
+
+```bash
+$ cargo check
+# Build successful!
+```
+
+## Final Verification
+
+```bash
+$ cargo clippy -- -D warnings
+# No warnings
+
+$ cargo test
+running 6 tests
+test service::cache::tests::test_insert ... ok
+test service::cache::tests::test_get ... ok
+test handler::api::tests::test_parse_count ... ok
+test handler::api::tests::test_missing_count ... ok
+test handler::api::tests::test_db_import ... ok
+test handler::api::tests::test_response ... ok
+
+test result: ok. 6 passed; 0 failed; 0 ignored
+```
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Build errors fixed | 3 |
+| Clippy warnings fixed | 0 |
+| Files modified | 2 |
+| Remaining issues | 0 |
+
+Build Status: SUCCESS
+````
+
+## 修复的常见错误
+
+| 错误 | 典型修复方法 |
+|-------|-------------|
+| `cannot borrow as mutable` | 重构以先结束不可变借用；仅在合理情况下克隆 |
+| `does not live long enough` | 使用拥有所有权的类型或添加生命周期注解 |
+| `cannot move out of` | 重构以获取所有权；仅作为最后手段进行克隆 |
+| `mismatched types` | 添加 `.into()`、`as` 或显式转换 |
+| `trait X not implemented` | 添加 `#[derive(Trait)]` 或手动实现 |
+| `unresolved import` | 添加到 Cargo.toml 或修复 `use` 路径 |
+| `cannot find value` | 添加导入或修复路径 |
+
+## 修复策略
+
+1. **首先解决构建错误** - 代码必须能够编译
+2. **其次解决 Clippy 警告** - 修复可疑的构造
+3. **第三处理格式化** - 符合 `cargo fmt` 标准
+4. **一次修复一个** - 验证每次更改
+5. **最小化改动** - 不进行重构，仅修复问题
+
+## 停止条件
+
+代理将在以下情况下停止并报告：
+
+* 同一错误尝试 3 次后仍然存在
+* 修复引入了更多错误
+* 需要架构性更改
+* 借用检查器错误需要重新设计数据所有权
+
+## 相关命令
+
+* `/rust-test` - 构建成功后运行测试
+* `/rust-review` - 审查代码质量
+* `/verify` - 完整验证循环
+
+## 相关
+
+* 代理：`agents/rust-build-resolver.md`
+* 技能：`skills/rust-patterns/`

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

@@ -0,0 +1,146 @@
+---
+description: 全面的Rust代码审查，涵盖所有权、生命周期、错误处理、不安全代码使用以及惯用模式。调用rust-reviewer代理。
+---
+
+# Rust 代码审查
+
+此命令调用 **rust-reviewer** 代理进行全面的 Rust 专项代码审查。
+
+## 此命令的作用
+
+1. **验证自动化检查**：运行 `cargo check`、`cargo clippy -- -D warnings`、`cargo fmt --check` 和 `cargo test` —— 任何一项失败则停止
+2. **识别 Rust 变更**：通过 `git diff HEAD~1`（或针对 PR 使用 `git diff main...HEAD`）查找修改过的 `.rs` 文件
+3. **运行安全审计**：如果可用，则执行 `cargo audit`
+4. **安全扫描**：检查不安全使用、命令注入、硬编码密钥
+5. **所有权审查**：分析不必要的克隆、生命周期问题、借用模式
+6. **生成报告**：按严重性对问题进行分类
+
+## 何时使用
+
+在以下情况下使用 `/rust-review`：
+
+* 编写或修改 Rust 代码之后
+* 提交 Rust 变更之前
+* 审查包含 Rust 代码的拉取请求时
+* 接手新的 Rust 代码库时
+* 学习惯用的 Rust 模式时
+
+## 审查类别
+
+### 关键（必须修复）
+
+* 生产代码路径中未经检查的 `unwrap()`/`expect()`
+* 没有 `// SAFETY:` 注释记录不变量的 `unsafe`
+* 查询中通过字符串插值导致的 SQL 注入
+* 在 `std::process::Command` 中通过未经验证的输入导致的命令注入
+* 硬编码凭据
+* 通过原始指针导致的释放后使用
+
+### 高（应该修复）
+
+* 为满足借用检查器而进行的不必要的 `.clone()`
+* 参数为 `String`，而 `&str` 或 `impl AsRef<str>` 即可满足
+* 在异步上下文中的阻塞操作（`std::thread::sleep`、`std::fs`）
+* 共享类型上缺少 `Send`/`Sync` 约束
+* 对业务关键枚举使用通配符 `_ =>` 匹配
+* 大型函数（>50 行）
+
+### 中（考虑）
+
+* 在热点路径中不必要的分配
+* 已知大小时缺少 `with_capacity`
+* 未说明理由就抑制 clippy 警告
+* 公共 API 缺少 `///` 文档
+* 对于忽略返回值很可能是错误的非 `must_use` 返回类型，考虑使用 `#[must_use]`
+
+## 运行的自动化检查
+
+```bash
+# Build gate (must pass before review)
+cargo check
+
+# Lints and suggestions
+cargo clippy -- -D warnings
+
+# Formatting
+cargo fmt --check
+
+# Tests
+cargo test
+
+# Security audit (if available)
+if command -v cargo-audit >/dev/null; then cargo audit; else echo "cargo-audit not installed"; fi
+```
+
+## 使用示例
+
+````text
+User: /rust-review
+
+Agent:
+# Rust Code Review Report
+
+## Files Reviewed
+- src/service/user.rs (modified)
+- src/handler/api.rs (modified)
+
+## Static Analysis Results
+- Build: Successful
+- Clippy: No warnings
+- Formatting: Passed
+- Tests: All passing
+
+## Issues Found
+
+[CRITICAL] Unchecked unwrap in Production Path
+File: src/service/user.rs:28
+Issue: Using `.unwrap()` on database query result
+```rust
+let user = db.find_by_id(id).unwrap();  // Panics on missing user
+```
+Fix: Propagate error with context
+```rust
+let user = db.find_by_id(id)
+    .context("failed to fetch user")?;
+```
+
+[HIGH] Unnecessary Clone
+File: src/handler/api.rs:45
+Issue: Cloning String to satisfy borrow checker
+```rust
+let name = user.name.clone();
+process(&user, &name);
+```
+Fix: Restructure to avoid clone
+```rust
+let result = process_name(&user.name);
+use_user(&user, result);
+```
+
+## Summary
+- CRITICAL: 1
+- HIGH: 1
+- MEDIUM: 0
+
+Recommendation: Block merge until CRITICAL issue is fixed
+````
+
+## 批准标准
+
+| 状态 | 条件 |
+|--------|-----------|
+| 批准 | 无关键或高优先级问题 |
+| 警告 | 仅存在中优先级问题（谨慎合并） |
+| 阻止 | 发现关键或高优先级问题 |
+
+## 与其他命令的集成
+
+* 首先使用 `/rust-test` 确保测试通过
+* 如果出现构建错误，使用 `/rust-build`
+* 提交前使用 `/rust-review`
+* 对于非 Rust 专项问题，使用 `/code-review`
+
+## 相关
+
+* 代理：`agents/rust-reviewer.md`
+* 技能：`skills/rust-patterns/`、`skills/rust-testing/`

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

@@ -0,0 +1,311 @@
+---
+description: 为Rust强制执行TDD工作流。先写测试，然后实现。使用cargo-llvm-cov验证80%以上的覆盖率。
+---
+
+# Rust TDD 命令
+
+该命令使用 `#[test]`、rstest、proptest 和 mockall 来强制执行 Rust 代码的测试驱动开发方法。
+
+## 该命令的作用
+
+1. **定义类型/特征**：使用 `todo!()` 搭建函数签名
+2. **编写测试**：创建全面的测试模块（RED）
+3. **运行测试**：验证测试因正确的原因而失败
+4. **实现代码**：编写通过测试所需的最少代码（GREEN）
+5. **重构**：在保持测试通过的前提下进行改进
+6. **检查覆盖率**：使用 cargo-llvm-cov 确保 80%+ 的覆盖率
+
+## 何时使用
+
+在以下情况使用 `/rust-test`：
+
+* 实现新的 Rust 函数、方法或特征时
+* 为现有 Rust 代码添加测试覆盖时
+* 修复错误时（首先编写失败的测试）
+* 构建关键业务逻辑时
+* 学习 Rust 中的 TDD 工作流程时
+
+## TDD 循环
+
+```
+RED     -> 先编写失败的测试
+GREEN   -> 实现最小化代码以通过测试
+REFACTOR -> 改进代码，保持测试通过
+REPEAT  -> 下一个测试用例
+```
+
+## 示例会话
+
+````text
+User: /rust-test I need a function to validate user registration
+
+Agent:
+# TDD Session: Registration Validator
+
+## Step 1: Define Interface
+
+```rust
+// src/validator.rs
+pub struct RegistrationRequest {
+    pub name: String,
+    pub email: String,
+    pub password: String,
+}
+
+pub enum ValidationResult {
+    Valid,
+    Invalid(Vec<String>),
+}
+
+pub fn validate_registration(request: &RegistrationRequest) -> ValidationResult {
+    todo!()
+}
+```
+
+## Step 2: Write Tests (RED)
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn valid_registration_returns_valid() {
+        let request = RegistrationRequest {
+            name: "Alice".into(),
+            email: "alice@example.com".into(),
+            password: "SecureP@ss1".into(),
+        };
+        assert!(matches!(validate_registration(&request), ValidationResult::Valid));
+    }
+
+    #[test]
+    fn blank_name_returns_invalid() {
+        let request = RegistrationRequest {
+            name: "".into(),
+            email: "alice@example.com".into(),
+            password: "SecureP@ss1".into(),
+        };
+        match validate_registration(&request) {
+            ValidationResult::Invalid(errors) => {
+                assert!(errors.contains(&"Name is required".to_string()));
+            }
+            ValidationResult::Valid => panic!("expected Invalid"),
+        }
+    }
+
+    #[test]
+    fn invalid_email_returns_invalid() {
+        let request = RegistrationRequest {
+            name: "Alice".into(),
+            email: "not-an-email".into(),
+            password: "SecureP@ss1".into(),
+        };
+        assert!(matches!(
+            validate_registration(&request),
+            ValidationResult::Invalid(_)
+        ));
+    }
+
+    #[test]
+    fn short_password_returns_invalid() {
+        let request = RegistrationRequest {
+            name: "Alice".into(),
+            email: "alice@example.com".into(),
+            password: "short".into(),
+        };
+        assert!(matches!(
+            validate_registration(&request),
+            ValidationResult::Invalid(_)
+        ));
+    }
+}
+```
+
+## Step 3: Run Tests — Verify FAIL
+
+```bash
+$ cargo test
+running 4 tests
+test tests::valid_registration_returns_valid ... FAILED (not yet implemented)
+test tests::blank_name_returns_invalid ... FAILED
+test tests::invalid_email_returns_invalid ... FAILED
+test tests::short_password_returns_invalid ... FAILED
+```
+
+Tests fail as expected (todo! panic).
+
+## Step 4: Implement Minimal Code (GREEN)
+
+```rust
+pub fn validate_registration(request: &RegistrationRequest) -> ValidationResult {
+    let mut errors = Vec::new();
+
+    if request.name.trim().is_empty() {
+        errors.push("Name is required".into());
+    }
+    if !request.email.contains('@') {
+        errors.push("Invalid email format".into());
+    }
+    if request.password.len() < 8 {
+        errors.push("Password must be at least 8 characters".into());
+    }
+
+    if errors.is_empty() {
+        ValidationResult::Valid
+    } else {
+        ValidationResult::Invalid(errors)
+    }
+}
+```
+
+## Step 5: Run Tests — Verify PASS
+
+```bash
+$ cargo test
+running 4 tests
+test tests::valid_registration_returns_valid ... ok
+test tests::blank_name_returns_invalid ... ok
+test tests::invalid_email_returns_invalid ... ok
+test tests::short_password_returns_invalid ... ok
+
+test result: ok. 4 passed; 0 failed
+```
+
+All tests passing!
+
+## Step 6: Check Coverage
+
+```bash
+$ cargo llvm-cov
+Coverage: 100.0% of lines
+```
+
+Coverage: 100%
+
+## TDD Complete!
+````
+
+## 测试模式
+
+### 单元测试
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn adds_two_numbers() {
+        assert_eq!(add(2, 3), 5);
+    }
+
+    #[test]
+    fn handles_error() -> Result<(), Box<dyn std::error::Error>> {
+        let result = parse_config(r#"port = 8080"#)?;
+        assert_eq!(result.port, 8080);
+        Ok(())
+    }
+}
+```
+
+### 使用 rstest 进行参数化测试
+
+```rust
+use rstest::{rstest, fixture};
+
+#[rstest]
+#[case("hello", 5)]
+#[case("", 0)]
+#[case("rust", 4)]
+fn test_string_length(#[case] input: &str, #[case] expected: usize) {
+    assert_eq!(input.len(), expected);
+}
+```
+
+### 异步测试
+
+```rust
+#[tokio::test]
+async fn fetches_data_successfully() {
+    let client = TestClient::new().await;
+    let result = client.get("/data").await;
+    assert!(result.is_ok());
+}
+```
+
+### 基于属性的测试
+
+```rust
+use proptest::prelude::*;
+
+proptest! {
+    #[test]
+    fn encode_decode_roundtrip(input in ".*") {
+        let encoded = encode(&input);
+        let decoded = decode(&encoded).unwrap();
+        assert_eq!(input, decoded);
+    }
+}
+```
+
+## 覆盖率命令
+
+```bash
+# Summary report
+cargo llvm-cov
+
+# HTML report
+cargo llvm-cov --html
+
+# Fail if below threshold
+cargo llvm-cov --fail-under-lines 80
+
+# Run specific test
+cargo test test_name
+
+# Run with output
+cargo test -- --nocapture
+
+# Run without stopping on first failure
+cargo test --no-fail-fast
+```
+
+## 覆盖率目标
+
+| 代码类型 | 目标 |
+|-----------|--------|
+| 关键业务逻辑 | 100% |
+| 公共 API | 90%+ |
+| 通用代码 | 80%+ |
+| 生成的 / FFI 绑定 | 排除 |
+
+## TDD 最佳实践
+
+**应做：**
+
+* **首先**编写测试，在任何实现之前
+* 每次更改后运行测试
+* 使用 `assert_eq!` 而非 `assert!` 以获得更好的错误信息
+* 在返回 `Result` 的测试中使用 `?` 以获得更清晰的输出
+* 测试行为，而非实现
+* 包含边界情况（空值、边界值、错误路径）
+
+**不应做：**
+
+* 在测试之前编写实现
+* 跳过 RED 阶段
+* 在 `Result::is_err()` 可用时使用 `#[should_panic]`
+* 在测试中使用 `sleep()` — 应使用通道或 `tokio::time::pause()`
+* 模拟一切 — 在可行时优先使用集成测试
+
+## 相关命令
+
+* `/rust-build` - 修复构建错误
+* `/rust-review` - 在实现后审查代码
+* `/verify` - 运行完整的验证循环
+
+## 相关
+
+* 技能：`skills/rust-testing/`
+* 技能：`skills/rust-patterns/`