diff --git a/InBox/AGENTS.md_待看.md b/InBox/AGENTS.md_待看.md new file mode 100644 index 0000000..1b87919 --- /dev/null +++ b/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/ diff --git a/InBox/Agent上下文管理策略_待看.md b/InBox/Agent上下文管理策略_待看.md new file mode 100644 index 0000000..80dbbc2 --- /dev/null +++ b/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/