Trim redundant source comments

2026-07-25 13:02:37 +08:00
parent f7b36bd36d
commit fac6c35e9a
83 changed files with 219 additions and 748 deletions
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -27,7 +27,7 @@ export interface AcpConfig {

 Depends on: `Stream` (`@agentclientprotocol/sdk`)

-Source: [`packages/ui/acp/src/index.ts:285`](../packages/ui/acp/src/index.ts)
+Source: [`packages/ui/acp/src/index.ts:275`](../packages/ui/acp/src/index.ts)

 ## `@deepseek-ai/dsh-acp-demo`

@@ -710,12 +710,12 @@ Source: [`packages/lsp/lsp-local/src/index.ts:85`](../packages/lsp/lsp-local/src
 Requires: `tools`

 ```ts config-catalog
-/** Discriminated union of all supported MCP transport configurations. */
+/** Configuration for one stdio or Streamable HTTP MCP server. */
 export type Config = StdioConfig | StreamableHttpConfig

 /** Config for connecting to an MCP server via a spawned child process over stdio. */
 export interface StdioConfig {
-  /** Transport type: spawn a child process and communicate over stdio. */
+  /** Selects child-process stdio transport. */
  transport: 'stdio'
  /**
   * Stable local namespace for this server's model-facing tool names
@@ -723,21 +723,21 @@ export interface StdioConfig {
   * unique across live mcp-client instances.
   */
  serverName: string
-  /** Executable to spawn. */
+  /** Executable used to start the server. */
  command: string
-  /** Arguments passed to the command. */
+  /** Arguments passed directly, without shell interpolation. */
  args: string[]
  /** Extra env vars merged on top of scrubbed ambient env. */
  env: Record<string, string>
  /** Working directory for the child process. */
  cwd: string
-  /** Timeout per callTool invocation (ms). */
+  /** Per-tool-call timeout in milliseconds. */
  toolCallTimeoutMs: number
 }

 /** Config for connecting to an MCP server over Streamable HTTP (SSE). */
 export interface StreamableHttpConfig {
-  /** Transport type: connect to an MCP server over Streamable HTTP (SSE). */
+  /** Selects Streamable HTTP transport. */
  transport: 'streamable-http'
  /**
   * Stable local namespace for this server's model-facing tool names
@@ -745,11 +745,11 @@ export interface StreamableHttpConfig {
   * unique across live mcp-client instances.
   */
  serverName: string
-  /** MCP server URL. */
+  /** MCP endpoint URL. */
  url: string
-  /** Extra headers (e.g. auth tokens). */
+  /** Additional headers attached to MCP requests. */
  headers: Record<string, string>
-  /** Timeout per callTool invocation (ms). */
+  /** Per-tool-call timeout in milliseconds. */
  toolCallTimeoutMs: number
 }
 ```
--- a/docs/core-data-structures/subagent.i18n.yaml
+++ b/docs/core-data-structures/subagent.i18n.yaml
@@ -2,5 +2,5 @@
 # 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
-subagent.md: 0335a3f0780ae17b57ae730f5a49a269261c8073
-subagent.zh.md: dac48b624f6e0cfc28737e3e1a2774ba2d97e85b
+subagent.md: fda4b4b738c648c893c65a633e4a0d6a1761424f
+subagent.zh.md: ba43789a3e4efe59b197f6454c977db52d90aca1
--- a/docs/core-data-structures/subagent.md
+++ b/docs/core-data-structures/subagent.md
@@ -22,13 +22,9 @@ A provider advertises its **start-time** features on a static descriptor the ser
 * is the capability.
 */
 interface SubagentCapabilities {
-  /** Honor {@link SubagentStartRequest.outputSchema} (structured final output). */
  readonly outputSchema: boolean
-  /** Enforce {@link SubagentStartRequest.maxDepth} (recursion cap). */
  readonly depthLimit: boolean
-  /** Enforce {@link SubagentStartRequest.toolFilter} (child tool scoping). */
  readonly toolFilter: boolean
-  /** Honor {@link SubagentStartRequest.persona} (a per-child persona). */
  readonly persona: boolean
 }
 ```
@@ -45,16 +41,11 @@ The tool layer builds this request from the model input and its own config; the
 * passes it to {@link SubagentProvider.start}.
 */
 interface SubagentStartRequest {
-  /** The task/prompt for the child agent (a user message in the child session). */
+  /** Content delivered as the child's user message. */
  readonly prompt: ContentBlock[]
  /**
-   * The spawning ("parent") agent — the one whose tool call started this
-   * subagent. REQUIRED: in-process backends read `parent.session.header` for
-   * the working directory, the `parentSession` lineage to stamp on the child,
-   * and the parent's delegation depth. The out-of-process backend (ACP) reads
-   * exactly one field — the session header's cwd, the child's workspace when
-   * no deployment `cwd` override is configured; nothing else crosses the
-   * process boundary.
+   * The spawning agent. In-process providers derive workspace, lineage, and
+   * delegation depth from its durable session state; ACP uses only its cwd.
   */
  readonly parent: Agent
  /**
@@ -65,7 +56,6 @@ interface SubagentStartRequest {
   * afterward.
   */
  readonly signal: AbortSignal
-  /** Per-child agent options (model and plugin-defined extension fields). */
  readonly agentOptions?: AgentOptions
  /**
   * Object-rooted JSON Schema within `assertObjectJsonSchema`'s enforced subset. Start rejects
@@ -135,15 +125,12 @@ interface SubagentResult {
 * non-`completed` result to an `isError` tool result.
 */
 interface SubagentStopReasonMap {
-  /** The child finished its turn normally. */
  completed: 'completed'
-  /** The run was cancelled by its request signal or by disposal. */
+  /** Cancelled through the request signal or disposal. */
  aborted: 'aborted'
-  /** The child failed (model error, transport error). */
+  /** Model or transport failure. */
  error: 'error'
-  /** The child hit its token ceiling before finishing. */
  'max-tokens': 'max-tokens'
-  /** The child declined the task. */
  refusal: 'refusal'
 }
 ```
@@ -180,9 +167,8 @@ interface SubagentRun {
   */
  readonly result: Promise<SubagentResult>
  /**
-   * Cancel remaining work, reach child quiescence, and release the run's
-   * resources (in-process: dispose the owned agent and remove its session;
-   * ACP: kill and reap the subprocess). Idempotent.
+   * Cancel remaining work, reach child quiescence, and release resources.
+   * Idempotent.
   */
  dispose(): Promise<void>
  /**
@@ -206,12 +192,9 @@ Each provider is a named child-agent transport, and multiple providers may coexi

 ```ts type-equiv
 /**
- * A subagent backend: one transport for running a child agent (in-process
- * spawn/fork, ACP to another process, …). Implementations register under a
- * unique name via {@link SubagentService.registerProvider}; multiple providers
- * coexist in one context (unlike the single-implementation bash seam). The
- * Providers are trusted same-process implementations; callers treat their
- * descriptors and returned values as borrowed immutable data.
+ * One registered transport for running child agents. Providers are trusted
+ * same-process implementations; callers treat descriptors and returned values
+ * as borrowed immutable data.
 */
 interface SubagentProvider {
  /** Unique registry name (e.g. `spawn`, `fork`, `acp`). */
--- a/docs/core-data-structures/subagent.zh.md
+++ b/docs/core-data-structures/subagent.zh.md
@@ -22,13 +22,9 @@ subagent seam：一个 agent（智能体）将工作委派给子 agent。与 [ba
 * is the capability.
 */
 interface SubagentCapabilities {
-  /** Honor {@link SubagentStartRequest.outputSchema} (structured final output). */
  readonly outputSchema: boolean
-  /** Enforce {@link SubagentStartRequest.maxDepth} (recursion cap). */
  readonly depthLimit: boolean
-  /** Enforce {@link SubagentStartRequest.toolFilter} (child tool scoping). */
  readonly toolFilter: boolean
-  /** Honor {@link SubagentStartRequest.persona} (a per-child persona). */
  readonly persona: boolean
 }
 ```
@@ -45,16 +41,11 @@ interface SubagentCapabilities {
 * passes it to {@link SubagentProvider.start}.
 */
 interface SubagentStartRequest {
-  /** The task/prompt for the child agent (a user message in the child session). */
+  /** Content delivered as the child's user message. */
  readonly prompt: ContentBlock[]
  /**
-   * The spawning ("parent") agent — the one whose tool call started this
-   * subagent. REQUIRED: in-process backends read `parent.session.header` for
-   * the working directory, the `parentSession` lineage to stamp on the child,
-   * and the parent's delegation depth. The out-of-process backend (ACP) reads
-   * exactly one field — the session header's cwd, the child's workspace when
-   * no deployment `cwd` override is configured; nothing else crosses the
-   * process boundary.
+   * The spawning agent. In-process providers derive workspace, lineage, and
+   * delegation depth from its durable session state; ACP uses only its cwd.
   */
  readonly parent: Agent
  /**
@@ -65,7 +56,6 @@ interface SubagentStartRequest {
   * afterward.
   */
  readonly signal: AbortSignal
-  /** Per-child agent options (model and plugin-defined extension fields). */
  readonly agentOptions?: AgentOptions
  /**
   * Object-rooted JSON Schema within `assertObjectJsonSchema`'s enforced subset. Start rejects
@@ -135,15 +125,12 @@ interface SubagentResult {
 * non-`completed` result to an `isError` tool result.
 */
 interface SubagentStopReasonMap {
-  /** The child finished its turn normally. */
  completed: 'completed'
-  /** The run was cancelled by its request signal or by disposal. */
+  /** Cancelled through the request signal or disposal. */
  aborted: 'aborted'
-  /** The child failed (model error, transport error). */
+  /** Model or transport failure. */
  error: 'error'
-  /** The child hit its token ceiling before finishing. */
  'max-tokens': 'max-tokens'
-  /** The child declined the task. */
  refusal: 'refusal'
 }
 ```
@@ -182,9 +169,8 @@ interface SubagentRun {
   */
  readonly result: Promise<SubagentResult>
  /**
-   * Cancel remaining work, reach child quiescence, and release the run's
-   * resources (in-process: dispose the owned agent and remove its session;
-   * ACP: kill and reap the subprocess). Idempotent.
+   * Cancel remaining work, reach child quiescence, and release resources.
+   * Idempotent.
   */
  dispose(): Promise<void>
  /**
@@ -208,12 +194,9 @@ interface SubagentRun {

 ```ts type-equiv
 /**
- * A subagent backend: one transport for running a child agent (in-process
- * spawn/fork, ACP to another process, …). Implementations register under a
- * unique name via {@link SubagentService.registerProvider}; multiple providers
- * coexist in one context (unlike the single-implementation bash seam). The
- * Providers are trusted same-process implementations; callers treat their
- * descriptors and returned values as borrowed immutable data.
+ * One registered transport for running child agents. Providers are trusted
+ * same-process implementations; callers treat descriptors and returned values
+ * as borrowed immutable data.
 */
 interface SubagentProvider {
  /** Unique registry name (e.g. `spawn`, `fork`, `acp`). */