dsh-plugin-guide 0.3.42 → 0.4.1

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

@@ -1,96 +0,0 @@
----
-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

@@ -1,28 +0,0 @@
-# Bilingual-pair consistency record for 2026-09-14-workspace-changes-event.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# 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
-/:
-  en: 3d5a424ae7d7e46b
-  zh: c22a8e4a62d8cc1a
-/2026-09-14-workspace-changes-event:
-  en: 26ab5b62b8108a0f
-  zh: 8914ac35bb8726be
-/2026-09-14-workspace-changes-event/summary:
-  en: dc8a100acdf87cb3
-  zh: d345afd67b00a057
-/2026-09-14-workspace-changes-event/table-of-contents:
-  en: 6cf314a069ceb451
-  zh: 9adff678e9ecab3b
-/2026-09-14-workspace-changes-event/declaration:
-  en: 6907136f28e48c90
-  zh: 02f8298485f3d8e7
-/2026-09-14-workspace-changes-event/compatibility:
-  en: 27e62c14c209cf6c
-  zh: 16f08efcd6a12154
-/2026-09-14-workspace-changes-event/verification:
-  en: fb7f954e862c47a7
-  zh: 76ec9f48f51b17ce
-/2026-09-14-workspace-changes-event/dev-note:
-  en: b75c8458928b72b9
-  zh: 003ba4e17b4b5269

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

@@ -1,48 +0,0 @@
----
-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

@@ -1,72 +0,0 @@
-{
-  "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

@@ -1,48 +0,0 @@
----
-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/2026-09-16-session-format-v4.i18n.yaml

@@ -1,28 +0,0 @@
-# Bilingual-pair consistency record for 2026-09-16-session-format-v4.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/persistence-changes/2026-09-16-session-format-v4.md
-/:
-  en: 3d5a424ae7d7e46b
-  zh: c22a8e4a62d8cc1a
-/2026-09-16-session-format-v4:
-  en: eb866e6ff81b18d6
-  zh: 1689de18c9b69db7
-/2026-09-16-session-format-v4/summary:
-  en: d941a7e0957adc5c
-  zh: bc3848a302d6497e
-/2026-09-16-session-format-v4/table-of-contents:
-  en: 6cf314a069ceb451
-  zh: 9adff678e9ecab3b
-/2026-09-16-session-format-v4/declaration:
-  en: 6907136f28e48c90
-  zh: 02f8298485f3d8e7
-/2026-09-16-session-format-v4/compatibility:
-  en: 0fc8ce7241c4ecbe
-  zh: d3f2c2812ecaca38
-/2026-09-16-session-format-v4/verification:
-  en: 94b3c1b1d07bc87d
-  zh: af7ec37007c62ecb
-/2026-09-16-session-format-v4/dev-note:
-  en: b75c8458928b72b9
-  zh: 003ba4e17b4b5269

package/references/official-docs/docs/persistence-changes/2026-09-16-session-format-v4.md

@@ -1,120 +0,0 @@
----
-description: "Records a persistence type transition and its compatibility acknowledgement."
-kind: persistence-change
----
-
-# 2026-09-16-session-format-v4
-
-English | [中文](2026-09-16-session-format-v4.zh.md)
-
-## Summary
-
-Advances the declared SessionHeader.version from 3 to 4 for the finalized V4 writer, records first-class tool-role results and producer-owned sources, and adds the forked variant to turn/end.reason. Adds developer-role Session changes with name-only tool additions bound to historical request headers, tool removals, and deferred-loading schema markers.
-
-## 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-16-session-format-v4
-baseline: false
-changes:
-  - root: "SessionHeader"
-    previous: "2026-09-11-initial"
-    after: "1a3440e3577382704d42a6263aa463504eb74c566734a55e9503a63efcd02445"
-    decision: version-bump
-  - root: "event:agent/inbox/spliced"
-    previous: "2026-09-14-image-offload"
-    after: "1506a9b8224986c83015ae99d2cb5ede705538c58c063d6a48ef6d761a31ba6c"
-    decision: version-bump
-  - root: "event:assistant/attempt"
-    previous: "2026-09-14-image-offload"
-    after: "15d5dfdd822aa35e115afd74a8982825a493880457774e6850bc1520b50875e4"
-    decision: version-bump
-  - root: "event:assistant/message"
-    previous: "2026-09-14-image-offload"
-    after: "1033093edd0db80ff410e00830b523405e00bb0c7684948e531ff65095799625"
-    decision: version-bump
-  - root: "event:compaction/summary"
-    previous: "2026-09-14-image-offload"
-    after: "e2f9a41e0989f54ed8cee80f8db2bcf9d60a5c810dc9d45b83fa050b9dce7602"
-    decision: version-bump
-  - root: "event:developer/message"
-    previous: null
-    after: "eef4ef54dc7a133d47448a4ee822e45a351314923ef5f66db34c8b24e4b32d80"
-    decision: version-bump
-  - root: "event:request/header"
-    previous: "2026-09-11-initial"
-    after: "4208123b50df5006b181481ab45fcf1cde807b88d3fd4d340090bc2e202fac41"
-    decision: version-bump
-  - root: "event:session/title-llm-request"
-    previous: "2026-09-14-image-offload"
-    after: "fa8f7d3ebf08a76c7f7a8b0781873c4d819b964da5dbb52cd3cdfa5da34f452d"
-    decision: version-bump
-  - root: "event:system/message"
-    previous: "2026-09-14-image-offload"
-    after: "69081694be231d56fd9580ba14645fd5e35373202605d5c5c841a9435b5fa3b1"
-    decision: version-bump
-  - root: "event:team/message/queued"
-    previous: "2026-09-14-image-offload"
-    after: "21fb6a90d5068f6a0003b7ab316ed2f56342477146a65c00db0f13c4d8df667d"
-    decision: version-bump
-  - root: "event:tool/ptc-dispatch"
-    previous: "2026-09-14-image-offload"
-    after: "100f6dca1468538239522cde3533e5bd721d0f1a7b50bea8b0eb533ea6c96163"
-    decision: version-bump
-  - root: "event:tool/result"
-    previous: "2026-09-14-image-offload"
-    after: "7c9f44e90a0058f4cc532ae20dad0c10afa6eba22e70a6c79fc79490bad64397"
-    decision: version-bump
-  - root: "event:turn/end"
-    previous: "2026-09-14-image-offload"
-    after: "0f8512903d94f57a4748fa1a2092e64342856796684e6b8343db685b192745ce"
-    decision: version-bump
-  - root: "event:user/message"
-    previous: "2026-09-14-image-offload"
-    after: "3f72db3d87a0c5c43e68be467b4cca728eaf5adc1d5d2b6975ff42bfbd961761"
-    decision: version-bump
-```
-
-<a id="compatibility"></a>
-## Compatibility
-
-The tool-role declaration changes ten event roots because inbox entries, message events, compaction summaries, title requests, team messages, and PTC dispatches embed the shared `Message` or `ContentBlock` declarations. Removing `tool-result` from that union and specializing message roles changes those reachable schemas without adding ten independent event protocols. The `turn/end` change separately records the forked reason; `SessionHeader` records the version increase.
-
-The [native V4 validation decision](../../.agents/notes/implemented/architecture/2026-09-17-native-v4-read-validation.md) owns the reader admission required by these current fields.
-
-The V3-to-V4 migration lifts released user-role tool results into tool-role messages with a required toolCallId and optional isError. Tool-result wrappers leave the content-block union. The migration preserves every admitted source event and inherited cut, and appends missing parent subagent/catalog records from retained direct-child logs in the same persistence root. Historical body restoration requires an explicit child-evidence set, including an empty set when no children are available to backfill. Missing, multiple, or unknown-version child descriptors skip that child’s backfill; conflicting identities, timestamps, or modes refuse migration without publication. Existing catalog facts remain. Historical read opens prepare the result in memory. Write opens revalidate child membership and revisions before publishing the current successor beside unchanged predecessor files. Delivery-generation checks keep historical acknowledgements from becoming active V4 watermarks. V3 readers refuse the newer generation. The finalized transition adds forked to turn/end.reason; exact-cut forks append child-owned error results and closers after the inherited marker. V4 admits checked not-started fork results with deterministic branch-specific IDs and wording; released V0–V3 validators and recorded predecessor generations remain unchanged.
-
-The `request/header` schema also records the retired `system` key as forbidden. This declaration captures the existing native-reader refusal without changing stored data or prompt reconstruction; later permitting a value requires compatibility review for a same-version change, or an explicit version bump, instead of being classified as an ordinary optional-field addition.
-
-Producer-owned sources replace released plugin wrappers through the [V3-to-V4 migration](../../packages/session/session-format-v3-to-v4/README.md#v3-to-v4-specification). The frozen rename table and collision rules preserve source fields and event coordinates; unknown producer attribution retains every own JSON property. Native read and write opens validate source fields before exposing the Session. Existing V4 files do not rerun the incoming migration edge.
-
-The core-owned user source property records the attribution-preservation policy; tmux-context qualifies its location attribution while retaining producer-local duplicate suppression. Auto Review and the compaction summarizer use request-only user inputs, removing their active source registrations without removing historical migration support. These inputs cannot be written as durable Session messages. Catalog formatVersion 2 stores the policy metadata; it does not change the Session version or rewrite frozen schema records. System, model, and tool sources retain their strict semantic rules.
-
-Developer events retain their original role and require an open step. Each addition stores toolName; developer/message.headerSeq identifies an earlier known request/header containing exactly one complete matching ToolSchema. All additions in one event share that historical header revision, while removal-only and other developer messages omit headerSeq. Native and Session admission reject absent, forward, non-header, unknown-header, ambiguous, incomplete-definition and retired inline-definition forms without interpreting unknown ignorable records or dropping unrelated JSON metadata. Same-name replacement, restart, fork, surface replacement and compaction retain historical schema identity without consulting the latest header or registry. Generic sourceEventSeqs remains independent. Developer sources use the same recorded attribution-preservation policy as user sources. The optional deferLoading marker is independent of addition history. No shipped profile emits developer records; provider serialization, automatic emission and UI support remain deferred.
-
-The PTC producer writes `source.kind: 'ptc-mode'`. The V3-to-V4 edge retains `tools-code-mode` and `tools-ptc` as historical plugin lookup keys and maps both to that current kind. The source policy reserves `ptc-mode` against attribution-only qualification.
-
-<a id="verification"></a>
-## Verification
-
-The focused Session, agent-loop, Session Controller, V4, chat-view, and compaction suites passed 1,523 tests across 63 files after integration of exact-cut forks. V4 fork tests retain original IDs and text across encoding, decoding, and restoration, reject malformed results, and validate nested inherited cuts. The tool-role migration tests and SDK snapshot refresh also passed in the originating change; the built Python runtime sdk-snapshot scenario passed, and focused pi-ai and auto-review coverage passed 351 tests with 100% coverage of the three affected modules.
-
-The generated request-header reservation regression and existing retired-syntax and Session surface tests passed 65 tests across three files. The generated field retains optional `never`; the current classifier marks permitting an optional string as requiring compatibility review, while the native reader still refuses the retired key.
-
-The producer-source and request-input checks pass 447 tests across 12 files, including provider equality, request-only type rejection, user-attribution retention, source migration, and native source admission. Comparing the generated inventories with the tool-role parent reports four changed roots and 447 unchanged type fingerprints.
-
-The focused Session, V4 and request-input suite passes 884 tests across 38 files, with 100% statements, branches, functions and lines for the complete V3-to-V4 package and Session surface. Coverage includes historical same-name schema binding, compound additions/removals, malformed references and definitions, unknown-header refusal, opaque unknown records, metadata preservation, forks, replacements, compaction references, and native plain/zstd read/write admission without rewriting the generation.
-
-<a id="dev-note"></a>
-## Dev Note
-
-None.