dsh-plugin-dev-kb 1.3.0 → 1.5.1

package/kb/extra/subsystems/deliverables.zh.md

@@ -0,0 +1,178 @@
+# 产出物
+
+[English](deliverables.md) | 中文
+
+记录一轮交给用户的东西，由 [deliverables 包组](../../packages/deliverables/README.zh.md)拥有：模型通过 `present` 工具声明的文件，记在一个只写日志的 Session 事件里；这一轮改动的文件，由轮开始和轮结束时的 git 工作树快照对比得出，git 覆盖不到的路径则由文件工具每次编辑前后的整文件捕获得出，用一个只写日志的事件宣告，并在 Session 存活期间由 Host 服务连同每个所列文件在轮开始与轮结束时的对比一起提供。它们只由客户端读取，Web [产出物插件](../../packages/client/ui-deliverables/README.zh.md)在轮末渲染两者。工具行为、快照机制和配置见 [`tool-present`](../../packages/deliverables/tool-present/README.zh.md) 与 [`workspace-changes`](../../packages/deliverables/workspace-changes/README.zh.md) 的包 README。
+
+源码：[`packages/deliverables/tool-present/src/types.ts`](../../packages/deliverables/tool-present/src/types.ts)、[`packages/deliverables/workspace-changes/src/types.ts`](../../packages/deliverables/workspace-changes/src/types.ts)
+
+## `PresentedFile`：一条声明的交付
+
+```ts type-equiv
+/** A declared filesystem file whose current contents remain at its source path. */
+interface PresentedFile {
+  /** Original absolute path or path relative to the Session working directory. */
+  path: string
+  /** Optional description supplied by the model. */
+  description?: string
+}
+```
+
+## `WorkspaceChangedFile`：一个改动的文件
+
+```ts type-equiv
+/** One file changed during a turn, with line counts from git or from the whole-file captures around its file-tool edits. */
+interface WorkspaceChangedFile {
+  /** Path relative to the Session working directory, or an absolute Host path outside it. */
+  path: string
+  /**
+   * Sort key and label: the relative path inside the working directory, a
+   * `../` path for repository files above it, a `~` path under the home
+   * directory, otherwise the absolute path. Always slash-separated.
+   */
+  display: string
+  /** Lines added; zero for a binary or oversized file. */
+  added: number
+  /** Lines deleted; zero for a binary or oversized file. */
+  deleted: number
+  /** Present when git reported the file as binary, or when a captured side holds a NUL byte. */
+  binary?: true
+  /** Present when a captured side exceeded the plugin's `maxFileBytes`; the file is listed without counts or comparison. */
+  oversized?: true
+}
+```
+
+## `WorkspaceChangesSummary`：一轮的改动摘要
+
+```ts type-equiv
+/** Files changed during one top-level turn, kept on the Host until its Session is disposed. */
+interface WorkspaceChangesSummary {
+  /** The turn whose file changes this summary describes. */
+  turn: number
+  /** The Session working directory `path` values are relative to. */
+  cwd: string
+  /** Changed files in `display` order, capped at the plugin's `maxFiles`. */
+  files: WorkspaceChangedFile[]
+  /** Complete changed-file count, including files omitted by the cap. */
+  total: number
+  /** Lines added over every changed file, including files omitted by the cap. */
+  added: number
+  /** Lines deleted over every changed file, including files omitted by the cap. */
+  deleted: number
+  /** Git tree ids of the turn-start and turn-end snapshots; absent when no snapshot was taken. */
+  snapshot?: { before: string; after: string }
+}
+```
+
+## `WorkspaceDiffHunk`：一个 unified diff hunk
+
+```ts type-equiv
+/** One unified-diff hunk with three context lines; every line keeps its `+`, `-`, or space prefix. */
+interface WorkspaceDiffHunk {
+  /** First line of the hunk in the turn-start content, 1-based; a side without lines starts at 1 with zero lines. */
+  oldStart: number
+  /** Lines of the hunk taken from the turn-start content. */
+  oldLines: number
+  /** First line of the hunk in the turn-end content, 1-based; a side without lines starts at 1 with zero lines. */
+  newStart: number
+  /** Lines of the hunk taken from the turn-end content. */
+  newLines: number
+  /** Hunk body in order, each line prefixed with `+`, `-`, or a space. */
+  lines: string[]
+}
+```
+
+## `WorkspaceFileDiff`：一个文件的对比
+
+```ts type-equiv
+/** The comparison of one listed file's turn-start and turn-end contents, computed when asked for. */
+type WorkspaceFileDiff =
+  | {
+    kind: 'text'
+    /** The listed file's `path`. */
+    path: string
+    /** The listed file's `display`. */
+    display: string
+    /** Whether the file existed at turn start. */
+    before: boolean
+    /** Whether the file existed at turn end. */
+    after: boolean
+    /** Hunks in file order; empty when both sides hold the same lines. */
+    hunks: WorkspaceDiffHunk[]
+    /** True when the line comparison exceeded the plugin's `diffTimeoutMs` and every line is shown as replaced. */
+    coarse: boolean
+  }
+  /** A side git reported as binary or that holds a NUL byte; no lines are served. */
+  | { kind: 'binary'; path: string; display: string }
+  /** A side larger than the plugin's `maxFileBytes`; no lines are served. */
+  | { kind: 'oversized'; path: string; display: string }
+```
+
+## `WorkspaceChanges`：提供摘要与对比的 Host 服务
+
+```ts type-equiv
+/** Serves the summaries and file comparisons the recorder keeps for live Sessions. */
+interface WorkspaceChanges {
+  /**
+   * The summary announced by one `workspace/changes` event.
+   * @param sessionId - the Session that appended the event.
+   * @param seq - the event's sequence number.
+   * @returns the summary, or undefined once its Session was disposed or when this Host never recorded it.
+   */
+  summary(sessionId: SessionId, seq: number): WorkspaceChangesSummary | undefined
+  /**
+   * Compare one listed file's contents at turn start and turn end.
+   * @param sessionId - the Session that appended the event.
+   * @param seq - the event's sequence number.
+   * @param index - the file's index in the summary's `files`.
+   * @param signal - cancels the reads.
+   * @returns the comparison, or undefined once its Session was disposed, when this Host never recorded it, or when no file has that index.
+   * @throws when a snapshot read fails for a live Session.
+   */
+  diff(sessionId: SessionId, seq: number, index: number, signal: AbortSignal): Promise<WorkspaceFileDiff | undefined>
+}
+```
+
+## 持久事件与提供的摘要
+
+`tool-present` 通过声明合并把 `deliverables/presented: { turn; callId; files: PresentedFile[] }` 加入 `SessionEventMap`，每次 `present` 的最终结果成功时追加一条。`workspace-changes` 合并 `workspace/changes: { turn }`，在顶层轮停止时追加；该事件宣告的摘要不在日志里，而是由 `workspaceChanges.summary(sessionId, seq)` 按事件序号返回，直到 Session 释放，因此 Host 重启后重新打开的对话，先前轮次没有改动文件卡片。`workspaceChanges.diff(sessionId, seq, index, signal)` 按同样的条件对比一个所列文件。同一轮后来的事件替代先前的，客户端只保留最新一条。生成的[持久化目录](../persistence-catalog.zh.md#deliverablespresented--log-only)记录了两处声明位置。两个事件都不会进入模型请求。
+
+<!-- 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="ctxworkspacechanges--workspacechanges"></a>
+
+### `ctx.workspaceChanges` — `WorkspaceChanges`
+
+Serves the summaries and file comparisons the recorder keeps for live Sessions.
+
+```ts cordis-catalog
+/**
+ * The summary announced by one `workspace/changes` event.
+ * @param sessionId - the Session that appended the event.
+ * @param seq - the event's sequence number.
+ * @returns the summary, or undefined once its Session was disposed or when this Host never recorded it.
+ */
+summary(sessionId: SessionId, seq: number): WorkspaceChangesSummary | undefined
+
+/**
+ * Compare one listed file's contents at turn start and turn end.
+ * @param sessionId - the Session that appended the event.
+ * @param seq - the event's sequence number.
+ * @param index - the file's index in the summary's `files`.
+ * @param signal - cancels the reads.
+ * @returns the comparison, or undefined once its Session was disposed, when this Host never recorded it, or when no file has that index.
+ * @throws when a snapshot read fails for a live Session.
+ */
+diff(sessionId: SessionId, seq: number, index: number, signal: AbortSignal): Promise<WorkspaceFileDiff | undefined>
+```
+
+Types: [SessionId](core.zh.md)
+
+Source: [`packages/deliverables/workspace-changes/src/types.ts`](../../packages/deliverables/workspace-changes/src/types.ts)
+<!-- END GENERATED cordis-surface -->

package/kb/extra/subsystems/extensions.md

@@ -46,7 +46,8 @@ list(): CordisInspectProviderView[]
  * @param input - optional lossless JSON input.
  * @param agent - requesting Agent and scope.
  * @param signal - tool-call cancellation.
- * @returns provider JSON data.
+ * @returns provider JSON data; Client queries fail fast when Gateway has no live Client
+ * and retain only the first observed failure diagnostic for timeout reporting.
  */
 async query( platform: CordisInspectPlatform, providerId: string, methodName: string, input: JsonValue | undefined, agent: Agent, signal: AbortSignal, ): Promise<JsonValue>
 
@@ -55,7 +56,7 @@ async query( platform: CordisInspectPlatform, providerId: string, methodName: st
  * @param agent - Agent whose Session owns the query.
  * @param requestId - Pending Client query identity.
  * @param resolution - Client provider result or failure.
- * @returns whether this response settled the still-pending query.
+ * @returns acknowledgement with accepted true only for a success that settles the query; only the first failure diagnostic is retained.
  */
 resolveClientQuery( agent: Agent, requestId: CordisInspectRequestId, resolution: CordisInspectQueryResolution, ): CordisInspectResolveAck
 ```
@@ -168,11 +169,12 @@ async stop(agent: Agent, pluginId: CordisDynamicPluginId): Promise<DynamicCordis
 @Remote('syncInspectManifest') syncInspectManifest(providers: readonly CordisInspectProviderManifest[]): null
 
 /**
- * Claim one pending Client inspect query with its live result.
+ * Submit a Client inspect result or failure for a pending query.
  * @param agent - Session that owns the query.
  * @param requestId - exact pending query identity.
  * @param resolution - provider result or structured refusal.
- * @returns whether this answer won the query.
+ * @returns acknowledgement with accepted true only for a valid success that settles the query;
+ * pending-query failures return { accepted: false } and retain only the first diagnostic.
  */
 @Remote('resolveInspectQuery') resolveInspectQuery( agent: Agent, requestId: CordisInspectRequestId, resolution: CordisInspectQueryResolution, ): CordisInspectResolveAck
 

package/kb/extra/subsystems/extensions.zh.md

@@ -46,7 +46,8 @@ list(): CordisInspectProviderView[]
  * @param input - optional lossless JSON input.
  * @param agent - requesting Agent and scope.
  * @param signal - tool-call cancellation.
- * @returns provider JSON data.
+ * @returns provider JSON data; Client queries fail fast when Gateway has no live Client
+ * and retain only the first observed failure diagnostic for timeout reporting.
  */
 async query( platform: CordisInspectPlatform, providerId: string, methodName: string, input: JsonValue | undefined, agent: Agent, signal: AbortSignal, ): Promise<JsonValue>
 
@@ -55,7 +56,7 @@ async query( platform: CordisInspectPlatform, providerId: string, methodName: st
  * @param agent - Agent whose Session owns the query.
  * @param requestId - Pending Client query identity.
  * @param resolution - Client provider result or failure.
- * @returns whether this response settled the still-pending query.
+ * @returns acknowledgement with accepted true only for a success that settles the query; only the first failure diagnostic is retained.
  */
 resolveClientQuery( agent: Agent, requestId: CordisInspectRequestId, resolution: CordisInspectQueryResolution, ): CordisInspectResolveAck
 ```
@@ -168,11 +169,12 @@ async stop(agent: Agent, pluginId: CordisDynamicPluginId): Promise<DynamicCordis
 @Remote('syncInspectManifest') syncInspectManifest(providers: readonly CordisInspectProviderManifest[]): null
 
 /**
- * Claim one pending Client inspect query with its live result.
+ * Submit a Client inspect result or failure for a pending query.
  * @param agent - Session that owns the query.
  * @param requestId - exact pending query identity.
  * @param resolution - provider result or structured refusal.
- * @returns whether this answer won the query.
+ * @returns acknowledgement with accepted true only for a valid success that settles the query;
+ * pending-query failures return { accepted: false } and retain only the first diagnostic.
  */
 @Remote('resolveInspectQuery') resolveInspectQuery( agent: Agent, requestId: CordisInspectRequestId, resolution: CordisInspectQueryResolution, ): CordisInspectResolveAck
 

package/kb/extra/subsystems/feedback.md

@@ -27,7 +27,7 @@ interface MessageFeedbackItem {
   readonly rating: MessageFeedbackRating
   /** Optional explanation, preserved verbatim after validation. */
   readonly note?: string
-  /** Category the human filed a negative judgment under. */
+  /** Category the human filed the judgment under. */
   readonly category?: FeedbackCategory
   /** Equality-only token replaced by every material create or update. */
   readonly version: MessageFeedbackVersion
@@ -290,7 +290,7 @@ Successful message-feedback mutations await canonical persistence: live operatio
 
 Plugin disposal closes operation admission and drains accepted per-Session queue work.
 
-When explicitly enabled, [`session-log-deepseek`](../../packages/session/session-log-deepseek/README.md) carries feedback as part of the ordinary `dsh_session_log` suffix on subsequent eligible DeepSeek requests. Recording feedback does not trigger an LLM request or a separate `dsh_feedback` upload. For non-DeepSeek routes, the [OTel backend](../../packages/session/session-telemetry-otel/README.md) can release the canonical prefix through recorded feedback. The command acknowledgement confirms recording and identifies the Session and anonymous user; it reports neither telemetry policy nor delivery.
+By default, [`session-log-deepseek`](../../packages/session/session-log-deepseek/README.md) carries feedback as part of the ordinary `dsh_session_log` suffix on subsequent eligible DeepSeek requests; a composition disables it with `enabled: false`. Recording feedback does not trigger an LLM request or a separate `dsh_feedback` upload. For non-DeepSeek routes, the [OTel backend](../../packages/session/session-telemetry-otel/README.md) can release the canonical prefix through recorded feedback. The command acknowledgement confirms recording and identifies the Session and anonymous user; it reports neither telemetry policy nor delivery.
 
 ## Web surface
 
@@ -298,9 +298,9 @@ When explicitly enabled, [`session-log-deepseek`](../../packages/session/session
 
 The controls are the `feedback` entry (order 10) of the `conversation.chat.assistant-actions` list slot, which `ui-conversation` declares and renders inside the finalized assistant message's IconActions row. `AssistantMessageNode` carries the optional `messageId` from the `assistant/message` event. The field is absent on interruption-frozen partials, and the render site skips the slot when it is absent. The strip renders once per turn, on the closing assistant message: the Host accepts every append-origin step message as a target, but earlier steps of a multi-step turn render tool rows rather than a rateable body, so the UI exposes a narrower set than the Host contract allows.
 
-One `MessageFeedbackController` per Session backs every message control in that Session: a single `list` read seeds the whole transcript, deferred to first hover or focus rather than fired on mount. Each mutation sends the version that controller last observed as `ifVersion`; a `version-conflict` reply carries the authoritative item, so the controller reconciles from the reply instead of refetching. Mutations serialize per Session so a queued operation compares against the committed version. A `connection/reset` refreshes only Sessions already read.
+One `MessageFeedbackController` per Session backs every message control in that Session: a single `list` read seeds the whole transcript, deferred to first hover or focus rather than fired on mount. Each mutation sends the version that controller last observed as `ifVersion`; a `version-conflict` reply carries the authoritative item, so the controller reconciles from the reply instead of refetching. Mutations serialize per Session so a queued operation compares against the committed version. The injected `retract` operation rechecks the committed rating inside that queue and becomes a no-op after a concurrent change, so stale UI cannot bypass the dialog by recording a bare rating. A `connection/reset` refreshes only Sessions already read.
 
-Like records the bare positive judgment at once and shows the acknowledgement toast. Dislike opens the Session's feedback dialog, the `feedback-dialog` entry of `conversation.input.overlay`: the shared Modal card with seven category chips and a detail box. Submit puts a negative judgment carrying the chosen category and the trimmed description, or neither. The same dialog opens for the Session from a bare `/feedback` — a decoration `ui-commands` routes as an `action` — and then records through `sessionFeedback.record`; `/feedback <text>` keeps the Host command path. Clicking a recorded rating retracts it.
+Either unrecorded rating opens the Session's feedback dialog, the `feedback-dialog` entry of `conversation.input.overlay`: the shared Modal card with seven category chips and a detail box. Submit puts the selected judgment carrying the chosen category and the trimmed description, or neither; success closes the dialog and shows the acknowledgement toast, while failure keeps the dialog and draft open and shows a warning toast. The same dialog opens for the Session from a bare `/feedback` — a decoration `ui-commands` routes as an `action` — and then records through `sessionFeedback.record`; `/feedback <text>` keeps the Host command path. Clicking a recorded rating retracts it without opening the dialog.
 
 ## Boundaries and limitations
 

package/kb/extra/subsystems/feedback.zh.md

@@ -27,7 +27,7 @@ interface MessageFeedbackItem {
   readonly rating: MessageFeedbackRating
   /** Optional explanation, preserved verbatim after validation. */
   readonly note?: string
-  /** Category the human filed a negative judgment under. */
+  /** Category the human filed the judgment under. */
   readonly category?: FeedbackCategory
   /** Equality-only token replaced by every material create or update. */
   readonly version: MessageFeedbackVersion
@@ -290,7 +290,7 @@ fork 种子可以包含父 Session 的反馈事件，但 payload 保留父级 `s
 
 插件释放会关闭操作接纳，并排空已进入各 Session 队列的工作。
 
-显式启用后，[`session-log-deepseek`](../../packages/session/session-log-deepseek/README.zh.md) 会在后续符合条件的 DeepSeek 请求中，把反馈作为普通 `dsh_session_log` 后缀的一部分传送。记录反馈不会触发 LLM 请求，也不会单独上传 `dsh_feedback`。对于非 DeepSeek 路由，[OTel 后端](../../packages/session/session-telemetry-otel/README.zh.md)可以将权威日志前缀释放至已记录的反馈。命令确认文本确认记录并标识 Session 与匿名用户，不报告遥测策略或投递结果。
+默认情况下，[`session-log-deepseek`](../../packages/session/session-log-deepseek/README.zh.md) 会在后续符合条件的 DeepSeek 请求中，把反馈作为普通 `dsh_session_log` 后缀的一部分传送；组合可用 `enabled: false` 禁用它。记录反馈不会触发 LLM 请求，也不会单独上传 `dsh_feedback`。对于非 DeepSeek 路由，[OTel 后端](../../packages/session/session-telemetry-otel/README.zh.md)可以将权威日志前缀释放至已记录的反馈。命令确认文本确认记录并标识 Session 与匿名用户，不报告遥测策略或投递结果。
 
 ## Web 界面
 
@@ -298,9 +298,9 @@ fork 种子可以包含父 Session 的反馈事件，但 payload 保留父级 `s
 
 控件是 `conversation.chat.assistant-actions` list slot 的 `feedback` 条目（order 10），该 slot 由 `ui-conversation` 声明，并渲染在已定稿助手消息的 IconActions 行内。`AssistantMessageNode` 携带来自 `assistant/message` 事件的可选 `messageId`。被中断冻结的部分输出没有该字段，渲染点在字段缺失时跳过该 slot。该操作栏每个 Turn 渲染一次，位于收尾的助手消息上：Host 接受每条 append-origin 步骤消息作为目标，但多步骤 Turn 中较早的步骤渲染的是工具行而非可评分正文，因此 UI 暴露的范围比 Host 约定允许的更窄。
 
-每个 Session 一个 `MessageFeedbackController`，支撑该 Session 内所有消息的控件：一次 `list` 读取即填充整段对话，且延迟到首次 hover 或 focus 才发起，而非挂载时触发。每次变更把该 controller 最后观察到的版本作为 `ifVersion` 发送；`version-conflict` 响应携带权威条目，controller 据此对账而不重新拉取。变更按 Session 串行，排队操作与已提交版本比较。`connection/reset` 只刷新已读取过的 Session。
+每个 Session 一个 `MessageFeedbackController`，支撑该 Session 内所有消息的控件：一次 `list` 读取即填充整段对话，且延迟到首次 hover 或 focus 才发起，而非挂载时触发。每次变更把该 controller 最后观察到的版本作为 `ifVersion` 发送；`version-conflict` 响应携带权威条目，controller 据此对账而不重新拉取。变更按 Session 串行，排队操作与已提交版本比较。注入的 `retract` 操作会在该队列内重新检查已提交评分，并在并发变更后变为无操作，因此陈旧 UI 无法绕过弹窗记录裸评分。`connection/reset` 只刷新已读取过的 Session。
 
-点赞立即记录不带备注的好评并显示确认 toast。点踩打开该 Session 的反馈弹窗，即 `conversation.input.overlay` 的 `feedback-dialog` 条目：共用的 Modal 卡片，里面是七个分类标签和一个详情框。提交会 put 一条差评，带上所选分类与去除首尾空白的描述，两者也可都不带。不带文本的 `/feedback`（`ui-commands` 以 `action` 路由的一个装饰）为 Session 打开同一个弹窗，随后通过 `sessionFeedback.record` 记录；`/feedback <text>` 仍走宿主命令路径。再次点击已记录的评分会撤回它。
+任一未记录的评分都会打开该 Session 的反馈弹窗，即 `conversation.input.overlay` 的 `feedback-dialog` 条目：共用的 Modal 卡片，里面是七个分类标签和一个详情框。提交会 put 所选评分，带上所选分类与去除首尾空白的描述，两者也可都不带；成功会关闭弹窗并显示确认 toast，失败则保留弹窗与草稿并显示警告 toast。不带文本的 `/feedback`（`ui-commands` 以 `action` 路由的一个装饰）为 Session 打开同一个弹窗，随后通过 `sessionFeedback.record` 记录；`/feedback <text>` 仍走宿主命令路径。再次点击已记录的评分会直接撤回，不打开弹窗。
 
 ## 边界与限制