weekly-report

# Weekly Report Assistant

这是一个专门用于生成个人工作周报的技能。它可以帮助你将零散的工作记录整理成结构清晰的规范周报，并将其转换为正式的 Word 文档。

## 依赖环境 (Prerequisites)

此技能需要以下 Python 库支持：
- `python-docx` - 用于读取和生成 Word 文档
- `markdown` - 用于解析 Markdown 格式
- `beautifulsoup4` - 用于 HTML 处理

如果运行脚本时发现缺少依赖，可安装这些库。

## 工作流程 (Workflows)

### 场景 1: 从工作内容生成周报

**触发条件**: 用户提供了本周工作内容和下周工作计划，或要求整理工作记录

- **Step 1**: 收集周报所需信息
  - 检查用户是否提供了姓名（或部门）
  - 检查用户是否提供了工作内容描述
  - 检查用户是否提供了下周工作计划
  - **错误处理**: 如果关键信息缺失，明确告知用户需要补充哪些内容，不要跳过直接生成

- **Step 2**: 获取周报日期范围
  - 优先从用户输入中提取日期信息（如"3月10日-14日"、"这周"等）
  - 如果用户未提供日期，调用 `scripts/weekly_range.py` 自动计算当前周的日期范围
  - 将日期统一格式化为 `yyyy.mm.dd-yyyy.mm.dd` 格式（如 `2026.03.10-2026.03.14`）
  - 向用户确认提取到的日期范围是否正确

- **Step 3**: 内容整理与润色
  - **工作润色**: 将口语化描述改写为客观、专业的书面语
  - **内容提炼**: 聚焦工作成果和关键进展，去除冗余过程描述
  - **数据保留**: 如有具体数据（如"提升50%"、"修复3个bug"），优先保留
  - **结构整理**: 按工作主题或项目分条归纳，每条内容独立且完整

- **Step 4**: 生成 Markdown 周报
  - 按照 [输出格式模板](#outputformat) 组织内容
  - 使用标题作为文件名保存，格式：`工作周报-{姓名}-{开始日期}-{结束日期}.md`
  - 例如：`工作周报-张三-2026.03.10-2026.03.14.md`

- **Step 5**: 用户确认
  - 展示生成的 Markdown 预览
  - 告知 Markdown 文件保存路径
  - 询问用户是否满意，或是否需要调整（如：修改措辞、添加/删除工作项）
  - 询问是否需要转换为 Word 文档

### 场景 2: Markdown 转 Word

**触发条件**: 用户已有 Markdown 格式的周报，需要转换为 Word 文档

- **Step 1**: 确认转换需求
  - 确认源 Markdown 文件路径
  - **自动命名**: Word 文档名称与 Markdown 标题保持一致
  - 如 `工作周报-张三-2026.03.10-2026.03.14.md` → `工作周报-张三-2026.03.10-2026.03.14.docx`
  - 用户可以指定其他文件名或路径

- **Step 2**: 执行转换
  - **必须**使用 `scripts/md_to_docx.py` 脚本进行转换
  - 命令格式: `python3 scripts/md_to_docx.py <input.md> <output.docx>`
  - 验证输出文件是否成功生成

- **Step 3**: 交付结果
  - 告知用户 Word 文档的保存路径
  - 简要说明文档包含的内容

## 工具脚本说明 (Tools Reference)

### weekly_range.py - 获取当前周日期范围

**用途**: 自动计算当前周（周一至周五）的日期范围

**用法**:
```bash
scripts/weekly_range.py
```

**输出**: 返回格式化的周期字符串

**示例**:
```bash
scripts/weekly_range.py
# 输出: {"start": "2026.03.10", "end": "2026.03.14"}
```

**错误处理**:
- 如果脚本执行失败 → 手动询问用户确认日期范围

### md_to_docx.py - Markdown 转 Word

**用途**: 将 Markdown 格式的周报转换为格式规范的 Word 文档

**用法**:
```bash
scripts/md_to_docx.py <markdown_file_path> <word_output_path>
```

**示例**:
```bash
scripts/md_to_docx.py 工作周报-张三-2026.03.10-2026.03.14.md 工作周报-张三-2026.03.10-2026.03.14.docx
```

**功能特性**:
- 自动应用模板格式（template.docx）
- 支持标题层级转换
- 保持列表和段落格式

## OutputFormat

请严格按照以下 Markdown 格式生成个人工作周报：

```markdown
# 工作周报-{姓名}-{开始日期}-{结束日期}
<!-- 日期格式: yyyy.mm.dd，如 2026.03.10 -->

## 一、本周工作

{50-100字的工作总结，概括本周主要成果和进展}，具体工作成果如下：

1、{工作内容第一条，不要分段，一句话或两句话描述完整}

2、{工作内容第二条，不要分段，聚焦成果}

3、{工作内容第三条（可根据实际数量增减）}

## 二、下周工作计划

1、{下周工作计划第一条，简明扼要}

2、{下周工作计划第二条}

3、{下周工作计划第三条（可根据实际数量增减）}
```

### 格式说明

| 元素 | 格式要求 |
|------|---------|
| 文档标题 | `# 工作周报-{姓名}-{开始日期}-{结束日期}` |
| 工作总结 | 50-100字，客观概括，引出后续具体工作项 |
| 工作内容 | `数字、内容`，如 `1、完成登录模块开发`，不分段，一句话说清楚 |
| 下周计划 | `## 二、下周工作计划` 下使用数字编号列表 |

### 日期处理规则

**自动获取**:
优先调用 `scripts/weekly_range.py` 自动计算当前周日期，支持从用户输入中识别的格式包括：
- `3.10-3.14` → 转换为 `2026.03.10-2026.03.14`（年份取当前年）
- `3月10日-14日` → 转换为 `2026.03.10-2026.03.14`
- `2026.03.10-03.14` → 转换为 `2026.03.10-2026.03.14`
- `这周`、`本周` → 调用脚本自动计算

**手动确认**:
- 获取日期后，向用户确认: "检测到周报日期为 2026.03.10-2026.03.14，是否正确？"
- 如果无法自动获取，询问: "请提供周报的时间范围（如：2026.03.10-2026.03.14）"

## 示例 (Examples)

### 示例 1: 从工作内容生成周报

**输入**:
用户说："帮我写一下这周的周报，我叫张三，这周主要做了登录模块的开发，修了几个bug，还和产品开了需求评审会，下周打算做首页功能。"

**执行步骤**:
1. 识别姓名：张三
2. 运行: `scripts/weekly_range.py` 获取日期范围
3. 润色内容，提炼主要工作项
4. 生成 Markdown 周报

**输出**:
```markdown
# 工作周报-张三-2026.03.10-2026.03.14

## 一、本周工作

本周主要完成了登录模块的开发工作，修复了多个功能性问题，并参与了产品需求评审，具体工作成果如下：

1、完成用户登录模块的开发，实现了用户名密码登录及 Token 鉴权功能，通过联调测试。

2、排查并修复了若干已知问题，提升了系统稳定性。

3、参与产品需求评审会议，对下阶段功能需求进行确认和拆解。

## 二、下周工作计划

1、开始首页功能模块的设计与开发。

2、与后端团队对接首页所需接口，完成接口文档确认。

3、持续跟进本周遗留问题的修复验证。
```

### 示例 2: 直接提供结构化内容

**输入**:
用户粘贴："本周工作：1. API接口开发 2. 代码审查 3. 编写文档。下周计划：1. 压力测试 2. 上线准备。"

**输出**:
直接整理润色成标准格式的 Markdown（同上格式）

### 示例 3: Markdown 转 Word

**输入**:
用户说："帮我把 工作周报-张三-2026.03.10-2026.03.14.md 转成 Word 文档"

**执行步骤**:
1. 读取 Markdown 文件的标题
2. 自动使用与标题一致的文件名
3. 运行转换命令:

```bash
python3 scripts/md_to_docx.py 工作周报-张三-2026.03.10-2026.03.14.md 工作周报-张三-2026.03.10-2026.03.14.docx
```

**输出**:
"已成功将 Markdown 转换为 Word 文档，保存在: 工作周报-张三-2026.03.10-2026.03.14.docx"

## 最佳实践 (Best Practices)

- **客观专业**: 保持语气客观、专业，避免口语化表达（如"搞定了"、"弄好了"）
- **精炼准确**: 每条工作项应言简意赅，聚焦结果而非过程，不超过两句话
- **数据支撑**: 如有具体数据（如"提升50%"、"修复3个bug"），优先保留
- **结构清晰**: 严格遵守各级标题结构，工作项与计划项分开呈现
- **完整性**: 本周工作和下周计划均需填写，不可缺失任一部分
- **文件命名一致**: Markdown 文件和 Word 文档的文件名应与标题保持一致

## 常见错误处理 (Error Handling)

| 问题 | 处理方式 |
|------|---------|
| 未提供姓名 | "请提供您的姓名，以便生成周报标题" |
| 工作内容为空 | "请描述您本周的工作内容，以便整理周报" |
| 下周计划缺失 | "请补充下周工作计划，格式要求：简要说明下周主要工作方向" |
| 日期未提供 | 调用 `scripts/weekly_range.py` 自动获取，失败则询问用户 |
| 脚本执行失败 | "脚本执行出错，请检查依赖是否已安装：`pip install python-docx markdown beautifulsoup4`" |

## 提示词优化建议

如果用户说：
- "写一下这周的工作" → 询问姓名和工作内容，或直接请用户粘贴
- "帮我整理一下工作" → 确认是要生成个人周报
- "把Markdown转成Word" → 确认文件路径并执行转换
- "生成周报" → 询问数据来源（口述/文本）和姓名