diff --git a/docs/features/assistant-workbar/README.md b/docs/features/assistant-workbar/README.md index b931ccb6..5ee6d05d 100644 --- a/docs/features/assistant-workbar/README.md +++ b/docs/features/assistant-workbar/README.md @@ -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#执行清单接入范围)拥有远程部署与连接边界。 diff --git a/docs/features/assistant-workbar/prd.md b/docs/features/assistant-workbar/prd.md index 4de97a57..e43bd19b 100644 --- a/docs/features/assistant-workbar/prd.md +++ b/docs/features/assistant-workbar/prd.md @@ -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 中的受管运行。 diff --git a/docs/features/assistant-workbar/progress.md b/docs/features/assistant-workbar/progress.md index 816dc031..15c1aa14 100644 --- a/docs/features/assistant-workbar/progress.md +++ b/docs/features/assistant-workbar/progress.md @@ -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，设计及完整验收清单见 diff --git a/docs/features/assistant-workbar/runtime-checklist-technical-design.md b/docs/features/assistant-workbar/runtime-checklist-technical-design.md new file mode 100644 index 00000000..1473ee8c --- /dev/null +++ b/docs/features/assistant-workbar/runtime-checklist-technical-design.md @@ -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 或本地成功代替远程验收。 diff --git a/docs/features/assistant-workbar/runtime-interactions.md b/docs/features/assistant-workbar/runtime-interactions.md index 6ebadba4..acc37927 100644 --- a/docs/features/assistant-workbar/runtime-interactions.md +++ b/docs/features/assistant-workbar/runtime-interactions.md @@ -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-资源复用)， diff --git a/docs/features/remote-host/technical-design.md b/docs/features/remote-host/technical-design.md index 1770304f..5c831800 100644 --- a/docs/features/remote-host/technical-design.md +++ b/docs/features/remote-host/technical-design.md @@ -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：连接、查询、启动、取消、关闭和重连。数据面只负责 diff --git a/docs/features/task-and-job/task-and-job-model.md b/docs/features/task-and-job/task-and-job-model.md index f934c8d0..92e27a36 100644 --- a/docs/features/task-and-job/task-and-job-model.md +++ b/docs/features/task-and-job/task-and-job-model.md @@ -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