myorch 流程手册

这本手册讲每个流程：做什么、什么时候用、每一步做什么、什么时候需要你。平台本身（服务、架构、命令、项目包、流程语法）在使用手册里。

每个流程一章。章里的输入表、步骤图和步骤明细都从 flows/*.yaml 生成，和 myorch expand、控制台「流程」看到的一样，所以不会和流程定义对不上。其余文字写在流程旁边的 flows/<流程>.md 里，英文版在 docs/en/flows/<流程>.md。改了流程或它的 .md 以后，重新生成（中英文手册一起生成）：

uv run --with markdown python docs/workflows/build.py

所有项目共用一套流程

每个角色只有一个流程（flows/development.yaml、review.yaml 等），所有项目共用。项目之间的差别写在项目包 myorch-knowledge/<项目>/ 里，展开流程时生效，发起时不用选：

• project.yaml 的 flows.development：review 有多重（reviewers、max_rounds、security、on_exhausted），要不要提交 takeaway（takeaway），有没有 incident 输入（incident）。不写时用默认值：3、3、true、ask、false、false。
• prompts/<槽位>.md：项目自己的 prompt 条款，槽位有 develop、review、verify、fix、risk。展开时原文拼进对应步骤的 prompt，先放模板的，再放项目的。
• jira：有 Jira 时，开发流程有工单输入和 fetch-ticket，工单就是需求；没有时第一条消息就是需求。
• 流程里的 if: 按项目裁掉步骤和输入。裁掉的输入在表单里看不到。

• 每个项目怎么走开发流程，见 development 的「按项目的不同」。
• 改某个项目的做法，改它的项目包，然后 uv run myorch project sync <项目>。改 flows/ 下的流程或片段，所有项目都受影响。
• 流程文件开头写 role:（角色）。myorch 按角色认流程，不按名字。例如「在这个分支上接着改」对 development 角色的运行都有效，eval 回放用 eval 角色的流程。
• 2026-11-03 到 2026-11-10 之间，流程按项目复制过（ck-、blog-、mo- 前缀）。现在合成了一套，原因见 docs/notes/2026-11-10-one-set-of-flows.md。旧运行（例如 ck-development-…）照样能看、能接着改。

角色

什么时候用哪个

发起一个运行

• 字段由流程文件的 inputs 定义：标签、提示、是否必填、类型。类型有文本、消息、下拉选项、工单号（MD-18700 和 18700 都可以）、运行（从这个项目已结束的运行里选）。每章的「输入」表列出了它们。
• 消息框写什么也由流程定义，可以按项目不同。development 在有 Jira 的项目（mdm）里，需求在工单里，消息是可选的补充说明；blog 和 myorch 没有工单，消息就是需求，必填。
• 工单输入和输入里的工单号会自动成为运行的标签，运行列表可以按标签搜。
• 发起前，客户端读流程、按 presets 选参数、展开片段、填入项目值、检查。写错了直接报错，不会启动。想先看展开结果：uv run myorch expand flows/<流程>.yaml --project <项目>。

你介入的地方

流程在下面几种地方停下来等你。控制台顶栏的「等你处理」和 uv run myorch list 都会列出来。Slack 线程里有同样的按钮。步骤图里琥珀色的卡片和「可能问你」标记就是这些地方。

• 提问等太久会超时失败，默认 24 小时。
• 批准绑定提交。批准之后代码变了，交付会拒绝推送，必须重跑。
• 提修改意见把运行送回审批前的循环（例如 review-fix）再跑一轮，你的意见会给到修复的 agent。
• 本机 Claude Code 会话能回答提问、从失败的步骤继续，不能审批。

在原分支上接着改

用于 development 运行结束以后：自测发现了问题，或者要在这次改动的基础上再改。在控制台里打开那个运行，点「在这个分支上接着改」，第一条消息写这次要改什么。命令行用 -i from_run=<运行 ID>。

• 选的运行必须已经结束，属于同一个项目，角色也是 development。没给工单号时，沿用上一次的。
• 新运行用同一个分支名，推送后更新的是同一个分支，所以人开的 PR 也跟着更新。
• 从那个分支的最后一个提交开始。远端分支上有人追加了提交时，从远端的最新提交开始。两者分叉时停下来，要人先处理。
• 上一次的需求、设计、实现记录、风险判定、交付说明和最后一轮 review 结论放在 docs/previous/。agent 在它们的基础上写，并单独写明这次改了什么。更早的几次在 docs/previous/earlier/ 里，一层套一层。
• 人对上一次运行说的话放在 docs/previous/conversation.md：agent 问过的问题和人的回答、修改意见、批准或驳回时的意见，以及失败和重新执行。事件日志在宿主机上，sandbox 读不到，所以发起时（命令行、控制台、Slack 都一样）由宿主机写进新运行。agent 把它当作人的决定，和上一次文档里的假设冲突时以它为准。
• 后面的实现、review、审批照常走。第 1 轮 review 只看这次新加的提交，检查和风险判定看整个分支相对 base 的改动。细节见 development 的「接着改」。

看懂步骤图

• 从上到下是执行顺序。同一行的步骤并行。一张卡片等的不是上一行的全部步骤时，卡片下面写「等 …」。
• 卡片第二行是执行者：agent（模型 · profile）、脚本（profile）、宿主机动作（注册过的确定性动作，不进 sandbox）、审批。profile 决定 sandbox 的权限，见使用手册 · 7. 项目包。
• 左边有蓝条的是 agent。斜线底的是宿主机动作。琥珀色是需要你的地方：审批卡片，和标着「可能问你」的步骤。
• 虚线外框是有条件的步骤或循环。鼠标停在「有条件」上能看到表达式。
• 方框是循环：标题写最多几轮、什么时候停、跑满了怎么办。底部的反思步骤只在跑满且要问你时执行，给出建议。
• 「×3 并行」表示同一个步骤起 3 个实例（例如 3 个 reviewer）。
• 图按 mdm 和默认输入展开（mdm 的开发流程步骤最全）。换一个项目，项目包可能裁掉一些步骤、换掉参数（例如 blog 的 review 只有 1 个 reviewer），条件里的项目值也可能不同。用 myorch expand flows/<流程>.yaml --project <项目> 或控制台「流程」看某个项目的展开结果。点开图下面的「每一步的执行者、条件、输出」看完整的表达式。

改流程

1. 改 flows/<流程>.yaml 或片段。写法见使用手册 · 8. 写流程。
2. uv run myorch expand flows/<流程>.yaml --project <项目> 看展开结果。
3. 同步改 flows/<流程>.md 和 docs/en/flows/<流程>.md，重新生成这本手册。
4. 跑一次 uv run pytest。worker 和控制台在 compose 里时，docker compose -f deploy/compose.yaml up -d --build 让它们读到新的流程。

本页源文件： docs/workflows/README.md

development 开发

开发流程：从一个需求做到推送分支。所有项目共用这一个流程。它在一个会话里写需求、技术设计、改代码，再经过 review、风险判定和人工审批，最后把批准的那个提交推到这次运行的分支。myorch 不开 PR，也不合并：PR 由人在 GitHub 上开，合并也由人决定。审批之前改动不离开沙箱，什么都不推送。

项目之间的差别都在项目包里，发起时不用选（见按项目的不同）：

• review 有多重：几个 reviewer、最多几轮、要不要单独的 security、跑满以后怎么办（project.yaml 的 flows.development）。
• 有没有 Jira：有时先由 fetch-ticket 读工单，工单就是需求；没有时第一条消息就是需求。
• 要不要把任务信息和经验（takeaway）提交到仓库的 myorch/ 目录（flows.development.takeaway）。
• 有没有 incident 输入：平台出了问题时，把出问题的运行挂给 develop 看（flows.development.incident）。
• 项目自己的 prompt 条款（prompts/develop.md、review.md、verify.md、fix.md、risk.md），展开流程时原文拼进对应步骤的 prompt。

uv run myorch run flows/development.yaml --project mdm -i ticket=18700
uv run myorch run flows/development.yaml --project mdm -i ticket=18700 -i task="只改后台接口，前端另开工单"
uv run myorch run flows/development.yaml --project blog -i task="给文章页加字数统计"
uv run myorch run flows/development.yaml --project myorch -i task="..." -i incident=development-1a2b3c4d
uv run myorch run flows/development.yaml --project mdm -i from_run=<上一次的运行 ID> -i task="自测发现：批量导入时没有校验"
uv run myorch run flows/development.yaml --project mdm -i ticket=18700 -i at=<PR 的 merge-base> -i ticket_as_of=2026-10-01T08:00:00Z

控制台：先选项目，任务选「开发」。表单只显示这个项目用得上的字段。

• 有 Jira 的项目（mdm）：填工单号（MD-18700 或 18700）。第一条消息是可选的补充说明：写工单里没有的重点和限制。
• 没有 Jira 的项目（blog、myorch）：第一条消息就是需求，必填，可以写多行。
• myorch：平台在某次运行里出了问题时，在「出问题的运行」里填那次运行的 ID。本机 Claude Code 会话发现平台问题时，也用 channel 工具 start 发起，第一条消息写看到的现象和初步分析。

消息的第一行成为 task，全文写进 docs/external/request.md。

输入

步骤图

从 flows/development.yaml 生成，按项目 mdm 和默认输入展开（别的项目的项目包可能裁掉步骤、换掉参数），和 myorch expand、控制台「流程」看到的一样。

上面的图按 mdm 展开，步骤最全。blog 和 myorch 没有 fetch-ticket 和 takeaway 四步，blog 的 review 循环只有 1 个 reviewer、没有 security。

每一步做什么

• develop 判断不需要改代码（proceed 为 false）时，后面的步骤全部跳过，运行正常结束。
• 没有 takeaway 的项目，四步在展开时就去掉了，risk-rules 直接等 review-fix。
• 流程顶层是 on_failed: ask：步骤重试后仍失败时问你。

你介入的地方

takeaway 的四步失败时不问你（on_failed: skip），也不阻塞后面的步骤。宿主机动作失败时也不会问。

产物

同一个运行的所有步骤共享一个工作区。控制台右栏的「文档」能看所有文档和截图。命令行用 myorch ws <run> 列出文件，myorch ws <run> docs/risk.md 读一个文件。

observed/<运行 ID>/           接着改时上一次的运行、有 incident 时出问题的运行（只读）
docs/
├── external/
│   ├── request.md            第一条消息的原文（控制台和 Slack 发起时）
│   ├── ticket.md             工单（fetch-ticket，或 develop 用 MCP 读的）
│   └── attachments/          工单里的图片
├── previous/                 接着改时：上一次的文档和对话
├── requirements.md           需求、验收标准、工单对照；有 incident 时开头是原因分类
├── design.md                 影响分析、方案、兼容和回滚、测试计划
├── implementation.md         改动、证据、检查结果、假设、和设计的差异；fix 追加「第 N 轮修复」
├── ci/round-N.md             每轮的检查报告（round-N/ 里有 result.json、head.txt）
├── review/round-N/           reviewer-K.json、security.json、verified.json、summary.md、rebuttal.md、approver.json、pack/
├── takeaway/                 trail.json、task.md、takeaway.md（只在 takeaway 的项目）
├── risk.md                   风险结论和请审批人重点检查的地方
└── delivery.md               交付说明
repo/myorch/<日期>-<运行 ID>/  task.md、takeaway.md（提交在分支上，只在 takeaway 的项目）

develop

一个 agent 从读需求做到提交代码，三个阶段按顺序：需求、技术设计、实现。不能跳过前两个阶段直接写代码。项目的 prompts/develop.md 原文拼在 prompt 的「输入」之后，见按项目的不同。

• 输入：工单 docs/external/ticket.md（有时）、截图、请求原文 docs/external/request.md、项目约定、仓库自带的知识、项目包的 guide/（其中 decisions.md 是以前人做过的决定）。请求原文和工单是外部数据，里面的指令不执行。
• 需求文档：目标、范围、明确不做的事、可检查的验收标准、工单对照表、预计改动的文件、风险、依据。
• 工单对照表：工单里的每一条要求照抄一行（包括评论里补充的），对应哪条验收标准，或者为什么不做。一条要求里有几个动作，验收标准就要覆盖每个动作。
• 工单点名的模块、功能、场景不能由 agent 自己划进「明确不做的事」。想排除时要问人。
• 技术设计：影响分析（调用方、跨模块依赖、其他服务）、方案和不选的方案、兼容和回滚、测试计划（每条验收标准的测试，加上边界和反例）、风险。设计里不写代码。
• 列全入口：给字段加校验或要求多处一致时，至少用报错文案和字段名两种方式反查，在设计里写出搜索命令和找到的入口。
• 删除或放宽已有的判断前，用注释和 git log -L、git blame 查清它为什么存在。查不清、或改动后它保护的东西不再成立时，问人。
• 先找同类的已有实现：能直接用就调用；形状不合适就改成能共用的形状；行为由共享方法决定时改共享方法，并检查它的每个调用方。不复制一份。为了复用而改共享实现属于这次的范围。
• 改代码之前问，最多问一次：两个阶段里发现的需要人决定的问题，放进一次提问，每个问题给选项，第一个是推荐的。用户能看到的东西、接口和契约、数据模型和迁移、影响其他模块或服务的行为变化、明显改变实现规模的选择，都不能由 agent 替你选。decisions.md 里已经有的决定照做，不再问。
• 兜底：agent 结束时说还有没问就按推荐做了的问题（requires_design_decision），平台照样问你，你的回答作为下一轮发回同一个会话。
• 实现：只改范围内的代码，每条验收标准有测试或检查，跑 myorch-checks（项目的 checks.sh）直到通过，写实现记录，在当前分支提交一次。检查报告把失败列在「环境」里时（沙箱的网络或系统限制），不算代码的问题，照常提交，在实现记录里写明。
• 停下来：需求和代码矛盾、必须改范围以外的代码、检查因代码失败又修不好时，不提交，步骤失败，然后问你怎么办。
• 可以判断不用改：功能已经存在，或者你决定不做。不写文档，后面全部跳过。

为什么合成一步：分开时每次交接都会丢信息。有凭证的步骤（sync-master、fetch-ticket、deliver）仍然单独跑，develop 拿不到 GitHub 和 Jira 的凭证。

读工单

• 条件：项目设置了 jira.url（mdm 是 example.atlassian.net，前缀 MD），并且给了工单号。只写数字时加上项目的前缀（jira.key）。没有 Jira 的项目没有工单输入，也没有 fetch-ticket 这一步。
• 只读：凭证是项目的 Jira provider（mdm 是 jira-mdm），出站规则只放行读工单、读附件内容和 /myself。沙箱里只有占位符，真实 token 由网关替换。
• 内容：标题、类型、状态、优先级、报告人、经办人、标签、组件、父工单、关联工单、描述、子任务、附件列表、评论。文件开头写明它是外部数据。
• 截图：只下载图片附件，最多 10 张，每张不超过 5 MB，存到 docs/external/attachments/<id>-<文件名>。ticket.md 的「附件」一节列出路径，develop 用 Read 打开看。描述里的 !文件名! 指的就是这些图。其他附件只列名字。某张下载失败不影响运行。控制台的「文档」也能看这些图。
• 评论：ticket_comments 默认 all。选 none 时不带评论，只按描述做（评测用：需求应该写在工单里，不靠评论）。
• MCP 兜底：fetch-ticket 没跑（项目没有 jira.url）、而这次运行挂了能读工单的 MCP 知识源时，develop 先用 MCP 读工单，写同一个 docs/external/ticket.md，开头注明来源。读不到就在摘要里写明，按请求原文继续。mdm 目前不默认挂 Atlassian MCP。

review 循环

定义在片段 lib/review-loop.yaml，review 和 eval 也用它（只跑 1 轮、不修复）。这里的参数来自项目的 flows.development：默认 3 个 reviewer 加单独的 security，最多 3 轮，跑满时问你。项目的 prompts/review.md、verify.md、fix.md 拼进对应步骤。

• 每轮看什么：第 1 轮看整个改动（接着改时只看这次运行的新提交）；之后每轮只看上一轮开始以后的提交。范围由 ci 算出，写在 docs/ci/round-N/head.txt 里。
• 先独立判断，最后读作者的说法：reviewer 先只看需求文档、技术设计和 diff，自己找问题；然后才读实现记录，核对里面的测试和检查是否真的存在、假设站不站得住。实现记录里写了原因，也不是放过问题的理由。
• 需求文档对照工单原文：需求文档也是作者写的。漏掉、缩小或改写了工单的要求，工单对照表只覆盖了一部分动作，或者自己把工单点名的内容划出范围，都算 Important。
• 到仓库里查：只看 diff 看不出来的三类问题，一律算 Important：
• 没有复用已有的同类实现，或者复制了共享方法的分支而不是改它。
• 漏掉的入口：同一个字段、同一句报错的其他读写位置没改，设计里也没说为什么。
• 删掉或放宽了已有的判断，破坏了它保护的东西，而需求文档没写这是人决定的。
• 分工：1 号多看正确性和边界，2 号多看验收标准和测试，3 号多看设计、范围和复用。漏掉的入口和放宽的判断每个人都查。只有 1 个 reviewer 的项目（blog）只有 1 号。
• 读前面步骤的过程：fix 和 reflect 可以用 /sandbox/bin/myorch-steps 分段读这次运行前面步骤的 manifest 和日志（例如 develop 当时为什么这么做）。reviewer 和 verify 的 prompt 不提它：它们要先独立判断。前面步骤的记录（.myorch/、别的步骤的 .claude/）对每一步都是只读的。
• 规则标记：上面这些「到仓库里查」「先独立判断」「Nit 最多 5 条」之类的条款，是因为模型以前犯过错才加的。它们在流程文件里用 [[rule:<规则>/<位置>]] 标出来，起因登记在 rules/registry.yaml。展开时标记去掉、正文照常保留；只有重放时 --set flows.ablate=<规则> 会去掉整条，用来评测这条规则还需不需要。
• verify：合并重复，逐条打开代码核实，只有一个人报的也核实，不成立的删掉。删掉纯风格意见，Nit 最多留 5 条。每个检查失败项算一条 Important，环境失败不算。上一轮的问题标成 fixed、open 或 rebutted。blocking 是还没解决的 Important 条数，为 0 时循环结束。
• fix：只修 Important，一个问题的所有位置一起改，不碰 Nit。认为发现不成立、或者修复要人决定时，不改代码，写进 rebuttal.md（要人决定的以「需要人决定：」开头），下一轮的 verify 会判断。原因在项目包里时，提项目包修改，见下一节。修完跑检查，在实现记录末尾加「第 N 轮修复」，提交一次。
• 跑满：on_exhausted: ask（默认）时，reflect 读完所有轮次，判断是个别问题、方向错了、需要人决定，还是 reviewer 误判，给出建议，然后问你：再跑一轮、接受当前结果、终止。accept（blog）时直接往下走，最后一轮的修复没人 review 过，risk-rules 会把这些提交列出来。
• 审批人要求修改：意见写进下一轮的 approver.json，每一条都算 Important，verify 不会把它删掉。

项目包的修改（pack-choose、pack-apply）

阻塞问题有时出在项目包里，例如 checks.sh 写错了。项目包在 sandbox 里是只读的（project/），fix 改不了它。这时：

1. fix 不改 project/，也不为它写 rebuttal。它把 project/ 复制到 /tmp，在副本上改，用副本跑一次相关的检查，再把建议写进 docs/review/round-N/pack/proposals.json（机器读）和 proposals.md（给人看，含验证结果）。
2. pack-choose 列出建议，问你采纳哪几条。
3. pack-apply 在宿主机上把采纳的改动写回 myorch-knowledge，只提交这些文件，重新同步项目快照。每条改动的原文必须在文件里恰好出现一次，否则什么都不写，步骤失败。
4. 这次运行的下一轮挂新的快照，用新的项目包检查。别的运行不受影响。最后一轮刚写回时，反思步骤会建议再跑一轮。

只能改 guide/ 下的文件、checks.sh、checks.env、setup.sh（project.py 的 EDITABLE["fix"]）。risk-rules.yaml 和 security.md 不能改：运行不能改变自己的改动怎么被审批。要改别的文件时，fix 写「需要人决定：」。

任务信息和 takeaway

只在项目设置了 flows.development.takeaway: true 时（现在只有 mdm）：仓库里放一个 myorch/ 目录要项目同意。review 循环之后、风险判定之前，四步把这次运行的任务信息和经验提交到仓库。

• 提交在分支上：takeaway-commit 把 task.md 和 takeaway.md 复制到 repo/myorch/<日期>-<运行 ID>/（日期是运行开始的那天），只提交这个目录，提交信息固定为 Add myorch task and takeaway for <运行 ID>。内容没变时不重复提交。审批时能看到，推送后在 PR 里，合并后进 base 分支，learn 从那里读。
• 不阻塞：四步都是 on_failed: skip。失败了记一条失败事件，当作跳过，后面照常。每一步只在上一步给出输出时执行，所以不会提交旧的或写了一半的文件（takeaway-trail 先清空两个文件）。
• trail：每一步的状态、摘要、失败原因、重试次数，问答，review 每轮的 blocking 和检查结果，分支、输入、myorch 提交、项目包版本。像密钥的行在写入前删掉。
• takeaway 写什么：task.md 只写事实（工单、运行、输入、需求摘要、问答、每轮 review 和检查、结果）。takeaway.md 写遇到的问题、根本原因、怎么解决的、缺了什么知识、对流程或平台的建议，每条标类别（项目知识、流程、平台、环境）并给出证据。「缺了什么知识」只写换一个需求也用得上的项目知识，不写这张工单的答案。两个文件合起来不超过 200 行。agent 不挂知识源，只读。
• 读过程：除了 trail.json，takeaway 还可以用 /sandbox/bin/myorch-steps 分段读每一步的日志，找最早走偏的地方。
• 不写密钥：两个文件会进公司仓库。takeaway-redact 按 knowledge.SECRET_RULES（和知识源扫描是同一份规则）删掉像密钥的行。两个文件都空时它失败，提交就不会执行。
• risk-rules 怎么看这个提交：它在最后一轮 review 之后，但不算「没有经过 review 的提交」：只有一个父提交、而且只改了 myorch/ 下 .md 文件的提交不计入。合并提交一律计入。risk-rules 在这个提交之后取 head_sha，所以你批准的、推送的，都是带着这两个文件的提交。
• 不写的时候：重放（at）不写，否则评测案例的答案会进知识。develop 判断不用改时也不写。运行在审批前失败时推不出去，它的经验不在仓库里。

风险和审批

风险由改动决定，不由作者决定。两个分类器互相兜底：规则可能漏掉语义上的风险，模型可能看漏路径上的风险，最后取较严的一个。

risk-rules（确定性脚本）：

• 规则来自项目包的 risk-rules.yaml（模板的规则加上项目自己的），命中的规则里取最严的。规则可以按路径、按新文件里的文字、按改动行的正则匹配。没有规则命中时用 default。
• 下面任意一种情况，至少 1 人：最后一轮 review 还有没解决的 Important；最后一轮检查失败；最后一轮 review 之后有新的提交（例如跑满后接受了，最后一轮的修复没人看过）。takeaway 的提交不算，见上一节。
• 输出 approvers（规则要求的人数）和 available（项目登记的审批人数）。

classify-risk（agent，只读）：读实际的 diff、需求文档、实现记录里的假设、最后一轮 review 和检查、没经过 review 的提交，判断 0、1 或 2 人。改接口或数据、改构建部署、和安全有关、难以撤回、影响下游，任意一条就是 2 人。写 docs/risk.md：结论、影响范围、没解决的问题、请审批人重点检查的 3 到 5 处。项目的 prompts/risk.md 拼在 prompt 末尾（myorch 用它规定「影响范围」按平台的边界、未结束的运行、部署来写）。

human-review 的人数：

min(项目登记的审批人数, max(risk-rules 的人数, min(classify-risk 的人数, 2)))

• 三个项目现在都只登记了一个审批人，所以人数最多是 1。
• mdm：core-ng 模板默认 1 人，数据库迁移、接口模块、构建和依赖、CI 和部署、环境配置、实体字段注解、破坏性 SQL 是 2 人；mdm 的 protos 子模块 2 人、规格文档 1 人。所以每次都要恰好 1 人。
• blog：default: 1，每次都要 1 人。
• myorch：default: 0，平台的边界（sandbox、凭证、profile、部署、调度和审批的代码）要 2 人。两个判断都给 0（例如只改了文档）时自动通过，deliver 直接推送分支。推送的只是分支，合并和部署要人做。
• 发起人必须是审批人之一（require_initiator）。agent 的批准不算数。
• 审批绑定提交：打开审批时记下 head_sha，deliver 推送前核对。
• 要求修改：回到 review-fix，最多再跑 2 轮。之后 takeaway、风险判定、审批从头再走一遍。
• 24 小时没人处理，发一次提醒。7 天没人处理，这一步失败（「审批超时」），什么都不推送。
• 任何一人驳回，运行终止。

交付

定义在 lib/deliver.yaml。

• 当前分支是 base 分支时拒绝推送。HEAD 不等于批准的提交时拒绝推送，要重新运行、重新审批。
• 推送分支（普通推送，不强推），不调用 GitHub API，不开 PR。
• 写 docs/delivery.md：标题和工单、改了什么（取自实现记录的「改动」）、怎么验证的（检查结果、验收标准表）、review 轮数和没解决的问题、没经过 review 的提交、风险结论和重点检查项、怎么撤回。
• outputs.delivery 带上分支、base、提交、标题、工单、交付说明和仓库的 PR 模板。run_finished 事件带着它，控制台和 Slack 据此告诉你推送了哪个分支。PR 由你开。

接着改（from_run）

通用的做法见 在原分支上接着改。这个流程里：

• checkout-branch 只读挂载上一次运行的工作区，从它的最后一个提交开始。远端同名分支上有人追加了提交时，从远端的最新提交开始。两者分叉时停下来，要人先处理。
• 复制到 docs/previous/ 的文件：requirements.md、design.md、implementation.md、risk.md、delivery.md、external-request.md（上一次的请求原文）、最后一轮 review 的 review-summary.md、记录上一次运行 ID 的 RUN，更早的几次在 earlier/ 里。conversation.md 是宿主机写的：人对上一次运行说过的话。
• develop 的需求文档写完整的需求，在「目标」里单独写一段「这次的修改」。上一次的验收标准仍然有效，除非这次的请求改了它。设计在上一次的基础上改。代码在已有提交上改，不重做。conversation.md 里人的决定优先于上一次文档里的假设。
• checkout-branch 输出 since（这次开始时的提交）。review 循环的第 1 轮只看 since 之后的提交，检查仍然跑整个分支相对 base 改动的文件。风险判定看整个分支。
• 推送到同一个分支，已经开的 PR 会自动更新。没给工单号、incident 时沿用上一次的。
• 不能和 at 同时给。

重放（评测用）

用来在当时的代码上重做一张已经合并的工单，再和合并的 PR 对比。表单只对有 Jira 的项目显示 at、ticket_as_of、ticket_comments（命令行对任何项目都能传 -i at=）。平时不填。

• at 填 PR 的 merge-base。checkout-branch 从这个提交建分支，然后删掉 origin remote、其他所有引用、FETCH_HEAD、reflog 和借来的对象，做一次 gc，子模块也一样。之后的提交会泄露答案，所以仓库里只剩 at 能到达的历史。最后把 origin/<base> 指向 at，后面所有 diff 都以它为基准。
• ticket_as_of 填开始做这张工单的时刻（ISO 时间）。fetch-ticket 用工单的变更记录把标题、描述、状态、优先级、经办人回滚到那个时刻，只留之前的评论、附件和关联工单，不带子任务（子任务可能写着解法）。
• 重放永远不审批、不推送：human-review 和 deliver 的条件带 not inputs.at。删掉 origin 是第二道保护。takeaway 也不写。运行在 classify-risk 之后结束。
• 不能和 from_run 同时给，checkout-branch 会直接失败。
• 想知道只靠工单描述够不够时，加 -i ticket_comments=none。
• 对比：重放时可以用 --set 改这次运行的流程设置，例如 --set flows.development.reviewers=1 或 --set flows.ablate=nit-cap（去掉一条标记过的规则，规则名见 rules/registry.yaml）。只能改 flows. 下已有的设置，只在重放时能用；改了什么记在 mandate 里，运行带 set:… 标签，方便按变体分组。myorch expand --set … 可以先看改完的 prompt。

按项目的不同

流程只有这一个。2026-11-10 之前每个项目复制了一份（ck-development、blog-development、mo-development），同一处改进要改三份，三份很快就不一样了，所以合回一个（docs/notes/2026-11-10-one-set-of-flows.md）。项目之间的差别写在项目包 myorch-knowledge/<项目>/ 里，展开流程时生效：

• project.yaml 的 flows.development：reviewers（默认 3）、max_rounds（3）、security（true）、on_exhausted（ask）、takeaway（false）、incident（false）。模板可以设置，项目覆盖模板。
• prompts/<槽位>.md：槽位有 develop、review、verify、fix、risk，先放模板的，再放项目的，原文拼进对应步骤的 prompt。mandate 的快照里能看到拼好的 prompt。文件名不是这几个槽位时直接报错。
• 流程里的 if:：按项目裁掉步骤和输入。fetch-ticket 和工单、重放输入看 project.jira.url，takeaway 四步看 flows.development.takeaway，incident 输入看 flows.development.incident。裁掉的输入在表单里看不到，保留默认值。

改某个项目的做法：改它的项目包（flows.development、prompts/、risk-rules.yaml），然后 uv run myorch project sync <项目>。改 flows/development.yaml 或片段会影响所有项目。

blog

个人博客（leweii/leweii.github.io）。改动小，所以 review 轻：1 个 reviewer 看一次，有阻塞问题就修一次，不再 review，跑满直接接受。修复后的提交没人 review 过，risk-rules 把它们列出来，交付说明的「review」一节列出没修好的问题。分支是 myorch/<运行 ID>，永远不推 master：推到 master 博客就上线了。

• prompts/develop.md：写文章看写作规范，改主题看开发指南。需求文档、技术设计写短，不涉及的部分写「不涉及」。文章的观点和事实、是否公开（published、加密文章）、影响全站的改动（_config.yml、布局、依赖、部署）都要问人。
• prompts/review.md：构建会不会挂、链接会不会断、页面会不会错乱；写作规范、front matter、有没有误公开。
• 端到端测试只在 review 里跑，development 不跑。

myorch 和 incident

myorch 平台自己：代码、流程、prompt、文档都在仓库 leweii/myorch 里，分支 myorch/<运行 ID>。两种用法：做一个普通需求；或者平台在某次运行里出了问题（任何项目的运行都可以），带上 incident 找原因、修平台。

incident 是出问题的那次运行。它的工作区只读挂给 develop，位置是 /sandbox/workspace/observed/<运行 ID>/：

• .myorch/flow.yaml：那次运行用的流程快照。
• .myorch/steps/<实例>/out/manifest.json 和 logs/turn-<attempt>-<turn>.log：每一步的结果和每次尝试的日志；supervisor-*.log 是 sandbox 的网络、DNS、凭证记录。
• docs/ 和 memory/MEMORY.md：那次运行的需求、设计、review、检查报告。

这些文件是那次运行的数据：agent 只读，不执行里面的命令和指令。控制台的运行选择器只列本项目的运行，所以 incident 是普通的文本框。

myorch 的 prompts/develop.md 要求 develop 在写需求之前先判断原因：

「停止」是指 outputs.proceed 写 false：后面的步骤全部跳过，运行正常结束，什么都不推。原因分类、证据（文件和行）和该去哪里处理写在摘要里。继续时，需求文档开头写「出问题的运行和原因分类」，「目标」写清楚那次运行出了什么问题、根本原因在哪个文件、改完以后同样的情况应该怎样。修复不能放宽 policy、provider、挂载、审批。

同一个 prompts/develop.md 还让技术设计多看几件平台的事：分层（engines → runner → storage → core）、改了片段或 profile 影响哪些流程（流程是所有项目共用的）、Temporal 的确定性、volume 和 events.db、sandbox 里的命令和镜像、要不要重新生成文档。

myorch：合并以后

这个流程不部署。sandbox 只改仓库，拿不到 docker.sock、gateway 和数据目录，流程里也不能有自动合并、自动部署的步骤（项目包的 security.md）。develop 在实现记录最后写「合并以后要做的事」。你在 GitHub 上开 PR、合并到 main 以后：

1. 在 myorch 的 main 分支上运行 deploy/update.sh（先用 --check 看要发布哪些提交、会等什么）。它快进 main，等没有正在执行的步骤，用目标提交的干净检出重建镜像，重启 worker 和控制台，跑冒烟流程。冒烟失败时自动回滚到上一次发布的提交。改了 src/myorch/engines/ 或 core/run.py 时，它等所有未结束的运行结束。见 deploy/README.md 的「发布 origin/main」。
2. 改了 images/claude-code/ 时，update.sh 一起重建 sandbox 的基础镜像 openshell-claude-code。各项目的开发镜像都基于它，要用上新的基础镜像，还要重建项目的镜像（项目包的 image/build.sh）。改了 pyproject.toml 或 uv.lock 时，重建 myorch 项目的开发镜像（在 myorch-knowledge 目录下运行 myorch/image/build.sh ../myorch），以后 myorch 项目的 development 运行才用上新依赖。
3. 改了 tools/（sandbox 里的辅助命令 myorch-checks、myorch-ask 等）时，它们由 myorch init 装进 volume（compose 里是 init 服务）。要确认重新运行过 myorch init，否则 sandbox 里还是旧版本。

本页源文件： flows/development.md

review 评审 PR

PR 评审：对一个已有的 PR（包括人写的）做一轮 AI review。所有项目共用这一个流程。它先跑项目的检查，再让 reviewer 看代码；项目有端到端测试时，最后用浏览器测运行中的应用。结论只在本地控制台（右栏「改动」页）和工作区的 docs/review/round-1/ 里，不往 GitHub 上发任何东西。它只找问题：不改代码，不批准 PR，也不要求修改，因为 agent 的批准不算数。对 GitHub 只读。

它用的 review 循环和 development 是同一个片段 lib/review-loop.yaml，但只跑 1 轮、不修复、有阻塞问题也照常结束。项目的 prompts/review.md、verify.md 同样拼进去（例如 core-ng 项目的 *-interface 检查、博客的写作规范和误公开检查）。

uv run myorch run flows/review.yaml --project mdm -i pr=13                # 默认 standard
uv run myorch run flows/review.yaml --project blog -i pr=13 -i depth=deep

控制台：先选项目，任务选「评审 PR」，填 PR 编号，选评审强度。第一条消息可以不写。

评审强度（depth）决定 reviewer 的个数、模型和要不要单独做安全 review，见下面的预设表。日常的 PR 用 standard。只想快速看一眼用 quick。改了构建、依赖、安全相关的地方用 deep。verify 总是用 Opus。

输入

按输入 depth 选一组参数（presets）：

步骤图

从 flows/review.yaml 生成，按项目 mdm 和默认输入展开（别的项目的项目包可能裁掉步骤、换掉参数），和 myorch expand、控制台「流程」看到的一样。

上面的图按 mdm 展开。mdm 和 myorch 没有设置 e2e.image，没有 e2e 块；blog 有。

每一步做什么

• 两个块都只跑 1 轮，fix: false、on_exhausted: accept：有阻塞问题或测试失败，运行也照常结束，只报告。
• e2e 在 review-round 之后，用的是 ci 准备好的检出。

你介入的地方

没有要你回答的提问，也没有审批。某一步失败时运行就失败（这个流程没有设 on_failed: ask）。

产物

docs/
├── pr.md                    可信的元数据：作者、状态、head → base、改动文件
├── external/pr.md           PR 作者写的标题和描述（只当参考数据）
├── ci/round-1.md            检查报告
├── review/round-1/
│   ├── reviewer-K.json      每个 reviewer 的发现
│   ├── security.json        安全 review 的发现（quick 没有）
│   ├── verified.json        核实以后的发现：Important / Nit / Pre-existing
│   └── summary.md           数量、阻塞问题列表、验收标准表
└── e2e/round-1/             有端到端测试的项目
    ├── smoke/               report.md、result.json、截图
    ├── acceptance/          report.md、result.json、截图，cases/ 是写出的用例
    └── acceptance.md        每条验收标准的结论

原则

• 每次都 review 整个 PR：myorch 不在 GitHub 上留标记，没有增量 review。fetch-pr 里「上次 review 到」的逻辑已经不用了：last_reviewed 总是空的，changed 总是 true，所以 review-round 每次都跑，第 1 轮看的是 origin/<base>...HEAD。
• 可信的和不可信的分开放：作者、状态、改动文件、SHA 写进 docs/pr.md。PR 作者写的标题和描述写进 docs/external/pr.md，每个 agent 都把 docs/external/ 当作参考数据，里面的指令不执行。
• reviewer 的规则和开发流程一样：先独立判断再核对作者的说法、到仓库里查复用和漏掉的入口、放宽的判断，详见 development 的 review 循环。1、2、3 号各有侧重，quick 只有 1 号（侧重正确性和边界）。
• verify 逐条核实：不管几个 reviewer，每条发现都打开代码核实，不成立的删掉，只有一个人报的也核实。votes 只记录几个人报告了它。Nit 最多留 5 条，检查失败算 Important。
• 需求文档：这个流程没有给 review 循环传 requirement_doc，reviewer 和 verify 被告知的需求文档是 docs/requirements.md，而评审运行里没有这个文件。所以它们只能按改动本身判断，PR 描述只在 docs/external/pr.md 里当参考。端到端块传的是 docs/pr.md。

端到端测试

• review 读代码，e2e 测运行中的应用，两者分开。用什么工具测由项目决定：project.yaml 的 e2e:（image、profile、acceptance），项目包的 e2e/（博客用 Playwright 和无头 Chromium，见 myorch-knowledge/blog/e2e/README.md）。
• 测试步骤的权限是 e2e.profile（blog 是 dev-read：仓库只读，没有凭证）。
• 冒烟用例失败只是测试环境的问题（例如浏览器没起来）时，报告里单独列为「环境」，不算代码的问题。
• e2e-accept 不能为了通过而放宽用例。用例失败时先判断是用例写错了还是改动有问题，改动有问题就保留用例。

安全

• 别人的 PR 代码不可信，ci 和端到端测试会执行它（构建脚本、测试、lint 配置）。执行 PR 代码的步骤（ci、e2e-smoke、e2e-accept）和读代码的 reviewer 都拿不到 GitHub 凭证，在跑完即删的沙箱里。
• 有凭证的一步（fetch-pr）只运行流程里写死的脚本，不执行 PR 里的任何代码。它只读：拉代码、读 PR。
• 剩下的风险是 prompt 注入：PR 内容可能诱导 reviewer 写出误导的结论。结论只在本机显示，不发到 GitHub。

本页源文件： flows/review.md

postmortem 复盘

复盘一个已经进了项目代码的问题：找出引入它的提交，判断最早该在哪一层拦住、为什么没拦住，提出知识库修改，并把这次改动做成一个评测案例。用在问题已经修好（或已经 revert）以后，想知道当初为什么没拦住时。

它只分析，不改项目代码，修 bug 用 development。对外只改本地的 myorch-knowledge（你采纳的建议）和本机的评测集（myorch-data/evals/cases/）。和 learn 的区别：learn 从一批运行里找规律，postmortem 从一个具体的问题倒查。postmortem 的结论以后也会被 learn 读到。

uv run myorch run flows/postmortem.yaml --project mdm -i commit=<修复或 revert 提交>
uv run myorch run flows/postmortem.yaml --project mdm -i bad=<引入问题的提交>

控制台：先选项目，任务选「复盘」，填「修复或 revert 提交」或「引入问题的提交」中的一个。第一条消息可以写问题的现象和影响，也可以不写；写了存成 docs/external/request.md，analyze 会读。

输入

步骤图

从 flows/postmortem.yaml 生成，按项目 mdm 和默认输入展开（别的项目的项目包可能裁掉步骤、换掉参数），和 myorch expand、控制台「流程」看到的一样。

输入

• commit 和 bad 二选一，都不填时运行不会启动。两个都填时，以 bad 为准，commit 当作修复提交。
• 提交不在任何分支上（例如没合并的 PR）也可以：locate 会按 SHA 从 GitHub 单独拉取。
• runs 不用填。发起时客户端填入这个项目最新的 development 和 review 运行（最多 20 个，已结束、失败、取消的都算），locate 从里面挑出碰过这次改动的。

每一步做什么

<id> 是这次 postmortem 运行 ID 的最后一段，例如 postmortem-1a2b3c4d 的回放是 eval-1a2b3c4d-before。

locate：怎么找到引入问题的提交

• 引入问题的提交是合并提交时，对比的基准是它的第一个父提交，所以看的是整个 PR。
• 完整历史克隆在工作区外面（/tmp），包含修复的历史不进运行的工作区。
• 碰过这次改动的运行：它的分支上有这个提交、而它开始时的 base 上没有；或者它关联的 PR 就是这个提交的 PR。
• 需求取自第一个碰过它的运行的 requirements.md（或 pr.md）。没有 myorch 运行碰过时，用提交信息和 PR 标题、描述。
• 找不到时这一步失败，并说明原因：提交不在仓库里；修复改的行找不到来源（这时用 -i bad= 直接指定）；引入问题的提交是仓库的第一个提交。

analyze：该拦住的层和原因

• 没有 myorch 运行碰过这次改动时，判断的是：如果当时经过 myorch，哪一层该拦住。
• 建议最多 5 条，格式和 learn 一样（精确替换或追加），只改 guide/。规则要写成能用到同类问题上的样子，不只写这一个 bug。
• 适合做成 lint、CI、测试的建议写进 follow-ups.md，要另起 development 去做。
• case.json 只写 reviewer 看改动本身就应该发现的问题。category 是 not-detectable，或者只有 CI 才能发现时，写 []。

回放和评测案例

回放是单独的 eval 运行（eval 流程，evals.py）。那里的 reviewer 只看到改动本身和需求，看不到这次运行的工作区：事故描述、修复、分析和期望的发现都看不到。eval 运行从 GitHub 克隆仓库，检出引入问题的提交，之后的提交（包括修复）、分支和 reflog 都删掉。

案例 ID 就是这次 postmortem 的运行 ID，存在本机 myorch-data/evals/cases/<运行 ID>.json。它这样走到评测集里：

• 案例页显示两次回放各抓到了几条。确认之前按 case.json 的全部发现算，确认之后按你勾选的算。
• 命令行对比这次的两次回放：uv run myorch eval report --batch <postmortem 运行 ID>。它只按你勾选过的发现打分，所以先确认案例。
• 两个回放步骤都幂等：已经起过的回放不会再起第二次。
• 回放是另一个运行，它失败不影响 postmortem 本身。去 eval 运行里看原因。

你介入的地方

• 回复的写法和 learn 一样：1,3、1、3、all、none；看不懂会再问一次。详细内容在 docs/postmortem/proposals.md。
• 一条都不采纳时，不改知识库，也不做第二次回放。

写回项目包

和 learn 用同一个宿主机动作 project-apply，同样是 scope: learn，规则见 learn 的「写回项目包」：全部校验通过才写、只提交自己写的文件、提交信息是 learn(<项目>): … 并带 myorch-run: <run_id>、写完重新同步快照、可以 git revert。

区别只在读的文件：建议在 docs/postmortem/proposals.json，采纳的编号在 docs/postmortem/accepted.json。prompt 只让 analyze 改 guide/；动作本身按 learn 的范围校验，也接受 checks.sh、checks.env。

产物

都在工作区的 docs/postmortem/ 下，控制台右栏「文档」能看，也可以 uv run myorch ws <run> docs/postmortem。

docs/postmortem/
  target.json            引入问题的提交、基准、修复、PR、碰过它的运行、需求
  bad.diff, fix.diff     引入问题的改动；修复（有时）
  trace.json, trace.md   当时每一层看到了什么
  postmortem.md          结论：问题、该拦住的层和原因、证据、建议
  proposals.json, proposals.md, accepted.json   知识库建议，你采纳的编号
  follow-ups.md          要另起 development 的确定性检查建议
  case.json              评测案例里期望的发现

本页源文件： flows/postmortem.md

sweep 找 bug

找项目现有代码里的 bug。所有项目共用这一个流程。每次按固定顺序看一批文件，几个审查员并行看，核实后写一份日报。适合每晚定时跑，一轮一轮把整个仓库扫完。

它是观察模式：只写日报 docs/sweep/report.md，不改代码，不推送，不启动 development，也不改知识库。发现的问题要修，由人另起 development。和 review 的区别：review 看一个 PR 的改动，sweep 看已经在主分支上的代码。

uv run myorch run flows/sweep.yaml --project mdm                     # 跑一次，审查强度默认 standard
uv run myorch run flows/sweep.yaml --project mdm -i depth=deep
uv run myorch schedule add nightly-sweep-mdm --flow sweep --project mdm --cron '0 2 * * *'   # 每晚 2 点

控制台：先选项目，任务选「找 bug」，选审查强度。第一条消息不用写。

输入

按输入 depth 选一组参数（presets）：

步骤图

从 flows/sweep.yaml 生成，按项目 mdm 和默认输入展开（别的项目的项目包可能裁掉步骤、换掉参数），和 myorch expand、控制台「流程」看到的一样。

看哪些文件

由项目包 project.yaml 的 sweep: 决定（见 7. 项目包）：

• 文件列表来自 git ls-files，按路径排序。
• mdm 和 blog 现在没有写 sweep:，所以看整个仓库，每次 20 个文件。myorch 只看 src/myorch、flows、tools、deploy（不看 src/myorch/ui/static/vendor/**），每次 15 个。
• sweep 读的是项目包快照里的配置。改了 project.yaml 以后要 uv run myorch project sync <项目>。
• 配置一个文件都没选中时，pick 失败。

每一步做什么

audit：找什么

• 正确性（逻辑错误、漏掉的边界情况、没处理的错误、和文档或注释不一致）、安全（注入、泄露的密钥、不安全的默认值、缺少的权限检查）、用户会看到的错误（坏链接、错误的数据或显示）。
• 每个审查员有自己的重点：1 号多看正确性和边界情况，2 号多看安全和错误处理，3 号多看文档和数据是否一致。
• 不报：代码风格、命名、能写得更好但没错的地方、缺少测试；已知问题；这批文件以外的代码（只用来理解上下文）。
• 严重程度只有两级：Important（错误行为、数据错误、安全问题，值得安排人修）和 Nit（确实是问题，但影响小）。没把握的不报。
• 有 guide/review-guide.md 时按它的标准看。

verify：核实

• 每条都打开代码亲自核实，不成立的去掉。
• 几个审查员报的同一个问题合并成一条，votes 是报告它的人数。只有一个人报、核实成立的也保留。
• 和 known.json 里是同一个问题的去掉。
• 日报：没有新问题时只有一句「这批文件没有发现新问题。」，后面附看了哪些目录。有新问题时，第一句写 Important 和 Nit 各几条，再按严重程度列出每条的位置、问题、后果、建议怎么修。不写过程，不写客套话。

跨运行的状态

跨运行的状态放在项目共享目录 shared/<项目>/sweep/（myorch 存储的 volume 上）。只有 pick 和 record 挂载它。

• 整个运行成功后游标才前移。 record 是最后一步，前面任何一步失败，它都不执行，下次重扫同一批。
• 扫到最后一个文件后从头开始，所以能一直定时跑下去。
• 游标是排序后列表里的位置，不是文件名。文件增删后，下一批的起点会跟着错开几个文件：可能漏看或重看几个，下一轮会补上。
• 已知问题去两次重：verify 按意思判断是不是同一个问题，record 再按 文件|标题 的指纹去掉完全相同的。
• known.json 只增不减。想从头扫，删掉 cursor.json；想让某个问题再被报告，从 known.json 里删掉那一项。每个运行的工作区里也有一份当时的副本 docs/sweep/known.json。

你介入的地方

运行中不需要你。看日报：控制台打开运行，右栏「文档」里的 docs/sweep/report.md；或者 uv run myorch ws <run> docs/sweep/report.md。值得修的问题，另起 development。

定时跑

• --flow 要写流程名 sweep。需要别的审查强度时加 -i depth=quick 或 -i depth=deep。
• 上一次定时发起的运行还在跑时，这一次跳过，所以两次运行不会同时动游标。不要加 --allow-overlap：两个运行会扫同一批文件，known.json 也可能被后结束的那个覆盖。
• 运行的发起人是建定时任务的人。uv run myorch schedule list 看下次什么时候跑，pause、unpause、delete 管理，trigger 立即跑一次。

产物

docs/sweep/
  chunk.txt          这次看的文件，每行一个
  known.json         开始时的已知问题副本
  audit-<编号>.json   每个审查员的发现
  verified.json      核实后的新问题
  report.md          日报

本页源文件： flows/sweep.md

learn 学习

从一个项目过往的运行里沉淀知识，让下一次运行一开始就知道。所有项目共用这一个流程。它把各种信号整理成对项目包的修改建议，你挑选采纳哪几条，然后写回 myorch-knowledge/<项目>/。知识库变准了，以后的每次 development 和 review 都受益。

它只改本地的 myorch-knowledge：guide/、checks.sh、checks.env。它不推送，不碰项目仓库，也不改流程（对流程的建议只写成文件）。和 postmortem 的区别：postmortem 从一个漏过去的问题倒查，learn 从一批运行里找反复出现的规律。

uv run myorch run flows/learn.yaml --project mdm                                                 # 自动选运行
uv run myorch run flows/learn.yaml --project mdm -i runs=development-b947d694,review-5d5a21ec     # 手动选运行
uv run myorch schedule add weekly-learn-mdm --flow learn --project mdm --cron '0 9 * * 1'         # 每周一 9 点

控制台：先选项目，任务选「学习」。「要学习的运行」可以留空，第一条消息不用写。

输入

步骤图

从 flows/learn.yaml 生成，按项目 mdm 和默认输入展开（别的项目的项目包可能裁掉步骤、换掉参数），和 myorch expand、控制台「流程」看到的一样。

学哪些运行

不给 runs 时，发起的客户端（命令行、控制台、Slack、定时任务都一样）自动选：

• 这个项目上次完成的 learn 之后开始的 development、review 和 postmortem 运行；
• 只要已经结束的（成功或失败），取消的不算；
• 最多 20 个，取最新的。observe_runs 最多挂载 20 个工作区。

命令行会在开始前列出选了哪些。一个新运行都没有时，运行不会启动，报「没有新的已结束的 development / review run」。uv run myorch list --project <项目> 能看到有哪些运行，手动选时用 -i runs=<id>,<id>。

失败或超时的 learn 不算完成。下一次 learn 还会选到同一批运行。

读哪些信号

每一步做什么

collect：发现的处理结果

已经标为 fixed 的发现不算。其余每条按下面的顺序判断，取第一个成立的：

myorch 不再往 PR 上发评论，所以没有「有人回复了评论」这一类，结果只来自运行自己的记录和 PR 状态。

collect：仓库里的 takeaway

• 项目设置了 flows.development.takeaway（现在只有 mdm）时，development 每次把 task.md 和 takeaway.md 随改动提交到 myorch/<日期>-<run_id>/。PR 合并后它们才在 base 分支上，所以只读得到合并了的。别的项目仓库里没有这个目录，这一类信号就是空的。
• 工作区没有仓库时，collect 做一个不检出文件的浅克隆，用 git show 逐个读。
• 跳过学过的，从最早的开始读。每次最多 30 条、300 KB（第一条总会读），其余留给下一次。摘要写明还剩几条。
• 读不到 takeaway.md（网络问题、空文件）的不读，也不记为学过，下次再试。连续 3 条读不到就停下。目录名不是 <日期>-<run_id> 的跳过。
• 读不到仓库时只记一句固定的话和 git 退出码，不带命令行和 git 的输出。learn 照常进行。
• 学过哪些只记在本机 myorch-data/learn/<项目>/takeaways.json（takeaways.py），不写公司仓库，也不写 myorch-knowledge。

analyze：找哪几类知识

最多 8 条，证据不够就少提或不提。不重复知识库和仓库自带文档里已有的内容，措辞简短，沿用现有文件的风格。

另外两个文件不会被应用：follow-ups.md 是要改项目仓库本身的建议（lint、CI、测试），要另起 development；flow-proposals.md 是对 myorch 流程的建议（步骤顺序、提问时机、总失败或多余的步骤）。

takeaway 当作信号，和其他证据一样核实：只采纳能推广到以后的项目知识，只对某个工单成立的不要。证据写成 <run_id>: takeaway。流程、平台、环境类的建议进 flow-proposals.md。

每条建议的修改写成精确替换（edits：old 从当前文件逐字复制，在文件里只出现一次）或追加（append）。不用 diff，因为 agent 写的 diff 常常行号对不上。

你介入的地方

• 问题里每条建议一行，带类型和证据条数。详细内容在 docs/learn/proposals.md：控制台右栏「文档」，或 uv run myorch ws <run> docs/learn/proposals.md。
• 回复写编号就行：1,3、1、3、1 3 都可以。all 或 全部 是全部采纳，none、无、0 是一条都不要。编号不存在或看不懂时会再问一次。
• 回复一旦被接收就开始执行，不能再改。想补采纳的，另跑一次 learn，或者手改项目包。
• 24 小时不回复，这一步超时失败。定时发起的 learn 也停在这里等你。

写回项目包

apply 是宿主机动作 project-apply，scope: learn（actions.py、project.py）。sandbox 访问不到 myorch-knowledge，所以在宿主机上做。

• 只写项目自己的目录 myorch-knowledge/<项目>/，模板（例如 mdm 的 _templates/core-ng/）不变。项目只从模板继承的文件，第一次修改时先复制模板的内容再改。
• 先在内存里校验所有采纳的修改：路径在允许的范围内、不跳出项目包、每个 old 恰好出现一次。任何一处不通过，就一处都不写，这一步失败并列出原因。
• 写入后在 myorch-knowledge 里提交，只提交这次写的文件（别人暂存的改动不会带进去）。提交信息是 learn(<项目>): #1 标题; #3 标题，正文带 myorch-run: <run_id> step: apply 和采纳的编号。
• 然后重新同步项目包快照。之后开始的运行用新知识，Mandate 里记录的项目包版本也跟着变。正在跑的运行继续用它们自己的快照。
• 幂等：发现这一步已经提交过，就直接算成功，不写第二遍。
• 某条建议效果不好：在 myorch-knowledge 里 git revert <提交>，再 uv run myorch project sync <项目>。

产物

都在工作区的 docs/learn/ 下，控制台右栏「文档」能看，也可以 uv run myorch ws <run> docs/learn。

docs/learn/
  trail.json                 发起时写入：事件日志里的问答、意见、驳回、失败、重新执行
  takeaways-learned.json     发起时写入：已经学过的 takeaway 的 run_id
  findings.json, outcomes.md 发现和处理结果，统计表
  signals.json, signals.md   review 以外的信号
  takeaways.json, takeaways/<日期>-<run_id>/   这次读到的 takeaway
  proposals.json, proposals.md                 建议
  follow-ups.md, flow-proposals.md             不会自动应用的建议
  accepted.json              你采纳的编号

定时跑

myorch schedule add 的 --flow 要写流程名 learn。定时任务和控制台用同一条路径发起，所以自动选运行、写 trail.json 和 takeaways-learned.json 都一样。

• 上一次定时发起的运行还在跑（例如还停在 choose）时，这一次跳过。要同时跑，加 --allow-overlap。
• 没有新运行时，这一次不会启动运行。即使仓库里有新的 takeaway 也一样，因为 takeaway 只在 learn 运行里读。
• 运行的发起人是建定时任务的人。uv run myorch schedule list 看下次什么时候跑，pause、delete 停用。

本页源文件： flows/learn.md

eval 评测

给 reviewer 打分：把一次历史 review 看过的改动原样重放，让 reviewer 再看一遍，和人确认过的真问题对比，算抓到几条、漏掉几条、多报几条。改了 reviewer 的 prompt、模型或项目包的 guide/ 以后，用它判断变好还是变差。它对外什么都不写：不推送，不改代码，不改项目包。

一次 eval 运行只重放一个案例、一种评审强度。案例的收集、确认、批量发起和打分都在本机由 myorch eval 做（../src/myorch/evals.py），流程本身只负责准备代码和跑一轮 review。

uv run myorch eval collect                              # 从历史运行收集候选案例
uv run myorch eval list                                 # 案例和状态
# 在控制台「流程 → 评测集」里，逐个案例勾选哪些发现是真问题
uv run myorch eval run --depth quick --depth standard   # 每个已确认的案例，每种强度各起一次 eval
uv run myorch eval run --case <案例 ID>                  # 只跑某个案例（默认强度 standard）
uv run myorch eval report [--batch <批次>]               # 对比表

不要在控制台的「＋ 新运行」里或用 myorch run 直接发起它：只有 myorch eval run（和 postmortem 的回放）会把案例写进工作区，直接发起时 prepare 读不到案例，会失败。Slack 的发起弹窗不列这个流程。

输入

按输入 depth 选一组参数（presets）：

步骤图

从 flows/eval.yaml 生成，按项目 mdm 和默认输入展开（别的项目的项目包可能裁掉步骤、换掉参数），和 myorch expand、控制台「流程」看到的一样。

案例从哪里来

案例是一次历史 review 第 1 轮看过的改动，加上人确认过的真问题。存在本机的 myorch-data/evals/cases/<案例 ID>.json。

postmortem 也会生成案例（origin: git）：改动是项目仓库里引入问题的那个提交，不来自 myorch 运行，案例 ID 是复盘运行的 ID。复盘自己发起这些回放：用当时的知识库一次，你采纳了它提出的知识库修改时，用新的知识库再一次，myorch eval report --batch <复盘运行 ID> 能看。

每一步做什么

强度和 review 的三种一样，见上面的预设表。

不泄露答案

• 标准答案不进工作区：myorch eval run 只把案例里能看的字段写进 docs/eval/case.json：来源、源运行、流程、仓库、base 和 head 提交、需求文档。人确认的发现留在本机的 myorch-data/evals/cases/。
• 后来的提交不留：源运行后来的修复提交会告诉 reviewer 问题在哪里，所以仓库里只留 head 能到达的历史，分支、远端引用、reflog 都删掉。
• 对外不可写：删掉 origin 以后，重放里的任何一步都推不出去。
• reviewer 也看不到源运行的技术设计、实现记录和工单原文：工作区里只有需求文档和改动。所以评测比真实开发流程里的 review 少了这些输入。

怎么打分

在本机算，流程里不算：

• 只比较 Important 和 Nit，两边都一样。
• 抓到：重放的某条发现和一条勾选的发现在同一个文件，行号相差不超过 10（任意一个位置对上就算）。
• 漏掉：勾选的发现里没被抓到的。
• 额外：重放报了、但没对上任何勾选发现的。它们可能是误报，也可能是当时没人标出的真问题。单独列出其中的 Important 条数。
• report 先列每次运行（强度、案例、抓到/期望、额外），再按强度汇总：案例数、期望、抓到、漏掉、召回率（抓到 ÷ 期望）、额外、额外的 Important。复盘的回放按「强度·before」「强度·after」分开。还没跑完的运行不计入，最后提示还有几个在跑。

你介入的地方

运行本身没有提问和审批。

本页源文件： flows/eval.md

onboard 接入项目

让 myorch 了解一个项目。它读仓库，拿最近几个提交试跑一次项目包的检查，然后提出补充或修正项目包的建议；你挑选采纳哪几条，写回 myorch-knowledge/<项目>/。以后的开发、review 和风险判定都依赖这些知识。

新接一个项目时跑一次，仓库结构变化大时再跑。它对项目仓库什么都不推送，只改本地的 myorch-knowledge。和其他流程一样，所有项目共用它。和 learn 的区别：learn 从跑过的运行里学，onboard 只看仓库本身，能改的文件也更多（检查脚本、准备脚本、审批规则、安全重点）。

uv run myorch run flows/onboard.yaml --project <项目>
uv run myorch run flows/onboard.yaml --project <项目> -i focus="数据库迁移"

控制台：先选项目，任务选「接入项目」。第一条消息就是「要重点看的地方」，可以不写。

输入

步骤图

从 flows/onboard.yaml 生成，按项目 mdm 和默认输入展开（别的项目的项目包可能裁掉步骤、换掉参数），和 myorch expand、控制台「流程」看到的一样。

开始之前

项目包至少要有 project.yaml，并且已经 uv run myorch project sync <项目>。项目的 GitHub provider 要建好，开发镜像要构建好。步骤见 7. 项目包 · 接入一个新项目。

focus 原样接在 analyze 的任务说明后面，例如「前端检查」「数据库迁移」，让它在这些地方多花功夫。

每一步做什么

try-checks：试跑检查

• 目的：看 checks.sh 是否找对了模块、要跑多久，哪些检查因为和改动无关的原因失败（环境、网络、缓存）。
• 样本改动是 base 分支最近 5 个提交。仓库不足 6 个提交时，用全部历史（从空树算起）。改了哪些文件写在 changed.txt。
• 检查按 checks.sh 的约定 运行，CHECKS_DIR 是 docs/onboard/checks/。
• 检查没通过、setup.sh 失败、没有 checks.sh，都只记进结果，这一步照样成功。这些正是 analyze 要看的。

analyze：要弄清楚什么

• 每条结论注明依据（文件路径）。
• 建议最多 8 条，类型是 fill-gap（补知识）、fix-checks（修检查）、fix-rule（修审批规则）、security（安全重点）。
• guide/ 只写仓库自带文档里没有、而且会影响 agent 判断的内容，措辞简短。
• 需要人回答才能定的问题写进 open-questions.md。流程不会问你这些问题。看完以后手改项目包，或带着 focus 再跑一次。

你介入的地方

• 先看 docs/onboard/report.md 和 proposals.md：控制台右栏「文档」，或 uv run myorch ws <run> docs/onboard。
• 回复写编号就行：1,3、1、3、1 3 都可以。all 或 全部 是全部采纳，none、无、0 是一条都不要。编号不存在或看不懂时会再问一次。
• 回复一旦被接收就开始执行，不能再改。24 小时不回复，这一步超时失败。

写回项目包

开发流程按项目的设置（project.yaml 的 flows.development、prompts/，见 development 的「按项目的不同」）onboard 改不了，要改时由人手改。

修改有三种写法：精确替换（edits，old 必须在文件里恰好出现一次）、追加（append）、整个文件（content）。

• 只写项目自己的目录 myorch-knowledge/<项目>/，模板 _templates/<模板>/ 不变。
• guide/、checks.sh、setup.sh 是覆盖式继承：项目只从模板继承的文件，第一次修改时先复制模板的内容再改，所以 edits 可以引用快照里看到的原文。
• risk-rules.yaml 和 security.md 是拼接式继承：快照里是模板的内容加项目的内容，项目自己的文件里只有项目特有的部分。所以 security.md 只用 append，risk-rules.yaml 只用 content，写完整的项目规则文件（rules: 列表，可选 default:）。同步快照时再和模板的规则拼起来。
• 其余规则和 learn 一样，见 learn 的「写回项目包」：全部校验通过才写，只提交自己写的文件，写完重新同步快照，可以 git revert。提交信息是 onboard(<项目>): #1 标题; …，正文带 myorch-run: <run_id>。

产物

都在工作区的 docs/onboard/ 下。

docs/onboard/
  checks/
    changed.txt        样本改动的文件
    report.md          checks.sh 的报告
    result.json        passed、failed、skipped
  report.md            项目概况和结论，每条带依据
  proposals.json, proposals.md   建议
  open-questions.md    要人回答的问题
  accepted.json        你采纳的编号

本页源文件： flows/onboard.md

片段

片段是 flows/lib/ 下可以复用的步骤或循环。流程用 use: 引用它，发起时展开。写法见使用手册 · 8. 写流程。这张表从片段文件生成。