# 提示词优化与规则组装

本文面向 Iris 0.2.3，介绍对话草稿的忠实整理、明确改写、可选建议和零模型调用的规则组装。结果先进入预览，写回不会自动发送。

## 用途选择

面板将一般功能放在可折叠卡片中，按“通用、画图、改图、视频、数字人”选择用途。当前草稿、本次规则、操作、可编辑结果和对照属于同一功能区域；折叠不清空选择、规则或结果，也不触发模型请求。指令与模型设置独立折叠，可在调用前查看当前系统指令和目标模板。浏览器原生对话框在顶层显示，避免宿主悬浮按钮遮住结果。桌面和窄屏使用同一流程，支持点击背景或 Escape 关闭、焦点恢复与对话框内键盘焦点循环。

| 目标 | 标识 | 内置优化重点 |
|---|---|---|
| 通用 | `general` | 目标、背景、约束、输出和验收 |
| 画图 | `image` | 主体、场景、构图与已指定风格 |
| 改图 | `image-edit` | 明确修改范围，保持原图其余特征 |
| 视频 | `video` | 动作先后、镜头与连续性 |
| 数字人 | `s2v` | 已有首帧与音频下的人物动作、表情和镜头 |

默认指令参照项目 Skills 的职责、目标、输入、保持/改变和输出组织方式，并使用实际 Iris 工具语义。S2V 指已有首帧加音频的数字人视频。优化器仍只编辑草稿，不读取图片/音频、不生成媒体，也不冒充已经检查素材；具体方位、数量、颜色、数值、引用原文和否定条件必须保留。模型实际是否遵守仍需用户检查原文对照。

v1 配置兼容：增加 `targets["image-edit"]`，旧配置缺少此项时只在内存补齐，不自动重写文件。既有 systemPrompt、目标模板与模型路由优先保留，包含用户自定义 s2v 文本；用户显式恢复默认后才替换为新的内置指令。没有新增规则持久格式、特殊功能或 CLI。

### 编辑方式

新界面默认选择 **忠实整理**：模型只选择相邻原文片段之间的分段位置，程序从原稿拼回正文。每个片段必须恰好出现一次、句序保持，遗漏、重复、调换或新增内容都会拒绝。条件、动作先后、引文、代码和复杂格式采用保守分段；已有完整文本允许保持原样。忠实整理保证原文片段和顺序，不是自动证明所有排版变化的语义完全相同。

需要等义润色或明确改变某个项目时，选择 **改写表达** 并填写本次改写规则。例如“只把白色丝袜改为黑色，其余保持”授权改变指定颜色；其余事实和否定继续保留。忠实整理不会静默执行或丢弃改写规则。改写表达仍是模型生成文字，新增含义与遗漏需查看对照，不能以结果非空证明忠实。

结果中的 **可选补充与待确认** 独立于正文。点击“获取补充建议”才新增一次模型调用，不自动生成第二轮；默认未勾选，勾选也不改正文，点击“采纳所选建议”后才加入可编辑预览。采纳与撤回不调用模型、不直接写回或发送。手动修改预览会清除旧建议绑定，避免撤回旧快照覆盖你的编辑；再次获取建议针对当前文字。失败、取消、会话切换或请求期间文字变化不会把迟到建议写入预览。

只组装仍为零模型调用。旧后端未声明编辑能力时保留原“智能优化”流程，不发送其不支持的新策略。会话/fixed 模型选择保持，不因为选择“画图”用途就进入生图模型池，也不硬编码供应商默认模型或失败后自动切换。

## 使用

在 DSH 输入框写入未发送的纯文本草稿，打开 🫧 并选择用途。0.2.2 提供五用途和一般功能新布局；旧 0.2.1 的四目标调用仍兼容。

“本次规则”可填写以下内容；留空表示不选择。规则只在当前组件中保留，刷新后重置，不改写已有 `prompt-optimizer.json`。

| 内容 | 智能优化 | 只组装 |
|---|---|---|
| 改写规则 | 指导模型如何编辑草稿，不要求将规则原文抄入结果 | 不使用 |
| 输出前缀 | 模型改写完成后，程序原样加入开头 | 原样加入原稿开头 |
| 输出后缀 | 模型改写完成后，程序原样加入末尾 | 原样加入原稿末尾 |

需要模型的优化进行一次文本生成；单片段忠实整理直接保留原文，不调用模型。只组装不读取模型路由或优化配置、不调用模型，在 Host 文本服务不可用时仍可使用。只组装不会套用目标模板或自动润色原稿。规则之间与正文之间用两个 LF 分隔；输出规则原文与只组装的草稿空白保持不变。

结果先进入可编辑预览。可以查看原文、本次参与规则、实际模型与思考策略，以及折叠相同首尾后的中间替换区。这是文本改动对照，不代表模型解释了每处改动的原因。手动编辑也会更新对照；复制和写回使用编辑后的文字。

改写结果会在拼接前后缀之前检查未由原稿/明确改写规则提供的新链接、媒体标记和明显的执行完成/拒绝回复；已有合法链接、原文引用及只组装保留。忠实整理与建议模式另检查专用 JSON 形状、片段序列或建议字段，未授权正文不能混入。检查不构成任意自然语言的完整语义证明。拒绝后不自动重试、切换模型或写回；上游可能已经处理请求，不能据此推定没有计费或媒体副作用。

写回不会自动发送。出现新草稿时先确认替换；出现结构化 `@`、`/` 引用或忙碌状态时拒绝写回。切换会话清除旧预览并取消在途操作，即便两边草稿文本相同。取消、关闭或卸载会传递 abort，迟到结果不能恢复旧预览或覆盖新操作。恢复原文只恢复本次操作前的文字，不自动恢复附件/结构化引用。

## 规则来源与限制

优化处理规则、用户选择的改写规则、待处理草稿和程序拼接的输出规则分别处理。Iris 不从草稿解析额外规则，不读取会话历史、附件、工具或工作区。JSON 包装及 system 字段用于区分指令和素材，不能证明模型永远抵御提示词注入；事实保留、规则冲突和优化质量仍需真实模型评估与预览。

输出前后缀不交给模型改写，也不自动转换为生成 API 参数。例如文字中的画幅要求不等同于图片工具的实际尺寸参数。Iris 不对任意自然语言规则做完整冲突检测。

- 草稿：沿用修剪后 32 KiB UTF-8 上限；返回原文保留空白。
- 规则：单条最多 4,000 个 UTF-16 code units；最多 12 条，正文总计 16 KiB UTF-8。
- 最终结果：最多 16,000 个 UTF-16 code units；智能优化先为输出规则与分隔符预留空间，超限或截断失败。
- 默认预算：45 秒、1,200 输出 token；元数据查询和生成共用 deadline，不自动重试或切换模型。
- 配置仍为 v1，模型路由、JSON 导入/导出、恢复默认和开关保持原有方式。`off-if-supported` 在关闭能力未知时使用供应商默认；显式 effort 和 `inherit` 的具体档位必须有元数据声明，否则在生成前拒绝。该拒绝是与 npm 0.2.0 的行为差异。

取消表示本地停止等待并向底层传递信号，不保证第三方远端执行或计费已停止。失败、工具调用、未知终态和部分正文不会作为完整结果交付。

## 预览、配置与恢复

再次优化失败或取消时，已有预览和手工编辑会保留；等待期间继续编辑，新结果不会覆盖这些改动。单片段忠实整理会显示“无需分段，未调用模型”。需要模型时，预览显示实际路由及选择原因，并可展开发送给 Model Port 的指令。

配置异常时，界面说明是否使用默认值及原文件是否保留。“仅恢复默认指令”保留模型、生成参数和入口开关；“恢复全部设置”重置完整配置。导入会替换当前配置，操作前可先导出备份。

## 开发者参考

`prompt-optimizer-core.js` 只接收显式文字、模板快照及 TextModel Port；DSH 入口负责 v1 配置、模型绑定、预览与写回。DSH 适配器聚合 `text-delta` / `block-end`、忽略思考正文、检查终态和清理源迭代器。rc.2 的缓存与未缓存输入计数相加后成为共享输入 token 数，未知 usage 字段省略。

优化和组装不创建 Core Task/Attempt/Artifact，不取得 writer 租约。纯核心可在无 DSH 的安装树中执行，当前没有独立提示词 CLI、公共 SDK export 或规则持久化格式。

现有 `POST /iris/api/prompt-optimizer/optimize` 增加可选 `mode`（`optimize` / `assemble`）与 `rules`；省略时沿用原优化行为。规则形状为 `{ id, label, kind, text, position? }`：kind 是 `optimization` 或 `output`，只有 output 设置 `prefix` / `suffix`。调用者不能伪造 source；响应由程序标记为 `user-selected`。直接 API 在 assemble 模式携带 optimization 规则会拒绝；UI 只组装只提交输出规则。

0.2.2增加可选 `editing: "faithful" | "rewrite" | "suggestions"`，仅用于 optimize。省略时保持旧文字改写协议与 `optimized` 文本响应，不破坏旧调用；新界面显式传 faithful。faithful 允许输出前后缀但不接受 optimization 规则，响应另含 `editing: { strategy, coverage: "exact", order: "preserved", groups }`。suggestions 不接受任何规则，`optimized` 逐字等于原稿，另含 `suggestions: [{ id, label, text }]`、`questions: string[]`，ID 由程序生成；内置指令要求至多三条有用建议/问题，协议上限分别为六条，label 最多 80、text/问题最多 600 字符。它们未经事实验证或采纳，不能当成用户已有要求。

配置 API 在配置对象外返回 `capabilities: { rules: true, assemble: true }`；0.2.2另声明 `targets: ["general", "image", "image-edit", "video", "s2v"]` 与 `editing: ["faithful", "rewrite", "suggestions"]`。客户端读到明确能力才启用规则、只组装、新改图目标与新编辑策略。没有 targets 声明时只启用旧四目标，没有 editing 声明时保持旧智能优化；能力字段不进入配置导出文件。

参见 [Model Port 契约](MODEL_PORT_CONTRACT.md) 与 [架构边界](ARCHITECTURE.md)。浏览器/Android 交互和真实模型质量需各自验收。

### 改写格式与路由选择

改写表达增加专用正文交付协议：返回输入 JSON 中 prompt 的实际字符串值，不复制 target/prompt 容器或序列化转义，保留原稿实际的 JSON、代码、引号、换行和反斜杠。协议追加到本次请求，不覆盖自定义 v1 配置。程序拒绝可识别的新增双字段 target/prompt 外壳、完整外层代码围栏，以及带转义的整体 JSON 字符串包装；原稿本身采用该 JSON 形状、改写规则提供对应字段样例，或素材已有围栏/JSON 字符串时允许保留。原稿内部引用 JSON 不授权给整份正文新加容器。输出前后缀仍由程序原样拼接，改写不再自动剥掉 text/markdown 围栏。忠实整理和建议继续使用各自的 JSON 协议，省略 editing 的旧入口也使用新改写交付约定。

这些是有限结构检查：原稿已有对应格式时不能自动辨别所有额外包装，也不能可靠判断普通正文中每个新增转义、标题、解释或含义变化。不会自动解包 JSON、删反斜杠或重试。结果仍需查看对照；rewrite 的输入和结果沿用首尾 trim，不承诺逐字保留首尾缩进。

需要模型的操作，选择优先级保持 **fixed 配置 → 当前会话明确选择 → 宿主默认**。null/未提供会话路由才使用默认；提供但缺字段、包含无效 ID 或无效 reasoningEffort 时明确拒绝。fixed 优先，不读取被其覆盖的会话或默认选择，也不在固定模型失败后改用另一来源。只组装和本地单片段忠实结果不使用模型路由。

调用前使用宿主精确模型元数据检查身份与文本输入能力。inputModalities 明确不包含 text 则拒绝；缺失字段或没有查询端口属于未知，不从模型名、用途或媒体池推断。查询端口存在但查询失败则返回准备阶段错误，停止生成，不能把失败当成未知继续请求。元数据查询和生成仍共用一次操作预算，只查询所选路线，没有额外生成探测。已声明接受文本输入不保证远端只输出文字，正文检查继续生效。

响应 route 另含 `reason`（选择原因）与 `textInput: "supported" | "unknown"`（宿主文本输入声明）；预览显示这两项，旧响应缺少字段时保持原显示。没有新增路由池、成本/时延排名、配置格式迁移或失败切换。

### 预览保护、忠实零调用与本次指令

再次优化保留当前预览、手工编辑及建议撤回记录；新结果成功且预览未在等待期间改变时才替换。失败、取消、关闭后的迟到结果或等待期间的继续编辑不清空或覆盖已有内容；切换会话仍清除旧预览并中止请求。重新生成依照输入框当前草稿，继续保持明确写回、不自动发送。

忠实整理若只有一个受保护的原文片段，程序原样返回并拼接输出前后缀，跳过优化配置加载、模型路由、元数据查询和生成。响应保持 `mode: "optimize"`、完整来源/顺序及单组 ID，另含 `execution: { modelInvocations: 0, reason: "single-part-faithful" }`、`route: null`、`configSource: "not-loaded"`；界面显示“忠实整理：无需分段，未调用模型”，不标为只组装。正常输入/规则/输出限额及预取消继续检查；多片段仍由模型决定连续分组。英文句号、条件、复杂引用/代码等经保守分段可能成为单片段，这表示原样保留，不表示已经改善排版。

配置 API 在配置对象外另声明 `capabilities.localFaithful: true`；界面只有收到这一明确能力才说明单片段零调用。仅有旧 faithful 能力时继续说明可能产生模型费用，避免单独更新客户端后误宣称旧服务端已经省掉调用。能力不进入 v1 配置导出。

调用模型的响应 `processing.request: { system, prompt }` 保存本次完整编译指令，包括模式协议、改写规则及素材 JSON 包装。预览的折叠区分别展示正文处理和可选建议的快照；它们表示 Iris 发送给 Model Port 的内容，不保证等于宿主/SDK/供应商最终 payload。没有模型请求时不伪造快照。旧响应缺少字段时保留原显示，不迁移配置或持久保存这些快照。

### 配置反馈与恢复范围

配置读取、导入、恢复和开关接口在配置之外返回 `feedback.warnings`；已调用的优化结果另含本次 `configFeedback`，没有加载配置的本地路径不伪造读取状态。正常默认与正常加载没有警告；读取失败、JSON 无效或校验失败会说明正在使用内置默认，并记录原文件是否隔离保留。反馈和受控日志不返回原始错误、文件内容、被忽略的字段值或私有路径。成功隔离的原文件继续保留，不自动清理。

v1 仍忽略未知字段并按内置默认补齐缺项，但现在反馈未知或当前路由未使用的字段名。例如 `modeTemplates`、`rules`、`generation.maxTokens` 并未接入，实际 token 字段是 `generation.maxOutputTokens`；session 路由中的 provider/model 不生效。反馈最多列出 32 个字段名、每名最多 256 字符，同时报告总数。导入仍替换当前完整配置，不把缺项自动合并为当前个人设置；反馈不写入导出文件或持久 v1 配置。

“仅恢复默认指令”只更新 systemPrompt 和全部 targets，保留当前可读设置中的 route、generation、enabled；“恢复全部设置”同时重置上述全部字段、生成预算和入口开关。只恢复指令需要 `capabilities.resetInstructions: true`，旧后端按钮不可用，防止旧服务端把新请求当成全部恢复。恢复操作需要界面确认；读取回退时，不能声称保留未读出的原设置，因此仅指令恢复拒绝，需先导入有效配置或明确全部恢复。

API `POST .../reset` 接受 `scope: "instructions" | "all"`，省略 scope 继续旧的全部恢复；其他 scope 返回 400 且零写入。读取失败不移动原文件；内容无效隔离失败时也不会因切换入口开关覆盖原文件。成功隔离后的入口切换继续保留本进程的回退提示，显式有效导入或全部恢复才清除；进程重载后以实际当前文件为准。