@chongyan/autospec 1.0.2 → 1.0.3

package/knowledge/01-principles/04-operational-principles.md

@@ -1,275 +0,0 @@
-# L4: 操作原则
-
-> **定位**: 战术原则的具体落地，包含明确的行为规范和检查清单
->
-> **进化分区**: 🟡 受控区（自动提议 + 人工批准）
-
----
-
-## 一、原则体系
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  L4: 操作原则 (Operational Principles)                        │
-│  ─────────────────────────────────────────────────────────  │
-│  源自 L3 战术原则，指导具体行为规范                           │
-│                                                              │
-│  O1 编码规范 | O2 自主修复 | O3 宪法门禁 | O4 检查清单        │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 追溯关系
-
-```
-L3 战术原则              L4 操作原则
-─────────────────      ──────────────────
-T6 优先复用      ────→   O1 编码规范
-T3 精准回退      ────→   O2 自主修复
-T5 驯服非确定性  ────→   O3 宪法门禁
-T4 反模式预判    ────→   O4 检查清单
-```
-
----
-
-## 二、O1: 编码规范 (Coding Style)
-
-> **源自**: T6 优先复用项目现有能力
->
-> **核心章节**: 详见 `knowledge/07-standards/00-coding-style.md`
-
-### 1.1 核心原则
-
-**复用优先与禁止硬编码**:
-- 实现前先扫描项目现有能力
-- 优先使用项目已有的 Helper、Util 类
-- 按已有代码的模式和风格实现
-- 禁止硬编码目录名、包名、类名、配置项
-
-**一锁二判三更新**（并发场景）:
-```
-1. 一锁：锁定单点资源（单条记录）
-2. 二判：基于锁定的记录最新状态，判断状态、数值
-3. 三更新：判断通过后的处理
-```
-
-**异步异常处理**:
-- 异步方法中必须捕获和处理异常
-- 禁止吞掉异常
-- 使用带返回值的 AsyncResult，上层通过 get() 捕获异常
-
-**ThreadLocal 清理**:
-- 使用完毕后必须在 finally 中调用 remove() 清理
-- 禁止使用 `set(null)` 替代 `remove()`
-
-**LogUtil 优先**:
-- 日志打印必须使用 LogUtil 工具类
-- 自动添加 TraceId
-- 禁止直接使用 logger 或 System.out
-
-### 1.2 SOLID+DDD 原则
-
-| 原则 | 说明 | 应用 |
-|------|------|------|
-| **S**RP 单一职责 | 一个类只有一个职责 | 类设计 |
-| **O**CP 开闭原则 | 对扩展开放，对修改关闭 | 架构设计 |
-| **L**SP 里氏替换 | 子类可替换父类 | 继承设计 |
-| **I**SP 接口隔离 | 客户端不应依赖不需要的接口 | 接口设计 |
-| **D**IP 依赖倒置 | 依赖抽象，不依赖具体 | 依赖管理 |
-
-**DDD 战术设计**:
-- 统一语言：代码命名与业务术语一致
-- 聚合设计：小聚合优于大聚合
-- 领域事件：事件命名用过去时，一旦发生不可修改
-- 充血模型：核心业务逻辑内聚到领域对象
-
-### 1.3 追溯关系
-
-- **上游**: T6 优先复用、T5 驯服非确定性
-- **下游**: `knowledge/07-standards/00-coding-style.md`
-
----
-
-## 三、O2: 自主修复机制 (Auto-Fix Loop)
-
-> **源自**: S1 双层验证 + T3 精准回退
->
-> **核心规则**: 分析→决策→执行→验证，最多 3 次循环
-
-### 3.1 修复循环流程
-
-```
-检测障碍 → 分析根因 → 决策策略 → 执行修复 → 验证结果
-    ↑                                      │
-    └──────────── 最多 3 次循环 ─────────────┘
-```
-
-### 3.2 错误分类与修复策略
-
-| 错误类型 | 自主修复策略 | 示例 |
-|---------|------------|------|
-| **依赖类** | 自动添加/安装 | 缺少 npm/Maven 包 |
-| **配置类** | 自动修正配置 | 配置文件错误 |
-| **代码类** | 自动修正代码 | 语法错误、类型错误 |
-| **资源类** | 自动创建/下载 | 文件缺失、目录不存在 |
-| **验证类** | 自动重试/修正 | 测试失败、编译错误 |
-| **逻辑类** | 需人工确认 | 业务逻辑错误、需求歧义 |
-
-### 3.3 修复边界（进化分区）
-
-| 区域 | 内容 | 修复方式 |
-|------|------|---------|
-| 🔴 **冻结区** | 宪法文件、核心原则 | 不可自主修改，直接 BLOCKED |
-| 🟡 **受控区** | 框架核心机制、接口契约 | 需人工批准，生成修复提案 |
-| 🟢 **自由区** | 依赖添加、配置修正、语法错误 | 可自主修复，修复后验证 |
-
-### 3.4 三级修复循环
-
-```
-Level 内联重试:
-  生成失败立即单次重试
-
-Level 修正循环:
-  结构化诊断反馈 → 定向修复 → 重验证（最多 3 次）
-
-Level 人工升级:
-  提交 3 次产出 + 3 次诊断 + AI 的"为什么反复不过"分析
-```
-
-### 3.5 追溯关系
-
-- **上游**: S1 双层验证、T3 精准回退、P1 验证为王
-- **下游**: `knowledge/01-principles/08-auto-fix-principles.md`
-
----
-
-## 四、O3: 宪法门禁 (Constitution Gate)
-
-> **源自**: P1 验证为王 + P3 渐进自主 + S1 双层验证
->
-> **核心规则**: 15 条红线，违反即停线
-
-### 4.1 安全红线（不可违反）
-
-| 红线 | 说明 | 违反信号 |
-|------|------|---------|
-| #1 不可逆动作人工确认 | DB 迁移、生产部署、外部 API 调用 | 未经人工确认就执行 |
-| #2 敏感信息不硬编码 | 密钥、密码、Token | 代码中出现明文秘钥 |
-| #3 安全漏洞零容忍 | SQL 注入、XSS、CSRF、越权 | 检测到安全漏洞 |
-
-### 4.2 流程红线（必须执行）
-
-| 红线 | 说明 | 违反信号 |
-|------|------|---------|
-| #4 启动门禁不跳过 | 读 pipeline→读宪法→确认范围 | 未确认就直接开始 |
-| #5-6 Layer 1 真实执行 | 编译/测试/lint 必须真实执行 | 用静态分析替代真实执行 |
-| #7 做审必须分离 | 不同 AI 实例执行 | 同一上下文切换角色 |
-| #8 回退上限 3 次 | 同一问题最多修复 3 次 | 超过 3 次继续修复 |
-| #9 关键假设显式记录 | 假设必须写在文件中 | 假设留在对话中 |
-
-### 4.3 决策红线
-
-| 红线 | 说明 | 违反信号 |
-|------|------|---------|
-| #10 方向性决策人工确认 | 需求方向、架构重大变更 | AI 自主决定方向 |
-| #11 知情猜测有上限 | 最多 3 个 NEEDS CLARIFICATION | 超过 3 个不确定项 |
-
-### 4.4 停线条件（立即停止）
-
-检测到以下情况必须停止全流程：
-- 安全漏洞（SQL 注入、XSS、凭证泄露）
-- 数据丢失风险
-- 测试覆盖率低于阈值
-- 编译错误无法在 3 次内修复
-- AI 自我判断置信度极低
-
-### 4.5 追溯关系
-
-- **上游**: P1 验证为王、P3 渐进自主、S1 双层验证
-- **下游**: `knowledge/01-principles/09-constitution.md`
-
----
-
-## 五、O4: 检查清单 (Checklists)
-
-> **源自**: T4 反模式预判 + S1 双层验证
->
-> **核心规则**: 5 阶段清单，嵌入式自检
-
-### 5.1 各阶段检查清单
-
-| 阶段 | 检查清单文件 | 核心检查项 |
-|------|-------------|-----------|
-| **需求分析** | `checklists/requirement.md` | 必填章节、业务完整性、技术可行性 |
-| **方案设计** | `checklists/design.md` | 两步生成、设计质量、架构规范 |
-| **编码实现** | `checklists/code.md` | Layer 1 验证、编码规范、代码质量 |
-| **测试** | `checklists/test.md` | 测试策略、覆盖率、边界场景 |
-| **发布** | `checklists/release.md` | 前置检查、回滚方案、监控告警 |
-
-### 5.2 检查清单设计原则
-
-**嵌入式自检**:
-- 检查清单嵌入到产出模板中
-- 生产者完成后必须先自检
-- 审查者独立检查
-
-**强制字段**:
-- 不填 = schema 校验不通过
-- 不确定性标记（`[NEEDS CLARIFICATION]`，最多 3 个）
-
-### 5.3 追溯关系
-
-- **上游**: T4 反模式预判、S1 双层验证
-- **下游**: `knowledge/04-checklists/` 各阶段清单
-
----
-
-## 六、原则应用矩阵
-
-### 6.1 按错误类型应用
-
-| 错误类型 | 应用原则 | 处理方式 |
-|---------|---------|---------|
-| **代码规范问题** | O1 编码规范 | 按 coding-style 修正 |
-| **编译/测试失败** | O2 自主修复 | 诊断→修复→验证（最多 3 次） |
-| **安全红线违反** | O3 宪法门禁 | 立即停线→升级人工 |
-| **阶段完成遗漏** | O4 检查清单 | 补全检查项→自检通过 |
-
-### 6.2 原则检查清单
-
-**编码实现前**:
-- [ ] 已扫描项目现有能力（O1）
-- [ ] 已了解项目技术栈（O1）
-- [ ] 已准备必要的知识（O1）
-
-**编码实现中**:
-- [ ] 遵守一锁二判三更新（O1）
-- [ ] 使用 LogUtil 打印日志（O1）
-- [ ] 禁止硬编码（O1）
-- [ ] 遵守 SOLID+DDD 原则（O1）
-
-**遇到错误时**:
-- [ ] 执行自主修复流程（O2）
-- [ ] 修复循环不超过 3 次（O2）
-- [ ] 未违反宪法红线（O3）
-
-**阶段完成时**:
-- [ ] 已完成检查清单自检（O4）
-- [ ] Layer 1 验证通过（O4）
-- [ ] 关键假设已记录（O3）
-
----
-
-## 七、关联文档
-
-| 文档 | 说明 |
-|------|------|
-| [03-tactical-principles.md](03-tactical-principles.md) | L3 战术原则（T1-T6） |
-| `knowledge/07-standards/00-coding-style.md` | 编码规范详情 |
-| `knowledge/01-principles/09-constitution.md` | 项目宪法详情 |
-| `knowledge/04-checklists/` | 各阶段检查清单 |
-
----
-
-**维护者**: AutoSpec 团队
-**进化分区**: 🟡 受控区
-**关联原则**: T1 任务分解、T3 精准回退、T4 反模式预判、T5 驯服非确定性、T6 优先复用