@lark-apaas/coding-steering 0.1.0-alpha.1 → 0.1.1

package/steering/vite-react/skills/plugin-guide/references/table.md

@@ -0,0 +1,501 @@
+# 飞书多维表格 (feishu-bitable)
+
+本插件提供了一整套与飞书多维表格进行交互（CRUD + 聚合查询）的接口。
+
+## 开发者注意事项
+
+**本文档是为 妙搭助手 设计的技术指南。**
+
+在查看本插件的 Action 时，你将同时获得两部分信息：
+
+1. **本文档 (README)**: 提供高级指引、业务逻辑、使用场景、重要约束。
+2. **Action 的 `inputSchema` 和 `outputSchema`**: 提供精确的 JSON Schema 格式的输入/输出结构。
+
+**请遵循以下原则：**
+
+- **以 `Schema` 为结构基准**：严格按照 `inputSchema` 构建你的输入对象，并参照 `outputSchema` 解析返回结果。
+- **以 `README` 为语义权威**：`README` 中的描述包含了 `Schema` 无法表达的关键信息。**必须优先遵循 `README` 中的指引和约束。**
+
+---
+
+## 重要提醒
+
+**禁止修改插件配置中的任何字段！即使出现字段类型错误或 Action 执行错误也不能修改。**
+
+使用前需读取配置中的 `fields` 字段，了解可操作的字段及其 `bizType`。
+
+## 字段使用规范
+
+1. **使用字段名称而非 ID**：所有操作必须使用 `fields.name`（字段名称），禁止使用字段 ID
+
+2. **选项字段必须严格匹配 enumValues**：`SingleSelect` 和 `MultiSelect` 类型的选项值必须完全参考配置中的 `enumValues`，禁止自行编造
+
+   ```json
+   // 示例：假设字段配置如下
+   {
+     "name": "状态",
+     "bizType": "SingleSelect",
+     "enumValues": ["待处理", "进行中", "已完成"]
+   }
+   // ✅ 正确：使用 enumValues 中的值
+   { "状态": "进行中" }
+   // ❌ 错误：使用不存在的选项
+   { "状态": "处理中" }
+   ```
+
+3. **字段名称可能包含中文或特殊字符**：必须使用括号表示法，禁止点表示法
+
+   ```javascript
+   // ✅ 正确
+   record['状态']
+   record['v1.0版本']
+   { '状态': '进行中', 'v1.0版本': '已发布' }
+
+   // ❌ 错误
+   record.状态        // 语法错误
+   record.v1.0版本    // 会被错误解析
+   ```
+
+4. **特殊字段需特化展示**：Progress（进度条）、Currency（货币符号）、Rating（星级）、DateTime（格式化日期）、Checkbox（勾选图标）、User（头像+名称）、Barcode（条码图形）
+5. **特殊字段需专用录入组件**：SingleSelect/MultiSelect（下拉选择器）、Checkbox（开关）、DateTime（日期选择器）、User（人员选择器）
+
+---
+
+## BizType 字段类型对照表
+
+| 字段类型 | BizType        | 字段类型     | BizType        | 字段类型 | BizType       |
+| -------- | -------------- | ------------ | -------------- | -------- | ------------- |
+| 文本     | `Text`         | 单选         | `SingleSelect` | 附件     | `Attachment`  |
+| 邮箱     | `Email`        | 多选         | `MultiSelect`  | 单向关联 | `SingleLink`  |
+| 条码     | `Barcode`      | 日期         | `DateTime`     | 双向关联 | `DuplexLink`  |
+| 数字     | `Number`       | 复选框       | `Checkbox`     | 查找引用 | `Lookup`      |
+| 进度     | `Progress`     | 人员         | `User`         | 公式     | `Formula`     |
+| 货币     | `Currency`     | 电话号码     | `Phone`        | 地理位置 | `Location`    |
+| 评分     | `Rating`       | 超链接       | `Url`          | 群组     | `GroupChat`   |
+| 创建时间 | `CreatedTime`  | 最后更新时间 | `ModifiedTime` | 创建人   | `CreatedUser` |
+| 修改人   | `ModifiedUser` | 自动编号     | `AutoNumber`   | 按钮     | `Button`      |
+
+---
+
+## BizType 读写格式对照表
+
+**重要**：读取和写入时的数据格式可能不同，必须严格按照下表处理。
+
+### 可写字段
+
+| BizType                                 | 写入格式         | 读取格式           | 说明                     |
+| --------------------------------------- | ---------------- | ------------------ | ------------------------ |
+| `Text`/`Email`/`Barcode`                | `string`         | `{ text: string }` | 写入纯字符串，读取为对象 |
+| `Phone`                                 | `string`         | `string`           | 读写均为字符串           |
+| `Number`/`Progress`/`Currency`/`Rating` | `number`         | `number`           | 数值类型                 |
+| `SingleSelect`                          | `string`         | `string`           | 必须匹配 enumValues      |
+| `MultiSelect`                           | `string[]`       | `string[]`         | 必须匹配 enumValues      |
+| `DateTime`                              | `number`         | `number`           | Unix 时间戳（毫秒）      |
+| `Checkbox`                              | `boolean`        | `boolean \| null`  | 读取时可能为 null        |
+| `User`                                  | `number[]`       | `number[]`         | suda user id 数组        |
+| `Url`                                   | `{ text, link }` | `{ text, link }`   | 读写格式一致             |
+| `Attachment`                            | `string[]`       | 复杂对象           | 写入文件 URL 数组        |
+
+### 只读字段
+
+| BizType                      | 读取格式                                       |
+| ---------------------------- | ---------------------------------------------- |
+| `CreatedTime`/`ModifiedTime` | `number`（时间戳）                             |
+| `CreatedUser`/`ModifiedUser` | `number[]`（user id 数组）                     |
+| `AutoNumber`                 | `{ text: string }`                             |
+| `Formula`                    | `{ bizType: string, value: any }`              |
+| `Location`                   | `{ fullAddress, provinceName, cityName, ... }` |
+| `GroupChat`                  | `[{ groupID, displayName, avatarImageUrl }]`   |
+
+---
+
+## Actions 概览
+
+| Action               | 说明                           |
+| -------------------- | ------------------------------ |
+| `searchRecords`      | 搜索记录，支持筛选、排序、分页 |
+| `getRecord`          | 根据 ID 查询单条记录           |
+| `batchAddRecords`    | 批量新增记录（最多 500 条）    |
+| `batchUpdateRecords` | 批量更新记录（最多 500 条）    |
+| `deleteRecords`      | 批量删除记录（最多 500 条）    |
+| `aggregateQuery`     | 聚合查询，支持分组、聚合计算、筛选、排序、分页 |
+
+> 注意：分析/统计类场景应优先使用 `aggregateQuery`，不要用 `searchRecords` 模拟统计。
+
+### Action 选择决策树
+
+```
+需要什么？
+├─ 查看/编辑单条记录 → getRecord / batchUpdateRecords
+├─ 列表分页浏览 → searchRecords（游标分页，pageToken 翻页）
+├─ 按条件筛选少量记录 → searchRecords + filter + pageSize
+├─ 排行榜 / TOP N → searchRecords + sort + pageSize=N
+├─ 统计数值（计数/求和/平均/最大最小） → aggregateQuery
+├─ 分组统计（按部门/状态等维度） → aggregateQuery + dimensions
+├─ 统计 + 明细下钻 → 聚合用 aggregateQuery，下钻用 searchRecords + filter
+├─ 新增数据 → batchAddRecords
+└─ 删除数据 → deleteRecords
+
+⚠️ 禁止模式：
+❌ searchRecords 拉全量 → 内存 reduce/filter 做统计 → 必须用 aggregateQuery
+❌ searchRecords 拉全量 → sort → slice 取 TOP N → 必须用 searchRecords + sort + pageSize
+❌ searchRecords 拉全量 → find 找单条 → 必须用 getRecord
+```
+
+## 数据分析类Action补充说明
+
+`aggregateQuery` 用于分组聚合统计，支持 dimensions（分组维度）和 measures（聚合计算）。
+
+### 输入参数
+
+- **dimensions 支持的 bizType**：`Text`、`Email`、`Barcode`、`Number`、`Progress`、`Currency`、`Rating`、`SingleSelect`、`MultiSelect`、`DateTime`、`CreatedTime`、`ModifiedTime`、`Checkbox`、`User`、`CreatedUser`、`ModifiedUser`
+
+### 输出结构
+
+- 返回 `{ result, hasMore, pageToken }`
+- `result` 是聚合结果数组，每个元素是对象，key 对应 dimensions/measures 中声明字段，value 结构为 `{ value: <actual_value> }`
+
+### dimensions value 类型（常见）
+
+- `Text` / `Email` / `Barcode`: `{ text: string }`
+- `Number`: `string`
+- `Progress`: `string`
+- `Currency`: `string`
+- `Rating`: `string`
+- `SingleSelect`: `string`
+- `MultiSelect`: `string[]`
+- `DateTime` / `CreatedTime` / `ModifiedTime`: `string`（按多维表格配置格式）
+- `Checkbox`: `string`（`"true"` / `"false"`）
+- `User`: `Array<{ id, name }>`
+- `CreatedUser` / `ModifiedUser`: `{ id, name }`
+
+### measures value 类型
+
+- 所有 measures 的 `value` 都是 `number`
+
+### measures 支持的 bizType
+
+| aggregation | 支持的 bizType | 不支持 |
+|-------------|---------------|--------|
+| `count` | 所有类型（但只统计非空值，统计总行数建议用不会为空的 Number 字段） | - |
+| `sum` / `avg` | `Number`、`Currency`、`Progress`、`Rating` | **`Formula`**、`Text` |
+| `max` / `min` | `Number`、`Currency`、`DateTime` | `Formula`、`Text` |
+
+### filter
+
+aggregateQuery 的 filter 格式与 searchRecords **完全相同**，遵循下方"搜索过滤条件规则"章节的所有规则。
+
+### expandArrayDimension
+
+- `expandArrayDimension=true` 时会先展开数组维度再聚合统计
+- 典型场景：`MultiSelect`、`User`
+
+---
+
+## 代码示例
+
+```typescript
+import { capabilityClient } from '@lark-apaas/client-toolkit-lite';
+
+// 推荐：load 一次 executor 后复用，每次 cast 两次（详见 SKILL.md 调用规范）
+const bitable = (capabilityClient as any).load('plugin_instance_id');
+
+// 搜索记录
+const response = await (bitable as any).call('searchRecords', {
+  filter: {
+    conjunction: 'and',
+    conditions: [{ fieldName: '状态', operator: 'is', value: ['进行中'] }],
+  },
+  pageSize: 20,
+});
+
+// ⚠️ 响应数据直接从 response 访问，不要加 .data 或 .output 前缀
+// ✅ 正确：response.records / response.hasMore / response.total / response.pageToken
+// ❌ 错误：response.data.records / response.data.output.records
+const { records, hasMore, total, pageToken } = response;
+console.log(`共 ${total} 条，本页 ${records.length} 条，还有更多: ${hasMore}`);
+
+// 获取单条记录
+const detail = await (bitable as any).call('getRecord', { recordID: 'recXXX' });
+// ✅ 正确：detail.id / detail.record
+// ❌ 错误：detail.data.output.id
+const title = detail.record['标题']?.text;
+
+// 批量新增（注意：写入时用写入格式，字段名必须用引号包裹）
+await (bitable as any).call('batchAddRecords', {
+  records: [
+    {
+      record: {
+        文本字段: '内容', // Text: string（非 { text: string }）
+        数字字段: 100, // Number: number
+        单选字段: '选项A', // SingleSelect: string（必须匹配 enumValues）
+        多选字段: ['标签1', '标签2'], // MultiSelect: string[]
+        复选框: true, // Checkbox: boolean
+        日期字段: Date.now(), // DateTime: number (毫秒时间戳)
+        人员字段: [123456, 789012], // User: number[] (suda user id)
+        超链接: { text: '链接文本', link: 'https://example.com' }, // Url
+      },
+    },
+  ],
+});
+
+// 批量更新
+await (bitable as any).call('batchUpdateRecords', {
+  records: [{ id: 'record_id', record: { 文本字段: '新内容' } }],
+});
+
+// 删除记录
+await (bitable as any).call('deleteRecords', { recordIDs: ['id1', 'id2'] });
+
+// 读取时注意格式差异
+const textValue = record.record['文本字段']?.text; // 读取时是 { text: string }
+const numberValue = record.record['数字字段']; // number
+const userIds = record.record['人员字段']; // number[]
+
+// 聚合查询
+const aggResp = await (bitable as any).call('aggregateQuery', {
+  dimensions: ['region'],
+  measures: [{ fieldName: 'order_id', aggregation: 'count', alias: 'order_count' }],
+  sort: [{ fieldName: 'region', desc: false }],
+  pageSize: 100,
+});
+
+const chartData =
+  aggResp.result?.map((item: Record<string, { value: unknown }>) => ({
+    region: String(item.region?.value || ''),
+    order_count: Number(item.order_count?.value || 0),
+  })) || [];
+```
+
+## 代码实现注意事项
+
+1. **响应数据直接访问，禁止猜测嵌套路径**。`capabilityClient.call()` 返回的就是最终数据，直接用 `response.records`、`response.total` 等。**禁止**加 `.data`、`.output`、`.data.output` 等前缀。如果不确定响应结构，先用 `console.log` 打印完整响应再编码，禁止凭猜测修改数据路径。
+2. 在进行写入操作时，比如确认提交时，应该有loading效果，禁止用户重复点击。
+3. 如果capabilityClient call失败，命中了error逻辑，要打印日志，同时把error message提示给用户。
+4. 在进行更新操作时，只更新需要更新的字段即可，不需要对全量字段进行更新。
+5. **分页必须使用游标分页，禁止全量拉取后切片**。先拉全部数据再 `slice` 会导致性能极差、浪费带宽和内存。每次只拉当前页数据，通过 `pageToken` 翻页：
+
+   ```typescript
+   const ex = (capabilityClient as any).load(pluginInstanceId);
+   const result = await (ex as any).call('searchRecords', {
+     pageSize: 10,
+     pageToken: cursor, // 上一页返回的 pageToken
+   });
+   // 返回：{ records, pageToken（下一页游标）, hasMore, total }
+   ```
+
+---
+
+## 推荐 UI 组件（vite-react / shadcn-ui）
+
+vite-react 用的是 shadcn-ui + Radix Primitives（无 spark UI 的 `<UserDisplay>` / `<UserSelect>` / `<Hyperlink>`）。下表按 shadcn 体系给出推荐组件，**核心读写格式跟 spark 是一致的**，差异在 UI 控件本身。
+
+| BizType                      | 展示                                                                 | 录入                                                |
+| ---------------------------- | -------------------------------------------------------------------- | --------------------------------------------------- |
+| `User`                       | `<Avatar>` + 名字（按需查询 `getCurrentUserProfile` 等接口）         | 自己拼：`<Select>` / `<Combobox>` 加搜索接口        |
+| `Url`                        | `<a href={val.link} target="_blank">{val.text}</a>`                  | 两个 `<Input>`（一个填 text，一个填 link）          |
+| `SingleSelect`/`MultiSelect` | 文本 / `<Badge>` 标签                                                | `<Select>` 选项来自 enumValues                      |
+| `DateTime`                   | `new Date(ts).toLocaleDateString()`                                  | `<Popover>` + `<Calendar>`（shadcn date picker）    |
+| `Checkbox`                   | `value ? '是' : '否'`                                                | `<Checkbox />`                                      |
+| `Currency`                   | `¥${value.toFixed(2)}`                                               | `<Input type="number" />`                           |
+| `Progress`                   | `<Progress value={value} />` 或 `${value}%`                          | `<Input type="number" min={0} max={100} />` 或 `<Slider />` |
+| `Rating`                     | `'★'.repeat(value) + '☆'.repeat(5-value)`                            | `<Input type="number" min={0} max={5} />`           |
+
+> spark 体系下的 `<UserDisplay>` / `<UserSelect>` / `<Hyperlink>` 在 vite-react 不可用。`@lark-apaas/client-toolkit-lite` 没有暴露这些组件 —— 需要自己用 shadcn 的 `<Avatar>` / `<Select>` / `<Combobox>` 拼装。人员数据的获取需要走业务 API（视具体 capability 而定）。
+
+### 组件代码示例
+
+```tsx
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
+import { Checkbox } from '@/components/ui/checkbox';
+
+// 单选下拉（选项必须来自 enumValues）
+<Select value={value} onValueChange={setValue}>
+  <SelectTrigger><SelectValue placeholder="请选择" /></SelectTrigger>
+  <SelectContent>
+    {enumValues.map(opt => (
+      <SelectItem key={opt} value={opt}>{opt}</SelectItem>
+    ))}
+  </SelectContent>
+</Select>
+
+// 人员展示（最小实现：Avatar + 名字）
+<div className="flex items-center gap-2">
+  <Avatar className="size-6">
+    <AvatarImage src={user.avatarUrl} />
+    <AvatarFallback>{user.name?.[0]}</AvatarFallback>
+  </Avatar>
+  <span>{user.name}</span>
+</div>
+
+// 超链接展示
+<a href={record['超链接']?.link} target="_blank" rel="noreferrer" className="text-primary underline">
+  {record['超链接']?.text}
+</a>
+```
+
+---
+
+## 表格列渲染示例
+
+```tsx
+const columns = [
+  // 文本字段 - 注意读取格式是 { text: string }
+  { title: '文本', dataIndex: ['record', '文本字段', 'text'], key: 'text' },
+  // 人员字段 - vite-react 自行用 Avatar + 名字渲染（数据来源走业务接口）
+  {
+    title: '负责人',
+    key: 'user',
+    render: (_, record) => {
+      const ids = (record.record['人员字段'] as number[]) || [];
+      return ids.map((id) => <UserChip key={id} userId={id} />);
+    },
+  },
+  // 日期字段 - 格式化显示
+  {
+    title: '创建日期',
+    dataIndex: ['record', '日期字段'],
+    key: 'date',
+    render: (v) => (v ? new Date(v).toLocaleDateString() : '-'),
+  },
+  // 货币 - 格式化显示
+  {
+    title: '金额',
+    dataIndex: ['record', '货币字段'],
+    key: 'currency',
+    render: (v) => (v != null ? `¥${v.toFixed(2)}` : '-'),
+  },
+  // 超链接 - vite-react 直接渲染 <a>
+  {
+    title: '链接',
+    key: 'hyperlink',
+    render: (_, record) => {
+      const v = record.record['超链接'] as { text?: string; link?: string } | undefined;
+      return v?.link ? (
+        <a href={v.link} target="_blank" rel="noreferrer" className="text-primary underline">
+          {v.text || v.link}
+        </a>
+      ) : '-';
+    },
+  },
+  // 多选 - 逗号分隔显示
+  {
+    title: '标签',
+    dataIndex: ['record', '多选字段'],
+    key: 'multiSelect',
+    render: (v) => v?.join(', ') || '-',
+  },
+];
+```
+
+---
+
+## 搜索过滤条件规则
+
+### 核心规则
+
+1. **value 始终是字符串数组**：数字需转为字符串，如 `["23.4"]`
+2. **空值判断**：`isEmpty`/`isNotEmpty` 时 value 填 `[]`
+3. **Formula 字段不支持筛选**
+4. **Text 字段 `is`/`isNot` 的 value 只能传一个元素**（见下方常见错误）
+
+### 各 BizType 的 value 格式与支持的操作符
+
+| BizType                                              | value 格式                                              | 支持的操作符                                                                                   |
+| ---------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `Text`/`Email`/`Barcode`/`Phone`                     | `["内容"]`（只能一个元素）                              | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Number`/`Currency`/`Progress`/`Rating`/`AutoNumber` | `["23.4"]`（数字转字符串）                              | `is`, `isNot`, `isGreater`, `isGreaterEqual`, `isLess`, `isLessEqual`, `isEmpty`, `isNotEmpty` |
+| `SingleSelect`/`MultiSelect`                         | `["选项A", "选项B"]`（`is`/`isNot` 填一个，其他可多个） | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Checkbox`                                           | `["true"]` 或 `["false"]`                               | `is`（仅此一个）                                                                               |
+| `User`/`CreatedUser`/`ModifiedUser`                  | `["123456"]`（suda user id）                            | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Url`                                                | `["显示名称"]`（填显示文本，非 URL）                    | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `GroupChat`                                          | `["328472133423"]`（群组 ID）                           | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Location`                                           | `["地址文本"]`（只能一个元素）                          | `is`, `isNot`, `contains`, `doesNotContain`, `isEmpty`, `isNotEmpty`                           |
+| `Attachment`                                         | `[]`（仅支持空值判断）                                  | `isEmpty`, `isNotEmpty`                                                                        |
+| `DateTime`/`CreatedTime`/`ModifiedTime`              | 见下方                                                  | `is`, `isEmpty`, `isNotEmpty`, `isGreater`, `isLess`                                           |
+
+### 日期字段 value
+
+| value                                                                     | 含义                   | operator 限制 |
+| ------------------------------------------------------------------------- | ---------------------- | ------------- |
+| `["ExactDate", "1702449755000"]`                                          | 具体日期（毫秒时间戳） | -             |
+| `["Today"]`/`["Tomorrow"]`/`["Yesterday"]`                                | 今天/明天/昨天         | -             |
+| `["CurrentWeek"]`/`["LastWeek"]`/`["CurrentMonth"]`/`["LastMonth"]`       | 本周/上周/本月/上月    | 仅 `is`       |
+| `["TheLastWeek"]`/`["TheNextWeek"]`/`["TheLastMonth"]`/`["TheNextMonth"]` | 过去/未来七天/三十天   | 仅 `is`       |
+
+### ⚠️ 常见错误（必读）
+
+#### 1. Text 字段 `is`/`isNot` 传多个 value → 查询返回空结果
+
+```typescript
+// ❌ 错误：Text 类型 is 只能传一个元素，传多个会静默返回空
+{ fieldName: '状态', operator: 'is', value: ['红色', '黑色'] }
+
+// ✅ 排除少数值：多条 isNot + conjunction: 'and'
+{
+  conjunction: 'and',
+  conditions: [
+    { fieldName: '进展', operator: 'isNot', value: ['已完成'] },
+    { fieldName: '进展', operator: 'isNot', value: ['已终止'] },
+  ],
+}
+
+// ✅ 匹配多个值：用 contains 模糊匹配（适合有公共子串的场景）
+{ fieldName: '进展', operator: 'contains', value: ['付款'] }  // 匹配"付款审批"和"付款动作"
+```
+
+#### 2. Formula 字段不支持 filter 和 sum/avg 聚合
+
+同一数据常有两个字段：原始 Number 字段（如 `金额`，单位元）和计算 Formula 字段（如 `金额(万元)`）。聚合和过滤**必须用 Number 字段**，在代码里做单位转换：
+
+```typescript
+// ❌ 错误：金额(万元) 是 Formula，不能聚合也不能过滤
+{ fieldName: '金额(万元)', aggregation: 'sum' }
+{ fieldName: '金额(万元)', operator: 'isGreater', value: ['0'] }
+
+// ✅ 正确：用 Number 类型的 金额 字段，代码里除以 10000 转万元
+{ fieldName: '金额', aggregation: 'sum', alias: 'total_amount' }
+// 结果处理：const amountWan = totalAmount / 10000;
+```
+
+#### 3. aggregateQuery 的 `isNot` 会排掉字段为空/null 的记录
+
+与 searchRecords 不同，aggregateQuery 中 `isNot` 会把字段值为空的记录也排除。如果很多记录的该字段为空，结果会远少于预期甚至为 0。
+
+解决方案：不在 filter 里用 `isNot` 排除 Text 值，改为在 dimensions 里加上该字段，在结果侧用 if 跳过不要的分组：
+
+```typescript
+// ❌ 错误：isNot 会把「目前进展」为空的记录也排掉
+filter: { conditions: [{ fieldName: '目前进展', operator: 'isNot', value: ['已完成'] }] }
+
+// ✅ 正确：不加 filter，在 dimensions 里加「目前进展」，结果侧排除
+dimensions: ['当前状态', '目前进展'],
+// 解析时：if (progress === '已完成' || progress === '已终止') continue;
+```
+
+#### 4. count 聚合只统计非空值
+
+统计总行数时用不会为空的 Number 字段（如"行号"），不要用可能为空的 Text 字段。
+
+### 筛选条件构建示例
+
+```typescript
+const filter = {
+  conjunction: 'and', // 或 'or'
+  conditions: [
+    { fieldName: '标题', operator: 'contains', value: ['关键词'] }, // 文本包含
+    { fieldName: '状态', operator: 'is', value: ['进行中'] }, // 单选匹配
+    { fieldName: '金额', operator: 'isGreater', value: ['1000'] }, // 数字比较
+    { fieldName: '创建日期', operator: 'is', value: ['Today'] }, // 日期-今天
+    { fieldName: '截止日期', operator: 'isLess', value: ['ExactDate', Date.now().toString()] }, // 日期-具体
+    { fieldName: '负责人', operator: 'is', value: ['123456'] }, // 人员筛选
+    { fieldName: '备注', operator: 'isEmpty', value: [] }, // 空值检查
+    { fieldName: '已归档', operator: 'is', value: ['true'] }, // 复选框
+  ],
+};
+
+const response = await capabilityClient
+  .load('plugin_instance_id')
+  .call<SearchResponse>('searchRecords', { filter, pageSize: 20 });
+```

package/steering/vite-react/tech.md

@@ -13,23 +13,64 @@
 
 ```
 my-app/
-├── client/
-│   ├── src/
-│   │   ├── components/   # 业务组件
-│   │   ├── ui/           # shadcn-ui 基础组件（不要直接改）
-│   │   ├── pages/        # 路由页面
-│   │   ├── hooks/        # 自定义 hooks
-│   │   └── lib/          # 工具函数
-│   ├── index.html
-│   └── public/
+├── src/
+│   ├── assets/         # 代码 import 的静态资源（图标、组件用图）
+│   ├── components/     # 业务组件
+│   │   └── ui/         # shadcn-ui 基础组件（不要直接改）
+│   ├── pages/          # 路由页面
+│   ├── hooks/          # 自定义 hooks
+│   └── lib/            # 工具函数
+├── public/             # 固定 URL 的公开静态资源（favicon 等）
+├── shared/
+│   ├── static/         # 鉴权访问的静态资源（私有源托管）
+│   └── capabilities/   # capabilities 声明
+├── index.html
 ├── vite.config.ts
-├── tsconfig.json
 └── package.json
 ```
 
+路径别名：
+
+- `@/*` → `./src/*`
+- `@shared/*` → `./shared/*`
+
+## 静态资源放哪——判定规则
+
+按问题树走，**从上往下选第一个 yes**：
+
+1. **代码里要 `import` 它吗？**（组件用的图标、被引用的图片、CSS 里的小图）
+   → `src/assets/`，用 `import url from '@/assets/foo.png'`。
+   Vite 会 hash + 优化，进 CDN。**绝大多数情况选这条。**
+
+2. **需要鉴权才能访问吗？**（仅登录用户可见的图片、PDF、配置）
+   → `shared/static/`。通过平台运行时 SDK 拿带 token 的 URL，**不要**用 `/shared/static/...` 这种相对路径直接引。
+
+3. **必须是固定 URL 文件名吗？**（favicon、被外部系统按 URL 抓取、第三方 SDK 写死路径）
+   → `public/`。
+   - HTML 里：`<link rel="icon" href="/favicon.svg" />`（Vite 自动重写到 BASE_URL）
+   - JSX/CSS 里**不要**写 `<img src="/foo.png" />`——绝对路径在生产会解析到 HTML 域名而不是 CDN，会 404。必须用 `${import.meta.env.BASE_URL}foo.png`。
+
+⚠️ 写代码默认走 `src/assets/`。`public/` 只在 1、2 都不适用时才用，并且必须用 `BASE_URL` 拼路径。
+
+## 动态选择一组资源（国旗、头像类）
+
+不要用 `public/flags/` + 拼字符串。用 `src/assets/` + `import.meta.glob`：
+
+```ts
+const flags = import.meta.glob('@/assets/flags/*.svg', {
+  eager: true,
+  query: '?url',
+  import: 'default',
+}) as Record<string, string>
+
+const url = flags[`/src/assets/flags/${code}.svg`]
+```
+
+这样能拿到 hash 后的 CDN URL，且 Vite 会 tree-shake 未引用项。
+
 ## 核心约定
 
-1. **shadcn-ui 组件不直接改源码**——需要变化时通过 className / variant props 控制
-2. **样式优先用 Tailwind utility**，避免写 CSS module
-3. **表单始终用 react-hook-form + zod**——不要直接操作 input value
-4. **图表 ECharts 优先 echarts-for-react**——React 18 严格模式下要小心 echarts instance 的初始化
+1. **shadcn-ui 组件不直接改源码**——需要变化时通过 `className` / `variant` props 控制。
+2. **样式优先用 Tailwind utility**，避免写 CSS module。
+3. **表单始终用 react-hook-form + zod**——不要直接操作 input value。
+4. **图表 ECharts 优先 echarts-for-react**——React 19 严格模式下注意 echarts instance 的初始化时机。

package/steering/_common/skills/react-hook-best-practices/SKILL.md

@@ -1,40 +0,0 @@
----
-name: react-hook-best-practices
-description: "Use when writing or reviewing React hooks: useEffect dependencies, useMemo/useCallback, custom hooks. 触发词：useEffect, useMemo, useCallback, 自定义 hook, React hook 规范"
-steering: true
-steering-topic: react_hook_best_practices
----
-
-# React Hook 最佳实践
-
-## 一、useEffect 依赖
-
-```tsx
-// ❌ 错：缺依赖
-useEffect(() => {
-  fetchUser(userId);
-}, []);
-
-// ✅ 对：完整依赖
-useEffect(() => {
-  fetchUser(userId);
-}, [userId]);
-```
-
-- 始终用 `eslint-plugin-react-hooks` 自动检查依赖
-- 不要为了"避免重复执行"省略依赖——用 cleanup function 或 ref 处理
-
-## 二、useMemo / useCallback
-
-只在以下场景使用：
-
-- 计算昂贵（实测 >5ms）
-- 引用稳定性影响下游（passed as prop to memoized child）
-
-默认**不预先优化**——大多数计算不需要 memo。
-
-## 三、自定义 hook
-
-- 命名以 `use` 开头：`useDebounce` / `useLocalStorage`
-- 单一职责，<50 行
-- 内部不直接操作 DOM（用 ref + useEffect）

package/steering/_common/skills/tailwind-conventions/SKILL.md

@@ -1,36 +0,0 @@
----
-name: tailwind-conventions
-description: "Use when styling components with Tailwind CSS: class organization, custom utilities, dark mode, responsive design. 触发词：Tailwind, className 顺序, 暗色模式, 响应式设计"
-steering: true
-steering-topic: tailwind_conventions
----
-
-# Tailwind 约定
-
-## 一、className 顺序
-
-按下列顺序写 class：
-
-1. layout（display / position / flex / grid）
-2. spacing（margin / padding / gap）
-3. sizing（width / height）
-4. typography（text-* / font-*）
-5. color（bg-* / text-* / border-*）
-6. interactive（hover: / focus: / active:）
-7. responsive（md: / lg:）
-
-```tsx
-<div className="flex items-center gap-2 px-4 py-2 text-sm text-gray-900 bg-white hover:bg-gray-50 md:px-6">
-```
-
-## 二、暗色模式
-
-- 用 `next-themes` 提供 `dark` class 切换
-- 颜色用 `bg-white dark:bg-gray-900` 双写
-
-## 三、避免硬编码颜色
-
-❌ `text-[#3b82f6]`
-✅ `text-blue-500`
-
-如确需自定义色，加到 `tailwind.config.js` 的 theme.colors。