@chongyan/autospec 1.0.2 → 1.0.4

package/knowledge/03-guides/44-manage-knowledge.md

@@ -1,369 +0,0 @@
-# 知识管理指南
-
-> **版本**: v1.0
-> **最后更新**: 2026-03-26
-> **基于**: 业界知识库 / 插件市场知识管理体系
-> **适用范围**: 所有知识库建设和维护场景
-
----
-
-## 目标
-
-建立分层、易用、可演进的知识库体系，支撑 AI 驱动的研发流程。
-
----
-
-## 知识分层架构
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Layer 1: Metadata（元数据层）                              │
-│  · skill description（触发条件）                           │
-│  · 知识库导航（README/SUMMARY）                            │
-│  · 快速索引（标签、分类）                                  │
-│  用途：快速定位，决定是否加载                               │
-├─────────────────────────────────────────────────────────┤
-│  Layer 2: SKILL.md（核心逻辑层）                           │
-│  · 执行步骤（Steps）                                      │
-│  · 输入输出（Guardrails）                                 │
-│  · 检查清单（Checklist）                                  │
-│  用途：指导 AI 执行具体任务                                 │
-├─────────────────────────────────────────────────────────┤
-│  Layer 3: References（参考文档层）                         │
-│  · 详细规范（coding-style.md 等）                         │
-│  · 最佳实践（best-practices/）                            │
-│  · 示例代码（examples/）                                  │
-│  用途：按需加载，提供详细参考                              │
-└─────────────────────────────────────────────────────────┘
-```
-
-### 各层设计原则
-
-**Layer 1: Metadata**
-- 简洁明了，一句话说清"什么时候用"
-- 不包含工作流细节（避免 AI 直接按 description 执行）
-- 创造信息差，迫使 AI 加载完整正文
-
-**Layer 2: SKILL.md**
-- 结构化步骤（Step 1, Step 2, ...）
-- 明确的输入输出（Guardrails）
-- 嵌入式检查清单（Post-Check）
-- 检查点机制（BLOCKING CHECKPOINT）
-
-**Layer 3: References**
-- 详细的规范文档
-- 丰富的示例代码
-- 最佳实践总结
-- 可按需加载，不强制全读
-
----
-
-## 业务文档写作规范
-
-### 定位
-
-业务文档（`knowledge/03-guides/domain-*.md`）描述"业务是什么"，不描述"技术怎么实现"。
-
-### 内容范围
-
-**应该写**:
-- 业务流程（用户视角的流转）
-- 业务规则（准入、限制、计算规则）
-- 业务术语（定义、解释）
-- 业务场景（用例、场景描述）
-
-**不应该写**:
-- 技术实现细节（类、方法、算法）
-- 数据库设计（表结构、索引）
-- 接口定义（API、参数）
-- 架构设计（分层、模块）
-
-### 示例对比
-
-**错误示例**（混入技术实现）:
-```markdown
-# 产品购买流程
-
-1. 用户调用 `/api/product/purchase`接口
-2. 系统创建 PurchaseOrder 对象
-3. 调用 ProductService.createOrder() 方法
-4. 写入 purchase_order 表
-```
-
-**正确示例**（纯业务视角）:
-```markdown
-# 产品购买流程
-
-1. 用户提交购买申请（填写金额、选择产品）
-2. 系统校验购买资格（账户状态、风险评估、限额）
-3. 冻结用户资金（购买金额 + 手续费）
-4. 确认份额（T+1 日，按确认日价值）
-5. 份额登记（登记到用户账户）
-```
-
----
-
-## 技术文档写作规范
-
-### 定位
-
-技术文档（`knowledge/system/`）描述"技术怎么实现"，指导开发和运维。
-
-### 标准文件结构
-
-```markdown
-# {系统名称}
-
-## 1. Overview（概述）
-- 系统定位
-- 核心职责
-- 技术栈
-
-## 2. Model（模型）
-- 领域模型
-- 数据模型
-- 状态机
-
-## 3. Process（流程）
-- 核心业务流程
-- 关键时序图
-
-## 4. Design（设计）
-- 架构设计
-- 模块划分
-- 接口定义
-```
-
-### 各章节编写指南
-
-**1. Overview**
-- 一句话描述系统定位
-- 列出核心职责（3-5 条）
-- 技术栈清单（框架、中间件、语言）
-
-**2. Model**
-- 领域模型图（Mermaid classDiagram）
-- 数据模型图（Mermaid erDiagram）
-- 状态流转图（Mermaid stateDiagram）
-
-**3. Process**
-- 核心业务流程图（Mermaid flowchart）
-- 关键时序图（Mermaid sequenceDiagram）
-- 异常流程说明
-
-**4. Design**
-- 系统架构图（分层、模块关系）
-- 模块职责说明
-- 对外接口清单
-
----
-
-## 术语管理
-
-### 原则
-
-**不独立维护 glossary**，术语解释在正文中首次出现时括号说明。
-
-### 示例
-
-```markdown
-# 产品转换流程
-
-产品转换是指投资者将其持有的某个产品（转出产品）转换为同一机构旗下的另一个产品（转入产品）的行为。
-
-转换流程：
-1. 投资者提交转换申请
-2. 系统计算转出产品的可转换份额
-3. 按转换日价值计算转入产品份额
-4. 份额变更登记
-```
-
-### 术语使用规则
-
-1. **首次出现**: 括号解释（如：产品转换（将持有的产品 A 转换为产品 B））
-2. **后续出现**: 直接使用术语，不再解释
-3. **一词多义**: 明确标注不同含义的使用场景
-
----
-
-## 共用规则管理
-
-### 原则
-
-通用规则在父级文档，差异文件仅记录不同点。
-
-### 示例结构
-
-```
-knowledge/03-guides/domain-product/
-├── README.md              # 产品业务通用规则
-├── purchase.md            # 购买特有规则
-├── redeem.md              # 赎回特有规则
-└── transfer.md            # 转换特有规则
-```
-
-### purchase.md 示例
-
-```markdown
-# 产品购买
-
-## 通用规则
-
-参考 [产品业务通用规则](README.md)
-
-## 特有规则
-
-### 购买限额
-
-| 渠道 | 单笔限额 | 单日限额 | 单月限额 |
-|------|---------|---------|---------|
-| 直销 | 100 万 | 500 万 | 2000 万 |
-| 代销 | 50 万 | 200 万 | 1000 万 |
-
-### 购买费率
-
-| 金额区间 | 费率 |
-|---------|------|
-| <100 万 | 1.5% |
-| 100-500 万 | 1.0% |
-| ≥500 万 | 1000 元/笔 |
-```
-
----
-
-## 知识库导航设计
-
-### SUMMARY.md 结构
-
-```markdown
-# 知识库导航
-
-## 业务知识 (domain/)
-* [产品业务](domain/product/README.md)
-  * [购买流程](domain/product/purchase.md)
-  * [赎回流程](domain/product/redeem.md)
-  * [转换流程](domain/product/transfer.md)
-* [支付业务](domain/payment/README.md)
-
-## 系统文档 (system/)
-* [交易系统](system/trade/README.md)
-* [账户系统](system/account/README.md)
-
-## API 文档 (api/)
-* [交易接口](api/trade/README.md)
-* [账户接口](api/account/README.md)
-
-## 数据文档 (data/)
-* [表结构](data/schema/README.md)
-* [数据字典](data/dictionary/README.md)
-```
-
-### 导航设计原则
-
-1. **层次清晰**: 按业务域/系统/类型分层
-2. **命名一致**: 同级目录命名风格一致
-3. **链接有效**: 所有链接可正常跳转
-4. **及时更新**: 新增文档及时更新导航
-
----
-
-## AI Skills 自动生成
-
-### 从知识库到 Skill
-
-AI Skills 可从知识库文档自动生成：
-
-```
-知识库文档 → Skill 提取器 → SKILL.md
-```
-
-### Skill 模板结构
-
-```markdown
----
-name: domain-{业务域}
-description: {业务域} 领域知识，当用户提到 {关键词} 时加载
----
-
-# {业务域} 领域知识
-
-## 业务规则
-
-{从知识库提取的业务规则}
-
-## 术语定义
-
-{从知识库提取的术语}
-
-## 典型场景
-
-{从知识库提取的典型场景}
-```
-
----
-
-## 知识维护流程
-
-### 新增知识
-
-1. **识别类型**: 业务文档/技术文档/API 文档
-2. **选择位置**: 按目录结构存放
-3. **编写内容**: 遵循对应规范
-4. **更新导航**: 更新 SUMMARY.md
-5. **注册 Skill**: 如需要，创建对应的 SKILL.md
-
-### 更新知识
-
-1. **变更识别**: 从代码/流程变更识别知识变更
-2. **影响分析**: 分析受影响的文档
-3. **更新文档**: 更新相关内容
-4. **版本记录**: 记录变更内容和日期
-
-### 废弃知识
-
-1. **标记废弃**: 在文档顶部添加`> ⚠️ 已废弃`
-2. **指向替代**: 说明替代文档
-3. **保留历史**: 不删除，保留历史记录
-
----
-
-## 知识质量检查
-
-### 完整性检查
-
-- [ ] 业务文档覆盖所有业务域
-- [ ] 技术文档覆盖所有系统
-- [ ] API 文档覆盖所有接口
-- [ ] 导航链接全部有效
-
-### 一致性检查
-
-- [ ] 业务文档与技术文档一致
-- [ ] 术语定义一致（同一概念不同文档中名称一致）
-- [ ] 流程图与实际流程一致
-
-### 时效性检查
-
-- [ ] 文档更新日期在 1 年内
-- [ ] 废弃文档已标记
-- [ ] 过时内容已更新
-
----
-
-## 最佳实践
-
-1. **分层加载**: 按 Layer 1→Layer 2→Layer 3 渐进式加载
-2. **业务技术分离**: 业务文档不写技术实现，技术文档不写业务背景
-3. **术语管理**: 首次出现时解释，不独立维护 glossary
-4. **共用规则**: 通用规则在父级，差异仅记录不同点
-5. **导航清晰**: SUMMARY.md 层次清晰，链接有效
-6. **及时更新**: 变更代码同时更新文档
-7. **AI 友好**: Skills 结构化，便于 AI 理解和执行
-
----
-
-## 参考资料
-
-- [template-registry](../environment/template-registry.md)
-- [design-philosophy - 渐进式披露](../principles/01-first-principles.md#核心设计模式)
-- [design-philosophy - 上下文精确管理](../principles/01-first-principles.md#dp4-上下文精确管理)

package/knowledge/03-guides/45-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/
-   - 清理临时文件