中文文档索引¶
English · 简体中文
这些指南描述包含它们的源码修订，不一定对应最近发布 tag。参见项目说明和 Unreleased 更新。
从推理优先主流程开始¶
新用户：先看 安装与更新，选择打包快速路径或正式支持的源码/开发者路径；两条路径都进入 reasonfirst setup。需要详细手工运维或旧生命周期背景时，再看首次完整接入。
主产品闭环：普通 ChatGPT 读取并推理仓库/MR/CI 证据，定义任务和验收标准；ReasonFirst 将获批任务交给编程 worker；实现与 CI 的有界证据再回到 ChatGPT + 人工审查。CLI 快速上手应被视为这条闭环中的执行引擎/运维参考。脱离 ChatGPT 的直接 CLI 使用对测试、恢复和自动化仍有价值，但属于次要能力。可选 Bridge Preview 权限更高，启用前先阅读架构说明。已经接入：使用日常 start/status/stop/restart。
当前文档入口¶
| 主题 | 简体中文 | English |
|---|---|---|
| 安装/更新：打包路径或源码路径 | 安装与更新 | Install & update |
| 详细/手工首次接入与第一条普通 ChatGPT 提示词 | 详细首次接入 | Operator setup |
| 产品与能力 | 项目说明 | ReasonFirst |
| 启动必需服务与生命周期管理 | 隧道生命周期 | Tunnel lifecycle |
| 使用新提出的 GitLab 项目之前 | 项目预检与用户授权 | Project access |
| 演练 ChatGPT、Codex 与同一 MR 的三轮审查 | 实战演练 | Practice lab |
| 完整演练全聊天 managed worker → MR → matching-head CI | 全聊天 E2E | Chat-only E2E |
| 界面职责与证据 | 工作流程 | Workflow |
| 执行引擎安装与受控实现 | CLI 快速上手 | CLI quickstart |
| 手工/高级启动、凭证替代方式 | 运维指南/Windows | Manual operator guide |
| 人工交接批准任务与结果 | 写作模板，不是运行时 API | Handoff template |
| 当前架构与信任边界 | 架构说明 | Architecture |
| 架构理念 / 设计动机 | 设计理念 | Design philosophy |
| HTTP 到 HTTPS 迁移 | 迁移指南 | Migration |
| API/MCP 私有 CA、重定向与原生 Git 边界 | 运行时 TLS | Runtime TLS |
| PR 检出、测试、源码更新 | 本地 PR 审阅 | Local PR review |
| 不弱化控制的诊断 | 故障排查 | Troubleshooting |
| 贡献流程 | 贡献指南 | Contributing |
| 安全报告与限制 | 安全策略 | Security |
| v0.5.0 发布说明 | 0.5.0 release notes | 0.5.0 中文 release notes |
| 公开发布之前 | 维护者清单 | Release checklist |
第一次 ChatGPT 对话之前的必需步骤¶
完成前置条件，启动选定 Tunnel/MCP，保持其 Terminal 运行，检查本地就绪，然后在普通 ChatGPT 输入框选择真实应用。随后调用 gitlab_whoami、check_project_access，并在 resolved_commit_sha 读取文件。本地健康、单独身份成功、消息里写一个连接名称，都不等于项目读取端到端验收。
Keychain 是 Mac 指南推荐的 runtime-key 来源，不是所有平台强制组件。OpenAI tunnel key、Tunnel ID、GitLab token、本地 allowlist、编程代理登录分别不同。Platform 隧道权限、ChatGPT workspace 权限、GitLab/本地项目授权也互不替代。完整指南在每个停止点指明应由谁处理；不能假定上次 shell export 在新 Terminal 仍存在。
新项目访问门槛¶
项目名/本地目录不能证明远端存在或授权。首次引入项目时，批量读取或交接前调用 check_project_access。ok: false 时展示诊断，等待用户/操作者处理。404 或过滤后的空列表不能区分不存在和不可访问。
逐项目授权在本地 MCP 的 GITLAB_ALLOWED_PROJECTS，不是 OpenAI Tunnel 设置。仅在明确批准后追加准确目标项目、保留已有项，并重启原 MCP。助手不会创建项目或自动授权。使用较早的首任务示例前，同样需要此门槛。
一个推理界面，不额外要求聊天工具¶
普通 ChatGPT 负责推理与审阅。只读 GitLab Tunnel/MCP 提供仓库/MR/CI 读取；ActualCoder 使用 codex-cli、copilot-cli 或 codex-desktop 实现获批任务。可选 Bridge Preview 是另一条权限更高的本地编排接口。localhost Assistant、Codex tunnel plugin、Inspector 不是前置条件或验收门槛，Overview/Logs 只是可选诊断。不使用 Assistant 不会禁用上游附带 helper，也不会卸载 Codex。
标准 GitLab read connector 不承担本地任务执行。可选 Bridge Preview 已支持本地编排、审批、finish preview 和用户配置 SSH 操作。持久 core TaskSpec/attempt 与 bounded EvidencePack 已进入 main，作为推理意图与 worker 证据之间的持久边界。读取成功不证明 Git push、编程模型登录或完整应用 CI；这些在获批实现中验证。
翻译范围与维护¶
同步维护中英文当前指南，包括可执行示例、停止条件、权限与证据边界。新增完整接入双语页记录源码基线与服务商核对日期；测试验证命令一致和初始化安全。既有 quickstart、生命周期、访问、迁移、TLS 双语指南继续作为专项参考。
历史说明/CHANGELOG 保留记录，LICENSE 不变。文档不产生新发布、不改变权限、不宣称未支持的功能。服务商界面/资格会变化，核对完整接入及手工指南中的一手参考。
历史设计与旧操作示例¶
旧中文 onboarding与旧中文配置教程仅为历史记录，不是必需清单。不执行旧的含 token 示例、不覆盖工作中的 .env，不因历史文档提及就安装可选组件。
V0.2 设计、V0.2 Codex 指南、CodingAgent 兼容指南、V0.3 路线图、V0.3 审计保留历史背景。
历史专项实现说明包括发布安全、退出状态、历史扫描、日志证据。这些文件名记录开发增量，不代表当前发布状态。v0.5.0 已实现持久 TaskSpec/attempt 与 bounded EvidencePack；Issue #6 保留为历史/路线 umbrella，Issue #10 跟踪剩余原生 Git trust/destination-policy 工作。
全聊天闭环演练¶
- 全聊天 E2E 演练：在一个普通 ChatGPT 对话中完成实时仓库读取 → Bridge 管理修改 → 精确 snapshot 审核 → MR → matching-head CI/EvidencePack，全程无需手工 Codex CLI。