企业官网建设流程全解析

oh-my-pi 维护者指令驱动的 Issue 处置：深度解析 robomp 的 kickoff_directive 提示模板

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi

本篇文章聚焦 oh-my-pi 自托管 GitHub 分诊机器人 robomp 在"维护者通过 @ 提及直接下达处置指令"场景下的会话启动模板 kickoff_directive.md，剖析其模板变量、权威性语义、三路工作流分支、分类前置约束与副作用边界，并结合 persona.py、worker.py、host_tools.toml 与 test_persona.py 给出源码级实现佐证。读完你将掌握 robomp 提示模板体系的装配机制，以及"维护者指令如何覆盖默认分类停驶规则、强制先分类、再按指令类型执行并仅通过 gh_* 宿主工具落盘副作用"的完整链路。

一、背景：robomp 与三线会话启动模板

robomp 是 oh-my-pi 仓库python/robomp/下的自托管 GitHub 分诊机器人（详见 README.md）。它以子进程方式驱动omp --mode rpc运行在"每个 Issue 独立 git worktree"之上，再通过持有 PAT 的 sidecar（gh-proxy）把结果写回 GitHub。

robomp 的提示词体系位于 python/robomp/src/prompts/，按任务类型拆分为多份 kickoff / followup 模板。其中与"新 Issue 会话启动"相关的有三条主线：

• kickoff_issue.md：普通新 Issue 的标准三线入口，强制"先分诊再行动"；
• kickoff_directive.md（本文主体）：维护者已通过 @ 提及下达明确指令时的入口，指令具有权威性，可覆盖默认的分类停驶规则；
• kickoff_pr_review.md/kickoff_release.md：分别面向 PR 评审与发布哨兵会话。

此外，对"已经分诊过的线程"上的后续指令，robomp 使用另一份模板 directive.md，它不再要求分类（原文明确写道classify_issue, set_issue_labels: unavailable; originating issue already triaged.）。kickoff_directive.md与它最大的区别，正是保留了"先分类再执行"的硬性约束——这一点在模板第 25 行以 MUST 强调，对应测试 test_kickoff_directive_prompt_embeds_thread_and_classify_instruction 中assert "Classify first" in out的断言。

二、模板骨架逐字段解析

kickoff_directive.md是一份基于 Jinja 风格{{ }}变量的提示模板，会话启动时由persona.kickoff_directive()渲染（persona.py）：

def kickoff_directive( *, repo: RepoInfo, issue: IssueInfo, workspace: Workspace, directive: Any, ) -> str: """Kickoff for an untriaged issue that arrived via a maintainer mention.""" return render( _load("kickoff_directive.md"), { "repo": repo, "issue": issue, "workspace": workspace, "directive": {"body": directive.body, "author": directive.author}, "thread": _render_thread(getattr(directive, "thread", ()) or ()), }, )

模板开头的元信息块提供了 Agent 判断上下文所需的全部标识：

其中{{thread}}由 persona.py 的_render_thread渲染：它对issue_body/pr_body/review_comment/review/ 普通comment分别生成带@author、时间戳、文件路径锚点（path:Ln）的 Markdown 块；当没有历史消息时输出(no prior conversation)。测试中该字段被验证为可嵌入failing on macos这类原始评论内容。

三、指令的权威性：覆盖默认分类停驶规则

模板第 9 行是整份文件语义的基石：

@{{directive.author}}tagged you. Their directive authoritative; overrides default classification stop rules:enhancementnormally waits foraccepted, but this directive permits proceeding.

在默认分诊流程（kickoff_issue.md）中，enhancement/proposal类的处置是"发表一条有深度的评论后停手，不建 PR"——这是分类停驶规则（classification stop rules）。但当维护者通过 @ 提及下达指令时，该指令被视为权威：即使 Issue 当前标签是enhancement，只要指令要求推进，Agent 就获得了继续执行的许可。

需要强调的是，这种"覆盖"仅针对停驶/等待规则，绝不豁免分类动作本身（见下节）。这一点在directive.md（已分诊线程）与kickoff_directive.md（未分诊线程）之间形成了精确的分工：前者因线程已分诊而禁用classify_issue，后者则明确要求必须先分类。

四、第一原则：执行任何副作用前 MUST 先分类

模板 "What to do" 第 1 步的措辞是全文最硬的一条约束：

Classify first. MUST callclassify_issue(primary=..., priority=..., functional=[...], rationale=...)before any other side effect, even if directive states answer. Labels: org triage.

即使指令内容已经写明了答案（even if directive states answer），Agent 依然必须在产生任何副作用之前先调用classify_issue。这一"先分类、后执行"的顺序性由 worker 侧强制：在 worker.py 的_build_prompt中，triage_issue任务在resuming为假且directive非空时选用persona.kickoff_directive，否则退回普通persona.kickoff——两条路径的分流恰好让"是否带指令"决定 Agent 拿到哪份提示，但无论哪份，classify_issue都是首个动作。

classify_issue的参数契约定义在 host_tools.toml：

• primary：主分类，必填且唯一；
• priority：仅当primary=='bug'时必填，取prio:p0..p3；其他主分类必须省略该字段，编排器会静默丢弃多余值；
• functional：零或多个功能标签，未知值被静默丢弃；
• provider/platform：仅在适用时提供（provider:<name>、platform:linux|macos|windows|wsl）；
• rationale：一句话说明分类依据；
• branch_slug：仅bug/documentation场景提供，用于替换自动生成的工作分支 slug（1-50 字符[a-z0-9-]，不允许首尾或连续连字符）。

分类的同时，classify_issue会调用set_issue_labels把标签落到 GitHub 上——后者有一项不可撤销的纪律：只追加、绝不删除已有标签（Append labels to the originating issue/PR. NEVER removes existing labels.）。

五、三路工作流分支：如何执行一条指令

模板 "What to do" 第 2 步根据指令类型给出三条互斥的执行路径：

5.1 代码变更（Code change）

Code change → commit on{{workspace.branch}}; thengh_push_branch+gh_open_pr. Both runbun run fix, thenbun check, against worktree;gh_open_pralso runs the repo's fullbun run testand refuses while it is red.

流程为：在{{workspace.branch}}上提交 →gh_push_branch推送 →gh_open_pr建 PR。两条工具都带有发布前门禁：

• bun run fix：先跑格式化，任何格式化 diff 会被 amend 进 Agent 的 HEAD 提交，不产生独立的style:噪音提交（README Security posture 一节明确说明）；
• bun check：类型/静态检查，失败则修复后重试；
• gh_open_pr额外运行仓库完整bun run test（1 小时预算），套件红灯则拒绝开 PR——套件在格式化 amend 之后运行，因此校验的正是将要发布的那个确切 tree。

PR 正文必须逐字使用四段模板，这与 host_tools.toml 中gh_open_pr的参数契约 完全一致（body参数：MUST contain## Repro/## Cause/## Fix/## Verificationin order），README 还补充了第五个要求：正文必须带Fixes/Closes/Resolves #N的引用，缺任一条件则拒绝开 PR。

若门禁失败，模板要求"修复原因后重新调用"；只有确认失败是main上预先存在、与本 diff 无关时，才允许skip_checks=true绕过，且必须在## Verification中记录绕过理由。完成后回复方式为单条gh_post_comment并附 PR 链接。

5.2 提问 / 澄清（Question / clarification）

Question / clarification → onegh_post_comment. No branch or PR.

只发一条评论，不建分支、不建 PR。

5.3 显式停止 / 忽略（Explicit stop / ignore）

Explicit stop / ignore → one acknowledginggh_post_comment; halt.

发一条确认收悉的评论后立即停止。

5.4 指令含糊：绝不猜测

Ambiguous directive → one clarifyinggh_post_comment; stop. NEVER guess.

指令存在歧义时，只发一条澄清评论并停止。NEVER guess是模板的硬性禁令；这一原则同样体现在宿主工具层——abort_task的说明强调它只能用于编排器/环境缺陷（损坏的权限、缺失系统工具、损坏的 git 元数据、harness bug），"失败的构建和不清晰的维护者请求"必须走gh_post_comment，从而堵住了 Agent 用 abort 逃避澄清的路径。

六、副作用边界：只能通过 gh_* 宿主工具

模板倒数第二节是全文的安全红线：

All side effects MUST usegh_*/classify_issue/set_issue_labels. NEVER shell out toghorgit push.

Agent 对 GitHub 的一切写操作（评论、推送、开 PR、加标签、记录 repro）都只能通过 robomp 暴露的宿主工具完成，绝不允许在子进程里直接执行ghCLI 或git push。这套设计背后的信任边界在 README.md 的 Architecture 与 Security posture 中有完整交代：

• 双容器单信任边界：robomp 持有 HMAC 密钥但永不持有 PAT；gh-proxy 持有GITHUB_TOKEN，只验证 HMAC 签名请求并执行 REST +git push，仅允许访问api.github.com；
• 编排器拒启：robomp 若在自己的环境里看到GITHUB_TOKEN会拒绝启动；Agent 子进程环境通过worker._SCRUBBED_ENV_KEYS清除GITHUB_TOKEN/ROBOMP_GH_PROXY_HMAC_KEY等敏感项；
• 全量审计：每次宿主工具调用都会记入tool_calls表，参数与结果做凭据脱敏（host_tools._audit只记录 Agent 提供的参数）；
• git 错误脱敏：git_ops.GitCommandError会把 argv/stdout/stderr 中的https://user:pw@host脱敏为https://***@host后再抛出。

推送前还有身份与树状态双重门禁（gh_push_branch）：分支必须与工作区分支一致、工作树必须干净、origin/<default>..HEAD上的每个提交都必须带有ROBOMP_GIT_AUTHOR_NAME+ROBOMP_GIT_AUTHOR_EMAIL；Agent 用git commit -m 'a\n\nb'产生的 shell 字面\n会被改写成真实换行（仅消息改动，tree/身份/日期不变）。

七、渲染与装配的实现纵深

kickoff_directive.md的装配链路由两层完成：

1. persona 层：persona.kickoff_directive()接收 duck-typed 的directive（任何具有body、author、thread属性的对象皆可，worker.DirectiveInfo即其一），将模板变量注入后经render()输出完整提示。函数 docstring 注明"lazily imported to avoid a persona → worker circular dependency"，render拿到directive.thread后经_render_thread转成 Markdown。

2. worker 层：_build_prompt依据任务类型与上下文做分派——triage_issue+ 非续跑 + 有指令 →kickoff_directive；续跑 →resume_triage；无指令 → 普通kickoff。这说明同一份工作树与 Issue 信息会被复用进不同模板，提示模板的选择完全由"是否带维护者指令"这一状态驱动。

装配的端到端验证落在 test_persona.py：构造一条issue_body类型的历史线程（作者alice，正文failing on macos）与DirectiveInfo(body="reproduce + fix", author="can1357")，断言渲染结果同时包含仓库标识octo/widget#1080、历史评论原文、指令正文reproduce + fix，并专门断言了Classify first的存在——即"kickoff 变体也必须先分类"这一契约有测试兜底。

八、风格纪律与可操作性约定

模板末行Terse. Technical. No emoji.是三份 kickoff 模板共用的输出风格约束，直接映射到 README.md 中"PR 正文四段模板、单条评论、每条具体改动一行概括"的回复规范：Agent 的 GitHub 评论保持简短、技术化、无 emoji，从而保证维护者审阅的信噪比。

对运维与二次开发者而言，这条模板链的调试入口也很明确：robomp triage owner/repo#123可人工合成一次issues.opened事件并等待完整处置（见 README.md CLI 一节）；若希望在某仓库上启用这类"维护者 @ 提及即获得处置授权"的能力，需要确认该仓库已加入ROBOMP_REPO_ALLOWLIST，且机器人账号具备Write权限（fine-grained PAT 需 Contents / Issues / Pull requests RW + Metadata R）。

小结

kickoff_directive.md虽然只有三十余行，却是 robomp"维护者指令优先"处置路径的语义中枢：它以最小化的元信息上下文，向 Agent 同时传达了指令权威性（可覆盖分类停驶规则）、分类前置性（任何副作用前 MUSTclassify_issue）、三路互斥工作流（变更 / 提问 / 停止）、PR 四段模板与门禁链（bun run fix→bun check→bun run test）以及副作用边界（仅gh_*，禁止 shell out）。配合 persona.py 的渲染函数、worker.py 的分派逻辑与 host_tools.toml 的工具契约，可以完整还原一条"维护者提及 → 强制分类 → 分诊 → 修复 → 门禁 → PR → 单条评论回执"的自动化闭环——这也是 robomp 将自主 Agent 行为约束在可审计、可回滚边界内的核心机制之一。

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi