K7-Tech

一次上线事故教会我的三件事：清单、验证、同步

Sun, 01 Nov 2026 00:00:00 GMT

时间说明：事故发生在 2021 年 5 月 20 日，问题于次日发现。

2021 年 5 月 20 日 19:00，我发布了一个看似简单的需求：在申请流程中增加一项必填校验。

开发前，我因为疏忽忘记了这项任务，只能将发版推迟一天。开发时，我发现正常申请入口和另一个业务入口共用了部分逻辑，但两个入口能提供的信息并不相同。我没有继续确认另一个入口的实际调用情况，按自己的理解完成了修改。

发版后，我没有等待完整回归，也没有查看线上日志，便离开了。直到第二天，同事发现了问题。

这次事故涉及的技术并不复杂。问题出在三个环节：任务推进、影响面判断和发版后观察。我都把「应该没问题」当成了事实。

一、任务不能只记在脑子里

这次问题最早出现在发版前一天。我忘记了自己的任务，直到临近发版才开始补救。任务推迟后，我也没有确认所有相关人员是否都知道这个变化。

当时我以为，只要自己记住任务就够了。但一个任务除了「要写什么」，还包括依赖谁、何时提测、何时发版，以及计划变化后需要通知谁。只记住开发内容，并不等于管理好了任务。

更可靠的做法是把任务写进清单，每天至少检查一次。清单不必复杂，但要回答几个问题：

当前要交付的结果是什么？
还依赖谁提供信息、Review 或测试？
下一个明确时间点是什么？
如果计划变化，需要通知哪些人？

清单用来减少遗漏，不必追求形式。计划发生变化时，也不能把「某个人知道」当成「所有人已经达成共识」。涉及提测和发版的变化，需要明确同步，并确认关键人员已经收到。

二、「我以为」不能代替验证

这次修改最大的风险，是我在影响面不清楚时，仍然确信自己的判断。

现在回看，当时至少有三个问题没有回答：

这项校验是否真的需要由服务端强制执行？
另一个入口是否也能提供校验所需的信息？
修改公共逻辑后，两个入口分别需要回归哪些场景？

我没有通过代码、日志或实际请求确认这些问题，也没有把两个入口的差异明确告诉测试人员。个人猜测就这样代替了可以验证的信息。

会影响业务行为的判断，都要尽量变成可以验证的事实。

关心入口差异，就检查两个入口的请求参数和调用关系；关心历史数据，就抽样确认旧数据是否满足新条件；无法自己确认，就把问题、可能影响和待验证项明确交给产品或测试。

提问能把风险尽早暴露给相关人员。独自消化一个不确定点，往往只是让风险晚一点暴露。

AI 让猜测看起来更像答案

这次事故发生时，AI 编程助手还没有进入我的日常开发。现在，AI 已经能参与需求拆解、代码生成、测试编写和问题排查。它能加快实现，也会让「我以为」变得更隐蔽。

过去，我不确定一个概念时，可能直接按自己的理解写代码。现在，我可能会先问 AI。如果提示里缺少关键上下文，AI 就可能虚构一个看似合理的概念、接口或调用关系。回答越完整、语气越肯定，我越容易把「AI 这么说」误认为「事实已经得到确认」。

AI 还能继续基于错误前提生成实现和测试。代码能运行，测试也可能通过，但它们验证的可能只是同一个错误假设。整个开发流程可能因此建立在未经确认的概念上。

与 AI 沟通时，不能只要求它给出答案，还要改变提问和验收方式：

要求 AI 区分已知事实、推测和修改建议，并提供对应的代码、文档或日志依据。
对 AI 提出的新名词、字段、接口和调用关系，回到源码与真实环境中验证；找不到依据，就不进入实现。
除了让 AI 生成代码，也让它列出反例、影响入口和验证清单，用独立证据检查结果，避免同一个错误前提被反复用于自证。

AI 适合帮助我们提出假设，事实仍要自己验证。自己的经验、同事的建议和 AI 的输出，在进入生产前都应接受同样的检查。

三、代码发布不等于任务完成

发版后没有观察日志，是这次事故中最直接的责任缺位。

当时我把「代码已经发布」当成了任务终点。但从用户角度看，发布只是变更开始影响真实流量的时刻。测试环境无法覆盖所有数据、入口和调用组合，发版后的观察正是最后一道及时发现问题的机会。

一次完整的交付，至少应包含发版后的几个动作：

查看错误日志，确认是否出现新增异常。
观察与本次修改直接相关的业务指标。
验证最重要的正常流程和受影响入口。
出现异常时，及时同步影响，并按预案回滚或修复。

观察什么，应当在发版前就确定。否则发版后面对大量日志和指标，很容易变成随便看一眼，甚至完全不看。

回滚方案也不应在出问题后才临时讨论。代码如何回退、配置如何恢复、数据变更是否可逆，都属于交付的一部分。

一份更实用的检查清单

日常开发中，可以用三个问题检查自己的交付过程。

开发前：确认任务边界。

写清需求目标、影响入口、依赖人员和交付时间。遇到不明确的地方，尽早提出，别急着按自己的理解实现。

发版前：验证关键判断。

检查不同入口、异常参数、历史数据和兼容场景。把测试需要关注的差异明确说出来，不要指望别人自动知道自己的修改思路。

发版后：观察真实表现。

查看日志和业务指标，验证核心流程，明确观察责任与回滚方式。确认没有异常后，再把任务标记为完成。

这三件事都不复杂，坚持做却能减少很多交付问题。

把功能写出来只是第一步。任务清楚、判断有据、风险可见，才是一次可靠的交付。

接到需求别急着写实现：AI 时代更需要自顶向下拆任务

Sun, 01 Nov 2026 00:00:00 GMT

时间说明：与本文方法直接相关的记录写于 2020 年 5 月 14 日。当时正在总结入职初期的开发方法，本文于今日重新整理。

刚参加工作时，我容易一接到需求就开始写实现。遇到一个细节，就停下来修改；想到一个优化点，又转去调整结构。忙了很久，代码量增加不少，主流程却还没有跑通。

后来观察有经验的同事开发，我发现他们开始前已经拆好了步骤：先列出大致流程和空方法，再逐步补实现；功能与测试一起推进；临时想到的事情先记入 TODO，不立刻打断当前任务。

这套自顶向下的方法，在 AI 时代反而更重要。AI 能加快代码生成，却不能自动替我们确定需求边界和交付顺序。规划越模糊，生成速度越快，返工也可能来得越快。

一、实现速度快，不等于交付速度快

没有任务拆分时，开发过程很容易被局部细节牵着走。

一个参数校验还没想清楚，就开始优化数据库访问；主流程还没有验证，就先抽象一个未来可能复用的组件；发现另一个模块也有问题，又顺手扩大修改范围。每个动作看起来都有价值，但都不一定服务于当前交付。

AI 辅助开发会放大这个问题。只输入一句「帮我实现这个功能」，AI 可能一次生成接口、数据模型、异常处理和测试。内容看起来很完整，却可能包含不存在的需求、未经确认的假设和超出范围的修改。

交付速度应该从「确认需求」算到「验证通过」。自顶向下拆任务，就是先把这条路画出来，再决定每一步写什么。

二、先确定终点，再拆实现步骤

拆任务首先要确认最终要交付什么，暂时不用急着设计类和方法。

以「给现有申请流程增加一项校验」为例，开始前至少需要明确：

哪个入口需要这项校验？
校验失败时，用户应该看到什么结果？
历史数据和另一个入口是否受影响？
本次明确不修改哪些行为？

这些问题构成验收边界。边界不清楚时，不急着让 AI 或自己生成实现。

接下来，把目标拆成一条可以验证的主流程：

接收并检查请求参数。
读取校验所需的数据。
执行业务规则。
保存结果或返回错误。
验证正常流程和异常流程。

到这里才需要空方法。空方法用来固定主流程，让每一步都有明确输入、输出和完成条件。实现某一步时，暂时不被其他步骤的细节干扰。

三、临时想法进 TODO，不立即扩大范围

开发过程中总会冒出新想法：这里可以优化，那里可以抽象，另一个接口似乎也应该一起修改。

这些想法不一定没有价值，但出现的时间未必合适。立即处理，会不断切换上下文，也会让本次修改越来越难以验证。

更稳妥的方式是先把它们写进 TODO，并简单注明原因。完成当前主流程后，再逐项判断：

不处理会不会影响本次验收？
属于当前需求，还是另一项独立改进？
如果现在处理，需要新增哪些测试和回归范围？

AI 也会不断提出类似建议，比如引入新的设计模式、增加一层抽象，或者顺带重构相关代码。对这些建议同样先放入 TODO，别因为 AI 给出了一段完整实现，就直接扩大交付范围。

TODO 用来保护当前最重要的工作，避免它淹没在新增想法里。

四、小步实现，让每一步都有反馈

主流程确定后，再按最小可验证步骤推进。

可以先完成数据模型及对应测试，再连接接口和业务逻辑，随后检查返回结构，最后验证完整流程。每一步只处理一个主要问题，并尽早得到测试、运行结果或代码 Review 的反馈。

「小步」强调每一步都能回答：刚刚完成了什么，如何证明它没有破坏已有行为。提交是否够小，也应该用这一点判断。

如果某一步需要同时修改多个模块、补大量代码，甚至只能靠完整上线后才能验证，通常说明任务还需要继续拆分。

五、用 AI 开发时，把任务拆分写进提问

AI 很适合承担局部实现，但前提是我们能清楚描述当前步骤。给 AI 的信息不应只有一句需求描述，还应包括目标、边界和验收方式。

一个实用的提问框架是：

目标：本次要改变什么行为？
已知事实：哪些代码、文档或运行结果已经确认？
边界：哪些文件、入口和行为不在本次范围内？
当前步骤：现在只完成哪一步？
验收条件：需要运行哪些测试，检查哪些结果？

这套框架既是给 AI 的上下文，也是给自己的开发约束。

当 AI 返回实现后，先检查它是否引入了未经确认的概念，是否修改了边界外的代码，是否满足验收条件。当前步骤验证通过后，再进入下一步，别一次性接受整个功能的所有改动。

使用 AI 时，可以按这个方式分工：AI 加速实现、补充反例和检查遗漏；工程师确认目标、安排顺序、控制范围，并对验证结果负责。

六、主流程可以边做边调整

拆任务不意味着在开发前预测所有细节，也不等于用大量文档延迟实现。

一开始只需要画出主流程和验收边界。开发中获得新证据后，可以调整后续步骤，但调整仍然要回到整体目标，别让临时发现牵着走。

日常开发时，可以用五个问题检查自己的进度：

最终要交付的结果是什么？
主流程可以拆成哪几个可验证步骤？
当前只做哪一步？
哪些新想法应该先进入 TODO？
用什么证据确认这一步已经完成？

无论由人写代码，还是由 AI 生成代码，这些问题都不会消失。

AI 时代更需要开发规划，主要因为实现变得太快。先想清楚要去哪里，才能用生成速度缩短交付时间。

K7-Translate：用本地模型为浏览器增加翻译能力

Sun, 01 Nov 2026 00:00:00 GMT

项目时间：K7-Translate 最早提交于 2026 年 10 月 28 日。本文基于 2026 年 10 月 31 日的仓库代码，介绍它解决的问题、使用方式和当前边界。

阅读英文技术文档时，有时只需要理解选中的一句话，有时则需要在原文和译文之间持续对照。K7-Translate 是我为此开发的浏览器扩展，面向 Microsoft Edge 和 Google Chrome，支持选中文本自动翻译，也能将网页正文切换为原文、双语或译文视图。

项目默认使用 Index-Translate-2B，通过 llama.cpp 在本机运行。按默认方式部署时，网页文本不需要发送到第三方在线翻译服务，翻译请求可以在自己的电脑上完成。

它具体能做什么

K7-Translate 目前提供两种翻译方式。

选文翻译，在普通网页中选中一段文本后，扩展会显示翻译浮层。浮层支持切换目标语言、复制译文和失败重试。输入框与可编辑区域不会自动触发，避免影响正常输入。

选文翻译适合局部理解，比如确认一个术语、一段错误信息或文档中的某句话。当前支持 2 至 4000 个字符，目标语言包括简体中文、繁体中文、英语、日语、韩语、法语、德语、西班牙语和俄语。

整页正文翻译，点击浏览器工具栏中的 K7 图标后，扩展会优先从页面的 article 或 main 区域收集正文段落，再逐段请求翻译。译文随任务进度逐步插入，不需要等整页完成后才能阅读。

整页翻译提供三种显示模式：

原文：暂时隐藏译文。
双语：保留原文，并在段落后显示译文。
译文：隐藏已翻译的原文，只显示译文。

点击「恢复原始页面」会取消当前任务并移除译文，让页面回到翻译前的状态。

本地模型如何与浏览器扩展配合

项目由浏览器扩展和本地推理服务两部分组成：

网页中的选文或正文段落
        ↓
Content Script
        ↓
扩展 Background Service Worker
        ↓
TranslationService
        ↓
IndexTranslateProvider
        ↓
本机 llama.cpp 服务
        ↓
Index-Translate-2B GGUF 模型

Content Script 负责识别选中文本、展示浮层和处理页面段落。Background Service Worker 负责发送翻译请求、取消任务和返回结果。模型适配层负责生成提示词，并通过 OpenAI 兼容接口调用 llama.cpp。

项目默认使用 Index-Translate-2B 的 Q4_K_M GGUF 模型。首次启动需要下载模型，后续可以复用本地缓存。原生服务监听 127.0.0.1，Docker 容器端口也只映射到宿主机的 127.0.0.1。

安装与使用

使用项目需要完成两部分部署。

先启动模型服务。macOS 可以运行：

./scripts/setup-macos.sh --port 8000

这个脚本会安装固定版本的 llama.cpp、下载模型并启动服务，优先使用 Metal。macOS 或 Linux 也可以选择 Docker CPU 方式：

K7_TRANS_PORT=8000 docker compose up --build -d

然后构建并安装扩展：

pnpm install
pnpm build

在 Edge 的 edge://extensions 或 Chrome 的 chrome://extensions 中开启开发人员模式，选择「加载解压缩的扩展」，加载项目生成的 dist/ 目录。两个浏览器共用同一份 Manifest V3 构建产物。

默认服务地址为 http://127.0.0.1:8000/v1，模型名为 Index-Translate-2B。设置页提供「保存并测试真实翻译」，可以用一次实际请求检查模型地址、端口和配置是否正确。

K7-Translate 目前更适合有一定开发经验的用户，安装和配置还做不到开箱即用。

模型可以替换，页面逻辑不必跟着改

模型调用被收敛在 TranslationProvider 接口之后，选文和整页逻辑只依赖统一的翻译请求与响应。

默认的 IndexTranslateProvider 通过 OpenAI 兼容协议调用服务。只要其他服务也提供兼容接口，就可以在设置页修改 Base URL、模型名称、API Key 和提示词预设，不需要修改页面代码。

如果服务使用其他协议，可以新增 provider，把协议转换放在适配层内部，再在 ProviderFactory 中注册。页面功能不需要理解不同模型的 API 差异，替换模型时也不用重写选文和整页翻译。

TranslationService 还统一处理超时、取消、短期缓存和错误信息。当前缓存最多保留 100 条翻译结果，原文和译文不会写入扩展的持久化存储；扩展设置则保存在浏览器本地。

自定义服务地址会改变数据流向

按默认配置使用本机 llama.cpp 时，文本会发送到本机服务，翻译过程不依赖第三方在线翻译 API。

项目也允许自定义 OpenAI 兼容服务地址。如果改为远程服务，网页文本就会发送到对应服务。「本地模型翻译」描述的是默认部署方式，实际数据流向取决于用户配置的 Base URL。

本地推理的成本也需要考虑。整页翻译按段调用模型，速度会受到硬件、模型大小、段落数量和并发数影响。默认并发为 2，可以调整为 1 至 4；提高并发会增加内存和计算压力，不一定总能缩短整体时间。

当前版本还有哪些限制

K7-Translate 目前版本为 0.1.0，仍处于较早阶段，主要边界包括：

整页译文采用纯文本渲染，复杂内联链接和富文本格式还不能完整保留。
动态加载的长页面需要在内容出现后重新执行整页翻译。
暂不支持流式输出、图片和音频翻译、术语表及浏览器同步。
edge://、chrome://、扩展商店和独立 PDF 查看器等受保护页面无法使用内容脚本。
Windows 一键安装脚本和 Firefox 适配仍在 TODO 中，Edge 与 Chrome 扩展商店也尚未发布。
翻译质量由实际使用的模型决定，替换为非翻译专用模型时可能需要调整提示词。

项目代码采用 MPL-2.0，模型权重及其使用条件则遵循 Index-Translate 自身许可，两者需要分别确认。

适合哪些用户

如果主要需求是阅读技术文档、希望在本地完成翻译，并且愿意配置 llama.cpp 和浏览器扩展，K7-Translate 提供了一种相对直接的实现。

如果更关注开箱即用、复杂网页格式还原、移动端使用或无需维护的在线服务，当前版本不太合适。

这个项目目前的形态很简单：在浏览器中保留原文阅读体验，同时让选文和整页正文可以使用本地模型翻译。

项目地址：https://github.com/wnz27/K7-Translate