dsh-plugin-guide 0.3.35 → 0.3.36

package/references/official-docs/docs/defensive-patterns/README.i18n.yaml

@@ -0,0 +1,10 @@
+# Bilingual-pair consistency record for README.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/defensive-patterns/README.md
+/defensive-patterns:
+  en: 7229c49e920aa5b3
+  zh: 1dd52db6b4d84952
+/defensive-patterns/why-these-rules:
+  en: 7c012071b5af8c98
+  zh: 298aaba83625c7a0

package/references/official-docs/docs/defensive-patterns/README.md

@@ -0,0 +1,25 @@
+# Defensive patterns
+
+English | [中文](README.zh.md)
+
+Hard-won rules: each pattern in this directory is a requirement this repository enforces in review, stated as the rule and the defect it prevents. Every rule states what must hold, the condition a reviewer judges it by, its boundary and who approves an exception, and a correct and a wrong example. Read the page for the artifact you are about to change, before you change it.
+
+## Why these rules
+
+Five habits cover most of what follows, and each page is their application to one artifact:
+
+- **Make correctness explicit.** Write it into the structure — named call points, explicit lifecycles, explicit conditions and types — rather than compensating for it afterwards with timing.
+- **Keep one source of truth.** One read path for a piece of data, one home for a fact, one owner for shared state.
+- **Extend through the registered seam.** A new capability registers; an existing carrier stops taking new logic instead of growing a branch inside it.
+- **Keep the change face equal to the review face.** A change carries only the lines its stated behavior change needs, a migration moves code rather than rewriting it, and a performance-sensitive change carries its measurement.
+- **Require evidence.** A claim is falsifiable and recomputable — measured before and after, or checked by a gate — rather than kept in sync by hand.
+
+| Changing | Read |
+|---|---|
+| Package exports, package shape, build faces, dependency declarations | [package-surface.md](package-surface.md) |
+| Remote services, `@Remote` methods, API dispatch, business ownership at the API layer | [remote-and-api.md](remote-and-api.md) |
+| Client components, slots, stores, hooks, effects | [client-components.md](client-components.md) |
+| Session reads, retention, conversation nodes, renderers | [conversation-and-session.md](conversation-and-session.md) |
+| Timing, state representation, shared ownership, decentralization, refactors, migrations, performance evidence, disposal, callbacks, subprocesses | [general.md](general.md) |
+
+Type definitions and per-subsystem semantics live in [subsystems/](../subsystems/README.md); this directory carries the rules, and the semantics pages carry what the types mean. [dsh-code-review](../../.agents/skills/dsh-code-review/SKILL.md) reads this directory when judging a pull request, and Development routes through the same table from [AGENTS.md](../../AGENTS.md).

package/references/official-docs/docs/defensive-patterns/README.zh.md

@@ -0,0 +1,27 @@
+# 防御性模式
+
+[English](README.md) | 中文
+
+来之不易的规则：本目录中每条模式都是本仓库在评审中执行的**要求**，以「规则 + 它所防止的缺陷」的形式陈述。每条规则都写明：必须成立什么、评审据什么判定、边界在哪、例外由谁批准，以及一个正例与一个反例。动手修改某类制品之前，先读对应那一页。
+
+<a id="why-these-rules"></a>
+
+## 这些规则背后的思想
+
+下面五条习惯覆盖了绝大部分内容，每一页都是它们在某类制品上的落地：
+
+- **把正确性显式化。** 把它写进结构——具名调用点、显式生命周期、显式条件与类型——而不是事后用时序去补偿。
+- **只留一个真相。** 一份数据一条读取路径，一个事实一个正家，共享状态一个所有者。
+- **走注册面扩展。** 新能力靠注册接入；既有载体不再承接新逻辑，而不是在它内部长出分支。
+- **把改动面压成评审面。** 改动只包含其声明的行为变化所需的行；迁移是搬代码而不是重写；涉及性能的改动附带测量。
+- **要求可证伪、可复算。** 口径能被改动前后的实测或门禁证明/否证，而不是靠人肉同步。
+
+| 你在改什么 | 读哪篇 |
+|---|---|
+| 包导出面、包形态、构建面、依赖声明 | [package-surface.zh.md](package-surface.zh.md) |
+| 远程服务、`@Remote` 方法、API 分发、API 层的业务归属 | [remote-and-api.zh.md](remote-and-api.zh.md) |
+| 客户端组件、slots、store、hooks、effect | [client-components.zh.md](client-components.zh.md) |
+| Session 读取、持有、会话节点、renderer | [conversation-and-session.zh.md](conversation-and-session.zh.md) |
+| 时序、状态表示、共享归属、去中心化、重构、迁移、性能证据、清理、回调、子进程 | [general.zh.md](general.zh.md) |
+
+类型定义与各子系统语义见 [subsystems/](../subsystems/README.zh.md)；本目录承载**规则**，语义页承载**类型的含义**。[dsh-code-review](../../.agents/skills/dsh-code-review/SKILL.md) 在评审 pull request 时读本目录，日常修改经 [AGENTS.md](../../AGENTS.md) 路由到同一张表。

package/references/official-docs/docs/defensive-patterns/client-components.i18n.yaml

@@ -0,0 +1,46 @@
+# Bilingual-pair consistency record for client-components.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/defensive-patterns/client-components.md
+/client-component-rules:
+  en: a6e8a87976040c04
+  zh: 08b59ad3c14fe250
+/client-component-rules/state-arrives-through-injection:
+  en: 112232a703ce472d
+  zh: cf42bda22d8e4da4
+/client-component-rules/props-carry-data-and-callbacks-not-react-nodes:
+  en: 253f05568dd7e26f
+  zh: fa12565ff5afb8bd
+/client-component-rules/a-slot-registration-is-a-stable-function-component:
+  en: 784d3a4bba02f8a4
+  zh: 0ccfcc1a504b135c
+/client-component-rules/components-never-receive-a-cordis-context:
+  en: 8bb102b178615c03
+  zh: 93cb177a578a1373
+/client-component-rules/context-comes-from-the-current-scope:
+  en: 652ec94d13ee51c9
+  zh: b47c39e96c53cfac
+/client-component-rules/resource-consumers-go-through-useresource:
+  en: 6650c772df96f935
+  zh: 57fc0a564caf62a8
+/client-component-rules/store-usage-is-narrow-and-explicit:
+  en: 697b2e81a862e3bf
+  zh: 13cf31bef332a601
+/client-component-rules/identity-and-initial-state-are-deliberate:
+  en: a34c30b8f7c415d4
+  zh: cbd0c0cf0c0db57c
+/client-component-rules/uselayouteffect-is-not-a-default:
+  en: f53f17846a8a89b2
+  zh: 94d205c4d85f1de9
+/client-component-rules/effects-never-push-render-derived-data-to-a-parent:
+  en: 580441bd6cce9ee9
+  zh: a5f093d8e7dec2ee
+/client-component-rules/build-and-style-follow-their-owners:
+  en: 561df1e1709a004c
+  zh: 89ca6eb4533648b8
+/client-component-rules/a-key-states-what-it-identifies:
+  en: 1d6f9bdc2b267fef
+  zh: cf4d579ca877c422
+/client-component-rules/each-shared-layer-keeps-its-own-isolation-level:
+  en: 3faec81a6a7c9fdd
+  zh: aa512c089b5f9afc