yidaconnector 2026.6.11

package/yida-skills/skills/large-file-write/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: large-file-write
+description: 解决 heredoc 或 shell 命令写入大文件内容被截断的问题。当需要可靠地写入超过 100 行的大块内容时使用，通过 Node.js 脚本将内容作为模板字符串写入，绕过 shell 截断限制。不适用于：文件内容少于 100 行（直接使用 create_file 工具），或二进制文件写入。
+---
+
+# Large File Write Skill
+
+## 问题背景
+
+在 AI Agent 模式下，使用 heredoc（`<< 'EOF'`）或 shell 命令向文件写入大块内容时，经常出现：
+- 内容被截断（工具输出超过 token 限制）
+- heredoc 内容未生效（zsh 特殊字符转义问题）
+- 多次追加导致重复内容或语法错误
+- Windows PowerShell 为了转义内容而执行 `Get-Content -Raw | ConvertTo-Json`，会把大 JSX/JS 文件整体读入内存并 JSON 转义，可能导致内存暴涨
+
+## 解决方案
+
+使用 Node.js 脚本 `scripts/write.js`，将内容作为 JS 字符串变量传入，绕过 shell 截断限制。
+
+## 使用方式
+
+三种写入模式的完整代码示例，详见 [references/write-patterns.md](./references/write-patterns.md)：
+
+- **模式一**：创建内容脚本后执行（推荐）— 用 `create_file` 创建临时 JS 脚本，再 `node` 执行
+- **模式二**：追加内容到已有文件 — 用 `fs.appendFileSync` 追加大块内容
+- **模式三**：使用通用写入脚本（stdin 模式）— 通过管道传入内容
+
+### 快速示例
+
+```js
+// /tmp/content-payload.js
+const fs = require('fs');
+const content = `// 你的大块内容（支持任意长度）
+export function myFunction() { ... }
+`;
+fs.writeFileSync('/path/to/target.js', content, 'utf8');
+console.log('写入完成，行数：', content.split('\n').length);
+```
+
+```bash
+node /tmp/content-payload.js
+wc -l /path/to/target.js   # 验证行数
+```
+
+## 核心原则
+
+1. **永远不要用 heredoc 写大文件** — 改用 `create_file` 工具创建临时 JS 脚本
+2. **永远不要用 PowerShell JSON 化大文件** — 禁止 `Get-Content -Raw <file> | ConvertTo-Json`、`ConvertFrom-Json` 处理 `.oyd.jsx/.jsx/.js` 页面源码
+3. **内容放在 JS 模板字符串里** — 支持任意长度，不受 shell 限制
+4. **写完立即验证** — `wc -l` 检查行数，`tail` 检查末尾内容
+5. **分段写入大文件** — 超过 300 行的内容，拆分为多个 `create_file` + `node` 执行
+6. **本技能不读写 memory**：文件写入为纯本地操作，不依赖跨会话的 memory 状态
+
+## 适用场景
+
+- 宜搭自定义页面代码（通常 500-1500 行）
+- Three.js 场景代码
+- 任何超过 100 行的代码文件写入
+- Windows 环境下写入/修补大 `.oyd.jsx` 页面源码
+
+## Windows / PowerShell 禁止模式
+
+不要为了转义或生成 patch，把大页面源码转换成 JSON 字符串：
+
+```powershell
+# 禁止：会整体读入并生成多份转义副本，可能瞬间占用几十 GB 内存
+Get-Content -Raw project\pages\src\vendor-section.oyd.jsx | ConvertTo-Json
+```
+
+正确做法是直接用 Node 写入目标文件；需要局部替换时，用 Node 读取后做精确字符串/AST 替换并直接 `fs.writeFileSync` 写回，不要额外包成 JSON patch。
+
+## 触发条件
+
+**正向触发**：
+- 需要写入超过 100 行的代码文件
+- 使用 heredoc 或 shell 命令写文件时出现内容截断
+- 写入宜搭自定义页面代码（通常 500-1500 行）
+
+**不适用场景（不要触发）**：
+- 文件内容少于 100 行 → 直接使用 `create_file` 工具
+- 二进制文件写入 → 不适用
+- 仅追加少量内容 → 直接使用 `create_file`
+
+## 异常处理
+
+| 问题 | 原因 | 处理方式 |
+|------|------|----------|
+| `node: command not found` | Node.js 未安装 | 先安装 Node.js ≥ 16 |
+| 脚本执行后文件为空 | 模板字符串语法错误 | 检查反引号是否闭合，特殊字符是否转义 |
+| 写入不完整 | 内容超过单次 create_file 限制 | 按「分段写入」方式拆分为多个脚本 |
+| 权限拒绝 | 目标路径无写权限 | 检查目录权限，或改用 `/tmp/` 路径 |

package/yida-skills/skills/large-file-write/references/write-patterns.md

@@ -0,0 +1,149 @@
+# 大文件写入模式参考
+
+本文档提供三种大文件写入模式的完整代码示例，供 AI Agent 直接参考使用。
+
+## 模式一：创建内容脚本后执行（推荐）
+
+适用于一次性写入大块内容（>100 行）。
+
+### Step 1：用 `create_file` 工具创建临时内容脚本
+
+```js
+// /tmp/content-payload.js
+const fs = require('fs');
+const content = `
+// 这里放你要写入的大块内容
+// 支持任意长度，不受 heredoc 限制
+export function myFunction() {
+  // ...
+}
+`;
+fs.writeFileSync('/path/to/target.js', content, 'utf8');
+console.log('写入完成，行数：', content.split('\n').length);
+```
+
+### Step 2：执行脚本
+
+```bash
+node /tmp/content-payload.js
+```
+
+### Step 3：验证写入结果
+
+```bash
+wc -l /path/to/target.js
+tail -5 /path/to/target.js
+```
+
+---
+
+## 模式二：追加内容到已有文件
+
+适用于向已有文件末尾追加大块内容。
+
+```js
+// /tmp/append-payload.js
+const fs = require('fs');
+const appendContent = `
+// 追加的内容
+export function additionalFunction() {
+  // ...
+}
+`;
+fs.appendFileSync('/path/to/target.js', appendContent, 'utf8');
+console.log('追加完成');
+```
+
+执行：
+
+```bash
+node /tmp/append-payload.js
+```
+
+---
+
+## 模式三：使用通用写入脚本（stdin 模式）
+
+适用于通过管道传入内容的场景。
+
+```bash
+node ~/.agents/skills/large-file-write/scripts/write.js \
+  --file /path/to/target.js \
+  --mode write   # 或 append
+```
+
+然后通过 stdin 输入内容（Ctrl+D 结束）。
+
+---
+
+## Windows / PowerShell 禁止模式
+
+**不要**用 PowerShell 把大 JSX/JS 文件转成 JSON patch：
+
+```powershell
+# 禁止：会把整个文件读入内存并生成转义后的大字符串
+Get-Content -Raw project\pages\src\vendor-section.oyd.jsx | ConvertTo-Json > vendor-patch.json
+```
+
+这种写法会同时持有原始源码、JSON 转义字符串、管道对象和输出缓冲。对包含 vendor、base64、压缩代码的 `.oyd.jsx` 文件，内存可能被放大到数十 GB。
+
+请改用 Node：
+
+```js
+const fs = require('fs');
+const target = 'project/pages/src/vendor-section.oyd.jsx';
+const source = fs.readFileSync(target, 'utf8');
+const next = source.replace('old snippet', 'new snippet');
+fs.writeFileSync(target, next, 'utf8');
+```
+
+如果替换内容很大，按下文“分段写入大文件”拆分。
+
+---
+
+## 分段写入大文件（>300 行）
+
+当单次内容超过 300 行时，拆分为多个脚本分段写入：
+
+```js
+// /tmp/part1-payload.js — 写入第一段（文件头 + 前半部分）
+const fs = require('fs');
+const part1 = `
+// === 第一段内容 ===
+const CONSTANTS = { ... };
+export function functionA() { ... }
+`;
+fs.writeFileSync('/path/to/target.js', part1, 'utf8');
+console.log('第一段写入完成');
+```
+
+```js
+// /tmp/part2-payload.js — 追加第二段
+const fs = require('fs');
+const part2 = `
+// === 第二段内容 ===
+export function functionB() { ... }
+export function functionC() { ... }
+`;
+fs.appendFileSync('/path/to/target.js', part2, 'utf8');
+console.log('第二段追加完成');
+```
+
+验证最终结果：
+
+```bash
+wc -l /path/to/target.js
+head -5 /path/to/target.js
+tail -5 /path/to/target.js
+```
+
+---
+
+## 常见错误与修复
+
+| 错误现象 | 原因 | 修复方式 |
+|---------|------|---------|
+| 文件为空 | 模板字符串反引号未闭合 | 检查 `` ` `` 是否成对，特殊字符是否转义 |
+| 内容截断 | 单次 create_file 超过 token 限制 | 拆分为多个脚本分段写入 |
+| 权限拒绝 | 目标路径无写权限 | 改用 `/tmp/` 路径，或检查目录权限 |
+| node 命令未找到 | Node.js 未安装 | 先安装 Node.js ≥ 16 |

package/yida-skills/skills/large-file-write/scripts/write.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * large-file-write - Node.js 大文件可靠写入工具
+ *
+ * 解决 AI Agent 模式下 heredoc / shell 命令写入大文件时内容被截断的问题。
+ *
+ * 用法：
+ *   node write.js --file <目标文件路径> [--mode write|append] [--encoding utf8]
+ *
+ * 内容来源（三选一）：
+ *   1. stdin：echo "content" | node write.js --file out.js
+ *   2. --content-file <临时内容文件>：node write.js --file out.js --content-file /tmp/content.txt
+ *   3. --payload <JS文件>：node write.js --payload /tmp/payload.js（payload 文件自行调用 fs 写入）
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// ─── 解析命令行参数 ───────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const key = argv[i];
+    if (key.startsWith('--')) {
+      const name = key.slice(2);
+      const value = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true;
+      args[name] = value;
+    }
+  }
+  return args;
+}
+
+const args = parseArgs(process.argv);
+
+// ─── 帮助信息 ─────────────────────────────────────────────────────────────────
+
+if (args.help || args.h) {
+  console.log(`
+large-file-write - 大文件可靠写入工具
+
+用法：
+  node write.js --file <目标路径> [选项]
+
+选项：
+  --file <path>          目标文件路径（必填，除非使用 --payload）
+  --mode <write|append>  写入模式，默认 write（覆盖）
+  --encoding <enc>       文件编码，默认 utf8
+  --content-file <path>  从指定文件读取内容后写入目标文件
+  --payload <path>       执行一个自包含的 JS 脚本（脚本内自行调用 fs 写入）
+  --verify               写入后输出行数和末尾5行进行验证
+  --help                 显示帮助
+
+示例：
+  # 从 stdin 写入
+  echo "hello world" | node write.js --file /tmp/out.txt
+
+  # 从内容文件写入
+  node write.js --file /tmp/out.js --content-file /tmp/content.txt --verify
+
+  # 执行自包含 payload 脚本
+  node write.js --payload /tmp/my-payload.js
+`);
+  process.exit(0);
+}
+
+// ─── 执行 payload 模式 ────────────────────────────────────────────────────────
+
+if (args.payload) {
+  const payloadPath = path.resolve(args.payload);
+  if (!fs.existsSync(payloadPath)) {
+    console.error(`❌ payload 文件不存在：${payloadPath}`);
+    process.exit(1);
+  }
+  console.log(`▶ 执行 payload：${payloadPath}`);
+  require(payloadPath);
+  process.exit(0);
+}
+
+// ─── 普通写入模式 ─────────────────────────────────────────────────────────────
+
+if (!args.file) {
+  console.error('❌ 缺少必填参数 --file <目标文件路径>');
+  console.error('   运行 node write.js --help 查看帮助');
+  process.exit(1);
+}
+
+const targetFile = path.resolve(args.file);
+const writeMode = args.mode === 'append' ? 'a' : 'w';
+const encoding = args.encoding || 'utf8';
+const shouldVerify = args.verify === true || args.verify === 'true';
+
+// 确保目标目录存在
+const targetDir = path.dirname(targetFile);
+if (!fs.existsSync(targetDir)) {
+  fs.mkdirSync(targetDir, { recursive: true });
+  console.log(`📁 已创建目录：${targetDir}`);
+}
+
+function writeContent(content) {
+  const flag = writeMode;
+  fs.writeFileSync(targetFile, content, { encoding, flag });
+
+  const totalLines = content.split('\n').length;
+  const actualLines = fs.readFileSync(targetFile, 'utf8').split('\n').length;
+  const modeLabel = flag === 'a' ? '追加' : '写入';
+
+  console.log(`✅ ${modeLabel}成功：${targetFile}`);
+  console.log(`   本次内容：${totalLines} 行 | 文件总行数：${actualLines} 行`);
+
+  if (shouldVerify) {
+    const lines = fs.readFileSync(targetFile, 'utf8').split('\n');
+    const tail = lines.slice(-5).join('\n');
+    console.log('\n📋 文件末尾 5 行：');
+    console.log('─'.repeat(50));
+    console.log(tail);
+    console.log('─'.repeat(50));
+  }
+}
+
+// ─── 从 --content-file 读取内容 ───────────────────────────────────────────────
+
+if (args['content-file']) {
+  const contentFilePath = path.resolve(args['content-file']);
+  if (!fs.existsSync(contentFilePath)) {
+    console.error(`❌ 内容文件不存在：${contentFilePath}`);
+    process.exit(1);
+  }
+  const content = fs.readFileSync(contentFilePath, encoding);
+  writeContent(content);
+  process.exit(0);
+}
+
+// ─── 从 stdin 读取内容 ────────────────────────────────────────────────────────
+
+const isTTY = process.stdin.isTTY;
+
+if (isTTY) {
+  console.log('📝 请输入内容（输入完成后按 Ctrl+D 结束）：');
+}
+
+const chunks = [];
+const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+
+rl.on('line', (line) => {
+  chunks.push(line);
+});
+
+rl.on('close', () => {
+  const content = chunks.join('\n');
+  if (!content.trim()) {
+    console.error('❌ 未接收到任何内容，请通过 stdin 或 --content-file 提供内容');
+    process.exit(1);
+  }
+  writeContent(content);
+});

package/yida-skills/skills/yida-data-management/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: yida-data-management
+description: 宜搭数据管理。表单实例/子表/流程实例/任务中心的查询、新增、更新。表单走 /v1/form/，流程走 /v1/process/，不能混用。
+---
+
+# 数据管理
+
+## 严格禁止 (NEVER DO)
+
+- 不要混用表单接口和流程接口，两套接口完全独立，参数和返回结构不同
+- 不要编造 formInstId 或 processInstanceId，必须从查询结果中提取
+- 不要用此命令修改表单结构（字段增删改），应使用 `yida-create-form-page`
+- **绝对禁止猜测或编造字段 ID（fieldId）**，宜搭字段 ID 由平台随机生成（如 `textField_eftt1aa5m`），无法预测，必须通过 `yidaconnector get-schema` 获取
+
+## 严格要求 (MUST DO)
+
+- 操作前先用 query 命令确认目标数据存在
+- 批量操作单次不超过 30 条记录
+- 删除数据前必须向用户展示操作摘要并获得明确确认
+- **录入/更新数据前，必须先执行 `yidaconnector get-schema` 获取真实字段 ID，并将字段 ID 映射记录到 `.cache/<项目名>-schema.json`**
+- **生成测试数据或录入/更新数据时，`DateField` / `CascadeDateField` 必须使用 13 位毫秒时间戳（如 `1719705600000`），不要传 `YYYY-MM-DD`、`YYYY-MM-DD HH:mm:ss` 或 ISO 字符串**
+- **录入数据后，必须执行 `yidaconnector data query` 抽查至少 1 条记录，确认 `formData` 中字段有实际值（非空），否则说明字段 ID 有误，需重新排查**
+- **读取子表明细超过 50 行时，必须使用 `yidaconnector data query subform` 或 `listTableDataByFormInstIdAndTableId` 分页查询完整子表；不要把 `searchFormDatas.currentPage` 当作子表分页**
+- **本技能不读写 memory**：数据操作通过 CLI 命令写入宜搭平台，不依赖跨会话的 memory 状态
+- 一次性造数、旧数据修正、字段迁移脚本可以使用 Python 或 JS，优先选择更快更清晰的实现；脚本、导入数据、查询条件文件必须放在 `.cache/yidaconnector/` 下，并复用真实查询到的 appType/formUuid/fieldId/formInstId
+- **禁止在仓库根目录生成导入用的 `*.json`、`*.js`、`*.py`、`*.csv` 临时文件**；推荐使用 `.cache/yidaconnector/data-import/` 存放数据文件，`.cache/yidaconnector/scripts/` 存放一次性执行脚本
+
+## 适用场景
+
+用户需要"查询数据"、"新增记录"、"更新数据"、"查看表单实例"、"发起流程"时使用。
+
+**关键区分**：
+- 操作表单数据记录（增删改查）→ 本技能
+- 修改表单结构（字段增删改）→ `yida-create-form-page`
+- 自定义页面调用连接器或外部 API 数据源 → `yida-data-source-connectors`
+- 表单接口（`/v1/form/`）vs 流程接口（`/v1/process/`）不能混用
+
+## 触发条件
+
+**正向触发**：
+- "查询数据"、"新增记录"、"更新数据"
+- "查看表单实例"、"发起流程"
+- "录入数据"、"批量导入"、"查询待办任务"
+
+**不适用场景（不要触发）**：
+- 修改表单结构（字段增删改）→ `yida-create-form-page`
+- 配置集成自动化 → `yida-integration`
+- 自定义页面接入 HTTP 连接器、第三方接口或外部系统数据 → `yida-data-source-connectors`
+- 获取字段 ID → `yida-get-schema`
+- 表单接口（`/v1/form/`）和流程接口（`/v1/process/`）不能混用
+
+## 危险操作确认
+
+删除数据记录为不可逆操作，执行前必须：
+1. 展示将删除的记录摘要（数量 + 关键字段）
+2. 等待用户明确确认
+3. 执行删除
+
+---
+
+
+> 表单与流程是两套独立接口，主键、参数、返回结构都不同，不能混用。
+
+## 命令
+
+### 表单实例
+
+```bash
+yidaconnector data query form <appType> <formUuid> [--page 1 --size 20] [--search-json '<json>'|--search-file .cache/yidaconnector/data-import/search.json] [--resolve-aliases]
+yidaconnector data get form <appType> --inst-id <formInstId>
+yidaconnector data create form <appType> <formUuid> --data-json '<json>' [--resolve-aliases]
+yidaconnector data create form <appType> <formUuid> --data-file .cache/yidaconnector/data-import/record.json [--resolve-aliases]
+yidaconnector data update form <appType> --inst-id <formInstId> --form-uuid <formUuid> --data-json '<json>' [--resolve-aliases]
+yidaconnector data update form <appType> --inst-id <formInstId> --form-uuid <formUuid> --data-file .cache/yidaconnector/data-import/patch.json [--resolve-aliases]
+yidaconnector data query subform <appType> <formUuid> --inst-id <formInstId> --table-field-id <fieldId|alias> [--page 1 --size 100] [--resolve-aliases]
+```
+
+当 JSON 使用宜搭组件别名作为 key 时，追加 `--resolve-aliases`，YidaConnector 会先读取表单 Schema 中的 `componentAlias.items`，再将别名转换为真实 `fieldId` 后调用数据接口。更新类命令若要解析别名，必须额外传 `--form-uuid <formUuid>`。
+
+### 子表超过 50 行
+
+当 `searchFormDatas` 或 `getFormDataById` 返回的 `formData.tableField_xxx` 刚好是 50 行时，优先判断为详情接口对子表内嵌数据做了截断，不要直接下结论为"没有更多数据"。
+
+正确处理流程：
+
+1. 先确认主记录的 `formInstId` 和子表真实 `tableFieldId`；如果只有别名，先执行 `yidaconnector get-schema` 或给 `query subform` 追加 `--resolve-aliases`。
+2. 使用 `yidaconnector data query subform <appType> <formUuid> --inst-id <formInstId> --table-field-id <tableFieldId> --page 1 --size 100` 查询子表第一页。
+3. 如果返回 `totalCount` 大于 `data.length`，继续按 `currentPage/pageSize` 翻页，或在脚本中复用 `listTableDataByFormInstIdAndTableId` 拉全量。
+4. 不要通过 DOM、虚拟滚动列表、页面全局变量抓取子表全量数据；这类方式依赖页面实现，不能作为稳定数据管理方案。
+
+注意：`searchFormDatas.currentPage` 分页的是主表实例列表，不是某条实例里的子表行。把 `currentPage` 改为 2 后返回空，只能说明主表第二页没有记录，不能证明子表不支持分页。
+
+不要把"创建自定义数据源"作为解决宜搭表单/子表 50 行截断的首选方案；只有在确实需要调用 HTTP 连接器、第三方接口或外部系统数据时，才切换到 `yida-data-source-connectors`。
+
+### 流程实例
+
+```bash
+yidaconnector data query process <appType> <formUuid> [--instance-status RUNNING] [--search-file .cache/yidaconnector/data-import/process-search.json] [--resolve-aliases]
+yidaconnector data get process <appType> --process-inst-id <processInstanceId>
+yidaconnector data create process <appType> <formUuid> --process-code <processCode> --data-json '<json>' [--resolve-aliases]
+yidaconnector data create process <appType> <formUuid> --process-code <processCode> --data-file .cache/yidaconnector/data-import/process-record.json [--resolve-aliases]
+yidaconnector data update process <appType> --process-inst-id <processInstanceId> --form-uuid <formUuid> --data-json '<json>' [--resolve-aliases]
+yidaconnector data update process <appType> --process-inst-id <processInstanceId> --form-uuid <formUuid> --data-file .cache/yidaconnector/data-import/process-patch.json [--resolve-aliases]
+yidaconnector data query operation-records <appType> --process-inst-id <processInstanceId>
+yidaconnector data execute task <appType> --task-id <taskId> --process-inst-id <processInstanceId> --out-result AGREE --remark '同意' [--data-file .cache/yidaconnector/data-import/task-data.json] [--form-uuid <formUuid>] [--resolve-aliases]
+```
+
+### 任务中心
+
+```bash
+yidaconnector data query tasks <appType> --type todo|done|submitted|cc [--page 1 --size 20]
+```
+
+## 接口总览
+
+### 表单实例
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `searchFormDatas` | GET | 查询列表 |
+| `searchFormDataIds` | GET | 查询 ID 列表 |
+| `getFormDataById` | GET | 查询详情 |
+| `saveFormData` | POST | 新增 |
+| `updateFormData` | POST | 更新 |
+| `listTableDataByFormInstIdAndTableId` | GET | 查询子表数据 |
+
+### 流程实例
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `startProcessInstance` | POST | 发起流程 |
+| `getInstanceIds` | GET | 查询 ID 列表 |
+| `getInstances` | GET | 查询列表 |
+| `getInstanceById` | GET | 查询详情 |
+| `updateInstance` | POST | 更新 |
+| `getOperationRecords` | GET | 审批记录 |
+| `executeTask` | POST | 执行任务 |
+
+### 任务中心
+
+| 接口 | 说明 |
+|------|------|
+| `getTodoTasksInApp` | 待办 |
+| `getDoneTasksInApp` | 已完成 |
+| `getMySubmitInApp` | 已提交 |
+| `getNotifyMeTasksInApp` | 抄送 |
+
+## 数据格式
+
+### 查询条件 `searchFieldJson`
+
+必须传**字符串**：
+
+```json
+[{"key":"textField_xxx","value":"测试","type":"TEXT","operator":"eq","componentName":"TextField"}]
+```
+
+### 保存/更新数据
+
+```json
+{"textField_xxx":"文本","numberField_xxx":10,"dateField_xxx":1719705600000,"employeeField_xxx":["userId"]}
+```
+
+当 JSON 较长或用于批量导入时，写入 `.cache/yidaconnector/data-import/<name>.json`，再使用 `--data-file` 或 `--search-file`；不要为了拼接命令在仓库根目录生成临时脚本。
+
+### 常见字段格式
+
+| 组件类型 | 查询格式 | 保存格式 |
+|---------|---------|----------|
+| 文本 | `"文本"` | `"文本"` |
+| 数字 | `["1","10"]` 或单值 | `1` |
+| 单选 | `"选项一"` | `"选项一"` |
+| 多选 | `["选项一"]` | `["选项一","选项二"]` |
+| 日期 | `[开始毫秒时间戳,结束毫秒时间戳]` | `13 位毫秒时间戳` |
+| 成员 | `["userId"]` | `["userId"]` |
+| 部门 | `["deptId"]` | `["deptId"]` |
+| 子表 | `"模糊搜索"` | `[{"textField_xxx":"值"}]` |
+| 关联表单 | 不支持直接查询 | `[{"appType":"xxx","formUuid":"xxx","instanceId":"xxx"}]` |
+
+### 日期字段写入约定
+
+- `DateField` 保存/更新值必须是 13 位毫秒时间戳，例如 `1719705600000`。
+- `CascadeDateField` 保存/更新值必须是毫秒时间戳数组，例如 `[1719705600000,1722384000000]`。
+- 生成测试数据时，先用 `new Date('2024-06-30T00:00:00+08:00').getTime()` 或等价方式转换，不要直接写 `"2024-06-30"`。
+- 日期字符串可能导致保存失败、字段为空，或后续报表/筛选异常。
+
+```bash
+yidaconnector data create form APP_xxx FORM-xxx --data-json '{
+  "textField_xxx": "测试记录",
+  "dateField_xxx": 1719705600000,
+  "cascadeDateField_xxx": [1719705600000,1722384000000]
+}'
+```
+
+### 关联表单字段
+
+关联表单字段保存时必须使用数组对象格式，包含三个必填字段：
+
+```bash
+# 示例：创建带关联客户的商机
+yidaconnector data create form APP_xxx FORM-商机表 --data-json '{
+  "textField_xxx": "商机名称",
+  "associationFormField_xxx": [{"appType":"APP_xxx","formUuid":"FORM-客户表","instanceId":"FINST-xxx"}]
+}'
+```
+
+> 注意：字段名是 `instanceId`（不是 formInstId），三个字段缺一不可
+
+
+## 代码示例
+
+> 需要参考表单字段定义和数据插入写法时，执行以下命令获取示例，再用 `read_file` 读取：
+
+```bash
+yidaconnector sample yida-data-management form-field-template   # 表单字段定义模板（字段类型/必填/选项配置）及数据插入示例
+```
+
+## 注意事项
+
+- `pageSize` 最大 100，QPS 限制约 40 次/秒
+- `searchFieldJson` 和 `dynamicOrder` 必须传字符串
+- 字段 ID 通过 `yidaconnector get-schema` 获取，不要手写猜测
+- 批量脚本可以用 Python `subprocess` 调用 `yidaconnector data ...`，也可以用 JS 复用 Node 工具；脚本必须放在 `.cache/yidaconnector/scripts/`，导入数据放在 `.cache/yidaconnector/data-import/`
+
+## 异常处理
+
+| 异常场景 | 处理方式 |
+|---------|----------|
+| 查询返回空结果 | 确认 formUuid 正确，检查查询条件是否过于严格 |
+| 子表只返回 50 行 | 不要翻 `searchFormDatas.currentPage`；使用 `query subform` / `listTableDataByFormInstIdAndTableId` 按 `formInstId + tableFieldId` 分页查询 |
+| 新增数据后字段值为空 | 字段 ID 有误，先执行 `yidaconnector get-schema` 获取真实 fieldId |
+| 更新失败（formInstId 不存在） | 先用 query 命令确认记录存在，不要猜测 formInstId |
+| 接口返回 401/未登录 | 执行 `yidaconnector login` 重新登录 |
+| QPS 超限（429） | 降低请求频率，批量操作单次不超过 30 条 |
+| 删除操作误删 | 删除前必须展示操作摘要并获得用户明确确认，不可逆操作 |
+| 流程接口用了表单接口路径 | 检查接口路径：表单用 `/v1/form/`，流程用 `/v1/process/` |
+
+## Agent 错误处理策略
+
+当 Agent 执行本技能遇到错误时，必须遵循以下默认行为：
+
+| 错误类型 | 默认处理策略 |
+|---------|-------------|
+| 命令执行失败 | 停止执行，向用户展示错误信息，询问是否重试或调整参数 |
+| 参数缺失（appType/formUuid/fieldId 等） | 主动询问用户补充，或引导用户使用 `yida-get-schema` 获取 |
+| 权限不足 / 登录态失效 | 停止执行，提示用户执行 `yidaconnector login` 重新登录 |
+| 字段 ID 无效 | 停止执行，引导用户执行 `yidaconnector get-schema` 获取真实字段 ID |
+| 删除操作前 | 必须先展示操作摘要（数量 + 关键字段），等待用户明确确认 |
+| QPS 超限 | 降低请求频率，单次批量操作不超过 30 条，间隔 1 秒重试 |
+| 表单/流程接口混用 | 停止执行，提示用户检查接口类型（表单用 `/v1/form/`，流程用 `/v1/process/`） |
+| 网络超时 | 重试 1 次，仍失败则停止并提示用户检查网络 |
+| 未知错误 | 停止执行，完整展示错误信息，建议用户反馈问题 |