TOD - TheOneDev 命令行工具

TOD (TheOneDev) 是一款适用于 OneDev 13+ 的强大命令行工具，它通过允许您针对本地更改运行 CI/CD 作业、将拉取请求检出到本地工作目录、查询和编辑问题/PR/构建，以及通过附带的技能文件驱动 AI 代理执行上述所有操作，从而简化您的开发工作流。

功能

• 查询和编辑 OneDev 实体 — 问题、拉取请求和构建 — 直接从 shell 操作。

• 针对本地更改、分支或标签运行 CI/CD 作业，并支持实时日志流式传输 (tod build run --local, --branch 或 --tag)。

• 在本地检出拉取请求 (tod pr checkout)。

• 检查并迁移 .onedev-buildspec.yml 到最新版本 (tod build check-spec)。

• 代理技能，位于 skills/ 目录下，用于指导 Claude Code、Cursor 以及其他支持 SKILL.md 的代理通过 tod 驱动 OneDev 工作流。

• 跨平台支持 (Windows, macOS, Linux)。

Related MCP server: AlibabaCloud DevOps MCP Server

安装

要安装 tod，请将二进制文件放入您的 PATH 中。

下载预构建的二进制文件

https://code.onedev.io/onedev/tod/~builds?query=%22Job%22+is+%22Release%22

从源码构建

要求： Go 1.22.1 或更高版本。

git clone https://code.onedev.io/onedev/tod.git
cd tod
go build

配置

运行 tod config set 以交互方式创建或更新配置文件：

tod config set
# OneDev server URL (e.g. https://onedev.example.com): ...
# OneDev personal access token (input is visible): ...

或者在非交互式设置中通过标志传递所有内容：

tod config set \
  --server-url https://onedev.example.com \
  --access-token your-personal-access-token \
  --non-interactive

tod config get 打印当前配置（令牌会被屏蔽），tod config get <属性名> 打印单个属性，tod config set <属性名> <属性值> 更新一个属性。属性名称为 server-url 和 access-token。tod config path 打印正在使用的路径。

配置文件将在以下位置搜索（第一个匹配项生效）：

1. $XDG_CONFIG_HOME/tod/config

2. ~/.config/tod/config

3. ~/.todconfig (旧版回退)

它使用 INI 格式，并以 0600 模式写入：

server-url=https://onedev.example.com
access-token=your-personal-access-token

快速入门

# Run CI against your uncommitted changes
cd /path/to/onedev-git-repository
tod build run --local ci

# Run ci job against the main branch
tod build run --branch main ci

# Check out pull request PROJ-123 into the current working directory
tod pr checkout PROJ-123

# Query open issues assigned to you
tod issue list --query 'assignee is me and state is "Open"'

# Inspect the most recent failing build for a project
tod build list --query 'successful is false' --count 1
tod build get <ref>
tod build get-log <ref>

请参阅 cli.md 获取完整的命令参考。

代理技能

TOD 在 skills/ 下附带了四个与工具无关的 SKILL.md 文件，用于指导 AI 代理如何通过 CLI 驱动常见的 OneDev 工作流：

• using-tod — 通过 tod 进行任何 OneDev 交互的综合指南

• edit-build-spec — 创建或编辑 .onedev-buildspec.yml

• investigate-build-problems — 调试失败的构建

• review-pull-request — 执行结构化的拉取请求审查

请参阅 skills.md 了解如何将这些技能安装到 Claude Code、Cursor 或任何其他读取 SKILL.md 文件的代理中。

本地 CI 运行注意事项

Nginx 配置

如果 OneDev 运行在 Nginx 之后，请禁用 HTTP 缓冲以实现日志流式传输：

location /~api/streaming {
    proxy_pass http://localhost:6610/~api/streaming;
    proxy_buffering off;
}

详情请参阅 OneDev Nginx 设置文档。

安全注意事项

如果作业访问作业机密，请确保清除授权字段以允许所有作业。将授权设置为允许所有分支是不够的 — 本地更改会被推送到不属于任何分支的临时引用中。

性能提示

1. 大型仓库 — 在检出步骤中使用适当的克隆深度，而不是完整历史记录。

2. 外部依赖 — 使用 缓存 来处理下载和中间文件。

3. 构建优化 — 缓存生成缓慢的中间文件。

贡献

TOD 是 OneDev 生态系统的一部分。有关贡献、问题和功能请求，请访问 OneDev 项目。

许可证

请参阅 license.txt。