@lark-apaas/coding-steering 0.1.6-alpha.1 → 0.1.6-alpha.11

package/steering/nestjs-react-fullstack/skills/devops-guide/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: devops-guide
+description: "Use when user needs build, deploy, run, troubleshoot, or operate a miaoda fullstack app. IMPORTANT: Only activate this skill when the user explicitly asks about deployment, build failures, or service operations. Do NOT proactively trigger this skill during normal code development — reading devops skills to troubleshoot preemptively disrupts the development workflow. Only use when: build fails, deploy fails, service crashes, or user explicitly asks about ops issues. 触发词：devops, 构建, 部署, 运维, 日志, 启动失败, 编译失败, 服务异常, read_logs, pkill, ps, pstree"
+steering: true
+steering-topic: devops
+match-template-name: nestjs-react-fullstack
+control-by-feature-ab: true
+---
+
+# DevOps Guide
+
+用于处理妙搭全栈应用的构建、部署、运行排障。
+
+核心原则：**先检查，再验证，再看日志，最后才下结论**。
+
+## Quick Reference
+
+| 场景 | 必做动作 | 结果标准 |
+|------|----------|----------|
+| 修改代码后自检 | 先跑代码检查工具 | 无语法错误、无类型错误、无明显构建错误 |
+| 修改服务端代码 | 补跑接口测试 | 每个新增接口都能验证通过 |
+| 准备交付前 | 读取最新日志 | 最新改动后无错误日志 |
+| 用户反馈编译失败 | 查 lint/typecheck + devServer 日志 | 定位到具体文件、具体报错 |
+| 用户反馈服务无响应 | 查日志 + 查进程状态 | 确认是代码报错还是 dev 进程卡死 |
+
+## Step 1：先判断问题类型
+
+### A. 代码改完后的质量保障
+
+按固定顺序执行：
+
+1. 运行代码检查工具，优先发现语法、类型、样式问题。
+2. 若改了服务端代码，执行接口测试，覆盖新增接口。
+3. 最后读取日志，确认最新改动没有引入错误日志。
+
+### B. 编译失败 / 服务启动失败 / 页面异常
+
+按定位顺序执行：
+
+1. 先查代码检查结果。
+2. 再查 devServer 日志。
+3. 必要时检查进程状态，判断 dev 进程是否失活。
+
+## Step 2：根据改动范围读取正确日志
+
+| 改动范围 | 必读日志 |
+|----------|----------|
+| 服务端代码 | `server`、`server-devserver` |
+| 客户端代码 | `client-devserver` |
+| 编译失败但范围不清楚 | `server-devserver` + `client-devserver` |
+| 请求报错 | `server`，必要时补 `trace` |
+
+规则：
+
+- **不要只看一个日志源**。
+- **不要基于旧日志下结论**，要读取最新日志。
+- 日志为空不代表没问题，先确认对应服务是否真的在运行。
+
+## Step 3：devServer 无响应时的 SOP
+
+若你发现代码已经修改，但 dev 日志长时间不更新，优先怀疑 dev 进程失活。
+
+### 检查顺序
+
+1. 用 `ps` / `pgrep` / `pstree` 确认 `dev:server`、`dev:client` 相关进程是否存在。
+2. 若进程存在但日志不更新，先把现象记录为结论，不要直接重启环境。
+3. 只有调用方明确要求时，才执行 `pkill -f "dev:server"` 或 `pkill -f "dev:client"`。
+
+### 推荐命令
+
+```bash
+ps -ef | grep "dev:server"
+ps -ef | grep "dev:client"
+pgrep -af "dev:server"
+pgrep -af "dev:client"
+pstree -p <pid>
+pkill -f "dev:server"
+pkill -f "dev:client"
+```
+
+### 判断标准
+
+- 有进程、日志持续刷新：devServer 正常，继续排查代码问题。
+- 有进程、日志不刷新：高概率卡死，先报告现象和证据。
+- 没进程：说明服务未拉起，先看最近一次 devServer 错误日志。
+
+## Step 4：构建 / 部署 / 运维排查框架
+
+按照 **现象 → 根因 → 方案** 输出。
+
+### 常见现象映射
+
+| 现象 | 高概率根因 | 优先方案 |
+|------|------------|----------|
+| 编译失败 | 语法错误、类型错误、依赖误用 | 先跑 lint / typecheck，再看 devServer 日志 |
+| 后端启动失败 | Nest 模块注册错误、配置错误、运行时异常 | 查 `server-devserver` 和 `server` |
+| 页面白屏 | 前端编译错误、运行时异常、接口异常 | 查 `client-devserver`，必要时补 `browser` |
+| 接口 500 | 服务端业务异常 | 查 `server` / `trace`，补接口测试 |
+| 热更新失效 | dev 进程卡死 | 查进程状态，不要默认重启 |
+
+## 交付要求
+
+输出排查结果时，必须包含：
+
+1. **现象**：用户看到什么错误。
+2. **根因**：定位到哪一层出问题。
+3. **证据**：哪条日志、哪段报错、哪个检查结果支撑结论。
+4. **方案**：下一步修复动作。
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| 改完代码直接说“没问题” | 先跑代码检查，再读日志 |
+| 服务端改动后不测接口 | 必须验证新增接口 |
+| 只看 `server` 不看 `server-devserver` | 服务端至少看两个日志源 |
+| 发现无响应就直接 `pkill` | 先用 `ps` / `pgrep` / `pstree` 定位，再报告结论 |
+| `pkill` 后不复读日志 | 只有明确要求重启时才执行，并再次读日志确认 |
+| 只给结论不给证据 | 必须给日志或检查结果作为依据 |

package/steering/nestjs-react-fullstack/skills/feishu/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: feishu
+description: Use when integrating with Feishu (飞书) or Lark Open Platform using @larksuiteoapi/node-sdk in NestJS/TypeScript, including converting miaoda userId ↔ Feishu open_id / union_id / employee_id via spark id_convert. 触发词：飞书, Feishu, Lark, 飞书开放平台, 飞书SDK, 飞书机器人, 飞书消息, 飞书日历, 飞书审批, 多维表格, 飞书通讯录, 飞书考勤, 飞书文档, 云文档, 飞书云空间, 飞书知识库, open_id, union_id, employee_id, 飞书open_id, 飞书union_id, 飞书employee_id, open_id转换, union_id转换, 妙搭飞书ID互转, 妙搭userId转open_id, open_id反查妙搭, spark id_convert, id_convert
+---
+
+# Feishu Node SDK — NestJS/TypeScript 集成指南
+
+使用 `@larksuiteoapi/node-sdk` 在 NestJS/TypeScript 项目中集成飞书开放平台。
+
+## 集成工作流
+
+**在写任何飞书代码之前，必须按顺序走完以下步骤：**
+
+```
+Step 1: 检查项目现状
+  ├─ 检查 package.json 是否有 @larksuiteoapi/node-sdk
+  ├─ 检查是否有 FeishuService / FeishuModule
+  └─ 检查 FeishuService 是否已有凭证（appId 非占位符）
+
+  ↓ 已有凭证（FeishuService 已配置）→ 跳到 Step 4
+  ↓ 没有 → Step 2
+
+Step 2: 引导用户创建飞书自建应用
+  - 向用户发送以下完整操作清单（假设用户对飞书开放平台不熟悉）：
+
+      1. 打开 https://open.feishu.cn/app → 点击「创建企业自建应用」
+      2. 进入应用 →「凭证与基础信息」页面 → 复制 App ID 和 App Secret
+      3. 「添加应用能力」→ 开启「机器人」（发消息必须）
+      4. 「权限管理」→ 申请以下权限：[根据用户需求列出具体权限，见"常用场景所需权限"表]
+      5. 「版本管理与发布」→ 创建版本 → 提交审核（企业管理员审核通过后应用生效）
+
+  - 清单发送完毕后，补充说明：
+      「完成以上步骤后，请将 App ID 和 App Secret 发给我，我来帮你写代码。」
+
+  - 等待用户提供真实凭证，**不要使用占位符生成代码**
+
+Step 3: 确认权限 + 保存凭证
+  - 根据用户需求告知需申请的权限（见"常用场景所需权限"表）
+  - 将凭证写入 FeishuService 源码常量（见"NestJS 模块设置"）
+  - 将 App ID 和用途写入 agent.md（见"飞书应用信息持久化"模板）
+
+Step 4: 安装依赖
+  - npm install @larksuiteoapi/node-sdk
+
+Step 5: 编写代码
+  - 创建 FeishuService（将凭证写入模块顶部常量）
+  - 创建 FeishuModule
+```
+
+## 代码生成约束
+
+- 所有飞书 API 调用必须放在 NestJS `@Injectable()` Service 的方法中
+- `client` 始终通过 `this.client`（FeishuService 内部）或 `this.feishuService.getClient()`（其他 Service）获取
+- 数据库操作使用 Drizzle ORM 注入实例（`@Inject(DRIZZLE_DATABASE)`），不使用裸 SQL 或自建连接
+- 禁止生成独立运行的 `.ts` 脚本文件
+
+> reference 文件中的代码示例省略了 Service 类包裹，实际使用时 `client` 应替换为 `this.client` 或从注入的 FeishuService 获取。
+
+## 插件优先原则
+
+以下飞书能力存在**平台一方插件**，优先使用插件，不要直接用 node-sdk：
+
+| 需求 | 应使用 | 说明 |
+|------|--------|------|
+| 发送飞书文本/富文本消息 | **插件**（参考 `plugin_guide`） | 插件在 Client 侧调用，无需后端 Service |
+| **发送飞书消息卡片** | **node-sdk**（本文档） | 插件不支持卡片消息，必须用 node-sdk |
+| 飞书多维表格增删改查 | **插件**（参考 `plugin_guide`） | 同上 |
+| 创建飞书群组 | **插件**（参考 `plugin_guide`） | 同上 |
+
+> **操作步骤（插件）**：先调用 `plugin_guide` 查询候选插件实例 → 调用 `get_plugin_ai_json` 获取 schema → 按文档生成 Client 侧调用代码。
+
+以下能力**无对应插件**，使用本文档的 node-sdk 方案：
+消息卡片、日历、审批、云文档、云空间、知识库、权限管理、通讯录、考勤、事件订阅、OAuth 授权。
+
+## Quick Reference
+
+| 模块 | 参考文件 | 简介 |
+|------|----------|------|
+| 消息 | `references/messaging.md` | 发送文本/富文本消息优先用插件；**卡片消息**用 node-sdk |
+| 日历 | `references/calendar.md` | 日程创建/查询/会议室 |
+| 审批 | `references/approval.md` | 审批流创建/查询/同意/拒绝 |
+| 多维表格 | `references/bitable.md` | 表格/记录/字段 CRUD ⚠️ 优先用插件 |
+| 云文档 | `references/doc.md` | 文档创建/Block 读写 |
+| 云空间 | `references/drive.md` | 文件夹/文件上传下载 |
+| 知识库 | `references/wiki.md` | 知识空间/节点管理 |
+| 权限管理 | `references/perm.md` | 文档协作者权限设置 |
+| 通讯录 | `references/contacts.md` | 用户/部门信息查询 |
+| 飞书妙搭 | `references/id-convert.md` | 妙搭与飞书开放平台用户 ID 互转 |
+| 考勤 | `references/attendance.md` | 打卡记录/考勤规则查询 |
+| 事件订阅 | `references/events.md` | WebSocket 长连接接收事件 |
+| OAuth 授权 | `references/oauth.md` | user_access_token 授权 |
+
+> 按需读取 `references/` 下的模块文档获取详细 API 用法和代码示例。
+
+## 飞书应用创建指南
+
+1. 打开 [飞书开发者后台](https://open.feishu.cn/app) → 创建企业自建应用
+2. 进入「凭证与基础信息」页面，复制 **App ID** 和 **App Secret** 发给开发者
+3. 添加应用能力 → 开启**机器人**（发消息必需）
+4. 权限管理 → 申请对应模块的 API 权限（见下方权限映射表）
+5. 安全设置 → 配置**通讯录权限范围**（使用通讯录/考勤 API 必需，设为「全部成员」或指定部门）
+6. 可用范围 → 添加需要使用该应用的人员或部门（默认仅创建者可用）
+7. 版本管理与发布 → 创建版本 → 提交管理员审核
+8. 对于已有文档/多维表格/知识库：需要将应用机器人添加为文档协作者（否则 API 无权访问）
+
+### 常用场景所需权限
+
+| 用户需求 | 需要申请的权限 | 额外要求 |
+|----------|---------------|----------|
+| 发送消息 | `im:message:send_as_bot` | 开启机器人能力 |
+| 读写文档 | `docx:document` | 机器人需为文档协作者 |
+| Markdown 转文档 | `docx:document` + `docx:document.block:convert` | — |
+| 读写多维表格 | `bitable:app` | 机器人需为表格协作者 |
+| 管理知识库 | `wiki:wiki` | 机器人需为知识空间成员 |
+| 文件上传下载 | `drive:drive` | — |
+| 文档权限管理 | `drive:permission` | — |
+| 日历日程 | `calendar:calendar` | — |
+| 审批流操作 | `approval:approval` + `approval:task` | — |
+| 查询通讯录 | `contact:contact.base:readonly` | 配置通讯录权限范围 |
+| 妙搭↔飞书用户 ID 转换 | `获取 ID 转换信息`（spark 权限） | — |
+| 查询考勤 | `attendance:task:readonly` | 配置通讯录权限范围 |
+| 事件订阅 | 对应事件的订阅权限 | 需在开发者后台配置「使用长连接接收事件/回调」 |
+| 卡片交互回调 | `card:action.trigger` | 开启长连接订阅方式，订阅 card.action.trigger 回调 |
+
+### 飞书应用信息持久化
+
+引导用户完成应用配置后，将 App ID 和项目的飞书用途写入 `agent.md`，供后续会话判断是否需要重新引导：
+
+```markdown
+## 飞书集成
+
+- **App ID**: cli_xxxxxxxxxxxxxxxx
+- **用途**: 通过飞书 API 实现消息通知、文档自动生成（描述项目实际使用飞书做了什么）
+```
+
+## NestJS 模块设置
+
+### 安装 SDK
+
+```bash
+npm install @larksuiteoapi/node-sdk
+```
+
+### FeishuService 单例
+
+> ⚠️ **凭证写入源码**：全栈框架不支持自定义环境变量，因此 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 必须直接写在源码常量中，**不要改为 `process.env`**。
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import * as lark from '@larksuiteoapi/node-sdk';
+
+const FEISHU_APP_ID = 'cli_xxxx';      // ← 用户提供的真实值
+const FEISHU_APP_SECRET = 'xxxx';      // ← 用户提供的真实值
+
+@Injectable()
+export class FeishuService {
+  private readonly client: lark.Client;
+
+  constructor() {
+    this.client = new lark.Client({
+      appId: FEISHU_APP_ID,
+      appSecret: FEISHU_APP_SECRET,
+      appType: lark.AppType.SelfBuild,
+      domain: lark.Domain.Feishu,
+    });
+  }
+
+  getClient(): lark.Client {
+    return this.client;
+  }
+}
+```
+
+在 Module 中注册为全局 provider：
+
+```typescript
+@Module({
+  providers: [FeishuService],
+  exports: [FeishuService],
+})
+export class FeishuModule {}
+```
+
+## 核心 API 调用模式
+
+### 语义化调用
+
+```typescript
+// 调用模式: client.<domain>.<resource>.<method>({ params, data, path })
+const res = await client.im.message.create({
+  params: { receive_id_type: 'chat_id' },
+  data: {
+    receive_id: 'oc_xxx',
+    content: JSON.stringify({ text: 'hello' }),
+    msg_type: 'text',
+  },
+});
+
+// 检查返回值
+if (res.code !== 0) {
+  throw new Error(`Feishu API error [${res.code}]: ${res.msg}`);
+}
+```
+
+### 分页迭代器
+
+接口名后缀加 `WithIterator` 自动处理 page_token：
+
+```typescript
+for await (const items of await client.contact.user.listWithIterator({
+  params: { department_id: '0', page_size: 50 },
+})) {
+  console.log(items);
+}
+```
+
+## 错误处理与权限诊断
+
+> **排查优先级**：遇到 API 调用失败或配置问题时，先查阅对应 `references/` 文件顶部的开放平台文档链接，获取最新的参数说明、权限要求和错误码解释，再对照下方速查表定位问题。
+
+### 常见错误码
+
+| 错误码 | 含义 | 修复方法 |
+|--------|------|----------|
+| 99991672 | 权限不足 | 开发者后台 → 权限管理 → 申请对应权限 |
+| 99991671 | access_token 无效/过期 | 检查 app_id/app_secret 是否正确 |
+| 99991663 | tenant_access_token 过期 | SDK 自动刷新，检查网络连接 |
+| 230001 | 应用不可见/未安装 | 管理员审核发布应用 |
+| 99991400 | 参数错误 | 检查必填字段和参数类型 |
+| 99991668 | 用户不在通讯录权限范围 | 安全设置 → 通讯录权限范围设为「全部成员」 |
+
+### 权限速查
+
+遇到 `99991672 Permission denied` 时，根据 API 域查找所需权限：
+
+| API 域 | 权限标识 | 说明 |
+|--------|----------|------|
+| `im.message.*` | `im:message:send_as_bot` | 发送消息 |
+| `calendar.calendarEvent.*` | `calendar:calendar` | 日历日程读写 |
+| `vc.room.*` | `vc:room:readonly` | 会议室查询 |
+| `approval.approval.*` | `approval:approval` | 审批信息读写 |
+| `approval.instance.query` | `approval:approval.list:readonly` | 审批实例列表 |
+| `approval.task.*` | `approval:task` | 审批操作（同意/拒绝/转交） |
+| `bitable.app*` | `bitable:app` | 多维表格读写 |
+| `docx.document.*` | `docx:document` | 云文档读写 |
+| `docx.document.convert()` | `docx:document.block:convert` | Markdown 转 Block |
+| `drive.*` | `drive:drive` | 云空间文件/文件夹 |
+| `wiki.space.*` / `wiki.spaceNode.*` | `wiki:wiki` | 知识库读写 |
+| `drive.permissionMember.*` | `drive:permission` | 文档权限管理 |
+| `contact.user.*` | `contact:contact.base:readonly` | 通讯录用户信息 |
+| `contact.department.*` | `contact:department.base:readonly` | 部门信息 |
+| `contact.user.*.employee_id` | `contact:user.employee_id:readonly` | 用户 employee_id |
+| `attendance.userTask.*` | `attendance:task:readonly` | 打卡数据 |
+| `attendance.group.*` | `attendance:rule:readonly` | 考勤规则 |
+| `spark.directory.user.id_convert` | `获取 ID 转换信息` | 妙搭 userId ↔ 飞书 open_id/union_id；nestjs-react-fullstack 项目内优先用 `AuthNPaasService`（见 user-identity skill） |
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| 将凭证改为 process.env 读取 | 全栈框架不支持自定义环境变量，凭证必须写入源码常量 |
+| `content` 传对象而非 JSON 字符串 | `content: JSON.stringify({ text: 'hello' })` |
+| 每次请求都新建 `lark.Client` | NestJS `@Injectable()` 单例模式复用 |
+| `receive_id_type` 与 ID 前缀不匹配 | `oc_` → `chat_id`, `ou_` → `open_id`, `on_` → `union_id` |
+| 未配置通讯录权限范围 | 安全设置 → 通讯录权限范围 → 全部成员 |
+| 应用未发布直接调 API | 创建版本 → 管理员审核 → 发布后才能使用 |
+| 忘记开启机器人能力 | 应用能力 → 添加机器人（发消息必须） |
+| 日期格式搞混 | 日历用 RFC3339 (`2026-01-01T09:00:00+08:00`)，考勤用整数 (`20260101`) |
+| 生成独立可运行的脚本文件 | 所有飞书调用放在 NestJS Service 方法中，由 Controller 调用 |
+

package/steering/nestjs-react-fullstack/skills/feishu/references/approval.md

@@ -0,0 +1,214 @@
+# 审批 (Approval)
+
+> 开放平台文档（Markdown 版）：https://open.larkoffice.com/document/server-docs/approval-v4/approval-overview.md
+
+使用 `@larksuiteoapi/node-sdk` 在 NestJS 中管理飞书审批流程。
+
+## 所需权限
+
+| 权限标识 | 说明 |
+|----------|------|
+| `approval:approval` | 读写审批信息 |
+| `approval:approval.list:readonly` | 查询审批实例列表 |
+| `approval:task` | 审批人操作（同意/拒绝/转交、查询任务） |
+
+## 获取 Approval Code
+
+飞书不提供「列出所有审批定义」的 API，需从管理后台手动获取：
+
+1. 打开 [飞书审批管理后台（开发者模式）](https://www.feishu.cn/approval/admin/approvalList?devMode=on)
+2. 找到目标审批 → 点击 **编辑**
+3. 从浏览器地址栏复制 `definitionCode=` 后面的值
+   - 示例：`https://www.feishu.cn/approval/admin/edit?definitionCode=48D49517-C979-447E-AD93-4BAE0FBC57EA`
+4. 获取到的 Code 即为 `approval_code`
+
+## 获取审批定义
+
+查看审批表单结构，了解需要填写哪些字段：
+
+```typescript
+const definition = await client.approval.approval.get({
+  path: { approval_code: '48D49517-C979-447E-AD93-4BAE0FBC57EA' },
+});
+// definition.data?.form — 表单控件 JSON 字符串
+// definition.data?.node_list — 审批节点列表
+```
+
+## 创建审批实例
+
+```typescript
+const instance = await client.approval.instance.create({
+  data: {
+    approval_code: '48D49517-C979-447E-AD93-4BAE0FBC57EA',
+    open_id: 'ou_xxx', // 发起人
+    form: JSON.stringify([
+      {
+        id: 'widget001',
+        type: 'input',
+        value: '出差事由：参加客户交流会',
+      },
+      {
+        id: 'widget002',
+        type: 'date',
+        value: '2026-03-01T09:00:00+08:00',
+      },
+    ]),
+    // department_id: 'od_xxx', // 多部门用户需填写
+  },
+});
+const instanceCode = instance.data?.instance_code;
+```
+
+## 获取审批详情
+
+```typescript
+const detail = await client.approval.instance.get({
+  path: { instance_id: instanceCode },
+});
+// detail.data?.status — PENDING / APPROVED / REJECTED / CANCELED
+// detail.data?.form — 表单数据
+// detail.data?.task_list — 任务列表
+// detail.data?.timeline — 审批动态
+```
+
+## 查询审批实例列表
+
+```typescript
+const list = await client.approval.instance.query({
+  data: {
+    approval_code: '48D49517-...',
+    instance_status: 'PENDING', // PENDING / APPROVED / REJECT / RECALL / ALL
+    // user_id: 'ou_xxx', // 按发起人过滤
+    // start_time: '1708300800000', // Unix 毫秒时间戳
+    // end_time: '1708387200000',
+    page_size: 20,
+  },
+});
+```
+
+## 撤回审批
+
+```typescript
+await client.approval.instance.cancel({
+  data: {
+    approval_code: '48D49517-...',
+    instance_code: instanceCode,
+    user_id: 'ou_xxx', // 审批提交人
+  },
+});
+```
+
+> 撤回需要在审批后台对应审批定义中勾选「允许撤销审批中的申请」或「允许撤销 x 天内通过的审批」。
+
+## 查询审批人待办任务
+
+```typescript
+const tasks = await client.approval.task.search({
+  data: {
+    user_id: 'ou_xxx', // 审批人 open_id
+    approval_code: '48D49517-...', // 可选
+    task_status: 'PENDING', // PENDING / APPROVED / REJECTED / TRANSFERRED
+    page_size: 10,
+  },
+  params: { user_id_type: 'open_id' },
+});
+```
+
+也可以通过 `query` 方法查询任务：
+
+```typescript
+const taskQuery = await client.approval.task.query({
+  params: {
+    page_size: 20,
+    // page_token: '...',
+  },
+  data: {
+    topic: 'pending', // pending / approved / rejected
+    user_id: 'ou_xxx',
+  },
+});
+```
+
+## 同意审批
+
+```typescript
+await client.approval.task.approve({
+  data: {
+    approval_code: '48D49517-...',
+    instance_code: instanceCode,
+    user_id: 'ou_xxx', // 审批人
+    task_id: '7605931414537653476',
+    comment: '同意，请注意安全',
+    // form: '...', // 部分审批需要补充表单
+  },
+});
+```
+
+## 拒绝审批
+
+```typescript
+await client.approval.task.reject({
+  data: {
+    approval_code: '48D49517-...',
+    instance_code: instanceCode,
+    user_id: 'ou_xxx',
+    task_id: '7605931414537653476',
+    comment: '时间冲突，建议改期',
+  },
+});
+```
+
+## 转交审批
+
+```typescript
+await client.approval.task.transfer({
+  data: {
+    approval_code: '48D49517-...',
+    instance_code: instanceCode,
+    user_id: 'ou_xxx', // 当前审批人
+    task_id: '7605931414537653476',
+    comment: '转交给主管处理',
+    transfer_user_id: 'ou_yyy', // 转交目标
+  },
+});
+```
+
+## 常见表单控件类型
+
+| 控件类型 | 说明 | value 格式 |
+|----------|------|------------|
+| `input` | 单行文本 | `"文本内容"` |
+| `textarea` | 多行文本 | `"文本内容"` |
+| `number` | 数字 | `123.45` |
+| `date` | 日期 | `"2026-02-12T09:00:00+08:00"` (RFC3339) |
+| `leaveGroup` | 请假控件组 | `{"name":"年假","start":"...","end":"...","interval":2.0}` |
+| `remedyGroupV2` | 补卡控件组 | `[{"date":"2026-02-12","remedy_time":"...","reason":"..."}]` |
+| `tripGroup` | 出差控件组 | `{"schedule":[...],"interval":2.0,"reason":"..."}` |
+| `radioV2` | 单选 | `"选项名称"` |
+| `checkboxV2` | 多选 | `["选项1","选项2"]` |
+| `attachmentV2` | 附件 | 附件 token 列表 |
+
+## 典型工作流
+
+### 发起审批（发起人视角）
+
+1. 获取 approval_code（管理后台或预配置）
+2. `client.approval.approval.get()` → 查看表单结构
+3. 组装 form JSON → `client.approval.instance.create()` 发起审批
+4. `client.approval.instance.get()` → 查询审批状态
+
+### 处理审批（审批人视角）
+
+1. `client.approval.task.search({ data: { user_id, task_status: 'PENDING' } })` → 获取待办
+2. 根据标题/申请人匹配目标任务 → 拿到 `task_id` 和 `instance_code`
+3. `client.approval.task.approve()` 同意 / `reject()` 拒绝 / `transfer()` 转交
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+|------|----------|
+| 想用 API 列出所有审批定义 | 无此 API，从管理后台获取 approval_code |
+| form 传对象而非 JSON 字符串 | `form: JSON.stringify([{id, type, value}])` |
+| 忘记传 `task_id` 执行同意/拒绝 | 先通过 `task.search()` 获取 task_id |
+| 撤回失败 | 检查审批定义是否允许撤回 |
+| `instance_status` 拼写 | `REJECT`（不是 `REJECTED`），`RECALL`（不是 `CANCELED`） |