vps-work 2.4.1 → 2.5.1

package/dist/packages/vps-work/src/commands/documents/index.js

@@ -0,0 +1,991 @@
+import { randomUUID } from 'node:crypto';
+import { Command } from 'commander';
+import { documentsRequest, printDocumentsResult } from '../../core/documents-client.js';
+import { VertuError } from '../../core/errors.js';
+import { imRequest } from '../../core/im-client.js';
+import { parseJsonArg } from '../../utils/parse-json-arg.js';
+import { readStdinText, readUtf8File } from '../../utils/read-text.js';
+const DOCUMENT_BLOCK_TYPES = [
+    'paragraph',
+    'heading',
+    'numberedListItem',
+    'bulletListItem',
+    'checkListItem',
+    'codeBlock',
+    'quote',
+];
+const DOCUMENT_BLOCK_ALIGNMENTS = ['left', 'center', 'right'];
+const DOCUMENT_BLOCK_BACKGROUNDS = ['default', 'yellow'];
+function required(value, flag) {
+    const normalized = value?.trim();
+    if (!normalized) {
+        throw new VertuError(`${flag} 为必填。`);
+    }
+    return normalized;
+}
+/** 解析 --locked true/false。 */
+function parseLockedFlag(value) {
+    const normalized = required(value, '--locked').toLowerCase();
+    if (normalized === 'true' || normalized === '1')
+        return true;
+    if (normalized === 'false' || normalized === '0')
+        return false;
+    throw new VertuError('--locked 必须是 true 或 false。');
+}
+/** 组装新建字段的 options；人员字段用 --multiple，单选/多选用 --choices。 */
+function fieldOptions(opts) {
+    if (opts.type === 'member') {
+        return { isMultiple: opts.multiple === true };
+    }
+    if (opts.type === 'rating') {
+        return { icon: 'star', max: 5 };
+    }
+    if (opts.type === 'formula' || opts.type === 'rollup' || opts.type === 'conditionalRollup') {
+        return {
+            expression: required(opts.expression, '--expression'),
+            foreignTableId: opts.foreignTable,
+        };
+    }
+    if (opts.type === 'link') {
+        return {
+            foreignTableId: required(opts.foreignTable, '--foreign-table'),
+            isOneWay: opts.oneWay === true,
+            relationship: opts.relationship ?? 'manyMany',
+        };
+    }
+    if (opts.choices) {
+        return { choices: parseJsonArg(opts.choices, '--choices') };
+    }
+    return undefined;
+}
+function documentPath(docId, suffix = '') {
+    return `/v1/documents/${encodeURIComponent(docId)}${suffix}`;
+}
+/** 历史查询参数；字段和修改人用逗号分隔。 */
+function historyQuery(opts) {
+    return {
+        createdByIds: opts.createdByIds,
+        cursor: opts.cursor,
+        endDate: opts.endDate,
+        fieldIds: opts.fieldIds,
+        mirrorId: opts.mirrorId,
+        startDate: opts.startDate,
+    };
+}
+function attachBaseOptions(command) {
+    return command
+        .option('--base-url <url>', 'Override Vertu service URL')
+        .option('--no-json', 'Print compact output instead of formatted JSON');
+}
+async function resolveContent(opts) {
+    if (opts.content !== undefined && opts.contentFile !== undefined) {
+        throw new VertuError('--content 和 --content-file 不能同时使用。');
+    }
+    if (opts.contentFile === '-') {
+        return readStdinText();
+    }
+    if (opts.contentFile !== undefined) {
+        return readUtf8File(opts.contentFile);
+    }
+    return opts.content;
+}
+async function resolveBlockPatch(opts) {
+    const hasJsonPatch = opts.patch !== undefined || opts.patchFile !== undefined;
+    const hasStructuredPatch = [opts.type, opts.level, opts.align, opts.background]
+        .some((value) => value !== undefined);
+    if (opts.patch !== undefined && opts.patchFile !== undefined) {
+        throw new VertuError('--patch 和 --patch-file 不能同时使用。');
+    }
+    if (hasJsonPatch && hasStructuredPatch) {
+        throw new VertuError('--patch/--patch-file 不能与 --type/--level/--align/--background 混用。');
+    }
+    if (hasJsonPatch) {
+        const raw = await resolveContent({ content: opts.patch, contentFile: opts.patchFile });
+        return parseJsonArg(raw ?? '', '--patch', {
+            fileFlagSuggestion: '--patch-file',
+            requireObject: true,
+        });
+    }
+    if (!hasStructuredPatch) {
+        throw new VertuError('请提供结构化格式参数（--type/--level/--align/--background）或 --patch/--patch-file。');
+    }
+    const patch = {};
+    if (opts.type !== undefined) {
+        if (!DOCUMENT_BLOCK_TYPES.includes(opts.type)) {
+            throw new VertuError(`--type 需为 ${DOCUMENT_BLOCK_TYPES.join('、')}。`);
+        }
+        patch.type = opts.type;
+    }
+    const props = {};
+    if (opts.level !== undefined) {
+        if (!/^[1-5]$/.test(opts.level)) {
+            throw new VertuError('--level 需为 1 到 5 的整数。');
+        }
+        if (opts.type !== undefined && opts.type !== 'heading') {
+            throw new VertuError('--level 仅适用于 --type heading。');
+        }
+        props.level = Number(opts.level);
+    }
+    if (opts.align !== undefined) {
+        if (!DOCUMENT_BLOCK_ALIGNMENTS.includes(opts.align)) {
+            throw new VertuError(`--align 需为 ${DOCUMENT_BLOCK_ALIGNMENTS.join('、')}。`);
+        }
+        if (opts.type === 'codeBlock' || opts.type === 'quote') {
+            throw new VertuError(`--type ${opts.type} 不支持 --align。`);
+        }
+        props.textAlignment = opts.align;
+    }
+    if (opts.background !== undefined) {
+        if (!DOCUMENT_BLOCK_BACKGROUNDS.includes(opts.background)) {
+            throw new VertuError(`--background 需为 ${DOCUMENT_BLOCK_BACKGROUNDS.join('、')}。`);
+        }
+        if (opts.type === 'codeBlock') {
+            throw new VertuError('--type codeBlock 不支持 --background。');
+        }
+        props.backgroundColor = opts.background;
+    }
+    if (Object.keys(props).length > 0)
+        patch.props = props;
+    return patch;
+}
+function parseDocType(value) {
+    const normalized = value?.trim() || 'block';
+    if (normalized === 'block' || normalized === 'sheet' || normalized === 'folder' || normalized === 'base') {
+        return normalized;
+    }
+    throw new VertuError('--type 需为 block、sheet、folder 或 base。');
+}
+function parseScope(value) {
+    const normalized = value?.trim() || 'mine';
+    if (normalized === 'mine' || normalized === 'team' || normalized === 'trash') {
+        return normalized;
+    }
+    throw new VertuError('--scope 需为 mine、team 或 trash。');
+}
+function parseShareMode(value) {
+    const normalized = value?.trim();
+    if (normalized === 'private'
+        || normalized === 'public-view'
+        || normalized === 'public-edit'
+        || normalized === 'login-view'
+        || normalized === 'login-edit'
+        || normalized === 'team-view'
+        || normalized === 'team-edit') {
+        return normalized;
+    }
+    throw new VertuError('--mode 需为 private、public-view、public-edit、login-view、login-edit、team-view 或 team-edit。');
+}
+function parseSharePermission(value) {
+    const normalized = value?.trim() || 'request';
+    if (normalized === 'request' || normalized === 'view' || normalized === 'edit') {
+        return normalized;
+    }
+    throw new VertuError('--permission 需为 request、view 或 edit。');
+}
+function record(value, message) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new VertuError(message);
+    }
+    return value;
+}
+function text(recordValue, ...keys) {
+    for (const key of keys) {
+        const value = recordValue[key];
+        if (typeof value === 'string' && value.trim()) {
+            return value.trim();
+        }
+    }
+    return '';
+}
+function documentType(value) {
+    return value === 'sheet' || value === 'folder' || value === 'html' || value === 'base' ? value : 'block';
+}
+function documentExcerpt(value) {
+    return typeof value === 'string' ? value.replace(/\s+/g, ' ').trim().slice(0, 800) : '';
+}
+async function resolveSheetUpdates(opts) {
+    if (opts.updates !== undefined && opts.updatesFile !== undefined) {
+        throw new VertuError('--updates 和 --updates-file 不能同时使用。');
+    }
+    const raw = await resolveContent({
+        content: opts.updates,
+        contentFile: opts.updatesFile,
+    });
+    if (raw === undefined) {
+        throw new VertuError('请提供 --updates 或 --updates-file。');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new VertuError('单元格更新必须是有效 JSON。');
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new VertuError('单元格更新必须是非空 JSON 数组。');
+    }
+    return parsed;
+}
+/** 读取自动化 / Routine 快照 JSON。 */
+async function resolveAutomationDraft(opts) {
+    const raw = await resolveContent({ content: opts.draft, contentFile: opts.draftFile });
+    if (raw === undefined) {
+        throw new VertuError('请提供 --draft 或 --draft-file。');
+    }
+    return parseJsonArg(raw, '--draft', {
+        fileFlagSuggestion: '--draft-file',
+        requireObject: true,
+    });
+}
+async function resolveOptionalDraft(opts) {
+    if (opts.draft === undefined && opts.draftFile === undefined)
+        return undefined;
+    return resolveAutomationDraft(opts);
+}
+async function resolveJsonRecords(opts) {
+    if (opts.records !== undefined && opts.recordsFile !== undefined) {
+        throw new VertuError('--records 和 --records-file 不能同时使用。');
+    }
+    const raw = await resolveContent({ content: opts.records, contentFile: opts.recordsFile });
+    if (raw === undefined) {
+        throw new VertuError('请提供 --records 或 --records-file。');
+    }
+    const parsed = parseJsonArg(raw, '--records', { fileFlagSuggestion: '--records-file' });
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new VertuError('记录必须是非空 JSON 数组。');
+    }
+    return parsed;
+}
+/** 解析逗号分隔的记录 ID；空值直接抛错。 */
+function parseRecordIds(value) {
+    const ids = (value ?? '').split(',').map((item) => item.trim()).filter(Boolean);
+    if (ids.length === 0)
+        throw new VertuError('--ids 必须是非空的记录 ID 列表。');
+    return ids;
+}
+/** 组装 Teable 风格的视图锚点插入参数。 */
+function recordOrder(opts) {
+    const position = required(opts.position, '--position');
+    if (position !== 'before' && position !== 'after') {
+        throw new VertuError('--position 必须是 before 或 after。');
+    }
+    return {
+        anchorId: required(opts.anchorId, '--anchor-id'),
+        position,
+        viewId: required(opts.viewId, '--view-id'),
+    };
+}
+function positiveIntegerEnv(...keys) {
+    for (const key of keys) {
+        const raw = process.env[key]?.trim();
+        if (raw && /^\d+$/.test(raw)) {
+            const value = Number(raw);
+            if (Number.isSafeInteger(value) && value > 0) {
+                return value;
+            }
+        }
+    }
+    return undefined;
+}
+function firstEnv(...keys) {
+    for (const key of keys) {
+        const value = process.env[key]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return '';
+}
+export function buildDocumentsCommand() {
+    const documents = new Command('docs').description('企业云文档：查询、读取、新建、更新、共享、复制与导出。');
+    attachBaseOptions(documents
+        .command('+list')
+        .description('列出当前用户可访问的云文档')
+        .option('--query <text>', '按标题搜索')
+        .option('--scope <scope>', 'mine / team / trash', 'mine')
+        .option('--team-id <id>', '团队范围内限定团队 ID')).action(async (opts) => {
+        const scope = parseScope(opts.scope);
+        const payload = await documentsRequest('GET', '/v1/documents', {
+            baseUrl: opts.baseUrl,
+            query: {
+                q: opts.query,
+                scope: scope === 'mine' ? undefined : scope,
+                teamId: opts.teamId,
+            },
+        });
+        printDocumentsResult(opts.json, payload);
+    });
+    attachBaseOptions(documents
+        .command('+get')
+        .description('读取文档详情与可提取正文')
+        .requiredOption('--doc-id <id>', '文档 ID')).action(async (opts) => {
+        const payload = await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id')), { baseUrl: opts.baseUrl });
+        printDocumentsResult(opts.json, payload);
+    });
+    attachBaseOptions(documents
+        .command('+create')
+        .description('新建文档、智能表格、多维表或文件夹')
+        .requiredOption('--title <title>', '标题')
+        .option('--type <type>', 'block / sheet / folder / base', 'block')
+        .option('--content <text>', '新建文档的 Markdown 初始正文')
+        .option('--content-file <path>', '从 UTF-8 文件读取初始正文；- 表示 stdin')
+        .option('--parent-id <id>', '父文件夹 ID')).action(async (opts) => {
+        const type = parseDocType(opts.type);
+        const content = await resolveContent(opts);
+        if (content !== undefined && type !== 'block') {
+            throw new VertuError('--content / --content-file 当前仅支持 block 文档。');
+        }
+        const payload = await documentsRequest('POST', '/v1/documents', {
+            baseUrl: opts.baseUrl,
+            body: {
+                title: required(opts.title, '--title'),
+                type,
+                parentId: opts.parentId?.trim() || null,
+                ...(content === undefined
+                    ? {}
+                    : { initialPayload: JSON.stringify({ format: 'markdown', content }) }),
+            },
+        });
+        printDocumentsResult(opts.json, payload);
+    });
+    attachBaseOptions(documents
+        .command('+rename')
+        .description('重命名文档、表格或文件夹')
+        .requiredOption('--doc-id <id>', '文档 ID')
+        .requiredOption('--title <title>', '新标题')).action(async (opts) => {
+        const payload = await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), '/rename'), {
+            baseUrl: opts.baseUrl,
+            body: { title: required(opts.title, '--title') },
+        });
+        printDocumentsResult(opts.json, payload);
+    });
+    attachBaseOptions(documents
+        .command('+set-content')
+        .description('仅为尚未进入实时协作的文档设置 Markdown 正文')
+        .requiredOption('--doc-id <id>', '文档 ID')
+        .option('--content <text>', 'Markdown 正文')
+        .option('--content-file <path>', '从 UTF-8 文件读取正文；- 表示 stdin')).action(async (opts) => {
+        const content = await resolveContent(opts);
+        if (content === undefined) {
+            throw new VertuError('请提供 --content 或 --content-file。');
+        }
+        const payload = await documentsRequest('PUT', documentPath(required(opts.docId, '--doc-id'), '/content'), { baseUrl: opts.baseUrl, body: { content } });
+        printDocumentsResult(opts.json, payload);
+    });
+    attachBaseOptions(documents
+        .command('+block-schema')
+        .description('返回 Agent 可读取的块类型、格式属性和并发规则')).action(async (opts) => {
+        const payload = await documentsRequest('GET', '/v1/documents/capabilities/blocks', { baseUrl: opts.baseUrl });
+        printDocumentsResult(opts.json, payload);
+    });
+    attachBaseOptions(documents
+        .command('+get-blocks')
+        .description('读取协作块文档的块 ID、格式属性和并发版本')
+        .requiredOption('--doc-id <id>', '文档 ID')).action(async (opts) => {
+        const payload = await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), '/blocks'), { baseUrl: opts.baseUrl });
+        printDocumentsResult(opts.json, payload);
+    });
+    const updateBlock = documents
+        .command('+update-block')
+        .description('按稳定 block ID 精确更新协作文档段落格式')
+        .requiredOption('--doc-id <id>', '文档 ID')
+        .requiredOption('--block-id <id>', '块 ID')
+        .option('--expected-version <version>', '由 +get-blocks 返回的并发版本')
+        .option('--type <type>', 'paragraph / heading / numberedListItem / bulletListItem / checkListItem / codeBlock / quote')
+        .option('--level <1-5>', '标题级别；仅适用于 heading')
+        .option('--align <alignment>', 'left / center / right')
+        .option('--background <color>', 'default / yellow')
+        .option('--patch <json>', '高级格式 patch JSON；不能与结构化格式参数混用')
+        .option('--patch-file <path>', '从 UTF-8 JSON 文件读取高级 patch；- 表示 stdin');
+    updateBlock.addHelpText('after', `
+Workflow:
+  1. vps-work docs +block-schema
+  2. vps-work docs +get-blocks --doc-id <uuid>
+  3. Use blocks[].id and version in +update-block.
+
+Examples:
+  $ vps-work docs +update-block --doc-id <uuid> --block-id <id> --expected-version <version> --type heading --level 2 --align center --background yellow
+  $ vps-work docs +update-block --doc-id <uuid> --block-id <id> --expected-version <version> --patch-file ./patch.json
+
+Notes:
+  --level requires heading. quote/codeBlock do not support --align; codeBlock does not support --background.
+  On a version conflict, run +get-blocks again and verify the target block before retrying.
+`);
+    attachBaseOptions(updateBlock).action(async (opts) => {
+        const docId = required(opts.docId, '--doc-id');
+        const blockId = required(opts.blockId, '--block-id');
+        const payload = await documentsRequest('PATCH', documentPath(docId, `/blocks/${encodeURIComponent(blockId)}`), {
+            baseUrl: opts.baseUrl,
+            body: {
+                expectedVersion: opts.expectedVersion?.trim() || undefined,
+                patch: await resolveBlockPatch(opts),
+            },
+        });
+        printDocumentsResult(opts.json, payload);
+    });
+    attachBaseOptions(documents
+        .command('+sheet-get')
+        .description('读取智能表格的当前工作簿数据')
+        .requiredOption('--doc-id <id>', '智能表格文档 ID')).action(async (opts) => {
+        const payload = await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), '/sheet'), { baseUrl: opts.baseUrl });
+        printDocumentsResult(opts.json, payload);
+    });
+    attachBaseOptions(documents
+        .command('+sheet-set-cells')
+        .description('批量更新智能表格单元格；value=null 表示清空')
+        .requiredOption('--doc-id <id>', '智能表格文档 ID')
+        .option('--sheet <id-or-name>', '工作表 ID 或名称；默认第一张工作表')
+        .option('--updates <json>', '单元格更新 JSON 数组')
+        .option('--updates-file <path>', '从 UTF-8 JSON 文件读取更新；- 表示 stdin')).action(async (opts) => {
+        const payload = await documentsRequest('PUT', documentPath(required(opts.docId, '--doc-id'), '/sheet'), {
+            baseUrl: opts.baseUrl,
+            body: {
+                cells: await resolveSheetUpdates(opts),
+                sheet: opts.sheet?.trim() || undefined,
+            },
+        });
+        printDocumentsResult(opts.json, payload);
+    });
+    attachBaseOptions(documents
+        .command('+base-schema')
+        .description('读取多维表的表、字段和视图')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), '/base'), {
+            baseUrl: opts.baseUrl,
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-tables')
+        .description('列出多维表中的数据表')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')).action(async (opts) => {
+        const payload = await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), '/base'), { baseUrl: opts.baseUrl });
+        printDocumentsResult(opts.json, { tables: payload.base?.tables ?? [] });
+    });
+    attachBaseOptions(documents
+        .command('+base-create-table')
+        .description('新建一张数据表')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--name <name>', '数据表名称')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), '/base/tables'), {
+            baseUrl: opts.baseUrl,
+            body: { name: required(opts.name, '--name') },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-records')
+        .description('读取多维表记录')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .option('--view-id <id>', '按视图过滤')
+        .option('--query <text>', '关键字搜索')
+        .option('--limit <n>', '返回条数')
+        .option('--archived', '只列归档记录')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/records`), {
+            baseUrl: opts.baseUrl,
+            query: {
+                archived: opts.archived ? '1' : undefined,
+                limit: opts.limit,
+                q: opts.query,
+                viewId: opts.viewId,
+            },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-create-records')
+        .description('批量新增记录，fields 使用字段 ID')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .option('--records <json>', '记录 JSON 数组')
+        .option('--records-file <path>', '从 UTF-8 JSON 文件读取记录；- 表示 stdin')
+        .option('--view-id <id>', '插入到指定视图锚点')
+        .option('--anchor-id <id>', '锚点记录 ID')
+        .option('--position <before|after>', '插到锚点前或后')).action(async (opts) => {
+        const order = opts.viewId || opts.anchorId || opts.position ? recordOrder(opts) : undefined;
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/records`), {
+            baseUrl: opts.baseUrl,
+            body: { order, records: await resolveJsonRecords(opts) },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-update-records')
+        .description('批量更新记录，每项需含 id 和 fields')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .option('--records <json>', '更新 JSON 数组')
+        .option('--records-file <path>', '从 UTF-8 JSON 文件读取更新；- 表示 stdin')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('PATCH', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/records`), {
+            baseUrl: opts.baseUrl,
+            body: { records: await resolveJsonRecords(opts) },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-insert-records')
+        .description('在锚点前/后插入空记录')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--view-id <id>', '视图 ID')
+        .requiredOption('--anchor-id <id>', '锚点记录 ID')
+        .requiredOption('--position <before|after>', '插到锚点前或后')
+        .option('--count <n>', '插入条数，1–1000，默认 1')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/records/insert`), {
+            baseUrl: opts.baseUrl,
+            body: { count: opts.count === undefined ? 1 : Number(opts.count), order: recordOrder(opts) },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-duplicate-records')
+        .description('复制记录并插到最后一条之后')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--view-id <id>', '视图 ID')
+        .requiredOption('--ids <ids>', '逗号分隔的记录 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/records/duplicate`), {
+            baseUrl: opts.baseUrl,
+            body: { ids: parseRecordIds(opts.ids), viewId: required(opts.viewId, '--view-id') },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-reorder-records')
+        .description('按当前视图把记录拖到 dropIndex')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--view-id <id>', '视图 ID')
+        .requiredOption('--ids <ids>', '逗号分隔的记录 ID')
+        .requiredOption('--drop-index <n>', '目标位置')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/records/reorder`), {
+            baseUrl: opts.baseUrl,
+            body: {
+                dropIndex: Number(required(opts.dropIndex, '--drop-index')),
+                ids: parseRecordIds(opts.ids),
+                viewId: required(opts.viewId, '--view-id'),
+            },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-archive-records')
+        .description('归档记录')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--ids <ids>', '逗号分隔的记录 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/records/archive`), {
+            baseUrl: opts.baseUrl,
+            body: { ids: parseRecordIds(opts.ids) },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-restore-records')
+        .description('从归档区恢复记录')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--ids <ids>', '逗号分隔的记录 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/records/restore`), {
+            baseUrl: opts.baseUrl,
+            body: { ids: parseRecordIds(opts.ids) },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-create-field')
+        .description('新增字段')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--name <name>', '字段名称')
+        .requiredOption('--type <type>', 'Teable 字段类型，如 singleLineText / rating / formula / link / rollup / conditionalRollup / autoNumber / createdTime')
+        .option('--choices <json>', '单选/多选选项 JSON 数组')
+        .option('--multiple', '人员字段允许多人')
+        .option('--expression <expr>', '公式或汇总表达式')
+        .option('--foreign-table <id>', '关联 / 条件汇总目标表')
+        .option('--relationship <rel>', '关联关系 oneOne / manyMany / oneMany / manyOne')
+        .option('--one-way', '单向关联，不创建对称字段')
+        .option('--lookup', '查找模式')
+        .option('--conditional-lookup', '条件查找模式')
+        .option('--lookup-options <json>', '查找 / 汇总 lookupOptions JSON')
+        .option('--view-id <id>', '插入到该视图的列序')
+        .option('--order <n>', '插入列的 columnMeta.order')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/fields`), {
+            baseUrl: opts.baseUrl,
+            body: {
+                isConditionalLookup: opts.conditionalLookup === true || undefined,
+                isLookup: opts.lookup === true || opts.conditionalLookup === true || undefined,
+                lookupOptions: opts.lookupOptions
+                    ? parseJsonArg(opts.lookupOptions, '--lookup-options')
+                    : undefined,
+                name: required(opts.name, '--name'),
+                options: fieldOptions(opts),
+                order: opts.order === undefined ? undefined : Number(opts.order),
+                type: required(opts.type, '--type'),
+                viewId: opts.viewId,
+            },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-views')
+        .description('列出数据表视图')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/views`), { baseUrl: opts.baseUrl }));
+    });
+    attachBaseOptions(documents
+        .command('+base-create-view')
+        .description('新建只读视图定义')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--name <name>', '视图名称')
+        .option('--type <type>', 'grid / kanban / form', 'grid')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/views`), {
+            baseUrl: opts.baseUrl,
+            body: { name: required(opts.name, '--name'), type: opts.type ?? 'grid' },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-lock-view')
+        .description('锁定或解锁视图配置')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--view-id <id>', '视图 ID')
+        .requiredOption('--locked <bool>', 'true 锁定 / false 解锁')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('PATCH', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/views/${encodeURIComponent(required(opts.viewId, '--view-id'))}/locked`), {
+            baseUrl: opts.baseUrl,
+            body: { isLocked: parseLockedFlag(opts.locked) },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-update-view')
+        .description('更新视图配置，可设置冻结列')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--view-id <id>', '视图 ID')
+        .option('--frozen-field-id <id>', '冻结至此字段')
+        .option('--config-file <path>', '完整视图 config JSON')).action(async (opts) => {
+        if (!opts.configFile && opts.frozenFieldId === undefined) {
+            throw new VertuError('请提供 --frozen-field-id 或 --config-file。');
+        }
+        const tablePath = `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}`;
+        const listed = await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), `${tablePath}/views`), { baseUrl: opts.baseUrl });
+        const current = listed.items?.find((item) => item.id === required(opts.viewId, '--view-id'));
+        if (!current)
+            throw new VertuError('找不到指定视图。');
+        const config = opts.configFile
+            ? parseJsonArg(await readUtf8File(opts.configFile), '--config-file')
+            : { ...(current.config ?? {}) };
+        if (opts.frozenFieldId !== undefined) {
+            if (!opts.frozenFieldId.trim())
+                delete config.frozenFieldId;
+            else
+                config.frozenFieldId = opts.frozenFieldId.trim();
+        }
+        printDocumentsResult(opts.json, await documentsRequest('PATCH', documentPath(required(opts.docId, '--doc-id'), `${tablePath}/views/${encodeURIComponent(required(opts.viewId, '--view-id'))}`), { baseUrl: opts.baseUrl, body: { config } }));
+    });
+    attachBaseOptions(documents
+        .command('+base-create-mirror')
+        .description('从指定视图创建镜像表')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--view-id <id>', '源视图 ID')
+        .requiredOption('--name <name>', '镜像表名称')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/mirrors`), {
+            baseUrl: opts.baseUrl,
+            body: { name: required(opts.name, '--name'), viewId: required(opts.viewId, '--view-id') },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-rename-mirror')
+        .description('重命名镜像表')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--mirror-id <id>', '镜像表 ID')
+        .requiredOption('--name <name>', '新名称')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('PATCH', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/mirrors/${encodeURIComponent(required(opts.mirrorId, '--mirror-id'))}`), { baseUrl: opts.baseUrl, body: { name: required(opts.name, '--name') } }));
+    });
+    attachBaseOptions(documents
+        .command('+base-delete-mirror')
+        .description('删除镜像表')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--mirror-id <id>', '镜像表 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('DELETE', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/mirrors/${encodeURIComponent(required(opts.mirrorId, '--mirror-id'))}`), { baseUrl: opts.baseUrl }));
+    });
+    attachBaseOptions(documents
+        .command('+base-set-mirror-grants')
+        .description('覆盖镜像表通讯录授权')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--mirror-id <id>', '镜像表 ID')
+        .requiredOption('--grants-file <path>', '授权 JSON 数组')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('PUT', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/mirrors/${encodeURIComponent(required(opts.mirrorId, '--mirror-id'))}/grants`), {
+            baseUrl: opts.baseUrl,
+            body: { grants: parseJsonArg(await readUtf8File(required(opts.grantsFile, '--grants-file')), '--grants-file') },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-record-history')
+        .description('读取一条记录的字段变更历史')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--record <id>', '记录 ID')
+        .option('--start-date <date>', '起始日期')
+        .option('--end-date <date>', '结束日期')
+        .option('--field-ids <ids>', '字段 ID，逗号分隔')
+        .option('--created-by-ids <ids>', '修改人 ID，逗号分隔')
+        .option('--cursor <cursor>', '分页游标')
+        .option('--mirror-id <id>', '镜像表 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/records/${encodeURIComponent(required(opts.record, '--record'))}/history`), { baseUrl: opts.baseUrl, query: historyQuery(opts) }));
+    });
+    attachBaseOptions(documents
+        .command('+base-table-history')
+        .description('读取整表字段变更历史')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .option('--start-date <date>', '起始日期')
+        .option('--end-date <date>', '结束日期')
+        .option('--field-ids <ids>', '字段 ID，逗号分隔')
+        .option('--created-by-ids <ids>', '修改人 ID，逗号分隔')
+        .option('--cursor <cursor>', '分页游标')
+        .option('--mirror-id <id>', '镜像表 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/records/history`), { baseUrl: opts.baseUrl, query: historyQuery(opts) }));
+    });
+    attachBaseOptions(documents
+        .command('+base-import')
+        .description('从 CSV 导入记录')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .option('--csv <text>', 'CSV 文本')
+        .option('--csv-file <path>', '从 UTF-8 文件读取 CSV；- 表示 stdin')).action(async (opts) => {
+        const csv = await resolveContent({ content: opts.csv, contentFile: opts.csvFile });
+        if (csv === undefined) {
+            throw new VertuError('请提供 --csv 或 --csv-file。');
+        }
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/import`), { baseUrl: opts.baseUrl, body: { csv, hasHeader: true } }));
+    });
+    attachBaseOptions(documents
+        .command('+base-export')
+        .description('导出当前视图或全表为 CSV')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .option('--view-id <id>', '按视图导出')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/export`), { baseUrl: opts.baseUrl, query: { viewId: opts.viewId } }));
+    });
+    attachBaseOptions(documents
+        .command('+base-workflows')
+        .description('列出多维表自动化工作流')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), '/base/workflows'), {
+            baseUrl: opts.baseUrl,
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-create-workflow')
+        .description('创建自动化工作流草稿')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--name <name>', '工作流名称')
+        .option('--draft <json>', '工作流快照 JSON')
+        .option('--draft-file <path>', '从 UTF-8 JSON 文件读取快照；- 表示 stdin')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), '/base/workflows'), {
+            baseUrl: opts.baseUrl,
+            body: { draft: await resolveAutomationDraft(opts), name: required(opts.name, '--name') },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-update-workflow')
+        .description('更新自动化工作流草稿')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--workflow-id <id>', '工作流 ID')
+        .option('--name <name>', '工作流名称')
+        .option('--draft <json>', '工作流快照 JSON')
+        .option('--draft-file <path>', '从 UTF-8 JSON 文件读取快照；- 表示 stdin')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('PATCH', documentPath(required(opts.docId, '--doc-id'), `/base/workflows/${encodeURIComponent(required(opts.workflowId, '--workflow-id'))}`), {
+            baseUrl: opts.baseUrl,
+            body: {
+                draft: await resolveOptionalDraft(opts),
+                name: opts.name,
+            },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-apply-workflow')
+        .description('发布并启用自动化工作流')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--workflow-id <id>', '工作流 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/workflows/${encodeURIComponent(required(opts.workflowId, '--workflow-id'))}/apply`), { baseUrl: opts.baseUrl }));
+    });
+    attachBaseOptions(documents
+        .command('+base-workflow-runs')
+        .description('查看自动化运行历史')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--workflow-id <id>', '工作流 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), `/base/workflows/${encodeURIComponent(required(opts.workflowId, '--workflow-id'))}/runs`), { baseUrl: opts.baseUrl }));
+    });
+    attachBaseOptions(documents
+        .command('+base-rerun-workflow')
+        .description('重跑失败的自动化')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--workflow-id <id>', '工作流 ID')
+        .requiredOption('--run-id <id>', '运行 ID')
+        .option('--mode <mode>', 'full / resumeFromFailedStep', 'full')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/workflows/${encodeURIComponent(required(opts.workflowId, '--workflow-id'))}/runs/${encodeURIComponent(required(opts.runId, '--run-id'))}/rerun`), { baseUrl: opts.baseUrl, body: { mode: opts.mode === 'resumeFromFailedStep' ? 'resumeFromFailedStep' : 'full' } }));
+    });
+    attachBaseOptions(documents
+        .command('+base-routines')
+        .description('列出多维表 Routine')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), '/base/routines'), {
+            baseUrl: opts.baseUrl,
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-create-routine')
+        .description('创建 Routine 草稿')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--name <name>', 'Routine 名称')
+        .option('--draft <json>', 'Routine 快照 JSON')
+        .option('--draft-file <path>', '从 UTF-8 JSON 文件读取快照；- 表示 stdin')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), '/base/routines'), {
+            baseUrl: opts.baseUrl,
+            body: { draft: await resolveAutomationDraft(opts), name: required(opts.name, '--name') },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-apply-routine')
+        .description('发布并启用 Routine')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--routine-id <id>', 'Routine ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/routines/${encodeURIComponent(required(opts.routineId, '--routine-id'))}/apply`), { baseUrl: opts.baseUrl }));
+    });
+    attachBaseOptions(documents
+        .command('+base-run-routine')
+        .description('立即运行 Routine')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--routine-id <id>', 'Routine ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/routines/${encodeURIComponent(required(opts.routineId, '--routine-id'))}/run`), { baseUrl: opts.baseUrl }));
+    });
+    attachBaseOptions(documents
+        .command('+base-secrets')
+        .description('列出自动化密钥名称')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('GET', documentPath(required(opts.docId, '--doc-id'), '/base/secrets'), {
+            baseUrl: opts.baseUrl,
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-put-secret')
+        .description('写入自动化密钥')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--name <name>', '密钥名')
+        .requiredOption('--value <value>', '密钥值')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), '/base/secrets'), {
+            baseUrl: opts.baseUrl,
+            body: { name: required(opts.name, '--name'), value: required(opts.value, '--value') },
+        }));
+    });
+    attachBaseOptions(documents
+        .command('+base-click-button')
+        .description('点击多维表按钮字段并触发自动化')
+        .requiredOption('--doc-id <id>', '多维表文档 ID')
+        .requiredOption('--table <id>', '数据表 ID')
+        .requiredOption('--record <id>', '记录 ID')
+        .requiredOption('--field-id <id>', '按钮字段 ID')).action(async (opts) => {
+        printDocumentsResult(opts.json, await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), `/base/tables/${encodeURIComponent(required(opts.table, '--table'))}/records/${encodeURIComponent(required(opts.record, '--record'))}/fields/${encodeURIComponent(required(opts.fieldId, '--field-id'))}/click`), { baseUrl: opts.baseUrl }));
+    });
+    attachBaseOptions(documents
+        .command('+share')
+        .description('设置链接或企业内部共享权限')
+        .requiredOption('--doc-id <id>', '文档 ID')
+        .requiredOption('--mode <mode>', 'private / public-view / public-edit / login-view / login-edit / team-view / team-edit')).action(async (opts) => {
+        const payload = await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), '/share'), {
+            baseUrl: opts.baseUrl,
+            body: { mode: parseShareMode(opts.mode) },
+        });
+        printDocumentsResult(opts.json, payload);
+    });
+    attachBaseOptions(documents
+        .command('+send')
+        .description('把云文档卡片发送到当前 Hermes/VPS IM 会话')
+        .requiredOption('--doc-id <id>', '文档 ID')
+        .option('--permission <permission>', 'request / view / edit', 'request')
+        .option('--channel-id <id>', '目标 IM 会话 id；Hermes 中默认使用当前会话')).action(async (opts) => {
+        const docId = required(opts.docId, '--doc-id');
+        const permission = parseSharePermission(opts.permission);
+        const detail = record(await documentsRequest('GET', documentPath(docId), { baseUrl: opts.baseUrl }), '文档详情响应无效。');
+        const doc = record(detail.doc, '文档详情缺少 doc。');
+        const title = text(doc, 'title') || '未命名文档';
+        const type = documentType(doc.type);
+        let shareToken = text(doc, 'shareToken', 'share_token');
+        let shareMode = text(doc, 'shareMode', 'share_mode') || null;
+        if (permission !== 'request') {
+            shareMode = permission === 'edit' ? 'login-edit' : 'login-view';
+            const share = record(await documentsRequest('POST', documentPath(docId, '/share'), {
+                baseUrl: opts.baseUrl,
+                body: { mode: shareMode },
+            }), '文档共享响应无效。');
+            shareToken = text(share, 'token') || shareToken;
+        }
+        const channelId = opts.channelId?.trim() || firstEnv('VERTU_AGENT_CHANNEL_ID');
+        const agentSlug = firstEnv('VERTU_AGENT_SLUG', 'HERMES_AGENT_SLUG');
+        const agentName = firstEnv('VERTU_AGENT_NAME', 'VERTU_AGENT_PROFILE_NAME');
+        const sessionId = firstEnv('VERTU_AGENT_SESSION_ID', 'HERMES_SESSION_ID');
+        const userId = positiveIntegerEnv('VERTU_AGENT_USER_ID', 'VERTU_AGENT_ODOO_USER_ID');
+        if (!channelId && !agentSlug) {
+            throw new VertuError('无法确定目标会话：请在 Hermes 当前会话中执行，或提供 --channel-id。');
+        }
+        const clientMessageId = `docs-share-${randomUUID()}`;
+        const metadata = {
+            card: 'document_share',
+            document_id: docId,
+            title,
+            creator_name: text(doc, 'creatorName', 'creator_name') || '文档成员',
+            share_url: shareToken ? `vertu://documents/share/${shareToken}` : '',
+            excerpt: documentExcerpt(doc.content),
+            document_type: type,
+            permission,
+        };
+        const message = {
+            body: `[文档] ${title}`,
+            message_type: 'interactive_card',
+            client_message_id: clientMessageId,
+            idempotency_key: clientMessageId,
+            metadata,
+        };
+        const delivery = agentSlug
+            ? await imRequest('POST', '/v1/im/agents/hermes/notify', {
+                baseUrl: opts.baseUrl,
+                body: {
+                    ...message,
+                    agent_slug: agentSlug,
+                    ...(agentName ? { agent_name: agentName } : {}),
+                    ...(sessionId ? { session_id: sessionId } : {}),
+                    ...(channelId ? { channel_id: channelId } : {}),
+                    ...(userId ? { user_id: userId } : {}),
+                    event_id: clientMessageId,
+                },
+            })
+            : await imRequest('POST', `/v1/im/channels/${encodeURIComponent(channelId)}/messages`, { baseUrl: opts.baseUrl, body: message });
+        const deliveryRecord = record(delivery, 'IM 投递响应无效。');
+        printDocumentsResult(opts.json, {
+            ok: true,
+            document: { id: docId, title, type },
+            permission,
+            share_mode: shareMode,
+            channel_id: text(deliveryRecord, 'channel_id') || channelId || null,
+            message: deliveryRecord.message ?? null,
+        });
+    });
+    for (const [name, description, suffix] of [
+        ['+duplicate', '复制文档或表格', '/duplicate'],
+        ['+export', '导出文档原始数据与协作状态', '/export'],
+        ['+export-markdown', '将文档导出为 Markdown 文本', '/export-markdown'],
+    ]) {
+        attachBaseOptions(documents
+            .command(name)
+            .description(description)
+            .requiredOption('--doc-id <id>', '文档 ID')).action(async (opts) => {
+            const payload = await documentsRequest('POST', documentPath(required(opts.docId, '--doc-id'), suffix), { baseUrl: opts.baseUrl });
+            printDocumentsResult(opts.json, payload);
+        });
+    }
+    documents.addHelpText('after', `
+Agent block-format workflow:
+  vps-work docs +block-schema
+  vps-work docs +get-blocks --doc-id <uuid>
+  vps-work docs +update-block --doc-id <uuid> --block-id <id> --expected-version <version> --type heading --level 2 --align center
+`);
+    return documents;
+}