@77-zhike/app-sdk 0.2.0-d7b1.7 → 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,7 +1,12 @@
 {
   "name": "@77-zhike/app-sdk",
-  "version": "0.2.0-d7b1.7",
-  "description": "\u667a\u5ba2 Integration App \u4e00\u671f SDK \u4e0e\u672c\u5730 Toolchain",
+  "version": "0.2.0-d7b1.9",
+  "description": "智客 Integration App 一期 SDK 与本地 Toolchain",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tonyjiang88215/TruthLoop.git",
+    "directory": "developer-tools/packages/app-sdk"
+  },
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -53,5 +58,6 @@
     "react": {
       "optional": true
     }
-  }
+  },
+  "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/forms/array-contract.d.ts

@@ -0,0 +1,32 @@
+export const ARRAY_LIMITS: Readonly<{ arrays: number; rowFields: number; rows: number; instances: number; valueBytes: number; messageBytes: number }>;
+export function validFieldKey(key: unknown): boolean;
+export function formBytes(value: unknown): number;
+export function formObject(value: unknown, keys: string[]): void;
+export interface FieldAddress { field: string; array?: string; index?: number }
+export interface ArrayBinding { name: string; rowKey: string; formInstanceId: string; structureRevision: number }
+export type ArrayAction = { kind: 'append'; value: Record<string, unknown> } | { kind: 'insertBefore'; beforeKey: string; value: Record<string, unknown> } | { kind: 'remove'; rowKey: string } | { kind: 'move'; rowKey: string; before: string | null };
+export interface ArrayOperation { formId: string; formInstanceId: string; arrayName: string; baseStructureRevision: number; action: ArrayAction }
+export interface ArraySnapshot {
+  formId: string; name: string; formInstanceId: string; revision: number; structureRevision: number;
+  rows: { key: string; index: number; value: Record<string, unknown>; errors: Record<string, string>; validatingFields: Record<string, boolean> }[];
+  submitting: boolean; canAppend: boolean; error: string | null;
+}
+export type ErrorTree<T = string> = Record<string, T | (Record<string, T> | null)[]>;
+export function parseFieldPath(path: string): FieldAddress;
+export function fieldAtPath<F>(fields: Record<string, F>, path: string): F;
+export function valueAtPath(values: Record<string, unknown>, path: string): unknown;
+export function setPathValue(values: Record<string, unknown>, path: string, value: unknown): void;
+export function rulePath(path: string): string;
+export function leafPaths(fields: Record<string, unknown>, values: Record<string, unknown>): string[];
+export function rhfPath(path: string): string;
+export function publicPath(path: string): string;
+export function assertFieldValue(value: unknown, field: unknown, draft?: boolean): void;
+export function assertArrayCapacity(fields: Record<string, unknown>, values: Record<string, unknown>, draft?: boolean): void;
+export function normalizeFormValues<T extends Record<string, unknown>>(fields: Record<string, unknown>, raw: T): T;
+export function assertErrorTree(tree: unknown, fields: Record<string, unknown>, values?: Record<string, unknown>, boolean?: boolean, maxText?: number): void;
+export function assertArrayErrors(errors: unknown, fields: Record<string, unknown>, maxText?: number): void;
+export function flattenErrors<T = string>(tree?: ErrorTree<T>): Record<string, T>;
+export function nestErrors<T = string>(flat: Record<string, T>): ErrorTree<T>;
+export function assertArrayBinding(binding: unknown): ArrayBinding;
+export function assertArrayOperation(input: unknown): ArrayOperation;
+export function assertArraySnapshot(snapshot: unknown, formId: string, name: string, fields: Record<string, unknown>): ArraySnapshot;

package/src/forms/array-contract.js

@@ -0,0 +1,138 @@
+import { assertJsonValue } from '../ui/validation.js';
+import { isDateTime, isPlainDate, parseNumberDraft } from './values.js';
+import { assertRecordRef, recordObjectsForField } from './record-options.js';
+
+export const ARRAY_LIMITS = Object.freeze({ arrays: 3, rowFields: 12, rows: 50, instances: 300, valueBytes: 65536, messageBytes: 196608 });
+const fail = () => { throw new Error('runtime_form_array_invalid'); };
+export const validFieldKey = key => typeof key === 'string' && /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(key) && !['constructor', 'prototype'].includes(key);
+export const formBytes = value => new TextEncoder().encode(JSON.stringify(value)).length;
+export function formObject(value, keys) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) fail();
+}
+export function parseFieldPath(path) {
+  if (validFieldKey(path)) return { field: path };
+  const match = typeof path === 'string' && /^([a-zA-Z][a-zA-Z0-9_]{0,63})\[(0|[1-9][0-9]*)\]\.([a-zA-Z][a-zA-Z0-9_]{0,63})$/.exec(path);
+  if (!match || !validFieldKey(match[1]) || !validFieldKey(match[3]) || !Number.isSafeInteger(Number(match[2])) || Number(match[2]) >= ARRAY_LIMITS.rows) fail();
+  return { array: match[1], index: Number(match[2]), field: match[3] };
+}
+export function fieldAtPath(fields, path) {
+  const address = parseFieldPath(path);
+  const field = address.array ? fields[address.array]?.item?.fields[address.field] : fields[address.field];
+  if (!field || address.array && fields[address.array].type !== 'array') fail();
+  return field;
+}
+export function valueAtPath(values, path) {
+  const address = parseFieldPath(path);
+  return address.array ? values[address.array]?.[address.index]?.[address.field] : values[address.field];
+}
+export function setPathValue(values, path, value) {
+  const address = parseFieldPath(path);
+  if (address.array) values[address.array][address.index][address.field] = value;
+  else values[address.field] = value;
+}
+export function rulePath(path) {
+  const address = parseFieldPath(path);
+  return address.array ? `${address.array}[*].${address.field}` : address.field;
+}
+export function leafPaths(fields, values) {
+  return Object.entries(fields).flatMap(([name, field]) => field.type === 'array'
+    ? (values[name] ?? []).flatMap((_row, index) => Object.keys(field.item.fields).map(key => `${name}[${index}].${key}`)) : [name]);
+}
+export const rhfPath = path => path.replace(/\[(\d+)\]/g, '.$1');
+export const publicPath = path => path.replace(/\.(\d+)\./g, '[$1].');
+export function assertFieldValue(value, field, draft = false) {
+  if (field.type === 'array') {
+    if (!Array.isArray(value) || value.length > field.maxItems || Object.keys(value).length !== value.length) fail();
+    for (const row of value) {
+      formObject(row, Object.keys(field.item.fields));
+      if (Object.keys(row).length !== Object.keys(field.item.fields).length) fail();
+      for (const [key, leaf] of Object.entries(field.item.fields)) assertFieldValue(row[key], leaf, draft);
+    }
+  } else if (field.type === 'boolean') { if (typeof value !== 'boolean') fail(); }
+  else if (field.type === 'number') { if (value !== null && !(draft && typeof value === 'string') && (typeof value !== 'number' || !Number.isFinite(value))) fail(); }
+  else if (field.type === 'record') { if (value !== null) assertRecordRef(value, recordObjectsForField(field)); }
+  else if (field.type === 'plainDate' || field.type === 'dateTime') { if (value !== null && !(draft && typeof value === 'string') && !(field.type === 'plainDate' ? isPlainDate(value) : isDateTime(value))) fail(); }
+  else if (typeof value !== 'string' || value.length > 10000) fail();
+}
+export function assertArrayCapacity(fields, values, draft = false) {
+  if (!Object.values(fields).some(field => field.type === 'array')) return;
+  formObject(values, Object.keys(fields));
+  if (Object.keys(fields).length !== Object.keys(values).length) fail();
+  for (const [name, field] of Object.entries(fields)) assertFieldValue(values[name], field, draft);
+  if (leafPaths(fields, values).length > ARRAY_LIMITS.instances || formBytes(values) > ARRAY_LIMITS.valueBytes) throw new Error('runtime_form_limit_exceeded');
+}
+export function normalizeFormValues(fields, raw) {
+  return Object.fromEntries(Object.entries(fields).map(([name, field]) => {
+    const value = raw[name];
+    return [name, field.type === 'array' ? value.map(row => normalizeFormValues(field.item.fields, row))
+      : field.type === 'number' ? parseNumberDraft(value).value
+      : field.type === 'dateTime' ? isDateTime(value) ? new Date(value).toISOString() : null
+      : field.type === 'plainDate' ? isPlainDate(value) ? value : null : structuredClone(value)];
+  }));
+}
+/** errors / validatingFields 的索引只对应这次快照；无错误行必须是显式 null。 */
+export function assertErrorTree(tree, fields, values, boolean = false, maxText = 4096) {
+  formObject(tree, Object.keys(fields));
+  for (const [name, error] of Object.entries(tree)) {
+    const field = fields[name];
+    if (field.type === 'array') {
+      if (!Array.isArray(error) || error.length > (values?.[name]?.length ?? field.maxItems) || Object.keys(error).length !== error.length) fail();
+      for (const row of error) if (row !== null) assertErrorTree(row, field.item.fields, undefined, boolean, maxText);
+    } else if (boolean ? typeof error !== 'boolean' : typeof error !== 'string' || !error.trim() || error.length > maxText) fail();
+  }
+}
+export function assertArrayErrors(errors, fields, maxText = 4096) {
+  formObject(errors, Object.keys(fields).filter(name => fields[name].type === 'array'));
+  if (Object.values(errors).some(value => typeof value !== 'string' || !value.trim() || value.length > maxText)) fail();
+}
+export function flattenErrors(tree = {}) {
+  return Object.fromEntries(Object.entries(tree).flatMap(([name, value]) => Array.isArray(value)
+    ? value.flatMap((row, index) => Object.entries(row ?? {}).map(([key, error]) => [`${name}[${index}].${key}`, error])) : [[name, value]]));
+}
+export function nestErrors(flat) {
+  const tree = {};
+  for (const [path, error] of Object.entries(flat)) {
+    const address = parseFieldPath(path);
+    if (!address.array) tree[path] = error;
+    else {
+      const rows = tree[address.array] ??= [];
+      while (rows.length <= address.index) rows.push(null);
+      (rows[address.index] ??= {})[address.field] = error;
+    }
+  }
+  return tree;
+}
+export function assertArrayBinding(binding) {
+  formObject(binding, ['name', 'rowKey', 'formInstanceId', 'structureRevision']);
+  if (!validFieldKey(binding.name) || !opaque(binding.rowKey) || !opaque(binding.formInstanceId) || !revision(binding.structureRevision)) fail();
+  return binding;
+}
+const opaque = value => typeof value === 'string' && value.length > 0 && value.length <= 200;
+const revision = value => Number.isSafeInteger(value) && value >= 0;
+export function assertArrayOperation(input) {
+  formObject(input, ['formId', 'formInstanceId', 'arrayName', 'baseStructureRevision', 'action']);
+  if (!opaque(input.formId) || !opaque(input.formInstanceId) || !validFieldKey(input.arrayName) || !revision(input.baseStructureRevision)) fail();
+  const action = input.action;
+  const keys = { append: ['kind', 'value'], insertBefore: ['kind', 'beforeKey', 'value'], remove: ['kind', 'rowKey'], move: ['kind', 'rowKey', 'before'] }[action?.kind];
+  if (!keys) fail();
+  formObject(action, keys);
+  if (Object.keys(action).length !== keys.length || keys.includes('rowKey') && !opaque(action.rowKey) || keys.includes('beforeKey') && !opaque(action.beforeKey) || keys.includes('before') && action.before !== null && !opaque(action.before)) fail();
+  return input;
+}
+export function assertArraySnapshot(snapshot, formId, name, fields) {
+  assertJsonValue(snapshot, { maxBytes: ARRAY_LIMITS.messageBytes, maxEntries: 4096 });
+  formObject(snapshot, ['formId', 'name', 'formInstanceId', 'revision', 'structureRevision', 'rows', 'submitting', 'canAppend', 'error']);
+  const field = fields[name];
+  if (snapshot.formId !== formId || snapshot.name !== name || !opaque(snapshot.formInstanceId) || !revision(snapshot.revision) || !revision(snapshot.structureRevision) || field?.type !== 'array' || !Array.isArray(snapshot.rows) || snapshot.rows.length > field.maxItems || typeof snapshot.submitting !== 'boolean' || typeof snapshot.canAppend !== 'boolean') fail();
+  const keys = new Set();
+  for (const [index, row] of snapshot.rows.entries()) {
+    formObject(row, ['key', 'index', 'value', 'errors', 'validatingFields']);
+    if (!opaque(row.key) || keys.has(row.key) || row.index !== index) fail();
+    keys.add(row.key);
+    assertFieldValue([row.value], { ...field, maxItems: 1 });
+    assertErrorTree(row.errors, field.item.fields);
+    assertErrorTree(row.validatingFields, field.item.fields, undefined, true);
+  }
+  if (snapshot.error !== null && (typeof snapshot.error !== 'string' || !snapshot.error || snapshot.error.length > 4096) || formBytes(snapshot) > ARRAY_LIMITS.messageBytes) fail();
+  return snapshot;
+}

package/src/forms/factory.js

@@ -1,29 +1,34 @@
+import { createFieldArrays } from './field-array.js';
 import { compileForm } from './schema.js';
 import { createWithState } from './state.js';
 import { useNormalizedRecordOptions, recordObjectsForField } from './record-options.js';
 import { boundComponents, formComponent } from './components.generated.js';
 import { useNormalizedOptions } from './normalize-options.js';
-export function createFormHook(React, { useBindCallback = () => callback => callback } = {}) {
+export function createFormHook(React, { useBindCallback = () => callback => callback, useInvoke = () => () => Promise.reject(new Error('runtime_host_interaction_unavailable')) } = {}) {
 const { createElement, useId, useMemo, useRef } = React;
 
 return function useForm(options) {
   const formId = useId();
   const bindCallback = useBindCallback();
+  const invoke = useInvoke();
   const initial = useRef(options);
   return useMemo(() => {
     const { initialValues } = initial.current;
     const { schema, ...validation } = compileForm(initial.current, formId, bindCallback);
+    const arrays = createFieldArrays(React, formId, schema, invoke);
     const field = type => function Field({ children, ...props }) {
+      const binding = arrays.useBinding(props.name);
       if (type === 'Combobox' || type === 'RecordCombobox') {
         const { options, ...rest } = props;
         const normalized = type === 'RecordCombobox'
-          ? useNormalizedRecordOptions({ useRef, useMemo }, options, recordObjectsForField(schema.fields[props.name]))
+          ? useNormalizedRecordOptions({ useRef, useMemo }, options, recordObjectsForField(binding.arrayBinding ? schema.fields[binding.arrayBinding.name].item.fields[binding.name] : schema.fields[props.name]))
           : useNormalizedOptions({ useRef, useMemo }, options);
-        return createElement(type, { ...rest, ...normalized, formId });
+        return createElement(type, { ...rest, ...normalized, ...binding, formId });
       }
-      return createElement(type, { ...props, formId }, children);
+      return createElement(type, { ...props, ...binding, formId }, children);
     };
     return Object.freeze({
+      FieldArray: arrays.FieldArray,
       WithState: createWithState(React, formId, schema, initialValues),
       Form: function Form({ children, onSubmit }) {
         return createElement(formComponent, { formId, schema, initialValues, onSubmit, ...validation }, children);

package/src/forms/field-array.d.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+import type { ArrayName, FormSchema, FormValues } from './schema.js';
+type ReadonlyValue<T> = T extends object ? { readonly [K in keyof T]: ReadonlyValue<T[K]> } : T;
+export type ArrayOperationResult = { ok: true; rowKey?: string } | { ok: false; code: string; message: string };
+type Row<S extends FormSchema, N extends ArrayName<S>> = FormValues<S>[N] extends (infer R)[] ? R : never;
+export interface FieldArrayHandle<R> {
+  readonly ready: boolean;
+  readonly rows: readonly { readonly key: string; readonly index: number; readonly value: ReadonlyValue<R>; readonly errors: Readonly<Partial<Record<keyof R, string>>>; readonly validatingFields: Readonly<Partial<Record<keyof R, boolean>>> }[];
+  readonly pending: boolean; readonly submitting: boolean; readonly canAppend: boolean;
+  readonly error: string | null; readonly operationError: string | null;
+  append(value: R): Promise<ArrayOperationResult>;
+  insertBefore(beforeKey: string, value: R): Promise<ArrayOperationResult>;
+  remove(rowKey: string): Promise<ArrayOperationResult>;
+  move(rowKey: string, position: { before: string | null }): Promise<ArrayOperationResult>;
+}
+export type FieldArrayComponent<S extends FormSchema> = <N extends ArrayName<S>>(props: { name: N; children: (array: FieldArrayHandle<Row<S, N>>) => ReactNode }) => ReactNode;

package/src/forms/field-array.js

@@ -0,0 +1,52 @@
+import { assertArraySnapshot, parseFieldPath } from './array-contract.js';
+import { freezeFormState } from './state.js';
+
+export function createFieldArrays(React, formId, schema, invoke) {
+  const { createContext, createElement, Fragment, useContext, useEffect, useRef, useState, useMemo } = React;
+  const Context = createContext(null);
+  // 只串行化结构操作；行值仍由 Host 持有，不能乐观修改第二份草稿。
+  const gate = { pending: false };
+  function Observer({ name, children }) {
+    if (schema.fields[name]?.type !== 'array' || typeof children !== 'function') throw new Error('runtime_form_array_invalid');
+    const latest = useRef(null), alive = useRef(true);
+    const [snapshot, setSnapshot] = useState(null), [pending, setPending] = useState(false), [operationError, setError] = useState(null);
+    useEffect(() => { alive.current = true; return () => { alive.current = false; }; }, []);
+    const onState = useMemo(() => next => {
+      assertArraySnapshot(next, formId, name, schema.fields);
+      if (!alive.current || latest.current && latest.current.formInstanceId === next.formInstanceId && latest.current.revision >= next.revision) return;
+      latest.current = freezeFormState(next); setSnapshot(latest.current);
+    }, [name]);
+    async function operate(action) {
+      const state = latest.current;
+      const reject = (code, message) => { if (alive.current) setError(message); return { ok: false, code, message }; };
+      if (!alive.current || !state) return reject('owner_closed', '表单尚未就绪');
+      if (gate.pending || state.submitting) return reject('busy', '请等待当前操作完成');
+      gate.pending = true; setPending(true); setError(null);
+      try {
+        const result = await invoke('formArray', { formId, formInstanceId: state.formInstanceId, arrayName: name, baseStructureRevision: state.structureRevision, action });
+        if (result?.snapshot) onState(result.snapshot);
+        if (!result || typeof result.ok !== 'boolean') throw new Error('runtime_form_array_invalid');
+        if (!result.ok) return reject(result.code, result.message);
+        return { ok: true, ...(result.rowKey ? { rowKey: result.rowKey } : {}) };
+      } catch { return reject('owner_closed', '操作未确认，请检查当前明细后再操作'); }
+      finally { gate.pending = false; if (alive.current) setPending(false); }
+    }
+    const handle = Object.freeze({ ready: Boolean(snapshot), rows: snapshot?.rows ?? [], pending, submitting: snapshot?.submitting ?? false,
+      canAppend: Boolean(snapshot?.canAppend && !pending), error: snapshot?.error ?? null, operationError,
+      append: value => operate({ kind: 'append', value }), insertBefore: (beforeKey, value) => operate({ kind: 'insertBefore', beforeKey, value }),
+      remove: rowKey => operate({ kind: 'remove', rowKey }), move: (rowKey, { before }) => operate({ kind: 'move', rowKey, before }),
+    });
+    return createElement(Fragment, null, createElement('FormArrayObserver', { formId, name, onState }),
+      createElement(Context.Provider, { value: snapshot }, children(handle)));
+  }
+  function useBinding(name) {
+    const snapshot = useContext(Context);
+    if (name === undefined) return {};
+    const path = parseFieldPath(name);
+    if (!path.array) return { name };
+    if (!snapshot || snapshot.name !== path.array || !snapshot.rows[path.index] || !schema.fields[path.array].item.fields[path.field]) throw new Error('runtime_form_array_binding_missing');
+    return { name: path.field, arrayBinding: { name: path.array, rowKey: snapshot.rows[path.index].key, formInstanceId: snapshot.formInstanceId, structureRevision: snapshot.structureRevision } };
+  }
+  function FieldArray(props) { return createElement(Observer, { ...props, key: props.name }); }
+  return { FieldArray, useBinding };
+}

package/src/forms/index.d.ts

@@ -3,14 +3,17 @@ import type { ComponentType, ReactNode } from "react";
 import type { FormSchema, FormValues, FieldName, FormSubmitResult, FormOptions } from "./schema.js";
 import type { Option, OptionsPage, OptionsProvider } from "./options.js";
 import type { RecordOptionsProvider } from "./record-options.js";
+import type { FieldArrayComponent } from "./field-array.js";
+export type { FieldArrayHandle, ArrayOperationResult } from "./field-array.js";
 import type { WithStateComponent } from "./state.js";
 export type { FormStateSelection, SelectedFormState } from "./state.js";
 export type { RecordRef, RecordObjectOption, RecordOption, RecordOptionsPage, RecordOptionsProvider } from "./record-options.js";
 export type { Option, OptionsPage, OptionsProvider } from "./options.js";
 export { Forms } from "./schema.js";
-export type { FormField, FormSchema, FormValues, FieldName, FormSubmitResult, FormOptions, FormValidationResult } from "./schema.js";
+export type { FormField, FormSchema, FormValues, FieldName, FormSubmitResult, FormOptions, FormValidationResult, FormFieldErrors, FormArrayErrors, ArrayName } from "./schema.js";
 export interface FormHandle<S extends FormSchema> {
   WithState: WithStateComponent<S>;
+  FieldArray: FieldArrayComponent<S>;
   Form: ComponentType<{
   children?: ReactNode;
   onSubmit: (values: FormValues<S>) => FormSubmitResult<S> | Promise<FormSubmitResult<S>>;
@@ -69,6 +72,7 @@ export interface FormHandle<S extends FormSchema> {
   description?: string;
   placeholder?: string;
   disabled?: boolean;
+  step?: number;
   }>;
   PlainDateInput: ComponentType<{
   name: FieldName<S, "plainDate">;

package/src/forms/schema.d.ts

@@ -7,26 +7,44 @@ export type FormField = (
   | { type: "number"; label: string; required?: boolean; min?: number; max?: number }
   | { type: "plainDate" | "dateTime"; label: string; required?: boolean; min?: string; max?: string }
   | ({ type: "record"; label: string; required?: boolean } & ({ objectSlug: string; objects?: never } | { objectSlug?: never; objects: readonly [RecordObjectOption] }))) & { messages?: RuleMessages };
-export interface FormSchema { fields: Readonly<Record<string, FormField | { type: FormField['type']; label: (text: string) => unknown }>>; }
-export type FormValues<S extends FormSchema> = {
-  [K in keyof S["fields"]]: S["fields"][K] extends { type: "boolean" } ? boolean
-    : S["fields"][K] extends { type: "record" } ? (S["fields"][K] extends { objectSlug: infer O extends string } ? RecordRef & { objectSlug: O } : RecordRef) | null
-    : S["fields"][K] extends { type: "number" } ? number | null
-    : S["fields"][K] extends { type: "plainDate" | "dateTime" } ? string | null : string;
+export type LeafDefinition = FormField | { type: FormField['type']; label: (text: string) => unknown };
+export interface ArrayField<F extends Record<string, LeafDefinition> = Record<string, LeafDefinition>> {
+  type: 'array'; label: string; minItems: number; maxItems: number; item: { type: 'object'; fields: F };
+  messages?: { min?: string; max?: string };
+}
+export type ArrayBuilder<F extends Record<string, LeafDefinition>> = Omit<ArrayField<F>, 'label'> & {
+  label(text: string): ArrayBuilder<F>;
+  min(count: number, options?: MessageOption): ArrayBuilder<F>;
+  max(count: number, options?: MessageOption): ArrayBuilder<F>;
+  custom(validator: (rows: ReadonlyValue<RowValues<F>[]>) => void | string | Promise<void | string>): ArrayBuilder<F>;
 };
+export interface FormSchema { fields: Readonly<Record<string, LeafDefinition | ArrayField | ArrayBuilder<Record<string, LeafDefinition>>>>; }
+export type ValueOf<F> = F extends { type: 'array'; item: { fields: infer R extends Record<string, LeafDefinition> } } ? RowValues<R>[]
+  : F extends { type: 'boolean' } ? boolean : F extends { type: 'record' } ? (F extends { objectSlug: infer O extends string } ? RecordRef & { objectSlug: O } : RecordRef) | null
+  : F extends { type: 'number' } ? number | null : F extends { type: 'plainDate' | 'dateTime' } ? string | null : string;
+export type RowValues<F extends Record<string, LeafDefinition>> = { [K in keyof F]: ValueOf<F[K]> };
+export type FormValues<S extends FormSchema> = { [K in keyof S['fields']]: ValueOf<S['fields'][K]> };
+export type ArrayName<S extends FormSchema> = { [K in keyof S['fields']]: S['fields'][K]['type'] extends 'array' ? K : never }[keyof S['fields']] & string;
 export type FieldName<S extends FormSchema, T extends FormField['type']> = {
-  [K in keyof S['fields']]: S['fields'][K]['type'] extends T ? K : never;
-}[keyof S['fields']] & string;
+  [K in keyof S['fields'] & string]: S['fields'][K] extends { type: 'array'; item: { fields: infer F extends Record<string, LeafDefinition> } }
+    ? `${K}[${number}].${{ [P in keyof F & string]: F[P]['type'] extends T ? P : never }[keyof F & string]}`
+    : S['fields'][K]['type'] extends T ? K : never;
+}[keyof S['fields'] & string];
+export type FormFieldErrors<S extends FormSchema, E = string> = { [K in keyof S['fields']]?: S['fields'][K] extends { type: 'array'; item: { fields: infer F } }
+  ? (Partial<Record<keyof F, E>> | null)[] : E };
+export type FormArrayErrors<S extends FormSchema> = Partial<Record<ArrayName<S>, string>>;
 /** void 兼容既有提交；失败保留输入，字段名必须属于当前表单。 */
 export type FormSubmitResult<S extends FormSchema> = void | { ok: true } | {
   ok: false;
   code: string;
   message: string;
-  fieldErrors?: Partial<Record<Extract<keyof S['fields'], string>, string>>;
+  fieldErrors?: FormFieldErrors<S>;
+  arrayErrors?: FormArrayErrors<S>;
 };
 
 export type FormValidationResult<S extends FormSchema> = void | {
-  fieldErrors?: Partial<Record<Extract<keyof S['fields'], string>, string>>;
+  fieldErrors?: FormFieldErrors<S>;
+  arrayErrors?: FormArrayErrors<S>;
   formError?: string;
 };
 type FieldValue<F extends FormField> = FormValues<{ fields: { value: F } }>['value'];
@@ -52,7 +70,8 @@ export type FieldBuilder<F extends FormField> = Omit<F, 'label'> & {
 } : {});
 // builder 的 label 是方法，wire 的 label 是字符串；只有编译后才跨 Worker 边界。
 export const Forms: {
-  schema<const F extends Record<string, { type: FormField['type']; label: (text: string) => unknown }>>(fields: F): { readonly fields: F };
+  schema<const F extends Record<string, LeafDefinition | ArrayBuilder<Record<string, LeafDefinition>>>>(fields: F): { readonly fields: F };
+  array<const F extends Record<string, LeafDefinition>>(fields: F): ArrayBuilder<F>;
   string(): FieldBuilder<Extract<FormField, { type: 'string' }>>;
   number(): FieldBuilder<Extract<FormField, { type: 'number' }>>;
   boolean(): FieldBuilder<Extract<FormField, { type: 'boolean' }>>;