lxy
b994cf2c54
- 无人值守长任务设计定稿,含效率与可观测补遗 - u-relay wire 协议规格与五项评估结论 - 新能力引入评估纪律五项清单 - todo 销账与狗粮短板分析登记
319 lines
30 KiB
Markdown
319 lines
30 KiB
Markdown
# 无人值守长任务 — 机制设计
|
||
|
||
> 日期: 2026-10-04 | 状态: ~~设计稿(待拍板)~~ ✅拍板通过(2026-10-04,13/13 按建议;全量拍板记录见 [拍板集-2026-10-04.md](./滚动规范/拍板集-2026-10-04.md)) | 勘察: 只读实测锚点
|
||
> 拍板背景: 产品方向定为「任务规划一次性确定边界后,无人值守、自主无干预、稳定完成长任务」;S2-B 真审批通道延后不做。
|
||
> 设计目标(用户原话转译): ①长任务中途零打断(不弹审批、不等人) ②发起时一次拍板授权范围,存续期内 AI 全自主 ③无人盯着也能信任——失败自愈、进度可观测、异常安全停靠、完成/异常有通知。
|
||
|
||
---
|
||
|
||
## 一、现状勘察(锚点实测)
|
||
|
||
### 1.1 打断点全景与无人值守处置
|
||
|
||
| # | 打断点 | 现状机制(锚点) | 现行为 | 无人值守处置 |
|
||
|---|--------|---------------|--------|-------------|
|
||
| 1 | 风险审批挂起 | `audit/approval.rs` handle_approval_tool → insert_pending_approval;auto_exec_mode 三档(low/medium/all) + patch_file 全档放行特例 + 会话信任(session_trust,`mod.rs:542` TrustKey) | Medium/High 挂 loop,弹卡 + 系统通知,默认 15 分钟超时自动取消(`state.rs:240` approval_timeout_minutes) | **边界内放行**:风险≤任务上限 ∧ 非破坏性命令 → 直接执行(decided_by=boundary_auto);边界外不弹卡,拒绝 tool_result + 记待办 |
|
||
| 2 | 路径授权挂起 | `audit/path_auth.rs` check_file_tool_auth → NeedsAuth → ApprovalKind::Path + emit AiDirAuthRequired | 挂 loop 等三档授权(once/session/always,`state/allowed_dirs.rs`) | **边界内放行**:路径命中任务白名单 → Authorized;白名单外 → 不弹卡,结构化拒绝(L1 可改提示) |
|
||
| 3 | 黑名单硬拒 | 同上 Denied 分支 + validate_path 黑名单;已有先例:all 档保黑名单(audit/mod.rs:667),bypass 开关才连黑名单放行(PathBypass::All),子代理 KeepBlacklist | 就地拒绝,loop 继续 | **永不放行**(安全底线,同 all 档/子代理先例);拒绝 envelope 提示换路径 |
|
||
| 4 | 破坏性命令 | `mod.rs:603` is_destructive_command(rm/del/format/... 首 token 精配) | 信任放行门控,命中走正常审批 | **永不放行**;边界内 run_command 也过此闸 |
|
||
| 5 | LLM 流错误停 | `agentic/mod.rs` RoundOutcome::Fatal(候选 4xx 非429 或全 candidate 耗尽)→ return;流前 InitFailed Retryable 已有退避重试+candidate 链切换(retry.rs 同源分类) | Fatal 直接终轮 | **降级为安全停靠**(见 4.2):非正常终局统一停靠出口,不再裸 return |
|
||
| 6 | 工具执行失败 | Low 失败 = 失败 envelope 进 tool_result,loop 继续(AR-6);外层超时 60s/run_command clamp/spawn_agent 挂钟+60 | 错误交 LLM 自纠 | **可降级继续**:已有,不改;唯一化入停靠判定(连续失败见 4.1) |
|
||
| 7 | 断路器求助 | L1 失败断路器(THRESHOLD=3/WINDOW=20)+ G2 探索熔断(3 次) → emit 求助,等用户 | 挂起等介入 | **安全停靠**:触发即停靠(保留熔断,语义从「等」改「存档+通知」) |
|
||
| 8 | 达最大轮次 | agentic/mod.rs:1150 已改自动收尾(incomplete=true)+ NeedAction 通知 | 自动终止 | **已是停靠雏形**,补停靠说明+待办清单,预算可由任务边界放大 |
|
||
|
||
结论:打断点 1/2 是无人值守的**主要敌人**(挂起等输入);3/4 是**安全线**(保留);5-8 已有自动终局雏形,统一成语义即可。
|
||
|
||
### 1.2 既有边界件盘点(可直接复用为任务级边界底座)
|
||
|
||
| 件 | 锚点 | 复用方式 |
|
||
|----|------|---------|
|
||
| spawn_agent 白名单钳制 | `agentic/sub_agent.rs:260` clamp_tool_whitelist(tools ∩ Low ∖ spawn_agent)+ 执行期双闸(audit/mod.rs:172 sub_agent_tool_clamped) | 判定结构参照;**子代理不放宽**(fail-closed 保持,见拍板点 6) |
|
||
| 会话级授权目录 | `state/allowed_dirs.rs` AllowedDirs{persistent/session/once} | 任务白名单独立于三档(任务级,不写用户 persistent 白名单——一次性授权不污染全局);判定函数复用 check_path_authorization 的规范化/黑名单逻辑 |
|
||
| 三重熔断 | `sub_agent.rs:301` round_budget_stop(轮次/200k token/900s 挂钟) | 结构直接抄给任务级预算(参数独立可配,主会话量级上限实测后定) |
|
||
| 看门狗/心跳 | execute_with_heartbeat 30s AiHeartbeat + 前端 130s watchdog + stall_detector check_retry_exhausted | 已覆盖长工具误杀与流断连,零改动 |
|
||
| fail-closed 拒绝协议 | deny_sub_agent_tool 结构化 envelope(denial_layer 四层)+ is_sub_agent_deny_envelope 解析 | 边界外拒绝**照抄此协议**(新 denial_layer=boundary-exceeded),LLM 可自纠、报告可申报缺口 |
|
||
| 审批恢复/落库 | pending_approvals 序列化 + restore_pending_approvals 启动恢复;auto checkpoint(save_conversation 每 20 条消息 <1MB 快照入 ai_conversation_checkpoints) | 断点续跑底座(P2) |
|
||
| 全局全自动先例 | df-ai-auto-execute-mode=all + df-ai-path-auth-bypass | 即「完全信任」档的存量实现(L3 远期档,见五);本设计不重造 |
|
||
|
||
### 1.3 稳定性现状
|
||
|
||
- 重试面: retry.rs 指数退避(1s→2s→4s+jitter,30s 预算,Retryable/Fatal 分类)覆盖 complete() 与流前;candidate 链自动切 provider。**工具级无自动重试**——被 detect_retry_count/去重缓存刻意压制(防死循环),维持。
|
||
- 进度可观测: AiToolCallStarted/Completed 全事件流 + AiHeartbeat + 审计表 + checkpoint。缺「任务级」聚合视图(轮次/预算余量)。
|
||
- 通知: `notify.rs` 三类(Completed/Failed/NeedAction),主窗聚焦跳过 + 5s 节流合并 + 失败静默。P3-6 基建完整,停靠/完成通知直接挂现有出口。
|
||
- 断点续跑: checkpoint 表有快照、审批有启动恢复,但 **loop 本身重启后不自动续跑**,需人工。
|
||
|
||
---
|
||
|
||
## 二、任务级授权边界模型
|
||
|
||
### 2.1 数据结构(挂会话,不建新表——宁少勿预留)
|
||
|
||
```rust
|
||
// commands/ai/boundary.rs(新文件,纯结构+判定函数+单测)
|
||
pub struct TaskBoundary {
|
||
pub risk_ceiling: RiskLevel, // 上限 Low|Medium;High 不经此通道(拍板点 1)
|
||
pub allowed_dirs: Vec<PathBuf>, // 任务目录白名单(canonicalize 规范形态,含项目根)
|
||
pub forbid_destructive: bool, // 恒 true,字段留作显式声明(UI 展示用),判定不读
|
||
pub budget: TaskBudget { max_rounds: u32, max_tokens: u64, wall_secs: u64 }, // 缺省继承现网常量
|
||
}
|
||
```
|
||
|
||
存储与生命周期:
|
||
- 内存: per_conv 会话条目新增 `boundary: Option<TaskBoundary>`(会话级单真相源先例,`mod.rs:621`);
|
||
- 落库: ai_conversations 新列 `boundary_json`(迁移一个 ALTER TABLE,save_conversation 随现有 meta 链路写,启动 load 还原);
|
||
- 生命周期 = 会话存续: 发起时一次声明 → 整个任务存续生效 → 会话删除级联消失。不做中途改边界(改边界=新拍板,UI 提示重开任务),防「边跑边扩权」;
|
||
- 与全局档正交: 有 boundary 的会话 boundary 优先;无 boundary = 现状逐次审批,**渐进增强零倒退**。
|
||
|
||
### 2.2 UI 形态(发起时一次性配置卡)
|
||
|
||
参照 spawn_agent 参数卡(审批卡 approval_hint 模板,`tools/spawn_agent.rs:172`)+ 设置页范式:
|
||
- 入口: 新任务发起对话框(或首条消息发送时)展开「无人值守边界」折叠卡;非必填——不展开 = 现状审批模式;
|
||
- 字段四项: 风险上限(Low/medium 单选,默认 Low)/ 目录白名单(复用设置页 allowed_dirs 目录选择交互,默认预填当前项目绑定目录)/ 预算(轮次/token/挂钟,默认值预填,高级折叠)/ 确认按钮文案「一次授权,任务期内不再打扰」;
|
||
- 展示态: 任务进行中侧栏会话条目挂边界徽标,点开只读回显(禁中途改)。
|
||
|
||
### 2.3 IPC 面
|
||
|
||
`ai_set_task_boundary(conv_id, boundary_json)` 发起时调用;`ai_get_task_boundary(conv_id)` 回显。删除/停止会话既有级联不动(边界随会话条目同亡,无需新清理点)。
|
||
|
||
---
|
||
|
||
## 三、边界内审批旁路(risk 分流改造)
|
||
|
||
### 3.1 判定链插桩(单点,两处)
|
||
|
||
现判定链: path_auth 预校验(path_auth.rs)→ classify_risk_and_auto(approval.rs:33)→ trust → pending。改造在 `process_tool_calls`(audit/mod.rs:604)读取 auto_exec_mode 处并列读取 boundary 快照,然后:
|
||
|
||
```
|
||
对每条工具调用(有 boundary 会话):
|
||
① 黑名单命中 → Denied(现状,永不放行)
|
||
② 文件工具: 路径 ∈ boundary.allowed_dirs → Authorized;
|
||
路径 ∉ 白名单 → 拒绝 envelope{denial_layer:"boundary-dirs"},不弹卡不挂起,
|
||
LLM 换路径或写入报告未尽事项(fail-closed 同构)
|
||
③ 风险: risk ≤ risk_ceiling ∧ (run_command → !is_destructive_command)
|
||
→ 归入 low_risk 并行执行向量(复用既有执行+审计链),
|
||
decided_by = "boundary_auto"(risk 真实等级透传,F-#97 先例防审计失真)
|
||
④ 超上限(含 High、破坏性命令) → 拒绝 envelope{denial_layer:"boundary-risk"},
|
||
记入会话待办清单(4.3),不 insert pending
|
||
```
|
||
|
||
### 3.2 兼容性(不倒退保证)
|
||
|
||
- 无 boundary 声明: 上述分支全部跳过,auto_exec_mode/trust/审批/路径授权全链路现状,零行为变更;
|
||
- ai_approve / ai_authorize_dir IPC 不动: 有边界会话不产生新 pending(黑名单本来也不产生),审批 UI 自然不触发;
|
||
- 审批超时定时器(15 分钟)对边界会话天然不触发(无新挂起),零改动;
|
||
- PathBypass 枚举不加新形态: 边界会话白名单判定在 check_file_tool_auth **调用前**完成(boundary 命中即 Authorized,bypass 参数传 Off 保黑名单),避免与 bypass 开关语义纠缠;
|
||
- 审计: boundary_auto / boundary-dirs / boundary-risk 三种 decided_by/denial_layer 全留痕,无人值守事后可全量追溯。
|
||
|
||
---
|
||
|
||
## 四、无人值守稳定性机制
|
||
|
||
### 4.1 失败分级自愈(增量最小化)
|
||
|
||
| 级别 | 判定 | 处置 | 增量 |
|
||
|------|------|------|------|
|
||
| 瞬态可重试 | 网络超时/5xx/429(复用 retry::is_status_retryable) | 已有: 退避重试+candidate 链,零改动 | 无 |
|
||
| 工具级失败 | 失败 envelope | 已有: 交 LLM 自纠(loop 继续),死循环已被去重缓存+retry guard 治理 | 无 |
|
||
| 探索停滞 | L1/G2 断路器触发 | 改: 熔断求助出口 → 安全停靠(4.2) | 小 |
|
||
| 不可恢复 | Fatal 全 candidate 耗尽 / 边界预算耗尽 / 连续 N 轮零产出(阈值实测后定) | 统一安全停靠出口 | 中 |
|
||
|
||
不新造工具级自动重试层——既有 envelope+熔断已覆盖,自动重试同参数正是 detect_retry_count 刻意压制的行为(反馈_no_guess_api 同源: 盲重试制造风暴)。
|
||
|
||
### 4.2 安全停靠语义(不是死等)
|
||
|
||
现网「非正常终局」五路出口(Fatal/Stale/MidStream/熔断/达轮次)行为不一。统一停靠出口:
|
||
|
||
1. 保存现场: 既有 teardown_round 落库链路不变;
|
||
2. 会话尾部追加停靠说明(system 提示块): 停止原因 / 已完成什么(取本轮 assistant 文本) / **待办清单**(边界外被拒操作 + 未完成事项,数据源=3.1④ 的拒绝记录 + 熔断采样);
|
||
3. emit `AiTaskParked { conv_id, reason, pending_items }` 新事件(前端操作卡: 继续恢复/停止归档,复用 pendingMaxRounds 操作卡骨架——lib.rs:435 既有续/停 IPC);
|
||
4. notify NeedAction 系统通知(托盘场景补位,复用 P3-6 全套);
|
||
5. **不保持 generating=true**: guard 复位(达轮次出口已有先例),用户回来点「继续」走 ai_continue_loop(start_iter 语义沿用: 预算耗尽重计=用户再授权)。
|
||
|
||
### 4.3 进度可观测
|
||
|
||
- 已有零改动: 工具事件流 + 心跳 + 审计表即事实源;
|
||
- 增量: 每 N 轮(建议 5,实测后定)emit `AiTaskProgress { conv_id, round, budget, tokens_used, pending_items_count }`;前端会话头部挂轻量进度条(轮次/预算维度),长任务静默期(如 spawn_agent 子代理长跑)用户可判断「在干活还是死了」。不落新表,事件即逝。
|
||
|
||
### 4.4 完成与异常通知
|
||
|
||
复用 notify.rs 现有三类出口,无需新通知通道;增量仅两处挂点: 停靠出口(4.2)发 NeedAction、边界会话正常收敛发 Completed(emit_ai_completed_once 已挂,核对边界会话不因 incomplete 路径漏发即可)。
|
||
|
||
### 4.5 断点续跑(P2,进程重启后)
|
||
|
||
- 现状: checkpoint 快照已有、pending_approvals 有启动恢复,loop 不自动续;
|
||
- 设计: ai_conversations 新列 `loop_state`(running/parked/finished),边界会话 loop 生命周期同步落库;启动时检测「loop_state=running 但进程重启」→ **不自动续跑**(本地桌面场景,重启即用户在场,自动续跑反而惊吓),侧栏该会话标「任务中断可恢复」+ 一键恢复按钮;
|
||
- V21 迁移教训直接套用(docs/todo.md:860: 全局 COUNT 幂等窗口,中途崩溃→永久残缺被版本号掩盖): 恢复判据必须**按会话逐条落进度标记**(loop_state per-conv),禁止依赖全局内存态或推算;快照恢复走既有 checkpoint 表,恢复粒度=消息级(本轮已落库消息不重放,ai_messages 增量基线既有机制天然支持)。
|
||
|
||
---
|
||
|
||
## 五、信任分级(拍板项)
|
||
|
||
| 档 | 语义 | 载体 | 状态 |
|
||
|----|------|------|------|
|
||
| L1 逐次审批 | 现状: 三档 auto + 审批卡 + 路径授权弹窗 | df-ai-auto-execute-mode | 现网,不动 |
|
||
| L2 任务边界自主 | 本设计主体: 发起时一次拍板,边界内零打断,黑名单/破坏性命令永不放行 | TaskBoundary(会话级) | 本设计 P0 |
|
||
| L3 完全信任 | 等价 skip-permissions: 全档自动+连黑名单也放行 | 存量组合: auto=all + path-auth-bypass=on | 远期可选,UI 不与 L2 并列推荐,标注「含敏感目录」风险;不新造代码 |
|
||
|
||
分级关系: L2 是 L1 之上的会话级增强,L3 是全局级现状开关的组合,三层互不替代。
|
||
|
||
---
|
||
|
||
## 六、分期实施建议
|
||
|
||
### P0 边界模型 + 旁路主干(可独立交付验收)
|
||
- 改动面: 新增 `commands/ai/boundary.rs`(结构+判定+单测)、`commands/ai/mod.rs`(per_conv 字段+IPC 注册)、`conversation.rs`(boundary_json 落库列)、`audit/mod.rs`(判定链插桩:auto_exec_mode 读取处)、`audit/path_auth.rs`(boundary 白名单判定前置)、`audit/approval.rs`(boundary_auto 分流)、迁移一条(boundary_json 列)、前端任务发起配置卡 + useAiConversations 透传;
|
||
- 验收: 边界会话 Medium 工具/白名单路径零弹卡直接执行+审计 boundary_auto;黑名单/破坏性命令/超上限三项被拒且不弹卡;无边界会话全链路行为与改造前逐字节一致(既有测试全绿);
|
||
- 冲突面: audit/mod.rs、approval.rs、path_auth.rs、conversation.rs、chat.rs、state.rs **全部在当前在飞批次工作区改动中**(git status 30+ 文件,befix2/dx1/dx2 三代理在改)——P0 必须等在飞批次合入后开工,或以 worktree 零交集摘出纯新增文件(boundary.rs+前端卡)先行、插桩点后置。串行,禁双头互踩(uswitch-403 同款事故预防)。
|
||
|
||
### P1 自愈 + 通知(依赖 P0 边界字段)
|
||
- 改动面: `agentic/mod.rs`(五路非正常终局统一停靠出口)、`stall_detector.rs`(熔断求助→停靠)、`notify.rs` 挂点、event_bus 新事件 AiTaskParked/AiTaskProgress、前端操作卡+进度条;
|
||
- 验收: 构造 Fatal/熔断/预算耗尽三种场景 → 各自产停靠说明+待办清单+托盘通知,generating 复位,点继续可续跑;
|
||
- 冲突面: agentic/mod.rs 在飞改动中,同 P0 策略。
|
||
|
||
### P2 断点续跑 + 信任分级(依赖 P1 停靠语义)
|
||
- 改动面: `conversation.rs`(loop_state 列+落库点)、`lib.rs`(启动扫描)、侧栏恢复入口;信任分级 UI 是否进设置页等拍板点 7;
|
||
- 验收: 边界会话长任务跑一半杀进程重启 → 侧栏标「可恢复」→ 一键恢复从 checkpoint 续跑不重放已落库轮次;
|
||
- 冲突面: lib.rs 启动段低频改动,冲突小。
|
||
|
||
---
|
||
|
||
## 拍板点清单
|
||
|
||
| # | 决策 | 选项 | 建议 |
|
||
|---|------|------|------|
|
||
| 1 | risk_ceiling 是否开放 High | A 封顶 Medium;B 开放 High 但破坏性命令仍拒 | **A**。High(run_command 等)无人看过命令串风险不可控;确需 High 归 L3 完全信任档 |
|
||
| 2 | 边界存储形态 | A 会话级 JSON 列;B 独立任务表 | **A**。任务与会话 1:1,独立表是过度设计;字段随会话同亡零清理成本 |
|
||
| 3 | 边界外动作处置 | A 拒绝+记待办随停靠报告;B 拒绝即停靠;C 弹卡(违背无人值守) | **A**。fail-closed 同构子代理,LLM 有自纠空间,缺口随停靠说明透出 |
|
||
| 4 | 进度事件频率 | A 每 5 轮;B 每轮;C 不做 | **A**。B 噪音,C 牺牲静默期可观测;具体值实测后定 |
|
||
| 5 | 重启后自动续跑 | A 不自动,标记+一键恢复;B 自动续跑 | **A**。本地桌面重启即用户在场,自动续跑惊吓且 V21 教训表明恢复判据须可人工确认 |
|
||
| 6 | 边界会话内子代理是否放宽 | A 维持 Low-only fail-closed;B 继承父边界 | **A**。子代理无监督面,放宽破坏隔离语义;Medium 需求由父会话边界内直接执行 |
|
||
| 7 | L3 完全信任是否进设置页 UI | A 不做 UI,文档说明存量开关组合;B 设置页显式三档 | **A(P2 再议 B)**。存量开关已可达,先验证 L2 使用率 |
|
||
| 8 | 中途改边界 | A 全不可改;B risk/目录不可改,预算可由用户中途调 | **B(补遗后修订)**。一次性拍板约束的是「AI 不回头问用户」,不是「用户不能动自己的任务」;risk 上限与目录白名单一次性不可改(安全边界),预算字段开放用户中途收紧/放宽(经 #12);**纠偏注入(7.2)≠改边界**——只注入指令文本,边界字段零触碰 |
|
||
|
||
---
|
||
|
||
## 补遗(2026-10-04 二次拍板追加,与主体章节并列生效)
|
||
|
||
> 追加两维:效率(任务完成得快、tokens 高效)与可观测/可控。不重写主体章节,冲突处以本补遗为准。
|
||
|
||
## 七、效率维度
|
||
|
||
### 7.1 token 效率(复用为主,增量小)
|
||
|
||
| 设计点 | 既有件(复用) | 无人值守增量 |
|
||
|--------|--------------|-------------|
|
||
| 上下文膨胀控制 | ContextManager::build_for_request 预算裁剪;namespace_store 大工具结果进 namespace 主队列留引用(audit/mod.rs 两处 T2);TOOL_RESULT_COMPRESS_ENABLED 工具结果压缩;TOPIC_MARKER 话题标记;自动 checkpoint | 长任务场景将「工具结果冗余」放大,既有链路已按预算自动收敛,**零新增**;视图裁剪滚动摘要(派工决策单 B2 待做)落地后收益直接作用于长任务,不另立项 |
|
||
| 重复调用抑制 | 只读工具跨轮缓存+轮内去重(audit/mod.rs:976+,cache_hit_warning 递增威慑);High 去重缓存;detect_retry_count 断重试循环;G2 探索熔断(同签名重复派发检测) | **自动降级**:缓存命中计数达阈值(现警告头已有,阈值实测后定)时自动插入一条 system 降级指令(「同参调用已 N 次,必须换策略或写入报告」),把「威慑」升级为「强制转向」;G2 熔断在无人值守下直接走安全停靠(4.1 已定),不再等用户 |
|
||
| 任务级模型分级 | router ModelTier(Code/Debug→Heavy/Chat→Fast,agentic/mod.rs:1617 tier tiebreak);resolve_model_with_override;spawn_agent 的 model 参数(子代理可指定模型) | 边界配置卡加可选「子代理模型」高级项;**默认策略: 子代理派发缺省走轻量模型**(重活主循环继承会话模型,机械探索活子代理小模型),路由复用 ModelTier 既有分档,零新机制(#10) |
|
||
| prompt 瘦身/任务书复用 | spawn_agent 任务书自包含语义(子代理看不到父对话,不重复注入父轨迹);GOAL_PIN 钉目标防逐轮重述(GOAL_INJECT_BANNER);SKILL_LIST 描述截断 80 字 | 零新增——「任务书复用而非重注入」正是子代理架构的既有形态;长任务多轮目标防漂移由 GOAL_PIN 覆盖 |
|
||
|
||
### 7.2 速度设计点
|
||
|
||
| 设计点 | 机制 | 与既有的关系 |
|
||
|--------|------|-------------|
|
||
| 并行工具批最大化 | 旁路后 Medium 工具归入 low_risk 向量走 join_all 并行(§3.1③) | **本设计免费提速点**:现网 spawn_agent(Medium)逐个走审批串行挂起;边界会话内 LLM 一轮发多个 spawn_agent → join_all 天然并行,上限 MAX_TOOL_CALLS_PER_ROUND=8。**P0 零代码副产品,须在验收清单标注** |
|
||
| 子代理并行编排 | 同上——并行编排不需要新调度器,是「旁路 × join_all」的组合效应 | 零新增;子代理各自独立预算熔断(三重熔断互不挤占),父侧只等 join_all 汇合 |
|
||
| 空轮/确认轮消除 | 无人值守任务书模板追加一条纪律:「不向用户提问;信息不足按明确假设继续,假设写入报告」;纯文本收敛轮(无 tool_calls)即终态,不存在「等确认轮」 | 复用 PURE_GREETING_TOOL_GATE 与 G2 熔断兜底异常空转;确认类行为在无人值守下=fail-closed 反面(挂起等输入),任务书纪律+边界语义双重压制,P0 随配置卡文案交付 |
|
||
|
||
### 7.3 效率度量口径(为「快」提供数据)
|
||
|
||
- **任务耗时** = 首条 user 消息 → 终态事件(AiTaskParked / 正常收敛)的挂钟差;落库复用 ai_conversations.created_at + 终态时间戳(补 parked_at 小列或复用 updated_at,P0 定);
|
||
- **token 花费** = 会话累计 prompt/completion 列(已有,save_conversation 落库)+ **子代理单列**(SubAgentOutcome rounds/tokens 已经 AiAgentFinished 透出;子代理出口整轨迹落库但 token 不进父 TokenAccumulator,故口径必须「父会话 / 子代理 / 合计」三段呈现,禁混算,#11);
|
||
- **每轮均摊** = 合计 token / 轮次(趋势指标,识别哪段任务烧钱);不做成本换算(密钥价目不进引擎,数据不出门边界)。
|
||
|
||
**分期归属**: 并行编排/确认轮消除/度量口径落库=P0(大部分零代码或小列);缓存降级注入+子代理默认小模型=P1;度量面板汇总视图=P2(随可观测面板同批)。
|
||
|
||
## 八、可观测/可控维度
|
||
|
||
### 8.1 可观测(10 秒三问:跑到哪/花多少/剩多少)
|
||
|
||
| 呈面 | 数据源(复用) | 新增量 |
|
||
|------|--------------|--------|
|
||
| 当前进度呈面(阶段/当前动作/轮次与 token/预算剩余) | 当前动作=最近一条 AiToolCallStarted 的 tool+GoalMeta 摘要(goal_of 已有,如 run_command→「执行 xxx」);轮次/token=AiTaskProgress 事件(§4.3 已设计) | 会话头部常驻任务面板(#12):一行「阶段·当前动作」+进度条(轮次/预算)+token 累计;打开界面即答三问,不依赖滚动消息流 |
|
||
| 子代理树状态一览 | SubAgentRegistry(parent→children 内存注册表,已有)+ AiAgentFinished(每子代理终态 rounds/tokens/rejected 已透出) | 树 UI 为纯前端消费:运行中子代理=spawn 事件实时挂节点,完成=Finished 回填终态;父会话面板内嵌一行树,不建独立页面 |
|
||
| 花费实时累计 | TokenAccumulator 快照 + usage_delta_since 增量口径(均已有) | AiTaskProgress 携带 tokens_used 即可,零新事件 |
|
||
|
||
### 8.2 可控(逐项标注复用/新建)
|
||
|
||
| 操作 | 机制 | 复用 or 新建 |
|
||
|------|------|-------------|
|
||
| 中途停止 | ai_chat_stop → stop_flag 置位 + cascade_stop_children(Stop form)级联子代理 | **纯复用**,零改动;边界会话停止=任务终止,停靠说明照发(4.2) |
|
||
| 暂停/恢复 | 「停止 + 一键恢复」组合即暂停:stop 保现场落库,恢复走 P2 断点续跑入口(ai_continue_loop, checkpoint 粒度) | **复用组合,不新造「暂停态」**(宁少勿预留——独立暂停态需新增 loop 挂起检查点,收益不抵复杂度);P2 交付 |
|
||
| 中途纠偏(向运行中任务注入指令) | ai_chat_force_send 既有通道:打断当前轮 + 注入新 user 指令 + F1 并发 epoch 新 loop 接管(旧 loop 让位,epoch 机制已有)+ 级联 Stop form 子代理 | **纯复用**;语义定义:纠偏只注入指令文本,边界字段零触碰(**纠偏≠改边界**,与拍板点 8 对齐);P0 即可用,任务面板加「插话」入口即可(前端小改) |
|
||
| 接管转人工 | = 任务终止的单向形态:用户纠偏注入「停下我来」或点停止 → 移除 boundary 标记,会话回落 L1 逐次审批模式继续对话 | **复用 stop + boundary 摘除**;单向降级(任务态→普通态)不是边界修改,不违反拍板点 8;P1 随停靠操作卡交付「转人工」按钮 |
|
||
| 预算中途调整 | IPC ai_update_task_boundary 仅开放 budget 三字段(轮次/token/挂钟),risk/目录拒改 | **新建一个窄 IPC**(P1);用户主动调整合规(拍板点 8 修订后口径),UI 在任务面板预算条旁放开编辑 |
|
||
| 与看门狗/级联取消的关系 | 纠偏/接管经 epoch 接管不与前端 watchdog 冲突(新 loop 自带 guard+heartbeat);级联取消(Stop/Delete 双形态)覆盖停止与删除两路 | 既有机制全覆盖,零新增 |
|
||
|
||
**分期归属**: 中途停止/纠偏注入=P0(复用件,仅前端入口);任务面板+子代理树+预算调整+接管=P1;暂停/恢复=P2(与断点续跑同批,共享恢复入口)。
|
||
|
||
## 补遗新增拍板点(续编)
|
||
|
||
| # | 决策 | 选项 | 建议 |
|
||
|---|------|------|------|
|
||
| 9 | 缓存命中的自动降级策略 | A 命中超阈值自动插 system 强制转向指令;B 维持警告头威慑 | **A**。无人值守无人读警告,机制必须自己踩刹车;阈值实测后定 |
|
||
| 10 | 任务级模型分级默认 | A 边界卡显式选;B 子代理默认轻量模型+主循环继承会话模型,卡内高级项可覆盖;C 不做 | **B**。自动分级零配置收益最大,显式选择作兜底;轻量模型具体指认实测后定 |
|
||
| 11 | token 度量口径 | A 父会话/子代理分列+合计;B 只算父会话 | **A**。子代理 token 不进父 TokenAccumulator,混算会严重低估;合计是「任务花费」的正口径 |
|
||
| 12 | 任务面板形态 | A 会话头部常驻面板(进度+花费+预算+插话+树);B 仅侧栏徽标点开看 | **A**。「10 秒三问」要求免点击可达;徽标作为托盘化场景补充 |
|
||
| 13 | 预算中途调整方向 | A 双向(收紧/放宽)都允许;B 只许收紧 | **A**。用户主动放宽=追加授权,与「一次性拍板」不冲突(拍板约束 AI 不约束用户) |
|
||
|
||
## 九、效率补遗二:u-claw 实战思想迁移(2026-10-04,历史会话汲取)
|
||
|
||
> 来源:`~/.u-claw/willcard/decisions.jsonl`(298 条决策,效率相关 60+ 条实证)+ devflow 知识库。
|
||
> 基调(用户原话):「从我历史使用 u-claw 的历史会话、我主张的思想中汲取知识辅助设计和决策;无人值守同时也要确保极高效率任务推进能力」。
|
||
> 以下思想在 u-claw 侧均经生产实证,迁移 devflow 时逐条标注落点与分期。知识库已沉淀两条 workflow_optimization(f6cd9de8 派工契约/c2c0a444 A/B 层纪律)。
|
||
|
||
### 9.1 派工契约:颗粒约束+验收前置+首轮任务图(u-claw 09-25/09-30 拍板)
|
||
|
||
- **废除时长预估**:不要求「预计 N 分钟」——u-claw 实证时长预估无锚定价值,超时即杀导致活任务被误杀;
|
||
- **替代契约**:①任务书必含**验收命令**(一轮内自证完成并带回验收证据) ②**超一轮未完成=派工颗粒过大**,主控拆批重派,不盲等 ③杀进程仅作卡死/跑偏兜底;
|
||
- **首轮任务图**(09-30 第 7 条):整包委托语义令下,round-0 **必须产出任务分解+派工清单**再动手,禁主控先亲手做首个任务(亲手兜底仅 1-2 行 typo 级);
|
||
- **devflow 落点**:无人值守任务书模板加「round-0 规划纪律」段(P0 文案);spawn_agent 超轮触发拆批提示(而非熔断即弃);子代理任务书 acceptance 对齐(批 2 指引真空项同源改造)。
|
||
|
||
### 9.2 A/B 层 prompt 纪律:预算行进 user 尾部不毁缓存(u-claw 08-31)
|
||
|
||
- system 层(A):编排纪律五判据(耗时意识/试错预算/委派契约/超时自查/并行合并)——稳定段进 cache_control;
|
||
- **每轮 user 尾部(B):任务预算行**(当前阶段/剩余轮次/剩余 token)——user 消息注入不动 system 前缀,prompt cache 零失效(u-claw 实证口径);
|
||
- **devflow 落点**:对齐已拍板的 AC-EFF-C0-2(稳定段/易变段分离)——预算行作为易变段追加到消息流尾部,AiTaskProgress 的前端展示与后端注入同源数据;**P1 实施**(与 A9 缓存降级同批)。
|
||
|
||
### 9.3 换代水位 70% 主动切(u-claw 09-03)
|
||
|
||
- rollover 判据=窗口×70%(如 1M→700K),**不等硬爆**;水位取值=最后一条 assistant 行 usage(真实窗口口径,非估算);
|
||
- **devflow 落点**:无人值守长任务压缩触发阈值联动此口径(maybe_auto_compress 判据核对,P1 顺带);devflow 主循环已有压缩链,补「长任务下水位提前」参数化。
|
||
|
||
### 9.4 文件互斥分区并行(u-claw 09-29-6)
|
||
|
||
- 多代理并行按**文件清单显式隔离**,各自批次文件集无交集才能并行写;
|
||
- **devflow 落点**:spawn_agent 派工时若子代理任务书含明确目标文件集,主循环日志登记防重叠(软约束:提示词级「不要改本任务书之外的文件」已有,补主控侧登记);硬锁在 namespace owner 隔离(已设计)同批考虑。
|
||
|
||
### 9.5 卡片活性与聚合回填(u-claw 09-06 三连拍板)
|
||
|
||
- 后台执行被否决:**用户以为任务丢失**;卡片须延续活性+回填结果+多任务聚合展示;
|
||
- **devflow 落点**:对齐 A12 任务面板+AiAgentFinished 完成卡(已设计);面板补「子代理状态/任务清单/等待原因/危险动作告警」四件套语义(u-claw 08-29 processing 卡四件套实证有效),P1 面板实施时并入。
|
||
|
||
### 9.6 失败按码分级冷却(u-claw 09-13)
|
||
|
||
- 402/401(确定性失败)冷却 10min,其余(瞬态)30s——**确定性失败不烧重试预算**;
|
||
- **devflow 落点**:对齐已修的「Retryable/Fatal 分层」(10-02 批次2),补冷却时长分级(401/403/404 系 10min,超时/网络 30s);retry.rs 已有骨架,P2 效率批接线。
|
||
|
||
### 9.7 高置信自主推进决策法(u-claw 10-02)
|
||
|
||
- 决策项先查历史指令(will-card+memory+decisions.jsonl)辅助直裁;实在不决记录挂起,**自主连续推进**;
|
||
- **devflow 落点**:已对齐——拍板集+知识库检索+挂起登记(todo 遗留),无需新增;持续把用户长期偏好(如「决策影响边界简洁呈现」「列表禁表格」)沉淀进知识库,供 AI 直裁。
|
||
|
||
### 9.8 汇报与决策呈现纪律(u-claw 09-28)
|
||
|
||
- 决策须给**足够且简洁易读的影响边界**(降低决策心智投入);默认列表禁表格(宽列截断看不见内容);
|
||
- **devflow 落点**:停靠卡/NeedAction 通知文案规范(A12 面板实施时并入:一行定性结论+决策级技术事实+影响边界,列表化呈现)。
|
||
|
||
### 分期并入
|
||
|
||
| 思想 | 分期 |
|
||
|---|---|
|
||
| 9.1 round-0 任务图+验收契约 | **P0 文案**(任务书模板,P0 收尾即生效) |
|
||
| 9.2 预算行 user 尾注入 | P1(与 A9 同批) |
|
||
| 9.3 水位 70% 联动 | P1(压缩链顺带) |
|
||
| 9.4 文件互斥登记 | P1(子代理批同做) |
|
||
| 9.5 面板四件套 | P1(A12 面板) |
|
||
| 9.6 冷却分级 | P2(效率批) |
|
||
| 9.7/9.8 | 已对齐/随 P1 文案 |
|