DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

slinxiaosun-blip /

slinxiaosun-blip/dsh-ai-passport-plugin

Topic repository only

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

★ 3 Stars2 Forks1 IssuesN/A Community rating0 Confirmed installs
View on GitHubProject homepage
READMESource: main@321e432e

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 ≥ 22(DSH 0.2.2-rc.1 自身要求 ≥ 24.9.0, 桌面版自带该运行时)。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-11-08):

组件 版本 说明
DSH 桌面版 0.2.2-rc.1 插件 API 基线,开发时以它为准;0.2.1-rc.5 亦兼容(两版 tools.register 都强制要求 output)
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.4.0 packages/dsh-ai-passport/package.json
设备固件 1.4.1 + git 短哈希 固件仓 version.txt,构建期自动追加 git describe
BLE 协议 v1 双端常量 PROTOCOL_VERSION ↔ AP_PROTOCOL_VERSION,取较小值运行
固件基线 main @ 0b9e4c8 上游 FoloToy/ai-passport
Node ≥ 22(插件自身);DSH 0.2.2-rc.1 要求 ≥ 24.9.0 开发机 v22.22.2 跑 npm test 全绿;桌面版自带 Node(Contents/Resources/runtime/bin/node,版本随 App 走)
操作系统 macOS(Apple Silicon)/ Windows 10 1703+ BLE 后端:CoreBluetooth / WinRT(noble);固件一次烧录两端通用

版本记录:

  • 1.4.0 —— 语音交互与状态卡整轮打磨:

    • 语音识别改走 DSH 自带语音输入(ctx.speechToText,官方 voice-input bundle), 优先 host-local / SenseVoice;未启用时在挂件、面板给出可操作提示;插件不再自带 ASR。
    • 追问「其他」交互重做:单击提交、长按录音;识别结果改为独立结果页 (单击填入 / 长按提交 / 上键重录 / 下键翻页),语音页只显示录音状态、不回显文字。
    • 状态卡:按用户要求不再单独显示「待审批 / 待回答」(统一显示「运行中」, 内部仍用于亮屏、优先级与不休眠);运行计时移到任务提示下方居中, 任务完成后在该位置静态显示最终用时。
    • 追问默认不再超时(questions.timeoutMs=0),审批仍默认不超时。
    • 设置页新增「按键音」开关(音量沿用提示音量);长选项选中行跑马灯滚动。
    • 蓝牙:断开时复位 hello 标志,且 hello.ack 同时携带固件/电量, 修复重连后面板固件与电量一直显示「—」。
    • 固件 1.4.0 同步,协议 v1 不变。
  • 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.4.1(行为等价补丁:修复 Linux CI 的 strnlen 静态检查)与 1.4.0 (语音结果独立页 + 下键翻页、状态卡与设置项调整;重连后固件/电量可靠上报)。 协议 v1 未变,固件与插件可独立升级。

插件依赖 DSH 0.2.x 的 ctx.webServer / speechToText / deepseekAccount 等宿主 API(当前基线 0.2.2-rc.1,0.2.1-rc.5 亦兼容)。DSH 升级前先跑 npm test(mock 联调)+ docs/07 真机验收,通过再升级。

目录结构

├── packages/dsh-ai-passport/   DSH 插件(npm 包,独立可 link 安装)
│   ├── lib/ble/                transport 抽象 + noble / 桥进程 / mock 三驱动
│   ├── lib/protocol/           帧编解码(协议 v1)
│   ├── lib/bridge/             session / watch / approval / balance / voice / pairing
│   ├── lib/panel/              Web 控制面板
│   ├── lib/client.js           桌面客户端输入框挂件
│   └── cordis.patch.yml         DSH 配置树补丁
├── docs/                       跨端文档(见下方索引)
├── tools/                      主机侧工具(插件安装 / 截图 / 布局校验 / 字体子集化)
├── assets/fonts/               字体源文件(含 LICENSE)
└── vendor/ai-passport/         固件仓库(独立 git,clone 进来,不入库)

文档索引

文档 内容
01-方案设计 系统架构、BLE 协议、设备端交互、语音链路
02-进展与下一步 开发日志:阶段 A/B/C 全记录
03-构建与烧录 环境、固件编译、烧录、插件安装、版本号机制
04-桌面客户端集成 输入框挂件形态、语音回填、桌面端行为
05-语音发送-设计 语音链路设计
06-设备端问答与语音直发-设计 设备端问答与语音直发
07-设备端验收用例 逐项验收表与真机实测记录
08-Windows反馈清单 Windows 客户端适配说明、已知边界、用户反馈清单

开发须知

  • 协议常量双端同步:packages/dsh-ai-passport/lib/protocol/constants.js 的 PROTOCOL_VERSION 与固件仓 main/app_proto.h 的 AP_PROTOCOL_VERSION 手工保持一致, 改协议必须两侧同时 bump,并跑双端 parity 测试。
  • 测试:npm test(顶层 workspace 转发;固件侧逻辑测试在固件仓 ./tools/validate.sh --static)。
  • 版本:固件 version.txt + 构建期 git describe;插件版本在本仓 package.json。

License

MIT © 2026 slinxiaosun-blip

本仓库(DSH 插件、跨端文档与主机侧工具)是独立原创作品,版权归作者本人所有。

设备端固件是另一回事:它是 FoloToy/ai-passport (MIT,版权归 FoloToy)的二次开发作品,遵循其原有许可,版权行见固件仓库的 LICENSE。 两个仓库各自独立授权,互不派生。

—/ 5

No ratings yet

Manifest verification required

Commit 321e432e8a24

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout