内容
# InkPaw
> 一个为 AI 代理提供的小型、精致的 DOCX 工具包。模型编写内容；InkPaw 保持文档正确。
InkPaw 是一个为 AI 代理提供 Word 文档生成、编辑、验证和渲染的工具包。它提供了一个 MCP 服务器、一个与协议无关的渲染器和一个用于尝试完整代理工作流的本地 Web Playground。
设计原则很简单：**模型拥有内容和结构；确定性代码拥有编号、样式、引用、OOXML 正确性和输出验证。**
## 尝试 Playground
体验 InkPaw 的最快方式是使用本地实验性 Playground：
```bash
git clone https://github.com/syouro/InkPaw.git
cd InkPaw
npm install
npm run playground
```
打开 `http://127.0.0.1:8766`，输入与 OpenAI 兼容的基准 URL、模型名称和 API 密钥，然后要求代理创建文档。
Playground 显示流式推理和工具活动，渲染页面预览，支持后续编辑和模板，并提供 DOCX/PDF 下载。它默认绑定到 localhost，旨在进行本地评估，而不是直接公开部署。完整的页面预览需要 LibreOffice 和 poppler-utils。参见 [Playground 指南](docs/playground.md)。
### DeepSeek 支持
InkPaw 包括对 DeepSeek 思考模式代理循环的明确兼容性：它发送 `thinking` 控制，流式传输 `reasoning_content` 到单独的 UI 面板，并按照 DeepSeek API 的要求在工具调用继续中保留该推理。Playground 的推荐起始模型是 **`deepseek-v4-flash`**，它预填充了官方的 `https://api.deepseek.com` 端点。
参见 [DeepSeek 集成指南](docs/deepseek.md)，了解设置、协议详细信息和故障排除。
## 为什么选择 InkPaw？
大型语言模型可以编写强大的内容，但要求模型直接控制 Word 布局细节通常会导致编号损坏、样式漂移、引用无效或文档无法打开。InkPaw 通过持久结构化文档模型（`def` JSON）将这些问题分开：
- 代理创建标题、段落、表格、图像、方程式、脚注、评论和章节。
- InkPaw 生成编号、标题、交叉引用、目录、样式和 OOXML。
- 稳定的节点 ID 允许在代理回合之间进行精确查询、更新、移动和删除操作。
- 结构化验证问题包括位置、修复指导和权威示例，以进行自我纠正。
## 功能
- 结构化文档创建和 Markdown 导入。
- 节点级插入、更新、移动和删除，带有 SQLite 持久性。
- 自动编号、标题、交叉引用和静态或原生目录。
- 三层样式：预设 → 样式配置文件 → 文档覆盖。
- 表格跨度、页眉/页脚、脚注、评论、复选框、方程式、浮动图像和多个章节。
- DOCX、PDF 和每页 PNG 输出。
- 三层验证：OPC 完整性、ECMA-376 架构和 Word 兼容性检查。
- 通过 stdio 或无状态 Streamable HTTP 进行 MCP。
- HTTP Bearer 身份验证和可选的每个用户存储范围。
- 带有流式代理循环、MCP 工具、预览和下载的本地 BYOK Playground。
## 要求
- Node.js 18+
- npm
- LibreOffice Writer + Math，用于完整的测试套件和 PDF/PNG 预览
- 可选：poppler-utils，用于每页 PNG 转换
- 可选：xmllint + xsltproc，用于完整的 OOXML 架构验证
核心 DOCX 生成不需要 LibreOffice。
## MCP 快速入门
InkPaw 默认使用 stdio 传输启动：
```bash
npm start
```
示例 MCP 客户端配置：
```json
{
"mcpServers": {
"inkpaw": {
"command": "node",
"args": ["/absolute/path/to/InkPaw/src/server.js"]
}
}
}
```
### 流式 HTTP
```bash
npm run start:http
```
默认端点是 `http://127.0.0.1:8765/mcp`，需要 Bearer 身份验证。首次启动时，InkPaw 会创建 `data/mcp-token`；您也可以显式设置 `DOCX_MCP_TOKEN`。
### 仅渲染器
渲染器不依赖于 MCP 或 SQLite：
```bash
npm run demo
node src/docxUtil.js render examples/demo-report.js
```
## 验证
```bash
npm test
npm run validate -- path/to/file.docx
scripts/docx2png.sh path/to/file.docx
npm run visual
```
视觉基准依赖于 LibreOffice 和已安装的字体。仅在手动审查渲染的页面后更新它们。
## 架构
```text
MCP 客户端或本地 Playground
│
▼
MCP 传输（stdio / HTTP）
│
▼
服务 + 验证器 + SQLite 存储
│
▼
转换（编号 / 引用 / 标题）
│
▼
与协议无关的 DOCX 渲染器
│
▼
DOCX / PDF / PNG + 验证反馈
```
参见 [架构](docs/architecture.md)，了解模块边界和不变量。
## 仓库布局
```text
src/ 核心渲染器、MCP 服务器、服务、存储和验证
playground/ 实验性本地 Web 代理体验
scripts/ 启动、验证、渲染和视觉回归工具
test/ 单元测试和集成测试
presets/ 可重用的样式预设
schemas/ OOXML 验证资产
docs/ 架构、规范、兼容性和发布策略
```
## 文档
- [Playground](docs/playground.md)
- [DeepSeek 集成](docs/deepseek.md)
- [架构](docs/architecture.md)
- [文档节点规范](docs/docxUtil-spec.md)
- [查看器兼容性](docs/compatibility.md)
- [上游 docx 问题](docs/upstream-issues.md)
- [源快照和同步规则](SOURCE_SNAPSHOT.md)
- [开源发布政策](docs/open-source-release-policy.md)
- [贡献](CONTRIBUTING.md)
- [安全](SECURITY.md)
## 项目状态
核心 DOCX/MCP 工具包是主要项目。Playground 被标记为实验性，因为其 API 和接口可能会更改，其默认安全边界是 localhost。它已经过测试，但不是一个可以直接使用的多租户公共 SaaS 部署。
## 许可证
[MIT](LICENSE) 2026 syouro. 第三方通知列在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中。
