byteplan-cli 1.0.2 → 1.2.2

package/skills/byteplan-excel/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: byteplan-excel
+description: 根据已有的分析数据生成 Excel 报告。只输出结构化数据表格，不包含说明文字。需要先使用 byteplan-analysis skill 完成数据分析。
+---
+
+# BytePlan Excel 报告 Skill
+
+## 概述
+
+此 Skill 根据已有的分析数据生成 Excel 报告，**只输出结构化数据表格**：
+
+1. **读取数据** - 从工作目录读取分析结果数据
+2. **转换格式** - 将数据转换为 Excel 表格格式
+3. **生成 Excel** - 使用 xlsx 库创建工作簿
+
+**设计原则**：简洁、结构化、纯数据展示。
+
+**前置条件**：必须先使用 [byteplan-analysis](../byteplan-analysis/SKILL.md) skill 完成数据分析。
+
+---
+
+## 输出规范
+
+### 1. 文件命名
+
+```
+{分析主题}报告.xlsx
+```
+
+### 2. Sheet 结构
+
+每个分析维度生成一个独立的 Sheet：
+
+| Sheet 名称 | 内容 | 列结构 |
+|-----------|------|--------|
+| TOP3贡献要素 | 贡献最大的三个要素 | 排名、维度、要素、金额、贡献占比 |
+| 费用类别贡献 | 按费用类别的贡献分析 | 费用类别、金额、贡献占比 |
+| 资产类别贡献 | 按资产类别的贡献分析 | 资产类别、金额、贡献占比 |
+| 分摊步骤贡献 | 按分摊步骤的贡献分析 | 分摊步骤、金额、贡献占比 |
+| ... | 根据实际分析维度动态生成 | ... |
+
+### 3. 数据格式
+
+| 字段类型 | 格式 | 示例 |
+|---------|------|------|
+| 金额 | 数字，保留2位小数 | 16898.63 |
+| 占比 | 数字，保留3位小数 | 0.449 |
+| 排名 | 整数 | 1, 2, 3 |
+| 名称 | 字符串 | 研发费用 |
+
+### 4. 列宽设置
+
+```javascript
+// 根据内容自动设置列宽
+ws["!cols"] = [
+  { wch: 40 },  // 名称列
+  { wch: 15 },  // 金额列
+  { wch: 12 }   // 占比列
+];
+```
+
+---
+
+## 数据格式
+
+### 输入数据结构（excel_data.json）
+
+```json
+{
+  "sheets": [
+    {
+      "name": "TOP3贡献要素",
+      "columns": ["排名", "维度", "要素", "金额", "贡献占比"],
+      "data": [
+        [1, "分摊步骤", "其他费用分摊", 33396.69, 0.887],
+        [2, "费用类别", "研发费用", 16898.63, 0.449],
+        [3, "资产类别", "固定资产-施工设备-卷扬机、升降机", 15636.13, 0.579]
+      ]
+    },
+    {
+      "name": "费用类别贡献",
+      "columns": ["费用类别", "金额", "贡献占比"],
+      "data": [
+        ["研发费用", 16898.63, 0.449],
+        ["销售费用", 13363.98, 0.355],
+        ["管理费用", 6418.02, 0.170],
+        ["生产成本", 966.12, 0.026]
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 使用方法
+
+### 方式一：命令行
+
+```bash
+# 使用默认数据文件 (excel_data.json)
+cd skills/byteplan-excel
+pnpm run generate -o report.xlsx
+
+# 指定数据文件
+pnpm run generate -o report.xlsx -d /path/to/data.json
+```
+
+### 方式二：Node.js 调用
+
+```javascript
+import { generateExcel } from './scripts/generate_excel.js';
+
+generateExcel('report.xlsx', 'data.json');
+```
+
+### 方式三：直接传入数据
+
+```javascript
+import { generateExcelFromData } from './scripts/generate_excel.js';
+
+const data = {
+  sheets: [
+    {
+      name: "费用类别贡献",
+      columns: ["费用类别", "金额", "贡献占比"],
+      data: [
+        ["研发费用", 16898.63, 0.449],
+        ["销售费用", 13363.98, 0.355]
+      ]
+    }
+  ]
+};
+
+generateExcelFromData('report.xlsx', data);
+```
+
+---
+
+## 完整示例
+
+### 1. 准备数据文件
+
+```bash
+# 从分析结果生成数据文件
+# 确保 excel_data.json 包含所有必要字段
+```
+
+### 2. 生成 Excel
+
+```bash
+cd skills/byteplan-excel
+pnpm run generate -o 边际分析报告.xlsx
+```
+
+### 3. 打开查看
+
+```bash
+open 边际分析报告.xlsx
+```
+
+---
+
+## ⚠️ 重要规则
+
+### 文件输出位置
+
+**所有生成的 Excel 文件必须放在 BytePlan 工作目录下：**
+
+```
+~/.byteplan/workspaces/{主题}_{时间戳}/{主题}报告.xlsx
+```
+
+**❌ 错误位置：**
+- `~/.openclaw/workspace/`
+- `/tmp/`
+- 当前任意目录
+
+**✅ 正确位置：**
+- `~/.byteplan/workspaces/边际分析_20260331_230800/边际分析报告.xlsx`
+
+### 数据来源
+
+Excel 数据必须来自 `byteplan-analysis` 的分析结果，不能凭空编造数据。
+
+---
+
+## 与其他 Skill 的关系
+
+```
+byteplan-analysis          ← 数据分析（必须先执行）
+       ↓
+   analysis_report.md
+   analysisPlan.json
+       ↓
+byteplan-excel            ← 生成 Excel（读取分析结果）
+       ↓
+   xxx报告.xlsx
+       ↓
+byteplan-ppt              ← 生成 PPT（可选）
+byteplan-word             ← 生成 Word（可选）
+```
+
+---
+
+## 注意事项
+
+- **只输出数据**：Excel 中只包含结构化数据表格，不包含说明文字、标题等
+- **每个维度一个 Sheet**：不同分析维度分别放在独立的 Sheet
+- **数据来源**：必须基于 byteplan-analysis 的分析结果
+- **文件位置**：输出文件必须放在 BytePlan 工作目录
+- **包管理器**：使用 pnpm 安装依赖

package/skills/byteplan-excel/examples/margin-analysis.json

@@ -0,0 +1,40 @@
+{
+  "sheets": [
+    {
+      "name": "TOP3贡献要素",
+      "columns": ["排名", "维度", "要素", "金额", "贡献占比"],
+      "data": [
+        [1, "分摊步骤", "其他费用分摊", 33396.69, 0.887],
+        [2, "费用类别", "研发费用", 16898.63, 0.449],
+        [3, "资产类别", "固定资产-施工设备-卷扬机、升降机", 15636.13, 0.579]
+      ]
+    },
+    {
+      "name": "费用类别贡献",
+      "columns": ["费用类别", "金额", "贡献占比"],
+      "data": [
+        ["研发费用", 16898.63, 0.449],
+        ["销售费用", 13363.98, 0.355],
+        ["管理费用", 6418.02, 0.170],
+        ["生产成本", 966.12, 0.026]
+      ]
+    },
+    {
+      "name": "资产类别贡献",
+      "columns": ["资产类别", "金额", "贡献占比"],
+      "data": [
+        ["固定资产-施工设备-卷扬机、升降机", 15636.13, 0.579],
+        ["固定资产-工业生产设备-内燃机", 11370.07, 0.421],
+        ["计算机", 0, 0]
+      ]
+    },
+    {
+      "name": "分摊步骤贡献",
+      "columns": ["分摊步骤", "金额", "贡献占比"],
+      "data": [
+        ["其他费用分摊", 33396.69, 0.887],
+        ["研发费用分摊", 4250.06, 0.113]
+      ]
+    }
+  ]
+}

package/skills/byteplan-excel/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "byteplan-excel",
+  "version": "1.0.0",
+  "description": "BytePlan Excel 报告生成",
+  "type": "module",
+  "scripts": {
+    "generate": "node scripts/generate_excel.js"
+  },
+  "dependencies": {
+    "xlsx": "^0.18.5"
+  }
+}

package/skills/byteplan-excel/pnpm-lock.yaml

@@ -0,0 +1,68 @@
+lockfileVersion: '6.0'
+
+dependencies:
+  xlsx:
+    specifier: ^0.18.5
+    version: 0.18.5
+
+packages:
+
+  /adler-32@1.3.1:
+    resolution: {integrity: sha512-ynZ4w/nUUv5rrsR8UUGoe1VC9hZj6V5hU9Qw1HlMDJGEJw5S7TfTErWTjMys6M7vr0YWcPqs3qAr4ss0nDfP+A==}
+    engines: {node: '>=0.8'}
+    dev: false
+
+  /cfb@1.2.2:
+    resolution: {integrity: sha512-KfdUZsSOw19/ObEWasvBP/Ac4reZvAGauZhs6S/gqNhXhI7cKwvlH7ulj+dOEYnca4bm4SGo8C1bTAQvnTjgQA==}
+    engines: {node: '>=0.8'}
+    dependencies:
+      adler-32: 1.3.1
+      crc-32: 1.2.2
+    dev: false
+
+  /codepage@1.15.0:
+    resolution: {integrity: sha512-3g6NUTPd/YtuuGrhMnOMRjFc+LJw/bnMp3+0r/Wcz3IXUuCosKRJvMphm5+Q+bvTVGcJJuRvVLuYba+WojaFaA==}
+    engines: {node: '>=0.8'}
+    dev: false
+
+  /crc-32@1.2.2:
+    resolution: {integrity: sha512-ROmzCKrTnOwybPcJApAA6WBWij23HVfGVNKqqrZpuyZOHqK2CwHSvpGuyt/UNNvaIjEd8X5IFGp4Mh+Ie1IHJQ==}
+    engines: {node: '>=0.8'}
+    hasBin: true
+    dev: false
+
+  /frac@1.1.2:
+    resolution: {integrity: sha512-w/XBfkibaTl3YDqASwfDUqkna4Z2p9cFSr1aHDt0WoMTECnRfBOv2WArlZILlqgWlmdIlALXGpM2AOhEk5W3IA==}
+    engines: {node: '>=0.8'}
+    dev: false
+
+  /ssf@0.11.2:
+    resolution: {integrity: sha512-+idbmIXoYET47hH+d7dfm2epdOMUDjqcB4648sTZ+t2JwoyBFL/insLfB/racrDmsKB3diwsDA696pZMieAC5g==}
+    engines: {node: '>=0.8'}
+    dependencies:
+      frac: 1.1.2
+    dev: false
+
+  /wmf@1.0.2:
+    resolution: {integrity: sha512-/p9K7bEh0Dj6WbXg4JG0xvLQmIadrner1bi45VMJTfnbVHsc7yIajZyoSoK60/dtVBs12Fm6WkUI5/3WAVsNMw==}
+    engines: {node: '>=0.8'}
+    dev: false
+
+  /word@0.3.0:
+    resolution: {integrity: sha512-OELeY0Q61OXpdUfTp+oweA/vtLVg5VDOXh+3he3PNzLGG/y0oylSOC1xRVj0+l4vQ3tj/bB1HVHv1ocXkQceFA==}
+    engines: {node: '>=0.8'}
+    dev: false
+
+  /xlsx@0.18.5:
+    resolution: {integrity: sha512-dmg3LCjBPHZnQp5/F/+nnTa+miPJxUXB6vtk42YjBBKayDNagxGEeIdWApkYPOf3Z3pm3k62Knjzp7lMeTEtFQ==}
+    engines: {node: '>=0.8'}
+    hasBin: true
+    dependencies:
+      adler-32: 1.3.1
+      cfb: 1.2.2
+      codepage: 1.15.0
+      crc-32: 1.2.2
+      ssf: 0.11.2
+      wmf: 1.0.2
+      word: 0.3.0
+    dev: false

package/skills/byteplan-excel/scripts/generate_excel.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+
+/**
+ * BytePlan Excel 报告生成脚本
+ * 
+ * 功能：根据分析数据生成结构化的 Excel 报告
+ * 
+ * 使用方式：
+ *   node generate_excel.js -o output.xlsx [-d data.json]
+ * 
+ * 参数：
+ *   -o, --output  输出文件路径（必需）
+ *   -d, --data    数据文件路径（默认：excel_data.json）
+ */
+
+import XLSX from 'xlsx';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { resolve, dirname, basename } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * 解析命令行参数
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const params = {
+    output: null,
+    data: null
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    if ((args[i] === '-o' || args[i] === '--output') && args[i + 1]) {
+      params.output = args[i + 1];
+      i++;
+    } else if ((args[i] === '-d' || args[i] === '--data') && args[i + 1]) {
+      params.data = args[i + 1];
+      i++;
+    }
+  }
+
+  return params;
+}
+
+/**
+ * 计算列宽
+ */
+function calculateColWidth(data, columns) {
+  const widths = columns.map((col, idx) => {
+    // 列标题宽度
+    let maxWidth = String(col).length * 2 + 2;
+    
+    // 数据宽度
+    data.forEach(row => {
+      const cellValue = row[idx];
+      const cellWidth = String(cellValue ?? '').length * 2 + 2;
+      if (cellWidth > maxWidth) {
+        maxWidth = cellWidth;
+      }
+    });
+    
+    return Math.min(Math.max(maxWidth, 10), 50);
+  });
+  
+  return widths.map(w => ({ wch: w }));
+}
+
+/**
+ * 从数据对象生成 Excel
+ */
+export function generateExcelFromData(outputPath, data) {
+  const wb = XLSX.utils.book_new();
+
+  // 遍历每个 Sheet
+  for (const sheet of data.sheets) {
+    // 组装数据：第一行是列标题，后面是数据行
+    const sheetData = [sheet.columns, ...sheet.data];
+    
+    // 创建 Sheet
+    const ws = XLSX.utils.aoa_to_sheet(sheetData);
+    
+    // 设置列宽
+    ws['!cols'] = calculateColWidth(sheet.data, sheet.columns);
+    
+    // 添加到工作簿
+    XLSX.utils.book_append_sheet(wb, ws, sheet.name);
+  }
+
+  // 写入文件
+  XLSX.writeFile(wb, outputPath);
+  
+  return outputPath;
+}
+
+/**
+ * 从 JSON 文件生成 Excel
+ */
+export function generateExcel(outputPath, dataPath) {
+  // 检查数据文件
+  if (!existsSync(dataPath)) {
+    console.error(`❌ 数据文件不存在: ${dataPath}`);
+    process.exit(1);
+  }
+
+  // 读取数据
+  const data = JSON.parse(readFileSync(dataPath, 'utf-8'));
+  
+  // 生成 Excel
+  return generateExcelFromData(outputPath, data);
+}
+
+/**
+ * 主函数
+ */
+function main() {
+  const params = parseArgs();
+
+  if (!params.output) {
+    console.log(`
+BytePlan Excel 报告生成
+
+使用方式：
+  node generate_excel.js -o output.xlsx [-d data.json]
+
+参数：
+  -o, --output  输出文件路径（必需）
+  -d, --data    数据文件路径（默认：excel_data.json）
+
+示例：
+  node generate_excel.js -o 报告.xlsx
+  node generate_excel.js -o 报告.xlsx -d ../excel_data.json
+`);
+    process.exit(0);
+  }
+
+  // 默认数据文件
+  const dataPath = params.data || resolve(__dirname, '../excel_data.json');
+  const outputPath = resolve(params.output);
+
+  console.log(`📊 生成 Excel 报告...`);
+  console.log(`   数据: ${dataPath}`);
+  console.log(`   输出: ${outputPath}`);
+
+  try {
+    generateExcel(outputPath, dataPath);
+    console.log(`✅ Excel 已生成: ${outputPath}`);
+  } catch (error) {
+    console.error(`❌ 生成失败: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// 执行主函数
+main();