ishuowang/dsh-rolehub-bridge

DSH RoleHub Bridge

选择一个可移植角色，验证它的 bundle，再把它作为 DSH 原生、可恢复的 Session 启动。

当前会话仍然是当前会话，Agent Team Room 仍然只做 Room。

English · 安装 · 原生-ui · 命令 · 信任模型 · 安全说明

RoleHub Bridge 是 RoleHub 面向 DeepSeek Harness 的原生兼容层。它从 Host 配置的 Hub 发现可移植角色，校验并锁定准确 bundle，计算由 Host 控制的 effective policy，然后创建一个独立、角色作用域内的子 Session。

这里没有内置公司团队、人物角色或 Room 场景。只有人在界面或 Host 命令中明确选择时，角色才会从 RoleHub 进入 DSH。Agent Team Room 只是生成 Session 的可选去向，不是必选依赖，也不提供角色权限。

一个 bridge，清晰边界

Bridge 负责	Bridge 刻意不负责
Hub 发现、catalog 校验和有界下载	角色创作或社区治理
精确校验 manifest、archive 与 bundle 摘要	因为角色出现在 catalog 就自动信任发布者
effective capability policy 与固定 Host 工具绑定	让角色自行授予工具、密钥、shell、网络或 Room 权限
新建可恢复、角色作用域内的子 Session	把正在进行的会话热切换成另一个角色
通过 Room 公共 Host API 可选接入成员	Room 成员关系、投递、任务、场景或看板
增量式 DSH 原生控件和只读快照	替换 DSH Web、修改任意 DOM 或注入全局 CSS

架构

flowchart LR
  U[人在 DSH 原生 UI 中操作] -->|明确选择| C[/rolehub Host 命令]
  U -->|同源 GET| V[字段白名单角色快照]

  subgraph Bridge[RoleHub Bridge]
    C --> R[Resolver + 私有缓存]
    H[HTTPS Hub catalog] --> R
    R --> D[摘要锁定 deployment]
    D --> P[Host effective policy]
    P --> A[DSHarness 兼容 setup]
  end

  A --> S[可恢复子 Session]
  S -. 可选接入 .-> M[Agent Team Room]
  X[冷恢复] -->|provider 名包含 bundle 摘要| D
  D -->|重验 receipt + bindings| X

最终可执行能力一定比角色请求更窄：

角色 required 请求 ∩ bridge 支持范围 ∩ Host allowlist

可选能力不会自动授予；缺少任意 required 能力时会直接失败。

DSH 原生 UI

插件通过官方 conversation.session.header.actions 与 sidebar.footer.action typed slot 增加 RoleHub 入口。两个入口打开同一个原生 Modal：可按 Hub、标签、描述和能力搜索，查看 bundle 摘要与能力分组，再创建角色 Session。安装 Room v0.6 或更新版本后，Bridge 会把同一个已验证选择器分别注册到 Room 的 header/footer provider seat，并预选当前 Room；原 header seat key 仍会注册，让既有 provider 集成继续使用稳定接口。

第一次打开界面只执行同源 GET。刷新会明确运行 /rolehub refresh，启动角色会明确运行 /rolehub start。浏览器快照只包含 Hub id、公开角色元数据、摘要、能力标签和有界 Room 摘要；不会暴露 catalog/archive URL、本地路径、policy receipt、provider binding、会话历史或 Room 私有数据。

这里没有独立 RoleHub 看板。对话、侧栏、输入框与 Room 成员管理仍由 DSH 和 Room 本身负责。

安装

要求 Node.js ^22.19.0 || >=24 与 DeepSeek Harness 0.1.0-rc.6。

dsh plugin --profile web add github:ishuowang/dsh-rolehub-bridge#v0.2.0
dsh web

v0.2 推荐使用锁定版本的 GitHub 安装。bundle 会把 Host runtime、/rolehub 命令、只读原生 API 和 Web client 一并加入同一 profile；当前尚未发布 npm 包。

如需把创建出的角色 Session 接入 Room，请在同一 profile 安装 Room：

dsh plugin --profile web add github:ishuowang/dsh-agent-team-room#v0.6.0

没有 Room 时，除接入 Room 外的功能都可正常使用：角色会作为普通的独立子 Session 启动。

第一个角色

刷新已配置 Hub，检查一个角色，然后启动：

/rolehub refresh
/rolehub inspect official/software-engineer
/rolehub start official/software-engineer --label "Software engineer" --prompt "Review the current implementation."

只有安装 Room 时，才能在创建时把 Session 接入 Room：

/rolehub start official/software-engineer --room <room-id> --label "Implementation reviewer"

初始 prompt 只会投递到子 Session，不会重放到父会话的命令历史，也不会复制进 Room 存储。

/rolehub 命令

/rolehub hubs
/rolehub list
/rolehub refresh
/rolehub inspect <hub>/<role-name>
/rolehub start <hub>/<role-name> [--label "..."] [--room <id>] [--prompt "..."]
/rolehub sessions

操作	结果
hubs	在 Host 命令平面列出已配置 Hub id 与 catalog 位置。
list	列出最近一次通过校验的 catalog 快照中的角色。
refresh	拉取并校验 catalog；网络失败时，可为已安装角色和查看操作回退到有时效上限的缓存。
inspect	查看角色身份、信任标签、摘要和能力请求。
start	校验/安装角色，创建可恢复子 Session，并可选接入 Room。
sessions	列出当前父 Session 的持久化角色绑定。

所有写操作都只能通过这个 Agent-scoped Host 命令执行。插件刻意不提供面向模型的“安装角色”或“启动角色”工具。

配置

默认配置不够时，编辑当前 profile 的 cordis.patch.yml 中由插件插入的 rolehub-bridge 行：

- id: rolehub-bridge
  name: dsh-rolehub-bridge
  config:
    storageDir: /srv/dsh/rolehub-bridge
    allowCommunityRoles: false
    allowedCapabilities:
      - filesystem.read
      - filesystem.write
      - network.fetch
      - web.search
      - source-control.read
      - room.message
    fetchTimeoutMs: 15000
    maxCatalogCacheAgeMs: 86400000
    maxCatalogBytes: 2000000
    maxArchiveBytes: 20000000
    agentProvider: ""
    agentModel: ""
    hubs:
      - id: official
        catalogUrl: https://raw.githubusercontent.com/ishuowang/agent-role-hub/main/catalog/index.json
        archiveUrlTemplate: https://github.com/ishuowang/agent-role-hub/releases/download/v{version}/{name}-{version}.role.tgz
        trustedPublishers:
          - io.github.ishuowang
        allowedRedirectHosts:
          - release-assets.githubusercontent.com
          - objects.githubusercontent.com

所有 Hub 地址必须是无凭证的 HTTPS。发布者信任只绑定到单个 Hub；即使另一个 Hub 声称同名发布者，也不会继承 official 的信任。重定向默认只能留在原请求 host，额外目标必须精确写入该 Hub 的 allowedRedirectHosts。已验证 catalog 缓存超过 maxCatalogCacheAgeMs 后不再回退使用，默认有效期为 24 小时；离线缓存永远不能授权首次安装角色。

storageDir 默认使用 $DSH_HOME/rolehub-bridge；未设置 DSH_HOME 时使用 ~/.dsh/rolehub-bridge。Bridge 只会认领带自身 marker 的专用私有存储，使用 0600 文件、有界下载、安全归档解包与原子 receipt 写入；遇到危险路径或非私有的既有根目录会直接拒绝，不会擅自修改其权限。请把该目录视为单 Host 状态，不要手工修改 receipt。

agentProvider 与 agentModel 可覆盖新角色 Session 的路由；都留空时遵循 DSH 正常路由。

信任与能力边界

Catalog 中的标签只是发现元数据，不是密码学签名。激活前，Bridge 会把完整 catalog 身份与已加载 manifest 对齐，记录下载 archive 哈希，并校验 manifest、bundle lock 与最终 RoleHub bundle 摘要。Reference publisher 必须在对应 Hub 配置中明确受信；community 角色需要设置 allowCommunityRoles: true。

角色可以请求能力，但不能授予自己能力。v0.2 只会授予同时存在于 allowedCapabilities 且由 Bridge 固定 DSH binding 实现的 required 请求。Denied 保持拒绝，optional 保持未授权；任何 required 能力不支持都会中止创建。生成的 policy receipt 与角色 bundle 摘要绑定，并会在每次 activation 前重新验证。

这些控制是共享 Host 进程内的 DSH tool-policy 边界，不等于 OS sandbox、容器、出口防火墙、secret broker 或交互式审批系统。Bridge 和兼容包都是可信 Host 代码，安装前应审查。

冷恢复

每个已创建 Session 都记录一个由准确 bundle 摘要派生的 provider 名。Host 冷启动时，Bridge 重新加载已验证 deployment 和不含 prompt 的 Session binding，再检查 deployment、manifest、bundle、policy receipt 与固定 binding，最后在子 Session 发布前应用 DSH 角色 setup。若 deployment 缺失或不匹配，会失败关闭，而不是悄悄加载同名角色的最新版。

持久化内容包括 catalog 快照、已验证角色文件、deployment/policy receipt 与 Session-to-digest binding；不会把 Session 历史、Room 消息、密钥或用户初始 prompt 作为 Bridge 元数据保存。

可选 Room 集成

Room 保持角色中立：不发现 RoleHub、不加载 prompt 或 skill，也不解释 capability policy。Bridge 先验证角色并启动独立 Session，再请求 Room 接入该 Session，同时携带不参与授权的 RoleHub 来源信息（id、version 与 bundle 摘要）。从 Room 移除成员或关闭 Room，都不会删除对应 DSH Session。

如果 Session 创建后，Room 接入或 receipt 持久化失败，Bridge 会尝试移除 Room 成员、中断子 Session，并记录 orphaned binding 便于诊断；不会假装跨插件操作具备完整事务性。

v0.2 限制

• DeepSeek Harness 集成仍是 developer preview，并固定到 0.1.0-rc.6；升级 DSH 前必须重新验证。
• 摘要校验只能证明完整性，不能证明发布者身份；尚未实现签名、透明日志、撤销与交互式信任确认。
• 尚未实现 optional capability 审批，所以 optional 请求不会被授予。
• 角色声明的 turn/output/time 限制与模型偏好尚未映射到 DSH runtime；仍以 Host/Session 限制为准。
• 执行边界是进程内 DSH tool policy 与隔离角色配置，不是独立进程或 OS sandbox。
• 原生接口的同源检查不是身份认证；远程暴露 DSH 前应配置带认证的 TLS 入口。
• Catalog 刷新可回退到近期已验证缓存，但首次安装角色始终要求 Hub 和 archive 下载在线；创建 Session 可能消耗模型额度。
• Room 接入使用跨插件补偿机制，不是分布式事务。

开启 community 角色或把 DSH Web 暴露到公网前，请阅读 SECURITY.md。

开发

npm ci
npm run check
npm pack --dry-run
git diff --check

仓库会提交 lib/ 发布产物，使 GitHub 安装无需执行依赖的 prepare 脚本。开发分支统一使用 feature/ 前缀；仓库约束见 AGENTS.md。

License

MIT © 2026 ishuowang · 爱发电支持