@yosai/cli 0.0.0-stage → 0.2.0

package/dist/commands/index.js

@@ -0,0 +1,10 @@
+import './login.js';
+import './doctor.js';
+import './ping.js';
+import './tool.js';
+import './domain.js';
+import './docs-download.js';
+import './kb.js';
+import './skill.js';
+import './version.js';
+import './update.js';

package/dist/commands/kb-upload.js

@@ -0,0 +1,210 @@
+import { readdir } from 'node:fs/promises';
+import { join, basename, dirname } from 'node:path';
+export function buildPathIndex(nodes, prefix = '') {
+    const index = new Map();
+    for (const node of nodes) {
+        const path = prefix ? `${prefix}/${node.name}` : node.name;
+        index.set(path, { code: node.resourceCode, type: node.resourceType });
+        if (node.children && node.children.length > 0) {
+            for (const [childPath, value] of buildPathIndex(node.children, path)) {
+                index.set(childPath, value);
+            }
+        }
+    }
+    return index;
+}
+export function findSubtreeChildren(root, dirCode) {
+    const children = root.children ?? [];
+    if (!dirCode) {
+        return children;
+    }
+    const queue = [...children];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        if (node.resourceCode === dirCode) {
+            return node.children ?? [];
+        }
+        if (node.children) {
+            queue.push(...node.children);
+        }
+    }
+    return [];
+}
+export function targetDirPath(baseName, relDir) {
+    return relDir ? `${baseName}/${relDir}` : baseName;
+}
+export function sortDirsByDepth(dirs) {
+    return [...dirs].sort((a, b) => depthOf(a) - depthOf(b) || a.localeCompare(b));
+}
+function depthOf(relDir) {
+    return relDir === '' ? 0 : relDir.split('/').length;
+}
+export function resolveRename(name, taken) {
+    if (!taken.has(name)) {
+        return name;
+    }
+    const dot = name.lastIndexOf('.');
+    const base = dot > 0 ? name.slice(0, dot) : name;
+    const ext = dot > 0 ? name.slice(dot) : '';
+    let seq = 1;
+    while (taken.has(`${base} (${seq})${ext}`)) {
+        seq += 1;
+    }
+    return `${base} (${seq})${ext}`;
+}
+export function decideSingleFileUpload(name, siblingNames, onConflict) {
+    const taken = new Set(siblingNames);
+    if (!taken.has(name)) {
+        return { action: 'upload', finalName: name };
+    }
+    if (onConflict === 'skip') {
+        return { action: 'skip' };
+    }
+    if (onConflict === undefined) {
+        return { action: 'abort' };
+    }
+    return { action: 'upload', finalName: resolveRename(name, taken) };
+}
+export async function walkLocalDir(root) {
+    const dirs = [''];
+    const files = [];
+    await walkInto(root, '', dirs, files);
+    return { dirs, files };
+}
+async function walkInto(absDir, relDir, dirs, files) {
+    const entries = await readdir(absDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name.startsWith('.')) {
+            continue;
+        }
+        const childRel = relDir ? `${relDir}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            dirs.push(childRel);
+            await walkInto(join(absDir, entry.name), childRel, dirs, files);
+        }
+        else if (entry.isFile()) {
+            files.push({ relDir, name: entry.name, absPath: join(absDir, entry.name) });
+        }
+    }
+}
+export async function uploadDirectory(deps, opts) {
+    const baseName = basename(opts.localRoot);
+    const summary = {
+        kbCode: opts.kbCode,
+        targetDir: opts.dirCode ?? null,
+        foldersCreated: [],
+        foldersReused: [],
+        uploaded: [],
+        renamed: [],
+        skipped: [],
+        failed: [],
+        conflicts: [],
+    };
+    const local = await deps.walk(opts.localRoot);
+    let index = buildPathIndex(findSubtreeChildren(await deps.fetchTree(opts.kbCode), opts.dirCode));
+    const conflicts = local.files.filter((file) => {
+        const path = `${targetDirPath(baseName, file.relDir)}/${file.name}`;
+        return index.has(path);
+    });
+    summary.conflicts = conflicts.map((file) => `${targetDirPath(baseName, file.relDir)}/${file.name}`);
+    if (conflicts.length > 0 && !opts.onConflict) {
+        return { exitCode: 1, aborted: true, summary };
+    }
+    const takenByParent = collectTakenNames(local.files, index, baseName);
+    const pending = [];
+    for (const file of local.files) {
+        const parentPath = targetDirPath(baseName, file.relDir);
+        const isConflict = index.has(`${parentPath}/${file.name}`);
+        if (!isConflict) {
+            pending.push({ file, finalName: file.name, parentPath });
+            continue;
+        }
+        if (opts.onConflict === 'skip') {
+            summary.skipped.push(`${parentPath}/${file.name}`);
+            continue;
+        }
+        const taken = takenByParent.get(parentPath) ?? new Set();
+        const finalName = resolveRename(file.name, taken);
+        taken.add(finalName);
+        pending.push({ file, finalName, parentPath });
+    }
+    await ensureFolders(deps, opts, baseName, local.dirs, index, summary);
+    index = buildPathIndex(findSubtreeChildren(await deps.fetchTree(opts.kbCode), opts.dirCode));
+    await uploadPendingFiles(deps, opts, pending, index, summary);
+    return { exitCode: summary.failed.length > 0 ? 1 : 0, aborted: false, summary };
+}
+function collectTakenNames(files, index, baseName) {
+    const taken = new Map();
+    const add = (parentPath, name) => {
+        if (!taken.has(parentPath)) {
+            taken.set(parentPath, new Set());
+        }
+        taken.get(parentPath)?.add(name);
+    };
+    for (const path of index.keys()) {
+        const parent = dirname(path);
+        add(parent, path.slice(parent.length + 1));
+    }
+    for (const file of files) {
+        add(targetDirPath(baseName, file.relDir), file.name);
+    }
+    return taken;
+}
+async function ensureFolders(deps, opts, baseName, dirs, index, summary) {
+    const sorted = sortDirsByDepth(dirs);
+    const maxDepth = sorted.length > 0 ? depthOf(sorted[sorted.length - 1]) : 0;
+    for (let depth = 0; depth <= maxDepth; depth += 1) {
+        const level = sorted.filter((relDir) => depthOf(relDir) === depth);
+        let createdAny = false;
+        for (const relDir of level) {
+            const path = targetDirPath(baseName, relDir);
+            if (index.get(path)?.type === 'folder') {
+                summary.foldersReused.push(path);
+                continue;
+            }
+            const folderName = depth === 0 ? baseName : relDir.slice(relDir.lastIndexOf('/') + 1);
+            const parentCode = depth === 0 ? opts.dirCode : index.get(dirname(path))?.code;
+            await deps.mkdir(folderName, opts.kbCode, parentCode);
+            summary.foldersCreated.push(path);
+            createdAny = true;
+        }
+        if (createdAny) {
+            replaceIndex(index, buildPathIndex(findSubtreeChildren(await deps.fetchTree(opts.kbCode), opts.dirCode)));
+        }
+    }
+}
+function replaceIndex(target, source) {
+    target.clear();
+    for (const [key, value] of source) {
+        target.set(key, value);
+    }
+}
+async function uploadPendingFiles(deps, opts, pending, index, summary) {
+    const total = pending.length;
+    let seq = 0;
+    for (const item of pending) {
+        seq += 1;
+        const label = `${item.parentPath}/${item.finalName}`;
+        const parentCode = index.get(item.parentPath)?.code;
+        if (!parentCode) {
+            summary.failed.push({ name: label, error: `目标文件夹未就绪：${item.parentPath}` });
+            deps.log(`[${seq}/${total}] ${label} 失败：目标文件夹未就绪`);
+            continue;
+        }
+        try {
+            const result = await deps.uploadFile(item.file.absPath, opts.kbCode, parentCode, item.finalName);
+            if (item.finalName !== item.file.name) {
+                summary.renamed.push({ from: item.file.name, to: item.finalName, nodeCode: result.nodeCode });
+            }
+            else {
+                summary.uploaded.push({ name: item.file.name, nodeCode: result.nodeCode, fileSize: result.fileSize });
+            }
+            deps.log(`[${seq}/${total}] ${label} → ${result.nodeCode}`);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            summary.failed.push({ name: label, error: message });
+            deps.log(`[${seq}/${total}] ${label} 失败：${message}`);
+        }
+    }
+}

package/dist/commands/kb.js

@@ -0,0 +1,165 @@
+import { stat } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { register } from '../cli.js';
+import { loadConfig, resolveEndpoint, resolveKey } from '../config.js';
+import { BusinessError, EXIT, UsageError } from '../errors.js';
+import { uploadKnowledgeFile } from '../openapis-client.js';
+import { print, printErr, printJson } from '../output.js';
+import { clientFromConfig } from './context.js';
+import { decideSingleFileUpload, findSubtreeChildren, uploadDirectory, walkLocalDir, } from './kb-upload.js';
+const CONFLICT_POLICIES = ['skip', 'rename'];
+register({
+    name: 'kb upload',
+    description: '上传本地文件或整个目录到知识库（目录递归镜像文件夹，multipart 直传，单文件 ≤20MB）',
+    usage: 'yos kb upload <本地文件或目录> --kb <kb_code> [--dir <parent_code>] [--on-conflict <skip|rename>] [--json]',
+    group: '知识库 kb',
+    risk: 'write',
+    options: {
+        kb: { type: 'string' },
+        dir: { type: 'string' },
+        'on-conflict': { type: 'string' },
+        json: { type: 'boolean' },
+    },
+    paramNotes: [
+        ['--kb', '知识库编码'],
+        ['--dir', '目标父文件夹编码（缺省知识库根目录）'],
+        ['--on-conflict', '同名冲突处理：skip 跳过 / rename 加后缀新建（缺省则中止并列出冲突）'],
+        ['--json', '结构化输出（目录上传返回汇总对象）'],
+    ],
+    async run({ positionals, flags }) {
+        const target = positionals[0];
+        if (!target) {
+            throw new UsageError('缺少本地文件或目录路径', '用法: yos kb upload <本地文件或目录> --kb <kb_code> [--dir <parent_code>] [--on-conflict <skip|rename>]');
+        }
+        const kbCode = flags.kb;
+        if (!kbCode) {
+            throw new UsageError('缺少 --kb 知识库编码', '可用 `yos kb list` 查看知识库编码');
+        }
+        const json = flags.json === true;
+        const onConflict = parseConflictPolicy(flags['on-conflict']);
+        const dirCode = flags.dir;
+        const isDir = (await stat(target).catch(() => {
+            throw new BusinessError(`文件或目录不存在：${target}`);
+        })).isDirectory();
+        const config = loadConfig();
+        const deps = buildDeps(resolveEndpoint(config), resolveKey(config), json);
+        return isDir
+            ? uploadDir(deps, target, kbCode, dirCode, onConflict, json)
+            : uploadSingle(deps, target, kbCode, dirCode, onConflict, json);
+    },
+});
+function parseConflictPolicy(raw) {
+    if (raw === undefined || raw === true) {
+        return undefined;
+    }
+    const value = Array.isArray(raw) ? raw[raw.length - 1] : raw;
+    if (!CONFLICT_POLICIES.includes(value)) {
+        throw new UsageError(`--on-conflict 取值非法：${value}`, '可选：skip（跳过冲突件）/ rename（加后缀新建）');
+    }
+    return value;
+}
+async function uploadSingle(deps, filePath, kbCode, dirCode, onConflict, json) {
+    const name = basename(filePath);
+    const siblings = findSubtreeChildren(await deps.fetchTree(kbCode), dirCode).map((node) => node.name);
+    const decision = decideSingleFileUpload(name, siblings, onConflict);
+    if (decision.action === 'abort') {
+        if (json) {
+            printJson({ aborted: true, reason: 'conflict', fileName: name });
+        }
+        else {
+            printErr(`目标位置已存在同名文件，已中止（未上传）：${name}`);
+            printErr('提示: 加 --on-conflict skip 跳过，或 --on-conflict rename 加后缀新建');
+        }
+        return EXIT.BUSINESS;
+    }
+    if (decision.action === 'skip') {
+        if (json) {
+            printJson({ skipped: true, fileName: name });
+        }
+        else {
+            print(`已跳过（目标位置已存在同名文件）：${name}`);
+        }
+        return EXIT.OK;
+    }
+    const finalName = decision.finalName;
+    try {
+        const result = await deps.uploadFile(filePath, kbCode, dirCode, finalName);
+        if (json) {
+            printJson(result);
+        }
+        else if (finalName === name) {
+            print(`已上传：${result.fileName}（${result.fileSize} 字节）→ 节点 ${result.nodeCode}`);
+        }
+        else {
+            print(`已改名上传：${name} → ${result.fileName}（${result.fileSize} 字节）→ 节点 ${result.nodeCode}`);
+        }
+        return EXIT.OK;
+    }
+    catch (e) {
+        if (e instanceof BusinessError && e.message.includes('超过 20MB')) {
+            throw new BusinessError(e.message, '更大文件请先在客户端上传后共享，或拆分为多个文件');
+        }
+        throw e;
+    }
+}
+async function uploadDir(deps, localRoot, kbCode, dirCode, onConflict, json) {
+    const { exitCode, aborted, summary } = await uploadDirectory(deps, { localRoot, kbCode, dirCode, onConflict });
+    if (aborted) {
+        if (json) {
+            printJson({ aborted: true, reason: 'conflict', ...summary });
+        }
+        else {
+            printErr(`发现 ${summary.conflicts.length} 个同名冲突，已中止（未上传任何文件）：`);
+            for (const path of summary.conflicts) {
+                printErr(`  - ${path}`);
+            }
+            printErr('提示: 加 --on-conflict skip 跳过冲突件，或 --on-conflict rename 加后缀新建');
+        }
+        return EXIT.BUSINESS;
+    }
+    if (json) {
+        printJson(summary);
+    }
+    else {
+        print(renderSummary(summary));
+    }
+    return exitCode;
+}
+function buildDeps(endpoint, apiKey, json) {
+    const client = clientFromConfig();
+    return {
+        async fetchTree(kbCode) {
+            const result = await client.callTool('docs_tree', { kb_code: kbCode });
+            if (result.isError) {
+                throw new BusinessError(`目录树查询失败：${result.text}`);
+            }
+            return JSON.parse(result.text);
+        },
+        async mkdir(name, kbCode, parentCode) {
+            const args = { folder_name: name, kb_code: kbCode };
+            if (parentCode) {
+                args.parent_code = parentCode;
+            }
+            const result = await client.callTool('docs_mkdir', args);
+            if (result.isError) {
+                throw new BusinessError(`创建文件夹失败：${name}，${result.text}`);
+            }
+        },
+        uploadFile(absPath, kbCode, parentCode, finalName) {
+            return uploadKnowledgeFile(endpoint, apiKey, absPath, kbCode, parentCode, finalName);
+        },
+        walk: walkLocalDir,
+        log: json ? () => { } : (message) => print(message),
+    };
+}
+function renderSummary(summary) {
+    const lines = [
+        `上传完成：新建文件夹 ${summary.foldersCreated.length}、复用文件夹 ${summary.foldersReused.length}、`
+            + `上传 ${summary.uploaded.length}、改名 ${summary.renamed.length}、`
+            + `跳过 ${summary.skipped.length}、失败 ${summary.failed.length}`,
+    ];
+    for (const item of summary.failed) {
+        lines.push(`  失败：${item.name} — ${item.error}`);
+    }
+    return lines.join('\n');
+}

package/dist/commands/login.js

@@ -0,0 +1,35 @@
+import { register } from '../cli.js';
+import { loadConfig, maskKey, normalizeEndpoint, saveConfig } from '../config.js';
+import { DEFAULT_ENDPOINT } from '../endpoints.js';
+import { UsageError } from '../errors.js';
+import { formatIdentity, OpenApisClient } from '../openapis-client.js';
+import { print } from '../output.js';
+import { readHiddenLine } from '../prompt.js';
+register({
+    name: 'login',
+    description: '配置访问令牌与 BFF 端点（校验身份后保存）',
+    usage: 'yos login [--endpoint <url>] [--key <key>]',
+    group: '基础',
+    options: {
+        endpoint: { type: 'string' },
+        key: { type: 'string' },
+    },
+    paramNotes: [
+        ['--endpoint', 'BFF 服务地址（缺省读 YOS_ENDPOINT，再缺省生产环境；本地联调 http://localhost:8080）'],
+        ['--key', '访问令牌（40 位小写 hex，缺省读 YOS_API_KEY，否则交互输入）'],
+    ],
+    async run({ flags }) {
+        const config = loadConfig();
+        const endpoint = normalizeEndpoint(flags.endpoint
+            ?? process.env.YOS_ENDPOINT ?? config?.endpoint ?? DEFAULT_ENDPOINT);
+        const key = flags.key
+            ?? process.env.YOS_API_KEY
+            ?? await readHiddenLine('请粘贴访问令牌（输入不回显，客户端「个人设置-访问令牌」页创建并复制）: ');
+        if (!/^[0-9a-f]{40}$/.test(key)) {
+            throw new UsageError('令牌格式不正确（应为 40 位小写 hex）', '请在客户端「个人设置-访问令牌」页创建并复制完整令牌');
+        }
+        const identity = await new OpenApisClient(`${endpoint}/open-apis`, key).whoami();
+        saveConfig({ ...config, endpoint, apiKey: key });
+        print(`已保存配置：endpoint=${endpoint}，key=${maskKey(key)}，身份 ${formatIdentity(identity)}`);
+    },
+});

package/dist/commands/ping.js

@@ -0,0 +1,40 @@
+import { register } from '../cli.js';
+import { loadConfig, resolveEndpoint, resolveKey } from '../config.js';
+import { CliError, EXIT } from '../errors.js';
+import { formatIdentity, OpenApisClient } from '../openapis-client.js';
+import { print, printErr, printJson } from '../output.js';
+register({
+    name: 'ping',
+    description: '探活：检查服务连通与访问令牌是否有效（客户端检测对接用）',
+    usage: 'yos ping [--json]',
+    group: '基础',
+    options: { json: { type: 'boolean' } },
+    paramNotes: [['--json', '结构化输出（ok / endpoint / userCode / userName / error）']],
+    async run({ flags }) {
+        const config = loadConfig();
+        const endpoint = resolveEndpoint(config);
+        try {
+            const identity = await new OpenApisClient(`${endpoint}/open-apis`, resolveKey(config)).whoami();
+            if (flags.json) {
+                printJson({ ok: true, endpoint, userCode: identity.userCode, userName: identity.userName });
+            }
+            else {
+                print(`✓ 连接成功，令牌有效：身份 ${formatIdentity(identity)}`);
+            }
+            return EXIT.OK;
+        }
+        catch (e) {
+            const failure = e instanceof CliError ? e : new CliError(String(e), EXIT.BUSINESS);
+            if (flags.json) {
+                printJson({ ok: false, endpoint, error: failure.message });
+            }
+            else {
+                printErr(`错误: ${failure.message}`);
+                if (failure.hint) {
+                    printErr(`提示: ${failure.hint}`);
+                }
+            }
+            return failure.exitCode;
+        }
+    },
+});

package/dist/commands/skill.js

@@ -0,0 +1,22 @@
+import { register } from '../cli.js';
+import { UsageError } from '../errors.js';
+import { print } from '../output.js';
+import { BUILTIN_SKILLS, detectSkillTargets, installSkillsTo } from '../skill-sync.js';
+register({
+    name: 'skill install',
+    description: '安装内置 YOS Skill 到 Agent 技能目录',
+    usage: 'yos skill install [--target <dir>]',
+    group: 'Agent 接入',
+    options: { target: { type: 'string' } },
+    paramNotes: [['--target', '显式指定安装目标目录（缺省自动探测本机 Agent 技能目录）']],
+    async run({ flags }) {
+        const explicit = flags.target;
+        const targets = explicit ? [explicit] : detectSkillTargets();
+        if (targets.length === 0) {
+            throw new UsageError('未发现已安装的 Agent 技能目录', '请用 --target <dir> 指定（如 ~/.claude/skills）');
+        }
+        installSkillsTo(targets);
+        print(`已安装 ${BUILTIN_SKILLS.length} 个 Skill 到：\n${targets.join('\n')}`);
+        print('提示：重启 Agent 工具以确保 Skill 加载');
+    },
+});

package/dist/commands/tool.js

@@ -0,0 +1,129 @@
+import { register } from '../cli.js';
+import { EXIT, UsageError } from '../errors.js';
+import { print, printJson, summarize } from '../output.js';
+import { groupTools } from '../tool-domains.js';
+import { clientFromConfig } from './context.js';
+register({
+    name: 'tool list',
+    description: '列出 YOS 全部可用工具（按领域分组，动态获取）',
+    usage: 'yos tool list [--json]',
+    group: '工具通道',
+    options: { json: { type: 'boolean' } },
+    paramNotes: [['--json', '结构化输出']],
+    async run({ flags }) {
+        const tools = await clientFromConfig().listTools();
+        if (flags.json) {
+            printJson(tools);
+            return;
+        }
+        if (tools.length === 0) {
+            print('（无可用工具）');
+            return;
+        }
+        const nameWidth = Math.max(...tools.map((tool) => tool.name.length));
+        const sections = groupTools(tools).map((group) => {
+            const rows = group.tools
+                .map((tool) => `  ${tool.name.padEnd(nameWidth)}  ${summarize(tool.description ?? '')}`)
+                .join('\n');
+            return `${group.domain}（${group.tools.length}）\n${rows}`;
+        });
+        print(sections.join('\n\n'));
+        print('\n提示: 常规场景优先使用领域命令（yos kb / docs / retrieve / support / transcript --help），未覆盖的工具用 yos tool schema <工具名> 查看完整说明');
+    },
+});
+register({
+    name: 'tool schema',
+    description: '查看单个工具的完整说明（描述全文、入参、返参、调用示例）',
+    usage: 'yos tool schema <name> [--json]',
+    group: '工具通道',
+    options: { json: { type: 'boolean' } },
+    paramNotes: [['--json', '结构化输出']],
+    async run({ positionals, flags }) {
+        const name = resolveToolName(positionals);
+        if (!name) {
+            throw new UsageError('缺少工具名', '用法: yos tool schema <name>（先用 yos tool list 浏览可用工具）');
+        }
+        const schema = await clientFromConfig().toolSchema(name);
+        if (flags.json) {
+            printJson(schema);
+            return;
+        }
+        print(renderToolSchema(schema));
+    },
+});
+register({
+    name: 'tool call',
+    description: '调用任意 YOS 工具（参数为 JSON）',
+    usage: "yos tool call <name> [--params '<json>'] [--json]",
+    group: '工具通道',
+    options: {
+        params: { type: 'string' },
+        json: { type: 'boolean' },
+    },
+    paramNotes: [
+        ['--params', "工具入参 JSON（遵循工具 schema，如 '{\"kb_code\":\"KB1\"}'）"],
+        ['--json', '结构化输出（工具返回原文在 text 字段内）'],
+    ],
+    async run({ positionals, flags }) {
+        const name = resolveToolName(positionals);
+        if (!name) {
+            throw new UsageError('缺少工具名', "用法: yos tool call <name> [--params '<json>']");
+        }
+        const paramsRaw = flags.params ?? '{}';
+        let params;
+        try {
+            params = JSON.parse(paramsRaw);
+        }
+        catch {
+            throw new UsageError(`--params 不是合法 JSON：${paramsRaw}`);
+        }
+        const result = await clientFromConfig().callTool(name, params);
+        if (flags.json) {
+            printJson(result);
+        }
+        else {
+            print(result.text);
+        }
+        return result.isError ? EXIT.BUSINESS : EXIT.OK;
+    },
+});
+function resolveToolName(positionals) {
+    if (positionals.length === 0) {
+        return undefined;
+    }
+    if (!positionals.every((token) => /^[a-z][a-z0-9_-]*$/.test(token))) {
+        return positionals[0];
+    }
+    return positionals.map((token) => token.replace(/-/g, '_')).join('_');
+}
+function renderToolSchema(schema) {
+    const lines = [`工具: ${schema.name}`, `说明: ${schema.description ?? ''}`, ''];
+    const properties = Object.entries(schema.inputSchema?.properties ?? {});
+    const required = new Set(schema.inputSchema?.required ?? []);
+    if (properties.length === 0) {
+        lines.push('入参: 无');
+    }
+    else {
+        lines.push('入参:');
+        lines.push(renderPropRows(properties.map(([key, prop]) => [
+            key,
+            String(prop?.type ?? 'any'),
+            required.has(key) ? '必填' : '可选',
+            String(prop?.description ?? '').replace(/\s*\n\s*/g, ' '),
+        ])));
+    }
+    lines.push('');
+    lines.push(`返参: ${schema.outputHint || '（未登记说明）'}`);
+    lines.push('');
+    const sample = Object.fromEntries(properties.filter(([key]) => required.has(key)).map(([key]) => [key, `<${key}>`]));
+    const sampleText = Object.keys(sample).length > 0 ? ` --params '${JSON.stringify(sample)}'` : '';
+    lines.push('调用示例:');
+    lines.push(`  yos tool call ${schema.name}${sampleText}`);
+    return lines.join('\n');
+}
+function renderPropRows(rows) {
+    const widths = [0, 1].map((index) => Math.max(...rows.map((row) => row[index].length)));
+    return rows
+        .map((row) => `  ${row[0].padEnd(widths[0])}  ${row[1].padEnd(widths[1])}  ${row[2]}  ${row[3]}`)
+        .join('\n');
+}