dsh-ai-passport-plugin

维护状态: 活跃

slinxiaosun-blip/dsh-ai-passport-plugin

DSH 插件：把 AI Passport 变成 DeepSeek Harness 的随身任务终端（蓝牙链路、任务桥接、语音识别、桌面挂件）

前往 GitHub 项目主页

$ dsh plugin add dsh-ai-passport-plugin

安装

dsh 没有统一的安装命令——把该插件 README 中的配置行加入你的 profile/patch 配置，然后重启即可。

了解安装方式

星标

Fork

JavaScript

语言

MIT

许可证

2026-10-07

创建于

2026-10-31

README

DSH AI Passport

把 FoloToy AI Passport（ESP32-C3 掌上设备）做成 DeepSeek Harness（DSH）的随身任务终端：

在设备上新建/选择 DSH 任务、看执行状态、收完成提醒、做任务审批、查 DeepSeek 余额、用语音下指令。设备与电脑（macOS / Windows 的 DSH 客户端）之间走 BLE 蓝牙无线联机，无需 Wi-Fi。

┌─ AI Passport（设备） ─┐   BLE 5（GATT，自定义帧 + JSON）   ┌─ Mac/Win + DSH ───┐
│  ESP32-C3 固件        │ ◄──────────────────────────────► │  本插件（npm 包）   │
│  app_*.c / LVGL UI   │      协议 v1 · 双端常量同步        │  ble/bridge/panel  │
└──────────────────────┘                                   └───────────────────┘

双仓库结构

本项目拆成两个 git 仓库，各自独立构建与发版：

仓库	内容	地址
本仓库（挂件端）	DSH 插件（npm 包）+ 跨端文档 `docs/` + 主机侧工具	`dsh-ai-passport-plugin`
固件仓库（设备端）	`app_*.c` 固件源码，独立仓库，基于上游二次开发	`ai-passport-dsh`

开发时固件 clone 到本目录的 vendor/ai-passport（已被 .gitignore 排除）：

git clone -b feature/dsh-passport \
  https://github.com/slinxiaosun-blip/ai-passport-dsh.git vendor/ai-passport

固件的环境、编译、烧录见 docs/03-构建与烧录.md。

不打算自己编译固件的话，直接从 Releases 下载 FoloToy-AI-Passport-full.bin，从 0x0 一次性刷入即可。

功能

能力	说明
任务台	设备上浏览/新建 DSH 任务，实时 step 与工具名推送
完成提醒	横幅 + 提示音 + 未读点，成功/失败/中断区分
任务审批	`approval/request` 瀑布拦截，设备端允许/拒绝（高风险工具默认停在拒绝）
配对	6 位配对码（每次上电换），NVS 密钥 + 常量时间比较 + 限流
DeepSeek 余额	大字显示，取不到时明确报错，不显示伪造的 0
语音输入	设备录音 → BLE 上行 ADPCM → 本地 SenseVoice 离线识别 → 回填输入框。单次最长 30 秒
桌面挂件	DSH 输入框旁的连接状态挂件 + 180px 浮层（`lib/client.js`）
Web 面板	本地控制面板（回环限定 + SSE 实时推送）

语音输入的时长限制

项	值	说明
单次录音上限	30 秒	说到 30 秒设备自动结束，不需要松手，随后送去识别
录音结束条件	仅两个	「松开按键」或「触达 30 秒上限」
说话中途停顿	不会被切断	没有"静音自动结束"；停顿、思考、句间留白原样录进去
主机侧转写上限	默认 30 秒	`voice.maxSeconds`，只能调短：超限截断尾部再识别，不丢弃整段录音
低于 0.5 秒	丢弃	按压误碰，不进识别、也不报错

要点：

上限 30 秒是硬限制，写在固件里（AP_AUDIO_MAX_SECONDS）。想调大得改固件重新编译烧录；插件侧的 voice.maxSeconds 调大不会让设备录更久。
说不到上限就松手 = 按实际时长结束，说满 30 秒会自动停。两种都正常识别。
需要说更长的内容：分几次按着说，识别结果逐条进输入框；或在电脑端直接打字。
设备说话时中途停顿不会被切断，可以自然停顿后再继续。

固件 1.2.0 起上限由 15 秒放宽到 30 秒，并取消了那之前的"静音 1.2 秒自动结束"。若你的插件低于 1.2.0，超过 10 秒的录音会静默失败（设备自己停了但不出结果也不报错），详见 docs/02 的 2026-10-10 返工记录。

快速开始

前置：DSH 桌面版（macOS 或 Windows）、Node ≥ 20。BLE 走 noble 原生后端： macOS 限 Apple Silicon；Windows 需 Windows 10 1703+（x64，noble 有 win32-x64 预编译； ARM64 需源码编译，见 docs/08）。

# 0) clone 本仓库（固件不需要时可不 clone）
git clone https://github.com/slinxiaosun-blip/dsh-ai-passport-plugin.git
cd dsh-ai-passport-plugin

# 1) 安装依赖
npm install

# 2) 把插件装进 DSH profile（macOS / Windows 同一命令；链接方式，源码即生效代码）
npm run install-plugin                 # 默认 desktop
npm run install-plugin -- web desktop  # 可指定多个 profile

# 3) 无硬件联调（虚拟设备会应答握手、心跳、任务列表、余额）
npm test

Windows 也可用等价入口：powershell -ExecutionPolicy Bypass -File tools\install-plugin-to-dsh.ps1。

脚本对每个 profile 做 node_modules/dsh-ai-passport -> 本仓库源码 的链接（macOS 用符号链接；Windows 用目录 junction，无需管理员权限；被机器策略禁止时自动降级为复制并明确提示），改源码即时生效。desktop profile 由 Electron 独占管理（dsh plugin CLI 拒绝操作），因此不走 CLI，手工链接是唯一可靠的开发安装方式。

装好后打开控制面板（DSH 内置 webserver）：

http://127.0.0.1:19387/dsh-passport

常用配置（DSH 设置界面或 cordis.patch.yml）：

配置	默认	说明
`transport`	`bridge`	`bridge`（子进程）/ `mock`（无硬件联调）/ `noble`（进程内）
`autoConnect`	`true`	插件加载后自动扫描连接
`tasks.maskTitles`	`false`	设备上只显示"任务 xxxx"，适合公共场合
`voice.directSend`	`true`	设备识别结果卡「双击确定」= 整段替换草稿并发送
`voice.maxSeconds`	`30`	单次转写长度上限（秒），超限截断；固件端自律同样是 30s

完整配置表与语音识别（SenseVoice 本地模型）启用方式见 docs/03-构建与烧录.md 与 docs/04-桌面客户端集成.md。

版本与兼容性

当前实测环境（2026-10-31）：

组件	版本	说明
DSH 桌面版	`0.2.1-rc.5`	插件 API 基线，开发时以它为准；macOS 与 Windows 同一份插件代码
dsh CLI	`0.2.0-rc.2`	`dsh --version` 实测；`@deepseek-ai/dsh` 全局安装
dsh-tui	launcher `0.14.0` / profile `0.17.0`	`dsh-tui --version` 实测，profile 目录 `~/.dsh/profiles/dsh-tui`
插件（本仓）	`1.3.1`	`packages/dsh-ai-passport/package.json`
设备固件	`1.3.1` + git 短哈希	固件仓 `version.txt`，构建期自动追加 `git describe`
BLE 协议	`v1`	双端常量 `PROTOCOL_VERSION` ↔ `AP_PROTOCOL_VERSION`，取较小值运行
固件基线	`main @ 0b9e4c8`	上游 FoloToy/ai-passport
Node	≥ 20	开发机 `v22.22.2`；桌面版自带 Node（`Contents/Resources/runtime/bin/node`，版本随 App 走）
操作系统	macOS（Apple Silicon）/ Windows 10 1703+	BLE 后端：CoreBluetooth / WinRT（noble）；固件一次烧录两端通用

版本记录：

1.3.1 —— 状态卡重排 + 计时放大：按用户要求"信息居中"，状态灯与 40px 状态大字改为一个横排容器整组水平居中（大字宽度随状态词变，灯跟着一起挪），提示行同一条中线居中；运行计时另起一档 28px 数字字体（只含 0-9 与 :），从 16px 放大到 28px 后跨小时的 10:23:45 实宽 107px，仍然一份字号走到底。纵向坐标由"块高 98 在计时下沿居中"算出，不再三处硬编码。顺带修掉销毁时漏清 s_timer_text / s_clock_text 两个指针（会让 if (!ptr) return 的判空失效）。固件 1.3.1 同步，协议 v1 不变。
1.3.0 —— 状态条字号统一：应用名/时间/电量原先 16px 与 8px 混排，用户反馈「大小不统一、没对齐」，现四者同为 16px 思源黑体、同一条基线（时间与电量改用比例字体后仍放得下完整文案）。同时状态卡里的运行计时跑过 1 小时不再降成 8px。固件 1.3.0 同步，协议 v1 不变。
1.2.0 —— 修复长录音静默失败：任何超过 10 秒的录音都会在设备自动停止后 "什么也不出"且无任何报错（主机侧会话存活期窗口写死 10s，短于录音上限）；现改为由录音上限派生。同时让 voice.maxSeconds 真正生效（此前是死配置），超限截断而非丢弃。配合固件 1.2.1（录音上限 30s、取消静音自动结束）。
1.1.0 —— 插件安装与运行自动适配 macOS / Windows 两个 DSH 客户端（安装器 junction/symlink 自适应、桥进程 Node 探测平台化、报错指引分平台）；设备固件行为不变、一次烧录两端通用，1.1.0 仅是版本对齐。
1.0.0 —— 阶段 A/B/C 全功能首个版本（任务台/审批/余额/语音/配对）。

设备固件见 ai-passport-dsh releases： 1.3.1（状态卡改为信息居中、运行计时放大到 28px；含 1.3.0 的状态条四元素统一 16px 思源）。协议 v1 未变，固件与插件可独立升级。

插件依赖 DSH 0.2.x 的 ctx.webServer / speechToText / deepseekAccount 等宿主 API（实测基线 0.2.1-rc.5）。DSH 升级前先跑 npm test（mock 联调）+ docs/07 真机验收，通过再升级。

目录结构

在 GitHub 阅读完整 README →