dsh-xiaozhi

「旗驭小智AI网关」一键接入 DSH（DeepSeek Harness）的插件。

装上插件后，认证窗口直接弹在 dsh 界面里：未接入时进入 dsh 自动全屏弹出（已接入则不打扰）。用户点一次「钉钉扫码登录」→ 小窗直达钉钉扫码 → 自动跳回 → 插件自动从 xiaozhi-server 拿到 个人 sk- key + 网关地址 + 全部模型 并写入 DSH。一次扫码，零复制零粘贴。

之后每次 DSH 启动自动校验并静默同步模型（用已存的 key 直连网关 /v1/models，不依赖登录态和 Server 在线）。

接入后，dsh 设置页最上面的「小智网关」区块显示当前用户信息（头像/姓名/已注册模型数），可随时「重新接入」；侧边栏官方 logo 与浏览器标签图标会替换为旗驭小智形象（replaceLogo 可关）。

安装与升级（普通用户必读）

务必带版本号安装。 pnpm 11 默认对「发布不满 24 小时」的版本有冷却期（minimumReleaseAge）：不带版本号的安装会静默拿到旧版（旧版可能与你的 dsh 不兼容，设置页会提示「插件宿主服务未挂上」），还会把 ^0.x 范围写进 profile，之后难以自动升级。

# 安装 / 升级 / 修复，一律带版本号（<版本> 换成最新版，见下方「怎么知道最新版是多少」）
dsh plugin --profile <你的profile名> add [email protected]

• 桌面版（Electron App）用户：desktop profile 由 App 独家管理，终端装不进去。请在 dsh 的插件管理页安装，安装框里输入 [email protected]（带版本号）。
• 怎么知道最新版是多少：设置页「旗驭小智Work」区块会显示当前插件版本；最新版以 npm 页面（npmjs.com/package/dsh-xiaozhi）或群里公告为准。
• 发布暗窗：每次发新版后的 24 小时内，裸名 dsh-xiaozhi 拿到的仍是上一版——这期间请始终带版本号安装。
• 报障先核对版本：设置页「插件版本」一行就是当前运行的版本号。

依赖与前提

• xiaozhi-server（xiaozhi-core 仓库的 xiaozhi-work 模块）已部署且可访问，默认 https://ai-work.yqcx.faw.cn（可在设置里改 serverURL）。它提供：

  • GET /oauth/authorize?redirect=...：钉钉扫码登录（direct_sign_in 直跳钉钉）
  • GET /api/work/models（Access-Token 头）：返回 {baseUrl, apiKey, models[]}

• Server 需配置外部回跳白名单（Nacos xiaozhi-work.yaml），插件本地回调才能收到凭证：

  xiaozhi:
    auth:
      allowed-redirect-prefixes:
        - http://127.0.0.1:43117/
        - http://localhost:43117/
  

  对应代码：LogtoOAuthService.normalizeRedirect 放行白名单绝对地址；OAuthController.callback 对外部回跳 302 到 {redirect}#access_token={jwt}（fragment 不落日志）。

• Logto「旗驭小智Work后端」应用的 Redirect URI 需登记 https://ai-work.yqcx.faw.cn/oauth/callback（各环境地址都登记）。

• 网关账号要求（两种模式，服务端决定）：

  • 无感模式（推荐）：服务端配置了令牌池（xiaozhi.gateway.pool.access-token）时，新用户第一次扫码即自动开通——池账号代发专属令牌（名 xz-<Logto sub>），全程无需去网关初始化；
  • 引导模式（兜底）：未配置令牌池时，用户需在 ai-gateway 用钉钉登录过一次（users.oidc_id == Logto sub 映射）且名下有可用令牌（优先名为 xiaozhi）。未初始化时插件会弹「去 AI 网关完成初始化」引导（服务端业务码 4601=账号未初始化 / 4602=名下无令牌，lcdp 包裹为 HTTP 200 + {code, msg}——插件已识别该形态），每个用户只需一次。
  • 用户日后自行登录网关建了个人账号/令牌，服务端自动切回个人令牌与分组。

降级路径

• 弹窗被拦截：登录地址会以链接形式给出，手动打开即可
• 扫码有问题：设置区块/弹窗里可手动粘贴 accessToken（Server /oauth/authorize 不带 redirect 的 JSON 模式）
• Server 未部署：key 直连网关的存量接入不受影响；新接入可临时走网关控制台「个人设置 → 安全 → 访问令牌」的旧路径（插件兼容识别）

使用

安装（本机已装好，写给别人看的）

# 1. 构建
pnpm install && pnpm run build

# 2. 挂进 profile（dev 用 link，发布后用「包名@版本号」，见上方「安装与升级」）
#    ~/.dsh/profiles/web/package.json:
#      dependencies: { "dsh-xiaozhi": "link:/path/to/dsh-xiaozhi-work" }
#      dsh.profile.bundles: [ ..., "dsh-xiaozhi" ]
dsh plugin --profile web install

# 3. 启动 dsh
dsh --profile web

配置

全部配置在 DSH 设置界面的 xiaozhi-connect 命名空间（对应 ~/.dsh/settings.yaml），热生效：

字段	默认	说明
serverURL	https://ai-work.yqcx.faw.cn	xiaozhi-work 服务地址
gatewayBaseURL	https://ai-gateway.yqcx.faw.cn	网关地址（模型直连/健康检查）
providerId	xiaozhi	注册进 llm-pi-ai.providers 的 id
displayName	旗驭小智AI网关	模型列表显示名
apiKeyEnv	XIAOZHI_API_KEY	推理密钥在凭据库里的变量名
jwtEnv	XIAOZHI_JWT	xiaozhi JWT 在凭据库里的变量名
localPort	43117	本机引导页/回调端口（需与 Server 白名单一致）
autoSetDefaultModel	false	接入后是否把默认模型切到本网关
replaceLogo	true	替换官方 logo/favicon 为旗驭小智形象

技术细节

• 双面插件（dual-face）：宿主半边（lib/index.js，node）注册 /api/xiaozhi/* 同源路由（ctx.webServer.register，仅回环）；浏览器半边（lib/client.js）由 dsh 网页经 __ModuleLoader__ 加载，认证弹窗为纯 DOM 实现，settings.section 官方插槽渲染用户信息区块。
• 登录闭环：弹窗 → Server /oauth/authorize（direct_sign_in 直跳钉钉）→ 钉钉扫码 → Server 302 回 http://127.0.0.1:43117/callback#access_token=... → 本地回调页交给 node → Server /api/work/models 换 key+模型 → 写入 DSH。
• 凭证读写走 DSH 正式服务 API：ctx.credentials（.credentials.yaml，0600）与 ctx.settings（settings.yaml，深合并热重载）。JWT 24h 过期只影响模型同步，推理用长期 sk- key。
• 网关连通性自检：启动时用存量 key 直连 /v1/models 验证并刷新模型列表，全程不需要 Server。
• 构建产物自包含（零裸包名运行时依赖），类型来自 vendor-types/dsh.d.ts（从 DSH 0.1.0-rc.6 拷贝的精简声明）。

调试

pnpm run check                     # typecheck + build
dsh --profile web --port 3099      # 起测试实例
curl http://127.0.0.1:43117/       # 独立引导页兜底入口