收录两篇Agent相关文章到待看笔记

InBox/AGENTS.md_待看.md

@@ -0,0 +1,81 @@
+# 在实际工作流中验证了四个月并可跨 project 复用的 AGENTS.md
+
+**来源**: [知乎](https://zhuanlan.zhihu.com/p/2009629370684306095)  
+**收录时间**: 2026-04-09  
+**标签**: #Agent #代码规范 #项目管理
+
+---
+
+## 文档写作原则：Self-Contained（自解释）
+
+所有文档（PROGRESS.md、STATES.md、EXPERIMENTS.md、TODO.md）必须做到**只读文档就能完全理解**，不依赖对话上下文或任何脑内默认知识。
+
+### 核心要求
+
+1. **每个方法首次出现时必须解释它是什么、怎么做的**。不能只写"方法 A 效果好"，必须写"方法 A（用因果卷积在 MLP 打分前丰富 token 特征，让 gate 感知邻居信息）效果好"
+
+2. **不要假设读者知道任何缩写**。首次使用缩写时必须给出全称和一句话解释。例如不要写"STE"，要写"STE（Straight-Through Estimator，前向用 hard 0/1 掩码，反向用 sigmoid 梯度近似）"
+
+3. **实验结论必须包含足够上下文**。不要写"差距缩小到 0.001"，要写"TopK 自适应选择与 Fixed 周期掩码的质量差距从 0.005 缩小到 0.001（提高 gate 学习率从 0.001 到 0.1）"
+
+4. **数字必须有参照物**。不要写"val_bpb=0.8605"，要写"val_bpb=0.8605（对比：无加速 baseline=0.840，Fixed 周期掩码=0.8605）"
+
+5. **因果链要完整**。不要只记录结论，要记录**为什么**。"TopK 不如 Fixed"不够，要写"TopK 不如 Fixed，因为 TopK 的 think token 48% 紧挨着聚集（间距=1），导致部分 skip token 的信息供给不足（信息瓶颈），而 Fixed 均匀间隔保证每个 think token 只需支撑 2 个 skip token"
+
+6. **docs/STATES.md 顶部维护一个术语表**，所有关键术语集中定义。其他文档开头引用该术语表即可
+
+### 反面例子（禁止）
+- "V11 实验效果不错" → 什么是 V11？做了什么？效果不错是多少？
+- "提高了 gate LR" → 从多少到多少？为什么要提高？效果改善了多少？
+- "信息瓶颈是核心问题" → 什么信息？什么瓶颈？为什么是核心？
+
+### 正面例子（要求）
+- "TopKConvGate 实验（在 MLP 打分前用 768 通道因果深度卷积让每个 token 看到前 7 个邻居的特征，帮助 gate 感知局部上下文以减少 think token 聚集）：E4T4D4 架构下 5k 步 val_bpb=0.8610，仍略差于 Fixed 周期掩码(0.8605)，差距 0.0005"
+
+---
+
+## 项目管理工作流
+
+### 文档维护规范
+
+**docs/PROGRESS.md**: 只记录"已经完成"的工作/实验/结论（附关键脚本/日志/ckpt 路径），不要写待办计划。
+
+**docs/TODO.md**: 只记录"未完成/进行中/下一步"的待办与计划（尽量可一键复现）；完成后从 docs/TODO.md 移除对应项，并把结果写入 docs/PROGRESS.md（避免重复记录）。
+
+**docs/STATES.md**: 只维护已经完成的成果，录入真正长期有用的东西而非临时的噪音。
+
+**docs/EXPERIMENTS.md**: 实验相关内容的特殊STATE，专注于处理实验和数据。
+
+### 关键原则
+
+- 能用小数据集/短实验快速 debug 就不要用大数据集/长实验；优先最快迭代
+- 每次准备做实验前必须先高层质疑与方向审视确认当前未知/最小实验/失败后下一步
+- 两个文档都必须按时间升序记录（越早在前、越晚在后），新增内容只能追加到文件末尾
+- 训练评测时只要是正式实验，一定要在正规文件里弄好脚本然后一键几乎无传参地跑
+- 跑训练或评测必须在 tmux 里启动，避免中途断开导致任务退出
+- 时刻注意删掉没用的 checkpoint 等大文件，维护空间不爆炸
+- 有多个相同功能文件的时候，请把错误的冗余的全部都扔进 archive，只保留一个
+
+### Git 提交规范
+
+当完成一个完整功能或要进行破坏性改动时：
+```bash
+git add .
+git commit -m "描述"
+```
+
+- 发现任何文档或代码有错误时，更新不要保留任何错误痕迹
+- 写了一个新版本的正确文件，请删掉错误版本的文件
+- 兼容性不要搞得那么好，不要 fallback
+- 同样的功能禁止有错误实现，并且只能有一个位置正确实现，禁止冗余
+
+---
+
+## 其他要点
+
+- 跟我沟通请使用中文。任何的临时测试都请在 tmp 文件夹
+- 我们现在是在一个Docker环境里边，使用公共服务器的电脑。千万不要跟别的程序抢占GPU，这是绝对禁令
+- 想用 GPU 的时候用 nvidia-smi 查看空闲 GPU 然后精确加载空闲的
+- 你只要遇到问题就处理，遇到问题就处理，直到没有问题。不要问我顺序什么的
+- 有不清楚的先记下来跳过，所有探究实现路径全部卡住了再都通知我
+- 没用的东西放 archive/

InBox/Agent上下文管理策略_待看.md

@@ -0,0 +1,115 @@
+# 万字长文解析Agent框架中的上下文管理策略
+
+**来源**: [知乎](https://zhuanlan.zhihu.com/p/2012088406826562496)  
+**收录时间**: 2026-04-09  
+**标签**: #Agent #上下文管理 #LLM #ClaudeCode
+
+---
+
+## 0x00. 写在前面
+
+今年春节前后，至少9家国内的厂商密集地发布了他们旗舰版本的模型（比如GLM5、MiniMaxM2.5、Qwen3.5），可以发现大模型领域的竞争焦点从通用能力转向了Agent落地、编程能力这两大方向。
+
+随着Claude Code、OpenClaw等Agent Scaffold的爆火，各大厂商也纷纷将自己的定位锁定在Agentic Engineering上，从"chatbots that respond" 转向 "agents that act"。
+
+---
+
+## 0x01. 背景
+
+### （1）什么叫上下文工程（Context Engineering）？
+
+"上下文工程"简单来说，就是在一些LLM的约束下（如上下文窗口大小、注意力长度的限制），优化上下文token的效用，从而持续获得理想输出的工程实践。
+
+一个好的context engineering追求用最少的、信号最强的token集合，最大化期望输出的概率。
+
+如果说之前早期的"Prompt Engineering"适用于单轮文本生成任务；那么"Context Engineering"就适用于需要多轮推理、长时间运行的智能体，需管理不断演变的上下文状态。
+
+### （2）为什么Context Engineering对构建一个强大智能体来说至关重要？
+
+Agent 每调用一次工具，就会返回一个工具的Observation，这个结果会被追加到聊天记录中。生产环境中的 Agent 可能会进行长达数百轮的对话，因此随着时间的推移，历史记录message会越来越长。
+
+**上下文腐败（context rot）**：虽然现在的LLM能够接受越来越长的序列了，但它们和人类一样，会随着上下文增长而出现注意力涣散的现象，模型准确回忆信息的能力会下降，而且推理也会变慢。
+
+导致这种现象的原因包括：
+- **注意力分散**：每个token都关注上下文中的所有其他token，形成了 n^2 级别的两两关系
+- **训练数据偏差**：模型在训练时接触的长序列远少于短序列
+- **位置编码插值**：可以让模型适应更长的序列，但通常会牺牲一定的精度
+
+---
+
+## 0x02. 上下文工程
+
+### （1）上下文卸载与检索（Context Offload & Retrieval）
+
+#### (a) 将上下文卸载到文件系统（紧凑化, Compaction）
+
+Manus提出了一个核心理念：**将文件系统视为终极上下文**。这是因为文件系统天然具有无限容量、持久化、可随机访问的特性。
+
+这种"可逆压缩"确保上下文长度缩减的同时，信息并未真正丢失——它们只是被卸载到文件系统中了，随时可以重新加载进来。
+
+#### (b) 检索：推理前检索 vs "Just-in-time"检索
+
+**RAG（Retrieval-Augmented Generation）**：预先对知识库的文本进行向量化，然后在推理前预先检索相关片段。
+
+**Just-in-time检索**：让 LLM 自己生成搜索命令，像人类一样主动探索大文件或者代码库。
+
+Claude Code 在处理大型的数据时，会生成一些复杂的 Bash 命令进行查询（如ripgrep、jq、find等），利用自己对代码的深刻理解，使用精细而复杂的正则表达式定位相关代码块。
+
+### （2）上下文摘要(Context Summarization)
+
+当上下文窗口即将被填满，且没有办法进一步做紧凑化的时候，我们不得不采用另一种手段：摘要化。这是一种有损压缩，它会将对话历史浓缩成一段摘要，从而释放空间。
+
+**Claude Code的压缩流程**：
+- 自动触发：监控当前上下文的 token 使用量，接近上限时自动触发
+- 手动触发：用户可通过/compact命令主动执行压缩
+
+摘要包含：主要请求和意图、关键技术概念、文件和代码段、错误和修复、问题解决、用户所有消息、待办任务、当前工作、可选下一步
+
+### （3）上下文隔离（多智能体架构）
+
+面对一个复杂的任务，我们可以将任务分解，然后由主智能体协调多个专门化的子智能体（sub-agents）来处理具体任务。
+
+**多智能体架构的好处**：
+- **节省主Agent的上下文**：subagent的上下文和主agent是隔离的
+- **权限控制**：限制 subagent 可用的工具
+- **特定领域专业化**：为特定领域编写专门的系统提示
+- **节约调用成本**：可以把某些简单的任务路由到更快、更便宜的模型
+
+**Claude Code的subagent分类**：
+- **Explore**：只读 agent，专门用于搜索和分析代码库（使用 Haiku）
+- **Plan**：负责理解代码库并进行规划（使用 Sonnet/Opus）
+- **General-Purpose**：全能型 agent（使用 Sonnet/Opus）
+
+**运行模式**：
+- **前台运行模式**：subagent 运行时阻塞主对话，用户实时决定要不要accept操作
+- **后台运行模式**：subagent 在后台运行，启动前收集权限，运行中自动拒绝未批准的操作
+
+**调用关系**：
+- **并行调用**：多个 subagent 同时独立运行
+- **链式调用**：多个 subagent 顺序执行，后一个依赖于前一个的输出
+
+### （4）上下文缓存
+
+**KV Cache（KV缓存）**：Transformer 模型在生成每个 token 时，需要计算所有之前 token 的Key和Value向量，用于注意力机制的计算，这些 KV 向量就构成了上下文的状态。KV Cache就是将这些中间计算结果保存下来，当后续请求包含相同的前缀时，可以直接复用。
+
+**Prefill（预填充）**：只在生成第一个输出 token 之前，模型对所有输入 token 进行并行处理的阶段。
+
+**为什么缓存对 agent 来说至关重要？**
+- Agent 的工作流程是多轮工具调用的重复
+- 平均Agent的输入输出 token 比高达 100:1
+- 以 Claude Sonnet 为例，缓存的输入 token 价格为 0.30 美元/百万 token，而未缓存的则高达 3 美元/百万 token，相差 10 倍！
+
+**Claude Code的缓存策略**：
+- **核心原则**：上下文只追加，不修改
+- **自动缓存**：在请求顶层添加cache_control字段，系统自动将最后一个可缓存的内容块作为缓存断点
+- **手动缓存**：对稳定性极高的内容（如system prompt、工具定义）使用显式断点
+- 最多4个缓存断点（包括显式和自动缓存）
+
+---
+
+## 参考链接
+
+- https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+- https://minusx.ai/blog/decoding-claude-code/#21-use-claudemd-for-collaborating-on-user-context-and-preferences
+- https://manus.im/en/blog/Context-Engineering-for-AI-Agents-Lessons-from-Buliding-Manus
+- https://platform.claude.com/docs/