Skip to content

dsh-xiaozhi

Verified

dsh-xiaozhi · v0.2.1 · MIT · Web UI

旗驭小智AI网关一键接入:浏览器完成钉钉 SSO 登录后,自动开通网关令牌并把全部可用模型注册进 DSH

Install

dsh plugin add dsh-xiaozhi

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Published to npm without a public repository. Inspect the package contents before installing.

Tags

Creators

Readme

dsh-xiaozhi

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

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

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

技能中文名称与调用

技能可在 SKILL.md 中声明中文名称,英文 name 和目录保持稳定:

name: xz-assets-ensure-budget-query
metadata:
  display_name: 资产保障-备件预算查询

市场卡片优先显示 metadata.display_name,没有或为空时显示 name;已安装列表同时支持中英文搜索。 在会话首部输入 /,有中文名的技能在原生候选中以中文标题、英文小字显示,同一技能一行;中文和英文均可搜索。原生选择仍使用英文技能标识;直接输入 /资产保障-备件预算查询 也会映射为英文入口,保留参数和附件。

候选合并适配当前 DSH 的原生技能源结构;宿主结构变化或标签服务不可用时保留原生英文候选,中文搜索源作为兼容回退,不保证其他宿主版本自动支持合并。 中文重名或技能不再可用时阻止调用;项目中的同名技能不会继承另一份全局文件的中文入口。历史消息可能显示发送后的英文入口。 远程市场中文显示依赖桥接返回 display_name,远程中文搜索需服务端配套。只更新本地技能文件、未更新插件时,不会自动生效。

接入后,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 为旗驭小智形象
skillsDir ~/.agents/skills Skill 市场的本地技能目录(发布/安装落点)

Skill 市场(上传 / 分发)

侧边栏「旗驭小智Skill市场」独立面板(sidebar.panellist 席位 + main 主面板页,图标为内联 SVG 随明暗主题自适应):

  • 领域(tag):发布时可打领域标签(可自定义),面板顶部领域卡片 +「+」新建领域(保存即成筛选);领域存于 Nacos labels.tags,桥接内存过滤分页

  • 卡片:市场与本地技能同一套卡片组件(本地仅多 未上传/已发布/市场有新版 状态徽标);3 列网格、上传人(未知兜底「未知用户」)与下载量、搜索、分页(每页 9)

  • 发布:本地技能目录一键发布,或 ZIP 直传(单层文件夹压缩包自动剥壳);发布弹窗填领域/说明,全程全屏 loading

  • 安装/更新/卸载:装进 skillsDir(默认 ~/.agents/skills),来源记 <技能>/.market.json,卸载仅限市场安装的技能

  • 管理员删除:xiaozhi.skill-market.admin-users(userId 白名单)内的用户卡片上直接删市场技能;Nacos 侧为 owner 所有权模型(服务账号上传即可删)

  • 样式沿用 DSH 设计令牌(--dsw-alias-*),明暗主题跟随宿主;发布/安装/删除全程全屏 loading

  • 链路:插件 /api/xiaozhi/skill-market/*(回环)→ xiaozhi-work 桥接 /api/work/skill-market/* (小智 JWT)→ Nacos 3.2 Skill Registry;下载走 9081 匿名注册表(Agent Skills v0.2 协议)

  • 打包/解包零依赖自研(src/zip.ts:deflate+CRC32+zip-slip 防护,确定性打包,中文文件名全程无忧)

  • 当前限制:仅纯文本技能(市场匿名通道不导出含二进制文件的技能,服务端会拦截并提示); 安装/更新后需重启会话生效。设计细节见 doc/skill-market-bridge-api.md。

技术细节

  • 双面插件(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/       # 独立引导页兜底入口

已安装技能的提交与更新

  • 首次显示“提交审核”;提交过即显示“重新提交”,不因审核状态隐藏该入口。提交成功记录保存在插件本机状态中,远程审核记录暂缺时仍保留按钮。
  • “发现”优先读取远程 labels.display_name(兼容桥接已归一化的 display_name),缺失时回退英文 name,不依赖本地是否安装。
  • 上传从 ZIP 中 SKILL.md 提取 metadata.display_name,以 multipart display_name 传给桥接。后端需配套合并写入 Nacos labels 并在列表中透出;仅更新插件不代表远程字段已存储。
  • “重新提交”和“更新”独立显示:前者把本地内容送审,后者用市场版覆盖本地。
  • 更新比较优先读取本地版本,再读取市场安装记录;没有可比较的本地版本时可手动更新,不标记“市场有新版”。
  • 已安装状态使用独立的完整市场目录缓存,不随“发现”页的搜索、领域或分页变化。