94 lines
4.1 KiB
Markdown
94 lines
4.1 KiB
Markdown
# 文档统计：总字数 / 总字符数
|
||
|
||
当用户需要统计 Docx / Wiki 文档的总字数或总字符数时，使用本 skill 附带脚本 `scripts/doc_word_stat.py`。统计口径以该脚本为准，不要改用其他方式自行计算，也不要只读取 simple 摘要后统计。
|
||
|
||
## 调用方式
|
||
|
||
在线文档使用 XML full 内容，并让脚本读取 `docs +fetch --format json` 的 envelope：
|
||
|
||
```bash
|
||
lark-cli docs +fetch --doc "$URL" --doc-format xml --detail full --format json \
|
||
| python3 skills/lark-doc/scripts/doc_word_stat.py --protocol xml --lark-json --pretty
|
||
```
|
||
|
||
`$URL` 可以是用户给出的 docx/wiki URL，也可以是可被 `docs +fetch` 解析的 token。
|
||
|
||
## 统计范围
|
||
|
||
先判断用户要求的是**整篇文档**还是**局部内容**：
|
||
|
||
- 整篇文档的总字数 / 总字符数：按上方「调用方式」抓取 `full` 内容后统计。
|
||
- 本次新增 / 替换 / 改写片段的字数：优先统计拟写内容本身；内容已写入文档时，只 fetch 对应 block / range 后统计。不得用整篇文档字数对比局部目标。
|
||
|
||
如需在自动化或回归验证中发现未覆盖块类型，追加严格参数：
|
||
|
||
```bash
|
||
lark-cli docs +fetch --doc "$URL" --doc-format xml --detail full --format json \
|
||
| python3 skills/lark-doc/scripts/doc_word_stat.py --protocol xml --lark-json --pretty --fail-on-unsupported --fail-on-unknown
|
||
```
|
||
|
||
## 如何读取结果
|
||
|
||
脚本输出 JSON。对用户汇报时默认只读两个核心字段：
|
||
|
||
- `word_count`：总字数。按语义单位统计汉字、英文单词/URL/code path、数字、中文标点；普通贴着英文的英文标点不计入，但独立 ASCII 符号、中文之间的 `/` 等以脚本结果为准。
|
||
- `char_count`：总字符数。统计汉字、英文字母、数字、中英文标点和脚本识别的可见符号；空格不计入。
|
||
|
||
其余字段用于排查或解释：
|
||
|
||
- `breakdown`：拆分统计来源，例如 `han_chars`、`english_words`、`digits`、`chinese_punctuations`。
|
||
- `unknown_blocks`：脚本遇到未知 XML/Markdown 块类型；通常表示需要扩展解析规则。
|
||
- `unsupported_blocks`：脚本识别到块类型，但当前无法可靠提取可见文本。
|
||
- `diagnostics.has_unknown` / `diagnostics.has_unsupported`：快速判断统计是否存在覆盖风险。
|
||
|
||
如果 `unknown_blocks` 或 `unsupported_blocks` 非空，回复用户时要说明“已统计可提取文本，但存在未覆盖块，结果可能偏低”，并列出对应块类型。为空时可直接给出结果。
|
||
|
||
## 字数遵循校验
|
||
|
||
当用户给了明确字数要求（写 N 字 / x-y 字 / x 字左右 / 上下浮动）时执行；没有明确字数要求则跳过。字数必须按本文流程用脚本统计，不要自己估。
|
||
|
||
1. 先按「统计范围」确认统计对象，再把要求归一成目标区间：`>x`→`[x+1, +∞)`；`<y`→`(-∞, y-1]`；`x-y`→`[x, y]`；`x 字左右`→`[round(0.9x), round(1.1x)]`
|
||
2. 按统计对象选择对应输入并调用脚本统计实际字数，读取输出里的 `word_count`
|
||
3. 对比 `word_count` 与目标区间：区间内即通过；低于下限 → 补充**实质内容**（非注水）；高于上限 → 删减冗余内容。改完重新统计
|
||
4. **最多 2 轮**。2 轮后仍不达标：停止，不得为达标而注水或删关键内容；如实汇报【目标区间 / 当前字数 / 差值与方向 / 已试 2 轮 / 未达原因】，**禁止谎称达标**
|
||
|
||
## 输出示例
|
||
|
||
输入正文等价于：`标题` + `一个苹果是 an apple。` 时，输出形态如下：
|
||
|
||
```json
|
||
{
|
||
"word_count": 10,
|
||
"char_count": 15,
|
||
"breakdown": {
|
||
"han_chars": 7,
|
||
"english_words": 2,
|
||
"number_words": 0,
|
||
"chinese_punctuations": 1,
|
||
"english_letters": 7,
|
||
"digits": 0,
|
||
"english_punctuations": 0,
|
||
"symbol_words": 0,
|
||
"symbol_chars": 0
|
||
},
|
||
"protocol": "xml",
|
||
"unknown_blocks": [],
|
||
"unsupported_blocks": [],
|
||
"diagnostics": {
|
||
"has_unknown": false,
|
||
"has_unsupported": false,
|
||
"types": {},
|
||
"unknown_types": {},
|
||
"unsupported_types": {},
|
||
"actions": {}
|
||
}
|
||
}
|
||
```
|
||
|
||
面向用户的回复可简化为：
|
||
|
||
```text
|
||
总字数：10
|
||
总字符数：15
|
||
```
|