@chongyan/autospec 1.0.1 → 1.0.3

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

@@ -1,254 +0,0 @@
----
-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

@@ -1,352 +0,0 @@
-# 系统设计指南
-
-> **版本**: 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)