周报生成器 (Weekly Report Generator)

设计哲学 (Design Philosophy)

这个技能的本质，不是简单的”填表”，而是一次语义提升的旅程：

碎片化的日常工作 → 模块化的业务叙事 → 结构化的周报文档

每周五，当开发者回顾本周的工作时，他们面对的是一系列零散的工作片段。这个技能的价值，是帮助他们从”我做了什么”提升到”我推进了哪些业务模块”。

核心工作流 (Core Workflow)

第一步：理解用户的输入模式

用户通常会在周五提供完整的一周工作内容，格式为：

生成周报，本周工作内容：
[周一的工作]
1. 任务描述
2. 任务描述
...

[周二的工作]
1. 任务描述
2. 任务描述
...

关键洞察：用户不会明确标注”周一”、”周二”，而是直接给出5组（或更少）工作列表。你需要智能识别每天的工作边界——通常通过连续的数字序号断层判断。

第二步：智能分类——按功能模块聚合

这是整个技能的核心价值所在。你需要：

1. 识别功能模块关键词

   • 拌合站（发料、管理、配合比）
   • 供应商发货（原型、H5、进度）
   • 实验室成品（报告、配合比、数据）
   • 项目部发货（申请、进度）
   • 电子签名
   • 表结构设计
   • 前端基础设施

2. 语义聚合原则

   • 相同业务主题的任务归为一类
   • 不同工作阶段（需求讨论、设计、开发）的同一模块合并
   • 例如：

     周一：优化拌合站表结构
     周二：实现拌合站后端接口
     周三：梳理拌合站业务流程
     → 归类为：拌合站发料管理模块
     

3. 分类输出格式

   {
     "拌合站发料管理模块": [
       "优化拌合站发料管理表结构设计",
       "根据优化后的表结构，开发后端接口",
       "梳理拌合站发料前的基本流程"
     ],
     "供应商发货系统": [
       "优化设计供应商发货原型和项目部发货申请原型",
       "根据原型生成对应的H5页面，协助UI理解业务"
     ]
   }
   

第三步：智能分配工时

一周总工时为 5人/天，需要合理分配到各个功能模块。

分配算法：

1. 基础权重：按条目数量初步分配

   • 例如：模块A有3个条目，模块B有2个条目 → 初步比例 3:2

2. 复杂度调整：

   • 会议讨论：权重 0.8
   • 需求分析、流程梳理：权重 1.0
   • 设计（表结构、原型）：权重 1.2
   • 开发（后端接口、H5页面）：权重 1.5
   • 调研、总结：权重 1.0

3. 智能取整：

   • 优先分配整数工时
   • 重要模块可以是 1.5、2.5（避免0.3、0.7这样的碎片）
   • 确保总和精确为 5

示例：

拌合站发料管理（4项任务，含设计+开发）→ 2.0人/天
供应商发货系统（3项任务，含原型+H5）→ 1.5人/天
实验室成品管理（2项任务，含数据库设计）→ 1.0人/天
前端基础设施（1项任务）→ 0.5人/天

第四步：生成Word文档

使用 scripts/generate_report.py 脚本直接生成周报。

工作流：

1. 准备JSON数据：

   {
     "name": "谭飞",
     "title": "后端研发",
     "date": "20251230",
     "tasks": [
       {
         "category": "拌合站发料管理模块",
         "items": [
           "优化拌合站发料管理表结构设计",
           "根据优化后的表结构，开发拌合站发料管理后端接口",
           "梳理拌合站发料前的基本流程"
         ],
         "workload": 2.0
       }
     ]
   }
   

2. 调用脚本生成文档：

   # 首先需要安装python-docx
   pip install python-docx --break-system-packages
   
   # 生成周报（脚本会自动创建完整的Word文档）
   python scripts/generate_report.py \
     /tmp/report_data.json \
     "/mnt/user-data/outputs/周报_20251230.docx"
   

3. 将生成的文档呈现给用户

生成的文档格式：

• 标题居中：周报_YYYYMMDD
• 表格结构：姓名 | 职责 | 任务 | 工时(人/天)
• 每个归类独占一行，任务内容以 1、2、3 展开
• 工时居中对齐，总计精确为 5 人/天

关键设计决策

为什么一个归类占据一行？

这是整个技能的核心设计哲学。

当领导打开你的周报，他们的眼睛不是在”阅读文字”，而是在”扫描模式”：

• 第一眼 → 看到四行 → “这周推进了四个模块”
• 第二眼 → 看右侧工时 → “2人/天是核心，其他是支线”
• 第三眼 → 进入某一行 → “这个模块包含了哪些具体工作”

一个归类一行，建立的是信息的层次感。 它让阅读者自主选择深入的层级，而不是被一大段文字淹没。每一行都是一个独立的认知单元，一个清晰的视觉焦点。

表格内部的 1、2、3 条目化展开，是第二层叙事——当阅读者决定深入某个模块时，他们看到的是有序、可追溯的工作细节。

这种设计尊重了人类注意力的运作方式：先全局，再局部；先模式，再细节。

为什么按功能模块分类？

因为这更符合业务视角。领导关心的是”哪些业务模块在推进”，而不是”你每天做了什么”。

为什么智能分配工时而非让用户手动？

用户的认知负担已经够重了（需要整理5天的工作）。自动化这个过程，让他们专注于提供内容。

为什么直接生成而非依赖模板？

模板是一种伪灵活性。它让用户误以为自己在”自定义格式”，但实际上增加了维护成本和出错可能。

周报的格式是固定的、可预测的——它应该被编码在系统中，而不是存储在一个需要用户维护的外部文件里。当格式本身就是标准时，模板不是工具，而是摩擦力。

使用 python-docx 直接生成完整文档，让脚本承载格式知识，消除了不必要的依赖，让整个流程更可靠、更简洁。

交互示例

用户输入：

生成周报，本周工作内容：
1. 会议讨论表结构设计
2. 优化拌合站发料管理表结构设计
1. 根据优化后的表结构，优化拌合站发料管理后端接口
2. 协助前端优化电子签名
1. 梳理拌合站发料前的基本流程
2. 设计实验室成品主表
1. 根据客户反馈，优化设计供应商发货原型
2. 根据原型生成对应的H5页面

系统输出：

我已经为你整理好本周的工作内容：

📊 工作总结：
✓ 拌合站发料管理模块（2人/天）
  1. 会议讨论表结构设计
  2. 优化拌合站发料管理表结构设计
  3. 根据优化后的表结构，优化拌合站发料管理后端接口
  4. 梳理拌合站发料前的基本流程

✓ 供应商发货系统（1.5人/天）
  1. 根据客户反馈，优化设计供应商发货原型
  2. 根据原型生成对应的H5页面

✓ 实验室成品管理模块（1人/天）
  1. 设计实验室成品主表

✓ 电子签名功能优化（0.5人/天）
  1. 协助前端优化电子签名

[生成的周报文档]

技术实现细节

依赖管理

pip install python-docx --break-system-packages

脚本说明

• scripts/generate_report.py：核心生成脚本
  • 直接创建完整的Word文档
  • 根据JSON数据填充表格
  • 自动设置格式和样式（标题居中、表头加粗、工时对齐）

文件输出

• 生成的文档统一放在 /mnt/user-data/outputs/ 供用户下载
• 文件命名格式：周报_YYYYMMDD.docx

持续优化方向

1. 更精细的分类算法：支持自定义分类规则
2. 工时分配的可调性：允许用户微调某些模块的工时
3. 多模板支持：适配不同公司的周报格式
4. 历史周报分析：基于过去的周报，预测常见模块和工时分布