docs: design device sharing network

2026-09-03 16:34:28 +08:00
parent 468cf0483f
commit fba5e1ad30
17 changed files with 2124 additions and 19 deletions
@@ -78,10 +78,16 @@ otherwise.
  POSIX process groups when a child uses an independent process group. Chat
  status checks use a one-shot Runtime probe that is immediately cleaned up
  rather than entering the model-and-project execution cache. Execution
-  Runtimes remain reusable per project, so different projects can run in
-  parallel. Interactive questions are answered only by foreground
-  conversations; scheduled tasks, remote channels, delegated work, and other
-  background runs fail immediately with guidance to rerun in the foreground
+  Runtimes remain reusable per project. GoodBuddy-managed local OpenCode keeps
+  requests in the same conversation ordered, while different conversations in
+  the same project and different projects can run in parallel. Request-scoped
+  dynamic MCP tools remain isolated through default wildcard disablement and
+  explicit current-request enablement. OpenCode and Continue runs do not stop
+  at a fixed tool-call or activity count, and exceeding local display capture
+  capacity truncates the displayed copy without cancelling the native task.
+  Interactive questions are answered only by foreground conversations; scheduled tasks, remote channels,
+  delegated work, and other background runs fail immediately with guidance to
+  rerun in the foreground
  instead of waiting indefinitely. Local OpenCode startup uses the selected
  absolute path directly without checking the file or running `--version`
  first; invalid paths fail at actual launch. On managed Linux ARM Hosts,
@@ -92,9 +98,10 @@ otherwise.
  Features and disabled by default. Disabling it does not affect local
  projects, ordinary desktop capabilities, or desktop releases. When enabled,
  users can manage SSH Hosts with pinned Host Keys, browse bounded remote
-  directories, and create Ask or Execute projects. Ask keeps the Workspace
-  read-only at the Runtime boundary through bubblewrap; Execute has all
-  permissions of the selected SSH account. The Agent owns accepted Prompts,
+  directories, and create Ask or Execute projects. Both modes start the
+  signed Runtime directly without bubblewrap. Ask permits only read tools at
+  the Agent tool-dispatch boundary, while Execute has all permissions of the
+  selected SSH account. The Agent owns accepted Prompts,
  provider/tool rounds, Runtime processes, a stable model ledger, and a bounded
  semantic transcript over a private Unix socket and ACP v4. Work continues on
  the Host after Desktop exit, network loss, or local-process termination.
@@ -128,7 +135,7 @@ otherwise.
  failure, Agent `SIGKILL`/restart, and recovery from a reopened Desktop SQLite
  database. Successful tool START/END events appear exactly once, with no
  Prompt, provider, or tool replay observed. The current source lock and
-  Agent source lock is `0.11.15`, while the current Desktop release candidate
+  Agent source lock is `0.11.16`, while the current Desktop release candidate
  is `0.12.2`; formal publication status follows the separate Agent and Desktop
  release channels.
 - [x] **Manual SSH Host environment provisioning source path**: After Host Key,
@@ -305,8 +312,8 @@ otherwise.
  execution, and coordination with affected running processes remain
  acceptance work. Six-platform release acceptance must not be claimed before
  the applicable checks pass.
- [x] **On-demand built-in MCP**: Knowledge, Magic Notes, and GoodBuddy
-  configuration MCP can be enabled independently and assigned to direct
+- [x] **On-demand built-in MCP**: Knowledge, Magic Notes, GoodBuddy
+  configuration, and built-in browser MCP can be enabled independently and assigned to direct
  models, GoodBuddy-managed OpenCode, and Continue. Settings explicitly marks
  DeepSeek Harness unsupported. Built-in MCP uses short-lived local authority
  for the current request, and user configuration cannot loosen Ask/Execute
@@ -325,6 +332,14 @@ otherwise.
  explicitly does not support Resources.
 - [x] **Local knowledge bases**: Supports file, directory, and web imports,
  SQLite FTS5 retrieval, and source tracing.
+- [ ] **External knowledge-base connections** (planned): Manage Dify, FastGPT,
+  and RAGFlow instances from the existing Knowledge page, then discover and
+  bind remote knowledge bases with provider-specific retrieval settings and
+  citations. External systems provide retrieval only: GoodBuddy does not use
+  their App, Chat, Workflow, or Agent APIs, and does not bulk-sync, locally
+  index, or modify remote content. Bounded cited snippets are retained locally
+  with their conversations. See the
+  [external knowledge-base PRD](./docs/features/knowledge-base/external-knowledge-prd.md).
 - [x] **Knowledge graph**: Supports rule-based, model-based, and hybrid
  extraction plus entity, relationship, alias, and evidence maintenance.
 - [x] **Embedding configuration and retrieval**: Configures compatible
@@ -415,7 +430,7 @@ otherwise.

 ### Browser, communication, voice, and application maintenance

- [x] **Built-in browser for direct models**: Uses GoodBuddy's isolated
+- [x] **Shared built-in browser for runtimes**: Uses GoodBuddy's isolated
  Chromium and never controls a browser installed by the user. A separate
  master switch decides whether Execute receives the capability, with no
  per-use prompt after enablement. The Browser workbar and Agent share the same
@@ -14,6 +14,7 @@
 ### 桌面基础、工作空间与上下文

 - [x] **跨平台桌面应用**：支持 Windows、macOS、Linux，以及 `x64`、`arm64` 发布目标。
+- [x] **信创软硬件覆盖**：正式 Linux 安装包覆盖国产 `x64` 与 `arm64` 架构，可用于统信 UOS、银河麒麟及海光、兆芯、鲲鹏、飞腾等兼容环境。龙芯 LoongArch 另行提供 `loong64` 实验预览版，不属于正式发布矩阵，也未纳入自动更新。这里的覆盖范围不等同于厂商或整机兼容认证，具体状态与限制见[龙芯预览版构建说明](./docs/development/loongarch-preview-build.md)。
 - [x] **可配置全局快捷唤起**：在“平台功能 / 通用设置”中启停或录制 Electron accelerator；默认保留 `CommandOrControl+Shift+Space`，冲突或保存失败时继续使用上一组已注册快捷键，并显示可处理的状态。
 - [x] **Projects、独立对话与会话分支**：按项目隔离上下文，管理会话、附件和 Git 工作区变更；本地会话可在稳定状态下复制当前聊天内容到独立分支，分支持续显示来源徽标且不复制 Task、队列或成果归属；项目选择器区分本地、托管 SSH 与远程消息通道项目，托管 SSH 项目按 Host 分组并在 Host 标题显示真实 Agent 连接状态，项目行只保留远端路径。
 - [x] **文件、截图、窗口、剪贴板上下文**：用户明确选择后才加入模型上下文。
@@ -27,8 +28,8 @@

 - [x] **直连模型 Runtime**：支持问答、知识总结、受控工具执行和图像生成。
 - [x] **直连模型编程 Agent**：本机直连文本模型可在 Execute 模式运行平台 Shell，并可按父请求模式、模型、工作区和能力范围委派一层编程 Subagent；OpenCode、Continue、DeepSeek Harness 和托管 SSH 不重复注入这两个工具。Windows 本机命令与真实模型“修改、测试、修复、复核”闭环已通过，macOS 与 Linux 真机命令仍待对应平台验收。
- [x] **OpenCode 与 Continue**：使用隔离子进程、环境变量白名单、统一配置、取消、总执行时限、有界流式输出和活动记录；共享进程回收逻辑保留 Windows 完整进程树终止，并对采用独立进程组的 POSIX 子进程执行组回收。聊天状态检查使用一次性探测 Runtime 并在返回后立即回收，不进入按模型与项目隔离的执行 Runtime 缓存；执行 Runtime 仍按项目复用，因此不同项目可并行。交互提问只由前台对话回答，定时任务、远程通道和委派等后台执行遇到提问时会立即失败并提示改为前台运行，避免无限等待。本机 OpenCode 启动时直接使用已选择的绝对路径，不预先检查文件或运行 `--version`，路径失效时由实际启动返回错误；托管 Linux ARM Host 激活 Runtime 时复用准备阶段已验证的 registry 和 manifest，不重新哈希或检查完整 OpenCode 二进制。
- [x] **托管 SSH OpenCode 闭环（技术预览）**：该能力由“设置 > 平台功能”中的独立“远程项目（技术预览）”页签控制并默认关闭；关闭时不影响任何本地项目、普通桌面功能或桌面发布。启用后可管理固定 Host Key 的 SSH Host、浏览有界远端目录并创建 Ask/Execute 项目；Ask 在 Runtime 边界通过 bubblewrap 保持 Workspace 只读，Execute 使用所选 SSH 账号的完整权限。Agent 通过私有 Unix socket 和 ACP v4 持有 accepted Prompt、Provider/工具轮次、Runtime 进程、稳定模型 ledger 与有界语义 transcript；Desktop 退出、网络中断或本机进程结束后 Host 继续执行，重启后只 attach 原 controller/binding/operation 并把 provenance 原子归并回原对话，不重发 Prompt。模型 profile 与 API Key 只在当前 accepted operation 生命周期内进入 Agent 内存，不写入 Renderer、SSH 参数、远端环境或磁盘。远端组件不嵌入桌面包，项目切换只更新本地选择且不会连接或下载；设置页只读取小型签名目录并按 Linux x64/arm64 显示本地版本、在线最新兼容版本和“有更新/已是最新”，用户点击后才下载签名 `.gbagent`，也可导入/导出离线包。每个复合包包含 Agent、固定 Node 与由桌面源码统一维护适配的 OpenCode Runtime；在线来源跟随“关于与更新”的 GitHub/北京 OSS 选择，签名累计目录绑定最低桌面版本、Agent 协议、架构、大小、SHA-256 和固定 URL。公钥 registry 接受等价 JSON 空白和换行，但仍严格校验 schema、Ed25519 key、环境与撤销；目录、包、manifest、payload 签名和流式 SHA-256 不变。缺少某架构包只使该架构托管 SSH 不可用。项目只保存 Host、远端路径、Runtime 选择和模式；首次实际使用 Workspace/Runtime 时读取 Host current identity，同一进程内其他项目复用已确认 identity 和 Agent 连接。托管 SSH 会话只显示支持的 OpenCode 选择。同一 Host 可并行运行多个项目和对话；恢复进度分别显示网络、Agent、Runtime、已提交事件 cursor、完成或失败/重试，只阻塞受影响项目。Linux x64 真实 Host 已覆盖短/长 detach、本机 harness 强制结束、并发、SSH relay 丢失、取消、确定/不确定 Provider 失败、Agent `SIGKILL`/重启和 reopened Desktop SQLite 恢复；成功工具 START/END 各一次，未发现 Prompt、Provider 或工具重放。当前 Agent 源码 lock 为 `0.11.15`，Desktop 发布候选为 `0.12.2`；正式发布状态以 Agent 与 Desktop 的独立发布渠道为准。
+- [x] **OpenCode 与 Continue**：使用隔离子进程、环境变量白名单、统一配置、取消、总执行时限、有界流式输出和活动记录；共享进程回收逻辑保留 Windows 完整进程树终止，并对采用独立进程组的 POSIX 子进程执行组回收。聊天状态检查使用一次性探测 Runtime 并在返回后立即回收，不进入按模型与项目隔离的执行 Runtime 缓存；执行 Runtime 仍按项目复用。本机 GoodBuddy 管理的 OpenCode 只对同一会话内的请求保持顺序，不同会话即使属于同一项目也可并行，不同项目同样可并行；请求级动态 MCP 通过默认通配禁用和当前请求精确放行保持隔离。OpenCode 与 Continue 不再按固定工具调用数或活动数中止单次运行，本机展示副本达到容量时只截断后续展示，不取消原生任务。交互提问只由前台对话回答，定时任务、远程通道和委派等后台执行遇到提问时会立即失败并提示改为前台运行，避免无限等待。本机 OpenCode 启动时直接使用已选择的绝对路径，不预先检查文件或运行 `--version`，路径失效时由实际启动返回错误；托管 Linux ARM Host 激活 Runtime 时复用准备阶段已验证的 registry 和 manifest，不重新哈希或检查完整 OpenCode 二进制。
+- [x] **托管 SSH OpenCode 闭环（技术预览）**：该能力由“设置 > 平台功能”中的独立“远程项目（技术预览）”页签控制并默认关闭；关闭时不影响任何本地项目、普通桌面功能或桌面发布。启用后可管理固定 Host Key 的 SSH Host、浏览有界远端目录并创建 Ask/Execute 项目；两种模式都直接启动签名 Runtime，不依赖 bubblewrap。Ask 在 Agent 工具分发边界只允许读取工具，Execute 使用所选 SSH 账号的完整权限。Agent 通过私有 Unix socket 和 ACP v4 持有 accepted Prompt、Provider/工具轮次、Runtime 进程、稳定模型 ledger 与有界语义 transcript；Desktop 退出、网络中断或本机进程结束后 Host 继续执行，重启后只 attach 原 controller/binding/operation 并把 provenance 原子归并回原对话，不重发 Prompt。模型 profile 与 API Key 只在当前 accepted operation 生命周期内进入 Agent 内存，不写入 Renderer、SSH 参数、远端环境或磁盘。远端组件不嵌入桌面包，项目切换只更新本地选择且不会连接或下载；设置页只读取小型签名目录并按 Linux x64/arm64 显示本地版本、在线最新兼容版本和“有更新/已是最新”，用户点击后才下载签名 `.gbagent`，也可导入/导出离线包。每个复合包包含 Agent、固定 Node 与由桌面源码统一维护适配的 OpenCode Runtime；在线来源跟随“关于与更新”的 GitHub/北京 OSS 选择，签名累计目录绑定最低桌面版本、Agent 协议、架构、大小、SHA-256 和固定 URL。公钥 registry 接受等价 JSON 空白和换行，但仍严格校验 schema、Ed25519 key、环境与撤销；目录、包、manifest、payload 签名和流式 SHA-256 不变。缺少某架构包只使该架构托管 SSH 不可用。项目只保存 Host、远端路径、Runtime 选择和模式；首次实际使用 Workspace/Runtime 时读取 Host current identity，同一进程内其他项目复用已确认 identity 和 Agent 连接。托管 SSH 会话只显示支持的 OpenCode 选择。同一 Host 可并行运行多个项目和对话；恢复进度分别显示网络、Agent、Runtime、已提交事件 cursor、完成或失败/重试，只阻塞受影响项目。Linux x64 真实 Host 已覆盖短/长 detach、本机 harness 强制结束、并发、SSH relay 丢失、取消、确定/不确定 Provider 失败、Agent `SIGKILL`/重启和 reopened Desktop SQLite 恢复；成功工具 START/END 各一次，未发现 Prompt、Provider 或工具重放。当前 Agent 源码 lock 为 `0.11.16`，Desktop 发布候选为 `0.12.2`；正式发布状态以 Agent 与 Desktop 的独立发布渠道为准。
 - [x] **SSH Host 手动环境准备源码链路**：Host Key、认证和系统探针成功后先保存 Host，并只读探测共享 Agent/Runtime；保存 Host、打开项目都不自动安装。Host 卡片只有一个按版本事实显示“安装远程环境”“更新远程环境”或“重新安装”的主按钮，次级 SegmentedControl 选择默认且不持久化的“自动”、Host 下载或 GoodBuddy 传输；“版本匹配”badge 不等同环境健康。自动模式只在 operation/prepare 前探测并择一，显式选择保持有效，任何 prepare、commit 或 adoption 失败都不跨 acquisition 自动 fallback。两种方式把同一签名 compound `.gbagent` 交付到固定 staging 后，共用 control-plane prepare、commit、Agent activate/health、Runtime activate、finalize 与显式 cleanup。GoodBuddy 路径可在同一次操作下载并验证缺失候选、缓存并取得 lease，再有界流式 SFTP 上传一个归档和其中已验证的 bootstrap Node，不把约 294 MiB 整包读入 Main `Buffer`；Host 在解包时完成一次完整 payload 校验。未完成操作只记录暂存 cleanup 所需的 operation ID；下次更新尽力清理旧暂存后重新 prepare，不保存远端 metadata 副本，也不让 cleanup 失败阻塞新更新或回滚健康环境。已有项目在实际使用 Workspace/Runtime 时按需解析 Host current identity 并执行固定 `attach-or-bootstrap`，注册后的 health、capabilities 和 prompt 启动不扫描完整 payload。详见 [设计说明](./docs/features/remote-host/environment-provisioning-technical-design.md)。
 - [ ] **SSH Host 环境准备真实 Host 验收**：源码已可使用当前 format v1 包；仍需完成 GitHub、北京镜像、Linux x64/arm64、取消和离线 GoodBuddy 传输的真实 Host 验收。当前状态不表示已发布或已完成真实 Host 测试。
 - [x] **DeepSeek Harness（预览）**：使用 GoodBuddy 固定 Host 和 OpenAI 兼容模型连接；优先使用管理员提供的连接，否则跟随兼容的默认模型或首个兼容连接，无需单独重复选择。Ask 只允许调用 Host 中真实注册的 `read`、`skill` 以及 Main 管理的 Web Search/Fetch 代理，拒绝插件同名冒充，Execute 放行全部已启用内置及插件工具，并以当前用户权限运行。图像输入跟随所选模型连接的能力声明，文本模型在 Host 或模型调用前拒绝图片，图片模型通过有界内联内容和临时 Attachment Store 接收 JPEG/PNG。
@@ -51,10 +52,11 @@
 - [x] **Skills 按需接入**：可分配给直连模型、OpenCode、Continue 和 DeepSeek Harness，并使用有界资源和受控 Runtime 边界。
 - [x] **本机工具执行环境源码链路**：在“能力与工具 > 工具执行环境”中为本机 Skills 与 stdio MCP 选择 GoodBuddy 托管 Node.js、按需安装的托管 Python，或经过真实验证的自定义解释器；提供独立的原生地址/OSS 镜像选择、诊断、安装进度、取消和删除。新的本机 Runtime 与 stdio MCP 获得不可变 PATH 快照，不修改普通终端、系统环境或远程 Host。Windows x64 托管 Node 与原生地址 Python 已通过真实安装验证；托管 Python 归档按目标文件系统验证，Linux 保留大小写不同的合法路径，所有目标仍拒绝完全重复路径和不安全条目。
 - [ ] **本机工具执行环境发布验收**：六个平台/架构的 OSS 镜像对象已完成字节、大小和 SHA-256 公开回读验证。托管 Python 保持按需下载，不向 Desktop 发行包额外带入许可证文件。每个标准打包任务使用目标架构原生 Runner，并在打包前真实安装托管 Python，验证 SSL、pip 与 venv。不可变的 `v0.12.0` 尝试在发布前通过 Windows 与 macOS，但暴露了 Linux TAR 大小写处理问题；`v0.12.1` 在同步 Agent 发布时于原生打包前取消。修正后的 `0.12.2` 候选仍须通过全部六个目标。真实 Skill/MCP、自定义解释器和运行中进程协调仍是待完成验收；完成适用检查前不宣称六平台发布验收通过。
- [x] **内置 MCP 按需接入**：知识库、魔法笔记与 GoodBuddy 配置 MCP 可分别启停，并可分配给直连模型、GoodBuddy 管理的 OpenCode 和 Continue；DeepSeek Harness 在设置中明确显示为暂不支持。内置 MCP 仅通过当前请求的短期本机权限提供，Ask / Execute 读写边界不受用户配置放宽。
+- [x] **内置 MCP 按需接入**：知识库、魔法笔记、GoodBuddy 配置与内置浏览器 MCP 可分别启停，并可分配给直连模型、GoodBuddy 管理的 OpenCode 和 Continue；DeepSeek Harness 在设置中明确显示为暂不支持。内置 MCP 仅通过当前请求的短期本机权限提供，Ask / Execute 读写边界不受用户配置放宽。
 - [x] **MCP Tools**：显式启用的自定义 MCP 可按 Runtime 分配给直连模型、GoodBuddy 管理的 OpenCode、Continue Agent Execute 和 DeepSeek Harness，并仅在 Execute 加载；Agent 子进程只获得按请求签发的本机回环权限，MCP 地址、命令和凭据保留在 Main，动态工具仍会重新发现并经过现有执行记录与权限边界。
 - [x] **MCP Prompts 与 Resources 元数据**：MCP 测试仅在 Server 声明对应能力时发现有界的 Prompt、参数与 Resource 元数据，不读取 Resource 内容；Runtime 支持的 Prompt 可填入聊天草稿后继续编辑。OpenCode 可报告实验性 Resource 清单，Continue 当前版本明确不支持 Resources。
 - [x] **本地知识库**：支持文件、目录和网页导入、SQLite FTS5 检索及来源追溯。
+- [ ] **外部知识库接入**（规划中）：在现有知识库页面管理 Dify、FastGPT 和 RAGFlow 实例；新建知识库时可读取并绑定远端知识库，保留 Provider 专属检索配置和引用。外部系统只负责知识检索，不接入其 App、Chat、Workflow 或 Agent，也不批量同步、本地索引或修改远端内容。被回答引用的有界检索片段随会话保存在本机。详见[外部知识库接入 PRD](./docs/features/knowledge-base/external-knowledge-prd.md)。
 - [x] **知识图谱**：支持规则、模型和混合抽取，以及实体、关系、别名和证据维护。
 - [x] **向量模型配置与检索**：可配置兼容 Embeddings 接口并用于语义检索。
 - [x] **向量诊断与索引任务**：提供真实向量生成诊断、按文档重建进度、取消、失败状态与重启后结果恢复；每篇成功文档立即可用于检索。
@@ -80,7 +82,7 @@

 ### 浏览器、通信、语音与应用维护

- [x] **直连模型内置浏览器**：使用 GoodBuddy 内置的隔离 Chromium，不控制客户端已安装的浏览器；用户通过独立总开关决定是否提供给 Execute，开启后不逐次询问。浏览器工作栏与 Agent 共用同一条按 Conversation 归属的会话和串行操作路径，支持返回、刷新/停止加载、地址输入、前往、交互和关闭；停止加载不会关闭会话，用户导航会改变 Agent 下一步看到的页面。
+- [x] **Runtime 共享内置浏览器**：使用 GoodBuddy 内置的隔离 Chromium，不控制客户端已安装的浏览器；用户通过内置 MCP 总开关和 Runtime 分配决定是否提供给 Execute，开启后不逐次询问。直连模型、GoodBuddy 管理的 OpenCode 和 Continue 通过请求级权限共享按 Conversation 归属的会话和串行操作路径；浏览器工作栏支持返回、刷新/停止加载、地址输入、前往、交互和关闭，用户导航会改变 Agent 下一步看到的页面。
 - [x] **客户端电脑控制工具**：与内置浏览器分开管理，并保留范围、取消、超时、输出边界和执行记录。
 - [x] **远程消息通道项目**：微信 ClawBot、企业微信和钉钉分别拥有系统管理的项目、独立远程会话、工作目录、处理后端、默认 Ask/Execute 模式及任务活动归属；完整回复交由各通道按平台能力控制长度与分段，不再由公共服务统一截断。
 - [x] **微信 ClawBot 扫码与媒体**：通过独立 Sidecar 完成本机扫码、验证码、加密凭据和文字收发；支持个人微信私聊图片与文件，单条消息最多 4 个附件、解密后合计不超过 12MB。
@@ -26,6 +26,28 @@ retrieval, notes, and scheduled tasks. No GoodBuddy account is required.
 Workspace data is stored locally by default. Model endpoints can run on the
 same device, on a private network, or at a provider selected by the user.

+## Highlights
+
+- **Local-first workspace**: No GoodBuddy account is required. Workspace data
+  stays local by default, and users choose where model services run.
+- **Unified Agent Runtimes**: Use direct models, OpenCode, Continue, and the
+  preview DeepSeek Harness from one desktop interface.
+- **Explicit execution boundaries**: `Ask` remains read-only, while `Execute`
+  uses the current account's permissions. Tool activity, cancellation,
+  timeouts, and token usage are recorded.
+- **Broad platform coverage**: Official Linux releases cover `x64` and `arm64`,
+  including compatible distributions used in China's domestic computing
+  ecosystem. A separate
+  experimental `loong64` preview is available for LoongArch systems.
+- **Knowledge and long-running work**: Knowledge bases, graphs, Magic Notes,
+  tasks, and Smart Heartbeat share one desktop workspace.
+
+Platform coverage describes operating-system, instruction-set, and package
+compatibility, not certification for every hardware vendor or distribution
+release. LoongArch is outside the official release matrix; see the
+[LoongArch preview notes](./docs/development/loongarch-preview-build.md) for its
+current limitations.
+
 ## Capabilities

 | Area | Available in GoodBuddy |
@@ -33,7 +55,7 @@ same device, on a private network, or at a provider selected by the user.
 | Agent Runtimes | Direct model connections, OpenCode, Continue, and the preview DeepSeek Harness |
 | Data and execution | Local SQLite storage, read-only `Ask`, full-account `Execute`, and recorded tool activity |
 | Knowledge | File, folder, and web imports with full-text, Chinese phrase, vector, and knowledge graph retrieval |
-| Desktop releases | Windows, macOS, and Linux builds for `x64` and `arm64` |
+| Desktop releases | Official Windows, macOS, and Linux builds for `x64` and `arm64`, plus an experimental LoongArch preview |
 | Integrations | Local or hosted model endpoints, custom MCP servers, WeChat ClawBot, WeCom, and DingTalk |

 ## Product tour
@@ -73,6 +95,9 @@ Download a build from
 | macOS | `x64`, `arm64` | DMG, ZIP |
 | Linux | `x64`, `arm64` | AppImage, DEB, RPM |

+The experimental LoongArch `loong64` build is distributed through a separate
+preview channel on the [product website](https://mesalogo.github.io/goodbuddy/#download).
+
 Desktop installers do not contain remote Agent payloads. Local projects do not
 need an Agent package; managed SSH users download or import one explicitly in
 Settings.
@@ -23,6 +23,16 @@

 GoodBuddy 是用于模型对话、编程 Agent、知识检索、笔记和定时任务的桌面应用。使用 GoodBuddy 无需注册账号，工作数据默认保存在本机。模型服务可以运行在本机、组织内网或用户选择的云端服务。

+## 产品亮点
+
+- **本地优先**：无需注册 GoodBuddy 账号，工作数据默认保存在本机，模型服务由用户选择。
+- **统一 Agent Runtime**：在一个桌面界面中使用直连模型、OpenCode、Continue 和预览版 DeepSeek Harness。
+- **执行边界明确**：`Ask` 保持只读，`Execute` 使用当前账号权限，工具调用、取消、超时和 Token 用量均有记录。
+- **支持信创软硬件**：正式 Linux 版本覆盖国产 `x64` 与 `arm64` 架构，可用于统信 UOS、银河麒麟及海光、兆芯、鲲鹏、飞腾等兼容环境；龙芯 LoongArch 提供独立 `loong64` 实验预览版。
+- **知识与长期工作一体化**：知识库、知识图谱、魔法笔记、任务和智能心跳共享同一个桌面工作空间。
+
+信创支持按操作系统、指令集和安装包兼容性描述，不代表已完成所有厂商、整机和系统版本的兼容认证。龙芯版本尚未进入正式发布矩阵，具体限制见[龙芯预览版说明](./docs/development/loongarch-preview-build.md)。
+
 ## 主要能力

 | 范围 | GoodBuddy 提供的能力 |
@@ -695,7 +695,7 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 - Agent Runtime 页面在低层程序与配置覆盖之外提供“能力与默认配置”区域。能力清单使用共享 `PageTabs`，按 Agents、Tools、Commands、Skills、MCP、Rules、Prompts、Resources、LSP、Formatters 和上下文 11 类单行滚动展示，一次只呈现当前分类的 `tabpanel`；清单只显示 Runtime 自有能力，不混入 GoodBuddy 分配的 Skills、临时 MCP 或 Continue 预设。Tools 必须独立于 Commands、LSP 和 Formatters，显示工具类型、来源及 Ask/Execute 可用性；清单状态必须区分完整、部分、不可用、仅连接和不支持，不能用进程连通性冒充清单可读。
 - “能力与默认配置”只显示一个模块标题，刷新入口位于该标题右侧，能力状态压缩为一行并排在默认 Agent 或 Continue 预设编辑器之前；不得再复制“Runtime 原生能力”等同义标题、说明或状态结论。刷新只更新能力快照，不覆盖未保存的原生定制草稿。
 - OpenCode 的默认 Agent 使用原生下拉选择；Continue 预设编辑器允许管理名称、说明、启用的 Rules 以及 Prompt 名称、说明和正文，并可展开查看原生 Rules 与启用预设 Rules 的最终合并顺序。持久启停仍使用共享 Switch，添加与删除使用明确按钮和可访问名称。
- MCP 设置按“内置 MCP / 直连模型 / 自定义 MCP / 电脑控制”四个同级 `PageTabs` 组织。直连模型中的联网搜索与内置浏览器使用一致的折叠卡片和独立总开关；内置浏览器必须明确说明其操作 GoodBuddy 隔离浏览器，不控制客户端已安装的浏览器，开启后可由 Execute 直接使用，不逐次询问。尚未生效的命名浏览器配置不得显示在界面中，“电脑控制”只显示实际操作客户端电脑的能力。内置 MCP 卡片与 Skills 一样提供持久启停和 Runtime 分配；直连模型、GoodBuddy 管理的 OpenCode 与 Continue 默认选中且可调整，DeepSeek Harness 必须以置灰、未选择和“暂不支持”文案持续显示，不能呈现为可保存的分配。魔法笔记 MCP 的自身启停与平台功能依赖分别显示，依赖未开启时保留用户配置并说明当前不会加载。
+- MCP 设置按“内置 MCP / 直连模型 / 自定义 MCP / 电脑控制”四个同级 `PageTabs` 组织。联网搜索保留在直连模型；内置浏览器归入内置 MCP，提供持久启停和 Runtime 分配，并明确说明其操作 GoodBuddy 隔离浏览器、不控制客户端已安装的浏览器，开启后可由已分配 Runtime 的 Execute 直接使用，不逐次询问。尚未生效的命名浏览器配置不得显示在界面中，“电脑控制”只显示实际操作客户端电脑的能力。内置 MCP 卡片与 Skills 一样提供持久启停和 Runtime 分配；直连模型、GoodBuddy 管理的 OpenCode 与 Continue 默认选中且可调整，DeepSeek Harness 必须以置灰、未选择和“暂不支持”文案持续显示，不能呈现为可保存的分配。魔法笔记 MCP 的自身启停与平台功能依赖分别显示，依赖未开启时保留用户配置并说明当前不会加载。
 - MCP Server 测试结果在同一展开卡片中分组显示 Tools、Prompts 和 Resources 的支持状态、数量与有界元数据；Prompt 参数标明必填项，Resource 只显示 URI、名称、类型和说明，不读取或渲染 Resource 内容。

 ### 13.9 文档解析设置
@@ -0,0 +1,450 @@
+# GoodBuddy 设备共享与 ShareServer 联邦网络总体设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 适用范围 | GoodBuddy 桌面端、ShareServer、网关间联邦协议 |
+| 桌面端设计 | [设备发现与共享](../features/device-sharing/README.md) |
+| 服务端设计 | [ShareServer](../features/share-server/README.md) |
+
+## 1. 文档职责
+
+本文是设备共享网络的跨端权威设计，负责定义拓扑、术语、身份、能力清单、授权计算、任务
+路由、能力分发、协议边界和共同验收标准。桌面端的产品与界面行为由“设备发现与共享”功能
+文档负责，独立 Web 服务由 ShareServer 功能文档负责。
+
+本文描述完整目标系统，不以交付阶段删减领域模型，也不把尚未实现的设计表述为当前能力。
+
+## 2. 核心决策
+
+### 2.1 两个独立产品面
+
+1. **GoodBuddy Desktop** 在设置中提供“设备发现与共享”，默认使用局域网发现与直连，也可
+   由用户额外连接一个或多个 ShareServer。
+2. **ShareServer** 是独立部署、独立升级的 Web 服务，提供组织、设备、能力、权限、更新、
+   联邦、中继和审计管理。它不运行在 Electron Main 中，也不由桌面端代为启动。
+
+### 2.2 能力优先，来源可见
+
+用户日常选择的是能力，不是网络连接。设备、ShareServer 和组织作为能力来源与诊断入口。
+任何调用都必须持续显示提供者、执行位置和数据去向，不能为了统一体验隐藏跨设备或跨组织
+边界。
+
+### 2.3 局域网是默认连接方式，网关是显式附加连接
+
+- 桌面端没有网关配置时，局域网发现、配对、调用和本机共享仍可完整工作。
+- 添加、删除或断开 ShareServer 不改变局域网配对关系。
+- ShareServer 不接管本机局域网发现，也不能静默把局域网设备注册到组织。
+- 同一桌面端可以连接多个 ShareServer；能力来源和授权按连接分别计算。
+
+### 2.4 发现、被发现和开放能力是三个独立动作
+
+- **发现设备**：浏览同一局域网中主动广播的 GoodBuddy 服务。
+- **允许被发现**：广播本设备存在及配对入口。
+- **开放能力**：向指定设备、用户组或组织发布可查看、调用或拉取的能力。
+
+开启其中一项不能推导另外两项已开启。新安装默认不开放能力。
+
+### 2.5 ShareServer 优先作为控制面
+
+ShareServer 负责身份、目录、策略、任务路由、更新和审计。数据面优先在两个已认证端点之间
+直接建立；网络条件不允许时，可按组织策略使用 ShareServer 中继。是否允许中继、正文是否
+端到端加密、是否允许跨组织，由本次任务冻结的策略共同决定。
+
+## 3. 术语
+
+| 术语 | 定义 |
+| --- | --- |
+| `Device` | 安装 GoodBuddy 并拥有稳定设备身份的终端 |
+| `Peer` | 与当前设备存在局域网配对关系的另一台设备 |
+| `ShareServer` | 提供组织控制面和可选数据中继的独立服务 |
+| `Organization` | ShareServer 中隔离成员、设备、能力与策略的管理范围 |
+| `GatewayConnection` | 某台设备与一个 ShareServer 上特定组织身份的连接 |
+| `Capability` | 可被查看、调用或分发的稳定能力标识 |
+| `CapabilityProvider` | 实际持有并执行某项能力的设备或服务节点 |
+| `Publication` | 能力提供者向某一范围发布的可见性和使用声明 |
+| `Grant` | 主体对能力执行某类动作的明确授权 |
+| `Task` | 一次远程能力调用及其输入、执行、输出和终态 |
+| `Package` | 可下载到本机安装的签名能力工件 |
+| `FederationTrust` | 两个组织网关之间经管理员确认的双边信任关系 |
+
+“网关”是 ShareServer 的网络角色；产品名称和代码目录统一使用 `ShareServer` / `shareserver`。
+
+## 4. 系统拓扑
+
+```text
+局域网：
+GoodBuddy Desktop A <-- mDNS 发现 + 配对后 TLS 直连 --> GoodBuddy Desktop B
+
+单组织：
+GoodBuddy Desktop A -- 出站连接 --> ShareServer <-- 出站连接 -- Provider Device B
+
+跨组织：
+Desktop A --> ShareServer A <== 联邦信任 ==> ShareServer B <-- Provider Device B
+```
+
+局域网和网关连接共享能力、授权和任务的领域语义，但不共享发现方式：
+
+| 维度 | 局域网 | ShareServer |
+| --- | --- | --- |
+| 发现来源 | mDNS/DNS-SD 主动广播 | 已配置 URL 或邀请链接 |
+| 初始身份 | 双端验证码确认设备指纹 | 用户登录、设备注册和组织成员身份 |
+| 能力目录 | 已配对设备直接返回 | 服务端按组织策略过滤 |
+| 连接方向 | 配对后直连 | 设备主动建立出站连接 |
+| 管理范围 | 单个设备间授权 | 用户组、组织和联邦授权 |
+| 审计权威 | 两端各自本地记录 | 组织网关记录元数据，两端保留本地记录 |
+
+## 5. 组件边界
+
+### 5.1 GoodBuddy Desktop
+
+- 浏览和广播局域网服务。
+- 创建、确认和撤销点对点配对。
+- 连接 ShareServer，保存脱敏连接信息和本机受保护凭据。
+- 发布用户明确选择的本机能力。
+- 展示经当前身份过滤的能力目录。
+- 在调用前冻结提供者、输入范围、授权和路由。
+- 执行本机提供的任务，或消费远端任务结果。
+- 校验并安装用户明确选择的签名能力包。
+- 保存本机活动记录和可撤销授权。
+
+### 5.2 ShareServer
+
+- 认证用户、设备、服务节点和其他 ShareServer。
+- 管理组织、成员、用户组和设备目录。
+- 接收能力发布并生成权限过滤后的目录。
+- 计算组织强制策略，签发短期任务授权。
+- 路由任务、维护在线状态，并在允许时中继数据。
+- 管理签名包、发布通道、更新策略和撤销。
+- 建立双边联邦关系并限制跨组织可见性与调用。
+- 保存有界审计元数据、用量和管理操作。
+
+### 5.3 能力提供者
+
+- 只执行已发布且本次授权允许的能力。
+- 在执行边界重新验证任务令牌、输入 schema、大小、期限和调用方。
+- 使用自身 Runtime、账号、工作区和数据权限。
+- 返回有界进度、结果、成果或确定终态。
+- 不因收到任务令牌而获得其他能力或任意系统接口。
+
+## 6. 身份与信任
+
+### 6.1 设备身份
+
+每次 GoodBuddy 安装生成稳定设备密钥和自签设备证书，私钥保存在系统安全存储中。对外只
+使用随机设备 ID、公钥指纹、用户设置的设备名称和必要协议版本。操作系统用户名、绝对路径、
+软件资产和能力详情不进入未认证发现广播。
+
+重装或主动重置设备身份会产生新设备。旧局域网配对和 ShareServer 设备注册不会自动迁移。
+
+### 6.2 局域网配对
+
+1. 发起端选择一台主动广播的设备。
+2. 双方建立临时加密通道并计算共同短验证码。
+3. 两端同时显示设备名、系统类型、公钥指纹和验证码。
+4. 双方用户确认后保存对端公钥及配对 ID。
+5. 后续使用双方设备证书认证；任一端可以撤销配对。
+
+IP 地址不作为设备身份，也不单独构成授权依据。
+
+### 6.3 ShareServer 注册
+
+用户通过浏览器/OIDC 或服务端支持的登录方式认证后，为当前设备申请一次性注册挑战。设备
+使用自身私钥签名挑战，ShareServer 建立 `user + organization + device` 绑定并签发可轮换的
+设备凭据。设备凭据不等同于用户 Web 会话，不可用于管理控制台登录。
+
+### 6.4 联邦身份
+
+两个 ShareServer 由双方管理员交换组织标识、网关公钥、公开端点和指纹，并分别确认信任。
+联邦关系只有在双方状态均为 `active` 时生效。单方暂停或撤销后立即停止新目录交换和新任务，
+已执行任务保留审计终态。
+
+## 7. 能力模型
+
+### 7.1 能力清单
+
+```json
+{
+  "schemaVersion": "1.0",
+  "capabilityId": "document.convert.docx",
+  "name": "文档转 Word",
+  "version": "1.4.0",
+  "modes": ["remote", "package"],
+  "inputSchema": {},
+  "outputSchema": {},
+  "permissions": ["receive_text", "receive_files", "return_files"],
+  "limits": {
+    "maxInputBytes": 10485760,
+    "maxOutputBytes": 52428800,
+    "maxDurationSeconds": 900,
+    "maxConcurrentTasks": 2
+  },
+  "dataPolicy": {
+    "retention": "task_lifetime",
+    "networkAccess": false,
+    "delegation": "none"
+  }
+}
+```
+
+清单只描述能力事实，不授予任何主体访问权。`inputSchema` 和 `outputSchema` 使用受限 JSON
+Schema 子集；实现必须限制 schema 深度、属性数、枚举数和总字节，不能把清单当作可执行代码。
+
+### 7.2 发布声明
+
+`Publication` 将一个能力版本发布到以下一种范围：
+
+- 指定局域网 Peer。
+- 所有已配对 Peer。
+- ShareServer 内指定用户、用户组或设备组。
+- 指定联邦组织中的用户组。
+
+发布声明同时定义允许动作：`discover`、`inspect`、`invoke`、`download`。`inspect` 允许查看
+详细清单，`discover` 只允许看到名称和可用状态。
+
+### 7.3 可调用与可分发
+
+- `remote`：代码与受控数据留在提供方，调用方只发送输入并接收结果。
+- `package`：签名工件下载到调用方，经校验和用户/组织策略批准后安装。
+
+同一能力可以同时支持两种模式，但两种模式分别授权。远程调用授权不能推导下载权，下载权
+也不能推导安装后自动启用。
+
+## 8. 授权模型
+
+### 8.1 授权输入
+
+一次动作的最终决定取以下约束交集：
+
+```text
+调用方用户权限
+∩ 调用方设备状态
+∩ 调用方组织强制策略
+∩ 发布范围
+∩ 提供方授权
+∩ 提供方组织强制策略
+∩ 能力输入与数据策略
+∩ 联邦关系限制（跨组织时）
+= allow | require_approval | deny
+```
+
+`deny` 优先于 `require_approval`，`require_approval` 优先于 `allow`。客户端偏好只能在组织强制
+策略允许的范围内收紧权限，不能放宽权限。
+
+### 8.2 Grant
+
+Grant 至少绑定：
+
+- 主体：用户、用户组、设备、设备组或外部组织。
+- 能力 ID 和允许的版本范围。
+- 动作：查看、调用、下载、安装或发布。
+- 输入：文本、文件、数据分类、单项和累计大小。
+- 提供者和执行位置限制。
+- 次数、并发、预算、时间段和有效期。
+- 是否需要每次批准。
+- 是否允许委托及明确的下游组织。
+
+“始终允许”只创建与当前能力、提供者、输入类型和范围匹配的 Grant，不创建整台设备的任意
+访问权。
+
+### 8.3 转委托
+
+默认 `delegation=none`。允许委托时，任务授权中必须冻结完整执行链和最大跳数。任一新组织、
+新能力或新数据接收方加入执行链，都需要重新计算授权，不能沿用原任务令牌。
+
+## 9. 任务协议
+
+### 9.1 任务快照
+
+创建任务时冻结：
+
+- 调用方用户、设备和组织。
+- 能力 ID、版本和提供者。
+- 输入 schema 版本、数据类型、数据分类和字节数。
+- 路由：局域网直连、网关直连、网关中继或联邦路径。
+- 授权决定、批准记录和策略版本。
+- 委托链、预算、期限和幂等键。
+
+设置或策略后续变化不追改已接受任务；紧急撤销可以阻止尚未开始的任务，并按策略取消活动
+任务。
+
+### 9.2 状态
+
+```text
+created -> awaiting_approval -> queued -> connecting -> running
+running -> completed | failed | cancelled | outcome_unknown
+created/awaiting_approval/queued/connecting -> rejected | expired | cancelled
+```
+
+- `completed` 只在提供者提交完整终态且调用方确认接收后成立。
+- 网络中断后无法确认副作用结果时使用 `outcome_unknown`，不得自动重放。
+- 重试创建新 attempt，并复用仅在能力声明支持时才有效的幂等键。
+- 用户取消必须传播到实际提供者；未确认取消时不能声称任务已停止。
+
+### 9.3 数据传输
+
+- 小型 JSON 输入使用任务通道传输。
+- 文件使用内容 SHA-256、声明大小和一次性任务对象令牌传输。
+- 接收端边读边校验大小和摘要，拒绝路径、符号链接和调用方文件名决定的落盘位置。
+- 任务正文、文件和输出不进入普通网关审计日志。
+- 中继模式下是否端到端加密由策略快照明确记录；界面必须显示网关能否读取正文。
+
+## 10. 能力包与更新
+
+每个 Package 必须提供不可变版本、目标平台和架构、内容大小、SHA-256、发布者签名、权限
+声明、依赖和兼容范围。安装流程统一为：
+
+```text
+取得签名目录 -> 选择不可变目标 -> 下载暂存 -> 校验大小/摘要/签名
+-> 展示权限差异 -> 批准 -> 安装到 GoodBuddy-owned 目录 -> 验证 -> 启用
+```
+
+要求：
+
+- 下载开始后冻结来源，不在失败时静默切换 ShareServer 或镜像。
+- 包不得包含凭据；配置只携带非敏感结构和密钥引用。
+- 新版本扩大文件、进程、网络、数据或委托权限时，旧 Grant 不自动继承。
+- 紧急撤销阻止新安装和新调用；已安装包的停用或删除遵循组织策略并向用户说明。
+- 复用现有 GoodBuddy 签名工件原则，但不同用途使用独立签名域。
+
+## 11. 协议分层
+
+### 11.1 局域网发现层
+
+- DNS-SD 服务类型：`_goodbuddy-share._tcp.local`。
+- 广播仅包含协议 major、随机实例 ID、端口和配对状态。
+- 设备名称、证书和详细版本通过临时加密握手取得。
+- 不扫描任意端口，不枚举未主动广播的机器。
+
+### 11.2 ShareServer 控制 API
+
+使用 HTTPS 提供登录、设备注册、目录、管理和审计 API；使用 WebSocket 建立设备出站控制
+通道，承载心跳、任务声明、取消和短期数据通道协商。普通管理 API 与设备通道使用不同凭据
+和受众。
+
+### 11.3 数据通道
+
+数据通道可以是配对 TLS 直连、ShareServer WebSocket 中继或经网关协商的端到端加密流。
+协议只保证有界帧、顺序、取消和终态，不自行实现另一套拥塞控制。
+
+### 11.4 版本协商
+
+- 每层独立声明 `major.minor`。
+- major 不同拒绝连接；minor 使用双方共同支持的最低能力集合。
+- 未识别字段在声明允许扩展的位置忽略，安全与授权枚举中的未知值一律拒绝。
+- 联邦只交换双方共同支持的能力和策略表达式，不降低任一方策略。
+
+## 12. 数据与审计
+
+### 12.1 最小审计事件
+
+- 操作者、调用设备和组织。
+- 动作、能力、版本和提供者。
+- 路由与是否跨组织。
+- 输入数据类别、分类、文件数和字节数。
+- 授权结果、策略 ID 和批准者。
+- 任务状态、耗时、输出大小和资源用量。
+- 包下载、安装、更新、撤销和发布变更。
+
+默认不保存提示正文、文件内容、模型输出、密钥、Cookie、认证头或完整私有路径。需要内容
+审计的组织必须单独定义保留期限和访问角色，并在调用前向用户显示。
+
+### 12.2 数据权威
+
+- 桌面端是本地配对、本机共享偏好和本地活动记录的权威。
+- ShareServer 是组织成员、设备注册、组织策略、发布目录和组织审计的权威。
+- 能力提供者是运行中任务及结果是否产生的权威。
+- 联邦两端各自保存本组织审计，不复制对方完整成员目录或内部策略。
+
+## 13. 安全边界
+
+ShareServer 可以部署到公网，因此公网连接、外部组织和服务端多租户是本设计中的实际信任
+边界。共同要求如下：
+
+1. 所有远端清单、名称、schema、错误、文件和模型输出都作为不可信数据处理。
+2. Renderer 不接触设备私钥、网关令牌、任意 socket 或原始文件传输接口。
+3. Main/Provider 在执行边界重新验证任务，不信任 Renderer 或 ShareServer 代替本机授权。
+4. ShareServer 按组织隔离查询，搜索和计数接口不能泄露无权查看的设备或能力。
+5. 设备只建立主动配置的网关出站连接，不接受 ShareServer 发起任意系统调用。
+6. 局域网发现不等于信任，组织成员身份也不等于所有能力授权。
+7. 远程能力不能扩大本机 Ask/Execute、Workspace、Runtime、Skill 或 MCP 现有权限。
+8. 密钥只进入对应安全存储，诊断和审计使用固定字段与脱敏错误码。
+9. 限制握手、清单、帧、文件、并发、速率、任务时长和审计查询大小。
+10. 撤销设备、用户、Grant、Publication、Package 或 FederationTrust 后停止签发新令牌。
+
+## 14. 建议领域实体
+
+```text
+DeviceIdentity
+PeerPairing
+GatewayConnection
+Organization
+Membership
+Group
+RegisteredDevice
+Capability
+CapabilityVersion
+Publication
+Grant
+Policy
+Approval
+Task
+TaskAttempt
+ArtifactTransfer
+Package
+PackageRelease
+FederationTrust
+AuditEvent
+Revocation
+```
+
+共享协议只定义跨端 DTO 和状态，不规定桌面 SQLite 与 ShareServer 数据库使用相同表结构。
+
+## 15. 仓库边界
+
+目标目录结构：
+
+```text
+docs/
+  architecture/share-network-architecture.md
+  features/device-sharing/
+  features/share-server/
+packages/
+  share-protocol/        # 与 Electron、数据库和 Web 框架无关的 schema/类型
+shareserver/             # 独立 Web 服务及管理前端
+src/                     # GoodBuddy Desktop
+```
+
+当前文档先固定边界，不创建空服务脚手架。实现时 `shareserver` 不反向依赖桌面端 `src/shared`；
+双方依赖独立 `share-protocol`。协议包不得包含数据库模型、Electron API、服务实现或凭据。
+
+## 16. 共同验收标准
+
+- [ ] 不配置 ShareServer 时，两台桌面端可通过局域网发现、双端配对、查看获准能力并调用。
+- [ ] 关闭“允许被发现”不会关闭主动发现；关闭主动发现不会撤销既有配对。
+- [ ] 本机没有明确 Publication 时，任何 Peer 或组织成员都不能查看或调用本机能力。
+- [ ] 桌面端可以连接多个 ShareServer，任一连接故障不影响局域网和其他连接。
+- [ ] ShareServer 只展示当前用户、设备和组织获准查看的目录。
+- [ ] 每次远程调用都能说明提供者、执行位置、发送数据、路由、授权依据和委托链。
+- [ ] 网络中断且副作用结果不确定时进入 `outcome_unknown`，不会自动重放。
+- [ ] 能力包经大小、SHA-256、签名、兼容和权限差异校验后才能安装。
+- [ ] 跨组织调用同时满足两端策略；联邦撤销后不能创建新任务。
+- [ ] 审计默认只保存必要元数据，不保存正文、文件、密钥或认证信息。
+- [ ] ShareServer 可独立部署和升级，不由 Electron 启动，也不影响桌面端离线使用。
+
+## 17. 相关设计
+
+- [设备发现与共享 PRD](../features/device-sharing/prd.md)
+- [设备发现与共享功能逻辑](../features/device-sharing/logic-design.md)
+- [设备发现与共享 UI](../features/device-sharing/ui-design.md)
+- [设备发现与共享技术设计](../features/device-sharing/technical-design.md)
+- [ShareServer PRD](../features/share-server/prd.md)
+- [ShareServer 功能逻辑](../features/share-server/logic-design.md)
+- [ShareServer 管理界面](../features/share-server/ui-design.md)
+- [ShareServer 技术设计](../features/share-server/technical-design.md)
+- [SSH 远程主机与 Agent](../features/remote-host/README.md)
+- [GoodBuddy 统一界面设计系统](../../UI-DESIGN.md)
@@ -0,0 +1,28 @@
+# 设备发现与共享
+
+本功能是 GoodBuddy 桌面端管理附近设备、本机共享和 ShareServer 连接的唯一入口。默认连接
+方式是局域网；网关由用户额外添加。功能不包含 ShareServer 的组织管理 Web 界面。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [PRD](./prd.md) | 用户问题、范围、功能需求和产品验收 |
+| [功能逻辑](./logic-design.md) | 不变量、状态、授权优先级和失败结果 |
+| [UI 设计](./ui-design.md) | 设置入口、四个页签、配对与调用交互 |
+| [技术设计](./technical-design.md) | Desktop 进程边界、持久化、IPC、网络和验证 |
+| [共享网络总体设计](../../architecture/share-network-architecture.md) | 跨端身份、能力、授权、任务、更新和协议权威 |
+
+当前没有单独的 User Stories：正常、失败、撤销、权限和兼容场景已直接进入 PRD 验收与逻辑
+决策表。功能尚未实施，因此不创建 `progress.md`。
+
+## 术语
+
+- **附近设备**：同一局域网内主动广播 GoodBuddy 共享服务的设备。
+- **已配对设备**：双方确认设备指纹后建立点对点信任的设备。
+- **网关连接**：本机与某个 ShareServer 中特定组织身份的连接。
+- **本机共享**：由本机作为提供者发布给 Peer 或组织的能力。
+- **远端能力**：由其他设备或组织提供、本机可以查看或调用的能力。
+
+SSH 远程项目是用户明确配置 Host 后操作远端工作区的独立功能，不自动进入设备发现与共享，
+详见[远程主机与远程执行](../remote-host/README.md)。
@@ -0,0 +1,202 @@
+# 设备发现与共享功能逻辑设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [设备发现与共享 PRD](./prd.md) |
+| 共享规则 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
+
+本文负责桌面端状态、不变量和决策规则，不重复跨端协议定义。
+
+## 1. 核心不变量
+
+### INV-1 连接方式独立
+
+局域网、每个 GatewayConnection 和本机能力互不拥有生命周期。启停、失败或删除其中一项不
+改写其他项。
+
+### INV-2 三项操作独立
+
+`discovering`、`advertising` 和 `publishing` 是三个独立状态。任何组合均合法，界面不得用
+一个“设备共享”总开关代替。
+
+### INV-3 默认不共享
+
+新安装没有 Publication。允许被发现只公开配对入口，不公开能力清单。
+
+### INV-4 身份先于能力
+
+未配对局域网设备不能取得详细能力；未注册网关设备不能取得组织目录。缓存不能绕过当前
+身份和撤销状态继续调用。
+
+### INV-5 提供者在调用前冻结
+
+自动选择只生成候选决定。用户确认或无需确认的请求创建后，provider、route 和授权快照不可
+改变。失败后切换提供者属于新的请求。
+
+### INV-6 最小发送上下文
+
+只发送能力 schema 要求且用户当前选择的输入。当前 Conversation、Project 和 Workspace 不
+因能力被调用而整体成为输入。
+
+### INV-7 结果未知不重放
+
+已经被提供者接受但终态无法确认的副作用任务进入 `outcome_unknown`。重新执行必须由用户
+发起，并显示可能重复产生副作用。
+
+### INV-8 撤销只影响未来授权
+
+撤销配对、网关连接、Grant 或 Publication 后不再创建新任务。历史记录保留；活动任务按
+冻结策略取消或完成，不能追改为从未发生。
+
+### INV-9 设置导航无业务副作用
+
+四个 PageTabs 只切换视图，不自动开始广播、连接网关、发布能力或保存草稿。
+
+## 2. 状态维度
+
+### 2.1 局域网服务
+
+```text
+discover: off | starting | active | unavailable | error
+advertise: off | starting | active | unavailable | error
+```
+
+操作系统或网络不支持时使用 `unavailable`；运行失败使用 `error`。两者分别重试。
+
+### 2.2 附近设备
+
+```text
+visible_unpaired -> pairing -> paired_online
+pairing -> rejected | expired | failed
+paired_online <-> paired_offline
+paired_* -> identity_changed | revoked
+```
+
+`identity_changed` 不自动接受新证书。用户必须撤销旧配对后重新配对。
+
+### 2.3 网关连接
+
+```text
+draft -> authenticating -> connecting -> connected
+authenticating -> cancelled | auth_failed
+connecting/connected -> offline | auth_expired | policy_blocked
+offline -> connecting
+任意已保存状态 -> removed
+```
+
+`offline` 保留连接和缓存目录供只读说明，但不能创建新任务；`auth_expired` 要求重新登录；
+`policy_blocked` 显示服务端给出的稳定原因和管理员联系路径。
+
+### 2.4 本机发布
+
+```text
+not_published -> draft -> validating -> published
+validating -> invalid
+published -> paused -> published
+published/paused -> removed
+```
+
+草稿和无效发布不对外可见。能力实现消失时发布进入 `paused`，不删除用户配置。
+
+### 2.5 远端任务
+
+采用共享架构定义的状态。本机 UI 归并为：
+
+| 协议状态 | 用户状态 |
+| --- | --- |
+| `created/awaiting_approval` | 等待确认 |
+| `queued/connecting` | 正在连接 |
+| `running` | 正在执行 |
+| `completed` | 已完成 |
+| `failed/rejected/expired` | 未完成，并显示具体原因 |
+| `cancelled` | 已取消 |
+| `outcome_unknown` | 结果未知 |
+
+## 3. 默认状态
+
+| 设置 | 全新安装默认值 |
+| --- | --- |
+| 发现附近设备 | 开启 |
+| 允许其他设备发现本机 | 关闭 |
+| 自动接受配对 | 不支持 |
+| 本机共享能力 | 无 |
+| 网关连接 | 无 |
+| 永久调用 Grant | 无 |
+
+主动发现默认开启只浏览 GoodBuddy 主动广播，不执行端口扫描。操作系统权限尚未授予时，首次
+进入页面再触发对应系统说明和授权，不在应用启动时抢占焦点。
+
+## 4. 提供者选择
+
+自动选择按以下顺序比较满足当前输入和授权的在线候选：
+
+1. 本机提供者。
+2. 已配对局域网提供者。
+3. 当前用户所属组织提供者。
+4. 联邦外部组织提供者。
+5. 同级中按服务端预计排队时间和稳定能力版本排序。
+
+自动选择不跨越 `require_approval` 与 `allow`：若排名第一的候选需要批准，界面显示该候选及
+批准要求，不静默换成权限更宽但来源更远的候选。用户可以明确选择其他候选。
+
+## 5. 调用决策表
+
+| 身份与能力状态 | 授权结果 | 行为 |
+| --- | --- | --- |
+| 身份有效、输入匹配 | allow | 创建任务并展示执行位置 |
+| 身份有效、输入匹配 | require_approval | 显示完整确认后创建 |
+| 身份有效 | deny | 不创建任务，显示策略原因 |
+| 提供者离线 | 任意 | 不创建任务，允许重新选提供者 |
+| 清单过期或版本变化 | 任意 | 刷新后重新计算，不沿用确认 |
+| 文件超过能力或策略上限 | 任意 | 就地拒绝并显示上限 |
+| 委托链与确认不一致 | 任意 | 拒绝并要求以新执行链重新确认 |
+
+## 6. 撤销与删除
+
+| 操作 | 删除内容 | 保留内容 |
+| --- | --- | --- |
+| 撤销 Peer | 配对凭据、该 Peer 的本地 Grant 和目录缓存 | 活动记录、已安装包 |
+| 移除网关 | 本机设备凭据、连接配置、目录缓存 | 服务端账号、活动记录、已安装包 |
+| 停止发布 | 对外 Publication | 能力实现、发布草稿、历史任务 |
+| 删除发布 | Publication 和本地发布设置 | 能力实现、历史任务 |
+| 删除已安装包 | GoodBuddy-owned 安装内容和分配 | 来源审计与任务历史 |
+
+存在活动任务时，撤销操作明确询问是否同时发送取消；无论取消是否确认，立即禁止新任务。
+
+## 7. 失败与恢复
+
+- mDNS 不可用：显示手动地址配对，不关闭已配对直连。
+- 广播失败：保留用户开关意图，状态为错误并允许重试。
+- 网关离线：指数退避重连，用户手动“重新连接”可立即尝试一次。
+- 登录取消：不保存连接。
+- 目录刷新失败：保留最后缓存并标记时间，不允许基于过期授权启动新任务。
+- 调用前连接失败：任务失败，可安全重新执行。
+- 提供者接受后断线：恢复查询同一任务；仍无法确认时进入结果未知。
+- 下载或签名失败：删除候选暂存，保留现有安装，不切换来源。
+
+## 8. 需求追踪
+
+| 需求 | 主要逻辑 |
+| --- | --- |
+| `FR-1`、`FR-2` | `INV-1`、`INV-2`、`INV-9` 和默认状态 |
+| `FR-3`、`FR-4` | 身份不变量和附近设备状态机 |
+| `FR-5` | 连接独立不变量、网关连接状态和删除规则 |
+| `FR-6` | provider 冻结不变量和提供者选择顺序 |
+| `FR-7` | 默认不共享不变量、本机发布状态和撤销规则 |
+| `FR-8` | 最小发送上下文和调用决策表 |
+| `FR-9` | 远端任务状态、结果未知不重放和失败恢复 |
+| `FR-10` | 撤销与删除、下载或签名失败规则；包协议由共享架构定义 |
+| `FR-11` | 撤销后历史保留和任务状态；展示行为由 UI 设计定义 |
+| `FR-12`、`FR-13` | 独立状态维度和失败恢复 |
+| `FR-14` | 身份先于能力、最小发送上下文和调用决策表 |
+
+## 9. 逻辑完整性
+
+本设计已覆盖发现、配对、连接、发布、调用、取消、撤销、离线、身份变化、权限变化和能力
+更新。实现前仍需在共享协议中固定受限 JSON Schema 子集、端到端中继加密套件和桌面端可
+注册为共享能力的首批实际类型；这些是技术选择，不改变本文状态和产品规则。
@@ -0,0 +1,160 @@
+# 设备发现与共享 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 适用产品 | GoodBuddy Desktop |
+| 关联架构 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
+| 关联文档 | [功能逻辑](./logic-design.md)、[UI 设计](./ui-design.md)、[技术设计](./technical-design.md) |
+
+## 1. 背景
+
+GoodBuddy 的能力当前主要在本机执行，SSH 远程项目则要求用户预先配置具体 Host。个人和组织
+需要在不复制完整环境的情况下使用附近工作站、其他成员设备或组织节点上的模型、知识、硬件
+和工具，也需要在经过确认后把可分发能力安装到本机。
+
+该能力不能以“扫描局域网机器”的方式实现。产品只发现主动开放 GoodBuddy 服务的设备，
+配对后才查看详细能力，授权后才发送数据或执行任务。
+
+## 2. 产品目标
+
+1. 用户无需配置服务器即可发现并配对同一局域网中的 GoodBuddy 设备。
+2. 用户可以额外连接一个或多个 ShareServer，使用组织或合作组织提供的能力。
+3. 用户能够逐项决定本机向哪些 Peer、用户组或组织开放什么能力。
+4. 远程调用前、中、后都能确认提供者、执行位置、数据去向和授权依据。
+5. 局域网、各网关连接和本机能力彼此独立，单点故障不阻塞其他来源。
+6. 可分发能力必须在明确校验和批准后安装，不迁移对方凭据或机器配置。
+
+## 3. 功能范围
+
+### 3.1 包含
+
+- 设置中的“设备发现与共享”一级分类。
+- 局域网主动发现、选择、双端配对、重命名和撤销。
+- 本机被发现开关和配对请求处理。
+- ShareServer 添加、登录、连接状态、组织身份和移除。
+- 远端能力目录、提供者选择、调用确认、进度、取消和结果。
+- 本机能力逐项发布、范围、允许动作和确认策略。
+- 签名能力包查看、下载、校验、安装和权限变化确认。
+- 局域网与网关活动记录。
+
+### 3.2 不包含
+
+- 扫描未主动广播 GoodBuddy 服务的机器或端口。
+- 在桌面端管理 ShareServer 成员、组织策略、联邦或服务器运维。
+- 自动公开本机 Skill、MCP、知识库、模型、文件或 SSH Host。
+- 同步 API Key、Cookie、系统环境变量、绝对路径或登录状态。
+- 把现有 SSH Host 自动转换为共享设备。
+- 无界远程 Shell、桌面控制或任意文件浏览接口。
+- 在网关断开时把组织授权自动降级为局域网授权。
+
+## 4. 功能需求
+
+### FR-1 设置入口
+
+- 设置中心增加“设备发现与共享”一级分类。
+- 页面提供“局域网”“网关”“本机共享”“活动记录”四个同级页签。
+- 普通入口默认打开“局域网”；定向入口可打开指定页签。
+
+### FR-2 独立开关
+
+- “发现附近设备”和“允许其他设备发现本机”使用两个独立 Switch。
+- 任一开关变化不撤销既有配对、不改变网关连接、不开放能力。
+- 新安装默认允许主动发现；默认不允许本机被发现，默认无共享能力。
+
+### FR-3 附近设备
+
+- 只展示当前收到有效主动广播的 GoodBuddy 设备。
+- 未配对设备只展示配对所需的有限信息，不展示能力和资产详情。
+- 列表区分附近未配对、已配对在线、已配对离线和身份变化。
+- 用户可手动刷新，但持续发现不得因刷新造成列表闪烁或重复项。
+
+### FR-4 双端配对
+
+- 双方显示相同验证码、设备名称、系统类型和证书指纹。
+- 只有双方在时限内确认才建立配对。
+- 任一端拒绝、超时、身份变化或连接中断均不保存半配对关系。
+- 任一端可以撤销；撤销不删除历史活动记录。
+
+### FR-5 网关连接
+
+- 用户可输入 HTTPS ShareServer 地址或打开受支持的邀请链接。
+- 登录在系统浏览器中完成，设备凭据回到 Main 的安全存储。
+- 连接条目显示服务名、组织、当前成员身份、状态和最近策略同步时间。
+- 同一设备可连接多个网关；移除连接只删除本机凭据和缓存，不删除服务端账号。
+
+### FR-6 能力目录
+
+- 已配对 Peer 和已连接网关分别返回当前身份获准查看的能力。
+- 同一能力有多个提供者时合并展示，并允许“自动选择”或明确选择提供者。
+- 自动选择仅比较满足授权和输入要求的在线候选，依次选择本机、已配对局域网 Peer、
+  当前用户所属组织和联邦外部组织；同级候选再按预计等待时间和稳定能力版本排序。
+- 选择结果必须在执行前冻结并展示，不能执行中静默更换提供者。
+
+### FR-7 本机共享
+
+- 只有显式注册为可共享的能力才能出现在本机共享列表。
+- 每项能力分别设置目标范围、`discover/inspect/invoke/download` 动作、输入类型、大小、
+  并发、有效期和是否逐次确认。
+- 关闭能力或目标范围后停止接受新任务，不伪装为删除能力本身。
+- 知识库原文、工作区写入、进程执行和硬件控制需要独立的明确能力声明。
+
+### FR-8 调用确认
+
+- 首次或策略要求时，确认界面显示提供者、执行位置、接收方、输入内容类别、文件名和大小、
+  路由、中继可读性及下游委托。
+- 用户可取消、仅本次允许，或在组织策略允许时按当前范围保存授权。
+- 调用上下文不隐式包含其他会话消息、整个工作区或未选择的知识库内容。
+
+### FR-9 执行状态
+
+- 会话或任务活动持续显示远端能力名称、来源、状态、发送字节和停止入口。
+- 支持排队、连接、执行、完成、失败、取消、过期和结果未知。
+- 网络中断且副作用结果无法确认时显示“结果未知”，不自动重试。
+
+### FR-10 能力包
+
+- 展示来源、版本、发布者、平台、大小、签名、权限和依赖。
+- 下载和安装经过共享架构规定的校验流程。
+- 新版本扩大权限时必须重新批准。
+- 安装到本机后按现有 Skill/MCP/Runtime 分配规则启用，不因来自可信组织自动取得全部 Runtime。
+
+### FR-11 活动记录
+
+- 统一记录本机发出、远端发入、局域网、网关和跨组织活动。
+- 支持按方向、来源、能力、结果和时间筛选。
+- 详情显示授权依据、执行链、数据类别、大小、版本和终态，不默认保存正文。
+
+### FR-12 错误隔离
+
+- 局域网发现失败不影响网关和本机能力。
+- 一个网关认证或连接失败不影响其他网关。
+- 一个提供者离线时不自动改发给另一个提供者；用户重新执行时再选择。
+- 页面保留可修复配置和准确错误，不以空状态代替失败状态。
+
+### FR-13 平台与网络
+
+- 支持 Windows、macOS、Linux 的当前桌面目标架构。
+- mDNS 被网络阻断时允许通过已知局域网地址发起配对，但仍执行相同身份确认。
+- 所有公网 ShareServer 使用 HTTPS；不提供“忽略证书错误”。
+
+### FR-14 与现有能力的边界
+
+- 远端调用不能扩大 Ask/Execute、Workspace、MCP、Skill 和知识库现有权限。
+- 本机提供任务时使用能力声明对应的 Runtime 边界。
+- SSH 远程项目、本机工具环境和模型配置默认不向 Peer 或网关传播。
+
+## 5. 产品验收
+
+- 两台新设备能完成发现、双端配对、授权、调用、取消和撤销。
+- 三个概念“主动发现、允许被发现、开放能力”在状态和界面上互不混淆。
+- 不配置网关时局域网工作完整；任一网关故障不阻塞其他来源。
+- 未配对或未授权主体无法查看详细能力。
+- 远端调用前能准确列出实际发送的数据，执行中和历史中可追溯提供者。
+- 结果未知不会被显示为失败后自动重试或成功。
+- 权限扩大的能力更新不会沿用旧授权静默安装。
+- 中英文、键盘、焦点、窄窗口和深浅主题符合统一设计系统。
@@ -0,0 +1,213 @@
+# 设备发现与共享技术设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [设备发现与共享 PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| 共享协议 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
+
+## 1. 进程边界
+
+```text
+Renderer
+  -> 窄 Preload API
+Main
+  -> DeviceSharingService
+       -> LanDiscoveryService
+       -> PeerPairingService
+       -> GatewayConnectionService
+       -> CapabilityCatalogService
+       -> CapabilityPublicationService
+       -> RemoteTaskService
+       -> PackageAcquisitionService
+       -> SharingAuditStore
+  -> 既有 Capability / Runtime / Skill / MCP 服务
+```
+
+Renderer 只取得脱敏快照和调用显式动作。设备私钥、Peer 证书、网关凭据、网络 socket、原始
+任务令牌、任意文件读取和包缓存路径只存在于 Main。
+
+## 2. 模块职责
+
+| 模块 | 职责 |
+| --- | --- |
+| `LanDiscoveryService` | mDNS browse/advertise、手动地址握手、接口变化 |
+| `PeerPairingService` | 临时握手、验证码、双端确认、配对凭据与撤销 |
+| `GatewayConnectionService` | 浏览器登录、设备注册、WebSocket、重连和策略同步 |
+| `CapabilityCatalogService` | 合并本机、Peer 和网关目录，保留来源身份 |
+| `CapabilityPublicationService` | 校验本机可共享能力并向目标范围发布 |
+| `RemoteTaskService` | 授权、确认、provider 冻结、传输、取消和终态 |
+| `PackageAcquisitionService` | 固定来源下载、校验、安装协调和权限差异 |
+| `SharingAuditStore` | 本机有界审计查询、筛选和清理 |
+
+目录合并只生成 UI 视图，不能把不同 provider 的授权、版本和执行位置压成一个身份。
+
+## 3. 共享契约
+
+实现前建立独立 `packages/share-protocol`。Desktop 只从该包导入 Zod schema 和 TypeScript
+类型。协议输入在网络边界和 IPC 边界分别验证，不能因已经过网络校验而跳过 Renderer 输入
+校验。
+
+建议导出：
+
+```text
+DeviceSummary
+PairingChallenge
+GatewayDescriptor
+CapabilityManifest
+Publication
+GrantConstraint
+AuthorizationDecision
+RemoteTaskSnapshot
+RemoteTaskEvent
+PackageDescriptor
+AuditEventSummary
+ProtocolError
+```
+
+错误只向 Renderer 返回稳定 code、可本地化参数和可恢复动作，不转发远端堆栈、响应正文或
+内部地址。
+
+## 4. 持久化
+
+建议在现有 Desktop SQLite 中增加：
+
+```text
+device_identity_metadata
+peer_pairings
+gateway_connections
+capability_publications
+local_grants
+remote_tasks
+sharing_audit_events
+installed_shared_packages
+```
+
+- 私钥和 refresh credential 存系统安全存储；SQLite 只存引用和脱敏元数据。
+- 附近广播、在线状态、配对验证码、短期任务令牌和目录候选只存在于内存。
+- 网关能力目录可有界缓存，用于离线说明，不作为离线调用授权。
+- 审计正文不落库，字段和保留上限在实现前固定。
+- 数据库迁移只覆盖已发布 schema；未发布设计不预建兼容读取器。
+
+## 5. 局域网网络实现
+
+- 使用系统支持的 mDNS/DNS-SD 库 browse `_goodbuddy-share._tcp.local`。
+- 广播绑定用户允许的网络接口；接口切换时重建监听，不保留旧地址为身份。
+- 服务端口由 Main 持有，使用设备证书建立 TLS。
+- 未配对握手仅暴露配对所需字段，并限制并发、频率、消息大小和有效时间。
+- 手动地址只替代发现，不替代证书指纹与双端确认。
+- 停止广播时关闭未完成配对监听；已配对活动连接按任务生命周期处理。
+
+## 6. 网关连接
+
+1. Main 校验 HTTPS URL，并取得服务公开描述。
+2. 生成带 PKCE、随机 state 和设备挑战的系统浏览器登录请求。
+3. 本机 loopback 或已注册应用链接只接收一次性回调 code。
+4. Main 交换设备凭据，展示组织身份，用户确认后持久化。
+5. Main 建立带设备身份的 WebSocket 出站连接。
+6. 心跳更新在线状态；断线按有界指数退避重连。
+
+服务器返回的跳转 URL 必须符合已取得服务描述和 HTTPS 限制。Renderer 不能提交认证头、设备
+证书、WebSocket URL 或任意回调地址。
+
+## 7. 本机能力适配
+
+不是所有现有 Capability 都自动可共享。每种可共享类型需要显式 adapter：
+
+```ts
+interface ShareableCapabilityAdapter {
+  describe(): CapabilityManifest
+  validatePublication(input: PublicationDraft): ValidationResult
+  invoke(input: unknown, context: ProviderTaskContext): AsyncIterable<TaskEvent>
+  cancel(taskId: string): Promise<CancelResult>
+}
+```
+
+adapter 负责把共享输入映射到既有生产服务，并保留原权限边界。首批类型在实现前根据真实
+产品需求确定；未有 adapter 的 Skill、MCP、知识库和 Runtime 不出现在共享列表。
+
+## 8. 远端调用生命周期
+
+```text
+Renderer 选择能力和输入
+-> Main 解析候选并取得当前授权
+-> 必要时返回确认描述
+-> 用户批准
+-> Main 冻结 task/provider/route/policy
+-> 建立数据通道并流式发送
+-> Provider 再校验并接受
+-> Main 转发有界进度和结果
+-> 终态与审计事务保存
+```
+
+每次任务使用稳定 `taskId` 和 attempt ID。Provider 未接受前的连接失败可以明确失败；已接受
+后的断线先查询同一任务，不新建 attempt。无法恢复权威终态时保存 `outcome_unknown`。
+
+附件从 Main 已授权的用户选择结果读取，按声明大小流式发送，不把任意本机路径交给远端。
+接收成果先写 GoodBuddy-owned 暂存并校验，再通过现有 Artifact 边界进入产品。
+
+## 9. IPC
+
+Preload 只暴露按产品动作命名的方法，例如：
+
+```text
+sharing.getSnapshot
+sharing.updateLanSettings
+sharing.startPairing / confirmPairing / cancelPairing
+sharing.revokePeer
+sharing.addGateway / completeGatewayLogin / removeGateway
+sharing.listCapabilities
+sharing.savePublication / pausePublication / deletePublication
+sharing.prepareInvocation / confirmInvocation / cancelTask
+sharing.listAuditEvents / getAuditEvent
+```
+
+所有变更方法校验 trusted sender、严格 schema、对象当前 revision 和归属关系。不得暴露通用
+HTTP、WebSocket、mDNS、证书、文件传输或数据库查询 IPC。
+
+## 10. 生命周期与资源边界
+
+- 应用启动按保存设置启动主动发现；不因保存了网关而阻塞窗口创建。
+- 广播只有在用户开启后启动。
+- 网关连接在后台恢复，认证过期只影响对应连接。
+- 应用退出停止接收新任务，取消未接受任务，并有界通知活动 Provider 后关闭连接。
+- 单个 Peer/网关/任务设置连接数、帧、字节、并发和重连上限。
+- 大文件全程流式处理，不进入单个 Main `Buffer` 或 Renderer state。
+
+## 11. 与现有模块集成
+
+- `capability-service` 提供本机能力事实；共享 adapter 明确选择可公开子集。
+- 已安装共享 Skill/MCP 继续使用现有配置、启停和 Runtime 分配，不建立第二套执行器。
+- SSH Host 保持独立；除非未来提供专门 adapter 和用户发布，否则不进入目录。
+- 远端 Task 的公开活动复用现有工具/任务展示语义，但保留 provider 和 route 字段。
+- 应用更新源、模型下载源、Agent 下载源和工具下载源不因添加 ShareServer 自动改变。
+
+## 12. 验证策略
+
+### 12.1 自动化
+
+- schema 边界、未知枚举和协议版本协商。
+- 三个独立开关及默认值。
+- mDNS 去重、接口变化、广播停止和手动地址。
+- 配对双方确认、拒绝、超时、身份变化和撤销。
+- 多网关隔离、认证过期、重连和移除。
+- provider 排序、冻结、授权变化和失败不切换。
+- 调用确认最小输入、附件上限、取消和结果未知。
+- Publication 校验、暂停、撤销和 adapter 消失。
+- 包签名、权限差异、来源冻结和失败保留旧安装。
+- IPC sender、revision、归属和无通用网络/文件接口。
+
+### 12.2 真实环境
+
+- Windows、macOS、Linux 至少两种组合完成同网段发现和配对。
+- mDNS 可用、被防火墙阻断、网络接口切换和设备离线场景。
+- 真实 ShareServer 登录、设备出站连接、目录、调用和认证过期。
+- 小型 JSON、文件流、取消、Provider 进程失败和网络中断。
+- 确认日志、Renderer、诊断和审计中没有凭据或文件正文。
+
+设计文档完成不代表功能实施或上述验证通过。
@@ -0,0 +1,211 @@
+# 设备发现与共享 UI 设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [设备发现与共享 PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| 全局规范 | [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md) |
+
+本文只定义桌面端界面。所有颜色、间距、字体、通知、Switch、PageTabs、焦点和响应式行为以
+全局设计系统为准。
+
+## 1. 信息架构
+
+设置中心新增一级分类“设备发现与共享”，使用 `standard` PageShell：
+
+```text
+设备发现与共享
+发现附近的 GoodBuddy，或连接组织网关使用和开放能力
+
+[ 局域网 ] [ 网关 ] [ 本机共享 ] [ 活动记录 ]
+```
+
+四项使用共享 `PageTabs` 的 `segmented` 视觉变体。普通入口默认“局域网”；来自能力来源、
+连接错误或审计入口的定向导航打开对应页签。页签选择不持久化为产品设置。
+
+## 2. 局域网页签
+
+页面顺序固定为本机发现状态、已配对设备、附近设备。
+
+```text
+局域网
+
+发现附近设备                                      [Switch 开]
+查看同一网络中主动开放的 GoodBuddy 设备
+
+允许其他设备发现本机                              [Switch 关]
+设备名称：Jiang-PC                                 [编辑]
+
+已配对设备                                      [刷新]
+名称             状态        能力       最近连接       操作
+GPU-Workstation  在线        4 项       刚刚           ...
+
+附近设备
+Design-Mac       等待配对                               [配对]
+```
+
+- 两个 Switch 必须独立成行，不能使用一个总开关。
+- “允许被发现”开启后只显示广播状态和设备名，不暗示已经共享能力。
+- 设备行采用紧凑列表，不使用大卡片墙。
+- 已配对设备行可展开简要能力；完整信息进入设备详情抽屉。
+- 离线设备保留在“已配对设备”，附近广播消失不删除配对。
+
+### 2.1 配对对话框
+
+```text
+与 Design-Mac 配对
+
+验证码        824 193
+设备          Design-Mac · macOS
+设备指纹      7A:31:...:D9
+有效时间      01:42
+
+请确认另一台设备显示相同信息。
+[取消] [信息一致，确认配对]
+```
+
+双方尚未确认时显示独立进度。拒绝、超时和连接失败保留设备行并给出重新配对，不显示成功
+通知。成功使用应用通知，焦点回到对应设备行。
+
+### 2.2 设备详情
+
+详情使用右侧抽屉，包含“概览”“能力”“授权”“活动”四个内部页签。未配对设备不能打开
+能力和授权。撤销配对放在抽屉底部 danger zone，并说明活动任务和历史记录影响。
+
+## 3. 网关页签
+
+```text
+网关                                                   [添加网关]
+
+研发组织网关
+研发中心 · 成员
+已连接 · 策略同步于 14:32
+可用能力 18 项 · 本机发布 2 项                         [...]
+```
+
+空状态说明网关是附加连接，局域网无需网关即可使用。主操作为“添加网关”。
+
+### 3.1 添加网关
+
+对话框只要求 HTTPS 地址，也可由邀请链接预填：
+
+```text
+网关地址
+[https://share.example.com]
+
+[取消] [继续登录]
+```
+
+地址通过 Main 验证后打开系统浏览器。应用内显示“等待浏览器登录”和取消入口，不嵌入第三方
+登录页。回调成功后显示服务名、组织和账号，用户确认才保存连接。
+
+网关详情抽屉包含连接、组织身份、可用能力、本机发布和诊断。移除连接明确说明只移除本机
+连接，不删除组织账号或服务端设备记录。
+
+## 4. 本机共享页签
+
+页首状态摘要不能替代逐项开关：
+
+```text
+本机共享
+已开放 2 项能力 · 局域网 1 项 · 网关 2 项
+
+搜索能力                     [范围筛选] [状态筛选]
+
+文档转 Word                                      [Switch 开]
+范围：研发组织、GPU-Workstation
+允许：查看、远程调用
+确认：每次调用                                    [编辑]
+```
+
+能力关闭时保留配置摘要并标为“已暂停”。点击“编辑”打开共享设置对话框：
+
+- 目标范围使用分组多选，不混合 Peer、网关组织和用户组。
+- 允许动作使用 Checkbox。
+- “每次确认”使用 Switch。
+- 输入类型、大小、并发、时间段和有效期使用对应表单控件。
+- 权限较高的能力在提交区显示具体影响，不用泛化风险等级。
+- 提交按钮附近再次列出目标范围和允许动作。
+
+能力尚未注册为可共享时不展示虚假的禁用行。列表为空时说明当前没有可共享能力，并提供前往
+“能力与工具”的次操作。
+
+## 5. 活动记录页签
+
+使用 `dashboard` 所需的表格能力，但保持在设置 PageShell 内横向滚动：
+
+```text
+方向       能力             对端/来源          状态       时间
+发出       图像生成         研发组织网关       已完成     14:36
+收到       文档转 Word      GPU-Workstation    正在执行   14:31
+```
+
+工具栏提供方向、来源、状态、时间和搜索。详情抽屉显示任务 ID、能力版本、授权依据、路由、
+数据类型和大小、执行链、耗时、结果及取消/撤销入口。正文和文件内容默认不展示。
+
+## 6. 能力选择与调用确认
+
+远端能力进入现有能力目录时，在名称旁持续显示来源标签。多个提供者使用菜单选择：
+
+```text
+图像生成
+提供者 [自动选择：GPU-Workstation v]
+```
+
+调用需要确认时使用对话框：
+
+```text
+调用“合同风险检查”
+
+提供者       法务服务商
+执行位置     外部组织
+将发送       当前输入；contract.docx（1.8 MB）
+连接方式     ShareServer 中继
+网关可见正文 否
+下游调用     无
+
+[取消] [仅本次允许] [按此范围始终允许]
+```
+
+组织策略不允许保存 Grant 时不显示“始终允许”。按钮文字必须表达作用域，不能使用“确定”。
+
+## 7. 执行活动
+
+会话和任务中的远端工具活动至少显示：
+
+```text
+合同风险检查 · 法务服务商
+正在执行 · 已发送 1 个文件（1.8 MB）                 [停止]
+```
+
+展开后显示路由、能力版本和执行链。跨组织来源使用文字“外部组织”，不能只靠颜色。进入结果
+未知时显示持久警告和“查看活动详情”，不提供普通的自动重试按钮。
+
+## 8. 状态与错误
+
+- 首次为空、筛选无结果、加载失败、无权限和离线分别使用不同状态。
+- 缓存目录必须显示“上次更新于”，且离线时不能显示为当前可用。
+- 身份变化使用阻塞状态，唯一修复路径是撤销后重新配对。
+- 网关认证过期在对应网关行提供“重新登录”。
+- 发布字段错误就地显示；异步连接错误显示在对象行或详情中。
+- 配对成功、网关保存和共享发布成功使用应用通知，不重复显示页内成功横幅。
+
+## 9. 无障碍与响应式
+
+- 四个页签使用 `tablist/tab/tabpanel`、方向键、Home、End 和可见焦点。
+- 持久二元状态使用 `role="switch"`；范围和动作多选使用 Checkbox。
+- 表格在窄窗口切换为保留同样字段的列表，不隐藏提供者、状态或执行位置。
+- 指纹和长网关地址允许换行并提供复制按钮，不依靠水平裁切。
+- 对话框关闭后焦点回到触发控件；浏览器登录返回后恢复到等待登录区域。
+- 状态包含文字和图标，不以颜色作为唯一信号。
+
+## 10. 固定词汇
+
+使用“设备发现与共享”“局域网”“网关”“本机共享”“附近设备”“已配对设备”“允许其他
+设备发现本机”“结果未知”“外部组织”。不使用“扫描机器”“公网共享”“永久信任整台设备”
+或把 ShareServer 简称为“云端”。
@@ -0,0 +1,29 @@
+# ShareServer
+
+ShareServer 是 GoodBuddy 设备共享网络的独立 Web 服务。它为一个或多个组织提供身份与设备
+目录、能力发布、授权策略、任务路由、可选数据中继、能力包更新、网关联邦和审计管理。
+
+ShareServer 不属于 Electron Main，不负责桌面端局域网发现，也不自动取得设备上的能力、
+文件、凭据或 SSH Host。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [PRD](./prd.md) | 管理角色、产品范围、功能需求和验收 |
+| [功能逻辑](./logic-design.md) | 组织隔离、设备、发布、策略、任务和联邦状态规则 |
+| [管理界面设计](./ui-design.md) | ShareServer Web 控制台的信息架构与交互 |
+| [技术设计](./technical-design.md) | 服务模块、API、数据、部署、运维和验证 |
+| [共享网络总体设计](../../architecture/share-network-architecture.md) | 跨端身份、能力、授权、任务、更新和协议权威 |
+
+当前没有单独的 User Stories：管理员、能力发布者、审计员和普通成员场景已进入 PRD 与逻辑
+设计。服务尚未实施，因此不创建 `progress.md`。
+
+## 角色
+
+- **系统管理员**：维护实例、身份源、域名、证书、存储和全局限制。
+- **组织管理员**：管理本组织成员、设备、组、策略、能力和联邦关系。
+- **能力发布者**：在获准范围内发布设备能力或签名能力包。
+- **审批人**：处理调用、发布、更新和联邦申请。
+- **审计员**：只读查看和导出获准范围内的审计事件。
+- **成员**：主要通过 GoodBuddy Desktop 使用能力，只在 Web 端处理个人设备和审批。
@@ -0,0 +1,209 @@
+# ShareServer 功能逻辑设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [ShareServer PRD](./prd.md) |
+| 共享规则 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
+
+## 1. 核心不变量
+
+### INV-1 组织隔离先于角色
+
+任何查询和变更先绑定 organization，再计算角色。系统管理员的跨组织操作使用独立系统管理
+入口并形成审计，不能依靠省略 organization 条件获得全局数据。
+
+### INV-2 注册不等于发布
+
+设备注册只建立身份和连接资格。没有有效 Publication 时，目录中没有该设备能力。
+
+### INV-3 目录不等于授权
+
+看到能力不能推导可调用或可下载。创建任务和下载包时重新计算当前授权。
+
+### INV-4 服务端授权不能扩大端点授权
+
+ShareServer 的 `allow` 只是签发任务资格。Provider 和调用方仍执行各自本地策略；任一端拒绝
+即终止动作。
+
+### INV-5 策略拒绝优先
+
+同一动作命中多个规则时使用 `deny > require_approval > allow`。没有匹配 allow 时默认 deny。
+
+### INV-6 联邦为双边交集
+
+单方创建或接受的关系不生效。双方 active 且两端发布、Grant 和数据策略均允许时才能跨组织
+创建任务。
+
+### INV-7 任务提供者不可改写
+
+ShareServer 只路由调用方冻结的 provider，不在离线、繁忙或失败时替换节点。
+
+### INV-8 不恢复短期权威
+
+备份恢复不恢复 Web 会话、设备 socket、一次性挑战、审批 nonce 或任务数据通道。终端必须
+重新连接并证明身份。
+
+### INV-9 初始化入口一次性关闭
+
+初始化只在实例尚无系统管理员时可用。首个系统管理员创建成功后，后续请求即使持有旧的
+一次性引导材料也不能再次进入初始化流程。
+
+## 2. 主要状态
+
+### 2.1 成员
+
+```text
+invited -> active -> suspended -> active
+invited -> expired | revoked
+active/suspended -> removed
+```
+
+`suspended` 不能登录或创建新任务；历史归属保留。`removed` 不级联删除审计和已完成任务。
+
+### 2.2 注册设备
+
+```text
+pending -> active <-> offline
+pending -> expired | rejected
+active/offline -> revoked
+```
+
+客户端心跳只决定 `active/offline`，不能清除 `revoked`。重新注册生成新设备 registration。
+
+### 2.3 Publication
+
+```text
+draft -> pending_approval -> active
+draft/pending_approval -> rejected
+active <-> paused
+active/paused -> revoked
+```
+
+provider 离线不会把 Publication 变为 paused；目录同时展示“已发布”和“当前离线”两个事实。
+
+### 2.4 审批
+
+```text
+pending -> approved | rejected | cancelled | expired
+```
+
+审批对象内容摘要、申请主体或策略版本变化后，原审批不能复用。approved 只产生其声明范围内
+的 Grant 或一次性决定。
+
+### 2.5 Package Release
+
+```text
+draft -> verifying -> available -> paused -> available
+verifying -> invalid
+available/paused -> revoked
+```
+
+发布后的版本和字节不可变。修复内容必须使用新版本；revoked 不删除审计证据和对象摘要。
+
+### 2.6 FederationTrust
+
+```text
+draft -> offered -> mutually_confirmed -> active
+offered -> rejected | expired
+active <-> paused
+任意非终态 -> revoked
+```
+
+`mutually_confirmed` 只表示身份确认完成；双方策略同步成功后才进入 active。
+
+## 3. 授权计算顺序
+
+1. 验证请求身份、会话 audience 和 organization。
+2. 验证用户、设备、provider、Publication 和 FederationTrust 当前状态。
+3. 校验能力版本、动作、输入 schema、数据类别、大小和委托链。
+4. 收集调用方组织、提供方组织、Publication 和 Grant 规则。
+5. 按拒绝优先合并，计算 `deny/require_approval/allow`。
+6. 校验次数、并发、预算和有效期。
+7. 返回决定、稳定原因和策略引用；需要批准时建立内容绑定申请。
+8. 创建任务时再次计算，并把决定快照写入任务。
+
+目录查询可以预计算“可能可用”，但不能替代第 1 至 8 步。
+
+## 4. 组织角色边界
+
+| 动作 | 系统管理员 | 组织管理员 | 发布者 | 审批人 | 审计员 | 成员 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 实例设置 | 是 | 否 | 否 | 否 | 只读有限项 | 否 |
+| 成员与组 | 紧急管理 | 是 | 否 | 否 | 只读 | 自己 |
+| 注册设备 | 只读/撤销 | 是 | 自己 | 否 | 只读 | 自己 |
+| 发布能力/包 | 否 | 是 | 授权范围 | 否 | 只读 | 否 |
+| 编辑策略 | 否 | 是 | 否 | 否 | 只读 | 否 |
+| 处理审批 | 否 | 可配置 | 否 | 授权范围 | 只读 | 自己的申请 |
+| 联邦关系 | 实例级许可 | 是 | 否 | 可共同审批 | 只读 | 否 |
+| 审计导出 | 实例级 | 组织级 | 自己相关 | 自己相关 | 授权范围 | 自己相关 |
+
+实际权限仍由策略计算，表格定义产品默认职责而非硬编码角色名称。
+
+## 5. 任务路由决策
+
+| 条件 | 结果 |
+| --- | --- |
+| provider 在线且双方可直连 | 签发短期直连协商信息 |
+| 无法直连且双方策略允许中继 | 建立有界中继通道 |
+| 中继关闭或任一方禁止 | 创建失败，说明无可用路由 |
+| provider 离线 | 不排队到无限期，按能力配置有界等待或拒绝 |
+| provider 接受后连接中断 | 保留 task，等待同一 provider 恢复/查询 |
+| provider 终态未知且恢复期结束 | `outcome_unknown` |
+| 调用方取消 | 转发取消；provider 确认后终态 cancelled |
+
+中继容量不足只产生排队或资源错误，不切换 provider，不改变是否允许中继。
+
+## 6. 更新策略优先级
+
+```text
+紧急撤销
+> 组织强制固定版本/禁止版本
+> 设备组发布通道
+> 用户允许的版本范围
+> 当前已安装版本
+```
+
+任何权限扩大都从自动路径转为 `require_approval`。降级只有在目标版本仍被签名目录允许且
+策略明确指定时才提供，不自动视为故障回滚。
+
+## 7. 联邦可见性
+
+联邦目录只导出对方明确允许的能力投影：组织显示名、能力、版本范围、数据政策和可用性摘要。
+不导出内部设备名、成员清单、组结构、节点地址、内部策略全文或审计记录。跨组织请求使用
+双方关联 ID，双方各自解析本地主体。
+
+## 8. 删除、撤销与保留
+
+- 删除组织前必须停止新任务、撤销联邦和设备，并按保留策略归档审计；不提供无提示级联。
+- 删除用户不删除其历史动作，审计显示不可变主体摘要。
+- 撤销设备、Publication、Grant、Package 或联邦后立即阻止新令牌。
+- 对象存储中的未完成任务正文按任务期限清理；审计元数据按组织保留策略清理。
+- 法定保留只锁定匹配审计事件，不使被撤销身份重新可用。
+
+## 9. 需求追踪
+
+| 需求 | 主要逻辑 |
+| --- | --- |
+| `FR-1` | `INV-1`、`INV-9` 和系统管理员角色边界 |
+| `FR-2` | 组织隔离不变量、成员状态和角色边界 |
+| `FR-3` | 注册不等于发布、设备状态和短期权威恢复规则 |
+| `FR-4` | 注册、Publication、目录与授权不变量 |
+| `FR-5` | 拒绝优先不变量和授权计算顺序 |
+| `FR-6` | 审批状态、内容绑定和授权重算 |
+| `FR-7` | provider 冻结不变量和任务路由决策 |
+| `FR-8` | Package Release 状态和更新策略优先级 |
+| `FR-9` | 联邦双边交集、FederationTrust 状态和联邦可见性 |
+| `FR-10` | 组织隔离、删除撤销与保留规则 |
+| `FR-11` | 组织角色边界及各对象状态；展示行为由 UI 设计定义 |
+| `FR-12` | 短期权威恢复规则和逻辑完整性；部署结构由技术设计定义 |
+
+## 10. 逻辑完整性
+
+本设计覆盖实例、组织、成员、设备、发布、授权、审批、任务、更新、联邦、撤销和恢复。实现
+前仍需确定首个 OIDC 提供者矩阵、默认审计保留期、部署规模目标和中继带宽上限；这些部署
+参数应可配置，不改变拒绝优先、双边联邦和 provider 冻结规则。
@@ -0,0 +1,149 @@
+# ShareServer PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 适用产品 | 独立部署的 ShareServer 与 Web 管理控制台 |
+| 关联架构 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
+| 关联文档 | [功能逻辑](./logic-design.md)、[管理界面](./ui-design.md)、[技术设计](./technical-design.md) |
+
+## 1. 背景
+
+局域网配对适合附近设备，但不能统一解决跨网络访问、成员离职、组织策略、集中更新、审计和
+跨组织协作。ShareServer 提供一个可自建的组织控制面，让设备通过主动出站连接注册能力并
+接收任务，不要求为每台桌面设备开放公网端口。
+
+## 2. 产品目标
+
+1. 组织可在自有网络、私有云或公网独立部署 ShareServer。
+2. 管理员可统一管理用户、组、设备、能力、权限、更新和审计。
+3. 成员通过桌面端使用获准能力，无需日常进入管理控制台。
+4. 设备离线、用户撤销或策略变化能准确影响新任务，不破坏历史证据。
+5. 两个组织可经双边确认建立有限范围的联邦协作。
+6. ShareServer 可以只运行控制面，也可按部署策略提供数据中继和包存储。
+
+## 3. 产品范围
+
+### 3.1 包含
+
+- 本地账号及可配置 OIDC 身份源。
+- 组织、成员、角色、用户组、设备组和服务账号。
+- 设备注册、状态、撤销和合规元数据。
+- 能力目录、Publication、Grant、强制策略和审批。
+- 设备出站控制通道、任务路由、取消和可选中继。
+- 签名能力包仓库、发布通道、更新策略和撤销。
+- ShareServer 间双边联邦。
+- 审计、用量、保留和导出。
+- Web 管理控制台和成员自助页面。
+
+### 3.2 不包含
+
+- 远程管理设备桌面、任意 Shell 或任意文件系统。
+- 发现未注册的局域网设备。
+- 保存或分发用户 API Key、Cookie 和桌面登录状态。
+- 默认查看任务正文、附件和模型输出。
+- 未经提供者发布自动盘点设备能力。
+- 自动信任同域邮箱、同一网络或其他 ShareServer。
+- 公共开放市场、计费结算或匿名能力调用。
+- 替代 GoodBuddy 官方客户端、模型和 Agent 发布源。
+
+## 4. 功能需求
+
+### FR-1 实例初始化
+
+- 首次启动通过一次性引导创建实例标识和首个系统管理员。
+- 引导完成后永久关闭初始化入口，后续管理员通过正常身份流程创建。
+- 实例公开描述包含名称、协议版本、登录方式和联邦端点，不包含内部拓扑。
+
+### FR-2 身份与组织
+
+- 支持一个实例承载多个隔离组织，也支持部署为单组织模式。
+- 支持本地账号和 OIDC；组织可限制允许的身份源。
+- 成员可以属于多个组并拥有有界角色，角色不隐式跨组织。
+- 停用用户立即停止签发新设备和任务凭据。
+
+### FR-3 设备管理
+
+- 桌面端经用户登录、一次性挑战和设备签名完成注册。
+- 设备条目显示所有者、平台、客户端版本、最近在线、连接和撤销状态。
+- 设备主动建立出站控制连接；服务端不能借此调用未发布能力。
+- 管理员可撤销设备并终止其新任务资格。
+
+### FR-4 能力目录
+
+- 只接收已注册设备或服务节点提交的显式 Publication。
+- 目录按调用者身份、设备状态、组织和策略过滤后返回。
+- 支持同一能力多个版本和多个 provider，不掩盖来源。
+- provider 离线时保留目录事实但显示不可用，不派发新任务。
+
+### FR-5 授权策略
+
+- Grant 可绑定用户、组、设备、设备组和联邦组织。
+- 可约束能力、版本、动作、输入类型、数据分类、提供者、时间、次数、并发和委托。
+- 支持组织强制策略和用户可收紧偏好；拒绝优先。
+- 每个决定返回稳定结果、命中策略和面向用户的原因。
+
+### FR-6 审批
+
+- 调用、能力发布、权限扩大更新和联邦关系可以要求审批。
+- 审批项显示申请人、对象、影响范围、数据类别、期限和策略依据。
+- 批准结果有明确范围和有效期，不提供无边界“永久允许”。
+- 申请内容变化后旧审批失效。
+
+### FR-7 任务路由
+
+- 根据冻结 provider、在线连接和路由策略把任务声明发送给目标设备。
+- 支持直连协商、网关中继和取消传播。
+- 任务正文与控制元数据分离；默认审计不保存正文。
+- 已接受任务断线后允许查询同一 task，不自动创建重复执行。
+
+### FR-8 能力包与更新
+
+- 保存不可变签名 Package 和发布目录。
+- 支持组织、组、平台、架构和维护窗口的更新策略。
+- 支持固定版本、允许版本范围、暂停发布和紧急撤销。
+- 权限扩大必须触发新批准，不能被普通自动更新策略覆盖。
+- 包来源、大小、摘要、签名和下载结果可审计。
+
+### FR-9 联邦
+
+- 两个 ShareServer 通过指纹交换和双方管理员确认建立关系。
+- 双方分别配置公开能力、允许主体、数据范围、用量和期限。
+- 最终权限取双方策略交集；任一端撤销后停止新任务。
+- 不默认链式转发到第三个组织。
+
+### FR-10 审计与用量
+
+- 记录身份、设备、发布、授权、审批、任务、包和联邦管理事件。
+- 默认仅记录共享架构定义的有界元数据。
+- 支持按组织隔离查询、条件筛选、分页和流式导出。
+- 审计员只读，不能因查看日志取得任务正文或管理权限。
+
+### FR-11 管理控制台
+
+- 提供概览、组织与成员、设备、能力目录、权限策略、审批、发布与更新、网关联邦、任务与
+  中继、审计、系统设置。
+- 普通成员只看到自己的设备、授权和待办；管理员栏目按权限隐藏并在 API 再次校验。
+- 所有高影响操作说明对象、范围和后果。
+
+### FR-12 可部署性
+
+- 支持容器部署，配置与持久数据分离。
+- 支持外部 PostgreSQL；对象存储和中继按功能启用。
+- 提供健康、就绪、指标、结构化日志、备份和恢复说明。
+- 服务升级不能要求同时升级所有在线桌面端；按协议版本协商兼容集合。
+
+## 5. 产品验收
+
+- 新实例可完成初始化、登录、创建组织、邀请成员和注册真实桌面设备。
+- 两个不同组织不能通过 API、搜索、计数、错误或审计结果读取对方数据。
+- 设备只有发布能力后才进入获准目录，撤销后不能接收新任务。
+- 调用授权能同时处理用户、设备、组织、提供者、数据和联邦限制。
+- 任务中继关闭时控制面仍可运行；中继开启时可取消并形成准确终态。
+- 权限扩大的包更新不能自动部署。
+- 两个独立 ShareServer 能建立、使用、暂停和撤销双边联邦。
+- 备份恢复后组织、策略、发布和审计身份保持一致，短期连接和令牌不恢复。
@@ -0,0 +1,242 @@
+# ShareServer 技术设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [ShareServer PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| 共享协议 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
+
+## 1. 仓库与运行边界
+
+实现时在仓库顶层创建独立项目：
+
+```text
+shareserver/
+  README.md
+  package.json
+  src/
+    api/
+    auth/
+    organizations/
+    devices/
+    capabilities/
+    policies/
+    approvals/
+    tasks/
+    relay/
+    packages/
+    federation/
+    audit/
+  web/
+  migrations/
+  deploy/
+  tests/
+```
+
+当前只提交设计文档，不创建无法运行的目录占位。服务端和 Desktop 共同依赖未来的
+`packages/share-protocol`，ShareServer 不导入 Electron 的 `src/shared`。
+
+## 2. 技术选型约束
+
+- 使用与仓库一致的 TypeScript/Node.js 工具链，具体 HTTP 框架在实现前根据维护性选择。
+- PostgreSQL 是组织、策略、任务元数据和审计的权威数据库。
+- Package 与可选中继暂存使用 S3 兼容对象存储；不开启对应功能时不要求对象存储。
+- Web 控制台与 API 同源部署，采用严格 CSP，不在浏览器保存设备凭据。
+- 单实例部署可完整工作；水平扩展时再引入共享事件/连接路由组件，不为未验证规模预设复杂
+  分布式协议。
+
+## 3. 服务模块
+
+| 模块 | 职责 |
+| --- | --- |
+| `auth` | 本地身份、OIDC、Web session、服务和设备凭据 |
+| `organizations` | 组织、成员、组、角色和范围解析 |
+| `devices` | 注册挑战、设备记录、出站连接和在线状态 |
+| `capabilities` | manifest、provider、Publication 和目录投影 |
+| `policies` | Grant、强制策略和确定性授权计算 |
+| `approvals` | 内容绑定申请、决定、过期和通知 |
+| `tasks` | task/attempt、provider 路由、状态和取消 |
+| `relay` | 可选有界数据中继，不解释能力正文 |
+| `packages` | 不可变对象、签名目录、通道和撤销 |
+| `federation` | 网关身份、offer、双边策略和跨组织映射 |
+| `audit` | 事务内审计写入、查询、保留和导出 |
+
+模块通过服务接口调用，API handler 不直接拼接跨组织 SQL 或自行计算权限。
+
+## 4. API 边界
+
+建议分为四类 audience：
+
+```text
+/api/v1/web/*         管理控制台与成员自助 API
+/api/v1/device/*      设备注册、目录和任务控制 API
+/api/v1/federation/*  ShareServer 间 API
+/api/v1/public/*      服务描述、健康与登录入口
+```
+
+设备使用 WebSocket `/api/v1/device/connect` 建立出站控制通道。包下载使用短期、绑定主体和对象
+摘要的 URL。联邦 API 使用网关身份，不接受普通用户 session。每类 token 使用不同 issuer/
+audience/scope，不能互换。
+
+所有请求经 schema、认证、organization scope、授权、速率和大小边界。列表使用游标分页和固定
+最大页；错误返回 request ID、稳定 code 和有界参数。
+
+## 5. 数据模型
+
+核心表建议为：
+
+```text
+instances
+identity_providers
+users
+organizations
+memberships
+groups
+group_members
+role_bindings
+registered_devices
+device_credentials
+device_connections
+capabilities
+capability_versions
+providers
+publications
+grants
+policies
+approval_requests
+approval_decisions
+tasks
+task_attempts
+task_events
+package_objects
+package_releases
+release_channels
+update_policies
+federation_trusts
+federation_capability_exports
+audit_events
+revocations
+```
+
+要求：
+
+- 所有组织数据表包含不可为空的 `organization_id`，并由 repository 层强制作用域。
+- 唯一约束同时包含 organization，避免跨组织名称冲突泄漏。
+- 密钥保存为单向摘要或经外部主密钥加密的密文；数据库不保存明文 token。
+- 在线连接和短期 nonce 主要在内存；表中只保存恢复所需元数据，不把 socket 当持久对象。
+- task event 只存控制状态和有界统计；正文流不进入普通关系表。
+
+## 6. 事务与一致性
+
+- 业务变更与对应审计事件在同一 PostgreSQL 事务提交。
+- Publication/Grant/Policy 使用 revision 做乐观并发，Web 草稿不能覆盖他人更新。
+- 授权决定创建 task 时再次读取当前 revision，并将命中策略摘要冻结到 task。
+- 设备在线状态允许短暂最终一致；身份、撤销、授权和任务接受必须走权威存储。
+- 重复注册挑战、联邦 offer 和 task create 使用唯一幂等键。
+- 无法确认 provider 副作用时只更新 `outcome_unknown`，不靠消息队列自动重放。
+
+## 7. 设备连接与任务
+
+连接建立后完成设备 credential、organization、客户端协议和当前 registration 校验。服务端为
+每个连接设置心跳、空闲、帧、发送队列和并发上限。
+
+任务流程：
+
+```text
+authorize -> create task -> resolve exact provider connection
+-> send declaration -> provider accepts/rejects
+-> establish direct or relay route -> stream progress
+-> provider terminal result -> caller delivery -> audit terminal state
+```
+
+同一设备重复连接时使用 connection generation；新连接接管未来任务，旧连接仍只允许完成或
+查询已归属 task，随后有界关闭。不能把新任务随机发到身份相同但 generation 过期的 socket。
+
+## 8. 中继
+
+中继是可选模块：
+
+- 控制面与中继可部署在不同进程，但共享 task 授权验证。
+- 每个 relay ticket 绑定 task、调用方、provider、方向、期限和最大字节。
+- 实现背压和全局/组织/设备并发及带宽上限。
+- 不解析能力正文，不写普通日志；需要临时落盘时使用加密 GoodBuddy-owned 暂存并按 task 清理。
+- 中继关闭、过载或策略禁止时返回准确路由错误，不静默转到其他节点。
+
+## 9. Package 存储
+
+上传先进入不可公开暂存：流式计算大小和 SHA-256，验证签名、manifest、版本、平台和权限后，
+以 digest 发布为不可变对象。相同 digest 可去重，但组织授权和 Release 分别保存。
+
+Release catalog 使用独立签名域。服务器不能重打包已签名 payload；镜像目标必须保持相同字节、
+大小和 SHA-256。撤销更新目录和授权，不覆盖或原地删除仍受审计保留的对象。
+
+## 10. 联邦协议
+
+- 每个实例生成网关身份和可轮换证书，私钥不进入数据库备份明文。
+- offer 包含双方可人工核对的组织名、端点、指纹、协议和 nonce。
+- 双方确认后交换有界 capability projection 和本地映射 ID。
+- 跨组织 task 带双方关联 ID 和短期签名声明；每端独立授权并各写审计。
+- 不接受调用方提供的任意回调 URL、第三方 hop 或内部主体 ID。
+- 证书轮换需要旧身份签名或双方重新确认；身份突变直接暂停关系。
+
+## 11. Web 安全
+
+- 使用 HttpOnly、Secure、SameSite cookie 和 CSRF 防护管理 Web session。
+- OIDC 使用 state、nonce、PKCE 和固定回调地址。
+- 富文本字段按纯文本显示；manifest/schema 使用安全代码查看器，不执行 HTML。
+- 权限隐藏仅改善界面，所有 API 在服务端重新校验。
+- 登录、设备注册、目录、审批、导出和联邦接口分别限速。
+- 密钥字段只能替换、轮换和测试，永不回显。
+
+## 12. 部署与配置
+
+最小生产部署：
+
+```text
+TLS reverse proxy/load balancer
+ShareServer API + Web
+PostgreSQL
+可选：S3 compatible object storage
+可选：Relay worker
+```
+
+部署配置通过环境变量或挂载文件提供数据库、主密钥、公开 URL、OIDC、邮件、对象存储和限制。
+普通 Web 管理员不能修改基础设施秘密。提供数据库迁移命令、不可变镜像、非 root 容器、健康
+与就绪端点、优雅停止和部署示例。
+
+## 13. 可观测性与备份
+
+- 结构化日志只包含 request/task/organization 关联 ID、稳定事件和错误码。
+- 指标覆盖请求、WebSocket、授权结果、任务状态、中继、Package 和联邦，不包含能力正文。
+- tracing 跨内部服务传播关联 ID，跨联邦只传播双方同意的关联标识。
+- 备份 PostgreSQL、Package 对象和网关身份；不备份缓存、Web session、nonce 或中继暂存。
+- 恢复后撤销列表、组织 ID、签名目录和审计序列保持有效，所有设备重新连接。
+
+## 14. 测试策略
+
+### 14.1 自动化
+
+- schema、认证 audience、CSRF、OIDC 和设备挑战。
+- 每个 repository/API 的跨组织隔离与枚举防护。
+- 拒绝优先授权、审批内容绑定、预算和并发。
+- device generation、离线、撤销、重连和 provider 冻结。
+- task 幂等、取消、结果未知和不自动重放。
+- Package 流式校验、不可变性、权限 diff 和撤销。
+- 联邦双方确认、策略交集、暂停、证书变化和禁止第三 hop。
+- 审计事务、过滤、分页、导出和正文缺失。
+
+### 14.2 集成与部署
+
+- Desktop 与真实 ShareServer 完成注册、目录、调用、文件和取消。
+- 两个隔离组织验证搜索、计数、错误、对象和审计不泄漏。
+- 两个 ShareServer 完成联邦建立、跨组织调用和单方撤销。
+- 中继关闭与开启、容量耗尽、连接中断和大文件背压。
+- 数据库备份恢复、版本升级、滚动停止和设备重连。
+- 生产 TLS、OIDC 和对象存储组合的端到端验证。
+
+设计完成不代表服务已实现；只有独立部署和真实 Desktop 端到端路径通过后才能更新实施状态。
@@ -0,0 +1,159 @@
+# ShareServer Web 管理界面设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [ShareServer PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+
+ShareServer 是独立 Web 产品，不直接复用 Electron 页面壳层实现，但沿用 GoodBuddy 的语义
+词汇、状态含义和克制的运营工具风格。界面以列表、表格和主从详情为主，不使用营销首页或
+装饰性卡片墙。
+
+## 1. 使用对象
+
+- 普通成员主要在 GoodBuddy Desktop 使用能力；Web 端只处理自己的设备、申请和授权。
+- 组织管理员使用完整组织控制台。
+- 系统管理员使用与组织控制台分开的实例管理范围。
+- 审计员进入只读视图，不显示可变更控件。
+
+登录后直接进入当前身份可用的实际控制台，不显示产品宣传页。
+
+## 2. 全局框架
+
+```text
+顶部栏：ShareServer 实例名 | 当前组织 | 全局搜索 | 审批 | 账号
+
+侧栏：
+概览
+组织与成员
+设备
+能力目录
+权限策略
+审批
+发布与更新
+网关联邦
+任务与中继
+审计
+系统设置（仅系统管理员）
+```
+
+当前组织始终显示。切换组织会重新加载整个数据范围，不保留上一组织的选择、筛选或详情。
+系统管理使用“实例范围”标识，不能伪装成某个组织。
+
+## 3. 概览
+
+概览只显示需要行动和运行事实：
+
+- 待审批数量及最旧等待时间。
+- 在线/离线/已撤销设备。
+- 可用/离线/暂停能力。
+- 当前任务、失败和结果未知。
+- 包更新异常和紧急撤销。
+- 联邦连接异常。
+- 中继流量和容量，仅在中继启用时显示。
+
+指标可点击进入已带筛选的对应页面。没有事件时不显示虚构趋势。
+
+## 4. 组织与成员
+
+使用“成员”“用户组”“角色”三个同级页签。成员表包含姓名、身份源、组、状态、设备数和
+最近活动。邀请是唯一主操作；暂停和移除进入行末菜单。
+
+成员详情采用抽屉，显示身份、组、角色、设备、有效 Grant、申请和审计。管理员不能查看成员
+任务正文或桌面文件。
+
+## 5. 设备
+
+```text
+设备             所有者      平台        状态      能力      最近在线
+Jiang-PC         Jiang       Windows     在线      2        刚刚
+GPU-Worker-02    AI Team     Linux       离线      8        2 小时前
+```
+
+设备详情包含概览、连接、已发布能力、Grant 和活动。设备状态与 Publication 状态分别显示。
+撤销设备使用危险确认，说明新任务、活动任务和重新注册影响。
+
+## 6. 能力目录
+
+目录以能力为第一列，提供者为可展开信息：
+
+```text
+能力              版本       提供者       可见范围      可用性
+图像生成          2.1.0      3 个节点     设计组        2/3 在线
+```
+
+详情包含 manifest、provider、Publication、允许输入、数据政策、调用趋势和最近错误。管理员
+看到的是组织元数据，不通过目录读取能力内部数据。
+
+## 7. 权限策略
+
+策略页分“强制策略”和“Grant”。创建和编辑使用结构化表单：主体、能力、动作、输入、提供者、
+时间、预算、批准和委托。保存前提供自然语言摘要：
+
+> 允许“设计组”从合规设备调用组织内“图像生成”2.x；只发送文本和图片；每人每日 20 次；
+> 不允许下游委托。
+
+策略冲突预览显示最终结果和命中规则，但不提供允许规则覆盖拒绝规则的顺序拖拽。
+
+## 8. 审批
+
+审批收件箱按调用、发布、更新和联邦分类。详情必须显示申请人、能力或对象、目标范围、数据
+类别、权限变化、期限和策略依据。批准按钮使用具体文案，例如“允许本次调用”“批准此版本
+发布”，不能只有“同意”。
+
+批量批准仅用于同类型、同策略且不包含权限扩大的低影响申请；联邦和权限扩大更新不支持
+批量批准。
+
+## 9. 发布与更新
+
+页面分“能力包”“发布通道”“更新策略”“撤销记录”。Package 表显示版本、发布者、签名、
+大小、目标平台、权限变化和状态。上传后先进入验证，不直接发布。
+
+版本详情提供 manifest、摘要、签名、兼容范围、权限 diff、依赖和下载事实。紧急撤销位于
+独立 danger zone，需要输入版本标识确认，并说明受影响设备和新任务。
+
+## 10. 网关联邦
+
+```text
+合作组织          对端地址                 状态       开放能力     有效期
+法务服务商        share.legal.example      已连接     2 项         12-31
+```
+
+建立关系采用向导：填写端点、核对组织和指纹、选择公开范围、设置调用与数据限制、生成 offer、
+等待对方确认、复核双方交集。只有双方完成后显示“已连接”。
+
+详情明确展示“我方开放”“对方开放”“最终可用”三个集合。暂停和撤销说明对活动任务的处理。
+
+## 11. 任务与中继
+
+任务表显示调用方、能力、provider、路由、数据类别、状态、耗时和时间。默认不显示正文。
+活动任务提供取消；结果未知使用独立状态并显示 provider 最后确认点。
+
+中继未启用时页面显示控制面正常和启用位置，不展示零值图表。启用后显示活动连接、吞吐、
+排队、容量和拒绝原因，不提供查看正文的调试入口。
+
+## 12. 审计
+
+提供操作者、动作、对象、组织、结果、时间和关联 ID 的可筛选表格。导出前显示条件、估算行数、
+时区和字段范围；大导出作为后台任务生成有时效下载。审计详情保持只读，不把原始内部错误、
+认证信息或任务正文显示给管理员。
+
+## 13. 系统设置
+
+只包含实例名称、公开地址、身份源、邮件、数据库/对象存储状态、中继开关与上限、保留策略、
+联邦总开关、证书和版本。秘密字段只支持替换或测试，不回显原值。
+
+运行时基础设施配置优先来自部署环境；Web 界面不能修改数据库连接串、主密钥或容器挂载路径。
+
+## 14. 状态、响应式与无障碍
+
+- 加载、无数据、无匹配、无权限、服务错误和部分不可用分别展示。
+- 管理表格支持键盘访问、可见焦点、表头关联和分页；行菜单有可访问名称。
+- 窄屏将表格转为字段列表，保持组织、来源、状态和风险信息，不把管理动作挤成不可辨图标。
+- 所有时间显示实例时区并可查看 ISO 时间；联邦事件同时显示对端时间时标明时区。
+- 状态不只依赖颜色。危险操作在确认后保持原页面上下文和可恢复错误。
@@ -9,8 +9,9 @@
 以及知识库、魔法笔记、智能心跳、桌面上下文和远程消息通道等桌面助手能力。
 下载区位于主要功能说明之前，并明确列出统信 UOS、银河麒麟、海光、兆芯、
 鲲鹏、飞腾和龙芯。页面不重复设置底部下载推广区。
-英文页面位于 `en.html`，不展示信创适配文案，三个平台的下载按钮始终前往
-GitHub 最新正式 Release。
+英文页面位于 `en.html`，用平台与架构覆盖描述同一产品事实，不使用中文信创
+政策语汇；页面会标明独立的 LoongArch 实验预览，但三个平台的下载按钮仍始终
+前往 GitHub 最新正式 Release。
 首屏产品界面默认正面展示，在精确指针设备上使用克制的 3D 倾斜、
 柔和跟随光效和同步浮动标签；触屏设备保持静态布局，系统启用“减少动态
 效果”时不运行该交互。