重构: 文档汇总+进度看板+孤儿任务清理脚本+gitignore 噪音排除

- docs/02 架构设计: 新增 aichat审查/异步审批构想/流式渲染调研/generating状态机/密钥迁移健壮性/工作流脚本执行边界/条件表达式引擎/F-07 trait下沉/Agent架构说明/任务推进构想/功能创意池;更新功能决策记录+归档/对抗论证/文档记录规范/经验记录
- docs/03 模块文档: 新增 AI对话引擎/DAG引擎详解;更新 df-knowledge/df-nodes/df-storage/df-workflow/df-ai
- docs/05 代码审查: 新增 全栈审查/全局review/架构审查/近期改动审查/工作区多角度走查/自研memo流式渲染审查
- docs/09 问题排查: 新增 aichat-apikey-401
- docs/INDEX+README 索引同步;docs/todo 待办看板(2026-06-15 汇总)
- PROGRESS.md Sprint 22-25;URGENT.md 加急清单快照(5 项 P0 已全修)
- scripts/cleanup_orphan_tasks.{py,sh} 孤儿任务清理工具
- .gitignore 补 *.broken.bak + tmp/ 噪音排除
This commit is contained in:
2026-06-15 05:14:21 +08:00
parent 4b5f096d1c
commit 04032a2a8d
43 changed files with 5372 additions and 163 deletions

View File

@@ -0,0 +1,344 @@
# 构想: 任务推进全局设计AI-First 推进链) — 2026-06-14
> 性质: 架构设计 / 实现方案
> 关联: df-workflow · AiNode/HumanNode · knowledge 状态机范式 · devflow AI-First 定位kms/devflow_ai_first_model.html
> 修订:
> - 多角度对抗论证收敛kind/状态机不抽层/范围精简)
> - 对抗性验证升级5 维度:收口/并发/崩溃/一致性/前端)
> - **AI-First 定位确认**:任务由 AI 执行→AI 自审→人工最终核对(人从操作者转为审批者)
---
## 定位AI-First 推进链(核心转向)
devflow 是 AI-First 工具。任务推进**不是人点按钮的操作流,是 AI 的执行流**
```
todo ──AI执行──▶ in_progress ──AI自审──▶ review_ready ──人工核对──▶ done
AiNode AiNode HumanNode
AI 干活 AI 审 AI 的活 人最终把关 AI 产出
```
- **AI 执行**:任务内容由 AI 干(写代码、改文件、跑测试)。干完自动推进,人不必手动点「开始」。
- **AI 自审**AI 审 AI 自己的产出code review结构化结论。审过推进审出问题退回重做。
- **人工最终核对**:人在 merge 关卡最终把关 AI 产出。**这是 AI-First 的核心契约——人监督 AI**,不是人确认自己的活。
**advance_task 的默认触发者从「人」变成「AI」**(执行/自审完成事件触发),人可介入/覆盖/微调。人从「操作者」转为「审批者」。
### 这修复了对抗验证的 merge 零因果批评
对抗验证 Agent 4 批评「单人场景 merge 审批零因果——自审自批≈手切」。**AI 执行 + 人工核对**正好修复merge 不再是人确认自己的活,而是**人监督 AI 的活**——从形式主义升级为实质关卡。
---
## 背景
项目管理任务维护目前**只能创建,不能推进**——前端状态标签纯展示无入口。根因缺「推进编排层」:状态字段、工作流引擎、分支表、状态机范式各干各的,且**完全缺 AI 执行层**。
## 痛点
| 已有能力 | 位置 | 现状 |
|---|---|---|
| 任务状态字段(裸 String无值域校验 | `models.rs:52` | 无状态机、无联动、前端不暴露 |
| 工作流引擎ScriptNode/HumanNode/**AiNode** | `df-workflow/*` + `df-nodes/*` | 三种节点现成AiNode 注释明示设计意图「AI 分析→人工审批」,但推进链没用上 |
| 分支表状态 | `models.rs:69` | 语义同构,未联动 |
| 状态机范式 | `knowledge.rs:53` | 只在 knowledge 用 |
| **AI 执行能力** | `df-ai` provider + `ai_node.rs` | AiNode 通用 LLM 调用现成agent 级「写代码改文件」能力渐进 |
---
## 核心模型AI-First 推进链 + 状态机
### 状态机AI 推进 + 退回 + 旁路)
```
AI执行闸门 AI自审闸门 人工核对闸门
todo ───────────▶ in_progress ──────────▶ review_ready ──────────▶ done
▲ │ │
└── AI自审block/人工拒绝 ┘ │ (AI 重做)
abandoned (任意态可放弃,终态不可逆)
```
**退回边** `review_ready → in_progress`AI 自审 block 或人工拒绝 → 退回让 AI 重做。AI 推进下退回比人推进更频繁AI 反复审自己),故 loop 管理必要。
### 闸门策略(三闸门各司其职,都必需)
| 边 | 闸门 | 节点 | 阶段一 | 阶段二 |
|---|---|---|---|---|
| `start` | **AI 执行** | AiNode/agent | ✅ 必需(最小形态) | + git worktreecode kind |
| `ready` | **AI 自审** | AiNode | ✅ 必需 | + lint/test 真校验 |
| `merge` | **人工核对** | HumanNode | ✅ 必需(人监督 AI | + git merge 副作用 |
| `abandon` | 无 | — | 直接转 | 直接转 |
三闸门都必需不再是「merge 强制 + start/ready 关闭」——AI 推进链上每环都有节点把关。
### ⚠️ 失败路径定义(含 AI 执行/自审失败)
| 失败场景 | 工作流结果 | 任务状态 | 反馈 |
|---|---|---|---|
| **AI 执行失败**agent 报错/超时) | failed | 保持 todo | 「AI 执行失败:<错误>」,人可重试或介入手干 |
| **AI 自审 block**(审出严重问题) | failed | **退回 in_progress**AI 重做) | 「AI 自审未通过:<问题清单>」 |
| **AI 自审 warn**(轻微问题) | completed带警告 | 推进到 review_ready | 警告附在任务上,人核对时可见 |
| **人工拒绝** | failed | **退回 in_progress**AI 重做) | 「人工核对未通过:<意见>」 |
| **闸门脚本失败**(阶段二 lint/test | failed | 保持推进前 | 「闸门失败」 |
| **审批超时/取消** | failed/Err | 保持推进前 | 「超时/已取消」 |
| **应用崩溃** | running 孤儿 | 保持推进前,可重新推进 | 启动提示「检测到中断的推进」 |
**关键**AI 自审/人工核对的「拒绝/block」→ 退回 in_progress 让 AI 重做不是退回给人干——AI-First 下人是审批者不是执行者)。
### AI 自审结果处理(建议性 vs 强制)
AiNode 输出纯文本,要判通过与否得约定结构化输出 + 解析:
```json
{ "verdict": "pass" | "warn" | "block", "issues": [...], "summary": "..." }
```
- `pass`:推进;`warn`:推进但带警告;`block`:退回 in_progress
- 默认 AI 自审走 verdict 判定(非纯建议),否则 AI 推进链断在人审前
- 人审merge仍是最终关卡可覆盖 AI 自审结论
---
## AI 执行层(新增,核心缺口)
任务内容由谁干——这是原方案的最大盲区。AI-First 下由 AI 执行。
### 实现形态
- **AiNode/agent 执行**start 闸门触发 AiNode或更复杂的 agent 编排)干活——读任务描述 + 项目上下文 → 写代码/改文件/跑测试 → 产出 diff
- **执行能力渐进**阶段一最小形态AiNode 跑执行 prompt / 接现有 AI 工具链),阶段二+ 逐步增强agent 多步、文件操作、git worktree 内执行)
- **执行产出**:代码 diff / 文件变更 / 测试结果,供下游 AI 自审节点消费
### advance_task 触发者变更
- **默认**AI 执行完成事件 → 自动触发 advance_task(start→推进)
- AI 自审完成 → 触发 advance_task(ready→推进或退回)
- 人工核对完成 → 触发 advance_task(merge→done)
- **人可介入**:任何节点人能手动推进/覆盖/接手(人转手干)
---
## 【P0】状态机收口对抗验证最高优先级
### 致命漏洞update_task 是公开旁路
`task.rs:74` update_task 白名单含 `"status"``crud.rs:291`),任意调用方一行绕过所有闸门和状态机。且 `crud tests:249` 单测固化旁路。AI 推进下更危险——AI agent 若能调 update_task 改 status整个 AI 执行/自审/核对链形同虚设。
### 收口措施
1. 从 tasks 白名单**移除 `"status"`**
2. **advance_task 成为 status 唯一写入路径**AI 触发也走它)
3. 删除/改写 `update_field_allows_tasks_status` 单测
4. advance_task 内联 `validate_task_status` 值域校验
---
## 状态集清理(非「定稿」)
对抗验证纠误:前端早已 5 态,后端 enum 多 3 个僵尸死状态InReview/Testing/Blocked 零使用。是「清理僵尸」非「7→5 定稿」。
措施:删后端 enum 死状态 + `merged→done` 改名 + 迁移前抽样 + status 值域校验。
```sql
-- 迁移幂等conn.transaction() 包裹)
UPDATE tasks SET status='done' WHERE status='merged';
```
---
## 任务类型:阶段一不加 kind
对抗验证:阶段一 code/generic 行为零差异,违反 YAGNI。阶段二 git 联动需要区分时再加 kindALTER + 回填 generic`tags` 保留承担语义标注doc/design
**AI 推进下的 kind 意义**:阶段二+ AI 执行内容按 kind 分化code 任务 AI 写代码、doc 任务 AI 写文档、design 任务 AI 出图)。阶段一 AI 执行最小形态不区分,随能力增强再分。
---
## 状态机实现:不抽层 + 下沉 SQL
enum 补 `can_transition_to`(不新建 state_machine.rsknowledge validate_transition 源码验证是空壳):
```rust
impl TaskStatus {
pub fn can_transition_to(&self, to: &TaskStatus) -> bool {
match (self, to) {
(Todo, InProgress | Abandoned) => true,
(InProgress, ReviewReady | Abandoned) => true,
(ReviewReady, Done | Abandoned | InProgress) => true, // 可退回AI 重做)
_ => false,
}
}
}
```
**状态机下沉 SQL**TOCTOU 根治advance_task 的校验+写入合并为带前置条件的 UPDATE
```sql
UPDATE tasks SET status=:new, updated_at=:now
WHERE id=:id AND status=:expected -- affected_rows==0 即状态已变,拒绝
```
终态保护:`AND status NOT IN ('done','abandoned')`
---
## loop 管理AI 推进下必需)
AI 自审/人工核对退回 → AI 重做 → 再审 → 可能反复。加 `review_rounds: i32` 计数,退回时 +1
- 任务卡显示「第 N 轮 review」迭代可见性
- 可选:轮数过高提示「是否卡住」(不强制终止——单人/AI 决定何时 done
- 强制终止/阈值不做over-engineering
---
## 并发与一致性护栏(对抗验证新增)
AI 推进下并发更常见(多个任务并行 AI 执行)。护栏不变:
1. **per-task 互斥锁**`task_locks: Arc<Mutex<HashMap<String, Arc<Mutex<()>>>>>`
2. **闸门工作流去重**:起 run_workflow 前查 running/interrupted 工作流
3. **WorkflowEvent 加 execution_id** + 转发过滤(防多任务事件串台)
4. **审批请求带 task_id**task_id + execution_id + node_id 三元组)
---
## 数据一致性:跨表事务
`crud.rs` 无跨表事务advance_task 多表写task.status + workflow.status + 阶段二 branches/projects半成品无法回滚。promote_idea 补偿范式不适用更新型。
措施:**补 `Database.transaction()`**OwnedTransactionadvance_task 事务内提交。迁移幂等column_exists + WHERE + conn.transaction 包裹。tags 写入校验。
---
## 崩溃恢复对抗验证新增AI 推进下更关键)
AI 执行/自审是长时异步过程,崩溃恢复更关键:
1. **启动孤儿清理**`UPDATE workflow_executions SET status='interrupted' WHERE status='running'`
2. **审批请求持久化**HumanNode 阻塞前落库node_executions status='pending'),启动恢复
3. **AI 执行状态持久化**AI 执行(长时)需 checkpoint崩溃后能恢复或安全重做阶段二+
4. **审批拒绝语义化**HumanNode/AiNode 区分同意/拒绝/block拒绝走失败路径不当 Ok
5. **重复触发守卫**advance_task 入口检查 running/interrupted 工作流
---
## 前端改造(对抗验证新增 + AI 推进适配)
1. **pendingApprovals 数组化**(按 execution_id 索引)
2. **liveEvents 按 task 路由**event payload 加 task_idstore 改 liveEventsByTask
3. **任务卡 AI 推进可视化**显示当前在哪个环节AI 执行中/AI 自审中/待人工核对/第 N 轮)
4. **按钮防重入**advancingTaskIds: Set
5. **确认式更新**:等 IPC/workflow 事件再刷 task非乐观更新
6. **AI 产出展示**AI 执行的 diff、AI 自审的意见清单,供人核对时查看
7. **统一错误桥接**:全局 watch state.error → Message.error
8. **回调判定**run_workflow 完成回调 advance_task 条件 `task_id.is_some()`
---
## 两阶段落地
### 阶段一AI-First 推进链 + 工程护栏
**推进链**
- 状态集清理(删僵尸 + merged→done+ enum 补 can_transition_to
- **状态机收口**(移除 status 白名单 + advance_task 唯一入口 + 值域校验)← P0
- advance_task + 状态机下沉 SQL + on_task_advanced 空钩子
- **AI 执行闸门**AiNode 最小形态)+ **AI 自审闸门**AiNode 结构化 verdict+ **人工核对闸门**HumanNode
- **失败路径定义**AI 执行失败/AI 自审 block/人工拒绝→退回重做)
- **loop 管理**review_rounds 计数)
- per-task 锁 + 闸门去重、跨表事务、WorkflowEvent 加 execution_id、启动孤儿清理 + 审批持久化
- WorkflowRecord 填值 + event payload 加 task_id
- 前端pendingApprovals/liveEventsByTask/advancingTaskIds/确认式更新/AI 推进可视化
**触发者**advance_task 支持 AI 事件触发 + 人手动介入双通道。
### 阶段二Git + 联动 + AI 执行增强
- 加 kind 字段code kind 闸门脚本换 git 命令串start/ready 接真 git/lint/test
- AI 执行增强agent 多步、worktree 内执行、文件操作)
- 填 on_task_advanced分支联动 + 项目 completed含边界守卫
- BranchRecord 加 worktree_path
### Git 集成:直接外部命令
git 是 ScriptNode/AiNode 一串命令,不特殊化。不建 worktree.rs/df-git crate不做 git 检测框架。硬依赖 git ≥2.20。非 code 任务不依赖 git。
### 联动策略
阶段一剥离分支联动和项目 completed~90 行 + 边界漏洞),阶段二填钩子返工 <30 行。
---
## 落地改动点(阶段一,按优先级)
| 级 | # | 文件 | 改动 |
|---|---|---|---|
| **P0** | 1 | `crud.rs`+`task.rs` | 移除 status 白名单 + advance_task 唯一入口 + 值域校验 + 改单测 |
| **P0** | 2 | `task.rs` | advance_task + 状态机下沉 SQL + on_task_advanced 空钩子 + **支持 AI 事件触发** |
| **P0** | 3 | 闸门 DAG 模板 | **AI 执行AiNode+ AI 自审AiNode verdict+ 人工核对HumanNode三闸门** |
| **P0** | 4 | `human_node.rs`+`ai_node.rs`+`executor.rs` | **审批/自审拒绝语义化**block/拒绝走失败路径不当 Ok |
| **P1** | 5 | `task.rs`/`models.rs` | **review_rounds 计数**(退回 +1 |
| **P1** | 6 | `state.rs` | per-task 锁 + 闸门去重 |
| **P1** | 7 | `db.rs`/`crud.rs` | 补 Database.transaction() + 事务包裹 |
| **P1** | 8 | `events.rs`+`workflow.rs` | WorkflowEvent 加 execution_id + 转发过滤 |
| **P1** | 9 | `state.rs` init | 启动孤儿清理 + 审批持久化恢复 |
| **P1** | 10 | `types.rs` | 删 enum 僵尸 + 补 can_transition_to |
| **P1** | 11 | 迁移 | merged→done幂等 + 事务)|
| **P1** | 12 | `workflow.rs` | run_workflow 加 task_id/project_id + event payload 加 task_id + 完成回调 |
| **P1** | 13 | `models.rs` | TaskRecord 加 tagskind 推阶段二)+ review_rounds + 白名单 |
| **P1** | 14 | 前端 `project.ts`/vue | pendingApprovals 数组 + liveEventsByTask + advancingTaskIds + 确认式更新 + **AI 推进环节可视化** + **AI 产出/diff 展示** |
| **P2** | 15 | `constants`+i18n | merged→done 键名 + tags + review_rounds 文案 + AI 环节文案 |
| **P2** | 16 | `project.ts` | 全局 error 桥接 |
---
## 决策护栏(触发反转条件)
| 决策 | 反转条件 |
|---|---|
| AI-First 推进AI 执行→自审→人核对) | AI 执行能力长期不足/不可靠 → 退回人执行 + AI 辅助审 |
| 阶段一不加 kind | 阶段二 doc/design 真要 AI 执行不同内容;或按 kind 统计 |
| 状态机不抽层 | 第三处状态机需统一审计 |
| 阶段一剥离联动 | 用户验收反馈「想看到项目自动完成」 |
| 不提前集成 git | worktree 异常恢复需 Rust 逻辑 |
| 状态机收口 | 出现「需批量脚本直接改 status」运维场景 → 另开受控入口 |
| AI 自审走 verdict 判定(非纯建议) | AI 自审误判率高 → 降级为建议性,人审全权 |
---
## 决策清单(人定取舍 · why
| # | 决策 | 否决备选 | why |
|---|---|---|---|
| 1 | **AI-First 推进链**AI 执行→AI 自审→人工核对) | 人点按钮推进 | devflow 是 AI-First 工具,任务是 AI 的执行流非人的操作流 |
| 2 | **advance_task 默认 AI 触发**,人可介入 | 仅人触发 | AI 执行/自审完成自动推进;人转审批者 |
| 3 | **AI 自审走 verdict 判定**pass/warn/block | 纯建议 | AI 推进链需 AI 自审能阻断,否则断在人审前 |
| 4 | **人工核对 = 人监督 AI**(非自审自批) | 人确认自己的活 | 修复 merge 零因果AI-First 核心契约 |
| 5 | **拒绝/block → 退回 AI 重做**(非退回人干) | 退回人执行 | AI-First 下人是审批者不是执行者 |
| 6 | **loop 管理 review_rounds**AI 推进必需) | 无计数 | AI 反复审自己,循环比人推进频繁 |
| 7 | 状态机收口(移除 update_task status | 保留旁路 | 对抗验证旁路让状态机形同虚设AI 推进下更危险 |
| 8 | 阶段一不加 kind阶段二再加 | 阶段一二分 | 对抗验证:阶段一零行为差异 |
| 9 | 状态机不抽层enum 补方法 | 抽通用层 | 源码验证空壳 |
| 10 | 状态机下沉 SQLWHERE 前置) | 纯内存校验 | 对抗验证:根治 TOCTOU |
| 11 | 失败路径全覆盖(含 AI 执行/自审失败) | 只描述快乐路径 | 对抗验证:拒绝被当成功是语义反转 |
| 12 | 补跨表事务 | 无事务多写 | 对抗验证:半成品无法回滚 |
| 13 | 崩溃恢复(孤儿清理+审批持久化+AI 执行 checkpoint | 纯内存 | AI 执行长时异步,崩溃恢复更关键 |
| 14 | WorkflowEvent 加 execution_id | 全局单通道 | 对抗验证:多任务事件串台 |
| 15 | 状态集清理后端僵尸(非 7→5 定稿) | 当作待决策 | 对抗验证:前端早已 5 态 |
| 16 | 闸门三必需AI执行/AI自审/人工核对) | merge 强制+其余关 | AI 推进链每环都有节点把关 |
| 17 | 阶段一剥离联动 | 顺带联动 | ~90 行+边界漏洞 |
| 18 | 预留 on_task_advanced 钩子 | 不预留 | 阶段二补是挂插件 |
| 19 | git=闸门脚本调外部命令 | worktree.rs/df-git crate | YAGNI |
| 20 | merged→done迁移 | 文案分流 | 命名中性化 |
| 21 | 前端 pendingApprovals 数组 + 确认式更新 + AI 环节可视化 | 单值/乐观 | 对抗验证多任务并发AI 推进需环节可见 |
---
## 演进记录
1. **多角度论证收敛**kind 二分、状态机不抽层、阶段一范围精简、闸门策略
2. **对抗性验证升级5 维度)**:状态机收口/并发/崩溃恢复/一致性/前端——挖出 P0 致命项(旁路、审批拒绝=成功、TOCTOU、纯内存
3. **AI-First 定位确认**:任务由 AI 执行→AI 自审→人工最终核对。补执行层原方案最大盲区advance_task 触发者改 AIAI 审/loop 升必需merge 升级为「人监督 AI」实质关卡