dsh-plugin-dev-kb 1.3.0 → 1.4.0

package/kb/extra/subsystems/deliverables.md

@@ -0,0 +1,178 @@
+# Deliverables
+
+English | [中文](deliverables.zh.md)
+
+What a turn hands to the user, owned by the [deliverables package group](../../packages/deliverables/README.md): the files the model declared through the `present` tool, recorded in a log-only Session event, and the files the turn changed, summarized from git working-tree snapshots taken at turn start and turn end plus whole-file captures around each file-tool edit for the paths git does not cover, announced by a log-only event and served by a Host service while the Session lives together with each listed file's turn-start and turn-end comparison. Only clients read them; the Web [deliverables plugin](../../packages/client/ui-deliverables/README.md) renders both at the end of the turn. Tool behavior, snapshot mechanics, and configuration are on the package READMEs for [`tool-present`](../../packages/deliverables/tool-present/README.md) and [`workspace-changes`](../../packages/deliverables/workspace-changes/README.md).
+
+Sources: [`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` — one declared delivery
+
+```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` — one changed file
+
+```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` — one turn's change summary
+
+```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` — one 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` — one file's comparison
+
+```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` — the Host service serving summaries and comparisons
+
+```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>
+}
+```
+
+## Durable events and the served summary
+
+`tool-present` declaration-merges `deliverables/presented: { turn; callId; files: PresentedFile[] }` into `SessionEventMap`, appended once per successful final `present` result. `workspace-changes` merges `workspace/changes: { turn }`, appended when a top-level turn stops; the summary that event announced is not in the log but is returned by `workspaceChanges.summary(sessionId, seq)` for the event's sequence until the Session is disposed, so a conversation reopened after a Host restart has no changed-files card for its earlier turns. `workspaceChanges.diff(sessionId, seq, index, signal)` compares one listed file on the same terms. A later event for the same turn replaces the earlier one, so a client keeps only the latest. The generated [persistence catalog](../persistence-catalog.md#deliverablespresented--log-only) records both declaration sites. Neither event reaches the model.
+
+<!-- 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="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.md)
+
+Source: [`packages/deliverables/workspace-changes/src/types.ts`](../../packages/deliverables/workspace-changes/src/types.ts)
+<!-- END GENERATED cordis-surface -->

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>` 仍走宿主命令路径。再次点击已记录的评分会直接撤回，不打开弹窗。
 
 ## 边界与限制
 

package/kb/extra/subsystems/mcp.md

@@ -0,0 +1,139 @@
+# MCP
+
+English | [中文](mcp.zh.md)
+
+## Summary
+
+Model Context Protocol (MCP) connects the model to tools supplied by external servers. Each configured server contributes ordinary harness tools with cancellation, permission checks, recorded results, and supported image output. Shared tools discover and read resources when a server is configured in the caller's scope, while server instructions join the logged system prompt. The official SDK negotiates modern or supported legacy protocol revisions. This reference covers the MCP package group's responsibilities, scope, and composition choices; the [client README](../../packages/mcp/mcp-client/README.md) owns server configuration.
+
+## Table of Contents
+
+- [Configuration](#configuration)
+- [Responsibilities and scope](#responsibilities-and-scope)
+- [Protocol and results](#protocol-and-results)
+- [Resources and instructions](#resources-and-instructions)
+- [Resource provider types](#resource-provider-types)
+- [Limits](#limits)
+- [Further reading](#further-reading)
+
+-----
+
+<a id="configuration"></a>
+## Configuration
+
+MCP servers are opt-in. Configure one `@deepseek-ai/dsh-mcp-client` entry per server in the intended Cordis scope. Every shipped profile supplies the [tool registry](tools.md) and mounts the shared resource service once; users configure only client entries. Callers with no visible configured server receive no MCP prompt text or tools in native or PTC mode.
+
+| Choice | Configuration owner |
+|---|---|
+| Server identity, local process or HTTP endpoint, credentials, and process environment | [Client configuration](../../packages/mcp/mcp-client/README.md#use-this-package) |
+| Tool and resource request timeout, startup failure policy, and reconnection | [Client configuration](../../packages/mcp/mcp-client/README.md#use-this-package) |
+| Resource discovery and reading | The [MCP resource service](../../packages/mcp/mcp-resources/README.md#use-this-package) is included in shipped profiles; it has no configuration fields |
+| Server instruction size limit | Client `maxInstructionBytes`; the composition supplies [system-prompt assembly](system-prompt.md) |
+| Permission decisions and supported image output | [Tool execution](tools.md) and [attachments](attachment.md) |
+
+Protocol negotiation follows the SDK's supported revisions; there is no product setting that forces a protocol revision. The [configuration catalog](../config-catalog.md#deepseek-aidsh-mcp-client) lists accepted client fields and defaults.
+
+-----
+
+<a id="responsibilities-and-scope"></a>
+## Responsibilities and scope
+
+The client is a per-server connection plugin and a consumer of the harness tool registry. It does not publish a shared `ctx.mcp` service. The external server implements MCP operations; the SDK owns protocol exchange; the client adapts discovered tools to harness execution.
+
+`mcp-resources` owns the shared resource tools and selects providers in the caller's scope. Each MCP client supplies resource operations through its own connection. The first provider in a scope enables the local shared tools, and removing the last removes them; inherited providers remain visible. The service owns these tool registrations independently of any one client. Connection failures do not remove shared resource tools while a visible client entry remains active.
+
+Configured `serverName` identifies a server in its registration scope. Two entries in that scope cannot reserve the same name; separate Agent scopes can reuse it. Public tool names include the configured server name, so equally named tools from different servers remain distinct. Registration effects own names and discovered tools; plugin disposal closes the connection and removes its contributions.
+
+The [native Cua Driver provider](../../packages/experimental/computer-use-cua-driver-native/README.md) shares the client's exported result adapter without opening an MCP connection. Desktop provider selection belongs to the [computer-use subsystem](computer-use.md).
+
+-----
+
+<a id="protocol-and-results"></a>
+## Protocol and results
+
+Both stdio and Streamable HTTP use the official SDK's negotiation, discovery, protocol validation, and cancellation. Tool-list changes trigger discovery through legacy notifications or a modern subscription. A failed refresh retains the previous tool generation; connection recovery follows the [client lifecycle](../../packages/mcp/mcp-client/README.md#use-this-package).
+
+The result adapter retains canonical MCP JSON for programmatic callers and prepares ordinary tool content. Supported images use the attachment system; unsupported rich content produces explicit text diagnostics. The tool registry remains authoritative for policy failures and replaced results. The [tool contracts](tools.md) own recording and final presentation; the [client result reference](../../packages/mcp/mcp-client/README.md#use-this-package) owns MCP-specific projection details.
+
+-----
+
+<a id="resources-and-instructions"></a>
+## Resources and instructions
+
+Resource calls require an explicit configured server name. When system-prompt assembly is available, the resource service lists caller-visible names from the same registry used for dispatch, including servers with no tools or instructions. The shared registry resolves that name in the calling Agent's scope before dispatch; unavailable servers fail without a network request. Discovery and reads are on demand, including for servers that expose resources without tools. The [resource package](../../packages/mcp/mcp-resources/README.md) owns pagination and content rendering; its generated tool schemas live in the [tool catalog](../tool-catalog.md#deepseek-aidsh-mcp-resources).
+
+Resource providers remain connection-owned. Scope disposal removes registrations; the MCP client controls cancellation and recovery. Canonical results retain complete JSON for programmatic callers, while the text projection replaces binary blobs with descriptions. Returned text enters ordinary tool history; content is not fetched merely because a server connects.
+
+When system-prompt assembly is composed, the client publishes nonblank server instructions as a scoped, server-attributed section. Instructions remain literal text and pass the configured size limit before publication. A replacement connection publishes instructions only after discovery succeeds; absent instructions add no section. The [system-prompt subsystem](system-prompt.md) owns assembly and recording.
+
+-----
+
+<a id="resource-provider-types"></a>
+## Resource provider types
+
+The connection provider receives one operation and the original tool execution, including its caller and cancellation signal.
+
+```ts type-equiv
+/** One supported resource operation, with server-owned cursors and URIs. */
+type McpResourceRequest =
+  | { method: 'resources/list' | 'resources/templates/list'; cursor?: string }
+  | { method: 'resources/read'; uri: string }
+```
+
+```ts type-equiv
+/** One configured server's resource access, owned by its MCP connection plugin. */
+interface McpResourceProvider {
+  /**
+   * Run an operation against one live connection generation.
+   * @param request - MCP resource method and parameters.
+   * @param exec - caller identity and cancellation for this invocation.
+   * @returns the protocol result as lossless JSON.
+   */
+  request(request: McpResourceRequest, exec: ToolExecution): Promise<JsonValue>
+}
+```
+
+-----
+
+<a id="limits"></a>
+## Limits
+
+MCP prompt templates, human-input elicitation, task-based execution, and resource subscriptions are unsupported. Resource tools require a caller-visible configured server; binary resources remain programmatic data with text descriptions for the model. Servers without a tools capability connect with an empty tool set. Connection and discovery timeouts follow the SDK; the client has no separate settings for them.
+
+-----
+
+<a id="further-reading"></a>
+## Further reading
+
+- [MCP package group](../../packages/mcp/README.md) — package entry points.
+- [MCP resources](../../packages/mcp/mcp-resources/README.md) — shared tools and resource-provider semantics.
+- [Resource visibility reference](../../packages/mcp/mcp-resources/README.md) — shared profile mounting and visibility from configured servers.
+- [Third-party memory servers](../user/guide/mcp-memory.md) — product configuration guide.
+- [Protocol negotiation reference](../../packages/mcp/mcp-client/README.md) — SDK ownership and compatibility decisions.
+
+<!-- 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="ctxmcpresources--mcpresourceruntime"></a>
+
+### `ctx.mcpResources` — `McpResourceRuntime`
+
+Scoped resource access plus three tools shared by configured MCP servers.
+
+```ts cordis-catalog
+/**
+ * Register one server and expose resource tools while that scope has providers.
+ * @param server - configured server name, unique in this scope.
+ * @param provider - connection-owned resource operations.
+ * @returns the effect disposer for this exact registration.
+ */
+register(server: string, provider: McpResourceProvider): () => void
+```
+
+Source: [`packages/mcp/mcp-resources/src/index.ts`](../../packages/mcp/mcp-resources/src/index.ts)
+<!-- END GENERATED cordis-surface -->