feat: add device sharing metadata application

docs/features/device-sharing/README.md

@@ -1,7 +1,11 @@
 # 设备发现与共享
 
-本功能是 GoodBuddy 桌面端管理附近设备、本机共享和 ShareServer 连接的唯一入口。默认连接
-方式是局域网；网关由用户额外添加。功能不包含 ShareServer 的组织管理 Web 界面。
+设备共享从“应用 → 设备共享”或“管理应用 → 设备共享 → 打开”进入。当前首期连接本地未认证
+ShareServer 元数据服务，默认地址为 `http://127.0.0.1:8787`，可注册本机、浏览设备与发布目录、
+发布能力或知识的元数据并撤销本机 ID 的条目。设备 ID 只用于识别，不是所有权认证。
+
+当前实现不执行远程能力，不读取、搜索或下载知识正文；来源模式和权限均为元数据声明。
+局域网发现、配对、组织网关和远程调用仍是后续设计，不是首期交付内容。
 
 ## 文档导航
 
@@ -9,12 +13,13 @@
 | --- | --- |
 | [PRD](./prd.md) | 用户问题、范围、功能需求和产品验收 |
 | [功能逻辑](./logic-design.md) | 不变量、状态、授权优先级和失败结果 |
-| [UI 设计](./ui-design.md) | 设置入口、四个页签、配对与调用交互 |
+| [UI 设计](./ui-design.md) | 当前应用入口、单页表单与列表，以及后续发现、配对界面 |
 | [技术设计](./technical-design.md) | Desktop 进程边界、持久化、IPC、网络和验证 |
+| [实施进度](./progress.md) | 首期实现、检查命令、真实 Electron 联调证据及未测范围 |
 | [共享网络总体设计](../../architecture/share-network-architecture.md) | 跨端身份、能力、授权、任务、更新和协议权威 |
 
-当前没有单独的 User Stories：正常、失败、撤销、权限和兼容场景已直接进入 PRD 验收与逻辑
-决策表。功能尚未实施，因此不创建 `progress.md`。
+当前没有单独的 User Stories：首期验收见 PRD 的 `FR-M1` 至 `FR-M5`；后续场景仍在原有
+需求与逻辑决策表中保留。下列 Peer、配对、网关术语仅用于后续设计。
 
 ## 术语
 

docs/features/device-sharing/logic-design.md

@@ -12,6 +12,23 @@
 
 本文负责桌面端状态、不变量和决策规则，不重复跨端协议定义。
 
+## 当前首期规则
+
+本节对应 [FR-M1 至 FR-M5](./prd.md#当前首期本地元数据)。后文发现、配对、授权和任务状态均为
+后续设计，不适用于本地未认证元数据服务。
+
+本机 ID 在首次读取设置时生成并原子保存；并发首次读取共用一次加载。名称与服务 URL 更新
+串行保存，不接受 Renderer 写入设备 ID。已存在设置无法读取或解析时直接报错，避免静默
+更换身份。切换服务保持本机 ID，但目标服务必须有本机注册记录才能发布。
+
+页面初次加载读取真实目录，空列表、加载中和读取失败分别展示。刷新失败保留旧列表并标记
+可能过期，禁用发布和撤销；用户可修改配置或重试。每次请求固定使用开始时读取的服务地址。
+页面操作期间锁定重复提交。保存失败保留设置草稿，发布失败保留条目草稿。
+
+发布状态只有 `published` 与 `revoked`。撤销入口匹配本机 ID，Main 再查询本机发布列表并确认
+条目 ID；这只是防止误操作，不是认证。撤销只改变元数据状态。能力类型发送三个 `false`
+权限；知识类型按独立选择发送。目录读取无需注册，注册记录不表示在线。
+
 ## 1. 核心不变量
 
 ### INV-1 连接方式独立

docs/features/device-sharing/prd.md

@@ -11,6 +11,30 @@
 | 关联架构 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
 | 关联文档 | [功能逻辑](./logic-design.md)、[UI 设计](./ui-design.md)、[技术设计](./technical-design.md) |
 
+## 当前首期：本地元数据
+
+2026-10-01 首期范围由 `FR-M1` 至 `FR-M5` 定义。后文 `FR-1` 至 `FR-14` 保留为后续共享网络
+设计，不能用来推断首期已有发现、认证、调用或内容传输能力。
+
+- **FR-M1 入口与设置**：应用中心及应用菜单提供“设备共享”。本机设备 ID 稳定保存，用户可
+  修改服务 URL 和设备名称。设置保存后重启仍保留；新设备默认连接 `http://127.0.0.1:8787`。
+- **FR-M2 注册与浏览**：用户显式注册本机，随后查看服务实际返回的设备及发布列表。注册
+  包含 ID、名称、平台、应用版本；时间来自服务记录，不从更新时间推断在线状态。
+- **FR-M3 元数据发布**：注册本机后可发布名称、描述、能力或知识类型、设备或服务器来源。
+  知识的搜索、读取、下载三个标志独立选择。服务器来源不会上传、同步或托管内容；权限
+  标志不提供内容访问实现。
+- **FR-M4 撤销与刷新**：只给匹配本机 ID 的已发布条目提供撤销入口，确认后更新服务记录并
+  刷新目录，显示已撤销状态。该筛选不构成认证，服务本身没有所有权鉴权。
+- **FR-M5 失败恢复**：请求有超时，错误可见；失败保留用户输入，列表失败不伪装为空目录。
+  修改服务 URL 后必须先保存，再向新服务注册或发布。既有应用设置、排序和常驻偏好保留。
+
+验收顺序为保存配置、注册本机、浏览返回列表、发布知识元数据、检查三个独立标志、撤销、
+刷新并重启读取设备 ID。网络请求由 Main 发出，Renderer 只调用显式 preload 方法。
+
+## 后续设计
+
+以下章节为完整共享网络计划，尚未实施。
+
 ## 1. 背景
 
 GoodBuddy 的能力当前主要在本机执行，SSH 远程项目则要求用户预先配置具体 Host。个人和组织

docs/features/device-sharing/technical-design.md

@@ -11,6 +11,37 @@
 | 功能逻辑 | [功能逻辑设计](./logic-design.md) |
 | 共享协议 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
 
+## 当前首期实现
+
+本节实现 [FR-M1 至 FR-M5](./prd.md#当前首期本地元数据)。后文模块树、SQLite 表、共享协议包、
+局域网与网关协议都是后续设计，当前不创建这些基础设施。
+
+`src/shared/device-sharing-contracts.ts` 定义严格输入和返回类型；`DesktopApi.sharing` 暴露
+`getSettings`、`saveSettings`、`registerDevice`、`getCatalog`、`publish`、`revoke` 六个方法。
+生产 preload 对应六个固定 IPC 通道，`device-sharing-ipc.ts` 对每次调用检查可信主窗口主帧，
+对变更输入进行 Zod 校验，不暴露通用网络入口。
+
+`DeviceSharingService` 在 Main 内使用 `fetch`，每个请求含响应体读取采用 10 秒超时，非成功
+响应保留 HTTP 状态；响应再经 Zod 校验。请求只在页面读取或用户动作时发出，不启动后台发现。
+URL 接受 HTTP／HTTPS，禁止内嵌凭据、查询和片段。没有令牌或 Agent／Runtime 改动。
+
+| 方法 | HTTP 请求 |
+| --- | --- |
+| 注册 | `POST /api/v1/sharing/devices/register`，字段为 `id,name,platform,appVersion` |
+| 设备列表 | `GET /api/v1/sharing/devices`，读取 `{devices:[]}` |
+| 发布列表 | `GET /api/v1/sharing/publications`，读取 `{publications:[]}` |
+| 发布 | `POST /api/v1/sharing/publications`，Main 生成条目 ID 并填入本机设备 ID |
+| 撤销 | 先按 `?deviceId=` 获取本机条目，再 `POST /api/v1/sharing/publications/:id/revoke` |
+
+设备 ID、名称与服务 URL 存在用户数据目录的 `device-sharing-settings.json`，版本为 1；
+复用 `writeJsonFileAtomically`，加载 Promise 去重、保存串行。损坏设置报错而不重置 ID。
+此文件不保存目录副本或凭据。导航沿用已有存储归一化，把 `device-sharing` 追加到旧顺序，
+保留既有应用相对顺序与设置；新入口可排序，无启用或常驻开关，始终可从应用菜单进入。
+
+服务测试使用真实 loopback HTTP，验证契约、独立权限、识别范围、持久化、错误和超时；
+Electron 测试通过环境变量选择相邻真实 ShareServer 源码，使用临时服务数据与桌面设置。
+具体命令和实测边界见[实施进度](./progress.md)。
+
 ## 1. 进程边界
 
 ```text

docs/features/device-sharing/ui-design.md

@@ -14,6 +14,24 @@
 本文只定义桌面端界面。所有颜色、间距、字体、通知、Switch、PageTabs、焦点和响应式行为以
 全局设计系统为准。
 
+## 当前首期页面
+
+本节对应 [FR-M1 至 FR-M5](./prd.md#当前首期本地元数据)，后文四页签、配对及调用界面为后续设计。
+
+入口在应用菜单和应用中心，主内容区使用 `standard` PageShell、PageHeader 与全局范围徽标。
+标题下常显未认证、ID 识别用途和无执行／内容访问的边界。内容依次为本机设置、已注册设备、
+发布表单和发布目录。服务 URL 与设备名称可编辑，设备 ID 只读；注册、保存与刷新为次操作，
+“发布元数据”为唯一主按钮。
+
+类型与来源使用短标签原生选择框；知识的搜索、读取、下载使用三个独立 Checkbox。服务器来源
+不上传或同步内容的说明常显。发布按钮附近显示已保存的目标服务及设备名称，尚未注册或
+配置未保存时给出操作提示。列表展示服务返回的名称、标识、平台／类型、更新时间和发布状态，
+不展示在线灯或执行按钮。
+
+撤销使用共享危险入口和就地确认，说明保留记录且不删除本机内容。成功与操作失败通过应用
+通知反馈；目录加载失败在页面显示并由刷新按钮恢复。宽度收窄时按钮换行，长 URL 和 ID 换行；
+表单复用 `.field`，颜色与间距使用共享令牌。页面文案提供中英文。
+
 ## 1. 信息架构
 
 设置中心新增一级分类“设备发现与共享”，使用 `standard` PageShell：