连接编码 Agent

完成一次本地授权与项目关联，指引 Claude Code、Cursor、Codex 等编码 Agent 精准对齐已发布的权威版本实现代码。

将外部编码 Agent 连接至 OriginAI，能确保其严格依据已发布的 Release 快照编写工程代码，彻底规避从碎片化聊天记录中胡乱猜度产品意图的风险。本指南介绍了面向所有 Agent 的标准化通用配置，以及主流客户端所需的专项适配细节。

开始前，请确认具备以下环境：一个已注册的 OriginAI 账户、一个已至少发布过一次 Release 的项目（推荐作为代码实现的基准源），以及支持运行 npx originai 的 Node.js 运行时。

通用集成三步走

以下操作流程适用于所有受支持的编码 Agent。

1. 本地设备授权（每台开发机仅需执行一次）

npx originai login
# 凭据将安全保存在 ~/.origin/settings.json 中 —— 切勿将其提交至 Git 仓库

2. 在本地代码仓库中关联 OriginAI 项目

cd your-app-repo
npx originai link --project <project-id>
# 根据需要追加标志：--skill / --claude-code / --codex / --cursor / --all

关联操作将生成：

.origin.json：包含 project_id、api_url 与当前的 release_hash，可安全提交至 Git。
可选的 Agent Skill 或工程指令提示词文件（取决于传入的命令参数）。

3. 验证环境与连通性

npx originai doctor
npx originai whoami

4. 拉取规格变更并开展代码实现

npx originai get-diff    # 查看统合规格差异（Diff）与对应内容；此命令不会推进指针
# 编码 Agent 对齐 Diff 编写与调整工程代码
npx originai sync        # 当代码实现已与规格完全匹配并通过测试后，推进 release_hash 指针

或者直接在会话中向 Agent 发送指令：“Read the OriginAI skill (or MCP tools) and implement the latest release.”

主流客户端专项配置

在完成上述通用的登录与项目关联后，不同客户端仅需极少量的针对性配置：

客户端	专属配置指引
Claude Code	从官方插件市场安装 Origin 插件。MCP 服务通过 `originai mcp` 本地运行（复用你的本地登录凭据）。
Cursor	执行 `link --cursor --skill`，随后运行 `originai mcp config --cursor` 完成配置。
Codex	执行 `link --codex --skill`；Agent 将通过 `AGENTS.md` 中的规范调用 CLI。
Pi / Hermes / OpenCode	执行 `link --skill` 安装 Agent Skill 规范与命令行工具。
skills.sh	从公开端点安装 Skill，随后仍需运行 `login` 与 `link` 完成本地授权与绑定。
CI/CD 持续集成	在环境变量中注入 `ORIGIN_TOKEN` 密钥——参见个人访问令牌。

完整客户端兼容性矩阵请参阅 MCP 与 Agent 安装参考。

集成成功的核心标志

编码 Agent 主动读取已发布的 Release 快照，杜绝从历史聊天中随意臆测。
本地 .origin.json 中的 release_hash 同步指针仅在代码真正实现并测试通过后（通过 sync）才向前推进。
在项目发布首个 Release 后，Agent 尝试发起的规格修改将自动暂存为变更请求，等待你在 Web 端确认应用。
日常开发中无需人工手动管理 export ORIGIN_TOKEN，单次 npx originai login 即可长效生效。

常见排查与处理建议

现象	原因分析与排查对策
读取 Release 快照返回 `404`	该项目尚未发布任何 Release 版本——在 Web 端发布首个版本，或使用 `--read-type workspace` 仅读取发布前的草稿索引。
写入操作返回 `suggested: true`	此为发布后的正常防护行为。Agent 应调用 `describe-proposal` 补充意图并执行 `submit-proposal`；你在 Web 端应用变更请求后再行发布。
写入操作返回 `403` 权限拒绝	属于非预期异常——请检查访问令牌的权限范围与项目协作者角色，而非旧版的发布锁定。
认证失败报错	重新执行 `npx originai login` 刷新凭据，或在 CI 环境中核验 `ORIGIN_TOKEN` 环境变量。
MCP 报告未授权	对于 Claude Code 插件，运行 `originai login` 后重启服务；若使用远程托管 MCP 主机，需显式配置 `ORIGIN_TOKEN`。
Agent 试图使用裸 `curl` 抓取	官方 Skill 明确禁止使用原始 HTTP 发送未授权请求——引导其改用标准的 MCP 工具或 CLI 命令。