@pzy560117/codex-harness 0.1.4 → 0.1.5

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

@@ -0,0 +1,140 @@
+---
+description: 全面的 C++ 代码审查，涵盖内存安全、现代 C++ 惯用法、并发性和安全性。调用 cpp-reviewer 代理。
+---
+
+# C++ 代码审查
+
+此命令调用 **cpp-reviewer** 代理进行全面的 C++ 特定代码审查。
+
+## 此命令的作用
+
+1. **识别 C++ 变更**：通过 `git diff` 查找已修改的 `.cpp`、`.hpp`、`.cc`、`.h` 文件
+2. **运行静态分析**：执行 `clang-tidy` 和 `cppcheck`
+3. **内存安全检查**：检查原始 new/delete、缓冲区溢出、释放后使用
+4. **并发审查**：分析线程安全性、互斥锁使用情况、数据竞争
+5. **现代 C++ 检查**：验证代码是否遵循 C++17/20 约定和最佳实践
+6. **生成报告**：按严重程度对问题进行分类
+
+## 使用时机
+
+在以下情况下使用 `/cpp-review`：
+
+* 编写或修改 C++ 代码后
+* 提交 C++ 变更前
+* 审查包含 C++ 代码的拉取请求时
+* 接手新的 C++ 代码库时
+* 检查内存安全问题
+
+## 审查类别
+
+### 严重（必须修复）
+
+* 未使用 RAII 的原始 `new`/`delete`
+* 缓冲区溢出和释放后使用
+* 无同步的数据竞争
+* 通过 `system()` 进行命令注入
+* 未初始化的变量读取
+* 空指针解引用
+
+### 高（应该修复）
+
+* 五法则违规
+* 缺少 `std::lock_guard` / `std::scoped_lock`
+* 分离的线程没有正确的生命周期管理
+* 使用 C 风格强制转换而非 `static_cast`/`dynamic_cast`
+* 缺少 `const` 正确性
+
+### 中（考虑）
+
+* 不必要的拷贝（按值传递而非 `const&`）
+* 已知大小的容器上缺少 `reserve()`
+* 头文件中的 `using namespace std;`
+* 重要返回值上缺少 `[[nodiscard]]`
+* 过于复杂的模板元编程
+
+## 运行的自动化检查
+
+```bash
+# Static analysis
+clang-tidy --checks='*,-llvmlibc-*' src/*.cpp -- -std=c++17
+
+# Additional analysis
+cppcheck --enable=all --suppress=missingIncludeSystem src/
+
+# Build with warnings
+cmake --build build -- -Wall -Wextra -Wpedantic
+```
+
+## 使用示例
+
+````text
+# C++ 代码审查报告
+
+## 已审查文件
+- src/handler/user.cpp (已修改)
+- src/service/auth.cpp (已修改)
+
+## 静态分析结果
+✓ clang-tidy: 2 个警告
+✓ cppcheck: 无问题
+
+## 发现的问题
+
+[严重] 内存泄漏
+文件: src/service/auth.cpp:45
+问题: 使用了原始的 `new` 而没有匹配的 `delete`
+```cpp
+auto* session = new Session(userId);  // 内存泄漏！
+cache[userId] = session;
+````
+
+修复：使用 `std::unique_ptr`
+
+```cpp
+auto session = std::make_unique<Session>(userId);
+cache[userId] = std::move(session);
+```
+
+\[高] 缺少常量引用
+文件：src/handler/user.cpp:28
+问题：大对象按值传递
+
+```cpp
+void processUser(User user) {  // Unnecessary copy
+```
+
+修复：通过常量引用传递
+
+```cpp
+void processUser(const User& user) {
+```
+
+## 摘要
+
+* 严重：1
+* 高：1
+* 中：0
+
+建议：FAIL: 在严重问题修复前阻止合并
+
+```
+## 批准标准
+
+| 状态 | 条件 |
+|--------|-----------|
+| PASS: 批准 | 没有 CRITICAL 或 HIGH 级别的问题 |
+| WARNING: 警告 | 仅有 MEDIUM 级别的问题（谨慎合并） |
+| FAIL: 阻止 | 发现 CRITICAL 或 HIGH 级别的问题 |
+
+## 与其他命令的集成
+
+- 首先使用 `/cpp-test` 确保测试通过
+- 如果出现构建错误，请使用 `/cpp-build`
+- 在提交前使用 `/cpp-review`
+- 对于非 C++ 特定的问题，请使用 `/code-review`
+
+## 相关
+
+- 代理：`agents/cpp-reviewer.md`
+- 技能：`skills/cpp-coding-standards/`, `skills/cpp-testing/`
+```

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

@@ -0,0 +1,257 @@
+---
+description: 为 C++ 强制执行 TDD 工作流程。先编写 GoogleTest 测试，然后实现。使用 gcov/lcov 验证覆盖率。
+---
+
+# C++ TDD 命令
+
+此命令使用 GoogleTest/GoogleMock 与 CMake/CTest，为 C++ 代码强制执行测试驱动开发方法。
+
+## 此命令的作用
+
+1. **定义接口**：首先搭建类/函数签名
+2. **编写测试**：创建全面的 GoogleTest 测试用例（RED 阶段）
+3. **运行测试**：验证测试因正确原因失败
+4. **实现代码**：编写最少代码以通过测试（GREEN 阶段）
+5. **重构**：在保持测试通过的同时改进代码
+6. **检查覆盖率**：确保覆盖率在 80% 以上
+
+## 何时使用
+
+在以下情况使用 `/cpp-test`：
+
+* 实现新的 C++ 函数或类时
+* 为现有代码增加测试覆盖率时
+* 修复错误时（先编写失败的测试）
+* 构建关键业务逻辑时
+* 学习 C++ 中的 TDD 工作流时
+
+## TDD 循环
+
+```
+RED     → 编写失败的 GoogleTest 测试
+GREEN   → 实现最小化代码以通过测试
+REFACTOR → 改进代码，测试保持通过
+REPEAT  → 下一个测试用例
+```
+
+## 示例会话
+
+````
+User: /cpp-test I need a function to validate email addresses
+
+Agent:
+# TDD Session: Email Validator
+
+## Step 1: Define Interface
+
+```cpp
+// validator/email.hpp
+#pragma once
+#include <string>
+#include <expected>
+
+enum class EmailError {
+    Empty,
+    InvalidFormat
+};
+
+std::expected<void, EmailError> validate_email(const std::string& email);
+```
+
+## Step 2: Write Tests (RED)
+
+```cpp
+// validator/email_test.cpp
+#include <gtest/gtest.h>
+#include "email.hpp"
+
+TEST(ValidateEmail, AcceptsSimpleEmail) {
+    auto result = validate_email("user@example.com");
+    EXPECT_TRUE(result.has_value());
+}
+
+TEST(ValidateEmail, AcceptsSubdomain) {
+    EXPECT_TRUE(validate_email("user@mail.example.com").has_value());
+}
+
+TEST(ValidateEmail, AcceptsPlus) {
+    EXPECT_TRUE(validate_email("user+tag@example.com").has_value());
+}
+
+TEST(ValidateEmail, RejectsEmpty) {
+    auto result = validate_email("");
+    ASSERT_FALSE(result.has_value());
+    EXPECT_EQ(result.error(), EmailError::Empty);
+}
+
+TEST(ValidateEmail, RejectsNoAtSign) {
+    EXPECT_FALSE(validate_email("userexample.com").has_value());
+}
+
+TEST(ValidateEmail, RejectsNoDomain) {
+    EXPECT_FALSE(validate_email("user@").has_value());
+}
+
+TEST(ValidateEmail, RejectsNoLocalPart) {
+    EXPECT_FALSE(validate_email("@example.com").has_value());
+}
+```
+
+## Step 3: Run Tests - Verify FAIL
+
+```bash
+$ cmake --build build && ctest --test-dir build --output-on-failure
+
+1/1 Test #1: email_validator_test .....***Failed
+    --- undefined reference to `validate_email`
+
+FAIL
+```
+
+✓ Tests fail as expected (unimplemented).
+
+## Step 4: Implement Minimal Code (GREEN)
+
+```cpp
+// validator/email.cpp
+#include "email.hpp"
+#include <regex>
+
+std::expected<void, EmailError> validate_email(const std::string& email) {
+    if (email.empty()) {
+        return std::unexpected(EmailError::Empty);
+    }
+    static const std::regex pattern(R"([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})");
+    if (!std::regex_match(email, pattern)) {
+        return std::unexpected(EmailError::InvalidFormat);
+    }
+    return {};
+}
+```
+
+## Step 5: Run Tests - Verify PASS
+
+```bash
+$ cmake --build build && ctest --test-dir build --output-on-failure
+
+1/1 Test #1: email_validator_test .....   Passed    0.01 sec
+
+100% tests passed.
+```
+
+✓ All tests passing!
+
+## Step 6: Check Coverage
+
+```bash
+$ cmake -DCMAKE_CXX_FLAGS="--coverage" -B build && cmake --build build
+$ ctest --test-dir build
+$ lcov --capture --directory build --output-file coverage.info
+$ lcov --list coverage.info
+
+validator/email.cpp     | 100%
+```
+
+✓ Coverage: 100%
+
+## TDD Complete!
+````
+
+## 测试模式
+
+### 基础测试
+
+```cpp
+TEST(SuiteName, TestName) {
+    EXPECT_EQ(add(2, 3), 5);
+    EXPECT_NE(result, nullptr);
+    EXPECT_TRUE(is_valid);
+    EXPECT_THROW(func(), std::invalid_argument);
+}
+```
+
+### 测试夹具
+
+```cpp
+class DatabaseTest : public ::testing::Test {
+protected:
+    void SetUp() override { db_ = create_test_db(); }
+    void TearDown() override { db_.reset(); }
+    std::unique_ptr<Database> db_;
+};
+
+TEST_F(DatabaseTest, InsertsRecord) {
+    db_->insert("key", "value");
+    EXPECT_EQ(db_->get("key"), "value");
+}
+```
+
+### 参数化测试
+
+```cpp
+class PrimeTest : public ::testing::TestWithParam<std::pair<int, bool>> {};
+
+TEST_P(PrimeTest, ChecksPrimality) {
+    auto [input, expected] = GetParam();
+    EXPECT_EQ(is_prime(input), expected);
+}
+
+INSTANTIATE_TEST_SUITE_P(Primes, PrimeTest, ::testing::Values(
+    std::make_pair(2, true),
+    std::make_pair(4, false),
+    std::make_pair(7, true)
+));
+```
+
+## 覆盖率命令
+
+```bash
+# Build with coverage
+cmake -DCMAKE_CXX_FLAGS="--coverage" -DCMAKE_EXE_LINKER_FLAGS="--coverage" -B build
+
+# Run tests
+cmake --build build && ctest --test-dir build
+
+# Generate coverage report
+lcov --capture --directory build --output-file coverage.info
+lcov --remove coverage.info '/usr/*' --output-file coverage.info
+genhtml coverage.info --output-directory coverage_html
+```
+
+## 覆盖率目标
+
+| 代码类型 | 目标 |
+|-----------|--------|
+| 关键业务逻辑 | 100% |
+| 公共 API | 90%+ |
+| 通用代码 | 80%+ |
+| 生成的代码 | 排除 |
+
+## TDD 最佳实践
+
+**应做：**
+
+* 先编写测试，再进行任何实现
+* 每次更改后运行测试
+* 在适当时使用 `EXPECT_*`（继续）而非 `ASSERT_*`（停止）
+* 测试行为，而非实现细节
+* 包含边界情况（空值、null、最大值、边界条件）
+
+**不应做：**
+
+* 在编写测试之前实现代码
+* 跳过 RED 阶段
+* 直接测试私有方法（通过公共 API 进行测试）
+* 在测试中使用 `sleep`
+* 忽略不稳定的测试
+
+## 相关命令
+
+* `/cpp-build` - 修复构建错误
+* `/cpp-review` - 在实现后审查代码
+* `/verify` - 运行完整的验证循环
+
+## 相关
+
+* 技能：`skills/cpp-testing/`
+* 技能：`skills/tdd-workflow/`

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

@@ -0,0 +1,32 @@
+---
+description: 通过 Context7 查找库或主题的当前文档。
+---
+
+# /docs
+
+## 目的
+
+查找库、框架或 API 的最新文档，并返回包含相关代码片段的摘要答案。使用 Context7 MCP（resolve-library-id 和 query-docs），因此答案反映的是当前文档，而非训练数据。
+
+## 用法
+
+```
+/docs [library name] [question]
+```
+
+对于多单词参数，使用引号以便它们被解析为单个标记。示例：`/docs "Next.js" "How do I configure middleware?"`
+
+如果省略了库或问题，则提示用户输入：
+
+1. 库或产品名称（例如 Next.js、Prisma、Supabase）。
+2. 具体问题或任务（例如“如何设置中间件？”、“认证方法”）。
+
+## 工作流程
+
+1. **解析库 ID** — 调用 Context7 工具 `resolve-library-id`，传入库名称和用户问题，以获取 Context7 兼容的库 ID（例如 `/vercel/next.js`）。
+2. **查询文档** — 使用该库 ID 和用户问题调用 `query-docs`。
+3. **总结** — 返回简洁的答案，并包含从获取的文档中提取的相关代码示例。提及库（如果相关，包括版本）。
+
+## 输出
+
+用户收到一个简短、准确的答案，该答案基于当前文档，并附带任何有帮助的代码片段。如果 Context7 不可用，则说明情况，并根据训练数据回答问题，并注明文档可能已过时。