@yandy0725/pi-lark 0.1.0

package/skills/lark-base/references/lark-base-field-json.md

@@ -0,0 +1,489 @@
+# Base field JSON SSOT
+
+> 适用命令：`lark-cli base +field-create`、`lark-cli base +field-update`
+
+本文档定义 `+field-create` / `+field-update` 写字段时 `--json` 的推荐格式，是字段类型与字段 JSON 结构的 source of truth。目标不是复刻完整 schema，而是让 agent 稳定产出正确 payload。
+
+## 1. 顶层规则（必须遵守）
+
+- `--json` 必须是 JSON 对象。
+- 顶层统一使用：`type` + `name` + 类型特有字段。
+- 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接。
+- 不要使用旧结构：`field_name`、`property`、`ui_type`、数字枚举 `type`。
+- `+field-update` 使用同样的字段 JSON 结构，但语义是 `PUT`；这是高风险写入操作，建议先 `+field-get` 再按目标状态全量提交，并带 `--yes`。
+- `type=formula` 或 `type=lookup` 创建/更新前，必须先读对应 guide。
+
+推荐示例：
+
+```json
+{
+  "type": "text",
+  "name": "需求背景",
+  "description": "记录需求背景与已知约束"
+}
+```
+
+## 2. 字段速查
+
+| 类型 | 最小必填字段 | 常见补充字段 |
+|------|--------------|-------------|
+| `text` | `type` `name` | `style.type` |
+| `number` | `type` `name` | `style` |
+| `select` | `type` `name` | `multiple` + `options`，或 `multiple` + `dynamic_options_source` |
+| `datetime` | `type` `name` | `style.format` |
+| `created_at` / `updated_at` | `type` `name` | `style.format` |
+| `user` / `group_chat` | `type` `name` | `multiple` |
+| `created_by` / `updated_by` | `type` `name` | 无 |
+| `link` | `type` `name` `link_table` | `bidirectional` `bidirectional_link_field_name` |
+| `formula` | `type` `name` `expression` | 无 |
+| `lookup` | `type` `name` `from` `select` `where` | `aggregate` |
+| `auto_number` | `type` `name` | `style.rules` |
+| `attachment` / `location` / `checkbox` | `type` `name` | 无 |
+
+所有类型都可额外传 `description`；上表的“常见补充字段”只列类型特有配置。
+
+## 3. 各类型写法
+
+### 3.1 text
+
+文本字段；电话、超链接、邮箱、条码也都属于 `text`，通过 `style.type` 区分。
+
+最小写法（默认 `style.type` 为 `plain`）：
+
+```json
+{
+  "type": "text",
+  "name": "标题"
+}
+```
+
+常用写法：
+
+```json
+{
+  "type": "text",
+  "name": "标题",
+  "description": "主标题字段"
+}
+```
+
+```json
+{
+  "type": "text",
+  "name": "联系电话",
+  "style": { "type": "phone" }
+}
+```
+
+```json
+{
+  "type": "text",
+  "name": "官网",
+  "style": { "type": "url" }
+}
+```
+
+常用 `style.type`：`plain`（默认）、`phone`、`url`、`email`、`barcode`。
+
+### 3.2 number
+
+数字字段；货币、进度、评分都属于 `number`，通过 `style.type` 区分。
+
+最小写法（默认 `style.type` 为 `plain`）：
+
+```json
+{
+  "type": "number",
+  "name": "工时"
+}
+```
+
+`style` 是按 `type` 区分的对象；不同 `style.type` 的内部字段不一样，不要混传。
+
+#### `plain`
+
+支持字段：`precision`、`percentage`、`thousands_separator`
+
+默认值 / 约束：
+- `precision` 取值 `0..4`，默认 `2`
+- `percentage` 默认 `false`
+- `thousands_separator` 默认 `false`
+
+```json
+{
+  "type": "number",
+  "name": "工时",
+  "style": {
+    "type": "plain",
+    "precision": 2,
+    "percentage": false,
+    "thousands_separator": true
+  }
+}
+```
+
+#### `currency`
+
+支持字段：`precision`、`currency_code`
+
+默认值 / 约束：
+- `precision` 取值 `0..4`，默认 `2`
+- `currency_code` 必填，如 `CNY`、`USD`、`EUR`
+
+```json
+{
+  "type": "number",
+  "name": "预算",
+  "style": { "type": "currency", "precision": 2, "currency_code": "CNY" }
+}
+```
+
+#### `progress`
+
+支持字段：`percentage`、`color`
+
+默认值 / 约束：
+- `percentage` 默认 `true`
+- `color` 必填
+- `color` 可用：`Blue`、`Purple`、`DarkGreen`、`Green`、`Cyan`、`Orange`、`Red`、`Gray`、`WhiteToBlueGradient`、`WhiteToPurpleGradient`、`WhiteToOrangeGradient`、`GreenToRedGradient`、`RedToGreenGradient`、`BlueToPinkGradient`、`PinkToBlueGradient`、`SpectralGradient`
+
+```json
+{
+  "type": "number",
+  "name": "完成度",
+  "style": { "type": "progress", "percentage": true, "color": "Blue" }
+}
+```
+
+#### `rating`
+
+支持字段：`icon`、`min`、`max`
+
+默认值 / 约束：
+- `icon` 默认 `star`
+- `icon` 可用：`star`、`heart`、`thumbsup`、`fire`、`smile`、`lightning`、`flower`、`number`
+- `min` 取值 `0..1`，默认 `1`
+- `max` 取值 `1..10`，默认 `5`
+
+```json
+{
+  "type": "number",
+  "name": "评分",
+  "style": { "type": "rating", "icon": "star", "min": 1, "max": 5 }
+}
+```
+
+### 3.3 select
+
+单选和多选都使用 `select`；用 `multiple` 区分。`multiple` 默认 `false`。静态选项用 `options`，动态选项用 `dynamic_options_source`；两者不要同时传。
+
+#### 静态选项
+
+支持字段：`multiple`、`options`
+
+默认值 / 约束：
+- `multiple` 默认 `false`
+- `options` 最多 `10000` 项
+- `options[]` 结构是 `{name, hue?, lightness?}`
+- `options[].name` 必填
+- `options[].hue` 可用：`Red`、`Orange`、`Yellow`、`Lime`、`Green`、`Turquoise`、`Wathet`、`Blue`、`Carmine`、`Purple`、`Gray` 缺省值为 `Blue`
+- `options[].lightness` 可用：`Lighter`、`Light`、`Standard`、`Dark`、`Darker` 缺省值为 `Lighter`
+- 选项里没有 `id`，只有 `name`。
+
+```json
+{
+  "type": "select",
+  "name": "状态",
+  "multiple": false,
+  "options": [
+    { "name": "Todo", "hue": "Blue", "lightness": "Lighter" },
+    { "name": "Done", "hue": "Green", "lightness": "Light" }
+  ]
+}
+```
+
+#### 动态选项
+
+支持字段：`multiple`、`dynamic_options_source`
+
+默认值 / 约束：
+- `multiple` 默认 `false`
+- `dynamic_options_source` 结构是 `{table_id, field_id}`
+- `dynamic_options_source.table_id` 填来源表 id 或表名
+- `dynamic_options_source.field_id` 填来源字段 id 或字段名
+- `dynamic_options_source` 仅创建支持；更新已有字段时不要传
+- 引用选项条件 / 级联筛选条件：这个功能在 Base 前端支持，属于 UI-only 属性，OpenAPI 里不支持，CLI 不能读取、创建或更新；不要根据接口返回缺失判断未配置
+
+```json
+{
+  "type": "select",
+  "name": "动态状态",
+  "multiple": false,
+  "dynamic_options_source": {
+    "table_id": "选项表",
+    "field_id": "候选状态"
+  }
+}
+```
+
+### 3.4 datetime
+
+手动填写的日期/时间字段。系统时间用 `created_at` / `updated_at`。
+
+最小写法：
+
+```json
+{
+  "type": "datetime",
+  "name": "截止时间"
+}
+```
+
+支持字段：`style.format`
+
+默认值 / 约束：
+- `style.format` 默认 `yyyy/MM/dd` 可用格式：`yyyy/MM/dd`、`yyyy/MM/dd HH:mm`、`yyyy/MM/dd HH:mm Z`、`yyyy-MM-dd`、`yyyy-MM-dd HH:mm`、`yyyy-MM-dd HH:mm Z`、`MM-dd`、`MM/dd/yyyy`、`dd/MM/yyyy`
+
+常用写法：
+
+```json
+{
+  "type": "datetime",
+  "name": "截止时间",
+  "style": { "format": "yyyy-MM-dd HH:mm" }
+}
+```
+
+### 3.5 created_at / updated_at
+
+系统创建时间 / 系统更新时间字段；可配显示格式，但记录写入时应视为只读。
+
+支持字段：`style.format`
+
+默认值 / 约束：
+- `style.format` 默认 `yyyy/MM/dd`
+- 可用格式：`yyyy/MM/dd`、`yyyy/MM/dd HH:mm`、`yyyy/MM/dd HH:mm Z`、`yyyy-MM-dd`、`yyyy-MM-dd HH:mm`、`yyyy-MM-dd HH:mm Z`、`MM-dd`、`MM/dd/yyyy`、`dd/MM/yyyy`
+
+```json
+{ "type": "created_at", "name": "创建时间" }
+```
+
+```json
+{ "type": "updated_at", "name": "更新时间", "style": { "format": "yyyy/MM/dd HH:mm" } }
+```
+
+### 3.6 user / group_chat
+
+人员字段和群字段都支持 `multiple`。
+
+默认值 / 约束：
+- `multiple` 默认 `true`
+
+```json
+{ "type": "user", "name": "负责人", "multiple": true }
+```
+
+```json
+{ "type": "group_chat", "name": "负责群", "multiple": true }
+```
+
+### 3.7 created_by / updated_by
+
+系统创建人 / 系统修改人字段；记录写入时应视为只读。
+
+```json
+{ "type": "created_by", "name": "创建人" }
+```
+
+```json
+{ "type": "updated_by", "name": "更新人" }
+```
+
+### 3.8 link
+
+关联字段；`link_table` 必填。
+
+支持字段：`link_table`、`bidirectional`、`bidirectional_link_field_name`
+
+默认值 / 约束：
+- `link_table` 必填
+- `link` 字段的单元格表示“当前记录关联到的对侧表记录集合”
+- `bidirectional` 默认 `false`
+- `bidirectional=true` 时，会在被关联表自动创建一个反向关联字段。任一侧记录的关联关系发生变更时，另一侧对应记录会自动同步更新
+- `bidirectional_link_field_name` 仅在 `bidirectional=true` 时使用
+- 关联字段筛选：这个功能在 Base 前端支持，属于 UI-only 属性，OpenAPI 里不支持，CLI 不能读取、创建或更新；不要根据接口返回缺失判断未配置
+
+```json
+{
+  "type": "link",
+  "name": "关联任务",
+  "link_table": "任务表"
+}
+```
+
+双向关联：
+
+```json
+{
+  "type": "link",
+  "name": "关联任务",
+  "link_table": "任务表",
+  "bidirectional": true,
+  "bidirectional_link_field_name": "反向关联"
+}
+```
+
+更新时注意：
+- `link` 不允许转换为其他类型，其他类型也不能转换为 `link`。
+- 现有 `link` 字段的 `bidirectional` 不能改。
+
+### 3.9 formula
+
+公式字段；`expression` 必填。创建/更新前先读 [formula-field-guide.md](formula-field-guide.md) 学习公式语法。
+
+```json
+{
+  "type": "formula",
+  "name": "合计",
+  "expression": "1+1"
+}
+```
+
+### 3.10 lookup
+
+查找引用字段；`from`、`select`、`where` 必填，`aggregate` 可选。创建/更新前先读 [lookup-field-guide.md](lookup-field-guide.md)。
+
+支持字段：`from`、`select`、`where`、`aggregate`
+
+默认值 / 约束：
+- `from`、`select`、`where` 必填
+- `aggregate` 默认 `raw_value` 代表不进行聚合，直接返回 select 回的原始值
+- `aggregate` 可用：`raw_value`、`sum`、`average`、`counta`、`unique_counta`、`max`、`min`、`unique`
+- `where.logic` 默认 `and`，仅支持 `and` / `or`
+- `where.conditions` 至少 1 条
+- `conditions` 每项是三元组 `[field, op, value?]`
+
+```json
+{
+  "type": "lookup",
+  "name": "状态汇总",
+  "from": "任务表",
+  "select": "状态",
+  "where": {
+    "logic": "and",
+    "conditions": [
+      ["负责人", "==", { "type": "field_ref", "field": "当前负责人" }],
+      ["状态", "non_empty", null]
+    ]
+  },
+  "aggregate": "raw_value"
+}
+```
+
+### 3.11 auto_number
+
+自动编号字段；不写 `style.rules` 时使用默认规则：`NO.001`。
+
+最小写法：
+
+```json
+{
+  "type": "auto_number",
+  "name": "编号"
+}
+```
+
+支持字段：`style.rules`
+
+默认值 / 约束：
+- `style.rules` 是规则数组，数量 `1..9`
+- 默认规则：
+
+```json
+{
+  "style": {
+    "rules": [
+      { "type": "text", "text": "NO." },
+      { "type": "incremental_number", "length": 3 }
+    ]
+  }
+}
+```
+
+#### `text`
+
+支持字段：`text`
+
+```json
+{ "type": "text", "text": "TASK-" }
+```
+
+#### `incremental_number`
+
+支持字段：`length`
+
+默认值 / 约束：
+- `length` 取值 `1..9`
+
+```json
+{ "type": "incremental_number", "length": 4 }
+```
+
+#### `created_time`
+
+支持字段：`date_format`
+
+默认值 / 约束：
+- `date_format` 可用：`yyyyMMdd`、`yyyyMM`、`yyMM`、`MMdd`、`yyyy`、`MM`、`dd`
+
+```json
+{ "type": "created_time", "date_format": "yyyyMMdd" }
+```
+
+自定义规则：
+
+```json
+{
+  "type": "auto_number",
+  "name": "编号",
+  "style": {
+    "rules": [
+      { "type": "text", "text": "TASK-" },
+      { "type": "created_time", "date_format": "yyyyMMdd" },
+      { "type": "incremental_number", "length": 4 }
+    ]
+  }
+}
+```
+
+### 3.12 attachment / location / checkbox
+
+```json
+{ "type": "attachment", "name": "附件" }
+```
+
+```json
+{ "type": "location", "name": "位置" }
+```
+
+写入必须使用 `{lng,lat}`。location 读回会包含 `full_address`；筛选和 `location -> text` 类型转换按 `full_address` 字符串处理，只有公式能访问坐标。
+
+```json
+{ "type": "checkbox", "name": "完成" }
+```
+
+## 4. 创建与更新
+
+- `+field-create`：按目标字段配置直接构造 `--json`。
+- `+field-update`：使用同样的 JSON 结构，但语义是 `PUT`；建议先 `+field-get`，再按目标完整状态提交，并带 `--yes`。
+
+## 5. 暂不支持字段
+
+Object（对象字段）、Button（按钮字段）、Stage（流程字段）暂时都没有被 CLI 支持。这些字段会展示为 `not_support` 字段并被保护：不允许修改，不允许读取内容。
+
+## 6. 易错点
+
+- `select` 只有一个类型；不要写 `single_select` / `multi_select`，用 `multiple` 控制是否多选。
+- `number` 的精度、货币、进度、评分配置都放在 `style` 下，不要写顶层 `precision`。
+- `datetime` 是手动日期字段；系统时间请改用 `created_at` / `updated_at`。
+- `formula` / `lookup` 没读 guide 前不要直接写。

package/skills/lark-base/references/lark-base-field-update.md

@@ -0,0 +1,171 @@
+# base +field-update
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+更新一个已有字段。
+
+## 推荐命令
+
+```bash
+lark-cli base +field-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --field-id <field_id> \
+  --json '{"name":"状态","type":"select","multiple":false,"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Doing","hue":"Orange","lightness":"Light"},{"name":"Done","hue":"Green","lightness":"Light"}]}' \
+  --yes
+
+lark-cli base +field-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --field-id <field_id> \
+  --json '{"name":"负责人","type":"user","multiple":false,"description":"用于标记记录的直接负责人"}' \
+  --yes
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--field-id <id_or_name>` | 是 | 字段 ID 或字段名 |
+| `--json <body>` | 是 | 字段属性 JSON 对象 |
+| `--yes` | 是 | 确认执行高风险字段更新 |
+
+> 这是**高风险写入操作**。`+field-update` 使用 `PUT` 全量字段定义语义；改变字段类型或关键配置可能影响整列已有数据的解释、展示或可用性。CLI 层要求显式传 `--yes`；如果用户已经明确目标和期望更新，可直接执行并带上 `--yes`。
+
+## API 入参详情
+
+**HTTP 方法和路径：**
+
+```
+PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
+```
+
+## JSON 值规范
+
+- `--json` 必须是 **JSON 对象**，顶层直接传字段定义。
+- 更新语义是 `PUT`（全量字段配置更新），不要只传零散片段；至少显式包含 `name`、`type`，并补齐该类型所需关键配置。
+- 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接。
+- `select` 更新时：`options` 仍按对象数组传，避免混入无效字段。
+- `link` 更新限制：
+  - 不能把非 `link` 字段改成 `link`，也不能把 `link` 改成非 `link`。
+  - 现有 `link` 字段的 `bidirectional` 不能改。
+
+**推荐更新示例**
+
+```json
+{
+  "name": "状态",
+  "type": "select",
+  "multiple": false,
+  "options": [
+    { "name": "Todo", "hue": "Blue", "lightness": "Lighter" },
+    { "name": "Doing", "hue": "Orange", "lightness": "Light" },
+    { "name": "Done", "hue": "Green", "lightness": "Light" }
+  ]
+}
+```
+
+**字段说明示例**
+
+```json
+{
+  "name": "负责人",
+  "type": "user",
+  "multiple": false,
+  "description": "用于标记记录的直接负责人"
+}
+```
+
+## 返回重点
+
+- 返回 `field` 和 `updated: true`。
+
+## 工作流
+
+
+1. 建议先用 `+field-get` 拉现状，再做最小化修改。
+2. `formula/lookup` 类型更新前先阅读对应指南。
+3. 如果这次更新会改变字段 `type` 先按下方“字段类型变更规则”判断能否执行。如果不修改 `type`，大多数场景都相对安全。
+
+## 字段类型变更规则
+
+字段类型变更采用白名单机制：**只允许白名单转换**；未命中白名单时，**不建议用 CLI 转换字段类型** 除非用户明确知道风险并同意。
+
+### 允许直接转换 type
+
+先 `+field-get` / `+field-list` 看结构，再抽样读值；只有命中以下规则时，转换才是比较安全的。
+
+#### 相对安全
+
+| 目标类型 | 允许的源类型 | 说明 |
+|------|------|------|
+| `text` | `number`、`select`、`datetime`、`created_at`、`updated_at`、`location`（只保留 `full_address`）、`auto_number`、`checkbox` | 保留字符串表示；丢失原类型语义和结构化能力 |
+| `number` | `text`、`number`、`datetime`、`created_at`、`updated_at`、`checkbox` | 保留可解析的数字值；无法解析的值会变空，原文本格式会丢失 |
+| `datetime` | `text`、`number`、`datetime`、`created_at`、`updated_at` | 保留可解析的时间字符串和时间戳；无法解析的值会变空，原文本格式会丢失 |
+| `select` | `text -> select`、`number -> select`、`single select -> multi select` | 只有完全匹配目标选项名的值会转成对应选项；没匹配上的值会被丢弃 |
+
+#### 可执行但会截断 / 重算
+
+- `select(multi) -> select(single)`: 只保留第一个值，其余值会被丢弃。
+- `user(multi) -> user(single)`: 只保留第一个人员，其余值会被丢弃。
+- `group_chat(multi) -> group_chat(single)`: 只保留第一个群，其余值会被丢弃。
+
+#### 无状态字段可直接转换
+
+- `created_at`、`created_by`、`updated_at`、`updated_by`、`formula`、`lookup`: 这类字段值由系统或计算逻辑生成，不承载独立存储数据；可以执行类型转换，不必担心破坏原始记录值，但仍要做下游读回验证。
+
+### 一律不要用 CLI 转换
+
+以下场景全部视为黑名单；默认要求用户改到 Web 页面手动完成，或改走“新建字段 + 数据迁移”。
+
+- `any -> checkbox`
+- `any -> user`
+- `any -> group_chat`
+- `any -> attachment`
+- `any -> location`
+- `link` 类型变更
+- 任意涉及动态 / 静态选项来源切换的 `select` 类型变更
+
+### 可例外继续执行的场景
+
+只有在**整列数据丢失可接受**时，才允许对黑名单场景例外执行。
+
+- `EmptyColumn`: 该列为空
+- `FreshTableInit`: 新建空表初始化
+- `PrimaryFieldBootstrap`: 主列不能删，只能更新完成初始化
+- `ExplicitLossAccepted`: 用户明确接受整列数据丢失
+
+不满足以上条件时，不要转换。
+
+### 非白名单场景如何处理
+
+- 命中白名单时：建议直接原地转换，再做读回验证。
+- 未命中白名单时：先询问用户是否仍要执行转换，并明确说明风险：
+  - 无状态字段除外；这类字段可以直接转换
+  - 可能整列变空
+  - 可能只保留第一个值
+  - 可能只保留字符串表示，丢失原类型语义和结构化能力
+  - 可能影响视图 / 筛选 / 排序 / 公式 / lookup / 写入引用
+- 如果用户不接受风险：不要执行转换。
+
+### 完成态验证
+
+- `FieldReadback`: 读回字段结构，确认 `type` / `multiple` / `style` / `options`
+- `ValueReadback`: 抽样读回转换后的单元格值
+- `DownstreamReadback`: 若涉及看板 / 分组 / 排序 / lookup / 公式，继续读回结果
+- `CompletionRule`: 结构、值、下游能力都正确，才能回复“已完成”
+
+## 坑点
+
+- ⚠️ 这是全量字段属性更新语义，不是 patch。
+- ⚠️ 这是高风险写入操作，执行时必须带 `--yes`。
+- ⚠️ 当 `type` 是 `formula` 或 `lookup` 时，先阅读对应指南再执行。
+
+## 参考
+
+- 更新前读取当前字段，确认现有 `type` 和具体配置细节，再决定是原地更新还是新建字段迁移。
+- [lark-base-field-json.md](lark-base-field-json.md) — 字段 JSON 规范（推荐）
+- [formula-field-guide.md](formula-field-guide.md) — formula 指南（更新公式前必读）
+- [lookup-field-guide.md](lookup-field-guide.md) — lookup 指南（更新查找引用前必读）