mirror of
https://github.com/Ryder-Sun/Meldwork.git
synced 2026-11-07 06:56:03 -10:00
docs: refine bilingual README for discoverability
This commit is contained in:
Ryder Sun committed
1 parent
a68c53bd86
commit
91a0aad3f2
2 files changed
+107
-221
No files matched your search
@@ -1,125 +1,77 @@
|
||||
<div align="center">
|
||||
|
||||
<img src="frontend/public/logos/meldwork-readme-banner-en.png" alt="Meldwork" width="100%" />
|
||||
|
||||
[Architecture](architecture.md) · [Agent Connector Contract](docs/agent-connector-sdk.md) · [Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
|
||||
|
||||
[English](README.md) | [简体中文](README.zh-CN.md)
|
||||
|
||||
[](LICENSE)
|
||||
[](https://github.com/Ryder-MHumble/Meldwork/releases)
|
||||
|
||||
</div>
|
||||
|
||||
# Meldwork: Local-First Multi-Agent Collaboration Workspace
|
||||
|
||||
> Meldwork is a local-first Electron desktop workspace for multi-agent collaboration and agent orchestration. It brings supported local Agent CLIs into one AI agent workspace, runs concurrent or negotiated work, preserves inspectable evidence, and keeps a human in the loop before workspace writes and adoption decisions.
|
||||
|
||||
Meldwork is a source-available, local-first desktop application for people who already use more than one AI coding or research Agent. The current public preview is a single-user work cell: you choose the participants, the working directory, the context, and the final decision. There is no required Meldwork server, account, or remote conversation store.
|
||||
<p align="center">
|
||||
<img src="frontend/public/logos/meldwork-wordmark-v3.svg" alt="Meldwork local-first AI Agent workspace" width="260">
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/Ryder-MHumble/Meldwork/releases/tag/Meldwork-V1.0.3"><strong>Download the V1.0.3 prerelease for Apple silicon macOS</strong></a>
|
||||
<strong>English</strong> · <a href="README.zh-CN.md">简体中文</a>
|
||||
</p>
|
||||
|
||||
# Meldwork - Local-first AI Agent Workspace
|
||||
|
||||
> Coordinate local Agent CLIs, compare independent work, and review evidence before anything is written.
|
||||
|
||||
Meldwork is a source-available Electron desktop app and local-first multi-agent collaboration workspace for developers, researchers, and technical teams who use more than one AI Agent. It brings local Agent CLIs such as Codex, Claude Code, Gemini CLI, OpenCode, and Qwen Code into one workspace for direct chats, concurrent responses, evidence-aware runs, and human-in-the-loop Agent orchestration.
|
||||
|
||||
The current public preview is a single-user Apple-silicon macOS work cell. You choose the participants, working directory, context, permissions, and final adoption decision. No Meldwork account, server, or hosted conversation store is required.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/Ryder-MHumble/Meldwork/releases/download/Meldwork-V1.0.3/Meldwork-0.1.3-arm64.dmg"><strong>Download the Apple silicon macOS preview</strong></a>
|
||||
· <a href="https://github.com/Ryder-MHumble/Meldwork/releases/tag/Meldwork-V1.0.3">Release notes</a>
|
||||
· <a href="architecture.md">Architecture</a>
|
||||
· <a href="desktop/README.md">Desktop guide</a>
|
||||
· <a href="LICENSE">License</a>
|
||||
</p>
|
||||
|
||||
## What problem does it solve?
|
||||
## Who it is for
|
||||
|
||||
Using several Agents usually means manually choosing a tool, moving context between terminals, reconciling conflicting answers, and remembering why a change was accepted. Meldwork provides the organization layer between individual Agents and a finished decision:
|
||||
Use Meldwork when you:
|
||||
|
||||
- one shared goal and explicit acceptance boundary;
|
||||
- independent proposals instead of hidden routing;
|
||||
- declared permissions, responsibilities, handoffs, dependencies, and stopping conditions;
|
||||
- durable, bounded artifacts and evidence that remain reviewable when Agents change;
|
||||
- human-controlled permission, budget, write, and adoption decisions.
|
||||
|
||||
## Core capabilities
|
||||
|
||||
### Multi-agent collaboration and orchestration
|
||||
|
||||
- **Direct conversations and persistent groups**: keep Agent sessions, messages, working directories, Skills, knowledge references, images, and other attachments together in a local workspace.
|
||||
- **Concurrent Responses**: freeze one task snapshot for all selected Agents, collect independent replies, and commit completed responses in stable member order.
|
||||
- **Auto Discussion V4**: selected Agents produce independent proposals, challenge and negotiate a shared responsibility graph, execute dependency-aware work packages, converge through a single synthesis writer, and run independent verification.
|
||||
- **Harness control plane**: enforce context, permission, budget, recovery, phase, receipt, and commit boundaries without privately assigning responsibilities outside the negotiated plan.
|
||||
- **Evidence and traceability**: persist sanitized run traces and compact typed records for Artifacts, Evidence, Findings, and Adoption. Raw chain-of-thought, credentials, executable paths, and unrestricted tool output stay outside the renderer.
|
||||
- **Human-in-the-loop safety**: workspace writes are opt-in. Permission, budget, ambiguous writable outcomes, and review decisions can require an explicit Human Gate; human adoption is recorded separately as an outcome.
|
||||
- **Local-first context**: import validated local files and media, select bounded knowledge-source references, use target-scoped Skills, and configure compatible Providers without moving Meldwork conversations to a hosted service.
|
||||
|
||||
### Supported local Agent CLIs
|
||||
|
||||
Meldwork can detect and invoke these built-in local CLI profiles when the corresponding command is installed and compatible:
|
||||
|
||||
| Agent | Local command |
|
||||
| --- | --- |
|
||||
| Codex | `codex` |
|
||||
| Hermes | `hermes` |
|
||||
| OpenClaw | `openclaw` |
|
||||
| WorkBuddy | `codebuddy` |
|
||||
| Pi Agent | `pi`, `pi-agent`, or `piagent` |
|
||||
| Kimi Code | `kimi` |
|
||||
| MiMo Code | `mimo` |
|
||||
| Claude Code | `claude` |
|
||||
| Gemini CLI | `gemini` |
|
||||
| OpenCode | `opencode` |
|
||||
| Qwen Code | `qwen` |
|
||||
| OpenCodeReview | `ocr` |
|
||||
|
||||
Custom Agents and the local Agent Connector SDK provide explicit extension paths. Connector packages are content-addressed, approved by the user, and constrained by declared capabilities; see the [Agent Connector SDK](docs/agent-connector-sdk.md).
|
||||
|
||||
## When Meldwork fits
|
||||
|
||||
| Use Meldwork when you need | Use the native tool or another product when you need |
|
||||
| --- | --- |
|
||||
| independent viewpoints from several local Agents on one goal | one Agent and one work surface are enough |
|
||||
| concurrent responses or multi-round proposal, negotiation, work, and verification | a hosted team workspace or remote Agent fleet |
|
||||
| inspectable evidence, bounded run traces, and explicit acceptance | automatic participant selection from a large roster |
|
||||
| local files, Skills, knowledge references, and opt-in workspace writes | enterprise SSO, centralized governance, or organization-wide audit today |
|
||||
|
||||
Remote Agents, Cloud and Channel Connectors, automatic participant selection, enterprise governance, and an Outcome Network are outside the current public preview boundary. License terms follow the [Apache License 2.0](LICENSE); see [Commercial use](COMMERCIAL_USE.md) for a practical summary.
|
||||
- already have multiple local Agent CLIs and need one task to span them;
|
||||
- need independent review for code, research, or product analysis before choosing a path;
|
||||
- need inspectable traces, evidence, and human review before workspace writes.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Discover and select** the local Agent CLIs you want to use.
|
||||
2. **Define context** with a working directory, prompt, validated files or media, Skills, and optional knowledge references.
|
||||
3. **Choose a mode**: direct conversation, Concurrent Responses, or Auto Discussion V4.
|
||||
4. **Review the trace**: inspect phase progress, Agent results, artifacts, evidence, and any Human Gate.
|
||||
5. **Decide what to adopt**. Meldwork does not silently write to the workspace or make the final decision for you.
|
||||
1. **Select** the local Agents and participants.
|
||||
2. **Scope** the goal, working directory, context, and permissions.
|
||||
3. **Run** Direct, Concurrent Responses, or Auto Discussion V4.
|
||||
4. **Review and adopt** the result, evidence, and any Human Gate before changing the workspace.
|
||||
|
||||
## Demo
|
||||
## Collaboration modes
|
||||
|
||||
| Local Agent discovery | Direct multimodal work | Concurrent multi-Agent work |
|
||||
| Mode | What happens | Best for |
|
||||
| --- | --- | --- |
|
||||
| [](assets/meldwork-agent-discovery.png) | [](assets/meldwork-direct-multimodal.png) | [](assets/meldwork-group-collaboration.png) |
|
||||
| Check which supported Agents are ready. | Keep prompts, files, permissions, and compatible sessions together. | Run concurrent replies or an Agent-negotiated collaboration with the participants you selected. |
|
||||
| **Direct** | One selected Agent keeps its conversation and native session when supported. | Focused work with one Agent. |
|
||||
| **Concurrent Responses** | Selected Agents receive the same frozen task snapshot and return independent replies in stable order. | Comparing approaches before choosing one. |
|
||||
| **Auto Discussion V4** | Selected Agents propose, challenge, negotiate responsibilities, execute dependency-aware work, then verify the result. | Multi-round work that needs explicit responsibility and review. |
|
||||
|
||||
## How it differs from adjacent tools
|
||||
Participants are always selected by the user. Automatic selection from a larger roster is outside the current preview.
|
||||
|
||||
| Category | Typical focus | Meldwork's scope |
|
||||
## See it in action
|
||||
|
||||
| Local Agent discovery | Multi-agent review | Direct multimodal work |
|
||||
| --- | --- | --- |
|
||||
| One Agent CLI or AI IDE | Deep work inside one Agent ecosystem | Preserve context and decisions across heterogeneous local Agents |
|
||||
| Parallel coding-Agent manager | Throughput and isolated code tasks | Proposal quality, responsibility, evidence, and acceptance |
|
||||
| Cloud Agent control plane | Remote jobs, sandboxes, and Agent fleets | Local-first execution with the Agents already installed on your computer |
|
||||
| Programmable Agent framework | Developer-defined graphs, roles, and routing | A user-facing organization and review workflow around selected Agents |
|
||||
| Terminals and scripts | Direct access to native Agent capabilities | Durable context, boundaries, traces, and explicit human decisions |
|
||||
| [](assets/meldwork-agent-discovery.png) | [](assets/meldwork-multi-agent-review.png) | [](assets/meldwork-direct-multimodal.png) |
|
||||
|
||||
## Install
|
||||
Example: give Codex, Claude Code, and Gemini CLI the same change-review context, compare their independent findings, then adopt only the evidence-backed result you approve.
|
||||
|
||||
### Packaged preview: Apple silicon macOS
|
||||
## Supported local Agent CLIs
|
||||
|
||||
The current release-validated target is Apple silicon macOS.
|
||||
Meldwork detects and invokes an installed command when its adapter and the CLI version are compatible:
|
||||
|
||||
1. Open the [Meldwork V1.0.3 prerelease](https://github.com/Ryder-MHumble/Meldwork/releases/tag/Meldwork-V1.0.3).
|
||||
2. Download `Meldwork-0.1.3-arm64.dmg`.
|
||||
3. Drag Meldwork into Applications and open it once.
|
||||
4. This prerelease is ad-hoc signed, not signed with an Apple Developer ID, and not Apple-notarized. If macOS blocks it, open **System Settings -> Privacy & Security**, find the Meldwork warning, choose **Open Anyway**, and confirm.
|
||||
5. Install or connect at least one supported local Agent CLI, then let Meldwork detect it.
|
||||
**Codex** (`codex`) · **Hermes** (`hermes`) · **OpenClaw** (`openclaw`) · **WorkBuddy** (`codebuddy`) · **Pi Agent** (`pi`, `pi-agent`, `piagent`) · **Kimi Code** (`kimi`) · **MiMo Code** (`mimo`) · **Claude Code** (`claude`) · **Gemini CLI** (`gemini`) · **OpenCode** (`opencode`) · **Qwen Code** (`qwen`) · **OpenCodeReview** (`ocr`)
|
||||
|
||||
Use only artifacts downloaded from the official GitHub Release.
|
||||
Approved Agent Connectors can be added through the [Agent Connector SDK](docs/agent-connector-sdk.md); custom executable Agents use the desktop custom-Agent path. See the [desktop guide](desktop/README.md) for the full adapter and capability matrix.
|
||||
|
||||
## Quick start
|
||||
|
||||
### Apple silicon macOS preview
|
||||
|
||||
Download [`Meldwork-0.1.3-arm64.dmg`](https://github.com/Ryder-MHumble/Meldwork/releases/download/Meldwork-V1.0.3/Meldwork-0.1.3-arm64.dmg) from the [official V1.0.3 prerelease](https://github.com/Ryder-MHumble/Meldwork/releases/tag/Meldwork-V1.0.3), move Meldwork to Applications, and install at least one supported local Agent CLI. The prerelease is ad-hoc signed and not notarized; macOS may require **Open Anyway** in **System Settings -> Privacy & Security** on first launch.
|
||||
|
||||
### Run from source
|
||||
|
||||
Prerequisites: Node.js `22.12` or newer and npm.
|
||||
Prerequisites: Node.js `22.12+` and npm.
|
||||
|
||||
```bash
|
||||
npm --prefix frontend ci
|
||||
@@ -127,7 +79,7 @@ npm --prefix desktop ci
|
||||
npm --prefix desktop run dev
|
||||
```
|
||||
|
||||
Run the repository checks before distributing a build:
|
||||
Before distributing a build:
|
||||
|
||||
```bash
|
||||
npm --prefix frontend test
|
||||
@@ -136,27 +88,18 @@ npm --prefix frontend run build:desktop
|
||||
npm --prefix desktop test
|
||||
```
|
||||
|
||||
For desktop-specific development, packaging, supported CLI details, and the provider matrix, see the [desktop guide](desktop/README.md).
|
||||
## Current boundary
|
||||
|
||||
## Trust boundaries and local data
|
||||
Meldwork is a local Electron app, not a hosted Agent fleet or a general Agent framework. The current preview does not provide remote/cloud/channel Agent execution, automatic participant selection, enterprise SSO/RBAC/governance, or an Outcome Network. Local-first does not mean fully offline: a selected Agent may send prompts, attachments, or Skills to its configured Provider. Workspace writes are opt-in workflow controls, not an operating-system sandbox.
|
||||
|
||||
- Conversations, groups, orchestration state, bounded run records, and imported attachment metadata stay in local Electron user data.
|
||||
- Agent execution, file access, attachment validation, Provider storage, Connector approval, and installer control remain in the Electron main process behind narrow preload APIs.
|
||||
- Provider API keys use operating-system-backed secure storage where supported; credentials and executable paths are not exposed to the renderer.
|
||||
- Workspace writes are explicit and opt-in. Agent CLIs and their configured model Providers remain external dependencies with their own data-handling terms.
|
||||
- Local-first does not mean every model runs offline: a selected Agent may still send prompts, attachments, or Skills to its configured Provider.
|
||||
|
||||
Read the [architecture](architecture.md) and [security policy](SECURITY.md) for the complete boundary and known limitations.
|
||||
|
||||
## Documentation and contribution
|
||||
## Docs
|
||||
|
||||
- [Architecture and product boundary](architecture.md)
|
||||
- [Desktop setup, Agent matrix, and packaging](desktop/README.md)
|
||||
- [Desktop setup and Agent matrix](desktop/README.md)
|
||||
- [Agent Connector SDK](docs/agent-connector-sdk.md)
|
||||
- [AI discoverability index](docs/ai-discoverability.md)
|
||||
- [Contributing](CONTRIBUTING.md)
|
||||
- [Security policy](SECURITY.md)
|
||||
- [Changelog](CHANGELOG.md)
|
||||
|
||||
## License
|
||||
|
||||
|
||||
+54
-111
@@ -1,125 +1,77 @@
|
||||
<div align="center">
|
||||
|
||||
<img src="frontend/public/logos/meldwork-readme-banner-en.png" alt="Meldwork" width="100%" />
|
||||
|
||||
[Architecture](architecture.md) · [Agent Connector Contract](docs/agent-connector-sdk.md) · [Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
|
||||
|
||||
[English](README.md) | [简体中文](README.zh-CN.md)
|
||||
|
||||
[](LICENSE)
|
||||
[](https://github.com/Ryder-MHumble/Meldwork/releases)
|
||||
|
||||
</div>
|
||||
|
||||
# Meldwork：Local-first 多 Agent 协作工作空间
|
||||
|
||||
> Meldwork 是一个 Local-first Electron 桌面工作空间，用于多 Agent 协作与 Agent 编排。它把受支持的本地 Agent CLI 放进同一个 AI Agent 工作空间，支持并发或协商式工作，保留可检查的 Evidence，并在工作区写入和采用决定之前让人类保持在环（human-in-the-loop）。
|
||||
|
||||
Meldwork 是一个源码可见（source-available）的 Local-first 桌面应用，面向已经使用多个 AI 编程或研究 Agent 的用户。当前公开预览版是单用户工作单元：由你选择参与者、工作目录、上下文和最终决定。Meldwork 不要求服务器、账号或远程对话存储。
|
||||
<p align="center">
|
||||
<img src="frontend/public/logos/meldwork-wordmark-v3.svg" alt="Meldwork 本地优先 AI Agent 工作空间" width="260">
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/Ryder-MHumble/Meldwork/releases/tag/Meldwork-V1.0.3"><strong>下载 V1.0.3 Apple 芯片 macOS 预览版</strong></a>
|
||||
<a href="README.md">English</a> · <strong>简体中文</strong>
|
||||
</p>
|
||||
|
||||
# Meldwork：本地优先（Local-first）AI Agent 工作空间
|
||||
|
||||
> 协同本地 Agent CLI，比较独立结果，在写入前检查证据。
|
||||
|
||||
Meldwork 是一个源码可见的 Electron 桌面应用和本地优先的多 Agent 协作工作空间，也是 AI Agent 编排工作空间，面向使用多个 AI Agent 的开发者、研究人员和技术团队。它把 Codex、Claude Code、Gemini CLI、OpenCode、Qwen Code 等本地 Agent CLI 放进同一个工作空间，支持直接会话、并发回复、有证据可追溯（evidence-aware）运行和人类在环（human-in-the-loop）复核。
|
||||
|
||||
当前公开预览版是 Apple 芯片 macOS 上的单用户工作单元。参与者、工作目录、上下文、权限和最终采用决定都由你选择。Meldwork 不要求账号、服务器或托管式对话存储。
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/Ryder-MHumble/Meldwork/releases/download/Meldwork-V1.0.3/Meldwork-0.1.3-arm64.dmg"><strong>下载 Apple 芯片 macOS 预览版</strong></a>
|
||||
· <a href="https://github.com/Ryder-MHumble/Meldwork/releases/tag/Meldwork-V1.0.3">发布说明</a>
|
||||
· <a href="architecture.md">架构</a>
|
||||
· <a href="desktop/README.md">桌面端指南</a>
|
||||
· <a href="LICENSE">许可证</a>
|
||||
</p>
|
||||
|
||||
## 它解决什么问题？
|
||||
## 适合谁
|
||||
|
||||
同时使用多个 Agent，通常意味着手动选择工具、在终端之间搬运上下文、处理互相冲突的答案，并记住最终为什么采用某个结果。Meldwork 提供单个 Agent 与最终决定之间的组织层：
|
||||
当你有以下需求时，Meldwork 更适合：
|
||||
|
||||
- 一个共享 Goal 和明确的验收边界；
|
||||
- 独立提案，而不是隐藏路由；
|
||||
- 声明式的权限、责任、交接、依赖和停止条件；
|
||||
- 可持续复核的 Artifact 与 Evidence，不因切换 Agent 而消失；
|
||||
- 由人类掌握的权限、预算、写入和采用决定。
|
||||
- 已经安装多个本地 Agent CLI，希望让同一任务跨 Agent 协作；
|
||||
- 需要在代码评审、研究或产品分析中获得独立判断，再选择方案；
|
||||
- 需要在写入工作区前检查可追溯的运行轨迹、证据并保留人工复核。
|
||||
|
||||
## 核心能力
|
||||
## 工作流程
|
||||
|
||||
### 多 Agent 协作与 Agent 编排
|
||||
1. **选择**本地 Agent 和参与者。
|
||||
2. **限定**目标、工作目录、上下文和权限。
|
||||
3. **运行**直接会话、并发回复或 Auto Discussion V4。
|
||||
4. **复核并采用**结果、证据和待处理的人工审批门（Human Gate），再写入工作区。
|
||||
|
||||
- **直接会话和持久群组**：在本地工作空间中保留 Agent Session、消息、工作目录、Skill、知识引用、图片和其他附件。
|
||||
- **并发回复（Concurrent Responses）**：为全部已选 Agent 冻结同一份任务快照，收集独立回复，再按稳定的成员顺序提交完成结果。
|
||||
- **Auto Discussion V4**：已选 Agent 先独立提案，再交叉质询并协商一张共享职责图，按依赖执行工作包，由单一整合写入者收敛结果，最后独立复核。
|
||||
- **Harness 控制平面**：约束上下文、权限、预算、恢复、阶段、回执和提交边界；不会绕过协商计划在模型之外私自分配职责。
|
||||
- **Evidence 与可追溯性**：持久化经过脱敏的运行轨迹，以及 Artifact、Evidence、Finding 和 Adoption 等紧凑类型化记录。Raw chain-of-thought、凭据、可执行路径和不受限工具输出不会进入渲染层。
|
||||
- **Human-in-the-loop 安全控制**：工作区写入默认关闭。权限、预算、存在歧义的写入结果和评审决定可以要求显式 Human Gate；人类采用结果会作为独立 Outcome 记录。
|
||||
- **Local-first 上下文**：导入经过校验的本地文件和媒体，选择有边界的知识源引用，使用面向目标 Agent 的 Skill，并为兼容 Agent 配置 Provider；Meldwork 对话不会迁移到托管服务。
|
||||
## 协作模式
|
||||
|
||||
### 当前支持的本地 Agent CLI
|
||||
|
||||
当对应命令已安装且兼容时，Meldwork 可以检测并调用以下内置本地 CLI profile：
|
||||
|
||||
| Agent | 本地命令 |
|
||||
| --- | --- |
|
||||
| Codex | `codex` |
|
||||
| Hermes | `hermes` |
|
||||
| OpenClaw | `openclaw` |
|
||||
| WorkBuddy | `codebuddy` |
|
||||
| Pi Agent | `pi`、`pi-agent` 或 `piagent` |
|
||||
| Kimi Code | `kimi` |
|
||||
| MiMo Code | `mimo` |
|
||||
| Claude Code | `claude` |
|
||||
| Gemini CLI | `gemini` |
|
||||
| OpenCode | `opencode` |
|
||||
| Qwen Code | `qwen` |
|
||||
| OpenCodeReview | `ocr` |
|
||||
|
||||
Custom Agent 和本地 Agent Connector SDK 提供明确的扩展路径。Connector package 采用内容寻址，由用户批准，并受声明能力约束；详见 [Agent Connector SDK](docs/agent-connector-sdk.md)。
|
||||
|
||||
## 适用场景与不适用场景
|
||||
|
||||
| 适合在这些场景使用 Meldwork | 这些需求应优先选择原生工具或其他产品 |
|
||||
| --- | --- |
|
||||
| 需要多个本地 Agent 针对同一目标给出独立判断 | 一个 Agent 和一个工作面已经足够 |
|
||||
| 需要并发回复，或提案、协商、执行、复核等多轮流程 | 需要托管式团队工作空间或远程 Agent Fleet |
|
||||
| 需要可检查的 Evidence、受边界约束的运行轨迹和明确验收 | 需要从大型候选池自动选人组队 |
|
||||
| 需要本地文件、Skill、知识引用和显式开启的工作区写入 | 当前就需要企业 SSO、集中治理或组织级审计 |
|
||||
|
||||
远程 Agent、Cloud 和 Channel Connector、自动选人组队、企业治理以及 Outcome Network 不在当前公开预览边界内。许可证条款遵循 [Apache License 2.0](LICENSE)；实际使用说明见[商业使用说明](COMMERCIAL_USE.md)。
|
||||
|
||||
## 使用流程
|
||||
|
||||
1. **检测并选择**要使用的本地 Agent CLI。
|
||||
2. **定义上下文**：设置工作目录、Prompt、经过校验的文件或媒体、Skill 和可选知识引用。
|
||||
3. **选择模式**：直接会话、并发回复或 Auto Discussion V4。
|
||||
4. **检查轨迹**：查看阶段进度、Agent 结果、Artifact、Evidence 和待处理的 Human Gate。
|
||||
5. **决定是否采用**。Meldwork 不会静默写入工作区，也不会替你做最终决定。
|
||||
|
||||
## 效果演示
|
||||
|
||||
| 本地 Agent 检测 | 直接会话中的多模态工作 | 并发多 Agent 工作 |
|
||||
| 模式 | 运行方式 | 适合场景 |
|
||||
| --- | --- | --- |
|
||||
| [](assets/meldwork-agent-discovery.png) | [](assets/meldwork-direct-multimodal.png) | [](assets/meldwork-group-collaboration.png) |
|
||||
| 查看哪些受支持 Agent 已就绪。 | 让 Prompt、文件、权限和兼容 Session 保持在一起。 | 运行并发回复，或让已选择的 Agent 自主协商协作方式。 |
|
||||
| **直接会话** | 一个已选 Agent 在适配器支持时保持对话和原生会话。 | 使用单个 Agent 完成聚焦工作。 |
|
||||
| **并发回复** | 已选 Agent 收到同一份冻结任务快照，并按稳定顺序返回独立回复。 | 在选择方案前比较不同路径。 |
|
||||
| **Auto Discussion V4** | 已选 Agent 先提案、质询并协商责任，按依赖执行工作，再独立复核结果。 | 需要明确责任和复核的多轮工作。 |
|
||||
|
||||
## 与相邻工具的区别
|
||||
参与者始终由用户选择。从更大候选池自动选人不属于当前预览版。
|
||||
|
||||
| 类别 | 通常关注什么 | Meldwork 的范围 |
|
||||
## 运行示例
|
||||
|
||||
| 本地 Agent 检测 | 多 Agent 评审 | 直接会话中的多模态工作 |
|
||||
| --- | --- | --- |
|
||||
| 单 Agent CLI 或 AI IDE | 在一个 Agent 生态中完成深度工作 | 让上下文和决定跨异构本地 Agent 保持连续 |
|
||||
| 并行 Coding-Agent 工作台 | 吞吐量和隔离的代码任务 | 方案质量、责任、Evidence 和验收 |
|
||||
| Cloud Agent 控制平面 | 远程 Job、Sandbox 和 Agent Fleet | Local-first 执行，使用电脑上已经安装的 Agent |
|
||||
| 可编程 Agent 框架 | 开发者定义 Graph、角色和路由 | 面向使用者的 Agent 组织与复核工作流 |
|
||||
| 多终端与脚本 | 直接访问原生 Agent 能力 | 持久上下文、边界、轨迹和明确的人类决定 |
|
||||
| [](assets/meldwork-agent-discovery.png) | [](assets/meldwork-multi-agent-review.png) | [](assets/meldwork-direct-multimodal.png) |
|
||||
|
||||
## 安装
|
||||
示例：把同一份变更评审上下文交给 Codex、Claude Code 和 Gemini CLI，比较各自的独立发现，再只采用你批准且有证据支持的结果。
|
||||
|
||||
### Apple 芯片 macOS 打包预览版
|
||||
## 支持的本地 Agent CLI
|
||||
|
||||
当前经过发布验证的目标是 Apple 芯片 macOS。
|
||||
当适配器和 CLI 版本兼容时，Meldwork 会检测并调用已安装的命令：
|
||||
|
||||
1. 打开 [Meldwork V1.0.3 预发布页](https://github.com/Ryder-MHumble/Meldwork/releases/tag/Meldwork-V1.0.3)。
|
||||
2. 下载 `Meldwork-0.1.3-arm64.dmg`。
|
||||
3. 将 Meldwork 拖入“应用程序”，然后打开一次。
|
||||
4. 当前预发布版使用 ad-hoc 临时签名，没有 Apple Developer ID 签名，也没有经过 Apple 公证。如果 macOS 阻止启动，请打开“系统设置 -> 隐私与安全性”，找到 Meldwork 提示，选择“仍要打开 / Open Anyway”并确认。
|
||||
5. 至少安装或连接一个受支持的本地 Agent CLI，然后让 Meldwork 执行检测。
|
||||
**Codex**（`codex`）· **Hermes**（`hermes`）· **OpenClaw**（`openclaw`）· **WorkBuddy**（`codebuddy`）· **Pi Agent**（`pi`、`pi-agent`、`piagent`）· **Kimi Code**（`kimi`）· **MiMo Code**（`mimo`）· **Claude Code**（`claude`）· **Gemini CLI**（`gemini`）· **OpenCode**（`opencode`）· **Qwen Code**（`qwen`）· **OpenCodeReview**（`ocr`）
|
||||
|
||||
请只使用官方 GitHub Release 下载的产物。
|
||||
已批准的 Agent Connector 可通过 [Agent Connector SDK](docs/agent-connector-sdk.md) 接入；自定义可执行 Agent 使用桌面端的自定义 Agent 入口。完整适配器和能力矩阵见[桌面端指南](desktop/README.md)。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### Apple 芯片 macOS 预览版
|
||||
|
||||
从[官方 V1.0.3 预发布页](https://github.com/Ryder-MHumble/Meldwork/releases/tag/Meldwork-V1.0.3)下载 [`Meldwork-0.1.3-arm64.dmg`](https://github.com/Ryder-MHumble/Meldwork/releases/download/Meldwork-V1.0.3/Meldwork-0.1.3-arm64.dmg)，将 Meldwork 移入“应用程序”，并至少安装一个受支持的本地 Agent CLI。该预发布版使用 ad-hoc 临时签名且未公证；首次启动时，macOS 可能要求你在“系统设置 -> 隐私与安全性”中选择“仍要打开 / Open Anyway”。
|
||||
|
||||
### 从源码运行
|
||||
|
||||
前置条件：Node.js `22.12` 或更高版本以及 npm。
|
||||
前置条件：Node.js `22.12+` 和 npm。
|
||||
|
||||
```bash
|
||||
npm --prefix frontend ci
|
||||
@@ -127,7 +79,7 @@ npm --prefix desktop ci
|
||||
npm --prefix desktop run dev
|
||||
```
|
||||
|
||||
分发前运行仓库检查：
|
||||
分发构建前运行：
|
||||
|
||||
```bash
|
||||
npm --prefix frontend test
|
||||
@@ -136,27 +88,18 @@ npm --prefix frontend run build:desktop
|
||||
npm --prefix desktop test
|
||||
```
|
||||
|
||||
桌面端开发、打包、完整 Agent 矩阵和 Provider 配置见[桌面端指南](desktop/README.md)。
|
||||
## 当前边界
|
||||
|
||||
## 信任边界与本地数据
|
||||
Meldwork 是本地 Electron 应用，不是托管式 Agent Fleet，也不是通用 Agent 框架。当前预览版不提供远程、云端或频道 Agent 执行，不提供自动选人组队、企业 SSO/RBAC/治理或 Outcome Network。Local-first 不等于完全离线：选定的 Agent 仍可能把 Prompt、附件或 Skill（技能）发送到其配置的 Provider（模型服务商）。工作区写入是可选的工作流控制，不是操作系统级沙箱。
|
||||
|
||||
- 对话、群组、编排状态、受边界约束的运行记录和附件元数据保存在本地 Electron 用户数据中。
|
||||
- Agent 执行、文件访问、附件校验、Provider 存储、Connector 审批和安装器控制都在 Electron 主进程中完成，并通过窄化的 preload API 暴露能力。
|
||||
- Provider API Key 在兼容环境中使用操作系统安全存储；凭据和可执行路径不会暴露给渲染层。
|
||||
- 工作区写入必须显式开启。Agent CLI 及其配置的模型 Provider 仍是外部依赖，各自适用自己的数据处理条款。
|
||||
- Local-first 不等于所有模型都离线运行：选定的 Agent 仍可能把 Prompt、附件或 Skill 发送到其配置的 Provider。
|
||||
|
||||
完整边界和已知限制见[架构说明](architecture.md)与[安全策略](SECURITY.md)。
|
||||
|
||||
## 文档与贡献
|
||||
## 文档
|
||||
|
||||
- [架构与产品边界](architecture.md)
|
||||
- [桌面端设置、Agent 矩阵和打包](desktop/README.md)
|
||||
- [桌面端设置与 Agent 矩阵](desktop/README.md)
|
||||
- [Agent Connector SDK](docs/agent-connector-sdk.md)
|
||||
- [AI 可发现性索引](docs/ai-discoverability.md)
|
||||
- [贡献指南](CONTRIBUTING.md)
|
||||
- [安全策略](SECURITY.md)
|
||||
- [变更记录](CHANGELOG.md)
|
||||
|
||||
## 许可证
|
||||
|
||||
|
||||
Reference in new issue
Block a user