dsh-plugin-guide 0.3.15 → 0.3.17

package/references/official-docs/docs/persistence-changes/2026-09-14-image-offload.zh.md

@@ -0,0 +1,96 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-09-14-image-offload
+
+[English](2026-09-14-image-offload.md) | 中文
+
+## 概述
+
+用 image/offload 事件记录选中的图片出现位置，通过所属插件的消息投影派生 offloaded 标记。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-14-image-offload
+baseline: false
+changes:
+  - root: "event:agent/inbox/spliced"
+    previous: "2026-09-11-initial"
+    after: "646c2f1d243d3a78c5bc9305786fb340f5209c48a97e65f2a186cc5195491f3f"
+    decision: same-version
+  - root: "event:assistant/attempt"
+    previous: "2026-09-11-initial"
+    after: "c80c89da83c46db7a454f034c10f969e03cfb574859c7316e5bff683f5a14b0e"
+    decision: same-version
+  - root: "event:assistant/message"
+    previous: "2026-09-11-initial"
+    after: "1169b301aaabcd992657b93ec93750c43175dda81ada5cac086f14f2eaaeed6d"
+    decision: same-version
+  - root: "event:compaction/summary"
+    previous: "2026-09-11-initial"
+    after: "f6f3f30109e9008fccf7da2a3268a63da8646b59dd7cf7b75bcd9cf08ac08a59"
+    decision: same-version
+  - root: "event:image/offload"
+    previous: null
+    after: "b222069eea2d768065161c1147b1f2c78c1b54328c84b3586ae5c8f91b8ed35e"
+    decision: same-version
+  - root: "event:llm/retry"
+    previous: "2026-09-11-initial"
+    after: "525254db03b1d1e6b74cf55aced52817568331ac1f96c0818728910b6692e336"
+    decision: same-version
+  - root: "event:session/title-llm-request"
+    previous: "2026-09-11-initial"
+    after: "e0b5bf44c27bbfc6ab144239e3e4169c4d21146645e0e3121bbb359c3bc8591d"
+    decision: same-version
+  - root: "event:system/message"
+    previous: "2026-09-11-initial"
+    after: "69becfb6b2d3fd5da91518089454cae8ef33f1835637ec44dde35dd077fd4bae"
+    decision: same-version
+  - root: "event:team/message/queued"
+    previous: "2026-09-11-initial"
+    after: "443371ec07a03a82a0e93d93abca3e70b03bca55ba5b01d507030fcb66e8fbb4"
+    decision: same-version
+  - root: "event:tool/ptc-dispatch"
+    previous: "2026-09-12-auto-review-error-metadata"
+    after: "b33142af8176323ffbb20762541be81c1d51b60a60887803836e0b146e5bef0c"
+    decision: same-version
+  - root: "event:tool/result"
+    previous: "2026-09-12-auto-review-error-metadata"
+    after: "29af48b840d0cd9e48b6f50bf3b354f8f6340607c5b99220a48e74f60beac9e2"
+    decision: same-version
+  - root: "event:turn/end"
+    previous: "2026-09-11-initial"
+    after: "bab768260853e13a7cf2e22e65af572a1e76a5b2c01f3cdc2ce09d39b87fb70b"
+    decision: same-version
+  - root: "event:user/message"
+    previous: "2026-09-11-initial"
+    after: "314765bdff29c7862fb6ce820f1773563ba3094a680d163ea21180a2591b8578"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+现有日志仍可读取。可选的图片字段 offloaded 使未标记的出现位置保持保留状态。新事件在读取时必须被识别：不认识 image/offload 的旧版本拒绝读取这些日志，当前读取器需要对应的消息投影。事件信封和结构性的 Session 格式版本不变。
+
+<a id="verification"></a>
+## 验证
+
+Session 和图片省略测试覆盖事件校验、不可变消息投影、缺少处理器、恢复和重试。所选的 1,144 项测试和两项 TypeScript 图片快照通过。Python advanced SDK 录制已通过构建后的 dsh profile 刷新，包含独立的 image/offload 事件。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/references/official-docs/docs/persistence-changes/2026-09-14-workspace-changes-event.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/persistence-changes/2026-09-14-workspace-changes-event.md
+2026-09-14-workspace-changes-event.md: 5d8a4ff6526dc67444d5dce0076b005d96b3b059
+2026-09-14-workspace-changes-event.zh.md: fa2d037dc50dae2bfb7ba4b3801558559b73fd7c

package/references/official-docs/docs/persistence-changes/2026-09-14-workspace-changes-event.md

@@ -0,0 +1,48 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-09-14-workspace-changes-event
+
+English | [中文](2026-09-14-workspace-changes-event.zh.md)
+
+## Summary
+
+Adds the log-only workspace/changes event that records the files a top-level turn changed.
+
+## Table of Contents
+
+- [Declaration](#declaration)
+- [Compatibility](#compatibility)
+- [Verification](#verification)
+- [Dev Note](#dev-note)
+
+<a id="declaration"></a>
+## Declaration
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-14-workspace-changes-event
+baseline: false
+changes:
+  - root: "event:workspace/changes"
+    previous: null
+    after: "e308ccf867a5398e316e0af8cb6ce238a8d33a63b9b384c8250a686786285f72"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## Compatibility
+
+A new root in the same Session format version. Existing logs contain no such event and stay valid; readers that predate it refuse a log carrying it, as every required-on-read event does. The event is appended only by the Web bundle's workspace-changes plugin and is never model-visible; the Web changed-files card is its only consumer and reads the latest event per turn.
+
+<a id="verification"></a>
+## Verification
+
+pnpm exec vitest run packages/deliverables/workspace-changes packages/client/ui-deliverables: 165 tests passed; snapshots/web/changed-files-turn replays the recorded event through the Web profile.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/references/official-docs/docs/persistence-changes/2026-09-14-workspace-changes-event.schema.json

@@ -0,0 +1,72 @@
+{
+  "formatVersion": 1,
+  "roots": [
+    {
+      "key": "event:workspace/changes",
+      "kind": "event",
+      "event": "workspace/changes",
+      "surface": false,
+      "digest": "e308ccf867a5398e316e0af8cb6ce238a8d33a63b9b384c8250a686786285f72",
+      "schema": {
+        "root": 0,
+        "nodes": [
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "data",
+                "type": 1,
+                "optional": false
+              },
+              {
+                "name": "ignorable",
+                "type": 3,
+                "optional": true
+              },
+              {
+                "name": "seq",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "time",
+                "type": 2,
+                "optional": false
+              },
+              {
+                "name": "type",
+                "type": 4,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "object",
+            "properties": [
+              {
+                "name": "turn",
+                "type": 2,
+                "optional": false
+              }
+            ],
+            "indices": []
+          },
+          {
+            "kind": "primitive",
+            "type": "number"
+          },
+          {
+            "kind": "literal",
+            "value": true
+          },
+          {
+            "kind": "literal",
+            "value": "workspace/changes"
+          }
+        ]
+      }
+    }
+  ],
+  "types": []
+}

package/references/official-docs/docs/persistence-changes/2026-09-14-workspace-changes-event.zh.md

@@ -0,0 +1,48 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-09-14-workspace-changes-event
+
+[English](2026-09-14-workspace-changes-event.md) | 中文
+
+## 概述
+
+新增仅写日志的 workspace/changes 事件，记录顶层轮次改动的文件。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-14-workspace-changes-event
+baseline: false
+changes:
+  - root: "event:workspace/changes"
+    previous: null
+    after: "e308ccf867a5398e316e0af8cb6ce238a8d33a63b9b384c8250a686786285f72"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+同一 Session 格式版本内的新根类型。已有日志没有该事件，保持有效；早于它的读取方遇到它会拒绝该日志，与所有读取时必需的事件一致。该事件只由 Web bundle 的 workspace-changes 插件追加，模型永远看不到；Web 的改动文件卡片是唯一消费者，读取每轮最新的一条。
+
+<a id="verification"></a>
+## 验证
+
+pnpm exec vitest run packages/deliverables/workspace-changes packages/client/ui-deliverables：165 个测试通过；snapshots/web/changed-files-turn 通过 Web profile 回放了记录的事件。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/references/official-docs/docs/persistence-changes/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/persistence-changes/README.md
+README.md: 7eb46efe69e139c294ad76e1b584e2d7384151b5
+README.zh.md: d91cfff9e5010bfff92b905ce0f075e7e419eb52

package/references/official-docs/docs/persistence-changes/README.md

@@ -0,0 +1,74 @@
+---
+description: "Review and maintain recorded Session persistence-type changes, their schema snapshots, and compatibility decisions."
+---
+
+# Persistence-type change records
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use this reference to inspect an acknowledged Session persistence-type change and its predecessor. Each record binds a compatibility decision to exact generated schemas. Local checks compare the current source with the recorded history using only files in the checkout. Start with the [review cookbook](../cookbook/reviewing-persistence-type-changes.md) when changing a persisted type.
+
+For older tagged versions, use the [prerelease archive](releases/README.md). It reconstructs alpha/RC type differences for historical reading and format validation; its observations do not serve as current compatibility acknowledgements.
+
+For complete schemas grouped by Session format, use the [format references](historical-formats/README.md). Their coverage follows the writer constant, including intermediate formats without a release tag.
+
+## Table of Contents
+
+- [Files and ownership](#files-and-ownership)
+- [Compatibility rules](#compatibility-rules)
+- [History and limitations](#history-and-limitations)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="files-and-ownership"></a>
+## Files and ownership
+
+The generated [catalog](../persistence-catalog.md) provides readable declarations and digests; the [schema inventory](../persistence-schema.json) contains the normalized types. Roots cover the logical Session header, the physical JSONL header line, the event envelope, and every repository-declared event. Referenced types contribute transitively to each affected root's digest.
+
+Each dated record has four sibling files:
+
+| File | Owner |
+|---|---|
+| `YYYY-MM-DD-slug.md` | English acknowledgement with `kind: persistence-change`, one machine declaration, compatibility reasoning, and verification evidence |
+| `YYYY-MM-DD-slug.zh.md` | Chinese counterpart with the identical machine declaration |
+| `YYYY-MM-DD-slug.i18n.yaml` | Generated bilingual consistency record |
+| `YYYY-MM-DD-slug.schema.json` | Generated complete after schemas for the affected roots that remain present |
+
+The [record template](../../.agents/skills/dsh-doc/templates/persistence-change.md) defines the authored format. Record creation accepts a bilingual prose input and generates the machine declaration, snapshots, catalog pair, and consistency records. The verifier reads the machine declaration once from the English file and checks the Chinese declaration for equality. A declaration names each affected root, its predecessor record, its after digest, and its compatibility decision. A new root has no predecessor; a deletion has no after schema and retains an explicit tombstone.
+
+<a id="compatibility-rules"></a>
+## Compatibility rules
+
+Every detected structural change requires an acknowledgement. Record creation and update infer the minimum decision from these fixed rules; an explicit `--decision` is a checked assertion. The rules apply to the complete change, so an allowed change cannot hide a simultaneous breaking change.
+
+| Detected change | Minimum decision |
+|---|---|
+| Add an optional event-body property, including its complete subtree | `same-version` |
+| Make a required event-body property optional | `same-version` |
+| Add an ordinary event type | `same-version` |
+| Make an optional property required, add a required property, change an existing type, or remove/rename a property or event | `version-bump` |
+| Change the Session header or event envelope | `version-bump` |
+
+A same-version explanation states why old records can omit the addition and why older readers can ignore it without changing replay. For required-to-optional changes, it explains how readers handle an absent value. The checker validates the type classification; reviewers assess the explanation. A version-bump record includes the increasing header version in the same transition and follows the [Session-format procedure](../cookbook/adding-a-session-format-version.md).
+
+<a id="history-and-limitations"></a>
+## History and limitations
+
+One baseline records the complete initial inventory. Later records use their predecessor's after schema as the before schema. The verifier rejects missing predecessors, cycles, duplicate successors for one root, digest mismatches, and current roots that disagree with their latest records. Independent roots can advance independently. Two changes to the same predecessor require a single ordered history after integration.
+
+Accepted records describe historical transitions; preserve their machine declarations and schema snapshots when adding a successor. An unaccepted terminal record can be refreshed explicitly; the command rejects baselines and records with dependants. The tree cannot establish review acceptance. Verification proves consistency within the tree, not that history was never rewritten. No Git ref, remote service, or released checkout supplies the baseline.
+
+Digests describe declared persistence types, not runtime validation or behavior. Comments, source locations, alias names, and harmless declaration reordering do not affect them. Object fields, union alternatives, intersection operands, and index signatures can be reordered when their resolved types stay the same; tuple positions and numeric enum values remain significant. Catalog text and source locations may still change, so regenerate stale artifacts without adding an acknowledgement for an unchanged digest. Opaque types such as `unknown` expose no hidden structure to compare. Behavior-only changes and structures hidden inside opaque values are outside this mechanism's scope. The [decision](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.md) records these trade-offs.
+
+<a id="dev-note"></a>
+## Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/references/official-docs/docs/persistence-changes/README.zh.md

@@ -0,0 +1,74 @@
+---
+description: "审阅和维护已记录的会话持久化类型变更、对应 schema 快照以及兼容性决策。"
+---
+
+# 持久化类型变更记录
+
+[English](README.md) | 中文
+
+## 概述
+
+本参考文档用于检查已确认的会话持久化类型变更及其前驱。每条记录把兼容性决策绑定到精确的生成 schema。本地检查仅使用当前检出目录中的文件，将当前源码与记录历史比较。修改持久化类型时，从[审阅实操手册](../cookbook/reviewing-persistence-type-changes.zh.md)开始。
+
+较早的 tag 参见[预发行版本归档](releases/README.zh.md)。它重建 alpha/RC 类型差异，供历史阅读和格式校验使用；这些观察记录不作为当前兼容性确认。
+
+按 Session 格式查看完整 schema 时，使用[格式参考](historical-formats/README.zh.md)。其覆盖范围由写入器常量决定，包括没有发布 tag 的中间格式。
+
+## 目录
+
+- [文件与职责](#files-and-ownership)
+- [兼容性规则](#compatibility-rules)
+- [历史与限制](#history-and-limitations)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="files-and-ownership"></a>
+## 文件与职责
+
+生成的[目录](../persistence-catalog.zh.md)提供可读声明和摘要；[schema 清单](../persistence-schema.json)包含规范化类型。根覆盖逻辑会话头、物理 JSONL 头行、事件封装以及每个仓库内声明的事件。被引用类型的变更会传递到每个受影响根的摘要。
+
+每条带日期的记录有四个同目录文件：
+
+| 文件 | 职责 |
+|---|---|
+| `YYYY-MM-DD-slug.md` | 英文确认文档，包含 `kind: persistence-change`、一份机器声明、兼容性说明和验证证据 |
+| `YYYY-MM-DD-slug.zh.md` | 中文对侧文件，包含相同的机器声明 |
+| `YYYY-MM-DD-slug.i18n.yaml` | 生成的双语一致性记录 |
+| `YYYY-MM-DD-slug.schema.json` | 生成的完整变更后 schema，覆盖受影响且仍然存在的根 |
+
+[记录模板](../../.agents/skills/dsh-doc/templates/persistence-change.md)定义人工编写的格式。创建记录时可以提供双语说明输入，由命令生成机器声明、快照、目录对和一致性记录。验证器从英文文件读取一次机器声明，并检查中文声明是否相同。声明列出每个受影响的根、其前驱记录、变更后摘要和兼容性决策。新根没有前驱；删除操作没有变更后 schema，并保留显式删除标记。
+
+<a id="compatibility-rules"></a>
+## 兼容性规则
+
+每个检测到的结构变更都需要确认。创建和更新记录依据这些固定规则推断最低决策；显式 `--decision` 是受检查的断言。规则应用于整个变更，因此允许的变更不能掩盖同时发生的破坏性变更。
+
+| 检测到的变更 | 最低决策要求 |
+|---|---|
+| 添加可选事件体属性，包括其完整子树 | `same-version` |
+| 将必选事件体属性改为可选 | `same-version` |
+| 添加普通事件类型 | `same-version` |
+| 将可选属性改为必选、添加必选属性、更改已有类型，或删除／重命名属性或事件 | `version-bump` |
+| 更改会话头或事件封装 | `version-bump` |
+
+同版本说明须解释旧记录为何可以缺少新增内容，以及旧读取器为何可以忽略它而不改变回放。对于必选改可选的变更，说明须解释读取器如何处理缺失值。检查器验证类型分类；审阅者判断说明是否成立。升版本记录在同一转换中包含递增的头部版本，并遵循[会话格式流程](../cookbook/adding-a-session-format-version.zh.md)。
+
+<a id="history-and-limitations"></a>
+## 历史与限制
+
+一条基线记录完整的初始清单。后续记录使用前驱的变更后 schema 作为变更前 schema。验证器拒绝缺失前驱、环、同一根的重复后继、摘要不匹配，以及当前根与最新记录不一致的情况。独立的根可以独立演进。同一前驱上的两个变更在集成后需要形成一条有序历史。
+
+已接受记录描述历史转换；添加后继时须保留其机器声明和 schema 快照。尚未接受的末端记录可以显式刷新；命令拒绝基线及被依赖的记录。目录本身无法证明审阅接受状态。验证证明目录内的一致性，不证明历史从未被改写。基线不依赖 Git 引用、远端服务或已发布版本的检出目录。
+
+摘要描述声明的持久化类型，不描述运行时验证或行为。注释、源码位置、别名名称和无语义变化的声明重排不影响摘要。对象字段、联合类型分支、交叉类型操作数和索引签名可以在解析类型不变时重排；元组位置和数字枚举值仍然影响摘要。目录文本和源码位置仍可能变化，因此应重新生成陈旧产物，无需为未变的摘要添加确认记录。`unknown` 等不透明类型不提供可比较的内部结构。纯行为变更以及不透明值中隐藏的结构不在本机制范围内。[决策记录](../../.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md)说明这些取舍。
+
+<a id="dev-note"></a>
+## 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/references/official-docs/docs/persistence-changes/historical-formats/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/persistence-changes/historical-formats/README.md
+README.md: fda6ac3b4fc3e52ef215dc0a2fca00576cd4ef0c
+README.zh.md: 792f47e532d6ebfdbb745c1bc2703c7b5f4fcc17

package/references/official-docs/docs/persistence-changes/historical-formats/README.md

@@ -0,0 +1,74 @@
+---
+description: "Find the complete declared persistence types for every Session format from V0 through the checkout writer."
+---
+
+# Session persistence formats
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use this reference to inspect a stored Session generation’s headers, event envelopes, and payload types. Every format below the checkout writer has a bilingual document and a complete schema snapshot. The current format uses the generated persistence catalog. The [version authority](../../session-format-status.md) owns the writer constant and release status.
+
+## Table of Contents
+
+- [Format references](#formats)
+- [Scope and evidence](#scope)
+- [Maintain coverage](#maintenance)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="formats"></a>
+## Format references
+
+The index is generated from validated snapshots and the current writer constant. Each historical reference identifies its source checkpoint; a Session format number does not identify every event payload revision within that format.
+
+<!-- persistence-format-index:start -->
+
+| Format | Source | Reference | Machine schema | Roots / types |
+|---|---|---|---|---|
+| 0 | `dsh-v0.1.2-rc.1` | [V0](v0.md) | [JSON](v0.schema.json) | 54 / 415 |
+| 1 | PR #3349 | [V1](v1.md) | [JSON](v1.schema.json) | 54 / 415 |
+| 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.md) | [JSON](v2.schema.json) | 56 / 435 |
+| 3 | Current checkout | [Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json) | 61 / 470 |
+
+<!-- persistence-format-index:end -->
+
+<a id="scope"></a>
+## Scope and evidence
+
+Each `vN.md` / `vN.zh.md` pair has `kind: persistence-format`, an identical `yaml persistence-format` declaration binding every root key to its captured digest, a pairing sidecar, and a complete `vN.schema.json`. The [template](../../../.agents/skills/dsh-doc/templates/persistence-format.md) defines these records. Roots cover the logical Session header, physical JSONL header, event envelope, and all first-party events at the selected checkpoint; each root includes every reachable declared type. Packed physical body records have separate codec owners linked from each page.
+
+V0 and V2 use the latest matching tags in the [captured prerelease archive](../releases/README.md). V1 uses an intermediate source tree identified in its reference because the captured tags contain no V1 writer. Historical sources retain file paths without line numbers. Snapshots preserve historical optional fields and opaque values; they do not substitute current types into older formats. Historical identifiers remain intact only in schema JSON and the verified generated schema regions; authored prose follows current terminology rules.
+
+These references describe selected schemas, not historical application replay or migration safety. Same-version event additions and optional payload changes can produce other valid inventories. The prerelease archive retains tag-by-tag differences; [change records](../README.md) retain current compatibility acknowledgements. Neither history is replaced by these format snapshots.
+
+<a id="maintenance"></a>
+## Maintain coverage
+
+`verify-persistence-formats` derives the required integer range from `SESSION_FORMAT_VERSION`. Every older integer needs its own complete record. The current catalog and schema must exist and match the writer version. The check rejects missing, extra, misnumbered, incomplete, or inconsistent records and stale generated regions without fetching Git history or querying a service.
+
+Before advancing the writer, verify the current catalog and archive the outgoing format. For a V3-to-V4 change, run these commands while the writer and current schema still describe V3:
+
+```sh
+pnpm run verify-persistence-catalog
+pnpm run verify-persistence-formats --archive 3
+```
+
+Replace `3` with the outgoing writer version for other transitions. `--archive N` creates `vN.schema.json` from the current inventory, retains exactly the types reachable from its roots, and removes source line numbers. It refuses an existing destination, a version other than the current writer, invalid or incomplete schemas, and combination with `--write`. Add the snapshot’s bilingual record and source evidence using the [template](../../../.agents/skills/dsh-doc/templates/persistence-format.md). Retain all earlier records. The successor uses the current catalog; copying a new current catalog cannot satisfy the archived predecessor requirement. Follow the [format-version cookbook](../../cookbook/adding-a-session-format-version.md) for runtime changes.
+
+The schema definitions and index inside comment markers are generated. After advancing the writer and completing the machine data and authored evidence, refresh their tables and pairing records, then verify:
+
+```sh
+pnpm run verify-persistence-formats --write
+pnpm run verify-persistence-formats
+pnpm run doc-sync
+```
+
+`--write` validates the machine data before updating generated Markdown and pairing records. It preserves authored explanations, machine declarations, and schemas. Default verification also rejects stale pairing records; the standard documentation checks validate translations and local links. Current catalog freshness remains owned by `verify-persistence-catalog`.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/references/official-docs/docs/persistence-changes/historical-formats/README.zh.md

@@ -0,0 +1,74 @@
+---
+description: "查找从 V0 到工作区写入器版本的每个 Session 格式的完整持久化类型声明。"
+---
+
+# Session 持久化格式
+
+[English](README.md) | 中文
+
+## 概述
+
+本参考用于查阅已存储 Session 代际的 header、事件信封与载荷类型。低于工作区写入器版本的每个格式都有双语文档与完整 schema 快照。当前格式使用生成的持久化目录。[版本真源](../../session-format-status.zh.md)负责写入器常量与发布状态。
+
+## 目录
+
+- [格式参考](#formats)
+- [范围与证据](#scope)
+- [维护覆盖](#maintenance)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="formats"></a>
+## 格式参考
+
+索引由已验证的快照与当前写入器常量生成。每个历史参考标明其来源检查点；Session 格式编号不能标识该格式内的每次事件载荷修订。
+
+<!-- persistence-format-index:start -->
+
+| 格式 | 来源 | 参考文档 | 机器 schema | 根类型 / 类型 |
+|---|---|---|---|---|
+| 0 | `dsh-v0.1.2-rc.1` | [V0](v0.zh.md) | [JSON](v0.schema.json) | 54 / 415 |
+| 1 | PR #3349 | [V1](v1.zh.md) | [JSON](v1.schema.json) | 54 / 415 |
+| 2 | `dsh-v0.1.3-alpha.2` | [V2](v2.zh.md) | [JSON](v2.schema.json) | 56 / 435 |
+| 3 | 当前工作树 | [当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json) | 61 / 470 |
+
+<!-- persistence-format-index:end -->
+
+<a id="scope"></a>
+## 范围与证据
+
+每组 `vN.md` / `vN.zh.md` 文档包含 `kind: persistence-format`、将每个根类型键绑定到已记录摘要的相同 `yaml persistence-format` 声明、配对记录及完整的 `vN.schema.json`。[模板](../../../.agents/skills/dsh-doc/templates/persistence-format.md)定义这些记录。根类型覆盖所选检查点的逻辑 Session header、物理 JSONL header、事件信封与所有第一方事件；每个根包含所有可达的声明类型。打包的物理 body 记录由每页链接的独立 codec 负责。
+
+V0 与 V2 使用[已收录预发布归档](../releases/README.zh.md)中最后一个对应 tag。由于收录的 tag 没有 V1 写入器，V1 使用其参考文档中标识的中间源码树。历史来源保留文件路径，不包含行号。快照保留历史可选字段与不透明值，不会将当前类型替换到旧格式中。历史标识符仅在 schema JSON 与已验证的生成 schema 区间中原样保留；人工说明遵循当前术语规则。
+
+这些参考描述选定的 schema，不表示历史应用回放结果或迁移安全性。同版本内新增事件与可选载荷变更可以产生其他有效目录。预发布归档保留逐 tag 差异；[变更记录](../README.zh.md)保留当前兼容性确认。这些格式快照不替代任何一种历史。
+
+<a id="maintenance"></a>
+## 维护覆盖
+
+`verify-persistence-formats` 从 `SESSION_FORMAT_VERSION` 推导所需的整数范围。每个更早的整数都需要独立的完整记录。当前目录与 schema 必须存在且匹配写入器版本。检查会拒绝缺失、多余、编号错误、不完整或不一致的记录及过期生成区间，无需获取 Git 历史或查询服务。
+
+推进写入器之前，验证当前目录并归档原格式。对于 V3 到 V4 的变更，在写入器与当前 schema 仍描述 V3 时运行以下命令：
+
+```sh
+pnpm run verify-persistence-catalog
+pnpm run verify-persistence-formats --archive 3
+```
+
+对于其他转换，将 `3` 替换为原写入器版本。`--archive N` 从当前目录创建 `vN.schema.json`，只保留从根类型可达的类型，并移除源码行号。它拒绝已存在的目标、与当前写入器不同的版本、无效或不完整的 schema，以及与 `--write` 的组合。使用[模板](../../../.agents/skills/dsh-doc/templates/persistence-format.md)添加该快照的双语记录与来源证据。保留所有更早的记录。后继格式使用当前目录；复制新的当前目录不能满足归档前驱的要求。运行时变更遵循[格式版本实操手册](../../cookbook/adding-a-session-format-version.zh.md)。
+
+注释标记内的 schema 定义与索引由工具生成。推进写入器并完成机器数据与人工证据后，刷新其表格和配对记录，再执行验证：
+
+```sh
+pnpm run verify-persistence-formats --write
+pnpm run verify-persistence-formats
+pnpm run doc-sync
+```
+
+`--write` 先验证机器数据，再更新生成的 Markdown 与配对记录。它保留人工说明、机器声明和 schema。默认验证也会拒绝过期的配对记录；标准文档检查验证翻译与本地链接。当前目录的新鲜度仍由 `verify-persistence-catalog` 负责。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/references/official-docs/docs/persistence-changes/historical-formats/v0.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/persistence-changes/historical-formats/v0.md
+v0.md: 91b8c239307c2ac721aa4879a4cb9857cd0396ce
+v0.zh.md: 735ac81c461e7dcb89aac05cf1ae3997e5e0fd25