@chongyan/autospec 1.0.1 → 1.0.2

package/knowledge/01-principles/08-auto-fix-principles.md

@@ -0,0 +1,320 @@
+# 自主修复原则 — 实战经验提炼
+
+> **定位**: 从自主修复机制实战中提炼的原则集合，补充到 principle-hierarchy.md
+>
+> **版本**: v1.0
+> **最后更新**: 2026-03-27
+> **来源**: 自主修复机制实战经验
+
+---
+
+## 一、核心洞察
+
+### 洞察 1: 框架缺乏自主修复能力是系统性失败
+
+**问题现象**:
+- 遇到任何错误就标记 BLOCKED 等待人工
+- 依赖缺失需要人工添加 pom.xml
+- 配置错误需要人工修正
+
+**根因分析**:
+- 框架设计时未将"自主修复"作为核心能力
+- 错误处理机制停留在"检测→报告"层面
+- 缺少"检测→分析→决策→执行→验证"的闭环
+
+**解决原则**:
+> **框架必须具备"分析→决策→执行→验证"的自主闭环能力**
+
+### 洞察 2: 自主修复必须有明确的边界
+
+**问题现象**:
+- AI 可能修改宪法文件
+- AI 可能改变架构决策
+- AI 可能引入安全风险
+
+**根因分析**:
+- 未定义修复边界
+- 未区分错误类型
+- 未设置停线条件
+
+**解决原则**:
+> **修复边界必须明确：冻结区/受控区/自由区**
+
+### 洞察 3: 优先复用项目现有能力是 Brownfield 适配的关键
+
+**问题现象**:
+- AI 倾向于新建代码而非复用现有代码
+- AI 硬编码路径、包名、类名
+- AI 不考虑项目已有的 AOP 框架、Helper 工具
+
+**根因分析**:
+- 未在规范中明确约束
+- 未提供扫描和复用的具体方法
+- AI 倾向于"从零实现"而非"搜索复用"
+
+**解决原则**:
+> **修复/实现前必须扫描项目现有能力，优先复用而非新建**
+
+---
+
+## 二、原则体系
+
+### AFP1: 修复循环原则 (Auto-Fix Loop Principle)
+
+**核心内容**:
+```
+检测障碍 → 分析根因 → 决策策略 → 执行修复 → 验证结果
+    ↑                                      │
+    └──────────── 最多 3 次循环 ─────────────┘
+```
+
+**错误分类**:
+| 错误类型 | 自主修复策略 | 示例 |
+|---------|------------|------|
+| 依赖类 | 自动添加/安装 | 缺少 npm/Maven 包 |
+| 配置类 | 自动修正配置 | 配置文件错误 |
+| 代码类 | 自动修正代码 | 语法错误、类型错误 |
+| 资源类 | 自动创建/下载 | 文件缺失、目录不存在 |
+| 验证类 | 自动重试/修正 | 测试失败、编译错误 |
+| 逻辑类 | 需人工确认 | 业务逻辑错误、需求歧义 |
+
+**追溯关系**:
+- 上游: L1-P1 验证为王、L3-T3 精准回退
+- 下游: L4-auto-fix-loop 自主修复机制
+
+### AFP2: 修复边界原则 (Repair Boundary Principle)
+
+**核心内容**:
+| 区域 | 内容 | 修复方式 |
+|------|------|---------|
+| 冻结区 | 宪法文件、核心原则 | 不可自主修改，直接 BLOCKED |
+| 受控区 | 框架核心机制、接口契约 | 需人工批准，生成修复提案 |
+| 自由区 | 依赖添加、配置修正、语法错误 | 可自主修复，修复后验证 |
+
+**停线条件**:
+- 检测到安全漏洞
+- 检测到数据丢失风险
+- 同一问题修复 3 次仍未通过
+- 宪法门禁检查不通过
+- AI 自我判断置信度极低
+
+**追溯关系**:
+- 上游: L1-P3 渐进自主、L2-S4 知情猜测
+- 下游: L4-constitution 宪法门禁
+
+### AFP3: 优先复用原则 (Reuse-First Principle)
+
+**核心内容**:
+
+**修复/实现前必须扫描**:
+1. 扫描项目已有的 AOP 框架、Helper 工具类、Util 类
+2. 扫描 environment 知识文件，了解项目使用的中间件和组件
+3. 识别项目已有的技术选型和架构模式
+
+**禁止硬编码**:
+- 不可在代码中硬编码目录名、包名、类名、配置项
+- 必须从环境知识文件、配置文件中动态读取
+- 支持不同项目的差异化配置
+
+**复用优先于新建**:
+- 项目已有 AOP 框架 → 使用 AOP 切面方式，不手动埋点
+- 项目已有 Helper 工具 → 调用 Helper 方法，不重复实现
+- 项目已有 Util 类 → 使用 Util 工具，不自己造轮子
+
+**违反示例**（禁止行为）:
+- ❌ 项目已有 `AgentTracingHelper`，却自己新建一个埋点类
+- ❌ 项目已有 AOP 切面模式，却直接在业务代码中硬编码埋点
+- ❌ 在代码中硬编码 `pom.xml`、`src/main/java` 等路径
+- ❌ 项目已有 `LogUtil`，却直接使用 `logger.info()`
+- ❌ 不考虑项目已有的技术栈，直接引入新的依赖
+
+**遵守示例**（推荐行为）:
+- ✅ 先读取 `knowledge/06-environment/` 了解项目技术栈
+- ✅ 先搜索代码库是否有类似的 Helper/Util/AOP 实现
+- ✅ 复用项目已有的 `AgentTracingHelper`、`LogUtil` 等工具类
+- ✅ 使用项目已有的 AOP 切面模式进行埋点
+- ✅ 从配置文件或环境知识中动态读取路径和配置
+
+**追溯关系**:
+- 上游: L1-P2 极简实用、L2-S3 Harness Engineering
+- 下游: L4-coding-style 编码规范 0.1/0.2 节
+
+### AFP4: 设计原则约束原则 (Design Principles Constraint)
+
+**核心内容**:
+
+自主修复过程中，必须遵循以下面向对象设计原则：
+
+#### 修复流程原则
+- **P1: 优先复用项目现有能力** — 修复前先扫描项目已有能力
+- **P2: 禁止硬编码** — 从环境知识文件动态读取配置
+- **P3: 先搜索后实现** — 先搜索代码库，再决定实现方式
+
+#### 面向对象设计原则（通用）
+| 原则 | 核心要求 |
+|------|---------|
+| 单一职责 (SRP) | 一个类只负责一项职责 |
+| 开闭原则 (OCP) | 对扩展开放，对修改关闭 |
+| 里氏替换 (LSP) | 子类必须能够替换其父类 |
+| 依赖倒置 (DIP) | 面向接口编程，不依赖具体实现 |
+| 接口隔离 (ISP) | 使用多个专门的接口 |
+| 迪米特法则 | 只与直接的朋友通信 |
+| 合成/复用 | 优先使用组合/聚合 |
+| 高内聚低耦合 | 模块内聚，模块间松耦合 |
+| AOP 优先 | 跨切面功能优先使用 AOP 切面 |
+
+**追溯关系**:
+- 上游: L1-P2 极简实用、L3-T6 优先复用
+- 下游: L4-coding-style 编码规范 0.3 节/第 11 章
+
+### AFP5: 重试上限原则 (Retry Limit Principle)
+
+**核心内容**:
+- 同一问题最多自主修复 **3 次**
+- 3 次后仍未通过 → 升级人工，记录到 `practice-log`
+- 每次重试必须记录：问题、根因、修复方案、验证结果
+
+**追溯关系**:
+- 上游: L1-P1 验证为王、L3-T3 精准回退
+- 下游: L4-constitution 宪法门禁、L4-auto-fix-loop
+
+### AFP6: 实践日志原则 (Practice Log Principle)
+
+**核心内容**:
+
+每次自主修复都必须记录到 practice-log：
+
+```markdown
+## [日期] 自主修复记录
+
+**问题**: [问题描述]
+**根因**: [根因分析]
+**修复方案**: [修复措施]
+**验证结果**: [验证输出]
+**分类**: [错误类型]
+**区域**: [修复区域]
+**重试次数**: [x/3]
+```
+
+**追溯关系**:
+- 上游: L1-P1 验证为王、L3-进化机制
+- 下游: L4-evolution 自进化机制
+
+---
+
+## 三、原则应用矩阵
+
+### 3.1 按错误类型应用原则
+
+| 错误类型 | 应用原则 | 处理流程 |
+|---------|---------|---------|
+| **依赖缺失** | AFP1 修复循环、AFP3 优先复用 | 扫描现有依赖 → 自动安装 → 验证 → 记录 |
+| **配置错误** | AFP1 修复循环、AFP2 修复边界 | 分析配置 → 判断区域 → 修正 → 验证 |
+| **代码错误** | AFP1 修复循环、AFP4 设计原则 | 诊断 → 修复（遵循 SOLID）→ 重验证 |
+| **资源缺失** | AFP1 修复循环、AFP2 修复边界 | 创建目录/文件 → 验证 |
+| **测试失败** | AFP1 修复循环、AFP5 重试上限 | 分析失败 → 修复 → 重测（最多 3 次） |
+| **逻辑错误** | AFP2 修复边界 | 受控区 → 生成提案 → 人工确认 |
+| **安全风险** | AFP2 修复边界 | 冻结区 → 立即停线 → 升级人工 |
+
+### 3.2 原则追溯链示例
+
+**场景 1**: Maven 依赖缺失
+
+```
+错误发生：package com.enterprise.tracer does not exist
+    ↓
+AFP1 修复循环 → 错误分类（依赖类）
+    ↓
+AFP3 优先复用 → 扫描现有 pom.xml，查找是否有类似依赖
+    ↓
+修复执行：添加缺失的 Maven 依赖
+    ↓
+验证结果：重新执行 mvn compile
+    ↓
+AFP5 重试上限 → 验证通过，循环结束
+    ↓
+AFP6 实践日志 → 记录修复过程
+```
+
+**场景 2**: 代码硬编码路径
+
+```
+代码审查发现：String path = "/Users/chenjianzeng/Code/autospec/";
+    ↓
+AFP3 优先复用 → 违反"禁止硬编码"原则
+    ↓
+AFP4 设计原则 → 违反"依赖倒置"原则
+    ↓
+修复执行：从配置文件读取路径
+    ↓
+验证结果：重新执行代码审查
+    ↓
+AFP6 实践日志 → 记录违规和修复过程
+```
+
+**场景 3**: 重复造轮子
+
+```
+代码审查发现：新建了 MyTracingHelper，但项目已有 AgentTracingHelper
+    ↓
+AFP3 优先复用 → 违反"优先复用项目现有能力"原则
+    ↓
+修复执行：删除新建类，改用已有类
+    ↓
+验证结果：重新执行代码审查
+    ↓
+AFP6 实践日志 → 记录违规和修复过程
+```
+
+---
+
+## 四、原则检查清单
+
+### 4.1 修复前检查
+
+- [ ] 已扫描项目现有的框架、组件、工具类
+- [ ] 已扫描 environment 知识文件
+- [ ] 已识别项目已有的技术选型和架构模式
+- [ ] 已判断修复区域（冻结区/受控区/自由区）
+- [ ] 已分析错误类型（依赖/配置/代码/资源/验证/逻辑）
+
+### 4.2 修复中检查
+
+- [ ] 遵循优先复用原则（不重复造轮子）
+- [ ] 遵循禁止硬编码原则（从配置读取）
+- [ ] 遵循设计原则约束（SOLID+DDD+AOP）
+- [ ] 遵循修复循环流程（分析→决策→执行→验证）
+- [ ] 遵循重试上限原则（最多 3 次）
+
+### 4.3 修复后检查
+
+- [ ] 已验证修复结果（重新执行原命令）
+- [ ] 已记录实践日志（问题/根因/修复/验证）
+- [ ] 已更新相关文档（如需要）
+- [ ] 已提炼经验教训（如需要）
+
+---
+
+## 五、与 principle-hierarchy.md 的映射
+
+| 本文档章节 | 对应 principle-hierarchy.md 章节 | 说明 |
+|-----------|-------------------------------|------|
+| AFP1 修复循环 | L3-T3 精准回退、L4-O2 自主修复 | 修复循环流程 |
+| AFP2 修复边界 | L2-S4 知情猜测、L4-O3 宪法门禁 | 修复区域划分 |
+| AFP3 优先复用 | L3-T6 优先复用项目现有能力 | Brownfield 适配 |
+| AFP4 设计原则 | L4-O1 编码规范 0.3 节/第 11 章 | SOLID+DDD |
+| AFP5 重试上限 | L2-宪法#8、L3-T3 精准回退 | 最多 3 次循环 |
+| AFP6 实践日志 | L3-进化机制、L4-evolution | 经验沉淀 |
+
+---
+
+**维护者**: AutoSpec 团队
+**反馈渠道**: 知识库 Git 仓库 Issue
+**关联文档**:
+- [00-principles-hierarchy.md](00-principles-hierarchy.md) - 原则体系总纲
+- [01-first-principles.md](01-first-principles.md) - L1 第一性原则
+- [02-strategic-principles.md](02-strategic-principles.md) - L2 战略原则
+- [03-tactical-principles.md](03-tactical-principles.md) - L3 战术原则
+- [04-operational-principles.md](04-operational-principles.md) - L4 操作原则
+- [09-constitution.md](09-constitution.md) - 项目宪法
+- `knowledge/07-standards/00-coding-style.md` - 编码规范

package/knowledge/01-principles/09-constitution.md

@@ -0,0 +1,220 @@
+# 项目宪法 — 不可违反的红线清单
+
+> 宪法门禁（DP10）：自动检查，违反任何一条立即停止全流程。
+>
+> **版本**: v2.0
+> **最后更新**: 2026-03-27
+> **基于**: 业界风险防范基本条例、核心原则
+
+## 安全红线
+
+1. **不可逆动作必须人工确认**
+   - 数据库迁移（DDL 变更）
+   - 生产环境部署
+   - 外部 API 发送（邮件、短信、支付等）
+   - 数据删除（DELETE/TRUNCATE）
+   - 分支强制推送
+
+2. **敏感信息不可硬编码**
+   - 密钥、密码、Token 不可出现在代码中
+   - 生产环境配置不可出现在代码仓库中
+   - 用户隐私数据不可出现在日志中
+
+3. **安全漏洞零容忍**
+   - SQL 注入
+   - XSS（跨站脚本）
+   - CSRF（跨站请求伪造）
+   - 越权访问
+   - 未加密传输敏感数据
+
+## 流程红线
+
+4. **启动门禁不可跳过**
+   - 收到开发/建设类任务时，必须先执行启动协议（读 pipeline→读宪法→确认范围）
+   - 禁止跳过需求分析直接写代码
+   - "全流程自动化"≠"跳过流程"，而是"按框架自动推进各阶段"
+
+5. **Layer 1 不过不进 Layer 2**
+   - 确定性验证（编译/测试/lint）失败时，禁止进入 AI 审查
+   - 测试红灯时，禁止声明代码完成
+
+6. **Layer 1 必须真实执行**
+   - 禁止用"静态分析评估"替代真实执行来声称 Layer 1 通过
+   - 无法执行 → 标记为 BLOCKED，不是 PASSED
+   - BLOCKED → 先解决环境问题，或降级为 experiment 模式
+   - Layer 1 结果必须附带真实执行日志
+
+7. **做审必须分离**
+   - 做类 skill 和审类 skill 必须由不同 AI 实例执行
+   - 审查必须通过 Agent 工具启动独立子进程，实现信息隔离
+   - 禁止同一上下文中切换角色冒充分离
+
+8. **回退上限 3 次**
+   - 同一问题修正循环超过 3 次必须升级人工
+   - 禁止无限循环修复
+
+9. **关键假设必须显式记录**
+   - 每个阶段的关键假设必须写入文件
+   - 阶段间传递时必须校验假设一致性
+   - 待确认假设超过 3 个必须升级人工
+
+## 决策红线
+
+10. **方向性决策必须人工确认**
+    - 需求方向和范围变更
+    - 架构重大变更（如单体→微服务）
+    - 安全敏感决策
+    - 新技术引入
+    - 自动模式下：标记为 REQUIRE_REVIEW + pendingConfirmations，不阻塞但不执行
+
+11. **知情猜测有上限**
+    - 最多 3 个 NEEDS CLARIFICATION 标记
+    - 其余做合理默认但不可隐藏假设
+
+## 执行模式红线
+
+> 自动模式（unattended）不降低安全标准，只改变确认方式。
+
+- **以下红线在自动模式下不可降级**（两种模式同等执行）：
+  - 安全红线（#1-#3）全部生效
+  - Layer 1 真实执行（#5-#6）全部生效
+  - 做审分离（#7）全部生效
+  - 数据完整性（#12）全部生效
+  - 部署可回滚（#13）全部生效
+  - 安全审计结论为"不安全" → 两种模式都阻止执行
+- **以下确认行为在自动模式下可降级为记录**：
+  - 不可逆动作确认（#1）→ 生成方案但不执行，记录 pendingConfirmations
+  - 阶段产出确认（#4 流程中的人工确认点）→ 使用 stage-gate Agent 替代
+  - 方向性决策确认（#10）→ 使用推荐值，标记 REQUIRE_REVIEW
+  - 待确认假设升级（#9）→ 记录但不阻塞，标记 HIGH_PRIORITY_REVIEW
+- **自动模式完成后，pendingConfirmations 中的所有项必须在下次交互中向用户展示**
+
+## 数据红线
+
+12. **数据完整性不可妥协**
+    - 禁止跳过数据校验
+    - 禁止未经验证的数据格式转换
+    - 禁止金额使用浮点数运算（必须使用 Money 类或 BigDecimal）
+    - 禁止 SELECT * 查询（必须指定列名）
+    - 禁止使用 ${} 进行 SQL 拼接（必须使用 #{} 参数化查询）
+
+## 运维红线
+
+13. **部署必须可回滚**
+    - 每次部署必须有回滚方案
+    - 回滚方案必须经过验证
+    - 禁止"只能前进不能后退"的部署
+
+14. **监控与日志规范**
+    - 关键业务节点必须打印日志（使用 LogUtil，带 TraceId）
+    - 禁止直接使用 logger 打印（无 TraceId，无法链路追踪）
+    - 禁止空 catch 块（异常必须记录日志并处理）
+    - 异步方法必须捕获异常（防止异常吞掉）
+    - 必须考虑三板斧：灰度、监控、应急
+
+15. **并发控制**
+    - 更新数据前必须加锁（一锁二判三更新原则）
+    - 禁止使用无界线程池（队列长度建议≤100）
+    - ThreadLocal 使用完毕后必须调用 remove() 清理
+
+## 停线条件
+
+以下任一条件成立 → 立即停止全流程，等待人工处理：
+- 检测到安全漏洞（上述第 3 条）
+- 检测到数据丢失风险
+- 同一问题修复 3 次仍未通过（自主修复循环上限）
+- 宪法门禁检查不通过
+- AI 自我判断置信度极低（无法给出合理默认值）
+
+## 自主修复机制（Auto-Fix Loop）
+
+> 框架具备"分析→决策→执行→验证"的自主闭环能力，适用于任何项目或事项。
+
+### 修复循环流程
+
+```
+检测障碍 → 分析根因 → 决策策略 → 执行修复 → 验证结果
+    ↑                                      │
+    └──────────── 最多 3 次循环 ─────────────┘
+```
+
+### 错误分类与修复策略
+
+| 错误类型 | 自主修复策略 | 示例 |
+|---------|------------|------|
+| **依赖类** | 自动添加/安装 | 缺少 npm/Maven 包、工具缺失 |
+| **配置类** | 自动修正配置 | 配置文件错误、环境变量缺失 |
+| **代码类** | 自动修正代码 | 语法错误、类型错误、导入缺失 |
+| **资源类** | 自动创建/下载 | 文件缺失、目录不存在 |
+| **验证类** | 自动重试/修正 | 测试失败、编译错误 |
+| **逻辑类** | 需人工确认 | 业务逻辑错误、需求歧义 |
+
+### 自主修复边界
+
+**冻结区（不可自主修改）**
+- 宪法文件 (`constitution.md`, `evolution.md`)
+- 核心设计原则
+- 用户明确锁定的文件
+
+**受控区（需人工批准）**
+- 框架核心机制修改
+- 接口契约变更
+- 跨系统依赖变更
+- 方向性决策（需求范围、架构变更）
+
+**自由区（可自主修复）**
+- 依赖添加/版本升级
+- 配置文件修正
+- 代码语法/类型错误
+- 测试文件修复
+- 环境问题（缺失的工具/目录）
+
+### 自主修复原则（必须遵循）
+
+自主修复过程中，必须遵循以下原则：
+
+#### 修复流程原则
+
+**P1: 优先复用项目现有能力**
+- 修复前必须先扫描项目已有的框架、组件、工具类
+- 优先使用项目已有的 AOP、Helper、Util 等基础设施
+- 禁止重复造轮子 —— 项目已有类似实现时，必须复用或扩展
+- 新增代码必须符合项目已有的代码风格和架构模式
+
+**P2: 禁止硬编码**
+- 不可在代码中硬编码目录名、包名、类名、配置项等
+- 必须从环境知识文件、配置文件中动态读取
+- 支持不同项目的差异化配置
+
+**P3: 先搜索后实现**
+- 实现任何功能前，先搜索代码库是否已有类似实现
+- 有 → 复用或扩展；无 → 按已有代码的模式和风格实现
+
+#### 面向对象设计原则（通用）
+
+> 以下原则为软件工程的通用设计原则，适用于所有设计、编码和修复场景。
+> 详细说明和代码示例见：`knowledge/07-standards/00-coding-style.md` 第 11 节
+
+| 原则 | 核心要求 |
+|------|---------|
+| **单一职责 (SRP)** | 一个类只负责一项职责，只有一个引起它变化的原因 |
+| **开闭原则 (OCP)** | 对扩展开放，对修改关闭 |
+| **里氏替换 (LSP)** | 子类必须能够替换其父类，程序行为不变 |
+| **依赖倒置 (DIP)** | 面向接口编程，不依赖具体实现 |
+| **接口隔离 (ISP)** | 使用多个专门的接口，不使用单一的总接口 |
+| **迪米特法则** | 只与直接的朋友通信，不与"陌生人"交谈（最少知道原则） |
+| **合成/复用** | 优先使用组合/聚合，其次才是继承 |
+| **高内聚低耦合** | 模块内聚，模块间松耦合，变化点封装隔离 |
+| **AOP 优先** | 跨切面功能优先使用 AOP 切面方式，不侵入业务代码 |
+
+### retryCount 上限
+
+- 同一问题最多自主修复 **3 次**
+- 3 次后仍未通过 → 升级人工，记录到 `practice-log`
+
+## 宪法修订规则
+
+- 本宪法的修改必须人工审批
+- AI 不可自行修改或绕过宪法条款
+- 每季度 review 一次，确认条款仍然合理
+- 新增条款需说明来源（哪个事件/风险触发）