@chongyan/autospec 1.0.1

package/knowledge/guides/support/test-runner.md

@@ -0,0 +1,254 @@
+---
+name: test-runner
+description: 运行项目测试并收集结果，为 field-evolve 和 validate 命令提供数据支撑
+type: skill
+---
+
+# 测试运行器
+
+## 定位
+
+运行项目的编译、测试、Lint 等确定性验证，收集执行结果供 AI 分析。
+
+---
+
+## 支持的验证类型
+
+### 1. 编译检查
+
+| 语言/框架 | 命令 |
+|----------|------|
+| Node.js/TypeScript | `npm run build` 或 `tsc --noEmit` |
+| Java/Maven | `mvn compile` |
+| Java/Gradle | `./gradlew compileJava` |
+| Python | `python -m py_compile` 或无（解释型） |
+| Go | `go build ./...` |
+| Rust | `cargo build` |
+
+### 2. 单元测试
+
+| 语言/框架 | 命令 |
+|----------|------|
+| Node.js/Jest | `npm test` 或 `npx jest` |
+| Node.js/Vitest | `npm test` 或 `npx vitest run` |
+| Node.js/Mocha | `npm test` 或 `npx mocha` |
+| Python/pytest | `pytest` |
+| Python/unittest | `python -m unittest` |
+| Java/Maven | `mvn test` |
+| Java/Gradle | `./gradlew test` |
+| Go | `go test ./...` |
+| Rust | `cargo test` |
+
+### 3. Lint 检查
+
+| 语言/框架 | 命令 |
+|----------|------|
+| JavaScript/ESLint | `npm run lint` 或 `npx eslint .` |
+| TypeScript/ESLint | `npx eslint . --ext .ts,.tsx` |
+| Python/Flake8 | `flake8 .` |
+| Python/Pylint | `pylint **/*.py` |
+| Java/Checkstyle | `mvn checkstyle:check` |
+| Go/golint | `golint ./...` |
+| Rust/Clippy | `cargo clippy` |
+
+### 4. 类型检查
+
+| 语言/框架 | 命令 |
+|----------|------|
+| TypeScript | `tsc --noEmit` |
+| Python/mypy | `mypy .` |
+| Go | 内置于编译 |
+| Rust | 内置于编译 |
+
+---
+
+## 输出格式
+
+测试结果输出到 `.autospec/runtime/test-result.json`：
+
+```json
+{
+  "timestamp": "2024-01-15T10:30:00Z",
+  "project": {
+    "name": "my-project",
+    "techStack": "Node.js/TypeScript",
+    "subsystems": [
+      {
+        "name": "backend",
+        "path": "backend",
+        "type": "backend"
+      },
+      {
+        "name": "frontend",
+        "path": "frontend",
+        "type": "frontend"
+      }
+    ]
+  },
+  "results": {
+    "compile": {
+      "status": "pass",
+      "duration": 5.2,
+      "output": "...",
+      "errors": []
+    },
+    "test": {
+      "status": "fail",
+      "duration": 12.5,
+      "output": "...",
+      "summary": {
+        "total": 50,
+        "passed": 47,
+        "failed": 3,
+        "skipped": 0
+      },
+      "coverage": {
+        "lines": 78.5,
+        "branches": 65.2,
+        "functions": 82.1
+      },
+      "failures": [
+        {
+          "file": "tests/auth.test.ts",
+          "name": "should authenticate user",
+          "line": 45,
+          "message": "Expected status 200 but got 401",
+          "stack": "Error: Expected status 200..."
+        }
+      ]
+    },
+    "lint": {
+      "status": "pass",
+      "duration": 2.1,
+      "output": "...",
+      "warnings": [
+        {
+          "file": "src/utils/helper.ts",
+          "line": 15,
+          "rule": "no-unused-vars",
+          "message": "'temp' is declared but never used"
+        }
+      ]
+    },
+    "typecheck": {
+      "status": "pass",
+      "duration": 3.5,
+      "output": "...",
+      "errors": []
+    }
+  },
+  "overall": {
+    "status": "fail",
+    "passedChecks": ["compile", "lint", "typecheck"],
+    "failedChecks": ["test"]
+  }
+}
+```
+
+---
+
+## 执行步骤
+
+### Step 1: 确定技术栈
+
+```
+1. 读取 .autospec/runtime/config.json
+2. 获取 techStack 和 subsystems 信息
+3. 确定要执行的验证类型
+```
+
+### Step 2: 执行验证
+
+```
+对每个子系统（或单系统）：
+1. 执行编译检查
+2. 编译通过后执行单元测试
+3. 执行 Lint 检查
+4. 执行类型检查（如适用）
+```
+
+### Step 3: 收集结果
+
+```
+1. 捕获命令输出
+2. 解析测试结果
+3. 提取覆盖率数据（如有）
+4. 收集错误和警告信息
+```
+
+### Step 4: 汇总报告
+
+```
+1. 合并各子系统结果
+2. 计算总体状态
+3. 输出到 .autospec/runtime/test-result.json
+```
+
+---
+
+## 命令检测逻辑
+
+自动检测项目使用的测试框架：
+
+```javascript
+// 检测 Jest
+if (exists('jest.config.js') ||
+    packageJson.devDependencies?.jest) {
+  testCommand = 'npx jest --json --outputFile=test-result.json'
+}
+
+// 检测 Vitest
+if (exists('vitest.config.ts') ||
+    packageJson.devDependencies?.vitest) {
+  testCommand = 'npx vitest run --reporter=json'
+}
+
+// 检测 pytest
+if (exists('pytest.ini') ||
+    exists('pyproject.toml') && contains('[tool.pytest')) {
+  testCommand = 'pytest --json-report'
+}
+```
+
+---
+
+## 错误处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 命令不存在 | 跳过该检查，记录警告 |
+| 超时 | 默认 5 分钟，可配置 |
+| 内存不足 | 建议用户增加资源 |
+| 权限不足 | 建议用户检查权限 |
+
+---
+
+## 多系统支持
+
+对于多子系统项目：
+
+```
+1. 按子系统顺序执行（backend → frontend → ...）
+2. 每个子系统独立收集结果
+3. 汇总时标记各子系统状态
+4. 一个子系统失败不影响其他子系统执行
+```
+
+---
+
+## 注意事项
+
+1. **性能优化**：
+   - 并行执行独立的检查
+   - 使用增量测试（如支持）
+   - 缓存编译结果
+
+2. **结果解析**：
+   - 支持多种测试框架的输出格式
+   - 提取覆盖率数据
+   - 解析错误堆栈
+
+3. **环境隔离**：
+   - 不修改项目文件
+   - 结果输出到 .autospec/runtime/
+   - 清理临时文件

package/knowledge/guides/system-design.md

@@ -0,0 +1,352 @@
+# 系统设计指南
+
+> **版本**: v1.0
+> **最后更新**: 2026-03-26
+> **基于**: 业界系统设计最佳实践 / 结构化设计方法
+> **适用范围**: 所有系统设计场景
+
+---
+
+## 目标
+
+基于 proposal.md 或用户描述的需求，进行两步生成系统设计文档（design.md）。
+
+---
+
+## 两步生成法
+
+### 设计哲学
+
+**Phase 1: 大纲生成** → **Phase 2: 逐个细化**
+
+```
+Phase 1 (大纲)          Phase 2 (详设)
+    ↓                       ↓
+功能点列表            逐个功能点写详设
+全部标记 - [ ]          每完成一个打钩 - [x]
+    ↓                       ↓
+用户确认方向           进度可视化
+```
+
+### 优势
+
+1. **避免整体返工**: 用户先确认大纲方向，再细化
+2. **可中断**: 逐个细化可中断，完成部分可直接使用
+3. **进度可视化**: 用户随时知道完成度
+4. **即时反馈**: 每完成一个功能点即可 review
+
+---
+
+## 设计文档模板结构
+
+```markdown
+# Design: {需求名}/{系统名}
+
+## 1. 项目背景
+**目标**: {一句话描述}
+**参与人**: PM: xx, 开发：xx, 测试：xx
+**相关文档**: [proposal.md](../proposal.md)
+
+## 2. 业务用例
+[Mermaid flowchart - 从 proposal 中提取本系统相关用例]
+
+## 3. 功能设计
+
+### 3.1 功能点列表
+- [ ] **FP-01**: {功能点 1 名称} - {简要描述}
+- [ ] **FP-02**: {功能点 2 名称} - {简要描述}
+- [ ] **FP-03**: {功能点 3 名称} - {简要描述}
+
+### 3.2 详细设计
+
+#### 3.2.1 FP-01: {功能点 1 名称}
+> ⏳ 待细化
+
+#### 3.2.2 FP-02: {功能点 2 名称}
+> ⏳ 待细化
+
+#### 3.2.3 FP-03: {功能点 3 名称}
+> ⏳ 待细化
+
+## 4. 领域模型 (可选)
+## 5. 发布依赖 (涉及共享组件/依赖库变更时必须)
+## 6. 风险分析 (可选)
+```
+
+---
+
+## 设计原则
+
+### 1. 描述方法职责，不平铺实现代码
+
+**错误示例**:
+```markdown
+### 3.2.1 FP-01: 创建订单
+
+实现代码：
+```java
+public Order createOrder(OrderRequest request) {
+    // 1. 参数校验
+    if (request == null) {
+        throw new IllegalArgumentException("请求不能为空");
+    }
+    // 2. 查询用户
+    User user = userRepository.findById(request.getUserId());
+    // ... 更多实现
+}
+```
+```
+
+**正确示例**:
+```markdown
+### 3.2.1 FP-01: 创建订单
+
+**职责**: 接收订单创建请求，校验参数后创建订单记录
+
+**输入**: OrderRequest (userId, productId, amount)
+
+**处理**:
+1. 参数校验（非空、格式、业务规则）
+2. 用户存在性校验
+3. 库存预占
+4. 创建订单记录，状态为"待支付"
+5. 发送订单创建事件
+
+**输出**: Order (orderId, status, createTime)
+
+**异常**:
+- IllegalArgumentException: 参数校验失败
+- UserNotFoundException: 用户不存在
+- StockNotEnoughException: 库存不足
+```
+
+### 2. 功能点职责清晰不重叠
+
+**错误示例**:
+```markdown
+#### FP-01: 用户注册
+处理用户注册请求，验证手机号，发送验证码，创建用户记录
+
+#### FP-02: 发送验证码
+接收手机号，生成验证码，发送短信，存储验证码
+```
+问题：FP-01 和 FP-02 职责重叠，"发送验证码"逻辑重复
+
+**正确示例**:
+```markdown
+#### FP-01: 用户注册
+处理用户注册请求，调用 FP-02 发送验证码，创建用户记录
+
+#### FP-02: 发送验证码
+接收手机号，生成验证码，发送短信，存储验证码（供 FP-01 和其他场景调用）
+```
+
+### 3. 开关/配置只加必要的
+
+**原则**:
+- 能由调用方控制的不在本系统加开关
+- 新增配置必须有明确的业务场景
+- 避免过度配置导致维护成本
+
+**错误示例**:
+```markdown
+新增 DRM 配置：
+- enableOrderCreate: 是否开启订单创建
+- enableOrderUpdate: 是否开启订单更新
+- enableOrderDelete: 是否开启订单删除
+- logLevel: 日志级别
+- timeout: 超时时间
+- retryCount: 重试次数
+```
+
+**正确示例**:
+```markdown
+新增 DRM 配置：
+- orderCreateEnabled: 订单创建开关（用于应急降级）
+```
+
+### 4. 共享组件/依赖库变更必须说明
+
+涉及共享组件（SPI/Facade/依赖库）模型变更时，必须说明：
+
+| 字段 | 说明 |
+|------|------|
+| Maven 坐标 | groupId:artifactId |
+| 当前版本 | 当前使用的版本 |
+| 升级版本 | 计划升级的版本 |
+| 变更内容 | 具体变更了什么 |
+| 需升级的系统 | 哪些系统需要同步升级 |
+
+---
+
+## 详细设计单点模板
+
+```markdown
+### 3.2.{N} FP-{NN}: {功能点名称}
+
+**概述**
+{功能点的业务目标和实现思路}
+
+**流程图** (可选)
+```mermaid
+sequenceDiagram
+    participant U as 用户/上游
+    participant S as 本系统
+    participant D as 下游系统
+
+    U->>S: 1. 请求描述
+    S->>D: 2. 调用下游
+    D-->>S: 3. 返回结果
+    S-->>U: 4. 响应
+```
+
+**下游交互** (可选)
+{描述与下游系统的交互细节}
+
+**对外接口** (可选)
+{描述对外提供的接口定义}
+
+**异常处理** (可选)
+{描述异常处理逻辑}
+
+**业务规则** (可选)
+{描述涉及的业务规则}
+```
+
+---
+
+## 设计文档质量检查
+
+### Phase 1 检查点
+
+- [ ] 项目背景填写完整
+- [ ] 业务用例图从 proposal 正确提取
+- [ ] 功能点列表完整，覆盖 proposal 所有功能
+- [ ] 功能点命名清晰，职责单一
+- [ ] 详细设计章节占位符正确
+
+### Phase 2 检查点
+
+- [ ] 所有功能点已标记为 `[x]` 完成
+- [ ] 每个功能点都有详细设计内容
+- [ ] 流程图可正常渲染
+- [ ] 与 proposal.md 业务流程一致
+- [ ] 遵循系统架构规范
+
+### 设计原则检查
+
+- [ ] 无实现代码平铺（方法设计只描述职责、入参、输出）
+- [ ] 功能点职责不重叠（无多个功能点重复描述同一逻辑）
+- [ ] 开关/配置无过度设计
+- [ ] 新增配置与项目已有配置声明方式一致
+- [ ] 共享组件/依赖库模型变更已说明版本升级方案
+
+---
+
+## 领域模型设计指南
+
+### 4.1 模型设计
+
+使用 Mermaid classDiagram 描述领域模型：
+
+```mermaid
+classDiagram
+    class Order {
+        +Long orderId
+        +String userId
+        +OrderStatus status
+        +Money amount
+        +confirm()
+        +cancel()
+    }
+    class OrderStatus {
+        <<enumeration>>
+        INIT
+        PAYING
+        SUCCESS
+        CANCELLED
+    }
+    Order --> OrderStatus
+```
+
+### 4.2 状态机
+
+使用 Mermaid stateDiagram 描述状态流转：
+
+```mermaid
+stateDiagram-v2
+    [*] --> INIT: 创建订单
+    INIT --> PAYING: 发起支付
+    PAYING --> SUCCESS: 支付成功
+    PAYING --> CANCELLED: 支付失败/超时
+    CANCELLED --> [*]
+    SUCCESS --> [*]
+```
+
+### 4.3 数据库设计
+
+使用 Mermaid erDiagram 或表格描述：
+
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ ORDER_ITEM : contains
+    PRODUCT ||--o{ ORDER_ITEM : included_in
+```
+
+---
+
+## 多系统设计指南
+
+### 设计文档组织
+
+```
+requirements/{业务域}/{需求}/
+├── proposal.md              # 整体需求提案
+└── design/
+    ├── overview.md          # 整体架构设计
+    ├── backend.md           # 后端系统设计
+    ├── frontend.md          # 前端系统设计
+    ├── ai.md                # AI/模型设计（如需要）
+    └── data.md              # 数据管道设计（如需要）
+```
+
+### 设计顺序
+
+**有依赖关系的系统**：
+1. 先设计被依赖的系统（如后端 API）
+2. 再设计调用方系统（如前端、移动端）
+
+**可并行的系统**：
+1. 先定义契约（API Schema、数据 Schema）
+2. 各系统基于契约并行设计
+
+### 跨系统设计检查
+
+- [ ] 系统间接口定义清晰
+- [ ] 数据一致性方案明确
+- [ ] 超时/重试/降级策略一致
+- [ ] 错误码定义统一
+- [ ] 监控指标对齐
+
+---
+
+## 最佳实践
+
+1. **两步生成**: Phase 1 大纲 → Phase 2 详设，避免整体返工
+2. **流程图优先**: 能用图表达的不用文字
+3. **职责单一**: 每个功能点职责清晰不重叠
+4. **领域模型**: 核心业务逻辑内聚到领域对象
+5. **状态机**: 复杂状态流转用状态图描述
+6. **多系统**: 先契约后实现，支持并行设计
+7. **发布依赖**: 涉及共享组件/依赖库必须说明升级方案
+
+---
+
+## 参考资料
+
+- [design 模板](../templates/design.md)
+- [design 检查清单](../checklists/design.md)
+- [设计哲学 - 两步生成](../principles/design-philosophy.md#核心设计模式)
+- [编码规范](../standards/coding-style.md)
+- [数据一致性规范](../standards/data-consistency.md)