《为什么我们把 Agent 的能力做成 CLI：tjucli 的设计》
反思复杂 MCP 与臃肿 RPC 框架的过度封装，深度解析为什么 TJUClaw 将智能体的所有校园与业务能力沉淀为纯粹的 Unix CLI 工具链。
《为什么我们把 Agent 的能力做成 CLI：tjucli 的设计》
在智能体（Agent）生态狂飙突进的今天，每隔几个月就会诞生一种新的“智能体工具集成协议”——从 OpenAI 的 Function Calling、LangChain 的 DynamicTool，到近来备受推崇的 Model Context Protocol (MCP) 与各种自研 RPC 网关。
然而，在 TJUClaw 面向真实校园业务进行工程落地的过程中，我们得出了一个看似逆潮流、实则极度实用主义的结论：
为智能体赋予能力的最佳形态，不是把所有接口都包成昂贵的网络协议或 Python 类库，而是将它们实现为符合 Unix 哲学的标准命令行工具（CLI）。
这正是 tjucli 的诞生初衷。本文将深入探讨为什么我们选择将校园公开数据、资源获取与业务扩展能力收敛到单一二进制可执行文件 tjucli 中，以及它背后的确定性输入输出协议、双模运行架构与严格安全防御。
1. 为什么不是 MCP 或 Python SDK？
在方案选型之初，我们深入评估了当前主流的几种 Agent 扩展手段：
| 方案 | 运行机制 | 核心弊端 |
|---|---|---|
| Python SDK / 动态执行 | 模型直接 import 专用库并调用类方法 | 严重污染执行环境；依赖包版本地狱；模型极易臆想未公开的方法参数 |
| MCP (Model Context Protocol) | 依赖长连接 JSON-RPC 进程间通信 | 协议栈沉重；沙箱内需要常驻后台服务；网络异常与挂起排查成本极高 |
| Function Calling HTTP API | 模型每一步均经由调度中心代理打回 API | 产生大量网络往返延迟；将平台认证 Token 直接暴露在沙箱或 Prompt 中 |
独立二进制 CLI (tjucli) | 子进程一次性唤起 (fork/exec) | 零外部运行依赖；毫秒级启动；输入输出自成文档；标准流自然隔离 |
核心收益：
- Unix 哲学的力量：Do One Thing and Do It Well
智能体在沙箱内天生拥有 Bash 执行能力。调用一个可执行文件并捕获其
stdout，是操作系统最底层、最稳健的原语，没有任何中间通信协议栈的隐形黑盒。 - 人类可调试性与自愈反馈（Self-Correction）
当开发者或运维想要验证某个接口时，无需在 Python REPL 中初始化复杂的 Client，直接在终端敲下
tjucli course search "电路"即可看到输出；模型在参数传错时，CLI 返回的明确退出码（Exit Code 1/2）与友好的 stderr 提示，能够天然指导模型进行多轮上下文自愈。 - 极度轻量与跨平台 采用 Go 1.27 标准库编写，编译生成纯静态单二进制文件，体积仅数兆字节，无任何 libc 依赖，可瞬间分发并挂载到任意轻量级 Linux 沙箱中。
2. 协议设计：确定性 JSON 封套与边界保护
当使用者是 LLM 时，命令行工具的输出绝不能是一段随意的格式化排版字符串，否则模型必须浪费大量的注意力（Attention）去切分换行和提取字段。
tjucli 实现了统一的结构化协议：全量子命令原生支持 --json 标志。
CLI 调用方 (Agent Harness)
│
▼ tjucli course search "线性代数" --json
+------------------+
| tjucli |
+--------+---------+
│
├──────────────────────────────┐
▼ ▼
[标准输出 stdout: 确定性 JSON] [标准错误 stderr: 人类可读排查]
{ [2026-09-17 14:00] scanned 3 pages...
"ok": true,
"data": { "items": [...] },
"meta": { "total": 12 }
}2.1 确定性双封套契约
无论命令执行成功或失败，tjucli 在启用 --json 时均保证输出符合严谨的双封套契约：
- 成功封套 (
ok: true):{ "ok": true, "data": { "items": [ { "name": "线性代数复习讲义.pdf", "path": "/courses/math/linear-algebra.pdf", "size": 4194304 } ] }, "meta": { "scope": "public_courses", "pages_scanned": 3, "incomplete": false } } - 失败封套 (
ok: false):{ "ok": false, "error": { "code": "invalid_argument", "message": "path traversal is strictly forbidden" } }
2.2 防截断与防污染
- 标准流分离：所有过程日志、网络重试警告与调试追踪一律强制打到
stderr，stdout保持绝对纯净的单行/合法 JSON 块，确保 Agent 的解析器直接反序列化而绝不抛出 JSON SyntaxError； - 有界防御：搜索默认限制 20 页、最多 50 条结果（绝对硬上限 100 页 / 1000 条），防止模型输入过宽泛的查询词导致几兆字节的列表撑爆 LLM 上下文。
3. 双模运行架构：本地直连 vs 远端受控代理
为了兼顾开发者本地离线调试与生产沙箱的零信任安全，tjucli 设计了透明的双模运行架构：
+-------------------------------------------------+
| tjucli 统一客户端二进制 |
+-----------------------+-------------------------+
|
TJUCLI_MODE 环境变量路由分支
|
┌────────────────────┴────────────────────┐
▼ ▼
[Mode 1: standalone 本地直连] [Mode 2: remote 生产沙箱代理]
│ │
│ 直接 HTTPS 发起请求 │ 读取 TJUCLI_TOKEN_FILE
│ 适用于个人 CLI / 本地轻量调试 │ 携带 Bearer 令牌发送给网关
▼ ▼
+--------------------+ +--------------------+
| 公开课程云存储源 | | tjucli-server |
| (cs.tjuse.com) | | (内部微服务网关) |
+--------------------+ +---------+----------+
│ 校验 Grant 令牌
▼
+--------------------+
| 受控抓取 / 校园源 |
+--------------------+- Standalone 模式：无需任何后端基础设施，开发者在个人电脑安装后可直接查询与下载公开学习资料，最大程度降低工具链的使用门槛；
- Remote 模式：在生产沙箱环境中强制注入
TJUCLI_MODE=remote，所有网络请求必须经由tjucli-server（端口:18090）转发。沙箱内完全接触不到底层数据源的真实地址、爬虫会话或私钥，所有权限均与单次任务 Run 强绑定。
4. 严苛的文件下载防御与原子落盘
当 Agent 执行诸如 tjucli course download /path/to/file.pdf --output ./math.pdf 时，传统的文件写入实现极易引发竞态条件、越权覆盖或半途崩溃导致的不完整文件。
tjucli 贯彻了极致的防御式编程规范：
- 拒绝路径穿越与越权覆盖：
- 严格规范化输入路径，彻底拦截
../、反斜杠\、控制字符及非法 UTF-8 编码； - 拒绝写入已存在的同名文件，拒绝向软链接（Symlink）写入数据，避免容器内核心系统配置文件被静默篡改。
- 严格规范化输入路径，彻底拦截
- 原子化临时文件与落盘清洗：
- 下载流首先写入工作区同级的隐藏临时文件（如
.math.pdf.tmp）； - 实时校验
Content-Length，一旦下载字节超出上限（沙箱上限 64 MiB）或网络中断，立即无条件清除临时文件，绝不残留半截垃圾数据； - 只有在全量下载完成、且计算出的 SHA-256 哈希完全吻合后，才通过原子重命名（Atomic Rename）发布为最终目标文件。
- 下载流首先写入工作区同级的隐藏临时文件（如
5. 总结：最朴素的工具，最坚固的基石
在 Agent 基础设施的演进历程中，很多人痴迷于设计繁复精细的抽象框架，试图把一切交互都转变为昂贵的高层概念。
但工程的经验反复告诉我们：越是底层的基石，越需要拥抱简单。
tjucli 的实践证明，把 Agent 的能力以符合 Unix 哲学的 CLI 形式封装——提供确定性的 JSON 契约、原子化的文件操作、零外部依赖的纯静态分发与双模安全架构，能够以最小的系统开销，换取最高的可靠性与可维护性。这才是真正经得起长久考验的 Agent 工具底座。