WordCraft（文档写作）

在智能体会话中起草、排版并交付可编辑的 Word 文档。保留章节结构、原生表格和页码，交付前重新打开核对。

版本：0.1.0-dev.20261019.1 · 许可证：Apache-2.0 · 技能：16 个 · MCP 服务：1 个

English · 安装 · 快速开始 · 项目结构

项目定位

WordCraft 面向需要直接得到可编辑 Word 文档的用户，而不是一段 Markdown 或纯文本。它先收集并核对事实，再建立章节与字段结构，用原生标题、表格、页码和页眉页脚完成排版，最后重新打开文件检查读者实际看到的内容。

适用场景：

• 工作周报、会议纪要、项目说明
• 商业报价、验收报告、需求说明
• 简历、培训讲义、研究报告
• 目录、页码、图表题注与样式统一
• 已有文档的局部修改与版本比对

不适用：

• 把长文档简单拼接成一段文字
• 在没有事实来源时编造业务数据
• 用截图代替可编辑文档

一眼看懂

访谈 / 记录 / 数据 / 旧稿
        │
        ▼
WordCraft 技能（收集 → 结构 → 排版 → 回读）
        │
        ├── wordcraft-cli（原生文档操作）
        └── MCP 编辑器（浏览器内查看与局部调整）
        │
        ▼
DOCX + 重新打开检查 + 交付说明

能力与边界

能力	说明	边界
起草	按目标、读者和材料生成章节	事实必须来自输入或明确标注
结构	标题层级、目录、页码、页眉页脚	长文档分页需实际打开检查
表格	原生表格、合并单元格、题注	复杂公式与图表需单独核对
样式	段落、字体、编号、间距统一	不替代品牌设计规范
局部修改	保留未涉及内容，只改指定范围	修改后必须重新打开
版本比对	两版文字与结构差异	不判断业务上谁对
导出	DOCX，必要时 PDF	PDF 需检查字体嵌入

架构与核心流程

宿主 / Agent
   │  调用技能
   ▼
skills/wordcraft-*  ──►  MCP 编辑器 / wordcraft-cli
                              │
                              ▼
                     DOCX + 结构检查
                              │
                              ▼
                     重新打开、逐页核对、交付

原则：

1. 先确认目标、读者、篇幅和交付格式。
2. 先生成结构，再填内容，最后统一排版。
3. 每次修改保留可回退版本。
4. 退出码成功不等于版面正确，必须重新打开检查。

兼容性

项目	状态
宿主	Codex 有完整证据；其他宿主未验证
Node.js	24+（编辑器）
原生引擎	WordCraft 0.7.0 / wordcraft-cli
平台	以实际安装包与发行说明为准
Windows Git	需要开启 longpaths

安装

codex plugin marketplace add partme-ai/full-aigc-plugins
codex plugin add wordcraft@full-aigc-plugins

安装后重启宿主，先做只读检查：

打开这份文档，告诉我章节结构、页数和现有样式，不要修改。

快速开始

1. 确认目标：文档类型、读者、篇幅、必须包含的章节。
2. 收集事实：会议记录、数据、旧稿、品牌规范。
3. 生成结构：先目录和章节，再逐节填内容。
4. 统一排版：标题、正文、表格、页码、页眉页脚。
5. 重新打开：检查分页、目录、表格跨页和字体。
6. 交付：给出 DOCX，必要时导出 PDF。

配置

变量	用途	默认
CRAFT_WORKSPACE_ROOT	编辑器绑定的工作区	当前项目
CRAFT_EDITOR_UPDATE	设为 off 跳过增强包下载	开启

不要在文档或配置中写入密钥、令牌和私有路径。

扩展契约

新增技能时应：

• 使用 wordcraft- 前缀
• 在 SKILL.md 声明触发条件和边界
• 通过 MCP 或固定 CLI 操作真实文档
• 修改后重新打开并核对结构
• 不把“生成成功”写成“交付完成”

重试、幂等与恢复

• 修改前保存版本或副本。
• 失败后先检查当前文档状态，不自动重复写入。
• 重新执行时使用新输出路径。
• 不确定的结果标记为待核对。

数据与状态

• 原始材料只读。
• 输出文档与临时文件分开。
• 保留修改记录和最终版本。
• 删除临时文件前确认交付文件已保存。

安全

• 不把未授权材料上传到第三方服务。
• 敏感字段脱敏后再交付。
• 宏、外部链接和嵌入对象需显式确认。
• 发现泄露先轮换凭据，再清理文档。

可观测性与运行

• 记录命令、输出文件、页数和结构检查结果。
• 交付前确认文件可打开、目录可更新、页码正确。
• 长文档至少抽查首页、中间页和末页。

开发与验证

node --test
python3 -m pytest

提交前确认技能清单、目录和 README 一致。

打包与发布

• 版本与 plugin.json、市场清单、tag 一致。
• ZIP 根目录为 wordcraft-plugin。
• 发布后重新安装并做一次只读检查。

升级与迁移

• 升级前备份工作区文档。
• 旧版本生成的文件保持可打开。
• 迁移后重新检查模板、页码和目录。

故障排查

现象	检查
文档打不开	文件是否完整、是否被占用
目录不更新	在 Word 中更新域
页码错乱	分节符与页码起始值
表格跨页异常	行属性与重复标题行
字体缺失	嵌入字体或替换字体

项目结构

wordcraft-plugin/
├── .zcode-plugin/      # ZCode 清单与 UI surface
├── .codex-plugin/      # Codex 清单
├── .claude-plugin/     # Claude 清单
├── skills/             # 16 个技能
├── ui/                 # MCP Apps 编辑器
├── commands/open.md    # 打开编辑器命令
├── docs/               # 架构与验证记录
└── assets/             # 图标与模板

深入文档

• 架构
• 场景技能
• 任务回执

贡献与支持

提交问题时附上插件版本、宿主、文档类型、命令、输出文件和预期结果。不要附真实敏感文档。

许可证

Apache-2.0，见 LICENSE。