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
@@ -151,6 +151,22 @@ additional hardening beyond the actual internal-network threat model:
|
||||
- Keep UI accessible with labels, keyboard behavior, semantic roles, and visible
|
||||
focus states.
|
||||
|
||||
## Product Design Documentation
|
||||
|
||||
- Organize feature documentation by product feature under
|
||||
`docs/features/<feature-name>/`, not by document type.
|
||||
- Treat each feature directory's `README.md` as its documentation entry point.
|
||||
- Follow `docs/features/AGENTS.md` for required document responsibilities,
|
||||
naming, traceability, progress evidence, and migration rules.
|
||||
- Keep cross-feature architecture, quality protocols, development procedures,
|
||||
and product-wide roadmaps outside feature directories only when they cannot
|
||||
be owned by one feature.
|
||||
- Maintain one authoritative definition for each requirement, state rule, UI
|
||||
behavior, technical contract, and implementation fact. Link to it instead of
|
||||
duplicating it across documents.
|
||||
- Update the affected feature documents after functional changes. The
|
||||
implemented and validated production behavior is the final source of truth.
|
||||
|
||||
## UI Consistency
|
||||
|
||||
- Treat `UI-DESIGN.md` as the canonical UI design system. Read and follow it
|
||||
@@ -291,7 +307,7 @@ validation are not substitutes for this development-time check.
|
||||
to release time.
|
||||
|
||||
The detailed scenario rules are documented in
|
||||
[`docs/architecture/remote-host-and-goodbuddy-agent-design.md`](./docs/architecture/remote-host-and-goodbuddy-agent-design.md).
|
||||
[`docs/features/remote-host/technical-design.md`](./docs/features/remote-host/technical-design.md).
|
||||
|
||||
Before committing or pushing, inspect `git status`, `git diff`, and
|
||||
`git diff --cached`. Do not commit secrets, local databases, logs, generated
|
||||
|
||||
@@ -37,8 +37,9 @@ GoodBuddy是一个开箱即用的 AI 生产平台，安全、跨平台、本地
|
||||
|
||||
|
||||
|
||||
完整功能和路线图见 [FEATURES.md](FEATURES.md)，产品、架构、设计与质量文档见
|
||||
[文档导航](docs/README.md)。
|
||||
完整功能和路线图见 [FEATURES.md](FEATURES.md)，产品功能文档位于
|
||||
[`docs/features`](./docs/features/)，维护规范见
|
||||
[`docs/features/AGENTS.md`](./docs/features/AGENTS.md)。
|
||||
|
||||
## 安装
|
||||
|
||||
|
||||
+2
-2
@@ -314,9 +314,9 @@
|
||||
|
||||
助手工作栏是应用级右侧工具容器，不归属于聊天页面，也不根据当前页面、项目或 Runtime
|
||||
自动增删入口。产品契约见
|
||||
[通用助手工作栏与执行空间 PRD](./docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)，
|
||||
[通用助手工作栏与执行空间 PRD](./docs/features/assistant-workbar/prd.md)，
|
||||
动态 Tab、“+”和终端细节见
|
||||
[助手工作栏多终端页签 PRD](./docs/prd/assistant-experience/workbar-terminal-tabs-prd.md)。
|
||||
[助手工作栏多终端页签 PRD](./docs/features/assistant-workbar/terminal-tabs-prd.md)。
|
||||
|
||||
- 升级后默认打开任务中心、工作区、浏览器和成果四个单实例应用，不根据当前页面或 Runtime
|
||||
能力自动增删稳定应用目录入口。
|
||||
|
||||
@@ -1,57 +0,0 @@
|
||||
# GoodBuddy 文档导航
|
||||
|
||||
GoodBuddy 文档按“文档类型 → 功能域”组织。新增文档应先选择类型，再放入对应功能目录，
|
||||
避免继续把所有设计平铺到单一 `features` 目录。
|
||||
|
||||
## 产品需求
|
||||
|
||||
| 功能域 | 入口 |
|
||||
| --- | --- |
|
||||
| Task 与 Job | [Task 与 Job 总览](./prd/task-and-job/README.md) |
|
||||
| Smart Heartbeat | [智能心跳 PRD](./prd/smart-heartbeat/smart-heartbeat-prd.md) |
|
||||
| 助手工作栏 | [通用助手工作栏与执行空间 PRD](./prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md) |
|
||||
| 工作栏终端 | [助手工作栏多终端页签 PRD](./prd/assistant-experience/workbar-terminal-tabs-prd.md) |
|
||||
| 会话监督 | [会话监督 PRD](./prd/supervision/conversation-supervision-prd.md) |
|
||||
| 记忆 | [分区记忆 PRD](./prd/memory/partitioned-memory-prd.md) |
|
||||
| 并行实验 | [并行实验工作台 PRD](./prd/experiments/parallel-experiments-prd.md) |
|
||||
| 持续学习 | [持续学习与评估门 PRD](./prd/learning/continuous-learning-prd.md) |
|
||||
| 知识库 | [知识库检索与分块增强 PRD](./prd/knowledge/knowledge-rag-enhancement-prd.md) |
|
||||
| 文档处理 | [文档解析与本地 OCR](./prd/document-processing/document-extraction-and-local-ocr.md) |
|
||||
| 消息通道 | [微信 ClawBot 通道 PRD](./prd/channels/wechat-clawbot-channel-project-prd.md) |
|
||||
|
||||
## Task 与 Job 文档
|
||||
|
||||
- [统一领域模型](./prd/task-and-job/task-and-job-model.md)
|
||||
- [Task Center](./prd/task-and-job/task-center-prd.md)
|
||||
- [Scheduled Task](./prd/task-and-job/scheduled-task-prd.md)
|
||||
- [Goal Task](./prd/task-and-job/goal-task-prd.md)
|
||||
- [Job 与 Subjob](./prd/task-and-job/job-and-subjob-prd.md)
|
||||
|
||||
## 跨功能文档
|
||||
|
||||
- [自动化平台架构](./architecture/automation-platform-architecture.md)
|
||||
- [平台功能页签与模型下载源设计](./architecture/model-download-source-design.md)
|
||||
- [本地文本向量模型与连接设计](./architecture/local-text-embedding-model-design.md)
|
||||
- [本机工具环境设计与实施计划](./architecture/local-tool-environment-design.md)
|
||||
- [全双工实时语音交互设计](./architecture/full-duplex-voice-design.md)
|
||||
- [DeepSeek Harness Runtime 设计](./architecture/deepseek-harness-runtime-design.md)
|
||||
- [应用内反馈系统设计与对接](./architecture/in-app-feedback-integration-design.md)
|
||||
- [SSH 远程主机与 GoodBuddy Agent 实现说明](./architecture/remote-host-and-goodbuddy-agent-design.md)
|
||||
- [SSH Host 远程环境准备与控制面直连设计](./architecture/remote-host-environment-provisioning-design.md)
|
||||
- [长期助手路线图](./roadmap/long-term-assistant-roadmap.md)
|
||||
- [产品、性能与体验综合改进计划](./roadmap/product-performance-experience-improvement-plan.md)
|
||||
- [电脑控制实施状态](./status/computer-control-implementation-status.md)
|
||||
- [知识检索评估](./quality/knowledge-retrieval-evaluation.md)
|
||||
- [GoodBuddy 龙芯（LoongArch）预览版构建与功能列表](./development/loongarch-preview-build.md)
|
||||
- [统一界面设计系统](../UI-DESIGN.md)
|
||||
|
||||
## 目录规则
|
||||
|
||||
1. PRD 放在 `docs/prd/<功能域>/`。
|
||||
2. 跨功能技术总纲放在 `docs/architecture/`。
|
||||
3. 产品级设计放在 `docs/design/`，路线图和实施状态分别放在 `roadmap`、`status`。
|
||||
4. 测试方法、评估协议和质量报告放在 `docs/quality/`。
|
||||
5. 开发环境、实验性构建和移植说明放在 `docs/development/`。
|
||||
6. 一个概念只能有一份权威定义；其他文档链接到它，不复制另一套术语。
|
||||
7. Task、Job、Run、Subagent 和 Conversation 的含义以
|
||||
[Task 与 Job 统一领域模型](./prd/task-and-job/task-and-job-model.md) 为准。
|
||||
@@ -9,7 +9,7 @@
|
||||
| 日期 | 2026-08-19 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 文档角色 | Task/Job、调度、目标、并行实验、会话监督、分区记忆与持续学习的总纲 |
|
||||
| 领域模型 | [Task 与 Job 统一领域模型](../prd/task-and-job/task-and-job-model.md) |
|
||||
| 领域模型 | [Task 与 Job 统一领域模型](../features/task-and-job/task-and-job-model.md) |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
@@ -445,7 +445,7 @@ Renderer 只通过显式 IPC 列出、加入、删除、提升、释放和接收
|
||||
监督统一进入应用级助手工作栏中固定且始终可访问的“监督”栏目，不再保留“独立可折叠右栏”
|
||||
和“动态新增页签”两种实现。栏目默认跟随当前上下文，用户可以固定到其他 Conversation、
|
||||
Task 或实验对象；详细范围与交互契约见
|
||||
[通用助手工作栏与执行空间 PRD](../prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)。
|
||||
[通用助手工作栏与执行空间 PRD](../features/assistant-workbar/prd.md)。
|
||||
|
||||
## 13. 安全与隐私
|
||||
|
||||
@@ -555,15 +555,15 @@ Conversation 关联，旧 child-task 字段可兼容映射到 Job/Subjob；心
|
||||
|
||||
## 17. 相关文档
|
||||
|
||||
- [Task 与 Job 统一领域模型](../prd/task-and-job/task-and-job-model.md)
|
||||
- [Task Center PRD](../prd/task-and-job/task-center-prd.md)
|
||||
- [Scheduled Task PRD](../prd/task-and-job/scheduled-task-prd.md)
|
||||
- [Job 与 Subjob PRD](../prd/task-and-job/job-and-subjob-prd.md)
|
||||
- [智能心跳 PRD](../prd/smart-heartbeat/smart-heartbeat-prd.md)
|
||||
- [并行实验工作台 PRD](../prd/experiments/parallel-experiments-prd.md)
|
||||
- [会话监督 PRD](../prd/supervision/conversation-supervision-prd.md)
|
||||
- [分区记忆 PRD](../prd/memory/partitioned-memory-prd.md)
|
||||
- [持续学习与评估门 PRD](../prd/learning/continuous-learning-prd.md)
|
||||
- [Task 与 Job 统一领域模型](../features/task-and-job/task-and-job-model.md)
|
||||
- [Task Center PRD](../features/task-and-job/task-center-prd.md)
|
||||
- [Scheduled Task PRD](../features/task-and-job/scheduled-task-prd.md)
|
||||
- [Job 与 Subjob PRD](../features/task-and-job/job-and-subjob-prd.md)
|
||||
- [智能心跳 PRD](../features/smart-heartbeat/prd.md)
|
||||
- [并行实验工作台 PRD](../features/parallel-experiments/prd.md)
|
||||
- [会话监督 PRD](../features/conversation-supervision/prd.md)
|
||||
- [分区记忆 PRD](../features/memory/prd.md)
|
||||
- [持续学习与评估门 PRD](../features/continuous-learning/prd.md)
|
||||
- [GoodBuddy 长期助手功能规划](../roadmap/long-term-assistant-roadmap.md)
|
||||
- [GoodBuddy 统一界面设计系统](../../UI-DESIGN.md)
|
||||
|
||||
|
||||
@@ -1,647 +0,0 @@
|
||||
# GoodBuddy 本机工具环境设计与实施计划
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 文档类型 | 跨功能技术与产品架构 |
|
||||
| 状态 | 计划 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-08-31 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
|
||||
| 相关基线 | [DeepSeek Harness Runtime 设计](./deepseek-harness-runtime-design.md)、[SSH 远程主机与 GoodBuddy Agent 实现说明](./remote-host-and-goodbuddy-agent-design.md)、[统一界面设计系统](../../UI-DESIGN.md) |
|
||||
|
||||
本文定义 GoodBuddy 为本机 SKILL 脚本和本机 stdio MCP Server 提供 Node.js、Python
|
||||
解释器的产品形态、设置模型、进程环境、安装生命周期和实施顺序。目标是让普通用户无需
|
||||
预装开发环境即可使用依赖脚本的能力，同时让专业用户能够明确选择自己维护的解释器。
|
||||
|
||||
本文中的“本机工具环境”不等于 Agent Runtime，也不等于 SSH Host 上由 GoodBuddy Agent
|
||||
管理的远程环境。
|
||||
|
||||
---
|
||||
|
||||
## 1. 摘要与核心决策
|
||||
|
||||
1. 本机工具环境首期只管理 `Node.js` 和 `Python`。
|
||||
2. 每种工具只有两种互斥来源：
|
||||
- **GoodBuddy 托管**：由 GoodBuddy 提供、验证和解析。
|
||||
- **自定义环境**：用户从检测结果中选择，或指定其他可执行文件。
|
||||
3. 不提供独立的“自动选择”。它会隐藏实际版本，并可能在系统环境变化后静默改变执行结果。
|
||||
4. 不区分“系统安装”和“指定路径”。二者最终都是由用户明确选择的外部可执行文件，只是
|
||||
发现方式不同。
|
||||
5. Node.js 托管环境复用 Electron 内置 Node，通过受管 `node` shim 设置
|
||||
`ELECTRON_RUN_AS_NODE=1`，不额外打包一份 Node。
|
||||
6. Python 托管环境不无条件进入桌面安装包。用户首次需要时，GoodBuddy 按平台和架构下载、
|
||||
校验并安装一份固定 Python 发行包。
|
||||
7. `npm` 跟随 Node.js 来源，`pip` 跟随 Python 来源，不作为独立设置项。
|
||||
8. 首期不实现每个 SKILL、项目或 Runtime 单独覆盖解释器，也不实现通用 Node/Python
|
||||
版本管理器。
|
||||
9. 环境只注入本机 Runtime 和本机 stdio MCP 启动链路，不修改系统 PATH，不写 Shell
|
||||
Profile，不同步到远程主机。
|
||||
10. Ask/Execute 的现有权限语义保持不变。提供解释器不代表 Ask 获得脚本执行权限。
|
||||
11. 全新安装默认使用托管来源；升级用户当前可用的系统解释器会在一次性迁移中固化为
|
||||
自定义绝对路径，避免升级后改变既有脚本运行环境。
|
||||
12. 本机 stdio MCP 与 SKILL 使用同一套 Node.js/Python 选择。依赖 Python 或 Node.js
|
||||
启动的 MCP 不再要求用户另外配置一套解释器。
|
||||
|
||||
---
|
||||
|
||||
## 2. 当前实现基线
|
||||
|
||||
GoodBuddy 当前已经具备：
|
||||
|
||||
- 桌面安装包内的 Electron Node Runtime。
|
||||
- 随安装包交付的锁定 npm CLI。
|
||||
- DeepSeek Harness 插件安装器使用的受管 `node.cmd`/`node` shim，可复用
|
||||
`process.execPath + ELECTRON_RUN_AS_NODE=1`。
|
||||
- OpenCode、Continue 和 DeepSeek Harness 的独立本机进程环境构建入口。
|
||||
- SKILL 按 Runtime 目标分配和暂存的生产链路。
|
||||
- stdio MCP 的 Main 进程启动链路。
|
||||
- OpenCode 和 Continue 可执行文件的路径探测、版本读取和自定义路径设置模式。
|
||||
- 模型及远程 Runtime 包的下载、校验、进度、取消和清理模式。
|
||||
|
||||
当前缺口：
|
||||
|
||||
- 安装包没有向 SKILL 或通用 stdio MCP 暴露可直接调用的 `node` 命令。
|
||||
- 本机 Runtime 只继承经过筛选的系统 PATH；没有把 GoodBuddy 工具目录加入 PATH。
|
||||
- Python 完全依赖用户自行安装。
|
||||
- 设置页没有统一展示 Node.js、Python 的实际来源、版本、路径和可用状态。
|
||||
- 用户配置 `node server.js` 或 `python script.py` 时，成功与否取决于 GoodBuddy 启动时
|
||||
继承到的系统环境。
|
||||
|
||||
---
|
||||
|
||||
## 3. 范围
|
||||
|
||||
### 3.1 首期范围
|
||||
|
||||
- 本机 OpenCode、Continue、DeepSeek Harness 加载的 SKILL 脚本。
|
||||
- 由 GoodBuddy Main 启动的本机 stdio MCP Server。
|
||||
- Node.js 和 npm。
|
||||
- Python 3、pip 和标准 `venv` 能力。
|
||||
- 托管环境安装、删除、状态检查和真实解释器诊断。
|
||||
- 系统解释器探测、自定义文件选择和明确版本验证。
|
||||
- Windows、macOS、Linux 的 x64 与 arm64。
|
||||
|
||||
### 3.2 明确不作用的范围
|
||||
|
||||
- SSH Host 上的 GoodBuddy Agent、固定 Node 和签名 OpenCode Runtime。
|
||||
- 远程项目的 PATH、Shell Profile、Python、Node 或系统包。
|
||||
- HTTP/SSE MCP Server 的服务端运行环境。
|
||||
- Renderer 进程和网页内容。
|
||||
- GoodBuddy 自身构建环境。
|
||||
|
||||
### 3.3 非目标
|
||||
|
||||
首期不包含：
|
||||
|
||||
- 通用 `nvm`、`pyenv`、Conda、Poetry、uv 或操作系统包管理器替代品。
|
||||
- 任意 Node.js/Python 版本的目录、升级矩阵或自动切换。
|
||||
- 每个 SKILL 自动创建和维护独立虚拟环境。
|
||||
- 自动读取并执行任意 SKILL 的安装脚本。
|
||||
- 自动解析或合并多个 SKILL 的 `requirements.txt`、`package.json`。
|
||||
- 修改用户的系统 PATH、注册表、Shell Profile 或全局 npm/pip 配置。
|
||||
- 把 Python 无条件打入所有桌面安装包。
|
||||
- 把本机工具环境上传、复制或映射到 SSH Host。
|
||||
- 对用户自定义解释器进行安装、升级、修复或卸载。
|
||||
|
||||
---
|
||||
|
||||
## 4. 用户体验
|
||||
|
||||
### 4.1 设置位置
|
||||
|
||||
在 `Agent Runtime` 设置中增加“本机工具环境”区块。该区块位于默认工作区之后、
|
||||
具体 Runtime 高级设置之前，避免让用户误以为它只属于某一个 Runtime。
|
||||
|
||||
区块顶部持续显示范围说明：
|
||||
|
||||
> 用于本机 SKILL 脚本和本机 stdio MCP；不会修改系统环境，也不会应用于远程主机。
|
||||
|
||||
设置使用普通卡片和原生单选语义。选项只有两项，不增加三级页签或页面专属切换控件。
|
||||
|
||||
### 4.2 Node.js 卡片
|
||||
|
||||
```text
|
||||
Node.js
|
||||
|
||||
● GoodBuddy 托管（推荐）
|
||||
Node.js vXX · 已就绪
|
||||
|
||||
○ 自定义环境
|
||||
[Node.js v22.x · C:\Program Files\nodejs\node.exe ▼]
|
||||
[选择其他可执行文件]
|
||||
```
|
||||
|
||||
托管 Node 随应用可用，不显示安装按钮。版本来自一次真实
|
||||
`node --version` 诊断，而不是仅根据 Electron 包版本推断。
|
||||
|
||||
### 4.3 Python 卡片
|
||||
|
||||
未安装托管 Python 时：
|
||||
|
||||
```text
|
||||
Python
|
||||
|
||||
● GoodBuddy 托管（推荐）
|
||||
尚未安装
|
||||
[安装]
|
||||
|
||||
○ 自定义环境
|
||||
[Python 3.13.x · C:\Python313\python.exe ▼]
|
||||
[选择其他可执行文件]
|
||||
```
|
||||
|
||||
安装后显示版本、架构、占用空间和“删除”操作。删除前只需要说明依赖托管 Python 的本机
|
||||
SKILL 和 MCP 将暂时不可用；不引入额外确认文字输入。
|
||||
|
||||
### 4.4 自定义环境
|
||||
|
||||
- 下拉列表展示本次检测到且验证成功的候选项。
|
||||
- 每项必须同时展示版本和规范化绝对路径。
|
||||
- “选择其他可执行文件”使用 Main 管理的文件选择器。
|
||||
- 保存前执行真实 `--version` 诊断。
|
||||
- 已保存路径失效时保持该选择并显示“路径不可用”，不静默切回托管环境或其他候选。
|
||||
- 用户可以显式改回 GoodBuddy 托管。
|
||||
|
||||
### 4.5 反馈
|
||||
|
||||
- 安装、删除和重新检测的瞬时成功信息使用应用通知。
|
||||
- 当前来源、版本、路径、下载进度和阻塞错误保留在卡片内。
|
||||
- 下载失败保留当前选择和已验证旧安装。
|
||||
- 字段或路径错误就地展示，不与通知重复。
|
||||
|
||||
---
|
||||
|
||||
## 5. 设置与状态模型
|
||||
|
||||
### 5.1 持久设置
|
||||
|
||||
每种工具只保存用户意图：
|
||||
|
||||
```ts
|
||||
type LocalToolEnvironmentSelection =
|
||||
| { source: 'managed' }
|
||||
| { source: 'custom'; executablePath: string }
|
||||
|
||||
type LocalToolEnvironmentSettings = {
|
||||
node: LocalToolEnvironmentSelection
|
||||
python: LocalToolEnvironmentSelection
|
||||
}
|
||||
```
|
||||
|
||||
不持久化以下可重新推导的信息：
|
||||
|
||||
- 检测候选列表。
|
||||
- 当前版本。
|
||||
- PATH。
|
||||
- shim 路径。
|
||||
- 诊断结果。
|
||||
- 托管包的重复元数据副本。
|
||||
|
||||
托管 Python 的固定包清单属于随应用交付或从受信目录读取的产品元数据，不进入用户设置。
|
||||
|
||||
### 5.2 兼容迁移
|
||||
|
||||
- 全新用户的 Node.js、Python 默认来源均为 `managed`。
|
||||
- 已发布版本升级且设置中没有本机工具环境字段时，Main 分别按升级前实际使用的 PATH
|
||||
解析 `node` 和 Python 3。
|
||||
- 找到并通过真实版本诊断后，迁移写入
|
||||
`{ source: 'custom', executablePath: '<规范化绝对路径>' }`。
|
||||
- 未找到有效解释器时，该工具迁移为 `{ source: 'managed' }`。
|
||||
- 迁移只执行一次并持久化明确结果。后续 PATH 变化不会自动改变选择。
|
||||
- 迁移不复制、修改或删除系统解释器及其已安装包。
|
||||
|
||||
这样保留现有用户脚本的解释器来源，同时不向产品增加长期存在的“自动选择”模式。
|
||||
|
||||
### 5.3 Renderer 状态
|
||||
|
||||
Renderer 只接收有界公开状态：
|
||||
|
||||
```ts
|
||||
type LocalToolEnvironmentStatus = {
|
||||
tool: 'node' | 'python'
|
||||
selection: LocalToolEnvironmentSelection
|
||||
active?: {
|
||||
source: 'managed' | 'custom'
|
||||
executablePath: string
|
||||
version: string
|
||||
}
|
||||
candidates: Array<{
|
||||
executablePath: string
|
||||
version: string
|
||||
}>
|
||||
managed: {
|
||||
state: 'ready' | 'not-installed' | 'installing' | 'error'
|
||||
version?: string
|
||||
installedBytes?: number
|
||||
}
|
||||
error?: string
|
||||
}
|
||||
```
|
||||
|
||||
Renderer 不能提交下载 URL、摘要、解压目录、命令参数或任意环境变量。
|
||||
|
||||
---
|
||||
|
||||
## 6. Main 进程架构
|
||||
|
||||
### 6.1 `LocalToolEnvironmentService`
|
||||
|
||||
Main 新增单一服务负责：
|
||||
|
||||
- 读取和保存工具来源设置。
|
||||
- 探测系统候选。
|
||||
- 验证自定义解释器。
|
||||
- 解析当前有效解释器。
|
||||
- 准备受管 shim 目录。
|
||||
- 安装和删除托管 Python。
|
||||
- 发布有界进度和状态。
|
||||
- 应用退出时取消自身安装任务并清理本次暂存。
|
||||
|
||||
保持一个服务即可，不为 Node、Python、下载、shim 和探测分别建立持久 Manager 层。
|
||||
|
||||
### 6.2 解析结果
|
||||
|
||||
Runtime 和 MCP 不读取设置文件，而是请求一次解析结果：
|
||||
|
||||
```ts
|
||||
type ResolvedLocalToolEnvironment = {
|
||||
binDirectory: string
|
||||
nodeExecutable?: string
|
||||
pythonExecutable?: string
|
||||
}
|
||||
```
|
||||
|
||||
`binDirectory` 包含受管命令入口：
|
||||
|
||||
- Windows：`node.cmd`、`npm.cmd`、`python.cmd`、`python3.cmd`、`pip.cmd`。
|
||||
- macOS/Linux：`node`、`npm`、`python`、`python3`、`pip`。
|
||||
|
||||
只有当前选择且验证成功的工具才生成入口。入口使用绝对路径，不依赖递归 PATH 查找。
|
||||
|
||||
### 6.3 环境注入
|
||||
|
||||
本机 Runtime 启动时把 `binDirectory` 放在其现有 PATH 前面：
|
||||
|
||||
```text
|
||||
<GoodBuddy tool bin><delimiter><existing filtered PATH>
|
||||
```
|
||||
|
||||
注入点包括：
|
||||
|
||||
- 内置 OpenCode Server 进程。
|
||||
- Continue Utility Process。
|
||||
- DeepSeek Harness Utility Process。
|
||||
- Main 启动的 stdio MCP Server。
|
||||
|
||||
不注入：
|
||||
|
||||
- GoodBuddy Main 自身的 `process.env`。
|
||||
- Renderer。
|
||||
- SSH/Agent/远程 Runtime 请求。
|
||||
- 用户打开的普通系统终端。
|
||||
|
||||
首期不修改助手工作栏终端的环境，避免与用户 Shell Profile 和系统命令预期发生隐式冲突。
|
||||
如果未来提供“使用 GoodBuddy 工具环境的新终端”，必须作为用户显式选择的新终端类型设计。
|
||||
|
||||
### 6.4 运行时刷新
|
||||
|
||||
工具环境设置保存、托管 Python 安装或删除后：
|
||||
|
||||
- 新启动的 Runtime 和 MCP 使用新环境。
|
||||
- 已运行进程不在中途替换 PATH。
|
||||
- 需要重建的当前 Runtime 使用现有 Runtime 重建入口完成。
|
||||
- 已运行的 stdio MCP 在下一次正常重连或显式测试时使用新环境；首期不增加独立热切换协议。
|
||||
|
||||
界面应准确说明“新启动的本机 Runtime 和 MCP 将使用此环境”。
|
||||
|
||||
---
|
||||
|
||||
## 7. Node.js 托管环境
|
||||
|
||||
### 7.1 执行方式
|
||||
|
||||
托管 `node` shim 固定调用当前 `process.execPath`：
|
||||
|
||||
```text
|
||||
ELECTRON_RUN_AS_NODE=1 <GoodBuddy executable> <arguments...>
|
||||
```
|
||||
|
||||
实现复用 DeepSeek Harness npm 安装器已经验证的转义和平台脚本模式，不复制另一套命令
|
||||
拼接规则。
|
||||
|
||||
### 7.2 npm
|
||||
|
||||
- 托管 Node 使用安装包内锁定的 npm CLI。
|
||||
- `npm` shim 调用托管 Node，并把 npm CLI 绝对路径作为第一个参数。
|
||||
- `npm_node_execpath`、`npm_execpath` 只在 npm 子进程范围设置。
|
||||
- 自定义 Node 优先使用同一目录或系统 PATH 中与其配套的 npm；找不到 npm 时 Node 仍可用，
|
||||
卡片显示“npm 不可用”。
|
||||
- 首期不混用“自定义 Node + GoodBuddy npm”，避免产生难以解释的版本组合。
|
||||
|
||||
### 7.3 约束
|
||||
|
||||
- `ELECTRON_RUN_AS_NODE` 不写入 Main 全局环境。
|
||||
- shim 不放入系统 PATH。
|
||||
- Electron 升级后版本变化必须在设置状态中可见。
|
||||
- 普通 JavaScript 和 Node 内置模块属于支持路径。
|
||||
- 原生 `.node` 扩展可能受 Electron ABI 影响，界面帮助文案应明确不保证普通 Node 原生
|
||||
扩展兼容；N-API 兼容性仍以模块自身声明和真实加载为准。
|
||||
|
||||
---
|
||||
|
||||
## 8. Python 托管环境
|
||||
|
||||
### 8.1 包形态
|
||||
|
||||
- 使用可再分发、包含 `pip` 和 `venv` 的固定 CPython 独立发行包。
|
||||
- 每个平台和架构只有一个 GoodBuddy 支持版本。
|
||||
- 包目录包含版本、平台、架构、URL、字节数、SHA-256 和许可证信息。
|
||||
- 下载源复用“关于与更新”中用户选择的官方 GitHub/镜像来源，不另建一套来源设置。
|
||||
- 具体版本在实施时按六平台可用性和许可证复核后锁定，不在用户设置中自由选择。
|
||||
- Python 标准库和许可证与托管包一起安装。
|
||||
|
||||
### 8.2 安装
|
||||
|
||||
```text
|
||||
用户点击安装
|
||||
→ Main 读取当前固定包元数据
|
||||
→ 下载到 GoodBuddy 用户数据暂存目录
|
||||
→ 校验大小和 SHA-256
|
||||
→ 解压到新的版本目录
|
||||
→ 运行 python --version 和最小标准库诊断
|
||||
→ 发布为当前托管 Python
|
||||
→ 删除本次暂存
|
||||
```
|
||||
|
||||
失败时删除本次暂存并保留已验证旧安装。首期不建立快照、安装日志恢复器或多版本注册表；
|
||||
下次安装从头重试即可。
|
||||
|
||||
### 8.3 Python 包
|
||||
|
||||
- 托管 Python 提供正常的 `python -m pip`。
|
||||
- SKILL 仍显式声明和执行自身需要的依赖安装命令。
|
||||
- 首期不自动扫描或安装 `requirements.txt`。
|
||||
- 首期共用一个当前用户的托管 Python 包环境；若出现可复现的依赖冲突，再单独设计按
|
||||
SKILL 隔离，不预先建设虚拟环境编排系统。
|
||||
- 专业用户需要 Conda、uv、Poetry 或项目虚拟环境时，应选择对应环境中的 Python
|
||||
可执行文件作为“自定义环境”。
|
||||
|
||||
### 8.4 删除与升级
|
||||
|
||||
- 删除只影响 GoodBuddy-owned Python 目录。
|
||||
- 不删除用户工作区、系统 Python 或自定义环境。
|
||||
- 正在被 GoodBuddy 子进程使用时，先通过现有 Runtime/MCP 生命周期停止相关进程，再删除。
|
||||
- Python 版本随 GoodBuddy 发布清单更新，但不后台自动升级。用户在设置页看到“可更新”后
|
||||
显式执行更新。
|
||||
|
||||
---
|
||||
|
||||
## 9. 自定义环境探测
|
||||
|
||||
### 9.1 Node.js
|
||||
|
||||
候选来源：
|
||||
|
||||
- 当前筛选后 PATH 中的 `node`/`node.exe`。
|
||||
- Windows 常见 Node 安装目录和当前用户 npm 目录关联的 Node。
|
||||
- macOS/Linux 常见系统安装位置。
|
||||
- 已保存的自定义路径。
|
||||
|
||||
每个候选使用分离参数执行 `--version`，要求普通文件、目标平台可执行、成功退出且版本输出
|
||||
可解析。候选按规范化真实路径去重。
|
||||
|
||||
### 9.2 Python
|
||||
|
||||
候选来源：
|
||||
|
||||
- Windows 的 `python.exe`。
|
||||
- macOS/Linux 的 `python3`，其次是明确指向 Python 3 的 `python`。
|
||||
- 常见系统和当前用户安装目录。
|
||||
- 已保存的自定义路径。
|
||||
|
||||
验证命令必须同时确认 Python 3、平台架构和解释器绝对路径。Windows Store 的未安装
|
||||
App Execution Alias 不能作为成功候选。
|
||||
|
||||
### 9.3 探测行为
|
||||
|
||||
- 打开设置页时读取最近状态，不阻塞整个设置中心。
|
||||
- 用户点击“重新检测”时重新扫描。
|
||||
- 探测不安装软件、不执行包管理器、不修改文件。
|
||||
- 单候选和总探测均使用有界超时、输出上限和进程树清理。
|
||||
- 路径或版本诊断失败只影响该候选。
|
||||
|
||||
---
|
||||
|
||||
## 10. SKILL 与 MCP 接入
|
||||
|
||||
### 10.1 SKILL
|
||||
|
||||
GoodBuddy 继续按当前方式把 SKILL 包暂存到目标 Runtime。工具环境只改变本机 Runtime
|
||||
子进程看到的 PATH，因此 SKILL 可以使用稳定命令：
|
||||
|
||||
```text
|
||||
node "<skill-dir>/scripts/example.js"
|
||||
python "<skill-dir>/scripts/example.py"
|
||||
python -m pip install -r "<skill-dir>/requirements.txt"
|
||||
```
|
||||
|
||||
SKILL 不接收解释器真实安装目录，也不把路径写入自身内容。未准备的解释器被调用时，命令
|
||||
明确失败，Runtime 应把原始“环境未就绪”上下文返回给用户。
|
||||
|
||||
### 10.2 stdio MCP
|
||||
|
||||
- `command: node`、`command: python` 和对应脚本参数通过同一个工具 bin 解析。
|
||||
- `command: python3`、`command: npm`、`command: pip` 同样解析到当前明确选择的工具来源。
|
||||
- 以 `#!/usr/bin/env python3` 或 `#!/usr/bin/env node` 启动且由 Runtime Shell 解析的
|
||||
MCP 脚本，也会从注入的工具 bin 找到当前解释器。
|
||||
- 例如 `python -m my_mcp_server`、`node server.js` 这类本机 MCP 启动命令，无论由 Main
|
||||
直连模型工具链还是本机 OpenCode、Continue、DeepSeek Harness 发起，都使用相同来源。
|
||||
- 绝对命令路径继续按用户配置执行，不被工具环境替换。
|
||||
- HTTP/SSE MCP 不受影响。
|
||||
- 自定义 MCP 凭据和工具环境状态保持分离。
|
||||
- MCP 进程继续受现有取消、超时、关闭和输出上限控制。
|
||||
- 工具环境只提供解释器和配套 npm/pip，不自动安装 MCP 自身的 Python/Node 依赖；这些
|
||||
依赖仍由 MCP 的安装流程或用户明确执行的安装命令准备。
|
||||
|
||||
### 10.3 Ask/Execute
|
||||
|
||||
- Ask 的 Runtime 只读边界保持不变。
|
||||
- 提供 Node/Python 不会给直连模型新增 Execute 工具。
|
||||
- OpenCode、Continue、DeepSeek Harness 仍按各自 Ask 权限边界决定是否允许命令工具。
|
||||
- Execute 继续表示用户对所选本机账号可用工具和路径的完整授权。
|
||||
- stdio MCP 的启动行为沿用当前能力开关和分配规则，不新增第二套批准流程。
|
||||
|
||||
---
|
||||
|
||||
## 11. 远程主机边界
|
||||
|
||||
本机工具环境与远程托管环境严格分离：
|
||||
|
||||
- 不上传 shim、Python 包、pip 包或自定义解释器路径。
|
||||
- 不修改 SSH Host PATH。
|
||||
- 不把本机 SKILL 包同步到远程 OpenCode。
|
||||
- 不把本机 stdio MCP Server 配置传给远程 ACP Session。
|
||||
- 远程 Agent 的固定 Node 继续只服务 Agent、模型桥和签名 Runtime。
|
||||
- 远程项目只能使用远端签名 Runtime 自身具备的能力和 SSH 账号已有系统环境。
|
||||
|
||||
远程主机设置页必须持续显示：
|
||||
|
||||
> 本机配置的 Skills 和 MCP 不会应用于远程主机。
|
||||
|
||||
---
|
||||
|
||||
## 12. IPC 与安全边界
|
||||
|
||||
- 所有设置和操作输入使用共享 Zod schema。
|
||||
- Renderer 只提交工具类型、来源、已选择候选路径或文件选择动作。
|
||||
- 自定义路径由 Main 重新规范化、检查和执行真实版本诊断。
|
||||
- Renderer 不能提交 PATH、环境变量、下载 URL、安装目录或 shim 内容。
|
||||
- Main 只在明确的本机 Runtime/MCP 子进程环境中注入工具 bin。
|
||||
- API Key 和 MCP 凭据不进入解释器检测命令、安装日志或状态快照。
|
||||
- 下载、解压、诊断和删除都限制在 GoodBuddy-owned 目录。
|
||||
- 不删除或覆盖用户自定义解释器及其包。
|
||||
- 继续保持 Context Isolation、Sandbox 和 Renderer 无 Node Integration。
|
||||
|
||||
---
|
||||
|
||||
## 13. 实施顺序
|
||||
|
||||
以下阶段是开发顺序，不是可以长期停留的残缺产品状态。合并该能力前应完成普通用户使用
|
||||
托管 Node/Python 和专业用户使用自定义解释器的完整本机生产路径。
|
||||
|
||||
### 阶段 1：共享契约、设置与诊断
|
||||
|
||||
- 增加本机工具环境设置 schema、迁移默认值和 IPC 契约。
|
||||
- 全新用户默认 Node.js、Python 均选择 `managed`。
|
||||
- 升级用户把当前有效的系统解释器一次性固化为自定义绝对路径。
|
||||
- 实现 Node/Python 候选探测和真实版本诊断。
|
||||
- 增加设置页卡片、范围说明、来源选择、路径选择和状态展示。
|
||||
- 保持旧用户现有 Runtime 设置不变。
|
||||
|
||||
### 阶段 2：托管 Node 与本机执行链路
|
||||
|
||||
- 提取并复用当前 DSH `node` shim 逻辑。
|
||||
- 生成当前会话受管 tool bin。
|
||||
- 为 OpenCode、Continue、DeepSeek Harness 注入工具 bin。
|
||||
- 为本机 stdio MCP 注入同一工具环境。
|
||||
- 验证 npm CLI 与 npm lifecycle 子进程使用正确 Node。
|
||||
|
||||
### 阶段 3：托管 Python
|
||||
|
||||
- 选定并锁定六平台 CPython 独立发行包。
|
||||
- 增加包目录、许可证、下载、进度、取消、校验、安装、诊断和删除。
|
||||
- 生成 `python`、`python3`、`pip` shim。
|
||||
- 验证当前内置 Python SKILL 的真实执行路径。
|
||||
|
||||
### 阶段 4：端到端验收与文档收口
|
||||
|
||||
- 使用内置 Node 脚本 SKILL 验证无需系统 Node。
|
||||
- 使用现有 Python SKILL 验证全新设备从安装托管 Python 到生成实际成果。
|
||||
- 使用 Node 和 Python stdio MCP 分别验证启动和工具调用。
|
||||
- 验证切换到系统/自定义解释器后的版本和路径。
|
||||
- 验证 Ask/Execute、取消、退出和 Runtime 重建行为。
|
||||
- 更新用户说明、架构文档、设置文案、发布打包校验和许可证清单。
|
||||
|
||||
---
|
||||
|
||||
## 14. 预计代码落点
|
||||
|
||||
| 层 | 预计改动 |
|
||||
| --- | --- |
|
||||
| Shared | 本机工具环境设置、状态、操作和 IPC schema |
|
||||
| Main | `LocalToolEnvironmentService`、探测、shim、Python 包安装 |
|
||||
| Runtime | `process-environment`、OpenCode、Continue、DSH 启动环境注入 |
|
||||
| MCP | stdio transport 的受管 PATH 注入 |
|
||||
| Preload | 状态读取、保存、检测、安装、取消、删除和进度订阅 |
|
||||
| Renderer | Agent Runtime 设置中的本机工具环境卡片 |
|
||||
| Build | Python 包目录/许可证校验，现有 npm 和 Electron Node 验证 |
|
||||
| Docs | 用户范围、SKILL/MCP 使用和远程主机边界 |
|
||||
|
||||
实际实现应优先复用现有运行环境检测、模型下载、通知和进程树清理代码，不为了表格中的职责
|
||||
机械新增同名文件或抽象层。
|
||||
|
||||
---
|
||||
|
||||
## 15. 测试策略
|
||||
|
||||
### 15.1 单元测试
|
||||
|
||||
- 设置迁移和严格 schema。
|
||||
- 两种来源的解析，不存在第三种自动状态。
|
||||
- Node/Python 候选发现、去重、超时和版本解析。
|
||||
- Windows Store Python alias 拒绝。
|
||||
- shim 的 Windows 与 POSIX 转义。
|
||||
- `ELECTRON_RUN_AS_NODE` 仅存在于 Node 子进程。
|
||||
- PATH 前缀顺序和原环境保留。
|
||||
- 已保存自定义路径失效时不回退。
|
||||
- Python 下载摘要、暂存清理、成功发布和删除范围。
|
||||
|
||||
### 15.2 本地集成测试
|
||||
|
||||
- 安装包中的 Electron Node 实际执行 JavaScript 文件。
|
||||
- 安装包中的 npm CLI 实际运行并启动一个最小 lifecycle script。
|
||||
- OpenCode、Continue、DeepSeek Harness 分别解析相同 `node`/`python` shim。
|
||||
- 本机 stdio MCP 使用托管和自定义来源启动。
|
||||
- 设置变化后新进程使用新环境，旧进程不被中途改写。
|
||||
- 取消和应用退出没有残留安装任务或工具进程。
|
||||
|
||||
### 15.3 六平台打包验证
|
||||
|
||||
- tool bin 脚本存在且权限正确。
|
||||
- Electron RunAsNode 可用。
|
||||
- npm CLI 和许可证存在。
|
||||
- Python 固定包目录覆盖目标平台/架构，下载工件和许可证可验证。
|
||||
- Python 安装后能导入标准库、pip、venv。
|
||||
- 安装包未无条件包含完整 Python 工件。
|
||||
|
||||
### 15.4 项目验证
|
||||
|
||||
源码完成后运行：
|
||||
|
||||
```text
|
||||
npm test
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm run build
|
||||
```
|
||||
|
||||
涉及生产打包资源时按发布流程运行对应平台的原生 CI 打包验证。该功能不改变远程 Agent
|
||||
或桌面到 Agent 生产链路，因此不要求因本机工具环境本身修改共享 SSH Host；如果后续改动
|
||||
触及远程协议、Agent 包或远程 Runtime，则必须按远程架构文档完成真实 Host 验证。
|
||||
|
||||
---
|
||||
|
||||
## 16. 验收标准
|
||||
|
||||
- 全新安装且系统没有 Node.js 时，本机 SKILL 可以通过 `node` 执行普通 JavaScript。
|
||||
- 全新安装且系统没有 npm 时，托管 npm 可以执行受支持的安装命令。
|
||||
- 系统没有 Python 时，用户可以从设置页安装托管 Python，并运行现有 Python SKILL 生成
|
||||
实际成果。
|
||||
- 用户可以选择检测到的系统 Node/Python，设置页显示实际版本和绝对路径。
|
||||
- 用户可以选择未被自动发现的解释器文件，保存前完成真实诊断。
|
||||
- 自定义路径失效时明确报错，不静默切换来源。
|
||||
- Node.js 和 Python 各自只有“GoodBuddy 托管”和“自定义环境”两个来源。
|
||||
- npm 跟随 Node，pip 跟随 Python，不出现重复来源设置。
|
||||
- 本机 OpenCode、Continue、DeepSeek Harness 和 stdio MCP 使用一致的解释器选择。
|
||||
- 依赖 Python 和依赖 Node.js 的本机 stdio MCP 均能使用托管环境完成真实启动与工具调用。
|
||||
- 不修改系统 PATH、Shell Profile 或用户自定义解释器。
|
||||
- Ask 不因安装解释器获得额外写入或命令权限。
|
||||
- 取消、Runtime 重建和应用退出可以清理 GoodBuddy 自己启动的进程与暂存。
|
||||
- 远程主机不接收本机 SKILL、MCP、shim、Python 包或自定义解释器路径。
|
||||
- 中英文设置文案、键盘操作、可见焦点、状态和错误反馈符合统一界面设计系统。
|
||||
- 全量测试、类型检查、Lint 和生产构建通过。
|
||||
|
||||
---
|
||||
|
||||
## 17. 已知限制
|
||||
|
||||
- Electron Node 与普通 Node 的原生模块 ABI 可能不同，首期不承诺普通 Node 原生扩展兼容。
|
||||
- 托管 Python 首期只有一个 GoodBuddy 支持版本，不提供多版本并存和自动选择。
|
||||
- 首期共用托管 Python 包环境，不能解决所有第三方包版本冲突；复杂项目应选择用户自己的
|
||||
虚拟环境。
|
||||
- 已运行的 Runtime 和 MCP 不热切换解释器，设置变化对新进程生效。
|
||||
- 助手工作栏终端首期不自动继承本机工具环境。
|
||||
- HTTP/SSE MCP 的远端服务依赖由服务部署方负责。
|
||||
@@ -10,7 +10,7 @@
|
||||
| 日期 | 2026-08-19 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
|
||||
| 相关基线 | [统一界面设计系统](../../UI-DESIGN.md)、[文档解析与本地 OCR](../prd/document-processing/document-extraction-and-local-ocr.md)、[本地文本向量模型与连接设计](./local-text-embedding-model-design.md)、[全双工实时语音交互设计](./full-duplex-voice-design.md) |
|
||||
| 相关基线 | [统一界面设计系统](../../UI-DESIGN.md)、[文档解析与本地 OCR](../features/document-processing/prd.md)、[本地文本向量模型与连接设计](../features/knowledge-base/local-embedding-technical-design.md)、[全双工实时语音交互设计](../features/full-duplex-voice/technical-design.md) |
|
||||
|
||||
本文定义“设置 → 平台功能”的二级页签结构，以及所有 GoodBuddy 托管本地模型共同使用的
|
||||
“模型下载源”设置。首期下载源为 ModelScope 和 Hugging Face，默认使用 ModelScope。
|
||||
|
||||
@@ -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 中，后续实际维护该功能时按职责拆分。
|
||||
+12
-12
@@ -8,8 +8,8 @@
|
||||
| 版本 | 0.6 |
|
||||
| 日期 | 2026-08-31 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md)、[SSH 远程主机与 GoodBuddy Agent 实现说明](../../architecture/remote-host-and-goodbuddy-agent-design.md) |
|
||||
| 相关能力 | [会话监督](../supervision/conversation-supervision-prd.md)、[自动化平台](../../architecture/automation-platform-architecture.md)、[长期助手路线图](../../roadmap/long-term-assistant-roadmap.md) |
|
||||
| 相关设计 | [统一界面设计系统](../../../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. 背景
|
||||
|
||||
@@ -205,7 +205,7 @@ Runtime
|
||||
能力目录不等于同时打开八个面板。当前产品采用“已打开实例 Tab + 持久新增按钮”的工作栏
|
||||
模型：Tab 行只显示已打开实例，行末“+”始终可见；点击后在工作栏内容区打开稳定能力目录，
|
||||
用户再创建或激活应用实例。详细交互以
|
||||
[助手工作栏多终端页签 PRD](./workbar-terminal-tabs-prd.md) 为准。
|
||||
[助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) 为准。
|
||||
|
||||
- 每项始终显示稳定图标，并提供可见标签或可持续查看的工具提示。
|
||||
- 已打开实例使用 `tablist`、`tab`、`tabpanel`；“+”是位于 `tablist` 外的普通命令按钮。
|
||||
@@ -270,7 +270,7 @@ Conversation，默认 Execute，并持续显示 Runtime、Project、工作目录
|
||||
### 7.2 监督
|
||||
|
||||
监督是通用观察与评论入口，详细行为以
|
||||
[会话监督 PRD](../supervision/conversation-supervision-prd.md) 为准。
|
||||
[会话监督 PRD](../conversation-supervision/prd.md) 为准。
|
||||
|
||||
监督能力在目录中稳定可发现；用户打开面板实例后可以选择：
|
||||
|
||||
@@ -318,7 +318,7 @@ Runtime 能力统一监督直连模型、OpenCode、Continue、DeepSeek Harness
|
||||
|
||||
终端面板允许用户通过工作栏“+”主动创建和管理多个本机或 SSH 终端。详细产品行为、首期
|
||||
直接 SSH PTY 技术选择、生命周期和验收以
|
||||
[助手工作栏多终端页签 PRD](./workbar-terminal-tabs-prd.md) 为准。
|
||||
[助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) 为准。
|
||||
|
||||
- 新建、重命名、切换、关闭和重新连接终端。
|
||||
- 创建时自动绑定当前项目执行空间、权威工作目录和平台默认 Shell，不显示重复目标选择。
|
||||
@@ -512,7 +512,7 @@ type WorkbarPanelInstance = {
|
||||
|
||||
本节定义产品入口和用户行为。Host Key、凭据、远程 Agent 协议、模型请求代理、签名更新、
|
||||
断线和 Runtime 适配的技术边界以
|
||||
[SSH 远程主机与 GoodBuddy Agent 稳定终态设计](../../architecture/remote-host-and-goodbuddy-agent-design.md)
|
||||
[SSH 远程主机与 GoodBuddy Agent 稳定终态设计](../remote-host/technical-design.md)
|
||||
为准。
|
||||
|
||||
### 9.1 设置入口
|
||||
@@ -554,7 +554,7 @@ SSH/远程项目操作；已有 Host、项目和凭据保持不变。若当前
|
||||
不代表环境健康。环境准备失败或取消保留 Host 并显示可重试状态；重新安装失败时显示
|
||||
本次操作未完成，并以随后重新检查的版本卡片表达当前事实，不对不确定提交宣称旧版本
|
||||
未被替换。详细技术契约见
|
||||
[SSH Host 远程环境准备与直连下载设计](../../architecture/remote-host-environment-provisioning-design.md)。
|
||||
[SSH Host 远程环境准备与直连下载设计](../remote-host/environment-provisioning-technical-design.md)。
|
||||
|
||||
进入或切回“主机与远程执行”页面只读取本地 Host 列表，不逐台建立 SSH 连接。版本和瞬时
|
||||
下载能力仅在用户点击某台 Host 的“刷新版本”时探测，成功结果在当前 Renderer 进程内按
|
||||
@@ -969,17 +969,17 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
|
||||
## 18. 相关文档的职责
|
||||
|
||||
- 本文是助手工作栏稳定能力目录、用户面板实例、范围控制和执行空间的产品总契约。
|
||||
- [助手工作栏多终端页签 PRD](./workbar-terminal-tabs-prd.md) 定义持久“+”、应用实例策略、
|
||||
- [助手工作栏多终端页签 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/smart-heartbeat-prd.md) 定义心跳入口、范围和长期边界。
|
||||
- [会话监督 PRD](../supervision/conversation-supervision-prd.md) 定义监督判断、证据、预算和介入边界。
|
||||
- [智能心跳 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 设计](../../architecture/deepseek-harness-runtime-design.md) 定义该 Runtime 的具体适配边界。
|
||||
- [SSH Host 远程环境准备与直连下载设计](../../architecture/remote-host-environment-provisioning-design.md)
|
||||
- [DeepSeek Harness Runtime 设计](../deepseek-harness/technical-design.md) 定义该 Runtime 的具体适配边界。
|
||||
- [SSH Host 远程环境准备与直连下载设计](../remote-host/environment-provisioning-technical-design.md)
|
||||
定义 Host 级组件获取、首次准备、更新、回退和项目只验证边界。
|
||||
- [统一界面设计系统](../../../UI-DESIGN.md) 定义视觉、语义、响应式和无障碍规则。
|
||||
|
||||
+6
-6
@@ -8,9 +8,9 @@
|
||||
| 版本 | 1.1 |
|
||||
| 日期 | 2026-08-31 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 界面归属 | [通用助手工作栏与执行空间](./assistant-workbar-and-execution-spaces-prd.md) |
|
||||
| 界面归属 | [通用助手工作栏与执行空间](./prd.md) |
|
||||
| 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md) |
|
||||
| 远程架构 | [SSH 远程主机与 GoodBuddy Agent 实现说明](../../architecture/remote-host-and-goodbuddy-agent-design.md)、[SSH Host 远程环境准备与控制面直连设计](../../architecture/remote-host-environment-provisioning-design.md) |
|
||||
| 远程架构 | [SSH 远程主机与 GoodBuddy Agent 实现说明](../remote-host/technical-design.md)、[SSH Host 远程环境准备与控制面直连设计](../remote-host/environment-provisioning-technical-design.md) |
|
||||
|
||||
## 1. 文档职责
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
- “终端”作为首个多实例应用，自动使用当前项目的本机或托管 SSH 执行空间。
|
||||
- 本机与远程交互式终端的生命周期、状态、性能和验收要求。
|
||||
|
||||
[通用助手工作栏与执行空间 PRD](./assistant-workbar-and-execution-spaces-prd.md)
|
||||
[通用助手工作栏与执行空间 PRD](./prd.md)
|
||||
继续负责工作栏的应用级位置、稳定能力目录、执行空间、范围绑定和总体产品边界。本文不重新
|
||||
定义 Host Key、凭据、Agent 安装、Ask/Execute Runtime 或项目持久化契约。
|
||||
|
||||
@@ -572,11 +572,11 @@ Linux x64 Host 验证当前源码或候选包。
|
||||
|
||||
## 20. 相关文档职责
|
||||
|
||||
- [通用助手工作栏与执行空间 PRD](./assistant-workbar-and-execution-spaces-prd.md)：
|
||||
- [通用助手工作栏与执行空间 PRD](./prd.md)：
|
||||
工作栏应用级位置、稳定能力目录、执行空间和总体范围。
|
||||
- 本文：持久“+”、应用实例策略、工作栏动态 Tab、自动项目目标、本机与直接 SSH 多终端。
|
||||
- [统一界面设计系统](../../../UI-DESIGN.md)：Tab、菜单、布局、主题、焦点和无障碍规则。
|
||||
- [SSH 远程主机与 GoodBuddy Agent 实现说明](../../architecture/remote-host-and-goodbuddy-agent-design.md)：
|
||||
- [SSH 远程主机与 GoodBuddy Agent 实现说明](../remote-host/technical-design.md)：
|
||||
Host Key、凭据、连接池、Agent 和远程项目现状。
|
||||
- [SSH Host 远程环境准备与控制面直连设计](../../architecture/remote-host-environment-provisioning-design.md)：
|
||||
- [SSH Host 远程环境准备与控制面直连设计](../remote-host/environment-provisioning-technical-design.md)：
|
||||
Host 保存、环境准备和项目使用之间的职责。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 电脑控制
|
||||
|
||||
电脑控制包含 GoodBuddy 对浏览器和客户端桌面能力的产品实现与平台适配状态。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [功能进度](./progress.md) | 当前已实现能力、缺陷修复、平台限制和验证状态 |
|
||||
|
||||
当前只有进度文档；产品需求、功能逻辑、UI 和技术设计尚未从历史实现记录中独立整理。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 持续学习
|
||||
|
||||
持续学习定义 GoodBuddy 如何从运行结果、评估证据和人工反馈中形成可验证的改进闭环。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [持续学习与评估门 PRD](./prd.md) | 产品目标、学习边界、评估门和验收要求 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
+1
-1
@@ -7,7 +7,7 @@
|
||||
| 状态 | 设计中，远期能力 |
|
||||
| 版本 | 0.3 |
|
||||
| 日期 | 2026-08-19 |
|
||||
| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[并行实验 PRD](../experiments/parallel-experiments-prd.md)、[分区记忆 PRD](../memory/partitioned-memory-prd.md) |
|
||||
| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[并行实验 PRD](../parallel-experiments/prd.md)、[分区记忆 PRD](../memory/prd.md) |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# 会话监督
|
||||
|
||||
会话监督定义对长会话、工具执行和异常状态的观察、判断与介入边界。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [会话监督 PRD](./prd.md) | 监督目标、证据、介入方式和产品验收 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
+1
-1
@@ -8,7 +8,7 @@
|
||||
| 版本 | 0.2 |
|
||||
| 日期 | 2026-08-18 |
|
||||
| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md) |
|
||||
| 界面归属 | [通用助手工作栏与执行空间](../assistant-experience/assistant-workbar-and-execution-spaces-prd.md) |
|
||||
| 界面归属 | [通用助手工作栏与执行空间](../assistant-workbar/prd.md) |
|
||||
| 体验参考 | GoodBuddy 魔法笔记 AI 评论流 |
|
||||
|
||||
## 1. 背景
|
||||
@@ -0,0 +1,12 @@
|
||||
# DeepSeek Harness Runtime
|
||||
|
||||
本功能定义 DeepSeek Harness 作为 GoodBuddy 本机 Agent Runtime 的产品接入、控制面、
|
||||
插件市场、权限和打包边界。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [技术设计](./technical-design.md) | Runtime 产品与技术方案、协议、插件、打包、测试和验收 |
|
||||
|
||||
现有文档同时包含部分 PRD、功能逻辑和进度内容，后续修改该 Runtime 时再按标准职责拆分。
|
||||
+1
-1
@@ -535,7 +535,7 @@ Runtime 栏目入口始终存在，并采用统一监督模型；内部再按用
|
||||
显示 OpenCode、Continue 或 DSH 的具体区域。未支持能力不渲染空卡片或一排禁用按钮，而是
|
||||
在用户需要理解缺口时显示原因和可执行入口。跟随模式切换 Runtime、Conversation 或 Task
|
||||
时必须清理上一归属的聚合执行状态，固定目标则保持不变。完整工作栏契约见
|
||||
[通用助手工作栏与执行空间 PRD](../prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)。
|
||||
[通用助手工作栏与执行空间 PRD](../assistant-workbar/prd.md)。
|
||||
|
||||
所有未来的 Subagent、Job、Workflow、Hook 和会话操作仍须经过 Main 的 Runtime 边界，保留取消、超时、权限、Task/Job/Subjob 层级、用量和活动审计。高风险动作在侧栏就地确认，运行结果进入活动与成果记录，不以 Composer 按钮代替监督面板。DeepSeek Harness 首版仍不加载这些服务，本节只确定未来跨 Runtime 的产品位置和协议归属。
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# 文档处理
|
||||
|
||||
文档处理负责聊天附件和知识库导入中的文本提取、格式转换与本地 OCR。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [文档解析与本地 OCR PRD](./prd.md) | 产品范围、解析策略、OCR 模型管理和验收 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 全双工语音
|
||||
|
||||
全双工语音定义持续听说、打断、语音活动检测、本地与远端推理以及多平台音频边界。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [技术设计](./technical-design.md) | 产品目标、交互流程、音频架构、模型、打包和实施状态 |
|
||||
|
||||
现有文档是综合设计，尚未按 PRD、User Stories、功能逻辑、UI 和进度职责拆分。
|
||||
+2
-2
@@ -10,7 +10,7 @@
|
||||
| 日期 | 2026-08-19 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
|
||||
| 相关基线 | [跨平台助手产品设计](../design/cross-platform-assistant-product-design.md)、[长期助手路线图](../roadmap/long-term-assistant-roadmap.md)、[统一界面设计系统](../../UI-DESIGN.md) |
|
||||
| 相关基线 | [长期助手路线图](../../roadmap/long-term-assistant-roadmap.md)、[统一界面设计系统](../../../UI-DESIGN.md) |
|
||||
|
||||
本文定义 GoodBuddy 中类似自然通话的全双工实时语音能力，包括本地与云端语音引擎、
|
||||
音频平面、会话状态、打断语义、工具审批、数据留存、失败恢复、跨平台交付和验收指标。
|
||||
@@ -831,7 +831,7 @@ Endpoint 不能因为 URL 相似就被标记为实时语音。
|
||||
- 本地模块化引擎作为 Windows、macOS、Linux x64/arm64 的统一功能基线。
|
||||
- 在线 ASR、VAD 和轻量 TTS 权重不内置，继续使用按需下载和 ZIP 离线迁移。
|
||||
- GoodBuddy 托管模型的下载遵守
|
||||
[平台功能页签与模型下载源设计](./model-download-source-design.md)，使用用户显式选择的
|
||||
[平台功能页签与模型下载源设计](../../architecture/model-download-source-design.md)，使用用户显式选择的
|
||||
ModelScope 或 Hugging Face，失败时不切换来源。
|
||||
- 云端 Adapter 在六个平台复用同一契约，并分别验证 Electron WebRTC/WebSocket 行为。
|
||||
- 本地原生引擎按 Adapter 声明平台与硬件，不伪装成全平台能力。
|
||||
@@ -0,0 +1,11 @@
|
||||
# 应用内反馈
|
||||
|
||||
应用内反馈负责用户在 GoodBuddy 中提交反馈、附带受控诊断并获得提交状态。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [技术设计](./technical-design.md) | 产品流程、数据边界、接口、UI 接入和验收 |
|
||||
|
||||
现有文档是综合设计，尚未按标准职责拆分。
|
||||
+1
-1
@@ -10,7 +10,7 @@
|
||||
| 日期 | 2026-08-25 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
|
||||
| 相关基线 | [统一界面设计系统](../../UI-DESIGN.md)、[GoodBuddy 文档导航](../README.md) |
|
||||
| 相关基线 | [统一界面设计系统](../../../UI-DESIGN.md) |
|
||||
|
||||
本文定义 GoodBuddy 桌面端的应用内反馈入口、数据边界、Renderer / Preload /
|
||||
Main 进程职责、公共 API 对接、失败处理和验收方法。反馈平台服务端、管理后台、
|
||||
@@ -0,0 +1,14 @@
|
||||
# 知识库
|
||||
|
||||
知识库负责资料导入、解析、分块、索引、检索、图谱和带来源的知识问答。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [知识库检索与分块增强 PRD](./prd.md) | 检索、分块、诊断和产品验收 |
|
||||
| [User Stories](./user-stories.md) | 知识使用者、维护者和调试者场景 |
|
||||
| [本地文本向量技术设计](./local-embedding-technical-design.md) | 本地与兼容向量连接、模型包、索引和进程边界 |
|
||||
| [知识检索评估](./retrieval-evaluation.md) | 检索质量评估方法、数据集、指标和门槛 |
|
||||
|
||||
当前尚未拆出统一功能逻辑、UI 设计和功能进度文档。
|
||||
+3
-3
@@ -10,7 +10,7 @@
|
||||
| 日期 | 2026-08-22 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
|
||||
| 相关基线 | [知识库检索与分块增强 PRD](../prd/knowledge/knowledge-rag-enhancement-prd.md)、[模型下载源设计](./model-download-source-design.md)、[知识检索评估](../quality/knowledge-retrieval-evaluation.md)、[统一界面设计系统](../../UI-DESIGN.md) |
|
||||
| 相关基线 | [知识库检索与分块增强 PRD](./prd.md)、[模型下载源设计](../../architecture/model-download-source-design.md)、[知识检索评估](./retrieval-evaluation.md)、[统一界面设计系统](../../../UI-DESIGN.md) |
|
||||
|
||||
本文定义 GoodBuddy 的文本向量模型产品形态，包括 GoodBuddy 提供的内置本地连接、
|
||||
用户添加的 OpenAI 兼容连接、模型管理界面、进程边界、编码契约、索引兼容性、失败状态
|
||||
@@ -912,7 +912,7 @@ Endpoint、编码配置或服务端稳定模型摘要变化。
|
||||
- 目录只包含元数据，不包含模型权重。
|
||||
- 每个来源的文件固定不可变 Revision、URL、字节数和 SHA-256。
|
||||
- 实际下载使用“平台功能 → 通用设置”中显式选择的 ModelScope 或 Hugging Face，完整
|
||||
来源契约以[平台功能页签与模型下载源设计](./model-download-source-design.md)为准。
|
||||
来源契约以[平台功能页签与模型下载源设计](../../architecture/model-download-source-design.md)为准。
|
||||
- 下载写入随机暂存目录和 `.partial` 文件。
|
||||
- 禁止未声明重定向到其他主机。
|
||||
- 每个文件边下载边计算摘要。
|
||||
@@ -1084,7 +1084,7 @@ GoodBuddy 只持续显示规范化 Endpoint 主机、实际维度和诊断结果
|
||||
4. **质量评测**：中文、中英文混合、跨语言和代码标识固定样例。
|
||||
5. **平台评测**：六个平台的安装、加载、取消、退出和资源。
|
||||
|
||||
现有[知识检索评估](../quality/knowledge-retrieval-evaluation.md)中的确定性内存 Provider
|
||||
现有[知识检索评估](./retrieval-evaluation.md)中的确定性内存 Provider
|
||||
用于验证生产检索管道，不代表真实模型质量。内置模型需要单独的可选本地评测命令，
|
||||
该命令不读取用户数据库、不联网、不进入默认 CI。
|
||||
|
||||
+3
-3
@@ -9,7 +9,7 @@
|
||||
| 日期 | 2026-08-22 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 实施范围 | 第一阶段：可用、可见、可诊断；第二阶段：可调、可优化、可维护 |
|
||||
| 相关设计 | [本地文本向量模型与连接设计](../../architecture/local-text-embedding-model-design.md) |
|
||||
| 相关设计 | [本地文本向量模型与连接设计](./local-embedding-technical-design.md) |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
@@ -49,7 +49,7 @@ OpenAI 兼容向量模型、RRF 混合检索、知识图谱、任务状态和来
|
||||
跨平台向量扩展前，接受本地 CPU 线性扫描，并持续显示性能诊断。
|
||||
9. 向量索引兼容性同时校验 Provider、Model、维度和 Provider Fingerprint。
|
||||
同名模型切换端点后，旧向量不能继续参与召回。Fingerprint 的完整模型、编码与
|
||||
数据路径定义以[本地文本向量模型与连接设计](../../architecture/local-text-embedding-model-design.md)
|
||||
数据路径定义以[本地文本向量模型与连接设计](./local-embedding-technical-design.md)
|
||||
为准。
|
||||
10. 失败或取消的重建不能停用上一版已就绪索引。新索引只有完整校验成功后才
|
||||
原子替换当前服务版本。
|
||||
@@ -171,7 +171,7 @@ OpenAI 兼容向量模型、RRF 混合检索、知识图谱、任务状态和来
|
||||
|
||||
全局向量模型仍在“设置 → 模型连接 → 向量模型”中配置。GoodBuddy 内置连接和用户添加的
|
||||
OpenAI 兼容连接使用同一连接列表；其界面、数据路径及切换语义以
|
||||
[本地文本向量模型与连接设计](../../architecture/local-text-embedding-model-design.md)
|
||||
[本地文本向量模型与连接设计](./local-embedding-technical-design.md)
|
||||
为准，知识库页面只显示当前模型、索引兼容性、覆盖率和重建操作。“模型连接”是设置入口
|
||||
名称，不表示向量连接可以分配给 Agent Runtime；项目 Runtime 和 Agent Runtime 的模型
|
||||
选择中不显示向量连接。
|
||||
+1
-1
@@ -7,7 +7,7 @@
|
||||
| 状态 | 实施中 |
|
||||
| 版本 | 0.1 |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 关联 PRD | [知识库检索与分块增强 PRD](./knowledge-rag-enhancement-prd.md) |
|
||||
| 关联 PRD | [知识库检索与分块增强 PRD](./prd.md) |
|
||||
|
||||
## 1. 角色
|
||||
|
||||
@@ -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、技术设计和进度文档。
|
||||
@@ -7,7 +7,7 @@
|
||||
| 状态 | 设计中 |
|
||||
| 版本 | 0.3 |
|
||||
| 日期 | 2026-08-19 |
|
||||
| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[智能心跳 PRD](../smart-heartbeat/smart-heartbeat-prd.md)、[Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) |
|
||||
| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[智能心跳 PRD](../smart-heartbeat/prd.md)、[Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# 并行实验
|
||||
|
||||
并行实验定义多个候选方案、模型或执行分支的受控比较、评估与结果选择。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [并行实验工作台 PRD](./prd.md) | 实验对象、工作台流程、评估和验收 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
@@ -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 传输、安装事务、更新和恢复边界 |
|
||||
|
||||
现有文档包含产品、功能逻辑和进度事实，后续修改远程功能时再按标准职责拆分。
|
||||
+1
-1
@@ -13,7 +13,7 @@ Node，installer 由 GoodBuddy 桌面控制面打包并通过固定 SSH prepare
|
||||
bootstrap 能力元数据。公开直连能力仍须完成本文末尾 GitHub/北京镜像、Linux x64/arm64、
|
||||
取消和离线 GoodBuddy 传输的真实 Host 验收；本文
|
||||
不表示这些验收或新的 Agent 发布已经发生。当前实现细节同时以
|
||||
[SSH 远程主机与 GoodBuddy Agent 实现说明](./remote-host-and-goodbuddy-agent-design.md)
|
||||
[SSH 远程主机与 GoodBuddy Agent 实现说明](./technical-design.md)
|
||||
和源码为准。
|
||||
|
||||
## 设计结论
|
||||
+3
-3
@@ -5,7 +5,7 @@
|
||||
本文记录截至 2026-08-31 的当前代码实现，不定义额外的信任框架。“新增 Host 只探测、Host 卡片手动准备
|
||||
Agent/Runtime、Host 直接从 GitHub/北京镜像下载、项目始终使用 Host current 环境”已经完成源码接线，
|
||||
详细事务与验收边界见
|
||||
[SSH Host 远程环境准备与直连下载设计](./remote-host-environment-provisioning-design.md)；
|
||||
[SSH Host 远程环境准备与直连下载设计](./environment-provisioning-technical-design.md)；
|
||||
控制面直连源码可直接使用既有 package format v1 包，不等待携带 installer 的新 Agent
|
||||
包，也不通过额外目录元数据判断 bootstrap 能力；公开能力仍等待 GitHub/北京镜像、
|
||||
Linux x64/arm64、取消和离线 GoodBuddy 传输的真实 Host 验收。
|
||||
@@ -144,7 +144,7 @@ Detached GoodBuddy Agent
|
||||
环境；打开或切换只读取本地配置。Workspace/Runtime 实际使用时从 Host current registry
|
||||
和当前 Agent 连接取得 live identity，不再扫描、下载、上传或发布 Agent/Runtime。完整
|
||||
事务、兼容边界和验收要求以
|
||||
[Host 环境准备设计](./remote-host-environment-provisioning-design.md) 为准。
|
||||
[Host 环境准备设计](./environment-provisioning-technical-design.md) 为准。
|
||||
- 打开新建/项目设置弹窗只读取本地 Host 验证记录，不并发检查所有 Host；目录浏览或保存
|
||||
才连接所选 Host。
|
||||
- 项目选择器中的管理操作默认浮动隐藏，在悬停、键盘焦点或触屏环境显示。管理任意已保存
|
||||
@@ -176,7 +176,7 @@ Main 传入已规范化的绝对 POSIX root。Agent 返回 Workspace identity、
|
||||
selection，Renderer 会恢复为当前 OpenCode 配置；Main 的远程请求校验仍是最终边界。
|
||||
本机配置的 SKILL 包和 stdio MCP Server 不上传或分配给远程 Runtime；远程 ACP Session
|
||||
继续使用空 MCP Server 列表。Node.js、Python 等本机工具环境同样不修改或同步到 Host，
|
||||
完整边界见[本机工具环境设计与实施计划](./local-tool-environment-design.md)。
|
||||
完整边界见[本机工具环境](../local-tool-environment/README.md)。
|
||||
|
||||
### Ask
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# Smart Heartbeat
|
||||
|
||||
Smart Heartbeat 负责按计划或条件主动检查范围内信息，并生成可监督的建议或任务。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [智能心跳 PRD](./prd.md) | 用户目标、范围、计划、运行和产品验收 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
+1
-1
@@ -11,7 +11,7 @@
|
||||
| 文档角色 | 智能心跳当前能力、权威入口、范围和长期边界 |
|
||||
| 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md) |
|
||||
| 相关架构 | [自动化、监督与记忆平台总体设计](../../architecture/automation-platform-architecture.md) |
|
||||
| 相关界面 | [通用助手工作栏与执行空间 PRD](../assistant-experience/assistant-workbar-and-execution-spaces-prd.md) |
|
||||
| 相关界面 | [通用助手工作栏与执行空间 PRD](../assistant-workbar/prd.md) |
|
||||
| Task 模型 | [Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) |
|
||||
|
||||
> 本文区分近期实施与长期方向。未完成设计的“未来分区记忆”不得转写为数据结构、状态机、
|
||||
+1
-1
@@ -8,7 +8,7 @@
|
||||
| 版本 | 0.3 |
|
||||
| 日期 | 2026-08-19 |
|
||||
| 依赖 | [Task 与 Job 统一领域模型](./task-and-job-model.md) |
|
||||
| 界面归属 | [通用助手工作栏与执行空间](../assistant-experience/assistant-workbar-and-execution-spaces-prd.md) |
|
||||
| 界面归属 | [通用助手工作栏与执行空间](../assistant-workbar/prd.md) |
|
||||
|
||||
## 1. 产品定义
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# 微信消息通道
|
||||
|
||||
微信消息通道负责将微信连接、项目、工作目录、Runtime 和工作模式接入 GoodBuddy。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [微信 ClawBot 通道 PRD](./prd.md) | 通道连接、项目绑定、消息处理和验收 |
|
||||
|
||||
当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
|
||||
@@ -9,7 +9,7 @@
|
||||
| 版本 | 0.4 |
|
||||
| 日期 | 2026-08-22 |
|
||||
| 适用产品 | GoodBuddy 桌面端 |
|
||||
| 相关设计 | [通用助手工作栏与执行空间 PRD](../prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)、[Task 与 Job 统一领域模型](../prd/task-and-job/task-and-job-model.md)、[智能心跳 PRD](../prd/smart-heartbeat/smart-heartbeat-prd.md)、[全双工实时语音交互设计](../architecture/full-duplex-voice-design.md) |
|
||||
| 相关设计 | [通用助手工作栏与执行空间 PRD](../features/assistant-workbar/prd.md)、[Task 与 Job 统一领域模型](../features/task-and-job/task-and-job-model.md)、[智能心跳 PRD](../features/smart-heartbeat/prd.md)、[全双工实时语音交互设计](../features/full-duplex-voice/technical-design.md) |
|
||||
|
||||
## 1. 文档目标
|
||||
|
||||
@@ -58,7 +58,7 @@ GoodBuddy 应能够：
|
||||
### 3.2 右侧工作栏
|
||||
|
||||
本节的范围、选择、执行空间与安全契约以
|
||||
[通用助手工作栏与执行空间 PRD](../prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md) 为准。
|
||||
[通用助手工作栏与执行空间 PRD](../features/assistant-workbar/prd.md) 为准。
|
||||
|
||||
#### 任务中心
|
||||
|
||||
@@ -208,7 +208,7 @@ GoodBuddy 应能够：
|
||||
|
||||
- 当前已提供点击开始、再次点击停止或到达 20 秒上限后停止的本地一次性语音听写。
|
||||
- 转写结果先进入可编辑输入框，不自动发送。
|
||||
- 后续按[全双工实时语音交互设计](../architecture/full-duplex-voice-design.md)增加持续听说、
|
||||
- 后续按[全双工实时语音交互设计](../features/full-duplex-voice/technical-design.md)增加持续听说、
|
||||
Barge-in、流式文本转语音、本地与云端显式语音引擎。
|
||||
- 活动会话冻结引擎、Provider、模型、地域、数据位置和能力；引擎失败时明确停止或重试
|
||||
当前选择，不在本地/云端、原生/模块化、语音/文本之间静默降级。
|
||||
|
||||
@@ -89,7 +89,7 @@
|
||||
- 发布说明准确标注已验证架构和仍未验证范围。
|
||||
- **外部依赖：** Agent 发布审批、双架构正式产物、真实 Linux arm64 环境。
|
||||
- **起始证据：** `package.json`、`agent-runtime-lock.json`、
|
||||
`docs/architecture/remote-host-and-goodbuddy-agent-design.md`。
|
||||
`docs/features/remote-host/technical-design.md`。
|
||||
|
||||
### REL-02 正式 Latest 签名门槛
|
||||
|
||||
@@ -208,7 +208,7 @@
|
||||
- **验收：** 创建、编辑、重启恢复和到期触发均按本地日历执行且不重复。
|
||||
- **依赖：** `FUN-01`、`FUN-07`。
|
||||
- **起始证据：** `src/shared/assistant-contracts.ts`、
|
||||
`docs/prd/task-and-job/scheduled-task-prd.md`。
|
||||
`docs/features/task-and-job/scheduled-task-prd.md`。
|
||||
|
||||
### FUN-07 时区和错过执行策略
|
||||
|
||||
@@ -222,7 +222,7 @@
|
||||
- 重启或系统恢复后不会形成补跑风暴。
|
||||
- 时区和策略可创建、编辑、持久化并在界面复现。
|
||||
- **起始证据：** `src/main/assistant/assistant-database.ts`、
|
||||
`docs/prd/task-and-job/scheduled-task-prd.md`。
|
||||
`docs/features/task-and-job/scheduled-task-prd.md`。
|
||||
|
||||
### FUN-08 旧版 Office 文件
|
||||
|
||||
|
||||
Reference in New Issue
Block a user