本页面是为 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的安装界面中，用户选择仅选择指定仓库并挑选第一步中约定好的内容。即使安装该应用的用户离职，应用仍能正常运行，可接收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检测到的语言、框架、包管理工具及测试工具。将其与您的就绪度检查结果进行对比。若首次同步后技术栈为空或不符合预期，用户可在此处重新扫描。
- 完成设置：诸如“依赖项安装不成功”之类的提示，指向的是与第2步相同的遗漏项。请与用户一同处理这些问题。
随后用户打开项目的设置 → 知识库 → 上下文。第3步生成的记忆文件需列在代码仓库源之下并处于启用状态。若显示创建，则说明该文件尚未同步到已连接的分支。
第8步：组织设置（可选）
询问用户是否需要现在配置其中任意一项。所有选项均有可用的默认设置：
- 成员，位于设置 → 成员：即负责审核拉取请求的人员，包括所有者、管理员、成员或审核员。仅建议为有权更改策略及提供商密钥的人员分配管理员权限。该功能需专业版授权。
- 提供商密钥，位于设置 → 提供商密钥：仅用于使用组织自身的模型提供商账户。用户需在门户中录入对应密钥。建议选用带有消费限制的受限密钥。
- 其他组织的设置：在该组织中导出设置包，然后在设置 → 数据 → 导出设置机密信息会以占位符形式传输，因此预览中的每个
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所生成的内容。
下一步
创建您的账号和组织— 相同的设置，手动完成。