@77-zhike/app-sdk 0.2.0-d7b1.8 → 0.2.0-d7b1.9

package/README.md

@@ -1,5 +1,11 @@
 # 智客 App SDK 与 CLI
 
+## 获准依赖
+
+工具链从 `src/toolchain/allowed-packages.json` 读取平台维护的包白名单。目前允许 `@77-zhike/qiqi-openapi@0.1.0` 的服务端包根入口 `.`；前端不可导入。项目安装依赖后直接使用静态 ESM import，真实解析的包名、精确版本、入口及间接模块在打包时核对，代码合并进 Artifact。App 的 Manifest、Settings 或 `package.json` 不能扩展名单。
+
+Node builtin、CommonJS、动态 import、原生模块、未获准包和路径越界仍禁止。项目内 `file:` 包可用，但同名同版本不是来源证明。白名单只控制构建兼容性；不替代运行时沙箱、网络策略、租户隔离及 API 权限，不进行运行时 npm 安装。
+
 ## 统一构建
 
 `zhike dev` 是监听、构建、上传和应用开发安装的快捷工作流，不是另一种运行时。
@@ -133,7 +139,7 @@ import {
 } from '@77-zhike/app-sdk/client'
 import {
   Card,
-  Link,
+  ZhikeLink,
   Stack,
   TextBlock,
 } from '@77-zhike/app-sdk/ui'
@@ -144,9 +150,9 @@ function QueuePage() {
       <Card title="任务队列">
         <TextBlock>当前没有待处理任务。</TextBlock>
       </Card>
-      <Link destination={Destinations.appPage('overview')}>
+      <ZhikeLink destination={Destinations.appPage('overview')}>
         返回总览
-      </Link>
+      </ZhikeLink>
     </Stack>
   )
 }
@@ -161,13 +167,13 @@ export default definePage({
 
 同一 App 内，有 `order` 的 Page 排在前面并按 `order + slug` 稳定排序；未声明 `order` 的 Page 排在后面并按 slug 排序。`name` trim 后长度为 1～80 个 Unicode code points。`variant: 'full' | 'centered'` 只表达布局语义，Desktop 与 H5 分别决定具体页面壳。
 
-Page UI 必须使用 `@77-zhike/app-sdk/ui` 和 `@77-zhike/app-sdk/forms` 的公开组件，不能依赖 DOM、React Router 或自行复制产品控件。当前 Desktop 支持 Components 与 Forms；H5 支持 TextBlock、布局、反馈、Button、Tabs、Table、Card、Grid、EmptyState、Link 等 portable Components，并支持 Forms，暂不支持 `LookupCell`。含有不支持能力的 Page 在 H5 会整体显示“不支持”，不会静默丢节点或部分提交。
+Page UI 必须使用 `@77-zhike/app-sdk/ui` 和 `@77-zhike/app-sdk/forms` 的公开组件，不能依赖 DOM、React Router 或自行复制产品控件。当前 Desktop 支持 Components 与 Forms；H5 支持 TextBlock、布局、反馈、Button、Tabs、Table、Card、Grid、EmptyState、Link、ZhikeLink 等 portable Components，并支持 Forms，暂不支持 `LookupCell`。含有不支持能力的 Page 在 H5 会整体显示“不支持”，不会静默丢节点或部分提交。
 
 导航只提交结构化 Destination：
 
 - `Destinations.appPage(slug)` 打开当前 App 的另一个 Page。
 - `Destinations.record({ object, recordId })` 支持 `accounts`、`contacts`、`opportunities`、`tasks`、`activities` 和当前 Workspace 可见的 `custom_*` 公开 API slug。
-- `Link` 保留普通链接、复制地址和新标签行为；普通点击仍会在跳转前重验当前 Page 身份。
+- `ZhikeLink` 保留普通链接、复制地址和新标签行为；普通点击仍会在跳转前重验当前 Page 身份。外部 HTTPS 使用 `Link`。
 - `navigate()` 当前只允许从已挂载的 Page 调用，三类 Action 都不具备该能力。
 
 目录展示不会启动 Worker。首次打开 Page 时，宿主才会下载并校验 Manifest/Bundle、启动 Installation Worker；因此“Apps 菜单可见”不等于代码已经验证可运行。页面数据读写仍应通过受控 Server Function 完成。
@@ -196,9 +202,9 @@ export default async function readForCurrentMember() {
 
 ## 基础UI组件扩展
 
-新增Avatar、DescriptionList、Divider、Json、ExternalLink、StatusBadge、TextBlock与Typography，补齐Banner动作、Badge颜色、Card呈现、Grid容器模式、EmptyState操作编排和Table.HeaderCell。原flat exports与默认调用保留，复合写法使用同一节点。
+新增Avatar、DescriptionList、Divider、Json、外部Link、StatusBadge、TextBlock与Typography，补齐Banner动作、Badge颜色、Card呈现、Grid容器模式、EmptyState操作编排和Table.HeaderCell。复合写法使用同一节点。
 
-Desktop注册42项，H5注册41项（不含LookupCell），其中包括 `Widget.TextWidget`、`Widget.Title`、`Widget.Text.Primary`、`Widget.Text.Secondary`、`Widget.Loading` 与 `Widget.Decoration` 六个 Widget 语义节点。Link仍仅限Page；H5支持Forms，仍不开放Settings入口。新包要求`remote-react.v3`，发布前必须先部署对应Host及Bundle准入合同。
+Desktop与H5注册的组件合同中，`ZhikeLink` 仍仅限Page，`Link` 是受治理的外部HTTPS链接；H5支持Forms，仍不开放Settings入口。新包要求`remote-react.v3`，发布前必须先部署对应Host及Bundle准入合同。
 
 新增组件的日常验证：修改Core `components/contracts.mjs`后执行`npm run generate:components --workspace @77-zhike/app-sdk`和`npm run check:components --workspace @77-zhike/app-sdk`，同步双端manifest与adapter。App项目运行`zhike dev --workspace <workspace-id>`，从对应Workspace的Apps入口打开Page；Desktop Settings仅验证其允许的子集。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@77-zhike/app-sdk",
-  "version": "0.2.0-d7b1.8",
+  "version": "0.2.0-d7b1.9",
   "description": "智客 Integration App 一期 SDK 与本地 Toolchain",
   "repository": {
     "type": "git",
@@ -59,5 +59,5 @@
       "optional": true
     }
   },
-  "gitHead": "5ebb33176120cba2e1c70440cc56dc041e1cf924"
+  "gitHead": "d820fb6f04634518f062b82cf214d3b08d00c481"
 }

package/src/cli/development-logs.js

@@ -32,9 +32,12 @@ export function formatAppLog(app, entry, {
   const levelLabel = { log: "INFO ", warn: "WARN ", error: "ERROR" }[level];
   const levelColor = { log: colors.cyan, warn: colors.yellow, error: colors.red }[level];
   const timestamp = formatTimestamp(entry.received_at);
+  const version = entry.app_version_id ? safe(entry.app_version_id).replace(/\n/g, " ").slice(0, 64) : "";
+  const request = entry.invocation_id ? safe(entry.invocation_id).replace(/\n/g, " ").slice(0, 64) : "";
+  const identity = version || request ? `  [${[version, request].filter(Boolean).join(" · ")}]` : "";
   const prefix = color
-    ? `${colors.dim}${timestamp}${colors.reset}  ${levelColor}${levelLabel}${colors.reset}  ${colors.bold}${label}${colors.reset}`
-    : `${timestamp}  ${levelLabel}  ${label}`;
+    ? `${colors.dim}${timestamp}${colors.reset}  ${levelColor}${levelLabel}${colors.reset}  ${colors.bold}${label}${colors.reset}${identity}`
+    : `${timestamp}  ${levelLabel}  ${label}${identity}`;
   return safe(entry.message).split("\n").map((line) => `${prefix}  ${line}`).join("\n");
 }
 

package/src/cli/index.js

@@ -2,7 +2,7 @@ import { resolve } from "node:path";
 
 import { loadCliConfig } from "../config.js";
 import { asSafeCliError, ZhikeCliError } from "../errors.js";
-import { buildAppBundle, buildMockArtifact } from "../toolchain/index.js";
+import { buildAppBundle } from "../toolchain/index.js";
 import { authenticateCli, openSystemBrowser } from "./browser-auth.js";
 import { createSystemCredentialStore } from "./credential-store.js";
 import {
@@ -10,7 +10,6 @@ import {
   initializeProject,
   validateAppSlug,
 } from "./project-init.js";
-import { validateBundleUpload } from "./validate-bundle.js";
 import { uploadAppBundle } from "./upload-bundle.js";
 import { watchDevelopmentApp } from "./development-watch.js";
 import { runLocalCommand } from "./local-commands.js";
@@ -60,6 +59,16 @@ export async function runCli(
       );
       return result;
     }
+    if (command === "validate") {
+      _rejectArguments(rest);
+      const result = await buildAppBundle({
+        projectDirectory: cwd,
+      });
+      output.write(
+        `真实 App 源码校验通过：${result.artifacts.length} Artifacts，Bundle ${result.sha256} (${result.size} bytes)；未写入 dist\n`,
+      );
+      return result;
+    }
 
     const onProgress = (message) => output.write(`${message}\n`);
     let remoteContext = null;
@@ -186,26 +195,6 @@ export async function runCli(
       if (result && !ready) await onReady(result);
       return result;
     }
-    if (command === "experimental" && rest[0] === "validate-bundle") {
-      _rejectArguments(rest.slice(1));
-      const { config, store } = getRemoteContext();
-      const authenticatedApi = await authenticate({
-        ...config,
-        credentialStore: store,
-        fetchImpl,
-        openBrowser,
-        onProgress,
-      });
-      const result = await validateBundleUpload({
-        projectDirectory: cwd,
-        apiBaseUrl: config.apiBaseUrl,
-        authenticatedApi,
-      });
-      output.write(
-        `${result.upload.status === "accepted" ? "Bundle 已受理" : "Bundle 校验失败"}：${result.upload.id}\n`,
-      );
-      return result;
-    }
     throw new ZhikeCliError(
       "zhike_command_unknown",
       `未知命令：${command}`,
@@ -260,5 +249,4 @@ export {
   initializeProject,
   scaffoldProject,
 } from "./project-init.js";
-export { validateBundleUpload } from "./validate-bundle.js";
 export { uploadAppBundle } from "./upload-bundle.js";

package/src/cli/local-commands.js

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

package/src/cli/project-init.js

@@ -100,6 +100,7 @@ export async function scaffoldProject({ targetDirectory, binding }) {
 - 开发文档：${docsUrl}
 
 先读取文档索引，再按当前任务读取相关的 App SDK、CLI、扩展、连接和 API 文档；不要仅凭记忆猜测接口、参数或运行时能力。
+每使用一个复合 UI 或 Form 组件，必须打开该组件的专属文档，核对允许的直属子节点、嵌套顺序和入口限制。TypeScript、zhike validate、zhike build 或上传成功，不代表组件树已经符合运行时合同。
 索引中的相对链接以开发文档地址为基准解析。若无法访问文档，请明确说明访问失败，请用户提供相关文档，不要把猜测当作已确认能力。
 项目绑定环境与 App 身份见 .zhike/project.json；切换平台环境后应同步更新上述文档地址。
 `;
@@ -137,10 +138,10 @@ export async function scaffoldProject({ targetDirectory, binding }) {
           type: "module",
           scripts: {
             zhike: "zhike",
+            validate: "zhike validate",
             build: "zhike build",
             dev: "zhike dev",
             upload: "zhike upload",
-            "validate:mock": "zhike experimental validate-bundle",
           },
           devDependencies: {
             "@77-zhike/app-sdk": TOOLING_VERSION,

package/src/server/index.d.ts

@@ -1,4 +1,20 @@
 import type { JsonValue } from "../index.js";
+export { defineWorkflowStep, defineWorkflowStepExecute } from "./steps/index.js";
+export type { WorkflowObjectSchema, WorkflowScalarSchema, WorkflowStepDefinition, WorkflowStepOutcome, WorkflowStepResult, WorkflowSchemaValue } from "./steps/index.js";
+export { defineWorkflowTrigger, defineWorkflowTriggerActivate, defineWorkflowTriggerOnEvent, defineWorkflowTriggerDeactivate } from "./triggers/index.js";
+export type { WorkflowTriggerDefinition, WorkflowTriggerOutcome, WorkflowTriggerEventResult } from "./triggers/index.js";
+export {
+  defineWorkflowBlock,
+  defineWorkflowBlockExecute,
+  defineWorkflowBlockActivate,
+  defineWorkflowBlockTrigger,
+  defineWorkflowBlockDeactivate,
+} from "./workflow-blocks/index.js";
+export type {
+  WorkflowBlockDefinition,
+  WorkflowStepBlockDefinition,
+  WorkflowTriggerBlockDefinition,
+} from "./workflow-blocks/index.js";
 
 /** 当前执行的 App API Token；由可信 Runtime Module 在服务端模块求值前注入。 */
 export const ZHIKE_API_TOKEN: string;
@@ -206,18 +222,37 @@ export interface WorkspaceWebhookBody {
   events: WorkspaceWebhookEvent[];
 }
 
-/** 当前服务端执行可使用的 Workspace 外部系统连接。 */
-export interface WorkspaceConnection {
+interface WorkspaceConnectionBase {
   /** 当前 Workspace Connection 的稳定 ID。 */
   id: string;
   /** 当前 Connect/Reconnect generation 的非敏感稳定表示。 */
   generation: string;
-  /** 当前凭据类型。 */
-  type: "secret" | "oauth2";
-  /** Secret 或当前 OAuth access token，仅存在于本次服务端执行内存。 */
+  /** Secret 或当前 OAuth/OIDC access token，仅存在于本次服务端执行内存。 */
   value: string;
 }
 
+/** 当前服务端执行可使用的 Workspace 外部系统连接。 */
+export type WorkspaceConnection = WorkspaceConnectionBase & (
+  | {
+    type: "secret";
+    protocol: "secret";
+  }
+  | {
+    type: "oauth2";
+    protocol: "oauth2";
+    /** OAuth 2.0 access token；等同 value。 */
+    accessToken: string;
+  }
+  | {
+    type: "oauth2";
+    protocol: "oidc";
+    /** OIDC access token；等同 value。 */
+    accessToken: string;
+    /** OIDC ID token；仅存在于当前服务端执行内存。 */
+    idToken: string;
+  }
+);
+
 /** 同步读取当前执行的连接快照；未连接或暂不可用时抛出安全错误，不在 getter 内刷新。 */
 export function getWorkspaceConnection(): Readonly<WorkspaceConnection>;
 

package/src/server/index.js

@@ -1,4 +1,13 @@
 const SERVER_FUNCTION_MARKER = Symbol.for("zhike.server-function.v1");
+export { defineWorkflowStep, defineWorkflowStepExecute } from "./steps/index.js";
+export { defineWorkflowTrigger, defineWorkflowTriggerActivate, defineWorkflowTriggerOnEvent, defineWorkflowTriggerDeactivate } from "./triggers/index.js";
+export {
+  defineWorkflowBlock,
+  defineWorkflowBlockExecute,
+  defineWorkflowBlockActivate,
+  defineWorkflowBlockTrigger,
+  defineWorkflowBlockDeactivate,
+} from "./workflow-blocks/index.js";
 const LIFECYCLE_EVENT_MARKER = Symbol.for("zhike.lifecycle-event.v1");
 const WEBHOOK_HANDLER_MARKER = Symbol.for("zhike.webhook-handler.v1");
 const WORKSPACE_CONNECTION_EVENTS = new Set([
@@ -145,11 +154,23 @@ export function getWorkspaceConnection() {
     error.code = code;
     throw error;
   }
+  if (connection.protocol === "oidc" && (typeof connection.idToken !== "string" || !connection.idToken)) {
+    const error = new Error("connection_credential_unavailable");
+    error.code = "connection_credential_unavailable";
+    throw error;
+  }
+  const protocol = connection.type === "secret"
+    ? "secret"
+    : (connection.protocol === "oidc" && typeof connection.idToken === "string" && connection.idToken
+      ? "oidc" : "oauth2");
   return Object.freeze({
     id: connection.id,
     generation: connection.generation,
     type: connection.type,
+    protocol,
     value: connection.value,
+    ...(connection.type === "oauth2" ? { accessToken: connection.value } : {}),
+    ...(protocol === "oidc" ? { idToken: connection.idToken } : {}),
   });
 }
 

package/src/server/steps/index.d.ts

@@ -0,0 +1,71 @@
+export type WorkflowScalarSchema =
+  | { readonly type: "string"; readonly minLength?: number; readonly enum?: readonly string[]; readonly title?: string; readonly description?: string; readonly examples?: readonly string[] }
+  | { readonly type: "number"; readonly title?: string; readonly description?: string; readonly examples?: readonly number[] }
+  | { readonly type: "boolean"; readonly title?: string; readonly description?: string; readonly examples?: readonly boolean[] };
+
+export interface WorkflowObjectSchema {
+  readonly type: "object";
+  readonly properties: Readonly<Record<string, WorkflowScalarSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties: false;
+  readonly title?: string;
+  readonly description?: string;
+  readonly examples?: readonly (string | number | boolean)[];
+}
+
+export interface WorkflowStepOutcome {
+  readonly id: string;
+  readonly label: string;
+  readonly dataSchema: WorkflowObjectSchema | null;
+}
+
+export interface WorkflowStepDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[] = readonly WorkflowStepOutcome[],
+> {
+  readonly key: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly connection: "workspace" | "none";
+  readonly configSchema: Config;
+  readonly outcomes: Outcomes;
+}
+
+type ScalarValue<S> = S extends { readonly enum: readonly (infer E)[] } ? E
+  : S extends { readonly type: "string" } ? string
+  : S extends { readonly type: "number" } ? number
+  : S extends { readonly type: "boolean" } ? boolean
+  : never;
+
+type RequiredNames<S extends WorkflowObjectSchema> = S["required"] extends readonly string[]
+  ? S["required"][number] : never;
+
+export type WorkflowSchemaValue<S extends WorkflowObjectSchema> = {
+  [K in keyof S["properties"] as K extends RequiredNames<S> ? K : never]-?: ScalarValue<S["properties"][K]>;
+} & {
+  [K in keyof S["properties"] as K extends RequiredNames<S> ? never : K]?: ScalarValue<S["properties"][K]>;
+};
+
+type OutcomeResult<O extends WorkflowStepOutcome> = O extends WorkflowStepOutcome
+  ? O["dataSchema"] extends WorkflowObjectSchema
+    ? { readonly outcome: O["id"]; readonly data: WorkflowSchemaValue<O["dataSchema"]> }
+    : { readonly outcome: O["id"]; readonly data: null }
+  : never;
+
+export type WorkflowStepResult<Outcomes extends readonly WorkflowStepOutcome[]> =
+  OutcomeResult<Outcomes[number]>;
+
+export function defineWorkflowStep<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowStepOutcome, ...WorkflowStepOutcome[]],
+>(definition: WorkflowStepDefinition<Config, Outcomes>): WorkflowStepDefinition<Config, Outcomes>;
+
+export function defineWorkflowStepExecute<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[],
+>(
+  step: WorkflowStepDefinition<Config, Outcomes>,
+  execute: (params: Readonly<{ config: WorkflowSchemaValue<Config> }>) =>
+    WorkflowStepResult<Outcomes> | Promise<WorkflowStepResult<Outcomes>>,
+): (params: Readonly<{ config: WorkflowSchemaValue<Config> }>) =>
+  WorkflowStepResult<Outcomes> | Promise<WorkflowStepResult<Outcomes>>;

package/src/server/steps/index.js

@@ -0,0 +1,15 @@
+const STEP_MARKER = Symbol.for("zhike.workflow-step.v1");
+
+export function defineWorkflowStep(definition) {
+  if (!definition || typeof definition !== "object") {
+    throw new TypeError("workflow_step_definition_invalid");
+  }
+  return Object.freeze({ ...definition, [STEP_MARKER]: true });
+}
+
+export function defineWorkflowStepExecute(step, execute) {
+  if (!step?.[STEP_MARKER] || typeof execute !== "function") {
+    throw new TypeError("workflow_step_execute_invalid");
+  }
+  return execute;
+}

package/src/server/triggers/index.d.ts

@@ -0,0 +1,68 @@
+import type { WorkflowObjectSchema, WorkflowSchemaValue } from "../steps/index.js";
+
+export interface WorkflowTriggerOutcome {
+  readonly id: string;
+  readonly label: string;
+  readonly dataSchema: WorkflowObjectSchema;
+}
+
+export interface WorkflowTriggerDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[] = readonly WorkflowTriggerOutcome[],
+> {
+  readonly key: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly connection: "workspace" | "none";
+  readonly requestHeaders?: readonly string[];
+  readonly configSchema: Config;
+  readonly outcomes: Outcomes;
+}
+
+type OutcomeResult<O extends WorkflowTriggerOutcome> = O extends WorkflowTriggerOutcome
+  ? {
+      readonly type: "outcome";
+      readonly id: O["id"];
+      readonly eventKey: string;
+      readonly data: WorkflowSchemaValue<O["dataSchema"]>;
+    }
+  : never;
+
+export type WorkflowTriggerEventResult<Outcomes extends readonly WorkflowTriggerOutcome[]> =
+  | { readonly type: "no-op" }
+  | { readonly type: "error"; readonly code: "invalid_signature"; readonly retryable: false }
+  | OutcomeResult<Outcomes[number]>;
+
+export function defineWorkflowTrigger<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowTriggerOutcome, ...WorkflowTriggerOutcome[]],
+>(definition: WorkflowTriggerDefinition<Config, Outcomes>): WorkflowTriggerDefinition<Config, Outcomes>;
+
+export function defineWorkflowTriggerActivate<Config extends WorkflowObjectSchema>(
+  trigger: WorkflowTriggerDefinition<Config>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    activationId: string;
+    triggerCallbackUrl: string;
+  }>) => Promise<Readonly<{ subscriptionRef: string | null }>>,
+): typeof handler;
+
+export function defineWorkflowTriggerOnEvent<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[],
+>(
+  trigger: WorkflowTriggerDefinition<Config, Outcomes>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    body: string;
+    headers: Readonly<Record<string, string>>;
+  }>) => Promise<WorkflowTriggerEventResult<Outcomes>>,
+): typeof handler;
+
+export function defineWorkflowTriggerDeactivate(
+  trigger: WorkflowTriggerDefinition,
+  handler: (params: Readonly<{
+    activationId: string;
+    subscriptionRef: string | null;
+  }>) => Promise<void>,
+): typeof handler;

package/src/server/triggers/index.js

@@ -0,0 +1,27 @@
+const TRIGGER_MARKER = Symbol.for("zhike.workflow-trigger.v1");
+
+export function defineWorkflowTrigger(definition) {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition)) {
+    throw new TypeError("workflow_trigger_definition_invalid");
+  }
+  return Object.freeze({ ...definition, [TRIGGER_MARKER]: true });
+}
+
+function bindTriggerHandler(trigger, handler, kind) {
+  if (!trigger?.[TRIGGER_MARKER] || typeof handler !== "function") {
+    throw new TypeError(`workflow_trigger_${kind}_invalid`);
+  }
+  return handler;
+}
+
+export function defineWorkflowTriggerActivate(trigger, handler) {
+  return bindTriggerHandler(trigger, handler, "activate");
+}
+
+export function defineWorkflowTriggerOnEvent(trigger, handler) {
+  return bindTriggerHandler(trigger, handler, "on_event");
+}
+
+export function defineWorkflowTriggerDeactivate(trigger, handler) {
+  return bindTriggerHandler(trigger, handler, "deactivate");
+}

package/src/server/workflow-blocks/index.d.ts

@@ -0,0 +1,72 @@
+import type {
+  WorkflowObjectSchema,
+  WorkflowSchemaValue,
+  WorkflowStepDefinition,
+  WorkflowStepOutcome,
+  WorkflowStepResult,
+} from "../steps/index.js";
+import type {
+  WorkflowTriggerDefinition,
+  WorkflowTriggerEventResult,
+  WorkflowTriggerOutcome,
+} from "../triggers/index.js";
+
+export type WorkflowStepBlockDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[] = readonly WorkflowStepOutcome[],
+> = WorkflowStepDefinition<Config, Outcomes> & { readonly type: "step" };
+
+export type WorkflowTriggerBlockDefinition<
+  Config extends WorkflowObjectSchema = WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[] = readonly WorkflowTriggerOutcome[],
+> = WorkflowTriggerDefinition<Config, Outcomes> & { readonly type: "trigger" };
+
+export type WorkflowBlockDefinition = WorkflowStepBlockDefinition | WorkflowTriggerBlockDefinition;
+
+export function defineWorkflowBlock<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowStepOutcome, ...WorkflowStepOutcome[]],
+>(definition: WorkflowStepBlockDefinition<Config, Outcomes>): WorkflowStepBlockDefinition<Config, Outcomes>;
+
+export function defineWorkflowBlock<
+  const Config extends WorkflowObjectSchema,
+  const Outcomes extends readonly [WorkflowTriggerOutcome, ...WorkflowTriggerOutcome[]],
+>(definition: WorkflowTriggerBlockDefinition<Config, Outcomes>): WorkflowTriggerBlockDefinition<Config, Outcomes>;
+
+export function defineWorkflowBlockExecute<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowStepOutcome[],
+>(
+  block: WorkflowStepBlockDefinition<Config, Outcomes>,
+  execute: (params: Readonly<{ config: WorkflowSchemaValue<Config> }>) =>
+    WorkflowStepResult<Outcomes> | Promise<WorkflowStepResult<Outcomes>>,
+): typeof execute;
+
+export function defineWorkflowBlockActivate<Config extends WorkflowObjectSchema>(
+  block: WorkflowTriggerBlockDefinition<Config>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    activationId: string;
+    triggerCallbackUrl: string;
+  }>) => Promise<Readonly<{ subscriptionRef: string | null }>>,
+): typeof handler;
+
+export function defineWorkflowBlockTrigger<
+  Config extends WorkflowObjectSchema,
+  Outcomes extends readonly WorkflowTriggerOutcome[],
+>(
+  block: WorkflowTriggerBlockDefinition<Config, Outcomes>,
+  handler: (params: Readonly<{
+    config: WorkflowSchemaValue<Config>;
+    body: string;
+    headers: Readonly<Record<string, string>>;
+  }>) => Promise<WorkflowTriggerEventResult<Outcomes>>,
+): typeof handler;
+
+export function defineWorkflowBlockDeactivate(
+  block: WorkflowTriggerBlockDefinition,
+  handler: (params: Readonly<{
+    activationId: string;
+    subscriptionRef: string | null;
+  }>) => Promise<void>,
+): typeof handler;

package/src/server/workflow-blocks/index.js

@@ -0,0 +1,32 @@
+const WORKFLOW_BLOCK_MARKER = Symbol.for("zhike.workflow-block.v1");
+
+export function defineWorkflowBlock(definition) {
+  if (!definition || typeof definition !== "object" || Array.isArray(definition) ||
+    !["step", "trigger"].includes(definition.type)) {
+    throw new TypeError("workflow_block_definition_invalid");
+  }
+  return Object.freeze({ ...definition, [WORKFLOW_BLOCK_MARKER]: true });
+}
+
+function bindWorkflowBlockHandler(block, handler, type, kind) {
+  if (!block?.[WORKFLOW_BLOCK_MARKER] || block.type !== type || typeof handler !== "function") {
+    throw new TypeError(`workflow_block_${kind}_invalid`);
+  }
+  return handler;
+}
+
+export function defineWorkflowBlockExecute(block, handler) {
+  return bindWorkflowBlockHandler(block, handler, "step", "execute");
+}
+
+export function defineWorkflowBlockActivate(block, handler) {
+  return bindWorkflowBlockHandler(block, handler, "trigger", "activate");
+}
+
+export function defineWorkflowBlockTrigger(block, handler) {
+  return bindWorkflowBlockHandler(block, handler, "trigger", "trigger");
+}
+
+export function defineWorkflowBlockDeactivate(block, handler) {
+  return bindWorkflowBlockHandler(block, handler, "trigger", "deactivate");
+}

package/src/toolchain/allowed-packages.json

@@ -0,0 +1,7 @@
+{
+  "@77-zhike/qiqi-openapi": {
+    "versions": ["0.1.0"],
+    "targets": ["server"],
+    "subpaths": ["."]
+  }
+}