diff --git a/.gitignore b/.gitignore index 1cb6bde..15b7e62 100644 --- a/.gitignore +++ b/.gitignore @@ -20,7 +20,9 @@ release/ *.blockmap latest*.yml -# Documentation is part of the public repository. +# Local documentation drafts +/docs/ +/documentation/ .github/brand/ # Test and coverage output diff --git a/README.md b/README.md index 80f157a..84345c6 100644 --- a/README.md +++ b/README.md @@ -6,82 +6,97 @@ English · 简体中文

-# One task. Different Agents. A result you can inspect. +# AI agents are interchangeable. Your work should not be. -**Meldwork is a local-first desktop workspace that keeps conversations, files, permissions, compatible Agent sessions, and sanitized run evidence together while work moves between general-purpose Agents.** +**Meldwork is a local-first desktop workspace for persistent direct Agent conversations and bounded multi-Agent review. Each conversation keeps its own context, permissions, attachments, compatible native sessions, and sanitized execution history on your computer.** -Most Agent tools are good at completing a step. The work becomes fragile when you cross tools: context is copied by hand, files are attached again, permission boundaries drift, and the final answer arrives without a clear record of how it was reached. +Most Agent tools are already good at completing one step. The fragile part starts when work crosses tools: context gets copied by hand, files are attached again, permission boundaries drift, and the final answer can look complete without showing how it was formed. Meldwork keeps the task stable while Agents change. Start with one Agent, add another only when the work needs a different capability or an independent challenge, then inspect the result before deciding what to keep. -Meldwork keeps the task stable while Agents change. Start with one Agent, add another only when the work needs a different capability or an independent challenge, then inspect the result before deciding what to keep. +Meldwork is not about opening more AI windows. It is about letting complex work move between Agents without losing the thread: one Agent's conclusions and evidence can support the next step, every answer returns to the same task context, and you decide which results are worth accepting.

- Understand the Harness - · Run from source + Download the macOS DMG · AGPL-3.0 license + · Commercial use

-## The problem is fragmented work +## Install the desktop client -| When work crosses Agent tools | What Meldwork keeps together | +The current desktop build is for Apple silicon Macs. + +1. Open the [latest GitHub Release](https://github.com/Ryder-MHumble/Meldwork/releases/latest). +2. Download `Meldwork-0.1.0-arm64.dmg`. +3. Drag Meldwork into Applications and open it. +4. Connect the supported Agent CLIs already installed on your computer, or configure an independent Provider profile for an Agent. + +If the latest Release includes a DMG, it can be downloaded and installed locally. Developers can also run Meldwork from source with the commands below. + +## Start with one repeatable workflow + +The first public workflow is simple: produce a deliverable, have a second Agent challenge it, and let the human decide what to keep. + +1. Create a group with two locally ready Agents. +2. Attach only the files needed for the task and keep workspace write access off unless the task requires it. +3. Ask one Agent to produce the deliverable and the other to check assumptions, omissions, and evidence in a bounded discussion. +4. Inspect the final replies and sanitized run trace before accepting, revising, or discarding the result. + +Other domains are examples, not separate product promises. The release is successful when this two-Agent review loop works predictably on a clean Apple silicon Mac. + +## One place to see the work + +![Meldwork workspace overview](frontend/public/logos/meldwork-workspace-overview.png) + +Direct conversations and working groups live in the same desktop workspace. Start directly when one Agent is enough; create a group when the task needs an independent check. Meldwork does not currently merge separate conversation histories automatically, so attach or restate the context the group must share. + +## From a first answer to a reviewed decision + +| Step | What happens in Meldwork | | --- | --- | -| Conversation history is split across apps | A persistent direct conversation or working group | -| Files and instructions are repeatedly copied | Explicit task files, Skills, knowledge sources, and bounded context | -| Permission scope is easy to lose | A visible working directory and opt-in workspace write access | -| Multiple answers create more noise | Bounded rounds, Agent-specific results, and a human decision | -| The final output is hard to reconstruct | Sanitized events, context provenance, status, and compact evidence | +| Start | Open a direct conversation with the Agent best suited to the first step | +| Escalate | Create a working group and select only the Agents that should participate | +| Discuss | Run a manual handoff or a bounded automatic multi-round discussion | +| Verify | Inspect final replies, status, source context, and sanitized execution traces before accepting the result | -Meldwork does not automatically merge unrelated conversation histories. You decide which messages, files, Skills, and knowledge sources enter a task. +![Multi-Agent product review in Meldwork](frontend/public/logos/meldwork-multi-agent-review.png) -## A repeatable workflow - -1. **Start focused.** Open a direct conversation with the Agent best suited to the first step. -2. **Add only necessary context.** Attach task files, choose compatible Skills or configured knowledge sources, and keep workspace writes off unless the task requires them. -3. **Bring in a second perspective.** Create a group, select only the Agents that should participate, and use a manual handoff or a bounded automatic discussion. -4. **Inspect before accepting.** Review each Agent, round, conclusion, injected source context, and sanitized event history, then decide whether to adopt, revise, or discard the result. - -## One workspace for direct work and collaboration - -![Meldwork workspace overview](docs/assets/meldwork-multi-agent-review.png) - -Direct conversations and working groups live in the same desktop workspace. The sidebar reflects the Agents available on that computer; the main surface keeps active tasks, working directories, permissions, and recent conversations within reach. +The conversation remains readable while Agent-specific process details stay available on demand. Group runs preserve compact evidence for later Agents and for the human making the final decision. ## The Harness behind the workspace ![Meldwork Harness Engine](frontend/public/logos/Harness-readme.png) -Direct conversations stream progress inline. Group Runs add Agent- and round-specific trace details. Behind both surfaces, the Harness normalizes Agent events, builds bounded Context Packs, keeps compatible native Sessions separate, checkpoints local Run state, and exposes explicit recovery states. +The Harness is the layer that keeps Agent collaboration from turning into copied prompts and disconnected transcripts. It normalizes Agent events, builds bounded context for each target, keeps compatible native sessions separate, checkpoints local run state, and exposes recovery states when authentication or compatibility needs user action. - **Run control:** explicit targets, manual handoffs, bounded automatic rounds, stop, and per-Agent controls. - **Context control:** stable constraints, selected files, target-scoped Skills and knowledge sources, recent conclusions, and compact evidence capsules. -- **Inspectable execution:** conclusions, source context, warnings, terminal status, and, when exposed by the selected Agent or transport, plans and tool lifecycle summaries, without revealing raw chain-of-thought or credentials. -- **Durable local state:** conversations and bounded Run records remain inspectable; Context Packs remain durable and traceable after completion or interruption. -- **Explicit recovery:** authentication and compatibility failures require correction and a user retry instead of blind repeated attempts. +- **Inspectable execution:** conclusions, source context, warnings, terminal status, and, when exposed by the selected Agent or transport, plans and tool lifecycle summaries. +- **Durable local state:** conversations and bounded run records remain inspectable; context stays durable and traceable after completion or interruption. -Interrupted multi-Agent work is recorded, but not every workflow can resume from the exact previous Agent slot yet. The current behavior favors an inspectable interruption over silently duplicating work or side effects. - -## What you can do today - -- Keep persistent direct conversations and multi-Agent working groups. -- Target one or more Agents explicitly, or run an automatic discussion with a chosen maximum round limit. -- Attach validated images, media, documents, code, and archives, subject to the selected Agent's capabilities. -- Add up to four compatible Skills and configured Feishu, DingTalk, or Obsidian knowledge sources to the relevant Agent target. -- Continue compatible native Sessions without exposing their identifiers to the renderer. -- Keep workspace write access off by default and enable it per conversation when the task needs file changes. -- Inspect sanitized direct-run details inline and group-run details by Agent and round. -- Store Agent-specific Provider profiles with operating-system-backed encryption where supported. - -## Where it helps +## Why teams use Meldwork - **Research and intelligence:** one Agent builds the evidence base while another challenges unsupported assumptions. -- **Product and strategy:** one develops a proposal while another tests user value, feasibility, and expensive failure modes. -- **Software delivery:** one implements while another reviews the diff, tests, and reasoning behind the change. -- **Writing and operations:** one produces the deliverable while another checks accuracy, structure, and execution risk. +- **Product and strategy:** one develops the proposal, another tests positioning, feasibility, and expensive failure modes. +- **Software delivery:** one implements, another reviews the diff and the reasoning behind it. +- **Writing and content:** one creates, another checks structure, factual accuracy, and tone. +- **Operations:** specialized Agents handle different parts of the task while the full work record stays visible. -The goal is not to maximize Agent count. It is to use the smallest useful team without losing the task, the boundary, or the evidence. +The goal is not to maximize Agent count. It is to use the right Agent at the right moment without fragmenting the work. + +## What the desktop client keeps together + +- Persistent direct conversations and multi-Agent working groups. +- Explicit Agent targeting, manual runs, and automatic multi-round discussions. +- Compatible native-session continuity for each conversation and Agent. +- Sanitized run traces, completion state, and compact evidence capsules. +- Agent-specific Provider profiles and operating-system-backed credential storage where supported. +- Skills, validated images, media, documents, code, archives, approved knowledge sources, and opt-in workspace access. +- Local conversation and orchestration state with no Meldwork cloud account or remote conversation store. + +Model requests still follow the Agent and Provider you choose. Local-first describes Meldwork's workspace and orchestration state; it does not make third-party models offline. ## Connected Agents -General Agents: +Meldwork currently integrates with: **Codex · Hermes · OpenClaw · WorkBuddy · Kimi Code · MiMo Code · Claude Code · Gemini CLI · OpenCode · Qwen Code** @@ -91,13 +106,14 @@ Specialized review: Availability depends on the installed Agent, supported version, authentication state, and declared capabilities. OpenCodeReview is a specialized review target rather than a general conversation Agent. -## Data and control boundary +Each Agent keeps its own capabilities, provider configuration, permission model, and session behavior. Availability depends on the installed Agent, its version, and its authentication state. -Meldwork keeps its workspace and orchestration records on the local computer and does not require a Meldwork cloud account or remote conversation store. Model and tool requests still follow the Agent and Provider you configure. +## Current release scope -Workspace write access is an explicit per-conversation choice, but Meldwork is not an operating-system sandbox. Agent processes run with the local user's identity, and upstream tools remain responsible for enforcing the capabilities they declare. +The first release-validated target is Apple silicon macOS. Windows has implementation-level support, but broad real-device validation is still incomplete. Broad third-party Agent certification is not yet claimed. -## Run from source +
+Build from source for development Requires Node.js 20.19 or newer and npm. @@ -107,16 +123,16 @@ npm --prefix desktop ci npm --prefix desktop run dev ``` -The strongest current packaging and runtime verification is on Apple silicon macOS. Windows has implementation-level support, but broad real-device validation is still incomplete. +Use the repository test scripts before distributing a build: -Verification commands and known gaps are documented in [docs/tests.md](docs/tests.md). +```bash +npm --prefix frontend test +npm --prefix frontend run build +npm --prefix frontend run build:desktop +npm --prefix desktop test +``` -## Documentation - -- [Harness Engine strategy](docs/harness-engine-strategy.md) -- [Architecture](docs/architecture.md) -- [Permissions](docs/permissions.md) -- [Tests and verification](docs/tests.md) +
## License diff --git a/README.zh-CN.md b/README.zh-CN.md index 3149b36..c5abf44 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -6,100 +6,116 @@ English · 简体中文

-# 一项任务，不同 Agent，一份可检查的结果 +# Agent 可以换，工作不该断 -**Meldwork 是一个本地优先的 Agent 桌面工作空间。当工作在不同通用 Agent 之间流转时，它把会话、文件、权限、兼容的原生 Session 与脱敏运行证据留在同一个地方。** +**Meldwork 是一个本地优先的 Agent 桌面工作台，用于持续单聊和有边界的多 Agent 复核。每个会话的上下文、权限、附件、兼容的原生 Session 与脱敏运行记录都保存在你的电脑上。** -多数 Agent 已经能够完成一段工作。真正脆弱的是切换工具之后：上下文需要手工复制，文件要重新附加，权限边界容易丢失，最终答案看起来完整，却很难说明它是如何形成的。 +多数 Agent 已经能够完成一段工作。真正脆弱的是切换工具之后：上下文需要手工复制，文件要重新附加，权限边界容易丢失，最终答案看起来完整，却很难说明它是如何形成的。Meldwork 让任务保持稳定，让 Agent 按需变化。先从一个 Agent 开始；只有当任务需要另一种能力或独立质疑时，再加入第二个 Agent；最后由你检查结果并决定保留什么。 -Meldwork 让任务保持稳定，让 Agent 按需变化。先从一个 Agent 开始；只有当任务需要另一种能力或独立质疑时，再加入第二个 Agent；最后由你检查结果并决定保留什么。 +它解决的不是“同时打开更多 AI”，而是让一项复杂工作能够在不同 Agent 之间真正接力：前一个 Agent 留下的结论和证据，后一个可以继续使用；所有人的回答仍然回到同一条任务脉络里，由你决定哪些结果值得接受。

- 了解 Harness - · 从源码运行 + 下载 macOS DMG 安装包 · AGPL-3.0 开源许可证 + · 商业使用说明

-## 问题不在 Agent 数量，而在工作被切碎 +## 先装客户端，再开始工作 -| 当工作跨越多个 Agent 工具 | Meldwork 保留下来的内容 | -| --- | --- | -| 会话历史散落在不同应用 | 持续存在的单聊或工作群组 | -| 文件和要求反复复制 | 明确的任务文件、Skill、知识来源与有界上下文 | -| 权限范围容易丢失 | 可见的工作目录与按需开启的写入权限 | -| 多个答案带来更多噪音 | 限定轮次、Agent 独立结果与人工决定 | -| 最终输出难以复盘 | 脱敏事件、上下文来源、状态与精简证据 | +当前桌面客户端面向 Apple 芯片 Mac： -Meldwork 不会自动合并彼此无关的会话历史。哪些消息、文件、Skill 和知识来源进入任务，始终由你决定。 +1. 打开 [最新 GitHub Release](https://github.com/Ryder-MHumble/Meldwork/releases/latest)。 +2. 下载 `Meldwork-0.1.0-arm64.dmg`。 +3. 将 Meldwork 拖入“应用程序”并打开。 +4. 连接电脑上已经安装的 Agent CLI，或为某个 Agent 单独配置 Provider。 -## 一条可以重复使用的工作流 +如果最新 Release 中包含 DMG 文件，就可以直接下载到本地安装。开发者也可以使用下方命令从源码运行。 -1. **先聚焦。** 选择最适合第一步的 Agent，打开单聊开始工作。 -2. **只加入必要上下文。** 附加任务文件，选择兼容的 Skill 或已经配置的知识来源；除非任务必须修改文件，否则保持工作目录只读。 -3. **引入第二种视角。** 创建群组，只选择真正需要参与的 Agent，再使用手动接力或限定轮次的自动讨论。 -4. **检查后再接受。** 查看每个 Agent、每一轮、结论、注入的上下文来源和脱敏事件，再决定采用、修改还是放弃结果。 +## 先跑通一个可重复的工作流 -## 单聊与协作共享一个工作空间 +首个公开工作流很简单：先产出交付物，再由第二个 Agent 质疑和复核，最后由人决定采用什么。 -![Meldwork 工作台总览](docs/assets/meldwork-multi-agent-review.png) +1. 创建一个只有两个已就绪 Agent 的群组。 +2. 只附加任务真正需要的文件；除非任务必须修改工作区，否则保持写入权限关闭。 +3. 明确让一个 Agent 形成交付物，让另一个检查假设、遗漏与证据，并限制讨论轮数。 +4. 查看最终回答和脱敏运行轨迹，再决定采用、修改或放弃结果。 -单聊和工作群组位于同一个桌面工作空间。左侧栏反映这台电脑上可以使用的 Agent；主工作区把当前任务、工作目录、权限和最近会话放在随时可回到的位置。 +研究、产品、开发、写作和运营是使用示例，不是几套独立的产品承诺。首发成功的标准，是这条双 Agent 复核闭环能在一台干净的 Apple 芯片 Mac 上稳定完成。 + + +## 打开客户端，看到的是完整工作现场 + +![Meldwork 工作台总览](frontend/public/logos/meldwork-workspace-overview.png) + +单聊、工作群组和最近任务都在同一个桌面工作台里。一个 Agent 足够时使用单聊；需要独立检查时创建群组。Meldwork 当前不会自动合并两个独立会话的历史，因此群组需要的背景和文件仍应由用户明确附加或重述。 + +## 一项任务如何在 Meldwork 里推进 + +| 阶段 | 你的操作 | Meldwork 保留下来的内容 | +| --- | --- | --- | +| 先开工 | 选择最合适的 Agent 发起单聊 | 当前任务、对话和原生 Session 延续关系 | +| 再协作 | 创建群组，只选择真正需要参与的 Agent | 群组成员、工作目录和明确的执行权限 | +| 多轮打磨 | 手动点名，或启动有边界的自动多轮讨论 | 每轮回答、Agent 接力关系和运行状态 | +| 最终验收 | 查看结论与运行轨迹，决定是否采用 | 精简后的证据、状态和可追溯结果 | + +![Meldwork 多 Agent 产品审查群聊](frontend/public/logos/meldwork-multi-agent-review.png) + +主对话只保留对工作有价值的内容；需要追问时，再展开某个 Agent 的执行过程。这样既不会让工具日志淹没结论，也不会只剩一段看似完整、却无法复盘的最终回答。 ## 工作空间背后的 Harness ![Meldwork Harness Engine](frontend/public/logos/Harness-readme.png) -单聊的运行进度直接显示在对话中；群组 Run 会额外提供按 Agent 和轮次查看的运行详情。两种界面背后，Harness 负责统一 Agent 事件、构建有界 Context Pack、隔离兼容的原生 Session、保存本地 Run 状态，并把恢复过程变成明确状态。 +Harness 是让 Agent 协作不退化成复制 Prompt 和散落会话的关键层。它统一 Agent 事件，为每个目标构建有边界的上下文，隔离兼容的原生 Session，保存本地 Run 状态，并在认证或兼容性需要用户处理时暴露明确的恢复状态。 -- **运行控制：** 明确点名、手动接力、限定轮次的自动讨论、停止与单 Agent 控制。 +- **运行控制：** 明确点名、手动接力、有边界的自动轮次、停止与单 Agent 控制。 - **上下文控制：** 稳定约束、选定文件、按目标分配的 Skill 与知识来源、近期结论和精简证据摘要。 -- **可检查的执行过程：** 结论、上下文来源、警告、终态，以及所选 Agent 或传输能够提供的计划和工具生命周期摘要，同时不暴露原始思维链或凭据。 -- **持久本地状态：** 会话与有界 Run 记录在完成或中断后仍可查看；Context Pack 保持持久并可追溯。 -- **明确恢复：** 认证与兼容性错误需要先修正配置，再由用户重试，不进行无条件反复尝试。 +- **可检查的执行过程：** 结论、上下文来源、警告、终态，以及所选 Agent 或传输方式能够提供的计划和工具生命周期摘要。 +- **持久本地状态：** 会话与有界 Run 记录在完成或中断后仍可查看；上下文保持持久并可追溯。 -中断的多 Agent 工作会留下记录，但目前并非所有工作流都能从上一个 Agent 执行位置精确续跑。当前行为优先保留可检查的中断状态，避免静默重复工作或外部副作用。 - -## 当前可以完成什么 - -- 保留持续存在的 Agent 单聊与多 Agent 工作群组。 -- 明确点名一个或多个 Agent，或为自动讨论设置最大轮数。 -- 附加经过验证的图片、音视频、文档、代码和压缩包，具体取决于所选 Agent 的能力。 -- 为对应 Agent 目标加入最多四个兼容 Skill，以及已配置的飞书、钉钉或 Obsidian 知识来源。 -- 在兼容条件下延续原生 Session，同时不向渲染层暴露 Session 标识。 -- 默认关闭工作目录写入权限，并在任务确实需要修改文件时按会话开启。 -- 在单聊中查看脱敏运行详情，在群组中按 Agent 和轮次检查执行状态。 -- 在兼容系统上使用操作系统安全存储保存 Agent 专属 Provider 配置。 - -## 它适合哪些工作 +## 它适合哪些真实工作 - **研究与情报：** 一个 Agent 建立证据基础，另一个寻找证据缺口与错误假设。 -- **产品与战略：** 一个完善方案，另一个检查用户价值、可行性和高成本风险。 -- **软件交付：** 一个负责实现，另一个审查代码改动、测试和关键判断。 -- **写作与运营：** 一个形成交付物，另一个检查准确性、结构和执行风险。 +- **产品与战略：** 一个完善方案，另一个从用户价值、商业风险和执行成本上进行压力测试。 +- **软件开发：** 一个负责实现，另一个审查代码改动、测试覆盖和关键判断。 +- **写作与内容：** 一个搭建结构和初稿，另一个检查事实、表达和读者体验。 +- **复杂运营：** 不同 Agent 处理各自擅长的部分，但完整任务仍然留在一个地方。 -目标不是让更多 Agent 同时发言，而是用最小且有价值的组合完成任务，同时不丢失边界、上下文和证据。 +Meldwork 不鼓励为了“看起来智能”而堆叠 Agent。一个 Agent 足够时就直接完成；只有当第二种能力确实能降低错误、返工或决策风险时，才把它加入工作。 -## 当前连接的 Agent +## 客户端把这些能力放在一起 -通用 Agent： +- 持续存在的 Agent 单聊与多 Agent 工作群组。 +- 明确点名执行、手动接力和自动多轮讨论。 +- 在兼容条件下，为每个群组和 Agent 延续原生 Session。 +- 可复盘但经过脱敏和压缩的运行轨迹与证据摘要。 +- 每个 Agent 独立的 Provider 档案，以及兼容系统下的安全凭据存储。 +- Skill、经过验证的图片、音视频、文档、代码、压缩包、授权知识源和按需开启的工作目录访问。 +- 会话与编排状态留在本机，不依赖 Meldwork 云账号或远程会话数据库。 + +模型请求仍然会按照你选择的 Agent 和 Provider 发出。“本地优先”指 Meldwork 自己的工作空间和编排状态留在电脑上，并不意味着第三方模型自动变成离线模型。 + +## 当前可以连接的 Agent + +Meldwork 当前已支持： **Codex · Hermes · OpenClaw · WorkBuddy · Kimi Code · MiMo Code · Claude Code · Gemini CLI · OpenCode · Qwen Code** 专项审查： - **OpenCodeReview** 能否实际使用取决于本机安装情况、受支持版本、认证状态和 Agent 声明的能力。OpenCodeReview 是专项审查目标，不作为通用对话 Agent 使用。 -## 数据与控制边界 +每个 Agent 保留自己的能力、Provider、权限模型和 Session 行为。能否使用取决于本机是否安装、版本是否兼容，以及对应认证是否就绪。 -Meldwork 的工作空间与编排记录保存在本机，不要求 Meldwork 云账号或远程会话数据库。模型和工具请求仍会按照你配置的 Agent 与 Provider 发出。 +## 当前发布范围 -工作目录写入是按会话明确开启的权限，但 Meldwork 不是操作系统级沙箱。Agent 进程仍以本地用户身份运行，上游工具需要对其声明的能力负责。 +首个经过发布验证的目标是 Apple 芯片 Mac。Windows 已具备实现层支持，但广泛的真实设备验证仍未完成；所有第三方 Agent 的广泛兼容性还不属于当前承诺。 -## 从源码运行 +
+开发者从源码运行 -需要 Node.js 20.19 或更高版本以及 npm。 +源码开发需要 Node.js 20.19 或更高版本以及 npm： ```bash npm --prefix frontend ci @@ -107,16 +123,16 @@ npm --prefix desktop ci npm --prefix desktop run dev ``` -目前最充分的打包与运行验证集中在 Apple 芯片 macOS。Windows 已具备实现层支持，但广泛的真实设备验证仍未完成。 +分发前请运行仓库测试脚本： -完整验证命令与已知缺口见 [docs/tests.md](docs/tests.md)。 +```bash +npm --prefix frontend test +npm --prefix frontend run build +npm --prefix frontend run build:desktop +npm --prefix desktop test +``` -## 文档 - -- [Harness Engine 战略](docs/harness-engine-strategy.md) -- [架构](docs/architecture.md) -- [权限边界](docs/permissions.md) -- [测试与验证](docs/tests.md) +
## 许可证 diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 7203829..0000000 --- a/docs/README.md +++ /dev/null @@ -1,58 +0,0 @@ -# Meldwork 文档 - -Meldwork 是一个本地优先的 Agent 工作系统。它把已支持的本地 Agent CLI、Skill、文件和显式知识来源放进同一个持续工作空间，并通过 Harness 管理上下文、权限、运行状态和多 Agent 协作。 - -本目录是项目唯一的产品与工程文档入口。`archive/` 只保留历史战略版本，不能作为当前产品承诺。 - -## 核心文档 - -| 文档 | 用途 | 当前决策 | -| --- | --- | --- | -| [市场与用户调研](market-user-research.md) | 判断为什么做、为谁做、先验证什么 | 聚焦 Agent + Knowledge + Outcome，不做聚合聊天器 | -| [产品迭代规划](product-iteration-plan.md) | 把愿景拆成一个 OPC 能执行的优先级路线 | 先完成 Context Pack 与 Task Outcome，再扩展 Cloud/Channel | -| [Harness Engine 战略](harness-engine-strategy.md) | 定义异构 Agent 接入、动态协作、业务 Pack 与商业化路径 | 任意 CLI 是入口，Connector、Evaluation、Outcome 与业务交付才是长期价值 | -| [产品 BP](product-bp.md) | 对外解释定位、价值、增长和后续收入 | 开源优先，以重复使用和标准化回款决定商业化 | - -## 演示与传播 - -- [发布与 PR 素材](launch-kit.md)：README、发布帖和演示口径。 -- [演示录制场景](demo-recording-scenarios.md)：核心能力的可复现实录流程、英文测试指令与验收要点。 -- [宣传视频脚本](promo-video-scripts.md)：中英文 75 秒主片分镜、旁白、字幕与剪辑规范。 -- [品牌策略](brand-strategy.md)：工作名、Slogan、Logo 和传播边界。 - -## 工程与验证 - -- [macOS 签名与公证](macos-signing.md)：Apple Developer、证书、electron-builder 配置和验收。 -- [架构](architecture.md)：Electron、Renderer、Main、Connector 边界。 -- [流程](flows.md)：工作流与状态流转。 -- [权限边界](permissions.md)：本地执行、Provider、Installer 和写入权限。 -- [自动化](automation.md)：当前自动讨论与外部副作用清单。 -- [测试与验证](tests.md)：已执行检查、缺口和分发门槛。 -- [变量与密钥](variables.md)：Provider、Agent 凭证和本地运行变量。 - -## 文档口径 - -- **已实现：** 当前仓库、测试和用户界面可以直接支持的能力。 -- **验证中：** 已经有实现或实验，但还缺少稳定的真实环境证据。 -- **路线图：** 希望通过 Context Pack、Connector、Task、Artifact、Evidence 等机制交付的未来能力。 -- **商业假设：** 定价、付费和团队治理相关假设，不能写成当前功能。 - -对外宣传只能把第一类写成“现在可以用”。第二、三类必须明确边界，第四类必须说明仍待验证。 - -## 协议文件 - -- [许可证](../LICENSE) -- [商业使用政策](../COMMERCIAL_USE.md) -- [声明](../NOTICE) - -## 当前一句话 - -> **Meldwork brings the agents and knowledge sources you already use into one local, accountable workspace.** -> -> **Meldwork 把你已经在用的 Agent 和知识来源带进一个本地、可追溯的工作空间。** - -## 目标一句话 - -> **An open, local-first work system where context and outcomes can move between agents without losing control or proof.** -> -> **一套开放、本地优先的 Agent 工作系统，让上下文和结果可以在不同 Agent 之间流转，同时保留控制和证据。** diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index 5879877..0000000 --- a/docs/architecture.md +++ /dev/null @@ -1,105 +0,0 @@ -# Architecture - -## Product Boundary - -Meldwork is a local Electron desktop product for direct and multi-Agent work with explicitly selected Skill, image, and knowledge-source context. It has no account system, tenant model, required application server, remote conversation store, email delivery, scheduled jobs, or public SEO surface. Optional Agent, Cloud, and Channel Connectors run behind the Electron main-process trust boundary and are disabled until explicitly configured. - -The supported product surface is the packaged Electron application. The frontend is a renderer bundle; without the local preload bridge it shows a desktop-required state and cannot operate the workspace. - -## Components - -| Component | Responsibility | Primary evidence | -| --- | --- | --- | -| Vue renderer | Agent-first multi-session UI, direct-session rename/delete, live direct-chat conclusions and inline execution summaries, group-chat result streaming with an expandable per-Agent/right-side trace panel, per-round navigation, background completion markers, first-run carousel, conversation/Skill/image/knowledge composer UI, bounded attachment-preview cache, theme/i18n, user confirmation and input collection | `frontend/src/App.vue`, `frontend/src/components/RunTracePanel.vue`, `frontend/src/composables/useAttachmentPreviews.js`, `frontend/src/desktop.js`, `frontend/src/knowledgeBaseCatalog.js` | -| Electron preload | Exposes narrow workspace, Human Gate, Cloud control, installer/Skill, attachment, Provider, and knowledge-source methods through `window.roundrelayDesktop` only to a local `file:` document; Channel ingress has no renderer API | `desktop/src/preload.cjs` | -| Electron main | Trust boundary for IPC authorization and shutdown gating, persistence, attachment import/preview, Connector registration, Skill and knowledge-source validation, local/Cloud execution, Channel receivers, navigation, sanitized run events, operating-system notifications, Provider storage, and installer control | `desktop/src/main.cjs` | -| Local workspace | Persists Meldwork conversations, final replies, compact evidence capsules, safe message metadata, task-scoped group Sessions, conversation-scoped direct Sessions, legacy Session migration, Agent-specific transcript deltas, Agent preferences/runtime evidence, and active run coordination | `desktop/src/local-workspace.cjs` | -| Run Ledger | Atomically checkpoints bounded, sanitized per-run and per-Agent state for stop/crash recovery, marks nonterminal runs and Agent attempts interrupted after restart, supports idempotent reconciliation of missing terminal Agent messages, and purges records with their conversation | `desktop/src/run-ledger.cjs` | -| Context Pack and delivery stores | Capture immutable, content-addressed Task inputs, attempt-specific approved prompts, exact outbound fingerprints, source hashes, target scope, and native Session provenance | `desktop/src/context-pack-store.cjs`, `desktop/src/local-workspace-context-packs.cjs` | -| Outcome store | Persists typed Artifacts, Evidence, Findings, and Adoption records separately from diagnostic reasoning and tool summaries | `desktop/src/outcome-store.cjs`, `desktop/src/outcome-records.cjs` | -| Human Gate store | Persists permission, budget, and decision requests and their terminal user/system decisions without exposing raw request payloads to the renderer | `desktop/src/human-gate-store.cjs`, `desktop/src/human-gate-coordinator.cjs` | -| Scheduling and failure policy | Enforces run budgets, retry policy, per-Agent controls, and global/workspace scheduling | `desktop/src/run-scheduler.cjs`, `desktop/src/failure-policy.cjs` | -| Agent Connector registry/runtime | Validates approved manifests and instances, separates CredentialRefs, records Connector/upstream versions, and reduces versioned idempotent Run Events | `desktop/src/agent-connector-manifest.cjs`, `desktop/src/agent-connector-registry.cjs`, `desktop/src/agent-connector-runtime.cjs` | -| Attachment store | Imports validated local images, media, documents, code/configuration files, Office files, and archives into private app-owned storage, verifies metadata/checksums on read, and removes unreferenced entries | `desktop/src/attachment-store.cjs`, `desktop/src/image-dimensions.cjs` | -| Local Skill catalog | Scans bounded known roots per Agent and returns sanitized Skill coordinates without exposing paths or contents | `desktop/src/local-skill-catalog.cjs` | -| Local knowledge-source catalog | Detects and probes code-defined Feishu, DingTalk, and Obsidian access modes, returns sanitized readiness, validates task selections, and exposes reference-only future sources | `desktop/src/local-knowledge-base.cjs` | -| Knowledge Connector runtime | Executes main-owned bounded search/fetch/snapshot/citation operations for explicit source selections; the renderer receives only sanitized discovery and selection records | `desktop/src/local-knowledge-connectors.cjs`, `desktop/src/knowledge-connector-filesystem.cjs` | -| Cloud Agent runtime | Persists remote job/cursor state and idempotent input, permission, cancel, callback, polling, reconciliation, and Artifact operations without requiring a server | `desktop/src/cloud-agent-runtime.cjs`, `desktop/src/cloud-agent-operation-store.cjs` | -| Channel ingress runtime | Verifies main-owned Connector events, rejects replay/expired delivery, maps external actors and subscriptions to local Tasks, queues a durable Inbox, and audits outbound replies | `desktop/src/channel-ingress-runtime.cjs`, `desktop/src/channel-inbox-store.cjs` | -| Knowledge-source store | Persists only the user-selected Obsidian Vault path; Feishu and DingTalk credentials remain owned by their local CLIs | `desktop/src/knowledge-base-store.cjs` | -| CLI adapters | Detect and invoke supported local Agent executables with per-Agent arguments and constrained child environments | `desktop/src/cli-adapters.cjs` | -| Agent installer | Detects Agents and runs allowlisted npm packages or official installer scripts after user confirmation | `desktop/src/agent-installer.cjs` | -| Provider store | Validates Provider metadata and encrypts the API key with Electron `safeStorage` | `desktop/src/provider-store.cjs` | -| Managed OpenClaw runtime | Creates isolated local configuration and a restricted tool policy for OpenClaw | `desktop/src/openclaw-runtime.cjs` | - -## Trust Boundaries - -1. The renderer is not trusted with Node.js, Agent executable paths, native Agent session IDs or storage paths, attachment paths, Skill paths/contents, raw Provider credentials after saving, arbitrary filesystem reads, or arbitrary process execution. User-selected conversation workdirs and the user-selected Obsidian Vault path are intentional UI-visible paths; pasted image bytes use one exact import payload. -2. Preload exposes only named IPC methods. Main validates that every request comes from the current main frame and exact bundled frontend file. -3. Main owns local files, OS dialogs, attachment validation/storage, Skill and knowledge-source discovery/revalidation, Connector approval/registration, Agent discovery, child processes, Cloud observation, Channel authentication, installer downloads, and credential encryption. -4. Agent CLIs are external processes. They receive a selected working directory, a constrained environment, permission flags, main-resolved image paths, target-scoped immutable Skill snapshots, and validated knowledge snapshots or read-only hints after capability checks. -5. Provider, Agent Connector, Cloud Connector, Channel Connector, and installer destinations are external trust boundaries. Provider URLs are user supplied and validated; manifests and Connector instances fail closed unless explicitly approved; Channel signatures and Workspace scope are verified before Task delivery. -6. Harness events expose only allowlisted status, conclusion deltas, reasoning summaries, plans, tool lifecycle summaries, bounded result metadata, and source message IDs. Raw chain-of-thought, commands, executable paths, native session references, credentials, unrestricted stdout/stderr, and arbitrary tool payloads remain outside the renderer and shared Agent context. - -## Local Data - -| Data | Location | Protection | -| --- | --- | --- | -| Meldwork conversations, messages, native session-reference mappings, Agent preferences/runtime evidence | Electron user data: `roundrelay-workspace.json` | Local JSON written through main; group native references are keyed by Task and Agent, direct references by conversation and Agent, all remain main-only, and snapshots remove executable paths | -| Bounded run checkpoints | Electron user data: `roundrelay-run-ledger.json` | Atomic private writes; `0600` file, with new parent directories created as `0700`; at most 64 sanitized runs with bounded Agent output/events/source IDs; no raw commands, paths, credentials, or native session references | -| Immutable Context Packs, delivery records, content blobs, typed outcomes, and Human Gates | Electron user data under `roundrelay-private/` | Content-addressed or atomically written main-only records; renderer snapshots expose only bounded IDs, provenance summaries, budgets, and pending Gate choices | -| Cloud operations and Channel Inbox | Electron user data under `roundrelay-private/` | Private `0600` stores keep opaque remote references, idempotency state, signed-event-derived Task data, delivery cursors, Task mappings, and outbound audit records; raw signatures, headers, credentials, and complete IM history are not exposed to the renderer | -| Imported attachments | Electron user data under `attachments/` | App-owned copy; `0700` directories, `0600` files, type/MIME/size validation, image-dimension checks where applicable, metadata checksum, ID-only renderer access | -| Provider metadata and encrypted key | Electron user data: `roundrelay-provider.json` | API key encrypted with `safeStorage`; file written atomically with mode `0600` | -| Knowledge-source preference | Electron user data: `roundrelay-knowledge-base.json` | Stores the selected absolute Obsidian Vault path only; written atomically as a private file | -| Managed OpenClaw state/config | Electron user data under `openclaw-managed/` | Per-scope directories, mode `0700`; config mode `0600`; API key passed by child environment | -| Theme, locale, and onboarding completion | Renderer `localStorage` | Non-secret UI preferences | - -Live renderer events remain transient. Main separately checkpoints a bounded sanitized run snapshot, while final replies and compact evidence capsules are stored with local conversation messages so a group result can reopen its trace without retaining raw tool output. A conclusion already emitted through answer deltas is retained in the terminal failure, timeout, stop, or interruption message. On restart, nonterminal checkpoints become `interrupted`, then every recoverable terminal Agent checkpoint that is not already represented in the conversation is materialized with its recorded status and output. Completed and partial attempts become Agent messages; failed, timed-out, stopped, and interrupted attempts become status-specific system messages. If a matching `agentRunId` message already exists but lacks its Ledger output, reconciliation enriches it once. Writable Agents are never auto-resumed. Persisted attachment references contain safe metadata only, and Skill references contain sanitized target/namespace/slug/name coordinates. Renaming a conversation preserves its native sessions; changing its working directory clears them to prevent cross-workspace resume. Deleting a Meldwork conversation must first remove its Run Ledger records, then remove its app-owned messages, native session-reference mapping, and attachments no longer referenced elsewhere. It does not call a CLI-specific deletion command or remove history stored by Codex, Hermes, or another Agent CLI. - -There is no Meldwork-hosted remote data store or application account namespace. Managed OpenClaw paths are isolated by local conversation and working-directory scope inside Electron's per-user data directory. Optional Cloud jobs and Channel deliveries remain owned by their configured external systems while local recovery state stays in main-owned private stores. - -## Network Surface - -- Agent CLIs may call their own configured model providers. -- Selected attachments and Skill-influenced prompts may be sent by an Agent CLI to its configured model provider after local validation and capability checks. -- Compatible Agents may receive the user-configured Provider URL/model/key from main. -- Feishu and DingTalk readiness probes may invoke their configured local CLIs; a selected Agent may then use those CLI connections with read-only instructions. -- An explicit Obsidian selection is searched and fetched through the main-owned read-only filesystem Connector, then captured as an immutable snapshot or explicit live reference before Agent invocation. -- Approved Agent Connectors may contact only their declared outbound destinations and receive main-owned CredentialRefs rather than renderer-provided secrets. -- Configured Cloud Connectors may submit and observe remote jobs, answer waiting input/permission, cancel idempotently, and fetch declared Artifacts. -- Configured Channel Connectors may keep a main-process receiver active while the UI window is closed; verified events become scoped Task requests and audited replies rather than copied chat history. -- The installer may download fixed Hermes/Kimi installer URLs or invoke npm for fixed package names. -- Credential-free HTTPS links may be opened in the operating-system browser; remote navigation is denied inside the Electron window. -- The renderer CSP uses `connect-src 'self'` and does not directly call model or application APIs. - -## Known Risks And Assumptions - -- Installer recipes use mutable upstream packages or scripts and currently do not verify a pinned digest or signature (`desktop/src/agent-installer.cjs`). -- Conversation history is local but not application-encrypted (`desktop/src/local-workspace.cjs`). -- Sanitized Run Ledger checkpoints are local and private but not application-encrypted. The store assumes one Electron main-process writer and recovers only the last persisted bounded checkpoint, not every in-memory event (`desktop/src/run-ledger.cjs`). -- Conversation deletion is privacy-first across two local JSON stores rather than transactional: Ledger records are removed first; if the workspace write then fails, in-memory conversation state is rolled back and remains retryable, but the deleted trace checkpoints are not recreated. -- Imported attachment copies are private and integrity-checked but not application-encrypted (`desktop/src/attachment-store.cjs`). -- Local Skill files are untrusted prompt input. Main prevents renderer-supplied paths and cross-Agent selection, but a selected Skill can still influence Agent behavior (`desktop/src/local-skill-catalog.cjs`, `desktop/src/local-workspace.cjs`). -- Obsidian selections use a main-owned read-only Connector with bounded retrieval, immutable snapshots, and citation hash verification. Generic Feishu and DingTalk access remains CLI-owned and prompt-mediated; their authentication and document permissions are not controlled by Meldwork. Notion, Confluence, Google Drive, and SharePoint are reference-only planned sources and are not active Connectors. -- Native image support is currently limited to Codex, Hermes, and OpenCode, with different per-run limits; mixed groups fail before execution when they cannot receive equal image context (`desktop/src/cli-adapters.cjs`). -- Read-only enforcement is owned by the Obsidian Connector for captured selections. Agent workspace and CLI-mediated remote access still depends partly on each upstream CLI honoring its permission flags; Meldwork adds per-CLI hardening where available (`desktop/src/cli-adapters.cjs`). -- Provider requests and native Agent authentication are external dependencies; Meldwork cannot guarantee their availability or data handling. -- Agent/Cloud/Channel Connector contracts validate provenance, scope, and idempotency, but the external implementation must honor its CredentialRef, outbound destination, cancellation, and signature-verification obligations. The production build registers no Cloud or Channel Connector by default. -- macOS packaging uses ad-hoc signing for local validation, not a notarized public release (`desktop/scripts/after-pack.cjs`). - -## Capability Absences - -- No email sending, so there is no `emails.md`. -- No cron or scheduled background work, so there is no `cron.md`. -- No supported public or indexable routes, so there is no `seo.md`. - -## Related Documents - -- [Flows](flows.md) -- [Permissions](permissions.md) -- [Variables And Secrets](variables.md) -- [Test Coverage](tests.md) -- [Automation](automation.md) -- [Public MVP Release Checklist](public-mvp-release.md) -- [macOS Signing And Notarization](macos-signing.md) diff --git a/docs/archive/roundrelay-product-iteration-strategy-legacy.md b/docs/archive/roundrelay-product-iteration-strategy-legacy.md deleted file mode 100644 index 655d939..0000000 --- a/docs/archive/roundrelay-product-iteration-strategy-legacy.md +++ /dev/null @@ -1,712 +0,0 @@ -# RoundRelay 产品评审与迭代战略（历史归档） - -> **已被取代：** 本文保留旧阶段的判断依据，不代表当前产品路线、品牌、发布承诺或商业目标。当前版本请以 [市场与用户调研](../market-user-research.md)、[产品迭代规划](../product-iteration-plan.md) 和 [产品 BP](../product-bp.md) 为准。 - -> 状态：战略草案，供两院内部决策与工程排期使用 -> -> 产品名：RoundRelay -> -> 中文工作名：**群智接力** -> -> 证据基线：2026-07-30 的仓库与工作区快照 -> -> 适用阶段：内部 Alpha 到两院封闭试点 -> -> 复审节奏：每 4 周复审一次；当产品边界、数据政策或主目标用户发生变化时立即复审 - -## 0. 一页结论 - -### 决策建议 - -**建议有条件继续投入，暂不进入公开发布。** RoundRelay 已经具备一个可信本地桌面产品的技术骨架：Electron 主进程承担权限边界，本地 Agent 可被发现与调用，首次引导、单聊和群聊、`@` Skill、图片附件与会话引用已经形成实现和自动化验证，工作目录默认只读，自动讨论有轮数、时间和停止上限。这些能力足以支持院内 Alpha，不足以证明“多 Agent 一定比单 Agent 更有效”，也不足以支撑高敏感数据、Windows 正式发布或无人监管的自主辩论。 - -下一阶段不应继续以“支持更多 Agent、增加更多聊天功能”为主线，而应验证一个更窄的产品命题： - -> **RoundRelay（群智接力）是一款面向两院知识工作者的本地优先多智能体协作桌面端：在用户掌控上下文、工作目录权限和模型去向的前提下，将已有异构本地 Agent 组织为可持续对话、分工接力和可审计审校。** - -战略重点是从“多个 Agent 在一个聊天框里轮流说话”，升级为“围绕高价值任务形成可验证的工作结果”。若 12 周试点不能证明它相对“直接使用最强单 Agent”在质量、速度或风险发现上至少有一项达到预设门槛且方向稳定的优势，应收缩为统一的本地 Agent 工作台，不继续投入复杂自治编排。 - -### 战略范围说明 - -本文评审对象是当前仓库中的 **RoundRelay 本地桌面产品**，不是最初设想的“云 Agent + 本地 Agent + 多个人类同事”完整两院协作平台。两者应按“本地切入点与上层平台”的关系管理，而不是混为同一个已交付产品： - -- RoundRelay 先验证本地 Agent 互联、任务接力、权限控制和多 Agent 净收益，是可独立使用的产品，也是未来混合平台可复用的桌面执行节点。 -- 原始两院平台若继续推进，负责组织身份、同事协作、云 Agent、任务发布和跨端共享；它不能绕过本地端的数据去向确认与执行授权。 -- 在 RoundRelay 尚未证明高价值任务收益、协议稳定性和安全边界前，不把云端群聊、多用户实时协作或跨设备同步纳入当前路线图。 -- 后续若立项混合平台，应单独定义身份、消息同步、权限继承、云本地路由和审计架构，不以“给 RoundRelay 加一个服务器”代替战略与安全评审。 - -### 当前阶段判断 - -| 维度 | 判断 | 说明 | -| --- | --- | --- | -| 技术可行性 | 中高 | 本地执行、IPC 边界、持久化、首次引导、Skill/图片上下文、适配器和有界自动讨论已有代码与测试证据 | -| 发布成熟度 | 中低 | macOS 仅适合内部验证；未完成正式签名、公证、自动升级和完整真机矩阵 | -| 用户价值证据 | 低 | 仓库内没有访谈、行为数据、任务效果对照或留存证据 | -| 差异化潜力 | 中高 | “本地控制 + 异构 Agent + 结构化审校”组合有价值，但仅支持多个 CLI 很容易被复制 | -| 安全可信度 | 中 | Electron 边界和密钥存储较强，但 Agent 仍以本机用户权限运行，聊天数据未做应用层加密，安装源未锁定摘要 | -| 自主辩论成熟度 | 低 | 当前是顺序轮询、提示词约束和一致同意标记，不是角色化、证据化、可评测的辩论协议 | - -### 投资条件 - -未来 12 周只在以下条件下继续加码： - -1. 找到至少 2 个高频且高价值的院内任务，用户愿意每周重复使用。 -2. 对照最强单 Agent，RoundRelay 在盲评质量、风险发现或总用时上至少一项达到 20% 的方向性提升门槛，且没有明显增加返工；正式扩大前必须同时报告样本量、评审一致性和区间估计。 -3. 真实 Agent 调用失败率、写入越权、敏感信息外发和安装供应链风险达到本文件定义的发布门槛。 -4. 用户能正确理解“本地优先不等于完全离线”，不会把第三方 Provider 出网误认为 RoundRelay 云端上传。 - -### 明确不做 - -- 不做新的院内即时通信工具，不替代钉钉或现有协作平台。 -- 不做远程多人群聊、云端频道和云端会话存储。 -- 不把“无人值守自治”作为近期卖点；任何多轮运行都必须可见、可停、有预算、有责任人。 -- 不以支持 Agent 数量作为核心成功指标。 -- 不承诺 RoundRelay 能提供操作系统级沙箱；上游 CLI 的权限标志必须经过真机验证。 -- 不在缺少效果对照前建设复杂的 Agent 市场、公共社区或跨设备同步。 - -### 目标版本内部发布稿 - -> RoundRelay 面向两院首批试点人员开放内部版本。研究员、工程师和产品人员可以在自己的电脑上，把已经安装的 Codex、Hermes、WorkBuddy、OpenCode 等 Agent 放进同一任务工作台，明确选择工作目录、读写权限和模型去向，让不同 Agent 分别提出方案、审查风险、补充证据并由用户确认最终结果。RoundRelay 不建立云端会话服务，也不替代现有多人协作工具；会话与编排状态保存在本机，但所选 Agent 或模型 Provider 仍可能访问网络，产品会在运行前清楚显示数据去向和权限范围。 - -### 名称与视觉系统 - -- **产品名：RoundRelay。** `Round` 同时指多轮讨论、不同视角和围绕同一任务的回合；`Relay` 指上下文、方案、证据和产物在异构 Agent 之间接力。名称直接表达“轮次讨论 + 能力接力”，比泛化的 Agent Hub、Agent Chat 更能承载产品差异。 -- **中文工作名：群智接力。** 适合两院内部沟通，强调集体审校和结果传递，不暗示无人自治。是否作为正式对外中文名，应在试点前由品牌负责人确认。 -- **Logo：3D Relay Fold。** 三段折叠箭带形成持续循环，分别表达提出、质询和收敛，也可理解为多个 Agent 围绕同一任务交换主导权。薄荷青玻璃金属与深石墨底提供未来软件感，明确避开齿轮、线路板和工业机械意象。 -- **资产规范。** `roundrelay-app.png` 使用透明画布的 3D 应用图标，`roundrelay-favicon.png` 是 64px 小尺寸版本，`roundrelay.png` 保留为深色背景上的产品主标；首启三张 GPT Image 2 示意图沿用明亮 3D 视觉。缩小场景可使用同一几何标记的简化表达，但不得改成齿轮、机械臂或复杂网络拓扑。 - -## 1. 事实基线：现在到底有什么 - -### 1.1 证据分级 - -本文采用四级证据，避免把愿景写成现状： - -| 级别 | 定义 | 可使用的表述 | -| --- | --- | --- | -| A：代码 + 自动化测试 + 已执行验证 | 有实现、测试，且仓库记录了实际执行结果 | “已实现并验证” | -| B：代码 + 自动化测试 | 有实现和测试，但没有完整真机或生产环境验证 | “已实现，待真机验证” | -| C：工作区开发中 | 代码处于未提交或未闭环状态，关键调用链缺失 | “开发中，不可视为已交付” | -| D：规划或假设 | 没有实现证据，或只有产品意图 | “计划、假设、待验证” | - -### 1.2 能力盘点 - -| 能力 | 状态 | 证据与边界 | 产品判断 | -| --- | --- | --- | --- | -| 本地优先 Electron 桌面端 | A | `README.md`、`docs/architecture.md`、`desktop/src/main.cjs`；无账号、应用服务器、远程会话服务 | 是产品底座，应保持，不应为短期便利引入必需云服务 | -| 受限 preload 与主进程 IPC | A | `desktop/src/preload.cjs`、`desktop/src/main.cjs`、主进程安全测试 | 当前最有价值的可信基础之一 | -| 9 类本地 Agent 检测与调用适配 | B | `desktop/src/cli-adapters.cjs`、`desktop/src/agent-installer.cjs` 及单元测试 | 代码支持不等于九类 Agent 在目标设备上都稳定可用；必须以兼容矩阵对外呈现 | -| 本地 Agent 单聊 | B | `LocalWorkspace.createGroup` 的 `direct` 类型、会话引用复用测试、前端直接会话入口 | 可作为最小价值入口，但不能只做成 CLI 包装器 | -| 单人 + 多 Agent 群聊 | B | 群组、消息、话题和 Agent 列表本地持久化；每个群组只有一个本机人类操作者 | “人 + Agent 群”不是多个人类远程协作群，必须在文案中说清楚 | -| 手动多 Agent 回复 | B | `LocalWorkspace.sendMessage` 按目标 Agent 顺序调用，失败相互隔离 | 适合可控审校；顺序调用延迟会随 Agent 数量线性增长 | -| 有界自动讨论 | B | `LocalWorkspace.startAuto`：最多 12 轮、总时长 30 分钟、可停止、全员同轮显式同意才提前结束 | 是“自动轮询讨论”，不是成熟自主辩论；一致同意标记只能表示模型自报状态 | -| 话题与 Agent 原生会话隔离 | B | 每个群组、话题、Agent 保存独立会话引用；最近上下文限制为 16 条、12000 字符 | 有利于连续工作，但长历史压缩、召回质量和性能尚未验证 | -| 工作目录默认只读、显式开启写入 | B | 群组级 `allowWrite` 与各适配器权限参数 | 产品方向正确，但不是 OS 沙箱；每类 Agent 必须独立做破坏性写入验证 | -| Provider 密钥安全存储 | A/B | `safeStorage`、0600 文件、URL 校验及测试；真实操作系统和企业镜像仍需验证 | 应继续保持失败关闭，不得新增明文兜底 | -| 固定白名单 Agent 安装 | B | 固定 npm 包或 HTTPS 安装脚本、敏感环境过滤、取消与安装后验证 | 上游包和脚本可变且未校验摘要，是内部扩散前的高优先级风险 | -| macOS 打包 | A（内部验证） | 仓库记录 arm64 DMG/ZIP、打包 UI 冒烟和 ad-hoc 签名 | 能内测，不能等同公开可分发版本 | -| Windows 发行 | D/B | 有 Windows 路径与安装逻辑，但无真实 Windows 发布设备验证、无 CI 发行证据 | 不应在宣传中写“正式支持 Windows” | -| 图片附件 | A/B | 已实现选择器/粘贴、私有附件存储、尺寸与完整性校验、ID 预览、消息持久化、删除回收、并发导入门槛、全失败消息防重复、等上下文预检，以及 Codex/Hermes/OpenCode 参数路由；前端 54/54、桌面 219/219 自动化已通过，打包版剪贴板导入和预览 IPC 已冒烟 | 已进入 Alpha 能力；仍须在目标设备用真实 Agent 验证版本兼容、Provider 外发和混合群组失败口径 | -| 本地 Skill 引用 | A/B | 已实现已安装 Agent 的本地目录扫描、清洗后的 IPC、`@` 选择、每目标重新校验、消息提示和目标隔离；Hermes 原生 `--skills` 预加载及其他 Agent 的定向上下文提示有自动化覆盖 | 已进入 Alpha 能力；仍须验证各 Agent 真实 Skill 发现规则、执行效果、提示注入风险和版本差异 | -| 首次引导 | A | 三张 GPT Image 2 使用示意图、单次启动检测、真实完成门槛、焦点/滚动/返回键行为已有前端测试，且打包 `.app` 已确认图片加载、背景 inert、无横向溢出和 `Start using` 状态 | 已交付为激活入口；下一步衡量首次回复时间和真实任务完成率，而不是继续扩页 | -| 结构化质询、证据核验、反方角色 | D | 当前没有角色、论点、证据、异议和裁决对象模型 | 是下一阶段核心产品能力，不应把现有自动讨论改名冒充 | -| 多个人类实时协作 | 明确不支持 | 架构文档明确只有一个本机人类操作者，无远程参与者或云频道 | 保持边界，通过现有协作工具分享结果 | -| 会话应用层加密、不可篡改审计 | D | 会话 JSON 未做应用层加密；只有本地状态，没有独立审计日志 | 高敏感任务进入试点前需确定制度与技术门槛 | - -### 1.3 现有自动讨论的准确描述 - -当前自动讨论具有真实实现，不应被低估，也不应被包装过度： - -1. 用户先发起一个话题，再选择自动讨论轮数。 -2. 系统按群组 Agent 顺序逐个调用，每个 Agent 看到同一话题下有限的最近对话。 -3. 提示词要求 Agent 在最后输出 `agree` 或 `continue` 标记。 -4. 只有所有 Agent 在同一完整轮次成功返回且都标记 `agree`，系统才提前结束。 -5. 系统支持失败隔离、后续轮次重试、用户停止、12 轮硬上限和 30 分钟总上限。 -6. 带图片的根消息会在启动前检查所有 Agent 能否获得同一组图片；任一目标不支持或数量不足时整轮不启动。Skill 保持目标隔离，不会跨 Agent 传播。 - -它尚未做到：指定提议者/反方/证据审查者、验证引用来源、判断分歧是否真正解决、比较方案得分、保留少数意见、生成可追踪结论、针对同模型相关性做校正。因此战略上应称为“有界多 Agent 接力讨论”，将“结构化质询与收敛”作为未来目标。 - -### 1.4 证据缺口 - -仓库目前没有以下产品证据： - -- 至少 5 次目标用户访谈及原始任务样本。 -- 真实用户留存、重复任务率、每周任务完成数。 -- RoundRelay 与“最强单 Agent”在同一任务上的盲评对照。 -- 多 Agent 发现了多少单 Agent 未发现且被人类验证的问题。 -- 用户为切换 CLI、复制上下文和合并结果实际花费的时间。 -- 高敏感数据是否允许进入第三方 Provider 的院内政策结论。 -- 九类 Agent 在目标 macOS/Windows 设备上的完整真机兼容结果。 - -因此，本文对技术现状的置信度较高，对需求强度和留存的置信度较低。方向判断约 70% 置信度，首要场景排序约 50%，指标目标属于试点假设，不是历史基线。 - -## 2. 问题定义 - -### 2.1 核心问题假设 - -两院内部已经使用多个本地 Agent 的研究员、工程师和产品人员，在高价值任务上面临三类摩擦： - -1. **上下文碎片化**：不同 CLI、终端和工具各自保存会话，用户反复复制背景、约束和中间结论。 -2. **结果整合成本高**：多个 Agent 可以给出不同答案，但用户仍需手工组织提议、反驳、验证和最终结论。 -3. **信任边界不清楚**：用户知道工具“在本机运行”，却未必知道所选 Agent、Provider、安装脚本和工作目录权限具体会把什么数据带到哪里。 - -这些是待验证问题，不是已证实事实。首轮发现研究必须回答：问题发生频率多高、现有替代方案是什么、什么任务的失败成本足够高，值得承担多 Agent 的额外时间和模型费用。 - -### 2.2 要交付的用户结果 - -RoundRelay 的用户结果不是“产生更多消息”，而是： - -> 用户用更少的切换和整合成本，得到一个经过独立质询、知道数据去向、能够追溯过程并可以直接继续执行的结果。 - -### 2.3 三层价值 - -| 层级 | 用户价值 | 当前成熟度 | 下一步 | -| --- | --- | --- | --- | -| 统一入口 | 首次引导、发现、安装、单聊和继续使用不同本地 Agent | 中 | 做真机兼容与首次成功率，不再增加泛化引导页 | -| 协作接力 | 多 Agent 在同一任务上下文中分工、回应和延续 | 中低 | 从聊天串升级为任务、角色和结果对象 | -| 可信审校 | 有证据的质询、分歧保留、可解释收敛和权限审计 | 低 | 建立结构化协议、评测和安全门槛 | - -战略上，统一入口是获客和激活能力，协作接力是使用价值，可信审校才可能形成长期差异化。 - -## 3. 目标用户与优先场景 - -### 3.1 首要用户 - -**首要用户：已经每周使用至少两个本地 Agent CLI、处理非公开代码或文档、需要对重要结果负责的两院知识工作者。** - -优先选择这类用户，因为他们已经承担安装、认证和本地环境成本，能立即感知切换与整合摩擦，也更可能评价多 Agent 是否真的增加价值。 - -| 用户 | 核心任务 | 现有替代 | 成功结果 | 不适合的原因 | -| --- | --- | --- | --- | --- | -| 研发工程师/架构师 | 方案设计、代码审查、故障根因、变更风险 | 多个终端、IDE Agent、人工复制上下文 | 找出关键缺陷并形成可执行修改计划 | 简单补全或机械改动用单 Agent 更快 | -| AI 产品经理/研究运营 | PRD 红队、需求澄清、竞品假设、验收标准 | 单模型聊天、人工评审会 | 更早暴露口径、依赖和失败条件 | 没有原始证据时，多 Agent 只会放大推测 | -| 研究员/技术研究人员 | 研究设计、论证审校、复现实验计划 | 文献工具、单模型问答、同事评审 | 形成带未决问题和证据缺口的审校结果 | 需要在线检索但未配置可信工具时，结论质量不可控 | -| 项目负责人 | 重大方案预演、风险清单、决策备忘录 | 会议、专家咨询、人工汇总 | 缩短准备时间并保留少数意见 | 最终责任不能交给 Agent 共识标记 | - -### 3.2 优先任务 - -| 优先级 | 场景 | 为什么适合多 Agent | 目标产物 | 初始试点建议 | -| --- | --- | --- | --- | --- | -| P0 | 代码/架构变更审查 | 可分为实现理解、反例、测试、安全和整合 | 风险清单、证据位置、修改建议、未决项 | 首批必测 | -| P0 | PRD/方案红队 | 不同角色可独立挑战目标、范围、依赖和验收 | 问题列表、决策建议、修订版验收标准 | 首批必测 | -| P1 | 故障根因与复盘预演 | 多路径假设和反证有价值 | 假设树、验证步骤、置信度 | 有真实脱敏样本后测试 | -| P1 | 研究设计与论证审校 | 需要方法、证据和反方视角 | 证据缺口、偏差风险、复现计划 | 需接入可靠资料后测试 | -| P2 | 长周期自主研究/开发 | 可能受益于多轮迭代 | 可执行成果与完整审计 | 仅在前述任务成立后探索 | - -### 3.3 非目标用户与非目标场景 - -- 只使用一个 Agent、主要做低风险简单问答的用户。 -- 需要手机端、多人实时聊天、云端共享频道的团队。 -- 希望系统在无人监督下长期运行并直接提交高风险修改的用户。 -- 需要 RoundRelay 代管模型账号、统一结算或组织权限的企业客户。 -- 把“多 Agent 回复更多”本身当作价值的展示型场景。 - -## 4. 定位、边界与差异化 - -### 4.1 类别定位 - -RoundRelay 不应定位为“AI 群聊软件”，也不应定位为“另一个云端 Agent 编排平台”。更准确的类别是： - -> **本地优先的多 Agent 任务审校与接力工作台。** - -“聊天”是交互外壳，“任务结果、权限边界和审校过程”才是产品本体。 - -### 4.2 替代方案比较 - -| 替代方案 | 擅长什么 | RoundRelay 必须胜出的地方 | RoundRelay 应主动承认的劣势 | -| --- | --- | --- | --- | -| 分别使用各 Agent CLI/终端 | 原生能力完整、用户熟悉、迭代最快 | 减少上下文搬运、统一任务连续性、形成跨 Agent 结果 | 原生 CLI 新功能会先到上游，适配层可能滞后 | -| 单一 IDE/代码 Agent | 深度编辑、工程上下文和操作闭环 | 对重要方案提供独立质询和异构视角 | 日常编码延迟更低，简单任务体验更顺畅 | -| 云端多 Agent 框架/平台 | 集中部署、远程协作、自动化扩展 | 本地状态、用户掌控权限、复用现有 CLI 与认证 | 不提供服务器级调度、组织管理和跨设备协同 | -| 通用聊天/协作工具 | 多人沟通、通知、文件共享、组织关系 | 在本机执行任务并保留 Agent 运行上下文 | 不应复制即时通信能力 | -| 人工专家评审 | 责任清晰、经验深、可处理组织语境 | 降低预审成本，让人工聚焦高价值判断 | 不能取代专家责任和最终审批 | - -### 4.3 差异化组合 - -单个能力都不构成护城河，真正值得投入的是以下组合： - -1. **本地控制面**：会话、任务状态、工作目录选择和编排在本机；没有 RoundRelay 云端会话依赖。 -2. **异构原生 Agent**：复用用户已经安装、认证和信任的 Agent，而不是把多个相同模型包装成不同角色。 -3. **结构化审校协议**：把提议、反例、证据、异议、裁决和最终产物变成可追踪对象。 -4. **权限与数据去向可见**：每次运行明确显示 Agent、Provider、网络去向、目录权限和可写范围。 -5. **真实任务评测资产**：积累两院场景的脱敏任务集、质量量表、失败样本和适配兼容数据。 - -最容易被复制的是“支持九个 Agent”和“一个群聊窗口”；最难复制的是经过真实任务证明的协议、评测集、政策适配和用户信任。 - -### 4.4 成本定位 - -RoundRelay 不追求最低推理成本，而追求高价值任务的风险降低和整合时间缩短。默认仍应优先单 Agent，只有在以下条件满足时才建议升级为多 Agent： - -- 任务失败代价高； -- 存在多个合理方案或明显盲区； -- 需要独立审查或反证； -- 用户愿意用更长等待换取更高置信度。 - -产品需要显示预计 Agent 数、轮数和可能耗时，避免“自动讨论”成为不可控的成本放大器。 - -### 4.5 Can't / Won't - -竞争者“不会做”或“难以同时做好”的部分，才值得作为长期防御： - -- 云端平台通常更适合集中管理，不一定愿意让本地 CLI、会话和目录成为一等公民。 -- 单 Agent 厂商不会优先支持竞争 Agent 的平等协作和结果对照。 -- 通用聊天工具不会深度承担 Agent 进程、权限、会话恢复和工作区副作用。 -- RoundRelay 自己也明确不做云端多人通信、模型托管和无限自治，以换取本地可信和产品聚焦。 - -## 5. 产品原则 - -1. **结果先于对话。** 每次高价值任务都应有目标、产物、验收和未决问题，不能以消息数量衡量成功。 -2. **单 Agent 默认，多 Agent 升级。** 简单任务不应强制组队；系统应解释什么时候值得增加 Agent。 -3. **人类拥有目标、权限和最终裁决。** Agent 可以提议和质询，不能替用户承担责任。 -4. **本地优先必须如实表达。** RoundRelay 不上传会话到自己的云端，不代表所选 Agent 或 Provider 不出网。 -5. **权限必须可见、最小且可撤回。** 默认只读；写入必须显式、可追踪、可比较、可回滚。 -6. **异构必须有实质意义。** 同一底层模型、同一提示词产生的多个角色不能被包装成“独立专家”。 -7. **分歧比虚假共识更有价值。** 允许保留少数意见、证据不足和无法裁决，不以全员同意作为唯一成功条件。 -8. **协议状态由程序管理。** 轮次、角色、预算、停止条件和失败处理应由确定性状态机控制，不能完全依赖提示词自报。 -9. **可复现优先于炫技。** 记录 Agent/版本/模型/Provider/权限/上下文范围和产物，支持重跑与对照。 -10. **保持单机架构简单。** 在证明需要前，不引入服务器、数据库集群、远程队列或微服务。 - -## 6. 目标产品模型 - -### 6.1 从“群聊”升级为“任务” - -建议逐步引入以下本地对象，仍可保存在单机持久化层，不需要服务器： - -| 对象 | 关键字段 | 作用 | -| --- | --- | --- | -| 任务 Task | 目标、背景、约束、验收、敏感级别、预算 | 防止对话偏离结果 | -| 参与者 Participant | Agent 类型、版本、模型/Provider、能力、角色 | 解释每个观点来自谁、能做什么 | -| 上下文包 Context Pack | 用户消息、选择文件、Skill、历史摘要、外发范围 | 让用户知道 Agent 实际收到什么 | -| 运行 Run | 协议、轮次、超时、调用序列、权限、状态 | 提供可停、可恢复、可审计的执行单元 | -| 论点 Claim | 结论、依据、提出者、置信度 | 支持质询和合并 | -| 异议 Objection | 针对论点、反例、严重度、状态 | 防止“大家都同意”掩盖未解决问题 | -| 证据 Evidence | 来源、片段、文件位置、验证状态 | 区分事实、推断和幻觉 | -| 产物 Artifact | 文档、代码 diff、清单、决策备忘录 | 把对话转为可继续工作的结果 | -| 裁决 Decision | 采用、拒绝、保留意见、责任人 | 明确人类最终责任 | - -### 6.2 推荐的结构化质询协议 - -首个协议只做一个，不建设通用工作流编辑器。建议选择“方案红队”协议： - -```text -用户定义任务与验收 - ↓ -提议者生成初稿 - ↓ -反方寻找关键反例和失败条件 - ↓ -证据审查者核对引用、代码位置或数据口径 - ↓ -整合者合并结论、保留未解决异议 - ↓ -用户接受、要求重跑或终止 -``` - -程序必须控制：角色分配、每步输入、最大轮数、每 Agent 超时、总预算、失败降级和停止条件。提示词负责内容生成，不负责决定系统是否“真的达成共识”。 - -### 6.3 停止条件 - -任一条件满足即可停止，不要求全员一致： - -- 用户接受当前产物； -- 所有高严重度异议已解决或明确转为“需人工判断”； -- 新一轮没有新增有效论点或证据； -- 达到时间、轮数或调用预算； -- 关键 Agent 连续失败； -- 数据去向或权限条件发生变化，需要用户重新确认。 - -### 6.4 能力清单而非统一假设 - -每个 Agent 应有可机器读取的能力清单，至少包括： - -- 操作系统与已验证版本； -- 是否支持原生会话恢复； -- 是否支持图片及数量限制； -- 是否支持本地 Skill 引用； -- 只读和写入模式的实际保障等级； -- 可使用的 Provider 与是否出网； -- 最大运行时长、取消可靠性和已知兼容问题。 - -混合群组发送图片、Skill 或写入请求前，系统应按目标 Agent 显示兼容结果。不能让不支持某能力的 Agent 静默失败，也不能把同一附件无差别传给所有 Agent。 - -## 7. 分阶段路线图 - -### 7.1 总体节奏 - -| 阶段 | 时间 | 目标 | 主要交付 | 决策门 | -| --- | --- | --- | --- | --- | -| 阶段 0：事实固化 | 第 0-2 周 | 把 Alpha 现状变成可重复验证的基线 | 真机矩阵、数据流说明、现有开发分支闭环、任务研究 | 能否稳定完成首批真实任务 | -| 阶段 1：可信工作台 | 第 3-6 周 | 让目标用户可靠完成单聊和受控群聊 | 能力清单、运行前确认、结果/产物、恢复与删除、内部签名包 | 激活和安全门槛 | -| 阶段 2：任务化协作 | 第 7-12 周 | 证明多 Agent 比人工切换更有价值 | 两个任务模板、角色分工、结果合成、评测埋点 | 对照实验是否达标 | -| 阶段 3：结构化质询 | 第 13-20 周 | 验证有证据的多轮质询与收敛 | 状态机、论点/异议/证据、人工裁决、预算 | 质量提升是否覆盖延迟和成本 | -| 阶段 4：发布扩展 | 达标后 | 扩大两院使用或准备外部发布 | 公证签名、升级、Windows、政策包、运维手册 | 组织是否愿意长期维护 | - -阶段 3 和阶段 4 不是承诺项。阶段 2 的实验证据不达标时，应停止自治扩展。 - -### 7.2 P0：现在必须做（第 0-6 周） - -| 优先级 | 工作项 | 成功标准 | 负责人角色 | 时间 | -| --- | --- | --- | --- | --- | -| P0 | 建立真实 Agent 兼容矩阵 | 目标 macOS 设备逐一验证检测、认证、首次调用、续聊、取消、只读、写入；未通过者默认隐藏或标实验 | Agent 集成工程师 | 2 周 | -| P0 | 完成图片、Skill 与首次引导的真机验收 | 现有 54/54 前端、219/219 桌面和打包 UI/IPC 冒烟保持通过；Codex/Hermes/OpenCode 图片、Hermes 原生 Skill、其他 Agent 定向 Skill 提示在目标 macOS 上逐项验证，失败能力明确降级 | 桌面工程师 + Agent 集成工程师 | 1 周 | -| P0 | 运行前数据去向与权限确认 | 用户能看到目标 Agent、Provider、是否出网、上下文来源和目录读写权限 | 产品 + 桌面工程师 | 3 周 | -| P0 | 任务结果对象 | 每次运行可保存“结论、异议、下一步、产物”；不是只能翻聊天记录 | 前端/桌面工程师 | 4 周 | -| P0 | 安装供应链收敛 | 安装版本可追踪；脚本/下载件校验摘要或签名；失败不执行 | 安全评审 + 桌面工程师 | 4 周 | -| P0 | 本地数据生命周期 | 导出、删除、备份/恢复行为清晰；异常退出后保留最后有效状态 | 桌面工程师 | 4 周 | -| P0 | 内部可分发 macOS 包 | 完成院内认可的签名/分发流程，干净设备可安装，升级/回退有方案 | 发布工程师 | 6 周 | -| P0 | 发现研究与基线任务集 | 8-12 次访谈、20 个脱敏任务、现有流程耗时和质量基线 | PM + 研究支持 | 2 周 | - -### 7.3 P1：随后验证（第 7-12 周） - -| 优先级 | 工作项 | 成功标准 | 负责人角色 | 时间 | -| --- | --- | --- | --- | --- | -| P1 | “代码/架构审查”任务模板 | 能生成有文件位置、严重度、证据和修改建议的结果 | 产品 + Agent 工程师 | 3 周 | -| P1 | “PRD/方案红队”任务模板 | 能区分事实、假设、反例、依赖、非目标和未决项 | 产品 + Agent 工程师 | 3 周 | -| P1 | 角色化接力 | 用户可选择或接受推荐角色；每个角色输入输出清晰 | Agent 工程师 | 4 周 | -| P1 | 结果对照与盲评 | 同一任务可对照单 Agent 与 RoundRelay 结果，评审人不知道来源 | PM + 评测负责人 | 4 周 | -| P1 | 运行成本与时间预算 | 开始前显示预算，运行中可见进度，达到上限自动停止 | 桌面工程师 | 3 周 | -| P1 | 本地运行来源记录 | 保存 Agent/版本/模型/Provider/权限/协议/产物引用，支持导出 | 桌面工程师 | 4 周 | - -### 7.4 P2：有证据后再做（第 13-20 周） - -- 论点、异议、证据和裁决的结构化状态机。 -- 基于严重度和未解决问题的停止条件，而不是单一共识标记。 -- 任务中途的人类检查点、重定向和角色替换。 -- 同模型/同 Provider 相关性提示和角色多样性约束。 -- 长历史摘要与上下文选择，但必须可见、可纠正、可重放。 -- 对失败 Agent 的降级策略和部分结果交付。 -- 适用于两院具体工作流的本地策略包与模板包。 - -### 7.5 Later：暂不排期 - -- Windows 正式发行和自动升级。 -- 远程多人协作、跨设备同步、组织账号、云端会话。 -- 自定义可视化工作流编排器。 -- 公共 Agent/Skill 市场。 -- 无人值守长周期自治任务。 -- 商业化定价、外部开放注册和大规模市场推广。 - -## 8. 指标与评测 - -### 8.1 北极星指标 - -**每周被用户采纳的高价值任务数。** - -“采纳”必须由用户明确标记为以下之一：直接使用、轻改使用、进入正式评审或产生被保留的工作区产物。只发送消息、完成一轮调用或模型自报共识都不算采纳。 - -### 8.2 当前阶段唯一关键指标 - -在第 12 周前，唯一关键指标是： - -> **试点用户提交的目标任务中，被标记为“直接使用或轻改使用”的任务比例。方向性门槛为 60%。** - -相对用户当前最佳单 Agent 的 20% 盲评质量或风险发现提升是配对实验的扩大决策门槛，不与采纳率拼成一个不可诊断的复合指标。两项当前基线均未知；小样本阶段只能作为方向性证据。 - -### 8.3 指标体系 - -| 类型 | 指标 | 试点目标 | 说明 | -| --- | --- | --- | --- | -| 激活 | 安装后 15 分钟内成功完成首个 Agent 回复 | >= 70% | 排除缺少 Agent/认证的非目标用户后计算 | -| 激活 | 7 天内完成首个多 Agent 目标任务 | >= 40% | 不是随意群聊 | -| 价值 | 直接使用或轻改使用率 | >= 60% | 用户任务级标记 | -| 价值 | 相对最佳单 Agent 的盲评提升 | >= 20% | 质量或风险发现至少一项 | -| 效率 | 从任务开始到可用结果的总人工时间 | 降低 >= 30% | 计入用户整合和返工，不只算模型延迟 | -| 质量 | 经人工验证的新增关键问题数 | 每个适用任务 >= 1 | 只算单 Agent 未发现且确实成立的问题 | -| 留存 | 目标用户第 4 周仍每周使用 | >= 35% | 样本量较小时同时报告人数 | -| 可靠性 | Agent 调用非用户原因失败率 | < 5% | 按 Agent/版本拆分 | -| 可靠性 | 停止命令在 5 秒内终止进程树 | >= 99% | 真机验证 | -| 安全 | 未授权工作区写入 | 0 | 一票否决 | -| 安全 | Provider/密钥/可执行路径泄露到渲染层或日志 | 0 | 一票否决 | -| 隐私 | 未告知的数据外发 | 0 | 一票否决 | -| 成本 | 每个被采纳任务的 Agent 调用数/耗时 | 持续下降 | 防止用无限轮数换质量 | - -### 8.4 对照实验 - -每个优先场景先准备至少 10 个脱敏任务做方向性试点，采用配对交叉设计： - -1. 为同一任务准备等价输入和统一交付要求，由同一用户分别使用当前最佳单 Agent 与 RoundRelay；顺序随机并做交叉平衡，避免学习效应固定偏向后一种工具。 -2. 预先指定一个主要结果，例如总盲评分或关键风险发现率；其他维度作为次要结果，避免试验结束后挑最有利指标。 -3. 至少两名领域评审独立盲评，使用固定 1-5 分量表评估正确性、完整性、关键风险、可执行性和证据质量，并记录拒用原因。 -4. 报告配对差值、相对与绝对提升、样本量和 95% 置信区间；小样本可使用 bootstrap 区间，但不得仅凭点估计宣称“统计显著”。 -5. 报告评审一致性：序数总分优先使用加权 Cohen's kappa，连续汇总分可使用 ICC；一致性不足时先校准量表，不进入扩大决策。 -6. 同时记录总等待时间、用户操作时间、返工时间、调用次数和最终采纳。多 Agent 只有在质量收益覆盖时间与成本时才进入默认推荐。 - -每场景 10 个任务只用于发现方向、量表问题和明显失败，不足以单独证明普遍或显著优势。扩大试点前应根据观察方差补充配对样本，并报告不同用户和任务类型下是否方向一致。不要用“用户觉得很酷”“产生了更多观点”作为通过依据。 - -## 9. 架构、安全与隐私门槛 - -### 9.1 目标架构原则 - -继续保持单机 Electron 架构，但在代码职责上逐步形成五层： - -```text -Vue 渲染层 - -> 窄 preload API - -> Electron 主进程 - |- 策略与授权层：数据去向、目录权限、预算、用户确认 - |- 编排状态机：角色、轮次、停止、失败降级 - |- 上下文与产物层：消息、文件引用、Skill、结果、审计 - |- Agent 适配层：能力清单、参数、会话、取消、输出解析 - `- 本地持久化与安全存储 - -> 本机 Agent CLI / 用户批准的 Provider / 白名单安装源 -``` - -近期不拆微服务。若 `LocalWorkspace` 同时承担持久化、提示构造、编排和运行状态的复杂度开始阻碍测试，再按上述边界拆分；不是为了“架构漂亮”提前重写。 - -### 9.2 隐私真相 - -产品必须在 UI 和文档中同时表达以下事实： - -- 群组、消息和编排状态不上传到 RoundRelay 自有云端。 -- Agent CLI 可能根据自身配置访问外部模型、更新服务或工具。 -- 用户配置的 Provider 会收到被传入的提示、选中文件内容或工具结果。 -- 本地 JSON 会话未做应用层加密，安全性依赖设备账号、磁盘加密和本地访问控制。 -- Agent 进程拥有本地操作系统用户权限；RoundRelay 的只读参数不是完整 OS 沙箱。 - -任何“完全本地”“数据绝不出机”的宣传都必须经过运行模式限定。建议使用三种明确标签： - -| 模式 | 条件 | 可用文案 | -| --- | --- | --- | -| 本地状态 | 会话和编排状态只保存在本机 | “RoundRelay 不上传会话状态” | -| 批准出网 | Agent 使用用户批准的外部 Provider | “内容将发送至：具体 Provider/地址” | -| 受控本地推理 | 所有目标 Agent 指向经批准的本地或内网模型，且网络检查通过 | “本次运行未配置公网模型出口” | - -### 9.3 发布前安全门槛 - -| 门槛 | 要求 | 未通过时处理 | -| --- | --- | --- | -| IPC 与渲染层边界 | 新 API 采用固定方法、主帧校验、严格入参；不暴露路径、密钥和任意 shell | 不合入 | -| Agent 能力验证 | 每类 Agent 独立验证读取、写入、取消、会话、附件和错误输出 | 标记实验或禁用相关能力 | -| 写入可逆 | 写入前显示范围；运行后展示 diff/变化；高风险删除或覆盖需再次确认；有恢复方案 | 只读开放，写入关闭 | -| Provider 外发 | 运行前可见地址、模型、目标 Agent 和上下文类型；切换 Provider 要重新确认 | 禁止运行 | -| 安装供应链 | 固定版本，校验摘要/签名，下载大小和域名受限，安装日志脱敏 | 关闭一键安装，改为文档引导 | -| 数据生命周期 | 导出、删除、备份恢复、异常退出恢复有测试 | 限制为低敏试点 | -| 本地数据保护 | 明确设备磁盘加密基线；高敏场景决定是否需要应用层加密与自动锁定 | 不进入高敏场景 | -| 审计来源 | 本地记录 Agent、版本、模型、Provider、权限、协议、开始/结束/停止原因 | 不用于正式决策留痕 | -| 应用分发 | 内部认可的签名、完整性校验、回滚与版本标识 | 不扩大试点 | -| 隐私验证 | 空闲启动无意外连接；每种 Agent 模式建立预期出网清单 | 不宣称受控本地模式 | - -### 9.4 高风险设计提醒 - -- **附件混合路由**：当前适配器仅 Codex、Hermes 和 OpenCode 支持图片，且数量上限不同。现有实现会在不等上下文时整轮拒绝；真机验证仍须确认上游版本不会静默忽略参数。 -- **Skill 引用**：渲染层只应看到经清洗的标识和名称，主进程重新校验并解析；不能让前端提供任意本地路径。 -- **提示词注入**：本地文件和 Skill 同样是不可信输入。系统提示、权限和停止条件不能由被读取内容覆盖。 -- **共识伪装**：Agent 输出标记只能作为协议输入，不能直接等同事实正确或组织批准。 -- **同源偏差**：多个 Agent 可能使用同一模型或 Provider。产品应显示实际多样性，避免虚假独立性。 -- **本地状态损坏**：当前 JSON 适合 Alpha；长历史、异常退出、并发写入和迁移需要专门测试。只有出现真实性能或一致性瓶颈时才评估 SQLite。 - -## 10. 两院试点与内部 GTM - -### 10.1 试点目标 - -内部 GTM 的目的不是获得下载量，而是回答三个问题： - -1. 哪两类任务值得多 Agent？ -2. RoundRelay 是否比用户自己切换多个 CLI 更省时间、更可靠？ -3. 两院能否在不制造错误安全感的前提下接受它的数据与权限模型？ - -### 10.2 试点人群 - -建议招募 12-20 名设计伙伴，分三组： - -| 组别 | 人数建议 | 条件 | 任务 | -| --- | --- | --- | --- | -| 工程组 | 5-8 | 每周使用本地代码 Agent | 代码/架构审查、故障假设 | -| 产品与研究运营组 | 4-6 | 经常写方案、PRD、评审材料 | 方案红队、需求澄清 | -| 研究组 | 3-6 | 有可脱敏研究设计或技术文档 | 方法审校、证据缺口 | - -优先招募现有 CLI 用户，不从“不会安装或认证任何 Agent”的大众用户开始。前两周只使用公开或低敏脱敏任务，高敏任务必须等隐私门槛和院内政策确认。 - -### 10.3 六周试点节奏 - -| 周次 | 动作 | 输出 | -| --- | --- | --- | -| 第 0 周 | 访谈、现有流程观察、采集脱敏任务 | 问题证据、基线耗时、任务集 | -| 第 1 周 | 安装与首次任务陪跑 | 激活漏斗、兼容问题、认知误区 | -| 第 2 周 | 单聊与手动多 Agent 审校 | 失败日志、第一次采纳率 | -| 第 3-4 周 | 两个任务模板和对照实验 | 盲评、时间、成本、风险发现 | -| 第 5 周 | 结构化角色的低保真验证 | 是否需要更复杂编排 | -| 第 6 周 | 复盘与继续/收缩/停止决策 | 决策备忘录与下一阶段范围 | - -### 10.4 渠道与运营 - -- 通过现有院内协作渠道招募和发布版本，不在 RoundRelay 内建设远程社交或通知系统。 -- 每位试点用户有一个明确任务场景和一名产品联系人。 -- 每周发布一页状态：任务数、采纳率、失败、隐私/权限事件、已知兼容问题、范围变更。 -- 建立本地诊断包导出，默认脱敏，用户确认后才能分享给支持人员。 -- 版本说明必须区分“已验证 Agent”“实验 Agent”“仅检测未验证 Agent”。 - -### 10.5 试点决策门 - -| 决策 | 条件 | -| --- | --- | -| 扩大试点 | 安全一票否决项为 0；目标任务采纳率点估计 >= 60%；至少一个场景相对单 Agent 的预设主要结果点估计提升 >= 20%；同时披露分子/分母、配对样本量、评审一致性和 95% 置信区间。小样本达标只允许有限扩样，不得宣称统计显著 | -| 保持小范围继续探索 | 用户价值有信号但效果不稳定；可明确归因于一个可修复瓶颈 | -| 收缩为统一 Agent 工作台 | 单聊有留存，但多 Agent 质量/效率没有优势 | -| 停止自治方向 | 多轮质量不升反降、成本/延迟明显失控，或用户始终偏好人工切换 | -| 停止试点 | 出现未授权写入、未告知外发、密钥泄露或无法恢复的数据损坏 | - -## 11. 组织与资源 - -### 11.1 最小可行团队 - -| 角色 | 建议投入 | 责任 | -| --- | --- | --- | -| 产品负责人 | 0.5-1 人 | 用户研究、范围、试点、指标、决策日志 | -| Electron/桌面工程师 | 1 人 | IPC、安全存储、持久化、打包、系统集成 | -| Agent 集成/评测工程师 | 1 人 | CLI 适配、协议状态机、真机矩阵、评测集 | -| 前端/交互工程师 | 0.5-1 人 | 任务化 UI、结果/异议视图、可访问性 | -| 安全与 IT 评审 | 0.2-0.5 人 | 数据政策、供应链、签名分发、威胁评审 | -| 领域设计伙伴 | 每个场景 2-3 人 | 提供任务、盲评结果、解释错误成本 | - -如果只有两名全职工程师，应先覆盖 macOS、Codex/Hermes/OpenCode 等少量高使用 Agent 和两个任务场景。不要同时承诺九类 Agent 真机支持、Windows、公证发布、复杂自治和高敏数据。 - -### 11.2 所有权 - -每个路线图项必须有一个 DRI。推荐所有权： - -- PM：首要用户、任务集、指标、范围变更、试点决策。 -- 桌面工程负责人：本地数据、IPC、权限、分发、异常恢复。 -- Agent 工程负责人：能力清单、适配器、协议、评测、兼容降级。 -- 安全评审人：外发口径、安装供应链、写入门槛、高敏数据准入。 -- 场景负责人：确认输出是否真正可用，而不是只看模型自评。 - -### 11.3 工作节奏 - -- 每周一次兼容矩阵与安全问题评审。 -- 每周一次试点数据复盘，先看任务结果，再看功能反馈。 -- 每两周一次版本候选，未通过退出条件不扩大用户。 -- 所有中途新增需求进入范围变更表，明确接受、延后或拒绝。 -- 每四周复审战略假设，尤其是“多 Agent 是否有净收益”。 - -## 12. 风险与反例 - -| 风险/反例 | 为什么重要 | 早期信号 | 对策 | -| --- | --- | --- | --- | -| 多 Agent 放大同一个错误 | 多个角色可能共享模型、数据和偏差 | 答案措辞不同但事实错误一致 | 显示模型/Provider 同源性；引入证据审查；与单 Agent 基线对照 | -| 群聊比终端更慢 | 顺序调用延迟线性增加 | 用户等待后仍复制结果回原 CLI | 默认单 Agent；只在高价值任务推荐多 Agent；提供进度与预算 | -| 用户要的是产物，不是讨论 | 长对话难复用 | 用户频繁手工总结或复制到文档 | 把结论、异议、下一步和文件 diff 做成一等对象 | -| “本地”造成错误隐私预期 | Agent 仍可能把上下文发给外部 Provider | 用户无法说出数据去了哪里 | 运行前外发说明、Provider 标识、受控本地模式验证 | -| 上游 CLI 快速变化 | 参数、输出和认证随版本改变 | 升级后静默解析错误或只读失效 | 固定兼容版本、真机回归、能力降级、适配器契约测试 | -| 写入权限造成破坏 | CLI 以本机用户权限运行 | 只读模式仍有文件变化，或写入超出目录 | 默认只读、文件变化审计、禁用未验证写入、恢复与确认 | -| 自动共识不可信 | 模型可迎合提示或错误输出标记 | 快速全员同意但人类盲评低 | 共识不等于结束；使用异议/证据/人工裁决状态 | -| 一次性新鲜感 | 多 Agent 界面有吸引力但没有重复价值 | 首周高使用、第四周归零 | 只围绕重复任务优化；用周采纳任务数而非消息数 | -| 支持面过宽 | 九类 Agent、两系统、附件、Skill 同时推进 | 兼容问题占据大部分研发时间 | 根据真实使用率收缩支持矩阵；实验能力显式降级 | -| 本地 JSON 达到瓶颈 | 长历史、迁移和崩溃恢复未验证 | 启动变慢、文件膨胀、恢复失败 | 建性能阈值和迁移测试；达到门槛后再考虑 SQLite | -| 院内使用无法运维 | 无账号服务器也意味着远程诊断有限 | 每台机器问题无法复现 | 本地脱敏诊断包、版本/能力清单、可重放测试，不上传会话 | -| 远程多人诉求牵引产品漂移 | 两院协作天然会提出共享需求 | 团队开始建设账号、频道、通知 | 结果通过现有协作工具分享；是否做远程协作需独立战略评审 | - -### 12.1 什么时候不该使用 RoundRelay - -- 任务答案明确、失败成本低、最佳单 Agent 几分钟即可完成。 -- 所有 Agent 实际指向同一模型，且没有独立证据或工具差异。 -- 用户需要多人实时共编、审批和组织通知。 -- 工作区包含不允许发送到当前 Provider 的敏感内容。 -- 用户无法监督过程，却希望 Agent 直接执行不可逆操作。 - -把这些反例做进产品提示，比强行扩大使用率更能建立信任。 - -## 13. 预演失败（Pre-mortem） - -假设 6 个月后 RoundRelay 试点失败，最可能出现以下情形： - -| 失败情形 | 根因 | 预防动作 | 责任人 | -| --- | --- | --- | --- | -| 大家试了一次，没人每周回来 | 产品优化了群聊观感，没有嵌入真实重复任务 | 用 20 个真实任务先定义模板；周采纳任务数作为北极星 | PM | -| 多轮讨论很长，但结果不比单 Agent 好 | 角色只是提示词扮演，缺少独立信息和证据 | 建单 Agent 对照；没有净提升就停止复杂自治 | PM + 评测负责人 | -| 发生敏感内容意外出网 | 用户把“本地应用”理解为“模型不出网” | 运行前显示 Provider/地址/上下文；高敏模式只允许批准端点 | 安全负责人 | -| Agent 修改了不应修改的文件 | 过度依赖上游只读标志，缺少变化检测 | 未经真机验证的 Agent 禁止写入；运行后展示并可恢复 diff | 桌面负责人 | -| 上游升级后大量 Agent 失效 | 没有版本策略和兼容矩阵 | 固定已验证范围、自动契约测试、实验标识、快速禁用 | Agent 集成负责人 | -| 研发被 Windows、市场、同步和工作流编辑器拖散 | 路线图没有明确非目标和决策门 | 每次新增范围必须说明牺牲项；阶段 2 未达标不启动阶段 3/4 | 产品负责人 | -| 无法通过院内安全审查 | 供应链、数据生命周期、审计和签名后补 | 第 0 周引入安全评审；按发布门槛逐项收口 | 项目负责人 | - -## 14. 版本退出标准 - -### 14.1 内部 Alpha 退出标准（进入 12-20 人试点） - -- [ ] 目标 macOS 设备上至少 3 个高优先 Agent 完成检测、认证、调用、续聊、取消、只读及其声明的图片/Skill 能力真机验证。 -- [ ] 未通过验证的 Agent/能力在 UI 中明确标为实验或默认隐藏。 -- [ ] 运行前可见 Agent、Provider/出网、工作目录和读写权限。 -- [ ] 手动多 Agent 与有界自动讨论均可中止，进程树在门槛内结束。 -- [x] 图片与 Skill 已完成渲染层、窄 IPC、主进程校验、持久化/回收、目标路由和自动化测试闭环；真实 Agent 兼容性仍由前两项门槛控制。 -- [x] 首次引导已完成检测门槛、键盘/返回关闭、滚动锁、双语和打包 UI 冒烟；真实首次成功率仍需试点数据验证。 -- [ ] 工作区数据可导出、删除；异常退出恢复测试通过。 -- [ ] 没有渲染层路径/密钥泄露，没有未授权写入。 -- [ ] 内部分发包来源和版本可验证，安装回退方式已记录。 -- [ ] 已完成 8-12 次访谈和 20 个脱敏基线任务。 - -### 14.2 封闭 Beta 退出标准（扩大院内使用） - -- [ ] 目标任务“直接使用或轻改使用”率点估计 >= 60%，并报告分子/分母及 95% 置信区间。 -- [ ] 至少一个场景相对最佳单 Agent 的预设主要结果点估计提升 >= 20%，配对样本、评审一致性和区间估计均已披露，且不同用户/任务子组没有明显反向信号。 -- [ ] 第 4 周目标用户周留存 >= 35%，同时报告绝对人数。 -- [ ] 非用户原因 Agent 调用失败率 < 5%，按 Agent/版本可追踪。 -- [ ] 未告知外发、密钥泄露、未授权写入均为 0。 -- [ ] 安装件版本与完整性可校验，干净设备安装验证通过。 -- [ ] 关键运行来源和结果可本地导出，问题可由脱敏诊断包复现。 -- [ ] 至少两个任务模板由对应领域负责人确认“比聊天记录更可用”。 - -### 14.3 1.0 退出标准（考虑更广分发） - -- [ ] 连续两个版本周期达到 Beta 价值和安全门槛。 -- [ ] macOS 正式签名、公证、升级和回滚完成；Windows 若宣称支持则有独立真机与 CI 证据。 -- [ ] 数据分类、Provider 准入、日志/审计和本地数据保护通过院内评审。 -- [ ] 上游 CLI 版本兼容政策、停用机制和维护责任明确。 -- [ ] 结构化质询在至少一个场景证明净收益；否则 1.0 不包含自治卖点。 -- [ ] 支持、故障响应、发布节奏和长期维护人员已确定。 -- [ ] 所有公开表述经过事实核对，不把“本地状态”宣传成“任何数据绝不出机”。 - -## 15. 关键开放问题 - -以下问题必须在进入阶段 1 前明确负责人和截止日期： - -| 问题 | 为什么必须回答 | 建议负责人 | 截止 | -| --- | --- | --- | --- | -| 首要用户到底是工程、产品还是研究人员？ | 决定任务模板、评测量表和 Agent 支持优先级 | PM | 第 1 周 | -| 哪些数据级别允许进入哪些 Provider？ | 决定试点边界和“受控本地模式” | 安全/数据负责人 | 第 2 周 | -| 首批正式验证哪 3-4 个 Agent？ | 避免九类 Agent 平均用力 | PM + Agent 工程师 | 第 1 周 | -| “可用结果”由谁判定、如何盲评？ | 防止用模型自评替代业务结果 | PM + 场景负责人 | 第 2 周 | -| 写入模式需要何种恢复保证？ | 决定是否能进入真实代码和文档任务 | 桌面负责人 | 第 3 周 | -| 会话是否需要应用层加密？ | 影响高敏数据准入、搜索和恢复设计 | 安全 + 架构负责人 | 第 3 周 | -| 中文工作名“群智接力”是否只用于内部？ | 避免品牌与产品定位混乱 | 产品/品牌负责人 | 试点前 | -| Windows 是否是试点硬要求？ | 若是，会显著改变资源和时间线 | 项目负责人 | 第 1 周 | - -## 16. 接下来 10 个工作日 - -1. 冻结一个 Alpha 能力清单，逐项标记已验证、实验、开发中和不支持。 -2. 选择首批 3-4 个 Agent 和两类目标任务，不再平均覆盖九类 Agent。 -3. 完成 8-12 次用户访谈，收集 20 个脱敏真实任务及当前流程基线。 -4. 在两台干净 macOS 设备执行检测、认证、首次调用、续聊、取消、只读和写入矩阵。 -5. 在目标 macOS 上验收图片、Skill 与首次引导：验证 Codex/Hermes/OpenCode 图片参数、Hermes 原生 Skill、其他 Agent 定向 Skill 提示、干净用户首次检测，并把失败项降级为实验或禁用。 -6. 设计运行前数据去向/权限确认和任务结果页的低保真原型，先做可用性验证。 -7. 建立单 Agent 对照量表和试点评测表，不等功能完成后再补指标。 -8. 与安全/IT 负责人确认 Provider、数据级别、安装源、签名和本地数据保护门槛。 -9. 发布第一份每周状态模板，固定报告范围变化、风险、验证证据和下周决策。 -10. 第 10 个工作日召开继续/收缩评审，只批准阶段 1 的必要范围。 - -## 附录 A：战略画布 - -| 要素 | RoundRelay 选择 | -| --- | --- | -| 愿景 | 让高价值知识工作在用户掌控数据与权限的前提下，获得多种 Agent 能力的独立审校与可执行接力 | -| 首要细分 | 已使用多个本地 Agent、处理非公开任务、需要对结果负责的两院知识工作者 | -| 成本定位 | 不追求最低调用成本，追求重要任务的风险降低和整合时间节省 | -| 价值主张 | 从手工切换与复制上下文，转为一个本地、可控、可追溯的任务工作台 | -| 关键取舍 | 当前 RoundRelay 不做云端群聊、远程参与者、无限自治、模型托管和泛化工作流平台；完整两院混合平台作为独立上层战略评审 | -| 北极星 | 每周被用户采纳的高价值任务数 | -| 增长方式 | 两院设计伙伴驱动，先深做两个任务场景，再扩 Agent 和用户 | -| 核心能力 | Electron 安全边界、Agent 适配、本地 Skill/附件上下文、结构化协议、评测、数据去向与权限治理 | -| 防御性 | 经验证的任务协议、脱敏评测集、兼容矩阵、政策适配和长期信任，而非 Agent 数量 | - -## 附录 B：主要事实来源 - -- `README.md`：产品边界、支持 Agent、开发与发布状态。 -- `desktop/README.md`：本地运行、Provider、安装和 Agent 支持矩阵。 -- `docs/architecture.md`：组件、信任边界、本地数据、网络面和已知风险。 -- `docs/permissions.md`：Renderer/Main/Agent 权限矩阵和限制。 -- `docs/flows.md`：启动、Provider、安装、会话和自动讨论流程。 -- `docs/automation.md`：自动讨论边界、停止、失败与外部副作用。 -- `docs/tests.md`：已执行验证、自动化覆盖和明确测试缺口。 -- `desktop/src/local-workspace.cjs`：单聊/群聊、持久化、上下文、会话引用、顺序调用和自动讨论实现。 -- `desktop/src/cli-adapters.cjs`：Agent 调用参数、输出解析、会话与权限适配。 -- `desktop/src/main.cjs` 与 `desktop/src/preload.cjs`：Electron 信任边界和对渲染层开放的能力。 -- 当前工作区差异：图片附件、本地 Skill、首次引导、群组创建修复和 3D 品牌资产已完成实现与本轮可引用的自动化验证；打包 `.app` 另完成首启、群组创建、Skill 菜单、剪贴板图片预览、ASAR 资产/源码和退出清理冒烟。本文将其计为 Alpha 已实现能力，但不把自动化与打包冒烟替代真实 Agent 兼容矩阵、用户价值验证或公开发布证据。 diff --git a/docs/assets/harness-engine-architecture.prompt.txt b/docs/assets/harness-engine-architecture.prompt.txt deleted file mode 100644 index e85a5b7..0000000 --- a/docs/assets/harness-engine-architecture.prompt.txt +++ /dev/null @@ -1,15 +0,0 @@ -Use case: style-transfer -Asset type: README technical architecture infographic -Input images: Image 1: the attached flat Meldwork Harness Engine architecture diagram is a structural reference only; preserve its system semantics, but completely redesign the composition, visual language, and module arrangement. -Primary request: Redesign the Meldwork Harness Engine architecture as a premium product-grade AI systems map. Do not use a flat five-row table. Build a spatial architecture around a central 3D control core labeled "HARNESS CORE". The diagram must explain how a user request becomes streamed Agent work, compressed shared context, durable state, and recoverable execution. -Scene/backdrop: deep graphite documentation canvas, subtly textured like a dark technical presentation board; no scenery -Subject and information architecture: center = a beveled dark navy 3D control module titled "HARNESS CORE" with four clear responsibilities around it: "RUN CONTROL", "CONTEXT PACK", "SESSION REGISTRY", "RECOVERY". Upper-left = a 3D conversation surface module labeled "CONVERSATION SURFACES" with two smaller cards "DIRECT CHAT" and "GROUP CHAT"; direct chat connects to "INLINE STREAM", group chat connects to "TRACE PANEL". Upper-right = a media-inspired event module labeled "STREAMING EVENTS" with a waveform strip, playhead markers, and compact event chips labeled "ANSWER DELTA", "TOOL", "PLAN", "STATUS". Left-middle = a stacked translucent capsule module labeled "COMPRESSED SHARED CONTEXT" with smaller tags "STABLE CONSTRAINTS", "RECENT CONCLUSIONS", "EVIDENCE CAPSULES". Right-middle = an Agent runtime constellation with separate beveled tiles labeled "CODEX", "HERMES", "OPENCLAW", and a bridge tile "AGENT ADAPTERS" leading to "TOOL CALLS". Bottom = a horizontal durable-state vault labeled "DURABLE STATE" containing four compact modules "RUN JOURNAL", "RUN LEDGER", "WORKSPACE STATE", "RECOVERY CHECKPOINTS". Include a visible circular session token ring around the core labeled "NATIVE SESSION" and a small arrowed loop labeled "SESSION ROTATION". -Flow semantics: cyan arrows flow from CONVERSATION SURFACES into HARNESS CORE, from HARNESS CORE into COMPRESSED SHARED CONTEXT and AGENT ADAPTERS, from Agent runtime into STREAMING EVENTS and back to the UI. A coral recovery loop labeled exactly "401 RETRY / RECOVERY" and a second coral loop labeled "AGENT TIMEOUT" return from the Agent runtime to HARNESS CORE. Teal persistence lines flow down from HARNESS CORE and Agent runtime into DURABLE STATE. Keep every relationship readable and avoid crossing arrows through text. -Style/medium: high-end 3D technical infographic, dark-mode product architecture board, isometric-lite extruded modules with crisp edges, restrained glass and metal materials, subtle ambient occlusion, precise vector-like labels over 3D forms, premium enterprise systems design, not concept art -Composition/framing: 16:9 landscape, balanced asymmetrical composition with the core slightly left of center and runtime constellation on the right; title at top "Meldwork Harness Engine"; generous margins; modules large enough for README viewing; clear visual hierarchy; no numbered sections -Color palette: graphite and near-black background; dark navy core; electric cyan data paths; teal context and persistence paths; coral recovery paths; violet trace accents; white text; muted silver secondary text -Lighting/mood: cinematic but restrained, soft rim light around the core, controlled highlights on bevels, no dramatic lens flare -Materials/textures: beveled matte metal, translucent context capsules, subtle holographic event chips, waveform and timeline marks, thin luminous connectors -Text (verbatim): "Meldwork Harness Engine", "HARNESS CORE", "RUN CONTROL", "CONTEXT PACK", "SESSION REGISTRY", "RECOVERY", "CONVERSATION SURFACES", "DIRECT CHAT", "GROUP CHAT", "INLINE STREAM", "TRACE PANEL", "STREAMING EVENTS", "ANSWER DELTA", "TOOL", "PLAN", "STATUS", "COMPRESSED SHARED CONTEXT", "STABLE CONSTRAINTS", "RECENT CONCLUSIONS", "EVIDENCE CAPSULES", "CODEX", "HERMES", "OPENCLAW", "AGENT ADAPTERS", "TOOL CALLS", "DURABLE STATE", "RUN JOURNAL", "RUN LEDGER", "WORKSPACE STATE", "RECOVERY CHECKPOINTS", "NATIVE SESSION", "SESSION ROTATION", "401 RETRY / RECOVERY", "AGENT TIMEOUT" -Constraints: preserve the above semantics; all labels must be spelled exactly; use only these labels and no extra prose; prioritize readability over decorative detail; modules must look like one coherent system; show arrows with distinct colors and arrowheads; no logos, no watermark, no fake terminal screenshot, no code blocks -Avoid: flat stacked rows, generic flowchart boxes, white background, pastel corporate template, excessive gradients, neon overload, random 3D objects, tangled connectors, tiny labels, spelling errors, extra captions, stock icons diff --git a/docs/automation.md b/docs/automation.md deleted file mode 100644 index 290b4a3..0000000 --- a/docs/automation.md +++ /dev/null @@ -1,96 +0,0 @@ -# Automation And External Side Effects - -Meldwork embeds local Agent automation, optional main-process Cloud/Channel Connector runtimes, and an Agent installer. It has no required server, email automation, cron schedule, or unattended recurring Task trigger. No concrete Cloud or Channel Connector is enabled by default. - -## Automation Inventory - -| Automation | Trigger / owner | Automatic scope | External side effects | -| --- | --- | --- | --- | -| Manual Agent reply | Local user sends a message and selects targets | Invokes selected built-in or approved Connector Agents sequentially once | Agent process or Connector call, Provider/native network use, local message/session writes | -| Automatic discussion | Local user sends a group message in automatic mode | Runs the explicitly selected group Agents in complete rounds, 6 rounds by default, with either a finite 1-10 round limit or an explicitly confirmed no-round-limit mode; no-round-limit mode stops on consensus or manual stop, while every individual Agent invocation retains its own timeout | Same as manual replies, repeated within the selected round policy | -| Agent detection/readiness | App startup or explicit refresh | Scans fixed command names and credential evidence | Local process/file reads; Claude may run `auth status --json` | -| Knowledge-source readiness | Explicit Knowledge Base settings refresh or source validation | Probes code-defined Feishu/DingTalk CLI status and Obsidian installation/Vault access | Local process/file reads; document-list permission probes may call the configured knowledge service through its CLI | -| Agent installation | Local user confirms installation | One installer task at a time | Network download/npm access and global CLI installation | -| Managed OpenClaw setup | OpenClaw invocation with configured Provider | Writes isolated runtime configuration if changed | Local config directories/files; Provider call by OpenClaw | -| Harness trace checkpoint | A run starts, emits a meaningful sanitized event, changes context, stops, or finishes | Atomically updates one bounded local Run Ledger record; terminal messages retain streamed conclusions, and restart marks unfinished attempts interrupted, reconstructs missing terminal messages, or enriches an existing matching message with missing output | Private Run Ledger/workspace file writes only; no network request and no automatic writable resume | -| Cloud Agent observation | An explicitly configured Cloud Connector owns a submitted remote job | Polls/observes with a durable cursor, reattaches after restart, resumes waiting input/permission, fetches declared Artifacts, and delivers idempotent cancel | External Cloud Connector calls plus private job/cursor/operation records | -| Channel Inbox receiver | An explicitly configured Channel Connector starts with Electron main | Verifies signed events, rejects replay/expiry, queues durable deliveries while the UI is closed, upserts scoped Tasks exactly once, and records outbound replies | External receiver/reply calls plus private Inbox, cursor, Task mapping, and audit writes | -| Run completion notification | A manual or automatic run reaches a terminal state while the app window is unfocused | Main emits one sanitized lifecycle event and one local operating-system notification | Local notification only; no network request or conversation message | - -## Agent Invocation Contract - -**Inputs Agents may read:** - -- The current user message. -- One immutable Context Pack containing stable user constraints, bounded non-duplicated Task history, source hashes, compact evidence capsules, and target scope. A resumed native Session receives only the validated delta after that Agent's previous final reply. -- Group name/topic and selected working directory. -- Main-resolved paths for selected root images when the target Agent's declared capability accepts the complete set. Automatic discussion keeps offering the root images to each Agent until that Agent first receives them successfully. -- Up to four main-captured immutable Skill snapshots scoped to the selected target Agent. Hermes also receives the validated Skill slugs through its native `--skills` arguments. -- Up to four main-revalidated knowledge-source selections scoped to selected target Agents. Obsidian uses bounded Connector search/fetch/snapshot/citation; Feishu and DingTalk retain explicit live CLI-reference semantics. -- Only the selected Agent's native credentials and optional configured Provider values. - -**Executable/tool surface:** - -- Main may spawn only detected executables for Codex, Hermes, OpenClaw, WorkBuddy, Kimi Code, MiMo Code, Claude Code, Qwen Code, Gemini CLI, OpenCode, and OpenCodeReview. -- An approved external Agent Connector can join through its manifest, registry instance, recipe, CredentialRef, and versioned Run Event contract without editing core Agent allowlists. -- Command shapes are code-defined in `desktop/src/cli-adapters.cjs`; prompt text does not select an arbitrary executable or shell command. -- Kimi read-only conversations use Agent Client Protocol `plan` mode. Write-authorized conversations retain Kimi's native stream-JSON prompt mode. -- OpenClaw receives an explicit tool allow/deny configuration. Execution, process, browser, gateway, cron, messaging, session spawning, and subagent tools are denied; write/edit/apply-patch are added only when the conversation permits writes. -- Other CLIs receive their supported plan/read-only or edit permission flags. These flags are hard guardrails outside the prompt, but enforcement ultimately depends on the upstream CLI. - -**Steering:** - -- `LocalWorkspace.promptFor` identifies the Agent, repeats bounded stable user constraints, adds only the delivery delta required by that Task-scoped group Session or conversation-scoped direct Session, and asks it not to impersonate other Agents. -- Selected knowledge sources add an explicit read-only instruction plus immutable snapshot/citation records or an explicit live-reference limitation. -- Automatic discussion preflights root-image limits for every explicitly targeted Agent, so each selected participant can receive the same root image set or the run does not start. Agents still run sequentially, so later participants can see earlier conclusions; native Sessions remain Agent-specific while the approved Task context is shared. - -**Output contract:** - -- CLI-specific parsers reduce output to final text, a main-only native session reference, bounded execution metadata, and completion state where the protocol exposes it. -- Output size and runtime are bounded in the adapter; secrets found in child errors are redacted before persistence. -- The Harness exposes only allowlisted status, conclusion deltas, reasoning summaries, plans, tool lifecycle summaries, warnings, bounded result metadata, and source message IDs. It never exposes raw chain-of-thought, commands, unrestricted stdout/stderr, credentials, executable paths, native session references, or arbitrary tool payloads. -- Versioned Connector events preserve Permission, SourceUsed, Artifact, Evidence, Usage, WaitingInput, Completed, Failed, and Cancelled fields through main, persistence, preload sanitization, replay, and restart. -- Before launching Hermes, main makes a best-effort read of the message-ID watermark through Electron's read-only SQLite API. After exit, a non-empty post-watermark `assistant` row with `finish_reason` equal to `stop` or `length` is authoritative. If the database is absent, locked, incompatible, or has no current-turn final row, Meldwork falls back to the ANSI-stripped official `--quiet` stdout instead of blocking the Agent. Any newly reported native session reference is persisted before this lookup. Final text becomes `message.content`; up to eight sanitized process steps and elapsed time remain separate metadata and are not included in later Agent prompts. -- Successful final text becomes a local Agent message. User-visible failure diagnostics remain local system messages; an all-failed manual run resolves after recording each failure because the user message has already been accepted and persisted. -- Live progress events are transient renderer updates. Main also stores bounded sanitized checkpoints in the private Run Ledger and persists compact evidence capsules with terminal conversation messages, including partial, failure, stop, timeout, and interruption outcomes. Native session references are never exposed to the renderer, listener failures cannot change a completed run result, and shutdown suppresses terminal desktop notifications. -- Artifacts, Evidence, Findings, Adoption, exact delivery fingerprints, and Human Gate decisions are durable records separate from reasoning and tool summaries. -- Automatic replies carry an internal final-line consensus marker. Meldwork removes the marker before persistence and stops only when every Agent completes and agrees in the same round. - -## Workspace Side Effects - -- `allowWrite` defaults to false. Adapters with enforceable permission modes receive read-only/plan arguments until the user explicitly opts into writes. -- Knowledge-source selections are Task-scoped and do not change `allowWrite`. Main-owned filesystem Connectors enforce read-only retrieval; CLI-mediated sources still depend on upstream permissions and receive explicit live-reference limitations. -- Hermes and OpenClaw do not expose an equivalent Meldwork-enforced read-only switch, so their capability label remains Agent-managed permissions regardless of `allowWrite`. -- Main passes write permission per invocation; it does not grant a renderer filesystem API. -- Agents run with the local OS user's process identity. Meldwork is not an OS-level sandbox. - -## Installer Contract - -**Approval:** The renderer requires confirmation before calling `agentInstaller.start`. - -**Hard guardrails:** - -- Fixed Agent catalog and OS-specific recipes. -- Fixed npm package names or HTTPS hosts. -- Validated npm executable/shim handling, especially on Windows. -- Sensitive ambient variables removed from the installer environment. -- One concurrent task, bounded download size, version verification after installation, and temporary-file cleanup. - -**Known limitation:** Recipes currently use mutable upstream packages/scripts without digest or signature verification. Host/package allowlisting reduces arbitrary input risk but does not make upstream content immutable. - -## Controls And Operations - -| Control | Implementation | -| --- | --- | -| User approval | Send/install actions originate from explicit UI commands; install uses confirmation; permission, budget, and review decisions use durable Human Gates | -| Rate/bounds | Manual targets run sequentially; auto discussion defaults to 6 complete rounds, finite mode is capped at 10 rounds, no-round-limit mode has no total runtime cap, every Agent invocation retains its watchdog timeout, budgets cover tokens/cost/tools/outbound bytes/elapsed time, and Task/workspace/global scheduler limits are enforced | -| Cancellation | Stop is bound to the current `(groupId, runId)`; queued or active Agents can be cancelled/retried/replaced independently; Cloud cancel is idempotent; installer cancel aborts download/process; quit uses bounded runtime shutdown | -| Failure handling | Failures are classified before retry. Network/rate-limit failures use bounded backoff. Authentication and compatibility failures fail once without an automatic retry, recovery handoff, or group-membership mutation; the user can explicitly retry or replace the affected Agent after correcting configuration | -| Audit trail | Context Packs, delivery records, Run Ledger state, Connector provenance/events, Artifacts, Evidence, Findings, Adoption, Human Gates, Cloud operations, and Channel delivery/outbound records remain main-owned and bounded; raw execution data is excluded | -| Kill switch | Stop the active Task or Agent, cancel the installer/Cloud job, disable a Connector, or quit the application | - -## App-Owned Versus Agent-Owned Actions - -- The app owns Meldwork conversation persistence, Context Packs, permission/budget/Gate decisions, process and Connector launch, bounded Run Ledger checkpoints, typed outcomes, run lifecycle events, Cloud observation, Channel Inbox mapping, operating-system notifications, installer selection, Provider encryption, and cancellation. -- Agents own generated text, their CLI-native session/history stores, and any work they perform through their CLI under the granted mode. Removing an app-owned session reference does not delete the Agent-owned native session. -- Agent suggestions do not directly mutate Meldwork configuration; configuration changes require renderer IPC handled by main. diff --git a/docs/brand-strategy.md b/docs/brand-strategy.md deleted file mode 100644 index bf38f1d..0000000 --- a/docs/brand-strategy.md +++ /dev/null @@ -1,250 +0,0 @@ -# Meldwork 品牌策略 - -> 日期：2026-07-31 -> -> 状态：工作名称与候选视觉，待商标、域名和用户理解测试后确认 - -## 1. 品牌核心 - -### 品牌角色 - -Meldwork 不是制造 Agent 的公司，也不是把十个 Agent 头像放进一个群聊的工具。 - -它的角色是： - -> **让不同 Agent 基于用户明确授权的知识上下文接续同一份真实工作，并让用户始终看得见任务、边界、证据和结果。** - -### 品牌关键词 - -- Open：开放连接，不绑定单一模型或厂商。 -- Local-first：控制面和工作记录默认在本机。 -- Accountable：工作可追溯、可比较、可验收。 -- Cross-vendor：全球与中国 Agent 平等接入。 -- Context-aware：连接用户已有知识来源，但不取代其内容平台。 -- Quiet confidence：专业、克制、不用“AI 魔法”语言。 - -### 品牌应避免 - -- 网络节点、蜂巢、中心控制器等工业化多 Agent 图形。 -- 对称的三路汇聚、机器人和拟人团队隐喻。 -- 蓝紫渐变、发光 Orb 和通用 AI Spark。 -- “无限自治”“AI 团队自动完成一切”的夸张承诺。 -- 把 local-first 暗示为完全离线。 - -## 2. 命名判断 - -### 推荐继续使用 Meldwork - -下表是基于当前定位的启发式评估，不是用户研究结果。各维度尚未加权，也没有经过目标市场样本测试。 - -| 维度 | Meldwork | MAC-Work | Open-MACWork | RoundRelay | -| --- | ---: | ---: | ---: | ---: | -| 全球可读可念 | 4/5 | 3/5 | 2/5 | 4/5 | -| 与产品价值关联 | 4/5 | 3/5 | 3/5 | 3/5 | -| 可扩展到 Cloud/Channel | 5/5 | 3/5 | 3/5 | 3/5 | -| 品牌辨识度 | 4/5 | 2/5 | 2/5 | 3/5 | -| 歧义风险 | 4/5 | 1/5 | 1/5 | 3/5 | -| 总体建议 | 推荐 | 不推荐 | 不推荐 | 不回退 | - -### 为什么不推荐 MAC-Work / Open-MACWork - -- `MAC` 容易被理解为 Apple Mac、MAC address 或 Mandatory Access Control。 -- 用户给出的英文展开中 `Muti-Agent` 应为 `Multi-Agent`。 -- `Open Resource Multi-Agent Collaborative Work` 像为缩写反向拼接的句子，不自然，也很难成为国际品牌叙事。 -- 名称把产品锁定在“multi-agent collaboration”功能，而 Meldwork 可以扩展到 Cloud Agent、Channel、Workflow 和治理。 - -### 为什么 Meldwork 更合适 - -- `Meld` 表示接续并把分散工作状态带入同一可审查记录，不意味着答案必须融合或一致。 -- `work` 明确产品服务真实工作，而非泛聊天。 -- 名称不强制解释 Agent 数量，能覆盖未来的 Task、Artifact、Evidence 和 Channel。 -- 读音简单，视觉上适合形成 `m` 的独立标志。 - -### 五个备选名 - -| 名称 | 逻辑 | 优点 | 主要风险 | -| --- | --- | --- | --- | -| Meldwork | 接续不同 Agent 的工作 | 最符合当前品牌资产与长期扩展 | 需要品类描述帮助首次理解，并防止被误解为强制融合 | -| Commonline | 多 Agent 进入共同工作线 | 与连续线 Logo 关联强 | 通用词较多，商标/域名风险需查 | -| Relaycraft | 接力 + 专业工作 | 有动作感，延续 RoundRelay 部分资产 | 偏“接力”，弱化治理与证据 | -| Workloom | 不同线索织成工作成果 | 视觉隐喻丰富、非工业化 | `loom` 在 AI 产品中使用较多 | -| Threadbase | 持续工作线与上下文基础 | 产品化、适合 Channel | 容易被理解为消息 Thread 数据库 | - -**当前建议：把 Meldwork 作为工作名称继续推进，不再在开发阶段频繁切换主品牌。** 只有在目标市场商标、核心域名或英语/中文理解测试出现实质障碍时再改名。 - -国内首次传播不强造音译品牌名，使用 `Meldwork（跨厂商 Agent 工作系统）`；读音统一为 `meld-work`。是否采用“联作”等中文副品牌，必须经过中国目标用户的记忆与复述测试后再决定。 - -### 名称风险说明 - -截至 2026-07-30 的当次实抓检查：npm 没有完全同名 package；GitHub 仓库名搜索只有 `meldworks` 等近似结果；[`meldwork.com` 的 Verisign RDAP](https://rdap.verisign.com/com/v1/domain/meldwork.com) 显示其已于 2024-12-20 注册，当前注册期到 2026-12-20，并非可直接使用的主域名；[`meldwork.ai`](https://rdap.org/domain/meldwork.ai) 与 [`meldwork.dev`](https://rdap.org/domain/meldwork.dev) 的 RDAP 查询当前无注册记录，但这不等于注册一定可用。开发者也可能把 `meld` 联想到既有的 Meld diff/merge 工具，因此需要在 5 秒理解测试中记录这种联想。公开发布前仍需完成美国、中国、欧盟目标市场第 9/42 类及近似图形的正式商标检索、域名下单核验和社交账号占用检查。 - -## 3. 信息架构 - -品牌传播使用三层，不让一个 Slogan 承担全部解释责任。当前 MVP 与目标 Harness 使用阶段化文案，避免把 Evidence/Acceptance 路线图写成已实现能力。 - -### 第一层 A：当前 MVP Slogan - -> **Agents change. Work continues.** -> -> **Agent 可切换，工作不断线。** - -当前 README 和 MVP 演示优先使用这条文案，因为它与持久会话、兼容 Session 延续和跨 Agent 工作空间的已实现价值一致。 - -### 第一层 B：目标产品 Slogan - -> **Different agents. Work you can verify.** -> -> **不同 Agent，工作有据可验。** - -作用：在 Task、Artifact、Evidence 和 Acceptance 形成真实产品闭环后，把品牌记忆落在跨厂商差异、独立观点和可验证工作，而不是 Agent 数量、角色扮演或强制共识。 - -不再把 `Many agents. One shared outcome.` 作为首选：名称 `Meldwork`、单条连续线和 `shared outcome` 同时出现时，容易让人误解为顺序群聊、答案融合或强制共识。`Different agents. Work you can verify.` 更直接表达异构 Agent、独立观点与可验证工作，也不会诱导用户认为 Agent 越多越好。 - -升级目标 Slogan 前仍应对至少 10 名英语母语目标用户和至少 10 名中国目标用户做 5 秒理解与复述测试，确认 `verify` 能被理解为 Evidence 与人类验收，而不是 Meldwork 自动保证正确。同一发布页面只使用一套主 Slogan。 - -### 第二层：品类描述 - -> **An open, local-first work system for agents across vendors.** -> -> **面向跨厂商 Agent 的开放、本地优先工作系统。** - -对需要解释知识来源的页面，可使用扩展品类描述： - -> **An open, local-first work system for agents and knowledge across vendors.** -> -> **面向跨厂商 Agent 与知识来源的开放、本地优先工作系统。** - -作用：第一次看见产品的人能够立即理解是什么。短版用于 Logo 邻近位置，扩展版用于 README、BP 和产品介绍。 - -### 第三层：价值主张 - -> **Bring agents and trusted knowledge into one accountable workspace.** -> -> **让 Agent 与可信知识上下文在一个可追溯、可验收的工作空间内协作。** - -作用：解释为什么值得使用。 - -### MVP 阶段的事实版文案 - -当前还没有 Cloud Agent、Task、Artifact、Evidence 和团队治理；知识来源也只是显式访问提示，不是统一检索引擎。因此 README 应使用： - -> Bring the local Agent CLIs and explicitly selected knowledge sources already available on your machine into one persistent workspace. - -愿景文案与当前能力文案必须分开。 - -## 4. Logo V2：Open Stitch - -### 核心概念 - -Open Stitch 的主线由一条连续 SVG 路径构成，另以独立端点圆形标记验证状态；整体非对称、连续、开放，并隐约形成小写 `m`。 - -- 左侧较高：工作从一个明确输入开始。 -- 中间回落与再次上升：不同 Agent 接手、修订、挑战。 -- 右侧不闭合：系统保持开放，可继续连接新的 Agent 与 Channel。 -- 珊瑚色端点：Evidence 被检查、结果被人类验收，或工作进入下一次明确交接的验证点。 - -它不画“多个 Agent 本体”，而画它们共同作用后的工作连续性。 - -### 与 Slogan 的关系 - -> Different agents = 工作线中发生的独立尝试、接手、挑战与修订。 -> -> Work you can verify = 产品保留 Artifact、Evidence、测试和人类验收，而不是要求答案一致。 -> -> Coral endpoint = 当前结果的验证或明确交接点，不代表所有 Agent 达成共识。 - -Open Stitch 只负责表达工作连续性、开放接续和结果端点；Evidence、并排比较和审查循环由产品界面与传播演示承担，不向一个简单标志塞入全部功能含义。 - -### 颜色系统 - -| Token | 色值 | 用途 | -| --- | --- | --- | -| Ink | `#15171A` | 浅色背景主标志与正文 | -| Paper | `#FFFFFF` | 深色背景主标志 | -| Coral | `#EF5A45` | 端点、验收和少量关键状态 | -| Carbon | `#0E0F11` | App Icon 背景 | -| Mist | `#F4F5F7` | 中性界面背景，不属于标志本体 | - -不再使用高饱和品牌蓝作为主标志颜色。黑/白标志能够更自然地适配明暗主题，珊瑚端点提供识别度，但不主导整个 UI。调整后的 Coral 对白色和 Mist 均达到约 3:1 的非文本图形对比度目标。 - -### 使用规则 - -- 左侧导航：透明背景，浅色主题用 Ink，深色主题用 Paper。 -- App Icon：Carbon 实底、Paper 线条、Coral 端点。 -- README / 文档：使用 `` 或等价主题切换，浅色背景用透明 Ink，深色背景用透明 Paper；不要在 GitHub 深色主题中固定使用 Ink。 -- 最小尺寸：标准标志盒高不低于 24px；20px 只用于经过真实像素检查的紧凑导航场景，不再宣称非对称细节在更小尺寸仍完整可读。 -- 安全空间：至少为线宽的 1.5 倍。 -- 只在中性浅色或深色背景使用；珊瑚色背景会削弱端点识别。 -- 禁止拉伸、加阴影、加渐变、加外框或改成对称结构。 -- 珊瑚色只用于端点，不把整条线改成彩色。 - -## 5. 字标 - -- 字标使用中性、现代、非几何炫技的 Sans Serif。 -- 推荐系统栈：Inter / SF Pro / Arial / PingFang SC。 -- `Meldwork` 保持正常大小写，不使用全大写。 -- 字重建议 620-680；字距为 0，不使用负字距。 -- 标志与字标之间保留约一个主线宽度的 2.2-2.6 倍。 -- 对外 SVG 字标使用固定轮廓路径，不保留依赖系统字体的 ``，避免 macOS、Windows 和 GitHub 渲染时字宽与重量漂移。 -- 对外同时提供 Ink 与 Paper 两个固定轮廓字标；品牌概念板中的说明文字不是生产字标。 - -首次触达不能只放独立 `m` 标志。README、发布页和商店页面至少同时出现品牌名、Slogan 或品类描述中的两项，避免被理解为普通字母 Logo 或状态通知点。 - -## 6. 品牌语气 - -### 应该这样说 - -- Bring the agents you already use. -- Keep orchestration and work state local. -- Compare independent attempts. -- Review evidence before accepting a result. -- Local control. Explicit provider traffic. - -### 不应该这样说 - -- Build your unstoppable AI workforce. -- Fully private and offline by default. -- Ten agents are always better than one. -- Autonomous swarms that finish everything. -- Enterprise-grade security（在相应审计和能力完成前）。 - -## 7. PR 主叙事 - -### Headline - -> **Introducing Meldwork: one local workspace for the Agent CLIs you already use.** - -许可证提交后才可以使用： - -> **Introducing Meldwork: open-source, local-first work for agents across vendors.** - -目标产品首屏支持语（Task / Artifact / Evidence / Acceptance 闭环交付并通过理解测试后使用）： - -> **Different agents. Work you can verify.** - -### Story - -1. 开发者已经在多个 Agent 之间工作，但 Session、上下文和权限彼此割裂。 -2. Meldwork 让现有本地 CLI 进入一个持续工作空间。 -3. MVP 保留原生 Session，并在本机管理会话和编排。 -4. 下一阶段让结果从消息升级为 Task、Artifact、Evidence 和 Acceptance。 -5. 产品不声称 Provider 流量完全离线，也不强迫用户使用新的云账号。 - -### Demo 原则 - -当前 MVP 发布演示只展示真实已实现的本地 Agent 发现、持续会话、同一工作目录和有界讨论。下一阶段原型可以明确标注为： - -> 独立方案 → 交叉审查 → 修订 → Evidence → 人类接受 - -不要演示十个 Agent 头像按顺序发表相似意见。 - -## 8. V2 候选资产 - -- `frontend/public/logos/meldwork-mark-v2.svg`：浅色背景透明标志。 -- `frontend/public/logos/meldwork-mark-v2-dark.svg`：深色背景透明标志。 -- `frontend/public/logos/meldwork-wordmark-v2.svg`：标志 + 固定轮廓字标。 -- `frontend/public/logos/meldwork-wordmark-v2-dark.svg`：深色背景标志 + 固定轮廓字标。 -- `frontend/public/logos/meldwork-app-v2.svg`：App Icon。 -- `frontend/public/logos/meldwork-brand-board-v2.svg`：概念与应用预览板。 - -这些文件是旁路候选，不会在确认前替换当前客户端资产。 diff --git a/docs/demo-recording-scenarios.md b/docs/demo-recording-scenarios.md deleted file mode 100644 index b041af6..0000000 --- a/docs/demo-recording-scenarios.md +++ /dev/null @@ -1,316 +0,0 @@ -# Meldwork 核心能力录屏场景 - -本文用于录制 README GIF、产品演示片和后续社媒视频素材。所有场景都以当前客户端已经具备的能力为基础，不把 Cloud Agent、Channel、自动选人或无条件断点续跑拍成现有功能。 - -核心叙事只有一条： - -> **一项任务先由一个 Agent 开始；需要时加入第二种视角；讨论被限制在明确边界内；用户检查证据后做最终决定。** - -## 一、录制基线 - -### 环境 - -- 使用当前仓库源码启动的 Electron 客户端，不使用旧安装包。 -- 建议使用 Apple 芯片 Mac、英文界面和一个单独的演示用户数据目录。 -- 准备两个已经通过就绪检测的通用 Agent。优先使用 Codex 与 Hermes；若其中一个不稳定，可以替换，但需要同步修改场景 4 的角色名。 -- 不使用 OpenCodeReview 承担通用对话任务，它只作为专项审查目标。 -- 使用一个复制出来的演示工作目录，不直接展示真实项目、个人目录或生产数据。 -- 演示目录至少包含 `docs/architecture.md` 与 `docs/tests.md`。 -- 默认关闭工作目录写入权限。需要展示写入时，单独创建可丢弃目录并明确开启。 - -### 录制规格 - -- 主素材：`2560 × 1440` 或 `1920 × 1080`，16:9，30 fps。 -- GIF：每段保留 8-12 秒，导出 12-15 fps，宽度 1280 px，单文件尽量低于 8 MB。 -- 鼠标移动保持缓慢，点击前停留约 0.5 秒，不使用快速甩动和连续缩放。 -- 只保留真实产品界面、少量字幕和必要的局部放大，不加入通用机器人、粒子或网络节点素材。 -- 系统时间、通知、用户名和完整本地路径应在录制前隐藏。 - -### 推荐演示数据 - -| 项目 | 建议内容 | -| --- | --- | -| 单聊名称 | `Positioning Review` | -| 群组名称 | `README Decision Room` | -| 工作目录 | 一个只包含演示仓库副本的目录 | -| Agent 数量 | 单聊 1 个，群组 2 个 | -| 自动讨论最大轮数 | 2 轮 | -| 写入权限 | 默认关闭 | -| 附件 | `docs/architecture.md`、`docs/tests.md` | - -## 二、场景总览 - -| 场景 | 核心能力 | 建议成片时长 | README GIF | -| --- | --- | ---: | --- | -| 1. 回到一项真实任务 | 持续单聊、兼容 Session、行内运行状态 | 10-15 秒 | 是 | -| 2. 先确定工作边界 | 工作目录、只读模式、显式权限 | 8-12 秒 | 是 | -| 3. 只加入必要上下文 | 文件附件、单 Agent 点名、来源约束 | 12-18 秒 | 是 | -| 4. 两个 Agent 设置两轮上限 | 群组、自动讨论、最大轮数 | 18-25 秒 | 是 | -| 5. 检查后再接受 | Agent/轮次切换、上下文、脱敏事件、单 Agent 修订 | 18-25 秒 | 是 | - -## 三、场景 1：回到一项真实任务 - -### 目的 - -展示 Meldwork 不是一次性问答窗口。用户可以回到同一个 Agent 单聊，看到此前结论，并继续下一步。 - -### 前置准备 - -1. 提前创建一个名为 `Positioning Review` 的单聊。 -2. 在会话中保留一条已经完成的定位讨论，最后一条结论应清晰、简短。 -3. 确认该 Agent 当前就绪，且会话没有运行中的任务。 - -### 操作步骤 - -1. 从工作台或左侧栏打开 `Positioning Review`。 -2. 停留 1 秒，让历史对话完整出现。 -3. 输入并发送以下英文指令。 -4. 保留 Agent 行内运行状态和回答开始出现的过程。 - -### 英文测试指令 - -```text -Resume this task from the existing conversation. State the last confirmed decision in one sentence, identify the next smallest deliverable, and continue without modifying files. -``` - -### 预期可见状态 - -- 同一个单聊标题与历史消息保持不变。 -- 运行状态直接显示在对话时间线中，不需要打开群组 Run 详情。 -- Agent 能引用上一轮已经确认的决定，并给出下一步。 -- 本轮不产生文件修改。 - -### 验收检查 - -- 回答没有把任务当作全新会话重新介绍。 -- 没有重复创建第二个单聊。 -- 回答完成后刷新或重新打开会话，消息仍然存在。 -- 若 Agent 不支持稳定 Session，也必须能够基于 Meldwork 保存的明确会话上下文继续，而不是声称拥有不存在的原生历史。 - -### GIF 剪辑点 - -从点击历史会话开始，到第一句引用既有决定的回答出现为止。建议 10 秒，结尾停留 1 秒。 - -## 四、场景 2：先确定工作边界 - -### 目的 - -展示工作目录和写入权限在任务开始前就可见，而不是在 Agent 已经执行之后才补充说明。 - -### 前置准备 - -- 使用一个由适配器明确支持只读模式的 Agent，优先 Codex 或 Kimi Code。 -- 演示工作目录中不放任何未提交改动或个人文件。 -- 录制前保存一次目录状态，便于录制后核对没有文件变化。 - -### 操作步骤 - -1. 新建单聊或群组。 -2. 通过系统目录选择器选择演示工作目录。 -3. 明确展示写入开关处于关闭状态。 -4. 发送以下英文指令。 -5. 回答完成后，短暂展示只读标识与引用的文件名。 - -### 英文测试指令 - -```text -Inspect this workspace in read-only mode. Identify three documentation risks that could confuse a first-time user. Do not modify any files. Cite the file names you used. -``` - -### 预期可见状态 - -- 工作目录在会话顶部或设置区域可见，但录屏中只保留缩略路径。 -- 写入权限保持关闭。 -- Agent 输出三条风险，并引用读取过的文件名。 -- 不出现文件创建、修改或删除结果。 - -### 验收检查 - -- 录制前后的工作目录差异为零。 -- 界面没有把“只读”描述成操作系统沙箱。 -- 如果选择的 Agent 无法可靠执行只读约束，立即更换 Agent，不使用该段素材。 - -### GIF 剪辑点 - -从选择目录开始，经过关闭的写入开关，到发送英文指令为止。分析结果可另剪一段，避免一个 GIF 同时承载太多信息。 - -## 五、场景 3：只加入必要上下文 - -### 目的 - -展示文件不会自动倾倒给所有 Agent。用户明确选择文件、目标 Agent 和本轮任务范围。 - -### 前置准备 - -- 打开 `README Decision Room` 群组，但本轮只点名一个通用 Agent。 -- 准备 `docs/architecture.md` 与 `docs/tests.md`。 -- 确保两个文件不包含密钥、真实用户名或需要隐藏的本地路径。 - -### 操作步骤 - -1. 在输入区切换到“单轮回答”模式。 -2. 只选择一个目标 Agent。 -3. 点击附件按钮，依次选择两个文档。 -4. 确认输入框中出现两个附件项。 -5. 发送以下英文指令。 -6. 回答完成后打开对应运行详情，展示该用户消息是本次注入来源；点击来源回到消息，再展示两个附件名。 - -### 英文测试指令 - -```text -Review only the two attached documents. Produce a concise readiness assessment with three sections: confirmed capabilities, unresolved risks, and the next best validation step. Support every claim with an attached file name. -``` - -### 预期可见状态 - -- 两个附件在发送前均可见。 -- 只有被点名的 Agent 运行。 -- 回答包含三个指定部分，并以文件名支撑关键判断。 -- 运行详情展示经过允许的注入消息与上下文摘要；附件名可从对应的原始消息查看，但不暴露真实存储路径。 - -### 验收检查 - -- 两个文件均成功导入且没有签名、类型或大小错误。 -- 未选择的 Agent 没有产生回答。 -- 回答没有引用未附加且未授权的文件。 -- 上下文来源能回到包含这两个附件的用户消息。 - -### GIF 剪辑点 - -从两个附件项出现开始，到单 Agent 回答的三个小标题出现为止。建议 10-12 秒，使用 1.5-2 倍速但保留关键停顿。 - -## 六、场景 4：两个 Agent 设置两轮上限 - -### 目的 - -展示多 Agent 协作不是无限聊天。用户确认参与者、讨论模式和最大轮数，两个 Agent 在同一任务范围内形成不同视角。 - -### 前置准备 - -- 群组中只保留 Codex 与 Hermes 两个已就绪通用 Agent；若使用其他 Agent，需要同步修改测试指令中的角色名。 -- 工作目录和写入权限已经设置完成。 -- 关闭其他运行中的会话，避免系统资源和通知干扰。 - -### 操作步骤 - -1. 打开 `README Decision Room`。 -2. 在输入区切换到自动讨论模式。 -3. 确认群组仅包含两个 Agent，并把“最大轮数”设为 2。 -4. 发送以下英文指令。 -5. 录制两个 Agent 依次回答、轮次切换以及第 2 轮结束状态。 - -### 英文测试指令 - -```text -Run a two-round review of Meldwork's current README. Codex should argue from first-time user value; Hermes should challenge every claim against the available product evidence. Round 1 must surface disagreements and must not converge. In round 2, each Agent should answer the strongest opposing point, then converge on exactly three message changes and one claim to remove. -``` - -### 预期可见状态 - -- 自动讨论模式、两个群组成员和“最大轮数 2”在发送前可见。 -- 每个完整轮次中两个 Agent 各运行一次。 -- 后执行的 Agent 能看到前序结论的精简上下文，而不是完整工具日志。 -- 第 2 轮结束后 Run 进入明确终态，不继续第 3 轮。 - -### 验收检查 - -- 两个 Agent 都完成两轮；若第 1 轮提前收敛，或某个 Agent 失败、认证中断，不使用该次录制。 -- 界面不显示内部共识标记、原始思维链、凭据或完整命令输出。 -- 最终内容确实包含三条文案修改和一条应删除声明。 -- 自动讨论停止后仍可打开历史消息和运行详情。 - -### GIF 剪辑点 - -不要把两轮完整等待过程全部放进 GIF。建议剪成三个连续动作：启动自动讨论、Agent/轮次状态变化、第二轮完成。总时长控制在 10-12 秒。 - -## 七、场景 5：检查后再接受 - -### 目的 - -展示 Meldwork 的核心不是“让两个 Agent 都说完”，而是让用户能够检查每个 Agent、每一轮、上下文与脱敏事件，再指定一个 Agent 完成最终修订。 - -### 操作步骤 - -1. 在场景 4 的群组中打开 Run 详情。 -2. 依次切换两个 Agent。 -3. 切换第 1 轮与第 2 轮。 -4. 展开结论、事件和上下文来源，停留在每个区域约 1 秒。 -5. 关闭 Run 详情，将输入区切换到“单轮回答”模式，只选择一个目标 Agent。 -6. 发送以下英文指令，生成最终定位段落。 - -### 英文测试指令 - -```text -Using the review above, rewrite only the product positioning paragraph in no more than 80 words. Keep claims supported by the evidence and remove anything the review could not verify. -``` - -### 预期可见状态 - -- Run 详情可以按 Agent 和轮次切换。 -- 结论、上下文来源和终态彼此分离；若所选 Agent 或传输能够提供，还会显示计划或工具生命周期摘要。 -- 详情中没有原始思维链、凭据、原生 Session 标识或可执行路径。 -- 最终修订只由用户点名的一个 Agent 完成。 - -### 验收检查 - -- 第 1 轮与第 2 轮内容可以明确区分。 -- 上下文来源能对应之前的用户消息、Agent 结论，或包含附件的原始消息。 -- 最终段落不超过 80 个英文单词。 -- 用户可以选择复制、继续修改或放弃结果；视频不暗示 Meldwork 自动替用户做最终决策。 - -### GIF 剪辑点 - -优先展示 Run 详情中的 Agent 切换、轮次切换和上下文展开。最终修订可作为第二个 GIF，避免文字太小。 - -## 八、可选素材 - -以下内容只有在录制机器上能够稳定复现时才使用： - -- 已配置的飞书、钉钉或 Obsidian 知识来源选择。 -- 已安装 Agent 的兼容 Skill 选择与目标分配。 -- 一个不会产生真实外部副作用的 Human Gate。 -- 单 Agent 停止、重试或替换后的状态变化。 - -以下内容不进入当前产品演示： - -- 没有真实 Connector 的 Cloud Agent 或 Channel 页面。 -- 已在界面隐藏的自定义 Agent 配置。 -- 自动选择“最佳 Agent”或自动组队。 -- 中断后从任意多 Agent 节点无条件精确续跑。 -- 安装 Agent、修改系统环境或写入真实项目的过程。 - -## 九、README GIF 组合建议 - -| 文件名建议 | 内容 | 时长 | -| --- | --- | ---: | -| `meldwork-resume-task.gif` | 打开历史单聊并继续任务 | 8-10 秒 | -| `meldwork-add-context.gif` | 选择目录、保持只读、附加两个文件 | 10-12 秒 | -| `meldwork-two-agent-review.gif` | 设置两轮上限并显示轮次变化 | 10-12 秒 | -| `meldwork-inspect-run.gif` | 切换 Agent、轮次、事件与上下文 | 10-12 秒 | - -示例导出命令： - -```bash -ffmpeg -i source.mov -vf "fps=12,scale=1280:-2:flags=lanczos" -loop 0 output.gif -``` - -导出后逐帧检查：文字是否可读、是否出现鼠标残影、是否包含真实路径或通知、循环点是否自然。 - -## 十、录制隐私检查 - -- [ ] 使用演示目录，不包含真实业务数据。 -- [ ] 隐藏完整用户名、用户目录和外接磁盘名称。 -- [ ] 关闭系统通知、聊天软件、邮箱和日历提醒。 -- [ ] Provider 表单、API Key、环境变量和认证终端不入镜。 -- [ ] 不展开原生 Agent 的隐私数据、完整日志或 Session 文件。 -- [ ] 附件内容已人工检查，可公开展示。 -- [ ] 工作目录写入默认关闭；需要写入时只使用可丢弃目录。 -- [ ] 录制结束后检查每一帧，不只检查视频开头和结尾。 - -## 十一、最终验收 - -一组可用素材应让第一次看到 Meldwork 的人，在 30 秒内回答三个问题： - -1. 它解决什么问题：不同 Agent 之间的工作容易被切碎。 -2. 它如何工作：从一个 Agent 开始，按需加入另一个，并限制协作范围。 -3. 为什么值得信任：用户能看到权限、上下文、每轮结果和脱敏运行证据，并保留最终决定。 diff --git a/docs/flows.md b/docs/flows.md deleted file mode 100644 index 84a4616..0000000 --- a/docs/flows.md +++ /dev/null @@ -1,169 +0,0 @@ -# Security And Side-Effect Flows - -Meldwork has one human actor: the local desktop user. There are no accounts, roles, claims, tenants, or server-side authorization checks. Protected operations are authorized by the Electron main process accepting IPC only from the exact bundled renderer main frame. - -## 1. Application Startup - -**Precondition:** The local user launches Meldwork. - -1. Electron main creates Provider, knowledge, attachment, Context Pack, Outcome, Human Gate, Cloud operation, Channel Inbox, and bounded Run Ledger stores under `app.getPath('userData')`, plus `LocalWorkspace`, Connector registries/runtimes, and a `LocalSkillCatalog` rooted at `app.getPath('home')`. -2. Main registers IPC handlers, creates a sandboxed `BrowserWindow`, and loads the bundled frontend with `loadFile`. -3. Before accepting attachment work, main reconciles the private attachment directory against persisted message references. Malformed workspace state disables destructive cleanup. -4. Preload exposes workspace, installer, Skill, attachment, and Provider methods only when `location.protocol === 'file:'`. -5. The renderer requests a sanitized workspace snapshot and a non-probing Provider status. -6. The renderer performs the single startup Agent refresh, which detects installed CLIs and evaluates credential readiness. Main does not launch a duplicate eager scan. -7. `LocalWorkspace` restores durable Human Gate decisions and recoverable continuations before marking unrelated nonterminal local runs `interrupted`, then reconciles terminal Agent attempts into compact conversation messages. Writable local work is never auto-resumed without an accepted continuation. -8. Cloud runtime claims configured remote jobs by durable owner/cursor and replays idempotent pending operations; Channel runtime starts configured main-process receivers and drains its durable Inbox. Both runtimes default to zero Connectors. -9. On the first renderer launch, a three-slide onboarding carousel opens while that refresh runs. Its completion action remains disabled until detection actually settles; completion is stored only in renderer `localStorage`. - -**Deny case:** IPC from a different frame, web contents instance, protocol, or file path fails `requireDesktopRenderer`. - -**State/side effects:** Reads local Agent/Skill configuration and Meldwork data, removes only confirmed orphan attachment entries, and writes a non-secret onboarding preference after dismissal; it does not contact an application server. - -## 2. Save Or Remove A Provider - -**Precondition:** The user opens Provider settings in the local renderer. - -1. Renderer collects `provider`, `baseUrl`, `model`, and `apiKey` and calls the preload method. -2. Main validates the renderer origin and passes only the four expected fields to `ProviderStore`. -3. `ProviderStore` accepts HTTPS or loopback HTTP URLs without embedded credentials, query, or fragment. -4. `safeStorage` encrypts the API key. Main atomically writes metadata plus ciphertext to `roundrelay-provider.json`. -5. Status responses return metadata and configuration state, never the API key. -6. Removing the Provider deletes the local credential file and refreshes Agent availability. - -**Deny cases:** Missing recognized fields, invalid URL, unavailable OS encryption, encryption failure, or corrupt ciphertext fail closed. Main ignores unrecognized renderer properties instead of forwarding them to storage. - -**External side effect:** Later Agent invocations may send prompts to the configured Provider. Saving metadata alone does not test or call the Provider. - -## 3. Detect Or Install A Local Agent - -**Precondition:** The user opens the Agent manager. Installation requires a second confirmation click in the renderer. - -1. Main searches allowlisted command names in known user installation paths and verifies a non-empty version. -2. The renderer displays installed, ready, and installable states without executable paths. -3. On confirmed installation, main selects a code-defined recipe for the Agent and current OS. -4. npm recipes invoke a fixed package name. Hermes/Kimi recipes download from allowlisted HTTPS hosts into a temporary directory. -5. The installer runs one task at a time, filters sensitive environment variables, supports cancellation, and verifies the CLI version afterward. -6. Temporary installer files are removed and Agent detection is refreshed. - -**Deny cases:** Unknown Agent, unsupported OS, already installed Agent, missing npm, non-allowlisted command/URL, invalid Windows npm shim, failed download, or failed version verification. - -**External side effects:** Network download and global CLI installation. Current recipes are allowlisted but not cryptographically pinned. - -## 4. Manage Meldwork Conversations - -**Precondition:** At least one detected Agent is available. The user selects a working directory. - -1. The sidebar groups direct conversations under each available Agent and may create more than one Meldwork conversation for the same Agent. -2. Renderer sends the Meldwork conversation name/topic, Agent kinds, user-selected directory, and `allowWrite`. -3. Main validates the renderer and delegates create, select, rename, update, or delete operations to `LocalWorkspace` using a Meldwork-owned conversation ID. -4. `LocalWorkspace` keeps only available Agent kinds, resolves the directory, stores `allowWrite` as an explicit boolean, and isolates direct native Sessions by conversation and Agent and group native Sessions by Task and Agent. -5. Older topic/conversation-scoped group references are migrated once to Task scope. Changing the working directory clears that conversation's native Session mappings. -6. The workspace file is updated and a sanitized snapshot is emitted to the trusted renderer. - -**Deny cases:** No available Agent, invalid group ID, or attempts to enable an unavailable Agent. - -**State/side effects:** Writes local conversation configuration. Deleting a conversation is denied while it is running, first purges its Run Ledger records, then removes Meldwork messages and native session-reference mappings. A failed ledger purge leaves the conversation intact; a later workspace-write failure rolls back the in-memory conversation state, so deletion remains retryable without retaining app-owned trace checkpoints. It does not delete any CLI-native session or history from the CLI's own storage. - -## 5. Select Skills And Import Images - -**Precondition:** A conversation and at least one target Agent are selected. - -1. Typing `@` or pressing the Skill button asks `agentInstaller.skills(kind)` for each current target. The installed-Agent gate and `LocalSkillCatalog` return only sanitized `{targetKind, namespace, slug, name}` records. -2. The renderer keeps at most four selections and sends structured Skill coordinates, not filesystem paths or Skill contents. -3. The image button opens a main-owned PNG/JPEG picker. Clipboard images cross the bridge only as an exact `{name, mimeType, bytes}` payload. -4. `AttachmentStore` validates source-file safety, magic bytes, declared MIME/name agreement, the 8 MiB limit, private modes, checksum, and image dimensions before returning safe metadata plus a bounded preview. -5. Before persisting a message, `LocalWorkspace` resolves attachment IDs to main-only absolute paths, revalidates every Skill against the current target's catalog, and checks every selected Agent's image count/capability. -6. Persisted messages and renderer snapshots contain attachment metadata and target-scoped Skill hints only. Historical previews are loaded separately by ID through a bounded, visibility-driven renderer cache. -7. Removing an unsent image calls the discard IPC. Deleting a conversation removes only attachments no longer referenced by another message; startup cleanup removes confirmed orphans and interrupted-import residue. - -**Deny cases:** Unknown/stale/cross-Agent Skill, more than four Skills, malformed attachment input, unsupported type, MIME mismatch, more than 8 MiB per image, more than four images, unsafe/tampered storage, unsupported target Agent, or a target-specific image limit. Validation fails before a message or Agent run is recorded. - -**State/side effects:** Imports private local image copies and reads local Skill manifests. No Skill path, attachment path, preview payload, or raw bytes are persisted in the workspace snapshot. - -## 6. Connect And Select Knowledge Sources - -**Precondition:** The user opens Knowledge Base settings or opens the composer mention menu. - -1. Main resolves a code-defined source catalog. Feishu and DingTalk are probed through allowlisted local CLI commands; Obsidian is detected as an app or CLI and uses a user-selected Vault directory. -2. Main returns sanitized readiness, login, permission, read/write, command-name, and selected-Vault status. Notion, Confluence, Google Drive, and SharePoint remain planned reference entries rather than active Connectors. -3. Selecting an Obsidian Vault uses a main-owned directory dialog and persists only the normalized absolute path in `roundrelay-knowledge-base.json`. -4. The composer may select up to four ready knowledge sources and scopes each selection to explicit target Agents. -5. Before accepting the message, main re-probes missing cache entries and validates that the source is currently readable, its access mode is supported, and every target belongs to the current run. -6. Before invocation, the Knowledge Connector runtime turns explicit Obsidian selections into bounded search/fetch results and immutable snapshots with stable source IDs, content hashes, and reopenable citations. Feishu and DingTalk selections retain explicit live CLI-reference semantics. -7. Only the selected Agent receives its approved snapshot/citation records or validated live-reference hint. - -**Deny cases:** Unknown or planned source, missing login, missing permission, unreadable or invalid Vault, unsupported access mode, empty target set, target outside the run, or stale source state. - -**State/side effects:** Probes may invoke local Feishu/DingTalk commands and read local installation state. Obsidian Connector retrieval is bounded and read-only, and its snapshots/citations are stored privately. A later Agent run may send approved derived content to its configured Provider; live CLI references retain an explicit provenance limitation. - -## 7. Send A Message To Agents - -**Precondition:** The conversation is not already running and at least one selected target belongs to the group. - -1. `LocalWorkspace` reserves a unique `runId` and Task identity, captures an immutable Context Pack before the first durable execution checkpoint, validates the complete request, persists the user message, and begins a cancellable run for the explicit target Agents. -2. Each attempt receives an immutable delivery record containing its exact approved prompt fingerprint, source IDs/hashes, target scope, permission mode, Connector version, and native Session provenance. The first group turn sends the bootstrap instructions; after a native Session has completed once, later group turns send only a `ROUNDRELAY_HARNESS_CONTEXT_V1` continuation containing bounded stable constraints and recent conclusions. A resumed Session therefore receives only its validated, Harness-compressed delta; Session rotation or recovery returns to bootstrap. -3. Main resolves a built-in adapter or approved Agent Connector plus attachment paths, CredentialRefs, Provider/native environment, and selected Skill/knowledge snapshots. Prompt text cannot select an executable or unapproved Connector. -4. CLI adapters apply per-Agent read-only or write-enabled arguments. Child processes receive an allowlisted system environment plus only current-Agent credentials. -5. Main emits allowlisted status, conclusion deltas, reasoning summaries, plans, tool lifecycle summaries, warnings, and bounded result metadata. Direct conversations render these inline while running; group conversations stream conclusions in the shared conversation and keep detailed process events in the right-side panel. Raw chain-of-thought and unrestricted tool output are never emitted. -6. Meaningful Agent events and context statistics update the bounded Run Ledger checkpoint. Versioned Connector events are reduced idempotently, while normalized final text becomes message content and typed Artifacts/Evidence remain separate durable records. Native Session references remain main-only. For Hermes, a post-watermark non-empty `assistant` row with `finish_reason` `stop` or `length` overrides process output; validated `--quiet` stdout remains the fallback. -7. Failures are recorded as diagnostic system messages, with any conclusion already emitted through answer deltas retained below the status text. One failed Agent does not cancel successful Agents; when every Agent fails after the user message has been persisted, the send resolves as an accepted failed run so the renderer does not restore and duplicate the committed draft or attachments. -8. On terminal state, main finalizes the Ledger record and emits a best-effort sanitized run event. Live direct disclosures collapse; the active group process panel closes, while result messages retain a trace entry that can reopen durable compact evidence. A historical panel opened from a result remains open across unrelated run completion. When the window is unfocused main also creates a content-free operating-system notification whose click action focuses the app and opens the Meldwork conversation; shutdown suppresses these notifications. - -**Deny cases:** Empty text and no image, target outside the group, unavailable Agent, concurrent run, invalid Skill/attachment context, invalid sandbox, or authentication failure. - -**External side effects:** Agent/provider network calls and possible workspace reads. Workspace writes are intended only when `allowWrite` is true, subject to upstream CLI enforcement. - -## 8. Equal-Context Automatic Discussion And Stop - -**Precondition:** A group has at least two explicitly targeted Agents and a persisted user topic root. - -1. Before creating a run, `LocalWorkspace` checks the root message's entire image set against every explicitly targeted Agent. If any target cannot receive the same set, the discussion is rejected before any process starts. -2. The user chooses either a finite round count from one to ten, defaulting to six, or explicitly confirms no round limit. Unlimited mode has no total runtime cap; it stops on consensus, explicit user stop, application shutdown, or a terminal run failure. Every individual Agent attempt still has its own watchdog timeout. -3. `LocalWorkspace` invokes every explicitly targeted group Agent once per complete round. Each group Task and Agent has a main-only native Session reference, while all selected Agents receive the same bounded shared Task context and prior conclusions. Direct conversations retain conversation-and-Agent Session continuity. Root images are delivered once to each Agent; a failed delivery is retried on that Agent's next attempt instead of silently dropping context. Root Skill and knowledge-source selections are revalidated and remain scoped to their target Agent on every attempt. -4. Each Agent must end with one internal consensus marker. The marker is removed before persistence, and the run stops early only when every Agent completes and agrees in the same round. -5. A failed Agent is recorded once per stable failure, while later Agents and later bounded rounds continue. Retryable network and rate-limit failures use bounded backoff. HTTP 401/403 and compatibility failures end the affected Agent slot after one attempt, retain the configured group membership, and require an explicit user retry or replacement after configuration is corrected. Each later Agent receives prior conclusions plus compact, source-addressable evidence capsules instead of complete tool logs. -6. The user can stop only the currently displayed `(groupId, runId)` pair. A missing or stale `runId` is rejected, preventing an old UI request from cancelling a newer run. Per-Agent cancel, retry, and replace controls abort only the selected attempt; whole-run stop aborts the active process tree. Both paths retain the conversation run lock until child/output cleanup settles. - -**Deny cases:** Missing topic root, fewer than two selected target Agents, or another active run. - -**State/side effects:** Final messages, compact evidence capsules, bounded private Run Ledger checkpoints, and main-only session-reference mappings are updated. Live renderer events remain transient. A manual stop persists the last available Agent trace as `stopped`; shutdown-originated cancellation and crash recovery use `interrupted`, while an individual watchdog timeout remains `timeout`. There is no total Run timer, recurring schedule, unattended cron trigger, auto-resume worker, or retry daemon. - -“Equal context” here means every Agent can receive the same root image set before the run is allowed. Discussion remains sequential, so later Agents in a round can see earlier replies. Native Sessions are Task-and-Agent-specific for group work and conversation-and-Agent-specific for direct work; selected Skills remain Agent-specific. - -## 9. Cloud Agent Detach And Reattach - -**Precondition:** A main-owned approved Cloud Connector is configured; local-only deployments leave the Connector list empty. - -1. Main submits with a stable idempotency key and persists the remote job ID, cursor, Connector/upstream provenance, and recovery owner. -2. The UI may close while Electron main keeps observing. After restart, the runtime claims the remote job, reconciles its cursor, and reduces duplicate/out-of-order events without duplicating terminal transitions or Artifacts. -3. Waiting input/permission answers and cancel operations are persisted before delivery and replayed with the same idempotency key after a crash. -4. Preload exposes only sanitized status, waiting request, Artifact/Evidence IDs, and explicit input/permission/cancel commands; raw job IDs and cursors remain main-only. - -**External side effects:** Calls the configured Cloud Connector. Shutdown aborts observation and waits only for a bounded grace period even when a Connector ignores cancellation. - -## 10. Channel Ingress And Durable Inbox - -**Precondition:** A main-owned Channel Connector, Connection, ExternalActor, Subscription, and Workspace/Task mapping are configured. The production default has no Connector. - -1. The Connector verifies the signed envelope in main. Runtime rejects invalid, expired, replayed, cross-Workspace, disabled-subscription, or unknown-actor events. -2. A valid event creates one durable Delivery keyed by Connection and idempotency key. Only the bounded Task request is stored; raw headers/signatures and full IM history are discarded. -3. The Inbox upserts the mapped local Task exactly once across retries/restart and advances a durable cursor. -4. Outbound replies reference the originating Delivery and are stored as auditable idempotent records. -5. Closing the last window does not stop an active receiver; application shutdown stops it with a bounded grace period. - -**Renderer boundary:** There is no Channel IPC, preload method, Inbox browser, raw payload exposure, or renderer-visible CredentialRef. - -## 11. Shutdown IPC Gate - -**Precondition:** Electron receives `before-quit`. - -1. Main sets `shutdownStarted` before beginning asynchronous cleanup. -2. Every registered trusted IPC handler continues to verify the renderer and then rejects with `DESKTOP_CLIENT_SHUTTING_DOWN`; no new read, mutation, import, install, Provider, or Agent operation can enter during teardown. -3. Main cancels pending/active installation work, assigns `shutdown` only to run controllers without an existing stop reason, aborts local Agent processes, checkpoints/finalizes shutdown-originated attempts as `interrupted` while preserving prior stopped/timeout intent, and starts bounded Channel/Cloud runtime shutdown. -4. Main waits for workspace/installer settlement and the bounded Connector grace periods. A Connector that ignores `AbortSignal` cannot block application exit indefinitely. -5. Repeated quit requests reuse the same cleanup operation. After settlement, main marks cleanup complete and calls `app.quit()` once more to exit. - -**Deny case:** Any renderer IPC request after shutdown starts is rejected even when it comes from the otherwise trusted main frame. - -**State/side effects:** Active child processes are stopped before exit, the last bounded sanitized trace is retained, and no new IPC side effect can race with final persistence or attachment cleanup. An abrupt exit is reconciled from the last atomic Run Ledger checkpoint on the next launch. diff --git a/docs/harness-engine-strategy.md b/docs/harness-engine-strategy.md deleted file mode 100644 index 8931d12..0000000 --- a/docs/harness-engine-strategy.md +++ /dev/null @@ -1,811 +0,0 @@ -# Meldwork Harness Engine 与 Agent Team 商业化战略 - -> 日期：2026-08-02 -> -> 状态：产品与技术战略建议，不代表当前已交付能力 -> -> 关联文档：[产品迭代规划](product-iteration-plan.md)、[产品 BP](product-bp.md)、[架构](architecture.md)、[自动化](automation.md) - -## 0. 直接结论 - -**建议有条件推进。** 用户提出的方向成立，但需要把目标从“接入所有支持 CLI 的 Agent”升级为： - -> **把本地、自研和云端的异构 Agent 变成可发现、可调度、可约束、可恢复、可评估的工作单元，并让它们以最低必要协作成本交付可采用、可验证的结果。** - -推荐的产品主链路是： - -```text -Any Agent - -> Connector Contract - -> Harness Run - -> Task Graph / Blackboard - -> Artifact / Evidence - -> Decision / Adoption -``` - -这条路线有创业价值，但有三个前提： - -1. **“任意 CLI”是入口，不是壁垒。** 适配数量很容易被复制，也会被 ACP、A2A、MCP、AG-UI 等开放协议逐步商品化。 -2. **多 Agent 不是默认答案。** 默认先用一个最合适的 Agent；只有任务可拆分、能力互补、风险需要独立复核或证据存在冲突时，才增加 Agent。 -3. **商业化卖的是交付能力，不是 Agent Logo。** 客户为更低的协调成本、更高的成功率、可验证的结果、组织策略和私有部署付费，而不是为“一个窗口里有很多 Agent”付费。 - -因此，Meldwork 的核心创新不应是通用聊天聚合器，也不应直接与模型公司竞争“最强 General Agent”。更合理的定位是： - -> **跨厂商、Local-first 的 Agent Harness 与 Outcome Control Plane。** - -12 个月内只需要证明一件事：一个小团队能否依靠 Meldwork 的 Harness 和两个业务 Agent Pack，持续比手工切换 Agent 更快、更稳地交付经过验证的结果。如果不能证明，应收缩为“单 Agent + Knowledge + Outcome”的个人工具，而不是继续堆叠 Swarm。 - -## 1. Harness Engine 应该解决什么 - -### 1.1 定义 - -Harness Engine 是位于“用户任务意图”和“具体 Agent Runtime”之间的执行控制层。它不替代 Agent 的专业能力，而是决定： - -- 哪个 Agent 应该参与。 -- Agent 能看到什么上下文、使用什么 Provider、获得什么权限。 -- 工作如何拆解、并行、暂停、复核和恢复。 -- 哪些输出属于可继续使用的 Artifact。 -- 哪些证据足以支持结果和最终 Decision。 -- 这次协作是否比单 Agent 更好、更快或更便宜。 - -可以用一个简单公式理解其价值： - -```text -有效交付价值 -= Agent 专项能力 x 任务匹配度 x 上下文质量 x 可控性 x 可验证性 -- 协调成本 - Token/时间成本 - 失败与返工成本 -``` - -### 1.2 对用户四点理解的补全 - -用户提出的前三点是正确的，建议扩展为六点： - -1. **更低成本地交付更好结果**：路由到最合适的 Agent，只在可并行或高风险场景增加 Agent，压缩重复上下文和无效讨论。 -2. **更稳定、更可控**：权限、预算、超时、取消、Checkpoint、重试、降级和 Human Gate 都由 Harness 统一管理。 -3. **更易扩展**：Agent 通过 Connector Manifest 和协议能力加入，而不是不断在业务代码里增加 `if kind === ...`。 -4. **可观测、可评估**：每次 Run 都有统一事件、Artifact、Evidence、成本、耗时、失败原因和回归评测。 -5. **可组合、可复用**：被证明有效的任务拆解、Review Policy 和交付标准可以固化成有版本的 Workflow 或 Agent Pack。 -6. **可治理、可审计**：组织可以规定哪些数据能出站、哪些 Agent 能写入、什么任务必须复核、什么结果可以自动采用。 - -### 1.3 Harness 的五个平面 - -| 平面 | 责任 | 用户价值 | -| --- | --- | --- | -| Connector Plane | 发现、安装、调用本地 CLI、ACP Agent、A2A Agent 和云 API | Agent 可替换，避免被单一厂商锁定 | -| Control Plane | 权限、Provider、预算、取消、超时、Session、Checkpoint 和恢复 | 稳定、可控、可追责 | -| Coordination Plane | Task Graph、路由、调度、问题定向、Review 和裁决 | 减少无效全员讨论 | -| Outcome Plane | Artifact、Evidence、Decision、Adoption 和导出 | 从“说了什么”升级为“交付了什么” | -| Evaluation Plane | 场景评测、兼容测试、质量/成本回归和 Agent Fit Matrix | 能基于证据选择 Agent，而不是凭品牌选择 | - -## 2. 为什么方向成立，但不能只做连接层 - -### 2.1 外部证据给出的边界 - -Anthropic 在《Building effective agents》中建议从最简单的方案开始，再按任务采用 Routing、Parallelization、Orchestrator-workers 或 Evaluator-optimizer，而不是默认建立复杂自治系统。 - -Anthropic 公开的多 Agent Research 系统在其内部研究评测中相对单 Agent 提升 90.2%，但同时披露多 Agent 系统平均消耗约为普通聊天的 15 倍 Token；需要共享完整上下文、Agent 间依赖很强的任务，并不适合当前多 Agent 架构。这个结果说明，多 Agent 的价值来自**可并行的高价值任务**，不是 Agent 数量本身。 - -论文《Towards a Science of Scaling Agent Systems》在 260 种配置上的结果更直接：多 Agent 相对单 Agent 的变化范围从 `+80.8%` 到 `-70.0%`。工具密集任务存在明显协调开销，无中心验证的架构也更容易传播错误。结论不是“多 Agent 有效”或“无效”，而是**任务结构与协作架构是否匹配决定结果**。 - -Magentic-One 的启发同样不是“让所有 Agent 自由聊天”，而是让 Orchestrator 负责规划、跟踪、重规划和恢复，专业 Agent 按需参与。 - -### 2.2 连接层正在标准化 - -| 协议 | 主要解决的问题 | Meldwork 应如何使用 | -| --- | --- | --- | -| MCP | Agent 连接工具、数据和资源 | 作为 Tool/Knowledge 接口，不把 MCP Server 都称为 Agent | -| ACP | 客户端或编辑器连接 Coding Agent | 优先用于支持 Session、取消、权限和结构化事件的本地 Agent | -| A2A | 不同 Agent 通过 Agent Card、Task、Message、Artifact 协作 | 用于未来云 Agent 与跨组织 Agent，而不是替代本地 CLI | -| AG-UI | Agent Runtime 与前端之间的事件流 | 参考其事件模型，Renderer 仍只通过受限 Preload 访问主进程 | - -Meldwork 不需要再发明一个互不兼容的“万能 Agent 协议”。它需要做的是： - -- 对协议原生 Agent 直接适配。 -- 对传统 CLI 提供受控 Wrapper。 -- 把不同协议归一为 Meldwork 的 Task、Run、Artifact、Evidence 和 Decision 模型。 -- 通过兼容认证与真实场景评测告诉用户“哪个 Connector 在什么条件下可靠”。 - -### 2.3 竞争位置 - -| 类型或产品 | 已占据的优势 | Meldwork 不应硬碰的部分 | 可建立差异的部分 | -| --- | --- | --- | --- | -| GitHub Agent HQ | GitHub 工作入口、并行 Coding Agent、治理和任务可见性 | 不复制 GitHub 原生开发入口 | 跨代码、研究、知识平台和本地 Agent 的中立工作层 | -| Warp Oz | 云端 Agent 并行执行、运行环境、审计与 Workflow | 不先建设重型 Cloud Runner | Local-first、BYO Agent、私有上下文和本地 Handoff | -| OpenHands Agent Canvas | 本地/远程/云 Backend、ACP Agent、自动化 | 不做另一个纯 Coding Agent Control Center | 业务 Pack、Evidence/Adoption 和跨领域 Connector 评测 | -| LangGraph / AutoGen / CrewAI | 开发者可编程的多 Agent 框架 | 不与框架争夺 Python 编排开发者 | 面向终端用户的安装、治理、评测和交付体验 | -| 单厂商 General Agent | 模型、原生工具、Session 和推理能力 | 不训练自有通用模型 | 中立路由、专业 Agent 组合和结果可迁移性 | - -竞争产品已经证明“一个控制面可以启动多个 Agent”会很快成为基础能力。Meldwork 必须比这个基础层多交付三样东西： - -1. **跨厂商兼容可信度。** -2. **场景化 Agent Team 的可复用交付协议。** -3. **Artifact、Evidence、Decision 与 Adoption 形成的数据闭环。** - -## 3. Meldwork 当前基础与关键缺口 - -### 3.1 已有基础 - -当前仓库并不是从零开始： - -- Electron Main 已经是 Agent 执行、Provider、权限和本地持久化的信任边界。 -- `desktop/src/cli-adapters.cjs` 已支持多种本地 CLI 的发现、参数、结构化输出解析、Session 和取消差异。 -- `desktop/src/run-harness.cjs` 已有统一流式事件、上下文预算、Session 轮换和 Evidence Capsule 的基础。 -- `desktop/src/local-workspace.cjs` 已有有界自动讨论、超时、停止、失败隔离和运行状态。 -- Provider Key 已通过操作系统安全存储保护，Renderer 不接触原始凭据和可执行路径。 -- 当前实现已加入 OpenCodeReview，能够把当前 Workspace Diff 交给 `ocr review`，并通过兼容 Provider 注入运行。 - -这说明 Harness 并非纯概念，现有代码已经具备 Runtime 和安全边界的第一层。 - -### 3.2 OpenCodeReview 实验说明了什么 - -OpenCodeReview 是合适的第一项专项 Agent 实验，因为它不是“再接一个聊天模型”，而是把确定性文件选择、规则匹配、评论定位和专业 Review Agent 结合起来。其官方 Benchmark 声称，在相同底层模型下相对通用 Agent 获得更高 Precision/F1，并大幅减少 Token；该数据属于项目方自报，需要由 Meldwork 独立复验，但方向本身说明了专项 Harness 的价值： - -> 专项 Agent 的优势往往来自“确定性工程约束 + 领域工具 + 场景 Prompt + 评测数据”，而不仅是模型更强。 - -当前适配也暴露了下一步缺口：OpenCodeReview 在 Meldwork 中目前以文本格式接入、没有接入统一 Session 生命周期，并被标记为 `connector_limited`。这正适合作为 Connector Contract 的第一个升级样本，而不是继续为每个 Agent 增加一次性分支。 - -### 3.3 最大缺口 - -| 当前状态 | 结构问题 | 目标状态 | -| --- | --- | --- | -| Agent、命令、参数和 Parser 硬编码 | 每增加一个 Agent 都修改主逻辑 | Manifest + 主进程受控 Recipe + Connector SDK | -| Durable Center 仍是 Conversation | 能看到消息，难以回答任务是否完成 | Task / Run / Artifact / Evidence / Decision | -| 自动讨论按完整轮次顺序调用所有 Agent | 无关 Agent 也消耗时间和上下文 | 事件驱动 Task Graph，Agent 默认沉默 | -| 共识依赖 Agent 自报标记 | 一致不等于正确，分歧也可能有价值 | Evidence Gate、Verifier、Arbiter 和 Human Decision | -| 输出仍以 Final Text 为中心 | 代码、报告、引用和测试不够结构化 | Typed Artifact + Evidence Bundle | -| 能看到单次运行事件 | 缺少跨版本、跨 Agent 的回归数据 | Eval Harness + Agent Fit Matrix | -| Installer 使用可变上游包或脚本 | 供应链与兼容退化风险 | Pin、Checksum、签名、隔离安装和认证状态 | - -## 4. 目标架构 - -```mermaid -flowchart LR - U["用户 / Channel"] --> T["Task Compiler"] - T --> P["Planner + Router"] - P --> G["Task Graph / Blackboard"] - G --> S["Scheduler + Policy Engine"] - S --> R["Agent Runtime
Electron Main"] - R --> C["Connector Registry"] - C --> L["Local CLI / ACP Agent"] - C --> A["A2A / Cloud Agent"] - C --> W["Tool / Workflow Connector"] - R --> E["Normalized Run Events"] - E --> O["Artifact + Evidence Store"] - O --> V["Reviewer / Verifier / Arbiter"] - V --> D["Decision + Adoption"] - D --> G -``` - -### 4.1 核心组件 - -| 组件 | 责任 | 最小实现 | -| --- | --- | --- | -| Task Compiler | 把用户目标转成约束、验收标准和预期 Artifact | 用户确认后的结构化 Task，不自动臆造高风险权限 | -| Capability Registry | 记录 Agent、Tool 和 Workflow 的能力、版本和限制 | 本地 Manifest、健康状态、兼容等级 | -| Planner / Router | 决定单 Agent、多 Agent模式和任务拆分 | 先规则路由，再引入基于评测数据的模型路由 | -| Task Graph / Blackboard | 存放子任务、依赖、问题、Artifact、Evidence 和冲突 | 本地持久化事件图，不复制所有 Agent 私有思维过程 | -| Scheduler | 管理并发、预算、优先级、重试、暂停和取消 | 每 Workspace/Task/Agent 有界队列 | -| Agent Runtime | 启动、监控并终止本地或远程 Agent | 保持在 Electron Main，不向 Renderer 暴露任意执行 | -| Policy Engine | 判断读写、网络、数据出站、审批和采用规则 | 默认只读、显式写入、任务级 Human Gate | -| Artifact / Evidence Store | 捕获交付物、来源、测试和审查结果 | App-owned 本地对象，支持导出与复验 | -| Eval Harness | 在固定任务集上比较 Agent/Workflow 版本 | 质量、成本、耗时、失败和安全回归 | - -### 4.2 Local-first 与安全边界保持不变 - -- Renderer 只能提交 `connectorId`、Task、已选上下文和授权意图。 -- 可执行文件解析、命令 Recipe、环境变量、Secret 注入、进程树和网络策略都由 Main 控制。 -- Manifest 不能把 Renderer 输入直接拼成 Shell 命令。 -- Secret 只以安全存储引用存在，Connector 运行时按最小范围注入，不写入日志、Artifact 或导出包。 -- Cloud Agent 可以成为 Connector，但不要求把本地 Conversation、完整 Context Pack 或工作状态复制到 Meldwork 云端。 -- 写入 Workspace、发送外部消息、提交代码、创建 PR、发布文档等动作必须有独立 Policy 和审批边界。 - -## 5. Agent Connector Contract - -### 5.1 先区分 Agent、Tool 和 Workflow - -| 类型 | 判断标准 | 示例 | -| --- | --- | --- | -| Agent Connector | 能接收目标、动态规划或调用工具，并返回结果 | OpenCodeReview、gptme、mini-SWE-agent、PaperQA2 | -| Tool Connector | 提供确定性能力，由 Agent 或 Workflow 调用 | Browser、Git、测试命令、MCP Server | -| Workflow Connector | 按预定义 Pipeline 处理结构化输入输出 | DocETL、固定报告生成 Pipeline | - -这个分类很重要。把所有 CLI 都称为 Agent，会让路由、权限和评测失去意义。 - -### 5.2 Manifest 最小字段 - -下面是概念结构，不是直接允许执行的配置格式： - -```json -{ - "schemaVersion": 1, - "id": "example.agent", - "version": "1.2.0", - "kind": "agent", - "transport": { - "type": "cli", - "protocol": "jsonl" - }, - "discovery": { - "commands": ["example"], - "versionRange": ">=1.2 <2" - }, - "invocation": { - "recipeId": "example.agent.run" - }, - "capabilities": { - "domains": ["software-review"], - "sessions": true, - "resume": true, - "cancel": true, - "checkpoint": false, - "structuredOutput": true - }, - "permissions": { - "workspaceRead": "required", - "workspaceWrite": "optional", - "network": "required", - "sandbox": "supported" - }, - "artifacts": ["review-report"], - "evidence": ["file-location", "finding", "usage"], - "provider": { - "mode": "compatible", - "secretRef": "os-secure-storage" - }, - "license": "Apache-2.0" -} -``` - -`recipeId` 必须指向 Meldwork Main 中经过审核或签名的调用 Recipe。Manifest 本身不能提供任意 Shell 片段。 - -完整 Contract 至少要声明： - -- 发现、安装、版本、升级、卸载和健康检查。 -- 输入方式：参数、stdin、文件、ACP、A2A 或 HTTP。 -- 输出方式：文本、JSON、JSONL、事件流和退出码语义。 -- Session、Resume、Cancel、Checkpoint、Retry 和幂等性。 -- Workspace 读写、网络、浏览器、Shell、外部消息和审批需求。 -- Provider 类型、数据出站目标、Secret 映射和用户自带账号要求。 -- Artifact 类型、Evidence 类型、成本、耗时和使用量可观测性。 -- License、上游来源、依赖、已知漏洞和支持平台。 - -### 5.3 兼容等级 - -| 等级 | Contract 能力 | 产品承诺 | -| --- | --- | --- | -| L0 Text | 非交互文本输入输出、退出码和超时 | 可调用，但结果需要人工整理 | -| L1 Structured | JSON/JSONL、结构化状态和 Artifact | 可稳定显示和捕获结果 | -| L2 Managed | Session、取消、权限、Usage、Checkpoint 或可恢复状态 | 可进入有界 Workflow | -| L3 Protocol-native | ACP/A2A 等协议原生，事件和生命周期完整 | 可参与动态 Task Graph | -| Certified | 通过 Meldwork 场景评测、安全、取消、故障恢复和版本回归 | 可进入官方 Agent Pack 和企业支持矩阵 | - -“支持”与“认证”必须分开。社区可以提交 L0/L1 Connector，但官方 Pack 只使用经过认证的版本组合。 - -### 5.4 统一运行事件 - -建议在当前 Run Event 基础上逐步支持： - -```text -TaskProposed TaskClaimed RunStarted -ProgressUpdated PermissionRequested CheckpointSaved -ArtifactPublished EvidenceAttached ReviewRequested -QuestionDirected ObjectionRaised DecisionProposed -DecisionAccepted RunCompleted RunFailed / RunCancelled -``` - -Connector 可以保留自己的 Raw Event，但进入产品状态、日志和 UI 前必须归一化、限长和脱敏。 - -## 6. 从轮询讨论升级为动态 Agent Team - -### 6.1 当前自动讨论为什么不够 - -当前实现会让所有目标 Agent 按完整轮次顺序发言，默认 6 轮，固定模式最多 10 轮；显式“不限轮数”模式没有整体运行时限，只在达成共识或用户手动停止时结束，同时保留单个 Agent 的独立 watchdog 超时。HTTP 401/403 和兼容性失败会在首次失败后结束该 Agent 当前槽位，保留群聊配置，并要求用户在修复配置后显式重试或替换；网络和限流失败才会使用有界退避重试。它仍是顺序轮询的 MVP，存在四个结构问题： - -- C、D 即使没有任务或新信息也必须发言。 -- 后发 Agent 被迫消费前序消息，成本随轮次和 Agent 数快速增长。 -- “达成共识”依赖模型自报，不能证明结论正确。 -- 任务进度隐藏在聊天顺序里，不能独立重试、复核或恢复一个子任务。 - -### 6.2 推荐模型：中心协调、分布执行、证据裁决 - -建议采用 **Task Graph + Blackboard + Event-driven Activation**： - -- Task Graph 表达子任务、依赖、验收条件和预算。 -- Blackboard 记录可共享的 Artifact、Evidence、问题、异议和 Decision，不要求共享所有 Agent 完整对话。 -- Planner/Orchestrator 负责计划、状态和重规划。 -- Worker 并行执行可独立的子任务。 -- Reviewer 和 Verifier 按风险或 Evidence 缺口触发。 -- Arbiter 在冲突无法通过确定性证据消解时提出选项，不伪造共识。 - -Planner、Worker、Reviewer、Verifier、Arbiter 是**运行时角色**，不应永久绑定某个 Agent。OpenCodeReview 可以在代码任务中承担 Reviewer，但在研究任务中没有必要出现。 - -### 6.3 Agent 默认沉默 - -一个 Agent 只有在以下条件之一成立时才被激活： - -1. 被明确分配了未完成子任务。 -2. 收到另一个 Agent 的定向问题。 -3. Policy 要求独立 Review 或 Verification。 -4. 新 Evidence 与它负责的 Artifact 冲突。 -5. 当前 Agent 失败、超时或能力不足，需要接管。 -6. 用户明确要求独立观点或对抗性审查。 - -没有任务、没有问题、没有新证据时，Agent 保持沉默。这一条比“让讨论更像真人”更重要，因为它直接降低成本并提高可读性。 - -### 6.4 协作模式由任务结构决定 - -| 任务特征 | 默认模式 | 不应使用的模式 | -| --- | --- | --- | -| 共享上下文很大、步骤强依赖 | 单 Agent + Checkpoint | 多 Agent 全量复制上下文 | -| 子任务可独立并行、覆盖面重要 | Orchestrator-workers | 固定顺序轮询 | -| 有清晰类别或能力映射 | Router | 所有 Agent 都尝试 | -| 高风险产物需要独立检查 | Primary + Reviewer + Verifier | 自报共识 | -| 方案空间开放、需要多样观点 | 2-3 个独立 Attempt + Arbiter | 长轮次自由辩论 | -| 输出可通过测试或规则检查 | Evaluator-optimizer | 仅靠语言互评 | - -### 6.5 A、B、C、D 的目标交互 - -假设用户交给四个 Agent 一个复杂任务： - -1. Planner 生成 `T1 调研`、`T2 实施`、`T3 Review`、`T4 验证`，并标记依赖。 -2. A 负责调研，C 同时负责可独立实施的部分；B、D 此时保持沉默。 -3. A 发布 Evidence，C 发布 Artifact。 -4. B 因 Review Policy 被激活，只检查 C 的 Artifact 和验收标准。 -5. B 对 A 的一项 Evidence 提出定向问题，只有 A 和 B 进入局部讨论；C 可以继续修复其他 Finding，D 仍保持沉默。 -6. D 只在测试、引用或权限验证阶段被激活，发布可复验 Evidence。 -7. 如果 B 的异议被测试消解，Task 进入 Decision；如果无法消解，Arbiter 把分歧、证据和选项交给用户，而不是要求四个 Agent 继续发言。 - -这才是“像团队一样工作”：不是每个人按顺序讲话，而是每个角色在需要时承担责任。 - -### 6.6 决策不能等于共识 - -建议使用以下结束条件： - -- 验收标准全部有对应 Artifact。 -- 必需 Evidence 已达到 `Observed` 或 `Reproduced`，不能只有 Agent 的 `Declared`。 -- 高优先级 Reviewer Finding 已关闭、接受风险或提交 Human Gate。 -- 测试、引用、Schema 或 Policy Gate 通过。 -- 成本、时间和 Review Loop 没有超过预算。 - -保留未解决分歧比伪造全员一致更可信。 - -### 6.7 自治等级 - -| 等级 | 能力 | 默认人类位置 | -| --- | --- | --- | -| A0 Assist | Agent 给建议，不执行 | 每步决定 | -| A1 Execute | 单 Agent 完成一个有界 Task | 结果验收 | -| A2 Review | Primary + Reviewer，允许一次修订 | 最终采用 | -| A3 Team | Task Graph、局部协作、Checkpoint 和故障接管 | 权限/预算/高风险 Gate | -| A4 Policy-autonomous | 对预先批准的重复 Workflow 无人值守运行 | 异常和最终抽查 | - -近期目标是可靠达到 A2，再在两个业务 Pack 中验证 A3。不要把任意任务的 A4 当作近期承诺。 - -## 7. 评测系统与真正的产品壁垒 - -### 7.1 Agent Fit Matrix - -每次认证和用户运行应逐步形成以下矩阵： - -```text -Task Type x Agent x Connector Version x Model/Provider x OS x Permission Mode - -> Quality / Cost / Latency / Failure / Evidence / Adoption -``` - -路由器先使用显式规则和本地历史，再考虑模型预测。用户数据默认留在本地；只有用户单独同意时，才上传不含 Prompt、原文、Artifact 和 Secret 的最小派生指标。 - -### 7.2 每个 Agent Pack 都需要固定评测集 - -至少覆盖： - -- 正常任务、模糊任务和不可完成任务。 -- 权限不足、Provider 失败、CLI 升级和输出格式变化。 -- 中断、取消、Resume、Checkpoint 和超时恢复。 -- 恶意 Prompt、Workspace 中的非可信指令和 Secret 泄漏测试。 -- Artifact 完整性、Evidence 可复验性和 Human Adoption。 - -### 7.3 五层壁垒 - -| 壁垒 | 为什么能积累 | -| --- | --- | -| Connector Compatibility Data | 哪个版本在什么 OS、Provider 和权限下真实可用，需要持续测试和故障数据 | -| Task-specific Evaluation | 专项 Agent 是否比通用 Agent 更好，需要真实任务、评分标准和回归历史 | -| Outcome & Evidence Graph | 记录什么结果被采用、什么 Evidence 真正有效，形成跨 Agent 的工作记忆 | -| Business Agent Packs | 把行业交付标准、角色、Policy 和 Workflow 产品化，而不是卖一次性 Prompt | -| Trust & Governance | 本地控制、权限、审计、签名 Connector 和企业支持形成迁移成本 | - -开源代码本身不是壁垒。若这些数据、协议和业务 Pack 没有形成，项目就仍然只是一个可复制的 Wrapper。 - -## 8. 首发业务 Agent Pack - -首发只建议做两个 Pack。它们场景差异足够大，可以验证 Harness 是否通用；又能共享 Task、Artifact、Evidence、Review 和 Decision 核心对象。 - -### 8.1 Software Delivery Pack - -**目标客户：** 3-30 人研发团队、外包交付团队、AI Coding 高频个人开发者。 - -**推荐团队：** - -- Implementer：用户已有 Coding Agent。 -- Reviewer：OpenCodeReview。 -- Verifier：确定性测试、Lint、构建命令；必要时增加第二 Agent 解释失败。 -- Arbiter：只在 Review Finding 与测试证据冲突时加入。 - -**工作协议：** - -```text -Issue / Task - -> Plan - -> Code Artifact - -> OpenCodeReview Findings - -> Targeted Revision - -> Test Evidence - -> Human Apply / Commit / Reject -``` - -**可售价值：** 更少人工整理、更高 Finding Precision、可追溯测试证据、跨 Coding Agent 的统一 Review Policy。 - -**首轮指标：** - -- 相对“单 Coding Agent 自检”，高优先级缺陷发现率提升至少 15%。 -- Reviewer 被人类接受的 Finding Precision 至少 70%，并持续记录误报。 -- 完成相同验收标准时，主动人工协调时间中位数下降至少 25%。 -- 多 Agent 总成本不超过最佳单 Agent 基线的 2.5 倍；超过时必须证明返工或风险显著下降。 - -### 8.2 Research Evidence Pack - -**目标客户：** 研究、咨询、产品战略、投研和需要引用依据的知识团队。 - -**推荐团队：** - -- Researcher：GPT Researcher、gptme 或其他 Web Research Agent。 -- Literature Specialist：PaperQA2，处理用户提供或授权的科学文献集合。 -- Source Verifier：检查来源可访问性、引用与主张对应关系。 -- Reviewer：检查遗漏、冲突、时间口径和结论过度外推。 - -**工作协议：** - -```text -Research Question - -> Search Plan - -> Parallel Source Tasks - -> Evidence Cards - -> Draft Artifact - -> Citation / Claim Verification - -> Decision Brief - -> Human Adopt / Request Revision -``` - -**可售价值：** 来源透明、研究过程可复盘、引用与主张可追踪、不同 Research Agent 的结果可比较。 - -**首轮指标：** - -- 95% 的核心事实主张能链接到具体 Evidence。 -- 抽样引用中，主张与来源匹配率至少 90%。 -- 相对单 Agent，重要来源覆盖或有效结论评分提升至少 15%。 -- 若多 Agent 成本超过单 Agent 3 倍，必须把研究广度、引用质量或交付速度的提升量化，否则退回单 Agent。 - -### 8.3 暂不作为首发 Pack - -- Security/Pentest：权限和法律风险高，只能在客户书面授权环境中验证。 -- 浏览器自动化：可作为 Tool 或受限 Agent Connector，不能默认获得账号、支付、发布和消息权限。 -- 大规模文档 ETL：DocETL 更适合作为 Workflow Connector，待 Task/Artifact Contract 稳定后加入。 -- 通用“十人专家团”：缺少明确 Artifact 和验收标准，不构成产品 Pack。 - -## 9. GitHub CLI Agent 候选矩阵 - -下面的优先级是接入研究建议，不是当前支持承诺。License 和依赖商业条款必须在每次发行和企业打包前重新核对。 - -| 项目 | 类型 | 专项能力与接口 | 建议角色 | 优先级 | 主要风险 | -| --- | --- | --- | --- | --- | --- | -| [OpenCodeReview](https://github.com/alibaba/open-code-review) | Agent | `ocr review/scan`、代码审查、Session、行级 Finding；Apache-2.0 | Software Reviewer | P0，当前首个样本 | 当前 Meldwork 仅文本接入；官方 Benchmark 需独立复验 | -| [gptme](https://github.com/gptme/gptme) | Agent | 非交互模式、JSONL、Resume、MCP、ACP；MIT | Connector Contract 基准、通用 Worker | P0 | 权限面广，需明确 Tool Policy 和 Sandbox | -| [PaperQA2](https://github.com/Future-House/paper-qa) | Agent | `pqa ask`、本地论文索引、引用回答；Apache-2.0 | Literature Specialist | P0 | 索引成本、元数据服务和引用许可边界 | -| [mini-SWE-agent](https://github.com/SWE-agent/mini-swe-agent) | Agent | `mini` CLI、Issue 修复、Trajectory、本地/容器环境；MIT | Software Implementer 对照组 | P1 | Shell 权限、长运行和 Workspace 副作用 | -| [Open Interpreter](https://github.com/OpenInterpreter/openinterpreter) | Agent | ACP、Codex exec 协议、跨平台 Sandbox；Apache-2.0 | Protocol-native Worker | P1 | 执行能力强，必须验证审批与 Sandbox 真实边界 | -| [GPT Researcher](https://github.com/assafelovic/gpt-researcher) | Agent/框架 | Web Research、并行检索、引用报告；Apache-2.0 | Web Researcher | P1，需要 Wrapper | CLI/库输出需归一，搜索 Provider 和成本依赖较多 | -| [DocETL](https://github.com/ucbepic/docetl) | Workflow | `docetl run pipeline.yaml`、结构化文档 ETL；MIT | Document Workflow | P1，按 Workflow 接入 | 不应伪装成自主 Agent；Pipeline 写入和成本需声明 | -| [SWE-agent](https://github.com/SWE-agent/SWE-agent) | Agent | `sweagent run`、完整 Trajectory、Docker 默认；MIT | 重型 Coding 对照组 | P2 | 安装和容器成本高，不符合默认轻量体验 | -| [STORM](https://github.com/stanford-oval/storm) | Agentic System | 多阶段研究与带引用长报告；MIT | Research Workflow 参考 | P2，观察 | 稳定 CLI Contract 和维护活跃度弱于首选项 | -| [browser-use](https://github.com/browser-use/browser-use) | Agent/Tool | 浏览器控制和 Web Agent；MIT | Browser Worker | P2，受限实验 | 账号、Cookie、外部副作用和 Prompt Injection 风险高 | -| [PentestGPT](https://github.com/GreyDGL/PentestGPT) | Agent Framework | 渗透测试任务编排；MIT | 授权安全 Pack | 暂缓 | 法律、网络扫描、破坏性操作和责任边界 | - -### 9.1 接入评分门槛 - -建议按 100 分评估： - -| 维度 | 分值 | 关键问题 | -| --- | ---: | --- | -| 接口成熟度 | 20 | 是否非交互、结构化、可取消、可 Resume、错误语义稳定 | -| 安全与权限 | 20 | 是否可只读、Sandbox、限制网络和外部副作用 | -| Artifact / Evidence | 20 | 是否能交付结构化产物、来源、Finding、Trajectory 或测试 | -| 稳定与维护 | 15 | 版本节奏、测试、跨平台、失败恢复和可 Pin | -| 场景差异化 | 15 | 是否在专项任务中明显优于已有通用 Agent | -| License 与运维 | 10 | 商业许可、依赖、安装体积和支持成本 | - -- 低于 60 分：不接入。 -- 60-74 分：社区实验，不进入官方 Pack。 -- 75-84 分：Pilot Connector。 -- 85 分以上且通过回归：Certified Connector。 - -接入目标不应是“每月新增多少 Agent”，而应是“一个外部贡献者能否在不修改核心调度代码的情况下，于一天内完成 L1 Connector，并通过固定 Contract Test”。 - -## 10. 商业化路径 - -### 10.1 收入结构 - -| 层级 | 交付内容 | 收费理由 | -| --- | --- | --- | -| Community | Local-first 核心、基础 Connector、Task/Artifact 协议 | 建立信任、生态和贡献入口 | -| Pro | 官方 Agent Pack、评测比较、Evidence 导出、Workflow 版本 | 为个人持续交付和节省时间收费 | -| Team | 共享 Policy、预算、Workflow、兼容报告和可选同步 | 为团队一致性和管理成本收费 | -| Enterprise | 私有部署、签名 Connector、离线更新、审计、RBAC 和 SLA | 为风险、治理和支持责任收费 | -| Services | 按客户业务部署一套 Agent Team，并完成首批 Workflow | 用真实项目发现需求并资助产品化 | - -不建议默认对模型 Token 加价。BYO Agent、BYO Provider、BYO Knowledge 能降低毛利风险，也更符合中立控制层定位。 - -### 10.2 价格验证区间 - -以下仅用于付款意愿测试，不是正式定价： - -| 产品 | 建议测试区间 | -| --- | ---: | -| Pro | 99-199 元/月 | -| Team | 199-399 元/用户/月，或 1,999 元/月 Workspace 起 | -| Enterprise | 20-80 万元/年，按私有部署、治理和 SLA 范围报价 | -| 标准化 Pilot Service | 5-20 万元/4-8 周，只交付一个业务 Pack | - -价格不能先于价值验证。首批收费更重要的指标是：客户是否愿意为相同标准化能力续费，而不是一次定制项目金额。 - -### 10.3 适合 OPC 的服务产品化路径 - -1. 用“Agent Team 交付诊断”进入客户：识别重复任务、数据边界、验收标准和当前人工成本。 -2. 只售卖固定范围 Pilot：一个 Pack、一个部门、2-3 个 Workflow、明确成功指标。 -3. 客户特有逻辑放在 Connector/Policy/Template，核心 Engine 不接受单客户分叉。 -4. 每个定制需求必须回答“是否能被至少三家同类客户复用”；不能复用则按高价服务交付，不进入主产品。 -5. 服务收入与标准化软件收入分开核算，避免把创始人的工时误认为产品增长。 - -OPC 可承受的运营门槛建议是： - -- 认证 Connector 数量保持在 5-8 个，而不是无限扩张。 -- 单客户月均支持时间低于 4 小时。 -- 除模型费用外的软件毛利目标高于 75%。 -- 连续两个季度，标准化产品和 Pack 收入占总收入至少 60%。 -- 任何单一客户不应长期贡献超过 35% 收入。 - -### 10.4 首批 ICP 与销售动作 - -优先两类客户： - -- 已经同时使用两种以上 Coding Agent、代码交付频繁、Review 人力不足的小研发团队。 -- 每周重复产出研究、咨询或决策报告，且对来源、引用和复核有明确要求的知识团队。 - -销售路径： - -```text -现状诊断 - -> 用客户真实任务做单 Agent 基线 - -> 部署一个 Agent Pack - -> 比较质量 / 成本 / 人工时间 - -> 交付 Evidence 与兼容报告 - -> 续费软件或私有部署 -``` - -## 11. 12 个月路线图 - -### Phase A：Contract 与 Outcome 基础，0-6 周 - -**交付：** - -- Task、Run、Artifact、Evidence、Decision 的本地最小模型。 -- Agent Connector Manifest v0 和 Contract Test Harness。 -- 把 OpenCodeReview 从一次性适配升级为首个 L1/L2 样本。 -- 选择 gptme 或另一个结构化 CLI 作为第二种实现，验证 Contract 不是为 OCR 特制。 -- 20 个 Software Delivery 基准任务，记录单 Agent 基线。 - -**阶段门：** - -- 任何 Secret 不进入 Renderer、日志、Artifact 和导出包。 -- 取消后的进程树清理成功率至少 99%。 -- Artifact 捕获完整率至少 90%。 -- 新 Connector 不修改 `local-workspace.cjs` 的业务分支。 - -### Phase B：Software Delivery Pack，6-12 周 - -**交付：** - -- Primary + OpenCodeReview + Deterministic Verifier 工作协议。 -- Finding、修订、测试 Evidence 和 Human Adoption 界面。 -- 单 Agent 与 Pack 的质量、成本和耗时对照。 -- 5 个外部设计伙伴、至少 30 个真实 Task。 - -**阶段门：** - -- 至少 70% 的高优先级 Review Finding 被用户接受。 -- 人工协调时间中位数下降至少 25%。 -- 至少 3 个设计伙伴在 30 天内重复使用。 -- 若 Pack 不优于最佳单 Agent，则停止增加 Coding Agent，先修 Workflow 和 Evidence。 - -### Phase C：Research Evidence Pack 与事件驱动协作，3-6 个月 - -**交付：** - -- PaperQA2 加一个 Web Research Agent 的 Pilot Connector。 -- Evidence Card、Claim-Citation Link 和 Source Verification。 -- Task Graph、定向问题、Review Request、Objection 和 Agent 默认沉默。 -- Connector 兼容等级和本地认证报告。 - -**阶段门：** - -- 15 名固定用户中至少 8 名完成 30 天重复 Outcome。 -- 研究核心主张的 Evidence 覆盖率至少 95%。 -- 多 Agent 只在已验证任务类型中启用，质量提升至少 15% 或返工下降至少 25%。 -- 至少一个外部贡献的 Connector 或 Eval Task 被合并。 - -### Phase D：动态路由、恢复与付费 Pilot，6-9 个月 - -**交付：** - -- 基于任务类型、能力、预算和本地评测的 Router。 -- Checkpoint、失败接管、Agent 替换、重试和降级到单 Agent。 -- Workflow 版本、Policy Pack 和 Evidence Bundle 导出。 -- 3 个标准化付费 Pilot，服务与软件收入分别核算。 - -**阶段门：** - -- Run 成功或可解释失败率至少 95%。 -- Connector 版本退化能在发布前被 Contract/Eval Test 捕获。 -- 单客户月均支持时间低于 8 小时，并持续下降。 -- 至少 2 个客户愿意为同一 Pack 续费，而不是购买新定制。 - -### Phase E：Team / Enterprise 条件阶段，9-12 个月 - -**进入条件：** 至少 3 个团队为同一标准化能力付费，且重复使用和支持成本成立。 - -**候选交付：** - -- 共享 Workflow、Policy、预算和兼容矩阵。 -- 签名 Connector、离线更新、RBAC、审计和可选加密同步。 -- 对预先批准 Workflow 的 A4 Policy-autonomous 运行。 -- 企业部署工具和 SLA，而不是为每个客户维护独立分支。 - -## 12. 指标体系 - -### 12.1 北极星 - -**每周被实际采用并完成验证的 Artifact 数。** - -不以 Agent 数、消息数、轮次数或自动运行时长作为成功指标。 - -### 12.2 产品与质量 - -- 首次 Verified Artifact 完成时间。 -- Task 完成率、Adoption 率和 Reopen 率。 -- Reviewer Finding Precision、有效缺陷增量和误报率。 -- Evidence 覆盖率、可复验率和来源失效率。 -- 相对最佳单 Agent 的质量提升、返工下降和人工协调时间下降。 - -### 12.3 Harness 与扩展性 - -- Run 取消、超时和恢复成功率。 -- Session Resume、Checkpoint 和 Artifact 捕获完整率。 -- 新 L1 Connector 的开发时间。 -- Certified Connector 的版本回归率和平均修复时间。 -- 多 Agent 协调开销：额外 Token、等待、重复上下文和无效激活次数。 - -### 12.4 商业 - -- 设计伙伴到付费 Pilot 转化率。 -- Pilot 到续费/年付转化率。 -- 标准化收入与定制服务收入占比。 -- 单客户支持工时、部署时间和贡献毛利。 -- 同一 Pack 的付费客户数，而不是总客户数。 - -### 12.5 安全 - -- Secret 泄漏和权限越界事件必须为 0。 -- 未经批准的 Workspace 写入和外部副作用必须为 0。 -- 高风险任务 Human Gate 覆盖率 100%。 -- Connector 安装来源、版本和校验信息可追溯率 100%。 - -## 13. 停止条件与收缩策略 - -| 观察 | 决策 | -| --- | --- | -| 15 名固定用户中少于 8 名完成 30 天重复 Outcome | 不扩 Cloud/Team，先收缩激活与 Outcome 闭环 | -| 多 Agent 在目标任务上质量提升低于 10%，且成本超过单 Agent 2.5-3 倍 | 停止 Swarm，保留单 Agent + Reviewer | -| Connector 维护连续两个月占创始人时间超过 30% | 缩减认证列表，优先协议原生 Agent 和社区维护 | -| 两个 Pack 共享的核心 Engine 低于约 70% | 不再声称通用 Harness，选择一个垂直场景 | -| 超过 50% Pilot 收入来自不可复用定制，且复用率不提升 | 把业务定义为服务公司，或停止该垂直方向 | -| 出现 Secret 泄漏、未授权写入或无法可靠取消 | 暂停无人值守和企业销售，先修安全边界 | -| 用户只把产品当统一聊天窗口，Artifact/Decision 使用率低 | 保留个人工具，不继续投入复杂 Team/Workflow | - -## 14. 明确不做 - -近期不做： - -- 以“支持 100 个 Agent”作为版本目标。 -- 默认启动多个 Agent 或无限轮次 Swarm。 -- 把全员一致当作正确性证明。 -- 允许 Renderer 或第三方 Manifest 直接提交任意 Shell 命令。 -- 在 Outcome 闭环前建设重型云平台、远程 Conversation Store 或多租户系统。 -- 自建 General Model、IDE、完整知识中台或 Token Marketplace。 -- 同时产品化多个高风险垂直行业。 -- 为单客户长期维护核心代码分叉。 - -## 15. 下一步建议 - -接下来 30 天按以下顺序推进： - -1. 写一份 `Agent Connector Contract v0` ADR，固定 Agent/Tool/Workflow 分类、Manifest、事件和安全边界。 -2. 用 OpenCodeReview 与 gptme 两个差异明显的 CLI 做 Contract Spike，不再新增第三个硬编码 Agent。 -3. 建立 20 个真实 Software Delivery Eval Task，先测当前单 Agent 和 OpenCodeReview 组合基线。 -4. 落地最小 Task、Artifact、Evidence 和 Human Decision，不先做复杂 Task Graph UI。 -5. 交付 Software Delivery Pack 的 Primary + Reviewer + Verifier 闭环。 -6. 找 5 个真实设计伙伴，用质量、人工时间、成本和重复使用决定是否进入 Research Pack。 - -最关键的工程顺序仍然是： - -```text -Outcome Contract - -> Connector Contract - -> Evaluation - -> One Business Pack - -> Event-driven Team - -> Workflow / Enterprise -``` - -如果顺序反过来，Meldwork 会得到更多 Agent、更多动画和更多运行状态，但不会得到更好的交付结果或可持续商业模式。 - -## 16. 最终判断 - -这个方向值得做，原因不是“多 Agent 很热门”，而是市场中会长期存在大量能力不同、归属不同、运行位置不同的 Agent。用户和企业需要一个不依赖单一厂商的层，把它们组织成可控、可恢复、可验证的工作系统。 - -但 Meldwork 的壁垒不能停在“无缝接入”。真正应争取的是： - -1. 最可信的跨 Agent 兼容与认证层。 -2. 最清楚的 Task、Artifact、Evidence 和 Decision 工作协议。 -3. 最节制、按任务触发的动态 Agent Team。 -4. 两个能够量化 ROI、可重复部署的业务 Agent Pack。 -5. 一套小团队也能运营的 Local-first 治理与商业模型。 - -做到这些，Meldwork 才有机会成为一家 OPC 的产品核心；只做到聚合 CLI，它会是一个有用的开源客户端，但很难形成持续壁垒。 - -## 17. 主要来源 - -### Agent 架构与评测 - -- Anthropic：[Building effective agents](https://www.anthropic.com/research/building-effective-agents) -- Anthropic：[How we built our multi-agent research system](https://www.anthropic.com/engineering/multi-agent-research-system)。`90.2%` 为 Anthropic 内部 Research Eval，`15x` 为其披露的相对普通聊天 Token 使用量，不应外推为所有任务。 -- Kim et al.：[Towards a Science of Scaling Agent Systems](https://arxiv.org/abs/2512.08296v3) -- Fourney et al.：[Magentic-One: A Generalist Multi-Agent System for Solving Complex Tasks](https://arxiv.org/abs/2411.04468) - -### 开放协议 - -- [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) -- [Agent Client Protocol](https://agentclientprotocol.com/get-started/introduction) -- [Agent2Agent Protocol](https://a2a-protocol.org/latest/) -- [AG-UI Protocol](https://docs.ag-ui.com/introduction) - -### 竞争产品与框架 - -- GitHub：[Introducing Agent HQ](https://github.blog/news-insights/company-news/welcome-home-agents/) -- Warp：[Oz Cloud Agent Platform](https://www.warp.dev/oz) -- OpenHands：[Agent Canvas](https://github.com/OpenHands/OpenHands) -- [LangGraph](https://docs.langchain.com/oss/python/langgraph/overview) -- [AutoGen](https://microsoft.github.io/autogen/stable/) -- [CrewAI](https://docs.crewai.com/) - -### 专项 Agent 与 Workflow - -- [OpenCodeReview](https://github.com/alibaba/open-code-review) -- [gptme](https://github.com/gptme/gptme) -- [PaperQA2](https://github.com/Future-House/paper-qa) -- [mini-SWE-agent](https://github.com/SWE-agent/mini-swe-agent) -- [SWE-agent](https://github.com/SWE-agent/SWE-agent) -- [Open Interpreter](https://github.com/OpenInterpreter/openinterpreter) -- [GPT Researcher](https://github.com/assafelovic/gpt-researcher) -- [STORM](https://github.com/stanford-oval/storm) -- [DocETL](https://github.com/ucbepic/docetl) -- [browser-use](https://github.com/browser-use/browser-use) -- [PentestGPT](https://github.com/GreyDGL/PentestGPT) diff --git a/docs/launch-kit.md b/docs/launch-kit.md deleted file mode 100644 index c3c7d11..0000000 --- a/docs/launch-kit.md +++ /dev/null @@ -1,65 +0,0 @@ -# Meldwork Launch Kit - -This document contains draft public-relations and repository-launch copy for the current MVP. `Meldwork` still requires trademark, domain, and user-understanding checks. Publish only copy that matches the repository's AGPL Community Edition and commercial-license policy docs. - -## Positioning - -**Current MVP category:** Local-first desktop workspace for a bounded two-Agent produce-and-review loop - -**Current product line:** Agents change. Work continues. - -**Chinese:** Agent 可切换，工作不断线。 - -**Current one sentence:** Meldwork lets two supported local Agents produce and challenge one deliverable in a persistent local workspace, with explicit context, permissions, and reviewable execution state. - -**Chinese:** Meldwork 让两个已支持的本地 Agent 在同一个持续存在的本地工作空间里产出并复核一份交付物，同时保留明确的上下文、权限和可复盘运行状态。 - -**Target product category:** An open, local-first work system for compatible Agents and knowledge sources across vendors. - -**Target architecture line:** Agents and knowledge sources should join through explicit capabilities, permissions, events, and egress declarations. - -The target category and architecture line describe product direction. The current MVP still uses a fixed set of local CLI adapters and does not automatically merge separate direct and group conversation histories. - -## Launch headline - -Introducing Meldwork: a persistent workspace for the Agents you already use - -After the public connector contract is added, use: - -Introducing Meldwork: an open, local-first workspace for Agents and knowledge - -## Short announcement - -Meldwork is a local-first desktop workspace for a bounded two-Agent review loop. The current MVP discovers supported local Agent CLIs, keeps direct and group conversations persistent, resumes compatible native sessions, accepts validated task files, and records sanitized execution state. Its first public workflow is simple: one Agent produces a deliverable, a second challenges assumptions and evidence, and the human decides what to adopt. Other domains and future Connector capabilities remain examples or roadmap items. - -## Chinese announcement - -Meldwork 是面向双 Agent 有界复核的本地优先桌面工作空间。当前 MVP 可以发现已支持的本地 Agent CLI、持久保存单聊与群组会话、在兼容条件下恢复原生 Session、接收经过验证的任务文件，并记录脱敏运行状态。公开首发只承诺一个闭环：一个 Agent 形成交付物，第二个检查假设与证据，最后由人决定是否采用。其他业务领域和未来 Connector 能力仍属于示例或路线图。 - -## Story structure - -1. People and teams increasingly use several capable Agents and many knowledge sources, but their context, sessions, permissions, and outputs remain fragmented. -2. Meldwork gives supported local Agents and explicitly selected knowledge sources one persistent workspace without asking users to replace their Agent, Provider, or content platform relationships. -3. The current MVP demo should show one clean-profile two-Agent produce-and-review task from Agent readiness through human review. -4. Connector contracts, Cloud transport, and Channel ingress are platform capabilities, not required public-MVP demo claims until a production implementation is configured. -5. Task, Context Pack, Run, Artifact, Evidence, and human Adoption records support durability and review, but the launch story should stay focused on the user-visible produce-and-review loop. -6. The product difference must come from continuity, open connection, evidence, acceptance, and explicit permission boundaries, not from displaying more Agent avatars. -7. Local-first does not mean every model is offline; selected Providers may still use the network. - -## Pull request summary - -### What changed - -- Repositioned Meldwork from a coding-Agent CLI aggregator to a persistent workspace for general-purpose Agents. -- Rewrote the English and Chinese READMEs around user work fragmentation, current MVP facts, and the open Agent/knowledge Connector direction. -- Adopted the asymmetric Trace V3 identity across the client, Electron icon, favicon, brand board, and README campaign assets. -- Added separate English and Chinese 1600 x 640 README banners using a generated text-free visual plate with exact local logos and typography. -- Removed the superseded V2 and coding-specific README banner assets. - -### Why - -Agent products are converging toward general-purpose work systems. Meldwork's category should be defined by persistent cross-Agent work and an open connection model, not by the coding origins or names of the first supported tools. The Trace line represents continuity across Agent changes; the open connector and separated coral point represent extensibility and explicit human control. - -### Verification - -Before merge, record the exact frontend and desktop tests executed, image dimensions, SVG validation, README-link checks, theme-logo checks, live-Agent checks, Electron screenshots, and release steps that were intentionally not run. Do not claim arbitrary Agent connectivity, packaging, signing, notarization, or target-device compatibility without direct evidence. diff --git a/docs/macos-signing.md b/docs/macos-signing.md deleted file mode 100644 index c793bb5..0000000 --- a/docs/macos-signing.md +++ /dev/null @@ -1,141 +0,0 @@ -# macOS Developer ID 签名与 Apple 公证 - -当前内测版本采用临时签名（ad-hoc signing）。面向公众分发 DMG 和 ZIP 时，必须使用 `Developer ID Application` 证书完成签名，并提交 Apple 公证，确保应用能够在全新 Mac 上通过 Gatekeeper 检查。 - -## 1. 加入 Apple Developer Program - -1. 使用将来负责发布 Meldwork 的 Apple ID 登录 [Apple Developer Program](https://developer.apple.com/programs/)。 -2. 为 Apple ID 开启双重认证，然后加入 Apple Developer Program。Apple 会收取年度会员费，具体人民币价格和身份验证要求以申请页面为准。 -3. 如果未来由公司或机构发布，建议使用法人主体加入，而不是个人账号。Apple 可能要求提供 D-U-N-S 编号，并验证申请人是否有权代表该组织签署协议。 -4. 申请通过后，在 Membership 页面记录十位字符的 Apple Team ID。 - -审核时间可能从几小时到数个工作日不等，取决于个人身份或组织资质验证。这个申请过程无法通过本仓库自动完成。 - -## 2. 注册固定的应用标识 - -Meldwork 的正式 Bundle ID 是 `com.rydersun.meldwork`。必须在第一次签名并公证发布前注册这个标识，之后保持不变。后续修改 Bundle ID 可能影响 macOS 应用身份、系统权限、钥匙串数据访问和升级连续性。 - -进入 Apple Developer 网站的 Certificates, Identifiers & Profiles，在 Identifiers 中注册 `com.rydersun.meldwork`。首次公开发布后不要更换这个标识。 - -## 3. 创建签名证书 - -推荐在发布用 Mac 上通过 Xcode 创建证书： - -1. 安装发布 Mac 所支持的最新稳定版 Xcode。 -2. 打开 Xcode 设置，进入 Accounts，添加已经加入 Apple Developer Program 的 Apple ID，并选择正确的 Team。 -3. 打开 Manage Certificates，创建 `Developer ID Application` 证书。 -4. 确认登录钥匙串中同时存在证书和对应私钥： - -```bash -security find-identity -v -p codesigning -``` - -分发 DMG 和 ZIP 需要的是 `Developer ID Application`。只有分发签名 `.pkg` 安装包时才需要 `Developer ID Installer`。 - -将证书和私钥导出为加密的 `.p12` 文件，并保存在仓库之外的安全位置。不要把证书、私钥、密码、API Key 或公证配置提交到 Git。 - -## 4. 创建 Apple 公证凭据 - -CI/CD 推荐使用 App Store Connect API Key： - -1. 打开 App Store Connect，依次进入 Users and Access、Integrations、App Store Connect API。 -2. 创建一个能够代表当前 Team 提交公证任务、但权限尽可能小的 API Key。 -3. 下载只能获取一次的 `.p8` 私钥文件，同时记录 Key ID 和 Issuer ID。 - -如果只在本机发布，可以让 `notarytool` 把 Apple ID 凭据保存到钥匙串： - -```bash -xcrun notarytool store-credentials "meldwork-notary" \ - --apple-id "YOUR_APPLE_ID" \ - --team-id "YOUR_TEAM_ID" \ - --password "YOUR_APP_SPECIFIC_PASSWORD" -``` - -需要在 [Apple ID 账户页面](https://appleid.apple.com/) 创建 App 专用密码。这里不能使用 Apple ID 的普通登录密码。 - -## 5. 配置 electron-builder - -当前仓库已经使用 Bundle ID `com.rydersun.meldwork`，社区版许可证为 `AGPL-3.0-only`。公开发布配置必须保持 Hardened Runtime 开启，并在现有 `afterPack` Electron Fuses 加固完成后，由 electron-builder 执行签名和公证。 - -使用本机钥匙串证书时，electron-builder 可以自动发现有效的 `Developer ID Application` 身份。在 CI 中，需要把证书导出为加密的 `.p12`，并配置以下 Secrets： - -```text -CSC_LINK -CSC_KEY_PASSWORD -APPLE_API_KEY -APPLE_API_KEY_ID -APPLE_API_ISSUER -``` - -`CSC_LINK` 指向 `.p12` 证书或其安全编码内容，`CSC_KEY_PASSWORD` 是 `.p12` 密码。`APPLE_API_KEY` 必须指向 CI 运行环境中的 `.p8` 私钥文件。 - -如果不使用 App Store Connect API Key，也可以配置 Apple ID 方案： - -```text -APPLE_ID -APPLE_APP_SPECIFIC_PASSWORD -APPLE_TEAM_ID -``` - -如果使用本机钥匙串中的 `notarytool` Profile，设置 `APPLE_KEYCHAIN_PROFILE=meldwork-notary`。Profile 位于默认钥匙串时，通常不需要设置 `APPLE_KEYCHAIN`。 - -公开发布命令 `dist:public` 会依次执行以下保护： - -1. `scripts/public-release-preflight.cjs` 检查签名身份和完整的公证凭据。 -2. `electron-builder.public.cjs` 强制启用 `forceCodeSigning: true` 和 `mac.notarize: true`。 -3. `scripts/after-sign.cjs` 拒绝临时签名、缺失 Team ID、未开启 Hardened Runtime，或者 Bundle ID 不是 `com.rydersun.meldwork` 的产物。 - -不要增加任何明文凭据降级方案。缺少签名或公证凭据时，公开发布必须在打包前失败，不能生成可能被误发布的临时签名产物。 - -## 6. 构建并验证正式产物 - -安装锁定依赖并构建公开分发包： - -```bash -npm --prefix frontend ci -npm --prefix desktop ci -npm --prefix desktop run dist:public -``` - -`npm --prefix desktop run dist` 只用于本地打包验证，不是正式公开发布命令。 - -发布前检查实际生成的应用和 DMG： - -```bash -codesign --verify --deep --strict --verbose=2 \ - desktop/dist/mac-arm64/Meldwork.app - -spctl --assess --type execute --verbose=4 \ - desktop/dist/mac-arm64/Meldwork.app - -xcrun stapler validate desktop/dist/mac-arm64/Meldwork.app -xcrun stapler validate desktop/dist/Meldwork-0.1.0-arm64.dmg -``` - -必须在没有安装过 Meldwork、没有历史应用数据的全新 Apple 芯片 Mac 用户账户中安装 DMG，并通过正常双击启动。不能使用右键绕过、删除隔离属性或执行 `xattr` 的方式通过测试。只有 Gatekeeper 正常接受应用，才算满足公开发布门槛。 - -签名、公证和 Stapling 全部完成后，再生成最终校验值： - -```bash -shasum -a 256 \ - desktop/dist/Meldwork-0.1.0-arm64.dmg \ - desktop/dist/Meldwork-0.1.0-arm64.zip -``` - -发布到 GitHub Release 的 DMG、ZIP 和 `SHA256SUMS.txt` 必须来自同一个干净的 Git 标签和同一次正式构建。 - -## 7. 常见错误 - -- `CSSMERR_TP_NOT_TRUSTED`：证书链无效、证书已过期、缺少对应私钥，或者证书在当前钥匙串中不受信任。 -- `no identity found`：没有安装有效的 Developer ID 证书，或者 electron-builder 无法访问证书所在的钥匙串。 -- 公证拒绝二进制文件：使用 `notarytool` 查看详细日志，重点检查未签名的嵌套可执行文件、缺失 Hardened Runtime、无效 Entitlements 或额外打包的可执行内容。 -- `spctl` 拒绝已经签名的应用：通常是没有完成公证或 Stapling、公证票据无效，或者本地验证的应用并不是提交给 Apple 的同一份产物。 -- 签名版本启动后出现全新数据目录：Bundle ID 或产品身份可能在内测后发生了变化。应停止发布并先设计明确的数据迁移方案。 - -## 8. 当前项目状态 - -- Bundle ID 已固定为 `com.rydersun.meldwork`。 -- `dist:public` 已配置为缺少正式签名或公证凭据时安全失败。 -- 当前 Mac 上没有有效的 `Developer ID Application` 证书。 -- 当前检测到的 `www.dingtalkcs.com` 身份无效且与 Meldwork 无关，不能用于发布，也不应由项目脚本自动删除。 -- 在完成 Apple Developer Program 申请、证书安装和公证凭据配置之前，只能生成供本地验证使用的临时签名包。 diff --git a/docs/market-user-research.md b/docs/market-user-research.md deleted file mode 100644 index 1c6da34..0000000 --- a/docs/market-user-research.md +++ /dev/null @@ -1,337 +0,0 @@ -# Meldwork 市场与用户调研说明书 - -> 版本：General Agent + Knowledge 战略版 -> -> 日期：2026-08-02 -> -> 状态：战略工作稿；外部价格、竞品能力和法律结论在公开发布前需要刷新 - -## 0. 结论先行 - -### 0.1 值不值得继续做 - -**值得继续做，但不能继续把 Meldwork 定义为本地 Agent 聚合聊天器，也不应把产品重新锁死在 Coding Agent。** - -更合理的产品方向是： - -> **面向 General Agent 与用户已有知识来源的开放、本地优先工作系统。** - -用户真正需要的不是更多聊天入口，而是让一项工作在不同 Agent、知识来源和人之间接续时，仍然保留： - -- 被批准使用的上下文。 -- 原生 Session 和 Agent 能力。 -- 清晰的权限与数据出站边界。 -- 可继续使用的 Artifact。 -- 支持或反驳结果的 Evidence。 -- 人类最终采用、拒绝或修改的 Decision。 - -因此，Meldwork 的核心闭环应从： - -```text -Conversation -> More Agents -> More Messages -``` - -升级为： - -```text -Agent + Knowledge Source - -> Context Pack - -> Task / Run - -> Artifact / Evidence - -> Decision / Adoption -``` - -### 0.2 这不是“什么 Agent 都能接”的宽泛平台 - -General Agent 表示产品不按 Coding、Research、PM 或 Operations 把 Agent 人为分割成不同品类；它不表示所有 Agent 拥有相同能力，也不表示 Meldwork 可以无条件接入任何 Agent。 - -每个 Agent 和 Knowledge Connector 都必须声明： - -- 能做什么和不能做什么。 -- 支持哪些输入、Session 和工具。 -- 是否可读、可写、可联网和可取消。 -- 哪些运行事件、Artifact、Evidence 和费用可以观测。 -- 数据会流向哪里。 - -产品卖点应是“开放且可验证的连接”，不是“无限兼容”。 - -### 0.3 当前最有价值的新机会 - -当前仓库已经开始支持飞书、钉钉和 Obsidian 等知识来源。虽然现阶段只是经过验证的只读访问提示，而不是完整 RAG 或索引引擎，但它使 Meldwork 有机会形成比“多 Agent 控制面”更清晰的差异： - -> **把用户已经拥有的 Agent 和知识上下文带进同一个可追溯工作空间。** - -这条方向覆盖代码、研究、产品、咨询、规划、安全和运营等工作，不依赖某个 Agent 厂商，也不要求 Meldwork 自建模型。 - -### 0.4 投入判断 - -建议采用双层策略： - -| 层次 | 当前目标 | 决策 | -| --- | --- | --- | -| 开源项目 | 可安装、可理解、可完成真实任务、可贡献 | 立即投入 | -| 产品验证 | 证明 Context-grounded Outcome 是否产生重复价值 | 立即投入，但只做一个主协议 | -| 平台扩张 | Cloud、Channel、Workflow、Team | 由重复使用和回款触发 | - -不建议现在同时建设企业平台、云执行、多个 IM Channel、完整知识中台和大量 Connector。 - -## 1. 研究边界 - -### 1.1 已有证据 - -- `/Users/rydersun/Desktop/Meldwork Strategy` 中的市场、路线图和 BP 材料。 -- 当前仓库对本地 Agent、Session、Provider、Skill、图片和知识来源的实现。 -- 既有市场研究中关于 Agent 使用、AI 信任、控制面竞争和开源生态的公开资料。 - -### 1.2 尚未成立的事实 - -当前没有足够证据证明： - -- 用户会为跨厂商 Agent 工作层单独付费。 -- 多 Agent 在多数任务上稳定优于一个强 Agent。 -- 用户需要 Meldwork 自建知识索引，而不是让 Agent 读取已有来源。 -- 团队愿意把工作状态交给一个新的控制面。 -- 开放 Connector 会自动形成网络效应。 - -这些均应作为需要真实任务、留存和回款验证的假设。 - -## 2. 市场正在发生什么 - -### 2.1 Agent 正从工具变成可替换执行单元 - -Codex、Claude Code、Hermes、OpenClaw、Kimi、MiMo、Qwen 等产品正在同时扩展研究、文件、工具、浏览器、代码、自动化和渠道能力。Coding Agent 与 General Agent 的边界正在变模糊。 - -这意味着： - -1. 用户会长期同时使用多个能力不同的 Agent。 -2. 单个 Agent 的品牌和能力会频繁变化。 -3. 独立产品不能把 Agent 数量或聊天 UI 当作壁垒。 -4. 更稳定的价值位于上下文、工作状态、权限、Evidence 和 Adoption。 - -### 2.2 知识上下文仍然碎片化 - -用户的真实上下文散落在本地文件、Obsidian、飞书、钉钉、Notion、Confluence、Google Drive、SharePoint、GitHub 和各种聊天记录中。 - -现有 Agent 往往通过各自插件、MCP、CLI、粘贴或索引方案读取这些内容，导致： - -- 用户反复解释哪些来源可以用。 -- 不同 Agent 获得的上下文范围不一致。 -- 输出很难说明依据了哪些内容。 -- 权限和数据出站由多个工具分别管理。 -- 换 Agent 后，任务状态和决策链再次丢失。 - -Meldwork 不需要立即复制所有知识平台，而应先成为“本次任务允许使用哪些上下文”的本地控制层。 - -### 2.3 多 Agent 是按风险升级的能力 - -多数普通任务一个 Agent 足够。第二个 Agent 只有在以下情况下更可能产生净价值： - -- 错误成本高，需要独立 Reviewer。 -- 任务不确定，需要相互独立的方案。 -- 不同 Agent 具备明显互补的工具或知识访问能力。 -- 产物需要事实、约束或合规复核。 - -因此，产品默认行为应是一个 Agent 完成任务，并在风险、证据不足或用户主动选择时增加第二个 Agent。 - -### 2.4 控制面能力会商品化 - -GitHub Agent HQ、Cursor、Warp、OpenHands、Cline 和各家原生 Agent 都在增加并行运行、任务列表、团队协作和渠道入口。 - -Meldwork 不能只争夺“控制多个 Agent”这个功能，而应占据更具体的位置： - -- 跨厂商而非单厂商。 -- 本地控制而非强制云账户。 -- 连接用户已有 Agent 与知识来源。 -- 以 Artifact、Evidence 和 Decision 记录真实工作结果。 - -## 3. 市场位置 - -| 市场层 | 用户购买的结果 | Meldwork 的关系 | -| --- | --- | --- | -| Agent / 模型 | 推理、工具调用和执行能力 | 连接供给，不与其竞争 | -| IDE / Terminal | 在开发环境完成工作 | 不复制完整 IDE 或终端 | -| Knowledge Platform | 存储、搜索和协作文档 | 连接来源，不替代其内容系统 | -| Cloud Agent | 后台运行和远程交付 | 条件阶段 Connector | -| Agent Control Plane | 并行、状态、策略和审计 | 主要竞争层 | -| Work Channel | 在 GitHub、钉钉、飞书、Slack 等地派发工作 | 条件阶段入口 | - -建议品类： - -> **Open, local-first work system for agents and knowledge across vendors.** - -不建议定位为：AI IDE、通用聊天应用、知识库 SaaS、模型聚合器、无限自治集群或企业 IM。 - -## 4. 目标用户与 Jobs to Be Done - -### 4.1 首要用户：高频使用 Agent 的专业知识工作者 - -这类用户可能是产品经理、研究人员、顾问、开发者、安全人员、分析师或创业者。共同特征不是职业名称，而是： - -- 已使用两个或以上 Agent，或频繁在 Agent 与知识来源之间切换。 -- 处理有明确产物、来源和判断责任的工作。 -- 愿意理解工作目录、知识授权和 Provider 边界。 -- 不希望把全部工作状态迁移到单一厂商平台。 - -核心 Job： - -> 当一项工作重要到不能只依赖一个 Agent 或一段记忆时，我希望把被批准的知识上下文交给合适的 Agent，让另一个 Agent 独立复核，并保留可以追溯和继续使用的结果。 - -### 4.2 第二用户：5-50 人 AI-native 团队 - -核心 Job： - -> 当团队成员使用不同 Agent 和知识来源时，我希望复用同一套任务、上下文、权限、Evidence 和交付规则，而不是依赖每个人的私人 Prompt 和工具习惯。 - -只有个人闭环形成重复使用后，才验证共享模板、策略、审计和预算。 - -### 4.3 未来用户：高责任团队 - -研究、咨询、安全、合规、架构和重大决策场景更需要证据与复核，但也要求更强的隔离、审计和支持。当前只适合作为设计伙伴，不应宣传为生产级企业方案。 - -### 4.4 暂不优先 - -- 只需要单次聊天或低价模型切换的消费者。 -- 期待无人值守自动赚钱的泛自动化用户。 -- 需要完整 IDE、企业知识中台或大规模云 Runtime 的客户。 -- 要求 Meldwork 自动读取所有个人和企业知识而不做显式授权的用户。 - -## 5. 痛点优先级 - -| 优先级 | 痛点 | 用户损失 | 产品机会 | -| --- | --- | --- | --- | -| P0 | Agent、Session、文件和知识来源割裂 | 重复解释、遗漏约束、无法继续 | Workspace + Context Pack | -| P0 | 不知道结果依据了什么 | 错误进入决策和交付 | Source Usage + Evidence | -| P0 | 多 Agent 输出难以比较和采用 | 手工整理、责任不清 | Artifact + Decision | -| P0 | 权限与数据出站不透明 | 隐私、安全和误写入风险 | Local Control Plane | -| P1 | Agent 和知识连接随版本失效 | 激活失败、维护成本高 | Connector Contract + Compatibility | -| P1 | 有效工作方式无法复用 | 每次重新写 Prompt | Typed Task / Workflow Template | -| P2 | 本地与 Cloud Agent 无法连续交接 | 长任务中断 | Local / Cloud Handoff | -| P2 | 工作不能从现有渠道进入 | 额外切换入口 | Channel Connector | - -## 6. 核心竞争力 - -### 6.1 Context Portability - -用 Context Pack 明确记录一项任务实际使用的文件、图片、Skill、知识来源、权限和出站范围，使工作换 Agent 后仍能继续。 - -### 6.2 Session Fidelity - -尽可能保留不同 Agent 的原生 Session、能力和增量上下文，而不是把所有连接降级为无状态模型 API。 - -### 6.3 Outcome & Evidence Graph - -建立 Task、Run、Artifact、Evidence、Source 和 Decision 的关系，使用户可以回答：谁在什么条件下，基于什么上下文，产生了什么结果，最后为何被采用。 - -### 6.4 Local Control Plane - -工作状态与编排记录默认留在本机；Agent 和 Provider 是否联网、访问哪些知识来源、获得什么写入能力，都应在任务层可见。 - -### 6.5 Open Connector Ecosystem - -对 Agent 和 Knowledge Source 使用明确的能力 Manifest、事件 Contract、兼容矩阵和贡献流程。生态价值来自可复现适配和真实失败数据，而不是 Logo 数量。 - -### 6.6 Routing Intelligence - -只有在用户单独同意后，才贡献不含 Prompt、原文和 Artifact 的最小派生数据，例如任务类型、Connector 版本、结果评分、时间区间和采用标签。若授权样本不足，路由建议应保持为本地私有能力，不宣传成网络效应。 - -## 7. 首发验证协议 - -Meldwork 需要保持 General Agent 定位，但首轮不能验证所有场景。建议用一个协议覆盖多个职业： - -```text -Primary Agent produces an Artifact - -> Reviewer Agent checks constraints and Evidence - -> Human adopts, rejects or requests revision -``` - -先收集 10-15 个探索任务，再从以下模板中选择痛点最稳定的一类作为主样本： - -- 研究与决策核验。 -- 方案与交付物评审。 -- 代码与技术审查。 - -首轮不把三类任务混合成一个质量结论，只共享产品协议和数据模型。 - -## 8. 12 周验证计划 - -### 8.1 需求验证 - -- 访谈至少 20 名已使用 Agent 的专业用户，覆盖研究/产品与技术工作。 -- 只讨论过去两周的真实任务，不询问抽象偏好。 -- 记录上下文搬运、来源确认、手工复核、失败损失和当前工具预算。 -- 第 6 周前固定最先完成真实 Task 的 15 名用户 cohort。 - -### 8.2 产品验证 - -- 至少完成 30 个真实 Task，其中前 10 个用于发现流程，后 20 个按冻结模板验证。 -- 每个任务记录 Context Pack、Primary Artifact、Reviewer Finding、Evidence 和 Decision。 -- 至少 8/15 固定用户在首次任务后 30 天内再次完成一个真实 Task。 -- 相对用户当前手工工作方式，上下文搬运和结果整理主动时间中位数下降至少 25%。 -- Reviewer 新增 Finding 需要记录被采用、修复或拒绝及其原因。 - -### 8.3 生态与商业信号 - -- 至少 1 个外部 Connector 或 Task Template 贡献。 -- 至少 3 个团队愿意使用同一标准化试点边界；实际回款与定制服务分开记录。 -- Star、曝光、候补名单和 LOI 仅作为辅助信号。 - -## 9. Go / Pivot / Stop - -### Go - -- 首次任务可以独立完成。 -- 15 名固定用户中至少 8 名在 30 天内重复。 -- 至少 20 个 Task 形成 Artifact、Evidence 和 Decision。 -- 用户主动协调时间明显下降，Reviewer 产生可采用的新价值。 -- 出现外部贡献或标准化付费信号。 - -### Pivot - -- 用户需要单 Agent + Knowledge + Outcome，但多 Agent 价值弱：聚焦本地 Agent 工作台和 Evidence，不强推协作。 -- 知识访问是主要价值：强化 Context Pack 和 Source Connector，延后 Cloud Agent。 -- 技术用户重复使用而非技术用户不成立：保留 General Agent 架构，但收窄首发市场。 - -### Stop / 收缩 - -- 用户只喜欢统一界面，不会再次完成真实任务。 -- 维护 Connector 的时间长期超过用户价值开发。 -- 多 Agent 增加的成本和整合负担大于新增价值。 -- 只有定制开发和咨询收入，没有标准化需求。 - -## 10. 开源与商业化 - -开源仍是当前最合理的信任和分发方式，但不能把“开源”当作价值验证本身。 - -收入选项按证据逐步开放： - -| 阶段 | 可售价值 | 进入条件 | -| --- | --- | --- | -| Community | 本地核心、基础 Agent/Knowledge 连接、任务协议 | 公开边界和许可证明确 | -| Pro | 高级 Context Pack、比较、导出、模板和更新便利 | 个人用户持续重复使用 | -| Team | 共享模板、策略、预算、Evidence 和兼容报告 | 多个团队出现同类需求 | -| Enterprise | 私有部署、签名 Connector、审计、离线更新和 SLA | 3 个以上标准化付费客户 | - -不默认对模型 Token 加价，不提前承诺无限定制 Connector。 - -## 11. 最终判断 - -Meldwork 最值得做的不是“所有 Agent 的客户端”，而是： - -> **一个让 Agent、知识上下文和可验证结果持续接续的本地工作系统。** - -这条路径比 Coding Agent 聚合更宽，但比通用 Agent 平台更具体。它允许代码、研究、产品和运营共享同一工作协议，同时用 Context Pack、Artifact、Evidence 和 Decision 保持产品边界。 - -## 12. 参考来源 - -以下来源延续上一版调研，正式发布前需重新核验价格、产品状态和日期： - -- [Stack Overflow 2025 AI Survey](https://survey.stackoverflow.co/2025/ai) -- [METR: Early-2025 AI and experienced developers](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) -- [GitHub Agent HQ](https://github.blog/news-insights/product-news/welcome-home-agents/) -- [Cursor Cloud Agents](https://cursor.com/blog/cloud-agents) -- [Warp Oz](https://www.warp.dev/newsroom/2026/2/10/warp-launches-oz-the-orchestration-platform-for-cloud-coding-agents) -- [OpenHands](https://www.openhands.dev/) -- [OpenAI Codex](https://developers.openai.com/codex/) -- [Cline](https://github.com/cline/cline) -- [Factory](https://www.factory.ai/) -- [Devin](https://devin.ai/) diff --git a/docs/permissions.md b/docs/permissions.md deleted file mode 100644 index eb6b114..0000000 --- a/docs/permissions.md +++ /dev/null @@ -1,79 +0,0 @@ -# Permissions - -## Identity Model - -Meldwork has no login, account, role, claim, tenant, server session, or database authorization layer. The local OS user who launches the application is the only human actor. - -Authorization is process-bound: - -- Electron main is the trusted enforcement boundary. -- The renderer is an untrusted UI client. -- Preload exposes a fixed IPC surface only to the local `file:` document. -- Every privileged IPC handler verifies the current main frame and exact bundled frontend path. - -## Resource Matrix - -| Resource / operation | Local user through trusted renderer | Other document/frame | Agent child process | Enforcement | -| --- | --- | --- | --- | --- | -| Read sanitized workspace snapshot | Allowed | Denied | No IPC access | `requireDesktopRenderer`; `LocalWorkspace.snapshot` removes executable paths | -| Create/update/delete Meldwork conversations and messages | Allowed | Denied | No direct state-file API | Named IPC handlers plus `LocalWorkspace` validation; deletion is blocked while running and must purge app-owned Run Ledger records before conversation state | -| Receive active/terminal run state | Sanitized events and compact message traces only | Denied | N/A | Main allowlists run/conversation IDs, Agent kinds, status, conclusion deltas, summarized reasoning/plan/tool events, source message IDs, and bounded result metadata; direct details render inline and group details render in the right panel | -| Read or mutate the private Run Ledger | No direct API | Denied | No direct API | Electron main owns `RunLedger`; renderer receives live allowlisted events and durable compact message capsules, never the ledger file or arbitrary records | -| Create operating-system notifications | Not directly allowed | Denied | N/A | Main creates notifications only from trusted terminal run events; renderer cannot supply notification content | -| Select a working directory | Allowed through OS dialog | Denied | Receives selected path only at invocation | Main-owned `dialog.showOpenDialog` | -| List/select local Skills | Sanitized coordinates and display names for installed target Agents | Denied | Receives only its validated selections in prompt/native arguments | Installed-Agent gate; main-owned `LocalSkillCatalog`; per-target revalidation; no renderer-supplied path | -| Probe/select knowledge sources | Sanitized readiness plus the user-selected Obsidian Vault path | Denied | Receives only target-scoped, validated read-only access hints | Code-defined catalog; main-owned probes/dialog; per-run revalidation; planned OAuth sources cannot be selected | -| Import/preview/discard images | Allowed through picker, exact paste payload, attachment ID, and discard list | Denied | Receives a main-resolved path only for an authorized invocation | Main-owned dialog and `AttachmentStore`; type/size/dimension/checksum validation; referenced files cannot be discarded | -| Enable workspace writes | Explicit per-conversation opt-in | Denied | Enforced adapters receive write mode only when enabled; Hermes/OpenClaw remain Agent-managed | Stored `allowWrite`; per-CLI permission flags where supported | -| Detect Agents | Allowed | Denied | N/A | Code-defined command catalog; executable paths stay in main | -| Install an Agent | Explicit confirmation; one active task | Denied | Installer child runs fixed recipe | Allowlisted Agent, command, package/URL, and OS checks | -| Read Provider status | Metadata only | Denied | N/A | `ProviderStore.status` excludes API key | -| Save/remove Provider key | Allowed through Provider form | Denied | Compatible Agent receives scoped environment at invocation | Exact four-field payload, URL validation, `safeStorage` | -| Open external URL | Credential-free HTTPS in OS browser | In-window navigation denied | N/A | `isAllowedExternalUrl`; `setWindowOpenHandler`; `will-navigate` | -| Camera, microphone, Bluetooth, webview, generic Electron permissions | Denied | Denied | N/A | BrowserWindow settings and permission handlers | - -## Renderer Boundary - -`desktop/src/preload.cjs` exposes only: - -- `localWorkspace`: get/refresh/create/update/delete/send/directory selection, a stop request bound to the current `(groupId, runId)`, plus sanitized change, run-event, run-finished, and notification-open events. -- `agentInstaller`: catalog/Skill listing/state/start/cancel/sidebar visibility/change events. Skill listing accepts one Agent kind and returns sanitized records only. -- `localAttachments`: `pickImages`, exact-payload `importImage`, ID-only `preview`, and ID-list `discard`. It exposes no filesystem read, path resolution, or arbitrary file picker method. -- `localAgentProvider`: non-probing status, explicit encryption probe, save, and delete. -- `localKnowledgeBase`: source status, code-defined external setup guides, and a main-owned Obsidian Vault directory picker. - -Node integration, webviews, insecure content, and renderer permission requests are disabled. The packaged Electron fuses disable `runAsNode`, Node option injection, CLI inspect arguments, and loading app code outside `app.asar`. - -## Filesystem Permissions - -- Meldwork state is written only by main. -- `roundrelay-run-ledger.json` is written atomically by main as a private `0600` file; parent directories created by the private writer use `0700`. It retains at most 64 bounded sanitized runs and is purged before its conversation is removed. -- Provider and managed OpenClaw secret-bearing files use atomic writes and mode `0600`; their directories use mode `0700` where created by those modules. -- Imported PNG/JPEG copies live under the Electron user-data attachment directory. The root/entry directories use mode `0700`, files use `0600`, metadata carries a SHA-256 checksum, and symlink/path escape or tampering fails closed. -- Conversation data and bounded sanitized Run Ledger records are private local JSON but are not application-encrypted. The ledger assumes one Electron main-process writer and is a recovery/audit aid, not an immutable forensic log. -- Raw chain-of-thought, commands, unrestricted stdout/stderr, arbitrary tool payloads, Agent executable paths, native session IDs, native session storage paths, attachment paths, Skill paths, preview payloads, and credential material are stripped from renderer snapshots, lifecycle events, compact trace capsules, and Run Ledger records. User-selected conversation workdirs are intentionally returned for display and editing. -- Main scans known per-Agent Skill roots and reads only bounded Skill manifest prefixes for catalog metadata. The renderer cannot request an arbitrary directory or file. -- `KnowledgeBaseStore` persists only the normalized user-selected Obsidian Vault path. Feishu and DingTalk authentication remain in their local CLI-owned stores; Meldwork does not receive or persist their tokens. -- Knowledge-source selection accepts only code-defined source kinds. Main resolves an allowlisted CLI command name or the selected absolute Vault path and scopes the hint to explicit target Agents. -- Agent filesystem access is scoped to the selected working directory by Meldwork arguments/configuration where the upstream CLI supports it. - -## Process And Network Permissions - -- Only supported Agent kinds can be invoked. -- Skill selections are limited to four, must still exist in the selected Agent's current catalog, and are routed only to that Agent. Hermes receives validated slugs through its native `--skills` flags; no renderer value becomes an arbitrary CLI argument. -- Knowledge-source selections are limited to four, must be currently readable, and are routed only to their selected target Agents. Feishu/DingTalk command names come from main-side detection, not renderer input; Obsidian paths come from the main-owned directory picker. -- Image references are limited to four and are resolved inside main. Codex and OpenCode accept up to four; Hermes accepts one; unsupported or unequal multi-Agent context is rejected before any child process starts. -- Child environments begin with a system-variable allowlist, then add only the selected Agent's native credentials and optional configured Provider values. -- Installer environments remove variables whose names look like keys, tokens, secrets, passwords, credentials, cookies, authorization, or prompts. -- Provider URLs require HTTPS, except loopback HTTP for local development. -- Installer scripts require HTTPS and an allowlisted host; npm packages are selected from a fixed map. -- Once `before-quit` starts, every trusted IPC handler rejects new work with `DESKTOP_CLIENT_SHUTTING_DOWN` until active runs and installer work have settled. -- A renderer stop request must name the currently visible `runId`; stale or malformed run identifiers cannot abort a newer run. A successful response acknowledges cancellation, while the conversation remains locked until bounded child/output cleanup settles. - -## Explicit Limitations - -- There is no per-user permission separation inside the app because there is no account model. -- An Agent process runs with the operating-system permissions of the local user. Meldwork permission flags reduce capability but are not an OS sandbox. -- Imported images are private local copies but are not application-encrypted; when sent, their contents may reach the selected Agent's configured model Provider. -- Knowledge-source content is not copied into Meldwork by the selection flow, but an invoked Agent may read selected documents or Vault files and send relevant content to its configured Provider. Current read-only behavior is an explicit task instruction plus source capability constraints, not an OS sandbox or a universal upstream-tool guarantee. -- Installer approval authorizes an external system modification. Package/script integrity is not currently pinned. diff --git a/docs/product-bp.md b/docs/product-bp.md deleted file mode 100644 index 2daf947..0000000 --- a/docs/product-bp.md +++ /dev/null @@ -1,286 +0,0 @@ -# Meldwork 产品 BP - -> 版本：General Agent + Knowledge / Open-source-first -> -> 日期：2026-08-02 -> -> 用途：项目介绍、开源发布、设计伙伴沟通和后续商业化讨论 - -## 1. 一句话 - -**Meldwork 把用户已经在用的 Agent 和知识来源带进一个本地优先、可追溯的工作空间，让工作可以跨 Agent 接续，并留下可采用的产物与证据。** - -English: - -> **Meldwork brings the agents and knowledge you already use into one local, accountable workspace.** - -## 2. 产品定位 - -### 品类 - -> **An open, local-first work system for agents and knowledge across vendors.** -> -> **面向跨厂商 Agent 与知识来源的开放、本地优先工作系统。** - -### 当前 MVP Slogan - -> **Agents change. Work continues.** -> -> **Agent 可切换，工作不断线。** - -当前产品已经能够连接已支持的本地 Agent、维持工作空间和兼容条件下的原生 Session，并让用户显式选择部分知识来源。这条 Slogan 仍与现阶段价值一致。 - -### 目标产品承诺 - -> **Different agents. Context stays. Work can be verified.** -> -> **不同 Agent，上下文不断，结果有据可验。** - -只有当 Context Pack、Artifact、Evidence 和 Decision 形成真实闭环后，才应把这条表达用于主宣传。 - -### 品牌逻辑 - -Meld 表示不同 Agent 的工作可以接续，但不要求答案被强行融合或达成共识。Work 表示产品处理的是真实任务、产物和决定，而不是闲聊。 - -品牌标志中的连续线代表工作延续，独立的珊瑚色端点代表结果被检查并由人类采用或拒绝。品牌承诺应落在“连续性 + 可验证结果”，而不是 Agent 数量。 - -## 3. 用户问题 - -Agent 能力越来越强，但用户的工作仍然被拆散： - -- 不同 Agent 拥有独立 Session、工具、Provider 和权限。 -- 上下文散落在本地文件、Obsidian、飞书、钉钉、Notion、Confluence、GitHub 和聊天记录中。 -- 用户不断复制任务、约束和前序结果。 -- 不同 Agent 的输出难以比较，流畅文本容易被误认为已完成。 -- 用户不知道结果具体依据了哪些来源，也无法稳定复验。 -- 切换 Agent 后，Artifact、Evidence 和最终 Decision 很难继续。 - -市场并不缺更多 Agent，缺少的是用户能够掌控的跨 Agent 工作与上下文层。 - -## 4. 解决方案 - -Meldwork 的目标闭环： - -```text -Agent + Knowledge Source - -> Context Pack - -> Task / Run - -> Artifact / Evidence - -> Human Decision / Adoption -``` - -### 4.1 当前 MVP 已实现 - -- 本地 Electron 桌面工作空间。 -- 已支持本地 Agent CLI 的发现、就绪状态和受控运行。 -- 直接与群组会话，以及兼容条件下的原生 Session 延续。 -- 有界自动讨论、取消、失败状态和本地通知。 -- Agent-specific Skill 与受限图片上下文。 -- Provider 配置和操作系统安全存储。 -- 飞书、钉钉和 Obsidian 的连接状态与只读知识来源选择。 - -当前知识来源能力是显式访问提示，不是由 Meldwork 执行的统一搜索、索引或 RAG。Notion、Confluence、Google Drive 和 SharePoint 仍是规划入口。 - -### 4.2 下一阶段核心 - -- Knowledge Source 与 Context Pack。 -- Task、Run、Artifact、Evidence、Decision。 -- Primary Agent 产出 + Reviewer Agent 独立复核。 -- Agent / Knowledge Connector Contract。 -- Evidence Bundle、导出和真实 Adoption 记录。 - -### 4.3 后续条件能力 - -- Local / Cloud Agent Handoff。 -- GitHub、钉钉、飞书或其他任务型 Channel。 -- Typed Workflow、预算和 Human Gate。 -- Team 策略、审计和可选同步。 - -这些属于路线图，不是当前功能承诺。 - -## 5. 首要用户 - -### ICP 1：Agent 重度专业用户 - -产品经理、研究人员、顾问、开发者、安全人员、分析师和创业者中，已经使用多个 Agent 并需要对产物负责的人。 - -他们购买的不是“更多 Agent”，而是： - -- 少复制一次上下文。 -- 少遗漏一个关键来源或约束。 -- 多一个独立且可追溯的复核视角。 -- 把结果直接变成可以继续使用的 Artifact。 - -### ICP 2：5-50 人 AI-native 团队 - -团队成员使用不同 Agent 和知识来源，希望复用相同任务、权限、Evidence 和交付规则。只有个人重复使用成立后，才进入共享模板、策略、预算和审计验证。 - -### ICP 3：未来高责任团队 - -研究、咨询、安全、合规和重大决策团队对 Evidence 和 Decision 链更敏感，但需要更强隔离、审计和支持。当前只作为设计伙伴，不宣传为生产级企业能力。 - -## 6. 首发场景 - -Meldwork 保持 General Agent 定位，但首轮只实现一个通用协议： - -```text -Primary Agent produces an Artifact - -> Reviewer Agent checks constraints and Evidence - -> Human adopts, rejects or requests revision -``` - -候选模板： - -- 研究与决策核验。 -- 方案、PRD、报告或交付物评审。 -- 代码与技术审查。 - -首轮根据真实任务频率选择一个主模板，不同时为三个领域开发独立产品。 - -## 7. Why now - -1. Agent 正从 Coding、Research 或 Chat 工具演化为跨领域执行单元。 -2. 用户会长期同时使用全球与中国、开源与专有、本地与云端 Agent。 -3. 知识与工作上下文仍然分散在不同平台，换 Agent 就容易失去连续性。 -4. 上游平台会快速商品化并行 Agent，但天然优先优化自家生态。 -5. AI 使用增长与准确性、隐私、成本和责任问题同步增长。 -6. 本地优先和开源可以降低新控制层的信任门槛。 - -## 8. 核心竞争力 - -### 8.1 Cross-vendor Neutrality - -不绑定某个模型、IDE、知识平台或 Cloud。用户保留已有 Agent、账号、Provider 和知识来源。 - -### 8.2 Context Portability - -Context Pack 记录本次任务实际允许使用的文件、图片、Skill、知识来源、敏感等级和出站范围，使工作换 Agent 后仍可继续。 - -### 8.3 Session Fidelity - -连接不是简单转发 Prompt，而是尽可能保留原生 Session、工具、权限和增量上下文。 - -### 8.4 Outcome & Evidence Graph - -把 Task、Run、Artifact、Evidence、Source 和 Decision 关联起来，使结果可以比较、复验、导出和继续使用。 - -### 8.5 Local Control Plane - -工作状态默认保留在本机，Agent、Provider、知识访问和写入权限在任务层显式可见。Local-first 不等于所有模型离线。 - -### 8.6 Open Connector Ecosystem - -公开 Agent 与 Knowledge Connector 的能力 Manifest、兼容矩阵、事件 Contract 和贡献路径。生态价值来自可复现适配与真实失败数据，不是 Logo 数量。 - -## 9. 竞争关系 - -| 竞品类型 | 他们的优势 | Meldwork 的回答 | -| --- | --- | --- | -| 单厂商 Agent | 模型、工具和原生体验强 | 连接用户已有的不同 Agent | -| AI IDE / Terminal | 强入口和编辑执行体验 | 不复制 IDE，聚焦跨 Agent 工作状态 | -| Knowledge Platform | 内容、搜索和组织协作成熟 | 不替代内容平台，只管理任务上下文和来源关系 | -| Cloud Agent Control Plane | 后台执行、并行和企业治理强 | 先做本地控制与可验证 Handoff | -| 开放 Agent Platform | Runtime、协议和生态广 | 以易安装、知识接入、Session 和 Outcome 切入 | - -最大风险是上游平台覆盖多 Agent 控制面。因此 Meldwork 必须持续保持跨厂商、可迁移和知识平台中立。 - -## 10. Go-to-Market - -### 10.1 开源发布 - -1. 提供真实能力矩阵、安装说明、数据边界和故障排查。 -2. 用一个真实任务演示“知识上下文 -> Primary Artifact -> Reviewer Finding -> Human Decision”。 -3. 持续发布 Connector 兼容报告和失败复盘。 -4. 提供 Task Template、Connector 和评测任务的贡献入口。 -5. 国内外使用同一产品叙事，但只选择少量渠道持续经营。 - -### 10.2 内容策略 - -内容必须展示真实结果： - -- 同一份知识上下文交给两个 Agent，差异在哪里。 -- Reviewer 找到了什么，用户最终采用了什么。 -- 哪些知识来源被允许使用，哪些数据仍会出网。 -- 一次 Agent 或 Knowledge Connector 失效如何被诊断。 -- 为什么某项任务只需要一个 Agent。 - -不展示“十个头像轮流说话”或没有 Artifact 的自动讨论 Demo。 - -### 10.3 90 天目标 - -- 15 名固定外部用户完成真实 Task。 -- 同一批至少 8 名在首次任务后 30 天内重复。 -- 至少 20 个 Task 形成 Artifact、Evidence 和 Decision。 -- 至少 1 个外部 Connector 或 Task Template 贡献。 -- 相对手工跨 Agent，上下文搬运和整理主动时间中位数下降至少 25%。 -- 至少 3 个团队对同一标准化试点表达真实采购意愿，回款和定制收入分开记录。 - -## 11. 商业模式 - -### Open Core + BYO Agent / BYO Knowledge - -| 层级 | 可售价值 | 进入条件 | -| --- | --- | --- | -| Community | 本地核心、基础 Agent/Knowledge 连接、任务协议 | 公开边界和许可证明确 | -| Pro | 高级 Context Pack、比较、导出、模板和更新便利 | 个人用户持续重复使用 | -| Team | 共享策略、Evidence、预算、兼容报告和可选同步 | 多个团队出现同类问题 | -| Enterprise | 私有部署、签名 Connector、审计、离线更新和 SLA | 至少 3 个标准化付费客户 | - -不默认对模型 Token 加价。用户已经为 Agent、模型或知识平台付费，Meldwork 应对工作连续性、验证、兼容和治理收费。 - -## 12. 投入顺序 - -1. 新用户激活、安装和真实能力边界。 -2. Context Pack 与 Task Outcome 闭环。 -3. Agent / Knowledge Connector Contract 和兼容测试。 -4. Evidence、导出和评测。 -5. 一个 Cloud Handoff 或 Channel。 -6. Workflow、预算和 Team。 - -不优先投入：自建模型、重型云平台、完整知识中台、销售团队、全量 Agent 适配和复杂多租户。 - -## 13. 关键质疑 - -### “只是 Wrapper。” - -MVP 阶段部分成立。只有 Context Pack、Session Fidelity、Connector Contract、Outcome & Evidence Graph 和兼容数据形成闭环后，才具备独立产品层价值。 - -### “为什么不直接使用一个强 Agent？” - -多数任务应该只用一个 Agent。Meldwork 的价值首先是工作和上下文连续性；第二个 Agent 只在风险、证据不足或能力互补时加入。 - -### “为什么不直接使用知识平台自己的 AI？” - -知识平台优先优化自己的内容和 Agent。Meldwork 服务用户跨多个 Agent、文件和知识平台的工作，并保留本地任务与 Decision 记录。 - -### “General Agent 会不会过于宽泛？” - -如果产品按职业建立大量模式，会失去焦点。Meldwork 用统一 Task、Context、Artifact、Evidence 和 Decision 协议保持边界，并只验证一个首发模板。 - -### “开源会被复制？” - -代码可以复制。长期兼容数据、真实任务评测、Connector 社区、用户信任和可复用工作协议更难复制。如果这些没有形成，项目就不应自称拥有平台护城河。 - -## 14. 成功定义 - -### 开源成功 - -别人能安装、完成真实任务、理解数据边界、复现问题并提交有效贡献。 - -### 产品成功 - -同一批用户在 30 天内重复完成有 Context Pack、Artifact、Evidence 和 Decision 的 Task。 - -### 商业成功 - -至少 3 个团队为同一标准化能力付费，且支持和兼容成本可以由小团队承受。 - -### 应收缩 - -若用户只喜欢统一窗口、不重复使用，或多 Agent 价值不成立，则保留单 Agent + Knowledge + Outcome 的个人开源工具，不继续建设平台。 - -## 15. 最终叙事 - -> **Agents will change. Knowledge will live in different places. Work still needs continuity and proof.** - -Meldwork 不试图成为另一个万能 Agent，也不取代用户的知识平台。它要成为 Agent 和知识来源之间的本地工作层，让任务能够接续、结果能够复验、决定能够留下。 diff --git a/docs/product-iteration-plan.md b/docs/product-iteration-plan.md deleted file mode 100644 index e2226db..0000000 --- a/docs/product-iteration-plan.md +++ /dev/null @@ -1,350 +0,0 @@ -# Meldwork 产品迭代规划说明书 - -> 版本：General Agent + Knowledge + Outcome -> -> 日期：2026-08-02 -> -> 适用范围：产品、工程、开源、内容和用户验证 - -## 0. 路线结论 - -Meldwork 后续不应继续沿着“增加 Agent 数量”和“强化群聊效果”迭代，也不应重新收窄为 Coding Agent 控制台。 - -建议主线是： - -```text -Agent / Knowledge Source - -> Context Pack - -> Task / Run - -> Artifact / Evidence - -> Decision / Adoption - -> Reusable Workflow / Connector -``` - -产品要解决的不是“让更多 Agent 同时说话”，而是让一项工作在 Agent、知识来源和人之间流转时，不丢失上下文、权限边界、产物和验证记录。 - -阶段性取舍： - -1. 保持 General Agent 定位，但只验证一个通用工作协议。 -2. 默认使用一个 Agent，只有高风险、低确定性或需要独立观点时才增加 Reviewer Agent。 -3. 先完成本地 Task 和 Outcome 闭环，再决定 Cloud、Channel、Team 是否值得投入。 -4. 知识源先做显式授权和可追溯上下文，不提前建设重型 RAG、向量数据库或企业知识中台。 - -## 1. 当前事实基线 - -### 1.1 已具备 - -- Electron 本地优先桌面应用。 -- 已支持本地 Agent CLI 的发现、就绪状态和受控调用。 -- 直接会话、群组会话和兼容条件下的原生 Agent Session 延续。 -- 有界自动讨论、运行状态、失败状态和停止能力。 -- Agent-specific Skill 与受限图片上下文。 -- Provider 配置、操作系统安全存储和窄 Preload API。 -- 飞书文档、钉钉文档和 Obsidian 的本地连接状态与只读任务上下文选择。 -- Notion、Confluence、Google Drive 和 SharePoint 的规划入口，但尚未提供可用 Connector。 - -### 1.2 知识源能力的真实边界 - -当前能力是把用户明确选择、经过主进程验证的知识源访问方式作为只读提示交给目标 Agent： - -- 飞书和钉钉通过本机已配置 CLI 连接。 -- Obsidian 通过用户选择的本地 Vault 目录连接。 -- Agent 被要求在相关时使用知识源、说明所用来源并避免修改源内容。 - -当前尚未实现： - -- Meldwork 自己检索、索引或缓存知识库内容。 -- 统一的引用片段、内容快照、版本哈希或权限快照。 -- 确定性 RAG、跨知识库搜索排序或引用完整性校验。 -- Notion、Confluence、Google Drive 和 SharePoint 的真实连接与授权。 - -因此近期对外应使用“Knowledge Sources / 知识来源”和“显式上下文访问”，不应宣传成完整知识库引擎。 - -### 1.3 最大结构缺口 - -当前持久化中心仍然是 Conversation。它能回答 Agent 说了什么，但不能稳定回答： - -- 用户真正要完成的 Task 是什么。 -- 哪些知识来源和上下文被允许用于这次任务。 -- 哪次 Run 产生了哪个 Artifact。 -- 哪些 Evidence 支持或反驳结果。 -- 用户最终采用、拒绝或修改了什么。 - -## 2. 目标产品模型 - -### 2.1 Workspace - -本地信任与工作边界，包含工作目录、Agent、知识来源、Provider、权限默认值和本地数据策略。 - -### 2.2 Knowledge Source - -可被任务显式授权的输入来源，例如本地 Vault、文档 CLI、未来的 OAuth Connector 或用户选定文件。 - -每个 Knowledge Source 必须声明： - -- 访问方式与就绪状态。 -- 可读、可写和网络边界。 -- 数据所在位置或服务区域的可见说明。 -- 最后验证时间和已知限制。 - -### 2.3 Context Pack - -一次 Task 实际使用的上下文集合，而不是整个知识库的永久镜像。至少记录： - -- 用户输入、选定文件、图片和 Skill。 -- 被授权的 Knowledge Source。 -- 目标 Agent 和可见范围。 -- 创建时间、版本和可复验引用。 -- 敏感等级与允许出站范围。 - -Knowledge Source 是潜在输入，Context Pack 是本次任务被批准使用的输入。两者都不等于 Evidence。 - -### 2.4 Task - -一个有目标、有约束、有验收标准的工作单元。Task 至少包含：目标、背景、Context Pack、预期 Artifact、验收标准、风险级别、预算和是否允许多 Agent。 - -建议状态： - -```text -Draft -> Ready -> Running -> Needs review -> Adopted / Rejected / Blocked - -> Reopened / Rolled back -``` - -### 2.5 Run - -一次具体执行，记录 Agent、Connector 版本、Provider/模型标识、原生 Session 引用、权限模式、输入快照、状态、耗时和失败原因。 - -### 2.6 Artifact - -用户可以继续使用的产物：文档、研究结论、方案、代码变更、清单、结构化数据、图片、链接或导出包。 - -### 2.7 Evidence - -支持或反驳 Artifact 的证据：来源引用、文件位置、测试、命令结果、差异、截图、Reviewer Finding 和人类判断。 - -Evidence 必须区分： - -- Declared：Agent 自称已经验证。 -- Observed：Meldwork 捕获到结果或引用。 -- Reproduced：用户或另一个 Agent 成功复验。 -- Human accepted：人类确认该证据足以支持决策。 - -### 2.8 Decision 与 Adoption - -Acceptance 不能只是点击“接受”。需要记录： - -- 接受、拒绝、要求修改或选择另一个方案。 -- Artifact 被 Apply、Commit、Export、发送或用于哪项后续决定。 -- 采用后的测试、复核或结果反馈。 - -只有 Artifact 被实际使用，并完成与任务验收标准匹配的复验，才计入产品北极星。 - -## 3. 首发工作协议 - -首发不按 Coding、Research 或 PM 分裂三套产品，而是实现一个可复用协议： - -```text -Create Task - -> Select Context Pack - -> Primary Agent produces Artifact - -> Reviewer Agent checks Artifact and Evidence - -> Human adopts, rejects or requests revision -``` - -可以用三类模板验证，但首轮只能选择一个作为主样本： - -1. 研究与决策核验：基于文档来源形成结论，再由另一个 Agent 检查证据和遗漏。 -2. 方案与交付物评审：主 Agent 生成 PRD、方案、报告或演示结构，Reviewer 检查约束、冲突和可执行性。 -3. 代码与技术审查：实施 Agent 产出变更，Reviewer 检查缺陷、测试和风险。 - -这三类任务共享相同对象和指标。产品不为每个领域建立独立聊天模式。 - -## 4. Outcome Roadmap - -### Phase 0：可信激活，0-4 周 - -**目标结果：** 新用户能理解边界，并在 10 分钟内用一个 Agent 完成第一项真实工作。 - -最小交付： - -- Agent 与 Knowledge Source readiness 的清晰状态和修复提示。 -- 当前支持矩阵、访问边界和最后验证日期。 -- 首次任务引导，不要求用户先创建群组。 -- 一个 Agent + 可选知识来源的真实任务演示。 -- 安装、失败诊断和数据出站说明。 - -验证： - -- 5 名新用户不依赖现场解释完成安装和首个任务。 -- 首次任务失败能归因到安装、登录、权限、Connector 或任务输入。 -- README、应用状态和代码能力一致。 - -### Phase 1：Context Pack + Task Outcome，4-10 周 - -**目标结果：** 用户能把一次 Agent 工作变成可复盘、可采用的结果，而不是一段聊天记录。 - -最小交付： - -- Task、Context Pack、Run、Artifact、Evidence、Decision 的本地最小模型。 -- 一个 Primary + Reviewer 工作协议。 -- Reviewer 默认只看到 Artifact、验收标准和声明过的 Evidence，不默认读取 Primary 的完整对话。 -- Artifact 导出、接受、拒绝、要求修改和 Reopen。 -- 来源和 Evidence 的人工校正入口。 - -验证： - -- 至少 20 个任务能回答“用了什么上下文、谁产生了什么、为什么采用”。 -- 80% 的测试用户不需要手工整理聊天内容就能导出或采用 Artifact。 -- 任何 Verified 状态都能追溯到具体 Evidence。 - -### Phase 2：Connector Contract + Evidence Graph，10-16 周 - -**目标结果：** 新 Agent 和知识来源可以通过稳定能力协议加入，且结果关系能够被搜索和复验。 - -最小交付： - -- Agent Connector Manifest：能力、Session、权限、事件、成本和出站声明。 -- Knowledge Connector Manifest：访问方式、范围、引用、快照能力和限制。 -- 统一 Run Event：Started、Progress、Permission、SourceUsed、Artifact、Evidence、Usage、Completed/Failed/Cancelled。 -- Artifact、Evidence、Source 和 Decision 的关系图。 -- 可导出的 Evidence Bundle 和诊断包。 - -验证： - -- 用第二种实现验证 Contract 边界，而不是继续硬编码核心业务。 -- 至少一个外部 Connector 或 Task Template 贡献。 -- Connector 失败不会造成静默丢失或错误的“已完成”。 - -### Phase 3：Local / Cloud Handoff 与一个 Channel，4-8 个月，条件阶段 - -**进入条件：** 15 名固定用户中至少 8 名在 30 天内重复使用，并有 3 个以上重复的后台执行或外部渠道需求。 - -候选能力： - -- 本地 Context Pack 的出站预览与用户批准。 -- 一个 Cloud Agent 的创建、取消、状态和 Artifact 回传。 -- 优先接一个任务型 Channel。开发者样本优先 GitHub Issue/PR；知识工作样本优先钉钉或飞书。 -- Channel 只承载 Task、待验收结果和有效上下文，不复制完整 IM。 - -### Phase 4：Typed Workflow、预算和停止条件，8-12 个月，条件阶段 - -**进入条件：** 同一工作协议被至少 5 名用户重复执行，且手工步骤稳定。 - -候选能力： - -- 有类型的输入、输出和 Evidence 要求。 -- Reviewer、重试、停止条件和 Human Gate。 -- Task、Workspace 和 Channel 预算。 -- Observed / Estimated / Unavailable 三态成本。 -- Workflow 版本、运行历史和失败恢复。 - -### Phase 5：Team 与企业治理，12 个月后，条件阶段 - -**进入条件：** 至少 3 个团队对同一标准化能力实际付费，且不是定制 Connector 或咨询收入。 - -候选能力： - -- 可选加密同步与纯本地模式并存。 -- 共享模板、策略、RBAC、审计和预算。 -- SSO/SCIM、签名 Connector Registry、离线更新和兼容 SLA。 - -## 5. UI / UX 方向 - -### 5.1 导航从聊天转向工作状态 - -左侧导航优先级： - -1. Inbox：需要授权、补充输入或验收的事项。 -2. Active Tasks：进行中、待复核、失败和待重试。 -3. Workspaces / Channels：持续主题和工作边界。 -4. Conversations：Task 内的交互记录。 -5. Agents / Knowledge Sources：连接与能力状态。 - -### 5.2 Task 工作台 - -首屏必须回答： - -- 目标和验收标准是什么。 -- 哪些 Context 被允许使用。 -- 哪些 Run 已完成或失败。 -- 当前 Artifact 和 Evidence 是什么。 -- 用户下一步需要采用、修改、授权还是重试。 - -完整聊天流水作为辅助视图，不应占据默认主界面。 - -### 5.3 多 Agent 对照 - -- 使用相同 Context Pack 的独立 Attempt。 -- Artifact 差异、证据覆盖和冲突高亮。 -- 时间、成本和失败状态明确显示。 -- 不用 Agent 卡片墙代替可比较的信息结构。 - -### 5.4 通知 - -只通知需要人类行动的事件：权限请求、缺少输入、结果待验收、预算风险、Run 失败和 Connector 退化。 - -## 6. 指标体系 - -### 6.1 北极星 - -**每周被用户实际采用并完成验证的任务产出数。** - -同时披露：创建 Task 数、Adopted Task 数、失败激活用户数和每个安装 cohort 的人均值。不得只统计多 Agent Task，以免诱导不必要的 Agent 数量增长。 - -### 6.2 当前 OMTM - -**固定首批用户的 30 天重复 Outcome 率。** - -第 6 周前固定最先完成真实 Task 的 15 名用户，要求至少 8 名在各自首次任务后的 30 天内再次完成一个有 Artifact、Evidence 和 Decision 的 Task。 - -### 6.3 价值指标 - -- 首次 Task 完成率和完成时间。 -- Context Pack 被实际使用和校正的比例。 -- Artifact 被采用、导出或继续使用的比例。 -- Reviewer 新增有效 Finding 的采用率和误报率。 -- 相对手工跨 Agent 的上下文搬运与协调时间。 -- 单 Agent 与多 Agent 的质量、等待和成本差异。 - -### 6.4 可靠性指标 - -- Agent Session resume 成功率。 -- Knowledge Source readiness 和读取成功率。 -- Run 取消、失败恢复和 Artifact 捕获完整率。 -- Connector 版本退化率。 -- 权限越界、错误写入和数据丢失事件。 - -## 7. 明确不做 - -近期不应优先： - -- 用更多 Agent Logo 作为版本卖点。 -- 通用消费者聊天或社交产品。 -- 自建模型、Token Marketplace 或默认 Token 加价。 -- 自动抓取并索引用户所有知识库。 -- 无限制 Swarm、无限轮次和无人值守写入。 -- 在 Outcome 闭环成熟前建设 Cron、Webhook 和复杂自动化市场。 -- 同时开发多个 Cloud Agent、多个 IM Channel 和完整 Team 平台。 -- 把 General Agent 理解为“没有边界、什么都能做”。 - -## 8. 决策门 - -| 时间 | 必须回答的问题 | 决策 | -| --- | --- | --- | -| 第 4 周 | 新用户是否能独立完成首个真实任务？ | 否则先修激活，不增加平台范围 | -| 第 10 周 | Task、Context Pack 和 Outcome 是否减少手工整理并提高采用？ | 否则简化对象和首发协议 | -| 第 12-16 周 | 15 名固定用户中是否至少 8 名重复，是否出现外部贡献？ | 成立才投入 Cloud/Channel | -| 第 6-8 个月 | Cloud 或 Channel 是否被真实重复使用并愿意付费？ | 只扩展被证明的入口 | -| 第 12 个月后 | 是否有 3 个团队为同一标准化能力回款？ | 成立才进入 Team/Enterprise | - -## 9. 最终判断 - -Meldwork 的迭代顺序应该是： - -1. 从 Agent 会话升级到可采用的 Task Outcome。 -2. 从临时提示升级到可授权、可复验的 Context Pack。 -3. 从硬编码适配升级到 Agent 与 Knowledge Connector Contract。 -4. 从本地工作台扩展到经用户授权的 Cloud 和 Channel。 -5. 最后才把重复工作方式产品化为 Workflow 与 Team Governance。 - -第一和第二步没有完成时，Cloud、Channel、Workflow 和企业功能只会放大当前聊天产品的复杂度。 diff --git a/docs/promo-video-scripts.md b/docs/promo-video-scripts.md deleted file mode 100644 index 9c2d1e1..0000000 --- a/docs/promo-video-scripts.md +++ /dev/null @@ -1,376 +0,0 @@ -# Meldwork 宣传视频脚本 - -本文提供一支 75 秒产品主片的中文与英文版本，并说明如何从同一批录屏素材中拆出 README GIF、30 秒短片和 15 秒预告。 - -核心叙事： - -> **一个任务，两种视角，一份用户能够检查的结果。** - -视频不强调 Agent 数量，也不把未来能力包装成当前功能。所有主画面都来自真实客户端操作。 - -## 一、创意方向 - -### 目标观众 - -- 已经同时使用两种以上 Agent 的开发者、研究者、产品经理和独立创作者。 -- 对多 Agent 概念感兴趣，但反感角色扮演、无限对话和不可检查结果的人。 -- 希望保留本地工作状态、明确文件权限并继续使用现有 Agent 与 Provider 的用户。 - -### 看完后只需记住三件事 - -1. Meldwork 让一项任务在不同 Agent 之间保持完整。 -2. 多 Agent 协作有明确参与者、上下文和轮次边界。 -3. 最终结果不是黑盒，用户可以检查后再决定。 - -### 视觉风格 - -- 16:9 横屏，优先 `3840 × 2160` 或 `2560 × 1440`，24 或 30 fps。 -- 以真实产品录屏为主，使用深色或中性背景、白色文字和少量品牌珊瑚色。 -- 每个镜头只突出一个动作：选择、附加、讨论、检查或决定。 -- 字幕使用 Inter、SF Pro 或思源黑体，字距为 0，不使用夸张描边。 -- 转场以硬切、轻微推近和界面动作匹配为主，不使用粒子、机器人、发光球体或通用 AI 动画。 -- 音乐选择克制的电子氛围与轻节拍；不使用电影预告式重击和连续上升音效。 - -### 画面结构 - -| 时间 | 视觉任务 | -| --- | --- | -| 0:00-0:06 | 说明“拥有多个 Agent”不是难点 | -| 0:06-0:14 | 从一个 Agent 开始，按需增加另一个 | -| 0:14-0:25 | 选择 Agent、工作目录和权限边界 | -| 0:25-0:36 | 加入必要文件、Skill 或知识来源 | -| 0:36-0:51 | 设置轮次上限并展示有界讨论 | -| 0:51-1:06 | 检查 Agent、轮次、上下文、结论和事件 | -| 1:06-1:15 | 人保留最终决定，品牌收尾 | - -## 二、固定屏幕字幕 - -这些字幕在中英文版本中保持相同节奏，每次只出现一句。 - -| 中文 | English | -| --- | --- | -| 让任务保持完整 | Keep the task together. | -| 选择 Agent，设定边界 | Choose the Agents. Set the boundary. | -| 只加入必要上下文 | Add only the context needed. | -| 设置轮次上限 | Set the round limit. | -| 验收前先检查 | Inspect before accepting. | - -涉及本地优先时，画面下方使用一条事实说明： - -> **工作空间状态保存在本机；Agent 请求由所配置的 Provider 处理。** - -英文版本： - -> **Workspace state stays local. Agent requests use your configured Provider.** - -## 三、中文 75 秒主片 - -### 0:00-0:06｜问题 - -**画面** - -快速切过三个不同 Agent 的独立窗口或 Logo，随即切到 Meldwork 中的一项未完成任务。画面不超过三次切换。 - -**旁白** - -> 现在，找到一个能回答问题的 Agent 很容易。难的是，切换 Agent 之后，这项工作还能不能保持完整。 - -**屏幕字幕** - -> 让任务保持完整 - -### 0:06-0:14｜从一个 Agent 开始 - -**画面** - -打开一个历史单聊，显示此前结论；用户发送继续任务的消息，Agent 行内开始响应。 - -**旁白** - -> 在 Meldwork，你先从一个 Agent 开始。只有当任务需要另一种能力或独立质疑时，才把第二个 Agent 加进来。 - -### 0:14-0:25｜先确定边界 - -**画面** - -创建群组，选择两个 Agent，选择演示工作目录，写入开关保持关闭。镜头依次轻微推近三个动作。 - -**旁白** - -> 选择参与者、工作目录，并决定是否允许写入。任务开始前，边界清楚可见。 - -**屏幕字幕** - -> 选择 Agent，设定边界 - -### 0:25-0:36｜加入必要上下文 - -**画面** - -附加 `architecture.md` 与 `tests.md`，短暂展示 Skill 或已经就绪的知识来源入口。若知识来源未稳定配置，只使用文件附件画面。 - -**旁白** - -> 只加入这次任务真正需要的文件、Skill 和知识来源。上下文不再靠每次切换后重新拼接。 - -**屏幕字幕** - -> 只加入必要上下文 - -### 0:36-0:51｜设置轮次上限 - -**画面** - -切换到自动讨论，把“最大轮数”设为 2。展示两个 Agent 依次响应、第 1 轮切换到第 2 轮，以及第 2 轮完成。 - -**旁白** - -> 给两个 Agent 设置清晰的轮次上限，让它们先提出观点，再质疑和修订。目的不是增加声音，而是减少没有被发现的假设和错误。 - -**屏幕字幕** - -> 设置轮次上限 - -### 0:51-1:06｜检查运行证据 - -**画面** - -打开 Run 详情，切换 Agent 与轮次，展开结论、注入的上下文来源、上下文计数和脱敏事件。每个区域停留约 1 秒，避免快速扫过。 - -**旁白** - -> 打开运行详情，你可以看到每个 Agent、每一轮、注入的上下文来源与数量、形成的结论和脱敏事件。先检查结果，再决定是否相信和采用。 - -**屏幕字幕** - -> 验收前先检查 - -**事实说明** - -> 工作空间状态保存在本机；Agent 请求由所配置的 Provider 处理。 - -### 1:06-1:15｜人的最终决定 - -**画面** - -关闭 Run 详情，切换到“单轮回答”，只点名一个 Agent 生成最终修订。随后淡出到 Meldwork 标志、产品名与 Slogan。 - -**旁白** - -> 最终决定仍然属于你。Agent 随时切换，工作始终连续。Meldwork。 - -**收尾画面** - -> Meldwork -> Agents change. Work continues. - -## 四、English 75-Second Master - -### 0:00-0:06 | The problem - -**Visual** - -Cut across three separate Agent surfaces, then land on one unfinished task inside Meldwork. Keep the sequence restrained and readable. - -**Voice-over** - -> Finding an Agent that can answer a question is easy. Keeping the work coherent when you switch Agents is not. - -**On-screen text** - -> Keep the task together. - -### 0:06-0:14 | Start with one Agent - -**Visual** - -Open an existing direct conversation, reveal the last confirmed decision, and send a continuation request. Show the inline run state. - -**Voice-over** - -> In Meldwork, you start with one Agent. You add another only when the task needs a different capability or an independent challenge. - -### 0:14-0:25 | Set the boundary - -**Visual** - -Create a group, choose two Agents, select the demo working folder, and keep workspace writes off. - -**Voice-over** - -> Choose the participants and working folder, then decide whether workspace writes are enabled. The boundary is visible before the task begins. - -**On-screen text** - -> Choose the Agents. Set the boundary. - -### 0:25-0:36 | Add necessary context - -**Visual** - -Attach `architecture.md` and `tests.md`. Briefly reveal a compatible Skill or a configured knowledge source only when it is ready on the recording machine. - -**Voice-over** - -> Add only the files, Skills, and knowledge sources this task needs. Stop rebuilding context every time the work moves. - -**On-screen text** - -> Add only the context needed. - -### 0:36-0:51 | Set a round limit - -**Visual** - -Select automatic discussion, set the maximum round limit to two, and show the Agents completing round one and round two. - -**Voice-over** - -> Give two Agents a clear round limit so they can propose, challenge, and refine. More voices are not the goal. Fewer unchecked assumptions are. - -**On-screen text** - -> Set the round limit. - -### 0:51-1:06 | Inspect the work - -**Visual** - -Open Run details. Switch between Agents and rounds, then reveal conclusions, injected source messages, context counts, and sanitized events. - -**Voice-over** - -> Open Run details to inspect each Agent, each round, the injected source messages and context counts, the conclusions reached, and the sanitized event history. Inspect the work before you trust the result. - -**On-screen text** - -> Inspect before accepting. - -**Factual lower-third** - -> Workspace state stays local. Agent requests use your configured Provider. - -### 1:06-1:15 | Make the final call - -**Visual** - -Close Run details, switch to Single response, target one Agent for the final revision, then fade to the Meldwork mark, wordmark, and slogan. - -**Voice-over** - -> The final decision stays with you. Agents change. Work continues. Meldwork. - -**End frame** - -> Meldwork -> Agents change. Work continues. - -## 五、声音与剪辑 - -### 音乐 - -- 开头使用低频但轻量的脉冲，不做紧张悬疑。 -- 选择 Agent、目录和附件时加入非常轻的界面触感音。 -- 自动讨论开始时加入一个短促节拍，不为每条消息重复音效。 -- 打开 Run 详情时减弱音乐，让旁白和界面信息更清楚。 -- 结尾不做大幅上扬，只保留一个干净的收束音。 - -### 节奏 - -- 前 6 秒最多 4 个镜头。 -- 6-36 秒每个操作镜头保持 2-4 秒。 -- 自动讨论过程允许加速，但 Agent、轮次和完成状态必须可辨认。 -- Run 详情禁止快速滚动；每个检查点至少停留 1 秒。 -- 品牌收尾保持 2.5-3 秒，给观众留下识别时间。 - -### 字幕 - -- 全程字幕，但每行不超过 18 个中文字符或 42 个英文字符。 -- 旁白字幕靠下；核心屏幕字幕位于画面左上或留白区，二者不要重叠。 -- 不在画面上解释产品设计方法，也不加入“如何阅读本视频”的说明。 - -## 六、30 秒精简版 - -从主片保留四段： - -1. `0:00-0:06`：Agent 容易找到，工作容易被切碎。 -2. `0:14-0:25`：选择 Agent、目录与权限。 -3. `0:36-0:51`：两轮上限与讨论过程压缩为 8 秒。 -4. `0:51-1:15`：检查运行详情与品牌收尾压缩为 10 秒。 - -中文结尾旁白： - -> 不要只收集更多回答。让一项工作保持完整，并在接受之前看清它。Meldwork。 - -English ending: - -> More answers are not the goal. Keep the task coherent. Inspect the result before you accept it. Meldwork. - -## 七、15 秒预告 - -### 中文 - -**0:00-0:04** - -> 你不缺 Agent。你缺的是一项不会在切换中断掉的工作。 - -**0:04-0:11** - -画面依次展示：两个 Agent、2 轮上限、Run 详情。 - -**0:11-0:15** - -> Agent 随时切换，工作始终连续。Meldwork。 - -### English - -**0:00-0:04** - -> You do not need more Agents. You need the work to survive the switch. - -**0:04-0:11** - -Show two Agents, a two-round limit, and Run details. - -**0:11-0:15** - -> Agents change. Work continues. Meldwork. - -## 八、标题与封面文案 - -### 中文标题 - -- `我不需要更多 Agent，我需要一项不断线的工作 | Meldwork` -- `两个 Agent 不等于更好的答案，除非你能检查过程` -- `Meldwork：让一项任务在不同 Agent 之间保持完整` - -### English titles - -- `Your Agents Change. Your Work Shouldn't. | Meldwork` -- `One Task. Two Perspectives. An Inspectable Result.` -- `Meldwork: Keep the Work Together Across Agents` - -### 封面文字 - -中文： - -> 一个任务 -> 两种视角 - -英文： - -> One Task -> Two Perspectives - -封面只使用一个真实客户端画面或 Meldwork 标志，不放十个 Agent Logo，不用抽象 AI 网络图。 - -## 九、上线前检查 - -- [ ] 所有功能都能在当前录制环境中重复执行。 -- [ ] 视频没有暗示自动组队、统一检索、Cloud Agent 或 Channel 已经可用。 -- [ ] 本地优先说明同时交代 Provider 请求边界。 -- [ ] 写入权限、路径、附件和知识来源没有泄露真实数据。 -- [ ] Run 详情中没有凭据、原始思维链、完整命令或原生 Session 标识。 -- [ ] 中英文旁白表达同一事实，没有一版比另一版做出更强承诺。 -- [ ] 品牌名、Logo、Slogan 和珊瑚色端点在所有版本中一致。 -- [ ] 结尾把最终决定留给用户，不把 Agent 共识包装成正确性保证。 diff --git a/docs/public-mvp-release.md b/docs/public-mvp-release.md deleted file mode 100644 index 5fbef8e..0000000 --- a/docs/public-mvp-release.md +++ /dev/null @@ -1,53 +0,0 @@ -# Public MVP Release Checklist - -Meldwork's public MVP is one Apple silicon macOS workflow: two locally ready Agents produce and review one deliverable in a bounded group, while the human controls context, workspace access, and adoption. - -## Public MVP Contract - -- Supported release target: Apple silicon macOS only. -- Required workflow: create a two-Agent group, attach task files, complete a bounded discussion, inspect final replies and run state, then make a human adoption decision. -- Required local capability: at least two release-certified Agent CLIs can be detected, authenticated, invoked, cancelled, and resumed where their native protocol supports it. -- Data boundary: conversations, attachments, run state, Provider profiles, and selections remain in Electron-owned local storage; third-party Agent and Provider traffic follows the user's selected tools. -- Explicit absences: no Windows or Intel Mac release claim, no production Cloud Agent, no production Channel ingress, no automatic merge of separate conversation histories, and no claim that every listed Agent is release-certified. - -## Blocking Decisions - -- [x] Use AGPL-3.0-only for the Community Edition and preserve a separate commercial-license path for proprietary redistribution, embedding, and future commercial editions. -- [x] Use the stable macOS Bundle ID `com.rydersun.meldwork` before registering the first public binary. -- [ ] Confirm the public project name after trademark, domain, and account checks documented in `brand-strategy.md`. - -## Distribution Gates - -- [ ] Enroll the release owner or organization in the Apple Developer Program. -- [ ] Create and install a Developer ID Application certificate. -- [ ] Configure notarization credentials without committing them to the repository. -- [ ] Produce DMG and ZIP artifacts from a clean tagged commit with `npm --prefix desktop run dist:public`. -- [ ] Verify Developer ID signatures, Gatekeeper acceptance, notarization, stapling, archive contents, and SHA-256 checksums. -- [ ] Install the DMG on a clean Apple silicon Mac user account with no prior Meldwork data. - -## Product Acceptance - -- [ ] Complete the two-Agent produce-and-review workflow on the exact release package with two certified Agent/version combinations. -- [ ] Verify first-run detection, missing-auth guidance, Provider configuration, cancellation, restart recovery, file drag-and-drop, attachment opening, and deletion cleanup. -- [ ] Confirm that a failed or unavailable Agent does not erase history or make the remaining result look fully verified. -- [ ] Capture English and Chinese screenshots from the exact release package. -- [ ] Record every known limitation in the Release notes. - -## Repository Gates - -- [ ] Update README download links and remove private-preview wording only after the public Release exists. -- [ ] Make CI checks required for `main` after the repository is public; the current private repository plan returns HTTP 403 for branch protection. -- [x] Enable GitHub dependency vulnerability alerts. -- [ ] Enable GitHub private vulnerability reporting and confirm the reporting path after the repository is public; the endpoint is unavailable while this repository remains private. -- [x] Verify README, contribution, security, notice, commercial-use, and license links. -- [ ] Put a reviewed contributor-license agreement process in place before merging external code intended for separately licensed commercial builds. -- [ ] Publish `v0.1.0` release notes, DMG, ZIP, and `SHA256SUMS.txt` from the same commit. -- [ ] Change repository visibility only after the tagged Release and public documentation agree. - -## Not Required For The First Public MVP - -- Windows or Intel Mac packages. -- A production Cloud or Channel Connector. -- Certification of every Agent shown in the catalog. -- A server, account system, telemetry, automatic updater, or hosted conversation storage. -- A separate workflow for every business domain. diff --git a/docs/tests.md b/docs/tests.md deleted file mode 100644 index be99dfa..0000000 --- a/docs/tests.md +++ /dev/null @@ -1,105 +0,0 @@ -# Verification And Test Coverage - -Verification evidence below spans 2026-07-29 through 2026-08-06 on macOS arm64. Repository tooling and CI support Node.js 20.19 or newer; the packaged desktop runs on Electron's bundled Node.js runtime. On 2026-08-06, the current working tree completed the frontend and desktop suites, both renderer builds, arm64 package validation, and strict ad-hoc signature verification. Packaged direct/group attachment acceptance retains its 2026-08-05 executed baseline. Unchanged distribution, compatibility, and audit rows retain their earlier executed baseline. - -## Executed Verification - -| Check | Evidence | Result | -| --- | --- | --- | -| Frontend unit suite | `npm --prefix frontend test` | 30 files and 237/237 tests passed on 2026-08-06 | -| Desktop unit suite | `npm --prefix desktop test` | 842/842 tests passed on 2026-08-06 | -| CI Node adapter compatibility | `npx -y node@20.19.0 --test desktop/test/cli-adapters.test.cjs` | 71/71 tests passed | -| Renderer builds | `npm --prefix frontend run build` and `npm --prefix frontend run build:desktop` | Both Vite builds passed on 2026-08-06. The largest JavaScript chunk was 354.72 kB, so the previous 500 kB warning did not appear | -| Current desktop package validation | `npm --prefix desktop run pack`, `codesign --verify --deep --strict desktop/dist/mac-arm64/Meldwork.app`, and `spctl --assess --type execute --verbose=4 desktop/dist/mac-arm64/Meldwork.app` | Electron 39.8.10 arm64 packaging passed on 2026-08-06 with permanent Bundle ID `com.rydersun.meldwork`, version `0.1.0`, and `app.asar` SHA-256 `551aeccf3aabc53e0f4af4fe39bf5acaaf5b5ae0a66b2e5d32ebb93cea02f0dd`. Strict integrity verification passed with an ad-hoc signature; Gatekeeper rejected the app because real Developer ID signing and notarization are still unavailable | -| Public release fail-closed check | `npm --prefix desktop run dist:public` without release credentials | Exited before frontend build or packaging with `PUBLIC_RELEASE_SIGNING_IDENTITY_MISSING`; no ad-hoc public artifact was produced | -| Harness / Run Ledger automated regression coverage | `frontend/src/__tests__/roundrelay/App.conversation-trace.spec.js`; `frontend/src/__tests__/roundrelay/App.run-trace.spec.js`; `desktop/test/run-harness.test.cjs`; `desktop/test/run-ledger.test.cjs`; `desktop/test/local-workspace-harness.test.cjs` | Included in the passing 2026-08-06 suites: direct inline and group-panel trace contracts, streamed terminal conclusions, compact evidence handoff, sanitized checkpoints, provenance conflict rejection, durable restart recovery, no overall Run deadline, per-Agent watchdog cleanup, retryable transactions, and stale run-ID stop rejection | -| Runtime interruption and Human Gate recovery | `desktop/test/local-workspace-human-gate-recovery.test.cjs`; `desktop/test/human-gate-coordinator.test.cjs`; `desktop/test/local-workspace-run-coordinator.test.cjs`; `desktop/test/local-workspace-manual-controls.test.cjs`; `desktop/test/local-workspace.test.cjs` | Replay-safe final Agent slots can recover; legacy Role Review continuations fail closed with `LOCAL_WORKFLOW_UNSUPPORTED`, and non-final multi-Agent slots without a durable orchestration cursor fail closed with `LOCAL_RUN_ORCHESTRATION_RESUME_UNAVAILABLE`. Initial or resume checkpoint failures roll pending continuation state back, parallel Gates are exposed serially, waiter/listener cleanup is bounded, and shutdown still settles when a waiting checkpoint fails | -| Agent, Knowledge, and mock Cloud runtime coverage | `desktop/test/agent-connector-manifest.test.cjs`; `desktop/test/agent-connector-registry.test.cjs`; `desktop/test/agent-connector-instance-store.test.cjs`; `desktop/test/agent-connector-runtime.test.cjs`; `desktop/test/run-event-protocol.test.cjs`; `desktop/test/knowledge-connector-registry.test.cjs`; `desktop/test/local-knowledge-connectors.test.cjs`; `desktop/test/cloud-agent-runtime.test.cjs` | Approved Agent Manifests/instances, two Knowledge implementations, mock asynchronous Cloud execution, Human Gates, and fail-fast 401/403 handling that retains the configured Agent are included in the passing desktop suite. Production Channel and Cloud connectors are not configured | -| Electron CLI adapter and Hermes SQLite smoke | `ELECTRON_RUN_AS_NODE=1 ./node_modules/.bin/electron --test test/cli-adapters.test.cjs` from `desktop/` | 31/31 tests passed under Electron 39.8.10 / Node.js 22.22.1, including the read-only Hermes SQLite watermark and post-watermark `stop`/`length` selection contract | -| Current macOS distribution | `npm --prefix desktop run dist`; inspect ZIP and read-only mounted DMG | arm64 `.app`, DMG, and ZIP produced on 2026-08-06. ZIP and DMG both contain `com.rydersun.meldwork` plus byte-matching `LICENSE`, `NOTICE`, and `COMMERCIAL_USE.md`. DMG SHA-256 is `23325b745bd575cba92ff6ef913ded69216ddaeed3f33945a84e15bdbb27ea3f`; ZIP SHA-256 is `480986672e142bc94e4ea8b5627b19ee22bdddaf74cb05af7209d3e62021b9e5` | -| Dependency audit | `npm --prefix desktop audit`, `npm --prefix frontend audit`, and both commands with `--omit=dev` | 0 known vulnerabilities in the complete and production-only dependency sets after upgrading Electron to 39.8.10, `fast-uri` to 3.1.5, and affected `brace-expansion` lockfile entries to 1.1.18, 2.1.4, or 5.0.9 | -| ACP runtime packaging | Inspect and extract packaged `app.asar`, then dynamically import its production modules | `@agentclientprotocol/sdk` 0.23.0, `zod` 4.4.3, the ACP client, and both inbound Zod validators loaded successfully | -| Current packaged startup and quit smoke | Launch the exact `desktop/dist/mac-arm64/Meldwork.app` with a fresh temporary profile and CDP port `9339` | The exact package exposed one `Meldwork` page at its bundled `file:` URL ending `#/chat`; its User-Agent reported Electron 39.8.10, the packaged plist reported `com.rydersun.meldwork`, and the isolated process, CDP listener, and temporary profile were removed afterward | -| Packaged Harness group acceptance (pre-final edge-fix package) | Launch the packaged app with isolated profile `/private/tmp/meldwork-final-harness-profile.xVSai5`; inspect group `efcf61d5-2875-419d-a285-0c7b01171d8d`, run `ccae01a8-89c0-4088-9da2-ff8b77cec9b1`, and Task/thread root `7c25e3f7-aa88-47cb-a87f-daa6b5aa12c6` | Two rounds completed with no failures or 401 retries. Hermes and Codex both retained `turns: 2`; Hermes used one Task-scoped `legacy` Session with complete provenance. Live preload capture observed 14 events including four `answer_delta` events; the group showed no inline process details and opened a 380 CSS px right-side panel. Hermes truthfully reported `connector_limited` where legacy transport could not expose structured tool details. Ledger state retained the compacted durable trace rather than every live event | -| Historical packaged Harness direct acceptance | In the earlier exact packaged app/profile, inspect direct conversation `e85c04a5-6029-4c68-91aa-2696b759f64a` during and after a real Codex run | While running, conclusion and tool/status details streamed inline with no right panel. After completion, marker `DIRECT_LIVE_CAPTURE_OK` remained, execution details collapsed with two durable tool events, and no right panel appeared. The app then quit cleanly and both its PID and CDP listener were gone | -| Packaged attachment acceptance (2026-08-05 package) | Launch the exact package with the existing local profile and CDP port `9241`; drag HTML, JavaScript, and ZIP files into a group and a Codex direct conversation | All three files appeared in both composers with no unsupported-type or lower-limit error. Test drafts and private attachment copies were removed afterward; current attachment behavior is additionally pinned by the full 2026-08-06 regression suite | -| Logo packaging | Compare source, Vite output, and packaged asar hashes; inspect generated `icon.icns` and packaged UI | The final 3D Relay Fold app/product PNGs match source byte-for-byte in the package, and the packaged renderer loads the 1024x1024 brand asset | -| Idle startup network | Inspect the Meldwork process tree with `lsof` after disconnecting CDP | No established TCP or UDP connection; only the explicitly enabled loopback CDP listener remained | -| Empty-store secure-storage behavior | Unit tests plus a one-second process sample | No `SecItemCopyMatching`, `SecKeychain`, `CSSM_Decrypt`, or decrypt call observed without a stored Provider | -| macOS signature | `codesign --verify --deep --strict` | Passed with ad-hoc signature; `spctl` rejection is expected until Developer ID signing/notarization exists | - -The broader first-run, group creation, Skill IPC, clipboard attachment, real Hermes/Codex group relay, and direct-stream acceptance remain executed historical baselines. After the final shutdown, Gate, direct-401, and parallel-failure fixes, the exact current package was rebuilt and passed the startup/preload/render/quit smoke above; the final edge fixes are additionally covered by focused and full desktop regressions, but the current package did not repeat the complete live Agent CLI matrix. - -## Automated Coverage - -| Use case / rule | Expected behavior, including deny case | Evidence | Status | -| --- | --- | --- | --- | -| Renderer workbench and onboarding | Shows the configured Agent catalog, gates the first-run carousel on Agent detection, supports focus/scroll/back dismissal, local groups/direct chats, theme, and locale | `frontend/src/__tests__/roundrelay/App.spec.js` | Passed locally | -| Conversation run UX and session management | Shows Agent logos and capabilities, multiple direct sessions, rename/delete controls, per-Agent queued/running/completed state, automatic current/max round progress, inline direct execution, group trace-panel disclosure, background direct completion markers, unavailable-Agent history access, and truthful permission/image limits | `frontend/src/__tests__/roundrelay/App.spec.js`; `frontend/src/__tests__/roundrelay/App.conversation-trace.spec.js`; `frontend/src/__tests__/roundrelay/App.run-trace.spec.js`; `desktop/test/main-security.test.cjs` | Passed locally | -| Harness trace and Run Ledger durability | Streams allowlisted per-Agent trace and live context state, retains compact completed/partial/failed/stopped/timeout/interrupted traces, visibly renders streamed terminal conclusions, hands later Agents bounded source-addressable evidence, checkpoints sanitized run state, fails closed on malformed values, provenance conflicts, and duplicate identities, reconstructs durable turn outcomes after restart, keeps mutations retryable, reconciles terminal checkpoints idempotently, rejects stale run-ID stop requests, and purges ledger records with deleted conversations | `frontend/src/__tests__/roundrelay/App.run-trace.spec.js`; `desktop/test/run-harness.test.cjs`; `desktop/test/run-ledger.test.cjs`; `desktop/test/local-workspace-harness.test.cjs` | Passed locally | -| Immutable Context Packs and Session provenance | Captures immutable message, Skill, Knowledge, and attachment inputs; compares exact outbound payloads after mutation/restart; scopes native Sessions to Tasks; records inherited ancestry and provenance limits; warns instead of presenting newly packed IDs as complete latent Session context | `desktop/test/context-pack-store.test.cjs`; `desktop/test/local-workspace-context-packs.test.cjs`; `desktop/test/local-skill-snapshot.test.cjs`; `frontend/src/__tests__/roundrelay/App.run-trace.spec.js` | Passed locally | -| Human Gate, budget, and continuation recovery | Permission, budget, and generic decisions are durable; only replay-safe final Agent slots resume after restart; legacy Role Review continuations, non-final multi-Agent slots, cross-Run continuations, and missing Packs fail closed; checkpoint failure restores pending continuation state; parallel Gates serialize; manual retry/cancel/replace remain scoped to one Agent | `desktop/test/human-gate-coordinator.test.cjs`; `desktop/test/local-workspace-human-gate-recovery.test.cjs`; `desktop/test/local-workspace-run-coordinator.test.cjs`; `desktop/test/local-workspace-manual-controls.test.cjs`; `desktop/test/failure-policy.test.cjs`; `desktop/test/run-budget.test.cjs`; `desktop/test/run-scheduler.test.cjs` | Passed locally | -| Agent Connector contract | Enforces approved immutable Manifests/recipes, scoped instances, encrypted CredentialRefs, external discovery without core allowlist edits, version provenance, idempotent Run Event reduction, main/preload boundaries, and restart-stable replay | `desktop/test/agent-connector-manifest.test.cjs`; `desktop/test/agent-connector-registry.test.cjs`; `desktop/test/agent-connector-instance-store.test.cjs`; `desktop/test/agent-connector-runtime.test.cjs`; `desktop/test/run-event-protocol.test.cjs`; `desktop/test/main-security.test.cjs`; `desktop/test/preload-security.test.cjs` | Passed locally | -| Knowledge Connector contract | Enforces the full authorize/revoke/probe/search/fetch/snapshot/citation lifecycle across filesystem and memory implementations, stable bounded source IDs, connector-enforced read-only access, immutable snapshots, explicit live references, and citation reopening after restart | `desktop/test/knowledge-connector-contract.test.cjs`; `desktop/test/knowledge-connector-filesystem.test.cjs`; `desktop/test/knowledge-connector-memory.test.cjs`; `desktop/test/knowledge-connector-registry.test.cjs`; `desktop/test/local-knowledge-connectors.test.cjs`; `desktop/test/main-security.test.cjs`; `desktop/test/preload-security.test.cjs` | Passed locally | -| Mock Cloud Agent contract | Supports asynchronous submit/observe/input/cancel/artifact/reconcile, durable job/cursor replay, UI detach/reattach, duplicate suppression, cancel-once behavior, bounded shutdown, and retryable startup after recovery failures without requiring a server for local-only use | `desktop/test/cloud-agent-contract.test.cjs`; `desktop/test/cloud-agent-operation-store.test.cjs`; `desktop/test/cloud-agent-runtime.test.cjs`; `desktop/test/main-security.test.cjs`; `desktop/test/preload-security.test.cjs` | Passed locally; no production Cloud connector configured | -| Channel ingress framework and outbound audit | Test connectors verify signatures, reject stale/replayed/cross-scope events, map one durable Delivery to one Task through an injected `taskSink`, preserve cursor order, and replay outbound replies idempotently without renderer ownership. Production bootstrap intentionally has `connectors: []` and no `taskSink`, so no task-oriented Channel is shipped | `desktop/test/channel-ingress-contract.test.cjs`; `desktop/test/channel-inbox-store.test.cjs`; `desktop/test/channel-ingress-runtime.test.cjs`; `desktop/test/main-security.test.cjs` | Framework passed locally; production Channel not configured | -| Composer Skill routing | Loads Skills only for selected targets, supports `@` selection, and sends structured target-scoped coordinates | `frontend/src/__tests__/roundrelay/App.spec.js`; `desktop/test/local-skill-catalog.test.cjs`; `desktop/test/agent-installer.test.cjs`; `desktop/test/local-workspace.test.cjs` | Passed locally | -| Legacy knowledge-base hint routing | Separates ready/planned Feishu, DingTalk, and Obsidian hints, requires readable access, scopes selections to target Agents, persists only the selected Vault path, and rejects stale or unauthorized hints | `frontend/src/__tests__/roundrelay/App.spec.js`; `desktop/test/local-knowledge-base.test.cjs`; `desktop/test/knowledge-base-store.test.cjs`; `desktop/test/local-workspace.test.cjs`; `desktop/test/main-security.test.cjs` | Passed locally | -| Attachment composer UI | Imports picker, paste, Finder drag, and `DataTransfer.items` files; supports image, media, document, code, and archive metadata; blocks concurrent imports; discards unsent/overflow/stale imports; and sends metadata without paths or preview data | `frontend/src/__tests__/roundrelay/App.attachments.spec.js`; `frontend/src/__tests__/roundrelay/App.spec.js` | Passed locally | -| Attachment preview cache | Loads visible previews only, limits concurrent main-process requests to two, and evicts non-visible least-recent entries from the bounded cache | `frontend/src/__tests__/roundrelay/attachmentPreviews.spec.js` | Passed locally | -| Renderer bridge normalization | Uses only `window.roundrelayDesktop` services and normalizes missing data | `frontend/src/__tests__/roundrelay/desktop.spec.js` | Passed locally | -| Renderer i18n | Chinese/English keys and interpolation remain consistent | `frontend/src/__tests__/roundrelay/i18n.spec.js` | Passed locally | -| Renderer CSP and assets | Entry point keeps self-only/default restrictions, denies unsafe surfaces, and uses relative packaged assets | `frontend/src/__tests__/roundrelay/security.spec.js` | Passed locally | -| Main-frame IPC authorization | All registered local channels accept only the exact frontend main frame; other frames/paths are denied before dispatch | `desktop/test/main-security.test.cjs` | Passed locally | -| Electron navigation, lifecycle, and shutdown gate | Loads bundled frontend, denies in-window remote navigation, serializes refresh, rejects every trusted IPC call after shutdown starts, then waits for workspace/installer cleanup before quitting | `desktop/test/main-security.test.cjs` | Passed locally | -| Narrow preload API | Local documents get only named workspace, installer, Skill snapshot, attachment, Provider, local Agent Connector, Knowledge lifecycle, Cloud continuation/cancel, Outcome/Adoption, Human Gate, and per-Agent control methods. Attachment APIs expose no file read or path resolution; non-local documents get no privileged API | `desktop/test/preload-security.test.cjs` | Passed locally | -| Packaged Electron hardening | Fuses disable Node/runtime injection and require ASAR integrity | `desktop/test/package-security.test.cjs` | Passed locally | -| Public macOS release gate | `dist:public` requires a Developer ID source and one complete Apple notarization credential strategy; public config forces signing/notarization; the post-sign hook rejects ad-hoc signatures, missing Team ID, missing hardened runtime, and a Bundle ID other than `com.rydersun.meldwork` | `desktop/test/public-release-preflight.test.cjs`; `desktop/test/after-sign.test.cjs`; `desktop/test/package-security.test.cjs` | Passed locally; live Apple signing is still pending | -| Provider secret storage | Complete payload required; URL constrained; key encrypted; failures/corruption fail closed; delete works | `desktop/test/provider-store.test.cjs` | Passed locally | -| Agent readiness | Detects native credentials without returning values and scopes forwarded credential variables by Agent | `desktop/test/local-agent-readiness.test.cjs` | Passed locally | -| Installer allowlist and lifecycle | Fixed recipes, URL/command rejection, environment filtering, verification, cancellation, and single-task behavior | `desktop/test/agent-installer.test.cjs` | Passed locally | -| Attachment storage and validation | Validates image, media, document, code, Office, and archive signatures or bounded UTF-8 content; enforces MIME/name agreement and per-type limits; preserves private storage, checksums, tamper resistance, cleanup, bounded previews, and referenced-attachment deletion guards | `desktop/test/attachment-store.test.cjs`; `desktop/test/image-dimensions.test.cjs`; `desktop/test/main-security.test.cjs`; `desktop/test/preload-security.test.cjs` | Passed locally | -| CLI invocation and Hermes final-result safety | Per-Agent read-only/write arguments, Kimi ACP lifecycle, image limits, Hermes native Skill preload, guarded ACP-to-legacy fallback, invalid-session classification, best-effort pre-run message watermark, post-watermark `assistant` `stop`/`length` selection, official stdout fallback, early session persistence, environment scoping, secret redaction, and process-tree cancellation | `desktop/test/cli-adapters.test.cjs`; `desktop/test/cli-adapters-agent-protocols.test.cjs` | Passed locally | -| Workspace state and automation | Explicit persisted-field allowlists, path stripping, visual Task roots, Task-and-Agent group sessions, conversation-and-Agent direct sessions, exact legacy migration, workdir invalidation, bounded shared conclusions, target-scoped Skills, equal attachment context, cancellation-aware preflight, final-only downstream relay, failure isolation, complete rounds, strict consensus, no overall Run deadline, and per-Agent watchdog bounds | `desktop/test/local-workspace.test.cjs`; `desktop/test/local-workspace-auto.test.cjs`; `desktop/test/local-workspace-harness.test.cjs`; `desktop/test/run-scheduler.test.cjs` | Passed locally | -| Terminal run lifecycle | Completion events are transient and best-effort, listener failures do not change results, all-failed automatic runs keep the round-limit diagnostic, notification payloads are content-free, notification clicks open the target conversation, background successful direct runs receive completion markers, and shutdown suppresses new notifications | `desktop/test/local-workspace.test.cjs`; `desktop/test/main-security.test.cjs` | Passed locally | -| Managed OpenClaw | Isolated paths, key absent from config, immutable permission config, invalid scopes fail closed | `desktop/test/openclaw-runtime.test.cjs` | Passed locally | -| macOS packaging transform | Removes unused permission declarations, sets Electron fuses, and applies ad-hoc signing | `desktop/test/after-pack.test.cjs` | Passed locally | - -## CI-Declared Checks - -`.github/workflows/ci.yml` declares these push and pull-request checks: - -- Frontend: `npm ci`, `npm test`, `npm run build`, `npm run build:desktop` on Ubuntu. -- Desktop: frontend/desktop `npm ci`, `npm test`, and `npm run pack` on macOS. - -The workflow file exists, but branch protection and successful required checks are external GitHub state and are not verified by this repository documentation. - -## Proposed Tests - -| Type | Use case / rule | Expected behavior | Status | -| --- | --- | --- | --- | -| Automated packaged-app IPC integration | Extend the focused packaged smoke to exercise real preload IPC and attachment/Skill flows | Privileged calls work only in the main frame; imported images and selected Skills reach the expected Agent without exposing paths | Proposed | -| Automated Connector end-to-end integration | Drive one external Connector event through main-process validation, durable reduction, preload normalization, and renderer state | Supported fields and terminal state survive the complete pipeline and restart without duplicate effects | Proposed | -| Guarded live | One production task-oriented Channel Connector with an injected Task sink | Authenticated deliveries map idempotently to local Tasks and approved replies replay without renderer ownership | Proposed | -| Guarded live | One real Cloud Agent provider | Remote submit, detach/reattach, input, cancel, Artifact fetch, and reconciliation match the mock contract | Proposed | -| Guarded live | Real Agent CLI matrix on supported macOS/Windows versions | Detection, readiness, prompt execution, cancellation, session resume, Hermes final-row timing, and permission behavior match unit contracts | Proposed | -| Guarded live | Installer recipes on clean disposable OS users/VMs | Only the selected Agent is installed, cancellation cleans up, secrets are absent from child environment | Proposed | -| Automated visual regression | Light/dark theme and logo contrast | Detect theme, layout, or asset regressions without relying on manual screenshot inspection | Proposed | -| Guarded live | macOS Developer ID signing and notarization | Gatekeeper accepts the app and DMG on a clean machine | Proposed | -| Guarded live | Windows packaged build | Installation, app launch, CLI discovery, npm shim handling, and cancellation work on a real Windows device | Proposed | -| Automated resilience | Abrupt termination during workspace/provider writes | Previous valid state remains readable and no secret is left in a temporary file | Proposed | - -## Gaps - -| Priority | Rule with no current verification | Exposure | Status | -| --- | --- | --- | --- | -| High | Public release signing/notarization is not exercised with real Apple credentials | Distributed macOS artifacts can be rejected by Gatekeeper | Fail-closed preflight, forced signing/notarization config, and post-sign identity checks exist; live Developer ID and clean-machine acceptance remain pending | -| Medium | No concrete production Channel Connector or Task sink is configured | The Channel framework cannot yet receive a real external Task or deliver a production reply | Framework acceptance is complete and its tracking issues are closed; production configuration is outside the public MVP contract | -| Medium | No real Cloud Agent provider acceptance | Provider-specific authentication, polling, callback, and Artifact semantics may diverge from the mock contract | Mock Cloud Connector coverage only | -| Medium | No single automated Connector -> main -> persistence -> preload -> renderer test | Individually tested boundaries may still disagree when composed | Contract, main/preload, persistence, and renderer tests exist separately | -| Medium | No automated packaged preload/Agent end-to-end suite | Unit mocks may miss real IPC, attachment/Skill routing, or Agent process integration faults | Historical guarded live Harness/direct acceptance plus a current packaged startup/quit smoke; no automated suite | -| Medium | No clean-machine live Agent/installer matrix | Upstream CLI changes can invalidate flags, output parsing, paths, or installer behavior | None | -| Medium | No repeatable live Hermes CLI matrix, current-package direct run, or real macOS notification-click exercise | Upstream Hermes authentication/persistence timing and operating-system notification behavior can diverge from the isolated acceptance run | One isolated two-round packaged Hermes-to-Codex run, historical direct acceptance, and Electron SQLite smoke; no repeatable matrix | -| Medium | Windows release is not built or tested in CI | Windows support remains implementation-level rather than release-verified | None | -| Low | No automated visual regression or accessibility audit | Theme, contrast, focus, and responsive regressions require manual discovery | None | -| Low | No long-history/performance test | Large local message histories may expose latency or file-size limits late | None | diff --git a/docs/variables.md b/docs/variables.md deleted file mode 100644 index aa3621e..0000000 --- a/docs/variables.md +++ /dev/null @@ -1,82 +0,0 @@ -# Variables And Secrets - -Meldwork requires no `.env` file, server URL, account token, JWT, database credential, email credential, or cron secret. - -## User And Runtime Configuration - -| Name | Used by | Source and scope | Persistence / rotation | Risk and handling | -| --- | --- | --- | --- | --- | -| `ROUNDRELAY_CODEX_SANDBOX` | Codex adapter | Optional Electron process environment | Read at invocation; restart to change | Accepts only `read-only` or `workspace-write`; invalid values fall back to `read-only` | -| Provider `provider` | Compatible local Agents | User input in renderer, validated by main | Stored locally in `roundrelay-provider.json`; replace through UI | Non-secret display metadata | -| Provider `baseUrl` | Compatible local Agents | User input in renderer, validated by main | Stored locally; replace through UI | HTTPS required, except loopback HTTP; embedded credentials/query/fragment rejected | -| Provider `model` | Compatible local Agents | User input in renderer, validated by main | Stored locally; replace through UI | Non-secret model identifier | -| Provider `apiKey` | Compatible local Agents | User enters it in renderer; passed once over local IPC | Encrypted with `safeStorage`; rotate by saving a replacement or delete through UI | Secret; status and snapshots never return it | -| Obsidian Vault path | Knowledge-source selection | User chooses a directory through the main-owned OS picker | Stored in `roundrelay-knowledge-base.json`; replace or clear through UI | Non-secret local path, but may reveal directory naming; only selected Agents receive it as task context | -| Feishu / DingTalk CLI auth | Knowledge-source selection | Owned by the installed `lark-cli`/`opdev` or `dws` CLI | Managed and rotated through the upstream CLI | Meldwork probes status and document access but does not receive or store the upstream token | -| Theme / locale | Renderer | User preference | Browser `localStorage` | Non-secret | - -## Native Agent Credential Inputs - -Meldwork detects and forwards only credential variables associated with the selected Agent: - -| Agent | Recognized process variables | -| --- | --- | -| Codex | `OPENAI_API_KEY` | -| Hermes | `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` | -| OpenClaw | `OPENAI_API_KEY`, `OPENROUTER_API_KEY` | -| WorkBuddy | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` | -| Kimi Code | `MOONSHOT_API_KEY`, `KIMI_API_KEY` | -| Claude Code | `ANTHROPIC_API_KEY` | -| Qwen Code | `DASHSCOPE_API_KEY`, `OPENAI_API_KEY` | -| Gemini CLI | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | -| OpenCode | `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY` | -| OpenCodeReview | `OCR_LLM_TOKEN`, `OPENAI_API_KEY` | - -These credentials are owned and rotated through the upstream CLI/provider, not Meldwork. Readiness checks report only `ready`, `missing`, or `unknown`; they do not return credential values. - -## Internal Child-Process Variables - -Main derives these at invocation time; users should not set them as Meldwork configuration: - -| Variables | Purpose | -| --- | --- | -| `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL` | Normalized configured Provider values for compatible Agents | -| `HERMES_INFERENCE_MODEL` | Mirrors the configured model for Hermes | -| `CODEBUDDY_MODEL`, `CODEBUDDY_API_KEY`, `CODEBUDDY_BASE_URL` | WorkBuddy Provider mapping | -| `OCR_LLM_URL`, `OCR_LLM_TOKEN`, `OCR_LLM_MODEL`, `OCR_USE_ANTHROPIC` | OpenCodeReview Provider mapping | -| `ROUNDRELAY_OPENCLAW_API_KEY` | Secret environment reference used by generated OpenClaw config | -| `OPENCLAW_HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, `OPENCLAW_WORKSPACE_DIR` | Isolated managed OpenClaw runtime paths | -| `HERMES_EXEC_ASK`, `HERMES_YOLO_MODE`, `OPENCODE_PERMISSION` | Runtime safety overrides | - -The API key is intentionally absent from generated OpenClaw JSON and supplied only through the child environment. - -## Release Signing And Notarization - -These variables are used only by `npm --prefix desktop run dist:public`. They must come from the local Keychain or the release system's encrypted secret store and must never reach the renderer or packaged application. - -| Name | Used by | Source and scope | Persistence / rotation | Risk and handling | -| --- | --- | --- | --- | --- | -| `CSC_LINK` | electron-builder signing | Encrypted CI secret containing or pointing to the Developer ID `.p12` | Replace when the certificate is renewed or revoked | Secret certificate material; must be paired with `CSC_KEY_PASSWORD` | -| `CSC_KEY_PASSWORD` | electron-builder signing | Encrypted CI secret | Rotate with the exported `.p12` | Secret; never print or store in repository files | -| `CSC_NAME` | Local Keychain signing | Optional local identity selector | Update when the certificate identity changes | Non-secret name, but `dist:public` accepts only a Developer ID Application identity | -| `APPLE_API_KEY` | Apple notarization | Path to the private App Store Connect `.p8` key | Revoke and replace in App Store Connect | Secret file; `*.p8` is ignored by Git | -| `APPLE_API_KEY_ID`, `APPLE_API_ISSUER` | Apple notarization | App Store Connect identifiers stored with release secrets | Replace when the API key changes | Treat as release metadata and keep out of renderer state | -| `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID` | Alternative Apple notarization | Encrypted release secrets | Rotate the app-specific password and update Team membership as needed | The app-specific password is secret; the normal Apple ID password must never be used | -| `APPLE_KEYCHAIN_PROFILE`, `APPLE_KEYCHAIN` | Local `notarytool` profile | Local Keychain profile name and optional Keychain path | Recreate when Apple credentials rotate | References only; underlying credentials remain in Keychain | - -The public-release preflight requires one complete signing source and one complete notarization strategy. Partial credential groups fail before packaging, and the post-sign hook rejects ad-hoc or mismatched identities. - -## Non-Secret System Environment - -Agent children receive an allowlist of operating-system identity/path/locale/temp/certificate variables plus a constructed `PATH`. Meldwork does not forward the entire Electron environment. - -## Pre-Release Checklist - -- Confirm no real keys or tokens are present in source, tests, logs, or packaged assets. -- Confirm `safeStorage.isEncryptionAvailable()` succeeds on each supported release OS. -- Confirm Provider status never returns the API key and credential files remain mode `0600`. -- Confirm child-process environment tests cover newly supported Agents or variables. -- Confirm installer logs/state never expose command output or ambient secrets. -- Confirm `dist:public` passes with the intended Developer ID and fails when signing or notarization credentials are removed. -- Confirm no `.p8`, `.p12`, certificate password, or notarization profile is present in Git history or release archives. -- Rotate any credential used during guarded live testing before distributing artifacts. diff --git a/docs/assets/meldwork-multi-agent-review.png b/frontend/public/logos/meldwork-multi-agent-review.png similarity index 100% rename from docs/assets/meldwork-multi-agent-review.png rename to frontend/public/logos/meldwork-multi-agent-review.png diff --git a/docs/assets/meldwork-workspace-overview.png b/frontend/public/logos/meldwork-workspace-overview.png similarity index 100% rename from docs/assets/meldwork-workspace-overview.png rename to frontend/public/logos/meldwork-workspace-overview.png