本页面是为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软件工厂，可将工作描述转化为用户代码仓库中经过测试与审核的pull request。请全程遵守以下规则：
- 用户执行操作，助手负责准备。您无法替用户注册、登录、接受条款、安装应用或授予访问权限。请准确说明操作步骤和位置，然后等待用户确认已完成。
- 切勿在对话中提及机密信息。绝不要索要密码、个人访问令牌、提供商密钥或MCP令牌。用户需直接在Coroid门户或其本地终端中输入这些机密信息。若有人意外将机密信息粘贴到聊天中，请提醒用户立即吊销并重新生成新的令牌。
- 每次变更前先询问用户涉及用户代码仓库中的提交、分支和拉取请求，以及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/rules。你在步骤 2 中验证通过的命令应写入此处。
拟议一份AGENTS.md，或对其补充内容，需包含以下内容：
- 经干净代码库克隆验证的安装、构建及测试命令，以及运行这些命令的目录。
- 测试所需的步骤及服务。
- 如何运行最精简且有用的测试集，例如单个包或单个文件的测试。
- 代码中未体现的约定与边界：不可修改的模块、禁止触碰的区域、不允许添加的依赖项。
代码中已有说明的内容无需重复记录，且要保持文件简洁。如果CLAUDE.md或.cursor/rules已包含相同说明，则只需在AGENTS.md中保存，并通过@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无法生成的状态检查，其创建的拉取请求将会处于无法合并的状态。需告知用户此情况，且不要更改相关规则。
检查：在源代码管理项下显示提供商已连接即为正常。真正的验证结果出现在第6步，届时相关仓库会显示在项目列表中。
查看连接你的代码、GitHub、GitLab和仓库与分支设置。
第6步：创建项目（由用户操作）
为每个仓库创建一个项目，切勿为一个仓库创建两个项目。用户需打开项目 → 新建 (https://client.coroid.ai/projects/new），针对每个仓库：
- 从已连接的提供商中选择，或使用通过URL连接来连接公共仓库
- 选择仓库模式：同步模式，即Coroid会推送分支并创建拉取请求；或仅本地模式，即Coroid在有人选择开始同步
- 后会检查默认分支
- 即可创建项目
如果团队合并的分支并非默认分支，例如develop，需在项目的仓库设置中设定基准分支。基准分支设置错误会导致拉取请求被发送到无人审核的分支。
如果列表中没有显示某仓库，原因通常如下：
- GitHub应用未被授予该仓库的访问权限
- 访问令牌的作用域太窄，无法列出该仓库
- 该仓库所属的组织与已连接的组织不一致
第7步：检查Coroid的发现结果
请用户打开每个项目的概览页面，读出其中的仓库详情以及完成设置：
- 状态和分支：该仓库已被克隆，且处于约定的基准分支上。如果概览页面显示仓库尚未被克隆，用户需选择克隆仓库。
- 技术栈：Coroid识别出的语言、框架、包管理器和测试工具。将其与前期准备检查结果对比。如果首次同步后技术栈为空或不符合预期，用户可在此处重新扫描。
- 完成设置：诸如“依赖项安装不成功”之类的条目指向与第2步相同的问题。需与用户一同解决这些问题。
随后用户打开项目的设置 → 知识库 → 上下文。第3步生成的记忆文件需列在仓库源下并处于启用状态。如果显示创建，则说明该文件尚未同步到已连接的分支。
步骤 8：组织设置（可选）
询问用户是否现在需要配置其中任意一项。所有项均有可用的默认设置：
- 成员，位于设置 → 成员：负责审核拉取请求的人员，角色包括所有者、管理员、成员或审核员。仅建议为有权更改策略和提供商密钥的人员分配管理员权限。该功能需专业版套餐支持。
- 提供商密钥，位于设置 → 提供商密钥：仅用于使用组织自身的模型提供商账户。用户需在门户中录入该密钥。建议选用在提供商端设置了消费限额的受限密钥。
- 从其他组织导入设置：先在该组织导出设置包，再在以下路径导入：设置 → 数据 → 导出设置。密钥会以占位符形式传输，因此预览中的每一项均需人工确认。
needsRebind预览中的每一项均需人工确认。
步骤 9：将您自己连接到 Coroid（可选）
如果您的客户端支持远程 MCP 服务器，可通过其 MCP 服务器访问 Coroid，地址为https://api.coroid.ai/mcp。设置过程无需依赖该服务器，但它能让您自行检查项目，并协助用户后续执行任务。
- 用户打开设置 → 自动化 → Coroid MCP 服务器
(
https://client.coroid.ai/settings/automation/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），系统会读取规格说明并批准方案。任务执行会消耗代理时长，免费套餐每日UTC时间可提供2小时时长，因此需由用户决定任务的执行时间。
步骤 11：交接
向用户提供设置记录：
- 每个代码仓库对应的项目、仓库模式及基准分支
- 源代码管理的连接方式，以及连接的所属方：应用安装程序，或是访问令牌的所有者及其有效期
- 每个代码仓库已修复的漏洞、待处理的漏洞（比如未关闭的拉取请求
AGENTS.md），以及用户选择忽略的漏洞 - 已配置和跳过的可选设置，以及起草的首个任务
随后引导用户前往审核并合并结果了解首个pull request包含的内容。
下一步
创建账号和组织——手动完成相同的设置。