研发工作报告

概述

Work Report Generator

Generate structured development work reports by collecting data from Git commits and TAPD tasks.

TAPD MCP Configuration (Required for TAPD Data)

Before collecting TAPD data, verify that the TAPD MCP server is properly configured and connected.

Pre-check Steps

1. Check MCP server availability — Attempt to call lookup_tool_param_schema with tool_name=stories_get on the tapd_mcp_http_sys server.
   • If the call succeeds → TAPD MCP is configured, proceed normally.
   • If the call fails (server not found / connection error) → Guide the user through setup.
2. If TAPD MCP is NOT configured, display the following guidance to the user:

⚠️ TAPD MCP 服务未配置

要在报告中包含 TAPD 任务追踪数据（需求、缺陷、迭代），需要先配置 TAPD MCP 服务。

配置步骤：

1. 打开 IDE 的 MCP 设置（Settings → MCP Servers）
2. 添加一个新的 MCP 服务，配置如下：
   • 名称：tapd_mcp_http_sys
   • 类型：HTTP（Streamable HTTP）
   • URL：https://tapd-mcp.woa.com/mcp（内网）或联系管理员获取地址
   • Headers：根据认证要求配置（通常需要 Token 或 Cookie）
3. 保存配置后，重启 MCP 连接
4. 验证：尝试调用任意 TAPD 工具（如 iterations_get），确认返回正常数据

如果暂时无法配置 TAPD MCP，报告将仅包含 Git 提交统计数据，不包含 TAPD 任务追踪部分。

常见问题：

• 连接超时：检查是否在内网环境或已连接 VPN
• 认证失败：确认 Token/Cookie 是否过期，需要重新获取
• 工具调用报错：确认 workspace_id 是否正确（可在 TAPD 项目 URL 中找到）

1. If user chooses to skip TAPD — Continue generating the report with Git data only. Mark the TAPD section as "未配置 TAPD MCP，已跳过" in the output.

TAPD Workspace ID

The tapd_workspace_id can be found in the TAPD project URL:

https://tapd.woa.com/tapd_fe/<workspace_id>/story/list
                              ^^^^^^^^^^^^^^^^
                              This is the workspace_id

If the user doesn't know their workspace_id, use the user_participant_workspace_get tool to list all projects the user participates in, then let them choose.

Prerequisites

Before generating a report, collect the following from the user (or use smart defaults):

Project-level Configuration File

Skill supports a project-level configuration file (.work-report.json) placed in the workspace root directory. This allows teams or individuals to persist project-specific settings that override the global defaults.

Resolution order (highest priority first):

1. User explicitly provides in the current message
2. .work-report.json in the workspace root
3. Auto-detection logic
4. Skill global defaults

File location: <workspace_root>/.work-report.json

Schema:

{
  "author": "<your-git-username>",
  "role": "<your-role>",
  "week_cycle": "monday",
  "tapd_workspace_id": "<your-tapd-workspace-id>",
  "repos": ["<org/repo1>", "<org/repo2>"],
  "language": "zh",
  "output_dir": "<path-to-output-directory>",
  "resource_patterns": ["skills/", "assets/", "vendor/"],
  "exclude_patterns": ["node_modules/", "dist/", "*.lock"]
}

All fields are optional. Only the fields present in the config file will override defaults.

output_dir guidelines:

• If specified, reports will be saved to this directory
• If not specified, the skill will auto-detect (see below)
• Use absolute paths for reliability

How to read the config:

At the start of execution, before auto-detection, check each workspace directory for .work-report.json:

cat <workspace_root>/.work-report.json 2>/dev/null

If found, parse the JSON and use its values as overrides. If multiple workspaces have config files, merge them (later workspace values override earlier ones for conflicting keys; array fields like repos are concatenated).

Example: A project using Tuesday~Monday week cycle:

{
  "week_cycle": "tuesday",
  "tapd_workspace_id": "12345678"
}

With this config, even though the Skill default is monday, this project will always use tuesday as the week start day — no need to specify it every time.

Auto-detection Logic

When the user does not explicitly provide parameters, apply the following auto-detection in order:

1. Auto-detect author

Run in the workspace directory:

git config user.name

Use the output as the default author. If multiple workspaces exist, use the first one that returns a value.

2. Auto-detect repos

Scan each workspace directory for .git/config and extract the remote URL:

# For each workspace directory
git -C <workspace_dir> remote get-url origin

Parse the Gongfeng project path from the remote URL:

• git@git.woa.com:<org>/<repo>.git → <org>/<repo>
• https://git.woa.com/<org>/<repo>.git → <org>/<repo>
• git@git.code.tencent.com:<org>/<repo>.git → <org>/<repo>
• Supports nested groups: git@git.woa.com:<org>/<sub>/<repo>.git → <org>/<sub>/<repo>

If multiple workspaces are detected, include all of them.

3. Auto-detect output_dir

Determine where to save the generated report:

1. If output_dir is specified in .work-report.json → use it directly
2. If not specified, check if a docs/ directory exists in the workspace root → use <workspace_root>/docs/
3. If no docs/ directory exists → use the workspace root directory itself
4. If multiple workspaces exist → use the first workspace's resolved output directory

The user can always override by providing output_path explicitly.

4. Smart period defaults

Infer the report period from the user's request. Default to natural calendar weeks (Monday ~ Sunday) and natural calendar months:

Interaction Flow

The ideal interaction should be zero-config for common cases:

1. User says: "写周报"
2. AI auto-detects and presents a confirmation:

检测到以下配置：

• 👤 作者：<detected-author>（来自 git config）
• 📁 仓库：<org/repo1>, <org/repo2>（来自当前 workspace）
• 📅 周期：YYYY-MM-DD ~ YYYY-MM-DD（最近一周）
• 📂 输出目录：<detected-output-dir>

确认开始生成？（或输入修改项）

1. User confirms (or adjusts) → proceed to generate

When auto-detection fails (e.g., no .git found, no remote URL, ambiguous workspace):

• Fall back to asking the user for the missing parameter
• Provide helpful hints (e.g., "请提供工蜂项目路径，格式如 org/repo")

When user provides explicit values — always use user-provided values over auto-detected ones.

Execution Workflow

Phase 1: Collect Git Statistics

For each repository, use the Gongfeng MCP tools to gather commit data:

1. Get commit list — Use get_commits_list with author filter and date range
   • Parameters: project_id, ref_name (default branch), since, until, per_page=100
   • Paginate if needed to get all commits
   • Time format: YYYY-MM-DDTHH:MM:SS%2B0800
2. Get commit diffs — For each commit, use get_commit_diff with diff_file_only=true to get changed file paths
   • Then use get_commit_info for detailed stats (additions/deletions)
3. Separate resource files from business code — Classify file changes:
   • Business code: .ts, .tsx, .js, .jsx, .go, .py, .rs, .vue, .css, .scss, .html etc.
   • Resource files: files under skills/, assets/, vendor/, node_modules/, or non-code files (.md, .json, .yaml, .txt, .png, etc.)
   • The classification rules can be adjusted based on the project structure
4. Aggregate statistics per repo:
   • Total commits count
   • Business code: insertions / deletions / files changed
   • Resource files: insertions / deletions / files changed (listed separately)

Optimization: Instead of fetching diff for every commit, use terminal git log commands when the repo is available locally:

# Total stats
git log --author="<author>" --since="<start>" --until="<end>" --numstat --pretty="" | awk '{add+=$1; del+=$2; files++} END {printf "+%d / -%d, %d filesn", add, del, files}'

# Business code vs resource files (adjust grep pattern per project)
git log --author="<author>" --since="<start>" --until="<end>" --numstat --pretty="" | grep -E '^[0-9]' | awk 'BEGIN{...} /skills/|assets//{resource} {business} END{...}'

Phase 2: Collect TAPD Data (if workspace_id provided)

Use TAPD MCP tools to gather task data:

1. Get iterations — iterations_get with workspace_id
   • Filter iterations that overlap with the report period
2. Get stories (requirements) — stories_get with:
   • workspace_id, owner=<author>, with_v_status=1
   • Fields: id,name,iteration_id,status,v_status,priority_label,owner,created
   • Paginate to get all stories
3. Get bugs (defects) — bugs_get with:
   • workspace_id, current_owner=<author> for owned bugs
   • workspace_id, de=<author> for bugs fixed by the author
   • workspace_id, fixer=<author> for bugs fixed by the author
   • Fields: id,title,iteration_id,status,v_status,priority_label,current_owner,de,fixer,created
   • Deduplicate results across queries
4. Aggregate TAPD statistics:
   • Stories: total / by status (completed, in-progress, planned)
   • Bugs: total / by role (owner vs developer-fix) / by status
   • Iterations participated

Phase 3: Build Weekly Breakdown

Split the report period into weeks based on week_cycle (default from config or Monday~Sunday):

1. Calculate week boundaries
2. For each week, group commits by date
3. Summarize each week's work:
   • Parse commit messages for feature/fix/refactor categories
   • Group by project (repo)
   • Extract key deliverables from commit messages

For each week, generate:

• A descriptive title summarizing the week's focus
• A table of deliverables (project | description)
• A "contribution value" section highlighting key achievements

Phase 4: Generate Report

Assemble the final Markdown report following the template structure in references/report-template.md.

Section order:

1. Header — Title, author info, role, project, period, commit stats, code changes, repo links
2. Overall Work Summary — Numbered list of functional modules with status
3. Cumulative Statistics — Table with period, commits, code changes (business vs resource), modules, etc.
4. TAPD Task Tracking (if available):
   • Iteration overview table
   • Task statistics summary
   • Stories table (with TAPD links)
   • Bugs table (with TAPD links, role column)
5. Weekly Detailed Output — One subsection per week with table + contribution value
6. Core Deliverables — Code modules table, key technical documents
7. Project Experience & Value (optional) — Reusable assets, engineering insights
8. Product Thinking (optional) — High-level reflections
9. Concise Summary (群发版) — A copy-paste-ready plain text summary wrapped in code block, suitable for group chat sharing. Include: role, commit stats, iteration range, TAPD summary, completed modules, in-progress/planned modules

Phase 5: Output

1. Write the report to the specified output_path (or suggest a default path based on the date)
2. File naming convention: YYYYMMDD-work-report-<period-description>.md
3. Display a summary to the user

Report Formatting Rules

• Use Chinese for report content (unless language=en)
• Status icons: ✅ completed, 🟡 in-progress, 🔵 planned, 🔴 new, 📋 backlog
• Priority labels: keep original (High/Middle/Low or 紧急/高/中/低)
• TAPD links format: [详情]({tapd_base_url}/tapd_fe/{workspace_id}/{type}/detail/{id})
• TAPD base URL: use https://tapd.woa.com for internal (woa) projects, https://www.tapd.cn for external projects. Auto-detect from MCP server config or ask user if ambiguous.
• Code statistics: always separate business code from resource files
• Week cycle: Monday~Sunday by default (natural week, configurable)
• Tables: use Markdown tables with alignment
• No internal MD links (they won't work after publishing to wiki)

Important Notes

• When local git repos are available, prefer git log terminal commands over MCP API calls for efficiency
• For TAPD data, always use with_v_status=1 to get Chinese status names
• Deduplicate bugs that appear in multiple queries (owner + developer + fixer)
• If a commit message follows conventional commits format (feat/fix/refactor/chore), use it for categorization
• Large resource file changes (skills packages, vendor files) should be clearly separated from business code stats
• The report template in references/report-template.md is the canonical format reference

Resources

This skill includes example resource directories that demonstrate how to organize different types of bundled resources:

scripts/

Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.

Examples from other skills:

• PDF skill: fill_fillable_fields.py, extract_form_field_info.py – utilities for PDF manipulation
• DOCX skill: document.py, utilities.py – Python modules for document processing

Appropriate for: Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.

Note: Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.

references/

Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.

Examples from other skills:

• Product management: communication.md, context_building.md – detailed workflow guides
• BigQuery: API reference documentation and query examples
• Finance: Schema documentation, company policies

Appropriate for: In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.

assets/

Files not intended to be loaded into context, but rather used within the output Claude produces.

Examples from other skills:

• Brand styling: PowerPoint template files (.pptx), logo files
• Frontend builder: HTML/React boilerplate project directories
• Typography: Font files (.ttf, .woff2)

Appropriate for: Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.

Any unneeded directories can be deleted. Not every skill requires all three types of resources.