Marigold

Marigold — 本地草稿（marigold-draft）

在你的设备上，以毫秒为单位完成 Marigold 审阅循环。Agent 将丰富的 HTML/SVG 草稿写入文件；marigold-draft open 会在与云端 Marigold 相同的评论界面中提供预览；你可以高亮、评论、就地编辑，然后点击 Send feedback to agent — Agent 阻塞的 open --json 调用会返回反馈，随后 Agent 修改文件，文件更新会实时反映在你的标签页中。

无需 Postgres、渲染令牌、OAuth 或网络连接。每次打开都会复用同一个已启动的后台守护进程（状态保存在 ~/.marigold-local/server.json），因此每次修订的成本只是写入一个文件。评论会保存在草稿旁边的 sidecar 文件 <file>.marigold.json 中 — 它会在交接事件触发之前写入，因此即使等待进程崩溃或守护进程重启，反馈也不会丢失。

使用与生产环境相同的锚定引擎（@marigold/core 的确定性 data-marigold-id 插桩和 resolveAnchor），因此评论会在不同修订版本间重新锚定，就地编辑会写回源文件，而升级到云端 Marigold 的草稿（使用相同 HTML 调用 create_doc）也会进行相同的插桩。

安装

npm i -g marigold-draft
marigold-draft agent-setup   # wires up Claude Code (skill) + Claude Desktop (MCP)

或者将此提示词交给你的编码 Agent：

请使用 npm i -g marigold-draft 为我安装 Marigold，然后阅读 https://marigold.page/draft/setup.md 并完成相关设置， 以便使用它。

如果直接使用 monorepo：运行 pnpm --filter marigold-draft build，然后将 packages/local/dist/cli.cjs 链接到你的 PATH 中。

工作循环（Agent 运行的内容）

# 1. write draft.html (full document or fragment — fragments get a neutral wrapper)
marigold-draft open draft.html --json          # opens the browser tab, BLOCKS
# 2. reviewer comments / edits in place / hits "Send feedback to agent"
#    → the open call prints the review JSON (openComments with anchoredText,
#      overallComment, per-comment replies) and exits
# 3. edit draft.html — the tab live-reloads, comments re-anchor
marigold-draft reply draft.html c1 "Bumped the chart to 34px"
marigold-draft resolve draft.html c1
# 4. next round (tab already connected, so no new browser tab):
marigold-draft open draft.html --json --no-browser

将阻塞的 open 作为后台进程运行；该进程退出即表示收到反馈。使用 --json 可保持 stdout 干净（状态会输出到 stderr）。 .svg 文件也可用 — 它们会内嵌到包装器中，因此每个元素都可评论。

分享并升级到托管版 Marigold

本地草稿不会离开你的设备。想要分享草稿时 — 发给其他人、在手机上打开，或只是保留 — 可将其升级到托管版 Marigold。分两步：

marigold-draft share draft.html          # prints a share link + a claim link
marigold-draft share draft.html --title "Q3 Review" --origin http://localhost:3000

1. 即时分享链接，无需账户。 share 会将草稿 POST 到托管版 Marigold 的快捷入口，并打印一个 URL，其中的 ?k= 就是访问凭证 — 任何拥有该链接的人都可以查看和评论。该链接仅供通过链接访问（不会列出），并会在最后一次写入约 30 天后过期。share 还会打印一个认领链接。
2. 保留草稿／控制访问权限。 打开认领链接并登录：文档会移入你的账户（快捷链接随即失效），之后你可以按查看者／评论者／编辑者角色通过电子邮件分享，并保留版本历史记录。若要让 Agent 持续处理已认领的文档，请将 Agent 指向托管版 MCP 端点 https://marigold.page/api/mcp。

share 默认使用文件的 <title>（或文件名）作为标题，并向 https://marigold.page 发送内容 — 可通过 --origin 或 MARIGOLD_ORIGIN 覆盖。本地评论仍保存在本地 sidecar 中；托管副本会在相同的锚定引擎上开启新讨论串，因此评论会像在本地一样，在不同修订版本间重新锚定。

CLI

open <file>       serve + open in browser, wait for feedback
                  --json --no-browser --no-wait --timeout <s> --title <t>
listen [path…]    stream submitted rounds as JSON lines; path args (files
                  and/or dirs) scope it to those drafts — scope it when
                  parallel agent sessions run at once (no paths = all drafts);
                  reconnects forever — run under a persistent monitor
share <file>      publish to hosted Marigold + print a share link and claim link
                  --title <t> --origin <url> (default marigold.page)
comments <file>   list threads               [--json]
reply <file> <id> <text…>    reply to a comment (badged AI in the UI)
resolve|reopen <file> <id>   set comment status
start | status | stop        manage the background daemon (default port 4747,
                             override with MARIGOLD_LOCAL_PORT or --port)
mcp               stdio MCP server for chat clients (see below)

MCP 服务（Claude Desktop 和其他聊天客户端）

marigold-draft mcp 通过 stdio 使用 MCP，适用于无法运行 shell 命令的客户端。工具包括：create_draft（输入 html → 将文件写入 ~/.marigold-local/drafts/ → 打开浏览器）、open_draft、update_draft（标签页实时重新加载）、get_feedback（设置 waitSeconds 后，会阻塞等待审阅者点击“Send feedback to agent”）、reply_to_comment、resolve_comment、read_draft。

Claude Desktop 注册配置（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "marigold-draft": {
      "command": "/opt/homebrew/bin/node",
      "args": ["<repo>/packages/local/dist/cli.cjs", "mcp"]
    }
  }
}

对于 Claude Code，marigold-draft 技能（~/.claude/skills/marigold-draft/）会教 Agent 使用 CLI 工作循环 — 在聊天中说“启动 marigold draft”即可完成整个流程。（该二进制程序同时响应 marigold-local 和 marigold-draft。）

其他编码助手

任何支持 MCP 的助手都可以驱动这一循环——服务会以 { command: "marigold-draft", args: ["mcp"] } 启动。任何能够运行 Shell 命令的助手也可以完全跳过 MCP，直接使用 CLI（添加 agent-setup 打印的 AGENTS.md 片段，让它了解这一循环）。 各助手的注册方式：

• Codex CLI — ~/.codex/config.toml：添加 [mcp_servers.marigold-draft]，并配置 command = "marigold-draft" 和 args = ["mcp"]（或运行 codex mcp add marigold-draft -- marigold-draft mcp）。会读取 AGENTS.md。
• opencode — opencode.json → "mcp"：{ "marigold-draft": { "type": "local", "command": ["marigold-draft", "mcp"], "enabled": true } }。会读取 AGENTS.md。
• Google Antigravity — Settings → Customizations → Open MCP Config (~/.gemini/config/mcp_config.json) → "mcpServers"：{ "marigold-draft": { "command": "marigold-draft", "args": ["mcp"] } }。会读取 AGENTS.md / .agents/rules/*.md。

GUI 应用可能无法继承你的 Shell PATH；如果服务无法启动，请使用 which marigold-draft 查到的绝对路径。可直接复制粘贴的完整配置片段和 AGENTS.md 代码块见： /draft/setup.md。

弹性

守护进程会持久化 docId→路径注册表（~/.marigold-local/docs.json），并按需延迟重新打开文档，因此浏览器标签页在守护进程重启后仍可使用；守护进程无法访问时，Shell 会显示内嵌横幅，并自动重新连接。评论保存在 sidecar 中，不会因守护进程而丢失。

工作原理

• 守护进程（src/server.ts）：在 127.0.0.1 上运行 node:http。监视每个已打开文件；文件发生更改时，重新植入标记、为每条评论重新定位锚点（marigoldId → css → textQuote，无法解析的评论会成为孤立评论），递增版本号，并向标签页推送 SSE reload。
• Shell（src/shell.ts）：生产环境查看器（apps/web/.../viewer-client.tsx）的原生 JavaScript 移植版——使用相同的 postMessage 协议、sandbox="allow-scripts" iframe 中相同的锚点 Agent，以及相同的 marigold 样式。框架使用与生产环境渲染源相同的 CSP，因此在本地正常运行的草稿，在云端 Marigold 中的呈现也完全相同。
• 交接：通过 GET /api/docs/:id/wait?since=<seq> 长轮询；发送反馈会将本轮反馈持久化到 sidecar，然后唤醒等待者。since 游标可避免提交先于等待发生所导致的竞态。
• 就地编辑（applyInlineEdits）会直接写入源文件；片段草稿会还原为片段，确保文件保持整洁。

测试

pnpm --filter @marigold/local test

遥测

marigold-draft 会针对五种操作发送匿名使用次数（draft.opened、 feedback.submitted、listen.started、share.cloud、agent-setup.run）。 每个事件的完整载荷如下：

{ "event": "draft.opened", "version": "0.9.0", "platform": "darwin", "nodeMajor": 22 }

不包含任何参数、路径、文件名、文档内容、主机名、用户名、语言区域或硬件信息，也不包含任何类型的客户端标识符：不会持久化任何信息来识别你的设备。近似独立计数来自请求 IP 的加盐、截断后的服务端哈希（无法还原，且不会存储原始地址）——与 marigold.page 上所有匿名数据采用相同的隐私保护方式。

可通过以下任一方式关闭（任选一种即可）：

• marigold-draft telemetry off（会持久化；也可使用 on / status）
• MARIGOLD_TELEMETRY=0
• DO_NOT_TRACK=1（console.dev 标准）
• CI 环境会自动跳过

MARIGOLD_TELEMETRY_DEBUG=1 会在发送每个载荷时将其打印到 stderr。 发送操作采用即发即弃方式，最长等待 1.5s，绝不会拖慢、阻塞或中断命令。实现位于 src/telemetry.ts——欢迎审查。如果将 MARIGOLD_ORIGIN 指向可自托管的实例，数据会发送到该实例，而非发送给我们。

许可证

MIT — 永久免费。请参阅 LICENSE。源代码位于 GitHub： github.com/immuneeb/marigold-collab （目录 packages/local）。