瀏覽代碼

docs(tools): fix cross-module JSDoc links and the catalog source list

Codex review of the vocabulary relocation found two doc-accuracy issues:

- presentation.ts's JSDoc used {@link ToolDefinition...}, which the
  TypeScript language service cannot resolve because presentation.ts
  deliberately does not import index.ts (that would create the cycle the
  split avoids). Demote those three to plain `ToolDefinition` code text;
  same-file and imported @links (TerminalResultView, ContentBlock) stay.
- docs/core-data-structures/tools.md's source header listed only index.ts
  and schema.ts; add presentation.ts, which now owns the presentation
  vocabulary the page documents.
Tianyi Cui 2 月之前
父節點
當前提交
fb78a844af
共有 2 個文件被更改,包括 4 次插入4 次删除
  1. 1 1
      docs/core-data-structures/tools.md
  2. 3 3
      packages/core/tools/src/presentation.ts

+ 1 - 1
docs/core-data-structures/tools.md

@@ -2,7 +2,7 @@
 
 The tool pipeline of [dsh-tools](../../packages/core/tools). [core.md](core.md) introduces `ToolDefinition` as the one pipeline-authoring type promoted to the spine and `ToolSchema` as the model-facing wire shape. This page owns the full `ToolDefinition`, the typed schema DSL that builds it, the waterfall execution shapes, and the UI-presentation vocabulary.
 
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts) · [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts)
+Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts) · [`packages/core/tools/src/schema.ts`](../../packages/core/tools/src/schema.ts) · [`packages/core/tools/src/presentation.ts`](../../packages/core/tools/src/presentation.ts)
 
 ## `ToolDefinition` — a registered tool
 

+ 3 - 3
packages/core/tools/src/presentation.ts

@@ -1,6 +1,6 @@
 /**
  * Tool render-intent vocabulary: the provider-neutral types a tool declares via
- * {@link ToolDefinition.presentCall}/{@link ToolDefinition.presentResult} to say
+ * `ToolDefinition.presentCall`/`ToolDefinition.presentResult` to say
  * how ONE of its calls renders in a UI (an editor's tool-call card, a CLI log
  * line). A UI bridge switches on the `card` tag to map each intent to its own
  * wire shape, so a UI never special-cases tool names.
@@ -62,7 +62,7 @@ export interface FileDiff {
  * switches on `card` to map it to the bridge's own wire shape. Provider-neutral —
  * the tool owns its presentation, so a UI never special-cases tool names.
  *
- * Returned by {@link ToolDefinition.presentCall}. See the render-intent-union
+ * Returned by `ToolDefinition.presentCall`. See the render-intent-union
  * RFC (docs/rfc/implemented/architecture/2026-07-02-tool-render-intent-union.md).
  */
 export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView
@@ -144,7 +144,7 @@ export interface DiffCallView {
  * returns. A `card`-tagged union mirroring {@link ToolCallView}: a UI switches on
  * `card`. Lets the tool reformat its result for a UI distinctly from the
  * model-facing text it returned from `execute`. Returned by
- * {@link ToolDefinition.presentResult}; omitting the method keeps the pending
+ * `ToolDefinition.presentResult`; omitting the method keeps the pending
  * title and renders the raw result content.
  */
 export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView