GitHub 热门项目 cindy 拆解:把「开箱即用 AI Agent」写成一份可复用的工程手册
我是AI时代的无业游民,我游荡在现实与意念之间
GitHub 热门项目 cindy 拆解:把「开箱即用 AI Agent」写成一份可复用的工程手册
什么时候用这份手册
你在课程作业或作品集里想加一个「AI 能自己动手干活」的模块,但一搜 Agent 框架就被 LangGraph、AutoGen、MCP、工具调用协议、沙箱、记忆存储这些词劝退;或者你已经抄了一份 demo,跑起来却只会聊天、不会做事,一接真实任务就报错。这份手册按「使用频率」组织:先看症状对号入座,再看诊断定位根因,然后照抄重构后的最小模板,最后用检查清单自查。目标读者是学过语法、但还没在真实协作约束下写过工程代码的在校学生与转行者。
前置知识只有三条:会写 Python 函数、知道什么是 HTTP 请求、能读懂 JSON。读完你能拿出的作品集能力是:独立实现一个「任务输入 → 规划 → 调用工具 → 校验结果」的最小 Agent 闭环,并能说清每一步为什么这么设计。行业里这项技能的真实用法,不是让你从零造框架,而是让你能读懂一个开源 Agent 项目的目录结构、判断它是否可信、并把它裁剪进自己的项目。

① 重构前的症状:一个「会聊天但不会干活」的 Agent
最常见的初学者写法,是把所有逻辑塞进一个函数,用字符串拼接 prompt,让模型「顺便」输出要执行的命令:
# before.py —— 能跑,但一接真实任务就崩
import json, subprocess
from openai import OpenAI
client = OpenAI()
def run_agent(user_input: str) -> str:
prompt = f"""
你是助手。用户说:{user_input}
如果需要执行命令,请直接输出 shell 命令,我会执行。
"""
resp = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": prompt}],
)
text = resp.choices[0].message.content
# 直接把模型输出当命令执行
result = subprocess.run(text, shell=True, capture_output=True, text=True)
return result.stdout
三个可复现的痛点:
- 模型返回一句「好的,我来帮你查一下」而不是命令,
subprocess直接抛FileNotFoundError; - 模型返回带解释的多行文本,
shell=True把整段当命令,行为不可预测; - 没有循环:一次调用结束就返回,模型说「我需要先看目录」,程序也不会真的去看。
面试/作业常被追问的点:这段代码里 shell=True 加模型自由文本,等价于把任意代码执行权交给一个概率模型,这是安全评审一票否决的写法。
② 问题诊断:根因是「没有协议」和「没有循环」
表面看是解析失败,根因有三层:
- 输出格式无约束。自然语言和可执行指令混在一个通道里,解析必然脆弱。解法是让模型输出结构化 JSON,并用 schema 校验。
- 没有工具抽象。命令是裸字符串,没有名称、参数、返回值约定。解法是定义工具注册表,模型只能「点名」已注册的工具。
- 没有 Agent 循环。Agent 的本质是「观察 → 决策 → 行动 → 再观察」的循环,单次调用只是其中一步。解法是加
while循环和最大步数上限。
这也解释了为什么「开箱即用」的 Agent 项目值得看:它们把上述三层封装成了默认约定,你打开目录就能看到 tools/、agent loop、sandbox 的分层,而不是一坨 prompt。
③ 重构后的写法:协议 + 注册表 + 循环
# after.py —— 最小可复用闭环
import json
from openai import OpenAI
client = OpenAI()
MAX_STEPS = 8
# 1) 工具注册表:名称 -> (函数, 参数 schema)
TOOLS = {
"list_dir": {
"fn": lambda path=".": "\n".join(__import__("os").listdir(path)),
"schema": {"type": "object", "properties": {"path": {"type": "string"}}},
},
"read_file": {
"fn": lambda path: open(path, encoding="utf-8").read()[:2000],
"schema": {"type": "object", "properties": {"path": {"type": "string"}},
"required": ["path"]},
},
}
SYSTEM = """你是一个执行型 Agent。每轮只输出一个 JSON 对象,二选一:
{"action":"tool","name":"工具名","args":{...}}
{"action":"final","answer":"给用户的最终答复"}
不要输出 JSON 以外的任何文字。"""
def run_agent(user_input: str) -> str:
messages = [{"role": "system", "content": SYSTEM},
{"role": "user", "content": user_input}]
for _ in range(MAX_STEPS):
resp = client.chat.completions.create(
model="gpt-5.5", messages=messages,
response_format={"type": "json_object"}, # 关键改动 1
)
raw = resp.choices[0].message.content
try:
step = json.loads(raw)
except json.JSONDecodeError:
messages.append({"role": "user", "content": "输出不是合法 JSON,请重试。"})
continue
if step["action"] == "final":
return step["answer"]
name, args = step["name"], step.get("args", {})
tool = TOOLS.get(name) # 关键改动 2:白名单
if tool is None:
obs = f"未知工具 {name},可用:{list(TOOLS)}"
else:
try:
obs = tool["fn"](**args)
except Exception as e:
obs = f"工具执行失败:{e}"
messages.append({"role": "user", "content": f"观察结果:{obs}"}) # 关键改动 3
return "达到最大步数,任务未完成。"
三处关键改动对照:
| 改动 | before | after | 作用 |
|---|---|---|---|
| 输出协议 | 自由文本 | response_format=json_object + 固定二选一结构 | 解析不再靠猜 |
| 工具边界 | 任意 shell 字符串 | TOOLS 白名单 + 参数 schema | 模型只能调用你允许的能力 |
| 控制流 | 单次调用 | for 循环 + MAX_STEPS | 支持多步任务且不会死循环 |
注意点:read_file 这类工具务必加路径校验(如限制在项目目录内),示例为保持短小省略了;真实项目中把工具执行放进容器或子进程,而不是主进程。
④ 收益与代价
- 可读性:逻辑从「一个巨型 prompt」变成「注册表 + 循环 + 协议」三块,新增工具只需往
TOOLS加一项,不改主流程。 - 健壮性:非法 JSON、未知工具、工具异常三类失败都有兜底分支,不再整段崩溃;
MAX_STEPS把最坏情况从「无限调用」压到 8 次。 - 性能与成本:多步任务必然多轮调用,token 消耗随步数线性增长;
MAX_STEPS=8是成本与能力的折中,可按任务复杂度下调到 4。 - 复杂度:代码从约 15 行涨到约 50 行,但换来的是可测试性——每个工具函数可以单独单测,循环逻辑可以 mock 模型响应来测。
⑤ 适用边界与检查清单
不该这么改的时候:任务只需单轮问答(如文本润色、翻译),加循环纯属浪费;工具涉及不可逆操作(删除、支付)时,仅靠白名单不够,必须加人工确认环节;对延迟极敏感的场景,多轮调用不划算。
提交作品集前的检查清单:
- 模型输出是否被 schema 或
json_object约束,解析失败有重试分支? - 工具是否全部走注册表白名单,没有裸
shell=True拼接模型文本? - 是否有
MAX_STEPS上限和超限后的明确返回? - 工具异常是否被捕获并作为「观察结果」回灌给模型,而不是直接抛出?
- 文件类工具是否做了路径范围限制?
- 能否用 mock 的模型响应写一条不依赖网络的单测?
把这份手册当成模板:先跑通 after.py,再照着开源 Agent 项目的目录结构,把 tools/、agent loop、sandbox 拆成独立文件——这一步做完,你就有了一个能讲清设计取舍、也能经得起追问的最小 Agent 项目。
更多推荐

所有评论(0)