企业官网建设流程全解析

你有没有遇到过这种场景：项目代码看了半天，正准备让 AI 助手帮忙改一处逻辑，却发现自己光是解释"当前项目的目录结构、相关文件、依赖关系"就写了快一千字。我遇到太多次了。于是某个周五的下午，我开始写一个叫 context-mode 的小工具——它要解决的只有一个问题：帮你把上下文整理好、递到该递的地方。这篇文章就把我大半年来的设计思路、落地配置和踩坑过程完整摊开讲，适合那些每天在编辑器、终端和 AI 工具之间反复搬运上下文的人，也适合想自己动手做一个上下文管理插件的朋友。

1. 上下文碎片化问题：context-mode 要解决的真正痛点

1.1 每天在"粘贴-翻找-解释"之间流失的上下文

先盘一下日常。上周我改一个订单模块的遗留 bug：数据库表结构在schema.sql里，订单状态枚举在constants.ts，订单服务逻辑在order-service.ts，最新的改动记录散在三个 commit 里。为了给 AI 助手讲清楚现状，我把每个文件的关键段落反复复制、粘贴、删掉、再重贴。光整理这段上下文就花了二十分钟，真正改代码的时间反而只有五分钟。

这不是个例。做过几轮重构的人应该都有类似体感：大部分时间不是花在写代码上，而是花在让别人（或者让模型）理解你要干什么。尤其是用 AI 辅助编程之后，问题更明显了。你发给模型的 prompt 质量，直接决定了回包质量。而 prompt 的核心，就是上下文——哪些文件、哪些约束、哪些报错信息、哪些近期变更值得被带上。

我统计过自己一周的工作节奏：每次"上下文整理"大概 5 到 10 分钟，一天至少五回。一个月下来就是十多个小时。这个数字足够让我觉得：必须有个东西把这件事自动化。context-mode 在最开始就是为了消灭"复制粘贴上下文"这个动作而生的，后来才慢慢长成一个完整的上下文管理工具。

1.2 大窗口不等于好上下文：为什么 context-mode 主打"少而精"

你可能会说：现在模型上下文窗口不是动辄 128K、200K 吗？直接把整个仓库塞进去不就行了。我曾经也这么想，然后被现实教育了两次。

第一次是成本。一整个中型项目的源码加文档，大概有几百万 token，按当前 API 价格走一遍就是不小的开销。你在本地跑开源模型更难受，上下文一到窗口上限附近，生成速度和质量同时下滑，最后变成"你问它东，它答西"。

第二次是效果。模型并不是上下文里每个位置的信息都能同等利用。大量研究表明，模型对上下文开头和结尾的信息敏感度明显高于中间部分——你把 200K 的代码全塞进去，真正有用的那个文件可能正好落在"注意力盲区"里。这个现象在业内有句话叫"lost in the middle"，我后来在 context-mode 的调试中也反复踩到：不是上下文越多越好，而是越精准越好。

所以 context-mode 的核心设计原则从一开始就定成了"少而精"。它要做的是判断：当前这个任务、这个时刻，哪些信息配得上进入上下文，哪些信息纯属噪音。剩下的交给工具自动处理，而不是让你手动做判断。

2. context-mode 的核心设计：作用域、权重与记忆分层

2.1 三层作用域：项目级、会话级、瞬时级

我在设计 context-mode 的时候，最头疼的问题就是"哪些内容该进上下文"。如果所有文件一视同仁地堆进去，工具本身就成了新的噪音源。最后我参考了操作系统的内存管理思路，把上下文拆成三个作用域，每个作用域承担不同的职责：

• 项目级（project scope）：整个仓库的稳定信息，包括语言和框架、目录结构、代码规范、架构文档、约定俗成的写法。这类信息几乎不变，每次任务都应该带上，但占比要控制。
• 会话级（session scope）：当前这一轮工作涉及的内容，比如正在改的文件列表、最近几十分钟的 git diff、相关测试用例、你给自己写的一句任务目标。它会随着会话推进不断更新。
• 瞬时级（instant scope）：只跟当前问题强相关的内容，比如一条报错堆栈、你刚定位到的那一个函数、一条具体的 SQL 日志。用完就该丢，不占长期名额。

这三个作用域对应到配置上大概是这个样子：

[scope.project] enabled = true max_tokens = 8000 include = ["README.md", "docs/**/*.md", ".editorconfig", "src/**/types.ts"] [scope.session] enabled = true max_tokens = 16000 track_files = ["src/**/*.{ts,js}", "tests/**/*.ts"] track_git_diff = true diff_window_minutes = 30 [scope.instant] enabled = true max_tokens = 4000 auto_capture_error_stack = true

这个拆分的好处是，你不需要每次都想"这个文件要不要给模型看"，只需要判断它属于哪一层。任务范围越大，越依赖项目和会话层；问题越具体，瞬时层的权重就越大。这种分层思路后来被很多 AI 编程工具采用，但 2024 年我写 context-mode 的时候，市面上的工具普遍还是在做"全量注入"或者"手动选择文件"这种粗糙活。

2.2 权重打分：什么内容才有资格进入上下文

分层解决的是"从哪找"的问题，还有一个更麻烦的问题：同一层里文件多了，到底带谁？比如会话级跟踪了 20 个文件，但 prompt 放不下，怎么办？

我给 context-mode 加了一个权重打分机制。每个候选文件会从三个维度打分：

• 相关性：文件内容与当前会话关键词的重合度。你正在改支付逻辑，一个带payment字样的文件名天然比utils/string.ts得分高。
• 新鲜度：文件的最近修改时间。刚保存过的文件通常跟当前任务强相关，一周没动的文件大概率是背景信息。
• 引用频率：当前关注的文件是否频繁 import 它，或者是否被大量其他文件引用。一个被 80 个文件引用的公共类型定义，优先级高于一个只被自己调用的私有函数。

最终得分是三个维度的加权和，权重可以调节：

这个机制上线后，效果立竿见影。之前我手动挑文件，总是凭直觉带上几大块"可能有用"的代码。现在工具会告诉你：这个仓库里，当前任务最值得带的是这三个文件，理由分别是"与支付流程强相关""5 分钟前刚修改""被 23 个文件引用"。人不需要理解所有候选文件，只需要理解排序结果。

2.3 用记忆分层理解 context-mode

如果你不是工具作者，而是普通用户，可以用一个更生活化的方式理解这套设计：把 context-mode 想象成人脑的记忆系统。

项目级作用域是长期记忆——你的母语、你的生活习惯、你公司的规章制度。这些不需要每次重新回忆，但也不会因为今天吃了什么而改变。会话级作用域是工作记忆——你现在手头在做的任务、桌面上摊开的文件、刚跟同事讨论到一半的结论。瞬时级作用域则是你眼前看到的便利贴，上面写着"别忘了改第 137 行"，看完就可以撕掉。

一个人如果长期记忆特别强但工作记忆很差，就会表现为聊起框架头头是道，但永远记不住刚才说到哪。反过来，如果什么都往长期记忆里塞，也会因为信息过载而变得迟钝。context-mode 做的其实就是这件事：让长期记忆稳定可靠，让工作记忆实时更新，让便利贴用完即焚。这样理解之后，配置起来就不会觉得抽象了。

3. 落地实操：配置 context-mode 并跑通第一轮对话

3.1 安装初始化与最小配置

context-mode 目前以命令行工具为主，附带编辑器插件。安装过程很简单：

npm install -g context-mode cd your-project context-mode init

init会自动扫描仓库结构，生成一个.context/config.toml文件，并创建.context/knowledge/目录用于存放未来的上下文片段。初次生成的配置有几个需要手动确认的点：项目语言、主框架、文档目录位置。它会尝试通过识别包管理器和锁文件自动推断语言，但框架识别偶尔会判断错误，建议人工瞄一眼。

一份最小可用配置不一定很复杂，我自己会保留这些核心项：

# .context/config.toml [project] name = "order-service" language = "typescript" frame = "nestjs" [scope.project] max_tokens = 8000 include = ["README.md", "src/**/types.ts", "docs/architecture.md"] [scope.session] max_tokens = 12000 track_git_diff = true diff_window_minutes = 30 [memory] ttl_seconds = 1800 checkpoint_interval = 60 token_budget = 8000

注意token_budget这个选项我特意加在[memory]下，它是整份最终 prompt 的硬上限，作用域各自的 max_tokens 加总不能超过它。如果超了，按照权重从低到高裁掉。这个兜底逻辑非常重要，后面讲 Token 失控的时候你会知道为什么。

初次配置完，可以先跑一条命令看看当前环境：

context-mode status

它会输出当前项目、会话作用域里跟踪了哪些文件、已占用 token、以及估算的裁剪比例。

3.2 核心命令与快捷键设计

context-mode 的命令设计原则是"能少记就少记"。常用的就这几个：

# 查看当前上下文状态 context-mode status # 手动把文件加入会话上下文 context-mode add src/order.service.ts # 手动移除某个文件 context-mode drop src/order.service.ts # 列出当前所有上下文片段 context-mode ls # 生成最终 prompt（输出到 stdout 或剪贴板） context-mode build --copy # 监控文件变化，自动更新会话上下文 context-mode --watch

build是核心命令。它会按"项目级 -> 会话级 -> 瞬时级"的顺序拼接所有上下文片段，附加各类分隔标记，最后把结果输出到剪贴板。这样你直接粘贴给 AI 助手就是一份结构化的、可读的上下文。

编辑器插件提供一组快捷键，实测下来使用频率极高的是这四个：

快捷键映射到插件动作后，操作基本可以做到"手不离键盘"。

3.3 一个修 bug 的典型工作流

纸上谈兵没意思，我把一个完整的修 bug 流程放出来给你看。

第一步，我在 IDE 里发现测试报错，提示OrderService.calculateTotal拿到的税率是 undefined。我打开order.service.ts，按下 Ctrl+Alt+A，把它加入会话上下文。

第二步，context-mode 立刻做了几件事：根据当前文件的 import 关系，找到tax.service.ts和order.entity.ts作为候选关联文件；检查 git diff，发现tax.service.ts最近 30 分钟有改动；给两个文件打了高分，自动加入会话上下文。我连手都不用动。

第三步，按下 Ctrl+Alt+X，上下文 prompt 已经带着"项目基础信息、当前会话跟踪的 4 个文件、git diff 内容和报错信息"一起复制到剪贴板。我把它粘贴给 AI 助手，让它分析税率 undefined 的原因。

第四步，AI 助手给出了答案：tax.service.ts的方法签名从getRate(order)改成了getRate(order, region)，调用方没更新。我改完代码，Ctrl+Alt+R 刷新上下文，让刚才的修改进入新的 diff 状态。

第五步，测试通过后跑context-mode clean，清空瞬时层，进入下一个任务。

这个流程看起来像流水账，但它背后有一个关键转变：我不再需要自己决定"该把什么喂给模型"，工具替我做了前置筛选。省下来的时间不是一点点，而是让整个辅助编程体验从"能用"变成了"顺滑"。

4. 实战中遇到的坑：上下文污染、重复注入与 Token 失控

4.1 上下文污染：旧文件占据名额，新信息进不来

第一个让我头疼的坑是上下文污染，而且是在改一个持续两小时的线上 bug 时暴露的。那个 bug 涉及老模块，我在会话早期把一堆历史文件加入了上下文，中途逐步定位到真正的根因，发现完全在一个新文件里。但因为我一直没手动清理，早期那些"旧功臣"还在占据名额，权重排在它们后面的关键文件反而被挤掉了一部分。

我后来复盘，根因不是工具排序有问题，而是上下文更新没有时间维度。一个文件哪怕五分钟前无比重要，五十分钟后可能就是干扰。AI 模型在生成时不会主动"忘掉"上下文的开头部分，它会继续参考那些过时信息，导致回答被陈旧上下文带偏。

解决办法是我在[memory]区引入 TTL（存活时间）概念。默认情况下，会话级文件如果 30 分钟没有被引用，权重自动降一级；被项目级明确指定的文件除外。配置参数是ttl_seconds = 1800。实测下来非常有效，长时间会话的准确率明显回升。

[memory] ttl_seconds = 1800 # 30 分钟未被引用的会话级文件自动降级 checkpoint_interval = 60 token_budget = 8000

4.2 重复注入与 Token 失控：watch 模式悄悄吃掉你的预算

第二个坑更隐蔽：我推荐过context-mode --watch监听文件变化，它本意是让会话上下文自动更新，但默认行为是"文件只要变化就重新计算并全量注入"。在一次密集开发中，我连续保存了 20 多次文件，watch 模式就重新注入了 20 多次，等我把 prompt 粘给模型时才发现，token 占用竟然比预期高了一倍还多。

做了一次小实验统计：

问题出在"全量注入"这个策略上。文件里只改了一行，工具却把整个文件重新编码送进 prompt，而模型拿到的是同一个文件的两份结果，还可能导致自相矛盾。

修复方案是差分注入。context-mode 为每个跟踪文件建立 checkpoint，只有当 diff 长度超过阈值（默认 50 行）或者文件路径是新加入时，才重新注入完整内容；小改动只追加一段 diff 标注。加了checkpoint_interval = 60之后，watch 模式的 token 占用直接回落到接近手动刷新水平。这也是我把这项配置放在[memory]区下的原因——它本质上就是给上下文加了一个类似 gitcommit的版本管理。

4.3 规则引擎误伤：手动指令反而被过滤

最后一个坑最有代表性。某个用户在使用过程中反馈：我手动context-mode add foo.ts，结果跑完build之后，foo.ts并没有出现在最终 prompt 里。

排查了很久，最后发现是权重机制误伤。foo.ts是一个专门写死的配置值文件，既没有和当前会话关键词重合，也不是最近修改的，引用频率也不高。加权总分排在了裁剪阈值以下，被工具当成了"低价值上下文"舍弃了。

我一开始觉得工具做得没错——按照分数裁剪就是它的职责。但后来我意识到一个问题：手动操作是用户的显式意图，权重是算法推断的隐性意图，显式意图的优先级必须更高。这不是排序问题，这是产品设计原则。于是我在配置里增加了一个manual_override = true选项，被手动 add 的文件永不参与自动裁剪，除非用户手动 drop。

[memory] manual_override = true # 手动添加的上下文不被自动裁剪

这个坑给我留下一个长期原则：任何自动化工具都不能替用户做最终决定。算法过滤只能作为默认行为，永远要留一个"显式绕过"的口子。

5. 进阶玩法：团队级上下文仓库与动态注入

5.1 把架构文档与代码规范变成可检索的上下文片段

单个开发者用 context-mode 解决的是个人效率问题，但真正让上下文价值翻倍的是团队协同。我把项目里的架构文档、数据库设计约定、编码规范拆成了一段段可检索的上下文片段，放在.context/knowledge/目录。

我采用 YAML 格式做标签和匹配规则：

# knowledge/db-migration.yaml - file: "docs/db-migration.md" tags: [database, migration, schema] match: - "表结构" - "那张表" - "ALTER TABLE" - "migration" max_tokens: 5000 scope: project - file: "docs/api-error-handling.md" tags: [api, error, exception] match: - "错误处理" - "异常" - "HTTP status" max_tokens: 3000 scope: project

当用户在对话中提到"表结构"或者"ALTER TABLE"时，context-mode 会将docs/db-migration.md的摘要片段注入到当轮上下文中，而不是整篇塞进去。这样做的好处是：知识按需投放，不是一次给完。架构文档动辄几千行，全量注入既浪费 token，又会把关键细节淹没在中间。

5.2 团队共享的 .context 目录

.context/这个目录我会提交到 git 仓库。新成员 clone 项目后，不需要再花一整天翻文档，直接跑context-mode status，就能看到项目级上下文里注入了哪些约定和架构说明。这就是把团队的隐性知识变成了显性配置。

注意一个安全红线：.context 目录里绝对不能提交密钥、密码、Token 之类的敏感信息。上下文片段会被注入给模型，等于把机密直接发给了外部服务。我的建议是单独维护一份.context/.gitignore，把类似secrets.yaml、*.env这类文件挡在仓库外。如果你必须引用涉及敏感信息的文档，要么把敏感内容剥离出去，要么用占位符替代，并在 PR review 时重点盯这个目录的变更。

5.3 动态注入规则：结合 git 历史与 CI 状态

进阶一点，我把 context-mode 和 git 历史、CI 状态打通了。规则是这样：当会话跟踪到src/payment/目录下的任何文件变化时，自动注入支付模块的上下文片段，包括支付流程说明、相关测试清单、常见失败模式。

# rules/payment-module.yaml triggers: - watch_path: "src/payment/**" actions: - inject: "docs/payment-flow.md" - inject: "docs/payment-failure-checklist.md" - add_tags: [payments, stubbing]

实际使用中有个很舒服的场景：你刚改完支付模块的某个文件，还没开口，context-mode 已经自动帮你把相关的支付流程说明和踩坑清单带上了。这种"上下文跟人走"的感觉，比你自己去记忆"这个模块要用哪些文档"要省力太多。当然，动态注入规则需要克制，触发条件太宽泛会让上下文意外变大，建议只给高价值模块配这种规则。

6. 半年维护下来：context-mode 的使用边界与最终配置

6.1 它解决不好的问题

说了这么多,我也想把反面的场景讲清楚。context-mode 不是什么"银弹",有几类情况它帮不上忙：

第一，完全没有任何文档积累的新项目。项目级上下文是依赖 README、架构文档、代码规范这些"既有信息"的。如果你项目的.context/knowledge/目录是空的，context-mode 能做的只是帮你按引用关系排序文件，效果会打折扣。建议新项目在稳定一两个模块之后再接入。

第二，纯个人临时点子。比如你在纸上画了一个 idea，或者终端里跑一条临时 curl，这些不需要三层作用域来管理。上下文管理工具适合处理有"历史、有结构、有沉淀"的代码项目，不适合给随手笔记增加负担。

第三，需要特别灵活输出的探索型任务。如果任务是"帮我 brainstorm 几个设计方案"，你需要的反而不是精准上下文，而是发散空间。强行注入一堆既有代码，反而会限制模型的思路。我自己的习惯是：探索型问题不带上下文，执行型问题才用 context-mode。

6.2 我的最终推荐配置

经过大半年的反复调整,我目前的主力配置是这样的：

[project] name = "order-service" language = "typescript" frame = "nestjs" [scope.project] max_tokens = 8000 include = ["README.md", "src/**/types.ts", "docs/architecture.md"] [scope.session] max_tokens = 12000 track_git_diff = true diff_window_minutes = 30 [scope.instant] max_tokens = 4000 auto_capture_error_stack = true [memory] ttl_seconds = 1800 checkpoint_interval = 60 token_budget = 8000 manual_override = true [knowledge] enabled = true directory = ".context/knowledge"

几个点解释一下：ttl_seconds = 1800是经过多次长会话验证的经验值，太短会导致上下文频繁切换，太长又回到污染问题；checkpoint_interval = 60保证 watch 模式一分钟最多产生一次全量注入；manual_override = true必须开，保护手动操作不被权重裁剪。

6.3 后续想做的方向

接下来我计划做几件事。首先是更好的上下文可视化——当前context-mode status只给出 token 数字，我想加一个类似"地图"的界面，让用户一眼看到项目级、会话级、瞬时级各自占了多少空间，哪些内容即将过期。其次是多语言解析增强，现在引用关系的判断对 TypeScript 最友好，对 Python、Go 的支持还有一些细节要补。最后是与其他 agent 工具的打通，比如让 context-mode 生成的上下文直接作为它们的工具输入，省去复制粘贴这一步——不过这个方向涉及协议设计，还在研究阶段。

如果你也在搞类似的上下文管理工具，或者对某个部分的设计思路有更好的想法，欢迎交流。这类工具现在还没有标准答案，正因为如此，它才值得继续做下去。