fix(skills): align skill guidance with the typed error contract#1785
Closed
yukunlabs wants to merge 1 commit into
Closed
fix(skills): align skill guidance with the typed error contract#1785yukunlabs wants to merge 1 commit into
yukunlabs wants to merge 1 commit into
Conversation
Skill references written before the typed-error refactor still taught retired envelope shapes. AI agents following them now read what the CLI actually emits:
- permission recovery reads error.missing_scopes instead of the upstream permission_violations detail
- confirmation gates use type=confirmation, subtype=confirmation_required, and flat risk/action fields
- drive duplicate-remote failures are typed validation envelopes (failed_precondition with params[]), not duplicate_remote_path with error.detail
- drive batch partial failures are ok:false results on stdout, not an error.type=partial_failure stderr envelope
- minutes edit-permission and word-replace misses branch on stable error.code/error.subtype, not message text
- slides replace failures are stderr typed envelopes only; no raw backend response is printed to stdout
- slides and Base command outputs show the ok/identity/data success envelope instead of the raw {code,msg} OpenAPI wrapper
github-actions
Bot
added
domain/base
📝 WalkthroughWalkthroughThis PR is a documentation-only update across multiple skill and reference markdown files, aligning error and response field names with a new CLI contract: renaming ChangesResponse envelope and error field documentation updates
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Collaborator
|
Closing this PR because it was opened from the wrong GitHub identity. Recreating it from the evandance-owned branch. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills/lark-base/references/lark-base-data-query.md`:
- Around line 350-371: The CLI response section documents `error.code`,
`error.message`, and `error.hint`, but it omits the stable branching fields
already shown in the failure example. Update the Response 字段 table in
`lark-base-data-query.md` to include `error.type` and `error.subtype`, and make
it clear in the CLI 出参详情 around the success/failure examples that these typed
discriminators should be used alongside `error.code` when handling errors.
In `@skills/lark-slides/references/lark-slides-xml-presentation-slide-replace.md`:
- Around line 159-164: The failure envelope documentation is incomplete because
the example includes error.type and error.message but the field table in the
slide replace doc only lists error.code, error.subtype, and error.hint. Update
the table in the same section to add rows for error.type and error.message so
the stderr contract described by the slide-replace example is fully documented
and self-contained.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 1faa0078-5173-4a04-a4c2-be1d4ec70029
📒 Files selected for processing (20)
skills/lark-apps/references/lark-apps-openapi-key.mdskills/lark-base/SKILL.mdskills/lark-base/references/lark-base-dashboard-block-get-data.mdskills/lark-base/references/lark-base-data-query.mdskills/lark-drive/references/lark-drive-member-add.mdskills/lark-drive/references/lark-drive-pull.mdskills/lark-drive/references/lark-drive-push.mdskills/lark-drive/references/lark-drive-status.mdskills/lark-minutes/SKILL.mdskills/lark-minutes/references/lark-minutes-todo.mdskills/lark-shared/SKILL.mdskills/lark-slides/references/examples.mdskills/lark-slides/references/lark-slides-screenshot.mdskills/lark-slides/references/lark-slides-xml-presentation-slide-create.mdskills/lark-slides/references/lark-slides-xml-presentation-slide-delete.mdskills/lark-slides/references/lark-slides-xml-presentation-slide-get.mdskills/lark-slides/references/lark-slides-xml-presentation-slide-replace.mdskills/lark-slides/references/lark-slides-xml-presentations-get.mdskills/lark-vc-agent/SKILL.mdtests/cli_e2e/drive/coverage.md
Comment on lines
+350
to
+371
| ## CLI 出参详情 | ||
|
|
||
| **成功时：** | ||
| **成功时**（stdout，判断成功用 `ok == true` 或退出码 0）： | ||
|
|
||
| ```json | ||
| {"code": 0, "data": {"main_data": [{"dim_city": {"value": "北京"}, "total_amount": {"value": 12345.00}}, ...]}, "msg": ""} | ||
| {"ok": true, "identity": "user", "data": {"main_data": [{"dim_city": {"value": "北京"}, "total_amount": {"value": 12345.00}}, ...]}} | ||
| ``` | ||
|
|
||
| **失败时：** | ||
| **失败时**（stderr 类型化错误信封，非零退出码；`error.code` 是上游 API 错误码）： | ||
|
|
||
| ```json | ||
| {"code": 800004006, "data": {"error": {"code": 800004006, ...}}, "msg": "DSL validation failed"} | ||
| {"ok": false, "identity": "user", "error": {"type": "api", "subtype": "...", "code": 800004006, "message": "DSL validation failed", "hint": "..."}} | ||
| ``` | ||
|
|
||
| **Response 字段：** | ||
|
|
||
| | 字段 | 类型 | 说明 | | ||
| |------|------|------| | ||
| | `code` | int | 状态码，0 为成功 | | ||
| | `msg` | string | 错误信息 | | ||
| | `ok` | bool | 是否成功 | | ||
| | `data.main_data` | []object | 查询结果数组，每个元素为一行数据 | | ||
| | `data.error` | object | 失败时的错误详情 | | ||
| | `error.code` | int | 失败时的上游 API 错误码 | | ||
| | `error.message` / `error.hint` | string | 失败原因与建议的恢复动作 | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Document the stable error discriminators too.
The example already relies on error.type / error.subtype, but the table only explains error.code and the message fields. Please add the typed discriminator rows so readers don’t treat code as the only branching key.
♻️ Suggested table update
| 字段 | 类型 | 说明 |
|------|------|------|
| `ok` | bool | 是否成功 |
| `data.main_data` | []object | 查询结果数组，每个元素为一行数据 |
+| `error.type` | string | 错误大类 |
+| `error.subtype` | string | 细分错误类型 |
| `error.code` | int | 失败时的上游 API 错误码 |
| `error.message` / `error.hint` | string | 失败原因与建议的恢复动作 |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ## CLI 出参详情 | |
| **成功时：** | |
| **成功时**（stdout，判断成功用 `ok == true` 或退出码 0）： | |
| ```json | |
| {"code": 0, "data": {"main_data": [{"dim_city": {"value": "北京"}, "total_amount": {"value": 12345.00}}, ...]}, "msg": ""} | |
| {"ok": true, "identity": "user", "data": {"main_data": [{"dim_city": {"value": "北京"}, "total_amount": {"value": 12345.00}}, ...]}} | |
| ``` | |
| **失败时：** | |
| **失败时**（stderr 类型化错误信封，非零退出码；`error.code` 是上游 API 错误码）： | |
| ```json | |
| {"code": 800004006, "data": {"error": {"code": 800004006, ...}}, "msg": "DSL validation failed"} | |
| {"ok": false, "identity": "user", "error": {"type": "api", "subtype": "...", "code": 800004006, "message": "DSL validation failed", "hint": "..."}} | |
| ``` | |
| **Response 字段：** | |
| | 字段 | 类型 | 说明 | | |
| |------|------|------| | |
| | `code` | int | 状态码，0 为成功 | | |
| | `msg` | string | 错误信息 | | |
| | `ok` | bool | 是否成功 | | |
| | `data.main_data` | []object | 查询结果数组，每个元素为一行数据 | | |
| | `data.error` | object | 失败时的错误详情 | | |
| | `error.code` | int | 失败时的上游 API 错误码 | | |
| | `error.message` / `error.hint` | string | 失败原因与建议的恢复动作 | | |
| ## CLI 出参详情 | |
| **成功时**（stdout，判断成功用 `ok == true` 或退出码 0）： | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/lark-base/references/lark-base-data-query.md` around lines 350 - 371,
The CLI response section documents `error.code`, `error.message`, and
`error.hint`, but it omits the stable branching fields already shown in the
failure example. Update the Response 字段 table in `lark-base-data-query.md` to
include `error.type` and `error.subtype`, and make it clear in the CLI 出参详情
around the success/failure examples that these typed discriminators should be
used alongside `error.code` when handling errors.
Comment on lines
159
to
+164
| | 字段 | 类型 | 说明 | | ||
| |------|------|------| | ||
| | `data.revision_id` | integer | 成功时返回更新后最新版本号 | | ||
| | `data.failed_part_index` | integer | 失败的 part 在 `parts` 数组中的索引（从 0 起） | | ||
| | `data.failed_reason` | string | 失败原因 | | ||
| | `error.code` | integer | 失败时的上游 API 错误码 | | ||
| | `error.subtype` | string | 类型化错误子类，脚本可与 `error.code` 一起判断恢复动作 | | ||
| | `error.hint` | string | 建议的恢复动作 | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Document the full failure envelope.
The new example exposes error.type and error.message, but the field table only covers error.code, error.subtype, and error.hint. Please add the missing rows so the typed stderr contract is self-contained for scripts and agents.
Proposed fix
| `data.revision_id` | integer | 成功时返回更新后最新版本号 |
+| `error.type` | string | 失败时的错误类型 |
+| `error.message` | string | 失败原因说明 |
| `error.code` | integer | 失败时的上游 API 错误码 |
| `error.subtype` | string | 类型化错误子类，脚本可与 `error.code` 一起判断恢复动作 |
| `error.hint` | string | 建议的恢复动作 |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | 字段 | 类型 | 说明 | | |
| |------|------|------| | |
| | `data.revision_id` | integer | 成功时返回更新后最新版本号 | | |
| | `data.failed_part_index` | integer | 失败的 part 在 `parts` 数组中的索引（从 0 起） | | |
| | `data.failed_reason` | string | 失败原因 | | |
| | `error.code` | integer | 失败时的上游 API 错误码 | | |
| | `error.subtype` | string | 类型化错误子类，脚本可与 `error.code` 一起判断恢复动作 | | |
| | `error.hint` | string | 建议的恢复动作 | | |
| | 字段 | 类型 | 说明 | | |
| |------|------|------| | |
| | `data.revision_id` | integer | 成功时返回更新后最新版本号 | | |
| | `error.type` | string | 失败时的错误类型 | | |
| | `error.message` | string | 失败原因说明 | | |
| | `error.code` | integer | 失败时的上游 API 错误码 | | |
| | `error.subtype` | string | 类型化错误子类，脚本可与 `error.code` 一起判断恢复动作 | | |
| | `error.hint` | string | 建议的恢复动作 | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/lark-slides/references/lark-slides-xml-presentation-slide-replace.md`
around lines 159 - 164, The failure envelope documentation is incomplete because
the example includes error.type and error.message but the field table in the
slide replace doc only lists error.code, error.subtype, and error.hint. Update
the table in the same section to add rows for error.type and error.message so
the stderr contract described by the slide-replace example is fully documented
and self-contained.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Align skill/reference guidance with the current typed error contract so agents do not follow retired raw OpenAPI or legacy envelope shapes. This is a docs-only fix across Lark skill docs and related drive coverage notes.
Changes
missing_scopes,type=confirmation,subtype=confirmation_required, flatrisk/action, and stdoutok:falsepartial results).{code,msg}/ backend-response examples in Base and Slides docs with the CLI success/error envelopes that agents actually see.error.code/error.subtypeinstead of human message text.Test Plan
lark-cli <domain> <command>flow works as expectedLARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 lark-cli drive +delete --file-token file_token_test --type file --as botexits 10 and emits a typed confirmation envelope withtype=confirmation,subtype=confirmation_required, flatrisk, andaction.git diff --check origin/main...HEADRelated Issues
Summary by CodeRabbit
Documentation
okandidentityfields in examples.Tests