Agent学习之四-初识Agent CLI

一、什么是 Agent CLI？

Agent CLI 其实很简单，就是在终端与 Agent 进行交互，让其具备在控制台操作命令的能力。它非常适合以下场景：

• 记不住命令行操作，需要 Agent 辅助执行；
• 面对大量繁琐的文件操作，希望自动化处理；
• 需要对代码进行规划和设计，提升开发效率。

功能强大，上手简单，是提升终端生产力的好帮手。

二、安装第一个 Agent CLI

注意 ：阿里云 Qoder CLI 不等于 Qoder CLI CN。虽然功能差别不大，但定位不同，账号和 API Key 并不共用------前者针对国际版，后者针对国内用户。本文使用 Qoder CLI CN。

1. 登录注册账号

访问 Qoder 智能体编程平台 注册账号，新用户注册默认赠送两周免费额度（当前活动）。

2. 安装客户端

官网推荐使用命令安装，可惜我的电脑网络不给力，始终安装不成功：

irm https://static.qoder.com.cn/qoder-cli-cn/install.ps1 | iex

索性改用第二种安装方法：

npm install -g @qodercn-ai/qoderclicn

提示：安装前必须安装 Node.js（版本 >= 20.0.0）。

3. 开始使用

在命令行输入以下命令启动（尽量不要在 C 盘操作）：

qodercn

回车即可，输入 /login 登录命令：

两种登录方式（浏览器和 API Key）都可以，这里选择浏览器模式，点击继续即可：

会进入如下界面：

4. 实战案例

核心目标 ：找出 D 盘的核心大文件并删除。

怕误删，先找后删除

思考过程一步步进行，并且每一步都接受确认，安全性高------Agent 会自行判断执行过程是否合理，然后给出建议并征求同意。

三、CLI 内建的 system prompt 文件

在开始之前，先了解下什么是 system prompt。简单来说，它就是给大模型定义的一套身份准则和规范，具备长期性 ；而普通提示词是用户输入的，属于即时性，后一轮对话可能就忘记了。如果两者有冲突，优先满足系统提示词。

补充：system prompt 与 Skills 的区别------Skills 是真正干活落地的，system prompt 是规则的定义者，不负责具体干活。

Qoder CLI CN 的系统提示词文件可以分为 3 大类：

1. 指令类规则文件（AGENTS.md / Rules）

最核心的是 AGENTS.md 文件，Qoder CN CLI 启动时默认就会读取它，把它作为上下文的一部分注入给模型。为了不让 AGENTS.md 变得过于臃肿，你还可以在 .qoder/rules/*.md 目录下拆分。它分为用户级、项目级和本地级，CLI 会按特定顺序向上查找并加载它们。

2. 子代理 / 自定义代理

Subagent 就是直接定义一个"分身"。每个 Subagent 都拥有独立于主代理的系统提示词，还带了自己的专属配置。Subagent 的配置文件是一个 Markdown 文件，正文部分就是它的系统提示词，一般位置在 .qoder/agents/ 下。

3. Skill（技能文件）

这类更偏向于"按需加载的工具包"，它把一套专业知识和流程打包成一个固定的功能模块，主要位于 .qoder/skills/{skill-name}/SKILL.md。

---

当然，其实我理解 Skills 与系统提示词的概念还是有点差距的，指令类规则又太大，所以这一节从子代理进行介绍。

规则 ：写进去 3 件事------你的个性 / 偏好的 code style / 不能做的事。

---
name: my-helper
description: 我的个人编码助手
tools: [Read, Grep, Glob, Write, Edit]
disallowedTools: [Bash]
---

# 我的个性
你是我的结对编程伙伴，比我经验丰富一些。
说话直接但不刻薄，像朋友一样交流。
先理解问题，再给建议，不要上来就甩代码。

# 代码风格偏好
- Python：4空格缩进，用双引号，加类型注解，py文件需要加作者和创建日期
- 函数不超过30行
- 变量用 snake_case

- Go: 符合阿里编程规范
- 每个函数不超过60行代码
- 数据库访问使用ORM框架

- JAVA: 符合阿里编程规范
- 命名使用驼峰规则
- 常量使用统一文件命名
- 使用mybatis-plus作为数据库访问框架

# 不能做的事
- 不执行删除命令
- 不硬编码密码或密钥
- 不用 eval()
- 不编造不存在的函数

开头部分的 YAML 说明：

• name：就是个内部代号，系统用它来调你这个 Agent。
• description：系统用它来做匹配判断------当你的主对话问题匹配到"编码助手"时，系统可能会自动切到这个子代理。这就是系统控制"何时让你出场"的开关。
• tools 和 disallowedTools：才是真正的"权力清单"。

创建成功后，使用 /agents reload 加载即可。

实战案例：用 @my-helper 编写天气查询 API

需求 ：使用 @my-helper，编写一个查询明天天气的 API，需要使用 Python、Java 和 Go 实现，分别给出代码案例。

下面是生成的 Python 代码示例：

# Author: AI Pair Programming
# Created: 2025-01-20
# Description: 查询明天天气的 FastAPI 实现，调用 OpenWeatherMap API

import os
from datetime import datetime, timedelta
from typing import Optional

import httpx
from fastapi import FastAPI, HTTPException, Query
from pydantic import BaseModel

app = FastAPI(title="Weather API", description="查询明天天气的API服务")

# OpenWeatherMap API 配置
# 请设置环境变量 OPENWEATHER_API_KEY，或在下方直接填入你的 API Key
OPENWEATHER_API_KEY: str = os.getenv("OPENWEATHER_API_KEY", "your_api_key_here")
OPENWEATHER_BASE_URL: str = "https://api.openweathermap.org/data/2.5/forecast"


class WeatherResponse(BaseModel):
    """明天天气响应模型"""
    city: str
    date: str
    temperature_min: float
    temperature_max: float
    description: str
    humidity: int
    wind_speed: float


def get_tomorrow_noon_timestamp() -> int:
    """获取明天中午12点的时间戳，用于筛选最接近的预报数据"""
    tomorrow = datetime.now() + timedelta(days=1)
    tomorrow_noon = tomorrow.replace(hour=12, minute=0, second=0, microsecond=0)
    return int(tomorrow_noon.timestamp())


def find_tomorrow_forecast(forecast_list: list, target_ts: int) -> Optional[dict]:
    """从5天预报列表中找到最接近明天中午的数据"""
    closest = None
    min_diff = float("inf")

    for item in forecast_list:
        diff = abs(item["dt"] - target_ts)
        if diff < min_diff:
            min_diff = diff
            closest = item

    return closest


@app.get("/weather/tomorrow", response_model=WeatherResponse)
async def get_tomorrow_weather(
    city: str = Query(..., description="城市名称，如 Beijing, Shanghai"),
):
    """
    查询指定城市明天的天气预报。
    参数:
        city: 城市名称（英文）
    返回:
        WeatherResponse: 包含温度、天气描述、湿度、风速等信息
    """
    if OPENWEATHER_API_KEY == "your_api_key_here":
        raise HTTPException(
            status_code=500,
            detail="请先设置 OPENWEATHER_API_KEY 环境变量",
        )

    params = {
        "q": city,
        "appid": OPENWEATHER_API_KEY,
        "units": "metric",
        "lang": "zh_cn",
    }

    async with httpx.AsyncClient(timeout=10.0) as client:
        response = await client.get(OPENWEATHER_BASE_URL, params=params)

    if response.status_code != 200:
        raise HTTPException(
            status_code=response.status_code,
            detail=f"天气API请求失败: {response.text}",
        )

    data = response.json()
    target_ts = get_tomorrow_noon_timestamp()
    tomorrow_data = find_tomorrow_forecast(data.get("list", []), target_ts)

    if tomorrow_data is None:
        raise HTTPException(status_code=404, detail="未找到明天的天气数据")

    tomorrow_date = (datetime.now() + timedelta(days=1)).strftime("%Y-%m-%d")

    return WeatherResponse(
        city=data.get("city", {}).get("name", city),
        date=tomorrow_date,
        temperature_min=tomorrow_data["main"]["temp_min"],
        temperature_max=tomorrow_data["main"]["temp_max"],
        description=tomorrow_data["weather"][0]["description"],
        humidity=tomorrow_data["main"]["humidity"],
        wind_speed=tomorrow_data["wind"]["speed"],
    )


# ============================================================
# 运行方式:
#   1. 安装依赖: pip install -r requirements.txt
#   2. 设置环境变量: set OPENWEATHER_API_KEY=你的API密钥 (Windows)
#                    export OPENWEATHER_API_KEY=你的API密钥 (Linux/Mac)
#   3. 启动服务: uvicorn weather_api:app --reload --port 8000
#   4. 访问接口: http://localhost:8000/weather/tomorrow?city=Beijing
#   5. API文档:  http://localhost:8000/docs
# ============================================================

提供了相应的依赖：

fastapi>=0.104.0
uvicorn>=0.24.0
httpx>=0.25.0
pydantic>=2.0.0

虽然给出了很多要求，但是ai并不一定完全都遵守，如最大30行代码。后续补充详细约束规则。

四、新装一个 CLI，并使用它完成功能

这一节我们换一个 CLI 来体验------Kimi Code CLI，看看它在实际任务中的表现如何。

1. 安装 Kimi Code CLI

Windows 用户，使用以下命令安装：

irm https://code.kimi.com/kimi-code/install.ps1 | iex

2. 配置 API Key

登录 Kimi 网站，注册后，选择「用户中心 → API KEY 管理」：

注册 API-Key 后，记得保存好，否则得重新创建：

sk-xxxxxxxxxxxxxxxxxxxxxxxxx

3. 启动并登录

进入需要使用 Kimi Code CLI 的项目目录，然后启动：

kimi

接着输入登录命令，输入token即可：

/login

4. 实战任务：查找 C 盘大文件

任务目标 ：查找 C 盘下大于 1G 的文件，并区分可删除 和不可删除文件。

首先选择了 Kimi 2.6，中途执行失败退出了：

kimi2.6有点拉胯，直接替换2.7来操作：

并且给我生成了相应的脚本文件：

使用管理员运行 .bat 文件，报错：

将报错内容发送给客户端后，重新修改代码，最终运行成功：

5. 小结：Kimi 2.7 与 Qoder CN 的对比

在我看来，Kimi 2.7 的执行流程也是可以的（Kimi 2.6 有点拉胯），确认和思考环节基本和 Qoder CN 差不多。但最大的差别在于：执行结果是否直接返回，还是需要手工运行。期待kimi的进一步发展

五、认证细节

这一节我们换个简单的场景来体验------输入错误模型和错误 token 时的表现。生产环境中，这类问题会经常遇到，提前了解报错形态有助于快速排查。

1. 输入错误 token

填写错误 token 有两种方式，一种直接在环境变量中设置错误或过期的 token。

• 设置错误环境变量：

set QODERCN_PERSONAL_ACCESS_TOKEN=pt-e43L4svYHsjprQWi9TgKHwhj_01a050ae-b8a2-7d1d-*******

返回错误的信息：

• 通过 /login 登录方式进行错误验证：

填写正确的 API Key 能够进入平台（无论是环境变量还是本地登录）：

2. 填写错误模型

使用 -m 参数指定一个不存在的模型：

qodercn -m DeepSeek-V4-Pro2

六、总结

本文围绕 Agent CLI 实战体验 展开，从概念、安装、配置、实战到排错层层递进，覆盖 Qoder CLI CN 与 Kimi Code CLI 两款工具，兼具操作步骤与真实踩坑记录。核心要点提炼如下：

1. 核心概念

Agent CLI 是在终端与 Agent 交互、让其具备控制台操作命令能力的方式，适合记不住命令、繁琐文件操作、代码规划等场景，功能强大、上手简单。

2. 安装与配置

• Qoder CLI CN ：注册账号（赠送两周免费额度）→ 官方命令安装失败后改用 npm install -g @qodercn-ai/qoderclicn，需 Node.js >= 20 → 启动后 /login 登录（浏览器 / API Key 两种方式）。
• Kimi Code CLI ：irm 命令安装 → 配置 API Key → 启动后 /login 输入 token。

3. 系统提示词体系

Qoder CLI CN 的 system prompt 分为 3 大类：

• 指令类规则文件 （AGENTS.md / Rules）：定义长期身份准则，启动时自动注入；
• 子代理 / 自定义代理（Subagent）：独立系统提示词的"分身"，通过 YAML 配置个性、代码风格与禁止事项；
• Skill 技能文件：按需加载的专业知识工具包。

实战中，@my-helper 子代理能按约束生成多语言代码，但 AI 未必完全遵守所有限制（如 30 行代码），需后续补充更细的约束规则。

4. 实战对比

两款 CLI 的执行流程相近，均具备分步思考、逐步确认的安全机制。最大差别在于：执行结果是否直接返回，还是需要手工运行。Kimi 2.6 表现欠佳，2.7 明显改善。

5. 排错经验

生产环境中常见两类认证问题：输入错误 token （环境变量 / /login 两种方式）与填写错误模型 （-m 指定不存在的模型）。提前了解报错形态，有助于快速定位与排查。

一句话总结：Agent CLI 上手简单、实战性强，选对工具、配好提示词、掌握排错技巧，就能显著提升终端生产力。

下一章会继续介绍可用的Agent CLI，提高团队生产力