企业官网建设流程全解析

1. 为什么我开始关注 context-mode：一次真实的"上下文丢失"事故

去年有段时间，我在维护一个老项目的同时还要赶一个新功能，来回切分支、切模块是家常便饭。有天下午，我花了大半个上午把登录模块的改造思路理清楚了，代码写了一半，正准备收尾，突然被拉去查一个支付模块的线上问题。等我把支付那边处理完，再切回登录模块的时候，看着自己写了一半的代码，足足愣了五分钟：我为什么要把这个校验逻辑挪到这里？那个常量命名成MAX_RETRY到底是想表达什么？

这不是记性问题，而是上下文丢失。更麻烦的是，当时我习惯把项目背景、技术约束、待办事项全记在脑子里，一旦中断，重新恢复这些信息要花的时间远超想象。后来我开始系统性研究各种效率工具和开发模式，才把注意力放到了 context-mode 这个词上，也就是上下文模式。它本质上就是一套显式管理"当前任务需要知道什么"的机制，让工具、AI 助手、甚至未来的自己都能快速恢复上下文。

这篇文章我想把这段时间的实践和思考完整梳理一遍，适合正在用 AI 辅助编程、经常处理多任务并行、或者需要长期维护复杂项目的人参考。不吹不黑，里面有些方法我现在每天都在用，确实把"找回上下文"的时间压缩了一大半。

1.1 那次让我抓狂的调试经历

先说那个下午的具体过程。登录模块的改造涉及三个文件：auth_service.py、token_manager.py和一个改了半天的前端页面。我当时的思路是：把旧的 session 校验统一换成 JWT 方案，token_manager负责签发和刷新，auth_service只做路由层的校验。代码已经写了三分之一，token_manager的接口还没完全定下来。

支付模块那边的问题是签名验签失败，我切过去之后，连查日志带翻文档，折腾了一个小时，等回来打开token_manager.py，看到自己留下的一个 TODO 注释："这里需要处理 refresh token 并发刷新问题"，但完全想不起来当时打算怎么处理。我又把auth_service.py从头看了一遍，才慢慢拼凑出上午的思路。

这种痛苦的本质是：代码只是上下文的"结果"，真正重要的上下文——为什么这样做、有哪些约束、下一步计划——全在脑子里。一旦被中断，代码不会告诉你这些。

1.2 从"人肉记忆"到"显式上下文"

后来我在几个主流 AI 编程工具和终端助手里频繁看到 context-mode 这个选项，一开始没太在意，以为只是"给 AI 多塞点文件"。但用多了以后发现，这个模式的真正价值不是"让 AI 多看几个文件"，而是逼着你把原本散落在脑子里的决策依据、项目约束、任务目标，显式地写出来、存下来、传出去。

这就引出了一个关键转变：用 context-mode，本质是把上下文从"隐式的人肉记忆"变成"显式的可传递信息"。你可以把它理解成整理工作台——常干手工活的人都知道，开工前把工具摆好、把图纸摊开，比边干边翻抽屉高效得多。context-mode 就是给开发工作准备了一个"显式工作台"，让 AI 助手、同事、甚至三天后的自己，都能快速进入同一条思路。

2. context-mode 的核心机制：上下文窗口是怎么被喂饱的

既然要聊透 context-mode，光停留在"是一种工作习惯"这个层面是不够的。我们得先搞清楚底层机制：当你把上下文交给一个工具或者 AI 模型时，它到底在做什么？为什么有时候塞了一堆资料反而效果更差？这背后其实是窗口、Token、注意力三者之间的关系。

2.1 窗口、Token 与"注意力预算"

先简单过一遍基础概念。当前主流大语言模型都基于 Transformer 架构，处理文本时有一个固定大小的"上下文窗口"，窗口里能装多少内容，取决于 Token 数量。Token 可以粗略理解为"词元"，中文里一个汉字大约对应 1 到 2 个 Token，一个英文单词通常对应 1 到 2 个 Token。所以一个 8K 窗口，实际能装的中文内容大概在 4000 到 8000 字之间；32K 窗口能装的内容就宽裕不少；128K、200K 的窗口听起来很诱人，但并不是越大越好。

这里有个非常容易被忽略的点：模型在生成输出时，不是均匀地"看"窗口里所有内容的。它通过自注意力机制给窗口里的每个 Token 分配权重，窗口越长、内容越多，单位 Token 能分到的"注意力"就越少。换句话说，你想让 AI 严格执行的一条指令，如果被淹没在 100 页无关文档里，它的执行精度会明显下降。这就像开会时一个人同时收到 50 份材料，真正重要的那一页反而容易被翻过去。

2.2 上下文的分区：任务上下文、项目上下文、全局上下文

在实践 context-mode 的过程中，我逐渐把上下文分成了三个层次，这个分区方式对配置工具和优化使用效率非常有帮助：

这个分区的价值在于，每一层上下文的更新频率和粒度完全不同。全局上下文几乎不用动，项目上下文只在架构调整时更新，任务上下文则需要频繁维护。如果你把三者的信息混在一起塞进一个文件，就会出现一个典型问题：想更新任务信息时，必须小心翼翼地不碰坏全局规则；反过来，全局规则变了，又很难追踪它对历史任务的影响。

2.3 为什么"上下文越多越好"是错的

我踩过一个特别典型的坑。有次为了让 AI 助手能"全面理解"项目，我把整个项目的文件列表、数据库表结构、十几个模块的说明全塞进了上下文。结果 AI 生成的代码不仅没有更准确，反而开始把毫不相关模块的设计风格带进当前任务里，甚至出现了把一个旧模块里的废弃写法当成"项目惯例"来用的低级错误。

原因就是上下文窗口不是储物柜，而是工作台。工作台上堆的东西越多，你能看清的局部就越少。真正高效的 context-mode 应该遵循"最小必要信息"原则：只把当前任务直接依赖的约束和事实放进来，其余信息放到"需要时再查"的层级，而不是一股脑堆在窗口里。

3. 一套可落地的 context-mode 配置方法

理论讲完，聊聊实际操作。下面这套方法我在多个不同类型的项目里验证过，既有个人维护的开源工具，也有团队协作的业务系统，整体适用性很强。核心思路可以概括为四步：定义边界、组织文件、写入规则、循环迭代。

3.1 先定义你的"上下文边界"

配置 context-mode 的第一步，不是打开某个工具的开关，而是想清楚三个问题：当前任务的角色是什么？范围是什么？目标是什么？角色指的是你希望 AI 助手以什么身份工作，是"代码审查者"还是"测试用例生成器"？范围指的是它应该关注哪些模块、哪些文件？目标指的是这一轮交互最终要产出什么？

我用一个简单的模板来记录边界信息：

角色：资深 Python 后端工程师，熟悉 FastAPI 和 PostgreSQL 范围：只关注 auth 模块，涉及文件为 auth_service.py、token_manager.py、models/user.py 目标：将旧的 session 校验逻辑完整替换为 JWT 方案，并保证现有接口兼容 约束：不允许修改数据库表结构；密码加密方式保持 PBKDF2 不变

这段文字写出来之后，不管是复制到 AI 助手的对话开头，还是写进项目规则文件，都能让对方在第一时间建立正确的"心智定位"。很多用户配置 context-mode 没效果，问题不在工具，而在边界没定义清楚——AI 根本不知道自己是来干嘛的，自然给不出好结果。

3.2 上下文文件的组织方式

边界定义清楚后，下一步是把这些内容落到文件里。推荐在项目根目录建立一个专门的上下文目录，比如docs/context/，同时结合当前主流的 AI 编程工具约定，在项目根目录放一个全局规则文件。目录结构可以参考这样：

project-root/ ├── AGENTS.md # 项目级规则，AI 工具自动读取 ├── docs/ │ └── context/ │ ├── architecture.md # 架构说明与模块关系 │ ├──># AGENTS.md ## 项目技术栈 - 后端：Python 3.11 + FastAPI - 数据库：PostgreSQL 15，通过 SQLAlchemy 2.x ORM 访问 - 认证方案：JWT（access token + refresh token） - 部署：Docker Compose，Nginx 反代 ## 目录结构 - app/api/：路由层，只做参数校验和响应封装 - app/service/：业务逻辑层，核心逻辑都在这层 - app/models/：SQLAlchemy 模型定义 - app/core/：配置、安全、依赖注入 ## 约定 - 新增接口必须包含请求和响应 Pydantic 模型 - 业务异常使用 app/core/exceptions.py 中自定义异常抛出 - 数据库迁移必须生成新的 Alembic revision，禁止手动改表 - 日志使用 app/core/logger.py 中封装的 logger，禁止直接 print ## 当前任务（每次任务开始前更新） - 待办：在 token_manager.py 中实现 refresh token 的并发刷新控制 - 相关文件：app/service/token_manager.py, app/models/token_record.py - 不涉及：前端代码、支付模块

这份配置看起来简单，但它把三类关键信息都覆盖了：技术栈（项目上下文）、目录与约定（全局规则）、当前任务（任务上下文）。更重要的是，每一条规则都是"可直接验证的"，比如"禁止直接 print"，AI 在写代码时能明确判断对错。相比之下，如果你写的规则是"保持良好的代码风格"这种无验证标准的空话，AI 无法执行，配置了等于没配置。

4. 实测中的意外情况：context-mode 的坑与解法

配置得再漂亮，实战中该踩的坑一个都不会少。这里我挑四个印象最深的问题，每一个都是真实发生过、并且能稳定复现的，分享出来帮大家提前避雷。

4.1 上下文过期：旧信息比没有信息更危险

第一个坑是上下文过期。我的一个业务项目里有张order表，早期有一个status字段，取值范围是pending、paid、shipped、cancelled。后来产品调整，新增了refunded状态，并且把shipped改成了delivering。如果 AI 助手的上下文里还是旧的状态枚举，生成的代码就会调用旧常量，轻则报错，重则产生脏数据。

解法是把"时效性"写进上下文管理流程。我的做法是在task-current.md头部加上"最后更新日期"和"涉及模块版本号"，并在规则里明确要求 AI：当发现代码实际逻辑与上下文描述不一致时，必须以代码为准，并在回复里指出来。这个规则看起来像是在"打脸"上下文，实际上是防止过期信息带来更多错误的有效兜底。

4.2 上下文污染：无关内容挤占窗口

第二个坑是上下文污染。有段时间，我为了省事，把测试目录、迁移脚本、甚至一些历史归档文件的说明全都放进了项目上下文。表面上看信息很全，实际效果却很糟糕。AI 在生成代码时，会不由自主地"参考"那些归档文件里早已废弃的写法，因为那些内容也在上下文窗口里占着一席之地，模型无法区分"存在的文件"和"应该遵守的规范"。

解法是引入白名单思维。在规则文件里明确定义 AI 必须关注哪些文件、可以忽略哪些目录，并且把需要 AI 阅读的文档控制在必要范围内。我后来把docs/context/里的文件精简到三份：架构、数据模型、当前任务，效果立刻好转。记住一个朴素原则：上下文不是档案室，而是手边工具箱，只有常用的才值得放在手边。

4.3 安全边界：不要把敏感信息塞进上下文

第三个坑是安全边界。context-mode 的一个隐性风险在于：你把多少信息交给工具，工具就可能拿这些信息做什么。比如你为了图方便，把数据库连接字符串、内部 API 密钥、用户脱敏前的原始数据写进了上下文，而工具的上下文信息有时会被记录在日志、缓存甚至第三方服务中。一旦泄露，后果不可控。

我的安全准则是"最小权限原则的上下文版本"：凡是密钥类信息一律不进上下文，用环境变量引用；凡是涉及真实用户数据的，先用假数据或脱敏数据替代；凡是项目内网地址，只写说明不写可访问 URL。这条经验尤其重要，因为上下文信息相比代码仓库，往往更隐蔽、更容易被忽略，反而成为安全盲区。我在一个团队里推行这套准则后，至少避免了一次因上下文包含真实令牌而导致的仓库泄露风险。

4.4 性能不是免费的

最后一个坑更现实：性能。上下文越长，AI 每次请求需要处理的内容越多，响应速度越慢，消耗的计算资源也越高。尤其是上下文里有大段大段的项目文档时，本来几秒钟能返回的结果会被拖到半分钟，开发体验大打折扣。

我的优化做法是对长文档做摘要，而不是把原文直接塞进上下文。比如architecture.md里原本有三千字的模块说明，我会把它压缩成"核心模块职责清单"，一条一行，附上文件路径。这样既保留了关键信息，又显著缩短了上下文长度。大家可以对比一下，同样是描述认证模块，三千字的架构分析文和一行"认证模块在 app/service/auth.py，负责登录、登出、令牌刷新"相比，后者在 context-mode 里效率反而更高。

5. 进阶：让 context-mode 自动适配你的项目

基础配置跑通之后，如果你还想进一步提升效率，可以试试下面这几个进阶方向。它们的目标是一致的：让上下文从"手动维护"变成"半自动生成"，减少人工更新的成本和滞后性。

5.1 从文件系统到语义地图

项目越来越大之后，靠人工在architecture.md里维护模块关系会越来越吃力。一个替代方案是写一个简单的脚本，自动分析项目目录结构、核心依赖关系和入口文件，生成一份"语义地图"式摘要。在我的 Python 项目里，我用一个小脚本扫描app/目录下的所有模块，提取每个模块的 docstring 和关键类名，然后自动更新到docs/context/architecture.md。

python scripts/build_context_map.py --source app --output docs/context/architecture.md

这个脚本的思路很简单：遍历目录 -> 解析文件头部 docstring -> 提取类名和函数名 -> 按依赖关系排序 -> 生成 Markdown 清单。生成的文档不需要太详细，能给出"这个模块是干什么的、它的核心入口在哪"就够了。关键价值在于，每次架构调整后，运行一次脚本就能让上下文跟上变化，不用再手动翻代码更新文档。

5.2 与版本控制联动

另一个很实用的方向是让上下文主动感知代码变更。Git 本身就包含大量有价值的上下文：最近改了什么、这次提交要解决什么问题、哪些文件被动过。把这些信息注入 context-mode，AI 助手就能更好地理解当前工作状态。

我现在的做法是，在每次开始新任务时，先手动或通过脚本拉取最近几笔提交的信息，写入task-current.md开头：

git log --oneline -5 --no-merges git diff --stat HEAD~1

这两条命令的输出加起来不过几百个字符，却能提供非常有效的"位置感"。AI 看到最近改动集中在payment模块，而当前任务涉及order模块，就更容易推断出两者可能存在的耦合关系，生成的代码也会更有针对性。

5.3 用记忆层实现跨会话连续性

基础 context-mode 的局限在于，会话一结束，任务上下文就丢了。下次重新打开工具，AI 还是一片空白。要解决这个问题，需要增加一个"记忆层"，核心做法是定期把当前会话的结论沉淀回项目文档。

我的习惯是，每次任务收尾时，花五分钟把三件事写进task-current.md的"本次结论"区：这次做了什么决策、为什么做这个决策、下一步打算做什么。这个习惯坚持下来以后，我会发现一个奇妙的效应：不仅是 AI 助手能快速恢复上下文，我自己在不同时间点切换任务时的恢复速度也大大提升了。因为你在写结论的过程中，等于帮未来的自己重新梳理了一遍思路。

记忆层还可以用自动化手段强化。比如通过脚本在每次 CI 通过后，把测试结果和覆盖率追加到项目上下文里；或者定期将对话记录中的重要决策自动转存为 Changelog 草案。这些都属于"让上下文自动生长"的思路，关键是找到适合自己项目的自动化粒度，而不是一味堆脚本。

最后：关于 context-mode 的一句话总结是行不通的

写了这么多，最想说的是：context-mode 不是一个打开就生效的开关，而是一套需要持续维护的工作方式。从最初手动写任务快照，到后来配置自动化脚本生成架构摘要，再到如今把上下文维护当成日常开发的一部分，我最大的体会是——真正解决问题的不是某个工具的某个按钮，而是你愿意把模糊的"我记得"变成清晰的"写下来了"。

如果你刚接触这个概念，建议不要一次性照搬全部做法。先挑一个最简单的动作开始：下次开始编码前，花两分钟把"当前任务要做什么、相关文件有哪些、不碰什么"写下来。坚持一两个星期，再回头看效果。你会发现，那些曾经让人抓狂的中断和遗忘，大部分都能被这个小小的习惯消解掉。