@77-zhike/app-sdk 0.2.0-d7b1.18 → 0.2.0-d7b1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@77-zhike/app-sdk",
-  "version": "0.2.0-d7b1.18",
+  "version": "0.2.0-d7b1.20",
   "description": "智客 Integration App 一期 SDK 与本地 Toolchain",
   "repository": {
     "type": "git",
@@ -67,5 +67,5 @@
       "optional": true
     }
   },
-  "gitHead": "9494f3959fd49fe5dd4d2f500ab6d3c041c7db00"
+  "gitHead": "c7f1b793276cbde656dbd058731fcb8b51b95745"
 }

package/src/cli/index.js

@@ -10,6 +10,7 @@ import {
   assertExistingProjectTarget,
   initializeExistingProject,
   initializeProject,
+  organizationLabel,
   validateAppSlug,
 } from "./project-init.js";
 import { uploadAppBundle } from "./upload-bundle.js";
@@ -30,6 +31,7 @@ export async function runCli(
     fetchImpl = globalThis.fetch,
     openBrowser,
     selectWorkspace,
+    selectOrganization,
     isInteractive = Boolean(process.stdin.isTTY),
     developmentRunner = watchDevelopmentApp,
   } = {},
@@ -104,16 +106,7 @@ export async function runCli(
       return { command: "login" };
     }
     if (command === "init") {
-      const here = rest.includes("--here");
-      const slugArgs = rest.filter((arg) => arg !== "--here");
-      if (slugArgs.length !== 1 || slugArgs[0].startsWith("-") ||
-          rest.length !== (here ? 2 : 1)) {
-        throw new ZhikeCliError(
-          "zhike_init_usage_invalid",
-          "用法：zhike init <app-slug> [--here]",
-        );
-      }
-      const appSlug = validateAppSlug(slugArgs[0]);
+      const { appSlug, here, requestedOrganizationId } = _parseInitArguments(rest);
       const targetDirectory = here ? cwd : resolve(cwd, appSlug);
       if (here) await assertExistingProjectTarget(targetDirectory);
       else await assertEmptyTarget(targetDirectory);
@@ -132,9 +125,10 @@ export async function runCli(
       );
       const result = here
         ? await initializeExistingProject({ projectDirectory: targetDirectory, appSlug,
-          apiBaseUrl: config.apiBaseUrl, authenticatedApi })
+          apiBaseUrl: config.apiBaseUrl, authenticatedApi, requestedOrganizationId, selectOrganization, isInteractive })
         : await initializeProject({ targetDirectory, appSlug, apiBaseUrl: config.apiBaseUrl,
-          authenticatedApi, ...(scaffold ? { scaffold } : {}) });
+          authenticatedApi, requestedOrganizationId, selectOrganization, isInteractive, ...(scaffold ? { scaffold } : {}) });
+      output.write(`开发者空间：${organizationLabel(result.organization)}\n`);
       output.write(
         `${result.created ? "已创建" : "已复用"} App ${result.app.slug}，项目位于 ${here ? "当前目录" : `${appSlug}/`}（总耗时 ${_formatElapsed(startedAt)}）\n`,
       );
@@ -214,6 +208,26 @@ function _rejectArguments(args) {
   }
 }
 
+function _parseInitArguments(args) {
+  let here = false;
+  let requestedOrganizationId = null;
+  let slug = null;
+  const invalid = () => new ZhikeCliError("zhike_init_usage_invalid",
+    "用法：zhike init <app-slug> [--here] [--organization <organization-id>]");
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--here" && !here) here = true;
+    else if (arg === "--organization" && !requestedOrganizationId) {
+      const value = args[++index];
+      if (!value || !/^[0-9A-HJKMNP-TV-Z]{26}$/.test(value)) throw invalid();
+      requestedOrganizationId = value;
+    } else if (!arg.startsWith("-") && !slug) slug = arg;
+    else throw invalid();
+  }
+  if (!slug) throw invalid();
+  return { appSlug: validateAppSlug(slug), here, requestedOrganizationId };
+}
+
 function _parseDevArguments(args) {
   if (args.length === 0) return null;
   if (args.length === 2 && args[0] === "--workspace" && args[1]) {

package/src/cli/local-commands.js

@@ -13,7 +13,7 @@ export const commandHelp = {
   version: "version [--json]",
   doctor: "doctor [--json]",
   login: "login",
-  init: "init <app-slug> [--here]",
+  init: "init <app-slug> [--here] [--organization <organization-id>]",
   validate: "validate",
   build: "build",
   upload: "upload",

package/src/cli/project-init.js

@@ -10,6 +10,8 @@ import {
 } from "node:fs/promises";
 import { constants } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stripVTControlCharacters } from "node:util";
 
 import { normalizeOrigin, TOOLING_VERSION } from "../config.js";
 import { ZhikeCliError } from "../errors.js";
@@ -21,21 +23,27 @@ export async function initializeProject({
   apiBaseUrl,
   authenticatedApi,
   scaffold = scaffoldProject,
+  requestedOrganizationId = null,
+  selectOrganization,
+  isInteractive = Boolean(process.stdin.isTTY),
 }) {
   validateAppSlug(appSlug);
   const target = resolve(targetDirectory);
   await assertEmptyTarget(target);
 
-  const { app, organization, binding, created } = await resolveAppBinding({ appSlug, apiBaseUrl, authenticatedApi });
+  const { app, organization, binding, created } = await resolveAppBinding({ appSlug, apiBaseUrl, authenticatedApi,
+    requestedOrganizationId, selectOrganization, isInteractive });
   await scaffold({ targetDirectory: target, binding });
   return { app, organization, binding, created, targetDirectory: target };
 }
 
-export async function initializeExistingProject({ projectDirectory, appSlug, apiBaseUrl, authenticatedApi }) {
+export async function initializeExistingProject({ projectDirectory, appSlug, apiBaseUrl, authenticatedApi,
+  requestedOrganizationId = null, selectOrganization, isInteractive = Boolean(process.stdin.isTTY) }) {
   validateAppSlug(appSlug);
   const target = resolve(projectDirectory);
   await assertExistingProjectTarget(target);
-  const { app, organization, binding, created } = await resolveAppBinding({ appSlug, apiBaseUrl, authenticatedApi });
+  const { app, organization, binding, created } = await resolveAppBinding({ appSlug, apiBaseUrl, authenticatedApi,
+    requestedOrganizationId, selectOrganization, isInteractive });
   await mkdir(resolve(target, ".zhike"), { recursive: true });
   await writeFile(resolve(target, ".zhike", "project.json"), serializeProjectBinding(binding), { flag: "wx" });
   return { app, organization, binding, created, targetDirectory: target };
@@ -64,17 +72,33 @@ export async function assertExistingProjectTarget(projectDirectory) {
   }
 }
 
-async function resolveAppBinding({ appSlug, apiBaseUrl, authenticatedApi }) {
+async function resolveAppBinding({ appSlug, apiBaseUrl, authenticatedApi,
+  requestedOrganizationId, selectOrganization, isInteractive }) {
   const organizations = await authenticatedApi.listOrganizations();
-  if (!Array.isArray(organizations) || organizations.length !== 1) {
+  if (!Array.isArray(organizations) || organizations.some((item) =>
+    !item || !/^[0-9A-HJKMNP-TV-Z]{26}$/.test(item.id) || typeof item.name !== "string" || !item.name.trim()) ||
+    new Set(organizations.map(item => item.id)).size !== organizations.length) {
+    throw new ZhikeCliError("zhike_organizations_response_invalid", "Developer Server 返回了无效的开发者空间列表");
+  }
+  if (organizations.length === 0) {
     throw new ZhikeCliError(
       "zhike_developer_organization_unavailable",
-      organizations?.length === 0
-        ? "请先在 Developer Console 激活开发者组织"
-        : "当前账号存在多个开发者组织，D2-2 暂不支持隐式选择",
+      "请先在 Developer Console 激活开发者空间",
     );
   }
-  const organization = organizations[0];
+  let selectedId = requestedOrganizationId;
+  if (!selectedId && organizations.length === 1) selectedId = organizations[0].id;
+  if (!selectedId) {
+    if (!isInteractive && !selectOrganization) {
+      throw new ZhikeCliError("zhike_organization_selection_required",
+        "当前账号有多个开发者空间，非交互环境必须指定 --organization <organization-id>");
+    }
+    selectedId = await (selectOrganization || promptForOrganization)(organizations);
+  }
+  const organization = organizations.find(item => item.id === selectedId);
+  if (!organization) {
+    throw new ZhikeCliError("zhike_organization_not_available", "未选择可访问的开发者空间，请使用列表中的空间 ID");
+  }
   let app = await authenticatedApi.getAppBySlug(organization.id, appSlug);
   let created = false;
   if (!app) {
@@ -99,6 +123,26 @@ async function resolveAppBinding({ appSlug, apiBaseUrl, authenticatedApi }) {
   return { app, organization, binding, created };
 }
 
+export async function promptForOrganization(organizations, { input = process.stdin, output = process.stdout } = {}) {
+  const prompt = createInterface({ input, output });
+  try {
+    output.write("请选择 App 所属的开发者空间：\n");
+    organizations.forEach((organization, index) => {
+      output.write(`  ${index + 1}. ${organizationLabel(organization)}\n`);
+    });
+    const answer = (await prompt.question("输入序号：")).trim();
+    const index = /^\d+$/.test(answer) ? Number(answer) - 1 : -1;
+    return organizations[index]?.id ?? "";
+  } finally {
+    prompt.close();
+  }
+}
+
+export function organizationLabel(organization) {
+  const name = stripVTControlCharacters(organization.name).replace(/[\x00-\x1f\x7f-\x9f\u2028\u2029]/g, " ").trim();
+  return `${name} (${organization.id})`;
+}
+
 export async function assertEmptyTarget(targetDirectory) {
   try {
     await stat(targetDirectory);

package/src/client/index.d.ts

@@ -164,6 +164,8 @@ export interface PageDefinition {
   showInNavigation?: boolean;
   /** 默认显示宿主标题栏；false 时由 Page 自行提供标题。移动端仍保留返回导航。 */
   showHeader?: boolean;
+  /** 缺省 false，按内容自然滚动；true 由宿主提供扣除导航后的确定高度，内部滚动由 Page 布局负责。 */
+  fillHeight?: boolean;
   /** 纯 React Page component，只接收有界业务参数。 */
   Page: ComponentType<PageProps>;
 }
@@ -267,3 +269,6 @@ export type { RestrictedInputSchema, PreparePdfTemplateInput, OpenPdfDocumentInp
 export function preparePdfTemplate(input: import('./documents.js').PreparePdfTemplateInput): Promise<import('./documents.js').PreparedPdfTemplate | null>;
 /** Desktop/H5认证文件交付；started只表示已交浏览器，不证明磁盘保存。 */
 export function openPdfDocument(input: import('./documents.js').OpenPdfDocumentInput): Promise<import('./documents.js').OpenPdfDocumentResult>;
+
+/** 以当前成员权限打开稳定报告产物；宿主控制预览，不执行App提供的HTML。 */
+export function openArtifact(input: import('./interactions.js').OpenArtifactOptions): Promise<void>;

package/src/client/index.js

@@ -36,7 +36,7 @@ export function definePage(definition) {
     throw new TypeError("Page definition 必须是对象");
   }
   const keys = Object.keys(definition).sort();
-  const allowed = new Set(["Page", "name", "icon", "order", "variant", "showInNavigation", "showHeader"]);
+  const allowed = new Set(["Page", "name", "icon", "order", "variant", "showInNavigation", "showHeader", "fillHeight"]);
   if (keys.some(key => !allowed.has(key))) {
     throw new TypeError("Page definition 包含不支持的字段");
   }
@@ -56,6 +56,9 @@ export function definePage(definition) {
   if (typeof definition.Page !== "function") {
     throw new TypeError("Page definition 必须提供 React Page component");
   }
+  if (definition.fillHeight !== undefined && typeof definition.fillHeight !== 'boolean') {
+    throw new TypeError('Page fillHeight 必须是布尔值');
+  }
   if (definition.showHeader !== undefined && typeof definition.showHeader !== 'boolean') {
     throw new TypeError('Page showHeader 必须是布尔值');
   }
@@ -70,6 +73,7 @@ export function definePage(definition) {
     type: "page",
     variant: definition.variant,
     ...(definition.showHeader === undefined ? {} : { showHeader: definition.showHeader }),
+    ...(definition.fillHeight === undefined ? {} : { fillHeight: definition.fillHeight }),
     ...(definition.showInNavigation === undefined ? {} : { showInNavigation: definition.showInNavigation }),
   });
 }
@@ -86,3 +90,5 @@ export function queryAnalysis() { return Promise.reject(new Error('runtime_analy
 export function openAssistant() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }
 export function preparePdfTemplate() { return Promise.reject(new Error('runtime_document_unsupported')); }
 export function openPdfDocument() { return Promise.reject(new Error('runtime_document_unsupported')); }
+
+export function openArtifact() { return Promise.reject(new Error('runtime_host_interaction_unavailable')); }

package/src/client/interactions.d.ts

@@ -1,3 +1,7 @@
+export interface OpenArtifactOptions {
+  /** 私有报告的稳定ID；不承载身份或授予读取权限。 */
+  artifactId: string;
+}
 export interface OpenAssistantOptions {
   /** App 内的场景名；同 App/场景跨页面续聊，Host 自动拼接 App 前缀。 */
   scenario: string;
@@ -11,9 +15,10 @@ export interface ToastOptions { message: string; tone?: 'info' | 'success' | 'er
 export interface ConfirmOptions { title: string; description?: string; confirmLabel?: string; cancelLabel?: string }
 export interface OpenExternalUrlOptions { url: string }
 export interface NavigateOptions { destination: import('./destinations.js').AppDestination }
-export type HostInteraction = {operation:'preparePdfTemplate';input:import('./documents.js').PreparePdfTemplateInput} | {operation:'openPdfDocument';input:import('./documents.js').OpenPdfDocumentInput} | {operation:'openAssistant';input:OpenAssistantOptions} | {operation:'showToast';input:ToastOptions} | {operation:'confirm';input:ConfirmOptions} | {operation:'navigate';input:NavigateOptions} | {operation:'openExternal';input:OpenExternalOptions} | {operation:'openExternalUrl';input:OpenExternalUrlOptions};
-export function assertHostInteraction(operation: unknown, input: unknown): Readonly<ToastOptions | ConfirmOptions | NavigateOptions | OpenExternalOptions | OpenExternalUrlOptions | OpenAssistantOptions>;
-export function createClientInteractions(invoke: (operation: string, input: ToastOptions | ConfirmOptions | NavigateOptions | OpenExternalOptions | OpenExternalUrlOptions | OpenAssistantOptions) => Promise<unknown>): {
+export type HostInteraction = {operation:'openArtifact';input:OpenArtifactOptions} | {operation:'preparePdfTemplate';input:import('./documents.js').PreparePdfTemplateInput} | {operation:'openPdfDocument';input:import('./documents.js').OpenPdfDocumentInput} | {operation:'openAssistant';input:OpenAssistantOptions} | {operation:'showToast';input:ToastOptions} | {operation:'confirm';input:ConfirmOptions} | {operation:'navigate';input:NavigateOptions} | {operation:'openExternal';input:OpenExternalOptions} | {operation:'openExternalUrl';input:OpenExternalUrlOptions};
+export function assertHostInteraction(operation: unknown, input: unknown): Readonly<OpenArtifactOptions | ToastOptions | ConfirmOptions | NavigateOptions | OpenExternalOptions | OpenExternalUrlOptions | OpenAssistantOptions>;
+export function createClientInteractions(invoke: (operation: string, input: OpenArtifactOptions | ToastOptions | ConfirmOptions | NavigateOptions | OpenExternalOptions | OpenExternalUrlOptions | OpenAssistantOptions) => Promise<unknown>): {
+  openArtifact(input: OpenArtifactOptions): Promise<void>;
   openAssistant(input: OpenAssistantOptions): Promise<void>;
   showToast(input: ToastOptions): Promise<void>;
   confirm(input: ConfirmOptions): Promise<boolean>;

package/src/client/interactions.js

@@ -12,6 +12,11 @@ const externalUrl = value => {
   } catch { return false; }
 };
 export function assertHostInteraction(operation, input) {
+  if (operation === 'openArtifact') {
+    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).length !== 1
+      || typeof input.artifactId !== 'string' || !/^[A-Za-z0-9]{26}$/.test(input.artifactId)) fail();
+    return Object.freeze({ artifactId: input.artifactId });
+  }
   if (['preparePdfTemplate', 'openPdfDocument'].includes(operation)) return assertDocumentInput(operation, input);
   if (!input || typeof input !== 'object' || Array.isArray(input)) fail();
   const allowed = operation === 'openAssistant' ? ['scenario','context','title'] : operation === 'showToast' ? ['message','tone'] : operation === 'confirm' ? ['title','description','confirmLabel','cancelLabel'] : operation === 'navigate' ? ['destination'] : operation === 'openExternal' ? ['href'] : operation === 'openExternalUrl' ? ['url'] : [];
@@ -36,6 +41,10 @@ export function assertHostInteraction(operation, input) {
 }
 export function createClientInteractions(invoke) {
   return Object.freeze({
+    openArtifact(input) {
+      const request = assertHostInteraction('openArtifact',input);
+      return invoke('openArtifact',request).then(value=>{if(value!==null)fail();});
+    },
     openAssistant(input) {
       const request = assertHostInteraction('openAssistant',input);
       return invoke('openAssistant',request).then(value=>{if(value!==null)fail();});

package/src/toolchain/real-build.js

@@ -392,7 +392,7 @@ function createManifest({ clientBytes, serverBytes, sources }) {
           }
         : {}),
     },
-    frontendExtensions: sources.frontendExtensions.map(({ key, type, entry, label, icon, objects, name, order, variant, showInNavigation, showHeader }) => ({
+    frontendExtensions: sources.frontendExtensions.map(({ key, type, entry, label, icon, objects, name, order, variant, showInNavigation, showHeader, fillHeight }) => ({
       artifact: "client",
       entry,
       key,
@@ -405,6 +405,7 @@ function createManifest({ clientBytes, serverBytes, sources }) {
       ...(variant === undefined ? {} : { variant }),
       ...(showInNavigation === undefined ? {} : { showInNavigation }),
       ...(showHeader === undefined ? {} : { showHeader }),
+      ...(fillHeight === undefined ? {} : { fillHeight }),
     })),
     lifecycleEvents: sources.lifecycleEvents.map(({ event, key }) => ({
       artifact: "server",

package/src/toolchain/source-discovery.js

@@ -308,7 +308,7 @@ function parseWorkspacePage(sourceFile, relativePath, slug) {
   const object = requireObjectLiteral(call.arguments[0], relativePath);
   assertOnlyProperties(
     object,
-    ["name", "icon", "order", "variant", "Page", "showInNavigation", "showHeader"],
+    ["name", "icon", "order", "variant", "Page", "showInNavigation", "showHeader", "fillHeight"],
     relativePath,
     "zhike_page_definition_invalid",
     "Page definition 包含不支持的字段",
@@ -360,6 +360,15 @@ function parseWorkspacePage(sourceFile, relativePath, slug) {
     }
     showHeader = headerProperty.initializer.kind === ts.SyntaxKind.TrueKeyword;
   }
+  const fillHeightProperty = findProperty(object, "fillHeight");
+  let fillHeight;
+  if (fillHeightProperty !== undefined) {
+    if (!ts.isPropertyAssignment(fillHeightProperty)
+      || ![ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(fillHeightProperty.initializer.kind)) {
+      throw toolchainError("zhike_page_fill_height_invalid", `${relativePath}: fillHeight 必须是静态布尔值`);
+    }
+    fillHeight = fillHeightProperty.initializer.kind === ts.SyntaxKind.TrueKeyword;
+  }
   const pageProperty = findProperty(object, "Page");
   if (
     !pageProperty ||
@@ -381,6 +390,7 @@ function parseWorkspacePage(sourceFile, relativePath, slug) {
     ...(order === undefined ? {} : { order }),
     ...(showInNavigation === undefined ? {} : { showInNavigation }),
     ...(showHeader === undefined ? {} : { showHeader }),
+    ...(fillHeight === undefined ? {} : { fillHeight }),
     variant,
   });
 }