\n 使用 YAML 生成专业 Word 文档\n
\n\n\n 特性 •\n 安装 •\n 快速开始 •\n 文档 •\n 示例\n
\n\n---\n\n## 简介\n\nDoc Creator 是一个强大的文档生成工具，通过 YAML 格式定义文档结构和样式，自动生成专业的 Microsoft Word (.docx) 文档。采用严格的样式白名单机制，确保生成的文档风格一致、格式规范。\n\n## 特性\n\n- 🎯 **严格的样式约束** - 预定义样式白名单，防止样式不一致\n- 📝 **YAML 格式** - 结构清晰，易于编写和维护\n- ✅ **自动验证** - 内置验证器确保格式正确\n- 🎨 **丰富的格式支持** - 标题、段落、列表、表格、图表、数学公式等\n- 📊 **数据可视化** - 支持柱状图、折线图、饼图、雷达图\n- 📐 **科学排版** - 支持 LaTeX 数学公式\n- 📄 **标准输出** - 生成标准 .docx 文件，兼容 Microsoft Word\n\n## 技术栈\n\n- **Python 3.8+** - 核心运行时\n- **python-docx** - Word 文档生成\n- **PyYAML** - YAML 解析\n- **Matplotlib** - 图表绘制\n- **NumPy** - 数值计算\n\n## 安装\n\n### 环境要求\n\n- **Node.js** 14.0 或更高版本（用于便捷启动）\n- **Python** 3.8 或更高版本（核心运行时）\n\n### 方式一：使用 npx（推荐）\n\n无需克隆仓库，直接使用 npx 运行：\n\n```bash\nnpx -y @birthday8/doc-mcp\n```\n\n### 方式二：克隆仓库\n\n```bash\ngit clone https://github.com/233a45/doc-mcp.git\ncd doc-mcp\nnode index.js\n```\n\n### 方式三：Python 直接使用\n\n如果你不想使用 Node.js，可以直接使用 Python：\n\n```bash\npip install pyyaml python-docx matplotlib numpy\npython python/server.py\n```\n\n## MCP 配置\n\n将 Doc Creator 配置到你的 AI 客户端中：\n\n### Claude Desktop\n\n编辑 `claude_desktop_config.json`：\n\n**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"doc-creator\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@birthday8/doc-mcp\"\n ]\n }\n }\n}\n```\n\n### Cursor\n\n在 Cursor 设置中找到 MCP 配置，添加：\n\n```json\n{\n \"mcpServers\": {\n \"doc-creator\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@birthday8/doc-mcp\"\n ]\n }\n }\n}\n```\n\n### 其他支持 MCP 的客户端\n\n参考上述配置格式，将 `npx -y @birthday8/doc-mcp` 作为命令配置即可。\n\n## 快速开始\n\n### 1. 创建 YAML 文件\n\n```yaml\nversion: \"1.0\"\nmetadata:\n title: \"示例文档\"\ncontent:\n - type: heading\n level: 1\n children:\n - type: text\n content: \"欢迎使用 Doc Creator\"\n \n - type: paragraph\n style:\n align: justify\n lineHeight: 1.5\n children:\n - type: text\n content: \"这是一个使用 YAML 格式生成的 Word 文档示例。\"\n \n - type: chart\n chartType: bar\n title: \"季度销售数据\"\n labels: [\"Q1\", \"Q2\", \"Q3\", \"Q4\"]\n data: [120, 150, 180, 200]\n```\n\n### 2. 生成文档\n\n```python\nfrom python.yaml_to_docx import convert_yaml_to_docx\n\nwith open(\"document.yaml\", \"r\", encoding=\"utf-8\") as f:\n yaml_content = f.read()\n\nconvert_yaml_to_docx(yaml_content, \"output.docx\")\n```\n\n### 3. 命令行使用\n\n```bash\ncd python\npython yaml_to_docx.py input.yaml output.docx\n```\n\n## 核心功能\n\n### 支持的节点类型\n\n| 类型 | 说明 | 示例 |\n|------|------|------|\n| `heading` | 标题 | `level: 1-6` |\n| `paragraph` | 段落 | 支持样式和缩进 |\n| `text` | 纯文本 | 基础文本节点 |\n| `span` | 样式容器 | 字体、颜色、加粗等 |\n| `emphasis` | 强调 | strong/em/u/s/sup/sub |\n| `list` / `listItem` | 列表 | 有序/无序列表 |\n| `table` | 表格 | 支持合并单元格 |\n| `chart` | 图表 | 柱状图/折线图/饼图/雷达图 |\n| `math` | 数学公式 | LaTeX 公式 |\n| `image` | 图片 | 支持本地和网络图片 |\n| `codeBlock` | 代码块 | 语法高亮 |\n| `callout` | 提示框 | info/warning/success |\n| `toc` | 目录 | 自动生成 |\n| `columns` | 多栏布局 | 1-4 栏 |\n| `pageBreak` | 分页符 | 强制分页 |\n\n### 样式白名单\n\n所有样式值必须来自预定义白名单：\n\n| 属性 | 可选值 |\n|------|--------|\n| `fontSize` | 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 26, 28, 36, 48, 72 |\n| `fontFamily` | 微软雅黑, 宋体, 黑体, 楷体, Arial, Times New Roman, Consolas, Calibri, Helvetica, Georgia |\n| `color` | black, darkGray, gray, lightGray, red, blue, green, yellow, orange, purple, pink, brown, white, darkBlue, navy, darkGreen, darkRed, gold, silver |\n| `align` | left, center, right, justify |\n| `lineHeight` | 1.0, 1.15, 1.5, 2.0, 2.5 |\n| `bgColor` | lightBlue, lightGreen, lightYellow, lightRed, lightGray, white, lightPurple, lightOrange, lightPink |\n\n## 示例\n\n### 项目报告\n\n```yaml\nversion: \"1.0\"\nmetadata:\n title: \"项目进度报告\"\ncontent:\n - type: heading\n level: 1\n align: center\n children:\n - type: text\n content: \"项目进度报告\"\n \n - type: table\n children:\n - type: tableRow\n isHeader: true\n children:\n - type: tableCell\n bgColor: lightBlue\n children:\n - type: text\n content: \"任务\"\n - type: tableCell\n bgColor: lightBlue\n children:\n - type: text\n content: \"状态\"\n - type: tableRow\n children:\n - type: tableCell\n children:\n - type: text\n content: \"需求分析\"\n - type: tableCell\n children:\n - type: text\n content: \"已完成\"\n```\n\n### 数据可视化\n\n```yaml\n- type: chart\n chartType: line\n title: \"销售趋势\"\n labels: [\"1月\", \"2月\", \"3月\", \"4月\", \"5月\", \"6月\"]\n series:\n - name: \"2024年\"\n data: [100, 120, 140, 160, 180, 200]\n - name: \"2025年\"\n data: [110, 135, 155, 175, 195, 220]\n```\n\n### 数学公式\n\n```yaml\n- type: math\n latex: \"E = mc^2\"\n display: true\n```\n\n## 文档\n\n- [AI 使用指南](AI_USAGE_GUIDE.md) - 详细的 AI 使用说明\n- [AI 提示词](AI_USAGE_PROMPT.md) - AI 提示词模板\n- [YAML Schema](python/yaml_schema.py) - 完整的格式规范\n\n## 项目结构\n\n```\ndoc-creator/\n├── python/\n│ ├── server.py # MCP 服务器\n│ ├── yaml_schema.py # YAML 格式定义\n│ ├── yaml_document.py # 文档模型\n│ ├── yaml_validator.py # 验证器\n│ ├── yaml_to_docx.py # 转换器\n│ └── sample/ # 示例文档\n├── AI_USAGE_GUIDE.md # AI 使用指南\n├── AI_USAGE_PROMPT.md # AI 提示词\n└── README.md # 本文档\n```\n\n## MCP 工具\n\n本项目提供 MCP (Model Context Protocol) 工具供 AI 使用：\n\n| 工具 | 说明 |\n|------|------|\n| `get-yaml-schema` | 获取 YAML 格式规范 |\n| `validate-yaml` | 验证 YAML 格式 |\n| `convert-yaml-document` | 转换为 DOCX |\n| `get-document-guide` | 获取完整指南 |\n\n## 贡献\n\n欢迎提交 Issue 和 Pull Request！\n\n## 许可证\n\n[MIT](LICENSE)\n\n---\n\n\n Made with ❤️ for better document generation\n
\n","readmeFilename":"README.md"}