docs: define runtime checklist display scope

Specify read-only OpenCode and Continue checklists above conversations, including remote Agent delivery and validation requirements. Record native runtime test evidence and distinguish planned work from implemented behavior.
This commit is contained in:
mesalogo
2026-09-15 15:59:13 +08:00
parent f8d07419d2
commit 34215c72a1
7 changed files with 249 additions and 0 deletions
@@ -13,7 +13,13 @@
| [执行记录存储与升级回收](./execution-history-storage.md) | 子任务过程差量存储、远程去重、旧库转换、空间回收及升级界面 |
| [Runtime 交互边界](./runtime-interactions.md) | 原生权限、结构化问答、后台拒绝、终端交互、并行与输出、消息请求状态及资源生命周期规则 |
| [Runtime 进程复用技术设计](./runtime-process-reuse-technical-design.md) | 跨 Runtime 资源调研、锁定协议证据、进程与会话拆分、远端模型桥、实施顺序和性能验收 |
| [Runtime 执行清单技术设计](./runtime-checklist-technical-design.md) | OC/CN 原生清单提取、远程 Agent 传递复用、消息恢复与真实部署验收;尚未实现 |
当前尚未拆出独立 User Stories、功能逻辑和 UI 设计文档;产品场景与验收保留在现有 PRD,
Runtime 资源状态规则由交互边界文档维护。浏览器多实例和 Runtime 进程复用涉及不同的
跨进程身份与工具路由,分别使用技术设计文档维护。
执行清单的需求、场景和顶部布局见 [PRD](./prd.md#131-runtime-执行清单),状态规则见
[Runtime 交互边界](./runtime-interactions.md#runtime-执行清单)。本目录拥有该功能;
[Task 与 Job](../task-and-job/README.md)拥有产品任务领域,
[远程主机](../remote-host/technical-design.md#执行清单接入范围)拥有远程部署与连接边界。
+49
View File
@@ -937,6 +937,55 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
应用通知;预览失败、终端断线、Host Key 变化、监督证据失效等需要本地恢复的错误留在面板
内。同一事件不得同时重复显示为面板警告和应用通知。
### 13.1 Runtime 执行清单
本节为待实施设计。用户需要在对话顶部查看 Agent 本轮列出的工作项及完成情况,避免在
工具记录中反复查找。这里的“执行清单”由 Runtime 更新,术语边界见
[Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md#17-runtime-执行清单)。
- **FR-CL1**:接入 OpenCode(OC)的 `todowrite` 与 Continue(CN)的 `Checklist`,
范围包括本地及远程 GoodBuddy Agent 上运行这两个 Runtime。远程 CN 的部署和正常请求
路径也属于交付范围,当前可用程度见[进度](./progress.md#2026-09-15-runtime-执行清单设计未实现)。
- **FR-CL2**:顶部展示本轮最新有效清单,更新按整份替换处理,支持明确清空。每轮请求、
会话、项目、执行空间与 Runtime 的清单分别归属;普通聊天续轮不能沿用旧清单冒充本轮进度。
- **FR-CL3**:清单只读,用户不能手动勾选。请求完成、失败或取消保留清单实际状态,
不自动完成工作项;原生工具调用继续进入消息与活动记录。
- **FR-CL4**:重新打开会话可恢复已保存的清单及请求结果,远程重连遵循已有 Agent 恢复
流程,不重新发送模型或工具请求。没有原生清单的请求不显示空占位。
ACP 仅是传输及远端协议,不分类为 Runtime。DeepSeek Harness(DS)真实默认环境无
todo/plan,本次不为其增加工具。也不增加 plan 工作模式、计划文档、计划编辑器或定时任务
能力;只有格式已确认的原生 plan entries 可以适配清单。
#### 顶部布局
执行清单位于聊天内容区顶部、已有 Task 上下文栏下方、消息流上方;没有 Task 时仍可独立
显示。它不占用窗口标题栏操作区,也不替换 Task 摘要、任务索引或右侧 Runtime 栏目。
布局遵循 [UI-DESIGN](../../../UI-DESIGN.md#610-应用顶栏与全局操作)。
默认折叠为一行“执行清单 · 已完成 m/n”,有进行中条目时附简短摘要;展开后按原生顺序
显示内容、状态及原生提供的优先级。行内状态使用图标和“待处理 / 进行中 / 已完成 / 已取消”文字,
不用可勾选 Checkbox,也不根据位置推测优先级或进行中状态。请求结束后的摘要附真实
请求结果,例如“已取消”,不改变条目状态。后台更新不强制展开、不抢焦点。
展开按钮提供 `aria-expanded` 和 `aria-controls`,支持 Enter/Space,折叠后焦点留在
按钮;实时区域只播报摘要变化。复用全局颜色、间距和字体令牌,浅深主题均可读。窄窗口
摘要截短、展开内容换行并有界滚动,保留完成计数、请求结果与输入区;200% 缩放时仍可
操作。没有清单或收到有效空清单时整行隐藏,历史内容仍按消息归属查看。
#### 场景验收
| 场景 | Given / When / Then | 需求 |
| --- | --- | --- |
| US-CL1,连续更新 | OC/CN 本轮产生清单并修改、重排或删除条目;顶部显示最新完整内容,工具活动仍可查 | FR-CL1–FR-CL3 |
| US-CL2,请求隔离 | 同会话开始下一请求、切换 Runtime 或并行使用另一会话;旧轮迟到事件不覆盖当前清单,历史按原归属保留 | FR-CL2、FR-CL4 |
| US-CL3,失败与取消 | CN 更新失败或请求被取消;失败候选不替换上次有效清单,取消不把未完成项勾完;有效空清单清除顶部 | FR-CL2、FR-CL3 |
| US-CL4,本地与远程恢复 | 重新打开本地会话或重连共享 Linux Host 上的 OC/CN 请求;已有记录按原请求恢复,重复事件不重复展示,不重新调用模型或工具 | FR-CL1、FR-CL4 |
| US-CL5,无清单与无障碍 | DS 默认请求或普通 Markdown/list 工具输出没有已确认清单;顶部不出现伪清单;有清单时键盘、窄窗口及浅深主题可用 | FR-CL1–FR-CL3 |
行为规则见 [Runtime 交互边界](./runtime-interactions.md#runtime-执行清单),接入与验证见
[技术设计](./runtime-checklist-technical-design.md)。
## 14. 性能与资源边界
- 工作栏关闭或面板实例关闭时停止对应非必要画面和高频日志推送,但保留 Main 中的受管运行。
@@ -1,5 +1,40 @@
# 工作栏实现与验证进度
## 2026-09-15 Runtime 执行清单设计(未实现)
对应 FR-CL1–FR-CL4。用户本轮明确只完善设计与进展文档,不改代码;
[设计与验收](./runtime-checklist-technical-design.md)不代表功能已经接入或发布。
此前调研已通过真实模型完成以下本地测试;本次文档更新未重新运行测试:
| Runtime | 已确认的本地研究结果 | 调用口径 |
| --- | --- | --- |
| OC 1.18.29 | `todo.updated` 与 `session.todo` 为 `content/status/priority` 完整替换,无 item ID | 3 个真实模型轮次 |
| CN 1.5.47 | `Checklist.checklist` 为 Markdown `- [ ]` / `- [x]` 完整替换,成功后才提交 | 3 次真实 HTTP 调用 |
| DS | 真实默认环境无 todo/plan;本次不加工具 | 1 次真实模型 HTTP 调用,返回 200 |
上述口径不合并计算为同一种调用次数,也不算 GoodBuddy 顶部清单端到端通过。本轮新增
模型调用为 0,未运行代码测试或远程部署验证。
本轮只读源码检查确认 OC 普通工具输入及 CN 宿主工具输入存在 4,000 字符截断;
Agent 已传递带 Session、binding/operation 归属的通知,桌面已有 ACP plan/tool 消费,
但 plan entries 当前降为状态文本。这些链路可供设计复用,尚未验证清单端到端接入。
| 部署 | 已有能力与本功能可用程度 | 剩余工作 |
| --- | --- | --- |
| 本地 OC/CN | 原生清单格式已有上述实测结论;顶部清单未实现 | CL-P1、CL-P2、CL-P4 待实施及验证 |
| 远程 OC | 已有托管 Agent 安装与请求路径,其历史验证见远程文档;本功能没有远程实测 | 原生 entries/tool 格式、完整传递及 CL-P3、CL-P4 待验证 |
| 远程 CN | 当前受管安装、项目校验与 Runtime 创建只支持 OC,不能声明 CN 已可部署使用 | CL-P3 需补齐 CN 真实部署路径,再验收 CL-P4;当前本功能未验证 |
未决技术点:远程 OC/CN 实际发送的原生清单格式与等价性、CN 原生清空表示及 Markdown
接受规则、现有消息/事件字段的最小扩展位置、CN 受管工件与启动/模型桥接入方式。
产品范围与隔离规则已明确,不因这些待办缩减远程 CN 范围或增加 DS 工具、plan 模式与
文档功能。共享 Linux Host 的清单及重连验收全部待验证。
文档检查:已按 `deai-writing` 审校新增内容;新技术设计扫描为 0 个阻断项、12 个复核项,
复核项为必要的实现边界和验收枚举,按原意保留。新增相对链接与章节锚点已人工核对。
`git diff --check` 通过,仅输出工作区 LF/CRLF 提示;未修改本轮范围外的既有改动。
## 2026-09-14 Runtime 进程复用(实施中)
对应 FR-RR1–FR-RR6,设计及完整验收清单见
@@ -0,0 +1,106 @@
# Runtime 执行清单技术设计
状态:设计阶段,尚未实现。需求、场景与顶部布局由 [PRD](./prd.md#131-runtime-执行清单)
维护,替换、隔离和终态规则由 [Runtime 交互边界](./runtime-interactions.md#runtime-执行清单)
维护。研究证据与交付状态见[进度](./progress.md#2026-09-15-runtime-执行清单设计未实现)。
## 1. 原生数据与提取位置
| Runtime / 路径 | 已确认格式与设计接入 |
| --- | --- |
| 本地 OC 1.18.29 | `todo.updated` 与 `session.todo` 返回完整条目列表,字段为 `content/status/priority`,无 item ID;以原生更新事件驱动本轮整份替换 |
| 本地 CN 1.5.47 | 精确原生工具 `Checklist` 的参数 `checklist` 是 Markdown 勾选列表,`- [ ]` / `- [x]` 表示未完成/完成;按一次成功调用提交完整替换 |
| 远程 OC/CN | 先核对实际部署版本、原生输出与 Agent 传递结果;只有格式已确认且来源归属明确的原生 plan entries 或精确清单工具参数可以映射,当前尚无本功能远程实测 |
`opencode-runtime.ts` 当前将普通工具 input 经 `boundedToolDetail(..., 4_000)` 转成
展示字符串。接入应在 SDK 原始事件层消费 `todo.updated`;如需核对 `todowrite` 参数,
必须在该截断之前处理。`session.todo` 是 Session 当前快照,读取结果必须与请求生命周期
关联;不在每轮开始时无条件读旧快照充当新清单,也不轮询代替事件。
CN 的提取位置在 `continue-host-adapter.ts`:宿主产生工具事件、HTTP 状态合并及输入
校验均存在 4,000 字符展示限制,不能等到 `continue-runtime.ts` 收到截断字符串后再解析。
宿主应在最早的原始参数层提取 `checklist`,按工具调用 ID 保留候选,结合最终成功状态
提交;成功帧省略参数时使用同次调用的候选,失败不得提交。普通工具事件继续沿现有路径
流转。超出 4,000 字符的清单需要独立验证完整性,但不扩大所有普通工具输入的展示上限。
Markdown 解析只适用于已确认的 CN `Checklist.checklist`,不扫描助手正文或其他工具
输出。空数组在统一事件中明确表示清除;CN 原生如何表达空清单,以及空白、大小写和
非条目行的实际接受规则,实施时核对后固定解析规则。未确认或无效输入保留旧清单,
不能误当清空。
## 2. 统一事件与消息归属
拟在现有 Runtime 事件联合中增加完整清单事件,承载 `requestId`、条目数组和原生来源;
条目包含 `content`、`status` 及可选 `priority`。最终命名随实现确定,不设计条目级增删
协议或稳定 item ID。空数组必须经过 schema、IPC、消息投影和保存链路,不能被“无内容”
过滤丢弃。
Main 使用现有请求到助手消息的映射投影清单,Renderer 顶部读取该消息的最新有效状态。
同一请求若同时观察到原生清单事件与其工具记录,只以前者更新清单,后者保留活动;不能
提交两次替换。原生父 Session、请求开始/结束边界需共同校验,子 Session 或旧请求事件
不得通过当前活动请求映射到新轮。
优先扩展现有消息 metadata、Runtime 事件和数据库投影,历史清单与所属助手消息一起保存。
远端沿用事件提交、消息投影和 ACK 的既有事务及去重规则;相关存储边界见
[执行记录存储](./execution-history-storage.md)。实施前核对本地会话与远程任务实际落库
字段,选择能复用的最小表示。不新建清单数据库、独立快照系统、恢复日志或持久化服务。
旧消息没有结构化清单时保持缺省,不从已截断工具字符串或状态文案补造历史。
## 3. 远程 Agent 与 ACP 复用
本次源码检查确认以下传递位置,属于设计依据,不是本功能远程验证结果:
1. `AgentAcpConnection` 按原生 `sessionId` 分派 `sessionUpdate`;
`AgentOwnedAcpPrompt` 校验 Session 后,以 `bindingId/operationId` 将通知写入
既有 semantic transcript。
2. `ProtocolRemoteRuntimeChannel` 已有 transcript 读取/ACK、身份核对,以及 ACP
channel 恢复与重放;`AcpRemoteRuntime` 消费 `session-update` 并转换桌面事件。
3. `AcpRemoteRuntime` 当前将 `plan.entries` 及 `plan_update` 的 items 转成 `status`
字符串;markdown/URI 也只形成状态消息。工具事件按 `toolCallId` 合并 `rawInput`、
`status` 和结果,再有界保留。清单提取应发生在结构丢失或截断前。
优先复用上述通知和 transcript,不另建远端清单通道。对实际 OC/CN 部署确认过的
`plan.entries`,或已确认等价的 `plan_update` items,校验条目字段和状态后转成统一
清单事件。普通 `status`、plan markdown/URI、`plan_removed` 文案以及泛化工具名均不
触发清单更新;在没有确认对应原生清单身份前,`plan_removed` 也不能清空顶部。
若远程原生输出走精确清单工具,须确认原始参数、调用身份与成功状态确实贯穿 Agent,
再按同一提取规则接入。是否能直接复用原生 entries,或需补充最小 Agent 适配,取决于
真实格式证据,不能根据 ACP 类型定义推断 OC/CN 一定会发送。ACP 是协议,Runtime 身份
仍为 OC 或 CN。
当前托管 SSH 产品及受管安装、校验、创建链路只支持 OC,详见
[远程范围](../remote-host/technical-design.md#执行清单接入范围)。远程 CN 交付需补齐
受管工件、安装与启动、项目选择/校验及原生事件接入,确认 Main 模型桥、请求归属、取消
和已有恢复流程能用于该部署。不能只放开选择菜单或使用本地 CN 调远程模型来宣称完成。
重连按[既有 ACP 与断线规则](../remote-host/technical-design.md#acp-与断线)执行。
已接受 Prompt 使用原 binding/operation 恢复,清单从已提交消息和其后的既有事件恢复;
重复事件不重复展示。连接丢失不表示条目完成,不为恢复清单重新发送 Prompt、模型请求或
工具调用,也不新增独立重连机制。
## 4. 实施与验收
| 阶段 | 必须完成的工作 | 对应需求 |
| --- | --- | --- |
| CL-P1 | 原始层提取、严格格式校验、统一事件及请求归属;保留工具活动 | FR-CL1–FR-CL3 |
| CL-P2 | 消息投影和既有存储恢复、顶部只读布局、空数组清除及终态展示 | FR-CL2–FR-CL4 |
| CL-P3 | 确认远程 OC 原生格式,补齐远程 CN 真实部署与事件接入,复用 Agent 传递和恢复 | FR-CL1、FR-CL4 |
| CL-P4 | 本地与共享 Linux 真实 Host 逐项验收,记录版本、结果、调用口径与剩余阻塞 | FR-CL1–FR-CL4 |
以下均为待执行验收,本次文档工作不运行模型或代码测试:
- 本地 OC/CN 各经桌面正常发送路径产生并连续修改清单,检查新增、修改、重排、删除、
重复文本、有效清空及超过 4,000 字符的完整内容;CN 成功才替换,失败保留前值。
- 同会话连续两轮、并行会话、切换 Runtime/项目/执行空间、旧轮迟到事件和子会话事件
不串数据;完成、失败、取消不改写条目状态。默认 DS、任意 status/Markdown/list
工具不生成伪清单,工具活动仍可查。
- 本地会话重新打开及应用重启恢复历史;顶部折叠、键盘操作、浅深主题、窄窗口和 200%
缩放符合 PRD,保存与重放后的空清单不会恢复旧内容。
- 在共享 Linux x64 真实 Host 使用开发中的 Agent 与实际部署的 OC/CN,分别从远程项目
完成原生清单更新、取消、断线续接及历史恢复。沿用
[Agent 开发验证规则](../../../AGENTS.md#goodbuddy-agent-development-validation),
LAN/VPN 是同一机器的两条路径,不能计作两台 Host。
- 逐个记录 OC/CN 的安装、启动、模型请求、清单传递、顶部显示、取消和重连结果;基础
Runtime 成功不等于清单通过。任一步未执行写“待验证”,被外部条件阻塞则记录原因,
不以 mock、协议 fixture 或本地成功代替远程验收。
@@ -99,6 +99,38 @@ DeepSeek Harness 按调用 ID 保留名称、输入和摘要,结束事件省
实现与真实 Runtime 验证证据见[进度记录](./progress.md)。
## Runtime 执行清单
本节为未实现的状态设计,对应 [FR-CL1–FR-CL4、US-CL1–US-CL5](./prd.md#131-runtime-执行清单)。
原始格式和传递边界由[技术设计](./runtime-checklist-technical-design.md)维护。
清单属于一次请求及其助手消息。沿用项目、执行空间、Conversation、Runtime 选择和
原生 Session 到请求的既有映射;远端还需核对 binding/operation。不能仅以原生 Session
或 Conversation 为键更新顶部,因为同一会话会连续执行多轮请求。
| 输入或操作 | 清单与顶部行为 |
| --- | --- |
| 本轮尚无有效清单 | 隐藏顶部清单,不复制上一轮内容 |
| 收到本轮有效完整清单 | 按原生顺序整体替换,包括修改、删除、重排和重复文本;不按条目文本合并 |
| 收到有效空数组 | 记录明确清空并隐藏;空数组与缺少清单字段不同 |
| CN 调用进行中 | 候选只按该请求的调用 ID 暂存;成功后才提交完整替换 |
| CN 调用失败、取消或格式无效 | 丢弃该候选,保留上次有效清单,工具记录保留实际结果 |
| 请求完成、失败、取消或中断 | 冻结最新已提交清单,并显示请求真实结果;不推断条目完成,迟到输入不改写已结算清单 |
| 同一会话开始下一轮 | 顶部转向新请求,上一轮清单留在原消息;旧轮事件不得归入新轮 |
| 切换会话、项目、执行空间或 Runtime | 只读取目标归属的数据;原请求在原归属结算,不把原清单标为新 Runtime 的进度 |
| 查看历史或重连 | 从原消息及既有事件恢复;按原请求和远程来源顺序去重,不能用最新原生 Session 快照覆盖历史轮次 |
条目状态支持 `pending`、`in_progress`、`completed`、`cancelled`。OC 原生提供的 priority 保留;
CN 未勾选项映射为 `pending`,已勾选项为 `completed`,不推断 `in_progress` 或 priority。
OC 无稳定 item ID,视图索引仅服务本次完整列表渲染,不生成跨更新的条目身份。
清单内容不创建、调度或完成产品 Task,也不改变底部请求状态。清单更新与工具活动可以
同时保留,但顶部计数只来自已确认的结构化清单,不能反向解析普通状态文本、任意
Markdown 或名称含 `list` 的工具。子会话清单不覆盖父请求顶部。
以上产品状态规则已明确;远程 CN 接入、原生格式确认及历史字段选择仍属技术待办,见
[进度记录](./progress.md#2026-09-15-runtime-执行清单设计未实现)。
## Runtime 资源生命周期
本节对应 [FR-RR1–FR-RR6、US-RR1–US-RR4](./prd.md#141-runtime-资源复用),
@@ -271,6 +271,19 @@ Execute 直接启动已签名 Runtime:
`0.11.10` 及更早版本仍会按其 manifest 上限夹紧,因此桌面启用这一语义前必须配套更新
到 Agent `0.11.13` 或更高版本。
## 执行清单接入范围
OC `todowrite` / CN `Checklist` 顶部展示属于待实施功能,权威需求及接入设计见
[Runtime 执行清单](../assistant-workbar/runtime-checklist-technical-design.md),
当前证据见[工作栏进度](../assistant-workbar/progress.md#2026-09-15-runtime-执行清单设计未实现)。
目标范围包括远程 GoodBuddy Agent 运行 OC 和 CN;ACP 仅承担传输与远端协议。
当前托管安装与实时 Runtime 路径仍只接受 OC,不能把通用 ACP plan/tool 传递代码视作
远程 CN 已可用。CN 的受管工件、安装/启动、项目选择与校验、模型桥及原生清单传递
需要在该功能实施时补齐,并在共享 Linux 真实 Host 分别确认 OC/CN 的可用程度。
本次只完善文档,未实测任一远程 Runtime 的清单;已有 OC Ask/Execute、问答或重连证据
不作为本功能通过证据。清单恢复复用下节流程,不增加独立持久化或重连系统。
## ACP 与断线
- 管控面只负责有界 JSON-RPC:连接、查询、启动、取消、关闭和重连。数据面只负责
@@ -84,6 +84,14 @@ Subagent 是执行 Job 或 Subjob 的受限执行者,不是对象层级:
- Subagent 不自动拥有独立 Task 或 Conversation。
- Subagent 输出先回到所属 Job,再由 Task 协调器写入关联 Conversation。
### 1.7 Runtime 执行清单
Runtime 执行清单是一次请求中由 OC `todowrite` 或 CN `Checklist` 更新的只读工作项列表,
属于请求及其助手消息,不创建 Task、Job、Run 或 Schedule,也不驱动定时任务状态。
条目全部完成不表示关联 Task 目标达成,请求取消也不自动完成条目。
该功能尚未实现,需求、顶部展示与本地/远程接入由
[助手工作栏文档](../assistant-workbar/README.md)维护。
## 2. 对象关系
```text