dsh-plugin-guide 0.3.15 → 0.3.17

package/references/official-docs/docs/persistence-changes/2026-09-12-auto-review-error-metadata.zh.md

@@ -0,0 +1,52 @@
+---
+description: "记录持久化类型更改及其兼容性确认。"
+kind: persistence-change
+---
+
+# 2026-09-12-auto-review-error-metadata
+
+[English](2026-09-12-auto-review-error-metadata.md) | 中文
+
+## 概述
+
+为持久化的 PTC dispatch 增加可选的结构化错误元数据，并为持久化的原生工具错误增加可选的用户可见理由。两项新增字段均保持 Session 格式版本。
+
+## 目录
+
+- [声明](#declaration)
+- [兼容性](#compatibility)
+- [验证](#verification)
+- [开发备注](#dev-note)
+
+<a id="declaration"></a>
+## 声明
+
+```yaml persistence-change
+schemaVersion: 1
+id: 2026-09-12-auto-review-error-metadata
+baseline: false
+changes:
+  - root: "event:tool/ptc-dispatch"
+    previous: "2026-09-11-initial"
+    after: "b5d66eaebed4da391b13498623b11142222149fbf5e025975dbc6d94f0d06796"
+    decision: same-version
+  - root: "event:tool/result"
+    previous: "2026-09-11-initial"
+    after: "3a803805bdeb805f32b229e399fb7258be8e32a89f89063a7c99957cfea942f7"
+    decision: same-version
+```
+
+<a id="compatibility"></a>
+## 兼容性
+
+已有 tool/ptc-dispatch 事件可以省略 error，已有 tool/result 错误可以省略 reason。PTC dispatch 事件不进入模型历史；原生工具结果回放只投影 data.message，不包含错误元数据。旧读取方可以忽略新增字段，不改变模型回放。当前 Web 读取方接受缺失的理由，并且只有记录中的错误标识匹配时才显示 Auto review 拒绝详情。权限模式在已有事件中仍为字符串；选择 auto 不引入已声明持久化类型的变更。Session header、事件信封和已有值类型均未改变，无需相邻迁移。
+
+<a id="verification"></a>
+## 验证
+
+pnpm exec vitest run scripts/persistence-changes.spec.ts scripts/persistence-schema.spec.ts 通过 64 个测试。权限、Auto review、工具执行、agent loop（智能体循环）、subagent 继承和 TypeScript SDK 的定向测试共 10 个文件、390 个测试通过，覆盖原生与 PTC 拒绝元数据。uv run --python 3.10 --group test --project python/sdk pytest python/sdk/tests/test_client.py -k preserves_auto_review_errors 通过 1 个测试。持久化预览仅识别出这两项可选字段新增，均无需提升版本。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/references/official-docs/docs/persistence-changes/2026-09-14-image-offload.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-image-offload.md
+2026-09-14-image-offload.md: 1d4f47f5a25cc9dd39ad16f111af7f30d906a297
+2026-09-14-image-offload.zh.md: b184b32e96d04a425eda6faf9f5d50f815a9c32a

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

@@ -0,0 +1,96 @@
+---
+description: "Records a persistence type transition and its compatibility acknowledgement."
+kind: persistence-change
+---
+
+# 2026-09-14-image-offload
+
+English | [中文](2026-09-14-image-offload.zh.md)
+
+## Summary
+
+Record selected image occurrences with the image/offload event and derive their offloaded marks through the owning plugin's message projection.
+
+## 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-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>
+## Compatibility
+
+Existing logs remain readable. The optional offloaded image field leaves unmarked occurrences retained. The new event is required on read: older builds that do not recognize image/offload refuse those logs, and current readers require its message projection. Event envelopes and structural Session format versions are unchanged.
+
+<a id="verification"></a>
+## Verification
+
+Session and image-offload tests cover event validation, immutable message projection, missing interpreters, restore, and retry. The focused 1,144-test run and two TypeScript image snapshots pass. The Python advanced SDK recording was refreshed through the built dsh profile and includes the standalone image/offload event.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.