dsh-brain/docs/management-surface.md

12 KiB
Raw Blame History

统一管理卡接口与契约(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 后由用户在界面确认。

5. 技能来源树(0.5.0 增补)

「技能管理」页签按软件来源组织,来源→分类→技能三层,与工作方式一致:DSH 来源是真的,其他软件目录只读。

5.1 来源检测

id 标签 目录 本卡权限
dsh DSH $DSH_HOME/skills(停用区 $DSH_HOME/skills-disabled) 真实启停
agents 公共 Agent ~/.agents/skills 只读
codex Codex ~/.codex/skills 只读
workbuddy WorkBuddy ~/.workbuddy/skills 只读
claude Claude Code ~/.claude/skills 只读
opencode OpenCode ~/.config/opencode/skills 只读

目录不存在也照实显示 0 个(标注「目录还不存在」),不猜、不造。检测每次刷新时重算。

5.2 分类是纯元数据

$DSH_HOME/cloud-memory-skill-groups.json 只存 {sourceId: {enabled, groups: [{id,name,enabled,skills:[folder]}]}}。

  • 新建 / 改名 / 删除分类都不移动任何文件;删除分类只是把成员释放回「未分类」,接口返回 released 数量。
  • 一个技能最多属于一个分类:加入新分类会先从旧分类移除。
  • 未分类是合成分组(id: 'unassigned'),它的开关对该来源里所有未被分类的技能逐个生效。

5.3 开关的真实边界

位置 DSH 来源 其他来源
来源开关 真实:全部技能移入/移出 skills-disabled cardOnly: true,只记在本卡,不动它们的目录
分类开关 真实:该分类成员逐个启停,返回 applied / failed cardOnly: true
技能开关 真实(目录移动) 不提供(行内标「只读」)

任何真实启停都是目录移动,属于新会话生效;已在运行的会话保留旧状态。失败项逐条返回,不整批回滚成谎报成功。

5.4 接口

方法 路径 说明
GET /cloud-memory/skills/sources 整棵树 + note(分类不移动文件、只有 DSH 真实启停)
POST /cloud-memory/skills/groups/create {sourceId, name}
POST /cloud-memory/skills/groups/rename {sourceId, groupId, name}
POST /cloud-memory/skills/groups/delete {sourceId, groupId} → {released}
POST /cloud-memory/skills/groups/assign {sourceId, groupId, folders[]};groupId:'unassigned' 或空数组=移出分类
POST /cloud-memory/skills/groups/toggle {sourceId, groupId, enabled} → {cardOnly, applied[], failed[]}
POST /cloud-memory/skills/source/toggle {sourceId, enabled} → {cardOnly, applied, failed[]}
POST /cloud-memory/skills/source/reveal {sourceId} → 在系统文件管理器打开该来源根目录(仅已登记的源)

错误码:unknown_source / not_found → 404,invalid_name / duplicate / too_many → 400。

5.5 验证

verify-skill-tree.mjs:40 项通过——来源与计数、分类增删改、成员唯一性、DSH 真实 park/unpark、「未分类」开关只作用于未分类技能、外来源 cardOnly 且目录字节不变、持久化重开、路由闸门与错误码。

6. P3:技能市场 / 同步冲突 / 更新回退(0.6.0)

6.1 市场来源

首个经验证来源是 Anthropic 公开的 Claude 技能市场清单 https://raw.githubusercontent.com/anthropics/skills/main/.claude-plugin/marketplace.json。 客户端只传 provider 与条目 id,从不传仓库地址,因此宿主不会去拉取任意 URL。

方法 路径 说明
GET /cloud-memory/market/providers 已配置来源(id/标签/仓库)
GET /cloud-memory/market/search ?provider=&q=&cursor= → 条目分页
POST /cloud-memory/market/detail {provider,id} → 逐技能 SKILL.md 元数据
POST /cloud-memory/market/plan {provider,id} → 解析提交 + 克隆暂存计划(只列该条目技能)
POST /cloud-memory/market/commit {planId,folders} → 只装勾选项
POST /cloud-memory/market/cancel {planId} → 丢弃暂存

resolveArtifact 通过 GitHub API 解析固定提交;克隆后以 git rev-parse HEAD 记录实际提交,安装失败不会留下半装目录。

6.2 来源记录与更新/回退

安装(Git 或市场)会在技能目录写入 .skill-source.json:provider / repoUrl / ref / commit / sourcePath / entryId / installedAt,不含任何凭据。

方法 路径 说明
POST /cloud-memory/skills/update/check {folder} → 与来源最新提交比较,返回 added/removed/changed
POST /cloud-memory/skills/update/apply {folder,expectedCommit} → 更新前整目录备份,再切换并重写记录
POST /cloud-memory/skills/rollback {folder} → 恢复最近一次更新前备份

安全点:只信任来源记录里的仓库地址;新克隆在 $DSH_HOME/.cloud-memory-staging,复制时剔除 .git 与符号链接;expectedCommit 过期返回 stale_plan,绝不覆盖;同步进行中拒绝写。

6.3 同步冲突交互

SkillSync 仍然只按原策略暂停冲突项,但会暴露两侧信息并允许人工处置:

方法 路径 说明
GET /cloud-memory/sync/status 最近统计 + 每个冲突的本地/云端两侧
POST /cloud-memory/sync/run 立即执行一次同步
POST /cloud-memory/sync/resolve {name,action}:keep_local / take_cloud / manual
  • keep_local:用本地文件按当前云端 revision 上传为新版本;revision 过期返回 stale_revision。
  • take_cloud:先把本地目录备份到 $DSH_HOME/.cloud-memory-backups/sync/<name>/<时间>,再写入云端 bundle。
  • manual:只返回两侧信息,不改任何文件。

6.4 验证

  • verify-market.mjs:19 项通过(清单解析、search/detail、未知来源 400、plan 固定提交、只装勾选项、来源记录)。
  • verify-skill-update.mjs:15 项通过(真实 git 仓库的 check/apply/rollback、无来源拒绝、过期提交拒绝、备份存在)。
  • verify-sync-resolve.mjs:12 项通过(一次真实 pass 产生 4 个冲突、take_cloud 备份并覆盖、keep_local 上传、manual 只读、stale 拒绝)。