@yosai/cli 0.0.0-stage → 0.2.1-test.0

package/dist/commands/update.js

@@ -0,0 +1,73 @@
+import { register } from '../cli.js';
+import { loadConfig } from '../config.js';
+import { BusinessError } from '../errors.js';
+import { compareVersions, detectGlobalInstall, fetchLatestVersion, PUBLIC_REGISTRY, readPackageMeta, runNpm } from '../npm-meta.js';
+import { print, printJson } from '../output.js';
+import { installSkillsTo } from '../skill-sync.js';
+import { saveVersionState } from '../version-state.js';
+register({
+    name: 'update',
+    description: '检查并升级 CLI 到 npmjs 最新版（升级后自动重同步 Skill）',
+    usage: 'yos update [--check] [--json]',
+    group: '基础',
+    risk: 'write',
+    options: { check: { type: 'boolean' }, json: { type: 'boolean' } },
+    paramNotes: [
+        ['--check', '只检查是否有新版本，不安装、不写入状态'],
+        ['--json', '结构化输出（仅 --check 生效）'],
+    ],
+    async run({ flags }) {
+        const meta = readPackageMeta();
+        if (!meta) {
+            throw new BusinessError('无法确定包名（未找到 package.json）', '请通过 npm 全局安装后重试');
+        }
+        const latest = await fetchLatestVersion(meta.name);
+        const outdated = compareVersions(meta.version, latest) < 0;
+        if (flags.check) {
+            if (flags.json) {
+                printJson({ version: meta.version, latest, outdated });
+            }
+            else {
+                print(outdated
+                    ? `当前 ${meta.version}，最新 ${latest}，执行 yos update 升级`
+                    : `已是最新（${latest}）`);
+            }
+            return;
+        }
+        if (!outdated) {
+            syncSkills();
+            saveVersionState(meta.version);
+            print(`已是最新（${meta.version}）`);
+            return;
+        }
+        const shape = await detectGlobalInstall(meta);
+        if (!shape.global) {
+            print(`当前安装不在 npm 全局目录（${meta.dir}），不代跑升级`);
+            throw new BusinessError('非全局安装，已跳过自动升级', `手动升级：npm install -g ${meta.name}@latest --registry=${PUBLIC_REGISTRY}；或先 npm uninstall -g ${meta.name} 再全局安装`);
+        }
+        const install = await runNpm(['install', '-g', `${meta.name}@latest`, `--registry=${PUBLIC_REGISTRY}`]);
+        if (!install.ok) {
+            const output = `${install.stderr}\n${install.stdout}`;
+            if (/EACCES|EPERM|permission denied/i.test(output)) {
+                throw new BusinessError('npm 全局目录没有写权限', '把 npm 前缀改到用户目录后重试（npm config set prefix ~/.npm-global 并把其 bin 加入 PATH），不要 sudo npm install -g');
+            }
+            throw new BusinessError(`npm install -g ${meta.name}@latest 失败：${firstLine(install.stderr) || firstLine(install.stdout) || '无输出'}`);
+        }
+        syncSkills();
+        saveVersionState(latest);
+        print(`已升级 ${meta.version} → ${latest}`);
+        print('提示：重启 Agent 工具以加载刷新后的 Skill');
+    },
+});
+function syncSkills() {
+    const dirs = loadConfig()?.installedSkillDirs ?? [];
+    if (dirs.length === 0) {
+        print('未记录 Skill 安装目录，跳过 Skill 同步（需要时执行 yos skill install）');
+        return;
+    }
+    installSkillsTo(dirs);
+    print(`已重同步 Skill：${dirs.join(', ')}`);
+}
+function firstLine(text) {
+    return text.split(/\r?\n/)[0]?.trim() ?? '';
+}

package/dist/commands/version.js

@@ -0,0 +1,44 @@
+import { register } from '../cli.js';
+import { loadConfig, resolveEndpoint } from '../config.js';
+import { BusinessError } from '../errors.js';
+import { compareVersions, detectGlobalInstall, fetchLatestVersion, readPackageMeta } from '../npm-meta.js';
+import { print, printJson } from '../output.js';
+register({
+    name: 'version',
+    description: '显示 CLI 版本（--check 比对 npmjs 最新版）',
+    usage: 'yos version [--json] [--check]',
+    group: '基础',
+    risk: 'read',
+    options: { json: { type: 'boolean' }, check: { type: 'boolean' } },
+    paramNotes: [
+        ['--check', '与 npmjs 最新版本比对是否可升级（只读，不写入任何状态）'],
+        ['--json', '结构化输出'],
+    ],
+    async run({ flags }) {
+        const meta = readPackageMeta();
+        const version = meta?.version ?? 'unknown';
+        const endpoint = resolveEndpoint(loadConfig());
+        if (!flags.check) {
+            if (flags.json) {
+                const installedGlobally = meta ? (await detectGlobalInstall(meta)).global : false;
+                printJson({ version, installedGlobally, endpoint });
+            }
+            else {
+                print(`yos CLI ${version}`);
+            }
+            return;
+        }
+        if (!meta) {
+            throw new BusinessError('无法确定包名（未找到 package.json）', '请通过 npm 全局安装后重试');
+        }
+        const latest = await fetchLatestVersion(meta.name);
+        const outdated = compareVersions(meta.version, latest) < 0;
+        if (flags.json) {
+            printJson({ version, latest, outdated, installedGlobally: (await detectGlobalInstall(meta)).global, endpoint });
+            return;
+        }
+        print(outdated
+            ? `当前 ${meta.version}，最新 ${latest}，执行 yos update 升级`
+            : `已是最新（${latest}）`);
+    },
+});

package/dist/config.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_ENDPOINT } from './endpoints.js';
+import { UsageError } from './errors.js';
+export function configDir() {
+    return process.env.YOS_CONFIG_DIR ?? join(homedir(), '.config', 'yos');
+}
+export function configPath() {
+    return join(configDir(), 'config.json');
+}
+export function loadConfig() {
+    const path = configPath();
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveConfig(config) {
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    writeFileSync(configPath(), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+export function resolveKey(config) {
+    const fromEnv = process.env.YOS_API_KEY;
+    if (fromEnv) {
+        return fromEnv;
+    }
+    if (config?.apiKey) {
+        return config.apiKey;
+    }
+    throw new UsageError('未配置访问令牌', '请执行 `yos login` 或设置环境变量 YOS_API_KEY');
+}
+export function resolveEndpoint(config) {
+    const fromEnv = process.env.YOS_ENDPOINT;
+    if (fromEnv) {
+        return normalizeEndpoint(fromEnv);
+    }
+    return normalizeEndpoint(config?.endpoint ?? DEFAULT_ENDPOINT);
+}
+export function normalizeEndpoint(endpoint) {
+    return endpoint.replace(/\/+$/, '');
+}
+export function maskKey(key) {
+    return key.length <= 12 ? '****' : `${key.slice(0, 8)}****${key.slice(-4)}`;
+}
+export function updateConfig(patch) {
+    const merged = { endpoint: DEFAULT_ENDPOINT, ...loadConfig(), ...patch };
+    saveConfig(merged);
+    return merged;
+}

package/dist/domain-commands.js

@@ -0,0 +1,477 @@
+import { assertAnyParam, assertDateRange, assertGrepOrder, assertNotBlank, assertNumericId, assertTextLength, normalizeReadItems, parseReadTarget, resolveContent, } from './domain-executor.js';
+import { UsageError } from './errors.js';
+import { parseToolJson } from './openapis-client.js';
+import { print, renderRows } from './output.js';
+export const DOMAIN_META = {
+    kb: { groupLabel: '知识库 kb', description: '知识库本体：列表 / 详情 / 更新 / 上传（新建知识库请到 YOS 客户端手动操作）' },
+    docs: { groupLabel: '文档 docs', description: '文档与节点：树 / 正文 / 下载 / 创建 / 更新 / 移动 / 删除 / 恢复' },
+    retrieve: { groupLabel: '检索 retrieve', description: 'cortex 检索原语：语义检索 / 定位 / 精读 / 配套 / 大纲' },
+    support: { groupLabel: '支持 support', description: '帮助手册 / 客户端升级 / 问题反馈' },
+    transcript: { groupLabel: '转写 transcript', description: '录音转写查询' },
+};
+export const DOMAIN_COMMANDS = [
+    {
+        name: 'kb list',
+        domain: 'kb',
+        tool: 'kb_list',
+        description: '列出知识库（缺省全部可见：我创建的 + 分享给我的）',
+        risk: 'read',
+        flags: [
+            {
+                flag: 'scope', param: 'range', kind: 'string',
+                description: '范围 created=我创建|shared=分享给我|all=全部可见（缺省 all）',
+                values: ['created', 'shared', 'all'],
+            },
+            { flag: 'keyword', param: 'keyword', kind: 'string', description: '名称关键词（仅匹配库名，不搜正文）' },
+            { flag: 'page', param: 'page', kind: 'number', description: '页码（缺省 1）', min: 1 },
+            { flag: 'size', param: 'size', kind: 'number', description: '每页条数（缺省 10，上限 50）', min: 1, max: 50 },
+        ],
+        render: (result) => {
+            const data = parseToolJson(result);
+            const records = data.records ?? [];
+            if (records.length === 0) {
+                print('（无知识库）');
+                return;
+            }
+            print(renderRows(records.map((r) => [
+                String(r.kbCode ?? r.kb_code ?? ''),
+                String(r.kbName ?? r.kb_name ?? r.name ?? ''),
+            ])));
+        },
+    },
+    {
+        name: 'kb detail',
+        domain: 'kb',
+        tool: 'kb_detail',
+        description: '知识库详情',
+        risk: 'read',
+        positionals: [{ name: 'kb_code', param: 'kb_code', description: '知识库编码' }],
+    },
+    {
+        name: 'kb update',
+        domain: 'kb',
+        tool: 'kb_update',
+        description: '修改知识库名称或简介（至少传一个；需管理员及以上）',
+        risk: 'write',
+        positionals: [{ name: 'kb_code', param: 'kb_code', description: '知识库编码' }],
+        flags: [
+            { flag: 'name', param: 'kb_name', kind: 'string', description: '新名称（≤24 字）' },
+            { flag: 'description', param: 'description', kind: 'string', description: '新简介（≤80 字）' },
+        ],
+        validateArgs: (args) => {
+            assertAnyParam(args, ['kb_name', 'description'], ['--name', '--description']);
+            assertTextLength(args.kb_name, 24, '知识库名称');
+        },
+    },
+    {
+        name: 'docs tree',
+        domain: 'docs',
+        tool: 'docs_tree',
+        description: '知识库目录树（文件夹/文档层级，不含正文）',
+        risk: 'read',
+        positionals: [{ name: 'kb_code', param: 'kb_code', description: '知识库编码' }],
+    },
+    {
+        name: 'docs content',
+        domain: 'docs',
+        tool: 'docs_content',
+        description: '读取文档标题与正文（上传文件类型无内联正文）',
+        risk: 'read',
+        positionals: [{ name: 'node_code', param: 'node_code', description: '文档节点编码' }],
+    },
+    {
+        name: 'docs count',
+        domain: 'docs',
+        tool: 'docs_count',
+        description: '统计删除影响范围（文档=1，文件夹=全部子孙数）',
+        risk: 'read',
+        positionals: [{
+                name: 'node_code', param: 'node_code',
+                description: '节点编码（文件夹或文档）',
+            }],
+    },
+    {
+        name: 'docs mkdir',
+        domain: 'docs',
+        tool: 'docs_mkdir',
+        description: '创建文件夹（需编辑者及以上权限）',
+        risk: 'write',
+        positionals: [{ name: '文件夹名', param: 'folder_name', description: '新建文件夹名称' }],
+        flags: [
+            { flag: 'kb', param: 'kb_code', kind: 'string', description: '知识库编码（未传 --parent 时必填）' },
+            { flag: 'parent', param: 'parent_code', kind: 'string', description: '父文件夹编码（须为文件夹节点；缺省知识库根目录）' },
+        ],
+        validateArgs: (args) => assertAnyParam(args, ['kb_code', 'parent_code'], ['--kb', '--parent']),
+    },
+    {
+        name: 'docs create',
+        domain: 'docs',
+        tool: 'docs_create',
+        description: '创建文档（正文经 --content 或 --file 提供）',
+        risk: 'write',
+        positionals: [{ name: '标题', param: 'title', description: '文档标题（≤128 字）' }],
+        flags: [
+            { flag: 'kb', param: 'kb_code', kind: 'string', description: '知识库编码' },
+            { flag: 'parent', param: 'parent_code', kind: 'string', description: '父文件夹编码（缺省知识库根目录；须为文件夹节点）' },
+            {
+                flag: 'type', param: 'doc_type', kind: 'string',
+                description: '文档类型（缺省 md）：md=Markdown 文本 / cloud=云文档 / sheet=表格；'
+                    + 'cloud 与 sheet 的正文须为对应草稿 JSON，一般场景一律用 md',
+                values: ['md', 'cloud', 'sheet'],
+            },
+            { flag: 'content', param: 'content', kind: 'string', description: '正文文本（与 --file 二选一）' },
+            { flag: 'file', param: 'content', kind: 'string', description: '正文文件路径（UTF-8，与 --content 二选一）' },
+        ],
+        buildArgs: (context) => {
+            const title = context.positionals[0];
+            if (!title) {
+                throw new UsageError('缺少参数 <标题>', '用法: yos docs create <标题> --kb <code> (--content <文本> | --file <路径>)');
+            }
+            const args = {
+                title,
+                content: resolveContent(context.flags, true),
+            };
+            if (context.flags.kb) {
+                args.kb_code = context.flags.kb;
+            }
+            if (context.flags.parent) {
+                args.parent_code = context.flags.parent;
+            }
+            if (context.flags.type) {
+                args.doc_type = context.flags.type;
+            }
+            return args;
+        },
+        validateArgs: (args) => assertAnyParam(args, ['kb_code', 'parent_code'], ['--kb', '--parent']),
+    },
+    {
+        name: 'docs update',
+        domain: 'docs',
+        tool: 'docs_update',
+        description: '更新文档标题/正文/描述（正文为整体覆盖；需编辑者及以上权限）',
+        risk: 'write',
+        positionals: [{ name: 'node_code', param: 'node_code', description: '文档节点编码' }],
+        flags: [
+            { flag: 'title', param: 'title', kind: 'string', description: '新标题' },
+            { flag: 'content', param: 'content', kind: 'string', description: '新正文，整体覆盖原正文（与 --file 二选一）' },
+            { flag: 'file', param: 'content', kind: 'string', description: '新正文文件路径，整体覆盖原正文（与 --content 二选一）' },
+            { flag: 'description', param: 'description', kind: 'string', description: '新简介（≤100 字）' },
+        ],
+        buildArgs: (context) => {
+            const nodeCode = context.positionals[0];
+            if (!nodeCode) {
+                throw new UsageError('缺少参数 <node_code>', '用法: yos docs update <node_code> [--title <新标题>] [--content <文本> | --file <路径>]');
+            }
+            const args = { node_code: nodeCode };
+            if (context.flags.title) {
+                args.title = context.flags.title;
+            }
+            const content = resolveContent(context.flags, false);
+            if (content !== undefined) {
+                args.content = content;
+            }
+            if (context.flags.description) {
+                args.description = context.flags.description;
+            }
+            return args;
+        },
+        validateArgs: (args) => assertAnyParam(args, ['title', 'content', 'description'], ['--title', '--content/--file', '--description']),
+    },
+    {
+        name: 'docs rename',
+        domain: 'docs',
+        tool: 'docs_rename',
+        description: '重命名文件夹（仅文件夹）',
+        risk: 'write',
+        positionals: [
+            { name: 'node_code', param: 'node_code', description: '文件夹节点编码' },
+            { name: '新名称', param: 'folder_name', description: '新文件夹名称' },
+        ],
+        flags: [{ flag: 'description', param: 'description', kind: 'string', description: '新描述（可空）' }],
+    },
+    {
+        name: 'docs move',
+        domain: 'docs',
+        tool: 'docs_move',
+        description: '移动节点（--parent 缺省=移动至根目录；需管理员及以上）',
+        risk: 'write',
+        positionals: [{
+                name: 'node_code', param: 'node_code',
+                description: '待移动节点编码（文件夹或文档）',
+            }],
+        flags: [
+            { flag: 'parent', param: 'parent_code', kind: 'string', description: '目标父节点编码（必须是文件夹节点；缺省知识库根目录）' },
+            { flag: 'prev', param: 'prev_node_code', kind: 'string', description: '目标位置前一个相邻节点编码（控制排序，可空）' },
+        ],
+    },
+    {
+        name: 'docs delete',
+        domain: 'docs',
+        tool: 'docs_delete',
+        description: '删除节点（级联进入回收站，90 天内可恢复）',
+        risk: 'danger',
+        positionals: [{
+                name: 'node_code', param: 'node_code',
+                description: '节点编码（文件夹或文档）',
+            }],
+    },
+    {
+        name: 'docs restore',
+        domain: 'docs',
+        tool: 'docs_restore',
+        description: '从回收站恢复节点（≤100 个；文件夹与其同批次子文件整组恢复）',
+        risk: 'write',
+        positionals: [{
+                name: 'node_code', param: 'node_codes', variadic: true,
+                description: '待恢复节点编码，可传多个（单次 ≤100 个）',
+            }],
+    },
+    {
+        name: 'retrieve search',
+        domain: 'retrieve',
+        tool: 'retrieve_search',
+        description: '跨库语义检索（时间表达由服务端解析）',
+        risk: 'read',
+        positionals: [{
+                name: 'query', param: 'query', variadic: true, kind: 'space-join',
+                description: '检索词，可含空格（多个词按空格拼为一句）',
+            }],
+        flags: [
+            { flag: 'kb', param: 'kb_ids', kind: 'string', multiple: true, description: '限定知识库编码（可重复，1~10 个；缺省全部可见库）' },
+            { flag: 'dir', param: 'dirs', kind: 'string', multiple: true, description: '限定目录节点编码（可重复）' },
+            {
+                flag: 'top-k', param: 'top_k', kind: 'number', min: 1, max: 25,
+                description: '召回条数（缺省 10，上限 25）；结果按 score 降序，score 低表示相关度低，不代表一定相关',
+            },
+            { flag: 'entity', param: 'entity_keywords', kind: 'string', multiple: true, description: '图谱实体关键词（可重复）' },
+            { flag: 'topic', param: 'topic_keywords', kind: 'string', multiple: true, description: '图谱主题关键词（可重复）' },
+            { flag: 'type', param: 'content_types', kind: 'string', multiple: true, description: '内容类型（可重复）' },
+            {
+                flag: 'labels', param: 'labels', kind: 'string',
+                description: '业务标签 JSON 对象，原样透传，如 \'{"部门":["风控"]}\'（维度间 AND、维度内 OR）',
+            },
+            { flag: 'occurred-after', param: 'occurred_after', kind: 'string', description: '事件时间下限（自然语言，如 2026-01-01 / 上季度）' },
+            { flag: 'occurred-before', param: 'occurred_before', kind: 'string', description: '事件时间上限（自然语言）' },
+            { flag: 'effective-after', param: 'effective_after', kind: 'string', description: '生效日期下限（自然语言）' },
+            { flag: 'effective-before', param: 'effective_before', kind: 'string', description: '生效日期上限（自然语言）' },
+            { flag: 'include-inactive', param: 'include_inactive', kind: 'boolean', description: '纳入已失效文档' },
+        ],
+    },
+    {
+        name: 'retrieve grep',
+        domain: 'retrieve',
+        tool: 'retrieve_grep',
+        description: '正则精确定位（文号/编号等一字不差的串）',
+        risk: 'read',
+        positionals: [
+            {
+                name: 'target', param: 'target',
+                description: '目标 URN：文档级 cortex://kb/{kb_code}/doc/{node_code} 或库级 cortex://kb/{kb_code}',
+            },
+            { name: 'pattern', param: 'pattern', description: '正则表达式（在 target 之后，与 Unix grep 的参数顺序相反）' },
+        ],
+        flags: [
+            { flag: 'context', param: 'context', kind: 'number', min: 0, description: '命中行上下各 N 行' },
+            { flag: 'before', param: 'before', kind: 'number', min: 0, description: '命中行前 N 行' },
+            { flag: 'after', param: 'after', kind: 'number', min: 0, description: '命中行后 N 行' },
+            { flag: 'ignore-case', param: 'case_insensitive', kind: 'boolean', description: '忽略大小写' },
+            {
+                flag: 'mode', param: 'output_mode', kind: 'string', values: ['content', 'count'],
+                description: '输出模式（缺省 content）：content=命中行+上下文 / count=仅命中总数（count 只支持文档级 target）',
+            },
+            { flag: 'offset', param: 'offset', kind: 'number', min: 0, description: '命中结果分页起点（从 0 开始）' },
+            { flag: 'limit', param: 'limit', kind: 'number', min: 1, description: '返回命中条数' },
+        ],
+        validateArgs: (args) => assertGrepOrder(args.target, args.pattern),
+    },
+    {
+        name: 'retrieve read',
+        domain: 'retrieve',
+        tool: 'retrieve_read',
+        description: '读原文（<target>:起-止 区间简写，1~10 项）',
+        risk: 'read',
+        positionals: [{
+                name: 'target[:起-止]', param: 'items', variadic: true,
+                description: '目标 URN，可带 :起-止 行号区间（含两端，缺省 1-200），如 '
+                    + 'cortex://kb/KBxxxx/doc/NDxxxx:10-60；单次最多 10 项',
+            }],
+        flags: [{
+                flag: 'items', param: 'items', kind: 'string',
+                description: 'JSON 数组（与位置参数互斥），每项 {"target":"cortex://...","offset":1,"limit":200}；'
+                    + 'target 亦支持 :起-止 简写',
+            }],
+        buildArgs: (context) => {
+            const itemsFlag = context.flags.items;
+            if (itemsFlag) {
+                if (context.positionals.length > 0) {
+                    throw new UsageError('--items 与位置参数互斥', "二选一：位置参数 <target>:起-止 或 --items '[{...}]'");
+                }
+                return { items: normalizeReadItems(String(itemsFlag)) };
+            }
+            if (context.positionals.length === 0) {
+                throw new UsageError('缺少 target', "用法: yos retrieve read <target>[:起-止] ... 或 --items '[{...}]'");
+            }
+            if (context.positionals.length > 10) {
+                throw new UsageError(`单次最多读取 10 个区间（实际 ${context.positionals.length} 个）`, '拆分为多次调用');
+            }
+            return { items: JSON.stringify(context.positionals.map(parseReadTarget)) };
+        },
+    },
+    {
+        name: 'retrieve neighbors',
+        domain: 'retrieve',
+        tool: 'retrieve_neighbors',
+        description: '查找配套文档（kind: related=按内容找相关 / sibling=同目录兄弟）',
+        risk: 'read',
+        positionals: [{
+                name: 'target', param: 'target', validate: 'urn',
+                description: '文档级 URN：cortex://kb/{kb_code}/doc/{node_code}',
+            }],
+        flags: [
+            {
+                flag: 'kind', param: 'kind', kind: 'string', required: true, values: ['related', 'sibling'],
+                description: 'related=按正文内容找最相关文档（跨目录，多数场景选它）/ sibling=同目录兄弟文档',
+            },
+            { flag: 'limit', param: 'limit', kind: 'number', min: 1, description: '返回条数' },
+            { flag: 'include-inactive', param: 'include_inactive', kind: 'boolean', description: '纳入已失效文档' },
+        ],
+    },
+    {
+        name: 'retrieve outline',
+        domain: 'retrieve',
+        tool: 'retrieve_outline',
+        description: '库级=文档清单 / 文档级=章节树',
+        risk: 'read',
+        positionals: [{
+                name: 'target', param: 'target', validate: 'urn',
+                description: '目标 URN：库级 cortex://kb/{kb_code} 返回文档清单（含行数）；'
+                    + '文档级 cortex://kb/{kb_code}/doc/{node_code} 返回章节树',
+            }],
+        flags: [
+            { flag: 'depth', param: 'depth', kind: 'number', min: 1, max: 3, description: '章节树展开深度（缺省 2，上限 3；仅文档级 target 生效）' },
+            { flag: 'expand', param: 'expand', kind: 'string', multiple: true, description: '展开的章节编号（可重复；命中的子树全量展开，不受 --depth 限制）' },
+            {
+                flag: 'labels', param: 'labels', kind: 'string',
+                description: '业务标签 JSON 对象，原样透传，如 \'{"部门":["风控"]}\'（维度间 AND、维度内 OR）',
+            },
+            { flag: 'occurred-after', param: 'occurred_after', kind: 'string', description: '事件时间下限（自然语言）' },
+            { flag: 'occurred-before', param: 'occurred_before', kind: 'string', description: '事件时间上限（自然语言）' },
+            { flag: 'effective-after', param: 'effective_after', kind: 'string', description: '生效日期下限（自然语言）' },
+            { flag: 'effective-before', param: 'effective_before', kind: 'string', description: '生效日期上限（自然语言）' },
+        ],
+    },
+    {
+        name: 'support manual',
+        domain: 'support',
+        tool: 'support_manual',
+        description: '帮助手册目录树（先看结构再读取或检索）',
+        risk: 'read',
+    },
+    {
+        name: 'support manual-read',
+        domain: 'support',
+        tool: 'support_manual_read',
+        description: '按节点 ID 读帮助手册文章正文',
+        risk: 'read',
+        positionals: [{
+                name: 'node_id', param: 'node_id',
+                description: '手册节点 ID（FOLDER 节点无正文）',
+            }],
+    },
+    {
+        name: 'support manual-search',
+        domain: 'support',
+        tool: 'support_manual_search',
+        description: '关键词检索帮助手册（标题/正文命中）',
+        risk: 'read',
+        positionals: [{ name: 'keyword', param: 'keyword', description: '检索关键词（匹配手册标题与正文）' }],
+    },
+    {
+        name: 'support upgrade',
+        domain: 'support',
+        tool: 'support_upgrade',
+        description: '查询指定平台最新客户端版本（灰度仅白名单可见）',
+        risk: 'read',
+        flags: [
+            {
+                flag: 'platform', param: 'platform', kind: 'string', required: true,
+                description: 'WIN=Windows / MAC_X64=macOS Intel / MAC_ARM64=macOS Apple Silicon',
+                values: ['WIN', 'MAC_X64', 'MAC_ARM64'],
+            },
+        ],
+    },
+    {
+        name: 'support upgrade-log',
+        domain: 'support',
+        tool: 'support_upgrade_log',
+        description: '客户端升级记录（含公告全文）',
+        risk: 'read',
+        flags: [
+            {
+                flag: 'platform', param: 'platform', kind: 'string',
+                description: '平台过滤（缺省全部）：WIN / MAC_X64 / MAC_ARM64',
+                values: ['WIN', 'MAC_X64', 'MAC_ARM64'],
+            },
+            { flag: 'start', param: 'start_date', kind: 'string', description: '发布日期下限（yyyy-MM-dd）' },
+            { flag: 'end', param: 'end_date', kind: 'string', description: '发布日期上限（yyyy-MM-dd）' },
+            { flag: 'page', param: 'page', kind: 'number', description: '页码（缺省 1）', min: 1 },
+            { flag: 'size', param: 'size', kind: 'number', description: '每页条数（缺省 10，上限 50）', min: 1, max: 50 },
+        ],
+        validateArgs: (args) => assertDateRange(args.start_date, args.end_date, 'start', 'end'),
+    },
+    {
+        name: 'support feedback',
+        domain: 'support',
+        tool: 'support_feedback',
+        description: '提交反馈（自动关联当前用户与所属企业，≤2000 字）',
+        risk: 'write',
+        positionals: [{
+                name: '内容', param: 'content', variadic: true, kind: 'space-join',
+                description: '反馈正文（≤2000 字，可含空格）；不支持附件，提交后无法查询进度或撤回',
+            }],
+        validateArgs: (args) => {
+            assertNotBlank(args.content, '反馈内容', '用法: yos support feedback <内容...>');
+            assertTextLength(args.content, 2000, '反馈内容');
+        },
+    },
+    {
+        name: 'transcript list',
+        domain: 'transcript',
+        tool: 'transcript_list',
+        description: '列出我的转写记录（自建与他人分享，恒排除失败状态）',
+        risk: 'read',
+        flags: [
+            { flag: 'page', param: 'page', kind: 'number', description: '页码（缺省 1）', min: 1 },
+            { flag: 'size', param: 'size', kind: 'number', description: '每页条数（缺省 10，上限 50）', min: 1, max: 50 },
+            {
+                flag: 'status', param: 'status', kind: 'string',
+                description: '状态过滤：recording=录制中/转写中 / recorded=待总结 / summarizing=总结中 / summarized=总结完成'
+                    + '（failed 恒被排除，不可作为过滤值）',
+                values: ['recording', 'recorded', 'summarizing', 'summarized'],
+            },
+            {
+                flag: 'relation', param: 'relation_type', kind: 'string', values: ['owner', 'shared', 'all'],
+                description: '归属过滤（缺省 all）：owner=我创建 / shared=他人分享给我',
+            },
+            {
+                flag: 'keyword', param: 'keyword', kind: 'string',
+                description: '关键词：匹配创建人姓名与主题（模糊）或转写编码（全等）；不检索纪要与逐字稿',
+            },
+            { flag: 'start', param: 'start_date', kind: 'string', description: '开始日期（yyyy-MM-dd，含当日）' },
+            { flag: 'end', param: 'end_date', kind: 'string', description: '结束日期（yyyy-MM-dd，含当日）' },
+        ],
+        validateArgs: (args) => assertDateRange(args.start_date, args.end_date, 'start', 'end'),
+    },
+    {
+        name: 'transcript detail',
+        domain: 'transcript',
+        tool: 'transcript_detail',
+        description: '转写详情（含全文分段/纪要/思维导图，仅已完成可读）',
+        risk: 'read',
+        positionals: [{
+                name: 'transcription_user_id', param: 'transcription_user_id',
+                description: '转写归属记录 ID（数字，非 TT 开头的转写编码）',
+            }],
+        validateArgs: (args) => assertNumericId(args.transcription_user_id, '转写归属记录 ID', 'TT 开头的是转写编码，本命令需要对应的数字 ID'),
+    },
+];