---
title: "系统提示词与能力裁剪（Meta Harness）"
description: "在新会话创建时覆盖提示词段落、关闭 middleware，或控制内置 SubAgent 定义。"
---

> Documentation Index
> Fetch the complete documentation index at: https://konghayao.github.io/peri-cool/llms.txt
> Use this file to discover all available pages before exploring further.

# 系统提示词与能力裁剪（Meta Harness）

Meta Harness 是会话创建阶段的高级配置。它可以做三件事：

| key | value | 作用 |
| --- | --- | --- |
| 系统提示词段落 ID | `true` | 用 `.peri/meta/<ID>.md` 全文替换内置段落 |
| 链槽位名 / builtin 实例策略键 | `false` | 关闭宿主 adapter 或对应 MCP 能力面；策略关闭不等于销毁连接 |
| `BuiltInSubagents` | `true` / `false` | 启用或隐藏随 Peri 编译分发的 SubAgent 定义 |

这些状态会随会话快照冻结。修改配置或覆盖文件后，请新建会话；现有会话不会中途重载。

## 配置示例

全局配置位于 `~/.peri/settings.json`，项目覆盖位于 `<cwd>/.peri/settings.json`：

```json
{
  "config": {
    "meta_harness": {
      "01_intro": true,
      "WebMiddleware": false,
      "BuiltInSubagents": false
    }
  }
}
```

这份配置会：

- 从 `<cwd>/.peri/meta/01_intro.md` 读取替换内容；
- 关闭 builtin `web` 实例的工具面，因此 Web 工具和它的提示词贡献都不会进入当前会话；
- 隐藏 compile-time 内置 SubAgent 定义。

`BuiltInSubagents` 不会关闭 `SubAgentMiddleware`，也不会隐藏项目、插件提供的 Agent，
不会禁用 fork、resume、`Agent` 或 `AgentResult`。

## 段落覆盖

可覆盖的段落 ID 由当前代码注册表决定。现有分组如下：

- 基础段落：`01_intro`、`02_system`、`03_doing_tasks`、`04_actions`、
  `05_using_tools`、`06_tone_style`、`07_runtime`、`persona`、`language`；
- 能力段落：`10_hitl`、`11_subagent`、`12_ask_user`、`13_skills`；

覆盖文件只扫描 `<cwd>/.peri/meta/` 的一级 `.md` 文件。文件名去掉 `.md` 后就是
段落 ID，正文会整段替换内置内容：

```text
.peri/meta/01_intro.md
.peri/meta/05_using_tools.md
```

段落 ID 配为 `false` 表示显式使用内置内容；middleware 名配为 `true` 可以在项目配置中
恢复被全局配置关闭的组件。全局与项目的 `meta_harness` 按 key 合并，项目同名 key 优先。

## 关闭能力：链槽位与 MCP 实例分开

合法键以契约注册表为准。链槽位控制宿主消费与编排，builtin 策略键控制对应 MCP 实例：

| 职责 | 链槽位名 |
| --- | --- |
| 上下文 | `DefaultSystemPromptMiddleware`、`LangMiddleware`、`AgentsMdMiddleware`、`PluginMiddleware`、`SkillsMiddleware`、`SkillPreloadMiddleware`、`AtMentionMiddleware`、`ImageMiddleware` |
| 任务与交互 | `GitAttributionMiddleware`、`TodoMiddleware`、`HookMiddleware`、`PermissionMiddleware`、`HumanInTheLoopMiddleware`、`SubAgentMiddleware` |
| 扩展消费与编排 | `McpMiddleware`、`ToolSearch`、`GoalMiddleware` |

| builtin 实例 | MetaHarness 策略键 |
| --- | --- |
| `web` | `WebMiddleware` |
| `artifact` | `ArtifactMiddleware` |
| `cron` | `CronMiddleware` |
| `workspace` | `WorkspaceMiddleware` |
| `workflow` | `WorkflowMiddleware` |

`WorkspaceMiddleware: false` 同时关闭文件/终端工具、技能/Agent/项目指令与覆盖资源面；
不是旧 filesystem、terminal 或 Agent 定义单项关闭的等价替换。
`AgentDefineMiddleware`、`FilesystemMiddleware`、`TerminalMiddleware`、`GitWatchMiddleware`
及退役的 `15_channel` 不再是合法键，配置中出现时告警并忽略。

MetaHarness 管理的是会话内的能力使用策略，不负责 MCP server 的安装或物理销毁。
外部 server 由 MCP 配置、连接与授权管理，不支持把任意 server 名写成 MetaHarness 键。
Agent 的 allowlist/disallowlist 和运行时审批另管工具执行权。
`McpMiddleware` 控制 MCP 消费 adapter；`ToolSearch` 控制额外工具发现/执行入口，
两者都不是 pool shutdown，也不是任意外部 server 的独立关闭键。

关闭能力必须形成闭包：direct 工具、deferred 搜索索引、命令路由、提示词说明、
SubAgent/Workflow 继承面都不能继续暴露已经关闭的能力。遇到“工具已关闭但模型仍认为可用”
时，应把它视为实现问题，而不是让用户再写一段提示词规避。

## 审批与提问是两项能力

- `PermissionMiddleware` 负责敏感工具审批，并持有 `10_hitl`；
- `HumanInTheLoopMiddleware` 负责 `AskUserQuestion`，并持有 `12_ask_user`。

关闭前者不会自动关闭提问；关闭后者也不会自动进入 Bypass。不要用其中一个开关替代另一个。

> **Meta Harness 不提供新的权限**
>
> 关闭本地 middleware 不会替远端 MCP server 做授权，也不会创建操作系统沙箱。
> 覆盖安全段落只能改变模型看到的说明，不能改变运行时 policy 与审批事实。

## 安全地验证配置

每次只改一个 key，并在新会话中验证：

1. 预期 middleware 是否进入生产链；
2. direct 工具和 deferred 搜索结果是否同时符合预期；
3. 对应提示词段落或 request-time contribution 是否存在；
4. 审批、提问和外部系统边界是否仍符合任务要求。

恢复时删除项目级 key；如果同名 key 来自全局配置，还需要修改全局配置。删除段落覆盖 key
后，可再删除对应 `.peri/meta/<ID>.md`。

相关内容：[工具系统](/peri-cool/docs/features/tools/) · [Skills](/peri-cool/docs/features/skills/) · [权限系统](/peri-cool/docs/features/permissions/)

Source: https://konghayao.github.io/peri-cool/docs/features/meta-harness/index.mdx