dsh-plugin-guide 0.3.42 → 0.4.1

package/references/official-docs/docs/subsystems/todo.md

@@ -1,32 +0,0 @@
-# Todo
-
-English | [中文](todo.zh.md)
-
-The durable todo vocabulary owned by [`@deepseek-ai/dsh-tool-todo`](../../packages/todo/tool-todo/README.md). The model-facing tool replaces one agent session's whole list; the package also owns the event declaration and replay projection. Tool behavior and configuration are on the [package README](../../packages/todo/tool-todo/README.md).
-
-Source: [`packages/todo/tool-todo/src/types.ts`](../../packages/todo/tool-todo/src/types.ts)
-
-## `TodoItem` — one list entry
-
-```ts type-equiv
-/**
- * One entry in an agent's todo list — the unit of the `todo/write`
- * whole-list snapshot declared by this package.
- *
- * Deliberately minimal: a human-readable `content` line and a three-state
- * `status`. No id, priority, or `activeForm` — the list is replaced wholesale
- * on every write (last-write-wins), so entries need no stable identity. The
- * three statuses describe the complete portable lifecycle needed by model and
- * UI consumers.
- */
-interface TodoItem {
-  /** What this task is — a short imperative line shown in the UI. */
-  content: string
-  /** Lifecycle state. `in_progress` marks a task being worked now; parallel work may mark several. */
-  status: 'pending' | 'in_progress' | 'completed'
-}
-```
-
-## Durable event
-
-The package declaration-merges `todo/write: { todos: TodoItem[] }` into `SessionEventMap`. The event is log-only and carries the complete replacement list; the generated [persistence catalog](../persistence-catalog.md#todowrite--log-only) records its declaration site.

package/references/official-docs/docs/subsystems/todo.zh.md

@@ -1,32 +0,0 @@
-# Todo
-
-[English](todo.md) | 中文
-
-本页记录 [`@deepseek-ai/dsh-tool-todo`](../../packages/todo/tool-todo/README.zh.md) 拥有的持久 todo 词汇。面向模型的工具会整体替换一个 agent（智能体）会话的列表；该包还拥有事件声明和回放投影。工具行为与配置见[包 README](../../packages/todo/tool-todo/README.zh.md)。
-
-源码：[`packages/todo/tool-todo/src/types.ts`](../../packages/todo/tool-todo/src/types.ts)
-
-## `TodoItem`：一条列表项
-
-```ts type-equiv
-/**
- * One entry in an agent's todo list — the unit of the `todo/write`
- * whole-list snapshot declared by this package.
- *
- * Deliberately minimal: a human-readable `content` line and a three-state
- * `status`. No id, priority, or `activeForm` — the list is replaced wholesale
- * on every write (last-write-wins), so entries need no stable identity. The
- * three statuses describe the complete portable lifecycle needed by model and
- * UI consumers.
- */
-interface TodoItem {
-  /** What this task is — a short imperative line shown in the UI. */
-  content: string
-  /** Lifecycle state. `in_progress` marks a task being worked now; parallel work may mark several. */
-  status: 'pending' | 'in_progress' | 'completed'
-}
-```
-
-## 持久事件
-
-该包通过声明合并把 `todo/write: { todos: TodoItem[] }` 加入 `SessionEventMap`。此事件仅写入日志，并携带完整替换列表；生成的[持久化目录](../persistence-catalog.zh.md#todowrite--log-only)会记录其声明位置。

package/references/official-docs/docs/subsystems/token-meter.i18n.yaml

@@ -1,13 +0,0 @@
-# Bilingual-pair consistency record for token-meter.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/subsystems/token-meter.md
-/token-meter:
-  en: 7b81394f8688ad71
-  zh: e38852d59e9793fd
-/token-meter/tokenmeasurement:
-  en: 34853869e90adf31
-  zh: 285010a2f695ca01
-/token-meter/tokensurfacenode:
-  en: e445d12b10f651d0
-  zh: e93be5fb9da1da15

package/references/official-docs/docs/subsystems/token-meter.md

@@ -1,106 +0,0 @@
-# Token Meter
-
-English | [中文](token-meter.zh.md)
-
-`@deepseek-ai/dsh-token-meter` exposes one detached replay snapshot for request pressure and positional surface pricing. `logRevision` is the number of durable events consumed for every field in the measurement.
-
-Source: [`packages/llm/token-meter/src/types.ts`](../../packages/llm/token-meter/src/types.ts)
-
-## `TokenMeasurement`
-
-```ts type-equiv
-/** Detached immutable request-pressure and surface snapshot at one consumed log revision. */
-interface TokenMeasurement {
-  /** Number of durable events consumed; equal to the next unread event seq. */
-  readonly logRevision: SessionLogOffset
-  /** Provider or heuristic anchor used for this measurement. */
-  readonly baseline: TokenMeasurementBaseline
-  /** Signed repricing of current surface content relative to the baseline anchor. */
-  readonly surfaceDeltaTokens: number
-  /** Non-negative current request-and-response pressure. */
-  readonly totalTokens: number
-  /** Total route-priced request tokens across the current surface; equals the sum of the node prices. */
-  readonly surfaceTokens: number
-  /** Current surface nodes in positional head-to-tail order. */
-  readonly nodes: readonly TokenSurfaceNode[]
-}
-```
-
-Every measurement resolves the effective envelope's routed provider/model to that route's declared request-image pricing through `ctx.llm`, so image occurrences are priced as the visual tokens plus model-visible text the request actually sends; routes and compositions without declared pricing keep the fixed heuristic. `baseline.kind === 'usage'` means the latest successful provider call has the same canonical request envelope and its total is no lower than that call's full route-priced anchor. `estimated` means no reusable conservative usage anchor exists, so the service priced the complete envelope and surface itself. A later successful request replaces the earlier anchor; signed `surfaceDeltaTokens` preserves growth and shrinkage relative to a matching anchor, repricing both sides under the same route. `totalTokens` remains request-and-response pressure, while `surfaceTokens` is the surface-only route-priced total and equals the sum of the node prices.
-
-## `TokenSurfaceNode`
-
-```ts type-equiv
-/** One token-priced node in the current ordered session surface. */
-interface TokenSurfaceNode {
-  /** Durable sequence number of the surface event. */
-  readonly seq: SessionSeq
-  /**
-   * Request-pressure tokens for the exact message projected by this node under
-   * the measured route: image occurrences carry the route's declared visual
-   * price when the routed adapter declares one, and the fixed heuristic
-   * otherwise. Trigger, retention, and range selection all read this price.
-   */
-  readonly tokens: number
-  /**
-   * Fixed-heuristic tokens for the same message, independent of any route.
-   * The shadow-price protocol prices replacements with this value so the O(1)
-   * projection fold stays in agreement with its own appends.
-   */
-  readonly heuristicTokens: number
-}
-```
-
-Surface order is authoritative; replacement nodes can have higher durable seqs than later positional nodes. The snapshot is immutable and does not grow when the underlying replay fold advances.
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxtokenmeter--tokenmeter"></a>
-
-### `ctx.tokenMeter` — `TokenMeter`
-
-Replay owner for one service-wide estimator and isolated per-session folds.
-
-```ts cordis-catalog
-/**
- * Measure current request pressure and surface through the durable tail.
- *
- * The effective envelope's routed provider/model selects the request-image
- * pricing every node is priced under: a route whose adapter declares image
- * pricing charges each retained image its visual tokens plus its
- * model-visible text, while other routes keep the fixed heuristic. Provider
- * usage is reused only when the latest successful call's canonical request
- * envelope matches `requestHeader` and its total is no lower than that
- * call's full route-priced anchor; otherwise the complete envelope and
- * surface are repriced. The anchor includes all surface nodes immediately
- * before the assistant message, including inputs admitted after step/start.
- *
- * `requestHeader` replaces the latest logged envelope for pressure and node
- * pricing; the node set always describes the current session surface. Every
- * call clones those positional nodes, so measurement is O(surface).
- *
- * @param session - session to replay through its current durable tail.
- * @param requestHeader - optional effective request envelope replacing the latest logged header.
- * @returns a detached deeply immutable pressure and surface measurement.
- */
-measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
-
-/**
- * Heuristically price one model-visible message (instance face of the pure
- * `estimateMessage` export from `estimate.ts`).
- * @param message - message to price without mutation.
- * @returns content and role-framing tokens under the fixed service heuristic.
- */
-estimateMessage(message: Message): number
-```
-
-Types: [EpochHeader](session.md) · [Message](llm-streaming.md) · [Session](session.md)
-
-Source: [`packages/llm/token-meter/src/index.ts`](../../packages/llm/token-meter/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/token-meter.zh.md

@@ -1,106 +0,0 @@
-# Token 计量
-
-[English](token-meter.md) | 中文
-
-`@deepseek-ai/dsh-token-meter` 公开一个独立的回放快照，用于表示请求压力与按位置计算的表层定价。`logRevision` 表示生成该计量中每个字段时所消费的持久事件数量。
-
-来源：[`packages/llm/token-meter/src/types.ts`](../../packages/llm/token-meter/src/types.ts)
-
-## `TokenMeasurement`
-
-```ts type-equiv
-/** Detached immutable request-pressure and surface snapshot at one consumed log revision. */
-interface TokenMeasurement {
-  /** Number of durable events consumed; equal to the next unread event seq. */
-  readonly logRevision: SessionLogOffset
-  /** Provider or heuristic anchor used for this measurement. */
-  readonly baseline: TokenMeasurementBaseline
-  /** Signed repricing of current surface content relative to the baseline anchor. */
-  readonly surfaceDeltaTokens: number
-  /** Non-negative current request-and-response pressure. */
-  readonly totalTokens: number
-  /** Total route-priced request tokens across the current surface; equals the sum of the node prices. */
-  readonly surfaceTokens: number
-  /** Current surface nodes in positional head-to-tail order. */
-  readonly nodes: readonly TokenSurfaceNode[]
-}
-```
-
-每次计量都会通过 `ctx.llm` 把生效信封的路由 provider/model 解析为该路由声明的请求图片定价，因此图片出现处按请求实际发送的视觉 token 加模型可见文本计价；未声明定价的路由与组合保持固定启发式规则。`baseline.kind === 'usage'` 表示最近一次成功的提供方调用具有相同的规范请求 envelope，且该调用的总量不低于其完整路由定价锚点。`estimated` 表示不存在可复用的保守 usage 锚点，因此服务自行对完整信封和表层定价。后续成功请求会替换早先的锚点；有符号的 `surfaceDeltaTokens` 会保留相对于匹配锚点的增长与缩减，且两侧按同一路由重新定价。`totalTokens` 仍表示请求与响应压力，`surfaceTokens` 则是表层的路由定价总量，等于所有节点价格之和。
-
-## `TokenSurfaceNode`
-
-```ts type-equiv
-/** One token-priced node in the current ordered session surface. */
-interface TokenSurfaceNode {
-  /** Durable sequence number of the surface event. */
-  readonly seq: SessionSeq
-  /**
-   * Request-pressure tokens for the exact message projected by this node under
-   * the measured route: image occurrences carry the route's declared visual
-   * price when the routed adapter declares one, and the fixed heuristic
-   * otherwise. Trigger, retention, and range selection all read this price.
-   */
-  readonly tokens: number
-  /**
-   * Fixed-heuristic tokens for the same message, independent of any route.
-   * The shadow-price protocol prices replacements with this value so the O(1)
-   * projection fold stays in agreement with its own appends.
-   */
-  readonly heuristicTokens: number
-}
-```
-
-表层顺序具有权威性；替换节点的持久 seq 可能高于位置排在其后的节点。该快照不可变，不会随底层回放折叠推进而增长。
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxtokenmeter--tokenmeter"></a>
-
-### `ctx.tokenMeter` — `TokenMeter`
-
-Replay owner for one service-wide estimator and isolated per-session folds.
-
-```ts cordis-catalog
-/**
- * Measure current request pressure and surface through the durable tail.
- *
- * The effective envelope's routed provider/model selects the request-image
- * pricing every node is priced under: a route whose adapter declares image
- * pricing charges each retained image its visual tokens plus its
- * model-visible text, while other routes keep the fixed heuristic. Provider
- * usage is reused only when the latest successful call's canonical request
- * envelope matches `requestHeader` and its total is no lower than that
- * call's full route-priced anchor; otherwise the complete envelope and
- * surface are repriced. The anchor includes all surface nodes immediately
- * before the assistant message, including inputs admitted after step/start.
- *
- * `requestHeader` replaces the latest logged envelope for pressure and node
- * pricing; the node set always describes the current session surface. Every
- * call clones those positional nodes, so measurement is O(surface).
- *
- * @param session - session to replay through its current durable tail.
- * @param requestHeader - optional effective request envelope replacing the latest logged header.
- * @returns a detached deeply immutable pressure and surface measurement.
- */
-measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
-
-/**
- * Heuristically price one model-visible message (instance face of the pure
- * `estimateMessage` export from `estimate.ts`).
- * @param message - message to price without mutation.
- * @returns content and role-framing tokens under the fixed service heuristic.
- */
-estimateMessage(message: Message): number
-```
-
-Types: [EpochHeader](session.zh.md) · [Message](llm-streaming.zh.md) · [Session](session.zh.md)
-
-Source: [`packages/llm/token-meter/src/index.ts`](../../packages/llm/token-meter/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/tools.i18n.yaml

@@ -1,25 +0,0 @@
-# Bilingual-pair consistency record for tools.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/subsystems/tools.md
-/tools:
-  en: e3ecdbc9d7078226
-  zh: 82d609bfd382311e
-/tools/tooldefinition-a-registered-tool:
-  en: e5ebf149f6783674
-  zh: 062aa8477376f953
-/tools/the-unified-json-value-schema-dsl:
-  en: 9ff354e00a1fbe91
-  zh: b302216d889f9b58
-/tools/toolrestriction-one-scope-s-live-filter-over-what-it-inherits:
-  en: 8c3fc4ca26f7e314
-  zh: 2e27263cb25243b9
-/tools/execution-extensible-waterfalls-plus-monotonic-policy:
-  en: dcac8fa88ef3e719
-  zh: aae2f4ce8852d8d8
-/tools/the-enforced-raw-json-schema-subset:
-  en: 28e354bfa2f9cebb
-  zh: be1f75abccf8afdf
-/tools/tool-presentation-ui-vocabulary:
-  en: 078fac733842b847
-  zh: e8bc6e56ad1932fe