feat(doc): add v2 API for docs +create / +fetch / +update#638
Open
SunPeiYang996 wants to merge 1 commit intomainfrom
Open
feat(doc): add v2 API for docs +create / +fetch / +update#638SunPeiYang996 wants to merge 1 commit intomainfrom
SunPeiYang996 wants to merge 1 commit intomainfrom
Conversation
|
|
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds OpenAPI v2 implementations for docs create/fetch/update with runtime routing via Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant CLI as CLI Runtime
participant Router as Version Router
participant V2 as V2 Handler (OpenAPI)
participant V1 as V1 Handler (MCP)
participant API as Lark API
participant Output as Output Formatter
User->>CLI: docs +create --api-version v2 --content "<title>...<\/title>\n..."
CLI->>Router: evaluate flags / useV2Create()
Router->>V2: validateCreateV2()
V2->>V2: buildCreateBody()
Router->>V2: executeCreateV2()
V2->>API: POST /open-apis/docs_ai/v1/documents
API-->>V2: { data: { document: { document_id, revision_id, url, new_blocks } } }
V2->>V2: augment response (bot permission flow)
V2->>API: AutoGrantCurrentUserDrivePermission (optional)
API-->>V2: permission_grant result
V2->>Output: OutRaw(augmented response)
Output-->>User: JSON (no HTML escaping)
rect rgba(200,200,100,0.5)
Note over Router,V1: Alternative flow when useV2Create() == false
User->>CLI: docs +create --title "Old"
Router->>V1: validateCreateV1() -> executeCreateV1()
V1->>API: MCP create_document call
API-->>V1: MCP-style response
V1->>Output: Out(result)
Output-->>User: JSON
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~55 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
github-actions
Bot
added
domain/ccm
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 17
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
skills/lark-drive/references/lark-drive-add-comment.md (1)
6-6:⚠️ Potential issue | 🟡 MinorRemove stale
--selection-with-ellipsisdocumentation.This page now documents block-id targeting, but it still says
--selection-with-ellipsiscreates local comments and keeps duplicate parameter rows. That makes the supported local-comment path ambiguous.Proposed cleanup
-给文档或电子表格添加评论。底层统一走 `/open-apis/drive/v1/files/:file_token/new_comments`（`create_v2`）接口；未指定位置时省略 `anchor` 创建全文评论，指定 `--selection-with-ellipsis` 或 `--block-id` 时传入 `anchor.block_id` 创建局部评论。支持直接传 docx URL/token、旧版 doc URL（仅全文评论）、sheet URL，也支持传最终可解析为 doc/docx/sheet 的 wiki URL。 +给文档或电子表格添加评论。底层统一走 `/open-apis/drive/v1/files/:file_token/new_comments`（`create_v2`）接口；未指定位置时省略 `anchor` 创建全文评论，指定 `--block-id` 时传入 `anchor.block_id` 创建局部评论。支持直接传 docx URL/token、旧版 doc URL（仅全文评论）、sheet URL，也支持传最终可解析为 doc/docx/sheet 的 wiki URL。 @@ | `--content` | 是 | `reply_elements` JSON 数组字符串。示例：`'[{"type":"text","text":"文本"},{"type":"mention_user","text":"ou_xxx"},{"type":"link","text":"https://example.com"}]'` | | `--full-comment` | 否 | 显式指定创建全文评论；未传 `--block-id` 时也会默认走全文评论 | | `--block-id` | 局部评论时必填 | 目标块 ID，可通过 `docs +fetch --api-version v2 --detail with-ids` 获取 | -| `--full-comment` | 否 | 显式指定创建全文评论；未传 `--selection-with-ellipsis` / `--block-id` 时也会默认走全文评论（不适用于 sheet） | -| `--block-id` | 局部评论时二选一 | 已知目标块 ID 时直接使用；与 `--selection-with-ellipsis` 互斥。**Sheet 评论**：格式为 `<sheetId>!<cell>`（如 `a281f9!D6`） | @@ - **局部评论需要先获取 block ID**：先调用 `docs +fetch --api-version v2 --doc <TOKEN> --detail with-ids` 获取带有 block ID 的文档内容，然后使用 `--block-id` 指定目标块。 - 未传 `--block-id` 时，shortcut 默认创建**全文评论**；也可以显式传 `--full-comment`。 -- **Sheet 评论**：当 `--doc` 为 sheet URL 或 wiki 解析为 sheet 时，使用 `--block-id "<sheetId>!<cell>"` 指定单元格（如 `a281f9!D6`）。此时 `--full-comment` 和 `--selection-with-ellipsis` 不可用。 -- **无需预先获取文档内容**：使用 `--selection-with-ellipsis` 时，shortcut 内部会自动调用 `locate-doc` 定位目标文本，不需要先调用 `docs +fetch` 获取文档。 -- 未传 `--selection-with-ellipsis` / `--block-id` 时，shortcut 默认创建**全文评论**；也可以显式传 `--full-comment`。 +- **Sheet 评论**：当 `--doc` 为 sheet URL 或 wiki 解析为 sheet 时，使用 `--block-id "<sheetId>!<cell>"` 指定单元格（如 `a281f9!D6`）。此时 `--full-comment` 不可用。Also applies to: 95-108
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-drive/references/lark-drive-add-comment.md` at line 6, Remove the stale documentation that claims `--selection-with-ellipsis` creates local comments: delete the duplicate parameter rows and any text that describes `--selection-with-ellipsis` as a supported local-comment path, and instead make the local-targeting flow explicit by documenting only `--block-id` (and the underlying API `/open-apis/drive/v1/files/:file_token/new_comments` / `create_v2`) as the way to create block-scoped comments; ensure any remaining references to selection-based local comments are removed or replaced with the `--block-id` explanation so there is no ambiguity.
🧹 Nitpick comments (4)
shortcuts/common/runner.go (1)
500-515: AlignoutputErrcapture withOut().
OutRawcaptures the jq error via a plainif ctx.outputErr == nilcheck, whileOut()usesctx.outputErrOnce.Do(...). Aside from the consistency smell, this loses the once-only guarantee ifOutRawever gets called alongsideOuton the same runtime. Prefer reusing the existing guard.♻️ Proposed fix
if ctx.JqExpr != "" { if err := output.JqFilter(ctx.IO().Out, env, ctx.JqExpr); err != nil { fmt.Fprintf(ctx.IO().ErrOut, "error: %v\n", err) - if ctx.outputErr == nil { - ctx.outputErr = err - } + ctx.outputErrOnce.Do(func() { ctx.outputErr = err }) } return }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/common/runner.go` around lines 500 - 515, OutRaw currently sets ctx.outputErr with a plain `if ctx.outputErr == nil { ctx.outputErr = err }` which breaks the once-only guarantee used by Out(); change it to use the same once guard: inside the jq error branch call `ctx.outputErrOnce.Do(func(){ ctx.outputErr = err })` (capturing the err variable) instead of the plain check so OutRaw and Out share identical once-only semantics for setting outputErr.shortcuts/doc/docs_update_test.go (1)
12-31: AssertvalidCommandsV2Keys()as well as the map.
v2UpdateFlags()exposesvalidCommandsV2Keys()as the CLI enum, so this test can still pass if the helper drifts fromvalidCommandsV2.Proposed test hardening
func TestValidCommandsV2(t *testing.T) { expected := map[string]bool{ "str_replace": true, "block_delete": true, @@ for cmd := range validCommandsV2 { if !expected[cmd] { t.Fatalf("unexpected command %q in validCommandsV2", cmd) } } + + keys := validCommandsV2Keys() + if len(keys) != len(expected) { + t.Fatalf("expected %d command keys, got %d", len(expected), len(keys)) + } + seen := map[string]bool{} + for _, cmd := range keys { + if !validCommandsV2[cmd] { + t.Fatalf("unexpected command %q in validCommandsV2Keys", cmd) + } + if seen[cmd] { + t.Fatalf("duplicate command %q in validCommandsV2Keys", cmd) + } + seen[cmd] = true + } }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_update_test.go` around lines 12 - 31, The test currently only validates the map validCommandsV2; also call validCommandsV2Keys() (the helper used by v2UpdateFlags()) and assert its length matches len(validCommandsV2) and that every key returned by validCommandsV2Keys() exists in validCommandsV2 (and vice versa) so the helper cannot drift from the map; update TestValidCommandsV2 to fetch keys via validCommandsV2Keys(), compare lengths, and check mutual membership between the slice/keys and the map.shortcuts/doc/docs_update_v2.go (2)
13-39: DedupevalidCommandsV2andvalidCommandsV2Keys— single source of truth.
validCommandsV2(map) andvalidCommandsV2Keys()(slice) encode the same list of commands. Maintaining both risks drift when a new command is added. Derive the keys from the map (sorted for deterministic Enum/help output) or declare a single[]stringand build the lookup map from it.♻️ Proposed refactor
-var validCommandsV2 = map[string]bool{ - "str_replace": true, - "block_delete": true, - "block_insert_after": true, - "block_copy_insert_after": true, - "block_replace": true, - "block_move_after": true, - "overwrite": true, - "append": true, -} +var v2Commands = []string{ + "str_replace", + "block_delete", + "block_insert_after", + "block_copy_insert_after", + "block_replace", + "block_move_after", + "overwrite", + "append", +} + +var validCommandsV2 = func() map[string]bool { + m := make(map[string]bool, len(v2Commands)) + for _, c := range v2Commands { + m[c] = true + } + return m +}() @@ -func validCommandsV2Keys() []string { - return []string{"str_replace", "block_delete", "block_insert_after", "block_copy_insert_after", "block_replace", "block_move_after", "overwrite", "append"} -} +func validCommandsV2Keys() []string { return v2Commands }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_update_v2.go` around lines 13 - 39, The command list is duplicated between validCommandsV2 (map) and validCommandsV2Keys(), causing drift; pick one source of truth (prefer a single []string like validCommandsV2List) and derive the other from it: create a slice (e.g., validCommandsV2List) containing the commands, build validCommandsV2 (map[string]bool) from that slice at init, and have validCommandsV2Keys() return a sorted copy of the slice (or return the slice directly) so Enum in v2UpdateFlags uses the single canonical list; update references to validCommandsV2 and validCommandsV2Keys accordingly.
135-164:append+ user-supplied--block-idsilently overrides the user value.When
--command appendis used,buildUpdateBodyunconditionally rewritesblock_idto"-1"— even if the caller explicitly passed--block-id. Sinceappendis documented as a shorthand, that's acceptable, but it would be safer to reject the combination invalidateUpdateV2so the override isn't surprising.🔧 Proposed fix
case "append": if content == "" { return common.FlagErrorf("--command append requires --content") } + if blockID != "" { + return common.FlagErrorf("--command append does not accept --block-id (it always appends at end of document)") + }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_update_v2.go` around lines 135 - 164, buildUpdateBody currently forces block_id to "-1" when command == "append", silently overriding any user-supplied --block-id; update validateUpdateV2 to detect this conflicting input and return/raise an error when runtime.Str("command") == "append" and runtime.Str("block-id") is non-empty (or when the parsed flag for block-id is set), so callers cannot pass both append and a custom block-id; reference the validateUpdateV2 function to implement the check and return a clear validation error message instead of allowing buildUpdateBody to silently overwrite the value.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Line 204: The CLI example uses literal "\n" inside the --content string so
bash will pass backslash-n characters instead of newlines; update the lark-cli
invocation shown (the line with lark-cli docs +create --doc-format markdown
--content) to provide a real multiline body by using one of the suggested
approaches: use ANSI-C quoting $'...\\n...' to expand \n, switch to a heredoc to
embed an actual multiline Markdown payload, or reference a file via --content
`@weekly.md` and include the Markdown in that file; ensure the replacement
preserves the same title/heading/list content but results in actual newline
characters in the sent content.
In `@README.zh.md`:
- Line 205: The example command uses double quotes so the literal sequence "\n"
will not be expanded to newlines by the shell; update the example for `lark-cli
docs +create --doc-format markdown --content` to pass a real multiline body (use
$'...'' to expand \n, a heredoc to supply the Markdown text, or show the
`--content `@file.md`` form) so the Markdown headings like `# 本周进展` are received
as actual newlines rather than the two-character sequence `\`+`n`.
In `@shortcuts/doc/docs_create_v2.go`:
- Around line 33-43: dryRunCreateV2 currently calls Desc() twice which
overwrites the initial "OpenAPI: create document" text when runtime.IsBot() is
true; change the function to build a single desc string (start with "OpenAPI:
create document" and, if runtime.IsBot(), append the bot-specific sentence) and
call d.Desc(desc) only once so both messages appear; update the code around
function dryRunCreateV2, the d := common.NewDryRunAPI()... chain and the
runtime.IsBot() branch to use this composed desc before invoking Desc().
In `@shortcuts/doc/docs_fetch_v2.go`:
- Around line 17-30: The v2-only flags in v2FetchFlags are missing Hidden: true,
causing them to show under --api-version v1; update the v2FetchFlags function so
that the flags "scope", "start-block-id", "end-block-id", "keyword",
"context-before", "context-after", and "max-depth" include Hidden: true (match
the pattern used in v2CreateFlags / v2UpdateFlags) so all v2-only flags are
consistently hidden when API v1 is active.
In `@shortcuts/doc/docs_fetch.go`:
- Around line 108-117: The pagination hint is being written into the OutFormat
writer (stdout) inside the anonymous callback passed to runtime.OutFormat, which
pollutes program output; change the code that prints the hint when
result["has_more"] is true so it writes to stderr instead (e.g., use
fmt.Fprintln(os.Stderr, "...--- more content available, use --offset and --limit
to paginate ---") ), keep the title and markdown writes to the provided writer
w, and add an os import if missing so the hint is emitted to stderr while the
JSON/program output stays on stdout.
- Around line 30-47: The current useV2Fetch auto-detects v2 even when the user
explicitly passed --api-version v1; change useV2Fetch so that if
runtime.Str("api-version") is non-empty you respect it (return true if exactly
"v2", false if exactly "v1") and skip all auto-detect checks; only run the
existing detail/doc-format/revision-id/scope checks when api-version was not
explicitly provided (empty) so v2-only flags don't silently override an explicit
v1 selection; reference function useV2Fetch and the runtime.Str keys
"api-version", "detail", "doc-format", "scope" and runtime.Int("revision-id")
when applying this change.
In `@shortcuts/doc/docs_update_v2.go`:
- Around line 55-58: The str_replace branch only validates pattern but must also
require a non-empty replacement content; add a check in the "str_replace" case
(alongside the existing pattern check) that returns common.FlagErrorf("--command
str_replace requires --content") when the content variable is empty, mirroring
the validation style used in block_insert_after so the API always receives a
populated replacement field.
In `@shortcuts/doc/versioned_help.go`:
- Around line 33-40: The deprecation note is being written to stdout via
cmd.OutOrStdout() (when ver == "v1"), which mixes warnings with program output;
change the fmt.Fprintf target to cmd.ErrOrStderr() (or cmd.Err() if preferred)
so the message goes to stderr instead, keeping the existing text and formatting
and leaving cmd.Parent().Name() and cmd.Name() usage intact.
In `@skill-template/domains/drive.md`:
- Line 115: Update the localized sentence in drive.md to include the missing API
version flag so it matches the v2 fetch guidance: when describing the
`--block-id` usage (and the `--detail with-ids` v2 behavior), explicitly mention
and show `--api-version v2` alongside `--block-id`; ensure the phrasing mirrors
the concrete example in skills/lark-drive/SKILL.md so readers know the
`--api-version v2` is required for `docx`/wiki-to-docx block-id fetches.
In `@skills/lark-doc/references/lark-doc-create.md`:
- Around line 66-72: The Markdown table separator row uses `--` which prevents
proper table rendering; update the separator row to use at least three hyphens
per column (e.g., `---`) so the header line aligns with the columns for entries
like `--api-version`, `--content`, `--doc-format`, `--parent-token`, and
`--parent-position`; ensure the separator row has the same number of cells as
the header (e.g., `| --- | --- | --- |`) and preserve the existing header and
rows.
In `@skills/lark-doc/references/lark-doc-fetch.md`:
- Around line 34-46: The Markdown tables for `--detail` and `--scope` lack
surrounding blank lines causing MD058; edit the document to insert a blank line
before each table (i.e., add an empty line between the preceding paragraph and
the table rows for the `--detail` table and likewise before the `--scope` table)
so both tables are separated from adjacent text and comply with markdownlint.
In `@skills/lark-doc/references/lark-doc-md.md`:
- Line 7: The bold markers are mismatched in the sentence "⚠️
当文本中包含以下字符且**不想**触发 Markdown 语法时，需用 `\` 前缀转义。": remove the inner `**` around 不想
so only the outer `**` pair surrounds the whole phrase, and make sure the
backslash is wrapped in single backticks (e.g., `\`) outside the bold span so
the inline code for the escape character renders correctly; update the fragment
in the markdown (the line containing "⚠️ 当文本中包含以下字符且…") accordingly.
In `@skills/lark-doc/references/lark-doc-media-insert.md`:
- Line 51: The CLI example contains a typo: replace the incorrect binary name
"lak-cli" in the example command string `lak-cli docs +update --api-version v2
--doc "<doc_id>" --command block_insert_after \` with the correct binary name
(e.g., "lake-cli") so users won't get a command-not-found error; update that
literal in the file so the example matches the actual CLI binary.
In `@skills/lark-doc/references/lark-doc-update.md`:
- Around line 12-18: The docs incorrectly state "seven" commands (should be
eight), reference a non-existent --target-block-id, and show block_move_after
accepting --content and a malformed --block-id; update the v2 update command
section to list all eight commands (str_replace, block_insert_after,
block_replace, block_delete, block_move_after, append, overwrite, plus the
missing one), remove or replace every mention of the nonexistent
--target-block-id with the correct flag usage (use --block-id to identify the
block being acted on and use --after-block-id to indicate the destination for
move semantics), and fix the block_move_after invocation/flag list so it
requires a source --block-id and a destination --after-block-id (no --content
for moves) and show --block-id as a single valid block ID string; also apply the
same corrections to the other occurrences noted (the other two ranges).
In `@skills/lark-doc/references/lark-doc-xml.md`:
- Around line 23-33: The table rows for `<button>` and `<time>` contain
unescaped pipe characters (e.g., OpenLink|DuplicatePage|FollowPage and
true|false) that break the Markdown table; update the `<button>` and `<time>`
cells by escaping those pipes (e.g., `OpenLink\|DuplicatePage\|FollowPage` and
`true\|false`) or wrap the entire attribute value in inline code formatting
(backticks) so the pipes are treated as literal characters rather than column
separators.
In `@skills/lark-doc/references/style/lark-doc-create-workflow.md`:
- Around line 38-43: Replace the typo "进润" with "润色" in the heading/line that
reads "Spawn Agent 定向改进：（结合 `lark-doc-style.md` 进润）" so it correctly reads
"Spawn Agent 定向改进：（结合 `lark-doc-style.md` 润色）"; ensure the change occurs in the
"第四波 — 润色与图表（并行 Agent）" section and update any other occurrences of "进润" in that
markdown to maintain consistency.
In `@skills/lark-doc/references/style/lark-doc-update-workflow.md`:
- Around line 21-26: Update the scoped fetch examples to explicitly use v2 by
adding the flag `--api-version v2` to each of the `--scope` examples (the
`--scope outline`, `--scope section --start-block-id <目标标题id> --detail
with-ids`, `--scope range --start-block-id xxx --end-block-id yyy`, and `--scope
keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids`
usages) so they won't fall back to v1; also add `--api-version v2` to the other
scoped example referenced on the later line (the one noted at Line 48) to ensure
all scoped fetch guidance consistently targets v2.
---
Outside diff comments:
In `@skills/lark-drive/references/lark-drive-add-comment.md`:
- Line 6: Remove the stale documentation that claims `--selection-with-ellipsis`
creates local comments: delete the duplicate parameter rows and any text that
describes `--selection-with-ellipsis` as a supported local-comment path, and
instead make the local-targeting flow explicit by documenting only `--block-id`
(and the underlying API `/open-apis/drive/v1/files/:file_token/new_comments` /
`create_v2`) as the way to create block-scoped comments; ensure any remaining
references to selection-based local comments are removed or replaced with the
`--block-id` explanation so there is no ambiguity.
---
Nitpick comments:
In `@shortcuts/common/runner.go`:
- Around line 500-515: OutRaw currently sets ctx.outputErr with a plain `if
ctx.outputErr == nil { ctx.outputErr = err }` which breaks the once-only
guarantee used by Out(); change it to use the same once guard: inside the jq
error branch call `ctx.outputErrOnce.Do(func(){ ctx.outputErr = err })`
(capturing the err variable) instead of the plain check so OutRaw and Out share
identical once-only semantics for setting outputErr.
In `@shortcuts/doc/docs_update_test.go`:
- Around line 12-31: The test currently only validates the map validCommandsV2;
also call validCommandsV2Keys() (the helper used by v2UpdateFlags()) and assert
its length matches len(validCommandsV2) and that every key returned by
validCommandsV2Keys() exists in validCommandsV2 (and vice versa) so the helper
cannot drift from the map; update TestValidCommandsV2 to fetch keys via
validCommandsV2Keys(), compare lengths, and check mutual membership between the
slice/keys and the map.
In `@shortcuts/doc/docs_update_v2.go`:
- Around line 13-39: The command list is duplicated between validCommandsV2
(map) and validCommandsV2Keys(), causing drift; pick one source of truth (prefer
a single []string like validCommandsV2List) and derive the other from it: create
a slice (e.g., validCommandsV2List) containing the commands, build
validCommandsV2 (map[string]bool) from that slice at init, and have
validCommandsV2Keys() return a sorted copy of the slice (or return the slice
directly) so Enum in v2UpdateFlags uses the single canonical list; update
references to validCommandsV2 and validCommandsV2Keys accordingly.
- Around line 135-164: buildUpdateBody currently forces block_id to "-1" when
command == "append", silently overriding any user-supplied --block-id; update
validateUpdateV2 to detect this conflicting input and return/raise an error when
runtime.Str("command") == "append" and runtime.Str("block-id") is non-empty (or
when the parsed flag for block-id is set), so callers cannot pass both append
and a custom block-id; reference the validateUpdateV2 function to implement the
check and return a clear validation error message instead of allowing
buildUpdateBody to silently overwrite the value.
🪄 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: 63530373-8f62-4f8f-b650-fd59f587eacc
📒 Files selected for processing (31)
README.mdREADME.zh.mdshortcuts/common/runner.goshortcuts/common/types.goshortcuts/doc/docs_create.goshortcuts/doc/docs_create_test.goshortcuts/doc/docs_create_v2.goshortcuts/doc/docs_fetch.goshortcuts/doc/docs_fetch_v2.goshortcuts/doc/docs_update.goshortcuts/doc/docs_update_test.goshortcuts/doc/docs_update_v2.goshortcuts/doc/helpers.goshortcuts/doc/versioned_help.goskill-template/domains/drive.mdskills/lark-doc/SKILL.mdskills/lark-doc/references/lark-doc-create.mdskills/lark-doc/references/lark-doc-fetch.mdskills/lark-doc/references/lark-doc-md.mdskills/lark-doc/references/lark-doc-media-insert.mdskills/lark-doc/references/lark-doc-update.mdskills/lark-doc/references/lark-doc-xml.mdskills/lark-doc/references/style/lark-doc-create-workflow.mdskills/lark-doc/references/style/lark-doc-style.mdskills/lark-doc/references/style/lark-doc-update-workflow.mdskills/lark-drive/SKILL.mdskills/lark-drive/references/lark-drive-add-comment.mdskills/lark-event/references/lark-event-subscribe.mdskills/lark-vc/SKILL.mdskills/lark-whiteboard/SKILL.mdskills/lark-workflow-meeting-summary/SKILL.md
Comment on lines
+17
to
+30
| func v2FetchFlags() []common.Flag { | ||
| return []common.Flag{ | ||
| {Name: "doc-format", Desc: "content format", Hidden: true, Default: "xml", Enum: []string{"xml", "markdown", "text"}}, | ||
| {Name: "detail", Desc: "export detail level: simple (read-only) | with-ids (block IDs for cross-referencing) | full (all attrs for editing)", Hidden: true, Default: "simple", Enum: []string{"simple", "with-ids", "full"}}, | ||
| {Name: "revision-id", Desc: "document revision (-1 = latest)", Hidden: true, Type: "int", Default: "-1"}, | ||
| {Name: "scope", Desc: "partial read scope: outline | range | keyword | section (omit to read whole doc)", Default: "full", Enum: []string{"full", "outline", "range", "keyword", "section"}}, | ||
| {Name: "start-block-id", Desc: "range/section mode: start (anchor) block id"}, | ||
| {Name: "end-block-id", Desc: "range mode: end block id; \"-1\" = to end of document"}, | ||
| {Name: "keyword", Desc: "keyword mode: search string (case-insensitive); use '|' to match multiple keywords, e.g. 'foo|bar|baz'"}, | ||
| {Name: "context-before", Desc: "range/keyword/section mode: sibling blocks before match", Type: "int", Default: "0"}, | ||
| {Name: "context-after", Desc: "range/keyword/section mode: sibling blocks after match", Type: "int", Default: "0"}, | ||
| {Name: "max-depth", Desc: "outline: heading level cap; range/keyword/section: block subtree depth (-1 = unlimited)", Type: "int", Default: "-1"}, | ||
| } | ||
| } |
There was a problem hiding this comment.
Missing Hidden: true on v2-only fetch flags — inconsistent with docs_create_v2.go / docs_update_v2.go.
--scope, --start-block-id, --end-block-id, --keyword, --context-before, --context-after, and --max-depth are v2-only but not declared Hidden: true, so when the user runs docs +fetch --help under the default --api-version v1, installVersionedHelp's unhide/hide logic works, but any non-help usage print (e.g., on flag parse errors before help is dispatched) will still surface these v2-only flags under v1. All other v2 shortcuts in this PR (v2CreateFlags, v2UpdateFlags) consistently mark every v2-only flag Hidden: true.
🔧 Proposed fix
- {Name: "scope", Desc: "partial read scope: outline | range | keyword | section (omit to read whole doc)", Default: "full", Enum: []string{"full", "outline", "range", "keyword", "section"}},
- {Name: "start-block-id", Desc: "range/section mode: start (anchor) block id"},
- {Name: "end-block-id", Desc: "range mode: end block id; \"-1\" = to end of document"},
- {Name: "keyword", Desc: "keyword mode: search string (case-insensitive); use '|' to match multiple keywords, e.g. 'foo|bar|baz'"},
- {Name: "context-before", Desc: "range/keyword/section mode: sibling blocks before match", Type: "int", Default: "0"},
- {Name: "context-after", Desc: "range/keyword/section mode: sibling blocks after match", Type: "int", Default: "0"},
- {Name: "max-depth", Desc: "outline: heading level cap; range/keyword/section: block subtree depth (-1 = unlimited)", Type: "int", Default: "-1"},
+ {Name: "scope", Desc: "partial read scope: outline | range | keyword | section (omit to read whole doc)", Hidden: true, Default: "full", Enum: []string{"full", "outline", "range", "keyword", "section"}},
+ {Name: "start-block-id", Desc: "range/section mode: start (anchor) block id", Hidden: true},
+ {Name: "end-block-id", Desc: "range mode: end block id; \"-1\" = to end of document", Hidden: true},
+ {Name: "keyword", Desc: "keyword mode: search string (case-insensitive); use '|' to match multiple keywords, e.g. 'foo|bar|baz'", Hidden: true},
+ {Name: "context-before", Desc: "range/keyword/section mode: sibling blocks before match", Hidden: true, Type: "int", Default: "0"},
+ {Name: "context-after", Desc: "range/keyword/section mode: sibling blocks after match", Hidden: true, Type: "int", Default: "0"},
+ {Name: "max-depth", Desc: "outline: heading level cap; range/keyword/section: block subtree depth (-1 = unlimited)", Hidden: true, Type: "int", Default: "-1"},🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@shortcuts/doc/docs_fetch_v2.go` around lines 17 - 30, The v2-only flags in
v2FetchFlags are missing Hidden: true, causing them to show under --api-version
v1; update the v2FetchFlags function so that the flags "scope",
"start-block-id", "end-block-id", "keyword", "context-before", "context-after",
and "max-depth" include Hidden: true (match the pattern used in v2CreateFlags /
v2UpdateFlags) so all v2-only flags are consistently hidden when API v1 is
active.
Comment on lines
+30
to
+47
| func useV2Fetch(runtime *common.RuntimeContext) bool { | ||
| if runtime.Str("api-version") == "v2" { | ||
| return true | ||
| } | ||
| // --doc-format default is "xml", --detail default is "simple", --revision-id default is -1. | ||
| // Only trigger auto-detect when a non-default value is present. | ||
| if d := runtime.Str("detail"); d != "" && d != "simple" { | ||
| return true | ||
| } | ||
| if f := runtime.Str("doc-format"); f != "" && f != "xml" { | ||
| return true | ||
| } | ||
| if runtime.Int("revision-id") != -1 { | ||
| return true | ||
| } | ||
| if m := runtime.Str("scope"); m != "" && m != "full" { | ||
| return true | ||
| } |
There was a problem hiding this comment.
Don’t let v2-only flags silently override explicit v1 selection.
With the current logic, --api-version v1 --detail with-ids still routes to v2. Either reject mixed v1/v2 flags or only auto-detect v2 when --api-version was not explicitly set.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@shortcuts/doc/docs_fetch.go` around lines 30 - 47, The current useV2Fetch
auto-detects v2 even when the user explicitly passed --api-version v1; change
useV2Fetch so that if runtime.Str("api-version") is non-empty you respect it
(return true if exactly "v2", false if exactly "v1") and skip all auto-detect
checks; only run the existing detail/doc-format/revision-id/scope checks when
api-version was not explicitly provided (empty) so v2-only flags don't silently
override an explicit v1 selection; reference function useV2Fetch and the
runtime.Str keys "api-version", "detail", "doc-format", "scope" and
runtime.Int("revision-id") when applying this change.
Comment on lines
+38
to
+43
| ### 第四波 — 润色与图表（并行 Agent） | ||
| 8. Spawn Agent 定向改进：（结合 `lark-doc-style.md` 进润） | ||
| - **优先处理第三波识别出的画板需求**：简单图直接 `<whiteboard type="mermaid|plantuml">`，复杂图 spawn Agent 使用 **lark-whiteboard** skill | ||
| - 文字密集章节转为 `<table>`/`<grid>`/`<callout>` | ||
| - 主要章节间补充 `<hr/>` | ||
| - 本地图片使用 `docs +media-insert` 插入 |
There was a problem hiding this comment.
Fix the refinement-stage typo.
Line 39 says 进润; this appears to mean 润色.
Proposed text fix
-8. Spawn Agent 定向改进：（结合 `lark-doc-style.md` 进润）
+8. Spawn Agent 定向改进：（结合 `lark-doc-style.md` 润色）📝 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
| ### 第四波 — 润色与图表（并行 Agent） | |
| 8. Spawn Agent 定向改进：（结合 `lark-doc-style.md` 进润） | |
| - **优先处理第三波识别出的画板需求**：简单图直接 `<whiteboard type="mermaid|plantuml">`，复杂图 spawn Agent 使用 **lark-whiteboard** skill | |
| - 文字密集章节转为 `<table>`/`<grid>`/`<callout>` | |
| - 主要章节间补充 `<hr/>` | |
| - 本地图片使用 `docs +media-insert` 插入 | |
| ### 第四波 — 润色与图表（并行 Agent） | |
| 8. Spawn Agent 定向改进：（结合 `lark-doc-style.md` 润色） | |
| - **优先处理第三波识别出的画板需求**：简单图直接 `<whiteboard type="mermaid|plantuml">`，复杂图 spawn Agent 使用 **lark-whiteboard** skill | |
| - 文字密集章节转为 `<table>`/`<grid>`/`<callout>` | |
| - 主要章节间补充 `<hr/>` | |
| - 本地图片使用 `docs +media-insert` 插入 |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/lark-doc/references/style/lark-doc-create-workflow.md` around lines 38
- 43, Replace the typo "进润" with "润色" in the heading/line that reads "Spawn
Agent 定向改进：（结合 `lark-doc-style.md` 进润）" so it correctly reads "Spawn Agent
定向改进：（结合 `lark-doc-style.md` 润色）"; ensure the change occurs in the "第四波 —
润色与图表（并行 Agent）" section and update any other occurrences of "进润" in that
markdown to maintain consistency.
Comment on lines
+21
to
+26
| 1. **选择读取范围**（节省上下文的关键）： | ||
| - 用户只改某一节 / 文档较大 → 先 `--scope outline --max-depth 2` 拿目录，再 `--scope section --start-block-id <目标标题id> --detail with-ids` 精读该节（`section` 会自动展开到下一个同级/更高级标题前，不用手动算结束 block id） | ||
| - 需要精确跨节区间 → `--scope range --start-block-id xxx --end-block-id yyy`（或 `--end-block-id -1` 读到末尾） | ||
| - 用户只给了模糊关键词 → `--scope keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids` | ||
| - 用户明确要改整篇 → `docs +fetch --api-version v2 --detail with-ids` | ||
| - 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) "意图引导：选择正确的 --scope" |
There was a problem hiding this comment.
Add --api-version v2 to all scoped fetch examples.
--scope section/range/keyword and --detail with-ids are v2 fetch guidance in this PR. Lines 22-24 and Line 48 can accidentally route agents to the v1 path.
Proposed fix
- - 用户只改某一节 / 文档较大 → 先 `--scope outline --max-depth 2` 拿目录，再 `--scope section --start-block-id <目标标题id> --detail with-ids` 精读该节（`section` 会自动展开到下一个同级/更高级标题前，不用手动算结束 block id）
- - 需要精确跨节区间 → `--scope range --start-block-id xxx --end-block-id yyy`（或 `--end-block-id -1` 读到末尾）
- - 用户只给了模糊关键词 → `--scope keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids`
+ - 用户只改某一节 / 文档较大 → 先 `docs +fetch --api-version v2 --scope outline --max-depth 2` 拿目录，再 `docs +fetch --api-version v2 --scope section --start-block-id <目标标题id> --detail with-ids` 精读该节（`section` 会自动展开到下一个同级/更高级标题前，不用手动算结束 block id）
+ - 需要精确跨节区间 → `docs +fetch --api-version v2 --scope range --start-block-id xxx --end-block-id yyy`（或 `--end-block-id -1` 读到末尾）
+ - 用户只给了模糊关键词 → `docs +fetch --api-version v2 --scope keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids`-**上下文节省提示**：Agent 如需在自己负责的章节内重新读取内容，优先用 `docs +fetch --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉自己的章节，不要重复拉全文。
+**上下文节省提示**：Agent 如需在自己负责的章节内重新读取内容，优先用 `docs +fetch --api-version v2 --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `docs +fetch --api-version v2 --scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉自己的章节，不要重复拉全文。Also applies to: 48-48
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/lark-doc/references/style/lark-doc-update-workflow.md` around lines 21
- 26, Update the scoped fetch examples to explicitly use v2 by adding the flag
`--api-version v2` to each of the `--scope` examples (the `--scope outline`,
`--scope section --start-block-id <目标标题id> --detail with-ids`, `--scope range
--start-block-id xxx --end-block-id yyy`, and `--scope keyword --keyword xxx
--context-before 1 --context-after 1 --detail with-ids` usages) so they won't
fall back to v1; also add `--api-version v2` to the other scoped example
referenced on the later line (the one noted at Line 48) to ensure all scoped
fetch guidance consistently targets v2.
wittam-01
reviewed
Apr 23, 2026
| 7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。记录需要插图的章节及推荐的画板类型 | ||
|
|
||
| ### 第四波 — 润色与图表（并行 Agent） | ||
| 8. Spawn Agent 定向改进：（结合 `lark-doc-style.md` 进润） |
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (3)
shortcuts/doc/docs_fetch.go (2)
101-111:⚠️ Potential issue | 🟡 MinorSend the pagination hint to stderr.
The “more content available” message is a hint, not fetched document content, so writing it through the pretty-output writer pollutes stdout consumers. As per coding guidelines, Program output (JSON envelopes) must go to stdout; progress, warnings, and hints must go to stderr.
stderr fix
if md, ok := result["markdown"].(string); ok { fmt.Fprintln(w, md) } if hasMore, ok := result["has_more"].(bool); ok && hasMore { - fmt.Fprintln(w, "\n--- more content available, use --offset and --limit to paginate ---") + fmt.Fprintln(runtime.IO().ErrOut, "--- more content available, use --offset and --limit to paginate ---") } })🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_fetch.go` around lines 101 - 111, The pagination hint is being written to the pretty-output writer inside runtime.OutFormat (so it goes to stdout); change the hint emission to write to stderr instead by calling fmt.Fprintln(os.Stderr, "...") (or using the existing logger to stderr) only for the has_more branch in the anonymous func, leaving the title and markdown writes to the provided io.Writer unchanged; update the hasMore branch where it currently calls fmt.Fprintln(w, "\n--- more content available, use --offset and --limit to paginate ---") to write to os.Stderr.
32-41:⚠️ Potential issue | 🟡 MinorDon’t let v2-only flags override explicit
--api-version v1.
--api-version v1 --detail with-idsstill routes to v2. Treat an explicitly changedapi-versionas authoritative and only auto-detect v2 when it was omitted.Routing fix
func useV2Fetch(runtime *common.RuntimeContext) bool { + if runtime.Changed("api-version") { + return runtime.Str("api-version") == "v2" + } if runtime.Str("api-version") == "v2" { return true }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_fetch.go` around lines 32 - 41, The current useV2Fetch always returns true if api-version == "v2" but still treats v2-only flags as authoritative even when the user explicitly changed --api-version to v1; modify useV2Fetch so that if runtime.Changed("api-version") is true it returns runtime.Str("api-version") == "v2" (i.e., treat an explicit api-version as authoritative), otherwise keep the existing auto-detection by checking the v2-only flags (the loop that calls runtime.Changed on "detail","doc-format",...,"max-depth"); update the function logic around runtime.Changed and runtime.Str calls accordingly.shortcuts/doc/docs_update_v2.go (1)
55-58:⚠️ Potential issue | 🟡 MinorRequire replacement content for
str_replace.
buildUpdateBodyonly includescontentwhen non-empty, sostr_replacecan currently send a pattern without replacement text. Add the same required-content validation used by insert/replace operations.Validation fix
case "str_replace": if pattern == "" { return common.FlagErrorf("--command str_replace requires --pattern") } + if content == "" { + return common.FlagErrorf("--command str_replace requires --content") + }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_update_v2.go` around lines 55 - 58, The "str_replace" branch in buildUpdateBody currently only validates pattern but not replacement content; add the same non-empty content validation used by the insert/replace commands by checking content == "" in the "str_replace" case and return common.FlagErrorf("--command str_replace requires --content") so the function refuses to proceed when no replacement text is provided.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@shortcuts/common/runner.go`:
- Around line 651-654: The code calls shortcut.PostMount after
parent.AddCommand, but the lifecycle in shortcuts/common/types.go documents
PostMount as running before the command is added; either move the call to
PostMount so it executes before parent.AddCommand(cmd) (i.e., invoke
shortcut.PostMount(cmd) if non-nil, then call parent.AddCommand(cmd)), or update
the lifecycle comment in shortcuts/common/types.go to reflect the actual
ordering; adjust any related tests or callers of PostMount to match the chosen
contract.
In `@shortcuts/doc/docs_update.go`:
- Around line 47-58: The function useV2Update currently treats
runtime.Str("api-version") == "v2" as authoritative even when the user
explicitly set --api-version v1; update useV2Update to first check
runtime.Changed("api-version") and if changed return true only when
runtime.Str("api-version") == "v2" and return false when it's "v1", otherwise
(when api-version was not supplied) fall back to the existing auto-detection
using runtime.Str("command"), "content", "pattern", "block-id", and
"src-block-ids"; this ensures explicit --api-version selection (use of Changed)
overrides auto-detection.
---
Duplicate comments:
In `@shortcuts/doc/docs_fetch.go`:
- Around line 101-111: The pagination hint is being written to the pretty-output
writer inside runtime.OutFormat (so it goes to stdout); change the hint emission
to write to stderr instead by calling fmt.Fprintln(os.Stderr, "...") (or using
the existing logger to stderr) only for the has_more branch in the anonymous
func, leaving the title and markdown writes to the provided io.Writer unchanged;
update the hasMore branch where it currently calls fmt.Fprintln(w, "\n--- more
content available, use --offset and --limit to paginate ---") to write to
os.Stderr.
- Around line 32-41: The current useV2Fetch always returns true if api-version
== "v2" but still treats v2-only flags as authoritative even when the user
explicitly changed --api-version to v1; modify useV2Fetch so that if
runtime.Changed("api-version") is true it returns runtime.Str("api-version") ==
"v2" (i.e., treat an explicit api-version as authoritative), otherwise keep the
existing auto-detection by checking the v2-only flags (the loop that calls
runtime.Changed on "detail","doc-format",...,"max-depth"); update the function
logic around runtime.Changed and runtime.Str calls accordingly.
In `@shortcuts/doc/docs_update_v2.go`:
- Around line 55-58: The "str_replace" branch in buildUpdateBody currently only
validates pattern but not replacement content; add the same non-empty content
validation used by the insert/replace commands by checking content == "" in the
"str_replace" case and return common.FlagErrorf("--command str_replace requires
--content") so the function refuses to proceed when no replacement text is
provided.
🪄 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: 925452df-417c-4c51-9169-998c9f032a7f
📒 Files selected for processing (9)
README.mdREADME.zh.mdshortcuts/common/runner.goshortcuts/doc/docs_fetch.goshortcuts/doc/docs_update.goshortcuts/doc/docs_update_v2.goskills/lark-doc/references/lark-doc-media-insert.mdskills/lark-drive/references/lark-drive-add-comment.mdskills/lark-whiteboard/SKILL.md
✅ Files skipped from review due to trivial changes (3)
- README.md
- skills/lark-doc/references/lark-doc-media-insert.md
- skills/lark-drive/references/lark-drive-add-comment.md
🚧 Files skipped from review as they are similar to previous changes (1)
- README.zh.md
Comment on lines
+20
to
+21
| {Name: "offset", Desc: "pagination offset", Hidden: true}, | ||
| {Name: "limit", Desc: "pagination limit", Hidden: true}, |
There was a problem hiding this comment.
Reject invalid pagination values instead of silently converting them to zero.
strconv.Atoi errors are ignored, so --offset abc or --limit abc becomes 0 and fetches the wrong page. Register these as int flags and only include them when explicitly changed.
Pagination parsing fix
func v1FetchFlags() []common.Flag {
return []common.Flag{
- {Name: "offset", Desc: "pagination offset", Hidden: true},
- {Name: "limit", Desc: "pagination limit", Hidden: true},
+ {Name: "offset", Desc: "pagination offset", Hidden: true, Type: "int", Default: "0"},
+ {Name: "limit", Desc: "pagination limit", Hidden: true, Type: "int", Default: "0"},
}
}
@@
- if v := runtime.Str("offset"); v != "" {
- n, _ := strconv.Atoi(v)
- args["offset"] = n
+ if runtime.Changed("offset") {
+ args["offset"] = runtime.Int("offset")
}
- if v := runtime.Str("limit"); v != "" {
- n, _ := strconv.Atoi(v)
- args["limit"] = n
+ if runtime.Changed("limit") {
+ args["limit"] = runtime.Int("limit")
}Also remove the now-unused strconv import.
Also applies to: 120-126
Comment on lines
+47
to
+58
| // useV2Update returns true when the v2 (OpenAPI) update path should be used. | ||
| // Explicit --api-version v2 takes priority; otherwise auto-detect by v2-only flags. | ||
| func useV2Update(runtime *common.RuntimeContext) bool { | ||
| if runtime.Str("api-version") == "v2" { | ||
| return true | ||
| } | ||
| return runtime.Str("command") != "" || | ||
| runtime.Str("content") != "" || | ||
| runtime.Str("pattern") != "" || | ||
| runtime.Str("block-id") != "" || | ||
| runtime.Str("src-block-ids") != "" | ||
| } |
There was a problem hiding this comment.
Respect explicit --api-version v1 before auto-detecting v2.
--api-version v1 --command append currently routes to v2 because the v2 flag check runs even when the user explicitly selected v1. Use Changed("api-version") to make explicit version selection authoritative, then auto-detect only when omitted.
Routing fix
func useV2Update(runtime *common.RuntimeContext) bool {
+ if runtime.Changed("api-version") {
+ return runtime.Str("api-version") == "v2"
+ }
if runtime.Str("api-version") == "v2" {
return true
}
- return runtime.Str("command") != "" ||
- runtime.Str("content") != "" ||
- runtime.Str("pattern") != "" ||
- runtime.Str("block-id") != "" ||
- runtime.Str("src-block-ids") != ""
+ for _, name := range []string{"command", "content", "pattern", "block-id", "src-block-ids", "doc-format", "revision-id"} {
+ if runtime.Changed(name) {
+ return true
+ }
+ }
+ return false
}📝 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
| // useV2Update returns true when the v2 (OpenAPI) update path should be used. | |
| // Explicit --api-version v2 takes priority; otherwise auto-detect by v2-only flags. | |
| func useV2Update(runtime *common.RuntimeContext) bool { | |
| if runtime.Str("api-version") == "v2" { | |
| return true | |
| } | |
| return runtime.Str("command") != "" || | |
| runtime.Str("content") != "" || | |
| runtime.Str("pattern") != "" || | |
| runtime.Str("block-id") != "" || | |
| runtime.Str("src-block-ids") != "" | |
| } | |
| // useV2Update returns true when the v2 (OpenAPI) update path should be used. | |
| // Explicit --api-version v2 takes priority; otherwise auto-detect by v2-only flags. | |
| func useV2Update(runtime *common.RuntimeContext) bool { | |
| if runtime.Changed("api-version") { | |
| return runtime.Str("api-version") == "v2" | |
| } | |
| if runtime.Str("api-version") == "v2" { | |
| return true | |
| } | |
| for _, name := range []string{"command", "content", "pattern", "block-id", "src-block-ids", "doc-format", "revision-id"} { | |
| if runtime.Changed(name) { | |
| return true | |
| } | |
| } | |
| return false | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@shortcuts/doc/docs_update.go` around lines 47 - 58, The function useV2Update
currently treats runtime.Str("api-version") == "v2" as authoritative even when
the user explicitly set --api-version v1; update useV2Update to first check
runtime.Changed("api-version") and if changed return true only when
runtime.Str("api-version") == "v2" and return false when it's "v1", otherwise
(when api-version was not supplied) fall back to the existing auto-detection
using runtime.Str("command"), "content", "pattern", "block-id", and
"src-block-ids"; this ensures explicit --api-version selection (use of Changed)
overrides auto-detection.
SunPeiYang996
force-pushed
the
sun/online
branch
from
3e50f14 to
2d54d00
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (9)
skills/lark-doc/references/lark-doc-md.md (1)
7-7:⚠️ Potential issue | 🟡 MinorFix mismatched bold markers in the warning sentence.
Line 7 has nested
**that break intended emphasis and inline code rendering flow.Proposed fix
-> **⚠️ 当文本中包含以下字符且**不想**触发 Markdown 语法时，需用 `\` 前缀转义。转义分为**无条件转义**（行内任意位置生效）和**位置敏感转义**（仅特定位置才需要）两类。 +> **⚠️ 当文本中包含以下字符且不想触发 Markdown 语法时**，需用 `\` 前缀转义。转义分为**无条件转义**（行内任意位置生效）和**位置敏感转义**（仅特定位置才需要）两类。🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-md.md` at line 7, The warning sentence contains mismatched bold markers around the phrase starting with "⚠️ 当文本中包含以下字符且" which breaks emphasis and inline code rendering; update that sentence so the ** bold markers open and close correctly (e.g., wrap the intended phrase fully with a matching pair of ** and keep the inline code backticks `\` outside or inside as intended) — edit the line that begins "⚠️ 当文本中包含以下字符且" to remove the nested/misaligned ** and ensure proper pairing so emphasis and inline code render correctly.skills/lark-doc/references/lark-doc-fetch.md (1)
34-36:⚠️ Potential issue | 🟡 MinorAdd blank lines before the
--detailand--scopetables.Line 35 and Line 45 start table blocks without a separating blank line from preceding text, which triggers MD058 in linted docs.
Proposed fix
## 选 `--detail`（每块详细度） + | 意图 | `--detail` | 说明 | |------|-----------|------| @@ `--scope` 和 `--detail` 正交可组合。**省略 `--scope` 即读整篇；获取一小节时优先用局部读取。** + | 模式 | 何时用 | 关键参数 | 行为要点 | |-|-|-|-|Also applies to: 44-46
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-fetch.md` around lines 34 - 36, The markdown has tables starting immediately after text which triggers MD058; insert a blank line before the `--detail` table and before the `--scope` table so each table block is separated from preceding text — locate the headings/sections titled "## 选 `--detail`（每块详细度）" and the similar `--scope` section and add one empty line above the `| 意图 | ` table rows to fix the lint error.skills/lark-doc/references/lark-doc-update.md (2)
45-46:⚠️ Potential issue | 🟡 MinorAlign
block_move_afterparameter contract with its own example text.Line 45-Line 46 says
--contentcan be used, but Line 155 says moves use--src-block-idswithout content. Also Line 160’s--block-idsample is invalid and should be a real anchor id or-1.Proposed fix
-| `block_move_after` | 移动已有 block 到指定位置 | `--block-id` + (`--content` 或 `--src-block-ids`) | +| `block_move_after` | 移动已有 block 到指定位置 | `--block-id` `--src-block-ids` | @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_move_after \ - --block-id "-1表示末尾，page_id表示开头，blk" \ + --block-id "-1" \ --src-block-ids "block_a,block_b"Also applies to: 155-161
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-update.md` around lines 45 - 46, The table entry for block_move_after is inconsistent with the examples: update the parameter contract to list `--block-id` + `--src-block-ids` (remove `--content`) and then adjust the examples under the block_move_after section to use `--src-block-ids` for moved blocks (no content), and replace the invalid `--block-id` sample with a valid anchor id or `-1`; ensure references to `block_move_after`, `--block-id`, `--content`, and `--src-block-ids` are consistent across the table and the examples (including the examples around the described section).
18-18:⚠️ Potential issue | 🟡 MinorUse the v2 flag in the prerequisite fetch command.
Line 18 should include
--api-version v2to match the rest of this v2 update guide.Proposed fix
-> **Markdown 局限 & block ID 前提：** Markdown 不携带 block ID，也无样式（颜色、对齐、callout 等）。需要按 block ID 定位（`block_*` 指令的 `--block-id`）时，先 `docs +fetch --detail with-ids` **配合 `--scope`（`outline` / `range` / `keyword` / `section`）局部获取**目标段落，不要全量 fetch。拿到 block ID 后 `--content` 仍可用 Markdown，只是写入内容不带样式。 +> **Markdown 局限 & block ID 前提：** Markdown 不携带 block ID，也无样式（颜色、对齐、callout 等）。需要按 block ID 定位（`block_*` 指令的 `--block-id`）时，先 `docs +fetch --api-version v2 --detail with-ids` **配合 `--scope`（`outline` / `range` / `keyword` / `section`）局部获取**目标段落，不要全量 fetch。拿到 block ID 后 `--content` 仍可用 Markdown，只是写入内容不带样式。🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-update.md` at line 18, Update the prerequisite fetch command shown in the sentence mentioning "docs +fetch --detail with-ids" to include the v2 flag by appending --api-version v2 so the command matches the rest of the v2 update guide; specifically modify the fragment that describes using "docs +fetch --detail with-ids" (and its recommended --scope usage) to read with the --api-version v2 flag included.skills/lark-doc/references/lark-doc-create.md (1)
66-68:⚠️ Potential issue | 🟡 MinorFix the table delimiter row.
Line 67 uses
--for the middle column separator, which can break table rendering/linting.Proposed fix
| 参数 | 必填 | 说明 | -| ------------------- | -- |---------------------------------------------| +|---------------------|------|---------------------------------------------| | `--api-version` | 是 | 固定传 `v2` |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-create.md` around lines 66 - 68, The Markdown table delimiter row under the header currently uses `--` for the middle column which can break rendering; update the delimiter row so each column uses at least three dashes (e.g. change the `--` for the middle column to `---`) so the table header and the `--api-version` row render correctly; locate the table containing the `--api-version` header in lark-doc-create.md and replace the delimiter cells with `---` for all columns.skill-template/domains/drive.md (1)
115-115:⚠️ Potential issue | 🟡 MinorKeep the block-id fetch guidance explicitly on v2.
Line 115 should include
--api-version v2;--detail with-idsguidance here is tied to the v2 docs flow.Proposed fix
-- 局部评论：传 `--block-id` 时启用；仅支持 `docx`，以及最终解析为 `docx` 的 wiki URL。block ID 可通过 `docs +fetch --detail with-ids` 获取。 +- 局部评论：传 `--block-id` 时启用；仅支持 `docx`，以及最终解析为 `docx` 的 wiki URL。block ID 可通过 `docs +fetch --api-version v2 --detail with-ids` 获取。🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skill-template/domains/drive.md` at line 115, Update the guidance sentence that mentions passing `--block-id` and the `--detail with-ids` fetch to explicitly include `--api-version v2`; locate the sentence referencing `--block-id` and `docs +fetch --detail with-ids` and append or insert `--api-version v2` so the instruction reads that the `--block-id` flow and the `--detail with-ids` guidance are tied to the v2 docs flow.skills/lark-doc/references/lark-doc-xml.md (1)
32-33:⚠️ Potential issue | 🟡 Minor转义表格单元格中的管道符（Line 32-33）
OpenLink|DuplicatePage|FollowPage和true|false会被当成列分隔符，导致表格列错位。Proposed fix
-| `<button>` | 操作按钮 | `background-color`,src,必须包含 `action=OpenLink|DuplicatePage|FollowPage` | -| `<time>` | 提醒 | `必包含 expire-time、notify-time=毫秒时间戳、should-notify=true|false` | +| `<button>` | 操作按钮 | `background-color`、`src`，必须包含 `action=OpenLink\|DuplicatePage\|FollowPage` | +| `<time>` | 提醒 | 必包含 `expire-time`、`notify-time`（毫秒时间戳）、`should-notify=true\|false` |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-xml.md` around lines 32 - 33, Escape the pipe characters inside the table cell contents so Markdown doesn't treat them as column separators: update the `<button>` row to replace `OpenLink|DuplicatePage|FollowPage` with an escaped form (e.g., `OpenLink \| DuplicatePage \| FollowPage`) and update the `<time>` row to replace `true|false` with `true \| false`; modify the cell text for the `<button>` and `<time>` rows accordingly while preserving the original wording and backticks for code formatting.skills/lark-doc/references/style/lark-doc-create-workflow.md (1)
39-39:⚠️ Potential issue | 🟡 Minor修正文案错别字（Line 39）
进润应为润色，当前表述会影响指令可读性。Proposed fix
-8. Spawn Agent 定向改进：（结合 `lark-doc-style.md` 进润） +8. Spawn Agent 定向改进：（结合 `lark-doc-style.md` 润色）🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/style/lark-doc-create-workflow.md` at line 39, Replace the typo "进润" with "润色" in the phrase "Spawn Agent 定向改进：（结合 `lark-doc-style.md` 进润）" so it reads "Spawn Agent 定向改进：（结合 `lark-doc-style.md` 润色）"; update the markdown content in lark-doc-create-workflow.md accordingly to correct the copy.shortcuts/doc/docs_update.go (1)
47-58:⚠️ Potential issue | 🟡 MinorRespect explicit
--api-version v1before v2 auto-detection.This is still routed to v2 for cases like
docs +update --api-version v1 --command append .... CheckChanged("api-version")first, and only auto-detect v2 flags when the version flag was omitted.Routing fix
func useV2Update(runtime *common.RuntimeContext) bool { - if runtime.Str("api-version") == "v2" { - return true + if runtime.Changed("api-version") { + return runtime.Str("api-version") == "v2" } - return runtime.Str("command") != "" || - runtime.Str("content") != "" || - runtime.Str("pattern") != "" || - runtime.Str("block-id") != "" || - runtime.Str("src-block-ids") != "" + for _, name := range []string{"command", "content", "pattern", "block-id", "src-block-ids", "doc-format", "revision-id"} { + if runtime.Changed(name) { + return true + } + } + return false }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_update.go` around lines 47 - 58, The function useV2Update currently auto-detects v2 flags even when the user explicitly passed --api-version v1; update useV2Update (which takes *common.RuntimeContext) to first check runtime.Changed("api-version") and return false if runtime.Str("api-version") == "v1", return true if it's "v2", and only when the api-version flag was not changed fall back to the existing auto-detect logic that inspects runtime.Str("command"), runtime.Str("content"), runtime.Str("pattern"), runtime.Str("block-id"), and runtime.Str("src-block-ids").
🧹 Nitpick comments (4)
shortcuts/doc/docs_update_v2.go (2)
150-152:revision_idguard usesv != 0, which conflates "unset" with "revision 0".The flag defaults to
-1, so the condition currently fires for both the default and any user-supplied non-zero value. However, if revision0is ever a valid base revision on the API side, the user cannot request it (the field gets dropped). Preferruntime.Changed("revision-id")or unconditionally send the value so intent is unambiguous.Suggested fix
- if v := runtime.Int("revision-id"); v != 0 { - body["revision_id"] = v - } + if runtime.Changed("revision-id") { + body["revision_id"] = runtime.Int("revision-id") + }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_update_v2.go` around lines 150 - 152, The guard using runtime.Int("revision-id") with v != 0 conflates unset/default with a valid revision 0; update the code that sets body["revision_id"] (using runtime.Int("revision-id") and body map) to either (1) check runtime.Changed("revision-id") before assigning so revision 0 is preserved when explicitly set, or (2) always set body["revision_id"] to the integer value returned by runtime.Int("revision-id") (removing the v != 0 check) to make intent explicit.
13-39: DRY: derive command list and map from a single source.
validCommandsV2andvalidCommandsV2Keys()list the same eight commands, plus the invalid-command error message at line 50 repeats them a third time. Any future change risks drifting the three sources. Keep the ordered slice as the source of truth and derive the lookup map (and the error message) from it.Suggested refactor
-var validCommandsV2 = map[string]bool{ - "str_replace": true, - "block_delete": true, - "block_insert_after": true, - "block_copy_insert_after": true, - "block_replace": true, - "block_move_after": true, - "overwrite": true, - "append": true, -} +var validCommandsV2List = []string{ + "str_replace", "block_delete", "block_insert_after", "block_copy_insert_after", + "block_replace", "block_move_after", "overwrite", "append", +} + +var validCommandsV2 = func() map[string]bool { + m := make(map[string]bool, len(validCommandsV2List)) + for _, c := range validCommandsV2List { + m[c] = true + } + return m +}() @@ - {Name: "command", Desc: "operation: str_replace | block_delete | block_insert_after | block_copy_insert_after | block_replace | block_move_after | overwrite | append", Hidden: true, Enum: validCommandsV2Keys()}, + {Name: "command", Desc: "operation: " + strings.Join(validCommandsV2List, " | "), Hidden: true, Enum: validCommandsV2List}, @@ -func validCommandsV2Keys() []string { - return []string{"str_replace", "block_delete", "block_insert_after", "block_copy_insert_after", "block_replace", "block_move_after", "overwrite", "append"} -}And similarly build the error message at line 50 from
strings.Join(validCommandsV2List, " | ").🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_update_v2.go` around lines 13 - 39, Replace the duplicated command definitions with a single ordered slice (e.g., rename validCommandsV2 to validCommandsV2List) and derive both the lookup map and the keys/error text from it: keep a single source slice (validCommandsV2List), implement validCommandsV2Keys() to return that slice, and build the map (previously validCommandsV2) programmatically (e.g., in an init or helper like buildValidCommandsMap) so any code that needs a boolean lookup can use that generated map; also construct the invalid-command error message in the same place by joining validCommandsV2List with " | " (strings.Join(validCommandsV2List, " | ")) and update v2UpdateFlags() to keep using validCommandsV2Keys() for the Enum.shortcuts/common/runner.go (1)
510-527: UseoutputErrOnce.Do(...)inOutRawfor parity withOut.
Out(lines 494–505) captures the first jq error viactx.outputErrOnce.Do(func() { ctx.outputErr = err }), butOutRawuses a plainif ctx.outputErr == nilcheck. They should be consistent so callers get the same "first-error wins" semantics regardless of which writer is in use, and so theoutputErrOncefield doc onRuntimeContextremains accurate.Suggested fix
- if err := output.JqFilterRaw(ctx.IO().Out, env, ctx.JqExpr); err != nil { - fmt.Fprintf(ctx.IO().ErrOut, "error: %v\n", err) - if ctx.outputErr == nil { - ctx.outputErr = err - } - } + if err := output.JqFilterRaw(ctx.IO().Out, env, ctx.JqExpr); err != nil { + fmt.Fprintf(ctx.IO().ErrOut, "error: %v\n", err) + ctx.outputErrOnce.Do(func() { ctx.outputErr = err }) + }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/common/runner.go` around lines 510 - 527, OutRaw currently sets ctx.outputErr using a plain if check, but Out uses ctx.outputErrOnce.Do(...) to ensure only the first jq error is recorded; change OutRaw to mirror Out by replacing the if ctx.outputErr == nil assignment with ctx.outputErrOnce.Do(func() { ctx.outputErr = err }) so the first-error-wins semantics (and the RuntimeContext.outputErrOnce doc) remain correct; update the error-handling block inside OutRaw (the JqFilterRaw error branch) to call outputErrOnce.Do(...) when recording ctx.outputErr.shortcuts/doc/versioned_help.go (1)
21-32: FlagHiddenmutation is a persistent side effect.
VisitAllflipsf.Hiddenon the flag set each time--helpruns; the change sticks on the Cobra flag object for the process lifetime. In the normal CLI flow this is harmless (--helpexits the process), but it makes the command non-idempotent for any embedded / library-style consumer that callscmd.Help()multiple times with different--api-versionvalues (e.g., tests, or if a future caller reuses the command tree). Consider rendering help from a snapshot or restoring originalHiddenvalues afterorigHelpruns.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/versioned_help.go` around lines 21 - 32, The current SetHelpFunc mutates the persistent Flag.Hidden values in VisitAll which makes repeated Help calls non-idempotent; to fix, snapshot each flag's original Hidden state before you change it (inside the SetHelpFunc closure when you call cmd.Flags().VisitAll), then set f.Hidden based on flagVersions as you do, call origHelp(cmd,args), and finally restore each flag's Hidden to its saved value so the Cobra flag objects are not permanently mutated; reference SetHelpFunc, cmd.Flags().VisitAll, flagVersions, and origHelp to locate where to take the snapshot and where to restore the values.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@shortcuts/doc/docs_create.go`:
- Around line 30-37: The routing currently ignores an explicit "--api-version
v1"; update useV2Create to first check runtime.Str("api-version") and return
false if it equals "v1", return true if it equals "v2", and only when
api-version is empty perform the existing auto-detection (checking
runtime.Str("content"), "parent-token", "parent-position"); keep the function
name useV2Create and use runtime.Str(...) calls so the explicit api-version
selection is authoritative and auto-detection runs only when api-version is
omitted.
In `@skills/lark-doc/references/lark-doc-xml.md`:
- Line 113: The header "## 八、完整示例" is using a level-2 heading but should be the
main section; change the markdown heading text in the file from "## 八、完整示例" to a
level-1 heading "# 八、完整示例" so the chapter becomes a top-level section and the
document TOC/hierarchy remains correct; update any adjacent headings if needed
to preserve consistent numbering and nesting.
---
Duplicate comments:
In `@shortcuts/doc/docs_update.go`:
- Around line 47-58: The function useV2Update currently auto-detects v2 flags
even when the user explicitly passed --api-version v1; update useV2Update (which
takes *common.RuntimeContext) to first check runtime.Changed("api-version") and
return false if runtime.Str("api-version") == "v1", return true if it's "v2",
and only when the api-version flag was not changed fall back to the existing
auto-detect logic that inspects runtime.Str("command"), runtime.Str("content"),
runtime.Str("pattern"), runtime.Str("block-id"), and
runtime.Str("src-block-ids").
In `@skill-template/domains/drive.md`:
- Line 115: Update the guidance sentence that mentions passing `--block-id` and
the `--detail with-ids` fetch to explicitly include `--api-version v2`; locate
the sentence referencing `--block-id` and `docs +fetch --detail with-ids` and
append or insert `--api-version v2` so the instruction reads that the
`--block-id` flow and the `--detail with-ids` guidance are tied to the v2 docs
flow.
In `@skills/lark-doc/references/lark-doc-create.md`:
- Around line 66-68: The Markdown table delimiter row under the header currently
uses `--` for the middle column which can break rendering; update the delimiter
row so each column uses at least three dashes (e.g. change the `--` for the
middle column to `---`) so the table header and the `--api-version` row render
correctly; locate the table containing the `--api-version` header in
lark-doc-create.md and replace the delimiter cells with `---` for all columns.
In `@skills/lark-doc/references/lark-doc-fetch.md`:
- Around line 34-36: The markdown has tables starting immediately after text
which triggers MD058; insert a blank line before the `--detail` table and before
the `--scope` table so each table block is separated from preceding text —
locate the headings/sections titled "## 选 `--detail`（每块详细度）" and the similar
`--scope` section and add one empty line above the `| 意图 | ` table rows to fix
the lint error.
In `@skills/lark-doc/references/lark-doc-md.md`:
- Line 7: The warning sentence contains mismatched bold markers around the
phrase starting with "⚠️ 当文本中包含以下字符且" which breaks emphasis and inline code
rendering; update that sentence so the ** bold markers open and close correctly
(e.g., wrap the intended phrase fully with a matching pair of ** and keep the
inline code backticks `\` outside or inside as intended) — edit the line that
begins "⚠️ 当文本中包含以下字符且" to remove the nested/misaligned ** and ensure proper
pairing so emphasis and inline code render correctly.
In `@skills/lark-doc/references/lark-doc-update.md`:
- Around line 45-46: The table entry for block_move_after is inconsistent with
the examples: update the parameter contract to list `--block-id` +
`--src-block-ids` (remove `--content`) and then adjust the examples under the
block_move_after section to use `--src-block-ids` for moved blocks (no content),
and replace the invalid `--block-id` sample with a valid anchor id or `-1`;
ensure references to `block_move_after`, `--block-id`, `--content`, and
`--src-block-ids` are consistent across the table and the examples (including
the examples around the described section).
- Line 18: Update the prerequisite fetch command shown in the sentence
mentioning "docs +fetch --detail with-ids" to include the v2 flag by appending
--api-version v2 so the command matches the rest of the v2 update guide;
specifically modify the fragment that describes using "docs +fetch --detail
with-ids" (and its recommended --scope usage) to read with the --api-version v2
flag included.
In `@skills/lark-doc/references/lark-doc-xml.md`:
- Around line 32-33: Escape the pipe characters inside the table cell contents
so Markdown doesn't treat them as column separators: update the `<button>` row
to replace `OpenLink|DuplicatePage|FollowPage` with an escaped form (e.g.,
`OpenLink \| DuplicatePage \| FollowPage`) and update the `<time>` row to
replace `true|false` with `true \| false`; modify the cell text for the
`<button>` and `<time>` rows accordingly while preserving the original wording
and backticks for code formatting.
In `@skills/lark-doc/references/style/lark-doc-create-workflow.md`:
- Line 39: Replace the typo "进润" with "润色" in the phrase "Spawn Agent 定向改进：（结合
`lark-doc-style.md` 进润）" so it reads "Spawn Agent 定向改进：（结合 `lark-doc-style.md`
润色）"; update the markdown content in lark-doc-create-workflow.md accordingly to
correct the copy.
---
Nitpick comments:
In `@shortcuts/common/runner.go`:
- Around line 510-527: OutRaw currently sets ctx.outputErr using a plain if
check, but Out uses ctx.outputErrOnce.Do(...) to ensure only the first jq error
is recorded; change OutRaw to mirror Out by replacing the if ctx.outputErr ==
nil assignment with ctx.outputErrOnce.Do(func() { ctx.outputErr = err }) so the
first-error-wins semantics (and the RuntimeContext.outputErrOnce doc) remain
correct; update the error-handling block inside OutRaw (the JqFilterRaw error
branch) to call outputErrOnce.Do(...) when recording ctx.outputErr.
In `@shortcuts/doc/docs_update_v2.go`:
- Around line 150-152: The guard using runtime.Int("revision-id") with v != 0
conflates unset/default with a valid revision 0; update the code that sets
body["revision_id"] (using runtime.Int("revision-id") and body map) to either
(1) check runtime.Changed("revision-id") before assigning so revision 0 is
preserved when explicitly set, or (2) always set body["revision_id"] to the
integer value returned by runtime.Int("revision-id") (removing the v != 0 check)
to make intent explicit.
- Around line 13-39: Replace the duplicated command definitions with a single
ordered slice (e.g., rename validCommandsV2 to validCommandsV2List) and derive
both the lookup map and the keys/error text from it: keep a single source slice
(validCommandsV2List), implement validCommandsV2Keys() to return that slice, and
build the map (previously validCommandsV2) programmatically (e.g., in an init or
helper like buildValidCommandsMap) so any code that needs a boolean lookup can
use that generated map; also construct the invalid-command error message in the
same place by joining validCommandsV2List with " | "
(strings.Join(validCommandsV2List, " | ")) and update v2UpdateFlags() to keep
using validCommandsV2Keys() for the Enum.
In `@shortcuts/doc/versioned_help.go`:
- Around line 21-32: The current SetHelpFunc mutates the persistent Flag.Hidden
values in VisitAll which makes repeated Help calls non-idempotent; to fix,
snapshot each flag's original Hidden state before you change it (inside the
SetHelpFunc closure when you call cmd.Flags().VisitAll), then set f.Hidden based
on flagVersions as you do, call origHelp(cmd,args), and finally restore each
flag's Hidden to its saved value so the Cobra flag objects are not permanently
mutated; reference SetHelpFunc, cmd.Flags().VisitAll, flagVersions, and origHelp
to locate where to take the snapshot and where to restore the values.
🪄 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: b5874c16-ecf1-4fc2-965e-9f688fa6395f
📒 Files selected for processing (33)
README.mdREADME.zh.mdinternal/output/jq.gointernal/output/jq_raw_test.goshortcuts/common/runner.goshortcuts/common/types.goshortcuts/doc/docs_create.goshortcuts/doc/docs_create_test.goshortcuts/doc/docs_create_v2.goshortcuts/doc/docs_fetch.goshortcuts/doc/docs_fetch_v2.goshortcuts/doc/docs_update.goshortcuts/doc/docs_update_test.goshortcuts/doc/docs_update_v2.goshortcuts/doc/helpers.goshortcuts/doc/versioned_help.goskill-template/domains/drive.mdskills/lark-doc/SKILL.mdskills/lark-doc/references/lark-doc-create.mdskills/lark-doc/references/lark-doc-fetch.mdskills/lark-doc/references/lark-doc-md.mdskills/lark-doc/references/lark-doc-media-insert.mdskills/lark-doc/references/lark-doc-update.mdskills/lark-doc/references/lark-doc-xml.mdskills/lark-doc/references/style/lark-doc-create-workflow.mdskills/lark-doc/references/style/lark-doc-style.mdskills/lark-doc/references/style/lark-doc-update-workflow.mdskills/lark-drive/SKILL.mdskills/lark-drive/references/lark-drive-add-comment.mdskills/lark-event/references/lark-event-subscribe.mdskills/lark-vc/SKILL.mdskills/lark-whiteboard/SKILL.mdskills/lark-workflow-meeting-summary/SKILL.md
✅ Files skipped from review due to trivial changes (1)
- skills/lark-vc/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (10)
- README.zh.md
- shortcuts/doc/helpers.go
- skills/lark-event/references/lark-event-subscribe.md
- README.md
- skills/lark-workflow-meeting-summary/SKILL.md
- skills/lark-whiteboard/SKILL.md
- shortcuts/doc/docs_update_test.go
- shortcuts/doc/docs_fetch_v2.go
- skills/lark-doc/references/style/lark-doc-update-workflow.md
- skills/lark-drive/references/lark-drive-add-comment.md
Comment on lines
+30
to
+37
| func useV2Create(runtime *common.RuntimeContext) bool { | ||
| if runtime.Str("api-version") == "v2" { | ||
| return true | ||
| } | ||
| return runtime.Str("content") != "" || | ||
| runtime.Str("parent-token") != "" || | ||
| runtime.Str("parent-position") != "" | ||
| } |
There was a problem hiding this comment.
Respect explicit --api-version v1 before v2 auto-detection.
docs +create --api-version v1 --content ... currently routes to v2 because the v2-only flag check still runs. Make explicit version selection authoritative, then auto-detect only from changed v2-only flags when --api-version is omitted.
Routing fix
func useV2Create(runtime *common.RuntimeContext) bool {
- if runtime.Str("api-version") == "v2" {
- return true
+ if runtime.Changed("api-version") {
+ return runtime.Str("api-version") == "v2"
}
- return runtime.Str("content") != "" ||
- runtime.Str("parent-token") != "" ||
- runtime.Str("parent-position") != ""
+ for _, name := range []string{"content", "doc-format", "parent-token", "parent-position"} {
+ if runtime.Changed(name) {
+ return true
+ }
+ }
+ return false
}📝 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
| func useV2Create(runtime *common.RuntimeContext) bool { | |
| if runtime.Str("api-version") == "v2" { | |
| return true | |
| } | |
| return runtime.Str("content") != "" || | |
| runtime.Str("parent-token") != "" || | |
| runtime.Str("parent-position") != "" | |
| } | |
| func useV2Create(runtime *common.RuntimeContext) bool { | |
| if runtime.Changed("api-version") { | |
| return runtime.Str("api-version") == "v2" | |
| } | |
| for _, name := range []string{"content", "doc-format", "parent-token", "parent-position"} { | |
| if runtime.Changed(name) { | |
| return true | |
| } | |
| } | |
| return false | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@shortcuts/doc/docs_create.go` around lines 30 - 37, The routing currently
ignores an explicit "--api-version v1"; update useV2Create to first check
runtime.Str("api-version") and return false if it equals "v1", return true if it
equals "v2", and only when api-version is empty perform the existing
auto-detection (checking runtime.Str("content"), "parent-token",
"parent-position"); keep the function name useV2Create and use runtime.Str(...)
calls so the explicit api-version selection is authoritative and auto-detection
runs only when api-version is omitted.
63f5b81 to
7db1c22
Compare
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
skills/lark-doc/references/lark-doc-media-insert.md (1)
20-24:⚠️ Potential issue | 🟡 MinorUpdate the URL source rule to include the new direct insert path.
The table still tells agents to download URL images first, but the new example says
docs +updatecan insert network images directly. Align the decision rule so agents do not skip this path.Proposed fix
-| 图片是 URL | 先下载到本地 → `--file`；或用 `drive` 相关命令 | — | +| 图片是 URL | 若目标是在线文档内容，优先用 `docs +update --api-version v2` 写入 `<img href="..."/>`；若必须作为本地上传/云空间文件处理，再下载到本地 → `--file` 或用 `drive` 相关命令 | — |Also applies to: 50-53
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-media-insert.md` around lines 20 - 24, Update the table row for "图片是 URL" to include the new direct-insert path using the "docs +update" command: change the cell text from "先下载到本地 → `--file`；或用 `drive` 相关命令" to something like "可直接用 `docs +update` 插入网络图片，或先下载到本地 → `--file`；或用 `drive` 相关命令", and apply the same wording update to the duplicate occurrence around lines 50-53 so agents know to prefer `docs +update` for URL images; keep the existing `--file <path>`, `--from-clipboard`, and `drive` references intact.
♻️ Duplicate comments (14)
skills/lark-doc/references/lark-doc-md.md (1)
7-7:⚠️ Potential issue | 🟡 MinorFix the broken bold emphasis in the warning callout.
The nested
**不想**closes the outer bold span early and breaks the intended rendering.Proposed fix
-> **⚠️ 当文本中包含以下字符且**不想**触发 Markdown 语法时，需用 `\` 前缀转义。转义分为**无条件转义**（行内任意位置生效）和**位置敏感转义**（仅特定位置才需要）两类。 +> **⚠️ 当文本中包含以下字符且不想触发 Markdown 语法时**，需用 `\` 前缀转义。转义分为**无条件转义**（行内任意位置生效）和**位置敏感转义**（仅特定位置才需要）两类。🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-md.md` at line 7, The warning callout's nested bold (**不想**) prematurely closes the outer bold span; to fix, change the inner emphasis so it doesn't use double asterisks—e.g., replace **不想** with single-asterisk emphasis *不想* or escape the inner asterisks (\\*\\*不想\\*\\*) or use HTML tags like <strong> for the outer and <em> for the inner; update the line containing the nested bold in the callout so the outer bold span remains intact.skill-template/domains/drive.md (1)
115-115:⚠️ Potential issue | 🟡 MinorKeep the template aligned with the v2 fetch command.
Line 115 still omits
--api-version v2for--detail with-ids, while this guidance is v2-specific.Proposed fix
-- 局部评论：传 `--block-id` 时启用；仅支持 `docx`，以及最终解析为 `docx` 的 wiki URL。block ID 可通过 `docs +fetch --detail with-ids` 获取。 +- 局部评论：传 `--block-id` 时启用；仅支持 `docx`，以及最终解析为 `docx` 的 wiki URL。block ID 可通过 `docs +fetch --api-version v2 --detail with-ids` 获取。🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skill-template/domains/drive.md` at line 115, Update the template text that documents the --block-id usage to mention the v2 fetch requirement: modify the sentence that currently reads "局部评论：传 `--block-id` 时启用；仅支持 `docx`，以及最终解析为 `docx` 的 wiki URL。block ID 可通过 `docs +fetch --detail with-ids` 获取。" so it explicitly includes the v2 flag (e.g., reference `docs +fetch --detail with-ids --api-version v2`); ensure the mention of `--detail with-ids` is annotated as v2-specific and keep the rest of the guidance about `--block-id`/`docx` unchanged.shortcuts/doc/versioned_help.go (1)
33-40:⚠️ Potential issue | 🟡 MinorSend the deprecation note to stderr.
This warning currently goes through
cmd.OutOrStdout(), which can mix hint text into stdout output consumed by scripts.Proposed fix
if ver == "v1" { - fmt.Fprintf(cmd.OutOrStdout(), + fmt.Fprintf(cmd.ErrOrStderr(), "\n[NOTE] v1 API is deprecated and will be removed in a future release.\n"+ " Use --api-version v2 for the latest API:\n"+ " %s %s --api-version v2 --help\n"+As per coding guidelines, Program output (JSON envelopes) must go to stdout; progress, warnings, and hints must go to stderr.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/versioned_help.go` around lines 33 - 40, The deprecation note is being written to stdout via cmd.OutOrStdout() which can contaminate machine-readable output; update the write target so the warning goes to stderr when ver == "v1" by using the command's error output (e.g., cmd.ErrOrStderr()) instead of cmd.OutOrStdout(), keeping the same formatted message and parameters (cmd.Parent().Name(), cmd.Name()) so the deprecation/hint text is emitted to stderr.skills/lark-doc/references/lark-doc-update.md (1)
36-45:⚠️ Potential issue | 🟡 MinorCorrect the
block_move_afterrequired flags and example.The quick table still says
block_move_aftercan use--content, while the dedicated section correctly says it uses--src-block-ids. The example also passes explanatory text as the--block-idvalue.Proposed docs correction
-| `block_move_after` | 移动已有 block 到指定位置 | `--block-id` + (`--content` 或 `--src-block-ids`) | +| `block_move_after` | 移动已有 block 到指定位置 | `--block-id` `--src-block-ids` | @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_move_after \ - --block-id "-1表示末尾，page_id表示开头，blk" \ + --block-id "-1" \ --src-block-ids "block_a,block_b"Also applies to: 153-161
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-update.md` around lines 36 - 45, Update the quick-reference table and example for the block_move_after command to match the detailed section: change its required flags to use --block-id and --src-block-ids (remove --content) and fix the example so --block-id is an actual block id (not explanatory text) and --src-block-ids contains the source block ids; ensure both the table row for block_move_after and the corresponding example in the document use the exact flag names (--block-id, --src-block-ids) and valid placeholder values.skills/lark-doc/references/lark-doc-fetch.md (1)
34-46:⚠️ Potential issue | 🟡 MinorAdd blank lines before Markdown tables.
The
--detailand--scopetables are not surrounded by blank lines, matching the markdownlint MD058 warnings.Proposed Markdown lint fix
## 选 `--detail`（每块详细度） + | 意图 | `--detail` | 说明 | |------|-----------|------| @@ `--scope` 和 `--detail` 正交可组合。**省略 `--scope` 即读整篇；获取一小节时优先用局部读取。** + | 模式 | 何时用 | 关键参数 | 行为要点 | |-|-|-|-|🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-fetch.md` around lines 34 - 46, Add a blank line above each Markdown table to satisfy MD058: insert an empty line before the table that starts with "| 意图 | `--detail` | 说明 |" in the "## 选 `--detail`（每块详细度）" section and before the table that starts with "| 模式 | 何时用 | 关键参数 | 行为要点 |" in the "## 选 `--scope`（读取范围）" section so both tables are separated from preceding headings/text.skills/lark-doc/references/lark-doc-xml.md (2)
23-33:⚠️ Potential issue | 🟡 MinorEscape pipes inside table cells.
The
|characters inOpenLink|DuplicatePage|FollowPageandtrue|falseare parsed as column separators, so the table can render with missing or shifted content.Proposed table fix
-| `<button>` | 操作按钮 | `background-color`,src,必须包含 `action=OpenLink|DuplicatePage|FollowPage` | -| `<time>` | 提醒 | `必包含 expire-time、notify-time=毫秒时间戳、should-notify=true|false` | +| `<button>` | 操作按钮 | `background-color`, `src`，必须包含 `action=OpenLink\|DuplicatePage\|FollowPage` | +| `<time>` | 提醒 | 必包含 `expire-time`、`notify-time`（毫秒时间戳）、`should-notify=true\|false` |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-xml.md` around lines 23 - 33, The table's cells for the `<button>` and `<time>` rows contain unescaped pipe characters ("OpenLink|DuplicatePage|FollowPage" and "true|false") which break Markdown table parsing; update those cells in the row for `<button>` and the row for `<time>` to escape the pipe characters (e.g., replace "|" with "\|" or wrap the entire value in code backticks) so they are treated as literal text rather than column separators, ensuring the `<button>` and `<time>` table entries render correctly.
100-113:⚠️ Potential issue | 🟡 MinorKeep the complete example as a top-level section.
八、完整示例is currently nested under七、重要规则, which makes the numbered hierarchy inconsistent.Proposed heading fix
-## 八、完整示例 +# 八、完整示例🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-xml.md` around lines 100 - 113, The heading "八、完整示例" is nested under "七、**重要规则**" causing inconsistent numbering; move the "八、完整示例" heading out to the document root as a top-level sibling of "七、**重要规则**" (ensure its markdown heading level matches "七、**重要规则**"), update any surrounding indentation or block scope so the example is not nested, and verify the heading text "八、完整示例" and its content remain intact.shortcuts/doc/docs_update_v2.go (1)
57-61:⚠️ Potential issue | 🟠 MajorPreserve explicit empty
--contentforstr_replace.
--content ""is documented as deletion, butbuildUpdateBodydrops empty strings, so the request omitscontententirely. Validate that--contentwas provided, while still allowing an explicit empty value, then include the field when the flag is present.Run this read-only check to find the existing
RuntimeContextflag-presence helper before wiring the fix:#!/bin/bash set -euo pipefail # Find RuntimeContext and any existing flag-presence helpers. rg -nP 'type\s+RuntimeContext\b|func\s*\([^)]*\*RuntimeContext[^)]*\)\s*(Changed|FlagChanged|IsSet|HasFlag|WasSet)\b|\.(Changed|FlagChanged|IsSet|HasFlag|WasSet)\s*\(' --type=go -C 3Expected result: identify the project’s existing “flag was explicitly set” API, then use it for both validation and body construction.
Also applies to: 153-155
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_update_v2.go` around lines 57 - 61, The str_replace handling drops explicitly provided empty --content because buildUpdateBody ignores empty strings; fix by using the RuntimeContext flag-presence helper (e.g., RuntimeContext.Changed / FlagChanged / WasSet — discover exact name via the provided rg command) to detect whether --content was provided, validate that the flag was set (not just non-empty), and when present include content in the update body even if it's the empty string; update both the validation branch in the switch for "str_replace" and the buildUpdateBody logic to consult the same RuntimeContext flag-presence helper so the field is included when the flag was explicitly set (also apply the same change for the other occurrence at lines 153-155).skills/lark-doc/references/lark-doc-create.md (1)
66-72:⚠️ Potential issue | 🟡 MinorFix the Markdown table separator.
The second delimiter cell is
--, which can prevent the parameters table from rendering correctly.Proposed table fix
| 参数 | 必填 | 说明 | -| ------------------- | -- |---------------------------------------------| +|---------------------|------|---------------------------------------------| | `--api-version` | 是 | 固定传 `v2` |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-create.md` around lines 66 - 72, The Markdown table's header separator row uses `--` for the second column which can break rendering; update the separator row in skills/lark-doc/references/lark-doc-create.md so each column uses a proper Markdown separator (`---` or at least three dashes) matching the header count — specifically change the middle cell from `--` to `---` so the row becomes `| ------------------- | --- |---------------------------------------------|`, ensuring the `--api-version`, `--content`, `--doc-format`, `--parent-token`, and `--parent-position` parameter columns render correctly.skills/lark-doc/references/style/lark-doc-create-workflow.md (1)
38-43:⚠️ Potential issue | 🟡 MinorFix the refinement-stage typo.
Line 39 says
进润; this appears to mean润色.Proposed text fix
-8. Spawn Agent 定向改进：（结合 `lark-doc-style.md` 进润） +8. Spawn Agent 定向改进：（结合 `lark-doc-style.md` 润色）🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/style/lark-doc-create-workflow.md` around lines 38 - 43, In the "第四波 — 润色与图表（并行 Agent）" section update the typo in the bullet that reads "Spawn Agent 定向改进：（结合 `lark-doc-style.md` 进润）" to use the correct word "润色" (i.e., change "进润" → "润色"); ensure the corrected phrase reads "结合 `lark-doc-style.md` 润色" and scan the nearby bullets (e.g., the lines about `<whiteboard>`/`lark-whiteboard`, `<table>`/`<grid>`/`<callout>`, and `docs +media-insert`) for any similar wording inconsistencies to keep style consistent.shortcuts/doc/docs_fetch.go (3)
107-116:⚠️ Potential issue | 🟡 MinorSend the pagination hint to stderr.
The
--- more content available...line is a hint, not fetched document content, so writing it through the pretty-output writer pollutes stdout consumers.Output stream fix
if md, ok := result["markdown"].(string); ok { fmt.Fprintln(w, md) } if hasMore, ok := result["has_more"].(bool); ok && hasMore { - fmt.Fprintln(w, "\n--- more content available, use --offset and --limit to paginate ---") + fmt.Fprintln(runtime.IO().ErrOut, "\n--- more content available, use --offset and --limit to paginate ---") }As per coding guidelines, Program output (JSON envelopes) must go to stdout; progress, warnings, and hints must go to stderr.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_fetch.go` around lines 107 - 116, The pagination hint is being written to the pretty-output writer inside runtime.OutFormat (see runtime.OutFormat and the anonymous func using w) which sends it to stdout; change the code so the hint triggered by result["has_more"] is written to stderr instead (e.g., use fmt.Fprintln(os.Stderr, "...") or the project's stderr logger) rather than fmt.Fprintln(w, ...). Keep title and markdown output to the existing writer w, but emit the "--- more content available ---" message directly to stderr when has_more is true.
32-40:⚠️ Potential issue | 🟡 MinorRespect explicit
--api-version v1before auto-detecting v2.
docs +fetch --api-version v1 --detail with-idsstill routes to v2 because v2-only flag detection runs after reading the value, not after checking whether the version flag was explicitly set.Routing fix
func useV2Fetch(runtime *common.RuntimeContext) bool { + if runtime.Changed("api-version") { + return runtime.Str("api-version") == "v2" + } if runtime.Str("api-version") == "v2" { return true }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_fetch.go` around lines 32 - 40, The routing logic in useV2Fetch incorrectly auto-detects v2 even when the user explicitly passed --api-version v1; update useV2Fetch to first check if runtime.Changed("api-version") and if so return runtime.Str("api-version") == "v2" (so explicit v1 forces v1), otherwise fall through to the existing v2-only flag detection loop; reference the useV2Fetch function and the runtime.Changed / runtime.Str calls to locate where to add this explicit-version check.
10-10:⚠️ Potential issue | 🟡 MinorReject invalid pagination values instead of converting them to zero.
strconv.Atoierrors are ignored, so--offset abcor--limit abcbecomes0and fetches the wrong page. Register these as int flags and only include them when explicitly changed.Pagination parsing fix
import ( "context" "fmt" "io" - "strconv" "github.com/spf13/cobra" @@ func v1FetchFlags() []common.Flag { return []common.Flag{ - {Name: "offset", Desc: "pagination offset", Hidden: true}, - {Name: "limit", Desc: "pagination limit", Hidden: true}, + {Name: "offset", Desc: "pagination offset", Hidden: true, Type: "int", Default: "0"}, + {Name: "limit", Desc: "pagination limit", Hidden: true, Type: "int", Default: "0"}, } } @@ - if v := runtime.Str("offset"); v != "" { - n, _ := strconv.Atoi(v) - args["offset"] = n + if runtime.Changed("offset") { + args["offset"] = runtime.Int("offset") } - if v := runtime.Str("limit"); v != "" { - n, _ := strconv.Atoi(v) - args["limit"] = n + if runtime.Changed("limit") { + args["limit"] = runtime.Int("limit") }Also applies to: 20-21, 126-132
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_fetch.go` at line 10, The code currently reads --offset and --limit as strings and ignores strconv.Atoi errors (silently treating invalid values as 0); change these to typed int flags (register them with the flag/pflag/Cobra int flag API rather than string flags) so parsing is handled by the flag library and invalid values are rejected, and only include offset/limit in the outgoing request when the user explicitly set them (e.g., check the flag's Changed state or compare to a sentinel/unset value); update the parsing code that currently calls strconv.Atoi (referenced by the offset/limit flag variables and the parsing logic around lines referenced) and similarly fix the other occurrences at the other sites (lines 20-21 and 126-132) so no invalid string-to-int conversion silently becomes zero.shortcuts/doc/docs_update.go (1)
49-58:⚠️ Potential issue | 🟡 MinorMake explicit
--api-versionauthoritative.
--api-version v1 --command appendstill routes to v2, while--doc-format markdownor--revision-id 123can route to v1 because auto-detection checks values instead of changed flags and misses those v2-only flags.Routing fix
func useV2Update(runtime *common.RuntimeContext) bool { + if runtime.Changed("api-version") { + return runtime.Str("api-version") == "v2" + } if runtime.Str("api-version") == "v2" { return true } - return runtime.Str("command") != "" || - runtime.Str("content") != "" || - runtime.Str("pattern") != "" || - runtime.Str("block-id") != "" || - runtime.Str("src-block-ids") != "" + for _, name := range []string{"command", "content", "pattern", "block-id", "src-block-ids", "doc-format", "revision-id"} { + if runtime.Changed(name) { + return true + } + } + return false }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_update.go` around lines 49 - 58, The routing currently treats --api-version as non-authoritative because useV2Update reads raw values via runtime.Str and auto-detects based on flag values; update useV2Update so that if runtime.Changed("api-version") is true it authoritatively returns true only when runtime.Str("api-version") == "v2" (and false when it's "v1"), and otherwise fall back to auto-detection; also change the auto-detection checks inside useV2Update to use runtime.Changed("command"), runtime.Changed("content"), runtime.Changed("pattern"), runtime.Changed("block-id"), and runtime.Changed("src-block-ids") (instead of runtime.Str) so only explicitly provided v2-only flags route to v2.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@shortcuts/doc/docs_create_test.go`:
- Around line 24-30: The tests use registerDocsCreateAPIStub only to stub
responses, so they don't verify the v2 create request payload; update the v2
create tests (e.g., the test using registerDocsCreateAPIStub in
shortcuts/doc/docs_create_test.go and the other occurrences) to capture and
return the stub instance, then assert its CapturedBody includes the expected
fields (--content present, correct --doc-format default, and parent placement
fields). Locate the stub created via registerDocsCreateAPIStub, change the call
to assign the returned stub to a variable, and add assertions against
stub.CapturedBody (or equivalent captured request) in at least one v2 create
test for each listed block so any behavior change in the outgoing OpenAPI
request is detected.
In `@shortcuts/doc/docs_update_test.go`:
- Around line 12-31: The current test only asserts the allowlist
(validCommandsV2); add table-driven tests that cover each command’s
required/disallowed flags and the produced request body from buildUpdateBody:
create test cases for "append" (verify body fields for appending), "str_replace"
with --content "" (verify empty-content behavior in buildUpdateBody), and
copy/move commands (verify source block IDs are included and mapped correctly),
and iterate over validCommandsV2 to assert flag validation errors and
buildUpdateBody output match expected JSON/struct for each case; target the test
helpers and functions named validCommandsV2 and buildUpdateBody when adding
these assertions.
In `@skills/lark-doc/references/lark-doc-md.md`:
- Line 53: The bullet for **双引号 `"..."`** is incorrect about `>` being treated
as redirection; update the text that currently says "把 `>` 当重定向" to accurately
describe double-quote behavior: explain that double quotes allow variable
expansion (`$变量`) and command substitution (backticks or `$()`), and that
backslashes still escape certain characters, while characters like `>` are taken
literally inside quotes; locate the offending string "**双引号 `\"...\"`**：会展开
`$变量`、把 `>` 当重定向，易踩坑" and replace it with a corrected sentence conveying those
points.
In `@skills/lark-event/references/lark-event-subscribe.md`:
- Around line 195-198: The code appends user-controlled variable content (the
shell variable content) directly into lark-cli docs via the --content "-
$content" invocation which allows Markdown/meta-characters and newlines to break
doc structure; update the handling so content is safely escaped or encoded
before passing to lark-cli: sanitize the content variable (escape Markdown
special characters such as #, -, *, >, backticks, and convert newlines to a
literal-safe representation or wrap the entire payload as a fenced code block or
HTML-escaped text) and then use that sanitized/encoded value in the lark-cli
--content argument; refer to the content variable and the lark-cli docs +update
--content invocation when making the change.
---
Outside diff comments:
In `@skills/lark-doc/references/lark-doc-media-insert.md`:
- Around line 20-24: Update the table row for "图片是 URL" to include the new
direct-insert path using the "docs +update" command: change the cell text from
"先下载到本地 → `--file`；或用 `drive` 相关命令" to something like "可直接用 `docs +update`
插入网络图片，或先下载到本地 → `--file`；或用 `drive` 相关命令", and apply the same wording update to
the duplicate occurrence around lines 50-53 so agents know to prefer `docs
+update` for URL images; keep the existing `--file <path>`, `--from-clipboard`,
and `drive` references intact.
---
Duplicate comments:
In `@shortcuts/doc/docs_fetch.go`:
- Around line 107-116: The pagination hint is being written to the pretty-output
writer inside runtime.OutFormat (see runtime.OutFormat and the anonymous func
using w) which sends it to stdout; change the code so the hint triggered by
result["has_more"] is written to stderr instead (e.g., use
fmt.Fprintln(os.Stderr, "...") or the project's stderr logger) rather than
fmt.Fprintln(w, ...). Keep title and markdown output to the existing writer w,
but emit the "--- more content available ---" message directly to stderr when
has_more is true.
- Around line 32-40: The routing logic in useV2Fetch incorrectly auto-detects v2
even when the user explicitly passed --api-version v1; update useV2Fetch to
first check if runtime.Changed("api-version") and if so return
runtime.Str("api-version") == "v2" (so explicit v1 forces v1), otherwise fall
through to the existing v2-only flag detection loop; reference the useV2Fetch
function and the runtime.Changed / runtime.Str calls to locate where to add this
explicit-version check.
- Line 10: The code currently reads --offset and --limit as strings and ignores
strconv.Atoi errors (silently treating invalid values as 0); change these to
typed int flags (register them with the flag/pflag/Cobra int flag API rather
than string flags) so parsing is handled by the flag library and invalid values
are rejected, and only include offset/limit in the outgoing request when the
user explicitly set them (e.g., check the flag's Changed state or compare to a
sentinel/unset value); update the parsing code that currently calls strconv.Atoi
(referenced by the offset/limit flag variables and the parsing logic around
lines referenced) and similarly fix the other occurrences at the other sites
(lines 20-21 and 126-132) so no invalid string-to-int conversion silently
becomes zero.
In `@shortcuts/doc/docs_update_v2.go`:
- Around line 57-61: The str_replace handling drops explicitly provided empty
--content because buildUpdateBody ignores empty strings; fix by using the
RuntimeContext flag-presence helper (e.g., RuntimeContext.Changed / FlagChanged
/ WasSet — discover exact name via the provided rg command) to detect whether
--content was provided, validate that the flag was set (not just non-empty), and
when present include content in the update body even if it's the empty string;
update both the validation branch in the switch for "str_replace" and the
buildUpdateBody logic to consult the same RuntimeContext flag-presence helper so
the field is included when the flag was explicitly set (also apply the same
change for the other occurrence at lines 153-155).
In `@shortcuts/doc/docs_update.go`:
- Around line 49-58: The routing currently treats --api-version as
non-authoritative because useV2Update reads raw values via runtime.Str and
auto-detects based on flag values; update useV2Update so that if
runtime.Changed("api-version") is true it authoritatively returns true only when
runtime.Str("api-version") == "v2" (and false when it's "v1"), and otherwise
fall back to auto-detection; also change the auto-detection checks inside
useV2Update to use runtime.Changed("command"), runtime.Changed("content"),
runtime.Changed("pattern"), runtime.Changed("block-id"), and
runtime.Changed("src-block-ids") (instead of runtime.Str) so only explicitly
provided v2-only flags route to v2.
In `@shortcuts/doc/versioned_help.go`:
- Around line 33-40: The deprecation note is being written to stdout via
cmd.OutOrStdout() which can contaminate machine-readable output; update the
write target so the warning goes to stderr when ver == "v1" by using the
command's error output (e.g., cmd.ErrOrStderr()) instead of cmd.OutOrStdout(),
keeping the same formatted message and parameters (cmd.Parent().Name(),
cmd.Name()) so the deprecation/hint text is emitted to stderr.
In `@skill-template/domains/drive.md`:
- Line 115: Update the template text that documents the --block-id usage to
mention the v2 fetch requirement: modify the sentence that currently reads
"局部评论：传 `--block-id` 时启用；仅支持 `docx`，以及最终解析为 `docx` 的 wiki URL。block ID 可通过 `docs
+fetch --detail with-ids` 获取。" so it explicitly includes the v2 flag (e.g.,
reference `docs +fetch --detail with-ids --api-version v2`); ensure the mention
of `--detail with-ids` is annotated as v2-specific and keep the rest of the
guidance about `--block-id`/`docx` unchanged.
In `@skills/lark-doc/references/lark-doc-create.md`:
- Around line 66-72: The Markdown table's header separator row uses `--` for the
second column which can break rendering; update the separator row in
skills/lark-doc/references/lark-doc-create.md so each column uses a proper
Markdown separator (`---` or at least three dashes) matching the header count —
specifically change the middle cell from `--` to `---` so the row becomes `|
------------------- | --- |---------------------------------------------|`,
ensuring the `--api-version`, `--content`, `--doc-format`, `--parent-token`, and
`--parent-position` parameter columns render correctly.
In `@skills/lark-doc/references/lark-doc-fetch.md`:
- Around line 34-46: Add a blank line above each Markdown table to satisfy
MD058: insert an empty line before the table that starts with "| 意图 | `--detail`
| 说明 |" in the "## 选 `--detail`（每块详细度）" section and before the table that starts
with "| 模式 | 何时用 | 关键参数 | 行为要点 |" in the "## 选 `--scope`（读取范围）" section so both
tables are separated from preceding headings/text.
In `@skills/lark-doc/references/lark-doc-md.md`:
- Line 7: The warning callout's nested bold (**不想**) prematurely closes the
outer bold span; to fix, change the inner emphasis so it doesn't use double
asterisks—e.g., replace **不想** with single-asterisk emphasis *不想* or escape the
inner asterisks (\\*\\*不想\\*\\*) or use HTML tags like <strong> for the outer
and <em> for the inner; update the line containing the nested bold in the
callout so the outer bold span remains intact.
In `@skills/lark-doc/references/lark-doc-update.md`:
- Around line 36-45: Update the quick-reference table and example for the
block_move_after command to match the detailed section: change its required
flags to use --block-id and --src-block-ids (remove --content) and fix the
example so --block-id is an actual block id (not explanatory text) and
--src-block-ids contains the source block ids; ensure both the table row for
block_move_after and the corresponding example in the document use the exact
flag names (--block-id, --src-block-ids) and valid placeholder values.
In `@skills/lark-doc/references/lark-doc-xml.md`:
- Around line 23-33: The table's cells for the `<button>` and `<time>` rows
contain unescaped pipe characters ("OpenLink|DuplicatePage|FollowPage" and
"true|false") which break Markdown table parsing; update those cells in the row
for `<button>` and the row for `<time>` to escape the pipe characters (e.g.,
replace "|" with "\|" or wrap the entire value in code backticks) so they are
treated as literal text rather than column separators, ensuring the `<button>`
and `<time>` table entries render correctly.
- Around line 100-113: The heading "八、完整示例" is nested under "七、**重要规则**" causing
inconsistent numbering; move the "八、完整示例" heading out to the document root as a
top-level sibling of "七、**重要规则**" (ensure its markdown heading level matches
"七、**重要规则**"), update any surrounding indentation or block scope so the example
is not nested, and verify the heading text "八、完整示例" and its content remain
intact.
In `@skills/lark-doc/references/style/lark-doc-create-workflow.md`:
- Around line 38-43: In the "第四波 — 润色与图表（并行 Agent）" section update the typo in
the bullet that reads "Spawn Agent 定向改进：（结合 `lark-doc-style.md` 进润）" to use the
correct word "润色" (i.e., change "进润" → "润色"); ensure the corrected phrase reads
"结合 `lark-doc-style.md` 润色" and scan the nearby bullets (e.g., the lines about
`<whiteboard>`/`lark-whiteboard`, `<table>`/`<grid>`/`<callout>`, and `docs
+media-insert`) for any similar wording inconsistencies to keep style
consistent.
🪄 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: abf7e49c-0931-4f52-83ff-c04e42fb1265
📒 Files selected for processing (33)
README.mdREADME.zh.mdinternal/output/jq.gointernal/output/jq_raw_test.goshortcuts/common/runner.goshortcuts/common/types.goshortcuts/doc/docs_create.goshortcuts/doc/docs_create_test.goshortcuts/doc/docs_create_v2.goshortcuts/doc/docs_fetch.goshortcuts/doc/docs_fetch_v2.goshortcuts/doc/docs_update.goshortcuts/doc/docs_update_test.goshortcuts/doc/docs_update_v2.goshortcuts/doc/helpers.goshortcuts/doc/versioned_help.goskill-template/domains/drive.mdskills/lark-doc/SKILL.mdskills/lark-doc/references/lark-doc-create.mdskills/lark-doc/references/lark-doc-fetch.mdskills/lark-doc/references/lark-doc-md.mdskills/lark-doc/references/lark-doc-media-insert.mdskills/lark-doc/references/lark-doc-update.mdskills/lark-doc/references/lark-doc-xml.mdskills/lark-doc/references/style/lark-doc-create-workflow.mdskills/lark-doc/references/style/lark-doc-style.mdskills/lark-doc/references/style/lark-doc-update-workflow.mdskills/lark-drive/SKILL.mdskills/lark-drive/references/lark-drive-add-comment.mdskills/lark-event/references/lark-event-subscribe.mdskills/lark-vc/SKILL.mdskills/lark-whiteboard/SKILL.mdskills/lark-workflow-meeting-summary/SKILL.md
✅ Files skipped from review due to trivial changes (6)
- shortcuts/doc/helpers.go
- README.zh.md
- README.md
- skills/lark-vc/SKILL.md
- shortcuts/doc/docs_create_v2.go
- shortcuts/doc/docs_create.go
🚧 Files skipped from review as they are similar to previous changes (7)
- skills/lark-workflow-meeting-summary/SKILL.md
- skills/lark-whiteboard/SKILL.md
- skills/lark-doc/references/style/lark-doc-style.md
- shortcuts/doc/docs_fetch_v2.go
- internal/output/jq.go
- skills/lark-drive/references/lark-drive-add-comment.md
- skills/lark-doc/references/style/lark-doc-update-workflow.md
Comment on lines
+24
to
30
| registerDocsCreateAPIStub(reg, map[string]interface{}{ | ||
| "document": map[string]interface{}{ | ||
| "document_id": "doxcn_new_doc", | ||
| "revision_id": float64(1), | ||
| "url": "https://example.feishu.cn/docx/doxcn_new_doc", | ||
| }, | ||
| }) |
There was a problem hiding this comment.
Assert the v2 create request payload.
registerDocsCreateAPIStub only stubs the response, so these tests would still pass if the v2 implementation dropped --content, default --doc-format, or parent placement fields from the OpenAPI request. Return the stub and assert its CapturedBody in at least one v2 create test.
As per coding guidelines, Every behavior change must have an accompanying test.
Also applies to: 84-90, 116-122, 144-150, 291-301
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@shortcuts/doc/docs_create_test.go` around lines 24 - 30, The tests use
registerDocsCreateAPIStub only to stub responses, so they don't verify the v2
create request payload; update the v2 create tests (e.g., the test using
registerDocsCreateAPIStub in shortcuts/doc/docs_create_test.go and the other
occurrences) to capture and return the stub instance, then assert its
CapturedBody includes the expected fields (--content present, correct
--doc-format default, and parent placement fields). Locate the stub created via
registerDocsCreateAPIStub, change the call to assign the returned stub to a
variable, and add assertions against stub.CapturedBody (or equivalent captured
request) in at least one v2 create test for each listed block so any behavior
change in the outgoing OpenAPI request is detected.
Comment on lines
+12
to
+31
| func TestValidCommandsV2(t *testing.T) { | ||
| expected := map[string]bool{ | ||
| "str_replace": true, | ||
| "block_delete": true, | ||
| "block_insert_after": true, | ||
| "block_copy_insert_after": true, | ||
| "block_replace": true, | ||
| "block_move_after": true, | ||
| "overwrite": true, | ||
| "append": true, | ||
| } | ||
| if len(validCommandsV2) != len(expected) { | ||
| t.Fatalf("expected %d commands, got %d", len(expected), len(validCommandsV2)) | ||
| } | ||
| for cmd := range validCommandsV2 { | ||
| if !expected[cmd] { | ||
| t.Fatalf("unexpected command %q in validCommandsV2", cmd) | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
Add table tests for v2 validation and request-body construction.
This only locks the allowlist. The new v2 behavior also needs coverage for each command’s required/disallowed flags and buildUpdateBody output, especially append, str_replace --content "", and copy/move source block IDs. As per coding guidelines, Every behavior change must have an accompanying test.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@shortcuts/doc/docs_update_test.go` around lines 12 - 31, The current test
only asserts the allowlist (validCommandsV2); add table-driven tests that cover
each command’s required/disallowed flags and the produced request body from
buildUpdateBody: create test cases for "append" (verify body fields for
appending), "str_replace" with --content "" (verify empty-content behavior in
buildUpdateBody), and copy/move commands (verify source block IDs are included
and mapped correctly), and iterate over validCommandsV2 to assert flag
validation errors and buildUpdateBody output match expected JSON/struct for each
case; target the test helpers and functions named validCommandsV2 and
buildUpdateBody when adding these assertions.
Comment on lines
195
to
+198
| content=$(echo "$line" | jq -r '.content // empty') | ||
| [[ -z "$content" ]] && continue | ||
|
|
||
| lark-cli docs +update --doc "DOC_URL" --mode append --markdown "- $content" | ||
| lark-cli docs +update --api-version v2 --doc "DOC_URL" --command append --doc-format markdown --content "- $content" |
There was a problem hiding this comment.
Escape user-controlled message content before appending it.
content comes from chat events. Writing it directly as Markdown lets messages containing headings, lists, newlines, or XML-like tags change the document structure instead of being logged as literal text.
Safer example
content=$(echo "$line" | jq -r '.content // empty')
[[ -z "$content" ]] && continue
- lark-cli docs +update --api-version v2 --doc "DOC_URL" --command append --doc-format markdown --content "- $content"
+ entry=$(jq -Rn -r --arg c "$content" '"<ul><li>\($c|@html)</li></ul>"')
+ lark-cli docs +update --api-version v2 --doc "DOC_URL" --command append --doc-format xml --content "$entry"📝 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
| content=$(echo "$line" | jq -r '.content // empty') | |
| [[ -z "$content" ]] && continue | |
| lark-cli docs +update --doc "DOC_URL" --mode append --markdown "- $content" | |
| lark-cli docs +update --api-version v2 --doc "DOC_URL" --command append --doc-format markdown --content "- $content" | |
| content=$(echo "$line" | jq -r '.content // empty') | |
| [[ -z "$content" ]] && continue | |
| entry=$(jq -Rn -r --arg c "$content" '"<ul><li>\($c|@html)</li></ul>"') | |
| lark-cli docs +update --api-version v2 --doc "DOC_URL" --command append --doc-format xml --content "$entry" |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@skills/lark-event/references/lark-event-subscribe.md` around lines 195 - 198,
The code appends user-controlled variable content (the shell variable content)
directly into lark-cli docs via the --content "- $content" invocation which
allows Markdown/meta-characters and newlines to break doc structure; update the
handling so content is safely escaped or encoded before passing to lark-cli:
sanitize the content variable (escape Markdown special characters such as #, -,
*, >, backticks, and convert newlines to a literal-safe representation or wrap
the entire payload as a fenced code block or HTML-escaped text) and then use
that sanitized/encoded value in the lark-cli --content argument; refer to the
content variable and the lark-cli docs +update --content invocation when making
the change.
8e0fc73 to
f372328
Compare
🚀 PR Preview Install Guide🧰 CLI updatenpm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@358b94f19d39569244a9af79e61fe6c306e9fba5🧩 Skill updatenpx skills add larksuite/cli#sun/online -y -g |
Codecov Report❌ Patch coverage is ❌ Your patch check has failed because the patch coverage (24.60%) is below the target coverage (60.00%). You can increase the patch coverage or adjust the target coverage. Additional details and impacted files@@ Coverage Diff @@
## main #638 +/- ##
==========================================
- Coverage 62.89% 60.60% -2.30%
==========================================
Files 428 432 +4
Lines 37280 45699 +8419
==========================================
+ Hits 23448 27694 +4246
- Misses 11721 15882 +4161
- Partials 2111 2123 +12 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (10)
shortcuts/doc/docs_create_v2.go (1)
33-43:⚠️ Potential issue | 🟡 Minor
Desc()still overwrites the primary description in bot mode.Line 37 sets the primary description, then line 40 replaces it when
runtime.IsBot(). Compose once:Proposed fix
- d := common.NewDryRunAPI(). - POST("/open-apis/docs_ai/v1/documents"). - Desc("OpenAPI: create document"). - Body(body) - if runtime.IsBot() { - d.Desc("After document creation succeeds in bot mode, the CLI will also try to grant the current CLI user full_access (可管理权限) on the new document.") - } - return d + desc := "OpenAPI: create document" + if runtime.IsBot() { + desc += ". After creation succeeds in bot mode, the CLI will also try to grant the current CLI user full_access (可管理权限) on the new document." + } + return common.NewDryRunAPI(). + POST("/open-apis/docs_ai/v1/documents"). + Desc(desc). + Body(body)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_create_v2.go` around lines 33 - 43, The Desc() call in dryRunCreateV2 currently gets set then overwritten in bot mode; instead build a single description string (e.g., baseDesc := "OpenAPI: create document") and, if runtime.IsBot(), append the bot-specific sentence to that string, then call Desc(...) only once on the DryRunAPI returned from common.NewDryRunAPI().POST(...) so the primary description is composed rather than replaced.shortcuts/doc/docs_create_test.go (1)
291-301:⚠️ Potential issue | 🟡 Minorv2 create tests do not assert the outgoing request payload.
registerDocsCreateAPIStubdiscards the stub, so any regression that dropscontent,doc-format,parent-token, orparent-positionfrom the v2 request body would still pass these tests. Return the stub and assertstub.CapturedBodyin at least one v2 test (e.g.TestDocsCreateV2BotAutoGrantSuccess).As per coding guidelines: "Every behavior change must have an accompanying test."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_create_test.go` around lines 291 - 301, registerDocsCreateAPIStub currently discards the created httpmock.Stub so v2 create tests can't assert the outgoing request body; change registerDocsCreateAPIStub to return the *httpmock.Stub and update callers (e.g., in TestDocsCreateV2BotAutoGrantSuccess) to capture the returned stub and assert stub.CapturedBody contains the expected keys/values for "content", "doc-format", "parent-token", and "parent-position" (and any required values), failing the test if any are missing or incorrect.skills/lark-doc/references/lark-doc-xml.md (1)
113-113:⚠️ Potential issue | 🟡 MinorHeading level not corrected.
Previous review flagged this (and was marked addressed) but line 113 still uses
## 八、完整示例. Should be# 八、完整示例to match the other top-level chapter headings (# 一、……# 七、…).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-xml.md` at line 113, The heading "## 八、完整示例" is using level-2 but should be a top-level chapter like the other headings; change the markdown token for the line containing "## 八、完整示例" to a single hash so it reads "# 八、完整示例" to match the other top-level headings (e.g., "# 一、…", "# 七、…").skills/lark-doc/references/lark-doc-update.md (1)
153-162:⚠️ Potential issue | 🟡 Minor
block_move_afterexample still contains a malformed--block-id.Previous review (marked addressed) asked to fix line 160 to show a single valid anchor block ID (e.g.
"-1"). Current code still reads--block-id "-1表示末尾，page_id表示开头，blk", which is shown to users/agents as a literal value to copy.Proposed fix
- --block-id "-1表示末尾，page_id表示开头，blk" \ + --block-id "-1" \Also consider documenting the sentinel semantics (
-1= end,<page_id>= beginning,<block_id>= specific anchor) in the parameter table at line 30 rather than inside an example value.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-update.md` around lines 153 - 162, The example for the block_move_after command contains a malformed literal for the --block-id flag; replace the current literal value for --block-id ("-1表示末尾，page_id表示开头，blk") with a single valid anchor example such as "-1" (meaning append to end) and ensure the CLI example shows a real, copyable flag value; also add or update the parameter table entry for --block-id to document sentinel semantics (-1 = end, <page_id> = beginning, <block_id> = specific anchor) so the example no longer needs to encode those semantics inline.shortcuts/doc/docs_create.go (1)
30-37:⚠️ Potential issue | 🟡 MinorExplicit
--api-version v1is still overridden by v2 auto-detection.
docs +create --api-version v1 --markdown ...routes to v2 because v1 still populates no v2 flags — but any user invoking--api-version v1 --content ...(e.g. migrated scripts that pass both) is silently re-routed to v2. The fix pattern already applied inuseV2Fetch(seeshortcuts/doc/docs_fetch.go:30-42) should be mirrored here:Routing fix (matches useV2Fetch)
func useV2Create(runtime *common.RuntimeContext) bool { - if runtime.Str("api-version") == "v2" { - return true + if runtime.Changed("api-version") { + return runtime.Str("api-version") == "v2" } - return runtime.Str("content") != "" || - runtime.Str("parent-token") != "" || - runtime.Str("parent-position") != "" + for _, name := range []string{"content", "doc-format", "parent-token", "parent-position"} { + if runtime.Changed(name) { + return true + } + } + return false }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_create.go` around lines 30 - 37, The function useV2Create currently auto-detects v2 even when the caller explicitly supplied --api-version v1; update useV2Create to mirror useV2Fetch's routing: first check runtime.Has("api-version") and if present return true only when runtime.Str("api-version") == "v2" (return false for "v1" or other explicit values), otherwise fall back to the existing content/parent-token/parent-position checks; modify the useV2Create function accordingly so explicit --api-version overrides auto-detection.shortcuts/doc/docs_fetch.go (3)
114-115:⚠️ Potential issue | 🟡 MinorSend the pagination hint to stderr.
The
has_moremessage is a hint, not fetched document content, so writing it through the pretty-output writer pollutes stdout consumers.🔧 Proposed fix
if hasMore, ok := result["has_more"].(bool); ok && hasMore { - fmt.Fprintln(w, "\n--- more content available, use --offset and --limit to paginate ---") + fmt.Fprintln(runtime.IO().ErrOut, "--- more content available, use --offset and --limit to paginate ---") }As per coding guidelines, Program output (JSON envelopes) must go to stdout; progress, warnings, and hints must go to stderr.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_fetch.go` around lines 114 - 115, The hint about pagination is being written to the pretty-output writer (fmt.Fprintln(w, ...)) which pollutes stdout; change the code that checks result["has_more"] and, when true, write the message to stderr instead (e.g., use os.Stderr) so program output remains on stdout and hints/warnings go to stderr; ensure os is imported if not already and only the pagination hint line is switched from fmt.Fprintln(w, ...) to writing to stderr.
32-41:⚠️ Potential issue | 🟡 MinorRespect explicit
--api-version v1before auto-detecting v2.
--api-version v1 --detail with-idsstill routes to v2 because changed v2-only flags override the explicit version. Make explicit version selection authoritative, then auto-detect only when the user did not pass--api-version; add routing tests for explicit v1/v2 and v2 flag auto-detection. As per coding guidelines, Every behavior change must have an accompanying test.🔧 Proposed routing fix
func useV2Fetch(runtime *common.RuntimeContext) bool { + if runtime.Changed("api-version") { + return runtime.Str("api-version") == "v2" + } if runtime.Str("api-version") == "v2" { return true }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_fetch.go` around lines 32 - 41, The routing currently treats v2-only flags as authoritative even when the user explicitly passed --api-version v1; update useV2Fetch to first check if the user explicitly set api-version via runtime.Changed("api-version") and return true only if runtime.Str("api-version") == "v2" (return false if it's "v1" or any other explicit value), and only when api-version was not explicitly provided fall back to the existing auto-detect loop that checks runtime.Changed(...) for v2-only flags; additionally add unit tests that cover explicit --api-version v1 and v2 cases and the previous auto-detection behavior when api-version is not supplied.
20-21:⚠️ Potential issue | 🟡 MinorReject invalid v1 pagination values instead of coercing them to zero.
strconv.Atoierrors are ignored, so--offset abc/--limit abcbecome0and fetch the wrong page. Register these as int flags and include them only when explicitly changed.🔧 Proposed fix
import ( "context" "fmt" "io" - "strconv" "github.com/spf13/cobra" @@ return []common.Flag{ - {Name: "offset", Desc: "pagination offset", Hidden: true}, - {Name: "limit", Desc: "pagination limit", Hidden: true}, + {Name: "offset", Desc: "pagination offset", Hidden: true, Type: "int", Default: "0"}, + {Name: "limit", Desc: "pagination limit", Hidden: true, Type: "int", Default: "0"}, } } @@ - if v := runtime.Str("offset"); v != "" { - n, _ := strconv.Atoi(v) - args["offset"] = n + if runtime.Changed("offset") { + args["offset"] = runtime.Int("offset") } - if v := runtime.Str("limit"); v != "" { - n, _ := strconv.Atoi(v) - args["limit"] = n + if runtime.Changed("limit") { + args["limit"] = runtime.Int("limit") }Also applies to: 126-132
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_fetch.go` around lines 20 - 21, The current flag handling for "offset" and "limit" coerces invalid values to 0 because strconv.Atoi errors are ignored; change the flags to be registered as int flags (use flag.Int or equivalent) for "offset" and "limit" instead of parsing strings with strconv.Atoi, validate any parsing errors and return an error to the user for invalid inputs, and only include the offset/limit parameters in the request when the int flags have been explicitly set (i.e., not their zero default) so you don't send unintended zero pagination; update the code locations referencing the "offset" and "limit" flag parsing (the existing strconv.Atoi usages and flag definitions) and apply the same change to the similar block at the other occurrence (lines around the second block 126-132).shortcuts/doc/docs_fetch_v2.go (1)
22-28:⚠️ Potential issue | 🟡 MinorKeep all v2-only fetch flags hidden by default.
These partial-read flags are v2-only but are not initialized with
Hidden: true, unlikedoc-format,detail, andrevision-id; that can leak inactive-version flags in non-help usage output before versioned help rewrites visibility.🔧 Proposed fix
- {Name: "scope", Desc: "partial read scope: outline | range | keyword | section (omit to read whole doc)", Default: "full", Enum: []string{"full", "outline", "range", "keyword", "section"}}, - {Name: "start-block-id", Desc: "range/section mode: start (anchor) block id"}, - {Name: "end-block-id", Desc: "range mode: end block id; \"-1\" = to end of document"}, - {Name: "keyword", Desc: "keyword mode: search string (case-insensitive); use '|' to match multiple keywords, e.g. 'foo|bar|baz'"}, - {Name: "context-before", Desc: "range/keyword/section mode: sibling blocks before match", Type: "int", Default: "0"}, - {Name: "context-after", Desc: "range/keyword/section mode: sibling blocks after match", Type: "int", Default: "0"}, - {Name: "max-depth", Desc: "outline: heading level cap; range/keyword/section: block subtree depth (-1 = unlimited)", Type: "int", Default: "-1"}, + {Name: "scope", Desc: "partial read scope: outline | range | keyword | section (omit to read whole doc)", Hidden: true, Default: "full", Enum: []string{"full", "outline", "range", "keyword", "section"}}, + {Name: "start-block-id", Desc: "range/section mode: start (anchor) block id", Hidden: true}, + {Name: "end-block-id", Desc: "range mode: end block id; \"-1\" = to end of document", Hidden: true}, + {Name: "keyword", Desc: "keyword mode: search string (case-insensitive); use '|' to match multiple keywords, e.g. 'foo|bar|baz'", Hidden: true}, + {Name: "context-before", Desc: "range/keyword/section mode: sibling blocks before match", Hidden: true, Type: "int", Default: "0"}, + {Name: "context-after", Desc: "range/keyword/section mode: sibling blocks after match", Hidden: true, Type: "int", Default: "0"}, + {Name: "max-depth", Desc: "outline: heading level cap; range/keyword/section: block subtree depth (-1 = unlimited)", Hidden: true, Type: "int", Default: "-1"},🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_fetch_v2.go` around lines 22 - 28, The listed fetch flags ("scope", "start-block-id", "end-block-id", "keyword", "context-before", "context-after", "max-depth") in docs_fetch_v2.go are v2-only but missing Hidden: true; update each flag's descriptor (the entries for these names) to include Hidden: true so they remain hidden by default like the existing v2-only flags (e.g., doc-format, detail, revision-id), ensuring non-help usages don’t leak inactive-version flags.shortcuts/doc/docs_update.go (1)
49-58:⚠️ Potential issue | 🟡 MinorRespect explicit
--api-version v1before v2 auto-detection.
--api-version v1 --command appendstill routes to v2, and default-valued v2 flags like--doc-format xml/--revision-id -1are not reliably detected because the check uses string values instead ofChanged. Make explicit version selection authoritative, then auto-detect only changed v2-only flags; cover both paths with routing tests. As per coding guidelines, Every behavior change must have an accompanying test.🔧 Proposed routing fix
func useV2Update(runtime *common.RuntimeContext) bool { + if runtime.Changed("api-version") { + return runtime.Str("api-version") == "v2" + } if runtime.Str("api-version") == "v2" { return true } - return runtime.Str("command") != "" || - runtime.Str("content") != "" || - runtime.Str("pattern") != "" || - runtime.Str("block-id") != "" || - runtime.Str("src-block-ids") != "" + for _, name := range []string{"command", "content", "pattern", "block-id", "src-block-ids", "doc-format", "revision-id"} { + if runtime.Changed(name) { + return true + } + } + return false }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/docs_update.go` around lines 49 - 58, The current useV2Update function ignores an explicit "--api-version v1" and misdetects v2 flags by reading runtime.Str values; update useV2Update to first return false when runtime.Str("api-version") == "v1", then for auto-detection only consider v2-only flags via runtime.Changed("command"), runtime.Changed("content"), runtime.Changed("pattern"), runtime.Changed("block-id"), runtime.Changed("src-block-ids") (instead of checking their string values), and add routing unit tests that assert behavior when api-version is explicitly "v1", when explicitly "v2", and when v2-only flags are changed to cover both paths.
🧹 Nitpick comments (3)
internal/output/jq.go (1)
15-29: Godoc comment forJqFilterreads unclear.Line 17-18 says
HTML escaping (<, >, & → <, >, &), which renders as identical characters on both sides of the arrow and obscures what actually happens (they get escaped to\u003c/\u003e/\u0026). Consider clarifying so future readers immediately see whyJqFilterRawexists.Proposed doc tweak
// JqFilter applies a jq expression to data and writes the results to w. // Scalar values are printed raw (no quotes for strings), matching jq -r behavior. -// Complex values (maps, arrays) are printed as indented JSON with Go's default -// HTML escaping (<, >, & → <, >, &). +// Complex values (maps, arrays) are printed as indented JSON with Go's default +// HTML escaping applied (so `<`, `>`, and `&` are emitted as `\u003c`, +// `\u003e`, and `\u0026`). Use JqFilterRaw when HTML/XML must be preserved +// verbatim. func JqFilter(w io.Writer, data interface{}, expr string) error {🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@internal/output/jq.go` around lines 15 - 29, Update the godoc for JqFilter (and mention JqFilterRaw) to explicitly state that Go's JSON marshaling escapes HTML characters, e.g. '<' becomes '\u003c', '>' becomes '\u003e', and '&' becomes '\u0026', which is why JqFilterRaw exists to disable that escaping; reference the functions JqFilter, JqFilterRaw and the helper jqFilter so reviewers can find the implementation and ensure the comment clarifies that complex values are re-marshaled with HTML-escaped sequences unless the raw flag (used by JqFilterRaw) is true.shortcuts/doc/versioned_help.go (1)
19-43:cmd.Parent()nil-deref risk and flag-state mutation across help invocations.Two small hardening suggestions:
- Line 40 dereferences
cmd.Parent()unconditionally. For the current call sites (docs +create/+fetch/+update) the parent is always non-nil, but if this helper is ever reused on a top-level command it will panic. Guard it.- Line 27-31 mutates
f.Hiddenon the sharedpflag.Flaginstances as a side effect of help. If the same process ever invokes--helpwith one--api-versionand later runs (or help-dumps) with another, the hidden state from the previous call persists across flags not re-visited. In practice this is not hit today (help runs then exits), but it's surprising behavior; consider restoring the priorHiddenvalues via a deferred pass, or documenting the assumption.Proposed guard for Parent()
- if ver == "v1" { - fmt.Fprintf(cmd.ErrOrStderr(), - "\n[NOTE] v1 API is deprecated and will be removed in a future release.\n"+ - " Use --api-version v2 for the latest API:\n"+ - " %s %s --api-version v2 --help\n"+ - " Upgrade skill:\n"+ - " npx skills add larksuite/cli#feat/upgrade-command -y -g\n", - cmd.Parent().Name(), cmd.Name()) - } + if ver == "v1" { + parentName := "" + if p := cmd.Parent(); p != nil { + parentName = p.Name() + } + fmt.Fprintf(cmd.ErrOrStderr(), + "\n[NOTE] v1 API is deprecated and will be removed in a future release.\n"+ + " Use --api-version v2 for the latest API:\n"+ + " %s %s --api-version v2 --help\n"+ + " Upgrade skill:\n"+ + " npx skills add larksuite/cli#feat/upgrade-command -y -g\n", + parentName, cmd.Name()) + }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@shortcuts/doc/versioned_help.go` around lines 19 - 43, installVersionedHelp currently dereferences cmd.Parent() unconditionally and mutates shared pflag.Flag.Hidden in-place during cmd.Flags().VisitAll, which risks panics and persistent state across help invocations; fix by (1) guarding the parent deref: compute parentName := "" and if cmd.Parent() != nil set parentName = cmd.Parent().Name(), then use parentName when writing the note; and (2) avoid permanent mutation of flags by capturing prior hidden states inside VisitAll (e.g., build a map[ string ]bool of original Hidden values), set f.Hidden as needed for rendering, and after origHelp returns restore each flag’s Hidden from that map (or use defer to restore) so the VisitAll pass does not leave side effects on pflag.Flag.Hidden.skills/lark-doc/references/lark-doc-media-insert.md (1)
49-56: URL-insert example is placed under the "从本地文件插入" heading, which is misleading.Lines 49 and 55 are "从本地文件插入" / "插入图片（默认）" comments, but the new snippet at Lines 50-53 is about inserting an image from a network URL — not from a local file. Readers scanning by section header will miss it, and the transitional prose on Line 50 ("除了上传本地文件…") reads awkwardly as the very first line under the "从本地文件插入" header.
Consider promoting this into its own subsection (e.g. a new
## 通过 URL 直接插入网络图片（v2）block, or at least a distinct# 通过 URL 插入（docs +update --api-version v2）comment) placed alongside — not inside — the local-file example.Proposed restructure
# 从本地文件插入 -# 除了上传本地文件，还可以在 `docs +update` 时直接通过网络 URL 插入图片，无需先下载到本地： -lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_insert_after \ - --block-id "目标 block_id" \ - --content '<img href="https://example.com/photo.png"/>' - -# 插入图片（默认） +# 插入图片（默认） lark-cli docs +media-insert --doc doxcnXXX --file ./image.png + +# 通过 URL 直接插入网络图片（docs +update --api-version v2，无需先下载到本地） +lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_insert_after \ + --block-id "目标 block_id" \ + --content '<img href="https://example.com/photo.png"/>'🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-media-insert.md` around lines 49 - 56, 将“通过网络 URL 插入图片”的示例从“从本地文件插入”节中抽离出来并移动到一个独立小节；具体操作是创建一个新的小标题（例如 “## 通过 URL 直接插入网络图片（v2）” 或 “# 通过 URL 插入（docs +update --api-version v2）”），然后把包含命令 lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_insert_after --block-id "目标 block_id" --content '<img href="https://example.com/photo.png"/>' 的整段示例移动到该小节，并保留本地文件示例 lark-cli docs +media-insert --doc doxcnXXX --file ./image.png 在原有“从本地文件插入”节以避免混淆。
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@shortcuts/common/runner.go`:
- Around line 520-537: RuntimeContext.OutRaw currently skips content-safety
scanning and sets ctx.outputErr unsafely; update OutRaw to mirror Out by running
output.ScanForSafety on the payload (or on the JQ-filtered result in the JqExpr
branch), honor scanResult.Blocked (return without writing) and scanResult.Alert
semantics the same way Out does, and replace the bare if ctx.outputErr == nil
assignment with the same ctx.outputErrOnce.Do(...) pattern used by Out when
recording the first error; keep the existing use of output.JqFilterRaw and
json.Encoder but perform scanning and safe error recording in both branches to
match Out’s behavior.
In `@shortcuts/doc/docs_fetch_v2.go`:
- Around line 159-162: The early return when mode :=
strings.TrimSpace(runtime.Str("scope")) is "" or "full" causes buildReadOption
to omit read_option and silently fetch full docs even when partial-read flags
are set; update the check in docs_fetch_v2.go so that when mode=="" or "full"
you validate that no partial-read flags (e.g., --start-block-id, --keyword,
--context-before) are present and return an error if they are, otherwise
proceed; ensure useV2Fetch/buildReadOption only omit read_option when scope is
full and no partial flags were provided and surface a clear validation error
when the combination is invalid.
---
Duplicate comments:
In `@shortcuts/doc/docs_create_test.go`:
- Around line 291-301: registerDocsCreateAPIStub currently discards the created
httpmock.Stub so v2 create tests can't assert the outgoing request body; change
registerDocsCreateAPIStub to return the *httpmock.Stub and update callers (e.g.,
in TestDocsCreateV2BotAutoGrantSuccess) to capture the returned stub and assert
stub.CapturedBody contains the expected keys/values for "content", "doc-format",
"parent-token", and "parent-position" (and any required values), failing the
test if any are missing or incorrect.
In `@shortcuts/doc/docs_create_v2.go`:
- Around line 33-43: The Desc() call in dryRunCreateV2 currently gets set then
overwritten in bot mode; instead build a single description string (e.g.,
baseDesc := "OpenAPI: create document") and, if runtime.IsBot(), append the
bot-specific sentence to that string, then call Desc(...) only once on the
DryRunAPI returned from common.NewDryRunAPI().POST(...) so the primary
description is composed rather than replaced.
In `@shortcuts/doc/docs_create.go`:
- Around line 30-37: The function useV2Create currently auto-detects v2 even
when the caller explicitly supplied --api-version v1; update useV2Create to
mirror useV2Fetch's routing: first check runtime.Has("api-version") and if
present return true only when runtime.Str("api-version") == "v2" (return false
for "v1" or other explicit values), otherwise fall back to the existing
content/parent-token/parent-position checks; modify the useV2Create function
accordingly so explicit --api-version overrides auto-detection.
In `@shortcuts/doc/docs_fetch_v2.go`:
- Around line 22-28: The listed fetch flags ("scope", "start-block-id",
"end-block-id", "keyword", "context-before", "context-after", "max-depth") in
docs_fetch_v2.go are v2-only but missing Hidden: true; update each flag's
descriptor (the entries for these names) to include Hidden: true so they remain
hidden by default like the existing v2-only flags (e.g., doc-format, detail,
revision-id), ensuring non-help usages don’t leak inactive-version flags.
In `@shortcuts/doc/docs_fetch.go`:
- Around line 114-115: The hint about pagination is being written to the
pretty-output writer (fmt.Fprintln(w, ...)) which pollutes stdout; change the
code that checks result["has_more"] and, when true, write the message to stderr
instead (e.g., use os.Stderr) so program output remains on stdout and
hints/warnings go to stderr; ensure os is imported if not already and only the
pagination hint line is switched from fmt.Fprintln(w, ...) to writing to stderr.
- Around line 32-41: The routing currently treats v2-only flags as authoritative
even when the user explicitly passed --api-version v1; update useV2Fetch to
first check if the user explicitly set api-version via
runtime.Changed("api-version") and return true only if
runtime.Str("api-version") == "v2" (return false if it's "v1" or any other
explicit value), and only when api-version was not explicitly provided fall back
to the existing auto-detect loop that checks runtime.Changed(...) for v2-only
flags; additionally add unit tests that cover explicit --api-version v1 and v2
cases and the previous auto-detection behavior when api-version is not supplied.
- Around line 20-21: The current flag handling for "offset" and "limit" coerces
invalid values to 0 because strconv.Atoi errors are ignored; change the flags to
be registered as int flags (use flag.Int or equivalent) for "offset" and "limit"
instead of parsing strings with strconv.Atoi, validate any parsing errors and
return an error to the user for invalid inputs, and only include the
offset/limit parameters in the request when the int flags have been explicitly
set (i.e., not their zero default) so you don't send unintended zero pagination;
update the code locations referencing the "offset" and "limit" flag parsing (the
existing strconv.Atoi usages and flag definitions) and apply the same change to
the similar block at the other occurrence (lines around the second block
126-132).
In `@shortcuts/doc/docs_update.go`:
- Around line 49-58: The current useV2Update function ignores an explicit
"--api-version v1" and misdetects v2 flags by reading runtime.Str values; update
useV2Update to first return false when runtime.Str("api-version") == "v1", then
for auto-detection only consider v2-only flags via runtime.Changed("command"),
runtime.Changed("content"), runtime.Changed("pattern"),
runtime.Changed("block-id"), runtime.Changed("src-block-ids") (instead of
checking their string values), and add routing unit tests that assert behavior
when api-version is explicitly "v1", when explicitly "v2", and when v2-only
flags are changed to cover both paths.
In `@skills/lark-doc/references/lark-doc-update.md`:
- Around line 153-162: The example for the block_move_after command contains a
malformed literal for the --block-id flag; replace the current literal value for
--block-id ("-1表示末尾，page_id表示开头，blk") with a single valid anchor example such as
"-1" (meaning append to end) and ensure the CLI example shows a real, copyable
flag value; also add or update the parameter table entry for --block-id to
document sentinel semantics (-1 = end, <page_id> = beginning, <block_id> =
specific anchor) so the example no longer needs to encode those semantics
inline.
In `@skills/lark-doc/references/lark-doc-xml.md`:
- Line 113: The heading "## 八、完整示例" is using level-2 but should be a top-level
chapter like the other headings; change the markdown token for the line
containing "## 八、完整示例" to a single hash so it reads "# 八、完整示例" to match the
other top-level headings (e.g., "# 一、…", "# 七、…").
---
Nitpick comments:
In `@internal/output/jq.go`:
- Around line 15-29: Update the godoc for JqFilter (and mention JqFilterRaw) to
explicitly state that Go's JSON marshaling escapes HTML characters, e.g. '<'
becomes '\u003c', '>' becomes '\u003e', and '&' becomes '\u0026', which is why
JqFilterRaw exists to disable that escaping; reference the functions JqFilter,
JqFilterRaw and the helper jqFilter so reviewers can find the implementation and
ensure the comment clarifies that complex values are re-marshaled with
HTML-escaped sequences unless the raw flag (used by JqFilterRaw) is true.
In `@shortcuts/doc/versioned_help.go`:
- Around line 19-43: installVersionedHelp currently dereferences cmd.Parent()
unconditionally and mutates shared pflag.Flag.Hidden in-place during
cmd.Flags().VisitAll, which risks panics and persistent state across help
invocations; fix by (1) guarding the parent deref: compute parentName := "" and
if cmd.Parent() != nil set parentName = cmd.Parent().Name(), then use parentName
when writing the note; and (2) avoid permanent mutation of flags by capturing
prior hidden states inside VisitAll (e.g., build a map[ string ]bool of original
Hidden values), set f.Hidden as needed for rendering, and after origHelp returns
restore each flag’s Hidden from that map (or use defer to restore) so the
VisitAll pass does not leave side effects on pflag.Flag.Hidden.
In `@skills/lark-doc/references/lark-doc-media-insert.md`:
- Around line 49-56: 将“通过网络 URL
插入图片”的示例从“从本地文件插入”节中抽离出来并移动到一个独立小节；具体操作是创建一个新的小标题（例如 “## 通过 URL 直接插入网络图片（v2）” 或
“# 通过 URL 插入（docs +update --api-version v2）”），然后把包含命令 lark-cli docs +update
--api-version v2 --doc "<doc_id>" --command block_insert_after --block-id "目标
block_id" --content '<img href="https://example.com/photo.png"/>'
的整段示例移动到该小节，并保留本地文件示例 lark-cli docs +media-insert --doc doxcnXXX --file
./image.png 在原有“从本地文件插入”节以避免混淆。
🪄 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: 2786816a-9c21-4c59-aee8-bfa68aa0e168
📒 Files selected for processing (33)
README.mdREADME.zh.mdinternal/output/jq.gointernal/output/jq_raw_test.goshortcuts/common/runner.goshortcuts/common/types.goshortcuts/doc/docs_create.goshortcuts/doc/docs_create_test.goshortcuts/doc/docs_create_v2.goshortcuts/doc/docs_fetch.goshortcuts/doc/docs_fetch_v2.goshortcuts/doc/docs_update.goshortcuts/doc/docs_update_test.goshortcuts/doc/docs_update_v2.goshortcuts/doc/helpers.goshortcuts/doc/versioned_help.goskill-template/domains/drive.mdskills/lark-doc/SKILL.mdskills/lark-doc/references/lark-doc-create.mdskills/lark-doc/references/lark-doc-fetch.mdskills/lark-doc/references/lark-doc-md.mdskills/lark-doc/references/lark-doc-media-insert.mdskills/lark-doc/references/lark-doc-update.mdskills/lark-doc/references/lark-doc-xml.mdskills/lark-doc/references/style/lark-doc-create-workflow.mdskills/lark-doc/references/style/lark-doc-style.mdskills/lark-doc/references/style/lark-doc-update-workflow.mdskills/lark-drive/SKILL.mdskills/lark-drive/references/lark-drive-add-comment.mdskills/lark-event/references/lark-event-subscribe.mdskills/lark-vc/SKILL.mdskills/lark-whiteboard/SKILL.mdskills/lark-workflow-meeting-summary/SKILL.md
✅ Files skipped from review due to trivial changes (6)
- shortcuts/doc/helpers.go
- shortcuts/common/types.go
- README.zh.md
- skills/lark-vc/SKILL.md
- skills/lark-doc/references/style/lark-doc-style.md
- skills/lark-doc/references/style/lark-doc-update-workflow.md
🚧 Files skipped from review as they are similar to previous changes (8)
- README.md
- skills/lark-event/references/lark-event-subscribe.md
- internal/output/jq_raw_test.go
- skill-template/domains/drive.md
- skills/lark-whiteboard/SKILL.md
- skills/lark-workflow-meeting-summary/SKILL.md
- shortcuts/doc/docs_update_v2.go
- shortcuts/doc/docs_update_test.go
Comment on lines
+520
to
+537
| func (ctx *RuntimeContext) OutRaw(data interface{}, meta *output.Meta) { | ||
| env := output.Envelope{OK: true, Identity: string(ctx.As()), Data: data, Meta: meta, Notice: output.GetNotice()} | ||
| if ctx.JqExpr != "" { | ||
| // JqFilterRaw (not JqFilter) so that complex jq results preserve | ||
| // XML/HTML as-is, matching the non-jq branch below. | ||
| if err := output.JqFilterRaw(ctx.IO().Out, env, ctx.JqExpr); err != nil { | ||
| fmt.Fprintf(ctx.IO().ErrOut, "error: %v\n", err) | ||
| if ctx.outputErr == nil { | ||
| ctx.outputErr = err | ||
| } | ||
| } | ||
| return | ||
| } | ||
| enc := json.NewEncoder(ctx.IO().Out) | ||
| enc.SetEscapeHTML(false) | ||
| enc.SetIndent("", " ") | ||
| _ = enc.Encode(env) | ||
| } |
There was a problem hiding this comment.
OutRaw skips content-safety scanning and uses unsynchronized outputErr write.
Two gaps versus Out():
Outrunsoutput.ScanForSafety(...)and honorsscanResult.Blocked/scanResult.Alert.OutRawdoes neither, so v2 doc responses (create/fetch/update) bypass the safety scanner entirely even though they carry user-controlled XML/HTML payloads. This weakens the guarantee documented onOut.- The first-error capture uses a bare
if ctx.outputErr == nil { ctx.outputErr = err }(lines 527-529) whileOut()serializes the same write throughctx.outputErrOnce. If any caller ends up invoking both on the sameRuntimeContext(or future concurrent output paths), this is a race; at minimum it is inconsistent with the documented pattern.
Proposed fix sketch
func (ctx *RuntimeContext) OutRaw(data interface{}, meta *output.Meta) {
+ scanResult := output.ScanForSafety(ctx.Cmd.CommandPath(), data, ctx.IO().ErrOut)
+ if scanResult.Blocked {
+ ctx.outputErrOnce.Do(func() { ctx.outputErr = scanResult.BlockErr })
+ return
+ }
env := output.Envelope{OK: true, Identity: string(ctx.As()), Data: data, Meta: meta, Notice: output.GetNotice()}
+ if scanResult.Alert != nil {
+ env.ContentSafetyAlert = scanResult.Alert
+ }
if ctx.JqExpr != "" {
if err := output.JqFilterRaw(ctx.IO().Out, env, ctx.JqExpr); err != nil {
fmt.Fprintf(ctx.IO().ErrOut, "error: %v\n", err)
- if ctx.outputErr == nil {
- ctx.outputErr = err
- }
+ ctx.outputErrOnce.Do(func() { ctx.outputErr = err })
}
return
}🧰 Tools
🪛 GitHub Check: codecov/patch
[warning] 520-529: shortcuts/common/runner.go#L520-L529
Added lines #L520 - L529 were not covered by tests
[warning] 531-531: shortcuts/common/runner.go#L531
Added line #L531 was not covered by tests
[warning] 533-536: shortcuts/common/runner.go#L533-L536
Added lines #L533 - L536 were not covered by tests
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@shortcuts/common/runner.go` around lines 520 - 537, RuntimeContext.OutRaw
currently skips content-safety scanning and sets ctx.outputErr unsafely; update
OutRaw to mirror Out by running output.ScanForSafety on the payload (or on the
JQ-filtered result in the JqExpr branch), honor scanResult.Blocked (return
without writing) and scanResult.Alert semantics the same way Out does, and
replace the bare if ctx.outputErr == nil assignment with the same
ctx.outputErrOnce.Do(...) pattern used by Out when recording the first error;
keep the existing use of output.JqFilterRaw and json.Encoder but perform
scanning and safe error recording in both branches to match Out’s behavior.
Comment on lines
+159
to
+162
| mode := strings.TrimSpace(runtime.Str("scope")) | ||
| if mode == "" || mode == "full" { | ||
| return nil | ||
| } |
There was a problem hiding this comment.
Reject partial-read flags when --scope is full.
useV2Fetch routes to v2 when flags like --start-block-id, --keyword, or --context-before are changed, but this early return makes buildReadOption omit read_option entirely. The command can silently fetch the full document instead of the requested subset.
🛡️ Proposed validation
mode := strings.TrimSpace(runtime.Str("scope"))
if mode == "" || mode == "full" {
+ for _, name := range []string{"start-block-id", "end-block-id", "keyword", "context-before", "context-after", "max-depth"} {
+ if runtime.Changed(name) {
+ return common.FlagErrorf("--%s requires --scope outline, range, keyword, or section", name)
+ }
+ }
return nil
}📝 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
| mode := strings.TrimSpace(runtime.Str("scope")) | |
| if mode == "" || mode == "full" { | |
| return nil | |
| } | |
| mode := strings.TrimSpace(runtime.Str("scope")) | |
| if mode == "" || mode == "full" { | |
| for _, name := range []string{"start-block-id", "end-block-id", "keyword", "context-before", "context-after", "max-depth"} { | |
| if runtime.Changed(name) { | |
| return common.FlagErrorf("--%s requires --scope outline, range, keyword, or section", name) | |
| } | |
| } | |
| return nil | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@shortcuts/doc/docs_fetch_v2.go` around lines 159 - 162, The early return when
mode := strings.TrimSpace(runtime.Str("scope")) is "" or "full" causes
buildReadOption to omit read_option and silently fetch full docs even when
partial-read flags are set; update the check in docs_fetch_v2.go so that when
mode=="" or "full" you validate that no partial-read flags (e.g.,
--start-block-id, --keyword, --context-before) are present and return an error
if they are, otherwise proceed; ensure useV2Fetch/buildReadOption only omit
read_option when scope is full and no partial flags were provided and surface a
clear validation error when the combination is invalid.
Adds an `--api-version v2` path to the docs shortcuts, backed by the
`docs_ai/v1/documents` OpenAPI. DocxXML is the default document format
and Markdown is available as an alternative. Content input is unified
across the three shortcuts via `--content` + `--doc-format`. The v1
(MCP) path is preserved for backward compatibility and now prints a
deprecation notice on use.
Shortcuts:
- `docs +create --api-version v2`: create a document from XML or
Markdown, with optional `--parent-token` or `--parent-position`.
Bot identity continues to auto-grant the current CLI user
full_access on the new document.
- `docs +fetch --api-version v2`: adds `--detail simple|with-ids|full`
for export granularity and `--scope full|outline|range|keyword|section`
for partial reads, along with `--context-before` / `--context-after`,
`--max-depth`, and `--revision-id`.
- `docs +update --api-version v2`: introduces structured operations
via `--command`: `str_replace`, `block_delete`, `block_insert_after`,
`block_copy_insert_after`, `block_replace`, `block_move_after`,
`overwrite`, `append`.
Framework support in `shortcuts/common`:
- `OutRaw` / `OutFormatRaw` emit the JSON envelope with HTML escaping
disabled so XML/HTML document bodies are preserved verbatim.
- New `Shortcut.PostMount` hook runs after a cobra.Command is fully
configured; used here to install a version-aware help function
that hides flags belonging to the inactive `--api-version`.
Also refreshes the lark-doc skill pack (SKILL.md, create/fetch/update
references, new lark-doc-xml and lark-doc-md references, style and
workflow guides), README examples, and downstream skill call sites
(lark-drive, lark-vc, lark-whiteboard, lark-workflow-meeting-summary,
lark-event).
Change-Id: Ide2d86b190a4e21095ae29096e7fb00031d80489
SunPeiYang996
force-pushed
the
sun/online
branch
from
f372328 to
358b94f
Compare
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
3 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.
Adds an
--api-version v2path to the docs shortcuts, backed by thedocs_ai/v1/documentsOpenAPI. DocxXML is the default document format and Markdown is available as an alternative. Content input is unified across the three shortcuts via--content+--doc-format. The v1 (MCP) path is preserved for backward compatibility and now prints a deprecation notice on use.Shortcuts:
docs +create --api-version v2: create a document from XML or Markdown, with optional--parent-tokenor--parent-position. Bot identity continues to auto-grant the current CLI user full_access on the new document.docs +fetch --api-version v2: adds--detail simple|with-ids|fullfor export granularity and--scope full|outline|range|keyword|sectionfor partial reads, along with--context-before/--context-after,--max-depth, and--revision-id.docs +update --api-version v2: introduces structured operations via--command:str_replace,block_delete,block_insert_after,block_copy_insert_after,block_replace,block_move_after,overwrite,append.Framework support in
shortcuts/common:OutRaw/OutFormatRawemit the JSON envelope with HTML escaping disabled so XML/HTML document bodies are preserved verbatim.Shortcut.PostMounthook runs after a cobra.Command is fully configured; used here to install a version-aware help function that hides flags belonging to the inactive--api-version.Also refreshes the lark-doc skill pack (SKILL.md, create/fetch/update references, new lark-doc-xml and lark-doc-md references, style and workflow guides), README examples, and downstream skill call sites (lark-drive, lark-vc, lark-whiteboard, lark-workflow-meeting-summary, lark-event).
Change-Id: Ide2d86b190a4e21095ae29096e7fb00031d80489
Summary
Changes
Test Plan
lark xxxcommand works as expectedRelated Issues
Summary by CodeRabbit
New Features
Documentation
Tests