@lark-apaas/coding-steering 0.1.72 → 0.1.73-alpha.20261026071512

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.72",
+  "version": "0.1.73-alpha.20261026071512",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [
     "steering"
   ],
+  "scripts": {
+    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
+  },
   "devDependencies": {
     "markdownlint-cli": "^0.47.0"
   },
@@ -17,8 +20,5 @@
     "miaoda",
     "coding-steering"
   ],
-  "license": "MIT",
-  "scripts": {
-    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
-  }
-}
+  "license": "MIT"
+}

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

@@ -60,8 +60,8 @@
    record.v1.0版本    // 会被错误解析
    ```
 
-4. **特殊字段需特化展示**：Progress（进度条）、Currency（货币符号）、Rating（星级）、DateTime（格式化日期）、Checkbox（勾选图标）、User（头像+名称）、Barcode（条码图形）
-5. **特殊字段需专用录入组件**：SingleSelect/MultiSelect（下拉选择器）、Checkbox（开关）、DateTime（日期选择器）、User（人员选择器）
+4. **特殊字段需特化展示**：Text（`BitableText` 分段渲染：链接可点击、保留换行）、Progress（进度条）、Currency（货币符号）、Rating（星级）、DateTime（格式化日期）、Checkbox（勾选图标）、User（头像+名称）、Barcode（条码图形）
+5. **特殊字段需专用录入组件**：Text（多行文本框 `Textarea`）、SingleSelect/MultiSelect（下拉选择器）、Checkbox（开关）、DateTime（日期选择器）、User（人员选择器）
 
 ---
 
@@ -89,7 +89,8 @@
 
 | BizType                                 | 写入格式         | 读取格式           | 说明                     |
 | --------------------------------------- | ---------------- | ------------------ | ------------------------ |
-| `Text`/`Email`/`Barcode`                | `string`         | `{ text: string }` | 写入纯字符串，读取为对象 |
+| `Text`                                  | `string \| TextSegment[]` | `{ text: string; originalValue?: TextSegment[] }` | 写入：纯文本直接传字符串；需要保留或写入链接、@ 时传分段数组，通常就是读到的 `originalValue` 修改后原样回传（见「文本字段写入分段」）。读取：`text` 是拼接后的纯文本，用于筛选、排序、比较；展示用 `originalValue`。读取时传 `textFormat: 'original'` 才有 `originalValue`；服务端开关关闭时也可能缺失，缺失时退回 `text` |
+| `Email`/`Barcode`                       | `string`         | `{ text: string }` | 写入纯字符串，读取为对象 |
 | `Phone`                                 | `string`         | `string`           | 读写均为字符串           |
 | `Number`/`Progress`/`Currency`/`Rating` | `number`         | `number`           | 数值类型                 |
 | `SingleSelect`                          | `string`         | `string`           | 必须匹配 enumValues      |
@@ -100,6 +101,22 @@
 | `Url`                                   | `{ text, link }` | `{ text, link }`   | 读写格式一致             |
 | `Attachment`                            | `string[]`       | 复杂对象           | 写入文件 URL 数组        |
 
+`TextSegment` 定义：
+
+```typescript
+// 多维表格文本字段的一段内容，原样来自多维表格；各段 text 依次拼接等于外层的 text
+type TextSegment = {
+  type: string;          // 'text' 普通文字（可能含 \n，也可能是空串）/ 'url' 超链接 / 'mention' @文档或@人；遇到不认识的按 text 显示
+  text: string;
+  link?: string;         // url 段、@文档段的地址
+  mentionType?: string | number; // mention 段：读出是 Bitable / Docx / Wiki / User 等字符串，取值开放，按有没有 link 判断能否点击；写入接受字符串或数字，必须与链接的文档类型一致
+  token?: string;        // @文档的文档 token；@人时是飞书 open_id，不是妙搭用户 ID，不要拿去查用户或和人员字段比较
+  [k: string]: unknown;  // 其他字段原样保留
+};
+```
+
+兼容说明：`originalValue` 是可选的新增字段，不传 `textFormat` 时返回内容与原来完全一致，只读 `.text` 的存量代码不用改也能正常运行。要链接可点击、保留换行时，再按下文迁移：读取加 `textFormat: 'original'`，展示从 `.text` 换成 `BitableText`。写入同理：Text 字段继续传字符串的存量代码行为不变，分段数组是新增的可选写法。
+
 ### 只读字段
 
 | BizType                      | 读取格式                                       |
@@ -175,7 +192,7 @@
 
 ### dimensions value 类型（常见）
 
-- `Text` / `Email` / `Barcode`: `{ text: string }`
+- `Text` / `Email` / `Barcode`: `{ text: string }`（Text 分组维度只有 `text`，没有 `originalValue`，不要按 originalValue 渲染分组标签）
 - `Number`: `string`
 - `Progress`: `string`
 - `Currency`: `string`
@@ -228,6 +245,9 @@ const response = await capabilityClient.load('plugin_instance_id').call<{
     conditions: [{ fieldName: '状态', operator: 'is', value: ['进行中'] }],
   },
   pageSize: 20,
+  // 列表展示文本字段（链接可点击、保留换行）时传；不传就没有 originalValue，页面只能显示纯文本。
+  // 同步入库、导出、统计等不展示的读取不要传，见「代码实现注意事项」第 6 条
+  textFormat: 'original',
 });
 
 // ⚠️ 响应数据直接从 response 访问，不要加 .data 或 .output 前缀
@@ -240,17 +260,17 @@ logger.info(`共 ${total} 条，本页 ${records.length} 条，还有更多: ${h
 const detail = await capabilityClient.load('plugin_instance_id').call<{
   id: string;
   record: Record<string, any>;
-}>('getRecord', { recordID: 'recXXX' });
+}>('getRecord', { recordID: 'recXXX', textFormat: 'original' }); // 详情 / 编辑页要展示文本字段，传 textFormat
 // ✅ 正确：detail.id / detail.record
 // ❌ 错误：detail.data.output.id
-const title = detail.record['标题']?.text;
+const title = detail.record['标题']?.text; // 纯文本，用于筛选、比较、导出；展示用 BitableText
 
 // 批量新增（注意：写入时用写入格式，字段名必须用引号包裹）
 await capabilityClient.load('plugin_instance_id').call('batchAddRecords', {
   records: [
     {
       record: {
-        文本字段: '内容', // Text: string（非 { text: string }）
+        文本字段: '内容', // Text: string（非 { text: string }）；要带链接时传 TextSegment[]，见「文本字段写入分段」
         数字字段: 100, // Number: number
         单选字段: '选项A', // SingleSelect: string（必须匹配 enumValues）
         多选字段: ['标签1', '标签2'], // MultiSelect: string[]
@@ -263,7 +283,7 @@ await capabilityClient.load('plugin_instance_id').call('batchAddRecords', {
   ],
 });
 
-// 批量更新
+// 批量更新（record 里只放改过的字段，见下方「代码实现注意事项」第 4 条）
 await capabilityClient.load('plugin_instance_id').call('batchUpdateRecords', {
   records: [{ id: 'record_id', record: { 文本字段: '新内容' } }],
 });
@@ -274,7 +294,7 @@ await capabilityClient
   .call('deleteRecords', { recordIDs: ['id1', 'id2'] });
 
 // 读取时注意格式差异
-const textValue = record.record['文本字段']?.text; // 读取时是 { text: string }
+const textValue = record.record['文本字段']?.text; // 纯文本，用于筛选、比较、导出；展示用 BitableText
 const numberValue = record.record['数字字段']; // number
 const userIds = record.record['人员字段']; // number[]
 
@@ -300,23 +320,125 @@ const chartData =
 1. **响应数据直接访问，禁止猜测嵌套路径**。`capabilityClient.call()` 返回的就是最终数据，直接用 `response.records`、`response.total` 等。**禁止**加 `.data`、`.output`、`.data.output` 等前缀。如果不确定响应结构，用 `logger.info('response', response)` 临时输出查看（或在浏览器开发者工具 Network 面板看）。
 2. 在进行写入操作时，比如确认提交时，应该有loading效果，禁止用户重复点击。
 3. 如果capabilityClient call失败，命中了error逻辑，要打印日志，同时把error message提示给用户。
-4. 在进行更新操作时，只更新需要更新的字段即可，不需要对全量字段进行更新。
+4. **只提交改过的字段（硬约束）**。编辑后调用 batchUpdateRecords 时，**只提交和读取时相比值有变化的字段**，逐字段比较后再组装 `record`。Text 字段没改动时**禁止**放进请求：多维表格按字段整体覆盖，而编辑表单的文本框提交的是纯字符串，带链接的文本会被写成纯文本，链接永久丢失。要改文字又保留链接，按下方「文本字段写入分段」写分段数组。
+
+   ```typescript
+   // 编辑页读取：含链接提示依赖 originalValue，getRecord 也要传 textFormat（见第 6 条）
+   const { record: original } = await capabilityClient.load(pluginInstanceId).call<{ id: string; record: Record<string, any> }>('getRecord', {
+     recordID: recordId,
+     textFormat: 'original',
+   });
+
+   // 表单回填：Text 字段用 .text（表单值是 string），不要把整个 { text, originalValue } 对象放进表单，
+   // 否则文本框显示 [object Object]，保存时还会把对象当写入值提交
+   const initForm = {
+     文本字段: original['文本字段']?.text ?? '',
+     数字字段: original['数字字段'],
+     多选字段: original['多选字段'] ?? [],
+     // ...其余可编辑字段；只读字段（创建时间、创建人、公式等）不要放进表单
+     // Attachment 读取是复杂对象、写入是文件 URL 数组，编辑时按写入格式单独维护
+   };
+
+   // 保存：form 是以 initForm 初始化、用户编辑后的表单值；逐字段和读取值比较，只组装改过的字段
+   const changed: Record<string, unknown> = {};
+   // Text：用 .text 和表单值比
+   if (form['文本字段'] !== (original['文本字段']?.text ?? '')) changed['文本字段'] = form['文本字段'];
+   // 标量字段：直接比较
+   if (form['数字字段'] !== original['数字字段']) changed['数字字段'] = form['数字字段'];
+   // 数组、对象字段（多选、人员、超链接等）按值比较，不要用 !==（引用不同会被误判为已修改）
+   const sameValue = (a: unknown, b: unknown) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+   if (!sameValue(form['多选字段'], original['多选字段'] ?? [])) changed['多选字段'] = form['多选字段'];
+   // ...其余字段同样逐个比较；只读字段不要放进 changed
+   // Attachment 读取格式与写入格式不同：未改动时不提交，改动时按写入格式（文件 URL 数组）提交
+   if (Object.keys(changed).length > 0) {
+     await capabilityClient.load(pluginInstanceId).call('batchUpdateRecords', {
+       records: [{ id: recordId, record: changed }],
+     });
+   }
+   ```
+
+   含链接文本的编辑提示：编辑控件检测到 `originalValue` 里有 `url` 或 `mention` 段时，在控件下方提示「该文本包含链接，保存后链接将变为纯文本」（示例见「推荐 UI 组件」）。编辑表单读取记录时必须传 `textFormat: 'original'`，否则拿不到分段，提示永远不出现。
 5. **分页必须使用游标分页，禁止全量拉取后切片**。先拉全部数据再 `slice` 会导致性能极差、浪费带宽和内存。每次只拉当前页数据，通过 `pageToken` 翻页：
 
    ```typescript
-   const result = await capabilityClient.load(pluginInstanceId).call('searchRecords', {
+   const result = await capabilityClient.load(pluginInstanceId).call<{
+     records: Array<{ id: string; record: Record<string, any> }>;
+     hasMore: boolean;
+     pageToken?: string;
+     total: number;
+   }>('searchRecords', {
      pageSize: 10,
      pageToken: cursor, // 上一页返回的 pageToken
+     // 要把文本字段展示给用户时再加 textFormat: 'original'（见第 6 条）
    });
    // 返回：{ records, pageToken（下一页游标）, hasMore, total }
    ```
 
+6. **展示或编辑文本字段时显式要原始分段**。列表、详情、编辑表单回显这类要把文本字段展示给用户（或在编辑时提示链接）的读取，searchRecords / getRecord 传 `textFormat: 'original'`；不传就没有 `originalValue`，页面只能显示纯文本。同步入库、导出、统计等不展示的读取不要传——返回体会变大，也没有用处。编辑表单读取记录时同样要传，否则拿不到分段，第 4 条的含链接提示永远不出现。传了也可能拿不到（服务端开关关闭），渲染时必须能退回 `text`。
+
+### 文本字段写入分段
+
+Text 字段写入除了字符串，还可以传分段数组 `TextSegment[]`，用来保留或写入链接、@。
+
+**原样写回 / 改文字保链接**：读取时传 `textFormat: 'original'`，把要改的普通文字段（`type: 'text'`）的 `text` 改掉，其余段（url、mention、空段）**原样保留不要删字段**，整个数组作为写入值。
+
+```typescript
+const detail = await capabilityClient.load(pluginInstanceId).call<{ id: string; record: Record<string, any> }>('getRecord', {
+  recordID: recordId,
+  textFormat: 'original',
+});
+const value = detail.record['文本字段'] as { text: string; originalValue?: TextSegment[] } | null | undefined;
+// 空单元格读回来没有这个字段（null），按空分段处理；有文字却拿不到 originalValue（未传 textFormat、服务端开关关闭或回滚）才报错：
+// 这时不能按分段写回（写入 [] 会清空单元格），也不能静默跳过（用户会以为已保存）
+const segments: TextSegment[] | undefined = value?.originalValue ?? (value?.text ? undefined : []);
+if (!segments) {
+  throw new Error('暂时无法保留文本中的链接，请稍后重试');
+}
+// 改开头的文字：第一段是普通文字就改它，否则（空单元格、开头是链接或 @）在最前面补一段文字
+const next: TextSegment[] =
+  segments[0]?.type === 'text'
+    ? [{ ...segments[0], text: '新的开头文字' }, ...segments.slice(1)]
+    : [{ type: 'text', text: '新的开头文字' }, ...segments];
+await capabilityClient.load(pluginInstanceId).call('batchUpdateRecords', {
+  records: [{ id: recordId, record: { 文本字段: next } }],
+});
+```
+
+**程序化写入链接**：
+
+```typescript
+await capabilityClient.load(pluginInstanceId).call('batchAddRecords', {
+  records: [
+    {
+      record: {
+        文本字段: [
+          { type: 'text', text: '详情见 ' },
+          { type: 'url', text: '需求文档', link: 'https://example.com/doc' },
+        ],
+      },
+    },
+  ],
+});
+```
+
+**写入规则**（每段缺字符串 `type` 或 `text` 时插件入参校验直接报错、不会到多维表格；其余不满足的由多维表格拒绝，错误码 800074060，message 说明原因）：
+
+- 每段必须有字符串 `type` 和 `text`（空段写 `''`）
+- `url` 段必须有 `text` 和 `link`（`link` 不要传空串：多维表格会把它补成 `http://<显示文字>`）
+- @文档（非 User 的 mention）必须同时有 `token` 和 `link`，且 `mentionType` 必须与链接的文档类型一致——**不要自己拼 @文档，复用读到的 mention 段**
+- @人段 `mentionType: 'User'`、`token` 为读到的 open_id
+- `mentionNotify`：原样透传。BOE 实测通过接口写入（含原样写回）未观察到 @ 通知，以多维表格侧说明为准；不要为了「不打扰」去删改读到的 mention 段
+- 空数组 `[]` 会清空单元格；要清空才这样写
+
+**编辑表单不变**：用户在文本框里编辑文本仍提交字符串（链接会变纯文本，保留第 4 条的编辑提示）；文本框未改动时仍然不提交该字段（与「只提交改过的字段」一致）。不要把文本框的字符串和 `originalValue` 拼接。
+
 ---
 
 ## 推荐 UI 组件
 
 | BizType                      | 展示                                                                 | 录入                                        |
 | ---------------------------- | -------------------------------------------------------------------- | ------------------------------------------- |
+| `Text`                       | `<BitableText value={val} />`（见下方示例）                          | `<Textarea />`（多行；不能用单行 `<Input>`，否则换行会在编辑时被吞掉） |
 | `User`                       | `<UserDisplay value={ids.map(id => id.toString())} />`               | `<UserSelect multiple />`                   |
 | `Url`                        | `<Hyperlink value={val} readOnly />`                                 | `<Hyperlink readOnly={false} />`            |
 | `SingleSelect`/`MultiSelect` | 文本/标签                                                            | `<Select>` 选项来自 enumValues              |
@@ -328,8 +450,53 @@ const chartData =
 
 BizType 为 `User` 的字段展示必须使用 business-ui `UserDisplay`；不要直接渲染、拼接或 `join` 用户 ID 文本。
 
+BizType 为 `Text` 的字段展示必须使用下方 `BitableText`；不要直接渲染 `.text`（多行会挤成一行，链接不可点击）。
+
 ### 组件代码示例
 
+```tsx
+import { Textarea } from '@/components/ui/textarea';
+
+// 文本展示：按 originalValue 分段渲染（TextSegment 定义见「BizType 读写格式对照表」）
+function BitableText({ value }: { value?: { text: string; originalValue?: TextSegment[] } }) {
+  if (!value?.text) return <span>-</span>;
+  // 未传 textFormat、服务端开关关闭或回滚时没有 originalValue，退回纯文本
+  const segments = value.originalValue ?? [{ type: 'text', text: value.text }];
+  return (
+    // pre-wrap 保留多行文本的换行
+    <span className="whitespace-pre-wrap break-words">
+      {segments.map((seg, i) =>
+        // 只有 http(s) 链接可点击；@人没有 link，按文字显示
+        typeof seg.link === 'string' && /^https?:\/\//.test(seg.link) ? (
+          <a key={i} href={seg.link} target="_blank" rel="noopener noreferrer" className="text-primary underline">
+            {seg.text}
+          </a>
+        ) : (
+          <span key={i}>{seg.text}</span>
+        ),
+      )}
+    </span>
+  );
+}
+```
+
+示例里的 `/^https?:\/\//` 校验不能省：链接来自表格里的用户输入，直接塞进 `href` 会放过 `javascript:` 这类链接。
+
+```tsx
+// 文本录入：多行 Textarea（不能用单行 Input，换行会被吞掉）
+// formData 回填时 Text 字段取 .text（字符串），见「代码实现注意事项」第 4 条
+<Textarea
+  value={formData['文本字段'] ?? ''}
+  onChange={(e) => setFormData({ ...formData, 文本字段: e.target.value })}
+  placeholder="请输入"
+/>
+{record['文本字段']?.originalValue?.some((seg) => seg.type === 'url' || seg.type === 'mention') && (
+  <p className="text-xs text-muted-foreground">该文本包含链接，保存后链接将变为纯文本</p>
+)}
+
+// 保存时只提交改过的字段，见「代码实现注意事项」第 4 条
+```
+
 ```tsx
 // 人员展示（business-ui UserDisplay 使用 value；不要传 users）
 <UserDisplay
@@ -379,8 +546,10 @@ BizType 为 `User` 的字段展示必须使用 business-ui `UserDisplay`；不
 
 ```tsx
 const columns = [
-  // 文本字段 - 注意读取格式是 { text: string }
-  { title: '文本', dataIndex: ['record', '文本字段', 'text'], key: 'text' },
+  // 文本字段 - 用 BitableText 分段渲染（链接可点击、保留换行），不要 dataIndex 直接取 text
+  { title: '文本', key: 'text', render: (_, r) => <BitableText value={r.record['文本字段']} /> },
+  // @deprecated 旧写法：{ title: '文本', dataIndex: ['record', '文本字段', 'text'], key: 'text' }
+  // 仍能运行，但多行挤成一行、链接不可点击；新页面不要再用，存量页面改到这一列时换成上面的 BitableText 写法
   // 人员字段 - 使用 business-ui UserDisplay 组件，传 value（用户 ID 字符串数组），不要传 users
   {
     title: '负责人',
@@ -424,6 +593,28 @@ const columns = [
 
 ---
 
+## ⚠️ 文本字段（Text）常见错误
+
+**1. 直接渲染 `record['文本字段'].text` → 多行挤成一行、链接不可点击**
+
+```tsx
+// ❌ 错误
+<span>{record.record['文本字段']?.text}</span>
+
+// ✅ 正确：用 BitableText（见「推荐 UI 组件」）
+<BitableText value={record.record['文本字段']} />
+```
+
+**2. 用 `originalValue` 做筛选、排序或等值比较** — 一律用 `text`；`originalValue` 只用于展示
+
+**3. 编辑表单把整条记录原样提交 → 没改的文本字段里的链接被覆盖成纯文本** — 只提交改过的字段；表单回填 Text 用 `.text`（见「代码实现注意事项」第 4 条）
+
+**4. 读取时不传 `textFormat`，却去读 `originalValue` → 永远拿不到分段** — 列表、详情、编辑页这类展示或编辑文本字段的读取，searchRecords / getRecord 都传 `textFormat: 'original'`；同步、导出、统计等不展示的读取不传
+
+**5. 改写分段时删掉 mention 段的 `token`/`link` 或改了 `mentionType` → 写入被拒** — 只改 `type: 'text'` 段的 `text`，其余段原样保留（见「文本字段写入分段」）
+
+---
+
 ## 搜索过滤条件规则
 
 ### 核心规则

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

@@ -56,8 +56,8 @@
    record.v1.0版本    // 会被错误解析
    ```
 
-4. **特殊字段需特化展示**：Progress（进度条）、Currency（货币符号）、Rating（星级）、DateTime（格式化日期）、Checkbox（勾选图标）、User（头像+名称）、Barcode（条码图形）
-5. **特殊字段需专用录入组件**：SingleSelect/MultiSelect（下拉选择器）、Checkbox（开关）、DateTime（日期选择器）、User（人员选择器）
+4. **特殊字段需特化展示**：Text（`BitableText` 分段渲染：链接可点击、保留换行）、Progress（进度条）、Currency（货币符号）、Rating（星级）、DateTime（格式化日期）、Checkbox（勾选图标）、User（头像+名称）、Barcode（条码图形）
+5. **特殊字段需专用录入组件**：Text（多行文本框 `Textarea`）、SingleSelect/MultiSelect（下拉选择器）、Checkbox（开关）、DateTime（日期选择器）、User（人员选择器）
 
 ---
 
@@ -85,7 +85,8 @@
 
 | BizType                                 | 写入格式         | 读取格式           | 说明                     |
 | --------------------------------------- | ---------------- | ------------------ | ------------------------ |
-| `Text`/`Email`/`Barcode`                | `string`         | `{ text: string }` | 写入纯字符串，读取为对象 |
+| `Text`                                  | `string \| TextSegment[]` | `{ text: string; originalValue?: TextSegment[] }` | 写入：纯文本直接传字符串；需要保留或写入链接、@ 时传分段数组，通常就是读到的 `originalValue` 修改后原样回传（见「文本字段写入分段」）。读取：`text` 是拼接后的纯文本，用于筛选、排序、比较；展示用 `originalValue`。读取时传 `textFormat: 'original'` 才有 `originalValue`；服务端开关关闭时也可能缺失，缺失时退回 `text` |
+| `Email`/`Barcode`                       | `string`         | `{ text: string }` | 写入纯字符串，读取为对象 |
 | `Phone`                                 | `string`         | `string`           | 读写均为字符串           |
 | `Number`/`Progress`/`Currency`/`Rating` | `number`         | `number`           | 数值类型                 |
 | `SingleSelect`                          | `string`         | `string`           | 必须匹配 enumValues      |
@@ -96,6 +97,22 @@
 | `Url`                                   | `{ text, link }` | `{ text, link }`   | 读写格式一致             |
 | `Attachment`                            | `string[]`       | 复杂对象           | 写入文件 URL 数组        |
 
+`TextSegment` 定义：
+
+```typescript
+// 多维表格文本字段的一段内容，原样来自多维表格；各段 text 依次拼接等于外层的 text
+type TextSegment = {
+  type: string;          // 'text' 普通文字（可能含 \n，也可能是空串）/ 'url' 超链接 / 'mention' @文档或@人；遇到不认识的按 text 显示
+  text: string;
+  link?: string;         // url 段、@文档段的地址
+  mentionType?: string | number; // mention 段：读出是 Bitable / Docx / Wiki / User 等字符串，取值开放，按有没有 link 判断能否点击；写入接受字符串或数字，必须与链接的文档类型一致
+  token?: string;        // @文档的文档 token；@人时是飞书 open_id，不是妙搭用户 ID，不要拿去查用户或和人员字段比较
+  [k: string]: unknown;  // 其他字段原样保留
+};
+```
+
+兼容说明：`originalValue` 是可选的新增字段，不传 `textFormat` 时返回内容与原来完全一致，只读 `.text` 的存量代码不用改也能正常运行。要链接可点击、保留换行时，再按下文迁移：读取加 `textFormat: 'original'`，展示从 `.text` 换成 `BitableText`。写入同理：Text 字段继续传字符串的存量代码行为不变，分段数组是新增的可选写法。
+
 ### 只读字段
 
 | BizType                      | 读取格式                                       |
@@ -157,7 +174,7 @@
 
 ### dimensions value 类型（常见）
 
-- `Text` / `Email` / `Barcode`: `{ text: string }`
+- `Text` / `Email` / `Barcode`: `{ text: string }`（Text 分组维度只有 `text`，没有 `originalValue`，不要按 originalValue 渲染分组标签）
 - `Number`: `string`
 - `Progress`: `string`
 - `Currency`: `string`
@@ -207,6 +224,9 @@ const response = await (bitable as any).call('searchRecords', {
     conditions: [{ fieldName: '状态', operator: 'is', value: ['进行中'] }],
   },
   pageSize: 20,
+  // 列表展示文本字段（链接可点击、保留换行）时传；不传就没有 originalValue，页面只能显示纯文本。
+  // 同步入库、导出、统计等不展示的读取不要传，见「代码实现注意事项」第 6 条
+  textFormat: 'original',
 });
 
 // ⚠️ 响应数据直接从 response 访问，不要加 .data 或 .output 前缀
@@ -216,17 +236,17 @@ const { records, hasMore, total, pageToken } = response;
 console.log(`共 ${total} 条，本页 ${records.length} 条，还有更多: ${hasMore}`);
 
 // 获取单条记录
-const detail = await (bitable as any).call('getRecord', { recordID: 'recXXX' });
+const detail = await (bitable as any).call('getRecord', { recordID: 'recXXX', textFormat: 'original' }); // 详情 / 编辑页要展示文本字段，传 textFormat
 // ✅ 正确：detail.id / detail.record
 // ❌ 错误：detail.data.output.id
-const title = detail.record['标题']?.text;
+const title = detail.record['标题']?.text; // 纯文本，用于筛选、比较、导出；展示用 BitableText
 
 // 批量新增（注意：写入时用写入格式，字段名必须用引号包裹）
 await (bitable as any).call('batchAddRecords', {
   records: [
     {
       record: {
-        文本字段: '内容', // Text: string（非 { text: string }）
+        文本字段: '内容', // Text: string（非 { text: string }）；要带链接时传 TextSegment[]，见「文本字段写入分段」
         数字字段: 100, // Number: number
         单选字段: '选项A', // SingleSelect: string（必须匹配 enumValues）
         多选字段: ['标签1', '标签2'], // MultiSelect: string[]
@@ -239,7 +259,7 @@ await (bitable as any).call('batchAddRecords', {
   ],
 });
 
-// 批量更新
+// 批量更新（record 里只放改过的字段，见下方「代码实现注意事项」第 4 条）
 await (bitable as any).call('batchUpdateRecords', {
   records: [{ id: 'record_id', record: { 文本字段: '新内容' } }],
 });
@@ -248,7 +268,7 @@ await (bitable as any).call('batchUpdateRecords', {
 await (bitable as any).call('deleteRecords', { recordIDs: ['id1', 'id2'] });
 
 // 读取时注意格式差异
-const textValue = record.record['文本字段']?.text; // 读取时是 { text: string }
+const textValue = record.record['文本字段']?.text; // 纯文本，用于筛选、比较、导出；展示用 BitableText
 const numberValue = record.record['数字字段']; // number
 const userIds = record.record['人员字段']; // number[]
 
@@ -272,7 +292,44 @@ const chartData =
 1. **响应数据直接访问，禁止猜测嵌套路径**。`capabilityClient.call()` 返回的就是最终数据，直接用 `response.records`、`response.total` 等。**禁止**加 `.data`、`.output`、`.data.output` 等前缀。如果不确定响应结构，先用 `console.log` 打印完整响应再编码，禁止凭猜测修改数据路径。
 2. 在进行写入操作时，比如确认提交时，应该有loading效果，禁止用户重复点击。
 3. 如果capabilityClient call失败，命中了error逻辑，要打印日志，同时把error message提示给用户。
-4. 在进行更新操作时，只更新需要更新的字段即可，不需要对全量字段进行更新。
+4. **只提交改过的字段（硬约束）**。编辑后调用 batchUpdateRecords 时，**只提交和读取时相比值有变化的字段**，逐字段比较后再组装 `record`。Text 字段没改动时**禁止**放进请求：多维表格按字段整体覆盖，而编辑表单的文本框提交的是纯字符串，带链接的文本会被写成纯文本，链接永久丢失。要改文字又保留链接，按下方「文本字段写入分段」写分段数组。
+
+   ```typescript
+   // 编辑页读取：含链接提示依赖 originalValue，getRecord 也要传 textFormat（见第 6 条）
+   const { record: original } = await (bitable as any).call('getRecord', {
+     recordID: recordId,
+     textFormat: 'original',
+   });
+
+   // 表单回填：Text 字段用 .text（表单值是 string），不要把整个 { text, originalValue } 对象放进表单，
+   // 否则文本框显示 [object Object]，保存时还会把对象当写入值提交
+   const initForm = {
+     文本字段: original['文本字段']?.text ?? '',
+     数字字段: original['数字字段'],
+     多选字段: original['多选字段'] ?? [],
+     // ...其余可编辑字段；只读字段（创建时间、创建人、公式等）不要放进表单
+     // Attachment 读取是复杂对象、写入是文件 URL 数组，编辑时按写入格式单独维护
+   };
+
+   // 保存：form 是以 initForm 初始化、用户编辑后的表单值；逐字段和读取值比较，只组装改过的字段
+   const changed: Record<string, unknown> = {};
+   // Text：用 .text 和表单值比
+   if (form['文本字段'] !== (original['文本字段']?.text ?? '')) changed['文本字段'] = form['文本字段'];
+   // 标量字段：直接比较
+   if (form['数字字段'] !== original['数字字段']) changed['数字字段'] = form['数字字段'];
+   // 数组、对象字段（多选、人员、超链接等）按值比较，不要用 !==（引用不同会被误判为已修改）
+   const sameValue = (a: unknown, b: unknown) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+   if (!sameValue(form['多选字段'], original['多选字段'] ?? [])) changed['多选字段'] = form['多选字段'];
+   // ...其余字段同样逐个比较；只读字段不要放进 changed
+   // Attachment 读取格式与写入格式不同：未改动时不提交，改动时按写入格式（文件 URL 数组）提交
+   if (Object.keys(changed).length > 0) {
+     await (bitable as any).call('batchUpdateRecords', {
+       records: [{ id: recordId, record: changed }],
+     });
+   }
+   ```
+
+   含链接文本的编辑提示：编辑控件检测到 `originalValue` 里有 `url` 或 `mention` 段时，在控件下方提示「该文本包含链接，保存后链接将变为纯文本」（示例见「推荐 UI 组件」）。编辑表单读取记录时必须传 `textFormat: 'original'`，否则拿不到分段，提示永远不出现。
 5. **分页必须使用游标分页，禁止全量拉取后切片**。先拉全部数据再 `slice` 会导致性能极差、浪费带宽和内存。每次只拉当前页数据，通过 `pageToken` 翻页：
 
    ```typescript
@@ -280,10 +337,69 @@ const chartData =
    const result = await (ex as any).call('searchRecords', {
      pageSize: 10,
      pageToken: cursor, // 上一页返回的 pageToken
+     // 要把文本字段展示给用户时再加 textFormat: 'original'（见第 6 条）
    });
    // 返回：{ records, pageToken（下一页游标）, hasMore, total }
    ```
 
+6. **展示或编辑文本字段时显式要原始分段**。列表、详情、编辑表单回显这类要把文本字段展示给用户（或在编辑时提示链接）的读取，searchRecords / getRecord 传 `textFormat: 'original'`；不传就没有 `originalValue`，页面只能显示纯文本。同步入库、导出、统计等不展示的读取不要传——返回体会变大，也没有用处。编辑表单读取记录时同样要传，否则拿不到分段，第 4 条的含链接提示永远不出现。传了也可能拿不到（服务端开关关闭），渲染时必须能退回 `text`。
+
+### 文本字段写入分段
+
+Text 字段写入除了字符串，还可以传分段数组 `TextSegment[]`，用来保留或写入链接、@。
+
+**原样写回 / 改文字保链接**：读取时传 `textFormat: 'original'`，把要改的普通文字段（`type: 'text'`）的 `text` 改掉，其余段（url、mention、空段）**原样保留不要删字段**，整个数组作为写入值。
+
+```typescript
+const detail = await (bitable as any).call('getRecord', {
+  recordID: recordId,
+  textFormat: 'original',
+});
+const value = detail.record['文本字段'] as { text: string; originalValue?: TextSegment[] } | null | undefined;
+// 空单元格读回来没有这个字段（null），按空分段处理；有文字却拿不到 originalValue（未传 textFormat、服务端开关关闭或回滚）才报错：
+// 这时不能按分段写回（写入 [] 会清空单元格），也不能静默跳过（用户会以为已保存）
+const segments: TextSegment[] | undefined = value?.originalValue ?? (value?.text ? undefined : []);
+if (!segments) {
+  throw new Error('暂时无法保留文本中的链接，请稍后重试');
+}
+// 改开头的文字：第一段是普通文字就改它，否则（空单元格、开头是链接或 @）在最前面补一段文字
+const next: TextSegment[] =
+  segments[0]?.type === 'text'
+    ? [{ ...segments[0], text: '新的开头文字' }, ...segments.slice(1)]
+    : [{ type: 'text', text: '新的开头文字' }, ...segments];
+await (bitable as any).call('batchUpdateRecords', {
+  records: [{ id: recordId, record: { 文本字段: next } }],
+});
+```
+
+**程序化写入链接**：
+
+```typescript
+await (bitable as any).call('batchAddRecords', {
+  records: [
+    {
+      record: {
+        文本字段: [
+          { type: 'text', text: '详情见 ' },
+          { type: 'url', text: '需求文档', link: 'https://example.com/doc' },
+        ],
+      },
+    },
+  ],
+});
+```
+
+**写入规则**（每段缺字符串 `type` 或 `text` 时插件入参校验直接报错、不会到多维表格；其余不满足的由多维表格拒绝，错误码 800074060，message 说明原因）：
+
+- 每段必须有字符串 `type` 和 `text`（空段写 `''`）
+- `url` 段必须有 `text` 和 `link`（`link` 不要传空串：多维表格会把它补成 `http://<显示文字>`）
+- @文档（非 User 的 mention）必须同时有 `token` 和 `link`，且 `mentionType` 必须与链接的文档类型一致——**不要自己拼 @文档，复用读到的 mention 段**
+- @人段 `mentionType: 'User'`、`token` 为读到的 open_id
+- `mentionNotify`：原样透传。BOE 实测通过接口写入（含原样写回）未观察到 @ 通知，以多维表格侧说明为准；不要为了「不打扰」去删改读到的 mention 段
+- 空数组 `[]` 会清空单元格；要清空才这样写
+
+**编辑表单不变**：用户在文本框里编辑文本仍提交字符串（链接会变纯文本，保留第 4 条的编辑提示）；文本框未改动时仍然不提交该字段（与「只提交改过的字段」一致）。不要把文本框的字符串和 `originalValue` 拼接。
+
 ---
 
 ## 推荐 UI 组件（vite-react / shadcn-ui）
@@ -292,6 +408,7 @@ vite-react 用的是 shadcn-ui + Radix Primitives（无 spark UI 的 `<UserDispl
 
 | BizType                      | 展示                                                                 | 录入                                                |
 | ---------------------------- | -------------------------------------------------------------------- | --------------------------------------------------- |
+| `Text`                       | `<BitableText value={val} />`（见下方示例，原生元素 + tailwind）     | shadcn `<Textarea />`（多行；不能用单行 `<Input>`，否则换行会在编辑时被吞掉） |
 | `User`                       | `<Avatar>` + 名字（按需查询 `getCurrentUserProfile` 等接口）         | 自己拼：`<Select>` / `<Combobox>` 加搜索接口        |
 | `Url`                        | `<a href={val.link} target="_blank">{val.text}</a>`                  | 两个 `<Input>`（一个填 text，一个填 link）          |
 | `SingleSelect`/`MultiSelect` | 文本 / `<Badge>` 标签                                                | `<Select>` 选项来自 enumValues                      |
@@ -303,12 +420,15 @@ vite-react 用的是 shadcn-ui + Radix Primitives（无 spark UI 的 `<UserDispl
 
 > spark 体系下的 `<UserDisplay>` / `<UserSelect>` / `<Hyperlink>` 在 vite-react 不可用。`@lark-apaas/client-toolkit-lite` 没有暴露这些组件 —— 需要自己用 shadcn 的 `<Avatar>` / `<Select>` / `<Combobox>` 拼装。人员数据的获取需要走业务 API（视具体 capability 而定）。
 
+BizType 为 `Text` 的字段展示必须使用下方 `BitableText`（原生元素 + tailwind 实现，不依赖 spark 组件）；不要直接渲染 `.text`（多行会挤成一行，链接不可点击）。
+
 ### 组件代码示例
 
 ```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';
+import { Textarea } from '@/components/ui/textarea';
 
 // 单选下拉（选项必须来自 enumValues）
 <Select value={value} onValueChange={setValue}>
@@ -333,16 +453,57 @@ import { Checkbox } from '@/components/ui/checkbox';
 <a href={record['超链接']?.link} target="_blank" rel="noreferrer" className="text-primary underline">
   {record['超链接']?.text}
 </a>
+
+// 文本录入：shadcn 多行 Textarea（不能用单行 Input，换行会被吞掉）
+// formData 回填时 Text 字段取 .text（字符串），见「代码实现注意事项」第 4 条
+<Textarea
+  value={formData['文本字段'] ?? ''}
+  onChange={(e) => setFormData({ ...formData, 文本字段: e.target.value })}
+  placeholder="请输入"
+/>
+{record['文本字段']?.originalValue?.some((seg) => seg.type === 'url' || seg.type === 'mention') && (
+  <p className="text-xs text-muted-foreground">该文本包含链接，保存后链接将变为纯文本</p>
+)}
+
+// 保存时只提交改过的字段，见「代码实现注意事项」第 4 条
+```
+
+```tsx
+// 文本展示：按 originalValue 分段渲染（TextSegment 定义见「BizType 读写格式对照表」）
+function BitableText({ value }: { value?: { text: string; originalValue?: TextSegment[] } }) {
+  if (!value?.text) return <span>-</span>;
+  // 未传 textFormat、服务端开关关闭或回滚时没有 originalValue，退回纯文本
+  const segments = value.originalValue ?? [{ type: 'text', text: value.text }];
+  return (
+    // pre-wrap 保留多行文本的换行
+    <span className="whitespace-pre-wrap break-words">
+      {segments.map((seg, i) =>
+        // 只有 http(s) 链接可点击；@人没有 link，按文字显示
+        typeof seg.link === 'string' && /^https?:\/\//.test(seg.link) ? (
+          <a key={i} href={seg.link} target="_blank" rel="noopener noreferrer" className="text-primary underline">
+            {seg.text}
+          </a>
+        ) : (
+          <span key={i}>{seg.text}</span>
+        ),
+      )}
+    </span>
+  );
+}
 ```
 
+示例里的 `/^https?:\/\//` 校验不能省：链接来自表格里的用户输入，直接塞进 `href` 会放过 `javascript:` 这类链接。
+
 ---
 
 ## 表格列渲染示例
 
 ```tsx
 const columns = [
-  // 文本字段 - 注意读取格式是 { text: string }
-  { title: '文本', dataIndex: ['record', '文本字段', 'text'], key: 'text' },
+  // 文本字段 - 用 BitableText 分段渲染（链接可点击、保留换行），不要 dataIndex 直接取 text
+  { title: '文本', key: 'text', render: (_, r) => <BitableText value={r.record['文本字段']} /> },
+  // @deprecated 旧写法：{ title: '文本', dataIndex: ['record', '文本字段', 'text'], key: 'text' }
+  // 仍能运行，但多行挤成一行、链接不可点击；新页面不要再用，存量页面改到这一列时换成上面的 BitableText 写法
   // 人员字段 - vite-react 自行用 Avatar + 名字渲染（数据来源走业务接口）
   {
     title: '负责人',
@@ -391,6 +552,36 @@ const columns = [
 
 ---
 
+## ⚠️ 文本字段（Text）常见错误
+
+### 1. 直接渲染 `record['文本字段'].text` → 多行挤成一行、链接不可点击
+
+```tsx
+// ❌ 错误
+<span>{record.record['文本字段']?.text}</span>
+
+// ✅ 正确：用 BitableText（见「推荐 UI 组件」）
+<BitableText value={record.record['文本字段']} />
+```
+
+### 2. 用 `originalValue` 做筛选、排序或等值比较
+
+一律用 `text`；`originalValue` 只用于展示。
+
+### 3. 编辑表单把整条记录原样提交 → 没改的文本字段里的链接被覆盖成纯文本
+
+只提交改过的字段；表单回填 Text 用 `.text`（见「代码实现注意事项」第 4 条）。
+
+### 4. 读取时不传 `textFormat`，却去读 `originalValue` → 永远拿不到分段
+
+列表、详情、编辑页这类展示或编辑文本字段的读取，searchRecords / getRecord 都传 `textFormat: 'original'`；同步、导出、统计等不展示的读取不传。
+
+### 5. 改写分段时删掉 mention 段的 `token`/`link` 或改了 `mentionType` → 写入被拒
+
+只改 `type: 'text'` 段的 `text`，其余段原样保留（见「文本字段写入分段」）。
+
+---
+
 ## 搜索过滤条件规则
 
 ### 核心规则