Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 18 additions & 15 deletions docs/architecture/agent-runtime-services-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@ CLI Agent 体验边界见 [`cli-product-line-design.md`](cli-product-line-design
新增公共类型前必须有真实生产调用方、版本边界和验证路径。现有 Agent Runtime SDK 仍是 v1 preview,CLI、ACP、
Desktop 仍保留 `bitfun-core/product-full` 兼容 owner。CLI 与 CLI 托管的 ACP server 已消费各自的产品组装结果;
Desktop 主交互只消费由现有 Core owner 构造的窄口径 SDK 门面,尚未组装完整 Desktop profile。这些接入都不等于
协调器、调度器、持久化或工具执行 owner 已迁移;ACP 的完整持久化历史、模型/模式、MCP、客户端路径与 Desktop
的其余入口仍保留明确的兼容边界。
协调器、调度器、持久化或工具执行 owner 已迁移;ACP 的完整持久化历史、模式、模型目录/提供方配置、MCP、客户端路径与
Desktop 的其余入口仍保留明确的兼容边界,活动会话的模型写入已通过 SDK 回到 Core owner

阅读路径:第 1 节确认 SDK、内核、产品特性、扩展接口和 crate 边界;第 2-3 节说明稳定接口、
运行时服务、内核、工具和工作流;第 4 节说明产品组装与扩展注册;第 5 节作为质量保护和
Expand Down Expand Up @@ -708,19 +708,20 @@ pub struct HarnessExecutionContext {
`DeliveryProfile::Acp` 构造 `ProductRuntimeParts`。Desktop 主交互直接从现有协调器和调度器端口构造窄口径
Agent Runtime SDK 门面,不注册未实现的 `RuntimeServices` 能力,也不宣称完整 Desktop profile 可用。CLI 通过
一个调用级上下文把 Agent Runtime SDK、Harness、能力注册、调用级权限和 Agentic 事件广播交给 TUI、Exec、Session、Usage 与
交互模式下的 Peer Host。SDK 已承接会话创建/列举/删除/恢复、类型化转录读取、轮次提交/取消,以及 CLI/TUI
交互模式下的 Peer Host。SDK 已承接会话创建/列举/删除/恢复、会话模型更新、类型化转录读取、轮次提交/取消,以及 CLI/TUI
的工具确认、拒绝和用户问题回答;固定 ID 创建使用独立的 `create_session_with_id` 方法,普通创建 DTO 保持 v1
字段集合。未实现该能力的提供方返回类型化不支持错误;实现成功时 Runtime 必须校验返回 ID 与请求完全一致,不能
替换为自动生成的 ID。`SessionSelector::Create` 仍保持自动生成。Peer Host 当前只消费同一 SDK 的工具确认与拒绝。
SDK v1 尚未覆盖的模型更新、分支、用量、快照和
持久化维护等操作仍由 `assembly/core` 的单一兼容门面转发。`doctor` 与 `health` 校验真实组装结果及必需注册完整性;
替换为自动生成的 ID。`SessionSelector::Create` 仍保持自动生成。Peer Host 通过同一 SDK 处理对话提交、精确取消、
工具确认、拒绝和会话模型更新。SDK v1 尚未覆盖的分支、用量、快照和持久化维护等操作仍由
`assembly/core` 的单一兼容门面转发。
`doctor` 与 `health` 校验真实组装结果及必需注册完整性;
Core 的 Network、Git 和 MCP Catalog 当前仍含兼容 marker,因此该诊断不等于对这些外部服务做实时探活。

该切换仍是 `product-full` 兼容组装,不是 owner 迁移。协调器、调度器、持久化、工具管线和 Agentic Event Queue
仍由 Core 唯一持有;CLI 与 ACP 不复制这些状态。ACP 服务端通过 SDK 处理会话创建/列举、轮次、取消、交互响应和事件订阅,
但完整持久化历史回放、模型/模式、模型目录/配置和 MCP 仍走单一 Core 兼容门面;ACP stdio、连接和协议投影仍在
但完整持久化历史回放、模式、模型目录/配置和 MCP 仍走单一 Core 兼容门面;会话模型写入通过 SDK 回到同一 Core owner。ACP stdio、连接和协议投影仍在
`interfaces/acp`。Desktop 复用同一 Core owner 构造一个窄口径 SDK 门面,主界面的轮次提交/取消、工具确认/拒绝和
用户问题回答已通过该门面;会话 CRUD/恢复视图、模型、MCP、MiniApp、Cron、远程连接、Tauri 窗口与平台资源
用户问题回答与会话模型更新已通过该门面;会话 CRUD/恢复视图、MCP、MiniApp、Cron、远程连接、Tauri 窗口与平台资源
仍保留在 Desktop/Core 兼容入口。Server 仅提供健康检查、信息与 ping 路由。未接入入口的 profile、枚举分支和
单元测试仍不能证明对应产品形态可用。

Expand Down Expand Up @@ -794,14 +795,15 @@ Core 的 Network、Git 和 MCP Catalog 当前仍含兼容 marker,因此该诊
| ACP | ACP 协议、客户端生命周期、远端探测 | 外部智能体/工具能力、环境事实、权限桥接 |
| Web UI / mobile web | UI 状态、hydration、配对、会话展示、插件状态视图 | 接口/传输 DTO、运行时事件事实、能力服务读模型 |

当前 Runtime SDK 已提供会话创建、列出、删除、恢复和类型化转录读取。`AgentSessionRestoreRequest/Result` 与
当前 Runtime SDK 已提供会话创建、列出、删除、恢复、模型更新和类型化转录读取。模型更新只接受会话 ID 与模型 ID,
不承载模型目录、模式、提供方配置或宿主 UI 选择语义。`AgentSessionRestoreRequest/Result` 与
`AgentSessionRestorePort` 归 Agent Runtime SDK,以继续复用 Runtime owner 的完整 `SessionState`;类型化
`SessionTranscript` 归 `runtime-ports`。两者都由 `assembly/core` 注入真实持久化 owner,当前由 CLI/TUI
消费;ACP 为保证模型配置与完整历史来自同一次恢复,继续通过 Core 兼容门面读取协议回放所需的完整轮次,避免为单一协议
扩张通用 transcript。CLI/TUI 的工具确认、拒绝和用户问题回答,以及 ACP 服务端 / Peer Host 的工具确认与拒绝,通过类型化
`AgentInteractionResponsePort` 回到 Core 的工具管线或用户输入 owner,不改变审批策略或交互所有权。
`CoreAgentRuntimeCompatibility` 仍承载未迁移的
模型更新、持久化、分支、用量和快照等操作;不能据此把整个兼容门面一次性删除,也不能把这些
持久化、分支、用量和快照等操作;不能据此把整个兼容门面一次性删除,也不能把这些
操作提前声明为跨宿主稳定接口。旧固定 ID 创建方法仅作为标记废弃的源码迁移转发保留一个兼容周期,生产 CLI
调用已经迁移到 Runtime SDK;该转发不得重新成为新调用入口。

Expand Down Expand Up @@ -866,7 +868,8 @@ Provider 装配同样按需增加,不提前为 Memory、Context、Workflow、S

CLI 托管的 ACP 服务端使用 `DeliveryProfile::Acp` 组装一个 Agent Runtime,通过 SDK 处理会话创建/列举、轮次提交/取消、
交互响应和只读 Agent 事件订阅。ACP 只把共享运行时事实映射成协议更新;标准输入输出、连接、权限 RPC 与通知生命周期
不进入 SDK。完整持久化历史恢复、模型/模式、模型目录/配置、MCP 和 ACP 客户端路径仍是明确的 Core 兼容范围,
不进入 SDK。完整持久化历史恢复、模式、模型目录/提供方配置、MCP 和 ACP 客户端路径仍是明确的 Core 兼容范围;
活动会话的模型写入已经通过 SDK 回到 Core owner,
不据此扩张通用 runtime DTO。

继续拥有:
Expand Down Expand Up @@ -1060,12 +1063,12 @@ Product 测试:
- `bitfun-harness` 已提供类型化工作流描述与注册能力。
- `bitfun-core` 可继续作为 `product-full` 兼容门面,避免迁移期间一次性重写入口。
- CLI 已以 `DeliveryProfile::Cli` 构造真实 Runtime Parts 和 SDK runtime;本地 Agent 入口、会话、用量和
Peer Host 共用一个调用级上下文与广播事件源,审批策略不再写回全局配置。Peer Host 通过 SDK 提交/取消
turn,通过单一 Core 兼容门面处理会话与快照缺口,不再构造独立调度器、持久化 manager 或事件队列;
Peer Host 共用一个调用级上下文与广播事件源,审批策略不再写回全局配置。Peer Host 通过 SDK 提交/精确取消
turn、更新会话模型并处理工具确认/拒绝,通过单一 Core 兼容门面处理会话与快照缺口,不再构造独立调度器、持久化 manager 或事件队列;
wire schema、Relay ACK/重放和重连协议未在该切换中扩张。
- CLI 通过 SDK 处理已覆盖的 session/turn/cancel 操作,并通过一个 Core 兼容门面处理 SDK v1 缺口;
该门面复用现有 owner,不建立第二套状态或事件 schema。
- CLI 托管的 ACP 服务端已以 `DeliveryProfile::Acp` 构造真实 Runtime Parts;会话创建/列举、轮次、取消、工具确认/拒绝和
- CLI 托管的 ACP 服务端已以 `DeliveryProfile::Acp` 构造真实 Runtime Parts;会话创建/列举、轮次、取消、会话模型更新、工具确认/拒绝和
Agent 事件订阅复用同一 SDK 语义,ACP stdio、连接与协议投影保持不变。Agentic Event Queue 仍是唯一事件 owner;
全局有界 broadcast 继续服务 CLI/TUI,活动 ACP prompt 使用固定容量、仅接收本会话事件的临时通道,并在最后一个订阅者
释放时立即回收。CLI 宿主进程只保留一个旧消费队列排空任务,不增加每会话转发任务或第二套事件 schema。ACP 组装入口使用独立的
Expand All @@ -1080,7 +1083,7 @@ Product 测试:
- 把 embedded relay 的 TCP bind、静态 fallback 和任务生命周期移出 assembly;room/device 状态、account/sync
存储、asset store 与 HTTP/WebSocket router 已归属 `services/relay-service`,Cargo 反向边已删除并由通用边界检查保护。
- 继续缩小 CLI 的 Core 兼容门面;只有稳定端口、真实生产调用方和行为等价测试齐备时才迁移 owner。
- 继续按真实复用需求缩小 ACP 的完整持久化历史、模型/模式、MCP 与客户端兼容路径;Desktop 仅继续迁移存在稳定端口和
- 继续按真实复用需求缩小 ACP 的完整持久化历史、模式、模型目录/提供方配置、MCP 与客户端兼容路径;Desktop 仅继续迁移存在稳定端口和
行为等价测试的入口。完整 Desktop 产品组装需先补齐真实必需服务与事件消费路径,不以桩实现提前声明能力;ACP 生命周期
和 Desktop 平台资源仍留在各自入口。
- 为 Agent Runtime SDK 增加至少一个非 `bitfun-core` 的真实嵌入方;预览 facade 和单元测试不等于外部可用 SDK。
Expand Down
28 changes: 16 additions & 12 deletions docs/architecture/cli-product-line-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,9 @@ BitFun CLI 应成为可独立安装和发布的 Agent 产品,而不是 Desktop
并把 `ProductRuntimeParts`、Agent Runtime SDK、事件源和调用级审批策略保存在一个 `CliRuntimeContext` 中。
- TUI、`exec`、会话、用量和交互模式下的 Peer Host 复用同一上下文。SDK 已承接会话创建(包括
`exec --session-id` 和缺失后端会话通过独立固定 ID 方法按原 ID 重建)/列举/删除、轮次提交和取消;普通创建
DTO 保持 v1 字段集合,固定 ID 冲突返回 `InvalidRequest`。SDK v1 尚未覆盖的恢复视图、
消息、分支、用量、快照和工具确认由一个 Core
DTO 保持 v1 字段集合,固定 ID 冲突返回 `InvalidRequest`。会话模型更新、工具确认/拒绝和用户问题回答也通过
SDK 的窄端口回到 Core owner;模型目录、模式和提供方配置仍由产品入口解释。SDK v1 尚未覆盖的恢复视图、
消息、分支、用量和快照由一个 Core
兼容门面转发给原 owner。
- Agentic Event Queue 仍是唯一事件 owner;TUI、`exec` 与 Peer Host 使用独立广播订阅,不互相消费事件。
- 有界旧队列只承担兼容存储;达到容量时不得抑制广播。CLI 保持一个后台 drain,订阅方一旦报告 lag/closed,
Expand All @@ -107,8 +108,8 @@ BitFun CLI 应成为可独立安装和发布的 Agent 产品,而不是 Desktop
相对路径、绝对路径或分隔符越出 sessions 根目录。
- TUI 终端句柄由恢复守卫持有;初始化中途失败、正常返回、错误返回或 panic 展开都会尽力退出 alternate screen、
关闭输入捕获、关闭 raw mode 并显示光标。真实 PTY/ConPTY 启动页进程冒烟测试已验证 resize 后仍可交互、
多行输入、空闲 Ctrl+C 和可观察的终端清理序列;resize 渲染正确性、Chat 活动 turn、初始化失败与异常退出等
仍需独立验收
多行输入、空闲 Ctrl+C 和可观察的终端清理序列;Chat 活动 turn 的 resize 静默期已有状态单测,窄屏流式
reflow 已有 TestBackend 回归,真实 PTY 活动 turn、初始化失败与异常退出等仍需独立验收
- Startup 与 Chat 共用 CLI 私有输入读取器;一次读取同时受 256 个事件和 50ms 限制,跨批次仅延续快速文本尾部,
短批次普通按键保持原有路由。被识别为粘贴的文本按批次写入输入缓冲,每批只刷新一次命令菜单;粘贴内容中的
Tab 明确转换为四个空格。
Expand Down Expand Up @@ -146,7 +147,7 @@ BitFun CLI 应成为可独立安装和发布的 Agent 产品,而不是 Desktop
| OpenCode 来源发现与真实执行尚未形成完整闭环 | “来源可识别”容易被误解为“插件可执行” | 第一条闭环只完成一个无外部依赖的契约样例;取得真实 `execute` 并注册到 Tool Runtime 后才显示可用。 |
| 当前 CLI 使用 `product-full`,OHOS target 图包含多组未验证的平台依赖 | 不能据依赖可解析、`hdc shell` 或移动 Remote App 推导 PC 本地 CLI/TUI 可用 | 问题与风险统一记录在平台规约;具体工作另立专题,HAP 不作为替代。 |
| Product Capability 已有,但品牌、资源、默认策略和发行配置没有统一产品定义 | 白标需要修改多处常量和工作流,能力隐藏不等于后端禁用 | 产品定义只在组装/构建边界选择身份、资源、能力包、默认策略和发行事实。 |
| CLI 已有独立 Linux 测试,参数互斥、结果/envelope 序列化、前置失败和组装有 focused contract;Linux 与 Windows 分别运行启动页 PTY/ConPTY 生命周期冒烟,发布归档上传前完成 SHA-256 与解压执行验证 | 真实模型审批/取消、Chat 活动 turn、resize 渲染、Patch I/O 失败和终端故障注入仍可能晚于 PR 发现 | 继续补剩余进程级故障契约;避免为同一依赖图重复建立三平台编译矩阵。 |
| CLI 已有独立 Linux 测试,参数互斥、结果/envelope 序列化、前置失败和组装有 focused contract;Linux 与 Windows 分别运行启动页 PTY/ConPTY 生命周期冒烟,发布归档上传前完成 SHA-256 与解压执行验证 | 真实模型审批/取消、真实 PTY 活动 turn 的 resize、Patch I/O 失败和终端故障注入仍可能晚于 PR 发现 | 继续补剩余进程级故障契约;避免为同一依赖图重复建立三平台编译矩阵。 |

## 3. 分阶段产品需求

Expand All @@ -157,8 +158,8 @@ CLI-P0 的目标是建立后续功能补齐所需的稳定边界,不改变现
CLI-P0 不是一个统一重构 PR。静态 profile、真实 Runtime Services、Runtime Parts、调用级审批、共享事件源和
本地 Agent 纵向入口已接入;旧门面仅在后续 owner 迁移的行为等价成立后退出。配置解释、产品定制消费和 TUI
进一步拆分仍需独立交付。CLI 托管的 ACP 服务端已独立切换到 ACP profile 与组装后的 SDK runtime;启动页
PTY/ConPTY 生命周期冒烟测试与发布归档冒烟测试已存在,真实模型、Chat 活动 turnresize 渲染、终端故障注入与
权限失败等完整进程级验收仍需另行完成
PTY/ConPTY 生命周期冒烟测试与发布归档冒烟测试已存在Chat 活动 turnresize 静默期已有确定性状态单测,
窄屏流式 reflow 已有 TestBackend 回归,真实模型、真实 PTY 活动 turn、终端故障注入与权限失败等完整进程级验收仍需另行完成

其余工作独立立项,不能与 profile 迁移互相充当完成条件:

Expand Down Expand Up @@ -267,8 +268,9 @@ TUI renderer、实验性接口和完整外部 Server 协议按总矩阵明确降
| 生态配置适配器 | 解析受支持外部格式并生成导入候选/诊断 | 直接写运行时配置、读取密钥、决定最终权限 |

CLI/TUI 的会话创建、列出、删除、恢复和历史转录读取通过 Runtime SDK 的类型化端口完成;TUI 只把
`SessionTranscript` 投影为本地渲染状态,不再消费 Core `Message`。Peer Host、账户同步、会话分支、用量、快照和
工具交互仍使用经过审查的 Core compatibility 方法,直到各自具备明确 owner、稳定 DTO、远程语义和行为等价测试。
`SessionTranscript` 投影为本地渲染状态,不再消费 Core `Message`。Peer Host 的对话提交、精确取消、会话模型更新和
工具确认/拒绝通过 SDK 回到 Core owner;账户同步、会话分支、用量、快照及其他未覆盖操作仍使用经过审查的 Core
compatibility 方法,直到各自具备明确 owner、稳定 DTO、远程语义和行为等价测试。
这是一条垂直链路迁移,不是删除整个兼容门面或新建 CLI 专用服务层。

Runtime Configuration Service 当前由 `bitfun-core/service/config` 负责。在经评审的 port/provider
Expand Down Expand Up @@ -339,8 +341,10 @@ flowchart LR
| Action Registry | 统一 action id、slash/palette/help、上下文、可用性、处理器和默认键位;不持有业务状态 |
| Keymap Resolver | 根据当前模式和焦点把用户显式配置或默认键位解析为 action id;不直接执行业务副作用 |

`modes/chat.rs` 最终只保留生命周期编排;现有 `ui/chat/state.rs`、`input.rs`、`render.rs` 等模块继续作为
收敛基础。拆分以可测试边界为目的,不以文件数量为目标。
`modes/chat.rs` 当前主要保留 `ChatMode` 外壳、共享上下文和私有子文件组织;生命周期、输入/命令、选择器、MCP、
会话与能力副作用按职责保留在同一 Rust 模块的 `modes/chat/` 子文件中。现有 `ui/chat/state.rs`、`input.rs`、
`render.rs` 等模块继续作为收敛基础。该拆分不形成公共 TUI 框架,也不改变交互规格;后续仍以可测试边界为目的,
不以文件数量为目标。

### 4.5 Action 与快捷键

Expand Down Expand Up @@ -598,7 +602,7 @@ CLI Agent 能力加强必须落在共享 Agent Runtime、Tool Runtime 或 Harnes
通用 `cargo check --workspace` 负责三平台 CLI 编译保护;独立 CLI CI 运行
`cargo test --locked -p bitfun-cli -p bitfun-acp -p bitfun-agent-runtime`。Linux 启动页 PTY 生命周期冒烟随独立 CLI
测试运行,Windows 启动页 ConPTY 生命周期冒烟复用通用 Windows job;发布归档在上传前完成 SHA-256 与解压执行
验证。完整模型、Chat 活动 turnresize 渲染与故障进程矩阵仍按对应切片补入门禁,不能由序列化单测或基础冒烟
验证。真实模型进程级交互、真实 PTY 中的 Chat 活动 turn resize 与故障进程矩阵仍按对应切片补入门禁,不能由序列化单测或基础冒烟
测试代替。

### 10.2 阶段退出条件
Expand Down
Loading
Loading