dsh-harness-jarvis · 贾维斯

English | 中文

贾维斯是常驻桌面的悬浮窗助手，也是一只有状态的桌面宠物：DSH 弹出权限审批时，悬浮窗立刻出现卡片，一键允许 / 拒绝 / 总是允许（此工作区），与主窗口竞答、先到者生效；任何时候按 ⌃⌥J 就能唤出输入条和他对话，对话记录内嵌面板；启动时他还会出声打招呼。他的本体是一颗随状态呼吸的粒子光球——思考、说话、等你拍板各有动效，拖到屏幕边缘就融进墙里收起，要用时一碰涨回球形。

当前 0.7.1 是"助手版"：上面这些能力开箱即用；完整的贾维斯愿景在路线图中继续推进。

贾维斯能做什么

• 🔔 权限审批：DSH 弹出权限请求 → 悬浮窗出现审批卡片，**允许 / 拒绝 / 总是允许（此工作区）**一键作答；面板与 DSH 主窗口竞答，先到者生效，不必切回主窗口。审批出现在哪，就在哪处理。
• ⌨️ 悬浮式对话：全局快捷键 ⌃⌥J（默认，可在面板设置中修改）随时唤出快速输入条，和贾维斯直接聊；对话记录内嵌面板，随点随看。一个快捷键，历史随手可及。
• 🔊 语音问候：启动时贾维斯出声打招呼，问候语与发音人可配置，悬停光球可静音。一段可配置、可静音的开机问候。
• ✨ 桌面形象：Metal 粒子光球——五种状态动效、贴边融变、悬停唤醒，像一只安静的桌面宠物待在屏幕角落。一半是状态灯，一半是陪伴。

下面这段动图是一次完整交互：⌃⌥J 展开输入条、打字发送、贾维斯思考并口播、审批卡片一键允许。

光球与设计稿

贾维斯的本体是一颗 Metal 粒子光球：六边形核心，向外两次扩散成环，粒子在环间呼吸。空闲时安静悬浮，思考、说话、等待决策、出错各有一套动效；把它拖到屏幕边缘，光球会"融"进墙里，变成一条贴边的扁条，要用时一碰又涨回球形。

• 交互式设计稿（克隆仓库后本地打开即可看动效）：
  • docs/design/orb-states.html — 各状态的粒子动效与实际尺寸对比
  • docs/design/orb-visual-direction.html — 早期视觉方向探索
• 动图由仓库内同款粒子模拟直接渲染，截图由 Snapshotter 生成——均为演示数据，不含真实会话。

空闲悬浮 · 等待你拍板时的"咚-咚"心跳提醒

贴边融变收纳 · 审批卡片与工作区预设

安装

当前提供源码安装。面板需要 macOS 14+ 与 Swift 6 工具链（Xcode 或 Command Line Tools）；宿主建议 Node.js 22.18+。

1. 从仓库根目录构建：

   npm ci
   npm run build
   (cd macos && ./build.sh)
   

2. 在你使用的 DSH profile 的 package.json 中合并以下条目（把路径换成此仓库的绝对路径，保留原有条目）：

   {
     "dependencies": {
       "dsh-harness-jarvis": "link:/absolute/path/to/dsh-harness-jarvis"
     },
     "dsh": {
       "profile": { "bundles": ["dsh-harness-jarvis"] }
     }
   }
   

3. 在 profile 目录执行 pnpm install 解析 link: 依赖（不要在仓库里安装此链接）。插件的 dsh.bundle.patch 指向 cordis.patch.yml；插件会自己创建贾维斯会话，不要在 profile 里重复插入同 ID 条目。

4. 在 profile 覆盖配置或 DSH 的贾维斯设置页里指定 provider / model，也可以留空——留空时插件会自动选取第一个可用提供方与该提供方的第一个模型（重启 DSH 后生效，可用 npm run smoke 验证）。

硬依赖服务为 tools、userQuestions、jobs；agentLoop、llm、systemPrompt、webServer、settings 等按可用性接入，缺少时插件降级运行（无 webServer 则没有面板通信入口）。

首次使用

1. 重启 DSH 后，屏幕上出现悬浮光球；按 ⌃⌥J 唤出输入条即可开始对话。
2. 下一次 DSH 弹权限审批时，面板会出现审批卡片——点一下即可，也可以回到 DSH 主窗口处理，两边先答先得。
3. 悬停光球可控制声音；展开输入区可查看对话记录。

配置

下表列出助手版面向使用者的公开配置，由 src/index.ts 的 schema 生成；其余内部字段不对外承诺。路径与身份经 profile 配置；设置页中的 provider/model 改动需重启 DSH，其余开关下次请求即生效。

字段 / Field	类型 / Type	默认值 / Default	DSH 设置页 / Settings
locale	"zh" / "en"	"zh"	否 / No
audioDir	string	"~/.dsh/jarvis"	否 / No
ttsBackend	"edge"	"edge"	否 / No
edgeVoice	string	"zh-CN-YunjianNeural"	是 / Yes
provider	string	""	是 / Yes
model	string	""	是 / Yes
greetings	string[]	[]	是 / Yes

locale 控制启动问候语言，不是完整的面板双语开关；面板外观与快捷键设置保存在 ~/.dsh/jarvis/panel.json，连接凭据只写入本机该目录，请勿分享。

与 voice-mini 配合

voice-mini 可选。可用时贾维斯优先用它的播报与播放控制；不可用时退回内置 edge-tts。静音会抑制播报。

隐私与权限

审批记录、日志与语音缓存默认保存在本机 ~/.dsh/jarvis，没有云端存储。本机存储不等于离线处理：所配置的模型服务会收到对话上下文，内置 edge-tts 会把播报文本发给 Microsoft 语音服务。

插件不申请 danger-full-access；快捷键走 Carbon RegisterEventHotKey，不需要辅助功能按键监听；当前没有麦克风录音。审批记录与日志可能包含敏感操作上下文，请自行管理分享范围。

路线图

0.7.x 之后将逐步补齐贾维斯的完整愿景（细节随版本落地再公布）：

• 语音输入——对贾维斯说话，含唤醒词
• 预编译面板随 npm 包分发，免本地 Swift 构建
• 指挥官能力：会话托管、分级审批与长期记忆
• 跨平台面板（非 macOS 桌面）

已知限制

• 原生面板仅面向 macOS 14+；语音输入与预编译分发尚未完成。
• 安全审查与真机验收未完成，暂不声称已通过发布安全验收。

开发

npm ci
npm run build
npm test
(cd macos && swift test && ./build.sh)
npm run docs:config          # 重新生成上方配置表
npm run docs:config -- --check
npm pack --dry-run

构建后重启 DSH 再执行 npm run smoke。面板改动后重建并重启；截图用演示数据从仓库根目录生成：

JARVIS_SNAPSHOT=/tmp/jarvis-snapshots ./macos/jarvis-panel

许可证

MIT © 2026 zane — 见 LICENSE。