@lark-base-open/base-database-cli 1.3.9 → 1.4.3

package/dist/ai-functions.js

@@ -1,9 +1,12 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
+import { assertFunctionResults, functionEnv, getFunction, listFunctions, putFunctions, } from './unified-functions.js';
+import { responseFunctionHints, AGENT_TOOL_DESIGN_REFERENCE, } from './function-params.js';
+import { normalizeFunctionInputSchema } from './function-schema.js';
 import { readConfig } from './config.js';
 import { assertProjectRuntimeProfile, ONLINE_RUNTIME_PROFILE, } from './environment.js';
 import { LarkCliError } from './lark-cli-error.js';
-import { responseData, runLarkCli } from './lark-cli.js';
+import { responseData, runLarkCli, resolveLarkProfileEnvironment, } from './lark-cli.js';
 // 服务端对 AI Function 管理接口（list/get/upsert/delete/validate/update/usage）做用户级 feature gate，
 // 未开通时返回 800004011 "ai function feature is not enabled"。这不是 scope 缺失，重新登录无法解决；
 // 这里把它翻译成可执行的降级路径，避免 Agent 把它当作权限错误循环授权。
@@ -11,11 +14,13 @@ export const AI_FUNCTION_FEATURE_NOT_ENABLED_CODE = 800004011;
 export const AI_FUNCTION_FEATURE_NOT_ENABLED_MESSAGE = 'AI Function management is not enabled for the current user (800004011). This is a feature gate, not a missing scope, so `auth login` does not help. Publish without AI Functions via `deploy --skip-ai-functions` (or remove ai/) and report the AI Function part as blocked.';
 export function isAIFunctionFeatureNotEnabled(error) {
     return (error instanceof LarkCliError &&
-        Number(error.details.code) === AI_FUNCTION_FEATURE_NOT_ENABLED_CODE);
+        Number(error.details.code) === AI_FUNCTION_FEATURE_NOT_ENABLED_CODE &&
+        /ai function feature is not enabled|AI Function management is not enabled/i.test(error.details.message));
 }
-function aiFunctionAccessError(error) {
+export function aiFunctionAccessError(error) {
     if (error instanceof LarkCliError &&
-        Number(error.details.code) === AI_FUNCTION_FEATURE_NOT_ENABLED_CODE) {
+        Number(error.details.code) === AI_FUNCTION_FEATURE_NOT_ENABLED_CODE &&
+        /ai function feature is not enabled|AI Function management is not enabled/i.test(error.details.message)) {
         return new LarkCliError({
             ...error.details,
             message: AI_FUNCTION_FEATURE_NOT_ENABLED_MESSAGE,
@@ -32,14 +37,89 @@ function runAIFunctionApi(args, env, cwd) {
     }
 }
 // AI Function 是「功能清单」里的一类声明式资源（function_type=4）：model/System Prompt/能力配置都在
-// ai/<functionKey>/meta.json 里维护，随 deploy 走 OpenAPI 全量覆盖同步。不进 site.zip（不是部署代码，是配置）。
+// ai/<functionKey>/meta.json 里维护，随 deploy 走 OpenAPI 全量覆盖同步。随 site.zip 保存源声明，pull 以远端草稿详情恢复配置。
 const FUNCTION_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
-const MAX_AI_FUNCTIONS = 200;
 const AI_FUNCTIONS_DIR = 'ai';
 const CAPABILITY_TYPES = new Set(['text', 'vision', 'image', 'video']);
+function parseAIJSON(source) {
+    const json = JSON;
+    return JSON.parse(source, (_key, value, context) => {
+        if (typeof value !== 'number')
+            return value;
+        if (json.rawJSON && context?.source)
+            return json.rawJSON(context.source);
+        if (!Number.isFinite(value) ||
+            (Number.isInteger(value) && !Number.isSafeInteger(value)))
+            throw new RangeError('Exact AI numeric defaults require Node.js 22');
+        return value;
+    });
+}
 function stripPlatformManagedFields(config) {
     const normalized = { ...config };
     delete normalized.limits;
+    delete normalized.output_mode;
+    if (normalized.variables !== undefined) {
+        process.stderr.write('Warning: AI config.variables 已弃用，请将 meta.json 迁移为 config.input_schema。\n');
+    }
+    if (normalized.input_schema === undefined) {
+        const properties = Object.create(null);
+        const required = [];
+        const variables = normalized.variables ?? [];
+        if (!Array.isArray(variables))
+            throw new Error('AI variables must be an array');
+        for (const variable of [...variables].sort((a, b) => String(a?.name) < String(b?.name)
+            ? -1
+            : String(a?.name) > String(b?.name)
+                ? 1
+                : 0)) {
+            if (!variable ||
+                typeof variable.name !== 'string' ||
+                !['string', 'number', 'boolean', 'object'].includes(variable.type))
+                throw new Error('Invalid legacy AI variable declaration');
+            if (Object.hasOwn(properties, variable.name))
+                throw new Error(`Duplicate AI variable: ${variable.name}`);
+            const property = variable.type === 'object'
+                ? { oneOf: [{ type: 'object' }, { type: 'array' }] }
+                : { type: variable.type };
+            if (typeof variable.description === 'string')
+                property.description = variable.description;
+            if (variable.default !== undefined && variable.default !== '') {
+                try {
+                    const value = variable.type === 'string'
+                        ? variable.default
+                        : JSON.parse(variable.default);
+                    if (variable.type === 'object'
+                        ? value === null || typeof value !== 'object'
+                        : typeof value !== variable.type)
+                        throw new Error('type');
+                    property.default =
+                        variable.type === 'string' ? value : parseAIJSON(variable.default);
+                }
+                catch (error) {
+                    if (error instanceof RangeError)
+                        throw error;
+                    process.stderr.write(`Warning: AI variable ${variable.name}: invalid default omitted.\n`);
+                }
+            }
+            properties[variable.name] = property;
+            if (variable.required === true && !Object.hasOwn(property, 'default'))
+                required.push(variable.name);
+        }
+        normalized.input_schema = {
+            type: 'object',
+            properties,
+            ...(required.length ? { required } : {}),
+            additionalProperties: true,
+        };
+    }
+    else {
+        normalizeFunctionInputSchema(normalized.input_schema, 'AI config.input_schema');
+    }
+    if (!normalized.input_schema ||
+        typeof normalized.input_schema !== 'object' ||
+        normalized.input_schema.type !== 'object')
+        throw new Error('AI input_schema must have type object');
+    delete normalized.variables;
     const text = config.text;
     if (text && typeof text === 'object' && !Array.isArray(text)) {
         const rest = { ...text };
@@ -58,7 +138,7 @@ function readAIFunctionMeta(path) {
         !FUNCTION_ID_PATTERN.test(functionKey)) {
         throw new Error(`Invalid AI Function key: ${functionKey}`);
     }
-    const manifest = JSON.parse(readFileSync(path, 'utf8'));
+    const manifest = parseAIJSON(readFileSync(path, 'utf8'));
     if (typeof manifest.name !== 'string' || manifest.name === '') {
         throw new Error(`AI Function name must be a non-empty string: ${path}`);
     }
@@ -66,7 +146,9 @@ function readAIFunctionMeta(path) {
         typeof manifest.description !== 'string') {
         throw new Error(`AI Function description must be a string: ${path}`);
     }
-    if (!manifest.config || typeof manifest.config !== 'object') {
+    if (!manifest.config ||
+        typeof manifest.config !== 'object' ||
+        Array.isArray(manifest.config)) {
         throw new Error(`AI Function config must be an object: ${path}`);
     }
     const config = stripPlatformManagedFields(manifest.config);
@@ -81,114 +163,116 @@ function readAIFunctionMeta(path) {
         name: manifest.name,
     };
 }
-// collectLocalAIFunctions 读取 ai/<key>/meta.json 全集（本地声明），供 deploy 全量覆盖同步与 sync 命令共用。
-export function collectLocalAIFunctions(workspace) {
+/** Inventory does not parse AI configuration, so skip can still bypass invalid AI metadata. */
+export function localAIFunctionKeys(workspace) {
     const root = aiFunctionsRoot(workspace);
-    if (!existsSync(root)) {
+    if (!existsSync(root))
         return [];
-    }
-    const items = [];
-    const seen = new Set();
-    for (const entry of readdirSync(root, { withFileTypes: true })) {
-        if (!entry.isDirectory())
-            continue;
+    return readdirSync(root, { withFileTypes: true })
+        .filter((entry) => {
         const path = join(root, entry.name, 'meta.json');
-        if (!existsSync(path) || !statSync(path).isFile())
-            continue;
-        const item = readAIFunctionMeta(path);
-        if (seen.has(item.functionKey)) {
-            throw new Error(`Duplicate AI Function key: ${item.functionKey}`);
-        }
-        seen.add(item.functionKey);
-        items.push(item);
-    }
-    if (items.length > MAX_AI_FUNCTIONS) {
-        throw new Error(`AI Functions cannot exceed ${MAX_AI_FUNCTIONS}`);
-    }
-    return items;
+        return entry.isDirectory() && existsSync(path) && statSync(path).isFile();
+    })
+        .map((entry) => entry.name)
+        .sort();
 }
-// buildUpdatePayload 把本地全集转成 OpenAPIUpsertAIFunctions 的全量覆盖请求体。
-function buildUpdatePayload(items) {
-    return JSON.stringify({
-        ai_functions: items.map((item) => ({
-            config_json: item.configJson,
-            description: item.description,
-            function_key: item.functionKey,
-            name: item.name,
-        })),
-    });
+// Full synchronization also validates each declared AI configuration.
+export function collectLocalAIFunctions(workspace) {
+    return localAIFunctionKeys(workspace).map((key) => readAIFunctionMeta(join(aiFunctionsRoot(workspace), key, 'meta.json')));
 }
-// assertAIFunctionResultsOk 严格校验逐条结果：任一条 code != 0 立即抛错。
-// 后端整批拒绝时会同时返回顶层失败和 data.results；调用方必须保留逐条诊断，
-// 并阻止 deploy 继续上传产物或发布失败快照。
-function assertAIFunctionResultsOk(data) {
-    const results = data.results ?? data.Results;
-    if (results === undefined || results === null) {
-        return;
-    }
-    if (!Array.isArray(results)) {
-        throw new Error('AI Function sync returned an invalid results payload');
-    }
-    const failures = [];
-    for (const entry of results) {
-        if (!entry || typeof entry !== 'object')
-            continue;
-        const record = entry;
-        const code = record.code ?? record.Code;
-        if (typeof code === 'number' && code !== 0) {
-            const key = record.function_key ?? record.functionKey ?? record.FunctionKey;
-            const message = record.msg ?? record.Msg ?? record.message ?? '';
-            failures.push(`${String(key ?? '(unknown)')}: code=${code}${message ? ` ${String(message)}` : ''}`);
-        }
-    }
-    if (failures.length > 0) {
-        throw new Error(`AI Function sync failed for ${failures.length} function(s): ${failures.join('; ')}`);
-    }
+export function aiFunctionWrite(item) {
+    return {
+        functionId: item.functionKey,
+        name: item.name,
+        description: item.description,
+        functionType: 'ai',
+        spec: item.configJson,
+    };
 }
-// syncAIFunctionsFullCover 走 OpenAPI 全量覆盖同步（对齐 update_functions 心智）：传本地全集，服务端 diff 出
-// add/update/delete + 逐条校验码。deploy 与 `ai sync` 命令共用。空集合仍会清空远端 AI Function（全量覆盖语义）。
-// 任一条 results[].code != 0 立即抛错，避免 deploy 在 AI 同步失败后继续 artifact/publish。
 export function syncAIFunctionsFullCover(appToken, items, env, cwd) {
-    const token = encodeURIComponent(appToken);
-    let response;
     try {
-        response = runLarkCli([
-            'api',
-            'POST',
-            `/open-apis/base/v3/sites/${token}/ai_functions/update`,
-            '--data',
-            buildUpdatePayload(items),
-        ], env, cwd);
+        return putFunctions(appToken, ['ai'], items.map(aiFunctionWrite), env, cwd);
     }
     catch (error) {
-        // 顶层失败不能覆盖服务端保留的逐条诊断。
-        if (error instanceof LarkCliError && error.details.results) {
-            assertAIFunctionResultsOk({ results: error.details.results });
-        }
         throw aiFunctionAccessError(error);
     }
-    const data = responseData(response);
-    assertAIFunctionResultsOk(data);
-    return data;
 }
-function remoteAIFunctionKeys(appToken, env, cwd) {
-    const data = responseData(runAIFunctionApi([
-        'api',
-        'GET',
-        `/open-apis/base/v3/sites/${encodeURIComponent(appToken)}/ai_functions`,
-    ], env, cwd));
-    const list = Array.isArray(data.functions) ? data.functions : [];
-    return list.flatMap((entry) => {
-        if (!entry || typeof entry !== 'object')
-            return [];
-        const record = entry;
-        const key = record.function_key ?? record.functionKey;
-        return typeof key === 'string' && key !== '' ? [key] : [];
-    });
+// 专用管理接口返回完整草稿列表，不支持 Prod，也不要求 discovery 的 skillHash。
+// 当前服务端不分页；如响应声明 hasMore，则必须读完游标，不能把首屏当全集。
+function listDraftAIFunctions(appToken, env, cwd) {
+    const functions = [];
+    const keys = new Set();
+    const cursors = new Set();
+    let pageToken = '';
+    for (let page = 0; page < 1000; page++) {
+        const data = responseData(runAIFunctionApi([
+            'api',
+            'GET',
+            `/open-apis/base/v3/sites/${encodeURIComponent(appToken)}/ai_functions`,
+            ...(pageToken ? ['--params', JSON.stringify({ pageToken })] : []),
+        ], env, cwd));
+        const hasMore = data.hasMore ?? data.has_more;
+        if (!Array.isArray(data.functions) ||
+            (hasMore !== undefined && typeof hasMore !== 'boolean'))
+            throw new Error('AI_FUNCTION_RESPONSE_UNKNOWN: invalid AI Function list');
+        for (const item of data.functions) {
+            const key = item?.functionKey ?? item?.function_key;
+            if (typeof key !== 'string' ||
+                !/^[A-Za-z0-9_-]{1,64}$/.test(key) ||
+                keys.has(key))
+                throw new Error('AI_FUNCTION_RESPONSE_UNKNOWN: invalid or duplicate functionKey');
+            keys.add(key);
+            // 保持 1.4.1 的列表字段；专用接口缺失的发现元数据明确置空，不推断可调用性。
+            functions.push({
+                functionId: key,
+                name: item.name ?? null,
+                description: item.description ?? null,
+                functionType: 'ai',
+                capabilityType: item.capabilityType ?? item.capability_type ?? null,
+                mode: null,
+                result: null,
+                schemaStatus: null,
+                inputSchema: null,
+                agentTool: null,
+                statusReason: null,
+                statusHint: null,
+            });
+        }
+        if (!hasMore)
+            return functions;
+        const next = data.pageToken ?? data.page_token;
+        if (typeof next !== 'string' || !next || cursors.has(next))
+            throw new Error('AI Function list returned an empty or repeated pageToken');
+        cursors.add(next);
+        pageToken = next;
+    }
+    throw new Error('AI_FUNCTION_RESPONSE_UNKNOWN: unbounded AI Function list');
+}
+export function remoteAIFunctionKeys(appToken, env, cwd) {
+    return listDraftAIFunctions(appToken, env, cwd).map((item) => item.functionId);
+}
+function aiDetail(appToken, key, version, env, cwd) {
+    const view = getFunction(appToken, key, version, env, cwd);
+    if (view.functionType !== 'ai')
+        throw new Error(`Function ${key} is not an AI Function`);
+    return view;
+}
+function restoreAI(view, functionKey, workspace) {
+    if (!FUNCTION_ID_PATTERN.test(functionKey) || functionKey.length > 64)
+        throw new Error('Invalid remote AI Function key');
+    if (typeof view.name !== 'string' || typeof view.spec !== 'string')
+        throw new Error(`Remote AI Function ${functionKey} did not return name and spec`);
+    const parsed = parseAIJSON(view.spec);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error('AI spec must be an object');
+    const config = stripPlatformManagedFields(parsed);
+    const directory = join(aiFunctionsRoot(workspace), functionKey);
+    mkdirSync(directory, { recursive: true });
+    writeFileSync(join(directory, 'meta.json'), `${JSON.stringify({ name: view.name, description: view.description ?? '', config }, null, 2)}\n`);
 }
 // restoreRemoteAIFunctions 把远端 AI Function 草稿配置写回 <workspace>/ai/<key>/meta.json。
 // pull 调用它，让"修改已有应用前先恢复远端 AI Function"由 CLI 完成，而不是交给 Agent 判断。
-// 当前用户未开通 AI Function（800004011）时不算失败：本地不落 ai/，后续 deploy 自动跳过同步，远端保持原样。
+// 仅明确的 feature-not-enabled 消息可分类跳过，普通权限错误必须失败。
 export function restoreRemoteAIFunctions(appToken, workspace, env, cwd) {
     let keys;
     try {
@@ -199,38 +283,8 @@ export function restoreRemoteAIFunctions(appToken, workspace, env, cwd) {
             return { status: 'not_enabled' };
         throw error;
     }
-    const root = aiFunctionsRoot(workspace);
-    for (const functionKey of keys) {
-        if (functionKey.length > 64 || !FUNCTION_ID_PATTERN.test(functionKey)) {
-            throw new Error(`Remote AI Function key is not restorable: ${functionKey}`);
-        }
-        const detail = responseData(runAIFunctionApi([
-            'api',
-            'GET',
-            `/open-apis/base/v3/sites/${encodeURIComponent(appToken)}/ai_functions/${encodeURIComponent(functionKey)}`,
-        ], env, cwd));
-        const view = (detail.function ?? detail);
-        const configJson = view.config_json ?? view.configJson;
-        if (typeof view.name !== 'string' || typeof configJson !== 'string') {
-            throw new Error(`Remote AI Function ${functionKey} did not return name and config_json`);
-        }
-        let config;
-        try {
-            config = JSON.parse(configJson);
-        }
-        catch {
-            throw new Error(`Remote AI Function ${functionKey} config_json is not valid JSON`);
-        }
-        const directory = join(root, functionKey);
-        mkdirSync(directory, { recursive: true });
-        writeFileSync(join(directory, 'meta.json'), `${JSON.stringify({
-            name: view.name,
-            ...(typeof view.description === 'string' && view.description !== ''
-                ? { description: view.description }
-                : {}),
-            config,
-        }, null, 2)}\n`);
-    }
+    const details = keys.map((key) => aiDetail(appToken, key, 'preview', env, cwd));
+    keys.forEach((key, index) => restoreAI(details[index], key, workspace));
     return { status: 'restored', functionKeys: keys };
 }
 // assertNoRemoteAIFunctionLoss 在全量覆盖前核对：远端已有的 key 必须都在本地全集中，否则拒绝，
@@ -262,127 +316,124 @@ export function syncAIFunctionsForDeploy(appToken, items, env, cwd) {
     assertNoRemoteAIFunctionLoss(appToken, items, env, cwd);
     return syncAIFunctionsFullCover(appToken, items, env, cwd);
 }
-async function resolveEnv(workspace, runtimeProfile) {
+async function resolveEnv(workspace, runtimeProfile, explicitProfile) {
     const config = readConfig(workspace);
     assertProjectRuntimeProfile(config.runtimeProfile, runtimeProfile);
-    const env = await runtimeProfile.commandEnvironment();
+    const { env } = resolveLarkProfileEnvironment(await runtimeProfile.commandEnvironment(), explicitProfile, config.larkProfile, runtimeProfile);
     return { config, env };
 }
 // listAIFunctions 列出 Site 下 AI Function。
 export async function listAIFunctions(options) {
     const workspace = resolve(options.directory);
     const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
-    const { config, env } = await resolveEnv(workspace, runtimeProfile);
-    const response = runAIFunctionApi([
-        'api',
-        'GET',
-        `/open-apis/base/v3/sites/${encodeURIComponent(config.appToken)}/ai_functions`,
-    ], env, workspace);
-    return responseData(response);
+    const { config, env } = await resolveEnv(workspace, runtimeProfile, options.larkProfile);
+    const version = functionEnv(options.env);
+    return {
+        env: version,
+        functions: version === 'preview'
+            ? listDraftAIFunctions(config.appToken, env, workspace)
+            : listFunctions(config.appToken, version, env, workspace).filter((item) => item.functionType === 'ai'),
+    };
 }
-// getAIFunction 读取单个 AI Function 配置（用于本地编辑 / diff）。
 export async function getAIFunction(functionKey, options) {
     const workspace = resolve(options.directory);
-    const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
-    const { config, env } = await resolveEnv(workspace, runtimeProfile);
-    const response = runAIFunctionApi([
-        'api',
-        'GET',
-        `/open-apis/base/v3/sites/${encodeURIComponent(config.appToken)}/ai_functions/${encodeURIComponent(functionKey)}`,
-    ], env, workspace);
-    return responseData(response);
+    const { config, env } = await resolveEnv(workspace, options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE, options.larkProfile);
+    const version = functionEnv(options.env);
+    const view = aiDetail(config.appToken, functionKey, version, env, workspace);
+    if (version === 'prod')
+        return { env: version, function: view };
+    if (typeof view.spec !== 'string')
+        throw new Error('AI Function detail is missing spec');
+    return {
+        env: version,
+        function: view,
+        config: stripPlatformManagedFields(parseAIJSON(view.spec)),
+    };
+}
+export async function pullAIFunction(functionKey, options) {
+    if (functionEnv(options.env) !== 'preview')
+        throw new Error('AI pull requires env=preview');
+    const workspace = resolve(options.directory);
+    const { config, env } = await resolveEnv(workspace, options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE, options.larkProfile);
+    restoreAI(aiDetail(config.appToken, functionKey, 'preview', env, workspace), functionKey, workspace);
+    return { ok: true, functionKey, env: 'preview' };
 }
 // syncAIFunctions 把本地 ai/ 全集全量覆盖同步到 Site。
 export async function syncAIFunctions(options) {
     const workspace = resolve(options.directory);
     const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
-    const { config, env } = await resolveEnv(workspace, runtimeProfile);
+    const { config, env } = await resolveEnv(workspace, runtimeProfile, options.larkProfile);
     const items = collectLocalAIFunctions(workspace);
-    const data = syncAIFunctionsFullCover(config.appToken, items, env, workspace);
+    const { deletedFunctionIds, ...data } = syncAIFunctionsFullCover(config.appToken, items, env, workspace);
     return {
         ok: true,
         appToken: config.appToken,
         count: items.length,
         results: data,
+        deletedFunctionIds,
     };
 }
 // validateAIFunction 静态校验单个本地 AI Function（保存/发布前，按能力分支），不落库。
 export async function validateAIFunction(functionKey, options) {
     const workspace = resolve(options.directory);
     const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
-    const { config, env } = await resolveEnv(workspace, runtimeProfile);
-    const items = collectLocalAIFunctions(workspace);
-    const target = items.find((item) => item.functionKey === functionKey);
-    if (!target) {
+    const { config, env } = await resolveEnv(workspace, runtimeProfile, options.larkProfile);
+    if (!localAIFunctionKeys(workspace).includes(functionKey))
         throw new Error(`AI Function not found in ${AI_FUNCTIONS_DIR}/: ${functionKey}`);
-    }
+    const target = readAIFunctionMeta(join(aiFunctionsRoot(workspace), functionKey, 'meta.json'));
     const response = runAIFunctionApi([
         'api',
         'POST',
-        `/open-apis/base/v3/sites/${encodeURIComponent(config.appToken)}/ai_functions/validate`,
+        `/open-apis/base/v3/sites/${encodeURIComponent(config.appToken)}/functions/validate`,
         '--data',
-        JSON.stringify({
-            function: {
-                config_json: target.configJson,
-                description: target.description,
-                function_key: target.functionKey,
-                name: target.name,
-            },
-        }),
+        JSON.stringify({ kinds: ['ai'], functions: [aiFunctionWrite(target)] }),
     ], env, workspace);
     const data = responseData(response);
-    if (data.is_success !== true) {
-        const message = String(data.err_msg ?? 'unknown validation error');
-        throw new Error(`AI Function validation failed: ${message}`);
-    }
-    return data;
-}
-function readCapabilityType(data) {
-    const value = data.function;
-    if (!value || typeof value !== 'object') {
-        throw new Error('AI Function detail does not contain function');
-    }
-    const view = value;
-    const raw = view.config_json;
-    if (typeof raw !== 'string' || raw === '') {
-        throw new Error('AI Function detail is missing config_json');
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new Error('AI Function detail config_json is not valid JSON');
-    }
-    if (!parsed || typeof parsed !== 'object') {
-        throw new Error('AI Function detail config_json is not an object');
-    }
-    const capability = parsed.capability_type;
-    if (typeof capability !== 'string' || !CAPABILITY_TYPES.has(capability)) {
-        throw new Error('AI Function detail contains invalid capability_type');
-    }
-    return capability;
+    assertFunctionResults(data, [functionKey]);
+    if (data.valid !== true)
+        throw new Error('AI Function validation failed');
+    const hints = responseFunctionHints(data, [functionKey]);
+    return {
+        ...data,
+        ...(hints.length
+            ? {
+                functionHints: hints,
+                functionHintsGuide: `Review hints against ${AGENT_TOOL_DESIGN_REFERENCE}.`,
+            }
+            : {}),
+    };
 }
-// debugAIFunction 调试 text/vision 时走 unary 聚合；image/video 走统一 tasks 提交接口。
 export async function debugAIFunction(functionKey, options) {
     const workspace = resolve(options.directory);
     const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
-    const { config, env } = await resolveEnv(workspace, runtimeProfile);
+    const { config, env } = await resolveEnv(workspace, runtimeProfile, options.larkProfile);
     const token = encodeURIComponent(config.appToken);
     const key = encodeURIComponent(functionKey);
-    const detail = runAIFunctionApi(['api', 'GET', `/open-apis/base/v3/sites/${token}/ai_functions/${key}`], env, workspace);
-    const capabilityType = readCapabilityType(responseData(detail));
-    const body = JSON.stringify({
-        input: options.input ?? {},
-        messages: options.messages ?? [],
-        variables: options.variables ?? {},
-    });
+    const version = functionEnv(options.env);
+    if (options.params !== undefined && options.variables !== undefined)
+        throw new Error('--params and --variables are mutually exclusive');
+    if (options.variables !== undefined)
+        process.stderr.write('Warning: --variables 已弃用，请使用 --params。\n');
+    const params = options.params ?? options.variables ?? {};
+    if (!params || typeof params !== 'object' || Array.isArray(params))
+        throw new Error('--params must be a JSON object');
+    const detail = aiDetail(config.appToken, functionKey, version, env, workspace);
+    const capabilityType = detail.capabilityType;
+    if (typeof capabilityType !== 'string' ||
+        !CAPABILITY_TYPES.has(capabilityType))
+        throw new Error('AI Function detail contains invalid capabilityType');
+    const media = capabilityType === 'image' || capabilityType === 'video';
+    if (media ? options.messages !== undefined : options.input !== undefined)
+        throw new Error('AI capability does not accept the supplied messages/input');
+    const body = JSON.stringify(media
+        ? { params, input: options.input ?? {} }
+        : { params, messages: options.messages ?? [] });
     const response = runAIFunctionApi([
         'api',
         'POST',
-        `/open-apis/base/v3/sites/${token}/ai_functions/${key}/${capabilityType === 'image' || capabilityType === 'video' ? 'tasks' : 'invoke'}`,
+        `/open-apis/base/v3/sites/${token}/functions/${key}/invoke`,
         '--params',
-        JSON.stringify({ env: options.env }),
+        JSON.stringify({ env: functionEnv(options.env), includeInternal: true }),
         '--data',
         body,
     ], env, workspace);
@@ -392,16 +443,17 @@ export async function debugAIFunction(functionKey, options) {
 export async function getAIFunctionTask(functionKey, taskId, options) {
     const workspace = resolve(options.directory);
     const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
-    const { config, env } = await resolveEnv(workspace, runtimeProfile);
+    const { config, env } = await resolveEnv(workspace, runtimeProfile, options.larkProfile);
     const token = encodeURIComponent(config.appToken);
     const key = encodeURIComponent(functionKey);
     const task = encodeURIComponent(taskId);
+    process.stderr.write(`AI task env=${functionEnv(options.env)}；查询成功不等于生成成功，请按 status 判断。\n`);
     const response = runAIFunctionApi([
         'api',
         'GET',
-        `/open-apis/base/v3/sites/${token}/ai_functions/${key}/tasks/${task}`,
+        `/open-apis/base/v3/sites/${token}/functions/${key}/tasks/${task}`,
         '--params',
-        JSON.stringify({ env: options.env }),
+        JSON.stringify({ env: functionEnv(options.env), includeInternal: true }),
     ], env, workspace);
     return responseData(response);
 }
@@ -409,7 +461,7 @@ export async function getAIFunctionTask(functionKey, taskId, options) {
 export async function getAIFunctionUsage(options) {
     const workspace = resolve(options.directory);
     const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
-    const { config, env } = await resolveEnv(workspace, runtimeProfile);
+    const { config, env } = await resolveEnv(workspace, runtimeProfile, options.larkProfile);
     const token = encodeURIComponent(config.appToken);
     const params = {};
     if (options.from !== undefined)