gongfeng-cli——专为 AI Agent 打造的腾讯工蜂命令行工具
前言
在上一篇文章 https://www.cnblogs.com/studyzy/p/19885426 中，我们探讨了 tapd-ai-cli 的设计理念：为什么 CLI 比 MCP 更适合作为 AI Agent 与外部系统之间的桥梁。核心论点很清晰——MCP 的 Schema 注入机制像一笔"菜单税"，每轮对话都要完整背诵一遍所有工具签名，而 CLI 通过渐进式发现将这笔固定开销降至近乎为零。
那篇文章发布后，不少读者问了一个自然而然的问题：TAPD 能做到，代码托管平台呢？
这正是 gongfeng-cli 要回答的问题。
一、背景：AI Agent 需要一个怎样的代码托管接口？
当 AI Agent 参与软件开发的完整生命周期时，它不可避免地需要与代码托管平台打交道：查看 MR 变更、创建分支、提交代码评审、检查 CI 状态……这些操作在人类开发者眼中稀松平常，但对 AI Agent 而言，问题出在接口的形态上。
让我们直面现实中的三种选择：
| 方案 | 优点 | 痛点 |
|---|---|---|
| Web UI | 信息丰富 | AI 无法直接操作 |
| REST API（裸调用） | 功能完整 | Agent 需生成复杂 HTTP 请求，JSON 响应冗长 |
| MCP 封装 | 标准化工具调用 | Schema 膨胀、token 消耗巨大 |
gongfeng-cli 提供第四种选择：一个专门为 AI Agent 的认知模式设计的命令行工具。它不是对 API 的简单包装，而是从输出格式、信息密度、发现机制等维度，系统性地优化了 Agent 与工蜂平台的交互效率。
二、核心设计思想
gongfeng-cli 的设计延续了 tapd-ai-cli 验证过的五个原则，并针对代码托管场景做了深化：
2.1 AI 友好的输出格式：Markdown 与 JSON 的精确分工
输出格式不是审美问题，而是 token 经济学问题。gongfeng-cli 的策略是按场景自动选择最省 token 的格式：
- 列表命令输出紧凑 JSON（无缩进、无多余空格），一行一条记录，最小化 token 消耗
- 详情命令默认输出 YAML frontmatter + Markdown body，结构化元数据与自由文本各得其所
举个具体例子。一条 MR 详情通过 gongfeng mr show 42 获取，输出如下：
---
id: "42"
title: "feat: 支持自动合并"
state: opened
source_branch: feature/auto-merge
target_branch: main
author: zhangsan
---
本 MR 实现了当 CI 全部通过后自动触发合并的功能……
对比完整 JSON 响应动辄 50+ 个字段的庞大体量，YAML frontmatter 只保留 Agent 决策所需的关键字段，description 以 Markdown 正文形式呈现，天然适合大语言模型的阅读习惯。Token 消耗可轻松降低 40% 以上。
如果 Agent 确实需要完整结构化数据，加上 --json 即可切换；需要人类阅读时，--pretty 会输出带缩进的美化 JSON。三种模式，一个入口，零认知负担。
2.2 渐进式功能发现：帮助信息就是 AI 的"函数签名"
MCP 的致命问题在于：不管你这轮对话是否需要某个工具，它的完整 Schema 都会被注入 context。这就像去餐厅点餐，服务员每次过来都要把整本菜单从头朗读一遍。
gongfeng-cli 的帮助系统是专门为"机器阅读"设计的参考卡。执行 gongfeng --help，Agent 得到的是一张紧凑的命令参考：
gongfeng - 面向 AI Agent 的腾讯工蜂命令行工具
Global: [--project-id=<id>] [--json] [--pretty]
# project
gongfeng project list [--search] [--page] [--per-page] # 获取项目列表
gongfeng project show <project_id> # 获取项目详情
...
# mr
gongfeng mr create --source-branch=<必需> --target-branch=<必需> --title=<必需> # 创建 MR
gongfeng mr show <mr_id> # 获取 MR 详情
...
注意几个设计细节：
- 每条命令一行即全部——命令路径、参数（区分必需/可选）、简短说明
- 必需参数用
--name=<必需>标注，可选参数用[--name]包裹，枚举值直接内联[--state=<opened/closed/merged/all>] - 按功能分组、按使用频率排序，高频命令（project、mr、branch）置于顶部
Agent 第一次调用时获取这张参考卡，即可在后续所有对话轮次中零成本调用任意命令。这就是"按需获取"对"强制预加载"的结构性优势。
2.3 无状态原子操作：每条命令都是自足的
# 创建分支 -> 无需记住上一步返回的任何 ID
gongfeng branch create --branch-name feature/login --ref main
# 查询 MR -> 直接传参数，无需"先切换项目"
gongfeng mr list --project-id myteam/backend --state opened
每条命令通过 flag 携带完整上下文，不依赖任何会话状态。这意味着：
- Agent 可以在任意对话轮次独立调用任何命令
- 失败后重试无需回溯
- 并行调用天然安全
2.4 标准管道组合：Unix 哲学的 AI 时代延伸
gongfeng-cli 的 JSON 输出天然适配 jq 等管道工具：
# 找出所有超过 7 天未更新的 opened MR
gongfeng mr list --state opened | jq '[.[] | select(.updated_at < "2026-05-11")]'
# 获取某个 MR 的所有变更文件路径
gongfeng mr changes 42 | jq '.[].new_path'
Agent 可以用一条组合命令完成原本需要多轮对话才能实现的复杂查询，进一步压缩交互轮次和 token 开销。
2.5 SDK 与 CLI 分层：两层架构服务两类用户
┌─────────────────────────────┐
│ gongfeng-cli (命令行工具) │ ← Agent 直接调用
│ 输出优化 / 帮助系统 / 认证 │
├─────────────────────────────┤
│ gongfeng-sdk-go (Go SDK) │ ← 程序化集成
│ 完整 API 覆盖 / 类型安全 │
└─────────────────────────────┘
CLI 面向 AI Agent 做 token 优化；SDK 面向 Go 开发者提供类型安全的全 API 覆盖。两层独立演进、互不耦合。如果你需要在自己的 Agent 框架中深度集成工蜂能力，直接 go get github.com/studyzy/gongfeng-sdk-go@latest 引入 SDK 即可。
三、功能覆盖：一个 CLI 覆盖完整的代码托管工作流
gongfeng-cli 并非只覆盖 MR 和分支这类高频操作。它的目标是让 AI Agent 能够完整地参与代码托管平台上的一切协作活动：
gongfeng
├── auth 认证管理
├── project 项目管理（CRUD、成员、共享、标星）
├── mr 合并请求（创建、评审、合并、变更查看）
├── branch 分支管理
├── commit 提交管理（列表、详情、Diff、评论）
├── commit-status CI/CD 检测状态
├── tag 标签管理
├── issue 缺陷跟踪
├── review 代码评审（MR 评审 + Commit 评审）
├── release 版本发布
├── repo 仓库文件操作（读/写/删/比较）
├── group 项目组管理
├── namespace 命名空间
├── label 标签分类
├── milestone 里程碑
├── note 评论系统（MR/Issue/Review 评论）
├── fork Fork 管理
├── user 用户信息
├── watcher 关注管理
└── webhook Webhook 配置
这意味着 AI Agent 可以执行从"查看代码变更并提交评审意见"到"创建 Release 并配置 Webhook 通知"的完整开发流程，无需切换工具。
四、实测对比：CLI vs MCP 在代码托管场景的 Token 差异
让我们用一个真实场景做对比。假设 Agent 需要完成一个典型的代码评审流程：
- 查看 MR 列表找到待评审的 MR
- 获取 MR 详情了解变更意图
- 查看代码变更（diff）
- 提交评审意见
4.1 MCP 方案的 Token 消耗
以 gongfeng-cli 覆盖的 20 个工具组为例，假设每个工具的 JSON Schema 平均 300 token（含参数定义和描述），MCP 需要在每轮对话中注入：
Schema 注入：20 × 300 = 6,000 token/轮
4 轮对话 Schema 总计：24,000 token
这 24,000 token 纯粹是"协议税"——不产生任何有效信息，只是告诉模型"你有这些工具可以用"。
4.2 gongfeng-cli 方案的 Token 消耗
第 1 轮：gongfeng --help（约 800 token，获取命令参考卡，此后永不重复）
第 2-4 轮：0 token（Agent 已知如何调用，无需额外注入）
Schema 级别 Token 节省：24,000 vs 800，节约 30 倍。
如果对话持续 10 轮（Agent 在评审过程中需要反复查看代码、追问作者、检查 CI），差距会指数级放大。
五、快速上手
安装
go install github.com/studyzy/gongfeng-cli/cmd/gongfeng@latest
认证配置
# 交互式登录（Token 写入 ~/.gongfeng.json）
gongfeng auth login --token <your_private_token>
# 或通过环境变量
export GONGFENG_TOKEN=<your_private_token>
支持四级凭据优先链：CLI flags > 环境变量 > 项目级配置 > 全局配置。
日常使用示例
# 查看当前用户信息
gongfeng user me
# 列出项目 MR
gongfeng mr list --project-id myteam/backend --state opened
# 查看 MR 代码变更
gongfeng mr changes 42
# 创建 MR 并指定评审人
gongfeng mr create \
--source-branch feature/auth \
--target-branch main \
--title "feat: 接入 OAuth 2.0" \
--reviewers "zhangsan,lisi"
# 通过评审
gongfeng review approve 42 --message "LGTM，代码质量很好"
# 检查 CI 状态
gongfeng commit-status result main
# 合并 MR
gongfeng mr accept 42
与 AI 编程工具集成
在 Claude Code 的 CLAUDE.md 中添加：
## 工蜂操作
使用 `gongfeng` 命令管理代码仓库，执行 `gongfeng --help` 查看可用命令。
项目 ID: myteam/backend
Agent 读取到这段指引后，会自动调用 gongfeng --help 获取完整命令参考，此后即可自主完成代码托管相关的一切操作。
六、设计决策背后的思考
为什么详情默认 Markdown 而非 JSON？
大语言模型的训练语料中，Markdown 是占比最高的结构化文本格式之一。用 YAML frontmatter 承载元数据、用 Markdown 正文承载自由文本（如 MR 描述、Issue 详情），这恰好贴合模型的阅读惯性。实测表明，同样的信息用 Markdown 呈现比完整 JSON 节省约 40% 的 token，同时模型的理解准确率不降反升。
为什么帮助输出是平铺的"参考卡"而非树形结构？
树形结构对人类友好，但对 LLM 而言，缩进层级会引入不必要的格式 token。参考卡的平铺设计确保每条命令恰好占一行，Agent 可以通过简单的行扫描定位目标命令，认知效率最高。
为什么错误输出也是结构化 JSON？
{"error":"authentication_required","message":"No valid credentials found","hint":"Run 'gongfeng auth login --token <token>'."}
Agent 遇到错误时需要快速判断：是参数问题还是权限问题？能否自动修复？结构化的错误码 + 提示信息让 Agent 能够精确地自我纠错，而不是靠"阅读理解"一段自然语言错误消息。
七、深入底层：gongfeng-sdk-go
前面反复提到"SDK 与 CLI 分层"，那么底层的 gongfeng-sdk-go 究竟长什么样？为什么要把它独立出来？
7.1 设计哲学：极简依赖，完整覆盖
gongfeng-sdk-go 的设计遵循一个朴素原则：做好一件事，不引入不必要的复杂性。
翻看它的 go.mod，你会发现直接依赖只有一个：
require github.com/google/go-querystring v1.1.0
没有重型 HTTP 框架，没有 ORM 式的抽象层，整个 HTTP 客户端基于标准库的 net/http 自建。这意味着：
- 引入 SDK 不会带来传递依赖的膨胀
- 编译速度快，二进制体积小
- 与任何 Go 项目的技术栈都不会冲突
7.2 架构：一个 Client，二十个 Service
SDK 的核心是一个 Client 结构体，通过函数式选项模式（Functional Options）配置：
// 连接公有云工蜂
client, err := gongfeng.NewClient("your-private-token")
// 连接私有部署实例
client, err := gongfeng.NewClient("your-private-token",
gongfeng.WithBaseURL("https://git.example.com/"),
)
// 注入自定义 HTTP Client（便于测试或加入中间件）
client, err := gongfeng.NewClient("your-private-token",
gongfeng.WithHTTPClient(myCustomClient),
)
每个 API 资源被封装为独立的 Service，挂载在 Client 上：
client.Projects // 项目管理
client.MergeRequests // 合并请求
client.Branches // 分支管理
client.Commits // 提交管理
client.CommitStatuses // CI/CD 状态
client.Reviews // 代码评审
client.Issues // 缺陷跟踪
client.Repositories // 仓库文件操作
client.Releases // 版本发布
client.Notes // 评论系统
client.Labels // 标签
client.Milestones // 里程碑
client.Groups // 项目组
client.Namespaces // 命名空间
client.Tags // Tag 管理
client.Users // 用户信息
client.Forks // Fork 管理
client.Watchers // 关注管理
client.Webhooks // Webhook 配置
client.Session // 会话认证
这种"按资源拆文件"的组织方式让每个 Service 的代码量控制在几百行以内，定位和维护都非常方便。
7.3 类型系统：让编译器替你检查参数
SDK 为所有 API 操作定义了强类型的 Options 结构体和返回类型。以创建 MR 为例：
opts := &gongfeng.CreateMergeRequestOptions{
SourceBranch: gongfeng.Ptr("feature/login"),
TargetBranch: gongfeng.Ptr("main"),
Title: gongfeng.Ptr("feat: 用户登录模块"),
Description: gongfeng.Ptr("实现了基于 JWT 的登录认证"),
Reviewers: gongfeng.Ptr("zhangsan,lisi"),
}
mr, resp, err := client.MergeRequests.CreateMergeRequest(ctx, "myteam/backend", opts)
几个值得注意的设计选择：
- 泛型
Ptr[T]辅助函数——用gongfeng.Ptr("value")代替手动取地址，既简洁又明确表达"这是一个可选参数，我主动设置了它" interface{}类型的项目 ID——同时支持整数 ID（12345）和字符串路径（"myteam/backend"），内部自动处理 URL 编码- 所有方法接受
context.Context——原生支持超时控制、取消传播和链路追踪
7.4 分页与错误处理：开箱即用
SDK 对工蜂 API 的分页 Header 做了统一封装：
projects, resp, err := client.Projects.ListProjects(ctx, &gongfeng.ListProjectsOptions{
ListOptions: gongfeng.ListOptions{Page: 1, PerPage: 20},
Search: gongfeng.Ptr("backend"),
})
fmt.Printf("共 %d 个项目，当前第 %d/%d 页\n",
resp.TotalItems, resp.CurrentPage, resp.TotalPages)
Response 结构体自动从 X-Total、X-Total-Pages、X-Page 等响应头中提取分页信息，调用者无需手动解析。
错误处理同样结构化：
_, _, err := client.MergeRequests.GetMergeRequest(ctx, "myteam/backend", 9999)
if err != nil {
// err 是 *gongfeng.ErrorResponse 类型
// 包含 HTTP 状态码、请求 URL 和工蜂返回的错误消息
fmt.Println(err) // "GET https://git.code.tencent.com/api/v3/...: 404 Not Found"
}
7.5 TLS 兼容性：对企业内网友好
实际使用中，不少企业内部部署的工蜂实例 TLS 配置较旧。SDK 默认启用了宽松的 TLS 密码套件兼容：
func newDefaultHTTPClient() *http.Client {
var suites []uint16
for _, s := range tls.CipherSuites() {
suites = append(suites, s.ID)
}
for _, s := range tls.InsecureCipherSuites() {
suites = append(suites, s.ID)
}
return &http.Client{
Transport: &http.Transport{
TLSClientConfig: &tls.Config{
MinVersion: tls.VersionTLS12,
CipherSuites: suites,
},
},
}
}
这意味着拿到 SDK 即可直连内部工蜂，无需额外处理证书兼容问题——对企业内部推广至关重要。
7.6 典型集成场景
gongfeng-sdk-go 适用于以下场景：
场景一：自定义 CI/CD 工具
// 在 CI 流水线中自动上报构建状态
client.CommitStatuses.CreateCommitStatus(ctx, projectID, sha,
&gongfeng.CreateCommitStatusOptions{
State: gongfeng.Ptr("success"),
Name: gongfeng.Ptr("unit-test"),
TargetURL: gongfeng.Ptr("https://ci.example.com/builds/123"),
Description: gongfeng.Ptr("All 42 tests passed"),
})
场景二：自动化代码评审 Bot
// 拉取 MR 变更，分析后自动提交评论
changes, _, _ := client.MergeRequests.GetMergeRequestChanges(ctx, pid, mrID)
for _, diff := range changes.Files {
if issues := analyze(diff); len(issues) > 0 {
client.Notes.CreateMRNote(ctx, pid, mrID,
&gongfeng.CreateMRNoteOptions{
Body: gongfeng.Ptr(formatReview(issues)),
Path: gongfeng.Ptr(diff.NewPath),
Line: gongfeng.Ptr(issues[0].Line),
})
}
}
场景三：构建自己的 Agent 工具链
如果你正在开发自己的 AI Agent 框架，不满足于 CLI 的交互方式，可以直接基于 SDK 构建更贴合需求的工具层——比如一个 MCP Server、一个 HTTP 网关、或者一个 gRPC 服务。SDK 提供的是纯粹的 API 客户端能力，不绑定任何上层形态。
7.7 CLI 与 SDK 的关系
回到分层架构的全景：
┌──────────────────────────────────────────────┐
│ AI Agent (Claude Code / Cursor / 自研框架) │
│ "gongfeng mr list --state opened" │
├──────────────────────────────────────────────┤
│ gongfeng-cli │
│ · 输出格式优化（Markdown/JSON 自动选择） │
│ · 参考卡式帮助系统 │
│ · 认证管理（四级优先链） │
│ · 错误信息结构化 │
├──────────────────────────────────────────────┤
│ gongfeng-sdk-go │
│ · 完整的工蜂 v3 API 覆盖 │
│ · 强类型参数与响应 │
│ · 统一分页/错误处理 │
│ · TLS 兼容 / 函数式选项 │
└──────────────────────────────────────────────┘
CLI 专注于"如何让 AI Agent 高效交互"，SDK 专注于"如何正确调用工蜂 API"。两者职责清晰，独立发布、独立版本、独立测试。你可以只用 SDK 而不用 CLI，也可以只用 CLI 而不关心 SDK 的存在——但如果你想扩展 CLI 或构建新工具，SDK 就是你的起点。
八、总结与展望
回顾 tapd-ai-cli 到 gongfeng-cli 的实践，几个核心认知逐渐清晰：
-
工具设计比协议更重要——CLI 的优势不是因为 bash 比 MCP 更好，而是因为一个精心设计的 CLI 天然具备渐进发现、无状态调用、管道组合等 Agent 友好的特性。
-
Token 意识应贯穿每一个设计决策——从输出格式的选择（Markdown vs JSON）、帮助系统的排版（平铺 vs 树形）、到错误信息的结构（JSON vs 自然语言），每一处都是 token 优化的机会。
-
覆盖完整工作流才有实际价值——如果 Agent 做到一半需要切换到另一个工具，上下文切换的代价会吞噬掉所有节省。gongfeng-cli 覆盖了从项目管理到代码评审的完整生命周期，让 Agent 可以在单一工具内完成所有操作。
-
SDK 与 CLI 的分层是长期可维护的关键——底层 SDK 保证 API 覆盖的完整性和类型安全，上层 CLI 专注 Agent 交互优化，两层独立演进、互不拖累。
gongfeng-cli 和 tapd-ai-cli 分别覆盖了代码托管与项目管理两大核心系统。当一个 AI Agent 同时装备了这两个工具，它就拥有了完整的软件工程协作能力——从需求跟踪到代码提交，从分支管理到持续集成，全链路无缝衔接。
这不是终点，而是起点。CLI 作为 AI Agent 与外部世界的通用接口层，其设计原则可以推广到任何系统——文档平台、监控系统、数据库管理……每一个需要与 AI Agent 协作的系统，都值得拥有一个精心设计的命令行工具。
项目地址：
- gongfeng-cli: github.com/studyzy/gongfeng-cli
- gongfeng-sdk-go: github.com/studyzy/gongfeng-sdk-go
欢迎 Star、Issue 和 PR，一起探索 AI Agent 时代的工具设计范式。
浙公网安备 33010602011771号
