aico-cli 2.0.76 → 2.0.77

package/dist/chunks/simple-config.mjs

@@ -14,7 +14,7 @@ import { join, dirname, basename } from 'pathe';
 import { fileURLToPath } from 'node:url';
 import { EventEmitter } from 'node:events';
 
-const version = "2.0.76";
+const version = "2.0.77";
 
 function displayBanner(subtitle) {
   const defaultSubtitle = "\u4E00\u952E\u914D\u7F6E\u4F60\u7684\u5F00\u53D1\u73AF\u5883";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aico-cli",
-  "version": "2.0.76",
+  "version": "2.0.77",
   "packageManager": "pnpm@9.15.9",
   "description": "AI CLI",
   "repository": {

package/templates/agents/aico/tech-spec/tech-spec-analyzer.md

@@ -0,0 +1,158 @@
+---
+name: tech-spec-analyzer
+description: 技术规格说明书生成指导，指导用户使用 MCP 工具分步生成技术规格说明书
+tools: mcp__tech-spec-generator
+color: blue
+---
+
+# 技术规格说明书生成指导
+
+指导用户使用 MCP 工具分步生成技术规格说明书。
+
+## 🛠️ 可用 MCP 工具
+
+### 项目管理
+
+| 工具名                     | 说明                       |
+| -------------------------- | -------------------------- |
+| `create_tech_spec_project` | 创建项目，返回 projectUuid |
+| `get_project_progress`     | 获取项目进度               |
+| `list_tech_spec_projects`  | 列出所有项目               |
+
+### 章节保存（可多次调用）
+
+| 工具名                    | 说明                       |
+| ------------------------- | -------------------------- |
+| `save_service_interfaces` | 保存一个服务的接口清单     |
+| `save_interface_design`   | 保存一个服务的接口设计详情 |
+| `save_database_table`     | 保存一个数据库表结构       |
+| `save_tech_solution`      | 保存技术方案               |
+| `save_business_exception` | 保存业务异常处理           |
+| `save_appendix`           | 保存附录（异常码、码值）   |
+
+### 渲染与分析
+
+| 工具名                      | 说明                       |
+| --------------------------- | -------------------------- |
+| `render_tech_spec_document` | 合并所有章节生成 Word 文档 |
+| `analyze_project_structure` | 分析项目结构               |
+| `analyze_large_project`     | 自动分析大型项目           |
+
+## 📋 标准生成流程
+
+### 步骤 1：创建项目
+
+```
+调用 create_tech_spec_project
+参数：
+  - projectPath: 项目路径
+  - projectName: 项目名称
+  - moduleName: 模块名称
+返回：projectUuid（后续步骤必需）
+```
+
+### 步骤 2：保存服务接口清单
+
+对每个 Controller/Service 调用：
+
+```
+调用 save_service_interfaces
+参数：
+  - projectUuid: 步骤1返回的UUID
+  - serviceType: "REST" 或 "RPC"
+  - serviceEnglishName: 类名，如 "UserController"
+  - serviceChineseName: 中文名，如 "用户管理"
+  - serviceDescription: 服务描述
+  - interfaces: JSON字符串，格式：
+    [{"functionDescription":"查询用户","serviceName":"UserController","methodName":"getUser"}]
+```
+
+### 步骤 3：保存接口设计详情
+
+对每个服务调用：
+
+```
+调用 save_interface_design
+参数：
+  - projectUuid: UUID
+  - serviceName: 服务名称
+  - serviceDesc: 服务描述
+  - designs: JSON字符串，格式：
+    [{
+      "functionName": "查询用户",
+      "interfaceDesc": "根据ID查询用户信息",
+      "className": "UserController",
+      "methodName": "getUser",
+      "parameterList": [{"type":"Long","name":"id","required":"是","desc":"用户ID"}],
+      "returnResultList": [{"type":"UserVo","name":"data","desc":"用户信息"}],
+      "implementLogic": "1.校验参数 2.查询数据库 3.返回结果"
+    }]
+```
+
+### 步骤 4：保存数据库表结构
+
+对每个表调用：
+
+```
+调用 save_database_table
+参数：
+  - projectUuid: UUID
+  - tableName: 表名，如 "t_user"
+  - entityName: 实体名，如 "User"
+  - tableDescription: 表描述
+  - fields: JSON字符串，格式：
+    [{"fieldName":"id","fieldType":"bigint","fieldDescription":"主键","fieldLength":"20"}]
+```
+
+### 步骤 5：保存技术方案（可选）
+
+```
+调用 save_tech_solution
+参数：
+  - projectUuid: UUID
+  - content: Markdown格式的技术方案内容
+```
+
+### 步骤 6：保存附录（可选）
+
+```
+调用 save_appendix
+参数：
+  - projectUuid: UUID
+  - exceptionCodes: JSON字符串，格式：
+    [{"exceptionCode":"USER_001","exceptionDescription":"用户不存在"}]
+  - codeValues: JSON字符串，格式：
+    [{"propertyName":"用户状态","codeValue":"1-正常,0-禁用"}]
+```
+
+### 步骤 7：生成文档
+
+```
+调用 render_tech_spec_document
+参数：
+  - projectUuid: UUID
+  - outputDir: 输出目录（可选）
+返回：生成的 Word 文档路径
+```
+
+## ⚡ 快速模式
+
+对于大型项目，可使用自动分析：
+
+```
+调用 analyze_large_project
+参数：
+  - projectPath: 项目路径
+  - projectName: 项目名称（可选）
+  - moduleName: 模块名称（可选）
+返回：projectUuid
+
+然后调用 render_tech_spec_document 生成文档
+```
+
+## 📝 注意事项
+
+1. **分步保存**：每个服务/表单独调用保存，避免一次传输大量数据
+2. **JSON 字符串**：复杂参数使用 JSON 字符串格式传递
+3. **多次调用**：同类型章节可多次调用，系统会自动合并
+4. **projectUuid**：创建项目后返回，后续所有操作都需要此参数

package/templates/commands/aico/tech-spec.md

@@ -0,0 +1,214 @@
+---
+description: 技术规格说明书生成指挥官，支持单工程和多工程（微服务）合并生成
+allowed-tools: Read(**), Write(.aico/tech/**), mcp__tech-spec-generator
+argument-hint: <工程路径> [工程路径2...] [--name 项目名称] [--exclude 排除模块]
+---
+
+## 用法
+
+`/tech-spec <路径> [选项]`
+
+### 单工程
+
+```bash
+# 分析当前目录
+/tech-spec .
+
+# 分析指定工程
+/tech-spec /path/to/project
+
+# 指定项目名称
+/tech-spec /path/to/project --name "用户管理系统"
+
+# 排除测试模块
+/tech-spec /path/to/project --exclude test,demo
+```
+
+### 多工程（微服务）
+
+多个工程并行分析，合并生成一本技术规格说明书：
+
+```bash
+# 方式1：给父目录，自动识别子工程
+/tech-spec /path/to/microservices-parent
+
+# 方式2：明确指定多个工程路径
+/tech-spec /path/to/user-service /path/to/order-service /path/to/payment-service
+
+# 使用别名标识工程（格式：路径:别名）
+/tech-spec /path/to/user-service:用户服务 /path/to/order-service:订单服务
+
+# 指定合并后的项目名称
+/tech-spec /path/to/microservices-parent --name "电商微服务系统"
+```
+
+## 智能体调用
+
+### 单工程模式
+
+调用 `tech-spec-analyzer` 智能体：
+
+```
+tech-spec-analyzer
+  ├── projectPath: 工程路径
+  ├── projectName: 项目名称
+  └── excludeModules: 排除模块
+```
+
+### 多工程模式（并行分析 → 合并生成）
+
+**并行调用多个 `tech-spec-analyzer` 智能体**分析各工程：
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    并行执行                          │
+├─────────────────────────────────────────────────────┤
+│ tech-spec-analyzer(用户服务) ──┐                    │
+│ tech-spec-analyzer(订单服务) ──┼── 等待所有完成      │
+│ tech-spec-analyzer(支付服务) ──┘                    │
+└─────────────────────────────────────────────────────┘
+                      ↓
+              合并分析结果
+                      ↓
+           生成一本技术规格说明书
+```
+
+## 执行流程
+
+### 阶段一：参数解析与工程识别
+
+1. 解析输入路径
+2. **判断路径类型**：
+   - 单个工程（有 pom.xml/package.json/build.gradle）
+   - 父目录（包含多个子工程）
+   - 多个明确指定的工程路径
+3. **自动识别子工程**（父目录模式）：
+   ```
+   扫描子目录，识别包含以下文件的为独立工程：
+   - pom.xml（Java Maven）
+   - build.gradle（Java Gradle）
+   - package.json（Node.js）
+   ```
+4. 解析工程别名和选项参数
+
+### 阶段二：并行分析
+
+**单工程**：
+
+```
+调用 tech-spec-analyzer 智能体
+  └── analyze_full_project → 生成文档
+```
+
+**多工程**：
+
+```
+并行调用 N 个 tech-spec-analyzer 智能体（仅分析，不生成文档）
+  ├── 智能体1 → 分析用户服务 → 返回 serviceInterfaceList, tableInfoList
+  ├── 智能体2 → 分析订单服务 → 返回 serviceInterfaceList, tableInfoList
+  └── 智能体N → 分析支付服务 → 返回 serviceInterfaceList, tableInfoList
+等待所有智能体完成
+```
+
+### 阶段三：合并生成（多工程）
+
+收集所有智能体的分析结果，合并后生成一本文档：
+
+```
+合并规则：
+1. 服务接口：添加工程前缀 [用户服务] UserController
+2. 数据表：添加工程前缀 [用户服务] t_user
+3. 重新编号：合并后统一编号
+4. 生成统一文档
+```
+
+### 阶段四：结果展示
+
+**单工程结果**：
+
+```markdown
+## 📄 技术规格说明书生成完成
+
+**项目**：{projectName}
+**文档路径**：{outputPath}
+
+| 统计项   | 数量           |
+| -------- | -------------- |
+| 服务接口 | {serviceCount} |
+| 数据表   | {tableCount}   |
+```
+
+**多工程结果**：
+
+```markdown
+## 📄 微服务技术规格说明书生成完成
+
+**项目**：{projectName}
+**文档路径**：{outputPath}
+
+### 各工程统计
+
+| 工程     | 服务接口 | 数据表 |
+| -------- | -------- | ------ |
+| 用户服务 | 12       | 8      |
+| 订单服务 | 15       | 10     |
+| 支付服务 | 8        | 5      |
+| **合计** | **35**   | **23** |
+
+已合并生成一本技术规格说明书。
+```
+
+## 流程可视化
+
+```mermaid
+graph TD
+    A[用户输入路径] --> B{路径类型判断}
+
+    B -->|单工程| C[tech-spec-analyzer]
+    C --> D[analyze_full_project]
+    D --> E[生成文档]
+
+    B -->|父目录| F[扫描识别子工程]
+    F --> G{发现多个工程?}
+    G -->|是| H[并行调用智能体]
+    G -->|否| C
+
+    B -->|多个路径| H
+
+    H --> I1[智能体1: 分析工程1]
+    H --> I2[智能体2: 分析工程2]
+    H --> I3[智能体N: 分析工程N]
+    I1 --> J[等待所有完成]
+    I2 --> J
+    I3 --> J
+    J --> K[合并分析结果]
+    K --> L[生成合并文档]
+
+    E --> M[展示结果]
+    L --> M
+```
+
+## MCP 工具说明
+
+### analyze_project_structure
+
+扫描工程目录，识别文件类型和模块。
+
+### analyze_full_project
+
+完整分析工程并生成技术规格说明书。
+
+**参数**：
+
+- `projectPath`: 工程根目录（必填）
+- `projectName`: 项目名称（可选）
+- `moduleName`: 模块名称（可选）
+- `excludeModules`: 排除的模块列表（可选）
+
+## 输出
+
+文档保存到 `.aico/tech/` 目录：
+
+```
+技术规格说明书_{项目名}_{模块名}_{时间戳}.docx
+```

package/templates/settings.json

@@ -4,6 +4,8 @@
     "DISABLE_TELEMETRY": "1",
     "DISABLE_ERROR_REPORTING": "1",
     "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
+    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000",
+    "MAX_THINKING_TOKENS": "31999",
     "ANTHROPIC_BASE_URL": "http://127.0.0.1:3456",
     "ANTHROPIC_AUTH_TOKEN": "sk-aico-x-ccr"
   },

package/templates/skills/tech-whitepaper/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 五域科技
+Copyright (c) 2025 智能软件星工厂
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/templates/skills/word-document-processor/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 智能软件星工厂
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/skills/word-document-processor/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: word-document-processor
+description: Word 文档（.docx）处理技能，支持创建、读取、编辑和模板渲染。使用场景：(1) 创建新的 Word 文档 (2) 读取和提取 .docx 文件内容 (3) 编辑现有文档内容 (4) 使用模板生成文档 (5) 处理文档中的表格、列表、样式等。当用户需要处理 Word 文档、生成报告、填充模板或提取文档内容时触发此技能。
+---
+
+# Word Document Processor
+
+Word 文档处理技能，基于 docxtemplater 和 pizzip 库实现。
+
+## 核心依赖
+
+```bash
+npm install docxtemplater pizzip
+```
+
+## 快速开始
+
+### 读取 Word 文档
+
+```typescript
+import PizZip from "pizzip";
+import Docxtemplater from "docxtemplater";
+import * as fs from "fs/promises";
+
+async function readDocx(filePath: string): Promise<string> {
+  const content = await fs.readFile(filePath);
+  const zip = new PizZip(content);
+  const doc = new Docxtemplater(zip, {
+    paragraphLoop: true,
+    linebreaks: true,
+  });
+  return doc.getFullText();
+}
+```
+
+### 使用模板生成文档
+
+```typescript
+async function renderTemplate(
+  templatePath: string,
+  data: Record<string, any>,
+  outputPath: string
+): Promise<void> {
+  const templateContent = await fs.readFile(templatePath);
+  const zip = new PizZip(templateContent);
+
+  const doc = new Docxtemplater(zip, {
+    paragraphLoop: true,
+    linebreaks: true,
+    delimiters: { start: "{", end: "}" },
+  });
+
+  doc.render(data);
+
+  const output = doc.getZip().generate({
+    type: "nodebuffer",
+    compression: "DEFLATE",
+  });
+
+  await fs.writeFile(outputPath, output);
+}
+```
+
+## 模板语法
+
+### 基础占位符
+
+```
+{variableName}           - 简单变量替换
+{#items}...{/items}      - 循环列表
+{#condition}...{/condition} - 条件渲染
+```
+
+### 循环示例
+
+模板：
+
+```
+{#users}
+姓名: {name}
+邮箱: {email}
+{/users}
+```
+
+数据：
+
+```typescript
+{
+  users: [
+    { name: "张三", email: "zhang@example.com" },
+    { name: "李四", email: "li@example.com" },
+  ];
+}
+```
+
+### 嵌套循环
+
+```
+{#departments}
+部门: {deptName}
+{#employees}
+  - {empName} ({empRole})
+{/employees}
+{/departments}
+```
+
+## 高级功能
+
+### 处理表格
+
+表格中的循环会自动复制行：
+
+```
+| 序号 | 名称 | 描述 |
+|------|------|------|
+{#items}
+| {id} | {name} | {desc} |
+{/items}
+```
+
+### 图片处理
+
+需要额外安装 `docxtemplater-image-module-free`：
+
+```typescript
+import ImageModule from "docxtemplater-image-module-free";
+
+const imageOpts = {
+  centered: false,
+  getImage: (tagValue: string) => fs.readFileSync(tagValue),
+  getSize: () => [150, 150],
+};
+
+const doc = new Docxtemplater(zip, {
+  modules: [new ImageModule(imageOpts)],
+});
+```
+
+### 错误处理
+
+```typescript
+try {
+  doc.render(data);
+} catch (error: any) {
+  if (error.properties && error.properties.errors) {
+    const errors = error.properties.errors
+      .map((e: any) => e.properties?.explanation || e.message)
+      .join("; ");
+    throw new Error(`模板渲染错误: ${errors}`);
+  }
+  throw error;
+}
+```
+
+## 完整示例
+
+参考 `scripts/docx-processor.ts` 获取完整的文档处理工具类实现。
+
+## 最佳实践
+
+1. **模板设计**: 使用清晰的占位符命名，避免特殊字符
+2. **数据准备**: 确保数据结构与模板占位符完全匹配
+3. **错误处理**: 始终捕获并处理 docxtemplater 的错误
+4. **性能优化**: 大文档使用流式处理，避免内存溢出
+5. **编码问题**: 确保模板文件使用 UTF-8 编码
+
+## 常见问题
+
+- **占位符未替换**: 检查数据字段名是否与模板完全匹配
+- **循环不工作**: 确保数据是数组格式
+- **中文乱码**: 确保模板和代码都使用 UTF-8 编码

package/templates/skills/word-document-processor/references/template-syntax.md

@@ -0,0 +1,187 @@
+# Word 模板语法参考
+
+## 目录
+
+1. [基础语法](#基础语法)
+2. [循环语法](#循环语法)
+3. [条件语法](#条件语法)
+4. [表格处理](#表格处理)
+5. [高级用法](#高级用法)
+
+## 基础语法
+
+### 简单变量
+
+```
+{variableName}
+```
+
+数据: `{ variableName: "Hello World" }`
+
+### 嵌套对象
+
+```
+{user.name}
+{user.address.city}
+```
+
+数据:
+
+```json
+{
+  "user": {
+    "name": "张三",
+    "address": { "city": "北京" }
+  }
+}
+```
+
+## 循环语法
+
+### 基础循环
+
+```
+{#items}
+- {name}: {value}
+{/items}
+```
+
+数据:
+
+```json
+{
+  "items": [
+    { "name": "项目A", "value": 100 },
+    { "name": "项目B", "value": 200 }
+  ]
+}
+```
+
+### 嵌套循环
+
+```
+{#departments}
+部门: {deptName}
+{#members}
+  员工: {memberName}
+{/members}
+{/departments}
+```
+
+### 循环索引
+
+使用 `@index` 获取当前索引（从 0 开始）:
+
+```
+{#items}
+{@index}. {name}
+{/items}
+```
+
+## 条件语法
+
+### 简单条件
+
+```
+{#showSection}
+这部分内容只在 showSection 为 true 时显示
+{/showSection}
+```
+
+### 反向条件
+
+```
+{^isEmpty}
+列表不为空时显示
+{/isEmpty}
+```
+
+### 条件与循环结合
+
+```
+{#hasItems}
+{#items}
+- {name}
+{/items}
+{/hasItems}
+{^hasItems}
+暂无数据
+{/hasItems}
+```
+
+## 表格处理
+
+### 表格行循环
+
+在 Word 表格中，循环标签会自动复制整行:
+
+| 序号        | 名称   | 金额            |
+| ----------- | ------ | --------------- |
+| {#rows}{id} | {name} | {amount}{/rows} |
+
+数据:
+
+```json
+{
+  "rows": [
+    { "id": 1, "name": "商品A", "amount": "¥100" },
+    { "id": 2, "name": "商品B", "amount": "¥200" }
+  ]
+}
+```
+
+### 嵌套表格
+
+```
+{#orders}
+订单号: {orderNo}
+| 商品 | 数量 | 单价 |
+|------|------|------|
+| {#items}{productName} | {quantity} | {price}{/items} |
+{/orders}
+```
+
+## 高级用法
+
+### 原始 XML 输出
+
+使用 `{@rawXml}` 插入原始 XML:
+
+```
+{@formattedContent}
+```
+
+### 空值处理
+
+建议在数据准备阶段处理空值:
+
+```typescript
+function normalizeValue(val: any, defaultValue = "不涉及"): string {
+  if (!val || val === "" || val === "无") {
+    return defaultValue;
+  }
+  return String(val);
+}
+```
+
+### 自定义分隔符
+
+如果模板中需要使用 `{}` 字符，可以更改分隔符:
+
+```typescript
+const doc = new Docxtemplater(zip, {
+  delimiters: { start: "<<", end: ">>" },
+});
+```
+
+模板变为: `<<variableName>>`
+
+### 换行处理
+
+启用 `linebreaks: true` 后，数据中的 `\n` 会转换为 Word 换行:
+
+```typescript
+{
+  description: "第一行\n第二行\n第三行";
+}
+```

package/templates/skills/word-document-processor/scripts/docx-processor.ts

@@ -0,0 +1,206 @@
+/**
+ * Word 文档处理工具类
+ * 提供 .docx 文件的读取、创建、编辑和模板渲染功能
+ */
+
+import * as fs from "fs/promises";
+import * as path from "path";
+import Docxtemplater from "docxtemplater";
+import PizZip from "pizzip";
+
+export interface DocxProcessorOptions {
+  paragraphLoop?: boolean;
+  linebreaks?: boolean;
+  delimiters?: { start: string; end: string };
+}
+
+export interface RenderResult {
+  success: boolean;
+  outputPath: string | null;
+  error?: string;
+}
+
+const DEFAULT_OPTIONS: DocxProcessorOptions = {
+  paragraphLoop: true,
+  linebreaks: true,
+  delimiters: { start: "{", end: "}" },
+};
+
+/**
+ * 读取 Word 文档内容
+ */
+export async function readDocx(filePath: string): Promise<string> {
+  const content = await fs.readFile(filePath);
+  const zip = new PizZip(content);
+  const doc = new Docxtemplater(zip, {
+    paragraphLoop: true,
+    linebreaks: true,
+  });
+  return doc.getFullText();
+}
+
+/**
+ * 获取文档中的所有占位符
+ */
+export async function getPlaceholders(templatePath: string): Promise<string[]> {
+  const content = await fs.readFile(templatePath);
+  const zip = new PizZip(content);
+  const doc = new Docxtemplater(zip, {
+    paragraphLoop: true,
+    linebreaks: true,
+  });
+
+  // 获取模板中的所有标签
+  const text = doc.getFullText();
+  const placeholderRegex = /\{([^{}#/]+)\}/g;
+  const matches = text.match(placeholderRegex) || [];
+
+  return [...new Set(matches.map((m) => m.slice(1, -1)))];
+}
+
+/**
+ * 使用模板渲染文档
+ */
+export async function renderTemplate(
+  templatePath: string,
+  data: Record<string, any>,
+  outputPath: string,
+  options: DocxProcessorOptions = {}
+): Promise<RenderResult> {
+  try {
+    const mergedOptions = { ...DEFAULT_OPTIONS, ...options };
+
+    // 检查模板文件
+    try {
+      await fs.access(templatePath);
+    } catch {
+      return {
+        success: false,
+        outputPath: null,
+        error: `模板文件不存在: ${templatePath}`,
+      };
+    }
+
+    const templateContent = await fs.readFile(templatePath);
+    const zip = new PizZip(templateContent);
+
+    const doc = new Docxtemplater(zip, {
+      paragraphLoop: mergedOptions.paragraphLoop,
+      linebreaks: mergedOptions.linebreaks,
+      delimiters: mergedOptions.delimiters,
+    });
+
+    doc.render(data);
+
+    const output = doc.getZip().generate({
+      type: "nodebuffer",
+      compression: "DEFLATE",
+    });
+
+    // 确保输出目录存在
+    const outputDir = path.dirname(outputPath);
+    await fs.mkdir(outputDir, { recursive: true });
+
+    await fs.writeFile(outputPath, output);
+
+    return {
+      success: true,
+      outputPath,
+    };
+  } catch (error: any) {
+    // 处理 docxtemplater 错误
+    if (error.properties && error.properties.errors) {
+      const errorMessages = error.properties.errors
+        .map((e: any) => e.properties?.explanation || e.message)
+        .join("; ");
+      return {
+        success: false,
+        outputPath: null,
+        error: `模板渲染错误: ${errorMessages}`,
+      };
+    }
+
+    return {
+      success: false,
+      outputPath: null,
+      error: error.message || "未知错误",
+    };
+  }
+}
+
+/**
+ * 批量渲染文档
+ */
+export async function batchRender(
+  templatePath: string,
+  dataList: Record<string, any>[],
+  outputDir: string,
+  fileNameGenerator: (data: Record<string, any>, index: number) => string
+): Promise<RenderResult[]> {
+  const results: RenderResult[] = [];
+
+  for (let i = 0; i < dataList.length; i++) {
+    const data = dataList[i];
+    const fileName = fileNameGenerator(data, i);
+    const outputPath = path.join(outputDir, fileName);
+
+    const result = await renderTemplate(templatePath, data, outputPath);
+    results.push(result);
+  }
+
+  return results;
+}
+
+/**
+ * 合并多个 Word 文档的文本内容
+ */
+export async function mergeDocxTexts(filePaths: string[]): Promise<string> {
+  const texts: string[] = [];
+
+  for (const filePath of filePaths) {
+    const text = await readDocx(filePath);
+    texts.push(text);
+  }
+
+  return texts.join("\n\n---\n\n");
+}
+
+/**
+ * 验证模板数据完整性
+ */
+export async function validateTemplateData(
+  templatePath: string,
+  data: Record<string, any>
+): Promise<{ valid: boolean; missingFields: string[] }> {
+  const placeholders = await getPlaceholders(templatePath);
+  const dataKeys = Object.keys(flattenObject(data));
+
+  const missingFields = placeholders.filter((p) => !dataKeys.includes(p));
+
+  return {
+    valid: missingFields.length === 0,
+    missingFields,
+  };
+}
+
+/**
+ * 扁平化对象（用于验证嵌套数据）
+ */
+function flattenObject(
+  obj: Record<string, any>,
+  prefix = ""
+): Record<string, any> {
+  const result: Record<string, any> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    const newKey = prefix ? `${prefix}.${key}` : key;
+
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      Object.assign(result, flattenObject(value, newKey));
+    } else {
+      result[newKey] = value;
+    }
+  }
+
+  return result;
+}