FlightPlan

你的代理相互冲突。提交一份 FlightPlan。

在工作开始之前，你的每个代理都会声明其目标，并查看已经在进行中的工作。 它们围绕冲突进行协调，然后留下变更内容及其原因。

提供建议，绝不锁定。

是代理工作的副产品，而非需要维护的另一个流程。

FlightPlan 在编码代理的工作发生冲突之前对其进行协调。此仓库包含托管服务 getflightplan.com 的 CLI、MCP 服务器和安装程序。

快速开始

在你的仓库根目录下：

uvx getflightplan install

这将为 Claude Code 安装 FlightPlan。对于 Codex，请附加 --agent codex（或 --agent both）。该命令可以安全地重复运行。 在机器上首次运行时，接下来运行 uvx getflightplan login——它会连接你的账户并完成 MCP 设置。

托管服务处于测试阶段；使用你的 GitHub 账户登录 getflightplan.com。该包位于 PyPI 上，因此上述命令就是你所需要的全部。要固定某个分支或提交，请从源码安装： uvx --from git+https://github.com/sledmonkey/getflightplan getflightplan install。

版本和兼容性策略：docs/versioning.md。

Related MCP server: asynkor

工作原理

1. 提交工作。 在编辑之前，代理声明其任务和预期要接触的文件。

2. 查看进行中的工作。 FlightPlan 返回重叠的活跃工作，包括 Git 无法看到的未提交更改、编码过程中做出的决策，以及相关的近期结果。

3. 协调。 重叠是建议性的：缩小工作范围、排序，或在了解上下文的情况下继续。

4. 汇报。 代理记录变更内容、意外情况以及尝试过的方法，以便下一次会话不会从零开始。

安装程序添加的内容

• .flightplan.toml——固定每个代理发布时使用的仓库名称以及注册表 URL。有意提交；不包含机密。

• 在 CLAUDE.md 和/或 AGENTS.md 中的托管代理片段。

• /registry-digest——一个按需的“最近发生了什么”命令。

• 一个会话结束停止钩子（.claude/hooks/flightplan_stop_hook.py 及其设置连接），提醒代理关闭未完成的意图。

它还会检查 MCP 注册和服务可达性，并在机器拥有凭据时修复注册——无需提示。验证是建议性的，绝不会导致运行失败。

要删除安装程序写入的所有内容，请在仓库根目录下运行 getflightplan uninstall（使用 --dry-run 预览，使用 --purge-key 同时删除保存的 API 密钥）。

登录

getflightplan login 无需复制 API 密钥即可获取凭据。它会打开你的浏览器，你在那里批准，凭据会以模式 600 保存到 ~/.config/flightplan/env。凭据永远不会被打印出来。存储凭据后，登录还会为你机器上的代理二进制文件注册 MCP 服务器——这是安装程序在机器没有凭据时必须跳过的步骤。

在没有浏览器的机器上，运行 getflightplan login --headless。该命令会显示一个短代码和一个地址。在另一台设备上打开该地址并输入代码。

getflightplan logout 会从这台机器上删除存储的凭据。要在服务上撤销它，请使用 /devices 页面。

查找你的仓库

登录后，客户端会向注册表询问此检出属于哪个仓库。它会发送你的 origin 远程地址以及最多 1000 个提交 ID，以证明你拥有一个克隆。如果你的账户有访问权限，ID 和名称会写入 .flightplan.toml。如果注册表不知道这个仓库，客户端会提供在你的浏览器中注册它的选项。如果你的账户没有访问权限，客户端会提供请求访问的选项。

getflightplan login --no-register 会跳过检查。getflightplan register 稍后单独运行它。失败的检查绝不会导致登录失败。

声明工作已完成

使用 uncommitted: true 完成的意图表示工作位于某人的工作树中，而不是其他地方。注册表无法看到你的工作树，因此它会持续警告所有接触这些路径的人，直到被告知工作已落地。

代理使用 mark_intent_landed 工具执行此操作。你也可以手动操作：

getflightplan landed <intent-id> --commit <sha> --commit <sha>

提交是可选的；时间戳是修正。只有在你确定知道的情况下才传递 SHA——客户端永远不会猜测哪些提交属于某个意图。落地可以安全地重复执行，并且永远不会重写已完成记录。

配置

• FLIGHTPLAN_URL——https://api.getflightplan.com

• FLIGHTPLAN_API_KEY——你的密钥（MCP 服务器的环境变量；停止钩子也会读取 ~/.config/flightplan/env）。

• .flightplan.toml——每个仓库的固定配置：一个 repo 名称和 url，或者一个带有可读 name 的 target_id（一旦仓库有了固定的 ID）。

你的代理被告知的内容

安装程序会添加以下托管契约，其中固定了你的仓库名称。

意图注册表

此仓库参与团队意图注册表（MCP 服务器：flightplan）。

• 在开始非琐碎工作之前，调用 post_intent。判断标准：该工作是否会改变其他代理可能遇到的行为、默认值或契约——或者，对于纯调查，调查结果是否能节省下一个代理一个小时？两者中任一为是 → 发布；问答和拼写级别的修复，则不需要。发送一段摘要（做什么 + 为什么）、kind（build，或用于一次性调查的 explore/spike）以及你预期要更改区域的 touches glob 模式。保留返回的 ID 以供后续使用。对于 repo，使用 git 远程 origin 的 basename（如果没有远程，则使用仓库根目录名称）——此仓库上的每个代理必须使用相同的名称，否则冲突检查会静默地互相错过。响应可能包含 context：与你的任务相关的近期已完成工作——在开始之前阅读这些结果；其中的意外和死胡同是重要的信息。

• 如果响应包含级别为 warn 的重叠，在暂停之前检查重叠是什么。两种情况无需确认——提及重叠并继续：重叠的意图正是你被要求处理的工作（审查它、验证它、跟进它），或者你的任务是只读的。否则，告诉你的用户谁在做什么以及哪些 glob 冲突，并在继续之前询问如何操作。fyi/nudge 级别：简要提及并继续。

• 如果工作范围发生变化或运行时间过长，调用 update_intent：当范围扩大时修改摘要/touches（冲突检查会针对它们运行——过时的 glob 会错过真正的冲突），或者仅使用 ID 调用以续订跨越超过一天的工作的 TTL。响应包含新的 overlaps——与发布时相同的基于 glob 的冲突检查——其中的 warn 与发布时的 warn 处理方式相同。

• 当工作完成或被放弃时——包括会话即将结束时——调用 complete_intent 并附上一段结果：实际发生了什么变化、任何意外情况、尝试过并被拒绝的方法、任何故意保留的内容。如果 warn 重叠改变了工作的进行方式（协调、缩小范围、无论如何继续），请说明是哪一个。附上你已经知道的 git 事实：实际更改的 files（git diff --name-only）、创建的 commits，以及如果任何工作尚未提交则 uncommitted: true——这个标志让其他代理的冲突检查大声警告而不是静默处理。完成意图结束的是片段，而不是会话：完成之后改变行为、默认值或契约的后续工作需要重新发布——“同一会话”并不豁免。

• 当你得知已声明未提交的工作已落地时，使用该意图的 ID（以及你知道的提交 SHA）调用 mark_intent_landed：除非有人声明，否则注册表会持续警告所有接触这些路径的人。

• 每当你对进行中工作的了解可能过时时，重新检查冲突——发布时检查一次，在长时间会话中会过时。需要重新检查的时刻：在你读取和编辑之间文件发生了变化，或者编辑在你刚刚读取的文本上失败——某人的工作在你下面落地了；在编辑你本次会话未创建的共享文档或工件之前；在从另一个代理交接后恢复时；以及在接触早期 warn 中命名的文件之前。最便宜的重新检查是仅使用你的意图 ID 调用 update_intent（续订 TTL，返回新的 overlaps）；当你没有开放的意图或正在规划新工作时，使用 list_intents（传递 overlaps glob，加上用于语义检查的 summary，或用于历史的 q/since）。

• 当在对话中做出决定时（选择了方法、拒绝了替代方案、设定了方向），在决定确定的那一刻记录它：使用 kind: "decision" 调用 post_intent，摘要为问题，结果在 outcome 中——决定了什么、拒绝了什么以及原因。一次调用；没有 touches，稍后无需完成。决定永远不会冲突，并成为可搜索的团队记忆。决定也是修正机制：已完成的结果是不可变的，因此如果后来证明是错误的，发布一个决定，引用实际成立的内容。

• 注册表是建议性的，绝不能阻塞工作：如果其工具缺失或出错，继续工作，并告诉你的用户一次，他们可以运行 uvx getflightplan install（参见 getflightplan.com）加入此仓库的注册表。

数据

离开你机器的是协调记录：意图摘要和结果段落、glob 模式、更改的文件路径、分支名称和提交 ID——仅发送给 FlightPlan 服务。源代码内容永远不会上传。注册表知道的一切，都是作为你代理工作的副产品而得知的。

详细信息——什么永远不会离开，以及什么存储在哪里——在 docs/data-flow.md 中。漏洞报告：SECURITY.md。

许可证

Apache-2.0