@77-zhike/app-sdk 0.2.0-d7b1.10

package/src/cli/project-init.js

@@ -0,0 +1,259 @@
+import { createHash, randomBytes } from "node:crypto";
+import {
+  access,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { constants } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+
+import { normalizeOrigin, TOOLING_VERSION } from "../config.js";
+import { ZhikeCliError } from "../errors.js";
+import { serializeProjectBinding } from "../project-binding.js";
+
+export async function initializeProject({
+  targetDirectory,
+  appSlug,
+  apiBaseUrl,
+  authenticatedApi,
+  scaffold = scaffoldProject,
+}) {
+  validateAppSlug(appSlug);
+  const target = resolve(targetDirectory);
+  await assertEmptyTarget(target);
+
+  const { app, organization, binding, created } = await resolveAppBinding({ appSlug, apiBaseUrl, authenticatedApi });
+  await scaffold({ targetDirectory: target, binding });
+  return { app, organization, binding, created, targetDirectory: target };
+}
+
+export async function initializeExistingProject({ projectDirectory, appSlug, apiBaseUrl, authenticatedApi }) {
+  validateAppSlug(appSlug);
+  const target = resolve(projectDirectory);
+  await assertExistingProjectTarget(target);
+  const { app, organization, binding, created } = await resolveAppBinding({ appSlug, apiBaseUrl, authenticatedApi });
+  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 };
+}
+
+export async function assertExistingProjectTarget(projectDirectory) {
+  let projectPackage;
+  try {
+    projectPackage = JSON.parse(await readFile(resolve(projectDirectory, "package.json"), "utf8"));
+    const source = await stat(resolve(projectDirectory, "src"));
+    if (!source.isDirectory() || (!projectPackage?.devDependencies?.["@77-zhike/app-sdk"] &&
+        !projectPackage?.dependencies?.["@77-zhike/app-sdk"])) {
+      throw new Error("not an App project");
+    }
+  } catch {
+    throw new ZhikeCliError("zhike_existing_project_invalid", "当前目录不是包含 SDK 和 src 的 App 项目");
+  }
+  try {
+    await stat(resolve(projectDirectory, ".zhike", "project.json"));
+    throw new ZhikeCliError("zhike_project_already_bound", "当前项目已有 App 绑定，不能重复初始化");
+  } catch (error) {
+    if (error instanceof ZhikeCliError) throw error;
+    if (error?.code !== "ENOENT") {
+      throw new ZhikeCliError("zhike_project_binding_check_failed", "无法检查当前项目的 App 绑定", { cause: error });
+    }
+  }
+}
+
+async function resolveAppBinding({ appSlug, apiBaseUrl, authenticatedApi }) {
+  const organizations = await authenticatedApi.listOrganizations();
+  if (!Array.isArray(organizations) || organizations.length !== 1) {
+    throw new ZhikeCliError(
+      "zhike_developer_organization_unavailable",
+      organizations?.length === 0
+        ? "请先在 Developer Console 激活开发者组织"
+        : "当前账号存在多个开发者组织，D2-2 暂不支持隐式选择",
+    );
+  }
+  const organization = organizations[0];
+  let app = await authenticatedApi.getAppBySlug(organization.id, appSlug);
+  let created = false;
+  if (!app) {
+    app = await authenticatedApi.createApp(organization.id, {
+      name: displayNameFromSlug(appSlug),
+      slug: appSlug,
+      idempotencyKey: createInitIdempotencyKey({
+        apiBaseUrl,
+        organizationId: organization.id,
+        appSlug,
+      }),
+    });
+    created = true;
+  }
+  const binding = {
+    schemaVersion: 1,
+    platformEnvironment: apiBaseUrl,
+    appId: app.id,
+    organizationId: organization.id,
+    appSlug: app.slug,
+  };
+  return { app, organization, binding, created };
+}
+
+export async function assertEmptyTarget(targetDirectory) {
+  try {
+    await stat(targetDirectory);
+    throw new ZhikeCliError(
+      "zhike_target_exists",
+      `目标路径已存在：${basename(targetDirectory)}`,
+    );
+  } catch (error) {
+    if (error instanceof ZhikeCliError) {
+      throw error;
+    }
+    if (error?.code !== "ENOENT") {
+      throw new ZhikeCliError(
+        "zhike_target_check_failed",
+        "无法检查项目目标路径",
+        { cause: error },
+      );
+    }
+  }
+  try {
+    await access(dirname(targetDirectory), constants.W_OK);
+  } catch (error) {
+    throw new ZhikeCliError(
+      "zhike_target_parent_not_writable",
+      "项目目标路径的父目录不可写",
+      { cause: error },
+    );
+  }
+}
+
+export async function scaffoldProject({ targetDirectory, binding }) {
+  const docsUrl = `${normalizeOrigin(binding.platformEnvironment, "platformEnvironment")}/docs/`;
+  const agentInstructions = `# 智客 App 开发
+
+开始开发或修改此 App 前，先读取当前平台环境的开发文档：
+
+- 文档索引：${docsUrl}llms.txt
+- 开发文档：${docsUrl}
+
+先读取文档索引，再按当前任务读取相关的 App SDK、CLI、扩展、连接和 API 文档；不要仅凭记忆猜测接口、参数或运行时能力。
+每使用一个复合 UI 或 Form 组件，必须打开该组件的专属文档，核对允许的直属子节点、嵌套顺序和入口限制。TypeScript、zhike validate、zhike build 或上传成功，不代表组件树已经符合运行时合同。
+索引中的相对链接以开发文档地址为基准解析。若无法访问文档，请明确说明访问失败，请用户提供相关文档，不要把猜测当作已确认能力。
+项目绑定环境与 App 身份见 .zhike/project.json；切换平台环境后应同步更新上述文档地址。
+`;
+  const temporaryDirectory = `${targetDirectory}.zhike-tmp-${randomBytes(6).toString("hex")}`;
+  try {
+    await mkdir(resolve(temporaryDirectory, ".zhike"), { recursive: true });
+    await mkdir(
+      resolve(temporaryDirectory, "src", "app", "extensions"),
+      { recursive: true },
+    );
+    await mkdir(resolve(temporaryDirectory, "src", "app", "webhooks"), {
+      recursive: true,
+    });
+    await mkdir(resolve(temporaryDirectory, "src", "app", "events"), {
+      recursive: true,
+    });
+    await mkdir(resolve(temporaryDirectory, "src", "server", "functions"), {
+      recursive: true,
+    });
+    for (const filename of ["AGENTS.md", "CLAUDE.md"]) {
+      await writeFile(resolve(temporaryDirectory, filename), agentInstructions, { flag: "wx" });
+    }
+    await writeFile(
+      resolve(temporaryDirectory, ".zhike", "project.json"),
+      serializeProjectBinding(binding),
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(temporaryDirectory, "package.json"),
+      `${JSON.stringify(
+        {
+          name: binding.appSlug,
+          private: true,
+          version: "0.0.0",
+          type: "module",
+          scripts: {
+            zhike: "zhike",
+            validate: "zhike validate",
+            build: "zhike build",
+            dev: "zhike dev",
+            upload: "zhike upload",
+          },
+          devDependencies: {
+            "@77-zhike/app-sdk": TOOLING_VERSION,
+          },
+        },
+        null,
+        2,
+      )}\n`,
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(temporaryDirectory, "tsconfig.json"),
+      `${JSON.stringify(
+        {
+          compilerOptions: {
+            lib: ["ES2022", "DOM"],
+            jsx: "react-jsx",
+            jsxImportSource: "@77-zhike/app-sdk",
+            module: "ESNext",
+            moduleResolution: "Bundler",
+            noEmit: true,
+            strict: true,
+            target: "ES2022",
+          },
+          include: ["src"],
+        },
+        null,
+        2,
+      )}\n`,
+      { flag: "wx" },
+    );
+    await writeFile(
+      resolve(temporaryDirectory, ".gitignore"),
+      "dist/\n.zhike/development.json\n",
+      { flag: "wx" },
+    );
+    await rename(temporaryDirectory, targetDirectory);
+  } catch (error) {
+    await rm(temporaryDirectory, { recursive: true, force: true });
+    if (error instanceof ZhikeCliError) {
+      throw error;
+    }
+    throw new ZhikeCliError(
+      "zhike_scaffold_failed",
+      "App 已确认，但本地项目生成失败；修复文件系统问题后可安全重试",
+      { cause: error, retryable: true },
+    );
+  }
+}
+
+export function createInitIdempotencyKey({
+  apiBaseUrl,
+  organizationId,
+  appSlug,
+}) {
+  return `init-${createHash("sha256")
+    .update(`${apiBaseUrl}\n${organizationId}\n${appSlug}`, "utf8")
+    .digest("hex")}`;
+}
+
+export function displayNameFromSlug(slug) {
+  return slug
+    .split("-")
+    .map((part) => `${part[0].toUpperCase()}${part.slice(1)}`)
+    .join(" ");
+}
+
+export function validateAppSlug(value) {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value || "") || value.length > 100) {
+    throw new ZhikeCliError(
+      "zhike_app_slug_invalid",
+      "App slug 只能包含小写字母、数字和中划线",
+    );
+  }
+  return value;
+}

package/src/cli/upload-bundle.js

@@ -0,0 +1,73 @@
+import { randomUUID } from "node:crypto";
+
+import { ZhikeCliError } from "../errors.js";
+import { readProjectBinding } from "../project-binding.js";
+import { buildAppBundle } from "../toolchain/real-build.js";
+
+export async function uploadAppBundle({
+  projectDirectory,
+  apiBaseUrl,
+  authenticatedApi,
+  maxAttempts = 2,
+  expectedScopeRevision,
+}) {
+  const bundle = await buildAppBundle({
+    projectDirectory,
+    expectedEnvironment: apiBaseUrl,
+    writeToDist: true,
+    development: true,
+  });
+  const binding = await readProjectBinding(projectDirectory, apiBaseUrl);
+  const idempotencyKey = `bundle-${randomUUID()}`;
+  let attempt = 0;
+  let upload = null;
+  while (attempt < maxAttempts) {
+    attempt += 1;
+    try {
+      upload = await authenticatedApi.uploadBundle(
+        binding.appId,
+        bundle,
+        idempotencyKey,
+      );
+      break;
+    } catch (error) {
+      if (!error?.retryable || attempt >= maxAttempts) throw error;
+    }
+  }
+  if (!upload || upload.status !== "accepted" || !upload.app_bundle_id) {
+    throw new ZhikeCliError(
+      "zhike_bundle_acceptance_invalid",
+      "Developer Server 未返回可激活的 App Bundle",
+    );
+  }
+
+  let developmentManifest = null;
+  let manifestAttempts = 0;
+  while (manifestAttempts < maxAttempts) {
+    manifestAttempts += 1;
+    try {
+      developmentManifest = await authenticatedApi.updateDevelopmentManifest(
+        binding.appId, upload.app_bundle_id, expectedScopeRevision,
+      );
+      break;
+    } catch (error) {
+      if (error?.retryable && manifestAttempts < maxAttempts) continue;
+      const partial = new ZhikeCliError(
+        "zhike_bundle_accepted_manifest_update_failed",
+        `Bundle ${upload.id} 已受理，但当前 Development Manifest 更新失败：${error.message}`,
+        { cause: error, retryable: error.retryable ?? false },
+      );
+      partial.acceptedUploadId = upload.id;
+      partial.acceptedAppBundleId = upload.app_bundle_id;
+      throw partial;
+    }
+  }
+  return {
+    artifact: bundle,
+    binding,
+    upload,
+    developmentManifest,
+    attempts: attempt,
+    manifestAttempts,
+  };
+}

package/src/client/analysis.d.ts

@@ -0,0 +1,4 @@
+import type { JsonValue } from '../ui/index.js';
+export interface AnalysisRequest { operation: 'list' | 'get' | 'execute'; input: { [key: string]: JsonValue } }
+export function assertAnalysisRequest(value: unknown): AnalysisRequest;
+export function createAnalysisClient(invoke: (operation: string, input: AnalysisRequest) => Promise<JsonValue>): (request: AnalysisRequest) => Promise<JsonValue>;

package/src/client/analysis.js

@@ -0,0 +1,12 @@
+import { assertJsonValue } from '../ui/validation.js';
+
+/** 当前成员的受控只读分析；不接受身份、URL 或任意执行代码。 */
+export function assertAnalysisRequest(request) {
+  assertJsonValue(request, { maxBytes: 64 * 1024, maxEntries: 4000 });
+  if (!request || Array.isArray(request) || typeof request !== 'object' || Object.keys(request).some(key => !['operation', 'input'].includes(key))
+      || !['list', 'get', 'execute'].includes(request.operation) || !request.input || Array.isArray(request.input) || typeof request.input !== 'object') throw new Error('runtime_analysis_request_invalid');
+  return request;
+}
+export function createAnalysisClient(invoke) {
+  return request => invoke('analysis', assertAnalysisRequest(request));
+}

package/src/client/destinations.d.ts

@@ -0,0 +1,25 @@
+/** 有界字符串业务参数；不包含宿主身份，不授予记录访问权。 */
+export type PageParams = Readonly<Record<string, string>>;
+
+export interface AppPageDestination {
+  readonly kind: 'app-page';
+  /** 当前 App 内的 Page slug。 */
+  readonly pageSlug: string;
+  readonly params?: PageParams;
+}
+
+export interface RecordDestination {
+  readonly kind: 'record';
+  /** 标准对象复数 slug，或当前 Workspace 可见的 custom_* 公开 API slug。 */
+  readonly object: string;
+  readonly recordId: string;
+}
+
+export type AppDestination = AppPageDestination | RecordDestination;
+
+export function assertAppDestination(value: unknown): Readonly<AppDestination>;
+export function assertPageParams(value: unknown): PageParams;
+export const Destinations: Readonly<{
+  appPage(pageSlug: string, options?: { params?: PageParams }): Readonly<AppPageDestination>;
+  record(input: { object: string; recordId: string }): Readonly<RecordDestination>;
+}>;

package/src/client/destinations.js

@@ -0,0 +1,70 @@
+const PAGE_SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const OBJECT_SLUG = /^[a-z][a-z0-9_]{0,99}$/;
+const STANDARD_RECORD_OBJECTS = new Set([
+  'accounts',
+  'contacts',
+  'opportunities',
+  'tasks',
+  'activities',
+]);
+
+const fail = () => { throw new TypeError('runtime_destination_invalid'); };
+const only = (value, keys) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some(key => !keys.includes(key))) fail();
+};
+
+/** 参数是地址中的不可信业务输入，不承载宿主身份或授权。 */
+export function assertPageParams(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail();
+  const keys = Object.keys(value).sort();
+  if (keys.length > 16) fail();
+  const entries = keys.map(key => {
+    const item = value[key];
+    if (!/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key)
+      || ['__proto__', 'prototype', 'constructor'].includes(key)
+      || typeof item !== 'string' || [...item].length > 512
+      || /[\p{Cc}\p{Cs}]/u.test(item)) fail();
+    return [key, item];
+  });
+  const params = Object.fromEntries(entries);
+  if (new TextEncoder().encode(JSON.stringify(params)).byteLength > 2048) fail();
+  return Object.freeze(params);
+}
+
+export function assertAppDestination(value) {
+  only(value, value?.kind === 'app-page' ? ['kind', 'pageSlug', 'params'] : value?.kind === 'record'
+    ? ['kind', 'object', 'recordId'] : []);
+  if (value.kind === 'app-page') {
+    if (typeof value.pageSlug !== 'string' || value.pageSlug.length > 64 || !PAGE_SLUG.test(value.pageSlug)) fail();
+    const params = value.params === undefined ? undefined : assertPageParams(value.params);
+    return Object.freeze({ kind: 'app-page', pageSlug: value.pageSlug,
+      ...(params && Object.keys(params).length ? { params } : {}),
+    });
+  }
+  if (value.kind === 'record') {
+    const custom = typeof value.object === 'string' && value.object.startsWith('custom_');
+    if (
+      typeof value.object !== 'string'
+      || !OBJECT_SLUG.test(value.object)
+      || (!STANDARD_RECORD_OBJECTS.has(value.object) && !custom)
+      || typeof value.recordId !== 'string'
+      || value.recordId.length < 1
+      || value.recordId.length > 160
+    ) fail();
+    return Object.freeze({ kind: 'record', object: value.object, recordId: value.recordId });
+  }
+  fail();
+}
+
+export const Destinations = Object.freeze({
+  appPage(pageSlug, options) {
+    if (options !== undefined) only(options, ['params']);
+    return assertAppDestination({ kind: 'app-page', pageSlug, ...(options?.params === undefined ? {} : { params: options.params }) });
+  },
+  record(input) {
+    only(input, ['object', 'recordId']);
+    return assertAppDestination({ kind: 'record', object: input.object, recordId: input.recordId });
+  },
+});

package/src/client/external-url.js

@@ -0,0 +1,9 @@
+/** SDK 与 Host 重复验证同一有界 HTTPS 合同，不接受浏览器自动纠正的危险写法。 */
+export function assertExternalUrl(value) {
+  if (typeof value !== 'string' || !value.length || value.length > 2048 || value !== value.trim()
+    || /[\p{Cc}\\]/u.test(value) || !/^https:\/\//i.test(value)) throw new Error('runtime_external_url_invalid');
+  let url;
+  try { url = new URL(value); } catch { throw new Error('runtime_external_url_invalid'); }
+  if (url.protocol !== 'https:' || !url.hostname || url.username || url.password) throw new Error('runtime_external_url_invalid');
+  return url.href;
+}