From 6f9090d9689085cbada3c46f0b8fc0e8d94e253b Mon Sep 17 00:00:00 2001
From: cfdaily <cfdaily@gitee.com>
Date: Thu, 14 May 2026 08:59:42 +0800
Subject: [PATCH] auto-sync: 2026-05-14 08:59:42

---
 docs/design/architecture-v2.md | 232 +++++++++++++++++++++++++++++----
 1 file changed, 209 insertions(+), 23 deletions(-)

diff --git a/docs/design/architecture-v2.md b/docs/design/architecture-v2.md
index 66bbd0a..de4d551 100644
--- a/docs/design/architecture-v2.md
+++ b/docs/design/architecture-v2.md
@@ -881,55 +881,241 @@ config/
 
 **states.yaml**:
 ```yaml
-# 任务级状态定义
+# 任务级状态定义（v2.0）
+# 基于 v1.0 state_machine.py 的成熟经验，新增 AI native 场景
 # Daemon 启动时加载，代码里不允许出现硬编码的状态名
+
+# ── 终态（不可变）──
+terminal_states: [completed]
+
+# ── 任务状态 ──
 states:
+  # === Phase 1: 需求探索 ===
   - name: exploring
-    description: "需求探索中"
+    description: "AI 与用户需求探索中"
     phase: 1
+    type: active
     transitions_to: [planning, cancelled]
-    
+    user_actions: [cancel, steer, takeover]
+    auto_triggers:
+      - trigger: confidence >= 0.8
+        to: planning
+        description: "AI 判断需求已足够清晰"
+
+  # === Phase 2: 动态规划 ===
   - name: planning
-    description: "动态规划中"
+    description: "AI 生成/调整执行计划"
     phase: 2
-    transitions_to: [executing, planning, cancelled]
-    
+    type: active
+    transitions_to: [executing, planning, paused, cancelled]
+    user_actions: [cancel, pause, steer, approve, reject]
+    auto_triggers:
+      - trigger: plan_approved
+        to: executing
+        description: "计划被批准（用户或 AI 自动）"
+      - trigger: plan_revise
+        to: planning  # 自转换
+        description: "challenge 驳回，修订计划"
+
+  # === Phase 3: 自主执行 ===
   - name: executing
-    description: "自主执行中"
+    description: "Agent 自主执行中"
     phase: 3
-    transitions_to: [reviewing, executing, cancelled]
-    
+    type: active
+    transitions_to: [reviewing, paused, escalated, failed, executing, cancelled]
+    user_actions: [cancel, pause, steer, takeover, intervene]
+    auto_triggers:
+      - trigger: all_steps_done
+        to: reviewing
+        description: "所有步骤完成"
+      - trigger: critical_step_failed
+        to: escalated
+        description: "关键步骤失败，需人工"
+
+  # === Phase 3.5: 执行中暂停 ===
+  - name: paused
+    description: "用户暂停，等待恢复"
+    phase: 3
+    type: active
+    transitions_to: [executing, planning, cancelled]
+    user_actions: [cancel, resume, replan]
+    auto_triggers:
+      - trigger: resume
+        to: executing
+        description: "用户恢复"
+      - trigger: goal_changed
+        to: planning
+        description: "用户改需求，重新规划"
+
+  # === 人工介入 ===
+  - name: escalated
+    description: "AI 主动升级，需要用户决策"
+    phase: 3
+    type: active
+    transitions_to: [executing, planning, cancelled]
+    user_actions: [cancel, rollback, replan]
+    auto_triggers:
+      - trigger: user_decision
+        to: executing
+        description: "用户给出决策，继续执行"
+      - trigger: goal_changed
+        to: planning
+        description: "用户决定改需求"
+
+  # === Phase 4: 验收 ===
   - name: reviewing
-    description: "验收中"
+    description: "AI 向用户汇报，等待验收"
     phase: 4
+    type: active
     transitions_to: [completed, executing, cancelled]
-    
+    user_actions: [accept, reject, cancel, steer]
+    auto_triggers:
+      - trigger: user_accept
+        to: completed
+        description: "用户验收通过"
+      - trigger: user_reject
+        to: executing
+        description: "用户不满意，继续执行"
+
+  # === 终态 ===
   - name: completed
     description: "任务完成"
-    transitions_to: []  # 终态
-    
+    phase: 4
+    type: terminal
+    transitions_to: []
+
   - name: cancelled
-    description: "已取消"
-    transitions_to: []  # 终态
+    description: "已取消（可 resume 重新激活）"
+    phase: null
+    type: normal  # 非终态，可恢复
+    transitions_to: [executing]
+    user_actions: [resume]
+
+  - name: failed
+    description: "任务失败（可 retry/escalate）"
+    phase: null
+    type: normal
+    transitions_to: [executing, escalated, cancelled]
+    user_actions: [retry, escalate, cancel]
+
+# ── 用户动作定义（AI native 扩展）──
+user_actions:
+  cancel:
+    description: "取消任务"
+    available_from: "任何非终态"
+  pause:
+    description: "暂停，冻结所有执行"
+    available_from: [planning, executing]
+  resume:
+    description: "恢复执行"
+    available_from: [paused, cancelled]
+  steer:
+    description: "用户中途改方向（不改 goal，只调整执行策略）"
+    available_from: [exploring, planning, executing, reviewing]
+    ai_native: true  # v2.0 新增：用户在对话中说“改成MACD”即触发
+  takeover:
+    description: "用户接管某个步骤"
+    available_from: [executing, escalated]
+    ai_native: true  # v2.0 新增：用户说“这部分我来”
+  intervene:
+    description: "用户主动干预（查看/修改产出物）"
+    available_from: [executing]
+    ai_native: true  # v2.0 新增：用户随时可以介入
+  approve:
+    description: "批准计划"
+    available_from: [planning]
+  reject:
+    description: "驳回计划"
+    available_from: [planning, reviewing]
+  replan:
+    description: "重新规划"
+    available_from: [paused, escalated]
+    ai_native: true
+  accept:
+    description: "验收通过"
+    available_from: [reviewing]
+  retry:
+    description: "失败后重试"
+    available_from: [failed]
+  escalate:
+    description: "升级到人工"
+    available_from: [failed]
+  rollback:
+    description: "回滚到执行态"
+    available_from: [escalated]
 ```
 
 **step-states.yaml**:
 ```yaml
-# 步骤级状态定义
+# 步骤级状态定义（v2.0）
+# 基于 v1.0 NODE_STATES 成熟经验
+
 step_states:
   - name: pending
+    description: "待分配"
     transitions_to: [assigned, cancelled]
+
   - name: assigned
+    description: "已分配 Agent"
     transitions_to: [executing, cancelled]
+
   - name: executing
-    transitions_to: [completed, failed, blocked, cancelled]
-  - name: completed
-    transitions_to: []
-  - name: failed
-    transitions_to: [pending]  # 可重试
-    max_retries: 3
+    description: "Agent 执行中"
+    transitions_to: [completed, failed, blocked, reviewing, waiting_human, cancelled]
+    # reviewing: 执行完进入审查（v1.0 challenge 机制）
+    # waiting_human: Agent 请求人工确认
+
+  - name: reviewing
+    description: "产出审查中（challenge）"
+    transitions_to: [completed, pending, failed, escalated]
+    # v1.0 挑战循环：pass → completed, iterate → pending, fail → failed
+
   - name: blocked
-    transitions_to: [pending, cancelled]
+    description: "被阻塞"
+    transitions_to: [pending, failed, cancelled]
+    max_retries: 3
+
+  - name: waiting_human
+    description: "等待人工确认（Checkpoint）"
+    transitions_to: [executing, completed, cancelled]
+    # v2.0: AI 主动请求用户确认关键产出
+
+  - name: completed
+    description: "完成"
+    transitions_to: []
+    type: terminal
+
+  - name: failed
+    description: "失败（可重试）"
+    transitions_to: [pending, escalated, cancelled]
+    max_retries: 3
+
+  - name: escalated
+    description: "升级到人工"
+    transitions_to: [executing, pending, cancelled]
+
+  - name: cancelled
+    description: "已取消"
+    transitions_to: []
+    type: terminal
+
+# ── 步骤执行方式 ──
+execution_modes:
+  - name: sub_agent
+    description: "创建 isolated sub-agent 执行（sessions_spawn）"
+    when: "复杂任务（编码、文档、调研）"
+    cleanup: "delete"
+    archive_transcript_to: "artifacts/task-{id}/steps/{step_id}/"
+
+  - name: main_session
+    description: "在 Agent 主 session 中执行"
+    when: "简单任务（数据获取、文件操作）"
+    record_to: "artifacts/task-{id}/steps/{step_id}/transcript.jsonl"
+
+  - name: human
+    description: "用户自己执行"
+    when: "用户说'这部分我来'"
+    trigger: "takeover"
 ```
 
 **代码中禁止出现硬编码状态名**：