# gitee-report

**Repository Path**: cc-2018_admin/gitee-report

## Basic Information

- **Project Name**: gitee-report
- **Description**: 一个本地运行的 Gitee 提交日报生成器，支持 OAuth 登录、提交记录拉取、代码改动分析、AI 提示词反推和问题量化汇总。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-21
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Git, AI, JavaScript

## README

# Gitee Commit Report

> 仓库简介：一个本地运行的 Gitee 提交日报生成器，支持网页 OAuth 登录、命令行扫描和 Markdown/JSON 输出。

Gitee Commit Report 用来把 Gitee 账号近期提交整理成中文报告。它会拉取提交记录和文件改动，按提交说明、关联 issue/PR、文件变化推断本次提交的“解决/目的”，并生成适合日报、周报、复盘或团队同步的 Markdown 报告。

## 功能特性

- 本地网页模式：通过 Gitee OAuth 登录后，一键生成指定日期的提交报告。
- 命令行模式：支持按账号、仓库、时间范围、数量等参数生成报告文件。
- 多数据来源：支持读取用户动态 `PushEvent`，也支持扫描公开仓库提交。
- 报告摘要：输出仓库、提交时间、Commit 链接、文件变更、行数统计和目的推断。
- AI 提示词分析：为每条提交基于文件和 patch 推断可能使用的提示词模板。
- 问题量化分析：为每条提交汇总解决的问题、边界场景和关键流程数量。
- 关联项识别：可识别提交说明中的 Gitee issue 编号、`#编号` 和 `!PR`。
- 本地优先：服务运行在本机，OAuth token 保存在本地 HttpOnly Cookie 中，CLI 报告不会写入 token。

## 运行环境

- Node.js `>=18`
- npm
- 可访问 Gitee API 的网络环境

当前项目没有第三方运行依赖，确保 Node.js 版本满足要求后即可运行。

## 快速开始

```bash
npm start
```

启动后会自动打开本地页面：

```text
http://127.0.0.1:5178
```

如果不希望自动打开浏览器：

```bash
NO_OPEN=1 npm start
```

或使用跨平台参数：

```bash
npm start -- --no-open
```

## 网页模式

网页模式适合生成当天或指定日期的个人提交报告。

### 配置 Gitee OAuth

1. 打开 [Gitee OAuth 应用管理](https://gitee.com/oauth/applications)，创建或选择一个 OAuth 应用。
2. 将回调地址填入 OAuth 应用：

```text
http://127.0.0.1:5178/oauth/callback
```

3. 启动时配置 OAuth 应用信息：

```bash
GITEE_OAUTH_CLIENT_ID=你的ClientID \
GITEE_OAUTH_CLIENT_SECRET=你的ClientSecret \
npm start
```

也可以写入本地 `.env` 文件，`npm start` 和 `npm run dev` 会自动读取：

```bash
GITEE_OAUTH_CLIENT_ID=你的ClientID
GITEE_OAUTH_CLIENT_SECRET=你的ClientSecret
```

如果没有配置环境变量，页面会显示手动模式，可以在页面中填写 `Client ID` 和 `Client Secret` 后登录。

### 配置 AI 提示词反推

如需对每条提交使用模型反推可能 prompt，可在 `.env` 中配置 Anthropic Messages 兼容接口。模型只参考文件列表、改动位置和 patch 摘要，不把提交说明作为结论依据：

```bash
AI_PROMPT_BASE_URL='http://127.0.0.1:15721'
AI_PROMPT_API_KEY='你的接口密钥'
AI_PROMPT_MODEL='claude-opus-4-7'
```

未配置 `AI_PROMPT_API_KEY` 时，会自动使用本地启发式推断；模型接口失败时也会回退本地推断。
请求会发送到 `AI_PROMPT_BASE_URL` 拼出的 `/v1/messages`，鉴权使用 Anthropic 的 `x-api-key` 请求头。

`.env` 已被 `.gitignore` 忽略，请不要把真实的 OAuth 密钥、Gitee token 或 AI API Key 提交到仓库。

### 页面流程

1. 运行 `npm start` 启动本地服务。
2. 打开本地页面并点击“登录 Gitee”。
3. 在 Gitee 完成授权后回到本地页面。
4. 选择日期、来源、指定仓库和提交数量。
5. 点击“生成今日报告”，查看提交列表和 AI 分析结果。

默认日期按 `Asia/Shanghai` 计算。

## 命令行模式

命令行模式适合在终端中按条件生成报告文件。

```bash
npm run report -- --user <gitee用户名>
```

默认输出：

```text
reports/gitee-commit-report.md
```

常见示例：

```bash
# 拉取公开动态中的 PushEvent，生成最近 20 个 commit 的 Markdown 报告
npm run report -- --user normalcoder --limit 20

# 使用 token，包含授权可见动态
GITEE_TOKEN=你的令牌 npm run report -- --user your-login --include-private

# 只扫描指定仓库
npm run report -- --user your-login --repo owner/project --since 2026-01-01T00:00:00+08:00

# 输出 JSON
npm run report -- --user your-login --format json --output reports/report.json

# 扫描账号公开仓库中的提交
npm run report -- --user your-login --source repos --max-repos 20 --limit 50
```

## 参数说明

| 参数 | 说明 |
| --- | --- |
| `--user` | 必填，Gitee 登录名。 |
| `--token` | 可选，Gitee 私人令牌；也可以使用 `GITEE_TOKEN` 环境变量。 |
| `--source` | 数据来源，支持 `events` 或 `repos`，默认 `events`。 |
| `--include-private` | 使用 `/events` 拉取授权可见动态，适合配合 token 使用。 |
| `--repo` | 指定仓库，格式为 `owner/repo`，可以重复传入。 |
| `--repo-file` | 从文件读取仓库列表，每行一个 `owner/repo`，空行和 `#` 开头的行会被忽略。 |
| `--since` | ISO 8601 起始时间，只保留该时间之后的提交。 |
| `--until` | ISO 8601 结束时间，只保留该时间之前的提交。 |
| `--limit` | 最大输出提交数量，默认 `50`。 |
| `--max-events` | `events` 模式最多扫描动态数，默认 `200`。 |
| `--max-repos` | `repos` 模式最多扫描仓库数，默认 `30`。 |
| `--format` | 输出格式，支持 `markdown` 或 `json`，默认 `markdown`。 |
| `--output` | 输出文件路径，默认 `reports/gitee-commit-report.md`。 |

## 环境变量

| 环境变量 | 说明 |
| --- | --- |
| `HOST` | 本地网页服务监听地址，默认 `127.0.0.1`。 |
| `PORT` | 本地网页服务端口，默认 `5178`。 |
| `NO_OPEN` | 设置为 `1` 时，启动后不自动打开浏览器。 |
| `GITEE_OAUTH_CLIENT_ID` | Gitee OAuth 应用的 Client ID。 |
| `GITEE_OAUTH_CLIENT_SECRET` | Gitee OAuth 应用的 Client Secret。 |
| `GITEE_OAUTH_SCOPE` | OAuth 权限范围，默认 `user_info projects`。 |
| `GITEE_TOKEN` | CLI 模式使用的 Gitee 私人令牌。 |
| `AI_PROMPT_BASE_URL` | AI 提示词反推接口地址，默认 `http://127.0.0.1:15721`。 |
| `AI_PROMPT_API_KEY` | AI 提示词反推接口密钥，未配置时不调用模型，改用本地兜底推断。 |
| `AI_PROMPT_MODEL` | AI 提示词反推模型，默认 `claude-opus-4-7`。 |

## 报告内容

Markdown 报告会包含：

- 账号、数据来源、生成时间和提交数量。
- 每个 commit 的标题、仓库、时间、完整 SHA 和 Gitee 链接。
- 根据提交说明和文件改动推断出的“解决/目的”。
- 每条提交基于文件列表、改动位置和 patch 摘要推断出的可能提示词，并在提示词下方补充 Commit 链接。
- 每条提交量化后的“Commit 解决的问题”，包括边界场景、关键流程和条件分支数量。
- 文件级修改摘要，包括新增、删除、修改、重命名和行数变化。
- 从提交说明中识别出的 issue 或 PR 关联链接。
- API 截断、扫描上限等提示信息。

## 数据来源和边界

- `events` 模式读取用户动态中的 `PushEvent`，适合快速生成近期提交报告。
- `repos` 模式读取用户公开仓库，再按 `author` 参数筛选提交，适合需要扫描仓库历史的场景。
- 指定 `--repo` 或 `--repo-file` 后，会优先扫描指定仓库，不再按用户动态选择仓库。
- 私有仓库、企业仓库或更完整的动态通常需要 Gitee token 或 OAuth 授权。
- “解决/目的”是基于提交信息、关联编号和文件改动的启发式推断，不等同于人工代码审查结论。
- 提示词分析会在配置模型时对每条提交调用 AI 反推，否则使用本地启发式；两者都无法从 Gitee 提交记录还原真实历史 prompt。
- Gitee API 可能返回截断的文件或 patch 内容，报告只会展示接口可获取的部分。

## 项目结构

```text
.
├── bin/gitee-commit-report.js  # CLI 入口和报告生成核心逻辑
├── public/index.html           # 本地网页页面
├── server.js                   # 本地 HTTP 服务和 OAuth 回调
├── package.json                # npm 脚本和项目元信息
└── README.md                   # 项目说明文档
```

## 相关 Gitee API

- 用户动态：`/v5/users/{username}/events` 和 `/v5/users/{username}/events/public`
- 用户公开仓库：`/v5/users/{username}/repos`
- 仓库提交列表：`/v5/repos/{owner}/{repo}/commits`
- 单个提交详情：`/v5/repos/{owner}/{repo}/commits/{sha}`