# 元规划协议与动态约束注入 — 实现报告

> 文档编号：IMPL-RPT-025
> 日期：2026-06-12
> 关联设计：[DESIGN-ARCH-025] khyos 元规划协议与动态约束注入规范
> 关联测试：[TEST-RPT-009] 元规划协议与动态约束注入 — 测试报告

---

## 1. 目标

闭环「JS/混合语言环境下的灵活执行 vs 约束」矛盾：让模型在执行前先自决**用哪些执行器 + 上多重的锁**，
系统据此**按需配发锁具，绝不提前加锁**——低风险极速、高风险绝不裸奔；模型自决失误时熔断自愈。

## 2. 自调查结论（§1，僵化逻辑定位）

| 僵化点 | 证据 | 损耗 |
|---|---|---|
| 执行器硬编码指派，模型无选择权 | `toolCalling.js:2609-2642` 对 `descriptor.source` 硬 `switch` | 无法按任务选 AST 写手 vs 裸替换 |
| 编辑工具无 AST 安全网 | `editFile.js:110-145` 纯 `String.indexOf/slice/split` | 语法错误可直写磁盘 |
| 守卫一刀切、无风险分级 | `toolGuards.js:358-413` 按文件名模式统一施加；`riskGate.stepType` 仅审计 | 改注释与重构同路径 |
| 安全 Prompt 无条件整段注入 | `generalPurposeAgent.js:34-36` 整段 `EXECUTION_DISCIPLINE+HARD_PROHIBITIONS` | 低风险白烧 Token |

## 3. 改动清单

### 3.1 新增（`services/backend/src/services/metaplan/`，7 个模块，零侵入）

| 文件 | 行为 |
|---|---|
| `constraintStrategy.js` | 三级约束枚举 + 单调升级格 `escalate`（LUB）；未知策略 fail-safe 取最严 |
| `executorRegistry.js` | §4 武器库闭集（4 执行器）+ `validateToolchain`（**防呆②** 拒捏造）+ `describeForModel`（菜单单一真源）|
| `metaPlanSchema.js` | §2 元规划契约：`buildMetaPlanSchema`（enum 来自活注册表）+ `parseMetaPlan`（**防呆①**）+ `validateMetaPlan`（防偷懒升级）|
| `codeInterceptors.js` | §3 真实拦截器：`babel`/`python_ast`/`vm`/`balance`；缺工具链 fail-safe `{ok:true,skipped:true}`，永不卡死 |
| `constraintInjection.js` | §3 注入引擎：`resolveInjection`（挂什么锁）+ `runHardValidation`（真跑校验，Soft 快放行）|
| `constitutionalRedLines.js` | §5 宪法红线：删库/暴露机密/删核心依赖，按动作匹配强制 `System_Block`（**防呆④** 不可覆盖）|
| `trustCircuitBreaker.js` | §5 信任熔断状态机：类型级扣分 + 连续 2 次翻车全会话锁定（**防呆③**）|
| `index.js` | `MetaPlanCoordinator` 四步编排闭环 + 再导出全部子模块（唯一集成面）|

### 3.2 测试

`tests/services/metaplan/metaPlanSubsystem.test.js`（node:test，31 用例）。

## 4. 关键实现决策

1. **真拦截器非桩**：JS 走项目已装的 `@babel/parser`（回退内置 `vm`）；Python 走 `python3 -c ast.parse`
   子进程；跨语言退化为括号/引号配平。已实测坏代码被打回、好代码通过。
2. **fail-safe 降级**：任何校验器在工具链缺失时返回 `{ok:true, skipped:true}`，**不比今天更差**，
   绝不因缺 babel/python 卡死 agent；校验器永不向上抛异常。
3. **override 单调取严**：熔断地板、宪法红线均只经 `escalate` 加锁；`ingestMetaPlan` 把红线置于叠加最后，
   使「不可覆盖」一目了然。
4. **防偷懒确定性升级**：`Prompt_Soft` 缺/短 `risk_dissent`（< `KHY_METAPLAN_MIN_DISSENT`，默认 12）
   自动升 `Code_Hard`，原因入 `escalations[]`。
5. **零侵入**（防呆⑤）：全部新文件自成子目录，未改 `toolCalling`/`editFile`/守卫/网关；`MetaPlanCoordinator`
   供调度器按需调用，接线为后续单独 PR（与 [DESIGN-ARCH-024] 同样的渐进策略）。
6. **零硬编码**：阈值全部命名默认值 + 环境覆盖（`KHY_METAPLAN_MIN_DISSENT`、`KHY_METAPLAN_SESSION_TRIP`、
   `KHY_PYTHON_BIN`）。

## 5. 验证

- `node -e "require('./src/services/metaplan')"` → 全部导出加载。
- `node --test tests/services/metaplan/metaPlanSubsystem.test.js` → **tests 31 / pass 31 / fail 0**。
- 真校验冒烟：坏 JS/坏 Python/不配平括号被拒，好代码通过；裸执行器放行。
- 未触碰任何既有模块，无回归面。
