mainline

Mainline

此技能面向 Agent，提供 Mainline 集成。即使仓库的 AGENTS.md 中尚无 Mainline 文本，且未安装 Mainline 钩子，它也应足以满足需要。

Mainline 会记录 AI 驱动的变更为何发生，将这些意图与代码提交关联起来，并在 PR 评审前呈现语义冲突。应将其视为编码工作流的一部分，而非可选文档。

如果当前会话中已包含由 Mainline 钩子注入的 mainline:context 区块，则视为已加载该钩子上下文。不要仅为重复加载上下文而重新运行通用引导上下文命令。仅在需要时运行特定于任务的上下文命令。

停止线速查表

将此表用作第一步边界判断；以下详细工作流会说明如何执行每个边界。

从语义上理解用户最新指令，而不是按关键词匹配。

指令类别	有效边界	未获新的明确请求时，不得越过
仅提供建议 / 只读	assist	编辑、提交、封存、发布元数据、推送或 PR
完成本地工作 / 提交 / 封存 / 交接	handoff	推送代码分支或 PR
推送分支 / 创建或更新 PR	review，受团队 max_autonomy 限制	推送到 main、合并、发布、部署或合并后的清理
继续下一个任务	保持当前有效边界	生命周期推进，除非这是自然的下一步且在许可范围内
合并 / 发布 / 部署 / 发布软件包 / 合并后的清理	明确的交付任务，而非自主权	目标不明确或缺少仓库工作流检查

用词注意事项：

• mainline publish 发布的是 Mainline 意图元数据 / actor-log 状态。这与推送 Git 分支、创建 PR、合并、发布软件包、部署或产品发布不同。如果用户只说“发布”，但未明确对象，应先确认目标。
• 推送 Git 分支、创建 PR、合并 PR，以及发布 / 部署产品，是彼此独立的交付步骤。不要将它们合并为一个“发布”操作。
• 文件重叠仅是一个信号。只有检查确认其确实构成潜在矛盾后，才进入冲突处理工作流。

语言规则（至关重要）

在写入 Mainline 的所有内容中，使用用户所用的语言： mainline start 中的目标文本、每轮 mainline append、封存时的 summary.title / what / why / user_goal / decisions / review_notes、显式 signal 命令文本，以及 PR 描述正文。 如果用户用中文书写，就用中文封存。英文输入，英文输出。 混合输入 → 使用占主导地位的语言。

原因：封存记录是团队的长期记忆。队友日后阅读 mainline show <id> 时，必须能认出这是他们自己的工作。将中文任务翻译成英文封存，会让这份语料更难被那些需要依靠它记忆工作的人员阅读。

原样传递用户实质性的目标文本——mainline start "<goal>" 会成为 mainline log 中的标题。如果最新指令只是依赖上下文的指代，而非对工作的持久描述，则用用户所用的语言将其扩展为简短易读的目标。将该指代保留在轮次引用或封存引用中，而不要将其作为标题。无论对话使用何种语言，代码标识符、命令名称、文件路径和 CLI 代码片段都保持原样。

触发策略

在 Git 仓库中处理任务时，只要满足以下任一条件，就使用此技能：

• 仓库中存在 .mainline/config.toml、.ml-cache/、AGENTS.md 中的 Mainline 区块、Mainline 引用，或项目文档中已有 Mainline 命令。
• 用户提到 Mainline、意图、冲突检查、Agent 指引、钩子、封存、提案、覆盖率、缺口、未覆盖的提交、Agent 自主性、agent_authority、max_autonomy、停止线、allowed_boundary、inspect_or_stop、当前指令覆盖、交接／审查／交付边界，或自动提交／自动提交更改／自动封存行为。
• 你准备在已知使用 Mainline 的仓库中编辑代码、重构、删除代码、更改测试或 CI、提交、推送、创建 PR、审查 PR，或调查之前的工作是否已作出决定。

如果仓库看起来在使用 Mainline，因此触发了此技能，请在广泛搜索代码或编辑之前运行 Mainline 检查。如果仓库看起来没有使用 Mainline，且用户未要求设置 Mainline，则未经用户确认，不要初始化 Mainline。

设置责任

不要假设用户已经安装或初始化 Mainline。如果任务需要 Mainline，而 mainline 不存在，请先安装或协助安装，再继续。

首先检查：

command -v mainline
mainline status --json

如果 CLI 不存在，在 macOS/Linux 上优先使用公开的安装脚本：

curl -fsSL https://raw.githubusercontent.com/mainline-org/mainline/main/install.sh | bash

如果用户更倾向于使用 Go 原生安装程序，或安装脚本不可用，请使用 Go 1.22+：

go install github.com/mainline-org/mainline@latest

只有在用户明确要求当前尚未发布的开发版本时，才使用 @main：

go install github.com/mainline-org/mainline@main

安装后，确保安装目录（脚本通常使用 ~/.local/bin，go install 通常使用 ~/go/bin）已加入 PATH。重新运行 mainline status --json。

如果 CLI 已存在，但仓库尚未初始化，且用户要求设置 Mainline，则进行初始化。mainline init 会安装默认的 Mainline 技能和仓库本地钩子集成。除非仓库已经跟踪这些钩子配置文件，否则新建的钩子配置文件会通过 .git/info/exclude 保持在克隆本地；除非用户明确要求设置仓库级策略，否则不会写入 AGENTS.md：

mainline init --actor-name "<name>"

从用户明确提供的信息、现有 Git 身份或稳定的本地 Agent 名称中选择 <name>。如果初始化会修改共享的仓库指引或 Git 引用规范，而用户只要求进行范围有限的代码更改，请先征求用户同意。

钩子

钩子会提供动态上下文并提高触发率，但并非权威依据。此技能仍是完整工作流的权威来源，Agent 仍须自行作出语义判断。

mainline init 默认会安装钩子。用户要求检查、修复或手动安装钩子集成时，请使用以下命令：

mainline hooks status
mainline hooks install

如果未安装钩子，请继续使用下面的命令工作流。不要仅仅因为缺少钩子就阻止代码工作。

任务开始

如果目标过于模糊，无法形成有效意图，请在运行 mainline start 前优先提出一个简短的澄清问题；不要将此变成 PRD／任务规划。如果仍决定继续，请采用最安全且范围最窄的理解，并在第一次 mainline append 中记录该假设。

只读诊断、历史考证、计划审查以及“先看看／暂不修改”请求都属于 Mainline 感知型工作，但并非意图声明。根据需要使用 preflight、status、context、show 和 trace 等只读命令。在当前指令授权进行非琐碎编辑、提交／封存／交接或其他持久化工程记录之前，不要运行 mainline start。如果调查后来转为修改，请在这一转换时开始记录意图，并在第一次 append 中记录有用的诊断发现。

开始 Mainline 感知型任务时，请先执行只读检查：

mainline preflight --json

preflight 是一个低噪声的就绪检查关卡。如果它返回 "level": "ok" 和 "ok_to_continue": true，就继续，不要为了保险而扩大 上下文范围。如果它返回 warn 或 block，请先读取 findings、overlaps 和 recommended_next 字段，然后仅运行它指出的 针对性后续命令（show、trace、context --files/--query 或 check）。

如果存在 agent_authority，也请读取它。CLI JSON 会将命令载荷包装在 .data 下，因此运行时路径通常是 .data.agent_authority；示例和测试中可能会显示未包装的引擎字段 agent_authority。它仅供参考，但它是团队可见的停止线约定，用于规定 Agent 在没有收到新的人工指令时可以推进到什么程度：

• assist / before_commit：分析、编辑并验证，然后停止，不得提交、封存、发布、推送或创建 PR，除非用户明确要求交接。
• handoff / proposed_intent：提交范围明确的工作，并在就绪时封存，然后停止，不得推送代码分支或创建／更新 PR，除非用户明确要求评审。
• review / opened_pr：在非主分支上推进至外部评审，并使用生成的 Mainline PR 正文，然后停止，不得合并、发布或进行合并后的清理。

硬性关卡和当前用户指令优先。团队的 max_autonomy 是上限：当前用户指令可以降低停止线，也可以将其提高至该上限，但不能授权超出团队上限的操作。切勿将单轮覆盖写入 .mainline/config.toml 或 .mainline/local.toml。

如果 preflight 将 .data.agent_authority.current.allowed_boundary 降至 inspect_or_stop，不要盲目推进生命周期。先检查列出的 findings／overlaps。对每项重叠进行分类：

• 同一分支、同一目标或明确的后续工作 → 记录其关联关系。
• 相邻／互补的协议或文档工作 → 记录其为何不构成矛盾。
• 会改变相同行为的上游漂移 → 在实施或收尾前进行变基／合并／检查。
• 真实且可能相互矛盾的语义冲突 → 运行 mainline check 或请求人工判断。

不要仅仅因为文件有重叠就运行 mainline check。不要默默忽略重叠；请在下一次追加／封存时记录分类。

status 或 preflight 中的 notes_health.likely_history_rewrite 是根据最近一次同步缓存的，不会在每次热路径命令运行时重新计算。如果用户提到最近发生过 force-push、变基、filter-repo 重写、作者重写、贡献者清理、远程回滚，或提案／覆盖状态突然有误，即使缓存中没有警告，也要运行只读诊断：

mainline doctor --notes --json

如果 doctor 建议迁移，请先预览：

mainline migrate notes --infer --dry-run --json

除非用户明确确认计划，否则不要运行 mainline migrate notes --write 或 --push；--push 会更改共享 notes ref。

如果已安装的二进制版本较旧，不支持 preflight，则改用：

mainline status --json

然后，仅在状态或任务表明存在重叠风险时，运行 mainline list-proposals --json 和针对性的 mainline context --files ... --json。

历史重写与注释恢复

如果 mainline preflight --json 报告了 notes_rewrite_drift 发现项，或者 mainline status --json 包含 notes_health.likely_history_rewrite: true， 请先运行只读诊断：

mainline doctor --notes --json

如果用户提到最近执行过强制推送、变基、filter-repo 重写、作者信息重写、贡献者清理、远程回滚，或者历史更改后提议意图／未覆盖提交突然激增，也请运行 mainline doctor --notes --json。

如果 doctor 建议迁移，仅预览：

mainline migrate notes --infer --dry-run --json

在执行任何写入之前，先向用户显示安全／需要审核／未解决的数量。除非用户明确确认计划，否则不要运行 mainline migrate notes --write 或 --push。--push 会更改共享的 notes ref，必须视为高影响 Git 操作。

如果当前没有活动意图，且任务已涉及非简单更改或需要持久化的工程记录，请根据用户的实际目标启动一个意图：

mainline start "<user goal>" --json

如果 mainline start 返回了该分支的现有草稿，请确认它与用户的任务相符，再追加内容。如果不符，请停止并隔离这项工作。

如果同一分支已有已封存或已提议的意图，而用户要求进行后续更改，请为后续工作启动一个新意图，不要尝试修改已封存的意图。

设计更改之前，检查正在进行的工作：

mainline list-proposals --json

如果 preflight 可用且结果为绿色，则无需单独调用 list-proposals；preflight 已会读取提议索引并报告文件重叠情况。将 list-proposals 用作旧版二进制文件的备用方案，或在 preflight 指出需要调查重叠时使用。

意图优先的代码阅读

对于非简单工作，在进行广泛 grep、读取文件或实现之前，优先先通过精简的预检门槛：

mainline preflight --json

如果报告了重叠、视图过期或分支偏移，请有针对性地深入检查：

mainline context --files <path>... --json

如果任务涉及语义：

mainline context --query "<task summary>" --json

阅读返回的摘要、决策、风险和指纹。将其作为历史背景，然后对照当前代码进行验证。除非用户明确要求重新审视，否则不要重复已放弃或已被取代的方案。

对于相关意图：

mainline show <intent_id> --json
mainline trace <intent_id> --json

不要把每项任务都例行处理为运行广泛的 context --current、list-proposals、show 和 trace。预期流程是：先运行 preflight；结果为绿色时继续；结果为黄色／红色时，检查所列意图／文件并解决具体风险。

重叠收敛树：

• 上游已解决用户的目标 → 放弃本地草稿，或在重复实现之前停止。
• 本地工作仍有增量价值 → 将其缩小为后续意图。
• 两个意图在语义上互斥 → 运行 mainline check，或在继续之前寻求人为判断。

工作树与意图归属

当协调范围为 local_worktrees 时，不要创建或模拟单独的声明／租约注册表。兄弟分支的草拟意图就是当前活动的本地声明。Preflight 会显示其工作树路径、目标和已观察到的文件，方便 Agent 复用现有工作、缩小范围，或在编辑前安排有依赖关系的工作。只有当前有效的显式文件重叠会阻止操作；仅目标匹配、已提议／已封存的历史记录以及过期草稿都只是警告。封存、放弃或移除已检出的工作树，会自然结束该声明。

当前工作树干净或明确归属于当前任务时，请复用它。

在运行 git switch、mainline append 或 mainline seal 之前，确认分支、活动意图以及脏文件／未跟踪文件仍指向同一任务。如果不是，请停止并隔离这项工作；对于并行的活动意图，优先使用单独的 Git 工作树。

编辑工作流

完成 Mainline 上下文检查后，照常检查代码并进行所请求的更改。

在有意义的节点记录进展：

mainline append "<what changed and why>" --json

在完成子任务、调整方向，或发现会改变处理方法的情况后追加记录。不要逐分钟记录活动。

在探索、验证想法，或分支可能会被变基、修订或重新确定范围时，继续起草意图。本地提交是有用的证据，但仅凭这一点并不代表工作已准备好作为团队记忆提交。

停止线工作流

使用 agent_authority 和当前用户指令来确定收尾边界。不要把“工作已实现”视为自动获准越过该边界。当前指令覆盖仅适用于本轮；绝不要将其写入 .mainline/config.toml 或 .mainline/local.toml。

1. 运行 mainline preflight --json，建立协作上下文。
2. 读取 .data.agent_authority.current.allowed_boundary 并判断当前用户是否有覆盖指令。
3. 执行工作并进行验证。
4. 仅推进到允许的边界。
5. 遇到硬性门槛时停止。

有效边界取团队策略、硬性门槛和当前指令中限制最低的那个。只有当 .data.agent_authority.team.max_autonomy 允许时，用户的直接请求才可将本轮提升至 review；合并、发布和合并后清理仍属于明确的交付任务，而非自主权限。

当前指令覆盖类别：

指令类别	视为
仅提供建议／只读	降至 assist
完成本地工作／提交／封存／交接	将边界设为 handoff
推送分支／创建或更新 PR	提升至 review，但不超过团队的 max_autonomy
合并／发布／部署／发布软件包／合并后清理	属于明确的交付任务，而非自主权限；确定目标，且只有在用户直接要求、其他硬性门槛也允许时才继续

在有效自主级别为 review，且实现已完成、验证已通过、没有未解决的设计问题，并且提交／封存／PR 是下一个自然边界时，含糊的继续指令才会推进至 PR。否则，继续处理下一个未完成的实现或设计步骤。

提交工作流

Mainline 不规定仓库如何暂存更改、编写提交信息或分组提交。遵循仓库现有的 Git 工作流和提交约定。如果由你创建提交，先检查未暂存和已暂存的差异，并且只包含预期文件。

提交或封存前，重新运行就绪检查：

mainline preflight --json

如果结果为 block，请停止并解决或上报所指出的重叠／偏移问题，不要仅为保持工作区干净或使用过期基准而封存。如果结果只有 warn，请在交接说明中提及警告，并在继续前审慎决定。

封存前，必须先有一个可供 Mainline 引用的提交。Mainline 不会替你创建该提交。

如果有效自主级别为 assist，请在此停止，并报告差异和验证状态。之后，用户可以明确要求你提交并封存；这属于当前指令下的交接。

如果用户要求创建提交或 PR，而分支没有活动意图，除非更改纯属机械性且仓库策略将其标记为跳过，否则应先创建或补充一个意图，再提交。

封存工作流

只有当工作已准备好交接、评审、PR、推送或进入其他团队可见的记忆边界时才封存。不要仅因存在本地实验或中间提交就封存。

除非用户明确要求交接、提交或封存，否则在有效自主级别为 assist 时不要封存。

当仓库中已有预期提交，且工作已准备好达到该交接边界时，准备封存：

mainline seal --prepare --json > .ml-cache/seal.json

.ml-cache/ 已被 mainline init 加入 git 忽略列表，因此临时 seal 文件不会进入 git，也能让 v0.3 的工作树干净检查在提交时顺利通过。程序包包含一个 seal_result_starter 字段，其中已预先填入确定性内容（intent_id、fingerprint.files_touched、fingerprint.subsystems）——根据实际情况补充 title / what / why / decisions / rejected / acknowledged_constraints / review_notes / fingerprint / confidence，而不是从头开始编写 JSON。

Seal 默认记录决策。seal 摘要写入架构不包含创建持久信号的字段，例如旧版 summary.risks、summary.followups 或 summary.anti_patterns；包含这些键的旧临时 seal 文件会被拒绝，应使用 mainline seal --prepare --json 重新生成。

仅当来源真实可靠时，才使用明确的信号命令：

• 仅当存在具体的故障模式（含触发条件或影响），以及缓解措施 / 验证方式 / 负责人时，才使用 mainline risks add。
• 仅当用户明确推迟了工作、存在外部问题 / 工单 / PR，或此 PR 明确删减了实际范围时，才使用 mainline followups add。
• 请勿自行创建约束。mainline guard add 采用交互式操作，且需要人工确认。

如果你掌握的内容只有评审上下文、验证说明、已接受的权衡、范围说明或“也许以后再做”的想法，请将其保留在 review_notes、decisions、最终回复中，或直接省略。可以向用户提出候选约束，但只有经人工确认的 guard 命令才能将其设为持久记录。

生成符合返回架构的 SealResult JSON。指纹必须足够具体，以便检测冲突：

• summary.decisions 是对象数组（point、chose、可选的 rationale、可选的 rejected 字符串数组），而不是字符串数组。
• summary.rejected 是对象数组（alternative、可选的 reason）；如果没有顶层被拒绝的替代方案，请保留为 []。
• summary.review_notes 是字符串数组；如果没有临时评审上下文，请保留为 []。
• fingerprint.api_changes 和 fingerprint.data_model_changes 是对象数组；如果均不适用，请保留为 []。
• 子系统和父级概念
• 修改的文件
• 架构方面的声明
• 行为变更
• API 或 CLI 变更
• 数据模型变更
• 安全影响
• 迁移说明
• 标签，包括同义词和相关技术

提交 seal：

mainline seal --submit --json < .ml-cache/seal.json

如果工作树中有无关的已修改或未跟踪文件，且因其属于用户而无法清理，请仅在说明 Mainline 会永久记录这些未清理状态后使用 --allow-dirty：

mainline seal --submit --allow-dirty --json < .ml-cache/seal.json

如果响应包含 conflicts，请将其视为第 1 阶段的重叠警告，而非语义冲突判断。结束前请检查并分类：对于相邻、互补或已纳入考虑的重叠，仅在有用时用简洁的自然语言概述；默认不要粘贴原始 JSON。如果无法对警告分类，或警告看起来像是真正的语义冲突，请向用户升级处理，并提供相关意图、可能冲突的原因以及建议的后续操作。仅当用户要求调试详情，或工具输出本身是诊断故障所必需时，才包含原始 JSON。

如果提交 seal 已在本地完成，但因网络中断而发布失败，请稍后重试：

mainline publish --intent <intent_id> --json

这是元数据发布，不是产品发布或部署。它只会重试发布已封存的 Mainline 意图状态。

不要将 mainline abandon 作为修复 seal 措辞、lint 警告或 rebase/amend 后提交哈希偏移的常规手段。仅在取消或拒绝这项工作时使用 abandon；如果已提交的 seal 有误，请报告问题，并与用户选择明确的修复或替换方案。

发布、推送和 PR

Mainline 不要求执行 Git 推送、创建拉取请求或使用 GitHub。除非用户明确要求更改，否则请保留仓库现有的评审和发布工作流。

有效的 handoff 自主权限止于推送代码分支或创建／更新 PR 之前。有效的 review 自主权限可以推送非 main 分支并创建或更新 PR，但仍止于合并、发布或合并后的清理之前。如果当前分支是 main，请先创建或切换到非 main 分支，再进行推送或创建 PR；review 自主权限绝不允许执行 git push origin main。

在进行用户要求且符合停止边界的任何远程分支推送或 PR 创建之前，请确保意图已提出或可发布：

mainline status --json
mainline publish --intent <intent_id> --json

如果用户的工作流会创建或更新 PR，请根据已封存的 Mainline 意图生成 PR 正文：

mainline pr-description --intent <intent_id> > .ml-cache/pr-description.md

将生成的 Markdown 用作 PR 正文。存在已封存的意图时，不要手动编写替代的 PR 描述，也不要依赖通用 GitHub 发布辅助工具的默认正文。生成的正文包含 mainline:pr-description 标记；PR 意图评论工作流会使用该标记来避免创建重复的置顶评论。

在调用任何 GitHub 发布辅助工具、连接器或 gh pr create 后备方案之前，请检查生成的文件并确认它仍包含 ``。将该文件的准确内容作为 PR 正文传入。不要只复制可见的 Markdown，不要重新生成一个相似的正文，也不要让发布辅助工具使用 --fill／默认文案覆盖正文。 对于 gh 后备方案，安全的格式如下：

gh pr create --body-file .ml-cache/pr-description.md

存在已封存的意图时，不要使用 gh pr create --fill 或任何连接器的默认正文。

如果用户没有要求推送或创建 PR，请在封存／发布 Mainline 意图后停止，并报告本地结果。不要仅仅因为 Mainline 元数据已就绪，就引入远程工作流。

除非用户明确要求，否则不要运行以下命令：

mainline pin <intent> <commit>
mainline init --rewire
mainline doctor --setup --fix

评审和冲突工作流

在用户要求评审 Mainline 状态、解释之前的工作或判断冲突标记时，使用以下命令：

mainline log --json --limit 30
mainline show <intent_id> --json
mainline trace <intent_id> --json
mainline check --prepare --intent <intent_id> --json
mainline check --submit --json < judgment.json

使用 show 了解决策和风险。使用 trace 了解工作是如何展开的。仅当检查过的第一阶段重叠确实存在且可能相互矛盾时，才使用 check。相邻或互补的重叠应作为判断记录在 append／seal 中，而不是升级为 check。

覆盖范围和补救

如果 status 或 gaps 报告存在未覆盖的提交：

mainline gaps --json

选择破坏性最小的补救路径。这些是恢复选项，并非用于替代仓库的常规 Git 工作流：

• 如果提交在本地且尚未推送，可以使用 git reset --soft HEAD^ 撤销提交，启动适当的意图，按照仓库的常规工作流重新提交，然后封存。
• 如果提交已推送，可以使用 mainline start "<why>" --commits <sha> 补录意图，追加事后说明，然后封存。
• 如果该提交属于常规操作且有意排除在 Mainline 之外，可以添加 Mainline-Skip: 尾注，或配置跳过模式。

除非用户明确要求，否则不要改写已发布的历史记录。

技能分发

使用 npx skills 为支持的目标 Agent 安装此技能：

npx --yes skills add mainline-org/mainline --skill mainline --agent codex claude-code cursor pi --global --yes

从此仓库进行本地开发时：

npx --yes skills add ./skills/mainline --skill mainline --agent codex claude-code cursor pi --global --yes

mainline init 会尽力安装默认技能和钩子。mainline agents update 或 mainline init --rewire 不会刷新现有的全局技能安装；请使用以下命令显式刷新：

npx --yes skills update mainline --global --yes

如果 update 无法确定来源，请重新运行上面的匹配 skills add 命令。此技能的长远目标是教会 Agent 正确安装、初始化、使用、发布和评审 Mainline 意图数据。