apaas-oapi-client 0.1.39 → 0.1.40

package/README.md

@@ -51,7 +51,25 @@ mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
 cp -R skills/apaas-* "${CODEX_HOME:-$HOME/.codex}/skills/"
 ```
 
-通过 npx 从 npm 直接安装：
+通过官方 Skills CLI 从 GitHub 安装：
+
+```bash
+npx skills add https://github.com/ennann/apaas-oapi-node-client --skill apaas-object
+```
+
+安装全部 aPaaS Skills：
+
+```bash
+npx skills add https://github.com/ennann/apaas-oapi-node-client --skill '*'
+```
+
+查看仓库内可用 Skills：
+
+```bash
+npx skills add https://github.com/ennann/apaas-oapi-node-client --list
+```
+
+通过本包内置安装器从 npm 安装：
 
 ```bash
 npx apaas-oapi-client install-skills

package/dist/field-schema-rules.d.ts

@@ -18,6 +18,32 @@ export interface FieldCreateRule {
 }
 export declare const SCHEMA_TYPE_BY_METADATA_TYPE: Record<MetadataFieldType, SchemaFieldType>;
 export declare const OPTION_COLOR_LIST: readonly ["blue", "cyan", "green", "yellow", "orange", "red", "magenta", "purple", "blueMagenta", "grey"];
+export type OptionColor = typeof OPTION_COLOR_LIST[number];
+export declare function getOptionColor(index: number): OptionColor;
+export declare const OPTION_COLOR_RULES: {
+    readonly allowedColors: readonly ["blue", "cyan", "green", "yellow", "orange", "red", "magenta", "purple", "blueMagenta", "grey"];
+    readonly assignment: "Use OPTION_COLOR_LIST in order and cycle from the beginning when options exceed 10.";
+    readonly verifiedBy: {
+        readonly namespace: "package_154107__c";
+        readonly object: "object_test2";
+        readonly field: "option_colors";
+        readonly date: "2026-06-30";
+    };
+    readonly metadataShape: {
+        readonly typeName: "option";
+        readonly optionListPath: "type.settings.optionList";
+        readonly colorPath: "type.settings.optionList[].color";
+        readonly sourcePath: "type.settings.optionSource";
+        readonly globalOptionPath: "type.settings.globalOptionAPIName";
+    };
+    readonly createShape: {
+        readonly typeName: "enum";
+        readonly optionsPath: "type.settings.options";
+        readonly colorPath: "type.settings.options[].color";
+        readonly sourcePath: "type.settings.option_source";
+        readonly globalOptionPath: "type.settings.global_option_api_name";
+    };
+};
 export declare const FIELD_SCHEMA_RULES: FieldCreateRule[];
 export declare const SCHEMA_TYPE_MISMATCHES: Array<{
     metadataType: MetadataFieldType;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { LoggerLevel } from './logger';
 import { FIELD_TYPES, SYSTEM_FIELDS, LANGUAGE_CODES, SCHEMA_GUIDELINES, CREATE_OBJECT_EXAMPLE, UPDATE_OBJECT_ADD_FIELD_EXAMPLE, UPDATE_OBJECT_REPLACE_FIELD_EXAMPLE, UPDATE_OBJECT_REMOVE_FIELD_EXAMPLE, UPDATE_OBJECT_SETTINGS_EXAMPLE, getSystemFields, getCustomFieldTypes, getFieldType, isSystemField, createMultilingualText, extractMultilingualText, type FieldTypeMetadata, type MultilingualText, type ObjectSettings, type FieldTypeDefinition, type EncryptType, type FieldOperator, type CreateFieldDefinition, type UpdateFieldDefinition, type CreateObjectDefinition, type UpdateObjectDefinition } from './field-types';
+import { SCHEMA_TYPE_BY_METADATA_TYPE, OPTION_COLOR_LIST, OPTION_COLOR_RULES, FIELD_SCHEMA_RULES, SCHEMA_TYPE_MISMATCHES, BATCH_UPDATE_REQUIREMENTS, getOptionColor, type MetadataFieldType, type SchemaFieldType, type FieldCreateRule, type OptionColor } from './field-schema-rules';
 /**
  * 批量操作结果
  */
@@ -803,5 +804,5 @@ declare class Client {
 export declare const apaas: {
     Client: typeof Client;
 };
-export type { BatchResult, RetryOptions, FieldTypeMetadata, MultilingualText, ObjectSettings, FieldTypeDefinition, EncryptType, FieldOperator, CreateFieldDefinition, UpdateFieldDefinition, CreateObjectDefinition, UpdateObjectDefinition };
-export { FIELD_TYPES, SYSTEM_FIELDS, LANGUAGE_CODES, SCHEMA_GUIDELINES, CREATE_OBJECT_EXAMPLE, UPDATE_OBJECT_ADD_FIELD_EXAMPLE, UPDATE_OBJECT_REPLACE_FIELD_EXAMPLE, UPDATE_OBJECT_REMOVE_FIELD_EXAMPLE, UPDATE_OBJECT_SETTINGS_EXAMPLE, getSystemFields, getCustomFieldTypes, getFieldType, isSystemField, createMultilingualText, extractMultilingualText };
+export type { BatchResult, RetryOptions, FieldTypeMetadata, MultilingualText, ObjectSettings, FieldTypeDefinition, EncryptType, FieldOperator, CreateFieldDefinition, UpdateFieldDefinition, CreateObjectDefinition, UpdateObjectDefinition, MetadataFieldType, SchemaFieldType, FieldCreateRule, OptionColor };
+export { FIELD_TYPES, SYSTEM_FIELDS, LANGUAGE_CODES, SCHEMA_GUIDELINES, CREATE_OBJECT_EXAMPLE, UPDATE_OBJECT_ADD_FIELD_EXAMPLE, UPDATE_OBJECT_REPLACE_FIELD_EXAMPLE, UPDATE_OBJECT_REMOVE_FIELD_EXAMPLE, UPDATE_OBJECT_SETTINGS_EXAMPLE, getSystemFields, getCustomFieldTypes, getFieldType, isSystemField, createMultilingualText, extractMultilingualText, SCHEMA_TYPE_BY_METADATA_TYPE, OPTION_COLOR_LIST, OPTION_COLOR_RULES, FIELD_SCHEMA_RULES, SCHEMA_TYPE_MISMATCHES, BATCH_UPDATE_REQUIREMENTS, getOptionColor };

package/dist/index.js

@@ -735,6 +735,315 @@ function extractMultilingualText(multilingualText, languageCode = LANGUAGE_CODES
     return found ? found.text : ((_a = multilingualText[0]) === null || _a === void 0 ? void 0 : _a.text) || '';
 }
 
+/**
+ * Canonical field rules for schema.create/schema.update.
+ * Verified in namespace `package_5dc5b7__c` on 2026-02-10.
+ *
+ * Notes:
+ * - `metadataType` is usually the type name returned by object.metadata.fields.
+ * - Some entries are rule extensions for practical schema usage (`text_multiline`, `lookup_multi`).
+ * - `schemaType` is the type name that should be sent to schema.create/update.
+ */
+const SCHEMA_TYPE_BY_METADATA_TYPE = {
+    text: 'text',
+    text_multiline: 'text',
+    bigint: 'bigint',
+    number: 'float',
+    date: 'date',
+    datetime: 'datetime',
+    option: 'enum',
+    boolean: 'boolean',
+    lookup: 'lookup',
+    lookup_multi: 'lookup',
+    referenceField: 'reference_field',
+    file: 'attachment',
+    autoId: 'auto_number',
+    richText: 'richText',
+    mobileNumber: 'phone',
+    avatarOrLogo: 'avatar',
+    email: 'email',
+    region: 'region',
+    decimal: 'decimal',
+    multilingual: 'multilingual'
+};
+const OPTION_COLOR_LIST = [
+    'blue',
+    'cyan',
+    'green',
+    'yellow',
+    'orange',
+    'red',
+    'magenta',
+    'purple',
+    'blueMagenta',
+    'grey'
+];
+function getOptionColor(index) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error('Option color index must be a non-negative integer.');
+    }
+    return OPTION_COLOR_LIST[index % OPTION_COLOR_LIST.length];
+}
+const OPTION_COLOR_RULES = {
+    allowedColors: OPTION_COLOR_LIST,
+    assignment: 'Use OPTION_COLOR_LIST in order and cycle from the beginning when options exceed 10.',
+    verifiedBy: {
+        namespace: 'package_154107__c',
+        object: 'object_test2',
+        field: 'option_colors',
+        date: '2026-06-30'
+    },
+    metadataShape: {
+        typeName: 'option',
+        optionListPath: 'type.settings.optionList',
+        colorPath: 'type.settings.optionList[].color',
+        sourcePath: 'type.settings.optionSource',
+        globalOptionPath: 'type.settings.globalOptionAPIName'
+    },
+    createShape: {
+        typeName: 'enum',
+        optionsPath: 'type.settings.options',
+        colorPath: 'type.settings.options[].color',
+        sourcePath: 'type.settings.option_source',
+        globalOptionPath: 'type.settings.global_option_api_name'
+    }
+};
+const FIELD_SCHEMA_RULES = [
+    {
+        metadataType: 'text',
+        schemaType: 'text',
+        settingsExample: {
+            required: false,
+            unique: false,
+            case_sensitive: false,
+            multiline: false,
+            max_length: 255
+        }
+    },
+    {
+        metadataType: 'text_multiline',
+        schemaType: 'text',
+        settingsExample: {
+            required: false,
+            unique: false,
+            case_sensitive: false,
+            multiline: true,
+            max_length: 100000
+        }
+    },
+    {
+        metadataType: 'bigint',
+        schemaType: 'bigint',
+        settingsExample: {
+            required: false,
+            unique: false
+        }
+    },
+    {
+        metadataType: 'number',
+        schemaType: 'float',
+        settingsExample: {
+            required: false,
+            unique: false,
+            display_as_percentage: false,
+            decimal_places_number: 2
+        },
+        notes: 'Do not send create type as `number`.'
+    },
+    {
+        metadataType: 'date',
+        schemaType: 'date',
+        settingsExample: {
+            required: false
+        }
+    },
+    {
+        metadataType: 'datetime',
+        schemaType: 'datetime',
+        settingsExample: {
+            required: false
+        }
+    },
+    {
+        metadataType: 'option',
+        schemaType: 'enum',
+        settingsExample: {
+            required: false,
+            multiple: false,
+            option_source: 'custom',
+            global_option_api_name: '',
+            options: [
+                {
+                    label: { zh_cn: 'Option One', en_us: 'Option One' },
+                    api_name: 'option_one',
+                    description: null,
+                    color: 'blue',
+                    active: true
+                },
+                {
+                    label: { zh_cn: 'Option Two', en_us: 'Option Two' },
+                    api_name: 'option_two',
+                    description: null,
+                    color: 'green',
+                    active: true
+                }
+            ]
+        },
+        notes: `Do not send create type as \`option\`. Metadata returns optionList/optionSource/globalOptionAPIName; create/update expects options/option_source/global_option_api_name. Available option colors: ${OPTION_COLOR_LIST.join(', ')}.`
+    },
+    {
+        metadataType: 'boolean',
+        schemaType: 'boolean',
+        settingsExample: {
+            default_value: true,
+            description_if_true: { zh_cn: '1', en_us: '1' },
+            description_if_false: { zh_cn: '0', en_us: '0' }
+        }
+    },
+    {
+        metadataType: 'lookup',
+        schemaType: 'lookup',
+        settingsExample: {
+            required: false,
+            multiple: false,
+            referenced_object_api_name: '_user',
+            display_as_tree: false,
+            display_style: 'select'
+        },
+        dependsOn: ['Target object must exist first: `_user`'],
+        notes: 'Single-value lookup (`multiple: false`), can be used by `reference_field`.'
+    },
+    {
+        metadataType: 'lookup_multi',
+        schemaType: 'lookup',
+        settingsExample: {
+            required: false,
+            multiple: true,
+            referenced_object_api_name: '_user',
+            display_as_tree: false,
+            display_style: 'select'
+        },
+        dependsOn: ['Target object must exist first: `_user`'],
+        notes: 'Multi-value lookup (`multiple: true`) cannot be used by `reference_field`.'
+    },
+    {
+        metadataType: 'referenceField',
+        schemaType: 'reference_field',
+        settingsExample: {
+            current_lookup_field_api_name: 'lookup_835c2a2457b',
+            target_reference_field_api_name: '_lark_user_id'
+        },
+        dependsOn: [
+            'A single-value lookup field must exist first in the same object',
+            'The target field must exist in the lookup target object'
+        ],
+        notes: 'Guide field must be single lookup (`multiple: false`).'
+    },
+    {
+        metadataType: 'file',
+        schemaType: 'attachment',
+        settingsExample: {
+            required: false,
+            any_type: true,
+            max_uploaded_num: 10,
+            mime_types: []
+        },
+        notes: 'Do not send create type as `file`.'
+    },
+    {
+        metadataType: 'autoId',
+        schemaType: 'auto_number',
+        settingsExample: {
+            generation_method: 'random',
+            digits: 1,
+            prefix: '',
+            suffix: '',
+            start_at: '1'
+        },
+        notes: 'Do not send create type as `autoId`.'
+    },
+    {
+        metadataType: 'richText',
+        schemaType: 'richText',
+        settingsExample: {
+            required: false,
+            max_length: 1000
+        }
+    },
+    {
+        metadataType: 'mobileNumber',
+        schemaType: 'phone',
+        settingsExample: {
+            required: false,
+            unique: false
+        },
+        notes: 'Do not send create type as `mobileNumber`.'
+    },
+    {
+        metadataType: 'avatarOrLogo',
+        schemaType: 'avatar',
+        settingsExample: {
+            display_style: 'square'
+        },
+        notes: 'Do not send create type as `avatarOrLogo`.'
+    },
+    {
+        metadataType: 'email',
+        schemaType: 'email',
+        settingsExample: {
+            required: false,
+            unique: false
+        }
+    },
+    {
+        metadataType: 'region',
+        schemaType: 'region',
+        settingsExample: {
+            required: false,
+            multiple: false,
+            has_level_strict: true,
+            strict_level: 4
+        }
+    },
+    {
+        metadataType: 'decimal',
+        schemaType: 'decimal',
+        settingsExample: {
+            required: false,
+            unique: false,
+            display_as_percentage: false,
+            decimal_places: 2
+        }
+    },
+    {
+        metadataType: 'multilingual',
+        schemaType: 'multilingual',
+        settingsExample: {
+            required: false,
+            unique: false,
+            case_sensitive: false,
+            multiline: false,
+            max_length: 1000
+        }
+    }
+];
+const SCHEMA_TYPE_MISMATCHES = FIELD_SCHEMA_RULES
+    .filter((rule) => rule.metadataType !== rule.schemaType)
+    .map((rule) => ({
+    metadataType: rule.metadataType,
+    schemaType: rule.schemaType
+}));
+const BATCH_UPDATE_REQUIREMENTS = {
+    add: 'Use operator=add with full field definition.',
+    replace: 'Use operator=replace and include full `type` (name + settings). Label-only replace fails.',
+    remove: 'Use operator=remove with api_name only.',
+    dependencyOrder: {
+        add: ['lookup/lookup_multi before reference_field'],
+        remove: ['reference_field before lookup/lookup_multi']
+    },
+    referenceFieldConstraint: 'reference_field only works with single lookup (`multiple: false`).'
+};
+
 /**
  * 判断错误是否可重试
  */
@@ -2744,10 +3053,16 @@ const apaas = {
     Client
 };
 
+exports.BATCH_UPDATE_REQUIREMENTS = BATCH_UPDATE_REQUIREMENTS;
 exports.CREATE_OBJECT_EXAMPLE = CREATE_OBJECT_EXAMPLE;
+exports.FIELD_SCHEMA_RULES = FIELD_SCHEMA_RULES;
 exports.FIELD_TYPES = FIELD_TYPES;
 exports.LANGUAGE_CODES = LANGUAGE_CODES;
+exports.OPTION_COLOR_LIST = OPTION_COLOR_LIST;
+exports.OPTION_COLOR_RULES = OPTION_COLOR_RULES;
 exports.SCHEMA_GUIDELINES = SCHEMA_GUIDELINES;
+exports.SCHEMA_TYPE_BY_METADATA_TYPE = SCHEMA_TYPE_BY_METADATA_TYPE;
+exports.SCHEMA_TYPE_MISMATCHES = SCHEMA_TYPE_MISMATCHES;
 exports.SYSTEM_FIELDS = SYSTEM_FIELDS;
 exports.UPDATE_OBJECT_ADD_FIELD_EXAMPLE = UPDATE_OBJECT_ADD_FIELD_EXAMPLE;
 exports.UPDATE_OBJECT_REMOVE_FIELD_EXAMPLE = UPDATE_OBJECT_REMOVE_FIELD_EXAMPLE;
@@ -2758,5 +3073,6 @@ exports.createMultilingualText = createMultilingualText;
 exports.extractMultilingualText = extractMultilingualText;
 exports.getCustomFieldTypes = getCustomFieldTypes;
 exports.getFieldType = getFieldType;
+exports.getOptionColor = getOptionColor;
 exports.getSystemFields = getSystemFields;
 exports.isSystemField = isSystemField;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "apaas-oapi-client",
-    "version": "0.1.39",
+    "version": "0.1.40",
     "main": "dist/index.js",
     "bin": {
         "apaas-oapi-client": "./bin/apaas-oapi-client.js"

package/skills/apaas-schema/SKILL.md

@@ -7,40 +7,35 @@ description: "Use for aPaaS Node SDK schema management: creating objects, updati
 
 Use this skill for `client.schema.*`.
 
-## Required Reference
+## Required References
 
-Before creating or updating fields, read `references/field-schema-rules.md`. It contains the verified metadata-to-create type mapping and dependency order.
+- Before creating or updating fields, read `references/field-schema-rules.md`. It contains the verified metadata-to-create type mapping and option color rules.
+- For whole-app object maintenance, SQL/ER conversion, multi-object dependencies, or delete/rebuild workflows, read `references/schema-maintenance-sop.md`.
 
 ## Workflow
 
 1. Use `apaas-shared` to initialize the client.
 2. Read current objects with `client.object.listWithIterator()`.
 3. Read existing fields with `client.object.metadata.fields({ object_name })`.
-4. Build the smallest schema payload that matches the requested change.
-5. For dependency fields, create target objects first, then lookup fields, then reference fields.
-6. After the call, re-read metadata to verify the effective schema.
+4. For new objects, create shells first, then add fields with `schema.update`.
+5. For dependency fields, create base fields first, then lookup fields, then reference fields.
+6. Check request-level, silent-failure, and item-level response status.
+7. After the call, re-read metadata to verify the effective schema.
 
 ## Create Object
 
+Create objects as shells first. Do not rely on `schema.create({ fields })` to create fields.
+
 ```ts
 await client.schema.create({
   objects: [{
     api_name: "product",
     label: { zh_cn: "产品", en_us: "Product" },
     settings: {
-      display_name: "name",
-      allow_search_fields: ["_id", "code", "name"],
-      search_layout: ["code", "name"]
-    },
-    fields: [{
-      api_name: "code",
-      label: { zh_cn: "产品编号", en_us: "Product Code" },
-      type: {
-        name: "text",
-        settings: { required: true, unique: true, max_length: 50 }
-      },
-      encrypt_type: "none"
-    }]
+      display_name: "_id",
+      allow_search_fields: ["_id"],
+      search_layout: []
+    }
   }]
 });
 ```

package/skills/apaas-schema/references/field-schema-rules.md

@@ -5,6 +5,7 @@ Use this reference before `client.schema.create` or `client.schema.update` field
 - Verified source in this repo: `src/FIELD_SCHEMA_RULES.md`
 - Machine-readable source: `src/field-schema-rules.ts`
 - Verification date in source: `2026-02-10`
+- Option color live check: `package_154107__c.object_test2.option_colors` on `2026-06-30`
 
 ## Metadata To Create Type Mapping
 
@@ -61,6 +62,52 @@ Allowed option colors:
 - `blueMagenta`
 - `grey`
 
+Use the colors in this order and cycle from the beginning when options exceed 10. The live `object_test2.option_colors` check returned colors 1-12 as:
+
+```text
+blue, cyan, green, yellow, orange, red, magenta, purple, blueMagenta, grey, blue, cyan
+```
+
+### Option Metadata Shape vs Create Shape
+
+`object.metadata.fields` returns option fields in metadata shape:
+
+```ts
+{
+  type: {
+    name: "option",
+    settings: {
+      optionSource: "custom",
+      globalOptionAPIName: "",
+      optionList: [
+        { apiName: "option_x", color: "blue", active: true, label: [{ language_code: 2052, text: "1" }] }
+      ]
+    }
+  }
+}
+```
+
+`schema.create` / `schema.update` must use create shape:
+
+```ts
+{
+  type: {
+    name: "enum",
+    settings: {
+      option_source: "custom",
+      global_option_api_name: "",
+      options: [
+        { api_name: "option_x", color: "blue", active: true, label: { zh_cn: "1", en_us: "1" } }
+      ]
+    }
+  }
+}
+```
+
+Do not copy metadata `optionList` back into `schema.update`; convert it to `options`.
+
+Use `getOptionColor(index)` from the SDK to assign colors in this stable 10-color cycle.
+
 ## Minimal Lookup Example
 
 ```ts

package/skills/apaas-schema/references/schema-maintenance-sop.md

@@ -0,0 +1,181 @@
+# Schema Maintenance SOP
+
+Use this reference for whole-application object maintenance: reading object structure, creating objects, editing fields, deleting fields, deleting objects, converting SQL/ER designs, and managing lookup/reference dependencies.
+
+## Non-Negotiable Rules
+
+- Read live object metadata before writing.
+- Do not modify or delete system objects `_user` and `_department`.
+- Do not create, replace, or remove fields whose API name starts with `_`.
+- Treat `schema.create`, `schema.update`, and `schema.delete` as high-risk writes.
+- Batch `schema.create/update/delete` calls by at most 10 objects.
+- After every write, re-read metadata and verify the expected object/field shape.
+
+## Response Validation
+
+Check three layers after every schema call:
+
+```ts
+function checkSchemaResponse(result: any, context: string) {
+  if (result.code !== "0") {
+    throw new Error(`${context} request failed: ${result.code} ${result.msg || ""}`);
+  }
+
+  if (result.data === null) {
+    throw new Error(`${context} silently failed: result.code is 0 but result.data is null`);
+  }
+
+  const failed = (result.data?.items || []).filter((item: any) => item.status?.code !== "0");
+  if (failed.length > 0) {
+    throw new Error(`${context} item failures: ${JSON.stringify(failed)}`);
+  }
+}
+```
+
+`code: "0"` with `data: null` is not success. It usually means a required setting is missing, for example `text.multiline` or `auto_number.generation_method`.
+
+## Create Objects: Three Stages
+
+Do not create a full object with fields in one call. Use this sequence even when there is no obvious dependency cycle.
+
+1. Stage 1a: create object shells only.
+2. Stage 1b: add base fields with `schema.update` and `operator: "add"`.
+3. Stage 2: add `lookup` / `lookup_multi` fields after all target objects exist.
+4. Stage 3: add `reference_field` after its single-value lookup exists.
+5. Final: update `display_name`, `allow_search_fields`, and `search_layout` after fields exist.
+
+```ts
+await client.schema.create({
+  objects: [{
+    api_name: "customer",
+    label: { zh_cn: "客户", en_us: "Customer" },
+    settings: { display_name: "_id", allow_search_fields: ["_id"], search_layout: [] }
+  }]
+});
+```
+
+```ts
+await client.schema.update({
+  objects: [{
+    api_name: "customer",
+    fields: [{
+      operator: "add",
+      api_name: "name",
+      label: { zh_cn: "客户名称", en_us: "Name" },
+      type: {
+        name: "text",
+        settings: {
+          required: true,
+          unique: false,
+          case_sensitive: false,
+          multiline: false,
+          max_length: 100
+        }
+      },
+      encrypt_type: "none"
+    }]
+  }]
+});
+```
+
+## Update Fields
+
+- Add: send `operator: "add"` and the full field definition.
+- Replace: send `operator: "replace"` and the full `type.name + type.settings`; label-only replace fails.
+- Remove: send `operator: "remove"` and only `api_name`.
+- Skip existing fields when rerunning idempotently.
+
+```ts
+async function addFieldsIdempotent(client: any, objectName: string, fieldsToAdd: any[]) {
+  const metadata = await client.object.metadata.fields({ object_name: objectName });
+  const existingNames = new Set((metadata.data?.fields || []).map((field: any) => field.apiName));
+  const newFields = fieldsToAdd.filter(field => !existingNames.has(field.api_name));
+  if (newFields.length === 0) return;
+  const result = await client.schema.update({ objects: [{ api_name: objectName, fields: newFields }] });
+  checkSchemaResponse(result, `addFields(${objectName})`);
+}
+```
+
+## Dependency Order
+
+Add order:
+
+1. Object shells
+2. Base fields
+3. `lookup` / `lookup_multi`
+4. `reference_field`
+
+Remove order:
+
+1. `reference_field`
+2. `lookup` / `lookup_multi`
+3. Other custom fields
+4. Custom objects
+
+Never add a lookup and a reference field that depends on it in the same `schema.update` batch; execution order is not guaranteed.
+
+## Delete All Custom Objects
+
+Use this flow for environment cleanup or model rebuilds:
+
+1. List objects with `client.object.listWithIterator()`.
+2. Filter out system objects whose API name starts with `_`.
+3. Read fields for each custom object.
+4. Remove `referenceField` fields grouped by object.
+5. Remove `lookup` fields grouped by object.
+6. Delete custom objects in batches of 10.
+7. Re-list objects to verify deletion.
+
+## SQL / ER To aPaaS Mapping
+
+Map relational designs into aPaaS objects only after presenting a conversion table for user confirmation.
+
+| SQL Concept | aPaaS Mapping |
+| --- | --- |
+| Table | Object |
+| Primary key `id` | Ignore; aPaaS provides `_id` |
+| `created_at` / `updated_at` audit columns | Usually ignore; aPaaS provides system fields |
+| `VARCHAR(n)` / `CHAR(n)` | `text` with `max_length: n`, `multiline: false` |
+| `TEXT` / long text | `text` with `multiline: true`, `max_length: 100000` |
+| `INT` / `INTEGER` / `BIGINT` | `bigint` |
+| `FLOAT` / `DOUBLE` | `float` |
+| `DECIMAL(p,s)` | `decimal` with `decimal_places: s` |
+| `DATE` | `date` |
+| `DATETIME` / `TIMESTAMP` | `datetime` |
+| `BOOLEAN` / `TINYINT(1)` | `boolean` |
+| `ENUM(...)` | `enum` with `options` |
+| Foreign key | `lookup` with `multiple: false` |
+| Pure join table | Usually eliminate; use `lookup` with `multiple: true` on one side |
+| Join table with business fields | Keep as an object with two lookup fields |
+
+Semantic overrides:
+
+- Column names containing `email` / `mail`: prefer `email`.
+- Column names containing `phone` / `mobile` / `tel`: prefer `phone`.
+- Column names containing `avatar` / `logo`: prefer `avatar`.
+- Column names containing `region` / `province` / `city`: consider `region`, but ask before converting address text to region.
+
+Unsupported SQL features:
+
+- Stored procedures
+- Triggers
+- Views
+- Composite primary keys
+- Composite unique constraints
+- CHECK constraints
+- Partitioning
+
+## Confirmation Table
+
+Before creating from SQL/ER input, present a table like this and wait for confirmation:
+
+| SQL Table | aPaaS Object | Treatment |
+| --- | --- | --- |
+| customer | customer | Create |
+| customer_tag | - | Convert pure join table into multi lookup |
+
+| Object | SQL Column | SQL Type | aPaaS Type | API Name | Notes |
+| --- | --- | --- | --- | --- | --- |
+| customer | id | INT PK | - | - | Ignored; use `_id` |
+| customer | status | ENUM | enum | status | Confirm labels and colors |
+| order | customer_id | FK | lookup | customer | Target object must exist first |

package/src/FIELD_SCHEMA_RULES.md

@@ -7,6 +7,7 @@ This file summarizes the verified schema rules for field types in aPaaS.
 - Source object for metadata: `full_field_format`
 - Lookup target used in tests: `_user`
 - Reference field target used in tests: `_lark_user_id`
+- Option color live check: `package_154107__c.object_test2.option_colors` on `2026-06-30`
 
 ## Why this file exists
 
@@ -66,6 +67,26 @@ Allowed option colors:
 - `blueMagenta`
 - `grey`
 
+Use the colors in this order and cycle from the beginning when options exceed 10.
+
+Live metadata for option fields returns camelCase keys:
+
+- Type name: `option`
+- Options path: `type.settings.optionList`
+- Option source: `type.settings.optionSource`
+- Global option API name: `type.settings.globalOptionAPIName`
+
+Create/update schema payloads use snake_case keys:
+
+- Type name: `enum`
+- Options path: `type.settings.options`
+- Option source: `type.settings.option_source`
+- Global option API name: `type.settings.global_option_api_name`
+
+Do not copy metadata `optionList` back into `schema.update`; convert it to `options`.
+
+Use `getOptionColor(index)` from the SDK to assign colors in this stable 10-color cycle.
+
 ## Batch update (`batch_update`) rules
 
 - `add`: use `operator: "add"` and send full field definition.

package/src/field-schema-rules.ts

@@ -94,6 +94,41 @@ export const OPTION_COLOR_LIST = [
     'grey'
 ] as const;
 
+export type OptionColor = typeof OPTION_COLOR_LIST[number];
+
+export function getOptionColor(index: number): OptionColor {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error('Option color index must be a non-negative integer.');
+    }
+
+    return OPTION_COLOR_LIST[index % OPTION_COLOR_LIST.length];
+}
+
+export const OPTION_COLOR_RULES = {
+    allowedColors: OPTION_COLOR_LIST,
+    assignment: 'Use OPTION_COLOR_LIST in order and cycle from the beginning when options exceed 10.',
+    verifiedBy: {
+        namespace: 'package_154107__c',
+        object: 'object_test2',
+        field: 'option_colors',
+        date: '2026-06-30'
+    },
+    metadataShape: {
+        typeName: 'option',
+        optionListPath: 'type.settings.optionList',
+        colorPath: 'type.settings.optionList[].color',
+        sourcePath: 'type.settings.optionSource',
+        globalOptionPath: 'type.settings.globalOptionAPIName'
+    },
+    createShape: {
+        typeName: 'enum',
+        optionsPath: 'type.settings.options',
+        colorPath: 'type.settings.options[].color',
+        sourcePath: 'type.settings.option_source',
+        globalOptionPath: 'type.settings.global_option_api_name'
+    }
+} as const;
+
 export const FIELD_SCHEMA_RULES: FieldCreateRule[] = [
     {
         metadataType: 'text',
@@ -175,7 +210,7 @@ export const FIELD_SCHEMA_RULES: FieldCreateRule[] = [
                 }
             ]
         },
-        notes: `Do not send create type as \`option\`. Available option colors: ${OPTION_COLOR_LIST.join(', ')}.`
+        notes: `Do not send create type as \`option\`. Metadata returns optionList/optionSource/globalOptionAPIName; create/update expects options/option_source/global_option_api_name. Available option colors: ${OPTION_COLOR_LIST.join(', ')}.`
     },
     {
         metadataType: 'boolean',

package/src/index.ts

@@ -29,6 +29,19 @@ import {
     type CreateObjectDefinition,
     type UpdateObjectDefinition
 } from './field-types';
+import {
+    SCHEMA_TYPE_BY_METADATA_TYPE,
+    OPTION_COLOR_LIST,
+    OPTION_COLOR_RULES,
+    FIELD_SCHEMA_RULES,
+    SCHEMA_TYPE_MISMATCHES,
+    BATCH_UPDATE_REQUIREMENTS,
+    getOptionColor,
+    type MetadataFieldType,
+    type SchemaFieldType,
+    type FieldCreateRule,
+    type OptionColor
+} from './field-schema-rules';
 
 /**
  * 批量操作结果
@@ -2669,7 +2682,11 @@ export type {
     CreateFieldDefinition,
     UpdateFieldDefinition,
     CreateObjectDefinition,
-    UpdateObjectDefinition
+    UpdateObjectDefinition,
+    MetadataFieldType,
+    SchemaFieldType,
+    FieldCreateRule,
+    OptionColor
 };
 
 export {
@@ -2690,5 +2707,13 @@ export {
     getFieldType,
     isSystemField,
     createMultilingualText,
-    extractMultilingualText
+    extractMultilingualText,
+    // Schema rules
+    SCHEMA_TYPE_BY_METADATA_TYPE,
+    OPTION_COLOR_LIST,
+    OPTION_COLOR_RULES,
+    FIELD_SCHEMA_RULES,
+    SCHEMA_TYPE_MISMATCHES,
+    BATCH_UPDATE_REQUIREMENTS,
+    getOptionColor
 };