dsh-docx-format 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Romebody
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,181 @@
1
- # Temporary Holding Version
1
+ # dsh-docx-format
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 让 DSH 生成的所有 `.docx` 自动符合《通用公文格式规范》。
4
+
5
+ 三层生效方式,任一层命中就够:
6
+
7
+ | 层 | 机制 | 作用 |
8
+ | --- | --- | --- |
9
+ | 提示词 | `systemPrompt.section`(order 3260) | 模型生成 docx 前就知道字体、字号、行距、缩进、页边距,直接照规矩排 |
10
+ | 工具 | `docx_format` | 模型可显式调用:`mode=check` 体检、`mode=apply` 规范化并写回 |
11
+ | 钩子 | `tools/result` 观察者 | 任何工具(含 `ops_bash`、技能脚本)产出 .docx 路径后,自动排队规范化 |
12
+
13
+ 真正的排版逻辑在 `lib/docxfmt.py`(python-docx),插件只负责调度进程。
14
+
15
+ ## 本版(v2)修的四件事
16
+
17
+ 1. **段前段后一律 0 磅,空行用空段落表达**
18
+ 所有段落 `w:spacing w:before="0" w:after="0"`(不再用 `beforeLines/afterLines`,也不再拿段前 58pt 冒充空行)。
19
+ 注意是**显式写 0**:以前的做法是把 `before/after` 删掉,Word 会继续继承 `docDefaults`/Normal 里的段后间距(模板里就有 `w:after="200"` = 10 磅),
20
+ 看起来“段前段后还是不是 0”。
21
+ 「空一行」现在是真的插入空段落:标题上空 2 行、标题下空 1 行、附件说明前 1 行、附件说明与落款之间 2 行、落款前 2 行、
22
+ 文件末尾 `附件1` 标记与其标题之间 1 行(标记本身上面不插空行);附件多条目(`1.`/`2.`)视为同一段,条目间不插空行。
23
+ 空段落本身同样段前段后 0、固定 29 磅,**且字体/字号/对齐/缩进必须与前后文一致**(等价于在 Word 里手工按回车继承出来的空行):
24
+ 标题上下的空行写成 方正小标宋简体 二号(22pt)、居中、无首行缩进;正文/附件/落款之间的空行写成 仿宋 三号(16pt)、两端对齐、`firstLineChars="200"`。
25
+ 实现写在 `_style_blank(par, cfg, kind)`(`kind` 为 `blank` / `blank_title`)里,字体落在段落标记 `w:pPr/w:rPr`,`w:sz` 写磅值×2。
26
+ 已有空段落会被复用,不够才补,多了才删;`check` 会把字体/字号/对齐/首行缩进不符的空行报成 `blank.mark`。
27
+ 2. **首行缩进用「字符」而不是磅;附件按 2 / 6 / 5 / 6 字符分段**
28
+ 正文写的是 OOXML `w:ind w:firstLineChars="200"`(2 字符),同时保留 `w:firstLine="640"` 作为不认识 `*Chars` 的阅读器兜底;
29
+ `check` 模式把 `firstLine` 有值但 `firstLineChars` 缺失的情况判为偏差。除首行缩进外,左/右/悬挂缩进一律 0。
30
+ 附件不走悬挂缩进(Word 在 `leftChars`+`hangingChars` 并存时把悬挂量加到**折行**上,与 OOXML 语义相反;
31
+ 纯磅值虽然几何正确,但缩进阶梯要靠段前段后和左缩进拼,跟“普通缩进全 0”的要求冲突),改成**真正的分段**:
32
+ 「附件:1.……」所在段落 `firstLineChars="200"`;该条目的折行续行单独成段、`firstLineChars="600"`(6 字符);
33
+ 多附件的「2.……」段落 `firstLineChars="500"`(5 字符),它的续行同样是 6 字符。
34
+ 折行点用 Word 实测:把待测段落单独存成临时文档,交给 Word/WPS 排版后用
35
+ `Range.Information(wdFirstCharacterLineNumber)` 读每个字符落在第几行,按实测边界拆段,
36
+ 所以拆出来的每一段在最终打印版面里都正好一行、互不重叠。拆完再体检一遍,幂等。
37
+ 探测段落只用磅值左缩进(`w:left`),不能写 `w:leftChars`:实测两者并存时 Word 会把
38
+ “6 字符”当成 30 磅,折行点偏后 2 个字,拆出来的续行会再折一次。
39
+ 版面坐标(Word 导 PDF 实测,左边距 76.5pt):首行 108.6pt = +2 字符、续行 / 6 字符 172.6pt、
40
+ `2.` 5 字符 156.6pt;`tools/smoke_attach_split.py` 会重新量一遍并断言每段正好一行。
41
+ 没有可调用的 Word/WPS 时退回 `attachSplit.mode="indent-only"` 的效果:只排 2/5 字符缩进、不拆段,
42
+ 并给出 `附件自动分段不可用` 的提示,折行留给使用者手工换行。
43
+ 条目文字短于 `attachSplit.minCharsToMeasure`(默认 20 字)时不可能折行,直接跳过、不启动 Word
44
+ (省 3~6 秒;短附件因此仍是 0.2 秒级的体检)。
45
+ 3. **请求文字白名单 + 默认不写落款**
46
+ - 白名单:看**当前会话最后一条用户消息**,命中 `skipRequestKeywords`(默认 `["实验报告"]`)就整条请求停用插件——
47
+ `tools/result` 钩子不排队、队列里的任务出队时再判一次、`docx_format` 直接返回 `skipped`(要强制处理传 `force=true`)。
48
+ 会话文字从 `sessions` 服务的 `session.deriveMessages()` 取,另有 `session/event` 缓存兜底。
49
+ - 落款:提示词明确「用户没要求署名/日期就不写落款」;引擎只格式化**文档里已经存在**的落款,绝不凭空新增。
50
+ 4. **表格单元格完全水平居中**
51
+ 表头 + 表内容**每一个单元格的每一段**都设 `w:jc w:val="center"`,并清掉单元格内的 `firstLine/firstLineChars/left/leftChars` 缩进,
52
+ 同时保持垂直居中、单倍行距。只居中表头不再算合规。
53
+
54
+ ## 规范内容
55
+
56
+ - 页面 A4,页边距 上 3.6cm / 下 3.0cm / 左 2.7cm / 右 2.7cm。
57
+ - 正文 仿宋 三号(16pt),两端对齐,首行缩进 2 字符(`w:firstLineChars="200"`),行距**固定值 29 磅**,段前段后 0。
58
+ - 大标题 方正小标宋简体 二号(22pt),居中;标题上方空 2 行、下方空 1 行——用**两个 / 一个空段落**表达。
59
+ - 一级标题 黑体三号、二级标题 楷体三号、三级标题 仿宋三号;编号「一、」「(一)」「1.」(全角点,无尾随空格)。
60
+ - 数字与字母一律 Times New Roman;破折号 `——` 用 TNR;小数点半角。
61
+ - 表格:标题 方正小标宋简体二号;表头 黑体小四、表内容 仿宋小四;**所有单元格段落水平+垂直居中**、单倍行距;外边框 1.5 磅、内边框 0.5 磅;行高最小值 0.7cm;表格居中无环绕;两字词语中间加两个半角空格(`姓 名`);表标题与表格之间插一行 0 行高、10.5pt 的空段。
62
+ - 图片:图片单独成段,**居中 + 无缩进(首行/左/右/悬挂全 0)+ 单倍行距**(`w:line="240" w:lineRule="auto"`,
63
+ 不走 29 磅固定值,避免图片被裁或行高被拉死),段前段后仍 0;判定规则 `par.lineSingle`。
64
+ - 页码:页脚居中 `— 1 —`,宋体四号(14pt),字段拆成 6 个 run,保证 Word / LibreOffice 都渲染成 `— N —`。
65
+ - 落款(**只在用户明确要求时才有**):正文后空两行(两个空段落)、右对齐;日期末尾补两个全角空格;署名与日期右边缘对齐(需盖章时署名居中于日期,`seal: true`)。
66
+ - 附件:`附件:1.xxx` 前空 1 行、下与落款空 2 行;缩进阶梯是 2 / 6 / 5 / 6 **字符**,靠真实分段实现:
67
+ 第一段 `firstLineChars="200"`、续行段 `600`、`2.…` 段 `500`、它的续行又是 `600`,左右悬挂全 0;
68
+ 折行点由 Word 排版实测(`wdFirstCharacterLineNumber`)后自动拆段,拆完每段在版面里正好一行;
69
+ 文件末尾 `附件1` 标记用黑体三号、无缩进、两端对齐、无冒号,其下与附件标题空 1 行。
70
+ - 幂等:重复 `apply` 完全无副作用,`check` 稳定为 0 偏差。
71
+
72
+ ## 用法
73
+
74
+ 命令行(脱离 DSH 也能用,只要装了 python-docx):
75
+
76
+ ```bash
77
+ python lib/docxfmt.py 报告.docx --mode check # 只体检,有偏差退出码 2
78
+ python lib/docxfmt.py 报告.docx --mode apply # 规范化并原子写回
79
+ python lib/docxfmt.py ./docs --mode apply --recursive # 批量
80
+ python lib/docxfmt.py 报告.docx --mode check --json # 机器可读报告
81
+ # 临时关掉内容白名单
82
+ python lib/docxfmt.py 报告.docx --mode apply --config '{"skipContentKeywords":[]}'
83
+ ```
84
+
85
+ 模型侧:
86
+
87
+ ```text
88
+ docx_format(path="C:/.../通知.docx", mode="apply")
89
+ docx_format(path="C:/.../通知.docx", mode="check")
90
+ docx_format(path="C:/.../公文目录", mode="apply", recursive=true)
91
+ docx_format(path="C:/.../通知.docx", mode="apply", force=true) # 无视请求文字白名单
92
+ ```
93
+
94
+ ### 读已有 docx:`docx_read`
95
+
96
+ ```text
97
+ docx_read(path="C:/.../毕业论文.docx") # 默认返回前 12000 字
98
+ docx_read(path="C:/.../毕业论文.docx", max_chars=60000)
99
+ docx_read(path="C:/.../毕业论文.docx", offset=12000) # 用上次返回的 next_offset 续读
100
+ ```
101
+
102
+ - 纯标准库实现(`lib/docx_read.py`),**不需要 python-docx、不需要联网、不改原文件**。
103
+ - 表格按 `单元格 | 单元格` 输出;返回 `total_chars / paragraphs / tables / next_offset / truncated / notes`。
104
+ - 只取正文文字:图片与脚注会以 `notes` 提示,不会静默吞掉。
105
+ - 给模型用的一等工具,就是为了替掉「read 工具报 binary file → pip install python-docx → 上网搜」这条死路。
106
+ 同理 `docx_format` 的返回值已统一过 `stripUndefined`,不会再触发 DSH 的 `value is not lossless JSON` 校验错误。
107
+
108
+ 命令行等价物:
109
+
110
+ ```bash
111
+ python lib/docx_read.py 毕业论文.docx --max-chars 2000
112
+ python lib/docx_read.py 毕业论文.docx --offset 2000 --json
113
+ ```
114
+
115
+ ## 安装
116
+
117
+ 1. 把 `dsh-docx-format` 整个目录放到任意位置(记为 `<PLUGIN_DIR>`)。
118
+ 2. profile 的 `package.json` 里 `dependencies` 增加 `"dsh-docx-format": "link:<PLUGIN_DIR>"`;
119
+ 已发布到 npm 时直接写版本号,如 `"dsh-docx-format": "^1.0.0"`。
120
+ 3. 同一个 `package.json` 的 `dsh.profile.bundles` 追加 `"dsh-docx-format"`。
121
+ 4. `node_modules/dsh-docx-format` 指向该目录(junction / pnpm link / npm install 均可)。
122
+ 5. 重启 dsh。
123
+
124
+ 环境要求:Node ≥ 20;Python 3.9+ 与 `python-docx`(DSH 自带运行时里已有)。
125
+ 装了 Word 或 WPS 时附件会自动按实测折行拆段;没有则退回 2/5 字符缩进、不拆段。
126
+
127
+ ## 配置
128
+
129
+ `cordis.patch.yml` 里是默认值:
130
+
131
+ | 键 | 默认 | 说明 |
132
+ | --- | --- | --- |
133
+ | `autoFormat` | `true` | 关闭后只保留工具与提示词 |
134
+ | `formatExisting` | `false` | 只处理插件加载后新写的文件;改 `true` 会连旧文件一起规范化 |
135
+ | `debounceMs` | `1200` | 结果钩子去抖 |
136
+ | `timeoutMs` | `120000` | 单次 python 超时 |
137
+ | `python` | `''` | 显式解释器;空则用 `DSH_DOCX_PYTHON` → `~/.dsh/dsh-runtimes/.../python.exe` → PATH |
138
+ | `skipPatterns` | `*格式要求*` 等 | 通配符匹配文件路径,命中不自动改(防止改到格式规范原件) |
139
+ | `skipRequestKeywords` | `['实验报告']` | **请求文字白名单**:会话最后一条用户消息含该词就整条请求停用插件 |
140
+ | `maxFilesPerTurn` | `8` | 一轮最多自动处理几个文件 |
141
+ | `prompt.enabled / order` | `true / 3260` | 提示词段开关与排序 |
142
+ | `defaults` | `{}` | 透传给 docxfmt.py,覆盖任何 DEFAULTS(如 `linePt`、`signature.seal`、`skipContentKeywords`) |
143
+
144
+ 引擎侧的附件相关键(写进 `defaults` 即可覆盖):
145
+
146
+ | 键 | 默认 | 说明 |
147
+ | --- | --- | --- |
148
+ | `attachLineIndentChars` | `2` | 「附件:1.」首行缩进字符数 |
149
+ | `attachContIndentChars` | `5` | 多附件「2.」首行缩进字符数 |
150
+ | `attachWrapIndentChars` | `6` | 折行续行段的首行缩进字符数 |
151
+ | `attachSplit.enabled` | `true` | 关掉就完全不碰附件分段 |
152
+ | `attachSplit.mode` | `word` | `word` = 用 Word/WPS 实测折行后自动拆段;`indent-only` = 只排 2/5 缩进、不拆段 |
153
+ | `attachSplit.maxRounds` | `12` | 长条目要拆成多段,最多迭代几轮 |
154
+ | `attachSplit.minCharsToMeasure` | `20` | 短于此长度的条目直接跳过,不启动 Word |
155
+
156
+ ## 目录
157
+
158
+ ```text
159
+ dsh-docx-format/
160
+ ├── index.js # 插件入口:工具 + 提示词 + 结果钩子 + 请求文字白名单
161
+ ├── lib/docxfmt.py # 排版引擎(apply/check,命令行可用)
162
+ ├── cordis.patch.yml # bundle patch(insert 一行配置)
163
+ ├── locale/zh.json # 展示文案
164
+ ├── locale/en.json
165
+ ├── icon.svg
166
+ └── package.json
167
+ ```
168
+
169
+ ## 排查
170
+
171
+ - 没生效:重启 dsh;再看日志里有没有 `[docx-format] ready python=... whitelist=[...]`。
172
+ - 明明该格式化却没动:看日志有没有 `whitelist hit 「实验报告」` / `skip ... 请求文字含...`;那是白名单在生效,用 `force=true` 绕过。
173
+ - `无法启动 python`:在配置里写死 `python` 路径。
174
+ - 旧文件不自动改:默认 `formatExisting: false`,用 `docx_format` 指定文件,或把它改成 `true`。
175
+ - 只想看问题:`docx_format(mode="check")` 打印逐条 `规则 x次数 where 当前 -> 期望`。
176
+ - 自测:`node tools/smoke_whitelist.mjs`(工作区根目录),`python tools/smoke_attach_split.py`
177
+ (附件 2/6/5/6 阶梯 + Word 实测每段一行 + 幂等),`python tools/smoke_blank_fmt.py`
178
+ (空段落字体/字号/对齐/缩进是否与前后文一致、幂等),`python tools/smoke_image_line.py`
179
+ (图片段居中/无缩进/单倍行距、正文仍是 29 磅、幂等),`python tools/verify_v2.py <docx> -v` 逐段核对 OOXML。
180
+ - 空行看起来“比手工回车矮/宽”:那是空段落没继承前后文字体。用 `docx_format(mode="check")` 看 `blank.mark`,
181
+ 它会给出“当前字体/字号/对齐 -> 期望值”,`apply` 会就地重写段落标记的 `w:pPr/w:rPr`。
@@ -0,0 +1,37 @@
1
+ # dsh-docx-format —— 公文格式规范化
2
+ # 安装方式(把 <PLUGIN_DIR> 换成插件所在目录):
3
+ # 1) profile 的 package.json dependencies 加 "dsh-docx-format": "link:<PLUGIN_DIR>"
4
+ # (已发布到 npm 时直接写版本号,如 "dsh-docx-format": "^1.0.0")
5
+ # 2) dsh.profile.bundles 追加 "dsh-docx-format"
6
+ # 3) 重启 dsh
7
+ - insert:
8
+ - id: docx-format
9
+ name: 'dsh-docx-format'
10
+ config:
11
+ # 自动规范化:任何工具结果里出现 .docx 路径都会排队处理
12
+ autoFormat: true
13
+ # 只处理插件加载之后新写的文件;true 则连旧文件一起改(有备份需求时改这个)
14
+ formatExisting: false
15
+ debounceMs: 1200
16
+ timeoutMs: 120000
17
+ # 显式指定 python;留空则自动找 .dsh 自带运行时
18
+ python: ''
19
+ skipPatterns:
20
+ - '*格式要求*'
21
+ - '*模板*'
22
+ - '~$*'
23
+ - '*/node_modules/*'
24
+ # 用户请求文字白名单:本条请求(会话最后一条用户消息)命中即整个插件停用
25
+ # 例:用户说“写个实验报告” → 不套公文格式、不自动改文件
26
+ skipRequestKeywords:
27
+ - '实验报告'
28
+ prompt:
29
+ enabled: true
30
+ order: 3260
31
+ tool:
32
+ enabled: true
33
+ # 覆盖 docxfmt.py 的 DEFAULTS,例如:
34
+ # defaults:
35
+ # linePt: 28
36
+ # signature:
37
+ # seal: true
package/icon.svg ADDED
@@ -0,0 +1,5 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
2
+ <path d="M6 3h8l4 4v14H6z"/>
3
+ <path d="M14 3v4h4"/>
4
+ <path d="M9 11h6M9 14h6M9 17h4"/>
5
+ </svg>