feat(doc): add document word statistics helper

[fangshuyu-768]

Summary

• add scripts/doc_word_stat.py to the lark-doc skill for Docx/XML and Markdown word/character statistics
• keep SKILL.md lean with a route for word/character count requests
• add references/lark-doc-word-stat.md with the online-doc workflow, output interpretation, diagnostics guidance, and a concrete JSON example

Validation

• python3 skills/lark-doc/scripts/doc_word_stat.py -h
• python3 -m py_compile skills/lark-doc/scripts/doc_word_stat.py
• node scripts/skill-format-check/index.js
• smoke-tested XML stdin and lark-cli JSON envelope inputs

Summary by CodeRabbit

• New Features

  • Added a standardized workflow to generate document total word and character counts from Lark Docs content.
  • Introduced structured results output including counts and diagnostic details for unsupported or unknown content types.

• Documentation

  • Added reference guidance specifying the official counting script to use and the recommended automation command.
  • Documented how to interpret the output fields and what to do when diagnostics indicate issues.

[coderabbitai]

Note

Reviews paused

It 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 reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new doc_word_stat.py CLI for parsing Lark Doc XML/Markdown, extracting visible text, and computing word/character statistics. The skill guide and reference doc now point users to that script and define the counting workflow.

Changes

Document Word Stat Script

Layer / File(s)	Summary
Data model and counting primitives skills/lark-doc/scripts/doc_word_stat.py	Defines dataclasses for blocks, segments, stats, and unknown blocks, plus character classification helpers and counting primitives.
Segment counting rules skills/lark-doc/scripts/doc_word_stat.py	Implements segment boundaries, token classification, and word/character aggregation for text, code, markers, and symbols.
Markdown and XML parsing skills/lark-doc/scripts/doc_word_stat.py	Adds Markdown parsing and inline cleanup, XML normalization, block-tree construction, and fallback content extraction.
Extraction registry and handlers skills/lark-doc/scripts/doc_word_stat.py	Implements the registry, handler protocol, and handlers for containers, lists, checkboxes, tasks, unknown, and unsupported blocks.
CLI and documentation skills/lark-doc/scripts/doc_word_stat.py, skills/lark-doc/SKILL.md, skills/lark-doc/references/lark-doc-word-stat.md	Adds CLI argument parsing, input loading, JSON-envelope handling, diagnostics, exit codes, and usage guidance in the skill and reference docs.

Estimated code review effort: 4 (Complex) | ~60 minutes

Suggested labels: domain/ccm

Suggested reviewers: SunPeiYang996, caojie0621

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: adding a document word statistics helper.
Description check	✅ Passed	The description covers summary and validation, but it doesn't follow the template's Changes, Test Plan, and Related Issues sections exactly.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/doc-word-stat-skill

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@840959834e6f03c12dd3e59529f9b7a9348e27fb

🧩 Skill update

npx skills add larksuite/cli#feat/doc-word-stat-skill -y -g

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.48%. Comparing base (775ee5a) to head (8409598).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1697      +/-   ##
==========================================
+ Coverage   74.47%   74.48%   +0.01%     
==========================================
  Files         849      850       +1     
  Lines       86631    86703      +72     
==========================================
+ Hits        64517    64583      +66     
- Misses      17172    17175       +3     
- Partials     4942     4945       +3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@skills/lark-doc/scripts/doc_word_stat.py`:
- Around line 1088-1090: The `--lark-json` handling in `doc_word_stat.py` is
assuming a fixed envelope shape and will crash with opaque parsing/key errors
when the payload is malformed or the content key is different. Update the
`args.lark_json` branch to validate the decoded object before reading
`envelope["data"]["document"]["content"]`, and surface a clear user-facing error
when the JSON is invalid or missing the expected keys. Keep the fix scoped to
the `json.loads`/envelope lookup path so the `source` assignment only proceeds
when the payload matches the expected lark-cli structure.
- Around line 629-639: The parse_xml function currently uses
xml.etree.ElementTree.fromstring on input that can come from stdin, files, or
docs +fetch, so harden this untrusted XML path by switching parse_xml to
defusedxml.ElementTree (including the fragment fallback) or add explicit
input/entity limits and trusted-input documentation. Update the XML parsing
logic in parse_xml and any related ET.parse/fromstring usage so the parser
cannot be abused with hostile XML content.

🪄 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: a75c62d1-6608-4cbc-aa1b-37df334bcbde

📥 Commits

Reviewing files that changed from the base of the PR and between 775ee5a and c6feb21.

📒 Files selected for processing (2)

• skills/lark-doc/SKILL.md
• skills/lark-doc/scripts/doc_word_stat.py

[fangshuyu-768]

Addressed the two CodeRabbit findings in baccac8:

• Hardened --lark-json handling: the script now validates the lark-cli JSON envelope and returns clear error: messages for malformed JSON or missing data.document.content.
• Hardened XML parsing: parse_xml now rejects oversized XML and DOCTYPE/ENTITY declarations before ElementTree parsing, including the fragment fallback path.

Validation run locally:

• python3 -m py_compile skills/lark-doc/scripts/doc_word_stat.py
• valid and invalid --lark-json smoke tests
• XML DOCTYPE/entity rejection smoke test
• node scripts/skill-format-check/index.js
• PUBLIC_CONTENT_METADATA=.tmp/quality-gate/public-content-metadata.json make quality-gate