aico-cli 2.0.76 → 2.1.1

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;
+}