@chongyan/autospec 1.0.1

package/knowledge/guides/support/environment-validator.md

@@ -0,0 +1,207 @@
+---
+name: environment-validator
+description: 校验环境知识配置文件的完整性和有效性
+type: skill
+---
+
+# 环境配置校验器
+
+## 定位
+
+校验 `.autospec/environment/` 目录下的环境知识配置文件，确保格式正确、字段完整、内容有效。
+
+---
+
+## 校验范围
+
+### 1. 文件格式校验
+
+| 文件类型 | 校验项 |
+|---------|--------|
+| YAML (.yaml, .yml) | 语法正确性、缩进一致性 |
+| JSON (.json) | 语法正确性、编码格式 |
+
+### 2. 必填字段校验
+
+**中间件配置** (`env-knowledge/middleware/*.yaml`)：
+```yaml
+apiVersion: autospec/v1     # 必填
+kind: Middleware            # 必填
+meta
+  name: string              # 必填
+  version: string           # 必填
+spec:
+  type: string              # 必填
+  connection:
+    template: string        # 必填
+```
+
+**组件配置** (`component-lib/components/*/component.yaml`)：
+```yaml
+apiVersion: autospec/v1     # 必填
+kind: Component             # 必填
+metadata:
+  name: string              # 必填
+  version: string           # 必填
+spec:
+  type: string              # 必填
+  description: string       # 必填
+```
+
+### 3. 类型一致性校验
+
+| 字段 | 期望类型 |
+|------|---------|
+| `metadata.version` | 语义化版本字符串 |
+| `spec.type` | 枚举值 |
+| `spec.configuration.required` | 数组 |
+| `spec.bestPractices` | 数组 |
+
+### 4. 引用完整性校验
+
+- 环境变量引用是否存在
+- 文件路径引用是否正确
+- 注册表与实际文件是否一致
+
+---
+
+## 输出格式
+
+校验结果输出：
+
+```json
+{
+  "timestamp": "2024-01-15T10:30:00Z",
+  "summary": {
+    "total": 15,
+    "passed": 12,
+    "failed": 2,
+    "warnings": 3
+  },
+  "files": [
+    {
+      "path": "env-knowledge/middleware/redis.yaml",
+      "valid": true,
+      "errors": [],
+      "warnings": [
+        {
+          "field": "spec.connection.template",
+          "message": "连接模板中包含硬编码的主机地址",
+          "suggestion": "建议使用环境变量替换"
+        }
+      ]
+    },
+    {
+      "path": "env-knowledge/middleware/mysql.yaml",
+      "valid": false,
+      "errors": [
+        {
+          "field": "metadata.version",
+          "message": "版本号格式不正确",
+          "expected": "语义化版本 (如 1.0.0)",
+          "actual": "v1"
+        },
+        {
+          "field": "spec.type",
+          "message": "未知的中间件类型",
+          "expected": "relational-database, document-database, cache, message-queue, search-engine",
+          "actual": "db"
+        }
+      ],
+      "warnings": []
+    }
+  ]
+}
+```
+
+---
+
+## 执行步骤
+
+### Step 1: 扫描配置文件
+
+```
+1. 扫描 .autospec/environment/ 下所有 YAML/JSON 文件
+2. 跳过隐藏文件和临时文件
+3. 构建文件列表
+```
+
+### Step 2: 逐文件校验
+
+```
+对每个文件：
+1. 解析文件内容
+2. 校验文件格式
+3. 校验必填字段
+4. 校验类型一致性
+5. 记录错误和警告
+```
+
+### Step 3: 注册表校验
+
+```
+1. 读取 registry.json
+2. 检查注册的文件是否存在
+3. 检查文件与注册信息是否一致
+```
+
+### Step 4: 汇总结果
+
+```
+1. 统计通过/失败/警告数量
+2. 输出校验报告
+```
+
+---
+
+## 校验规则
+
+### 错误级别（必须修复）
+
+| 规则 | 说明 |
+|------|------|
+| YAML_SYNTAX | YAML 语法错误 |
+| JSON_SYNTAX | JSON 语法错误 |
+| REQUIRED_FIELD | 缺少必填字段 |
+| INVALID_TYPE | 字段类型不正确 |
+| INVALID_VERSION | 版本号格式不正确 |
+| FILE_NOT_FOUND | 注册表中引用的文件不存在 |
+
+### 警告级别（建议修复）
+
+| 规则 | 说明 |
+|------|------|
+| HARDCODED_VALUE | 硬编码值（建议使用环境变量） |
+| MISSING_OPTIONAL | 缺少可选但推荐的字段 |
+| DEPRECATED_FIELD | 使用了已弃用的字段 |
+| EMPTY_SECTION | 空的配置段落 |
+| INCONSISTENT_NAMING | 命名风格不一致 |
+
+---
+
+## 自动修复（可选）
+
+对于某些问题，支持自动修复：
+
+| 问题 | 修复方式 |
+|------|---------|
+| 缺少 `apiVersion` | 自动填充 `autospec/v1` |
+| 缺少 `kind` | 根据文件路径推断 |
+| 版本号格式错误 | 尝试转换为语义化版本 |
+| 缩进不一致 | 自动格式化 YAML |
+
+---
+
+## 注意事项
+
+1. **性能考虑**：
+   - 大文件分块解析
+   - 并行处理多个文件
+
+2. **兼容性**：
+   - 支持不同版本的配置格式
+   - 向后兼容旧版本字段
+
+3. **扩展性**：
+   - 支持自定义校验规则
+   - 支持插件扩展

package/knowledge/guides/support/knowledge-generator.md

@@ -0,0 +1,234 @@
+# 环境知识生成器
+
+## 功能
+
+根据检测到的中间件/组件，生成完整的环境知识配置。包括连接配置模板、最佳实践建议、反模式警告。
+
+## 触发条件
+
+- 检测到新的中间件或组件
+- 需要生成环境知识配置
+- 用户请求添加组件知识
+
+## 输入
+
+```json
+{
+  "middleware": {
+    "name": "mysql",
+    "type": "relational-database",
+    "detectedFrom": "依赖检测",
+    "usagePatterns": ["检测到的使用模式"]
+  },
+  "projectContext": {
+    "language": "python",
+    "framework": "FastAPI",
+    "existingKnowledge": "已有的环境知识"
+  }
+}
+```
+
+## 输出
+
+```yaml
+# 环境知识 YAML
+middleware:
+  mysql:
+    type: relational-database
+    description: MySQL 数据库
+    connection:
+      host: ${MYSQL_HOST}
+      port: ${MYSQL_PORT:-3306}
+      database: ${MYSQL_DATABASE}
+      user: ${MYSQL_USER}
+      password: ${MYSQL_PASSWORD}
+    codeExamples:
+      python: |
+        import pymysql
+        connection = pymysql.connect(
+            host='${MYSQL_HOST}',
+            port=3306,
+            database='${MYSQL_DATABASE}',
+            user='${MYSQL_USER}',
+            password='${MYSQL_PASSWORD}'
+        )
+    bestPractices:
+      - 使用连接池管理连接
+      - 敏感信息使用环境变量
+      - 定期备份
+    antiPatterns:
+      - 不要在代码中硬编码密码
+      - 不要使用 root 用户连接
+    envVariables:
+      - name: MYSQL_HOST
+        required: true
+        description: MySQL 服务器地址
+      - name: MYSQL_PORT
+        required: false
+        default: "3306"
+        description: MySQL 端口
+```
+
+## 执行步骤
+
+1. **分析中间件类型**
+   - 根据名称和依赖推断类型
+   - 确定连接配置模板
+
+2. **生成连接配置**
+   - 根据中间件类型选择模板
+   - 使用环境变量占位符
+
+3. **生成代码示例**
+   - 根据项目语言选择示例
+   - 包含最佳实践代码
+
+4. **添加最佳实践**
+   - 从知识库检索相关实践
+   - 结合项目上下文调整
+
+5. **添加反模式警告**
+   - 常见错误模式
+   - 安全注意事项
+
+## 中间件类型模板
+
+### relational-database (MySQL, PostgreSQL, etc.)
+
+```yaml
+connection:
+  host: ${NAME_HOST}
+  port: ${NAME_PORT:-3306}
+  database: ${NAME_DATABASE}
+  user: ${NAME_USER}
+  password: ${NAME_PASSWORD}
+```
+
+### cache (Redis, Memcached, etc.)
+
+```yaml
+connection:
+  host: ${NAME_HOST}
+  port: ${NAME_PORT:-6379}
+  password: ${NAME_PASSWORD}
+  db: ${NAME_DB:-0}
+```
+
+### queue (Kafka, RabbitMQ, etc.)
+
+```yaml
+connection:
+  brokers: ${NAME_BROKERS}
+  topic: ${NAME_TOPIC}
+  groupId: ${NAME_GROUP_ID}
+```
+
+### vector-store (ChromaDB, Pinecone, etc.)
+
+```yaml
+connection:
+  host: ${NAME_HOST}
+  port: ${NAME_PORT}
+  apiKey: ${NAME_API_KEY}
+  collection: ${NAME_COLLECTION}
+```
+
+## 最佳实践模板
+
+### 数据库
+
+- 使用连接池
+- 配置合理的超时
+- 启用 SSL 连接
+- 定期备份
+
+### 缓存
+
+- 设置合理的过期时间
+- 使用序列化
+- 监控命中率
+
+### 消息队列
+
+- 配置重试策略
+- 处理死信队列
+- 监控积压
+
+### 向量存储
+
+- 选择合适的索引类型
+- 配置合理的 chunk 大小
+- 监控查询延迟
+
+## 反模式模板
+
+### 通用
+
+- 硬编码敏感信息
+- 使用默认凭据
+- 忽略错误处理
+
+### 数据库
+
+- N+1 查询
+- 缺少索引
+- 大事务
+
+### 缓存
+
+- 缓存穿透
+- 缓存雪崩
+- 热点 Key
+
+## 示例
+
+### 输入
+
+```json
+{
+  "middleware": {
+    "name": "redis",
+    "type": "cache"
+  },
+  "projectContext": {
+    "language": "python",
+    "framework": "FastAPI"
+  }
+}
+```
+
+### 输出
+
+```yaml
+middleware:
+  redis:
+    type: cache
+    description: Redis 缓存
+    connection:
+      host: ${REDIS_HOST}
+      port: ${REDIS_PORT:-6379}
+      password: ${REDIS_PASSWORD}
+      db: ${REDIS_DB:-0}
+    codeExamples:
+      python: |
+        import redis
+        client = redis.Redis(
+            host='${REDIS_HOST}',
+            port=6379,
+            password='${REDIS_PASSWORD}',
+            db=0
+        )
+    bestPractices:
+      - 使用连接池
+      - 设置合理的过期时间
+      - 使用序列化存储对象
+    antiPatterns:
+      - 不要存储大对象
+      - 不要使用 KEYS 命令
+      - 不要忽略缓存失效
+    envVariables:
+      - name: REDIS_HOST
+        required: true
+      - name: REDIS_PASSWORD
+        required: false
+```

package/knowledge/guides/support/methodology-extractor.md

@@ -0,0 +1,55 @@
+---
+name: methodology-extractor
+description: 当全流程完成或practice-log积累到5条以上、需要从实践中识别和提取可复用的方法论时触发
+type: produce
+---
+
+## 定位
+让方法论从实践中自然生长，而非空想。识别实践中的有效模式和认知，沉淀为可复用的原则和方法论。
+
+> 与skill-distiller的区别：distiller提取**可执行的skill**，extractor提取**认知性的方法论**（原则、检查项、决策树）。
+
+## 输入
+- 必须输入：practice-log中状态为"待处理"的条目
+- 可选输入：流程执行记录、人工复盘的讨论内容
+
+## 输出
+- 更新后的methodology文件（principles.md / checklists/ / decision-trees/ / design-philosophy.md）
+- 提取报告（从什么实践提取、更新了哪个文档、新增还是修改）
+- **证据清单**（支撑提取决策的practice-log引用）
+
+## 执行步骤
+1. 扫描practice-log中"待处理"的条目
+2. 分析本次实践：哪些做法有效、哪些踩坑
+   - 预期产出：有效做法列表 + 踩坑列表
+3. 与已有methodology对比：是新发现还是已有原则的验证
+   - 如果是已有原则的验证 → 增加验证案例引用
+   - 如果与已有原则冲突 → 标记待讨论，**不自动覆盖**
+4. 判断是否可泛化：
+   - 只对当前项目有效 → 留在practice-log，标记"仅作案例保留"
+   - 普遍适用 → 提取为方法论
+5. 确定更新目标：
+   - 新原则 → 更新 methodology/principles.md
+   - 新检查项 → 更新对应 methodology/checklists/
+   - 新决策模式 → 创建或更新 methodology/decision-trees/
+   - 设计哲学层面的发现 → 更新 methodology/design-philosophy.md
+6. 执行更新（追加或修改，不删除已有内容除非明确过时）
+7. 更新practice-log对应条目状态为"已处理"
+8. **整理证据清单**
+
+## 反模式清单（DP7）
+1. **空想方法论**：没有实践支撑的方法论。检测：每条方法论必须引用至少1条practice-log
+2. **过度泛化**：把项目特有的经验强行泛化。检测：判断是否在2+项目中有效
+3. **自动覆盖冲突**：新发现与已有原则冲突时自动覆盖。检测：冲突必须标记待讨论
+4. **区分不清**：把可执行的skill混入方法论。检测：方法论是"认知性的"，skill是"可执行的"
+5. **忽略失败案例**：只提取成功经验。检测：踩坑教训同样有提取价值
+
+## 适用场景与边界
+- 适用：全流程完成后的自动扫描、practice-log积累到5条以上时、老板要求复盘时
+- 不适用：提取的是可执行skill（用skill-distiller）、与已有methodology冲突需人工裁决的
+
+## 示例
+**实践**：连续3个项目在设计阶段都因为"没考虑缓存策略"被打回
+**分析**：这是一个普遍适用的设计检查项，不是项目特有的
+**提取**：在 methodology/checklists/design.md 中新增检查项："缓存策略是否已考虑（适用于有数据读取的场景）"
+**证据**：practice-log #5, #8, #11