advanced-preset 1.6.0 → 1.7.0

package/dist/ap.js

@@ -7377,7 +7377,11 @@ var FORMAT_VERSION = 3;
 var TRANSPORTS = ["prefill", "plaintext", "structured", "tool-single", "tool-multi"];
 var TOOL_ARG_STREAMING = ["auto", "on", "off"];
 var BUILD_VAR_TYPES = ["string", "list", "dict"];
-var STRUCTURE_KINDS = ["reply", "memory", "recap", "impersonate", "synopsis", "options", "custom"];
+var STRUCTURE_KINDS = ["reply", "memory", "recap", "impersonate", "synopsis", "options", "custom", "annotations"];
+var INLINE_STRUCTURE_KINDS = ["annotations"];
+var isInlineStructure = (s) => INLINE_STRUCTURE_KINDS.includes(s.kind);
+var USER_INPUT_MODES = ["keep", "truncate", "remove"];
+var DEFAULT_SYNOPSIS_HISTORY_TEMPLATE = "{{content}}\n\n[{{time}} \xB7 {{location}}] {{event}}: {{summary}}";
 
 // ../protocol/src/expr.ts
 var ExprError = class extends Error {
@@ -7610,7 +7614,8 @@ var STRUCTURE_PROPERTIES = {
   memory: ["scope", "operation", "key", "content"],
   synopsis: ["time", "location", "event", "summary"],
   options: ["label", "content"],
-  custom: []
+  custom: [],
+  annotations: []
 };
 function structureFieldSchema(decl, expand = (t) => t) {
   const d = (t) => t ? expand(t).trim() || void 0 : void 0;
@@ -7659,6 +7664,8 @@ function structureFieldSchema(decl, expand = (t) => t) {
         },
         ...decl.count ? { minItems: decl.count, maxItems: decl.count } : {}
       });
+    case "annotations":
+      return withDesc({ type: "string" });
     case "custom":
       return decl.shape === "kv" ? withDesc({ type: "object", additionalProperties: { type: "string" } }) : withDesc({ type: "string" });
   }
@@ -7739,7 +7746,8 @@ function stageSchema(stage, description, tools = DEFAULT_TOOLS, expand = same) {
 function tool(name, description, parameters) {
   return { type: "function", function: { name, ...description ? { description } : {}, parameters } };
 }
-function turnArtifacts(tools, workflow, stages, structures, expand = same) {
+function turnArtifacts(tools, workflow, stages, allStructures, expand = same) {
+  const structures = allStructures.filter((s) => !isInlineStructure(s));
   const desc = (template, stage) => {
     if (!template) return void 0;
     const t = expand(stage ? fillTemplate(template, stageVars(stages, stage)) : template).trim();
@@ -8827,6 +8835,19 @@ function compile(tree) {
       decl.shape = o.shape === "kv" ? "kv" : "text";
       decl.display = o.display === "hidden" ? "hidden" : "card";
     }
+    if (kind === "annotations") {
+      if (!decl.formatPrompt.tag) decl.formatPrompt.tag = decl.formatPrompt.field;
+      if (!decl.formatPrompt.field) decl.formatPrompt.field = decl.formatPrompt.tag;
+    }
+    if (o.history !== void 0) {
+      if (kind !== "annotations" && kind !== "synopsis") diag.error("only annotations and synopsis structures support `history`", { ...where, path: `${where.path}.history` });
+      else if (typeof o.history === "number" && Number.isInteger(o.history) && o.history >= 0) decl.history = o.history;
+      else diag.error("`history` must be a non-negative integer", { ...where, path: `${where.path}.history` });
+    }
+    if (kind === "synopsis" && (o.history !== void 0 || o.historyTemplate !== void 0)) {
+      decl.historyTemplate = str2(o.historyTemplate, DEFAULT_SYNOPSIS_HISTORY_TEMPLATE);
+      if (!decl.historyTemplate.includes("{{content}}")) diag.warn("`historyTemplate` has no `{{content}}`: kept messages would lose their text", { ...where, path: `${where.path}.historyTemplate` });
+    } else if (o.historyTemplate !== void 0) diag.warn("`historyTemplate` only applies to synopsis structures and is ignored", { ...where, path: `${where.path}.historyTemplate` });
     if (o.title !== void 0) decl.title = text(str2(o.title), where);
     if (!/^[A-Za-z_][\w.-]*$/.test(decl.tag)) diag.error(`invalid tag name \`${decl.tag}\``, where);
     if (!/^[A-Za-z_]\w*$/.test(decl.field)) diag.error(`invalid field name \`${decl.field}\``, where);
@@ -8864,9 +8885,16 @@ function compile(tree) {
     if (e) meta.tasks[task] = e;
   }
   const tsSrc = isObj3(raw.tokenSaving) ? raw.tokenSaving : {};
+  const userInputMode = (v, path) => {
+    if (v === void 0) return void 0;
+    if (USER_INPUT_MODES.includes(v)) return v;
+    diag.error(`\`userInput\` must be one of ${USER_INPUT_MODES.join(", ")}`, { file: M, path });
+    return void 0;
+  };
   const tokenSaving = {
     keepFullTurns: typeof tsSrc.keepFullTurns === "number" ? tsSrc.keepFullTurns : 6,
     truncateUserAfter: typeof tsSrc.truncateUserAfter === "number" ? tsSrc.truncateUserAfter : 2e3,
+    userInput: userInputMode(tsSrc.userInput, "tokenSaving.userInput") ?? "truncate",
     synopsisTemplate: str2(tsSrc.synopsisTemplate, "[{{time}} \xB7 {{location}}] {{event}}: {{summary}}")
   };
   const syntheticTurns = (Array.isArray(raw.syntheticTurns) ? raw.syntheticTurns : []).map((s, i) => {
@@ -8977,7 +9005,7 @@ function compile(tree) {
     },
     modules: Object.fromEntries(modules.filter((m) => m.toggle === "user").map((m) => [m.id, m.default])),
     params: Object.fromEntries(params.map((p) => [p.id, p.default])),
-    tokenSaving: { enabled: false, keepFullTurns: tokenSaving.keepFullTurns, truncateUserAfter: tokenSaving.truncateUserAfter, ...sect("tokenSaving") },
+    tokenSaving: { enabled: false, keepFullTurns: tokenSaving.keepFullTurns, truncateUserAfter: tokenSaving.truncateUserAfter, userInput: tokenSaving.userInput, ...sect("tokenSaving") },
     meta: { recentCount: meta.recentCount, ...sect("meta") }
   };
   for (const k of ["names", "prefixes"]) if (isObj3(identitySrc[k])) Object.assign(configurationDefaults.identity[k], identitySrc[k]);
@@ -8989,12 +9017,14 @@ function compile(tree) {
     if (!(k in configurationDefaults.params)) diag.error(`configurationDefaults.params: unknown param \`${k}\``, { file: M, path: `configurationDefaults.params.${k}` });
     else configurationDefaults.params[k] = v;
   }
+  userInputMode(sect("tokenSaving").userInput, "configurationDefaults.tokenSaving.userInput");
   for (const k of Object.keys(cd)) if (!(k in configurationDefaults)) diag.warn(`unknown configuration section \`${k}\``, { file: M, path: `configurationDefaults.${k}` });
   const configurations = (Array.isArray(raw.configurations) ? raw.configurations : []).map((c, i) => {
     const o = isObj3(c) ? c : {};
     const rc = { id: str2(o.id), name: str2(o.name, str2(o.id)), diff: isObj3(o.diff) ? o.diff : {} };
     if (o.description !== void 0) rc.description = str2(o.description);
     if (!rc.id) diag.error("configuration id is required", { file: M, path: `configurations[${i}]` });
+    if (isObj3(rc.diff.tokenSaving)) userInputMode(rc.diff.tokenSaving.userInput, `configurations[${i}].diff.tokenSaving.userInput`);
     return rc;
   });
   if (!configurations.length) configurations.push({ id: "default", name: "Default", diff: {} });
@@ -9433,6 +9463,7 @@ function validate(p, map, diag) {
   for (const [k, ids] of byKind) if (ids.length > 1) diag.error(`only one structure of kind ${k} is allowed (${ids.join(", ")})`, { file: M, path: "structures" });
   const fields = /* @__PURE__ */ new Map();
   for (const s of Object.values(p.structures)) {
+    if (isInlineStructure(s)) continue;
     if (fields.has(s.field)) diag.error(`structures ${fields.get(s.field)} and ${s.id} share field \`${s.field}\``, { file: M, path: "structures" });
     fields.set(s.field, s.id);
   }
@@ -9446,7 +9477,7 @@ function validate(p, map, diag) {
   if (env.thinking.name === env.result.name) diag.error("envelope thinking and result fields must differ", T);
   const synthetic = new Set(p.syntheticTurns.map((t) => t.tool.name));
   if (synthetic.has(p.tools.submit.name)) diag.error(`tools.submit.name \`${p.tools.submit.name}\` is also a synthetic turn tool`, T);
-  const structureFields = new Set(Object.values(p.structures).map((s) => s.field));
+  const structureFields = new Set(Object.values(p.structures).filter((s) => !isInlineStructure(s)).map((s) => s.field));
   function checkNames(w, where) {
     const structs = Object.values(p.structures);
     const a = turnArtifacts(p.tools, w, w.stages, structs);
@@ -9665,7 +9696,7 @@ async function dev(o) {
 import { cp, mkdir as mkdir2, readdir as readdir2, readFile as readFile2, rename, stat, writeFile as writeFile2 } from "node:fs/promises";
 import { join as join2 } from "node:path";
 import { fileURLToPath } from "node:url";
-var CLI_VERSION = true ? "1.6.0" : "0.0.0-dev";
+var CLI_VERSION = true ? "1.7.0" : "0.0.0-dev";
 var TEMPLATE = fileURLToPath(new URL("../template", import.meta.url));
 async function* files(dir) {
   for (const ent of await readdir2(dir, { withFileTypes: true })) {
@@ -9761,7 +9792,7 @@ async function installSkills(target, source = SKILLS_SOURCE) {
 }
 
 // src/cli.ts
-var VERSION = true ? "1.6.0" : "0.0.0-dev";
+var VERSION = true ? "1.7.0" : "0.0.0-dev";
 var HELP = `ap ${VERSION} \u2014 Advanced Preset toolchain
 
 Usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "advanced-preset",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Advanced Preset CLI (ap) — build, check, preview and hot-reload Advanced Preset sources for SillyTavern.",
   "keywords": [
     "advanced-preset",

package/template/.agents/skills/ap-preset-authoring/references/artifact-and-runtime.md

@@ -68,6 +68,10 @@ AP 接管的每条助手消息在 `message.extra.advanced_preset` 中保存一
   "patched": "…",                 // 有补丁时：修订后的正文
   "patchesApplied": true,         // 当前显示的是否为修订稿
   "structures": { "options": [ { "label": "…", "content": "…" } ] },
+  "annotations": [                // 行内批注（有 annotations 结构时）
+    { "id": "a1", "start": 12, "end": 17, "quote": "轻轻推开门", "prefix": "…", "suffix": "…", "comment": "…" }
+  ],
+  "annotationVersions": { "draft": [ ], "patched": [ ] }, // 有补丁时：两份正文各自的批注
   "events": [ { "type": "memory.replace", "key": "…", "content": "…", "source": "model" } ],
   "metaInput": ["…"],             // 本轮输入中的元指令片段
   "reasoning": "…",               // 模型的推理内容（如果有）
@@ -77,7 +81,23 @@ AP 接管的每条助手消息在 `message.extra.advanced_preset` 中保存一
 
 - 阶段 `status`：`done`（完成）、`missing`（必需阶段没有输出）、`interrupted`（生成被中断）；
 - 消息正文 `mes` 只包含终结正文（或纯轮次的回复文字），阶段与结构不写进正文，所以切换预设或关闭 AP 后聊天记录仍然干净；
-- 用户在 UI 中切换原稿 / 修订稿时，`mes` 与 `patchesApplied` 随之改变。
+- 用户在 UI 中切换原稿 / 修订稿时，`mes`、`patchesApplied` 与 `annotations` 随之改变。
+- 用户在事件摘要卡片上编辑后，`structures` 中对应的值被直接覆盖（只改当前 swipe，`mes` 不变）。
+
+### 行内批注
+
+`annotations` 中每条批注的 `start` / `end` 是干净正文 `mes` 中的 UTF-16 偏移，`quote` 是被批注的原文，`prefix` / `suffix` 是前后各约 32 字的上下文，`comment` 是批注文字。用户编辑消息后 AP 用 `quote` 与上下文重新定位并更新偏移；找不到时标记 `"orphan": true`，保留但不显示。
+
+**显示面**：AP 在每个显示面中分别定位批注——ST 的 `.mes_text`，以及其中每个**同源** iframe（例如酒馆助手渲染的前端界面）的文档。匹配按可见文字进行（跳过隐藏元素、`script` / `style`，忽略 Markdown 强调符号、零宽字符与引号样式差异），每个显示面里一条批注至多标记一处；有多处时依次用上下文、出现序号消歧。划线使用各文档自己的 `CSS.highlights`（名为 `ap-anno`），不修改前端的 DOM；气泡统一显示在 ST 主页面。跨源 iframe 无法适配。
+
+**前端控制**：在 iframe 的 `<html>` 或 `<body>` 上设置
+
+| 属性 | 效果 |
+| --- | --- |
+| `data-ap-annotations="off"` | 不在此 iframe 中显示批注 |
+| `data-ap-annotations="manual"` | 不自动标记，前端通过 `window.parent.AdvancedPreset.annotations` 自行绘制 |
+
+**TauriTavern**：在受管 ChatSurface 模式下（`isManagedOwnershipRequired()` 为真），AP 通过清单 hook `chatSurface` 注册 participant `advanced-preset/annotations`，在 `didCommitContent` 中挂载批注并返回 disposer；其他模式使用常规 DOM 监听。
 
 ### 事件
 
@@ -106,6 +126,9 @@ AP 接管的每条助手消息在 `message.extra.advanced_preset` 中保存一
 | `listPresets()` | 可用预设：`[{ id, name, version, source }]`，`source` 为 `builtin` / `installed` / `dev` |
 | `activePresetId()` | 当前选中的 Carrier 对应的预设 id，未选中时为 `null` |
 | `update()` | 检查并应用扩展更新，返回 `'updated'` / `'current'` |
+| `togglePanel(open?)` | 打开 / 关闭 AP 面板（不传参数时切换） |
+| `annotations.get(mesId)` | 消息当前可见的行内批注（不含孤立批注），偏移对应当前 `mes` |
+| `annotations.on('change', (mesId) => …)` | 订阅批注变化（生成、编辑、切换 swipe 或补丁），返回取消订阅函数 |
 
 脚本调用 ST 生成（如 `generateRaw` / `generateQuietPrompt`）时，如果当前选中的是 Carrier，AP 同样会组装区域并接管请求，来源为 `task`；调用方的工具与 JSON Schema 的处理见 [transports.md](transports.md#调用方的工具与-schema)。
 

package/template/.agents/skills/ap-preset-authoring/references/configuration.md

@@ -38,7 +38,7 @@ configurationDefaults:
     prefixes: { narrator: "" } # 空字符串 = 使用角色的默认前缀
   modules: { options: true }   # 只能写用户可开关的模组
   params: { length: 600 }
-  tokenSaving: { enabled: false, keepFullTurns: 6, truncateUserAfter: 2000 }
+  tokenSaving: { enabled: false, keepFullTurns: 6, truncateUserAfter: 2000, userInput: truncate }
   meta: { recentCount: 3 }
 ```
 
@@ -57,7 +57,7 @@ configurationDefaults:
 | `identity` | `names.<actor>` / `prefixes.<actor>` | `''` | 覆盖角色名字 / 前缀；空字符串表示用清单 `actors` 的值 |
 | `modules` | `<module id>` | 模组的 `default` | 用户可开关模组的状态 |
 | `params` | `<param id>` | 参数的 `default` | 参数值 |
-| `tokenSaving` | `enabled` / `keepFullTurns` / `truncateUserAfter` | `false` / 清单 `tokenSaving` 的值 | 省 token（[meta-and-tasks.md](meta-and-tasks.md#省-token)） |
+| `tokenSaving` | `enabled` / `keepFullTurns` / `truncateUserAfter` / `userInput` | `false` / 清单 `tokenSaving` 的值 | 省 token（[meta-and-tasks.md](meta-and-tasks.md#省-token)） |
 | `meta` | `recentCount` | 清单 `meta.recentCount` | `{{ap::recent_meta}}` 的条数 |
 
 ### sampling

package/template/.agents/skills/ap-preset-authoring/references/manifest.md

@@ -270,16 +270,18 @@ meta:
 tokenSaving:
   keepFullTurns: 6
   truncateUserAfter: 2000
+  userInput: truncate
   synopsisTemplate: "[{{time}} · {{location}}] {{event}}: {{summary}}"
 ```
 
 | 字段 | 默认 | 说明 |
 | --- | --- | --- |
 | `keepFullTurns` | `6` | 保留最近几轮完整内容 |
-| `truncateUserAfter` | `2000` | 更早的用户消息超过这个字符数就截断并加 `…`（0 表示不截断） |
+| `truncateUserAfter` | `2000` | `userInput: truncate` 时，更早的用户消息超过这个字符数就截断并加 `…`（0 表示不截断） |
+| `userInput` | `truncate` | 更早的用户消息：`keep`（原样）/ `truncate`（截断）/ `remove`（不发送） |
 | `synopsisTemplate` | 如上 | 更早的助手消息替换成事件摘要时的格式 |
 
-是否启用由配置 `tokenSaving.enabled` 决定（默认关闭）；`keepFullTurns` / `truncateUserAfter` 也可在配置中覆盖。规则见 [meta-and-tasks.md](meta-and-tasks.md#省-token)。
+是否启用由配置 `tokenSaving.enabled` 决定（默认关闭）；`keepFullTurns` / `truncateUserAfter` / `userInput` 是配置的默认值，用户可在面板中修改。最近几条消息附带事件摘要由 `synopsis` 结构的 `history` / `historyTemplate` 声明（见 [structures.md](structures.md#synopsis)）。规则见 [meta-and-tasks.md](meta-and-tasks.md#省-token)。
 
 ## 主题 `theme`
 

package/template/.agents/skills/ap-preset-authoring/references/meta-and-tasks.md

@@ -85,7 +85,8 @@ AdvancedPreset.nextGeneration({ origin: 'story' }); // 只影响下一次生成
 
 1. **剔除纯轮次**：`turn` 为 `meta-pure` / `summary` / `impersonate` 的助手消息，连同触发它的用户消息一起不发送（当前输入除外）；
 2. **剥离元指令**：较早用户消息中的元指令片段被去掉；剥离后为空的用户消息不发送；当前输入保持原样；
-3. **省 token**（启用时，见下）。
+3. **省 token**（启用时，见下）；
+4. **附带事件摘要**：`synopsis` 结构声明了 `history: N` 且请求它的模组已开启时，最近 N 条助手消息（含已被省 token 替换的）中仍为原文的，按 `historyTemplate` 附上自己的事件摘要（见 [structures.md](structures.md#synopsis)）。
 
 ## 省 token
 
@@ -94,10 +95,10 @@ AdvancedPreset.nextGeneration({ origin: 'story' }); // 只影响下一次生成
 - 最近 `keepFullTurns` 条助手消息以及它们前面的用户消息保持完整（用户消息与其后的助手回复算同一轮）；当前输入总是保留；
 - 更早的消息中：
   - 已被总结覆盖的（真实索引 ≤ 当前总结的 `coversUpTo`）**不发送**，由模组通过 `{{ap::recap}}` 提供总结；
-  - 用户消息超过 `truncateUserAfter` 个字符时截断并加 `…`（0 表示不截断）；
+  - 用户消息按 `userInput` 处理：`keep` 原样发送；`truncate` 超过 `truncateUserAfter` 个字符时截断并加 `…`（0 表示不截断）；`remove` 不发送。扩写类写法中正文（及其事件摘要）已包含用户输入，适合 `remove`；
   - 助手消息如果有事件摘要（`synopsis` 结构），替换为 `tokenSaving.synopsisTemplate` 渲染的一行（占位符 `{{time}}` `{{location}}` `{{event}}` `{{summary}}`）；没有则保持原样。
 
-`keepFullTurns`、`truncateUserAfter` 的默认值来自清单 `tokenSaving`，可被配置覆盖。条件变量 `features.tokenSaving` 表示已开启，`recap.present` 表示有生效的总结。
+`keepFullTurns`、`truncateUserAfter`、`userInput` 的默认值来自清单 `tokenSaving`，可被配置覆盖。条件变量 `features.tokenSaving` 表示已开启，`recap.present` 表示有生效的总结。
 
 ## 脚本路径的回填
 

package/template/.agents/skills/ap-preset-authoring/references/structures.md

@@ -1,6 +1,6 @@
 # 结构
 
-**结构**是模型在正文之外交回的附加数据：叙述者的回复、记忆更新、剧情总结、代写、事件摘要、选项，以及预设自定义的块。结构的**机制**（数据形状、解析、保存、卡片 UI）由 AP 内置；预设只为它们**命名**（标签名 / 字段名）并提供**说明文字**。
+**结构**是模型在正文之外交回的附加数据：叙述者的回复、记忆更新、剧情总结、代写、事件摘要、选项、行内批注，以及预设自定义的块。结构的**机制**（数据形状、解析、保存、卡片 UI）由 AP 内置；预设只为它们**命名**（标签名 / 字段名）并提供**说明文字**。
 
 ```yaml
 structures:
@@ -27,17 +27,20 @@ structures:
 
 | 字段 | 默认 | 说明 |
 | --- | --- | --- |
-| `kind` | 结构 id | 种类：`reply` `memory` `recap` `impersonate` `synopsis` `options` `custom`。其他值报错 |
+| `kind` | 结构 id | 种类：`reply` `memory` `recap` `impersonate` `synopsis` `options` `annotations` `custom`。其他值报错 |
 | `tag` | 结构 id | 对话式写法中的 XML 标签名，须匹配 `^[A-Za-z_][\w.-]*$` |
 | `field` | 结构 id | 指令式写法中的 JSON 字段名 / 工具参数名，须匹配 `^[A-Za-z_]\w*$` |
 | `description` | — | 字段整体的说明，进入 JSON Schema 的 `description`（模型可见，支持宏） |
 | `properties` | — | 子字段说明，键只能是该种类的固定子字段（见下表），其他键报错 |
 | `count` | — | 仅 `options`：要求的选项数，写入 schema 的 `minItems` / `maxItems` |
+| `history` | `0` | 仅 `synopsis`：最近几条原样发送的助手消息附带自己的事件摘要（0 表示不附带），见下 |
+| `historyTemplate` | `{{content}}` + 空行 + `[{{time}} · {{location}}] {{event}}: {{summary}}` | 仅 `synopsis`：附带摘要的消息的格式 |
 | `title` | 结构 id | 卡片标题（自定义结构用；`reply` 等也可以设，如花瓣的回复卡片显示叙述者名字）。可在 `locales` 中翻译 |
 | `formatPrompt.tag` | `''` | 对话式下的格式说明，由 `{{ap::structure::<id>}}` 输出 |
 | `formatPrompt.field` | `''` | 指令式下的格式说明，由 `{{ap::structure::<id>}}` 输出 |
 | `shape` | `text` | 仅 `custom`：`text`（一段文字）或 `kv`（键值对） |
 | `display` | `card` | 仅 `custom`：`card`（消息下方显示可折叠卡片）或 `hidden`（只保存，不显示） |
+| `history` | `0` | 仅 `annotations`：把批注以 CriticMarkup 重新注入最近 N 条助手消息的历史（见 [annotations](#annotations)） |
 
 约束（报错）：
 
@@ -54,10 +57,13 @@ structures:
 | `impersonate` | `string` | — | 是 | 代写的用户下一条输入，卡片可“填入输入框” |
 | `synopsis` | `{ time, location, event, summary }` | `time` `location` `event` `summary` | 是 | 本段的事件摘要卡片；省 token 时替代旧回复 |
 | `options` | `{ label, content }[]` | `label` `content` | 是 | 选项卡片，点击填入输入框 |
+| `annotations` | 正文内标记 → `Annotation[]` | — | — | **行内**结构：写在正文里，解析后从正文移除，显示为虚线下划线与气泡 |
 | `custom` | `string` 或 `Record<string, string>` | — | 是 | 预设自定义的块（状态栏等） |
 
 “必填”指生成的 JSON Schema 中该字段是否进入 `required`。`memory` 与 `recap` 是可选的：模型可以不写。
 
+`annotations` 是唯一的**行内结构**：它不是 schema 字段，也没有标签，两种写法下都由模型直接写在正文里（`tag` / `field` / `description` / `properties` 不使用）。
+
 ## 何时请求结构
 
 结构**不会自动出现**。只有当某个**当前生效的模组**在 frontmatter 中列出它时，这一轮才会请求它：
@@ -74,6 +80,7 @@ structures: [options]
 
 - 指令式：作为字段加入回合 schema（结构化、单工具），或作为锚点阶段工具的附加参数（多工具），位置见 [workflows.md](workflows.md#结构的位置)；
 - 对话式：AP 从模型输出中提取对应标签；
+- 行内结构（`annotations`）：两种写法相同，AP 从正文中解析标记；
 
 由脚本或其他扩展发起的任务生成（`gen.type == "script"` 且 `gen.origin == "task"`）不请求任何结构，即使模组列出了它们。
 
@@ -157,7 +164,28 @@ SillyTavern 的“代写”按钮会发送清单中的 `meta.impersonatePrompt`
 
 ### synopsis
 
-显示为事件摘要卡片。启用省 token 时，较早的助手消息会被 `tokenSaving.synopsisTemplate` 渲染的摘要替代（见 [meta-and-tasks.md](meta-and-tasks.md#省-token)）。
+显示为事件摘要卡片，用户可在卡片上编辑四个字段，保存后直接覆盖该楼层（当前 swipe）Sidecar 中的结构值，不改正文 `mes`，也不保留原值。事件摘要在历史中有两种用法，模板都由预设指定，都读取编辑后的值：
+
+- **替换**：启用省 token 时，较早的助手消息被 `tokenSaving.synopsisTemplate` 渲染的摘要替代（见 [meta-and-tasks.md](meta-and-tasks.md#省-token)）；
+- **附带**：`history: N` 时，最近 N 条助手消息保留原文，并按 `historyTemplate` 附上自己的摘要（与是否启用省 token 无关）。占位符 `{{content}}`（消息原文）与 `{{time}}` `{{location}}` `{{event}}` `{{summary}}`。
+
+故事中没有明确时间时，模型往往只能从先前的事件摘要推断时间；附带最近几条摘要可以避免时间线混乱。只有请求了该结构的模组开启时才附带；已被省 token 替换的消息也计入 N。
+
+```yaml
+structures:
+  synopsis:
+    kind: synopsis
+    history: 3
+    historyTemplate: |-
+      {{content}}
+
+      <synopsis>
+        <time>{{time}}</time>
+        <location>{{location}}</location>
+        <event>{{event}}</event>
+        <summary>{{summary}}</summary>
+      </synopsis>
+```
 
 ### options
 
@@ -185,6 +213,49 @@ structures:
 Previous status: {{ap::structure::status::last}}
 ```
 
+### annotations
+
+行内批注：模型在正文中用 CriticMarkup 的子集标出一段文字并附上批注：
+
+```text
+她{==轻轻推开门==}{>>这里的“轻轻”呼应上一幕的犹豫。<<}，走了进去。
+```
+
+```yaml
+structures:
+  annotations:
+    kind: annotations
+    history: 0
+    formatPrompt:
+      tag: |-
+        Inline annotations are written inside the story text as `{==phrase==}{>>note<<}`.
+        Mark a short phrase or a single sentence, never across paragraphs, and never nest marks.
+```
+
+`formatPrompt` 只需写 `tag` 或 `field` 之一，另一个自动取相同文字（行内写法与输出方式无关）。建议这里只写语法，批注的用途、口吻与数量写在请求它的模组里，这样不同模组（如作者评论、术语注释）可以复用同一份语法说明。
+
+**语法**（严格成对）：
+
+| 写法 | 结果 |
+| --- | --- |
+| `{==原文==}{>>批注<<}` | 一条批注；正文保留“原文” |
+| 单独的 `{==原文==}` | 去掉标记，保留“原文” |
+| 单独的 `{>>批注<<}` | 整段移除 |
+| 未闭合的 `{==` | 丢弃标记，保留其后文字 |
+| 未闭合的 `{>>` | 按原文保留 |
+
+标记不能跨段落（空行），也不能嵌套。被批注的“原文”应是短语或句子。
+
+**保存**：消息的 `mes` 始终是**去掉标记后的干净正文**；批注单独存于 sidecar 的 `annotations`（见 [artifact-and-runtime.md](artifact-and-runtime.md#行内批注)）。每条批注用偏移 + 原文 + 前后各约 32 字的上下文锚定；用户编辑正文后 AP 重新定位，找不到的批注成为**孤立批注**——保留但不显示，可在调试页查看。工作流的补丁作用于带标记的文本，因此补丁前后各有一份批注，随“显示 / 撤销补丁”切换。
+
+**流式**：生成过程中 AP 只把已确定的部分交给 ST，标记不会闪现；下划线在生成结束后出现。
+
+**历史**：默认（`history: 0`）历史中只有干净正文。`history: N` 时，最近 N 条助手消息（未被用户改动过的）在组装时把批注以 CriticMarkup 重新注入，帮助模型保持批注风格；代价是更多 token。
+
+**显示**：被批注的文字显示虚线下划线（CSS Custom Highlight API，不改动消息 DOM；不支持时退化为 `<ap-anno>` 包裹），悬停或轻点弹出气泡，署名为叙述者。同源 iframe 前端（如酒馆助手渲染的界面）自动适配，详见 [artifact-and-runtime.md](artifact-and-runtime.md#行内批注)。用户可在外观设置中关闭显示或更改下划线颜色。
+
+请求方式与其他结构相同：由生效模组的 `structures: [annotations]` 请求，并在正文里放 `{{ap::structure::annotations}}` 输出格式说明。
+
 ### 保存条件
 
-记忆与总结只在**拦截器参与的生成**中保存，且生成类型不是 `quiet`（后台生成）。所有结构值都写在消息的 `extra.advanced_preset.structures` 中（见 [artifact-and-runtime.md](artifact-and-runtime.md)）。
+记忆与总结只在**拦截器参与的生成**中保存，且生成类型不是 `quiet`（后台生成）。所有结构值都写在消息的 `extra.advanced_preset.structures` 中，行内批注除外（`extra.advanced_preset.annotations`，见 [artifact-and-runtime.md](artifact-and-runtime.md)）。

package/template/.github/workflows/build.yml

@@ -4,6 +4,8 @@ on:
     branches: [main]
     tags: ['v*']
   pull_request:
+permissions:
+  contents: write   # create the GitHub Release on v* tags
 jobs:
   build:
     runs-on: ubuntu-latest