@lark-base-open/base-database-cli 1.6.0 → 1.8.0

package/dist/sdk-codegen.js

@@ -1,29 +1,51 @@
-import { sdkInstallGuidance } from './sdk-install.js';
 import { projectCapabilities } from './project-capabilities.js';
 import { createRequire } from 'node:module';
 import { execFileSync } from 'node:child_process';
 import { existsSync, lstatSync, cpSync, mkdirSync, realpathSync, symlinkSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, dirname, relative } from 'node:path';
-import { serverDirectory } from './project-layout.js';
+import { join, dirname, relative, isAbsolute, sep } from 'node:path';
+import { projectLayout, serverDirectory } from './project-layout.js';
 const SDK = '@lark-base-open/base-database-app-sdk';
 export class SDKCodegenError extends Error {
     code;
-    constructor(code, message) {
+    nextActions;
+    constructor(code, message, nextActions = []) {
         super(`${code}: ${message}`);
         this.code = code;
+        this.nextActions = nextActions;
         this.name = 'SDKCodegenError';
     }
     toJSON() {
-        return { code: this.code, message: this.message };
+        return {
+            code: this.code,
+            message: this.message,
+            ...(this.nextActions.length ? { nextActions: this.nextActions } : {}),
+        };
     }
 }
 const locations = (root) => ['page', serverDirectory(root), ''].map((p) => join(root, p, 'package.json'));
 export function requiresSDKCodegen(root) {
     return projectCapabilities(root).sdkCodegen;
 }
-function unavailable() {
-    throw new SDKCodegenError('SDK_CODEGEN_UNAVAILABLE', `Install SDK with codegen: ${sdkInstallGuidance(true)}. Then run contracts generate.`);
+function dependencyRecovery(root) {
+    const layout = projectLayout(root);
+    const install = layout.version === 2
+        ? 'npm ci'
+        : layout.dependencies
+            .map((directory) => `npm ci --prefix ${directory}`)
+            .join('; ');
+    return [
+        `From the project root, restore dependencies from the existing manifests and lockfiles: ${install}. Keep the declared SDK version unchanged.`,
+        'If dependencies are already installed but the SDK lacks codegen, keep the current SDK and upgrade only with user authorization; follow its Migration instructions.',
+        'Once codegen is available, use the same CLI and environment to run contracts generate, then check --json.',
+    ];
+}
+function unavailable(root, missingExport = false) {
+    throw new SDKCodegenError('SDK_CODEGEN_UNAVAILABLE', missingExport
+        ? 'The installed SDK codegen does not export generateFunctionClients.'
+        : 'Cannot resolve the installed SDK codegen entry. Project dependencies may not be installed, or the installed SDK may not provide codegen.', missingExport
+        ? dependencyRecovery(root).slice(1)
+        : dependencyRecovery(root));
 }
 /** Resolve/snapshot reads package bytes only; project modules execute only in the restricted child. */
 export function runSDKCodegen(root, data) {
@@ -38,7 +60,7 @@ export function runSDKCodegen(root, data) {
         catch { }
     }
     if (!entry)
-        unavailable();
+        unavailable(root);
     const temp = mkdtempSync(join(tmpdir(), 'base-codegen-'));
     try {
         let packageRoot = dirname(entry);
@@ -47,7 +69,7 @@ export function runSDKCodegen(root, data) {
                 .name !== SDK) {
             const parent = dirname(packageRoot);
             if (parent === packageRoot)
-                unavailable();
+                unavailable(root);
             packageRoot = parent;
         }
         snapshotPackage(packageRoot, join(temp, 'node_modules', SDK), new Map());
@@ -87,8 +109,10 @@ globalThis.WebSocket = undefined;
         catch {
             throw new SDKCodegenError('SDK_CODEGEN_FAILED', 'Isolated SDK codegen failed, timed out, or returned invalid JSON');
         }
-        if (!result.ok && result.code === 'SDK_CODEGEN_UNAVAILABLE')
-            unavailable();
+        if (!result.ok &&
+            result.code === 'SDK_CODEGEN_UNAVAILABLE' &&
+            result.message === 'SDK codegen export missing')
+            unavailable(root, true);
         if (!result.ok)
             throw new SDKCodegenError(result.code ?? 'SDK_CODEGEN_FAILED', (result.message ?? 'SDK codegen failed') +
                 (result.code === 'CONTRACT_DATA_INVALID'
@@ -139,7 +163,7 @@ function resolvePackage(name, from) {
             return realpathSync(candidate);
         const parent = dirname(directory);
         if (parent === directory)
-            throw new SDKCodegenError('SDK_CODEGEN_UNAVAILABLE', `Missing installed SDK dependency; reinstall SDK: ${sdkInstallGuidance(true)}`);
+            throw new SDKCodegenError('SDK_CODEGEN_UNAVAILABLE', `Missing installed SDK dependency: ${name}. Restore this project's existing locked dependencies and keep the SDK version unchanged.`);
         directory = parent;
     }
 }
@@ -170,7 +194,7 @@ function snapshotPackage(source, destination, copied) {
                 p.startsWith('.env.')))
                 return false;
             const real = realpathSync(path), rel = relative(source, real);
-            if (rel.startsWith('..') || rel.startsWith('/'))
+            if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
                 throw new SDKCodegenError('SDK_CODEGEN_UNAVAILABLE', 'SDK package contains external symbolic links');
             return true;
         },

package/dist/sdk-codegen.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-codegen.js","sourceRoot":"","sources":["../src/sdk-codegen.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sdk-codegen.js","sourceRoot":"","sources":["../src/sdk-codegen.ts"],"names":[],"mappings":"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"}

package/dist/sdk-compatibility.js

@@ -57,7 +57,7 @@ export function checkSDKCompatibility(workspace, command = 'base-database-cli')
         const nextActions = [
             `Keep the installed SDK by default: use its package-local docs and examples; do not apply newer Skill API examples.`,
             `Only with user authorization, upgrade: ${upgradeCommand}`,
-            `For an authorized upgrade, read the target SDK CHANGELOG.md Migration sections for every crossed incompatible version, migrate affected calls, then run ${command} contracts generate, ${command} check --json and the project build. Do not use type assertions or caller-supplied generics to bypass migration errors.`,
+            `For an authorized upgrade, read the target SDK CHANGELOG.md and package-local docs for upgrade and compatibility guidance on every crossed incompatible version, migrate affected calls, then run ${command} contracts generate, ${command} check --json and the project build. Do not use type assertions or caller-supplied generics to bypass migration errors.`,
         ];
         warnings.push({
             code: 'SDK_BEHIND_CLI',

package/dist/sdk-compatibility.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdk-compatibility.js","sourceRoot":"","sources":["../src/sdk-compatibility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEzE,MAAM,GAAG,GAAG,uCAAuC,CAAC;AAapD,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAEnC,IAAI;IAEJ,WAAW;IAHtB,YACW,IAA2B,EACpC,OAAe,EACN,WAAqB;QAE9B,KAAK,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;oBAJpB,IAAI;2BAEJ,WAAW;QAGpB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;IACD,MAAM;QACJ,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC;IACJ,CAAC;CACF;AAED,2GAA2G;AAC3G,MAAM,UAAU,qBAAqB,CACnC,SAAiB,EACjB,OAAO,GAAG,mBAAmB;IAE7B,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IACxC,MAAM,eAAe,GAAG,iBAAiB,EAAE,CAAC;IAC5C,MAAM,QAAQ,GAA8B,EAAE,CAAC;IAC/C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,SAAS,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;QACpD,MAAM,OAAO,GAAG,aAAa,CAC3B,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,CAAC,CAC9C,CAAC;QACF,MAAM,UAAU,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACpE,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,cAAc,CAAC,CACnC,CAAC;QACF,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI;YAAE,SAAS,CAAC,oDAAoD;QACzE,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC;YAAE,SAAS;QACnC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACrB,MAAM,WAAW,GAAG,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC9C,IAAI,gBAAwB,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;YACxD,IACE,QAAQ,CAAC,IAAI,KAAK,GAAG;gBACrB,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ;gBACpC,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAE/B,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;YACpD,gBAAgB,GAAG,QAAQ,CAAC,OAAO,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,qBAAqB,CAC7B,qBAAqB,EACrB,wCAAwC,WAAW,GAAG,EACtD,CAAC,wDAAwD,CAAC,CAC3D,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,gBAAgB,EAAE,eAAe,CAAC;YAAE,SAAS;QAC5D,MAAM,cAAc,GAAG,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACxD,MAAM,WAAW,GAAG;YAClB,oHAAoH;YACpH,0CAA0C,cAAc,EAAE;YAC1D,2JAA2J,OAAO,wBAAwB,OAAO,yHAAyH;SAC3T,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,6BAA6B,GAAG,IAAI,gBAAgB,KAAK,WAAW,+CAA+C,eAAe,0CAA0C,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;YAC5M,SAAS,EAAE,EAAE;YACb,gBAAgB;YAChB,eAAe;YACf,WAAW;YACX,cAAc;YACd,WAAW;SACZ,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"sdk-compatibility.js","sourceRoot":"","sources":["../src/sdk-compatibility.ts"],"names":[],"mappings":"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"}

package/dist/source-format.d.ts

@@ -7,6 +7,7 @@ interface SourceFormat {
     minCli: string;
     cli: string;
 }
+export declare function sourceCliVersion(): string;
 export declare function sourceArchiveComment(): string;
 export declare function readSourceFormat(comment: string): SourceFormat | undefined;
 export {};

package/dist/source-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-format.d.ts","sourceRoot":"","sources":["../src/source-format.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,wBAAwB,QAAuC,CAAC;AAG7E,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,UAAU,YAAY;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAe7C;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAgC1E"}
+{"version":3,"file":"source-format.d.ts","sourceRoot":"","sources":["../src/source-format.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,wBAAwB,QAAuC,CAAC;AAG7E,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,UAAU,YAAY;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CASzC;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAQ7C;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAgC1E"}

package/dist/source-format.js

@@ -9,17 +9,20 @@ const MIN_SOURCE_CLI = '1.4.1';
 export function compressedSourceArchiveSizeError(size) {
     return `Compressed source archive is ${size} bytes, exceeds ${MAX_SOURCE_ARCHIVE_MIB} MiB (${MAX_SOURCE_ARCHIVE_BYTES} bytes)`;
 }
-export function sourceArchiveComment() {
+export function sourceCliVersion() {
     // 内部分发的共享源码位于 dist/src，包版本在 dist 的上一级。
     const root = existsSync(join(packageRoot, 'package.json'))
         ? packageRoot
         : dirname(packageRoot);
     const { version } = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    return version;
+}
+export function sourceArchiveComment() {
     return JSON.stringify({
         baseDatabaseSource: {
             format: SOURCE_FORMAT,
             minCli: MIN_SOURCE_CLI,
-            cli: version,
+            cli: sourceCliVersion(),
         },
     });
 }

package/dist/source-format.js.map

@@ -1 +1 @@
-{"version":3,"file":"source-format.js","sourceRoot":"","sources":["../src/source-format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAC/B,2EAA2E;AAC3E,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AACzC,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,GAAG,IAAI,GAAG,IAAI,CAAC;AAC7E,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,MAAM,UAAU,gCAAgC,CAAC,IAAY;IAC3D,OAAO,gCAAgC,IAAI,mBAAmB,sBAAsB,SAAS,wBAAwB,SAAS,CAAC;AACjI,CAAC;AAQD,MAAM,UAAU,oBAAoB;IAClC,uCAAuC;IACvC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;QACxD,CAAC,CAAC,WAAW;QACb,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACzB,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CACjD,CAAC;IACF,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,kBAAkB,EAAE;YAClB,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,cAAc;YACtB,GAAG,EAAE,OAAO;SACb;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,KAAK,EAAE,kBAAkB,CAAC;QACzC,IACE,KAAK;YACL,OAAO,KAAK,KAAK,QAAQ;YACzB,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACrB,MAAM,KAAK,SAAS;YAEpB,OAAO,SAAS,CAAC;QACnB,IACE,CAAC,MAAM;YACP,OAAO,MAAM,KAAK,QAAQ;YAC1B,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YACrB,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC;YACpC,MAAM,CAAC,MAAM,GAAG,CAAC;YACjB,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;YACjC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE;YACrB,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;YAC9B,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE;YAElB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,4BAA4B;QAC5B,OAAO,CAAC,IAAI,CACV,iGAAiG,CAClG,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}
+{"version":3,"file":"source-format.js","sourceRoot":"","sources":["../src/source-format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC;AAC/B,2EAA2E;AAC3E,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AACzC,MAAM,CAAC,MAAM,wBAAwB,GAAG,sBAAsB,GAAG,IAAI,GAAG,IAAI,CAAC;AAC7E,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,MAAM,UAAU,gCAAgC,CAAC,IAAY;IAC3D,OAAO,gCAAgC,IAAI,mBAAmB,sBAAsB,SAAS,wBAAwB,SAAS,CAAC;AACjI,CAAC;AAQD,MAAM,UAAU,gBAAgB;IAC9B,uCAAuC;IACvC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;QACxD,CAAC,CAAC,WAAW;QACb,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACzB,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CACjD,CAAC;IACF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,kBAAkB,EAAE;YAClB,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,cAAc;YACtB,GAAG,EAAE,gBAAgB,EAAE;SACxB;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,KAAK,EAAE,kBAAkB,CAAC;QACzC,IACE,KAAK;YACL,OAAO,KAAK,KAAK,QAAQ;YACzB,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACrB,MAAM,KAAK,SAAS;YAEpB,OAAO,SAAS,CAAC;QACnB,IACE,CAAC,MAAM;YACP,OAAO,MAAM,KAAK,QAAQ;YAC1B,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YACrB,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC;YACpC,MAAM,CAAC,MAAM,GAAG,CAAC;YACjB,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;YACjC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE;YACrB,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;YAC9B,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE;YAElB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,4BAA4B;QAC5B,OAAO,CAAC,IAAI,CACV,iGAAiG,CAClG,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-base-open/base-database-cli",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "CLI and Agent Skill for building database applications on Lark Base.",
   "type": "module",
   "bin": {

package/skills/lark-base-database/SKILL.md

@@ -22,7 +22,7 @@ metadata:
 
 | 用户任务                 | 执行路径                                                           | 主要命令                                                  | 进入阶段前读取                                                                            |
 | ------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| 新建系统                 | 明确需求与访问模型 → 确定 Base 来源 → 初始化 → 开发 → Preview 交付 | `init` → `deploy`                                         | [工程与环境](references/workspace.md)、[权限设计](references/permission-design.md)        |
+| 新建系统                 | 明确需求与访问模型 → 确定 Base 来源 → 设计底表 → 初始化 → 开发 → Preview 交付 | `init` → `deploy`                                         | [工程与环境](references/workspace.md)、[底表设计](references/base-table-design.md)、[权限设计](references/permission-design.md)        |
 | 修改已有系统             | 确认现有工程 → 判断影响范围 → 增量修改 → 验证与交付                | 按影响范围修改，必要时 `deploy`                           | [增量修改与追加绑定](references/workspace.md#增量修改与追加绑定)，再读取受影响的协议                                 |
 | 恢复远端工程             | 确认本地状态和应用 → 恢复源码与 Catalog → 继续原任务              | 按来源选择 `pull` 或 `init`                               | [工程与环境](references/workspace.md)                                                     |
 | 设计或评审               | 按评审范围分析并输出，不创建资源或发布                             | 只读分析                                                  | [工程质量](references/style-guide.md)，涉及权限、查询或视觉时读取对应专项                 |
@@ -57,9 +57,11 @@ metadata:
 | 为 Page 或 FaaS 添加、升级第三方 npm 依赖             | [Page 开发中的依赖策略](references/development.md#第三方依赖策略)                       |
 | 附件上传、展示、下载、追加或移除                      | [文件传输](references/file-transfer.md)，实现前核对目标环境能力                         |
 | binding、身份过滤、角色或数据可见性                   | [权限设计](references/permission-design.md)                                             |
+| 以机器人（bot）身份搭建，并把新建的 Base 与应用管理员交给发起人 | [bot 建站与交接](references/collaborator-handoff.md)：显式声明 bot 身份，向用户报告 init 返回的 `handoff` 授权结果 |
 | 自动化、表单、仪表盘等原生能力，或能力归属不明        | [原生 Base 能力路由](references/base-capability-routing.md)                             |
 | 原生 workflow 通知与站内入口                          | [通知集成](references/notifications.md)                                                 |
 | 固定单表的基础创建、更新、删除、附件增量或批量写入 | [Mutation Function](references/mutations.md) |
+| 新建表、新增字段，或调整底表的视图、选项颜色、公式字段 | [底表设计](references/base-table-design.md) |
 
 新建或整体改版先在内部规划中确定视觉方案，再实现设计变量和组件。业务建模与通用工程取舍按[工程质量](references/style-guide.md)执行；默认不创建额外设计文件。新建站点或修改业务能力时，按[站点 README](references/release.md#站点-readme)维护随源码制品上传的项目说明；用户要求其他文档时按要求交付。
 

package/skills/lark-base-database/references/agent-tools.md

@@ -51,6 +51,8 @@
 | 说明 | `lark-cli api GET /open-apis/base/v3/sites/<app-token>/functions/<function-id> --params '{"env":"prod"}' --as user` | `data.function` 的 `inputSchema`、`parameters[]`、`requestExample`、`replacePaths`、`callCommand`；Mutation 还读取 `outputSchema` 了解返回字段名称和类型 |
 | 调用 | 按 `callCommand`：`lark-cli api POST /open-apis/base/v3/sites/<app-token>/functions/<function-id>/invoke --params '{"env":"prod"}' --data @body.json --as user` | 顶层业务码与 `data` |
 
+上表示例使用 `--as user`。以 bot 调用时，将每条命令的身份显式设为 `--as bot`，安装、分页、详情、invoke 与 task 续查始终沿用同一 profile 和身份，不切换身份绕过权限。异步任务使用 `lark-cli api GET /open-apis/base/v3/sites/<app-token>/functions/<function-id>/tasks/<task-id> --params '{"env":"prod"}' --as bot` 续查。
+
 列表请求始终携带 `apiVersion=2`，包括翻页、`env=preview` 或 `includeInternal=true`；检查响应 `data.apiVersion` 为数字 `2` 后再使用列表，未回写 `2` 时，通过同站点的 `skillCommand`（`GET /open-apis/base/v3/sites/<app-token>/skill`）读取 SKILL.md 清单，逐个读取函数的实时说明后再调用，不把该列表响应视为空清单。
 
 原则：参数以服务端实时返回的说明为准，Skill、函数索引和历史会话不保存参数 Schema。仅站点管理者做开发期验证时可在列表、说明和调用的 `--params` 中显式加 `"includeInternal":true` 访问页面专用内部函数；外部 Agent 默认不带。
@@ -87,12 +89,18 @@ Prod 交付回复中的业务能力说明与完整 handoff 按[交付结果](rel
 默认路径：开发者使用 `nextAction.externalAgent.installation.command`；未取得该字段时，在包含 `base-database.jsonc` 的工程目录执行：
 
 ```bash
-base-database-cli agent-tools skill install
+base-database-cli agent-tools skill install --as user
 ```
 
 Prod 成员安装命令由 CLI 交付块生成。完整交付条件与回复写法见[交付结果](release.md#交付结果)；不要自行拼装或改写成员消息。
 
-成员无需打开工程目录，可在任意目录执行 `base-database-cli agent-tools skill install --site <站点链接或 token>`。命令使用当前 lark-cli 用户登录态，返回的站点能力仍按该成员自己的访问权限决定。成员安装摘要存放在用户级 CLI 状态目录，不写入站点工程；摘要用于识别同名 Skill 的站点来源，不参与工程 Preview 过期判断。仅有 Preview 的站点不能用此命令安装。
+成员无需打开工程目录，可在任意目录执行 `base-database-cli agent-tools skill install --site <站点链接或 token>`。工程安装与 `--site` 安装的身份按 显式 `--as user|bot` > lark-cli strict mode / default-as > `user` 解析，不采用自动检测推断 bot。`--as user` 使用当前 profile 的用户登录态；`--as bot` 使用该 profile 的应用身份，应用 bot 须与站点同租户且已是站点协作者。安装、发现、详情、调用与 task 查询需要 `base:appmode:read` scope，站点能力仍按所选身份的访问权限决定。成员安装摘要存放在用户级 CLI 状态目录，不写入站点工程；摘要用于识别同名 Skill 的站点来源，不参与工程 Preview 过期判断。仅有 Preview 的站点不能用此命令安装。
+
+例如应用 bot 在工程外安装：
+
+```bash
+base-database-cli --profile <profile> agent-tools skill install --site <app-token> --as bot
+```
 
 成员使用 `--site` 安装时，若目标目录中已有另一个站点的同名 Skill，安装器会按站点 token 哈希加短后缀并提示新名称；同一站点重装会覆盖其已记录的安装。未被 CLI 摘要识别的同名目录仍按普通已存在目录处理，用户可先核对目标再显式使用 `--force`。
 

package/skills/lark-base-database/references/base-sql-errors.generated.md

@@ -667,6 +667,7 @@ Placeholders denote the names and types reported in the error. Use the concrete
 | `SQL_UNSUPPORTED_OPERATOR` / `unsupported_operator` | Operator {Operator} is not supported for {ArgTypes}. | [outside_sql] |
 | `SQL_UNSUPPORTED_SYNTAX` / `aggregate_modifier` | Aggregate {Function} does not support {Modifier}. | [outside_sql] |
 | `SQL_UNSUPPORTED_SYNTAX` / `aggregate_separator` | The separator of {Function} must be {Requirement}. | [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `array_alias_shape` | ARRAY_CONTAINS and ARRAY_OVERLAP require two arguments without DISTINCT, FILTER, or OVER. | [outside_sql] |
 | `SQL_UNSUPPORTED_SYNTAX` / `array_dimension` | ARRAY_LENGTH dimension must be {Form}. | Changing the dimension can change the result. [outside_sql] |
 | `SQL_UNSUPPORTED_SYNTAX` / `array_subquery_shape` | This ARRAY subquery shape is not supported. | Only a direct single-column UNNEST projection is supported here. [outside_sql] |
 | `SQL_UNSUPPORTED_SYNTAX` / `binary_operator` | Unsupported binary operator: {Operator}. | [outside_sql] |
@@ -692,6 +693,7 @@ Placeholders denote the names and types reported in the error. Use the concrete
 | `SQL_UNSUPPORTED_SYNTAX` / `ordered_set_function` | Function {Function} does not support WITHIN GROUP. | [outside_sql] |
 | `SQL_UNSUPPORTED_SYNTAX` / `protocol_shape` | Invalid compiled structure: {Shape} is not supported. | Recompile the query using the current supported contract. |
 | `SQL_UNSUPPORTED_SYNTAX` / `route_table_required` | The query must reference a table for execution routing. | Adding an arbitrary table can change row count. [outside_sql] |
+| `SQL_UNSUPPORTED_SYNTAX` / `series_projection_shape` | SELECT supports one top-level GENERATE_SERIES without stars, grouping, aggregates, or windows. | [outside_sql] |
 | `SQL_UNSUPPORTED_SYNTAX` / `series_shape` | GENERATE_SERIES supports constant integer bounds and a nonzero step, with at most 10000 values in the exact numeric range. | [outside_sql] |
 | `SQL_UNSUPPORTED_SYNTAX` / `subquery_constraint` | {Construct} requires {Constraint}. | The subquery must satisfy the stated constraint for a supported SQL rewrite. [outside_sql] |
 | `SQL_UNSUPPORTED_SYNTAX` / `syntax_feature` | SQL feature {Feature} is not supported. | [outside_sql] |

package/skills/lark-base-database/references/base-table-design.md

@@ -0,0 +1,37 @@
+# 底表设计
+
+从零建 Base、在已有 Base 中新增表或字段时读取。
+
+## 前提：人也会直接看底表
+
+应用页面不是数据的唯一入口。底表的 Base 协作者会长期直接打开 Base 浏览、筛选、修改和统计数据，底表是这个应用的第二个界面。设计表结构时同时考虑两类读者：Database Function、Mutation、FaaS 和外部 Agent 读写字段，人在表格里看视图。
+
+## 两层设计
+
+- **存储层**：有类型的业务事实。金额、数量用数字，时间用日期，人用人员，引用其他实体用关联，有限取值用单选或多选。这一层给程序读写，保持规范化：一个事实只存一处，不存 JSON、拼接串或带单位、币种符号的格式化文本。
+- **呈现层**：主字段的选择、字段顺序、选项颜色、数字和日期格式、视图，以及只读的公式字段。它们决定人打开表格时能否看懂，不改变存储字段的读写方式；写入仍按 [Mutation](mutations.md) 或 [FaaS](faas.md) 协议处理。
+
+人习惯在一行里看全一件事。规范化拆表后，人需要在主表上长期看到的子表汇总或跨表信息，用公式字段带回主表，不要为了好看把它存成文本。
+
+## 判定
+
+对每张业务表问：Base 协作者会不会长期直接打开它浏览或处理？会的话，他打开时能否不借助应用页面，就回答这张表最常被问到的问题？
+
+- 能回答，不需要额外呈现。
+- 缺的是事实，补存储字段；缺的是汇总或跨表信息，补公式字段；缺的是"只看一部分记录"的入口，补视图。
+
+不会被人长期浏览的表保持默认即可。
+
+## 默认做法
+
+- 主字段用人能认出这一行的业务名称或标题，不用流水号、外部 ID 或机器键。
+- 字段按阅读顺序排列：判断状态最需要的字段（状态、负责人、关键日期、金额）靠前，技术辅助字段（排序值、外部 ID、同步标记）靠后或在视图里隐藏。
+- 选项颜色与含义一致：完成或通过用绿，阻塞、风险或驳回用红或橙，进行中用蓝，未开始、暂停或归档用灰；含义不同、需要区分的选项不共用同一颜色。
+- 视图围绕人的高频任务建，视图类型按 lark-base 的视图选型执行。
+- 跨表引用、汇总和计算按 lark-base 的默认策略使用公式字段。
+
+## 例外：应用内部数据
+
+应用运行需要的技术数据，例如页面与 Agent 之间的状态同步、调用队列、游标、缓存、键值配置，本身不是业务事实，人也不需要浏览。优先不放进 Base：能由页面状态、Function 参数或环境变量承载的就不建表。确实需要持久化时，用单独的表与业务表分开，字段仍按存储层要求选用正确类型。
+
+复用已有 Base 时，呈现层的新增和调整只在用户授权修改的范围内进行；未经授权不改动用户已有的视图、颜色和字段顺序。

package/skills/lark-base-database/references/collaborator-handoff.md

@@ -0,0 +1,62 @@
+# 以机器人身份建站与交接
+
+以机器人（bot）身份搭建时，新建 Base 与应用的属主是机器人，不是发起搭建的人。CLI 在资源创建后把管理员授权交给一个明确的人，让对方能直接打开 Base、管理应用。
+
+## 声明身份
+
+CLI 只采用明确声明的身份，不根据登录状态猜测：
+
+| 场景 | 声明方式 |
+|------|----------|
+| 单次命令 | 任意命令加 `--as bot`（或 `--as user`） |
+| 本机 profile 默认用 bot | `lark-cli config default-as bot` |
+| 团队共享 bot | `lark-cli config bind --identity bot-only`，自带 strict-mode，无需再传参数 |
+| 宿主通过环境变量注入凭证 | 只注入 `LARKSUITE_CLI_TENANT_ACCESS_TOKEN` 时自动只允许 bot；注入 App ID/Secret 时设置 `LARKSUITE_CLI_DEFAULT_AS=bot` |
+
+未声明时一律以用户身份执行；用户登录失效会直接报错并提示登录，不会改用 bot 建站。
+
+## 授权对象与结果
+
+```bash
+base-database-cli init . --schema schema.json --name <名称> --as bot
+base-database-cli init . --schema schema.json --name <名称> --as bot --grant-admin <ou_...>
+```
+
+- 授权对象：当前 lark-cli 登录用户，加上 `--grant-admin` 指定的用户（追加，不替代）。
+- 新建资源前必须有授权对象：两者都没有时 init 在任何写入前以 `blocked` 退出，否则建出的资源无人能打开。此时请用户按 `nextAction` 登录 lark-cli 后重跑原命令；open_id 按应用区分，用户无从得知，不要向用户索要。
+- `--grant-admin` 指定了其他人时，两人都获得 Base `full_access` 与应用管理员：`userOpenId` 为指定用户，当前登录用户在 `alsoGrantedOpenId` 中报告。当前登录用户的 Base 授权由 lark-cli 建 Base 时自动授予，无法跳过；不希望其获得权限时，在没有用户登录的 bot profile 中执行。
+- 范围：只针对本次 init 新建的 Base（`full_access`）与应用（管理员）。通过 `--base-token` / `--app-token` 绑定的已有资源不做任何授权。
+- `--grant-admin` 供团队 Agent 等宿主使用：只在以 bot 搭建时可用，只接受同一应用下来自可信来源（如宿主收到的消息事件）的发起人 `open_id`；不从对话或通讯录推断。
+
+返回的 `handoff` 分别报告 `base` 与 `app`：
+
+| status | 含义 | 处理 |
+|--------|------|------|
+| `granted` | 已授权给 `userOpenId` | 告知用户可直接打开 |
+| `skipped` | 续跑时没有授权对象 | 登录 lark-cli 后用原命令加 `--resume` |
+| `failed` | 授权请求失败，`hint` 给出原因 | 按 `hint` 修复后用原命令加 `--resume` 重试，或按下文手动补加 |
+| `not_applicable` | 资源不是本次新建 | 无需处理 |
+
+授权失败不影响建站结果（`ok` 仍为 true），但必须把 `handoff` 的每一项如实告诉用户。应用授权失败后重试前，先确认对方是否已是应用管理员（超时的请求可能已生效）。初始化已完成时，原命令加 `--resume` 只重试未完成的授权，不再发出任何建站写入。
+
+## 手动补加 / 核对
+
+| 目标 | 命令 |
+|------|------|
+| 加 Base 管理员 | `lark-cli drive +member-add --token <base> --type bitable --member-type openid --member-id <ou_...> --perm full_access --as bot --yes` |
+| 列/移除 Base 协作者 | `lark-cli drive +member-list` / `+member-remove`（同参） |
+| 加/移除应用管理员 | `lark-cli api POST /open-apis/base/v3/sites/<app-token>/members --data '{"add":[{"member_id":"<ou_...>","member_type":"openid","role":3}]}' --as bot`（移除用 `{"remove":[...]}`，不传 role） |
+
+- `member_type` 是 id 种类（`openid` / `openchat` / `opendepartmentid`），`member_id` 是对应的开放平台 id，不传内部数字 id。
+- 应用成员接口需要 `base:appmode:update` scope，调用者须为该应用管理员（新建应用的 bot 默认满足）；暂不支持添加其他租户的成员。
+- 高危写前可 `--dry-run` 核对；`opendepartmentid` 只支持 `--as user`。
+
+## 安全边界
+
+- 共享宿主不要在 bot profile 中保留某个人的用户登录，否则授权会落到这个人。
+- 授权不改变运行态数据边界：加管理员只影响能否直接打开、管理资源，不放开页面数据访问（Mutation / FaaS / Database Function 边界不变）。Preview/Prod 准入见[权限设计](permission-design.md#preview-与-prod-准入)。
+- 移除协作者、下调权限同为危险操作，按 [Skill 主流程](../SKILL.md#外部操作与授权)核对目标与影响。
+
+## bot 的 scope 前置
+
+以 bot 走 `init` 建站，应用需申请：`base:app:create`、`base:appmode:create/read/update`、`base:table:read/create/update`、`base:field:read/create/update`、`base:record:create/read/update`、`base:site:create`、`bitable:app`；交接 Base 管理员另需 `docs:permission.member:create`。缺少时服务端返回 `99991672` 并给出申请链接（租户 scope 自动审批，应用管理员一次性配置）。

package/skills/lark-base-database/references/database-function.md

@@ -377,4 +377,4 @@ Page 新入口 HTTP body：
 
 `base-database-cli deploy` 统一调用服务端查询校验。编译成功仅证明编译阶段；实际读取按[发布与交付](release.md)或用户要求的[专项验收](verification.md)执行。失败时保留具体错误节点和 LogID，按 Catalog、参数与支持边界修复，不猜测响应 envelope 绕过。
 
-workspace 或已安装 SDK 的工程，`contracts generate` 使用工程内 SDK `/codegen`。CLI 提取契约并隔离执行生成器；check 只比较生成内容，过期时先重新运行 `contracts generate`。`SDK_CODEGEN_UNAVAILABLE` 表示需要安装包含 codegen 的 SDK，按 CLI 报错给出的安装命令执行（版本与新建工程模板一致），不能通过跳过生成或回退 CLI 模板修复。未安装 SDK 的 classic 工程保留旧输入类型生成行为。
+workspace 或已安装 SDK 的工程，`contracts generate` 使用工程内 SDK `/codegen`。CLI 提取契约并隔离执行生成器；check 只比较生成内容。依赖准备、契约过期及 `SDK_CODEGEN_UNAVAILABLE` 的处理统一见[Check 与契约生成](development.md#check-与契约生成)，不能通过跳过生成或回退 CLI 模板修复。未安装 SDK 的 classic 工程保留旧输入类型生成行为。

package/skills/lark-base-database/references/development.md

@@ -221,7 +221,7 @@ workspace 的输入类型与 `DatabaseFunctionParameterOptions` 统一生成在
 
 - `SDK_BEHIND_CLI` 是非阻断的版本提醒。默认保留 SDK，读取警告 `packagePath` 所在包的 docs 和示例，不套用标注较新适用版本的 Skill 示例。
 - `SDK_VERSION_INVALID` 表示已安装 SDK 的包信息损坏，先修复工程依赖。`doctor` 将此错误记录在 `sdkCompatibility` 中（`severity: error`），继续检查登录、scope 和服务；`check`、`contracts generate`、`deploy` 则停止并报告该错误。
-- 用户已授权升级 SDK 时，执行警告给出的 `upgradeCommand`。读取目标 SDK `CHANGELOG.md` 中跨过的每个不兼容版本的 Migration：确认会坏什么、定位受影响调用、按步骤修改源码。然后依次运行 `base-database-cli contracts generate`、`base-database-cli check --json` 和工程 build；失败时按诊断继续迁移，不用 `as` 强转或自行指定返回泛型绕过迁移错误。
+- 用户已授权升级 SDK 时，执行警告给出的 `upgradeCommand`。读取目标 SDK `CHANGELOG.md` 及包内 docs 的升级与兼容说明，核对跨过的每个不兼容版本：确认会坏什么、定位受影响调用、按步骤修改源码。涉及默认写后读行为时，按目标包 `docs/page.md` 和[写后读指引](mutations.md#写后读)处理同步中状态。然后依次运行 `base-database-cli contracts generate`、`base-database-cli check --json` 和工程 build；失败时按诊断继续迁移，不用 `as` 强转或自行指定返回泛型绕过迁移错误。
 
 CLI 不自动升级依赖或改写业务代码。工程结构和 helper 改动由 coding agent 按[工程迁移指南](workspace-migration.md)执行；结构迁移另需用户授权，不因 SDK 警告擅自进行。
 
@@ -231,6 +231,18 @@ CLI 不自动升级依赖或改写业务代码。工程结构和 helper 改动
 
 ## Check 与契约生成
 
+workspace 或 SDK 工程修改 Function 声明后，在项目根目录执行：
+
+<!-- example: prepare-workspace-contracts -->
+```bash
+base-database-cli contracts generate
+base-database-cli check --json
+```
+
+`contracts generate` 默认校验依赖声明与锁文件，复用 check/deploy 的安装缓存；依赖缺失或安装指纹变化时，使用 CLI 自带 npm 按现有锁文件执行 npm ci，再生成契约。workspace 使用根依赖，classic SDK 工程分别准备 Page 和服务端依赖；无 SDK 的 classic 保留原有输入类型生成，不安装依赖。仅改页面且不影响契约时直接 check。
+
+已准备好依赖、需要保留当前安装现场或独立管理安装步骤时，可执行 `base-database-cli contracts generate --no-install`；该选项直接使用现有依赖，不运行 npm ci、不更新安装缓存，缺少生成所需依赖时仍会报错。`CONTRACT_DEPENDENCIES_FAILED` 表示安装前的锁文件校验或依赖安装失败，按具体诊断修复后重试同一命令；不删除锁文件或切换 SDK 版本。`SDK_CODEGEN_UNAVAILABLE` 表示生成入口不可用，实际安装包缺少 codegen 能力时按[SDK 升级](#工程迁移与-sdk-升级)取得授权后处理。
+
 `check` 先在本地读取全部 Function 声明，按需安装依赖、核对 Function 契约，再用与 deploy 相同的本次 kind 集合调用统一 `/functions/validate`，最后构建 Page/FaaS。payload 始终声明 `sql/edge/mutation`；存在 `ai/` 根时还声明 ai kind，其中空根表示明确校验空集合。Validate 不修改 binding、draft、Artifact 或发布状态。workspace 或 SDK 工程的契约发生变化时会报告 `CONTRACT_STALE`；先在项目根显式执行 `base-database-cli contracts generate`，再运行 `base-database-cli check --json`，不要反复 check 或手改生成物。
 
 只有无 App SDK 的 classic 使用本地 metadata 自动更新输入类型。生成形态仍按[Function 调用契约](#function-调用契约)选择；check 的自动生成不改变 helper 路由。`--no-install` 要求依赖已经就绪，不能绕过契约核对。只有明确没有应用 API 访问条件的离线检查才使用 `--local-only`；结果中的 `serverValidation.status=not_run` 表示 SQL 编译、Catalog、AI model profile 和其他服务端语义均未验证。显式 `--skip-ai-functions` 时，AI 声明不进入本次校验 payload，结果中的 AI 数量为 0，不能报告 AI 已校验。旧工程缺少整个 `ai/` 根时同样不声明 ai kind，但结果会给出 `AI_FUNCTION_ROOT_ABSENT_PRESERVED`，表示远端 AI 被保留且未校验、未同步；先用公共 `pull` 恢复，而不是把缺失根当成空集合。

package/skills/lark-base-database/references/faas.md

@@ -162,13 +162,16 @@ type DownstreamOutcome<T> =
 
 FaaS 使用 `context.fetch` 调用固定的批量写入路由；只使用线上 origin：
 
-| 目标 | Origin |
+| 环境／品牌 | Origin |
 |---|---|
-| Online | `https://open.feishu.cn` |
+| Online 飞书 | `https://open.feishu.cn` |
+| Online Lark（海外） | `https://open.larksuite.com` |
+
+使用 SDK 的 `ctx.records` 时，地址由 SDK 自动选择，无需手动配置。后文的 `context.fetch` 示例以飞书为例，Lark 使用上表对应的地址，路径及请求体相同。
 
 #### 应用记录写入协议
 
-FaaS 只使用以下五个固定路由，均为 `POST`，请求头为
+站点记录与附件写入使用以下五个固定路由，均为 `POST`，请求头为
 `Content-Type: application/json; charset=utf-8`：
 
 ```http

package/skills/lark-base-database/references/mutations.md

@@ -303,7 +303,7 @@ workspace 从已安装 SDK `/page` 导入两个 helper，并按包内 docs 核
 
 ### 写后读
 
-Page 示例适用版本：SDK 0.3.3 起（workspace 工程的默认写后读、`DataNotReadyError` 与 `readYourWrites: false` 选项）。先读已安装 SDK 的 `package.json` 版本；未满足时按[SDK 升级流程](development.md#工程迁移与-sdk-升级)处理，升级前页面的读按普通查询发起。
+Page 示例适用版本：SDK 0.4.0 起（workspace 工程的默认写后读、`DataNotReadyError` 与 `readYourWrites: false` 选项）。先读已安装 SDK 的 `package.json` 版本；未满足时按[SDK 升级流程](development.md#工程迁移与-sdk-升级)处理，升级前页面的读按普通查询发起。
 
 Page 的读默认读到本会话此前的写入，包括写后由刷新结果联动触发的查询；数据尚未追上时由服务端等待、SDK 重试。
 

package/skills/lark-base-database/references/permission-design.md

@@ -130,6 +130,7 @@ FaaS 调用 Database Function 与写入的协议见[FaaS 协议](faas.md#faas-
 - 对外分发或扩大分享范围前，提醒用户核对应用文档的分享设置——该设置决定访问准入，不能由页面代码代替。
 - Preview 可验证已授权管理者的行为，不能据此证明普通成员/访客的行为；身份和覆盖边界见[Preview 与 Prod 准入](#preview-与-prod-准入)。普通成员多角色验收在已授权的 Prod 任务中用真实账号完成。
 - 修改原生 Base 角色或高级权限、删除 binding 属于危险操作，按 [Skill 主流程](../SKILL.md#外部操作与授权)核对具体目标和影响范围的授权。
+- 以机器人（bot）身份搭建的 Base 与应用属主是机器人；init 只把本次新建的资源交给当前 CLI 用户及 `--grant-admin` 追加指定的人，结果与补救见[bot 建站与交接](collaborator-handoff.md)。加管理员不改变运行态数据边界。
 
 ## Preview 与 Prod 准入
 

package/skills/lark-base-database/references/release.md

@@ -4,7 +4,7 @@
 
 ## 站点 README
 
-新建站点时，先从用户原始建站 Prompt 的主要自然语言确定 README 语言：支持中文、日文、英文；其他语言或无法判断主要语言时使用英文。用户明确指定 README 使用这三种语言之一时按其指定语言填写；指定其他语言时仍使用英文。读取初始化生成的项目根目录 `README.md`，按选定语言重写业务标题与正文、清理 hello 示例，并移除实际存在的占位内容；命令、路径和代码标识符保留原样。修改已有站点时沿用现有 README 语言，除非用户明确要求切换。README 是生成时确定的源码文档，不随 Site 运行时的宿主或浏览器语言变化。
+新建站点时，先从用户原始建站 Prompt 的主要自然语言确定 README 语言：支持中文、日文、英文；其他语言或无法判断主要语言时使用英文。用户明确指定 README 使用这三种语言之一时按其指定语言填写；指定其他语言时仍使用英文。读取初始化生成的项目根目录 `README.md`，按选定语言重写业务标题与正文，并移除实际存在的占位内容；不需要的问候 Function 按[清理初始化示例](workspace.md#清理初始化示例)处理。命令、路径和代码标识符保留原样。修改已有站点时沿用现有 README 语言，除非用户明确要求切换。README 是生成时确定的源码文档，不随 Site 运行时的宿主或浏览器语言变化。
 
 四个必要章节使用下表中所选语言的标题；CLI 接受这三组标题，并只检查结构、占位符和章节是否非空，不判断正文语言或业务描述是否属实：
 

package/skills/lark-base-database/references/style-guide.md

@@ -6,7 +6,7 @@
 
 1. 先明确用户、目标、核心流程、状态变化和失败路径，再设计表与页面。
 2. 具有独立生命周期、权限或统计需求的业务事实使用独立表，并明确数据所有权、归档和追溯要求。
-3. 每张表有可读主字段；存在独立生命周期时设计状态，存在责任分配时设计负责人，按业务与审计需求配置时间、标识和关系。
+3. 每张表有可读主字段；存在独立生命周期时设计状态，存在责任分配时设计负责人，按业务与审计需求配置时间、标识和关系。底表也会被 Base 协作者直接打开浏览，表结构按[底表设计](base-table-design.md)执行。
 4. 状态使用受控单选并定义合法转换；关系、金额、日期、人员使用对应 Base 字段。
 5. 页面围绕用户任务组织，不按表机械生成 CRUD。
 6. 每个 operation 定义固定输入、输出、权限、失败语义和影响范围。

package/skills/lark-base-database/references/workspace.md

@@ -17,7 +17,7 @@ CLI/存量 classic 使用 Node.js 20.19+；新建 workspace 与契约生成使
 
 `skill install` 安装用于搭建、修改和发布应用的开发者 Skill；外部 Agent 使用已发布业务功能时，按[站点 Skill 安装](agent-tools.md#安装到本地-agent)运行 `agent-tools skill install`。
 
-公开 CLI 只使用 `online` 环境；`init`、`pull` 等支持环境参数的命令显式传 `--env online`，`deploy` 不接受该参数。CLI、OpenAPI、Accounts、应用和 Page runtime 必须处于同一环境；原生资源操作始终使用 `--as user`。
+公开 CLI 只使用 `online` 环境；`init`、`pull` 等支持环境参数的命令显式传 `--env online`，`deploy` 不接受该参数。CLI、OpenAPI、Accounts、应用和 Page runtime 必须处于同一环境；原生资源操作默认使用 `--as user`；以机器人（bot）身份搭建时按 [bot 建站与交接](collaborator-handoff.md) 显式声明身份。
 
 首次使用 `lark-cli` 时读取当前入口的 `--help`，本会话复用已确认的命令能力；不只按版本号判断。
 
@@ -34,7 +34,7 @@ Windows 官方 npm 安装的 `lark-cli.cmd` 由 Base Database CLI 解析到同
 
 优先使用本机已安装的 `base-database-cli`。已知全局安装存在但 PATH 异常时，使用确认过的可执行路径；不自动修改 shell 配置。没有可用本地入口时，回退 `npx @lark-base-open/base-database-cli`；需要固定版本时使用 `npx @lark-base-open/base-database-cli@<已确认的精确版本>`。不猜 npm scope，不全盘搜索或反复安装。
 
-首次使用先确认 `lark-cli` 与 `base-database-cli` 可执行；缺失时按上述安装命令及回退入口处理。执行 `base-database-cli doctor`；认证缺失时按[认证与重新授权](#认证与重新授权)处理，用户完成授权后重新执行 doctor，`ok: true` 后再 init。`init`、`pull` 不会自动触发登录。
+首次使用先确认 `lark-cli` 与 `base-database-cli` 可执行；缺失时按上述安装命令及回退入口处理。需要诊断时，按本任务身份执行 `base-database-cli doctor`；显式使用 Bot 时执行 `base-database-cli doctor --as bot`。doctor 沿用显式 `--as` 或 lark-cli 的 strict-mode / default-as；未声明时使用 User，不因用户登录失效自动切到 Bot。User 路径检查用户授权；Bot 路径只探测应用身份的只读服务访问，`userScopes.status=not_applicable` 表示不检查 UAT，不代表已验证全部建站或交接权限。doctor 的 `ok: true` 不替代后续业务命令的权限与结果检查。`init`、`pull` 不会自动触发登录。
 
 ### 公开 CLI 版本预检
 
@@ -55,7 +55,9 @@ CI 跳过更新检查；其他环境正常检查。检查失败不阻塞任务
 
 ## 认证与重新授权
 
-沿用本任务已选定的 CLI 入口、环境和同一 profile。`not_configured`（原文 `not configured`）、`token_missing`（用户身份原文 `no access token available for user`，或 `need_user_authorization (user: …)`）来自 lark-cli；`need_user_authorization` 是后者的消息标记，`…` 代表实际用户标识。`missing_scopes` 由本 CLI 检查用户 scope 后返回，原文包含 `missing_scopes:` 和 `Run auth login with the same CLI, environment and profile to authorize these user scopes.`：说明缺少用户授权，执行 `base-database-cli auth login`，用户完成授权后只重试原命令一次；仍失败时停止并保留原错误，不循环授权。
+沿用本任务已选定的 CLI 入口、环境、身份和同一 profile。以下用户登录恢复仅适用于 User（UAT）；Bot（TAT）凭证或应用权限错误交由宿主或应用管理员按原错误修复，不通过用户登录恢复，也不切换身份。Bot 建站与权限前置见 [bot 建站与交接](collaborator-handoff.md)。
+
+User 路径中，`not_configured`（原文 `not configured`）、`token_missing`（用户身份原文 `no access token available for user`，或 `need_user_authorization (user: …)`）来自 lark-cli；`need_user_authorization` 是后者的消息标记，`…` 代表实际用户标识。`missing_scopes` 由本 CLI 检查用户 scope 后返回，原文包含 `missing_scopes:` 和 `Run auth login with the same CLI, environment and profile to authorize these user scopes.`：说明缺少用户授权，执行 `base-database-cli auth login`，用户完成授权后只重试原命令一次；仍失败时停止并保留原错误，不循环授权。
 
 `app_scope_not_applied` 来自 lark-cli（原文 `access denied: app has not applied for the required scope(s)`，`app` 后可能附应用 ID），表示应用侧尚未申请所需 scope；不执行 auth login，报告应用权限未开通的阻塞并保留原错误，按错误提示处理。
 
@@ -103,12 +105,14 @@ CLI 自动保存 init、pull 和提交成功后的草稿基线。`REMOTE_SOURCE_
 
 ### 从零创建 Base
 
-编写 schema 前，按已确认的文档入口读取字段规范：支持 `skills read` 时先执行 `lark-cli skills read lark-base` 查看文件列表，再读取其中的字段定义 reference（当前为 `references/lark-base-field-json.md`，以列表实际名称为准）；否则直接读取环境中 lark-base 的对应 reference，并用 `lark-cli base +table-create --help` 核对当前命令契约，不再尝试已知缺失的入口。不要猜测属性。`tables[].fields` 使用与 `lark-cli base +base-create/+table-create --fields` 相同的字段定义；init 会先创建每张表的主字段，取得全部真实表 ID 后再按原顺序创建其余字段。
+编写 schema 前，按已确认的文档入口读取字段规范：先执行 `lark-cli skills list lark-base/references` 获取当前 reference 路径列表，再用 `lark-cli skills read <reference-path>` 读取其中的字段定义文档；`<reference-path>` 使用列表返回的完整路径，不猜测或固定文件名。命令不可用时，直接读取环境中 lark-base 的对应 reference，并用 `lark-cli base +table-create --help` 核对当前命令契约，不再尝试已知缺失的入口。不要猜测属性。`tables[].fields` 使用与 `lark-cli base +base-create/+table-create --fields` 相同的字段定义；init 会先创建每张表的主字段，取得全部真实表 ID 后再按原顺序创建其余字段。
 
 - 用户所在地或需求明确了时区时，`init --schema` 追加 `--time-zone <IANA 时区>`（例如 `Asia/Tokyo`）；未指定时由服务端按租户默认时区创建。
+- 表结构先按[底表设计](base-table-design.md)完成两层设计。
 - 首个字段成为表的主字段，优先采用可读的文本标识；其他类型先核对主字段限制。
 - 单选和多选都用 `select`，多选显式设置 `"multiple": true`，选项按字段规范声明。
 - `link` 字段必须提供 `link_table`，且名称与本次 Schema 中的目标表完全一致；自关联和跨表关联会在所有表创建后补建，不需要按关联依赖调整表顺序。
+- Schema 包含 `formula` 或 `lookup` 时，编写表达式或引用条件前先读取当前 lark-base 中对应类型的指南；字段结构校验不能代替该步骤。
 - `datetime.style.format` 使用当前 Base 支持的固定枚举，不能自行增加秒级展示格式；底层时间精度与展示格式分别处理。
 - 创建字段的 schema、查询类型与记录 CellValue 是不同协议，不互相替代。
 
@@ -126,9 +130,9 @@ CLI 自动保存 init、pull 和提交成功后的草稿基线。`REMOTE_SOURCE_
           "name": "状态",
           "multiple": false,
           "options": [
-            { "name": "待处理" },
-            { "name": "进行中" },
-            { "name": "已完成" }
+            { "name": "待处理", "hue": "Gray" },
+            { "name": "进行中", "hue": "Blue" },
+            { "name": "已完成", "hue": "Green" }
           ]
         },
         {
@@ -191,6 +195,17 @@ package-lock.json    # 唯一根依赖锁
 
 只从 `catalog.json` 读取表名、字段名、ID、选项和查询类型，不根据建表输入猜测 Catalog 结果。
 
+### 清理初始化示例
+
+初始化生成的 `server/functions/hello/` 是问候示例。业务不使用它时，在首次生成契约和 check 前删除整个目录，包括 `index.ts`、`contract.ts`、`meta.json`，不要只删除文件后留下空目录。在项目根目录执行：
+
+<!-- example: remove-starter-hello -->
+```bash
+node -e "require('node:fs').rmSync('server/functions/hello', { recursive: true, force: true })"
+```
+
+该命令也可清理逐文件删除后留下的空目录；已改为业务用途的 hello 和其他需求外 Function 保留。同步移除页面中实际存在的示例调用，再按[Check 与契约生成](development.md#check-与契约生成)生成契约并检查。CLI 仍将非完整的 Function 目录视为错误，不会把残缺声明静默排除。
+
 ### 初始化失败与阶段回执
 
 `--schema` 路径会在首个远端创建前校验整份 schema；按返回的字段路径修正。本地预检通过不代表权限、配额或服务端语义检查通过。