From 614ffd5b4dc8abe8f4bbcd64a7570c219519771f Mon Sep 17 00:00:00 2001 From: Kevin Cui Date: Mon, 27 Jul 2026 13:01:38 -0400 Subject: [PATCH 1/2] refactor(output): standardize the JSON-only commands and retire the legacy exports - connector schema, llm config, and llm json declare output: "json-only": they gain the standard --format/--json/--show-schema-version options (connector schema's bespoke compat --json and its i18n key die), their dead format schema fields disappear, and telemetry now reports output_format "json" for every invocation instead of "text" on bare ones. connector schema also honors --show-schema-version, wrapping multi-action arrays per the shared conventions. - createFormatInputError is deleted from shared/input-parsing.ts (last callers were the JSON-only commands' catch-all mappers). - writeJsonOutput becomes private to command-output.ts; its envelope tests are rewritten against the emitJson interface. - docs/commands.md + docs/commands.zh-CN.md: connector schema Options and Output sections describe the standard flags and the array schemaVersion wrap. --- docs/commands.md | 8 +- docs/commands.zh-CN.md | 8 +- .../commands/command-output.test.ts | 169 +++++------------- src/application/commands/command-output.ts | 4 +- .../__snapshots__/index.cli.test.ts.snap | 7 +- .../commands/connector/index.cli.test.ts | 5 +- src/application/commands/connector/schema.ts | 14 +- src/application/commands/llm/config.ts | 24 +-- src/application/commands/llm/json.ts | 14 +- .../commands/shared/input-parsing.test.ts | 19 -- .../commands/shared/input-parsing.ts | 8 - src/i18n/catalog.ts | 4 - 12 files changed, 77 insertions(+), 207 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index 32c53f36..fd22d108 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -877,11 +877,15 @@ Show the stable schema contract for one or more connector actions. backwards compatibility; it accepts exactly one bare service name and rejects both additional positional arguments and the `.` form. - Options: `--refresh` fetches fresh metadata from the connector metadata API. -- Options: `--json` is accepted for compatibility and does not change output. +- Options: `--format ` and `--json` are accepted for consistency with + other commands; the command always prints JSON. `--show-schema-version` adds + the `schemaVersion` field following the shared JSON output conventions. - Output: for a single requested action, the command prints a JSON object with the stable CLI fields `service`, `name`, `description`, `inputSchema`, and `outputSchema`. For two or more requested actions, it prints a JSON array of - those objects in request order. + those objects in request order; with `--show-schema-version` the array is + wrapped as `{ "schemaVersion": "1.0.0", "items": [...] }` per the shared + conventions. - Notes: `--refresh` forces a fresh schema fetch for every selected action. - Notes: schemas cached by an earlier lookup or connector search are reused until they expire; use `--refresh` when the latest remote contract is diff --git a/docs/commands.zh-CN.md b/docs/commands.zh-CN.md index 7ea0f7b1..1cf4e39e 100644 --- a/docs/commands.zh-CN.md +++ b/docs/commands.zh-CN.md @@ -741,10 +741,14 @@ CLI 默认记录受隐私约束的命令使用 telemetry。事件不包含 free- 纯服务名。该旧写法为向后兼容而保留：只接受一个纯服务名，并会拒绝额外的 位置参数以及 `.` 形式。 - 选项：`--refresh` 会直接从 connector metadata API 获取最新 schema。 -- 选项：`--json` 作为兼容性选项被接受，不会改变输出。 +- 选项：`--format ` 与 `--json` 为与其他命令保持一致而接受；命令始终 + 输出 JSON。`--show-schema-version` 会按共享的 JSON 输出约定加入 + `schemaVersion` 字段。 - 输出：当只请求一个 action 时，命令输出 JSON 对象，包含稳定 CLI 字段 `service`、`name`、`description`、`inputSchema` 和 `outputSchema`；当请求两个 - 或更多 action 时，则按请求顺序输出这些对象组成的 JSON 数组。 + 或更多 action 时，则按请求顺序输出这些对象组成的 JSON 数组；指定 + `--show-schema-version` 时，数组会按共享约定包装为 + `{ "schemaVersion": "1.0.0", "items": [...] }`。 - 说明：`--refresh` 会强制为每个选中的 action 重新获取 schema。 - 说明：此前查询或 connector 搜索缓存的 schema 会在过期前被复用；需要 最新远端 contract 时请使用 `--refresh`。 diff --git a/src/application/commands/command-output.test.ts b/src/application/commands/command-output.test.ts index 7f58cc48..75f3357d 100644 --- a/src/application/commands/command-output.test.ts +++ b/src/application/commands/command-output.test.ts @@ -1,11 +1,11 @@ import { describe, expect, test } from "bun:test"; +import { createTextBuffer } from "../../../__tests__/helpers.ts"; import { CliUserError } from "../contracts/cli.ts"; import { createCommandOutput, JSON_OUTPUT_SCHEMA_VERSION, resolveOutputFormat, - writeJsonOutput, } from "./command-output.ts"; describe("resolveOutputFormat", () => { @@ -33,7 +33,7 @@ describe("createCommandOutput", () => { describe("without an output mode (inert handle)", () => { test("resolves to text and never validates", () => { const output = createCommandOutput( - createCollectingWriter([]), + createTextBuffer().writer, { format: "yaml", json: true }, undefined, ); @@ -49,7 +49,7 @@ describe("createCommandOutput", () => { { expected: "json", optionValues: { json: true }, title: "--json" }, ])("$title -> $expected", ({ expected, optionValues }) => { const output = createCommandOutput( - createCollectingWriter([]), + createTextBuffer().writer, optionValues, "standard", ); @@ -59,13 +59,13 @@ describe("createCommandOutput", () => { test("rejects an invalid --format value with the shared error", () => { expect(() => createCommandOutput( - createCollectingWriter([]), + createTextBuffer().writer, { format: "yaml" }, "standard", )).toThrow(CliUserError); try { - createCommandOutput(createCollectingWriter([]), { format: "yaml" }, "standard"); + createCommandOutput(createTextBuffer().writer, { format: "yaml" }, "standard"); } catch (error) { expect(error).toBeInstanceOf(CliUserError); @@ -78,14 +78,14 @@ describe("createCommandOutput", () => { describe("json-only mode", () => { test("pins format to json without any flags", () => { - const output = createCommandOutput(createCollectingWriter([]), {}, "json-only"); + const output = createCommandOutput(createTextBuffer().writer, {}, "json-only"); expect(output.format).toBe("json"); }); test("accepts --format json", () => { const output = createCommandOutput( - createCollectingWriter([]), + createTextBuffer().writer, { format: "json" }, "json-only", ); @@ -95,7 +95,7 @@ describe("createCommandOutput", () => { test("still rejects an invalid --format value", () => { expect(() => createCommandOutput( - createCollectingWriter([]), + createTextBuffer().writer, { format: "yaml" }, "json-only", )).toThrow(CliUserError); @@ -104,9 +104,9 @@ describe("createCommandOutput", () => { describe("emit", () => { test("writes the JSON payload and skips renderText in json mode", () => { - const chunks: string[] = []; + const stdout = createTextBuffer(); const output = createCommandOutput( - createCollectingWriter(chunks), + stdout.writer, { format: "json" }, "standard", ); @@ -116,14 +116,14 @@ describe("createCommandOutput", () => { textRendered = true; }); - expect(chunks.join("")).toBe(`{"ok":true}\n`); + expect(stdout.read()).toBe(`{"ok":true}\n`); expect(textRendered).toBe(false); }); test("calls renderText and writes no JSON in text mode", () => { - const chunks: string[] = []; + const stdout = createTextBuffer(); const output = createCommandOutput( - createCollectingWriter(chunks), + stdout.writer, {}, "standard", ); @@ -133,163 +133,86 @@ describe("createCommandOutput", () => { textRendered = true; }); - expect(chunks).toEqual([]); + expect(stdout.read()).toBe(""); expect(textRendered).toBe(true); }); }); describe("emitJson", () => { test("applies the schemaVersion envelope captured from the options", () => { - const chunks: string[] = []; - const output = createCommandOutput( - createCollectingWriter(chunks), - { format: "json", showSchemaVersion: true }, - "standard", - ); - - output.emitJson({ taskID: "task-1" }); - - expect(JSON.parse(chunks.join(""))).toEqual({ + expect(JSON.parse(emitJsonThrough({ taskID: "task-1" }, { + showSchemaVersion: true, + }))).toEqual({ schemaVersion: JSON_OUTPUT_SCHEMA_VERSION, taskID: "task-1", }); }); test("wraps array payloads under items when the envelope is on", () => { - const chunks: string[] = []; - const output = createCommandOutput( - createCollectingWriter(chunks), - { json: true, showSchemaVersion: true }, - "standard", - ); - - output.emitJson([1, 2]); - - expect(JSON.parse(chunks.join(""))).toEqual({ + expect(JSON.parse(emitJsonThrough([1, 2], { + json: true, + showSchemaVersion: true, + }))).toEqual({ schemaVersion: JSON_OUTPUT_SCHEMA_VERSION, items: [1, 2], }); }); test("writes bare JSON without --show-schema-version", () => { - const chunks: string[] = []; - const output = createCommandOutput( - createCollectingWriter(chunks), - { format: "json" }, - "standard", - ); - - output.emitJson([1, 2]); - - expect(chunks.join("")).toBe(`[1,2]\n`); + expect(emitJsonThrough([1, 2])).toBe(`[1,2]\n`); }); test("ignores a non-boolean showSchemaVersion value", () => { - const chunks: string[] = []; - const output = createCommandOutput( - createCollectingWriter(chunks), - { format: "json", showSchemaVersion: "yes" }, - "standard", - ); - - output.emitJson({ ok: true }); - - expect(chunks.join("")).toBe(`{"ok":true}\n`); + expect(emitJsonThrough({ ok: true }, { showSchemaVersion: "yes" })) + .toBe(`{"ok":true}\n`); }); }); }); -describe("writeJsonOutput", () => { +describe("emitJson envelope", () => { test("emits compact JSON with a trailing newline by default", () => { - const chunks: string[] = []; - const writer = createCollectingWriter(chunks); - - writeJsonOutput(writer, { taskID: "task-1" }); - - expect(chunks.join("")).toBe(`{"taskID":"task-1"}\n`); - }); - - test("omits schemaVersion when showSchemaVersion is not set", () => { - const chunks: string[] = []; - const writer = createCollectingWriter(chunks); - - writeJsonOutput(writer, { taskID: "task-1" }, { - showSchemaVersion: false, - }); - - expect(chunks.join("")).toBe(`{"taskID":"task-1"}\n`); + expect(emitJsonThrough({ taskID: "task-1" })).toBe(`{"taskID":"task-1"}\n`); }); - test("merges schemaVersion into object payloads", () => { - const chunks: string[] = []; - const writer = createCollectingWriter(chunks); - - writeJsonOutput(writer, { taskID: "task-1" }, { - showSchemaVersion: true, - }); - - expect(JSON.parse(chunks.join(""))).toEqual({ - schemaVersion: JSON_OUTPUT_SCHEMA_VERSION, - taskID: "task-1", - }); + test("omits schemaVersion when showSchemaVersion is false", () => { + expect(emitJsonThrough({ taskID: "task-1" }, { showSchemaVersion: false })) + .toBe(`{"taskID":"task-1"}\n`); }); test("places schemaVersion before object properties", () => { - const chunks: string[] = []; - const writer = createCollectingWriter(chunks); - - writeJsonOutput(writer, { taskID: "task-1" }, { - showSchemaVersion: true, - }); - - expect(chunks.join("")).toBe( + expect(emitJsonThrough({ taskID: "task-1" }, { showSchemaVersion: true })).toBe( `{"schemaVersion":"${JSON_OUTPUT_SCHEMA_VERSION}","taskID":"task-1"}\n`, ); }); - test("wraps array payloads under items", () => { - const chunks: string[] = []; - const writer = createCollectingWriter(chunks); - - writeJsonOutput(writer, [1, 2, 3], { showSchemaVersion: true }); - - expect(JSON.parse(chunks.join(""))).toEqual({ - schemaVersion: JSON_OUTPUT_SCHEMA_VERSION, - items: [1, 2, 3], - }); - }); - test("forces schemaVersion to override any existing field on objects", () => { - const chunks: string[] = []; - const writer = createCollectingWriter(chunks); - - writeJsonOutput(writer, { schemaVersion: "2.0.0", value: 1 }, { + expect(JSON.parse(emitJsonThrough({ schemaVersion: "2.0.0", value: 1 }, { showSchemaVersion: true, - }); - - expect(JSON.parse(chunks.join(""))).toEqual({ + }))).toEqual({ schemaVersion: JSON_OUTPUT_SCHEMA_VERSION, value: 1, }); }); test("wraps primitive payloads under value", () => { - const chunks: string[] = []; - const writer = createCollectingWriter(chunks); - - writeJsonOutput(writer, null, { showSchemaVersion: true }); - - expect(JSON.parse(chunks.join(""))).toEqual({ + expect(JSON.parse(emitJsonThrough(null, { showSchemaVersion: true }))).toEqual({ schemaVersion: JSON_OUTPUT_SCHEMA_VERSION, value: null, }); }); }); -function createCollectingWriter(chunks: string[]): { write: (chunk: string) => void } { - return { - write: (chunk: string) => { - chunks.push(chunk); - }, - }; +function emitJsonThrough( + payload: unknown, + optionValues: { json?: unknown; showSchemaVersion?: unknown } = {}, +): string { + const stdout = createTextBuffer(); + + createCommandOutput( + stdout.writer, + { format: "json", ...optionValues }, + "standard", + ).emitJson(payload); + + return stdout.read(); } diff --git a/src/application/commands/command-output.ts b/src/application/commands/command-output.ts index f99e9a92..26f8463b 100644 --- a/src/application/commands/command-output.ts +++ b/src/application/commands/command-output.ts @@ -108,11 +108,11 @@ function resolveStrictOutputFormat( return mode === "json-only" ? "json" : resolveOutputFormat(optionValues); } -export interface WriteJsonOutputOptions { +interface WriteJsonOutputOptions { showSchemaVersion?: boolean | undefined; } -export function writeJsonOutput( +function writeJsonOutput( writer: Writer, value: unknown, options: WriteJsonOutputOptions = {}, diff --git a/src/application/commands/connector/__snapshots__/index.cli.test.ts.snap b/src/application/commands/connector/__snapshots__/index.cli.test.ts.snap index dfee0f89..f5e7c0fd 100644 --- a/src/application/commands/connector/__snapshots__/index.cli.test.ts.snap +++ b/src/application/commands/connector/__snapshots__/index.cli.test.ts.snap @@ -107,7 +107,7 @@ Global Options: } `; -exports[`connectorCommand CLI renders connector schema help with the json compatibility option 1`] = ` +exports[`connectorCommand CLI renders connector schema help with the standard output options 1`] = ` { "exitCode": 0, "stderr": "", @@ -121,7 +121,10 @@ Arguments: Options: -a, --action Specify the target action name --refresh Bypass any cached response and fetch fresh data - --json Accepted for compatibility; output is always JSON + --format Specify output format (use json for structured output) + --json Alias for --format=json + --show-schema-version Include schemaVersion in JSON output (no effect without + --json) -h, --help Show help for command Global Options: diff --git a/src/application/commands/connector/index.cli.test.ts b/src/application/commands/connector/index.cli.test.ts index b31e6171..60c447ea 100644 --- a/src/application/commands/connector/index.cli.test.ts +++ b/src/application/commands/connector/index.cli.test.ts @@ -496,15 +496,16 @@ describe("connectorCommand CLI", () => { } }); - test("renders connector schema help with the json compatibility option", async () => { + test("renders connector schema help with the standard output options", async () => { const sandbox = await createCliSandbox(); try { const result = await sandbox.run(["connector", "schema", "--help"]); expect(createCliSnapshot(result)).toMatchSnapshot(); - expect(result.stdout).not.toContain("--format"); + expect(result.stdout).toContain("--format"); expect(result.stdout).toContain("--json"); + expect(result.stdout).toContain("--show-schema-version"); } finally { await sandbox.cleanup(); diff --git a/src/application/commands/connector/schema.ts b/src/application/commands/connector/schema.ts index 63626df0..de77b3a6 100644 --- a/src/application/commands/connector/schema.ts +++ b/src/application/commands/connector/schema.ts @@ -4,8 +4,6 @@ import type { ConnectorActionMetadata } from "./shared.ts"; import { z } from "zod"; import { CliUserError } from "../../contracts/cli.ts"; import { bucketTelemetryCount } from "../../telemetry/buckets.ts"; -import { writeJsonOutput } from "../command-output.ts"; -import { createFormatInputError } from "../shared/input-parsing.ts"; import { loadConnectorActionSchema } from "./schema-cache.ts"; import { connectorSchemaRefreshCommand } from "./schema-refresh.ts"; import { requireConnectorActionName } from "./shared.ts"; @@ -51,18 +49,13 @@ export const connectorSchemaCommand: CliCommandDefinition longFlag: "--refresh", descriptionKey: "options.refresh", }, - { - name: "json", - longFlag: "--json", - descriptionKey: "options.connectorSchemaJson", - }, ], + output: "json-only", inputSchema: z.object({ action: z.string().optional(), actionId: z.array(z.string()).optional(), refresh: z.boolean().optional(), }), - mapInputError: (_, rawInput) => createFormatInputError(rawInput), handler: async (input, context) => { const actionIds = input.actionId ?? []; const targets = input.action === undefined @@ -102,10 +95,7 @@ export const connectorSchemaCommand: CliCommandDefinition // A single requested action keeps the historical object shape; two or // more actions widen the output to an array in request order. - writeJsonOutput( - context.stdout, - outputs.length === 1 ? outputs[0]! : outputs, - ); + context.output.emitJson(outputs.length === 1 ? outputs[0]! : outputs); }, }; diff --git a/src/application/commands/llm/config.ts b/src/application/commands/llm/config.ts index f71fc1b3..51767673 100644 --- a/src/application/commands/llm/config.ts +++ b/src/application/commands/llm/config.ts @@ -2,17 +2,9 @@ import type { CliCommandDefinition } from "../../contracts/cli.ts"; import { z } from "zod"; import { requireIdentity } from "../../auth/identity.ts"; -import { outputFormatOptions, writeJsonOutput } from "../command-output.ts"; -import { createFormatInputError } from "../shared/input-parsing.ts"; -const llmConfigFormatValues = ["json"] as const; export const defaultLlmModel = "oomol-chat"; -interface LlmConfigInput { - format?: (typeof llmConfigFormatValues)[number]; - showSchemaVersion?: boolean; -} - interface LlmConfigOutput { apiKey: string; baseUrl: string; @@ -20,18 +12,14 @@ interface LlmConfigOutput { model: string; } -export const llmConfigCommand: CliCommandDefinition = { +export const llmConfigCommand: CliCommandDefinition = { name: "config", excludeFromTelemetry: true, summaryKey: "commands.llm.config.summary", descriptionKey: "commands.llm.config.description", - options: [...outputFormatOptions], - inputSchema: z.object({ - format: z.enum(llmConfigFormatValues).optional(), - showSchemaVersion: z.boolean().optional(), - }), - mapInputError: (_, rawInput) => createFormatInputError(rawInput), - handler: async (input, context) => { + output: "json-only", + inputSchema: z.object({}), + handler: async (_input, context) => { const { account } = await requireIdentity(context); const baseUrl = createLlmBaseUrl(account.endpoint); const config: LlmConfigOutput = { @@ -41,9 +29,7 @@ export const llmConfigCommand: CliCommandDefinition = { model: defaultLlmModel, }; - writeJsonOutput(context.stdout, config, { - showSchemaVersion: input.showSchemaVersion, - }); + context.output.emitJson(config); }, }; diff --git a/src/application/commands/llm/json.ts b/src/application/commands/llm/json.ts index f972a0ff..1c785fd5 100644 --- a/src/application/commands/llm/json.ts +++ b/src/application/commands/llm/json.ts @@ -5,8 +5,6 @@ import { resolve } from "node:path"; import { z } from "zod"; import { requireIdentity } from "../../auth/identity.ts"; import { CliUserError } from "../../contracts/cli.ts"; -import { outputFormatOptions, writeJsonOutput } from "../command-output.ts"; -import { createFormatInputError } from "../shared/input-parsing.ts"; import { readJsonInputValue } from "../shared/json-input.ts"; import { compileJsonSchema, @@ -19,7 +17,6 @@ import { defaultLlmModel, } from "./config.ts"; -const llmJsonFormatValues = ["json"] as const; const defaultMaxRetries = 2; const maxAllowedRetries = 5; @@ -44,12 +41,10 @@ const chatCompletionResponseSchema = z.object({ }).passthrough(); interface LlmJsonInput { - format?: (typeof llmJsonFormatValues)[number]; input?: string; maxRetries?: string; model?: string; schema?: string; - showSchemaVersion?: boolean; system?: string; } @@ -95,18 +90,15 @@ export const llmJsonCommand: CliCommandDefinition = { valueName: "model", descriptionKey: "options.model", }, - ...outputFormatOptions, ], + output: "json-only", inputSchema: z.object({ - format: z.enum(llmJsonFormatValues).optional(), input: z.string().optional(), maxRetries: z.string().optional(), model: z.string().optional(), schema: z.string().optional(), - showSchemaVersion: z.boolean().optional(), system: z.string().optional(), }), - mapInputError: (_, rawInput) => createFormatInputError(rawInput), handler: async (input, context) => { const { account } = await requireIdentity(context); const schema = await readRequiredJsonSchema(input.schema, context); @@ -147,9 +139,7 @@ export const llmJsonCommand: CliCommandDefinition = { ok: true, }; - writeJsonOutput(context.stdout, output, { - showSchemaVersion: input.showSchemaVersion, - }); + context.output.emitJson(output); }, }; diff --git a/src/application/commands/shared/input-parsing.test.ts b/src/application/commands/shared/input-parsing.test.ts index 69028945..4fd6019e 100644 --- a/src/application/commands/shared/input-parsing.test.ts +++ b/src/application/commands/shared/input-parsing.test.ts @@ -1,8 +1,6 @@ import { describe, expect, test } from "bun:test"; -import { CliUserError } from "../../contracts/cli.ts"; import { - createFormatInputError, parseEnumOption, parsePositiveIntegerOption, } from "./input-parsing.ts"; @@ -78,20 +76,3 @@ describe("parsePositiveIntegerOption", () => { ).toBe(100); }); }); - -describe("createFormatInputError", () => { - test("returns a CliUserError with the format value", () => { - const error = createFormatInputError({ format: "yaml" }); - - expect(error).toBeInstanceOf(CliUserError); - expect(error.exitCode).toBe(2); - expect(error.key).toBe("errors.shared.invalidFormat"); - expect(error.params).toEqual({ value: "yaml" }); - }); - - test("uses empty string when format is missing", () => { - const error = createFormatInputError({}); - - expect(error.params).toEqual({ value: "" }); - }); -}); diff --git a/src/application/commands/shared/input-parsing.ts b/src/application/commands/shared/input-parsing.ts index 92386c99..5f308d8a 100644 --- a/src/application/commands/shared/input-parsing.ts +++ b/src/application/commands/shared/input-parsing.ts @@ -53,11 +53,3 @@ export function parsePositiveIntegerOption( return parsedValue; } - -export function createFormatInputError( - rawInput: Record, -): CliUserError { - return new CliUserError("errors.shared.invalidFormat", 2, { - value: String(rawInput.format ?? ""), - }); -} diff --git a/src/i18n/catalog.ts b/src/i18n/catalog.ts index fdcfdb55..0917c0f5 100644 --- a/src/i18n/catalog.ts +++ b/src/i18n/catalog.ts @@ -976,8 +976,6 @@ export const enMessages = { "options.json": "Alias for --format=json", "options.showSchemaVersion": "Include schemaVersion in JSON output (no effect without --json)", - "options.connectorSchemaJson": - "Accepted for compatibility; output is always JSON", "options.keywords": "Specify comma-separated keywords to refine the skill search", "options.maxRetries": "Maximum retry count", @@ -2280,8 +2278,6 @@ export const zhMessages = { "options.json": "--format=json 的别名", "options.showSchemaVersion": "在 JSON 输出中加入 schemaVersion 字段（未指定 --json 时无效）", - "options.connectorSchemaJson": - "兼容性选项；输出始终是 JSON", "options.keywords": "指定用于细化 skill 搜索的逗号分隔关键词", "options.maxRetries": "最大重试次数", From 5762cb7f041f7033bc96ba816c64b39d0cdab6da Mon Sep 17 00:00:00 2001 From: Kevin Cui Date: Mon, 27 Jul 2026 19:15:41 -0400 Subject: [PATCH 2/2] docs(connector): document the single-action schemaVersion merge for connector schema --- docs/commands.md | 9 +++++---- docs/commands.zh-CN.md | 7 ++++--- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index fd22d108..79fe0f22 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -882,10 +882,11 @@ Show the stable schema contract for one or more connector actions. the `schemaVersion` field following the shared JSON output conventions. - Output: for a single requested action, the command prints a JSON object with the stable CLI fields `service`, `name`, `description`, `inputSchema`, and - `outputSchema`. For two or more requested actions, it prints a JSON array of - those objects in request order; with `--show-schema-version` the array is - wrapped as `{ "schemaVersion": "1.0.0", "items": [...] }` per the shared - conventions. + `outputSchema`; with `--show-schema-version` the object gains a top-level + `schemaVersion` field. For two or more requested actions, it prints a JSON + array of those objects in request order; with `--show-schema-version` the + array is wrapped as `{ "schemaVersion": "1.0.0", "items": [...] }` per the + shared conventions. - Notes: `--refresh` forces a fresh schema fetch for every selected action. - Notes: schemas cached by an earlier lookup or connector search are reused until they expire; use `--refresh` when the latest remote contract is diff --git a/docs/commands.zh-CN.md b/docs/commands.zh-CN.md index 1cf4e39e..fa5b66e5 100644 --- a/docs/commands.zh-CN.md +++ b/docs/commands.zh-CN.md @@ -745,9 +745,10 @@ CLI 默认记录受隐私约束的命令使用 telemetry。事件不包含 free- 输出 JSON。`--show-schema-version` 会按共享的 JSON 输出约定加入 `schemaVersion` 字段。 - 输出：当只请求一个 action 时，命令输出 JSON 对象，包含稳定 CLI 字段 - `service`、`name`、`description`、`inputSchema` 和 `outputSchema`；当请求两个 - 或更多 action 时，则按请求顺序输出这些对象组成的 JSON 数组；指定 - `--show-schema-version` 时，数组会按共享约定包装为 + `service`、`name`、`description`、`inputSchema` 和 `outputSchema`，指定 + `--show-schema-version` 时该对象会获得顶层 `schemaVersion` 字段；当请求两个 + 或更多 action 时，则按请求顺序输出这些对象组成的 JSON 数组，指定 + `--show-schema-version` 时数组会按共享约定包装为 `{ "schemaVersion": "1.0.0", "items": [...] }`。 - 说明：`--refresh` 会强制为每个选中的 action 重新获取 schema。 - 说明：此前查询或 connector 搜索缓存的 schema 会在过期前被复用；需要