apaas-oapi-client 0.1.37 → 0.1.39

package/README.md

@@ -30,6 +30,48 @@
 
 ---
 
+## 🤖 **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/"
+```
+
+通过 npx 从 npm 直接安装：
+
+```bash
+npx apaas-oapi-client install-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 +80,7 @@ npm install apaas-oapi-client
 
 ---
 
-## � **快速开始**
+## 🚀 **快速开始**
 
 ### 创建数据对象
 

package/bin/apaas-oapi-client.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const skillsRoot = path.join(packageRoot, "skills");
+
+function usage() {
+    console.log(`Usage:
+  npx apaas-oapi-client install-skills [--target <dir>] [--dry-run]
+
+Commands:
+  install-skills    Install bundled aPaaS Codex skills.
+
+Options:
+  --target <dir>    Skill install directory. Defaults to $CODEX_HOME/skills or ~/.codex/skills.
+  --dry-run         Print planned copies without writing files.
+  -h, --help        Show this help.`);
+}
+
+function parseArgs(argv) {
+    const args = {
+        command: argv[0],
+        target: process.env.CODEX_HOME
+            ? path.join(process.env.CODEX_HOME, "skills")
+            : path.join(os.homedir(), ".codex", "skills"),
+        dryRun: false
+    };
+
+    if (args.command === "-h" || args.command === "--help") {
+        args.command = "help";
+        return args;
+    }
+
+    for (let i = 1; i < argv.length; i += 1) {
+        const arg = argv[i];
+
+        if (arg === "--dry-run") {
+            args.dryRun = true;
+            continue;
+        }
+
+        if (arg === "--target") {
+            const target = argv[i + 1];
+            if (!target) {
+                throw new Error("--target requires a directory");
+            }
+            args.target = path.resolve(target);
+            i += 1;
+            continue;
+        }
+
+        if (arg === "-h" || arg === "--help") {
+            args.command = "help";
+            continue;
+        }
+
+        throw new Error(`Unknown option: ${arg}`);
+    }
+
+    return args;
+}
+
+function listBundledSkills() {
+    if (!fs.existsSync(skillsRoot)) {
+        throw new Error(`Bundled skills directory not found: ${skillsRoot}`);
+    }
+
+    return fs.readdirSync(skillsRoot, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && entry.name.startsWith("apaas-"))
+        .map(entry => entry.name)
+        .sort();
+}
+
+function installSkills(args) {
+    const skillNames = listBundledSkills();
+
+    if (skillNames.length === 0) {
+        throw new Error(`No bundled apaas-* skills found in ${skillsRoot}`);
+    }
+
+    console.log(`Installing ${skillNames.length} aPaaS skill(s) to ${args.target}`);
+
+    if (!args.dryRun) {
+        fs.mkdirSync(args.target, { recursive: true });
+    }
+
+    for (const skillName of skillNames) {
+        const source = path.join(skillsRoot, skillName);
+        const target = path.join(args.target, skillName);
+        console.log(`${args.dryRun ? "Would copy" : "Copying"} ${skillName}`);
+
+        if (!args.dryRun) {
+            fs.cpSync(source, target, {
+                recursive: true,
+                force: true,
+                errorOnExist: false
+            });
+        }
+    }
+
+    console.log(args.dryRun ? "Dry run complete." : "Done. Restart or refresh Codex to load the skills.");
+}
+
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+
+    if (!args.command || args.command === "help") {
+        usage();
+        return;
+    }
+
+    if (args.command !== "install-skills") {
+        throw new Error(`Unknown command: ${args.command}`);
+    }
+
+    installSkills(args);
+}
+
+try {
+    main();
+} catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error("");
+    usage();
+    process.exitCode = 1;
+}

package/package.json

@@ -1,7 +1,10 @@
 {
     "name": "apaas-oapi-client",
-    "version": "0.1.37",
+    "version": "0.1.39",
     "main": "dist/index.js",
+    "bin": {
+        "apaas-oapi-client": "./bin/apaas-oapi-client.js"
+    },
     "exports": {
         ".": "./dist/index.js",
         "./node-sdk": "./dist/index.js"
@@ -14,8 +17,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 +49,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."