diff --git a/AGENTS.md b/AGENTS.md index 946ce60c..b2b84cd7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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//`, 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 diff --git a/README.md b/README.md index 78d1565d..7122f7a9 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,9 @@ GoodBuddy是一个开箱即用的 AI 生产平台，安全、跨平台、本地 ![GoodBuddy 智能心跳](docs/screenshots/smart-heartbeat.png) -完整功能和路线图见 [FEATURES.md](FEATURES.md)，产品、架构、设计与质量文档见 -[文档导航](docs/README.md)。 +完整功能和路线图见 [FEATURES.md](FEATURES.md)，产品功能文档位于 +[`docs/features`](./docs/features/)，维护规范见 +[`docs/features/AGENTS.md`](./docs/features/AGENTS.md)。 ## 安装 diff --git a/UI-DESIGN.md b/UI-DESIGN.md index 64747f1b..631ae4d2 100644 --- a/UI-DESIGN.md +++ b/UI-DESIGN.md @@ -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 能力自动增删稳定应用目录入口。 diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index d398ed53..00000000 --- a/docs/README.md +++ /dev/null @@ -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) 为准。 diff --git a/docs/architecture/automation-platform-architecture.md b/docs/architecture/automation-platform-architecture.md index 40afbec1..94f4cd65 100644 --- a/docs/architecture/automation-platform-architecture.md +++ b/docs/architecture/automation-platform-architecture.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) diff --git a/docs/architecture/local-tool-environment-design.md b/docs/architecture/local-tool-environment-design.md deleted file mode 100644 index 72e329f3..00000000 --- a/docs/architecture/local-tool-environment-design.md +++ /dev/null @@ -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 - -``` - -注入点包括： - -- 内置 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 -``` - -实现复用 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 "/scripts/example.js" -python "/scripts/example.py" -python -m pip install -r "/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 的远端服务依赖由服务部署方负责。 diff --git a/docs/architecture/model-download-source-design.md b/docs/architecture/model-download-source-design.md index e43c8e51..0bf94887 100644 --- a/docs/architecture/model-download-source-design.md +++ b/docs/architecture/model-download-source-design.md @@ -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。 diff --git a/docs/features/AGENTS.md b/docs/features/AGENTS.md new file mode 100644 index 00000000..36566d6e --- /dev/null +++ b/docs/features/AGENTS.md @@ -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// + 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. diff --git a/docs/features/assistant-workbar/README.md b/docs/features/assistant-workbar/README.md new file mode 100644 index 00000000..26db55e7 --- /dev/null +++ b/docs/features/assistant-workbar/README.md @@ -0,0 +1,13 @@ +# 助手工作栏 + +助手工作栏统一承载本机与远程执行空间、Task、成果、文件、浏览器和终端等持续工作界面。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [通用助手工作栏与执行空间 PRD](./prd.md) | 工作栏整体产品范围、执行空间和各工作面板归属 | +| [多终端页签 PRD](./terminal-tabs-prd.md) | 多终端 Tab、目标选择、关闭确认和终端生命周期 | + +当前尚未拆出独立 User Stories、功能逻辑、UI 设计、技术设计和进度文档；相关内容仍保留在 +两份现有 PRD 中，后续实际维护该功能时按职责拆分。 diff --git a/docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md b/docs/features/assistant-workbar/prd.md similarity index 97% rename from docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md rename to docs/features/assistant-workbar/prd.md index 25e7dce2..3609ac8f 100644 --- a/docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md +++ b/docs/features/assistant-workbar/prd.md @@ -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) 定义视觉、语义、响应式和无障碍规则。 diff --git a/docs/prd/assistant-experience/workbar-terminal-tabs-prd.md b/docs/features/assistant-workbar/terminal-tabs-prd.md similarity index 97% rename from docs/prd/assistant-experience/workbar-terminal-tabs-prd.md rename to docs/features/assistant-workbar/terminal-tabs-prd.md index f0ef82d5..25951615 100644 --- a/docs/prd/assistant-experience/workbar-terminal-tabs-prd.md +++ b/docs/features/assistant-workbar/terminal-tabs-prd.md @@ -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 保存、环境准备和项目使用之间的职责。 diff --git a/docs/features/computer-control/README.md b/docs/features/computer-control/README.md new file mode 100644 index 00000000..12352103 --- /dev/null +++ b/docs/features/computer-control/README.md @@ -0,0 +1,11 @@ +# 电脑控制 + +电脑控制包含 GoodBuddy 对浏览器和客户端桌面能力的产品实现与平台适配状态。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [功能进度](./progress.md) | 当前已实现能力、缺陷修复、平台限制和验证状态 | + +当前只有进度文档；产品需求、功能逻辑、UI 和技术设计尚未从历史实现记录中独立整理。 diff --git a/docs/status/computer-control-implementation-status.md b/docs/features/computer-control/progress.md similarity index 100% rename from docs/status/computer-control-implementation-status.md rename to docs/features/computer-control/progress.md diff --git a/docs/features/continuous-learning/README.md b/docs/features/continuous-learning/README.md new file mode 100644 index 00000000..c885f9b7 --- /dev/null +++ b/docs/features/continuous-learning/README.md @@ -0,0 +1,11 @@ +# 持续学习 + +持续学习定义 GoodBuddy 如何从运行结果、评估证据和人工反馈中形成可验证的改进闭环。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [持续学习与评估门 PRD](./prd.md) | 产品目标、学习边界、评估门和验收要求 | + +当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。 diff --git a/docs/prd/learning/continuous-learning-prd.md b/docs/features/continuous-learning/prd.md similarity index 98% rename from docs/prd/learning/continuous-learning-prd.md rename to docs/features/continuous-learning/prd.md index 358fb853..f4286fda 100644 --- a/docs/prd/learning/continuous-learning-prd.md +++ b/docs/features/continuous-learning/prd.md @@ -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. 背景 diff --git a/docs/features/conversation-supervision/README.md b/docs/features/conversation-supervision/README.md new file mode 100644 index 00000000..5524f2db --- /dev/null +++ b/docs/features/conversation-supervision/README.md @@ -0,0 +1,11 @@ +# 会话监督 + +会话监督定义对长会话、工具执行和异常状态的观察、判断与介入边界。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [会话监督 PRD](./prd.md) | 监督目标、证据、介入方式和产品验收 | + +当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。 diff --git a/docs/prd/supervision/conversation-supervision-prd.md b/docs/features/conversation-supervision/prd.md similarity index 99% rename from docs/prd/supervision/conversation-supervision-prd.md rename to docs/features/conversation-supervision/prd.md index e6f27019..265deab7 100644 --- a/docs/prd/supervision/conversation-supervision-prd.md +++ b/docs/features/conversation-supervision/prd.md @@ -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. 背景 diff --git a/docs/features/deepseek-harness/README.md b/docs/features/deepseek-harness/README.md new file mode 100644 index 00000000..17545fb1 --- /dev/null +++ b/docs/features/deepseek-harness/README.md @@ -0,0 +1,12 @@ +# DeepSeek Harness Runtime + +本功能定义 DeepSeek Harness 作为 GoodBuddy 本机 Agent Runtime 的产品接入、控制面、 +插件市场、权限和打包边界。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [技术设计](./technical-design.md) | Runtime 产品与技术方案、协议、插件、打包、测试和验收 | + +现有文档同时包含部分 PRD、功能逻辑和进度内容，后续修改该 Runtime 时再按标准职责拆分。 diff --git a/docs/architecture/deepseek-harness-runtime-design.md b/docs/features/deepseek-harness/technical-design.md similarity index 99% rename from docs/architecture/deepseek-harness-runtime-design.md rename to docs/features/deepseek-harness/technical-design.md index 2cccce89..811569b0 100644 --- a/docs/architecture/deepseek-harness-runtime-design.md +++ b/docs/features/deepseek-harness/technical-design.md @@ -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 的产品位置和协议归属。 diff --git a/docs/features/document-processing/README.md b/docs/features/document-processing/README.md new file mode 100644 index 00000000..47f10d8e --- /dev/null +++ b/docs/features/document-processing/README.md @@ -0,0 +1,11 @@ +# 文档处理 + +文档处理负责聊天附件和知识库导入中的文本提取、格式转换与本地 OCR。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [文档解析与本地 OCR PRD](./prd.md) | 产品范围、解析策略、OCR 模型管理和验收 | + +当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。 diff --git a/docs/prd/document-processing/document-extraction-and-local-ocr.md b/docs/features/document-processing/prd.md similarity index 100% rename from docs/prd/document-processing/document-extraction-and-local-ocr.md rename to docs/features/document-processing/prd.md diff --git a/docs/features/full-duplex-voice/README.md b/docs/features/full-duplex-voice/README.md new file mode 100644 index 00000000..54f3cc77 --- /dev/null +++ b/docs/features/full-duplex-voice/README.md @@ -0,0 +1,11 @@ +# 全双工语音 + +全双工语音定义持续听说、打断、语音活动检测、本地与远端推理以及多平台音频边界。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [技术设计](./technical-design.md) | 产品目标、交互流程、音频架构、模型、打包和实施状态 | + +现有文档是综合设计，尚未按 PRD、User Stories、功能逻辑、UI 和进度职责拆分。 diff --git a/docs/architecture/full-duplex-voice-design.md b/docs/features/full-duplex-voice/technical-design.md similarity index 99% rename from docs/architecture/full-duplex-voice-design.md rename to docs/features/full-duplex-voice/technical-design.md index ccc56324..dfdaabfa 100644 --- a/docs/architecture/full-duplex-voice-design.md +++ b/docs/features/full-duplex-voice/technical-design.md @@ -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 声明平台与硬件，不伪装成全平台能力。 diff --git a/docs/features/in-app-feedback/README.md b/docs/features/in-app-feedback/README.md new file mode 100644 index 00000000..cb010c2a --- /dev/null +++ b/docs/features/in-app-feedback/README.md @@ -0,0 +1,11 @@ +# 应用内反馈 + +应用内反馈负责用户在 GoodBuddy 中提交反馈、附带受控诊断并获得提交状态。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [技术设计](./technical-design.md) | 产品流程、数据边界、接口、UI 接入和验收 | + +现有文档是综合设计，尚未按标准职责拆分。 diff --git a/docs/architecture/in-app-feedback-integration-design.md b/docs/features/in-app-feedback/technical-design.md similarity index 99% rename from docs/architecture/in-app-feedback-integration-design.md rename to docs/features/in-app-feedback/technical-design.md index 82a86ba5..a6ab956e 100644 --- a/docs/architecture/in-app-feedback-integration-design.md +++ b/docs/features/in-app-feedback/technical-design.md @@ -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 对接、失败处理和验收方法。反馈平台服务端、管理后台、 diff --git a/docs/features/knowledge-base/README.md b/docs/features/knowledge-base/README.md new file mode 100644 index 00000000..4ef53c97 --- /dev/null +++ b/docs/features/knowledge-base/README.md @@ -0,0 +1,14 @@ +# 知识库 + +知识库负责资料导入、解析、分块、索引、检索、图谱和带来源的知识问答。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [知识库检索与分块增强 PRD](./prd.md) | 检索、分块、诊断和产品验收 | +| [User Stories](./user-stories.md) | 知识使用者、维护者和调试者场景 | +| [本地文本向量技术设计](./local-embedding-technical-design.md) | 本地与兼容向量连接、模型包、索引和进程边界 | +| [知识检索评估](./retrieval-evaluation.md) | 检索质量评估方法、数据集、指标和门槛 | + +当前尚未拆出统一功能逻辑、UI 设计和功能进度文档。 diff --git a/docs/architecture/local-text-embedding-model-design.md b/docs/features/knowledge-base/local-embedding-technical-design.md similarity index 99% rename from docs/architecture/local-text-embedding-model-design.md rename to docs/features/knowledge-base/local-embedding-technical-design.md index e2552a6e..bd215887 100644 --- a/docs/architecture/local-text-embedding-model-design.md +++ b/docs/features/knowledge-base/local-embedding-technical-design.md @@ -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。 diff --git a/docs/prd/knowledge/knowledge-rag-enhancement-prd.md b/docs/features/knowledge-base/prd.md similarity index 99% rename from docs/prd/knowledge/knowledge-rag-enhancement-prd.md rename to docs/features/knowledge-base/prd.md index 35f74ca3..a989bcb3 100644 --- a/docs/prd/knowledge/knowledge-rag-enhancement-prd.md +++ b/docs/features/knowledge-base/prd.md @@ -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 的模型 选择中不显示向量连接。 diff --git a/docs/quality/knowledge-retrieval-evaluation.md b/docs/features/knowledge-base/retrieval-evaluation.md similarity index 100% rename from docs/quality/knowledge-retrieval-evaluation.md rename to docs/features/knowledge-base/retrieval-evaluation.md diff --git a/docs/prd/knowledge/knowledge-rag-enhancement-user-stories.md b/docs/features/knowledge-base/user-stories.md similarity index 99% rename from docs/prd/knowledge/knowledge-rag-enhancement-user-stories.md rename to docs/features/knowledge-base/user-stories.md index 7a70e0d0..03185a1a 100644 --- a/docs/prd/knowledge/knowledge-rag-enhancement-user-stories.md +++ b/docs/features/knowledge-base/user-stories.md @@ -7,7 +7,7 @@ | 状态 | 实施中 | | 版本 | 0.1 | | 日期 | 2026-08-11 | -| 关联 PRD | [知识库检索与分块增强 PRD](./knowledge-rag-enhancement-prd.md) | +| 关联 PRD | [知识库检索与分块增强 PRD](./prd.md) | ## 1. 角色 diff --git a/docs/features/local-tool-environment/README.md b/docs/features/local-tool-environment/README.md new file mode 100644 index 00000000..3dc6bb57 --- /dev/null +++ b/docs/features/local-tool-environment/README.md @@ -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. 每次完成功能阶段后立即更新进度、验证命令和剩余阻塞项。 diff --git a/docs/features/local-tool-environment/logic-design.md b/docs/features/local-tool-environment/logic-design.md new file mode 100644 index 00000000..ea89c0e6 --- /dev/null +++ b/docs/features/local-tool-environment/logic-design.md @@ -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 | diff --git a/docs/features/local-tool-environment/prd.md b/docs/features/local-tool-environment/prd.md new file mode 100644 index 00000000..92b15ac9 --- /dev/null +++ b/docs/features/local-tool-environment/prd.md @@ -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 和生产构建通过。 diff --git a/docs/features/local-tool-environment/progress.md b/docs/features/local-tool-environment/progress.md new file mode 100644 index 00000000..ecfd805a --- /dev/null +++ b/docs/features/local-tool-environment/progress.md @@ -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/技术设计。 diff --git a/docs/features/local-tool-environment/technical-design.md b/docs/features/local-tool-environment/technical-design.md new file mode 100644 index 00000000..04e69d32 --- /dev/null +++ b/docs/features/local-tool-environment/technical-design.md @@ -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` 固定调用 ` -m pip`，避免解释器错配。 + +## 5. Node.js 托管环境 + +托管 Node shim： + +```text +ELECTRON_RUN_AS_NODE=1 +``` + +约束： + +- 复用 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 验证。 diff --git a/docs/features/local-tool-environment/ui-design.md b/docs/features/local-tool-environment/ui-design.md new file mode 100644 index 00000000..ae9c8d36 --- /dev/null +++ b/docs/features/local-tool-environment/ui-design.md @@ -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 +- 远程托管环境 diff --git a/docs/features/local-tool-environment/user-stories.md b/docs/features/local-tool-environment/user-stories.md new file mode 100644 index 00000000..4dbefd46 --- /dev/null +++ b/docs/features/local-tool-environment/user-stories.md @@ -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 diff --git a/docs/features/memory/README.md b/docs/features/memory/README.md new file mode 100644 index 00000000..fb6f7590 --- /dev/null +++ b/docs/features/memory/README.md @@ -0,0 +1,11 @@ +# 记忆 + +记忆定义 GoodBuddy 的用户、项目和会话记忆分区、写入边界、召回和治理。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [分区记忆 PRD](./prd.md) | 记忆范围、分区、生命周期和产品验收 | + +当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。 diff --git a/docs/prd/memory/partitioned-memory-prd.md b/docs/features/memory/prd.md similarity index 99% rename from docs/prd/memory/partitioned-memory-prd.md rename to docs/features/memory/prd.md index f0391a8a..383b569f 100644 --- a/docs/prd/memory/partitioned-memory-prd.md +++ b/docs/features/memory/prd.md @@ -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. 背景 diff --git a/docs/features/parallel-experiments/README.md b/docs/features/parallel-experiments/README.md new file mode 100644 index 00000000..0ca87944 --- /dev/null +++ b/docs/features/parallel-experiments/README.md @@ -0,0 +1,11 @@ +# 并行实验 + +并行实验定义多个候选方案、模型或执行分支的受控比较、评估与结果选择。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [并行实验工作台 PRD](./prd.md) | 实验对象、工作台流程、评估和验收 | + +当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。 diff --git a/docs/prd/experiments/parallel-experiments-prd.md b/docs/features/parallel-experiments/prd.md similarity index 100% rename from docs/prd/experiments/parallel-experiments-prd.md rename to docs/features/parallel-experiments/prd.md diff --git a/docs/features/remote-host/README.md b/docs/features/remote-host/README.md new file mode 100644 index 00000000..d0ac53c0 --- /dev/null +++ b/docs/features/remote-host/README.md @@ -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 传输、安装事务、更新和恢复边界 | + +现有文档包含产品、功能逻辑和进度事实，后续修改远程功能时再按标准职责拆分。 diff --git a/docs/architecture/remote-host-environment-provisioning-design.md b/docs/features/remote-host/environment-provisioning-technical-design.md similarity index 99% rename from docs/architecture/remote-host-environment-provisioning-design.md rename to docs/features/remote-host/environment-provisioning-technical-design.md index 9a419f05..7fe80827 100644 --- a/docs/architecture/remote-host-environment-provisioning-design.md +++ b/docs/features/remote-host/environment-provisioning-technical-design.md @@ -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) 和源码为准。 ## 设计结论 diff --git a/docs/architecture/remote-host-and-goodbuddy-agent-design.md b/docs/features/remote-host/technical-design.md similarity index 99% rename from docs/architecture/remote-host-and-goodbuddy-agent-design.md rename to docs/features/remote-host/technical-design.md index 46c4084b..6d7bf9b9 100644 --- a/docs/architecture/remote-host-and-goodbuddy-agent-design.md +++ b/docs/features/remote-host/technical-design.md @@ -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 diff --git a/docs/features/smart-heartbeat/README.md b/docs/features/smart-heartbeat/README.md new file mode 100644 index 00000000..ed7eb9f2 --- /dev/null +++ b/docs/features/smart-heartbeat/README.md @@ -0,0 +1,11 @@ +# Smart Heartbeat + +Smart Heartbeat 负责按计划或条件主动检查范围内信息，并生成可监督的建议或任务。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [智能心跳 PRD](./prd.md) | 用户目标、范围、计划、运行和产品验收 | + +当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。 diff --git a/docs/prd/smart-heartbeat/smart-heartbeat-prd.md b/docs/features/smart-heartbeat/prd.md similarity index 99% rename from docs/prd/smart-heartbeat/smart-heartbeat-prd.md rename to docs/features/smart-heartbeat/prd.md index 0582bd39..72fc3504 100644 --- a/docs/prd/smart-heartbeat/smart-heartbeat-prd.md +++ b/docs/features/smart-heartbeat/prd.md @@ -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) | > 本文区分近期实施与长期方向。未完成设计的“未来分区记忆”不得转写为数据结构、状态机、 diff --git a/docs/prd/task-and-job/README.md b/docs/features/task-and-job/README.md similarity index 100% rename from docs/prd/task-and-job/README.md rename to docs/features/task-and-job/README.md diff --git a/docs/prd/task-and-job/goal-task-prd.md b/docs/features/task-and-job/goal-task-prd.md similarity index 100% rename from docs/prd/task-and-job/goal-task-prd.md rename to docs/features/task-and-job/goal-task-prd.md diff --git a/docs/prd/task-and-job/job-and-subjob-prd.md b/docs/features/task-and-job/job-and-subjob-prd.md similarity index 100% rename from docs/prd/task-and-job/job-and-subjob-prd.md rename to docs/features/task-and-job/job-and-subjob-prd.md diff --git a/docs/prd/task-and-job/scheduled-task-prd.md b/docs/features/task-and-job/scheduled-task-prd.md similarity index 100% rename from docs/prd/task-and-job/scheduled-task-prd.md rename to docs/features/task-and-job/scheduled-task-prd.md diff --git a/docs/prd/task-and-job/task-and-job-model.md b/docs/features/task-and-job/task-and-job-model.md similarity index 100% rename from docs/prd/task-and-job/task-and-job-model.md rename to docs/features/task-and-job/task-and-job-model.md diff --git a/docs/prd/task-and-job/task-center-prd.md b/docs/features/task-and-job/task-center-prd.md similarity index 98% rename from docs/prd/task-and-job/task-center-prd.md rename to docs/features/task-and-job/task-center-prd.md index 97434b4e..60b5c293 100644 --- a/docs/prd/task-and-job/task-center-prd.md +++ b/docs/features/task-and-job/task-center-prd.md @@ -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. 产品定义 diff --git a/docs/features/wechat-channel/README.md b/docs/features/wechat-channel/README.md new file mode 100644 index 00000000..0277e745 --- /dev/null +++ b/docs/features/wechat-channel/README.md @@ -0,0 +1,11 @@ +# 微信消息通道 + +微信消息通道负责将微信连接、项目、工作目录、Runtime 和工作模式接入 GoodBuddy。 + +## 文档导航 + +| 文档 | 权威职责 | +| --- | --- | +| [微信 ClawBot 通道 PRD](./prd.md) | 通道连接、项目绑定、消息处理和验收 | + +当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。 diff --git a/docs/prd/channels/wechat-clawbot-channel-project-prd.md b/docs/features/wechat-channel/prd.md similarity index 100% rename from docs/prd/channels/wechat-clawbot-channel-project-prd.md rename to docs/features/wechat-channel/prd.md diff --git a/docs/roadmap/long-term-assistant-roadmap.md b/docs/roadmap/long-term-assistant-roadmap.md index cd0bcdac..29c60544 100644 --- a/docs/roadmap/long-term-assistant-roadmap.md +++ b/docs/roadmap/long-term-assistant-roadmap.md @@ -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、模型、地域、数据位置和能力；引擎失败时明确停止或重试 当前选择，不在本地/云端、原生/模块化、语音/文本之间静默降级。 diff --git a/docs/roadmap/product-performance-experience-improvement-plan.md b/docs/roadmap/product-performance-experience-improvement-plan.md index b015fbac..15e213ce 100644 --- a/docs/roadmap/product-performance-experience-improvement-plan.md +++ b/docs/roadmap/product-performance-experience-improvement-plan.md @@ -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 文件