feat: implement hgctl agent & mcp add subcommand
#3051
Conversation
erasernoob
requested review from
2456868764,
Xunzhuo and
johnlanni
as code owners
实现
|
| 文件路径 | 变更说明 |
|---|---|
| hgctl/go.mod | 升级了 Go 版本和工具链，并新增了多个依赖库。 |
| hgctl/pkg/agent/agent.go | 实现了 `hgctl agent` 命令，用于启动交互式代理窗口。 |
| hgctl/pkg/agent/base.go | 定义了代理核心环境检查逻辑，包括 Node.js 和代理 CLI 的安装状态检查。 |
| hgctl/pkg/agent/core.go | 实现了代理核心执行逻辑，通过 `exec.Command` 调用底层 CLI。 |
| hgctl/pkg/agent/mcp.go | 实现了 `hgctl mcp add` 命令，支持添加 HTTP 和 OpenAPI 类型的 MCP 服务，并与 Higress 控制台集成。 |
| hgctl/pkg/agent/services/client.go | 实现了 Higress 控制台 HTTP 客户端，用于与控制台 API 交互。 |
| hgctl/pkg/agent/services/service.go | 实现了与 Higress 控制台服务源和 MCP 服务器管理相关的 API 调用。 |
| hgctl/pkg/agent/types.go | 定义了与代理交互相关的数据结构，如消息、请求、响应等。 |
| hgctl/pkg/agent/utils.go | 实现了工具函数，包括 Node.js 安装检查、提示安装逻辑、OpenAPI 解析等。 |
时序图
sequenceDiagram
participant User as 用户
participant Hgctl as hgctl CLI
participant Agent as Claude Agent
participant Higress as Higress 控制台
User->>Hgctl: hgctl agent
Hgctl->>Hgctl: 检查 Node.js 和 Agent 安装
Hgctl->>User: 提示安装 Node.js (如未安装)
User->>Hgctl: 选择安装方式
Hgctl->>Hgctl: 自动安装 Node.js
Hgctl->>User: 提示安装 Agent CLI (如未安装)
User->>Hgctl: 确认安装
Hgctl->>Hgctl: 安装 Agent CLI
Hgctl->>Agent: 启动 Agent CLI
User->>Hgctl: hgctl mcp add <name> -t http <url>
Hgctl->>Agent: 调用 Agent CLI 添加 MCP 服务
Agent->>Higress: 发布 MCP 服务到 Higress 控制台
User->>Hgctl: hgctl mcp add <name> -t openapi --spec <file>
Hgctl->>Hgctl: 解析 OpenAPI 规范
Hgctl->>Higress: 发布 OpenAPI 服务到 Higress 控制台
Higress->>Higctl: 返回服务信息
Hgctl->>Agent: 添加 MCP 服务到 Agent
💡 小贴士
与 lingma-agents 交流的方式
📜 直接回复评论
直接回复本条评论，lingma-agents 将自动处理您的请求。例如：
-
在当前代码中添加详细的注释说明。
-
请详细介绍一下你说的 LRU 改造方案，并使用伪代码加以说明。
📜 在代码行处标记
在文件的特定位置创建评论并 @lingma-agents。例如：
-
@lingma-agents 分析这个方法的性能瓶颈并提供优化建议。
-
@lingma-agents 对这个方法生成优化代码。
📜 在讨论中提问
在任何讨论中 @lingma-agents 来获取帮助。例如：
-
@lingma-agents 请总结上述讨论并提出解决方案。
-
@lingma-agents 请根据讨论内容生成优化代码。
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3051 +/- ##
==========================================
+ Coverage 35.91% 43.30% +7.39%
==========================================
Files 69 82 +13
Lines 11576 10898 -678
==========================================
+ Hits 4157 4719 +562
+ Misses 7104 5851 -1253
- Partials 315 328 +13 🚀 New features to boost your workflow:
|
![lingma-agents[bot]](https://avatars.githubusercontent.com/in/1198481?s=60&v=4){kind=small}
There was a problem hiding this comment.
🔎 代码评审报告
🎯 评审意见概览
| 严重度 | 数量 | 说明 |
|---|---|---|
| 🔴 Blocker | 0 | 阻断性问题，需立即修复。例如：系统崩溃、关键功能不可用或严重安全漏洞。 |
| 🟠 Critical | 2 | 严重问题，高优先级修复。例如：核心功能异常或性能瓶颈影响用户体验。 |
| 🟡 Major | 2 | 主要问题，建议修复。例如：非核心功能缺陷或代码维护性较差。 |
| 🟢 Minor | 2 | 次要问题，酬情优化。例如：代码格式不规范或注释缺失。 |
总计: 6 个问题
📋 评审意见详情
💡 代码实现建议
以下是文件级别的代码建议，聚焦于代码的可读性、可维护性和潜在问题。
📄 hgctl/go.mod (1 💬)
- 应明确指定 Go 工具链版本以确保构建一致性。 (L3-L5)
🔹 hgctl/pkg/agent/mcp.go (2 💬)
- 部分字段命名存在歧义需优化以清晰表达意图。 (L27-L42)
- 打印语句应替换为结构化日志记录以方便调试与监控。 (L109-L112)
🔹 hgctl/pkg/agent/services/client.go (1 💬)
- 客户端超时时间不宜固定应可根据需求调整。 (L25-L27)
🔹 hgctl/pkg/agent/utils.go (2 💬)
🚀 架构设计建议
以下是对代码架构和设计的综合分析，聚焦于跨文件交互、系统一致性和潜在优化空间。
🔍1. 依赖管理中引入了过多间接依赖，可能增加安全与维护风险
在 go.mod 和 go.sum 中新增了大量间接依赖（如 github.com/chzyer/readline、github.com/getkin/kin-openapi 等），这些依赖虽然未被直接使用，但会增大项目的攻击面并提高长期维护成本。建议审查是否所有新增的依赖都是必要的，并考虑通过工具（如 go mod tidy）清理不必要的间接依赖。
📌 关键代码
潜在的安全漏洞、构建时间增长、未来升级冲突的风险增加
🔍2. 外部命令执行缺乏上下文控制和错误恢复机制
在多个文件中（例如 core.go 的 run() 方法、utils.go 的自动安装函数等）频繁使用 exec.Command 执行外部命令且没有设置上下文超时或重试逻辑，这可能导致进程阻塞或无法优雅退出。此外，在子进程中直接使用 os.Exit(1)（如 utils.go 第287行和第315行）会影响主程序对错误的统一处理能力。推荐改用可取消的上下文并返回错误供上层调用者决定如何处理。
📌 关键代码
func (c *AgenticCore) run(args ...string) error {
cmd := exec.Command(AgentBinaryName, args...)
cmd.Stdin = os.Stdin
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
return cmd.Run()
}if err != nil {
fmt.Printf("Error parsing OpenAPI specification: %v\n", err)
os.Exit(1)
}if err != nil {
fmt.Printf("add openapi tools failed: %v\n", err)
os.Exit(1)
}系统挂起、资源泄露、异常终止导致状态不一致、难以集成到更复杂的流程控制中
🔍3. 业务逻辑分散于多个模块间，缺乏集中协调与抽象
当前实现中，MCP 添加功能涉及从参数解析 (mcp.go) 到服务源创建和服务注册 (services/service.go) 再到最终向 Agent 发送指令 (core.go) 多个步骤，其间缺少一个中央协调器来编排整个操作流。这种设计容易造成重复代码、接口不匹配以及扩展性差的问题。建议引入一个高层级的操作协调器负责整体流程调度，并将通用行为抽象成独立组件。
📌 关键代码
func handleAddMCP(w io.Writer, arg MCPAddArg) error {
client := getAgent()
h := newHanlder(client, arg, w)
if err := h.validateArg(); err != nil {
return err
}
switch arg.transport {
case HTTP:
return h.addHTTPMCP()
case OPENAPI:
...
}
}func HandleAddMCPServer(client *HigressClient, body interface{}) ([]byte, error) {
data, ok := body.(map[string]interface{})
...
resp, err := client.Put("/v1/mcpServer", data)
if err != nil {
return nil, fmt.Errorf("failed to add mcp server: %w", err)
}
return resp, nil
}各部分之间耦合度高、变更影响范围不可控、新特性开发困难、单元测试覆盖率低
🔍4. 硬编码常量及路径限制跨平台兼容性和灵活性
项目中存在不少硬编码值，比如 AgentBinaryName="claude"（见 base.go）、特定操作系统的安装脚本（如 utils.go 中判断 Darwin/Linux 自动安装方式）等，这类做法降低了代码的适应性和移植性。应当尽量采用配置驱动或者运行时检测的方式来替代静态定义的关键字和行为规则。
📌 关键代码
const (
AgentBinaryName = "claude"
BinaryVersion = "0.1.0"
DevVersion = "dev"
NodeLeastVersion = 18
AgentInstallCmd = "npm install -g @anthropic-ai/claude-code"
AgentReleasePage = "https://docs.claude.com/en/docs/claude-code/setup"
)func installNodeAutomatically() error {
switch runtime.GOOS {
case "windows":
color.Cyan("📦 Please download Node.js installer from https://nodejs.org and run it manually on Windows")
return errors.New("automatic installation not supported on Windows yet")
case "darwin":
// macOS: use brew
cmd := exec.Command("brew", "install", "node")
cmd.Stdout = os.Stdout
cmd.Stderr = os.Stderr
return cmd.Run()
case "linux":
...
}
}不同环境部署失败、难以支持更多操作系统类型、后期修改成本高昂
🔍5. 缺少完整的端到端测试覆盖策略
尽管实现了较为复杂的功能（如 OpenAPI 转换为 MCP 配置、远程服务交互等），但在现有代码中并未看到任何关于自动化测试的设计或编写痕迹。特别是对于网络请求模拟、JSON/YAML 解析准确性验证等方面尤为关键。强烈建议补充针对核心数据流转路径的 mock 测试用例，以保障后续迭代质量稳定。
回归缺陷频发、对外部系统强依赖导致 CI 不稳定、重构信心不足
审查详情
📒 文件清单 （12 个文件）
✅ 新增: 8 个文件
📝 变更: 4 个文件
✅ 新增文件:
hgctl/pkg/agent/agent.gohgctl/pkg/agent/base.gohgctl/pkg/agent/core.gohgctl/pkg/agent/mcp.gohgctl/pkg/agent/services/client.gohgctl/pkg/agent/services/service.gohgctl/pkg/agent/types.gohgctl/pkg/agent/utils.go
📝 变更文件:
hgctl/go.modhgctl/go.sumhgctl/pkg/root.gotools/hack/get-hgctl.sh
💡 小贴士
与 lingma-agents 交流的方式
📜 直接回复评论
直接回复本条评论，lingma-agents 将自动处理您的请求。例如：
-
在当前代码中添加详细的注释说明。
-
请详细介绍一下你说的 LRU 改造方案，并使用伪代码加以说明。
📜 在代码行处标记
在文件的特定位置创建评论并 @lingma-agents。例如：
-
@lingma-agents 分析这个方法的性能瓶颈并提供优化建议。
-
@lingma-agents 对这个方法生成优化代码。
📜 在讨论中提问
在任何讨论中 @lingma-agents 来获取帮助。例如：
-
@lingma-agents 请总结上述讨论并提出解决方案。
-
@lingma-agents 请根据讨论内容生成优化代码。
|
Thank you for your contribution. This is great work and a crucial step in transitioning Higress's own management from a cloud-native model to an AI model |
3 participants
Ⅰ. Describe what this PR did
Enhance hgctl command tool by implementing two subcommand:
hgctl mcphgctl agenthgctl agentThis command will invoke the agent cli under the hood (currently is
claude-code). hgctl will prompt user to set up prequisite environment in a interactive window in user's first-time usage.mcp addThis command can directly call the Higress Console API and publish the server to the Higress MCP Server management tool.
Extend the -t parameter of claude mcp add by adding a new openapi type and an additional --spec parameter, allowing users to provide an OpenAPI specification. OpenAPI-type MCP servers can then directly call the Higress Console API to be published to the Higress MCP Server management tool.
Consistent user experience:
Both types of MCP tools can be used directly in the interactive hgctl agent window, maintaining a consistent experience.
Optional publishing:
Add a --no-publish parameter to claude mcp add. If specified, the corresponding MCP server will not be published to Higress and can only be used in the interactive agent window. (Note: the OpenAPI-type MCP server does not support this parameter, since this capability requires traffic to go through Higress.)
Ⅱ. Does this pull request fix one issue?
fixes #3052
Ⅲ. Why don't you add test cases (unit test/integration test)?
Ⅳ. Describe how to verify it
Ⅴ. Special notes for reviews