mirror of
https://github.com/Ryder-Sun/Meldwork.git
synced 2026-11-07 06:56:03 -10:00
Ryder Sun
4c522c0997
Update bilingual documentation and website, include the official Zcode logo and deployable license notices, and replace the unverified display font with the bundled OFL font. Guard version, download and licensing consistency in CI. Give the native ACP multi-phase integration test a realistic completion budget. Validation: frontend 369/369, landing 12/12, deterministic eval 6 cases/18 results, web/desktop builds, pack/dist, DMG/ZIP integrity and extracted-app signature/license checks passed. Packaged Electron startup passed. The ACP restart group passed 10/10 after one full-suite timing failure; the full desktop suite is rerunning before publication.
144 lines
8.7 KiB
Markdown
144 lines
8.7 KiB
Markdown
# Meldwork 桌面客户端
|
||
|
||
Meldwork 是完全本地运行的 Electron 客户端。它直接加载仓库中的桌面前端，在 Electron
|
||
主进程中检测和调用本机 Agent CLI，不需要登录、JWT、远端平台、Docker 或云端服务。
|
||
|
||
本地群聊、消息、群组配置和 CLI 会话引用保存在 Electron 用户数据目录。渲染进程只通过
|
||
`window.meldworkDesktop` 调用经过约束的 preload API，不会获得可执行文件路径、Provider
|
||
API Key 或任意 Shell 执行能力。
|
||
|
||
支持检测和调用以下本机 Agent CLI：
|
||
|
||
- Codex
|
||
- Hermes
|
||
- OpenClaw
|
||
- WorkBuddy
|
||
- Zcode
|
||
- Pi Agent
|
||
- Kimi Code
|
||
- MiMo Code
|
||
- Claude Code
|
||
- Gemini CLI
|
||
- OpenCode
|
||
- Qwen Code
|
||
- OpenCodeReview
|
||
|
||
Agent 管理面板提供经过白名单约束的安装入口。安装命令和下载地址由主进程固定，不会根据页面
|
||
输入执行任意命令。内置 Agent 通过各自支持的原生权限模式或 Meldwork 托管工具策略执行；无法
|
||
满足当前权限契约的 Agent 会安全失败。群聊级工作目录写入默认关闭，只有用户明确授权后才会
|
||
切换为写入模式。Kimi 在只读对话中通过 Agent Client Protocol 的 `plan` 模式运行；用户明确
|
||
开启写入权限后，才切换到 Kimi 原生的 `stream-json --prompt` 模式。
|
||
|
||
## 首次启动与本地 Agent 检测
|
||
|
||
V1.0.7 GitHub 预发布使用 ad-hoc 临时签名，不使用 Apple Developer ID，也不提交 Apple 公证。
|
||
如果 macOS 首次启动时拦截候选应用，请打开
|
||
“系统设置 → 隐私与安全性”，找到 Meldwork 的拦截提示，点击“仍要打开 / Open Anyway”，
|
||
再确认启动。
|
||
|
||
首次启动会显示三页引导轮播，依次介绍本地 Agent 检测、多 Agent 协作、Skill 与文件上下文。
|
||
客户端在引导打开时执行唯一一次启动刷新；检测任务真正结束前“开始使用”按钮保持禁用，不会
|
||
用固定计时器伪装完成。检测成功或失败后才释放按钮。完成或关闭引导后会在渲染层本地记录状态，
|
||
后续启动直接进入工作台；Agent 仍可在管理面板中重新检测。
|
||
|
||
## 并发协作 Harness V4
|
||
|
||
群聊中选择多个 Agent 后，“并发回复”会在任何 Agent 获取调度资源前冻结同一份任务快照，让全部已选 Agent 独立生成，并在批次屏障后按稳定顺序提交。
|
||
|
||
Auto Discussion 会依次进入独立提案、交叉质询与职责协商、分工执行、单写者整合和独立复核。职责图由 Agent 协商产生，Harness 只负责验证全员同意的同一份计划、依赖、权限、回执、恢复和提交边界，不在模型之外私下分配工作。参与者仍由用户选定；从更大候选池自动选人组队不属于当前版本。
|
||
|
||
## `@` Skill 引用
|
||
|
||
在消息输入框输入 `@` 或点击 `@` 按钮，可以选择当前目标 Agent 本机已发现的 Skill。列表只
|
||
返回清洗后的 Agent、命名空间、slug 和显示名称，不返回 Skill 文件路径或内容。一次消息最多
|
||
选择 4 个 Skill；主进程会在发送前按目标 Agent 重新扫描并验证选择，跨 Agent 冒用、过期条目
|
||
或前端构造的任意路径都会被拒绝。Hermes 使用原生 `--skills` 参数预加载已验证 Skill；其他
|
||
Agent 只会收到属于自己的 Skill 坐标提示，不会收到其他目标的选择。
|
||
|
||
## 文件与多模态附件
|
||
|
||
消息输入框支持系统文件选择器、剪贴板图片以及把文件拖入输入区。当前接受经过 MIME、扩展名和
|
||
文件签名交叉校验的 PNG、JPEG、音视频、PDF、文本、Markdown、常见代码与配置文件、Office
|
||
文档和常见压缩容器；一条消息最多 4 个附件，各格式使用独立大小上限。附件会复制到 Electron
|
||
用户数据目录下的私有存储，工作区消息只保存 `id`、文件名、MIME 类型和大小；渲染层不能读取
|
||
附件路径，只能通过窄 IPC 请求预览或使用系统默认应用打开文件。
|
||
|
||
Agent 原生支持的图片会按其数量限制直接传递。其他文件，或超过某个 Agent 原生媒体能力的附件，
|
||
会在运行期间暂存为工作区内的只读输入文件，并在运行结束后清理；提示词明确要求只读取、不得执行
|
||
附件。未发送附件、删除会话后的无引用附件和异常导入残留由主进程回收。
|
||
|
||
## Provider 配置
|
||
|
||
Agent 使用各自本机的原生鉴权、Provider 和默认模型配置。Meldwork 不要求统一 Provider，
|
||
也不会将一个 Agent 的密钥注入其他 Agent。WorkBuddy 桌面账号的加密登录不能直接供独立
|
||
CLI 解锁；可在 Meldwork 中选择桌面配置里已有且已配置鉴权的模型。
|
||
Meldwork 仅保存模型标识，运行时由主进程读取原生配置，不向渲染层返回密钥。
|
||
Zcode 沿用默认配置；若其默认 Provider 缺少 API Key，需要先修复本机原生配置。
|
||
|
||
## 本地 CLI 支持矩阵
|
||
|
||
| Agent | 检测命令 | macOS 安装 | Windows 安装 | 用户 Provider |
|
||
| --- | --- | --- | --- | --- |
|
||
| Codex | `codex` | npm：`@openai/codex@latest` | npm：`@openai/codex@latest` | 不注入；沿用 Codex 本机配置 |
|
||
| Hermes | `hermes` | 官方 `install.sh` | 官方 `install.ps1` | 沿用本机配置 |
|
||
| OpenClaw | `openclaw` | npm：`openclaw@latest` | npm：`openclaw@latest` | 沿用本机配置 |
|
||
| WorkBuddy | `codebuddy` | npm：`@tencent-ai/[email protected]` | npm：`@tencent-ai/[email protected]` | 可选择桌面已配置模型 |
|
||
| Zcode | `zcode` | 官方 CLI 安装 | 官方 CLI 安装 | 沿用默认配置 |
|
||
| Pi Agent | `pi` | npm：`@mariozechner/pi-coding-agent` | npm：`@mariozechner/pi-coding-agent` | 沿用本机配置 |
|
||
| Kimi Code | `kimi` | 官方 `install.sh` | 官方 `install.ps1` | 不注入；沿用 Kimi 本机配置 |
|
||
| MiMo Code | `mimo` | npm：`@mimo-ai/cli@latest` | npm：`@mimo-ai/cli@latest` | 不注入；沿用 MiMo 本机配置，按授权使用 `plan` / `build` 模式 |
|
||
| Claude Code | `claude` | npm：`@anthropic-ai/claude-code@latest` | npm：`@anthropic-ai/claude-code@latest` | 不注入；沿用 Claude 本机配置 |
|
||
| Gemini CLI | `gemini` | npm：`@google/gemini-cli@latest` | npm：`@google/gemini-cli@latest` | 不注入；沿用 Gemini 本机配置 |
|
||
| OpenCode | `opencode` | npm：`opencode-ai@latest` | npm：`opencode-ai@latest` | 不注入；沿用 OpenCode 本机配置 |
|
||
| Qwen Code | `qwen` | npm：`@qwen-code/qwen-code@latest` | npm：`@qwen-code/qwen-code@latest` | 沿用本机配置 |
|
||
| OpenCodeReview | `ocr` | npm：`@alibaba-group/open-code-review@latest` | npm：`@alibaba-group/open-code-review@latest` | 沿用本机配置 |
|
||
|
||
macOS 会在当前 `PATH` 之外搜索 Volta、pnpm、fnm、asdf、mise、bun、
|
||
`~/.local/bin`、`~/.kimi-code/bin`、`~/.mimocode/bin`、Homebrew 等常见目录。Windows 会额外搜索用户 npm、
|
||
WindowsApps、Node.js、WorkBuddy、Chocolatey 和 Scoop 目录，并按 `PATHEXT` 解析命令。
|
||
|
||
Hermes 和 Kimi 的安装脚本来自固定 HTTPS 白名单地址；客户端不内置脚本副本，因此离线环境
|
||
不能使用这两个一键安装入口。当前自动安装面向 macOS 和 Windows，Windows 安装流程仍需在
|
||
真实 Windows 设备上做发布前验证。
|
||
|
||
## 目录结构
|
||
|
||
- `src/agents/`：Agent 兼容层、路由、运行时、CLI、安装器、连接器
|
||
- `src/attachments/`：附件、内容存储、图片尺寸校验
|
||
- `src/collaboration/`：对话、上下文包、产物、任务图
|
||
- `src/workspace/`：本地工作区与自动调度；自动运行器的通用失败、重试和等待语义位于 `local-workspace-auto-runner-support.cjs`
|
||
- `src/runs/`：运行、预算、事件、调度、日志
|
||
- `src/knowledge/`：知识库与知识连接器
|
||
- `src/skills/`：Skill 目录、快照、信任
|
||
- `src/security/`：私有文件与敏感信息脱敏
|
||
- `test/`：按同名领域镜像组织测试，`support/` 放测试辅助代码；测试发现与 suite 选择位于 `scripts/test-discovery.cjs`
|
||
|
||
## 本地开发
|
||
|
||
```bash
|
||
cd desktop
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
可选环境变量：
|
||
|
||
- `MELDWORK_CODEX_SANDBOX`：Codex 默认沙箱模式，支持 `read-only` 和
|
||
`workspace-write`；未设置或值不受支持时使用 `read-only`。
|
||
|
||
## 测试与打包
|
||
|
||
```bash
|
||
npm test
|
||
npm run pack
|
||
npm run dist
|
||
npm run dist:public
|
||
```
|
||
|
||
`pack` 用于生成未打包应用并验证 Electron 产物；`dist` 生成 V1.0.7 GitHub 预发布候选使用的 ad-hoc 签名 DMG 和 ZIP。这些产物不具备 Developer ID 信任链且未公证，不能声称通过 Gatekeeper。
|
||
|
||
`dist:public` 是未来正式签名公开发行的专用命令：它要求
|
||
Developer ID 证书和完整公证凭据，强制代码签名，在签名后校验永久 Bundle ID、Team ID 与
|
||
hardened runtime，并调用 Apple 公证；任一条件不满足都会失败。产物输出到 `desktop/dist/`，
|
||
其中包含本地前端，不依赖服务器或容器。
|