@chongyan/autospec 1.0.2 → 1.0.3

package/knowledge/03-guides/38-evaluate-ai-path.md

@@ -1,274 +0,0 @@
----
-name: ai-path-evaluator
-description: AI 分析执行路径，评估 SDD 引导效果
-type: review
----
-
-## 定位
-
-分析执行路径数据，评估 Spec-driven development (SDD) 的引导效果，识别框架改进机会。
-
-## 核心价值
-
-通过分析执行路径，量化评估框架是否有效引导 AI 按规范执行开发流程，为框架迭代提供数据支撑。
-
-## 输入
-
-- 必须输入：
-  - traceId: 流程追踪 ID
-  - executionPath: 执行路径数据
-- 可选输入：
-  - metrics: 质量指标数据
-  - frameworkRules: 框架规则定义
-
-## 评测维度
-
-### 1. 流程合规性 (权重 30%)
-
-评估执行路径是否符合框架定义的流程规范。
-
-**检查项**：
-- [ ] 阶段顺序是否正确（需求→设计→实现→测试→交付）
-- [ ] 必要阶段是否执行
-- [ ] 双层验证是否执行
-- [ ] 门禁检查是否通过
-
-**评分规则**：
-```javascript
-score = 100;
-// 阶段顺序违规扣分
-if (stageOrderViolation) score -= 20;
-// 缺失必要阶段扣分
-score -= missingStages.length * 15;
-// 未执行 Layer1 扣分
-if (!hasLayer1Execution) score -= 30;
-// 门禁阻止率影响
-score -= gateBlockedRate * 10;
-```
-
-### 2. 执行效率 (权重 25%)
-
-评估执行路径是否高效，识别浪费和重复。
-
-**检查项**：
-- [ ] 重复操作检测
-- [ ] 无效操作检测
-- [ ] 阶段耗时分析
-- [ ] 工具使用效率
-
-**评分规则**：
-```javascript
-score = 100;
-// 重复操作扣分
-score -= repeatedOperations.length * 5;
-// 回退次数扣分
-score -= rollbackCount * 5;
-// 工具调用效率
-efficiency = uniqueTools / totalToolCalls;
-score *= efficiency;
-```
-
-### 3. 决策质量 (权重 25%)
-
-评估决策点的合理性，反映框架的自主能力。
-
-**检查项**：
-- [ ] 人工介入必要性分析
-- [ ] 自动决策成功率
-- [ ] 决策类型分布
-
-**评分规则**：
-```javascript
-score = 100;
-// 人工介入率（越低越好）
-humanRate = humanDecisions / totalDecisions;
-score -= humanRate * 30;
-// 自动决策成功率
-score += autoDecisionSuccessRate * 20;
-```
-
-### 4. 异常处理 (权重 20%)
-
-评估异常情况处理是否得当。
-
-**检查项**：
-- [ ] 异常类型分布
-- [ ] 恢复成功率
-- [ ] 升级合理性
-
-**评分规则**：
-```javascript
-score = 100;
-// 恢复率加分
-score *= recoveryRate;
-// 升级率合理时不扣分
-if (escalateRate > 0.3) score -= 10;
-```
-
-## 输出格式
-
-```json
-{
-  "overallScore": 84,
-  "grade": "B",
-  "dimensions": {
-    "compliance": {
-      "score": 95,
-      "violations": [],
-      "strengths": ["阶段顺序正确", "双层验证完整"]
-    },
-    "efficiency": {
-      "score": 80,
-      "repeatedOps": 3,
-      "wastedOps": 1,
-      "suggestions": ["减少重复的 Read 操作"]
-    },
-    "decision": {
-      "score": 85,
-      "humanRate": 0.25,
-      "autoSuccessRate": 0.9,
-      "analysis": "人工介入主要集中在设计决策点"
-    },
-    "exception": {
-      "score": 75,
-      "recoveryRate": 0.8,
-      "escalateCount": 1,
-      "analysis": "大部分异常成功恢复"
-    }
-  },
-  "sddGuidanceEffect": {
-    "score": 82,
-    "analysis": "框架引导效果良好，AI 基本按规范执行",
-    "improvementAreas": [
-      "设计阶段的决策点可进一步自动化",
-      "减少重复操作的建议机制"
-    ]
-  },
-  "recommendations": [
-    {
-      "priority": "high",
-      "area": "efficiency",
-      "suggestion": "实现 Read 结果缓存，减少重复读取"
-    }
-  ]
-}
-```
-
-## 执行步骤
-
-### Step 1: 加载执行路径数据
-
-```
-1. 从 metrics.json 读取 executionPath
-2. 从 trace 日志读取详细事件
-3. 加载框架规则定义
-```
-
-### Step 2: 分析流程合规性
-
-```
-1. 检查阶段序列是否符合预期
-2. 检查必要阶段是否执行
-3. 检查双层验证执行情况
-4. 统计门禁通过/阻止情况
-```
-
-### Step 3: 分析执行效率
-
-```
-1. 检测重复操作（相同操作 >= 3 次）
-2. 检测无效操作（回退后的重做）
-3. 分析工具调用分布
-4. 计算效率指标
-```
-
-### Step 4: 分析决策质量
-
-```
-1. 统计决策类型分布
-2. 分析人工介入必要性
-3. 评估自动决策成功率
-4. 识别可自动化的决策点
-```
-
-### Step 5: 分析异常处理
-
-```
-1. 统计异常类型分布
-2. 计算恢复成功率
-3. 分析升级合理性
-4. 识别异常模式
-```
-
-### Step 6: 综合评估 SDD 引导效果
-
-```
-1. 汇总各维度评分
-2. 分析框架引导的成功点
-3. 识别需要改进的环节
-4. 生成改进建议
-```
-
-### Step 7: 输出报告
-
-```
-1. 输出结构化 JSON 结果
-2. 更新 metrics.json 的 pathEvaluation
-3. 触发进化机制（如有必要）
-```
-
-## SDD 引导效果评估标准
-
-| 分数范围 | 等级 | 引导效果 | 说明 |
-|---------|------|---------|------|
-| 90-100 | A | 优秀 | AI 完全按规范执行，极少人工介入 |
-| 80-89 | B | 良好 | AI 基本按规范执行，少量人工纠正 |
-| 70-79 | C | 一般 | AI 部分偏离规范，需要较多人工干预 |
-| 60-69 | D | 较差 | AI 经常偏离规范，人工干预频繁 |
-| <60 | F | 失败 | 框架引导失效，需要重新设计 |
-
-## 进化触发规则
-
-基于路径评测结果，自动触发进化机制：
-
-1. **合规性问题**：连续 3 次出现相同违规 → 更新 constitution 或 skill
-2. **效率问题**：重复操作模式出现 5 次 → 新增优化 skill
-3. **决策问题**：人工介入率 > 50% → 优化决策自动化
-4. **异常问题**：恢复率 < 60% → 增强异常处理机制
-
-## 与 metrics.json 的集成
-
-评估完成后，更新 metrics.json：
-
-```json
-{
-  "pathEvaluation": {
-    "compliance": { "score": 95, "violations": [] },
-    "efficiency": { "score": 80, "repeatedOps": 3 },
-    "decision": { "score": 85, "humanRate": 0.25 },
-    "exception": { "score": 75, "recoveryRate": 0.8 },
-    "overall": 84,
-    "evaluatedAt": "2026-03-24T10:00:00Z"
-  }
-}
-```
-
-## 适用场景
-
-- 流程结束时自动触发（Stop Hook）
-- 手动执行 `/evaluate`
-- 进化机制定期分析
-
-## 反模式清单 (DP7)
-
-1. **只看结果不看过程**：忽略执行路径中的细节
-   - 检测：必须分析具体事件序列
-
-2. **过度惩罚人工介入**：认为所有人工介入都是框架问题
-   - 检测：区分必要和非必要人工介入
-
-3. **忽略上下文**：不考虑任务复杂度
-   - 检测：结合任务复杂度调整评分标准
-
-4. **建议过于笼统**：没有具体可执行的改进建议
-   - 检测：每个建议必须指向具体的改进点

package/knowledge/03-guides/39-validate-ai-data.md

@@ -1,276 +0,0 @@
----
-name: data-validator
-description: 当项目包含数据开发组件（ETL、数据管道、数据仓库等）时，分析数据质量、验证数据完整性、提供数据分析支持。用于数据开发的稳定、安全、效果保障。
-type: ai
----
-
-## 定位
-
-AI专用技能。为数据开发提供质量验证、分析和挖掘支持，参考AI评测方法论到数据领域。
-
-## 输入
-
-- 必须输入：数据代码路径或项目目录、数据源配置
-- 可选输入：数据质量要求、验证规则
-
-## 输出
-
-```json
-{
-  "dataSystem": {
-    "type": "etl-pipeline",
-    "components": ["data-source", "transformation", "data-warehouse"],
-    "qualityRequirements": ["completeness", "accuracy", "timeliness"]
-  },
-  "validations": [
-    {
-      "dimension": "completeness",
-      "checks": ["null_check", "missing_value_check"],
-      "thresholds": {"null_rate": 0.05}
-    },
-    {
-      "dimension": "accuracy",
-      "checks": ["range_check", "format_check"],
-      "thresholds": {"error_rate": 0.01}
-    },
-    {
-      "dimension": "timeliness",
-      "checks": ["freshness_check", "delay_check"],
-      "thresholds": {"max_delay_hours": 24}
-    }
-  ],
-  "analysisSupport": {
-    "dataProfile": true,
-    "anomalyDetection": true,
-    "trendAnalysis": false
-  },
-  "tools": {
-    "suggested": ["great-expectations", "pandas-profiling", "dbt"],
-    "reason": "这些工具支持数据质量验证和分析"
-  }
-}
-```
-
-## 执行步骤
-
-### Step 1: 识别数据系统类型（确定性）
-
-基于依赖和代码特征识别数据系统：
-
-```
-数据系统识别规则：
-- dbt: 依赖dbt，代码中有 dbt run, dbt test
-- airflow: 依赖airflow，代码中有 DAG, Task
-- spark: 依赖pyspark，代码中有 SparkSession, DataFrame
-- pandas: 依赖pandas，代码中有 read_csv, read_excel
-- etl: 自定义ETL实现
-```
-
-### Step 2: Grep获取数据处理逻辑（高效）
-
-搜索数据处理模式：
-
-```bash
-# 数据读取
-grep -r -n -A 5 "read_csv\|read_excel\|load\|fetch" --include="*.py" .
-
-# 数据转换
-grep -r -n -A 5 "transform\|aggregate\|join\|filter" --include="*.py" .
-
-# 数据写入
-grep -r -n -A 5 "to_csv\|write\|save\|export" --include="*.py" .
-```
-
-### Step 3: 分析数据质量要求（模型）
-
-基于代码上下文分析数据质量要求：
-
-```
-关注点：
-- 数据源类型和可靠性
-- 数据转换逻辑
-- 数据质量检查点
-- 错误处理机制
-```
-
-### Step 4: 设计验证方案（模型）
-
-设计数据质量验证方案：
-
-```
-验证维度：
-1. 完整性：空值、缺失记录、重复数据
-2. 准确性：格式、范围、一致性
-3. 时效性：更新频率、延迟
-4. 唯一性：主键重复、外键关联
-5. 合法性：业务规则、数据约束
-```
-
-### Step 5: 输出结果
-
-汇总数据验证方案，包括验证规则、工具建议和实施计划。
-
-## 数据质量维度
-
-### 1. 完整性 (Completeness)
-
-| 检查项 | 指标 | 方法 |
-|--------|------|------|
-| 空值检查 | null_rate | 统计null/空字符串比例 |
-| 缺失记录 | missing_count | 对比预期记录数 |
-| 重复数据 | duplicate_rate | 检查主键重复 |
-
-### 2. 准确性 (Accuracy)
-
-| 检查项 | 指标 | 方法 |
-|--------|------|------|
-| 格式检查 | format_error_rate | 正则表达式验证 |
-| 范围检查 | range_error_rate | 数值范围验证 |
-| 一致性检查 | consistency_rate | 跨表一致性验证 |
-
-### 3. 时效性 (Timeliness)
-
-| 检查项 | 指标 | 方法 |
-|--------|------|------|
-| 新鲜度 | data_freshness | 数据更新时间 |
-| 延迟 | delay_hours | 数据延迟时间 |
-| 调度 | schedule_adherence | 调度执行情况 |
-
-### 4. 唯一性 (Uniqueness)
-
-| 检查项 | 指标 | 方法 |
-|--------|------|------|
-| 主键重复 | pk_duplicate_rate | 主键唯一性 |
-| 外键关联 | fk_violation_rate | 外键完整性 |
-
-### 5. 合法性 (Validity)
-
-| 检查项 | 指标 | 方法 |
-|--------|------|------|
-| 业务规则 | business_rule_violation | 业务规则验证 |
-| 数据约束 | constraint_violation | 约束检查 |
-
-## 数据分析支持
-
-### 数据分析维度
-
-| 维度 | 说明 | 工具 |
-|------|------|------|
-| **数据画像** | 数据的基本统计信息 | pandas-profiling, sweetviz |
-| **异常检测** | 识别异常数据点 | isolation-forest, z-score |
-| **趋势分析** | 数据随时间变化趋势 | pandas, matplotlib |
-| **相关性分析** | 变量间相关关系 | pandas, seaborn |
-| **分布分析** | 数据分布特征 | histogram, boxplot |
-
-### 数据挖掘支持
-
-| 任务 | 说明 | 适用场景 |
-|------|------|----------|
-| **特征工程** | 特征提取和转换 | 机器学习准备 |
-| **数据标注** | 标注数据生成 | AI模型训练 |
-| **数据增强** | 数据扩充 | 样本不足 |
-| **数据清洗** | 脏数据处理 | 质量提升 |
-
-## 数据验证工具
-
-### 开源工具
-
-| 工具 | 说明 | 特点 |
-|------|------|------|
-| **Great Expectations** | 数据质量验证 | 声明式验证规则 |
-| **Pandas Profiling** | 数据画像 | 自动生成报告 |
-| **Dbt** | 数据转换 | SQL式ETL |
-| **Great Expectations** | 数据测试 | 集成测试 |
-| **Soda** | 数据监控 | 主动监控 |
-
-### 验证规则模板
-
-```python
-# 完整性验证
-expect_column_values_to_not_be_null("email")
-expect_column_value_lengths_to_be_between("phone", 10, 15)
-expect_table_row_count_to_be_between("orders", 1000, 1000000)
-
-# 准确性验证
-expect_column_values_to_match_regex("email", ".*@.*\\..*")
-expect_column_values_to_be_between("price", 0, 10000)
-expect_column_values_to_be_in_set("status", ["active", "inactive"])
-
-# 唯一性验证
-expect_column_values_to_be_unique("user_id")
-expect_compound_columns_to_be_unique(["order_id", "line_item_id"])
-```
-
-## 调用时机
-
-- 检测到数据系统组件时
-- 数据管道开发阶段
-- 数据质量保障需求
-- 数据分析需求
-
-## 示例
-
-**输入**：
-```
-项目目录：/project
-数据系统：dbt + snowflake
-数据源：用户行为数据
-```
-
-**Grep搜索**：
-```
-找到文件：models/users.sql, tests/schema_test.yml
-```
-
-**代码上下文**：
-```sql
--- models/users.sql
-SELECT
-    user_id,
-    email,
-    created_at,
-    status
-FROM raw_users
-WHERE status = 'active'
-```
-
-**输出**：
-```json
-{
-  "dataSystem": {
-    "type": "dbt-pipeline",
-    "components": ["raw_users", "users_model"],
-    "qualityRequirements": ["completeness", "accuracy"]
-  },
-  "validations": [
-    {
-      "dimension": "completeness",
-      "checks": ["not_null", "unique"],
-      "fields": ["user_id", "email"],
-      "thresholds": {"null_rate": 0}
-    },
-    {
-      "dimension": "accuracy",
-      "checks": ["valid_email", "valid_status"],
-      "fields": ["email", "status"],
-      "thresholds": {"error_rate": 0.01}
-    }
-  ],
-  "tools": {
-    "suggested": ["dbt-utils", "great-expectations"],
-    "reason": "与dbt集成良好"
-  }
-}
-```
-
-## 与AI评测的类比
-
-将AI评测方法论应用到数据开发：
-
-| AI评测 | 数据开发 | 说明 |
-|--------|----------|------|
-| 任务完成率 | 数据完整率 | 数据是否完整 |
-| 工具使用正确性 | 转换逻辑正确性 | ETL逻辑是否正确 |
-| 响应质量 | 数据准确性 | 数据是否准确 |
-| 基础设施噪声 | 数据源波动 | 源数据质量问题 |
-| AI-resistant评估 | 数据一致性验证 | 防止数据泄露 |