MarioYang
/
report_skill_expm
forked from Zhubei_iXD/report_skill_expm
1
0
Fork 0
Code Pull Requests Activity

feat: improve format

This commit is contained in:
insleker 2026-01-19 12:41:06 +08:00
parent 69c955fd57
commit 0db7c83733
14 changed files with 171 additions and 1440 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
skills/week_report_gen/README.md → .claude/skills/week_report_gen/README.md
View File

1
skills/week_report_gen/SKILL.md → .claude/skills/week_report_gen/SKILL.md
View File

@ -295,6 +295,7 @@ print(summary_data)
- Column structure - Column structure
- Separator rows between projects - Separator rows between projects
- Appropriate column widths - Appropriate column widths
- **Template colors and styles**: When a template file is provided, all cell colors, fonts, borders, and other styling from the template's first 4 rows (headers) are automatically preserved in the output
6. **Multiple Team Members**: When multiple people work on the same project, their names are combined in the "參與人員" column and hours are summed. 6. **Multiple Team Members**: When multiple people work on the same project, their names are combined in the "參與人員" column and hours are summed.

162
skills/week_report_gen/generate_report.py → .claude/skills/week_report_gen/generate_report.py
View File

@ -8,9 +8,98 @@ import pandas as pd
import openpyxl import openpyxl
from datetime import datetime from datetime import datetime
from openpyxl.styles import Font, Alignment, PatternFill, Border, Side from openpyxl.styles import Font, Alignment, PatternFill, Border, Side
from copy import copy
import os import os
# Style constants for consistent coloring
HEADER_FILL_COLOR = 'FF2F75B5' # Blue header background
DATA_FILL_COLOR = 'FFE7E6E6' # Light gray data background
WHITE_BORDER = Border(
left=Side(style='thin', color='FFFFFFFF'),
right=Side(style='thin', color='FFFFFFFF'),
top=Side(style='thin', color='FFFFFFFF'),
bottom=Side(style='thin', color='FFFFFFFF')
)
def copy_cell_style(source_cell, target_cell):
"""
Copy all styling from source cell to target cell.
"""
if source_cell.has_style:
target_cell.font = copy(source_cell.font)
target_cell.border = copy(source_cell.border)
target_cell.fill = copy(source_cell.fill)
target_cell.number_format = copy(source_cell.number_format)
target_cell.protection = copy(source_cell.protection)
target_cell.alignment = copy(source_cell.alignment)
def copy_sheet_with_format(source_sheet, target_sheet, max_rows=10):
"""
Copy formatting from source sheet template to target sheet.
Only copies the first few rows (headers) to preserve template styling.
"""
# Copy row heights
for row_idx in range(1, max_rows + 1):
if row_idx in source_sheet.row_dimensions:
target_sheet.row_dimensions[row_idx].height = source_sheet.row_dimensions[row_idx].height
# Copy column widths
for col_letter in ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K']:
if col_letter in source_sheet.column_dimensions:
target_sheet.column_dimensions[col_letter].width = source_sheet.column_dimensions[col_letter].width
# Copy cell formatting for header rows (first max_rows)
for row_idx in range(1, max_rows + 1):
for col_idx in range(1, 12): # Columns A-K
source_cell = source_sheet.cell(row=row_idx, column=col_idx)
target_cell = target_sheet.cell(row=row_idx, column=col_idx)
# Copy style
copy_cell_style(source_cell, target_cell)
# Copy merged cells info (we'll handle merging separately)
# Copy merged cells from template (only header rows)
for merged_range in source_sheet.merged_cells.ranges:
if merged_range.min_row <= max_rows and merged_range.max_row <= max_rows:
try:
target_sheet.merge_cells(str(merged_range))
except:
pass # Skip if already merged or invalid
def style_header_row(ws, row_idx, template_cell=None, col_start=2, col_end=10):
"""
Apply header styling (blue fill, bold, centered, white grid) to a row.
If template_cell is provided, its style is copied before applying borders.
"""
for col_idx in range(col_start, col_end + 1):
cell = ws.cell(row=row_idx, column=col_idx)
if template_cell and template_cell.has_style:
copy_cell_style(template_cell, cell)
else:
cell.fill = PatternFill(start_color=HEADER_FILL_COLOR, end_color=HEADER_FILL_COLOR, fill_type='solid')
cell.font = Font(bold=True)
cell.alignment = Alignment(horizontal='center', vertical='center', wrap_text=True)
cell.border = WHITE_BORDER
def style_data_row(ws, row_idx, fill_color=DATA_FILL_COLOR, col_start=2, col_end=10):
"""
Apply data row styling (fill, wrap text, white grid) to a row.
"""
data_fill = PatternFill(start_color=fill_color, end_color=fill_color, fill_type='solid')
data_align = Alignment(vertical='top', wrap_text=True)
for col_idx in range(col_start, col_end + 1):
cell = ws.cell(row=row_idx, column=col_idx)
cell.fill = data_fill
cell.alignment = data_align
cell.border = WHITE_BORDER
def read_cost_report(file_path): def read_cost_report(file_path):
""" """
Read cost report and parse the data. Read cost report and parse the data.
@ -150,15 +239,39 @@ def generate_weekly_report(input_file, output_file, template_file=None, team_nam
if template_file and os.path.exists(template_file): if template_file and os.path.exists(template_file):
print(f"Loading template from: {template_file}") print(f"Loading template from: {template_file}")
wb = openpyxl.load_workbook(template_file) wb = openpyxl.load_workbook(template_file)
# Get the template sheet (usually the first or named '周报示例')
template_sheet = None
for sheet_name_candidate in ['周报示例', wb.sheetnames[0]]:
if sheet_name_candidate in wb.sheetnames:
template_sheet = wb[sheet_name_candidate]
break
# Create new sheet for this week # Create new sheet for this week
sheet_name = f"{end_date.strftime('%Y%m%d')}-{team_name}" sheet_name = f"{end_date.strftime('%Y%m%d')}-{team_name}"
ws = wb.create_sheet(sheet_name, 0) # Insert at beginning ws = wb.create_sheet(sheet_name, 0) # Insert at beginning
# Copy formatting from template if available
if template_sheet:
print(f"Copying formatting from template sheet: {template_sheet.title}")
copy_sheet_with_format(template_sheet, ws, max_rows=4)
# Unmerge cells beyond row 4 to allow data writing
# Keep header merges (rows 1-3) but clear any others
merged_ranges_to_remove = []
for merged_range in ws.merged_cells.ranges:
if merged_range.min_row > 4:
merged_ranges_to_remove.append(merged_range)
for merged_range in merged_ranges_to_remove:
ws.unmerge_cells(str(merged_range))
else: else:
print("Creating new workbook (no template provided)") print("Creating new workbook (no template provided)")
wb = openpyxl.Workbook() wb = openpyxl.Workbook()
ws = wb.active ws = wb.active
sheet_name = f"{end_date.strftime('%Y%m%d')}-{team_name}" sheet_name = f"{end_date.strftime('%Y%m%d')}-{team_name}"
ws.title = sheet_name ws.title = sheet_name
template_sheet = None
# Write header # Write header
ws['B1'] = '弘訊科技股份有限公司' ws['B1'] = '弘訊科技股份有限公司'
@ -171,6 +284,10 @@ def generate_weekly_report(input_file, output_file, template_file=None, team_nam
for col_idx, header in enumerate(headers, start=2): # Start from column B for col_idx, header in enumerate(headers, start=2): # Start from column B
ws.cell(row=4, column=col_idx, value=header) ws.cell(row=4, column=col_idx, value=header)
# Ensure header row is uniformly blue (including the 下周計畫 column)
template_header_cell = template_sheet.cell(row=4, column=2) if 'template_sheet' in locals() and template_sheet else None
style_header_row(ws, row_idx=4, template_cell=template_header_cell)
# Write data starting from row 5 # Write data starting from row 5
current_row = 5 current_row = 5
for idx, row_data in report_df.iterrows(): for idx, row_data in report_df.iterrows():
@ -183,45 +300,36 @@ def generate_weekly_report(input_file, output_file, template_file=None, team_nam
ws.cell(row=current_row, column=8, value=row_data['交付物']) ws.cell(row=current_row, column=8, value=row_data['交付物'])
ws.cell(row=current_row, column=9, value=row_data['代碼上傳']) ws.cell(row=current_row, column=9, value=row_data['代碼上傳'])
ws.cell(row=current_row, column=10, value=row_data['下周計畫']) ws.cell(row=current_row, column=10, value=row_data['下周計畫'])
# Apply consistent gray fill and white borders to data row
style_data_row(ws, row_idx=current_row)
current_row += 1 current_row += 1
# Add separator row (except after last entry) # Add separator row (except after last entry)
if idx < len(report_df) - 1: if idx < len(report_df) - 1:
current_row += 1
ws.cell(row=current_row, column=2, value='專案名稱') ws.cell(row=current_row, column=2, value='專案名稱')
for col_idx, header in enumerate(headers[1:], start=3): for col_idx, header in enumerate(headers[1:], start=3):
ws.cell(row=current_row, column=col_idx, value=header) ws.cell(row=current_row, column=col_idx, value=header)
# Apply blue header styling to separator row (no blank white spacer)
style_header_row(ws, row_idx=current_row, template_cell=template_header_cell)
current_row += 1 current_row += 1
# Apply formatting # Apply formatting (only if no template was used)
header_fill = PatternFill(start_color='D3D3D3', end_color='D3D3D3', fill_type='solid') if not template_sheet:
bold_font = Font(bold=True)
center_align = Alignment(horizontal='center', vertical='center', wrap_text=True)
wrap_align = Alignment(vertical='top', wrap_text=True)
# Format title rows # Format title rows
ws['B1'].font = Font(bold=True, size=14) ws['B1'].font = Font(bold=True, size=14)
ws['B1'].alignment = center_align ws['B1'].alignment = Alignment(horizontal='center', vertical='center', wrap_text=True)
ws['B2'].font = Font(bold=True, size=12) ws['B2'].font = Font(bold=True, size=12)
ws['B2'].alignment = center_align ws['B2'].alignment = Alignment(horizontal='center', vertical='center', wrap_text=True)
ws['B3'].font = Font(size=10, italic=True) ws['B3'].font = Font(size=10, italic=True)
ws['B3'].alignment = wrap_align ws['B3'].alignment = Alignment(vertical='top', wrap_text=True)
# Merge cells for headers # Merge cells for headers
ws.merge_cells('B1:J1') ws.merge_cells('B1:J1')
ws.merge_cells('B2:J2') ws.merge_cells('B2:J2')
ws.merge_cells('B3:J3') ws.merge_cells('B3:J3')
# Format column headers and separator rows
for row in range(1, current_row + 1):
cell_b = ws.cell(row=row, column=2)
if cell_b.value == '專案名稱' or row == 4:
for col_idx in range(2, 11):
cell = ws.cell(row=row, column=col_idx)
cell.fill = header_fill
cell.font = bold_font
cell.alignment = center_align
# Set column widths # Set column widths
column_widths = { column_widths = {
'B': 20, # 專案名稱 'B': 20, # 專案名稱
@ -237,8 +345,22 @@ def generate_weekly_report(input_file, output_file, template_file=None, team_nam
for col, width in column_widths.items(): for col, width in column_widths.items():
ws.column_dimensions[col].width = width ws.column_dimensions[col].width = width
else:
# Template was used - only apply formatting to separator rows and data cells
# Get header formatting from row 4
header_cells = [ws.cell(row=4, column=col_idx) for col_idx in range(2, 11)]
# Apply header formatting to separator rows
for row in range(5, current_row + 1):
cell_b = ws.cell(row=row, column=2)
if cell_b.value == '專案名稱':
for col_idx in range(2, 11):
target_cell = ws.cell(row=row, column=col_idx)
source_cell = ws.cell(row=4, column=col_idx)
copy_cell_style(source_cell, target_cell)
# Apply wrap text to all data cells # Apply wrap text to all data cells
wrap_align = Alignment(vertical='top', wrap_text=True)
for row in range(5, current_row): for row in range(5, current_row):
for col in range(2, 11): for col in range(2, 11):
ws.cell(row=row, column=col).alignment = wrap_align ws.cell(row=row, column=col).alignment = wrap_align

0
skills/week_report_gen/references/cost-report-2026-01-16-T-16-22-3620260116-7-1r1n4h.xls → .claude/skills/week_report_gen/references/cost-report-2026-01-16-T-16-22-3620260116-7-1r1n4h.xls
View File

0
skills/week_report_gen/references/項目週報-台灣-軟體部-智能控制組 (20260115).xlsx → .claude/skills/week_report_gen/references/項目週報-台灣-軟體部-智能控制組 (20260115).xlsx
View File

0
skills/week_report_gen/references/項目週報-模板.xlsx → .claude/skills/week_report_gen/references/項目週報-模板.xlsx
View File

3
.gitignore vendored
View File

@ -161,3 +161,6 @@ cython_debug/
#.idea/ #.idea/
uv.lock uv.lock
temp/
output/
logs/

166
README.md
View File

@ -8,30 +8,6 @@ This repository contains AI skills for automated report generation. Currently in
Automatically generates weekly project reports (項目週報) from exported Excel time tracking data. Automatically generates weekly project reports (項目週報) from exported Excel time tracking data.
**Features:**
- Reads cost report Excel exports from project management systems
- Aggregates work hours by person and project
- Generates formatted weekly reports following company templates
- Auto-populates team members, work hours, and progress notes
- Creates professional Excel output with proper formatting
**Use Cases:**
- Weekly project status reporting
- Time tracking data transformation
- Team productivity summaries
- Management reporting automation
**Quick Start:**
```bash
cd skills/week_report_gen
python generate_report.py
```
**Documentation:**
- [SKILL.md](skills/week_report_gen/SKILL.md) - Comprehensive skill documentation
- [README.md](skills/week_report_gen/README.md) - Usage guide and examples
- [QUICK_REFERENCE.md](skills/week_report_gen/QUICK_REFERENCE.md) - AI assistant reference
## Getting Started ## Getting Started
### Prerequisites ### Prerequisites
@ -39,146 +15,4 @@ python generate_report.py
```bash ```bash
# Create virtual environment and install dependencies # Create virtual environment and install dependencies
uv sync uv sync
# Activate virtual environment (optional - uv run handles this)
.venv\Scripts\activate # Windows
source .venv/bin/activate # Linux/Mac
``` ```
> **💡 Tip**: This project uses `pyproject.toml` for reliable dependency management with uv.
> See [UV_SETUP_GUIDE.md](UV_SETUP_GUIDE.md) for detailed setup instructions and best practices.
### Using with AI Assistants
Simply tell your AI assistant (GitHub Copilot, Claude, etc.):
> "Generate a weekly report from the cost report file"
The AI will automatically:
1. Read the skill documentation
2. Process the input data
3. Generate a formatted report
4. Show you a summary
### Manual Usage
```python
from skills.week_report_gen.generate_report import generate_weekly_report
# Generate report
output_file, summary = generate_weekly_report(
input_file='path/to/cost-report.xls',
output_file='path/to/weekly-report.xlsx'
)
print(f"Report saved: {output_file}")
```
## Repository Structure
```
report_skill_expm/
├── README.md # This file
├── skills/
│ └── week_report_gen/ # Weekly report generator skill
│ ├── SKILL.md # Skill documentation
│ ├── README.md # User guide
│ ├── QUICK_REFERENCE.md # AI assistant reference
│ ├── generate_report.py # Main script
│ └── references/ # Sample files and templates
│ ├── cost-report-*.xls # Example input
│ ├── 項目週報-模板.xlsx # Standard template
│ └── 項目週報-*.xlsx # Example outputs
└── .venv/ # Virtual environment (created)
```
## Input & Output Examples
### Input: Cost Report
```
日期 使用者 活動 專案 單位
2026-01-12 ben sung Development masterXXX 8
2026-01-12 Ryan Hsueh - AXEL PLC 8
2026-01-13 傑 羅 Development CNC Library 移植 4
```
### Output: Weekly Report
```
弘訊科技股份有限公司
2026年度週報(01月12日-01月16日）
專案名稱 參與人員 工時 本周主要進展
──────────────────────────────────────────────────
AXEL PLC Ryan Hsueh 48.0 -
masterXXX ben sung 15.0 Development
migrate to entry based sdo queue
CNC Library移植 傑 羅 8.0 Development
程式碼整理及重構
```
## Development
### Adding New Skills
1. Create a new directory under `skills/`
2. Add a `SKILL.md` file with comprehensive documentation
3. Implement the skill functionality
4. Add examples and tests
5. Update this README
### Testing
```bash
# Test the weekly report generator
cd skills/week_report_gen
python generate_report.py
```
## Use Cases
### 1. Weekly Team Reports
Transform time tracking exports into management-ready weekly reports automatically.
### 2. Project Status Updates
Quickly see which projects are active, who's working on them, and how many hours were invested.
### 3. Resource Allocation Analysis
Understand how team members' time is distributed across projects.
### 4. Management Reporting
Generate standardized reports for management review with minimal manual effort.
## Roadmap
Future skills being considered:
- **Monthly Summary Generator**: Aggregate weekly reports into monthly summaries
- **Project Timeline Generator**: Visualize project progress over time
- **Resource Utilization Report**: Analyze team member utilization rates
- **Cost Analysis Report**: Transform time data into cost estimates
- **Multi-team Comparison**: Compare metrics across different teams
## Contributing
Contributions welcome! To add a new skill:
1. Follow the existing skill structure
2. Provide comprehensive documentation
3. Include example files
4. Test thoroughly
5. Submit a pull request
## License
MIT License - See individual skill files for specific licensing information.
## Support
For questions or issues:
1. Check the skill-specific documentation in `skills/[skill_name]/`
2. Review example files in `references/` directories
3. Open an issue for bugs or feature requests
## Acknowledgments
This project demonstrates how AI skills can automate routine reporting tasks, saving time and reducing errors in data transformation and report generation workflows.

292
UV_SETUP_GUIDE.md
View File

@ -1,292 +0,0 @@
# Quick Start Guide for UV-based Setup
## Why UV + pyproject.toml?
✅ **Reliable**: All dependencies locked to specific versions
✅ **Fast**: UV is significantly faster than pip
✅ **Reproducible**: Same environment across all machines
✅ **Simple**: One command to set up everything
✅ **Modern**: Using Python packaging best practices
## Installation
### First Time Setup
```bash
# Install uv (if not already installed)
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or with pip
pip install uv
```
### Project Setup
```bash
# Clone or navigate to the repository
cd report_skill_expm
# Create virtual environment and install all dependencies
uv sync
# That's it! All dependencies are now installed and locked
```
## Usage
### Option 1: Using `uv run` (Recommended)
No need to activate the virtual environment - uv handles it automatically:
```bash
# Run the example
uv run python example.py
# Run the report generator directly
uv run python skills/week_report_gen/generate_report.py
# Import and use in Python
uv run python -c "from skills.week_report_gen.generate_report import generate_weekly_report; print('Ready!')"
```
### Option 2: Traditional Virtual Environment
```bash
# Activate the virtual environment
.venv\Scripts\activate # Windows
source .venv/bin/activate # Linux/Mac
# Now you can run Python normally
python example.py
python skills/week_report_gen/generate_report.py
```
## What's in pyproject.toml?
```toml
[project]
name = "report-skill-expm"
version = "1.0.0"
requires-python = ">=3.9"
dependencies = [
"openpyxl>=3.1.0", # Excel file handling
"pandas>=2.0.0", # Data processing
"xlrd>=2.0.0", # Reading .xls files
]
[project.optional-dependencies]
dev = [
"pytest>=7.0.0", # Testing framework
"black>=23.0.0", # Code formatter
"flake8>=6.0.0", # Linter
]
```
## Common Commands
```bash
# Install/update dependencies
uv sync
# Install with dev dependencies
uv sync --extra dev
# Add a new dependency
uv add package-name
# Remove a dependency
uv remove package-name
# Update all dependencies
uv sync --upgrade
# Show installed packages
uv pip list
# Run any Python script
uv run python your_script.py
# Run a specific module
uv run python -m skills.week_report_gen.generate_report
# Start Python REPL with dependencies available
uv run python
```
## Benefits Over Manual pip Installation
### Before (Manual)
```bash
python -m venv .venv
.venv\Scripts\activate
pip install openpyxl pandas xlrd
# Need to remember all packages and versions
# No lock file - different versions on different machines
```
### After (UV + pyproject.toml)
```bash
uv sync
# Done! Everything locked and reproducible
```
## Dependency Management
### Adding Dependencies
```bash
# Add a runtime dependency
uv add requests
# Add a development dependency
uv add --dev pytest-cov
# Add with version constraint
uv add "pandas>=2.0,<3.0"
```
### Updating Dependencies
```bash
# Update all dependencies
uv sync --upgrade
# Update specific package
uv add --upgrade pandas
```
### Lock File
The `uv.lock` file (auto-generated) ensures:
- ✅ Exact versions are used across all environments
- ✅ Transitive dependencies are locked
- ✅ No "works on my machine" issues
- ✅ Fast, deterministic installs
**Commit `uv.lock` to version control!**
## Troubleshooting
### "uv: command not found"
Install uv first:
```bash
pip install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### "No module named 'xxx'"
Make sure you've run `uv sync`:
```bash
uv sync
```
### Virtual Environment Not Found
Recreate it:
```bash
rm -rf .venv # or rmdir /s .venv on Windows
uv sync
```
### Import Errors
Use `uv run` to automatically activate the environment:
```bash
uv run python your_script.py
```
## CI/CD Integration
### GitHub Actions
```yaml
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install uv
run: pip install uv
- name: Install dependencies
run: uv sync
- name: Run tests
run: uv run pytest
```
### GitLab CI
```yaml
test:
script:
- pip install uv
- uv sync
- uv run pytest
```
## Migration from requirements.txt
If you have an old `requirements.txt`:
```bash
# Import from requirements.txt
uv add $(cat requirements.txt)
# Or manually add each package
uv add openpyxl pandas xlrd
```
## Best Practices
1. **Always commit `uv.lock`** - Ensures reproducible builds
2. **Use `uv run`** - Simplifies workflow, no activation needed
3. **Keep pyproject.toml clean** - Only list direct dependencies
4. **Use version constraints** - `>=3.1.0` not `==3.1.0`
5. **Separate dev dependencies** - Use `[project.optional-dependencies]`
## Comparison: pip vs uv
| Feature | pip | uv |
|---------|-----|-----|
| Speed | 🐌 Slow | 🚀 Fast (10-100x) |
| Lock file | requirements.txt (manual) | uv.lock (automatic) |
| Resolver | Sometimes inconsistent | Always consistent |
| Parallel installs | No | Yes |
| Built-in venv | Need separate commands | Integrated |
## Resources
- [UV Documentation](https://github.com/astral-sh/uv)
- [Python Packaging Guide](https://packaging.python.org/)
- [pyproject.toml Specification](https://peps.python.org/pep-0621/)
---
**Quick Reference Card**
```bash
# Setup
uv sync # Install everything
# Run
uv run python app.py # Execute with dependencies
# Manage
uv add pkg # Add dependency
uv remove pkg # Remove dependency
uv sync --upgrade # Update all
# Dev
uv sync --extra dev # Install dev dependencies
uv run pytest # Run tests
uv run black . # Format code
```

405
skills/week_report_gen/COMPLETE_GUIDE.md
View File

@ -1,405 +0,0 @@
# Weekly Report Generator Skill - Complete Guide
## 🎯 What This Skill Does
The **Weekly Report Generator** (`week_report_gen`) is an AI skill that automatically transforms time tracking data from project management systems into professional weekly project reports (項目週報).
### Key Benefits
✅ **Saves Time**: Automates report generation from raw time tracking data
✅ **Reduces Errors**: Eliminates manual data entry and calculation mistakes
✅ **Consistent Format**: Uses company standard templates every time
✅ **Smart Aggregation**: Automatically groups work by project and team member
✅ **AI-Powered**: Works seamlessly with GitHub Copilot, Claude, and other AI assistants
---
## 📦 What's Included
```
skills/week_report_gen/
├── SKILL.md # Comprehensive technical documentation
├── README.md # User guide with examples
├── QUICK_REFERENCE.md # AI assistant reference guide
├── generate_report.py # Main Python script
└── references/
├── cost-report-*.xls # Example input file
├── 項目週報-模板.xlsx # Standard template
└── 項目週報-*.xlsx # Example outputs
```
---
## 🚀 Quick Start
### 1. Setup (One Time)
```bash
# From repository root: create venv and install all dependencies
uv sync
# Activate it (optional - uv run handles this automatically)
.venv\Scripts\activate # Windows
source .venv/bin/activate # Mac/Linux
```
### 2. Generate Your First Report
**Option A: Using AI Assistant** (Easiest)
Just say:
> "Generate a weekly report from my cost report file"
**Option B: Command Line**
```bash
# From repository root
uv run python skills/week_report_gen/generate_report.py
# Or navigate first
cd skills/week_report_gen
uv run python generate_report.py
```
**Option C: Python Script**
```python
from skills.week_report_gen.generate_report import generate_weekly_report
output_file, summary = generate_weekly_report(
input_file='cost-report.xls',
output_file='weekly-report.xlsx'
)
```
---
## 📊 Input → Output
### Input: Cost Report Excel
Raw time tracking data exported from your project management system.
| 日期 | 使用者 | 活動 | 專案 | 單位 |
|------|--------|------|------|------|
| 2026-01-12 | ben sung | Development | masterXXX | 8 |
| 2026-01-12 | Ryan Hsueh | - | AXEL PLC | 8 |
### Output: Weekly Report Excel
Formatted, professional report ready for management review.
| 專案名稱 | 參與人員 | 工時 | 本周主要進展 | 下周計畫 |
|----------|----------|------|--------------|----------|
| masterXXX | ben sung | 15.0 | Development<br>migrate to entry based sdo queue | _(fill in)_ |
| AXEL PLC | Ryan Hsueh | 48.0 | - | _(fill in)_ |
---
## 🎨 Key Features
### 1. Smart Data Aggregation
- Automatically sums hours by project and person
- Groups multiple entries from the same project
- Combines team members who worked on the same project
### 2. Auto-Population
**Automatically filled:**
- ✅ 專案名稱 (Project name)
- ✅ 參與人員 (Team members)
- ✅ 工時 (Total hours)
- ✅ 本周主要進展 (Progress notes from comments)
**Leave blank for manual input:**
- ⬜ 進度 (Progress percentage)
- ⬜ 交付物 (Deliverables)
- ⬜ 代碼上傳 (Code upload status)
- ⬜ 下周計畫 (Next week's plan)
### 3. Professional Formatting
- Company header and branding
- Proper column widths
- Header formatting with gray background
- Separator rows between projects
- Text wrapping for long entries
- Merged cells for titles
### 4. Date Range Detection
Automatically extracts the reporting period from the data:
```
2026年度週報(01月12日-01月16日）
```
---
## 💡 Usage Examples
### Example 1: Basic Generation
```bash
# Navigate to skill directory
cd skills/week_report_gen
# Run with default settings (uses sample file)
python generate_report.py
# Output: 項目週報-智能控制組-20260116.xlsx
```
### Example 2: Custom Files
```bash
# Specify input and output files
python generate_report.py \
"path/to/your-cost-report.xls" \
"path/to/output-weekly-report.xlsx"
```
### Example 3: Python Integration
```python
from generate_report import generate_weekly_report
# Generate report for specific team
output, summary = generate_weekly_report(
input_file='data/cost-report.xls',
output_file='reports/weekly-20260116.xlsx',
template_file='templates/standard.xlsx',
team_name='研發部-AI組'
)
# View summary
print(f"Generated report with {len(summary)} projects")
print(f"Total hours: {summary['工時'].sum()}")
```
### Example 4: AI Assistant
```
You: "Generate a weekly report from cost-report-2026-01-16.xls for the AI team"
AI: "I'll generate the weekly report for the AI team.
[Processing...]
✓ Report generated successfully!
Summary of 5 projects:
- Project A (Team Member 1, Team Member 2, 32 hours)
- Project B (Team Member 3, 16 hours)
...
Report saved to: 項目週報-AI組-20260116.xlsx
Please review and fill in:
- Progress percentages
- Deliverables
- Next week's plan"
```
---
## 📋 After Report Generation
### Manual Steps Required
1. **Open the Excel file** in your spreadsheet application
2. **Review "本周主要進展" (Progress)**
- Check auto-generated progress notes
- Edit for clarity and completeness
- Add any missing accomplishments
3. **Fill in "進度" (Progress %)**
- Enter progress as decimal (0.5 = 50%)
- Example: 0.75 for 75% complete
4. **Add "交付物" (Deliverables)**
- List specific deliverables if any
- Include document names, versions, etc.
5. **Mark "代碼上傳" (Code Upload)**
- Enter "Y" if code was uploaded
- Enter "N" if not applicable
6. **Plan "下周計畫" (Next Week)**
- Outline next week's goals
- Be specific and actionable
7. **Add Visual Materials** (Optional)
- Insert diagrams, screenshots, etc.
- Reference in the header suggestion
---
## 🔧 Customization
### Change Team Name
```python
generate_weekly_report(
input_file='cost.xls',
output_file='report.xlsx',
team_name='您的團隊名稱' # Your team name
)
```
### Adjust Column Widths
Edit `generate_report.py`:
```python
column_widths = {
'B': 25, # Wider project name column
'E': 40, # Wider progress column
# Adjust as needed
}
```
### Modify Grouping Logic
Edit the `format_for_weekly_report()` function to change:
- How projects are grouped
- What information is included in progress
- How team members are listed
---
## 🐛 Troubleshooting
### Error: "Module not found"
**Solution:**
```bash
# Make sure you're in the virtual environment
.venv\Scripts\activate
# Install dependencies
uv pip install openpyxl pandas xlrd
```
### Error: "Column not found"
**Cause:** Input file has different column names
**Solution:**
1. Open the input Excel file
2. Check column names match: 日期, 使用者, 專案, 單位
3. If different, the script will try alternative headers
4. Contact support if issues persist
### Empty or No Output
**Check:**
1. Input file has data (not just headers)
2. Data starts at expected row (usually row 2)
3. File isn't corrupted or password-protected
4. Required columns have values (not all empty)
### Report Looks Wrong
**Verify:**
1. Template file exists and is valid
2. Using correct template for your organization
3. Excel/LibreOffice can open the file
4. File isn't read-only
---
## 📚 Additional Resources
### Documentation Files
- **[SKILL.md](SKILL.md)** - Complete technical documentation
- Detailed API reference
- Function descriptions
- Code examples
- Error handling guide
- **[README.md](README.md)** - Comprehensive user guide
- Feature overview
- Installation instructions
- Usage examples
- Customization options
- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - AI assistant guide
- How to use with AI assistants
- Common patterns
- Troubleshooting for AI
- Best practices
### Example Files
Located in `references/` directory:
- Input example: `cost-report-*.xls`
- Template: `項目週報-模板.xlsx`
- Output example: `項目週報-台灣-軟體部-智能控制組 (20260115).xlsx`
---
## 🎓 Tips & Best Practices
### For Users
1. **Run Weekly**: Generate reports at week-end for best workflow
2. **Review Before Sharing**: Always check auto-generated content
3. **Keep Template Updated**: Update template when format changes
4. **Backup Originals**: Keep raw cost reports for audit trail
5. **Consistent Naming**: Use consistent project names in time tracking
### For Developers
1. **Test with Real Data**: Use actual cost reports for testing
2. **Handle Edge Cases**: Test with empty data, special characters, etc.
3. **Preserve Formulas**: If using formulas, don't hardcode values
4. **Document Changes**: Update SKILL.md when modifying code
5. **Version Control**: Track changes to template and script
### For AI Assistants
1. **Validate First**: Check input file exists before processing
2. **Show Progress**: Display what's being done at each step
3. **Summarize Results**: Show key metrics after generation
4. **Remind Manual Steps**: List fields that need manual input
5. **Handle Errors Gracefully**: Provide helpful error messages
---
## 📞 Support & Contact
### Getting Help
1. **Check Documentation**: Review SKILL.md and README.md
2. **Review Examples**: Look at reference files in `references/`
3. **Test Script**: Run the example script: `python example.py`
4. **Open Issue**: Report bugs or request features
### Reporting Issues
When reporting issues, include:
- Error message (full stack trace)
- Input file format (column names, sample data)
- Expected vs actual output
- Version of Python and libraries
- Operating system
---
## 📝 License
MIT License - See individual skill files for complete terms.
---
## 🙏 Acknowledgments
This skill demonstrates how AI can automate routine reporting tasks, saving valuable time and reducing errors in data transformation workflows.
**Built with:**
- Python 3.x
- openpyxl (Excel file handling)
- pandas (Data processing)
- Love and attention to detail ❤️
---
**Version:** 1.0.0
**Last Updated:** January 16, 2026
**Status:** Production Ready ✅

250
skills/week_report_gen/QUICK_REFERENCE.md
View File

@ -1,250 +0,0 @@
# Weekly Report Generator - Quick Reference
## For AI Assistants (GitHub Copilot/Claude)
When a user asks to generate a weekly report, follow these steps:
### 1. Identify the Request
User might say:
- "Generate a weekly report"
- "Create 項目週報 from cost report"
- "Transform time tracking data into weekly report"
- "Make a weekly project report from the Excel export"
### 2. Read the Skill Documentation
```python
# Read the full skill instructions
read_file('skills/week_report_gen/SKILL.md')
```
### 3. Use the Generate Report Script
```python
# Import and run the generator
from skills.week_report_gen.generate_report import generate_weekly_report
# Generate report with provided file paths
output_file, summary_df = generate_weekly_report(
input_file='path/to/cost-report.xls',
output_file='path/to/output-report.xlsx',
template_file='skills/week_report_gen/references/項目週報-模板.xlsx',
team_name='智能控制組' # Or user-specified team name
)
print(f"✓ Report generated: {output_file}")
print("\nProject Summary:")
for idx, row in summary_df.iterrows():
print(f"\n{row['專案名稱']}")
print(f" Team: {row['參與人員']}")
print(f" Hours: {row['工時']}")
```
### 4. Alternative: Run via Terminal
```bash
cd skills/week_report_gen
python generate_report.py "path/to/cost-report.xls" "path/to/output.xlsx"
```
## Common Usage Patterns
### Pattern 1: User Provides Input File
```
User: "Generate weekly report from cost-report-2026-01-16.xls"
Assistant Actions:
1. Locate the input file
2. Determine output filename (based on date and team)
3. Run generate_weekly_report()
4. Show summary of projects and hours
5. Confirm file saved location
```
### Pattern 2: User Wants to Customize Output
```
User: "Create weekly report for 研發部 team"
Assistant Actions:
1. Ask for input file if not specified
2. Use team_name parameter: team_name='研發部'
3. Generate report
4. Confirm customization applied
```
### Pattern 3: User Has Multiple Cost Reports
```
User: "Generate reports for all cost reports in the folder"
Assistant Actions:
1. List all .xls/.xlsx files in references folder
2. Filter for cost report files
3. Generate report for each
4. Provide summary of all generated reports
```
## Key Functions
### read_cost_report(file_path)
Reads and parses the cost report Excel file.
**Returns**: DataFrame with columns [日期, 使用者, 活動, 專案, 單位, etc.]
### aggregate_work_hours(df)
Groups work hours by user and project.
**Returns**:
- `summary_df`: Aggregated data
- `start_date`: Report start date
- `end_date`: Report end date
### format_for_weekly_report(summary_df)
Transforms aggregated data into weekly report format.
**Returns**: DataFrame ready for Excel output
### generate_weekly_report(input_file, output_file, template_file, team_name)
Main function that orchestrates the entire process.
**Returns**:
- `output_file`: Path to generated report
- `report_df`: Summary DataFrame
## Example AI Responses
### Example 1: Basic Generation
```
User: "Generate a weekly report from the cost report file"
AI Assistant:
"I'll generate the weekly report from your cost report.
[Runs generate_report.py]
✓ Weekly report generated successfully!
Summary of 8 projects:
- AXEL PLC (Ryan Hsueh, 48 hours)
- CNC Library 移植 (傑 羅, 8 hours)
- masterXXX (ben sung, 15 hours)
...
Report saved to: 項目週報-智能控制組-20260116.xlsx
Please review and fill in the following fields:
- 進度 (Progress percentages)
- 交付物 (Deliverables)
- 代碼上傳 (Code upload status)
- 下周計畫 (Next week's plan)"
```
### Example 2: Custom Team Name
```
User: "Create a weekly report for the 研發部-AI組 team"
AI Assistant:
"I'll create a weekly report for the 研發部-AI組 team.
[Runs with team_name='研發部-AI組']
✓ Report generated with custom team name!
File: 項目週報-研發部-AI組-20260116.xlsx"
```
### Example 3: Batch Processing
```
User: "Generate weekly reports for all cost report files"
AI Assistant:
"I found 3 cost report files. Generating reports...
1. cost-report-2026-01-16.xls → 項目週報-20260116.xlsx ✓
2. cost-report-2026-01-09.xls → 項目週報-20260109.xlsx ✓
3. cost-report-2025-12-30.xls → 項目週報-20251230.xlsx ✓
All reports generated successfully!"
```
## Troubleshooting Guide for AI
### Issue: File Not Found
```python
# Check if file exists
import os
if not os.path.exists(input_file):
# List available files
files = os.listdir('skills/week_report_gen/references')
print(f"Available files: {files}")
# Ask user for correct filename
```
### Issue: Missing Columns
```python
# Check what columns are present
import pandas as pd
df = pd.read_excel(input_file, header=1)
print(f"Available columns: {list(df.columns)}")
# Suggest using different header row or file format
```
### Issue: Empty Output
```python
# Check data was loaded
if len(df) == 0:
print("No data found in file. Check:")
print("1. Correct sheet is being read")
print("2. Data starts at expected row")
print("3. File isn't corrupted")
```
## Best Practices for AI Assistants
1. **Always validate input file exists** before processing
2. **Show summary of data** after reading (number of entries, date range, projects)
3. **Display key metrics** in the output (total hours, number of projects, team members)
4. **Remind user of manual fields** that need to be filled in
5. **Provide file location** of generated report clearly
6. **Handle errors gracefully** with helpful error messages
7. **Suggest next steps** after generation (review, fill in fields, etc.)
## Quick Code Snippets
### Check Available Cost Reports
```python
import os
files = [f for f in os.listdir('skills/week_report_gen/references')
if f.startswith('cost-report') and f.endswith(('.xls', '.xlsx'))]
print(f"Found {len(files)} cost report(s): {files}")
```
### Validate Input File Structure
```python
import pandas as pd
df = pd.read_excel(file_path, header=1)
required = ['日期', '使用者', '專案', '單位']
missing = [col for col in required if col not in df.columns]
if missing:
print(f"⚠ Missing columns: {missing}")
else:
print("✓ File structure is valid")
```
### Preview Data Before Processing
```python
df = pd.read_excel(file_path, header=1)
print(f"Date range: {df['日期'].min()} to {df['日期'].max()}")
print(f"Total entries: {len(df)}")
print(f"Projects: {', '.join(df['專案'].unique()[:5])}")
print(f"Team members: {', '.join(df['使用者'].unique()[:5])}")
```

282
skills/week_report_gen/VISUAL_WORKFLOW.md
View File

@ -1,282 +0,0 @@
# Weekly Report Generator - Visual Workflow
```
┌─────────────────────────────────────────────────────────────────────────┐
│ WEEKLY REPORT GENERATOR WORKFLOW │
└─────────────────────────────────────────────────────────────────────────┘
┌──────────────────┐
│ INPUT FILE │
│ (Cost Report) │
│ .xls/.xlsx │
└────────┬─────────┘
│
│ 日期 使用者 活動 專案 單位
│ 01-12 ben sung Dev masterXXX 8
│ 01-12 Ryan - AXEL PLC 8
│ 01-13 傑 羅 Dev CNC Lib 4
│
▼
┌─────────────────────────────────┐
│ STEP 1: READ & PARSE │
│ • Load Excel file │
│ • Identify columns │
│ • Clean missing data │
│ • Extract date range │
└────────┬────────────────────────┘
│
│ DataFrame with validated data
│ Date range: 2026-01-12 to 2026-01-16
│
▼
┌─────────────────────────────────┐
│ STEP 2: AGGREGATE │
│ • Group by user & project │
│ • Sum work hours │
│ • Combine activities │
│ • Collect comments │
└────────┬────────────────────────┘
│
│ Project: masterXXX
│ • ben sung: 15 hours
│ • Activities: Development, Specification
│ • Notes: migrate to entry based sdo queue...
│
▼
┌─────────────────────────────────┐
│ STEP 3: FORMAT │
│ • Group by project │
│ • List team members │
│ • Format progress notes │
│ • Calculate totals │
└────────┬────────────────────────┘
│
│ Formatted report data ready for Excel
│
▼
┌─────────────────────────────────┐
│ STEP 4: GENERATE EXCEL │
│ • Load template (if exists) │
│ • Create new sheet │
│ • Write headers │
│ • Write project data │
│ • Apply formatting │
│ • Save file │
└────────┬────────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ OUTPUT FILE (Weekly Report) │
│ 項目週報-智能控制組 │
│ │
│ 弘訊科技股份有限公司 │
│ 2026年度週報(01月12日-01月16日） │
│ │
│ 專案 參與人員 工時 本周進展 │
│ ──────────────────────────────────────── │
│ AXEL Ryan Hsueh 48.0 - │
│ master ben sung 15.0 Development │
│ XXX migrate to.. │
│ │
└──────────────────────────────────────────────┘
DATA FLOW DIAGRAM
═════════════════
Raw Time Data ──────┐
│
Export from PM ├─────────► Read Excel ────► Parse Columns
System │ │
│ │
Cost Report File ───┘ ▼
Validate & Clean
│
▼
Extract Date Range
│
▼
Group by Project ────┐
│ │
│ │
Sum Hours ◄──────────┤
│ │
│ │
Combine Teams ◄──────┘
│
▼
Format Progress
│
▼
Load Template
│
▼
Write to Excel
│
▼
Apply Styling
│
▼
Save Output File
│
▼
Weekly Report ✓
COMPONENT ARCHITECTURE
══════════════════════
┌─────────────────────────────────────────────────────────────┐
│ SKILL ARCHITECTURE │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ User Interface Layer │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ • Command Line Interface │ │
│ │ • AI Assistant Integration │ │
│ │ • Python API │ │
│ └────────────────┬────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Core Processing Layer │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ • read_cost_report() │ │
│ │ └─► Load Excel, validate columns │ │
│ │ │ │
│ │ • aggregate_work_hours() │ │
│ │ └─► Group data, sum hours, extract dates │ │
│ │ │ │
│ │ • format_for_weekly_report() │ │
│ │ └─► Transform to report format │ │
│ │ │ │
│ │ • generate_weekly_report() │ │
│ │ └─► Main orchestration function │ │
│ └────────────────┬────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Output Generation Layer │ │
│ ├─────────────────────────────────────────────────────┤ │
│ │ • Excel Writer (openpyxl) │ │
│ │ • Template Handler │ │
│ │ • Style & Format Applier │ │
│ │ • File Saver │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
▲ ▲
│ │
┌────┴─────┐ ┌──────┴──────┐
│ pandas │ │ openpyxl │
│ (Data │ │ (Excel │
│ Process) │ │ Files) │
└──────────┘ └─────────────┘
FILE ORGANIZATION
═════════════════
skills/week_report_gen/
│
├── 📄 SKILL.md ─────────────────► Technical documentation
│ • API reference
│ • Function details
│ • Code examples
│
├── 📄 README.md ────────────────► User guide
│ • Installation
│ • Quick start
│ • Examples
│
├── 📄 QUICK_REFERENCE.md ───────► AI assistant guide
│ • Usage patterns
│ • Best practices
│
├── 📄 COMPLETE_GUIDE.md ────────► Comprehensive guide
│ • Everything combined
│ • Tips & tricks
│
├── 🐍 generate_report.py ───────► Main script
│ • Core functions
│ • Entry point
│
└── 📁 references/
│
├── 📊 cost-report-*.xls ────► Example input
├── 📋 項目週報-模板.xlsx ───► Template
└── 📊 項目週報-*.xlsx ──────► Example output
USAGE PATTERNS
══════════════
Pattern 1: AI Assistant
────────────────────────
User: "Generate weekly report"
│
▼
AI reads SKILL.md
│
▼
AI runs generate_report.py
│
▼
AI shows summary
│
▼
Report saved ✓
Pattern 2: Command Line
───────────────────────
$ python generate_report.py input.xls output.xlsx
│
▼
Script processes data
│
▼
Console shows progress
│
▼
Report saved ✓
Pattern 3: Python Integration
──────────────────────────────
from generate_report import generate_weekly_report
│
▼
output, summary = generate_weekly_report(...)
│
▼
Use summary data in your code
│
▼
Process complete ✓
KEY SUCCESS FACTORS
═══════════════════
✓ Input Validation
└─► Verify file exists, columns present, data valid
✓ Smart Aggregation
└─► Group logically, sum accurately, preserve info
✓ Template Support
└─► Use existing templates, maintain consistency
✓ Error Handling
└─► Clear messages, graceful failures, helpful hints
✓ Formatting
└─► Professional appearance, proper widths, colors
✓ Documentation
└─► Clear examples, complete reference, AI-friendly
```

BIN
skills/week_report_gen/references/項目週報-智能控制組-20260116.xlsx
View File

Binary file not shown.

BIN
skills/week_report_gen/references/項目週報-示例輸出-20260116.xlsx
View File

Binary file not shown.