16-不会还有人每个会话都从零发明流程吧？入口文件才是值班手册 | Agent 启动清单

上一篇：不会还有人 MCP 接不上就怪模型吧？多半是路径和环境 | IDE 配置调试排障

不会还有人每个会话都从零发明流程吧？入口文件才是值班手册 | Agent 启动清单

系列：《从 Rule 到落地：AI 工程化实践》第 16 篇
标签：Agent · 入口文件 · 执行纪律 · 清单
专栏：从小白到AI落地大师

序言

工具接上了，童鞋们发现另一个飘：每个会话从零发明流程，有时忘加载安全 Rule，有时结束不写验证。本篇定义 Agent 入口文件应包含的启动清单与执行纪律，让每次会话行为稳定可预期。

说句自嘲的：我当过「即兴值班长」——临场发挥很帅，复盘很惨。后来肯把入口文件当值班手册版本管理，翻车率才下降。帅不是目标，可预期才是。

记住一句话：入口文件 = 进门有清单、途中有停靠、出门有约定。三关缺一，会话就靠气质起飞——这次碰巧对，下次碰巧错，团队永远学不到东西。

概念

Agent，按入口手册启动与收尾的编排者。启动清单，加载常驻 Rule、确认目标、扫描高风险路径。执行纪律，小步改动、高风险确认、结束前自检。停靠点，必须暂停确认或跑验证的检查点。

可以理解为：入口文件是航班起飞前检查单。再资深的机长，也不靠记忆跳过燃油与舱门确认。助手更不该靠气质起飞。

一张图说清会话生命周期——启动清单管进门，停靠点管途中，输出约定管出门：

停靠点什么时候触发，别靠临场感觉，给个固定的判定优先级——风险级一票停靠，其次看范围蔓延，最后看疑难度。可以理解为：超速（风险）永远先停，占道（范围）其次，拿不准路线（疑难度）再问——不是三个条件投票，是排队掐闸。这套判定怎么短路、又是怎么真把任务砍停的，下面举例用一份可跑的session.py演给你看，里面还埋了一个类型比较的坑。

问题在哪

没有入口文件时，流程随会话心情漂移。有人先改代码再想目标，有人改完不跑验证，有人碰生产工具不确认。Skill 与 MCP 明明准备好了，却在入口处断开——像装备齐全但不出门。

出口也常缺约定：改了什么、怎么验、剩余风险。人和 CI 无法接力，记忆层也捕获不到干净原料。

举例：一份拷进仓库就能跑的入口手册 + 会话模拟器

步骤总览，大家先喽一眼。下面BOOT.md + session.py 两个文件，session.py 纯标准库、复制即跑，把「进门有清单、途中有停靠、出门有约定」三段一次跑全：

• 步骤 1：一份五段齐全的BOOT.md入口手册（可整段拷进仓库）；
• 步骤 2：session.py会话模拟器——先 lint 手册完整性，再对一批任务逐条跑停靠判定，最后按出口约定出总结；
• 最后：真实运行输出，逐行看三道停靠闸门各砍停了谁。

步骤 1：BOOT.md 入口手册

骨架谁都会画，但画了不检查就等于没画。所以直接给可整段拷进仓库的完整版（虚构 acme，五段齐全）：

# BOOT.md —— Agent 入口手册（acme，随仓库版本管理） ## 1. 角色与目标 - 本会话角色：实现者（审核由独立会话负责，见第 17 篇） - 开工前必须用一句话向用户复述本会话目标，确认后再动键盘 ## 2. 必读 Rule / Pack - [ ] 已加载 `acme-rules@1.4.x`（以 lock 文件为准，版本不一致必须停） - [ ] 已读 `00-safety.always.md`（常驻安全内核） - [ ] 按意图加载场景路由 Rule（映射类任务加 `06-adaptor.routing.md`） ## 3. 可用 Command 与 Skill - 映射变更 → `fix-parse` Skill（带正反例与报告模板） - 记忆查询 → memory-boot `recall`（默认 top 3，勿自行放宽） - 未列出的工具先问，不默认「应该可以」 ## 4. 停靠点（何时必须停） - 改 `adaptor/public/**` 之前 → 停，等人确认 - 风险 T3 及以上 → 停，等 owner 确认 - 每个补丁落地后 → 停，跑单测或夹具再继续 - 加载的 Pack 版本与 lock 不一致 → 停 ## 5. 禁止事项 - 不一次改多个无关模块 - 不绕过审核门禁自行合并 - 不把令牌写入任何可提交文件 - 结束前必须输出：变更清单 / 验证命令与结果 / 剩余风险

模板有了，还得防两件事：一是「改着改着小节没了」，二是「停靠点写在纸上、没人真按它走」。下面这份session.py一次把两个都跑给你看——boot_lint盯手册完整性，should_stop盯任务，出口约定盯总结：

步骤 2：会话模拟器 session.py

# session.py —— Agent 会话模拟器：进门 lint → 逐任务停靠判定 → 出门总结（纯标准库）# 用法：python session.pyfromdataclassesimportdataclass,field REQUIRED=["## 1.","## 2.","## 3.","## 4.","## 5."]@dataclassclassTask:title:strrisk:int# 1..4；必须数值比较，别拿 "T10"<"T3" 字符串比大小modules:list=field(default_factory=list)uncertainty:str="low"# low / highdefshould_stop(task):iftask.risk>=3:# 1. 风险级：一票停靠，最高优先return"confirm_by_owner"iflen(task.modules)>1:# 2. 范围：一次改动跨多个无关模块return"confirm_scope"iftask.uncertainty=="high":# 3. 疑难度：目标或方案没想清return"ask_question"return"proceed"# 都不命中才放行defboot_lint(text):return[f"缺小节{s}"forsinREQUIREDifsnotintext]TASKS=[Task("给 adapt_smoke 补一条断言",risk=1,modules=["tests"]),Task("改 public 映射表列宽",risk=3,modules=["adaptor/public"]),Task("重构 parse+export 两处",risk=2,modules=["parser","export"]),Task("排查偶发超时原因",risk=1,modules=["ops"],uncertainty="high"),]defmain():print("== 进门：入口手册体检 ==")ok=boot_lint(open("BOOT.md",encoding="utf-8").read())print(" BOOT.md :","OK 五段齐全"ifnotokelseok)trimmed="## 1. x\n## 2. x\n## 3. x\n## 4. x\n"# 有人「顺手精简」掉了第 5 节print(" 顺手精简版 :",boot_lint(trimmed))print("\n== 途中：逐任务停靠判定 ==")fortinTASKS:d=should_stop(t)mark="停靠"ifd!="proceed"else"放行"print(f" [{mark}]{t.title}->{d}"f"(risk={t.risk}, mods={t.modules}, unc={t.uncertainty})")print("\n== 出门：结束输出约定 ==")proceed=[t.titlefortinTASKSifshould_stop(t)=="proceed"]stopped=[t.titlefortinTASKSifshould_stop(t)!="proceed"]print(" 变更清单：",proceed)print(" 验证命令： python run_case.py cases/adapt_smoke_01.yaml -> pass")print(f" 剩余风险：{len(stopped)}个任务停在停靠点，待 owner 确认后继续")if__name__=="__main__":main()

should_stop这里刻意把risk定成int，比较写task.risk >= 3。别顺着直觉写成task.risk >= "T3"拿字符串比大小——"T10" >= "T3"按字典算是False，风险最高的 T10 反而一路放行。这类坑不真跑一遍根本发现不了，正应了第 4 篇那句：不可判定的约束等于没写。

步骤 3：跑起来长这样

BOOT.md和session.py放同一目录，UTF-8 终端下python session.py，真实输出原样贴上：

== 进门：入口手册体检 == BOOT.md : OK 五段齐全 顺手精简版 : ['缺小节 ## 5.'] == 途中：逐任务停靠判定 == [放行] 给 adapt_smoke 补一条断言 -> proceed (risk=1, mods=['tests'], unc=low) [停靠] 改 public 映射表列宽 -> confirm_by_owner (risk=3, mods=['adaptor/public'], unc=low) [停靠] 重构 parse+export 两处 -> confirm_scope (risk=2, mods=['parser', 'export'], unc=low) [停靠] 排查偶发超时原因 -> ask_question (risk=1, mods=['ops'], unc=high) == 出门：结束输出约定 == 变更清单： ['给 adapt_smoke 补一条断言'] 验证命令： python run_case.py cases/adapt_smoke_01.yaml -> pass 剩余风险： 3 个任务停在停靠点，待 owner 确认后继续

输出你看什么

逐行拆，四段输出正好走完一次受纪律约束的会话：

1. 进门两行，一绿一红：正经BOOT.md判OK 五段齐全；那个「顺手精简版」少了## 5.，立刻被抓成['缺小节 ## 5.']。纪律漂移的第一现场就是入口文件被顺手精简——lint 红了，谁精简谁举证，不用等三个月后出事再考古。
2. 四条任务，三种停靠各砍一刀：改 public 映射表列宽命中 risk=3 →confirm_by_owner，风险一票否决，短路掉后面两条判定；重构 parse+export 两处风险才 2，但mods=['parser','export']跨两模块 →confirm_scope；排查偶发超时原因单模块低危，却因unc=high→ask_question。三条红各停在不同闸门，把「风险 > 范围 > 疑难度」的优先级演得明明白白。
3. 只有第一条进得了变更清单：给 adapt_smoke 补一条断言低危、单模块、目标清晰 →proceed。停靠过的任务没确认，就不该出现在出门总结里——变更清单只有一项，正是那个唯一放行的。
4. 出门三件套：变更清单 / 验证命令 / 剩余风险一次列全。剩余风险： 3 个任务停在停靠点直白告诉接手的人（或 CI，或第 19 篇的记忆层）——这次会话不是「全绿」，是「一个动了、三个卡住」。截图式「我改完了」在这种约定下无处遁形。

把TASKS换成你们真实待办、REQUIRED换成你们 BOOT 的小节标题，session.py就是你们的会话门禁。它不替你想流程，它替你每次都用同一个流程起手。

自检

# 入口文件自检 - [ ] 是否有启动清单，而非即兴发挥？ - [ ] 是否有执行中停靠点？ - [ ] 结束是否约定输出变更与验证？ - [ ] 是否写明与 Skill/MCP 的衔接？ - [ ] 入口文件是否进版本库？

两问。第一，新会话第一分钟，助手是否必然加载安全 Rule？不是必然，清单就还是愿望。第二，结束时能否让另一个人只看总结接下去？不能，出口约定还没生效。

入口文件保持短。超过两屏，人就不读，模型也容易丢。细节链到 Skill，入口只留纪律与停靠点。

把「确认目标」写成强制步。目标不清就开改，是最常见的忙乱来源——看起来勤奋，实际在挖坑。

入口文件BOOT.md建议固定五段：角色与目标、必读 Rule/Pack 版本、可用 command 列表、停靠点（何时问人）、禁止事项。会话开始先读它，比每次从聊天记录考古靠谱。

和流水线的关系：BOOT 负责「上班打卡与今日菜单」；第 11 篇流水线负责「点菜之后怎么过门禁、谁上灶、怎么归档」。两张纸缺一，值班就会靠默契。

启动清单要可勾选，不要写成散文诗。例如：

• 已加载 Packacme-rules@1.4.x
• 已读 hard-constraints
• 今日任务风险级已声明
• 高危命令确认人是谁

值班交接只传 BOOT 勾选结果 + correlation_id，不传三千行聊天。聊天是噪声，勾选是状态。

读到这里，五分钟动作：把上面 BOOT.md 模板拷进你们仓库改出第一版，再把 lint 脚本挂进 CI。下周开会，争论「流程该是什么」就变成「BOOT 第 4 节这条要不要改」——文件在，讨论才有坐标。第 16 篇的验收不是「读完」，是「入口文件进了版本库，lint 是绿的」。

举例加长：BOOT 里的停靠点示例

• 改adaptor/public之前必须停
• 风险 T3 及以上必须停
• 加载的 Pack 版本与 lock 不一致必须停

停靠点是值班友谊的保险绳，不是不信任。

思考

小结三句。入口文件是 Agent 的值班手册。启动清单降低漏加载 Rule 的概率。结束输出约定便于人和 CI 接力。

可以理解为：起飞检查单写好了，再谈多机长协作。下篇扩展多角色：主 Agent、子任务与审核门禁——别既当运动员又当裁判。

下篇预告：《不会还有人既当运动员又当裁判吧？审核门禁必须分角色 | 主 Agent 与审核》——分角色是为了责任清晰，不是为了堆模型调用。

觉得有用的话，欢迎点赞、留言贴一版你的入口骨架；有「即兴值班长翻车」经历，也欢迎对照清单拆。

专栏：从小白到AI落地大师｜《从 Rule 到落地：AI 工程化实践》