dsh-flowus

@blksword/dsh-flowus

English | 中文

DeepSeek Harness（DSH）的 FlowUs 集成插件。该插件在宿主进程内完成面向 FlowUs 官方 MCP 服务器（https://mcp.flowus.cn/message）的 OAuth 2.1 授权（RFC 9728 元数据发现、RFC 7591 动态客户端注册、PKCE S256），将服务器公布的工具注册为 Agent 原生工具，并提供 /flowus 命令与设置面板页面。授权过程不使用静态令牌。

功能范围

• 浏览器授权。 面向 FlowUs 官方 MCP 服务器完成 OAuth 2.1 授权码流程，回调地址为 127.0.0.1 上的 loopback 监听。访问令牌与刷新令牌保存在插件私有状态文件中，由插件自动续期。
• 原生工具。 将 FlowUs MCP 服务器公布的工具注册至 DSH 工具注册表，命名规则与 DSH 内置 MCP 桥一致，即 mcp__flowus__<工具名>。
• /flowus 命令。 提供状态查询、授权、登出、工具列表、直接调用、重连与帮助。
• 设置面板页面。 设置面板中的独立 FlowUs 页面：授权与连接状态、服务器版本、工具目录（可按名称或描述搜索，并标注只读/写入），以及授权、重连、登出、刷新操作；凭据路径与授权地址可一键复制，登录等待期间自动轮询，切回标签页时立即刷新。
• 系统提示词段落。 将服务器 instructions 与当前工具目录并入系统提示词；未授权时给出明确的操作指引。

背景

DSH 内置的 @deepseek-ai/dsh-mcp-client 支持 stdio 与 streamable-http（自定义请求头）两种接入方式，不支持 MCP OAuth。FlowUs 官方 MCP 服务器采用 OAuth 2.1，并要求客户端在无法完成授权流程时明确报告，而非退回静态令牌。本插件实现该 OAuth 客户端流程，并将发现的工具桥接至 ctx.tools。

环境要求

安装

从 npm 安装

dsh plugin --profile web add @blksword/dsh-flowus@latest

dsh plugin add 的执行过程如下：

1. 通过 pnpm 安装该包；
2. 识别包内声明的 dsh.bundle.patch，并将 @blksword/dsh-flowus 追加至 dsh.profile.bundles（无需手工编辑 package.json）；
3. 通过 peer 依赖解析到 DSH 安装内提供的 @deepseek-ai/* 实现。

pnpm 11 的 minimumReleaseAge 默认值为 1440 分钟：发布不足 24 小时的版本在解析 @latest 时会被跳过，解析结果回退至上一版本，且退出码仍为成功。安装最新发布时应指定确切版本号：

dsh plugin --profile web add @blksword/dsh-flowus@0.1.1

从 GitHub 安装

仓库为公开仓库，可不经 registry 直接安装：

dsh plugin --profile web add github:BlkSword/dsh-flowus

该路径已完成端到端验证：pnpm 可解析 git 依赖，bundle 条目写入 dsh.profile.bundles，加载器完成组合与导入（dsh --profile <名称> --dump-config 与 --dump-config-schema 均通过）。如需可复现的安装，可使用 github:BlkSword/dsh-flowus#<commit-sha> 指定提交；后续通过 dsh plugin --profile web update @blksword/dsh-flowus 获取更新。

从本地检出安装

# 1. 打包至 profile 目录
npm pack --pack-destination "$env:USERPROFILE\.dsh\profiles\web"

# 2. 在 profile 目录中安装（使用相对路径）
dsh plugin --profile web add "file:./blksword-dsh-flowus-0.1.1.tgz"

Windows 说明：pnpm 会将 link:D:/...、file:D:/... 形式的绝对路径按相对路径解析，从而生成指向 ...\profiles\web\D:\... 的无效链接。因此应先将 tarball 打包至 profile 目录，再使用上述相对 file: 说明符。

安装后操作

重启 dsh web 并刷新浏览器页面。客户端入口图（window.__DSH_BOOT__）在进程启动时组装，默认配置下 dsh-hmr 的 root: [] 仅保留显式配置监视点，因此新增插件不会热加载进正在运行的进程。重启后可通过 /flowus status 或“设置 → FlowUs”确认加载结果。

兼容性

本版本支持的 DSH 版本为 0.2.0-rc.2、0.2.1-alpha.1、0.2.1-alpha.2，不支持其他版本。peer 依赖与兼容性记录仅声明这三个版本。

peer 依赖声明方式：@deepseek-ai/dsh-* 采用精确版本析取 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2；@deepseek-ai/cordis 与 @deepseek-ai/schemastery 采用成对范围 ~4.0.4 || ~4.0.5-alpha.1 与 ~3.18.4 || ~3.18.5-alpha.1。上述 @deepseek-ai/* 包均由当前 dsh profile 提供，不应另行添加依赖。

该矩阵经实测确认：离线套件与联网冒烟测试分别在三个运行时自带的包上执行，均无失败；插件涉及的具名导出集合在三个版本间完全一致。alpha 版本的范围分支为必需项：预发布版本仅在比较符于同一 major.minor.patch 上带预发布标识时才满足范围，因此 ~4.0.4 不接受 4.0.5-alpha.1，0.2.0-rc.2 亦不接受 0.2.1-alpha.1。

未列入声明的新版本（实测记录）。 @deepseek-ai/dsh@0.2.1-alpha.3 与 alpha.4 已发布，本插件暂不声明支持：

• 宿主半层已在 alpha.3 上实测通过。 在一份完整安装的 alpha.3 运行时（609 个包，peer 闭包齐全）上运行本仓库全部用例：164 项、161 通过、0 失败、3 项联网跳过，与 0.2.0-rc.2 结果一致。该运行时配对的 cordis@4.0.5-alpha.2、schemastery@3.18.5-alpha.2、dsh-tools@0.2.1-alpha.3 均落在现有 ~ 与精确析取范围内，无需修改声明。
• 客户端半层尚未验证。 alpha 线不再把 @deepseek-ai/dsh-client-ui-primitives 作为运行时的依赖包（node_modules\@deepseek-ai 下已无此包），而设置页的 classic script 需要从 shell 的模块表 require 它；alpha.3 的 shell bundle 中仍可见该模块 id，故结论未定。列入支持前，需要在 alpha.3 上真正打开一次设置页确认。
• @deepseek-ai/dsh-atomic-write 已加入 peer 集合（可选）：存在时用于状态文件的原子写与跨进程文件锁。

首次授权

/flowus login

1. 插件在本机 127.0.0.1:42813/callback 建立一次性回调监听；
2. 打开默认浏览器至 FlowUs 授权页；若无法自动打开，命令输出与设置页均会显示完整授权 URL；
3. 用户在 FlowUs 页面确认授权后，浏览器重定向至回调地址；
4. 插件以授权码与 PKCE verifier 换取令牌，随后连接 MCP 服务器、发现工具并完成注册；
5. 命令返回已注册的工具数量。

授权完成后可直接以自然语言向 Agent 提出 FlowUs 相关任务。

命令

设置页

插件通过 settings.section 槽位（id: flowus）向设置面板贡献一个独立页面，用于查看状态并执行授权相关操作：

• 状态指示：未授权、等待浏览器授权、已授权未连接、已连接（含工具数量）四种状态，使用 StateDot 与 Tag 呈现。
• 状态明细：MCP 地址、工具命名空间、凭据文件路径、授权 scope、令牌过期时间、是否包含刷新令牌、上次同步时间、最近错误。
• 操作按钮：登录（未授权时）、重新授权（已授权时）、取消（授权进行中）、重新连接、退出登录、刷新。
• 工具列表：当前注册至模型侧的 mcp__flowus__* 工具及其简述。

页面数据来自宿主路由 GET /flowus/api/status；按钮分别向 /flowus/api/login、/flowus/api/login-cancel、/flowus/api/logout、/flowus/api/reload 发送 POST 请求。全部响应均为同一份状态快照（{ ok, snapshot }），因此单一渲染路径即可覆盖所有操作。

上述路由与 DSH 其他 Web 接口一致，先经由连接服务的信任栅栏（Host/Origin 校验与登录令牌 Cookie）：未认证请求直接返回 401，无法读取状态或触发授权。

授权采用先返回后轮询的方式：POST /flowus/api/login 立即返回，浏览器授权在后台执行（上限为 loginTimeoutMs）；页面在等待期间每 1.5 秒刷新一次状态，因此不会长时间占用 HTTP 请求。

配置

配置通过 profile 补丁层覆盖（$DSH_HOME/profiles/web/cordis.patch.yml）：

- id: flowus
  config:
    callbackPort: 42813
    toolCallTimeoutMs: 60000

凭据与安全

• 凭据文件位于 %DSH_HOME%\flowus\oauth.json（默认 C:\Users\<用户名>\.dsh\flowus\oauth.json），内容包括动态注册的 client_id、令牌集合、PKCE verifier 与 discovery 缓存。写入优先使用宿主提供的 @deepseek-ai/dsh-atomic-write（随机后缀 + wx 独占创建 + rename，并以文件锁串行化跨进程的读-改-写；该 peer 声明为可选，缺失时回退到等价的本地实现），权限按平台能力设置为 0600。登出会顺带清理残留的 <file>.*.tmp 与 <file>.corrupt。
• 客户端类型为 public client：token_endpoint_auth_method = "none"，配合 PKCE S256，不存在 client secret；刷新令牌是唯一的长期凭据。
• logout 仅清除令牌与 verifier，保留动态客户端注册。注册端点限流较严格（实测响应头 X-RateLimit-Limit: 3），复用注册可避免重复登录时触发限流。
• 涉及的网络端点：mcp.flowus.cn（资源元数据与 MCP 数据面）、api.flowus.cn（授权、令牌、注册）。
• 撤销授权：先在 FlowUs 侧撤销该应用授权，再于本地执行 /flowus logout。

实现

/flowus login
  ├─ 建立 127.0.0.1:42813/callback 一次性监听（先生成 state）
  ├─ auth(provider, { serverUrl, scope })          ← 由 MCP SDK 驱动
  │    ├─ RFC 9728 发现  /.well-known/oauth-protected-resource
  │    ├─ RFC 8414 发现  /.well-known/oauth-authorization-server
  │    ├─ 无注册信息时执行 RFC 7591 动态客户端注册（loopback redirect + native）
  │    └─ 生成 PKCE(S256) 授权 URL → redirectToAuthorization → 打开浏览器
  ├─ 浏览器授权 → 回调携带 ?code&state（state 不匹配则拒绝）
  ├─ auth(provider, { serverUrl, authorizationCode, iss })
  │    └─ 换取令牌（access + refresh）并持久化
  └─ MCP initialize → tools/list → 逐项注册为 DSH 工具（mcp__flowus__*）

• 令牌续期。 运行时收到 401 时，SDK 使用刷新令牌续期并重试一次；仍失败则以“需要重新授权”的明确错误报告。插件记录令牌的获取时间与有效期，在连接前若判定已过期即先行刷新，以避免首次请求即返回 401。
• 工具列表变更。 MCP 的 notifications/tools/list_changed 触发重新同步：插件接管新列表并以整代替换重新注册，失败时保留上一代。
• 会话自愈。 服务器遗忘会话时（JSON-RPC -32001，或会话端点 404），插件自动重连一次、重新注册工具列表并重放当前调用，无需人工执行 /flowus reload。
• 瞬时故障退避。 mcp.flowus.cn 前面的 nginx 会给出秒级的 503 窗口（实测：所有 MCP 端点同时 503，8 秒后恢复正常）。这类网关拒绝会以指数退避 + 抖动重放（最多 3 次，500ms 起、8s 封顶）；可能已被处理的模糊失败（500/429/连接重置）只对只读工具重放，写操作永不因插件自身重试而重复执行。同步失败后还会自动补试（5s / 15s / 60s），与 DSH 自带 MCP 桥的重连行为一致。
• 错误脱敏。 SDK 会把响应正文整段塞进错误信息，因此对外（状态快照、设置页、/flowus status、模型看到的工具错误）只给出一句短文本：已知状态码转成人话、剥掉标记、压掉空白并截断到 200 字符，网关 HTML 原文只进日志。快照另带 lastErrorKind，设置页与 /flowus status 会标明「暂时性，插件会自动重试」。
• 结果上界与调用卡片。 单个结果转发给模型前按 maxResultChars 截断：保留首尾并注明省略了多少字符，结构化内容同样受限，超大内联负载（base64 图片/blob）在保存的原始块中以大小占位。每个工具还提供调用卡片：kind 区分读取/搜索与写入，标题给出本次调用的对象。
• 调用串行化。 FlowUs 服务端限制同一 MCP 会话同时仅允许一个工具调用（并发调用返回 JSON-RPC -32002）。插件在会话内以串行队列执行调用，并对并发拒绝执行有限次退避重试，因此模型并行发起多个只读调用不会失败（验证结果：5 个并发调用全部成功）。
• 命名冲突。 若 mcp__flowus__* 已被其他插件占用，则该次同步整体拒绝，不产生部分发布。
• 回调校验。 回调监听只接受 GET，并要求唯一且匹配的 state（常量时间比较）；不满足者只作答、不结束登录，因此本机任意进程或页面无法取消进行中的授权。监听地址强制为 loopback（RFC 8252 §7.3），帮助页回显的服务器文本经转义并截断。
• 凭据绑定。 存储的凭据记录其所属资源 URL；当配置的 serverUrl 指向另一资源时，插件拒绝出示令牌并提示重新授权，而不会把 FlowUs 令牌发给第三方端点。
• 设置页实现。 宿主侧通过 ctx.webServer.register 注册 /flowus/api/*；客户端侧为 window.__ModuleLoader__ 形式的 classic script（lib/client.js，无需构建步骤），注册至 settings.section 槽位；两侧通过 fetch 与 JSON 快照通信，未引入自定义 RPC 协议。

开发与测试

本地开发从锁文件安装，再把一份 DSH 运行时链接进来（node_modules 不入库）：

npm ci --ignore-scripts --legacy-peer-deps                    # 按锁文件安装（含 typescript / @types/node）
npm install --no-save --no-package-lock --ignore-scripts --legacy-peer-deps @deepseek-ai/dsh@0.2.0-rc.2
npm run link-runtime                                          # 逐包软链到上面这份运行时

npm run check                                                 # 类型检查 + 离线套件：180 项用例，177 项通过，3 项联网用例跳过
npm audit                                                     # 有锁文件后才能审计依赖
$env:DSH_FLOWUS_LIVE=1; node --test tests/flowus-live.test.js  # 联网冒烟：3 项

链接方式与顺序。 scripts/link-runtime-packages.mjs 为每个 @deepseek-ai/* 包各建一条软链（Windows 用 junction），而不是把整个 scope 目录链成一个。实测差别：npm install 会删掉逐包软链本身、但保留其指向的真实包；整目录 junction 则会让 npm 穿过链接删掉运行时里的包（本仓库被这样毁过一次）。顺序上仍是先跑完所有 npm 命令、再链接；链接之后任何 npm/pnpm 命令都要重跑 npm run link-runtime。

测试构成：

源码修改后的本地分发方式：

npm pack --pack-destination "$env:USERPROFILE\.dsh\profiles\web"
dsh plugin --profile web add "file:./blksword-dsh-flowus-0.1.1.tgz"

正式发布参见“发布”。

在另一运行时上验证

测试通过 node_modules\@deepseek-ai 这一 junction 解析 @deepseek-ai/*。更换运行时进行验证时，将该 junction 指向目标版本的包目录，并在仓库副本上重新执行 node --test 与联网冒烟测试。两个版本差异需注意：

• 依赖布局。 0.2.0-rc.2 将依赖嵌套于 <dsh>\node_modules\@deepseek-ai\...；0.2.1-alpha.1 与 0.2.1-alpha.2 则提升至 <runtime>\node_modules\@deepseek-ai\...，不存在嵌套目录。任何假定 rc.2 布局的脚本均需增加回退逻辑。
• ./invariant 子路径已移除。 @deepseek-ai/dsh-tools/invariant、dsh-commands/invariant、dsh-system-prompt/invariant（及其 lib/invariant.js）在 0.2.0-rc.2 中存在，自 0.2.1-alpha.1 起被移除。本插件仅从包根导入，不应新增此类深层路径引用。

发布

npm login                      # 每台机器执行一次；@blksword scope 须属于该账号
npm publish --access public    # prepublishOnly 会先执行离线测试
npm view @blksword/dsh-flowus version

# 对发布产物执行端到端校验
dsh plugin --profile web remove @blksword/dsh-flowus
dsh plugin --profile web add @blksword/dsh-flowus@latest

dsh plugin add 是唯一受支持的安装路径：加载器从 profile 的 node_modules 解析该包，客户端半由包内 exports["./client"] 提供。

故障排查

已知限制

• 图片、音频等富内容块不内联渲染，以占位文本呈现。FlowUs 的工具以文本与 JSON 为主。
• 不支持 MCP 任务扩展：execution.taskSupport === "required" 的工具将被跳过，并在日志中说明原因。
• 不注册 MCP resources 与 prompts；本插件的范围为工具、命令与设置页。
• 设置页仅提供状态展示与授权、连接操作，不提供按工具粒度的启用开关；工具可见性目前仅受 maxTools 上限与命名冲突保护约束。
• 首次授权必须由用户在浏览器中确认，这是 OAuth 授权码流程的固有要求。

目录结构

dsh-flowus/
├─ cordis.patch.yml      # bundle 层：插入 flowus 插件行与默认配置
├─ package.json          # dsh.bundle.patch / dsh.client / peer 依赖 / 发布白名单
├─ icon.svg
├─ locale/               # 插件列表中的显示名与简介（en/zh）
│  ├─ en.json
│  └─ zh.json
├─ lib/
│  ├─ index.js           # 插件入口：Config、apply、工具发布、/flowus 命令、提示词段落、设置页路由
│  ├─ http-api.js        # 设置页宿主 JSON API（/flowus/api/*，经连接信任栅栏）
│  ├─ client.js          # 浏览器半：__ModuleLoader__ bundle，注册设置页
│  ├─ login.js           # 两段式授权码流程编排
│  ├─ oauth-provider.js  # SDK 的 OAuthClientProvider 实现与令牌摘要、过期判断
│  ├─ callback-server.js # 一次性 loopback 回调监听
│  ├─ browser.js         # 不依赖 shell 的浏览器启动（含 Windows 候选回退）
│  ├─ mcp-session.js     # MCP 会话：连接、发现、调用与结果归一化
│  ├─ tool-bridge.js     # MCP JSON Schema 至 DSH defineTool 定义的转换
│  ├─ tool-names.js      # mcp__<server>__<raw> 命名契约
│  ├─ command-grammar.js # /flowus 语法解析
│  └─ store.js           # 私有状态文件（原子写入、串行化）
└─ tests/                # 离线测试与可选联网冒烟测试

许可证

Apache-2.0，详见 LICENSE。