Mortis 指挥层与 Guard 双脑架构规范

目标与定位

本文是 Mortis controller / queue / Codex 执行链的专题 canonical 规范，用来把“指挥层决策 + 执行层操作”的双脑架构固定成可落地的真源，而不是继续停留在聊天里的口头约束。

它不替代 任务包与能力分层路由规范.md 的通用执行基线，而是在 Mortis 的 controller、task queue、Guard 审查、Codex 执行场景下，补一层更硬的结构化约束。

一、总原则

1. controller 决策，Codex 执行；执行器默认不能自己扩展范围。
2. 先判层，再定入口，再定 allowed_files，最后才允许执行。
3. 任何问题先做 minimal experiment，禁止跳过实验直接持久化。
4. 一个任务只允许一个主入口文件或主入口点，避免多入口并行改动。
5. 未达到 V3 之前，执行链不得声称“成功”。

二、四层架构

核心口径只有一句话：Codex 不是 planner，而是 executor。

三、层级模型 L1-L6

这张表的用途不是分类好看，而是决定“问题应该从哪个入口修”。

四、越层规则

1. 若问题属于 L1 / L2 / L3，禁止直接改 L4 / L5。
2. 若问题属于 L4，才允许改业务代码；能在配置层解决时不优先碰代码层。
3. 若问题属于 L5，必须明确系统调用边界、信号来源和 kill / spawn 影响面。
4. 若问题属于 L6，仍要先判断真实故障是否来自更低层；网络症状不能自动推导成代码问题。
5. 一个 execution_plan 只能有一个 target_layer，其余只作为 allowed_layers 的补充，不允许多主层并行。

典型映射

{
  "WindowsTerminal/settings.json": "L1",
  "keybindings.json": "L1",
  "PowerShell_profile.ps1": "L2",
  "config.toml": "L3",
  "*.ts|*.js|server/**": "L4",
  "win-spawn-relay.mjs|signal相关": "L5"
}

这份 layer_map 应由 Guard 与 task_gate 共享，而不是每个 agent 临时脑补一份。

五、execution_plan 作为唯一执行凭证

所有可执行 task 在进入 queue 前都必须带 execution_plan。没有 plan，Guard 直接 BLOCK。

Canonical 结构

{
  "problem_type": "terminal_input",
  "host": "WindowsTerminal+PowerShell",
  "target_layer": "L1",
  "allowed_layers": ["L1"],
  "allowed_files": ["WindowsTerminal/settings.json"],
  "forbidden_files": ["codex/**", "server/**", "*.mjs"],
  "steps": [
    "读取 settings.json",
    "修改 ctrl+c 绑定为空输入",
    "保存"
  ],
  "minimal_experiment": [
    "临时修改并测试 ctrl+c 行为"
  ],
  "success_criteria": [
    "ctrl+c 无中断",
    "复制不受影响"
  ],
  "verification_level_required": "V3"
}

字段职责

• problem_type：controller 对问题本质的分类，不由执行器反推。
• host：宿主组合，例如 WindowsTerminal+PowerShell、Mortis+TaskQueue。
• target_layer：主修复层；只允许一个。
• allowed_layers：本轮允许触达的层；不在其中即视为越层。
• allowed_files：白名单；执行器只能改这里。
• forbidden_files：显式黑名单，用于防止“顺手改”。
• steps：正式执行步骤；执行器不得新增步骤。
• minimal_experiment：先验证假设的最小动作；未执行则不能持久化。
• success_criteria：控制器定义的完成条件；不是执行器自由发挥的“看起来正常”。
• verification_level_required：最终最低验收门槛。

六、强制流程

6.1 标准顺序

1. controller 输出层级诊断表。
2. 执行 minimal_experiment。
3. 回传实验结果与当前验证等级。
4. controller 决定是否允许进入持久化步骤。
5. 仅在 plan 允许时执行正式步骤并写回结果。

6.2 诊断表最小字段

这张表必须先于真实改动出现；没有诊断表，说明 controller 还没真正定边界。

七、验证等级

在 Mortis controller / Guard / Codex 这条执行链内部，统一使用 V0-V4 口径，不用 verified 这个词来替代真实验证等级。

注意：Atramenti 的 verification bundle 仍可保留 verified / unverified / failed 作为外层交付分类，但那是文档归档层，不是执行器内部状态机。

八、禁止行为

1. 不得跨层修改。
2. 不得同时改多个入口。
3. 不得未实验直接持久化。
4. 不得修改 allowed_files 之外文件。
5. 不得自行扩展问题范围。
6. 未达到 V3 不得输出成功。

这些规则不是建议，而是 Guard 的硬门槛。

九、MCP Guard 规则

Guard 在 task 创建前和执行前都可运行一次；任何一次失败都直接 BLOCK。

if execution_plan 不存在 -> BLOCK
if target_file 不在 allowed_files -> BLOCK
if file_layer 不在 allowed_layers -> BLOCK
if problem_layer in {L1, L2, L3} and target_layer in {L4, L5} -> BLOCK
if minimal_experiment 未执行 -> BLOCK
if 声明 success and verification_level < V3 -> BLOCK

Guard 的三个子检查器

• layer_guard：根据 layer_map 检查是否越层。
• scope_guard：限制只能修改 allowed_files。
• verification_guard：要求输出结论达到 plan 指定的验证等级。

Guard 的职责不是补 plan，而是拒绝坏 plan、越权执行和伪成功。

十、Mortis 接入架构

A. controller_session

• 新增会话类型，只负责生成 execution_plan。
• 默认不执行 task。
• 适合需要人工确认或高风险分层判断的入口。

B. issue + task_queue（主方案）

• controller 在 issue 创建或 agent 指派前生成 plan_json。
• plan_json 写入 issue metadata / task metadata。
• task_gate 调用 Guard 校验，通过后才入队。
• daemon 从 queue 取任务，再调用 Codex 作为执行器。

这是推荐主路径，因为它把 plan、queue、Guard、executor 串成了一条硬链，而不是靠执行器自觉。

C. autopilot

• autopilot 作为策略脑自动生成 plan 并触发 task。
• 仍需经过同一套 Guard 和 task_gate。
• 它可以替代人工 controller 生成 plan，但不能绕过 Guard。

十一、数据流

用户 / 事件
  -> controller_session 生成 execution_plan
  -> 写入 issue 或 task metadata
  -> task_gate 调用 MCP_GUARD 校验
  -> 通过后创建 task
  -> daemon 从 queue 领取任务
  -> 执行 agent（Codex 等）
  -> 回传 progress / result / verification_level
  -> controller 判断继续、结束或升级回归验证

关键点是：queue 前一定先 Guard；Codex 之后一定回 controller，而不是让执行器自己宣布完成。

十二、数据库与服务接入点建议

12.1 字段建议

• issues.plan_json
• tasks.plan_json
• tasks.verification_level
• chat_session.controller_plan

如果现有 issue / task 结构已有 metadata 字段，也可以先把 plan 放入 metadata，再逐步显式 schema 化；但语义上仍应保持同名职责。

12.2 服务接入点

推荐在 server/internal/service/task.go 的入队前加：

1. validate(plan_json)
2. layer_guard(plan_json, target_files)
3. scope_guard(plan_json, target_files)
4. verification_guard(plan_json, requested_status)

不通过则拒绝入队。

十三、Codex 执行约束

Codex 必须以“收到 execution_plan 的执行器”身份工作，而不是 assistant 式 planner。

允许行为

• 读取 allowed_files
• 执行 steps
• 执行 minimal_experiment
• 回传日志、diff、当前验证等级

禁止行为

• 自行新增步骤
• 修改其它文件
• 自己改 verification_level_required
• 发现阻碍后擅自换层修复
• 输出解释性长文替代结构化结果

推荐输出格式

1. 层级诊断表
2. 执行日志
3. diff
4. 当前验证等级

执行器不负责“讲道理”，只负责回传受约束的执行结果。

十四、最小实验与单点修改原则

最小实验原则

任何问题先做临时方案验证，再决定是否持久化。例如：

• 终端问题先临时改宿主快捷键。
• 配置问题先用单次环境变量或临时 config 覆盖验证。
• 进程问题先用单次 kill / spawn / dry-run 验证因果，再改长期 handler。

单点修改原则

一个任务默认只允许一个主入口文件或主入口点。原因不是机械限制，而是为了防止“同一个问题同时改宿主配置、业务代码、进程 handler”，最后谁起作用都说不清。

十五、落地顺序建议

1. 先把 execution_plan 与 verification_level 字段打通到 issue / task metadata。
2. 再把 task_gate + MCP_GUARD 插到 queue 入口。
3. 再收紧 Codex executor 的输入输出契约。
4. 最后再考虑 controller_session 和 autopilot 的自动化程度。

这样能先建立硬门禁，再补“谁来生成 plan”的智能层，而不是一开始就让 autopilot 自动下发无门禁任务。

十六、一句话模板

你是执行器，不负责思考；仅按 execution_plan 执行。禁止越层、禁止扩散、先实验再持久化，未达 V3 不得声称成功。

这是 Codex 侧的最小提示词模板，但真正的约束主体仍然应该是 controller + Guard，而不是提示词本身。

十七、Execution Gateway 作为硬门禁层

上面的 controller / Guard / executor 结构还不够；如果没有真正的执行入口拦截，规则仍会退化成“建议”。因此需要在执行器之前再放一层 Execution Gateway。

17.1 Gateway 的唯一职责

Execution Gateway 不负责思考，不负责补 plan，只负责三件事：

1. 判断任务能否开始。
2. 判断当前动作能否执行。
3. 判断执行结果能否进入“已完成”。

17.2 三道门

A. 任务门

• 判断任务是否 trivial。
• 判断是否必须先写 plan。
• 判断是否需要工具 / MCP / 远端协同。
• 未通过就直接阻断启动。

硬规则口径：

No plan -> no execution
No mode / route -> no execution

B. 动作门

• 命令执行、浏览器打开、文件修改、MCP 调用、远端访问都必须先过 Gateway。
• AI 不直接触发外部能力；AI 只能请求 Gateway 执行动作。

C. 完成门

• 执行完成不等于任务完成。
• 必须检查真实结果、artifact、残留进程 / 页面 / 锁、验证等级。

硬规则口径：

No verification -> no completion

17.3 Gateway 是程序，不是提示词

这里的门禁必须落在代码层，而不是继续堆在文本规则里：

if no plan -> block
if tool route exists and no tool path chosen -> block
if no verification artifact -> block

因此至少要有三类可执行模块：

• task_gate
• action_gate
• verify_gate

十八、能力网关层

Execution Gateway 只负责准入；真正与外部世界接触的能力，需要继续收口到更窄的能力网关。

18.1 Command Gateway

职责：

• 所有命令统一从这里出去。
• 统一处理 stdout / stderr / timeout / kill / 退出码。
• 切断不受控启动链，避免 cmd.exe -> npx.cmd -> shell wrapper 这种漂移路径重新长出来。

推荐链路：

executor -> command gateway -> node + real js entry

18.2 Browser Manager

AI 不直接操作 Playwright / Puppeteer，只能走 Browser Manager。它至少应提供：

• open_page
• verify_page
• act_page
• list_pages
• close_task_pages

补强要求：

• 自动回收 browser / context / page
• 任务级 tab 上限
• 先 verify 再 act
• 截图 / DOM / console 作为 artifact

18.3 File Gateway

全局系统不能让执行器任意读写任意文件，因此要有 task-scoped file sandbox：

• 读哪个文件
• 能不能写
• 是否越界
• 是否触碰系统关键路径或别的项目边界

核心原则：

某个任务只能动自己的工作区与允许路径

十九、多 agent 的最小协同结构

如果任务升级为多 agent，最小正确结构只有三类角色：

• Planner
• Guard
• Executor

19.1 职责分工

Planner

• 判断任务类型
• 拆步骤
• 决定模式（FAST / DEEP / AGENT）
• 写 plan

它不执行代码，不直接碰环境。

Guard

• 审查计划
• 审查动作
• 审查结果
• 判断是否偏航

它不负责出主意，也不负责执行。

Executor

• 调网关
• 执行动作
• 返回结果

它不能扩 scope，不能自己升级任务，不能绕过 gate。

19.2 单向依赖

依赖关系必须锁死成：

Planner -> Guard -> Executor -> Guard

禁止：

• Executor 反向主导 Planner
• Executor 绕过 Guard

19.3 模式切换

不是所有任务都需要完整三代理，因此保留三种模式：

• /fast：小任务，直接执行
• /deep：中型工程任务，允许更多分析
• /agent：复杂任务，进入完整多代理流程

默认仍是 fast，但遇到下列条件自动升级到 deep 或 agent：

• 多步骤浏览器自动化
• 跨本机 + 服务器
• 超过 2 个文件修改
• 持续运行任务
• 高不确定性任务

二十、Mortis 与外部 Web GPT 的角色边界

Web ChatGPT 可以接入，但它不适合作为核心执行后端，只适合作为高层策略脑或人工辅助顾问层。

20.1 适合做的事

• 高层规划
• 复杂解释
• 策略讨论
• 人机协同咨询

20.2 不适合做的事

• 高频自动调用
• 关键任务主后端
• 稳定执行引擎

20.3 推荐接法

如果 Mortis 需要调用 Web ChatGPT，应通过独立桥接层：

Mortis
  -> Web GPT Bridge
  -> Browser Session / Human-in-the-loop
  -> ChatGPT Web

这个桥只负责：

• 发问题
• 收回答
• 存归档
• 作为高层建议输入

它不直接拿 Web ChatGPT 去操控系统。

二十一、本机与服务器的执行边界

默认原则不是“一律本机”也不是“一律远端”，而是：

能远程执行的，优先远程
必须本机人工介入的，才留本机

21.1 本机更适合承载的动作

• 登录
• 验证码
• 本机 GUI / 输入设备相关验证
• 本机浏览器会话与人工确认点
• 用户工作站独占资源

21.2 服务器更适合承载的动作

• 可重复批处理
• 长时任务
• 与控制面 / deploy target 同机更稳定的任务
• 不依赖人工交互的脚本链

Mortis 的职责是决定任务落在哪一侧执行；Gateway 的职责是保证“落在哪一侧”之后，动作仍然是受控的。

二十二、Mortis 团队分工与 owner tree

在 PLAN-20260422-014314 已验证的 live 最小三角基础上，Mortis 不应直接照搬 Atramenti box 的 CEO / PMO / HR 办公室隐喻，而应吸收其中更可迁移的结构：profile 与 runtime 解耦、owner tree 明确、编排层保持薄、handoff/approval/artifact 有标准对象。

22.1 当前已验证的最小三角

当前 live 工作基础仍是：

Mortis Operator
Mortis Builder
Mortis Guard

它已经证明：

• Operator 可以真实接活、读取 live workspace、路由 issue 并收口结果。
• Builder 可以在受控路径内完成本地/仓库执行。
• Guard 可以对真实 run 和结果做 PASS / BLOCK 审查。

因此后续扩编必须建立在这个三角之上，而不是重做一套新控制面。

22.2 推荐扩编结构

推荐把 controller 保持为逻辑上游，而不是一开始就强制建成常驻 live agent。

Mortis Controller
  -> Mortis Operator
      -> Mortis Planner
      -> Mortis Researcher
      -> Mortis Architect
      -> Mortis Builder
      -> Mortis Guard
      -> Mortis QA
      -> Mortis Ops
      -> Mortis Recoverer
      -> Mortis Archivist

其中：

• Controller：逻辑决策脑，负责判层、定边界、产出 plan；可由人工 controller_session 或 autopilot 承担。
• Operator：统一入口、任务分诊、agent 指派、结果汇总、升级和 closeout。
• Planner：把需求压成 execution_plan，不直接执行。
• Researcher：补上下文、查现状、查文档、查外部资料。
• Architect：做跨模块/跨系统结构判断，不直接落地。
• Builder：只按 plan 执行，产出 diff、日志和 artifact。
• Guard：审 plan、审 scope、审验证等级和 closeout。
• QA：专注 browser.run、UI、smoke、回归和用户可见验证。
• Ops：负责 deploy、runtime、host、service、告警与恢复。
• Recoverer：追索失败 run、遗留任务、丢失状态与漂移会话。
• Archivist：归档 verification bundle、handoff、证据链和历史决策。

22.3 owner tree 规则

默认 owner 关系建议如下：

controller
  owner: none
 
operator
  owner: controller
 
planner / researcher / architect / builder / guard / qa / ops / recoverer / archivist
  owner: operator

核心约束：

1. Builder 与 Guard 必须平级，不能互相拥有。
2. QA 与 Ops 是侧翼角色，默认也归 Operator，不直接拥有 Builder。
3. Planner / Researcher / Architect 只提供 plan、背景和结构判断，不直接触发落地动作。
4. 所有 override、重派与升级默认由 Operator 发起；Controller 只处理更高层的边界重判。

22.4 推荐部门划分

为了让前端和状态投影更易读，推荐分为五个逻辑部门：

22.5 路由规则

默认路由顺序建议如下：

Issue / Event
  -> Operator
  -> (Planner / Researcher / Architect as needed)
  -> Guard 预审
  -> Builder / QA / Ops
  -> Guard 复审
  -> Operator closeout

补充规则：

• 信息不全 -> Researcher
• 需要拆 plan -> Planner
• 涉及结构设计 -> Architect
• 直接落地 -> Guard 预审后给 Builder
• 需要浏览器或用户可见验证 -> QA
• 涉及 deploy/runtime/host/service -> Ops

22.6 实施顺序

扩编不要一口气铺满，按三阶段推进：

1. Phase 1：保留 Operator / Builder / Guard，新增 Planner / QA / Ops 三个 profile。
2. Phase 2：补 Researcher / Architect，把 route/handoff 标准化。
3. Phase 3：再考虑 Recoverer / Archivist 与更重的 control-room 可视化。

这能保证 Mortis 先把执行链跑稳，而不是先变成一个巨型办公室 UI。

22.7 Phase 1 首版落地定义

Phase 1 的目标不是让 Mortis 一夜之间长成完整组织，而是把现有 Operator / Builder / Guard 执行链扩成一个能稳定拆 plan、做可见验证、做 deploy/runtime 收口的最小作战队。

本轮只新增三个 profile：

• Planner
• QA
• Ops

它们都默认由 Operator 拥有和调度，不单独拥有队列入口，也不绕过 Guard。

22.8 Phase 1 角色触发与对象契约

补充硬规则：

1. Planner 的输出对象必须是可交给 Guard 和 Builder 的 execution_plan，而不是长篇建议。
2. QA 的输出对象必须带 artifact 引用，不能只回“已验证”。
3. Ops 的输出对象必须带 target / runtime / result 三元组，不能只回“已部署”。

22.9 与 Operator 的拥有关系

Phase 1 下 owner tree 仍保持简单：

Controller
  -> Operator
      -> Planner
      -> Builder
      -> Guard
      -> QA
      -> Ops

这里有三个明确边界：

1. Operator 负责挑选谁来接下一棒，但不替代子角色产出其专属对象。
2. Planner / QA / Ops 都不能直接把任务标记为完成，最终 closeout 仍回到 Operator。
3. Guard 继续作为平级审查者存在；Planner 不能越过 Guard 直接派给 Builder，Ops 也不能因为“只是部署”就跳过 Guard 或完成门。

22.10 Phase 1 标准 handoff

Phase 1 先不要求引入全新的复杂消息总线，但交接内容至少要标准化为下列字段：

• fromProfile
• toProfile
• reason
• target
• expectedOutput
• artifacts
• blockingQuestions
• approvalNeeded

最小 handoff 约束：

• Operator -> Planner：必须给出任务目标、范围边界、已知约束。
• Planner -> Guard：必须给出 execution_plan、验证标准、风险和 route 选择原因。
• Guard -> Builder / QA / Ops：必须给出 PASS/BLOCK 与具体条件，不能只回抽象态度。
• Builder -> QA：必须给出可验证对象、预期可见结果、必要启动方式和已有 artifact。
• Builder / QA / Ops -> Guard：必须给出 closeout 前的证据链，供复审。
• Guard -> Operator：必须给出是否可 closeout、是否需要补审批、是否仍有剩余 gap。

22.11 Phase 1 审批边界

新增 Planner / QA / Ops 后，审批边界应比最小三角更清楚：

硬边界：

• Planner 不能批准自己的 plan。
• QA 不能以“页面打开了”替代 Guard 的完成门。
• Ops 不能以“服务启动了”替代线上/运行态验证。

22.12 Phase 1 路由矩阵

Operator 在首版可以按下表路由，避免把所有事都丢给 Builder：

默认 route 口径可以简写为：

Need structure -> Planner
Need implementation -> Builder
Need visible proof -> QA
Need runtime/deploy -> Ops
Need policy/closeout decision -> Guard -> Operator

22.13 Phase 1 完成标准

只有满足下面条件，才能说 Planner / QA / Ops 第一版已真正落地，而不是只在文档中出现：

1. Operator 能把任务稳定路由给这三个 profile，而不是继续全塞给 Builder。
2. Planner 的输出已收敛成 execution_plan 对象，而不是自由文本。
3. QA 至少能覆盖 browser.run / 前端页面 / smoke 的证据链。
4. Ops 至少能覆盖 deploy target / runtime state / recovery action 的记录。
5. Guard 仍然卡住 plan、完成门和 override，而不是被新角色绕空。

二十三、Mortis 结构化对象草案

Mortis 当前已有 issue / task / run / runtime / comment 这些基础对象；后续若要把团队编排落得更稳定，建议追加但不平行替代以下对象：

• agent profile
• agent instance projection
• approval record
• override decision
• artifact manifest
• handoff message

本规范只固定语义和职责；可直接复制的 TypeScript 草案放在：

E:\My Project\Atramenti-Console\codex\_artifacts\task-packs\20260422-mortis-team-structure-schema\mortis-team-schema.draft.ts

23.1 agent profile

用途：

• 定义角色，不定义具体运行时实例
• 表达 role / department / ownerProfile / capabilities / allowedActions
• 让同一 runtime 可以承载多个 profile，而不是把角色永久绑死在 provider 上

23.2 agent instance projection

用途：

• 把 live agent 当前状态投影出来，给列表页 / control-room / issue detail 用
• 表达 profileId / runtimeKind / ownerAgentId / currentTaskId / approvalsNeeded / state

这一层对应的是“运行中的谁正在做什么”，而不是“组织上谁负责什么”。

23.3 approval record

用途：

• 记录 scope_expand / layer_override / deploy / runtime_reassign / closeout_override
• 统一保存 reason / riskLevel / decidedBy / evidenceRefs

Guard 可以 BLOCK，但是否 override 应通过标准 approval/override 记录，而不是只留在评论文本里。

23.4 artifact manifest

用途：

• 统一记录一次执行对应的 artifact 列表，而不是让前端去猜 comment 或 task.result
• 尤其适合 browser.run、smoke、proof-file、verification bundle

对 browser.run，建议最小固定产物为：

• screenshot
• html_snapshot
• json_result
• run.summary 或 verification_bundle

23.5 handoff message

用途：

• 标准化 Operator / Planner / Builder / Guard / QA / Ops 之间的交接
• 把现在很多只存在于 comment 文本中的隐式交接，升级成显式消息

推荐消息种类：

• task
• event
• response
• handoff
• review_request
• review_result

23.6 推荐状态机

建议把后续前端、API 和 closeout 口径统一为：

• issue: todo -> in_progress -> in_review -> done
• task: queued -> running -> completed | blocked | failed
• approval: pending -> approved | rejected | expired
• handoff: created -> delivered -> acknowledged -> resolved

23.7 当前最值得先落的字段

若只做最小增量，优先级如下：

1. agent.profileId
2. agent.role
3. agent.ownerAgentId 或 ownerProfileId
4. task.context.handoff
5. task.context.execution
6. run.result.artifactManifestId
7. 独立 approval 记录

这七项足以把 Mortis 从“最小三角已跑通”推进到“可持续扩编而不失控”的状态。