svharness 0.8.0 → 0.13.2

package/templates/cpp/skeleton/agent-env/skills/harness-cmake-build/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: harness-cmake-build
+description: CMake 构建系统配置与管理。覆盖目标定义、依赖管理、测试配置、安装规则与跨平台构建。
+---
+
+# CMake 构建系统
+
+## 概述
+
+使用 CMake 作为跨平台构建系统。遵循现代 CMake 最佳实践（目标驱动、IMPORTED 接口、别名命名）。
+
+> **刚性约束已由 rules 加载：**
+> - `seed-cmake-explicit-sources` — CMakeLists.txt 必须显式列出源文件，禁止 glob
+
+---
+
+## 根 CMakeLists.txt
+
+```cmake
+cmake_minimum_required(VERSION 3.20)
+project(MyProject VERSION 1.0.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# 选项
+option(BUILD_TESTS "Build unit tests" ON)
+option(BUILD_EXAMPLES "Build examples" OFF)
+
+# 添加子目录
+add_subdirectory(src/core)
+add_subdirectory(src/module_a)
+
+if(BUILD_TESTS)
+    enable_testing()
+    add_subdirectory(tests)
+endif()
+```
+
+## 目标定义（现代 CMake）
+
+```cmake
+# src/core/CMakeLists.txt — Library 目标
+
+# 只使用 add_library，不设置全局 include_directories
+add_library(core
+    src/sensor_base.cpp
+    src/actuator_base.cpp
+)
+
+# 公开头文件目录（被依赖者继承）
+target_include_directories(core
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:include>
+    PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/src
+)
+
+# 链接依赖
+target_link_libraries(core
+    PUBLIC
+        # 接口依赖（传播给使用者）
+    PRIVATE
+        # 实现细节依赖
+)
+```
+
+## 可执行目标
+
+```cmake
+# src/app/CMakeLists.txt
+add_executable(my_app main.cpp)
+
+target_link_libraries(my_app
+    PRIVATE
+        core
+        module_a
+)
+```
+
+## 测试配置
+
+```cmake
+# tests/CMakeLists.txt
+find_package(GTest REQUIRED)
+
+add_executable(unit_tests
+    test_core_sensor.cpp
+    test_module_a.cpp
+)
+
+target_link_libraries(unit_tests
+    PRIVATE
+        core
+        module_a
+        GTest::gtest_main
+        GTest::gmock
+)
+
+target_compile_definitions(unit_tests PRIVATE UNIT_TEST)
+
+# 自动注册测试
+include(GoogleTest)
+gtest_discover_tests(unit_tests)
+
+add_test(NAME unit_tests COMMAND unit_tests)
+```
+
+## 安装规则
+
+```cmake
+# 安装库与头文件
+install(TARGETS core module_a
+    EXPORT MyProjectTargets
+    LIBRARY DESTINATION lib
+    ARCHIVE DESTINATION lib
+    RUNTIME DESTINATION bin
+    INCLUDES DESTINATION include
+)
+
+install(DIRECTORY include/ DESTINATION include)
+
+# 导出包（供 find_package 使用）
+install(EXPORT MyProjectTargets
+    FILE MyProjectTargets.cmake
+    NAMESPACE MyProject::
+    DESTINATION lib/cmake/MyProject
+)
+```
+
+## 跨平台
+
+```cmake
+# 编译器特定设置
+if(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
+    target_compile_options(my_target PRIVATE /W4 /WX)
+else()
+    target_compile_options(my_target PRIVATE -Wall -Wextra -Werror -Wpedantic)
+endif()
+
+# 平台检测
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+    target_link_libraries(my_target PRIVATE pthread)
+elseif(CMAKE_SYSTEM_NAME STREQUAL "Android")
+    # Android NDK 特定配置
+endif()
+
+# 显式列出源文件（禁止 GLOB）
+set(MODULE_A_SOURCES
+    src/module_a/processor.cpp
+    src/module_a/validator.cpp
+    src/module_a/utils.cpp
+)
+```
+
+---
+
+## 相关规则
+
+- `seed-cmake-explicit-sources` — 显式源文件列表
+- `seed-no-cyclic-deps` — 循环依赖检测

package/templates/cpp/skeleton/agent-env/skills/harness-cpp-architecture/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: harness-cpp-architecture
+description: C++ 项目架构与模块化设计指引。覆盖目录结构、分层职责、依赖管理、接口设计与循环依赖预防。
+---
+
+# C++ 架构设计指引
+
+## 概述
+
+本项目采用模块化分层架构。组件间通过明确接口通信，禁止循环依赖，保持低耦合高内聚。
+
+> **刚性约束已由 rules 加载，本技能不再重复。** 详见：
+> - `seed-include-layering` — include 分层顺序与可见性约束
+> - `seed-no-cyclic-deps` — 禁止模块间循环依赖
+> - `seed-header-guards` — 头文件保护符强制
+
+---
+
+## 项目结构
+
+```
+project/
+├── src/
+│   ├── core/                  # 核心抽象与接口
+│   │   ├── include/core/
+│   │   │   ├── ISensor.h
+│   │   │   └── IActuator.h
+│   │   └── CMakeLists.txt
+│   ├── module_a/              # 功能模块 A
+│   │   ├── include/module_a/
+│   │   ├── src/
+│   │   └── CMakeLists.txt
+│   ├── module_b/              # 功能模块 B
+│   │   └── ...
+│   └── app/                   # 应用入口
+│       ├── main.cpp
+│       └── CMakeLists.txt
+├── tests/
+│   ├── unit/
+│   └── integration/
+├── third_party/               # 第三方依赖
+├── CMakeLists.txt             # 根 CMake
+└── README.md
+```
+
+## 分层依赖规则
+
+```
+App（主入口）
+  │ 依赖所有模块
+  ▼
+Core（抽象接口）
+  │ 零依赖或仅依赖标准库
+  ▼
+Module A ←──→ Module B（禁止循环依赖）
+  │               │
+  ▼               ▼
+Core（接口层）
+```
+
+| 层级 | 职责 | 可依赖 |
+|------|------|--------|
+| **App** | 初始化、依赖注入、生命周期 | 所有模块 |
+| **Module** | 业务逻辑实现 | Core 接口、其他模块（单向） |
+| **Core** | 纯抽象接口、数据结构 | 标准库 |
+
+## 接口设计
+
+```cpp
+// core/include/core/ISensor.h
+#pragma once
+
+#include <memory>
+#include <optional>
+#include <vector>
+
+namespace core {
+
+struct SensorData {
+    double value;
+    uint64_t timestamp_us;
+    bool valid;
+};
+
+class ISensor {
+public:
+    virtual ~ISensor() = default;
+
+    // 纯虚接口 — 禁止定义成员变量
+    virtual std::optional<SensorData> read() = 0;
+    virtual bool configure(const std::string& key, double value) = 0;
+    virtual std::string name() const = 0;
+};
+
+// 工厂函数（非类方法）
+std::unique_ptr<ISensor> CreateTemperatureSensor();
+
+} // namespace core
+```
+
+## 依赖注入
+
+```cpp
+class TemperatureMonitor {
+public:
+    // 通过构造函数注入依赖
+    explicit TemperatureMonitor(std::unique_ptr<core::ISensor> sensor)
+        : sensor_(std::move(sensor)) {}
+
+    double getCurrentTemperature() {
+        auto data = sensor_->read();
+        return data.has_value() ? data->value : 0.0;
+    }
+
+private:
+    std::unique_ptr<core::ISensor> sensor_; // 所有权唯一
+};
+```
+
+## PIMPL 模式（隐藏实现细节）
+
+```cpp
+// public/include/module_a/Processor.h
+#pragma once
+
+#include <memory>
+
+namespace module_a {
+
+class Processor {
+public:
+    Processor();
+    ~Processor();
+
+    Processor(const Processor&) = delete;
+    Processor& operator=(const Processor&) = delete;
+    Processor(Processor&&) noexcept;
+    Processor& operator=(Processor&&) noexcept;
+
+    void process();
+    void setConfig(const std::string& config);
+
+private:
+    class Impl;
+    std::unique_ptr<Impl> impl_;
+};
+
+} // namespace module_a
+```
+
+---
+
+## 相关规则
+
+- `seed-include-layering` — include 分层顺序
+- `seed-no-cyclic-deps` — 循环依赖禁止
+- `seed-header-guards` — 头文件保护符

package/templates/cpp/skeleton/agent-env/skills/harness-cpp-concurrency/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: harness-cpp-concurrency
+description: C++ 并发与线程安全模式。覆盖 std::thread、互斥锁、条件变量、std::async、线程池与无锁编程指南。
+---
+
+# C++ 并发编程
+
+## 概述
+
+正确使用 C++ 并发设施，遵循线程安全原则，避免数据竞争与死锁。
+
+> **相关规则：**
+> - `seed-raii` — RAII 管理互斥锁生命周期
+
+---
+
+## 基本线程管理
+
+```cpp
+#include <thread>
+#include <iostream>
+
+void worker(int id) {
+    std::cout << "Worker " << id << " started\n";
+}
+
+int main() {
+    std::thread t1(worker, 1);
+    std::thread t2(worker, 2);
+
+    // 等待完成
+    t1.join();
+    t2.join();
+    return 0;
+}
+```
+
+## 互斥锁（RAII 封装）
+
+```cpp
+#include <mutex>
+
+class SensorCache {
+public:
+    void update(double value) {
+        std::lock_guard<std::mutex> lock(mutex_); // 异常安全
+        cache_ = value;
+        ++version_;
+    }
+
+    std::pair<double, uint64_t> read() const {
+        std::lock_guard<std::mutex> lock(mutex_);
+        return {cache_, version_};
+    }
+
+private:
+    mutable std::mutex mutex_; // mutable 允许 const 方法加锁
+    double cache_ = 0.0;
+    uint64_t version_ = 0;
+};
+```
+
+## 读写锁（读频繁场景）
+
+```cpp
+#include <shared_mutex>
+
+class ConfigStore {
+public:
+    std::string get(const std::string& key) const {
+        std::shared_lock lock(mutex_); // 共享读
+        auto it = map_.find(key);
+        return it != map_.end() ? it->second : "";
+    }
+
+    void set(const std::string& key, std::string value) {
+        std::unique_lock lock(mutex_); // 独占写
+        map_[key] = std::move(value);
+    }
+
+private:
+    mutable std::shared_mutex mutex_;
+    std::map<std::string, std::string> map_;
+};
+```
+
+## 条件变量
+
+```cpp
+#include <condition_variable>
+
+class MessageQueue {
+public:
+    void push(int value) {
+        {
+            std::lock_guard lock(mutex_);
+            queue_.push(value);
+        }
+        cv_.notify_one();
+    }
+
+    int pop() {
+        std::unique_lock lock(mutex_);
+        cv_.wait(lock, [this] { return !queue_.empty(); });
+        int value = queue_.front();
+        queue_.pop();
+        return value;
+    }
+
+private:
+    std::mutex mutex_;
+    std::condition_variable cv_;
+    std::queue<int> queue_;
+};
+```
+
+## std::async — 简化异步任务
+
+```cpp
+#include <future>
+
+// 异步获取传感器数据
+std::future<SensorData> async_sensor_read(ISensor& sensor) {
+    return std::async(std::launch::async, [&sensor] {
+        return sensor.read();
+    });
+}
+
+// 使用
+ISensor& sensor = getSensor();
+auto future = async_sensor_read(sensor);
+
+// 执行其他操作...
+
+// 等待结果（带超时）
+if (future.wait_for(std::chrono::milliseconds(100)) ==
+    std::future_status::ready) {
+    auto data = future.get();
+    process(data);
+}
+```
+
+## 线程安全单例
+
+```cpp
+class Logger {
+public:
+    static Logger& instance() {
+        static Logger log; // C++11 起线程安全（magic static）
+        return log;
+    }
+
+    void log(const std::string& msg) {
+        std::lock_guard lock(mutex_);
+        // 写入日志...
+    }
+
+private:
+    Logger() = default;                         // 私有构造
+    Logger(const Logger&) = delete;
+    Logger& operator=(const Logger&) = delete;
+    std::mutex mutex_;
+};
+```
+
+## 注意事项
+
+| 陷阱 | 说明 | 解决方案 |
+|------|------|---------|
+| **死锁** | 多个锁交叉顺序加锁 | 固定加锁顺序或使用 std::lock() |
+| **数据竞争** | 非原子变量的并发读写 | 使用 mutex 或 std::atomic |
+| **假唤醒** | 条件变量无故唤醒 | wait() 必须使用谓词重载 |
+| **线程泄漏** | detach 后线程未完成 | 优先使用 join，避免 detach |
+| **异常传播** | 线程内异常无法传出 | 用 std::future 或包装错误码 |
+
+---
+
+## 相关规则
+
+- `seed-raii` — RAII 管理锁生命周期

package/templates/cpp/skeleton/agent-env/skills/harness-memory-safety/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: harness-memory-safety
+description: C++ RAII 与内存安全最佳实践。覆盖智能指针使用、资源管理、异常安全、移动语义与防止内存泄漏。
+---
+
+# RAII 与内存安全
+
+## 概述
+
+RAII（Resource Acquisition Is Initialization）是 C++ 核心资源管理范式。资源在构造函数中获取，在析构函数中释放，确保异常安全与无泄漏。
+
+> **刚性约束已由 rules 加载：**
+> - `seed-raii` — 禁止裸 new/delete，禁止裸 malloc/free
+
+---
+
+## 资源管理三原则
+
+### 1. 动态内存 → 智能指针
+
+```cpp
+// 正确：智能指针
+auto buffer = std::make_unique<uint8_t[]>(1024);
+auto config = std::make_shared<Configuration>();
+
+// 错误：裸指针
+uint8_t* buf = new uint8_t[1024]; // 禁止
+delete[] buf;                      // 禁止
+```
+
+### 2. 文件 → RAII 包装
+
+```cpp
+// 正确：std::ifstream/ofstream 自动关闭
+std::ifstream file(path);
+if (!file) {
+    throw std::runtime_error("Failed to open file");
+}
+// 读取... 作用域结束自动关闭
+
+// 错误：手动配对
+FILE* f = fopen(path, "r"); // 禁止
+// ...
+fclose(f);                   // 禁止
+```
+
+### 3. 锁 → RAII 锁守卫
+
+```cpp
+// 正确：异常安全
+{
+    std::lock_guard<std::mutex> lock(mutex_);
+    shared_data_ = new_value;
+    // 自动解锁，即使异常
+}
+
+// 错误：手动 lock/unlock
+mutex_.lock();   // 禁止
+shared_data_ = new_value;
+mutex_.unlock(); // 异常时不会执行
+```
+
+## 异常安全
+
+```cpp
+// 强异常安全保证：要么完全成功，要么回滚
+class Account {
+public:
+    void transfer(Account& other, double amount) {
+        // 先复制
+        Account temp(*this);
+        temp.balance_ -= amount;
+        other.balance_ += amount;
+
+        // 全部成功后原子交换
+        std::swap(*this, temp); // noexcept
+    }
+
+private:
+    double balance_ = 0.0;
+};
+```
+
+## 移动语义
+
+```cpp
+// 移动构造函数与移动赋值
+class Buffer {
+public:
+    Buffer() : data_(nullptr), size_(0) {}
+
+    // 移动构造
+    Buffer(Buffer&& other) noexcept
+        : data_(std::exchange(other.data_, nullptr))
+        , size_(std::exchange(other.size_, 0)) {}
+
+    // 移动赋值
+    Buffer& operator=(Buffer&& other) noexcept {
+        if (this != &other) {
+            delete[] data_;
+            data_ = std::exchange(other.data_, nullptr);
+            size_ = std::exchange(other.size_, 0);
+        }
+        return *this;
+    }
+
+    ~Buffer() {
+        delete[] data_;
+    }
+
+    // 禁止拷贝（资源唯一所有权）
+    Buffer(const Buffer&) = delete;
+    Buffer& operator=(const Buffer&) = delete;
+
+private:
+    uint8_t* data_;
+    size_t size_;
+};
+```
+
+## 自定义 RAII 包装
+
+```cpp
+// 通用 RAII 包装（任何需要释放的资源）
+template <typename T, auto Deleter>
+class ScopedResource {
+public:
+    explicit ScopedResource(T resource) : resource_(resource) {}
+
+    ~ScopedResource() {
+        if (resource_) {
+            Deleter(resource_);
+        }
+    }
+
+    ScopedResource(const ScopedResource&) = delete;
+    ScopedResource& operator=(const ScopedResource&) = delete;
+
+    T get() const { return resource_; }
+
+private:
+    T resource_;
+};
+
+// 使用：包装 C API 句柄
+// auto fd = ScopedResource<int, close>(open(path, O_RDONLY));
+```
+
+## 内存泄漏预防清单
+
+- [ ] 所有 `new` 配对 `delete`（或使用智能指针）
+- [ ] 基类析构函数声明为 `virtual` 或 `protected`
+- [ ] 资源管理类遵守 **三五法则**（Rule of Three/Five）
+- [ ] 容器使用 `std::vector` / `std::array` 而非裸数组
+- [ ] 字符串使用 `std::string` 而非 `char*`
+- [ ] 跨 DLL 边界传递使用 `std::shared_ptr`（小心 ABI）
+
+---
+
+## 相关规则
+
+- `seed-raii` — RAII 与内存安全强制
+- `seed-header-guards` — 头文件保护符