SHA256
Python CLI 管理工具
tjhlp 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计功能。
前置要求
- Python >= 3.14
- uv
安装
cd scripts
uv sync
安装后即可使用 uv run tjhlp 调用。
配置
基础配置 (settings.toml)
已随项目提供, 包含默认值和预定义 Label 集合。一般无需修改。
敏感配置 (.secrets.toml)
cp .secrets.toml.example .secrets.toml
编辑 .secrets.toml, 填入实际值:
[default.gitea]
token = "your-gitea-api-token" # 必填
API Token 获取方式: 登录 Gitea -> 设置 -> 应用 -> 生成令牌(勾选所有权限)。
.secrets.toml 已在 .gitignore 中排除, 不会被提交。
环境变量覆盖
所有配置项均可通过 TJHLP_ 前缀的环境变量覆盖:
export TJHLP_GITEA_URL=http://192.168.1.100:3000
export TJHLP_GITEA_TOKEN=your-token
命令一览
tjhlp
├── setup
│ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook
│ └── status 检查 Gitea 连接状态
├── users
│ ├── create 从 CSV 批量创建账号(初始密码与用户名相同)
│ ├── list 列出所有用户
│ └── delete 批量删除用户
├── orgs
│ ├── create 创建组织
│ ├── create-team 创建团队
│ ├── add-members 批量添加成员到团队
│ └── list-teams 列出组织下的团队
├── repos
│ ├── create 创建仓库
│ ├── create-homework 创建作业仓库(自动推送模板/Labels/Webhook)
│ ├── init-templates 推送 Issue Templates 到仓库
│ └── configure 配置仓库设置
├── webhooks
│ ├── create 创建 Webhook
│ ├── list 列出 Webhook
│ ├── test 测试 Webhook
│ └── delete 删除 Webhook
├── labels
│ ├── sync 同步预定义 Label 到仓库
│ └── list 列出仓库 Label
└── stats
├── summary Issue 统计摘要
└── export 导出 Issue 数据到 CSV
典型工作流
学期初始化
# 1. 检查连接
uv run tjhlp setup status
# 2. 一键初始化(创建组织 + 团队 + general 仓库 + Labels + Webhook)
uv run tjhlp setup init \
--org tjhlp-2025f \
--webhook-url http://notify-server:8080/webhook \
--webhook-secret mysecret
# 3. 批量创建用户并分配到团队
uv run tjhlp users create --file members.csv --org tjhlp-2025f
cmd 可直接复制的写法:
uv run tjhlp setup status
uv run tjhlp setup init --org tjhlp-2025f --webhook-url http://notify-server:8080/webhook --webhook-secret mysecret
uv run tjhlp users create --file members.csv --org tjhlp-2025f
每次布置作业
uv run tjhlp repos create-homework \
--org tjhlp-2025f \
--number 3 \
--desc "作业3: 链表操作" \
--webhook-url http://notify-server:8080/webhook
cmd 可直接复制的写法:
uv run tjhlp repos create-homework --org tjhlp-2025f --number 3 --desc "作业3: 链表操作" --webhook-url http://notify-server:8080/webhook
这会自动完成: 创建 hw03 仓库 -> 推送作业 Issue Template -> 同步 Labels -> 配置 Webhook -> 添加到 ta/students 团队。
日常管理
# 查看 Issue 统计
uv run tjhlp stats summary tjhlp-2025f/general
# 导出 Issue 数据
uv run tjhlp stats export tjhlp-2025f/hw03 --output hw03_issues.csv
# 同步 Label 到新仓库
uv run tjhlp labels sync tjhlp-2025f/hw03
# 查看 Webhook 状态
uv run tjhlp webhooks list tjhlp-2025f/general
学期结束清理
uv run tjhlp users delete --file members.csv --yes
CSV 格式
输入: members.csv
id,name,role
2659999,赵一伤,student
2659876,钱二败,student
10001,李四催,ta
id- 学号或工号, 同时作为 Gitea 用户名name- 姓名, 作为 Gitea 的full_namerole-student或ta, 决定分配到哪个团队- 邮箱自动生成为
{id}@tongji.edu.cn - 初始密码与用户名(学号/工号)相同
示例文件见 example/members.csv。
预定义 Label
通过 settings.toml 配置, setup init 和 labels sync 时自动创建:
| Label | 颜色 | 用途 |
|---|---|---|
duplicate |
灰色 | 助教标记重复问题 |
invalid |
黄色 | 不符合提问规范 |
resolved |
绿色 | 已解决 |
wontfix |
白色 | 不予处理 |
good-question |
紫色 | 优质问题 |
FAQ |
蓝色 | 常见问题 |
课程内容 |
粉紫 | 课程知识点相关 |
编程作业 |
浅红 | 编程作业相关 |
环境配置 |
浅青 | 环境配置相关 |
紧急 |
红色 | 需要尽快回复 |
测试
安装开发依赖
uv sync --extra dev
运行测试
uv run pytest tests/ -v # 全部测试
uv run pytest tests/test_models.py # 只运行模型测试
uv run pytest tests/ -k "password" # 按名称过滤
覆盖率报告
uv run pytest tests/ --cov=tjhlp --cov-report=term-missing
代码检查
uv run ruff check src/
uv run ruff format --check src/
测试套件结构
tests/
├── conftest.py 公共 fixtures(mock config、client、样本数据)
├── test_models.py 数据模型(MemberRecord、Gitea API 模型、枚举)
├── test_config.py 配置校验(LabelDef 颜色、GiteaConfig 必填字段)
├── test_utils.py 工具函数(parse_repo、compute_issue_stats)
├── test_client.py API 客户端(respx mock HTTP, 分页、错误处理、CRUD)
└── test_commands.py 命令集成(CliRunner + mock, setup/users/repos 流程)
测试分层
| 层级 | 测试对象 | 方法 | 速度 |
|---|---|---|---|
| 单元测试 | models, config, 纯函数 | 直接调用, 无 mock | 极快 |
| API 客户端测试 | client.py | respx mock HTTP 层 | 快 |
| 命令集成测试 | commands/*.py | Typer CliRunner + mock GiteaClient | 快 |
| 端到端测试 | 完整流程 | 需要运行中的 Gitea 实例 | 慢(手动) |
当前 93 个测试用例, 核心模块覆盖率:
| 模块 | 覆盖率 | 说明 |
|---|---|---|
models.py |
100% | 全部模型和 computed fields |
config.py |
87% | Pydantic 校验逻辑(未覆盖 Dynaconf 加载函数) |
users.py |
79% | 创建/跳过/删除流程 |
client.py |
67% | 核心 HTTP 方法和分页(未覆盖所有 API endpoint) |
项目结构
scripts/
├── pyproject.toml 项目配置(Python >=3.14, 依赖声明)
├── settings.toml 默认配置 + 预定义 Label
├── .secrets.toml.example 敏感配置示例
├── example/
│ └── members.csv 示例成员名单
├── tests/ 测试套件
│ ├── conftest.py 公共 fixtures
│ ├── test_models.py 数据模型测试
│ ├── test_config.py 配置校验测试
│ ├── test_utils.py 工具函数测试
│ ├── test_client.py API 客户端测试
│ └── test_commands.py 命令集成测试
└── src/tjhlp/
├── cli.py Typer 主入口
├── config.py Dynaconf 加载 + Pydantic 校验
├── client.py Gitea REST API 客户端(自动分页/错误处理)
├── models.py 数据模型
├── utils.py 共享工具函数(parse_repo, push_templates 等)
└── commands/
├── setup.py 初始化命令
├── users.py 用户管理
├── orgs.py 组织/团队管理
├── repos.py 仓库管理
├── webhooks.py Webhook 管理
├── labels.py Label 管理
└── stats.py Issue 统计
技术选型
| 库 | 用途 |
|---|---|
| Typer | CLI 框架 |
| httpx | HTTP 客户端(调用 Gitea API) |
| Rich | 终端美化(表格、颜色、进度) |
| Pydantic | 数据校验、配置模型 |
| Dynaconf | 配置管理(TOML + 环境变量 + secrets 分离) |
| pytest | 测试框架 |
| respx | httpx mock 库(API 客户端测试) |
| ruff | 代码检查与格式化 |