Skip to content

Commit 0873d47

Browse files
jiangguozhoujiangguozhou
committed
docs: add lark-drive permission governance workflow
Change-Id: I4d886ea68f95271a66e552839f71ab566a6a7df7
1 parent f3949f0 commit 0873d47

5 files changed

Lines changed: 739 additions & 0 deletions

‎skills/lark-drive/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ metadata:
1818
1919
## 快速决策
2020

21+
- 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签**，或要“权限风险报告、收紧权限、申请查看 / 编辑权限”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
2122
- 用户要**整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库**，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 [`references/lark-drive-workflow-knowledge-organize.md`](references/lark-drive-workflow-knowledge-organize.md)。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
2223
- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--mine`，实为 owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
2324
- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。

‎skills/lark-drive/references/lark-drive-workflow-permission-governance-commands.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# 权限治理 Command Patterns
2+
3+
本文只提供 `permission_governance` workflow 的具体 `lark-cli` 命令样例。只有进入对应 state 且需要拼装命令时才读取本文；命令可用范围仍以 [`lark-drive-workflow-permission-governance.md`](lark-drive-workflow-permission-governance.md) 的 `Command Map` 为准。
4+
5+
## 目录
6+
7+
- `目标解析`
8+
- `目标发现`
9+
- `事实读取`
10+
- `写前确认与执行`
11+
12+
## 目标解析
13+
14+
```bash
15+
lark-cli drive +inspect --url '<url>' --as user --format json
16+
```
17+
18+
`/wiki/space/<space_id>` URL 是 Wiki space 范围，不要用 `drive +inspect` 当作单文档解析；直接提取 `space_id` 后进入 `DISCOVER_TARGETS`。
19+
20+
## 目标发现
21+
22+
发现 Wiki space / node 下目标：
23+
24+
```bash
25+
lark-cli wiki +node-list \
26+
--space-id '<space_id>' --page-size 50 \
27+
--as user --format json
28+
29+
lark-cli wiki +node-list \
30+
--space-id '<space_id>' --parent-node-token '<node_token>' --page-size 50 \
31+
--as user --format json
32+
```
33+
34+
发现 Drive folder 下目标：
35+
36+
```bash
37+
lark-cli drive files list \
38+
--params '{"folder_token":"<folder_token>","page_size":200}' \
39+
--as user --format json
40+
41+
lark-cli drive files list \
42+
--params '{"folder_token":"<folder_token>","page_size":200,"page_token":"<PAGE_TOKEN>"}' \
43+
--as user --format json
44+
```
45+
46+
## 事实读取
47+
48+
读取 metadata：
49+
50+
```bash
51+
lark-cli drive metas batch_query \
52+
--data '{"request_docs":[{"doc_token":"<token>","doc_type":"<type>"}],"with_url":true}' \
53+
--as user --format json
54+
```
55+
56+
读取 public permission：
57+
58+
```bash
59+
lark-cli drive permission.public get \
60+
--params '{"token":"<token>","type":"<type>"}' \
61+
--as user --format json
62+
```
63+
64+
按需读取访问统计：
65+
66+
```bash
67+
lark-cli drive file.statistics get \
68+
--params '{"file_token":"<token>","file_type":"<type>"}' \
69+
--as user --format json
70+
```
71+
72+
按需读取最近访问记录：
73+
74+
```bash
75+
lark-cli drive file.view_records list \
76+
--params '{"file_token":"<token>","file_type":"<type>","page_size":50}' \
77+
--as user --format json
78+
```
79+
80+
## 写前确认与执行
81+
82+
patch 前检查 manage-public permission：
83+
84+
```bash
85+
lark-cli drive permission.members auth \
86+
--params '{"token":"<token>","type":"<type>","action":"manage_public"}' \
87+
--as user --format json
88+
```
89+
90+
显式确认后 patch public permission：
91+
92+
```bash
93+
lark-cli drive permission.public patch \
94+
--params '{"token":"<token>","type":"<type>"}' \
95+
--data '{"link_share_entity":"closed","external_access":false}' \
96+
--as user --yes --format json
97+
```
98+
99+
显式确认后申请访问权限：
100+
101+
```bash
102+
lark-cli drive +apply-permission \
103+
--token '<url>' \
104+
--perm view --remark '<reason>' --as user --format json
105+
106+
lark-cli drive +apply-permission \
107+
--token '<bare-token>' --type '<type>' \
108+
--perm view --remark '<reason>' --as user --format json
109+
```
110+
111+
显式确认后更新 secure label：
112+
113+
```bash
114+
lark-cli drive +secure-label-update \
115+
--token '<url>' \
116+
--label-id '<label-id>' --as user --format json
117+
118+
lark-cli drive +secure-label-update \
119+
--token '<bare-token>' --type '<type>' \
120+
--label-id '<label-id>' --as user --format json
121+
```

‎skills/lark-drive/references/lark-drive-workflow-permission-governance-outputs.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# 权限治理输出模板
2+
3+
本文只提供 `permission_governance` workflow 的用户可见输出模板。默认先给简短摘要；只有用户要求完整表格、需要写入确认，或结果大到需要结构化展示时才读取本文。
4+
5+
## 目录
6+
7+
- `输出策略`
8+
- `用户语言映射`
9+
- `定位与治理动作`
10+
- `审计摘要`
11+
- `容器安全诊断报告摘要`
12+
- `可操作风险清单`
13+
- `治理选择交互`
14+
- `权限设置清单`
15+
- `访问复核清单`
16+
- `整改 dry-run`
17+
- `批量权限申请确认`
18+
- `确认请求`
19+
- `最终摘要`
20+
21+
## 输出策略
22+
23+
- 单目标默认输出审计摘要。
24+
- 容器目标默认输出安全诊断报告摘要：一句话结论、覆盖情况、风险分级、优先处理对象、建议下一步和剩余限制。
25+
- 容器目标不要把风险按数量机械排序；外部公开、允许对外分享、缺失密级标签优先于复制 / 下载 / 评论这类依赖策略的候选项。
26+
- 用户没有提供明确 policy 时，使用“候选风险 / 待复核 / 待策略确认”，不要写“违规 / 已泄露 / 已外部访问”。
27+
- 风险对象展示按规模渐进披露：1-10 个全部展示；11-30 个展示全部高优先级待处理对象，中 / 低优先级只做分组摘要；31-100 个按高优先级分组展示 Top 5 和数量；100+ 个只展示分组统计和 Top 样例。
28+
- 当摘要未展示全部风险对象时，必须明确“完整清单包含 <count> 条”，并提供生成 Markdown / CSV / 飞书文档风险清单或整改 dry-run 的下一步。
29+
- 只要发现需要处理的对象，最终回复必须给出可执行下一步 CTA。不能因为默认只读，就只报告风险后结束。
30+
- 完整风险清单是后续治理选择的输入；Markdown / CSV / 飞书文档报告必须使用同一套字段和稳定 `risk_id`。
31+
- 写入前必须使用确认模板；权限申请、public-permission patch、secure-label update 分别确认。
32+
- 最终回复必须包含已完成事项、验证结果和剩余限制；异步 owner 审批不能表述为已完成授权。
33+
34+
## 用户语言映射
35+
36+
面向用户的主结论优先使用业务语言；底层字段名只在证据或完整清单中保留。
37+
38+
| 底层字段 / 值 | 用户可见说法 |
39+
|---------------|--------------|
40+
| `link_share_entity=anyone_readable/anyone_editable` | 互联网公开链接候选风险 |
41+
| `link_share_entity=tenant_readable` | 公司内知道链接可读 |
42+
| `link_share_entity=tenant_editable` | 公司内知道链接可编辑 |
43+
| `link_share_entity=closed` | 未开启链接分享 |
44+
| `external_access=true` | 允许分享到组织外；不等于已经存在外部协作者 |
45+
| `external_access=false` | 不允许分享到组织外 |
46+
| `share_entity=anyone` | 较多人可添加或管理协作者 |
47+
| `share_entity=same_tenant` | 公司内成员可添加或管理协作者 |
48+
| `share_entity=only_full_access` | 仅有管理权限的人可管理协作者 |
49+
| `security_entity` is not `only_full_access` | 复制 / 下载 / 打印范围需要按策略复核 |
50+
| `comment_entity=anyone_can_view` | 可查看者都能评论 |
51+
| `sec_label_name` missing | 缺少密级标签 |
52+
53+
## 定位与治理动作
54+
55+
风险对象必须能让用户直接定位和处理：
56+
57+
- 摘要中的每个优先处理对象必须包含 `path/title`、`URL`、`type`、风险原因、关键证据和建议动作。
58+
- 完整清单、访问复核清单、整改 dry-run 和写入确认都必须包含 URL。缺少 URL 时，展示 token / node_token，并说明 URL 未能获取。
59+
- 同名文档、shortcut 或副本必须用 path + URL 区分；不要只输出 title。
60+
- 完整风险清单中的每条记录必须有稳定 `risk_id`，格式为 `PG-001`、`PG-002`。`risk_id` 在同一次诊断和后续 dry-run / 确认 / 验证中保持不变。
61+
- 建议动作必须和风险类型绑定：互联网公开链接优先建议关闭链接分享或收紧为组织内；允许对外分享优先建议 owner 复核或关闭对外分享；缺少密级标签优先建议补齐密级；复制 / 下载 / 评论范围只在用户 policy 明确时建议收紧。
62+
- 写入动作只能作为下一步选项或确认请求出现。不要在诊断摘要里暗示已经执行缩权。
63+
64+
## 摘要清单展开规则
65+
66+
容器安全诊断的摘要必须兼顾可读性和可治理性。不要用固定 Top N 代替可处理清单。
67+
68+
| 风险对象数 | 摘要默认展示 | 必须提供的下一步 |
69+
|------------|--------------|------------------|
70+
| `0` | 只展示覆盖情况、未覆盖能力和剩余限制 | 如需更细审计，可生成权限设置清单 |
71+
| `1-10` | 展示全部风险对象 | 可直接按 `risk_id` 生成 dry-run 或写入确认 |
72+
| `11-30` | 展示全部高优先级待处理对象；中 / 低优先级做分组摘要 | 生成完整风险清单 artifact，或按风险分组生成 dry-run |
73+
| `31-100` | 每个高优先级风险分组展示 Top 5，附未展示数量 | 生成 Markdown / CSV / 飞书文档完整风险清单 |
74+
| `100+` | 只展示分组统计、Top 样例和覆盖限制，不内联长表 | 强烈建议生成结构化风险清单后再选择治理范围 |
75+
76+
高优先级待处理对象包括：互联网公开链接、允许对外分享、允许对外分享且缺少 / 低于 policy 密级标签、公司内可编辑链接、协作者管理范围较宽。复制 / 下载 / 打印、评论范围在用户未提供明确 policy 时归入“待策略确认”，不要挤占高优先级清单。
77+
78+
摘要中的每个待处理对象必须包含 `risk_id`、path/title、URL、type、风险原因、关键证据和建议动作。对同一底层文档的多个 Wiki 入口或 shortcut，必须用 URL 区分；如果建议合并治理，在建议动作里说明它们指向同一底层对象。
79+
80+
## 审计摘要
81+
82+
```text
83+
目标：<title> (<type>)
84+
URL：<url-or-token-if-url-unavailable>
85+
结论：<合规 / 待确认风险 / 无法完整判断>
86+
证据：
87+
- link_share_entity=<value>
88+
- external_access=<value>
89+
- share_entity=<value>
90+
- security_entity=<value>
91+
- comment_entity=<value>
92+
- sec_label_name=<value-or-missing>
93+
限制：<unsupported_checks or none>
94+
建议动作：<read-only next step or proposed remediation>
95+
```
96+
97+
## 容器安全诊断报告摘要
98+
99+
```text
100+
已完成只读安全诊断，没有做任何权限修改。
101+
102+
一句话结论：<未发现互联网公开链接 / 存在互联网公开链接候选风险>；<external_access_count> 个文档允许对外分享，<missing_label_count> 个文档缺少密级标签。建议优先复核 <top_priority_group_or_paths>。
103+
104+
覆盖情况：
105+
- 当前身份可见目标：<visible_count>
106+
- 已成功检查公开权限：<permission_checked_count>
107+
- 读取失败 / 已删除 / 无权限：<failed_count>
108+
- 未覆盖能力：<collaborator_list / inheritance / audit_log / view_records / none>
109+
110+
风险分级：
111+
- 高优先级：<internet_public_count> 个互联网公开链接候选；<external_access_count> 个允许对外分享；其中 <external_without_label_count> 个同时缺少密级标签。
112+
- 中优先级：<tenant_link_count> 个公司内知道链接可访问 / 可编辑；<wide_share_count> 个协作者管理范围较宽。
113+
- 待策略确认：<security_count> 个复制 / 下载 / 打印范围待复核；<comment_count> 个评论范围待复核。
114+
- 无法判断：<unsupported_or_unverified_summary>。
115+
116+
高优先级待处理清单：
117+
> 按 `摘要清单展开规则` 展示。每个对象必须包含 `risk_id` 和 URL；缺少 URL 时展示 token / node_token 和原因。若没有高优先级对象，只展示中优先级或待策略确认分组摘要。
118+
119+
- <risk_id> <path-or-title> (<type>)
120+
URL: <url-or-token-if-url-unavailable>
121+
风险：<why high priority>
122+
证据：<short field evidence>
123+
建议动作：<recommended action>
124+
125+
未完全展开：
126+
- 完整风险清单包含 <risk_manifest_count> 条；本摘要已展示 <shown_count> 条，未展示 <hidden_count> 条。
127+
- 未展示分组：<risk_group=count summary or none>
128+
129+
建议下一步：
130+
- 生成完整风险清单 artifact，包含 `risk_id`、URL、证据字段、建议动作和 `selected` 列。
131+
- 基于 risk_id、风险分组、owner、路径、URL 或 artifact 中 `selected=true` 的行生成只读整改 dry-run。
132+
- 只针对最高优先级目标进入写入确认流程，例如关闭互联网公开链接或收紧对外分享；写入前仍需二次确认。
133+
- 按 owner / 密级生成复核清单。
134+
- 继续读取访问记录，判断低活跃高暴露。
135+
136+
剩余限制：
137+
- <do not claim collaborator-list verification if unsupported>
138+
- <external_access=true only means sharing outside is allowed, not that external collaborators exist>
139+
- <missing view_records / DLP / AI index status / audit log limitations>
140+
```
141+
142+
## 可操作风险清单
143+
144+
完整风险清单用于让用户选择后续治理范围。Markdown / CSV / 飞书文档报告都必须包含以下字段；如果某种格式无法完整展示嵌套证据，使用短文本摘要，保留 `risk_id` 和 URL。
145+
146+
```text
147+
范围：<wiki_space / wiki_node / drive_folder> <name-or-id>
148+
生成时间：<timestamp>
149+
用途：用户可按 risk_id、risk_group、owner、path、URL 或 selected=true 选择治理对象。
150+
151+
| risk_id | Path | URL | Type | Owner | risk_group | evidence | recommended_action | current_setting | target_setting | selected | decision | status | skip_reason |
152+
|---------|------|-----|------|-------|------------|----------|--------------------|-----------------|----------------|----------|----------|--------|-------------|
153+
| PG-001 | <path> | <url-or-token> | <type> | <owner-or-unknown> | <risk_group> | <short evidence> | <recommended-action> | <field=value> | <field=value-or-owner-review> | false | undecided | pending | <none-or-reason> |
154+
```
155+
156+
字段规则：
157+
158+
- `risk_id` 按风险优先级和 path 稳定排序生成；同一次诊断中不得重复。
159+
- `selected` 默认 `false`；用户可在 CSV / 飞书文档表格中改为 `true`，或在聊天中直接说 “处理 PG-001、PG-003”。
160+
- `decision` 表示用户决策：`undecided`、`keep`、`dry_run`、`confirm_write`、`skip`。
161+
- `status` 表示执行状态：`pending`、`dry_run_ready`、`confirmed`、`executed`、`verified`、`failed`、`skipped`。
162+
- `target_setting` 是建议目标状态，不代表已执行；没有明确 policy 时只能写 owner review / policy review。
163+
164+
## 治理选择交互
165+
166+
用户基于完整风险清单继续治理时，Agent 必须先解析选择范围，再生成只读 dry-run：
167+
168+
```text
169+
可接受的用户选择：
170+
- 处理 PG-001、PG-003、PG-008，把互联网公开链接关闭。
171+
- 先处理所有 risk_group=internet_public_link，不处理 external_access_only。
172+
- 把 CSV / 飞书文档里 selected=true 的行生成整改 dry-run。
173+
- PG-003 先跳过，只处理 PG-001。
174+
175+
Agent 必须回复：
176+
- 已选择对象数：<count>
177+
- 选择来源：<risk_id list / risk_group / selected=true / URL / path>
178+
- 将执行的下一步：生成 dry-run；不执行写入
179+
- 需要跳过或重新确认的对象：<missing risk_id / unsupported / changed_since_report / no manage_public>
180+
```
181+
182+
如果用户选择来自旧报告或外部 artifact，生成 dry-run 前必须对所选目标重新读取当前权限。当前设置和报告快照不一致时，标记为 `changed_since_report`，不要直接沿用旧字段执行。
183+
184+
## 权限设置清单
185+
186+
```text
187+
范围：<wiki_space / wiki_node / drive_folder> <name-or-id>
188+
189+
| Path | URL | Type | link_share_entity | external_access | share_entity | security_entity | comment_entity | sec_label_name | 建议动作 | 限制 |
190+
|------|-----|------|-------------------|-----------------|--------------|-----------------|----------------|----------------|----------|------|
191+
| <path> | <url-or-token> | <type> | <value> | <value> | <value> | <value> | <value> | <value-or-missing> | <recommended-action> | <unsupported-or-none> |
192+
```
193+
194+
## 访问复核清单
195+
196+
```text
197+
范围：<wiki_space / wiki_node / drive_folder / explicit_list> <name-or-id>
198+
复核对象数：<count>
199+
200+
| Owner | Path | URL | Type | 风险标签 | 当前权限摘要 | 最近访问证据 | 建议动作 |
201+
|-------|------|-----|------|----------|--------------|--------------|----------|
202+
| <owner-or-unknown> | <path> | <url-or-token> | <type> | <labels> | <link/external/share/security/comment> | <uv/pv/last_view_or_unknown> | <keep / tighten / owner review / unsupported> |
203+
204+
限制：<unsupported_checks / discovery_blockers / none>
205+
```
206+
207+
## 整改 dry-run
208+
209+
```text
210+
将生成整改计划，不执行写入：
211+
- 范围：<scope>
212+
- 选择来源：<risk_id list / risk_group / selected=true artifact / URL list>
213+
- 候选目标数：<count>
214+
- 计划执行命令：<command family>
215+
- 重新读取：已对所选目标重新读取当前权限；changed_since_report=<count>
216+
- 字段变更：
217+
- <risk_id> <path> (<url-or-token>): <field> <old> -> <new>
218+
- 跳过项：<unsupported / no manage_public / unsupported type / missing policy>
219+
- 验证方式：执行后重新读取 <metadata/public_permission>
220+
- 有限回滚范围：<public_permission_snapshots fields or not applicable>
221+
222+
请确认是否进入写入确认。
223+
```
224+
225+
## 批量权限申请确认
226+
227+
```text
228+
将逐个发起 <view / edit> 权限申请：
229+
- 候选目标数：<count>
230+
- 命令类型：drive +apply-permission
231+
- 风险：write；每个请求都会通知 owner
232+
- 执行方式：按候选列表顺序逐个调用，失败项会单独记录
233+
234+
候选示例：
235+
- <risk_id> <title> (<type>, <url-or-token>)：<reason>
236+
237+
请确认是否对上述候选目标发起权限申请。
238+
```
239+
240+
## 确认请求
241+
242+
```text
243+
将执行 <operation>：
244+
- 目标：<risk_id> <title> (<type>, <url-or-token>)
245+
- 命令类型：<command family>
246+
- 风险：<risk_level>
247+
- 字段变更：
248+
- <field>: <old> -> <new>
249+
- 验证方式：执行后重新读取 <metadata/public_permission>
250+
- 有限回滚材料：<public_permission_snapshots or not applicable>
251+
252+
请确认是否执行。
253+
```
254+
255+
## 最终摘要
256+
257+
```text
258+
已完成：<read checks / writes>
259+
验证：<fresh read result or async owner approval note>
260+
清单状态：<risk_id status updates / not applicable>
261+
回滚材料：<public_permission_snapshots / not applicable>
262+
剩余限制：<unsupported_checks / partial facts / approvals>
263+
```

0 commit comments

Comments
 (0)