Midnight's blog

Agent基础概念扫盲

Wed, 15 Jul 2026 00:00:00 GMT

一、Hello Agent

先认识一下 Agent：它不是「更会聊天的模型」，而是能带着目标连续干活的程序。

核心就一件事——循环：

想下一步 → 调用工具 → 观察结果 → 再想 → 再调用…直到完成或停下。

和普通对话模型的区别很直接：后者问一句答一句就结束，Agent 会围着目标转好几圈，中间可能读文件、跑命令、查信息，再根据结果调整。这个圈一般叫 Agent Loop。

while not done:
    think()   # 推理
    act()     # 调 Tool
    observe() # 看结果

所以学 Agent，不必一上来堆概念：先记住它是个循环；Tool、Hooks、ToDo、Subagent、Skills等都是后来挂在这个循环上的能力与约束。

二、工具

2.1 Tool

"LLM 决策，Tool 落地"

从聊天对框到终端干活，第一个重要一步就是Tool，读文件、改代码、跑命令从此开始有了动手能力。模型通过 Tool Calling / Function Calling 选出工具并传入参数，由运行时真正执行，再把结果回传给模型，形成 [ 推理 → 调用 → 观察 → 再推理 ] 的循环。

tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",                    # 工具名
            "description": "读取指定路径的文件内容",  # 给模型看的说明
            "parameters": {                            # 参数 schema（结构化约束）
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "文件路径"}
                },
                "required": ["path"]
            }
        }
    }
]

2.2 Hooks

“管理边界能力”

有了 Tool，Agent 能读改文件、执行命令，能力明显变强；随之而来的是风险：路径搞错、误执行破坏性操作、越权访问敏感资源。

很多人会想：用提示词写清不许删文件、不许乱改行不行？提示词只能做 软约束——模型仍是概率生成，同一句话不能保证每次都遵守。

要把尽量别乱来变成违规就拦住，需要挂在工具调用前后的硬约束机制，这就是 Hooks（钩子）：在执行前审计/拦截，在执行后记录或补救，把不确定的生成行为收进可强制执行的边界里。

# hooks.json
# {
#   "version": 1,
#   "hooks": {
#     "beforeShellExecution": [
#       { "command": "python3 .cursor/hooks/guard_rm.py" }
#     ]
#   }
# }
data = json.load(sys.stdin)
cmd = data.get("command", "")
# 硬约束：命中危险模式就拒绝
if "rm " in cmd:
    # permission=deny：这次命令不会真正执行
    print(json.dumps({
        "permission": "deny",
        "user_message": "禁止删除命令"
    }))
else:
    # permission=allow：放行
    print(json.dumps({"permission": "allow"}))

三、规划与协作

3.1 ToDo

"按清单推进，而不是想到哪做到哪"

举个例子：你说"帮我推荐一件衣服"。

没有 ToDo 时，Agent 多半只能靠已有知识顺着你说——听起来很会聊，其实像在哄人，缺少推销员那种主动采集信息、对比筛选的过程，推荐也容易飘、容易空。

有了 ToDo，它会先把路径摊开：了解喜好 → 结合季节 → 确认体态/尺码 → 检索候选 → 清洗筛选 → 给出推荐；若你觉得步骤不对，还可以改清单。每一步可追踪，结果才更靠谱。

人和 Agent 不一样：人可以边想边做；Agent 没有真正的自主意识，长链路里更容易跑偏。所以在 Agent 开发里，规划不是加分项，而是把能力收成可控流程的关键一步——ToDo 做的，就是把模糊目标拆成可执行、可修正的清单。

3.2 Subagent

"主 Agent 编排，Subagent 干活"

还是买衣服：你要的不只是推荐一件，还要比价、看评价、盯库存。

没Subagent ，全压在一个 Agent 身上——边聊边搜边比，上下文越堆越乱，最后可能记混了，推荐也糊。

有Subagent，主Agent 像店长：一个小弟专搜款式，一个专比价格，一个专看评价；各自干完交结果，店长再汇总给你。人可以一个人干到底；Agent 不行，单会话塞太多容易懵。所以复杂任务要拆出去、并行干、再汇总——这就是 Subagent。

# 主 Agent 派活，Subagent 专项执行后交回结果
task = "推荐一件春季外套"
# 并行委派（示意）
results = {
    "style":  subagent_explore("搜春季外套款式"),   # 翻资料
    "price":  subagent_shell("比价脚本"),            # 跑工具
    "review": subagent_general("总结口碑"),          # 综合分析
}
# 主 Agent 只负责编排 + 最终答复
answer = synthesize(task, results)

3.3 Skills

"把会做，变成按标准做"

还是买衣服：老销售心里有套固定流程——先问预算、再看场合、再给三档选择。新人全靠临场发挥，今天一套说辞明天一套。

没有 Skills 时，Agent 每次都靠临场发挥，同一类活质量忽高忽低。

有了 Skills，等于给它一本标准作业书：什么场景触发、先问什么、输出长什么样。人可以凭经验自由发挥；Agent 没有真正经验，要把经验写成可复用规范，它才能稳定复现——这就是 Skills。

# Skill = 可复用的标准（触发条件 + 步骤 + 输出要求）
skill = {
    "name": "recommend-clothes",
    "when": "用户要推荐衣服",           # 何时启用
    "steps": [
        "确认预算与场合",
        "结合季节缩小范围",
        "给出高中低三档推荐并说明理由",
    ],
    "output": "列表 + 理由，不要空洞夸奖",
}
# 命中场景就按手册走，而不是纯靠临场发挥
if match(user_query, skill["when"]):
    follow(skill["steps"], skill["output"])

3.4 System prompt

"按需组装"

很多人以为 System Prompt 就是开头硬编码一大段你是谁、你要怎样。能跑，但不灵活：任务变了、Skill 变了、记忆变了，整段都得改。

更常见的做法是组装（Assembly）：运行前把几块拼起来，再塞进系统位。

角色与边界（你是谁、不能干什么）
当前任务说明
Skills / 规范片段（命中才挂上）
记忆摘要 / 索引（见下文）
输出格式要求

# System Prompt = 拼装，不是写死
system_prompt = "\n\n".join([
    role_rules,           # 角色与边界
    task_brief,           # 本次任务
    skill_snippets,       # 命中的 Skill
    memory_index,         # 相关记忆索引
    output_format,        # 输出要求
])

四、记忆

4.1 context

"窗口信息"

Context 就是塞进模型里的东西(可重复的)：系统提示、对话内容(有用的)、Tool结果…Agent多跑几轮，文件内容、命令输出全堆在message里，窗口一满，服务就停止了。

所以要压缩（Compaction）：裁减无关旧对话、把Tool结果总结、输出落库成文只能预览，还不够再让Agent做一轮摘要。原则很简单——便宜的先做(不设计Agent的能用代码搞定的)，贵的后做。

代价也清楚：压缩是为了继续跑，细节会丢。用户偏好、关键约束一旦挤掉，下一圈可能就忘了——这就连到 Memory。

# 每轮调用前：先腾地方，再问模型
context = cheap_compact(context)   # 裁剪 / 占位 / 文件落库
if too_long(context):
    context = summarize(context)   # 贵：LLM

4.2 memory

"压缩会丢细节，重要的是持久化"

简单落地：

用 Markdown 文件持久化，按固定格式写（类型、内容、时间、适用范围）
维护一份索引 md，只记有哪些记忆、大概讲什么
组装 System Prompt 时注入索引（或相关条目），而不是整库硬塞进 Context
分类：这类记忆该给谁——主 Agent、某个 Skill、某类任务、还是仅本会话

type: user_pref
scope: 主 Agent
content: 回答要简洁，少空话
updated: 2026-07-18
# 索引进提示词全部内容按需读
system_prompt = assemble(
    role_rules,
    memory_index,   # md 索引，渐进式披露
)
# 分类路由：该给谁，才给谁
route = {
    "user_pref": "主 Agent",
    "project_fact": "主 Agent + 相关 Skill",
    "tool_lesson": "同类任务再注入",
    "temp_note": "本会话用完可丢",
}

登陆凭证详解

Sat, 11 Jul 2026 00:00:00 GMT

一、什么是登陆凭证

**登录凭证（Login Credentials）**是向系统证明「我是我」的一组信息。系统不会凭空相信你，必须先核对凭证，才让你进入账户、访问数据、调用接口、分配相应权限。

凭证一定要做好保护，无论是用户还是开发者。

当用户凭证被攻击者拿走，就相当于账号被盗了。举个例子，Cursor 的用户凭证是存到 Cookie 中的信息，头是 WorkosCursorSessionToken；当你把这个凭证放到互联网上（之前薅羊毛），群众中的坏人拿着你的 Token 就把你账号注销了。

对于开发者来说更要把用户凭证做好保护，防止用户信息、财产损失。需要做好加密以及更新。

二、解决办法

一般方案（Cookie、Session）

用户完成登陆 → 服务器保存用户信息（Session） → 并将 Session 信息返回给前端 → 前端将其保存至浏览器 Cookie 中 → 每次请求将 Cookie 信息携带至请求体发送给后端 → 后端每次进行验证。

致命缺点： 在多个服务器的情况下，Session 只保留在登陆的那台机器上面，后续请求打到别的机器上就判定为未登录。

Redis 保存 Session

将 Session 保存至 Redis 中，无论多少服务器都能在 Redis 中找到 Session 进行校验。

需不需要设置过期时间？

这是肯定的。如果没有过期时间，用户岂不是一直处于登陆状态？这样可太坏了。

那过期时间设置多少呢？

用户不可能到一定时间就要重新登陆，所以这个过期实际是一个假过期：当用户正常使用时，服务端需要刷新用户的 Token，确保用户这段时间是在用的。等用户一段时间不用了，Redis 过期时间会自动把用户踢出登陆。

致命缺点：

服务端每次验证都要去查 Redis，对双方的压力都是不小的。

JWT

如果要减少 Redis 的压力，那么校验这一块就不能去 Redis 中。

服务端通过 JWT，将用户信息保存到 Token 中返回给前端，后续每个请求只需要本地校验即可。

优势：

减少服务端的压力、不需要查 Redis、扩展简单、适合分布式。

缺点：

JWT 是无状态的。攻击者只要拿到了用户的 JWT 凭证，只要没有过期就存在危险。不能踢出用户、限制用户。

双 Token（AccessToken、RefreshToken）

服务端维护两套 Token。

AccessToken 用于校验用户信息，过期后自动换新；如果丢失，只存在短时间危险。服务端如果要踢用户下线，只需要将保存的 RefreshToken 删除即可。

| | AccessToken | RefreshToken | | --- | --- | --- | | 用途 | 日常访问 API | 只用来换新的 AccessToken | | 有效期 | 短（1 ~ 2h） | 长（7天 ~ 30天） | | 携带频率 | 每次请求都带 | 几乎不带，只在刷新时用 | | 泄露风险 | 高（频繁传输） | 低（很少出现） |

无感续签

总结

没有最好的方案，只有最适合的办法，结合场景和现在实际情况考虑。

三、后续升级

会话安全： Token Family、Refresh Token 重用检测、单设备/全设备下线、Session 版本校验，使被撤销的 Access Token 可立即失效。

安全防护与审计： 补齐 CSRF、CORS、刷新接口限流、异常刷新检测，并记录登录、刷新、撤销日志。

平台化演进： 网关统一鉴权，Redis 管在线会话、数据库留审计历史；权限中心处理权限变更与缓存失效；高风险操作接入 MFA/风控，后续升级到 OAuth 2.1、OIDC、SSO。