# 术语账本

这份文档管的是**同一个东西在代码、界面、配置里叫什么**。改文案、加功能、写注释之前先对一遍；改名可以，但要连这张表一起改。

**三层四套名字，各有分工，不许互相借用**（新增于 2026-11-02，起因是入口页改成「破甲」定位）：

| 层 | 用在哪 | 怎么叫 | 谁定 |
| --- | --- | --- | --- |
| **定位层** | `README.md` / `README.en.md` 的开篇（`## 它做什么` 首段与五条能力） | **破甲**：它是这个项目「面向谁、解决什么」的对外说法。`README` 里写「专做破甲」「破甲词写这里」 | 作者原话，入口页以吸引与一眼读懂为目的，**别改成规格书** |
| **操作层** | 设置页五组、四个检查项、`state.json` 字段 | 五个组名 + 四个锁定标题（见下两节） | 本表 + `CHECK_TITLES` 锁定串 |
| **契约层** | `docs/brand-persona.md`、`docs/compatibility.md`、代码注释 | 「品牌人设」「内容边界文本」「声明层」等精确词 | 本表 |
| **机读层** | 配置值、字段名、档名 | `identity` / `hideHarness` / `text` / `enhanced` 等 | 代码 |

**为什么允许「破甲」与「内容边界」并存**：同一个东西在入口页叫「破甲词」、在设置页叫「内容边界」、在状态里叫 `contentScope` / `text`——这不是同物异名，是**同一功能在四个读者层上的四种叫法**。入口页的读者要的是「这玩意能帮我干什么」，设置页的读者要的是「我该点哪个」。把它们强行统一成一个词，任一层都会变成给另一层的人看的规格书。**但跨层引用时必须落到该层的名字**：README 里指向设置页时用「内容边界」，设置页里提到 README 的说法时不要自己编新词。


## 中文界面名 ↔ 机读标识符

两套名字**都合法、都要守**：中文是给人读的菜单名，标识符是给宿主看的配置值。表锁的是映射本身，**不是**把两者合并成一个名字。

| 界面名 | 标识符 | 层 |
| --- | --- | --- |
| 仅可查看 | `read-only` | 宿主档位 |
| 工作区内修改 | `workspace-write` | 宿主档位 |
| 完全权限 | `danger-full-access` | 宿主档位 |
| Enhanced | `enhanced` | 本包添加（表外档名） |

`enhanced` 是表外档名：宿主菜单把它渲染成 Title Case 的纯文字 **Enhanced**，字形表里没有它。patch 里写的是键名 `enhanced`，菜单里显示 **Enhanced**——同一个档的两层名字，别当两个档。

## 假同物异名：看着像一回事，其实不许合并

- **`suffix` ≠ `personaSuffix`**。前者是 `@deepseek-ai/dsh-persona` 的字段，后者是 `@deepseek-ai/dsh-system-prompt` 的字段——两个插件、两个字段。两者注册**同一个段名** `deployment:persona-suffix`、**同一个 order** `10200`；persona 那一行是 scope-only，挂到全局会与注册表碰撞并直接报错。任何「归一成同一个名字」的改动都是错的。
- **`custom` / `auto` 是宿主的保留档名**，写进档位表会被宿主直接抛错，**不可配置**。它们只用于派生状态与宿主的 Auto 集成；本包写档时只产基础三档加自己那个 `enhanced`。

## 同名两物：必须加限定词

| 词 | 物一 | 物二 | 消歧写法 |
| --- | --- | --- | --- |
| `ask` | 包内三态键（界面写「先问我」） | 宿主审批策略的取值（档位规格里的 `approval: ask`） | 前者写「三态键 `ask`」，后者写「审批策略 `approval: ask`」 |
| `approval` | 开关档：`shared/state.mjs` 的 `{allow, ask, deny}` | 审批策略 `approval/policy`：宿主的 `{ask, never}` | 前者写「开关档 `approval`」，后者写「审批策略 `approval/policy`」 |
| `preset` | 档位（PermissionPreset） | patch 里的一种声明类型（**仓内无实指**，依据在宿主官方文档 publish.md） | 前者写「档位」，后者写「`preset` 声明」 |
| `text` | 内容边界那段文本 | 检查项的机读键 `text` | 前者写「内容边界文本」，后者写「检查项 `text`」 |

`approval` 最容易踩：同一个模块里就有两套语义（宿主策略的 `never` 与本仓开关档的 `allow` / `ask`）。看到这个词先问一句「这是开关档还是审批策略」。

## 核心词「声明层」

**声明层**指系统提示里**描述 harness 自身**的那些注册项：开场那句自称（①），以及两段提到它名字的说明（② 实现目录、④ 界面）——一共 **5 个注册项，落在 3 个名字上**。它不是「提示词的开头」，也不是「所有带品牌的文字」。

| 名字 | 座位 | 注册项 |
| --- | --- | --- |
| `harness:identity` | section | ① 开场那句自称 |
| `harness:source` | section + runtime context | ② 实现目录说明（同名两项各算一项） |
| `app:web-surface` | section + runtime context | ④ 界面说明（同名两项各算一项） |

`dsh-enhance` 在**默认设置下**只在声明层动手，其余段落逐字节保留。**「5 个注册项 / 3 个名字」是本仓唯一口径**；宿主触点的总数与计数口径以 `docs/compatibility.md` 为权威，别在这里另立公式。其余文档提到「声明层」时引用本节，不复述定义。

## 检查项与设置组名

检查项四个机读键与标题（`CHECK_TITLES`）**逐字锁定**，改标题要连测试一起改——**这四个名字以本表为准**：

| 机读键 | 标题 |
| --- | --- |
| `plugins` | 插件在进程里 |
| `text` | 文字合规 |
| `inject` | 真的进了系统提示 |
| `preset` | Enhanced 档 |

产品侧的汇总句用的就是这四个名字。第四项在散文里可以多写「状态明确」（「Enhanced 档状态明确」）——那是附加成分，不必补进 `CHECK_TITLES`，也不必为了「一致」把它删掉。

`inject` 这一项的**口径**（不是标题）随 1.2.0 扩过一次，**键与标题仍然不动**：它同时验两路——内容边界文本（`sessionContains`），以及品牌人设（`custom` 要在日志里命中 `identity.txt` 的文本；`remove` 要用反向探针 `sessionOmits` 确认**最新一份**含 `system-prompt` 的装配记录里已经没有宿主原句；`keep` 这一路不判）。反向探针只看最新一份日志：用「最近 N 份都不含」会把切换开关前的旧日志算进来，刚打开遮蔽就永久判红。

设置页五个组名同样**以本表为准**：**品牌人设**、**内容边界**、**越界审批**、**Enhanced 权限档**、**检查**。界面文案用这五个名字；`README.md` 是入口页，写这五节时**功能名照用这五个**（开篇定位可以按定位层写成「破甲」，但落到这五节时用组名——读者在设置页里要找的是这五个词）。组 3 里那个问句「越界时怎么办」是**控件标签**，不是组名，别为了「统一」去改它。

这一节本身在设置页里叫「**增强**」——它既是宿主 `settings.section` 槽位的 label，也是版本行 `增强 <本包版本> · DSH <本机版本> · 已验 <范围>` 开头的那个词。别把它和五个组名混成一层。

### 「人设」一名三义，必须分写

「人设」这个词在本仓指三件不同的事，正文里**不许只写「人设」**：

| 写法 | 指什么 | 机读标识 |
| --- | --- | --- |
| **品牌人设** | 设置页第 1 组；替换系统提示开头那句 `You are an AI agent powered by DeepSeek Harness.` | `identity`（`keep` / `remove` / `custom`）、`hideHarness`、`identityText` |
| **部署人设** | 宿主 `deployment:persona-prefix` / `-suffix` 两段，由 `personaPrefix` / `personaSuffix` 配置与 `@deepseek-ai/dsh-persona` 供给；**不是本插件改的东西** | `personaPrefix` / `personaSuffix` |
| **尾巴文字** | 内容边界组里那段用户自写的文本，追加在系统提示末尾 | `text` / `content-scope.txt` |

「品牌人设」这个名字容易被读成宿主 persona——所以界面文案里只用「品牌人设」四个字，控件标签不写「人设开关」；内容边界的提示语也已把「写人设」改成实际那句「写行为规矩、写内容要求、写补充说明都行；它只是追加在末尾，不改 DSH 自己的系统提示。」（`ui/client.js` 的 `enh-hint` 是锁定串，以界面实际文案为准）。两处都不再单独用「人设」。

**「破甲」不在上述三名之内**，它是**定位层的对外说法**，指的是内容边界这个能力「用来干什么」（写让模型照做的语句）。它与「尾巴文字」的关系：尾巴文字是**载体**（那个 8 KB 文件里的文本），破甲是**用途**（那些文本常见的一类用途）。所以：

- 界面与契约里**仍然只用「内容边界」「尾巴文字」**，不写「破甲」（设置页的读者要的是「我该点哪个」）；
- `README.md` 的开篇与五条能力里**可以**写「破甲」——入口页要一眼说明「这玩意能帮我干什么」；
- 需要跨层指代时，README 指向设置页就说「内容边界」，不要写成「破甲那一组」（设置页里没有这个名字）。


## 声音锚点

守的是**方向**，不是某一组统计数字——数字每次改写都会漂，当判据就会自相矛盾。方向是：短句是常态、长句是例外，**不许把短句改成长句**。

- **破折号是这个声音的部件**：用来补语或转折，保留，不要为了「干净」删掉。
- **否定式是主力表达**：「档位」「只读」「越界」「不猜」这四个词保持原样，不许换同义词。
- **量与单位**：阿拉伯数字 + 空格 + 单位（`8 KB`、`10 份`、`约 15 分钟`）；口语量词用中文数字。
- **不写序数词**：不写「首先 / 其次 / 第一、第二」；有序的地方用编号列表，并列的地方用项目符号。

想量也有口径：按「含中文的连续串」为单位统计（不是汉字出现次数），看均长与长短句分布。量出来的是**当下值**，别把上一次的数字当标准。

**两套语域，各有分工，不许互相借用：**

| 语域 | 用在哪 | 口径 |
| --- | --- | --- |
| 同侪口吻 | 源码注释、测试注释 | 第三人称：说「调用方」「这一侧」「人」。注释里唯一一次「你」是转述 CLI 调用方的话，不是在对用户说话 |
| 对用户口吻 | `README.md`、界面文案 | 直呼「你」 |
| 招揽口吻（新增） | 仅 `README.md` / `README.en.md` 的 `## 它做什么` 首段与五条能力 | 短句、直给、先说「能帮你干什么」再说机制。这一段是**作者定的对外定位**，允许比其余部分更直接（「专做破甲」），但不得写未实现的能力、不得承诺效果（例如「一定能过内容审核」）。其余各节仍用对用户口吻写规格。 |

在源码注释里突然对用户说「你」，或者在用户文案里写成规格书，都是声音漂移。**招揽口吻只限入口页开头那一段**——把它扩散到设置页或契约里，就是把定位层的话塞进了操作层。

## 一条教训：策略值 ≠ 触发条件

`approval: ask` 或 `never` 描述的是**请求被分发时怎么走**，不是**请求会不会被发出**。要断言「什么情况下会发生某件事」，先找**触发源**（谁调用、在什么条件下调用），再看配置的取值。审批请求至少有两个触发源——沙箱升级、工具级的 `ask` 决策——只看策略值推结论，会推反。

落到本包那句话上：设置页那三项面向的是**越界（沙箱升级）**这条路径。Enhanced 档的沙箱已经全开、没有比它更宽的档可升，所以这条路径上不产生请求；工具级 `ask` 会不会出现，取决于部署把哪些工具配成需要确认。两句不矛盾，但都别把对方的口径算进来。

## 相关文档

- `README.md`——用户视角的入口：它是什么、怎么装。那边用的也是这五个组名、这一句适用版本。
- `docs/compatibility.md`——对哪个宿主版本负责：声明怎么被宿主执行、宿主触点、例行核验。
- `CONTRIBUTING.md`——怎么改：门禁、硬约束、提交流程。
- `CHANGELOG.md`——每个版本改了什么。