chore: extract ShareServer into its own repository
Move the existing Hono API, React console, tests, build configuration, and feature documentation from GoodBuddy into a standalone project. Keep the current interactive-prototype behavior and production limitations. Document the source commit and sibling-checkout links to the authoritative Desktop network architecture. Independent install, tests, typecheck, lint, build, and built-service HTTP smoke checks passed.
This commit is contained in:
lofyer
@@ -0,0 +1,33 @@
|
||||
# ShareServer
|
||||
|
||||
ShareServer 是 GoodBuddy 设备共享网络的独立 Web 服务。它为一个或多个组织提供身份与设备
|
||||
目录、能力发布、授权策略、任务路由、可选数据中继、能力包更新、网关联邦和审计管理。
|
||||
|
||||
ShareServer 不属于 Electron Main，不负责桌面端局域网发现，也不自动取得设备上的能力、
|
||||
文件、凭据或 SSH Host。
|
||||
|
||||
## 文档导航
|
||||
|
||||
| 文档 | 权威职责 |
|
||||
| --- | --- |
|
||||
| [PRD](./prd.md) | 管理角色、产品范围、功能需求和验收 |
|
||||
| [功能逻辑](./logic-design.md) | 组织隔离、设备、发布、策略、任务和联邦状态规则 |
|
||||
| [管理界面设计](./ui-design.md) | ShareServer Web 控制台的信息架构与交互 |
|
||||
| [技术设计](./technical-design.md) | 服务模块、API、数据、部署、运维和验证 |
|
||||
| [实施进度](./progress.md) | 已验证实现、剩余生产工作与验证证据 |
|
||||
| [共享网络总体设计](../../../../goodbuddy/docs/architecture/share-network-architecture.md) | 跨端身份、能力、授权、任务、更新和协议权威（GoodBuddy 仓库） |
|
||||
|
||||
当前没有单独的 User Stories：管理员、能力发布者、审计员和普通成员场景已进入 PRD 与逻辑
|
||||
设计。仓库已建立可运行的全控制台交互原型；它用于确认信息架构与交互，不代表生产服务已经
|
||||
实现。当前边界和运行方法见[实施进度](./progress.md)与
|
||||
[`README.md`](../../../README.md)。跨仓库文档链接要求将 `goodbuddy` 与
|
||||
`goodbuddy-shareserver` 克隆到同一级目录；服务构建和运行不依赖桌面端仓库。
|
||||
|
||||
## 角色
|
||||
|
||||
- **系统管理员**：维护实例、身份源、域名、证书、存储和全局限制。
|
||||
- **组织管理员**：管理本组织成员、设备、组、策略、能力和联邦关系。
|
||||
- **能力发布者**：在获准范围内发布设备能力或签名能力包。
|
||||
- **审批人**：处理调用、发布、更新和联邦申请。
|
||||
- **审计员**：只读查看和导出获准范围内的审计事件。
|
||||
- **成员**：主要通过 GoodBuddy Desktop 使用能力，只在 Web 端处理个人设备和审批。
|
||||
@@ -0,0 +1,219 @@
|
||||
# ShareServer 功能逻辑设计
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 设计中 |
|
||||
| 版本 | 0.2 |
|
||||
| 日期 | 2026-09-05 |
|
||||
| 关联 PRD | [ShareServer PRD](./prd.md) |
|
||||
| 共享规则 | [共享网络总体设计](../../../../goodbuddy/docs/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 初始化入口一次性关闭
|
||||
|
||||
初始化只在实例尚无系统管理员时可用。首个系统管理员创建成功后，后续请求即使持有旧的
|
||||
一次性引导材料也不能再次进入初始化流程。
|
||||
|
||||
### INV-10 数字人发布不等于记忆公开
|
||||
|
||||
发布数字人只建立一个有界 Agent Publication。它默认不取得所有者任何本地记忆；所有者可以
|
||||
在发布时勾选 Agent、Global、指定 Project 和指定 Automation 分区，不能开放 Conversation
|
||||
和 Run 分区。ShareServer 和调用者只能看到允许分区种类与“本次调用会使用本地记忆”的政策
|
||||
事实，不能读取原始条目、分区内容、来源正文或检索结果。新增可读分区按权限扩大重新审批，
|
||||
移除分区可以立即收紧。
|
||||
|
||||
## 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` | 短期权威恢复规则和逻辑完整性；部署结构由技术设计定义 |
|
||||
| `FR-13` | 注册、Publication、目录与授权不变量，provider 冻结及 `INV-10` |
|
||||
|
||||
## 10. 逻辑完整性
|
||||
|
||||
本设计覆盖实例、组织、成员、设备、能力与数字人发布、授权、审批、任务、更新、联邦、撤销
|
||||
和恢复。实现前仍需确定首个 OIDC 提供者矩阵、默认审计保留期、部署规模目标和中继带宽上限；这些部署
|
||||
参数应可配置，不改变拒绝优先、双边联邦和 provider 冻结规则。
|
||||
@@ -0,0 +1,195 @@
|
||||
# ShareServer PRD
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 设计中 |
|
||||
| 版本 | 0.2 |
|
||||
| 日期 | 2026-09-05 |
|
||||
| 适用产品 | 独立部署的 ShareServer 与 Web 管理控制台 |
|
||||
| 关联架构 | [共享网络总体设计](../../../../goodbuddy/docs/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 可以只运行控制面，也可按部署策略提供数据中继和包存储。
|
||||
7. 成员可以显式开放自己的数字人，获准的组织成员可通过 `@数字人` 发起有界协作任务。
|
||||
|
||||
## 3. 产品范围
|
||||
|
||||
### 3.1 包含
|
||||
|
||||
- 本地账号及可配置 OIDC 身份源。
|
||||
- 组织、成员、角色、用户组、设备组和服务账号。
|
||||
- 设备注册、状态、撤销和合规元数据。
|
||||
- 能力目录、Publication、Grant、强制策略和审批。
|
||||
- 设备出站控制通道、任务路由、取消和可选中继。
|
||||
- 签名能力包仓库、发布通道、更新策略和撤销。
|
||||
- ShareServer 间双边联邦。
|
||||
- 组织数字人目录、数字人 Publication、授权发现和 `@数字人` 调用。
|
||||
- 审计、用量、保留和导出。
|
||||
- Web 管理控制台和成员自助页面。
|
||||
|
||||
### 3.2 不包含
|
||||
|
||||
- 远程管理设备桌面、任意 Shell 或任意文件系统。
|
||||
- 发现未注册的局域网设备。
|
||||
- 保存或分发用户 API Key、Cookie 和桌面登录状态。
|
||||
- 默认查看任务正文、附件和模型输出。
|
||||
- 上传、同步或浏览数字人所有者的本地个人、项目、会话和原始 Agent 记忆。
|
||||
- 因为成员加入组织而自动开放其数字人、记忆、Runtime、工作区或工具。
|
||||
- 未经提供者发布自动盘点设备能力。
|
||||
- 自动信任同域邮箱、同一网络或其他 ShareServer。
|
||||
- 公共开放市场、计费结算或匿名能力调用。
|
||||
- 替代 GoodBuddy 官方客户端、模型和 Agent 发布源。
|
||||
|
||||
## 4. 功能需求
|
||||
|
||||
### FR-1 实例初始化
|
||||
|
||||
- 首次启动通过一次性引导创建实例标识和首个系统管理员。
|
||||
- 引导完成后永久关闭初始化入口，后续管理员通过正常身份流程创建。
|
||||
- 实例公开描述包含名称、协议版本、登录方式和联邦端点，不包含内部拓扑。
|
||||
|
||||
### FR-2 身份与组织
|
||||
|
||||
- 支持一个实例承载多个隔离组织，也支持部署为单组织模式。
|
||||
- 支持本地账号和 OIDC；组织可限制允许的身份源。
|
||||
- 成员可以属于多个组并拥有有界角色，角色不隐式跨组织。
|
||||
- 停用用户立即停止签发新设备和任务凭据。
|
||||
|
||||
### FR-3 设备管理
|
||||
|
||||
- 桌面端经用户登录、一次性挑战和设备签名完成注册。
|
||||
- 设备条目显示所有者、平台、客户端版本、最近在线、连接和撤销状态。
|
||||
- 设备主动建立出站控制连接；服务端不能借此调用未发布能力。
|
||||
- 管理员可撤销设备并终止其新任务资格。
|
||||
|
||||
### FR-4 能力目录
|
||||
|
||||
- 只接收已注册设备或服务节点提交的显式 Publication。
|
||||
- 目录按调用者身份、设备状态、组织和策略过滤后返回。
|
||||
- 支持同一能力多个版本和多个 provider，不掩盖来源。
|
||||
- provider 离线时保留目录事实但显示不可用，不派发新任务。
|
||||
- 数字人作为由具体设备或服务节点提供的复合 Agent 能力进入目录，持续显示所有者、提供者、
|
||||
运行位置和可调用状态，不伪装成 ShareServer 自身能力。
|
||||
|
||||
### FR-5 授权策略
|
||||
|
||||
- Grant 可绑定用户、组、设备、设备组和联邦组织。
|
||||
- 可约束能力、版本、动作、输入类型、数据分类、提供者、时间、次数、并发和委托。
|
||||
- 支持组织强制策略和用户可收紧偏好；拒绝优先。
|
||||
- 每个决定返回稳定结果、命中策略和面向用户的原因。
|
||||
|
||||
### FR-6 审批
|
||||
|
||||
- 调用、能力发布、数字人上线或范围扩大、权限扩大更新和联邦关系可以要求审批。
|
||||
- 审批项显示申请人、对象、影响范围、数据类别、期限和策略依据。
|
||||
- 批准结果有明确范围和有效期，不提供无边界“永久允许”。
|
||||
- 申请内容变化后旧审批失效。
|
||||
|
||||
### FR-7 任务路由
|
||||
|
||||
- 根据冻结 provider、在线连接和路由策略把任务声明发送给目标设备。
|
||||
- 支持直连协商、网关中继和取消传播。
|
||||
- 任务正文与控制元数据分离；默认审计不保存正文。
|
||||
- 已接受任务断线后允许查询同一 task，不自动创建重复执行。
|
||||
|
||||
### FR-8 能力包与更新
|
||||
|
||||
- 保存不可变签名 Package 和发布目录。
|
||||
- 支持组织、组、平台、架构和维护窗口的更新策略。
|
||||
- 支持固定版本、允许版本范围、暂停发布和紧急撤销。
|
||||
- 权限扩大必须触发新批准，不能被普通自动更新策略覆盖。
|
||||
- 包来源、大小、摘要、签名和下载结果可审计。
|
||||
|
||||
### FR-9 联邦
|
||||
|
||||
- 两个 ShareServer 通过指纹交换和双方管理员确认建立关系。
|
||||
- 双方分别配置公开能力、允许主体、数据范围、用量和期限。
|
||||
- 最终权限取双方策略交集；任一端撤销后停止新任务。
|
||||
- 不默认链式转发到第三个组织。
|
||||
|
||||
### FR-10 审计与用量
|
||||
|
||||
- 记录身份、设备、发布、授权、审批、任务、包和联邦管理事件。
|
||||
- 默认仅记录共享架构定义的有界元数据。
|
||||
- 支持按组织隔离查询、条件筛选、分页和流式导出。
|
||||
- 审计员只读，不能因查看日志取得任务正文或管理权限。
|
||||
|
||||
### FR-11 管理控制台
|
||||
|
||||
- 提供概览、组织与成员、设备、能力目录、数字人、权限策略、审批、发布与更新、网关联邦、
|
||||
任务与中继、审计、系统设置。
|
||||
- 普通成员只看到自己的设备、授权和待办；管理员栏目按权限隐藏并在 API 再次校验。
|
||||
- 普通成员可以管理自己发布的数字人，并发现和 `@` 当前组织内获准调用的数字人。
|
||||
- 所有高影响操作说明对象、范围和后果。
|
||||
|
||||
### FR-12 可部署性
|
||||
|
||||
- 支持容器部署，配置与持久数据分离。
|
||||
- 支持外部 PostgreSQL；对象存储和中继按功能启用。
|
||||
- 提供健康、就绪、指标、结构化日志、备份和恢复说明。
|
||||
- 服务升级不能要求同时升级所有在线桌面端；按协议版本协商兼容集合。
|
||||
|
||||
### FR-13 数字人发布与组织内 `@` 调用
|
||||
|
||||
- “数字人”是运行在成员设备或组织服务节点上的可调用 Agent Publication。一个成员可以按
|
||||
不同用途发布零个或多个数字人，每个数字人独立配置 handle、能力、提供者和记忆来源；
|
||||
加入组织、注册设备或创建本地 Agent 都不会自动发布。
|
||||
- 发布时必须明确数字人的组织内唯一 `@handle`、显示名、说明、版本、提供者、支持的输入/
|
||||
输出类型、可用时间、并发、有效期、目标用户或用户组，以及
|
||||
`discover/inspect/invoke` 动作。`@数字人` 是 `invoke` 的界面入口，不绕过 Grant 或审批。
|
||||
- 数字人目录持续显示所有者、来源组织、执行设备或服务节点、Runtime 类型、版本、在线状态、
|
||||
数据策略和最近可用性；重名显示名不能掩盖唯一 handle 和实际提供者。
|
||||
- 获准成员在组织会话或任务输入中通过显式选择器插入 `@数字人`。发送前必须显示实际接收者、
|
||||
执行位置、将发送的数据类别、附件、路由、中继可读性、有效授权和可能的下游委托。
|
||||
- 一次 `@数字人` 创建绑定所选数字人 Publication、版本和 provider 的远程 Task。数字人离线
|
||||
或拒绝时不得改发给同名数字人或其他 provider；网络中断后的终态遵守 `FR-7`。
|
||||
- 数字人默认无权读取所有者的其他本地记忆。发布时，所有者可以勾选该数字人的 Agent 分区、
|
||||
Global 分区、指定 Project 分区和指定 Automation 分区；首期不能开放短期的 Conversation
|
||||
和 Run 分区。一次调用只在 Publication 冻结的允许分区中读取当前有效、已确认且敏感度
|
||||
允许的记忆。
|
||||
- 记忆检索和上下文组装始终在 Provider 本地完成。ShareServer 只保存 Publication 的分区
|
||||
种类、经过验证的本地关联 ID 摘要和是否使用专属记忆等策略元数据；原始记忆、分区内容、
|
||||
来源正文和检索结果不上传 ShareServer，也不向调用者展示。
|
||||
- 数字人输出可能受到其 Agent 记忆影响，因此发布页和调用确认必须显示“使用数字人专属记忆”
|
||||
这一事实及允许的数据敏感度。Restricted 记忆不得用于远端调用；暂停或撤销数字人后停止
|
||||
新调用，但保留历史任务和有界审计。
|
||||
- Provider 在执行边界重新验证 Publication、Grant、输入 schema、数据类别、大小、期限和
|
||||
本地 Agent 记忆权限。ShareServer 的允许决定不能扩大数字人所在设备的本地权限。
|
||||
- 所有者可以暂停、恢复、更新或撤销自己的数字人。handle 或能力、数据、工具、委托发生
|
||||
变化，或新增可读记忆分区时，旧批准失效并重新进入审批；移除可读分区可以立即收紧而不
|
||||
等待新批准，普通文案修改不得改变既有权限。
|
||||
- 审计默认只记录调用方、数字人、Publication、provider、数据类别、路由、授权、状态、耗时
|
||||
和大小，不保存消息正文、附件内容、模型输出或记忆内容。
|
||||
|
||||
## 5. 产品验收
|
||||
|
||||
- 新实例可完成初始化、登录、创建组织、邀请成员和注册真实桌面设备。
|
||||
- 两个不同组织不能通过 API、搜索、计数、错误或审计结果读取对方数据。
|
||||
- 设备只有发布能力后才进入获准目录，撤销后不能接收新任务。
|
||||
- 调用授权能同时处理用户、设备、组织、提供者、数据和联邦限制。
|
||||
- 任务中继关闭时控制面仍可运行；中继开启时可取消并形成准确终态。
|
||||
- 权限扩大的包更新不能自动部署。
|
||||
- 两个独立 ShareServer 能建立、使用、暂停和撤销双边联邦。
|
||||
- 成员可以显式发布一个数字人，获准的同组织成员能从选择器插入 `@handle` 并完成一次有界
|
||||
调用；未获准成员不能通过目录、搜索、补全或直接 API 枚举和调用该数字人。
|
||||
- 暂停或撤销数字人后不能创建新调用，已完成任务与有界审计仍可追溯到原 Publication 和
|
||||
provider。
|
||||
- 数字人调用可以使用所有者在发布时勾选的 Agent、Global、指定 Project 或指定 Automation
|
||||
分区，但不能开放 Conversation 和 Run；ShareServer 和调用者不能读取原始记忆、未选择的
|
||||
本地分区或记忆来源正文。
|
||||
- 备份恢复后组织、策略、发布和审计身份保持一致，短期连接和令牌不恢复。
|
||||
@@ -0,0 +1,88 @@
|
||||
# ShareServer 实施进度
|
||||
|
||||
## 当前状态
|
||||
|
||||
ShareServer 已进入可运行交互原型阶段。当前实现用于验证完整控制台信息架构、视觉方向与操作
|
||||
流程，不提供生产身份、组织隔离、设备连接、授权、任务路由或数据持久化。
|
||||
|
||||
### 2026-09-06：独立仓库迁移
|
||||
|
||||
- 源码、测试、锁文件、构建及容器配置从 GoodBuddy 的 `shareserver/` 移至
|
||||
`goodbuddy-shareserver` 仓库根目录，六份功能文档随迁，保留原型行为不变。
|
||||
- 跨端共享网络总体设计保留在 GoodBuddy 仓库。双向文档链接采用同级克隆布局，
|
||||
服务安装、测试、构建和运行不依赖桌面端仓库。
|
||||
- 原桌面工作区的依赖和构建产物未搬动或删除；其测试/lint 排除项保留以避开这些本地产物。
|
||||
- 新仓库执行 `npm ci`、`npm test`（2 个文件、5 个测试）、`npm run typecheck`、
|
||||
`npm run lint` 和 `npm run build` 全部通过。安装报告 1 个 low 级依赖漏洞，
|
||||
未在本次迁移中升级依赖。
|
||||
- 构建后的独立服务在回环地址通过健康、就绪、快照、无持久化操作确认、SPA 回退和
|
||||
JS/CSS 静态资源 HTTP 冒烟验证，随后停止测试进程；未重跑浏览器交互或容器运行测试。
|
||||
- 31 个非 README 源码/配置文件与来源提交逐字节一致，35 个相对 Markdown 链接均可解析。
|
||||
- GoodBuddy 桌面仓库 `npm test`、`npm run typecheck`、`npm run lint` 全部通过；
|
||||
首次全量验证达到 200 秒超时后，延长时限重跑通过。
|
||||
- 历史来源记录于根 README。此次迁移不代表生产功能、Desktop 集成或容器运行已验收。
|
||||
|
||||
### 2026-09-06：桌面发布与测试边界
|
||||
|
||||
ShareServer 功能尚未完成，不属于本次 Desktop `0.12.5` / Agent `0.11.19`
|
||||
的产品交付或发布验收范围。用户确认本次发布不需要单独测试 ShareServer，
|
||||
其原型测试通过也不代表生产功能已完成。以下记录对应拆仓前的发布操作。
|
||||
|
||||
桌面端根测试和 lint 配置排除 `shareserver/**`，桌面发布 CI 不为其单独安装测试依赖。
|
||||
ShareServer 独立项目自身的测试配置保留，供后续功能开发使用；本次不运行其独立测试。
|
||||
此前候选 `89a81dd` 临时加入的 `npm ci --prefix shareserver` 步骤已撤除。
|
||||
|
||||
ShareServer 的实现与验证在后续功能开发中单独推进；真实 Desktop 集成验收仍属于
|
||||
下文的剩余生产工作。
|
||||
|
||||
## 已验证实现
|
||||
|
||||
### 2026-09-05：全控制台交互原型
|
||||
|
||||
- `shareserver/` 是独立 Node.js/TypeScript 项目，不依赖 Electron Main 或
|
||||
`src/shared`。
|
||||
- Hono 同源提供健康、就绪、原型快照和无持久化操作确认 API。
|
||||
- 管理控制台覆盖概览、组织与成员、设备、能力目录、权限策略、审批、发布与更新、网关联邦、
|
||||
任务与中继、审计和系统设置。
|
||||
- 成员自助覆盖自己的设备、授权和申请；角色切换后导航和 URL 范围同步变化。
|
||||
- 控制台支持深浅主题、组织范围、全局搜索、列表搜索、状态筛选、详情、表单、确认、成功/
|
||||
失败反馈、响应式侧栏和键盘对话框。
|
||||
- 构建后的 Web 由 Hono 同源托管；`Dockerfile` 使用多阶段构建和非 root 运行用户。
|
||||
- readiness 明确返回 `interactive-prototype` 与 `productionReady=false`，避免把 fixture
|
||||
误认为生产服务。
|
||||
|
||||
验证证据：
|
||||
|
||||
```text
|
||||
cd shareserver
|
||||
npm test # 2 files, 5 tests passed
|
||||
npm run lint # passed
|
||||
npm run build # typecheck + Vite Web + server TypeScript passed
|
||||
```
|
||||
|
||||
浏览器实际验收：
|
||||
|
||||
- 生产构建在 `http://127.0.0.1:8787` 启动并成功加载 API 快照。
|
||||
- 宽屏管理员概览、审批详情、批准确认和原型 API 提交流程通过。
|
||||
- `390 × 844` 成员自助页面、筛选区和列表布局通过。
|
||||
- 深色与浅色审批页的 WCAG 2 A/AA 自动检查均为 0 个确定违规；半透明侧栏被检查器列为
|
||||
需人工判断项，已通过实际截图复核文字可读性。
|
||||
- 仓库级 `npm test` 通过 325 个测试文件、3501 个测试，另有 8 个文件和 55 个测试按既有
|
||||
条件跳过；仓库级 `npm run typecheck` 与 `npm run lint` 通过。
|
||||
|
||||
## 剩余生产工作
|
||||
|
||||
按技术设计从以下纵向切片开始，不能把原型 fixture 逐步演变为权威状态：
|
||||
|
||||
1. FR-1 一次性初始化、本地管理员身份、Web session 和 CSRF。
|
||||
2. PostgreSQL migration、实例/组织/成员表、强制 organization repository 作用域和事务审计。
|
||||
3. 真实组织与成员管理 API，再将对应原型页面切换到权威数据。
|
||||
4. 设备挑战注册、凭据和出站 WebSocket 连接。
|
||||
5. Publication、目录、拒绝优先策略、审批和任务路由。
|
||||
6. Package、可选中继、联邦、保留、导出、备份恢复和真实 Desktop 端到端验证。
|
||||
|
||||
当前尚未满足 PRD 的产品验收，也未进行真实 Desktop/ShareServer 集成测试。
|
||||
|
||||
2026-09-05 PRD `FR-13` 新增组织数字人发布和 `@数字人` 调用。当前交互原型尚无“数字人”
|
||||
目录、发布管理、提及选择器或 Agent 记忆边界展示，因此这些能力仍属于剩余生产与原型工作，
|
||||
不能由现有通用能力目录或原型操作确认替代。
|
||||
@@ -0,0 +1,283 @@
|
||||
# ShareServer 技术设计
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 设计中 |
|
||||
| 版本 | 0.2 |
|
||||
| 日期 | 2026-09-05 |
|
||||
| 关联 PRD | [ShareServer PRD](./prd.md) |
|
||||
| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
|
||||
| 共享协议 | [共享网络总体设计](../../../../goodbuddy/docs/architecture/share-network-architecture.md) |
|
||||
|
||||
## 1. 仓库与运行边界
|
||||
|
||||
ShareServer 在独立的 `goodbuddy-shareserver` 仓库根目录维护。当前可运行结构为：
|
||||
|
||||
```text
|
||||
goodbuddy-shareserver/
|
||||
README.md
|
||||
package.json
|
||||
server/ # Hono API 与同源静态资源服务
|
||||
shared/ # 原型 fixture 与类型
|
||||
src/ # React Web 控制台
|
||||
docs/features/share-server/
|
||||
Dockerfile
|
||||
```
|
||||
|
||||
以下是后续生产实现的建议模块结构，尚未创建，不代表已实现：
|
||||
|
||||
```text
|
||||
goodbuddy-shareserver/
|
||||
README.md
|
||||
package.json
|
||||
src/
|
||||
api/
|
||||
auth/
|
||||
organizations/
|
||||
devices/
|
||||
capabilities/
|
||||
policies/
|
||||
approvals/
|
||||
tasks/
|
||||
relay/
|
||||
packages/
|
||||
federation/
|
||||
audit/
|
||||
web/
|
||||
migrations/
|
||||
deploy/
|
||||
tests/
|
||||
```
|
||||
|
||||
仓库根目录是可独立运行的全控制台交互原型。原型使用 Hono 提供健康、就绪、
|
||||
界面快照和无持久化操作确认 API，并同源托管 React/Vite Web 控制台；它不依赖 Electron 的
|
||||
`src/shared`。当前尚未建立生产数据库、认证、设备连接和共享协议，因此也不提前创建空的
|
||||
`packages/share-protocol`。进入真实 Desktop 协议实现时，服务端和 Desktop 共同依赖
|
||||
独立发布的 `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、数字人 profile、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
|
||||
agent_profiles
|
||||
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 只存控制状态和有界统计；正文流不进入普通关系表。
|
||||
- `agent_profiles` 只保存组织内唯一 handle、显示元数据和其能力版本引用。数字人复用
|
||||
Publication、Grant、Approval 和 Task，不创建第二套授权或路由模型；本地 Agent 记忆条目、
|
||||
分区目录和来源正文不进入 ShareServer 数据库。
|
||||
- 数字人 Publication revision 保存有界 `memory_source_policy`，只允许 `agent`、`global`、
|
||||
`project` 和 `automation` 种类及 Provider 验证后的本地关联 ID 摘要。Provider 执行时按该
|
||||
revision 在本地重新解析分区并检索；服务端不接收记忆文本、来源正文、Embedding 或检索
|
||||
结果。新增来源是权限扩大，移除来源是单向收紧。
|
||||
|
||||
## 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 端到端路径通过后才能更新实施状态。
|
||||
|
||||
## 15. 当前原型实现
|
||||
|
||||
2026-09-05 建立的交互原型固定以下技术基线：
|
||||
|
||||
- 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 镜像。
|
||||
|
||||
`/api/v1/public/ready` 返回 `mode=interactive-prototype` 和
|
||||
`productionReady=false`。原型 fixture、角色切换和操作确认只用于评审信息架构，不得被
|
||||
Desktop 或部署脚本当作真实身份、策略、任务或审计 API。下一实施阶段必须从 FR-1
|
||||
初始化、本地身份、PostgreSQL 组织作用域和事务审计开始，不在 fixture 上叠加生产状态。
|
||||
@@ -0,0 +1,200 @@
|
||||
# ShareServer Web 管理界面设计
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | 设计中 |
|
||||
| 版本 | 0.2 |
|
||||
| 日期 | 2026-09-05 |
|
||||
| 关联 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、允许输入、数据政策、调用趋势和最近错误。管理员
|
||||
看到的是组织元数据，不通过目录读取能力内部数据。
|
||||
|
||||
### 6.1 数字人
|
||||
|
||||
数字人使用独立栏目呈现，不混入普通工具能力表。目录按 `@handle`、显示名、所有者、专业
|
||||
说明、提供者、Runtime、版本、在线状态和可用范围筛选；只有当前成员可发现的数字人进入
|
||||
搜索和提及补全。
|
||||
|
||||
数字人详情显示：
|
||||
|
||||
- 所有者、来源组织、执行设备或服务节点。
|
||||
- Publication 版本、支持的输入/输出、可用时间、并发和有效期。
|
||||
- 数据去向、路由、中继可读性、是否允许委托。
|
||||
- 是否使用本地记忆、允许的分区种类，以及允许处理的数据敏感度；不显示记忆条目、具体分区
|
||||
名称、来源正文和检索结果。
|
||||
- 当前成员的 `discover/inspect/invoke` 权限、命中策略和审批要求。
|
||||
|
||||
成员可以在“我的数字人”中创建多个用途不同的发布草稿，选择一个本地 Agent、设置唯一
|
||||
`@handle` 和开放范围、提交审批、暂停、恢复、更新或撤销。加入组织不会生成默认数字人，
|
||||
创建本地 Agent 也不会自动发布。
|
||||
|
||||
发布表单的“可用记忆”默认全部关闭，并允许勾选数字人的 Agent、Global、指定 Project 和
|
||||
指定 Automation 分区。Conversation 和 Run 不作为可选项。表单持续说明记忆只在提供者本地
|
||||
检索，调用者和 ShareServer 看不到内容；新增分区在保存前明确标为权限扩大，移除分区明确
|
||||
标为立即收紧。
|
||||
|
||||
组织会话和任务输入区使用带搜索的显式选择器插入 `@数字人`，不能只靠自由文本猜测 handle。
|
||||
选择后持续显示目标数字人；发送前确认实际接收者、执行位置、发送数据和授权。离线、无权或
|
||||
需要审批的项保持可读并说明原因，但不能形成已发送调用。
|
||||
|
||||
## 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 时间；联邦事件同时显示对端时间时标明时区。
|
||||
- 状态不只依赖颜色。危险操作在确认后保持原页面上下文和可恢复错误。
|
||||
|
||||
## 15. 交互原型视觉基线
|
||||
|
||||
2026-09-05 的首个可运行原型采用深海科技控制台方向，并同时提供浅色主题。视觉实现遵循
|
||||
shadcn/ui 的本地组件模式和 Radix 可访问 primitives，布局参考成熟后台的侧栏、顶栏、数据
|
||||
表格和详情对话框，但不复制第三方示例业务页面。
|
||||
|
||||
原型已覆盖数字人需求加入前的一级栏目、管理员与成员自助视图切换、组织范围、搜索筛选、
|
||||
页签、详情、创建表单、危险确认和 390px 窄屏导航。动态发光、网格和网络脉冲只用于运行状态
|
||||
与品牌氛围；业务表格仍保持克制，状态继续同时使用图标与文字。原型操作会调用无持久化确认
|
||||
API，并持续标明不会写入生产数据，不能据此宣称真实审批、撤销、策略或任务操作已实现。
|
||||
`FR-13` 新增的数字人目录、“我的数字人”和 `@` 选择器尚未进入当前原型。
|
||||
Reference in New Issue
Block a user