@yandy0725/pi-lark 0.1.0

package/skills/lark-base/references/lark-base-role-guide.md

@@ -0,0 +1,65 @@
+# Base advanced permission and role guide
+
+This guide is the entry point for Base advanced permissions and roles. Use it to choose commands and understand safety boundaries. For the permission JSON itself, use [role-config.md](role-config.md) as the SSOT.
+
+## Command selection
+
+| Goal | Command | Notes |
+|------|---------|-------|
+| Enable advanced permissions | `+advperm-enable` | Required before creating or updating roles. Caller must be a Base admin. |
+| Disable advanced permissions | `+advperm-disable` | High-risk write. Disabling invalidates existing custom roles. |
+| Locate roles | `+role-list` | Returns role summaries. Use `+role-get` for full config. |
+| Inspect one role | `+role-get` | Use before updating a role or deciding whether a role can be deleted. |
+| Create a custom role | `+role-create` | Supports `custom_role` only. Read [role-config.md](role-config.md) before constructing `--json`. |
+| Update a role | `+role-update` | Delta merge. Read current config first, then send only intended changes. |
+| Delete a role | `+role-delete` | Custom roles only. System roles cannot be deleted. |
+
+## Safety boundaries
+
+- Role operations require advanced permissions to be enabled and the caller to be a Base admin.
+- `+role-create` creates custom roles only.
+- `+role-delete` is only for custom roles. System roles such as editor/reader can be configured within supported limits, but cannot be deleted.
+- `+role-update` uses delta merge: omitted fields remain unchanged, but identity fields such as `role_name` and `role_type` should match the current target role.
+- `+advperm-disable` invalidates existing custom roles; confirm the target Base and user intent before passing `--yes`.
+
+## Common Fewshots
+
+Use these fewshots for simple role changes. For table, field, record, dashboard, docx, or filter permission details, switch to [role-config.md](role-config.md).
+
+Create a custom role that keeps copy/download disabled:
+
+```bash
+lark-cli base +role-create \
+  --base-token <base_token> \
+  --json '{"role_name":"Reviewer","role_type":"custom_role","base_rule_map":{"copy":false,"download":false}}'
+```
+
+Rename a role while preserving its type:
+
+```bash
+lark-cli base +role-update \
+  --base-token <base_token> \
+  --role-id <role_id> \
+  --json '{"role_name":"Finance Reviewer","role_type":"custom_role"}' \
+  --yes
+```
+
+Grant read-only access to one table:
+
+```bash
+lark-cli base +role-update \
+  --base-token <base_token> \
+  --role-id <role_id> \
+  --json '{"role_name":"Finance Reviewer","role_type":"custom_role","table_rule_map":{"Orders":{"perm":"read_only"}}}' \
+  --yes
+```
+
+## JSON SSOT
+
+Use [role-config.md](role-config.md) for:
+
+- `AdvPermBaseRoleConfig` top-level structure.
+- `base_rule_map`, `table_rule_map`, `dashboard_rule_map`, and `docx_rule_map`.
+- Table, view, field, record, dashboard, and docx permission values.
+- Filter permission JSON.
+- Default permission strategy and risk rules.

package/skills/lark-base/references/lark-base-view-set-filter.md

@@ -0,0 +1,189 @@
+# base +view-set-filter
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+更新视图筛选配置。
+
+## 1. 顶层规则
+
+- `--json` 必须是 JSON 对象。
+- 顶层结构是 `{logic?, conditions?}`。
+- `logic` 默认 `and`；推荐只用 canonical 值 `and` / `or`。
+- `conditions` 默认空数组。
+- 每条条件写成 tuple：`[field, operator, value?]`。
+- `empty` / `non_empty` 可写成 2 项：`[field, "empty"]`、`[field, "non_empty"]`。
+- 支持 `filter` 的视图类型：`grid`、`kanban`、`gallery`、`calendar`、`gantt`。
+
+## 2. operator
+
+可用 operator：
+- `==`
+- `!=`
+- `>`
+- `>=`
+- `<`
+- `<=`
+- `intersects`
+- `disjoint`
+- `empty`
+- `non_empty`
+
+## 3. value 写法
+
+### `text`
+
+用字符串：
+
+```json
+["标题", "intersects", "发布"]
+```
+
+### `location`
+
+location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度筛选；优先使用 `intersects` 做包含匹配，例如查深圳：
+
+```json
+["位置", "intersects", "深圳"]
+```
+
+不推荐写 `["位置", "==", "深圳"]` 这类精确匹配，除非确保筛选值与完整 `full_address` 完全一致。
+
+### `number` / `auto_number`
+
+用数字：
+
+```json
+["工时", ">=", 3.5]
+```
+
+### `select`
+
+用选项名数组：
+
+```json
+["状态", "intersects", ["Doing", "Blocked"]]
+```
+
+### `user` / `created_by` / `updated_by`
+
+用对象数组：
+
+> **人员筛选：不要猜 ID。** 不知道 `open_id` 时，先用 `lark-contact` 查 id：`lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user`。
+
+```json
+["负责人", "intersects", [{ "id": "ou_xxx" }]]
+```
+
+### `group_chat`
+
+用对象数组：
+
+> **群组筛选：不要猜 ID。** 不知道 `chat_id` 时，先用 `lark-im` 搜群：`lark-cli im +chat-search --query "<群名关键词>" --as user`；取结果里的 `oc_xxx`。
+
+```json
+["负责群", "intersects", [{ "id": "oc_xxx" }]]
+```
+
+### `link`
+
+用记录 id 对象数组：
+
+```json
+["关联任务", "intersects", [{ "id": "rec_xxx" }]]
+```
+
+### `checkbox`
+
+用布尔值：
+
+```json
+["完成", "==", true]
+```
+
+### `datetime` / `created_at` / `updated_at`
+
+用相对时间关键字或 `ExactDate(...)`：
+
+```json
+["截止时间", "==", "ExactDate(2026-01-01)"]
+```
+
+```json
+["截止时间", "==", "ExactDate(2026-01-01 11:30)"]
+```
+
+```json
+["截止时间", "==", "Today"]
+```
+
+可用关键字：
+- `Today`
+- `Yesterday`
+- `Tomorrow`
+
+### `formula` / `lookup`
+
+- 筛选值类型由字段计算结果类型动态决定。
+- 拿不准时，先把 `value` 当作单个字符串填入做一次尝试。
+- 如果报错，再按错误提示把 `value` 改成对应类型。
+
+字符串示例：
+
+```json
+["风险说明", "intersects", "高风险"]
+```
+
+数字示例：
+
+```json
+["汇总分", ">=", 80]
+```
+
+## 4. 推荐命令
+
+```bash
+lark-cli base +view-set-filter \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --view-id <view_id> \
+  --json '{"logic":"and","conditions":[["状态","intersects",["Doing"]],["负责人","intersects",[{"id":"ou_xxx"}]],["截止时间","empty"]]}'
+```
+
+## 5. JSON 写法
+
+```json
+{
+  "logic": "and",
+  "conditions": [
+    ["状态", "intersects", ["Doing"]],
+    ["负责人", "intersects", [{ "id": "ou_xxx" }]],
+    ["截止时间", "empty"]
+  ]
+}
+```
+
+清空写法：
+
+```json
+{
+  "conditions": []
+}
+```
+
+## 6. 使用建议
+
+- 先读取当前筛选配置，理解现有 `logic` 和 `conditions` 的组合关系；只替换用户要求变更的条件，未提到的条件默认保留。
+- 优先传字段 id，不要依赖字段名。
+- 需要清空全部筛选时，直接传 `{"conditions":[]}`。
+
+## 7. 易错点
+
+- 不要再写旧对象风格：`{"field_name":...,"operator":...}`。
+- `user` / `group_chat` / `link` 不要写成单个标量。
+- `empty` / `non_empty` 不要硬塞无意义的 value。
+- 日期条件稳定写法用 `ExactDate(...)` 或 `Today` / `Yesterday` / `Tomorrow`。
+- `formula` / `lookup` 的 value 形状不固定；拿不准时先读当前 filter 或字段定义，或根据错误提示修正类型。
+
+## 8. 参考
+
+- [lookup-field-guide.md](lookup-field-guide.md)