项目分析报告技能
概述
从本地文件夹中的多个Excel数据文件（.xlsx）自动读取、聚合、分析，并生成一份自包含的HTML综合数据分析报告。无需后端服务，直接在浏览器中即可查看完整的图表、数据表格和分析洞察。本技能旨在赋能一线公益机构低成本完成项目透明化汇报，同样适用于企业运营与数据汇报场景。
🎯 能力边界
✅ 能做：
- 读取同一目录下的多份结构化 .xlsx（首行为列标题），自动聚合生成自包含 HTML 报告
- 输出 KPI 卡片、Chart.js 图表、聚合数据明细表、基于数据的洞察框
- 对敏感标签仅做聚合统计（分组计数/占比），并对小样本分组自动合并以降低重识别风险
- 移动端响应式布局，可在浏览器直接查看，或经 Playwright 另存 PDF
❌ 不做：
- ❌ 不逐条渲染个体敏感明细（如"某儿童姓名+留守/低保标签"的名单行）——仅聚合展示
- ❌ 不做实时/在线数据大屏、不启动后端服务、不做数据库直连
- ❌ 不分析非结构化数据（PDF/Word/图片/纯文本），不处理无列标题的表
- ❌ 不替代专业审计/法律/财税结论——洞察为 AI 辅助参考
- ❌ 不做单张表的简单公式计算（此类需求请直接用 Excel）
越界拒绝模板： 当用户请求超出上述范围时，明确告知："该需求超出本技能范围（本技能仅从多份结构化 Excel 生成聚合型 HTML 报告）。建议改用 {对应工具/方式}。"
🛠️ 工具能力声明
allowed-tools: Read, Write, Edit, Bash（最小权限原则）
| 工具 | 可用范围 | 禁止用途 |
|---|---|---|
| Bash | 安装依赖（xlsx）、执行 node scripts/generate_report.js |
不用于联网上传数据、不删除用户目录外文件 |
| Read | 读取脚本、配置参考、用户提供的路径信息 | 不读取与本任务无关的敏感文件 |
| Write / Edit | 修改 REPORT_CONFIG 配置、写出报告 HTML |
不覆盖用户其它文件（同名输出会先提示） |
> Bash 为高危工具，此处仅用于本地安装 npm 依赖与运行 Node 脚本，全程本地读写、无网络外传。
⚖️ 合规与免责（务必先读）
本技能可能处理未成年人 + 敏感个人信息（如留守/低保/民族/学业等标签），使用前请确认：
- 授权：处理儿童个人信息须已取得监护人/机构的合规授权。
- 最小必要：仅采集与分析必需的字段；脚本对敏感字段只做聚合统计，不逐条输出个体明细。
- 使用范围：生成的自包含 HTML 默认仅供机构内部管理使用；对外披露/分享/上云前须完成脱敏与授权复核（对小样本分组做合并/隐去，避免重识别）。
- 免责：报告中的洞察结论由 AI 自动生成、仅供参考，不构成审计、法律或财税意见；数据用于项目改进，不构成对任何儿童个人的评价或标签。
> 上述声明会自动注入到生成报告的页脚，运行结束时终端也会再次提示。相关法律依据：《中华人民共和国个人信息保护法》《中华人民共和国未成年人保护法》。
触发场景
- 用户要求"根据这些Excel文件生成数据分析报告"
- 用户要求"生成项目综合看板"
- 用户要求"把项目执行记录做成可视化报告"
- 用户提供多个Excel文件并希望生成HTML报告时
前置条件
- Excel数据文件位于同一目录，格式为
.xlsx - 每份Excel的第一个Sheet包含数据，首行为列标题
- 当前环境安装了 Node.js (>=16) 和 xlsx npm 包（见"步骤二"，请用官方修复版）
✅ 执行前置校验（U4）
在运行脚本前，请依次确认（脚本内部也会做同样校验并给出中文报错）：
REPORT_CONFIG.excelDir指向的目录存在且为文件夹（建议用绝对路径）；- 目录内至少有一个
.xlsx文件（忽略~$临时文件）； node -e "require('xlsx')"可正常 require（依赖已安装）；- Node 版本
node -v≥ 16； - 涉及未成年人信息时，已确认取得授权（见"合规与免责"）。
工作流程
步骤一：确认数据与需求（含授权确认）
与用户确认以下信息：
- Excel文件所在目录（绝对路径）
- 报告标题与副标题
- 需要分析的数据维度（可选，默认覆盖所有Excel文件）
- 报告输出路径（默认：当前目录下的
综合数据分析报告.html） - 【涉未成年人/敏感信息时必做】 提示用户：使用儿童等敏感个人信息须已取得监护人/机构合规授权，报告默认仅做聚合展示、不渲染个体明细行。
步骤二：安装依赖（使用官方修复版 xlsx）
⚠️ 安全提示：npm 上的 xlsx 停留在 0.18.5，存在原型污染（GHSA-4r6h-8v6p-xvw6）与 ReDoS（GHSA-5pgg-2g8v-p4x9）高危漏洞且无修复版。由于本技能会解析用户提供的 Excel，攻击面直接相关，必须安装 SheetJS 官方 CDN 的修复版：
cd /path/to/working/dir && npm install https://cdn.sheetjs.com/xlsx-latest/xlsx-latest.tgz
- 请仅处理可信来源的 Excel 文件。
- 若因网络受限无法访问官方 CDN，须在文档中标注已知 CVE 并由使用方明确接受风险后，方可临时使用
npm install xlsx。
步骤三：准备配置文件
根据用户的数据结构，在 scripts/generate_report.js 顶部的 REPORT_CONFIG 对象中配置：
reportMeta— 报告标题、副标题、输出路径excelDir— Excel文件所在目录kpiColorRules— KPI正负指标颜色规则
详细的字段映射和配置语法见 references/config.md。
步骤四：执行生成
node scripts/generate_report.js
脚本将：
1. 校验目录与文件（失败时给出友好中文提示）
2. 读取所有Excel数据并执行聚合计算（敏感字段仅聚合、小样本合并）
3. 生成静态HTML文件（含Chart.js图表、数据表格、KPI卡片、洞察框、合规声明页脚）
4. 输出文件大小和图表数量统计
步骤五：验证与交付（含脱敏/授权复核）
生成完成后：
1. 在浏览器中打开HTML文件验证图表和数据
2. 检查KPI数值是否与原始数据一致
3. 对外分享前脱敏/授权复核：确认无个体敏感明细、小样本分组已合并/隐去、已获授权；该文件默认仅供内部使用
4. 可选：使用Playwright将HTML导出为PDF（需另行安装 Playwright，npm i -D playwright && npx playwright install chromium）
🛡️ 失败降级策略（U5）
| 失败类型 | 触发条件 | 降级/处置 |
|---|---|---|
| 目录不存在 | excelDir 路径无效 |
终止并提示检查配置路径（建议用绝对路径） |
| 无 xlsx 文件 | 目录内无 .xlsx |
终止并提示放入数据文件 |
| 依赖缺失 | require('xlsx') 失败 |
终止并提示按步骤二安装官方修复版 |
| 文件损坏/加密 | XLSX.readFile 抛错 |
终止并提示该文件名及"未损坏/未加密"检查 |
| 核心表缺失 | 未识别到"儿童"表或为空 | 终止并列出已识别到的表名 |
| 次要表缺失 | 资金/志愿者等表为空 | 继续生成，相关指标以占位符"—"显示，不产出 NaN |
| CDN 不可达 | 离线/内网打开报告 | 图表不渲染，需将 Chart.js 改为本地内联/内网镜像（HTML 注释已说明） |
> 主流程包裹 try/catch，任何异常均输出用户友好的中文错误描述 + 排查建议，不直接抛原始堆栈。
核心特性
| 特性 | 说明 |
|---|---|
| 左侧导航栏 | 固定240px，桌面端自动滚动高亮当前模块 |
| 英雄封面 | 顶部区域展示报告标题、周期、覆盖范围、核心数字 |
| KPI卡片 | 每模块4个彩色卡片，绿=达标、红=风险、琥珀=关注 |
| 图表 | Chart.js v4 图表（柱状图/环形图/雷达图/水平柱状图），带 chartjs-plugin-datalabels 数值标注，CDN 引入启用 SRI 校验 |
| 数据明细表 | 每个图表下方附带聚合数据表，含类别/数值/占比/合计行 |
| 洞察框 | 每模块3条数据支撑的分析结论（AI 自动生成、供参考） |
| 隐私护栏 | 敏感字段仅聚合、小样本分组自动合并、页脚注入合规声明 |
| 移动端 | ≤768px自适应：汉堡菜单+2列KPI+1列图表 |
| 配色 | 专业10色调色板，CSS变量管理 |
扩展与自定义
- 修改配色：编辑脚本中的
COL对象 - 增减模块：在脚本
modules数组中增删条目 - 调整KPI颜色规则：修改
REPORT_CONFIG.kpiColorRules - 调整小样本阈值：修改脚本中的
K_ANON_THRESHOLD（默认 5） - 新增图表类型：参考 Chart.js 文档，在图表配置中添加新的
type
依赖
- Node.js >= 16
- npm 包:
xlsx（须用官方修复版：npm install https://cdn.sheetjs.com/xlsx-latest/xlsx-latest.tgz，用于读取Excel文件） - 报告HTML中 CDN 加载: Chart.js v4.4.7, chartjs-plugin-datalabels v2.2.0（已启用 SRI 完整性校验；离线环境需改本地内联）
