Prompt 工程、Tool Calling 与 Agent 记忆机制 (Memory Workflow)

回到总览：AI 时代的工程师能力
相关模块：AI 辅助开发与 Agentic Workflow 全景总览 · Agent Tool Calling (Function Calling) 架构与安全防护

一句话定义

Prompt 工程、Tool Calling 与 Memory Workflow 构成了现代 AI Agent 的三大基础设施：通过结构化 Prompt（提示词） 明确指令与边界，通过 Tool Calling（工具调用） 读写系统资源与运行命令，通过 Memory（上下文记忆与 Knowledge Items） 跨 Session 延续决策上下文与项目经验。

代码索引

计划补齐的实验：

• labs/shared/ai-engineering/prompt-memory-demo/ — System Prompt 注入、Tool Calling 协议解析与 Memory 读写测试

为什么需要

• 为什么直接向 AI 提出模糊口语指令（如“帮我优化这个代码”）效果很差，而提供结构化 Role + Context + Rules 效果非常好？
  • 一句话答：LLM 是基于概率预测下一个 Token 的模型；清晰的结构化提示词（Role 角色、Context 背景、Constraints 约束、Output Standard 格式）收窄了模型的解空间，显著降低了回答的不确定性与幻觉。
• 为什么 10 年资深工程师必须理解 Agent 的 Memory（上下文记忆）机制？
  • 一句话答：LLM 的 Context Window（上下文窗口）是有限且昂贵的；通过将项目规范提取为持久化的 KI (Knowledge Items) 或 task_logs 记忆文件，Agent 才能在开启全新对话时瞬间恢复上下文，避免重复调研。

底层机制

1. 结构化 Prompt 黄金四要素 (SYSTEM / USER / RULES)

[Identity & Role] ───► "你是一名资深 Android / Flutter 架构师..."
[Context]        ───► "本仓库是 Engineering Review Lab，读者画像为 10 年 Android 背景..."
[Constraints]    ───► "规则：所有问题必须带一句话答，禁止只提问不回答..."
[Task & Input]   ───► "请分析并发 HashMap 的底层扩容..."

2. Tool Calling 交互闭环 (JSON-Schema Protocol)

1. User: "帮我检查 docs 目录下文件的行数"
2. LLM:  输出 Tool Call 请求 ──► { "name": "run_command", "args": { "CommandLine": "wc -l docs/*.md" } }
3. IDE:  执行 Shell 命令 ─────► 返回 Output: " 42 docs/01.md \n 100 docs/02.md"
4. LLM:  解析 Output 内容 ────► 总结并回答用户

3. 三级 Memory 存储体系

1. Short-term Memory (短期记忆)：当前 Conversation 窗口内的 JSON Lines Transcript（如 transcript.jsonl）。
2. Medium-term Task Logs (任务进度日志)：跨 Session 恢复进度的本地日志（如 ~/.gemini/task_logs/）。
3. Long-term Knowledge Items (长效知识项/KI)：项目固化的架构决策与 Gotchas 知识库（如 <appDataDir>/knowledge/）。

Android / Flutter / Web / Backend 对照

记忆与配置维度	Antigravity / Agent	Standard LLM Chat
全局规则	~/.gemini/config/AGENTS.md	无 (每次需重新 Paste)
项目规则	.agents/AGENTS.md	无
Skill 工具包	.agents/skills/<name>/SKILL.md	Custom GPTs / System Prompt

常见场景

1. 编写清晰的 SKILL.md 前置声明

---
name: engineering-review-lab-authoring
description: 项目级写作规范，当需要撰写 docs 或创建 labs 时触发
---
# 写作规范
1. 问题必答：每个问题下方紧跟 **一句话答**。
2. 双向跳转：维护文首索引、章节 Lab 与文末实验三处相对链接。

常见误配、事故后果与排障

1. 事故：Context Window 溢出导致 Agent 遗忘最初的约束规则

• 误配原因：在单个 Long Session 中持续对话几十轮，输入了海量的终端长日志，触发了上下文截断（Truncation）。
• 后果：Agent 丢失了最开头的 System Prompt 或 AGENTS.md 约束，开始出现“只提问不回答”或误改无关文件的行为。
• 排障与修法：定期让 Agent 总结进度写入 task_logs 或 Artifact，开启新对话通过“读取上次进度”恢复干净窗口。

对应实验

计划补齐的实验：

• labs/shared/ai-engineering/prompt-tool-memory-demo/ — Prompt 结构、Tool 调用失败反馈与 Memory 窗口管理测试

复习检查题

1. 在 Agent 的 Tool Calling 流程中，为什么 Tool 执行失败时的错误日志（Error Log）必须原封不动地返回给 LLM？

   答：因为 LLM 具备根据错误日志自我推理和 Debug 的能力。当命令执行失败或抛出异常时，未截断的完整 Stack Trace 是 LLM 诊断根因的最高事实依据；LLM 会分析错误原因，自动修正工具参数并发起第二次重试，从而实现自主纠错。

2. 为什么在 Prompt 中使用 GitHub 风格的 Alert (如 > [!IMPORTANT]) 和显式的约束能够降低 LLM 的幻觉？

   答：LLM 在生成文本时会给上下文中的 Token 分配注意力权重（Attention Weights）。明确的提示词结构和强调符号能够显著提高模型对关键约束规则的 Attention 权重，强制模型在采样概率时优先满足约束条件，从而收窄回答的随机性并减少幻觉。

速记

• Prompt 四要素：Role 角色、Context 背景、Constraints 约束、Input 任务。
• Tool 闭环：LLM 发起 JSON 请求 → IDE 跑命令 → 结果喂给 LLM 总结。
• Memory 三级：Transcript 短期，Task Log 中期，KI/AGENTS.md 长期固化。