面向 Agent 的 Word 报告导出工具
| 
| 
|
| 现金流风险简报 | 运营执行手册 | 市场进入评估 |
| 
| 
| 
|
## 安装
### 1. 安装 CLI
```bash
npm install -g @dztabel/docxkit
docx-kit --version
```
出现类似输出代表 CLI 安装成功：
```text
docx-kit 0.1.62 (cli-contract 0.2)
```
### 2. 安装 Agent skill（二选一）
#### 2.1 Codex
```bash
node -e "const fs=require('fs'),os=require('os'),path=require('path'),cp=require('child_process');const root=cp.execSync('npm root -g',{encoding:'utf8'}).trim();const src=path.join(root,'@dztabel','docxkit','skills','docxkit');const dest=path.join(os.homedir(),'.agents','skills','docxkit');fs.rmSync(dest,{recursive:true,force:true});fs.mkdirSync(path.dirname(dest),{recursive:true});fs.cpSync(src,dest,{recursive:true});console.log('Codex skill installed');"
```
检查 Codex skill 是否安装成功，在终端中输入：
```bash
node -e "const fs=require('fs'),os=require('os'),path=require('path');const p=path.join(os.homedir(),'.agents','skills','docxkit','SKILL.md');if(!fs.existsSync(p))process.exit(1);console.log('Codex skill installed');"
```
出现以下输出代表成功：
```text
Codex skill installed
```
打开 Codex 后输入 `$docxkit`。能按 `Tab` 选中该 skill，代表可用。若未出现，按 `Cmd+K` / `Ctrl+K` 选择 `Force Reload Skills`，或重新打开 Codex。
#### 2.2 Claude Code
```bash
node -e "const fs=require('fs'),os=require('os'),path=require('path'),cp=require('child_process');const root=cp.execSync('npm root -g',{encoding:'utf8'}).trim();const src=path.join(root,'@dztabel','docxkit','skills','docxkit');const dest=path.join(os.homedir(),'.claude','skills','docxkit');fs.rmSync(dest,{recursive:true,force:true});fs.mkdirSync(path.dirname(dest),{recursive:true});fs.cpSync(src,dest,{recursive:true});console.log('Claude Code skill installed');"
```
检查 Claude Code skill 是否安装成功，在终端中输入：
```bash
node -e "const fs=require('fs'),os=require('os'),path=require('path');const p=path.join(os.homedir(),'.claude','skills','docxkit','SKILL.md');if(!fs.existsSync(p))process.exit(1);console.log('Claude Code skill installed');"
```
出现以下输出代表成功：
```text
Claude Code skill installed
```
打开 Claude Code 后输入 `/docxkit`。能选中该 skill，代表可用。若未出现，输入 `/reload-skills` 后重试；旧版本 Claude Code 可重新打开窗口。
## 快速开始
### 1. 用户带资料生成 Word 报告
```text
$docxkit 请读取我上传的 Excel、PDF 和会议纪要，整理成一份正式项目复盘报告并导出 Word。
/docxkit 请读取我上传的 Excel、PDF 和会议纪要，整理成一份正式项目复盘报告并导出 Word。
```
### 2. 用户只给目标，Agent 自行调研
```text
$docxkit 请调研国内储能行业最新进展，整理成行业研究报告并导出 Word。
/docxkit 请调研国内储能行业最新进展，整理成行业研究报告并导出 Word。
```
### 3. 用户已有草稿，Agent 重写成可交付报告
```text
$docxkit 请把这份散乱的草稿改写成结构清晰的正式分析报告并导出 Word。
/docxkit 请把这份散乱的草稿改写成结构清晰的正式分析报告并导出 Word。
```
### 4. 用户基于反馈迭代报告
```text
$docxkit 请把刚才生成的报告压缩到 8 页，第二章改成更适合管理层阅读的版本，并重新导出 Word。
/docxkit 请把刚才生成的报告压缩到 8 页，第二章改成更适合管理层阅读的版本，并重新导出 Word。
```
Agent 会完成资料读取、调研、正文组织、格式约束和 Word 导出。
## 技术细节
Agent 会自动把资料整理成 DocxKit 可处理的中间内容，并调用：
```bash
docx-kit build prepared-report.md --out ./report --filename 项目复盘报告.docx
docx-kit qa ./report/项目复盘报告.docx --report-json ./report/report.json --out ./report/qa
```
DocxKit 输出：
```text
report/项目复盘报告.docx
report/report.json
report/build-result.json
report/qa/qa-result.json
```
生成的 `.docx` 默认不内嵌字体：每个模版都在 fontTable 中声明规范字体名与跨平台替代链，Word/WPS 会优先使用目标电脑已安装的字体并保持文档可编辑。若收件人环境缺少规范字体，用 `--embed-fonts` 显式嵌入本机可合法嵌入的字体子集。
内置三个模版：`executive-cn-docx`（默认，楷体商务风）、`executive-cn-song-docx`（宋体正文 + 不加粗黑体标题，正式规范风）和 `executive-cn-official-docx`（方正小标宋标题、楷体_GB2312 副标题、仿宋_GB2312 三号正文、小四号表格及表题、二三级标题加粗、无页眉、固定 30 磅行距，禁止 callout）。公文范式默认在首页顶部直接排列标题、副标题和正文，不生成独立封面与目录；只有明确需要时才设置 `document_mode: report`。在 Markdown frontmatter 中用 `template:` 显式切换。
支持公式（LaTeX 块级与行内，Word 原生可编辑）、表/图/公式/来源四类可点击交叉引用、图目录与表目录；构建内置内容质量门禁（悬空引用等 error 级问题会使构建失败，详见输出 JSON 的 checks 字段）。
## 排障
当前公开测试版支持 macOS Apple Silicon 与 Windows x64。
如果全局 npm 安装跳过了 optional dependencies，显式安装对应平台包：
```bash
npm install -g @dztabel/docxkit @dztabel/docxkit-darwin-arm64
```
构建失败时，提交 issue 请附：
- `docx-kit --version`
- `report/build-result.json`
- 可复现问题的最小 `content.md`
## 仓库范围
本公开仓库包含 npm wrapper 元数据、命令 shim、公开 skills、文档和轻量预览资产。
渲染器源码、私有模板、schemas、视觉回归样例和平台二进制不包含在本仓库中。平台二进制通过 npm 平台包分发。
## 许可
DocxKit 以专有 CLI 二进制形式通过 npm 分发。本仓库提供用于安装和使用 CLI 的公开 wrapper、skills 和文档。