dsh-ai-passport-plugin

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 仓库，各自独立构建与发版：

开发时固件 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 一次性刷入即可。

功能

语音输入的时长限制

要点：

• 上限 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）：

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

版本与兼容性

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

版本记录：

• 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 真机验收，通过再升级。

目录结构

Read the full README on GitHub →