首页
Agentour 开发者文档
进入控制台

Agentour 开发者文档

这份文档面向希望把 Agent 发布到 Agentour 的开发者。你可以从一个想法开始，也可以把现有 Agent 项目转换为 Agentour Package。

先选对工具：Claude Code Plugin 和 Codex Plugin 是两个独立产品。 它们使用不同的安装机制、目录结构和调用方式，但最终生成同一种 Agentour Package，并遵守相同的验证、审批、运行状态和还原度要求。

两种 Plugin 怎么选

你正在使用应安装使用入口官方仓库
Anthropic Claude CodeAgentour Compiler for Claude CodeClaude Code 中运行 /agentour-compileragentour-claudecode-plugin
OpenAI Codex / ChatGPT desktop CodexAgentour Compiler for Codex直接用自然语言描述要创建或转换的 Agentagentour-codex-plugin

两者不要交叉安装。Claude 版的 plugin.json、commands 和 agents 不能直接当作 Codex Plugin 使用；Codex 版要求 .codex-plugin/plugin.json、skills 以及 Marketplace 清单。

相关资料：

A. Claude Code Plugin 完整指南

A1. 适用场景

选择 Claude Code 版，如果你已经在终端中使用 Claude Code，并希望通过 slash command 完成以下工作：

  • 从零访谈并创建 Agent；
  • 扫描已有项目并转换为 Agentour Package；
  • 生成 Package、锁文件和 Smoke Test；
  • 运行 Agentour Validator，修复 Gate 问题；
  • 经你确认后上传到指定 Agentour 平台。

源码、版本与问题反馈都在 Claude Plugin 仓库。

A2. 前置条件

  1. 已安装 Claude Code。
  2. 能在目标 Agent 项目目录中启动 Claude Code。
  3. 知道目标 Agentour 平台地址。
  4. 只有需要发布时，才需要 Agentour 开发者令牌。

检查 Claude Code：

claude --version

A3. 从 Marketplace 安装

在 Claude Code 会话中依次执行：

/plugin marketplace add agentour-platform https://github.com/Onesyn-ai/agentour-claudecode-plugin
/plugin install agentour-compiler@agentour-platform

安装完成后重新打开一个 Claude Code 会话，再运行：

/agentour-compiler

如果命令没有出现，先查看 Claude Code 的 Plugin 列表，确认 Marketplace 名为 agentour-platform，Plugin 名为 agentour-compiler。升级时从同一 Marketplace 更新，不要同时保留手工复制的旧版本。

A4. 启动后的固定流程

Plugin 不要求用户配置 URL。第一轮只选择一个平台：测试服（https://test.agentour.ai）或 正式服（https://agentour.ai）。第二轮只输入该平台生成的 at_ 开发者令牌。

Plugin 启动时先检查 Marketplace 最新版本并自动升级。随后使用 GET /v1/dev/me 校验令牌；失败时停在这一轮，让用户检查并重新输入。成功后从所选平台的 GET /v1/models 拉取候选模型，再逐一调用模型探针并过滤不可用模型，最后才询问是重构已有 Agent 还是从零发明。

令牌只用于当前流程的校验和上传，不写入项目、Package、日志或还原度报告。

A5. 从零创建 Agent

在目标项目目录启动 Claude Code，然后运行：

/agentour-compiler

完成平台、令牌和来源选择后选择“从零创建”。Plugin 会通过内部 brainstorm 与 grill-me 多轮确认领域、用户、输入、输出、业务流程、确定性工具、外部系统、审批点、模型和定价，并维护 AGENT_SPEC.md。

每轮只允许问一个问题或做一个选择，不能让用户一次回答一张问卷。即使需要多个输入样例，也必须分轮收集。

在 Plugin 展示设计摘要前，不应急于生成代码。生成后至少检查 agentour.json、README.md、tests/smoke.yaml 和 payload/agent/instructions.md。

A6. 转换已有 Agent

在现有 Agent 仓库根目录运行 /agentour-compiler，选择“已有 Agent”。转换前会扫描入口、所有 Agent、Prompt、Skills、Tools、MCP、子 Agent、Workflow、依赖、环境变量、附件、文件读写、审批和交付物。

如果项目包含多个 Agent，Plugin 会单独询问：合成一个 Package、全部分别转换上传，还是只选其中一个或几个。这个范围选择完成后才继续逐轮访谈。

转换不能只以“能 build”为成功标准。至少要生成能力清单、转换映射和还原度报告，并对原 Agent 与 Agentour Package 使用相同测试用例。任何关键 Tool、审批边界、附件解析、输出 Schema 或交付物失败，都应阻止自动发布。

A7. Claude 版常见问题

  • /agentour-compiler 不存在：确认 Plugin 已安装，并新建 Claude Code 会话。
  • 令牌校验失败：确认令牌来自当前选择的平台，并在该平台控制台重新生成。
  • 模型列表请求失败：先确认所选平台可访问，再直接请求该平台的 /v1/models。
  • Validator 失败：把完整 Gate 报告交给 Plugin 修复，不要删除失败测试。
  • 准备发布但没有令牌：登录 Agentour 控制台发布页生成。

B. Codex Plugin 完整指南

B1. 它和 Claude 版有什么不同

Codex 版是原生 Codex Plugin，清单位于 .codex-plugin/plugin.json。它只向用户暴露一个自动入口：用户描述目标后，Plugin 自己完成需求发现、AGENT_SPEC.md、创建或转换、验证修复、还原度检查和发布准备。用户不需要知道或指定内部 Skill。

仓库包含 .agents/plugins/marketplace.json，Marketplace 名为 agentour-platform。查看源码与更新记录：agentour-codex-plugin。

B2. 添加 Marketplace

在终端执行：

codex plugin marketplace add Onesyn-ai/agentour-codex-plugin
codex plugin marketplace list

第二条命令应能看到 agentour-platform Marketplace。根据 Codex 官方机制，CLI 用于添加和维护 Marketplace；Plugin 的浏览、安装和启用在 ChatGPT desktop app / Codex 的 Plugin 目录中完成。不要依赖未经官方文档确认的 codex plugin add 命令。

打开 Plugin 目录，选择 Agentour Platform Marketplace，安装 Agentour Compiler。安装或升级后新建一个任务/Thread，使新 Skills 生效。官方说明见 Build plugins 和 Plugins。

升级 Marketplace：

codex plugin marketplace upgrade agentour-platform

移除 Marketplace：

codex plugin marketplace remove agentour-platform

B3. 平台选择与令牌校验

Codex Plugin 同样内置两个固定目标：测试服（https://test.agentour.ai）和 正式服（https://agentour.ai）。用户第一轮只选平台，第二轮只输入该平台的 at_ 开发者令牌。

Plugin 先调用 GET /v1/dev/me 验证令牌。验证失败就要求用户检查后重输；验证成功才调用 GET /v1/models。令牌在 控制台发布页生成，只显示一次，不能写入仓库、Package、Prompt、日志或报告。

B4. 从零创建 Agent

新建 Codex 任务后直接描述目标，不要指定 Skill：

帮我做一个可以发布到 Agentour 的合同审核 Agent。你负责完整推进，只在确实无法判断时问我，先不要发布。

Plugin 会自动建立规格并多轮推进。每轮严格只问一个问题或要求一个选择，通过内部 brainstorm 与 grill-me 消除偏差；信息足够后自动进入实现、验证和修复。

B5. 转换已有 Agent

在已有仓库中启动 Codex，并输入：

把当前项目里的 Agent 自动转换成 Agentour Package。保留原项目不动，完成能力盘点、原版与转换版对比、还原度报告和全部验证，先不要发布。你负责完整推进，只在确实无法判断时问我。

Codex 版会生成：

.agentour/
├── conversion-inventory.json
├── conversion-map.json
└── fidelity-report.json

报告必须把能力标为 preserved、adapted、reimplemented、degraded、unsupported 或经明确同意的 removed。不能静默删除源 Agent 的能力。多 Agent 项目必须先询问合并、全部拆分还是选择部分。

B6. 检查并修复 Package

检查并修好 packages/my-agent，自动运行全部验证，直到达到可发布状态；不要为了通过而修改或删除有效测试。

Plugin 会在内部完成 Validator 阶段，检查 Package 结构、锁文件、模型路由、运行状态、审批语义、Secret、Smoke Test、构建结果，以及转换场景中的还原度报告与 Package SHA-256 绑定。失败时应自己修复并重跑，而不是把报告作为作业交给用户。

B7. Codex 版常见问题

  • Marketplace 已添加但看不到 Plugin：刷新或重启 ChatGPT desktop app，再从 Plugin 目录选择 Marketplace。
  • Skills 未生效：安装或升级后新建任务，不要只继续旧 Thread。
  • 令牌校验失败：确认令牌属于当前选择的平台，且是 at_ 开发者令牌，不是登录 token。
  • 转换分数高但仍被阻止：关键能力失败优先级高于总分，这是预期行为。

C. 两种 Plugin 共同遵守的发布流程

C1. Package 最小结构

packages/<agent-id>/
├── agentour.json
├── README.md
├── RELEASE.md
├── tests/smoke.yaml
└── payload/
    ├── package.json
    ├── pnpm-lock.yaml
    └── agent/
        ├── agent.ts
        ├── instructions.md
        ├── sandbox/sandbox.ts
        ├── tools/
        └── skills/

详细规范可继续查看平台仓库中的 Package Authoring、Plugin 协议 和 API Reference。

C2. 用户可理解的运行状态

Package 必须在 agentour.json 为真实能力配置用户文案。内部动作 load skill 不能直接显示给用户，应显示“正在加载合同风险识别能力…”之类的业务语言。

waiting_approval 表示 Agent 已暂停并等待用户，页面必须显示“等待审批”，不能显示“正在执行”。Plugin 和 Validator 都应强制检查。

C3. Token、上下文与长任务

Agentour 记录 token 用量用于计费与观察，但平台不应因为单轮输出 token、每日 token 或固定总运行时长中断 Agent 或 Workflow，也不应静默截断附件和工作流中间结果。

仍然存在无法凭软件消除的物理边界：所选模型的上下文窗口、上游模型服务可用性、ECS 内存、磁盘和网络。平台会隐藏已确认不可用的模型，Plugin 还必须从所选平台的 GET /v1/models 读取 canonical 模型并逐一通过 POST /v1/dev/model-probe/{model_id} 后再生成；处理超大文档时应设计分块、索引或分阶段汇总。

C4. 发布前检查

发布前必须展示并确认：目标平台、Agent ID、版本、模型、公开/私有、验证结果、还原度等级、降级项和不支持项。

推荐异步发布接口：

方法地址用途
GET/v1/models获取目标平台公开可用模型
POST/v1/dev/publish-async创建异步发布任务
GET/v1/dev/publish-jobs/{job_id}查询发布进度与 Gate 结果
POST/v1/dev/publish同步发布，适合小包或调试
GET/v1/dev/plugins查询平台公布的两种 Plugin 仓库
GET/v1/dev/compiler-contract获取当前平台编译协议
POST/v1/dev/model-probe/{model_id}验证模型可真实回复
POST/v1/dev/feedback上传发布后的平台与 Plugin 问题 Markdown

手工发布示例：

tar czf package.tgz --exclude='payload/node_modules' -C packages/my-agent .

curl -fsS \
  -H "Authorization: Bearer $AGENTOUR_TOKEN" \
  -H "Content-Type: application/gzip" \
  --data-binary @package.tgz \
  "$AGENTOUR_URL/v1/dev/publish-async"

公开 Agent 通过自动 Gate 后仍需管理员审核；私有 Agent 仅自己可见，可以使用 ?visibility=private。

C5. 发布成功的最低标准

  • Package 构建成功且 Smoke Test 通过；
  • 没有 Secret 或错误的 localhost 回退；
  • 所有副作用 Tool 都声明审批；
  • 所有实际能力都有用户可理解的状态文案；
  • 等待审批时状态准确；
  • 转换项目有完整能力清单、映射和还原度报告；
  • Agent/Workflow 能完成长任务，不被平台 token 配额或固定运行时长人为中断；
  • 目标平台、版本和可见性已经由开发者确认。

C6. 发布后的反馈闭环

Agent 成功部署后，Plugin 必须生成 问题梳理与优化意见清单.md 并用同一个开发者令牌上传到所选平台的 POST /v1/dev/feedback。报告只分析平台能力和 Plugin 设计问题，不把普通 Agent 业务缺陷混入其中。管理员可以在控制台“反馈”Tab 中统一阅读和下载这些 Markdown。