svharness 0.8.0

package/templates/cpp/skeleton/agent-env/rules/seed-header-guards.md

@@ -0,0 +1,34 @@
+# 头文件守卫（种子规则）
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+所有 `.h` / `.hpp` 文件必须使用 `#pragma once`（或等价的 `#ifndef` 守卫）。
+禁止在头文件中放 `using namespace std;` 或非内联的函数定义。
+
+## 正例
+
+```cpp
+// wireless/wireless_controller.h
+#pragma once
+#include <cstdint>
+
+namespace dsv::wireless {
+class WirelessController { /* ... */ };
+}
+```
+
+## 反例
+
+```cpp
+// ❌ 头文件污染命名空间
+using namespace std;
+// ❌ 头文件包含非 inline 的函数体
+int Add(int a, int b) { return a + b; }
+```
+
+## 如何检测
+
+- 每个头文件首 5 行必须出现 `#pragma once` 或 `#ifndef ... #define`。
+- 头文件中 grep `^using namespace` 命中即违规。

package/templates/cpp/skeleton/agent-env/rules/seed-include-layering.md

@@ -0,0 +1,39 @@
+# include 分层顺序（种子规则）
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+每个 `.cpp` 的 include 顺序：
+**自身配套头 → 本模块头 → 项目其它模块头 → 三方库 → C++ 标准库 → C 标准库**。
+每组之间一个空行。
+
+## 正例
+
+```cpp
+// wireless_controller.cpp
+#include "wireless/wireless_controller.h"   // 自身头
+
+#include "wireless/wireless_parser.h"       // 本模块
+
+#include "common/logger.h"                  // 其它模块
+
+#include <spdlog/spdlog.h>                  // 三方
+
+#include <memory>                           // 标准库
+#include <vector>
+```
+
+## 反例
+
+```cpp
+// ❌ 顺序乱，三方夹在自家中间
+#include <spdlog/spdlog.h>
+#include "wireless/wireless_controller.h"
+#include <memory>
+#include "common/logger.h"
+```
+
+## 如何检测
+
+- clang-format 的 `IncludeCategories` 自动检查；PR 评审拒绝乱序。

package/templates/cpp/skeleton/agent-env/rules/seed-no-cyclic-deps.md

@@ -0,0 +1,29 @@
+# 禁止模块循环依赖（种子规则）
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+每个模块目录是一个 CMake target；模块间只能**单向依赖**。
+出现循环立即视为 bug —— 通过**下沉公共抽象**或**上浮接口**解决。
+
+## 正例
+
+```
+core → (no deps)
+common → core
+wireless → common, core
+ui → wireless, common, core
+```
+
+## 反例
+
+```
+wireless → ui → wireless     ❌
+common → wireless → common   ❌
+```
+
+## 如何检测
+
+- `cmake --graphviz=deps.dot ..` 生成依赖图，人工/脚本检测环。
+- PR 评审：新增 `target_link_libraries` 时必须追溯目标的反向依赖。

package/templates/cpp/skeleton/agent-env/rules/seed-raii.md

@@ -0,0 +1,30 @@
+# RAII：禁止裸 new/delete（种子规则）
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+所有资源（内存、文件、锁、句柄）必须通过 RAII 对象持有；
+禁止裸 `new` / `delete` / `malloc` / `free` / 手写 `fopen/fclose` 对称。
+
+## 正例
+
+```cpp
+auto buf = std::make_unique<uint8_t[]>(len);
+std::lock_guard<std::mutex> lk(mu_);
+std::ifstream in(path);
+```
+
+## 反例
+
+```cpp
+// ❌ 裸指针 + 手动释放，异常安全无保证
+uint8_t* buf = new uint8_t[len];
+doSomething(buf);
+delete[] buf;
+```
+
+## 如何检测
+
+- grep `new\s+\w` / `delete\s` / `\bmalloc\(` / `\bfree\(` 命中需评审；
+  允许白名单：第三方 C API 适配、placement new。

package/templates/python/skeleton/agent-env/rules/seed-context-managers.md

@@ -0,0 +1,60 @@
+# 上下文管理器（种子规则）
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+文件、网络连接、锁、数据库游标等资源**必须使用 `with` 语句**管理生命周期，禁止裸 `open()`/`.close()` 配对。
+异常安全由上下文管理器保证，无需手写 `try/finally`。
+
+自定义资源类应实现 `__enter__` / `__exit__`，或使用 `contextlib.contextmanager` 装饰器。
+
+## 正例
+
+```python
+with open("data.json", "r", encoding="utf-8") as f:
+    data = json.load(f)
+
+with httpx.Client() as client:
+    resp = client.get("https://api.example.com/health")
+
+with threading.Lock():
+    shared_counter += 1
+
+# 自定义上下文管理器
+from contextlib import contextmanager
+
+@contextmanager
+def temp_env(key: str, value: str):
+    old = os.environ.get(key)
+    os.environ[key] = value
+    try:
+        yield
+    finally:
+        if old is None:
+            del os.environ[key]
+        else:
+            os.environ[key] = old
+```
+
+## 反例
+
+```python
+# ❌ 裸 open/close，异常时泄露
+f = open("data.json")
+data = json.load(f)
+f.close()
+
+# ❌ 手写 try/finally 代替 with
+lock = threading.Lock()
+lock.acquire()
+try:
+    shared_counter += 1
+finally:
+    lock.release()
+```
+
+## 如何检测
+
+- `ruff` 规则 `SIM115`（使用上下文管理器打开文件）。
+- grep `\.open\(` 但不在 `with` 块中。

package/templates/python/skeleton/agent-env/rules/seed-docstrings.md

@@ -0,0 +1,48 @@
+# 文档字符串（种子规则）
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+所有公共模块、类、函数/方法必须写 docstring（PEP 257）。
+格式统一为 Google style 或 NumPy style，项目内二选一后强制执行。
+docstring 需涵盖：一句话摘要、`Args`/`Returns`/`Raises`/`Examples`。
+
+## 正例
+
+```python
+def divide(a: float, b: float) -> float:
+    """返回 a / b 的商。
+
+    Args:
+        a: 被除数。
+        b: 除数。
+
+    Returns:
+        a / b 的浮点结果。
+
+    Raises:
+        ZeroDivisionError: 当 b 为 0 时抛出。
+    """
+    if b == 0:
+        raise ZeroDivisionError("除数不能为 0")
+    return a / b
+```
+
+## 反例
+
+```python
+# ❌ 无 docstring
+def divide(a, b):
+    return a / b
+
+# ❌ 无意义 docstring
+def divide(a, b):
+    """divide function."""
+    return a / b
+```
+
+## 如何检测
+
+- `ruff` 规则 `D`（pydocstyle）或 `interrogate` 检查覆盖率。
+- CI 设置 docstring 覆盖率阈值（推荐 ≥ 80% 公共 API）。

package/templates/python/skeleton/agent-env/rules/seed-import-order.md

@@ -0,0 +1,49 @@
+# 导入顺序（种子规则）
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+import 语句分三组，组间空一行，组内按字母序排列：
+1. **标准库**（`os`, `sys`, `pathlib` …）
+2. **第三方库**（`requests`, `numpy`, `fastapi` …）
+3. **本地/项目内模块**（`from .utils import ...`）
+
+禁止 `from module import *`（星号导入），禁止在函数内 import（除非处理循环引用且加注释说明）。
+
+## 正例
+
+```python
+import os
+import sys
+from pathlib import Path
+
+import numpy as np
+import requests
+
+from myapp.core.config import Settings
+from myapp.utils.validators import validate_email
+```
+
+## 反例
+
+```python
+# ❌ 星号导入
+from os import *
+
+# ❌ 乱序混排
+import requests
+import os
+from myapp.core import config
+import sys
+
+# ❌ 函数内无注释 import
+def do_something():
+    import json  # 无循环引用说明
+    ...
+```
+
+## 如何检测
+
+- `ruff` 规则 `I`（isort）或直接使用 `isort --check-only`。
+- 禁止 `# isort: skip` 无注释使用。

package/templates/python/skeleton/agent-env/rules/seed-pep8-naming.md

@@ -0,0 +1,45 @@
+# PEP 8 命名规范（种子规则）
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+Python 命名必须遵守 PEP 8：
+- 模块/包：`snake_case`（全小写 + 下划线）
+- 函数/方法/变量：`snake_case`
+- 类/异常：`PascalCase`
+- 常量：`UPPER_CASE`
+- 私有成员：单下划线前缀 `_internal`；避免双下划线前缀（name mangling）除非必要
+
+## 正例
+
+```python
+MAX_RETRIES = 3
+
+class UserRepository:
+    def __init__(self, db_url: str):
+        self._db_url = db_url  # 私有属性
+
+    def find_by_id(self, user_id: int) -> User | None:
+        ...
+```
+
+## 反例
+
+```python
+# ❌ 驼峰命名函数
+def getUserById(userId):
+    ...
+
+# ❌ 类用小写
+class user_repository:
+    ...
+
+# ❌ 常量用小写
+max_retries = 3
+```
+
+## 如何检测
+
+- 启用 `ruff` 规则 `N`（pep8-naming）或 `flake8` 插件 `pep8-naming`。
+- CI 中 `ruff check --select N` 命中即违规。

package/templates/python/skeleton/agent-env/rules/seed-type-annotations.md

@@ -0,0 +1,43 @@
+# 类型注解（种子规则）
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+所有公共函数/方法必须标注参数类型与返回值类型（PEP 484 / PEP 585）。
+使用 `from __future__ import annotations`（Python 3.7+）启用延迟求值，避免循环引用。
+容器类型使用 `list[X]` / `dict[K,V]`（Python 3.9+），而非 `typing.List`。
+
+## 正例
+
+```python
+from __future__ import annotations
+
+def parse_config(path: str) -> dict[str, str | int]:
+    ...
+
+def query_users(
+    ids: list[int],
+    *,
+    limit: int = 100,
+) -> list[User]:
+    ...
+```
+
+## 反例
+
+```python
+# ❌ 无类型注解
+def parse_config(path):
+    ...
+
+# ❌ 过时的 typing 泛型
+from typing import List, Dict
+def get_map() -> Dict[str, List[int]]:
+    ...
+```
+
+## 如何检测
+
+- `mypy --strict` 或 `pyright` 全覆盖。
+- 禁止 `# type: ignore` 无注释使用（grep 扫 `type: ignore` 需写原因）。

package/templates/web-react/skeleton/agent-env/rules/seed-controlled-component.md

@@ -0,0 +1,43 @@
+# 表单走受控组件
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+可编辑的表单元素（`<input>` `<textarea>` `<select>`）**必须使用受控模式**：`value` 绑定到 state，`onChange` 同步回写 state。禁止依赖 `defaultValue` + DOM 查询读回值（`ref.current.value`）做业务逻辑。
+
+## 正例
+
+```tsx
+function LoginForm() {
+  const [email, setEmail] = useState('');
+  const [pwd, setPwd] = useState('');
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); submit(email, pwd); }}>
+      <input value={email} onChange={(e) => setEmail(e.target.value)} />
+      <input type="password" value={pwd} onChange={(e) => setPwd(e.target.value)} />
+      <button type="submit" disabled={!email || !pwd}>登录</button>
+    </form>
+  );
+}
+```
+
+## 反例
+
+```tsx
+function LoginForm() {
+  const emailRef = useRef<HTMLInputElement>(null);
+
+  return (
+    <form onSubmit={() => submit(emailRef.current!.value)}> {/* ❌ 直接读 DOM 值 */}
+      <input defaultValue="" ref={emailRef} />              {/* ❌ 非受控 */}
+    </form>
+  );
+}
+```
+
+## 如何检测
+
+- grep 扫 `defaultValue=` 与业务组件 `useRef<HTMLInputElement>` 的同文件共存，人工复核是否用于读取用户输入。
+- code-review checklist：任何 `<input>`/`<textarea>`/`<select>` 必须同时出现 `value=` 与 `onChange=`。

package/templates/web-react/skeleton/agent-env/rules/seed-effect-cleanup.md

@@ -0,0 +1,43 @@
+# useEffect 必须返回 cleanup
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+`useEffect` 内若创建了**订阅、定时器、事件监听、WebSocket、AbortController、异步 fetch 任务**，必须返回 cleanup 函数在组件卸载或依赖变更时释放，否则会内存泄漏、状态错乱、"Can't perform a React state update on an unmounted component" 警告。
+
+## 正例
+
+```tsx
+useEffect(() => {
+  const ctrl = new AbortController();
+  fetch(`/api/user/${id}`, { signal: ctrl.signal })
+    .then((r) => r.json())
+    .then(setUser)
+    .catch((e) => { if (e.name !== 'AbortError') console.error(e); });
+
+  const timer = setInterval(tick, 1000);
+  window.addEventListener('resize', onResize);
+
+  return () => {
+    ctrl.abort();
+    clearInterval(timer);
+    window.removeEventListener('resize', onResize);
+  };
+}, [id]);
+```
+
+## 反例
+
+```tsx
+useEffect(() => {
+  setInterval(tick, 1000);                 // ❌ 无 cleanup，组件卸载后仍在跑
+  window.addEventListener('resize', onResize); // ❌ 监听未移除
+  fetch(url).then(setData);                // ❌ 卸载后仍 setState
+}, []);
+```
+
+## 如何检测
+
+- 启用 `eslint-plugin-react-hooks` 的 `react-hooks/exhaustive-deps` 规则。
+- grep 扫 `useEffect(` 的同块内出现 `setInterval|addEventListener|new WebSocket|subscribe(` 但无 `return (` 的回调。

package/templates/web-react/skeleton/agent-env/rules/seed-hook-rules.md

@@ -0,0 +1,42 @@
+# React Hook 调用铁律
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+React Hook（`useState` / `useEffect` / `useMemo` / 自定义 `useXxx`）**只能在组件函数顶层同步调用**，禁止在条件分支、循环、`try/catch`、嵌套函数内调用，否则 Hook 调用顺序会错乱，React 内部以调用顺序匹配状态槽位，错乱即导致状态读错。
+
+## 正例
+
+```tsx
+function UserPanel({ id }: { id: string }) {
+  const [user, setUser] = useState<User | null>(null);
+  const theme = useTheme();
+
+  useEffect(() => {
+    let cancelled = false;
+    fetchUser(id).then((u) => !cancelled && setUser(u));
+    return () => { cancelled = true; };
+  }, [id]);
+
+  if (!user) return <Spinner />;
+  return <Card theme={theme}>{user.name}</Card>;
+}
+```
+
+## 反例
+
+```tsx
+function UserPanel({ id }: { id?: string }) {
+  if (!id) return null;                 // ❌ 提前 return 前后 Hook 数量不一致
+  const [user, setUser] = useState(null); // ❌ 条件之后才调用 Hook
+  for (const f of fields) {
+    const [v, setV] = useState('');     // ❌ 循环内 Hook
+  }
+}
+```
+
+## 如何检测
+
+- 启用 `eslint-plugin-react-hooks` 的 `react-hooks/rules-of-hooks` 规则（`error` 级）。
+- CI 中禁用 `eslint-disable react-hooks/rules-of-hooks`（grep 扫禁词）。

package/templates/web-react/skeleton/agent-env/rules/seed-key-stability.md

@@ -0,0 +1,39 @@
+# 列表 key 必须稳定
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+`<List>.map` 渲染列表时，`key` **必须是数据本身的稳定唯一标识**（id / uuid / hash），禁止使用数组 `index` 作为 key（除非列表完全静态、永不插入/删除/重排）。index 作 key 会在增删中错位，导致组件状态串台、表单值丢失、动画错误。
+
+## 正例
+
+```tsx
+{users.map((u) => (
+  <UserCard key={u.id} user={u} />
+))}
+
+// 若数据天然无 id，在数据层生成稳定 id（crypto.randomUUID），不要在渲染时生成
+const todos = rawTodos.map((t) => ({ ...t, _id: t.id ?? crypto.randomUUID() }));
+```
+
+## 反例
+
+```tsx
+{users.map((u, i) => (
+  <UserCard key={i} user={u} />        // ❌ index 作 key
+))}
+
+{users.map((u) => (
+  <UserCard key={Math.random()} />     // ❌ 每次渲染都变
+))}
+
+{users.map((u) => (
+  <UserCard key={`${u.name}-${u.age}`} /> // ❌ 非唯一，可能重复
+))}
+```
+
+## 如何检测
+
+- 启用 eslint 规则 `react/no-array-index-key`。
+- grep 扫 `key={.*Math\.random|key=\{[a-z]+Index\}|key=\{i\}|key=\{index\}`。

package/templates/web-react/skeleton/agent-env/rules/seed-no-props-drilling.md

@@ -0,0 +1,43 @@
+# 禁止超 2 层 props drilling
+
+> 种子规则：可保留、修改或删除。
+
+## 是什么
+
+同一个 prop 若需**经过 3 层及以上组件透传**（父→子→孙→曾孙），必须改用 `Context` 或状态管理库（Zustand / Redux / Jotai），否则中间层组件被迫声明自己不关心的字段，耦合度急剧上升，重构时一改多处。
+
+阈值：**允许 2 层透传，3 层及以上必须改造**。
+
+## 正例
+
+```tsx
+const ThemeContext = createContext<Theme>('light');
+
+function App() {
+  const [theme, setTheme] = useState<Theme>('dark');
+  return (
+    <ThemeContext.Provider value={theme}>
+      <Layout />  {/* Layout → Sidebar → MenuItem 都可直接 useContext */}
+    </ThemeContext.Provider>
+  );
+}
+
+function MenuItem() {
+  const theme = useContext(ThemeContext);
+  return <li className={theme}>...</li>;
+}
+```
+
+## 反例
+
+```tsx
+<Layout theme={theme} />
+<Sidebar theme={theme} />    {/* Layout 自己不用 theme，只是透传 */}
+<Menu theme={theme} />       {/* Sidebar 也不用 */}
+<MenuItem theme={theme} />   {/* 第 4 层才真正使用 ❌ */}
+```
+
+## 如何检测
+
+- code-review：若某个 prop 在连续 3 层组件中仅透传未使用，要求拆为 Context。
+- 可选：eslint 自定义规则扫 `<Foo prop={prop} />` 模式（prop 同名透传）。