本页面是为 AI 助手编写的操作手册:包括Claude Code、Codex、Cursor,或任何能够读取网页内容且理想情况下可在本地代码库副本中工作的助手。该手册会引导助手为一个或多个代码仓库配置 CoRoid。所有需要人工操作的一步都会暂停,例如登录、授予访问权限、输入密钥或审批变更。
将其交给你的助手
在希望 CoRoid 工作的代码仓库中打开你的助手,并向其发送以下提示词:
Set up CoRoid for this repository. Follow the runbook at
https://coroid.ai/docs/export/en-US/getting-started/assistant-setup.md
step by step. Ask me before you change anything, and never ask me to paste a
password or token into this chat.对于多个代码库,可在包含它们的目录下打开助手,并在提示词中注明这些代码库名称。助手会负责检查和验证,并明确告知你在每一步需要做什么。
助手的基本原则
你正在搭建 CoRoid,一个托管的 AI 软件工厂。项目设置完成后,公司内的任何人员都可以用自然语言描述工作任务,而 CoRoid 会按照项目标准完成编译、测试和评审,并在用户的代码仓库中创建 pull request。请全程遵守以下规则:
- 用户执行操作,你负责准备。你无法替用户注册、登录、接受条款、安装应用或授予访问权限。请准确说明操作步骤和位置,然后等待用户确认已完成。
- 切勿在对话中提及密钥信息。切勿索要密码、个人访问令牌、服务商密钥或MCP令牌。用户需将密钥输入到 CoRoid 门户或其本地Shell中。如果有人仍将这些密钥粘贴到聊天窗口,请告知用户立即撤销并重新生成新密钥。
- 每次变更前都要询问包括用户代码仓库中的提交、分支和拉取请求,CoRoid 项目以及相关邀请。
- 每完成一步后,再进入下一步。若某步检查未通过,请参考该步骤中的说明,仅在该步通过或用户决定跳过时方可继续。
- 遵循产品实际行为,而非凭主观猜测。若门户显示的内容与本操作指南描述不符,请告知用户你所看到的情况并按门户提示操作。切勿自行编造设置项。
- 记录配置过程记录每一步及其结果,以备后续查阅。
每一步都链接到对应的详细说明页面。https://coroid.ai/llms.txt用于索引整个文档内容。
步骤 1:确定方案
请一次性向用户提出以下问题,不要逐个询问:
| 问题 | 为何重要 |
|---|---|
| CoRoid 应针对哪些代码仓库开展工作? | 一个代码库对应一个项目。 |
| GitHub 还是 GitLab?归个人还是组织所有? | 确定 CoRoid 的连接方式以及审批人。 |
| CoRoid 是否应创建拉取请求(已同步),还是先让工作保留在 CoRoid 内部(仅本地)? | 仅本地模式绝不会向代码库写入任何内容。 |
| 是否已经存在 CoRoid 组织,它采用何种套餐? | 免费版仅支持一个项目且无法添加其他成员。 |
| 还有谁会审核相关工作,其角色是什么? | 邀请成员需使用专业版计划。 |
| CoRoid 是否应使用该组织自身的模型服务商密钥? | 可选。通过 CoRoid 路由的模型无需此类密钥。 |
随后复述一遍方案:包括下方的操作步骤、需要用户参与的部分以及涉及的代码库范围。
步骤 2:检查每个代码库是否能从干净克隆版本中完成构建和测试
这是你能完成的最有价值的工作。每个 CoRoid 任务都在一个干净且可丢弃的Linux工作空间中运行:全新的代码克隆,无任何缓存,除镜像自带的工具链外不安装任何额外组件。无法编译和测试项目的助手无法验证自身工作成果,其任务也会因与变更无关的原因而验证失败。
若你能在本地操作该代码库,请对每个代码库执行以下操作:
- 识别所用语言、包管理器,以及是否为单体仓库。
- 从 README、CI 配置和清单文件中找到安装、构建及测试命令。
- 执行任何操作前先询问用户。然后将代码库克隆到空的临时目录中,在不设置其他任何环境的情况下运行安装、构建和测试。用户的工作副本中存在缓存和
.env文件,这些会掩盖实际问题。 - 记录下干净克隆版本所缺少、但运行所需的一切:
- 测试所需的服务,如数据库、缓存或队列
- 测试前的步骤,如代码生成、数据迁移或初始数据准备
- 环境变量或
.env文件,这类文件未被提交到代码库 - 私有包注册表
- 代码库中未包含的运行时 代理环境
永不执行用于部署、发布或操作共享环境的命令。如果测试套件运行缓慢或调用了付费服务,请先询问用户。
针对每个代码库报告简短的就绪检查结果:包含所用命令、测试套件耗时、通过的项目以及每个问题点和对应的修复建议。
| 问题点 | 拟定的修复方案 |
|---|---|
| 测试需要依赖数据库或其他服务 | 可运行测试套件及其相关服务的Dockerfile或Compose文件 |
必需的.env文件未被提交 | 代码中已定义测试默认配置,或已提交包含非机密值的测试配置文件 |
| 测试需要真实的机密信息 | 在测试中模拟该依赖项。永不提交机密信息 |
| 依赖项来自私有仓库 | 请告知用户:CoRoid 需要将其作为项目配置的凭证。 |
| 命令仅能在子目录下运行 | 记录准确的目录路径及任何工作区过滤规则 |
缺少运行时环境也不属于阻碍因素:使用封装了对应工具链的容器即可解决。如果无法在本地访问代码库,就从用户处收集现有信息,并注明未执行干净克隆检查。
步骤3:编写供 CoRoid 助手读取的指令
在执行每项任务前,CoRoid 的助手会读取代码仓库中的内存文件:AGENTS.md、CLAUDE.md或GEMINI.md位于根目录,Cursor的规则则位于.cursor/rules。
你在步骤2中验证过的命令就应放在此处。
拟定一份AGENTS.md,或是补充现有内容,需包含以下内容:
- 从干净克隆环境验证通过的安装、构建及测试命令,以及运行这些命令的目录
- 测试所需的步骤及相关服务
- 如何运行最精简且有用的测试集,例如单个包或单个文件
- 代码未体现的约定与边界:不可修改的模块、禁止触碰的区域、禁止添加的依赖项
省略代码已说明的内容,保持文件简洁。如果CLAUDE.md或.cursor/rules包含相同指令,只需在AGENTS.md并通过@AGENTS.md行导入另一文件。
如果描述的是本地Git工作流程,请参阅每台智能体均使用AGENTS.md。
向用户展示差异内容。经其批准后,在新分支上提交更改并创建pull request,或由用户自行提交。该更改必须在首个任务启动前合并到基准分支,因为每项任务都会从该分支的独立检出结果中读取记忆文件。对步骤2中用户认可的修复方案也采用相同处理方式。
步骤4:账号与组织(用户相关)
如果用户已经以所有者或管理员身份隶属于某个 CoRoid 组织,则可跳过此步骤。
请用户执行以下操作:
- 在
https://client.coroid.ai/auth/signup使用其工作邮箱注册,并验证地址 - 接受服务条款
- 创建组织
核对:用户能够打开https://client.coroid.ai/projects。完成此设置的人员需具备所有者或管理员权限,因为只有这些角色才能关联源代码控制并添加提供商密钥。
查看创建您的账号与组织。
步骤5:关联源代码控制(用户相关)
开始操作前,需与用户确认访问要求。因需他人审批而导致安装中途停滞,是此步骤耗时数天而非几分钟的常见原因。
GitHub
用户打开设置 → 连接 → 源代码管理
(https://client.coroid.ai/settings/connections/source-control)。
| 选项 | 适用场景 | 用户在GitHub上所需的内容 |
|---|---|---|
| GitHub应用(推荐) | 几乎总是 | 拥有在所属账号或组织中安装应用的权限。在组织内通常为所有者权限;其他成员可提出申请由所有者审批。 |
| 个人访问令牌 | 应用所需的审批权限用户无法获取 | 具备repo范围的经典令牌,或具备对内容和拉取请求针对所选代码库的权限 |
| 通过URL关联,无连接 | 公共代码库,已在仅本地可用 | 无 |
GitHub应用:在 GitHub 的安装界面上,用户需选择仅选择 代码仓库并选取步骤1中约定的那些选项。即使安装该应用的人员离职,应用仍能继续运行,它能接收Webhook事件,也是 CoRoid 在拉取请求上发布检查结果的依托。仅靠令牌无法发布 GitHub 检查。
个人访问令牌:用户在 GitHub 上创建带有有效期的令牌,并将其粘贴到 CoRoid 门户中。建议选用仅限约定代码仓库使用的细粒度令牌。拉取请求会归属于该令牌的所有者,一旦该人员失去访问权限,连接便会中断。
GitLab
GitLab 目前处于私有预览阶段,仅在已启用该功能的账号中显示。
它需通过具备api范围。如果在“源代码管理”中未看到 GitLab,请告知用户联系 CoRoid,切勿围绕它制定计划。
分支保护
CoRoid 会创建普通的拉取请求,因此分支保护、必填检查和评审规则仍然适用。建议保持这些保护措施开启。如果规则要求签名提交或 CoRoid 无法生成的状态检查,其拉取请求会创建但无法合并。请告知用户,切勿更改他们的规则。
校验:提供程序会在源代码管理项下显示为已连接。真正的验证 结果出现在第六步,即代码仓库出现在项目列表中时。
查看关联你的代码、GitHub、GitLab和代码仓库与分支设置。
第六步:创建项目(由用户操作)
为每个代码仓库创建一个项目,切勿为一个代码仓库创建两个项目。用户需打开项目 → 新建 (https://client.coroid.ai/projects/new) 并且,针对
每个代码仓库:
- 从已连接的提供程序中挑选,或使用通过URL关联用于 公共代码仓库
- 选择代码仓库模式:同步模式,即 CoRoid 会推送分支并创建拉取请求;或仅本地模式,即 CoRoid 在有人选择之前绝不会向代码仓库写入内容开始同步
- 勾选默认分支
- 创建项目
如果团队合并的分支并非默认分支,例如develop,需在项目的代码仓库设置中设定基准分支。基准分支设置错误会导致拉取请求被发送到无人审核的分支。
如果列表中没有显示某个代码仓库,原因通常如下:
- GitHub 应用未被授予该代码仓库的访问权限
- 令牌的权限范围过窄,无法列出该代码仓库
- 该代码仓库所属的组织与已关联的组织的名称不一致
步骤7:查看 CoRoid 的发现结果
请用户打开每个项目的概览页,读取其中的代码仓库详情以及完成设置:
- 状态和分支:代码仓库已被克隆,处于约定的基准分支上。若概览页显示代码仓库尚未克隆,用户需选择克隆代码仓库。
- 技术栈:CoRoid 识别出的语言、框架、包管理器和测试工具。将其与你的就绪性检查结果进行对比。若首次同步后技术栈为空或不符,用户可从该处重新扫描。
- 完成设置:诸如“依赖项安装不成功”之类的提示,指向的是第二步中出现的同类问题。请与用户一起逐一解决这些问题。
随后用户打开项目的设置 → 知识库 → 上下文。第三步生成的记忆文件需列在代码仓库源之下且处于 启用状态。若显示创建,则说明该文件尚未同步到 关联的分支中。
第八步:组织设置(可选)
询问用户是否现在需要配置其中任何一项。所有项均有可用的默认设置:
- 成员,在设置 → 成员:即负责审核拉取请求的人员,包括所有者、管理员、成员或审核员。建议仅给需要更改策略及提供程序密钥的人员授予管理员权限。该功能需专业版套餐支持。
- 提供商密钥,在设置 → 提供商密钥:仅用于使用 组织自身的模型提供程序账户。用户需在门户中输入对应密钥。建议在提供程序端设置带有消费限额的受限密钥。
- 其他组织的设置:在此处导出设置包,然后
导入到设置 → 数据 → 导出设置。机密信息会以
占位符形式传输,因此预览中的每个
needsRebind条目都需要仔细核对。
步骤9:自行连接 CoRoid(可选)
如果你的客户端支持远程MCP服务器,可通过其MCP服务器访问 CoRoid,地址为https://api.coroid.ai/mcp。设置过程并不依赖它,但它
能让您自行查看项目情况,并在后续协助用户执行任务。
- 用户打开设置 → 连接 → CoRoid MCP 服务器
(
https://client.coroid.ai/settings/connections/coroid-mcp)。如果该功能对其组织不可用,可跳过此步骤。 - 客户端设置会显示各客户端的对应命令。使用 OAuth 时,用户会在浏览器中 授权您的访问权限;使用个人访问令牌时,用户需在访问令牌中创建该令牌,并将其存储于自身 Shell 的环境 变量中。您无需查看该令牌的值。
- 建议授予最低必要权限:
mcp.read用于检查设置情况,此外mcp.work.write仅当您需要创建任务时才需使用。请将令牌的权限限定于这些 项目,设置过期时间,并指定自动化策略,然后再让任何 客户端自动运行任务。
核对:调用list_projects,接着get_project针对步骤 6 中的每个项目进行操作,
并确认对应的代码库和分支。
仅可使用api.coroid.ai用于 MCP。客户端门户的主机名不支持该功能。
步骤 10:起草首个任务
最后,与用户一起在新项目中起草一个小型的首个任务。 合适的首个任务应真实可行、规模较小、贴近现有测试用例,且有明确的交付标准。应避免涉及身份验证、支付、数据迁移、无明确收尾的清理工作,以及尚未确定设计方案的任务。
描述预期成果而非实现方式:任务完成后应满足何种条件、哪些文件与之相关、哪些文件无需改动。用户从新任务 (https://client.coroid.ai/work/new),它会读取
相关说明并批准该计划。任务执行会消耗代理时长,免费套餐每天包含 2 小时 UTC 时长,因此由用户决定任务的运行时间。
步骤 11:交接
向用户提供设置记录:
- 每个代码库及其对应的项目、代码库模式和基准分支
- 源代码控制方式的连接方式,以及连接的所有者:应用安装程序,或令牌的所有者及过期日期
- 每个代码库对应的已修复问题、待处理问题(如带有
AGENTS.md的未合并拉取请求),以及用户选择忽略的问题 - 已设置及跳过的可选配置,还有起草的首个任务
随后引导用户前往审核并合并结果以了解首个 pull request 生成的内容。
下一步
创建您的账号和组织——同样的设置,手动完成。