如何让 AI 智能体更聪明：CangjieMagic-Examples 中 @tool 注解与任务规划的完整指南-平芜编程栈

如何让 AI 智能体更聪明：CangjieMagic-Examples 中 @tool 注解与任务规划的完整指南

【免费下载链接】CangjieMagic-Examples项目地址: https://gitcode.com/Cangjie/CangjieMagic-Examples

CangjieMagic-Examples是 Cangjie Magic 框架的官方示例仓库，它用三个真实项目（端侧智能体MagicAgent、RAG 代码助手CangjieRAGCodeAssistant、MCP 工具服务集合CangjieMagicMCPServer）演示了智能体开发中最核心的两件事：用@tool注解把普通函数变成大模型可调用、可自主规划的工具。读完本文，你就能理解"工具设计模式"是怎么让 Agent 从"会聊天"变成"会干活"的。

🗂️ 一图看懂：仓库里的三类智能体示例

模块	定位	核心看点
`CangjieMagicMCPServer/`	工具集（MCP Server）	`@tool`注解的完整形态：参数描述、示例、安全边界、自动修复
`MagicAgent/`	端侧智能体 App	任务规划工具 +`react`执行器 + MCP 混合接入
`CangjieRAGCodeAssistant/`	本地 RAG 助手	`@agent`声明式绑定检索源，代码问答助手

其中工具示例覆盖了 5 种典型场景：fetcher（网页抓取+语义检索）、filesystem（文件操作+摘要）、pyexec（代码执行+自动修复）、imageGen（文生图）、time（时间查询），完整源码见 CangjieMagicMCPServer/README.md。

🔧 @tool 注解深度解析：Agent 调用工具前的"说明书"

大模型本身不能执行代码，它只能"决定"调用哪个工具、传什么参数。@tool注解的作用，就是把一个普通函数翻译成模型能读懂的"说明书"。

1. 最小用法：零参数工具

最简单的工具只需要一句功能描述，见 time/src/main.cj：

@tool[ description = "获取当前时间" ] public func getCurrentTime(): String { ... }

配合一行StdioMCPServer.startWith(getCurrentTime)，这个函数就成了标准 MCP 协议下的可调用工具。描述写得越准确，模型选工具、传参数就越准——这是工具设计的第一原则。

2. 进阶用法：参数描述 + 调用示例

给有参数的工具，用parameters字段逐项说明语义，见 pyexec/src/main.cj：

@tool[ description: """...环境每次执行都会重置，必须发送完整脚本...""", parameters: { code: "The python code to execute..." }, examples: [ "codeInterpreter(\"print(1+2)\")" ] ] public func codeInterpreter(code: String): String { ... }

这里有三个细节值得学习：

描述中写明"坑"：告诉模型环境每次重置、代码不要包在 markdown 代码块里，能显著减少无效调用；
参数说明精确到格式：连字符串字面量的引号写法都做了约束；
examples提供调用范例：等价于给模型做 few-shot，降低幻觉参数概率。

fetcher工具则展示了"参数即检索意图"的设计——target参数描述用户期望从网页获取什么内容，工具内部直接用它做语义检索，见 fetcher/src/main.cj。

3. 工具族模式：安全边界 + 复合能力

filesystem模块（filesystem/src/main.cj）是一个完整的"工具族"设计范本：

安全沙箱：所有工具入口先走checkPath校验，只允许访问启动时声明的--allowed-dir，路径越界直接返回错误信息；
能力分层：listDir、readFile、searchFile三个原子工具 + 一个"高阶工具"summarizeFile；
工具内嵌子智能体：summarizeFile内部用一个@agent声明的SummaryAgent生成摘要——工具不只是执行，还可以是一个"小型智能体"。

💡 设计启示：一个高质量工具 = 清晰的 description + 明确的参数约束 + 可靠的错误返回。错误信息会直接喂给模型，让它有机会自我纠正。

🤖 智能体任务规划：让 Agent 自己"想步骤"

工具解决"能做什么"，任务规划解决"怎么做"。仓库中pyexec和MagicAgent展示了两种典型规划模式。

1. 代码自修复：把"试错-修复"规划进工具内部

codeInterpreter工具在内部实现了一个最多 3 轮的规划循环：执行 Python → 失败则把错误信息交给"程序修复模型" → 重试。修复模型的系统提示词里还内置了THOUGHT PROTOCOL（先理解、再分析根因、最后探索修复方案），见 pyexec/src/main.cj。

这种"工具内部自带 ReAct 循环"的模式，让上层 Agent 无需关心修复细节，一次调用就拿到可用结果。

2. 端侧任务规划：规划工具 + react 执行器

MagicAgent的 entry/src/main/cangjie/src/pages/llm.cj 是整仓最精彩的部分：

核心技巧：把"流程"本身做成一个工具。ticketPlan工具不执行任何操作，只是返回一份购票步骤清单（定位出发地 → 推断目的地 → 确认日期 → 查票 → 确认车次 → 确认座位 → 天气提醒）：

@tool[description: "购买车票流程规划（预订/购买车票相关的，优先调用该工具）"] public func ticketPlan(): String { return """具体分为以下步骤..."""; }

@prompt中再约定"涉及购票时先调用ticketPlan进行规划"，模型就会先"取计划、再按步骤执行"。这就是规划与执行分离：

@agent[model: "${MODEL}", executor: "react", mcp: [ http("https://mcp.amap.com/sse?key=${AMAP_MCP_KEY}"), tools(ticketPlan, starbucksBooking, getCurLocation, queryContacts, ...) ] ] class Superman { @prompt("""...""") ... }

react执行器：让 Agent 自主"思考 → 调用工具 → 观察结果 → 再思考"；
mcp混合接入：既挂远程地图 MCP 服务（路线规划、天气），又挂本地@tool函数（通讯录、日历、定位）；
askUser也是工具：向用户提问被建模为一次工具调用，配合BlockingQueue同步等待用户输入，实现多轮交互式规划。

📚 RAG 代码助手：声明式绑定知识库

CangjieRAGCodeAssistant/src/main.cj 展示了另一类"能力挂载"：@agent注解里直接声明rag检索源，Agent 每次对话前自动检索仓颉官方文档语料：

@agent[model: "${MODEL}", executor: "naive", rag: {source: retriver()}] class Superman { @prompt("""...""") }

配套的@prompt用完整示例教模型"只引用有用的文档、回答末尾列出参考文档"。构建向量库只需cjpm run --name cjca --run-args "--build"，详见 CangjieRAGCodeAssistant/README.md。

🚀 快速上手：3 步跑通你的第一个 @tool 服务

装环境：安装仓颉 SDK 1.0.5 与 stdx，配置CANGJIE_STDX_PATH（见 CangjieMagicMCPServer/README.md）；
选最简示例：克隆仓库后先跑无外部依赖的time工具：
```
cjpm build cjpm run --name time
```
改造为你自己的工具：参考filesystem的模式，写函数 → 加@tool注解（描述+参数）→StdioMCPServer.startWith([...])暴露出去，即可接入任意支持 MCP 的 Agent。