dsh-harness-jarvis · 贾维斯
English | 中文
贾维斯是常驻桌面的悬浮窗助手，也是一只有状态的桌面宠物：DSH 弹出权限审批时，悬浮窗立刻出现卡片，一键允许 / 拒绝 / 总是允许（此工作区），与主窗口竞答、先到者生效；任何时候按 ⌃⌥J 就能唤出输入条和他对话，对话记录内嵌面板；启动时他还会出声打招呼。他的本体是一颗随状态呼吸的粒子光球——思考、说话、等你拍板各有动效，拖到屏幕边缘就融进墙里收起，要用时一碰涨回球形。
贾维斯光球状态动效：待机、等待、思考、说话、需要你处理
当前 0.7.1 是"助手版"：上面这些能力开箱即用；完整的贾维斯愿景在路线图中继续推进。
贾维斯能做什么
- 🔔 权限审批：DSH 弹出权限请求 → 悬浮窗出现审批卡片，**允许 / 拒绝 / 总是允许（此工作区）**一键作答；面板与 DSH 主窗口竞答，先到者生效，不必切回主窗口。审批出现在哪，就在哪处理。
- ⌨️ 悬浮式对话：全局快捷键
⌃⌥J（默认，可在面板设置中修改）随时唤出快速输入条，和贾维斯直接聊；对话记录内嵌面板，随点随看。一个快捷键，历史随手可及。
- 🔊 语音问候：启动时贾维斯出声打招呼，问候语与发音人可配置，悬停光球可静音。一段可配置、可静音的开机问候。
- ✨ 桌面形象：Metal 粒子光球——五种状态动效、贴边融变、悬停唤醒，像一只安静的桌面宠物待在屏幕角落。一半是状态灯，一半是陪伴。
下面这段动图是一次完整交互：⌃⌥J 展开输入条、打字发送、贾维斯思考并口播、审批卡片一键允许。
完整交互演示：展开输入条、打字、发送、思考与播报、审批一键允许
光球与设计稿
贾维斯的本体是一颗 Metal 粒子光球：六边形核心，向外两次扩散成环，粒子在环间呼吸。空闲时安静悬浮，思考、说话、等待决策、出错各有一套动效；把它拖到屏幕边缘，光球会"融"进墙里，变成一条贴边的扁条，要用时一碰又涨回球形。
- 交互式设计稿（克隆仓库后本地打开即可看动效）：
- 动图由仓库内同款粒子模拟直接渲染，截图由 Snapshotter 生成——均为演示数据，不含真实会话。
空闲悬浮动图
等待决策的心跳提醒动图
空闲悬浮 · 等待你拍板时的"咚-咚"心跳提醒
贴边融变动图：融进墙角成 L 形扁条，再涨回球形
审批卡片与工作区预设
贴边融变收纳 · 审批卡片与工作区预设
安装
当前提供源码安装。面板需要 macOS 14+ 与 Swift 6 工具链（Xcode 或 Command Line Tools）；宿主建议 Node.js 22.18+。
-
从仓库根目录构建：
npm ci
npm run build
(cd macos && ./build.sh)
-
在你使用的 DSH profile 的 package.json 中合并以下条目（把路径换成此仓库的绝对路径，保留原有条目）：
{
"dependencies": {
"dsh-harness-jarvis": "link:/absolute/path/to/dsh-harness-jarvis"
},
"dsh": {
"profile": { "bundles": ["dsh-harness-jarvis"] }
}
}
-
在 profile 目录执行 pnpm install 解析 link: 依赖（不要在仓库里安装此链接）。插件的 dsh.bundle.patch 指向 cordis.patch.yml；插件会自己创建贾维斯会话，不要在 profile 里重复插入同 ID 条目。
-
在 profile 覆盖配置或 DSH 的贾维斯设置页里指定 provider / model，也可以留空——留空时插件会自动选取第一个可用提供方与该提供方的第一个模型（重启 DSH 后生效，可用 npm run smoke 验证）。
硬依赖服务为 tools、userQuestions、jobs；agentLoop、llm、systemPrompt、webServer、settings 等按可用性接入，缺少时插件降级运行（无 webServer 则没有面板通信入口）。
首次使用
- 重启 DSH 后，屏幕上出现悬浮光球；按
⌃⌥J 唤出输入条即可开始对话。
- 下一次 DSH 弹权限审批时，面板会出现审批卡片——点一下即可，也可以回到 DSH 主窗口处理，两边先答先得。
- 悬停光球可控制声音；展开输入区可查看对话记录。
配置
下表列出助手版面向使用者的公开配置，由 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。
