diff --git a/shortcuts/base/base_execute_test.go b/shortcuts/base/base_execute_test.go index 741b2f0e37..80463ff464 100644 --- a/shortcuts/base/base_execute_test.go +++ b/shortcuts/base/base_execute_test.go @@ -432,7 +432,7 @@ func TestBaseFieldExecuteUpdate(t *testing.T) { "data": map[string]interface{}{"id": "fld_x", "name": "Amount", "type": "number"}, }, }) - if err := runShortcut(t, BaseFieldUpdate, []string{"+field-update", "--base-token", "app_x", "--table-id", "tbl_x", "--field-id", "fld_x", "--json", `{"name":"Amount","type":"number"}`}, factory, stdout); err != nil { + if err := runShortcut(t, BaseFieldUpdate, []string{"+field-update", "--base-token", "app_x", "--table-id", "tbl_x", "--field-id", "fld_x", "--json", `{"name":"Amount","type":"number"}`, "--yes"}, factory, stdout); err != nil { t.Fatalf("err=%v", err) } if got := stdout.String(); !strings.Contains(got, `"updated": true`) || !strings.Contains(got, `"fld_x"`) { diff --git a/shortcuts/base/base_shortcuts_test.go b/shortcuts/base/base_shortcuts_test.go index eeca3b8d1d..7a9df7c8d1 100644 --- a/shortcuts/base/base_shortcuts_test.go +++ b/shortcuts/base/base_shortcuts_test.go @@ -167,6 +167,12 @@ func TestBaseTableDeleteRisk(t *testing.T) { } } +func TestBaseFieldUpdateRisk(t *testing.T) { + if BaseFieldUpdate.Risk != "high-risk-write" { + t.Fatalf("risk=%q want=%q", BaseFieldUpdate.Risk, "high-risk-write") + } +} + func TestBaseDeleteShortcutsRisk(t *testing.T) { cases := map[string]string{ BaseFieldDelete.Command: BaseFieldDelete.Risk, diff --git a/shortcuts/base/field_update.go b/shortcuts/base/field_update.go index 03999c0224..f8e8a47d08 100644 --- a/shortcuts/base/field_update.go +++ b/shortcuts/base/field_update.go @@ -13,7 +13,7 @@ var BaseFieldUpdate = common.Shortcut{ Service: "base", Command: "+field-update", Description: "Update a field by ID or name", - Risk: "write", + Risk: "high-risk-write", Scopes: []string{"base:field:update"}, AuthTypes: authTypes(), Flags: []common.Flag{ diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md index b3585ad487..2abc724ab6 100644 --- a/skills/lark-base/SKILL.md +++ b/skills/lark-base/SKILL.md @@ -96,7 +96,7 @@ metadata: | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | |------|------------------|----------------|----------| | `+field-list / +field-get` | 列出字段结构,或获取单个字段详情 | [`lark-base-field-list.md`](references/lark-base-field-list.md)、[`lark-base-field-get.md`](references/lark-base-field-get.md) | 写记录、写字段、做分析前常先读 `+field-list`;`+field-list` 只能串行执行;`+field-get` 适合删除/更新前确认目标 | -| `+field-create / +field-update / +field-delete` | 创建、更新或删除普通字段 | [`lark-base-field-create.md`](references/lark-base-field-create.md)、[`lark-base-field-update.md`](references/lark-base-field-update.md)、[`lark-base-field-delete.md`](references/lark-base-field-delete.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 写字段前先看字段属性规范;如果涉及类型转换,直接按 `+field-update` 中的字段类型变更规则执行,只在安全白名单内考虑原地转换;如果类型是 `formula / lookup`,先转去读对应 guide;删除时用户已明确目标可直接执行并带 `--yes` | +| `+field-create / +field-update / +field-delete` | 创建、更新或删除普通字段 | [`lark-base-field-create.md`](references/lark-base-field-create.md)、[`lark-base-field-update.md`](references/lark-base-field-update.md)、[`lark-base-field-delete.md`](references/lark-base-field-delete.md)、[`lark-base-shortcut-field-properties.md`](references/lark-base-shortcut-field-properties.md) | 写字段前先看字段属性规范;如果涉及类型转换,直接按 `+field-update` 中的字段类型变更规则执行,只在安全白名单内考虑原地转换;如果类型是 `formula / lookup`,先转去读对应 guide;更新或删除时用户已明确目标可直接执行并带 `--yes` | | `+field-search-options` | 查询字段可选项 | [`lark-base-field-search-options.md`](references/lark-base-field-search-options.md) | 适合单选/多选等选项型字段 | #### 2.3.3 Record 子模块 @@ -326,7 +326,7 @@ lark-cli auth login --domain base ### 4.4 确认与回复规则 - 视图重命名时,用户已明确“把哪个视图改成什么名字”时,`+view-rename` 直接执行即可。 -- 删除记录 / 字段 / 表时,如果用户已经明确说要删除,且目标明确,`+record-delete / +field-delete / +table-delete` 可直接执行,并带 `--yes`。 +- 更新字段或删除记录 / 字段 / 表时,如果用户已经明确目标,`+field-update / +record-delete / +field-delete / +table-delete` 可直接执行,并带 `--yes`。 - 删除目标仍有歧义时,先用 `+record-get / +field-get / +table-get` 或相应 list 命令确认。 - `+base-create / +base-copy` 成功后,回复中必须主动返回新 Base 的标识信息;若结果带可访问链接,也应一并返回。 - 若 Base 由 bot 身份创建或复制,shortcut 会自动尝试为当前 CLI 用户补授 `full_access`,并在输出中返回 `permission_grant`;agent 不需要再手动编排单独授权。owner 转移必须单独确认,禁止擅自执行。 diff --git a/skills/lark-base/references/formula-field-guide.md b/skills/lark-base/references/formula-field-guide.md index df89fdb73d..5d9a46350b 100644 --- a/skills/lark-base/references/formula-field-guide.md +++ b/skills/lark-base/references/formula-field-guide.md @@ -6,6 +6,8 @@ When creating or updating a formula field with `lark-cli base +field-create/+fie Do **not** proactively add `--i-have-read-guide` before reading this guide. Without it, the CLI will fail fast and direct you back to this guide. +When using `+field-update`, also pass `--yes`: field update is a high-risk `PUT` operation because changing a field definition can affect the whole column. + ## Default strategy **All cross-table references, aggregations, and computed fields should use Formula fields by default.** Do NOT use Lookup fields unless the user explicitly requests it. Formula is a strict superset of Lookup — anything Lookup can do, Formula can do with a single expression. diff --git a/skills/lark-base/references/lark-base-field-update.md b/skills/lark-base/references/lark-base-field-update.md index c81370609c..76511a4d25 100644 --- a/skills/lark-base/references/lark-base-field-update.md +++ b/skills/lark-base/references/lark-base-field-update.md @@ -11,13 +11,15 @@ lark-cli base +field-update \ --base-token \ --table-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"}]}' + --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 \ --table-id \ --field-id \ - --json '{"name":"负责人","type":"user","multiple":false,"description":"用于标记记录的直接负责人"}' + --json '{"name":"负责人","type":"user","multiple":false,"description":"用于标记记录的直接负责人"}' \ + --yes ``` ## 参数 @@ -28,6 +30,10 @@ lark-cli base +field-update \ | `--table-id ` | 是 | 表 ID 或表名 | | `--field-id ` | 是 | 字段 ID 或字段名 | | `--json ` | 是 | 字段属性 JSON 对象 | +| `--yes` | 是 | 确认执行高风险字段更新 | + +> 这是**高风险写入操作**。`+field-update` 使用 `PUT` 全量字段定义语义;改变字段类型或关键配置可能影响整列已有数据的解释、展示或可用性。CLI 层要求显式传 `--yes`;如果用户已经明确目标和期望更新,可直接执行并带上 `--yes`。 + ## API 入参详情 **HTTP 方法和路径:** @@ -154,7 +160,7 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id ## 坑点 - ⚠️ 这是全量字段属性更新语义,不是 patch。 -- ⚠️ 这是写入操作,执行前必须确认。 +- ⚠️ 这是高风险写入操作,执行时必须带 `--yes`。 - ⚠️ 当 `type` 是 `formula` 或 `lookup` 时,先阅读对应指南再执行。 ## 参考 diff --git a/skills/lark-base/references/lark-base-shortcut-field-properties.md b/skills/lark-base/references/lark-base-shortcut-field-properties.md index a794e88534..ea6ebb1a32 100644 --- a/skills/lark-base/references/lark-base-shortcut-field-properties.md +++ b/skills/lark-base/references/lark-base-shortcut-field-properties.md @@ -10,7 +10,7 @@ - 顶层统一使用:`type` + `name` + 类型特有字段。 - 所有字段类型都支持可选 `description`;支持纯文本,也支持 Markdown 链接。 - 不要使用旧结构:`field_name`、`property`、`ui_type`、数字枚举 `type`。 -- `+field-update` 使用同样的字段 JSON 结构,但语义是 `PUT`;建议先 `+field-get` 再按目标状态全量提交。 +- `+field-update` 使用同样的字段 JSON 结构,但语义是 `PUT`;这是高风险写入操作,建议先 `+field-get` 再按目标状态全量提交,并带 `--yes`。 - `type=formula` 或 `type=lookup` 创建/更新前,必须先读对应 guide。 推荐示例: @@ -471,7 +471,7 @@ ## 4. 创建与更新 - `+field-create`:按目标字段配置直接构造 `--json`。 -- `+field-update`:使用同样的 JSON 结构,但语义是 `PUT`;建议先 `+field-get`,再按目标完整状态提交。 +- `+field-update`:使用同样的 JSON 结构,但语义是 `PUT`;建议先 `+field-get`,再按目标完整状态提交,并带 `--yes`。 ## 5. 易错点 diff --git a/skills/lark-base/references/lookup-field-guide.md b/skills/lark-base/references/lookup-field-guide.md index 27d22f1b24..499aa0539f 100644 --- a/skills/lark-base/references/lookup-field-guide.md +++ b/skills/lark-base/references/lookup-field-guide.md @@ -6,6 +6,8 @@ When creating or updating a lookup field with `lark-cli base +field-create/+fiel Do **not** proactively add `--i-have-read-guide` before reading this guide. Without it, the CLI will fail fast and direct you back to this guide. +When using `+field-update`, also pass `--yes`: field update is a high-risk `PUT` operation because changing a field definition can affect the whole column. + ## Default strategy **Use Formula fields by default for cross-table references and aggregations.** Only use Lookup fields when the user explicitly requests a Lookup field. Formula is a strict superset of Lookup — anything Lookup can do, Formula can do with a single expression.