-
Notifications
You must be signed in to change notification settings - Fork 1.4k
docs: add approval comments skill guidance #2614
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,99 @@ | ||
| # approval comments create | ||
|
|
||
| 创建、回复或编辑审批实例评论(用户级写操作)。同一个命令通过请求体区分三种行为:不传 `parent_comment_id` 和 `comment_id` 是创建顶层评论;传 `parent_comment_id` 是回复;传 `comment_id` 是编辑本人已有评论或回复。 | ||
|
|
||
| 需要的 scopes: ["approval:instance:write"] | ||
|
|
||
| ## 命令 | ||
|
|
||
| ```bash | ||
| # 创建顶层评论 | ||
| lark-cli approval comments create \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>"}' \ | ||
| --data '{"content":"{\"text\":\"请补充报销说明\"}"}' \ | ||
| --as user | ||
|
|
||
| # 回复一条顶层评论 | ||
| lark-cli approval comments create \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>"}' \ | ||
| --data '{"parent_comment_id":"<PARENT_COMMENT_ID>","content":"{\"text\":\"已补充,请查看\"}"}' \ | ||
| --as user | ||
|
|
||
| # 编辑本人评论或回复 | ||
| lark-cli approval comments create \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>"}' \ | ||
| --data '{"comment_id":"<COMMENT_ID>","content":"{\"text\":\"更新后的评论内容\"}"}' \ | ||
| --as user | ||
|
|
||
| # 只同步评论数据,不触发 bot | ||
| lark-cli approval comments create \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>"}' \ | ||
| --data '{"content":"{\"text\":\"仅同步评论\"}","disable_bot":true}' \ | ||
| --as user | ||
|
|
||
| # 创建带 @ 人的文本评论 | ||
| lark-cli approval comments create \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>","user_id_type":"open_id"}' \ | ||
| --data '{"content":"{\"text\":\"@张三 请补充说明\"}","at_info_list":[{"user_id":"ou_xxx","name":"张三","offset":"0"}]}' \ | ||
| --as user | ||
|
|
||
| # 预览 API 调用,不执行 | ||
| lark-cli approval comments create \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>"}' \ | ||
| --data '{"content":"{\"text\":\"请补充说明\"}"}' \ | ||
| --as user \ | ||
| --dry-run | ||
| ``` | ||
|
|
||
| ## 参数 | ||
|
|
||
| | 参数 | 必填 | 说明 | | ||
| |------|------|------| | ||
| | `--params '{...}'` | 是 | 路径和查询参数,使用 JSON 传入 | | ||
| | `instance_id` | 是 | 审批实例 Code;也兼容租户自定义审批实例 ID | | ||
| | `user_id_type` | 否 | 评论相关用户字段的 ID 类型:`open_id`、`user_id`、`union_id`;不填默认 `open_id` | | ||
| | `--data '{...}'` | 是 | 请求体 JSON,使用 JSON 传入 | | ||
| | `content` | 是 | 评论内容字符串;当前 CLI 引导只支持 `{"text":"..."}` 文本结构 | | ||
| | `at_info_list` | 否 | @ 人信息数组;元素包含 `user_id`、`name`、`offset`,并与 `content.text` 中的 @ 文案对应 | | ||
| | `parent_comment_id` | 回复时必填 | 父评论 ID;传入后创建回复 | | ||
| | `comment_id` | 编辑时必填 | 要编辑的评论或回复 ID;传入后编辑本人已有评论或回复 | | ||
| | `disable_bot` | 否 | `true` 表示只同步评论数据,不触发 bot | | ||
| | `extra` | 否 | 附加字段字符串 | | ||
| | `--as user` | 否 | 建议显式指定用户身份;当前操作人来自用户身份令牌,不从参数指定 | | ||
| | `--dry-run` | 否 | 预览 API 调用,不执行 | | ||
|
|
||
| ## content 格式 | ||
|
|
||
| `content` 是字符串,不是 JSON 对象。当前只按文本评论暴露: | ||
|
|
||
| ```json | ||
| { | ||
| "content": "{\"text\":\"请补充说明\"}" | ||
| } | ||
| ``` | ||
|
|
||
| @ 人评论需要同时设置 `content.text` 和 `at_info_list`: | ||
|
|
||
| ```json | ||
| { | ||
| "content": "{\"text\":\"@张三 请补充说明\"}", | ||
| "at_info_list": [ | ||
| { | ||
| "user_id": "ou_xxx", | ||
| "name": "张三", | ||
| "offset": "0" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| 其中 `offset` 从 0 开始,表示 `content.text` 中对应 @ 符号的位置;`user_id` 的类型需要和 `user_id_type` 保持一致。 | ||
|
|
||
| ## 使用建议 | ||
|
|
||
| - 创建、回复、编辑是同一个 OpenAPI action;根据 `parent_comment_id` 和 `comment_id` 判断语义。 | ||
| - 编辑只能编辑当前用户自己的评论或回复;不要尝试用参数伪造操作人。 | ||
| - `user_id_type` 只影响评论相关用户字段的 ID 类型,不用于指定当前操作人。 | ||
| - 先用 `comments list` 获取 `comment_id`,再执行回复、编辑或删除。 | ||
| - 当前只引导创建文本评论;不要写入非 `text` 的内容结构。 | ||
| - 这个接口不是清空评论;本期不要暴露或使用 `clear`。 |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| # approval comments delete | ||
|
|
||
| 删除审批实例下的一条评论或回复(用户级高风险写操作)。这个命令只删除指定 `comment_id`,不会清空实例下的全部评论。 | ||
|
|
||
| > [!CAUTION] | ||
| > 这是 **high-risk-write** 写操作。建议先用 `--dry-run` 预览;真正执行时,如果用户已明确要删除该条审批评论或回复且 `instance_id`、`comment_id` 都无误,再带 `--yes` 运行。不要在未获用户明确同意时静默追加 `--yes`。 | ||
|
|
||
| 需要的 scopes: ["approval:instance:write"] | ||
|
|
||
| ## 命令 | ||
|
|
||
| ```bash | ||
| # 先预览请求,不实际执行 | ||
| lark-cli approval comments delete \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>","comment_id":"<COMMENT_ID>"}' \ | ||
| --as user \ | ||
| --dry-run | ||
|
|
||
| # 删除一条顶层评论或回复 | ||
| lark-cli approval comments delete \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>","comment_id":"<COMMENT_ID>"}' \ | ||
| --as user \ | ||
| --yes | ||
|
|
||
| # 删除后回查确认 is_delete | ||
| lark-cli approval comments list \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>"}' \ | ||
| --as user | ||
| ``` | ||
|
|
||
| ## 参数 | ||
|
|
||
| | 参数 | 必填 | 说明 | | ||
| |------|------|------| | ||
| | `--params '{...}'` | 是 | 路径参数,使用 JSON 传入 | | ||
| | `instance_id` | 是 | 审批实例 Code;也兼容租户自定义审批实例 ID | | ||
| | `comment_id` | 是 | 要删除的评论或回复 ID | | ||
| | `--as user` | 否 | 建议显式指定用户身份;当前操作人来自用户身份令牌,不从参数指定 | | ||
| | `--yes` | 是 | 确认执行高风险写操作;未带时可能返回 `confirmation_required` / exit 10 | | ||
| | `--format` | 否 | 输出格式:`json`(默认)、`ndjson`、`table`、`csv` | | ||
| | `--dry-run` | 否 | 预览 API 调用,不执行;dry-run 不需要 `--yes` | | ||
|
|
||
| ## 使用建议 | ||
|
|
||
| - 先用 `comments list` 获取并确认目标 `comment_id`,再执行删除。 | ||
| - 这个命令删除单条评论或回复,不是清空全部评论;不要使用或暴露 `clear`。 | ||
| - 只能删除当前用户有权删除的评论或回复。通常本人评论可删除,非本人评论会被服务端权限校验拦截。 | ||
| - 删除后建议回查 `comments list`,确认目标评论或回复的 `is_delete=1`。 | ||
| - 不要通过额外参数指定操作人;UAT 接口会从当前用户身份令牌识别操作人。 |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| # approval comments list | ||
|
|
||
| 查询审批实例的评论树(用户级只读操作)。适合查看顶层评论、回复、评论创建人、删除标记、@ 人信息和图片 / 文件内容结构。 | ||
|
|
||
| 需要的 scopes: ["approval:instance:read"] | ||
|
|
||
| ## 命令 | ||
|
|
||
| ```bash | ||
| # 查询审批实例评论 | ||
| lark-cli approval comments list \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>"}' \ | ||
| --as user | ||
|
|
||
| # 指定返回用户字段的 ID 类型 | ||
| lark-cli approval comments list \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>","user_id_type":"open_id"}' \ | ||
| --as user | ||
|
|
||
| # 表格格式输出,便于快速浏览顶层字段 | ||
| lark-cli approval comments list \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>"}' \ | ||
| --format table \ | ||
| --as user | ||
|
|
||
| # 预览 API 调用,不执行 | ||
| lark-cli approval comments list \ | ||
| --params '{"instance_id":"<INSTANCE_CODE>"}' \ | ||
| --as user \ | ||
| --dry-run | ||
| ``` | ||
|
|
||
| ## 参数 | ||
|
|
||
| | 参数 | 必填 | 说明 | | ||
| |------|------|------| | ||
| | `--params '{...}'` | 是 | 路径和查询参数,使用 JSON 传入 | | ||
| | `instance_id` | 是 | 审批实例 Code;也兼容租户自定义审批实例 ID | | ||
| | `user_id_type` | 否 | 返回结果中用户字段的 ID 类型:`open_id`、`user_id`、`union_id`;不填默认 `open_id` | | ||
| | `--as user` | 否 | 建议显式指定用户身份;审批评论是用户态接口 | | ||
| | `--format` | 否 | 输出格式:`json`(默认)、`ndjson`、`table`、`csv` | | ||
| | `--dry-run` | 否 | 预览 API 调用,不执行 | | ||
|
Comment on lines
+37
to
+42
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- review file ---'
cat -n skills/lark-approval/references/lark-approval-comments-list.md | sed -n '1,120p'
printf '%s\n' '--- related symbols and pagination terms ---'
rg -n -S --glob '*.go' --glob '*.md' --glob '*.yml' --glob '*.yaml' \
'approval\.comments\.list|comments\.list|page_token|page_size|auto.?pag|pagination' \
skills cmd internal .github 2>/dev/null | head -n 240
printf '%s\n' '--- file diff ---'
git diff -- skills/lark-approval/references/lark-approval-comments-list.mdRepository: larksuite/cli Length of output: 39847 🤖 get_repo_knowledge executed:
Length of output: 44959 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- candidate registry and schema files ---'
fd -HI -t f 'meta_data|schema' . | head -n 120
printf '%s\n' '--- approval comments references ---'
rg -n -S 'approval|comments' . --glob '!**/*_test.go' --glob '!vendor/**' | head -n 240
printf '%s\n' '--- generic service pagination implementation ---'
cat -n cmd/service/service.go | sed -n '180,330p'
cat -n cmd/service/service.go | sed -n '560,750p'
printf '%s\n' '--- service command help/flag contract ---'
rg -n -S 'page-all|page-token|page-size|PaginationOptions|methodPaginates' cmd/service internal/client | head -n 220Repository: larksuite/cli Length of output: 50369 🤖 get_repo_knowledge executed:
Length of output: 8298 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- approval comments metadata ---'
rg -n -C 8 '"(approval\.comments\.list|comments\.list|page_token|page_size)"' internal/registry/meta_data_default.json | head -n 220
printf '%s\n' '--- schema command implementation ---'
cat -n cmd/schema/schema.go | sed -n '1,260p'
printf '%s\n' '--- service execution pagination decision ---'
cat -n cmd/service/service.go | sed -n '400,470p'
cat -n cmd/service/service.go | sed -n '680,790p'Repository: larksuite/cli Length of output: 17827 🤖 get_repo_knowledge executed:
Length of output: 17822 🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- registry default metadata shape ---'
wc -c internal/registry/meta_data_default.json
head -c 800 internal/registry/meta_data_default.json
printf '\n%s\n' '--- approval/pagination keys in default metadata ---'
rg -n -i -C 3 'approval|instance_id|page_token|page_size' internal/registry/meta_data_default.json | head -n 160 || true
printf '%s\n' '--- registry loading and metadata source ---'
rg -n -S 'meta_data_default|SchemaCatalog|Registry|metadata' internal/registry --glob '*.go' | head -n 160Repository: larksuite/cli Length of output: 5181 🌐 Web query:
💡 Result: To retrieve a list of comments for a Feishu/Lark approval instance using the Approval v4 API, you use the GET endpoint: https://open.larksuite.com/open-apis/approval/v4/instances/:instance_id/comments [1][2]. This API supports pagination to handle large numbers of comments [2]. Below are the details regarding the relevant pagination parameters and response structure [2]: Pagination Parameters: - page_size (int, optional): The maximum number of comments to return in a single request (e.g., 10) [2]. - page_token (string, optional): Used for pagination [2]. For the first request, this should be left empty to start from the beginning [2]. If there are more results, the response will include a new page_token, which you then pass in the next request to fetch the subsequent page [2]. Response Structure: The response contains a comments array, which lists the comments and their replies [1][2]. The response also includes pagination metadata, such as a has_more boolean indicator and the next page_token [3]. Technical Notes: - The:instance_id in the URL path is the Approval instance code [1][2]. - Required Scopes: To access this API, you must have at least one of the following scopes enabled: approval:approval, approval:approval:readonly, or approval:instance.comment [4][2]. - The API returns all comments and replies, excluding system-generated actions such as approved, rejected, or transferred statuses [1][2]. Citations:
🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- generated API parameter flag binding ---'
rg -n -S 'type paramFlagBinder|func \(.*paramFlagBinder|page-size|page-token|StringVar|IntVar' cmd/service internal/cmdutil | head -n 220
printf '%s\n' '--- exact request parameter construction ---'
cat -n cmd/service/paramflags.go 2>/dev/null | sed -n '1,280p' || true
cat -n cmd/service/service.go | sed -n '500,640p'Repository: larksuite/cli Length of output: 16347 补充审批评论的分页说明。 🤖 Prompt for AI AgentsSource: MCP tools |
||
|
|
||
| ## 输出重点字段 | ||
|
|
||
| | 字段 | 说明 | | ||
| |------|------| | ||
| | `comments[].id` | 顶层评论 ID;回复、编辑、删除时常用 | | ||
| | `comments[].content` | 评论内容字符串;按服务端原样返回,可能包含 `text`、`files` 等结构 | | ||
| | `comments[].commentator` | 评论创建人,格式受 `user_id_type` 影响 | | ||
| | `comments[].create_time` | 评论创建时间,毫秒级时间戳字符串 | | ||
| | `comments[].update_time` | 评论更新时间,毫秒级时间戳字符串 | | ||
| | `comments[].is_delete` | 是否已删除,`0` 未删除,`1` 已删除 | | ||
| | `comments[].replies[]` | 当前评论下的回复列表,字段结构与顶层评论类似 | | ||
| | `comments[].at_info_list[]` | 评论中的 @ 人信息 | | ||
|
|
||
| ## 使用建议 | ||
|
|
||
| - 审批评论挂在审批实例上,输入字段叫 `instance_id`,实际通常传审批实例 Code。 | ||
| - 如果要回复、编辑或删除评论,先用 `comments list` 获取目标 `comment_id`。 | ||
| - `comments list` 返回评论树;删除后的评论或回复可能仍在树中出现,但 `is_delete=1`。 | ||
| - `user_id_type` 只影响返回结果中的用户 ID 展示,不用于指定当前操作人;当前操作人来自用户身份令牌。 | ||
| - 这不是 Drive 文档评论;不要把审批实例评论误路由到 `drive +add-comment` 或 Drive comment API。 | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
Repository: larksuite/cli
Length of output: 47717
🤖 get_repo_knowledge executed:
get_repo_knowledge larksuite/cli /tmp/coderabbit-repo-knowledge/larksuite-cli-f41f2344/learnings /tmp/coderabbit-repo-knowledge/larksuite-cli-f41f2344/conventionsLength of output: 43935
🏁 Script executed:
Repository: larksuite/cli
Length of output: 4900
🌐 Web query:
Lark OpenAPI approval instance comments list create delete API required scopes user_access_token tenant_access_token💡 Result:
The Lark OpenAPI provides dedicated endpoints for managing comments on approval instances. All these operations require a tenant_access_token for authentication [1]. Required Scopes To perform operations on approval instance comments, your application must have at least one of the following scopes enabled [2][3][1]: - View, create, update, and delete info of Approval app (approval:approval) - Access Approval (approval:approval:readonly) [2][4] Additionally, if your API response requires specific user-related identity fields (e.g., using user_id instead of the default open_id), you must also include the following scope [2][3][5]: - Obtain user ID (contact:user.employee_id:readonly) API Endpoints - List Comments: Retrieves all comments and replies for a specific instance. - Method: GET - URL: https://open.larksuite.com/open-apis/approval/v4/instances/:instance_id/comments [2][4] - Create/Modify Comment (or Reply): Used to create new comments, edit existing comments, or reply to them. - Method: POST - URL: https://open.larksuite.com/open-apis/approval/v4/instances/:instance_id/comments [3][6] - Delete Specific Comment: Removes an individual comment/reply. - Method: DELETE - URL: https://open.larksuite.com/open-apis/approval/v4/instances/:instance_id/comments/:comment_id [1] - Clear All Comments: Removes all comments and replies under an approval instance. - Method: POST - URL: https://open.larksuite.com/open-apis/approval/v4/instances/:instance_id/comments/remove [5][1] Authentication These APIs are designed for server-side use and require a tenant_access_token [1][7]. While some Lark APIs support both user_access_token and tenant_access_token, the official approval comment documentation explicitly references the use of tenant_access_token [1][7]. Ensure your application has the necessary permissions configured in the Lark Developer Console to use these scopes [1].
Citations:
🏁 Script executed:
Repository: larksuite/cli
Length of output: 2586
🌐 Web query:
site:open.larksuite.com/document/server-docs/approval-v4/instance-comment "tenant_access_token" "approval:approval"💡 Result:
The term approval:approval refers to a permission scope required for accessing the Lark (or Feishu) Approval API [1][2]. When calling APIs related to the Approval module—such as creating, viewing, updating, or deleting approval instance comments—you must authenticate your request using a tenant_access_token [3][1][2]. In this context, tenant_access_token is the authorization mechanism used to identify your application to the Lark platform, and approval:approval is the specific permission scope that must be granted to your application in the Lark Developer Console to authorize those API calls [1][2]. To successfully perform these operations, you must include the tenant_access_token in the Authorization header of your HTTP request, formatted as a Bearer token (e.g., Authorization: Bearer t-xxxxxxxxxxxxxxxxxxxx) [3][1][2].
Citations:
🏁 Script executed:
Repository: larksuite/cli
Length of output: 19904
🌐 Web query:
Lark Feishu Approval V4 instance comment list create remove required permission scope tenant_access_token official documentation💡 Result:
For Lark/Feishu Approval V4 API instance comments, you must use a tenant_access_token for authentication [1][2]. The required permission scopes depend on the specific operation, and having at least one of the listed relevant scopes is sufficient [3][4][2]. Below are the details for the relevant API operations: 1. List Comments (GET /open-apis/approval/v4/instances/:instance_id/comments) - Required Scopes (enable any one): - View, create, update, and delete info of Approval app (approval:approval) [4][5] - Access Approval (approval:approval:readonly) [4][5] - View, create, update, and delete info in Approval comment (approval:instance.comment) [4][5] 2. Create/Modify Comments (POST /open-apis/approval/v4/instances/:instance_id/comments) - Required Scopes (enable any one): - View, create, update, and delete info of Approval app (approval:approval) [6][7][8] - View, create, update, and delete info in Approval comment (approval:instance.comment) [2] 3. Remove/Clear Comments (POST /open-apis/approval/v4/instances/:instance_id/comments/remove) - Required Scopes (enable any one): - View, create, update, and delete info of Approval app (approval:approval) [3][1] - View, create, update, and delete info in Approval comment (approval:instance.comment) [3][1][2] Note: If you need to retrieve sensitive fields such as user IDs from the response, you may also need the additional field scope: Obtain user ID (contact:user.employee_id:readonly) [3][4][5]. Always ensure your app is configured with the necessary permissions in the Lark Developer Console before making requests [9].
Citations:
🏁 Script executed:
Repository: larksuite/cli
Length of output: 16999
🌐 Web query:
site:open.feishu.cn/document/server-docs/approval-v4/instance-comment/list "approval:instance.comment" "tenant_access_token"💡 Result:
The terms approval:instance.comment and tenant_access_token are associated with the Feishu (Lark) Open Platform's Approval API [1][2]. approval:instance.comment is a specific permission scope required to perform operations—such as viewing, creating, updating, or deleting—related to comments on approval instances within the Feishu platform [1]. To successfully call APIs related to approval comments (for example, to list comments for a specific approval instance at https://open.feishu.cn/open-apis/approval/v4/instances/:instance_id/comments), an application must have this scope enabled [1]. tenant_access_token is the authentication credential required in the Authorization header to call these APIs [1]. When making the request, the token must be provided in the format Bearer access_token (e.g., Bearer t-7f1bcd13fc57d46bac21793a18e560) [1]. In summary, to interact with approval comments programmatically, your application must possess the approval:instance.comment scope and include a valid tenant_access_token in the request header [1].
Citations:
🏁 Script executed:
Repository: larksuite/cli
Length of output: 12160
将审批评论命令改为租户身份并更新 scope。
审批实例评论接口使用
tenant_access_token,不是user_access_token。接口要求approval:instance.comment或更高层级的审批权限;当前声明的approval:instance:read/write不匹配。请同步更新三个 reference 文件、skill-template/domains/approval.md和skills/lark-approval/SKILL.md中的 scope、身份说明及示例,将--as user改为--as bot。📍 Affects 5 files
skills/lark-approval/references/lark-approval-comments-list.md#L5-L5(this comment)skills/lark-approval/references/lark-approval-comments-create.md#L5-L5skills/lark-approval/references/lark-approval-comments-delete.md#L8-L8skill-template/domains/approval.md#L88-L89skills/lark-approval/SKILL.md#L101-L102🤖 Prompt for AI Agents
Source: MCP tools