十三希诺通用 Agent 工作流（Shisan Xinuo Agent Workflow）· 纪律元核心

家族结构：本文件=纪律元核心（只管「怎么做」）；流程细节与模板→shisan-xinuo-flows；审查角色→shisan-xinuo-roles（两包独立可装，建议与核心同装；按需加载、用完不驻留）。 阅读顺序：§0 元规则与强制分级 → §1 何时用 → §2 跑道骨架（唯一入口） → §3 平台注入 → §4 必问与停型门禁 → §5 模式 → §6 门禁出口与交付纪律 → §7 易错点与借口拦截 → §8 记忆留档 → §9 会话状态面 → §10 路由表 → §11 速查表。 每节写法固定「触发 → 步骤（清单）→ 模板 → 自检 → 边界」；需要「解释」而不是「执行」的内容 → 上报。

0. 元规则、强制分级与宪章

• 触发优先：一条规则只在触发条件成立时适用。口径关系：注入核心=常驻最小集，本文件=核心全文；冲突以核心为准并立即修本文件（细则 #325 同源）。防棘轮：本体以「语义不重复、检索面收敛」为维护目标，新增先 diff、重复当场合并，删减降级合法。步骤即清单 / 模板即复制 / 边界说不做什么。
• 宪章五维与五门（本 Skill 只干这五件事）：①元规则执行纪律——规则可被跳过，但「跳过」这个动作必须受约束（跳过必声明）②路由与阶段纪律——任务分诊/阶段门控/范围纪律（只碰被要求碰的）③反合理化——借口拦截表+危险词自检（§7）④硬门禁与验证——唯一停型门禁+独立审计（§4/§6）⑤交付纪律——从「说做完了」到「证明做完了」。五门=意图门/验证门/完成门/上下文门/安全门。
• 强制力四级（RFC 2119 中文惯例，全篇生效）：
  • 必须级（「必须/不得」）：不可跳过，agent 无自判豁免权，唯一例外=用户显式豁免——红线 7 条（注入核心红线段）、L3 停型门禁、不假实现。
  • 应当级（「应当」）：默认强制，可声明跳过/降采样但必须留痕（跳过必声明三条；下限未达=照报理由）——复述+状态行、开工四步、三问分流、GATE、能力检索、努力预算、验证步、每步「无产物不进下一步」门控。
  • 可以级（「可以」）：按需/症状触发，不触发不适用——细则 lookup、角色 dispatch、知识包（v3.1 候选，未建）。
  • 压缩级（形态维度）：应当级产出的详细度可按任务量降采样（一行化/简式/照报 0），但存在性不可压缩——一行也算在场，静默消失=违规。
• 工程 Token 观（双向 · 精算机）：不得因省 Token 跳过实质动作（需求对齐/调研/验证/能力检索/边界覆盖），也不得因堆流程无意义燃烧——Token=投资，ROI 为负同样违规；形态压缩仍合法——省的是仪式，不是实质（details #349/#357）。
• 三防线速记：防偷懒（底线：不准零调研/零提问/零验证/零调用）→ 防灾难（上限：不准无脑烧/重复消耗/塞爆上下文）→ 求杠杆（目标：最小精准投入换最大逻辑确定性）。分档预算/白名单天花板/沉淀外部化/子代理隔离与止损见 details #357-#362。
• 跳过必声明（元规则）：任何规则/步骤/纪律被跳过（含 L2-S 边界豁免、L1 整体标注、压缩级降采样）——①复述跳过了什么 ②任务记录留依据（为什么跳：选道豁免/预算/不适用）③向用户一行提醒。「跳过+声明」合法，静默跳过=违规（触达失效主通道）。
• 复述前置：每轮首产物=复述（新任务全量三行；追加/继续=一行「收到 X｜理解为 Y｜边界 Z」）；阶段边界加全量复述；L3 确认不豁免；摘要接续=一行接续声明。状态行=Context: state=<读档/新建/单发> L=<L1/L2-S/L2-F> confirm=<无需/已问/豁免:理由>（判级并入 L= 字段）。
• 文档写作分层：正文=结论/规则本身+≤1 句为什么；史料（出处/拍板人/日期/版本/轮次）只落决策史层（details #278）。

1. 何时使用 / 何时不用

使用：任何工程任务（动手即按 §2 跑道推进）；用户要求纪律化执行、工作流治理、跨项目跨平台行为一致。加载即场景判定+承载检查（§2.0），不依赖注入核心在场——多 Skill 共存平台上在场的核心可能是其他 Skill 的。 不用：不替代官方文档学习框架/库/API；不替代项目自身约定——冲突时项目自身文档优先。

references/details.md 是踩坑日志（曾经错在哪），不是技术教程；流程/规则/门禁层与框架无关。

2. 跑道骨架（唯一入口）

2.0 开工四步（每步有出口产物，无产物不进下一步）

场景判定：项目特征（.git/多文件/既有 memory/ 或 docs/ 任一）=持续全套；无特征且非工程任务=单发（纪律全走、文档豁免，交付回复声明一行「单发模式：未建承载」）；判定不清默认持续（先建兜底，误判持续只是多几个文件）。

L1 豁免：整体标注「L1 精简」→承载检查豁免、承载增量补缺不免；状态行+复述不可豁免。

2.1 能力检索协议（清单匹配形态）

• 开工时与每次出现「我直接写吧/我记得有个工具/得搜一下」念头时，先做一次能力检索：当前任务意图 → 匹配 Skill 清单与 MCP 工具清单（清单已在系统提示常驻，零机制新增）→ 命中即用；未命中才允许自己写，并给出「未命中」归因一行。
• 检索分档与天花板：L1 不做检索（一毛不拔档）；L2-S ≤1 次；L2-F ≥1 次且命中即停（禁翻全清单）——details #358/#359。
• 场景明显匹配某能力却选择自写 → 状态段记闲置归因：闲置归因: <能力> 未调用｜理由：…；无归因=违规绕行，下一 GATE 标 errpath=能力绕过。
• 出口产物=能力检索记录（意图+命中/未命中）；GATE 用 caps= 记录实际使用（§6）。details #347。

2.2 判级速查（10 秒定论，一句话即止，禁止展开论证）

本块 = L3 封闭清单 / L1/L2 速判 / 三问分流的唯一权威源。三级同步链：本块 → injection-core.md → 已注入的平台全局副本——三级必须一致（改判级先改本块 → 同步核心 → 重新部署）。

• L3 封闭清单（仅 6 项，清单外一律不是 L3，不得自行扩展）：密钥/权限｜数据删除｜数据或服务迁移｜对外发布｜架构选型｜超预算破坏性操作。清单外高危域执行层枚举（CI/CD·DNS/证书·IAM·计费配额·生产 feature flag·webhook/回调·限流阈值·OAuth 回调白名单·生产配置中心写操作）＝命中至少按 L3 停点问询；不动清单语义（细则 #370，机检端口 scripts/risk_scan.py）。
• L1 速判：改名、文案、格式、单行修改等可逆小改 → 直接做，不问、不展开。L2：新功能、多文件、跨模块 → 记录后做，关键点汇报。判不了 → 默认 L2。
• 判级 ≠ 理解确认：目标/边界/方向有歧义、理解不尽确定 → 普通模式也必问。
• 三问分流（一次答完）：①跨 ≥3 包/跨 api+contracts+前端？②涉契约·架构·迁移·发布·安全？③用户点名「按流程/严格分析」？→ ≥2 命中=L2-F；其余=L2-S。L3 永远 L2-F+暂停行。

2.3 L1 快速通道（小改动、可逆、低影响）

一句话复述（目标/边界，不可豁免）→ 最小修改（只改任务范围）→ 最小验证（跑最小验证命令并记退出码）→ 一行汇报。标注「L1 快速通道」=命名通道，不是静默跳步。

2.4 L2-S 短工作流（≤3 文件、单域、与既有模式同构）

1. 对接真相调研（绝不跳过）：写码前先填表 模块 | API/端点 | 对接方式 | 证据来源(source:line)——grep 调用点 → 读 schema/类型 → 确认包归属 → 才写；命名直觉被禁止（details #233）。升级形态=约束与影响矩阵：每模块列清职责/输入输出/依赖与被依赖/日志可观测性/权限边界/失败模式/验收用例/变更影响面——答不上「这个改动会扯动什么」就不准进实现（details #351）。
2. 复述 3 短行（改哪/影响什么/怎么验）。
3. 一行「改动 + 验收 + 回滚基线」（单文件可直接做）。
4. 执行 + 最小验证（可重跑，捕捉退出码）。
5. GATE（§6）。

边界（省什么）：免联网双调研、免产品五问深度、免 plan 文档；必问协议与红线不豁免；Token 预算=精打细算档（状态段/检索各 ≤1 次，details #358）。

2.5 L2-F 完整 9 步主流程（大模块 / 任何 L3）

最铁铁律（复用铁律）：以最少的代码实现最完整的功能和体验并达到需求=最好的代码；能复用绝不自研。设计成本铁律：设计决策按「后期改造成本」评估，不按当下成本。设计确认先于写码（details #312）。 Token 预算=重投入档（双约束）：复杂度预算（任务预估上限）+ 努力预算（§2.6 下限）同时生效；超支未完结=stop_reason 止损降级（§6、details #362）。

门禁：上一步出口产物不存在不进下一步；无法产出的步写明理由，不得静默跳过（跳过必声明）。

2.6 需求工程协议（分档执行）

四轮提问（第一轮目标：解决什么问题/成功长什么样→第二轮边界：什么不做/哪些用户数据权限→第三轮失败：哪里易错/出错怎么恢复→第四轮验收：拿哪几个边界情况验/预期结果）+ 模糊词追问（「细查/体验不行/不对劲」全部追问到可测试）→ 产出 《意图与边界确认单》（目标/非目标/角色/输入输出/约束/验收用例/失败场景/回滚方案）。分档：L2-F 全轮；L2-S 简式单轮；L1 豁免。 计划模式必问（details #346，硬性）：进入计划模式（计划模式/plan 词/「做计划」）必须以平台提问工具提问需求要点，不可省略；可分多轮多次，直至对需求有 95% 信心；确实无疑问时记 clarify=无疑问（依据…） 照报——不达下限的 GATE 判不通过。 努力预算下限（#349）：L2-F 至少 1 轮能力检索 + 需求澄清（或照报）+ ≥3 边界用例；未达=GATE 不通过（照报形态如上）。

2.7 新项目 / 状态澄清（回指）

工作区无 memory/ 骨架或无 docs/ 指导 → 按 references/new-project-bootstrap.md 走六节索引（架构/目标/模块表/调研导航/参考资源/复述确认）。目标或现状模糊 → shisan-xinuo-flows §0.0 澄清流程（一次一问→澄清纪要→回选道）。

3. 平台检测与注入（首次部署才做）

• 安装名前缀自检（每会话一次）：能确定安装目录名且无 agent- 前缀 → 一行提示可一键带前缀重装（scripts/install-skill.ps1）；目录名未知 → 不猜不阻塞；用户已明确不改 → agent-log 记「保持无前缀」后静默。
• 检测平台 → 项目级注入点定位 → 注入模式二选一（按需=只写应用层；强制=三层写入并先提醒授权）——全表见 references/platform-adaptation.md（注入点表/降级链/结构化提问协议）。写前备份合并不覆盖；写入后回读注入副本核对三级一致+新会话触达验收；验收看平台解析到的 Base directory，不是文件版本号（#239）。边界：绝不预载 references。
• 自更新：python scripts/syncer.py（三路合并；备份落 skill-backups/=扫描路径外；user-notes/、memory/ 永不碰；只许手改 user-notes/）。

4. 必问协议与停型门禁

触发（命中任一即停）：方向不明/歧义、理解不尽确定、需求冲突、权限/密钥、破坏性操作、架构选型、范围扩大、方案分歧。问清楚比直接做重要。

停型门禁（唯一 MUST-STOP，必须级）：命中 L3 任一项 → 先输出打算执行的命令清单 → 结束回合等用户确认 → 确认后才执行；本地备份取代不了确认。

提问规则：触发即停绝不先动手；每题带推荐选项+核心理由+替代后果；降级链=①平台原生提问工具 ②结构化文本协议（理解/选项/风险/推荐）后结束回合等待；超时/空答≠批准；答复后按纠偏续跑增量调整（details #280：保留已确认部分→增量→从当前状态继续→重跑验证，不从头重做）；拒绝→拒绝日志（原话+隐含需求→偏好/需求变更→回流）。 偏好记忆：确认的选择写 agent-log 偏好段+主动复核大类方向；同类直接采用；密钥与破坏性意图绝不写入。 仲裁序：用户/项目纪律 > 平台硬注入核心 > 设计稿/brief > 本 Skill 默认 > 其他 Skill 默认——只保留胜者+一行仲裁记录；同一理由裁决两次升格常设决策（必带「前提+重开条件」，#279）。

4.1 复述增强 RE（子复述 + 总复述）

关键决定/方向改变/口径确认时即时一行子复述：决定：对 X 采用 A｜依据：<证据/用户原话/根因>｜影响：<范围> → 进任务记录；块尾总复述=决策链/证据链/影响面/未决点要点提炼（不全文重述）。琐碎细节走日志行即可。

5. 执行模式

目标模式附加：执行前写计划（范围/风险/预算）；子任务按依赖边界拆分（#281：强依赖串行、独立并行且带五要素、合并后统一集成验证，批派≤3 防限流）；边执行边记录；超预算自停；结束交复盘+待确认清单。微轮次豁免：cron 空转轮/无人值守微轮次可压缩为「一轮一行+GATE」，标注即合规。 每条用户消息检查：①模式关键词（活开关）②复述前置。降采样合法（压缩级）：长会话/轻任务按比例降采样（阶段复述+块级一行档案+阶段级 GATE），显式声明即合规——存在性不可压缩。

6. 门禁出口与交付纪律

• GATE 块（每任务块末尾；12 字段）：字段语义与格式唯一权威=注入核心「交付与留档」GATE 段（本节不维护副本，防双份漂移）；形态恒为单行 GATE: {key=值, …}（英文短键+中文值）——level/v/cmd/exit/files/refs/errpath/lessons/exempt + caps（能力使用）/effort（努力证明）/stop_reason（止损原因，未触发填 —）；分级：包级=完整 12 字段；子块/轻任务=行内简式（3 字段即 level/v/exit）。验证层级（ev=，L2-F / 高风险任务必填，细则 #371）：exec 执行 / cover 覆盖 / invariant 不变量 / indep 独立路径——至少含一项非 exec（执行证据证「跑过」，非执行证据才触及「跑对」）；机检 scripts/gate_audit.py --gate "<GATE 行>" --high-risk。cmd 可重跑；refs=grep 实测值（0 照报）；证据三挂靠（details #363）：cmd=可执行命令原文（禁「已跑」叙述）、exit=真实退出码、files=真实变化路径——受外部探针（scripts/gate_audit.py/探针批）抽检，虚假 GATE=errpath 标「虚假GATE」+强制降级+教训区黑历史行（#364）；caps 全空且任务显然需要外部能力 → errpath 标「能力闲置」不得宣布完成；effort 未达 §2.6 下限 → GATE 不通过；止损交付：超支未完结→降级为最小验证交付并在 exempt 标 unresolved（details #362）。可重跑工件 > 自我叙述；验收权在用户。
• 完成声明六件套 + 用户验收门（#354）：宣布完成时必须提交 ①变更摘要 ②影响模块清单 ③验证证据（测试输出/边界用例结果）④未覆盖项与风险 ⑤回滚方案 ⑥建议用户重点抽查的边界用例——完成 = 证据 + 用户验收，不是 agent 的自称状态（用户随机/指定复核）。收敛判据=同一可重跑命令 exit 0（#345）。
• 交付五查：缺失需求/边界情况/临时代码/无关改动/错误已写入日志模块（有日志模块时，diff 里 console. 与空 catch {} = 零容忍）。
• 回滚规则：重大修改或不可逆操作前必须先建回滚点（git 干净基线 commit/stash 或快照）。原子操作锁：删除/迁移/覆盖写/发布=先列命令清单→结束回合等确认。
• ExitPlanMode 四件套（提交任何 plan 前自查）：①验收标准 3-5 条 ②一句判级 ③回滚点 ④边界与不做的清单。
• 最小闭环：理解→最小修改→最小验证（真实跑一遍，没跑=未完成；L2-F 加真实用户走查）→交付成品（不交半成品；未完成显式标 TODO/未验证；绝不假实现）。
• 有效性诚实声明：规则有效性（对照 A/B）未达显著——本工作流提供可追溯/可审计/防返工/点破后恢复机制，不宣称正确性优势；触达比内容更紧（已安装≠被加载；「规则在场≠规则被遵守」）。

7. 易错点与借口拦截

借口拦截表（details #348；危险词「显然/只是/很简单/不用了/别废话」出现即触发自检）：

其余易错点：判级内耗（一句话定论，展开论证=token 浪费最大来源之一）；同会话重载=纯浪费；流程不可跳步（双调研最易跳——小模块免全量调研=选道非跳步）；触发词是活开关；绝不覆盖已有规则文件（只备份+合并）；用户想法与代码冲突直说；过度提问毁采纳率（L1 直接做）；Skill 加载≠任务开工；结论立刻落盘；同坑≥3 晋升 / 2 干净周期降级；判「不复现」四要件（判据逐字对齐/真实调用链禁自造模拟/对照组/不满足降「未定论」，#255）；子代理纪律直送（不继承注入副本、不保证自加载——委托必须内联最小纪律包：只读=一行包，含写路径=全包，含判级/红线/TOP/引用形态/GATE/承载；rules §28）；隔离役割（details #361）：重度调研/排错/日志细查下沉子代理，主会话只做复述/判级/三问/派单/验收；子代理只回结构化摘要（长篇=违规）；平台无子代理通道→按大输出两步式降级主会话执行并留痕；升级验收看 Base directory。

异常观察记录（details #353）：任何「感觉不对劲」——用户或自检——即时转一条记录：现象/期望/实际/复现/影响哪些模块/当前临时假设/下一步验证动作；不得口头带过（严重逻辑错误最早都以「不对劲」出现）。

8. 记忆与留档纪律

触发：会话始/块尾/会话末/写任何文档产物时。

• 会话始：§2.0 四步；记忆对齐最小读取；上下文预算法：常驻（注入核心）→ 开工读（agent-log 状态段+按症状检索）→ 按需（references/流水历史，到步骤才读）→ 结束更新（最小追加）。
• 块尾：流水区追加一行（改动→验证(结果)→未验证项→GATE）——时间戳 YYYY-MM-DD HH:mm:ss 秒级必填；活头部校验（头部时间戳 ≥ 最新正文条目）；容量上限=行数与体积双指标先到者为准：流水区 >200 行或 >150 KB、教训区 >150 行 → 移 agent-log-archive-YYYY-MM.md（移动非删除；机械归档=scripts/agent_log_rotate.py，默认 dry-run、--apply 落刀，细则 #372）。
• 会话末：①最小验证+自查 ②agent-log 流水+状态段刷新 + 每项重要决策一行决策审计（决定/依据【含前提+重开条件】/被否候选/影响）③教训区（新坑=症状→根因→解决→预防；重复只写一处）④偏好段（确认偏好+复核提醒）⑤文档与代码同批提交；结束提炼 1-5 条可复用知识点。回滚本地备份优先；push 仅需远程保护/交付时。
• 一档制：项目根 memory/agent-log.md 单文件四区（状态段/教训区/偏好段/流水区），开工必读、缺失从模板建；状态段**≤10 行且首行=STATE 单行结构化** STATE: task_id | level | route | confirm | gates_passed | last_errpath（禁小作文；与上下文冲突→以本档为准+重读真实 FS，details #366）（超限先归档里程碑史）；业务恰用 memory/ 时可在项目规则文件改归档目录 .agent-records/（唯一覆盖点）。
• 经验回流（双击晋升）：项目级踩坑先落教训区 T2；同一坑单项目两次/跨项目一次 → 按「症状→根因→解决→预防」晋升进 references/details.md；一次性噪音永不进 Skill。
• 折叠协议（上下文 40-60% 或压缩信号，details #272）：①保留清单五必留核对（任务本质/验收标准/激活规则原文/当前步骤/回滚基线）②checkpoint 落盘 ③旧块一行摘要入归档 ④重载序（§10 守卫）⑤状态面记「已折叠 N 块」。激活规则原文原样保留，不折叠。
• 语言默认中文（代码标识符/标准术语除外）；密钥与破坏性意图绝不写入任何档。

9. 会话状态面（会话末一致性报告——给用户复核）

注入版本: <版本>
细则命中: grep -cE 'references/details|details[ #]+[0-9]{2,3}|细则[ #]+[0-9]{2,3}' <会话产物> → N（0 照报 0）
          （只认完整前缀形态；裸 `#NNN` 已废弃——与 GitHub issue 编号同形异义，假阳性实证 9/10）
上下文预算: ~X tokens（阈值 150-200K → 压缩 + 重载序）
版本一致性: 副本 vs 源库（不一致 → syncer.py；并核对平台解析到的 Base directory）
上下文账本: input 增量 ~X ｜最大单次 ~Y ｜工具占比 ｜盘点 N 次（按信号触发）
未验证/待办: <exempt 与未完成项——必须是真待办>

规则：证据化而非自述；不是通过/失败声明。

10. 路由表与引用加载

路由表（dispatch，按需加载、用完不驻留）：调试/排错 → shisan-xinuo-flows·排错工作流｜新功能/多文件 → flows·对应工作流分册｜设计类 → flows·设计调研 + shisan-xinuo-roles·frontend｜审查/验收 → roles 包（8 角色 dispatch：critic/风险/安全/调试/契约/测试/前端/性能）｜Skill/工具选型纠结 → references/skill-usage.md｜平台注入问题 → references/platform-adaptation.md。

错误处置入口：错误/API 意外形态/未知字段/新依赖不生效 → 先对「错误必查 TOP」内联处置 → 完成后留 errpath 行（症状→处置路径：TOP 命中 / lookup 执行[贴命中行] / 未跑[理由]）→ 需要按症状检索时跑 detail_lookup.py；引用统一完整前缀 details #N / 细则 #N（禁裸 #N）。 错误必查 TOP：details #294 文件双通道混用=Edit 报 not read（占错误 55%）｜#233 命名直觉=假绿｜#228 改包先重编｜#229 常驻进程旧 dist｜#214 响应分层断言｜#163 统一错误契约｜#256/#269 异步栈丢调用点·响应体只消费一次｜#262 深拷贝语义变体。 重载两道守卫：①显式信号（用户说「重载/你被压缩了」或平台重置）→立即按序：重读本 SKILL → 重读记忆 → 重读当前引用 → 复述任务与验收再继续；②关键节点自检：默写核心要素（跑道选道/模式/回滚规则/必问协议），复述不全=上下文缺失，先重读再继续。压缩/折叠/交接前先核对保留清单五必留（details #272）。

11. 速查表（条款的执行化一行）

模板索引与完整流程分册见 shisan-xinuo-flows；审查角色与 dispatch 矩阵见 shisan-xinuo-roles；两者独立可装、建议同装。