Weekly Report AI Agent

自动读取 Git 提交、VSCode History、JetBrains LocalHistory，生成适合团队复用的周报 MCP，支持飞书和钉钉 Webhook。

功能

• 采集 Git、VSCode、JetBrains 多数据源
• 支持多个项目根目录、多个 Git 作者
• 自动推断项目名，不再依赖固定的个人目录结构
• 支持 business、technical、hybrid 三种周报风格
• 支持飞书交互卡片和钉钉 Webhook
• 可作为 MCP Server 给 Cline、Claude Desktop、Cursor、Windsurf 使用

快速开始

npm 使用

{
  "mcpServers": {
    "weekly-report-agent": {
      "command": "npx",
      "args": ["-y", "weekly-report-agent"],
      "env": {
        "OPENAI_BASE_URL": "http://your-base-url",
        "OPENAI_API_KEY": "your-api-key",
        "OPENAI_MODEL": "gpt-4o",
        "GIT_PROJECT_ROOTS": "/Users/you/workspace,/Users/you/side-projects", //负责“去哪里找 Git 仓库”
        "GIT_AUTHORS": "your-name,[email protected]", //负责“谁在写代码”
        "PROJECT_ROOTS": "/Users/you/workspace,/Users/you/side-projects", //用来从 VSCode/IDEA 的编辑记录里推断“这个文件属于哪个项目”。
        "REPORT_AUTHOR": "Your Name",
        "REPORT_STYLE": "hybrid",
        "REPORT_AUDIENCE": "team",
        "REPORT_LANGUAGE": "zh-CN",
        "REPORT_OUTPUT_DIR": "/Users/you/weekly-reports",
        "DINGTALK_AUTHOR": "staffId",
        "DINGTALK_WEBHOOK_URL": "https://your-WEBHOOK-URL"
      }
    }
  }
}

源码使用

npm install
npm run build
node build/mcp-server.js

项目目录配置

这是当前版本通用化的重点。

过去项目名识别依赖固定路径规则，比如 /project/xxx/...。现在改成通用策略：

1. 优先根据 PROJECT_ROOTS 或 GIT_PROJECT_ROOTS 判断项目名
2. 如果没命中，再向上查找 .git、package.json、pyproject.toml、go.mod、Cargo.toml、.idea 等项目标记
3. 再不行才回退到父目录名

推荐目录结构：

/Users/you/workspace
  ├── app-a
  ├── app-b
  └── platform-tools

推荐配置：

{
  "GIT_PROJECT_ROOTS": "/Users/you/workspace,/Users/you/oss",
  "PROJECT_ROOTS": "/Users/you/workspace,/Users/you/oss"
}

说明：

• GIT_PROJECT_ROOTS 用于扫描 Git 仓库
• PROJECT_ROOTS 用于从编辑记录里推断项目名
• 如果两者一致，只配 GIT_PROJECT_ROOTS 也可以，程序会自动复用
• 兼容旧配置 GIT_PROJECT_ROOT，但更推荐迁移到 GIT_PROJECT_ROOTS

Git 作者配置

现在支持多个作者标识，适合这些场景：

• 同一个人有多个 Git name / email
• 公司邮箱和个人邮箱混用
• 中文名和英文名混用

推荐配置：

{
  "GIT_AUTHORS": "your-name,[email protected],Your English Name"
}

兼容旧配置 GIT_AUTHOR，但更推荐 GIT_AUTHORS。

周报风格配置

支持三种风格：

• business: 更偏结果、价值、影响
• technical: 更偏实现、模块、稳定性、细节
• hybrid: 两者兼顾

配置示例：

{
  "REPORT_STYLE": "hybrid",
  "REPORT_AUDIENCE": "team lead",
  "REPORT_LANGUAGE": "zh-CN"
}

REPORT_LANGUAGE 支持：

• zh-CN
• en-US
• bilingual

环境变量

| 变量 | 说明 | 默认值 | | -------------------------- | ------------------------------------------------- | --------------------------- | | OPENAI_API_KEY | OpenAI 兼容 API Key | - | | OPENAI_BASE_URL | OpenAI 兼容 API 地址 | https://api.openai.com/v1 | | OPENAI_MODEL | 模型名 | gpt-4o | | GIT_PROJECT_ROOT | 单个 Git 根目录，兼容旧配置 | 空 | | GIT_PROJECT_ROOTS | 多个 Git 根目录，逗号分隔 | 空 | | PROJECT_ROOTS | 编辑记录项目根目录，逗号分隔 | 复用 GIT_PROJECT_ROOTS | | GIT_AUTHOR | 单个 Git 作者，兼容旧配置 | 空 | | GIT_AUTHORS | 多个 Git 作者或邮箱，逗号分隔 | 空 | | GIT_MAX_DEPTH | Git 仓库扫描深度 | 2 | | VSCODE_HISTORY_PATH | VSCode History 路径 | 按操作系统自动推导 | | VSCODE_STATE_DB_PATH | VSCode state DB 路径 | 按操作系统自动推导 | | IDEA_HISTORY_PATH | JetBrains 配置根目录 | 按操作系统自动推导 | | IDEA_ENABLED | 是否启用 JetBrains 采集 | true | | REPORT_OUTPUT_DIR | 周报输出目录 | ~/weekly-reports | | REPORT_AUTHOR | 周报作者名 | 空，回退到 Git 作者 | | REPORT_STYLE | 周报风格：business / technical / hybrid | business | | REPORT_AUDIENCE | 周报目标读者 | team | | REPORT_LANGUAGE | 语言：zh-CN / en-US / bilingual | zh-CN | | FEISHU_APP_ID | 飞书应用 ID | 空 | | FEISHU_APP_SECRET | 飞书应用密钥 | 空 | | FEISHU_RECEIVE_ID | 飞书接收人 open_id | 空 | | DINGTALK_WEBHOOK_URL | 钉钉 Webhook 地址 | 空 | | DINGTALK_TRIGGER_KEYWORD | 钉钉关键字字段 | 更新 | | DINGTALK_AUTHOR | 钉钉 staffId，最终会发送为 [{ staffId: "..." }] | 空 |

MCP 工具

generate_weekly_report

生成周报，可选自动发送。

参数：

• start_date: YYYY-MM-DD
• end_date: YYYY-MM-DD
• editor_source: auto | vscode | idea | both
• send_feishu: boolean
• send_dingtalk: boolean
• dingtalk_author: 钉钉人员的 staffId；如果没配 DINGTALK_AUTHOR，这里必须传。最终会发送为 [{ "staffId": "..." }]
• skip_vscode: boolean
• skip_idea: boolean

diagnose_config

检查当前 MCP 配置是否完整，会返回：

• OpenAI 是否已配置
• Git 项目根目录是否存在
• Git 作者是否已配置
• VSCode / JetBrains 路径是否可读
• 飞书 / 钉钉发送配置是否完整

get_vscode_activity

查看 VSCode 编辑活动。

get_idea_activity

查看 JetBrains 编辑活动。

get_git_summary

查看 Git 提交汇总。

send_report_to_feishu

发送最新周报或指定内容到飞书。

send_report_to_dingtalk

发送最新周报或指定内容到钉钉 Webhook。

额外支持：

• dingtalk_author

飞书与钉钉

飞书

配置：

• FEISHU_APP_ID
• FEISHU_APP_SECRET
• FEISHU_RECEIVE_ID

发送格式是交互卡片。

钉钉

配置：

• DINGTALK_WEBHOOK_URL
• DINGTALK_TRIGGER_KEYWORD
• DINGTALK_AUTHOR

默认发送 JSON：

{
  "keyword": "更新",
  "content": "一、功能开发\n1. xxx；",
  "time": "2026/04/10",
  "author": [
    {
      "staffId": "123456"
    }
  ]
}

CLI

node build/index.js generate
node build/index.js generate --send
node build/index.js generate --dingtalk
node build/index.js send --dingtalk
node build/index.js info
node build/index.js diagnose

说明

• 当前版本要求配置 OPENAI_API_KEY
• 没有配置项目根目录或 Git 作者时，Git 统计会直接报错，避免生成失真的周报
• 如果你之前使用的是单目录配置，可以先保持兼容，再逐步切到 GIT_PROJECT_ROOTS
• 现在支持先运行 diagnose_config 或 node build/index.js diagnose 做接入自检