企业官网建设流程全解析

导读

本文基于 Firstmate 仓库中的 agent-only playbookfirstmate-codexapp，系统讲解如何在 Firstmate 的舰队工作流中协调Codex Desktop 可见线程：何时使用、如何创建与投递指令、如何通过state/<id>.status状态文件建立可验证的返回通道、如何观察协调与归档线程，以及为什么 Codex App 至今仍是"受阻的后端边界"而非可选择的运行时后端。读完本文，你将掌握一套可直接落地的宿主工具编排流程，并能准确区分"可见伴随线程"与"完整 Firstmate 后端"的技术边界。

一、角色定位：Codex Desktop 线程是伴随工作流，不是后端

Firstmate 对 Codex App 的定位有一句非常明确的总纲（见 SKILL.md 与 docs/codex-app-backend.md）：

Codex Desktop 可见线程是伴随宿主工具工作流（companion host-tool workflows），不是可选择的 Firstmate 运行时后端。

当前唯一受支持的工作形态是：

• Desktop 宿主工具编排（host-tool choreography），即由运行在 Codex Desktop 内的 Firstmate 会话直接调用create_thread、read_thread、send_message_to_thread等宿主工具；
• 外加一条显式的状态文件返回通道检查（status-file return-channel check），即线程向 Firstmate 的state/<id>.status追加生命周期行，并由 Firstmate 侧验证该写入真实发生。

这不是FM_BACKEND=codex-app这种后端取值。代码层面对此有双重铁证：

• bin/fm-backend.sh 头注释明确写着 "Codex App is intentionally not in the known set yet"，且第 70 行的已知后端集合与可 spawn 集合都是FM_BACKEND_KNOWN="tmux herdr zellij orca cmux"、FM_BACKEND_SPAWN="tmux herdr zellij orca cmux"，codex-app刻意缺席；
• docs/configuration.md 配置文档同样声明 "codex-appis not an accepted runtime backend yet"。

为什么不能把"一个能写状态文件的手工线程台账"当作后端？因为手工线程台账不是后端——Firstmate 的后端契约要求完整的生命周期控制能力，而不仅仅是记录存在性。这一点在下一节展开。

二、验收契约：未来 Codex App 后端必须满足的五项条件

docs/codex-app-backend.md 给出了未来 Codex App 后端必须满足的验收契约，与终端型适配器（terminal-backed adapters）完全一致：

1. 创建任务端点并返回一个持久的线程 id；
2. 发送初始指令以及后续操作者消息到该端点；
3. 读取足够的实时状态或有界 transcript 以监督任务；
4. 归档、终止或以其他方式停止该精确端点；
5. 让线程追加Firstmate 正常的生命周期行到state/<id>.status。

其中第 5 条——状态返回通道是强制的（mandatory）。文档原话是：一个无法向 Firstmate 正常生命周期汇报的可见线程，不是一个完整的后端（A visible thread that cannot report into Firstmate's normal lifecycle is not a complete backend）。

三、当前阻塞点：缺少受支持的 shell 可调用桥接

为什么 Codex App 至今仍处于"受阻边界"状态？docs/codex-app-backend.md 给出了非常具体的技术归因：

• Firstmate 的后端脚本是shell 入口点，可以径直调用 tmux、Herdr、Zellij、Orca、cmux；
• 而Codex Desktop 宿主工具只对 Desktop 会话（conversation）可用，不对任意 Firstmate 子进程可用；
• 因此缺失的组件是一个Codex Desktop 支持的、可被 shell 调用的传输通道，而不是另一个本地台账。

文档还记录了一个真实的探测结论：codex app-server --stdio确实暴露了部分有用的 JSON-RPC 片段（如线程启动、turn 启动、线程读取、线程归档），一个单进程探针甚至能创建并归档一条线程记录；但没有任何受支持的桥接能让 Firstmate 在同一可见 Desktop 端点上完整地创建、继续、读取并归档其全生命周期。原始 Desktop 控制 socket 代理同样不是受支持传输。这些零散片段并不足以把codex-app加入已知后端注册表或可 spawn 后端注册表——这也正是 bin/fm-backend.sh 中 "codex-app remains deliberately absent" 的工程原因。

四、所需桥接与未来落地路径

docs/codex-app-backend.md 规定了桥接的启用条件与语义。当 Codex Desktop 暴露以下任一受支持接口时，实现才可开始：

• 一个封装 create/send/read/archive 宿主工具操作的CLI 包装器；
• 一个有稳定帧协议的、文档化的JSON-RPC 或 MCP 传输；
• 或一个受维护的辅助程序，能说该受支持传输并向 shell 适配器返回纯 JSON。

桥接必须提供如下语义：

create: task id, worktree request, initial instructions -> thread id, cwd, state send: thread id, text -> accepted or rejected read: thread id, bounded cursor -> transcript and live state archive: thread id -> archived or stopped return: thread appends state/<id>.status lifecycle lines

一旦桥接可用，Firstmate 的计划是：新增真正的bin/backends/codex-app.sh，持久化backend=codex-app与codex_app_thread_id=，并让 spawn、send、peek、watch、cleanup 全部走共享调度器（shared dispatcher）。分阶段推出的顺序也很明确：ship 与 scout 任务先行；在 create、send、read、status return、archive 全部通过正常后端调度器验证之前，Secondmate 支持保持范围外。

五、宿主工具清单与预检流程

使用本 playbook 前必须完成四项预检（见 SKILL.md）：

1. 确认会话运行在 Codex Desktop 内且宿主工具已暴露。按精确名称检索以下工具：create_thread、list_threads、read_thread、send_message_to_thread、archive、set_thread_archived。注意：当前没有任何宿主工具能为 agent 创建 Codex App 项目，因此目标仓库必须已由人类在 Desktop 中保存为项目。
2. 确认目标仓库已保存为 Codex Desktop 项目。由于缺少创建项目的宿主工具，人类必须先在 Desktop 中添加项目，新建线程才能可靠地落到该项目下。
3. 不要为仓库工作创建无项目线程。若项目不存在，应停下并要求添加项目，或改用普通 Firstmate 后端。
4. 判定这是真正的 Firstmate 托管任务还是可见伴随线程。真正的任务需要：任务 id、隔离的 worktree 或 Desktop 自有的 cwd、分支计划，以及可写的state/<id>.status路径。

这条"无项目线程禁止"约束在 docs/codex-app-backend.md 的验证记录中同样成立：可复用的 Desktop 宿主工具 smoke 第一步就是"list a saved project"。

六、创建与投递：必须用宿主工具，禁止 shell 模仿

创建可见线程时必须使用 Desktop 宿主工具，而不是 shell 模仿（"use the Desktop host tool, not shell imitation"）。创建后先让 worker 报告初始环境，指令文本如下：

pwd git rev-parse --show-toplevel git branch --show-current git log --oneline --max-count=3

对可写仓库工作，应指示 worker 使用 Codex 创建的当前目录（Desktop-owned cwd），不要让它cd进已保存的项目 checkout 去做编辑、提交、no-mistakes、push 或 PR 工作——这既是隔离要求，也直接对应 AGENTS.md 中"项目工作必须从隔离的 disposable worktree 开始，绝不在主 checkout 中"的 spawn 断言。

后续跟进指令一律通过send_message_to_thread发送。若用户直接在可见线程里输入内容，应将其视为权威输入，并通过read_thread协调（reconcile）而非撤销。

七、状态返回通道：可验证的汇报要求

Desktop 自有的 Codex 线程只有在两种条件同时成立时才能向 Firstmate 状态文件追加内容：提示词给出绝对路径，且 Desktop 权限上下文可以写入该 checkout。因此 SKILL.md 强调：状态写入是经验证的返回通道要求（verified return-channel requirement），而不是默认成立的事实。

对于 Firstmate 托管任务，必须包含显式状态指令：

Append supervisor-visible status lines to <absolute-firstmate-home>/state/<task-id>.status. Use only these prefixes for status changes: working:, needs-decision:, blocked:, paused:, done:, failed:. Follow the task brief's status-reporting rule for declaring and resolving waits; bin/fm-brief.sh owns that rule. Before doing substantive work, append "working: Codex Desktop thread started".

注意前缀白名单working:/needs-decision:/blocked:/paused:/done:/failed:正是 Firstmate 状态协议的规范集合。底层语义在 bin/fm-brief.sh 中有精确定义：paused:用于主动等待预计会自行消除的外部条件（并可用until <YYYY-MM-DDTHH:MMZ>标注消除时间），而blocked:用于卡住且需要 Firstmate 介入；working:只是稀疏的、监督者可行动的事件，禁止仅仅用它确认收到消息或宣布已开始。Firstmate 状态协议还规定：被打开的决策/阻塞项只有在携带其精确 key 的resolved行落地后才会关闭，后续的done:或working:行不能关闭它。

在将线程视为"已受监督"之前，必须验证返回通道：

• read_thread显示 worker 确实尝试了状态写入；
• 本地state/<task-id>.status文件包含预期行；
• 若可用，transcript 包含该状态文件的 file-change 条目。

若线程无法写入状态文件，则只能保留为可见伴随线程，不得宣称它是完整 Firstmate 后端。

八、观察与协调：以 read_thread 为事实来源

观察阶段的规则非常克制：

• 用read_thread获取线程事实（thread truth）；
• list_threads只用于查找或恢复可见线程 id，不能替代阅读 transcript。

Firstmate 协调（reconciliation）时应优先使用具体证据，而非转述大段对话：

• 线程 id 与项目
• 当前 Desktop 自有 cwd
• 分支名
• 最近一个有意义的线程状态
• 最新状态文件行
• 存在 PR 时的 PR URL

禁止把冗长 transcript 重复进 Firstmate 文档或 PR 正文；只需概括宿主工具调用、状态文件结果与归档结果。向船长（captain）汇报 Desktop 线程结果时，必须把状态前缀与返回通道证据翻译成船长用语——这条翻译契约由 AGENTS.md 第 9 节"Escalation and captain etiquette"管辖：谈结果而非机制，不得把working:/blocked:/done:等内部标签、任务 id、status 文件路径原样抛给船长，而要转成"正在处理/等待批准/已完成"这类具体结果与下一步决策。

九、归档：通过宿主工具完成

归档同样走 Desktop 宿主工具：暴露的是archive原语就用archive，暴露的是工具名就用set_thread_archived(threadId=<id>, archived=true)。

需要理解归档的语义边界：归档可能把线程从正常的 sidebar/项目视图移除，但不应抹掉 transcript 或已落地的成果（it should not erase the transcript or landed work）。这在实际验证中也有对应记录：归档后读取已归档 transcript，状态为notLoaded，但内容仍在。

• 对伴随线程：归档线程，并报告持久成果落在哪里；
• 若存在真正的 Firstmate 任务记录，则清理决策留给正常 Firstmate 任务流，不由本 skill 决定。

十、失败信号与处置清单

SKILL.md 给出五类典型失败及其处置：

其中"禁止用 shell 文件模拟宿主工具"与 AGENTS.md 的验证纪律一脉相承：已验证 harness 集合之外的一切都要 fail-closed，缺失依赖、认证失败、不支持后端、版本拒绝都是阻塞项，绝不静默换后端重试。

十一、实证记录：Desktop 宿主工具 smoke

verification/runtime-backends.md 的 "Codex App host tools" 一节保存了可复用的实测记录：2026-07-06 针对 Codex Desktop bundle 26.623.101652（build 4674，bundle idcom.openai.codex）执行的宿主工具 smoke。本地路径与任务级 id 刻意不留存在该文档中。smoke 覆盖的宿主工具序列为：

1. 列出已保存项目；
2. 创建 Desktop 自有的 worktree 线程；
3. 在线程活动期间与完成后恢复并读取线程；
4. 验证线程追加了 Firstmate 状态行并写入了报告；
5. 向同一线程发送跟进；
6. 读取已完成的跟进；
7. 归档该精确线程；
8. 读取归档后的 transcript（状态notLoaded）。

记录给出的已验证保证是：当提示词提供授权的绝对路径时，Desktop 自有线程可以写入 Firstmate 生命周期文件，且 create/send/read/archive 在 Desktop 宿主工具层都能工作。未验证的保证仍是：不存在受支持的 shell 可调用桥接让 Firstmate 对同一可见 Desktop 端点执行这些操作——app-server 的部分方法与原始 socket 实验均不满足该桥接契约。

十二、边界速查：什么可以、什么不可以

配置层面同样适用此边界：docs/configuration.md 中FM_BACKEND=的说明明确指出 tmux/herdr/zellij/orca/cmux 支持 ship/scout spawn，而 "codex-app is not accepted"。

结语

firstmate-codexapp这份 playbook 的价值在于把"想要让 Codex Desktop 参与 Firstmate 工作"这一模糊诉求，收敛为一条纪律严明、可验证、不越界的操作路径：可见线程永远只是伴随工作流，宿主工具编排 + 状态文件返回通道验证是当前唯一受支持形态，而真正的codex-app后端必须在 shell 可调用桥接出现、并通过共享调度器的完整生命周期验收之后才会进入后端注册表。对实践者而言，记住三句话即可：创建走宿主工具，汇报走状态文件且必须验证，边界归docs/codex-app-backend.md管辖。