svharness 0.8.0 → 0.13.2

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

@@ -0,0 +1,149 @@
+---
+name: harness-modern-cpp
+description: Modern C++ (C++17/20) 最佳实践。覆盖智能指针、std::optional/span/variant、结构化绑定、constexpr 与范围算法。
+---
+
+# Modern C++ 最佳实践
+
+## 概述
+
+优先使用 C++17/20 特性替代旧式 C 风格代码，提升代码安全性与可读性。
+
+> **刚性约束已由 rules 加载：**
+> - `seed-raii` — 禁止裸 new/delete，必须使用 RAII
+
+---
+
+## 智能指针
+
+```cpp
+// 唯一所有权 — std::unique_ptr
+auto sensor = std::make_unique<TemperatureSensor>(args...);
+
+// 共享所有权 — std::shared_ptr（谨慎使用，只在真正需要时）
+auto config = std::make_shared<Configuration>(path);
+
+// 观察者 — 裸指针/引用（非拥有）
+void process(const ISensor* sensor) {
+    if (sensor != nullptr) {
+        auto data = sensor->read();
+    }
+}
+```
+
+## std::optional
+
+```cpp
+// 可能无返回值的函数
+std::optional<double> parseValue(const std::string& input) {
+    try {
+        return std::stod(input);
+    } catch (...) {
+        return std::nullopt; // 失败时不抛异常
+    }
+}
+
+// 使用
+auto result = parseValue("3.14");
+if (result.has_value()) {
+    use(result.value());
+}
+
+// 或使用 value_or 提供默认值
+double v = parseValue(text).value_or(0.0);
+```
+
+## std::span — 连续内存视图
+
+```cpp
+// 替代 (T* data, size_t len) 参数对
+double computeAverage(std::span<const double> values) {
+    double sum = 0.0;
+    for (double v : values) {
+        sum += v;
+    }
+    return sum / static_cast<double>(values.size());
+}
+
+// 可传入 vector 或数组
+std::vector<double> vec = {1.0, 2.0, 3.0};
+double avg = computeAverage(vec);
+
+double arr[] = {4.0, 5.0, 6.0};
+avg = computeAverage(arr);
+```
+
+## std::variant — 类型安全联合体
+
+```cpp
+// 替代裸 union
+using Command = std::variant<StartCmd, StopCmd, ConfigCmd, ErrorCmd>;
+
+void handleCommand(const Command& cmd) {
+    std::visit([](const auto& c) {
+        // 编译器确保所有类型都被处理
+        c.execute();
+    }, cmd);
+}
+```
+
+## 结构化绑定
+
+```cpp
+// 从 pair 解包
+std::map<std::string, int> counts;
+for (const auto& [key, value] : counts) {
+    // ...
+}
+
+// 从自定义类型解包
+struct Point { double x, y, z; };
+Point p{1.0, 2.0, 3.0};
+auto [x, y, z] = p;
+```
+
+## constexpr
+
+```cpp
+// 编译期计算
+constexpr uint32_t crc32TableEntry(uint8_t index) {
+    uint32_t crc = index;
+    for (int i = 0; i < 8; ++i) {
+        crc = (crc & 1) ? (crc >> 1) ^ 0xEDB88320 : (crc >> 1);
+    }
+    return crc;
+}
+
+constexpr auto CRC_TABLE = []() {
+    std::array<uint32_t, 256> table{};
+    for (size_t i = 0; i < 256; ++i) {
+        table[i] = crc32TableEntry(static_cast<uint8_t>(i));
+    }
+    return table;
+}();
+```
+
+## 范围算法 (C++20)
+
+```cpp
+#include <ranges>
+#include <algorithm>
+
+std::vector<int> data = {4, 2, 3, 1, 5, 2, 6};
+
+// 链式操作
+auto result = data
+    | std::views::filter([](int n) { return n > 2; })
+    | std::views::transform([](int n) { return n * n; })
+    | std::views::take(3);
+
+// 输出: 16, 9, 25
+for (int v : result) { /* ... */ }
+```
+
+---
+
+## 相关规则
+
+- `seed-raii` — RAII 与智能指针
+- `seed-header-guards` — 头文件保护符

package/templates/python/skeleton/agent-env/skills/harness-async-patterns/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: harness-async-patterns
+description: Python 异步编程模式。覆盖 asyncio 核心用法、协程管理、并发限流与错误处理。
+---
+
+# 异步编程模式
+
+## 概述
+
+使用 `asyncio` 实现高并发 I/O 操作。遵循结构化并发原则，避免回调地狱。
+
+---
+
+## 基础模式
+
+### 协程定义与调用
+
+```python
+import asyncio
+
+async def fetch_data(url: str) -> dict:
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(url)
+        resp.raise_for_status()
+        return resp.json()
+
+# 入口点
+async def main() -> None:
+    data = await fetch_data("https://api.example.com/data")
+    print(data)
+
+asyncio.run(main())
+```
+
+### 并发执行
+
+```python
+async def main() -> None:
+    # 并发运行多个协程
+    async with asyncio.TaskGroup() as tg:
+        task1 = tg.create_task(fetch_data("/api/users"))
+        task2 = tg.create_task(fetch_data("/api/posts"))
+        task3 = tg.create_task(fetch_data("/api/comments"))
+
+    results = [task1.result(), task2.result(), task3.result()]
+```
+
+## 并发限流
+
+```python
+import asyncio
+from asyncio import Semaphore
+
+class RateLimiter:
+    """并发限流器。"""
+
+    def __init__(self, max_concurrent: int) -> None:
+        self._semaphore = Semaphore(max_concurrent)
+
+    async def execute[T](self, coro: asyncio.Task[T]) -> T:
+        async with self._semaphore:
+            return await coro
+
+# 使用
+async def batch_process(items: list[str]) -> list[dict]:
+    limiter = RateLimiter(max_concurrent=10)
+
+    async with asyncio.TaskGroup() as tg:
+        tasks = [
+            tg.create_task(limiter.execute(process_item(item)))
+            for item in items
+        ]
+
+    return [t.result() for t in tasks]
+```
+
+## 超时处理
+
+```python
+async def fetch_with_timeout(url: str, timeout: float = 5.0) -> dict | None:
+    try:
+        async with asyncio.timeout(timeout):
+            return await fetch_data(url)
+    except asyncio.TimeoutError:
+        logger.warning("Request to %s timed out after %ss", url, timeout)
+        return None
+```
+
+## 生产者-消费者模式
+
+```python
+import asyncio
+from asyncio import Queue
+
+async def producer(queue: Queue[int]) -> None:
+    for i in range(100):
+        await queue.put(i)
+        await asyncio.sleep(0.01)
+
+async def consumer(name: str, queue: Queue[int]) -> None:
+    while True:
+        item = await queue.get()
+        try:
+            print(f"{name} processing {item}")
+            await asyncio.sleep(0.1)  # 模拟处理
+        finally:
+            queue.task_done()
+
+async def main() -> None:
+    queue: Queue[int] = asyncio.Queue(maxsize=20)
+
+    async with asyncio.TaskGroup() as tg:
+        tg.create_task(producer(queue))
+        for i in range(3):
+            tg.create_task(consumer(f"worker-{i}", queue))
+
+    await queue.join()  # 等待所有任务完成
+```
+
+## 异步上下文管理器
+
+```python
+import asyncio
+from typing import Self
+
+class AsyncDBConnection:
+    async def __aenter__(self) -> Self:
+        self.conn = await create_connection()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object,
+    ) -> None:
+        await self.conn.close()
+
+    async def query(self, sql: str) -> list[dict]:
+        return await self.conn.execute(sql)
+
+# 使用
+async with AsyncDBConnection() as db:
+    results = await db.query("SELECT * FROM users")
+```
+
+## 常见陷阱
+
+| 陷阱 | 说明 | 解决方案 |
+|------|------|---------|
+| **阻塞调用阻塞事件循环** | 在协程中调用 `time.sleep()` 等同步阻塞 | 使用 `asyncio.to_thread()` 或 `loop.run_in_executor()` |
+| **忘记 await** | 协程不会自动执行 | 始终 `await` 或 `create_task` |
+| **没有超时** | 协程可能永远挂起 | 始终设置 `asyncio.timeout` |
+| **TaskGroup 优于 gather** | `gather(return_exceptions=True)` 容易遗漏异常 | 优先使用 `TaskGroup` |
+| **共享可变状态** | 协程间数据竞争 | 使用 `Queue` 或不可变数据结构 |
+
+---
+
+## 相关规则
+
+- `seed-type-annotations` — 类型注解
+- `seed-context-managers` — 上下文管理器

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

@@ -0,0 +1,160 @@
+---
+name: harness-python-architecture
+description: Python 项目架构与模块化设计。覆盖分层职责、依赖管理、配置分离与项目结构。
+---
+
+# Python 架构设计指引
+
+## 概述
+
+采用分层模块化架构，保持低耦合高内聚。明确接口边界，避免循环依赖。
+
+> **刚性约束已由 rules 加载：**
+> - `seed-import-order` — 导入顺序规范
+> - `seed-pep8-naming` — PEP 8 命名规范
+> - `seed-type-annotations` — 类型注解
+
+---
+
+## 项目结构
+
+```
+project/
+├── src/
+│   ├── core/                  # 核心抽象与接口
+│   │   ├── interfaces/        # 抽象基类 / Protocol
+│   │   ├── models/            # 数据模型
+│   │   └── errors/            # 自定义异常
+│   ├── services/              # 业务服务层
+│   │   ├── service_a/
+│   │   └── service_b/
+│   ├── repositories/          # 数据访问层
+│   ├── api/                   # HTTP API 层
+│   │   ├── routes/
+│   │   ├── middleware/
+│   │   └── dependencies/
+│   ├── config/                # 配置管理
+│   ├── utils/                 # 工具函数
+│   └── main.py                # 应用入口
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── conftest.py
+├── scripts/                   # 脚本工具
+├── pyproject.toml             # 项目元数据与依赖
+├── requirements.txt
+└── README.md
+```
+
+## 分层依赖规则
+
+```
+API Layer（路由入口）
+  │ 依赖 Service 层
+  ▼
+Service Layer（业务逻辑）
+  │ 依赖 Repository 层、Core 接口
+  ▼
+Repository Layer（数据访问）
+  │ 依赖 Core 模型
+  ▼
+Core Layer（核心抽象）
+  │ 零依赖或仅依赖标准库
+```
+
+| 层级 | 职责 | 可依赖 |
+|------|------|--------|
+| **API** | 请求处理、参数校验、响应序列化 | Service |
+| **Service** | 业务编排、事务管理、事件发布 | Repository、Core |
+| **Repository** | 数据存取（DB/API/文件） | Core |
+| **Core** | 纯数据模型、接口协议、异常定义 | 标准库 |
+
+## 依赖注入
+
+```python
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+# Core 接口
+class UserRepository(ABC):
+    @abstractmethod
+    async def find_by_id(self, user_id: str) -> User | None:
+        ...
+
+# Service 通过构造器注入依赖
+class UserService:
+    def __init__(self, repo: UserRepository) -> None:
+        self._repo = repo
+
+    async def get_user(self, user_id: str) -> UserDTO | None:
+        user = await self._repo.find_by_id(user_id)
+        if user is None:
+            return None
+        return UserDTO.from_domain(user)
+
+# 组装（依赖注入入口）
+def wire_dependencies() -> UserService:
+    repo = PostgresUserRepository(dsn=settings.DATABASE_URL)
+    return UserService(repo=repo)
+```
+
+## 配置管理
+
+```python
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    # 应用配置
+    APP_NAME: str = "my-service"
+    DEBUG: bool = False
+
+    # 数据库
+    DATABASE_URL: str
+    DB_POOL_SIZE: int = 10
+
+    # 外部服务
+    REDIS_URL: str = "redis://localhost:6379"
+    API_TIMEOUT_SECONDS: float = 30.0
+
+    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
+
+# 全局单例（线程安全，不可变）
+settings = Settings()
+```
+
+## 错误处理
+
+```python
+class AppError(Exception):
+    """应用基础异常。"""
+    def __init__(self, message: str, code: str) -> None:
+        self.message = message
+        self.code = code
+        super().__init__(message)
+
+class NotFoundError(AppError):
+    def __init__(self, entity: str, entity_id: str) -> None:
+        super().__init__(
+            message=f"{entity} not found: {entity_id}",
+            code="NOT_FOUND",
+        )
+
+class ValidationError(AppError):
+    def __init__(self, field: str, reason: str) -> None:
+        super().__init__(
+            message=f"Validation failed for {field}: {reason}",
+            code="VALIDATION_ERROR",
+        )
+
+# 统一错误处理
+def handle_error(error: AppError) -> dict[str, str]:
+    return {"error": error.code, "message": error.message}
+```
+
+---
+
+## 相关规则
+
+- `seed-import-order` — 导入顺序规范
+- `seed-pep8-naming` — PEP 8 命名规范
+- `seed-type-annotations` — 类型注解

package/templates/python/skeleton/agent-env/skills/harness-python-package-structure/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: harness-python-package-structure
+description: Python 包与模块组织管理。覆盖包结构、__init__.py 规范、依赖管理与发布配置。
+---
+
+# 包与模块组织
+
+## 概述
+
+规范的包结构是 Python 项目的基石。遵循标准约定，确保可导入性、可测试性与可分发性。
+
+> **相关规则：**
+> - `seed-import-order` — 导入顺序规范
+> - `seed-pep8-naming` — PEP 8 命名规范
+
+---
+
+## 包结构
+
+```
+my_package/
+├── __init__.py               # 包入口，导出公共 API
+├── _internal/                # 内部实现，不导出
+│   ├── __init__.py
+│   ├── _helpers.py
+│   └── _constants.py
+├── models/                   # 数据模型
+│   ├── __init__.py
+│   ├── user.py
+│   └── order.py
+├── services/                 # 业务服务
+│   ├── __init__.py
+│   ├── user_service.py
+│   └── payment_service.py
+├── cli.py                    # 命令行入口（可选）
+└── __version__.py            # 版本信息
+```
+
+## __init__.py 规范
+
+```python
+# my_package/__init__.py
+"""My Package - 简短描述包的目的。
+
+这个包提供了用户管理与支付处理功能。
+"""
+
+from my_package.models.user import User, UserRole
+from my_package.models.order import Order, OrderStatus
+from my_package.services.user_service import UserService
+from my_package.services.payment_service import PaymentService
+
+__all__ = [
+    "User",
+    "UserRole",
+    "Order",
+    "OrderStatus",
+    "UserService",
+    "PaymentService",
+]
+```
+
+## pyproject.toml 配置
+
+```toml
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.backends._legacy:_Backend"
+
+[project]
+name = "my-package"
+version = "0.1.0"
+description = "A short description"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Developer", email = "dev@example.com" },
+]
+
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "ruff>=0.3",
+    "mypy>=1.8",
+]
+test = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/example/my-package"
+
+[project.scripts]
+my-cli = "my_package.cli:main"
+```
+
+## 模块组织原则
+
+### 1. 单一职责
+
+```python
+# 正确：职责分离
+# services/user_service.py
+class UserService:
+    """仅处理用户相关的业务逻辑。"""
+
+    async def create_user(self, data: CreateUserDTO) -> User:
+        ...
+
+    async def deactivate_user(self, user_id: str) -> None:
+        ...
+
+# services/notification_service.py
+class NotificationService:
+    """仅处理通知发送。"""
+    ...
+```
+
+### 2. 显式 re-export
+
+```python
+# services/__init__.py
+from my_package.services.user_service import UserService
+from my_package.services.payment_service import PaymentService
+
+__all__ = ["UserService", "PaymentService"]
+```
+
+### 3. 内部实现隐藏
+
+```python
+# _internal/_helpers.py
+# 单下划线前缀表示内部实现，不视为公共 API
+def _format_currency(amount: float, currency: str) -> str:
+    ...
+```
+
+## 依赖管理
+
+```txt
+# requirements.txt — 锁定版本部署
+httpx==0.27.0
+pydantic==2.5.0
+python-dotenv==1.0.1
+uvicorn[standard]==0.27.0
+
+# requirements-dev.txt — 开发依赖
+-r requirements.txt
+pytest==8.0.0
+pytest-cov==5.0.0
+ruff==0.3.0
+mypy==1.8.0
+pre-commit==3.6.0
+```
+
+或使用 Poetry:
+
+```toml
+[tool.poetry]
+name = "my-package"
+version = "0.1.0"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+httpx = "^0.27"
+pydantic = "^2.5"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+ruff = "^0.3"
+mypy = "^1.8"
+```
+
+## 命令行入口
+
+```python
+# cli.py
+import argparse
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description="My CLI Tool")
+    parser.add_argument("--verbose", "-v", action="store_true")
+    args = parser.parse_args(argv)
+
+    if args.verbose:
+        print("Verbose mode enabled")
+    print("Running my CLI...")
+
+if __name__ == "__main__":
+    main()
+```
+
+---
+
+## 相关规则
+
+- `seed-import-order` — 导入顺序规范
+- `seed-pep8-naming` — PEP 8 命名规范
+- `seed-type-annotations` — 类型注解