dsh-brain/docs/management-surface.md

80 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 统一管理卡接口与契约(0.5.0)
本文件记录 0.5.0 交付的「连接与上报 / 技能管理 / MCP 管理」三页签所依赖的真实接口、约束与验证结果。凡是未实现的能力都在这里写明,不在界面上假装可用。
## 1. 路由
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/cloud-memory` | 自带配置页(旧入口,保留) |
| GET | `/cloud-memory/status` | 设置 + 令牌掩码 + 上报计数 + `lastCheck` + `capabilities` |
| GET | `/cloud-memory/capabilities` | 能力清单与缺口说明 |
| PUT | `/cloud-memory/config` | 写配置;换 origin 时返回 `credentialsCleared` |
| POST | `/cloud-memory/login` | 账号一次性换取令牌 |
| POST | `/cloud-memory/test` | 只读分项检查:`network` / `activity` / `memory` / `summary` |
| POST | `/cloud-memory/flush` | 重试上报队列 |
| GET | `/cloud-memory/skills/api` | 技能清单 + `plans`(未完成安装计划) |
| POST | `/cloud-memory/skills/detail` | `{folder}` → SKILL.md、文件清单、哈希 |
| POST | `/cloud-memory/skills/toggle` | `{folder, enabled}` → 目录移动 + 生效范围说明 |
| POST | `/cloud-memory/skills/install/plan` | `{url}` → 暂存克隆 + 候选描述 |
| POST | `/cloud-memory/skills/install/commit` | `{planId, folders}` → 只装选中项 |
| POST | `/cloud-memory/skills/install/cancel` | `{planId}` → 丢弃暂存 |
| POST | `/cloud-memory/skills/install` | 旧页面用的一次性安装(等于 plan + 全部非冲突项) |
| POST | `/cloud-memory/skills/uninstall/plan` | `{folder}` → 影响预览 + 一次性 token |
| POST | `/cloud-memory/skills/remove` | `{folder, token, confirmed:true}` → 真实删除 |
## 2. 契约要点
### 2.1 服务地址与凭据
- `settings.baseUrlConfigured=false` 表示地址仍是打包占位符,界面必须显示「未配置服务」。
- 写入配置时若 `new origin != old origin`:本次请求没有显式提供新值的令牌全部删除,响应带 `credentialsCleared: ['activity','memory','summary']`。旧服务的 bearer token 绝不会被发往新 origin。
- 令牌只以掩码形式出现在 `status`;清除是独立动作(`clear*Token`)。
### 2.2 检查状态
`POST /test` 返回 `checks[]`,每项 `{id,label,state,message}`,`state ∈ ok | unconfigured | invalid | forbidden | unreachable | error`。鉴权通过与「已写入一条上报」分开显示;`:reach()` 只证明服务可达。
### 2.3 技能安装
1. `plan`:只接受 `https://` / `file://`;`git clone --depth 1` 到 `$DSH_HOME/.cloud-memory-staging/<planId>`;候选深度 ≤ 3、≤ 60 个;描述含 `files`、`bytes`、`scripts`、`conflict`、`problem`。
2. 计划记录只保存 `planId / url / createdAt / expiresAt / stagingDir / candidates` 元数据,TTL 30 分钟;过期计划连暂存目录一起清理。
3. `commit`:只安装 `folders` 里且计划中存在的候选;`conflict`/`problem` 一律跳过;`.git` 与符号链接在 `cp` filter 中被剔除;源与目标都校验在各自根目录内(`path_escape`)。
4. 不执行仓库里的任何脚本、钩子或依赖命令;需要执行时由用户另行决定。
### 2.4 技能卸载
`uninstall/plan` 返回真实目录、文件数、字节数、含脚本列表、`recoverable:false` 与提示,并签发绑定该目录的一次性 token(10 分钟);`remove` 必须同时满足 `confirmed:true` + 该 folder 的 token,token 用后即废,换目录无效。没有回收站,删除即不可恢复,界面必须原样说明。
### 2.5 启停
启停仍是把目录移进/移出 `$DSH_HOME/skills-disabled/`,属于**新会话生效**;已加载会话不受影响。接口在响应里带这条说明,界面不得宣称立即生效。
### 2.6 MCP 桥接
MCP 页签不新建凭据库,读取宿主 `dsh-mcp-connector`(0.2.88)同源公开接口:
```
POST /mcp-connector/api { "method": "status" | "healthCheck" | "toolsList" | "setEnabled" | "reconnect" | "disconnect" | ..., "params": {...} }
```
- 探测失败(404/超时/非 200)→ 界面显示能力缺口,并指向「设置 → 插件配置 → MCP 服务器配置」这一权威入口。
- 只展示 `name / transport / authMode / enabled / connectionState / injectionLabel / scope / healthCheckedAt / lastError`;不回显 stdio 启动命令、env、token 或敏感 header。
- 工具缓存与连接状态分开显示:工具可见 ≠ 业务可调用。
- 市场条目与远端文本视为不可信内容,不内嵌执行。
## 3. 已执行验证(Windows,本机 Node v24.21.0)
- `verify-brain-panel.mjs`:53 项全过(status/capabilities、config 换 origin 清凭据、方法/Origin/Content-Type 闸门、技能清单与详情、安装计划与选择、冲突跳过、计划过期、暂存清理、卸载预览与一次性 token、路径穿越拒绝)。
- `verify-skill-admin.mjs`:15 项全过(含与同步引擎的联动:已停用技能不被云端更新重新启用)。
- `tsc -p tsconfig.build.json` 与 `tsc -p tsconfig.json --noEmit`:无错误。
## 4. 明确未完成
- 技能市场:无经验证来源,`features.skillsMarketplace=false`。
- 云端同步冲突的交互式处理(保留本地/采用云端/手动合并):仍由现有引擎按原策略暂停冲突项,界面只读展示。
- 自动更新与版本回退:未实现(无来源清单与制品基线)。
- MCP 市场的内嵌浏览与安装:未实现,只给宿主面板位置。
- 跨软件(Codex / Claude Code / OpenCode)适配与工作区级作用域:未实现,仍在方案 P0/P4 调研项。
- 浏览器端实机验收(375/574/1280 宽、深色模式、真实上报):需要重启 DSH 后由用户在界面确认。