auto-sync: 2026-05-14 09:45:05

docs/design/architecture-v2.md

@@ -1794,6 +1794,224 @@ experience:
 | 11 | Daemon 通知庞统 | Gateway WS API systemEvent | 步骤完成/异常/需要裁决时 |
 | 12 | 经验沉淀 | 任务完成后自动触发 AI 蒸馏 | + 规划/执行/异常时自动检索 |
 | 13 | 实现方式 | **一次性完整实现** | 不做最小集迭代，避免做着做着偏离 |
+| 14 | 治理原则 | **质量优先，成本和工期为质量让步，但有硬性上限** | 见 4.1 治理框架 |
+
+### 4.1 质量/成本/工期治理框架
+
+> 核心原则：**质量是第一优先级，成本和工期可以为质量妥协，但不能无限妥协。**
+>
+> 参考：Wanman TokenBudget（per-agent ceiling + 全局 ceiling）、Network-AI FederatedBudget（双层预算）、Network-AI QualityGate（两层门控：规则+AI）。
+
+#### 三层预算体系
+
+每个任务创建时分配三重预算，任何一重耗尽都触发干预：
+
+```yaml
+# config/settings.yaml 中的默认预算
+budget_defaults:
+  token:
+    per_task_ceiling: 500000       # 单任务总 token 上限
+    per_step_ceiling: 100000        # 单步骤 token 上限
+    per_agent_ceiling: 200000       # 单 Agent token 上限
+  time:
+    per_task_ceiling: 3600          # 单任务总时间上限（秒）
+    per_step_ceiling: 600           # 单步骤时间上限（秒）
+  depth:
+    max_plan_adjustments: 5         # 计划调整次数上限
+    max_retries_per_step: 3         # 单步骤重试次数上限
+    max_challenge_rounds: 3         # 挑战循环次数上限
+```
+
+**预算耗尽时的行为**：
+
+| 预算类型 | 耗尽行为 | 谁干预 |
+|---------|---------|--------|
+| step token 耗尽 | 步骤标记 failed，触发异常处理 | Daemon 自动 |
+| step 时间耗尽 | 步骤标记 failed，检查 Agent 存活 | Daemon 自动 |
+| task token 耗尽 | 任务暂停，通知庞统 + 用户 | Daemon → 庞统 → 用户 |
+| task 时间耗尽 | 任务暂停，通知庞统 + 用户 | Daemon → 庞统 → 用户 |
+| 计划调整次数耗尽 | 停止调整，用当前最佳计划继续 | Daemon 自动 |
+| 重试次数耗尽 | 步骤标记 failed，升级到庞统 | Daemon → 庞统 |
+
+#### 质量门控（Quality Gate）
+
+参考 Network-AI 两层门控：
+
+```
+Agent 提交产出物
+  │
+  ▼
+Layer 1: 规则验证（确定性，零成本，毫秒级）
+  ├── 文件存在性检查
+  ├── 文件非空检查
+  ├── Schema 校验（JSON/CSV 格式正确）
+  ├── Placeholder 检测（TODO/FIXME/...）
+  └── 基础完整性（字段非空、数值范围合理）
+  │
+  ├─ 通过 → 进入 Layer 2
+  └─ 失败 → reject（退回 Agent 修复）
+  │
+  ▼
+Layer 2: AI 审查（有成本，秒级，仅当 confidence < 阈值时触发）
+  ├── 产出物是否与 end_state 描述匹配
+  ├── 代码质量（变量命名、异常处理、逻辑正确性）
+  └── 幻觉检测（声称的结论是否有数据支撑）
+  │
+  ├─ approve → 完成
+  ├─ quarantine → 隔离待人工审查（通知庞统 + 用户）
+  └─ reject → 退回 Agent 修复
+```
+
+**成本控制**：Layer 2 不是每次都跑。默认只在以下情况触发：
+- Agent 回报 confidence < 0.7
+- 步骤是关键步骤（用户明确指定要审查的）
+- 连续多个步骤 Layer 1 都一次通过（抽样审查，防止 Agent 学会绕规则）
+
+#### 质量提升的分级投入
+
+不是所有任务都需要极致质量。根据任务重要性分级投入：
+
+```yaml
+# config/settings.yaml
+quality_levels:
+  critical:          # 资金安全、实盘交易
+    layer2_threshold: 0.8
+    max_retries: 5
+    always_ai_review: true
+    human_approval_required: true
+    token_budget_multiplier: 2.0
+    
+  standard:          # 策略回测、数据分析
+    layer2_threshold: 0.7
+    max_retries: 3
+    always_ai_review: false
+    human_approval_required: false
+    token_budget_multiplier: 1.0
+    
+  exploratory:       # 探索性研究、快速验证
+    layer2_threshold: 0.5
+    max_retries: 1
+    always_ai_review: false
+    human_approval_required: false
+    token_budget_multiplier: 0.5
+```
+
+任务创建时，AI 根据内容自动判定 quality_level，用户也可以手动指定。
+
+#### 成本回收机制
+
+高质量的产出如果被后续任务复用，相当于摊薄了成本：
+
+- **经验沉淀**：高质量任务的产出自动蒸馏为经验，下次同类任务减少 token 消耗
+- **Skill 转化**：高频经验固化为 Skill，直接注入减少检索成本
+- **模板复用**：高质量的计划结构可以保存为模板，下次直接使用
+
+#### 工期控制：何时干预
+
+| 场景 | 判断标准 | 干预方式 |
+|------|---------|----------|
+| 明显死循环 | 同一步骤 retry > max_retries | 强制终止 + 升级 |
+| 计划反复调整 | plan_adjustments > max | 锁定当前计划继续 |
+| Agent 超时无响应 | step 执行时间 > per_step_ceiling | 检查存活 → 重试或换 Agent |
+| 质量长期不达标 | 连续 3 个步骤 AI 审查 reject | 暂停任务 + 通知用户 |
+| 成本超预期 | task token > 80% ceiling | 通知庞统评估是否值得继续 |
+| 接近 deadline | task 时间 > 80% ceiling | AI 判断：是否降级质量等级以保工期 |
+
+#### AI 决策结构化
+
+每个 AI 决策必须记录完整的推理过程（司马懿评审意见）。
+
+```sql
+-- decisions 表结构化扩展
+CREATE TABLE decisions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    task_id TEXT NOT NULL,
+    step_id TEXT,
+    decision_type TEXT NOT NULL,  -- agent_selected / plan_adjusted / anomaly_classified / quality_review
+    
+    -- 结构化推理（司马懿要求：输入、选项、选择、原因、置信度）
+    input_summary TEXT NOT NULL,       -- AI 看到了什么
+    options_considered TEXT NOT NULL,   -- 考虑了哪些选项（JSON array）
+    selected TEXT NOT NULL,            -- 选了什么
+    reason TEXT NOT NULL,              -- 为什么选这个
+    confidence REAL NOT NULL,          -- 置信度 0.0-1.0
+    
+    model TEXT,
+    token_cost INTEGER,
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+```
+
+#### 经验生命周期
+
+经验不是写进去就永远有效：
+
+```sql
+-- experiences 表扩展
+ALTER TABLE experiences ADD COLUMN lifecycle TEXT DEFAULT 'draft';  -- draft / verified / superseded / expired
+ALTER TABLE experiences ADD COLUMN verified_at TEXT;
+ALTER TABLE experiences ADD COLUMN verified_by TEXT;  -- ai / human
+ALTER TABLE experiences ADD COLUMN expires_at TEXT;   -- TTL，过期自动降权
+ALTER TABLE experiences ADD COLUMN superseded_by INTEGER REFERENCES experiences(id);
+```
+
+| 生命周期 | 说明 | 检索权重 |
+|---------|------|---------|
+| draft | AI 自动蒸馏，未验证 | 0.5x |
+| verified | 经过实际任务验证（引用 >= 2 次） | 1.0x |
+| superseded | 被更好的经验替代 | 0.1x |
+| expired | TTL 过期，自动降权 | 0.0x（不检索） |
+
+#### 异常处理策略表
+
+异常分类用确定性逻辑，处理策略用预设决策表（司马懿评审意见）：
+
+```yaml
+# config/exceptions.yaml
+exceptions:
+  - type: agent_timeout
+    detection: "step execution time > per_step_ceiling"
+    strategy:
+      - action: check_agent_alive
+      - action: retry
+        max: 3
+        backoff: exponential
+      - action: reassign_agent  # 换一个 Agent
+      - action: escalate_to_human
+    
+  - type: validation_failed
+    detection: "quality gate Layer 1 failed"
+    strategy:
+      - action: reject_to_agent
+        max: 3
+      - action: escalate_to_human
+    
+  - type: ai_judgment_conflict
+    detection: "two AI decisions contradict"
+    strategy:
+      - action: escalate_to_human  # AI 冲突必须人工裁决
+    
+  - type: resource_deadlock
+    detection: "circular dependency detected"
+    strategy:
+      - action: break_cycle  # 随机释放一个等待
+      - action: reassign_agent
+      - action: escalate_to_human
+    
+  - type: budget_exceeded
+    detection: "any budget ceiling reached"
+    strategy:
+      - action: pause_task
+      - action: notify_pangtong
+      - action: await_human_decision
+    
+  - type: unknown
+    detection: "unclassified exception"
+    strategy:
+      - action: ai_classify  # 只有未知异常才让 AI 分类
+      - action: apply_strategy  # 应用 AI 选择的策略
+      - action: escalate_to_human  # 兜底
+```
 
 ---