@chongyan/autospec 1.0.2 → 1.0.4

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

@@ -1,320 +0,0 @@
-# 自主修复原则 — 实战经验提炼
-
-> **定位**: 从自主修复机制实战中提炼的原则集合，补充到 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

@@ -1,220 +0,0 @@
-# 项目宪法 — 不可违反的红线清单
-
-> 宪法门禁（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 一次，确认条款仍然合理
-- 新增条款需说明来源（哪个事件/风险触发）