# 元帅（Marshal）双模式任命与约束 — 实现报告

> 文档编号：IMPL-RPT-024
> 日期：2026-06-12
> 关联设计：[DESIGN-ARCH-024] khyos 元帅双模式任命与约束规范
> 关联测试：[TEST-RPT-008] 元帅双模式任命 — 测试报告

---

## 1. 目标

闭环「主控模型（元帅）自动选举 ⇄ 用户强制指定」的矛盾：任何在线模型都能被任命为元帅，
且无论谁当元帅系统都稳定运行——强主放权、弱主上镣铐、连续失败可弹劾移交，全程不损坏项目文件、
不违背用户意志。

## 2. 改动清单

### 2.1 新增（`services/backend/src/services/marshal/`，9 个纯模块）

| 文件 | 行为 |
|---|---|
| `capabilityVector.js` | 层级→连续能力向量 + 加权分数 + 强/弱裁决（阈值 `KHY_MARSHAL_STRONG_THRESHOLD`，默认 65） |
| `marshalAppointment.js` | 双模式任命：`electMarshal`（reasoning 最高）/ `appointMarshal`（用户指定，**防呆②** 不在线即报错） |
| `strategySOP.js` | 预置战略库 6 意图（含 2 个只读逃生地板）+ `buildChoiceSchema` 闭枚举 + `isLegalChoice` 校验 |
| `ruleEngineGuard.js` | **防呆①** 二次校验：弱主 + 不可逆 + 未授权 → 降级须审批；红线硬拦截；逃生地板恒可行；强主 commit 豁免 |
| `weakMasterProtocol.js` | 渲染选择题 Prompt（**防呆③** 需求逐字围栏）+ `extractFirstJson` 解析 + 确定性单微步展开 |
| `strongMasterProtocol.js` | 强主赋能：全权 / 跨级指挥 / 自我反省；精简 Prompt 原样接受自由计划 |
| `contextBaton.js` | 无缝切换载体；`businessRequest` `Object.defineProperty` 冻结（**防呆③**）；mutator 返回新接力棒 |
| `impeachment.js` | 降级弹劾状态机；连续失败阈值（`KHY_MARSHAL_IMPEACH_THRESHOLD`，默认 2）；逐字精确逼宫文案 |
| `index.js` | `MarshalCoordinator` 编排——唯一对外集成面，再导出全部子模块 |

### 2.2 修改

| 文件 | 改动 |
|---|---|
| `platform/khy_platform/cli.py` | `_run_claude_code_launcher` 解析 `--marshal <model>` / `--marshal=`；`_build_khy_proxy_env(marshal=…)` 透传 `KHY_MARSHAL`；用法文档补一行。透传层不做能力封锁（用户意志至上）。 |

### 2.3 测试

`tests/services/marshal/marshalSubsystem.test.js`（node:test，35 用例）。

## 3. 关键实现决策

1. **复用既有单一真源，零重复造轮**：能力分层走 `modelTier`，可逆性走 `reversibility`，红线/活性走
   `constraintLattice`，JSON 恢复走 `safeJsonParse.extractFirstJson`，拆解走 `taskDecomposer`（仅确定性策略）。
2. **防呆落到代码而非仅 Prompt**：
   - ① `ruleEngineGuard.vetAction` 对弱主不可逆动作返回 `allowed:false, requiresApproval:true`；
   - ② `appointMarshal` 对不在线指定返回 `{error:'model_not_in_pool'}`；
   - ③ `contextBaton` 冻结 `businessRequest`，渲染器逐字嵌入；
   - ④ 全部为新文件，未触碰 toolUseLoop / 网关等核心业务逻辑。
3. **零侵入接线**：`MarshalCoordinator` 是唯一集成面，宿主按需接 `KHY_MARSHAL`；当前不强行改写核心循环
   （依防呆④留作另行评审的可选增强）。
4. **零硬编码**：所有阈值带命名默认值 + 环境覆盖；选举确定性（并列按 reasoning→池序）。

## 4. 验证

- `python3 -m py_compile platform/khy_platform/cli.py` → OK。
- `node -e "require('./src/services/marshal')"` → 9 导出全部加载。
- `node --test tests/services/marshal/marshalSubsystem.test.js` → **tests 35 / pass 35 / fail 0**。
- 既有 `reversibility` / `constraintLattice` 等模块未被修改，无回归面。

## 5. 现状

目标 10 全部六阶段闭环；三场景（自动选举 / 强主指定 / 弱主指定）端到端跑通，含弹劾→无损移交。
