@amaster.ai/pi-lark 0.1.2-beta.66 → 0.1.2-beta.68
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +2 -2
- package/skills/lark-base/references/lark-base-dashboard-block-config.md +31 -0
- package/skills/lark-base/references/lark-base-dashboard-block-get-data.md +6 -3
- package/skills/lark-base/references/lark-base-dashboard.md +17 -1
- package/skills/lark-base/references/lark-base-workflow-schema.md +2 -2
- package/skills/lark-calendar/SKILL.md +44 -16
- package/skills/lark-calendar/references/lark-calendar-list-attendees.md +33 -0
- package/skills/lark-calendar/references/lark-calendar-recurring.md +62 -66
- package/skills/lark-calendar/references/lark-calendar-schedule-clear-time.md +7 -1
- package/skills/lark-doc/references/lark-doc-create-workflow.md +2 -2
- package/skills/lark-doc/references/lark-doc-script.md +1 -1
- package/skills/lark-drive/references/lark-drive-comment-location.md +1 -1
- package/skills/lark-drive/references/lark-drive-workflow-topic-move-collector-resolve-verify.md +1 -1
- package/skills/lark-drive/references/lark-drive-workflow-topic-move-collector.md +1 -1
- package/skills/lark-okr/SKILL.md +38 -29
- package/skills/lark-okr/references/lark-okr-comment-create.md +103 -0
- package/skills/lark-okr/references/lark-okr-comment-delete.md +59 -0
- package/skills/lark-okr/references/lark-okr-comment-detail.md +80 -0
- package/skills/lark-okr/references/lark-okr-comment-get.md +66 -0
- package/skills/lark-okr/references/lark-okr-comment-list.md +79 -0
- package/skills/lark-okr/references/lark-okr-comment-patch.md +73 -0
- package/skills/lark-okr/references/lark-okr-comment-solve-reopen.md +83 -0
- package/skills/lark-okr/references/lark-okr-entities.md +66 -2
- package/skills/lark-sheets/SKILL.md +1 -0
- package/skills/lark-sheets/references/lark-sheets-batch-update.md +3 -3
- package/skills/lark-sheets/references/lark-sheets-legacy-command-migration.md +152 -0
- package/skills/lark-sheets/references/lark-sheets-read-data.md +2 -2
- package/skills/lark-sheets/references/lark-sheets-write-cells.md +40 -17
package/skills/lark-okr/SKILL.md
CHANGED
|
@@ -16,19 +16,20 @@ metadata:
|
|
|
16
16
|
|
|
17
17
|
## 快速决策
|
|
18
18
|
|
|
19
|
-
| 用户需求
|
|
20
|
-
|
|
21
|
-
| 查看自己/他人的 OKR
|
|
22
|
-
| 为自己写一组 OKR
|
|
23
|
-
| 只新增一条 O 或单条 KR
|
|
24
|
-
| 编辑内容/备注/截止时间
|
|
25
|
-
| 修改 OKR 分数
|
|
26
|
-
| 调整顺序或权重
|
|
27
|
-
| 更新数字进度/完成度
|
|
28
|
-
| 写文字进展
|
|
29
|
-
| 对齐目标
|
|
30
|
-
|
|
31
|
-
|
|
19
|
+
| 用户需求 | 操作路径 | 参考文档 |
|
|
20
|
+
|------------------------------|-------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
21
|
+
| 查看自己/他人的 OKR | 获取用户 ID -> `+cycle-list` -> `+cycle-detail` -> 按需查指标/进展记录 | [`cycle-list`](references/lark-okr-cycle-list.md), [`cycle-detail`](references/lark-okr-cycle-detail.md), [`indicators`](references/lark-okr-indicators.md), [`progress-list`](references/lark-okr-progress-list.md) |
|
|
22
|
+
| 为自己写一组 OKR | 优先用 `+batch-create` 创建 Objective/KR 骨架 | [`batch-create`](references/lark-okr-batch-create.md), [`contentblock`](references/lark-okr-contentblock.md) |
|
|
23
|
+
| 只新增一条 O 或单条 KR | 用 `+create` | [`create`](references/lark-okr-create.md) |
|
|
24
|
+
| 编辑内容/备注/截止时间 | 用 `+patch` | [`patch`](references/lark-okr-patch.md) |
|
|
25
|
+
| 修改 OKR 分数 | 只有用户明确说“分数”“评分”“打分”“score”时才用 `+patch --score`；分数不是进度/完成度 | [`patch`](references/lark-okr-patch.md) |
|
|
26
|
+
| 调整顺序或权重 | 用 `+reorder` / `+weight` | [`reorder`](references/lark-okr-reorder.md), [`weight`](references/lark-okr-weight.md) |
|
|
27
|
+
| 更新数字进度/完成度 | 百分比或不带单位数字用 `+indicator-update`；需要改单位/目标值时查指标后用 `indicators patch` | [`indicator-update`](references/lark-okr-indicator-update.md), [`indicators`](references/lark-okr-indicators.md) |
|
|
28
|
+
| 写文字进展 | 用 `+progress-create`；如果文本和数字都有，百分比或默认单位可使用 `--progress-percent` 统一改，非百分比单位更新量化指标 | [`progress-create`](references/lark-okr-progress-create.md), [`progress-list`](references/lark-okr-progress-list.md), [`progress-update`](references/lark-okr-progress-update.md) |
|
|
29
|
+
| 对齐目标 | 直接按对齐关系工作流处理 | [`alignments`](references/lark-okr-alignments.md) |
|
|
30
|
+
| 查询/创建/修改/解决 OKR 评论 | 获取周期下全部评论聚合用 `+comment-detail`，查询单个 O/KR/进展或仅查询周期全局评论用 `+comment-list`； | [`comment`](references/lark-okr-comment-list.md), [`comment-create`](references/lark-okr-comment-create.md), [`comment-solve-reopen`](references/lark-okr-comment-solve-reopen.md) |
|
|
31
|
+
|
|
32
|
+
分类只在用户明确要求分类，或创建 Objective 返回 `invalid parameters` 且怀疑租户强制开启分类时处理：用 `lark-cli okr categories list --params '{"owner_type":"user","page_size":100}' --as user` 查可用分类，选择语义合适且`enabled=true` 的分类 ID；分类可后续调整，不必停下等待用户确认。
|
|
32
33
|
|
|
33
34
|
获取当前用户用 `contact +get-user`；按姓名/邮箱查他人用 `contact +search-user`，拿到 `open_id` 后再查 OKR。
|
|
34
35
|
|
|
@@ -65,22 +66,30 @@ lark-cli okr +indicator-update \
|
|
|
65
66
|
|
|
66
67
|
Shortcut 是对常用操作的高级封装（`lark-cli okr +<verb> [flags]`）。有 Shortcut 的操作优先使用。
|
|
67
68
|
|
|
68
|
-
| Shortcut
|
|
69
|
-
|
|
70
|
-
| [`+cycle-list`](references/lark-okr-cycle-list.md)
|
|
71
|
-
| [`+cycle-detail`](references/lark-okr-cycle-detail.md)
|
|
72
|
-
| [`+create`](references/lark-okr-create.md)
|
|
73
|
-
| [`+progress-list`](references/lark-okr-progress-list.md)
|
|
74
|
-
| [`+progress-get`](references/lark-okr-progress-get.md)
|
|
75
|
-
| [`+progress-create`](references/lark-okr-progress-create.md)
|
|
76
|
-
| [`+progress-update`](references/lark-okr-progress-update.md)
|
|
77
|
-
| [`+progress-delete`](references/lark-okr-progress-delete.md)
|
|
78
|
-
| [`+upload-image`](references/lark-okr-image-upload.md)
|
|
79
|
-
| [`+batch-create`](references/lark-okr-batch-create.md)
|
|
80
|
-
| [`+reorder`](references/lark-okr-reorder.md)
|
|
81
|
-
| [`+weight`](references/lark-okr-weight.md)
|
|
82
|
-
| [`+indicator-update`](references/lark-okr-indicator-update.md)
|
|
83
|
-
| [`+patch`](references/lark-okr-patch.md)
|
|
69
|
+
| Shortcut | 说明 |
|
|
70
|
+
|------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
|
|
71
|
+
| [`+cycle-list`](references/lark-okr-cycle-list.md) | 分页获取特定用户的 OKR 周期列表，可以用 `--time-range` 对当前页后置筛选 |
|
|
72
|
+
| [`+cycle-detail`](references/lark-okr-cycle-detail.md) | 获取特定 OKR 中所有目标和关键结果的内容 |
|
|
73
|
+
| [`+create`](references/lark-okr-create.md) | 创建单个 Objective（可带备注），或向已有 Objective 新增 KR |
|
|
74
|
+
| [`+progress-list`](references/lark-okr-progress-list.md) | 分页获取目标或关键结果的进展记录列表 |
|
|
75
|
+
| [`+progress-get`](references/lark-okr-progress-get.md) | 根据 ID 获取单条 OKR 进展记录 |
|
|
76
|
+
| [`+progress-create`](references/lark-okr-progress-create.md) | 为目标或关键结果创建进展记录 |
|
|
77
|
+
| [`+progress-update`](references/lark-okr-progress-update.md) | 更新指定 ID 的进展记录内容 |
|
|
78
|
+
| [`+progress-delete`](references/lark-okr-progress-delete.md) | 删除指定 ID 的进展记录（不可恢复） |
|
|
79
|
+
| [`+upload-image`](references/lark-okr-image-upload.md) | 上传图片用于 OKR 进展记录的富文本内容 |
|
|
80
|
+
| [`+batch-create`](references/lark-okr-batch-create.md) | 批量创建 Objective（可带备注）和 KR |
|
|
81
|
+
| [`+reorder`](references/lark-okr-reorder.md) | 调整 Objective 或 KR 的顺位 |
|
|
82
|
+
| [`+weight`](references/lark-okr-weight.md) | 调整 Objective 或 KR 的权重 |
|
|
83
|
+
| [`+indicator-update`](references/lark-okr-indicator-update.md) | 更新 Objective 或 KR 的当前进度指标。更复杂的量化指标操作见 [量化指标管理](references/lark-okr-indicators.md) |
|
|
84
|
+
| [`+patch`](references/lark-okr-patch.md) | 部分更新 Objective 或 KR（content、notes、score、deadline） |
|
|
85
|
+
| [`+comment-detail`](references/lark-okr-comment-detail.md) | 获取周期下 Cycle/Objective/KeyResult/Progress 的全部评论 |
|
|
86
|
+
| [`+comment-list`](references/lark-okr-comment-list.md) | 分页获取单个 OKR 实体下的评论 |
|
|
87
|
+
| [`+comment-get`](references/lark-okr-comment-get.md) | 获取单条评论详情 |
|
|
88
|
+
| [`+comment-create`](references/lark-okr-comment-create.md) | 创建新评论或回复已有评论(仅支持 --as user) |
|
|
89
|
+
| [`+comment-patch`](references/lark-okr-comment-patch.md) | 修改评论内容(仅支持 --as user) |
|
|
90
|
+
| [`+comment-delete`](references/lark-okr-comment-delete.md) | 永久删除单条评论(仅支持 --as user) |
|
|
91
|
+
| [`+comment-solve`](references/lark-okr-comment-solve-reopen.md) | 解决评论或划词评论串(仅支持 --as user) |
|
|
92
|
+
| [`+comment-reopen`](references/lark-okr-comment-solve-reopen.md) | 重新打开评论或划词评论串(仅支持 --as user) |
|
|
84
93
|
|
|
85
94
|
### 创建场景选择
|
|
86
95
|
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# okr +comment-create
|
|
2
|
+
> **前置条件：** 先阅读 [lark-shared/SKILL.md](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则；
|
|
3
|
+
|
|
4
|
+
创建一条 OKR 评论，或回复已有的评论。只支持 user 身份。
|
|
5
|
+
|
|
6
|
+
## 推荐命令
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
# 在周期下创建实体级评论。
|
|
10
|
+
lark-cli okr +comment-create --target-type cycle --target-id 3456789012345678901 --content '{"text":"进展不错"}'
|
|
11
|
+
|
|
12
|
+
# 在 Objective 正文中创建指定文本的划词评论。
|
|
13
|
+
lark-cli okr +comment-create --target-type objective --target-id 2345678901234567890 --content '{"text":"请补充数据"}' --selected-text '提升核心接口稳定性'
|
|
14
|
+
|
|
15
|
+
# 在 Objective 正文中创建划词评论。
|
|
16
|
+
lark-cli okr +comment-create --target-type objective --target-id 2345678901234567890 --content '{"text":"请补充数据"}' --select-all
|
|
17
|
+
|
|
18
|
+
# 在 KeyResult 的已有划词评论串中追加回复。
|
|
19
|
+
lark-cli okr +comment-create --target-type key_result --target-id 4567890123456789012 --content '{"text":"已回复"}' --ref-comment-id 7000000000000000004
|
|
20
|
+
|
|
21
|
+
# 使用 richtext 文件作为评论正文。
|
|
22
|
+
lark-cli okr +comment-create --target-type progress --target-id 3456789012345678901 --style richtext --content '@comment.json'
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
# 写入前预览创建评论的 URL、参数和请求体。
|
|
27
|
+
lark-cli okr +comment-create --target-type progress --target-id 3456789012345678901 --content '{"text":"进展不错"}' --dry-run
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## 常用表述
|
|
31
|
+
|
|
32
|
+
以下是一些用户需求中常见的表述:
|
|
33
|
+
|
|
34
|
+
- 全局评论/周期评论/OKR评论: 指 OKR 周期的实体级评论，当用户要求创建全局评论，或对某个周期的 OKR 进行评论（不特指某个 Objective 或 KeyResult 时），可以创建周期实体级评论。
|
|
35
|
+
- 划词评论: 指 Objective/KeyResult 下的划词评论。需要注意，Objective/KeyResult 下不能创建实体级评论（必须携带 selected-text 或 select-all）。若用户没有特别指定需评论的段落，使用 --select-all
|
|
36
|
+
|
|
37
|
+
## 参数
|
|
38
|
+
|
|
39
|
+
| 参数 | 必填 | 默认值 | 说明 |
|
|
40
|
+
|------------------|------|---------|---------------------------------------------------------------------------------------------------------------|
|
|
41
|
+
| --target-type | 是 | — | cycle、progress、objective 或 key_result。 |
|
|
42
|
+
| --target-id | 是 | — | 评论对象 ID，int64 正整数。 |
|
|
43
|
+
| --content | 是 | — | 评论正文；输入风格：`simple`（半纯文本 JSON，推荐） \| `richtext`（完整 ContentBlock JSON），支持 @文件路径。 |
|
|
44
|
+
| --selected-text | 否 | — | Objective/KeyResult 新建划词时的完整纯文本。 |
|
|
45
|
+
| --select-all | 否 | false | Objective/KeyResult 划词时选择全文。 |
|
|
46
|
+
| --ref-comment-id | 否 | — | 回复 Progress/Cycle 评论，或将 Objective/KeyResult 评论挂入已有划词串。 |
|
|
47
|
+
| --style | 否 | simple | 输入/输出风格：simple 或 richtext。 |
|
|
48
|
+
| --user-id-type | 否 | open_id | open_id、union_id、user_id 或 user_key。 |
|
|
49
|
+
| --dry-run | 否 | — | 预览 API 调用而不实际执行。 |
|
|
50
|
+
| --format | 否 | json | 输出格式。 |
|
|
51
|
+
|
|
52
|
+
## 评论场景参数组合
|
|
53
|
+
|
|
54
|
+
| 场景 | target-type | 必须传 | 不能传 |
|
|
55
|
+
|--------------------------------|-------------------------|---------------------------------------------------------------|-------------------------------------------------------|
|
|
56
|
+
| 创建周期/进展实体级评论 | cycle 或 progress | `--content` | `--selected-text`、`--select-all`、`--ref-comment-id` |
|
|
57
|
+
| 回复周期/进展已有评论 | cycle 或 progress | `--content`、`--ref-comment-id` | `--selected-text`、`--select-all` |
|
|
58
|
+
| 创建 Objective/KR 划词评论 | objective 或 key_result | `--content`，并在 `--selected-text` / `--select-all` 中二选一 | `--ref-comment-id` |
|
|
59
|
+
| 追加到 Objective/KR 划词评论串 | objective 或 key_result | `--content`、`--ref-comment-id` | `--selected-text`、`--select-all` |
|
|
60
|
+
|
|
61
|
+
## 工作流程
|
|
62
|
+
|
|
63
|
+
1. 确定评论 target：使用 [+cycle-detail](lark-okr-cycle-detail.md) 获取 Objective/KeyResult ID，使用 [+progress-list](lark-okr-progress-list.md) 获取 Progress ID；已有评论串时使用 [+comment-list](lark-okr-comment-list.md) 或 [+comment-get](lark-okr-comment-get.md) 获取 comment-id。
|
|
64
|
+
2. 根据 target-type 选择评论形式：
|
|
65
|
+
- cycle/progress：不传 selected-text 或 select-all；需要回复时传 ref-comment-id。
|
|
66
|
+
- objective/key_result：在 selected-text、select-all、ref-comment-id 中选择且只能选择一个；selected-text 和 select-all 互斥，二者也都和 ref-comment-id 互斥。
|
|
67
|
+
3. 准备 content：content 是业务必填，通常建议使用 simple 格式，需要精确控制 @用户的位置时，可以使用 richtext 格式，参考 [ContentBlock 格式](lark-okr-contentblock.md)
|
|
68
|
+
4. 执行命令；真实写入前可以先使用 --dry-run 检查 URL、query 和 body。
|
|
69
|
+
5. 在创建(而非回复) Objective/KeyResult 划词评论时，若用户未指定评论的具体位置，通常可以使用 select-all 而非自行指定 selected-text，除非用户需求中明确了具体的段落。
|
|
70
|
+
- 若需使用 selected-text 精确选择划词选区时，只可传入正文中真实存在的连续纯文本片段；不要包含或跨越 mention 占位符，否则无法命中具体内容。
|
|
71
|
+
- selected-text 会选择对应文本的首个命中。若 selected-text 未匹配到内容，会 fallback 至选择全文。
|
|
72
|
+
|
|
73
|
+
## 输出
|
|
74
|
+
|
|
75
|
+
创建成功返回 JSON：
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"comment_id": "7000000000000000004",
|
|
80
|
+
"selection_id": "8000000000000000002"
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
- comment_id 是新评论 ID。
|
|
85
|
+
- selection_id 只在创建划词评论时返回，用于识别评论串。
|
|
86
|
+
- 创建接口不直接返回完整 Comment；需要详情时使用 [+comment-get](lark-okr-comment-get.md)。
|
|
87
|
+
|
|
88
|
+
## 注意事项
|
|
89
|
+
|
|
90
|
+
- Objective/KeyResult 的 ref-comment-id 只用于定位已有划词串，不会在新评论的 ref_comment_id 字段建立引用关系。
|
|
91
|
+
- `--ref-comment-id` 必须传评论实体自身的 `id`，不能传 `selection.id`。`selection.id` 只用于识别同一个划词评论串；如果要回复某个划词串，应先从 +comment-list 或 +comment-detail 中找到该串内任意一条 Comment 的 `id`，再将这个 `id` 传给 `--ref-comment-id`。
|
|
92
|
+
- Progress/Cycle 是实体级评论；Progress 的 ref-comment-id 会建立普通评论之间的引用关系。
|
|
93
|
+
- 评论的 content 不支持 docs/images 字段，建议使用 simple 格式填写
|
|
94
|
+
|
|
95
|
+
## 参考
|
|
96
|
+
|
|
97
|
+
- [lark-okr](../SKILL.md) — OKR 命令、路由和通用约定
|
|
98
|
+
- [OKR 实体定义](lark-okr-entities.md) — Comment、评论串和 target 类型
|
|
99
|
+
- [ContentBlock 格式](lark-okr-contentblock.md) — simple/richtext 输入格式
|
|
100
|
+
- [okr +comment-list](lark-okr-comment-list.md) — 查询已有评论和 selection.id
|
|
101
|
+
- [okr +comment-get](lark-okr-comment-get.md) — 获取评论详情
|
|
102
|
+
- [okr +comment-solve / +comment-reopen](lark-okr-comment-solve-reopen.md) — 管理评论状态
|
|
103
|
+
- [lark-shared](../../lark-shared/SKILL.md) — 认证、身份、权限和安全规则
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# okr +comment-delete
|
|
2
|
+
> **前置条件：** 先阅读 [lark-shared/SKILL.md](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则；
|
|
3
|
+
|
|
4
|
+
永久删除一条评论。删除划词评论时只删除指定评论，不会删除同一 selection.id 下的其他评论。
|
|
5
|
+
|
|
6
|
+
## 功能简介
|
|
7
|
+
|
|
8
|
+
删除一条特定评论。本 shortcut 为高风险接口，删除的评论不可找回，如果只是暂时结束讨论，可使用 +comment-solve。只支持 user 身份。
|
|
9
|
+
|
|
10
|
+
## 推荐命令
|
|
11
|
+
```bash
|
|
12
|
+
# 预览删除请求，不实际执行永久删除。
|
|
13
|
+
lark-cli okr +comment-delete --comment-id 7000000000000000004 --dry-run
|
|
14
|
+
# 确认删除目标后，执行不可恢复的删除操作。
|
|
15
|
+
lark-cli okr +comment-delete --comment-id 7000000000000000004 --yes
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
## 参数
|
|
20
|
+
|
|
21
|
+
| 参数 | 必填 | 默认值 | 说明 |
|
|
22
|
+
|--------------|--------------|--------|-------------------------------------------------------------|
|
|
23
|
+
| --comment-id | 是 | — | 要删除的评论 ID，int64 正整数。建议先由 +comment-get 核对。 |
|
|
24
|
+
| --yes | 真实执行时是 | — | 确认 high-risk-write 操作。--dry-run 时不需要。 |
|
|
25
|
+
| --dry-run | 否 | — | 预览 API 调用而不实际执行。 |
|
|
26
|
+
| --format | 否 | json | 输出格式。 |
|
|
27
|
+
|
|
28
|
+
## 工作流程
|
|
29
|
+
|
|
30
|
+
1. 使用 [+comment-list](lark-okr-comment-list.md)、[+comment-detail](lark-okr-comment-detail.md) 或 [+comment-get](lark-okr-comment-get.md) 定位并确认 comment-id。
|
|
31
|
+
2. 判断是否真的需要删除：解决评论使用 [+comment-solve](lark-okr-comment-solve-reopen.md)，删除只用于永久移除内容。
|
|
32
|
+
3. 先执行带 --dry-run 的命令检查 URL 和 comment-id。
|
|
33
|
+
4. 向用户明确说明删除不可恢复；得到确认后，在原始命令末尾追加 --yes 执行。
|
|
34
|
+
5. 根据 deleted=true 和返回的 comment_id 确认结果。
|
|
35
|
+
|
|
36
|
+
## 输出
|
|
37
|
+
|
|
38
|
+
删除成功返回 JSON：
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"deleted": true,
|
|
42
|
+
"comment_id": "7000000000000000004"
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
## 注意事项
|
|
48
|
+
|
|
49
|
+
- 删除是单条评论级操作，即使评论属于划词评论串，也不会连带删除其他评论。
|
|
50
|
+
- 删除后不能使用 +comment-reopen 恢复；暂时关闭讨论应使用 +comment-solve。
|
|
51
|
+
- 该命令不需要 style，因为接口没有返回 Comment 正文。
|
|
52
|
+
|
|
53
|
+
## 参考
|
|
54
|
+
|
|
55
|
+
- [lark-okr](../SKILL.md) — OKR 命令、路由和通用约定
|
|
56
|
+
- [OKR 实体定义](lark-okr-entities.md) — Comment、评论串和状态规则
|
|
57
|
+
- [okr +comment-get](lark-okr-comment-get.md) — 删除前核对评论
|
|
58
|
+
- [okr +comment-solve / +comment-reopen](lark-okr-comment-solve-reopen.md) — 暂时解决和恢复评论
|
|
59
|
+
- [lark-shared](../../lark-shared/SKILL.md) — 高风险操作确认协议
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# okr +comment-detail
|
|
2
|
+
> **前置条件：** 先阅读 [lark-shared/SKILL.md](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则；
|
|
3
|
+
|
|
4
|
+
获取指定 OKR 周期下 Cycle、Objective、KeyResult 和 Progress 的全部评论，并按评论对象和评论串整理后按时间升序排列。该 shortcut 是跨多个 OKR 接口的聚合查询。
|
|
5
|
+
|
|
6
|
+
## 推荐命令
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
# 获取指定周期下所有 Cycle、Objective、KeyResult 和 Progress 的评论。
|
|
10
|
+
lark-cli okr +comment-detail --cycle-id 1234567890123456789
|
|
11
|
+
|
|
12
|
+
# 获取原始 ContentBlock 格式的评论正文。
|
|
13
|
+
lark-cli okr +comment-detail --cycle-id 1234567890123456789 --style richtext
|
|
14
|
+
|
|
15
|
+
# 预览聚合查询的 API 调用，不实际执行。
|
|
16
|
+
lark-cli okr +comment-detail --cycle-id 1234567890123456789 --dry-run
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## 参数
|
|
20
|
+
|
|
21
|
+
| 参数 | 必填 | 默认值 | 说明 |
|
|
22
|
+
|------------|------|--------|--------------------------------------------------------------------------------------------|
|
|
23
|
+
| --cycle-id | 是 | — | OKR 周期 ID，int64 正整数，可从 +cycle-list 获取。 |
|
|
24
|
+
| --style | 否 | simple | simple 返回半纯文本格式，不涉及字体/颜色等信息时推荐使用；richtext 返回原始 ContentBlock。 |
|
|
25
|
+
| --dry-run | 否 | — | 预览聚合查询而不实际执行。 |
|
|
26
|
+
| --format | 否 | json | 输出格式。 |
|
|
27
|
+
|
|
28
|
+
## 工作流程
|
|
29
|
+
|
|
30
|
+
1. 使用 +cycle-list 获取周期 ID；如果用户已经提供周期 ID，直接使用。
|
|
31
|
+
2. 执行 +comment-detail --cycle-id "..."。shortcut 会依次获取周期下的 Objective、每个 Objective 下的 KeyResult、每个 Objective/KeyResult 下的 Progress，以及四类对象的评论。
|
|
32
|
+
3. 评论接口自动处理分页；对象读取和评论读取使用有界并发。任一底层请求失败时整体返回错误，不返回静默不完整结果。
|
|
33
|
+
4. 评论串按首条评论的 create_time 升序排列，串内评论也按 create_time 升序排列。
|
|
34
|
+
|
|
35
|
+
## 输出
|
|
36
|
+
|
|
37
|
+
返回 JSON 的核心结构如下：
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"cycle_id": "1234567890123456789",
|
|
42
|
+
"comments": {
|
|
43
|
+
"2345678901234567890": [
|
|
44
|
+
[
|
|
45
|
+
{
|
|
46
|
+
"id": "7000000000000000001",
|
|
47
|
+
"target": {"target_type": "objective", "target_id": "2345678901234567890"},
|
|
48
|
+
"commentator_id": "ou_xxx",
|
|
49
|
+
"status": "open",
|
|
50
|
+
"create_time": "2025-01-15 10:30:00",
|
|
51
|
+
"update_time": "2025-01-15 10:30:00",
|
|
52
|
+
"selection": {"id": "8000000000000000001", "selected_text": "提升核心接口稳定性"},
|
|
53
|
+
"content": {"text": "请补充指标", "mention": [], "docs": [], "images": []}
|
|
54
|
+
}
|
|
55
|
+
]
|
|
56
|
+
]
|
|
57
|
+
},
|
|
58
|
+
"style": "simple"
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
- comments 第一层 key 是 target_id；value 是评论串数组；每个评论串是评论数组。
|
|
63
|
+
- simple 风格下 content 是 SemiPlainContent；richtext 风格下 content 是 ContentBlock。
|
|
64
|
+
- 评论时间戳会转换为可读日期时间；selection、状态和引用字段会保留。
|
|
65
|
+
- `comments` 会为周期遍历到的每个 target 保留一个 target_id key；即使该对象没有评论，对应 value 也会是空的评论串数组。
|
|
66
|
+
|
|
67
|
+
## 注意事项
|
|
68
|
+
|
|
69
|
+
- 这是聚合查询，接口调用次数取决于周期下的 Objective、KeyResult 和 Progress 数量。
|
|
70
|
+
- +comment-detail 不接受 department-id-type，该接口参数由 shortcut 忽略。
|
|
71
|
+
- 该命令只读取评论，不会修改、解决或删除评论。
|
|
72
|
+
|
|
73
|
+
## 参考
|
|
74
|
+
|
|
75
|
+
- [lark-okr](../SKILL.md) — OKR 命令、路由和通用约定
|
|
76
|
+
- [OKR 实体定义](lark-okr-entities.md) — Cycle、Objective、KeyResult、Progress 和 Comment 的关系
|
|
77
|
+
- [ContentBlock 格式](lark-okr-contentblock.md) — ContentBlock 与 SemiPlainContent 格式
|
|
78
|
+
- [okr +cycle-detail](lark-okr-cycle-detail.md) — 获取周期下的 Objective 和 KeyResult
|
|
79
|
+
- [okr +progress-list](lark-okr-progress-list.md) — 获取 Objective 或 KeyResult 下的 Progress
|
|
80
|
+
- [lark-shared](../../lark-shared/SKILL.md) — 认证、身份、权限和安全规则
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# okr +comment-get
|
|
2
|
+
> **前置条件：** 先阅读 [lark-shared/SKILL.md](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则；
|
|
3
|
+
|
|
4
|
+
根据评论 ID 获取单条 OKR 评论，查看评论正文、状态、评论对象、引用关系和划词信息。本 shortcut 适合用于在编辑评论后确认其最终状态。
|
|
5
|
+
|
|
6
|
+
## 推荐命令
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
# 获取一条评论的简化正文和元数据。
|
|
10
|
+
lark-cli okr +comment-get --comment-id 7000000000000000001
|
|
11
|
+
|
|
12
|
+
# 获取原始 ContentBlock 格式的评论正文。
|
|
13
|
+
lark-cli okr +comment-get --comment-id 7000000000000000001 --style richtext
|
|
14
|
+
|
|
15
|
+
# 预览获取评论的 API 调用，不实际执行。
|
|
16
|
+
lark-cli okr +comment-get --comment-id 7000000000000000001 --dry-run
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## 参数
|
|
20
|
+
|
|
21
|
+
| 参数 | 必填 | 默认值 | 说明 |
|
|
22
|
+
|----------------|------|---------|----------------------------------------------------------------------------------------|
|
|
23
|
+
| --comment-id | 是 | — | 评论 ID，int64 正整数。 |
|
|
24
|
+
| --user-id-type | 否 | open_id | open_id、union_id、user_id 或 user_key。 |
|
|
25
|
+
| --style | 否 | simple | simple 返回半纯文本格式，不涉及字体/颜色等信息时推荐使用；richtext 返回 ContentBlock。 |
|
|
26
|
+
| --dry-run | 否 | — | 预览 API 调用而不实际执行。 |
|
|
27
|
+
| --format | 否 | json | 输出格式。 |
|
|
28
|
+
|
|
29
|
+
## 工作流程
|
|
30
|
+
|
|
31
|
+
1. 如果只有目标 ID，先用 [+comment-list](lark-okr-comment-list.md) 或 [+comment-detail](lark-okr-comment-detail.md) 定位 comment-id。
|
|
32
|
+
2. 执行 +comment-get --comment-id "..."。
|
|
33
|
+
3. 根据后续操作检查 selection、status 和 ref_comment_id：selection.id 表示划词评论，status 为 solved 表示已解决，ref_comment_id 表示引用关系。
|
|
34
|
+
|
|
35
|
+
## 输出
|
|
36
|
+
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"comment": {
|
|
40
|
+
"id": "7000000000000000001",
|
|
41
|
+
"target": {"target_type": "progress", "target_id": "3456789012345678901"},
|
|
42
|
+
"commentator_id": "ou_xxx",
|
|
43
|
+
"status": "open",
|
|
44
|
+
"create_time": "2025-01-15 10:30:00",
|
|
45
|
+
"update_time": "2025-01-15 10:30:00",
|
|
46
|
+
"content": {"text": "进展不错", "mention": [], "docs": [], "images": []},
|
|
47
|
+
"ref_comment_id": "7000000000000000000"
|
|
48
|
+
},
|
|
49
|
+
"style": "simple"
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
selection、solver_id、solved_time 和 ref_comment_id 按接口是否返回保留。
|
|
54
|
+
|
|
55
|
+
## 注意事项
|
|
56
|
+
|
|
57
|
+
- Objective/KeyResult 的划词评论通过 selection.id 归属于评论串；实体级评论没有 selection。
|
|
58
|
+
- 解决或重新打开请使用 [+comment-solve / +comment-reopen](lark-okr-comment-solve-reopen.md)。
|
|
59
|
+
|
|
60
|
+
## 参考
|
|
61
|
+
|
|
62
|
+
- [lark-okr](../SKILL.md) — OKR 命令、路由和通用约定
|
|
63
|
+
- [OKR 实体定义](lark-okr-entities.md) — Comment 字段与评论串规则
|
|
64
|
+
- [ContentBlock 格式](lark-okr-contentblock.md) — 评论正文格式
|
|
65
|
+
- [okr +comment-list](lark-okr-comment-list.md) — 查询目标下的评论
|
|
66
|
+
- [lark-shared](../../lark-shared/SKILL.md) — 认证、身份、权限和安全规则
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# okr +comment-list
|
|
2
|
+
> **前置条件：** 先阅读 [lark-shared/SKILL.md](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则；
|
|
3
|
+
|
|
4
|
+
分页获取单个 Cycle、Objective、KeyResult 或 Progress 下的评论。查询整个周期下所有评论时可使用 [+comment-detail](lark-okr-comment-detail.md)。
|
|
5
|
+
|
|
6
|
+
## 推荐命令
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
# 获取 Objective 下的第一页评论。
|
|
10
|
+
lark-cli okr +comment-list --target-type objective --target-id 2345678901234567890
|
|
11
|
+
|
|
12
|
+
# 使用上一页 token 获取 Progress 下的下一页评论。
|
|
13
|
+
lark-cli okr +comment-list --target-type progress --target-id 3456789012345678901 --page-size 100 --page-token "7000000000000000002"
|
|
14
|
+
|
|
15
|
+
# 以 richtext 输出 KeyResult 评论，但是仅预览请求，不实际获取。
|
|
16
|
+
lark-cli okr +comment-list --target-type key_result --target-id 4567890123456789012 --style richtext --dry-run
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## 参数
|
|
20
|
+
|
|
21
|
+
| 参数 | 必填 | 默认值 | 说明 |
|
|
22
|
+
|----------------|------|---------|----------------------------------------------------------------------------------------|
|
|
23
|
+
| --target-type | 是 | — | cycle、objective、key_result 或 progress。 |
|
|
24
|
+
| --target-id | 是 | — | 评论对象 ID，int64 正整数。 |
|
|
25
|
+
| --page-size | 否 | 100 | 每页数量，范围 1-100。 |
|
|
26
|
+
| --page-token | 否 | "" | 上一次响应中的 token；首页不传。 |
|
|
27
|
+
| --user-id-type | 否 | open_id | open_id、union_id、user_id 或 user_key。 |
|
|
28
|
+
| --style | 否 | simple | simple 返回半纯文本格式，不涉及字体/颜色等信息时推荐使用；richtext 返回 ContentBlock。 |
|
|
29
|
+
| --dry-run | 否 | — | 预览 API 调用而不实际执行。 |
|
|
30
|
+
| --format | 否 | json | 输出格式。 |
|
|
31
|
+
|
|
32
|
+
## 工作流程
|
|
33
|
+
|
|
34
|
+
1. 根据用户需求选择 target-type：周期用 cycle，目标用 objective，关键结果用 key_result，进展用 progress。
|
|
35
|
+
2. 如果缺少 ID，使用 [+cycle-list](lark-okr-cycle-list.md)、[+cycle-detail](lark-okr-cycle-detail.md) 或 [+progress-list](lark-okr-progress-list.md) 获取。
|
|
36
|
+
3. 执行 +comment-list --target-type "..." --target-id "..."。
|
|
37
|
+
4. has_more 为 true 且 page_token 非空时，将 page_token 原样作为下一次调用的 --page-token；不要自行解析或修改 token。
|
|
38
|
+
|
|
39
|
+
## 输出
|
|
40
|
+
|
|
41
|
+
```json
|
|
42
|
+
{
|
|
43
|
+
"comments": [
|
|
44
|
+
[
|
|
45
|
+
{
|
|
46
|
+
"id": "7000000000000000001",
|
|
47
|
+
"target": {"target_type": "objective", "target_id": "2345678901234567890"},
|
|
48
|
+
"commentator_id": "ou_xxx",
|
|
49
|
+
"status": "open",
|
|
50
|
+
"create_time": "2025-01-15 10:30:00",
|
|
51
|
+
"update_time": "2025-01-15 10:30:00",
|
|
52
|
+
"selection": {"id": "8000000000000000001", "selected_text": "提升核心接口稳定性"},
|
|
53
|
+
"content": {"text": "请补充指标", "mention": [], "docs": [], "images": []}
|
|
54
|
+
}
|
|
55
|
+
]
|
|
56
|
+
],
|
|
57
|
+
"has_more": true,
|
|
58
|
+
"page_token": "7000000000000000002",
|
|
59
|
+
"style": "simple"
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
comments 是当前页按评论串分组的二维数组，不会自动拉取所有分页；simple 风格返回简单的半纯文本格式，richtext 风格返回原生 ContentBlock。
|
|
64
|
+
|
|
65
|
+
## 注意事项
|
|
66
|
+
|
|
67
|
+
- 实体级评论没有 selection；Objective/KeyResult 的划词评论带有 selection.id。
|
|
68
|
+
- 只对当前页内的评论进行评论串分组；如果同一评论串跨越分页边界，需结合相邻页自行合并，或使用 +comment-detail 获取整个周期的聚合结果。
|
|
69
|
+
- 评论串按首条评论的 create_time 升序排列，串内评论也按 create_time 升序排列；时间相同则按评论 ID 升序。
|
|
70
|
+
- 该命令是只读操作，不会改变评论状态。
|
|
71
|
+
|
|
72
|
+
## 参考
|
|
73
|
+
|
|
74
|
+
- [lark-okr](../SKILL.md) — OKR 命令、路由和通用约定
|
|
75
|
+
- [OKR 实体定义](lark-okr-entities.md) — Comment、评论串和 target 类型
|
|
76
|
+
- [okr +comment-detail](lark-okr-comment-detail.md) — 聚合获取周期评论
|
|
77
|
+
- [okr +cycle-detail](lark-okr-cycle-detail.md) — 获取 Objective 和 KeyResult ID
|
|
78
|
+
- [okr +progress-list](lark-okr-progress-list.md) — 获取 Progress ID
|
|
79
|
+
- [lark-shared](../../lark-shared/SKILL.md) — 认证、身份、权限和安全规则
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# okr +comment-patch
|
|
2
|
+
> **前置条件：** 先阅读 [lark-shared/SKILL.md](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则；
|
|
3
|
+
|
|
4
|
+
修改指定评论的正文。评论目标、划词定位、引用关系则一经创建不可修改。只支持 user 身份。
|
|
5
|
+
|
|
6
|
+
`--content` 是业务必填项：OpenAPI schema 中该字段可能表现为可选，但实际修改评论必须提供非空正文。
|
|
7
|
+
|
|
8
|
+
## 推荐命令
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
# 使用 simple 风格修改评论正文。
|
|
12
|
+
lark-cli okr +comment-patch --comment-id 7000000000000000004 --content '{"text":"更新后的评论"}'
|
|
13
|
+
|
|
14
|
+
# 使用 richtext 文件修改评论正文。
|
|
15
|
+
lark-cli okr +comment-patch --comment-id 7000000000000000004 --style richtext --content '@comment.json'
|
|
16
|
+
|
|
17
|
+
# 写入前预览修改评论的 API 调用，不实际执行。
|
|
18
|
+
lark-cli okr +comment-patch --comment-id 7000000000000000004 --content '{"text":"预览更新"}' --dry-run
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## 参数
|
|
22
|
+
|
|
23
|
+
| 参数 | 必填 | 默认值 | 说明 |
|
|
24
|
+
|----------------|------|---------|-------------------------------------------------------------------------------------------------------------------------------|
|
|
25
|
+
| --comment-id | 是 | — | 评论 ID，int64 正整数；可从 [+comment-list](lark-okr-comment-list.md) 或 [+comment-detail](lark-okr-comment-detail.md) 获取。 |
|
|
26
|
+
| --content | 是 | — | 新正文；输入风格：`simple`（半纯文本 JSON，推荐） \| `richtext`（完整 ContentBlock JSON），支持 @文件路径。 |
|
|
27
|
+
| --style | 否 | simple | 输入/输出风格：simple 或 richtext。 |
|
|
28
|
+
| --user-id-type | 否 | open_id | open_id、union_id、user_id 或 user_key。 |
|
|
29
|
+
| --dry-run | 否 | — | 预览 API 调用而不实际执行。 |
|
|
30
|
+
| --format | 否 | json | 输出格式。 |
|
|
31
|
+
|
|
32
|
+
## 工作流程
|
|
33
|
+
|
|
34
|
+
1. 使用 [+comment-list](lark-okr-comment-list.md)、[+comment-detail](lark-okr-comment-detail.md) 或 [+comment-get](lark-okr-comment-get.md) 确认 comment-id 和目标评论。
|
|
35
|
+
2. 准备 content：通常建议使用 simple 格式，需要精确控制 @用户的位置时，可以使用 richtext 格式，参考 [ContentBlock 格式](lark-okr-contentblock.md)
|
|
36
|
+
3. 执行 +comment-patch；真实写入前用 --dry-run 检查请求。
|
|
37
|
+
4. 如果要解决或重新打开评论，不要使用 patch，改用 [+comment-solve](lark-okr-comment-solve-reopen.md) 或 [+comment-reopen](lark-okr-comment-solve-reopen.md)。
|
|
38
|
+
|
|
39
|
+
## 输出
|
|
40
|
+
|
|
41
|
+
返回 JSON：
|
|
42
|
+
|
|
43
|
+
```json
|
|
44
|
+
{
|
|
45
|
+
"comment": {
|
|
46
|
+
"id": "7000000000000000004",
|
|
47
|
+
"target": {"target_type": "progress", "target_id": "3456789012345678901"},
|
|
48
|
+
"commentator_id": "ou_xxx",
|
|
49
|
+
"status": "open",
|
|
50
|
+
"create_time": "2025-01-15 10:30:00",
|
|
51
|
+
"update_time": "2025-01-15 11:00:00",
|
|
52
|
+
"content": {"text": "更新后的评论", "mention": [], "docs": [], "images": []}
|
|
53
|
+
},
|
|
54
|
+
"style": "simple"
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
simple 风格的 content 为 SemiPlainContent；richtext 风格的 content 为 ContentBlock。
|
|
59
|
+
|
|
60
|
+
## 注意事项
|
|
61
|
+
|
|
62
|
+
- patch 不会改变评论的 target、selection、ref_comment_id 或 status。
|
|
63
|
+
- simple 输入不支持 docs/images；需要富文本元素时使用 richtext。
|
|
64
|
+
- 空正文不允许提交；如需删除评论，请使用 [+comment-delete](lark-okr-comment-delete.md)，删除不可恢复。
|
|
65
|
+
|
|
66
|
+
## 参考
|
|
67
|
+
|
|
68
|
+
- [lark-okr](../SKILL.md) — OKR 命令、路由和通用约定
|
|
69
|
+
- [OKR 实体定义](lark-okr-entities.md) — Comment 字段与评论串规则
|
|
70
|
+
- [ContentBlock 格式](lark-okr-contentblock.md) — 评论正文格式
|
|
71
|
+
- [okr +comment-get](lark-okr-comment-get.md) — 获取更新前后的评论
|
|
72
|
+
- [okr +comment-delete](lark-okr-comment-delete.md) — 永久删除评论
|
|
73
|
+
- [lark-shared](../../lark-shared/SKILL.md) — 认证、身份、权限和安全规则
|