5.6 KiB
5.6 KiB
统一管理卡接口与契约(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 技能安装
plan:只接受https:///file://;git clone --depth 1到$DSH_HOME/.cloud-memory-staging/<planId>;候选深度 ≤ 3、≤ 60 个;描述含files、bytes、scripts、conflict、problem。- 计划记录只保存
planId / url / createdAt / expiresAt / stagingDir / candidates元数据,TTL 30 分钟;过期计划连暂存目录一起清理。 commit:只安装folders里且计划中存在的候选;conflict/problem一律跳过;.git与符号链接在cpfilter 中被剔除;源与目标都校验在各自根目录内(path_escape)。- 不执行仓库里的任何脚本、钩子或依赖命令;需要执行时由用户另行决定。
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 后由用户在界面确认。