看板娘 KanbanNiang

Tauri 2 + Live2D 桌面看板娘，内置 MCP 服务（Streamable HTTP）。 Agent 通过 11 个 MCP 工具操作她的动作、表情、台词、窗口位置与模型；本仓库同时是一个 DSH 插件包，安装后 DSH 启动时自动拉起看板娘，并把工具注入为 mcp__kanbanniang__*。

In English: a Tauri 2 + Live2D desktop mascot with a built-in MCP server (11 tools, Streamable HTTP). It is also packaged as a DSH (DeepSeek Harness) plugin: DSH auto-launches the mascot and exposes mcp__kanbanniang__* tools to any MCP client.

给其他人的一键安装（DSH 插件）

git clone https://github.com/Evil-Wideplain/kanbanniang.git && cd kanbanniang && npm install && npm run plugin:install

前置：DSH 桌面端 0.2.x、Node 18+、Rust 工具链已就绪。该命令会构建应用、编译宿主插件并注册到 DSH desktop profile；手动步骤与验证见下文「快速开始」与「作为 DSH 插件安装」。

特性

Related MCP server: Persona Motion Studio

架构

DSH（插件系统 + MCP 客户端）          Claude Desktop / Inspector / 自研脚本
      │ Streamable HTTP                       │ Streamable HTTP
      ▼                                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│ 看板娘进程（Tauri 2 / Rust，127.0.0.1:7432）                          │
│ axum：POST /mcp · GET /health（Streamable HTTP 唯一传输）              │
│ JSON-RPC 2.0 路由 → 工具清单 src/mcp/tools.json → tools/call           │
└───────────────────────────────┬─────────────────────────────────────┘
                                │ Tauri 事件 mascot:action
                                ▼
┌─────────────────────────────────────────────────────────────────────┐
│ WebView 前端（TypeScript + pixi.js + pixi-live2d-display）            │
│ dispatcher → Live2D 控制器 → 动作 / 表情 / 气泡                        │
│ 需回传结果的工具经 mascot:result 事件返回（oneshot，5s 超时）          │
└─────────────────────────────────────────────────────────────────────┘

• 传输：单端点 POST /mcp。initialize 的 protocolVersion 按客户端请求回显，受支持版本为 2025-06-18 / 2025-03-26 / 2024-11-05；未声明或未知版本回退 2025-06-18。旧版 HTTP+SSE 的 /mcp/sse 已下线。

• 动作链路：tools/call → Rust 发射 Tauri 事件 mascot:action → 前端 dispatcher 驱动 Live2D 控制器执行。

• 查询链路：src/mcp/tools.json 中 query: true 的工具（play_motion、set_expression、move、list_motions、list_expressions、get_status、set_model、list_models）由前端经 mascot:result 回传，Rust 侧 oneshot 等待 5s；speak、move_in_window、set_idle 发射后直接返回。

• 导入链路：拖放到角色 → Tauri 原生拖放事件 → Rust 解析 *.model3.json 并落盘到应用数据目录 → 前端注册运行时档案并热切换；模型资源经只读协议 mascot-model:// 提供给 WebView（Windows 上为 http://mascot-model.localhost/...）。

• DSH 链路：DSH 启动 → 宿主插件读设置解析端点、探活 /health、未运行则拉起 exe → 官方 MCP 客户端连同一端点 → 工具注入会话。

前置依赖

Cubism Core 运行时 live2dcubismcore.min.js（6.0.1，支持 Cubism 3–5.3 / moc3 v1–v6）已内置于 src/frontend/mascot/render/live2d/ 并随仓库提交，无需手动获取。

快速开始

# 1. 安装依赖
npm install

# 2. 准备模型（任选其一，详见 models/README.md）
#    a) 构建期静态资源：把模型目录放进 models/<模型名>/
#    b) 运行时导入：先跳过本步，启动应用后把 .zip 或模型文件夹拖到角色身上

# 3. 启动桌面应用（Vite + 编译 Rust + 打开看板娘窗口）
npm run tauri:dev

# 4. 另开终端验证 MCP 链路（需应用已启动）
node cmd/client/test-streamable.mjs

冒烟脚本按顺序覆盖：/health → initialize（校验协议与 Mcp-Session-Id）→ notifications/initialized → tools/list（≥ 11 个工具）→ get_status → speak → play_motion。执行时应看到看板娘显示气泡并播放两个动作，终端逐项打印 ✅。

作为 DSH 插件安装

前置：DSH 桌面端 0.2.x 已启动过一次（完成 profile 初始化），本机已具备 Rust 工具链。

npm install
npm run plugin:install               # 构建应用本体 + 编译插件宿主半侧 + 注册到 desktop profile
npm run plugin:install -- --no-build # 跳过构建，沿用 target/release 现有产物

脚本调用桌面端自带的 dsh.cmd（resources/runtime/cli/bin/dsh.cmd）执行 plugin --profile desktop add link:<仓库绝对路径>；PATH 上的 npm dsh 会拒绝操作 desktop profile。找不到桌面端 CLI 时退化为直接修改 profile 清单，并打印需要手工执行的 pnpm 安装命令。

它做了什么

1. package.json 的 dsh.bundle.patch 指向 cordis.patch.yml，安装后自动成为一层 bundle；

2. cordis.patch.yml 按顺序插入两行插件：

   • kanbanniang 宿主插件（src/plugin/ → lib/host.js）：从看板娘 settings.json 的 mcpEnabled / mcpPort 推导 MCP 端点（默认 7432），发布 mascotStartup 服务；探测 /health，未运行则拉起 target/release/kanbanniang.exe（缺省回退 target/debug/），就绪后再用 MCP get_status 做一次前端链路探活；

   • @deepseek-ai/dsh-mcp-client：inject: [mascotStartup]，以 streamable-http 连接同一端点，把工具注册为 mcp__kanbanniang__<tool>。

插件以 link: 方式安装，运行时直接拉起仓库里的 target/release 产物，不打包、不复制 exe，因此安装脚本会先执行 tauri build --no-bundle。不要用 cargo build --release 代替：那样编出的二进制带 cfg(dev)，前端走 devUrl，DSH 拉起后是白屏且查询超时。

安装后验证

• 完全退出并重启 DSH，新建会话，工具列表应出现 mcp__kanbanniang__get_status / speak / play_motion 等；

• 对模型说「让看板娘挥挥手，并说欢迎回来」，应看到动作与气泡；

• 宿主插件日志：<DSH_HOME>/kanbanniang/plugin.log（Windows 默认 %USERPROFILE%\.dsh）。

配置

图形界面安装（等价）：DSH 侧栏「插件」→「安装第三方插件」→ 填本仓库绝对路径 → 安装并启用。

卸载

npm run plugin:uninstall   # dsh plugin --profile desktop remove kanbanniang

安装/卸载后需完全退出并重启 DSH 生效；看板娘应用与仓库文件不受影响，仍可直接运行 target/release/kanbanniang.exe。

DSH 插件市场

现状：不能直接从 DSH 插件市场安装，请使用上一节的本地 link: 安装。 结论是「协议与工具链层面支持，本仓库打包形态尚不支持」：

• 机制本身可用（DSH 0.2.1-rc.3 实测）：可选组合包 @deepseek-ai/dsh-experimental-plugin-market-bundle 提供「发现」页；索引格式 1 有随装校验器；安装 spec 由 marketInstallTarget 生成（npm 为 name@version，git 为 git+<url>#<commit>），交给 pluginManager.installBundle。

• 入口缺失：lib/（宿主插件编译产物）在 .gitignore 中，git 形态的包没有 main 入口；改用安装期 prepare 构建也走不通——pnpm 会拦截 git 依赖的构建脚本，要求精确到 包名@git+url#commit 的 allowBuilds key，而市场安装的授权只记录包名。

• 应用 exe 缺失：安装目录里没有 target/release/kanbanniang.exe；宿主插件的 findRepoRoot() 要求包内同时存在 package.json 与 src/tauri/Cargo.toml，但 pnpm 按 files 打包，src/ 与 target/ 都不会进包，实测 plugin.log 报「未找到看板娘可执行文件」。

• 没有 npm 版本：package.json 为 private: true，且这是含 Rust 源码的应用仓库，市场只能走 git source；DSH 目前也没有官方市场，索引源需自建自托管、由用户手动添加。

• 模型不入库：市场安装无法附带 Live2D 模型，用户仍需自备并拖拽导入。

完整的验证过程（索引校验、隔离 profile 实测、plugin.log 证据）、阻塞项清单与上架前启用清单见 docs/market-distribution.md。在补齐这些之前，请使用本地安装方式。

让 Agent 接入（MCP 客户端）

端点：http://127.0.0.1:7432/mcp（Streamable HTTP，唯一传输）。 端口可在看板娘设置页修改；旧版 HTTP+SSE（2024-11-05）的 /mcp/sse 已下线。

• DSH：按上一节安装插件，无需手工配置。

• Claude Desktop / 其他客户端：编辑客户端的 MCP 配置（Claude Desktop 为 claude_desktop_config.json，位置见其文档），重启客户端后确认 kanbanniang 已连接：

{
  "mcpServers": {
    "kanbanniang": {
      "url": "http://127.0.0.1:7432/mcp"
    }
  }
}

• 可视化调试：官方 @modelcontextprotocol/inspector，填入上述 URL 即可。

• 仅支持旧版 HTTP+SSE 的客户端需先升级（Claude Desktop、DSH 及现代客户端均已支持 Streamable HTTP）。

工具清单（MCP）

工具定义的单一来源是 src/mcp/tools.json（Rust 与 TS 同源加载），本表为文档镜像，冲突以清单为准。可用动作名与表情名取决于模型自带文件，先调 list_motions / list_expressions 查询。

接入真实 Live2D

方式 A：拖拽导入（不写入仓库）

把 .zip 压缩包或解压后的模型文件夹拖到角色身上，松开即导入：解析 moc / 贴图 / 动作组 / 表情，校验必需文件存在后复制到 <app_data_dir>/models/imported-<名字>/（Windows 一般在 %APPDATA% 下）。同名模型重复导入整体覆盖；不同名模型 id 撞车时分配 -2 保留，不会互相删除。导入成功后立即热切换，并出现在设置页芯片与 list_models 中（id 形如 imported-haru）。移除：退出应用后删除对应目录。

方式 B：构建期静态资源（可随仓库分发，但模型目录不入库）

1. 把模型目录放到 models/<模型名>/（含 *.model3.json 及 motions/、expressions/ 等）；

2. models/ 经 Vite publicDir 作为静态资源根，models/Haru/… 会以 /Haru/… 提供；

3. npm run dev / npm run build 前由 scripts/gen-models.mjs 自动扫描并生成模型清单，无需手工登记；

4. 需要展示名、缩放 / 锚点或语义别名时，编辑 src/frontend/shared/domain/profiles.ts 的 MODEL_OVERRIDES（键为 models/ 下的目录名）。

语义别名：不同模型的动作 / 表情命名不一致（官方系多为 Idle / TapBody，表情可能是 F01 起）。档案可为 idle、speak、neutral、happy 等语义名配置映射，Agent 即可用同一套调用名操作任意模型。批量发现与命名可运行 node cmd/client/preview.mjs（需应用已启动），逐个播放并让你在终端标注。

运行时切换：list_models 查档案 → set_model 热切换；切换会重置表情与位置（跨模型名称不同），同 id 重复切换返回 {ok:true, unchanged:true}。完整说明（含排查）见 models/README.md。

目录结构

pet/
├─ src/
│  ├─ frontend/           前端（TS + Vite）
│  │  ├─ app/             三个窗口入口与组合根
│  │  ├─ shared/          领域契约 / IPC / 表现工具
│  │  ├─ mascot/          看板娘域：dispatcher、模型热切换、Live2D 渲染、气泡、拖放浮层
│  │  ├─ settings/        设置页
│  │  ├─ debug/           MCP 调试面板（仅开发构建）
│  │  └─ styles/
│  ├─ plugin/             DSH 宿主插件半侧（TS → lib/）
│  ├─ mcp/tools.json      MCP 工具清单（单一来源）
│  └─ tauri/              Rust 后端：Tauri 装配、axum MCP 服务、模型导入
├─ cmd/client/            MCP 客户端与脚本：client.mjs / test-streamable.mjs / preview.mjs
├─ scripts/               gen-models.mjs（构建前扫描模型）、install-dsh-plugin.mjs（安装到 DSH）
├─ models/                静态资源根；模型目录不入库，接入文档见 models/README.md
├─ assets/icon.png        插件管理页图标
├─ docs/                  补充文档（如 market-distribution.md）
├─ .github/workflows/     CI
├─ .agents/skills/        内置开发规约（按需加载）
├─ cordis.patch.yml       DSH bundle patch：宿主插件 + MCP 客户端两行
├─ Makefile               常用命令入口
├─ package.json           前端依赖、脚本与 DSH 插件元数据
├─ AGENTS.md              Agent 开发入口与硬性规则
├─ LICENSE                MIT
├─ .gitattributes / .gitignore
└─ README.md

开发与验证

提交前至少执行 make verify；改动协议、工具清单或动作后补跑冒烟测试；改动 DSH 装配后用非 desktop profile（如复制 web 模板）验证层叠与端到端工具调用。

CI（GitHub Actions，.github/workflows/ci.yml）在 windows-latest 上跑同一组门禁：前端 npm ci → npm run build → npm run test → npm run test:plugin，Rust 侧 cargo fmt --check + cargo clippy --all-targets -- -D warnings（先构建 dist/，不跑 tauri build）。

GNU 工具链 + MSYS / Git Bash 下若 make lint 报 windres Unable to create temp file，是该 shell 把 TEMP 置为 /tmp 导致资源编译找不到合法临时目录：改用 PowerShell / cmd 运行，或先把 TEMP、TMP 设为 Windows 路径（如 C:\...\Temp）；make check / make unit 不受影响。

编码规约、分层约束与完整检查清单见 AGENTS.md 与 .agents/skills/，本 README 不重复搬运。

常见问题

已知限制

• 无鉴权：MCP 服务仅监听 127.0.0.1，未做 token / 证书，请勿直接暴露到公网。

• 平台：Windows 为主要验证平台；macOS / Linux 的自动拉起路径（可执行文件名）未适配。

• 口型：speak 仅显示气泡并做表情反馈，真实口型同步需接入 AudioEngine + Phoneme。

• 前端依赖：查询型工具要求前端在线，窗口关闭即 5s 超时。

• 模型：models/*/ 不入库，需自备模型并遵守各自许可；Cubism 2 的 .model.json 会被拒绝。

• 市场分发：DSH 市场机制本身可用，但当前打包形态（lib/ 不入库、包内无 exe）装完起不来，只能本地安装；详见「DSH 插件市场」与 docs/market-distribution.md。

• 鼠标穿透：按角色像素命中动态开关，空白区域收不到任何鼠标消息；前端有 fail-safe（交互层停止、光标源失效、穿透态 1s 无采样主动恢复可交互），不会卡死。

• 窗口适配：启动时按当前显示器工作区收缩窗口（只收缩不放大）；角色缩放以 360×480 设计基准计算，窗口变小只是减少四周留白，不改变角色像素尺寸。

贡献与致谢

• 提交前跑 make verify；commit message 遵循 Conventional Commits（type(scope): 中文 subject），细则见 .agents/skills/commit。

• 文档分工：README 面向使用者，AGENTS.md 与 .agents/skills/ 面向开发规约；补充文档放 docs/。

• 致谢：Tauri、axum、Live2D Cubism SDK、pixi-live2d-display、pixi.js、Model Context Protocol、DeepSeek Harness。

• 仓库不附带模型；演示用的示例模型来自 Live2D Cubism SDK（遵循 Live2D 开放许可），商用请自行确认授权。

License

MIT