goodbuddy/docs/features/direct-model-agent/prd.md

直连模型 Agent 能力 PRD

文档信息

项目	内容
状态	已实施，跨平台 CI 待验证
版本	0.4
日期	2026-09-09
适用产品	GoodBuddy 桌面端
目标平台	Windows、macOS、Linux，x64 与 arm64
关联领域	Task 与 Job 统一领域模型

1. 背景

GoodBuddy 直连模型已经可以读取、列出和写入工作区文本，使用浏览器、联网搜索、知识库及 分配的 MCP，但没有内置命令执行工具。模型可以生成代码，却不能运行构建、测试、格式化、 Git 或项目脚本，因此无法独立验证结果。

本功能设计时，GoodBuddy 已有面向用户专家协作的只读 Subagent，但直连模型尚不能在工具 循环中主动委派编程子任务。当前专家协作已继承父请求 Ask/Execute 模式并使用本机直连模型 工具，与本功能的 subagent_delegate 仍为不同入口。OpenCode、Continue 和 DeepSeek Harness 一般已经提供 Shell、Agent 或 Task 能力，再向它们注入 GoodBuddy 同名工具只会造成重复入口和语义冲突。

本功能补齐直连模型缺少的基础 Agent 能力：

1. 一组工作区搜索、分页读取和补丁编辑接口。
2. 一个按平台适配的进程执行接口。
3. 一个单层、继承父请求范围的编程 Subagent 接口。

2. 产品目标

1. 让直连模型在 Execute 模式完成“读取代码 → 修改 → 运行 → 根据结果修正”的闭环。
2. 在 Windows、macOS 和 Linux 使用同一个模型工具契约，不要求模型调用平台专属工具名。
3. 让直连模型可以把独立工作委派给临时 Subagent，并取得有界、可核验的结果。
4. 保持 Ask 只读、Execute 完整授权、执行空间、取消、有界输出和进程回收语义不变。
5. 不向已有原生执行能力的 Agent Runtime 重复注入 GoodBuddy 进程或 Subagent 工具。
6. 使用安装包内置 ripgrep 提供跨平台一致的快速代码搜索，不依赖用户预装命令。

3. 核心产品决策

3.1 统一工具名，平台适配留在 Main

模型只看到 process_execute。GoodBuddy 根据当前平台选择 PowerShell、Bash 或 Sh，并在 工具描述和结果中明确实际 Shell。模型不需要在 Windows 调用 powershell_execute、在 macOS/Linux 改用 bash_execute。

3.2 它是内置能力，不依赖 MCP

进程生命周期、工作目录、取消和执行空间由 GoodBuddy 管理。用户仍可以配置提供其他命令 能力的 MCP，但直连模型的基本编程能力不依赖第三方 MCP 是否安装或在线。

3.3 Runtime 能力不重复注入

Runtime	GoodBuddy process_execute	GoodBuddy subagent_delegate
直连模型 model	Execute 提供	Ask/Execute 提供
OpenCode	不提供	不提供
Continue	不提供	不提供
DeepSeek Harness	不提供	不提供

“不提供”只表示不注入本功能工具，不限制 Runtime 自己的 Bash、PowerShell、Task、 Agent 或插件能力。

3.4 Subagent 继承，不扩权

Subagent 使用父请求的项目、执行空间、工作模式、直连模型连接和已启用能力快照：

• Ask 父请求只能创建 Ask Subagent。
• Execute 父请求创建 Execute Subagent。
• 子级不能切换父请求绑定的项目、工作区、Runtime、模型连接或工作模式；Execute 命令的 单次工作目录选择遵循 FR-3。
• 子级不再看到 subagent_delegate，首版最大委派深度固定为 1。
• 子任务不是新的顶层 Task 或 Conversation，结果先返回父模型。

3.5 不新增权限档位

Ask 禁止命令和写入。Execute 是用户对当前执行空间账号的完整授权。进程和 Subagent 不增加 “受控执行”“仅测试”“可信命令”或逐命令风险等级，也不重复弹出第二套确认。

3.6 精简工作区工具

直连模型使用 workspace_rg 发现文件和搜索内容，使用 workspace_read_text 按行分页读取， 使用 workspace_apply_patch 新增、修改或删除文本文件。新请求不再注入低效的单层目录列表和 整文件覆盖工具。Ask 提供前两个只读工具；Execute 额外提供补丁工具。

4. 功能范围

4.1 包含

• 本机 Windows、macOS、Linux 的前台 Shell 命令执行。
• 当前工作区默认工作目录，以及当前用户可访问的本机工作目录选择。
• Exit Code、标准输出、标准错误、Shell、目录、耗时和截断状态。
• 命令超时、用户取消、进程树停止和应用退出清理。
• 新进程使用当前本机工具环境提供的 Node、Python 和 PATH。
• 直连模型单层 Subagent 委派、排队、运行、部分结果、失败和取消。
• 父子请求的工具、模型用量、活动和成果归属。
• 桌面聊天和选择直连模型的消息通道项目使用相同 Runtime 能力矩阵。
• 安装包按目标平台和架构携带固定版本 ripgrep，并将其提供给工作区搜索和命令 PATH。

4.2 不包含

• 交互式 PTY、终端复用、持续 stdin、密码提示或 TUI 自动化。
• 后台守护进程、任意 PID 枚举、接管或停止用户已有进程。
• Shell Session 持久化，环境变更不会跨 process_execute 调用保留。
• 首版远程 SSH 直连模型进程执行。
• 向 OpenCode、Continue 或 DeepSeek Harness 注入本功能工具。
• 递归 Subagent、长期运行的自治 Agent、Workflow、Hook 或恢复未完成子任务。
• 新的权限矩阵、逐命令批准、沙箱档位或命令白名单。
• 自动安装项目依赖；模型可以在 Execute 中显式运行项目已有的安装命令。

5. 功能需求

FR-1 直连模型专属可用性

• 进程、编程 Subagent 和输出续读工具只由 Runtime provider model 注册。
• Agent Runtime 切换为 OpenCode、Continue 或 DeepSeek Harness 后不再显示这些工具。
• 图像生成连接不获得文本 Agent 工具。
• 能力不可用时返回准确原因，不以其他 Runtime 或本机 Shell 静默代替。

FR-2 跨平台进程执行

• 使用统一的 process_execute 工具契约。
• Windows 选择 PowerShell；macOS/Linux 选择 Bash，Bash 不可用时可使用 POSIX Sh。
• 每次调用启动一个前台进程树，完成后返回结构化结果。
• 非零退出码是可观察的命令结果，不自动转成模型请求失败。
• Shell 启动失败、非法参数或执行后端不可用才属于工具失败。

FR-3 工作目录和执行位置

• 默认目录是父请求当前工作区。
• 可选工作目录支持绝对路径、相对工作区路径及指向工作区外目录的路径或符号链接， 不额外限制在工作区内；目标必须是实际存在且当前用户可访问的目录。
• 本机执行只能发生在当前桌面执行空间。
• 当前请求绑定 SSH 执行空间且没有远端进程后端时不注册工具，绝不在桌面目录回退执行。

FR-4 Ask/Execute

• Ask 工具清单不包含 process_execute。
• Runtime 边界必须再次拒绝 Ask 发起的伪造命令调用。
• Execute 命令使用 GoodBuddy 客户端当前用户权限，不声称 Runtime OS 沙箱。
• 消息通道的直连模型 Execute 继续服从该通道既有工具策略。

FR-5 Subagent 委派

• subagent_delegate 接受一个清晰的任务说明，不要求用户预先创建专家。
• 子级默认使用父请求选择的直连模型连接。
• 子级继承父请求的工作模式和能力上限，但不获得再次委派能力。
• 子级最终输出、部分输出、错误、用量和状态返回父请求。
• 父模型负责综合结果并向用户作最终回答。

FR-6 Subagent 领域归属

• 子任务使用 Job/Subjob 语义，不创建 Task Center 条目或独立 Conversation。
• UI 对象层级继续止于用户 Task；活动可以显示 Subagent 状态卡，但不显示 Job/Run 树。
• 子任务产生的工具、成果和用量可追溯到父请求及子任务标识。

FR-7 生命周期和资源边界

• 父请求取消必须传播到活动 Subagent 和其当前进程。
• Runtime 替换、会话释放和应用退出必须停止 GoodBuddy 创建的活动子进程。
• 命令、Subagent 提示、单次返回的输出预览、队列和并发有界；完整输出不因超过预览容量而丢弃。
• 预览省略内容时明确标记并提供续读位置。模型可用 output_read 逐页取得完整日志及 Subagent 结果，包括失败或取消前已取得的部分输出。
• Ask 和 Execute 均可续读当前会话的输出。会话或 Runtime 释放后，临时输出删除，旧句柄失效。

FR-8 环境和凭据

• 新进程使用筛选后的当前用户环境和本机工具环境 PATH。
• 模型 Provider 凭据、GoodBuddy 加密设置和无关桌面会话变量不进入命令环境。
• 首版不接受模型提交任意环境变量映射；需要的普通变量由 Shell 命令在单次调用中设置。

FR-9 状态与活动

• 进程活动显示等待、运行、成功、非零退出、超时、取消和失败。
• Subagent 显示排队、运行、完成、失败和取消。
• 命令和子任务失败保留可操作错误及已有部分输出。
• 同一事件不同时显示页内错误和应用通知。

FR-10 兼容

• 现有模型连接、MCP 分配、专家设置和 Runtime 选择无需迁移。
• 不改变现有 Agent Runtime 的工具清单或权限语义。
• 不修改系统 PATH、Shell Profile 或用户终端会话。

FR-11 模型请求重试

• 直连文本模型的普通问答、工具轮次和上下文摘要遇到瞬时网络错误或单次请求超时时， 在尚未显示文本或推理内容的前提下最多自动重试 3 次。
• 重试使用递增等待时间并显示当前次数；用户取消必须立即终止等待和后续请求。
• 一旦本次模型调用已经显示文本或推理内容，不自动重放该调用，避免重复回答。
• 非网络类 Provider 错误、协议错误和用户取消不进入自动重试。

FR-12 高效工作区工具

• workspace_rg 接受原生 rg 参数和可选工作目录，支持内容搜索、上下文、文件列表及 自选输出格式，保留原生输出与退出码。默认遵循项目忽略规则。
• workspace_read_text 接受起始行和行数，大文件通过续读完成，不因超过旧的整文件上限而 完全不可读；超长单行可使用返回的字节位置继续读取。
• workspace_apply_patch 支持一个补丁新增、修改和删除多个 UTF-8 文件；执行前验证全部 路径和 hunk，执行失败时准确报告已完成文件。
• 搜索和读取在 Ask/Execute 均可用；补丁只在 Execute 可用，Main 调用边界再次检查模式。
• workspace_rg 直接调用随包 ripgrep；Ask 限于工作区内只读搜索，Execute 使用当前账号权限。 具体参数与模式边界见工具契约。
• 工作区工具不限制文件总大小、补丁总大小、搜索表达式长度、glob 数量或模型请求的结果 数量。单次返回按上下文容量截断或分页；读取结果提供续读位置，搜索完整输出通过 output_read 续读。

6. 产品验收

• Windows 直连模型 Execute 使用 PowerShell 创建文件、运行测试并读取退出码。
• macOS/Linux 直连模型 Execute 使用 Bash/Sh 完成同一工作流。
• Ask 中模型看不到进程工具，伪造调用也在 Main 边界失败。
• 直连模型可以委派编程子任务，子级运行命令并把结果返回父模型。
• Ask Subagent 保持只读；Execute Subagent 不增加第二套批准。
• Subagent 不能递归委派，不能切换父请求工作区、模式或模型。
• 切换到 OpenCode、Continue 或 DeepSeek Harness 后不出现本功能工具。
• 非零退出、超时、取消和输出截断均准确展示。
• 模型能续读长输出中未出现在预览内的中间与结尾内容，中文和表情不会导致分页停滞。
• 取消父请求和退出应用后没有残留 GoodBuddy 命令进程。
• 本机工具环境选择对新命令生效，Main 持有的模型凭据不进入子进程。
• 子任务不进入 Task Center，不创建独立可导航 Conversation。
• TLS 建连重置和请求超时在未输出内容时最多自动重试 3 次，成功后继续原请求。
• 重试等待可取消，已显示部分内容的失败不自动重放。
• Ask 可使用 ripgrep 搜索和分页读取，但不能应用补丁。
• Execute 可通过一个补丁新增、修改和删除多个工作区文件，并运行测试验证。
• Windows、macOS、Linux 的 x64/arm64 安装包均携带对应 ripgrep，且无需系统预装。
• 全量测试、类型检查、Lint 和生产构建通过。