Work With Alloy

使用 Alloy

关于 Alloy

Alloy 是一个 AI 原生工作空间，让团队与 AI Agent 协作——在统一的基础上共享产物、知识、技能和对外部系统的访问权限。连接 Claude、Codex 或 Gemini，或者启动 Alloy 云端 Agent，让它们与彼此及团队成员协同工作。

在 alloy.cx 免费开始 · 文档：alloy.cx/docs

---

此插件可教会任何 AI Agent 将 Alloy 用作真实信息来源，并为其提供可重复使用的 Alloy 专属操作技能——回答前先阅读共享知识、撰写持久化笔记和产物、创建工作流、执行运营审核，以及启动自主 Agent。

共享的真实信息来源是 work-with-alloy 技能。各平台专属的 插件清单只是对相同技能内容的轻量封装。

使用场景

将 Alloy 用作 AI Agent 与人类及其他 Agent 协作的共享工作层，包括 Claude、Codex、Alloy 云端 Agent 和其他 AI Agent。

• 回答前阅读共享的组织知识：公司文档、决策、知识笔记、沟通历史，以及所有 AI Agent 和人类维护的上下文。
• 将持久化产物写回 Alloy：提案、研究、摘要、规范、日志、决策和可供未来 Agent 使用的可重复利用笔记。
• 通过 Alloy 管控的 MCP 访问获准的业务系统：Agent 只需连接一次 Alloy，之后由 Alloy 管理可用的上游 MCP、API、文件、密钥和操作。
• 跨已连接的工具开展工作，无需每个 Agent 单独配置所有集成：CRM、支持、文档、日历、电子邮件、数据库、内部系统和私有网关。
• 调用 Alloy 云端 AI Agent 执行委派任务，然后根据其输出和产物继续工作。
• 创建或配置 Alloy AI 团队成员、指令技能和可执行工作流，让可重复的工作成为受管控的组织流程。
• 协调多 Agent 操作，让 AI Agent 通过 MCP/API 触发器交接任务。
• 让组织经验能够在不同 Agent 间迁移：知识、产物、访问规则和审计记录。

目录结构

• skills/work-with-alloy/ - 核心真实信息来源技能。
• skills/review-alloy-operations/ - 用于审核团队成员、指令技能、工作流、MCP 和近期活动的运营审核技能。
• skills/*/references/ - 各技能加载的配套操作指南。
• skills/*/agents/openai.yaml - Codex/OpenAI 技能 UI 元数据。
• skills/work-with-alloy/assets/ - 共享技能 UI 资源，例如 Alloy 图标。
• .codex-plugin/plugin.json - Codex 插件清单。
• .claude-plugin/plugin.json - Claude Code 插件清单。
• .mcp.json - 使用 ALLOY_TOKEN 的 Alloy 托管 MCP 配置。

共享技能

skills/ 下的技能旨在保持与宿主无关。请在此处更新共享技能内容，而不要分别维护 Claude 和 Codex 的指令目录树。

前置条件

以下要求适用于将插件安装到 Claude Code 或 Codex 的所有用户。

1. ALLOY_TOKEN 环境变量

随附的 .mcp.json 会从 ALLOY_TOKEN 读取 Alloy MCP bearer。启动 Claude Code 或 Codex 前，请在宿主 Shell 中导出该变量：

export ALLOY_TOKEN="<your-alloy-token>"

请访问 https://alloy.cx/docs/reference/tech-docs/hosted-mcp 获取令牌。

2. 安装后重启宿主

插件的 MCP 服务会在宿主启动时加载。安装或更新插件后，请重启宿主，以便加载随附的 MCP 配置。

Codex

Codex 插件清单引用了 ./skills/ 和 ./.mcp.json。

使用捆绑的 MCP 配置前，请在宿主环境中设置 ALLOY_TOKEN。

Marketplace 注册和 app-server 安装已通过 Codex 0.125.0 验证：

codex plugin marketplace add Alloy-Systems/alloy-marketplace

Codex 会从指向带标签版本的 Marketplace 条目安装 work-with-alloy。安装后，Codex 会报告该插件已启用，并提供 work-with-alloy:work-with-alloy 技能以及捆绑的 alloy MCP 服务。

Claude Code

Claude 插件清单 .claude-plugin/plugin.json 引用的 ./skills/ 和 ./.mcp.json 与 Codex 端相同。Alloy Marketplace 发布后，安装流程如下：

/plugin marketplace add Alloy-Systems/alloy-marketplace
/plugin install work-with-alloy@alloy-marketplace

Claude Code 的插件安装程序默认通过 SSH 从 GitHub 克隆插件源代码。运行 /plugin install 前，请确保满足以下任一条件：

• 此机器上有可用的 GitHub SSH 密钥（测试：ssh -T [email protected]）。

• 配置全局 git URL 重写规则，通过 HTTPS 克隆插件：

  git config --global url."https://github.com/".insteadOf "[email protected]:"
  

使用捆绑的 MCP 配置前，请在宿主环境中设置 ALLOY_TOKEN。

安装后，重启 Claude Code 并确认注册：

claude mcp list   # expect plugin:work-with-alloy:alloy as connected

版本策略

本项目遵循语义化版本控制，Claude Code 和 Codex 包装器同步发布。单个版本适用于整个发布内容：skills/work-with-alloy/ 中的共享技能内容、两个 plugin.json 清单、.mcp.json 配置以及本 README。.codex-plugin/plugin.json 和 .claude-plugin/plugin.json 始终使用相同的 version 字段。

此插件的 Semver 语义

版本变更	含义	示例
补丁（0.1.0 → 0.1.1）	仅涉及外观。错别字、措辞调整、失效链接、说明澄清。不会改变 Agent 的行为。	修正 SKILL.md 中的错别字。更新 references/ 中过时的 URL。
次要（0.1.0 → 0.2.0）	向后兼容的新增内容。新规则、新的快速参考表行、新的参考操作手册、新的可选清单字段。之前的用法仍然有效。	在核心规则中添加新规则。在快速参考表中添加新条目。在 references/ 下添加新的操作手册。
主要（0.x → 1.0，1.x → 2.x）	不兼容变更。规范路径、文件名、必填字段或必需规则发生变更，可能导致现有使用方无法继续使用。	将 Personal/<username>/.knowledge/knowledge.md 重命名为其他路径。删除一条核心规则。重构 references/，导致现有链接失效。

1.0 之前的版本（0.x）表示“仍在稳定过程中——次要版本升级可能包含不兼容变更”。确认规范路径和核心规则稳定后，将发布 1.0.0 系列。

发布流程

1. 工作在功能分支上进行，再通过 PR 合并到 main。
2. 当 main 达到值得发布的状态时，在同一次提交中升级 .codex-plugin/plugin.json 和 .claude-plugin/plugin.json 的 version 字段。
3. 在合并提交上创建 git 标签：git tag vX.Y.Z && git push origin vX.Y.Z。
4. 在 Alloy-Systems/alloy-marketplace 仓库的 marketplace.json 中，升级 work-with-alloy 条目对应的 ref 字段。只有在 Marketplace 更新后，用户才能通过 /plugin update 获取新版本。
5. 未打标签的 main 提交对阅读仓库的任何人可见，但在 Marketplace 指向新标签之前，不会通过 /plugin install 或 /plugin update 分发。

发布节奏

按逻辑版本发布标签，而不是每次提交都发布。典型的触发条件包括：新增一条核心规则、新增一本参考操作手册，或者完成一项不兼容的重构并准备发布。纯外观变更可以累积在 main 中，方便时再作为补丁版本发布。

许可证

Apache License 2.0。