7ff805ca68
涵盖凭证安全存储、执行脚本写法、Windows Task Scheduler 和 Linux crontab 配置 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
184 lines
5.2 KiB
Markdown
184 lines
5.2 KiB
Markdown
# weekly-report
|
||
|
||
统计项目过去 7 天的 commit 和 PR，为每位协作者生成个人工作日志，并生成项目整体进度报告，通过 SMTP 发送到指定邮箱。
|
||
|
||
> 适用于自建 Gitea 仓库，不依赖 `gh` CLI。
|
||
|
||
## 前置要求
|
||
|
||
- Python 3.8+
|
||
- 项目使用 Git，且 `origin` 指向 Gitea 实例
|
||
- 有可用的 SMTP 邮件账号
|
||
|
||
## 第一步：在项目根目录创建配置文件
|
||
|
||
在**需要生成周报的项目**根目录下创建 `report-config.json`（可提交到 git）：
|
||
|
||
```json
|
||
{
|
||
"recipients": ["boss@company.com", "team@company.com"],
|
||
"project_name": "你的项目名称",
|
||
"smtp_host": "smtphz.qiye.163.com",
|
||
"smtp_port": 994
|
||
}
|
||
```
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `recipients` | 是 | 收件人邮箱列表 |
|
||
| `project_name` | 是 | 项目名称，显示在邮件标题中 |
|
||
| `smtp_host` | 否 | SMTP 服务器地址，内置服务商可省略（见下表） |
|
||
| `smtp_port` | 否 | SMTP 端口，内置服务商可省略 |
|
||
|
||
### 内置服务商（smtp_host/smtp_port 可省略）
|
||
|
||
| 发件邮箱后缀 | 自动使用的服务器 | 端口 |
|
||
|-------------|----------------|------|
|
||
| `@gmail.com` | smtp.gmail.com | 587 |
|
||
| `@qq.com` | smtp.qq.com | 465 |
|
||
| `@163.com` | smtp.163.com | 465 |
|
||
| `@126.com` | smtp.126.com | 465 |
|
||
| `@outlook.com` / `@hotmail.com` | smtp.office365.com | 587 |
|
||
|
||
企业自定义域名（如 `@yourcompany.com`）需手动填写 `smtp_host` 和 `smtp_port`。
|
||
|
||
## 第二步：设置环境变量
|
||
|
||
账号密码**不要写入任何文件**，在终端中临时设置：
|
||
|
||
```bash
|
||
export SMTP_USER=your@email.com
|
||
export SMTP_PASSWORD=your-smtp-password-or-auth-code
|
||
```
|
||
|
||
> **说明**：`export` 仅对当前终端会话有效，关闭后自动失效。
|
||
> 如需持久化，可写入 `~/.bashrc`（注意文件权限 `chmod 600 ~/.bashrc`）。
|
||
|
||
### 私有 Gitea 仓库
|
||
|
||
如果仓库是私有的，还需要额外设置 Gitea 访问令牌：
|
||
|
||
```bash
|
||
export GITEA_TOKEN=your-gitea-token
|
||
```
|
||
|
||
在 Gitea 中生成令牌：`头像 → 设置 → 应用 → 管理 Access Token`，权限勾选 `repository: Read`。
|
||
|
||
公开仓库无需配置此项。
|
||
|
||
## 第三步：启用插件
|
||
|
||
在项目的 `.claude/settings.json` 中添加插件路径：
|
||
|
||
```json
|
||
{
|
||
"plugins": ["/path/to/ieslab_skills"]
|
||
}
|
||
```
|
||
|
||
## 第四步：调用技能
|
||
|
||
在 Claude Code 中输入：
|
||
|
||
```
|
||
/weekly-report
|
||
```
|
||
|
||
Claude 会自动执行以下流程：
|
||
1. 读取 `report-config.json`
|
||
2. 拉取 `origin/main` 最新代码
|
||
3. 通过 Gitea API 获取过去 7 天的 commits 和已合并 PR
|
||
4. 生成每位协作者的个人工作日志
|
||
5. 生成项目整体进度报告
|
||
6. 发送 HTML 格式邮件到 `recipients` 列表
|
||
|
||
## 定时自动发送（Cron）
|
||
|
||
通过 `claude -p` 可以以非交互模式运行技能，配合定时任务实现每周自动发送。
|
||
|
||
### 安全存储凭证
|
||
|
||
**不要**把密码直接写在脚本里，应单独存放在权限受限的凭证文件中：
|
||
|
||
```bash
|
||
# 创建凭证文件（只存在于本机，不入 git）
|
||
cat > ~/.ieslab_credentials << 'EOF'
|
||
export SMTP_USER=your@email.com
|
||
export SMTP_PASSWORD=your-auth-code
|
||
export GITEA_TOKEN=your-gitea-token
|
||
EOF
|
||
|
||
# 限制只有当前用户可读
|
||
chmod 600 ~/.ieslab_credentials
|
||
```
|
||
|
||
### 创建执行脚本
|
||
|
||
新建 `~/weekly_report.sh`：
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
set -e
|
||
|
||
# 加载凭证（敏感信息在此文件中，不在本脚本里）
|
||
source ~/.ieslab_credentials
|
||
|
||
# 切换到目标项目目录
|
||
cd /path/to/your-project
|
||
|
||
# 以非交互模式运行技能
|
||
claude -p "/weekly-report"
|
||
```
|
||
|
||
```bash
|
||
chmod +x ~/weekly_report.sh
|
||
```
|
||
|
||
> `claude -p` 是 Claude Code 的非交互模式，执行完成后自动退出，适合在定时任务中使用。
|
||
|
||
### Windows 定时任务（Task Scheduler）
|
||
|
||
Windows 没有 cron，使用"任务计划程序"代替：
|
||
|
||
1. 开始菜单搜索「任务计划程序」→「创建基本任务」
|
||
2. 触发器：选择「每周」，设置具体时间（如每周五 18:00）
|
||
3. 操作：选择「启动程序」
|
||
- 程序：`C:\Program Files\Git\bin\bash.exe`
|
||
- 参数：`-l -c "/c/Users/你的用户名/weekly_report.sh"`
|
||
4. 在「条件」中取消勾选「只在使用交流电源时运行」
|
||
|
||
### Linux / Mac（crontab）
|
||
|
||
如果在 Linux 服务器上运行：
|
||
|
||
```bash
|
||
crontab -e
|
||
```
|
||
|
||
添加一行（每周五 18:00 执行）：
|
||
|
||
```
|
||
0 18 * * 5 /bin/bash ~/weekly_report.sh >> ~/weekly_report.log 2>&1
|
||
```
|
||
|
||
`>> ~/weekly_report.log 2>&1` 会把输出和错误都记录到日志文件，方便排查问题。
|
||
|
||
### 注意事项
|
||
|
||
- 凭证文件 `~/.ieslab_credentials` 必须 `chmod 600`，且**绝不能提交到 git**
|
||
- 脚本中只有 `source ~/.ieslab_credentials`，密码本身不出现在脚本里
|
||
- 定时任务的运行环境可能缺少 `claude` 的 PATH，如遇「命令未找到」错误，将 `claude` 替换为绝对路径（可用 `which claude` 查询）
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
**Q：发送失败，提示认证错误**
|
||
A：SMTP 密码通常需要使用"授权码"而非登录密码。QQ/163 邮箱请在邮箱设置中开启 SMTP 并生成授权码；Gmail 需要开启两步验证后生成"应用专用密码"。
|
||
|
||
**Q：没有 PR 数据**
|
||
A：直接 `git push` 的提交不会产生 PR 记录，只有通过 Gitea 创建 Pull Request 并合并的才会被统计。
|
||
|
||
**Q：私有仓库报 401 错误**
|
||
A：需要设置 `GITEA_TOKEN` 环境变量，参考上方说明。
|