apaas-oapi-client 0.1.37 → 0.1.38

package/README.md

@@ -30,6 +30,42 @@
 
 ---
 
+## 🤖 **AI Agent / Skills**
+
+本仓库内置面向 AI Agent 的模块化 Skills，路径为 [skills](./skills)。设计采用 `shared + domain skill + references` 的轻量结构：主 `SKILL.md` 负责路由和安全边界，复杂规则放到 `references/` 按需读取。
+
+| Skill | 适用场景 |
+| --- | --- |
+| `apaas-shared` | Client 初始化、凭证安全、namespace、token、日志、分页与错误处理 |
+| `apaas-object` | 对象列表、字段元数据、记录查询/创建/更新/删除、Markdown 导出 |
+| `apaas-schema` | 对象和字段结构管理、字段类型映射、lookup/reference 依赖规则 |
+| `apaas-function-flow` | 云函数调用、自动化流程 v1/v2 执行 |
+| `apaas-builder` | 页面列表、页面详情、页面访问链接 |
+| `apaas-global` | 全局选项、环境变量读取与审计 |
+| `apaas-exchange-attachment` | 用户/部门 ID 交换、附件和头像上传下载 |
+
+从仓库根目录安装到 Codex Skill 目录：
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R skills/apaas-* "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
+从 npm 包所在项目安装：
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R node_modules/apaas-oapi-client/skills/apaas-* "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
+使用建议：
+
+- 写入前先用 `apaas-object` 读取真实 metadata。
+- Schema 字段变更前先读 `apaas-schema/references/field-schema-rules.md`。
+- 删除、批量写入、流程执行都按写操作处理，先确认目标和影响。
+
+---
+
 ## 📦 **安装**
 
 ```bash
@@ -38,7 +74,7 @@ npm install apaas-oapi-client
 
 ---
 
-## � **快速开始**
+## 🚀 **快速开始**
 
 ### 创建数据对象
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "apaas-oapi-client",
-    "version": "0.1.37",
+    "version": "0.1.38",
     "main": "dist/index.js",
     "exports": {
         ".": "./dist/index.js",
@@ -14,8 +14,19 @@
         "dev": "tsx src/index.ts",
         "release": "npm run build && npm version patch && git push origin main --follow-tags"
     },
-    "keywords": [],
+    "keywords": [
+        "apaas",
+        "openapi",
+        "nodejs",
+        "sdk",
+        "ai-agent",
+        "codex-skill"
+    ],
     "author": "",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/ennann/apaas-oapi-node-client"
+    },
     "license": "ISC",
     "dependencies": {
         "axios": "^1.10.0",
@@ -35,5 +46,5 @@
         "tsx": "^4.21.0",
         "typescript": "^5.8.3"
     },
-    "description": ""
+    "description": "aPaaS OpenAPI Node.js 客户端 SDK，内置 AI Agent 友好的模块化 Skills 与 Schema 辅助规则。"
 }

package/skills/apaas-builder/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: apaas-builder
+description: "Use for aPaaS Node SDK builder page operations: listing pages, paginating page metadata, reading page details, generating page access URLs with pageParams, parentPageParams, navId, or tabId, and verifying page IDs from live metadata."
+---
+
+# aPaaS Builder
+
+Use this skill for `client.page.*`.
+
+## Resolve Page IDs
+
+Start from live page metadata unless the user provides a confirmed page ID.
+
+```ts
+const { items } = await client.page.listWithIterator({ limit: 100 });
+const target = items.find(page => page.name === "门店详情");
+```
+
+Use returned `page_id` values in follow-up calls.
+
+## Page Detail
+
+```ts
+const detail = await client.page.detail({
+  page_id: "page_id"
+});
+```
+
+Use detail reads before generating links that require route parameters.
+
+## Page URL
+
+```ts
+const url = await client.page.url({
+  page_id: "page_id",
+  pageParams: { id: "record_id" },
+  parentPageParams: {},
+  navId: "nav_id",
+  tabId: "tab_id"
+});
+```
+
+Only include optional parameters that are required by the target page. Verify generated URLs by opening them or handing them to the user with the relevant page and record context.

package/skills/apaas-builder/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "aPaaS Builder"
+  short_description: "aPaaS 页面元数据、详情和访问链接生成操作指南"
+  default_prompt: "Use $apaas-builder to inspect pages and generate page links with the aPaaS Node SDK."

package/skills/apaas-exchange-attachment/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: apaas-exchange-attachment
+description: "Use for aPaaS Node SDK identity exchange and attachment operations: department ID exchange, user ID exchange, batch exchange with retry results, file upload/download/delete, avatar image upload/download, and safe handling of IDs and binary payloads."
+---
+
+# aPaaS Exchange Attachment
+
+Use this skill for `client.department.*`, `client.user.*`, and `client.attachment.*`.
+
+## Department Exchange
+
+```ts
+const department = await client.department.exchange({
+  department_id_type: "department_id",
+  department_id: "1758534140403815"
+});
+
+const batch = await client.department.batchExchange({
+  department_id_type: "external_department_id",
+  department_ids: ["dept-a", "dept-b"]
+});
+```
+
+Check `failedCount` after batch exchange.
+
+## User Exchange
+
+```ts
+const user = await client.user.exchange({
+  user_id_type: "external_open_id",
+  user_id: "ou_xxx",
+  feishu_app_id: "cli_xxx"
+});
+
+const batch = await client.user.batchExchange({
+  user_id_type: "external_user_id",
+  user_ids: ["u1", "u2"],
+  feishu_app_id: "cli_xxx"
+});
+```
+
+Use real `feishu_app_id`; do not guess it from namespace.
+
+## Attachments
+
+```ts
+const uploaded = await client.attachment.file.upload({ file });
+const data = await client.attachment.file.download({ file_id: "file_token" });
+await client.attachment.file.delete({ file_id: "file_token" });
+
+const avatar = await client.attachment.avatar.upload({ image });
+const imageData = await client.attachment.avatar.download({ image_id: "image_token" });
+```
+
+## Safety
+
+- Confirm deletes before calling `attachment.file.delete`.
+- Do not print binary payloads, raw access tokens, or private file contents.
+- For record attachment fields, read object metadata first and write only the field shape expected by the platform.

package/skills/apaas-exchange-attachment/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "aPaaS Exchange Attachment"
+  short_description: "aPaaS 用户部门 ID 交换和附件处理操作指南"
+  default_prompt: "Use $apaas-exchange-attachment to exchange IDs or handle attachments with the aPaaS Node SDK."

package/skills/apaas-function-flow/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: apaas-function-flow
+description: "Use for aPaaS Node SDK cloud function and automation flow execution: invoking functions, executing v1/v2 flows, preparing operator payloads, checking returned code/msg/data, and avoiding unsafe repeated workflow submissions."
+---
+
+# aPaaS Function Flow
+
+Use this skill for `client.function.*` and `client.automation.*`.
+
+## Function Invoke
+
+Use when the target is a named cloud function and the caller already knows the function contract.
+
+```ts
+const res = await client.function.invoke({
+  name: "SyncStoreManager",
+  params: {
+    store_id: "record_id"
+  }
+});
+
+if (res.code !== "0") {
+  throw new Error(res.msg || "function invoke failed");
+}
+```
+
+## Automation Flow
+
+Use `automation.v1.execute` only for v1 flow endpoints and `automation.v2.execute` for v2 endpoints. Always pass an explicit operator object from a real user record or documented service account.
+
+```ts
+const res = await client.automation.v2.execute({
+  flow_api_name: "store_manager_change",
+  operator: {
+    _id: 123456,
+    email: "operator@example.com"
+  },
+  params: {
+    store_id: "record_id",
+    new_manager_id: "user_record_id"
+  }
+});
+```
+
+## Safety
+
+- Treat flow execution as a write operation; confirm before triggering production workflows.
+- Do not resubmit failed flows with `is_resubmit` unless the user explicitly requests it and `pre_instance_id` is known.
+- Log flow/function names and result codes, not secrets or full sensitive payloads.
+- If the flow mutates records, verify the target record after execution with `apaas-object`.

package/skills/apaas-function-flow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "aPaaS Function Flow"
+  short_description: "aPaaS 云函数调用和自动化流程执行安全操作指南"
+  default_prompt: "Use $apaas-function-flow to invoke cloud functions or automation flows."

package/skills/apaas-global/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: apaas-global
+description: "Use for aPaaS Node SDK global data operations: reading global option details, listing global options, reading global variable details, listing global variables, paginating results, and resolving API names from live metadata."
+---
+
+# aPaaS Global
+
+Use this skill for `client.global.*`.
+
+## Global Options
+
+```ts
+const option = await client.global.options.detail({
+  api_name: "store_status"
+});
+
+const { total, items } = await client.global.options.listWithIterator({
+  limit: 100,
+  filter: { quickQuery: "status" }
+});
+```
+
+Use global options to validate enum-like values before writing records or schema.
+
+## Global Variables
+
+```ts
+const variable = await client.global.variables.detail({
+  api_name: "current_region"
+});
+
+const variables = await client.global.variables.listWithIterator({
+  limit: 100
+});
+```
+
+Do not expose secrets from global variables. When reporting results, summarize key names and operational meaning instead of raw secret values.
+
+## Rules
+
+- Use `listWithIterator` for inventory or audit tasks.
+- Use `detail` when an exact API name is known.
+- Treat missing global values as configuration problems, not SDK bugs, until live metadata proves otherwise.

package/skills/apaas-global/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "aPaaS Global"
+  short_description: "aPaaS 全局选项和环境变量读取审计安全操作指南"
+  default_prompt: "Use $apaas-global to inspect global options and variables with the aPaaS Node SDK."

package/skills/apaas-object/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: apaas-object
+description: "Use for aPaaS Node SDK object metadata and record operations: listing objects, reading fields, exporting metadata to Markdown, querying records, count, create, update, delete, batch operations, pagination, and record-level error recovery."
+---
+
+# aPaaS Object
+
+Use this skill for `client.object.*`.
+
+## Workflow
+
+1. Initialize the client with `apaas-shared`.
+2. Resolve object and field API names from live metadata.
+3. Read before write when the payload depends on field type or readonly status.
+4. Use iterator helpers for full-result work.
+5. Check SDK response codes and failed item lists.
+
+## Metadata
+
+Prefer metadata calls before record work:
+
+```ts
+const objects = await client.object.listWithIterator({
+  filter: { type: "custom", quickQuery: "store" },
+  limit: 50
+});
+
+const fields = await client.object.metadata.fields({
+  object_name: "object_store"
+});
+
+const markdown = await client.object.metadata.export2markdown({
+  object_names: ["object_store", "_user"]
+});
+```
+
+Use returned API names, not user-facing labels, in later calls.
+
+## Record Reads
+
+- Use `search.record` for one known record ID.
+- Use `search.records` for one page.
+- Use `search.recordsWithIterator` for full-table or full-filter tasks.
+- Use `search.count` when only the count is needed.
+
+```ts
+const { total, items } = await client.object.search.recordsWithIterator({
+  object_name: "object_store",
+  data: {
+    need_total_count: true,
+    page_size: 100,
+    offset: 0,
+    select: ["_id", "store_code", "store_name"],
+    use_page_token: true
+  }
+});
+```
+
+Do not answer global max/min/top/count questions from a single page unless the user asked for a sample.
+
+## Record Writes
+
+Use storage fields only. Re-read metadata when unsure.
+
+```ts
+await client.object.create.record({
+  object_name: "object_event_log",
+  record: {
+    name: "sync_started",
+    content: "nightly job started"
+  }
+});
+
+await client.object.update.record({
+  object_name: "object_store",
+  record_id: "record_id",
+  record: { store_name: "新门店名称" }
+});
+```
+
+For large batches, use `recordsWithIterator` helpers and inspect failures:
+
+```ts
+const result = await client.object.update.recordsWithIterator({
+  object_name: "object_store",
+  records,
+  limit: 100
+});
+
+if (result.failedCount > 0) {
+  console.warn(result.failed);
+}
+```
+
+## Delete Rules
+
+- Confirm target object and record IDs before delete.
+- Prefer `delete.recordsWithIterator` for large deletes so partial failures are visible.
+- Report `successCount`, `failedCount`, and failed IDs after batch deletion.

package/skills/apaas-object/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "aPaaS Object"
+  short_description: "aPaaS 对象元数据、记录读写与分页查询操作指南"
+  default_prompt: "Use $apaas-object to read metadata and operate records with the aPaaS Node SDK."

package/skills/apaas-schema/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: apaas-schema
+description: "Use for aPaaS Node SDK schema management: creating objects, updating object labels/settings, adding/replacing/removing fields, deleting objects, field type mapping, lookup/reference field dependencies, and schema change safety checks."
+---
+
+# aPaaS Schema
+
+Use this skill for `client.schema.*`.
+
+## Required Reference
+
+Before creating or updating fields, read `references/field-schema-rules.md`. It contains the verified metadata-to-create type mapping and dependency order.
+
+## 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.
+
+## Create Object
+
+```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"
+    }]
+  }]
+});
+```
+
+## Update Object Or Fields
+
+- Add field: `operator: "add"` and full field definition.
+- Replace field: `operator: "replace"` and full `type.name + type.settings`.
+- Remove field: `operator: "remove"` and `api_name` only.
+- Update label/settings without field changes by omitting `fields`.
+
+```ts
+await client.schema.update({
+  objects: [{
+    api_name: "product",
+    fields: [{
+      operator: "add",
+      api_name: "description",
+      label: { zh_cn: "产品描述", en_us: "Description" },
+      type: {
+        name: "text",
+        settings: { multiline: true, max_length: 100000 }
+      },
+      encrypt_type: "none"
+    }]
+  }]
+});
+```
+
+## Delete Rules
+
+- Confirm the object API names before `client.schema.delete`.
+- Do not delete objects as a cleanup shortcut if records or references may still depend on them.
+- Remove `reference_field` before removing its lookup field.

package/skills/apaas-schema/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "aPaaS Schema"
+  short_description: "aPaaS 对象、字段结构和类型规则管理安全操作指南"
+  default_prompt: "Use $apaas-schema to create or update aPaaS object schemas safely."

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

@@ -0,0 +1,98 @@
+# Field Schema Rules
+
+Use this reference before `client.schema.create` or `client.schema.update` field changes.
+
+- 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`
+
+## Metadata To Create Type Mapping
+
+| Metadata Type | Create Type | Notes |
+| --- | --- | --- |
+| `text` | `text` | Single-line text, commonly `max_length=255`. |
+| `text_multiline` | `text` | Use `multiline=true`, commonly `max_length=100000`. |
+| `bigint` | `bigint` | Same type name. |
+| `number` | `float` | `number` create type fails. |
+| `date` | `date` | Same type name. |
+| `datetime` | `datetime` | Same type name. |
+| `option` | `enum` | `option` create type fails. |
+| `boolean` | `boolean` | Same type name. |
+| `lookup` | `lookup` | Single value, `multiple=false`. |
+| `lookup_multi` | `lookup` | Multi value, `multiple=true`. |
+| `referenceField` | `reference_field` | Depends on a single-value lookup field. |
+| `file` | `attachment` | `file` create type fails. |
+| `autoId` | `auto_number` | `autoId` create type fails. |
+| `richText` | `richText` | Same type name. |
+| `mobileNumber` | `phone` | `mobileNumber` create type fails. |
+| `avatarOrLogo` | `avatar` | `avatarOrLogo` create type fails. |
+| `email` | `email` | Same type name. |
+| `region` | `region` | Same type name. |
+| `decimal` | `decimal` | Same type name. |
+| `multilingual` | `multilingual` | Same type name. |
+
+## Dependency Rules
+
+- Create target objects before lookup fields that reference them.
+- Create `lookup` or `lookup_multi` before `reference_field`.
+- Use only a single-value `lookup` as `reference_field.current_lookup_field_api_name`.
+- Do not use `lookup_multi` as the guide field for `reference_field`.
+- Remove `reference_field` before removing its lookup field.
+
+## Batch Update Rules
+
+- `add`: use `operator: "add"` and send the full field definition.
+- `replace`: use `operator: "replace"` and send full `type.name` plus `type.settings`.
+- `remove`: use `operator: "remove"` and send only `api_name`.
+- Label-only replace without `type` fails with `k_ec_000015 field type is required`.
+
+## Option Colors
+
+Allowed option colors:
+
+- `blue`
+- `cyan`
+- `green`
+- `yellow`
+- `orange`
+- `red`
+- `magenta`
+- `purple`
+- `blueMagenta`
+- `grey`
+
+## Minimal Lookup Example
+
+```ts
+{
+  operator: "add",
+  api_name: "owner",
+  label: { zh_cn: "负责人", en_us: "Owner" },
+  type: {
+    name: "lookup",
+    settings: {
+      objectAPIName: "_user",
+      multiple: false
+    }
+  },
+  encrypt_type: "none"
+}
+```
+
+## Minimal Reference Field Example
+
+```ts
+{
+  operator: "add",
+  api_name: "owner_lark_id",
+  label: { zh_cn: "负责人飞书 ID", en_us: "Owner Lark ID" },
+  type: {
+    name: "reference_field",
+    settings: {
+      current_lookup_field_api_name: "owner",
+      target_reference_field_api_name: "_lark_user_id"
+    }
+  },
+  encrypt_type: "none"
+}
+```

package/skills/apaas-shared/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: apaas-shared
+description: "Use for aPaaS Node SDK shared setup and safety rules: client initialization, credentials, namespace, token cache, logger level, pagination defaults, retry expectations, write/delete confirmation, and error triage before using module-specific apaas skills."
+---
+
+# aPaaS Shared
+
+Use this skill before module-specific aPaaS SDK work.
+
+## Baseline
+
+- Use the Node SDK package `apaas-oapi-client`.
+- Initialize one `apaas.Client` per namespace.
+- Keep `clientId`, `clientSecret`, access tokens, and app secrets out of logs and final answers.
+- Prefer `client.setLoggerLevel(3)` for normal work, `4` for debugging, and `5` only when inspecting non-sensitive payloads.
+- Treat SDK responses with `code !== "0"` as failed even if the HTTP call succeeded.
+
+```ts
+import { apaas } from "apaas-oapi-client";
+
+const client = new apaas.Client({
+  clientId: process.env.APAAS_CLIENT_ID!,
+  clientSecret: process.env.APAAS_CLIENT_SECRET!,
+  namespace: process.env.APAAS_NAMESPACE!
+});
+
+await client.init();
+client.setLoggerLevel(3);
+```
+
+## Safety Rules
+
+- Read real metadata before writing records, fields, flows, or pages.
+- Confirm user intent before destructive calls: record delete, batch delete, schema delete, field remove, attachment delete.
+- For batch operations, inspect `failed`, `failedCount`, or per-item success fields before reporting completion.
+- For full-table answers, use iterator methods and verify pagination is exhausted; a single page is only a sample.
+- Do not write system fields, readonly fields, formula outputs, lookup outputs, or reference field outputs as ordinary record values.
+
+## Module Routing
+
+- Object metadata and record CRUD: use `apaas-object`.
+- Object and field schema changes: use `apaas-schema`.
+- Cloud functions and automation flows: use `apaas-function-flow`.
+- Builder page metadata and links: use `apaas-builder`.
+- Global options and variables: use `apaas-global`.
+- User/department ID exchange and attachments: use `apaas-exchange-attachment`.
+
+## Error Triage
+
+| Symptom | First action |
+| --- | --- |
+| Permission or scope error | Verify app permissions and namespace; do not retry blindly. |
+| Field value type mismatch | Re-read `client.object.metadata.fields({ object_name })`. |
+| Missing field/object | Re-read object list or metadata; use API names from returned data. |
+| Batch partially failed | Report failed items and retry only failed IDs/records when safe. |
+| Rate limit or transient 5xx | Use SDK iterator/batch helpers and retry only idempotent reads or confirmed-safe writes. |

package/skills/apaas-shared/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "aPaaS Shared"
+  short_description: "aPaaS SDK 认证、凭证、安全与通用调用规则指南"
+  default_prompt: "Use $apaas-shared to initialize aPaaS SDK access safely."

package/.env

@@ -1,5 +0,0 @@
-CLIENT_APP_ID=c_fc919c38b7ab41a5ab36
-CLIENT_APP_SECRET=cad5106b819a43f286fb46a51b6ea2c8
-
-LARK_APP_ID=cli_a77cb9cd64b81013
-LARK_APP_SECRET=AEq56P8ntETGxNucLHTgbdLR2kNkXRNd