Diagrid Catalyst

catalyst-ai

通过提示词构建和运行 Diagrid Catalyst — Dapr 工作流、持久化 Agent，以及正在运行的系统。

已在 Claude Code 中端到端验证 — 安装不到 5 秒，每项技能都会注册，而且提出一个真实的 Catalyst 问题时会触发正确的技能并获得有依据的回答。在 Codex 和 GitHub Copilot 中，安装及每项技能均已验证，并已确认 Codex 会将它们提供给模型；但目前尚未在这两者中获得针对 Catalyst 问题的回答，原因与各客户端已验证和未验证的内容无关。

早期版本。 这些技能通过远程 Catalyst MCP 服务驱动 Catalyst：你只需添加服务并登录一次。唯一的例外是应用隧道，它允许 Catalyst 调用你机器上的进程。没有 MCP 工具可以打开应用隧道，因此 catalyst-app-tunnels 会安装 Diagrid CLI，并仅用它来处理此事。请阅读当前可用功能，了解目前哪些功能可通过 MCP 使用，哪些尚不可用。

安装

Claude Code

claude plugin marketplace add diagridio/catalyst-ai
claude plugin install catalyst-ai@diagrid

然后检查是否已安装 — 两个命令都要运行，不能只运行第二个：

claude plugin list                           # expect Version: 0.7.0 or later
claude plugin details catalyst-ai@diagrid    # expect 12 skills

list 会报告你实际安装的版本。details 会报告市场正在提供的版本，只有两者一致时才会读取已安装的副本 — 因此单独运行时，它可能会显示你有 12 项技能，但你的会话实际加载了 11 项。如果其中任一项看起来不对，请跳转到如果你安装的版本落后。

然后登录 Catalyst MCP 服务

该插件还会注册 Catalyst MCP 服务：https://mcp.cloud.r1.diagrid.io/mcp。登录一次后，它才会开始工作。在 Claude Code 中，运行 /mcp，选择 plugin:catalyst-ai:catalyst 并完成浏览器登录。无需 API 密钥。

如果你之前已使用 claude mcp add 手动添加该服务，请在安装插件后移除该条目（claude mcp remove catalyst --scope user）。否则，每项 Catalyst 工具都会出现两份。

该插件会请求 catalyst:read catalyst:write offline_access 这些作用域。没有 offline_access 就不会有刷新令牌，因此每次会话过期时都需要重新登录。当你的角色为只读，或登录未授予写入作用域时，写入工具（例如 catalyst_apply）会完全从工具列表中移除。如果这些工具缺失，请重新登录并批准写入权限；如果仍然缺失，说明你的角色为只读。

可以通过提问来检查是否成功：“我在 Catalyst 中是谁？” 答案来自 catalyst_whoami。

将其他客户端连接到远程 MCP 服务

每个客户端都连接到同一个远程服务 https://mcp.cloud.r1.diagrid.io/mcp （必须包含 r1），并在浏览器中使用 OAuth 登录。授权服务不支持动态注册，因此 每个客户端都使用其已注册的客户端 ID：codex、copilot-cli、vscode 或 claude-code。

下面的每段配置还会设置 X-Catalyst-Plugin-Version 标头，以指定插件版本， 让服务知道客户端是依据哪个版本的说明进行设置的。该标头只会添加到客户端原本就会发送的 MCP 请求中。更新技能时， 请同步更新标头。

先为客户端安装技能（见下文），然后：

Codex

codex mcp add catalyst --url https://mcp.cloud.r1.diagrid.io/mcp --oauth-client-id codex
codex mcp login catalyst

codex mcp add 不支持标头参数，因此请将以下内容添加到它刚写入的 ~/.codex/config.toml 中的服务配置下：

[mcp_servers.catalyst.http_headers]
X-Catalyst-Plugin-Version = "0.7.3"

GitHub Copilot CLI

copilot mcp add 不支持客户端 ID 参数，因此请先添加服务，再在 ~/.copilot/mcp-config.json 中设置 oauthClientId：

{
  "mcpServers": {
    "catalyst": {
      "type": "http",
      "url": "https://mcp.cloud.r1.diagrid.io/mcp",
      "headers": { "X-Catalyst-Plugin-Version": "0.7.3" },
      "oauthClientId": "copilot-cli",
      "tools": ["*"]
    }
  }
}

然后在 Copilot 中运行 /mcp，并在浏览器中对 catalyst 服务进行身份验证。

VS Code（Copilot Chat），在 .vscode/mcp.json 或用户 MCP 配置中：

{
  "servers": {
    "catalyst": {
      "type": "http",
      "url": "https://mcp.cloud.r1.diagrid.io/mcp",
      "headers": { "X-Catalyst-Plugin-Version": "0.7.3" },
      "oauth": { "clientId": "vscode" }
    }
  }
}

首次连接时，VS Code 会打开浏览器进行授权。请参阅 VS Code MCP 配置参考。

其他客户端（Gemini CLI、Zed、Antigravity 等）：在该客户端自己的 MCP 设置中，将 URL 添加为远程 （可流式传输的 HTTP）MCP 服务，并使用其 MCP 登录功能。

该服务也已列入官方 MCP Registry，名称为 io.diagrid/catalyst （搜索注册表）， 因此支持基于注册表的服务目录的客户端可以在那里找到它。

GitHub Copilot（以及 Gemini CLI、Zed、Antigravity）

npx -y skills add diagridio/catalyst-ai --agent github-copilot --skill '*' --yes

如果要传入多个 Agent，请重复使用 --agent 标志。上游 README 中记录的逗号形式 （-a codex,github-copilot）会输出 Invalid agents:，不安装任何内容并以 1 退出——因此它会如实报告失败，检查退出代码的步骤也能捕获该问题。已在 1.5.22 和 1.5.23 上重新测量；本行的早期版本曾声称退出码为 0，这是测量错误。

真正会静默失败的情况是缺少 -y，且无人能响应提示，这适用于所有 CI 运行器：它会输出 Done!，不安装任何技能，并以 0 退出。请传入 -y，并断言技能数量，而不是检查退出代码。

这会将全部十二项技能写入 .agents/skills/，Copilot 自己的列表也确认它会读取这些技能：

copilot skill list        # all 12 under "Project skills"

Copilot 会在 .github/skills/、.agents/skills/ 和 .claude/skills/ 中查找项目技能，因此一个目录就够了。不要依赖 npx skills list 来验证这一点—— 它的“Agents:”行只会列出它检测到已安装在你机器上的 Agent，因此会悄悄漏掉尚未安装的客户端。

Codex

npx -y skills add diagridio/catalyst-ai --agent codex --skill '*' --yes

.agents/skills/ 也是 Codex 的项目技能目录——安装程序有意将 codex 映射到此目录，因此没有创建 .codex/ 是正确的，并非安装失败。 Codex 会读取这些技能：codex debug prompt-input 会呈现模型可见的提示词，所有技能 都会出现在它的 <skills_instructions> 块中，描述也会逐字节保持完整。 Codex 自己的指导文本说明，默认允许自动选择技能，因此你无需指定技能——不过目前还没有人通过实际会话确认这一点。

各客户端已验证和未验证的内容

	skills 安装	skills 注册	已回答问题
Claude Code 2.1.241	✅ 4.7 s	✅ 10/10	✅ 无需提示词就触发了正确的技能，并给出了有依据的回答
Codex 0.149.0	✅ 2.0 s	✅ 10/10，在模型可见的提示词中	尚未验证
GitHub Copilot 1.0.80	✅ 2.0 s	✅ 10/10	尚未验证

这些数据是在前十个技能上测得的。catalyst-app-tunnels 和 catalyst-agent-harness 尚未在这些客户端上重新测量。

如果你能让 Codex 或 Copilot 回答一个关于 Catalyst 的问题，这是你能报告的最有用的一件事——请提供你使用的措辞，以及触发了哪个技能。一个从未触发的技能，看起来和会话中没有出现任何相关内容完全一样，因此这需要人来验证，而不能只看安装程序的退出代码。

然后直接提问

刚接触 Catalyst？在 Claude Code 中，输入以下任一内容，即可端到端查看一次崩溃并恢复的过程。每个都是单行内容，无需粘贴多行：

• /catalyst-ai:try-workflow：一个持久工作流在运行中途崩溃，然后从停止的位置恢复。
• /catalyst-ai:try-agent：持久 AI Agent 的同一演示（使用 LangGraph，无需 API 密钥）。

在其他客户端中，粘贴 commands/ 中对应的提示词。文本完全相同。

之后，你无需学习命令。试试：

设置 Diagrid Catalyst，然后展示我的项目中有什么。

或

在此仓库中添加一个工作流，用于扣款、预订房间，并在预订失败时进行补偿。

或

我的工作流运行失败了。为什么？

技能会根据你的提问自动触发。你不应该需要指定某个技能——如果你发现自己不得不这么做，那就值得报告这个问题（参见反馈）。

包含的内容

技能	用途
catalyst-setup	将此会话连接到 Catalyst，并确认连接正常
catalyst-workflow-scaffold	添加一个 Dapr Workflow——编排器、活动和项目接线
catalyst-workflow-from-diagram	将流程图、时序图、BPMN 文件或白板照片转换为工作流
catalyst-agent-scaffold	将持久 Agent 搭建为你自己的应用，并由 Catalyst Agent 提供前端
catalyst-agent-harness	让你自己的 Agent 循环具备持久性——每次模型调用和工具调用都作为独立活动
catalyst-develop	针对实时 Catalyst 基础设施进行“编辑 → 重新运行 → 观察”循环
catalyst-app-tunnels	让 Catalyst 调用你机器上的进程：应用间调用、发布/订阅消息投递，以及 Agent 调用你在本地运行的 MCP 服务
catalyst-deploy	将应用从笔记本电脑迁移到 Catalyst
catalyst-operate	只读检查正在运行的项目
catalyst-debug	诊断问题所在
catalyst-workflow-determinism	为编排器主体提供安全重放保障
catalyst-activity-idempotency	让活动可以安全地运行两次

语言和框架会自动检测，而非询问。没有 catalyst-workflow-python 技能——工作流技能会读取你的仓库，并判断它是 Python 项目。

成本：十二个技能总计约 1240 个常驻 token（每个约 103 个，根据前十个技能估算），无论是否触发技能，都会计入每次会话。只有技能实际触发时，每个技能才会额外消耗几千个 token。这个数字因模型而异——claude plugin details 会根据你当前使用的模型选择分词器，因此同样的十个描述在 Sonnet 5 和 Opus 5 上每个约需 103 个 token，在 Haiku 4.5 上每个约需 68 个 token。引用这个数字时请注明模型，否则结果无法复现。

当前可用功能

明确说明这一点很重要，因为这里的差距不容忽视，你也会注意到：

	状态
编写 — 工作流、Agent	✅ 目前可用
运维 — 检查、调试、读取运行记录	✅ 目前可用，通过 MCP 服务
确定性和幂等性审查	✅ 目前可用
创建、更改、删除和部署资源	✅ catalyst_apply 和 catalyst_delete_resource，适用于有写入权限的角色
工作流运行操作和访问控制	✅ 适用于有写入权限的角色
在本地运行你的应用、Agent 或 MCP 服务，并调用 Catalyst	✅ 目前可用，通过 catalyst_get_connection
让 Catalyst 调用你机器上的进程 — 调用目标、订阅者、Agent 端点、MCPServer 背后的 MCP 服务 — 并打印入站请求	✅ 通过应用隧道，这是唯一需要使用 Diagrid CLI（catalyst-app-tunnels）的步骤
Agent 通过 Catalyst 的工作流路径调用你机器上的 MCP 服务（dapr.internal.mcp.* 子工作流）	⛔ 工作流路径目前还无法访问隧道中的 MCP 服务；技能会引导 Agent 使用 Catalyst 的 HTTP MCP 端点，该端点可以正常工作
日志	⚠️ catalyst_get_logs 仅在 full 数据共享级别下可用，且只能读取 sidecar 的 API 调用
调用应用、发布、读取或写入状态、集群诊断	⛔ 目前无法通过 MCP 使用

如果某项功能目前无法通过 MCP 使用，技能会用一句话说明，而不是临时拼凑解决方案。如果缺少写入工具，说明你的角色是只读的，而非连接出了问题。

技能中包含但你可能不知道的信息

这些内容已经包含在技能中；列在这里是因为它们曾让人耗费数小时，而且都会悄无声息地失败，或只给出无用的错误信息。

• 不要创建项目。 你的组织已经有一个 default 项目，它在注册时就已配置，其中包含托管式 pub/sub、KV、工作流存储和 Agent 基础设施。批次中的 Project 清单会创建它所命名的项目，而项目数量受每个区域的上限限制；你可以通过 catalyst_get_usage 查看上限。
• 每个项目只有一个 pub/sub 和一个 KV 存储，适用于所有套餐，免费和付费套餐都一样，因此升级套餐也不会增加第二个。同一个多 Agent 拓扑会让多个主题共用一个 pub/sub。这些是按组织覆盖设置的套餐值，并非代码中的常量，因此技能会读取实时配额，而不是断言上限为 1。
• Agent 面向的是你的应用。 它接收端点和归档设置，而不是模型设置 — 如果你在找大模型设置，说明找错了资源。
• 在应用创建之前启用托管式工作流存储。 sidecar 会在启动时读取工作流配置，因此之后再启用，会导致永远无法补齐配置的 sidecar 处于 FAILED_PRECONDITION 状态。
• 必须先创建 Agent 或 MCP 服务，再创建任何同名对象。 它不会接管不属于它的身份，之后会一直处于错误状态。
• 身份按区域在整个组织范围内计数 — 每个应用、Agent 和 MCP 服务各占一个名额，都从同一个配额中扣除 — 因此将拓扑拆分到多个项目也毫无帮助。
• 不存在不等于为空。 在默认的 metadata 数据共享级别下，工作流的 input、output 和 customStatus 是不提供的，而非为空。没有显示输出的运行记录，实际可能已经产生了大量输出。
• 连接值仅供本地开发使用。 已部署的应用会从平台获取自己的连接值。连接值应直接写在启动命令中、放入应用文件夹中被 git 忽略的 .env 文件，或通过工具的环境选项传入，绝不能放进聊天、拉取请求或提交中。
• 除打开应用隧道外，技能会将 Catalyst 中的所有操作都交给 Catalyst MCP 工具处理。 打开应用隧道时绝不使用公共隧道（cloudflared、ngrok）：那会绕过 App ID 的身份验证和访问策略。

如果安装版本落后

这里有两种不同的问题，修复方法也不同。先运行 claude plugin list，因为这个命令会报告你实际安装的内容。

你的版本早于 main。 市场目录是一个 Git 克隆，固定在上次获取时的提交，因此上周安装的版本仍是上周的版本，技能也停留在上周的状态。claude plugin install 不会更新它——该命令会报告“已安装”，并且不会做任何更改：

claude plugin marketplace update diagrid
claude plugin update catalyst-ai@diagrid     # the command that actually upgrades
claude plugin list                           # expect Version: 0.7.0 or later

你的版本正确，但缺少技能。 Claude Code 会将插件缓存到其声明的版本目录 ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ 下，并且不会刷新已有的版本目录。实测：一个内容不完整的版本目录只提供了 10 个技能中的 4 个，而 marketplace update 和 plugin install 都报告成功，却没有修复任何问题。删除该目录是唯一的修复方法：

rm -rf ~/.claude/plugins/cache/diagrid/catalyst-ai
claude plugin install catalyst-ai@diagrid
claude plugin details catalyst-ai@diagrid    # expect 12 skills

现在，CI 会对未提升版本号却更改了插件内容的提交报错，因此第二种情况应该不会再出现。

反馈

最有帮助的反馈是本应触发却未触发的技能，并附上你使用的准确措辞。我们无法从这一侧看到这种失效——它看起来和没有发生任何相关操作的会话完全一样，而具体措辞是诊断问题的关键。

以下情况也值得反馈，按价值大致排序：

1. 技能提到的工具不存在或无法使用。CI 会根据 contracts/catalyst-mcp-tools.txt 检查每个 catalyst_* 名称，因此不匹配意味着服务发生了变化，或者检查存在漏洞。两种情况都值得发现。
2. 本应触发另一个技能时，触发了其他技能。
3. 技能告诉你的任何后来证实有误的信息。

请在此仓库中提交 issue。

如果遇到安全问题，请勿提交 issue。请参阅 SECURITY.md。

贡献

每个 PR 都会运行门禁检查，每项检查都有自己的测试套件。它们之所以存在，是因为实际中曾有问题通过了评审或 claude plugin validate --strict：

python3 scripts/lint_skills.py            # the real gate
python3 scripts/test_lint_skills.py       # proves the gate still catches what it claims
python3 scripts/check_mcp_surface.py      # tools, CLI and hosts, across skills, evals and README
python3 scripts/test_check_mcp_surface.py
python3 scripts/check_version_bump.py     # a plugin change must bump the version
python3 scripts/test_check_version_bump.py
python3 scripts/check_plugin_version_header.py   # the MCP version header matches the plugin version
python3 scripts/test_check_plugin_version_header.py
python3 scripts/check_server_json.py      # server.json: registry name, and the same URL as the plugin
python3 scripts/test_check_server_json.py
python3 scripts/test_plan_registry_version.py   # the MCP Registry version planner
python3 scripts/build_install_data.py --check   # web/install/ data matches commands/ and this README
(cd web/install && npm test)

web/install/ 是 npm 包 @diagrid/catalyst-ai-install，这是一个供文档和网站使用的 <catalyst-ai-install> Web 组件。其数据由脚本生成：更改 commands/ 或此处的安装步骤后，运行 python3 scripts/build_install_data.py 并提交生成的结果。

lint_skills.py 会检查客户端实际需要的内容：name 与其目录名一致、描述可解析且少于 260 个字符、frontmatter 符合允许列表、没有 ../ 链接、技能单独安装时每个链接都能解析，以及任意两条描述之间的相似度不得超过 0.20，避免多个技能争用同一个触发条件。它还会禁止一组曾在某处发布并造成问题的子字符串。

check_mcp_surface.py 会核对技能、评估用例和本 README 与远程 MCP 接口的一致性。每个 catalyst_* 名称都必须出现在 contracts/catalyst-mcp-tools.txt 中；该文件是服务端 tools/list 返回内容的副本，服务端工具列表变更时请更新它。此门禁还会拦截任何 Diagrid CLI 调用（隧道命令除外：仅允许在 skills/catalyst-app-tunnels/ 和 evals/tunnel-*/ 中使用安装检查、登录和两个隧道命令）、任何指向非远程服务的内容，以及任何属于 Diagrid 域名但不在允许列表中的主机（MCP 服务、控制台、文档和下载主机，以及主站）。 工具名称不区分大小写。技能只能通过远程 MCP 服务驱动 Catalyst，因此，如果某项功能没有对应工具，技能会说明该功能目前无法通过 MCP 使用，而不会尝试其他方式。

如果新增技能或更改任何技能的内容，请提升 .claude-plugin/plugin.json 中的 version。否则，已安装的用户会继续使用旧内容，而且不会收到任何提示。每次提升版本号都会更改 X-Catalyst-Plugin-Version 标头：请在 plugin.json 的 mcpServers.catalyst.headers 中将其设为新版本，并更新此处安装步骤下的三个代码片段（Codex、Copilot CLI 和 VS Code），以及 skills/catalyst-setup/SKILL.md 中相同的三处配置（check_plugin_version_header.py 会检查这两处）。然后运行 python3 scripts/build_install_data.py 并提交生成的结果。

许可证

Apache-2.0。参见 LICENSE。