docs: organize product design by feature
Define repository and feature-scoped documentation rules for PRDs, User Stories, logic, UI, technical design, and progress evidence. Move feature-owned documents under docs/features, add one entry point per feature, remove the redundant docs index, and update all affected cross-references. Expand the local tool environment design with explicit product, story, logic, UI, technical, and progress documents.
This commit is contained in:
mesalogo
@@ -0,0 +1,123 @@
|
||||
# GoodBuddy Feature Documentation Guide
|
||||
|
||||
## Scope
|
||||
|
||||
These instructions apply to all files under `docs/features/`.
|
||||
|
||||
Each direct child directory represents one user-visible product feature or one coherent feature family. Organize documentation by feature ownership first, then by document responsibility.
|
||||
|
||||
## Standard Structure
|
||||
|
||||
Use the smallest applicable subset:
|
||||
|
||||
```text
|
||||
docs/features/<feature-name>/
|
||||
README.md
|
||||
prd.md
|
||||
user-stories.md
|
||||
logic-design.md
|
||||
ui-design.md
|
||||
technical-design.md
|
||||
progress.md
|
||||
```
|
||||
|
||||
Additional documents are allowed when one standard file would mix independent responsibilities. List every additional document and its unique responsibility in the feature `README.md`.
|
||||
|
||||
Do not create empty placeholders. If a standard document is not needed yet, omit it and state the missing responsibility in `README.md` only when that absence matters to current work.
|
||||
|
||||
## Document Responsibilities
|
||||
|
||||
### `README.md`
|
||||
|
||||
- The sole entry point for the feature.
|
||||
- Summarizes feature purpose and boundary.
|
||||
- Lists all feature documents and their authoritative responsibilities.
|
||||
- Defines feature-specific terminology.
|
||||
- Points to cross-feature dependencies without copying them.
|
||||
|
||||
### `prd.md`
|
||||
|
||||
- Defines the user problem, goals, scope, non-goals, functional requirements, and product acceptance.
|
||||
- Describes what the product must do, not module layout or implementation mechanics.
|
||||
- Records explicit limitations when a workflow is intentionally unsupported.
|
||||
|
||||
### `user-stories.md`
|
||||
|
||||
- Defines user roles, scenarios, and Given/When/Then-style acceptance.
|
||||
- Covers first use, normal use, failure recovery, compatibility, permissions, and boundary cases relevant to real users.
|
||||
- Keeps implementation details out unless the detail is itself an observable contract.
|
||||
|
||||
### `logic-design.md`
|
||||
|
||||
- Defines invariants, state dimensions, state transitions, decision tables, priority rules, failure outcomes, and cross-story consistency.
|
||||
- Resolves overlap between PRD requirements and User Stories before technical implementation.
|
||||
- Includes a logic completeness assessment and identifies unresolved product decisions separately from technical selection work.
|
||||
|
||||
### `ui-design.md`
|
||||
|
||||
- Defines feature information architecture, shared component usage, states, copy, feedback, keyboard behavior, accessibility, and responsive behavior.
|
||||
- Must follow the repository root `UI-DESIGN.md`.
|
||||
- Does not create feature-local visual systems when shared tokens and primitives already exist.
|
||||
|
||||
### `technical-design.md`
|
||||
|
||||
- Defines process and module boundaries, shared contracts, persistence, IPC, lifecycle, packaging, compatibility, validation, and implementation order.
|
||||
- Implements the PRD and logic design rather than redefining their behavior.
|
||||
- Follows KISS and YAGNI. Do not add recovery or compatibility machinery without a demonstrated requirement.
|
||||
|
||||
### `progress.md`
|
||||
|
||||
- Records only verified implementation facts, remaining work, blockers, validation commands, and dated evidence.
|
||||
- Never marks an item complete based only on a design, mock, schema, or injected fake when the production path remains incomplete.
|
||||
- Does not duplicate future design. Link back to the authoritative document.
|
||||
|
||||
## Traceability
|
||||
|
||||
For non-trivial features:
|
||||
|
||||
1. PRD requirements use stable IDs such as `FR-1`.
|
||||
2. User Stories use stable IDs such as `US-A1`.
|
||||
3. Logic design maps rules and state transitions to PRD and User Story IDs.
|
||||
4. UI and technical design link to the PRD and logic design.
|
||||
5. Progress items map to implementation stages and record actual validation.
|
||||
|
||||
Do not renumber stable IDs merely for presentation after implementation begins.
|
||||
|
||||
## Source of Truth
|
||||
|
||||
- PRD owns product scope and requirements.
|
||||
- User Stories own user scenarios and scenario acceptance.
|
||||
- Logic design owns behavioral decisions and state rules.
|
||||
- Root `UI-DESIGN.md` owns global UI consistency; feature UI design owns feature-specific application.
|
||||
- Technical design owns implementation architecture.
|
||||
- Progress owns current implementation and validation status.
|
||||
- Final code and validated runtime behavior override stale documentation. Correct all affected documents when they diverge.
|
||||
|
||||
## Feature Boundaries
|
||||
|
||||
- Keep a document in a feature directory when one feature can own its behavior and acceptance.
|
||||
- Keep a document in `docs/architecture`, `docs/quality`, `docs/development`, or `docs/roadmap` only when it truly governs multiple features and has no single feature owner.
|
||||
- Reference cross-feature documents rather than copying their definitions.
|
||||
- When two features share a global domain model, keep that model in the feature family that owns the domain or in cross-feature architecture if ownership is genuinely global.
|
||||
|
||||
## Migration Rules
|
||||
|
||||
When moving existing documentation:
|
||||
|
||||
1. Preserve content and Git history where practical.
|
||||
2. Update every repository link to the new path.
|
||||
3. Add or update the destination feature `README.md`.
|
||||
4. Delete the old authoritative path; do not leave a duplicate compatibility copy.
|
||||
5. Do not rewrite unrelated document content merely because the file moved.
|
||||
6. Preserve uncommitted user edits while moving files.
|
||||
7. Verify all relative Markdown links after migration.
|
||||
|
||||
## Review Checklist
|
||||
|
||||
- The feature has one clear entry point.
|
||||
- Every document has one declared responsibility.
|
||||
- Product requirements, stories, logic, UI, technical design, and progress do not contradict each other.
|
||||
- Normal, failure, cancellation, compatibility, permission, and scope behavior are covered where applicable.
|
||||
- UI behavior follows `UI-DESIGN.md`.
|
||||
- Progress claims are backed by dated evidence.
|
||||
- All relative links resolve.
|
||||
@@ -0,0 +1,13 @@
|
||||
# 助手工作栏
|
||||
|
||||
助手工作栏统一承载本机与远程执行空间、Task、成果、文件、浏览器和终端等持续工作界面。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [通用助手工作栏与执行空间 PRD](./prd.md) | 工作栏整体产品范围、执行空间和各工作面板归属 |
|
||||
| [多终端页签 PRD](./terminal-tabs-prd.md) | 多终端 Tab、目标选择、关闭确认和终端生命周期 |
|
||||
|
||||
当前尚未拆出独立 User Stories、功能逻辑、UI 设计、技术设计和进度文档；相关内容仍保留在
|
||||
两份现有 PRD 中，后续实际维护该功能时按职责拆分。
|
||||
@@ -0,0 +1,988 @@
|
||||
# 通用助手工作栏与执行空间 PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 设计中 |
|
||||
| 版本 | 0.6 |
|
||||
| 日期 | 2026-08-31 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md)、[SSH 远程主机与 GoodBuddy Agent 实现说明](../remote-host/technical-design.md) |
|
||||
| 相关能力 | [会话监督](../conversation-supervision/prd.md)、[自动化平台](../../architecture/automation-platform-architecture.md)、[长期助手路线图](../../roadmap/long-term-assistant-roadmap.md) |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
GoodBuddy 已经在聊天右侧提供任务中心、工作区、浏览器和成果面板，也已经具备
|
||||
Runtime 事件、Git 变更、文件预览、成果存储、受控浏览器和专家执行等基础能力。后续还
|
||||
计划增加：
|
||||
|
||||
- Conversation、Task 和实验的独立监督。
|
||||
- OpenCode、Continue 和 DeepSeek Harness 的 Runtime 生命周期监督。
|
||||
- 用户可直接使用的终端和受管进程。
|
||||
- HTML 等成果的即时安全预览。
|
||||
- 本机与 SSH 远程主机上的工作区和 Agent Runtime。
|
||||
|
||||
这些能力不能被收束为只面向编程的工作台。监督、Runtime、终端、进程、浏览器和成果
|
||||
都可以服务于普通问答、内容分析、自动化、数据处理、远程运维、知识整理和软件开发。
|
||||
同时，能力目录也不能根据当前页面、项目类型或 Runtime 能力无提示地变化，否则用户无法在
|
||||
需要时主动打开面板并选择目标、主机或运行环境。
|
||||
|
||||
本设计把右侧区域定义为应用级的“助手工作栏”，并把本机或远程的目录、终端、进程和
|
||||
Runtime 统一抽象为“执行空间”。
|
||||
|
||||
## 2. 产品定义
|
||||
|
||||
### 2.1 助手工作栏
|
||||
|
||||
助手工作栏是 GoodBuddy 中始终可访问的应用级工具容器。它提供稳定能力目录，用户从中
|
||||
查看任务中心，并按需打开一个或多个监督、Runtime、终端、进程、工作区、浏览器和成果
|
||||
面板实例。稳定的是能力的可发现性，不是八个同时占据界面的固定面板。
|
||||
|
||||
工作栏不是：
|
||||
|
||||
- 只在编程项目中出现的 IDE 面板。
|
||||
- 当前聊天消息的附属详情框。
|
||||
- 根据能力探测结果自动增删入口的动态菜单。
|
||||
- 绕过 Main、Preload、Ask/Execute 或审批边界的控制台。
|
||||
- 全系统进程管理器、任意文件浏览器或无边界远程管理工具。
|
||||
|
||||
### 2.2 执行空间
|
||||
|
||||
执行空间描述工作区、终端、受管进程和 Agent Runtime 实际运行的位置：
|
||||
|
||||
```ts
|
||||
type ExecutionSpaceSelection =
|
||||
| {
|
||||
kind: 'local'
|
||||
rootPath?: string
|
||||
}
|
||||
| {
|
||||
kind: 'ssh'
|
||||
hostId: string
|
||||
remoteRootPath?: string
|
||||
}
|
||||
```
|
||||
|
||||
执行空间可以来自当前项目，也可以由用户在工作栏中临时选择。临时选择不会静默修改项目
|
||||
设置，也不直接授予文件、终端或 Runtime 能力。Main 必须先把选择草稿验证为绑定窗口、
|
||||
controller、Host/Workspace identity、信任 revision、能力和 lease 的 opaque 临时 Grant；
|
||||
后续 IPC 只引用 Grant ID。只有用户显式保存并重新通过 Project 候选验证时才成为项目默认值。
|
||||
|
||||
## 3. 核心产品原则
|
||||
|
||||
### 3.1 能力目录稳定，面板实例由用户控制
|
||||
|
||||
工作栏能力目录提供以下标准能力：
|
||||
|
||||
```text
|
||||
任务中心
|
||||
监督
|
||||
Runtime
|
||||
终端
|
||||
进程
|
||||
工作区
|
||||
浏览器
|
||||
成果
|
||||
```
|
||||
|
||||
- 应用不得根据当前项目、会话、Runtime、主机或探测结果无提示地增删能力目录项。
|
||||
- 用户主动打开、关闭、排序和停靠面板实例；应用不默认同时挂载全部能力。
|
||||
- Task Center 是 Task 的单例应用级索引。每个 Task 只关联一条 Conversation，一条
|
||||
Conversation 可以关联多个 Task；Task Center 不复制会话内容，也不显示普通 Conversation、
|
||||
Job、Run 或心跳事项。
|
||||
- 当前能力、连接、数据和空状态可以动态变化。
|
||||
- 能力不可用时，目录项或已打开面板显示原因、影响和可执行的配置或切换入口，不能只通过隐藏表示。
|
||||
- 用户可以在设置中调整目录顺序；恢复默认布局恢复标准目录与默认打开面板，不强制打开全部能力。
|
||||
- 同一能力需要并排比较不同目标时可以创建多个实例，每个实例拥有独立身份和范围绑定。
|
||||
|
||||
### 3.2 当前上下文只提供默认值
|
||||
|
||||
任务中心作为全局索引不跟随当前会话，也不支持为同一列表打开多个目标实例。其他可绑定
|
||||
目标的能力使用当前会话、项目、Runtime 和主机帮助新面板实例初始定位，但这些上下文不是
|
||||
使用门槛：
|
||||
|
||||
- 监督默认选择当前会话，用户可以改选其他 Conversation、Task 或实验对象。
|
||||
- Runtime 默认跟随当前会话或 Task；执行事件可以查看，但 Job/Run 不作为独立选择对象。
|
||||
- 终端创建时固定到当前项目执行空间，由项目配置自动决定本机或托管 SSH；没有当前项目时
|
||||
使用本机 Home。
|
||||
- 工作区默认显示当前项目目录，用户可以打开其他本机目录或远程目录。
|
||||
- 成果默认使用当前范围，用户可以切换到项目、全局或其他允许范围。
|
||||
- 下一次请求的附件和知识库由当前 Composer 展示与管理，不作为工作栏能力。历史执行上下文
|
||||
随关联 Task 查看；记忆功能实现后也归入任务中心，而不是新增独立上下文面板。
|
||||
|
||||
每个可切换目标的面板实例都提供一致的范围模式：
|
||||
|
||||
```text
|
||||
跟随当前上下文
|
||||
固定到指定对象
|
||||
```
|
||||
|
||||
固定目标失效时，面板显示“目标不可用”和修复入口，不静默回到其他目标。
|
||||
|
||||
### 3.3 用户控制打开、切换和介入
|
||||
|
||||
- 后台事件可以更新目录徽标、面板状态和通知，但不得无条件抢占当前面板。
|
||||
- 只有用户刚刚发起且明确需要面板完成的交互，才可以打开对应面板。
|
||||
- 浏览器画面、审批、监督警告、Runtime 失败和终端退出默认通过徽标或通知提示。
|
||||
- 高风险状态必须持续可见，但不以自动切页代替用户选择。
|
||||
- 用户切换页面、会话或项目时，已固定的面板目标保持不变；跟随模式才更新目标。
|
||||
|
||||
### 3.4 入口稳定不等于虚假能力
|
||||
|
||||
稳定能力目录和已打开面板必须准确呈现能力差异：
|
||||
|
||||
- 当前 Runtime 不支持后台 Job 时，Runtime 能力仍可发现；打开后说明当前可监督的内容。
|
||||
- 当前执行空间没有 Git 仓库时，工作区文件功能仍可使用，Git 区域显示不可用原因。
|
||||
- 没有活动进程时，进程面板提供创建终端或启动 Runtime 的入口。
|
||||
- 没有项目时，终端使用当前用户本机 Home；工作区等允许选择路径的能力仍必须先取得有界
|
||||
临时 Execution Space Grant，不能把可选路径直接传给文件、Git、Process 或 Runtime。
|
||||
- 监督未启用时，监督面板提供目标、模式和“开始监督”，而不是隐藏能力。
|
||||
|
||||
不得渲染成排没有解释的禁用按钮，也不得把“进程连通”描述为已经支持完整原生监督。
|
||||
|
||||
### 3.5 通用能力与领域能力分层
|
||||
|
||||
- 监督判断目标、证据、矛盾、遗漏、质量和风险，不假设目标一定是编程。
|
||||
- Runtime 监督展示运行生命周期，不假设 Runtime 一定是 OpenCode。
|
||||
- 终端和进程是通用执行能力，不只服务代码构建。
|
||||
- 工作区可以是文档、数据、知识或代码目录；Git 是可选区域。
|
||||
- HTML 预览属于通用成果能力，不只用于网页开发。
|
||||
- SSH 主机可以承载 Agent、自动化、数据处理和工作区，不只代表远程代码仓库。
|
||||
|
||||
## 4. 目标
|
||||
|
||||
### 4.1 用户目标
|
||||
|
||||
- 从任意主要页面随时发现同一组稳定能力，并按需打开所需面板。
|
||||
- 自主选择每个可绑定目标的面板实例跟随当前上下文还是固定到指定目标。
|
||||
- 在不中断主任务的情况下观察监督意见、Runtime、进程和成果。
|
||||
- 随时创建本机或远程终端，并理解其执行位置和权限。
|
||||
- 查看 GoodBuddy 管理的进程及其来源、输出和停止状态。
|
||||
- 对生成的 HTML、Markdown、JSON、图片等成果进行即时安全预览。
|
||||
- 管理 SSH 主机，并在远程执行空间中运行受控 Agent Runtime。
|
||||
|
||||
### 4.2 产品目标
|
||||
|
||||
- 建立不依赖具体页面和 Runtime 的应用级工作栏、能力目录和面板实例壳层。
|
||||
- 建立统一范围、执行空间、生命周期、成果和控制契约。
|
||||
- 复用现有 Project、Conversation、Task、Artifact、Activity 和 Approval 数据。
|
||||
- 保持 Renderer 无任意文件、进程、PTY、SSH 或 Electron API 能力。
|
||||
- 保持 Ask 只读、Execute 审批、取消、超时、输出边界和活动审计。
|
||||
- 为本机与远程能力提供一致 UI，同时准确表达能力差异。
|
||||
|
||||
## 5. 非目标
|
||||
|
||||
- 不把 GoodBuddy 改造成完整 IDE。
|
||||
- 不提供全系统进程枚举和任意 PID 终止。
|
||||
- 不默认扫描用户全部目录、远程主机或 SSH 配置。
|
||||
- 不允许 Agent 未经现有 Runtime 边界直接向用户终端注入输入。
|
||||
- 不自动执行 HTML 中的脚本或访问网络。
|
||||
- 不让监督器自动替用户发言、批准工具、扩大范围或修改安全策略。
|
||||
- 不提供以 SSH 连接为生命周期的临时远程 Agent；远程执行必须由用户级常驻 Daemon 承载。
|
||||
- 不支持任意 ProxyCommand、任意端口转发或 SSH Agent Forwarding。
|
||||
- 不要求所有 Runtime 提供相同的 Subagent、Job、Hook 或会话能力。
|
||||
|
||||
## 6. 信息架构
|
||||
|
||||
### 6.1 应用级位置
|
||||
|
||||
助手工作栏位于主窗口右侧，但不归属于聊天页面。聊天、知识、魔法笔记、自动化、活动记录
|
||||
等主要页面都可以打开它。各页面可以提供默认范围，不能维护互不相容的右栏副本。
|
||||
|
||||
```text
|
||||
┌──────────────┬──────────────────────────────┬────────────────────────┐
|
||||
│ 主导航 │ 当前主任务 │ 助手工作栏 │
|
||||
│ │ │ │
|
||||
│ 会话 / 知识 │ 聊天、文档、自动化或数据视图 │ 稳定能力目录 │
|
||||
│ 自动化 / 活动│ │ 用户打开的面板实例 │
|
||||
│ 设置 │ │ 各实例范围与执行空间 │
|
||||
└──────────────┴──────────────────────────────┴────────────────────────┘
|
||||
```
|
||||
|
||||
### 6.2 能力目录与面板实例
|
||||
|
||||
能力目录不等于同时打开八个面板。当前产品采用“已打开实例 Tab + 持久新增按钮”的工作栏
|
||||
模型：Tab 行只显示已打开实例，行末“+”始终可见；点击后在工作栏内容区打开稳定能力目录，
|
||||
用户再创建或激活应用实例。详细交互以
|
||||
[助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) 为准。
|
||||
|
||||
- 每项始终显示稳定图标，并提供可见标签或可持续查看的工具提示。
|
||||
- 已打开实例使用 `tablist`、`tab`、`tabpanel`；“+”是位于 `tablist` 外的普通命令按钮。
|
||||
- 应用注册表声明 `single` 或 `multiple`。重复选择单实例应用时聚焦已有实例；选择多实例
|
||||
应用时每次创建新实例。
|
||||
- 支持方向键、Home、End、Enter、Space、关闭面板和正确焦点恢复。
|
||||
- 徽标显示未解决数量、等待审批或失败状态，并同时提供文字或可访问名称。
|
||||
- 用户调整目录顺序、打开实例、停靠位置和尺寸后持久化；关闭实例后能力仍可从目录重新打开。
|
||||
- 默认布局只恢复经过产品确认的少量常用面板，不自动打开全部标准能力。
|
||||
- 每个实例显示稳定实例 ID、能力名称、跟随或固定状态与当前目标；同能力多实例不能只靠位置区分。
|
||||
|
||||
从当前聊天右栏迁移时，Task Center、工作区、浏览器和成果作为默认打开的单实例应用保留；
|
||||
终端不默认打开，由用户通过“+”创建，并从首期开始支持多实例。Tab 必须单行横向滚动，
|
||||
不能自动隐藏或缩写到不可辨认，“+”不能随滚动消失。Task Center 继续作为 Task 的现有
|
||||
入口；审批定位到所属 Task 或 Runtime。智能心跳不作为工作栏页签，其报告、建议、历史和
|
||||
完整配置统一归属“智能心跳”菜单入口。当前阶段不新增独立自动化中心。
|
||||
|
||||
### 6.3 工作栏尺寸
|
||||
|
||||
- 所有窗口宽度下工作栏都停靠右侧并参与水平布局回流；展开时主工作区同步收缩，不能覆盖
|
||||
或遮罩其内容。
|
||||
- 分栏计算排除最左侧主导航，主工作区与工作栏使用相同的 `300px` 最小宽度。拖动记录两侧
|
||||
在可用分栏宽度中的比例；任一侧达到最小值后停止，窗口缩放后按原比例重新计算并再次
|
||||
应用同一最小值约束。
|
||||
- 最左侧主导航保持全高连续表面；窗口标题栏只覆盖右侧内容框架，不能横跨主导航并把品牌、
|
||||
项目切换器和导航整体向下推移。
|
||||
- 对话内容与输入区始终保留对称的左右安全边距，工作栏边界不得覆盖或裁切输入框、发送
|
||||
按钮及主工作区右侧边距。
|
||||
- 唯一展开与收起开关固定在窗口关闭按钮正下方。工作栏内部不重复关闭入口。开关图标中的
|
||||
箭头方向随当前动作切换，按钮不以持续高亮表达展开状态；当前会话没有 Task 时不渲染空
|
||||
Task 上下文栏。
|
||||
- “新建任务”入口位于工作栏“任务索引”标题后方，不在会话 Task 上下文栏重复出现；索引
|
||||
状态筛选占满可用宽度并等分各筛选项。
|
||||
- 终端、宽日志和大型成果允许用户切换到底部停靠或独立窗口。
|
||||
- 应用只建议适合的布局，不因面板内容自动改变用户已经选择的停靠位置。
|
||||
|
||||
## 7. 能力与面板定义
|
||||
|
||||
### 7.1 Task Center
|
||||
|
||||
Task Center 保留为工作栏中的稳定入口，并在现有基础上适度完善：
|
||||
|
||||
- 只索引 Task；每个 Task 只关联一条 Conversation，一条 Conversation 可以关联多个 Task。
|
||||
- 显示名称、关联 Conversation、Global 或 Project 范围、Ask/Execute、状态、最近进展、
|
||||
真实活动时间和需要关注信息。
|
||||
- 点击 Task 打开其关联 Conversation 并定位 Task。
|
||||
- 完整消息留在 Conversation；工具、Subagent、审批、错误和成果按 Task 关联到 Runtime、
|
||||
活动记录和成果查看器中，不在窄栏复制，也不呈现 Job/Run 树。
|
||||
- 智能心跳的报告、建议、历史和配置不进入任务中心。
|
||||
|
||||
任务中心是单例索引，不使用其他能力的“跟随 / 固定目标”多实例模型。后台状态可以更新
|
||||
徽标和排序，但不能自动打开面板或抢占用户当前工作。
|
||||
|
||||
主侧栏最近会话为关联 Task 提供轻量入口：父会话行只显示行首展开按钮，Task 子项使用
|
||||
任务图标和本地化摘要，展开层级只到 Task；点击 Task 子项打开同一 Conversation 并定位。
|
||||
新建定制任务使用 Modal 选择当前或新
|
||||
Conversation，默认 Execute，并持续显示 Runtime、Project、工作目录、工具和审批摘要。
|
||||
|
||||
详细产品边界以 [Task Center PRD](../task-and-job/task-center-prd.md) 和
|
||||
[Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) 为准。
|
||||
|
||||
### 7.2 监督
|
||||
|
||||
监督是通用观察与评论入口，详细行为以
|
||||
[会话监督 PRD](../conversation-supervision/prd.md) 为准。
|
||||
|
||||
监督能力在目录中稳定可发现；用户打开面板实例后可以选择：
|
||||
|
||||
- 普通会话。
|
||||
- Task。
|
||||
- 实验或实验结果。
|
||||
- 后续支持的文档分析和其他可监督对象。
|
||||
|
||||
监督面板包含：
|
||||
|
||||
- 当前目标与范围。
|
||||
- 开启状态、监督模式、触发方式和预算。
|
||||
- 评论、警告、人工复核请求和证据。
|
||||
- 未解决、已查看、已解决、忽略和误报状态。
|
||||
- “带入输入框”“查看证据”“追问”“停止当前回复”等用户介入操作。
|
||||
|
||||
“采纳”只生成可编辑草稿或显式会话操作，不自动发送、执行、切换 Execute 或批准工具。
|
||||
|
||||
### 7.3 Runtime
|
||||
|
||||
Runtime 能力统一监督直连模型、OpenCode、Continue、DeepSeek Harness 和后续 Runtime。
|
||||
能力在目录中稳定可发现，打开的面板实例依据所选 Runtime 的真实能力显示状态。
|
||||
远程实现先只交付 OpenCode 官方 ACP 闭环；Continue 与 DeepSeek Harness 后续复用同一
|
||||
面板和通道契约。产品不为并行建设多套后端而增加用户可见模式或临时入口。
|
||||
|
||||
共同区域：
|
||||
|
||||
- Runtime、模型连接、Conversation 或 Task 身份。
|
||||
- 活动请求、状态、耗时、用量和取消。
|
||||
- 工具、审批、问题、上下文压缩和错误。
|
||||
- 跳转完整活动记录和持久设置。
|
||||
|
||||
可选区域：
|
||||
|
||||
- Task 级委派状态和取消。
|
||||
- Task 级后台执行进度、结果和终止。
|
||||
- Todo、Workflow 和 Hook 运行。
|
||||
- 原生会话、暂停、恢复、压缩或释放。
|
||||
|
||||
可选区域不可用时，用一段有操作路径的状态说明替代空卡片。用户可以在面板中切换 Runtime
|
||||
或 Conversation / Task 目标，不要求先回到聊天 Composer。内部 Job/Run 事件按 Task
|
||||
聚合，不提供 Job/Run 选择器、树、页面或独立操作菜单。
|
||||
|
||||
### 7.4 终端
|
||||
|
||||
终端面板允许用户通过工作栏“+”主动创建和管理多个本机或 SSH 终端。详细产品行为、首期
|
||||
直接 SSH PTY 技术选择、生命周期和验收以
|
||||
[助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) 为准。
|
||||
|
||||
- 新建、重命名、切换、关闭和重新连接终端。
|
||||
- 创建时自动绑定当前项目执行空间、权威工作目录和平台默认 Shell，不显示重复目标选择。
|
||||
- 显示本机或远程主机、目录、Shell 和连接状态。
|
||||
- 支持复制、粘贴、搜索、清屏、滚动和调整终端尺寸。
|
||||
- 支持将终端切换到右侧、底部或独立窗口。
|
||||
|
||||
终端属于用户交互表面。Agent 工具调用可以产生独立受管进程和日志，但不能伪装成用户终端，
|
||||
也不能在没有明确授权的情况下向现有终端发送按键或命令。
|
||||
|
||||
### 7.5 进程
|
||||
|
||||
进程面板只展示 GoodBuddy 创建、托管或明确接管的进程：
|
||||
|
||||
- 用户终端 Shell。
|
||||
- Runtime Host、Server、Utility 和远程 GoodBuddy Agent。
|
||||
- Runtime 后台 Job。
|
||||
- 用户通过工作栏显式启动的长运行命令。
|
||||
- 浏览器或自动化中属于 GoodBuddy 的受管子进程摘要。
|
||||
|
||||
每项显示：
|
||||
|
||||
- 名称和有界命令摘要。
|
||||
- 来源、执行空间、项目或会话归属。
|
||||
- 启动时间、状态、退出码和资源摘要。
|
||||
- 有界 stdout/stderr 或结构化日志。
|
||||
- 正常终止、必要时强制终止和打开关联对象。
|
||||
|
||||
Renderer 不接收任意系统 PID 控制能力。控制动作引用 Main 签发的受管进程 ID，并由 Main
|
||||
重新验证所有权、当前状态和允许操作。
|
||||
|
||||
### 7.6 工作区
|
||||
|
||||
工作区面板允许用户选择：
|
||||
|
||||
- 当前项目目录。
|
||||
- 其他本机目录。
|
||||
- 已配置 SSH 主机上的远程目录。
|
||||
|
||||
面板提供：
|
||||
|
||||
- 有界目录树和文本文件预览。
|
||||
- 当前选择、规范化路径和执行空间。
|
||||
- 可选 Git 状态、Diff 和仓库信息。
|
||||
- 显式打开、下载副本或在终端中打开。
|
||||
- HTML 文件的源码与安全预览。
|
||||
|
||||
本机和远程访问都必须由 Main 或远程 GoodBuddy Agent 在对应文件系统上执行路径规范化、相对路径和
|
||||
符号链接边界检查。Renderer 只能提交受约束的相对路径和已授权范围 ID。
|
||||
|
||||
### 7.7 浏览器
|
||||
|
||||
浏览器能力在目录中稳定可发现，打开面板后允许用户：
|
||||
|
||||
- 创建新的 GoodBuddy 隔离浏览器会话。
|
||||
- 选择当前会话或其他受控浏览器会话。
|
||||
- 查看状态、当前 URL、有界画面和错误。
|
||||
- 通过顶部浏览器工具栏返回、刷新或停止加载、编辑地址并前往。
|
||||
- 进入明确的交互模式或关闭浏览器。
|
||||
|
||||
顶部工具栏按“返回、刷新/停止加载、地址输入、前往、交互、关闭浏览器”组织。“刷新”在
|
||||
页面加载期间原位切换为“停止加载”；“关闭浏览器”是清楚独立于导航的会话生命周期操作，
|
||||
必须与“停止加载”在文案和视觉上明确区分。现有“停止浏览器”语义统一改名为“关闭浏览器”。
|
||||
|
||||
浏览器面板和 Agent 操作同一条按 Conversation 归属的浏览器会话，不创建用户预览专用的
|
||||
第二个页面。用户执行前往、返回或刷新会有意改变 Agent 下一步读取和操作的页面。所有
|
||||
前往、返回和刷新请求都进入 `BrowserService`，并与 Agent 发起的浏览器操作串行执行；不在
|
||||
Renderer 建立第二套导航队列、抢占规则或恢复状态机。
|
||||
|
||||
浏览器工具栏读取的权威状态至少包含：
|
||||
|
||||
```ts
|
||||
type BrowserToolbarState = {
|
||||
committedUrl: string
|
||||
loading: boolean
|
||||
canGoBack: boolean
|
||||
sessionActivity: 'inactive' | 'creating' | 'ready' | 'agent_action' | 'full_interaction'
|
||||
}
|
||||
```
|
||||
|
||||
`committedUrl` 是浏览器已经提交的权威 URL。地址输入在未编辑时与它同步；获得编辑意图后，
|
||||
输入文字保持为 Renderer 本地草稿，画面、加载状态和 URL 更新不得覆盖草稿，直到用户“前往”
|
||||
或放弃编辑。用户提交未带 `http://` 或 `https://` 的裸域名时，Renderer 自动补上
|
||||
`http://`，再通过既有浏览器 URL 策略提交。地址草稿不属于浏览器会话持久状态，也不需要
|
||||
恢复或版本化机制。
|
||||
|
||||
创建会话、Agent 操作和完整交互窗口期间，返回、刷新、地址提交、前往、交互和关闭浏览器
|
||||
控件禁用，避免与同一会话并发操作。例外是活动导航处于加载中时，“停止加载”保持可用，
|
||||
可中断当前页面加载；
|
||||
它只取消页面加载，不销毁浏览器会话、不执行“关闭浏览器”，也不释放当前 Runtime 上下文。
|
||||
“关闭浏览器”沿用现有停止会话的生命周期语义。
|
||||
|
||||
没有浏览器会话时仍显示工具栏。活动 Conversation 可以直接在地址栏输入非空 URL 并“前往”，
|
||||
由 `BrowserService` 通过 Agent 浏览器相同的能力检查和 URL 策略创建会话并导航；不得为这一
|
||||
空状态增加旁路 WebView 或宽松 URL 入口。没有活动 Conversation 时说明需要先选择或创建会话。
|
||||
模型或后台浏览器活动可以更新徽标，但不得无条件打开面板或切换用户当前面板。
|
||||
|
||||
浏览器面板只管理 GoodBuddy 受控浏览器，不表示可以控制用户已安装的浏览器。
|
||||
|
||||
### 7.8 成果
|
||||
|
||||
成果面板统一显示全局、项目、Conversation、Task 执行和监督显式产生的独立成果：
|
||||
|
||||
- Markdown、纯文本和 JSON。
|
||||
- 图片和图表。
|
||||
- HTML 安全预览。
|
||||
- 后续的 PDF、Office、表格和其他受支持格式。
|
||||
|
||||
普通聊天回复只保留在会话消息流中，不自动复制为成果。只有 Runtime 或受管工具显式声明的
|
||||
Artifact、自动化和监督生成的独立输出，以及用户手动导入或明确保存的内容进入成果面板。
|
||||
升级前已经自动保存的普通对话 Markdown 可以从成果列表中隐藏，但不应通过升级迁移物理
|
||||
删除用户数据库内容。
|
||||
|
||||
用户可以切换范围、搜索、预览、查看来源、导出或打开关联对象。成果必须保留项目、
|
||||
Conversation、Task、内部 Run、创建者、MIME、大小、校验值和时间等可用归属；界面按
|
||||
Task 呈现来源，不把 Run 作为导航对象。
|
||||
|
||||
#### HTML 即时预览
|
||||
|
||||
- Runtime 或受管工具通过显式 Artifact 事件声明成果，不能让 Renderer 猜测任意路径。
|
||||
- Main 验证成果属于当前授权执行空间，限制大小、类型和读取范围后再持久化。
|
||||
- HTML 使用 `iframe sandbox=""` 和严格 CSP 进行脚本关闭、网络关闭的静态预览。
|
||||
- 清理脚本、事件属性、嵌套 frame、object、embed、base、link、meta refresh、表单和活动 URL。
|
||||
- 提供“预览 / 源码”切换，并持续标注“静态安全预览，脚本和网络已禁用”。
|
||||
- 不使用 `dangerouslySetInnerHTML`，不启用 Electron `webviewTag`。
|
||||
- 外部打开是明确的用户操作，并说明外部浏览器可能执行脚本或联网。
|
||||
|
||||
### 7.9 Composer 与任务上下文
|
||||
|
||||
工作栏不提供独立“上下文”能力。用户准备下一次模型请求时：
|
||||
|
||||
- 附件、图片、文档提取结果以及知识库范围在 Composer 中展示与管理。
|
||||
- Composer 提供与发送行为直接关联的预览、移除和清空操作，不在工作栏重复入口或状态。
|
||||
- 浏览器、工作区文件、授权目录以及 Runtime 或自动化绑定内容由各自能力展示。
|
||||
- Task 的历史执行上下文作为不可变快照随 Task 查看。
|
||||
- 记忆功能实现前不展示占位内容；实现后在任务中心按关联 Task 展示和管理。
|
||||
|
||||
## 8. 范围和选择模型
|
||||
|
||||
### 8.1 通用目标引用
|
||||
|
||||
各面板实例使用不包含敏感内容的目标引用：
|
||||
|
||||
```ts
|
||||
type WorkbarCapabilityId =
|
||||
| 'supervision'
|
||||
| 'runtime'
|
||||
| 'terminal'
|
||||
| 'processes'
|
||||
| 'workspace'
|
||||
| 'browser'
|
||||
| 'results'
|
||||
|
||||
type WorkbarTargetRef =
|
||||
| { type: 'conversation'; id: string }
|
||||
| { type: 'task'; id: string }
|
||||
| { type: 'experiment'; id: string }
|
||||
| { type: 'project'; id: string }
|
||||
| { type: 'workspace'; id: string }
|
||||
| { type: 'runtime-session'; id: string }
|
||||
| { type: 'terminal'; id: string }
|
||||
| { type: 'managed-process'; id: string }
|
||||
| { type: 'browser-session'; id: string }
|
||||
| { type: 'artifact'; id: string }
|
||||
```
|
||||
|
||||
Renderer 选择目标后，Main 必须重新验证对象存在、归属范围和当前用户可见性。不能把目标 ID
|
||||
直接转换为文件、进程或远程控制权限。
|
||||
|
||||
### 8.2 跟随与固定
|
||||
|
||||
```ts
|
||||
type WorkbarScopeBinding =
|
||||
| { mode: 'follow'; source: 'active-context' }
|
||||
| { mode: 'pinned'; target: WorkbarTargetRef }
|
||||
|
||||
type WorkbarPanelInstance = {
|
||||
id: string
|
||||
capability: WorkbarCapabilityId
|
||||
binding: WorkbarScopeBinding
|
||||
dock: 'right' | 'bottom' | 'window'
|
||||
}
|
||||
```
|
||||
|
||||
- 每个面板实例独立保存绑定方式；同一能力的多个实例不能共享可变选择状态。
|
||||
- 绑定只包含公开 ID，不包含路径、凭据、Token 或日志。
|
||||
- 删除固定目标后保留失效状态，直到用户选择新目标或恢复跟随。
|
||||
- 工作栏重新打开、页面切换和窗口重建后恢复用户打开的实例与选择。
|
||||
|
||||
## 9. 主机管理与远程执行空间
|
||||
|
||||
本节定义产品入口和用户行为。Host Key、凭据、远程 Agent 协议、模型请求代理、签名更新、
|
||||
断线和 Runtime 适配的技术边界以
|
||||
[SSH 远程主机与 GoodBuddy Agent 稳定终态设计](../remote-host/technical-design.md)
|
||||
为准。
|
||||
|
||||
### 9.1 设置入口
|
||||
|
||||
设置中心“平台功能”提供独立“远程项目（技术预览）”页签及开关，默认关闭。关闭时不显示
|
||||
“主机与远程执行”分类、托管 SSH 项目创建选项和已保存远程项目，Main IPC 同时拒绝新的
|
||||
SSH/远程项目操作；已有 Host、项目和凭据保持不变。若当前项目已经是远程项目，则切回
|
||||
项目列表中的第一个普通
|
||||
本地项目。重新启用后恢复完整入口和既有数据。
|
||||
|
||||
启用后，设置中心显示“主机与远程执行”分类，管理：
|
||||
|
||||
- 主机名称、地址、端口和用户名。
|
||||
- 认证方式和凭据配置状态。
|
||||
- Host Key 算法与 SHA-256 指纹。
|
||||
- 引导式身份/认证验证、远程系统和架构。
|
||||
- GoodBuddy Agent、Runtime 和能力状态。
|
||||
- 删除、重新验证或更新 Host Key。
|
||||
|
||||
主机配置是全局资源。项目或工作栏只引用主机 ID，不能复制凭据。
|
||||
删除 Host 前列出所有引用它的本地项目记录，包括归档项目；确认后仅删除本机 Host、凭据、
|
||||
项目和关联数据，不建立 SSH 连接，也不删除远端目录或内容。若当前项目被删除，界面切回
|
||||
普通本地项目。
|
||||
|
||||
当前实施状态：设置中心已经实现主机 CRUD 和模态验证向导。新增或目标/认证编辑依次完成
|
||||
连接信息、认证前 Host Key 核对、密码/系统 SSH Agent 认证和平台/架构/Shell/Home 有界
|
||||
探针，全部成功后才原子保存主机、加密凭据和完整 Host Key。认证失败可在弹窗内修改凭据
|
||||
重试；取消或失败不保留新主机。Key 变化显示旧/新指纹并要求显式高风险确认。项目创建和
|
||||
设置现可选择托管 SSH、已保存 Host、远端工作目录、OpenCode 和 Ask/Execute，不要求
|
||||
额外 trust tier 或 consent checklist。候选完成签名 Agent/Runtime、Workspace、ACP、模型桥
|
||||
和文本模型 profile 验证后原子提交。私钥导入仍未开放。旧流程已保存但
|
||||
没有成功探针记录的主机继续读取，但在完成新向导前显示为“需要重新验证”。
|
||||
|
||||
当前源码已把 Agent/Runtime 生命周期归入 Host 管理。新增或重新验证 Host
|
||||
在身份、认证和系统探针成功后先保存 Host，再只读探测实际组件状态和瞬时下载能力，然后
|
||||
结束新增向导。产品不提供自动安装开关，也不在保存后传输包。Host 卡片只有一个按版本
|
||||
事实显示“安装远程环境”“更新远程环境”或“重新安装”的主按钮；次级 SegmentedControl
|
||||
选择“自动”“Host 下载”或“GoodBuddy 传输”，默认“自动”且不持久化。版本匹配 badge
|
||||
不代表环境健康。环境准备失败或取消保留 Host 并显示可重试状态；重新安装失败时显示
|
||||
本次操作未完成，并以随后重新检查的版本卡片表达当前事实，不对不确定提交宣称旧版本
|
||||
未被替换。详细技术契约见
|
||||
[SSH Host 远程环境准备与直连下载设计](../remote-host/environment-provisioning-technical-design.md)。
|
||||
|
||||
进入或切回“主机与远程执行”页面只读取本地 Host 列表，不逐台建立 SSH 连接。版本和瞬时
|
||||
下载能力仅在用户点击某台 Host 的“刷新版本”时探测，成功结果在当前 Renderer 进程内按
|
||||
Host 持久化缓存，切换页面或重启应用后返回直接显示；Host 编辑、删除或开始更新远程环境后
|
||||
不复用旧结果。该动作不是项目连接前置条件；用户
|
||||
切换已有远程项目只更新 Renderer 的本地项目选择，不建立 Host/Agent 连接。
|
||||
新建远程项目弹窗同样只读取本地 Host 验证记录，不扫描所有 Host；浏览目录或保存时才连接
|
||||
所选 Host。版本号相同时仍允许用户显式重新安装，以修复 registry、签名或 identity 异常，
|
||||
且不删除 Host、凭据或项目。由远程主机安装只使用 SSH 和远端系统工具，不依赖已有 Agent；
|
||||
“自动”仅在操作开始时探测：直连明确可用才选 Host 下载，否则选 GoodBuddy 传输；用户
|
||||
显式选择不被改写，prepare、commit 或 adoption 失败后不在同次操作中切换 acquisition。
|
||||
|
||||
项目选择器中每个项目的管理按钮默认隐藏，在悬停、键盘焦点或触屏环境显示。该入口直接
|
||||
打开目标项目设置而不先切换项目，因此 Host 不可达或远端目录已不存在时仍可删除本地项目
|
||||
记录；删除操作从不删除远端项目内容。
|
||||
|
||||
应用重启后固定进入项目列表中的第一个普通本地项目。用户主动打开已有托管 SSH 项目时只
|
||||
切换本地项目配置；首次实际使用 Workspace 或 Runtime 时，Main 才通过 Agent/Runtime
|
||||
安装管理器解析 Host current identity，执行固定 `attach-or-bootstrap`，并使用同一 Agent
|
||||
连接。
|
||||
项目数据库不保存 Agent installation、Host revision、Workspace identity 或 Runtime
|
||||
digest。当前 registry、连接或 capability 无效时项目保持未切换，并提示到 Host 管理显式
|
||||
修复。当前进程缓存每个 Host 已确认的 Agent/Runtime identity，并复用 Agent 连接；Host
|
||||
编辑或环境更新会定向清空。Agent 的 attach/按需启动只读取 Host 管理已提交的 registry 与
|
||||
匹配 manifest 元数据，不重新验签或哈希完整 Agent payload。项目切换器立即提交本地选择，
|
||||
不展示远程激活进度；完整进度和取消只属于新建或显式保存项目。
|
||||
|
||||
项目只持久化 Host ID、规范远端路径、Runtime 选择和默认工作模式。新建和保存验证当前
|
||||
Workspace/Runtime，但不写入组件 identity；普通切换不做远程验证。未就绪或版本过旧时，
|
||||
实际 Workspace/Runtime 操作显示错误。桌面更新造成组件版本变化时，用户先在 Host 管理中
|
||||
准备环境；项目切换本身不连接、不下载、不扫描、不安装，也不改写项目。
|
||||
|
||||
已保存 Host 的地址、用户或固定 Host Key 变化后，Main 关闭旧连接并定向退役该 Host 的
|
||||
Runtime 缓存。引用项目下次选择时使用 Host 管理的当前 revision、Host Key 和用户执行固定
|
||||
attach 并读取 current registry，不存在项目中的旧 Host revision 或组件 identity；
|
||||
当前环境无效时才要求显式修复。
|
||||
|
||||
新建托管 SSH 项目时，远端工作目录既可手工输入，也可通过文件夹按钮打开 Main 管理的
|
||||
只读、有界 SFTP 目录选择器。选择器从 SSH 账号 Home 或当前有效绝对路径开始，只返回目录，
|
||||
支持上级、刷新、取消和选择当前目录；Host 变化、连接错误或取消都保留草稿，选择结果不会
|
||||
绕过正常项目验证与保存事务。
|
||||
|
||||
### 9.2 凭据和主机验证
|
||||
|
||||
- 优先支持系统 SSH Agent 或 OpenSSH 证书。
|
||||
- 导入私钥或密码时使用 Electron `safeStorage` 加密。
|
||||
- 凭据绑定主机 ID、地址、端口、用户名和认证类型。
|
||||
- Renderer 只接收 `credentialConfigured`、来源和错误状态。
|
||||
- Host Key 检查使用 Main 内五分钟有效、目标绑定的临时候选，检查阶段不接收认证凭据；
|
||||
认证和系统探针成功前不持久化新增主机，取消或失败不留下主机或密码。
|
||||
- 首次连接必须在发送密码、私钥签名或 SSH Agent 签名前取得并展示 Host Key 算法和
|
||||
SHA-256 指纹，由用户显式接受；持久化完整 Host Key 或可信 Host CA，不能只保存展示指纹。
|
||||
- Host Key 变化硬失败，并通过独立高风险流程替换。
|
||||
- 禁止 `StrictHostKeyChecking=no` 和默认 SSH Agent Forwarding。
|
||||
- 命令参数、URL、日志、SQLite 明文和 IPC 响应中不得出现私钥或密码；用户在受信任表单
|
||||
输入的密码只通过严格校验的单用途 IPC 请求交给 Main，Renderer 不得读取已保存密码。
|
||||
|
||||
### 9.3 远程 GoodBuddy Agent
|
||||
|
||||
远程能力通过版本化 GoodBuddy Agent 提供：
|
||||
|
||||
- 安装到远程当前用户的 GoodBuddy-owned 目录，不要求 root。首次连接先 attach，Agent
|
||||
不存在或未运行时幂等 bootstrap 为 detached process，再重新 attach；不注册开机服务，
|
||||
不依赖 systemd、D-Bus 或 `Linger=yes`。
|
||||
- SSH 负责 Host Key、认证、固定 bootstrap、可选 SFTP 安装和 `goodbuddy-agent attach`
|
||||
中继；attach 只连接用户私有 Unix socket。SSH relay 断开不终止 Agent 或活动 Runtime。
|
||||
- Host 环境准备可让远端按签名目录固定的 GitHub/北京镜像 URL、大小和 SHA-256 下载完整
|
||||
`.gbagent`，也可由 GoodBuddy 下载、完整验证后通过有界流式 SFTP 传输一个 compound
|
||||
archive 和归档中已验证的 bootstrap Node；完整包不一次读入 Main `Buffer`，Host 仍再次
|
||||
校验。两种 acquisition 交付到固定 operation staging 后共用
|
||||
`prepare → commit → Agent activate/health → Runtime activate → finalize → cleanup`。
|
||||
- 直连首次 bootstrap 不依赖已安装 Agent daemon。GoodBuddy 桌面控制面通过固定 SSH
|
||||
prepare channel 发送有界 one-shot installer；Host 先验证目录绑定的归档大小和 SHA-256，
|
||||
再由 format v1 归档内固定 Node 解码并运行 installer。归档无需包含
|
||||
`agent/lib/package-installer.cjs`，目录不提供或检查额外的 bootstrap 能力元数据。
|
||||
- Agent 与 Runtime 各自维护版本，签名摘要标识精确工件。Host 在解包到准备目录的同一遍
|
||||
处理中完成完整 payload 校验，commit 只复核签名 metadata 并原子替换 side-by-side
|
||||
目录，不重新读取归档、扫描旧目录或使用跨安装硬链接。
|
||||
- Main 只保存清理 operation staging 所需的 operation ID。控制通道中断或 adoption 失败
|
||||
后，下次更新尽力清理旧暂存并重新 prepare，不保存或恢复 Agent/Runtime metadata 副本。
|
||||
新 Agent/Runtime 各自最多完整验证一次；注册后的
|
||||
health、capabilities 和 prompt 启动只检查 registry、签名 manifest 与入口 metadata。
|
||||
确认 adoption 后显式 cleanup，cleanup 失败不回滚健康环境，也不阻塞下一次 fresh prepare。
|
||||
- 握手报告 installation、Daemon boot identity、协议、系统、架构、用户监督器和能力。
|
||||
- 在远程执行路径规范化、Git、文件、PTY、进程组和 Runtime 管理。
|
||||
- 持久化有界 Agent 到 Main 输出；SSH 断开后 Agent 继续运行，同一 Agent 重连时只恢复
|
||||
可确认的输出。Main 到 Runtime 的输入、工具、模型和 blob 请求不自动重放。
|
||||
- 对有副作用的请求使用稳定 operation ID 和 payload digest 去重；结果无法证明时进入
|
||||
`outcome-unknown`，禁止自动重放。
|
||||
- 对事件、日志、journal、文件、帧、超时、并发、缓存和总传输量设置硬上限。
|
||||
- Daemon、Runtime、受管进程和用户终端分别具有明确 lease、取消、drain 和回收语义。
|
||||
- Agent 不可用或身份不匹配时远程执行失败，不退化为 SSH stdio Runtime。
|
||||
|
||||
Host Key、远端用户或目标变化会关闭旧连接，并使绑定旧 Host identity 的 Workspace 和
|
||||
Runtime 会话失效。产品不维护 T1/T2/T3 等附加信任层级。
|
||||
|
||||
### 9.4 远程 Runtime
|
||||
|
||||
- Runtime 在远程执行空间内运行，不能让本机 Runtime 对远程路径进行伪本地操作。
|
||||
- Main 保持可信控制面，远程 GoodBuddy Agent 只接受有范围、有期限的请求。
|
||||
- GoodBuddy 控制协议负责 Agent、Workspace、Git、Process、Blob 和 Runtime supervision；
|
||||
Runtime Session、stream、tool、permission、usage 和取消优先复用 ACP。
|
||||
- Ask 的只读限制在远程 GoodBuddy Agent 和 Runtime 适配层共同强制。
|
||||
- Execute 是用户对所选 SSH 账号完整权限的授权，直接以该账号可用的文件、进程、网络和
|
||||
工具能力运行，不要求逐工具审批或第二个“受控执行”模式。取消、超时、输出上限和活动
|
||||
记录继续保留。
|
||||
- GoodBuddy 模型凭据和 Provider URL 必须留在 Main。远程 Runtime 只获得不含凭据的模型
|
||||
policy、私有 Unix socket、隔离 loopback endpoint 和 Prompt-bound blob channel；
|
||||
Main 按 durable round、profile digest、调用次数、最坏输出 token 预留和最终 delivery ACK
|
||||
代发，不得把原始 API Key 或认证头发送到远端。
|
||||
- 不向远程 Runtime 暴露通用本机 MCP、浏览器、文件系统或其他未分配能力。
|
||||
|
||||
## 10. Runtime 与进程统一生命周期
|
||||
|
||||
需要新增统一、受限的生命周期模型：
|
||||
|
||||
```ts
|
||||
type ManagedLifecycleState =
|
||||
| 'starting'
|
||||
| 'running'
|
||||
| 'waiting_approval'
|
||||
| 'paused'
|
||||
| 'reconciling'
|
||||
| 'stopping'
|
||||
| 'completed'
|
||||
| 'failed'
|
||||
| 'cancelled'
|
||||
| 'interrupted'
|
||||
| 'outcome_unknown'
|
||||
```
|
||||
|
||||
每个 Runtime 会话、Task 级执行、终端或受管进程公开：
|
||||
|
||||
- GoodBuddy 受管 ID。
|
||||
- 类型、来源和父子关系。
|
||||
- 执行空间和范围。
|
||||
- 状态、开始与结束时间。
|
||||
- 支持的控制动作。
|
||||
- 有界进度、用量和日志游标。
|
||||
|
||||
控制动作按能力声明：
|
||||
|
||||
```ts
|
||||
type ManagedControl =
|
||||
| 'cancel'
|
||||
| 'terminate'
|
||||
| 'force-terminate'
|
||||
| 'pause'
|
||||
| 'resume'
|
||||
| 'reconnect'
|
||||
| 'release'
|
||||
```
|
||||
|
||||
界面不能因为状态枚举中存在某个动作就假设所有 Runtime 都支持。Main 根据当前受管对象和
|
||||
能力重新验证动作。内部 Job/Run 快照可以支持聚合与审计，但不能成为
|
||||
`WorkbarTargetRef` 或独立 UI 对象。
|
||||
|
||||
## 11. 数据与契约建议
|
||||
|
||||
### 11.1 共享 Zod 契约
|
||||
|
||||
建议新增：
|
||||
|
||||
- `workbar-contracts.ts`
|
||||
- `managed-process-contracts.ts`
|
||||
- `terminal-contracts.ts`
|
||||
- `remote-host-contracts.ts`
|
||||
- 通用 Artifact Event 和 Preview 契约
|
||||
- Runtime Inspector Snapshot 和 Control 契约
|
||||
|
||||
所有输入严格限制字符串、数组、日志、帧、路径、端口和事件数量。公开快照不得包含：
|
||||
|
||||
- 凭据和认证头。
|
||||
- 完整环境变量。
|
||||
- 任意本机或远程绝对路径，除非该路径本身是用户当前可见对象。
|
||||
- 未经限制的 stdout/stderr、文件或 Runtime 响应。
|
||||
- 可直接传给系统 kill、spawn、Shell 或 SSH 的自由参数。
|
||||
|
||||
### 11.2 持久化
|
||||
|
||||
建议增加：
|
||||
|
||||
```text
|
||||
workbar_preferences
|
||||
remote_hosts
|
||||
terminal_sessions
|
||||
managed_processes
|
||||
runtime_sessions
|
||||
runtime_jobs
|
||||
remote_agent_installations
|
||||
remote_operations
|
||||
```
|
||||
|
||||
其中：
|
||||
|
||||
- 工作栏偏好只保存能力目录顺序、面板实例、停靠布局、尺寸和目标引用。
|
||||
- 主机表只保存非敏感元数据和加密凭据引用。
|
||||
- 应用重启后先通过远程 Daemon 的 journal、lease、boot identity 和 event cursor 核对活动
|
||||
终端、进程与 Runtime；无法确认时标记 `interrupted` 或 `outcome_unknown`。
|
||||
- 日志使用有界环形缓冲或分页持久化，不能无限写入 SQLite。
|
||||
- Artifact 继续作为成果的权威实体，不把完整成果复制进工作栏状态。
|
||||
- 当前 Renderer `localStorage` 活动记录不能作为 Runtime、监督或进程的权威来源。
|
||||
|
||||
### 11.3 IPC 与 Preload
|
||||
|
||||
Renderer 只通过显式方法访问：
|
||||
|
||||
- 工作栏偏好和目标绑定。
|
||||
- 主机 CRUD、临时 Host Key 检查、验证并原子保存。
|
||||
- 终端创建、输入、调整大小、关闭和有界输出订阅。
|
||||
- 受管进程列表、日志和允许的控制动作。
|
||||
- Runtime Inspector 快照、事件和允许的控制动作。
|
||||
- 工作区、成果、浏览器和监督的既有或扩展服务。
|
||||
|
||||
每个 Main Handler 都必须验证可信发送者、Zod 输入、对象归属和当前状态。不得暴露 raw
|
||||
Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
|
||||
|
||||
## 12. 安全边界
|
||||
|
||||
1. 工作栏能力目录项和面板实例不授予任何能力；权限只由 Main 中的范围和控制契约产生。
|
||||
2. Ask 在本机和远程 Runtime 边界保持只读。
|
||||
3. Execute 继续经过现有 Runtime 和审批控制，工作栏不能直接放宽。
|
||||
4. 用户终端和 Agent 工具执行使用不同身份和事件来源。
|
||||
5. 进程面板只控制 GoodBuddy 受管对象，不接受任意 PID。
|
||||
6. 本机和远程路径分别在对应文件系统上 canonicalize 并验证符号链接边界。
|
||||
7. HTML 默认静态、无脚本、无网络、无 Electron API。
|
||||
8. Supervisor 不接收授权回调，不能批准工具或替用户发送消息。
|
||||
9. SSH Host Key 必须固定，凭据保留在 Main 加密存储。
|
||||
10. 远程端只获得请求级、可撤销、最小范围能力。
|
||||
11. 关闭面板或切换目标、主机或 Runtime 时，旧订阅必须取消；其他固定实例的订阅明确保留。
|
||||
12. 通知、徽标和日志不得包含密钥、私人正文或未脱敏提供商响应。
|
||||
|
||||
## 13. 状态、错误和恢复
|
||||
|
||||
每个面板实例区分：
|
||||
|
||||
- 尚未选择目标。
|
||||
- 目标为空。
|
||||
- 正在连接或加载。
|
||||
- 正常可用。
|
||||
- 部分可用。
|
||||
- 当前能力不支持。
|
||||
- 连接失败。
|
||||
- 权限不足或只读。
|
||||
- 目标已失效。
|
||||
- 操作已取消或中断。
|
||||
|
||||
错误必须保留用户选择、终端缓冲、输入草稿、范围和可重试上下文。短期成功和非局部错误使用
|
||||
应用通知；预览失败、终端断线、Host Key 变化、监督证据失效等需要本地恢复的错误留在面板
|
||||
内。同一事件不得同时重复显示为面板警告和应用通知。
|
||||
|
||||
## 14. 性能与资源边界
|
||||
|
||||
- 工作栏关闭或面板实例关闭时停止对应非必要画面和高频日志推送，但保留 Main 中的受管运行。
|
||||
- 每个打开的面板实例只订阅其跟随或固定目标，不进行全局无界监听。
|
||||
- 终端和日志使用增量序号、环形缓冲和背压。
|
||||
- HTML、文件、目录、浏览器画面和远程传输沿用或收紧现有大小限制。
|
||||
- Runtime Snapshot 与事件流分离，重新打开时先取权威快照，再接增量事件。
|
||||
- 监督使用独立低优先级并发池和预算，不延迟前台回答。
|
||||
- 应用退出时停止新操作并让用户选择取消、等待或 detach；关闭 SSH attach 不卸载或终止
|
||||
用户级 GoodBuddy Agent Daemon。依赖 Main 模型网关、审批或本机工具的 Run 不能被描述为
|
||||
可以无人值守继续。
|
||||
|
||||
## 15. 无障碍与响应式
|
||||
|
||||
- 能力目录、所有面板实例、目标选择器、终端控制和进程操作可用键盘完成。
|
||||
- 能力目录与面板标题具有稳定可访问名称，徽标不是唯一状态信号。
|
||||
- 终端需要独立可访问说明，并允许关闭动画和声音提示。
|
||||
- 进程和 Runtime 高频日志不逐行进入实时区域，只播报重要状态变化。
|
||||
- 监督证据定位后将焦点移动到对应对象，并提供返回监督记录的方式。
|
||||
- HTML iframe 有明确标题、静态安全说明和源码替代视图。
|
||||
- 窄窗口下能力目录仍完整可达，不因空间不足隐藏能力。
|
||||
- 文字缩放到 200% 时，当前目标、执行空间、风险状态和停止操作不能被裁切。
|
||||
|
||||
## 16. 分阶段实施
|
||||
|
||||
本节只表示内部依赖顺序，不表示可以发布临时架构。SSH 远程执行只使用用户级 Daemon，
|
||||
不发布连接期 stdio Agent。OpenCode Ask、OpenCode Execute 和后续 Runtime 分别通过自身的
|
||||
安装、权限、取消和重连门槛后开放，未完成的能力继续显示不可用。
|
||||
|
||||
### 阶段 0：应用级工作栏壳层
|
||||
|
||||
- 将当前聊天专属右栏提升为应用级壳层。
|
||||
- 建立稳定能力目录和用户打开、关闭、排序、停靠的面板实例模型。
|
||||
- 建立实例级跟随、固定和失效目标语义。
|
||||
- 保留现有任务中心、工作区、浏览器和成果行为；附件与知识库继续由 Composer 管理。
|
||||
- 将 Task Center 明确为 Task 的单例索引，并补齐范围、状态、最近进展、需要关注和直接打开 Conversation。
|
||||
- 审批在所属任务或 Runtime 中持续可见，不新增独立审批面板。
|
||||
- 智能心跳菜单入口承接完整配置和范围后，再从任务中心移除重复表单；不得移除任务中心本身。
|
||||
|
||||
### 阶段 1：成果与 Runtime 可观测性
|
||||
|
||||
- 通用 Artifact Event。
|
||||
- HTML 工作区和成果的静态即时预览。
|
||||
- Runtime Inspector Snapshot 与事件。
|
||||
- OpenCode 会话、子会话、Todo、工具、用量和取消；本地与托管 SSH 的原生 Task 调用在
|
||||
Conversation 中统一显示为可追踪的 Subagent 状态，而不是普通工具参数卡。
|
||||
- 直连模型、OpenCode 原生 Subagent 及现有 GoodBuddy Subagent 的统一展示。
|
||||
|
||||
### 阶段 2：监督、终端与受管进程
|
||||
|
||||
- 普通会话手动监督和右栏评论流。
|
||||
- 工作栏持久“+”、应用注册表和单/多实例 Tab。
|
||||
- 本机 PTY 与直接 SSH PTY 多终端。
|
||||
- 受管进程注册、日志和终止。
|
||||
- 自动回复后监督、节流和独立预算。
|
||||
- 用户选择终端停靠位置。
|
||||
|
||||
### 阶段 3：Runtime 原生长期能力
|
||||
|
||||
- Continue 会话级 Host。
|
||||
- Continue Background Job、Subagent 和 Hook 的有界适配。
|
||||
- DeepSeek Harness 后续服务的能力握手。
|
||||
- Runtime Job、Workflow 和会话恢复契约。
|
||||
|
||||
### 阶段 4：SSH 主机与远程执行空间
|
||||
|
||||
- [x] 引导式主机管理、先验证后保存、密码安全存储、系统 SSH Agent、Host Key 固定和
|
||||
有界系统探针。
|
||||
- [ ] 私钥与受限 OpenSSH config 导入。
|
||||
- 签名、side-by-side GoodBuddy Agent 安装和按需 detached Daemon。
|
||||
- SSH connection pool、固定 attach relay、Agent 控制协议、Agent 本地 ACP 日志和断线重连同步。
|
||||
- 远程工作区、Git、终端和受管进程。
|
||||
- 先完成签名 OpenCode bundle、Ask bubblewrap、Execute 直接进程、官方 ACP channel、
|
||||
Main 模型网关、取消、超时和活动记录。
|
||||
- OpenCode 闭环稳定后，Continue 与 DeepSeek Harness 复用相同面板和通道契约逐个接入。
|
||||
- 新增或重新验证 Host 时只保存并探测 Agent/Runtime，不自动安装。用户在 Host 卡片用
|
||||
单一主按钮启动，并用次级控件选择自动、Host 下载或 GoodBuddy 传输；Host 保存与环境
|
||||
准备是两个可独立重试的事务。
|
||||
- 控制面直连源码直接使用既有 package format v1 包；不等待发布携带 installer 的新
|
||||
Agent 包，也不通过额外目录元数据判断 bootstrap 能力。GitHub/北京镜像、
|
||||
Linux x64/arm64、取消和离线 GoodBuddy 传输仍须真实 Host 验收，不能据此声称已发布或已完成
|
||||
真实 Host 测试。
|
||||
- 一次远程项目保存请求完成 Host/Agent/Workspace/Runtime 当前环境验证和 SQLite 原子
|
||||
提交，但只持久化 Host、路径、Runtime 选择和模式，也不获取或安装组件。
|
||||
- 桌面更新后，用户先在 Host 管理中更新当前签名 Agent/Runtime；远程项目下一次实际使用
|
||||
Workspace/Runtime 时直接使用新的 current 环境，无需刷新项目绑定。应用启动和项目切换
|
||||
本身都不连接 Host，也不下载或安装组件。
|
||||
- SSH、Main、Daemon、Runtime 和远端重启后的核对、恢复与 `outcome_unknown`。
|
||||
- 支持平台的安装、Ask、Execute、取消和重连冒烟测试通过后开放对应 OpenCode 能力。
|
||||
|
||||
### 阶段 5：开放后的扩展
|
||||
|
||||
- 更多远程系统和架构。
|
||||
- PDF、Office 和数据成果预览。
|
||||
- Conversation、Task 和实验的完整监督。
|
||||
- 用户可导入导出工作栏布局和主机非敏感配置。
|
||||
|
||||
## 17. 验收标准
|
||||
|
||||
### 17.1 稳定能力目录与用户控制
|
||||
|
||||
- [ ] 八个标准能力在所有主要页面的目录中始终可发现，但不会默认同时打开。
|
||||
- [ ] Task Center 继续作为 Task 的单例索引，不删除入口、不复制会话，也不混入 Job、Run 或心跳事项。
|
||||
- [ ] 项目、会话、Runtime 或主机变化不会无提示地增删能力目录项。
|
||||
- [ ] 用户可以按需打开、关闭、排序和停靠面板实例。
|
||||
- [ ] 用户可以独立设置每个可绑定目标的面板实例跟随或固定目标，并为同一能力打开多个目标实例。
|
||||
- [ ] 固定目标失效后显示修复状态，不静默切换。
|
||||
- [ ] 后台事件不会无条件打开面板或抢占用户当前实例。
|
||||
- [ ] 用户可一键恢复标准能力目录和默认的少量打开面板。
|
||||
|
||||
### 17.2 通用使用
|
||||
|
||||
- [ ] 没有项目时仍可创建终端、选择工作区、打开浏览器和查看成果。
|
||||
- [ ] 监督可以作用于普通 Conversation、Task 和后续实验对象，不假设编程语境。
|
||||
- [ ] 工作区不是 Git 仓库时仍可浏览文件。
|
||||
- [ ] Runtime 不支持某项原生能力时仍可从目录打开面板并获得准确说明。
|
||||
|
||||
### 17.3 安全与控制
|
||||
|
||||
- [ ] Renderer 没有任意文件、Shell、进程、PTY、SSH 或 Electron API。
|
||||
- [ ] Agent 不能未经授权向用户终端注入命令。
|
||||
- [ ] 进程面板不能枚举或终止任意系统进程。
|
||||
- [ ] Ask 在本机和远程执行空间均无法调用写入或外部副作用工具。
|
||||
- [ ] HTML 预览无法执行脚本、联网、打开窗口、提交表单或访问 Electron API。
|
||||
- [ ] Supervisor 不能自动发送消息、批准工具、切换工作模式或扩大范围。
|
||||
- [ ] SSH 首次连接和 Host Key 变化均经过明确验证流程。
|
||||
- [ ] 凭据不进入 Renderer、日志、SQLite 明文或命令参数。
|
||||
- [ ] Host 地址、用户或 Host Key 变化会关闭旧连接，并使旧 Workspace 和 Runtime 会话失效。
|
||||
|
||||
### 17.4 生命周期与恢复
|
||||
|
||||
- [ ] Runtime、终端、Task 级执行和进程具有权威 Main 快照和有序增量事件。
|
||||
- [ ] 取消、终止、失败、断线和应用退出都有确定终态。
|
||||
- [ ] 远程执行只通过按需 detached Daemon 提供，SSH attach 断开不销毁 Daemon 状态。
|
||||
- [ ] 重连先恢复 event cursor 并查询 operation；有副作用操作不会自动重放，无法确认的
|
||||
结果显示为 `outcome_unknown`。
|
||||
- [ ] Agent side-by-side 更新支持所需签名版本的健康切换，失败时保留旧项目绑定。
|
||||
- [x] 新增 Host 只探测远端下载能力，不提供自动安装开关，也不传输完整包；Host 卡片用
|
||||
一个按版本事实命名的主按钮与不持久化的 acquisition SegmentedControl 启动准备。
|
||||
- [x] 创建、保存、打开和切换托管 SSH 项目都从 Host current registry 与当前 Agent
|
||||
连接验证环境；项目只保存稳定配置，且这些流程不下载 `.gbagent`、上传 payload 或发布
|
||||
安装。
|
||||
- [ ] 切换跟随目标后不显示上一对象的过期状态。
|
||||
- [ ] 固定目标的订阅在页面切换后保持，关闭时正确释放。
|
||||
- [ ] 日志、终端、文件、成果和远程传输均有明确上限和背压。
|
||||
|
||||
### 17.5 可用性
|
||||
|
||||
- [ ] 宽、中、窄窗口均可访问完整能力目录和用户打开的面板实例。
|
||||
- [ ] 工作栏在宽、中、窄窗口展开时都推动主工作区回流，不覆盖、遮罩或隔离主内容；唯一
|
||||
开关始终固定在窗口关闭按钮正下方。
|
||||
- [ ] 仅使用键盘可以选择能力、面板实例、目标、执行空间和控制动作。
|
||||
- [ ] 状态不只依赖颜色，徽标具有文字或可访问名称。
|
||||
- [ ] 终端、HTML、监督证据和高频日志具有可访问替代或降噪行为。
|
||||
- [ ] 浏览器 Tab 顶部工具栏始终清楚区分“停止加载”和“关闭浏览器”；地址编辑草稿不会被
|
||||
权威状态刷新覆盖，用户与 Agent 的导航通过同一 `BrowserService` 会话串行执行。
|
||||
- [ ] 创建中、Agent 操作中和完整交互期间禁用浏览器其余工具栏控件；活动加载仍可单独停止，
|
||||
且停止加载不会关闭会话或释放 Runtime 上下文。
|
||||
- [ ] 活动 Conversation 没有浏览器会话时，可从同一地址栏按 Agent 相同 URL 策略启动会话。
|
||||
|
||||
## 18. 相关文档的职责
|
||||
|
||||
- 本文是助手工作栏稳定能力目录、用户面板实例、范围控制和执行空间的产品总契约。
|
||||
- [助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) 定义持久“+”、应用实例策略、
|
||||
动态 Tab 以及本机与直接 SSH 多终端。
|
||||
- [Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) 定义 Task、Conversation、
|
||||
Job、Subjob、Run 与 Subagent。
|
||||
- [Task Center PRD](../task-and-job/task-center-prd.md) 定义应用级 Task 索引。
|
||||
- [智能心跳 PRD](../smart-heartbeat/prd.md) 定义心跳入口、范围和长期边界。
|
||||
- [会话监督 PRD](../conversation-supervision/prd.md) 定义监督判断、证据、预算和介入边界。
|
||||
- [自动化平台总体设计](../../architecture/automation-platform-architecture.md) 定义 Plan、Job、Run、监督、预算和记忆。
|
||||
- [长期助手路线图](../../roadmap/long-term-assistant-roadmap.md) 记录整体长期能力与实施背景。
|
||||
- [DeepSeek Harness Runtime 设计](../deepseek-harness/technical-design.md) 定义该 Runtime 的具体适配边界。
|
||||
- [SSH Host 远程环境准备与直连下载设计](../remote-host/environment-provisioning-technical-design.md)
|
||||
定义 Host 级组件获取、首次准备、更新、回退和项目只验证边界。
|
||||
- [统一界面设计系统](../../../UI-DESIGN.md) 定义视觉、语义、响应式和无障碍规则。
|
||||
|
||||
若其他文档把工作栏描述为八个同时固定显示的栏目、根据项目或 Runtime 自动裁剪的动态入口，
|
||||
或仅属于当前聊天的附属区域，以本文“能力目录稳定、面板实例由用户打开、当前上下文只提供
|
||||
默认值”的产品决策为准。
|
||||
@@ -0,0 +1,582 @@
|
||||
# 助手工作栏多终端页签 PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 已实施，跨平台验证中 |
|
||||
| 版本 | 1.1 |
|
||||
| 日期 | 2026-08-31 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 界面归属 | [通用助手工作栏与执行空间](./prd.md) |
|
||||
| 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md) |
|
||||
| 远程架构 | [SSH 远程主机与 GoodBuddy Agent 实现说明](../remote-host/technical-design.md)、[SSH Host 远程环境准备与控制面直连设计](../remote-host/environment-provisioning-technical-design.md) |
|
||||
|
||||
## 1. 文档职责
|
||||
|
||||
本文细化助手工作栏中的以下行为：
|
||||
|
||||
- 已打开应用以同级 Tab 呈现。
|
||||
- Tab 行始终提供“+”入口，用户按需打开应用。
|
||||
- 应用通过统一注册表声明单实例或多实例策略。
|
||||
- “终端”作为首个多实例应用，自动使用当前项目的本机或托管 SSH 执行空间。
|
||||
- 本机与远程交互式终端的生命周期、状态、性能和验收要求。
|
||||
|
||||
[通用助手工作栏与执行空间 PRD](./prd.md)
|
||||
继续负责工作栏的应用级位置、稳定能力目录、执行空间、范围绑定和总体产品边界。本文不重新
|
||||
定义 Host Key、凭据、Agent 安装、Ask/Execute Runtime 或项目持久化契约。
|
||||
|
||||
## 2. 背景与当前问题
|
||||
|
||||
当前工作栏在聊天页面右侧固定显示“任务中心、工作区、浏览器、成果”四个 Tab。用户不能：
|
||||
|
||||
- 通过统一入口按需打开新的工作栏应用。
|
||||
- 关闭并重新打开一个工作栏应用。
|
||||
- 为支持多实例的应用创建第二个独立实例。
|
||||
- 在 GoodBuddy 内使用本机或远程 Host 的交互式 Shell。
|
||||
|
||||
当前代码已经具备工作栏右侧回流、宽度调整、Tab 键盘导航、SSH Host Key 固定、加密凭据和
|
||||
SSH 连接池，但尚不存在工作栏应用实例模型、终端 IPC、终端 Session Manager 或终端模拟器。
|
||||
`node-pty` 当前只作为其他 Runtime 的间接依赖被打包，不能视为已经存在用户终端能力。
|
||||
|
||||
## 3. 产品定义
|
||||
|
||||
### 3.1 工作栏应用
|
||||
|
||||
工作栏应用是可以在助手工作栏中打开的一个能力，例如任务中心、工作区、浏览器、成果或
|
||||
终端。每项应用通过统一注册表声明：
|
||||
|
||||
- 稳定应用 ID。
|
||||
- 用户可见名称、图标和说明。
|
||||
- `single` 或 `multiple` 实例策略。
|
||||
- 创建实例时可用的默认上下文。
|
||||
- 当前不可用时的原因和修复入口。
|
||||
|
||||
目录中的应用可发现性与实例是否已经打开相互独立。应用不可用时保留入口并说明原因，不以
|
||||
隐藏代替状态。
|
||||
|
||||
### 3.2 工作栏 Tab 实例
|
||||
|
||||
工作栏 Tab 是应用的一次打开实例。每个实例具有独立 ID、标题、应用类型和状态。Tab 行只
|
||||
显示已经打开的实例，不把全部能力同时渲染为 Tab。
|
||||
|
||||
### 3.3 终端实例
|
||||
|
||||
每个终端 Tab 对应一个独立交互式 Shell Session：
|
||||
|
||||
- 本机终端由桌面 Main 进程管理本机 PTY。
|
||||
- 远程终端通过现有、已验证的 SSH Host 打开直接 SSH PTY。
|
||||
- 不同终端拥有独立 Shell、工作目录、输入、输出、尺寸和结束状态。
|
||||
- 创建后固定到当时选择的执行位置，切换项目不会迁移已经运行的终端。
|
||||
|
||||
直接 SSH PTY 是用户操作的远程终端，不是连接期临时 GoodBuddy Agent，也不作为 Runtime
|
||||
stdio fallback。首期远程终端随 SSH Channel 结束，不提供跨 SSH 或桌面重启的进程恢复。
|
||||
|
||||
## 4. 已确认的产品决策
|
||||
|
||||
1. 工作栏 Tab 行末尾始终显示“+”按钮。
|
||||
2. “+”是普通命令按钮，不是一个 `tab`。
|
||||
3. 点击“+”在工作栏内容区显示“新建工作栏应用”选择页；取消后返回原活动 Tab。
|
||||
4. 选择应用后创建或激活实例，并关闭临时选择页。
|
||||
5. 单实例应用已经打开时，再次选择只聚焦已有实例，不创建重复 Tab。
|
||||
6. 多实例应用每次选择都创建新实例。
|
||||
7. 终端从首期开始就是多实例应用。
|
||||
8. 任务中心、工作区、浏览器和成果首期保持单实例；后续只需修改应用注册表策略即可开放
|
||||
多实例，不重写 Tab 壳层。
|
||||
9. 现有四个应用在升级后仍按当前默认布局打开，避免用户入口突然消失。
|
||||
10. 用户关闭、切换或重排应用 Tab 后，“+”仍保持可见。
|
||||
11. 选择“终端”后不再显示第二层目标选择器。存在当前项目时直接绑定该项目，由 Main
|
||||
根据项目执行空间自动打开本机或托管 SSH Shell；没有当前项目时打开本机 Home Shell。
|
||||
12. 远程首期使用直接 SSH PTY。SSH 断线后终端进入“已中断”，重新连接会创建一个新的
|
||||
Shell，不伪装为恢复旧进程。
|
||||
13. 工作栏收起、切换主页面或切换 Tab 不终止终端；显式关闭终端 Tab 才终止对应 Shell。
|
||||
14. 应用重启不自动启动 Shell。恢复的终端 Tab 显示“会话已结束”，由用户显式重新连接。
|
||||
15. 终端是用户交互表面。Ask/Execute 继续约束 Agent Runtime，不把用户键盘操作误判为
|
||||
Agent 工具调用；Agent、自动化和模型不得未经明确用户操作向终端注入输入。
|
||||
16. 工作栏继续按上位 PRD 提升为应用级容器；切换聊天、知识、魔法笔记或活动记录等主页面
|
||||
不销毁 Tab 实例或终端 Session。
|
||||
|
||||
## 5. 目标
|
||||
|
||||
### 5.1 用户目标
|
||||
|
||||
- 在工作栏中随时通过“+”发现并打开应用。
|
||||
- 同时打开多个本机或远程终端，并通过 Tab 快速切换。
|
||||
- 清楚知道每个终端运行在本机还是哪个远程 Host、当前目录和连接状态。
|
||||
- 在终端断线、退出或目标失效后获得准确状态和明确恢复操作。
|
||||
- 使用键盘完成打开应用、切换 Tab、操作终端和关闭实例。
|
||||
|
||||
### 5.2 产品目标
|
||||
|
||||
- 用一个可扩展的应用注册表统一单实例与多实例行为。
|
||||
- 把现有固定四 Tab 迁移为用户实例，而不回归现有任务中心、工作区、浏览器和成果能力。
|
||||
- 建立真实的 Main/Preload/Renderer 终端生产链路，而不是用普通文本框模拟终端。
|
||||
- 复用现有 SSH Host Key、凭据和连接池，不建立第二套 Host 管理。
|
||||
- 保持终端输入输出有序、响应流畅、内存有界，并可靠清理本机和远程资源。
|
||||
|
||||
## 6. 非目标
|
||||
|
||||
- 不把 GoodBuddy 改造成完整 IDE。
|
||||
- 不唤起 Windows Terminal、Terminal.app 等外部终端窗口代替内嵌终端。
|
||||
- 不扫描或导入用户全部 SSH config、目录、Shell profile 或命令历史。
|
||||
- 不支持任意 `ProxyCommand`、端口转发或 SSH Agent Forwarding。
|
||||
- 不在打开远程终端时安装、更新或修复 GoodBuddy Agent。
|
||||
- 不把 Agent 工具调用、Runtime 日志或自动化输出伪装成用户终端。
|
||||
- 不允许 Renderer 直接访问 PTY、ChildProcess、SSH Client、凭据或 Node API。
|
||||
- 首期不提供终端协作、录制、云同步、Shell Session 复用、tmux 管理或跨设备恢复。
|
||||
- 首期不实现底部停靠和独立窗口；本文保留兼容模型，后续按工作栏总 PRD 扩展。
|
||||
- 首期不通过 GoodBuddy Agent 恢复远程终端，也不为终端复制 Runtime transcript、
|
||||
`outcome_unknown` 或模型调用恢复协议。
|
||||
|
||||
## 7. 信息架构与“+”交互
|
||||
|
||||
### 7.1 Tab 行
|
||||
|
||||
```text
|
||||
┌──────────────────────────────────────────────┐
|
||||
│ 任务中心 │ 工作区 │ 终端 1 │ 终端 2 │ + │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ 当前活动实例内容 │
|
||||
└──────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- 已打开实例位于一个语义化 `tablist` 中。
|
||||
- 每个实例使用独立 `tab` 和 `tabpanel`。
|
||||
- “+”固定在 Tab 行末尾，但位于 `tablist` 之外。
|
||||
- Tab 过多时实例区域单行横向滚动，“+”保持可见；不换行、不自动隐藏实例。
|
||||
- 终端 Tab 默认使用递增标题，例如“终端 1”“终端 2”；状态栏持续显示项目、Host、
|
||||
工作目录和 Shell。用户可以重命名终端。
|
||||
- 当前 Tab 同时使用连续内容表面、选中边框、顶部强调线、图标和较高字重，不能只靠文字颜色。
|
||||
- Tab 关闭按钮默认不争夺视觉注意力，仅在鼠标悬停或键盘焦点进入对应 Tab 时出现；
|
||||
粗指针或无悬停设备始终显示，出现与隐藏不得引发布局位移。
|
||||
|
||||
### 7.2 新建应用选择页
|
||||
|
||||
点击“+”后：
|
||||
|
||||
1. 保留当前实例及其运行状态。
|
||||
2. 在工作栏内容区显示“新建工作栏应用”。
|
||||
3. 列出稳定应用目录，每项显示名称、说明、单/多实例提示和当前可用状态。
|
||||
4. 初始焦点进入第一个可用应用；Escape 或“取消”返回原活动实例和“+”按钮。
|
||||
5. 选择单实例应用时，若实例已存在，直接聚焦该 Tab。
|
||||
6. 选择终端时直接解析当前项目执行空间，创建新 Tab 并聚焦终端输入，不再要求用户
|
||||
重复选择本机或远程目标。
|
||||
|
||||
选择页是“+”触发的临时界面，不进入实例顺序，不持久化，也不占用一个普通 Tab。
|
||||
|
||||
### 7.3 首期应用注册表
|
||||
|
||||
| 应用 | 实例策略 | 升级后默认状态 | 再次从“+”选择 |
|
||||
| --- | --- | --- | --- |
|
||||
| 任务中心 | `single` | 打开 | 聚焦已有 Tab |
|
||||
| 工作区 | `single` | 打开 | 聚焦已有 Tab |
|
||||
| 浏览器 | `single` | 打开 | 聚焦已有 Tab |
|
||||
| 成果 | `single` | 打开 | 聚焦已有 Tab |
|
||||
| 终端 | `multiple` | 不打开 | 每次创建新 Tab |
|
||||
|
||||
实例策略是应用注册数据，不能分散硬编码在多个点击处理器中。
|
||||
|
||||
### 7.4 Tab 操作
|
||||
|
||||
- 点击或使用方向键切换实例不会暂停或终止后台实例。
|
||||
- 支持左右方向键、Home、End 和 roving `tabindex`。
|
||||
- 关闭非活动 Tab 后焦点保持在当前活动 Tab。
|
||||
- 关闭活动 Tab 后激活右侧相邻实例；没有右侧实例时激活左侧实例。
|
||||
- 关闭最后一个实例后显示明确空状态和“打开应用”，Tab 行仍保留“+”。
|
||||
- 关闭正在运行的终端需要确认“关闭终端将结束 Shell 及其子进程”；取消是初始焦点。
|
||||
- 已退出或已中断的终端可以直接关闭，不重复确认。
|
||||
|
||||
## 8. 终端创建流程
|
||||
|
||||
### 8.1 自动目标解析
|
||||
|
||||
- 当前项目是本地项目时，创建目标为公开 Project ID，Main 从权威项目记录解析本机根目录。
|
||||
- 当前项目是托管 SSH 项目时，创建目标仍为公开 Project ID，Main 再解析项目 Host、
|
||||
固定 Host Key、凭据和远端根目录。
|
||||
- 没有当前项目时使用本机目标和当前用户 Home。
|
||||
- Host 未验证、凭据不可用或不支持交互式 Shell 时，终端 Tab 就地显示失败原因和恢复入口，
|
||||
不静默切换到本机或其他 Host。
|
||||
|
||||
### 8.2 本机终端
|
||||
|
||||
- 当前项目是本地项目时，默认工作目录为项目根目录。
|
||||
- 没有本地项目目标时，默认工作目录为当前用户 Home。
|
||||
- Windows 优先使用可用的 PowerShell 7，其次 Windows PowerShell，最后使用系统
|
||||
`COMSPEC`。
|
||||
- macOS 和 Linux 优先使用当前用户有效的 `$SHELL`，不可用时使用平台常规 Shell fallback。
|
||||
- 首期自动选择默认 Shell，不提供任意可执行文件路径输入。
|
||||
- Main 只向 Shell 传递正常交互所需的筛选环境，不注入模型 API Key、GoodBuddy 内部
|
||||
Token 或其他产品凭据。
|
||||
|
||||
### 8.3 远程终端
|
||||
|
||||
- 当前项目是托管 SSH 项目时，自动使用项目 Host 和远端项目根目录。
|
||||
- Main 复用现有 Host store、完整 Host Key 固定、认证方式和 SSH connection pool。
|
||||
- 远端通过 SSH PTY 打开账号的登录 Shell，并支持输入、ANSI 输出和窗口尺寸同步。
|
||||
- 活动终端持有专用 Channel lease，不得被连接池空闲回收。
|
||||
- 不把密码、私钥、认证头或 GoodBuddy 模型凭据发送给 Renderer 或写入终端环境。
|
||||
- Host 地址、用户、凭据或 Host Key generation 变化时，旧 Session 进入“已中断”，新建
|
||||
Session 必须使用 Host store 中的当前身份。
|
||||
|
||||
### 8.4 创建结果
|
||||
|
||||
创建成功后：
|
||||
|
||||
- 新 Tab 插入当前活动 Tab 右侧并立即激活。
|
||||
- 焦点进入终端输入区域。
|
||||
- 状态栏显示“本机”或 Host 名称、工作目录、Shell 和连接状态。
|
||||
- 终端尺寸使用内容区计算出的首个有效 `cols/rows`，不是固定默认值覆盖实际布局。
|
||||
|
||||
创建失败时在终端 Tab 保留错误上下文并提供重试；不得留下不可回收 Session 或显示为已经连接。
|
||||
|
||||
## 9. 终端交互与状态
|
||||
|
||||
### 9.1 基础交互
|
||||
|
||||
首期支持：
|
||||
|
||||
- 真实 TTY 输入与 ANSI 输出。
|
||||
- 中文输入法、组合字符和常规键盘快捷键。
|
||||
- 复制、粘贴、全选、搜索、清屏和滚动。
|
||||
- 工作栏宽度或窗口尺寸变化后的 PTY resize。
|
||||
- 终端重命名。
|
||||
- 显式关闭、退出后重新打开和远程中断后重新连接。
|
||||
|
||||
浏览器原生页面快捷键与终端按键冲突时，终端聚焦期间优先交给终端；应用级保留快捷键必须
|
||||
有明确规则和可访问说明。
|
||||
|
||||
### 9.2 状态模型
|
||||
|
||||
```ts
|
||||
type TerminalSessionState =
|
||||
| 'starting'
|
||||
| 'running'
|
||||
| 'exited'
|
||||
| 'interrupted'
|
||||
| 'closing'
|
||||
| 'failed'
|
||||
```
|
||||
|
||||
- `starting`：正在创建本机 PTY 或 SSH Channel。
|
||||
- `running`：允许输入和 resize。
|
||||
- `exited`：Shell 正常或带退出码结束，显示退出码或信号。
|
||||
- `interrupted`：远程连接、Host identity 或桌面生命周期导致会话失效。
|
||||
- `closing`：已拒绝新输入，正在回收进程或 Channel。
|
||||
- `failed`：Session 未成功开始或发生不可恢复错误。
|
||||
|
||||
高频输出不逐行进入 live region。只播报连接成功、连接失败、已中断和 Shell 已退出等重要
|
||||
状态变化。
|
||||
|
||||
### 9.3 重新连接
|
||||
|
||||
- 本机或远程 Session 结束后，“重新打开”在同一 Tab 中创建全新的 Shell Session。
|
||||
- 远程断线后的按钮文案为“重新连接并新建 Shell”，不能暗示恢复旧进程。
|
||||
- 新 Session 使用 Host store 和项目中的当前有效配置，不复用旧 Host identity。
|
||||
- 重新连接前清空旧终端画面，并保留可见说明“这是新的 Shell 会话”。
|
||||
|
||||
## 10. 实例、Session 与持久化
|
||||
|
||||
工作栏实例与运行 Session 分离：
|
||||
|
||||
```ts
|
||||
type WorkbarAppDefinition = {
|
||||
id: 'tasks' | 'workspace' | 'browser' | 'results' | 'terminal'
|
||||
instancePolicy: 'single' | 'multiple'
|
||||
}
|
||||
|
||||
type WorkbarTabInstance = {
|
||||
id: string
|
||||
appId: WorkbarAppDefinition['id']
|
||||
title: string
|
||||
targetRef?: {
|
||||
type: 'project' | 'local'
|
||||
id?: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- 持久化工作栏打开状态、Tab 顺序、活动实例、应用 ID、自定义标题、公开目标引用和宽度比例。
|
||||
- 不持久化终端正文、未执行输入、凭据、环境变量、PTY PID、SSH Channel 或派生 Host
|
||||
identity。
|
||||
- Main 创建终端后返回新的不透明 Session ID；Renderer 不能选择 PID 或 Channel。
|
||||
- 应用重启恢复终端 Tab 描述，但状态为“会话已结束”，不自动建立 SSH 连接或启动本机
|
||||
Shell。
|
||||
- 运行期间切换项目不会改变已经创建的终端目标。用户需要新目标时通过“+”创建新终端。
|
||||
|
||||
## 11. 生命周期与关闭语义
|
||||
|
||||
| 用户或系统动作 | Tab | Shell Session |
|
||||
| --- | --- | --- |
|
||||
| 切换 Tab | 保留 | 继续运行 |
|
||||
| 收起工作栏 | 保留 | 继续运行，停止非必要高频 UI 工作 |
|
||||
| 切换主页面 | 保留 | 继续运行 |
|
||||
| 切换项目 | 保留并显示原目标 | 继续在原目标运行 |
|
||||
| 关闭运行中的终端 Tab 并确认 | 删除 | 结束 Shell 和子进程 |
|
||||
| Shell 自行退出 | 保留 | 标记 `exited` |
|
||||
| SSH 断线 | 保留 | 标记 `interrupted` |
|
||||
| 删除或修改目标 Host | 保留 | 关闭旧 Channel 并标记 `interrupted` |
|
||||
| Renderer 销毁或应用退出 | 下次恢复描述 | 在总关闭截止时间内回收 |
|
||||
|
||||
关闭操作必须安全处理竞态。Main 停止接受新输入，关闭 stdin/Channel，先正常结束，再在既有
|
||||
应用关闭截止时间内升级清理；一个卡死终端不能无限阻塞应用退出。关闭后的迟到 ACK 视为已
|
||||
完成，input、resize 或重复 close 返回 Session 不存在，不操作其他 Session。
|
||||
|
||||
## 12. 技术生产路径
|
||||
|
||||
### 12.1 Shared
|
||||
|
||||
新增独立终端契约，至少覆盖：
|
||||
|
||||
- `create`：目标引用、初始 `cols/rows`。
|
||||
- `write`：Session ID 和有界输入。
|
||||
- `resize`：Session ID、`cols/rows`。
|
||||
- `close`：Session ID。
|
||||
- `snapshot`：目标、状态、Shell、目录和终态。
|
||||
- `event`：带 Session ID 和单调序号的输出、状态、退出与错误事件。
|
||||
|
||||
所有 Schema 使用 Zod 严格校验，并限制 ID、标题、输入、尺寸、事件块、会话数和缓冲字节。
|
||||
|
||||
### 12.2 Main
|
||||
|
||||
新增统一 `TerminalSessionManager`：
|
||||
|
||||
- Session 按所属 `webContents` 和不透明 ID 隔离。
|
||||
- 将现有间接 `node-pty` 提升为 GoodBuddy 直接生产依赖，并用于启动平台 Shell。
|
||||
- 远程使用现有 `SshConnectionPool` 打开交互式 PTY Channel。
|
||||
- 统一处理 write、resize、close、exit、连接中断和应用退出。
|
||||
- 终端输出只发送给所属窗口。
|
||||
- 复用现有子进程树终止思路，但针对 PTY 验证 Windows 与 POSIX 的实际回收行为。
|
||||
|
||||
### 12.3 Preload 与 IPC
|
||||
|
||||
- `DesktopApi` 只暴露显式 `terminal.create/write/resize/close/getSnapshot/onEvent`。
|
||||
- Main Handler 对每个调用执行可信 sender 检查和共享 Schema parse。
|
||||
- Preload 管理事件订阅释放，不暴露 `ipcRenderer`、PTY、SSH Client 或 Node API。
|
||||
|
||||
### 12.4 Renderer
|
||||
|
||||
- 使用 `@xterm/xterm` 6 和官方 fit/search addon 处理 ANSI、光标、选择、IME、搜索、
|
||||
滚动和可访问输入，不自行实现终端转义状态机。
|
||||
- 终端首次打开时按需加载；支持 WebGL2 时使用官方 WebGL renderer，初始化失败或 Context
|
||||
丢失时释放 WebGL addon 并回退到 xterm 默认 renderer。
|
||||
- xterm 使用解析后的跨平台系统等宽字体栈，不能把未解析的 CSS `var(...)` 交给 Canvas。
|
||||
- Tab 壳层只管理实例与焦点，不持有 PTY 或 SSH 对象。
|
||||
- `ResizeObserver` 只在有效非零布局后发送去重后的 `cols/rows`。
|
||||
- 组件卸载时退订画面事件；只有显式关闭终端才调用 Session close。
|
||||
- 终端样式复用全局语义颜色、边框、焦点和字体令牌，不创建另一套工作台设计系统。
|
||||
|
||||
### 12.5 输出顺序与背压
|
||||
|
||||
- 输出按 Session 分区并携带单调序号。
|
||||
- Main 合并小块输出，限制单事件大小、待发送条目和总字节。
|
||||
- Renderer 确认已经消费的序号；慢消费者达到上限时暂停 PTY/SSH stream，消费后恢复。
|
||||
- 不通过丢弃中间输出维持界面响应，因为丢失字节会破坏终端状态。
|
||||
- Renderer 只保留有界滚动历史；清屏不改变 Main Session 生命周期。
|
||||
|
||||
## 13. 权限与边界
|
||||
|
||||
- 用户终端以当前本机账号或所选 SSH 账号的正常权限运行，不增加额外虚构的 trust tier。
|
||||
- Ask/Execute 是 Agent Runtime 模式，不自动改变用户直接操作终端的 OS 权限。
|
||||
- UI 必须持续将其标注为“用户终端”，避免被理解为 Ask Runtime 的只读输出。
|
||||
- Agent、模型、监督器和自动化不能调用终端 write，也不能把指令注入已有 Session。
|
||||
- 终端输出不会自动进入对话上下文、模型 Prompt、成果或活动记录。
|
||||
- Renderer 只能引用项目和 Session 的公开 ID；Main 从权威 store 解析目录、Host、凭据和
|
||||
当前 Host identity。
|
||||
- 不接受 Renderer 提交任意 Shell 可执行路径、SSH 命令、PID、环境变量集合或原始凭据。
|
||||
- 保持 Electron `contextIsolation`、sandbox 和禁用 Renderer Node integration。
|
||||
|
||||
## 14. 错误与反馈
|
||||
|
||||
- 创建失败、断线、Shell 退出和目标失效保留在终端面板，提供就地重试。
|
||||
- 不与全局通知重复显示同一终端错误。
|
||||
- 非局部错误，例如无法保存工作栏布局，可以进入应用通知。
|
||||
- 错误文案说明发生了什么、当前 Shell 是否仍在运行、用户可以做什么。
|
||||
- Host Key 变化沿用现有 Host 管理流程；终端只显示“主机身份已变化，请重新验证”，不在
|
||||
终端内复制凭据或 Host Key 修改流程。
|
||||
- 目标不可用时保留 Tab 名称和目标，不静默切换到本机或其他 Host。
|
||||
|
||||
## 15. 性能与资源要求
|
||||
|
||||
- 工作栏切换和终端输入在正常负载下保持即时反馈，持续输出不能阻塞主界面导航。
|
||||
- 同一窗口的活动终端数量必须有明确上限；达到上限时阻止新建并说明先关闭不用的终端。
|
||||
- 每个 Session 的输出队列、Renderer 滚动历史和 IPC 单事件均有硬上限。
|
||||
- 工作栏不可见时可以降低渲染刷新频率，但不能丢失终端协议字节或暂停 Shell 本身。
|
||||
- 应用退出复用现有总清理截止时间，不因终端新增无界等待。
|
||||
- 生产构建必须实际加载本机 PTY 原生模块；不能只验证文件存在。
|
||||
- 远程终端不能使 SSH connection pool 的空闲项、Channel 或监听器泄漏。
|
||||
|
||||
具体数值在共享契约和性能测试中确定，以现有 IPC、窗口和关闭预算为上限，不在多个进程中
|
||||
维护不同常量。
|
||||
|
||||
## 16. 无障碍与响应式
|
||||
|
||||
- Tab 使用 `tablist/tab/tabpanel`；“+”使用带可访问名称“打开工作栏应用”的普通按钮。
|
||||
- 应用选择页使用可键盘操作的列表或菜单语义，不使用 `SegmentedControl`；终端没有重复的
|
||||
目标选择页。
|
||||
- 每个终端 Tab 的可访问名称包含自定义名称或位置，多个终端不能都只读作“终端”。
|
||||
- Tab 关闭后焦点移动到确定的相邻 Tab；取消创建后焦点返回“+”。
|
||||
- 工作栏收起后焦点返回唯一工作栏开关，不增加焦点陷阱或遮罩。
|
||||
- 终端高频输出不逐行播报；只播报连接、退出、失败和中断。
|
||||
- 200% 文字缩放时，目标、Shell、目录、状态和关闭操作仍可访问。
|
||||
- Tab 单行横向滚动，终端内容随工作栏尺寸变化并同步 PTY，不把 Tab 换成下拉框。
|
||||
- 深色和浅色主题都使用设计系统语义令牌，并保持终端文本、选择和光标可辨。
|
||||
|
||||
## 17. 实施顺序与多代理工作包
|
||||
|
||||
功能必须以完整的本机和远程用户流程交付。以下是可并行的开发工作包，不表示可以发布只有
|
||||
Schema、假数据终端或不可用入口的中间产品。
|
||||
|
||||
### 17.1 依赖顺序
|
||||
|
||||
```text
|
||||
契约冻结
|
||||
├─ 工作栏实例壳层
|
||||
├─ 本机 PTY 后端
|
||||
├─ SSH PTY 后端
|
||||
└─ 终端 Renderer
|
||||
↓
|
||||
单一集成负责人完成 Main/Preload/App 接线
|
||||
↓
|
||||
完整验证、真实 Host 验收与文档同步
|
||||
```
|
||||
|
||||
### 17.2 文件所有权
|
||||
|
||||
| 工作包 | 主要职责 | 建议文件所有权 | 不应修改 |
|
||||
| --- | --- | --- | --- |
|
||||
| 契约与注册表 | Workbar/Terminal Schema、状态、测试 | 新建 `src/shared/workbar-contracts.ts`、`terminal-contracts.ts` 及测试 | `App.tsx`、`ipc.ts`、Preload |
|
||||
| 工作栏壳层 | 动态实例 Tab、“+”、选择页、单/多实例和焦点 | 新建工作栏组件及其测试 | PTY、SSH、Main IPC |
|
||||
| 本机终端后端 | 本机 PTY、输入、resize、退出和进程树清理 | 新建 `src/main/terminal/` 本机文件及测试 | Renderer、远程 Agent |
|
||||
| SSH 终端后端 | SSH PTY、lease、resize、断线和 Channel 清理 | 新建 `src/main/terminal/` 远程文件及聚焦测试 | 工作栏 UI、Agent 协议 |
|
||||
| 终端 Renderer | 模拟器、IME、搜索、复制粘贴、状态栏和 resize | 新建终端组件、样式和测试 | Main、SSH、中心 IPC |
|
||||
| 集成 | 依赖、IPC channel、DesktopApi、Preload、Main 注册、`App` 接线与关闭顺序 | `package.json`、lock、`ipc-channels.ts`、`contracts.ts`、`preload/index.ts`、`main/ipc.ts`、`App.tsx` | 不重写各包已验收内部逻辑 |
|
||||
| 验收与文档 | E2E、跨平台构建检查、真实 Host、最终文档 | 测试与相关文档 | 不用假实现替换生产路径 |
|
||||
|
||||
中心文件只能由集成负责人修改，避免多个代理同时编辑 `App.tsx`、`main/ipc.ts`、
|
||||
`shared/contracts.ts`、`preload/index.ts`、`package.json` 和 lockfile。
|
||||
|
||||
### 17.3 并行开发门槛
|
||||
|
||||
契约负责人先冻结：
|
||||
|
||||
- 应用注册和实例策略。
|
||||
- Terminal request、snapshot、event 和 error code。
|
||||
- Session 所有权和关闭语义。
|
||||
- 输出序号、ACK 与容量常量。
|
||||
|
||||
其他代理基于冻结契约工作。接口偏差由集成负责人统一修正，不由多个代理分别修改共享中心
|
||||
文件。
|
||||
|
||||
## 18. 验收标准
|
||||
|
||||
### 18.1 工作栏应用与实例
|
||||
|
||||
- [ ] Tab 行末始终显示“+”，包括没有任何打开实例时。
|
||||
- [ ] 点击“+”显示稳定应用目录，取消后返回原实例并恢复焦点。
|
||||
- [ ] 选择已打开单实例应用只聚焦已有 Tab。
|
||||
- [x] 连续选择终端会创建多个互相独立的终端 Tab。
|
||||
- [ ] 关闭、切换和重排实例后，“+”仍保持可用。
|
||||
- [ ] Tab 溢出时单行横向滚动，不隐藏“+”或把 Tab 换成下拉框。
|
||||
- [x] 关闭活动 Tab 后激活正确的相邻 Tab 并恢复焦点。
|
||||
- [x] 当前 Tab 的背景、边框、顶部指示和字重清晰可辨；关闭按钮仅在悬停、焦点或无悬停
|
||||
设备上出现，且不引发布局位移。
|
||||
- [ ] 升级后现有任务中心、工作区、浏览器和成果仍按默认布局打开且行为不回归。
|
||||
- [ ] 在所有主要页面都能打开工作栏；切换主要页面不会销毁 Tab 实例或终端 Session。
|
||||
|
||||
### 18.2 本机终端
|
||||
|
||||
- [x] 从“+ → 终端”直接打开当前本机项目的真实交互式 Shell，工作目录为项目根。
|
||||
- [ ] 没有项目时从用户 Home 打开本机 Shell。
|
||||
- [ ] `pwd` / `Get-Location`、交互输入、ANSI 颜色、中文 IME、复制和粘贴工作正常。
|
||||
- [ ] 调整工作栏和窗口尺寸会更新 PTY `cols/rows`，全屏 TTY 程序正确重绘。
|
||||
- [ ] 多个本机终端的输入、输出、目录和退出状态互不串线。
|
||||
- [ ] Shell 有活动子进程时关闭 Tab，确认后回收完整进程树；取消后 Session 继续运行。
|
||||
- [ ] 退出后的 Tab 显示退出码，并可在同一 Tab 显式创建新 Shell。
|
||||
|
||||
### 18.3 远程终端
|
||||
|
||||
- [ ] 从“+ → 终端”直接为当前托管 SSH 项目打开真实 SSH PTY。
|
||||
- [ ] 终端持续显示 Host、远端目录、Shell 和连接状态。
|
||||
- [ ] 使用现有固定 Host Key 和已存凭据，Renderer、日志和命令参数不出现凭据。
|
||||
- [ ] 输入、ANSI、中文、复制粘贴和 resize 在真实 Host 上工作正常。
|
||||
- [ ] 活动远程终端不会被 SSH connection pool 空闲回收。
|
||||
- [ ] SSH 断线立即标记“已中断”并拒绝继续输入，不显示为仍在运行。
|
||||
- [ ] “重新连接并新建 Shell”明确创建新 Session，不宣称恢复旧远端进程。
|
||||
- [ ] Host 删除、地址/用户/凭据或 Host Key generation 变化会中断旧 Session；新 Session
|
||||
使用当前 Host identity。
|
||||
|
||||
### 18.4 生命周期、性能和边界
|
||||
|
||||
- [ ] 收起工作栏、切换主页面、切换 Tab 或切换项目不会终止已有终端。
|
||||
- [ ] 终端不会随项目切换静默迁移执行位置。
|
||||
- [ ] 应用重启只恢复终端 Tab 描述，不自动连接或启动 Shell。
|
||||
- [ ] 输出顺序在持续大输出下保持正确，Main 和 Renderer 内存保持有界，主界面仍可操作。
|
||||
- [ ] 慢 Renderer 触发暂停和恢复，不丢弃中间终端字节。
|
||||
- [ ] Renderer 不获得 raw PTY、ChildProcess、SSH Client、PID、环境变量或凭据。
|
||||
- [ ] Agent、模型和自动化不能向已有用户终端注入输入。
|
||||
- [ ] 窗口销毁和应用退出在既有关闭截止时间内回收本机进程、SSH Channel 和监听器。
|
||||
- [ ] 重复 close、迟到 input/resize 和退出竞态不会操作其他 Session 或导致进程泄漏。
|
||||
|
||||
### 18.5 设计、无障碍和跨平台
|
||||
|
||||
- [ ] 仅使用键盘可以打开应用、创建终端、切换和关闭 Tab、复制、粘贴及重新连接。
|
||||
- [ ] Tab、“+”、选择页和关闭确认使用正确语义并有可见焦点。
|
||||
- [ ] 终端输出不逐行进入 live region，关键状态变化可被辅助技术感知。
|
||||
- [ ] 浅色、深色、200% 文字缩放和窄窗口下可以完成核心流程。
|
||||
- [ ] Windows、macOS、Linux x64 和 Linux arm64 的正式构建实际启动本机 PTY。
|
||||
- [ ] 远程链路在共享 Linux x64 真实 Host 上完成创建、输入、resize、断线、重连、关闭和
|
||||
应用退出验证；若 Host 不可达，远程终端不得标记为完成。
|
||||
|
||||
## 19. 验证计划
|
||||
|
||||
### 19.1 自动验证
|
||||
|
||||
- 共享 Zod Schema 和边界值测试。
|
||||
- 单/多实例注册策略、Tab 顺序、关闭焦点和“+”选择页组件测试。
|
||||
- 本机 PTY Session Manager 的输入、resize、退出、幂等关闭和进程树测试。
|
||||
- SSH PTY 的 Host identity、lease、断线、resize 和关闭测试。
|
||||
- Main trusted sender、Session 所有权、IPC 输入边界和事件路由测试。
|
||||
- Terminal Renderer 的 IME、键盘、ResizeObserver、订阅释放和状态测试。
|
||||
- `npm test`
|
||||
- `npm run typecheck`
|
||||
- `npm run lint`
|
||||
- `npm run build`
|
||||
|
||||
### 19.2 真实路径验证
|
||||
|
||||
- 在当前开发平台通过产品 UI 完成本机终端全流程。
|
||||
- 在共享 Linux x64 Host 通过现有 Host 配置完成远程终端全流程。
|
||||
- 真实运行需要 TTY 的程序，验证 ANSI、光标和 resize，不只运行非交互命令。
|
||||
- 持续输出并主动减慢 Renderer 消费，验证背压和内存上限。
|
||||
- 分别在本机和远程启动带子进程的命令，关闭 Tab 和应用后核对无 GoodBuddy 所属遗留资源。
|
||||
- 生产构建在各受支持平台实际加载 PTY 原生模块，不以单元测试或包内文件存在代替。
|
||||
|
||||
### 19.3 当前开发验证记录
|
||||
|
||||
2026-09-01 已通过生产 `SshConnectionPool` 和 `createSshTerminalSession` 在共享 Linux x64
|
||||
Host 完成直接 SSH PTY 验证：使用已有固定 Host Key 和测试凭据，以远端项目目录启动登录
|
||||
Shell，验证交互输入、ANSI、UTF-8 中文、`80×24` 到 `101×37` resize、连接销毁后进入
|
||||
`interrupted`、重新连接创建新 Shell，以及 Session close 和 connection pool dispose
|
||||
回收远端 Shell。验证只创建一个
|
||||
`$HOME/.goodbuddy/terminal-smoke-<UUID>` 临时目录，结束后已删除并确认无遗留 Shell 进程。
|
||||
|
||||
同日使用最新生产构建完成工作栏视觉检查：活动 Tab 使用连续内容表面、顶部强调线和应用
|
||||
图标；关闭按钮默认不可见，悬停后以 overlay 显示且 Tab 宽度不变；横向滚动继续可用但不
|
||||
显示滚动条，“+”保持独立可见。
|
||||
|
||||
本记录不替代尚未勾选的完整产品 UI、剪贴板、macOS、Linux arm64 和各平台本机 PTY 验收。
|
||||
|
||||
本 PRD 不改变 Agent 协议，因此首期远程终端无需 Agent package 更新。若实现期间改为
|
||||
Agent-owned PTY，必须先修订本文的远程生命周期和恢复语义，并按 Agent 开发规则在共享
|
||||
Linux x64 Host 验证当前源码或候选包。
|
||||
|
||||
## 20. 相关文档职责
|
||||
|
||||
- [通用助手工作栏与执行空间 PRD](./prd.md)：
|
||||
工作栏应用级位置、稳定能力目录、执行空间和总体范围。
|
||||
- 本文：持久“+”、应用实例策略、工作栏动态 Tab、自动项目目标、本机与直接 SSH 多终端。
|
||||
- [统一界面设计系统](../../../UI-DESIGN.md)：Tab、菜单、布局、主题、焦点和无障碍规则。
|
||||
- [SSH 远程主机与 GoodBuddy Agent 实现说明](../remote-host/technical-design.md)：
|
||||
Host Key、凭据、连接池、Agent 和远程项目现状。
|
||||
- [SSH Host 远程环境准备与控制面直连设计](../remote-host/environment-provisioning-technical-design.md)：
|
||||
Host 保存、环境准备和项目使用之间的职责。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 电脑控制
|
||||
|
||||
电脑控制包含 GoodBuddy 对浏览器和客户端桌面能力的产品实现与平台适配状态。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [功能进度](./progress.md) | 当前已实现能力、缺陷修复、平台限制和验证状态 |
|
||||
|
||||
当前只有进度文档；产品需求、功能逻辑、UI 和技术设计尚未从历史实现记录中独立整理。
|
||||
@@ -0,0 +1,176 @@
|
||||
# GoodBuddy 电脑控制开发进度
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 文档类型 | 实施进度 |
|
||||
| 状态 | 持续更新 |
|
||||
| 版本 | 0.3 |
|
||||
| 日期 | 2026-08-18 |
|
||||
| 适用能力 | 内置浏览器与客户端电脑控制 |
|
||||
|
||||
## 范围
|
||||
|
||||
本阶段不包含 LoongArch 和厂商互认证。目标平台仍为 Windows、macOS、
|
||||
Linux x64 和 Linux arm64。
|
||||
|
||||
## 已完成
|
||||
|
||||
### 直连模型与浏览器
|
||||
|
||||
- 已实现宿主进程拥有的隔离浏览器服务。
|
||||
- 使用 Electron 自带 Chromium 和 CDP，不下载额外浏览器。
|
||||
- 已实现导航、可访问性快照、点击、输入、选择、返回和有界截图工具。
|
||||
- 浏览器工具只在直连模型的 Execute 模式中提供；用户选择 Execute 即授权
|
||||
本次交互运行，不再逐个弹出 GoodBuddy 工具审批。
|
||||
- 支持当前设备可连接的 HTTP、HTTPS、公网、内网、本机和元数据地址，
|
||||
导航及重定向仍经过 DNS 解析和目标地址固定。
|
||||
- 已实现回环过滤代理、下载和文件选择器阻止、权限拒绝、会话取消、
|
||||
空闲回收和应用退出清理。
|
||||
- 直连模型工具循环不设置工具次数或模型轮次配额；取消、请求超时、工具结果大小和
|
||||
累计输出边界继续防止失控执行。
|
||||
|
||||
### MCP
|
||||
|
||||
- MCP 图片结果已支持 PNG、JPEG 和 WebP 的严格 Base64、文件签名和大小
|
||||
校验。
|
||||
- 已支持 Anthropic Messages、OpenAI Responses 和兼容 Chat Completions
|
||||
的多模态工具结果。
|
||||
- 已支持 MCP 进度续期、硬超时、Tasks、取消和关闭。
|
||||
- 自定义 stdio MCP 不继承桌面会话变量。
|
||||
- 已增加受审计 curated MCP 启动描述符，但在没有签名和打包的 helper
|
||||
前不启用外部桌面 helper。
|
||||
|
||||
### Computer Control Broker
|
||||
|
||||
- 已实现动作契约、风险分类、窗口租约、感知版本、过期引用、单次变更、
|
||||
审批、超时和取消核心。
|
||||
- 注入开始后的不确定失败记录为 `outcome_unknown`，防止重试造成重复提交。
|
||||
- 已实现 SQLite 持久审计，输入文本只保存长度和 SHA-256 摘要。
|
||||
|
||||
### Linux 技术预览
|
||||
|
||||
- 已实现 AT-SPI 语义核心、Portal 会话状态机、PipeWire 元数据校验、
|
||||
坐标映射和输入路由核心。
|
||||
- DDE、Treeland、UKUI、GNOME 和 KDE 名称只用于诊断，不用于假定能力。
|
||||
- 当前没有打包真实 D-Bus、PipeWire/libei 或 XTest 原生适配器，因此 Linux
|
||||
桌面控制保持不可启用，不能表述为生产可用。
|
||||
|
||||
### 设置与安全边界
|
||||
|
||||
- 能力存储已迁移到版本 2。
|
||||
- 内置浏览器已归入“直连模型”工具，与联网搜索并列，并明确说明不会控制
|
||||
客户端已安装的浏览器；原有开关和配置 ID 保持不变，用户状态无需迁移。
|
||||
- 用户通过内置浏览器总开关决定是否向直连模型提供工具；开启后可在 Execute
|
||||
模式直接使用，不逐次询问。诊断位于同一分类。
|
||||
- 尚未实际参与浏览器执行的命名配置已从界面隐藏；底层旧数据和兼容接口继续
|
||||
保留，不删除用户已有记录。
|
||||
- “电脑控制”只显示实际操作客户端电脑的能力。能力启用、配置变更和本地
|
||||
数据清除仍会替换或清理相关 Runtime 和会话。
|
||||
|
||||
## 本轮已修复缺陷
|
||||
|
||||
### P0：隔离浏览器创建失败，已修复
|
||||
|
||||
便携版中的两次失败都发生在浏览器导航工具进入运行状态约 15 秒后。
|
||||
隔离 Electron 探针已定位到：
|
||||
|
||||
1. 过滤代理启动成功。
|
||||
2. 隔离 Session 创建成功。
|
||||
3. 隐藏 BrowserWindow 创建成功。
|
||||
4. `webContents.debugger.attach('1.3')` 成功。
|
||||
5. 第一个 `Page.enable` CDP 命令一直不返回，最终触发 15 秒会话创建超时。
|
||||
|
||||
现在会先加载并等待 `about:blank` 初始文档，再附加并启用 CDP 域，同时保留
|
||||
超时后的迟到资源清理。真实 Electron 探针已确认 `Page.enable`、访问
|
||||
`https://example.com/` 和有界 JPEG 画面捕获均成功。
|
||||
|
||||
### P0：右侧没有浏览器实时画面，已修复
|
||||
|
||||
浏览器窗口默认使用 `show: false`，但 BrowserService 现在从模型实际操作的同一
|
||||
会话捕获页面帧，并通过受限 IPC 发送状态、当前 URL 和约 220KB 的 JPEG 画面。右侧工作栏
|
||||
新增“浏览器”页签；活动对话启动浏览器时会自动打开该页签，并显示创建中、
|
||||
加载中、操作中、用户交互中、就绪、失败和已停止状态。用户可点击“交互”打开
|
||||
同一会话的子窗口辅助 Agent；交互时主窗口暂时禁用，关闭时先刷新最终画面再将
|
||||
浏览器窗口最小化，页面和会话继续保留。用户也可明确关闭当前对话的浏览器会话。
|
||||
当前实现按导航、快照、点击、输入、选择、返回和截图操作刷新画面，而不是创建
|
||||
第二个预览浏览器，因此显示内容与模型受控页面一致。
|
||||
|
||||
### 已实现：浏览器工具栏
|
||||
|
||||
浏览器 Tab 顶部已增加“返回、刷新/停止加载、地址输入、前往、交互、关闭浏览器”工具栏。
|
||||
它继续操作 Agent 在当前 Conversation 中使用的同一浏览器会话；用户导航会有意改变 Agent
|
||||
下一步看到的页面。前往、返回和刷新通过 `BrowserService` 与 Agent 浏览器操作串行执行，
|
||||
不会创建第二套 Renderer 导航路径。
|
||||
|
||||
工具栏状态以浏览器提交后的权威 URL、是否加载中、能否返回和会话活动状态为准；地址输入
|
||||
在用户编辑期间保留本地草稿，不被状态刷新覆盖；提交未带 HTTP(S) 协议的裸域名时会自动添加
|
||||
`http://`。创建中、Agent 操作中和完整交互窗口期间禁用其余工具栏控件，但活动导航仍可用
|
||||
“停止加载”中断。停止加载只取消页面加载，不关闭浏览器，也不释放 Runtime 上下文；原“停止
|
||||
浏览器”会话生命周期操作已统一标为“关闭浏览器”，并在视觉和文案上与停止加载清楚区分。
|
||||
|
||||
活动 Conversation 尚无浏览器会话时，可直接从地址栏输入 URL 并“前往”，通过现有浏览器
|
||||
能力检查和同一 URL 策略创建会话。实现复用现有每 Conversation 串行队列和有界状态，不引入
|
||||
恢复、版本化或第二套会话框架。
|
||||
|
||||
### P0：百度输入时元素引用失效，已修复
|
||||
|
||||
截图中的“浏览器元素引用已失效，请重新获取快照”来自过宽的导航监听：广告或
|
||||
其他子框架开始导航、重定向时，也会清空主文档刚生成的元素引用。驱动现在只在
|
||||
主框架导航和重定向时清空引用，子框架活动不再中断主页面输入和点击。
|
||||
|
||||
如果主页面确实已经变化，过期引用会作为“可重试”工具结果返回给直连模型，并
|
||||
明确要求重新调用 `browser_snapshot`；模型可以用新引用继续操作，不再让整次
|
||||
任务直接失败。页面原始可访问性树不再按字节大小拒绝；无论页面多大，驱动都会
|
||||
读取页面并自动截取单次返回给模型的快照，同时用 `truncated` 明确标记，不再
|
||||
显示“浏览器可访问性树超过安全限制”。
|
||||
|
||||
真实 Electron 探针已完成“打开百度、获取快照、输入阿里云、点击百度一下、
|
||||
读取结果页”，结果页标题为“阿里云_百度搜索”，返回约 330 个节点并正确标记
|
||||
为已截断。
|
||||
|
||||
海关总署网站使用会变化的 CDN 地址和 JavaScript 挑战。过滤代理现在会在经过
|
||||
策略验证的地址间有界回退，并等待真正的主框架提交，不再把旧 `about:blank`
|
||||
误报为成功；托管浏览器同时使用标准 Chromium User-Agent。真实 Electron
|
||||
探针已确认 `http://www.customs.gov.cn/` 返回“中华人民共和国海关总署”标题、
|
||||
约 310 个快照节点，以及约 161KB 的工具截图和右侧实时 JPEG 画面。
|
||||
|
||||
### P0：截图与用户附件展示，已改善
|
||||
|
||||
浏览器、全屏和单窗口画面统一压缩为约 220KB 的 JPEG，再送入模型或实时预览。
|
||||
用户发送的文档和图片会在知识检索及 Runtime 调用前立即显示在对应用户消息中，
|
||||
并随会话持久化。单窗口截图不再使用横向原生按钮，改为应用内纵向窗口列表，
|
||||
避免选择器被多个长应用名称横向撑宽。
|
||||
|
||||
### P1：工具错误信息过度包装，已改善
|
||||
|
||||
浏览器会话创建错误现在包含“启动代理、创建隔离会话、配置网络代理、创建窗口、
|
||||
加载初始页面、初始化浏览器协议”等有界阶段信息；实时页签也显示当前操作阶段
|
||||
和截断后的错误原因。
|
||||
|
||||
浏览器底层错误目前被包装为“工具『浏览器导航』执行失败”，数据库和界面无法
|
||||
区分代理、分区、窗口、CDP 初始化、DNS 或页面导航失败。需要增加有界、脱敏的
|
||||
阶段错误码，并保留用户可执行的修复建议。
|
||||
|
||||
### P1：命名浏览器配置尚未用于执行，界面已隐藏
|
||||
|
||||
命名浏览器配置当前只保存未来托管隔离所需的元数据，实际执行仍使用每个会话
|
||||
随机创建的临时分区，不复用登录状态。为避免用户误以为该配置已经生效，设置
|
||||
界面暂不显示创建、选择、重命名或删除入口；底层数据与兼容接口继续保留。
|
||||
|
||||
## 下一步顺序
|
||||
|
||||
1. 在便携版真实模型流程中继续验证返回、取消和右侧画面刷新。
|
||||
2. 再设计命名隔离 Profile 的持久登录态、引用和清理策略。
|
||||
3. 分别实现并真机验证 Windows UIA、macOS AX 和 Linux 原生适配器。
|
||||
|
||||
## 最近验证
|
||||
|
||||
- `npm test`：591 项通过，6 项跳过。
|
||||
- `npm run typecheck`：通过。
|
||||
- `npm run lint`：通过。
|
||||
- `npm run build`：通过。
|
||||
|
||||
以上自动化结果覆盖协议、安全边界和模拟驱动，不替代真实 Electron
|
||||
BrowserWindow/WebContentsView、目标网站和目标 Linux 桌面环境的集成验证。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 持续学习
|
||||
|
||||
持续学习定义 GoodBuddy 如何从运行结果、评估证据和人工反馈中形成可验证的改进闭环。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [持续学习与评估门 PRD](./prd.md) | 产品目标、学习边界、评估门和验收要求 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
@@ -0,0 +1,410 @@
|
||||
# 持续学习与评估门 PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 设计中，远期能力 |
|
||||
| 版本 | 0.3 |
|
||||
| 日期 | 2026-08-19 |
|
||||
| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[并行实验 PRD](../parallel-experiments/prd.md)、[分区记忆 PRD](../memory/prd.md) |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
智能心跳可以生成摘要、后续任务和记忆候选，但这还不是完整学习。其长期“未来分区记忆”
|
||||
方向尚未设计，也不承担持续学习、模式挖掘或自动改进：
|
||||
|
||||
- 候选是否改善未来行为没有评估。
|
||||
- 一条反思是否会被检索和使用并不确定。
|
||||
- 没有 Baseline、回放集、Shadow、晋升和回滚。
|
||||
- 没有持续监控候选生效后的收益与退化。
|
||||
- 如果允许系统直接修改 Prompt、Skill 或规则，可能发生静默劣化。
|
||||
|
||||
持续学习必须建立为可观察、可评估、可批准、可回滚的闭环，而不是“让模型自动改自己”。
|
||||
|
||||
## 2. 产品定义
|
||||
|
||||
```text
|
||||
Observe
|
||||
→ Propose candidate
|
||||
→ Validate structure and safety
|
||||
→ Evaluate against baseline
|
||||
→ Shadow
|
||||
→ Promote with approval
|
||||
→ Monitor
|
||||
→ Keep, revise, rollback or archive
|
||||
```
|
||||
|
||||
学习产物只有在改变未来行为后才算生效；只保存一条 Reflection 仍属于记忆候选。
|
||||
|
||||
## 3. 已确认的产品决策
|
||||
|
||||
1. 评估门必须先于任何自动应用能力上线。
|
||||
2. 新候选默认 `candidate`，通过离线评估后先进入 `shadow`。
|
||||
3. 第一阶段只允许人工晋升。
|
||||
4. 每次晋升必须记录 Baseline、候选、评估结果、作用域和回滚版本。
|
||||
5. 学习不能修改安全边界、工具审批、目录权限、沙箱或 Electron 配置。
|
||||
6. 失败案例和用户负反馈只作为评估数据，不直接成为新规则。
|
||||
7. 回放案例必须脱敏、版本化，并得到用户明确选择或来自仓库公开样例。
|
||||
8. 模型评估不是唯一真值，优先使用确定性验收和人工反馈。
|
||||
9. 生效后的候选继续监控，发生退化可自动停用，但不能自动换上另一个候选。
|
||||
10. 没有足够证据时保持 `inconclusive`，不强行晋升。
|
||||
|
||||
## 4. 学习产物
|
||||
|
||||
首期只支持：
|
||||
|
||||
| 产物 | 作用 | 是否可自动应用 |
|
||||
| --- | --- | --- |
|
||||
| Memory | 改善相关上下文召回 | 否，人工确认 |
|
||||
| Automation Template | 改善目标、步骤、提示或预算默认值 | 否，创建新草稿 |
|
||||
| Prompt Variant | 用于实验比较 | 否 |
|
||||
| Rubric | 改善评估标准 | 否 |
|
||||
| Retrieval Preference | 调整特定 Automation 的检索配置候选 | 否 |
|
||||
|
||||
后续评估：
|
||||
|
||||
| 产物 | 风险 |
|
||||
| --- | --- |
|
||||
| Skill | 可能扩大行为和工具使用 |
|
||||
| Procedure | 可能长期影响多个任务 |
|
||||
| Non-security Rule | 可能阻断或改变行为 |
|
||||
| Agent Preference | 可能产生难以解释的个性漂移 |
|
||||
|
||||
永久禁止自动学习修改：
|
||||
|
||||
- 工具权限和审批策略。
|
||||
- 工作区根目录和文件访问范围。
|
||||
- 网络、远程消息和电脑控制权限。
|
||||
- Electron 安全设置。
|
||||
- API Key、凭据和 Provider Endpoint。
|
||||
- 删除、支付、发布和生产操作政策。
|
||||
|
||||
## 5. 候选来源
|
||||
|
||||
- 用户对回答、任务或 Supervisor 意见的显式反馈。
|
||||
- 用户对心跳报告或建议的显式反馈。
|
||||
- Task 执行的成功与失败比较。
|
||||
- 并行实验结论。
|
||||
- 回放评估发现的稳定差异。
|
||||
- 用户手动创建。
|
||||
|
||||
候选必须包含：
|
||||
|
||||
- 作用域。
|
||||
- 产物类型。
|
||||
- 来源证据。
|
||||
- 预期改善的指标。
|
||||
- 可能影响的行为。
|
||||
- 风险级别。
|
||||
- Baseline 引用。
|
||||
- 建议的评估集。
|
||||
|
||||
模型不能仅凭一条成功案例宣称“已学习”。
|
||||
|
||||
## 6. 状态机
|
||||
|
||||
```text
|
||||
candidate
|
||||
→ evaluating
|
||||
→ rejected
|
||||
→ inconclusive
|
||||
→ shadow
|
||||
→ awaiting_approval
|
||||
→ promoted
|
||||
→ paused
|
||||
→ rolled_back
|
||||
→ archived
|
||||
```
|
||||
|
||||
| 状态 | 含义 |
|
||||
| --- | --- |
|
||||
| `candidate` | 尚未评估 |
|
||||
| `evaluating` | 正在运行离线评估 |
|
||||
| `rejected` | 明确退化、安全不合格或无效 |
|
||||
| `inconclusive` | 证据不足 |
|
||||
| `shadow` | 计算候选决策但不影响真实行为 |
|
||||
| `awaiting_approval` | 达到晋升标准，等待用户 |
|
||||
| `promoted` | 已作为指定作用域的当前版本 |
|
||||
| `paused` | 暂停影响，保留版本 |
|
||||
| `rolled_back` | 已恢复前一版本 |
|
||||
| `archived` | 不再评估和使用 |
|
||||
|
||||
## 7. 评估案例
|
||||
|
||||
### 7.1 案例来源
|
||||
|
||||
优先级：
|
||||
|
||||
1. 仓库内公开、无隐私的固定评测样例。
|
||||
2. 用户手动创建的案例和期望。
|
||||
3. 用户明确选择并脱敏的历史会话或任务。
|
||||
4. 实验中产生、经用户批准保留的案例。
|
||||
|
||||
禁止默认采样所有私人会话用于学习。
|
||||
|
||||
### 7.2 案例结构
|
||||
|
||||
```ts
|
||||
type EvaluationCase = {
|
||||
id: string
|
||||
suiteId: string
|
||||
input: EvaluationInput
|
||||
assertions: EvaluationAssertion[]
|
||||
forbiddenBehaviors: EvaluationAssertion[]
|
||||
source: EvaluationCaseSource
|
||||
sensitivity: 'public' | 'private_local'
|
||||
version: number
|
||||
}
|
||||
```
|
||||
|
||||
断言可以是：
|
||||
|
||||
- 输出符合 Schema。
|
||||
- 包含或不包含确定文本模式。
|
||||
- 引用来自允许知识库。
|
||||
- 不调用工具。
|
||||
- 任务状态和成果存在。
|
||||
- 测试命令通过。
|
||||
- 人工评分。
|
||||
- 模型 Rubric 分项。
|
||||
|
||||
### 7.3 冻结
|
||||
|
||||
一次评估冻结：
|
||||
|
||||
- 案例版本。
|
||||
- Baseline 版本。
|
||||
- Candidate 版本。
|
||||
- Runtime 和模型。
|
||||
- 知识、记忆和工作区快照。
|
||||
- 预算。
|
||||
- 评估器版本。
|
||||
|
||||
设置变化不改变已开始的评估。
|
||||
|
||||
## 8. 评估门
|
||||
|
||||
### 8.1 判定
|
||||
|
||||
```ts
|
||||
type GateVerdict = {
|
||||
decision: 'reject' | 'inconclusive' | 'shadow'
|
||||
baselineMetrics: MetricValue[]
|
||||
candidateMetrics: MetricValue[]
|
||||
regressions: Regression[]
|
||||
caseIds: string[]
|
||||
evaluatorVersions: string[]
|
||||
notes: string
|
||||
}
|
||||
```
|
||||
|
||||
最小规则：
|
||||
|
||||
1. 任何安全、权限或硬约束退化立即 Reject。
|
||||
2. 确定性质量指标不能低于配置阈值。
|
||||
3. 成本和延迟退化必须在允许范围。
|
||||
4. 开放质量指标至少非退化，或收益足以覆盖明确成本。
|
||||
5. 案例数或评估器不足时 Inconclusive。
|
||||
6. 通过离线门只进入 Shadow，不直接 Promote。
|
||||
|
||||
### 8.2 Baseline
|
||||
|
||||
Baseline 是当前已生效版本或明确的无候选行为。不能用另一个同时变化的实验配置充当 Baseline。
|
||||
|
||||
### 8.3 多模型评估
|
||||
|
||||
模型 Rubric 可使用与被评候选不同的模型，但必须：
|
||||
|
||||
- 固定版本和提示。
|
||||
- 隐藏候选身份。
|
||||
- 随机化顺序。
|
||||
- 保存分项和证据。
|
||||
- 在关键晋升中结合确定性或人工评估。
|
||||
|
||||
## 9. Shadow
|
||||
|
||||
Shadow 模式：
|
||||
|
||||
- 接收与当前真实行为相同的有界输入。
|
||||
- 计算候选会做出的选择或输出。
|
||||
- 不调用有副作用工具。
|
||||
- 不替换用户看到的结果。
|
||||
- 不写入长期记忆。
|
||||
- 保存与实际结果可比较的指标。
|
||||
|
||||
对于成本较高的候选：
|
||||
|
||||
- 只对抽样的已授权案例运行。
|
||||
- 用户可设置月度调用上限。
|
||||
- 系统繁忙时延后。
|
||||
|
||||
Shadow 达到配置的最小观察数且无安全退化后进入 `awaiting_approval`。
|
||||
|
||||
## 10. 晋升
|
||||
|
||||
晋升对话框必须显示：
|
||||
|
||||
- 候选将改变什么。
|
||||
- 作用域和受影响计划。
|
||||
- 来源。
|
||||
- Baseline 与 Candidate 指标。
|
||||
- 失败案例和不确定性。
|
||||
- 额外成本。
|
||||
- 回滚版本。
|
||||
|
||||
用户可以：
|
||||
|
||||
- 晋升。
|
||||
- 继续 Shadow。
|
||||
- 拒绝。
|
||||
- 缩小作用域后重新评估。
|
||||
|
||||
晋升采用原子版本切换。不能在一半对象上成功、一半失败。
|
||||
|
||||
## 11. 上线后监控
|
||||
|
||||
监控：
|
||||
|
||||
- 使用次数。
|
||||
- 成功、失败和无结论。
|
||||
- 确定性指标。
|
||||
- 用户采纳、撤销和负反馈。
|
||||
- Token、耗时和工具调用变化。
|
||||
- Supervisor 警告变化。
|
||||
|
||||
自动暂停条件：
|
||||
|
||||
- 安全或权限硬约束失败。
|
||||
- 确定性错误率超过阈值。
|
||||
- 连续崩溃或格式失败。
|
||||
- 成本超过批准上限。
|
||||
|
||||
自动暂停只恢复到上一已批准版本，并通知用户。系统不能自行选择新候选替代。
|
||||
|
||||
## 12. 回滚
|
||||
|
||||
- 每个 Promoted 产物有不可变版本。
|
||||
- 保存前一版本和作用域绑定。
|
||||
- 一键回滚使用原子切换。
|
||||
- 回滚不删除失败版本，保留指标和原因。
|
||||
- 当前有运行使用该版本时，只影响下一次 Run；紧急安全暂停可取消尚未开始的 Run。
|
||||
- 被回滚候选再次晋升必须重新评估。
|
||||
|
||||
## 13. 衰减与归档
|
||||
|
||||
- 长期未使用的候选和 Shadow 可归档。
|
||||
- Promoted 产物不因时间静默删除。
|
||||
- Memory 类型遵守分区记忆的衰减规则。
|
||||
- 评估案例变化后，相关候选标记为“评估过期”。
|
||||
- 模型或 Runtime 大版本变化时，可要求重新回放。
|
||||
- 归档保留不含私人正文的指标和版本元数据。
|
||||
|
||||
## 14. 信息架构
|
||||
|
||||
若远期验证确有集中学习管理需求，应提供独立且可审计的“学习”视图，而不是放入智能心跳、
|
||||
任务中心或一个尚未确认的自动化中心：
|
||||
|
||||
1. **候选**：来源、作用域、预期收益和风险。
|
||||
2. **评估中**：进度、案例和预算。
|
||||
3. **Shadow**：观察数、差异和成本。
|
||||
4. **待批准**：晋升摘要。
|
||||
5. **已生效**：当前版本、使用量和健康状态。
|
||||
6. **历史**：拒绝、回滚和归档。
|
||||
|
||||
候选详情页签：
|
||||
|
||||
- 概览。
|
||||
- 变更 Diff。
|
||||
- 评估案例。
|
||||
- 指标和失败。
|
||||
- Shadow。
|
||||
- 版本与回滚。
|
||||
|
||||
## 15. 数据模型建议
|
||||
|
||||
```ts
|
||||
type LearningArtifact = {
|
||||
id: string
|
||||
scopeKind: 'global' | 'project' | 'automation' | 'agent'
|
||||
scopeId?: string
|
||||
kind:
|
||||
| 'memory'
|
||||
| 'automation_template'
|
||||
| 'prompt_variant'
|
||||
| 'rubric'
|
||||
| 'retrieval_preference'
|
||||
status:
|
||||
| 'candidate'
|
||||
| 'evaluating'
|
||||
| 'rejected'
|
||||
| 'inconclusive'
|
||||
| 'shadow'
|
||||
| 'awaiting_approval'
|
||||
| 'promoted'
|
||||
| 'paused'
|
||||
| 'rolled_back'
|
||||
| 'archived'
|
||||
payload: JsonValue
|
||||
sourceRefs: LearningSourceRef[]
|
||||
baselineVersionId?: string
|
||||
promotedVersionId?: string
|
||||
createdAt: string
|
||||
updatedAt: string
|
||||
}
|
||||
```
|
||||
|
||||
建议表：
|
||||
|
||||
- `learning_artifacts`
|
||||
- `learning_artifact_versions`
|
||||
- `evaluation_suites`
|
||||
- `evaluation_cases`
|
||||
- `evaluation_runs`
|
||||
- `evaluation_results`
|
||||
- `shadow_observations`
|
||||
- `promotion_events`
|
||||
- `rollback_events`
|
||||
|
||||
## 16. 安全与隐私
|
||||
|
||||
1. Apply 层拒绝没有 Gate Verdict 的候选。
|
||||
2. 产物类型和目标作用域使用代码白名单。
|
||||
3. 安全与权限配置不在可学习目标白名单中。
|
||||
4. 私人评估案例只在本地使用，不导出或发送到未授权 Provider。
|
||||
5. Shadow 不调用有副作用工具。
|
||||
6. Candidate 内容和评估输出都视为不可信数据。
|
||||
7. Renderer 不能直接设置 Promoted 状态，Main 验证评估与审批。
|
||||
8. 删除私人评估案例后清理派生缓存和 Embedding。
|
||||
9. 日志不记录完整案例、Prompt、回答、文件或凭据。
|
||||
10. 自动暂停采用确定性条件，不依赖模型自由判断。
|
||||
|
||||
## 17. 实施顺序
|
||||
|
||||
严格顺序：
|
||||
|
||||
1. 建立版本化评估案例和确定性断言。
|
||||
2. 复用并行实验运行 Baseline 与 Candidate。
|
||||
3. 实现 Gate Verdict，只有 Reject、Inconclusive 和 Shadow。
|
||||
4. 实现 Shadow，但不允许 Apply。
|
||||
5. 实现人工晋升和原子回滚。
|
||||
6. 实现上线监控和确定性自动暂停。
|
||||
7. 首先开放 Memory 和 Automation Template。
|
||||
8. 经过长期验证后再评估 Skill、Procedure 和非安全规则。
|
||||
|
||||
不能先做自动改 Prompt，再补评估门。
|
||||
|
||||
## 18. 验收标准
|
||||
|
||||
- [ ] 没有评估结果的候选无法晋升。
|
||||
- [ ] 安全、权限或硬约束退化必定 Reject。
|
||||
- [ ] 评估不足时显示 Inconclusive，不强行选优。
|
||||
- [ ] Baseline、Candidate、案例、Runtime 和评估器都被冻结和版本化。
|
||||
- [ ] Shadow 不影响用户结果、不调用副作用工具、不写长期记忆。
|
||||
- [ ] 晋升前展示收益、退化、成本、作用域和回滚版本。
|
||||
- [ ] 第一阶段只有用户可以批准晋升。
|
||||
- [ ] 晋升和回滚采用原子版本切换。
|
||||
- [ ] 生效后出现确定性严重退化时自动暂停并恢复上一批准版本。
|
||||
- [ ] 系统不会自动选择另一个候选替代。
|
||||
- [ ] 私人会话不会默认进入评估集。
|
||||
- [ ] 安全策略、权限、目录、凭据和 Electron 配置不属于可学习产物。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 会话监督
|
||||
|
||||
会话监督定义对长会话、工具执行和异常状态的观察、判断与介入边界。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [会话监督 PRD](./prd.md) | 监督目标、证据、介入方式和产品验收 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
@@ -0,0 +1,415 @@
|
||||
# 会话监督 PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 设计中 |
|
||||
| 版本 | 0.2 |
|
||||
| 日期 | 2026-08-18 |
|
||||
| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md) |
|
||||
| 界面归属 | [通用助手工作栏与执行空间](../assistant-workbar/prd.md) |
|
||||
| 体验参考 | GoodBuddy 魔法笔记 AI 评论流 |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
GoodBuddy 的魔法笔记已经提供一种有价值的交互：用户持续写作，AI 在右侧以长评、建议和
|
||||
警告进行评论，用户可以选择综合、扩展、润色、质疑或发散方向。该能力是内容分析，不是
|
||||
会话监督：
|
||||
|
||||
- 只分析当前笔记或待办文本。
|
||||
- 不观察聊天任务、工具调用、目标、预算或成果。
|
||||
- 不参与任务状态机。
|
||||
- 不引用具体会话步骤。
|
||||
- 不支持关注、暂停和解决流程。
|
||||
|
||||
随着目标任务和并行实验出现，用户需要一个与执行 Agent 相互独立的观察者，帮助发现偏题、
|
||||
遗漏、矛盾、证据不足、循环、成本失控和潜在风险。
|
||||
|
||||
## 2. 产品定义
|
||||
|
||||
会话监督是在明确范围和策略下，对普通 Conversation、Task 或 Experiment 的可见事件
|
||||
进行独立观察，产生带证据的评论、告警和人工介入请求。每个 Task 只关联一条 Conversation，
|
||||
一条 Conversation 可以承载多个 Task；Job/Run 是内部执行和审计对象，不作为当前 UI
|
||||
监督目标。
|
||||
|
||||
它不是：
|
||||
|
||||
- 第二个替用户发言的聊天 Agent。
|
||||
- 隐藏推理查看器。
|
||||
- 工具审批器。
|
||||
- 可以绕过安全边界的“总管理员”。
|
||||
- 自动修正执行过程的通用控制器。
|
||||
|
||||
## 3. 核心产品判断
|
||||
|
||||
建议增加会话监督，首期采用“魔法笔记式右侧评论流”，但只开放以下能力：
|
||||
|
||||
```text
|
||||
观察
|
||||
→ 评论 / 警告
|
||||
→ 用户查看证据
|
||||
→ 用户忽略、采纳、询问、暂停或调整任务
|
||||
```
|
||||
|
||||
首期模型监督不自动暂停。只有现有确定性安全规则、预算和用户显式配置的硬门禁可以自动暂停。
|
||||
|
||||
## 4. 已确认的产品决策
|
||||
|
||||
1. 监督默认关闭，由用户对 Conversation、Task 或实验显式启用。
|
||||
2. 监督只读取用户可查看的消息、工具事件、状态、指标、成果摘要和目标。
|
||||
3. 不读取、推断或保存模型隐藏推理链。
|
||||
4. 每条重要判断必须引用具体消息、工具、步骤、指标或成果。
|
||||
5. 模型监督默认只评论、警告或请求人工复核。
|
||||
6. 确定性监督负责权限、预算、Schema、幂等和硬停止条件。
|
||||
7. 监督器不能自动批准工具、扩大范围、修改安全策略或替用户发送消息。
|
||||
8. 监督评论不是长期事实，默认不进入记忆。
|
||||
9. 监督调用使用独立预算和低于前台对话的优先级。
|
||||
10. 同一个事件不能同时产生重复页内警告、评论和全局通知。
|
||||
|
||||
## 5. 目标
|
||||
|
||||
### 5.1 用户目标
|
||||
|
||||
- 在重要会话旁获得不中断主对话的独立评论。
|
||||
- 及时发现目标偏移、缺少证据、相互矛盾、重复循环和遗漏要求。
|
||||
- 点击监督意见查看对应证据，而不是接受无来源判断。
|
||||
- 对监督意见进行采纳、忽略、标记误报或追问。
|
||||
- 对 Scheduled/Goal Task 设置更严格的监督策略和人工检查点。
|
||||
|
||||
### 5.2 产品目标
|
||||
|
||||
- 为普通会话、目标任务和实验提供统一监督契约。
|
||||
- 让确定性安全门禁与模型质量判断保持分层。
|
||||
- 保存有界、可审计的监督事件，而非复制完整会话。
|
||||
- 将用户反馈用于调整规则和评估监督器，但不自动训练或改策略。
|
||||
|
||||
## 6. 非目标
|
||||
|
||||
- 不展示内部 Chain of Thought。
|
||||
- 不持续监控其他应用、键盘、麦克风或屏幕。
|
||||
- 不把 Supervisor 设为拥有所有工具的超级 Agent。
|
||||
- 不自动修改用户消息或助手回答。
|
||||
- 不保证识别所有事实错误、偏见或安全风险。
|
||||
- 不把一次模型警告作为任务失败的确定性依据。
|
||||
- 不在首期支持 Supervisor 与执行 Agent 自主多轮辩论。
|
||||
- 不让 Supervisor 读取未授权项目、会话、知识库或记忆。
|
||||
|
||||
## 7. 监督对象
|
||||
|
||||
| 对象 | 观察内容 | 典型用途 |
|
||||
| --- | --- | --- |
|
||||
| 普通会话 | 用户消息、助手回答、引用、工具事件 | 质量和证据评论 |
|
||||
| Task | 目标、状态、Conversation、成果 | 偏离、循环和失败分析 |
|
||||
| Experiment | 协议、变量、各候选执行、指标和证据 | 协议一致性、评估公平性与无结论提示 |
|
||||
|
||||
每个监督会话只能绑定一个主对象，并继承其项目范围。
|
||||
|
||||
## 8. 监督模式
|
||||
|
||||
### 8.1 评论方向
|
||||
|
||||
借鉴魔法笔记，普通会话支持：
|
||||
|
||||
| 模式 | 行为 |
|
||||
| --- | --- |
|
||||
| 综合 | 平衡总结目标、进展、风险和下一步 |
|
||||
| 质疑 | 检查逻辑跳跃、前提、反例和证据 |
|
||||
| 证据 | 检查重要结论是否有可追溯依据 |
|
||||
| 目标 | 检查是否回应用户目标和约束 |
|
||||
| 风险 | 检查权限、隐私、外部影响和不可逆行为 |
|
||||
|
||||
自动化和实验可组合多个检查维度，不用方向单选替代确定性规则。
|
||||
|
||||
### 8.2 触发方式
|
||||
|
||||
| 方式 | 说明 |
|
||||
| --- | --- |
|
||||
| 手动 | 用户点击“检查当前会话” |
|
||||
| 每次回复后 | 助手一轮完成后异步分析 |
|
||||
| 每 N 步 | 自动化或实验按有界步骤间隔分析 |
|
||||
| 关键事件 | 工具失败、预算 80%、等待审批、指标异常 |
|
||||
| Run 结束 | 进行最终监督回顾 |
|
||||
|
||||
首期优先手动和每次回复后。草稿输入不发送给监督器，除非未来明确增加类似魔法笔记的
|
||||
草稿评论模式。
|
||||
|
||||
### 8.3 干预级别
|
||||
|
||||
```ts
|
||||
type SupervisorAction =
|
||||
| 'continue'
|
||||
| 'comment'
|
||||
| 'warn'
|
||||
| 'request_review'
|
||||
| 'pause'
|
||||
| 'stop'
|
||||
```
|
||||
|
||||
- 模型 Supervisor 首期只可产生前四种。
|
||||
- `pause` 和 `stop` 只来自确定性门禁或用户操作。
|
||||
- 后续若允许模型建议暂停，仍需确定性策略把建议转换为 `request_review` 或经过用户预授权。
|
||||
|
||||
## 9. 观察输入
|
||||
|
||||
### 9.1 可见输入
|
||||
|
||||
- 当前对象的名称、目标和约束。
|
||||
- 最近有界消息。
|
||||
- 工具名称、状态、参数摘要和输出摘要。
|
||||
- Task、Job 和 Subjob 状态。
|
||||
- 成果标题、类型、大小和有界摘要。
|
||||
- 引用和知识检索诊断。
|
||||
- 预算使用。
|
||||
- 明确配置的监督规则。
|
||||
- 已解决或被忽略的近期监督意见摘要。
|
||||
|
||||
### 9.2 禁止输入
|
||||
|
||||
- API Key、Token、Cookie 和认证头。
|
||||
- 模型隐藏推理。
|
||||
- 未授权文件和完整私人文档。
|
||||
- 其他项目、会话或实验 Run 的数据。
|
||||
- 原始无限长度工具输出。
|
||||
- 已删除或用户要求忘记的记忆。
|
||||
|
||||
### 9.3 上下文窗口
|
||||
|
||||
- 普通会话默认最近 12 条消息和最多 24,000 字符。
|
||||
- 任务按最近 20 个关键事件和当前目标组装。
|
||||
- 长会话先使用确定性提取，再由监督器处理有界输入。
|
||||
- 不能把 Supervisor 自己的旧评论无限回填，最多保留近期未解决摘要。
|
||||
|
||||
## 10. 监督输出
|
||||
|
||||
```ts
|
||||
type SupervisorDecision = {
|
||||
action:
|
||||
| 'continue'
|
||||
| 'comment'
|
||||
| 'warn'
|
||||
| 'request_review'
|
||||
category:
|
||||
| 'goal_drift'
|
||||
| 'missing_requirement'
|
||||
| 'evidence_gap'
|
||||
| 'contradiction'
|
||||
| 'repetition'
|
||||
| 'quality'
|
||||
| 'risk'
|
||||
| 'budget'
|
||||
severity: 'info' | 'low' | 'medium' | 'high'
|
||||
title: string
|
||||
content: string
|
||||
evidence: SupervisorEvidenceRef[]
|
||||
confidence: number
|
||||
suggestedActions: SupervisorSuggestedAction[]
|
||||
}
|
||||
```
|
||||
|
||||
证据引用可以指向：
|
||||
|
||||
- `messageId`
|
||||
- `toolCallId`
|
||||
- `taskEventId`
|
||||
- `artifactId`
|
||||
- `metricId`
|
||||
- `approvalId`
|
||||
|
||||
没有有效证据时，严重度最多为 `low`，且必须显示“推测”。
|
||||
|
||||
## 11. 确定性监督
|
||||
|
||||
以下检查由代码执行：
|
||||
|
||||
- Ask 出现写工具请求。
|
||||
- 工具或路径超出计划快照。
|
||||
- 未经批准的跨项目或跨分区读取。
|
||||
- Token、时间、工具、Job/Subjob 和成果预算。
|
||||
- 幂等键冲突或结果未知。
|
||||
- 输出 Schema 不匹配。
|
||||
- 实验 Run 读取其他 Run 数据。
|
||||
- 硬停止条件和必填成果。
|
||||
|
||||
确定性监督可以阻止、暂停或终止运行。结果必须包含规则 ID、实际值、阈值和触发事件，
|
||||
不通过模型重新解释才能生效。
|
||||
|
||||
## 12. 模型监督
|
||||
|
||||
适合判断：
|
||||
|
||||
- 回答是否偏离用户问题。
|
||||
- 计划是否遗漏明确要求。
|
||||
- 重要结论是否缺少证据。
|
||||
- 当前回答与前文是否矛盾。
|
||||
- 是否重复尝试而没有进展。
|
||||
- 是否存在值得用户注意的模糊风险。
|
||||
|
||||
模型监督输出严格经过 Schema 校验。格式错误最多修复一次；失败不阻塞普通前台会话，
|
||||
但在配置为自动化门禁时必须明确记录“监督不可用”，不能假装检查通过。
|
||||
|
||||
## 13. 用户交互
|
||||
|
||||
### 13.1 工作栏监督栏目评论流
|
||||
|
||||
监督是助手工作栏中固定且始终可访问的栏目，不是只在聊天页面出现的附属面板。栏目默认
|
||||
跟随当前会话，用户也可以固定到其他普通 Conversation、Task 或 Experiment。
|
||||
切换页面不会改变固定目标；目标失效时必须显示修复状态，不能静默回到当前会话。
|
||||
|
||||
复用魔法笔记的体验方向：
|
||||
|
||||
- 长评卡。
|
||||
- 建议卡。
|
||||
- 警告卡。
|
||||
- 证据链接。
|
||||
- 评论方向和时间。
|
||||
|
||||
每条意见操作：
|
||||
|
||||
- 查看证据。
|
||||
- 采纳建议。
|
||||
- 追问。
|
||||
- 忽略。
|
||||
- 标记误报。
|
||||
- 对自动化请求暂停。
|
||||
|
||||
“采纳”只是把建议带入输入框、计划草稿或任务操作，不让 Supervisor 直接执行。
|
||||
|
||||
### 13.2 会话输入区
|
||||
|
||||
会话输入区可以提供当前会话监督的快捷入口，但不是监督能力的唯一入口，也不控制工作栏中
|
||||
已经固定到其他对象的监督目标：
|
||||
|
||||
```text
|
||||
监督：关闭 / 综合 / 质疑 / 证据 / 目标 / 风险
|
||||
```
|
||||
|
||||
这是持久二元启用加方向选择：
|
||||
|
||||
- 是否启用使用共享 Switch，`role="switch"`。
|
||||
- 方向使用 `SegmentedControl` 或上下文单选菜单。
|
||||
- 不把开关和方向做成一组含义不清的页签。
|
||||
|
||||
### 13.3 关注状态
|
||||
|
||||
会话或任务列表显示未解决意见数量和最高严重度，不能只用颜色。
|
||||
只有 `request_review`、高风险警告或确定性暂停触发全局通知。
|
||||
|
||||
## 14. 解决流程
|
||||
|
||||
```text
|
||||
open
|
||||
→ acknowledged
|
||||
→ resolved
|
||||
→ dismissed
|
||||
→ false_positive
|
||||
```
|
||||
|
||||
- `acknowledged`：用户已查看，尚未解决。
|
||||
- `resolved`：用户或后续运行说明已处理。
|
||||
- `dismissed`：不采纳，但不一定是误报。
|
||||
- `false_positive`：明确标记判断不正确。
|
||||
|
||||
后续监督输入可以包含未解决意见摘要，已解决意见默认不重复提醒。
|
||||
|
||||
## 15. 与任务控制的关系
|
||||
|
||||
Supervisor 建议“暂停”时：
|
||||
|
||||
1. 创建 `request_review`。
|
||||
2. 在任务自身的会话界面显示原因和证据。
|
||||
3. 用户选择继续、暂停、调整目标或取消。
|
||||
4. 用户操作进入任务审计。
|
||||
|
||||
确定性门禁暂停时：
|
||||
|
||||
1. Run 进入 `paused` 或 `waiting_approval`。
|
||||
2. 显示规则、阈值和实际值。
|
||||
3. 只有满足规则或用户完成对应审批后才能恢复。
|
||||
4. 模型评论不能覆盖门禁。
|
||||
|
||||
## 16. 与记忆的关系
|
||||
|
||||
- 监督评论默认保存在监督记录，不属于长期记忆。
|
||||
- 用户采纳后可以手动创建记忆候选。
|
||||
- “事实错误”“用户偏好”等监督判断不能自动写入 Project 或 Global。
|
||||
- 多次被用户标记误报的模式进入监督评估数据，不直接改变 Prompt。
|
||||
- 监督器可以读取绑定范围内的已确认记忆，但必须在证据中标明记忆来源。
|
||||
|
||||
## 17. 数据模型建议
|
||||
|
||||
```ts
|
||||
type SupervisorSession = {
|
||||
id: string
|
||||
projectId?: string
|
||||
targetType: 'conversation' | 'task' | 'automation_run' | 'experiment'
|
||||
targetId: string
|
||||
enabled: boolean
|
||||
mode: 'general' | 'challenge' | 'evidence' | 'goal' | 'risk'
|
||||
triggerPolicy: SupervisorTriggerPolicy
|
||||
budget: SupervisorBudget
|
||||
}
|
||||
|
||||
type SupervisorRecord = {
|
||||
id: string
|
||||
sessionId: string
|
||||
source: 'deterministic' | 'model'
|
||||
decision: SupervisorDecision
|
||||
status:
|
||||
| 'open'
|
||||
| 'acknowledged'
|
||||
| 'resolved'
|
||||
| 'dismissed'
|
||||
| 'false_positive'
|
||||
createdAt: string
|
||||
resolvedAt?: string
|
||||
}
|
||||
```
|
||||
|
||||
证据关系建议独立表或有界结构化 JSON，并在读取时重新验证对象归属。
|
||||
|
||||
## 18. 安全与隐私
|
||||
|
||||
1. Supervisor 使用独立可信系统指令，所有观察输入视为不可信数据。
|
||||
2. 默认不给 Supervisor 任何工具。
|
||||
3. 即使后续提供只读证据工具，也只能读取绑定对象和明确范围。
|
||||
4. Supervisor 不接收 Runtime 授权回调，不能请求工具批准。
|
||||
5. 普通会话监督失败不影响主回答；自动化配置的强制监督失败进入明确关注状态。
|
||||
6. 评论和通知不包含完整私人消息，证据点击后才在原对象中查看。
|
||||
7. Renderer 传入的 Evidence ID 必须由 Main 重新验证归属。
|
||||
8. 删除会话时按产品数据保留策略删除或匿名化监督记录。
|
||||
9. 用户关闭监督后停止新分析，但保留历史，除非用户明确删除。
|
||||
|
||||
## 19. 性能与预算
|
||||
|
||||
- Supervisor 使用独立后台并发池，默认全局并发 1。
|
||||
- 前台回复完成后异步运行，不延迟主回答呈现。
|
||||
- 同一会话同时只运行一次监督分析，新事件合并为下一次分析。
|
||||
- 普通会话每 30 秒最多自动分析一次。
|
||||
- 自动化按步骤或关键事件节流。
|
||||
- 达到 Supervisor 预算时显示“监督已暂停”，不继续产生费用。
|
||||
|
||||
## 20. 实施顺序
|
||||
|
||||
1. 定义监督会话、记录、证据和解决状态。
|
||||
2. 上线普通会话手动检查和右侧评论流。
|
||||
3. 增加每次回复后异步监督、节流和预算。
|
||||
4. 接入任务和自动化的确定性观察。
|
||||
5. 增加目标、证据和无进展模型检查。
|
||||
6. 接入实验协议一致性监督。
|
||||
7. 建立误报和有用性评估，不自动改 Prompt。
|
||||
|
||||
## 21. 验收标准
|
||||
|
||||
- [ ] 监督默认关闭，用户可对单个会话显式启用。
|
||||
- [ ] Supervisor 只读取当前对象的有界可见事件。
|
||||
- [ ] 隐藏推理、密钥和未授权内容不进入监督输入。
|
||||
- [ ] 每条中高严重度意见都有可点击证据。
|
||||
- [ ] 无证据推测不会显示为高严重度事实。
|
||||
- [ ] 模型监督不能自动暂停、终止、批准工具或替用户发言。
|
||||
- [ ] 确定性门禁不依赖模型判断即可阻止越权和超预算行为。
|
||||
- [ ] 主会话回答不等待后台 Supervisor 完成。
|
||||
- [ ] 用户可采纳、忽略、标记误报和解决意见。
|
||||
- [ ] 监督评论默认不进入长期记忆。
|
||||
- [ ] 自动化强制监督不可用时明确请求关注，不假装检查通过。
|
||||
- [ ] Supervisor 预算耗尽后停止新调用并显示状态。
|
||||
@@ -0,0 +1,12 @@
|
||||
# DeepSeek Harness Runtime
|
||||
|
||||
本功能定义 DeepSeek Harness 作为 GoodBuddy 本机 Agent Runtime 的产品接入、控制面、
|
||||
插件市场、权限和打包边界。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [技术设计](./technical-design.md) | Runtime 产品与技术方案、协议、插件、打包、测试和验收 |
|
||||
|
||||
现有文档同时包含部分 PRD、功能逻辑和进度内容，后续修改该 Runtime 时再按标准职责拆分。
|
||||
@@ -0,0 +1,778 @@
|
||||
# GoodBuddy 自维护 DeepSeek Harness Runtime 设计
|
||||
|
||||
## 1. 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 文档状态 | 实现与发布验收基线 |
|
||||
| 设计目标 | 将 DeepSeek Harness 作为 GoodBuddy 的第三个 Agent Runtime |
|
||||
| Runtime 标识 | `deepseek-harness` |
|
||||
| 当前依赖基线 | 实际使用的 `@deepseek-ai/dsh-*` 底层库，精确锁定 `0.1.0-rc.8` |
|
||||
| 上游状态 | Developer Preview，允许出现破坏性变更 |
|
||||
| 上游许可证 | MIT |
|
||||
| GoodBuddy 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
|
||||
| 本文性质 | 设计与发布验收约定 |
|
||||
|
||||
本文定义 DeepSeek Harness 在 GoodBuddy 中的架构边界、协议、执行策略、插件市场、界面、打包和验收要求。实现必须继续遵守 GoodBuddy 已有的 Main 进程安全边界、Ask/Execute 语义、取消、超时、有界输出和资源回收约定。
|
||||
|
||||
## 2. 摘要
|
||||
|
||||
DeepSeek Harness 的底层库使用 Cordis 组合服务。GoodBuddy 不采用官方产品 profile，也不允许用户配置覆盖内部 Host 或控制服务；GoodBuddy 自行维护 Host、控制协议和生命周期，同时提供一个由 Main 管理、默认关闭的 npm 插件市场。用户显式开启后，市场只搜索带精确 `dsh-plugin` 关键字的公共 npm 包，不代表 GoodBuddy 审核、推荐或承诺兼容这些包。
|
||||
|
||||
用户明确安装并启用的插件以当前用户权限运行。Ask/Execute 只控制模型经过 `tools/execute` 发起的工具调用：Ask 只允许 Host 中真实注册的 `read`、`skill` 和 Main 管理的 Web Search/Fetch 代理，Execute 放行 Host 中全部已注册工具。插件不能用同名工具冒充 Ask 允许项。插件安装脚本和初始化代码不属于模型工具调用，不能由 Ask 限制，因此界面在安装前必须明确确认这一边界。
|
||||
|
||||
整体分成两个互相约束的部分：
|
||||
|
||||
1. **GoodBuddy Main Control Plane**
|
||||
- 运行在 Electron Main 进程。
|
||||
- 持有加密设置、模型连接选择、Ask 只读策略、Runtime 生命周期、插件市场状态和审计归属。
|
||||
- 通过 Electron `utilityProcess` 启动受控 Harness 子进程。
|
||||
- 对环境、输入、输出、超时、取消和进程树执行强制限制，并只把已启用插件的受管入口传给 Host。
|
||||
|
||||
2. **GoodBuddy Harness Control Plane**
|
||||
- 运行在 Harness 子进程内，是 Host 私有的内部控制组件，不导出 Cordis 插件入口。
|
||||
- 使用 ACP 兼容的 JSON-RPC stdio 作为基础控制面。
|
||||
- 增加 GoodBuddy 所需的能力握手、每轮权限准备、会话释放、工具事件、推理、用量和安全凭据请求扩展。
|
||||
- 与 GoodBuddy Host 一起维护、构建和发布，不设计为独立 npm 包或市场插件；第三方插件只作为显式配置加载。
|
||||
|
||||
DeepSeek Harness 不替换 OpenCode、Continue 或直连模型 Runtime。用户可以按全局、项目、会话或消息通道继续选择现有 Runtime。
|
||||
|
||||
## 3. 背景与上游能力
|
||||
|
||||
### 3.1 已确认的官方能力
|
||||
|
||||
- `@deepseek-ai/dsh` 是官方 profile 启动器。
|
||||
- Harness 插件是导出 `apply(ctx, config)` 的 Cordis 模块。
|
||||
- npm 包可通过 `dsh.bundle` 声明配置补丁，再通过 `dsh plugin --profile <name> add <package>` 安装。
|
||||
- ACP 支持：
|
||||
- 初始化。
|
||||
- 创建多个会话。
|
||||
- 发送 Prompt。
|
||||
- 按会话取消。
|
||||
- 一次性权限选择。
|
||||
- 已提交的助手文本。
|
||||
- 官方本地沙箱支持：
|
||||
- Linux：Bubblewrap，或 Landlock 降级。
|
||||
- macOS：Seatbelt。
|
||||
- Windows：ACL 受限令牌，官方明确标记为部分强制执行。
|
||||
|
||||
GoodBuddy 不组合上述 Runtime OS 沙箱。当前产品选择 DSH 本地 Shell 与
|
||||
Filesystem Provider，以 GoodBuddy 客户端进程的当前用户权限运行工具。
|
||||
|
||||
### 3.2 官方通道的缺口
|
||||
|
||||
官方 ACP 插件有意只输出已提交文本，不输出推理、工具进度、计划、标题和用量。它也没有标准的会话关闭方法。SDK JSON-RPC 的展示事件更完整，但缺少 GoodBuddy 需要的单轮取消和权限回传。
|
||||
|
||||
因此，首版不单独选用其中一个官方通道作为完整实现。GoodBuddy Harness Control Plane 以 ACP 语义为基础，补充有命名空间的扩展方法和事件。
|
||||
|
||||
### 3.3 自维护边界
|
||||
|
||||
GoodBuddy 自己的 Runtime 和控制面不包装成标准 DSH 插件，也不加载用户 profile 或自定义 Host。只有 GoodBuddy Main 可以启动内部 Host、选择受管插件入口并处理启动失败。公共 npm 市场是第三方扩展来源，不改变 GoodBuddy 对内部 Host、Ask/Execute 语义和协议版本的控制。
|
||||
|
||||
## 4. 目标与非目标
|
||||
|
||||
### 4.1 首版目标
|
||||
|
||||
- 增加 `deepseek-harness` Runtime，并在设置、聊天和消息通道中可选择。
|
||||
- 使用 GoodBuddy 管理的模型连接，不在 Renderer 或持久化 Harness 配置中写入 API Key。
|
||||
- 当所选模型连接明确声明支持图像输入时，允许向 DeepSeek Harness 发送有界的 JPEG/PNG；文本模型在启动 Host 或调用模型前拒绝图片。
|
||||
- Ask 模式在 Runtime 工具分发边界强制只读，阻止 Shell、写入和编辑工具。
|
||||
- 在 Web Search 能力启用时，通过 Main 代理向 Ask 与 Execute 提供有界的 `web_search` 和 `web_fetch`，Harness Utility 不持有服务凭据。
|
||||
- Execute 模式使用 DSH 本地 Provider，以当前用户权限执行文件与命令工具；工作区是默认工作目录，不是 OS 权限边界。
|
||||
- 提供默认关闭的公共 npm DSH 插件市场总开关；用户显式开启后可搜索、查看详情、精确版本安装、启用、停用、配置和移除，首次安装前明确确认当前用户权限。
|
||||
- 只加载 Main 明确传入的已启用插件；单个插件启动失败不得阻止 Host，并自动停用失败插件。
|
||||
- 允许 Skills 和自定义 MCP 显式分配给 DeepSeek Harness；自定义 MCP 只在 Execute 中通过 Main 代理。
|
||||
- 设置页可读取有界的 Host/插件原生 Tool 与 Skill 清单；Tool 元数据显示类型、来源及 Ask/Execute 可用性，并明确排除 GoodBuddy 分配的 Skills、Web/MCP 请求代理。
|
||||
- 支持多会话、同会话串行、跨会话并行。
|
||||
- 支持按请求取消、超时、会话释放和应用退出时完整回收。
|
||||
- 输出文本、推理、工具参数、工具结果、stderr 和协议队列全部有界。
|
||||
- 使用真实 OpenAI 兼容 Chat Completions 模型验证调用，而不在日志、测试产物或提交中暴露凭据。
|
||||
- 保留 Windows、macOS、Linux 的 x64 和 arm64 发布能力。
|
||||
|
||||
### 4.2 首版非目标
|
||||
|
||||
- 不替换 OpenCode、Continue 或直连模型 Runtime。
|
||||
- 不开放用户 Cordis profile、cordis.patch.yml 或 $DSH_HOME 全局补丁覆盖。
|
||||
- 不提供外部 Host、自定义 Harness Control Plane、任意本地模块路径或用户 profile 插件目录。
|
||||
- 不加载 Harness Web UI、HMR、遥测、自动更新或目录选择器。
|
||||
- 不提供 Runtime OS 沙箱模式或相关持久设置。
|
||||
- 不向 Utility 暴露 MCP 凭据或建立直连 MCP Client。只有用户明确分配给 Harness 的 MCP 工具可以通过 Main 代理调用。
|
||||
- 不在首版向 Harness 暴露 GoodBuddy 浏览器控制、知识库或 Magic Notes。
|
||||
- 不在首版支持会话恢复、Harness Subagent、后台 Job、Hook、浏览器控制或 Workflow；Web Search/Fetch 只通过 Main 代理提供，不加载 Harness 自有网页服务。上述长生命周期能力未来统一进入右侧 Runtime 监督栏，不进入 Composer 工具栏。
|
||||
- 不发布独立 npm 包，也不创建上游 PR。
|
||||
- 不为第三方插件增加权限矩阵、风险等级、逐工具审批、沙箱档位、回滚代际或兼容性背书。
|
||||
|
||||
## 5. 核心设计决策
|
||||
|
||||
### 5.1 第三个独立 Runtime
|
||||
|
||||
`deepseek-harness` 是明确的 Runtime 类型，不伪装成 `model`、`opencode` 或 `continue`。共享契约、设置迁移、Runtime 选择、检测、聊天标签、消息通道和模型用量都使用同一个稳定标识。
|
||||
|
||||
### 5.2 受控组合，不启动用户 profile
|
||||
|
||||
GoodBuddy 使用自己固定的 Harness Host 入口和只读组合模板，不调用 `dsh web`，也不启动用户已有 profile。运行时禁止以下来源参与组合：
|
||||
|
||||
- 当前工作目录的 `.env`。
|
||||
- 用户 Harness Home 的 `.env`。
|
||||
- `$DSH_HOME/cordis.patch.yml`。
|
||||
- 用户 profile 的 `cordis.patch.yml`。
|
||||
- 任意 `--patch`。
|
||||
- HMR 和 profile 驱动的动态插件安装。
|
||||
|
||||
模型名称、服务地址、工作区、Skills、MCP schema 和已启用插件的规范化入口通过严格校验的 Main 配置传给 Host。API Key 只通过受控凭据通道按需提供，不写入 YAML、命令行、Renderer 或日志。插件配置只来自 GoodBuddy 受管状态，不合并用户 profile 或全局补丁。
|
||||
|
||||
### 5.3 双层内部控制面
|
||||
|
||||
Harness 子进程内控制面不能取代 Main 控制面，Main 控制面也不能代替进程内的 Session/Tool 适配层：
|
||||
|
||||
- Harness Control Plane 最接近 Session、Agent、Tool 和 Usage seam，适合做内部协议转换与 Ask 工具拦截。
|
||||
- Main 控制面是可信安全边界，适合持有模式授权策略、加密设置、进程控制和 IPC。
|
||||
|
||||
任何一侧缺失能力握手时，Runtime 必须报告不可用，不能降级为不受控执行。
|
||||
|
||||
### 5.4 GoodBuddy 继续拥有持久会话
|
||||
|
||||
首版不启用 Harness JSONL 会话持久化和 SQLite 会话索引。原因如下：
|
||||
|
||||
- GoodBuddy 已经持久化对话、消息、活动、工具事件和用量。
|
||||
- 再写一份 Harness 日志会扩大敏感数据副本和清理范围。
|
||||
- GoodBuddy 在 Runtime 重启后可以用现有的有界历史创建新 Harness Session。
|
||||
|
||||
Harness Session 只在当前 Runtime 进程生命周期内存在。释放 GoodBuddy 会话时必须同步释放对应 Harness Agent。
|
||||
|
||||
## 6. 总体架构
|
||||
|
||||
```text
|
||||
Renderer
|
||||
│ 显式、经 schema 验证的 preload API
|
||||
▼
|
||||
Electron Main
|
||||
├─ RuntimeSettingsStore
|
||||
├─ RuntimeExtensionStore / npm Marketplace
|
||||
├─ AgentRuntimeController
|
||||
├─ RuntimeAuthorizer（Ask 拒绝 / Main 代理工具授权）
|
||||
└─ DeepSeekHarnessRuntime / Main Control Plane
|
||||
│ ACP + goodbuddy/* 扩展，stdin/stdout
|
||||
▼
|
||||
Electron utilityProcess
|
||||
└─ GoodBuddy Harness Host
|
||||
├─ 固定 Cordis 组合
|
||||
├─ GoodBuddy Harness Control Plane（内部组件）
|
||||
├─ DSH Agent 与 LLM seam
|
||||
├─ 按模型能力挂载的有界内存图片存储
|
||||
├─ 本地 Shell / Filesystem Provider
|
||||
├─ 最小工具集与 Main 代理 MCP
|
||||
└─ Main 明确启用的第三方 Cordis 插件
|
||||
│ HTTP/HTTPS
|
||||
▼
|
||||
用户选择的 OpenAI 兼容模型连接
|
||||
```
|
||||
|
||||
### 6.1 信任边界
|
||||
|
||||
| 区域 | 信任级别 | 允许持有的内容 |
|
||||
| --- | --- | --- |
|
||||
| Renderer | 不可信展示层 | 脱敏设置、状态、用户可见事件 |
|
||||
| Preload | 窄桥 | 明确方法和共享 schema |
|
||||
| Electron Main | 可信控制面 | 加密设置、模式授权策略、Runtime 生命周期 |
|
||||
| npm 安装子进程 | 第三方执行面 | 受管暂存目录、去除模型凭据的有界环境和当前用户权限 |
|
||||
| Harness utilityProcess | 不可信执行面 | 当前请求、临时凭据、受控工具、第三方插件代码和当前用户权限 |
|
||||
| Harness 工具子进程 | 最低信任 | 单次命令所需的最小环境和当前用户权限 |
|
||||
|
||||
Harness 子进程崩溃、输出异常、拒绝协议或加载错误时，Main 必须失败关闭。
|
||||
|
||||
## 7. GoodBuddy Harness Control Plane
|
||||
|
||||
### 7.1 内部组件职责
|
||||
|
||||
控制面负责：
|
||||
|
||||
- 启动 ACP 兼容的 JSON-RPC stdio 服务。
|
||||
- 创建、查找和释放 Harness Agent。
|
||||
- 在 Prompt 前应用 GoodBuddy 指定的 Ask/Execute 权限。
|
||||
- 将 DSH Session 事件转换为有界的 GoodBuddy 事件。
|
||||
- 将 LLM 用量转换为稳定的模型用量事件。
|
||||
- 根据 Main 传入的模型能力声明 ACP 图片能力，验证内联图片并转换为 DSH 的不可变 Attachment 引用。
|
||||
- 在 dispose 时先取消 Agent，再等待子 Agent 和工具清理。
|
||||
- 保证 stdout 只包含协议帧，诊断只写 stderr。
|
||||
|
||||
控制面不负责：
|
||||
|
||||
- 保存 GoodBuddy 设置。
|
||||
- 持久保存 API Key。
|
||||
- 决定 Main 的模式授权结果。
|
||||
- 直接访问 Renderer 或 Electron API。
|
||||
- 接受任意路径、外部 Host 或 profile 覆盖；插件入口只能来自 Main 的受管清单。
|
||||
- 自行上传遥测。
|
||||
|
||||
### 7.2 第三方插件加载
|
||||
|
||||
GoodBuddy 控制面自身不导出 `apply(ctx, config)`，也不提供默认 stdin/stdout 入口或可安装 manifest。第三方插件由 Main 在启动配置中逐项指定：
|
||||
|
||||
- Main 只传递受管 Store 中已启用插件的稳定 ID、规范化入口文件和 JSON 配置。
|
||||
- Launcher 与 Host 对消息结构和绝对入口路径执行严格校验；Host 解析真实路径并要求入口是普通文件。
|
||||
- Host 动态加载 Cordis 插件并等待激活，每个插件有独立的 5 秒激活超时，完整插件序列最多占用 90 秒。
|
||||
- Main 的 Host 启动预算使用 10 秒基础预算，加上每个已启用插件 5 秒激活与最多 1 秒失败清理、且整个插件序列最多占用 91 秒，再预留 2 秒保存失败插件状态；显式测试超时仍作为调用方指定的硬上限。
|
||||
- 插件按清单依次加载；导入、导出形态或激活失败只记录该插件，不阻止其他插件和 Host 启动。失败 Fiber 的清理同样有界。
|
||||
- 有限但超过预算的同步导入或同步 `apply` 在返回后按超时失败并继续加载后续插件；JavaScript 不能在同一事件循环内抢占永不返回的同步第三方代码，此时由 Main 的独立启动截止时间终止整个 Utility。
|
||||
- 失败 ID 在 ready 握手中返回 Main；Main 原子写入停用状态和启动错误。
|
||||
- 插件成功激活后可注册工具或后台生命周期逻辑。Ask 只能拦截模型工具调用，不能撤销初始化阶段已经发生的副作用。
|
||||
|
||||
GoodBuddy 不扫描任意目录、不读取用户 profile 插件清单，也不接受 Renderer 直接提供文件路径。
|
||||
插件安装、升级和移除在目录重命名前写入受管变更日志。Main 下次初始化时以持久
|
||||
Store 是否已经提交为准，确定性完成新目录或恢复旧目录，并在处理前重新验证受管
|
||||
目录、入口真实路径、符号链接和根目录包含关系。旧版 `store.json` 继续原地迁移，
|
||||
不要求用户重新安装插件。
|
||||
|
||||
## 8. 协议设计
|
||||
|
||||
### 8.1 传输
|
||||
|
||||
- stdin/stdout 使用换行分隔 JSON-RPC。
|
||||
- stdout 不得出现日志、Banner、进度条或调试输出。
|
||||
- stderr 只允许有界诊断，不得包含 Prompt、工具完整输出或凭据。
|
||||
- 每一帧、每一字段和每个请求累计输出都必须在解析前或接收时限流。
|
||||
- 图片只允许作为 ACP 内联 base64 内容传入；拒绝远程 URI，Host 不替用户获取图片 URL。
|
||||
|
||||
### 8.2 标准 ACP 方法
|
||||
|
||||
首版保留 ACP 的初始化、`session/new`、`session/prompt` 和 `session/cancel` 语义。`promptCapabilities.image` 必须与所选模型连接的 `supportsImageInput` 完全一致，不能仅根据 Provider 或模型名称猜测。标准 ACP 客户端可以使用只读默认行为，但只有完成 GoodBuddy 能力握手的客户端才能启用 Execute。
|
||||
|
||||
### 8.3 GoodBuddy 扩展
|
||||
|
||||
扩展统一使用 `goodbuddy/` 命名空间：
|
||||
|
||||
| 方法或事件 | 方向 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| `goodbuddy/handshake` | Main → Control Plane | 交换控制协议、Harness、ACP 版本和能力 |
|
||||
| `goodbuddy/session/prepare` | Main → Control Plane | 在下一次 Prompt 前设置工作模式和请求标识 |
|
||||
| `goodbuddy/session/release` | Main → Control Plane | 取消并释放指定 Session |
|
||||
| `goodbuddy/session/event` | Control Plane → Main | 文本、推理、工具、状态和用量事件 |
|
||||
| `goodbuddy/credential/resolve` | Control Plane → Main | 按已登记引用请求当前 Runtime 的临时凭据 |
|
||||
| `goodbuddy/tools/list` | Control Plane → Main | 取得 Main 管理的有界 Web 工具与当前 Execute 请求的 MCP 工具 schema |
|
||||
| `goodbuddy/tools/call` | Control Plane → Main | 校验活动请求、工作模式、参数和精确注册代理身份后调用 Main Web/MCP 工具 |
|
||||
| `goodbuddy/native/snapshot` | Main → Control Plane | 从无 Agent scope 的 Host Registry 读取有界的原生 Tool/Skill 元数据，排除 GoodBuddy 分配项与请求级代理 |
|
||||
| `goodbuddy/shutdown` | Main → Control Plane | 停止接收新请求并有序清理 |
|
||||
|
||||
Utility 启动控制协议使用版本 2，严格携带 `supportsImageInput` 与固定 8 MiB 帧上限；版本 1 或缺少该字段的启动消息失败关闭，不能让 Host 自行猜测模型能力。扩展版本独立于 ACP 版本。握手响应至少包含：
|
||||
|
||||
```ts
|
||||
type GoodBuddyHarnessCapabilities = {
|
||||
controlProtocolVersion: 1
|
||||
harnessVersion: string
|
||||
acpProtocolVersion: number
|
||||
supports: {
|
||||
cancellation: true
|
||||
sessionRelease: true
|
||||
reasoningEvents: boolean
|
||||
toolEvents: boolean
|
||||
usageEvents: boolean
|
||||
credentialResolution: true
|
||||
}
|
||||
execution: {
|
||||
mode: 'host'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
版本不兼容、必需能力缺失或 `execution.mode` 不是 `host` 时，Main 不得开始模型请求。
|
||||
|
||||
### 8.4 每轮权限准备
|
||||
|
||||
GoodBuddy 的工作模式属于每个请求，不属于 Runtime 进程全局状态。同一对话可以在 Ask 和 Execute 之间切换。因此：
|
||||
|
||||
1. `session/new` 后默认是 Ask。
|
||||
2. 每个 Prompt 前，Main 发送一次 `goodbuddy/session/prepare`。
|
||||
3. Harness Control Plane 将准备状态绑定到 `sessionId + requestId`。
|
||||
4. `session/prompt` 只能消费匹配且尚未使用的准备状态。
|
||||
5. 缺少准备状态、重复使用、请求标识不匹配时，Control Plane 直接拒绝请求。
|
||||
6. 同一 Session 只允许一个 Prompt 在途。
|
||||
|
||||
### 8.5 事件模型
|
||||
|
||||
Harness Control Plane 只发送 GoodBuddy 能稳定解释的字段：
|
||||
|
||||
- `status`：简短运行状态。
|
||||
- `text`：已提交的助手文本分片。
|
||||
- `reasoning`：可选的有界推理摘要分片。
|
||||
- `tool`：工具 ID、名称、状态和有界输入/输出摘要。
|
||||
- `model-usage`：模型、提供方、输入、输出和缓存 Token。
|
||||
- `done`：停止原因和 Session ID。
|
||||
|
||||
禁止发送原始 Cordis Context、完整环境、内部对象、堆栈中的凭据或无界 Session 日志。
|
||||
|
||||
## 9. Runtime 生命周期
|
||||
|
||||
### 9.1 进程模型
|
||||
|
||||
- 每个活动的 DeepSeek Harness Runtime 实例拥有一个 `utilityProcess`。
|
||||
- 一个进程可以承载多个 Harness Session。
|
||||
- 同一 GoodBuddy 对话的 Prompt 串行执行。
|
||||
- 不同对话可以并行，但受全局并发上限控制。
|
||||
- Runtime 设置变化时创建新实例，旧实例等待在途请求结束或在宽限期后被取消。
|
||||
|
||||
### 9.2 会话映射
|
||||
|
||||
Main 保存内存映射：
|
||||
|
||||
```text
|
||||
GoodBuddy conversationId -> Harness sessionId + process generation
|
||||
```
|
||||
|
||||
- 首次请求创建 Session。
|
||||
- 已有 Session 只发送当前 Prompt。
|
||||
- 进程重启或映射失效时，创建新 Session，并只在这一次加入 GoodBuddy 提供的有界历史。
|
||||
- 历史以明确的“不可信会话数据”结构传入，不能拼接成系统指令。
|
||||
- 用户分配的 Skill 只通过 Main 校验的包路径进入 Host，并在 Agent scope 注册；不得把 Skill 内容伪装成用户 Prompt。
|
||||
|
||||
### 9.3 取消与有界控制操作
|
||||
|
||||
- 用户取消时立即发送 `session/cancel`。
|
||||
- 取消等待有界，超时后关闭连接并终止整个 Harness 进程。
|
||||
- 初始化、握手、请求准备、权限回传和关闭分别使用独立控制超时。
|
||||
- 生产 Prompt 不设置固定墙钟总时限，由 Harness 自身协议终态或用户取消结束。测试可以
|
||||
显式注入短 Prompt 时限验证取消传播，超时错误与用户取消仍不能被宽泛 catch 抹平。
|
||||
- 取消后仍可接收并丢弃该请求的最终协议结算帧，但不得写入下一请求。
|
||||
|
||||
### 9.4 释放与退出
|
||||
|
||||
- 原生能力清单通过一次性 Runtime 探测，取得有界快照后立即 dispose，不得因浏览设置或切换项目把 Host 缓存在执行 Runtime 池中。
|
||||
- 删除或释放对话时调用 `goodbuddy/session/release`。
|
||||
- Runtime dispose 时先拒绝新请求，再取消所有 Session。
|
||||
- Harness Control Plane 完成 Agent、工具和会话清理，Host 完成 Cordis Fiber 与子进程的反向清理。
|
||||
- Main 在宽限期内等待正常退出。
|
||||
- 超时后终止 utilityProcess，并在平台允许时清理完整进程树。
|
||||
- 应用退出时中止正在运行的 npm 插件安装并终止其完整进程树，不能让 lifecycle script 在 GoodBuddy 退出后继续运行。
|
||||
- 应用退出不得因 Harness 清理无限阻塞。
|
||||
|
||||
## 10. 权限与主机执行
|
||||
|
||||
### 10.1 模式映射
|
||||
|
||||
| GoodBuddy 模式 | Host 内置与插件工具 | Main Web Search/Fetch | GoodBuddy 自定义 MCP | 行为 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Ask | 只允许 Host Registry 中真实注册的 `read` 与 `skill`；其他 Host/插件工具一律拒绝 | 能力启用时注册 Main 的精确代理对象，无逐次审批 | 不注册 | 模型工具调用保持只读 |
|
||||
| Execute | 放行 Host 中全部已注册的内置与插件工具 | 能力启用时注册 Main 代理 | 按分配注册并经过既有 RuntimeAuthorizer | 不增加插件权限层，以当前用户权限运行 |
|
||||
|
||||
### 10.2 Ask 模式
|
||||
|
||||
- Harness Control Plane 在 `tools/execute` 分发边界识别当前 Session 和在途请求。
|
||||
- 采用所有权感知的只读允许列表，只接受 Registry 中真实的 `read`、`skill` 和 Main 注册的 Web 代理对象；`write`、`edit`、Shell、MCP 及任意新插件工具默认拒绝。只比较工具名不足以授权，插件注册同名工具仍会被拒绝。
|
||||
- Ask 不注册 Main 代理的 MCP 工具。
|
||||
- Web Search/Fetch 的凭据、传输与结果限制保留在 Main；Utility 只看到有界 schema 和结果。
|
||||
- 只读不等于无限输出，读取仍受字节和工具结果上限控制。
|
||||
- 插件安装脚本和 Cordis 初始化生命周期不经过 `tools/execute`。Ask 不能把已启用第三方代码变成沙箱，也不能保证第三方代码没有启动副作用。
|
||||
|
||||
### 10.3 Execute 模式
|
||||
|
||||
- 工作区来自 Session 创建时的规范化绝对路径，并作为文件与命令工具的默认工作目录。
|
||||
- DSH 本地 Filesystem、Bash 或 PowerShell Provider 直接使用 GoodBuddy 客户端当前用户的 OS 权限。
|
||||
- 工作区不是 containment 边界；绝对路径和命令可访问当前用户本来有权访问的主机资源。
|
||||
- 已启用插件注册的工具与内置工具使用同一分发路径；GoodBuddy 不增加插件权限矩阵或逐工具确认。
|
||||
- Main 代理的 MCP 工具继续执行分配、schema、活动请求、模式和 RuntimeAuthorizer 校验。
|
||||
- 所有工具调用仍作为活动事件记录；Ask 和 delegation 路径继续固定拒绝。
|
||||
|
||||
### 10.4 Runtime OS 沙箱
|
||||
|
||||
- GoodBuddy 不加载 DSH 平台 Sandbox Provider，也不执行启动沙箱探测。
|
||||
- “安全与数据”不提供 Runtime OS 沙箱开关。
|
||||
- 握手明确报告 `execution.mode = 'host'`，状态文案明确说明工具使用当前用户权限。
|
||||
- Electron Renderer、Preload、Browser Session 等应用安全沙箱不在本设计变更范围内。
|
||||
|
||||
### 10.5 环境与凭据
|
||||
|
||||
- 使用环境变量白名单构造 utilityProcess 环境。
|
||||
- 不继承 `NODE_OPTIONS`、调试端口、任意 npm 配置、用户 `DSH_*` 覆盖或白名单之外的凭据。
|
||||
- `DSH_TELEMETRY_DISABLED=1` 必须固定设置。
|
||||
- Harness Home 指向 GoodBuddy 管理的隔离目录。
|
||||
- 不调用官方 `loadEnv` 或 `loadLayeredEnv`。
|
||||
- API Key 由 Main 从加密设置中解析。
|
||||
- Harness Control Plane 只能用已握手登记的引用通过 `goodbuddy/credential/resolve` 请求当前 Runtime 的凭据。
|
||||
- 凭据只在模型请求所需的子进程内存中短暂存在，不写磁盘、不进入工具环境、不打印。
|
||||
- npm 安装使用同一环境白名单并移除模型 Provider 凭据；安装脚本仍拥有当前用户的文件、进程和网络权限。
|
||||
|
||||
## 11. 受控 Harness 组合
|
||||
|
||||
首版只加载完成文本对话、受控代码操作和用户明确分配能力所需的固定服务：
|
||||
|
||||
- Agent、Session、LLM 和 Tool Registry 基础服务。
|
||||
- GoodBuddy Harness Control Plane。
|
||||
- OpenAI 兼容 Chat Completions LLM 适配器。
|
||||
- 仅在所选模型声明图片能力时挂载的进程内 Attachment Store；它完整解码图片、校验格式/尺寸/摘要，以内容寻址引用保存，并随 Session 或 Host 释放。
|
||||
- DSH 本地 Subprocess、Filesystem 和平台 Shell Provider。
|
||||
- Token Meter 和必要的上下文压缩。
|
||||
- 有界的读取、写入、编辑和 Shell 工具。
|
||||
- Agent scope 的 Skill Registry 与 `skill` 工具。Skill 目录由 Main 选择并在 Launcher 和 Host 两次规范化、校验。
|
||||
- Main 代理的 Web 与 MCP schema 工具。Utility 不持有 Web/MCP URL、凭据或 Transport。
|
||||
- Main 明确传入的第三方 Cordis 插件及其 JSON 配置。
|
||||
|
||||
首版明确不加载：
|
||||
|
||||
- Web UI、HMR、Host API 和目录选择器。
|
||||
- Harness 遥测。
|
||||
- Settings File 和 Local Credentials。
|
||||
- 用户 profile 与全局补丁。
|
||||
- Harness 自有 Web Search/Fetch、Utility 直连 Web/MCP、Hooks。
|
||||
- Subagent、Workflow、Ralph、后台 Job。
|
||||
- JSONL Session Persistence 和 SQLite Session Query。
|
||||
- 自动技能发现、任意目录扫描和 profile 市场状态。
|
||||
|
||||
如果某个首版工具依赖被排除服务，启动审计必须失败，而不是自动加载更大的默认 bundle。
|
||||
|
||||
## 12. 模型配置
|
||||
|
||||
### 12.1 配置来源
|
||||
|
||||
DeepSeek Harness 首版只使用符合下列边界的 GoodBuddy 模型连接：
|
||||
|
||||
- 协议必须是 `openai-chat-completions`。
|
||||
- 认证必须是 API Key。
|
||||
- 服务地址支持 HTTP 和 HTTPS，不根据主机位置、端口、凭据、查询参数或片段增加额外限制。
|
||||
- 模型名称不限制为 DeepSeek 品牌，由所选 OpenAI 兼容服务决定。
|
||||
- 模型名称和服务地址由 Main 传入受控 Host。
|
||||
- 图片能力只读取所选 GoodBuddy 模型连接的 `supportsImageInput`；Main、Utility 启动配置、ACP 能力和 Pi-AI 模型输入模态必须使用同一个布尔值。
|
||||
- API Key 继续保存在 GoodBuddy 加密设置中。
|
||||
- 启动环境提供的部署连接只由 Main 自动解析，不在 Renderer 中显示为可选来源。
|
||||
|
||||
不允许选择 Harness 自有的用户配置文件或自定义 Host。Runtime 始终使用随当前 GoodBuddy 版本发布的内置 Host，并通过完整内部能力握手。
|
||||
|
||||
### 12.2 设置变化
|
||||
|
||||
模型、凭据、Skill、MCP 分配或插件安装、启停、配置、移除变化时，GoodBuddy 创建新 Runtime 实例。Harness Host 路径始终由当前 GoodBuddy 构建提供，不能由设置或环境变量替换。旧实例按现有 Runtime Controller 语义退役，不在一个活动进程内热替换配置。
|
||||
|
||||
### 12.3 输入限制
|
||||
|
||||
- 文本始终可用；图片是否可用完全取决于所选模型连接是否显式声明 `supportsImageInput: true`。
|
||||
- 文本模型收到图片时必须在启动 Host 或发起模型网络调用前返回明确错误，不能静默丢弃图片。
|
||||
- 图片模型只接受内联 JPEG/PNG，不接受 URL、文件路径、ACP `uri` 或其他媒体类型。
|
||||
- Main 已通过 `nativeImage` 解码用户选择的图片并生成有界模型输入；Utility 仍须独立执行严格 base64、签名、容器结构、CRC（PNG）、完整解码、尺寸和摘要校验，不能把 Main 校验当作跨进程信任替代。
|
||||
- 每条消息最多 8 张图，单图编码后最多 1 MiB，图片合计最多 2 MiB，单边最长 8,192 px，单图最多 1,600 万像素，累计解码像素最多 3,200 万（重复引用也计入预算）。进程内 Store 另设 32 MiB、256 个唯一对象的总上限。
|
||||
- Attachment Store 只服务当前非持久 Harness Session；引用按 Session 释放，Host 退出时清空，不写入磁盘或 GoodBuddy 第二份会话日志。
|
||||
- GoodBuddy 历史、Prompt、系统指令分别保持不同信任层。
|
||||
- 任何用户文本都不能进入 Cordis 配置表达式或模块名。
|
||||
|
||||
## 13. 输出和资源边界
|
||||
|
||||
建议首版默认限制：
|
||||
|
||||
| 项目 | 默认上限 |
|
||||
| --- | --- |
|
||||
| 单个 JSON-RPC 帧 | 8 MiB |
|
||||
| 单图 / 单条消息图片 | 1 MiB / 8 张且合计 2 MiB |
|
||||
| 单图尺寸 / 单条消息解码像素 | 单边最长 8,192 px 且 1,600 万像素 / 3,200 万像素 |
|
||||
| Host 临时图片存储 | 32 MiB 且最多 256 个唯一对象 |
|
||||
| 单个文本或推理事件 | 64 KiB |
|
||||
| 单次请求累计协议输出 | 4 MiB |
|
||||
| 工具输入摘要 | 4,000 字符 |
|
||||
| 工具输出摘要 | 4,000 字符 |
|
||||
| 待处理事件数 | 1,000 |
|
||||
| stderr 累计 | 64 KiB |
|
||||
| Host 启动 | 10 秒基础预算 + 每插件 5 秒激活与最多 1 秒失败清理，插件序列最多 91 秒；Main 另预留 2 秒持久化失败状态 |
|
||||
| ACP 初始化与内部握手 | 每阶段 10 秒 |
|
||||
| 单次 Prompt | 无固定墙钟总时限，由 Harness 终态或用户取消结束 |
|
||||
| 有序关闭宽限期 | 2 秒 |
|
||||
|
||||
超过限制时应取消当前请求。协议帧、队列或 stderr 持续异常时，应终止 Runtime 进程，避免继续信任已失控的通道。
|
||||
|
||||
## 14. Runtime 检测与状态
|
||||
|
||||
### 14.1 检测
|
||||
|
||||
检测只验证：
|
||||
|
||||
- 内置 Host 路径是规范化文件。
|
||||
- 版本可读取且在支持范围内。
|
||||
- 内部控制面能力握手成功。
|
||||
|
||||
检测不得调用付费模型，也不得读取或输出 API Key。真实模型测试是单独的显式操作。
|
||||
|
||||
### 14.2 设置界面
|
||||
|
||||
Agent Runtime 使用共享 `SegmentedControl` 展示 OpenCode、Continue 和 DeepSeek Harness。DeepSeek Harness 必须标记为“开发者预览”，并说明上游 RC 可能发生破坏性变更。
|
||||
|
||||
Runtime 的概览、模型配置和检测信息放在同一张详情卡中。当前单独显示的一行“已就绪”应移入卡片，与路径、版本号归为同一组：
|
||||
|
||||
```text
|
||||
Runtime： GoodBuddy 内置 DeepSeek Harness
|
||||
模型配置： 跟随 GoodBuddy · 企业网关（qwen-plus）
|
||||
状态： 已就绪
|
||||
路径： <受控 Host 路径>
|
||||
版本： 0.1.0-rc.8
|
||||
执行权限： 当前用户权限
|
||||
|
||||
Host 始终由当前 GoodBuddy 版本提供，不存在自定义 Host 入口。
|
||||
```
|
||||
|
||||
界面要求：
|
||||
|
||||
- 不再在卡片外重复一行检测结果。
|
||||
- 使用语义化键值结构，路径允许换行，不截断关键信息。
|
||||
- 状态不能只依靠绿色表达，必须同时有文字。
|
||||
- 检测中和不可用分别显示明确文案。
|
||||
- 高级设置默认收起。
|
||||
- DSH 插件市场提供共享 Switch 样式的总开关并默认关闭。关闭时不请求公共 npm 目录且隐藏市场管理界面，但不修改已有插件的逐项启停状态；因此已启用插件继续随 Host 加载，重新开启后恢复原有管理状态。
|
||||
- 同一 Runtime 页面提供紧凑的 DSH 插件市场：客户端筛选名称、包名、描述和许可证，已安装插件优先显示。
|
||||
- 安装前使用一个明确 Checkbox 确认 npm 安装脚本、插件初始化和 Execute 工具均使用当前用户权限；不展示权限矩阵或逐工具审批。
|
||||
- 已安装插件使用共享 Switch 启停，并提供 JSON 配置、明确移除确认和启动失败信息。
|
||||
- npm 目录离线时仍显示并允许管理已安装插件；目录错误就地显示并可重试。
|
||||
- 安装、启停、配置和移除的短期结果通过应用通知显示，不重复保留页内成功提示。
|
||||
- DSH 不提供独立的“允许图片”开关。Runtime 连接选择只引用“模型连接”中维护的图片能力声明，避免同一模型出现两份冲突配置。
|
||||
|
||||
聊天顶栏只显示简短 Runtime 状态，不显示文件路径和版本。完整诊断只在设置页展示。
|
||||
|
||||
### 14.3 Agent Runtime 交互表面归属
|
||||
|
||||
OpenCode、Continue 和 DeepSeek Harness 的后续能力按操作生命周期放置，不按上游产品分别堆叠入口：
|
||||
|
||||
| 表面 | 负责内容 | 不负责内容 |
|
||||
| --- | --- | --- |
|
||||
| Composer 通用行 | 附件、语音、知识范围、专家、Ask/Execute、Runtime 和发送 | Session 监督、后台进度、历史任务管理 |
|
||||
| Composer Runtime 专属行 | 仅对当前消息生效且需要高频选择的 Agent、预设、Prompt/Command 快捷操作 | Task 级委派、后台执行、Workflow/Hook 生命周期 |
|
||||
| 助手工作栏固定“Runtime”栏目 | 用户所选 Conversation 或 Task 的 Runtime 状态、Task 级委派与取消、后台执行进度/结果、Workflow/Hook 运行、长任务暂停/恢复/终止和会话监督；不显示 Job/Run 树 | 持久模型、程序路径、默认 Agent/预设配置 |
|
||||
| 设置 > Agent Runtime | 持久 Runtime 配置、默认值、插件管理、能力清单和连接诊断 | 某次活动会话的实时控制 |
|
||||
|
||||
Runtime 栏目入口始终存在，并采用统一监督模型；内部再按用户所选目标及其 Runtime 的真实能力
|
||||
显示 OpenCode、Continue 或 DSH 的具体区域。未支持能力不渲染空卡片或一排禁用按钮，而是
|
||||
在用户需要理解缺口时显示原因和可执行入口。跟随模式切换 Runtime、Conversation 或 Task
|
||||
时必须清理上一归属的聚合执行状态，固定目标则保持不变。完整工作栏契约见
|
||||
[通用助手工作栏与执行空间 PRD](../assistant-workbar/prd.md)。
|
||||
|
||||
所有未来的 Subagent、Job、Workflow、Hook 和会话操作仍须经过 Main 的 Runtime 边界，保留取消、超时、权限、Task/Job/Subjob 层级、用量和活动审计。高风险动作在侧栏就地确认，运行结果进入活动与成果记录，不以 Composer 按钮代替监督面板。DeepSeek Harness 首版仍不加载这些服务，本节只确定未来跨 Runtime 的产品位置和协议归属。
|
||||
|
||||
## 15. IPC 与共享契约
|
||||
|
||||
共享 schema 需要覆盖：
|
||||
|
||||
- `deepseek-harness` provider 和 Runtime ID。
|
||||
- Runtime 选择中的 `deepseekHarness` 分支。
|
||||
- 检测结果中的路径、版本、详情和主机执行模式。
|
||||
- GoodBuddy 模型连接选择。
|
||||
- 从所选模型连接解析并传到 Host 的 `supportsImageInput`，以及 ACP 图片能力的一致性。
|
||||
- DeepSeek Harness 模型用量归属。
|
||||
- Skill 与 MCP 对 `deepseek-harness` 的显式分配。
|
||||
- 插件市场总开关、目录、已安装状态、启停状态、JSON 配置和有界启动错误。
|
||||
- 插件 `set-marketplace-enabled`、`install`、`set-enabled`、`configure`、`remove` 五类严格 action。
|
||||
|
||||
Renderer 只接收公开 npm 元数据和受管插件状态。任何凭据、完整环境、npm 子进程参数、内部 Host 配置或任意插件文件路径都不能由 Renderer 提交；安装 action 只能引用当前目录中的精确包名与版本。
|
||||
|
||||
已有设置迁移必须：
|
||||
|
||||
- 对没有新字段的用户使用安全默认值。
|
||||
- 新建或没有已安装插件的旧 Store 将市场迁移为关闭；已有安装记录的旧 Store 保持开启，避免升级后隐藏用户正在管理的插件。
|
||||
- 保留 OpenCode、Continue 和模型连接选择。
|
||||
- 修复失效的 DeepSeek Harness 模型引用时给出可报告的迁移警告。
|
||||
- 不把旧 Runtime 自动迁移为 DeepSeek Harness。
|
||||
|
||||
## 16. 打包与供应链
|
||||
|
||||
### 16.1 版本策略
|
||||
|
||||
- 官方 RC 包全部精确锁定，不使用 `^` 或 `~`。
|
||||
- 同一 Harness 核心包族必须保持同一 RC 版本。
|
||||
- 升级前检查 release diff、协议 diff、工具执行语义和依赖闭包。
|
||||
- 内部握手同时检查锁定的 Harness 基线和 GoodBuddy 控制协议版本。
|
||||
|
||||
### 16.2 插件市场安装
|
||||
|
||||
- 目录来自 npm 公共搜索 API，只保留包含精确 `dsh-plugin` 关键字的包，最多读取 1,000 项并短期缓存。
|
||||
- 安装时再次读取精确版本 packument，不信任搜索结果替代版本清单。
|
||||
- GoodBuddy 精确锁定并随发布包携带 npm `11.19.0`；Electron 以 `ELECTRON_RUN_AS_NODE=1` 启动该 CLI 和受管 `node` shim，不要求用户另装 Node.js 或 npm。
|
||||
- npm 使用普通依赖解析并运行包及依赖声明的 lifecycle scripts。安装确认必须准确说明这些脚本以当前用户权限运行。
|
||||
- 安装在 Store 的暂存目录中完成，校验包名、精确版本、`dsh.bundle` 声明、入口文件和 lockfile integrity 后才原子替换当前版本。
|
||||
- 市场关闭时拒绝新安装且不请求目录，但 `getEnabledExtensions()` 继续按逐项启停状态返回已安装插件。
|
||||
- 首次安装默认启用。更新保留既有启停状态和 JSON 配置；失败更新保留原安装。
|
||||
- 每个插件只有一个受管目录和一条状态记录；Store 同时持久化市场总开关。状态写入原子化且 mutation 串行。
|
||||
- JSON 配置限制为对象根、64 KiB、16 层、每个容器 256 项和 4,096 个节点，避免 IPC、持久化和 Host 启动载荷无界增长。
|
||||
- Renderer 不接收受管入口路径；Main 只接受目录中的插件 ID 与精确包版本，不能由 IPC 指定 tarball URL、文件路径或命令。
|
||||
|
||||
### 16.3 原生依赖
|
||||
|
||||
受控组合可能需要：
|
||||
|
||||
- `node-pty`，用于受管理的工具子进程。
|
||||
- `koffi`，用于本地 Filesystem 在 Windows 上保持文件 ACL 和原子替换。
|
||||
- `@napi-rs/canvas` 及当前平台二进制，用于在 Utility 内完整解码并复核 JPEG/PNG；原生模块必须从 ASAR 解包并通过目标架构校验。
|
||||
|
||||
构建 GoodBuddy 自身时不得广泛批准依赖安装脚本；只允许生产组合实际需要、来源已审查、版本已锁定的脚本。这与用户确认后由市场插件执行自身 lifecycle scripts 是两个不同阶段。六个平台的构建必须验证：
|
||||
|
||||
- 对应架构的原生文件存在。
|
||||
- Electron Utility Process 可加载原生模块。
|
||||
- spawn helper 的权限正确。
|
||||
- 包中没有混入其他平台不需要的可执行内容，除非上游包无法拆分且已记录。
|
||||
|
||||
### 16.4 生产闭包
|
||||
|
||||
发布包包含受控 Host、锁定的 npm 安装 Runtime 和许可证。应尽量避免把 Harness Web profile、HMR 和其他未加载产品面带入生产闭包。若 npm 依赖结构无法拆分，必须：
|
||||
|
||||
- 确认这些模块不会被加载。
|
||||
- 评估它们带来的 audit 和体积风险。
|
||||
- 在后续上游版本允许时改为最小包族。
|
||||
- 确认 `tests/fixtures` 以及 Web3D 测试 Skill/MCP 不进入正式发布资源。
|
||||
|
||||
### 16.5 漏洞门禁
|
||||
|
||||
当前安装后的 `npm audit` 报告不能直接用 `npm audit fix --force` 处理。每项漏洞需要区分：
|
||||
|
||||
- GoodBuddy 既有依赖。
|
||||
- Harness 新增生产依赖。
|
||||
- 仅开发或打包依赖。
|
||||
- 未加载但被带入的 Web 依赖。
|
||||
|
||||
进入 Harness 执行路径且有可利用条件的高危问题必须在发布前修复、替换或移出生产闭包。
|
||||
|
||||
### 16.6 发布验证
|
||||
|
||||
`build/build-release.cjs` 需要验证：
|
||||
|
||||
- Harness Host 和受控配置存在。
|
||||
- GoodBuddy Host、内部控制协议与 Harness 依赖版本清单存在。
|
||||
- 平台原生 PTY/Koffi 依赖架构正确。
|
||||
- Harness、ACP SDK 和其他新增第三方许可证已打包。
|
||||
- `app.asar` 外需要执行或动态加载的资源位于预期目录。
|
||||
- 独立的 npm Runtime 及其捆绑依赖闭包存在，并可通过当前 Electron Node Runtime 启动和执行生命周期脚本。
|
||||
- Web3D Skill/MCP 等测试 fixture 不在 `app.asar` 或 `extraResources` 中。
|
||||
|
||||
## 17. 测试策略
|
||||
|
||||
### 17.1 单元测试
|
||||
|
||||
- Runtime 选择、设置迁移和失效引用修复。
|
||||
- 二进制检测、版本解析和路径规范化。
|
||||
- ACP 握手、事件转换和请求关联。
|
||||
- 每个会话单请求、跨会话并行。
|
||||
- Ask 在工具分发边界只允许真实注册的 `read`、`skill` 与 Main Web 代理，并拒绝同名冒充和任意新插件工具；Execute 放行插件工具。
|
||||
- 握手只接受明确的 `execution.mode = 'host'`。
|
||||
- 未分配 Skill/MCP 不可见；分配后的 Skill catalog 可调用 `skill` 加载。
|
||||
- 原生能力快照只包含 Host/插件原生 Skills，不包含 GoodBuddy 分配的 Skills 或 MCP。
|
||||
- Ask 不注册 MCP 工具；Web 代理可用于 Ask 与 Execute；Execute 每轮刷新有界 MCP schema，并在调用前再次校验活动请求、模式、参数和 RuntimeAuthorizer 结果。
|
||||
- MCP URL、启动命令和凭据不进入 Utility 启动配置或协议结果。
|
||||
- 未知授权结果失败关闭。
|
||||
- 超时、取消、迟到帧和进程意外退出。
|
||||
- 协议帧、事件队列、工具摘要和 stderr 上限。
|
||||
- 文本模型在 Host 启动前拒绝图片；图片模型的能力声明、ACP 图片块、Pi-AI 模态和 Attachment Store 保持一致。
|
||||
- 图片 base64、格式签名、PNG CRC、完整解码、尺寸、单图/单消息/Store 上限、内容摘要、Session 释放和 Host 清空。
|
||||
- release 和 dispose 的幂等性。
|
||||
- 状态卡中的状态、路径、版本和当前用户执行权限。
|
||||
- 插件 action 与目录 schema 接受严格的市场总开关并拒绝权限、回滚、任意路径和非精确版本等未支持字段。
|
||||
- Store 的原子安装、失败更新保留、串行 mutation、离线管理、配置、移除和启动失败停用。
|
||||
- npm 分页、精确关键字、捆绑 CLI 调用、lifecycle 参数、包身份、入口和 integrity 校验。
|
||||
- Renderer 的搜索、权限确认、Switch、JSON 配置、移除确认、离线目录和通知反馈。
|
||||
|
||||
### 17.2 本地集成测试
|
||||
|
||||
使用无网络的假控制面/模型验证：
|
||||
|
||||
- utilityProcess 管道。
|
||||
- 多 Session。
|
||||
- Session 释放。
|
||||
- Runtime 替换。
|
||||
- 进程树回收。
|
||||
- 本地 Filesystem 与 Shell Provider 使用规范化工作区作为默认工作目录，且不报告沙箱强制模式。
|
||||
- 受控配置不会读取工作区 `.env` 和用户 DSH 配置。
|
||||
- 插件导入或激活失败相互隔离，成功插件继续加载，失败 ID 返回 Main。
|
||||
- IPC 只接受严格插件 action，可信 Renderer 操作后触发 Runtime 重建。
|
||||
|
||||
### 17.3 真实模型测试
|
||||
|
||||
真实测试已经获得用户授权，但必须由显式环境门禁启用。Web3D Skill 和 MCP 仅作为 `tests/fixtures` 下的测试资产使用，不属于内置发布能力。至少验证：
|
||||
|
||||
1. 文本问答成功，并记录正确 Runtime 和模型用量。
|
||||
2. Ask 可以读取工作区，但写入被拒绝，且不会弹出权限对话框。
|
||||
3. 启用 Web Search 后，Ask 可以调用 Main 管理的 `web_search` 与 `web_fetch`，插件同名工具仍被拒绝。
|
||||
4. Execute 可以在工作区创建测试文件。
|
||||
5. Execute 工具确实以当前用户权限运行，且状态和握手不宣称 OS 隔离。
|
||||
6. Ask、delegation 和无活动请求不能绕过工具分发检查。
|
||||
7. 取消长请求后不再产生文本，并可继续使用其他 Session。
|
||||
8. 两个 Session 可并行，事件不会串线。
|
||||
9. 释放会话和关闭应用后没有残留 Harness 或工具进程。
|
||||
10. 从全新用户设置流程启用一个 3D 游戏 Skill 和实际本地或开放 MCP，工具事件能够证明二者确实被调用。
|
||||
11. Harness 生成的 3D 游戏项目可以安装、启动和实际游玩，包含 3D 渲染、玩家控制、目标和反馈，浏览器无关键错误。
|
||||
12. 使用公共 npm 搜索，通过 GoodBuddy 捆绑的 npm 安装经审查的最小第三方插件，Host 成功加载并执行其真实工具。
|
||||
13. 实际 ACP 路径中 Ask 拒绝该插件工具，Execute 允许该工具，不出现 GoodBuddy 逐工具确认。
|
||||
|
||||
测试不得打印、快照或提交 API Key。测试创建的文件只能位于专用临时工作区，并在确认可再现后清理。
|
||||
|
||||
### 17.4 项目验证
|
||||
|
||||
源码完成后必须运行：
|
||||
|
||||
```text
|
||||
npm test
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm run build
|
||||
```
|
||||
|
||||
涉及发布资源后，还要按可用原生平台运行聚焦的 `release:package` 验证。无法在当前主机执行的目标必须由六平台 CI 验证。
|
||||
|
||||
## 18. 验收标准
|
||||
|
||||
功能只有同时满足以下条件才算完成：
|
||||
|
||||
- `deepseek-harness` 可被保存、选择、检测和显示。
|
||||
- Runtime 详情卡内显示状态、路径、版本和当前用户执行权限。
|
||||
- Skills 与自定义 MCP 设置可把能力分配给 DeepSeek Harness；请求级 GoodBuddy 内置 MCP 当前不支持分配，并在内置 MCP 卡片中以置灰、未选择状态明确显示。布局、键盘语义、文案和保存回显通过真机检查。
|
||||
- DSH 市场初始关闭且不加载 npm 目录；显式开启后可以搜索、安装、启停、配置和移除插件，安装前只出现一次准确的当前用户权限确认。关闭市场后已有启用插件继续运行，重新开启后管理状态不变。
|
||||
- Ask 写入测试在 Runtime 边界失败。
|
||||
- Ask 可使用已启用的 Main Web Search/Fetch，且插件无法通过同名工具绕过所有权校验。
|
||||
- Ask 拒绝任意插件工具，Execute 可调用全部已启用插件工具。
|
||||
- Runtime 原生清单只显示 Host/插件原生 Skills，不显示 GoodBuddy 分配项。
|
||||
- Execute 工作区内写入成功。
|
||||
- Runtime OS 沙箱设置、平台 Runner、启动探测和原生沙箱打包产物均不存在。
|
||||
- 取消、超时、切换 Runtime 和退出应用均能回收进程。
|
||||
- 多会话不串流、不串权限请求、不串用量。
|
||||
- 用户 DSH 配置、`.env`、遥测和 Web UI 未被加载。
|
||||
- 一个插件启动失败时 Host 仍可用，失败插件自动停用并在设置中显示。
|
||||
- 发布包携带可执行的锁定 npm CLI，安装插件不依赖系统 Node.js/npm。
|
||||
- API Key 不进入 Renderer、配置文件、日志、错误文本或测试产物。
|
||||
- 全量测试、类型检查、Lint 和生产构建通过。
|
||||
- 真实 OpenAI 兼容 Chat Completions 请求成功。
|
||||
- 真实请求调用已分配 Skill 和 MCP，并生成、启动和实际游玩一个可用的 3D 游戏项目。
|
||||
- 新增第三方许可证和发布校验完整。
|
||||
|
||||
## 19. 已知限制
|
||||
|
||||
- DeepSeek Harness 底层库当前是 RC，但 GoodBuddy 不自动跟随升级；每次升级都可能要求同步修改内部控制面。
|
||||
- Harness 文件和命令工具没有 Runtime OS 隔离，会继承 GoodBuddy 客户端当前用户能够访问的主机资源。
|
||||
- 首版不恢复 Harness 原生 Session，Runtime 重启后由 GoodBuddy 历史重建。
|
||||
- 图片输入仅在所选模型连接明确声明支持时可用；首版仍不支持知识库、浏览器控制和 Harness Subagent。Web Search/Fetch 仅使用 Main 代理，MCP 仅支持用户分配、Main 代理和 Execute 自动单次授权路径。
|
||||
- Harness Subagent、后台 Job、Workflow、Hook 和原生会话监督尚未实现；未来按 Task 聚合到右侧 Runtime 监督栏，不扩张 Composer 工具栏或暴露 Job/Run 层级。
|
||||
- 推理、工具和用量扩展属于 GoodBuddy 协议，不是标准 ACP 保证。
|
||||
- 市场来自公共 npm 关键字搜索，不是精选目录；包的质量、兼容性和维护状态由发布者负责。
|
||||
- 插件安装、初始化、后台生命周期和 Execute 工具使用当前用户权限，不受 Runtime OS 沙箱保护；Ask 只控制模型工具调用。
|
||||
- 不支持用户 profile、自定义 Host、任意本地插件路径或 profile patch。
|
||||
|
||||
## 20. 自维护与升级策略
|
||||
|
||||
GoodBuddy 对该 Runtime 采用内部维护策略：
|
||||
|
||||
1. 当前通过验证的 Host、控制协议和依赖锁定随 GoodBuddy 一起版本化。
|
||||
2. 不自动跟随 DSH RC、插件 ABI、profile 格式或市场元数据变化；目录只反映 npm 当前精确版本。
|
||||
3. 升级前审查实际用户收益、上游 diff、主机工具语义、协议行为、依赖闭包和许可证。
|
||||
4. 六个平台的单元、假模型、UtilityProcess、主机执行和真实模型门禁全部通过后才能更新基线。
|
||||
5. 若上游方向不再满足 GoodBuddy 用户需求或安全边界，允许维护兼容补丁、替换单个底层包，或逐步移除 DSH 依赖；`goodbuddy/*` 内部协议保持由 GoodBuddy 控制。
|
||||
6. GoodBuddy 自身不以进入官方插件目录或服务非 GoodBuddy 客户端为目标；第三方市场兼容仅限当前受测 Cordis 导出和 `dsh.bundle` 声明。
|
||||
|
||||
## 21. 备选方案记录
|
||||
|
||||
### 21.1 每次调用 `dsh --profile headless`
|
||||
|
||||
未采用。它适合一次性任务，但不能满足流式事件、多会话、细粒度取消、权限回传和低延迟复用。
|
||||
|
||||
### 21.2 只使用官方 ACP 插件
|
||||
|
||||
未采用。取消和一次性权限选择符合需求，但缺少工具、推理、用量和会话释放事件。
|
||||
|
||||
### 21.3 只使用官方 SDK JSON-RPC
|
||||
|
||||
未采用。事件更完整，但单轮取消和权限回传能力不足。
|
||||
|
||||
### 21.4 把全部安全逻辑放进 Harness 子进程
|
||||
|
||||
未采用。Harness 子进程属于不可信执行面，不能拥有最终模式授权策略、加密设置和进程回收权限。
|
||||
|
||||
### 21.5 把全部控制适配放在 Main
|
||||
|
||||
未采用。Main 无法可靠观察 Cordis 内部 Session、Tool、Usage 和权限 seam，只能得到不完整的外部进程行为。
|
||||
|
||||
当前选择让双层内部控制面保持 GoodBuddy 私有，同时允许 Main 从受管 Store 向固定 Host 注入标准 Cordis 插件；插件扩展面不会取代 GoodBuddy 的可信 Main 控制权。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 文档处理
|
||||
|
||||
文档处理负责聊天附件和知识库导入中的文本提取、格式转换与本地 OCR。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [文档解析与本地 OCR PRD](./prd.md) | 产品范围、解析策略、OCR 模型管理和验收 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
@@ -0,0 +1,343 @@
|
||||
# 文档解析与本地 OCR
|
||||
|
||||
## 1. 目标
|
||||
|
||||
GoodBuddy 需要用同一条可信文档解析链路服务以下场景：
|
||||
|
||||
- 聊天附件问答；
|
||||
- 知识库导入、同步、分块与来源定位；
|
||||
- 后续的合同审阅、表格分析、演示文稿理解和文档转换。
|
||||
|
||||
文档解析不是对话模型的附属功能。它是主进程管理的独立基础能力，设置入口为“设置中心 / 文档解析”。
|
||||
本地 OCR 的模型下载源以
|
||||
[平台功能页签与模型下载源设计](../../architecture/model-download-source-design.md)为准。
|
||||
|
||||
## 2. 当前基线
|
||||
|
||||
原生解析器已经支持：
|
||||
|
||||
- UTF-8 文本、代码、配置、HTML；
|
||||
- 带文本层的 PDF；
|
||||
- DOCX 正文；
|
||||
- XLSX 工作表 XML 与共享字符串；
|
||||
- PPTX 幻灯片文字。
|
||||
|
||||
现有局限：
|
||||
|
||||
- 纯扫描 PDF 没有文本层时无法提取内容；
|
||||
- DOC、XLS、PPT 等旧版二进制 Office 格式不支持；
|
||||
- Office 解析主要提取文字，不能完整保留表格、公式、图表和版面；
|
||||
- 聊天附件和知识库直接调用底层解析函数，缺少可配置的统一工作流；
|
||||
- 没有本地 OCR 模型状态、真实解析测试和按场景策略。
|
||||
|
||||
## 3. 产品原则
|
||||
|
||||
### 3.1 双通道解析
|
||||
|
||||
PDF 不是所有文档唯一的中间格式。解析应同时保留：
|
||||
|
||||
1. 原生语义通道：标题、段落、单元格、公式、备注和对象关系；
|
||||
2. 渲染视觉通道：页码、版面、图表、图片和 OCR 结果。
|
||||
|
||||
两条通道合并为统一文档结构。转换为 PDF 用于补充视觉信息，不得覆盖更可靠的原生语义结果。
|
||||
|
||||
### 3.2 场景工作流
|
||||
|
||||
| 场景 | 默认预设 | 行为 |
|
||||
| --- | --- | --- |
|
||||
| 聊天附件 | 自动解析 | 优先快速提取，文本不足时按需 OCR，有界截断后加入当前请求 |
|
||||
| 知识库导入 | 完整索引 | 完整解析、按页或工作表定位、按需 OCR、分块与索引 |
|
||||
| 扫描文档 | OCR | 页面渲染、文字识别、置信度与定位保留 |
|
||||
| 表格分析 | 语义优先 | 单元格和值优先，PDF 或图片补充图表与打印布局 |
|
||||
| 高保真审阅 | 视觉增强 | 原生解析、页面渲染、OCR 或视觉理解合并 |
|
||||
|
||||
### 3.3 本地优先
|
||||
|
||||
- 文本层和本地 OCR 均在设备上处理；
|
||||
- 本地处理不因 Ask 或 Execute 模式改变；
|
||||
- OCR 来源必须在“本地模型 / 远程服务”之间明确选择；
|
||||
- 配置并保存远程服务即表示用户选择该处理路径，不再增加逐场景授权；
|
||||
- API 密钥只能保存在主进程加密设置中；
|
||||
- 测试文件不得自动进入聊天或知识库。
|
||||
|
||||
## 4. 设置设计
|
||||
|
||||
设置中心新增“文档解析”分类，结构如下：
|
||||
|
||||
1. 分类页头：“测试解析”“保存设置”；
|
||||
2. 运行状态：原生解析、文档转换、本地 OCR；
|
||||
3. 使用场景：聊天附件、知识库导入；
|
||||
4. 文档转换；
|
||||
5. OCR 识别；
|
||||
6. 高级解析设置；
|
||||
|
||||
OCR 模型区沿用语音模型管理模式：
|
||||
|
||||
- 应用不内置模型权重；
|
||||
- 用户按需从全局选择的 ModelScope 或 Hugging Face 下载，默认 ModelScope，下载完成后
|
||||
离线使用；
|
||||
- 显示来源、语言、运行时、模型体积、安装与校验状态；
|
||||
- 联网设备可导出已安装模型 ZIP，离线或内网设备可直接导入；
|
||||
- 支持下载进度、取消、删除、ZIP 导入导出、打开模型仓库和受管目录；
|
||||
- “打开模型仓库”直接显示在 OCR 模型卡片右上角，并使用当前下载源对应仓库；
|
||||
- 模型操作即时生效，解析策略仍通过分类页头的“保存设置”提交。
|
||||
|
||||
### 4.1 第一阶段字段
|
||||
|
||||
- 聊天附件预设：`auto`、`fast-text`、`high-fidelity`；
|
||||
- 知识库预设：`complete-index`、`fast-index`、`high-fidelity`；
|
||||
- PDF OCR 策略：`auto`、`always`、`disabled`；
|
||||
- OCR 来源：第一阶段固定为 `local`，远程服务入口禁用；
|
||||
- 本地 OCR 模型：`pp-ocrv6-tiny`、`pp-ocrv6-small`、`pp-ocrv6-medium`；
|
||||
- 单文档最大页数；
|
||||
- OCR 并发数；
|
||||
- 单页超时。
|
||||
|
||||
OCR 来源使用互斥选择。本地模型选中后才显示模型下拉列表、按需下载、导入和本地 OCR 参数；远程服务计划接入 MinerU、PaddleOCR-VL 等接口，第一阶段保持可读但禁用。来源选择本身就是用户的明确决策，不再显示额外的“隐私与云端处理”授权区。
|
||||
|
||||
## 5. 架构
|
||||
|
||||
```text
|
||||
聊天附件 ─┐
|
||||
├─ DocumentParsingService
|
||||
知识库导入 ┘ ├─ NativeDocumentParser
|
||||
├─ PdfTextQualityEvaluator
|
||||
├─ PdfPageRenderer
|
||||
├─ LocalOcrProvider
|
||||
├─ DocumentConversionProvider
|
||||
└─ ParsedDocument merger
|
||||
```
|
||||
|
||||
`DocumentParsingService` 是唯一场景入口：
|
||||
|
||||
```ts
|
||||
type DocumentParsingPurpose = 'chat-attachment' | 'knowledge-index'
|
||||
|
||||
type DocumentParsingService = {
|
||||
parse(
|
||||
name: string,
|
||||
bytes: Buffer,
|
||||
purpose: DocumentParsingPurpose,
|
||||
signal?: AbortSignal
|
||||
): Promise<ParsedDocument>
|
||||
}
|
||||
```
|
||||
|
||||
聊天上下文管理器与知识库服务依赖该接口，不直接选择 OCR Provider。
|
||||
|
||||
## 6. 统一结果
|
||||
|
||||
第一阶段兼容现有 `ParsedDocument`，并逐步扩展：
|
||||
|
||||
```ts
|
||||
type ParsedDocument = {
|
||||
title: string
|
||||
sourceFormat: string
|
||||
content: string
|
||||
sections: Array<{
|
||||
locator: string
|
||||
content: string
|
||||
method?: 'native' | 'ocr' | 'converted' | 'vision'
|
||||
confidence?: number
|
||||
}>
|
||||
warnings?: string[]
|
||||
}
|
||||
```
|
||||
|
||||
定位字段必须对使用者有意义：
|
||||
|
||||
- PDF：`第 3 页`；
|
||||
- XLSX：`工作表：预算 / A1:F28`；
|
||||
- PPTX：`幻灯片 5`；
|
||||
- DOCX：标题路径或页码；
|
||||
- 文本：`全文`。
|
||||
|
||||
## 7. 本地 OCR 基线
|
||||
|
||||
### 7.1 模型与运行时
|
||||
|
||||
全平台功能基线：
|
||||
|
||||
- 模型：PP-OCRv6 ONNX/ORT；
|
||||
- 轻量下载档位：Tiny，约 6 MiB，用于低资源设备和六平台离线链路；
|
||||
- 推荐下载档位：Small，约 30 MiB，官方支持 50 种语言；
|
||||
- 高精度下载档位：Medium，约 132 MiB，官方支持 50 种语言，但识别较慢且需要更多内存；
|
||||
- 运行时：ONNX Runtime WebAssembly；
|
||||
- 处理环境：隔离 Worker；
|
||||
- 加速：WebGPU 或平台原生执行 Provider，仅作为可选层；
|
||||
- 回退：任何加速失败后使用 WASM CPU。
|
||||
|
||||
需要覆盖的发布矩阵：
|
||||
|
||||
- Windows x64、Windows arm64；
|
||||
- macOS x64、macOS arm64；
|
||||
- Linux x64、Linux arm64。
|
||||
|
||||
模型清单必须固定以下信息：
|
||||
|
||||
- 上游仓库和不可变 revision；
|
||||
- 文件名、字节数和 SHA-256；
|
||||
- 模型族、语言、质量和速度；
|
||||
- 许可证名称、完整许可证和来源；
|
||||
- 检测模型、识别模型、字符字典的匹配关系。
|
||||
|
||||
运行时不得从 `main`、`latest` 或其他可变地址加载模型。
|
||||
|
||||
### 7.2 下载与安装
|
||||
|
||||
Tiny、Small 和 Medium 模型使用 PaddlePaddle 发布的规范工件。GoodBuddy 为 ModelScope
|
||||
和 Hugging Face 分别维护固定下载 Target，默认使用 ModelScope。Small 是默认推荐档位；
|
||||
Medium 面向更高识别质量，但具有更高内存占用和延迟。每个档位的检测模型、识别模型与
|
||||
字符字典配置分别使用固定提交，并在应用内记录各来源解析后的文件字节数和 SHA-256。
|
||||
当前 OCR 两个来源的对应文件字节一致；共享下载契约同时支持后续来源声明不同的固定
|
||||
工件指纹。
|
||||
|
||||
下载流程：
|
||||
|
||||
1. 主进程读取已保存的全局模型下载源，并解析该来源的固定 Target；
|
||||
2. 禁用凭据与缓存，限制重定向次数和单文件大小；
|
||||
3. 写入受管目录下的随机临时安装目录；
|
||||
4. 边下载边计算 SHA-256，并核对完整字节数；
|
||||
5. 三个文件全部通过校验后写入安装清单；
|
||||
6. 原子重命名为正式模型目录；
|
||||
7. 失败、取消或退出时删除临时文件。
|
||||
|
||||
单次任务只使用启动时冻结的一个来源。所选来源不可用或缺少任一必需文件时明确失败，
|
||||
不请求另一个来源。模型只在下载或用户显式打开仓库时访问网络。OCR 推理从受管目录读取
|
||||
已校验文件，不发起网络请求。
|
||||
|
||||
### 7.3 离线 ZIP 迁移
|
||||
|
||||
语音模型和 OCR 模型使用同一种离线迁移流程：
|
||||
|
||||
1. 联网设备完成受信任来源下载和校验；
|
||||
2. 在模型卡片选择“导出 ZIP”；
|
||||
3. 将 ZIP 通过组织批准的介质传输到离线或内网设备；
|
||||
4. 在相同模型的卡片选择“导入 ZIP”；
|
||||
5. 主进程按当前应用内置目录重新校验，并在全部通过后原子安装。
|
||||
|
||||
ZIP 根目录包含模型文件和 `goodbuddy-model.json`。清单格式为 `goodbuddy-model-archive`，当前版本为 `1`，记录：
|
||||
|
||||
- 模型类型：`speech` 或 `document-ocr`；
|
||||
- 内置模型 ID 和显示名称；
|
||||
- 文件名、角色、原始字节数和 SHA-256；
|
||||
- 导出时间。
|
||||
|
||||
导出不能直接信任已有安装清单，必须重新读取并校验每个文件。导入不能只信任 ZIP 自声明内容，模型 ID、文件角色、字节数和哈希必须再次完整匹配当前应用内置目录的默认包或任一来源包；不接受逐文件跨来源组合。导入通过后复用普通本地安装的受控临时目录和原子重命名路径。
|
||||
|
||||
归档处理使用有界流式读写，不把大型模型或整个展开结果复制到内存。主进程限制压缩包大小、条目数、清单大小、单文件大小和总展开大小，并拒绝：
|
||||
|
||||
- 绝对路径、`..`、目录或嵌套路径；
|
||||
- 大小写不敏感的重复条目；
|
||||
- 未声明、缺失或角色不匹配的文件；
|
||||
- 模型类型或模型 ID 不匹配；
|
||||
- 解压后大小或 SHA-256 不匹配；
|
||||
- 超过边界的压缩包和压缩炸弹。
|
||||
|
||||
取消文件对话框不会改变安装状态。导入和导出也不会切换当前语音/OCR 模型，不会隐式保存文档解析设置。
|
||||
|
||||
### 7.4 PDF 流程
|
||||
|
||||
1. 使用 PDF.js 读取每页文本层；
|
||||
2. 评估有效字符数、乱码率和图片占比；
|
||||
3. `auto` 模式只渲染文本不足的页面；
|
||||
4. `always` 模式渲染所有页面；
|
||||
5. Worker 将页面限制在配置的最大边长内；
|
||||
6. OCR 返回文字、坐标和置信度；
|
||||
7. 按页合并原生文本与 OCR，不重复可靠文本；
|
||||
8. 达到页数、超时、取消或输出限制时停止并返回明确错误。
|
||||
|
||||
受密码保护、损坏或超限的 PDF 不得进入 OCR。
|
||||
|
||||
## 8. Office 与转换
|
||||
|
||||
### 8.1 新格式
|
||||
|
||||
- DOCX：正文、标题、表格、批注和图片关系；
|
||||
- XLSX：工作表、单元格地址、值、公式、合并关系和图表；
|
||||
- PPTX：幻灯片、文字对象、备注、图片和阅读顺序。
|
||||
|
||||
Office 内嵌图片 OCR 属于增强流程，不能替代原生结构解析。
|
||||
|
||||
### 8.2 旧格式
|
||||
|
||||
DOC、XLS、PPT 通过 `DocumentConversionProvider` 转换：
|
||||
|
||||
1. 转换为 DOCX、XLSX 或 PPTX，供语义解析；
|
||||
2. 转换为 PDF，供页码、版面和视觉解析；
|
||||
3. 合并结果并记录转换警告。
|
||||
|
||||
本地 LibreOffice Provider 必须：
|
||||
|
||||
- 在隔离子进程中运行；
|
||||
- 禁用宏和网络；
|
||||
- 使用单任务临时目录；
|
||||
- 限制输入大小、输出大小、内存和超时；
|
||||
- 在成功、失败、取消和退出时清理；
|
||||
- 不接受用户提供的任意命令参数。
|
||||
|
||||
## 9. 安全边界
|
||||
|
||||
- 文件路径解析、读取、大小检查和格式校验在主进程完成；
|
||||
- OCR Worker 只接收当前任务所需的有界页面图像和只读模型；
|
||||
- 不向 Worker 暴露文件系统、Electron API、凭据或任意网络访问；
|
||||
- 文档内容视为不可信数据，不解释其中的提示词为系统指令；
|
||||
- 模型和转换程序必须固定版本并校验哈希；
|
||||
- OCR 输出受字符数限制，错误不得包含绝对路径或未脱敏文档内容；
|
||||
- 取消、超时和应用关闭必须终止待处理页面并释放模型会话。
|
||||
|
||||
## 10. 错误与回退
|
||||
|
||||
必须区分：
|
||||
|
||||
- 不支持的格式；
|
||||
- 文档损坏或受密码保护；
|
||||
- 文本层为空但 OCR 未启用；
|
||||
- OCR 模型不可用；
|
||||
- OCR 超时或取消；
|
||||
- 文档页数、大小或输出超限；
|
||||
- 本地转换服务未配置；
|
||||
- 所选远程 OCR 服务不可用或配置不完整。
|
||||
|
||||
`auto` 工作流可以从 OCR 回退到可靠的原生文本，但不能把空结果标记为成功。知识库导入失败时保留来源和可重试上下文。
|
||||
|
||||
## 11. 实施阶段
|
||||
|
||||
### 阶段一
|
||||
|
||||
- 新增文档解析设置分类和持久化契约；
|
||||
- 建立 `DocumentParsingService`，供聊天和知识库共用；
|
||||
- 将无文本 PDF 识别为可触发 OCR 的明确状态；
|
||||
- 接入 PP-OCRv6 Tiny、Small、Medium 的双来源下载、校验、ZIP 离线迁移、删除与
|
||||
WASM Worker；
|
||||
- 实现真实文件测试和六平台验证入口。
|
||||
|
||||
### 阶段二
|
||||
|
||||
- 增强 DOCX、XLSX、PPTX 语义结构；
|
||||
- 实现按页混合文本层与 OCR；
|
||||
- 增加版面、表格和阅读顺序。
|
||||
|
||||
### 阶段三
|
||||
|
||||
- 增加 LibreOffice 和 API 转换 Provider；
|
||||
- 支持 DOC、XLS、PPT；
|
||||
- 增加 MinerU、PaddleOCR-VL 等远程 OCR 服务连接配置；
|
||||
- 增加高保真工作流和解析结果预览。
|
||||
|
||||
## 12. 验收
|
||||
|
||||
- 同一份扫描 PDF 可从聊天附件和知识库得到一致的逐页文本；
|
||||
- 文本型 PDF 在 `auto` 模式下不运行 OCR；
|
||||
- 本地 OCR 在六个平台和两种架构上完全离线运行；
|
||||
- 模型文件损坏时拒绝加载并显示可恢复错误；
|
||||
- 未安装模型时扫描文档提示用户前往“文档解析”下载，文本型文档仍可原生解析；
|
||||
- 下载中可显示文件与总进度并允许取消，失败或取消后不留下已安装状态；
|
||||
- ModelScope、Hugging Face 下载与 ZIP 导入均经过同一大小和 SHA-256 校验；
|
||||
- 所选下载源失败或缺少模型时不会请求另一个来源；
|
||||
- 语音和 OCR 模型可在联网设备导出 ZIP，并在离线设备导入后完成真实推理；
|
||||
- 路径穿越、未知条目、错误模型 ID、篡改文件和超限 ZIP 均被拒绝；
|
||||
- 超页数、超时、取消和关闭不会留下运行任务；
|
||||
- 测试解析不会创建聊天消息或知识库文档；
|
||||
- 选择本地模型时没有任何文档上传；
|
||||
- 文档中的提示词不会改变系统、模式或工具权限。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 全双工语音
|
||||
|
||||
全双工语音定义持续听说、打断、语音活动检测、本地与远端推理以及多平台音频边界。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [技术设计](./technical-design.md) | 产品目标、交互流程、音频架构、模型、打包和实施状态 |
|
||||
|
||||
现有文档是综合设计，尚未按 PRD、User Stories、功能逻辑、UI 和进度职责拆分。
|
||||
@@ -0,0 +1,944 @@
|
||||
# GoodBuddy 全双工实时语音交互设计
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 文档类型 | 跨功能技术与产品架构 |
|
||||
| 状态 | 设计中 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-08-19 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
|
||||
| 相关基线 | [长期助手路线图](../../roadmap/long-term-assistant-roadmap.md)、[统一界面设计系统](../../../UI-DESIGN.md) |
|
||||
|
||||
本文定义 GoodBuddy 中类似自然通话的全双工实时语音能力，包括本地与云端语音引擎、
|
||||
音频平面、会话状态、打断语义、工具审批、数据留存、失败恢复、跨平台交付和验收指标。
|
||||
|
||||
本文所称“支持本地与云端”是指用户可以显式配置并选择不同语音引擎，不代表系统可以在
|
||||
它们之间自动切换。**GoodBuddy 不设计静默降级。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 摘要与核心决策
|
||||
|
||||
1. 实时语音是独立的 `VoiceSession`，不把现有一次性语音听写改名后直接复用。
|
||||
2. 系统支持三种显式引擎：
|
||||
- 本地模块化全双工：本地流式 ASR、所选 Agent Runtime、本地流式 TTS。
|
||||
- 本地原生全双工：一个本地端到端语音模型同时听、想和说。
|
||||
- 云端原生全双工：通过供应商 Realtime/Live API 进行双向流式音频交互。
|
||||
3. 用户开始会话时冻结引擎、Provider、模型、版本、地域、数据位置、声音、能力和
|
||||
Turn Detection 配置。会话过程中不得静默替换。
|
||||
4. 同一目标内允许有界重试、网络抖动恢复和语义等价的内部执行优化；任何会改变
|
||||
Provider、模型、数据位置、成本、隐私、能力、质量或可感知延迟的替代路径都必须显式。
|
||||
5. 所选引擎不可用时，会话明确进入 `blocked` 或 `failed`，保留可恢复上下文，并提供
|
||||
“重试当前引擎”或“结束后选择其他引擎”。不自动切换本地/云端，不退回听写、纯文本或
|
||||
非全双工模式。
|
||||
6. Renderer 负责麦克风采集、回声消除、低延迟播放和即时打断；Main 负责凭据、会话
|
||||
控制、Provider Adapter、工具权限、持久化和资源回收。
|
||||
7. 音频帧不进入普通 `AgentEvent` 和聊天消息持久化通道。默认只保存最终文本、会话状态和
|
||||
有界诊断，不保存原始录音。
|
||||
8. 语音不能成为新的授权通道。Ask 继续只读，Execute 的工具调用继续经过现有审批控件。
|
||||
|
||||
---
|
||||
|
||||
## 2. 背景与当前基础
|
||||
|
||||
GoodBuddy 当前已经具备：
|
||||
|
||||
- Renderer 中的麦克风入口、录音状态和取消操作。
|
||||
- `getUserMedia` 的单声道采集、回声消除和噪声抑制。
|
||||
- 将完整录音重采样为 16 kHz PCM 的能力。
|
||||
- 基于 `sherpa-onnx` 的本地离线识别、模型下载、ZIP 迁移、选择和删除。
|
||||
- Main 中受信任发送者校验、Zod IPC 输入校验、超时、取消和应用关闭回收。
|
||||
- `AgentRuntime.run()` 的流式文本、工具事件、审批、取消和会话持久化。
|
||||
- Renderer 中的流式聊天时间线、全局通知和可访问的输入控件。
|
||||
|
||||
当前链路仍是：
|
||||
|
||||
```text
|
||||
点击麦克风
|
||||
→ 最多录音 20 秒
|
||||
→ 停止并一次性发送完整 PCM
|
||||
→ 本地离线转写
|
||||
→ 把文本插入输入框
|
||||
→ 用户再次确认发送
|
||||
```
|
||||
|
||||
该链路适合听写，但不具备：
|
||||
|
||||
- 连续流式识别和临时转写。
|
||||
- 同时采集与播放。
|
||||
- 自动轮次检测。
|
||||
- 助手语音输出。
|
||||
- 用户抢话和响应截断。
|
||||
- 音频队列、背压和时钟同步。
|
||||
- 实时语音 Provider 抽象。
|
||||
- 语音会话快照和诊断。
|
||||
|
||||
因此实时语音必须新增会话层，而不是在现有 `SpeechTranscriptionService` 后面简单追加 TTS。
|
||||
|
||||
---
|
||||
|
||||
## 3. 目标
|
||||
|
||||
### 3.1 用户目标
|
||||
|
||||
- 用户可以像通话一样持续说话，不需要每轮点击开始和停止。
|
||||
- 助手可以边生成边说，并显示与实际播放进度一致的文本。
|
||||
- 用户开口时可以自然打断，助手在很短时间内停止出声并开始听取新内容。
|
||||
- 用户始终知道当前使用本地还是云端、具体引擎是什么、音频或转写文本会去哪里。
|
||||
- 本地或云端引擎失败时，用户能看到准确状态并决定下一步，不被系统暗中换模型。
|
||||
- 语音对话继续拥有文本聊天中的项目、知识库、角色、Ask/Execute、工具审批和历史能力。
|
||||
|
||||
### 3.2 产品目标
|
||||
|
||||
- 在六个平台/架构目标上提供统一的上层会话契约。
|
||||
- 先以现有 `sherpa-onnx` 和 Agent Runtime 构建可跨平台交付的本地模块化引擎。
|
||||
- 允许云端 Provider 使用 WebRTC 或 WebSocket，但不把供应商协议泄漏到通用 UI。
|
||||
- 允许高性能设备安装本地原生全双工模型，但按真实能力检测决定是否可选。
|
||||
- 保持 Main-only 凭据、上下文隔离、沙箱、取消、超时、有界输出和关机回收。
|
||||
- 为延迟、打断、回声、音频中断、Provider 错误和成本提供可诊断指标。
|
||||
|
||||
---
|
||||
|
||||
## 4. 非目标
|
||||
|
||||
首期不包含：
|
||||
|
||||
- 唤醒词、后台常驻监听或应用退出后的麦克风采集。
|
||||
- 根据网络、负载、价格或“智能判断”自动选择语音引擎。
|
||||
- 在一个会话内自动从云端切到本地，或从本地切到云端。
|
||||
- 从原生全双工自动退到 ASR → LLM → TTS，或反向切换。
|
||||
- 在实时语音失败后自动改成一次性听写、纯文本发送或系统 TTS。
|
||||
- 默认保存、上传或训练用户原始音频。
|
||||
- 声音克隆、未成年人声音模仿、电话呼入或多人会议。
|
||||
- 使用口头“同意”替代工具审批按钮或键盘确认。
|
||||
- 绕过当前 Agent Runtime 和权限边界的 Provider 直连工具、MCP 或 Connector。
|
||||
- 保证所有本地原生语音模型都能在 CPU 或全部六个发布目标上运行。
|
||||
|
||||
---
|
||||
|
||||
## 5. 术语与全双工范围
|
||||
|
||||
| 术语 | 定义 |
|
||||
| --- | --- |
|
||||
| `VoiceEngineProfile` | 用户保存的语音引擎配置，包含类型、Provider、模型、地域、声音和能力 |
|
||||
| `VoiceSession` | 一次从用户显式开始到结束的连续实时语音会话 |
|
||||
| `VoiceTurn` | 用户输入和助手响应形成的一次可持久化对话轮次 |
|
||||
| 系统级全双工 | 麦克风在助手播放期间继续采集，用户可以随时打断 |
|
||||
| 原生模型全双工 | 同一个模型联合处理持续输入、轮次判断和持续语音输出 |
|
||||
| 模块化全双工 | ASR、Agent Runtime 和 TTS 分离，但系统保持同时听说与可打断 |
|
||||
| 临时文本 | 尚未确认的 ASR 或尚未实际播放的助手文本，不写入长期历史 |
|
||||
| 已提交文本 | 用户轮次已确认，或助手对应音频已实际播放的文本 |
|
||||
| Barge-in | 用户在助手说话时开口，触发立即静音、取消和上下文截断 |
|
||||
| 引擎快照 | 会话开始时冻结的完整、无凭据配置及能力声明 |
|
||||
|
||||
“模块化”不等同于“回退”。当用户明确选择模块化本地引擎时，它就是该会话的唯一正式
|
||||
执行路径。原生模型和模块化引擎之间没有隐式优先级。
|
||||
|
||||
---
|
||||
|
||||
## 6. 不静默降级产品契约
|
||||
|
||||
### 6.1 必须显式的变化
|
||||
|
||||
以下变化不得在活动会话中静默发生：
|
||||
|
||||
- 本地与云端之间切换。
|
||||
- Provider、Endpoint、地域或账号切换。
|
||||
- 模型 ID、模型版本、量化档位或语音角色切换。
|
||||
- 原生全双工与模块化全双工之间切换。
|
||||
- ASR、LLM 或 TTS 组件切换。
|
||||
- 从音频输入改成仅文本输入，或从语音输出改成仅文本输出。
|
||||
- 禁用原本声明可用的工具、知识库、角色或 Execute 能力后继续运行。
|
||||
- 把原始音频改为上传，或改变云端数据地域和保留策略。
|
||||
- 采用明显更慢、更低质量或成本不同的路径。
|
||||
|
||||
### 6.2 可自动进行的恢复
|
||||
|
||||
以下操作可以自动执行，但必须保持同一引擎快照：
|
||||
|
||||
- 同一连接内的丢包恢复、抖动缓冲和音频重排。
|
||||
- 同一 Provider、模型、地域和配置的有限重连。
|
||||
- 同一本地模型进程的有限重启。
|
||||
- 不改变语义、隐私、成本和已声明性能级别的算子或执行 Provider 优化。
|
||||
|
||||
恢复在用户可感知前完成时可不打断界面；持续超过 500 ms、导致音频停顿或创建新远端
|
||||
会话时，必须显示“正在重新连接当前引擎”。所有恢复都进入有界诊断记录。
|
||||
|
||||
### 6.3 失败后的用户决策
|
||||
|
||||
恢复预算耗尽后：
|
||||
|
||||
1. 停止采集上传和音频播放。
|
||||
2. 将临时文本标记为未提交，不伪装成完整轮次。
|
||||
3. 保存已提交文本和脱敏错误。
|
||||
4. 显示当前失败的引擎、影响和建议。
|
||||
5. 提供“重试当前引擎”和“结束语音会话”。
|
||||
6. 用户结束后可以显式选择其他引擎并开始新会话。
|
||||
|
||||
首期不提供自动 Failover 列表。未来即使允许用户预先配置替代引擎，也必须在切换前获得
|
||||
明确确认，并在会话中持续显示新的活动引擎。
|
||||
|
||||
### 6.4 产品级适用范围
|
||||
|
||||
本契约不仅适用于语音。GoodBuddy 中 Provider、模型、Runtime、数据处理位置、工作模式、
|
||||
权限范围和质量档位等影响隐私、成本或能力的用户选择，都不得被静默替换。
|
||||
|
||||
用户明确选择名为“自动”的策略时，系统可以在该策略事先声明的范围内选择，但实际结果和
|
||||
任何能力退化必须可见、可诊断，不能把空结果或不完整结果表示为正常成功。
|
||||
|
||||
---
|
||||
|
||||
## 7. 用户体验
|
||||
|
||||
### 7.1 入口
|
||||
|
||||
现有麦克风入口继续表示“语音输入/听写”，转写进入可编辑输入框，不自动发送。
|
||||
|
||||
实时语音使用独立的“开始语音对话”入口，避免用户误以为点击一次听写会开启持续监听。
|
||||
入口只在以下条件满足时可用：
|
||||
|
||||
- 已选择并验证一个全双工语音引擎。
|
||||
- 当前平台满足该引擎能力要求。
|
||||
- 麦克风权限可申请。
|
||||
- 当前 Conversation 没有冲突的活动请求。
|
||||
- 当前工作模式和引擎能力兼容。
|
||||
|
||||
### 7.2 会话界面
|
||||
|
||||
活动会话显示一个持续可见的语音控制区：
|
||||
|
||||
- 当前状态：准备中、正在听、用户说话、正在思考、助手说话、正在打断、等待审批、
|
||||
正在重连、失败。
|
||||
- 本地/云端徽标、引擎名称和数据去向。
|
||||
- 实时用户转写和与播放同步的助手文本。
|
||||
- 麦克风静音、结束会话和必要的设备入口。
|
||||
- 输入音量与助手播放状态，但不得只用颜色表达。
|
||||
- 云端会话的使用量或成本提示入口。
|
||||
|
||||
“结束语音会话”是活动状态下的唯一主操作。波形和头像动效遵守
|
||||
`prefers-reduced-motion`，关闭动效后仍使用文字和图标表达状态。
|
||||
|
||||
### 7.3 打断
|
||||
|
||||
助手说话期间检测到用户有效语音：
|
||||
|
||||
1. 在 Renderer 立即对当前音频执行 20–40 ms 淡出。
|
||||
2. 清空尚未播放的音频队列。
|
||||
3. 向 Main 发送包含播放位置的 `interrupt`。
|
||||
4. Main 取消当前 Agent/TTS 响应或向 Provider 发送截断事件。
|
||||
5. 尚未播放的助手文本保持临时状态并从会话上下文中移除。
|
||||
6. 输入状态切到用户说话，继续采集，不重新建立会话。
|
||||
|
||||
键盘点击“停止说话”与语音 Barge-in 使用相同取消和提交语义。
|
||||
|
||||
### 7.4 工具和审批
|
||||
|
||||
- Ask 模式继续在 Runtime 边界保持只读。
|
||||
- Execute 模式的工具调用进入现有 Approval Broker。
|
||||
- 等待审批时暂停新的助手音频，可播放一次确定性的短提示，例如“需要你确认一个操作”。
|
||||
- 工具参数、风险、范围和确认操作使用现有可访问审批控件。
|
||||
- 麦克风中的“同意”“确认”或相似内容只作为普通用户文本，不构成授权。
|
||||
- 用户拒绝或取消后，结果作为结构化工具事件返回当前引擎，不私自换模型继续。
|
||||
|
||||
### 7.5 设置结构
|
||||
|
||||
长期设置结构使用一级“语音”分类，并以 `PageTabs` 组织：
|
||||
|
||||
1. **实时对话**：语音引擎列表、默认引擎、能力、数据位置、地域、声音和真实连接测试。
|
||||
2. **语音输入**：现有本地 ASR 模型、一次性听写和麦克风设置。
|
||||
3. **语音输出**：本地 TTS 模型、声音、语速和试听。
|
||||
|
||||
当前“模型连接”中的“语音输入”可在迁移阶段保留，之后移动现有模型管理组件时必须保存
|
||||
已安装模型和选择，不创建第二份设置。
|
||||
|
||||
模型类型选择器当前已经包含四项，不增加第五个分段项来承载实时语音，以免违反
|
||||
`SegmentedControl` 的 2–4 项约束。
|
||||
|
||||
语音引擎卡片必须持续显示：
|
||||
|
||||
- 本地或云端。
|
||||
- Provider、模型和版本。
|
||||
- 支持的语言。
|
||||
- 系统级或原生模型全双工。
|
||||
- 是否支持工具、图像和当前 Ask/Execute 模式。
|
||||
- 所需硬件或云端地域。
|
||||
- 音频和文本的数据去向。
|
||||
- 安装、已验证、不可用或需要凭据状态。
|
||||
|
||||
实际生成能力只能通过一次真实、有界、由用户触发的会话测试确认。配置保存成功或只完成
|
||||
握手不能证明麦克风输入、语音输出和打断均可工作。
|
||||
|
||||
---
|
||||
|
||||
## 8. 总体架构
|
||||
|
||||
```text
|
||||
┌──────────────────────── Renderer ────────────────────────┐
|
||||
│ VoiceSession UI │
|
||||
│ getUserMedia → AudioWorklet Capture → Fast VAD │
|
||||
│ AudioWorklet Playback ← Jitter/Playback Queue │
|
||||
└────────────── control IPC ─────── media MessagePort ───────┘
|
||||
│
|
||||
┌────────────────────────── Main ────────────────────────────┐
|
||||
│ VoiceSessionController │
|
||||
│ ├─ Session snapshot and state │
|
||||
│ ├─ Turn coordinator and interruption │
|
||||
│ ├─ Tool/approval bridge │
|
||||
│ ├─ Transcript/message persistence │
|
||||
│ ├─ Credential and provider policy │
|
||||
│ └─ VoiceEngineAdapter │
|
||||
│ ├─ LocalModularAdapter │
|
||||
│ ├─ LocalNativeDuplexAdapter │
|
||||
│ └─ CloudRealtimeAdapter │
|
||||
└───────────────┬──────────────────────┬─────────────────────┘
|
||||
│ │
|
||||
Local managed sidecar Cloud Realtime API
|
||||
or bounded worker WebRTC / WebSocket
|
||||
```
|
||||
|
||||
### 8.1 Renderer 音频平面
|
||||
|
||||
Renderer 负责需要接近音频设备的低延迟操作：
|
||||
|
||||
- 在用户操作后调用 `getUserMedia`。
|
||||
- 请求单声道、回声消除、噪声抑制和受支持时的自动增益。
|
||||
- 使用 `AudioWorklet`，不继续扩展 `ScriptProcessorNode`。
|
||||
- 将音频切成 10–20 ms 有序帧，并按引擎格式重采样。
|
||||
- 执行快速本地 VAD，用于 Barge-in，不独立提交最终轮次。
|
||||
- 维护有界播放和抖动缓冲，记录实际播放采样位置。
|
||||
- 在打断、设备变化、休眠或窗口销毁时立即静音和释放资源。
|
||||
|
||||
Renderer 不持有长期 API Key、不创建本地模型目录、不决定工具权限，也不持久化原始音频。
|
||||
|
||||
### 8.2 Preload 与 IPC
|
||||
|
||||
控制面使用显式、类型化的 preload 方法：
|
||||
|
||||
- `voice.getSnapshot()`
|
||||
- `voice.startSession(input)`
|
||||
- `voice.stopSession(sessionId)`
|
||||
- `voice.setMuted(input)`
|
||||
- `voice.interrupt(input)`
|
||||
- `voice.respondApproval(...)` 继续复用现有审批接口
|
||||
- `voice.onEvent(listener)`
|
||||
|
||||
音频帧不使用逐帧 `ipcRenderer.invoke`、JSON 或 Base64。Main 通过
|
||||
`MessageChannelMain` 向可信主 Frame 传递专用 `MessagePort`，使用可转移
|
||||
`ArrayBuffer` 和严格的帧头。控制事件和媒体帧分别限速、限长和验证。
|
||||
|
||||
### 8.3 Main 控制面
|
||||
|
||||
`VoiceSessionController` 负责：
|
||||
|
||||
- 每个窗口最多一个活动语音会话。
|
||||
- 解析并冻结 `VoiceSessionSnapshot`。
|
||||
- 建立所选 Adapter，不执行自动 Adapter 选择。
|
||||
- 维护输入、输出和生命周期状态。
|
||||
- 将 Barge-in 传播到 Provider、Agent Runtime、TTS 和播放队列。
|
||||
- 桥接工具调用、审批、问题和取消。
|
||||
- 只提交已经确认或实际播放的文本。
|
||||
- 处理超时、重连预算、应用退出、系统休眠和窗口销毁。
|
||||
- 对错误和诊断执行脱敏与边界限制。
|
||||
|
||||
### 8.4 本地进程边界
|
||||
|
||||
轻量 ONNX 能力可以运行在受控 Worker。需要 Python、CUDA、Metal/MLX 或独立依赖树的
|
||||
原生模型运行在 GoodBuddy 管理的 Sidecar：
|
||||
|
||||
- 只绑定 loopback，不监听外部网卡。
|
||||
- 使用随机端口和每次启动的短期认证值。
|
||||
- 环境变量使用最小 allowlist。
|
||||
- 不继承云端 Provider 密钥。
|
||||
- 模型路径由 Main 从受管目录解析，不接受任意相对路径。
|
||||
- 启动、健康检查、并发、输出、内存、超时和进程树有界。
|
||||
- 应用退出时终止完整进程树。
|
||||
|
||||
Sidecar 不因本地模型启动失败而自行连接云端。
|
||||
|
||||
### 8.5 云端连接边界
|
||||
|
||||
供应商支持 WebRTC 时优先使用其媒体传输、编解码和抖动能力：
|
||||
|
||||
- Main 使用长期凭据创建受限、短时的会话描述或临时凭据。
|
||||
- Renderer 只接收当前会话需要的短期材料。
|
||||
- 工具和业务事件优先由 Main sideband 连接处理。
|
||||
- Provider 不支持 sideband 时，由 Main 拥有 WebSocket，并通过媒体 `MessagePort`
|
||||
与 Renderer 交换音频。
|
||||
|
||||
长期凭据永不进入 Renderer、日志、诊断或会话快照。云端 Profile 必须固定可信 Endpoint、
|
||||
地域和数据说明，不跟随重定向切换到未声明的主机。
|
||||
|
||||
---
|
||||
|
||||
## 9. 共享契约
|
||||
|
||||
建议新增 `src/shared/voice-contracts.ts`，核心结构如下：
|
||||
|
||||
```ts
|
||||
type VoiceEngineKind =
|
||||
| 'local-modular'
|
||||
| 'local-native-duplex'
|
||||
| 'cloud-native-duplex'
|
||||
|
||||
type VoiceComponentRef = {
|
||||
providerId: string
|
||||
modelId: string
|
||||
modelVersion?: string
|
||||
endpoint?: string
|
||||
region?: string
|
||||
accountRef?: string
|
||||
credentialRef?: string
|
||||
}
|
||||
|
||||
type VoiceEngineProfile = {
|
||||
id: string
|
||||
name: string
|
||||
kind: VoiceEngineKind
|
||||
locality: 'local' | 'cloud'
|
||||
voiceId: string
|
||||
components: {
|
||||
asr?: VoiceComponentRef
|
||||
tts?: VoiceComponentRef
|
||||
nativeDuplex?: VoiceComponentRef
|
||||
}
|
||||
dataPath: {
|
||||
audioDestination:
|
||||
| { kind: 'device' }
|
||||
| {
|
||||
kind: 'provider'
|
||||
providerId: string
|
||||
endpoint: string
|
||||
region?: string
|
||||
}
|
||||
transcriptDestination:
|
||||
| { kind: 'device' }
|
||||
| {
|
||||
kind: 'provider'
|
||||
providerId: string
|
||||
endpoint: string
|
||||
region?: string
|
||||
}
|
||||
retentionPolicyId?: string
|
||||
}
|
||||
capabilities: {
|
||||
nativeDuplex: boolean
|
||||
supportsTools: boolean
|
||||
supportsAsk: boolean
|
||||
supportsExecute: boolean
|
||||
inputLanguages: string[]
|
||||
outputLanguages: string[]
|
||||
}
|
||||
}
|
||||
|
||||
type VoiceRuntimeSnapshot = {
|
||||
selection: Exclude<AgentRuntimeSelection, { provider: 'auto' }>
|
||||
profileRevision?: string
|
||||
configurationDigest: string
|
||||
workspacePath: string
|
||||
}
|
||||
|
||||
type VoiceSessionSnapshot = {
|
||||
sessionId: string
|
||||
conversationId: string
|
||||
profile: VoiceEngineProfile
|
||||
profileRevision: string
|
||||
engineConfigurationDigest: string
|
||||
runtime?: VoiceRuntimeSnapshot
|
||||
workMode: 'ask' | 'execute'
|
||||
inputFormat: VoiceAudioFormat
|
||||
outputFormat: VoiceAudioFormat
|
||||
turnDetection: VoiceTurnDetectionConfig
|
||||
startedAt: string
|
||||
}
|
||||
```
|
||||
|
||||
`credentialRef` 和 `accountRef` 是不含凭据正文的稳定引用。Endpoint 写入 Profile 或快照前
|
||||
必须规范化并删除用户名、密码、查询参数和 Fragment；供应商部署路径仍应保留，以便检测
|
||||
Endpoint 是否发生变化。Profile 持久化时只引用 Main 加密设置，快照不包含长期或临时
|
||||
Token。
|
||||
|
||||
模块化引擎分别记录 ASR 和 TTS 组件，原生引擎记录 `nativeDuplex` 组件；不能用一个
|
||||
`modelId` 代表多组件链路。文本 Agent 使用独立 `VoiceRuntimeSnapshot`，记录已解析的明确
|
||||
Runtime、模型 Profile 修订、配置摘要和工作区。`dataPath` 分别说明原始音频和转写文本
|
||||
留在设备还是发送到哪个供应商。
|
||||
|
||||
### 9.1 Runtime Lease
|
||||
|
||||
语音会话不能在每轮请求时重新读取可变的全局 Runtime 设置。启动时必须：
|
||||
|
||||
1. 将 `auto` 解析为明确的 Runtime 和模型 Profile，并在会话界面显示实际结果。
|
||||
2. 根据已解析配置创建或取得一个不可变的 `VoiceRuntimeLease`。
|
||||
3. Lease 在整个 Voice Session 内引用同一个 Runtime 实例和配置摘要。
|
||||
4. 全局设置变化只为新请求和新 Voice Session 创建 Runtime，不替换活动 Lease。
|
||||
5. 用户删除或修改活动 Profile 时，界面说明“下次语音会话生效”；当前 Lease 继续运行。
|
||||
6. 固定实例无法继续时，当前语音会话明确失败，不能取得新的全局 Runtime 继续。
|
||||
|
||||
现有 `AgentRuntimeController` 的可变 `current` Slot 会在 `replace()` 后中断活动请求，因此
|
||||
不能直接作为长期 Voice Session Lease。实现前必须增加引用计数式 Pin/Lease，或由
|
||||
`SelectedRuntimeManager` 为会话持有独立 Runtime Slot；会话结束后再
|
||||
`releaseConversation()` 并释放 Lease。
|
||||
|
||||
### 9.2 事件
|
||||
|
||||
控制事件至少包括：
|
||||
|
||||
- `session-preparing`
|
||||
- `session-ready`
|
||||
- `session-reconnecting`
|
||||
- `input-speech-started`
|
||||
- `input-transcript-delta`
|
||||
- `input-transcript-committed`
|
||||
- `response-started`
|
||||
- `response-transcript-delta`
|
||||
- `response-audio-started`
|
||||
- `response-interrupted`
|
||||
- `response-completed`
|
||||
- `approval-required`
|
||||
- `tool-state`
|
||||
- `usage`
|
||||
- `error`
|
||||
- `session-ended`
|
||||
|
||||
音频帧使用独立二进制协议，包含：
|
||||
|
||||
- `sessionId`
|
||||
- `generationId`
|
||||
- `sequence`
|
||||
- `timestampSamples`
|
||||
- `sampleRate`
|
||||
- `channels`
|
||||
- `encoding`
|
||||
- `payload`
|
||||
|
||||
帧乱序、重复、跨会话或超过大小上限时直接拒绝，不尝试解释为其他格式。
|
||||
|
||||
---
|
||||
|
||||
## 10. 状态模型
|
||||
|
||||
全双工不能只用一个“正在听/正在说”枚举描述。会话使用三个正交状态：
|
||||
|
||||
```text
|
||||
Lifecycle:
|
||||
idle → preparing → active ↔ reconnecting → ended
|
||||
└──────────────→ failed
|
||||
|
||||
Input:
|
||||
muted ↔ listening ↔ speech
|
||||
|
||||
Output:
|
||||
idle → generating → playing → interrupting → idle
|
||||
```
|
||||
|
||||
用户可见状态由三个状态组合得出。合法示例：
|
||||
|
||||
- `input=listening + output=playing`：助手说话，同时继续监听。
|
||||
- `input=speech + output=interrupting`：用户抢话，助手正在停止。
|
||||
- `lifecycle=reconnecting + input=muted + output=idle`：当前引擎重连，停止上传。
|
||||
|
||||
`awaiting-approval` 是运行阻塞原因，不关闭会话；此时输入可以继续听取取消或补充文本，
|
||||
但不能把口头内容解释成授权。
|
||||
|
||||
---
|
||||
|
||||
## 11. Turn、文本与播放提交
|
||||
|
||||
### 11.1 用户输入
|
||||
|
||||
- 流式 ASR Delta 只用于界面。
|
||||
- Endpoint Detector 确认轮次后产生 committed transcript。
|
||||
- 空白、纯噪音和低置信度片段不创建用户消息。
|
||||
- 用户可在提交前通过键盘修正；修正结果而非原始猜测进入 Agent Runtime。
|
||||
|
||||
### 11.2 助手输出
|
||||
|
||||
模块化 TTS 可能落后于文本生成，因此助手文本分为：
|
||||
|
||||
- `generated`：模型已生成，尚未安排播放。
|
||||
- `queued`：已生成音频，尚未播放。
|
||||
- `played`：对应音频已从播放时钟确认输出。
|
||||
|
||||
助手消息需要区分“用户可见历史”和“下一轮模型上下文”：
|
||||
|
||||
- 所有已展示的有界文本和结构化内容都写入可见消息历史。
|
||||
- 可朗读文本记录 `generated`、`queued`、`played` 边界；中断后的消息标记为
|
||||
`interrupted`，并保留用户已经看见的内容及已播放边界。
|
||||
- 下一轮模型上下文只包含 `played` 可朗读文本，以及已经展示的 `visual-only` 内容。
|
||||
- 尚未播放的可朗读尾部即使曾临时显示，也不回送模型，并在历史中显示“未播完”状态。
|
||||
|
||||
代码块、表格、URL、引用和工具结果等不适合逐字朗读的内容使用 `visual-only` Block。它们
|
||||
一旦完整展示即可进入可见历史和下一轮上下文，不受语音播放边界裁切。这样既不会丢失用户
|
||||
已经看到的详细成果，也不会让模型误以为用户听到了被打断的语音尾部。
|
||||
|
||||
云端 Provider 支持会话截断时，Main 使用实际播放位置截断远端 Conversation Item；
|
||||
不支持时由 GoodBuddy 在下一轮上下文中只组装 `played` 和已展示的 `visual-only` 部分。
|
||||
现有消息契约与上下文组装器需要增加对应 Block 状态，不能用删掉完整助手消息来模拟截断。
|
||||
|
||||
### 11.3 文本转语音规划
|
||||
|
||||
模块化引擎从流式文本中产生可取消的短语块：
|
||||
|
||||
- 优先在中文标点、英文句界和自然从句边界提交。
|
||||
- 首个短语不等待完整回答，以降低首音频延迟。
|
||||
- URL、Markdown 标记、代码块、表格、引用编号和工具 JSON 不逐字符朗读。
|
||||
- 不能可靠口述的内容在界面展示，并使用确定性短提示说明“详细内容已显示在对话中”。
|
||||
- 不调用第二个未选择的模型生成“语音摘要”。
|
||||
|
||||
---
|
||||
|
||||
## 12. 引擎设计
|
||||
|
||||
### 12.1 本地模块化全双工
|
||||
|
||||
首个跨平台本地基线复用现有 `sherpa-onnx`：
|
||||
|
||||
```text
|
||||
AudioWorklet
|
||||
→ Silero/TEN VAD
|
||||
→ sherpa-onnx OnlineRecognizer
|
||||
→ selected AgentRuntime
|
||||
→ deterministic speech text planner
|
||||
→ sherpa-onnx TTS callback
|
||||
→ AudioWorklet playback
|
||||
```
|
||||
|
||||
现有 `sherpa-onnx` Node Addon 已提供在线识别、VAD、本地 TTS 和 TTS 音频回调。当前已安装
|
||||
的 SenseVoice、Paraformer 和 Whisper 目录主要用于离线识别；实时模式需要独立的在线
|
||||
模型目录和能力声明，不能把离线模型误标成流式模型。
|
||||
|
||||
“本地模块化”只保证音频采集、ASR 和 TTS 在本机。中间 Agent Runtime 是否本地取决于
|
||||
用户明确选择的模型连接：
|
||||
|
||||
- 连接到 loopback 本地模型时，完整链路可离线。
|
||||
- 连接到云端文本模型时，原始音频留在本地，但最终转写文本和 Agent 上下文会发送到
|
||||
该模型。界面必须明确显示这一数据路径。
|
||||
|
||||
不得因当前文本 Runtime 不可用而替换为另一模型连接。
|
||||
|
||||
### 12.2 本地原生全双工
|
||||
|
||||
本地原生 Adapter 面向 MiniCPM-o、Moshi/PersonaPlex、BayLing-Duplex 等能够持续接收并
|
||||
生成音频的模型。具体模型接入前必须逐个验证：
|
||||
|
||||
- 中文和目标语言质量。
|
||||
- 真正的持续输入、Barge-in 和 Backchannel，而不只是流式输出。
|
||||
- 首音频延迟和长期运行内存。
|
||||
- Windows、macOS、Linux 及 x64/arm64 Runtime 可用性。
|
||||
- NVIDIA CUDA、Apple Silicon 或 CPU 的真实硬件要求。
|
||||
- 工具调用、系统指令、上下文长度和取消支持。
|
||||
- 模型、声音、训练数据与商业分发许可。
|
||||
- 权重下载、ZIP 迁移、校验和、磁盘占用和卸载。
|
||||
|
||||
本地原生模型不作为六平台默认能力。只有能力检测和一次真实会话测试通过后才允许选择。
|
||||
缺少结构化工具能力的模型可以声明为 Ask-only；Execute 入口必须阻塞并说明原因，不能暗中
|
||||
调用另一个文本模型补齐工具。
|
||||
|
||||
### 12.3 云端原生全双工
|
||||
|
||||
云端 Adapter 可以面向 OpenAI Realtime、Gemini Live、Qwen Realtime、Azure Voice Live
|
||||
等正式配置。每个 Adapter 必须显式声明：
|
||||
|
||||
- WebRTC 或 WebSocket 传输。
|
||||
- 输入输出音频格式。
|
||||
- VAD、Semantic Turn Detection 和手动提交能力。
|
||||
- 响应取消、音频截断和实际播放对齐能力。
|
||||
- 输入与输出转写能力。
|
||||
- 工具调用和 sideband 控制能力。
|
||||
- 会话时长、上下文、速率限制和费用。
|
||||
- 可用地域、数据处理与保留说明。
|
||||
|
||||
Provider 配置不使用泛化“OpenAI compatible”推断 Realtime 能力。普通 Chat Completions
|
||||
Endpoint 不能因为 URL 相似就被标记为实时语音。
|
||||
|
||||
---
|
||||
|
||||
## 13. 音频处理
|
||||
|
||||
### 13.1 采集
|
||||
|
||||
- 浏览器设备通常以 44.1 或 48 kHz 采集，不能假定请求值就是实际值。
|
||||
- 使用 `MediaStreamTrack.getSettings()` 记录实际声道、采样率和回声消除状态。
|
||||
- AudioWorklet 以原始设备时钟采集，再按引擎要求转换为 16/24/48 kHz。
|
||||
- 默认单声道 Float32 内部格式，边界处转换为 PCM16、Opus 或 Provider 指定格式。
|
||||
- 每帧 10–20 ms，带序号和采样时间，不使用墙钟猜测播放位置。
|
||||
|
||||
### 13.2 回声与抢话
|
||||
|
||||
回声处理使用两层信号：
|
||||
|
||||
1. Chromium AEC/NS/AGC 处理后的麦克风流。
|
||||
2. GoodBuddy 已知的播放活动、播放能量和 VAD 结果。
|
||||
|
||||
只有满足最短语音持续时间、能量和回声相关性条件时才触发 Barge-in。阈值必须可测试，
|
||||
不能仅依赖一个 Provider 的 `speech_started` 事件。Provider 事件作为权威轮次信号之一，
|
||||
本地快速 VAD 负责先静音。
|
||||
|
||||
### 13.3 播放与背压
|
||||
|
||||
- 每个响应使用独立 `generationId`，旧响应帧不得进入新队列。
|
||||
- 播放队列按采样时钟排序，禁止无限积压。
|
||||
- 达到高水位时对上游施加背压；无法背压的 Provider 丢弃会话并报告协议错误，不能持续
|
||||
增长内存。
|
||||
- 音频缺口使用短静音或 Provider 编解码恢复，不重复上一段语音。
|
||||
- 切换输出设备、设备丢失或系统休眠时暂停提交时钟，避免把未播放文本标记为已听到。
|
||||
|
||||
---
|
||||
|
||||
## 14. 数据与持久化
|
||||
|
||||
### 14.1 默认保存
|
||||
|
||||
- Voice Session ID、Conversation ID 和时间。
|
||||
- 无凭据的引擎快照及其摘要哈希。
|
||||
- 最终用户文本、已展示的助手消息、`visual-only` Block、实际播放边界和中断状态。
|
||||
- 中断、失败、取消和完成状态。
|
||||
- 有界延迟、音频中断和用量指标。
|
||||
- 工具与审批事件继续进入现有任务和活动记录。
|
||||
|
||||
### 14.2 默认不保存
|
||||
|
||||
- 原始麦克风音频。
|
||||
- Provider 返回但尚未播放的音频。
|
||||
- 临时 ASR Delta。
|
||||
- 长期或临时 API Key、Cookie、会话 Token。
|
||||
- Provider 原始错误正文和可能包含用户内容的网络帧。
|
||||
- 回声参考信号、设备唯一标识和完整声学特征。
|
||||
|
||||
未来若提供录音留存，必须是独立、默认关闭的功能，说明保存位置、期限、大小、导出和删除，
|
||||
并与“改进模型”授权分离。
|
||||
|
||||
### 14.3 崩溃恢复
|
||||
|
||||
应用启动时将未结束的 Voice Session 标记为 `interrupted`。恢复文本 Conversation，
|
||||
但不自动重新打开麦克风、不自动连接 Provider，也不重播未完成音频。
|
||||
|
||||
---
|
||||
|
||||
## 15. 错误、重连与资源回收
|
||||
|
||||
| 场景 | 行为 |
|
||||
| --- | --- |
|
||||
| 麦克风权限拒绝 | 阻塞启动，保留引擎选择，提供系统权限说明 |
|
||||
| 输入/输出设备消失 | 立即静音或暂停，要求用户处理设备，不改用未选择设备 |
|
||||
| 本地模型缺失或损坏 | 阻塞启动，进入模型管理，不连接云端 |
|
||||
| 本地 Runtime 启动失败 | 在有界预算内重启同一 Runtime，之后明确失败 |
|
||||
| 云端认证或地域错误 | 明确失败，保留配置，不尝试其他 Provider/地域 |
|
||||
| 短暂断网 | 同一引擎有界重连，超过 500 ms 显示状态 |
|
||||
| Provider 限流或余额不足 | 结束生成并显示原因，不切本地模型 |
|
||||
| Agent Runtime 失败 | 终止当前轮次，允许重试同一 Runtime，不换连接 |
|
||||
| TTS 失败 | 当前轮次失败，不静默改成系统 TTS 或仅文本成功 |
|
||||
| 工具等待审批 | 暂停响应，保留会话；拒绝后把结果返回当前引擎 |
|
||||
| 应用退出/窗口销毁 | 取消请求、停止 Track、关闭 Port/PeerConnection、终止 Sidecar |
|
||||
| 系统休眠/锁屏 | 停止采集和上传；恢复后要求用户显式继续 |
|
||||
|
||||
每个会话必须有最大时长、最大连续无声时间、最大媒体队列、最大临时文本、最大重连次数和
|
||||
最大诊断大小。取消优先于重连和重试。
|
||||
|
||||
---
|
||||
|
||||
## 16. 安全与隐私
|
||||
|
||||
1. 只允许可信主窗口主 Frame 创建和控制 Voice Session。
|
||||
2. 麦克风权限只放行音频，不因实时语音放开视频。
|
||||
3. 任何音频采集都需要用户操作；活动期间持续显示应用内状态和系统麦克风指示。
|
||||
4. 云端会话在开始前显示 Provider、地域、发送内容和可能费用。
|
||||
5. API Key 只在 Main 的加密设置或受控环境变量中使用。
|
||||
6. 临时 Provider 凭据具有最短可行期限、最小能力和单会话作用域。
|
||||
7. Provider 工具调用必须回到 Main 的白名单、Schema、Ask/Execute 和审批边界。
|
||||
8. 本地 Sidecar 只监听 loopback，使用短期认证，不开放外部端口。
|
||||
9. 模型权重按受信任目录、固定来源、大小和 SHA-256 校验，导入 ZIP 防止路径穿越和压缩炸弹。
|
||||
10. 日志只记录状态、耗时、错误分类和匿名引擎 ID，不记录语音正文和音频。
|
||||
11. 窗口隐藏时若会话仍活动，托盘必须持续显示麦克风状态和停止入口；首期可以选择隐藏即
|
||||
暂停，但不能隐藏后无提示继续采集。
|
||||
12. Voice Session 不扩大项目、知识库、文件、浏览器或桌面控制范围。
|
||||
|
||||
---
|
||||
|
||||
## 17. 性能与质量指标
|
||||
|
||||
### 17.1 交互指标
|
||||
|
||||
| 指标 | 目标 |
|
||||
| --- | --- |
|
||||
| 用户开口到本地 VAD 检出 | P95 ≤ 100 ms |
|
||||
| Barge-in 检出到扬声器静音 | P95 ≤ 150 ms |
|
||||
| 播放队列常态深度 | 100–400 ms |
|
||||
| 用户轮次结束到临时文本稳定 | P50 ≤ 300 ms |
|
||||
| 用户轮次结束到首段助手音频 | 云端/原生引擎 P50 ≤ 800 ms；模块化引擎 P50 ≤ 1,200 ms |
|
||||
| 已提交文本与实际播放偏差 | ≤ 100 ms 或一个最小短语块 |
|
||||
| 连续 30 分钟会话 | 无未界定内存增长、重复播放或资源泄漏 |
|
||||
|
||||
本地指标必须注明测试硬件，不能把高端 GPU 结果宣传为 CPU 基线。未达到所选引擎声明的
|
||||
实时系数时，能力检测应标记为不满足实时要求，而不是静默切到更小模型。
|
||||
|
||||
### 17.2 质量指标
|
||||
|
||||
- 中文普通话、英文和中英混合词的 ASR 错误率。
|
||||
- 长停顿、语气词、短回答和自我修正的轮次准确率。
|
||||
- 扬声器回声、键盘声、音乐和旁人说话下的误打断率。
|
||||
- 真正用户抢话的漏检率和停止延迟。
|
||||
- TTS 首段延迟、断句、数字、日期、英文缩写和代码术语可懂度。
|
||||
- 中断后下一轮上下文不包含未播放内容。
|
||||
- Provider、模型、数据位置和能力从不发生未声明变化。
|
||||
|
||||
---
|
||||
|
||||
## 18. 测试策略
|
||||
|
||||
### 18.1 自动化
|
||||
|
||||
- Voice Contract Schema、大小边界和迁移测试。
|
||||
- 三组正交状态及非法状态组合测试。
|
||||
- 有序、乱序、重复、迟到和跨 Session 音频帧测试。
|
||||
- Barge-in 对播放、Provider、Agent、TTS 和持久化的取消传播测试。
|
||||
- 临时文本、已提交文本和播放位置对齐测试。
|
||||
- 同一引擎重连预算与超时测试。
|
||||
- “禁止静默降级”矩阵测试：任何 Adapter、Provider、模型、地域或 Runtime 变化都必须失败。
|
||||
- Ask 只读和 Execute 审批测试。
|
||||
- 窗口销毁、应用退出、休眠和设备丢失的资源释放测试。
|
||||
- 不持久化音频、临时 Token 和 Provider 原始正文的数据库测试。
|
||||
|
||||
### 18.2 模拟与声学测试
|
||||
|
||||
建立确定性 Fake Voice Engine，能够注入：
|
||||
|
||||
- 固定节奏的输入、文本和音频。
|
||||
- 网络抖动、丢包、重复和断开。
|
||||
- 超前文本、迟到音频和错误播放位置。
|
||||
- 用户抢话、回声、短噪音和长停顿。
|
||||
- 工具调用、审批、拒绝和取消。
|
||||
|
||||
真实声学测试使用预录双声道夹具，一路作为助手扬声器参考，一路作为用户麦克风输入。
|
||||
不能只通过静态单段 WAV 验证全双工。
|
||||
|
||||
### 18.3 手动与外部调用
|
||||
|
||||
- 六个发布目标分别验证麦克风权限、采集、播放、设备拔插和应用退出。
|
||||
- 本地模型在声明的最低硬件上完成 30 分钟稳定性和实时系数测试。
|
||||
- 云端 Provider 测试会产生外部调用和费用，只在明确授权的 gated 测试中运行。
|
||||
- 每个云端 Adapter 至少验证一次真实音频输入、真实音频输出、打断和工具审批。
|
||||
- 真实测试失败时不使用配置握手成功替代生成验证。
|
||||
|
||||
---
|
||||
|
||||
## 19. 跨平台交付
|
||||
|
||||
### 19.1 基线
|
||||
|
||||
- 本地模块化引擎作为 Windows、macOS、Linux x64/arm64 的统一功能基线。
|
||||
- 在线 ASR、VAD 和轻量 TTS 权重不内置，继续使用按需下载和 ZIP 离线迁移。
|
||||
- GoodBuddy 托管模型的下载遵守
|
||||
[平台功能页签与模型下载源设计](../../architecture/model-download-source-design.md)，使用用户显式选择的
|
||||
ModelScope 或 Hugging Face，失败时不切换来源。
|
||||
- 云端 Adapter 在六个平台复用同一契约，并分别验证 Electron WebRTC/WebSocket 行为。
|
||||
- 本地原生引擎按 Adapter 声明平台与硬件，不伪装成全平台能力。
|
||||
|
||||
### 19.2 硬件能力等级
|
||||
|
||||
| 等级 | 目标 |
|
||||
| --- | --- |
|
||||
| CPU 基线 | 本地模块化 ASR/TTS；文本 Runtime 可以本地或云端 |
|
||||
| Apple Silicon | 可增加 MLX/Metal 本地原生 Adapter，必须单独验证 |
|
||||
| NVIDIA GPU | 可增加 CUDA 本地原生 Adapter，按显存和驱动验证 |
|
||||
| 不满足要求 | 引擎卡片显示不可用与原因，不自动选择其他引擎 |
|
||||
|
||||
安装包继续保持轻量。大模型权重、CUDA Runtime 和独立 Python 环境不得无条件加入全部
|
||||
发布包。
|
||||
|
||||
---
|
||||
|
||||
## 20. 分阶段实施
|
||||
|
||||
### 阶段 0：契约与模拟器
|
||||
|
||||
- 新增 Voice Contracts、状态机和 Fake Voice Engine。
|
||||
- 建立禁止静默降级测试矩阵。
|
||||
- 建立会话快照、事件和诊断结构。
|
||||
|
||||
### 阶段 1：Renderer 音频平面
|
||||
|
||||
- AudioWorklet 采集与播放。
|
||||
- 媒体 `MessagePort`、背压和播放时钟。
|
||||
- 快速 VAD、回声关联、Barge-in 和设备生命周期。
|
||||
- 实时语音控制区和可访问状态。
|
||||
|
||||
### 阶段 2：本地模块化基线
|
||||
|
||||
- 在线 ASR 和 VAD 模型管理。
|
||||
- Agent Runtime 流式文本桥。
|
||||
- 本地 TTS 模型管理、短语规划、音频回调和取消。
|
||||
- 最终文本持久化与工具审批。
|
||||
- 六个平台/架构验证。
|
||||
|
||||
### 阶段 3：首个云端原生 Adapter
|
||||
|
||||
- Main-only 凭据和引擎 Profile。
|
||||
- WebRTC 或 WebSocket 会话。
|
||||
- 转写、音频、截断、用量和 Provider 错误。
|
||||
- sideband 工具与审批。
|
||||
- 真实有费用的 gated 验证。
|
||||
|
||||
### 阶段 4：本地原生全双工 Adapter
|
||||
|
||||
- 选择一个中文质量、许可和硬件要求已验证的模型。
|
||||
- 建立受管 Sidecar、能力检测和真实会话测试。
|
||||
- 验证原生 Barge-in、文本提交、工具能力和长期稳定性。
|
||||
|
||||
### 阶段 5：扩展与质量
|
||||
|
||||
- 增加经过验证的云端和本地 Adapter。
|
||||
- 输出设备选择和企业语音策略。
|
||||
- 声学基准、延迟仪表盘和成本诊断。
|
||||
- 评估是否允许用户预配置仍需确认的显式替代策略。
|
||||
|
||||
---
|
||||
|
||||
## 21. 首个垂直切片
|
||||
|
||||
首个可合并实现应使用 Fake Voice Engine，不立即绑定某个云端 Provider：
|
||||
|
||||
1. 用户显式开始会话。
|
||||
2. AudioWorklet 持续采集和播放模拟流。
|
||||
3. Fake Engine 产生临时转写、助手文本和音频。
|
||||
4. 用户开口触发 150 ms 内静音和响应取消。
|
||||
5. 持久化已提交用户文本、已展示助手内容、`visual-only` Block 和实际播放边界；下一轮
|
||||
模型上下文只使用已播放文本与完整显示的 `visual-only` Block。
|
||||
6. 模拟工具审批时暂停语音，拒绝口头授权。
|
||||
7. 注入 Adapter 失败后明确结束，不切换任何引擎。
|
||||
8. 关闭窗口后所有 Track、Port、计时器和模拟任务归零。
|
||||
|
||||
该切片先验证最难改变的会话、音频、提交和安全契约，再分别接入本地和云端实现。
|
||||
|
||||
---
|
||||
|
||||
## 22. 验收标准
|
||||
|
||||
- 用户可以明确选择本地模块化、本地原生或云端原生引擎，界面持续显示当前选择。
|
||||
- 会话快照冻结 Provider、模型、地域、声音、数据位置和能力。
|
||||
- 任何引擎、Provider、模型、地域、Runtime 或模式变化都不能在测试中静默发生。
|
||||
- 助手播放期间继续采集麦克风，用户可在 P95 150 ms 内打断。
|
||||
- 中断后未播放音频与文本不进入下一轮上下文。
|
||||
- Ask 和 Execute 在语音中与文本中使用同一权限和审批边界。
|
||||
- 语音口令不能批准工具。
|
||||
- 云端长期凭据不进入 Renderer，本地 Sidecar 不监听外部地址。
|
||||
- 默认数据库、日志和 Artifact 中没有原始音频。
|
||||
- 本地引擎失败不连接云端，云端引擎失败不启动本地模型。
|
||||
- 重连只针对同一引擎快照，并在可感知时显示状态。
|
||||
- 六个平台目标完成各自声明能力的真实采集、播放、取消和资源回收验证。
|
||||
- `npm test`、`npm run typecheck`、`npm run lint` 和生产构建全部通过。
|
||||
|
||||
---
|
||||
|
||||
## 23. 参考
|
||||
|
||||
- [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx)：本地在线/离线 ASR、VAD 与 TTS。
|
||||
- [OpenAI Realtime](https://developers.openai.com/api/docs/guides/realtime)：云端实时音频会话与 WebRTC/WebSocket。
|
||||
- [Gemini Live API](https://ai.google.dev/gemini-api/docs/live-api)：云端双向实时音频与多模态会话。
|
||||
- [Qwen Realtime](https://help.aliyun.com/zh/model-studio/realtime)：云端实时音视频输入与音频/文本输出。
|
||||
- [MiniCPM-o](https://github.com/OpenBMB/MiniCPM-V)：本地端到端多模态与全双工候选。
|
||||
- [Moshi](https://github.com/kyutai-labs/moshi)：本地原生全双工语音模型框架。
|
||||
- [PersonaPlex](https://github.com/NVIDIA/personaplex)：本地可控角色与声音的全双工候选。
|
||||
- [AudioWorklet](https://developer.mozilla.org/en-US/docs/Web/API/AudioWorklet)：Renderer 低延迟音频处理基础。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 应用内反馈
|
||||
|
||||
应用内反馈负责用户在 GoodBuddy 中提交反馈、附带受控诊断并获得提交状态。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [技术设计](./technical-design.md) | 产品流程、数据边界、接口、UI 接入和验收 |
|
||||
|
||||
现有文档是综合设计，尚未按标准职责拆分。
|
||||
@@ -0,0 +1,710 @@
|
||||
# GoodBuddy 应用内反馈系统设计与对接
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 文档类型 | 跨功能产品与技术架构 |
|
||||
| 状态 | 已实施并完成生产联调，待发布 |
|
||||
| 版本 | 1.0 |
|
||||
| 日期 | 2026-08-25 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
|
||||
| 相关基线 | [统一界面设计系统](../../../UI-DESIGN.md) |
|
||||
|
||||
本文定义 GoodBuddy 桌面端的应用内反馈入口、数据边界、Renderer / Preload /
|
||||
Main 进程职责、公共 API 对接、失败处理和验收方法。反馈平台服务端、管理后台、
|
||||
数据库、附件存储、部署和运营流程由独立项目维护，不在本文复制其内部设计。
|
||||
|
||||
本文是 **GoodBuddy 客户端实现的权威设计**。服务端字段、状态码和限制以反馈平台
|
||||
发布的版本化公共 API 契约为准；两边的同名契约必须通过兼容性测试保持一致，不能各自
|
||||
扩展后继续沿用相同的 `schemaVersion`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 摘要与核心决策
|
||||
|
||||
1. 用户在“设置 → 关于与更新”内直接提交问题、功能建议、体验意见或其他反馈，不再跳转
|
||||
GitHub Issue 页面。
|
||||
2. Renderer 只负责表单、截图预览和状态展示。所有网络请求、安装标识、应用版本和系统
|
||||
环境组装都在 Main 中完成。
|
||||
3. Preload 只暴露用途明确的 `feedback.submit()` 方法，不暴露任意 URL、通用
|
||||
`fetch`、Electron API、文件路径或服务端管理能力。
|
||||
4. 公共请求固定使用版本化接口 `POST /api/v1/feedback`，GoodBuddy 的
|
||||
`productKey` 固定为 `goodbuddy`。
|
||||
5. 反馈服务的生产 HTTPS Origin 是客户端源代码中的受信产品常量，不是用户设置，不从
|
||||
Renderer、项目、Runtime、环境变量、远程配置或服务端重定向中获取。
|
||||
6. GoodBuddy 当前的全局 TLS 策略允许模型和内网服务使用自签名或过期证书。反馈可能包含
|
||||
用户输入和截图，因此 **反馈客户端不得复用全局不校验证书的 Dispatcher 或
|
||||
`globalThis.fetch`**，必须使用独立的 Undici Dispatcher 并显式启用正常证书校验。
|
||||
7. 首版允许一张可选截图。截图只能由用户主动选择或粘贴，发送前必须预览并允许移除；
|
||||
GoodBuddy 不自动截屏。原始输入和 PNG 标准化结果都不能超过 5 MiB。
|
||||
8. Main 在发送前解码并重编码截图为 PNG，确保原始 EXIF/XMP 等元数据不会离开设备；
|
||||
服务端仍独立执行自己的图片验证和标准化。
|
||||
9. 一次新反馈生成一个 `clientRequestId`。网络失败后的手动重试必须复用原 ID，服务端
|
||||
以此保证幂等；创建另一条反馈时才生成新 ID。
|
||||
10. GoodBuddy 使用单独的随机安装 UUID 做服务端限流。该 UUID 不得复用 Agent
|
||||
installation ID、硬件 ID、机器名、用户名、项目 ID 或任何设备指纹。
|
||||
11. 默认不发送对话、提示词、模型回复、诊断、日志、文件、项目或工作区路径、知识库、模型
|
||||
配置、Runtime 配置、API Key、Token、Cookie、SSH 信息、剪贴板或屏幕内容。用户可通过
|
||||
默认关闭的 Checkbox 主动附加有界的最近桌面诊断摘要。
|
||||
12. 反馈提交失败时保留全部表单内容和截图，成功后显示可复制的服务端反馈编号。
|
||||
13. 首版不提供反馈历史、状态查询、编辑、撤回、自动日志收集或服务端管理入口。
|
||||
14. 生产接口固定为 `https://imp.mesalogo.com/api/v1/feedback`。域名健康检查、
|
||||
TLS、v1 请求校验和客户端调用链必须在发布前一起通过。
|
||||
|
||||
---
|
||||
|
||||
## 2. 目标与非目标
|
||||
|
||||
### 2.1 用户目标
|
||||
|
||||
- 不离开 GoodBuddy 即可报告问题或提出建议。
|
||||
- 在发送前明确知道哪些字段会离开设备。
|
||||
- 只在主动选择后上传截图，并能检查、替换或移除截图。
|
||||
- 网络失败后无需重新填写内容。
|
||||
- 提交成功后获得稳定编号，便于后续沟通。
|
||||
|
||||
### 2.2 产品目标
|
||||
|
||||
- 让 GoodBuddy 成为独立多产品反馈平台的第一个客户端。
|
||||
- 保持 Electron 上下文隔离和 Main-only 网络边界。
|
||||
- 使用小而稳定的版本化契约，不把服务端工单、数据库和管理员概念泄漏到客户端。
|
||||
- 对 Windows、macOS、Linux 的 x64 与 arm64 使用相同行为。
|
||||
- 以数据最小化为默认，不把应用内反馈演变为隐式遥测或日志上传。
|
||||
|
||||
### 2.3 非目标
|
||||
|
||||
首版不包含：
|
||||
|
||||
- GitHub Issue 创建、GitHub Token 或 GitHub 网页附件上传。
|
||||
- GoodBuddy 内的管理员后台、处理状态修改或内部备注。
|
||||
- 用户账户、登录、反馈列表、远程状态查询或推送通知。
|
||||
- 自动附加当前对话、桌面诊断、日志、错误堆栈、项目、文件、模型或 Runtime 信息。
|
||||
- 远端 Agent 日志或通用日志、诊断包和附件框架。
|
||||
- 自动截取全屏、当前窗口、浏览器、远程桌面或其他应用窗口。
|
||||
- 多截图、视频、录屏、任意文件附件或压缩包。
|
||||
- 离线队列、后台自动重试、指数退避、跨重启草稿或发送历史。
|
||||
- 用户可编辑的反馈 Endpoint、证书豁免、代理凭据或服务端 API Key。
|
||||
- 由 GoodBuddy 推断优先级、自动分类、自动生成描述或代表用户提交。
|
||||
|
||||
---
|
||||
|
||||
## 3. 用户体验
|
||||
|
||||
### 3.1 入口
|
||||
|
||||
入口放在现有“关于与更新”页面，不增加新的设置一级分类。
|
||||
|
||||
在当前版本与更新卡片之后增加“帮助改进 GoodBuddy”能力卡：
|
||||
|
||||
- 标题：`帮助改进 GoodBuddy`
|
||||
- 说明：`报告问题、提出建议或反馈使用体验，我们会在独立反馈系统中处理。`
|
||||
- 主操作：`提交反馈`
|
||||
|
||||
该卡片不显示反馈平台内部状态、管理员信息或 GitHub 链接。服务不可用时仍允许用户打开
|
||||
表单和保留输入；提交失败后提供重试，而不是把用户重定向到另一个渠道。
|
||||
|
||||
### 3.2 反馈对话框
|
||||
|
||||
对话框字段按以下顺序排列：
|
||||
|
||||
1. **反馈类型**，必填：
|
||||
- 问题：`bug`
|
||||
- 功能建议：`feature`
|
||||
- 使用体验：`experience`
|
||||
- 其他：`other`
|
||||
2. **标题**，必填，1 至 120 字符。
|
||||
3. **详细描述**，必填，去除首尾空白后 10 至 5,000 字符；选择桌面诊断时为摘要预留空间，
|
||||
用户描述上限为 3,398 字符。
|
||||
4. **附加最近桌面诊断记录**，可选的原生 Checkbox，默认关闭。
|
||||
5. **联系邮箱**，可选，最多 254 字符。
|
||||
6. **截图**，可选，最多一张，支持选择 PNG/JPEG/WebP 或在对话框中粘贴图片。
|
||||
7. **将发送的信息**，只读显示应用版本、系统、架构和界面语言。
|
||||
8. **隐私说明**，紧邻提交操作。
|
||||
|
||||
隐私说明使用明确文案：
|
||||
|
||||
> 将发送反馈类型、标题、描述、可选邮箱、GoodBuddy 版本、操作系统、架构、界面语言，
|
||||
> 以及你主动添加的截图。默认不上传桌面诊断；只有勾选后才会把有界诊断摘要追加到描述。
|
||||
> 不会发送对话、Prompt、凭据、文件内容、路径、Provider 原始响应或远端 Agent 日志。
|
||||
|
||||
Checkbox 下方持续说明：诊断摘要只含时间、组件、阶段、稳定错误码、错误类型和固定短消息。
|
||||
Renderer 不预览、不读取也不接收诊断内容或路径。勾选后详细描述上限为 3,398 字符，为附加
|
||||
摘要预留 1,600 字符以及分隔换行；超长草稿保留在表单中并显示字段错误，不静默截断。
|
||||
|
||||
截图区域必须包含：
|
||||
|
||||
- 缩略预览。
|
||||
- 尺寸和所选文件大小；Main 仍在发送前独立执行 PNG 标准化和大小检查。
|
||||
- `替换截图` 与 `移除截图`。
|
||||
- `截图可能包含画面中可见的个人信息，请在发送前检查。`
|
||||
|
||||
### 3.3 提交状态
|
||||
|
||||
| 状态 | 行为 |
|
||||
| --- | --- |
|
||||
| 未填写 | 字段保持可编辑，提交按钮按字段有效性启用 |
|
||||
| 校验失败 | 在对应字段旁显示错误并把焦点移到第一个无效字段 |
|
||||
| 提交中 | 禁止重复提交、关闭和修改字段，按钮显示“正在提交…” |
|
||||
| 网络或服务失败 | 保留字段和截图，在表单内显示可操作错误及“重试” |
|
||||
| 成功 | 对话框切换为确认面板，显示并允许复制反馈编号 |
|
||||
|
||||
提交成功属于必须保留编号的上下文结果，不再同时发送一条重复的全局成功通知。异步失败也
|
||||
保留在对话框内，因为错误与当前草稿和重试操作直接关联。
|
||||
|
||||
### 3.4 可访问性
|
||||
|
||||
- 对话框使用 `role="dialog"`、`aria-modal="true"` 和可见标题。
|
||||
- 复用 `activateModalFocus()` 与 `trapTabFocus()`，打开后聚焦反馈类型，关闭后恢复入口
|
||||
按钮焦点。
|
||||
- 非提交状态支持 Escape 关闭；提交中保持对话框打开，直到请求完成或到达有界超时。
|
||||
- 字段使用原生 `label`、`select`、`input` 和 `textarea`。
|
||||
- 图片预览提供说明性替代文本，删除和替换按钮有明确可访问名称。
|
||||
- 加载、失败和成功状态使用文字，不依赖颜色。
|
||||
- 浅色、深色和 `prefers-reduced-motion` 行为遵循 `UI-DESIGN.md`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据与隐私边界
|
||||
|
||||
### 4.1 明确发送的数据
|
||||
|
||||
| 数据 | 来源 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| `schemaVersion` | Main 常量 | 选择公共契约版本 |
|
||||
| `productKey` | Main 常量 `goodbuddy` | 服务端产品路由 |
|
||||
| `category` | 用户选择 | 分流反馈 |
|
||||
| `title` | 用户输入 | 摘要 |
|
||||
| `description` | 用户输入；勾选时由 Main 追加桌面诊断摘要 | 问题、建议和主动提供的有界诊断详情 |
|
||||
| `contactEmail` | 用户可选输入 | 必要时联系用户 |
|
||||
| `environment.appVersion` | `app.getVersion()` | 判断受影响版本 |
|
||||
| `environment.platform` | `process.platform` 映射 | 判断受影响平台 |
|
||||
| `environment.architecture` | `process.arch` 映射 | 判断受影响架构 |
|
||||
| `environment.locale` | 当前 GoodBuddy UI 语言 | 理解用户语言环境 |
|
||||
| `installationId` | Main 本地随机 UUID | 服务端安装实例限流 |
|
||||
| `clientRequestId` | 当前草稿随机 UUID | 幂等和安全重试 |
|
||||
| `screenshot` | 用户主动选择或粘贴 | 复现视觉问题 |
|
||||
|
||||
客户端不主动发送来源 IP；IP 是 HTTPS 请求到达服务端时产生的网络元数据。服务端如何保存、
|
||||
散列和保留该元数据由独立反馈平台的隐私与运维策略负责。
|
||||
|
||||
用户填写联系邮箱后，邮箱会作为业务字段通过 HTTPS 发送并由反馈平台保存，不属于端到端
|
||||
加密内容。用户不希望提供联系方式时应留空，GoodBuddy 不尝试从系统账户或其他设置推断
|
||||
邮箱。
|
||||
|
||||
### 4.2 默认不发送的数据
|
||||
|
||||
以下数据不能因为“有助于复现”而隐式加入请求：
|
||||
|
||||
- 当前或历史对话、提示词、模型回复和 Supervisor 内容。
|
||||
- GoodBuddy、Runtime、Agent、SSH、消息通道、浏览器或操作系统日志。
|
||||
- 文件内容、附件、知识库、Magic Notes、成果和工作区改动。
|
||||
- 文件名、项目名、本地路径、远程路径、主机名、用户名或 IP 配置。
|
||||
- LLM、向量模型、语音模型、OCR、MCP、Skill、Runtime 或通道配置。
|
||||
- API Key、Access Token、Cookie、SSH 密码、私钥、代理凭据和其他秘密。
|
||||
- 剪贴板、屏幕、摄像头、麦克风或其他应用内容。
|
||||
- Remote Agent installation ID、Runtime ID、Conversation ID、Task ID 或 Project ID。
|
||||
|
||||
除上述用户主动选择、追加到描述且有界的桌面诊断摘要外，未来若增加日志、诊断包或其他
|
||||
附件，必须单独设计字段、预览、大小限制、用户选择和服务端保留策略，不能复用截图字段
|
||||
静默上传。
|
||||
|
||||
### 4.3 本地数据生命周期
|
||||
|
||||
- 表单草稿、邮箱和截图只保存在当前 Renderer 内存中。
|
||||
- 首版不把草稿、失败请求、成功响应或截图写入 GoodBuddy 数据库和设置文件。
|
||||
- Main 只在请求期间持有标准化图片字节，请求结束后释放引用，不创建临时图片文件。
|
||||
- 成功后关闭确认面板时清空草稿。
|
||||
- `installationId` 单独保存在用户数据目录中的
|
||||
`feedback-identity.json`，格式为版本化 JSON，文件权限沿用私有原子设置文件机制。
|
||||
- “清除本地数据”必须中止进行中的反馈请求并删除该身份文件；下次提交会生成新 UUID。
|
||||
|
||||
---
|
||||
|
||||
## 5. 公共 API 对接
|
||||
|
||||
### 5.1 外部契约所有权
|
||||
|
||||
反馈平台负责维护公共 API 的权威定义。GoodBuddy 只固定客户端实际需要的版本 1 子集：
|
||||
|
||||
```text
|
||||
POST https://imp.mesalogo.com/api/v1/feedback
|
||||
```
|
||||
|
||||
当前生产 Endpoint 已作为 Main-only 产品常量固定。实现和发布验证必须持续保证：
|
||||
|
||||
- 使用 `https:`。
|
||||
- URL 不含用户名、密码、查询参数或 fragment。
|
||||
- Path 精确为 `/api/v1/feedback`。
|
||||
- 对应产品 `goodbuddy` 已在服务端启用。
|
||||
- 桌面端所在网络能够直接访问该 Origin。
|
||||
|
||||
Renderer、Preload、用户设置、环境变量和远程配置都不能覆盖该 Endpoint。域名迁移必须
|
||||
同时修改客户端受信常量、测试、服务端 Origin 配置和部署文档。
|
||||
|
||||
### 5.2 请求 JSON
|
||||
|
||||
无截图时发送 `application/json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"productKey": "goodbuddy",
|
||||
"category": "bug",
|
||||
"title": "魔法笔记页签不可见",
|
||||
"description": "平台功能中的魔法笔记页签被布局压缩，无法看到或点击。",
|
||||
"contactEmail": "user@example.com",
|
||||
"environment": {
|
||||
"appVersion": "0.11.0",
|
||||
"platform": "windows",
|
||||
"architecture": "x64",
|
||||
"locale": "zh-CN"
|
||||
},
|
||||
"installationId": "00000000-0000-4000-8000-000000000101",
|
||||
"clientRequestId": "00000000-0000-4000-8000-000000000102"
|
||||
}
|
||||
```
|
||||
|
||||
有截图时发送 `multipart/form-data`：
|
||||
|
||||
- `payload`：同一 JSON 的字符串形式。
|
||||
- `screenshot`：一张标准化 PNG，文件名固定为 `feedback.png`。
|
||||
|
||||
`contactEmail` 为空时省略，不发送空字符串。请求对象不附加服务端未声明字段。
|
||||
|
||||
### 5.3 成功响应
|
||||
|
||||
HTTP 201 表示首次创建，HTTP 200 表示相同 `clientRequestId` 的幂等结果：
|
||||
|
||||
```json
|
||||
{
|
||||
"reference": "GOODBUDDY-000001",
|
||||
"duplicate": false
|
||||
}
|
||||
```
|
||||
|
||||
客户端对两种成功状态使用相同确认界面。`duplicate: true` 不能显示为失败，它表示先前请求
|
||||
已经成功落库。
|
||||
|
||||
### 5.4 错误映射
|
||||
|
||||
| HTTP / 错误 | 用户结果 |
|
||||
| --- | --- |
|
||||
| 400 | 提示提交内容无效，保留草稿；同时记录为客户端契约缺陷 |
|
||||
| 403 | 提示客户端与反馈服务配置不匹配 |
|
||||
| 404 | 提示反馈服务暂不可用 |
|
||||
| 413 | 提示截图或请求过大，允许移除截图后重试 |
|
||||
| 429 | 提示提交过于频繁，保留草稿并让用户稍后手动重试 |
|
||||
| 500–599 | 提示服务暂时异常，保留草稿 |
|
||||
| 超时 / DNS / TLS / 离线 | 提示无法连接反馈服务，保留草稿 |
|
||||
| 响应格式错误 | 提示服务返回无效结果，不能猜测成功 |
|
||||
| 本地诊断读取失败 | 不发送反馈，保留草稿、勾选状态和请求 ID，提示重试或取消勾选 |
|
||||
|
||||
首版不自动重试。自动重试容易让用户无法判断是否已经发送，也会在服务持续异常时制造额外
|
||||
流量。用户点击“重试”时复用同一个 `clientRequestId`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 进程与模块设计
|
||||
|
||||
### 6.1 调用链
|
||||
|
||||
```text
|
||||
UpdateSettingsSection / FeedbackDialog
|
||||
→ window.goodbuddy.feedback.submit(input)
|
||||
→ preload: ipcRenderer.invoke(feedbackSubmit)
|
||||
→ Main IPC: trusted sender + Zod parse
|
||||
→ FeedbackService: identity + environment + screenshot normalization
|
||||
→ StrictFeedbackHttpClient
|
||||
→ POST /api/v1/feedback
|
||||
→ response schema parse
|
||||
→ Renderer confirmation or inline retry state
|
||||
```
|
||||
|
||||
### 6.2 Shared
|
||||
|
||||
新增 `src/shared/feedback-contracts.ts`，包含：
|
||||
|
||||
- `feedbackCategorySchema`
|
||||
- `feedbackDraftSchema`
|
||||
- `feedbackScreenshotInputSchema`
|
||||
- `feedbackSubmitInputSchema`
|
||||
- `feedbackSubmitResultSchema`
|
||||
- `feedbackPublicPayloadSchema`
|
||||
- 公共字段长度和截图限制常量
|
||||
|
||||
推荐客户端 IPC 输入：
|
||||
|
||||
```ts
|
||||
type FeedbackSubmitInput = {
|
||||
category: 'bug' | 'feature' | 'experience' | 'other'
|
||||
title: string
|
||||
description: string
|
||||
includeDiagnostics: boolean
|
||||
contactEmail?: string
|
||||
locale: 'zh-CN' | 'en-US'
|
||||
clientRequestId: string
|
||||
screenshot?: {
|
||||
data: Uint8Array
|
||||
mimeType: 'image/png' | 'image/jpeg' | 'image/webp'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Renderer 不能传入 `productKey`、`appVersion`、`platform`、`architecture` 或
|
||||
`installationId`，也不能传入诊断内容或路径。这些字段由 Main 从受信运行环境生成。
|
||||
|
||||
### 6.3 IPC 与 Preload
|
||||
|
||||
新增：
|
||||
|
||||
```text
|
||||
ipcChannels.feedbackSubmit = "feedback:submit"
|
||||
```
|
||||
|
||||
`DesktopApi` 新增必选窄接口：
|
||||
|
||||
```ts
|
||||
feedback: {
|
||||
submit: (input: FeedbackSubmitInput) => Promise<FeedbackSubmitResult>
|
||||
}
|
||||
```
|
||||
|
||||
Main handler 必须：
|
||||
|
||||
1. 调用现有 `assertTrustedSender(event, window)`。
|
||||
2. 使用 Shared Zod schema 解析 `unknown` 输入。
|
||||
3. 不接收 URL、文件路径、Cookie、Header 或任意请求选项。
|
||||
4. 由 `FeedbackService` 跟踪活动 Promise，应用关闭或清除数据时先取消再有界等待。
|
||||
|
||||
Preload 只转发已声明输入，不做网络请求或图片文件读取。
|
||||
|
||||
反馈 handler 独立放在 `feedback/feedback-ipc.ts`，复用共享的
|
||||
`assertTrustedSender()`，避免继续扩展通用 `registerIpcHandlers()` 的位置参数列表。
|
||||
|
||||
### 6.4 FeedbackIdentityStore
|
||||
|
||||
新增 Main-only `FeedbackIdentityStore`：
|
||||
|
||||
- 文件：`<userData>/feedback-identity.json`
|
||||
- Schema：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"installationId": "00000000-0000-4000-8000-000000000101"
|
||||
}
|
||||
```
|
||||
|
||||
- 缺失时使用 `crypto.randomUUID()` 创建。
|
||||
- 使用 `writeJsonFileAtomically()` 写入 0600 临时文件并原子替换。
|
||||
- 读取时使用严格 schema。
|
||||
- 损坏时隔离原文件并生成新身份，不读取或复用 Remote Agent 身份。
|
||||
- 并发首次读取必须合并为同一个 Promise，不能生成两个 UUID。
|
||||
- `clear()` 删除文件和内存缓存，供“清除本地数据”调用。
|
||||
|
||||
该 UUID 是可重置的应用安装级随机标识，不声称代表真实设备或用户。
|
||||
|
||||
### 6.5 FeedbackService
|
||||
|
||||
Main-only `FeedbackService` 负责：
|
||||
|
||||
- 读取或创建安装 UUID。
|
||||
- 映射应用版本、平台和架构。
|
||||
- 验证并标准化可选截图。
|
||||
- 组装严格的公共 payload。
|
||||
- 仅在 `includeDiagnostics: true` 时通过注入的 DesktopDiagnostics provider 读取最多 20 条
|
||||
最近记录；默认提交完全不调用诊断 provider。
|
||||
- 将诊断格式化为带
|
||||
`[GOODBUDDY_DESKTOP_DIAGNOSTICS_V1_BEGIN]` /
|
||||
`[GOODBUDDY_DESKTOP_DIAGNOSTICS_V1_END]` 明确分隔、最多 1,600 字符且只保留完整 JSON
|
||||
行的摘要。无记录时写入固定 `{"status":"no-recent-diagnostics"}` 事实。
|
||||
- 调用 HTTP Client。
|
||||
- 维持单次提交的 AbortController，并在 dispose / 清除本地数据时取消。
|
||||
|
||||
平台映射固定为：
|
||||
|
||||
| Node 值 | API 值 |
|
||||
| --- | --- |
|
||||
| `win32` | `windows` |
|
||||
| `darwin` | `macos` |
|
||||
| `linux` | `linux` |
|
||||
| 其他 | `unknown` |
|
||||
|
||||
架构只保留 `x64` 和 `arm64`，其他值映射为 `unknown`。
|
||||
|
||||
公共 API 继续使用 `schemaVersion: 1` 和原有固定字段。`includeDiagnostics` 只属于客户端
|
||||
IPC 输入，不进入公共 payload，也不新增 multipart 字段；Main 把摘要追加到
|
||||
`payload.description`。默认未勾选时，公共 payload 与既有实现逐字段一致。诊断读取失败时
|
||||
不得发送部分摘要或声称已附加，必须返回可本地化的 `diagnostics-unavailable` 错误。
|
||||
|
||||
### 6.6 严格 HTTPS Client
|
||||
|
||||
反馈客户端使用 `undici` 的独立 `Agent`：
|
||||
|
||||
```ts
|
||||
new Agent({
|
||||
connect: {
|
||||
rejectUnauthorized: true
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
这是必要边界，不是额外配置。GoodBuddy 的 `GlobalTlsPolicy` 会给模型、MCP 和内网服务
|
||||
安装不校验证书的全局 Dispatcher；反馈内容不能经过该 Dispatcher。
|
||||
|
||||
每次请求必须满足：
|
||||
|
||||
- 固定、预先校验的 HTTPS URL。
|
||||
- 使用 Undici 原始 `request()`，不安装重定向处理器；任何 3xx 都按服务不可用处理。
|
||||
- 不使用 Cookie Jar、缓存、Referrer 或浏览器凭据模式。
|
||||
- `Accept: application/json`。
|
||||
- 固定、非敏感 `User-Agent`，例如 `GoodBuddy-Feedback/<version>`。
|
||||
- 不发送 `Authorization`、Cookie、API Key 或自定义代理凭据。
|
||||
- 总超时建议 15 秒，最大不得超过 30 秒。
|
||||
- 成功响应体最多 16 KiB，并检查流式实际字节数，不能只相信
|
||||
`Content-Length`。
|
||||
- 只接受 JSON `Content-Type` 和 JSON 响应体，并使用
|
||||
`feedbackSubmitResultSchema` 解析。
|
||||
- 日志只记录有界错误类别和 HTTP 状态，不记录请求正文、邮箱、截图、安装 UUID、
|
||||
`clientRequestId` 或响应编号。
|
||||
|
||||
测试可以注入 Endpoint、Dispatcher 和 Request Transport。生产构造路径不得读取测试覆盖值或
|
||||
环境变量。
|
||||
|
||||
---
|
||||
|
||||
## 7. 截图处理
|
||||
|
||||
### 7.1 Renderer
|
||||
|
||||
- 文件输入限制为 `.png,.jpg,.jpeg,.webp`。
|
||||
- 原始文件上限固定为 5 MiB，超过后不读取完整内容或调用 IPC。
|
||||
- 粘贴事件只处理图片，不拦截普通文本粘贴。
|
||||
- 读取 `File.arrayBuffer()` 后先执行 Shared 字节上限校验。
|
||||
- 使用临时 Object URL 预览，替换、移除或关闭对话框时立即
|
||||
`URL.revokeObjectURL()`。
|
||||
- 不调用 `webUtils.getPathForFile()`，不把本地文件路径传给 Main 或服务端。
|
||||
|
||||
### 7.2 Main
|
||||
|
||||
Main 不信任 Renderer 声明的 MIME：
|
||||
|
||||
1. 校验 PNG、JPEG、WebP 文件签名。
|
||||
2. 使用 `nativeImage.createFromBuffer()` 实际解码。
|
||||
3. 拒绝空图片、异常尺寸、超过 API 公开上限的像素数。
|
||||
4. 使用 `toPNG()` 重编码，去除原始元数据。
|
||||
5. 检查标准化后字节数不超过 5 MiB，最大边长不超过 8,192 像素，总像素数不超过
|
||||
3,200 万。
|
||||
6. 仅把标准化 PNG 放入当前网络请求，不写入磁盘。
|
||||
|
||||
客户端和服务端都执行图片验证属于有意的纵深防御：客户端保证原始元数据不离开设备，
|
||||
服务端保证不能信任任意客户端。
|
||||
|
||||
---
|
||||
|
||||
## 8. Renderer 实施落点
|
||||
|
||||
### 8.1 组件
|
||||
|
||||
- `UpdateSettingsSection.tsx`
|
||||
- 继续负责应用信息和更新卡片。
|
||||
- 渲染反馈入口卡片。
|
||||
- `FeedbackDialog.tsx`
|
||||
- 独立管理草稿、预览、校验、提交、重试和成功编号。
|
||||
- 关闭后销毁草稿状态。
|
||||
对话框不与更新检查状态共用 `saving`、`checking` 或 `error`，避免一个功能失败覆盖另一个
|
||||
功能的状态。
|
||||
|
||||
### 8.2 国际化
|
||||
|
||||
在 `settingsSections` 的 `zh-CN` 与 `en-US` 资源中增加同构键：
|
||||
|
||||
- 入口卡片标题、说明和按钮。
|
||||
- 类型名称。
|
||||
- 字段标签、占位、帮助和校验。
|
||||
- 截图选择、替换、移除和隐私提醒。
|
||||
- 提交中、失败、重试、成功和复制编号。
|
||||
- 数据发送说明。
|
||||
|
||||
组件不得内嵌只存在于一种语言的产品文案。
|
||||
|
||||
### 8.3 样式
|
||||
|
||||
- 复用 `capability-card`、`field`、`primary-button`、`secondary-button` 和现有
|
||||
对话框层级。
|
||||
- 新样式使用 `UI-DESIGN.md` 的语义颜色、间距、圆角和动效令牌。
|
||||
- 对话框桌面端最大宽度建议 600px；窄窗口占可用宽度并保持 16px 页面边距。
|
||||
- 不为反馈入口创建新的一级页面、页签视觉或高饱和营销卡片。
|
||||
|
||||
---
|
||||
|
||||
## 9. 失败、生命周期与恢复
|
||||
|
||||
### 9.1 幂等
|
||||
|
||||
- 打开新草稿时生成 `clientRequestId`。
|
||||
- 字段编辑、截图替换、网络失败和手动重试都不改变 ID。
|
||||
- 成功或显式丢弃草稿后，下一条反馈生成新 ID。
|
||||
- 同一 ID 返回原编号时按成功处理。
|
||||
|
||||
### 9.2 并发
|
||||
|
||||
- 对话框同一时间只允许一个提交。
|
||||
- Main 同一 `clientRequestId` 只运行一个请求。
|
||||
- Main 全局同一时间只发送一条反馈；相同 ID 的重复调用合并，不同 ID 在已有请求期间返回
|
||||
有界 `busy` 结果，不能并行保留多份 5 MiB 截图。
|
||||
- 读取截图使用选择代次；旧文件后完成时必须丢弃并释放 Object URL，不能覆盖较新的截图。
|
||||
|
||||
### 9.3 应用退出与清除数据
|
||||
|
||||
- 反馈请求有独立 AbortController。
|
||||
- 应用退出时取消进行中的请求并关闭严格 TLS Dispatcher。
|
||||
- “清除本地数据”先取消请求，再删除 `feedback-identity.json`。
|
||||
- 失败或取消不写入本地“已发送”状态，服务端是否已接收由同 ID 重试确认。
|
||||
|
||||
### 9.4 服务不可用
|
||||
|
||||
反馈平台不可用时：
|
||||
|
||||
- 保留表单和截图。
|
||||
- 显示明确网络或服务错误。
|
||||
- 不静默丢弃、不自动切换 GitHub、不打开网页、不自动重试。
|
||||
- 其他 GoodBuddy 功能继续可用。
|
||||
|
||||
---
|
||||
|
||||
## 10. 实施文件
|
||||
|
||||
当前实现涉及：
|
||||
|
||||
| 文件或目录 | 变更 |
|
||||
| --- | --- |
|
||||
| `src/shared/feedback-contracts.ts` | 输入、公共 payload、响应和限制 schema |
|
||||
| `src/shared/ipc-channels.ts` | `feedbackSubmit` channel |
|
||||
| `src/shared/contracts.ts` | `DesktopApi.feedback` |
|
||||
| `src/main/feedback/feedback-identity-store.ts` | 随机安装 ID |
|
||||
| `src/main/feedback/feedback-screenshot.ts` | 签名、解码和 PNG 标准化 |
|
||||
| `src/main/feedback/feedback-http-client.ts` | 固定 Endpoint、严格 TLS、有界响应 |
|
||||
| `src/main/feedback/feedback-service.ts` | payload 组装与生命周期 |
|
||||
| `src/main/feedback/feedback-ipc.ts` | 独立 trusted sender、schema parse 和 submit handler |
|
||||
| `src/main/trusted-ipc-sender.ts` | Main IPC 共享 sender / main Frame 校验 |
|
||||
| `src/main/index.ts` | Main service 构造、清理和 IPC 注入 |
|
||||
| `src/preload/index.ts` | 窄 `feedback.submit()` bridge |
|
||||
| `src/renderer/src/FeedbackDialog.tsx` | 表单和成功/失败流程 |
|
||||
| `src/renderer/src/UpdateSettingsSection.tsx` | About 入口卡片 |
|
||||
| `src/renderer/src/i18n/locales/*/settingsSections.ts` | 中英文文案 |
|
||||
| `src/renderer/src/styles.css` | 令牌化布局与响应式样式 |
|
||||
|
||||
每个生产文件应有相邻或现有测试文件覆盖。不要把 Endpoint、截图处理或网络逻辑塞进
|
||||
`ipc.ts` 或 React 组件。
|
||||
|
||||
---
|
||||
|
||||
## 11. 验证
|
||||
|
||||
以下 Shared、Main、IPC、Preload 和 Renderer 行为均由相邻或现有自动化测试覆盖；生产
|
||||
Endpoint 的健康检查和无副作用 schema 探针也必须在发布前通过。
|
||||
|
||||
### 11.1 Shared 合同
|
||||
|
||||
- 接受四种反馈类型和有效字段。
|
||||
- 拒绝未知字段、空标题、短描述、超长描述、错误邮箱、非 UUID 和多截图。
|
||||
- 对截图按字节限制，而不是字符串长度限制。
|
||||
- 请求与反馈平台 `schemaVersion: 1` fixture 双向兼容。
|
||||
|
||||
### 11.2 Main 单元测试
|
||||
|
||||
- 安装 ID 首次创建、并发读取、持久化、损坏隔离和清除。
|
||||
- 不复用 Agent、Runtime、Project 或硬件身份。
|
||||
- 平台和架构映射。
|
||||
- PNG/JPEG/WebP 签名、实际解码、尺寸限制、PNG 重编码和元数据不保留。
|
||||
- 无截图 JSON、有截图 multipart、请求 Header 和固定 URL。
|
||||
- 独立 Dispatcher 显式 `rejectUnauthorized: true`。
|
||||
- 拒绝重定向、非 HTTPS、错误 Origin、超时、超大响应、非 JSON 和错误 response schema。
|
||||
- 4xx、429、5xx 和网络错误映射。
|
||||
- 手动重试复用 `clientRequestId`。
|
||||
- 不同 ID 的并发请求被有界拒绝，清除本地数据期间不能开始新提交。
|
||||
|
||||
### 11.3 IPC 与 Preload
|
||||
|
||||
- 未知窗口和非主 Frame 被拒绝。
|
||||
- Renderer 不能覆盖 `productKey`、版本、平台、架构、安装 ID、Endpoint 或 Header。
|
||||
- Preload 只暴露 `feedback.submit()`。
|
||||
- Sandbox 测试验证没有通用网络或文件路径能力泄漏。
|
||||
|
||||
### 11.4 Renderer
|
||||
|
||||
- About 页面展示反馈卡片。
|
||||
- 表单字段、字符限制、中英文文案和隐私说明。
|
||||
- 普通文本粘贴不被图片处理拦截。
|
||||
- 截图选择、预览、替换、移除和 Object URL 清理。
|
||||
- 并发截图读取按最新选择生效，关闭对话框后不会留下待处理 Object URL。
|
||||
- 失败保留字段、诊断勾选状态，重试使用原 `clientRequestId`。
|
||||
- 默认提交不读取诊断且公共 payload 不变；主动附加、描述预算、无记录和读取失败均有覆盖。
|
||||
- 成功显示真实编号并清空后续新草稿。
|
||||
- Dialog role、初始焦点、Tab 循环、Escape 和焦点恢复。
|
||||
- 浅色、深色、窄窗口和 reduced motion。
|
||||
|
||||
### 11.5 真实集成
|
||||
|
||||
2026-08-25 已从隔离配置的真实 Electron 生产构建完成一次端到端合成提交：
|
||||
|
||||
- 标题：`[GOODBUDDY INTEGRATION TEST] 2026-08-25`
|
||||
- 类型：`other`
|
||||
- 联系邮箱：未填写
|
||||
- 截图：GoodBuddy 公共应用图标，经 Main 重编码后以 PNG multipart 上传
|
||||
- 服务端编号：`GOODBUDDY-000001`
|
||||
|
||||
该结果确认 About UI、Renderer、Preload、trusted IPC、安装身份、Main 图片处理、独立严格
|
||||
TLS Dispatcher 和生产 v1 API 调用链可以共同工作。发布候选仍应按以下清单复验：
|
||||
|
||||
1. 从打包候选的 About 页面提交一条明确标记的合成反馈。
|
||||
2. 可选添加一张不含个人数据的测试截图。
|
||||
3. 确认客户端显示的编号与管理后台一致。
|
||||
4. 确认版本、平台、架构和语言正确。
|
||||
5. 确认服务端只保存标准化 PNG，不含原始图片元数据。
|
||||
6. 断网后提交，确认草稿保留；恢复网络后以同一 ID 重试且只产生一条记录。
|
||||
7. 使用无效证书的测试服务，确认反馈客户端拒绝连接，即使 GoodBuddy 全局内网 TLS
|
||||
策略允许其他服务继续工作。
|
||||
8. 检查 Renderer 和 Main 日志不含正文、邮箱、截图、安装 ID 或凭据。
|
||||
|
||||
最终仍需运行仓库统一验证：
|
||||
|
||||
```text
|
||||
npm test
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. 发布与兼容性
|
||||
|
||||
- `schemaVersion: 1` 与 `/api/v1/feedback` 是同一版本边界。
|
||||
- 向请求增加必填字段、修改枚举或改变字段语义属于破坏性变更，必须发布新 schema 或新
|
||||
API 版本。
|
||||
- GoodBuddy 对响应执行严格解析。服务端需要扩展响应时，应先协调客户端兼容策略。
|
||||
- Endpoint 域名变化属于客户端发布变更，不能依赖 301/302 迁移。
|
||||
- 入口发布与 `goodbuddy` 产品启用状态、生产 TLS 和 v1 契约保持同一发布门槛。
|
||||
- 此功能不迁移现有用户数据；只新增可重置的随机反馈安装身份。
|
||||
- 发布说明应明确：用户现在可以在“关于与更新”内直接提交反馈，邮箱和截图可选；桌面诊断
|
||||
默认不上传，只有用户勾选后才附加有界摘要，并且不会发送对话、Prompt、凭据、文件内容、
|
||||
路径、Provider 原始响应或远端 Agent 日志。
|
||||
|
||||
---
|
||||
|
||||
## 13. 当前对接状态
|
||||
|
||||
截至 2026-08-25：
|
||||
|
||||
1. 生产 Origin 已确定为 `https://imp.mesalogo.com`，HTTPS、HSTS 和健康检查正常。
|
||||
2. `/api/v1/feedback` 已返回符合 v1 契约的严格校验错误，无副作用探针未创建记录。
|
||||
3. `goodbuddy` 产品已启用，实际提交返回 `GOODBUDDY-000001`。
|
||||
4. GoodBuddy 客户端已完成 Shared、Main、IPC、Preload、About UI、双语文案、截图和
|
||||
生命周期实现。
|
||||
5. 服务端公开 schema、字段长度和 5 MiB 截图上限与客户端一致。
|
||||
6. 隔离 Electron 实例已完成浅色、深色、600×800 窄窗口、焦点与背景隔离、截图预览和
|
||||
真实生产提交验收。
|
||||
@@ -0,0 +1,14 @@
|
||||
# 知识库
|
||||
|
||||
知识库负责资料导入、解析、分块、索引、检索、图谱和带来源的知识问答。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [知识库检索与分块增强 PRD](./prd.md) | 检索、分块、诊断和产品验收 |
|
||||
| [User Stories](./user-stories.md) | 知识使用者、维护者和调试者场景 |
|
||||
| [本地文本向量技术设计](./local-embedding-technical-design.md) | 本地与兼容向量连接、模型包、索引和进程边界 |
|
||||
| [知识检索评估](./retrieval-evaluation.md) | 检索质量评估方法、数据集、指标和门槛 |
|
||||
|
||||
当前尚未拆出统一功能逻辑、UI 设计和功能进度文档。
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,636 @@
|
||||
# 知识库检索与分块增强 PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 实施中 |
|
||||
| 版本 | 0.2 |
|
||||
| 日期 | 2026-08-22 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 实施范围 | 第一阶段：可用、可见、可诊断；第二阶段：可调、可优化、可维护 |
|
||||
| 相关设计 | [本地文本向量模型与连接设计](./local-embedding-technical-design.md) |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
GoodBuddy 已具备本地多知识库、文件与目录同步、网页导入、SQLite FTS5、
|
||||
OpenAI 兼容向量模型、RRF 混合检索、知识图谱、任务状态和来源引用。现有实现
|
||||
优先建立了本地数据主权、安全边界和跨 Runtime 工具授权，但用户仍难以稳定
|
||||
获得“导入资料后即可准确问答”的体验。
|
||||
|
||||
当前主要问题不是缺少知识图谱，而是基础 RAG 链路缺少完整闭环：
|
||||
|
||||
1. 在对话中启用知识库只会开放搜索工具，是否检索仍由模型自行决定。
|
||||
2. 默认向量检索关闭，中文全文检索对自然语言问法和同义表达的召回不足。
|
||||
3. 向量请求失败会降级为全文检索，但知识库页面仍可能显示索引完成。
|
||||
4. 大于 5,000 个向量分块的知识库会跳过向量召回。
|
||||
5. 用户不能独立测试召回、查看各通道得分或确认实际送入模型的上下文。
|
||||
6. 分块参数固定，缺少结构化、父子分块、分块预览和人工修正。
|
||||
7. 引用只能阅读片段，不能查看完整上下文或打开原始来源。
|
||||
|
||||
本项目先完成稳定性和可观测性，再增加高级分块、重排与维护能力。知识图谱
|
||||
继续作为可选召回通道，但不替代全文和向量检索的基础质量。
|
||||
|
||||
## 2. 已确认的产品决策
|
||||
|
||||
1. 保持本地优先，不引入必须联网的托管知识库服务。
|
||||
2. 保持 Electron Main、Preload、Renderer 的安全边界，Renderer 不直接读取
|
||||
数据库、原文件或向量。
|
||||
3. 保留“模型按需检索”，并新增“每次先检索”模式。后者必须由 Main 进程
|
||||
预检索，不能只依赖提示词要求模型调用工具。
|
||||
4. 知识库新建后不默认启用全部已有知识库；对话中的范围继续由用户显式选择。
|
||||
5. 向量服务不可用时保留全文与中文检索，但必须返回明确降级状态。这是可见的检索通道
|
||||
降级，不得自动切换内置连接、用户添加的 OpenAI 兼容连接或其他向量模型。
|
||||
6. 中文召回使用应用内可控的 CJK n-gram 索引，不新增远程服务依赖。
|
||||
7. 混合检索保留 RRF 候选融合，并增加本地确定性重排、可选的
|
||||
Cohere/Jina 兼容学习型重排、最低相关度和上下文预算。学习型重排失败时
|
||||
安全降级，不影响全文、向量和图谱召回。
|
||||
8. 向量搜索取消 5,000 分块静默失效，使用有界内存的分页扫描。在没有稳定
|
||||
跨平台向量扩展前，接受本地 CPU 线性扫描，并持续显示性能诊断。
|
||||
9. 向量索引兼容性同时校验 Provider、Model、维度和 Provider Fingerprint。
|
||||
同名模型切换端点后，旧向量不能继续参与召回。Fingerprint 的完整模型、编码与
|
||||
数据路径定义以[本地文本向量模型与连接设计](./local-embedding-technical-design.md)
|
||||
为准。
|
||||
10. 失败或取消的重建不能停用上一版已就绪索引。新索引只有完整校验成功后才
|
||||
原子替换当前服务版本。
|
||||
11. 分块设置属于知识库，修改后不会伪装为立即生效。用户需要显式重建索引。
|
||||
12. 分块允许预览、编辑、启用、停用和删除。来源再次同步可能覆盖人工修改，
|
||||
UI 必须在修改前持续说明该行为。
|
||||
13. 第一阶段和第二阶段均不新增付费或外部模型调用。现有 Embeddings 调用仍由
|
||||
用户配置决定。
|
||||
14. Ask 的运行时边界保持只读。知识库内容始终被标记为不可信证据，
|
||||
不能成为系统指令。
|
||||
15. 向量连接是 GoodBuddy Main 管理的知识服务依赖，不是 Agent Runtime 模型。它不进入
|
||||
直连模型、OpenCode、Continue、DeepSeek Harness、远程 Runtime 或项目 Runtime 的
|
||||
模型选择、配置和凭据边界。
|
||||
16. Runtime 只能获得 Main 检索后选出的有界文本证据、来源引用和脱敏诊断，不能获得
|
||||
Embedding Provider、连接 Profile、Endpoint、API Key、模型目录、Tokenizer、原始向量
|
||||
或索引 Fingerprint。
|
||||
|
||||
## 3. 目标
|
||||
|
||||
### 3.1 用户目标
|
||||
|
||||
- 明确知道本次回答是否检索、检索了哪些知识库，以及是否发生降级。
|
||||
- 在知识库页面输入真实问题，查看命中分块、通道、得分和最终上下文。
|
||||
- 为不同文档选择适合的分块模式，并在导入前理解影响。
|
||||
- 查看和修正错误分块，不需要删除并重新导入整个来源。
|
||||
- 从回答引用查看完整上下文，并打开对应本地文件或网页。
|
||||
- 在向量、解析或图谱失败时获得可恢复的状态和明确操作。
|
||||
|
||||
### 3.2 产品目标
|
||||
|
||||
- 默认中文问法在没有向量模型时仍具有可用的关键词召回。
|
||||
- 向量服务故障、大知识库和模型变更不再产生静默空结果。
|
||||
- 建立可复现的检索调试入口，支持固定问题进行回归测试。
|
||||
- 将解析、全文、向量和图谱状态拆分，避免“索引完成”误导。
|
||||
- 为后续元数据过滤、远程 Rerank Provider 和自动评测保留稳定契约。
|
||||
|
||||
### 3.3 质量目标
|
||||
|
||||
- 中文同义改写测试集的 Recall@5 相比现有全文检索基线提升至少 30%。
|
||||
- 检索测试结果必须在本机重复执行时保持稳定排序。
|
||||
- 任意向量失败都必须在检索诊断或任务状态中可见。
|
||||
- 10,000 个分块的知识库不得因固定上限返回空向量结果。
|
||||
- 每条展示引用都能找到仍存在且属于已授权知识库的分块和文档。
|
||||
- 检索输出和上下文拼装均遵守字符、结果数和 IPC 大小上限。
|
||||
|
||||
## 4. 非目标
|
||||
|
||||
本项目不包含：
|
||||
|
||||
- 团队共享知识库、SSO、SCIM 或跨设备同步。
|
||||
- 企业级 ACL、文档级角色继承和远程权限同步。
|
||||
- 云端网站爬虫、Notion、飞书、语雀等第三方连接器。
|
||||
- MinerU、PaddleOCR-VL 或其他远程文档解析服务。
|
||||
- 专用向量数据库、外部 Elasticsearch 或打包平台原生向量扩展。
|
||||
- 托管重排服务账户、计费或供应商绑定；仅提供通用兼容接口配置。
|
||||
- 自动问题生成、FAQ 生成和训练数据标注平台。
|
||||
- 完整 RAG 离线评测平台。第二阶段只提供手动检索测试与可导出的诊断信息。
|
||||
- 在应用内高保真渲染所有原始 Office 和 PDF 文档。
|
||||
- 把向量连接用作 LLM、Agent Runtime 模型或 Runtime 模型网关。
|
||||
- 让 Runtime 直接调用 Embeddings Endpoint、内置推理进程或向量数据库。
|
||||
- 未经独立设计就把知识库向量连接扩展到记忆、自动化、项目文件搜索或其他应用服务。
|
||||
|
||||
## 5. 竞品基线与 GoodBuddy 定位
|
||||
|
||||
截至 2026-08-11，Dify、FastGPT 和 RAGFlow 的公开文档均把检索测试、可配置
|
||||
分块和可调检索参数作为知识库基础能力：
|
||||
|
||||
| 能力 | Dify | FastGPT | RAGFlow | GoodBuddy 本期 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 检索测试 | 支持 | 支持 | 支持 | 第一阶段支持 |
|
||||
| Top K / 阈值 | 支持 | 支持 | 支持 | 第一阶段支持 |
|
||||
| 全文 + 向量 | 支持 | 支持 | 支持 | 已有，第一阶段增强中文 |
|
||||
| Rerank | 模型 Rerank | 模型 Rerank | 模型 Rerank | 本地确定性与可选兼容模型重排 |
|
||||
| 父子分块 | 支持 | 可通过索引与大分块组合 | 支持多种切分策略 | 第二阶段支持 |
|
||||
| 分块维护 | 支持内容维护 | 支持数据维护 | 支持块级检查 | 第二阶段支持 |
|
||||
| 深度文档理解 | 中等 | 中等 | 强 | 继续复用本地解析与 OCR |
|
||||
| 本地目录监听 | 非核心 | 非核心 | 非核心 | GoodBuddy 差异化能力 |
|
||||
| 本地可编辑图谱 | 非核心 | 非核心 | 部分版本支持 GraphRAG | GoodBuddy 差异化能力 |
|
||||
|
||||
本期不复制竞品的云端工作流平台，而是将其成熟 RAG 交互映射为桌面、本地、
|
||||
受控的数据链路。
|
||||
|
||||
参考公开文档：
|
||||
|
||||
- Dify Knowledge：
|
||||
<https://docs.dify.ai/en/use-dify/knowledge/readme>
|
||||
- Dify 检索测试：
|
||||
<https://docs.dify.ai/en/use-dify/knowledge/test-retrieval>
|
||||
- Dify 分块设置：
|
||||
<https://docs.dify.ai/en/use-dify/knowledge/create-knowledge/chunking-and-cleaning>
|
||||
- FastGPT 知识库搜索方案和参数：
|
||||
<https://doc.fastgpt.io/docs/introduction/guide/knowledge_base/dataset_engine>
|
||||
- RAGFlow Dataset 配置：
|
||||
<https://ragflow.io/docs/configure_knowledge_base>
|
||||
- RAGFlow 检索测试：
|
||||
<https://ragflow.io/docs/run_retrieval_test>
|
||||
|
||||
## 6. 信息架构
|
||||
|
||||
知识工作区继续使用主从布局和现有四个页签：
|
||||
|
||||
```text
|
||||
知识库
|
||||
├─ 文档与来源
|
||||
│ ├─ 来源管理
|
||||
│ ├─ 检索测试入口
|
||||
│ ├─ 文档状态
|
||||
│ └─ 分块查看与维护
|
||||
├─ 知识图谱
|
||||
├─ 任务中心
|
||||
└─ 设置
|
||||
├─ 检索设置
|
||||
├─ 分块设置
|
||||
└─ 图谱设置
|
||||
```
|
||||
|
||||
“检索测试”是当前知识库的高频诊断操作，通过知识库标题区次操作打开独立
|
||||
工作台，不新增第五个一级页签。
|
||||
|
||||
全局向量模型仍在“设置 → 模型连接 → 向量模型”中配置。GoodBuddy 内置连接和用户添加的
|
||||
OpenAI 兼容连接使用同一连接列表；其界面、数据路径及切换语义以
|
||||
[本地文本向量模型与连接设计](./local-embedding-technical-design.md)
|
||||
为准，知识库页面只显示当前模型、索引兼容性、覆盖率和重建操作。“模型连接”是设置入口
|
||||
名称，不表示向量连接可以分配给 Agent Runtime；项目 Runtime 和 Agent Runtime 的模型
|
||||
选择中不显示向量连接。
|
||||
|
||||
知识检索与 Runtime 的关系固定为：
|
||||
|
||||
```text
|
||||
用户问题
|
||||
→ Main / KnowledgeService 使用当前向量连接检索
|
||||
→ Main 生成有界文本证据、引用和检索诊断
|
||||
→ 当前 Runtime 仅消费这些不可信检索结果
|
||||
```
|
||||
|
||||
`always` 模式由 Main 在启动 Runtime 前完成检索；`auto` 模式中的 `knowledge_search`
|
||||
也只允许 Runtime 调用 Main 的有界知识工具。两种模式都不把向量连接、凭据、模型文件、
|
||||
Tokenizer、原始向量或索引访问能力传入 Runtime。切换 Runtime 不改变当前向量连接。
|
||||
|
||||
对话输入区的知识范围弹层包含：
|
||||
|
||||
1. 已启用知识库多选。
|
||||
2. 检索方式：模型按需检索、每次先检索。
|
||||
3. 当前范围为空、索引降级或向量未配置时的短说明。
|
||||
|
||||
## 7. 第一阶段：可用、可见、可诊断
|
||||
|
||||
### 7.1 检索方式
|
||||
|
||||
新增请求级 `knowledgeRetrievalMode`：
|
||||
|
||||
| 值 | 用户文案 | 行为 |
|
||||
| --- | --- | --- |
|
||||
| `auto` | 模型按需检索 | 保留当前 `knowledge_search` 工具，由模型决定是否调用 |
|
||||
| `always` | 每次先检索 | Main 在启动 Runtime 前使用原始用户问题检索一次，再把有界证据作为不可信上下文提供给 Runtime |
|
||||
|
||||
规则：
|
||||
|
||||
- 没有启用知识库时不显示为“已检索”。
|
||||
- `always` 预检索后仍保留 `knowledge_search`，模型可以改写查询再次检索。
|
||||
- 预检索零结果不阻止回答，但必须显示“已检索，未找到相关内容”。
|
||||
- 预检索失败不得自动扩大范围或访问未选知识库。
|
||||
- 图片生成能力不执行知识预检索。
|
||||
- Ask 和 Execute 使用相同的只读检索范围。
|
||||
|
||||
### 7.2 中文全文检索
|
||||
|
||||
在现有 `unicode61` FTS 之外增加本地 CJK n-gram 检索文本：
|
||||
|
||||
- 连续汉字生成二元词组，保留必要的单字符短查询回退。
|
||||
- 拉丁字母和数字使用 NFKC、大小写归一化和现有 FTS。
|
||||
- 多个查询词使用召回优先的 OR 候选，再通过覆盖率和短语命中重排。
|
||||
- 不把整句中文问题转换成“所有汉字必须同时出现”的条件。
|
||||
- 索引更新、分块编辑、停用和删除必须同步更新 CJK 索引。
|
||||
- 数据库迁移必须为已有分块有界回填，不要求用户重新导入。
|
||||
|
||||
### 7.3 检索设置
|
||||
|
||||
每个知识库保存以下设置：
|
||||
|
||||
| 字段 | 范围 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `topK` | 1 至 20 | 6 |
|
||||
| `minimumVectorSimilarity` | 0 至 1 | 0（不过滤低相似度结果） |
|
||||
| `ftsWeight` | 0 至 2 | 1 |
|
||||
| `vectorWeight` | 0 至 2 | 1 |
|
||||
| `graphWeight` | 0 至 2 | 0.8 |
|
||||
| `candidateMultiplier` | 2 至 10 | 4 |
|
||||
| `contextMaxCharacters` | 2,000 至 48,000 | 16,000 |
|
||||
| `adjacentChunkCount` | 0 至 2 | 0 |
|
||||
| `localRerankEnabled` | 布尔值 | false |
|
||||
|
||||
至少一个召回通道权重大于 0。图谱未启用时，图谱权重只读显示为不可用。
|
||||
向量模型未启用或索引不兼容时，向量权重保留但当前请求降级。
|
||||
|
||||
### 7.4 检索测试工作台
|
||||
|
||||
用户输入最多 4,000 字符的问题，工作台显示：
|
||||
|
||||
- 当前知识库和生效设置。
|
||||
- 总耗时、各通道耗时和候选数。
|
||||
- 请求通道、实际使用通道和降级原因。
|
||||
- 最终结果序号、文档、定位、片段和最终相关度。
|
||||
- FTS、CJK、向量、图谱的独立排名与向量相似度。
|
||||
- 本地重排前后排名。
|
||||
- 相邻分块或父块合并后的实际上下文。
|
||||
- “查看分块”“打开来源”操作。
|
||||
|
||||
图谱通道对中文自然语言问题生成有界 CJK 二元词和拉丁关键词，在实体名称、
|
||||
别名和类型中确定种子，再沿具有有效文档证据的关系执行有界多跳扩展。图谱探索页
|
||||
搜索到实体时保留其一跳邻居和关系上下文，并继续允许从实体或关系打开原始证据。
|
||||
|
||||
检索测试不创建聊天消息、不写入会话历史、不调用 LLM，也不改变知识库内容。
|
||||
|
||||
### 7.5 可扩展向量搜索
|
||||
|
||||
移除“超过 5,000 个候选则返回空结果”的逻辑：
|
||||
|
||||
1. 按稳定游标分页读取同一知识库、Provider、Model 和维度的向量。
|
||||
2. 每批计算余弦相似度。
|
||||
3. 内存中只保留候选上限所需的最佳结果。
|
||||
4. 支持取消和应用关闭。
|
||||
5. 维度、校验和或索引状态不匹配的向量不参与结果。
|
||||
6. 诊断返回扫描数量和向量耗时。
|
||||
7. Provider Fingerprint 不匹配时标记索引不兼容，不回退到同名旧模型向量。
|
||||
|
||||
线性扫描是本期跨平台保底实现。后续接入稳定向量扩展时不得改变上层契约。
|
||||
|
||||
### 7.6 状态与降级
|
||||
|
||||
文档状态拆分为：
|
||||
|
||||
| 状态 | 含义 |
|
||||
| --- | --- |
|
||||
| 解析 | 等待、运行、完成、失败 |
|
||||
| 全文索引 | 等待、完成、失败 |
|
||||
| 向量索引 | 未启用、等待、运行、完成、失败、不兼容 |
|
||||
| 图谱 | 未启用、按需、等待、运行、完成、失败 |
|
||||
|
||||
知识库汇总不得仅以“文档 metadata 不是 failed”计算完成。UI 至少显示：
|
||||
|
||||
- 可用于全文检索的文档数。
|
||||
- 已完成向量化的文档数。
|
||||
- 失败文档数。
|
||||
- 当前向量模型与索引是否兼容。
|
||||
|
||||
降级事件包括：
|
||||
|
||||
- 未配置向量模型。
|
||||
- 查询向量生成失败。
|
||||
- 当前模型没有匹配索引。
|
||||
- 部分文档向量失败。
|
||||
- 图谱关闭或没有证据。
|
||||
- 结果被相关度或上下文预算过滤。
|
||||
|
||||
### 7.7 引用查看
|
||||
|
||||
每条引用增加稳定 `chunkId`、最终相关度和检索通道。用户展开引用后可以：
|
||||
|
||||
1. 查看命中分块。
|
||||
2. 查看相邻分块或父块形成的完整上下文。
|
||||
3. 查看知识库、文档、来源和定位。
|
||||
4. 对本地文件调用 Main 校验后的 `shell.openPath`。
|
||||
5. 对 HTTP(S) 来源调用 Main 校验后的外部打开。
|
||||
|
||||
Renderer 不能提交任意路径或 URL。Main 必须根据 `libraryId`、`documentId` 和
|
||||
`chunkId` 重新读取已保存来源并验证归属。
|
||||
|
||||
界面把该列表描述为“本次检索证据”或“已查阅来源”，不把仅被召回的片段
|
||||
自动宣称为回答中某个句子的精确出处。后续只有经过稳定 Citation ID 校验的
|
||||
句级标注才能使用更强的“该句引用”语义。
|
||||
|
||||
## 8. 第二阶段：可调、可优化、可维护
|
||||
|
||||
### 8.1 分块模式
|
||||
|
||||
每个知识库选择一种模式：
|
||||
|
||||
| 模式 | 行为 | 适用内容 |
|
||||
| --- | --- | --- |
|
||||
| 固定分块 | 按目标长度、重叠和自然边界切分 | 普通文本、日志、代码 |
|
||||
| 结构分块 | 优先保持解析 section、Markdown 标题和段落结构 | 手册、制度、长文档 |
|
||||
| 父子分块 | 小块用于召回，大块用于模型上下文 | 长篇说明、合同、研究资料 |
|
||||
|
||||
设置：
|
||||
|
||||
| 字段 | 范围 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `mode` | `fixed` / `structure` / `parent-child` | `structure` |
|
||||
| `targetCharacters` | 400 至 8,000 | 1,600 |
|
||||
| `overlapCharacters` | 0 至目标长度的 40% | 160 |
|
||||
| `parentCharacters` | 1,600 至 16,000 | 4,800 |
|
||||
| `childCharacters` | 300 至 4,000 | 900 |
|
||||
|
||||
父子分块要求：
|
||||
|
||||
- 父块只作为上下文，不进入 FTS、CJK 或向量候选。
|
||||
- 子块用于召回，并保存父块关联。
|
||||
- 引用默认突出子块，同时允许查看父块全文。
|
||||
- 父块和子块总输出仍受上下文预算限制。
|
||||
|
||||
### 8.2 本地与学习型重排
|
||||
|
||||
第二阶段提供不调用外部模型的可选本地重排。评分特征包括：
|
||||
|
||||
- 原始 RRF 排名。
|
||||
- 中文和拉丁词覆盖率。
|
||||
- 完整短语命中。
|
||||
- 文档标题、分块标题和路径命中。
|
||||
- 向量相似度。
|
||||
- 同文档重复结果惩罚。
|
||||
|
||||
重排结果必须：
|
||||
|
||||
- 归一化为 0 至 1 的 `relevance`。
|
||||
- 对相同输入和索引保持确定性。
|
||||
- 保留重排前排名和各特征得分用于诊断。
|
||||
- 在关闭时完全保留原有 RRF 排序。
|
||||
|
||||
学习型模式使用 Main 进程中的 Cohere/Jina 兼容客户端，凭据只进入加密设置和
|
||||
Main 进程。请求限制为 100 个候选、每个候选 8,000 字符，并具有 15 秒默认
|
||||
超时、取消传播和有界响应。失败时可回退本地重排或 RRF，并只返回脱敏诊断。
|
||||
|
||||
### 8.3 相邻分块合并与上下文预算
|
||||
|
||||
- 对最终候选按文档和 ordinal 合并相邻分块。
|
||||
- 不把同一分块重复放入上下文。
|
||||
- 保留每个命中分块的引用定位。
|
||||
- 按相关度从高到低消耗 `contextMaxCharacters`。
|
||||
- 单个超长父块按安全边界截断并标记 `truncated`。
|
||||
- 不允许低排名结果挤掉已经选中的高排名证据。
|
||||
|
||||
### 8.4 分块管理
|
||||
|
||||
文档行提供“查看分块”，打开分块管理对话框：
|
||||
|
||||
- 显示 ordinal、角色、标题、定位、字符数、启用状态和内容预览。
|
||||
- 支持分页和文档内搜索。
|
||||
- 支持编辑内容。
|
||||
- 支持启用或停用。
|
||||
- 支持删除，并说明来源同步可能重新创建分块。
|
||||
- 编辑后更新 FTS 和 CJK 索引，并使旧向量失效。
|
||||
- 已配置向量模型时，编辑操作完成后为该文档重建向量。
|
||||
- 删除最后一个可检索分块时，文档显示“无可检索内容”，不能显示完全就绪。
|
||||
|
||||
高影响删除使用具体确认文案。普通启停使用共享 Switch，并声明
|
||||
`role="switch"`。
|
||||
|
||||
### 8.5 单文档与全库重建
|
||||
|
||||
- 单文档重建重新读取来源、解析、分块、全文索引、向量和图谱。
|
||||
- 全库重建按来源顺序执行，并显示文档级进度。
|
||||
- 修改分块模式或关键参数后，知识库显示“设置已更新，等待重建”。
|
||||
- 重建采用文档级原子替换，失败时保留上一版可用分块和向量。
|
||||
- 用户可以取消全库重建；已经成功替换的文档保持可用。
|
||||
- 文件不存在、网页失败或 OCR 不可用时保留可重试错误。
|
||||
- 单来源允许的 2,000 个文件必须全部参与增量同步、删除检测和校验和跳过，
|
||||
不受普通页面 500 项列表上限影响。
|
||||
|
||||
## 9. 数据模型与兼容性
|
||||
|
||||
### 9.1 KnowledgeBase
|
||||
|
||||
知识库增加版本化设置：
|
||||
|
||||
```ts
|
||||
type KnowledgeRetrievalSettings = {
|
||||
version: 1
|
||||
topK: number
|
||||
minimumVectorSimilarity: number
|
||||
ftsWeight: number
|
||||
vectorWeight: number
|
||||
graphWeight: number
|
||||
candidateMultiplier: number
|
||||
contextMaxCharacters: number
|
||||
adjacentChunkCount: number
|
||||
localRerankEnabled: boolean
|
||||
}
|
||||
|
||||
type KnowledgeChunkingSettings = {
|
||||
version: 1
|
||||
mode: 'fixed' | 'structure' | 'parent-child'
|
||||
targetCharacters: number
|
||||
overlapCharacters: number
|
||||
parentCharacters: number
|
||||
childCharacters: number
|
||||
}
|
||||
```
|
||||
|
||||
SQLite 使用 JSON 列保存设置，读写均经过共享 Zod Schema。迁移后的旧知识库使用
|
||||
与当前行为接近的兼容默认值，不自动重建已有分块。
|
||||
|
||||
### 9.2 Chunk
|
||||
|
||||
分块增加以下语义：
|
||||
|
||||
```ts
|
||||
type KnowledgeChunkRole = 'standalone' | 'parent' | 'child'
|
||||
|
||||
type KnowledgeChunkState = {
|
||||
enabled: boolean
|
||||
role: KnowledgeChunkRole
|
||||
parentChunkId?: string
|
||||
manuallyEdited: boolean
|
||||
updatedAt?: string
|
||||
}
|
||||
```
|
||||
|
||||
实现可以使用显式列或受校验 metadata，但查询必须为旧数据提供默认值：
|
||||
|
||||
- 缺少 `enabled` 时视为 `true`。
|
||||
- 缺少 `role` 时视为 `standalone`。
|
||||
- 父块不参与召回索引。
|
||||
|
||||
### 9.3 检索响应
|
||||
|
||||
```ts
|
||||
type KnowledgeRetrievalResponse = {
|
||||
query: string
|
||||
durationMs: number
|
||||
settings: KnowledgeRetrievalSettings
|
||||
diagnostics: {
|
||||
requestedChannels: KnowledgeRetrievalChannel[]
|
||||
usedChannels: KnowledgeRetrievalChannel[]
|
||||
degradedChannels: Array<{
|
||||
channel: KnowledgeRetrievalChannel
|
||||
reason: string
|
||||
}>
|
||||
candidateCounts: Partial<Record<KnowledgeRetrievalChannel, number>>
|
||||
}
|
||||
results: KnowledgeRetrievalResult[]
|
||||
context: {
|
||||
characterCount: number
|
||||
truncated: boolean
|
||||
groups: KnowledgeContextGroup[]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
错误、诊断和引用不得包含 API Key、Authorization Header、完整私人文档或未经
|
||||
限制的 Provider 响应。
|
||||
|
||||
## 10. IPC 与安全边界
|
||||
|
||||
新增或扩展的 IPC：
|
||||
|
||||
- `knowledge:retrieve`
|
||||
- `knowledge:settings:update`
|
||||
- `knowledge:document:rebuild`
|
||||
- `knowledge:library:rebuild`
|
||||
- `knowledge:chunks:list`
|
||||
- `knowledge:chunk:update`
|
||||
- `knowledge:chunk:delete`
|
||||
- `knowledge:reference:context`
|
||||
- `knowledge:reference:open`
|
||||
|
||||
要求：
|
||||
|
||||
- 所有输入由共享 Zod Schema 校验。
|
||||
- 所有处理器校验可信 Renderer sender。
|
||||
- ID 必须重新检查知识库、来源、文档和分块归属。
|
||||
- 列表使用有界分页，单次最多返回 200 个分块。
|
||||
- 内容编辑限制单块最大字符数。
|
||||
- 外部打开只接受数据库已保存的本地普通文件或 HTTP(S) URL。
|
||||
- 不向 Preload 暴露原始数据库、Electron `shell` 或文件系统 API。
|
||||
- 更新与重建遵守取消、超时、应用关闭和有界错误规则。
|
||||
|
||||
## 11. 交互与无障碍
|
||||
|
||||
- 复用 `PageTabs`、`SegmentedControl`、共享 Switch 和应用通知。
|
||||
- 检索方式是互斥选项，使用 `SegmentedControl` 或语义化单选组。
|
||||
- 分块启停是持久二元状态，使用 `role="switch"`。
|
||||
- 检索结果列表使用可访问名称，得分不得只用颜色表达。
|
||||
- 检索工作台打开后焦点进入问题输入框，关闭后返回触发按钮。
|
||||
- 分块编辑和删除对话框遵守焦点陷阱、Escape 和焦点恢复。
|
||||
- 异步成功使用应用通知；字段错误、检索进度和可就地恢复错误保留在工作台。
|
||||
- 窄窗口下检索结果改为单列，配置摘要保持可读，不隐藏降级状态。
|
||||
|
||||
## 12. 失败与恢复
|
||||
|
||||
| 场景 | 行为 |
|
||||
| --- | --- |
|
||||
| 向量查询失败 | 继续已配置的全文、中文和图谱通道，显示降级原因，不切换向量 Provider 或模型 |
|
||||
| 部分文档无向量 | 使用可用文档，显示完成数和失败数 |
|
||||
| CJK 索引迁移失败 | 回滚迁移，不损坏旧 FTS |
|
||||
| 重排失败 | 回退 RRF 排序并显示诊断 |
|
||||
| 分块编辑后向量失败 | 保留编辑和全文索引，标记向量失败 |
|
||||
| 单文档重建失败 | 保留上一版可用索引 |
|
||||
| 同名模型端点变化 | 旧 Fingerprint 索引标记不兼容，等待重建 |
|
||||
| 新向量重建失败 | 保留上一版就绪向量继续服务，单独记录失败尝试 |
|
||||
| 图谱模型空响应、超时或瞬时服务错误 | 按不超过约 8,192 个估算 Token 组织独立抽取批次，每批最多尝试两次；部分批次成功时发布已验证结果并在任务中显示具体警告；所有批次失败时图谱任务失败，但新文档的全文索引仍可发布，已有文档的显式重建继续保留上一版可用索引 |
|
||||
| 原文件已移动 | 显示来源不可用，提供重试或移除 |
|
||||
| 引用对象已删除 | 显示引用已失效，不打开任意替代路径 |
|
||||
| 上下文超预算 | 按排名截断并明确标记 |
|
||||
| 请求取消或应用关闭 | 停止新批次，释放句柄，不留下半替换索引 |
|
||||
|
||||
## 13. 埋点与评测
|
||||
|
||||
GoodBuddy 不上传私人检索查询或文档内容。本地诊断至少记录有界统计：
|
||||
|
||||
- 检索模式。
|
||||
- 启用知识库数量。
|
||||
- 各通道候选数和耗时。
|
||||
- 是否发生降级。
|
||||
- 最终结果数和上下文字符数。
|
||||
- 重建文档数、成功数、失败数和取消状态。
|
||||
- 图谱抽取批次数、部分失败警告和具体失败原因。
|
||||
|
||||
手动验收使用仓库内不含私人内容的固定样例集，覆盖：
|
||||
|
||||
- 中文自然语言改写和同义词。
|
||||
- 中英文混合产品名。
|
||||
- 精确编号、路径和代码标识。
|
||||
- 多文档冲突信息。
|
||||
- 无答案问题。
|
||||
- 10,000 个以上分块。
|
||||
- 向量服务断开和模型维度变化。
|
||||
|
||||
## 14. 实施顺序
|
||||
|
||||
### 14.1 第一阶段
|
||||
|
||||
1. 共享设置、请求和检索响应契约。
|
||||
2. SQLite 迁移和 CJK 索引。
|
||||
3. 可扩展向量扫描、检索诊断和状态模型。
|
||||
4. 检索设置与工作台。
|
||||
5. 对话“每次先检索”。
|
||||
6. 引用上下文和打开来源。
|
||||
7. 第一阶段单元、IPC 和 Renderer 测试。
|
||||
|
||||
### 14.2 第二阶段
|
||||
|
||||
1. 结构分块和父子分块。
|
||||
2. 本地重排与相关度。
|
||||
3. 相邻块合并和上下文预算。
|
||||
4. 分块预览、编辑、启停和删除。
|
||||
5. 单文档与全库重建。
|
||||
6. 第二阶段回归、性能和生产构建验证。
|
||||
|
||||
## 15. 验收标准
|
||||
|
||||
### 15.1 第一阶段
|
||||
|
||||
- 用户可在对话中选择“模型按需检索”或“每次先检索”。
|
||||
- “每次先检索”在 Runtime 启动前产生检索诊断和引用，即使模型未调用工具。
|
||||
- 未配置向量模型时，中文改写问题仍能通过 CJK 索引召回相关分块。
|
||||
- 向量查询失败时回答可继续，界面明确显示已降级。
|
||||
- 内置连接和用户添加的 OpenAI 兼容连接之间不会自动切换；用户连接的实际数据去向持续
|
||||
可见，内置连接不重复展示固定本地路径。
|
||||
- 项目 Runtime 和 Agent Runtime 的模型选择不显示向量连接。
|
||||
- Runtime 只获得有界文本证据、引用和脱敏诊断，不获得向量 Provider、凭据或原始向量。
|
||||
- 切换直连模型、OpenCode、Continue、DeepSeek Harness 或远程 Runtime 不改变当前向量
|
||||
连接。
|
||||
- 10,000 个分块的向量测试能够返回正确 Top K，不出现固定上限空结果。
|
||||
- 同名模型切换端点后，不会读取 Fingerprint 不匹配的旧向量。
|
||||
- 重建失败时，上一版已就绪向量仍能继续召回。
|
||||
- 包含 2,000 个文件的目录同步能够处理第 501 至 2,000 个文档的修改与删除。
|
||||
- 检索测试展示通道、候选数、排名、相关度、上下文和降级原因。
|
||||
- 引用可以查看完整上下文并打开 Main 校验后的来源。
|
||||
- 查询长度在共享契约、IPC、MCP 和数据库层保持一致。
|
||||
|
||||
### 15.2 第二阶段
|
||||
|
||||
- 用户可选择固定、结构或父子分块并显式重建。
|
||||
- 父块不参与召回，子块命中后可提供父块上下文。
|
||||
- 本地重排可以开启或关闭，并显示重排前后排名。
|
||||
- 上下文严格遵守字符预算，重复和相邻片段按规则合并。
|
||||
- 用户可预览、编辑、启停和删除分块。
|
||||
- 分块修改后 FTS、CJK 和向量状态保持一致。
|
||||
- 单文档重建失败不会破坏上一版可用索引。
|
||||
- 所有新增操作可用键盘完成，并在浅色、深色和窄窗口下可用。
|
||||
|
||||
### 15.3 工程验证
|
||||
|
||||
所有源代码变更完成后必须通过：
|
||||
|
||||
```text
|
||||
npm test
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm run build
|
||||
```
|
||||
|
||||
外部或付费模型调用不属于自动验证，只有获得明确授权后才运行。
|
||||
@@ -0,0 +1,112 @@
|
||||
# Knowledge retrieval evaluation
|
||||
|
||||
GoodBuddy's retrieval evaluation is an offline Vitest suite that exercises the
|
||||
real `KnowledgeService` and `KnowledgeDatabase` retrieval path without changing
|
||||
production data. Run it with:
|
||||
|
||||
```text
|
||||
npm run eval:retrieval
|
||||
```
|
||||
|
||||
By default the suite returns the report only to its tests and leaves no file.
|
||||
To retain a JSON report, set `GOODBUDDY_RETRIEVAL_EVAL_OUTPUT` to a
|
||||
workspace-relative file path. Absolute paths and paths escaping the workspace
|
||||
are rejected.
|
||||
|
||||
## Corpus and labels
|
||||
|
||||
The committed `synthetic-bilingual-v1` fixture is wholly synthetic, bilingual
|
||||
(Simplified Chinese and English), and CC0. Stable document, chunk, and query IDs
|
||||
make changes reviewable. The strict Zod schema bounds every field and rejects
|
||||
unknown fields, duplicate or dangling IDs, inexact annotations, and
|
||||
path/endpoint/secret-like values. It also rejects degenerate label sets: each
|
||||
language must contain both an answerable and a no-answer query.
|
||||
|
||||
Each answerable query has graded chunk judgments:
|
||||
|
||||
- `3`: directly answers the question.
|
||||
- `2`: substantially answers it.
|
||||
- `1`: useful supporting evidence.
|
||||
|
||||
Every judgment also contains one or more exact, verbatim answer spans from its
|
||||
chunk. A no-answer query has no judgments. When adding labels, two reviewers
|
||||
should independently check relevance grades and exact spans, resolve
|
||||
disagreements, then update the fixture version or ID when the corpus meaning
|
||||
changes.
|
||||
|
||||
## Evaluation design
|
||||
|
||||
Each run creates a temporary SQLite database and directly seeds the production
|
||||
knowledge classes with stable IDs. It uses deterministic in-memory embedding
|
||||
providers with stable fingerprints; it does not read API keys, environment
|
||||
provider settings, user databases, or network resources. Five ablations use
|
||||
the same corpus:
|
||||
|
||||
1. lexical retrieval only;
|
||||
2. topic-agnostic deterministic token-hash vector retrieval;
|
||||
3. handcrafted-alias vector retrieval;
|
||||
4. lexical/vector hybrid retrieval;
|
||||
5. hybrid retrieval with the local heuristic reranker.
|
||||
|
||||
The token-hash provider hashes normalized input tokens without topic-specific
|
||||
knowledge, so it is a transparent lexical-overlap vector ablation. The
|
||||
handcrafted bilingual alias provider exists only as **regression plumbing** to
|
||||
exercise vector, hybrid, and rerank production paths with stable cross-language
|
||||
matches. It is fixture-aware and is not an embedding-quality model or a claim
|
||||
about real provider quality.
|
||||
|
||||
The suite runs twice and compares the deterministic projection (IDs, hashes,
|
||||
rank metrics, and failures). Wall-clock latency is intentionally excluded from
|
||||
that equality check.
|
||||
|
||||
## Metrics
|
||||
|
||||
- **Recall@5 / Recall@10:** fraction of all annotated relevant chunks returned
|
||||
within the cutoff, macro-averaged over answerable queries.
|
||||
- **MRR@10:** reciprocal rank of the first relevant chunk, with zero when none
|
||||
appears in the first ten.
|
||||
- **Graded nDCG@10:** discounted cumulative gain using `2^grade - 1`, divided
|
||||
by the ideal graded ordering.
|
||||
- **Context precision:** characters in exact annotated spans found in returned
|
||||
context divided by all returned context characters.
|
||||
- **Context recall:** characters in exact annotated spans found in returned
|
||||
context divided by all annotated span characters.
|
||||
- **No-answer false-positive rate:** no-answer queries that return any result
|
||||
divided by all no-answer queries.
|
||||
- **Latency:** count, minimum, median, p95, maximum, and arithmetic mean in
|
||||
milliseconds for each ablation. These are diagnostic, not deterministic
|
||||
gates.
|
||||
|
||||
Rankings are deduplicated by chunk ID before cutoffs and ranking metrics are
|
||||
computed. Overlapping or nested exact evidence spans are unioned, so duplicate
|
||||
rank entries and overlapping annotations cannot inflate context precision or
|
||||
recall. Aggregate metrics are also emitted per language.
|
||||
|
||||
## Privacy
|
||||
|
||||
Reports contain only fixture/query/ablation IDs, a SHA-256 corpus hash, an
|
||||
evaluation-definition hash, a hash of provider definitions, aggregate metrics,
|
||||
latency summaries, and ID-based actionable failures. The
|
||||
`evaluationDefinitionHash` covers fixture version/ID, raw queries, judgments,
|
||||
retrieval settings, ablations, provider definitions, and metric version; it
|
||||
changes when the evaluated contract changes without disclosing that contract.
|
||||
Reports omit raw queries, document titles, corpus text, snippets/context,
|
||||
source paths, endpoints, fingerprints, model names, credentials, metadata, and
|
||||
vectors. The integration test checks every fixture title, chunk, query, and
|
||||
private provider identifier against the serialized report.
|
||||
|
||||
Retained report paths must be workspace-relative. Resolution uses async
|
||||
filesystem APIs, rejects absolute/traversal paths and null bytes, checks each
|
||||
parent component, and refuses symlink traversal or a symlink destination. The
|
||||
report is first written to a same-directory temporary file and then renamed.
|
||||
|
||||
## Quality gates
|
||||
|
||||
The integration test gates stable lexical, topic-agnostic token-hash,
|
||||
regression-vector, hybrid, context-precision/context-recall, and per-language
|
||||
baselines. It also requires reranked MRR@10 of at least 0.78, reranked nDCG@10
|
||||
of at least 0.75, no-answer false positives no higher than 0.34, and prevents
|
||||
local reranking from reducing hybrid nDCG@10 by more than 0.05. Exact nDCG
|
||||
arithmetic has a focused unit test. Gates are fixture baselines rather than
|
||||
universal production-SLA claims; adjust them only with a reviewed fixture or
|
||||
justified retrieval behavior change.
|
||||
@@ -0,0 +1,524 @@
|
||||
# 知识库检索与分块增强 User Stories
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 实施中 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 关联 PRD | [知识库检索与分块增强 PRD](./prd.md) |
|
||||
|
||||
## 1. 角色
|
||||
|
||||
### 1.1 普通知识使用者
|
||||
|
||||
已经导入公司制度、产品手册或项目资料，希望直接提问并得到稳定、带来源的回答，
|
||||
不需要理解向量、RRF 或分块算法。
|
||||
|
||||
### 1.2 知识库维护者
|
||||
|
||||
负责导入、同步和清理资料，需要知道哪些文档成功、哪些索引失败，以及如何修复
|
||||
错误解析或错误分块。
|
||||
|
||||
### 1.3 RAG 调试者
|
||||
|
||||
需要用真实问题验证召回，比较不同参数和通道，定位“文档里有但没有命中”的
|
||||
原因。
|
||||
|
||||
### 1.4 本地与内网用户
|
||||
|
||||
不能把资料上传到外部知识库服务，希望全文检索、分块、重排和诊断均在本机
|
||||
完成，只在显式配置 Embeddings 后发送有界文本。
|
||||
|
||||
## 2. Epic A：明确控制是否检索
|
||||
|
||||
### US-A1 模型按需检索
|
||||
|
||||
作为普通知识使用者，我希望保留由模型判断是否需要检索的模式，以便一般闲聊
|
||||
不会产生不必要的知识搜索。
|
||||
|
||||
验收：
|
||||
|
||||
- Given 当前启用了至少一个知识库并选择“模型按需检索”
|
||||
- When 用户发送问题
|
||||
- Then Main 只向本次请求开放已选知识库的只读搜索能力
|
||||
- And 模型没有调用知识搜索时，不显示虚假的“已检索”
|
||||
- And 未选中的知识库不可被工具参数扩大范围
|
||||
|
||||
### US-A2 每次先检索
|
||||
|
||||
作为普通知识使用者，我希望选择“每次先检索”，以便模型不能跳过已启用的
|
||||
知识库。
|
||||
|
||||
验收：
|
||||
|
||||
- Given 当前启用了至少一个知识库并选择“每次先检索”
|
||||
- When 用户发送文本问题
|
||||
- Then Main 在 Runtime 启动前使用原始问题执行一次有界检索
|
||||
- And 命中证据以不可信上下文进入 Runtime
|
||||
- And 模型仍可通过只读工具执行后续改写检索
|
||||
- And 页面明确显示“已预检索”“零结果”或“已降级”
|
||||
- And 图片生成请求不执行知识预检索
|
||||
|
||||
### US-A3 请求级范围
|
||||
|
||||
作为普通知识使用者，我希望每次请求只使用我勾选的知识库，以免不相关资料
|
||||
干扰回答。
|
||||
|
||||
验收：
|
||||
|
||||
- 新建知识库后只新增该知识库到当前选择，不自动重新启用已取消的知识库
|
||||
- 删除知识库后从当前范围中移除对应 ID
|
||||
- 同一请求最多启用 20 个知识库
|
||||
- 对话输入区持续显示已选数量和检索方式
|
||||
- 范围为空时检索方式不产生误导状态
|
||||
|
||||
## 3. Epic B：检索可见、可诊断
|
||||
|
||||
### US-B1 打开检索测试
|
||||
|
||||
作为 RAG 调试者，我希望在当前知识库直接输入问题并测试，以便不通过聊天模型
|
||||
也能验证索引。
|
||||
|
||||
验收：
|
||||
|
||||
- 知识库标题区提供“测试检索”次操作
|
||||
- 工作台打开后焦点进入查询输入框
|
||||
- 查询最多 4,000 字符
|
||||
- 测试不创建聊天消息、任务成果或模型调用
|
||||
- 关闭工作台后焦点返回触发按钮
|
||||
|
||||
### US-B2 查看通道诊断
|
||||
|
||||
作为 RAG 调试者，我希望看到每种检索通道的结果和降级原因，以便判断问题来自
|
||||
全文、向量还是图谱。
|
||||
|
||||
验收：
|
||||
|
||||
- 结果显示请求通道和实际使用通道
|
||||
- 结果显示 FTS/CJK、向量和图谱候选数
|
||||
- 结果显示总耗时和有界通道耗时
|
||||
- 向量未配置、请求失败或索引不兼容时显示明确原因
|
||||
- 不在错误或诊断中显示 API Key、Authorization 或完整文档
|
||||
|
||||
### US-B3 查看排名与上下文
|
||||
|
||||
作为 RAG 调试者，我希望看到候选排名、最终相关度和送入模型的上下文，以便
|
||||
解释最终回答为什么使用这些资料。
|
||||
|
||||
验收：
|
||||
|
||||
- 每条结果显示文档、定位、片段和最终排名
|
||||
- 可用时显示全文、向量、图谱独立排名和向量相似度
|
||||
- 启用本地重排后显示重排前排名
|
||||
- 展示相邻块或父块合并后的上下文
|
||||
- 展示上下文字符数、预算和截断状态
|
||||
|
||||
### US-B4 零结果诊断
|
||||
|
||||
作为普通知识使用者，我希望零结果时获得具体原因，而不是只有空列表。
|
||||
|
||||
验收：
|
||||
|
||||
- 区分“知识库为空”“索引不可用”“查询无命中”“被阈值过滤”
|
||||
- 提供修改关键词、检查状态或调整阈值的下一步说明
|
||||
- 零结果不显示为首次使用空状态
|
||||
- 检索测试保留原查询和设置，方便再次执行
|
||||
|
||||
## 4. Epic C：中文与混合检索
|
||||
|
||||
### US-C1 中文自然语言召回
|
||||
|
||||
作为中文用户，我希望不用输入原文中的连续短语，也能找到表达相同意思的内容。
|
||||
|
||||
验收：
|
||||
|
||||
- 中文索引生成连续二元词组
|
||||
- 中文查询不会要求所有不同汉字同时出现
|
||||
- 短查询具有有界单字回退
|
||||
- 中英文、数字和产品标识混合查询仍能召回
|
||||
- 相同查询和索引产生稳定排序
|
||||
|
||||
### US-C2 向量服务降级
|
||||
|
||||
作为本地与内网用户，我希望向量服务断开时仍可使用全文搜索，同时清楚知道
|
||||
语义召回不可用。
|
||||
|
||||
验收：
|
||||
|
||||
- 查询向量失败不阻止 FTS/CJK 和图谱检索
|
||||
- 检索响应包含向量降级原因
|
||||
- 文档状态不把向量失败显示成全部完成
|
||||
- 同名模型切换端点后，Fingerprint 不匹配的旧向量不得参与召回
|
||||
- 重建失败时，上一版已就绪向量继续服务
|
||||
- 修复配置并重建后，降级状态消失
|
||||
- 故障信息经过脱敏
|
||||
|
||||
### US-C3 大知识库向量检索
|
||||
|
||||
作为知识库维护者，我希望超过 5,000 个分块后语义搜索仍然工作。
|
||||
|
||||
验收：
|
||||
|
||||
- 向量分批扫描没有固定 5,000 分块空结果
|
||||
- 只保留所需最佳候选，内存不会随全库候选等比例增长
|
||||
- 扫描支持取消和应用关闭
|
||||
- 10,000 个以上分块的测试返回正确 Top K
|
||||
- 诊断显示扫描数量与耗时
|
||||
|
||||
### US-C4 大目录完整同步
|
||||
|
||||
作为知识库维护者，我希望包含 2,000 个文件的目录也能完整增量同步，以免后半
|
||||
部分文档长期保留旧内容。
|
||||
|
||||
验收：
|
||||
|
||||
- 第 501 至 2,000 个文档参与校验和比较
|
||||
- 未变化文档不会重复解析和向量化
|
||||
- 已删除文件对应文档会被移除
|
||||
- 页面分页上限不影响后台同步完整性
|
||||
|
||||
### US-C5 调整召回参数
|
||||
|
||||
作为 RAG 调试者，我希望调整 Top K、最低相关度和通道权重，以便适配不同知识
|
||||
类型。
|
||||
|
||||
验收：
|
||||
|
||||
- Top K、阈值、候选倍数和权重具有明确范围和默认值
|
||||
- 至少一个召回通道权重大于 0
|
||||
- 图谱关闭时图谱权重不可生效并说明原因
|
||||
- 设置持久化到当前知识库，不影响其他知识库
|
||||
- 非法输入不能跨 IPC
|
||||
|
||||
## 5. Epic D：真实索引状态
|
||||
|
||||
### US-D1 查看分阶段状态
|
||||
|
||||
作为知识库维护者，我希望分别看到解析、全文、向量和图谱状态，以便准确判断
|
||||
文档能否使用。
|
||||
|
||||
验收：
|
||||
|
||||
- 文档不再用单个“ready”代表所有索引完成
|
||||
- 全文完成但向量失败时，明确显示“全文可用、向量失败”
|
||||
- 向量未启用与向量失败是不同状态
|
||||
- 图谱按需、未启用和失败是不同状态
|
||||
- 图谱模型按有界 Token 批次抽取；部分批次失败时保留成功结果并在任务中显示具体警告，全部批次失败时新文档仍保留可用全文索引
|
||||
- 汇总显示全文可用数、向量完成数和失败数
|
||||
|
||||
### US-D2 修复失败文档
|
||||
|
||||
作为知识库维护者，我希望单独重建失败文档，而不是重新同步整个目录。
|
||||
|
||||
验收：
|
||||
|
||||
- 文档行提供“重建文档”
|
||||
- 重建重新执行解析、分块、全文、向量和图谱
|
||||
- 失败时保留上一版可用索引
|
||||
- 完成后更新任务和状态
|
||||
- 原文件不存在时保留可重试错误
|
||||
|
||||
### US-D3 修改设置后重建
|
||||
|
||||
作为知识库维护者，我希望分块设置修改后明确提示需要重建，以免误以为旧文档
|
||||
已经使用新设置。
|
||||
|
||||
验收：
|
||||
|
||||
- 保存关键分块设置后显示“等待重建”
|
||||
- 设置保存本身不删除现有索引
|
||||
- 用户可选择全库重建
|
||||
- 全库重建可取消
|
||||
- 已成功替换的文档继续可用
|
||||
|
||||
## 6. Epic E：高级分块
|
||||
|
||||
### US-E1 固定分块
|
||||
|
||||
作为知识库维护者，我希望配置目标长度和重叠，以便处理日志、代码或简单文本。
|
||||
|
||||
验收：
|
||||
|
||||
- 目标长度为 400 至 8,000 字符
|
||||
- 重叠不超过目标长度的 40%
|
||||
- 优先在自然边界切分
|
||||
- 每个块保留来源 section、定位和 ordinal
|
||||
- 旧知识库迁移后不自动改变已有分块
|
||||
|
||||
### US-E2 结构分块
|
||||
|
||||
作为知识库维护者，我希望分块尽量保持标题和段落结构，以便命中片段保留语义。
|
||||
|
||||
验收：
|
||||
|
||||
- 优先保持解析 section
|
||||
- Markdown 标题能够成为分块 heading
|
||||
- 标题随子段落进入索引元数据
|
||||
- 超长 section 仍按有界规则继续切分
|
||||
- 空标题和空段落不创建分块
|
||||
|
||||
### US-E3 父子分块
|
||||
|
||||
作为 RAG 调试者，我希望小块负责准确召回、大块负责完整上下文，以便兼顾精度
|
||||
和完整性。
|
||||
|
||||
验收：
|
||||
|
||||
- 父块和子块具有稳定关系
|
||||
- 父块不直接进入 FTS/CJK/向量候选
|
||||
- 子块命中后可返回父块上下文
|
||||
- 引用突出实际命中的子块
|
||||
- 父块输出仍受上下文预算和截断限制
|
||||
|
||||
## 7. Epic F：重排与上下文
|
||||
|
||||
### US-F1 本地重排
|
||||
|
||||
作为本地与内网用户，我希望在不调用外部模型的情况下改善候选排序。
|
||||
|
||||
验收：
|
||||
|
||||
- 本地重排默认关闭并可按知识库开启
|
||||
- 使用 RRF、词覆盖、短语、标题、路径、向量和重复惩罚等确定性特征
|
||||
- 结果相关度归一化到 0 至 1
|
||||
- 检索测试显示重排前后排名
|
||||
- 关闭时保持原 RRF 行为
|
||||
- UI 不把本地算法描述为 AI Rerank 模型
|
||||
|
||||
### US-F1.1 学习型重排
|
||||
|
||||
作为需要更高排序质量的用户，我希望可选择兼容的学习型重排模型，并在服务
|
||||
不可用时继续获得本地结果。
|
||||
|
||||
验收：
|
||||
|
||||
- 模式明确区分关闭、本地规则和学习型重排
|
||||
- Main 最多发送 100 个候选，每个候选不超过 8,000 字符
|
||||
- API Key 仅通过环境变量或 Main 加密存储使用，不进入 Renderer
|
||||
- 超时、无效响应和服务错误回退本地重排，并显示脱敏诊断
|
||||
- 用户取消和应用关闭必须终止请求，不得按普通降级吞掉
|
||||
|
||||
### US-F2 相邻分块合并
|
||||
|
||||
作为普通知识使用者，我希望命中片段包含必要的上下文，而不是孤立半句话。
|
||||
|
||||
验收：
|
||||
|
||||
- 可配置向前、向后相邻 0 至 2 个块
|
||||
- 只合并同文档且 ordinal 连续的启用分块
|
||||
- 同一块不会重复输出
|
||||
- 每个原命中仍保留引用定位
|
||||
- 合并结果遵守上下文预算
|
||||
|
||||
### US-F3 上下文预算
|
||||
|
||||
作为普通知识使用者，我希望低质量内容不会挤占模型上下文。
|
||||
|
||||
验收：
|
||||
|
||||
- 按最终相关度从高到低选择上下文
|
||||
- 已选择的高排名证据不会被低排名证据替换
|
||||
- 超预算时明确标记截断
|
||||
- 预算范围为 2,000 至 48,000 字符
|
||||
- IPC 和 Runtime 输入继续受总大小限制
|
||||
|
||||
### US-F4 上下文索引
|
||||
|
||||
作为知识库维护者，我希望检索可以利用文档结构，而引用仍忠于原文。
|
||||
|
||||
验收：
|
||||
|
||||
- 可按知识库启用上下文索引，并在修改后提示显式重建
|
||||
- 标题、标题层级、页码和块类型使用有界确定性前缀进入 FTS、CJK 和向量文本
|
||||
- 原始分块、引用、模型上下文和图谱证据不显示生成前缀
|
||||
- FTS、CJK、向量和内容校验使用同一规范索引文本
|
||||
|
||||
## 7.1 Epic F+：受控本体与检索评估
|
||||
|
||||
### US-F5 每库受控本体
|
||||
|
||||
作为知识库维护者，我希望控制可用实体和关系类型，以便图谱保持一致。
|
||||
|
||||
验收：
|
||||
|
||||
- 每库保存实体类型、关系类型、双语名称、别名和可选端点约束
|
||||
- 手工编辑使用受控选择器并拒绝未知类型或不兼容端点
|
||||
- 图谱抽取按类型解析实体，保留人工锁定字段和跨类型边界
|
||||
- 证据保存原文偏移、置信度、抽取来源和有界 provenance
|
||||
- 本体或启用中的图谱策略变化标记需要重建
|
||||
|
||||
### US-F6 离线检索评估
|
||||
|
||||
作为 RAG 维护者，我希望用固定双语样本检测召回回归，而不读取用户数据或调用
|
||||
网络服务。
|
||||
|
||||
验收：
|
||||
|
||||
- `npm run eval:retrieval` 使用临时 SQLite 和确定性内存 Provider
|
||||
- 报告 Recall@5/10、MRR@10、nDCG@10、上下文精度/召回、无答案误报和延迟
|
||||
- 提供词法、确定性向量、混合及本地重排消融
|
||||
- 质量门槛按中英文分别检查，报告不包含原文、查询、端点、模型名或凭据
|
||||
- 可选报告路径仅允许工作区内非符号链接文件
|
||||
|
||||
## 8. Epic G：分块维护
|
||||
|
||||
### US-G1 查看分块
|
||||
|
||||
作为知识库维护者，我希望查看某篇文档实际生成的分块，以便确认解析和切分质量。
|
||||
|
||||
验收：
|
||||
|
||||
- 文档行提供“查看分块”
|
||||
- 列表显示序号、角色、标题、定位、字符数和启用状态
|
||||
- 支持有界分页和文档内搜索
|
||||
- 可查看完整单块内容
|
||||
- 父子块关系可辨认但不只靠颜色表达
|
||||
|
||||
### US-G2 编辑分块
|
||||
|
||||
作为知识库维护者，我希望修正错误文本，以便问答使用正确内容。
|
||||
|
||||
验收：
|
||||
|
||||
- 编辑限制单块最大字符数
|
||||
- 保存后同步更新全文和 CJK 索引
|
||||
- 旧向量立即失效并触发当前文档重建
|
||||
- 编辑块标记为人工修改
|
||||
- UI 说明来源再次同步可能覆盖修改
|
||||
- 保存失败保留用户草稿
|
||||
|
||||
### US-G3 启停分块
|
||||
|
||||
作为知识库维护者，我希望暂时停用有害或无关片段，而不永久删除它。
|
||||
|
||||
验收：
|
||||
|
||||
- 使用共享 Switch 和 `role="switch"`
|
||||
- 停用块不参与任何召回通道
|
||||
- 重新启用后恢复全文索引，并按需重建向量
|
||||
- 状态更新失败时保留最后确认状态
|
||||
- 引用已停用块时显示引用已失效
|
||||
|
||||
### US-G4 删除分块
|
||||
|
||||
作为知识库维护者，我希望删除确定无用的分块，以便避免错误召回。
|
||||
|
||||
验收：
|
||||
|
||||
- 删除前说明来源同步可能重新创建该块
|
||||
- 删除使用具体动作和对象文案
|
||||
- 删除联动清理全文、CJK、向量和图谱证据
|
||||
- 删除最后一个可检索块后文档显示“无可检索内容”
|
||||
- 不删除原始文件
|
||||
|
||||
## 9. Epic H：引用和来源
|
||||
|
||||
### US-H1 查看完整引用上下文
|
||||
|
||||
作为普通知识使用者，我希望从回答引用查看完整上下文，以便验证回答是否忠于
|
||||
资料。
|
||||
|
||||
验收：
|
||||
|
||||
- 引用携带稳定 `libraryId`、`documentId` 和 `chunkId`
|
||||
- 点击引用由 Main 重新校验对象归属
|
||||
- 展示命中分块、相邻块或父块
|
||||
- 展示知识库、文档、来源和定位
|
||||
- 对已删除对象显示明确失效状态
|
||||
|
||||
### US-H2 打开原始来源
|
||||
|
||||
作为普通知识使用者，我希望从引用打开原文件或网页，以便继续阅读。
|
||||
|
||||
验收：
|
||||
|
||||
- 本地来源只通过数据库保存的普通文件路径打开
|
||||
- 网页来源只允许数据库保存的 HTTP(S) URL
|
||||
- Renderer 不能传入任意待打开路径或 URL
|
||||
- 文件已移动时显示可恢复错误
|
||||
- 不能跨平台精确跳页时仍显示原定位信息
|
||||
|
||||
### US-H3 引用与回答一致
|
||||
|
||||
作为普通知识使用者，我希望引用列表只显示本次实际检索到的内容。
|
||||
|
||||
验收：
|
||||
|
||||
- Main 只收集本次 capability token 产生的引用
|
||||
- 预检索和模型后续检索引用去重
|
||||
- 引用顺序遵循最终相关度和首次使用顺序
|
||||
- 单消息引用数和序列化大小有明确上限
|
||||
- 不把未检索文档显示为来源
|
||||
|
||||
## 10. Epic I：迁移、安全和兼容
|
||||
|
||||
### US-I1 无损迁移
|
||||
|
||||
作为现有用户，我希望升级后保留知识库、来源、分块、图谱和向量。
|
||||
|
||||
验收：
|
||||
|
||||
- SQLite 迁移在事务中执行
|
||||
- 旧分块默认启用并视为 standalone
|
||||
- 旧知识库获得兼容检索和分块设置
|
||||
- CJK 索引回填失败时回滚迁移
|
||||
- 升级不自动删除或重建原有内容
|
||||
|
||||
### US-I2 安全边界
|
||||
|
||||
作为本地用户，我希望新增功能不扩大 Renderer 和子 Runtime 权限。
|
||||
|
||||
验收：
|
||||
|
||||
- 新增 IPC 全部校验可信 sender 和共享 Schema
|
||||
- Main 重新检查知识库、文档、分块和来源归属
|
||||
- Renderer 不访问 SQLite、文件系统、Electron shell 或凭据
|
||||
- 知识内容标记为不可信证据
|
||||
- Ask 不获得写工具
|
||||
- 错误和日志不包含密钥、授权头和未限制正文
|
||||
|
||||
### US-I3 取消和关闭
|
||||
|
||||
作为用户，我希望大库检索或重建可以停止，不留下损坏索引。
|
||||
|
||||
验收：
|
||||
|
||||
- 长向量扫描、单文档重建和全库重建响应 AbortSignal
|
||||
- 应用关闭停止新批次并等待有界清理
|
||||
- 文档级替换成功前继续使用上一版索引
|
||||
- 取消状态区别于失败
|
||||
- 取消不会删除原文件或用户维护的其他文档
|
||||
|
||||
## 11. 优先级映射
|
||||
|
||||
### 第一阶段
|
||||
|
||||
- US-A1、US-A2、US-A3
|
||||
- US-B1、US-B2、US-B3、US-B4
|
||||
- US-C1、US-C2、US-C3、US-C4、US-C5
|
||||
- US-D1
|
||||
- US-H1、US-H2、US-H3
|
||||
- US-I1、US-I2
|
||||
|
||||
### 第二阶段
|
||||
|
||||
- US-D2、US-D3
|
||||
- US-E1、US-E2、US-E3
|
||||
- US-F1、US-F2、US-F3
|
||||
- US-G1、US-G2、US-G3、US-G4
|
||||
- US-I3
|
||||
|
||||
## 12. Definition of Done
|
||||
|
||||
每个 User Story 只有在以下条件全部满足时才完成：
|
||||
|
||||
1. Main、Preload、Renderer 和共享契约保持明确边界。
|
||||
2. 行为有聚焦的单元、IPC 或组件回归测试。
|
||||
3. 中英文文案同时更新。
|
||||
4. 浅色、深色、键盘和窄窗口核心流程可用。
|
||||
5. 失败、取消、空结果和降级状态均有独立表现。
|
||||
6. 不覆盖用户现有未提交或未跟踪文件。
|
||||
7. `npm test`、`npm run typecheck`、`npm run lint` 和 `npm run build`
|
||||
全部通过。
|
||||
@@ -0,0 +1,39 @@
|
||||
# 本机工具环境
|
||||
|
||||
本目录是 GoodBuddy“本机工具环境”功能的唯一文档入口。该功能为本机 SKILL 和本机
|
||||
stdio MCP 提供明确、可诊断的 Node.js 与 Python 环境，同时允许专业用户选择自己维护的
|
||||
解释器。
|
||||
|
||||
本功能不作用于 SSH Host 上的 GoodBuddy Agent、固定 Node、签名 Runtime、SKILL 或 MCP。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [PRD](./prd.md) | 用户问题、产品目标、范围、需求和产品验收 |
|
||||
| [User Stories](./user-stories.md) | 用户角色、使用场景和逐故事验收 |
|
||||
| [功能逻辑](./logic-design.md) | 不变量、状态机、决策表、失败恢复和跨场景一致性 |
|
||||
| [UI 设计](./ui-design.md) | 页面结构、组件、状态、文案和无障碍一致性 |
|
||||
| [技术设计](./technical-design.md) | Main、Runtime、MCP、打包、生命周期和测试架构 |
|
||||
| [功能进度](./progress.md) | 已完成、进行中、待实施、阻塞项和验证证据 |
|
||||
|
||||
## 术语
|
||||
|
||||
| 术语 | 定义 |
|
||||
| --- | --- |
|
||||
| 本机工具环境 | GoodBuddy 在桌面所在设备上向本机 Runtime 和 stdio MCP 提供的工具命令环境 |
|
||||
| GoodBuddy 托管 | 由 GoodBuddy 提供、验证并解析的 Node.js 或 Python |
|
||||
| 自定义环境 | 用户从检测结果中选择或直接指定的外部解释器 |
|
||||
| 工具就绪 | 解释器及配套命令通过真实诊断 |
|
||||
| 能力依赖就绪 | 某个 SKILL 或 MCP 所需的第三方包和入口通过实际验证 |
|
||||
|
||||
## 文档维护规则
|
||||
|
||||
1. 产品范围只在 PRD 定义，其他文档链接引用。
|
||||
2. 界面视觉和交互只在 UI 设计定义，并服从仓库根目录的
|
||||
[统一界面设计系统](../../../UI-DESIGN.md)。
|
||||
3. 状态转换、优先级和冲突决策只在功能逻辑中定义。
|
||||
4. 进度文档只记录已验证事实，不复制未来设计。
|
||||
5. 技术实现变化先更新技术设计；用户行为变化同时更新 PRD、User Stories、功能逻辑和
|
||||
UI 设计。
|
||||
6. 每次完成功能阶段后立即更新进度、验证命令和剩余阻塞项。
|
||||
@@ -0,0 +1,374 @@
|
||||
# 本机工具环境功能逻辑设计
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 计划 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-09-01 |
|
||||
| 关联 PRD | [本机工具环境 PRD](./prd.md) |
|
||||
| 关联场景 | [本机工具环境 User Stories](./user-stories.md) |
|
||||
|
||||
本文是本功能业务规则、状态转换、决策表和跨场景一致性的权威来源。它不定义组件视觉，也
|
||||
不规定代码模块如何实现。
|
||||
|
||||
## 1. 逻辑目标
|
||||
|
||||
1. 同一用户操作在不同本机 Runtime 和 stdio MCP 中得到一致的解释器选择。
|
||||
2. 系统不通过隐式回退掩盖配置错误。
|
||||
3. 工具可执行、配套命令可执行和具体能力依赖可用是三个可区分事实。
|
||||
4. 已运行进程使用稳定环境，不被设置变化中途改写。
|
||||
5. 安装、更新、取消、失败和删除都有唯一、可恢复的结果。
|
||||
6. 本机环境和远程 Host 环境没有隐式传播。
|
||||
|
||||
## 2. 核心不变量
|
||||
|
||||
### INV-1 单一明确来源
|
||||
|
||||
Node.js 和 Python 各自恰好保存一个来源：`managed` 或 `custom`。不存在 `auto`、候选优先级
|
||||
列表或运行时动态选择。
|
||||
|
||||
### INV-2 禁止静默回退
|
||||
|
||||
当前来源不可用时，该工具明确不可用。即使发现另一套系统解释器，也不会自动切换。
|
||||
|
||||
### INV-3 配套命令同源
|
||||
|
||||
- `node`、`npm`、`npx` 必须属于同一 Node 来源。
|
||||
- `python`、`python3`、`pip` 必须属于同一 Python 来源。
|
||||
- `pip` 等价于当前 Python 的 `-m pip`，不能解析到其他解释器。
|
||||
|
||||
### INV-4 三层状态独立
|
||||
|
||||
1. **解释器状态**：Node 或 Python 本身能否执行。
|
||||
2. **工具组合状态**：npm/npx 或 pip/venv/SSL 是否完整。
|
||||
3. **能力依赖状态**：具体 SKILL/MCP 的入口和第三方依赖是否通过验证。
|
||||
|
||||
任一上层成功都不能推导下一层成功。
|
||||
|
||||
### INV-5 进程环境不可变
|
||||
|
||||
每个 Runtime/MCP 进程在启动时取得一份环境快照。设置变化只影响之后启动的进程，不改写
|
||||
已运行进程的 PATH 或解释器。
|
||||
|
||||
### INV-6 绝对命令优先
|
||||
|
||||
stdio MCP 配置的绝对 command 表达用户对该 MCP 的明确覆盖，原样执行，不经过全局工具
|
||||
命令替换。
|
||||
|
||||
### INV-7 本机与远程隔离
|
||||
|
||||
本机工具选择、shim、Python 包、SKILL 包和 stdio MCP 配置不上传到远程 Host。
|
||||
|
||||
### INV-8 不推断能力依赖已就绪
|
||||
|
||||
能力没有专属实际诊断时，状态只能是“未验证”，不能根据解释器版本或文件存在推断“已就绪”。
|
||||
|
||||
## 3. 状态维度
|
||||
|
||||
### 3.1 来源选择
|
||||
|
||||
```text
|
||||
managed
|
||||
custom(executablePath)
|
||||
```
|
||||
|
||||
这是唯一持久状态。
|
||||
|
||||
### 3.2 托管 Python 安装状态
|
||||
|
||||
```text
|
||||
not-installed
|
||||
downloading
|
||||
verifying
|
||||
installing
|
||||
testing
|
||||
ready
|
||||
update-available
|
||||
error
|
||||
```
|
||||
|
||||
`error` 同时携带“是否仍有旧版可用”。若旧版可用，实际工具状态仍基于旧版诊断。
|
||||
|
||||
托管 Node 随 GoodBuddy 存在，不使用下载安装状态，但仍可能因打包损坏进入诊断失败。
|
||||
|
||||
### 3.3 工具诊断状态
|
||||
|
||||
```text
|
||||
unknown
|
||||
testing
|
||||
ready
|
||||
partial
|
||||
unavailable
|
||||
```
|
||||
|
||||
- `ready`：解释器和本功能承诺的配套命令全部通过。
|
||||
- `partial`：解释器通过，至少一个配套命令失败。
|
||||
- `unavailable`：解释器本身不能使用。
|
||||
|
||||
### 3.4 能力依赖状态
|
||||
|
||||
```text
|
||||
unknown
|
||||
checking
|
||||
ready
|
||||
missing
|
||||
incompatible
|
||||
error
|
||||
```
|
||||
|
||||
- `unknown` 在 UI 中显示“依赖未验证”。
|
||||
- `missing` 表示明确缺少包或入口。
|
||||
- `incompatible` 表示解释器版本、架构或 ABI 不满足已声明要求。
|
||||
- `error` 表示诊断本身没有得出有效结论。
|
||||
|
||||
## 4. 来源解析决策表
|
||||
|
||||
| 保存来源 | 当前事实 | 解析结果 | 是否回退 |
|
||||
| --- | --- | --- | --- |
|
||||
| 托管 Node | 完整诊断通过 | 使用 Electron Node 与锁定 npm/npx | 否 |
|
||||
| 托管 Node | Node 通过，npm/npx 失败 | Node 部分可用，显示失败项 | 否 |
|
||||
| 托管 Node | Node 失败 | Node 不可用，提示修复/重装 GoodBuddy | 否 |
|
||||
| 托管 Python | 未安装 | Python 不可用，提供安装 | 否 |
|
||||
| 托管 Python | 已安装且诊断通过 | 使用托管 Python | 否 |
|
||||
| 托管 Python | 更新失败但旧版健康 | 继续使用旧版并显示更新失败 | 否 |
|
||||
| 托管 Python | 安装损坏 | Python 不可用，提供重新安装/删除 | 否 |
|
||||
| 自定义 | 路径及诊断通过 | 使用该绝对路径 | 否 |
|
||||
| 自定义 | 路径失效 | 保持选择并显示路径不可用 | 否 |
|
||||
| 自定义 | 解释器通过、配套命令失败 | 部分可用并显示失败项 | 否 |
|
||||
| 任意 | 发现其他有效解释器 | 只作为候选展示 | 不自动使用 |
|
||||
|
||||
## 5. 命令解析决策表
|
||||
|
||||
| 调用形式 | 结果 |
|
||||
| --- | --- |
|
||||
| `node ...` | 当前 Node |
|
||||
| `npm ...` | 当前 Node 配套 npm |
|
||||
| `npx ...` | 当前 Node 配套 npx |
|
||||
| `python ...` | 当前 Python |
|
||||
| `python3 ...` | 当前 Python |
|
||||
| `pip ...` | 当前 Python `-m pip` |
|
||||
| `#!/usr/bin/env node` | 从进程工具 PATH 解析当前 Node |
|
||||
| `#!/usr/bin/env python3` | 从进程工具 PATH 解析当前 Python |
|
||||
| stdio MCP 绝对 command | 原样执行 |
|
||||
| 未托管裸命令，例如 `uvx` | 按原筛选 PATH 处理；找不到则明确失败 |
|
||||
| HTTP/SSE MCP | 不参与本机命令解析 |
|
||||
|
||||
绝对 command 的子进程若自行调用裸 `node` 或 `python`，仍会看到该 MCP 进程启动时的工具
|
||||
PATH。这不改变绝对 command 本身。
|
||||
|
||||
## 6. 首次使用和迁移
|
||||
|
||||
### 6.1 全新安装
|
||||
|
||||
| 工具 | 默认选择 | 首次状态 |
|
||||
| --- | --- | --- |
|
||||
| Node.js | GoodBuddy 托管 | 立即真实诊断 |
|
||||
| Python | GoodBuddy 托管 | 未安装，展示安装入口 |
|
||||
|
||||
系统候选可以展示，但不会改变默认选择。
|
||||
|
||||
### 6.2 旧版本升级
|
||||
|
||||
1. 设置中没有工具环境字段时执行一次迁移。
|
||||
2. 分别按旧版本实际 PATH 解析 Node 和 Python 3。
|
||||
3. 有效解释器固化为 `custom + 绝对真实路径`。
|
||||
4. 无有效解释器时选择 `managed`。
|
||||
5. 持久化后不再因 PATH 变化迁移。
|
||||
|
||||
迁移中 Node 和 Python 独立决策，不要求二者使用同一种来源。
|
||||
|
||||
## 7. 托管 Python 生命周期
|
||||
|
||||
### 7.1 首次安装
|
||||
|
||||
```text
|
||||
not-installed
|
||||
→ downloading
|
||||
→ verifying
|
||||
→ installing
|
||||
→ testing
|
||||
→ ready
|
||||
```
|
||||
|
||||
任一步失败：
|
||||
|
||||
```text
|
||||
→ 删除本次暂存
|
||||
→ error（没有活动版本）
|
||||
→ 用户可重试
|
||||
```
|
||||
|
||||
### 7.2 取消
|
||||
|
||||
| 取消阶段 | 结果 |
|
||||
| --- | --- |
|
||||
| 下载 | 终止下载、删除暂存、回到安装前状态 |
|
||||
| 校验 | 终止校验、删除暂存、回到安装前状态 |
|
||||
| 解压/安装 | 完成本次有界清理、回到安装前状态 |
|
||||
| 测试 | 停止诊断、删除未发布候选、回到安装前状态 |
|
||||
|
||||
取消不发布候选版本，不把取消显示为安装失败。
|
||||
|
||||
### 7.3 更新
|
||||
|
||||
1. 下载和验证候选时，旧版继续服务现有进程。
|
||||
2. 应用候选前，页面说明需要停止依赖托管 Python 的本机 Runtime/MCP。
|
||||
3. 用户确认后通过现有生命周期取消/停止相关进程。
|
||||
4. 无法确认停止时不替换当前版本。
|
||||
5. 候选完整诊断通过后才发布。
|
||||
6. 失败继续使用旧版，并显示更新失败。
|
||||
|
||||
首期不让两个托管 Python 版本长期并存。候选暂存只服务本次更新。
|
||||
|
||||
### 7.4 删除
|
||||
|
||||
| 条件 | 行为 |
|
||||
| --- | --- |
|
||||
| 没有使用中进程 | 确认后删除托管目录 |
|
||||
| 有使用中进程 | 说明影响，用户确认后停止相关进程再删除 |
|
||||
| 进程停止失败 | 不删除，保留当前环境 |
|
||||
| 当前选择为自定义 | 删除托管包不改变自定义来源 |
|
||||
| 当前选择为托管 | 删除后保持托管选择，状态变为未安装 |
|
||||
|
||||
## 8. 设置保存与进程生效
|
||||
|
||||
### 8.1 保存时
|
||||
|
||||
- 验证待保存来源。
|
||||
- 自定义路径必须在保存前通过解释器诊断；配套命令可以形成 `partial`。
|
||||
- 保存成功后标记本机 Runtime 环境配置已变化。
|
||||
- 不直接修改任何运行中进程。
|
||||
|
||||
### 8.2 后续进程
|
||||
|
||||
- 没有活动请求的缓存 Runtime 在下次使用前按现有重建入口重建。
|
||||
- 有活动请求的 Runtime 完成或被用户停止前保持原环境。
|
||||
- 已启动 stdio MCP 保持原环境，正常关闭、重连或显式测试后使用新环境。
|
||||
- 新启动的 Runtime/MCP 立即使用新环境。
|
||||
|
||||
每个工具调用的活动记录应归属于实际承载它的进程，不根据最新设置追改历史来源。
|
||||
|
||||
## 9. 能力依赖逻辑
|
||||
|
||||
### 9.1 诊断输入
|
||||
|
||||
能力可以声明：
|
||||
|
||||
- 需要 Node 或 Python。
|
||||
- 最低/最高解释器版本。
|
||||
- 可选依赖文件位置。
|
||||
- 可选的无副作用诊断入口。
|
||||
|
||||
首期声明只用于显示、版本比较和显式诊断，不触发自动安装。
|
||||
|
||||
### 9.2 状态推导
|
||||
|
||||
| 工具状态 | 能力诊断 | 能力状态 |
|
||||
| --- | --- | --- |
|
||||
| unavailable | 不执行 | missing 或 incompatible，附工具原因 |
|
||||
| partial | 能力不依赖失败配套项且实际诊断成功 | ready |
|
||||
| partial | 能力依赖失败配套项 | missing |
|
||||
| ready | 没有能力诊断 | unknown |
|
||||
| ready | 实际诊断成功 | ready |
|
||||
| ready | 明确缺包 | missing |
|
||||
| ready | 版本/ABI 不满足 | incompatible |
|
||||
| 任意 | 诊断自身异常 | error |
|
||||
|
||||
“依赖未验证”不是错误，也不能显示为“已就绪”。
|
||||
|
||||
## 10. Ask、Execute 与 MCP
|
||||
|
||||
| 场景 | 解释器是否可见 | 是否允许执行 |
|
||||
| --- | --- | --- |
|
||||
| 本机 Execute Runtime | 是 | 按现有 Execute 权限 |
|
||||
| 本机 Ask Runtime | 可以存在于进程环境 | 仍由 Runtime Ask 边界决定，不能因此获得命令权限 |
|
||||
| Main 启动的已启用 stdio MCP | 是 | 按当前 MCP 分配和模式规则 |
|
||||
| HTTP/SSE MCP | 不适用 | 按当前网络 MCP 规则 |
|
||||
| 远程 Runtime | 否 | 使用远程 Host 自身环境 |
|
||||
|
||||
工具环境不创建新的工具，不扩大 Runtime 当前允许的工具集合。
|
||||
|
||||
## 11. 网络受限与离线
|
||||
|
||||
### 11.1 托管 Node
|
||||
|
||||
随 GoodBuddy 提供，安装后可离线使用。
|
||||
|
||||
### 11.2 托管 Python
|
||||
|
||||
- 首期支持当前官方 GitHub/镜像来源。
|
||||
- 下载源不可达时保持未安装或旧版可用状态，并显示准确原因。
|
||||
- 首期不提供 Python 离线包导入，避免引入未经选型的包格式和导入流程。
|
||||
- 完全离线用户可以选择已经离线安装的自定义 Python。
|
||||
|
||||
未来若加入离线导入，必须在 PRD、User Stories、逻辑状态和技术包校验中同时定义，不能只
|
||||
增加一个文件按钮。
|
||||
|
||||
## 12. 冲突与一致性检查
|
||||
|
||||
| 可能冲突 | 唯一规则 |
|
||||
| --- | --- |
|
||||
| 全局工具选择 vs MCP 绝对 command | 绝对 command 优先 |
|
||||
| 新设置 vs 运行中进程 | 运行中进程保留启动快照 |
|
||||
| 新托管版本 vs 健康旧版本 | 候选完整通过后才发布 |
|
||||
| 系统发现新版本 vs 已保存自定义路径 | 不自动切换 |
|
||||
| 解释器成功 vs 缺少第三方包 | 工具 ready，能力 missing/unknown |
|
||||
| Ask 环境包含解释器 vs Ask 只读 | Ask 权限边界优先 |
|
||||
| 本机设置 vs 远程项目 | 远程隔离优先 |
|
||||
| 镜像不可达 vs 其他来源可用 | 不在同一次操作中静默切换来源 |
|
||||
|
||||
## 13. 逻辑评估结论
|
||||
|
||||
### 13.1 完整性评估
|
||||
|
||||
| 评估维度 | 结论 | 依据 |
|
||||
| --- | --- | --- |
|
||||
| 首次使用 | 通过 | 托管 Node 立即诊断，托管 Python 明确未安装 |
|
||||
| 正常执行 | 通过 | SKILL 与 stdio MCP 共用同一命令解析 |
|
||||
| 自定义环境 | 通过 | 明确路径、真实诊断、禁止静默回退 |
|
||||
| 部分失败 | 通过 | 解释器、工具组合、能力依赖三层状态独立 |
|
||||
| 安装生命周期 | 通过 | 安装、取消、失败、重试有唯一结果 |
|
||||
| 更新生命周期 | 通过 | 候选通过后发布，失败保留健康旧版 |
|
||||
| 删除生命周期 | 通过 | 使用中进程先停止，失败不删除 |
|
||||
| 设置生效 | 通过 | 进程启动快照不可变，新进程使用新设置 |
|
||||
| 升级兼容 | 通过 | 旧系统解释器一次性固化为自定义路径 |
|
||||
| Ask/Execute | 通过 | 工具环境不扩大工具集合或权限 |
|
||||
| 远程边界 | 通过 | 本机配置不进入 Host |
|
||||
| 受限网络 | 通过 | 来源失败可见，不在同次操作静默切换 |
|
||||
| 完全离线 | 有明确限制 | Node 可用；Python 首期要求已有自定义环境 |
|
||||
|
||||
### 13.2 一致性评估
|
||||
|
||||
- “两种来源”与自定义候选探测不冲突：候选只是自定义来源的选值，不是第三种来源。
|
||||
- “禁止回退”与升级迁移不冲突：迁移只发生一次，完成后按普通保存选择处理。
|
||||
- “进程环境不可变”与 Runtime 重建不冲突：只有空闲或后续启动的进程使用新环境。
|
||||
- “工具环境就绪”与“能力依赖就绪”不冲突：两者属于独立状态维度。
|
||||
- “绝对 MCP command 优先”与 PATH 注入不冲突：command 不替换，但其子进程继承启动快照。
|
||||
- “更新保留旧版”不要求长期多版本管理：旧版只在候选发布前保持当前，候选失败即删除。
|
||||
|
||||
### 13.3 当前未决项
|
||||
|
||||
没有未决的产品逻辑分支。以下属于实施前必须解决的技术选型，不改变业务规则：
|
||||
|
||||
1. 六平台 CPython 独立发行包、固定版本、许可证和摘要。
|
||||
2. SKILL/MCP 运行要求声明的最小 schema 和无副作用诊断入口。
|
||||
3. 各 Runtime 当前缓存进程的精确空闲判定与既有重建入口接线。
|
||||
|
||||
若技术选型无法满足当前逻辑，例如目标 Python 工件不包含可用 pip/venv，必须回到 PRD 和
|
||||
逻辑设计调整承诺，不能在实现中静默降级。
|
||||
|
||||
## 14. 需求追踪
|
||||
|
||||
| 逻辑范围 | PRD | User Stories |
|
||||
| --- | --- | --- |
|
||||
| 明确来源与禁止回退 | FR-3、FR-8 | US-C1、US-C2、US-D3 |
|
||||
| 托管 Node | FR-1 | US-A1、US-B2 |
|
||||
| 托管 Python 生命周期 | FR-2、FR-9 | US-A2、US-D2、US-D4、US-D5 |
|
||||
| 三层状态 | FR-6 | US-A3、US-A4 |
|
||||
| MCP 命令解析 | FR-5 | US-B1、US-B2、US-B3 |
|
||||
| 生效时机 | FR-7 | US-C3、US-C4 |
|
||||
| Ask/Execute | FR-10 | US-D6 |
|
||||
| 远程隔离 | FR-7、FR-9 | US-D1 |
|
||||
| 受限网络与离线 | FR-2 | US-E1、US-E2 |
|
||||
@@ -0,0 +1,158 @@
|
||||
# 本机工具环境 PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 计划 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-09-01 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
|
||||
| 关联文档 | [功能入口](./README.md)、[User Stories](./user-stories.md)、[功能逻辑](./logic-design.md)、[UI 设计](./ui-design.md)、[技术设计](./technical-design.md)、[功能进度](./progress.md) |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
GoodBuddy 的部分 SKILL 通过 Node.js 或 Python 脚本生成成果，部分本机 stdio MCP 也以
|
||||
`node`、`npm`、`npx`、`python` 或 `python -m` 启动。当前安装包没有向这些能力提供统一
|
||||
解释器，用户是否成功取决于系统 PATH 和预装软件。
|
||||
|
||||
普通用户不应为了使用一个 SKILL 或 MCP 手工安装开发环境。专业用户已有项目 Node、
|
||||
Python、虚拟环境或 Conda 环境时，也不能被 GoodBuddy 静默替换。
|
||||
|
||||
## 2. 产品目标
|
||||
|
||||
1. 全新设备无需预装 Node.js 即可运行普通 JavaScript SKILL 和 Node.js stdio MCP。
|
||||
2. 用户可在 GoodBuddy 内按需安装 Python，并运行 Python SKILL 和 stdio MCP。
|
||||
3. 专业用户可以选择检测到的解释器或指定其他可执行文件。
|
||||
4. 设置始终展示实际来源、版本、路径、工具状态和能力依赖状态。
|
||||
5. 本机工具环境不修改系统环境，也不传播到远程主机。
|
||||
6. 保持 Ask/Execute、Runtime、MCP、取消和进程清理的现有边界。
|
||||
|
||||
## 3. 核心决策
|
||||
|
||||
### 3.1 每种工具只有两个来源
|
||||
|
||||
- **GoodBuddy 托管（推荐）**
|
||||
- **自定义环境**
|
||||
|
||||
不提供“自动选择”。“系统安装”和“指定路径”合并为“自定义环境”，因为两者最终都是
|
||||
用户明确选择的外部可执行文件，区别只在发现方式。
|
||||
|
||||
### 3.2 配套命令跟随解释器
|
||||
|
||||
- Node.js 保证 `node`、`npm`、`npx` 来自同一来源。
|
||||
- Python 保证 `python`、`python3`、`pip` 来自同一来源；`pip` 实际绑定当前 Python。
|
||||
- 首期不托管 `uv`、`uvx`、Conda、Poetry、pyenv 或 nvm。
|
||||
|
||||
### 3.3 工具就绪不等于能力依赖就绪
|
||||
|
||||
解释器通过诊断后标记“工具环境已就绪”。只有 SKILL 或 MCP 的实际入口及所需第三方包
|
||||
通过验证后，才能标记“能力依赖已就绪”。GoodBuddy 首期不自动扫描和安装任意能力依赖。
|
||||
|
||||
## 4. 功能范围
|
||||
|
||||
### 4.1 包含
|
||||
|
||||
- 本机 OpenCode、Continue、DeepSeek Harness 加载的 SKILL。
|
||||
- Main 或本机 Runtime 启动的 stdio MCP。
|
||||
- 托管 Node.js、npm、npx。
|
||||
- 按需下载安装的托管 Python 3、pip、venv。
|
||||
- 系统解释器探测、自定义文件选择和真实诊断。
|
||||
- 工具来源、版本、路径、安装、删除、更新和错误状态。
|
||||
- 新启动本机 Runtime 和 MCP 的 PATH 注入。
|
||||
|
||||
### 4.2 不包含
|
||||
|
||||
- SSH Host 的 PATH、Agent、固定 Node、Runtime、SKILL 或 MCP。
|
||||
- HTTP/SSE MCP 服务端环境。
|
||||
- 普通助手工作栏终端的 Shell 环境。
|
||||
- 通用语言版本管理器。
|
||||
- 每项目或每 SKILL 的解释器覆盖。
|
||||
- 自动合并或求解多个 `requirements.txt`、`package.json`。
|
||||
- 自动执行任意第三方安装脚本。
|
||||
- 修改系统 PATH、注册表或 Shell Profile。
|
||||
- 无条件把完整 Python 打入桌面安装包。
|
||||
- 首期导入托管 Python 离线包；完全离线用户可选择已有的自定义 Python。
|
||||
|
||||
## 5. 功能需求
|
||||
|
||||
### FR-1 Node.js 托管环境
|
||||
|
||||
- 安装 GoodBuddy 后托管 Node.js 即可用，不需要额外下载。
|
||||
- 实际版本通过运行命令诊断，不仅根据 Electron 版本推断。
|
||||
- `node`、`npm`、`npx` 必须来自同一托管组合。
|
||||
- Electron Node 原生扩展兼容限制必须可见。
|
||||
|
||||
### FR-2 Python 托管环境
|
||||
|
||||
- Python 未安装时展示安装入口，不把完整 Python 放入所有桌面安装包。
|
||||
- 下载复用“关于与更新”的官方 GitHub/镜像来源。
|
||||
- 展示下载、校验、安装、取消、可更新、删除和失败状态。
|
||||
- 下载失败保留已验证旧安装。
|
||||
|
||||
### FR-3 自定义环境
|
||||
|
||||
- 探测 PATH 和常见安装位置中的有效候选。
|
||||
- 候选同时展示版本和规范化绝对路径。
|
||||
- 用户可以选择未被探测到的可执行文件。
|
||||
- 保存前执行真实诊断。
|
||||
- 已保存路径失效时保持用户选择并报错，不静默回退。
|
||||
|
||||
### FR-4 SKILL 接入
|
||||
|
||||
- SKILL 可以稳定调用 `node`、`npm`、`npx`、`python`、`python3` 和 `pip`。
|
||||
- SKILL 不需要知道解释器真实安装目录。
|
||||
- 缺失解释器或第三方依赖时返回准确错误。
|
||||
- 工具环境不自动安装 SKILL 声明的依赖。
|
||||
|
||||
### FR-5 stdio MCP 接入
|
||||
|
||||
- 裸命令通过当前工具环境解析。
|
||||
- `env node`、`env python3` 形式的脚本使用当前工具环境。
|
||||
- MCP 中配置的绝对命令路径保持原样，不被替换。
|
||||
- Python 和 Node.js MCP 均使用与 SKILL 相同的来源。
|
||||
|
||||
### FR-6 状态与诊断
|
||||
|
||||
- 分别显示“工具环境状态”和“能力依赖状态”。
|
||||
- Node 诊断覆盖 Node、npm、npx、标准库和子进程。
|
||||
- Python 诊断覆盖 Python 3、架构、标准库、SSL、pip 和 venv。
|
||||
- 诊断使用临时目录并在结束后清理。
|
||||
|
||||
### FR-7 生效范围
|
||||
|
||||
- 设置只对新启动的本机 Runtime 和 stdio MCP 生效。
|
||||
- 已运行进程不被中途替换环境。
|
||||
- 不影响普通终端、系统环境和远程主机。
|
||||
|
||||
### FR-8 升级兼容
|
||||
|
||||
- 全新用户默认选择 GoodBuddy 托管。
|
||||
- 已发布版本升级时，将当前有效系统解释器一次性固化为自定义绝对路径。
|
||||
- 没有有效系统解释器时迁移到托管来源。
|
||||
- 后续系统 PATH 变化不自动改变选择。
|
||||
|
||||
### FR-9 生命周期
|
||||
|
||||
- 安装、诊断、Runtime 和 MCP 子进程支持取消和应用退出清理。
|
||||
- 删除只作用于 GoodBuddy-owned 目录。
|
||||
- 不删除系统解释器、自定义环境、用户工作区或远程文件。
|
||||
|
||||
### FR-10 权限模式
|
||||
|
||||
- Ask 不因解释器可用而获得额外命令或写入权限。
|
||||
- Execute 继续使用当前本机账号的完整授权。
|
||||
- 不为工具环境增加第二套批准流程。
|
||||
|
||||
## 6. 产品验收
|
||||
|
||||
- 无系统 Node.js 时，托管 Node 可以真实执行 JavaScript SKILL 和 stdio MCP。
|
||||
- 无系统 Python 时，用户可安装托管 Python 并真实执行现有 Python SKILL 和 MCP。
|
||||
- Node、npm、npx 来源一致；Python、python3、pip 来源一致。
|
||||
- 用户可明确选择并锁定自定义解释器。
|
||||
- 自定义路径失效不触发静默切换。
|
||||
- 工具就绪与能力依赖就绪不会混为同一状态。
|
||||
- 本机 Skills、MCP 和工具环境不会应用于远程主机。
|
||||
- 中英文界面、键盘操作、焦点和状态反馈符合统一设计系统。
|
||||
- 全量测试、类型检查、Lint 和生产构建通过。
|
||||
@@ -0,0 +1,89 @@
|
||||
# 本机工具环境功能进度
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 文档类型 | 功能进度 |
|
||||
| 状态 | 计划中 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-09-01 |
|
||||
| 关联入口 | [本机工具环境](./README.md) |
|
||||
|
||||
## 当前结论
|
||||
|
||||
功能尚未进入源码实施。产品范围、User Stories、功能逻辑评估、UI 一致性和技术方案已经
|
||||
形成首版文档。
|
||||
|
||||
## 已完成
|
||||
|
||||
- [x] 明确功能只服务本机 SKILL 和本机 stdio MCP。
|
||||
- [x] 明确远程 Host 不接收本机工具环境、SKILL 或 MCP。
|
||||
- [x] 将来源收敛为“GoodBuddy 托管”和“自定义环境”。
|
||||
- [x] 明确 Node、npm、npx 同源，Python、python3、pip 同源。
|
||||
- [x] 区分工具环境就绪与能力依赖就绪。
|
||||
- [x] 定义现有用户解释器的一次性兼容迁移。
|
||||
- [x] 定义状态机、来源和命令决策表、失败恢复与生效时机。
|
||||
- [x] 定义设置页结构、状态、文案和无障碍要求。
|
||||
- [x] 定义 Main 服务、shim、探测、诊断、PATH 注入和 Python 生命周期。
|
||||
- [x] 远程主机设置副标题已说明本机 Skills 和 MCP 不作用于远程主机。
|
||||
|
||||
## 待实施
|
||||
|
||||
### 阶段 1：设置、探测和界面
|
||||
|
||||
- [ ] Shared 设置、状态、操作和 IPC schema。
|
||||
- [ ] 旧用户迁移。
|
||||
- [ ] Node/Python 候选探测。
|
||||
- [ ] 完整环境诊断。
|
||||
- [ ] Agent Runtime 设置中的本机工具环境卡片。
|
||||
|
||||
### 阶段 2：托管 Node
|
||||
|
||||
- [ ] 提取并复用 DSH Node shim。
|
||||
- [ ] 提供 node/npm/npx。
|
||||
- [ ] 注入 OpenCode、Continue、DeepSeek Harness。
|
||||
- [ ] 注入 Main 和 Runtime 的 stdio MCP。
|
||||
- [ ] 安装包真实 Node、npm、npx smoke。
|
||||
|
||||
### 阶段 3：托管 Python
|
||||
|
||||
- [ ] 选型并锁定六平台 CPython 工件。
|
||||
- [ ] 完成许可证和下载目录。
|
||||
- [ ] 下载、校验、安装、更新、取消和删除。
|
||||
- [ ] 提供 python/python3/pip。
|
||||
- [ ] Python 标准库、SSL、pip、venv 真实诊断。
|
||||
|
||||
### 阶段 4：端到端验收
|
||||
|
||||
- [ ] Node SKILL 实际成果。
|
||||
- [ ] Python SKILL 实际成果。
|
||||
- [ ] Node stdio MCP 实际调用。
|
||||
- [ ] Python stdio MCP 实际调用。
|
||||
- [ ] 自定义 Node/Python 路径。
|
||||
- [ ] Ask/Execute、Runtime 重建、取消、退出。
|
||||
- [ ] 六平台 CI、许可证和生产构建。
|
||||
|
||||
## 当前阻塞项
|
||||
|
||||
- 尚未完成六平台可再分发 CPython 工件选型，因此托管 Python 版本、体积和下载摘要未锁定。
|
||||
- 尚未开始源码接入。
|
||||
|
||||
## 已验证证据
|
||||
|
||||
### 2026-08-31
|
||||
|
||||
- 确认安装包携带 Electron Node 能力和锁定 npm CLI，但未向通用 SKILL/MCP 提供 `node`
|
||||
命令。
|
||||
- 确认 DSH 插件安装器已有 `ELECTRON_RUN_AS_NODE=1` shim，可作为复用基线。
|
||||
- 确认远程 Agent ACP Session 使用空 MCP Server 列表，本机 SKILL/MCP 不进入远程路径。
|
||||
- 远程主机设置文案聚焦测试通过：`80/80`。
|
||||
- 当时完整类型检查通过；完整测试和 Lint 被并行开发中的 `RightAssistantSidebar` 变更
|
||||
阻塞，不作为本功能实现验证。
|
||||
|
||||
## 进度维护要求
|
||||
|
||||
- 只有真实源码和生产路径完成后才能勾选对应实施项。
|
||||
- 测试失败时保留未完成状态并记录失败原因。
|
||||
- 每次更新记录日期、实际命令、结果和外部阻塞。
|
||||
- 不在本文件复制未来设计，需求变化回写 PRD/UI/技术设计。
|
||||
@@ -0,0 +1,284 @@
|
||||
# 本机工具环境技术设计
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 计划 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-09-01 |
|
||||
| 关联 PRD | [本机工具环境 PRD](./prd.md) |
|
||||
| 功能逻辑 | [本机工具环境功能逻辑设计](./logic-design.md) |
|
||||
| 相关架构 | [DeepSeek Harness Runtime 设计](../deepseek-harness/technical-design.md)、[SSH 远程主机与 GoodBuddy Agent 实现说明](../remote-host/technical-design.md) |
|
||||
|
||||
## 1. 当前基线
|
||||
|
||||
GoodBuddy 已具备：
|
||||
|
||||
- Electron 内置 Node Runtime。
|
||||
- 安装包中的锁定 npm CLI。
|
||||
- DSH 插件安装器使用的 `process.execPath + ELECTRON_RUN_AS_NODE=1` shim。
|
||||
- OpenCode、Continue、DeepSeek Harness 的独立本机进程环境入口。
|
||||
- SKILL 按 Runtime 目标分配和暂存。
|
||||
- Main 和 Runtime 的 stdio MCP 启动链路。
|
||||
- Runtime 可执行文件探测、版本读取和自定义路径模式。
|
||||
- 下载、摘要校验、进度、取消和暂存清理模式。
|
||||
|
||||
当前缺少统一工具来源设置、通用 PATH 注入和托管 Python。
|
||||
|
||||
## 2. 设置契约
|
||||
|
||||
```ts
|
||||
type LocalToolEnvironmentSelection =
|
||||
| { source: 'managed' }
|
||||
| { source: 'custom'; executablePath: string }
|
||||
|
||||
type LocalToolEnvironmentSettings = {
|
||||
node: LocalToolEnvironmentSelection
|
||||
python: LocalToolEnvironmentSelection
|
||||
}
|
||||
```
|
||||
|
||||
只持久化用户意图。不持久化候选列表、版本、PATH、shim 路径、诊断结果或可重新读取的托管
|
||||
包元数据。
|
||||
|
||||
### 2.1 兼容迁移
|
||||
|
||||
- 全新用户默认 `managed`。
|
||||
- 旧设置没有该字段时，Main 按升级前 PATH 分别解析有效 Node 和 Python 3。
|
||||
- 有效候选写成 `custom + 规范化绝对路径`。
|
||||
- 没有有效候选时写成 `managed`。
|
||||
- 迁移只执行一次，后续 PATH 变化不改变选择。
|
||||
|
||||
## 3. Main 服务
|
||||
|
||||
新增一个 `LocalToolEnvironmentService`，负责：
|
||||
|
||||
- 设置读取和保存。
|
||||
- Node/Python 候选探测。
|
||||
- 自定义解释器诊断。
|
||||
- 当前工具组合解析。
|
||||
- 受管工具 bin 创建。
|
||||
- 托管 Python 安装、更新、删除。
|
||||
- 有界状态和进度发布。
|
||||
- 应用退出时取消安装并清理本次暂存。
|
||||
|
||||
不为每项职责增加持久 Manager、注册表或恢复状态机。失败安装删除暂存，下次重新执行。
|
||||
|
||||
## 4. 解析结果
|
||||
|
||||
```ts
|
||||
type ResolvedLocalToolEnvironment = {
|
||||
binDirectory: string
|
||||
node?: {
|
||||
executablePath: string
|
||||
npmCliPath?: string
|
||||
npxCliPath?: string
|
||||
}
|
||||
python?: {
|
||||
executablePath: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
工具 bin：
|
||||
|
||||
| 平台 | 命令 |
|
||||
| --- | --- |
|
||||
| Windows | `node.cmd`、`npm.cmd`、`npx.cmd`、`python.cmd`、`python3.cmd`、`pip.cmd` |
|
||||
| macOS/Linux | `node`、`npm`、`npx`、`python`、`python3`、`pip` |
|
||||
|
||||
shim 使用绝对路径。`pip` 固定调用 `<python> -m pip`，避免解释器错配。
|
||||
|
||||
## 5. Node.js 托管环境
|
||||
|
||||
托管 Node shim：
|
||||
|
||||
```text
|
||||
ELECTRON_RUN_AS_NODE=1 <process.execPath> <arguments...>
|
||||
```
|
||||
|
||||
约束：
|
||||
|
||||
- 复用 DSH 已有的平台转义实现。
|
||||
- `ELECTRON_RUN_AS_NODE` 不写入 Main 全局环境。
|
||||
- npm/npx 使用安装包中同一锁定 npm 发行版的 CLI。
|
||||
- npm 子进程范围设置 `npm_execpath` 和 `npm_node_execpath`。
|
||||
- 自定义 Node 只使用与其配套且验证成功的 npm/npx，不混入 GoodBuddy npm。
|
||||
- 普通 JavaScript 和 Node 内置模块属于支持路径。
|
||||
- 普通 Node 原生扩展可能受 Electron ABI 影响，不承诺兼容。
|
||||
|
||||
## 6. Python 托管环境
|
||||
|
||||
### 6.1 包
|
||||
|
||||
- 使用包含 pip、venv、SSL 和标准库的固定 CPython 独立发行包。
|
||||
- 每个平台/架构锁定一个版本。
|
||||
- 目录包含版本、平台、架构、来源、字节数、SHA-256 和许可证。
|
||||
- 下载复用当前官方 GitHub/镜像来源，不增加来源设置。
|
||||
- 安装包不无条件携带完整 Python。
|
||||
|
||||
具体发行包和版本必须在实现前完成六平台工件、许可证、维护状态和 pip/venv 可用性核验。
|
||||
|
||||
### 6.2 安装
|
||||
|
||||
```text
|
||||
读取固定目录
|
||||
→ 下载到 GoodBuddy-owned 暂存
|
||||
→ 校验大小和 SHA-256
|
||||
→ 解压到新版本目录
|
||||
→ 运行完整环境诊断
|
||||
→ 发布为当前托管 Python
|
||||
→ 删除暂存
|
||||
```
|
||||
|
||||
失败保留已验证旧安装。删除只作用于 GoodBuddy-owned Python 目录。
|
||||
|
||||
### 6.3 包依赖
|
||||
|
||||
首期提供解释器和 pip，不自动扫描或安装任意 `requirements.txt`。第三方包由 SKILL/MCP
|
||||
安装流程或用户明确命令准备。出现可复现的包冲突后，再评估能力级虚拟环境。
|
||||
|
||||
## 7. 自定义环境探测
|
||||
|
||||
### 7.1 Node
|
||||
|
||||
候选来源：
|
||||
|
||||
- 筛选后的 PATH。
|
||||
- Windows/macOS/Linux 常见安装目录。
|
||||
- 已保存路径。
|
||||
|
||||
每个候选运行分离参数的 `--version`，确认普通文件、可执行、成功退出和可解析版本，并按
|
||||
真实路径去重。
|
||||
|
||||
### 7.2 Python
|
||||
|
||||
- Windows 探测 `python.exe`。
|
||||
- macOS/Linux 优先 `python3`，其次为明确的 Python 3 `python`。
|
||||
- 拒绝未安装的 Windows Store App Execution Alias。
|
||||
- 诊断 Python 3、版本、架构和解释器绝对路径。
|
||||
|
||||
单候选和总探测具有超时、输出上限、取消和进程树清理。
|
||||
|
||||
## 8. 完整诊断
|
||||
|
||||
### 8.1 Node
|
||||
|
||||
- `node --version`
|
||||
- 加载标准库
|
||||
- 启动最小子进程
|
||||
- `npm --version`
|
||||
- `npx --version`
|
||||
- npm/npx 实际 Node 来源一致
|
||||
|
||||
### 8.2 Python
|
||||
|
||||
- Python 3、版本和架构
|
||||
- 标准库导入
|
||||
- SSL/证书模块
|
||||
- `python -m pip --version`
|
||||
- 在临时目录创建最小 venv
|
||||
|
||||
诊断不联网，使用 GoodBuddy-owned 临时目录并清理。
|
||||
|
||||
## 9. 环境注入
|
||||
|
||||
新启动的以下本机进程将工具 bin 放到现有筛选 PATH 前面：
|
||||
|
||||
- OpenCode Server。
|
||||
- Continue Utility Process。
|
||||
- DeepSeek Harness Utility Process。
|
||||
- Main 启动的 stdio MCP。
|
||||
- Runtime 启动的 stdio MCP。
|
||||
|
||||
不注入 Main 全局环境、Renderer、普通终端、SSH 请求、Agent 或远程 Runtime。
|
||||
|
||||
设置变化后，有活动请求的 Runtime 保持启动时快照；空闲 Runtime 在下次使用前使用既有
|
||||
重建入口。已运行 MCP 在正常关闭、重连或显式测试后使用新环境，不增加热切换协议。
|
||||
|
||||
## 10. SKILL 与 MCP
|
||||
|
||||
SKILL 稳定调用命令名，不接收真实安装路径。
|
||||
|
||||
stdio MCP：
|
||||
|
||||
- 裸 `node`、`npm`、`npx`、`python`、`python3`、`pip` 使用工具 bin。
|
||||
- `env node`/`env python3` 脚本通过 PATH 使用同一来源。
|
||||
- 绝对 command 保持原样。
|
||||
- HTTP/SSE 不受影响。
|
||||
- 工具环境不自动安装 MCP 第三方依赖。
|
||||
|
||||
## 11. Renderer 状态与 IPC
|
||||
|
||||
Renderer 接收：
|
||||
|
||||
- 当前选择。
|
||||
- 当前实际来源、版本、路径。
|
||||
- 有界候选列表。
|
||||
- 托管安装状态、版本、占用空间。
|
||||
- 工具诊断分项结果。
|
||||
- 安装进度和脱敏错误。
|
||||
|
||||
Renderer 不能提交 PATH、环境变量、下载 URL、摘要、安装目录、shim 内容或任意命令参数。
|
||||
所有 IPC 输入使用共享 Zod schema，Main 重新验证路径和解释器。
|
||||
|
||||
## 12. 权限与远程边界
|
||||
|
||||
- Ask/Execute 语义不变。
|
||||
- 不新增解释器批准流程。
|
||||
- 不上传 shim、Python、pip 包或自定义路径。
|
||||
- 不修改 Host PATH。
|
||||
- 不把本机 SKILL 或 stdio MCP 传给远程 ACP Session。
|
||||
- 远程 Agent 固定 Node 继续只服务 Agent、模型桥和签名 Runtime。
|
||||
|
||||
## 13. 实施顺序
|
||||
|
||||
### 阶段 1：契约、迁移、探测和 UI
|
||||
|
||||
- Shared schema、设置迁移、IPC。
|
||||
- Node/Python 候选探测和完整诊断。
|
||||
- 设置卡片和状态。
|
||||
|
||||
### 阶段 2：托管 Node 与执行链路
|
||||
|
||||
- 提取 DSH shim。
|
||||
- 增加 node/npm/npx。
|
||||
- 注入本机 Runtime 和 stdio MCP。
|
||||
|
||||
### 阶段 3：托管 Python
|
||||
|
||||
- 锁定六平台工件。
|
||||
- 下载、校验、安装、更新、取消、删除。
|
||||
- 增加 python/python3/pip。
|
||||
|
||||
### 阶段 4：真实端到端验收
|
||||
|
||||
- Node SKILL 与 MCP。
|
||||
- Python SKILL 与 MCP。
|
||||
- 自定义解释器。
|
||||
- Ask/Execute、重建、取消和退出。
|
||||
- 六平台打包和许可证。
|
||||
|
||||
这些阶段是开发顺序，不是可长期发布的残缺功能。合并能力前完成普通用户和专业用户的完整
|
||||
生产路径。
|
||||
|
||||
## 14. 验证
|
||||
|
||||
单元测试覆盖设置迁移、探测、版本解析、shim 转义、PATH 顺序、失效路径、下载摘要和暂存
|
||||
清理。
|
||||
|
||||
集成测试覆盖安装包 Electron Node、npm/npx、托管 Python、三个本机 Runtime 和两类 stdio
|
||||
MCP 的实际进程路径。
|
||||
|
||||
项目验证：
|
||||
|
||||
```text
|
||||
npm test
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm run build
|
||||
```
|
||||
|
||||
生产资源通过六平台原生 CI 打包验证。若后续改动触及 Agent、远程协议或远程 Runtime，
|
||||
再按远程架构文档执行共享 Linux x64 Host 验证。
|
||||
@@ -0,0 +1,192 @@
|
||||
# 本机工具环境 UI 设计
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 计划 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-09-01 |
|
||||
| 关联 PRD | [本机工具环境 PRD](./prd.md) |
|
||||
| 功能逻辑 | [本机工具环境功能逻辑设计](./logic-design.md) |
|
||||
| 全局规范 | [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md) |
|
||||
|
||||
本文只定义本功能的界面结构和交互。颜色、字体、间距、通知、Switch、焦点和响应式行为以
|
||||
全局设计系统为最终权威，不在本文件建立页面专属视觉体系。
|
||||
|
||||
## 1. 信息架构
|
||||
|
||||
“本机工具环境”位于 `Agent Runtime` 设置分类，处于默认工作区之后、具体 Runtime 高级
|
||||
设置之前。它是本机 OpenCode、Continue、DeepSeek Harness 和 stdio MCP 的共享设置，
|
||||
不放入任一 Runtime 专属卡片。
|
||||
|
||||
区块顶部持续显示：
|
||||
|
||||
> 用于新启动的本机 Runtime 和 stdio MCP；不修改系统环境，也不应用于普通终端或远程主机。
|
||||
|
||||
## 2. 页面结构
|
||||
|
||||
```text
|
||||
本机工具环境
|
||||
范围说明
|
||||
|
||||
Node.js 卡片
|
||||
来源
|
||||
当前状态
|
||||
自定义候选或路径操作
|
||||
测试环境
|
||||
|
||||
Python 卡片
|
||||
来源
|
||||
当前状态
|
||||
安装/更新/删除或自定义路径操作
|
||||
测试环境
|
||||
```
|
||||
|
||||
卡片顺序固定为 Node.js、Python。页面不增加二级页签。
|
||||
|
||||
## 3. 来源选择
|
||||
|
||||
每张卡片使用原生单选语义，只提供：
|
||||
|
||||
1. **GoodBuddy 托管（推荐）**
|
||||
2. **自定义环境**
|
||||
|
||||
不显示“自动选择”“系统安装”“指定路径”三个交叉选项。自定义环境选中后，在同一区域展示
|
||||
检测候选下拉框和“选择其他可执行文件”次操作。
|
||||
|
||||
候选项格式：
|
||||
|
||||
```text
|
||||
Node.js v22.14.0 · C:\Program Files\nodejs\node.exe
|
||||
Python 3.13.2 · C:\Python313\python.exe
|
||||
```
|
||||
|
||||
版本和绝对路径不能只放在 Tooltip 中。
|
||||
|
||||
## 4. Node.js 卡片
|
||||
|
||||
```text
|
||||
Node.js
|
||||
|
||||
● GoodBuddy 托管（推荐）
|
||||
Node.js vXX · 已就绪
|
||||
npm 11.x · npx 11.x
|
||||
|
||||
○ 自定义环境
|
||||
[Node.js v22.x · C:\Program Files\nodejs\node.exe ▼]
|
||||
[选择其他可执行文件]
|
||||
|
||||
[测试环境]
|
||||
```
|
||||
|
||||
托管 Node 随应用提供，不显示安装和删除操作。测试结果分别显示 Node、npm、npx，不能用
|
||||
Node 成功代替整套组合成功。找不到配套 npm/npx 时，自定义 Node 可以保存，但状态显示
|
||||
“Node.js 已就绪，npm/npx 不可用”。
|
||||
|
||||
## 5. Python 卡片
|
||||
|
||||
托管 Python 未安装：
|
||||
|
||||
```text
|
||||
Python
|
||||
|
||||
● GoodBuddy 托管（推荐）
|
||||
尚未安装
|
||||
[安装]
|
||||
|
||||
○ 自定义环境
|
||||
[Python 3.13.x · C:\Python313\python.exe ▼]
|
||||
[选择其他可执行文件]
|
||||
```
|
||||
|
||||
安装中使用卡片内进度：
|
||||
|
||||
```text
|
||||
正在下载 Python 3.x
|
||||
[================------] 68%
|
||||
[取消]
|
||||
```
|
||||
|
||||
安装后显示：
|
||||
|
||||
- Python 版本和架构。
|
||||
- pip、venv 和 SSL 诊断状态。
|
||||
- 安装占用空间。
|
||||
- 有更新时的“更新”操作。
|
||||
- “删除托管 Python”危险次操作。
|
||||
|
||||
删除确认说明受影响范围，不要求输入确认文字：
|
||||
|
||||
> 删除后，依赖托管 Python 的本机 SKILL 和 stdio MCP 将不可用。系统 Python、自定义环境
|
||||
> 和项目文件不会被删除。
|
||||
|
||||
## 6. 两层状态
|
||||
|
||||
每张工具卡展示工具环境状态：
|
||||
|
||||
- 已就绪
|
||||
- 尚未安装
|
||||
- 正在安装
|
||||
- 路径不可用
|
||||
- 部分可用，例如 npm/npx 或 pip/venv 缺失
|
||||
- 测试失败
|
||||
- 可更新
|
||||
|
||||
SKILL/MCP 的能力详情展示能力依赖状态：
|
||||
|
||||
- 依赖已验证
|
||||
- 依赖未验证
|
||||
- 缺少第三方包
|
||||
- 入口不可用
|
||||
|
||||
不得把工具卡的“已就绪”复用为某个 SKILL 或 MCP 的“完全可用”。
|
||||
|
||||
## 7. 生效与刷新
|
||||
|
||||
保存后在卡片中持续显示：
|
||||
|
||||
> 对新启动的本机 Runtime 和 stdio MCP 生效。已运行进程不会中途切换环境。
|
||||
|
||||
设置保存成功、安装成功、删除成功和重新检测成功使用应用通知。版本、路径、安装进度和
|
||||
阻塞错误留在卡片内，不同时显示重复通知。
|
||||
|
||||
## 8. 错误与恢复
|
||||
|
||||
- 自定义路径失效：保留路径和来源选择，显示“重新检测”和“选择其他文件”。
|
||||
- 下载失败：保留已验证旧安装和安装按钮。
|
||||
- 诊断部分失败：逐项显示失败项，保留成功项。
|
||||
- 取消安装：恢复“尚未安装”或原已安装版本。
|
||||
- 字段错误：就地关联到选择控件。
|
||||
- Runtime/MCP 已运行：不显示为错误，只说明新进程生效。
|
||||
|
||||
## 9. 无障碍与键盘
|
||||
|
||||
- 来源使用 `radiogroup`/`radio` 语义。
|
||||
- 安装、测试、更新、删除和文件选择使用语义按钮。
|
||||
- 下载进度使用可命名的 `progressbar`。
|
||||
- 状态不只依赖颜色，必须包含文字。
|
||||
- 禁用控件仍提供可理解的邻近说明。
|
||||
- 切换到自定义环境后，焦点按正常 Tab 顺序进入候选选择框。
|
||||
- 对话框关闭后焦点回到触发操作。
|
||||
- 窄屏时卡片操作换行，不压缩版本和路径到不可读宽度。
|
||||
|
||||
## 10. 文案词汇
|
||||
|
||||
固定使用：
|
||||
|
||||
- 本机工具环境
|
||||
- GoodBuddy 托管
|
||||
- 自定义环境
|
||||
- 工具环境已就绪
|
||||
- 能力依赖已验证
|
||||
- 新启动的本机 Runtime 和 stdio MCP
|
||||
- 不应用于远程主机
|
||||
|
||||
不使用：
|
||||
|
||||
- 自动环境
|
||||
- 系统模式
|
||||
- 内置开发机
|
||||
- 全局 Python
|
||||
- 远程托管环境
|
||||
@@ -0,0 +1,264 @@
|
||||
# 本机工具环境 User Stories
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 计划 |
|
||||
| 版本 | 0.2 |
|
||||
| 日期 | 2026-09-01 |
|
||||
| 关联 PRD | [本机工具环境 PRD](./prd.md) |
|
||||
| 关联逻辑 | [本机工具环境功能逻辑设计](./logic-design.md) |
|
||||
|
||||
## 1. 角色
|
||||
|
||||
### 1.1 普通用户
|
||||
|
||||
希望直接使用文档、演示文稿或数据处理 SKILL，不理解 Node.js、Python、pip 或 PATH。
|
||||
|
||||
### 1.2 MCP 使用者
|
||||
|
||||
希望配置一个本机工具服务，并由 GoodBuddy 解决其基础解释器启动问题。
|
||||
|
||||
### 1.3 专业开发者
|
||||
|
||||
已有明确的 Node、Python、虚拟环境或 Conda 环境，希望控制实际版本和绝对路径。
|
||||
|
||||
### 1.4 内网与离线用户
|
||||
|
||||
无法稳定访问公网，需要使用选定镜像或离线准备环境，同时不向远程 Host 传播本机配置。
|
||||
|
||||
## 2. Epic A：普通用户无需预装环境
|
||||
|
||||
### US-A0 首次看到准确默认状态
|
||||
|
||||
作为普通用户，我希望第一次打开设置时看到 GoodBuddy 已提供什么、还需要安装什么，以免
|
||||
误以为所有工具都已就绪。
|
||||
|
||||
验收：
|
||||
|
||||
- 全新安装默认选择 GoodBuddy 托管 Node 和 Python
|
||||
- 托管 Node 立即执行真实诊断并显示版本
|
||||
- 未安装的托管 Python 显示“尚未安装”和安装入口
|
||||
- 检测到的系统解释器只作为自定义候选，不改变默认来源
|
||||
- 页面持续说明只对新启动的本机 Runtime 和 stdio MCP 生效
|
||||
|
||||
### US-A1 直接使用托管 Node
|
||||
|
||||
作为普通用户，我希望安装 GoodBuddy 后即可使用 Node.js SKILL，以免单独安装 Node.js。
|
||||
|
||||
验收：
|
||||
|
||||
- Given 系统 PATH 没有 Node.js
|
||||
- When 本机 Execute 请求运行普通 JavaScript SKILL
|
||||
- Then `node` 使用 GoodBuddy 托管来源
|
||||
- And `npm`、`npx` 与该 Node 来源一致
|
||||
- And 设置显示实际 Node 版本
|
||||
|
||||
### US-A2 按需安装 Python
|
||||
|
||||
作为普通用户，我希望在设置中安装 Python，以便运行 Python SKILL 而不离开 GoodBuddy。
|
||||
|
||||
验收：
|
||||
|
||||
- Given 系统没有 Python 且托管 Python 未安装
|
||||
- When 用户点击安装
|
||||
- Then 页面显示下载、校验和安装进度
|
||||
- And 成功后真实 Python、pip、venv 诊断通过
|
||||
- And 失败不会留下半安装目录
|
||||
|
||||
### US-A3 看懂缺失依赖
|
||||
|
||||
作为普通用户，我希望区分“没有 Python”和“缺少 python-pptx”，以便采取正确修复操作。
|
||||
|
||||
验收：
|
||||
|
||||
- 工具解释器不可用时显示工具环境错误
|
||||
- 解释器可用但能力包缺失时显示能力依赖错误
|
||||
- 页面不把 `python --version` 成功描述为 SKILL 已完全可用
|
||||
- 错误保留原任务和可执行的下一步
|
||||
|
||||
### US-A4 看懂部分就绪
|
||||
|
||||
作为用户，我希望知道解释器可用但配套命令损坏，以免把所有失败都理解为没有安装环境。
|
||||
|
||||
验收：
|
||||
|
||||
- Node 可用而 npm/npx 失败时显示“部分可用”和具体失败项
|
||||
- Python 可用而 pip、venv 或 SSL 失败时显示“部分可用”和具体失败项
|
||||
- 不依赖失败项的能力仍可通过实际诊断标记就绪
|
||||
- 没有能力专属诊断时显示“依赖未验证”，不推断为就绪
|
||||
|
||||
## 3. Epic B：本机 MCP 使用一致环境
|
||||
|
||||
### US-B1 启动 Python MCP
|
||||
|
||||
作为 MCP 使用者，我希望 `python -m my_mcp_server` 使用设置中的 Python，以免配置第二套
|
||||
解释器。
|
||||
|
||||
验收：
|
||||
|
||||
- 裸 `python`、`python3` 和 `pip` 解析到当前选择
|
||||
- Main 直连工具链和本机 Runtime 使用相同来源
|
||||
- 绝对命令路径不被替换
|
||||
- MCP 自身包缺失时准确报告依赖错误
|
||||
|
||||
### US-B2 启动 Node.js MCP
|
||||
|
||||
作为 MCP 使用者，我希望 `node server.js` 或 `npx package` 使用同一 Node 组合。
|
||||
|
||||
验收：
|
||||
|
||||
- `node`、`npm`、`npx` 来源一致
|
||||
- npm lifecycle 子进程使用当前 Node
|
||||
- 取消或关闭应用后没有遗留 MCP 进程
|
||||
|
||||
### US-B3 保持网络 MCP 不变
|
||||
|
||||
作为 MCP 使用者，我希望 HTTP/SSE MCP 不受本机解释器设置影响。
|
||||
|
||||
验收：
|
||||
|
||||
- HTTP/SSE 配置不显示本机解释器要求
|
||||
- GoodBuddy 不管理远端 MCP 服务端依赖
|
||||
- 切换本机工具环境不重建 HTTP/SSE 服务
|
||||
|
||||
## 4. Epic C：专业用户明确控制环境
|
||||
|
||||
### US-C1 使用检测到的系统解释器
|
||||
|
||||
作为专业开发者，我希望从版本和绝对路径列表中选择解释器，以便使用已有工具链。
|
||||
|
||||
验收：
|
||||
|
||||
- 候选经过真实版本和架构诊断
|
||||
- 相同真实路径不重复显示
|
||||
- 保存后状态显示实际生效来源
|
||||
- PATH 后续变化不会自动替换选择
|
||||
|
||||
### US-C2 指定项目虚拟环境
|
||||
|
||||
作为专业开发者，我希望选择未被自动发现的 Python，以便使用自己的 venv 或 Conda 环境。
|
||||
|
||||
验收：
|
||||
|
||||
- 文件选择由 Main 管理
|
||||
- 保存前验证 Python 3、版本和架构
|
||||
- GoodBuddy 不安装、升级或删除该环境
|
||||
- 路径失效时不静默回退
|
||||
|
||||
### US-C3 返回托管环境
|
||||
|
||||
作为专业开发者，我希望随时切回 GoodBuddy 托管环境，以便恢复标准组合。
|
||||
|
||||
验收：
|
||||
|
||||
- 切换前显示新启动进程才生效
|
||||
- 新 Runtime 和 stdio MCP 使用托管来源
|
||||
- 已运行进程不中途换环境
|
||||
|
||||
### US-C4 明确设置何时生效
|
||||
|
||||
作为专业开发者，我希望知道环境切换何时影响进程，以免一个运行中的任务突然换解释器。
|
||||
|
||||
验收：
|
||||
|
||||
- 保存前后都说明只对新启动进程生效
|
||||
- 有活动请求的 Runtime 保持启动时环境
|
||||
- 空闲 Runtime 在下一次使用前按现有入口重建
|
||||
- 已启动 stdio MCP 在关闭、重连或显式测试后使用新环境
|
||||
- 活动记录不根据最新设置改写历史解释器来源
|
||||
|
||||
## 5. Epic D：范围和生命周期可理解
|
||||
|
||||
### US-D1 不影响远程主机
|
||||
|
||||
作为远程项目用户，我希望清楚知道本机环境不会上传到 Host，以免错误预期远程脚本可用。
|
||||
|
||||
验收：
|
||||
|
||||
- 本机工具环境页显示范围说明
|
||||
- 远程主机设置页显示本机 Skills 和 MCP 不适用
|
||||
- Host PATH、Agent 包和 Runtime 包不包含本机选择
|
||||
|
||||
### US-D2 删除托管 Python
|
||||
|
||||
作为用户，我希望删除不再使用的托管 Python，以便释放磁盘空间。
|
||||
|
||||
验收：
|
||||
|
||||
- 删除前说明受影响的本机 SKILL 和 MCP
|
||||
- 只删除 GoodBuddy-owned Python 目录
|
||||
- 不删除系统、自定义或工作区文件
|
||||
- 使用中的进程先按现有生命周期停止
|
||||
|
||||
### US-D3 升级后保持既有解释器
|
||||
|
||||
作为现有用户，我希望升级 GoodBuddy 后已有脚本仍使用原来的系统解释器。
|
||||
|
||||
验收：
|
||||
|
||||
- 首次迁移把有效系统解释器保存为自定义绝对路径
|
||||
- 无有效解释器时才选择托管来源
|
||||
- 迁移结果只写一次
|
||||
|
||||
### US-D4 取消 Python 安装
|
||||
|
||||
作为用户，我希望可以取消耗时的 Python 安装，并在之后重试。
|
||||
|
||||
验收：
|
||||
|
||||
- 下载、校验、安装和候选诊断阶段都响应取消
|
||||
- 取消后清理本次暂存
|
||||
- 取消不发布未验证候选
|
||||
- 页面回到操作前的未安装状态或健康旧版本
|
||||
- 取消不显示为安装失败
|
||||
|
||||
### US-D5 安全更新托管 Python
|
||||
|
||||
作为用户，我希望更新托管 Python 失败时仍能使用旧版本，以免现有能力全部中断。
|
||||
|
||||
验收：
|
||||
|
||||
- 下载和验证候选期间旧版继续服务已有进程
|
||||
- 应用更新前说明需要停止哪些本机 Runtime/MCP
|
||||
- 用户确认后才通过现有生命周期停止相关进程
|
||||
- 无法停止时不替换当前版本
|
||||
- 候选完整诊断成功后才发布
|
||||
- 更新失败继续使用健康旧版本
|
||||
|
||||
### US-D6 安装解释器不扩大 Ask 权限
|
||||
|
||||
作为 Ask 用户，我希望安装 Node/Python 后仍保持原有只读边界，以免环境准备改变授权范围。
|
||||
|
||||
验收：
|
||||
|
||||
- 工具环境不新增 Runtime 工具
|
||||
- Ask 是否允许命令仍由当前 Runtime 边界决定
|
||||
- Ask 中禁止的写入和执行不会因解释器存在而放行
|
||||
- Execute 继续使用用户已授权的本机账号权限
|
||||
|
||||
## 6. Epic E：受限网络与离线行为明确
|
||||
|
||||
### US-E1 通过所选官方来源安装 Python
|
||||
|
||||
作为内网用户，我希望托管 Python 使用“关于与更新”中选择的官方来源，以便符合当前网络
|
||||
条件。
|
||||
|
||||
验收：
|
||||
|
||||
- Python 安装复用当前 GitHub/镜像来源
|
||||
- 来源不可达时显示来源和准确失败原因
|
||||
- 同一次安装不静默切换到另一来源
|
||||
- 失败保留健康旧版本或未安装状态
|
||||
|
||||
### US-E2 完全离线时使用已有环境
|
||||
|
||||
作为完全离线用户，我希望清楚知道首期可用路径，以免等待一个无法完成的下载。
|
||||
|
||||
验收：
|
||||
|
||||
- 托管 Node 安装后可离线使用
|
||||
- 托管 Python 未缓存且来源不可达时明确说明无法下载
|
||||
- 首期不展示未实现的 Python 离线导入入口
|
||||
- 用户可以选择设备上已经离线安装的自定义 Python
|
||||
@@ -0,0 +1,11 @@
|
||||
# 记忆
|
||||
|
||||
记忆定义 GoodBuddy 的用户、项目和会话记忆分区、写入边界、召回和治理。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [分区记忆 PRD](./prd.md) | 记忆范围、分区、生命周期和产品验收 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
@@ -0,0 +1,494 @@
|
||||
# 分区记忆 PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 设计中 |
|
||||
| 版本 | 0.3 |
|
||||
| 日期 | 2026-08-19 |
|
||||
| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[智能心跳 PRD](../smart-heartbeat/prd.md)、[Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
GoodBuddy 当前记忆已经支持：
|
||||
|
||||
- `global`、`project`、`conversation` 三种作用域。
|
||||
- `preference`、`fact`、`summary`、`procedure` 四种类型。
|
||||
- `proposed`、`confirmed`、`rejected` 三种状态。
|
||||
- 智能心跳提出 Global 或 Project 记忆候选，由用户确认；其长期“未来分区记忆”方向尚未设计。
|
||||
|
||||
但当前能力仍不足以支撑自动化和并行实验：
|
||||
|
||||
1. 交互请求会把已加载列表中的最多 20 条已确认记忆直接拼入提示，缺少查询相关度和明确的
|
||||
会话级过滤契约。
|
||||
2. 数据库有会话作用域，但旧版心跳候选与未来唤起需求混在同一产品概念中。
|
||||
3. 缺少 Automation、Experiment 和 Run 分区。
|
||||
4. 来源字段存在于表结构，但普通创建和心跳候选尚未完整保存来源关系。
|
||||
5. 缺少事实的有效时间、冲突、替代、访问记录和衰减。
|
||||
6. 实验 Run 若共享可变记忆，会造成候选互相污染。
|
||||
|
||||
本设计先完成分区、来源、检索和生命周期，再评估时间知识图谱。
|
||||
|
||||
## 2. 核心产品判断
|
||||
|
||||
### 2.1 分区是权限和隔离边界
|
||||
|
||||
分区不是搜索标签。每次读取先根据运行快照确定允许分区，再在这些分区中检索。
|
||||
模型不能请求任意分区 ID，Renderer 也不能把任意 ID 作为可信范围。
|
||||
|
||||
### 2.2 作用域和记忆种类是两个维度
|
||||
|
||||
- 作用域回答“谁可以读取”。
|
||||
- 类型回答“这是什么信息”。
|
||||
|
||||
不能用 `summary` 表示会话范围，也不能用 `project` 表示事实类型。
|
||||
|
||||
### 2.3 记忆和知识库分离
|
||||
|
||||
| 记忆 | 知识库 |
|
||||
| --- | --- |
|
||||
| 用户偏好、项目约定、过程经验、会话摘要 | 文档、网页、文件和外部资料 |
|
||||
| 小规模、动态、可确认和可遗忘 | 大规模、按来源同步和引用 |
|
||||
| 强调作用域、来源、时态和行为影响 | 强调检索、分块和证据引用 |
|
||||
|
||||
不能把整个文档或长工具输出保存为记忆。
|
||||
|
||||
### 2.4 第一阶段不需要图数据库
|
||||
|
||||
SQLite 显式字段、FTS、来源关系和可选本地 Embedding 足以支持首期。时间图谱只有在以下
|
||||
需求经过验证后再建设：
|
||||
|
||||
- 实体关系的多跳查询。
|
||||
- 事实有效期和关系演变。
|
||||
- 同一实体跨大量会话的别名消歧。
|
||||
- 可解释的关系证据链。
|
||||
|
||||
### 2.5 未来分区记忆尚待设计
|
||||
|
||||
已确认智能心跳的长期方向是“未来分区记忆”，但当前尚未定义其数据结构、唤起条件、状态、
|
||||
生命周期、与长期记忆的关系或迁移方式。本 PRD 不新增 `FutureMemory` 类型、表或检索规则。
|
||||
|
||||
## 3. 目标
|
||||
|
||||
- 为会话、自动化和并行 Run 提供严格隔离。
|
||||
- 每条记忆显示范围、类型、状态、来源、时间和敏感度。
|
||||
- 在允许分区内按相关性、重要性、新鲜度和预算检索。
|
||||
- 保留冲突事实和时态，不静默覆盖。
|
||||
- 让候选记忆经过确认或评估后再晋升。
|
||||
- 支持编辑、移动、合并、拒绝、归档、删除和要求忘记。
|
||||
- 记录哪些 Run 实际读取了哪些记忆。
|
||||
- 为现有智能心跳配置建立 Global 或指定 Project 范围，并保持当前候选记忆流程。
|
||||
|
||||
## 4. 非目标
|
||||
|
||||
- 不保存完整聊天、文档、工具日志或隐藏推理作为记忆。
|
||||
- 不自动确认敏感个人信息。
|
||||
- 不默认跨项目共享 Project、Conversation 或 Run 记忆。
|
||||
- 不允许模型自行创建新分区或跨分区移动记忆。
|
||||
- 不承诺记忆中的事实永远正确。
|
||||
- 第一阶段不建设 Memory Palace 五层空间隐喻。
|
||||
- 不把向量相似度作为权限判定。
|
||||
|
||||
## 5. 分区模型
|
||||
|
||||
### 5.1 分区类型
|
||||
|
||||
```ts
|
||||
type MemoryNamespaceKind =
|
||||
| 'global'
|
||||
| 'project'
|
||||
| 'conversation'
|
||||
| 'automation'
|
||||
| 'experiment'
|
||||
| 'run'
|
||||
| 'agent'
|
||||
```
|
||||
|
||||
| 分区 | 内容 | 生命周期 |
|
||||
| --- | --- | --- |
|
||||
| Global | 用户长期偏好和跨项目通用约定 | 长期，严格确认 |
|
||||
| Project | 项目术语、目标、决策和流程 | 随项目 |
|
||||
| Conversation | 当前会话摘要、局部约定和待澄清信息 | 随会话或短期 |
|
||||
| Automation | 某计划的稳定协议经验和运行约定 | 随计划 |
|
||||
| Experiment | 实验设计、结论和限制 | 随实验 |
|
||||
| Run | 单次运行观察、中间状态和临时经验 | 短期、严格隔离 |
|
||||
| Agent | 某专家或角色的个性化经验 | 后续，默认关闭 |
|
||||
|
||||
首期实现 Global、Project、Conversation、Automation 和 Run。Experiment 可复用
|
||||
Automation 机制后增加；Agent 必须在专家长期身份明确后再开放。
|
||||
|
||||
### 5.2 分区标识
|
||||
|
||||
```text
|
||||
global
|
||||
project:{projectId}
|
||||
conversation:{conversationId}
|
||||
automation:{planId}
|
||||
experiment:{experimentId}
|
||||
run:{automationRunId}
|
||||
agent:{expertId}
|
||||
```
|
||||
|
||||
数据库使用 UUID 外键和显式 `kind`，上述字符串只用于日志和展示，不作为未经验证的访问凭据。
|
||||
|
||||
### 5.3 读取链
|
||||
|
||||
交互会话推荐：
|
||||
|
||||
```text
|
||||
Conversation → Project → Global
|
||||
```
|
||||
|
||||
Task 执行（内部 Job/Run）：
|
||||
|
||||
```text
|
||||
Run → Job → Task → Conversation → Project → Global
|
||||
```
|
||||
|
||||
实验 Run：
|
||||
|
||||
```text
|
||||
Run → Experiment frozen snapshot → Project frozen snapshot → Global frozen snapshot
|
||||
```
|
||||
|
||||
各层使用独立结果数和字符预算。Run 层不能覆盖权限更高层，只能提供更具体上下文。
|
||||
|
||||
## 6. 记忆条目
|
||||
|
||||
```ts
|
||||
type MemoryItem = {
|
||||
id: string
|
||||
namespaceId: string
|
||||
kind:
|
||||
| 'preference'
|
||||
| 'fact'
|
||||
| 'summary'
|
||||
| 'procedure'
|
||||
| 'decision'
|
||||
| 'constraint'
|
||||
| 'reflection'
|
||||
content: string
|
||||
status:
|
||||
| 'candidate'
|
||||
| 'confirmed'
|
||||
| 'rejected'
|
||||
| 'superseded'
|
||||
| 'archived'
|
||||
confidence: number
|
||||
salience: number
|
||||
sensitivity: 'normal' | 'sensitive' | 'restricted'
|
||||
validFrom?: string
|
||||
validTo?: string
|
||||
expiresAt?: string
|
||||
sourceId: string
|
||||
supersedesId?: string
|
||||
createdAt: string
|
||||
updatedAt: string
|
||||
}
|
||||
```
|
||||
|
||||
兼容映射：
|
||||
|
||||
- 当前 `proposed` 对应 `candidate`。
|
||||
- 当前 `confirmed` 和 `rejected` 保留。
|
||||
- 当前四种类型保留，并按真实需求增加 `decision`、`constraint` 和 `reflection`。
|
||||
|
||||
## 7. 来源与证据
|
||||
|
||||
### 7.1 来源类型
|
||||
|
||||
```ts
|
||||
type MemorySource =
|
||||
| { type: 'user_entry'; createdBy: 'user' }
|
||||
| {
|
||||
type: 'message'
|
||||
conversationId: string
|
||||
messageId: string
|
||||
}
|
||||
| { type: 'task'; taskId: string; eventId?: string }
|
||||
| { type: 'heartbeat'; heartbeatRunId: string; entryId: string }
|
||||
| { type: 'supervisor'; supervisorRecordId: string }
|
||||
| { type: 'automation_run'; automationRunId: string }
|
||||
| {
|
||||
type: 'experiment_conclusion'
|
||||
experimentId: string
|
||||
conclusionId: string
|
||||
}
|
||||
| { type: 'artifact'; artifactId: string }
|
||||
```
|
||||
|
||||
### 7.2 来源规则
|
||||
|
||||
- 每条非用户手动记忆必须有来源。
|
||||
- 来源被删除时记忆不一定删除，但显示“来源不可用”并降低可信度。
|
||||
- 来源内容不复制进记忆表，只保存有界证据摘要和引用。
|
||||
- 用户确认只表示允许后续使用，不表示事实已被外部验证。
|
||||
- Supervisor 判断只能生成候选，不能直接生成确认事实。
|
||||
|
||||
## 8. 候选生成
|
||||
|
||||
候选来源：
|
||||
|
||||
- 用户明确“记住这个”。
|
||||
- 会话结束总结。
|
||||
- Task 执行结束反思。
|
||||
- 实验结论。
|
||||
- Supervisor 建议后用户采纳。
|
||||
- 智能心跳。
|
||||
|
||||
候选生成必须：
|
||||
|
||||
- 限制数量和长度。
|
||||
- 检查同分区近似重复。
|
||||
- 标记推断和不确定性。
|
||||
- 不自动提取密码、密钥、身份号码、健康和财务等敏感信息。
|
||||
- 不把指令型工具输出自动当作用户偏好。
|
||||
- 不从助手自己的未确认陈述提取事实。
|
||||
|
||||
## 9. 确认与晋升
|
||||
|
||||
### 9.1 允许路径
|
||||
|
||||
```text
|
||||
Run candidate
|
||||
→ Automation candidate
|
||||
→ Project candidate
|
||||
→ Global candidate
|
||||
```
|
||||
|
||||
每次跨层都是显式晋升，不是移动原记录：
|
||||
|
||||
- 保留原候选和来源。
|
||||
- 创建目标分区新版本。
|
||||
- 保存晋升理由、评估和操作者。
|
||||
- 可回滚到晋升前状态。
|
||||
|
||||
### 9.2 确认规则
|
||||
|
||||
- Global 默认必须人工确认。
|
||||
- Project 默认人工确认，可对特定低敏感模板启用批量确认。
|
||||
- Conversation 可以由用户“记住”直接确认。
|
||||
- Automation 和 Run 由自动化协议决定，但只在自身范围有效。
|
||||
- Experiment 结论必须结算成功且显示证据，才可成为 Project 候选。
|
||||
|
||||
### 9.3 拒绝
|
||||
|
||||
拒绝后：
|
||||
|
||||
- 不进入检索。
|
||||
- 保存规范化摘要指纹，减少重复建议。
|
||||
- 用户可查看和恢复。
|
||||
- 不把拒绝内容回填给模型，除非用于“避免重复建议”的有界规则。
|
||||
|
||||
## 10. 检索
|
||||
|
||||
### 10.1 两步边界
|
||||
|
||||
```text
|
||||
根据可信运行上下文确定允许分区
|
||||
→ 在允许分区中检索和排序
|
||||
```
|
||||
|
||||
这两步不能颠倒。先全库相似搜索再过滤会增加泄漏和实现风险。
|
||||
|
||||
### 10.2 排序
|
||||
|
||||
建议综合：
|
||||
|
||||
- 文本相关度。
|
||||
- 可选向量相关度。
|
||||
- Salience。
|
||||
- Confidence。
|
||||
- 新鲜度和有效时间。
|
||||
- 类型匹配。
|
||||
- 分区优先级。
|
||||
- 最近是否已使用。
|
||||
|
||||
只有 `confirmed`、当前有效且敏感度允许的记忆进入普通上下文。
|
||||
|
||||
### 10.3 预算
|
||||
|
||||
建议默认：
|
||||
|
||||
| 层级 | 最大条数 | 最大字符 |
|
||||
| --- | --- | --- |
|
||||
| Run | 8 | 4,000 |
|
||||
| Automation / Experiment | 8 | 4,000 |
|
||||
| Conversation | 8 | 4,000 |
|
||||
| Project | 10 | 5,000 |
|
||||
| Global | 6 | 3,000 |
|
||||
|
||||
总预算还受模型上下文组装器限制。不能每层取满后无界拼接。
|
||||
|
||||
### 10.4 上下文格式
|
||||
|
||||
提供给 Runtime 的每条记忆包含：
|
||||
|
||||
- 类型。
|
||||
- 范围。
|
||||
- 内容。
|
||||
- 有效时间。
|
||||
- 来源类型和可选引用。
|
||||
- 不确定或冲突标记。
|
||||
|
||||
可信指令明确说明记忆是用户确认的信息或候选证据，不是系统指令。
|
||||
|
||||
## 11. 冲突与时态
|
||||
|
||||
### 11.1 冲突
|
||||
|
||||
新条目与现有条目冲突时：
|
||||
|
||||
- 不静默覆盖。
|
||||
- 创建冲突关系。
|
||||
- 向用户展示两个内容、来源、时间和范围。
|
||||
- 用户可选择保留两者、设定有效期、替代旧条目或拒绝新条目。
|
||||
|
||||
### 11.2 时态
|
||||
|
||||
事实和决策支持：
|
||||
|
||||
- `validFrom`：何时开始有效。
|
||||
- `validTo`：何时不再有效。
|
||||
- `observedAt`：何时被系统观察。
|
||||
- `createdAt`：何时写入数据库。
|
||||
|
||||
例如“项目目标是 8 月发布”变更为“延期到 9 月”时，旧事实保留历史有效期，新事实成为
|
||||
当前有效版本。
|
||||
|
||||
### 11.3 适用范围冲突
|
||||
|
||||
Project 记忆与 Global 偏好冲突时：
|
||||
|
||||
- 当前 Project 的更具体约定优先。
|
||||
- 上下文中标明这是项目级覆盖。
|
||||
- 不修改 Global 原记录。
|
||||
|
||||
## 12. 实验隔离
|
||||
|
||||
- 实验启动时冻结可读长期记忆快照。
|
||||
- 各 Run 拥有独立 Run 分区。
|
||||
- Run 期间产生的候选不互相可见。
|
||||
- 实验结算后只从成功 Run 和有效证据生成 Experiment 候选。
|
||||
- 最佳 Run 的临时经验不会自动晋升。
|
||||
- 重跑相同协议可以选择复用原冻结快照或创建新版本，必须明确显示。
|
||||
|
||||
## 13. 生命周期与衰减
|
||||
|
||||
### 13.1 访问记录
|
||||
|
||||
保存有界使用记录：
|
||||
|
||||
- 哪个 Run 检索了该记忆。
|
||||
- 是否实际进入模型上下文。
|
||||
- 是否被用户或评估器认为有用。
|
||||
- 最近使用时间和命中次数。
|
||||
|
||||
不保存完整请求副本。
|
||||
|
||||
### 13.2 衰减
|
||||
|
||||
- Preference、Constraint 和 Procedure 不仅因时间自动失效。
|
||||
- Conversation、Run Summary 和 Reflection 可配置过期时间。
|
||||
- 长期未命中、低 Salience 的候选可归档。
|
||||
- 衰减先影响排序，再进入归档，不直接硬删除。
|
||||
- Restricted 记忆可采用更短保留期。
|
||||
|
||||
### 13.3 删除与忘记
|
||||
|
||||
- 删除记忆后立即停止检索。
|
||||
- “忘记”同时清理派生索引、Embedding 和缓存。
|
||||
- 来源消息是否删除由其自身生命周期决定，不能反向静默删除用户会话。
|
||||
- 删除 Project 时清理其分区、自动化和 Run 记忆，不影响 Global。
|
||||
- 审计只保留不含原内容的删除事件和 ID 摘要。
|
||||
|
||||
## 14. 敏感信息
|
||||
|
||||
| 敏感度 | 行为 |
|
||||
| --- | --- |
|
||||
| Normal | 按普通确认和检索规则 |
|
||||
| Sensitive | 必须人工确认，UI 持续标记 |
|
||||
| Restricted | 默认不允许模型自动生成；仅用户手动创建，读取需要显式启用 |
|
||||
|
||||
禁止自动长期记忆：
|
||||
|
||||
- 密码、密钥、Token、Cookie。
|
||||
- 完整身份证件、银行卡和账户凭据。
|
||||
- 未经用户明确要求的健康、财务和高度私密信息。
|
||||
- 工具输出中的认证数据。
|
||||
|
||||
## 15. 信息架构
|
||||
|
||||
记忆中心建议页签：
|
||||
|
||||
1. **记忆**：按范围、类型、状态和敏感度浏览。
|
||||
2. **待确认**：候选、冲突和晋升请求。
|
||||
3. **分区**：Global、Project、Conversation、Automation、Run 的统计和访问策略。
|
||||
4. **使用记录**：哪些 Run 使用了哪些记忆。
|
||||
5. **设置**：候选生成、保留期、敏感信息和检索预算。
|
||||
|
||||
每条记忆展示内容、类型、范围、来源、状态、时间、置信度、重要性和冲突。
|
||||
|
||||
智能心跳的完整配置仍在“智能心跳”菜单中管理；未来分区记忆完成独立设计前，不加入记忆
|
||||
中心信息架构。
|
||||
|
||||
## 16. 数据模型建议
|
||||
|
||||
建议表：
|
||||
|
||||
- `memory_namespaces`
|
||||
- `memory_items`
|
||||
- `memory_sources`
|
||||
- `memory_relations`
|
||||
- `memory_access_events`
|
||||
- `memory_promotion_events`
|
||||
- `memory_embeddings`，可选
|
||||
|
||||
现有 `memory_items` 可渐进迁移：
|
||||
|
||||
1. 增加 Namespace 并回填现有 Scope。
|
||||
2. 回填来源为空的旧记录为 `legacy_unknown`。
|
||||
3. 增加状态和类型兼容映射。
|
||||
4. 上线新检索器后再停止旧的列表拼接方式。
|
||||
|
||||
## 17. 安全与隐私
|
||||
|
||||
1. 分区解析只在 Main 进行。
|
||||
2. 所有 ID 重新验证对象归属和项目范围。
|
||||
3. Renderer 无法指定任意分区进行搜索。
|
||||
4. Runtime 只能获得有界记忆文本和来源摘要。
|
||||
5. Embedding 只能发送用户已配置允许的记忆，Restricted 默认不发送外部服务。
|
||||
6. 记忆内容和来源不出现在普通日志与通知。
|
||||
7. 跨分区晋升需要明确操作和审计。
|
||||
8. Ask 和 Execute 使用同一只读记忆检索边界。
|
||||
9. 记忆不能绕过系统指令、工具审批和工作区权限。
|
||||
|
||||
## 18. 实施顺序
|
||||
|
||||
1. 修正当前交互请求的范围过滤，确保只读 Global、当前 Project 和当前 Conversation。
|
||||
2. 增加来源记录和“实际进入上下文”的诊断。
|
||||
3. 为现有智能心跳配置增加 Global 或指定 Project 范围，保持候选记忆行为不变。
|
||||
4. 建立 Automation 和 Run Namespace。
|
||||
5. 上线有界相关检索，替换简单列表前 20 条拼接。
|
||||
6. 增加冲突、时态、替代和归档。
|
||||
7. 增加实验冻结快照与 Run 隔离。
|
||||
8. 增加可选本地 Embedding 和混合排序。
|
||||
9. 未来分区记忆和时间知识图谱都必须在明确需求与独立设计后再实施。
|
||||
|
||||
## 19. 验收标准
|
||||
|
||||
- [ ] 普通会话只读取 Global、当前 Project 和当前 Conversation 的允许记忆。
|
||||
- [ ] 智能心跳配置只能属于 Global 或 Main 已验证的一个、多个 Project。
|
||||
- [ ] 未来分区记忆完成独立设计前，不新增相关表、状态或检索行为。
|
||||
- [ ] Task 执行只读取内部 Run 快照绑定的分区。
|
||||
- [ ] 实验 Run 不能读取其他 Run 的消息或记忆。
|
||||
- [ ] 每条非手动记忆都有可追溯来源。
|
||||
- [ ] 候选和被拒绝记忆不进入普通上下文。
|
||||
- [ ] Global 和 Project 晋升需要明确确认或评估。
|
||||
- [ ] 冲突事实不被静默覆盖。
|
||||
- [ ] 当前有效事实可通过有效时间正确选择。
|
||||
- [ ] 上下文组装遵守各层和总字符预算。
|
||||
- [ ] UI 能在 Task 执行记录中显示实际使用的记忆，不把 Run 暴露为独立导航对象。
|
||||
- [ ] 删除或忘记后，文本、索引和缓存不再可检索。
|
||||
- [ ] Restricted 记忆不会自动生成或发送给外部 Embedding 服务。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 并行实验
|
||||
|
||||
并行实验定义多个候选方案、模型或执行分支的受控比较、评估与结果选择。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [并行实验工作台 PRD](./prd.md) | 实验对象、工作台流程、评估和验收 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
@@ -0,0 +1,389 @@
|
||||
# 并行实验工作台 PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 设计中 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-08-13 |
|
||||
| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
GoodBuddy 已能把一个请求并行委派给最多三个只读专家，再综合结果。这适合“一次请求，
|
||||
多种专业视角”，但不等同于实验：当前没有结构化变量、重复运行、统一指标、结果晋升和
|
||||
Run 级记忆隔离。
|
||||
|
||||
本功能借鉴 MesaLogo ParallelLab 中变量隔离、批量 Run、失败结算、指标比较和运行证据
|
||||
的思想，但不引入其 Action Space、服务端队列或重型仿真平台。
|
||||
|
||||
## 2. 产品定义
|
||||
|
||||
并行实验是在冻结的研究问题和执行协议下，生成多个相互隔离的候选 Run，以相同评估标准
|
||||
比较结果，并将结论追溯到运行证据。
|
||||
|
||||
```text
|
||||
Experiment
|
||||
├─ Question / Hypothesis
|
||||
├─ Protocol
|
||||
├─ Variables and Variants
|
||||
├─ Objectives and Evaluators
|
||||
├─ Budget and Stop Conditions
|
||||
└─ ExperimentRun × N
|
||||
├─ Isolated Conversation
|
||||
├─ Isolated Run Memory
|
||||
├─ Tasks and Artifacts
|
||||
├─ Metrics
|
||||
└─ Evidence
|
||||
```
|
||||
|
||||
## 3. 已确认的产品决策
|
||||
|
||||
1. 实验 Run 复用现有 Task、Runtime、Artifact 和审批机制。
|
||||
2. 每个 Run 有独立变量、会话、运行记忆、任务和成果。
|
||||
3. 默认实验是只读 Ask；写工作区的实验后续使用每 Run 独立沙箱。
|
||||
4. 多个 Run 不能并发修改同一个用户工作区。
|
||||
5. 失败、取消、预算耗尽或结果不完整的 Run 不参与最佳结果选择。
|
||||
6. 没有成功 Run 时实验为失败或无结论，不能报告成功。
|
||||
7. 模型生成的实验协议必须可审查、编辑和版本化。
|
||||
8. 评估优先使用确定性指标；模型 Rubric 显示评估器版本和不确定性。
|
||||
9. “最佳”只针对声明的目标和约束，不代表普遍最好。
|
||||
10. 最佳结果只能创建候选，不能直接覆盖计划、记忆或工作区。
|
||||
|
||||
## 4. 目标
|
||||
|
||||
- 把问题转为可审查的实验问题、变量、候选和指标。
|
||||
- 比较不同提示、模型、专家组合、参数或方案。
|
||||
- 监控每个 Run 的状态、成本、证据和失败原因。
|
||||
- 查看结果表、差异、稳定性和评估依据。
|
||||
- 从候选创建普通任务、计划草稿或记忆候选。
|
||||
- 为持续学习提供回放和非退化评估基础。
|
||||
|
||||
## 5. 非目标
|
||||
|
||||
- 第一阶段不模拟数千 Agent 或社会群体涌现。
|
||||
- 不实现任意连续参数的自动贝叶斯优化。
|
||||
- 不在样本不足时宣称统计显著性。
|
||||
- 不把模型的自报置信度直接作为跨模型比较指标。
|
||||
- 不允许实验自行增加样本数、预算或能力范围。
|
||||
- 不允许自动部署结果或修改安全策略。
|
||||
- 不把专家团队的一次回答自动包装成科学实验。
|
||||
|
||||
## 6. 实验类型
|
||||
|
||||
| 类型 | 变量示例 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| Prompt 对比 | 系统说明、输出格式、示例 | 比较自动化协议 |
|
||||
| 模型对比 | 已配置文本模型 | 质量、速度和 Token 权衡 |
|
||||
| 专家组合 | 专家集合、综合策略 | 多视角研究 |
|
||||
| 参数扫描 | 检索模式、Top K、轮数 | 寻找有限参数组合 |
|
||||
| 方案候选 | 多个用户或模型方案 | 按统一 Rubric 比较 |
|
||||
| 回放评估 | 历史脱敏案例集合 | 验证学习候选是否退化 |
|
||||
|
||||
后续多轮情景模拟需要单独定义角色、环境和状态变量。
|
||||
|
||||
## 7. 创建流程
|
||||
|
||||
### 7.1 研究问题
|
||||
|
||||
用户填写：
|
||||
|
||||
- 实验名称。
|
||||
- 问题和可选假设。
|
||||
- 探索、比较、优化或回放验证类型。
|
||||
- 项目范围。
|
||||
- 期望输出。
|
||||
- 禁止行为。
|
||||
|
||||
### 7.2 协议
|
||||
|
||||
`ExperimentProtocol` 包含：
|
||||
|
||||
- 基准输入或案例集。
|
||||
- 固定提示和步骤。
|
||||
- 变量与候选。
|
||||
- Runtime、模型和专家。
|
||||
- 工具、知识库和记忆范围。
|
||||
- 工作模式。
|
||||
- 每 Run 预算。
|
||||
- 指标、评估器和停止条件。
|
||||
- 重复次数。
|
||||
|
||||
模型生成协议草稿时必须标明用户字段、模型建议、确定性指标和模型判断指标。
|
||||
|
||||
### 7.3 变量
|
||||
|
||||
```ts
|
||||
type ExperimentVariable =
|
||||
| { name: string; type: 'enum'; values: JsonValue[] }
|
||||
| {
|
||||
name: string
|
||||
type: 'range'
|
||||
start: number
|
||||
end: number
|
||||
step: number
|
||||
}
|
||||
| { name: string; type: 'boolean' }
|
||||
| { name: string; type: 'prompt_variant'; values: string[] }
|
||||
| {
|
||||
name: string
|
||||
type: 'model_profile'
|
||||
profileIds: string[]
|
||||
}
|
||||
| {
|
||||
name: string
|
||||
type: 'expert_set'
|
||||
expertIdSets: string[][]
|
||||
}
|
||||
```
|
||||
|
||||
第一阶段只支持有限、确定生成的组合。保存前展示组合数、重复后 Run 总数、最大模型调用、
|
||||
Token 和耗时范围，以及最大并发。超过上限时要求缩小变量，不静默抽样。
|
||||
|
||||
### 7.4 基准与候选
|
||||
|
||||
- 至少一个 Variant。
|
||||
- 对比实验建议设置 Baseline。
|
||||
- Baseline 与 Candidate 使用相同案例和评估器。
|
||||
- 评估器不能读取 Variant 标签和模型名称作为质量信号。
|
||||
- 模型评分时随机化候选顺序并保存实际顺序。
|
||||
|
||||
## 8. Run 隔离
|
||||
|
||||
### 8.1 数据隔离
|
||||
|
||||
每个 Run 独立拥有：
|
||||
|
||||
- `experimentRunId` 和运行会话。
|
||||
- 变量快照和临时上下文。
|
||||
- Run 记忆分区。
|
||||
- Task、Job、Subjob 和成果。
|
||||
- 指标、证据和 Runtime 会话标识。
|
||||
|
||||
禁止：
|
||||
|
||||
- Run A 读取 Run B 的消息、临时记忆或中间成果。
|
||||
- 多个 Run 共享可变变量对象。
|
||||
- Run 候选记忆在实验结算前进入其他 Run。
|
||||
- 通过全局列表误取其他项目或实验数据。
|
||||
|
||||
### 8.2 工作区隔离
|
||||
|
||||
阶段 1 只支持 Ask 和只读工具。阶段 2 的 Execute Run 使用独立临时沙箱或版本化工作树，
|
||||
结果以 Patch 或成果展示，用户选择候选后再进入单独应用流程。
|
||||
|
||||
### 8.3 记忆隔离
|
||||
|
||||
Run 只读取冻结的 Global、Project、Automation 记忆快照和自己的 Run 分区，
|
||||
不读取其他 Run 或实验期间新产生的候选记忆。
|
||||
|
||||
## 9. 调度与预算
|
||||
|
||||
- 默认最大并发 3，与现有子专家调度能力一致。
|
||||
- 还需遵守全局后台并发和模型连接并发。
|
||||
- 每个 Variant 使用相同的单 Run 预算。
|
||||
- 不因候选暂时领先而静默给它更多预算。
|
||||
- 提前停止必须来自预先声明的规则。
|
||||
- UI 显示运行、排队、成功、失败和取消数量。
|
||||
|
||||
停止条件：
|
||||
|
||||
```ts
|
||||
type ExperimentStopCondition =
|
||||
| { type: 'all_runs_terminal' }
|
||||
| { type: 'successful_run_count'; count: number }
|
||||
| {
|
||||
type: 'metric_threshold'
|
||||
metric: string
|
||||
operator: string
|
||||
value: number
|
||||
}
|
||||
| { type: 'budget' }
|
||||
| { type: 'deadline'; at: string }
|
||||
| { type: 'manual' }
|
||||
```
|
||||
|
||||
触发停止后不启动新 Run；是否取消正在运行的 Run 必须在条件中明确。保存停止原因，
|
||||
未运行 Variant 不参与最终比较。
|
||||
|
||||
## 10. 评估与指标
|
||||
|
||||
### 10.1 指标类型
|
||||
|
||||
| 类型 | 示例 |
|
||||
| --- | --- |
|
||||
| 确定性结果 | Schema 有效、测试通过、文件存在、检查项完成 |
|
||||
| 运行指标 | 耗时、模型调用、Token、工具调用、成果大小 |
|
||||
| 检索指标 | 召回、引用覆盖、降级状态 |
|
||||
| 人工评分 | 正确性、可用性、偏好 |
|
||||
| 模型 Rubric | 结构、完整性、表达、风险 |
|
||||
|
||||
### 10.2 模型 Rubric
|
||||
|
||||
必须保存 Rubric 版本、评估模型、输入证据摘要、候选展示顺序、分项得分、结构化理由和
|
||||
格式修复。它不能覆盖确定性失败，也不能在缺少证据时编造事实正确性判断。
|
||||
|
||||
### 10.3 多目标
|
||||
|
||||
```ts
|
||||
type ExperimentObjective = {
|
||||
metric: string
|
||||
direction: 'maximize' | 'minimize' | 'target'
|
||||
weight?: number
|
||||
target?: number
|
||||
hardConstraint?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
结算先排除非成功和违反硬约束的 Run，再计算其余指标。存在明显权衡时展示 Pareto 候选，
|
||||
不强行选唯一最佳。
|
||||
|
||||
## 11. 结算规则
|
||||
|
||||
Run 成功要求：
|
||||
|
||||
- Runtime 正常结束。
|
||||
- 必填成果存在。
|
||||
- 必填评估器成功。
|
||||
- 未违反硬约束。
|
||||
- 没有结果未知的副作用。
|
||||
|
||||
Experiment 结算：
|
||||
|
||||
| 情况 | 状态 |
|
||||
| --- | --- |
|
||||
| 至少一个成功 Run，所需 Run 已结算 | `completed` |
|
||||
| 所有 Run 失败或无有效结果 | `failed` |
|
||||
| 提前停止且已有可比较结果 | `stopped_with_results` |
|
||||
| 提前停止且无可比较结果 | `cancelled` |
|
||||
| 指标冲突或证据不足 | `inconclusive` |
|
||||
|
||||
最佳结果展示 Variant、参数、成功和失败数量、重复运行原始值与聚合、目标分项、硬约束、
|
||||
证据和限制。只有一个成功 Run 时使用“当前最高分候选”，不使用“稳定最佳”。
|
||||
|
||||
## 12. 重复与复现
|
||||
|
||||
- 每个 Variant 默认重复 1 次，波动敏感实验建议至少 3 次。
|
||||
- 重复 Run 使用相同变量和独立运行会话。
|
||||
- Runtime 支持种子时保存种子，否则明确标注不可完全复现。
|
||||
- 聚合展示原始值、中位数或均值，并说明计算方式。
|
||||
- 样本不足时不展示统计显著性结论。
|
||||
|
||||
## 13. 会话监督接入
|
||||
|
||||
Supervisor 可以检查偏离协议、遗漏必填输出、证据不足和候选间协议不一致；
|
||||
确定性预算或权限违规可以暂停 Run，模型判断默认只警告或请求人工复核。
|
||||
|
||||
Supervisor 不能：
|
||||
|
||||
- 根据其他候选结果提示当前 Run。
|
||||
- 临时修改某个候选协议。
|
||||
- 自动提高预算或批准工具。
|
||||
|
||||
## 14. 信息架构
|
||||
|
||||
实验工作台页签：
|
||||
|
||||
1. **设计**：问题、协议、变量、指标和预算。
|
||||
2. **运行**：总体进度、候选执行和聚合状态。
|
||||
3. **比较**：指标表、图表、差异和 Pareto 候选。
|
||||
4. **证据**：按结论、指标和候选查看证据。
|
||||
5. **结论**：总结、限制和后续操作。
|
||||
|
||||
候选详情在 Experiment 工作台内展示参数、协议版本、时间线、消息、Task、成果、监督记录、
|
||||
指标、评估理由、上下文和记忆快照、Token、耗时与错误。内部 Run ID 只用于关联和审计，
|
||||
不提供独立 Run 路由、页面或操作菜单。
|
||||
|
||||
## 15. 后续操作
|
||||
|
||||
允许：
|
||||
|
||||
- 用候选参数创建普通任务。
|
||||
- 创建自动化计划草稿。
|
||||
- 保存实验模板。
|
||||
- 创建记忆候选。
|
||||
- 追加确认执行。
|
||||
- 导出脱敏结果摘要。
|
||||
|
||||
不得自动启用新计划、覆盖现有计划、确认长期记忆、应用工作区 Patch 或扩大权限。
|
||||
|
||||
## 16. 数据模型建议
|
||||
|
||||
```ts
|
||||
type Experiment = {
|
||||
id: string
|
||||
projectId?: string
|
||||
name: string
|
||||
question: string
|
||||
status:
|
||||
| 'draft'
|
||||
| 'queued'
|
||||
| 'running'
|
||||
| 'paused'
|
||||
| 'completed'
|
||||
| 'failed'
|
||||
| 'stopped_with_results'
|
||||
| 'inconclusive'
|
||||
| 'cancelled'
|
||||
protocolVersion: number
|
||||
totalRuns: number
|
||||
successfulRuns: number
|
||||
failedRuns: number
|
||||
}
|
||||
|
||||
type ExperimentRun = {
|
||||
id: string
|
||||
experimentId: string
|
||||
variantId: string
|
||||
repetition: number
|
||||
automationRunId: string
|
||||
variables: Record<string, JsonValue>
|
||||
status: string
|
||||
goalStatus: 'met' | 'not_met' | 'inconclusive'
|
||||
}
|
||||
```
|
||||
|
||||
建议表：
|
||||
|
||||
- `experiments`
|
||||
- `experiment_protocol_versions`
|
||||
- `experiment_variants`
|
||||
- `experiment_runs`
|
||||
- `experiment_run_metrics`
|
||||
- `experiment_evidence`
|
||||
- `experiment_conclusions`
|
||||
|
||||
## 17. 安全与隐私
|
||||
|
||||
1. 协议、案例、输出和评估输入都视为不可信数据。
|
||||
2. Renderer 不能指定其他项目的 Run 或记忆分区。
|
||||
3. 每个 Run 使用唯一 Runtime conversation ID，并在结束后释放。
|
||||
4. 实验默认不能写用户工作区。
|
||||
5. 模型对比不能传递其他供应商的凭据或隐藏配置。
|
||||
6. 导出默认不包含完整私人案例、提示、消息或文件内容。
|
||||
7. 取消实验传播到排队和运行任务，但不伪装撤销已有副作用。
|
||||
8. 实验删除不能误删已由用户独立保存的成果或计划候选。
|
||||
|
||||
## 18. 实施顺序
|
||||
|
||||
1. 建立 Experiment、Variant、Run 聚合实体和只读 Ask Run。
|
||||
2. 实现有限组合、预算估算、并发调度和运行监控。
|
||||
3. 增加确定性指标、失败结算和结果比较。
|
||||
4. 增加模型 Rubric、人工评分和证据工作台。
|
||||
5. 增加重复运行和回放评估。
|
||||
6. 最后评估独立工作树中的 Execute 实验。
|
||||
|
||||
## 19. 验收标准
|
||||
|
||||
- [ ] 保存前显示变量组合、重复后 Run 总数和最大预算。
|
||||
- [ ] 每个 Run 的会话、变量、记忆、任务和成果相互隔离。
|
||||
- [ ] 默认实验无法写用户工作区。
|
||||
- [ ] 最大并发和全局后台预算同时生效。
|
||||
- [ ] 各 Variant 使用相同单 Run 预算。
|
||||
- [ ] 失败、取消、预算耗尽和不完整 Run 不参与最佳选择。
|
||||
- [ ] 全部 Run 失败时实验不报告成功或最佳结果。
|
||||
- [ ] 模型 Rubric 显示版本、模型、分项和证据。
|
||||
- [ ] 多目标冲突时可以展示多个 Pareto 候选。
|
||||
- [ ] 用户可从候选创建草稿，但不会自动部署或确认记忆。
|
||||
- [ ] 结论能追溯到具体 Run、指标、成果和证据。
|
||||
@@ -0,0 +1,13 @@
|
||||
# 远程主机与远程执行
|
||||
|
||||
本功能负责 SSH Host 管理、Host Key、远程环境安装、GoodBuddy Agent、签名 Runtime、
|
||||
远程 Workspace 和 Ask/Execute 生产路径。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [远程主机与 Agent 技术设计](./technical-design.md) | 当前产品语义、Agent、Runtime、Workspace、协议、生命周期和验证事实 |
|
||||
| [远程环境准备技术设计](./environment-provisioning-technical-design.md) | Host 下载、GoodBuddy 传输、安装事务、更新和恢复边界 |
|
||||
|
||||
现有文档包含产品、功能逻辑和进度事实，后续修改远程功能时再按标准职责拆分。
|
||||
@@ -0,0 +1,329 @@
|
||||
# SSH Host 远程环境准备与直连下载设计
|
||||
|
||||
## 状态
|
||||
|
||||
本文记录 2026-08-28 确认的目标设计及当前实施状态。源码已经实现 Host 手动准备、
|
||||
GoodBuddy 传输、Host 直连下载、control-plane one-shot installer、发布后健康 adoption，
|
||||
以及项目路径只验证已安装环境。Host 负责 Agent/Runtime 的安装与更新生命周期，项目流程
|
||||
只消费已经准备好的 Host 环境。
|
||||
|
||||
当前源码可以直接使用既有 package format v1 `.gbagent`：归档已经包含固定 Agent 和
|
||||
Node，installer 由 GoodBuddy 桌面控制面打包并通过固定 SSH prepare channel 单次发送，
|
||||
不要求归档包含 `agent/lib/package-installer.cjs`，签名目录也不提供或检查额外的
|
||||
bootstrap 能力元数据。公开直连能力仍须完成本文末尾 GitHub/北京镜像、Linux x64/arm64、
|
||||
取消和离线 GoodBuddy 传输的真实 Host 验收；本文
|
||||
不表示这些验收或新的 Agent 发布已经发生。当前实现细节同时以
|
||||
[SSH 远程主机与 GoodBuddy Agent 实现说明](./technical-design.md)
|
||||
和源码为准。
|
||||
|
||||
## 设计结论
|
||||
|
||||
将安装和更新从项目切换移到 Host 管理是合理的，原因如下：
|
||||
|
||||
- Agent、固定 Node 和 OpenCode Runtime 安装在 SSH 账号 Home 下，由同一 Host/账号上的
|
||||
多个项目共享，不属于某一个 Workspace。
|
||||
- 大文件传输发生在项目切换时会阻塞导航，也把 Host 级故障误显示成项目故障。
|
||||
- Host Key、认证、平台和架构本来就在新增 Host 时验证，此时继续只读探测并在 Host 卡片
|
||||
提供手动准备入口最容易理解。
|
||||
- 项目只保存 Host ID、远端路径、Runtime 选择和默认工作模式。Agent installation、
|
||||
Runtime digest、Workspace identity 和 Host revision 都从当次连接取得，不写入项目；
|
||||
“移出安装”不等于“跳过当前环境检查”。
|
||||
|
||||
目标职责是：
|
||||
|
||||
| 流程 | 职责 |
|
||||
| --- | --- |
|
||||
| 新增或重新验证 Host | 验证身份和认证，保存 Host 并探测环境，不传输安装包 |
|
||||
| Host 管理 | 用户明确刷新目标 Host，并可选择安装、同版本重修、取消和重试 |
|
||||
| 创建远程项目 | 只读本地 Host 验证记录，保存时连接所选 Host 并验证当前 Agent、Workspace、Runtime 和模型配置，只持久化稳定配置 |
|
||||
| 切换远程项目 | 只切换本地项目配置，不连接 Host；实际使用 Workspace 或 Runtime 时按需复用 Host 当前环境 |
|
||||
|
||||
## 不变量
|
||||
|
||||
- Host 配置与远程环境准备是两个事务。SSH 验证成功后先原子保存 Host、凭据和完整 Host
|
||||
Key，再开始可能耗时的下载和安装。
|
||||
- 环境准备失败或取消时保留已保存 Host，显示“未就绪”并允许重试，不创建半完成项目。
|
||||
- 不把“环境健康”保存为长期可信布尔值。设置页从 Host 的签名 registry 和当前 Host
|
||||
identity 派生版本状态；准备完成和实际使用时再执行 bootstrap/health。合法但暂未运行的
|
||||
detached Agent 仍可显示为已安装，打开设置不能为了刷新卡片隐式启动或更新它。
|
||||
- 所有安装继续使用 GoodBuddy-owned staging 和 side-by-side digest 目录。失败不得覆盖
|
||||
可用旧安装，也不得删除 Host 上无关文件。
|
||||
- Renderer 不接收下载 URL、缓存路径、签名 key、digest、SSH 命令或凭据。Main 负责来源
|
||||
选择、可信目录解析、操作编排和 IPC 输入校验。
|
||||
- 产品不提供“自动安装远程环境”开关。保存、重新验证或打开 Host 都不能自动传输
|
||||
`.gbagent`；只有用户点击 Host 卡片的主按钮后，Main 才开始准备。
|
||||
- Host 卡片只有一个主按钮，按版本事实显示“安装远程环境”“更新远程环境”或“重新安装”。
|
||||
次级 SegmentedControl 选择“自动”“Host 下载”或“GoodBuddy 传输”；默认“自动”，只影响
|
||||
下一次操作，不持久化为 Host 配置。
|
||||
- “自动”只在 operation/prepare 前执行一次 Host capability probe：直连明确可用时选择
|
||||
Host 下载，否则选择 GoodBuddy 传输。用户显式选择的方式保持有效；一旦 acquisition
|
||||
已选定，prepare、commit 或 adoption 的任何失败都停止本次操作，不跨 acquisition
|
||||
自动回退。
|
||||
- 直连安装只要求已验证 SSH 连接和远端系统工具，不要求现有 Agent daemon。轻量能力探测
|
||||
返回确定性缺少工具、空间、权限或来源不可达时说明原因；探测本身异常时仍允许用户点击
|
||||
直连安装，由实际安装流程重新解析签名候选并通过 SSH 重试。
|
||||
- 项目路径不得为了“方便”回退到隐式安装。Host 未就绪时应引导到 Host 设置，不在项目
|
||||
切换器中启动大文件传输。
|
||||
|
||||
## 新增 Host 流程
|
||||
|
||||
新增向导保持现有 Host Key 和认证顺序，并在系统探针之后显示一次只读环境结果：
|
||||
|
||||
1. 输入名称、地址、端口、用户名和认证方式。
|
||||
2. 在发送认证材料前读取并确认 Host Key。
|
||||
3. 完成 SSH 认证以及平台、架构、Shell、Home 有界探针。
|
||||
4. 原子保存 Host、加密凭据和完整 Host Key。
|
||||
5. 读取 Host 已安装的 Agent/Runtime registry，并执行一次轻量下载能力探测。
|
||||
6. 如果已安装 identity 满足当前 GoodBuddy 要求，显示“版本匹配”并结束；该 badge 不代表
|
||||
Agent 正在运行或环境健康。
|
||||
7. 如果组件缺失或需要更新，显示目标 Agent、Node、Runtime、架构、来源和完整包大小，
|
||||
告知用户保存后前往 Host 卡片安装，然后结束新增向导。
|
||||
|
||||
新增流程到此结束，不显示自动安装开关，也不自动开始环境安装。保存后的 Host 卡片提供
|
||||
一个手动准备主按钮，并以次级 SegmentedControl 选择“自动”“Host 下载”或
|
||||
“GoodBuddy 传输”。主按钮按版本事实显示“安装远程环境”“更新远程环境”或“重新安装”。
|
||||
本地尚无精确包不要求用户先离开当前页面；选择 GoodBuddy 传输时，同一次操作会取得并
|
||||
验证候选后继续上传。
|
||||
|
||||
探测不得自动下载完整 `.gbagent`。只有用户明确启动安装后才允许传输大包。
|
||||
|
||||
## Host 编辑
|
||||
|
||||
- 仅修改显示名称不要求重装远端环境。
|
||||
- 地址、端口、用户名或 Host Key 变化时，旧 Host identity 立即失效，关闭旧连接和对应
|
||||
Runtime 缓存。项目记录不含旧组件 identity；下一次打开直接解析新 Host 的当前环境。
|
||||
保存新身份后只重新执行环境探测，所需安装由用户在 Host 卡片手动启动。
|
||||
- 只替换同一目标的认证材料时仍重新认证并读取实际环境；如果签名 identity 和健康状态
|
||||
未变化，不重复安装。
|
||||
- 当前项目引用的 Host 被编辑时，Main 立即失效该 Host 的 identity 和连接缓存；下一次
|
||||
Workspace/Runtime 操作按需使用新目标。环境未准备好时该操作失败，不回退旧连接。
|
||||
|
||||
## 下载能力探测
|
||||
|
||||
探测在 Host Key 已固定且 SSH 认证成功后执行，只检查当前选择的“关于与更新”来源：
|
||||
|
||||
- Host 是受支持的 Linux `x64` 或 `arm64`。
|
||||
- SSH 账号 Home 可写，GoodBuddy-owned staging 可创建。
|
||||
- 可用空间满足签名目录声明的包大小、解包上限和安全余量。
|
||||
- Host 可以通过 HTTPS 访问所选 GitHub 或北京镜像 URL。
|
||||
- 首次安装所需的下载、SHA-256 和运行归档内固定 Node 的能力可用。
|
||||
- 已安装 Agent 是否报告未来的直连更新能力。
|
||||
|
||||
探测使用小型签名目录或有界请求，不以一次成功 `HEAD` 代替真实安装验证。结果只用于当次
|
||||
展示，不持久化为永久能力；开始安装前重新检查，因为网络、代理和磁盘状态可能变化。
|
||||
|
||||
探测失败不能阻止保存 Host，也不能禁用显式 GoodBuddy 传输或离线导入路径。显式选择
|
||||
Host 下载时由实际操作报告不可用原因；“自动”只把“直连明确可用”作为选择 Host 下载的
|
||||
条件，其他结果选择 GoodBuddy 传输。
|
||||
|
||||
## 工件选择与来源
|
||||
|
||||
Main 继续读取并验证 `agent-catalog.json`、`agent-catalog.sig` 和 production 公钥
|
||||
registry，按以下条件选择唯一候选：
|
||||
|
||||
- Host 平台和架构匹配；
|
||||
- 最低桌面版本满足；
|
||||
- Agent protocol major 相同，minor 不高于桌面支持值；
|
||||
- 使用满足条件的最高 SemVer；
|
||||
- URL、文件名、大小和 SHA-256 来自签名目录；
|
||||
- 下载来源跟随“关于与更新”的 GitHub/镜像选择。
|
||||
|
||||
远程下载只优化大包的网络路径。Main 仍需先取得并验证小型目录，再通过经过 Host Key
|
||||
验证的 SSH 控制面传递固定候选元数据。产品不接受 Renderer、项目、Host 文件或用户输入的
|
||||
任意下载 URL。
|
||||
|
||||
## 获取与统一安装事务
|
||||
|
||||
首次安装不能假设 Host 已有 GoodBuddy Agent、installer 或系统 Node，也不由既有 Agent
|
||||
daemon 参与。两种 acquisition 的差别只在于如何把同一个签名 compound `.gbagent` 交付到
|
||||
固定 operation staging：
|
||||
|
||||
- **Host 下载**：控制面通过固定 SSH prepare channel 发送签名目录绑定的 URL、大小和
|
||||
SHA-256；Host 有界下载并校验完整归档。
|
||||
- **GoodBuddy 传输**：显式选择时，在线目录不可用或本地已验证包版本不低于在线候选，
|
||||
则优先使用本地包，包括版本更高的离线导入；线上存在更新且可用时仍取得线上新包。
|
||||
需要下载时，同一次用户操作会验证 SHA-256 和签名、写入缓存并取得 lease。随后以有界
|
||||
流式 SFTP 上传一个 compound archive，以及从该归档中已验证的 bootstrap Node。约
|
||||
294 MiB 的完整包不会一次读入 Main `Buffer`，Host 收到后仍再次校验完整包。
|
||||
|
||||
交付后两种 acquisition 完全共用一个 control-plane 事务：
|
||||
|
||||
1. Main 创建带 operation ID、总时限、输出上限和取消信号的准备操作，并通过固定
|
||||
`prepare` channel 发送有界 one-shot installer 与结构化输入。
|
||||
2. Host 在解包写入准备目录的同一遍处理中校验归档大小、SHA-256、外层及内层签名、
|
||||
平台、架构、协议和每个 payload digest；不再先完整扫描 payload、再重复解包和哈希。
|
||||
3. `commit` 只复核有界的签名 manifest、准备回执和入口 metadata，再以目录 rename 发布
|
||||
已准备内容及包内认证的公钥 registry/Runtime lock；不会重读归档或遍历 payload。
|
||||
4. commit 后在同一条已固定身份的 SSH lease 上执行 Agent bootstrap/readiness 和 Runtime
|
||||
activate。新 Agent 最多完整验证一次，新 Runtime 最多完整验证一次；注册成功后的
|
||||
health、capabilities 和 prompt 启动只读取 registry、签名 manifest 与入口 metadata。
|
||||
5. Main 确认 adoption 后显式执行 cleanup。cleanup 失败不回滚已经健康的 Agent/Runtime，
|
||||
也不阻塞下一次更新。
|
||||
|
||||
这不是两个并行安装管理器，也不存在把 Agent 与 Runtime payload 逐文件走 SFTP 安装的
|
||||
第二条路径。两种 acquisition 共享相同的 prepare、commit、adoption、finalize 与 cleanup。
|
||||
|
||||
Host 缺少可靠的下载、SHA-256 或 ZIP 能力时，不自动安装系统软件，也不要求 root。显式
|
||||
Host 下载返回明确失败；本次操作不自动切换 acquisition，用户可改选 GoodBuddy 传输后
|
||||
重新点击主按钮。后续更新和同版本重装复用同一事务，不要求用户先通过项目切换完成
|
||||
“过渡升级”。
|
||||
|
||||
## 本机传输与离线路径
|
||||
|
||||
现有 `.gbagent` 本地缓存、在线下载、离线导入和导出继续保留：
|
||||
|
||||
- GoodBuddy 路径在本地缺少精确候选时，于同一次操作完成下载、整包大小与 SHA-256、
|
||||
全部签名和 payload 验证、缓存发布及 lease 获取。
|
||||
- SFTP 有界流式上传单个 compound archive 与其中已验证的 bootstrap Node 到操作自己的
|
||||
staging；Main 不把完整归档读入内存，Host 再次校验后进入统一 control-plane 事务。
|
||||
- Host 无公网、代理/TLS 异常或缺少 bootstrap 工具时，用户可显式使用此路径；离线导入
|
||||
后也走同一缓存 lease、上传和 Host 校验流程。
|
||||
- 本地项目和普通桌面打包不依赖任何远端 Agent 工件。
|
||||
|
||||
## 完整包与发布
|
||||
|
||||
第一阶段继续发布和下载完整复合 `.gbagent`，不同时引入组件化增量发布：
|
||||
|
||||
- 远程直连和 GoodBuddy 本机下载都会传输完整包，其中包含 Agent、固定 Node 和 OpenCode
|
||||
Runtime。
|
||||
- 每次显式安装或重装都从本次已经校验并解包的准备目录原子替换对应 Agent 与 Runtime
|
||||
digest 目录，不为节省本机磁盘写入而重新遍历旧目录，也不使用跨安装硬链接。
|
||||
- 操作中断后不续写旧 operation。下一次更新尽力清理其 staging，并从签名候选重新
|
||||
prepare；正常 cleanup 随后删除本次准备目录。
|
||||
|
||||
只有真实包体和发布频率证明网络成本仍不可接受时，才另行设计 Agent、Node 和 Runtime
|
||||
独立签名组件目录；本功能不提前引入第二套发布协议。
|
||||
|
||||
## Host 准备状态
|
||||
|
||||
设置中的 Host 卡片分开表达版本事实和操作结果：
|
||||
|
||||
- **未验证**：Host Key、认证或系统探针尚未完成。
|
||||
- **尚未安装**：Host 可连接，但 Agent 或 Runtime 缺失。
|
||||
- **需要更新**：已安装 identity 与当前兼容候选不一致。
|
||||
- **正在准备**：正在探测、下载、验签、安装或健康检查。
|
||||
- **版本匹配**：版本 badge 只表示 Agent/Runtime identity 与当前兼容候选匹配，不等同于
|
||||
进程正在运行或环境健康；设置页普通刷新不会启动已停止的 Agent。
|
||||
- **准备失败**：保留 Host 和可用旧组件，展示有界错误与重试入口。
|
||||
|
||||
主按钮按版本事实显示“安装远程环境”“更新远程环境”或“重新安装”。重新安装失败后，
|
||||
界面显示本次操作未完成，并以随后重新检查的版本卡片表达当前事实，不在提交结果不确定时
|
||||
断言旧版本未被替换，也不得把“版本匹配”改称“环境健康”。统一进度以 `探测`、
|
||||
`下载/传输`、`校验`、`应用环境`、`Agent 激活与健康检查`、`Runtime 激活` 和
|
||||
`完成设置` 表达用户可理解的阶段。
|
||||
|
||||
同一 Host identity 同时只允许一个由用户启动、Main-owned 的准备操作。重复观察者加入
|
||||
已有操作，不启动第二次发布；窗口关闭、显式取消、Host identity 改变或 Main 退出时执行
|
||||
有界取消。Main 只为该 Host 持久化一个不含凭据的 version-1 pending operation ID，用于
|
||||
下一次操作开始时尽力清理旧 staging。无论旧 cleanup 成功、目标已变化还是旧记录损坏，
|
||||
都删除这条可丢弃记录并开始 fresh prepare；不保存远端 metadata 副本，不续写旧 commit，
|
||||
也不跨重启恢复 adoption。当前操作中可确定的失败会立即尽力 cleanup。环境已健康后的
|
||||
cleanup 失败不回滚环境，也不阻塞下一次更新。
|
||||
|
||||
## 项目创建与切换
|
||||
|
||||
- 新建托管 SSH 项目弹窗只读取本地 Host Key/连接验证记录，不逐台连接或刷新版本。只有
|
||||
已完成本地验证的 Host 可选；浏览目录或保存时才连接所选 Host，并由保存流程完整检查
|
||||
Agent、Workspace 和 Runtime，但不隐式安装。
|
||||
- 项目保存验证 Host 当前 revision 与 Host Key generation、当前 Agent、Workspace、
|
||||
Runtime、模型 profile 和 Ask/Execute 配置；SQLite 事务只写入 Host ID、规范远端路径、
|
||||
Runtime 选择和默认工作模式。
|
||||
- 打开或切换已有项目只提交本地项目选择，不执行 SSH、registry、Workspace 或 Runtime
|
||||
检查。首次实际使用远程 Workspace 或 Runtime 时才解析 Host 管理的当前 Agent/Runtime，
|
||||
并建立或复用当前 Agent 连接。已安装 Agent 暂未运行时，
|
||||
固定 `attach-or-bootstrap` 命令幂等启动 registry 中的 current identity；这里的
|
||||
bootstrap 只启动进程，不安装组件，也不重新读取、哈希或验签完整 payload。
|
||||
Agent 进程读取 Host 管理已提交的 registry 和匹配 manifest 元数据，不重新验签或扫描
|
||||
完整安装 payload。
|
||||
- Workspace 和 Runtime 使用当前 Agent 连接产生的 live handle/lease。项目不保存或核对
|
||||
历史 Workspace/Runtime identity；当前 registry、连接状态或 capability 无效时停止并
|
||||
引导到 Host 管理，不在项目流程中下载或安装。
|
||||
- 桌面更新导致 Host 组件过旧时，项目保持未切换并提示前往 Host 设置。应用启动仍进入
|
||||
第一个普通本地项目，不自动连接或更新远端 Host。
|
||||
- Host 环境更新成功后，Main 定向失效该 Host 的 Agent/Runtime identity、连接和 Runtime
|
||||
会话缓存。所有项目在下一次实际操作时自然使用新的 current 环境；无需改写项目记录。
|
||||
- 环境准备失败时不改变已有项目绑定。Host identity 编辑失败时则继续保持 fail-closed，
|
||||
因为旧身份不能替代用户刚保存的新身份。
|
||||
- 项目管理入口与项目选择分离。项目选择器中的浮动管理按钮直接打开目标项目设置；删除
|
||||
不访问 Workspace、Agent 或 Host，因此远端目录已删除或 Host 不可达都不能阻止本地
|
||||
项目记录清理。删除当前项目或 Host 级联删除当前项目时只回退到普通本地项目。
|
||||
- 项目选择器把托管 SSH 项目按已保存 Host 分组，并只读取 Main 当前持有的 Agent 连接
|
||||
状态显示“未连接 / 连接中 / 就绪 / 异常”；打开菜单或读取状态不得隐式连接 Host。
|
||||
Host 已承担类型与连接语义，项目副标题只显示远端工作目录。
|
||||
- Host 删除确认使用本地数据库列出全部引用项目，包括归档项目；确认后级联删除本地项目
|
||||
及其会话、任务、成果、记忆、计划和心跳关联，再删除本地 Host 与凭据。整个流程不发起
|
||||
SSH，也不删除远端内容；跨 Host 设置文件与 SQLite 的普通失败会恢复已写入的一侧。
|
||||
|
||||
项目切换不展示远程激活进度，也不阻塞项目导航。`Host`、`Agent`、`Workspace`、`Runtime`
|
||||
和 `Saving` 进度只属于新建或显式保存项目；实际 Workspace/Runtime 操作使用正常的局部
|
||||
加载和错误反馈。
|
||||
|
||||
## 实现结构
|
||||
|
||||
当前实现复用现有机制，没有新增平行的安装管理器：
|
||||
|
||||
- 扩展当前 Host 系统探针和远程环境 inspector，返回瞬时下载准备能力。
|
||||
- 让当前 `RemoteEnvironmentUpdateService` 演进为 Host 环境准备编排器，统一用户手动
|
||||
启动的首次安装和后续更新、自动 acquisition 选择、进度、取消和最终失效。
|
||||
- Host 环境准备编排器直接完成一次 package prepare/commit 及 Agent/Runtime adoption。
|
||||
Workspace 和执行路径只读取 current registry 并调用 Host 侧轻量 identity/health 检查，
|
||||
在当前进程内复用已确认 identity 和 Agent 连接；Host 编辑或环境更新定向清空这些缓存。
|
||||
这些路径不会取得安装包、发布组件或通过 SFTP 扫描 payload。
|
||||
- Host 卡片即使显示相同版本也保留显式重装操作，用于修复 registry、签名或 payload
|
||||
identity 异常；若同一 digest 的 GoodBuddy-owned 目录校验失败，重装会先隔离旧目录，
|
||||
并在原子 commit 失败时恢复旧目录。commit 成功后的 adoption 失败保留新发布内容，
|
||||
下次重装清理旧暂存并重新 prepare/adopt。重装不要求删除 Host、凭据或项目，也不会
|
||||
处理所有者异常、符号链接或非 GoodBuddy 管理路径。
|
||||
- 由桌面控制面打包有界 one-shot installer，并通过固定短命令 `exec sh -s` 和 stdin
|
||||
发送脚本及结构化输入，避免 SSH command 长度限制；既有 package format v1 归档内固定
|
||||
Node 负责解码和运行它。
|
||||
- Preload 只暴露明确的 Host 探测、准备、取消和进度方法，不暴露 URL 或任意 SSH 命令。
|
||||
- 现有 Agent/Runtime side-by-side、固定 SSH lease、Host 端一次完整验证、注册后轻量检查、
|
||||
连接失效和项目稳定配置事务继续作为唯一实现。
|
||||
|
||||
## 迁移
|
||||
|
||||
- 已保存 Host 打开设置时只显示本地记录，不自动连接或检查版本；用户点击对应 Host 的
|
||||
“刷新版本”后才执行只读状态探测。项目切换不依赖该按钮，也不建立连接。
|
||||
- 数据库升级保留远程项目、Host ID、远端路径、Runtime 选择及关联会话/任务，并删除旧的
|
||||
Agent/Runtime/Workspace/Host 验证列和 Runtime 验证表。下一次实际远程操作从 Host
|
||||
current 环境重新取得所有 live identity。
|
||||
- 如果 Host 未就绪或版本不兼容，项目仍可在本地选择，但实际远程操作失败；不再走旧的
|
||||
隐式安装。
|
||||
- 已下载或导入的本地 `.gbagent` 保持可用，不能因加入远程直连而迁移或删除。
|
||||
- pending operation 保持 version 1，只记录 Host、目标 identity 与 operation ID，用于
|
||||
尽力清理旧 staging；它不是远端环境状态或恢复日志。
|
||||
- 远程直连继续使用现有 package format version 1，不要求归档携带 installer，也不要求
|
||||
目录声明额外的 bootstrap 能力元数据。
|
||||
|
||||
## 验收标准
|
||||
|
||||
1. 新 Host 保存和探测完成后不会自动下载、上传或安装任何包，也不存在自动安装开关；
|
||||
再次进入 Host 设置不会逐台连接，只有显式“刷新版本”才探测目标 Host。
|
||||
2. Host 卡片只有一个按版本事实命名的主按钮；次级 SegmentedControl 提供默认且不持久化的
|
||||
“自动”及显式“Host 下载”“GoodBuddy 传输”。没有预装 Agent、Node 或 Runtime 的 Host
|
||||
可以完成准备；远程下载不可用时可手动改用 GoodBuddy 传输。
|
||||
3. 探测不下载完整包，失败不阻止保存 Host；非确定性探测失败不禁用直连重试，安装失败
|
||||
或取消后 Host 仍可重试。
|
||||
4. 直接下载严格匹配签名目录中的 URL、大小和 SHA-256；GoodBuddy 传输可在同一次操作中
|
||||
下载并验证缺失候选，以有界流式 SFTP 上传完整归档和已验证 bootstrap Node。Host 对
|
||||
两者完成相同的外层与内层签名、路径、架构、协议和 payload 校验。
|
||||
5. Host 对本次候选只完成一次完整 payload 校验；commit、adoption、health、capabilities
|
||||
和 prompt 启动不得再次遍历或哈希完整 Agent/Runtime，显式重装仍能用本次准备内容修复
|
||||
同 digest 的损坏目录。
|
||||
6. 创建、打开和切换项目不会产生 `.gbagent` 下载、Agent payload SFTP 上传或安装目录发布。
|
||||
7. 未就绪 Host 不能创建远程项目；已有项目仍可本地选择，但远程操作失败并引导到 Host 设置。
|
||||
8. Host 编辑或更新后，引用项目使用 Host 管理的当前连接和 current registry，不读取项目
|
||||
中的旧 Host/Agent/Runtime/Workspace identity；当前环境无效时才停止并要求在 Host 管理
|
||||
中修复。
|
||||
9. Host 地址、用户或 Host Key 在准备期间变化时停止候选发布，旧身份不会被重新启用。
|
||||
10. GitHub、北京镜像、无公网 Host、取消、应用退出、磁盘不足、损坏下载和不支持架构均有
|
||||
明确结果，且不触碰 GoodBuddy-owned 目录之外的文件。
|
||||
11. Linux x64 和 arm64 均通过 GitHub/北京镜像、取消、离线 GoodBuddy 传输，以及项目使用
|
||||
Host current 环境执行 Workspace/Runtime 操作的真实 Host 测试；这些真实 Host 验收当前
|
||||
仍待完成。
|
||||
12. Host 不可达或远端目录不存在时，用户仍可从项目浮动管理入口删除本地项目；删除 Host
|
||||
会列出并本地清理全部关联项目，但不会连接 Host 或删除任何远端目录和内容。
|
||||
13. 中断或 adoption 失败后的下一次更新只尽力清理旧 staging，然后 fresh prepare；
|
||||
pending record 不包含远端 metadata 副本。已健康环境的 cleanup 失败不触发回滚，
|
||||
也不阻塞下一次更新。
|
||||
@@ -0,0 +1,502 @@
|
||||
# SSH 远程主机与 GoodBuddy Agent 实现说明
|
||||
|
||||
## 状态
|
||||
|
||||
本文记录截至 2026-08-31 的当前代码实现，不定义额外的信任框架。“新增 Host 只探测、Host 卡片手动准备
|
||||
Agent/Runtime、Host 直接从 GitHub/北京镜像下载、项目始终使用 Host current 环境”已经完成源码接线，
|
||||
详细事务与验收边界见
|
||||
[SSH Host 远程环境准备与直连下载设计](./environment-provisioning-technical-design.md)；
|
||||
控制面直连源码可直接使用既有 package format v1 包，不等待携带 installer 的新 Agent
|
||||
包，也不通过额外目录元数据判断 bootstrap 能力；公开能力仍等待 GitHub/北京镜像、
|
||||
Linux x64/arm64、取消和离线 GoodBuddy 传输的真实 Host 验收。
|
||||
Windows 到 Linux x64 的安装、Agent-owned Prompt、Agent 本地模型 gateway、断线恢复、
|
||||
同一 OpenCode Session 续接、取消和终态清理已经使用真实模型与工具验证。Agent
|
||||
`0.11.10` 已通过独立 workflow 发布 Linux x64/arm64 复合包和签名累计目录；当前未发布
|
||||
Agent 源码 lock 为 `0.11.14`，桌面版本仍保持已发布的 `0.11.13`，等待发布审批后再选择
|
||||
新版本。现有源码显示本地与远端 OpenCode 原生 Task，并取消 GoodBuddy 对生产 Prompt 的
|
||||
固定墙钟总时限。失败的 `agent-v0.11.3` 保持不可变且未发布。
|
||||
|
||||
## 产品语义
|
||||
|
||||
远程 Host 与项目能力是默认关闭的技术预览。用户在“设置 > 平台功能”的独立
|
||||
“远程项目（技术预览）”页签启用开关后，Renderer 才显示 SSH Host 管理、托管 SSH 项目创建和已保存
|
||||
远程项目；Main 在 IPC 边界执行同一开关校验，避免隐藏界面被绕过。关闭开关不删除 Host、
|
||||
项目或凭据；当前远程项目切回第一个普通本地项目。应用启动仍固定
|
||||
选择普通本地项目，不会因为保存了远程项目而自动连接 Host。
|
||||
|
||||
远程项目只有两种工作模式：
|
||||
|
||||
- **Ask**：Runtime 在操作系统边界以只读方式访问项目 Workspace。
|
||||
- **Execute**：用户已授权使用所选 SSH 账号的完整权限。Runtime 可以使用该账号可访问的文件、进程、网络和工具，不再要求额外 trust tier、consent checklist、逐工具审批或“受控执行”授权。
|
||||
|
||||
Execute 不获得 root 或 SSH 账号本身没有的权限。托管 SSH Prompt 会把当前选中的文本模型
|
||||
profile 和凭据作为有界、逐 Prompt 的控制消息交给 Agent；该凭据不进入命令参数、环境变量、
|
||||
语义日志或模型调用账本，并在 Prompt 终态清除。此行为只适用于用户已明确启用的可信组织
|
||||
网络和已认证 SSH Host。
|
||||
|
||||
## 组件
|
||||
|
||||
```text
|
||||
Renderer
|
||||
-> 窄 Preload / Main IPC
|
||||
Main
|
||||
-> SSH Host 与 Host Key 管理
|
||||
-> SSH connection pool
|
||||
-> 签名 Agent / Runtime 安装
|
||||
-> 远程项目当前环境准备与稳定配置 SQLite 事务
|
||||
-> 永久项目、对话、Task 与已同步事件 SQLite
|
||||
SSH attach
|
||||
-> 远端私有 Unix socket
|
||||
Detached GoodBuddy Agent
|
||||
-> Workspace / Git 协议
|
||||
-> Agent-owned OpenCode ACP Prompt Promise
|
||||
-> Prompt-scoped Provider gateway / model-call ledger
|
||||
-> 有界语义 transcript / page / ACK
|
||||
-> 有界私有诊断记录
|
||||
-> 直接拥有的 Runtime 进程
|
||||
```
|
||||
|
||||
不提供把远端路径交给本机 Runtime 的伪本地模式，也不提供 SSH stdio Runtime fallback。
|
||||
|
||||
## SSH Host
|
||||
|
||||
- Renderer 只管理脱敏 Host 快照，不接触密码、密文、SSH Client 或任意命令接口。
|
||||
- Main 在认证前取得 Host Key，展示算法与 SHA-256 指纹，并保存完整 key blob。
|
||||
- 首次连接需要用户确认。Host Key 变化展示旧/新值并要求显式替换。
|
||||
- 密码使用 Electron `safeStorage`；系统 SSH Agent 认证不启用 Agent forwarding。
|
||||
- Host 地址、用户或 Host Key generation 变化时关闭旧连接，并定向退役依赖旧 Host identity 的 Workspace 和 Runtime 会话。下一次选择使用 Host 管理的当前连接记录解析 current Agent/Runtime，不读取项目中的旧 revision 或组件 identity；当前 registry、连接或 capability 无效时才要求显式修复。
|
||||
|
||||
## Agent 安装与生命周期
|
||||
|
||||
- Agent bundle 通过 manifest、Ed25519 签名、payload digest、平台和架构校验。
|
||||
- 安装使用当前 SSH 用户目录中的 GoodBuddy-owned 路径和 side-by-side digest 目录。
|
||||
- Agent 代码与固定 Node Runtime 一起位于签名 compound payload。显式安装或重装从本次
|
||||
已完整校验的准备目录原子发布整个 Agent，不扫描旧安装、不创建跨版本 Node 硬链接；
|
||||
Agent 不匹配不会阻止升级，也不会覆盖 GoodBuddy-owned 路径以外的内容。
|
||||
- 桌面包只携带版本 lock 与 production 公钥，不携带远端 payload。Host 卡片只有一个按
|
||||
版本事实显示“安装远程环境”“更新远程环境”或“重新安装”的主按钮；次级
|
||||
SegmentedControl 选择“自动”“Host 下载”或“GoodBuddy 传输”，默认“自动”且不持久化。
|
||||
每个复合包绑定 Agent、固定 Node 与桌面维护的 OpenCode Runtime 精确工件。添加或重新
|
||||
验证 Host 只保存并探测，不自动传输完整包。
|
||||
- Host 管理独占 Agent/Runtime 的包准备、更新和完整 payload 验证。已有项目的打开和切换
|
||||
只更新本地项目选择。Workspace 和执行路径按需读取 Host current registry，
|
||||
执行固定 `attach-or-bootstrap` 并复用当前 Agent 连接；同一进程内复用已确认 identity。
|
||||
它们不取得安装包、不发布组件，也不通过 SFTP 重读或哈希 payload。
|
||||
- Agent 的固定 attach/按需启动命令只读取 Host 管理已提交的 installation registry 和
|
||||
与其 digest 匹配的有界 manifest 元数据，不在每次项目切换时重新验签或哈希完整 payload。
|
||||
完整验签、payload 扫描和 registry 写入仍只发生在显式 Host 准备/更新流程。
|
||||
- 项目切换不执行远程核对，立即选择本地项目配置。Workspace 或 Runtime 首次实际使用时
|
||||
才通过当前 Agent 连接核对所需能力；失败只影响该操作。新建或显式保存项目仍执行完整
|
||||
准备，并只事务写入 Host、路径、Runtime 选择和工作模式。
|
||||
- SSH 连接先尝试 attach；Agent 不存在或未运行时执行幂等 bootstrap，然后重新 attach。
|
||||
- Agent 是按需启动的 detached process，不注册开机服务，不依赖 systemd、D-Bus 或 Linger。
|
||||
- 每个模型桥 helper 都为 loopback HTTP 入口生成一次性随机路径 capability；只有写入当前 OpenCode 子进程配置的 URL 可以访问该入口，其他本机用户即使发现临时端口也不能提交模型请求。
|
||||
- Agent 监听当前用户拥有的私有 Unix socket。SSH 中断只关闭 relay，不拥有 Agent 和活动 Runtime 的生命周期。
|
||||
- SSH Host 设置通过固定探针和有界 SFTP 显示 Host 已登记的 Agent/OpenCode 版本，并与当前
|
||||
GoodBuddy 所需版本比较。进入或切回该设置页只读取本地 Host 列表，不连接任何 Host；
|
||||
用户点击“刷新版本”后才探测对应 Host，探测不安装或切换远端组件。项目切换与此按钮
|
||||
解耦且不建立连接；实际远程操作才建立或复用 SSH/Agent 连接。
|
||||
- “平台功能 > 远程项目”中的本地 Agent 包清单与 Host 状态分离。Main 对用户数据目录中
|
||||
Linux x64/arm64 `.gbagent` 分别执行外层可信签名、桌面/协议兼容性、内部 Agent/Runtime
|
||||
签名、架构与完整 payload 校验；首次打开和手动刷新还会读取“关于与更新”所选来源的
|
||||
小型签名目录。Renderer 只得到本地/在线版本、是否有更新、架构、远端 Runtime 版本、
|
||||
协议和本地状态，不得到缓存路径、key ID 或 digest。目录检查不下载 `.gbagent`，在线
|
||||
包下载只由用户点击带目标版本的操作触发；离线导入/导出通过 Main 管理的文件对话框完成。
|
||||
- “自动”只在 operation/prepare 前用 Host capability probe 选择 acquisition：直连明确
|
||||
可用才选 Host 下载，否则选 GoodBuddy 传输；显式选择不被改写。prepare、commit 或
|
||||
adoption 失败后都不跨 acquisition 自动 fallback。
|
||||
- Host 下载由桌面控制面通过固定 SSH prepare channel 和结构化 stdin 发送候选信息，
|
||||
Host 取得 compound `.gbagent` 并核对大小与 SHA-256。显式 GoodBuddy 传输在在线目录
|
||||
不可用，或本地已验证包版本不低于在线候选时优先租用本地包，包括更高版本离线导入；
|
||||
线上存在更新且可用时仍取得线上新包。需要下载时，同一次操作会验 SHA-256 与签名、
|
||||
缓存并取得 lease，再以有界流式 SFTP 上传一个 compound archive 和归档中已验证的
|
||||
bootstrap Node；约 294 MiB 完整包不会一次读入 Main `Buffer`，Host 仍再次校验完整包。
|
||||
- 两种 acquisition 交付到固定 operation staging 后，完全共用 control-plane
|
||||
`prepare → commit → Agent activate/health → Runtime activate → finalize → cleanup`。
|
||||
Main 只保存清理 operation staging 所需的 operation ID。中断或 adoption 失败后，下次
|
||||
更新尽力清理旧暂存并重新 prepare，不保存或恢复 Agent/Runtime metadata 副本。确认
|
||||
adoption 后才显式 cleanup；cleanup 失败不回滚健康环境，也不阻塞下一次 fresh prepare。
|
||||
Host 在 prepare 解包时
|
||||
完成一次完整 payload 校验，commit 和后续注册检查不再遍历包体。首次 bootstrap 不依赖
|
||||
既有 Agent daemon，也不要求 format v1 归档携带 `agent/lib/package-installer.cjs`。
|
||||
- 即使版本号均为当前版本，Host 卡片仍提供同版本“重新安装”，用于修复 registry、签名
|
||||
或安装 identity 异常。GoodBuddy-owned 同 digest 目录损坏时先隔离后替换，并在发布或
|
||||
原子 commit 失败时恢复；commit 成功后的激活失败保留新发布内容，下次点击重新安装时
|
||||
清理旧暂存并重新 prepare/adopt。不要求删除 Host、凭据或引用项目。
|
||||
- Host 卡片的“版本匹配”badge 只表达版本事实，不代表 Agent 正在运行或环境健康。重新安装
|
||||
失败时明确显示本次操作未完成，并以随后重新检查的版本卡片表达当前事实；提交结果
|
||||
不确定时不声称旧版本未被替换。
|
||||
- 更新成功后才定向清理该 Host 的 Agent 连接和 Runtime 选择缓存。引用项目再次打开时
|
||||
解析新的 current registry 并建立当前连接，无需刷新项目记录；当前环境无效时要求用户
|
||||
显式修复，但不在项目切换中下载或安装。失败或取消保留 Host 配置、凭据、项目、
|
||||
Workspace 和旧组件。
|
||||
- 显式 stop、升级、身份冲突或进程退出时清理 GoodBuddy 自己的 socket、状态和子进程；不得删除或覆盖无关 Host 文件。
|
||||
|
||||
### Host 级环境生命周期
|
||||
|
||||
- Agent、Node 和 Runtime 是 Host/SSH 账号级共享环境。新增或重新验证 Host 后先保存 Host
|
||||
并只读探测，不自动安装；用户随后在 Host 卡片明确选择安装或更新方式，失败保留 Host
|
||||
并允许重试。
|
||||
- Host 可以按签名目录固定的 URL、大小和 SHA-256 直接从当前 GitHub/北京镜像来源下载
|
||||
完整 `.gbagent`，也可使用 GoodBuddy 本机下载、流式 SFTP 传输和离线导入。自动模式只在
|
||||
操作开始时择一；执行失败不会在同一次操作中切换 acquisition。
|
||||
- 项目只保存 Host ID、远端路径、Runtime 选择和默认模式。创建或保存时验证 Host current
|
||||
环境；打开或切换只读取本地配置。Workspace/Runtime 实际使用时从 Host current registry
|
||||
和当前 Agent 连接取得 live identity，不再扫描、下载、上传或发布 Agent/Runtime。完整
|
||||
事务、兼容边界和验收要求以
|
||||
[Host 环境准备设计](./environment-provisioning-technical-design.md) 为准。
|
||||
- 打开新建/项目设置弹窗只读取本地 Host 验证记录，不并发检查所有 Host；目录浏览或保存
|
||||
才连接所选 Host。
|
||||
- 项目选择器中的管理操作默认浮动隐藏，在悬停、键盘焦点或触屏环境显示。管理任意已保存
|
||||
项目不先激活项目，因此 Host 不可达或远端目录已不存在时仍可删除其本地记录。
|
||||
- “远程项目”在选择器中按已保存 SSH Host 轻量分组。Host 标题显示 Main 已持有的真实
|
||||
Agent 连接状态（未连接、连接中、就绪或异常），读取和展示状态本身不连接 Host；
|
||||
项目副标题只显示远端路径，不重复“托管 SSH”类型。
|
||||
- 删除 Host 时确认框列出所有引用它的本地项目记录，包括归档项目。确认后只删除本机
|
||||
Host、凭据、项目及其关联记录，不连接 Host、不删除远端目录或内容；Host 设置写入或
|
||||
项目事务失败时恢复另一侧，避免只删掉其中一类本地记录。
|
||||
|
||||
## Workspace
|
||||
|
||||
Main 传入已规范化的绝对 POSIX root。Agent 返回 Workspace identity、访问模式、Git 状态和有界能力。
|
||||
|
||||
- 创建项目时，用户可以直接输入远端工作目录，或通过输入框右侧的文件夹按钮浏览并选择目录。
|
||||
- 项目保存前的目录浏览使用 Main 管理的只读、有界 SFTP，只返回目录；每次请求重新解析并校验当前 Host revision 与 Host Key generation，不安装 Agent、不暴露任意 shell/SFTP 接口。
|
||||
- 浏览从 SSH 账号 Home 或当前有效绝对路径开始，限制扫描次数、返回条目和总时限；取消、Host 变化、超时或连接失败时关闭 SFTP 并保留用户原先输入。
|
||||
- 选择目录只更新项目草稿，仍需通过正常的 Agent、Workspace、Runtime 验证和项目保存事务才会持久化。
|
||||
- Ask Workspace handle 不暴露写入方法。
|
||||
- Execute Workspace handle 可读写，但这不是 Execute 的唯一权限面；Execute Runtime 本身使用 SSH 账号的正常权限。
|
||||
- 文件预览、搜索、Git diff、目录项和显式文件传输保持字节、条目数和路径长度上限。
|
||||
|
||||
## Runtime
|
||||
|
||||
首个远程 Runtime 固定为签名 OpenCode ACP bundle。
|
||||
托管 SSH 项目的 Composer Runtime 菜单只显示当前配置的 OpenCode 和管理入口，不显示
|
||||
直连模型、Continue 或 DeepSeek Harness。激活旧远程会话时，若其保存了其他 Runtime
|
||||
selection，Renderer 会恢复为当前 OpenCode 配置；Main 的远程请求校验仍是最终边界。
|
||||
本机配置的 SKILL 包和 stdio MCP Server 不上传或分配给远程 Runtime；远程 ACP Session
|
||||
继续使用空 MCP Server 列表。Node.js、Python 等本机工具环境同样不修改或同步到 Host，
|
||||
完整边界见[本机工具环境](../local-tool-environment/README.md)。
|
||||
|
||||
### Ask
|
||||
|
||||
Ask 使用系统 `bwrap`：
|
||||
|
||||
- Workspace 和 Runtime bundle 只读 bind；
|
||||
- 独立可写 scratch HOME、TMPDIR 和 XDG 目录；
|
||||
- 固定环境名和固定 Runtime argv；
|
||||
- 通过只读边界阻止 Workspace 修改。
|
||||
- ACP 权限请求只有在工具种类为原生 `read` 且 Runtime 提供 `allow_once` 选项时才允许；
|
||||
search、edit、execute、未知工具以及只提供持久授权的请求全部拒绝。
|
||||
|
||||
`allow_once` 只解决 OpenCode 发起原生读取前的 ACP 协商，真正的文件系统边界仍是只读
|
||||
`bwrap` bind。Host 缺少 `bwrap` 时 Ask 不可用。
|
||||
|
||||
### Execute
|
||||
|
||||
Execute 不经过 Ask 的 bubblewrap profile：
|
||||
|
||||
- 直接启动已签名 Runtime entrypoint；
|
||||
- 使用 Agent 本地模型 gateway 时，签名 Agent launcher 会 `exec` 候选 manifest 锁定的
|
||||
Node Runtime；进程 owner 校验最终 Node executable，而不是已经被替换的 shell
|
||||
launcher 路径；
|
||||
- `cwd` 为项目 Workspace；
|
||||
- 继承 SSH 账号的正常环境、文件系统、进程和网络能力；
|
||||
- 不进行 T2/T3、confinement attestation、approval bridge 或逐工具批准。
|
||||
|
||||
两种模式都保留输入/输出字节上限、用户取消和进程组清理。生产 Prompt 不设置固定墙钟
|
||||
总时限；只要 Runtime 尚未按自身协议结束，Main 和 Agent 就允许其持续运行。启动、握手、
|
||||
单个控制 RPC、重连尝试和关闭清理仍使用独立的有界超时，测试可以显式注入短 Prompt
|
||||
时限验证取消升级，但该覆盖值不是生产默认。无界 Prompt 继续复用已发布的必填
|
||||
`deadlineAt` 字段，以 year-9999 哨兵表达；Main 与 Agent 必须同时理解该哨兵，Agent
|
||||
`0.11.10` 及更早版本仍会按其 manifest 上限夹紧，因此桌面启用这一语义前必须配套更新
|
||||
到 Agent `0.11.13` 或更高版本。
|
||||
|
||||
## ACP 与断线
|
||||
|
||||
- 管控面只负责有界 JSON-RPC：连接、查询、启动、取消、关闭和重连。数据面只负责
|
||||
ACP/blob 数据与 Agent 本机 journal。二者共享同一个经过 Host Key 校验和认证的
|
||||
SSH attach 字节流，但不共享生命周期：管控连接关闭不会隐式取消 Agent 已接受的
|
||||
Runtime 动作。
|
||||
- 帧只保留连接 identity、channel identity、单调 sequence、类型和长度。Main 与
|
||||
Agent 都按调用顺序 FIFO 写入，输入队列达到固定字节或条目上限时暂停 SSH stream。
|
||||
顺序、可靠传输、分包和网络背压全部交给 SSH；协议不实现 credit/window、优先级
|
||||
调度、跨 channel 超车、批发送或第二套拥塞控制。
|
||||
- Agent 在把 Main 输入交给 Runtime 前、以及把 Runtime 输出交给 Main 前，先把 ACP frame 写入本机 journal。ACK 只推进 cursor 并裁剪已确认 frame，不表示 channel 已终止。
|
||||
- Main 持久化 binding identity 和单调 cursor；保留中的 connection lease 即使处于 offline/reconnecting，也可以先把新 cursor 落盘。重连提交不能覆盖 resume 过程中并发落盘的更新。
|
||||
- Runtime 事件先经过单事件、单请求输出和每次 Prompt 最多 100 个不同工具调用的边界；
|
||||
通过边界后，Renderer 和 Main 将已接受的工具详情保存到本地 SQLite，不再额外缩短其
|
||||
输入、输出、错误或摘要。
|
||||
- OpenCode 原生 Task 工具按 `subagent_type`、`description`、`prompt` 和稳定 tool call ID
|
||||
解析为子 Agent 事件。本地 OpenCode SDK 与远端 ACP 增量工具事件复用同一转换；ACP
|
||||
首帧缺少参数时可以先显示普通工具活动，后续参数确认其为 Task 后必须替换为子 Agent
|
||||
状态卡，并持久化任务说明、终态与输出。
|
||||
- 同一 detached Agent 存活时，短暂 SSH 断线依次执行 `controller/resume`、`runtime/resumeAcpChannel` 和 `runtime/replayAcpChannel`，从 Main 已确认的 cursor 后只重放 Agent 到 Main 的已记录输出。重复 frame 会被确认但不会再次交给上层。若上一代连接只留下没有活动请求的 detached binding，完成精确 controller takeover 后会先有界停止并核对遗留 Runtime process，再用新 channel epoch 重新打开同一 binding 并恢复已有 ACP session；其他 controller、未证明 takeover 或仍有活动请求的 binding 仍被拒绝。
|
||||
- Main 到 Runtime 的 ACP 输入、模型请求、工具请求和 blob 不自动重放。
|
||||
- 无法确认外部 Provider 是否已处理的模型调用保持结果未知，避免重复计费或重复副作用。
|
||||
- 只有远端返回 identity 匹配且 `closed: true` 时，Main 才删除持久化 binding；传输失败或未确认 close 会保留 recovery identity。
|
||||
- 终态 close 由 Agent 在一个事务中为两个方向记录 sequence high-water tombstone，删除剩余 frame 和 active channel，并归零对应 journal quota。tombstone 用于拒绝迟到的旧 epoch frame，因此当前不会按时间自动裁剪。
|
||||
- 断线不主动终止正在运行的 Runtime。用户取消、显式关闭、输出边界或 Agent shutdown
|
||||
才触发停止；连接恢复只受当前用户取消信号和单次重连控制超时约束，不把 Prompt 已运行
|
||||
时长当作停止条件。
|
||||
- Agent 失联期间继续把 Runtime 输出写入本机 journal；重新连接只校验 controller
|
||||
identity、恢复 binding，并从 Main 最后确认的 cursor 后同步缺失数据。已接受的
|
||||
指令和结果不确定的 Provider 请求都不自动重放。
|
||||
|
||||
### Agent-owned Prompt 与 Desktop 恢复
|
||||
|
||||
- 托管 SSH 的生产 Prompt 从一开始就由 Agent 持有 ACP `ClientSideConnection`、原始
|
||||
Prompt Promise、Provider 轮次和 Runtime 进程。SSH relay 或 Desktop 进程不属于该
|
||||
Promise 的生命周期，因此正常退出、强制结束 Desktop 或本机网络中断后，Host 仍能继续
|
||||
后续模型/工具轮次。该路径要求 `runtime/acp` capability v4，即 Agent `0.11.14` 或更高。
|
||||
- Agent 把 ACP session update、permission decision 和唯一 Prompt 终态写入有界语义
|
||||
transcript。Main 不恢复旧 JSON-RPC Promise，也不重发 `session/prompt`；Fresh Desktop
|
||||
只对同一 controller/binding/operation 执行 takeover、attach 和 ACK-exclusive page。
|
||||
- 每个 Agent 语义 sequence 在 Main 映射为零到多个公开事件，最后追加内部 checkpoint。
|
||||
Desktop 在同一 SQLite 事务中去重 provenance、归并原 assistant message，并在 checkpoint
|
||||
时提交 Task 终态；事务成功后生成器才继续并向 Agent ACK。断电发生在同一 sequence
|
||||
中间时会重读该 sequence，已写事件按 `(binding, operation, sequence, eventIndex)` 去重，
|
||||
未写事件继续归并，不会重复 Provider 或工具执行。
|
||||
- ACK 后 Agent 删除已确认事件，只保留小型操作终态与游标用于幂等核对；未 ACK 输出继续
|
||||
保留。Main 按 transcript page 的最高连续 sequence ACK，终态仍立即 ACK。单事件、单页、
|
||||
单 Prompt 总字节和事件数都有上限；Agent 始终为唯一终态预留一个事件和最大事件字节，
|
||||
避免配额耗尽后无法记录终态或无法重启。已 ACK 终态操作和已交付模型 ledger 在 daemon
|
||||
运行期间也按固定上限裁剪，不依赖重启。Agent 重启不能重建内存中的 Runtime/Prompt
|
||||
Promise，因此启动时把遗留 nonterminal 记录变为 `outcome-unknown`，Desktop 只同步该
|
||||
终态而不自动重放。
|
||||
- prepare 已接受但 start RPC 未到达时，Agent 使用两分钟 prepare-to-start watchdog 清除
|
||||
进程和 Prompt 凭据并记录 `outcome-unknown`，避免无界 Prompt 哨兵造成永久悬挂。
|
||||
- Desktop SQLite 仍是永久可见项目/对话数据的权威；Agent transcript 只是尚未同步事件的
|
||||
权威。启动后 Renderer 先订阅恢复进度，再触发每项目恢复。项目选择器依次显示网络、
|
||||
Agent、Runtime、cursor、完成或失败/重试；只阻塞受影响项目的发送和队列，已有历史与
|
||||
其他项目保持可用。
|
||||
- 正常应用退出对已接受托管 SSH 请求执行 detach，不等待远端完成；本地请求和尚未接受的
|
||||
请求仍按原行为取消。用户显式“停止”始终发送稳定 operation cancellation，并等待 Agent
|
||||
语义终态。已进入 Agent-owned `run` 但 start/attach 响应仍不确定的请求继续保留为
|
||||
`interrupted + remote_recoverable`，并自动走 exact attach；不会因为尚未收到第一个公开
|
||||
事件而丢失恢复身份。
|
||||
|
||||
## Agent 本地模型 gateway
|
||||
|
||||
- Main 在 `runtime/preparePrompt` 中发送当前解析后的有界 profile；Agent 只在该 operation
|
||||
的内存状态中持有 Provider URL、API Key 和认证信息。OpenCode 仍通过 Prompt 私有 Unix
|
||||
socket 发出模型请求，但 HTTP Provider dispatch、响应交付和稳定 call ledger 全部位于
|
||||
Agent，因此 Desktop 断电后可以继续下一轮。
|
||||
- Agent 校验固定 model、协议和 API path，拒绝 background/store、provider web search、
|
||||
provider MCP、持久 conversation、非文本 modality 和其他可独立计费能力；请求/响应 body
|
||||
各限制 768 KiB，响应同时核对声明长度与短读。每个
|
||||
`(binding, operation, roundIndex)` 只 dispatch 一次；已 dispatch 但未证明完整交付的调用
|
||||
变为 `outcome-unknown`，不会自动重试。
|
||||
- Prompt 最多 100 个模型调用，并受单次与累计输出 Token 上限保护；这些是资源边界，不是
|
||||
Prompt 墙钟总时限。Provider 单次请求仍有独立超时。实际 usage 在语义 transcript 中同步
|
||||
回 Desktop 的 usage/task 数据。Agent 在所有进程终止路径统一清除 Prompt token 计数。
|
||||
- helper 可以接收同一 Prompt 内并发到达的模型桥请求；它在单一稳定模型桥上按到达
|
||||
顺序等待并交付，不返回本地 `bridge-busy`，每个响应只有在 HTTP 完整 flush 后才
|
||||
发送 delivery ACK。
|
||||
- GoodBuddy 自己管理会话标题，因此传给 OpenCode 的配置禁用 title Agent；一次用户
|
||||
Prompt 不会额外触发标题模型请求。
|
||||
- Agent gateway 不再把 Provider 请求往返 Desktop；legacy blob bridge 只保留给旧的
|
||||
非 Agent-owned 测试/兼容路径。凭据不进入 Renderer、SSH 命令参数或远端环境。
|
||||
- Unix socket 接收端按 `readableLength` 中已经缓冲的字节增量排空一个声明长度的帧，
|
||||
不会在部分大响应到达时反复请求尚未缓冲的完整剩余长度；短读、连接结束、错误和取消
|
||||
都会使当前交换失败。原生 Linux 回归覆盖至少 256 KiB 的 broker 响应。
|
||||
- Renderer 把相邻 text/reasoning delta 合并为消息 block 时始终替换最后一个 block，
|
||||
不修改既有 React state 对象。这样开发环境 StrictMode 重复调用 state updater 时，
|
||||
block metadata 与 canonical 消息正文保持一致。
|
||||
|
||||
## Agent 开发期间的真实 Host 验证
|
||||
|
||||
任何会改变已部署 GoodBuddy Agent 或桌面到 Agent 生产链路的源码改动，都必须在开发期间
|
||||
使用共享 Linux x64 真实测试 Host 验证。适用范围包括 Agent daemon、Agent protocol
|
||||
及共享 contract、Agent 组包与安装、attach/update、Runtime 启动与进程归属、Workspace、
|
||||
model bridge，以及生命周期和恢复逻辑。单元测试、mock、fixture、CI 或正式发布前回归
|
||||
都不能替代这一步；不得等到准备发布时才首次运行受影响的真实链路。
|
||||
|
||||
测试 Host 有两个网络入口：
|
||||
|
||||
- `192.168.0.23`：局域网入口，在本地网络可达时优先使用；
|
||||
- `10.7.0.23`：VPN 入口，局域网入口不可达时使用。
|
||||
|
||||
两者指向同一台物理 Host，只代表两条访问路由，不能计为两个独立 Host、两种架构或两份
|
||||
覆盖结果。测试只使用已固定的 Host identity 和 GoodBuddy 已有凭据存储；地址不得写入
|
||||
产品行为或默认配置，用户名、密码、私钥等凭据不得写入源码、文档、命令、日志或测试输出。
|
||||
|
||||
开发时应在改动链路达到可运行状态后尽早执行真实 Host 验证，并在最终相关改动后重复受
|
||||
影响的场景。必须使用当前源码构建或当前候选包，不能只验证 Host 上已经发布的旧 Agent。
|
||||
按改动范围至少选择以下场景：
|
||||
|
||||
1. Agent 组包、安装或升级：验证当前候选的 attach-or-bootstrap、安装/更新、版本切换及
|
||||
随后的连接。
|
||||
2. Runtime profile、进程启动/归属或 Ask/Execute 边界：通过桌面生产入口启动真实 Runtime，
|
||||
验证受影响模式；Ask 权限改动必须验证只读边界，Execute 权限改动必须验证所需写入、
|
||||
进程和网络能力。
|
||||
3. Agent protocol、RPC、stream、model bridge 或模型消息链路：执行最小有界真实模型调用，
|
||||
禁用非必要工具和附件，并记录实际调用次数；大消息或工具链路改动还应覆盖对应的真实
|
||||
payload/工具场景。
|
||||
4. 会话、owner、取消、超时、断线或恢复逻辑：执行与改动直接相关的中断、取消、Agent/
|
||||
Runtime 重启、SSH 断开或重连序列，并确认不会错误重放结果未知的操作。
|
||||
5. Workspace 或 Host 文件路径：只在 GoodBuddy 专用测试目录操作，验证真实路径和权限，
|
||||
不得读取、覆盖或删除无关 Host 文件。
|
||||
|
||||
停止或修改远端进程前必须先核对其启动身份、PID/进程组和 GoodBuddy 归属。若两个入口均
|
||||
不可达，应立即把真实 Host 验证报告为开发阻塞，保持该验证未完成，不能把 Agent 改动表述
|
||||
为已完成，也不能把首次真实验证推迟到发布阶段。
|
||||
|
||||
## 已完成的 E2E 验收记录
|
||||
|
||||
- 2026-08 的本地 fixture 完整验证 Linux x64 Agent `0.11.2-e2e.12`、Node `24.19.0`
|
||||
和 Agent protocol `2.0`；当时没有 arm64 fixture，因此该记录不能作为当前独立发布
|
||||
的双架构验收。Agent `0.11.10` 后续已由原生 workflow 发布并公开验证双架构工件；
|
||||
当前源码 lock 固定为 `0.11.14`；正式发布状态以独立 Agent Release 与签名 catalog 为准。
|
||||
- 2026-08-30 在共享 Linux x64 Host 的隔离测试 HOME 中验证当前 `0.11.13` 源码候选：
|
||||
签名 Runtime 清单的测试墙钟上限为 1 秒，模型桥首轮故意延迟 2.515 秒后 Prompt 仍在
|
||||
5.770 秒正常完成；随后 OpenCode 原生 Task 依次产生 `running`、`completed` 子 Agent
|
||||
事件并完成父请求。测试结束后隔离 Agent、Runtime、socket 和 Workspace 已全部清理，
|
||||
Host current Agent 仍为 `0.11.10`。
|
||||
- 2026-08-31 使用隔离 Linux x64 Agent `0.11.14` 候选完成 remote-authoritative 矩阵：
|
||||
15 秒短 smoke、2 分钟正常 detach、5 分钟本机 harness 强制结束、并发对话、SSH relay
|
||||
丢失、显式取消、确定性 Provider 错误、2 秒 Provider 结果未知、Agent `SIGKILL`/重启，
|
||||
以及 reopened Desktop SQLite 恢复。成功工具的 START/END sentinel 都各出现一次；
|
||||
Provider 结果未知与 Agent 重启只提交 `outcome-unknown`，未重放 Prompt、模型调用或工具。
|
||||
- 同一矩阵中的 Desktop schema v32 实际恢复保持原 project/conversation/request/
|
||||
assistant-message 身份，在同一事务中提交语义 provenance、消息与 cursor；重新打开
|
||||
`assistant.sqlite` 后消息和 Task 都完整，重复 provenance 返回 false，recoverable Task
|
||||
归零。
|
||||
- 最终源码复核后重新构建测试签名 package：
|
||||
SHA-256 `39307fd1dccd638dcb723027591bcd83deab7057d550c99eff6f037e339829f4`，
|
||||
installation `agent-2cad05acfebe853394807e3a11f7befcd9f47215c2cf3a33a03d5f644b45716e`，
|
||||
Runtime `1.18.9` / bundle
|
||||
`sha256:6c7fc975415ef2547d3729bc4772d3e78362c2e76c05d1fc24968a0468fcb7ba`。
|
||||
最终 15 秒 detach/recovery 使用两个模型轮次、一个工具和一个终态，ledger 两轮均
|
||||
`completed + delivered`，语义 `latest=ACK=41`，保留事件、Runtime owner、ACP channel/
|
||||
frame 都为 0，START/END 各一次。最终取消另使用一个模型轮次、一个工具和一个 cancelled
|
||||
终态，语义 `latest=ACK=29`，清理计数同样为 0。最终补充验证共 3 次真实文本模型调用。
|
||||
采证后已按 PID/starttime/executable 停止精确隔离 daemon 并删除隔离 Host 测试根目录；
|
||||
`/root/.goodbuddy` 下的共享 Agent 安装和进程未被修改。
|
||||
- 2026-08-31 使用当前工作树短期测试签名 Linux x64 候选，在全新隔离 HOME 和 installation
|
||||
中验证有界诊断：bootstrap、detached daemon、attach、relay 断开与同 controller 重连、
|
||||
`controller/resume`、Runtime candidate 激活和 OpenCode ACP 进程启动均通过；新
|
||||
`diagnostics --installation-id` 命令在 daemon 重启后读取到 23 条完整 JSONL。诊断目录
|
||||
为 `0700`、文件为 `0600`，单文件 3719 bytes，未超过 64 KiB。六类测试哨兵覆盖 Prompt、
|
||||
密钥、环境、SSH 参数、用户文件内容和原始错误消息，CLI 输出与磁盘均未出现哨兵。把隔离
|
||||
diagnostics 目录临时设为不可写后，Attach 和 `agent/status` 仍正常；随后已恢复权限。
|
||||
本次未注入模型凭据或执行 Prompt，真实文本模型调用 0 次；三文件轮转继续由聚焦测试覆盖。
|
||||
测试结束前按 PID、UID、starttime、executable 和唯一 installation 核对并停止所有本次
|
||||
daemon，本地及 Host 临时目录均已清理，共享 current Agent 和 `/root/.goodbuddy` 未修改。
|
||||
- 正常 Host 更新路径把 Linux x64 Host 的 Agent 更新为 `0.11.2-e2e.12`，并确认
|
||||
OpenCode Runtime 已安装版本与所需版本均为 `1.18.9`。
|
||||
- 一条新的 Ask 用户操作只提交一次。OpenCode 先在 build 模型轮次请求一个原生
|
||||
`read`，读取专用测试 Workspace 中的证据文件，再在第二个 build 模型轮次生成最终
|
||||
回答；没有 title 模型轮次，也没有第二个工具调用。
|
||||
- 两个模型轮次都记录已交付，远端 helper 保持休眠且 Unix socket 没有未读响应积压。
|
||||
持久化的 canonical 助手正文精确为 `GOODBUDDY_REMOTE_TOOL_4C6B9D8A`。验收操作没有
|
||||
重放任何结果未知或已经完成的 Provider 请求。
|
||||
|
||||
## 项目保存
|
||||
|
||||
远程项目只持久化稳定配置：
|
||||
|
||||
- Host ID；
|
||||
- 规范远端工作目录；
|
||||
- Runtime selection；
|
||||
- `ask | execute` 默认模式。
|
||||
|
||||
Agent installation、Host revision/Host Key generation、Workspace identity、Runtime
|
||||
bundle/adapter digest 和 capability generation 都属于 live connection/lease，不进入项目
|
||||
domain object 或 SQLite。打开托管 SSH 项目不接受 Renderer 回传的旧项目草稿，而是从 Host
|
||||
store 解析当前连接目标，通过 Agent/Runtime 安装管理器的 current/activate 读取路径取得
|
||||
registry identity，再用同一个 Agent 连接验证 Workspace 路径和 Runtime capability。该流程
|
||||
不会扫描完整 payload、取得安装包或发布组件。
|
||||
|
||||
实时 Runtime 创建只接受 OpenCode，使用当前解析后的模型 profile 准备 Agent 本地 gateway，
|
||||
从当前 Agent 连接和 Runtime registry 取得会话 identity，并在该连接上打开 Workspace 和
|
||||
ACP channel。Host 编辑或环境更新会定向失效 Agent 连接与 Runtime 缓存，下一次请求自然
|
||||
重新取得 current 环境；无需修改项目。Ask/Execute 权限继续由每次 Prompt 的 ACP Runtime
|
||||
边界执行。
|
||||
|
||||
Renderer 在用户主动打开已有托管 SSH 项目时立即切换，不显示远程激活状态。Host、Agent、
|
||||
Workspace、Runtime 和 Saving 进度仅用于新建或显式保存项目；进行中可显式取消并禁用会
|
||||
产生冲突的项目创建和设置入口。远端 RPC 拒绝只向
|
||||
Renderer 暴露固定方法名、数字 RPC code 和有界 service code，不转发 Host 私有错误详情。
|
||||
`runtime/preparePrompt` 在远端明确拒绝且尚未接受 Prompt 时会关闭对应 Main binding，
|
||||
不会把确定性失败错误保留为 `outcome-unknown`。未确认终态的 Prompt 仍不会自动重放；
|
||||
同一当前 Agent identity 上的 `prompt-running` binding 会阻止不同的新 operation，直到
|
||||
原 operation 恢复或取消，避免遗留 Host 工作与新 Prompt 并行。只有 Host/Agent/Runtime
|
||||
identity 已变化且旧 authority 无法恢复，或原 binding 已有 `outcome-unknown` 终态时，显式
|
||||
新 Prompt 才替换旧 binding。新 ACP session 的首次 Prompt 会把 Desktop 已持久化的有界
|
||||
会话历史作为不可信数据一并发送；成功加载或恢复原 ACP session 时不会重复注入历史。
|
||||
Ask 模式的 Linux Runtime 进程由 `bwrap` 启动后 `exec` 到已签名 Runtime 或 Agent
|
||||
model bridge helper；监督器只接受同一 PID/进程组从固定 `bwrap` 路径到预期最终可执行文件
|
||||
的有界转换，再登记为运行中进程。
|
||||
|
||||
不持久化 T2/T3、consent、approval bridge、confinement 或组件验证结果。数据库 schema
|
||||
v32 保留项目及关联用户数据，并加入 remote-recoverable Task/message/provenance/cursor；
|
||||
执行空间表保持 `project_id/kind/root_path/ssh_host_id`
|
||||
四列，并删除旧 Runtime 验证表。
|
||||
|
||||
## Agent 有界诊断
|
||||
|
||||
Detached Agent 不依赖 stdio 留存故障证据。每个 installation 在固定私有目录
|
||||
`~/.goodbuddy/state/<installationId>/diagnostics/` 中维护
|
||||
`agent-diagnostics.jsonl`、`.1` 和 `.2`，每个文件不超过 64 KiB，目录权限为 `0700`，
|
||||
文件权限为 `0600`。记录覆盖 daemon 启停、detached 启动、连接、恢复和 Runtime
|
||||
启动/退出；每条只包含固定事件、时间、PID、可选工作模式、固定原因和白名单错误码。
|
||||
|
||||
诊断写入使用最多 64 条的有界异步队列。连接、恢复和 Runtime 回调只把已经归一化的固定
|
||||
记录入队，不等待磁盘；原始 `Error` 不进入队列。队列满、目录不可写或轮转失败只丢弃诊断，
|
||||
不得改变 Attach、协议、Runtime 或退出结果。daemon 停止和 bootstrap 生命周期结束时执行
|
||||
有界 flush。多个 Agent 进程通过 GoodBuddy 私有短期锁协调 append 和轮转，不把长期锁作为
|
||||
运行前提。
|
||||
|
||||
已安装 Agent 提供只读固定命令：
|
||||
|
||||
```text
|
||||
goodbuddy-agent diagnostics --installation-id <installationId>
|
||||
```
|
||||
|
||||
该命令只能从 installation 对应的固定 state 目录读取上述有界文件，并逐行输出已验证 JSONL；
|
||||
不接受任意路径，也不扩展 Agent protocol。诊断不得包含 accepted Prompt、模型输入输出、
|
||||
模型密钥、完整配置、环境变量、SSH 参数、用户文件内容、路径或原始错误消息。应用内反馈的
|
||||
“附加最近桌面诊断记录”只读取 Desktop 诊断，不会自动取得或上传这些远端 Agent 记录。
|
||||
|
||||
## 资源与发布
|
||||
|
||||
- 所有桌面构建（包括 `portable` 与 `release:package`）只携带
|
||||
`agent-runtime-lock.json`、`remote-runtime-lock.json` 与公开的
|
||||
`agent-release-keys.json`，不嵌入 `.agent-resources`、
|
||||
`.remote-runtime-resources` 或任何可安装 Linux 远端 payload。
|
||||
- `build/agent-package.cjs` 在对应原生 Linux 架构组装确定性 `.gbagent`，外层签名覆盖
|
||||
描述符和每个内部文件身份；内部 Agent 与 Runtime 仍分别使用既有签名 manifest 和 lock
|
||||
校验，但所有 production 层统一使用一组 GoodBuddy 通用发布身份并通过签名域区分用途，
|
||||
不要求内部 Runtime 单独配置密钥。`build/agent-catalog.cjs` 为双架构包生成签名累计目录，
|
||||
拒绝同一版本/架构改变字节。
|
||||
- `.github/workflows/agents.yml` 只使用进程内临时测试 key 做分支/PR 原生验证，不发布。
|
||||
`.github/workflows/agent-release.yml` 才可在 annotated `agent-v<version>` 标签和受保护
|
||||
`agent-signing` Environment 中构建 production 包。Agent GitHub Release 必须
|
||||
`--latest=false`；北京 OSS 先写 `agent-releases/v<version>/`，GitHub 公开后才切换
|
||||
单一 `agent-releases/latest.json` 指针，使客户端始终从同一不可变版本目录读取目录与签名。
|
||||
- Main 的本地缓存只发布完整验证成功的内容。在线目录和包都绑定固定 GitHub/OSS URL、
|
||||
大小和 SHA-256；选取规则是桌面最低版本满足、Agent protocol major 相同且 minor 不高于
|
||||
当前支持值的最高 SemVer。缺少某架构仅使该架构 Host 的托管 SSH 无法激活。
|
||||
- `agent-release-keys.json` 读取时按 UTF-8 JSON 解析并严格验证 schema、唯一 key ID、
|
||||
规范 Base64、有效 Ed25519 key、环境和撤销列表，不把 CRLF/LF 或普通 JSON 空白作为
|
||||
信任条件。上传到 Host 前重新序列化为确定性 LF JSON。签名目录、描述符、manifest 和
|
||||
payload 仍按原始签名字节及 SHA-256 验证。
|
||||
|
||||
## 发布前完整回归（不能替代开发验证）
|
||||
|
||||
以下清单只用于复核开发期间已经在真实 Host 上通过的链路，不得作为 Agent 改动的首次
|
||||
真实 Host 验证：
|
||||
|
||||
1. `npm test`
|
||||
2. `npm run typecheck`
|
||||
3. `npm run lint`
|
||||
4. `npm run build`
|
||||
5. 用测试签名复合包验证在线下载源选择和离线导入/导出；正式 Agent 候选还需公开校验
|
||||
双架构 production 包与签名目录。
|
||||
6. 在已固定 Host Key 的 Linux x64 测试 Host 上验证 attach-or-bootstrap。
|
||||
7. 在 GoodBuddy 专用测试目录验证 Ask 无法修改文件。
|
||||
8. 验证 Execute 可以写文件、启动进程和访问网络，同时不触碰无关 Host 文件。
|
||||
9. 运行一次有界的真实模型调用，确认凭据不进入 Renderer、SSH 参数、远端环境或磁盘，
|
||||
只在当前 accepted operation 生命周期内进入 Agent 内存。
|
||||
10. 中断并恢复 SSH，确认活动 Runtime 不被网络抖动终止。
|
||||
@@ -0,0 +1,11 @@
|
||||
# Smart Heartbeat
|
||||
|
||||
Smart Heartbeat 负责按计划或条件主动检查范围内信息，并生成可监督的建议或任务。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [智能心跳 PRD](./prd.md) | 用户目标、范围、计划、运行和产品验收 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
@@ -0,0 +1,246 @@
|
||||
# 智能心跳 PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 入口与范围已实现；未来分区记忆待独立设计 |
|
||||
| 版本 | 0.5 |
|
||||
| 日期 | 2026-08-19 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 文档角色 | 智能心跳当前能力、权威入口、范围和长期边界 |
|
||||
| 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md) |
|
||||
| 相关架构 | [自动化、监督与记忆平台总体设计](../../architecture/automation-platform-architecture.md) |
|
||||
| 相关界面 | [通用助手工作栏与执行空间 PRD](../assistant-workbar/prd.md) |
|
||||
| Task 模型 | [Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) |
|
||||
|
||||
> 本文区分近期实施与长期方向。未完成设计的“未来分区记忆”不得转写为数据结构、状态机、
|
||||
> 页面、迁移或验收条件。
|
||||
|
||||
## 1. 已确认的产品边界
|
||||
|
||||
### 1.1 智能心跳是独立能力
|
||||
|
||||
- “智能心跳”菜单入口是心跳配置、报告、建议和运行历史的权威位置。
|
||||
- 任务中心和设置中心不复制完整心跳配置表单。
|
||||
- 智能心跳不并入通用自动化中心，也不作为任务中心条目。
|
||||
- 现有心跳报告、记忆建议、行动建议和审计历史在本轮继续保留。
|
||||
|
||||
### 1.2 长期方向：未来分区记忆
|
||||
|
||||
已确认的方向只有：
|
||||
|
||||
> 智能心跳未来应成为按范围隔离的未来记忆。
|
||||
|
||||
以下内容尚未设计：
|
||||
|
||||
- “未来记忆”的数据结构与存储方式。
|
||||
- 与当前长期记忆、心跳报告和建议的关系。
|
||||
- 唤起条件、状态和生命周期。
|
||||
- 到期后的页面和交互。
|
||||
- 是否以及如何创建 Task。
|
||||
- 旧版心跳数据如何迁移。
|
||||
|
||||
本轮不得实现 `FutureMemory`、新增未来记忆数据库表，或制作“未来记忆 / 即将唤起 /
|
||||
已唤起”等页面。后续需要独立 PRD 和用户确认。
|
||||
|
||||
## 2. 本轮实施范围
|
||||
|
||||
### 2.1 目标
|
||||
|
||||
1. 完整心跳配置统一到“智能心跳”菜单入口。
|
||||
2. 心跳配置支持 `Global` 或指定一个、多个 Project。
|
||||
3. 保留现有概览、待处理建议、运行历史和报告能力。
|
||||
4. 新入口完整可用后，再移除任务中心和设置中心中的重复心跳配置。
|
||||
5. 旧心跳配置、运行、报告、建议、记忆和任务数据不丢失。
|
||||
|
||||
### 2.2 非目标
|
||||
|
||||
- 不设计或实现未来分区记忆。
|
||||
- 不修改 Task、Job 或 Task Center 模型。
|
||||
- 不新增独立 Automation Center。
|
||||
- 不移除定时任务现有入口。
|
||||
- 不扩大智能心跳的工具、目录、网络或 Execute 权限。
|
||||
- 不让智能心跳跨越配置范围读取数据。
|
||||
- 不将现有心跳建议静默转换成 Task。
|
||||
|
||||
## 3. 智能心跳范围
|
||||
|
||||
### 3.1 范围选择
|
||||
|
||||
每条心跳配置必须明确选择：
|
||||
|
||||
| 范围 | 当前执行语义 |
|
||||
| --- | --- |
|
||||
| `Global` | 回顾所有 Project 中允许读取的有界会话和任务，并读取 Global 已确认记忆 |
|
||||
| 指定 Project | 只回顾选中 Project 的有界会话和任务，并读取 Global 与选中 Project 的已确认记忆 |
|
||||
|
||||
指定 Project 可以选择一个或多个项目：
|
||||
|
||||
```text
|
||||
范围
|
||||
(•) Global
|
||||
( ) 指定项目
|
||||
[✓] 网站重构
|
||||
[ ] 内容运营
|
||||
[✓] 客户研究
|
||||
```
|
||||
|
||||
- `Global` 与指定 Project 互斥。
|
||||
- 指定 Project 时至少选择一个项目。
|
||||
- 多项目使用 Checkbox，不使用 Switch。
|
||||
- 当前项目只可以作为创建表单的建议默认值，不能在保存时隐式覆盖用户选择。
|
||||
- 切换当前项目不会改变已经保存的心跳范围。
|
||||
- Main 必须重新验证所有 Project ID，Renderer 不能扩大范围。
|
||||
|
||||
### 3.2 多项目执行
|
||||
|
||||
多项目配置的一次心跳仍然是一次运行和一份报告：
|
||||
|
||||
- 将选中项目中允许读取的会话、任务和记忆汇总后，再执行现有全局输入上限。
|
||||
- 不为每个 Project 分别创建 Run、报告、建议或 Task 副本。
|
||||
- 心跳报告成果以无项目归属保存，并在成果元数据中冻结本次配置范围。
|
||||
- 心跳产生的项目级记忆建议或行动建议必须明确目标 Project。
|
||||
- 目标 Project 不明确时，只能生成 Global 记忆建议或不绑定项目的行动建议，不能猜测。
|
||||
|
||||
### 3.3 兼容现有配置
|
||||
|
||||
旧配置按现有 `projectId` 非破坏映射：
|
||||
|
||||
- `projectId` 为空的配置迁移为 `Global`。
|
||||
- `projectId` 有值的配置迁移为“指定 Project”，且只绑定原项目。
|
||||
- 迁移不修改启停状态、重复规则、时间、回顾窗口、保留期限、下次运行或历史。
|
||||
- 项目删除时，只有该项目的配置按现有规则删除；多项目配置移除被删除项目并保留其他范围。
|
||||
|
||||
## 4. 权威入口
|
||||
|
||||
| 操作 | 权威入口 | 其他位置 |
|
||||
| --- | --- | --- |
|
||||
| 创建或编辑心跳配置 | 智能心跳 > 心跳计划 | 不复制表单 |
|
||||
| 选择 Global / Project 范围 | 智能心跳 > 心跳计划 | 不依赖当前项目推断 |
|
||||
| 暂停、恢复、立即心跳或删除 | 智能心跳 > 心跳计划 | 不复制操作 |
|
||||
| 查看报告与待处理建议 | 智能心跳 | 主导航徽标和通知可触达 |
|
||||
| 查看运行历史和失败 | 智能心跳 > 心跳轨迹 | 活动记录仅作审计补充 |
|
||||
| 管理平台级默认值 | 设置中心 | 不显示单条计划 CRUD |
|
||||
|
||||
移除重复入口的顺序：
|
||||
|
||||
1. 先在智能心跳中支持完整创建、编辑、范围、暂停、恢复、立即运行和删除。
|
||||
2. 验证旧数据与新范围均可管理。
|
||||
3. 再从任务中心移除 `HeartbeatSettings`。
|
||||
4. 再从设置中心移除重复 `HeartbeatSettings`，必要时保留“打开智能心跳”链接。
|
||||
5. 任一步失败都不得造成用户没有可用配置入口。
|
||||
|
||||
## 5. 智能心跳页面
|
||||
|
||||
保留现有四个页面：
|
||||
|
||||
- **成长概览**：状态、成功率、记忆、洞察和行动统计。
|
||||
- **待处理建议**：记忆建议和行动建议。
|
||||
- **心跳轨迹**：报告与 Run 审计。
|
||||
- **心跳计划**：唯一完整配置入口。
|
||||
|
||||
### 5.1 心跳计划
|
||||
|
||||
创建和编辑至少显示：
|
||||
|
||||
- 名称。
|
||||
- `Global` 或指定 Project 范围。
|
||||
- 每日或每周重复规则。
|
||||
- 本地时间、星期与 IANA 时区。
|
||||
- 回顾窗口。
|
||||
- 保留期限。
|
||||
- 启停状态。
|
||||
- 下次运行与上次状态。
|
||||
|
||||
交互要求：
|
||||
|
||||
- 使用持久标签，不以 placeholder 代替。
|
||||
- 编辑进入明确状态，支持保存或放弃。
|
||||
- 保存失败保留草稿。
|
||||
- 删除继续使用共享破坏性确认。
|
||||
- 运行中禁用重复操作。
|
||||
- 保存成功后由计划列表直接反映结果；失败保留草稿并在编辑区就地提示。
|
||||
|
||||
### 5.2 范围呈现
|
||||
|
||||
- 页面标题不再根据当前 Project 伪装成心跳实际范围。
|
||||
- 每张计划卡片显示 `Global` 或完整 Project 摘要。
|
||||
- 多项目过多时显示“项目 A、项目 B 等 N 个”，并提供完整可访问名称。
|
||||
- 报告成果元数据保存配置冻结范围；计划卡片始终显示计划自身范围，不根据当前项目重新解释。
|
||||
- 项目失效或删除后，界面准确显示剩余范围或配置已被移除。
|
||||
|
||||
### 5.3 响应式与无障碍
|
||||
|
||||
- 宽窗口使用 `dashboard` 壳层，创建和编辑区域保持单列。
|
||||
- 窄窗口下计划列表和表单转为单列卡片。
|
||||
- `Global / 指定项目` 使用共享分段选择控件，Project 多选使用 Checkbox。
|
||||
- 范围、状态和失败不能只依赖颜色。
|
||||
- 表单错误与字段程序化关联。
|
||||
- 对话框或编辑区关闭后，焦点返回触发按钮。
|
||||
|
||||
## 6. 数据与安全要求
|
||||
|
||||
目标合同只扩展现有心跳范围，不引入 Future Memory：
|
||||
|
||||
```ts
|
||||
type HeartbeatScope =
|
||||
| { kind: 'global' }
|
||||
| { kind: 'projects'; projectIds: string[] }
|
||||
```
|
||||
|
||||
- 旧 `projectId` 只用于迁移兼容，不继续作为目标范围合同。
|
||||
- Main 在创建、编辑、列出和执行时验证 Project 归属。
|
||||
- Global 读取所有 Project 的有界会话和任务，但长期记忆仍只读取 Global。
|
||||
- 指定 Project 读取选中项目的有界会话和任务，以及 Global 与选中项目记忆。
|
||||
- 现有输入条数、字符预算、输出大小、超时、重试、租约和工具禁用边界继续生效。
|
||||
- 多项目汇总后统一应用上限，不能按项目倍增预算。
|
||||
- 心跳结果默认不在系统通知中暴露私人正文。
|
||||
- 数据迁移必须使用 SQLite 事务，保留外键、级联删除和现有历史。
|
||||
- 心跳运行失败时，运行记录与配置的 `last_status` 必须在同一 SQLite 事务中
|
||||
更新；任一写入失败时两者一起回滚，不能留下半提交状态。
|
||||
|
||||
## 7. 实施状态与后续顺序
|
||||
|
||||
### 已完成：入口和范围
|
||||
|
||||
- 扩展共享 Schema、Preload 与 Main 数据合同。
|
||||
- 增加 Global / 多 Project 持久化与旧数据迁移。
|
||||
- 让心跳执行按冻结范围构建有界输入。
|
||||
- 在“心跳计划”中完成创建、编辑和全部计划操作。
|
||||
- 补齐范围、迁移、权限和界面测试。
|
||||
|
||||
### 已完成：移除重复配置
|
||||
|
||||
- 从 Task Center 移除心跳完整表单，保留 Task 和 Scheduled Task 现有行为。
|
||||
- 从设置中心移除单条心跳 CRUD。
|
||||
- 如需要，设置中心仅保留“打开智能心跳”导航。
|
||||
- 验证应用内仍只有一个完整配置入口。
|
||||
|
||||
### 后续：独立设计
|
||||
|
||||
- 未来分区记忆。
|
||||
- 与长期记忆的关系。
|
||||
- 唤起模型与生命周期。
|
||||
- 与 Task 的关系。
|
||||
|
||||
这些内容需要新的 PRD 和明确确认，不属于本轮实现。
|
||||
|
||||
## 8. 验收状态
|
||||
|
||||
- [x] 智能心跳菜单是完整配置的唯一权威入口。
|
||||
- [x] 用户可以创建和编辑 `Global` 心跳。
|
||||
- [x] 用户可以创建和编辑绑定一个或多个 Project 的心跳。
|
||||
- [x] 切换当前 Project 不会改变已保存范围。
|
||||
- [x] Main 拒绝不存在、已归档或超出配置范围的 Project ID。
|
||||
- [x] Global 与多项目输入遵守现有总上限，不按项目倍增。
|
||||
- [x] 多项目一次运行只产生一份 Run 和报告。
|
||||
- [x] 旧 Global 和单 Project 配置无损迁移。
|
||||
- [x] 旧运行、报告、建议、记忆和任务仍可查看。
|
||||
- [x] 心跳计划支持创建、编辑、暂停、恢复、立即运行和删除。
|
||||
- [x] 任务中心不再包含完整心跳配置表单。
|
||||
- [x] 设置中心不再包含单条心跳 CRUD。
|
||||
- [x] 任务中心本身以及定时任务现有行为没有被删除。
|
||||
- [x] 智能心跳仍保持只读、禁用工具和有界输入输出。
|
||||
- [x] 没有新增 Future Memory 表、状态机或未确认页面。
|
||||
- [x] 加载失败、空状态、字段错误和危险操作满足统一设计与无障碍要求。
|
||||
@@ -0,0 +1,16 @@
|
||||
# Task 与 Job 文档集
|
||||
|
||||
本目录定义 GoodBuddy 的工作对象、内部执行单元和调度关系。
|
||||
|
||||
## 权威文档
|
||||
|
||||
1. [Task 与 Job 统一领域模型](./task-and-job-model.md)：术语、身份和对象关系。
|
||||
2. [Task Center PRD](./task-center-prd.md)：Task 的应用级索引。
|
||||
3. [Scheduled Task PRD](./scheduled-task-prd.md)：时间或事件触发的 Task。
|
||||
4. [Goal Task PRD](./goal-task-prd.md)：围绕可验证结果有界推进的 Task。
|
||||
5. [Job 与 Subjob PRD](./job-and-subjob-prd.md)：Task 内部串行、并行和委派执行。
|
||||
|
||||
## 阅读顺序
|
||||
|
||||
先阅读统一领域模型。其他功能文档不得重新定义 Task、Conversation、Job、Run 或 Subagent。
|
||||
若实现与文档出现冲突，应先修正统一模型，再同步功能 PRD。
|
||||
@@ -0,0 +1,55 @@
|
||||
# Goal Task PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 设计中，未来能力 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-08-19 |
|
||||
| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) |
|
||||
|
||||
## 1. 产品定义
|
||||
|
||||
Goal Task 是围绕可验证结果持续推进的 Task。它只关联一条 Conversation，但该 Conversation
|
||||
也可以承载其他 Task；每轮观察、计划、行动和评估由内部 Job/Run 表达，不创建一串顶层 Task。
|
||||
|
||||
## 2. 必要配置
|
||||
|
||||
- 目标描述。
|
||||
- 至少一个成功标准。
|
||||
- 约束和停止条件。
|
||||
- 最大轮数、截止时间或预算。
|
||||
- 每轮评估方式。
|
||||
- 无进展处理。
|
||||
- Project、Runtime、知识、记忆、目录、工具和审批范围。
|
||||
|
||||
## 3. 有界循环
|
||||
|
||||
```text
|
||||
Observe Job
|
||||
→ Planning Job
|
||||
→ Permission and budget check
|
||||
→ Action Job / parallel Jobs
|
||||
→ Evaluation Job
|
||||
→ Complete, pause, revise or continue
|
||||
```
|
||||
|
||||
循环内的所有 Job 通过所属 Task 写入同一关联 Conversation。只有协调器把有意义的阶段进展
|
||||
写入消息时间线，避免每个内部步骤产生一条顶层 Task 或杂乱消息。当前 UI 只显示 Goal Task
|
||||
及其聚合状态，不显示 Job/Run 层级。
|
||||
|
||||
## 4. 完成和无进展
|
||||
|
||||
- 模型声明不能单独证明目标完成。
|
||||
- 成功标准必须可计算或可人工审查。
|
||||
- 连续两轮没有指标改善、重复下一步、连续失败、权限不可用或预算不足时暂停。
|
||||
- 修改范围、预算、Runtime、工作模式或权限必须用户确认。
|
||||
|
||||
## 5. 验收原则
|
||||
|
||||
- [ ] Goal Task 只关联一条 Conversation，Conversation 可以承载其他 Task。
|
||||
- [ ] 循环步骤以 Job 表达，不创建顶层子 Task。
|
||||
- [ ] 当前 UI 不展示 Goal Task 内部 Job/Run 层级。
|
||||
- [ ] 没有成功标准和停止条件时不能启用。
|
||||
- [ ] 无进展和预算耗尽不会伪装为成功。
|
||||
@@ -0,0 +1,102 @@
|
||||
# Job 与 Subjob PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 设计中，未来能力 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-08-19 |
|
||||
| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) |
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在不创建额外顶层 Task 或 Conversation 的前提下，让一个 Task 能够分解、串行、并行和委派
|
||||
多个执行单元，并将进展和结果有序汇入 Task 的同一 Conversation。
|
||||
|
||||
## 2. Job 类型
|
||||
|
||||
首期只使用有限类型：
|
||||
|
||||
- `step`：Task 内一个明确步骤。
|
||||
- `scheduled_occurrence`：Scheduled Task 的一次到期执行。
|
||||
- `delegated`：交给 Subagent 或远程执行器。
|
||||
- `parallel_branch`：并行方案或分工。
|
||||
- `aggregation`：汇总多个前置 Job。
|
||||
|
||||
类型描述执行方式，不创造新的产品对象层级。
|
||||
|
||||
## 3. 并行模型
|
||||
|
||||
```text
|
||||
关联 Conversation
|
||||
└─ Coordinating Job
|
||||
├─ Parallel Job A
|
||||
├─ Parallel Job B
|
||||
├─ Parallel Job C
|
||||
└─ Aggregation Job
|
||||
```
|
||||
|
||||
- 并行 Job 使用同一个 `taskId` 和 `conversationId`。
|
||||
- 每个 Job 有独立输入快照、状态、Run、预算和输出缓冲。
|
||||
- 并行 Job 不直接同时追加助手消息。
|
||||
- Aggregation Job 或 Task 协调器按确定顺序生成一条进展或结果消息。
|
||||
- 用户可以按 Task 查看有界活动和聚合状态，但不选择或展开单个 Job；主 Conversation
|
||||
保持可读。
|
||||
|
||||
## 4. Subjob
|
||||
|
||||
Job 可以创建有界 Subjob：
|
||||
|
||||
- 默认最大深度 2。
|
||||
- 默认最大并发 3。
|
||||
- 默认最大子项数、模型调用、Token、耗时和输出大小由父 Job 预算限制。
|
||||
- 子级只能使用父级已授权能力的子集。
|
||||
- 父级取消、失败或超时后，活动子级必须取消。
|
||||
|
||||
## 5. Subagent
|
||||
|
||||
Subagent 是 Job 的执行者：
|
||||
|
||||
- 专家选择和路由记录在 Job 上。
|
||||
- Subagent 的原始流式输出进入有界 Job 缓冲和活动记录。
|
||||
- 完成、失败和部分输出都返回父 Job。
|
||||
- Subagent 不获得独立 Task Center 条目或 Conversation。
|
||||
|
||||
## 6. 状态与恢复
|
||||
|
||||
Job 状态至少包括：
|
||||
|
||||
```text
|
||||
queued → running → waiting_approval → completed
|
||||
↘ failed | cancelled | interrupted | budget_exceeded
|
||||
```
|
||||
|
||||
- 重试创建新 Run，不覆盖失败 Run。
|
||||
- 应用退出将活动 Job 标记为 `interrupted`。
|
||||
- 有外部副作用且结果未知的 Job 不自动重试。
|
||||
- 聚合 Job 必须明确处理部分成功、全部失败和取消。
|
||||
|
||||
## 7. 界面
|
||||
|
||||
当前产品 UI 的对象层级止于 Task，不提供 Job/Subjob 树、独立页面或导航入口。
|
||||
|
||||
关联 Conversation 和 Task Center 只显示：
|
||||
|
||||
- 当前总体进展。
|
||||
- 并行执行数量和聚合状态。
|
||||
- 需要审批或用户输入的 Task 状态。
|
||||
- 完成后的统一结果。
|
||||
|
||||
活动与 Runtime 可以按 Task 显示执行者、工具、耗时、预算、错误、审批和成果事件，但不把
|
||||
Job、Subjob 或 Run 暴露为可选择、可展开或可操作的产品对象。内部标识只用于关联与审计。
|
||||
|
||||
## 8. 验收标准
|
||||
|
||||
- [ ] 并行 Job 通过所属 Task 写入同一关联 Conversation。
|
||||
- [ ] Job 不创建顶层 Task。
|
||||
- [ ] 并行输出不会无序污染消息时间线。
|
||||
- [ ] Subjob 深度、并发、预算和输出有界。
|
||||
- [ ] Subagent 失败能够返回部分输出和明确状态。
|
||||
- [ ] 父级取消传播到所有活动子级。
|
||||
- [ ] 当前 UI 只展示到 Task，不显示 Job/Subjob/Run 层级。
|
||||
@@ -0,0 +1,370 @@
|
||||
# Scheduled Task PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 首期稳定 Task 生命周期、创建体验与 Conversation 输入仲裁已实现；高级触发和执行治理待实施 |
|
||||
| 版本 | 0.7 |
|
||||
| 日期 | 2026-08-19 |
|
||||
| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) |
|
||||
| 相关架构 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md) |
|
||||
|
||||
## 1. 产品定义
|
||||
|
||||
Scheduled Task 是带时间或事件触发器的 Task。每个 Scheduled Task 关联一条 Conversation；
|
||||
一条 Conversation 可以同时承载多个 Task。
|
||||
|
||||
创建 Scheduled Task 时：
|
||||
|
||||
1. 用户选择关联当前 Conversation 或创建新 Conversation。
|
||||
2. 系统创建一个 Task，并保存稳定 `conversationId` 和 Schedule/Trigger Binding。
|
||||
3. 每次触发在同一 Task 内创建新的 Job 和 Run。
|
||||
4. 面向用户的文本进展和结果写回关联 Conversation，并标明 Task 来源。
|
||||
5. 独立交付物保存为 Artifact，并由结果消息引用。
|
||||
|
||||
因此，一个每日任务在 Task Center 中始终是一条 Task，而不是每天新增一条 Task；左侧会话
|
||||
列表通过行首展开按钮和带任务图标的子项呈现其关联。
|
||||
|
||||
## 2. 当前能力与差距
|
||||
|
||||
GoodBuddy 当前已实现首期统一生命周期：
|
||||
|
||||
- 创建 Modal 可以关联当前 Conversation 或原子创建新 Conversation，不修改当前
|
||||
Conversation 的标题和既有消息。
|
||||
- 每个 Schedule 绑定一个稳定产品级 Task 和 Conversation；重复触发复用同一身份，不再
|
||||
为每次触发创建新的顶层 Task。
|
||||
- 默认选择 Execute，并允许用户主动切换 Ask；不支持工具执行时明确禁用 Execute。
|
||||
- 单次、每日和每周计划支持暂停、恢复、立即运行、应用重启恢复和最多 4 个独立计划并发。
|
||||
- 到期和手动运行先进入关联 Conversation 的持久输入队列，与回复期间继续发送的普通消息
|
||||
顺序仲裁；默认不打断当前回复，也不与其并发写入时间线。
|
||||
- Composer 上沿显示待发送项和来源。用户可以删除尚未执行的 occurrence，或选择“立即
|
||||
中断并插入”取消当前执行并将该项提升为下一项。
|
||||
- 文本结果和失败写回关联 Conversation 并带 Task 来源；独立文件和图片继续保存为 Artifact。
|
||||
- 左侧 Conversation 列表、Conversation Task 区和 Task Center 使用同一产品 Task；普通
|
||||
模型请求、Subagent、委派和 Smart Heartbeat 内部 Task 不进入产品索引。
|
||||
- v22 迁移保留 Schedule 配置和历史运行，并为旧计划补齐稳定 Task 与 Conversation；v23
|
||||
增加可恢复的统一 Conversation 输入队列。
|
||||
|
||||
尚未实现的高级能力包括 IANA 时区与 DST 墙上时间、每月/工作日/受限 Cron、事件触发、
|
||||
可配置错过执行策略、租约、重试与结果未知治理、完整预算和权限快照，以及面向内部
|
||||
Job/Subjob/Run 的统一持久化抽象。当前每日和每周按既有 UTC 间隔递推。
|
||||
|
||||
## 3. 目标
|
||||
|
||||
- 支持单次、每日、每周、每月、工作日和受限 Cron。
|
||||
- 支持 Task 完成、失败、Conversation 完成等内部事件触发。
|
||||
- 创建时明确选择当前或新 Conversation。
|
||||
- 默认使用 Execute，并允许用户主动切换到 Ask。
|
||||
- 冻结 Project、Runtime、工作目录、工具、知识、记忆和审批范围。
|
||||
- 提供时区、错过执行、幂等、租约、重试、恢复、取消、预算和审计。
|
||||
- 让所有重复触发复用同一 Task 和 Conversation 关联。
|
||||
- 为一次触发建立清晰 Job/Run，而不是创建新的顶层 Task。
|
||||
|
||||
## 4. 非目标
|
||||
|
||||
- 不提供任意脚本和循环的通用 DAG 编辑器。
|
||||
- 不允许模型生成并直接启用任意 Shell、SQL 或无限频率 Cron。
|
||||
- 不承诺应用退出后继续运行。
|
||||
- 不允许后台计划静默扩大权限、目录、知识、记忆或网络范围。
|
||||
- 不把 Smart Heartbeat 变成 Scheduled Task。
|
||||
- 不把每次触发、重试、Job 或 Run 显示为新的顶层 Task。
|
||||
- 不在左侧会话列表继续展开 Job、Subjob 或 Run。
|
||||
|
||||
## 5. 创建入口与 Modal
|
||||
|
||||
Task Center 和 Conversation 操作都可以提供“新建定制任务”，但共用同一个 Modal，不在
|
||||
窄侧栏长期展开完整表单。
|
||||
|
||||
```text
|
||||
新建定制任务
|
||||
创建一个可以按计划自动运行，并持续记录在会话中的任务
|
||||
|
||||
任务名称 *
|
||||
[ 每周项目总结 ]
|
||||
|
||||
任务要求 *
|
||||
[ 总结本周完成和失败的工作，并列出下周优先事项。 ]
|
||||
|
||||
关联会话
|
||||
◉ 当前会话
|
||||
产品发布讨论 · GoodBuddy Desktop · 已有 2 个任务
|
||||
|
||||
○ 新建会话
|
||||
为任务创建一条新会话，默认标题为任务名称
|
||||
|
||||
执行模式
|
||||
[ Execute ] [ Ask ]
|
||||
|
||||
运行频率
|
||||
[ 单次 ] [ 每日 ] [ 每周 ] [ 每月 ] [ 工作日 ] [ Cron ]
|
||||
|
||||
首次运行 [ 2026-08-21 ] [ 17:00 ]
|
||||
时区 [ Asia/Shanghai ▾ ]
|
||||
|
||||
执行范围
|
||||
GoodBuddy Desktop · OpenCode · 项目工作目录
|
||||
8 个工具可用 · 高风险操作需要审批 [编辑]
|
||||
|
||||
[取消] [创建任务]
|
||||
```
|
||||
|
||||
### 5.1 Conversation 选择
|
||||
|
||||
- 从当前聊天发起时默认选择当前 Conversation。
|
||||
- 从 Task Center 发起时默认选择新 Conversation。
|
||||
- 当前选择必须持续可见，不能根据入口静默决定后隐藏。
|
||||
- 关联当前 Conversation 不修改其标题、既有消息和普通聊天能力。
|
||||
- 当前 Conversation 已有关联 Task 时，显示 Task 数量和共享上下文说明。
|
||||
- 新 Conversation 默认使用 Task 名称作为标题，用户可以单独修改。
|
||||
- 远程通道、归档、正在删除或 Project 不匹配的 Conversation 不可选择，并显示原因。
|
||||
|
||||
### 5.2 创建摘要
|
||||
|
||||
提交前显示确定性摘要：
|
||||
|
||||
```text
|
||||
✓ 为当前 Conversation 新增一个 Task
|
||||
✓ 在左侧会话列表显示“任务 3”
|
||||
✓ 默认以 Execute 模式运行
|
||||
✓ 每周五 17:00 自动执行此 Task
|
||||
✓ 文本结果写入当前 Conversation
|
||||
✓ 独立交付物保存到成果
|
||||
```
|
||||
|
||||
创建 Task、可选新 Conversation、关联关系和 Schedule Binding 必须在 Main 中原子提交。
|
||||
失败时保持 Modal 和用户输入，不只显示短暂通知。提交期间锁定重复操作。
|
||||
|
||||
### 5.3 Modal 行为与无障碍
|
||||
|
||||
- 使用 `role="dialog"`、`aria-modal="true"`、稳定标题和说明关联。
|
||||
- 打开后聚焦首个必填字段，Tab 焦点限制在 Modal 内。
|
||||
- Escape 在未提交时关闭并恢复触发按钮焦点。
|
||||
- 窄窗口使用接近全宽布局，保留 `16px` 外边距。
|
||||
- 字段错误靠近字段；非字段异步错误保留在 Modal 内并提供重试。
|
||||
|
||||
## 6. 工作模式、Runtime 与工具
|
||||
|
||||
### 6.1 默认 Execute
|
||||
|
||||
创建 Modal 默认选择 Execute：
|
||||
|
||||
- Execute 可以调用当前 Runtime 与 Project 已启用、且被 Task 快照允许的工具。
|
||||
- Ask 保持 Runtime 边界只读，只能调用允许的只读能力。
|
||||
- 所选 Runtime 不支持工具执行时，不能静默降级为 Ask；用户必须更换 Runtime 或主动选择
|
||||
Ask。
|
||||
- Modal 持续显示实际 Runtime、Project、工作目录和权限摘要。
|
||||
|
||||
### 6.2 权限快照
|
||||
|
||||
Task 创建时冻结：
|
||||
|
||||
- Project 和工作目录。
|
||||
- Runtime 与模型选择。
|
||||
- 工作模式。
|
||||
- Skills、MCP、知识库、记忆和上下文范围。
|
||||
- 可用工具与审批策略。
|
||||
- 预算、并发和输出限制。
|
||||
|
||||
后续设置变化不修改已启动 Run。编辑 Task 配置只影响后续 Job。
|
||||
|
||||
### 6.3 审批
|
||||
|
||||
- Execute 继续遵守当前 Runtime、GoodBuddy 原生能力和工具审批控制。
|
||||
- 已启用且按现有策略允许自动执行的工具可以在后台运行。
|
||||
- 需要额外确认的动作进入 `waiting_approval`，暂停所属 Job 并发送应用内及桌面通知。
|
||||
- 用户批准后继续同一个 Job/Run；拒绝后按协议失败、跳过或请求调整。
|
||||
- 定时触发不能把高风险、越界或未授权动作转换成自动批准。
|
||||
- 结果未知的外部副作用进入 `outcome_unknown`，不得自动重试。
|
||||
|
||||
## 7. 触发器
|
||||
|
||||
### 7.1 时间触发
|
||||
|
||||
```ts
|
||||
type TimeTrigger =
|
||||
| { type: 'once'; at: string; timezone: string }
|
||||
| { type: 'daily'; localTime: string; timezone: string }
|
||||
| {
|
||||
type: 'weekly'
|
||||
weekdays: number[]
|
||||
localTime: string
|
||||
timezone: string
|
||||
}
|
||||
| {
|
||||
type: 'monthly'
|
||||
day: number | 'last'
|
||||
localTime: string
|
||||
timezone: string
|
||||
}
|
||||
| {
|
||||
type: 'cron'
|
||||
expression: string
|
||||
timezone: string
|
||||
}
|
||||
```
|
||||
|
||||
“工作日”是 `weekly` 的周一至周五预设，不增加新的持久化触发类型。
|
||||
|
||||
受限 Cron 使用五字段，不支持秒、年份、宏、`L`、`W`、`#` 或供应商扩展。Main 负责解析，
|
||||
默认最小间隔为 15 分钟，并展示未来五次触发时间。
|
||||
|
||||
### 7.2 事件触发
|
||||
|
||||
后续支持：
|
||||
|
||||
- `conversation.completed`
|
||||
- `task.completed`
|
||||
- `task.failed`
|
||||
- `artifact.created`
|
||||
- `knowledge.sync.completed`
|
||||
- `magic_note.updated`
|
||||
|
||||
事件触发配置来源范围、确定性过滤、去重窗口、冷却时间和并发上限。基础匹配不调用模型。
|
||||
|
||||
### 7.3 手动触发
|
||||
|
||||
“立即运行”在当前 Task 内创建独立 Job 和 Run，不改变下一次计划时间，不创建新 Task。
|
||||
重复点击使用调用级幂等键去重。
|
||||
|
||||
### 7.4 与普通消息的顺序
|
||||
|
||||
同一 Conversation 的普通消息和 Scheduled Task occurrence 使用同一 FIFO 队列。Agent
|
||||
正在回复时，到期 occurrence 只显示为待执行，不中断当前输出；当前执行结束后才认领下一项。
|
||||
用户显式选择“立即中断并插入”时，系统取消当前 Conversation 的活动请求，并让所选项成为
|
||||
下一项。删除待执行 occurrence 只取消该次运行，不删除稳定 Task、Conversation 或历史结果。
|
||||
|
||||
## 8. 一次触发的对象关系
|
||||
|
||||
```text
|
||||
Conversation
|
||||
└─ Scheduled Task
|
||||
├─ Schedule Binding
|
||||
└─ Job: scheduled_occurrence
|
||||
└─ Run
|
||||
```
|
||||
|
||||
- `scheduledFor` 和计划版本形成幂等键。
|
||||
- 同一 Scheduled Task 默认最多一个活动 occurrence Job。
|
||||
- 若允许并行 occurrence，它们仍属于同一 Task，并由协调器有序写回关联 Conversation。
|
||||
- 重试产生新 Run，不产生新 Task 或新 occurrence Job。
|
||||
|
||||
## 9. 左侧会话列表
|
||||
|
||||
普通 Conversation 保持单行。包含 Task 的 Conversation 显示行首展开按钮：
|
||||
|
||||
```text
|
||||
▾ 产品发布讨论 10:24
|
||||
|
||||
每周进度总结 每周 · Execute · 等待中 ●
|
||||
发布前检查 单次 · Execute ✓
|
||||
```
|
||||
|
||||
- 父会话行不重复显示任务标签或数量；Task 子项名称在左，模式、计划和状态标记收在右侧，
|
||||
与父会话的更新时间位置一致。
|
||||
- 点击 Conversation 标题打开聊天；点击 Task 子项打开同一 Conversation 并定位到该 Task。
|
||||
- 新建 Task 成功后首次自动展开。用户手动折叠后持久化其选择，后台运行不强制展开。
|
||||
- 默认最多直接显示 3 个 Task；“查看全部 N 个任务”打开该 Conversation 的完整 Task 区。
|
||||
- Task 子项显示本地化的模式、计划和非完成态状态文字；状态标记固定在行尾。已完成使用
|
||||
带勾成功点，并将完成文案保留给辅助技术，避免在紧凑元数据中重复显示且不只靠颜色表达。
|
||||
- 左侧只展开 Task；当前产品 UI 的其他区域也不提供 Job/Run 树或独立导航。
|
||||
|
||||
## 10. Conversation 内呈现
|
||||
|
||||
打开包含 Task 的 Conversation 后，顶部提供可折叠 Task 条：
|
||||
|
||||
```text
|
||||
本会话有 2 个任务
|
||||
[每周进度总结] [发布前检查] [管理任务]
|
||||
```
|
||||
|
||||
选中 Task 后显示：
|
||||
|
||||
- 名称、状态和模式。
|
||||
- 计划、下次执行和未来预览。
|
||||
- 最近一次执行结果。
|
||||
- “立即运行”“暂停”“编辑计划”等操作。
|
||||
- 需要审批时的明确恢复入口。
|
||||
|
||||
每条自动结果消息显示 Task 名称、触发来源和时间。普通文本作为消息保存；文件、图片、PDF 和
|
||||
其他独立交付物保存为 Artifact，并从消息引用。多个 Task 并发时，最终文本以完整消息写入，
|
||||
不能把流式 Token 无序混入同一消息时间线。
|
||||
|
||||
## 11. Task Center
|
||||
|
||||
Task Center 显示 Scheduled Task 的范围、关联 Conversation、状态、模式、最近进展、需要
|
||||
关注和下次触发时间：
|
||||
|
||||
- 点击条目打开关联 Conversation，并定位到该 Task。
|
||||
- “立即运行”在内部创建 Job/Run，但 UI 仍只呈现 Task，不改变计划时间。
|
||||
- 暂停只阻止新 Job，不取消已经完成的外部副作用。
|
||||
- Task Center 是完整索引；左侧展开列表只是最近 Conversation 下的轻量入口。
|
||||
- 不新增平行 Automation Center。
|
||||
|
||||
## 12. 错过执行
|
||||
|
||||
| 策略 | 行为 |
|
||||
| --- | --- |
|
||||
| `skip` | 记录跳过，不补跑 |
|
||||
| `run_once` | 无论错过多少次，只在当前 Task 内补一个 Job |
|
||||
| `catch_up_bounded` | 在数量和时间窗口上限内创建多个有界 Job |
|
||||
|
||||
默认补跑最多 3 次、最多回溯 7 天。补跑同样受 Task 的并发、权限和预算控制。
|
||||
|
||||
## 13. 时区和夏令时
|
||||
|
||||
- 保存 IANA 时区，不保存固定 UTC 偏移。
|
||||
- 春季不存在的本地时间在当日第一个有效分钟触发。
|
||||
- 秋季重复时间只触发一次。
|
||||
- 系统时区变化不自动修改计划时区。
|
||||
- UI 显示计划时区、本机时区差异和未来五次触发时间。
|
||||
|
||||
## 14. 预算、恢复和删除
|
||||
|
||||
每个 Scheduled Task 配置最大 Job 耗时、模型/Token/工具调用、成果大小、活动 Job 数和后台
|
||||
优先级。前台请求优先，后台达到上限时记录 `deferred`。
|
||||
|
||||
- 瞬时且没有未知副作用的失败可以有界重试。
|
||||
- 配置、权限和范围错误不重试。
|
||||
- 应用退出将活动 Job/Run 标记为 `interrupted`。
|
||||
- 取消 Task 必须传播到活动 Job、Subjob 和 Runtime。
|
||||
- 删除 Schedule 只停止后续触发，不删除 Task、Conversation 或历史。
|
||||
- 删除 Task 停止其计划并移除关联，默认保留 Conversation 和既有消息。
|
||||
- 删除 Conversation 前显示关联 Task 数量，并先处理活动 Job。
|
||||
|
||||
## 15. 兼容迁移
|
||||
|
||||
现有 Schedule、Schedule Run、Task 和 Conversation 数据渐进关联：
|
||||
|
||||
- 保留现有计划 ID、启停状态、下次时间和历史。
|
||||
- 为每个现有 Schedule 创建一个稳定产品级 Task。
|
||||
- 旧 Schedule 不猜测绑定已有用户 Conversation；为其创建新的关联 Conversation。
|
||||
- 历史每次执行映射为该 Task 下的 occurrence Job/Run。
|
||||
- 旧执行产生的 Task 行在映射成功后不再作为产品级 Task 索引，但其状态、活动和成果继续
|
||||
通过迁移后的 Job/Run 归属保留。
|
||||
- 旧文本 Artifact 可以保留，但迁移不得把它们重复写成新消息。
|
||||
- 迁移不得复制用户消息、独立成果或顶层 Task。
|
||||
|
||||
## 16. 验收标准
|
||||
|
||||
- [x] 创建 Scheduled Task 可以选择当前或新 Conversation。
|
||||
- [x] 关联当前 Conversation 不修改其标题、类型或既有消息。
|
||||
- [x] 一条 Conversation 可以在左侧展开一个或多个 Task。
|
||||
- [x] 默认工作模式为 Execute，且用户可以主动选择 Ask。
|
||||
- [ ] Execute 能调用快照允许的工具，但不能绕过 Runtime 和审批控制。
|
||||
- [x] 不支持工具的 Runtime 不会让 Execute 静默降级。
|
||||
- [x] 重复触发始终复用同一 Task 和 Conversation 关联。
|
||||
- [x] 每次触发创建内部运行记录，不创建新的顶层 Task。
|
||||
- [x] 内部运行记录只用于执行和审计，不在 UI 中显示为独立层级。
|
||||
- [ ] 支持单次、每日、每周、每月、工作日和受限 Cron。
|
||||
- [ ] UI 显示计划时区和未来五次触发时间。
|
||||
- [ ] 夏令时不会造成漂移或双跑。
|
||||
- [ ] 错过执行按配置跳过、补一次或有界补跑。
|
||||
- [x] 手动运行不改变下次计划时间。
|
||||
- [x] Scheduled Task 与普通消息共用 Conversation 级队列，不并发写入同一时间线。
|
||||
- [x] 当前回复期间可以继续发送普通消息，并在 Composer 上沿查看、删除或提升待发送项。
|
||||
- [x] 应用重启恢复尚未执行的队列项和有界附件上下文；已写入 Conversation 的用户输入
|
||||
通过队列项身份完成恢复对账，不会再次进入待发送队列。
|
||||
- [x] 文本结果只写入 Conversation，独立交付物才进入成果。
|
||||
- [ ] Task Center 和桌面通知可以打开正确 Conversation 并定位 Task。
|
||||
- [ ] 应用重启不自动重放结果未知的副作用。
|
||||
@@ -0,0 +1,245 @@
|
||||
# Task 与 Job 统一领域模型
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 产品边界与 Scheduled Task 首期已实现；通用 Job/Run 能力待实施 |
|
||||
| 版本 | 0.3 |
|
||||
| 日期 | 2026-08-19 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 文档角色 | Task、Conversation、Job、Run 与 Subagent 的权威定义 |
|
||||
|
||||
## 1. 核心定义
|
||||
|
||||
### 1.1 Task
|
||||
|
||||
Task 是用户明确创建或确认的工作单位，也是 Task Center 的顶层对象。
|
||||
|
||||
- 每个 Task 必须关联且只关联一条 Conversation。
|
||||
- 创建 Task 时，用户可以关联当前 Conversation，也可以同时创建一条新 Conversation。
|
||||
- 关联当前 Conversation 不改变其对象类型、标题、既有消息或普通聊天能力，只增加 Task
|
||||
关联及其可见入口。
|
||||
- Task 的目标、状态、范围、计划、Job、审批、活动和成果使用独立 Task 身份保存。
|
||||
- 打开 Task 会打开关联的 Conversation，并定位或展开对应 Task。
|
||||
- 一个 Task 在生命周期内保持稳定的 `taskId` 和 `conversationId` 关联。
|
||||
- 删除 Task 默认停止其计划并移除关联，不删除 Conversation 或既有消息。
|
||||
|
||||
普通模型请求、工具调用或 Runtime Run 不自动成为产品级 Task。只有用户明确创建、确认或
|
||||
由已启用产品流程创建的工作，才进入 Task Center 和 Conversation 的 Task 列表。
|
||||
|
||||
### 1.2 Conversation
|
||||
|
||||
Conversation 是用户消息、助手消息和面向用户结果的内容容器，不因为关联 Task 而变成另一
|
||||
种 Conversation：
|
||||
|
||||
- 一条 Conversation 可以不关联 Task，也可以关联一个或多个 Task。
|
||||
- 多个 Task 可以共享同一 Conversation 的可见上下文，但各自拥有独立配置、计划、权限
|
||||
快照、状态、Job、Run 和成果引用。
|
||||
- Conversation 标题与 Task 名称相互独立。创建或重命名 Task 不静默修改现有会话标题。
|
||||
- 从稳定的本地 Conversation 创建分支会生成新的 Conversation 和消息 ID，并保存直接来源
|
||||
标识；它只复制可见聊天内容与会话级 Runtime/知识检索选择，不复制 Task、发送队列、Job、
|
||||
Run、记忆或 Artifact 归属。来源与分支后续独立更新，删除来源不删除已创建的分支。
|
||||
- 左侧会话列表根据显式 Task 关联显示行首展开按钮；父会话行不重复任务标签，展开后的
|
||||
Task 子项左侧显示名称，右侧显示状态标记，并只展开到 Task 层。
|
||||
- 并行 Job 不直接无序写入消息流；进度留在各自 Task/Job 状态中，最终文本以带来源元数据
|
||||
的完整消息写入 Conversation。
|
||||
- 删除 Conversation 前必须说明关联 Task 数量，并先停止或结算仍活动的 Job。
|
||||
|
||||
### 1.3 Job
|
||||
|
||||
Job 是 Task 内部的执行单位，不是新的顶层 Task：
|
||||
|
||||
- 一次计划触发、一个执行步骤、一项专家委派或一组并行工作都可以是 Job。
|
||||
- 一个 Task 可以串行或并行运行多个 Job。
|
||||
- 所有 Job 仍属于同一个 Task，并通过该 Task 关联的 Conversation 呈现用户可见结果。
|
||||
- Job 可以有自己的状态、预算、Runtime、执行者、输入快照和成果引用。
|
||||
- Job 不进入 Task Center、左侧会话列表或独立详情页。当前产品 UI 的对象层级止于 Task；
|
||||
活动和 Runtime 只按 Task 展示有界执行事件、工具、审批与错误，不呈现 Job 树。
|
||||
|
||||
### 1.4 Subjob
|
||||
|
||||
Subjob 是 Job 的子执行单元。它用于分解和并发，不创建新的 Task 或 Conversation。
|
||||
|
||||
- 父 Job 负责合并 Subjob 结果。
|
||||
- 取消父 Job 必须传播到仍活动的 Subjob。
|
||||
- Subjob 不能扩大父 Job 的 Project、目录、工具、知识、记忆或审批范围。
|
||||
- 深度、数量、并发、时间、Token 和输出大小必须有界。
|
||||
|
||||
### 1.5 Run
|
||||
|
||||
Run 是 Job 或 Subjob 的一次执行尝试和审计记录，不是用户工作对象：
|
||||
|
||||
- 重试、恢复或手动重新运行可以产生新的 Run。
|
||||
- Run 冻结当次配置、范围、预算、Runtime 和权限策略。
|
||||
- Run 进入内部审计；当前 UI 可以显示某次 Task 执行的时间、状态和活动，但不把 Run 呈现为
|
||||
可导航的产品对象。
|
||||
- `completed` 只表示该次执行按协议结束，不必然表示 Task 目标达成。
|
||||
|
||||
### 1.6 Subagent
|
||||
|
||||
Subagent 是执行 Job 或 Subjob 的受限执行者，不是对象层级：
|
||||
|
||||
- 专家、Agent Runtime 或其他执行器可以承担 Job。
|
||||
- Subagent 不自动拥有独立 Task 或 Conversation。
|
||||
- Subagent 输出先回到所属 Job，再由 Task 协调器写入关联 Conversation。
|
||||
|
||||
## 2. 对象关系
|
||||
|
||||
```text
|
||||
Conversation 1 ── 0..N Task
|
||||
│
|
||||
├─ Schedule / Trigger Binding（可选）
|
||||
├─ Job 1
|
||||
│ ├─ Run 0..N
|
||||
│ └─ Subjob 0..N
|
||||
│ └─ Run 0..N
|
||||
├─ Job 2（可与 Job 1 并行）
|
||||
└─ Artifact / Approval / Activity / Notification
|
||||
```
|
||||
|
||||
从 Task 方向看：
|
||||
|
||||
```text
|
||||
Task N ── 1 Conversation
|
||||
```
|
||||
|
||||
不允许：
|
||||
|
||||
```text
|
||||
Task → 没有关联 Conversation
|
||||
Task → 同时关联多条 Conversation
|
||||
Job → 新建顶层 Task
|
||||
Subagent → 自动新建 Conversation
|
||||
Job / Run → 成为可独立导航的 UI 对象
|
||||
```
|
||||
|
||||
## 3. 创建 Task
|
||||
|
||||
创建定制 Task 时必须明确选择 Conversation：
|
||||
|
||||
```text
|
||||
关联当前 Conversation
|
||||
或
|
||||
创建新 Conversation
|
||||
```
|
||||
|
||||
- 从当前聊天发起时，默认选择当前 Conversation。
|
||||
- 从 Task Center 发起时，默认选择新 Conversation。
|
||||
- 选择当前 Conversation 时持续显示会话标题、Project 和已有 Task 数量。
|
||||
- 选择新 Conversation 时，默认使用 Task 名称作为会话标题，但允许用户修改。
|
||||
- Task、Conversation 关联和可选 Schedule Binding 必须在 Main 中原子创建或回滚。
|
||||
|
||||
## 4. Scheduled Task
|
||||
|
||||
Scheduled Task 仍然是 Task，而不是 Schedule 定义和临时 Task 的松散组合：
|
||||
|
||||
1. 用户选择当前或新 Conversation。
|
||||
2. 系统创建一个 Task，建立稳定 `conversationId` 关联，并保存 Schedule/Trigger Binding。
|
||||
3. 到期时在该 Task 内创建新的 Job 和 Run。
|
||||
4. 每次触发的进展和文本结果写入同一关联 Conversation。
|
||||
5. 独立文件、图片和其他交付物保存为 Artifact，并从结果消息引用。
|
||||
6. 编辑计划影响后续 Job，不修改已经启动的 Run。
|
||||
|
||||
同一 Scheduled Task 默认串行触发。需要并行时，应显式允许多个 Job 并发，并继续使用同一
|
||||
Task 和 Conversation 关联，而不是复制顶层 Task。
|
||||
|
||||
## 5. 消息归属
|
||||
|
||||
Task 产生的用户可见消息至少记录：
|
||||
|
||||
```ts
|
||||
type TaskMessageMetadata = {
|
||||
taskId: string
|
||||
jobId: string
|
||||
runId: string
|
||||
trigger: 'manual' | 'scheduled' | 'event' | 'goal'
|
||||
}
|
||||
```
|
||||
|
||||
同一 Conversation 关联多个 Task 时：
|
||||
|
||||
- 消息持续显示来源 Task 名称。
|
||||
- 点击左侧展开项或 Task Center 条目可以定位对应 Task 和近期消息。
|
||||
- 任务筛选只改变定位和高亮，不隐藏用户未主动筛选的普通消息。
|
||||
- 多个活动 Job 的流式细节进入各自活动记录，最终文本有界持久化后再写入 Conversation。
|
||||
|
||||
## 6. 状态分层
|
||||
|
||||
| 层级 | 典型状态 | 用户在哪里看到 |
|
||||
| --- | --- | --- |
|
||||
| Task | idle、queued、running、waiting_approval、paused、completed、failed、cancelled、interrupted | Task Center、左侧会话展开项、Conversation |
|
||||
| Job | queued、running、waiting_approval、completed、failed、cancelled | 内部协调与审计，不作为 UI 对象 |
|
||||
| Run | claimed、running、completed、failed、cancelled、interrupted、budget_exceeded、outcome_unknown | 内部执行与审计，不作为 UI 对象 |
|
||||
|
||||
Task 状态由当前目标和所属 Job 聚合得出，但不能用“任一 Job 完成”直接推断 Task 完成。
|
||||
Conversation 折叠行只显示其关联 Task 中最高优先级的关注状态：
|
||||
|
||||
```text
|
||||
waiting_approval > failed > running > paused > idle
|
||||
```
|
||||
|
||||
## 7. UI 展示边界
|
||||
|
||||
当前产品 UI 的对象层级统一止于 Task：
|
||||
|
||||
- 左侧会话列表展开到 Task。
|
||||
- Task Center 只索引 Task。
|
||||
- Conversation 顶部任务区只选择和管理 Task。
|
||||
- 活动与 Runtime 可以展示 Task 的执行时间、工具、审批、错误、成果和状态事件，但不显示
|
||||
Job/Subjob 树，不提供 Job/Run 路由、列表或独立操作菜单。
|
||||
- “立即运行”“重试”和“恢复”在 UI 上都是 Task 操作；Job/Run 只在内部创建和审计。
|
||||
|
||||
## 8. 左侧 Conversation Task 列表
|
||||
|
||||
左侧最近会话列表是轻量发现入口，不替代 Task Center：
|
||||
|
||||
- 无 Task 的 Conversation 保持现有单行样式。
|
||||
- 有 Task 的 Conversation 显示行首展开按钮，父会话行不重复任务标签或数量。
|
||||
- 展开后只显示名称、本地化摘要和右侧状态标记，不继续显示 Job、Subjob 或 Run。
|
||||
- 新建 Task 成功后首次自动展开；用户手动折叠后保持选择，后台状态变化不强制展开。
|
||||
- 默认最多直接显示 3 个 Task；“查看全部 N 个任务”打开该 Conversation 的完整 Task 区。
|
||||
- Task 子项的状态标记固定在右侧；运行、审批、失败和暂停同时使用本地化状态文字。
|
||||
- 删除最后一个关联 Task 后，Conversation 的展开按钮自动消失。
|
||||
|
||||
## 9. 兼容映射
|
||||
|
||||
当前代码和旧文档中的对象按以下方式收敛：
|
||||
|
||||
| 旧概念 | 目标概念 |
|
||||
| --- | --- |
|
||||
| 自动任务 | Scheduled Task、Event Task 或 Goal Task |
|
||||
| 自动会话 | 删除该独立概念，使用关联 Conversation |
|
||||
| 子任务、Child Task | Job 或 Subjob |
|
||||
| 专家子任务 | 由专家 Subagent 执行的 Job/Subjob |
|
||||
| 多任务并行 | 一个或多个 Task 下的并行 Job；根据用户目标和 Conversation 归属明确建模 |
|
||||
| Schedule Run | Scheduled Task 内的 Job Run |
|
||||
| Automation Run | Task 所属 Job 或 Subjob 的 Run |
|
||||
| 普通请求 Task 行 | 内部执行/审计记录，不自动成为产品级 Task |
|
||||
|
||||
数据库字段可以在兼容期保留旧名称，但新产品文案、PRD 和新增契约必须使用本模型。
|
||||
|
||||
## 10. 安全和数据要求
|
||||
|
||||
- Main 验证 Conversation、Task、Job、Run 和 Project 的完整归属链。
|
||||
- Task 只能关联同一 Project 范围内允许使用的 Conversation。
|
||||
- Renderer 不能把任意 Task 或 Job 绑定到其他 Project 的 Conversation。
|
||||
- Job/Subjob 继承 Task 的能力上限，只能缩小，不能扩大。
|
||||
- Execute Task 冻结 Runtime、工作目录、工具和审批策略；后台触发不能扩大权限。
|
||||
- 并行输出先有界持久化，再按确定顺序汇总到 Conversation。
|
||||
- 取消、超时、审批和应用退出必须沿 Task → Job / Subjob → Run → Runtime 传播。
|
||||
- 删除 Task 默认保留 Conversation 和消息；删除 Conversation 必须处理其全部关联 Task。
|
||||
|
||||
## 11. 验收原则
|
||||
|
||||
- [ ] 每个 Task 只关联一条 Conversation。
|
||||
- [ ] 一条 Conversation 可以关联零个、一个或多个 Task。
|
||||
- [ ] 创建 Task 可以选择当前 Conversation 或新 Conversation，且不会改变当前会话类型。
|
||||
- [ ] 左侧会话列表通过行首按钮展开带任务图标和本地化摘要的 Task，但不展开 Job/Run。
|
||||
- [ ] 当前 UI 不提供 Job、Subjob 或 Run 的独立列表、树、路由或操作菜单。
|
||||
- [ ] Scheduled Task 的重复触发复用同一 Task 和 Conversation 关联。
|
||||
- [ ] 一个 Task 可以运行多个串行或并行 Job。
|
||||
- [ ] Job、Subjob、Run 和 Subagent 不进入 Task Center，也不成为其他可导航 UI 对象。
|
||||
- [ ] Task 消息可以通过 `taskId`、`jobId` 和 `runId` 追溯来源。
|
||||
- [ ] 并行 Job 不直接无序写入 Conversation。
|
||||
- [ ] 取消和权限范围能够沿层级正确传播。
|
||||
@@ -0,0 +1,120 @@
|
||||
# Task Center PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | Scheduled Task 首期已实现；Goal/Event Task 与完整操作待实施 |
|
||||
| 版本 | 0.3 |
|
||||
| 日期 | 2026-08-19 |
|
||||
| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) |
|
||||
| 界面归属 | [通用助手工作栏与执行空间](../assistant-workbar/prd.md) |
|
||||
|
||||
## 1. 产品定义
|
||||
|
||||
Task Center 是所有产品级 Task 的应用级单例索引，不是 Automation Center，也不复制
|
||||
Conversation 内容。点击条目打开其关联 Conversation，并定位或展开对应 Task。
|
||||
|
||||
每个 Task 只关联一条 Conversation；一条 Conversation 可以关联零个、一个或多个 Task。
|
||||
Conversation 不因为关联 Task 而改变对象类型。
|
||||
|
||||
## 2. 收录边界
|
||||
|
||||
收录：
|
||||
|
||||
- 用户明确创建或确认的 Task。
|
||||
- Scheduled Task、Event Task 和 Goal Task。
|
||||
- 未来由用户确认创建的其他顶层 Task。
|
||||
|
||||
不收录：
|
||||
|
||||
- 没有显式 Task 关联的普通 Conversation。
|
||||
- 普通模型请求或工具调用产生的内部执行记录。
|
||||
- Job、Subjob、Run、工具步骤或 Subagent。
|
||||
- Smart Heartbeat 配置、报告和建议。
|
||||
- 仅用于审计的活动记录。
|
||||
|
||||
当前产品 UI 的对象层级止于 Task。Task Center、左侧会话列表和 Conversation 任务区都不显示
|
||||
Job/Subjob/Run 树、独立详情或路由。
|
||||
|
||||
## 3. 列表信息
|
||||
|
||||
每条 Task 至少显示：
|
||||
|
||||
- 名称和 Global / Project 范围。
|
||||
- 关联 Conversation 标题。
|
||||
- Task 类型和触发来源。
|
||||
- Ask / Execute 模式。
|
||||
- 当前聚合状态。
|
||||
- 最近一次面向用户的进展。
|
||||
- 最近活动时间。
|
||||
- 等待审批、失败或需要关注状态。
|
||||
- 下次计划时间（如适用）。
|
||||
|
||||
Task 行只显示聚合后的用户状态，不要求用户理解内部 Job/Run。
|
||||
|
||||
## 4. 交互
|
||||
|
||||
- 点击条目打开关联 Conversation，并定位到该 Task。
|
||||
- 支持按需要关注、进行中、已暂停、已结束筛选。
|
||||
- 支持立即运行、暂停、恢复、取消、编辑和删除。
|
||||
- 后台变化更新状态和徽标，不自动抢占当前页面。
|
||||
- 立即运行、重试和恢复在 UI 上都是 Task 操作，内部 Job/Run 不单独显示。
|
||||
- 完整消息留在 Conversation；工具、审批和错误可以在活动或 Runtime 中按 Task 查看；
|
||||
独立交付物在成果中查看。
|
||||
|
||||
## 5. 左侧 Conversation Task 列表
|
||||
|
||||
左侧最近会话列表承担轻量 Task 发现，不替代 Task Center：
|
||||
|
||||
```text
|
||||
▾ 产品发布讨论 10:24
|
||||
|
||||
每周进度总结 每周 · Execute · 等待中 ●
|
||||
发布前检查 单次 · Execute ✓
|
||||
```
|
||||
|
||||
- 无 Task 的 Conversation 保持现有单行样式。
|
||||
- 有 Task 时在行最左侧显示独立展开按钮；父会话行不重复显示任务标签或数量。
|
||||
- 更新时间默认靠近行右侧，更多操作按钮不常驻占位；悬停会话行时，按钮替换右侧时间显示。
|
||||
键盘焦点进入会话行或操作菜单展开时，按钮仍保持可见。会话标题溢出时保持右侧区域固定，
|
||||
并在自身裁切区域内横向滑动展示完整名称。未溢出标题不滑动，减少动态效果偏好下使用完整
|
||||
标题提示而不产生位移。
|
||||
- 展开后每个 Task 子项左侧显示名称，右侧显示本地化的模式、计划和状态标记，与父会话
|
||||
更新时间对齐；已完成使用带勾成功点并将文案保留给辅助技术。列表不显示 Job、Subjob、
|
||||
Run 或工具步骤。
|
||||
- 点击 Conversation 标题打开聊天；点击 Task 打开同一 Conversation 并定位该 Task。
|
||||
- 新建 Task 后首次自动展开；用户手动折叠后保持选择。
|
||||
- 后台状态变化不强制展开；Task 状态持续显示在展开后的子项和 Task Center 中。
|
||||
- 默认最多显示 3 个 Task；“查看全部 N 个任务”打开该 Conversation 的完整任务区。
|
||||
|
||||
## 6. Conversation 任务区
|
||||
|
||||
包含 Task 的 Conversation 顶部显示可折叠任务区：
|
||||
|
||||
```text
|
||||
本会话有 2 个任务
|
||||
[每周进度总结] [发布前检查] [管理任务]
|
||||
```
|
||||
|
||||
选择 Task 后显示名称、模式、聚合状态、计划、下次执行、最近结果和 Task 级操作。工具、审批、
|
||||
错误和成果通过 Task 关联显示，但不暴露 Job/Run 层级。
|
||||
|
||||
## 7. 删除关系
|
||||
|
||||
- 删除 Schedule 只停止后续触发，不删除 Task、Conversation 或历史。
|
||||
- 删除 Task 停止其计划并移除关联，默认保留 Conversation 和既有消息。
|
||||
- 删除最后一个 Task 后，左侧 Conversation 的展开按钮消失。
|
||||
- 删除 Conversation 前必须显示关联 Task 数量，并先停止或结算活动执行。
|
||||
|
||||
## 8. 验收标准
|
||||
|
||||
- [x] Task Center 只展示产品级 Task。
|
||||
- [x] 一条 Conversation 可以关联并展开多个 Task。
|
||||
- [x] 点击 Task 打开正确 Conversation 并定位到对应 Task。
|
||||
- [x] 左侧会话列表通过独立展开按钮显示带任务图标和本地化摘要的 Task 子项。
|
||||
- [x] 当前 UI 不显示 Job/Subjob/Run 树或独立页面。
|
||||
- [x] Scheduled Task 显示下次时间，但每次触发不新增 Task 条目。
|
||||
- [x] 普通模型请求和工具调用不会误显示为 Task。
|
||||
- [ ] 删除 Task 默认保留 Conversation 和既有消息。
|
||||
- [x] Smart Heartbeat 不进入 Task Center。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 微信消息通道
|
||||
|
||||
微信消息通道负责将微信连接、项目、工作目录、Runtime 和工作模式接入 GoodBuddy。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [微信 ClawBot 通道 PRD](./prd.md) | 通道连接、项目绑定、消息处理和验收 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
@@ -0,0 +1,794 @@
|
||||
# 远程消息通道项目与微信 ClawBot 集成 PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 已实施，待真实微信账号联调 |
|
||||
| 版本 | 1.4 |
|
||||
| 日期 | 2026-08-09 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 首期范围 | 微信 ClawBot、企业微信、钉钉的通道项目；微信文字、图片和文件 Ask 与 Execute |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
GoodBuddy 已将企业微信、钉钉和微信 ClawBot 远程消息通道纳入系统管理的通道项目。该信息架构解决了早期通道仅存在于设置页和后台服务中，远程消息进入任务系统后无法持续、明确识别以下信息的问题：
|
||||
|
||||
1. 消息来自哪个平台。
|
||||
2. 当前正在与哪个发送者或群聊对话。
|
||||
3. 远程执行任务使用哪个工作目录。
|
||||
4. 执行请求、处理后端、工具调用和结果归属于哪个范围。
|
||||
|
||||
腾讯官方微信 ClawBot 使用扫码授权，不使用 App ID 或 Secret，并由本机独立 Sidecar 持续运行通信服务。文字、图片和文件收发、Ask 只读对话与 Execute 完整授权已经实现；真实微信账号的认证媒体端到端联调仍作为发布前手动验收。
|
||||
|
||||
为避免把通道来源、发送者身份和执行范围混在一起，本功能使用“通道项目 + 远程会话”的两级结构：
|
||||
|
||||
- 通道项目标识平台并确定默认工作目录、处理后端和默认模式。
|
||||
- 远程会话标识具体发送者或群聊。
|
||||
- 消息记录具体发送者和本次实际使用的模式。
|
||||
- 运行记录覆盖任务执行、工具调用和结果。
|
||||
|
||||
## 2. 已确认的产品决策
|
||||
|
||||
1. 微信 ClawBot、企业微信、钉钉分别对应一个系统管理的通道项目。
|
||||
2. 三个通道项目在通道设置服务初始化时幂等创建，不等待用户完成连接配置。
|
||||
3. Renderer 不直接创建通道项目。Main 进程保证项目存在，设置卡片首次展示时即可引用对应项目。
|
||||
4. 通道项目默认根目录为当前操作系统用户目录。
|
||||
5. 同一通道中的不同私聊用户或群聊分别建立独立远程会话。
|
||||
6. 微信 ClawBot 首期支持个人微信私聊中的文字、图片和文件；语音和视频后续支持。
|
||||
7. 微信卡片可以配置默认“对话”或“执行”模式。
|
||||
8. “对话”映射为 GoodBuddy `Ask`；“执行”映射为 `Execute`。
|
||||
9. 每个通道项目默认使用“模型连接”中的默认直连文本模型，也可以显式选择其他直连文本模型、OpenCode 或 Continue。选择 OpenCode/Continue 时，通道只保存 Runtime 类型，并在每次远程请求开始时动态跟随“Agent Runtime”中的对应全局配置，不维护第二套模型来源或 Runtime 配置。
|
||||
10. 远程 Execute 不显示通道专属请求级或逐工具确认；收到合法消息后立即按所选后端运行。
|
||||
11. 任务仍受工作目录上下文、Runtime 能力、Ask/Execute 边界、能力开关、直连模型工具安全策略和活动审计约束；Agent Runtime 工具使用当前用户权限。
|
||||
12. 停用或断开通道不得删除通道项目、远程会话、任务、活动或成果历史。
|
||||
13. 通道项目由系统管理，用户不能永久删除；用户可以修改其工作目录、处理后端和默认模式。
|
||||
|
||||
## 3. 目标
|
||||
|
||||
### 3.1 用户目标
|
||||
|
||||
- 在项目切换器中一眼识别微信、企业微信和钉钉来源。
|
||||
- 在通道项目中区分不同发送者和群聊。
|
||||
- 在设置卡片中完成连接、启停、处理后端、模式和工作目录配置。
|
||||
- 通过微信进行 Ask 只读问答或发起 Execute 任务。
|
||||
- 选择可信的执行后端，并查看完整执行记录。
|
||||
- 保留通道关闭前后的历史上下文和审计记录。
|
||||
|
||||
### 3.2 产品目标
|
||||
|
||||
- 将远程通道纳入 GoodBuddy 现有 Project、Conversation、Task、Activity 和 Artifact 信息架构。
|
||||
- 复用现有 ChannelService 的白名单、去重、并发、取消和错误脱敏能力；回复长度与分段由各通道适配器按平台能力控制。
|
||||
- 保持 Electron Main、Preload、Renderer 和不可信子进程之间的安全边界。
|
||||
- 为后续语音、视频、多账号和更多通道提供稳定扩展点。
|
||||
|
||||
## 4. 非目标
|
||||
|
||||
首期不包含：
|
||||
|
||||
- 微信群聊。
|
||||
- 微信语音和视频收发。
|
||||
- 多个个人微信账号同时绑定。
|
||||
- 通过微信临时扩大工具权限或安全策略。
|
||||
- 主动群发、营销消息或任意联系人发现。
|
||||
- 将微信会话自动合并进普通本地会话。
|
||||
- 删除或迁移现有企业微信、钉钉历史数据。
|
||||
- 把完整 OpenClaw Runtime 打包进 GoodBuddy。
|
||||
|
||||
## 5. 信息架构
|
||||
|
||||
### 5.1 项目分组
|
||||
|
||||
项目选择器使用富信息单选菜单，不使用只显示项目名称的原生 `select`。当前区分“本地项目 / 远程通道”；未来出现真正的远程项目时，应新增独立分组，不把通道提前命名为远程项目：
|
||||
|
||||
```text
|
||||
本地项目
|
||||
├─ 默认项目
|
||||
└─ 用户创建的其他项目
|
||||
|
||||
远程通道
|
||||
├─ 微信 ClawBot
|
||||
├─ 企业微信
|
||||
└─ 钉钉
|
||||
```
|
||||
|
||||
选择器收起时显示当前项目名称；展开后每个选项至少显示项目名称和项目类型。本地项目补充目录摘要，远程通道项目补充平台来源和默认目录；接入可复用的通道状态数据后继续补充文字连接状态。未来接入其他远程项目时可以补充远程主机、工作区或服务来源，而不改变菜单的基本结构。
|
||||
|
||||
每个通道项目持续显示连接状态：
|
||||
|
||||
- 未配置
|
||||
- 已停用
|
||||
- 正在连接
|
||||
- 等待扫码
|
||||
- 已连接
|
||||
- 连接失败
|
||||
|
||||
通道状态不得只通过颜色表达。
|
||||
|
||||
### 5.2 项目、会话和消息关系
|
||||
|
||||
```text
|
||||
通道项目
|
||||
└─ 远程会话
|
||||
└─ 消息
|
||||
└─ 可选任务 / 活动 / 成果
|
||||
```
|
||||
|
||||
职责划分：
|
||||
|
||||
| 层级 | 负责内容 |
|
||||
| --- | --- |
|
||||
| 通道项目 | 平台、连接状态、默认根目录、处理后端、默认模式 |
|
||||
| 远程会话 | 平台账号、私聊用户或群聊、连续上下文 |
|
||||
| 消息 | 具体发送者、本次实际模式、正文、时间和处理状态 |
|
||||
| 运行记录 | Runtime、工具调用、执行结果和错误 |
|
||||
|
||||
### 5.3 会话命名
|
||||
|
||||
- 微信 ClawBot：优先使用已绑定用户昵称；不可用时显示“我的微信”。
|
||||
- 企业微信私聊：优先使用平台显示名，否则显示脱敏发送者 ID。
|
||||
- 钉钉私聊：优先使用平台显示名，否则显示脱敏发送者 ID。
|
||||
- 群聊：使用群名称；每条消息仍显示具体发送者。
|
||||
- 不得把原始 Token、上下文令牌或完整敏感标识作为会话标题。
|
||||
|
||||
## 6. 通道项目生命周期
|
||||
|
||||
### 6.1 自动创建
|
||||
|
||||
应用初始化通道设置服务时，Main 进程执行 `ensureChannelProjects()`：
|
||||
|
||||
1. 按稳定通道标识查找 `weixin`、`wecom`、`dingtalk` 对应项目。
|
||||
2. 缺失时创建系统管理项目。
|
||||
3. 已存在时复用，不重复创建。
|
||||
4. 如果存在同名普通项目，不得按名称占用或修改该项目。
|
||||
5. 创建失败时保留其他通道可用，并在设置快照中返回有界错误。
|
||||
|
||||
默认值：
|
||||
|
||||
| 通道 | 项目名称 | 根目录 | 处理后端 | 默认模式 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `weixin` | 微信 ClawBot | 用户目录 | 默认直连文本模型 | Ask |
|
||||
| `wecom` | 企业微信 | 用户目录 | 默认直连文本模型 | Ask |
|
||||
| `dingtalk` | 钉钉 | 用户目录 | 默认直连文本模型 | Ask |
|
||||
|
||||
### 6.2 系统管理约束
|
||||
|
||||
- 通道项目不能从普通项目危险区永久删除。
|
||||
- 停用通道不归档项目。
|
||||
- 断开微信不删除项目和历史。
|
||||
- 数据迁移或异常导致项目缺失时，下次初始化自动修复。
|
||||
- 用户可以修改项目根目录、描述、处理后端和默认模式。
|
||||
- 项目名称首期由系统管理，避免来源名称被改到不可识别；后续如允许自定义，必须持续显示通道徽标。
|
||||
|
||||
### 6.3 默认用户目录
|
||||
|
||||
通道项目默认使用操作系统用户目录。设置卡片必须显示完整目录，并在首次启用 Execute 时明确说明该范围可能包含桌面、下载、文档和其他私人文件。
|
||||
|
||||
如果根目录不存在、不可访问或不是目录：
|
||||
|
||||
- Ask 仍可在不读取本地文件的边界内工作。
|
||||
- Execute 不得启动。
|
||||
- 设置卡片显示就近错误和“选择目录”操作。
|
||||
|
||||
## 7. 设置页产品需求
|
||||
|
||||
### 7.1 导航
|
||||
|
||||
设置页标签由“企业通信”改为：
|
||||
|
||||
- 标题：消息通道
|
||||
- 说明：微信 ClawBot、企业微信与钉钉
|
||||
|
||||
### 7.2 卡片通用结构
|
||||
|
||||
三个通道使用与模型设置一致的分段外观页签，并保留
|
||||
`tablist`、`tab`、`tabpanel`、游标焦点和方向键语义。每次只显示一个
|
||||
通道面板，窄窗口下页签单行横向滚动。
|
||||
|
||||
每个通道面板包含：
|
||||
|
||||
1. 通道名称和连接状态。
|
||||
2. 启用开关。
|
||||
3. 默认工作目录。
|
||||
4. 消息处理后端。
|
||||
5. 默认处理模式。
|
||||
6. 对应通道项目。
|
||||
7. 平台特有的连接配置。
|
||||
8. 最近错误或连接状态。
|
||||
|
||||
示意：
|
||||
|
||||
```text
|
||||
微信 ClawBot 已连接
|
||||
|
||||
已绑定账号：微信用户 ****8a3f
|
||||
最近收到消息：今天 14:32
|
||||
|
||||
启用微信通道 [开关]
|
||||
|
||||
默认处理模式
|
||||
[ 对话 ] [ 执行 ]
|
||||
|
||||
默认工作目录
|
||||
C:\Users\用户名 [选择目录]
|
||||
|
||||
消息处理后端
|
||||
[默认模型 · sonnet-5 v]
|
||||
|
||||
通道项目
|
||||
微信 ClawBot
|
||||
|
||||
[断开本机绑定（危险操作）]
|
||||
```
|
||||
|
||||
“对话 / 执行”是互斥状态，应使用语义化分段控件，不使用两个独立复选框。
|
||||
|
||||
### 7.3 模式说明
|
||||
|
||||
- 对话：只读回答，不调用工具或修改内容。
|
||||
- 执行：收到合法消息后立即交给所选后端，可在工作目录内调用已启用工具。
|
||||
|
||||
每个通道面板持续显示风险说明，不弹出一次性确认。默认 Ask 时也要说明白名单
|
||||
发送者仍可通过 `/execute` 临时执行：
|
||||
|
||||
```text
|
||||
远程消息可能要求 GoodBuddy 读取或修改默认工作目录中的内容。
|
||||
执行消息会立即交给所选后端，不再逐次弹窗确认。
|
||||
请只连接可信账号，并将工作目录限制在必要范围。
|
||||
|
||||
默认工作目录：
|
||||
C:\Users\用户名
|
||||
```
|
||||
|
||||
### 7.4 消息处理后端
|
||||
|
||||
每个通道项目提供相同的后端选择，不提供含义不明确的“自动”选项：
|
||||
|
||||
- 直连模型：默认选择“模型连接”中的默认文本连接；列出已配置的文本模型连接，不列出仅支持图像生成的连接。
|
||||
- OpenCode：使用当前 OpenCode Runtime，并动态跟随“Agent Runtime”中的全局 OpenCode 模型来源、自有配置、程序路径和服务地址。
|
||||
- Continue：使用当前 Continue Runtime，并动态跟随“Agent Runtime”中的全局 Continue 模型来源、自有配置和程序路径。
|
||||
|
||||
选择持久化在通道项目上。旧版本保存的 `auto` 选择在启动时迁移为当前默认
|
||||
直连文本模型。模型连接删除、改为图片模型或凭据失效后，优先修复为默认或
|
||||
首个可用文本模型；没有可用文本模型时，UI 明确提示用户完成模型配置或改选
|
||||
Agent Runtime。OpenCode/Continue 的通道项目只持久化 `provider`，旧版残留的
|
||||
通道级 `profileId` 在修复时移除；全局 Agent Runtime 配置变更从下一条远程
|
||||
请求开始生效。远程会话记录通道项目的逻辑后端选择，不复制全局配置或凭据。
|
||||
Execute 启动前检查解析后的后端是否支持工具执行，并返回可处理的配置错误。
|
||||
|
||||
通道面板的后端说明必须明确显示“跟随 Agent Runtime 全局配置”，不得在消息
|
||||
通道设置中重复展示 OpenCode/Continue 的模型来源、自有配置文件或程序路径。
|
||||
“Agent Runtime > 高级设置”中的来源选项、条件配置卡和后续路径字段保持
|
||||
`12px` 区块间距，不能出现卡片边框贴合或内容归属不清。
|
||||
|
||||
### 7.5 通道项目会话界面
|
||||
|
||||
通道项目是系统管理的远程消息范围，不允许创建普通本地会话：
|
||||
|
||||
- 切换到通道项目时，只显示由对应客户端消息创建的远程会话。
|
||||
- 隐藏“新建对话”和 `Ctrl+N` 提示；收到全局新建会话命令时不创建记录。
|
||||
- 尚无远程会话时显示等待首条客户端消息的空状态和设置入口。
|
||||
- 旧版本误建在通道项目中的普通本地会话不参与通道会话列表，但保留其数据。
|
||||
- 远程会话底部说明客户端联动方式，只显示历史、任务和执行结果，不再提及已移除的审批流程。
|
||||
- “运行记录”的“任务与会话”视图按“项目 → 任务或会话 → 活动详情”显示远程任务；所有任务或会话首次进入时默认收起，用户可通过原生展开控件查看明细。综合状态以最近一次顶层请求对应的最终 Agent 结果为准，最终结果尚未产生时使用请求当前状态；中间工具或子专家的失败、取消和中断不得覆盖最终成功状态。
|
||||
|
||||
### 7.6 微信扫码绑定
|
||||
|
||||
未绑定时显示“绑定个人微信”。扫码对话框包含：
|
||||
|
||||
- 本地渲染的二维码。
|
||||
- 扫码和手机确认步骤。
|
||||
- 二维码剩余有效时间。
|
||||
- 刷新和取消操作。
|
||||
- 等待扫码、已扫描、需要验证码、已连接、已过期和失败状态。
|
||||
|
||||
二维码过期时不得继续接受旧扫码结果。
|
||||
|
||||
需要配对数字时，在同一对话框中显示验证码输入。验证码不得写入日志或持久化。
|
||||
|
||||
绑定完成后显示“重新绑定”和“断开本机绑定”。“断开本机绑定”使用共享红色
|
||||
危险操作样式，并持续说明该操作只清除本机凭据、不保证解除微信服务端授权，
|
||||
也不删除通道项目、远程会话、任务、活动或成果历史。
|
||||
|
||||
### 7.7 企业微信和钉钉
|
||||
|
||||
企业微信和钉钉继续使用现有凭据表单、环境变量只读覆盖和连接测试，但增加：
|
||||
|
||||
- 通道项目显示。
|
||||
- 消息处理后端。
|
||||
- 默认处理模式。
|
||||
- 默认工作目录。
|
||||
- 打开通道项目。
|
||||
|
||||
现有发送者白名单和群聊提及设置继续有效。
|
||||
|
||||
## 8. 远程会话需求
|
||||
|
||||
### 8.1 会话创建与复用
|
||||
|
||||
收到合法消息后，根据以下稳定键查找会话：
|
||||
|
||||
```text
|
||||
channel + accountId + externalConversationId
|
||||
```
|
||||
|
||||
- 未找到时，在对应通道项目下创建远程会话。
|
||||
- 已找到时继续使用现有会话。
|
||||
- 微信私聊的 `externalConversationId` 首期可由绑定账号和发送者稳定标识组成。
|
||||
- 不得仅按显示名称匹配会话。
|
||||
- 消息重试不得创建重复会话或重复任务。
|
||||
|
||||
### 8.2 新建上下文
|
||||
|
||||
首期不提供手动“新建远程会话”入口，也不把通道项目中的全局“新建对话”
|
||||
命令转为本地会话。客户端首条合法消息按稳定键自动创建远程会话，后续消息
|
||||
继续复用该会话；未来如增加远程上下文重置命令，需要单独定义协议、去重和
|
||||
历史保留语义。
|
||||
|
||||
### 8.3 展示
|
||||
|
||||
最近对话和聊天标题区显示：
|
||||
|
||||
- 通道图标和名称。
|
||||
- 私聊用户或群聊名称。
|
||||
- 当前连接状态。
|
||||
- 默认模式。
|
||||
- 未读状态。
|
||||
|
||||
每条远程消息记录实际模式：
|
||||
|
||||
- Ask
|
||||
- Execute
|
||||
- 执行中
|
||||
- 已完成
|
||||
- 失败
|
||||
|
||||
收到普通远程消息时不得强制切换当前页面。应增加未读标记和全局通知。
|
||||
|
||||
## 9. Ask 与 Execute
|
||||
|
||||
### 9.1 模式解析
|
||||
|
||||
每条消息的模式按以下优先级确定：
|
||||
|
||||
1. 显式 `/ask` 或“对话：”前缀使用 Ask。
|
||||
2. 显式 `/execute`、`/exec` 或“执行：”前缀使用 Execute。
|
||||
3. 没有前缀时使用通道项目的默认模式。
|
||||
|
||||
前缀仅用于选择模式，不进入发送给模型的正文。
|
||||
|
||||
### 9.2 Ask
|
||||
|
||||
- 在 Runtime 边界保持只读。
|
||||
- 不提供工具授权回调，或所有工具请求返回拒绝。
|
||||
- 不修改文件、数据库、系统状态或远程状态。
|
||||
- 结果以有界文字返回原通道并写入远程会话。
|
||||
|
||||
### 9.3 Execute
|
||||
|
||||
Execute 消息通过身份、长度、去重和并发检查后：
|
||||
|
||||
1. 创建并立即启动远程执行任务。
|
||||
2. 使用通道项目当前保存的逻辑处理后端；OpenCode/Continue 在此时解析“Agent Runtime”中的对应全局配置。
|
||||
3. 将项目根目录作为本次 Runtime 工作目录。
|
||||
4. 所选后端不支持工具执行时，不启动任务，并返回设置修复说明。
|
||||
|
||||
远程 Execute 不创建 GoodBuddy 通道专属请求确认或逐工具确认。安全边界由
|
||||
发送者白名单、私聊限制、项目根目录上下文、所选 Runtime、工作模式边界、能力开关和工具
|
||||
安全策略共同提供。UI 必须持续说明该行为，不能让用户误以为仍会弹窗确认。
|
||||
通道只回传最终结果或可操作的失败信息，不发送“执行已开始”等无操作价值的
|
||||
中间状态消息。
|
||||
|
||||
### 9.4 工具控制
|
||||
|
||||
不同后端按现有行为运行：
|
||||
|
||||
- OpenCode 和 Continue 使用各自的工具系统与能力检查，并以 GoodBuddy 客户端当前用户权限运行。
|
||||
- 直连模型只可调用已启用的内置工作区工具及已分配 MCP 工具。
|
||||
- “Execute 自动授权已启用的工具”策略无需逐次确认；“禁止所有工具执行”策略拒绝所有直连模型工具调用。
|
||||
- 平台不提供 Runtime OS 沙箱模式；Ask 的只读边界和各 Runtime 工具策略继续有效。
|
||||
- 任何工具结果都进入现有任务和活动审计。
|
||||
|
||||
### 9.5 结果回传
|
||||
|
||||
- 成功：回传有界文字结果。
|
||||
- 当前任务生成的图片可以随最终结果回传；用户明确要求文件时，将当前任务的
|
||||
有界文本结果生成为 Markdown 附件。
|
||||
- 失败：回传经过脱敏、长度受限的用户可处理错误。
|
||||
- 取消：回传“任务已取消”。
|
||||
- 结果投递失败时保留发件箱记录并显示通道错误，不重复执行任务。
|
||||
- 发件箱达到五次投递尝试后进入可查询的终止状态，并继续通过现有通道错误回调
|
||||
暴露；终止记录不再发送，也不会从未投递查询中静默消失。
|
||||
|
||||
### 9.6 媒体与文件
|
||||
|
||||
- 单条微信消息最多接收或发送 4 个附件，解密后合计不超过 12MB。
|
||||
- 入站仅处理官方图片和文件消息项。Sidecar 下载腾讯 CDN 内容并完成
|
||||
AES-128-ECB 解密，Main 只接收有界字节、文件名、MIME 和大小。
|
||||
- 图片进入现有视觉上下文；文本、代码、PDF 和 Office 文件进入现有不可信
|
||||
文档上下文。不支持的类型显示可处理提示，不把原始 CDN 地址或密钥传给 Runtime。
|
||||
- 入站附件元数据和有界预览写入远程会话，原始字节作为任务处理期间的临时上下文。
|
||||
- 出站生成图片必须来自当前任务的 `generated-image` 事件。
|
||||
- 出站文件只能由 Main 根据当前任务的最终文本结果生成，不接受 Runtime 路径，
|
||||
不读取或发送任意现有工作区文件。
|
||||
- 媒体发件箱在成功投递或达到重试上限后清除二进制负载。
|
||||
|
||||
## 10. 微信 ClawBot 通信架构
|
||||
|
||||
### 10.1 进程边界
|
||||
|
||||
微信通信运行在独立 Node Sidecar 中：
|
||||
|
||||
```text
|
||||
微信
|
||||
↕ 腾讯 iLink HTTPS / CDN
|
||||
微信 Sidecar
|
||||
↕ 严格、有界、可验证的进程协议
|
||||
Main ChannelDriver
|
||||
↕
|
||||
ChannelService
|
||||
↕
|
||||
GoodBuddy Runtime 与工具安全策略
|
||||
```
|
||||
|
||||
禁止：
|
||||
|
||||
- 在 Renderer 中加载微信通信代码。
|
||||
- 向 Renderer 暴露 Token、上下文令牌或原始腾讯响应。
|
||||
- 把腾讯插件直接加载进 Electron Main。
|
||||
- 运行 `openclaw-weixin-cli` 安装器。
|
||||
- 仅为微信通道打包完整 OpenClaw。
|
||||
|
||||
### 10.2 Sidecar 能力
|
||||
|
||||
- 获取和刷新二维码。
|
||||
- 轮询扫码状态。
|
||||
- 提交一次性验证码。
|
||||
- 加载内存中的加密解封凭据。
|
||||
- 长轮询文字、图片和文件消息。
|
||||
- 从腾讯 CDN 有界下载并解密图片和文件。
|
||||
- 调用 `getuploadurl`，加密上传当前任务图片和文件，并发送媒体回复。
|
||||
- 保持会话 `context_token` 和同步游标。
|
||||
- 有界重试、退避、停止和异常退出。
|
||||
|
||||
### 10.3 协议扩展
|
||||
|
||||
现有 `wechat-sidecar-protocol.ts` 需要拆分为两个方向：
|
||||
|
||||
Sidecar 到 Main：
|
||||
|
||||
- `status`
|
||||
- `qr`
|
||||
- `verification_required`
|
||||
- `connected`
|
||||
- `inbound_message`，可包含有界图片或文件
|
||||
- `reply_result`
|
||||
- `fatal_error`
|
||||
|
||||
Main 到 Sidecar：
|
||||
|
||||
- `start_login`
|
||||
- `submit_verification`
|
||||
- `start_account`
|
||||
- `reply`，可包含有界图片或文件
|
||||
- `cancel_reply`
|
||||
- `disconnect`
|
||||
- `shutdown`
|
||||
|
||||
所有消息使用严格 Zod Schema、版本号、最大长度和关联 ID。协议拒绝未知字段。Token、Cookie、Session 和上下文令牌不得出现在普通状态或消息事件中。
|
||||
|
||||
## 11. 凭据与网络安全
|
||||
|
||||
### 11.1 凭据
|
||||
|
||||
- 微信 bot token 使用 Electron `safeStorage` 加密后保存在 Main 管理的设置文件。
|
||||
- 上下文令牌由 Sidecar 运行时持有；如需跨重启保存，必须由 Main 加密持久化。
|
||||
- 凭据不得出现在命令行参数、普通环境变量、stdout、Renderer IPC、通知或错误消息中。
|
||||
- Sidecar 通过私有继承管道接收本次运行所需凭据。
|
||||
- 安全存储不可用时不能完成微信绑定或启用通道。
|
||||
|
||||
### 11.2 网络
|
||||
|
||||
- 扫码入口固定为已审核的腾讯 HTTPS 主机。
|
||||
- 服务端返回的 API 主机和重定向主机必须通过腾讯主机允许列表验证后才能携带 Token 请求。
|
||||
- 不允许明文 HTTP 发送微信凭据。
|
||||
- 全局“内网兼容模式”不得放宽微信凭据端点的 HTTPS 和主机验证。
|
||||
- Sidecar 使用独立环境允许列表并显式启用证书验证，不继承
|
||||
`NODE_TLS_REJECT_UNAUTHORIZED=0`、代理变量、Node 加载钩子或提供商凭据。
|
||||
- 日志中的 URL 移除查询字符串，响应体对 Token 和上下文令牌脱敏。
|
||||
- 媒体下载和上传只允许腾讯微信 HTTPS 主机，所有重定向逐跳重新校验。
|
||||
- CDN 响应按流读取并在解密前后分别执行硬字节限制，不信任 `Content-Length`、
|
||||
文件名、MIME、扩展名或服务端声明的原始大小。
|
||||
|
||||
### 11.3 断开与解绑
|
||||
|
||||
产品区分：
|
||||
|
||||
- 停用：停止收发，保留本地绑定凭据。
|
||||
- 断开本机绑定：停止收发并清除本地凭据；入口使用红色危险操作样式。
|
||||
- 微信端解除绑定：只有腾讯提供并验证服务端撤销能力后才可承诺。
|
||||
|
||||
当前不得把本地清除描述为“已在微信端彻底解绑”。断开后保留通道项目、
|
||||
远程会话、任务、活动和成果历史。
|
||||
|
||||
## 12. 数据与契约建议
|
||||
|
||||
### 12.1 Project
|
||||
|
||||
为项目增加可向后兼容的来源字段：
|
||||
|
||||
```ts
|
||||
type ProjectKind = 'user' | 'channel'
|
||||
type ProjectChannel = 'weixin' | 'wecom' | 'dingtalk'
|
||||
```
|
||||
|
||||
通道项目包含：
|
||||
|
||||
- `kind: 'channel'`
|
||||
- `channel`
|
||||
- `runtimeSelection`
|
||||
- 稳定且唯一的通道绑定
|
||||
|
||||
现有项目迁移为 `kind: 'user'`。不得通过项目名称推断通道。
|
||||
|
||||
### 12.2 Conversation
|
||||
|
||||
增加远程会话映射，至少包含：
|
||||
|
||||
- `conversationId`
|
||||
- `projectId`
|
||||
- `channel`
|
||||
- `accountId`
|
||||
- `externalConversationId`
|
||||
- `conversationType`
|
||||
- 脱敏显示名
|
||||
- 创建和最近消息时间
|
||||
|
||||
唯一约束：
|
||||
|
||||
```text
|
||||
channel + accountId + externalConversationId
|
||||
```
|
||||
|
||||
### 12.3 Channel Settings
|
||||
|
||||
通道公开设置增加：
|
||||
|
||||
- `projectId`
|
||||
- `defaultWorkMode`
|
||||
- `runtimeSelection`
|
||||
- `rootPath`
|
||||
- `status`
|
||||
|
||||
微信私有设置增加加密字段：
|
||||
|
||||
- bot token
|
||||
- bot/account ID
|
||||
- 绑定用户 ID
|
||||
- 经验证的 API base URL
|
||||
|
||||
Renderer 快照只返回是否已配置和脱敏标识。
|
||||
|
||||
### 12.4 任务来源
|
||||
|
||||
远程任务保留：
|
||||
|
||||
- 通道项目 ID。
|
||||
- 远程会话 ID。
|
||||
- 通道。
|
||||
- 脱敏发送者。
|
||||
- 实际工作模式。
|
||||
- 实际消息处理后端。
|
||||
|
||||
任务队列可以复用 delegation 调度分类，但 UI 和活动审计必须依据通道项目与
|
||||
远程会话持续显示真实通道来源，不得呈现为普通本地任务。
|
||||
|
||||
## 13. IPC 与 Preload
|
||||
|
||||
建议增加窄接口：
|
||||
|
||||
- 获取通道设置快照。
|
||||
- 保存通道项目配置。
|
||||
- 开始微信扫码。
|
||||
- 刷新微信扫码。
|
||||
- 提交微信验证码。
|
||||
- 断开微信本地连接。
|
||||
- 订阅微信连接状态。
|
||||
- 打开对应通道项目。
|
||||
|
||||
所有 IPC：
|
||||
|
||||
- 使用共享 Zod Schema 验证。
|
||||
- 验证可信 Renderer sender。
|
||||
- 不接收 Renderer 提供的项目类型或通道身份作为可信事实。
|
||||
- 不返回凭据。
|
||||
|
||||
## 14. 关键异常流程
|
||||
|
||||
### 14.1 项目重名
|
||||
|
||||
存在名为“微信 ClawBot”的普通项目时，仍创建独立通道项目，并通过通道类型而非名称识别。UI 可以显示同名，但必须有“远程通道”分组和微信徽标。
|
||||
|
||||
### 14.2 通道项目缺失
|
||||
|
||||
如果数据库异常或旧版本操作导致绑定项目缺失，Main 初始化时重新创建并修复设置引用。历史会话无法安全迁移时保留原归属并给出诊断，不静默丢弃。
|
||||
|
||||
### 14.3 连接中退出
|
||||
|
||||
- 取消二维码轮询。
|
||||
- 清除内存验证码。
|
||||
- 停止 Sidecar。
|
||||
- 不保存未确认凭据。
|
||||
|
||||
### 14.4 执行期间断线
|
||||
|
||||
通道断开后不得启动新的 Execute。已开始的任务按现有取消策略处理，结果进入本地审计；恢复连接后不得自动重复执行。
|
||||
|
||||
### 14.5 重复消息
|
||||
|
||||
使用稳定平台消息 ID 去重。平台消息 ID 缺失时，使用账号、会话、发送者、时间和内容摘要构造有界稳定键。任务创建和回复必须共用同一个去重声明。
|
||||
|
||||
## 15. 可访问性与响应式
|
||||
|
||||
- 通道状态同时使用文字和图标。
|
||||
- 三个通道使用共享 `PageTabs` 的 `segmented` 外观，保留页签语义和方向键切换。
|
||||
- 模式选择使用语义化单选/分段控件和方向键。
|
||||
- 消息处理后端使用持久标签和分组选项，并说明当前选择的实际行为。
|
||||
- 二维码提供状态文字和备用刷新操作，但不把敏感二维码链接作为可复制文本。
|
||||
- 验证码错误与输入框建立 `aria-describedby` 关联。
|
||||
- 关闭对话框后焦点返回触发按钮。
|
||||
- 窄窗口下卡片单列，二维码对话框保留 16px 外边距。
|
||||
- 浅色、深色和 200% 文字缩放下可完成绑定、后端选择和保存。
|
||||
|
||||
## 16. 验收标准
|
||||
|
||||
### 16.1 通道项目
|
||||
|
||||
- [ ] 新安装首次启动后存在微信 ClawBot、企业微信和钉钉三个通道项目。
|
||||
- [ ] 重启应用不会重复创建通道项目。
|
||||
- [ ] 同名普通项目不会被占用或修改。
|
||||
- [ ] 通道项目默认根目录为当前用户目录，默认模式为 Ask。
|
||||
- [ ] 通道项目在项目选择器的“远程通道”分组中显示。
|
||||
- [ ] 项目选择器使用富信息单选菜单；每项显示项目名称和类型，本地项目显示目录摘要，远程通道显示平台来源与默认目录，并在可复用状态数据接入后显示文字连接状态。
|
||||
- [ ] 项目选择器的信息结构可扩展为“本地 / 远程”分组，不以图标或颜色作为项目来源和状态的唯一表达。
|
||||
- [ ] 停用或断开通道不会删除项目和历史。
|
||||
- [ ] 普通项目删除流程不能永久删除通道项目。
|
||||
|
||||
### 16.2 设置卡片
|
||||
|
||||
- [ ] 设置标签显示为“消息通道”。
|
||||
- [ ] 三个通道使用与模型设置一致的分段外观页签，并保留完整页签键盘语义。
|
||||
- [ ] 三个面板均显示项目、根目录、消息处理后端、默认模式和连接状态。
|
||||
- [ ] 微信卡片可以完成扫码、过期刷新、验证码和连接状态展示。
|
||||
- [ ] “断开本机绑定”使用共享红色危险操作样式，并明确说明只清除本机凭据、不删除历史或承诺服务端解绑。
|
||||
- [ ] 不显示“自动”后端；首次创建和旧版 `auto` 配置均落到默认直连文本模型。
|
||||
- [ ] 直连模型只列出文本连接，OpenCode 与 Continue 可直接选择。
|
||||
- [ ] 选择 OpenCode/Continue 时只保存 Runtime 类型，每次远程请求动态跟随“Agent Runtime”中的对应全局配置，通道页不出现第二套 Runtime 配置。
|
||||
- [ ] Agent Runtime 高级设置的来源选项、条件配置卡和路径字段之间保持 `12px` 间距且无横向溢出。
|
||||
- [ ] 默认 Execute 时持续显示目录范围和无逐次确认的风险说明。
|
||||
- [ ] Renderer 无法读取任何微信 Token 或上下文令牌。
|
||||
|
||||
### 16.3 会话
|
||||
|
||||
- [ ] 不同通道的消息进入不同通道项目。
|
||||
- [ ] 不同发送者或群聊进入独立远程会话。
|
||||
- [ ] 重复平台事件不会创建重复会话、消息或任务。
|
||||
- [ ] 最近对话、聊天标题和消息均能识别通道与发送者。
|
||||
- [ ] 收到普通消息不会强制切换当前页面。
|
||||
- [ ] 切换到通道项目不会创建普通本地会话。
|
||||
- [ ] 通道项目隐藏“新建对话”和 `Ctrl+N`，全局快捷命令也不创建会话。
|
||||
- [ ] 没有远程会话时显示等待客户端首条消息的空状态。
|
||||
- [ ] “运行记录”的任务或会话分组默认收起；综合状态使用最近一次顶层请求的最终 Agent 结果，中间工具或子专家失败不得覆盖最终成功状态。
|
||||
- [ ] 微信图片和文件显示在对应远程消息中，附件消息无需附带文字。
|
||||
- [ ] 支持的附件进入所选后端现有图片或文档上下文；不支持和超限附件返回明确提示。
|
||||
|
||||
### 16.4 Ask
|
||||
|
||||
- [ ] 普通消息默认按卡片配置进入 Ask。
|
||||
- [ ] Ask 在 Runtime 边界拒绝所有工具。
|
||||
- [ ] 有界结果回传原通道并写入远程会话。
|
||||
|
||||
### 16.5 Execute
|
||||
|
||||
- [ ] 默认 Execute 或显式执行前缀会立即使用通道项目所选后端。
|
||||
- [ ] 不显示通道专属请求级或逐工具确认。
|
||||
- [ ] 直连模型、OpenCode 和 Continue 均按各自能力正确路由。
|
||||
- [ ] 通道不发送“执行已开始”等中间占位消息，只发送最终结果或可操作失败。
|
||||
- [ ] 任务使用对应通道项目根目录。
|
||||
- [ ] Runtime、工作模式边界、能力和直连模型工具安全策略继续生效。
|
||||
- [ ] 任务、活动、工具、成果和最终结果关联到通道项目与远程会话。
|
||||
|
||||
### 16.6 生命周期与安全
|
||||
|
||||
- [ ] Sidecar 异常退出不会导致 Main 崩溃，并有有界重启限制。
|
||||
- [ ] 应用退出会取消长轮询并停止 Sidecar。
|
||||
- [ ] 微信凭据使用系统安全存储加密。
|
||||
- [ ] 任何普通日志、IPC、错误和通知中不存在凭据。
|
||||
- [ ] Token 只发送到已审核的腾讯 HTTPS 主机。
|
||||
- [ ] CDN 下载、上传和每次重定向只访问腾讯微信 HTTPS 主机。
|
||||
- [ ] 入站和出站媒体最多 4 个、合计不超过 12MB，AES 密钥和 CDN URL 不跨越 Sidecar 边界。
|
||||
- [ ] 只有当前任务生成图片或 Main 从本次最终文本生成的文件可以作为出站附件。
|
||||
|
||||
## 17. 实施阶段
|
||||
|
||||
### 阶段一：通道项目基础
|
||||
|
||||
- Project 数据迁移与通道类型。
|
||||
- 三个通道项目幂等创建。
|
||||
- 项目选择器“远程通道”分组。
|
||||
- 三张设置卡片接入项目、目录和模式配置。
|
||||
- 企业微信、钉钉消息建立独立远程会话。
|
||||
|
||||
### 阶段二：微信文字通道
|
||||
|
||||
- 微信 iLink Sidecar。
|
||||
- 扫码、验证码、加密凭据和生命周期。
|
||||
- 微信文字收发与稳定去重。
|
||||
- 微信远程会话。
|
||||
- Ask 模式。
|
||||
|
||||
### 阶段三：受控 Execute
|
||||
|
||||
- 通道项目处理后端选择与失效修复。
|
||||
- OpenCode/Continue 通道后端动态跟随全局 Agent Runtime 配置。
|
||||
- Execute Runtime 接入。
|
||||
- 直连模型工具安全策略和活动关联。
|
||||
- 结果回传、取消、超时和失败恢复。
|
||||
|
||||
### 阶段四：微信媒体
|
||||
|
||||
- 图片和文件 CDN 下载、AES 解密与有界上下文。
|
||||
- 生成图片和 Main 生成的任务结果文件加密上传与回复。
|
||||
- 远程会话附件展示和媒体发件箱清理。
|
||||
|
||||
### 阶段五：后续扩展
|
||||
|
||||
- 有界语音和视频。
|
||||
- 多微信账号。
|
||||
- 更细的项目路由。
|
||||
- 已验证的微信端解除绑定。
|
||||
|
||||
## 18. 测试要求
|
||||
|
||||
至少覆盖：
|
||||
|
||||
- 数据迁移和通道项目幂等创建。
|
||||
- 同名普通项目隔离。
|
||||
- 设置 Schema 与 Renderer 脱敏快照。
|
||||
- QR 状态机、过期、验证码和非法转换。
|
||||
- Sidecar 双向协议未知字段、超长字段和凭据泄漏拒绝。
|
||||
- 腾讯主机允许列表和重定向校验。
|
||||
- CDN 媒体 AES 加解密、流式大小限制、声明大小校验和恶意重定向拒绝。
|
||||
- 附件持久化展示、现有上下文接入、生成图片回传和任务成果目录隔离。
|
||||
- 消息去重、会话映射、并发和取消。
|
||||
- Ask 工具拒绝。
|
||||
- Execute 使用直连模型、OpenCode 和 Continue 的路由。
|
||||
- OpenCode/Continue 通道只保存 Runtime 类型，并在 Ask 与 Execute 开始时解析当前全局 Agent Runtime 配置。
|
||||
- Execute 不创建通道专属审批，直连模型禁止工具策略仍然生效。
|
||||
- 模型连接删除后的通道后端选择修复。
|
||||
- 发件箱投递失败不重复执行。
|
||||
- 项目选择器、分段页签、后端选择、设置面板和扫码对话框的键盘与无障碍行为。
|
||||
- Runtime 高级设置区块间距、微信断开危险按钮和任务活动默认折叠的 UI 回归。
|
||||
- Windows、macOS、Linux 的默认用户目录和 Sidecar 关闭行为。
|
||||
|
||||
实现完成后运行：
|
||||
|
||||
```text
|
||||
npm test
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm run build
|
||||
```
|
||||
|
||||
## 19. 发布条件
|
||||
|
||||
满足以下条件后才可默认向用户提供微信 Execute：
|
||||
|
||||
1. 微信文字 Ask 全流程稳定。
|
||||
2. UI 明确说明远程 Execute 会立即运行，且默认工作目录和处理后端始终可见。
|
||||
3. 凭据不会进入 Renderer、日志或普通子进程参数。
|
||||
4. Sidecar 网络目标和重定向已实施严格允许列表。
|
||||
5. 通道项目和远程会话的来源标识在所有入口持续可见。
|
||||
6. 任务重复投递不会导致重复执行。
|
||||
7. 应用退出、断线和更新过程中不会留下失控执行，直连模型禁止工具策略不能被远程来源绕过。
|
||||
8. 腾讯 iLink 独立宿主使用范围和本地断开语义已完成发布前确认。
|
||||
Reference in New Issue
Block a user