@@ -13,7 +13,7 @@
| GoodBuddy 目标平台 | Windows、macOS、Linux，
| 本文性质 | 设计与发布验收约定 |
本文定义 DeepSeek Harness 在 GoodBuddy 中的架构边界、协议、安全 策略、界面、打包和验收要求。实现必须继续遵守 GoodBuddy 已有的 Main 进程安全边界、Ask/Execute 语义、授权、取消、超时、有界输出和资源回收约定。
本文定义 DeepSeek Harness 在 GoodBuddy 中的架构边界、协议、执行 策略、界面、打包和验收要求。实现必须继续遵守 GoodBuddy 已有的 Main 进程安全边界、Ask/Execute 语义、授权、取消、超时、有界输出和资源回收约定。
## 2. 摘要
@@ -25,7 +25,7 @@ GoodBuddy 并不迫切于把该能力做成 DSH 插件或进入插件市场。
1. **GoodBuddy Main Control Plane **
- 运行在 Electron Main 进程。
- 持有加密设置、模型连接选择、Ask 拒绝与 Execute 自动授权 策略、Runtime 生命周期和审计归属。
- 持有加密设置、模型连接选择、Ask 只读 策略、Runtime 生命周期和审计归属。
- 通过 Electron `utilityProcess` 启动受控 Harness 子进程。
- 对环境、输入、输出、超时、取消和进程树执行强制限制。
@@ -56,6 +56,9 @@ DeepSeek Harness 不替换 OpenCode、Continue 或直连模型 Runtime。用户
- macOS：
- Windows：ACL 受限令牌，官方明确标记为部分强制执行。
GoodBuddy 不组合上述 Runtime OS 沙箱。当前产品选择 DSH 本地 Shell 与
Filesystem Provider，以 GoodBuddy 客户端进程的当前用户权限运行工具。
### 3.2 官方通道的缺口
官方 ACP 插件有意只输出已提交文本，不输出推理、工具进度、计划、标题和用量。它也没有标准的会话关闭方法。SDK JSON-RPC 的展示事件更完整，但缺少 GoodBuddy 需要的单轮取消和权限回传。
@@ -72,8 +75,8 @@ GoodBuddy 不急于把该 Runtime 包装成标准 DSH 插件，也不以进入
- 增加 `deepseek-harness` Runtime，并在设置、聊天和消息通道中可选择。
- 使用 GoodBuddy 管理的模型连接，不在 Renderer 或持久化 Harness 配置中写入 API Key。
- Ask 模式在 Runtime 边界强制只读，并禁止任何权限升级 。
- Execute 模式下的工具权限请求由 Main 自动给予单次授权，不弹出交互审批；默认文件模式仍为 `workspace-write` ，越界仅允许在真实沙箱拒绝后对完全相同操作单次重试 。
- Ask 模式在 Runtime 工具分发 边界强制只读，阻止 Shell、写入和编辑工具 。
- Execute 模式使用 DSH 本地 Provider，以当前用户权限执行文件与命令工具；工作区是默认工作目录，不是 OS 权限边界 。
- 支持多会话、同会话串行、跨会话并行。
- 支持按请求取消、超时、会话释放和应用退出时完整回收。
- 输出文本、推理、工具参数、工具结果、stderr 和协议队列全部有界。
@@ -86,7 +89,7 @@ GoodBuddy 不急于把该 Runtime 包装成标准 DSH 插件，也不以进入
- 不开放用户 Cordis profile、cordis.patch.yml 或 $DSH_HOME 全局补丁覆盖。
- 不提供外部 Host、自定义 Harness Control Plane、DSH 插件安装或市场入口。
- 不加载 Harness Web UI、HMR、遥测、自动更新或目录选择器。
- 不支持 `danger-full-access` 作为会话默认值或 持久设置。
- 不提供 Runtime OS 沙箱模式或相关 持久设置。
- 不向 Utility 暴露 MCP 凭据或建立直连 MCP Client。只有用户明确分配给 Harness 的 MCP 工具可以通过 Main 代理调用。
- 不在首版向 Harness 暴露 GoodBuddy 浏览器控制、知识库或 Magic Notes。
- 不在首版支持图像输入、会话恢复、Harness Subagent、后台 Job、Hook、Web Search 或 Workflow。
@@ -115,7 +118,7 @@ GoodBuddy 使用自己固定的 Harness Host 入口和只读组合模板，不
Harness 子进程内控制面不能取代 Main 控制面，Main 控制面也不能代替进程内的 Session/Tool 适配层：
- Harness Control Plane 最接近 Session、Agent、Tool、 Usage 和权限 seam，适合做内部协议转换。
- Harness Control Plane 最接近 Session、Agent、Tool 和 Usage seam，适合做内部协议转换与 Ask 工具拦截 。
- Main 控制面是可信安全边界，适合持有模式授权策略、加密设置、进程控制和 IPC。
任何一侧缺失能力握手时，Runtime 必须报告不可用，不能降级为不受控执行。
@@ -139,7 +142,7 @@ Renderer
Electron Main
├─ RuntimeSettingsStore
├─ AgentRuntimeController
├─ RuntimeAuthorizer（ Execute 自动单次 授权）
├─ RuntimeAuthorizer（ Main 代理工具 授权）
└─ DeepSeekHarnessRuntime / Main Control Plane
│ ACP + goodbuddy/* 扩展，stdin/stdout
▼
@@ -148,8 +151,7 @@ Electron utilityProcess
├─ 固定 Cordis 组合
├─ GoodBuddy Harness Control Plane（内部组件）
├─ DSH Agent 与 LLM seam
├─ DSH Sandbox Policy
├─ 沙箱 Shell / Filesystem
├─ 本地 Shell / Filesystem Provider
└─ 最小工具集
│ HTTPS
▼
@@ -163,10 +165,10 @@ Electron utilityProcess
| Renderer | 不可信展示层 | 脱敏设置、状态、用户可见事件 |
| Preload | 窄桥 | 明确方法和共享 schema |
| Electron Main | 可信控制面 | 加密设置、模式授权策略、Runtime 生命周期 |
| Harness utilityProcess | 不可信执行面 | 当前请求、临时凭据、受控工具和工作区 权限 |
| Harness 工具子进程 | 最低信任 | 单次命令所需的最小环境和沙箱能力 |
| Harness utilityProcess | 不可信执行面 | 当前请求、临时凭据、受控工具和当前用户 权限 |
| Harness 工具子进程 | 最低信任 | 单次命令所需的最小环境和当前用户权限 |
Harness 子进程崩溃、输出异常、拒绝协议、 加载错误或沙箱不可用 时，Main 必须失败关闭。
Harness 子进程崩溃、输出异常、拒绝协议或 加载错误时，Main 必须失败关闭。
## 7. GoodBuddy Harness Control Plane
@@ -178,7 +180,6 @@ Harness 子进程崩溃、输出异常、拒绝协议、加载错误或沙箱不
- 创建、查找和释放 Harness Agent。
- 在 Prompt 前应用 GoodBuddy 指定的 Ask/Execute 权限。
- 将 DSH Session 事件转换为有界的 GoodBuddy 事件。
- 将权限请求转发到 Main，并只接受一次性结果。
- 将 LLM 用量转换为稳定的模型用量事件。
- 在 dispose 时先取消 Agent，再等待子 Agent 和工具清理。
- 保证 stdout 只包含协议帧，诊断只写 stderr。
@@ -223,7 +224,7 @@ Harness 子进程崩溃、输出异常、拒绝协议、加载错误或沙箱不
| `goodbuddy/session/event` | Control Plane → Main | 文本、推理、工具、状态和用量事件 |
| `goodbuddy/credential/resolve` | Control Plane → Main | 按已登记引用请求当前 Runtime 的临时凭据 |
| `goodbuddy/tools/list` | Control Plane → Main | 取得用户分配给 Harness 的有界 MCP 工具 schema |
| `goodbuddy/tools/call` | Control Plane → Main | 通过当前 Execute 请求、schema 校验和自动单次授权 调用 MCP |
| `goodbuddy/tools/call` | Control Plane → Main | 通过当前 Execute 请求、schema 校验和既有 RuntimeAuthorizer 调用 MCP |
| `goodbuddy/shutdown` | Main → Control Plane | 停止接收新请求并有序清理 |
扩展版本独立于 ACP 版本。握手响应至少包含：
@@ -236,29 +237,28 @@ type GoodBuddyHarnessCapabilities = {
supports : {
cancellation : true
sessionRelease : true
oneShotApproval : true
reasoningEvents : boolean
toolEvents : boolean
usageEvents : boolean
credentialResolution : true
}
sandbox : {
provider : string
enforcement : 'full' | 'partial'
execution : {
mode : 'host'
}
}
```
版本不兼容、必需能力缺失或 `sandbox.enforcement` 不满足设置要求 时，Main 不得开始模型请求。
版本不兼容、必需能力缺失或 `execution.mode` 不是 `host` 时，Main 不得开始模型请求。
### 8.4 每轮权限准备
GoodBuddy 的工作模式属于每个请求，不属于 Runtime 进程全局状态。同一对话可以在 Ask 和 Execute 之间切换。因此：
1. `session/new` 后默认是 `read-only + never`
1. `session/new` 后默认是 Ask 。
2. 每个 Prompt 前，Main 发送一次 `goodbuddy/session/prepare` 。
3. Harness Control Plane 将准备状态绑定到 `sessionId + requestId` 。
4. `session/prompt` 只能消费匹配且尚未使用的准备状态。
5. 缺少准备状态、重复使用、请求标识不匹配时，Control Plane 使用只读且禁止授权的安全默认值，或 直接拒绝请求。
5. 缺少准备状态、重复使用、请求标识不匹配时，Control Plane 直接拒绝请求。
6. 同一 Session 只允许一个 Prompt 在途。
### 8.5 事件模型
@@ -315,42 +315,37 @@ GoodBuddy conversationId -> Harness sessionId + process generation
- 超时后终止 utilityProcess，并在平台允许时清理完整进程树。
- 应用退出不得因 Harness 清理无限阻塞。
## 10. 权限与沙箱
## 10. 权限与主机执行
### 10.1 模式映射
| GoodBuddy 模式 | DSH 文件模式 | DSH 权限策略 | 行为 |
| GoodBuddy 模式 | 本地工具 | GoodBuddy MCP 工具 | 行为 |
| --- | --- | --- | --- |
| Ask | `read-only `| `never` | 允许受控读取，不允许写入，不允许升级 |
| Execute | `workspace-write` | `ask` | 允许工作区与受控临时目录写入；权限请求由 Main 自动单次授权，不弹出交互审批 |
`danger-full-access` 只能作为某个已被沙箱拒绝的完全相同操作的一次性、更宽重试。Main 仅对该次重试自动返回 `allow-once` ；它不能保存为默认值、复用于后续操作，或通过“始终允许”返回。
| Ask | 只开放读取；分发边界阻止 `write` 、 `edit` 、 `bash `和 `pwsh` | 不注册 | 保持只读 |
| Execute | 全部固定工具可用 | 按分配注册并经过既有 RuntimeAuthorizer | 以当前用户权限运行 |
### 10.2 Ask 模式
- Main 即使收到权限请求也固定拒绝 。
- Harness Control Plane 禁止 `sandbox_permissions` 升级 。
- 文件写入和 Shell 写入都由 DSH 共享 Sandbox Policy 强制拒绝 。
- 只读不等于无限输出，读取仍受路径、 字节和工具结果上限控制。
- Harness Control Plane 在 `tools/execute` 分发边界识别当前 Session 和在途请求 。
- `write` 、 `edit` 、 `bash` 与 `pwsh` 固定拒绝，不能仅靠系统提示词保持只读 。
- Ask 不注册 Main 代理的 MCP 工具 。
- 只读不等于无限输出，读取仍受字节和工具结果上限控制。
- 首版不向 Ask 暴露 GoodBuddy 的可变数据工具。
### 10.3 Execute 模式
- 工作区根 来自 Session 创建时的规范化绝对路径。
- 工具不能自行更换工作区根 。
- 工作区内操作按 DSH `workspace-write` 执行 。
- 只有真实沙箱拒绝后的同一操作，才可请求一次升级 。
- Main 不调用 `ToolApprovalBroker` ，而是对当前 Execute 请求自动返回 `allow-once` ；界面不进入等待审批状态，也不弹出审批对话框。
- 工作区来自 Session 创建时的规范化绝对路径，并作为文件与命令工具的默认工作目录 。
- DSH 本地 Filesystem、Bash 或 PowerShell Provider 直接使用 GoodBuddy 客户端当前用户的 OS 权限 。
- 工作区不是 containment 边界；绝对路径和命令可访问当前用户本来有权访问的主机资源 。
- Main 代理的 MCP 工具继续执行分配、schema、活动请求、模式和 RuntimeAuthorizer 校验 。
- 所有工具调用仍作为活动事件记录；Ask 和 delegation 路径继续固定拒绝。
- Harness Control Plane 不接受 `allow_always` ，也不把未知结果解释为允许。
### 10.4 沙箱可用性
### 10.4 Runtime OS 沙箱
- `strict` ：要求完整强制执行。仅有 `partial` 或无 Runner 时 Runtime 不可用 。
- `auto` ：允许官方报告的 `full` 或 `partial` ，但必须在状态卡显示实际强制程度 。
- `off` ：不允许 Harness 退化到无限制工具执行。首版将 Execute 标记为不可用，Ask 仍只能在可强制只读时运行 。
Windows ACL 和旧 Linux Landlock 可能只报告 `partial` 。界面和诊断必须如实显示，不能写成“完全隔离”。
- GoodBuddy 不加载 DSH 平台 Sandbox Provider，也不执行启动沙箱探测 。
- “安全与数据”不提供 Runtime OS 沙箱开关 。
- 握手明确报告 `execution.mode = 'host'` ，状态文案明确说明工具使用当前用户权限 。
- Electron Renderer、Preload、Browser Session 等应用安全沙箱不在本设计变更范围内。
### 10.5 环境与凭据
@@ -370,10 +365,7 @@ Windows ACL 和旧 Linux Landlock 可能只报告 `partial`。界面和诊断必
- Agent、Session、LLM 和 Tool Registry 基础服务。
- GoodBuddy Harness Control Plane。
- OpenAI 兼容 Chat Completions LLM 适配器。
- Sandbox Policy 与平台 Sandbox Provider。
- 平台对应的受沙箱 Shell。
- 受沙箱 Filesystem。
- 一次性权限请求服务。
- DSH 本地 Subprocess、Filesystem 和平台 Shell Provider。
- Token Meter 和必要的上下文压缩。
- 有界的读取、写入、编辑和 Shell 工具。
- Agent scope 的 Skill Registry 与 `skill` 工具。Skill 目录由 Main 选择并在 Launcher 和 Host 两次规范化、校验。
@@ -411,7 +403,7 @@ DeepSeek Harness 首版只使用符合下列边界的 GoodBuddy 模型连接：
### 12.2 设置变化
模型、凭据、沙箱、 Skill 或 MCP 分配变化时，GoodBuddy 创建新 Runtime 实例。Harness Host 路径始终由当前 GoodBuddy 构建提供，不能由设置或环境变量替换。旧实例按现有 Runtime Controller 语义退役，不在一个活动进程内热替换安全配置。
模型、凭据、Skill 或 MCP 分配变化时，GoodBuddy 创建新 Runtime 实例。Harness Host 路径始终由当前 GoodBuddy 构建提供，不能由设置或环境变量替换。旧实例按现有 Runtime Controller 语义退役，不在一个活动进程内热替换安全配置。
### 12.3 输入限制
@@ -448,7 +440,6 @@ DeepSeek Harness 首版只使用符合下列边界的 GoodBuddy 模型连接：
- 内置 Host 路径是规范化文件。
- 版本可读取且在支持范围内。
- 内部控制面能力握手成功。
- 必需 Sandbox Provider 可用并报告强制程度。
检测不得调用付费模型，也不得读取或输出 API Key。真实模型测试是单独的显式操作。
@@ -464,7 +455,7 @@ Runtime：
状态： 已就绪
路径： <受控 Host 路径>
版本： 0.1.0-rc.6
安全强制 ： 完整 / 部分
执行权限 ： 当前用户权限
Host 始终由当前 GoodBuddy 版本提供，不存在自定义 Host 入口。
```
@@ -474,7 +465,7 @@ Host 始终由当前 GoodBuddy 版本提供，不存在自定义 Host 入口。
- 不再在卡片外重复一行检测结果。
- 使用语义化键值结构，路径允许换行，不截断关键信息。
- 状态不能只依靠绿色表达，必须同时有文字。
- 检测中、 不可用和部分强制 分别显示明确文案。
- 检测中和 不可用分别显示明确文案。
- 高级设置默认收起。
聊天顶栏只显示简短 Runtime 状态，不显示文件路径和版本。完整诊断只在设置页展示。
@@ -485,7 +476,7 @@ Host 始终由当前 GoodBuddy 版本提供，不存在自定义 Host 入口。
- `deepseek-harness` provider 和 Runtime ID。
- Runtime 选择中的 `deepseekHarness` 分支。
- 检测结果中的路径、版本、详情和沙箱强制程度 。
- 检测结果中的路径、版本、详情和主机执行模式 。
- GoodBuddy 模型连接选择。
- DeepSeek Harness 模型用量归属。
- Skill 与 MCP 对 `deepseek-harness` 的显式分配。
@@ -505,7 +496,7 @@ Renderer 只接收脱敏状态。任何凭据、完整环境、启动参数或
- 官方 RC 包全部精确锁定，不使用 `^` 或 `~` 。
- 同一 Harness 核心包族必须保持同一 RC 版本。
- 升级前检查 release diff、协议 diff、沙箱 diff 和依赖闭包。
- 升级前检查 release diff、协议 diff、工具执行语义 和依赖闭包。
- 内部握手同时检查锁定的 Harness 基线和 GoodBuddy 控制协议版本。
### 16.2 原生依赖
@@ -513,14 +504,13 @@ Renderer 只接收脱敏状态。任何凭据、完整环境、启动参数或
受控组合可能需要：
- `node-pty` ，用于受管理的工具子进程。
- `koffi` ，用于 Windows ACL 或相关本地能力 。
- `@deepseek-ai/node-addon-landlock-run` 的平台包。
- `koffi` ，用于本地 Filesystem 在 Windows 上保持文件 ACL 和原子替换 。
不得广泛批准所有安装脚本。只允许生产组合实际需要、来源已审查、版本已锁定的脚本。六个平台的构建必须验证：
- 对应架构的原生文件存在。
- Electron Utility Process 可加载原生模块。
- Runner 或 spawn helper 的权限正确。
- spawn helper 的权限正确。
- 包中没有混入其他平台不需要的可执行内容，除非上游包无法拆分且已记录。
### 16.3 生产闭包
@@ -549,7 +539,7 @@ Renderer 只接收脱敏状态。任何凭据、完整环境、启动参数或
- Harness Host 和受控配置存在。
- GoodBuddy Host、内部控制协议与 Harness 依赖版本清单存在。
- 平台原生 Sandbox/PTY 依赖架构正确。
- 平台原生 PTY/Koffi 依赖架构正确。
- Harness、ACP SDK 和其他新增第三方许可证已打包。
- `app.asar` 外需要执行或动态加载的资源位于预期目录。
- Web3D Skill/MCP 等测试 fixture 不在 `app.asar` 或 `extraResources` 中。
@@ -562,16 +552,16 @@ Renderer 只接收脱敏状态。任何凭据、完整环境、启动参数或
- 二进制检测、版本解析和路径规范化。
- ACP 握手、事件转换和请求关联。
- 每个会话单请求、跨会话并行。
- Ask 固定拒绝升级 。
- Execute 权限请求由 Main 自动返回单次授权，Ask 与 delegation 固定拒绝 。
- Ask 在工具分发边界固定拒绝 Shell、写入和编辑 。
- 握手只接受明确的 `execution.mode = 'host'`
- 未分配 Skill/MCP 不可见；分配后的 Skill catalog 可调用 `skill` 加载。
- Ask 不注册 MCP 工具；Execute 每轮刷新有界 schema，并在调用前再次校验活动请求、模式、参数和自动单次授权 。
- Ask 不注册 MCP 工具；Execute 每轮刷新有界 schema，并在调用前再次校验活动请求、模式、参数和 RuntimeAuthorizer 结果 。
- MCP URL、启动命令和凭据不进入 Utility 启动配置或协议结果。
- 未知授权结果失败关闭。
- 超时、取消、迟到帧和进程意外退出。
- 协议帧、事件队列、工具摘要和 stderr 上限。
- release 和 dispose 的幂等性。
- 状态卡中的状态、路径、版本和强制程度 。
- 状态卡中的状态、路径、版本和当前用户执行权限 。
### 17.2 本地集成测试
@@ -582,6 +572,7 @@ Renderer 只接收脱敏状态。任何凭据、完整环境、启动参数或
- Session 释放。
- Runtime 替换。
- 进程树回收。
- 本地 Filesystem 与 Shell Provider 使用规范化工作区作为默认工作目录，且不报告沙箱强制模式。
- 受控配置不会读取工作区 `.env` 和用户 DSH 配置。
### 17.3 真实模型测试
@@ -591,8 +582,8 @@ Renderer 只接收脱敏状态。任何凭据、完整环境、启动参数或
1. 文本问答成功，并记录正确 Runtime 和模型用量。
2. Ask 可以读取工作区，但写入被拒绝，且不会弹出权限对话框。
3. Execute 可以在工作区创建测试文件。
4. Execute 越界操作先被拒绝，再对完全相同的重试自动给予单次授权，全程不弹出审批 。
5. 不匹配的重试、Ask 和 delegation 不能换路径或重复绕过 。
4. Execute 工具确实以当前用户权限运行，且状态和握手不宣称 OS 隔离 。
5. Ask、delegation 和无活动请求不能绕过工具分发检查 。
6. 取消长请求后不再产生文本，并可继续使用其他 Session。
7. 两个 Session 可并行，事件不会串线。
8. 释放会话和关闭应用后没有残留 Harness 或工具进程。
@@ -619,11 +610,11 @@ npm run build
功能只有同时满足以下条件才算完成：
- `deepseek-harness` 可被保存、选择、检测和显示。
- Runtime 详情卡内显示状态、路径、版本和沙箱强制程度 。
- Runtime 详情卡内显示状态、路径、版本和当前用户执行权限 。
- Skills 与 MCP 设置页可把能力分配给 DeepSeek Harness，布局、键盘语义、文案和保存回显通过真机检查。
- Ask 写入测试在 Runtime 边界失败。
- Execute 工作区内写入成功。
- 越界写入只有同一操作获得自动单次授权后才能执行一次，且不弹出审批 。
- Runtime OS 沙箱设置、平台 Runner、启动探测和原生沙箱打包产物均不存在 。
- 取消、超时、切换 Runtime 和退出应用均能回收进程。
- 多会话不串流、不串权限请求、不串用量。
- 用户 DSH 配置、`.env` 、遥测和 Web UI 未被加载。
@@ -636,7 +627,7 @@ npm run build
## 19. 已知限制
- DeepSeek Harness 底层库当前是 RC，但 GoodBuddy 不自动跟随升级；每次升级都可能要求同步修改内部控制面。
- Windows ACL 和部分 Linux Landlock 环境只能提供部分强制执行 。
- Harness 文件和命令工具没有 Runtime OS 隔离，会继承 GoodBuddy 客户端当前用户能够访问的主机资源 。
- 首版不恢复 Harness 原生 Session，
- 首版不支持图片、知识库、浏览器工具和 Harness Subagent；
- 推理、工具和用量扩展属于 GoodBuddy 协议，不是标准 ACP 保证。
@@ -648,8 +639,8 @@ GoodBuddy 对该 Runtime 采用内部维护策略：
1. 当前通过验证的 Host、控制协议和依赖锁定随 GoodBuddy 一起版本化。
2. 不自动跟随 DSH RC、插件 ABI、profile 格式或市场元数据变化。
3. 升级前审查实际用户收益、上游 diff、沙箱与 工具语义、协议行为、依赖闭包和许可证。
4. 六个平台的单元、假模型、UtilityProcess、沙箱 和真实模型门禁全部通过后才能更新基线。
3. 升级前审查实际用户收益、上游 diff、主机 工具语义、协议行为、依赖闭包和许可证。
4. 六个平台的单元、假模型、UtilityProcess、主机执行 和真实模型门禁全部通过后才能更新基线。
5. 若上游方向不再满足 GoodBuddy 用户需求或安全边界，允许维护兼容补丁、替换单个底层包，或逐步移除 DSH 依赖；`goodbuddy/*` 内部协议保持由 GoodBuddy 控制。
6. 不以进入官方插件目录、适配市场机制或服务非 GoodBuddy 客户端作为目标。
mesalogo