root/goodbuddy-shareserver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add local model gateway and console tabs

Browse Source
This commit is contained in:
lofyer
2026-10-12 14:21:13 +08:00
parent 9fa8f3e762
commit ec2c90d208
46 changed files with 3491 additions and 1120 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/share-server/README.md
+23 -10
View File
@@ -23,34 +23,43 @@ ShareServer 不属于 Electron Main，不负责桌面端局域网发现，也不
| 文档 | 权威职责 |
| --- | --- |
| [产品功能列表](./feature-list.md) | 按模块、页面和 Tab 汇总功能范围、状态和当前交付边界 |
| [PRD](./prd.md) | 管理角色、产品范围、功能需求和验收 |
| [用户故事](./user-stories.md) | 工作空间、实时消息、资料同步及数字分身处理的验收场景与逻辑审查 |
| [功能逻辑](./logic-design.md) | 组织隔离、设备、发布、策略、任务和联邦状态规则 |
| [管理界面设计](./ui-design.md) | ShareServer Web 控制台的信息架构与交互 |
| [技术设计](./technical-design.md) | 服务模块、API、数据、部署、运维和验证 |
| [后端基础设计](./backend-foundation-design.md) | GoodBuddy 适配依据；B1 已实现、验收部分完成，B2 至 B6 待实现 |
| [实施进度](./progress.md) | 已验证实现、剩余生产工作与验证证据 |
| [共享网络总体设计](../../../../goodbuddy/docs/architecture/share-network-architecture.md) | 跨端身份、能力、授权、任务、更新和协议权威（GoodBuddy 仓库） |
| [Desktop Office 协同编辑](../../../../goodbuddy/docs/features/office-document-editing/README.md) | 文档 Tab、源文件回写、冲突和 AI 选区编辑（GoodBuddy 仓库） |
工作空间协作场景由用户故事追踪；管理员、能力发布者、审计员等既有场景继续由 PRD 与逻辑
设计覆盖。仓库已有全控制台交互原型及本地共享目录服务，后者持久化 GoodBuddy 注册和发布的元数据。
设计覆盖。仓库已有控制台交互原型、本地共享目录服务和真实转发的本地模型网关；目录持久化
GoodBuddy 注册和发布的元数据，网关独立保存上游、模型映射和有界调用元数据。
组织生产服务尚未实现。当前边界和运行方法见[实施进度](./progress.md)与
[`README.md`](../../../README.md)。跨仓库文档链接要求将 `goodbuddy` 与
[`README.md`](../../../README.md)。历史演示与测试记录保留其原有范围，当前实现说明不追溯扩大验证结论。
跨仓库文档链接要求将 `goodbuddy` 与
`goodbuddy-shareserver` 克隆到同一级目录；服务构建和运行不依赖桌面端仓库。
当前源码按 `web/src/`、`server/src/` 和根 `shared/` 组织，构建、测试与依赖仍由根目录统一管理。
目录和产物路径见[技术设计第 1 节](./technical-design.md#1-仓库与运行边界)。
## GoodBuddy 服务演示
## GoodBuddy 服务入口
当前新增 `/model-gateway`（模型网关）、`/documents`（文档与协作）、`/distribution`（配置下发）
三个路由，演示策略判断、文档归属与回收站、OnlyOffice 实例配置和检查、按组发布与回退。
三页导航共享会话内存，刷新重置；服务演示操作不发网络请求、不写本地存储。角色开关、检查
结果和在线设备应用状态均为模拟，未实现推理、真实转发、Office 编辑保存或设备交付。
具体交互见 [UI 设计第 16.1 节](./ui-design.md#161-goodbuddy-服务演示)。
`/model-gateway` 提供上游与模型映射保存、服务端加密凭据、模型访问 Key、真实模型发现、请求测试
和调用元数据审计。管理仅限直连回环，客户端通过 Bearer Key 访问获授权的模型；组织认证、组织
隔离及配额控制仍待实现。旧环境引用保留存储兼容，前缀导入界面和接口已移除。
网关独立于 GoodBuddy 运行，无桌面源码依赖；个人既有配置仅可用于明确授权的环境测试，不自动读取或迁移。
启动方法及客户端 Base URL 见[根 README](../../../README.md#local-model-gateway)，接口、存储和限制见
[技术设计第 4.2 节](./technical-design.md#42-本地模型网关契约已实现)。
共享中心沿用 `/capabilities`。能力目录、共享知识库、按用户查看和按设备查看使用示例数据；
“本地服务目录”页签读取真实本地记录。来源模式、权限展示与跳转约定见
`/documents` 显示待接入说明，没有示例文档或 OnlyOffice 模拟检查。`/distribution` 同样为待接入占位，
无配置草稿、设备回执、发布或回滚；保存网关模型
不会自动下发到 GoodBuddy。交互见 [UI 设计第 16.1 节](./ui-design.md#161-goodbuddy-服务入口)。
`/devices` 和共享中心沿用真实本地 API：前者展示登记设备及其发布数量，后者直接读取设备与发布记录，支持筛选、设备跳转和撤销已发布元数据；已移除组织示例页签。
来源模式与知识权限仅为声明，尚无正文服务。交互约定见
[UI 设计](./ui-design.md)，本地 API 见[技术设计第 4.1 节](./technical-design.md#41-本地共享目录契约已实现)。
本地体验：在本仓库运行 `npm run dev`，在 GoodBuddy 仓库运行 `npm run dev`，从桌面应用中心
@@ -58,6 +67,10 @@ ShareServer 不属于 Electron Main，不负责桌面端局域网发现，也不
`http://127.0.0.1:5174/capabilities?view=local` 查看。服务数据默认保存到 `data/sharing.json`。
完整桌面范围与验证见[设备共享文档](../../../../goodbuddy/docs/features/device-sharing/README.md)。
[后端基础设计 B1](./backend-foundation-design.md#4-b1正常模型网关接入)代码已实现，验收部分完成：
已记录 103 项自动化测试及部分真实 API 验证；完整工具结果回传、GoodBuddy Desktop 和浏览器界面
验收仍未完成。Vite `/api` 只允许回环 socket，容器／反向代理管理须等待 B2 登录。
## 角色
- **系统管理员**：维护实例、身份源、域名、证书、存储和全局限制。
docs/features/share-server/backend-foundation-design.md
+190
View File
@@ -0,0 +1,190 @@
# 基于 GoodBuddy 的后端基础设计
状态：B1 已实现、验收部分完成，2026-10-05；B2 至 B6 待实现。原始设计日期为 2026-10-04。
本文是[技术设计](./technical-design.md)的基础服务实施分册，维护客户端适配依据、接口和实施顺序。
产品范围由 [PRD](./prd.md)维护，业务状态由[功能逻辑](./logic-design.md)维护，已验证事实见[实施进度](./progress.md)。
## 1. 设计结论
GoodBuddy 承担模型选择、对话、工具执行、知识检索入口和文档日常操作。ShareServer 独立运行，
负责模型请求转发、组织身份与授权、共享目录和服务端文档存储。ONLYOFFICE 是独立编辑服务。
不把 Electron、客户端 SQLite、Agent Runtime 或客户端源码引入服务端构建。
基础功能优先利用客户端已有调用路径：先完成正常的模型网关接入，再增加组织与设备身份，
随后实现组织模型导入和真实资源发布。知识检索、文档编辑各自按实际用户动作验收。
完整组织服务仍以 PostgreSQL 为目标；本地网关阶段继续单进程文件存储，不先建设消息系统、联邦或通用任务平台。
## 2. 客户端依据与差距
下表链接指向相邻 `goodbuddy` 仓库，要求两个仓库位于同一级目录。只引用契约，不建立源码依赖。
| 客户端实现 | 已核对行为 | 后端设计影响 |
| --- | --- | --- |
| [模型配置 schema](../../../../goodbuddy/src/shared/contracts.ts) | profile 含 `baseUrl`、`modelName`、显式 `protocol`、认证方式及能力设置；模型 ID 最长 128 字符 | 开放模型 ID 按客户端限制保存；目录携带协议，不能只返回显示名称 |
| [OpenAI 地址拼接](../../../../goodbuddy/src/main/agent/openai-endpoint.ts) | 在 Base URL 后追加 `chat/completions` 或 `responses`；不自动增加 `/v1` | 接入信息必须给出包含 `/v1` 的完整 Base URL |
| [模型 Runtime](../../../../goodbuddy/src/main/agent/model-runtime.ts) | 连接测试发非流式生成请求；对话走 SSE，包含工具、工具结果和用量字段 | 获取模型成功不能代替连接测试；必须验收 JSON、SSE 与工具往返 |
| [配置存储](../../../../goodbuddy/src/main/runtime-settings-store.ts)、[凭据加密](../../../../goodbuddy/src/main/settings-credential-cipher.ts) | Main 保管模型 Key，Renderer 只看到是否已配置 | Desktop 保存网关访问 Key，上游 Key 留在 ShareServer |
| [模型选择](../../../../goodbuddy/src/shared/runtime-selection-contracts.ts) | 会话、项目、全局逐层解析模型 profile | 导入组织模型不覆盖个人模型，也不自动更换已有会话选择 |
| [设备共享服务](../../../../goodbuddy/src/main/device-sharing-service.ts) | 单服务 URL，稳定设备 ID，HTTP 注册、列表、发布和撤销；没有认证或心跳 | 现有 ID 不能当作用户身份；注册记录不能标为在线 |
| [发布契约](../../../../goodbuddy/src/shared/device-sharing-contracts.ts) | 仅名称、描述、类型、来源模式和权限声明，没有实际资源 ID | 不能从目录记录直接派发执行或检索请求 |
| [能力目录](../../../../goodbuddy/src/main/capabilities/capability-service.ts) | 可枚举本机 Skill、MCP 等配置 | 后续发布选择器可复用枚举；枚举结果不自动授权共享 |
| [知识服务](../../../../goodbuddy/src/main/knowledge/knowledge-service.ts) | `retrieve`、`retrieveMany` 是现有检索入口 | 提供端经授权后直接调用知识服务，不用 Agent 提示词代替检索协议 |
| [外部知识契约](../../../../goodbuddy/src/shared/external-knowledge-contracts.ts) | 当前提供者是 Dify、FastGPT、RAGFlow | ShareServer 共享知识需要新增适配，不能假设现有外部连接已支持 |
| [Office 功能文档](../../../../goodbuddy/docs/features/office-document-editing/README.md) | Office 编辑尚在设计；文件解析与外部打开已有实现 | 服务端 callback 和客户端文档 Tab 都要实现，不能把解析当作编辑 |
GoodBuddy 目前没有自动获取网关模型并创建 profile 的通用流程。现有设备共享页面也不会自动
启用模型连接。设备共享应用仍默认关闭，名称保留“设备共享（技术预览）”。
模型协议分别验收：本期只支持 `openai-chat-completions`。Responses、Anthropic、图像生成和
Embedding 均不因为上游声称“OpenAI 兼容”而自动支持。现有网关也没有这些转发端点。
远程 Agent 使用模型时，发请求的 Host 必须能访问网关；桌面本机的 `127.0.0.1` 地址不能直接用于该场景。
## 3. 服务划分与存储
| 服务 | 第一项可用行为 | 数据归属 |
| --- | --- | --- |
| 模型网关 | 保存上游、开放模型、验证访问 Key、转发并记录调用 | 上游配置及凭据、映射、访问 Key 摘要、调用元数据 |
| 身份与组织 | 管理员初始化、成员登录、加入组织 | 用户、组织、成员关系、会话 |
| 设备与目录 | 认证设备登记、撤销、发布者和资源绑定 | 设备归属、发布记录、动作授权；设备连接状态单独管理 |
| 客户端配置 | 显式获取并导入组织模型，回报应用结果 | 组织配置版本与每设备接收／应用结果 |
| 知识共享 | 对指定发布条目检索并返回引用 | 服务端保存发布元数据；远程模式的正文仍在提供设备 |
| 文档服务 | 上传、读取、编辑后保存、按归属删除或转交 | 主文档、归属、版本、回收记录；编辑会话单独保存 |
继续沿用 Hono 路由、业务 Store 和根 `shared/` DTO。业务增长后按上述职责拆文件，不预先建立
空模块树或通用插件框架。HTTP 边界校验输入与输出投影，控制台只使用 API，不直接访问存储。
现有 `sharing.json` 与 `gateway.json` 保留。网关新增秘密使用服务端加密密文，组织阶段再将
用户、组织、设备和授权纳入 PostgreSQL 事务。迁移要保留现有 ID 和撤销事实；没有身份的旧目录
只能作为未绑定记录，不能按设备名称自动认领。迁移命令、备份和重复执行行为随数据库实现交付。
## 4. B1：正常模型网关接入
这一实施单元完成本地可用路径，不依赖组织数据库。支持一个 ShareServer 实例、多个上游和
多个模型映射；使用本机管理入口，GoodBuddy 可手工配置网关。组织分组、费用结算、自动切换上游另行实现。
### 4.1 上游与凭据
新建上游输入 `name`、`baseUrl`、`protocol=openai-chat-completions`、`authentication=api-key|none`、
`enabled`。使用 API Key 时输入真实密钥。更新通过 `credentialAction=keep|replace|clear` 区分
保留、替换和清除，空输入不解释为清除。响应只返回 `credentialConfigured`，不返回密钥或密文。
使用 Node 标准加密实现 AES-256-GCM；主密钥来自部署配置或数据目录外的秘密文件，首次配置
命令为 `npm run gateway:init-key -- <文件路径>`，父目录须已存在，拒绝覆盖已有文件。
通过 `SHARESERVER_MASTER_KEY_FILE` 指定文件，或用 `SHARESERVER_MASTER_KEY` 提供 64 位十六进制值，不能同时设置。
密文带随机 nonce 与认证标签，以稳定上游 ID 为 AAD，随上游记录原子保存，避免独立文件半提交。
缺少或错误的主密钥应报告凭据不可用，不能生成新密钥覆盖既有密文。备份说明要求单独保管主密钥。
主密钥不进入 Web、普通数据备份和日志；HTTP 请求正文不记录密钥。
现有环境变量引用是已持久化的数据，需要继续可读、可调用；编辑时可以显式替换为托管凭据。
移除产品界面的前缀导入和变量名输入，环境文件加载仅保留为开发测试方式，不自动扫描 GoodBuddy 配置。
Base URL 接受 HTTP/HTTPS，保留合法服务路径，拒绝内嵌凭据、query 和 fragment，去掉尾斜杠。
可信内网 HTTP 上游已属于支持范围。访问 Key 经非加密 HTTP
传输的部署限制在接入说明中说明，对外部署使用 HTTPS；不为此加入额外网络发现流程。
### 4.2 模型与转发
发现模型调用上游 `/models`，发现失败不删除已保存配置，也不阻止手动填写模型 ID。
用户选择模型并指定对外 ID 后才创建映射。新对外 ID 最长 128 字符，首字符为 ASCII 字母或数字，
其余允许字母、数字、下划线、点、冒号、斜杠、连字符；显示名称单独保存。现有更长别名保留调用，
在导入 GoodBuddy 前要求管理员显式改名，不静默截断已有标识。
每个对外 ID 明确绑定一个上游和远端模型。转发只替换模型名与上游认证，不执行工具，不自动重试
有可能已经执行的请求。工具参数、工具结果和用量按 Chat Completions 协议传递；取消传播至上游。
保留现有超时、输出大小边界和终态审计。上游缺失用量记录为未知，不显示为零消耗。
### 4.3 网关访问与管理边界
客户端访问 Key 与上游 API Key 分开。服务端生成随机访问 Key，只在创建成功时返回完整值，
持久化 SHA-256 摘要、ID、名称、创建／撤销时间和允许的模型记录 UUID；别名改名不改变授权，列表不返回原值。可撤销后重新创建，
不提供读取旧 Key。初期 Key 代表一个调用配置，审计可关联 Key ID，但不能把备注名解释为已认证用户。
`/v1/models` 与 `/v1/chat/completions` 使用 Bearer Key；未知或撤销的 Key 返回 401，
无权调用该模型返回 403。列表只返回该 Key 允许且可用的模型。停用或撤销阻止后续请求，
已开始的流按原请求结束或由调用方取消；本期不承诺撤销自动追回已输出内容。
本机管理接口不能仅依靠 Origin 检查授权。B1 默认管理请求限直连回环来源，校验实际连接地址，
拒绝携带 `Forwarded`、`X-Forwarded-*` 或 `X-Real-IP` 的管理请求，并检查 Origin。
Vite 在代理 `/api` 前也检查原始 socket，只允许回环。除健康和就绪 GET 外，非回环 API 请求
仅能访问已带 Key 的推理接口；无认证旧目录 API 也保持
本机访问。容器／反向代理管理需要 B2 登录接入，不能将代理地址当作管理员。Web 网关测试仍通过
网关转发逻辑，由本机管理入口调用，不在浏览器长期保存管理秘密或把豁免开放给推理接口。
### 4.4 已实现接口
下表记录 B1 已实现接口，字段、错误及资源限制以技术设计第 4.2 节为准。前缀导入接口已移除，旧环境引用仅保留存储兼容。
| 路径 | 已实现行为 |
| --- | --- |
| `GET /api/v1/gateway/config` | 上游与模型公开投影、调用元数据、部署指定 `gatewayBaseUrl`；不携带任何密文或完整 Key |
| `POST /api/v1/gateway/upstreams`、`PUT /api/v1/gateway/upstreams/:id` | 接收地址、协议、认证方式和凭据操作，替代新表单的 `apiKeyEnv` |
| `POST /api/v1/gateway/upstreams/:id/discover` | 真实模型发现，保留手工映射入口 |
| `POST /api/v1/gateway/models`、`PUT /api/v1/gateway/models/:id` | 保存对外 ID、显示名、远端模型和启停 |
| `GET/POST /api/v1/gateway/access-keys` | 列表或创建模型访问 Key |
| `POST /api/v1/gateway/access-keys/:id/revoke` | 撤销 Key，重复撤销返回同一撤销事实 |
| `POST /api/v1/gateway/test` | 本机管理端非流式测试；复用真实转发及审计，不接受自定义上游 URL |
| `GET /api/v1/gateway/v1/models` | Bearer 认证后的 OpenAI 模型列表 |
| `POST /api/v1/gateway/v1/chat/completions` | Bearer 认证、模型授权、JSON/SSE 转发 |
Key 无效返回 401，其余错误沿用 `{error:{code,message},requestId}`，请求 ID 与调用
审计关联。不能把上游含密钥的错误正文原样返回；保留可定位的上游状态和错误类别。
### 4.5 GoodBuddy 使用与验收
管理员保存上游并开放模型后，在网关接入区取得 Base URL、协议和对外模型 ID，创建访问 Key。
GoodBuddy 在现有模型连接页面手动新增配置：
```text
Base URL: http://127.0.0.1:8787/api/v1/gateway/v1
Protocol: openai-chat-completions
Model: 管理员开放的模型 ID
API Key: ShareServer 签发的访问 Key
```
该操作不依赖设备共享开关，不读取供应商 Key，不修改个人已有 profile。异机调用用客户端可达
的 ShareServer 地址；界面显示配置的公开地址，不能把 Vite 端口或请求中的任意 Host 当作权威地址。
以下为完整验收清单，尚未全部通过。2026-10-05 已完成自动化检查和部分真实 API 验证，
包括发现、JSON/SSE、工具选择及本地执行、重启持久化与撤销拒绝；工具结果未回传上游，
未验证 GoodBuddy Desktop；浏览器仅核对页面快照，交互与视觉验收未完成。详细证据和剩余项目见[实施进度](./progress.md)。
验收依次检查：
1. 从空目录经 Web 保存真实上游，发现或手动添加模型；刷新、重启仍保留配置，密钥不回显。
2. GoodBuddy 现有模型连接测试成功，真实会话收到流式回答，审计可以关联模型和访问 Key。
3. 用无副作用工具完成一次真实工具调用与结果回传；停止生成时上游请求被取消。
4. 错误 Key、撤销 Key、未授权模型和停用上游均拒绝新调用，错误不伪装成空成功响应。
5. 上游超时、SSE 中断、凭据缺失、主密钥错误均给出准确状态；检查持久化及日志不含明文秘密或对话正文。
6. 验证 HTTP 内网上游及管理接口来源限制。单元测试不能替代上述桌面与真实服务验证。
这组验证只覆盖本机模型 Runtime。OpenCode、Continue、Harness 和远程 Agent 另行记录结果，
不从同一个 profile 推断全部 Runtime 可用。真实模型验证记录调用次数，不将配置下发标记为已实现。
## 5. 后续基础服务实施顺序
| 单元 | 交付内容 | 前置条件与完成标准 |
| --- | --- | --- |
| B2 身份与组织 | PostgreSQL 迁移、首个管理员、登录退出、单组织成员、设备绑定与撤销；Web 使用会话，Desktop 凭据在 Main 保存 | 从可信本机管理扩展到组织部署；两个不同成员不能改动对方设备或私人资源；退出或撤销后新请求被拒 |
| B3 组织模型导入 | 认证目录、用户显式导入、组织模型来源标记、配置版本与应用回报 | 依赖 B2；客户端创建独立 profile，保留个人配置；离线为待接收，收到后保存成功才为已应用 |
| B4 真实资源发布 | 从本机能力／知识库选择资源，登记稳定来源 ID、所有者、提供设备及独立动作权限 | 依赖 B2；客户端增加资源绑定和提供端通道；无心跳不显示在线，旧手工目录不自动成为可调用资源 |
| B5 共享知识检索 | 消费者选共享库，服务端授权并路由，提供端调用 `retrieveMany`，返回有界引用 | 依赖 B4；两台 GoodBuddy 真实检索，撤销及提供端离线有准确失败；正文读取、下载各自另验收 |
| B6 服务端文档 | 主文档上传、读取、个人删除、转交组织、回收；再接 ONLYOFFICE 编辑保存与 GoodBuddy 文档入口 | 归属功能依赖 B2；保存后重开及重启可见，转交后个人删除权失效，管理员元数据可见不赋予正文权限 |
Office 私有 DOCX 试验仍可按技术设计第 10.1 节独立验证部署与保存。该试验没有用户归属，
不能替代 B6。后续服务端主存文档保存不要求 Desktop 回写确认；显式本地／SSH 来源模式另走既有源文件契约。
B3 先实现主动获取和显式导入，不以推送、离线队列或回滚系统为第一步。组织配置关联服务端稳定
模型 ID，个人 profile 不由组织配置覆盖。组织撤销后网关直接拒绝访问，客户端缓存不能维持授权。
B4 的提供端连接必须单独实现。已有 Agent 执行通道没有发布身份、共享授权和知识正文协议，不能
直接暴露为共享 API。远程知识模式不上传整个库；服务器副本模式须实际完成文件与索引写入才可标为可检索。
## 6. 文档与实施记录
2026-10-04 设计轮只完成设计与源码核对，不更改两仓运行代码、不读取 `.env*`、不调用上游模型。
现有模拟接口仍留在服务端源码但已退出控制台路由，后续清理应单独验证调用方，不作为基础服务使用。
2026-10-05 按 B1 代码同步技术设计第 4.2 节、逻辑规则、UI 设计、运行文档和实施进度，
将实现状态与部分验收结果分开记录。B2 至 B6 和 B1 剩余验收继续按上述顺序推进。
跨产品网络与 Office 契约继续引用 GoodBuddy 原文；其总体架构仍有“没有真实 Desktop 集成”的旧描述，
应在后续 GoodBuddy 文档同步时改为“已有元数据接线，完整共享网络待实现”。本轮不修改相邻仓库。
docs/features/share-server/feature-list.md
+259
View File
@@ -0,0 +1,259 @@
# ShareServer 产品功能列表
## 文档用途
本文用于确定 ShareServer 的产品信息架构、页面范围和功能状态。功能按“模块、页面、Tab、功能”组织，页面结构先于功能细节确定。
状态含义如下：
| 状态 | 含义 |
| --- | --- |
| 已实现 | 代码和自动化验证已覆盖，范围以实施进度中的证据为准 |
| 部分实现 | 已有可运行功能，但生产验收或关键依赖尚未完成 |
| 设计中 | 已形成产品和技术设计，尚未作为生产功能交付 |
| 待规划 | 已进入产品方向，页面和接口仍需进一步确定 |
ShareServer 是 GoodBuddy 的独立组织后台。成员的日常操作主要在 GoodBuddy 中完成，ShareServer 负责设备目录、能力发布、授权、任务、模型网关、文档和审计等组织能力。当前仓库已经包含本地共享目录和真实转发的本地模型网关，生产身份、组织隔离、设备控制连接和工具执行尚未完成。
## 页面组织规则
- 一级导航按业务对象分组，页面只负责一个相对完整的管理对象。
- 页面内 Tab 按查看范围或操作阶段划分，不能把配置、运行记录和统计混在同一个 Tab。
- 列表、详情和创建表单属于同一 Tab 的交互，不单独扩成一级导航。
- Tab 名称使用产品对象或用户任务命名，避免使用“其他”“更多功能”等收纳式名称。
- 当前未接入的 Tab 可以进入，但必须显示待接入边界，不生成示例数据，也不提供不会生效的操作。
## 信息架构总览
| 一级模块 | 页面 | Tab | 当前状态 |
| --- | --- | --- | --- |
| 工作台 | 运行概览 | 服务状态、待处理事项、最近活动 | 部分实现 |
| GoodBuddy 服务 | 模型网关 | 概览、上游服务、模型目录、访问密钥、请求测试、调用审计、客户端接入 | 部分实现 |
| GoodBuddy 服务 | 文档与协作 | 文档库、编辑会话、Office 服务、保存记录 | 待接入 |
| GoodBuddy 服务 | 配置下发 | 配置草稿、设备生效、发布记录、回滚记录 | 待接入 |
| 共享资源 | GoodBuddy 接入 | 设备列表、设备详情、连接记录、撤销记录 | 部分实现 |
| 共享资源 | 共享中心 | 能力目录、共享知识库、按成员查看、按设备查看 | 部分实现 |
| 共享资源 | 数字人 | 数字人目录、我的数字人、调用权限、发布记录 | 设计中 |
| 组织管理 | 组织与成员 | 成员、用户组、角色、服务账号 | 设计中 |
| 组织管理 | 权限策略 | 强制策略、Grant、策略模拟、变更记录 | 设计中 |
| 组织管理 | 审批 | 待处理、已处理、我的申请、审批规则 | 设计中 |
| 组织管理 | 发布与更新 | 能力包、发布通道、更新策略、撤销记录 | 设计中 |
| 组织管理 | 网关联邦 | 合作组织、待确认、开放范围、事件记录 | 设计中 |
| 运营与审计 | 任务与中继 | 任务列表、活动任务、中继连接、运行统计 | 设计中 |
| 运营与审计 | 审计 | 事件查询、调用链、导出任务、保留策略 | 部分实现 |
| 系统 | 系统设置 | 实例信息、身份与登录、基础设施、中继与联邦、通知、保留与审计 | 设计中 |
| 成员自助 | 我的设备与授权 | 我的设备、我的授权、我的申请、我的数字人 | 设计中 |
## 1. 工作台
### 1.1 运行概览
| Tab | 内容 | 状态 |
| --- | --- | --- |
| 服务状态 | ShareServer、GoodBuddy 设备、模型上游和共享目录的关系；设备登记数、启用上游数和启用模型数 | 部分实现 |
| 待处理事项 | 待审批、失败任务、保存失败、连接异常和紧急撤销 | 设计中 |
| 最近活动 | 最近的注册、发布、网关调用、授权和任务事件 | 设计中 |
当前页面只展示真实 API 返回的服务拓扑和入口，不生成预设指标或活动记录。
## 2. GoodBuddy 服务
### 2.1 模型网关
模型网关为 GoodBuddy 和兼容客户端提供统一的模型请求入口。网关保存上游配置和模型映射，转发请求并记录有界调用元数据，不托管模型，也不在网关执行模型返回的工具调用。
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 概览 | 网关地址、启用上游数、启用模型数、访问密钥数、最近调用状态和管理边界 | 部分实现 |
| 上游服务 | 添加、编辑、启停上游；保存 Base URL、协议和认证方式；凭据留空则保留，填写则覆盖；发现远端模型 | 部分实现 |
| 模型目录 | 查看模型别名、远端模型名、所属上游和启用状态；手工添加或编辑映射；启停映射 | 部分实现 |
| 访问密钥 | 创建客户端 Bearer Key；按模型绑定授权范围；查看名称和状态；撤销密钥 | 部分实现 |
| 请求测试 | 选择可用模型发送真实非流式请求；显示结果；取消请求；提示数据去向和费用风险 | 部分实现 |
| 调用审计 | 查看时间、请求编号、模型、上游、访问密钥、流式方式、结果、HTTP 状态、耗时、Token 用量和错误码 | 部分实现 |
| 客户端接入 | 查看客户端 Base URL、协议、模型 ID 和配置步骤；说明客户端只使用网关访问 Key | 部分实现 |
模型网关的页面关系如下：
```text
概览
├─ 上游服务 管理外部模型服务连接
├─ 模型目录 管理客户端可见的模型映射
├─ 访问密钥 管理客户端调用凭据和模型授权
├─ 请求测试 验证模型请求转发
├─ 调用审计 查看调用结果和运行元数据
└─ 客户端接入 将已配置模型交给 GoodBuddy 或兼容客户端使用
```
网关后续扩展仍放在对应 Tab：
- 上游服务增加健康状态、延迟和错误率。
- 模型目录增加能力标签、路由规则和备用上游。
- 访问密钥增加主体、组织、有效期、配额和撤销原因。
- 请求测试增加工具调用和流式场景的受控验证。
- 调用审计增加 `traceId`、父子请求、决策、失败阶段和链路详情。
- 客户端接入增加按组织或用户组分发配置的能力。
组织身份、工具级权限、三态策略、供应商切换、配额、成本统计和工具执行属于后续网关能力，不能写成当前 Tab 已提供的操作。
### 2.2 文档与协作
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 文档库 | 主存文档、归属、版本、保留规则和检索 | 待接入 |
| 编辑会话 | 活动会话、访问模式、checkpoint、保存状态和过期处理 | 待接入 |
| Office 服务 | Document Server、回调、存储和健康检查 | 待接入 |
| 保存记录 | 服务端保存、结果未知、失败重试和本地源文件回写状态 | 设计中 |
首期 Office 范围为浏览器上传 DOCX、编辑、保存和重新打开。XLSX、PPTX、Desktop 文档 Tab 和本地回写属于后续范围。
### 2.3 配置下发
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 配置草稿 | 按客户端、设备或成员组编排模型和服务配置 | 待接入 |
| 设备生效 | 查看目标设备、应用版本、生效状态和失败原因 | 待接入 |
| 发布记录 | 查看配置版本、发布时间、发布者和影响范围 | 待接入 |
| 回滚记录 | 记录回滚请求、目标版本和设备确认结果 | 待接入 |
保存模型网关配置不会自动创建配置下发记录。
## 3. 共享资源
### 3.1 GoodBuddy 接入
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 设备列表 | 查询设备名称、平台、应用版本、登记时间和发布数量 | 部分实现 |
| 设备详情 | 查看登记信息、发布记录和来源声明 | 部分实现 |
| 连接记录 | 查看在线状态、出站控制连接和最近心跳 | 设计中 |
| 撤销记录 | 撤销设备、停止新任务和查看历史撤销原因 | 设计中 |
当前实现支持本地设备登记元数据和真实发布目录查询；生产设备认证、在线状态、出站 WebSocket 和任务控制待实现。
### 3.2 共享中心
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 能力目录 | 能力名称、版本、来源设备、发布状态和可见范围 | 部分实现 |
| 共享知识库 | 知识来源模式，以及搜索、读取原文、下载三项权限声明 | 部分实现 |
| 按成员查看 | 按成员查看可发现、可检查和可调用的资源 | 设计中 |
| 按设备查看 | 按提供设备查看已发布能力、知识和撤销记录 | 部分实现 |
当前共享中心只处理发布元数据，不提供知识正文、能力执行或真实授权。
### 3.3 数字人
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 数字人目录 | 按 `@handle`、所有者、Runtime、版本和可用范围查询 | 设计中 |
| 我的数字人 | 创建发布草稿、选择 Agent、设置开放范围、提交审批和撤销 | 设计中 |
| 调用权限 | 查看当前成员的发现、检查、调用权限和审批要求 | 设计中 |
| 发布记录 | 查看版本、状态、权限变化和撤销原因 | 设计中 |
## 4. 组织管理
### 4.1 组织与成员
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 成员 | 邀请、停用、移除和查看成员设备、授权与申请 | 设计中 |
| 用户组 | 管理成员组、设备组和组内授权范围 | 设计中 |
| 角色 | 管理组织管理员、发布者、审批人和审计员 | 设计中 |
| 服务账号 | 管理自动化调用主体、凭据、权限和有效期 | 设计中 |
### 4.2 权限策略
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 强制策略 | 组织级禁止规则、数据范围、出站地址和风险限制 | 设计中 |
| Grant | 将主体、资源、动作、有效期和预算绑定为授权 | 设计中 |
| 策略模拟 | 输入主体、资源和动作，查看命中规则与最终决策 | 设计中 |
| 变更记录 | 查看策略版本、变更者、影响范围和撤销结果 | 设计中 |
策略决策使用三种结果：自动允许、人工确认、直接拒绝。工具权限应落到具体动作，例如查询允许、修改需确认、删除拒绝。
### 4.3 审批
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 待处理 | 按调用、发布、更新和联邦申请筛选待审批项 | 设计中 |
| 已处理 | 查看批准、拒绝、过期和撤销的申请 | 设计中 |
| 我的申请 | 查看本人提交的申请和当前状态 | 设计中 |
| 审批规则 | 设置审批人、风险条件和批量审批范围 | 设计中 |
### 4.4 发布与更新
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 能力包 | 上传、验证、查看 manifest、签名、版本和兼容范围 | 设计中 |
| 发布通道 | 按设备组、组织和发布范围安排版本 | 设计中 |
| 更新策略 | 设置审批、自动更新、灰度和失败处理规则 | 设计中 |
| 撤销记录 | 紧急撤销版本、查看影响设备和后续任务处理 | 设计中 |
### 4.5 网关联邦
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 合作组织 | 查看对端地址、指纹、连接状态和有效期 | 设计中 |
| 待确认 | 创建、接受或拒绝联邦 offer | 设计中 |
| 开放范围 | 分别查看我方开放、对方开放和最终可用的资源集合 | 设计中 |
| 事件记录 | 查看建立、暂停、恢复、撤销和调用事件 | 设计中 |
## 5. 运营与审计
### 5.1 任务与中继
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 任务列表 | 按调用方、能力、提供者、路由、状态和时间查询任务 | 设计中 |
| 活动任务 | 查看排队、运行、等待确认、取消和结果未知的任务 | 设计中 |
| 中继连接 | 查看活动连接、吞吐、容量和拒绝原因 | 设计中 |
| 运行统计 | 查看延迟、失败率、取消率和提供者状态 | 设计中 |
### 5.2 审计
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 事件查询 | 按操作者、动作、对象、组织、结果、时间和关联 ID 查询 | 设计中 |
| 调用链 | 查看模型、工具、任务、路由和最终结果的父子事件 | 设计中 |
| 导出任务 | 创建、查看和下载有时效的审计导出 | 设计中 |
| 保留策略 | 设置事件、正文、工具参数和模型输出的保留范围 | 设计中 |
当前模型网关已经保存有界调用元数据。完整组织审计、调用链、导出和保留策略仍未实现。
## 6. 系统
### 6.1 系统设置
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 实例信息 | 实例名称、公开地址、协议版本和部署信息 | 设计中 |
| 身份与登录 | 本地账号、OIDC、Web 会话、CSRF 和会话撤销 | 设计中 |
| 基础设施 | 数据库、对象存储、证书、版本和服务状态 | 设计中 |
| 中继与联邦 | 中继开关、容量限制、联邦总开关和证书 | 设计中 |
| 通知 | 邮件、审批提醒、失败告警和通知渠道 | 设计中 |
| 保留与审计 | 全局保留规则、归档和审计导出限制 | 设计中 |
运行时秘密、数据库连接串、主密钥和容器挂载路径由部署环境提供，系统设置只显示状态或执行替换与测试。
## 7. 成员自助
### 7.1 我的设备与授权
| Tab | 主要功能 | 当前状态 |
| --- | --- | --- |
| 我的设备 | 管理本人设备、连接状态和设备撤销 | 设计中 |
| 我的授权 | 查看本人获得的能力、模型、工具、有效期和限制 | 设计中 |
| 我的申请 | 创建调用、发布和权限申请，查看处理结果 | 设计中 |
| 我的数字人 | 管理本人创建的数字人及其发布范围 | 设计中 |
成员的日常协作、消息、资料同步和能力调用主要在 GoodBuddy 中完成，Web 端提供授权、申请和发布管理入口。
## 当前交付边界
当前仓库可以运行的功能集中在两个页面域：
1. GoodBuddy 接入和共享中心：保存并读取本地设备登记、能力发布和知识发布元数据。
2. 模型网关：保存上游、加密凭据、模型映射和访问 Key，支持真实模型发现、请求转发、请求测试和有界调用审计。
组织认证、组织隔离、生产设备认证、设备控制连接、工具执行、任务路由、文档保存、Office 编辑、实时协作、成本控制和联邦仍属于设计或后续实现范围。接口、状态规则和验证证据分别由 [PRD](./prd.md)、[功能逻辑](./logic-design.md)、[技术设计](./technical-design.md) 和 [实施进度](./progress.md) 维护。
docs/features/share-server/logic-design.md
+32 -14
View File
@@ -12,8 +12,8 @@
## 本地目录首期状态规则
当前本地联调仅实现设备与发布元数据，使用[技术设计第 4.1 节](./technical-design.md#41-本地共享目录契约已实现)
的独立接口。下文组织身份、Grant、任务和文档归属规则属于目标设计。
本地目录实现设备与发布元数据，使用[技术设计第 4.1 节](./technical-design.md#41-本地共享目录契约已实现)
的独立接口；本地模型网关规则见第 6.1 节。下文组织身份、Grant、任务和文档归属规则属于目标设计。
Office 私有部署第一阶段的限定状态规则见第 8.2 节，不声称具备 INV-1 的组织隔离或 INV-12 的多类凭据体系。
- 注册相同设备 ID 更新名称、平台及版本，保留首次注册时间；相同内容重试不改变时间。
@@ -23,7 +23,7 @@ Office 私有部署第一阶段的限定状态规则见第 8.2 节，不声称
- 撤销将状态变为 `revoked` 并保留目录记录。重复撤销不改变结果；重试旧发布请求不恢复已撤销记录。
- 能力与知识按 `kind` 区分。知识的搜索、原文、下载标志分别存储，不相互推导；
`server` 来源也只是发布者声明，不表示文件已经上传或同步。
- 当前没有用户主体或组织所有权，因此真实目录按设备查看。按用户查看仍使用组织示例，
- 当前没有用户主体或组织所有权，因此真实目录按设备查看。组织示例已移除，
不把设备名称推定为用户身份。
## 1. 核心不变量
@@ -314,7 +314,7 @@ Publication/Grant，本人草稿确认也不能绕过当前访问权限。
共享知识区分服务器同步副本和远程设备取用。已就绪的服务器副本不因来源设备离线而失效，
但更新需等待设备连接；远程取用在设备离线时不可用。发布暂停或设备撤销仍阻止使用，不能
以已有副本绕过撤销。搜索、读取原文、下载分别判断权限；可用状态、共享对象和管理员元数据
可见性均不替代动作授权。当前共享中心只演示这些状态，无真实内容请求。
可见性均不替代动作授权。当前共享中心仅展示真实目录声明，无真实内容请求。
可用内容为来源授权、当前入口受众、动作、空间权限、组织策略及 Provider 本地权限的交集。
个人外部入口与组织空间独立授权；同一分身身份复用不复制其所有来源权限。
@@ -342,19 +342,37 @@ Publication/Grant，本人草稿确认也不能绕过当前访问权限。
任何权限扩大都从自动路径转为 `require_approval`。降级只有在目标版本仍被签名目录允许且
策略明确指定时才提供，不自动视为故障回滚。
### 6.1 网关配置演示
### 6.1 本地模型网关
模型网关负责向其他服务转发，不托管模型。原型仅在上游与映射均启用、目标组被允许时判定
模型可用；模拟调用记录允许／拒绝及路由元数据，不发送请求或记录正文。
本节描述已实现的 [B1 网关](./backend-foundation-design.md#4-b1正常模型网关接入)；完整验收尚未完成。
配置演示与上述签名能力包更新分开。草稿选择目标组可用模型，发布时重新检查策略；每组
独立记录发布历史。回退仅选择该组上一条记录，并重新检查其模型可用性，恢复版本及默认
模型后移除当前历史末项。发布和回退仅更新目标组在线示例设备；离线设备保留已应用版本，
目标版本随发布变化并显示待下发，未模拟重连交付。
模型网关向其他服务真实转发，不托管模型。新存储无上游、映射和审计。别名全局唯一并绑定
一个上游与远端模型。客户端必须提供有效 Bearer 访问 Key；列表只返回 Key 授权、上游及映射
均启用、凭据可用的模型，无需认证的上游不要求凭据。“凭据已配置”仅表示保存了密文或有效
环境引用，不表示解密或连接已验证。
这些状态仅保存在三页共享的会话内存中，刷新重置；角色开关不构成实际授权，发布状态不构成
设备确认。文档演示中仅本人可删除／转移个人文档，组织删除／恢复要求显式模拟组织文档管理员
角色，其他成员个人文档仅显示元数据，回收站不提供永久删除。
上游凭据按 `keep|replace|clear` 显式保留、替换或清除；空值不代表清除，无需认证不会自动删除
已有凭据。新秘密加密保存；主密钥缺失或错误时报告不可用，不覆盖旧密文。旧环境变量引用可
继续调用，显式替换后改为托管凭据；前缀导入界面及接口已移除。
Key 仅创建时返回原文，存储摘要；授权绑定模型记录 UUID，修改别名不改变范围。未知或撤销
Key 返回 401，未授权模型返回 403。重复撤销保持原撤销时间，撤销阻止新请求，不主动取消已开始
的流。管理与旧目录接口限制实际 socket 为直连回环，不能靠 Origin 或转发头建立管理身份。
发现模型真实访问上游列表，但不自动保存发现结果；失败仍可手工映射。用户选择或手动填写映射，
再通过本机管理测试入口显式测试。调用按配置将别名
换为远端模型，响应恢复别名，不允许请求覆盖上游地址或凭据，也不自动重试或切换上游。
调用终态为成功、失败或取消。JSON 响应通过格式检查后记录成功；SSE 必须收到 `[DONE]`，提前
结束记为失败。取消或超时中止上游请求，流已开始时的 HTTP 200 不等于最终成功。审计只记录
调用元数据，缺失用量保留未知；存储保留最新 200 条，不保存提示词、工具参数或响应正文。
配置和审计写盘成功后才更新内存，坏文件或写入失败报错，不清空已有记录。
本地预览已有 Key 级模型授权，尚无组织认证、组织隔离、用户组策略或配额。配置下发为占位，
没有发布、回退或设备确认；保存网关模型不会自动下发。接口和资源限制见技术设计第 4.2 节。
历史网关／配置演示记录保持原有证据范围，不能据此认定真实转发或交付已验证。
文档页显示待接入说明，已移除会话内存演示及模拟组织角色；文档归属与回收规则仍待服务端实现。
## 7. 联邦可见性
docs/features/share-server/prd.md
+31 -7
View File
@@ -38,9 +38,35 @@
相同记录，服务重启后记录仍保留。此阶段不自动枚举本地能力或上传知识文件。
验收要求：注册不自动发布，撤销后刷新仍为已撤销，网络失败有可重试反馈，知识权限独立保存；
真实目录与组织样例分别展示。API、状态和验证证据分别由技术设计、逻辑设计和实施进度维护。
界面只展示真实目录，空目录不填充样例。API、状态和验证证据分别由技术设计、逻辑设计和实施进度维护。
身份认证、组织授权、内容同步与远程调用仍按以下完整产品范围继续实现。
### 本地模型网关技术预览
当前实现允许在可信本地环境保存上游、模型别名，发现上游模型并发送真实测试请求。网关向
其他模型服务转发 OpenAI 兼容 Chat Completions，支持 JSON、SSE、工具调用数据和上游用量，
提供模型列表；不运行模型或工具，不支持 Responses 或 Anthropic API。
此阶段已有按模型授权的 Bearer 访问 Key，尚无组织认证、组织隔离、用户组策略或配额控制。
服务从空配置开始，持久化配置、加密上游凭据、访问 Key 摘要和最近 200 条调用元数据，不保存
提示词、响应正文或明文秘密。页面接收上游密钥，编辑时留空保留、填写覆盖；旧环境引用保留存储
兼容，前缀导入界面和接口已移除。管理限直连回环，发现模型和请求测试才访问上游。
ShareServer 可独立构建和运行，不依赖 GoodBuddy 源码；个人既有配置仅用于明确授权的环境测试。
配置下发当前为占位，保存模型不会自动配置 GoodBuddy。生产访问策略和按用户组分配仍为目标
范围。接口与限制由技术设计第 4.2 节维护，实际测试结果由实施进度维护；本节不改写历史验收证据。
### 正常模型网关接入（B1 已实现，验收部分完成）
管理员填写上游名称、协议、API 地址和 API Key，保存后发现或手动添加模型，选择对 GoodBuddy
开放的模型 ID。界面不要求用户理解环境变量前缀。ShareServer 保管上游凭据，另外签发可撤销的
网关访问 Key；GoodBuddy 使用网关地址和该 Key，通过现有模型连接入口发起实际对话。
首期完成本地网关管理、真实转发与调用记录；不依赖组织数据库或自动配置下发。只将实际支持的
Chat Completions 协议提供给客户端。当前已完成部分真实 API 验证，GoodBuddy Desktop 连接测试、
对话、完整工具往返、取消及浏览器界面仍需验收，不能用自动化或脚本调用代替。
接口与凭据设计、后续组织及知识服务顺序见[后端基础设计](./backend-foundation-design.md)。
### Office 私有部署第一阶段（待实现）
在可信私有网络内，先验证浏览器上传 DOCX、打开、编辑、保存到 ShareServer、关闭后重新打开，
@@ -77,7 +103,7 @@ JWT 用于编辑器配置和服务回调校验，不代表浏览器用户已认
- 远程管理设备桌面、任意 Shell 或任意文件系统。
- 发现未注册的局域网设备。
- 收集或分发用户个人 API Key、Cookie 和桌面登录状态。模型网关所需的组织上游凭据由管理员单独配置、服务端保管，不下发给客户端；当前原型不接收凭据。
- 自动收集或分发用户个人 API Key、Cookie 和桌面登录状态。管理员显式提供的网关上游凭据由服务端加密保管，不分发给客户端；客户端使用单独签发的访问 Key，见后端基础设计。
- 默认查看任务正文、附件和模型输出。
- 自动上传、同步或浏览数字人所有者的本地个人、项目、会话和原始 Agent 记忆；用户明确发布的知识与选定回顾按 FR-18 单独管理。
- 因为成员加入组织而自动开放其数字人、记忆、Runtime、工作区或工具。
@@ -175,11 +201,9 @@ JWT 用于编辑器配置和服务回调校验，不代表浏览器用户已认
按设备查看四个页签。内容展示发布者、提供设备、版本、在线与发布状态、共享对象；用户和
设备视图列出关联内容并可进入详情，既有设备详情提供对应共享视图入口。
当前“GoodBuddy 服务”原型提供 `/model-gateway`、`/documents`、`/distribution` 三页，覆盖
网关策略判断、文档归属与回收站、OnlyOffice 实例检查、配置发布和回退。操作仅修改会话内存，
跨页保留、刷新重置，不发送服务请求或写入本地存储；模拟角色不构成授权，模拟成功不构成
推理、转发、Office 保存或设备交付的验收。离线设备保持待下发与原已应用版本；发布和回退
都检查目标组当前可用模型，回退同时恢复版本及默认模型。细节见 UI 设计第 16.1 节。
当前“GoodBuddy 服务”提供 `/model-gateway` 本地技术预览；`/documents`、`/distribution`
及其他未实现模块显示待接入说明。网关和共享目录使用真实 API，界面已移除模拟角色、文档、
审批及配置发布操作。上述完整共享中心页签仍为目标范围。细节见 UI 设计第 16.1 节。
### FR-12 可部署性
docs/features/share-server/progress.md
+96 -2
View File
@@ -2,8 +2,102 @@
## 当前状态
ShareServer 包含控制台交互原型和可持久化的本地共享目录服务。GoodBuddy 已能注册设备、发布与
撤销元数据，Web 能查看真实目录；生产身份、组织隔离、设备控制连接、授权及任务路由仍未实现。
ShareServer 包含 Web 控制台、可持久化的本地共享目录和真实模型网关。GoodBuddy 已能注册
设备、发布与撤销元数据，Web 能查看真实目录。模型网关支持 OpenAI 兼容上游的发现、映射与
Chat Completions 转发，以及 B1 加密凭据、访问 Key 和模型授权。B1 代码已实现、验收部分完成；
生产身份、组织隔离、设备控制连接、组织授权及任务路由仍未实现。
### 2026-10-07：前端真实目录完善
- `GoodBuddy 接入` 已接入本地共享 API，显示真实登记设备、登记时间、版本和关联发布数量；支持搜索、详情和跳转到该设备的共享内容。页面明确登记记录不代表在线、所有权或身份认证。
- `共享中心` 新增真实发布记录的撤销确认和刷新流程。撤销调用 `POST /api/v1/sharing/publications/:id/revoke`，保留服务端撤销记录，不提供能力执行、知识正文读取或下载。
- 其他规划页面改为按模块展示专属待接入边界和可用入口，不显示示例数据或不会生效的创建、审批、导出和配置操作。模型网关调用元数据仍从模型网关页面查看。
- 新增共享 API 请求封装，统一错误信息和请求取消处理。前端自动化测试覆盖设备目录、待接入边界、共享筛选和撤销入口；本轮尚未进行浏览器视觉验收。
- 顶部移除“技术预览 · 非生产服务”常驻文字；侧栏按业务重排为工作台、GoodBuddy 服务、共享资源、组织管理、运营与审计、系统和成员自助。各页面内部仍保留必要的实现边界说明。
- 工作台增加服务拓扑，读取真实设备、发布记录和模型网关配置，展示 GoodBuddy 设备、ShareServer 与外部模型上游的关系及数量。空数据仅显示零接入状态，不生成示例节点；当前尚未进行浏览器视觉验收。
### 2026-10-05：B1 实现与部分验收
- 上游表单接收真实 API Key，支持保留、替换和清除；AES-256-GCM 密文随配置保存，主密钥位于
数据目录外并单独备份。旧环境变量引用继续可读、可调用，前缀导入界面与 `/import-env` 已移除。
- 客户端模型列表和聊天要求 Bearer Key，Key 原文仅创建时返回，持久化 SHA-256 摘要。
授权绑定模型记录 UUID，修改别名不改变范围；审计关联 Key ID，不将其名称当作用户身份。
管理与旧目录 API 校验实际回环 socket，并拒绝转发头；Vite `/api` 也只允许回环来源。
容器／反向代理管理尚不支持，等待 B2 登录。
- 实现轮验证记录：103 项测试通过，`npm run typecheck`、`npm run lint`、前后端构建通过。
自动化覆盖不等于 GoodBuddy Desktop 或浏览器端到端验收。
- 实现轮真实供应商验证共 5 次上游请求：1 次模型发现；1 次非流式请求使用 16 Token 上限，
输出过短，未形成有效结论；1 次 SSE 请求成功，包含 reasoning 内容和 Token 用量；1 次非流式
请求使用 1024 Token 上限并成功；1 次工具选择返回有效调用参数并在本地执行。工具结果未再次
发送给上游，因此未完成完整工具往返。
- 实际 API 验证确认重启后配置与访问 Key 保留，撤销后拒绝调用；存储含加密凭据而无明文秘密。
上述真实验证由实现轮提供，本次文档同步没有新增供应商请求或读取环境秘密。
- 浏览器已读取独立服务的网关页快照，确认空目录、访问密钥和客户端设置区域；点击被工具判定为超出视口，截图超时，未完成交互与视觉验收。独立服务已停止，默认数据未改动。
- 本轮没有验证 GoodBuddy Desktop。B1 剩余验收包括从空存储经浏览器配置、刷新
与重启，Desktop 连接测试和真实 SSE 会话，完整工具结果回传、用户停止时上游取消，以及真实
环境下超时、流中断、错误主密钥、内网 HTTP 和部署来源限制。后端基础设计第 4.5 节继续保留完整
清单；历史浏览器和旧网关结果不追溯成为 B1 验收。
- 文档同步轮重新运行 `npm test`，9 个文件、103 项测试通过；lint、含类型检查的前后端构建
通过。已阅读 deai-writing 并扫描相关文档，阻断项为 0；本次修改段落的字段枚举和验收限制
按技术含义保留，未借审校改写历史记录。`git diff --check` 通过，仅编辑 README 与文档。
以下按原日期保留历史记录，其中“当前”“本轮”均指对应日期的实现，不描述 2026-10-05 的状态。
### 2026-10-04：基于 GoodBuddy 源码的后端基础设计
- 新增[后端基础设计](./backend-foundation-design.md)，核对模型 profile、协议 URL、Main 凭据保存、
设备共享 HTTP、资源发布字段、统一知识检索入口和 Office 设计状态。按实际客户端契约安排 B1 至 B6。
- 首个实施单元为正常模型网关接入：密钥录入与服务端保存、开放模型、独立访问 Key、手工配置
GoodBuddy 和真实对话验证。自动组织模型导入、身份权限、资源绑定、知识检索及文档归属另列依赖。
- 修正功能入口、PRD、逻辑和技术文档中仍将模拟页面描述为当前实现的段落；保留历史验证记录。
新接口与凭据方案标记待实现，未把当前无认证网关描述成已有访问 Key。
- 本轮仅改 ShareServer 文档，未修改 GoodBuddy 或服务代码，未读取环境秘密、启动服务或调用模型。
相邻仓库链接目标及新增章节锚点已核对，`git diff --check` 通过。新增设计的 deai-writing 扫描
为 0 个阻断项；复核项涉及字段枚举和实施边界，按技术含义保留。未运行业务测试或进行运行时验收。
### 2026-10-02：移除界面模拟数据
- 控制台不再加载原型快照，移除虚构身份、组织、统计数量、活动以及模拟操作。
概览改为服务入口，共享中心直接读取本地目录；未接入模块保留菜单并显示待实现说明。
- 模型网关及共享目录继续使用真实 API，保留加载、空状态、失败重试和筛选。
未删除本地持久化数据，未改动 GoodBuddy 仓库。旧原型源码及接口未在本轮删除，已退出控制台路由。
- `npm test`：7 个文件、87 项测试通过；类型检查、lint 和前后端构建通过。
浏览器访问本地开发地址返回 `Request blocked`，本轮未完成视觉复查。
### 2026-10-01：本地模型网关与真实上游联调
- `/model-gateway` 改为真实 API 页面，移除网关样例上游、模型和模拟调用。新增配置持久化、
环境引用导入、模型发现、映射编辑与启停、网页请求测试及调用元数据。配置下发移除虚构模型、
用户组与设备回执，改为待接入说明；文档及其他示例模块仍保留明确的演示边界。
- API 支持模型列表、非流式 JSON 和流式 SSE 转发，透传工具调用数据和上游用量，不执行工具。
具体路径、资源限制和存储契约见[技术设计第 4.2 节](./technical-design.md#42-本地模型网关契约已实现)。
凭据只引用服务端环境变量，`scripts/dev.mjs` 支持显式 `--env-file`，加载值仅传给 API 子进程。
- 测试使用 `../goodbuddy/.env.deepseek.local`，经用户授权加载；未修改 GoodBuddy 仓库。
在独立端口 8792 和临时数据目录完成联调，保留原有 8787／5174 开发服务及项目数据。
浏览器从空目录导入配置，发现接口返回 2 个模型，包含已配置模型 `deepseek-flash`。
- 网页非流式请求返回预期内容，上游报告输入 41、输出 26 Token；另一条 SSE 请求收到 `[DONE]`
和预期内容，用量为输入 37、输出 20 Token。停用映射后请求返回 403，错误请求 ID 与审计一致，
被拒请求的未知用量未计为零。真实工具调用与 GoodBuddy 桌面端模型调用未在本轮验收。
- Playwright／Edge 验证模型发现、网页请求、停用与启用、刷新后保留配置并清除测试正文；
1440px 和 390px 的深浅主题未见横向溢出或页面脚本错误，并复核截图。重启独立 API 后，
1 个上游、1 个模型和 3 条审计与重启前一致；持久化文件不含测试凭据、提示词或响应正文。
独立测试服务已停止，测试配置未导入项目默认数据目录。
- `npm test`：7 个文件、77 项测试通过；`npm run lint`、`npm run build`（含类型检查）通过。
测试覆盖坏存储、上游错误、超限、流中断、超时、取消、审计写入失败和前端失败重试。
设计文档已按真实接口更新并使用 deai-writing 复核；历史演示验证记录保留原有时间与范围。
### 2026-10-01：本地仓库同步与开发入口
- 已逐项核对本地未提交代码和未跟踪源码：另一台机器提交的 `c9d5e63` 已包含这些功能与测试，
代码差异仅为目录迁移后的引用和构建输出路径调整；`9fa8f3e` 进一步补充 Office 私有部署设计。
- 按用户要求将本地 `main` 对齐 `origin/main` 的 `9fa8f3e`，清理旧路径重复源码，未产生合并提交。
同步后工作区干净；本地数据、依赖和忽略文件保留，GoodBuddy 仓库单独处理，本轮未操作。
- 本地开发在仓库根目录运行 `npm run dev`，入口为 `scripts/dev.mjs`，同时启动 `dev:api` 与
`dev:web`。API 使用 Node watch，前端使用 Vite 热更新；默认 Web 地址为 `http://127.0.0.1:5174`，
GoodBuddy 连接 API 地址 `http://127.0.0.1:8787`，Web 的 `/api` 请求代理到该端口。
- 首次安装依赖用 `npm ci`，终端按 `Ctrl+C` 停止开发服务。开发时先停止占用同一 API 端口或
数据目录的旧预览／容器实例；共享记录默认保存在 `data/sharing.json`。
- 本轮核对 Git 差异与启动配置，未重新启动服务或运行测试、构建。
### 2026-10-01：Office 私有部署第一阶段设计
docs/features/share-server/technical-design.md
+128 -44
View File
@@ -11,6 +11,10 @@
| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
| 共享协议 | [共享网络总体设计](../../../../goodbuddy/docs/architecture/share-network-architecture.md) |
基于 GoodBuddy 当前源码的适配依据、正常网关接入和基础服务实施顺序见
[后端基础设计](./backend-foundation-design.md)。B1 已实现、验收部分完成，B2 至 B6 待实现；第 4.1、4.2 节记录
当前已实现 API，组织与 Office 章节仍是目标设计，不代表现有菜单已有对应服务。
## 1. 仓库与运行边界
ShareServer 在独立的 `goodbuddy-shareserver` 仓库根目录维护。当前可运行结构为：
@@ -22,7 +26,7 @@ goodbuddy-shareserver/
server/
src/ # Hono API、测试与同源静态资源服务
tsconfig.json
shared/ # 原型 fixture 与类型
shared/ # 共享目录、网关 DTO 与保留的旧原型类型
web/
src/ # React Web 控制台与测试
index.html
@@ -69,9 +73,9 @@ goodbuddy-shareserver/
`npm start` 或容器启动后，Hono 同源托管 `dist/web/`。Docker 配置仍在 `docker/`，
Compose 的 `../data` 仍映射仓库根 `data/` 到容器 `/app/data`。
仓库根目录包含全控制台交互原型和本地共享目录服务。Hono 提供健康、就绪、
界面快照、原型操作确认与真实元数据 API，并同源托管 React/Vite Web 控制台；它不依赖 Electron 的
`src/shared`。本地目录使用 JSON 文件持久化，契约见第 4.1 节。当前尚未建立生产数据库、认证、设备控制连接，因此也不提前创建空的
仓库根目录包含控制台交互原型、本地共享目录和模型网关。Hono 提供健康、就绪、
界面快照、原型操作确认、真实元数据 API 和网关转发，并同源托管 React/Vite Web 控制台；它不依赖 Electron 的
`src/shared`。本地目录与网关使用独立 JSON 文件持久化，契约见第 4.1、4.2 节。当前尚未建立生产数据库、组织认证、设备控制连接，因此也不提前创建空的
`packages/share-protocol`。进入真实 Desktop 协议实现时，服务端和 Desktop 共同依赖
独立发布的 `share-protocol` 协议包，具体归属在真实协议实现时确定；
ShareServer 仍不得导入 Electron 的 `src/shared`，也不得依赖相邻桌面仓库构建。
@@ -79,9 +83,9 @@ ShareServer 仍不得导入 Electron 的 `src/shared`，也不得依赖相邻桌
## 2. 技术选型约束
本节及下文组织身份、数据库事务、Web session 安全与生产部署要求属于完整组织服务目标。
本地目录按第 4.1 节实现；Office 私有部署第一阶段按第 10.1 节单独推进，不以前述能力为前置条件。
本地目录和网关按第 4.1、4.2 节实现；Office 私有部署第一阶段按第 10.1 节单独推进，不以前述能力为前置条件。
- 使用与仓库一致的 TypeScript/Node.js 工具链，具体 HTTP 框架在实现前根据维护性选择。
- 使用与仓库一致的 TypeScript/Node.js 工具链，沿用当前 Hono 框架。
- PostgreSQL 是组织、策略、任务元数据和审计的权威数据库；工作空间消息、处理状态及可靠投递记录
也以数据库为准，具体业务表与受控正文存储在协作模块实现时增加。
- 完整组织服务计划使用 S3 兼容对象存储保存 Package、可选中继暂存和 Office 工作副本。
@@ -135,7 +139,7 @@ audience，并绑定单个 `DocumentEditSession`。
### 4.1 本地共享目录契约（已实现）
此接口供同机 GoodBuddy 与 Web Demo 联调，默认监听 `127.0.0.1:8787`。没有登录、组织隔离
或设备认证；可访问接口的客户端均可修改目录。设备 ID 仅标识记录，客户端只显示本机撤销按钮
或设备认证；B1 起只允许直连回环管理请求，符合此限制的客户端均可修改目录。设备 ID 仅标识记录，客户端只显示本机撤销按钮
不构成服务端所有权校验。`productionReady` 保持 `false`。上文 audience、组织授权及 WebSocket
规则是后续组织服务目标，不由这些本地接口实现。
@@ -171,9 +175,110 @@ GoodBuddy 通过 `页面 → preload → 可信 IPC → Main HTTP 服务` 调用
服务地址与设备名称，并设置请求超时。Web 同源读取目录，不保存桌面设备凭据。
两仓独立构建；桌面实现与验证见[设备共享文档](../../../../goodbuddy/docs/features/device-sharing/README.md)。
### 4.2 本地模型网关契约（已实现）
实现位于 `server/src/gateway-routes.ts`、`gateway-store.ts` 和 `shared/gateway.ts`，挂载到
`/api/v1/gateway`。B1 已实现本机管理、托管凭据和按模型授权的 Bearer 访问 Key，没有组织隔离、
用户组策略、配额或速率／并发控制。客户端 Key 不转发给上游。就绪接口报告网关边界，保持
`productionReady=false`、`storageChecked=false`。网关独立构建运行，不导入 GoodBuddy 源码。
下表路径均相对于 `/api/v1/gateway`，成功返回 200：
| 方法与路径 | 输入与行为 | 响应 |
| --- | --- | --- |
| `GET /config` | 读取配置、调用元数据和部署指定地址 | `{upstreams,models,audits,gatewayBaseUrl}` |
| `POST /upstreams`、`PUT /upstreams/:id` | `name,baseUrl,protocol,authentication,enabled,credentialAction`；仅 `replace` 带 `apiKey` | 上游公开字段及 `credentialConfigured`，无秘密或密文 |
| `POST /models`、`PUT /models/:id` | `alias,upstreamId,remoteModel,enabled`，可选 `displayName` | 模型映射 |
| `GET /access-keys` | 列出 Key 元数据 | `{accessKeys}`，不含摘要或原文 |
| `POST /access-keys` | `{name,modelIds}`，至少一个不重复的模型记录 ID | `{accessKey,key}`，完整 Key 仅此次返回 |
| `POST /access-keys/:id/revoke` | 撤销 Key | Key 元数据，重复撤销保留原 `revokedAt` |
| `POST /upstreams/:id/discover` | 无请求体；向已启用上游的 `/models` 发 GET | 去重模型 ID 列表 `{models: string[]}`，不自动保存映射 |
| `POST /test` | 本机管理测试，使用 Chat 字段，仅非流式 | 真实 JSON 响应，复用转发和审计，`accessKeyId=null` |
| `GET /v1/models` | Bearer Key；仅列授权、启用且上游启用、凭据可用的模型 | OpenAI 模型列表，模型 ID 为别名 |
| `POST /v1/chat/completions` | Bearer Key 与模型授权；按别名转发 | JSON 或 SSE，响应 `model` 改回别名 |
除两个 `/v1` 客户端端点外，网关管理和旧共享目录 API 均通过 `admin-boundary.ts` 校验实际
`incoming.socket.remoteAddress`，只接受 `::1`、`127.*` IPv4 及其 IPv4-mapped 地址；没有 socket
信息也拒绝。含 `Forwarded`、`X-Forwarded-*` 或 `X-Real-IP` 的管理请求返回 403，不采信其来源声明。
Origin 允许无值、同源、`http://127.0.0.1:5174` 和 `http://localhost:5174`；来源不符同样拒绝。
Vite 在代理前对所有 `/api` 请求检查原始 socket，仅限回环。容器和任意反向代理管理不受支持，
须等待 B2 登录；无转发头的本机代理不能被当作管理员身份。健康与就绪 GET 不受管理限制。
Key 使用 `ss_` 加 32 个随机字节的 base64url 编码，存储 SHA-256 摘要。`modelIds` 绑定映射
记录的 UUID，修改别名不改变授权。Key 名称不代表用户身份；缺失、格式错误、未知或已撤销的 Key
返回 401，未授权或不存在的请求模型返回 403。撤销阻止后续请求，不主动终止已经开始的流。
客户端 Base URL 为 `http://127.0.0.1:8787/api/v1/gateway/v1`。仅支持上述模型列表与 Chat
Completions，不实现 Responses、Anthropic 或其他推理端点，不执行工具。Chat 顶层字段采用
`CHAT_FIELDS` 白名单，包含消息、流式选项、采样参数、`tools/tool_choice/parallel_tool_calls`、
兼容的 `functions/function_call`、`response_format`、`reasoning_effort` 等；未知字段及地址／凭据
覆盖报错。消息角色允许 `system/developer/user/assistant/tool/function`；具体参数语义由上游处理，
不保证每个上游支持全部字段。工具调用数据和 usage 随响应透传。
配置输入严格匹配字段。名称、显示名和远端模型名最多 200 字符，新建或改名的别名最多 128 字符；
已有最长 200 字符的别名可继续使用和原名编辑，接入 GoodBuddy 前需显式改为其支持的长度。
别名以 ASCII 字母或数字开头，其余可含字母、数字、点、下划线、冒号、斜杠和连字符。
上游、模型记录和 Key ID 为服务端生成的 UUID v4。Base URL 最多 2048 字符，允许 HTTP/HTTPS
及合法路径，去掉尾斜杠，禁止用户信息、查询和片段；请求不跟随重定向。支持可信内网 HTTP
上游，但 HTTP 不加密传输凭据，对外部署使用 HTTPS；该校验不构成生产出站访问策略。
`protocol` 仅支持 `openai-chat-completions`，`authentication=api-key|none`。
`credentialAction=keep|replace|clear` 显式保留、替换或清除凭据；空输入不代表清除，选择 `none`
不自动删除已有凭据。替换时 `apiKey` 最多 16384 字符，使用 AES-256-GCM、随机 nonce、认证标签，
并以稳定上游 ID 作为 AAD；密文随上游一起原子保存。`credentialConfigured` 只反映密文或有效
环境引用是否存在，不保证解密或连接成功。
`SHARESERVER_MASTER_KEY_FILE` 指向数据目录外的秘密文件，也可用 `SHARESERVER_MASTER_KEY`
提供 64 位十六进制主密钥，两者不能同时设置。文件路径及真实路径均须在数据目录外。
初始化命令为 `npm run gateway:init-key -- <文件路径>`，父目录须已存在，拒绝覆盖已有文件；
Windows 可运行示例见根 README。主密钥与普通数据分开备份；缺失、错误或无法解密时返回
`CREDENTIAL_UNAVAILABLE`，不重新生成或覆盖。替换任一凭据前先检查既有密文能否解密。
旧版本 `apiKeyEnv` 记录仍可读取并在调用时解析 API 环境，显式替换／清除后移除引用；
新表单及 API 不接受变量名，`/import-env` 已移除。环境文件仅供旧引用及授权开发测试加载：
```text
npm run dev -- --env-file=../goodbuddy/.env.deepseek.local
```
`scripts/dev.mjs` 用 `parseEnv` 加载指定文件，仅将文件中的变量传给 API 子进程，Vite 不接收
这份加载结果，仅接收派生的 `SHARESERVER_API_PORT` 以同步代理目标；已有进程环境优先。
环境变更需重启 API。该路径仅是可选的授权测试输入，
不构成 GoodBuddy 依赖，不自动读取或迁移个人配置；使用既有个人配置须有明确的环境测试授权。
`SHARESERVER_GATEWAY_BASE_URL` 设置完整客户端 Base URL，`/config` 将其返回为 `gatewayBaseUrl`；
未配置时返回 `null`，界面提示配置，不从请求 Host 或 Vite 地址推断。自定义端口或异机访问须
设置客户端可达的地址并保留 `/api/v1/gateway/v1`。
请求体要求 JSON，读取上限为 1 MiB；上游 JSON 响应、发现结果及 SSE 总字节上限为 16 MiB。
SSE 单事件及未分帧缓冲的字符串长度上限为 1,048,576 个 JavaScript UTF-16 码元，不能视为
1 MiB 字节上限。默认超时 120 秒，聊天从读取入站请求到完成流共用该期限；取消会中止上游。
SSE 必须有 `[DONE]`，中途 EOF 记 `INCOMPLETE_STREAM`；聊天 JSON 结果／SSE JSON 数据事件须有
`choices` 数组且无 `error`。流已发出后，失败通过错误事件或流中断报告，HTTP 200 不代表调用成功。
错误包为 `{error:{code,message},requestId}`，不回传上游错误正文。输入无效 400，Key 无效 401，停用、未授权模型或 Origin
拒绝 403，不存在 404，别名冲突 409，请求超限 413，非 JSON 415，上游故障或响应无效 502，
缺凭据／存储故障 503，超时 504。聊天审计的取消状态记 499；这不是承诺客户端能收到的 HTTP 状态。
管理请求按上述 socket 和 Origin 规则校验；聊天端点也检查 Origin。未识别路径在通过管理边界后返回 JSON 404。
存储默认 `data/gateway.json`，跟随 `SHARESERVER_DATA_DIR`。文件缺失时从空上游、映射和审计
开始，首次写入创建文件，无预置服务或调用；每个数据目录只允许单进程中的一个 GatewayStore。
写入排队，经临时文件、文件同步和 rename 后更新内存；坏文件返回存储错误，不自动重置。
配置无删除 API，可编辑或停用；当前不提供配置修订冲突控制或 PostgreSQL 迁移。
存储版本 2 包含上游密文、映射、Key 摘要及元数据与最新写入的 200 条聊天终态审计；版本 1
可读取并在下次写入时保存为版本 2，保留原 ID 和旧环境引用。审计新记录在前，仅含 ID、时间、
已识别模型别名、上游 ID、访问 Key ID、是否流式、成功／失败／取消、HTTP 状态、耗时、输入／输出 Token 和
稳定错误码；未识别别名不保存用户原始值。用量只取上游有效非负整数，缺失为 `null`，不估算为零。
审计不保存提示词、工具参数、响应正文或凭据；配置变更与模型发现不生成聊天审计，不具备完整管理审计。
写入失败不能据此确认审计已保存，流中已发送的数据也不能撤回。
本节按当前源码描述契约。`gateway.test.ts` 中的测试用例不等同于本次运行证据，实测结果与日期
由 `progress.md` 维护；历史模拟网关的通过记录不追溯作为真实转发验收。
## 5. 数据模型
下列数据库模型属于组织服务目标设计。本地目录首期使用第 4.1 节的文件存储，不将本地设备 ID 当作组织身份。
下列数据库模型属于组织服务目标设计。本地目录和网关使用第 4.1、4.2 节的文件存储，不将本地设备 ID 当作组织身份。
核心表建议为：
@@ -287,7 +392,7 @@ Release catalog 使用独立签名域。服务器不能重打包已签名 payloa
### 10.1 私有部署第一阶段（待实现）
本节是首期容器、配置、接口和持久化的权威设计，范围以 PRD 第 3 节为准。当前 `/documents`
仍为演示，仓库只有 ShareServer 的 `docker/compose.yaml`，没有 Office overlay 或真实编辑链路。
显示待接入说明，仓库只有 ShareServer 的 `docker/compose.yaml`，没有 Office overlay 或真实编辑链路。
第一阶段采用单个 ShareServer 进程、独立 Document Server 和本地文件系统，不新增身份源、数据库、
S3/MinIO、独立 callback worker 或启动 code／安全 Cookie 交换。仅适用于可信私有网络；当前无认证，
可访问服务者可操作试验文档，随机文档 ID 和 JWT 均不能据此宣称用户授权或组织隔离。
@@ -523,46 +628,25 @@ Office 第一阶段配置与独立往返验收见第 10.1 节；后续组织部
设计完成不代表服务已实现；只有独立部署和真实 Desktop 端到端路径通过后才能更新实施状态。
## 16. 当前原型实现
## 16. 当前控制台实现
2026-09-05 建立的交互原型固定以下技术基线：
Hono 与 `@hono/node-server` 提供 API 和构建后的同源 Web 托管。Web 沿用 React、Vite、
TypeScript、Tailwind CSS 和 Radix。部署已有非 root 多阶段 Docker 镜像。
- API：Hono + `@hono/node-server`，保留 `/api/v1/public/*` 与
`/api/v1/web/*` audience 路径。
- Web：React、Vite、TypeScript、Tailwind CSS 和 Radix primitives，按 shadcn/ui 组件模式
维护本地可修改组件。
- 路由与范围：管理员和成员自助使用不同可见导航；当前组织持续显示。
- 部署：生产构建由同源 Hono 服务托管，并提供非 root 多阶段 Docker 镜像。
`web/src/App.tsx` 不再请求原型快照，不显示虚构身份或角色切换。概览显示服务入口，
`/capabilities` 通过 `sharing-center.tsx` 与 `local-sharing.tsx` 读取真实设备和发布记录；
来源与知识权限只是声明，不代表正文、检索或调用已可用。
`/api/v1/public/ready` 返回 `mode=interactive-prototype` 和
`productionReady=false`。原型 fixture、角色切换和操作确认只用于评审信息架构，不得被
Desktop 或部署脚本当作真实身份、策略、任务或审计 API。组织生产实施须从 FR-1
初始化、本地身份、PostgreSQL 组织作用域和事务审计开始；第 10.1 节私有 Office 试验可独立推进，
使用真实文件和独立元数据，不在 fixture 上叠加权威状态。
当前 `/documents` 已有 OnlyOffice 实例配置与预设检查模拟；Office 会话 API、对象存储、
ONLYOFFICE 编辑、callback、文档保存和 Desktop 文档 Tab 集成仍未实现。
`/model-gateway` 的 `gateway-page.tsx` 使用第 4.2 节真实 API 保存配置、发现模型、发起非流式
测试和读取审计；测试正文仅在组件内存，卸载取消在途请求。`/distribution` 只显示待接入说明
与网关链接。文档和其他未实现模块显示待接入状态，没有示例列表或模拟操作。
`web/src/app-config.ts` 将 `/model-gateway`、`/documents`、`/distribution` 放入管理员的
“GoodBuddy 服务”分组。`web/src/components/services-demo.tsx` 使用 `ServicesDemo` 的 React
Context 与 `useState` 共享演示状态，跨路由导航保留、刷新重置。服务演示操作不使用 Hono
操作确认 API、不发网络请求、不写本地存储，也不保存凭据；页面角色与权限判断均为内存模拟。
控制台启动仍通过既有快照 API 加载示例数据，此边界仅指三个服务页的模拟操作。
服务端仍保留旧 `/api/v1/web/prototype/*` 接口及 fixture，但它们已退出控制台调用路径，不能
作为组织业务 API。`/api/v1/public/ready` 仍报告 `mode=interactive-prototype`、
`productionReady=false` 和存储未检查。历史模拟测试不作为真实业务验收。
模型网关只模拟上游／映射启用与用户组策略判断及最近 50 条有界调用审计；产品职责是转发
其他模型服务，不托管模型或执行推理。文档仅保存示例名称、归属及回收站标记；转移清除个人
删除权，组织删除／恢复依赖显式模拟角色，恢复保留归属。OnlyOffice 检查使用预设结果。
配置演示保存单个草稿和按组发布历史，发布与回退均重新检查模型可用性；回退取上一条记录并
移除当前末项，恢复版本及默认模型。仅目标组在线示例设备更新 `applied`，离线设备保持原值与
待下发状态。这里没有设备连接、重连投递或持久化版本记录，不能作为真实配置交付证据。
共享中心原型由 `web/src/components/sharing-center.tsx` 和 `web/src/lib/sharing-fixtures.ts` 提供。
条目使用现有快照中的成员、设备 ID 建立关联，本地 fixture 仅含元数据和显式权限标记。
既有 `/capabilities` 路由不变；查询参数 `view=catalog|knowledge|users|devices` 选择页签，
`user`／`device` 定位主体，`item` 打开详情，`q`、`status=ready|unavailable`、
`source=synced|remote`、`audience` 保存筛选。刷新恢复 URL 状态；内容链接保留筛选，
跨主体链接清除旧条件，无效条目链接显示可关闭的错误详情。除启动快照外不新增 API 请求，
不保存正文、不模拟下载；真实授权和同步仍属后续实现。
B1 正常网关接入代码已实现，真实验收部分完成，范围见实施进度。组织服务需补身份、PostgreSQL 与授权；Office 私有
试验可按第 10.1 节独立推进。保存网关模型不会自动下发给 GoodBuddy，配置交付仍未实现。
## 17. 工作空间协作的待实现契约
docs/features/share-server/ui-design.md
+80 -24
View File
@@ -16,8 +16,14 @@ ShareServer 是独立 Web 产品，不直接复用 Electron 页面壳层实现
## 1. 使用对象
当前本地首期在 `/capabilities?view=local` 提供“本地服务目录”页签，读取真实设备和发布数据。
其余四个共享中心页签保留组织演示。真实页不使用示例组织、用户归属或在线状态解释本地记录。
当前控制台移除模拟数据与操作。`/capabilities` 直接读取本地服务的设备和发布数据，原
`/capabilities?view=local` 地址仍可访问。共享中心不再提供组织示例页签，不使用示例组织、
用户归属或在线状态解释本地记录。
概览只提供已接入服务的入口，不显示预设指标和活动。导航保留规划模块；未接入的页面显示
待实现说明，不提供虚假的保存、审批或健康检查。模型网关、共享目录分别加载自己的 API，
控制台不再依赖原型快照。移除预设身份、组织切换、角色切换、通知数量和未实现的全局搜索。
下文中的组织身份、文档协作及其他管理流程属于目标设计，尚未实现的部分不作为当前可用功能展示。
GoodBuddy 从应用菜单或应用中心进入“设备共享”，完成地址与名称保存、注册、发布、撤销和刷新。
Web 提供设备、类型、状态、关键词筛选，显示注册时间、来源声明及独立知识权限；提供加载、空目录、
@@ -56,6 +62,34 @@ GoodBuddy 接入
当前组织始终显示。切换组织会重新加载整个数据范围，不保留上一组织的选择、筛选或详情。
系统管理使用“实例范围”标识，不能伪装成某个组织。
### 2.1 页面 Tab 结构
每个管理页面围绕一个业务对象组织，页面内通过 Tab 切换查看范围或操作阶段。列表、详情和
编辑表单属于当前 Tab 的交互，不单独增加一级导航。未接入的页面保留 Tab 结构，但每个 Tab
只显示对应的待接入说明，不生成示例数据。
| 页面 | Tab |
| --- | --- |
| 运行概览 | 服务状态、待处理事项、最近活动 |
| 模型网关 | 概览、上游服务、模型目录、访问密钥、请求测试、调用审计、客户端接入 |
| 文档与协作 | 文档库、编辑会话、Office 服务、保存记录 |
| 配置下发 | 配置草稿、设备生效、发布记录、回滚记录 |
| GoodBuddy 接入 | 设备列表、设备详情、连接记录、撤销记录 |
| 共享中心 | 能力目录、共享知识库、按成员查看、按设备查看 |
| 数字人 | 数字人目录、我的数字人、调用权限、发布记录 |
| 组织与成员 | 成员、用户组、角色、服务账号 |
| 权限策略 | 强制策略、Grant、策略模拟、变更记录 |
| 审批 | 待处理、已处理、我的申请、审批规则 |
| 发布与更新 | 能力包、发布通道、更新策略、撤销记录 |
| 网关联邦 | 合作组织、待确认、开放范围、事件记录 |
| 任务与中继 | 任务列表、活动任务、中继连接、运行统计 |
| 审计 | 事件查询、调用链、导出任务、保留策略 |
| 系统设置 | 实例信息、身份与登录、基础设施、中继与联邦、通知、保留与审计 |
| 我的设备与授权 | 我的设备、我的授权、我的申请、我的数字人 |
Tab 的状态和功能范围以[产品功能列表](./feature-list.md)为准。当前原型已经为组织与成员
提供通用 Tab 组件；模型网关使用独立的真实 API 页面，其余尚未接入服务的页面显示占位说明。
## 3. 概览
概览只显示需要行动和运行事实：
@@ -192,7 +226,7 @@ GPU-Worker-02 AI Team Linux 离线 8 2 小时前
## 13. Office 编辑目标设计
Office 编辑管理归入“文档与协作”，属于系统管理员的服务配置和组织管理员的策略管理，不提供
文档正文浏览器。以下是生产目标，当前实例配置与预设检查演示见第 16.1 节。
文档正文浏览器。以下是生产目标，当前待接入页面见第 16.1 节。
日常文档操作在 GoodBuddy 中完成。文档以 ShareServer 为主存储；显式选择本地来源导入／回写
时，另行显示检查点与源文件回写状态。关闭会话不表示删除主文档，检查点可用不表示本地源文件已保存。
@@ -217,7 +251,7 @@ Office 编辑管理归入“文档与协作”，属于系统管理员的服务
### 13.1 私有部署第一阶段入口（待实现）
在 `/documents` 提供明确区分于现有演示的“私有文档试验”入口，展示无用户授权的使用范围。
后续在 `/documents` 提供“私有文档试验”入口，展示无用户授权的使用范围。
提供 DOCX 上传、真实文档列表、打开编辑器、保存状态与关闭后重新打开；不使用模拟个人／组织
归属或角色开关解释真实文件。列表显示名称、大小、最近持久化版本与保存时间，不显示服务器路径。
@@ -250,34 +284,56 @@ Office 编辑管理归入“文档与协作”，属于系统管理员的服务
shadcn/ui 的本地组件模式和 Radix 可访问 primitives，布局参考成熟后台的侧栏、顶栏、数据
表格和详情对话框，但不复制第三方示例业务页面。
原型已覆盖数字人需求加入前的一级栏目、管理员与成员自助视图切换、组织范围、搜索筛选、
页签、详情、创建表单、危险确认和 390px 窄屏导航。动态发光、网格和网络脉冲只用于运行状态
与品牌氛围；业务表格仍保持克制，状态继续同时使用图标与文字。既有 fixture 页面操作会调用无持久化确认
API，并持续标明不会写入生产数据，不能据此宣称真实审批、撤销、策略或任务操作已实现。
早期原型覆盖一级栏目、角色切换、搜索筛选、详情、创建表单与窄屏导航。
2026-10-02 起，控制台移除示例业务页面及其操作入口，保留侧栏、主题和窄屏导航。
`FR-13` 新增的数字人目录、“我的数字人”和 `@` 选择器尚未进入当前原型。
“文档与协作”已提供 OnlyOffice 实例配置和预设健康检查模拟；真实 Office 编辑与会话管理尚未实现。
“文档与协作”显示待接入状态；Office 编辑与会话管理尚未实现。
### 16.1 GoodBuddy 服务演示
### 16.1 GoodBuddy 服务入口
侧栏“GoodBuddy 服务”分组提供三个管理员路由。页首持续标注模拟边界：三页共享当前会话
内存，导航保留状态、刷新重置；操作不调用网络或写本地存储。角色选择仅用于评审，不构成
真实授权；未接入模型推理、网关转发、OnlyOffice 编辑保存或设备交付。
本节记录已实现的 [B1 网关界面](./backend-foundation-design.md#4-b1正常模型网关接入)，本轮未完成浏览器验收。
工作台顶部显示服务拓扑，按真实 API 汇总已登记 GoodBuddy 设备、ShareServer 发布目录和模型网关上游。拓扑表达服务职责和配置关系，登记设备不显示为在线，发布目录不显示为可执行内容；没有数据时显示零接入状态。
页面按 Tab 组织为“概览”“上游服务”“模型目录”“访问密钥”“请求测试”“调用审计”“客户端接入”。概览只展示网关地址、资源数量和最近状态；
上游服务管理外部连接，模型目录管理客户端可见的映射，访问密钥管理客户端授权，请求测试验证真实转发，调用审计查看有界元数据，客户端接入展示
GoodBuddy 所需的地址和模型配置。不同 Tab 不混合配置表单、运行结果和审计记录。上游表单输入 API 地址和密钥，移除前缀与变量名；
接入区展示完整 Base URL、协议、模型 ID，并支持创建与撤销访问 Key。凭据只显示配置状态，
编辑上游时，凭据输入框留空表示保留当前值，填写新值表示覆盖；页面不要求用户选择额外的凭据操作。新建访问 Key 仅当次显示完整值，离开后只保留名称及状态。
获取模型失败仍可手动添加，空状态引导接入，不填示例。访问 Key 的授权绑定模型记录 ID，修改别名不改变授权。
侧栏按业务流程分为“工作台”“GoodBuddy 服务”“共享资源”“组织管理”“运营与审计”“系统”和“成员自助”。
其中“GoodBuddy 服务”分组保留模型网关、文档与协作、配置下发三个管理路由；“共享资源”集中设备接入和共享中心。
各页分别说明实现范围。网关是无组织认证、
组织隔离和配额的本地技术预览，已实现客户端 Key 认证及模型授权；文档与配置下发显示待接入说明。
| 路由 | 交互与结果 |
| --- | --- |
| `/model-gateway` 模型网关 | “上游服务”“模型映射 / 访问策略”“调用审计”页签；可添加和启停上游，切换映射上游、允许组及启停状态，选择调用组模拟允许／拒绝。最近 50 条审计仅含路由与策略结果，可查看详情，不含请求／响应正文 |
| `/documents` 文档与协作 | “组织文档”“归属元数据”“OnlyOffice 服务器”“回收站”页签；展示名称与归属，无个人正文预览。OnlyOffice 可添加实例、预设健康／失败并累计模拟检查次数，不访问实例或建立编辑会话 |
| `/distribution` 配置下发 | 创建一个配置草稿，选择目标组、当前可用默认模型和三段数字版本；发布前再次检查模型与组策略。按组展示当前／上一版本、设备已应用／目标版本，并可回退到上一条发布记录 |
| `/model-gateway` 模型网关 | 按“概览／上游服务／模型目录／访问密钥／请求测试／调用审计／客户端接入”组织；配置保存到服务器，可添加、编辑、启停上游与映射，发现模型、创建和撤销访问 Key、测试及刷新审计，无用户组策略控件 |
| `/documents` 文档与协作 | 显示尚未接入服务，无示例文档、实例或操作按钮 |
| `/distribution` 配置下发 | 显示“尚无配置下发服务”及模型网关链接；无草稿、设备生效回执或发布回滚记录，保存网关模型不会自动下发到 GoodBuddy |
“打开模拟 GoodBuddy 客户端”仅打开对话框，个人创建者可删除自己的示例文档或确认转移给
当前组织，不启动真实客户端或上传文件。转移后从个人列表移除，原个人删除权失效；显式
勾选模拟“组织文档管理员”才可删除／恢复组织文档。其他成员个人文档不可操作，恢复保留
原归属，演示不提供永久删除。
网关初始展示空上游、空映射、空访问 Key 与空审计。上游表单填写名称、Base URL、协议、认证
方式和启用状态；API Key 留空时保留已有凭据，填写真实 API Key 时覆盖旧值，提交后清空密钥输入。保存失败保留
普通字段，密钥重试需重新输入。编辑默认保留；无需认证不会自动清除已有凭据。界面仅显示
凭据配置状态，不返回旧值或密文。旧环境引用保留存储兼容，当前界面没有导入入口。
配置发布与回退仅更新目标组在线示例设备；离线设备保持原已应用版本并标记待下发，无重连
交付模拟。回退同时恢复版本和默认模型；历史模型停用或当前组策略不允许时禁止回退，不能
仅改版本标签。上游及 OnlyOffice 地址表单只接受不含账号、密码、查询参数或片段的 HTTPS
地址，不提供密钥字段，也不验证连接。
“发现模型”访问真实上游并列出结果，选择结果打开映射表单，也可手动填写。测试只列出上游、
映射均启用且无需认证或已配置凭据的别名，用户填写提示词后通过本机管理 `/test` 发送非流式请求；发送前提示数据去向及
可能费用。测试支持取消、清除结果，提示词与结果仅在组件内存中，离开页面清除。页面显示客户端
Base URL 来自 `SHARESERVER_GATEWAY_BASE_URL`，本机示例为 `http://127.0.0.1:8787/api/v1/gateway/v1`；
未配置时提示管理员设置，不从 Vite 端口或浏览器 Host 推断。客户端使用访问 Key，不使用上游 API Key。
配置加载失败可重试；已有快照时保留并标注上次数据。保存失败保留普通字段，错误显示 HTTP
状态、错误码及请求 ID。取消测试后提示审计可能稍后更新。审计显示服务器保留的最新 200 条
调用元数据：时间、编号、模型、上游、访问 Key ID、流式方式、结果、HTTP 状态、耗时、Token 用量与错误码；
不展示正文，缺失用量显示“未知”。窄屏审计表可横向滚动。
文档页已移除“打开模拟 GoodBuddy 客户端”、示例文档、模拟角色和回收操作；归属操作待后端实现。
网关上游接受 HTTP/HTTPS，包括可信内网 HTTP，不允许账号、密码、查询参数或片段；保存不验证连接，
发现与测试才发真实请求。OnlyOffice 实例表单与预设检查已退出当前界面。
管理 API 与 Vite `/api` 均限制实际 socket 来源为回环；容器／反向代理管理待 B2 登录后支持。
既有网关策略与配置发布演示记录属于历史交互证据，不作为当前真实网关或设备交付的测试结论。
## 17. Desktop 工作空间协作目标交互