hasharmujahid/dsh-office-docs

office-docs

test

一个 DSH 技能，让 Word、Excel 和 PowerPoint 交付物变得可靠：构建它们、在修订模式下编辑它们、验证它们，并在交付前查看结果。

它的存在是因为“让模型凭记忆编写 OOXML”的失败模式不是崩溃——而是一个能打开但存在细微错误的文件：A4 而不是 Letter、在别处会塌陷的表格、渲染为未更改文本的删除、在审阅者“全部拒绝”后仍然存活的编辑。

这里有什么

office-docs/
├── SKILL.md                       # 路由、内部规则、故障排除（由 DSH 加载）
├── reference/
│   ├── docx.md                    # python-docx + OOXML 指南，经过测试的配方
│   ├── xlsx.md                    # openpyxl：公式、图表、数字格式
│   └── pptx.md                    # python-pptx：布局、适配、图表
└── scripts/
├── bootstrap.py               # 创建共享 venv（幂等，--check/--force）
├── office.py                  # info · dump · convert · render · new · validate
├── md2docx.py                 # new 使用的 Markdown -> .docx 渲染器
├── docx_edit.py               # merge-runs · find-replace --track · comment · accept · reject
├── smoke_test.py              # 对真实工具链的 27 项端到端检查
└── verify_reference_code.py   # 执行 reference/ 中的每个完整示例

安装

./install.sh                      # -> ~/.dsh/skills/office-docs + 共享 venv
./install.sh --link               # 符号链接，用于就地编辑此副本
./install.sh --project ~/work/x   # -> ~/work/x/.dsh/skills/office-docs

DSH 在 //SKILL.md 处发现技能；同级的 scripts/ 和 reference/ 目录作为技能的资源随它一起移动。可识别的根目录有 /.dsh/skills、/.agents/skills、$DSH_HOME/skills 和 $DSH_AGENTS_HOME/skills。

使用

PY=~/.dsh/office-docs/venv/bin/python
SKILL=~/.dsh/skills/office-docs

$PY "$SKILL/scripts/smoke_test.py"                     # 工具链是否健康？

Markdown -> Word
$PY "$SKILL/scripts/office.py" new report.md --title "Q3 Review" --toc --page-numbers

以审阅者的名义对现有文档进行红线标注
$PY "$SKILL/scripts/docx_edit.py" find-replace in.docx out.docx \
--old "ACME" --new "Acme Corporation" --author "A. Reviewer"
$PY "$SKILL/scripts/office.py" validate out.docx --original in.docx --author "A. Reviewer"

在交付前查看结果
$PY "$SKILL/scripts/office.py" render out.docx --prefix /tmp/page --dpi 100

它如何保持可靠

- 一个环境，固定主版本。 bootstrap.py 使用稳定主版本的
python-docx、openpyxl、python-pptx、lxml 和 pillow 构建 ~/.dsh/office-docs/venv。一个浮动
安装才是文档流水线在写好后六个月才出问题的地方。
- 验证是一条命令，不是一种期望。 office.py validate 会检查包完整性、每一个 XML
部件、公式错误字面量、批注交叉链接、修订一致性、某次编辑是否绕过了
修订跟踪，以及 LibreOffice 究竟能否打开该文件。
- 渲染闭合了回路。 office.py render 通过 LibreOffice 转换为 PDF，并用
poppler 栅格化，这样模型才能真正看到它生成的页面。
- 陷阱记录在它们会咬人的地方。 reference/ 中的每个模式都由
verify_reference_code.py 执行，因此文档不会悄悄腐烂。

要求

Python 3.9+（此处使用 3.14）· 一次性 pip install 需要网络访问 · LibreOffice
（libreoffice-writer、-calc、-impress）和 poppler-utils 用于转换、PDF 导出和
渲染。该技能会优雅降级：没有 LibreOffice 时，new、dump、find-replace、
comment 和 accept/reject 仍然可用。

Debian/Ubuntu
sudo apt-get install -y libreoffice-writer libreoffice-calc libreoffice-impress poppler-utils
macOS
brew install --cask libreoffice && brew install poppler

仓库布局

SKILL.md                       DSH 加载的文件
reference/{docx,xlsx,pptx}.md  格式指南；可执行示例
scripts/
bootstrap.py                 创建共享环境
office.py                    info · dump · convert · render · new · validate
md2docx.py                   Markdown -> .docx 渲染器
docx_edit.py                 修订跟踪、批注、接受/拒绝
smoke_test.py                27 项端到端检查
verify_reference_code.py     运行 reference/ 中的每个完整示例
install.sh                     安装到 DSH 技能根目录
CONTRIBUTING.md                不变量以及如何安全地修改此处

开发

CI 在安装了 LibreOffice 和 poppler 的 Python 3.9 和 3.12 上运行冒烟测试和参考代码
验证，因此只在某一台机器上有效的更改会在那里失败。在编辑 XML 处理之前，请参阅
CONTRIBUTING.md——其中列出的不变量每一条都源自一份悄悄出错的
文档。

许可证

MIT——见 LICENSE。

该设计参考了 anthropics/skills（专有，未
复制）：其 docx/xlsx/pptx 技能确立了工作流的形态。这里的每一行都是针对
python-docx、openpyxl、python-pptx 和 LibreOffice 的独立实现，因为
参考技术栈的依赖项（pandoc、npm docx、markitdown）在此环境中
并不存在。