@chongyan/autospec 1.0.1 → 1.0.3

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

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

@@ -1,234 +0,0 @@
-# 环境知识生成器
-
-## 功能
-
-根据检测到的中间件/组件，生成完整的环境知识配置。包括连接配置模板、最佳实践建议、反模式警告。
-
-## 触发条件
-
-- 检测到新的中间件或组件
-- 需要生成环境知识配置
-- 用户请求添加组件知识
-
-## 输入
-
-```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

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