chore: sync lark-doc skill from online-doc#1701
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:
📝 WalkthroughWalkthroughThis PR updates ChangesLark-doc skill documentation update
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 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 |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1701 +/- ##
==========================================
- Coverage 74.52% 74.40% -0.13%
==========================================
Files 851 853 +2
Lines 87155 88311 +1156
==========================================
+ Hits 64952 65704 +752
- Misses 17231 17544 +313
- Partials 4972 5063 +91 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
🚀 PR Preview Install Guide🧰 CLI updatenpm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@7e696c1b6ba3dc4fd64ce7a84daba233684252a1🧩 Skill updatenpx skills add larksuite/cli#chore/sync-lark-doc-from-online-doc -y -g |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
skills/lark-doc/references/lark-doc-update.md (1)
17-27: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winPotential documentation gap:
--reference-mapparameter removal.The parameter table at Lines 21-23 adds
--api-versionbut removes the previously documented--reference-maprow. However, the upstream code (shortcuts/doc/docs_update_v2.go:16-65) still registers and validates this flag as a structured input for external payload/reference mapping scenarios.If
--reference-mapis intentionally hidden from the main reference, consider adding it to an advanced section or the update workflow document. Otherwise, users withreference_mapneeds will have no documentation discovery path.📋 Suggested documentation recovery
Add a note in the "典型工作流" or "最佳实践" section, or restore
--reference-mapas a hidden/advanced table row:| `--reference-map` | 否 | 结构化 `reference_map` JSON 对象;当 `--content` 使用正文外部载荷 / 引用映射时与内容一起传给服务。支持直接 JSON、`@reference-map.json`(相对路径)或 `-` 从 stdin 读取 |🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/lark-doc/references/lark-doc-update.md` around lines 17 - 27, The parameter reference in lark-doc-update.md drops the documented `--reference-map` option even though `docs_update_v2.go` still supports and validates it; restore it in the main parameter table or add it to an advanced/hidden section. Update the documentation around the `docs +fetch` / `--content` workflow to mention `--reference-map` usage, especially for structured reference payloads, so users can discover and use it consistently.skills/lark-doc/scripts/count_chars.py (2)
39-51: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winAdd timeout to
subprocess.runand validatedoc_idformat.The
subprocess.runcall lacks a timeout, risking indefinite hangs iflark-clistalls. Also,doc_idis interpolated into the URL path without format validation; whileshell=Falseprevents command injection (the S603/BLE001 warnings are false positives here), a malformeddoc_idcould produce an invalid API path.def fetch_raw_content(doc_id, identity): + # Basic doc_id format validation + if not re.fullmatch(r'[A-Za-z0-9_-]+', doc_id): + sys.exit(f"Invalid document_id format: {doc_id}") cmd = ["lark-cli", "api", "GET", f"/open-apis/docx/v1/documents/{doc_id}/raw_content", "--as", identity] try: - out = subprocess.run(cmd, capture_output=True, text=True) + out = subprocess.run(cmd, capture_output=True, text=True, timeout=60) except FileNotFoundError:🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/lark-doc/scripts/count_chars.py` around lines 39 - 51, In fetch_raw_content, add a timeout to the subprocess.run invocation so lark-cli cannot hang indefinitely, and validate doc_id before building the /open-apis/docx/v1/documents/{doc_id}/raw_content path to ensure it matches the expected document ID format. Keep the shell=False usage unchanged, and update the error handling in fetch_raw_content to surface timeout or validation failures clearly alongside the existing FileNotFoundError and returncode checks.
94-133: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUse
withstatement for file I/O and add min/max validation.Line 108 opens a file without explicit close. While CPython will eventually garbage-collect the handle, explicit resource management is cleaner. Also, if both
--minand--maxare provided with--min > --max, the script silently accepts inconsistent bounds.elif args.file: - try: - text = open(args.file, encoding="utf-8").read() - except OSError as e: - sys.exit(f"读取文件失败: {e}") + try: + with open(args.file, encoding="utf-8") as f: + text = f.read() + except OSError as e: + sys.exit(f"读取文件失败: {e}")And add validation after approx handling:
mn, mx = args.min, args.max if args.approx is not None: mn, mx = round(args.approx * 0.9), round(args.approx * 1.1) + if mn is not None and mx is not None and mn > mx: + ap.error(f"--min ({mn}) cannot be greater than --max ({mx})")🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/lark-doc/scripts/count_chars.py` around lines 94 - 133, In main(), replace the raw open(args.file, ...) read with a context-managed file read so the handle is always closed, and add bounds validation after the approx expansion logic. Specifically, in the argument handling around fetch_raw_content(), args.file, and the mn/mx assignment, ensure that when both --min and --max are set the script rejects cases where min is greater than max, including when values come from --approx, by calling ap.error() with a clear message before count() and judge() run.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills/lark-doc/references/style/lark-doc-style.md`:
- Around line 35-44: The numbering guidance in lark-doc-style.md is internally
inconsistent: the “一、→(一)→ 1.→(1)” example conflicts with the “all-Chinese”
label, and the “阿拉伯小数” rule conflicts with the mixed examples. In the section on
numbering and hierarchy, update the wording to use one clear rule in
lark-doc-style.md: either explicitly permit the mixed Chinese-Arabic hierarchy
with the matching examples, or remove the mixed examples and keep only pure
Chinese or pure Arabic schemes; make the prohibition and examples in the “编号与层级”
section consistent.
---
Nitpick comments:
In `@skills/lark-doc/references/lark-doc-update.md`:
- Around line 17-27: The parameter reference in lark-doc-update.md drops the
documented `--reference-map` option even though `docs_update_v2.go` still
supports and validates it; restore it in the main parameter table or add it to
an advanced/hidden section. Update the documentation around the `docs +fetch` /
`--content` workflow to mention `--reference-map` usage, especially for
structured reference payloads, so users can discover and use it consistently.
In `@skills/lark-doc/scripts/count_chars.py`:
- Around line 39-51: In fetch_raw_content, add a timeout to the subprocess.run
invocation so lark-cli cannot hang indefinitely, and validate doc_id before
building the /open-apis/docx/v1/documents/{doc_id}/raw_content path to ensure it
matches the expected document ID format. Keep the shell=False usage unchanged,
and update the error handling in fetch_raw_content to surface timeout or
validation failures clearly alongside the existing FileNotFoundError and
returncode checks.
- Around line 94-133: In main(), replace the raw open(args.file, ...) read with
a context-managed file read so the handle is always closed, and add bounds
validation after the approx expansion logic. Specifically, in the argument
handling around fetch_raw_content(), args.file, and the mn/mx assignment, ensure
that when both --min and --max are set the script rejects cases where min is
greater than max, including when values come from --approx, by calling
ap.error() with a clear message before count() and judge() run.
🪄 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: aea33bf3-b995-4b23-9737-3e3ffe704fdc
📒 Files selected for processing (12)
skills/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-whiteboard.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-doc/scripts/count_chars.py
88a64ac to
ba05c91
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
skills/lark-doc/scripts/count_chars.py (1)
39-51: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winValidate
doc_idbefore passing to subprocess.
doc_idflows directly from user input (--doc) into asubprocess.runcommand list. While this is a CLI tool (not a network service), add a format validation (e.g., alphanumeric, expected length/pattern) to fail fast on malformed input and reduce command injection surface.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/lark-doc/scripts/count_chars.py` around lines 39 - 51, Validate the user-supplied doc_id before it reaches fetch_raw_content’s subprocess.run command list, since --doc flows directly into the lark-cli invocation. Add a fast-fail format check in fetch_raw_content (or the CLI argument parsing path) using the existing doc_id value, enforcing the expected document ID pattern/length and exiting with a clear message on malformed input. Keep the subprocess call unchanged, but only after doc_id passes validation.skills/lark-doc/references/style/lark-doc-create-workflow.md (4)
25-31: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winCommand prefix inconsistency extends to
block_insert_after.Line 28 presents
block_insert_afteras a bare command without anylark-cli docsprefix, while line 10 instructs to runlark-cli docscommands. Ifblock_insert_afteris a subcommand oflark-cli docs, it should be written aslark-cli docs block_insert_afterordocs block_insert_afterfor consistency with the convention established in line 10.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/lark-doc/references/style/lark-doc-create-workflow.md` around lines 25 - 31, This section has a command prefix inconsistency: block_insert_after is shown without the lark-cli docs prefix, which conflicts with the command style used elsewhere. Update the workflow text in lark-doc-create-workflow.md so the block_insert_after usage matches the same invocation convention as docs +create, using the proper full subcommand form consistently throughout the instructions.
49-57: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueClarify working directory for
count_chars.pyinvocation.Line 54 uses
uv run scripts/count_chars.pywith the note that the script is at "lark-doc skill 根的scripts/下". Since this workflow document is inreferences/style/, a user running from this file's directory would need../../scripts/count_chars.py. Consider either:
- Adding a
cdinstruction to the skill root before command examples- Using
../../scripts/count_chars.pyin the example- Adding a note that commands assume the skill root as working directory
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/lark-doc/references/style/lark-doc-create-workflow.md` around lines 49 - 57, The `count_chars.py` invocation in the “字数校验” step is ambiguous because the workflow lives under `references/style/` but the command assumes the skill root as the working directory. Clarify this by updating the instruction around `uv run scripts/count_chars.py` to either explicitly say to run from the lark-doc skill root, or adjust the path to the script accordingly, so users can reliably locate and execute the command.
10-10: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUnify CLI command prefix convention.
Line 10 uses
lark-cli docswhile lines 25, 28, 35, and 47 usedocs +create,block_insert_after, anddocs +fetchwithout thelark-cliprefix. Pick one convention and apply it throughout to avoid confusion about whetherlark-cliis required.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/lark-doc/references/style/lark-doc-create-workflow.md` at line 10, The workflow doc uses inconsistent CLI prefixing between the Execute step and later command examples; standardize the command convention across the document by updating the affected markdown sections that mention docs actions, and make the same choice consistently in the steps around the symbols `lark-cli docs`, `docs +create`, `block_insert_after`, and `docs +fetch` so readers can tell whether `lark-cli` is required everywhere.
62-64: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winInconsistent path specification for
lark-doc-xml.md.Line 64 lists "
lark-doc-xml.md路径" without a relative path, while line 47 and line 64'slark-doc-whiteboard.mduse../lark-doc-whiteboard.md. Iflark-doc-xml.mdis in the samereferences/directory aslark-doc-whiteboard.md, specify../lark-doc-xml.mdfor consistency and correct resolution from this file's location.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/lark-doc/references/style/lark-doc-create-workflow.md` around lines 62 - 64, The SVG SubAgent requirements in the workflow doc use an अस्पष्ट reference for lark-doc-xml.md; update the instruction text near the SVG SubAgent section to use the same relative-path style as lark-doc-whiteboard.md, specifically referencing lark-doc-xml.md with a path relative to this document. Keep the rest of the SVG SubAgent contract unchanged, including the existing symbols lark-doc-whiteboard.md and “SVG 设计 Workflow”.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills/lark-doc/scripts/count_chars.py`:
- Around line 76-77: The word-count regex in count_chars.py is too broad because
the en_words pattern includes non-letter symbols like × and ÷ via the À-ÿ range.
Update the regex used in the en_words calculation to exclude those code points,
either by narrowing the allowed Unicode ranges or explicitly removing the
offending characters, while keeping the rest of the count_chars logic unchanged.
- Around line 104-114: The `count_chars.py` CLI file-loading path in the
`args.file` branch still opens files directly and accepts unvalidated paths.
Update the `elif args.file` handling to use a context manager in the file-read
logic so the handle is always closed, and add path validation/normalization
before reading to block traversal or absolute-path access (for example by
constraining inputs to an allowed base or reusing any existing `@file`
restriction helper). Keep the change localized around the `fetch_raw_content`,
`args.file`, and `sys.stdin` branches.
---
Nitpick comments:
In `@skills/lark-doc/references/style/lark-doc-create-workflow.md`:
- Around line 25-31: This section has a command prefix inconsistency:
block_insert_after is shown without the lark-cli docs prefix, which conflicts
with the command style used elsewhere. Update the workflow text in
lark-doc-create-workflow.md so the block_insert_after usage matches the same
invocation convention as docs +create, using the proper full subcommand form
consistently throughout the instructions.
- Around line 49-57: The `count_chars.py` invocation in the “字数校验” step is
ambiguous because the workflow lives under `references/style/` but the command
assumes the skill root as the working directory. Clarify this by updating the
instruction around `uv run scripts/count_chars.py` to either explicitly say to
run from the lark-doc skill root, or adjust the path to the script accordingly,
so users can reliably locate and execute the command.
- Line 10: The workflow doc uses inconsistent CLI prefixing between the Execute
step and later command examples; standardize the command convention across the
document by updating the affected markdown sections that mention docs actions,
and make the same choice consistently in the steps around the symbols `lark-cli
docs`, `docs +create`, `block_insert_after`, and `docs +fetch` so readers can
tell whether `lark-cli` is required everywhere.
- Around line 62-64: The SVG SubAgent requirements in the workflow doc use an
अस्पष्ट reference for lark-doc-xml.md; update the instruction text near the SVG
SubAgent section to use the same relative-path style as lark-doc-whiteboard.md,
specifically referencing lark-doc-xml.md with a path relative to this document.
Keep the rest of the SVG SubAgent contract unchanged, including the existing
symbols lark-doc-whiteboard.md and “SVG 设计 Workflow”.
In `@skills/lark-doc/scripts/count_chars.py`:
- Around line 39-51: Validate the user-supplied doc_id before it reaches
fetch_raw_content’s subprocess.run command list, since --doc flows directly into
the lark-cli invocation. Add a fast-fail format check in fetch_raw_content (or
the CLI argument parsing path) using the existing doc_id value, enforcing the
expected document ID pattern/length and exiting with a clear message on
malformed input. Keep the subprocess call unchanged, but only after doc_id
passes validation.
🪄 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: d95b1c23-38cd-4311-90ec-21c24b44e25d
📒 Files selected for processing (8)
skills/lark-doc/SKILL.mdskills/lark-doc/references/lark-doc-create.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-doc/scripts/count_chars.py
✅ Files skipped from review due to trivial changes (1)
- skills/lark-doc/references/lark-doc-update.md
cfa7f28 to
e5b9f7c
Compare
There was a problem hiding this comment.
🧹 Nitpick comments (2)
skills/lark-doc/references/lark-doc-word-stat.md (1)
41-43: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winDefine the
上下浮动rule.Step 1 accepts requests like
上下浮动, but the normalization rule only coversx 字左右. Add an explicit conversion for that case so the target interval is deterministic.Proposed wording
-1. 把要求归一成目标区间:`>x`→`[x, +∞)`;`<y`→`(-∞, y]`;`x-y`→`[x, y]`;`x 字左右`→`[round(0.9x), round(1.1x)]` +1. 把要求归一成目标区间:`>x`→`[x, +∞)`;`<y`→`(-∞, y]`;`x-y`→`[x, y]`;`x 字左右` / `上下浮动`→`[round(0.9x), round(1.1x)]`🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/lark-doc/references/lark-doc-word-stat.md` around lines 41 - 43, The word-count normalization in the reference doc is missing an explicit rule for “上下浮动,” even though Step 1 accepts it. Update the normalization guidance around the word-count flow so the `上下浮动` case is converted into a deterministic target interval, alongside the existing `x 字左右` handling, using the same normalization section in `lark-doc-word-stat.md`.skills/lark-doc/references/style/lark-doc-update-workflow.md (1)
8-8: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winClarify the SubAgent split.
Line 8 reads as if all board rendering is offloaded, but Line 53 keeps Mermaid insertion on the main agent. Narrow this to SVG / existing-board work so the workflow doesn't read as contradictory.
Proposed wording
-2. **Execute(执行)** — 由主 Agent 自己运行 `lark-cli docs` 命令推进改写;仅画板渲染按需隔离到 SubAgent(见步骤二) +2. **Execute(执行)** — 由主 Agent 自己运行 `lark-cli docs` 命令推进改写;仅 SVG 画板 / 已有画板更新按需隔离到 SubAgent(见步骤二)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/lark-doc/references/style/lark-doc-update-workflow.md` at line 8, The workflow text is ambiguous about what the SubAgent handles, since it sounds like all board rendering is delegated while Mermaid insertion still stays with the main agent. Update the wording in the step that mentions “Execute(执行)” and the related board-rendering guidance so it clearly limits SubAgent use to SVG / existing-board work, while keeping Mermaid insertion on the main Agent, using the existing “Execute(执行)” and “步骤二” references to keep the split consistent.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@skills/lark-doc/references/lark-doc-word-stat.md`:
- Around line 41-43: The word-count normalization in the reference doc is
missing an explicit rule for “上下浮动,” even though Step 1 accepts it. Update the
normalization guidance around the word-count flow so the `上下浮动` case is
converted into a deterministic target interval, alongside the existing `x 字左右`
handling, using the same normalization section in `lark-doc-word-stat.md`.
In `@skills/lark-doc/references/style/lark-doc-update-workflow.md`:
- Line 8: The workflow text is ambiguous about what the SubAgent handles, since
it sounds like all board rendering is delegated while Mermaid insertion still
stays with the main agent. Update the wording in the step that mentions
“Execute(执行)” and the related board-rendering guidance so it clearly limits
SubAgent use to SVG / existing-board work, while keeping Mermaid insertion on
the main Agent, using the existing “Execute(执行)” and “步骤二” references to keep
the split consistent.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 956f1e8d-6057-4b74-b583-d066ce4caabf
📒 Files selected for processing (3)
skills/lark-doc/references/lark-doc-word-stat.mdskills/lark-doc/references/style/lark-doc-create-workflow.mdskills/lark-doc/references/style/lark-doc-update-workflow.md
🚧 Files skipped from review as they are similar to previous changes (1)
- skills/lark-doc/references/style/lark-doc-create-workflow.md
522288b to
65f9260
Compare
Sync the lark-doc skill docs with online guidance. Refine create/update workflow checks, word-count validation, whiteboard routing, and style rules. Co-authored-by: fangshuyu-768 <shuyufang768@outlook.com>
1ba681e to
978edbc
Compare
Summary
Sync the open-source
lark-docskill from the latest specialonline-docpackage, converting it back to thelark-doclayout used by this repository.Changes
skills/lark-docreferences and workflows from theonline-docsource package.lark-sharedprerequisite/reference lines where applicable for the open-source CLI skill.skills/lark-doc/scripts/doc_word_stat.py.Test Plan
node scripts/skill-format-check/index.js skillsgit diff --checkPYTHONPYCACHEPREFIX=/tmp/larksuite-cli-pycache python3 -m py_compile skills/lark-doc/scripts/doc_word_stat.pyprintf '你好,world 123!\n' | python3 skills/lark-doc/scripts/doc_word_stat.py --protocol xml --prettyskills/lark-doc/**/*.mdmake unit-test(fails ininternal/qualitygate/publiccontentandinternal/qualitygate/ruleswithTempDir RemoveAll cleanup: .../.git/ai: directory not empty; retrying those packages shows the same cleanup failure)Related Issues
Summary by CodeRabbit