跬步 On Coding

复盘：ClawOps AI Agent

Sat, 07 Mar 2026 12:00:00 +0800

前言

过去的两周，我经历了一次充满激情的开发，也经历了一次彻底的失败。

起因是我准备在内部做一个公共的“运维AI机器人”。我满怀热情地规划了多租户架构、复杂的并发控制、MCP（Model Context Protocol）对接以及各种内部系统的打通。然而，经过两周的爆肝，项目上线没多久就被平台团队勒令下线，而从业务价值来看，老板其实也并不需要这样一个东西。

俗话说，失败是成功之母。虽然项目黄了，但这两周踩过的坑、写过的废代码，都是技术架构演进路上的宝贵经验。我在这里复盘一下整个过程，聊聊我的技术实现、妥协，以及如果让我重新设计，我会怎么做。

1. 雄心勃勃的初始架构

项目初期的定位非常庞大：一个服务于全公司的公共运维Agent平台。为了支撑这个目标，我设计了一套相当复杂的服务端架构。

项目本身基于 PicoClaw。

在这个阶段，我的思维主要停留在“如何用技术解决所有场景的问题”。

多租户与隔离：每个用户拥有独立的Workspace，利用文件系统工具和Shell工具的黑名单机制进行隔离。
高并发的AgentLoop池：为了支持多用户，我设计了一个AgentLoop Worker池。当Inbound Bus收到消息时，自动分配Worker处理；处理完毕后通过Outbound消息池并发调用Channel的发送接口，随后Worker自动回收。
Web Channel的设计：为了让用户能在网页上使用，我做了一个Web Channel。前端通过POST接口发送消息到Inbound Bus，服务端通过SSE（Server-Sent Events）向前端持续推送AI的回复。同时，Tool调用的过程也会产生摘要，通过Hook机制经SSE推送给前端，连会话的Title都是AI自动生成并推送的。
状态与存储：Web会话和消息数据全部落盘MySQL。因为是公共服务，Inbound进入前和Outbound发出后，都需要对接内部认证组件拦截并识别用户，将用户信息注入Message Metadata，最终融合到LLM的System Prompt中。
内部IM（WPS协作）集成：通过WebSocket连接获取内部IM机器人的消息，提取出内部用户信息注入Inbound，再通过平台的发消息API回传给用户。由于共享Metadata，WPS端和Web端可以共用同一个AgentLoop实例和Workspace记忆。

初期架构流转图大概是这样的：

除此之外，我还实现了一个多用户的Cron任务管理服务。系统会遍历每个用户的Workspace，拉起Cron实例。AgentLoop中会记录用户的 last channel，以此决定定时任务的执行结果该推送到Web还是WPS（由于Web没有主动推送能力，还需要做特殊处理屏蔽Web Channel记录）。

2. 核心能力建设与“妥协”

在Agent本体骨架搭好后，下一步就是Skill（技能）的建设。这里我遇到了几个典型的架构决策问题。

WPS 365 MCP的对接与Proxy模式

我们内部使用了WPS 365，它提供了MCP。但是它的MCP使用OAuth2协议，AccessToken只有2小时有效期。如何让AI顺畅调用？我最初的想法是写个Wrapper程序直连数据库刷新Token，但这太不优雅了。最终的妥协方案是：在Web服务上暴露一个WPS MCP Proxy。

调用这个Proxy时携带User ID，Proxy负责去数据库换Token、组装认证请求头，最后转发给WPS。这样一来，AI只需要用普通的 mcptools 配合用户ID就能完成调用。

CMDB对接：CLI vs MCP

在对接内部CMDB平台时，我有了一个洞察：其实MCP并没有那么神圣，面向Agent开发的CLI工具才是未来。因为Agent的Shell Tool结合Skill可以搞定一切CLI的调用，而且极为灵活。

于是我把内部服务直接包成了一个CLI工具给Agent调用，并写了Skill说明文档。但Leader认为，这种能力应该包装成标准的MCP提供给其他生态。

这是一个典型的业务视角与开发视角的冲突。没问题，我把它改成了MCP暴露，但紧接着认证又成了痛点——现阶段做AI工具调用，搞复杂的统一认证太累了，其实最简单的固定Token透传才是效能最高的。

3. 失败的根因与挣扎

项目开发完了，写好了帮助文档，准备大干一场。然后，就迎来了平台团队的审核。

下线。

复盘这个结果，核心死穴在于：Sandbox（沙盒）隔离方案太简陋。

我原本以为，在程序层面做一个Shell命令的黑名单（比如禁用 rm、ssh）就万事大吉了。但我忽略了平台本身网络环境的复杂性。内部平台机器之间的网络是没有严格隔离的。Agent最核心的能力是能够自主编写Skill扩展能力、执行脚本。这意味着无论我怎么在应用层做黑名单，只要Agent能执行Python/Shell，它就能在内网里横冲直撞。要想解决，必须依赖底层平台做深度的容器网络隔离，而这在短时间内根本推不动。

服务端走不通，我不甘心，于是决定转向客户端（桌面版）。

我用Golang的 Wails 框架，花了极短的时间糊了一个和网页端一样的桌面客户端。

Wails甚至能直接Hook之前写的Gin路由。
因为不支持SSE，我把推送机制改造成了Wails自带的Event Bus。
MySQL太重？直接切成SQLite本地存储。
WPS协作只能单实例WebSocket连接？我在服务端保留了一个非常轻量的“消息转发网关”，根据User ID把消息路由到对应打开的客户端上。

技术上走通了，但这次碰到了最终的BOSS——业务价值伪需求。从老板的角度来看，团队并不需要一个新的、复杂的公共Agent平台。能力强的同事早就自己部署了类似的开源项目（比如OpenClaw），而能力稍弱的同事用Cursor就能解决80%的代码和运维问题。

4. 复盘：如果重来，我会怎么设计？

在之前的文章中我提到过，解决问题有不同的思维层次。

我这次的失败，在于我用第一层（用技术解决看到的所有问题）的精力，去挑战了第四层（从组织与平台底座出发看演进）的难题，最终因为基础设施不匹配和伪需求而夭折。

如果让我重新规划这个项目，我绝对不会立项做一个“多租户的企业级公共Agent”。我会将其彻底定位为一个极致轻量化的“个人AI助手（Personal AI Agent）”。

以下是我的重构思路：

1. 抛弃统一认证，拥抱本地配置（Identity）

既然是个人助手，就不要去对接什么内部复杂的SSO认证了。用户的身份定义完全下放。

用户只需要在本地修改自己的 USER.md 文件，明确自己的职责、系统偏好等。对于CMDB这种系统，直接在本地配置里写入私人Token，LLM在调用CLI或MCP时自动拼装读取即可。

2. WPS 365 MCP 授权的本地化改造

不需要服务端的Proxy和数据库。我会开发一个专用的CLI工具。

用户在本地执行CLI生成认证链接，浏览器授权后将Callback的AccessToken及其Refresh Token直接存入本地配置目录（如 ~/.wps/config.json）。之后的Token刷新完全由本地CLI自动完成，Agent直接调用本地工具即可。

3. 极简的Channel消息路由

保留服务端的“消息路由网关”，但不做任何用户认证。

WPS机器人在收到消息后，直接告诉用户他当前的 Chat ID。用户只需在自己本地助手的配置里填入这个 Chat ID。本地助手连上服务端网关的WebSocket，网关只负责无脑地按 Chat ID 转发消息。安全、轻量、解耦。

新的架构图将变得异常清晰且易于维护：

5. 结语

软件开发的过程，本质上是对业务需求进行抽象、提炼并构建逻辑的过程。

这次历时两周的“失败”，虽然没有产出能在公司内部大放异彩的平台产品，但它逼着我理清了Agent在ToB复杂网络下的安全死结，也帮我认清了“大而全的平台”与“小而美的个人工具”之间的边界。

做技术不能一味地追求架构的宏大（什么都想上多租户、Worker池、分布式），最终还是要服务于真实的痛点。现在的个人版架构，虽然看起来像是一个妥协的产物，但它没有了沉重的安全包袱，没有了复杂的数据库依赖，反而能把Agent的核心能力（工具调用、记忆、任务流）发挥到极致。

有时，砍掉一半的需求，反而能得到一个更健壮的架构。这就是我这两周交出的学费。

AI工程落地实践

Wed, 11 Feb 2026 14:00:00 +0800

前几天在整理项目代码的时候，看着 commit log 里那些由 AI 生成的代码，突然有点感慨。以前写代码是体力和脑力的双重劳动，现在好像变成了单纯的脑力博弈——跟 AI 的博弈。

这篇想絮絮叨叨聊一下从传统的开发模式转变为 Vibe Coding 的过程中，我踩过的坑以及现在摸索出来的一套还算顺手的 SOP。

1. 回顾：前AI时代的手工作坊

在那时候，我接一个大需求，流程基本是雷打不动的：

拆解：把大需求掰碎了，变成一个个小任务。
设计：看老代码，定方案。哪里要改，哪里要加，脑子里或者纸上得有个谱。
搬砖：按计划写代码，写单测。
验证：跑通端对端流程。
Code Review：提 PR，等同事挑刺，改代码，合并。

这个过程里，最重要的一步其实往往被忽视，就是复盘。这波开发里学到了什么新模式？引入了什么新坑？怎么避免下次再犯？这种“复利”思维才是工程师成长的关键。

2. Vibe Coding 时代的冲击与适应

进入 AI 时代（或者说 Cursor 时代）后，我一开始也是懵的，试错了很多次，现在的 SOP 变成了这样：

聊需求：先不急着写代码。拉着 ChatGPT 或者 Gemini 开聊。讨论业界怎么做，现在的项目痛点在哪。这一步是为了定方向，最后产出一份靠谱的需求文档。
定计划（feat.md大法）：
- 我会在 Cursor 里建个 feat.md，把需求文档丢进去。
- 在 Cursor 里 @feat.md，让 AI 出 Plan。
- 重点：如果 Plan 太大，我会让它拆。如果 Plan 漏了东西，只要不致命，我先不打断，记在小本本上，等它写完代码再补。
- 有时候 Plan 实在离谱，改动量太大，我会回头改 feat.md，限制它的发挥范围，只做第一阶段。
生成：Plan 只要逻辑通顺，我就让 Cursor 开工。
人工 Review：这一步绝对不能省。我对 AI 的信任度还没到无脑 Merge 的地步，尤其是 E2E 测试覆盖率不够高的时候。我得盯着它生成的代码，脑子里过一遍逻辑。
收尾：测试，合并。

这个流程看着挺顺，但有个大问题：我怎么把“复利”这一环加回来？

之前我看 Spec Driven Development（文档驱动开发），也就是 Speckit 或者 OpenSpec 那一套，试了一下就放弃了。感觉太重了，光是喂给 AI 的上下文就把窗口撑爆了，而且那种从头到尾写文档的感觉，很反直觉，完全没有了快速验证的快感。

直到读到那篇《认知重建：Speckit 用了三个月，我放弃了》，里面提到了复利工程的概念，简直说到我心坎里去了：

Plan ──────→ Work ──────→ Review ──────→ Compound
详细规划     执行工作     质量检查       知识沉淀
   ↑                                       │
   └───────────────────────────────────────┘
            知识复合：下次规划更精准

这不就是我以前手工作坊时代的升级版吗？

3. 在 Cursor 中落地复利工程

理论有了，怎么在 Cursor 里实现？上个月 Cursor 2.4 更新了 SubAgents、Skills 和 Commands，我感觉机会来了。

我先是扒了 everything-claude-code 这个项目，想复刻一套工具链：

Subagent: planner, code-reviewer, doc-updater
Skill: security-review, tdd-workflow
Commands: learn（这个最关键，用于知识沉淀）

理想很丰满，流程应该是 planner -> tdd-guide -> code-reviewer -> learn。

现实很骨感。Cursor 的 SubAgent 经常“自作主张”。你给它编排好了流程，它跑着跑着就切回自己的默认 Plan 模式，或者无视我的 SubAgent 逻辑。那一阵子搞得我很抓狂，感觉在跟一个不听话的实习生较劲。

不过，learn 这个命令我是真留下来了。每次做完需求，把改动总结成知识点存下来，下次 AI 再写代码时，就能读到这些“家规”，确实有用。

4. 最终的折衷方案

不死心的我又去研究了 superpowers 和 code-review-expert 这两个项目，重新调整了策略。

既然 Cursor 对 SubAgent 的调度有自己的想法，那我就顺着它，把流程简化，侧重于前置规划和后置学习。

现在的工具组合变成了：

Skill: brainstorming, writing-plans, executing-plans, test-driven-development, subagent-driven-development, code-review-expert, using-superpowers
Commands: learn (雷打不动)

流程图大概是这样：

brainstorming ──→ writing-plans ──→ executing-plans ──┬──→ test-driven-development
                                                      └──→ code-review-expert ──→ learn

为了适配 Cursor，我把 Claude Code 定义的工具名都改了一遍，还在 Prompt 里强制要求它必须明确调用哪个 Skill。

虽然现在 Cursor 还是偶尔会丢失上下文，或者写着写着断片了，需要我手动把断掉的节点接起来，但整体上，这套流程已经能复刻我以前的工作流了。

总结：

不管 AI 工具有多强，它终究是个工具。不要被工具牵着鼻子走，也不要为了用 AI 而用 AI。

我觉得核心还是要把人的经验沉淀下来。以前我们沉淀在脑子里、Wiki 里，现在我们通过 learn 命令沉淀在本地文档里。

AI 可以帮我们把 Plan -> Work 这一段做得飞快，但 Review -> Compound 这一段，目前还得靠我们自己把关。只有把这个闭环跑通了，才算真正把 AI 用成了自己的副驾驶，而不是请了个随时会跑路的外包。

我的2025

Sun, 04 Jan 2026 10:00:00 +0800

今天是2026年的第一个周日，窗外是珠海特有的温润海风。这一年，我从深圳到珠海，从一家迷茫的小公司到了老牌的金山办公。如果说2024年是本命年的阵痛，那么2025年对我来说，更像是在这激荡的技术浪潮中，努力寻找平衡与自洽的一年。

依然按照惯例，絮絮叨叨地复盘下我的2025吧。

行云创新：及时止损的教训

2025年的开头，我还在行云创新做云原生产品。当时做的是基于 K8s 的在线云 IDE，技术方案其实挺有意思：用 K8s 调度启动在线编辑器，用 code-server 和 selkies 暴露桌面 IDE，甚至还研究了 Docker Windows 容器。为了解决文件同步，我设计了 Sidecar 模式的文件服务，负责上传变更、初始化 git 目录这些活儿。

技术上虽然有成就感，但职场环境却让我第一次深刻体会到“庙小妖风大”。

先是内部莫名其妙的同事纠纷，随后是让人窒息的“服从性测试”。有一次我下班刚到家，就被领导一个电话叫回去值守，其实压根不是我的问题。最崩坏的是关于技术方向的讨论，领导要求我周末加班，把已经验证通过的方案改回到之前被废弃的死路上。我坚持了专业意见，并坦言周末搞不定，结果就是失去了所谓的“信任”。

在小公司，当领导不信任你，却又指望你干活时，事情会变得极其扭曲。他们开始通过能力欠缺的测试同学来传达意见。说实话，和理解能力、沟通能力都不在一个频次的人合作，真的非常痛苦。加上 2B 产品那种“为了投标乱堆定制功能”的短视，我意识到这里看不到未来。

教训很简单：不要对小公司抱有幻觉，更不要在让自己难受的环境里硬磨。 庆幸的是，年底和前同事聊天，发现我走后那里果然陷入了无意义的压榨。及时抽身，是我今年做的最正确的决定之一。

找工作：不匹配就是不匹配

2月过完年，我重新回到了 Boss 直聘的战场。明显的感受是，互联网的盛况确实不再了，坑位少了很多。

期间也面了一些不错的地方。比如一家做家具电商的新加坡公司，离家近，JD 也匹配。结果面试时考缓存一致性，我竟然脑子短路卡壳了，哈哈。还有影石360，面到了三轮，最后败在一道我没刷过的动态规划算法题上。

其实面多了就想通了：面试不过，本质上就是不匹配。 不擅长手写算法是我一直以来的短板，而很多岗位需要的也不是我这种偏工程和架构的背景。最后，我投了广州的唯品会和珠海的金山办公。唯品会方向没对上，而金山办公这边，经过5轮面试定级P7，我重新回到了 SRE 的老本行。

金山办公：双城生活与新的大腿

6月入职金山，刚进去就遇到了一出“大厂政治剧”。我的直接领导是一位从腾讯过来的高P总监，本以为抱到了“鹅厂老乡”的大腿，结果他入职半个月、试用期快过的时候突然离职了。原因是外来的高P动了老员工的利益，被“兄弟文化”排挤。

那一刻我真的很迷茫，简历这两年已经有点花了，要是这儿也待不住怎么办？好在新的 leader 就位后，我渐渐稳住了阵脚。我抛开了之前的屎山代码，开始在组内推广我推崇的“整洁架构”。

现在的状态是，我手下带了2个人，还跨地域带了武汉的2个同事。我把更多精力放在了架构约束上：制定项目规范、拆解需求、帮同事解决技术卡点，努力不让项目走向不可控的混乱。

最明显的变化是生活节奏。金山是真的不加班，早9晚6，非常养人。但我开启了“双城模式”：周一早起驱车去珠海，周五晚回深圳。对家人有愧疚，但下班后大把的独处时间，也让我看了不少以前没空看的电影，算是一种孤独的补偿吧。

Vibe Coding：AI 时代的生存法则

今年我最大的技术冲击来自于 AI。半年多前公司配了 Cursor，我正式开启了 Vibe Coding 模式。现在的流程是：我负责思考方案，写好文档，然后跟 AI 讨论可行性。

我的工具链目前是这样的：

Google AI Studio (Gemini 3 Pro)：负责宏观架构，它上下文大，适合讨论长篇的实施计划。
Cursor (Claude Sonnet 4.5)：负责写代码，又快又好。
GPT-5.1 Codex High：负责 Review，它能抓到很多我忽略的边界细节。

读代码也有了神器，deepwiki.com 理解大框架，gitingest.com 配合 Gemini 3 Pro 读仓库源码。在 Vibe Coding 时代，我发现程序员的“品味”变得空前重要。AI 会发散，如果没有严格的架构约束和清晰的规范，AI 产出的代码大概率也是一堆难以维护的屎山。

开源与折腾

有了闲暇时间，开源项目也搞得风生水起。

Pingsix：写了20多个插件，被 GPT-5.1 捉了十几个虫，解锁了Ingress Controller。
Bookmark：趁着 Pocket 关闭，我把老书签整理了，顺便用 AI 做了自动化总结。
NAS：家里的 RK3399 还在服役，换了 SSD，折腾了联通 IPv6。现在结合夸克网盘和 TG 机器人，追剧已经成了全自动的享受。

甚至我还精简了银行卡，把一堆乱七八糟的卡消了。现在主刷农行精粹白和工行香格里拉白。理财归微众，工资归招行，生活变得简单了不少。

结尾

2025年，我在珠海的夕阳里思考过职业危机，也在双城的高速上想念过家人。虽然简历看上去不再那么“大厂精英”，但我对编程的热爱反而因为 AI 的介入变得更纯粹了——我不再纠结于繁琐的语法，而是更专注于解决问题本身。

未来依然不确定，但就像我折腾 OpenWrt 拨号一样，掉线了就重新拨号，断路了就换个方案。只要逻辑还在，系统总能 Run 起来。

再见，2025。你好，2026。

AI Agent 工程化实践：从 Prompt 到 Context 的思维转变

Sun, 30 Nov 2025 10:00:00 +0800

最近在新公司这边，大部分精力都耗在了 AI Agent 的落地应用上。大家都在谈 Agent，网上的 Demo 也是满天飞，但当你真正把这玩意儿往生产环境搬的时候，会发现完全是两码事。

简单的说，AI Agent 的核心逻辑其实并不复杂，本质上就是一个基于 ReAct（Reasoning and Acting）范式的工程结构，程序在一个死循环里不断地调用 LLM 的 API，让它根据当前的观测去决策下一步是思考还是行动。

起初我也觉得这就跟写个脚本差不多，但在实际调试过程中，我发现让 Agent “跑通”不难，但要让它“跑好”、“省钱”且“不犯蠢”，这里面全是工程细节。我也复盘了一下这段时间的踩坑经历，总结了一些在工程实践中的“巧思”。

遇到的瓶颈

在项目初期，我碰到的最大痛点就是 Token 的消耗 和 上下文窗口（Context Window）的限制。

Agent 运行起来后，为了保证它能记住之前的操作，我们往往会把历史对话一股脑地塞进 Prompt 里。但随着交互轮数的增加，上下文会迅速膨胀。这不仅烧钱（Token 费很贵），更要命的是，当无关信息太多时，LLM 的注意力会被稀释，导致它开始“幻觉”或者逻辑混乱，也就是我们常说的“变笨了”。

为了解决这个问题，我开始从工程角度去干预 Agent 的记忆机制，我发现单纯的 Prompt Engineering 已经不够用了，我们需要进阶到 Context Engineering（上下文工程）。

几个工程化的巧思

针对上下文过载和执行效率低的问题，我在工程实践中尝试了以下几个优化策略，效果还不错：

1. 动态整理与压缩上下文

这招主要是应对“记不住”的问题。当对话轮数逼近模型的 Context 上限时，如果直接截断最早的记录，Agent 可能会丢失关键的任务背景。

我的做法是，在检测到 Token 数快到阈值时，触发一个后台任务，让 LLM 自己对之前的多轮对话做一个动态整理（Summary）。

输入：过去 N 轮的详细对话。
输出：提取出“用户的核心诉求”、“已完成的关键步骤”和“当前获得的中间结果”。

用这段高密度的摘要替换掉那 N 轮冗长的对话。这样既大幅减少了 Token 量，又确保了历史关键信息得以保存，让 Agent 始终记得“我是谁，我在哪，我要干什么”。

2. Checkpoint 回溯与有效信息保留

Agent 在尝试调用工具时，并不总是成功的。有时候它参数传错了，有时候 API 报错了。在标准的 ReAct 循环里，这些报错信息（Error Logs）会被完整地记录在上下文里。

这就导致一个问题：如果 Agent 试错了好几次才成功，那上下文里会充斥着大量的垃圾报错信息。这些信息对于后续的决策不仅无用，反而可能误导模型。

这里我引入了一个类似游戏存档的 Checkpoint（检查点） 机制。

在执行关键动作前，系统会自动保存当前的上下文快照。
当检测到 Agent 陷入死循环或产生大量无效交互时，系统会强制回滚到上一个 Checkpoint。
关键点：回溯不是简单的“读档重来”，我们会通过规则提取出刚才试错过程中产生的“有效信息”（比如“某个参数验证失败”的结论），将其注入到回溯后的上下文中。

这样既清洗了上下文中的噪音，又保留了试错的价值，避免 Agent 在同一个坑里跌倒两次。

3. Sub Agent 解决上下文隔离

在某些场景下，Agent 需要执行非常复杂的子任务，比如写一段 Python 代码并执行，或者进行复杂的数据清洗。

如果把这些子任务的所有中间步骤都塞进主线程的上下文（Main Context），瞬间就会把 Token 撑爆。我的解决思路是引入 Sub Agent（子智能体）：

把复杂任务分发给一个独立的 Sub Agent。
Sub Agent 拥有独立的上下文空间，它可以在里面进行多轮的思考、调试、修正。
当 Sub Agent 任务完成后，只提取“最终结果”返回给主 Agent。

通过这种方式，我们实现了上下文的物理隔离，主 Agent 的视野始终保持清爽，只关注宏观流程，而细节则由 Sub Agent 屏蔽。

4. 面向“人”设计工具，而非面向 API

这一点是我觉得思维层次提升最大的地方。

最初给 Agent 设计工具时，我习惯直接把后端的原子 API 扔给它，比如 login(), get_token(), get_user_info()。结果就是 Agent 完成一个简单的查用户信息，需要来回跑三趟。

后来我意识到，Agent 使用工具的逻辑应该更像“人”使用 app。工具的设计粒度应该更粗。我们将多个原子 API 组合封装成一个面向业务场景的高阶工具。这样一次调用就能搞定，减少了 Agent 的交互流程，容错率也大大提升。

总结：从 Prompt 到 Context

回顾这些优化点，我们可以发现，提升 Agent 能力的关键，不仅仅在于你 Prompt 写得有多花哨，更在于你如何管理它所能看到的“世界”。

让我们来总结下这里的思维层次：

第一层（Prompt Engineering）：专注于怎么把 Prompt 词写好，试图用一段话把所有要求都告诉 AI。
第二层（RAG / Memory）：开始给 AI 外挂数据库，解决知识库的问题。
第三层（Context Engineering）：把上下文看作一种稀缺的计算资源，通过动态压缩、Checkpoint 回溯、Sub Agent 隔离等工程手段，动态地管理 AI 的注意力。
第四层（Architecture Design）：从单点优化走向系统设计，构建一套具备自我纠错、状态管理、分层协作的智能体运行时环境。

以前做传统开发，我们优化的是 CPU 和内存；现在做 AI 开发，我们优化的其实是 Context Window 和 Token 效率。

在这个技术日新月异的时代，作为程序员，我们不仅要会写代码，更要学会如何设计系统来弥补模型的短板。这些关于 Context 的巧思，其实就是把复杂的非结构化问题，通过工程手段变得有序化的过程。

希望这些瞎絮叨的经验能对正在折腾 Agent 的你有那么一点点启发。2025 年了，保持学习，保持思考，依然是应对变化的唯一解法。

系统性思维的陷阱：从“完美方案”到“有效落地”

Fri, 21 Nov 2025 10:00:52 +0800

我做程序员已经 10 多年了。

回想刚入行那会儿，我的思维模式很简单：产品经理提什么，我就做什么。那时候追求的是“短平快”，像个执行指令的机器，代码写得快就是牛。

后来加入了腾讯，随着职级的提升，负责的系统越来越复杂，我开始意识到：写代码只是冰山一角，做方案才是真正的考验。

所谓的“系统性思维”，一度让我受益匪浅，但最近我发现，如果一旦陷入对“完美”的执念，系统性思维反而会成为阻碍项目落地的最大陷阱。今天想和大家聊聊，如何在架构设计、风险控制和实际落地之间找到那个微妙的平衡点。

方案的本质：平衡客观条件的艺术

什么是做方案？以前我觉得是画一张最漂亮的架构图，用最牛的组件。现在我理解，做方案其实是把各种“客观条件”作为输入，寻找最优解的过程。

这些客观条件包括：

硬件资源：手头有多少服务器？
依赖组件：公司基建支持什么？（比如你想用 ClickHouse，但公司运维没经验，出了问题没人兜底，那这就不是一个好选项，不如看看现有组件能不能替代。）
人力成本：团队几个人？水平如何？
时间窗口：业务等得起多久？

我见过很多“完美”的方案，逻辑自洽，架构优雅，但落地需要半年。而另一个方案虽然略显粗糙，但只需要 1 个月，且预留了后续演进的空间。在商业世界里，后者往往才是胜者。

架构不是设计出来的，是演进出来的。 我们需要做的是调整各种客观条件的优先级，在风险可控的前提下，通过多方评审（集思广益，消除盲区），找到那个平衡点。

实战案例：只解决 80% 的问题

分享一个我在腾讯做权限中心时的真实案例。

当时我们面临一个痛点：有一个中心化的管理员，每天大量时间都在处理审批单，他一直在吐槽，希望把这些审批自动路由到对应的业务负责人，别全堆在他头上。

我第一反应是：做不到。

从技术角度看，审批范围是一个复杂的表达式。要根据用户申请的数据去匹配这个表达式，没法直接做数据库索引。如果要实现，就得全表扫描进行遍历匹配，性能扛不住。而且，很多申请范围很模糊，根本匹配不到具体负责人，最后还是得兜底回落到管理员那里。

于是这个需求被我挡回去了。后来问题太严重，捅到了上面。在复盘会上，我的 Leader 问了一句话，让我瞬间顿悟：

“能不能在只解决 80% 问题的前提下，来做这个方案？”

我突然意识到，我陷入了“完美主义”的陷阱。我一直在纠结那 20% 匹配不到的情况，却忽略了如果能自动化处理掉 80% 的单子，管理员的工作量就能大大减轻。

于是我重新设计了方案：

引入前置索引：提取表达式中的关键特征做索引。
允许降级：能走索引匹配的先走索引，匹配不到的（那复杂的 20%），直接回退给中心管理员。

事实证明，方案落地后，管理员的压力骤减。这就告诉我：有时候真的没有完美的方案，只有平衡现状的方案。

开源代码的“神话”与重构

在阅读优秀开源项目代码时，我常有这种时刻：“哇塞，这代码写得太神了，连这种极端场景都想到了，作者是开了天眼吗？”

随着我自己经验的增长，我发现所谓的“神人”并没有那么玄乎。

他能考虑到那个场景，很可能只是因为他踩过那个坑。

版本 1.0 可能是个草台班子。
版本 2.0 修复了几个致命 Bug（踩坑）。
版本 3.0 因为补丁打多了，代码太烂，被迫重构，把之前的坑变成了新的设计约束。

我在腾讯的 6 年里，权限中心整体重构过 3 次，API 网关也重构过 3 次。每一次重构，都是因为旧的方案无法适应新的客观条件。

踩坑并不是坏事，失败也是财富。 那些让你绞尽脑汁都想不到的 Edge Case，往往是别人血淋淋的经验积累。我们在做方案时，不要怕现在的方案未来会被推翻，只要预留了演进空间，现在的“不完美”就是未来能力的基石。

警惕“过度系统化”的僵局

我现在所在的公司，领导层是运维出身。运维思维和研发思维有一个本质的区别：运维天然厌恶风险（Risk Averse），而研发需要管理风险。

这就导致了一个尴尬的局面：我提出了方案 A 来解决问题 A，但在评审会上，领导会挑战：“你这个方案没有解决问题 B 怎么办？有没有风险？”

于是，技术评审会变成了“挑刺大会”。

为了应对领导的挑刺，我们被迫把方案搞得越来越复杂，试图覆盖所有角落。
方案一复杂，落地难度就指数级上升。
最终结果是：动作变形，无法落地，不了了之。

组内甚至有同事因为方案迟迟推不动，最后无奈活水走人。

这种过度系统化的思考方式，实际上是一种停滞。领导当然需要系统性思考，但如果一直纠结于“一步到位”的完美方案，就会导致方案根本不具备可行性。

我的应对策略：最小化闭环

面对这种环境，如果硬刚，很容易陷入内耗。我的应对方法是：MVP（Minimum Viable Product）策略 + 工具提效。

把方案切得足够小：不要试图画一张大饼，而是聚焦当前最核心的痛点。
快速跑通 PoC（概念验证）：与其在会议室争论风险，不如直接把代码跑起来，让领导看到可视化的成果。
利用 AI 提效：为了不让自己太累，我现在大量使用 AI 编程工具。它可以帮我快速生成原型代码，大大缩短从“想法”到“演示”的时间。

虽然这样做确实会累一点（因为要先斩后奏，自己承担一部分验证成本），但在“不做不错”和“艰难推进”之间，我选择后者。

写在最后

系统性思维是好东西，它让我们思考得更全面。但我们不能让系统性思维成为阻碍系统发展的借口。

做方案，本质上是在不确定性中寻找确定性。

既要有思维高度，也要有“先解决当下问题”的务实态度。不要害怕方案不完美，只要控制好风险，让系统转起来，剩下的，交给时间去演进。

pingsix-ingress-controller启动

Mon, 20 Oct 2025 10:00:52 +0800

https://github.com/zhu327/pingsix

PingSIX 自从上次重构之后, 我一直在考虑如何扩展这个项目的功能与使用场景, 有2个方向可以考虑:

支持proxy-wasm插件
实现pingsix-ingress-controller

在调研了proxy-wasm的相关功能后, 结论是由于pingora面向的场景是CDN的反向代理, 所以没有考虑过方便的修改请求体与响应体, 这就造成很难基于pingora来实现proxy-wasm的ABI, 如果我要自己定义一个wasm的接口协议, 没法复用社区现有的proxy-wasm插件, 那就没必要了, 不如直接写Rust的插件. 相关参考内容:

在放弃了proxy-wasm的支持后, 我开始调研如何实现pingsix-ingress-controller, 由于pingsix的的资源定义是参考apisix来实现的, 所以就直接参考apisix-ingress-controller来实现我们自己的pingsix-ingress-controller.

1. apisix-ingress-controller架构

1. K8s Resources Watch Layer (资源监听层)

各种Controller通过Kubernetes的Watch机制监听对应的资源变化
支持的资源类型包括：
- Gateway API: HTTPRoute, Gateway, GRPCRoute, TCPRoute, UDPRoute, TLSRoute
- Kubernetes原生: Ingress, IngressClass
- APISIX CRD: ApisixRoute, ApisixGlobalRule, ApisixTls, ApisixConsumer, ApisixUpstream
- 自定义: Consumer, GatewayProxy

2. Provider Layer (提供者层)

Provider接收Controller的Update/Delete请求
TranslateContext收集所有依赖资源（Services, Secrets, EndpointSlices等）
为Translator提供完整的上下文信息

3. Translator Layer (翻译层)

将K8s资源翻译成ADC资源描述
每种资源类型都有对应的Translator方法
输出TranslateResult，包含：
- Services (路由规则)
- SSL/TLS (证书)
- Consumers (消费者)
- GlobalRules (全局规则)
- PluginMetadata (插件元数据)

4. ADC Client Layer (ADC客户端层)

ConfigManager: 管理多个GatewayProxy的配置
Store/MemDB: 内存数据库，存储ADC资源状态
StoreDelta: 对比新旧配置，计算差异
将变更任务传递给Executor执行

5. ADC Executor Interface (执行器接口)

ADC Executor提供统一的Execute接口，支持三种实现：

HTTPADCExecutor: 通过HTTP调用ADC Server（推荐方式）
DefaultADCExecutor: 通过命令行调用adc命令

6. ADC HTTP Server (ADC HTTP服务器)

ADC HTTP Server的核心流程：

接收/sync端点的PUT请求
解析ADCServerRequest（包含opts和config）
根据label-selector从APISIX拉取现有资源
将ADC资源描述转换为APISIX资源格式
对比已拉取的资源，计算差异（Diff）
调用APISIX Admin API执行创建/更新/删除操作
返回SyncResult（包含成功/失败状态）

7. APISIX Data Plane (APISIX数据平面)

最终在APISIX中创建/更新/删除的资源：

Routes (路由)
Services (服务)
Upstreams (上游)
SSL/TLS (证书)
Consumers (消费者)
Global Rules (全局规则)
Plugin Metadata (插件元数据)

8. 核心特性

多GatewayProxy支持: 通过ConfigManager管理多个APISIX实例的配置
Label Selector: 支持通过标签选择器过滤资源
增量同步: 通过MemDB对比差异，只同步变更的资源
错误处理: 完善的错误收集和状态更新机制
灵活的执行方式: 支持HTTP、命令行多种执行模式
资源隔离: 通过label实现不同资源的隔离和管理

2. apisix-ingress-controller的经验

虽然以前也写过一些operator的代码, 但是在学习apisix-ingress-controller代码的过程中, 我还是学到了一些新的东西, 在controller watch一类资源的时候, 我们可以watch所有关联的资源类型, 一旦这些关联的资源类型有变更, 就可以进入统一的变更流程, 这样就减少了我们写controller的逻辑复杂度, 所有的关联资源的变更都会触发主资源的更新.

// SetupWithManager sets up the controller with the Manager.
func (r *IngressReconciler) SetupWithManager(mgr ctrl.Manager) error {
	r.genericEvent = make(chan event.GenericEvent, 100)

	return ctrl.NewControllerManagedBy(mgr).
		For(&networkingv1.Ingress{},
			builder.WithPredicates(
				MatchesIngressClassPredicate(r.Client, r.Log),
			),
		).
		WithEventFilter(
			predicate.Or(
				predicate.GenerationChangedPredicate{},
				predicate.AnnotationChangedPredicate{},
				predicate.NewPredicateFuncs(TypePredicate[*corev1.Secret]()),
			),
		).
		Watches(
			&networkingv1.IngressClass{},
			handler.EnqueueRequestsFromMapFunc(r.listIngressForIngressClass),
			builder.WithPredicates(
				predicate.NewPredicateFuncs(r.matchesIngressController),
			),
		).
		Watches(
			&discoveryv1.EndpointSlice{},
			handler.EnqueueRequestsFromMapFunc(r.listIngressesByService),
		).
		Watches(
			&corev1.Secret{},
			handler.EnqueueRequestsFromMapFunc(r.listIngressesBySecret),
		).
		Watches(&v1alpha1.BackendTrafficPolicy{},
			handler.EnqueueRequestsFromMapFunc(r.listIngressForBackendTrafficPolicy),
			builder.WithPredicates(
				BackendTrafficPolicyPredicateFunc(r.genericEvent),
			),
		).
		Watches(&v1alpha1.HTTPRoutePolicy{},
			handler.EnqueueRequestsFromMapFunc(r.listIngressesByHTTPRoutePolicy),
			builder.WithPredicates(httpRoutePolicyPredicateFuncs(r.genericEvent)),
		).
		Watches(&v1alpha1.GatewayProxy{},
			handler.EnqueueRequestsFromMapFunc(r.listIngressesForGatewayProxy),
		).
		WatchesRawSource(
			source.Channel(
				r.genericEvent,
				handler.EnqueueRequestsFromMapFunc(r.listIngressForGenericEvent),
			),
		).
		Complete(r)
}

IngressReconciler Watch 事件详解

根据代码分析，IngressReconciler 在 SetupWithManager 方法中配置了多个 watch 事件。让我为您详细解释每个事件的作用和逻辑：

1. 主资源 Watch - Ingress (第70-81行)

For(&networkingv1.Ingress{}, builder.WithPredicates(
    MatchesIngressClassPredicate(r.Client, r.Log),
))

作用：监听 Ingress 资源本身的变化

Predicates（过滤条件）：

MatchesIngressClassPredicate: 只处理由当前控制器管理的 IngressClass 的 Ingress
GenerationChangedPredicate: 资源的 Generation 发生变化（spec 修改）
AnnotationChangedPredicate: 注解发生变化
TypePredicate[*corev1.Secret](): 用于 Secret 类型判断

逻辑：这是主要的监听对象，当 Ingress 的规格或注解变化时触发 Reconcile

2. IngressClass Watch (第82-88行)

Watches(
    &networkingv1.IngressClass{},
    handler.EnqueueRequestsFromMapFunc(r.listIngressForIngressClass),
    builder.WithPredicates(
        predicate.NewPredicateFuncs(r.matchesIngressController),
    ),
)

作用：监听 IngressClass 资源的变化

触发条件：

matchesIngressController: 只监听由当前控制器管理的 IngressClass（通过 spec.controller 字段匹配）

逻辑 (listIngressForIngressClass)：

检查 IngressClass 是否是默认类（通过注解 ingressclass.kubernetes.io/is-default-class）
如果是默认类：列出所有未指定 IngressClassName 或指定为该类的 Ingress
如果不是默认类：通过索引查找使用该 IngressClass 的所有 Ingress
返回需要 reconcile 的 Ingress 列表

使用场景：当 IngressClass 的配置变化时，需要重新处理所有使用该类的 Ingress

3. EndpointSlice Watch (第89-92行)

Watches(
    &discoveryv1.EndpointSlice{},
    handler.EnqueueRequestsFromMapFunc(r.listIngressesByService),
)

作用：监听后端服务的 Endpoint 变化

逻辑 (listIngressesByService)：

从 EndpointSlice 的 label 中提取 Service 名称（discovery.k8s.io/service-name）
通过索引 ServiceIndexRef 查找引用该 Service 的所有 Ingress
过滤出由当前控制器管理的 Ingress
返回需要 reconcile 的 Ingress 列表

使用场景：当后端 Pod 的 IP 地址变化（扩缩容、重启等）时，需要更新 APISIX 的 upstream 配置

4. Secret Watch (第93-96行)

Watches(
    &corev1.Secret{},
    handler.EnqueueRequestsFromMapFunc(r.listIngressesBySecret),
)

作用：监听 TLS 证书 Secret 的变化

逻辑 (listIngressesBySecret)：

通过索引 SecretIndexRef 查找直接引用该 Secret 的 Ingress（TLS 配置）
查找引用该 Secret 的 GatewayProxy（用于 provider 认证）
如果 GatewayProxy 引用了该 Secret，找到使用该 GatewayProxy 的 IngressClass
再找到使用这些 IngressClass 的所有 Ingress
去重后返回所有需要 reconcile 的 Ingress

使用场景：

TLS 证书更新或轮换
GatewayProxy 的 AdminKey Secret 变化

5. BackendTrafficPolicy Watch (第97-102行)

Watches(&v1alpha1.BackendTrafficPolicy{},
    handler.EnqueueRequestsFromMapFunc(r.listIngressForBackendTrafficPolicy),
    builder.WithPredicates(
        BackendTrafficPolicyPredicateFunc(r.genericEvent),
    ),
)

作用：监听后端流量策略的变化

Predicates 逻辑：

Create: 返回 true，新建时触发
Delete: 返回 true，删除时触发
Update: 检测 targetRefs 的变化
- 找出被移除的 targetRefs
- 将包含被移除 targetRefs 的旧对象发送到 genericEvent channel
- 这样可以清理不再被引用的资源

逻辑 (listIngressForBackendTrafficPolicy)：

遍历 Policy 的所有 targetRefs（引用的 Service）
通过索引查找使用这些 Service 的 Ingress
去重后返回需要 reconcile 的 Ingress 列表

使用场景：配置后端流量策略（如负载均衡算法、健康检查等）

6. HTTPRoutePolicy Watch (第103-106行)

Watches(&v1alpha1.HTTPRoutePolicy{},
    handler.EnqueueRequestsFromMapFunc(r.listIngressesByHTTPRoutePolicy),
    builder.WithPredicates(httpRoutePolicyPredicateFuncs(r.genericEvent)),
)

作用：监听 HTTP 路由策略的变化

Predicates 逻辑：

Create/Delete: 返回 true
Update: 检测 targetRefs 的变化
- 找出被移除的 targetRefs
- 将包含被移除 targetRefs 的旧对象发送到 genericEvent channel

逻辑 (listIngressesByHTTPRoutePolicy)：

遍历 Policy 的所有 targetRefs
过滤出 Kind 为 Ingress 的引用
获取这些 Ingress 对象
返回需要 reconcile 的 Ingress 列表

使用场景：配置 HTTP 路由级别的策略（如重写、重定向、超时等）

7. GatewayProxy Watch (第107-109行)

Watches(&v1alpha1.GatewayProxy{},
    handler.EnqueueRequestsFromMapFunc(r.listIngressesForGatewayProxy),
)

作用：监听 GatewayProxy 配置的变化

逻辑 (listIngressesForGatewayProxy -> listIngressClassRequestsForGatewayProxy)：

通过索引 IngressClassParametersRef 查找引用该 GatewayProxy 的 IngressClass
对每个 IngressClass，调用 listIngressForIngressClass 获取相关 Ingress
去重后返回所有需要 reconcile 的 Ingress

使用场景：

GatewayProxy 的 APISIX 地址变化
发布服务配置变化
Provider 配置变化

8. Generic Event Channel (第110-116行)

WatchesRawSource(
    source.Channel(
        r.genericEvent,
        handler.EnqueueRequestsFromMapFunc(r.listIngressForGenericEvent),
    ),
)

作用：处理通过 channel 发送的自定义事件

逻辑 (listIngressForGenericEvent)：

根据对象类型路由到相应的处理函数：
- BackendTrafficPolicy -> listIngressForBackendTrafficPolicy
- HTTPRoutePolicy -> listIngressesByHTTPRoutePolicy

使用场景：

处理 Policy 的 targetRefs 被移除时的清理工作
确保当资源不再被引用时，能正确更新相关配置

整体工作流程

1. 事件触发 → 2. Predicate 过滤 → 3. MapFunc 映射 → 4. Reconcile 队列 → 5. Reconcile 执行

Reconcile 主要步骤：

获取 Ingress 对象：如果不存在则执行删除逻辑
查找 IngressClass：确定配置来源
处理 IngressClass Parameters：加载 GatewayProxy 配置
处理 TLS：加载证书 Secret
处理 Backends：加载 Service 和 EndpointSlice
处理 HTTPRoutePolicy：应用路由策略
处理 BackendTrafficPolicy：应用后端流量策略
更新 APISIX 配置：通过 Provider 同步到 APISIX
更新状态：更新 Ingress 和相关资源的状态

关键设计特点

索引优化：使用 Field Indexer 快速查找资源关系
级联更新：依赖资源变化时自动触发主资源更新
去重机制：避免重复处理同一个 Ingress
事件通道：使用 genericEvent channel 处理复杂的清理场景
条件过滤：通过 Predicate 减少不必要的 Reconcile

indexer性能优化

可以看到在上面的watch逻辑中有很多的list操作, 比如listIngressForBackendTrafficPolicy, 这个时候就需要事先在k8s client的indexer中建立索引来优化查询速度, 避免list全扫数据:

func setupIngressIndexer(mgr ctrl.Manager) error {
	// create IngressClass index
	if err := mgr.GetFieldIndexer().IndexField(
		context.Background(),
		&networkingv1.Ingress{},
		IngressClassRef,
		IngressClassRefIndexFunc,
	); err != nil {
		return err
	}

	// create Service index for quick lookup of Ingresses using specific services
	if err := mgr.GetFieldIndexer().IndexField(
		context.Background(),
		&networkingv1.Ingress{},
		ServiceIndexRef,
		IngressServiceIndexFunc,
	); err != nil {
		return err
	}

	// create secret index for TLS
	if err := mgr.GetFieldIndexer().IndexField(
		context.Background(),
		&networkingv1.Ingress{},
		SecretIndexRef,
		IngressSecretIndexFunc,
	); err != nil {
		return err
	}

	if err := mgr.GetFieldIndexer().IndexField(
		context.Background(),
		&networkingv1.Ingress{},
		TLSHostIndexRef,
		IngressTLSHostIndexFunc,
	); err != nil {
		return err
	}

	return nil
}

📊 索引概览表

索引名称	索引字段	索引函数	主要用途
IngressClassRef	`ingressClassRef`	`IngressClassRefIndexFunc`	根据 IngressClass 查找 Ingress
ServiceIndexRef	`serviceRefs`	`IngressServiceIndexFunc`	根据后端 Service 查找 Ingress
SecretIndexRef	`secretRefs`	`IngressSecretIndexFunc`	根据 TLS Secret 查找 Ingress
TLSHostIndexRef	`tlsHostRefs`	`IngressTLSHostIndexFunc`	根据 TLS 主机名查找 Ingress

Ingress 的 4 个索引形成了一个完整的查询体系：

IngressClassRef：管理层面 - 按控制器分组
ServiceIndexRef：数据平面 - 后端服务关联
SecretIndexRef：安全层面 - TLS 证书管理
TLSHostIndexRef：域名层面 - SSL 配置管理

这些索引确保了当任何依赖资源变化时，控制器都能快速、准确地找到需要更新的 Ingress，实现高效的级联更新和实时配置同步。

3. pingsix-ingress-controller架构决策

从apisix-ingress-controller的架构中, 我们知道apisix抽象了一种ADC(API Declarative CLI)的资源类型用来在ingress与apisix资源之间作为中间的桥梁, 如果直接使用apisix-ingress-controller来对接pingsix的话, 就需要pingsix完整的实现apisix的admin api, 并且还需要在使用时启动etcd.

在我的印象中曾经看到过apisix-ingress-controller实现过一个不需要etcd的方案:

Embrace the Lightweight APISIX Ingress Controller Without etcd Dependency

然后我在apisix-ingress-controller 1.8.x 版本的代码下找到了这个这个实现方式, 只是当前的 2.0.x 版本在引入了ADC相关的功能后去掉了etcd-adapter, 那我在考虑实现我的pingsix-ingress-controller时, 为了避免直接改动pingsix的代码, 并且也不希望在ingress启动时依赖etcd, 所以决定重新引入etcd-adapter, 然后为了后续pingsix-ingress-controller能同步apisix-ingress-controller的上游更新, 我决定在现有的ADC Executor的接口的基础上, 实现pingsix的Executor, 这样就可以在避免直接修改apisix的逻辑代码, 使用一种adapter的方式来实现我们自己的pingsix-ingress-controller.

可以看到我们实现的这个Executor, 其实就是重复了一遍ADC http serve的逻辑, 但是最终资源的数据是写入到etcd-adapter中的, 我们实现了一个apisix-ingress-controller最底层的抽象, 通过这种低成本的改造我们后续还可以继续同步apisix-ingress-controller的变更, 并不会造成代码冲突.

总结

在实现pingsix-ingress-controller的过程中, 我完整的阅读了apisix-ingress-controller的代码, 收获了一些写operator的技巧, 然后在分析现有apisix-ingress-controller的代码架构时, 决定通过扩展ADC Executor的实现来实践了面向对象的开闭原则, 对于后续的代码更新合并开了一个好头.

编写可维护的代码 -- 面向AI编程

Thu, 16 Oct 2025 10:00:52 +0800

这是最近在小组内做的一次技术分享的文字稿，总体来说我觉得没有表达出特别硬核的内容，我本身也希望说这次分享不用讲的太硬核，在分享的开头还设计了互动环节，分享的过程中也尝试加入一些问答来互动，奈何现公司的技术氛围确实比较沉闷，似乎同事都比较I，好在最后的问答环节有几个比较好的问题，总体来说还算是一次成功的分享吧，希望自己能输出更多的好内容。

P1: 我们写的代码是写给谁看的?

(🎤 互动环节): “大家有没有过接手一个项目时，看到的第一感觉是：我该从哪下手？结果花了三天才搞明白一个功能的逻辑。有过类似经历的兄弟举个手我看看？”
小说家写小说给读者，建筑师盖房子给业主… 那我们程序员写代码，最终是写给未来的自己，和接手我们代码的同事看的。
代码的可维护性，决定了我们是在“创造价值”还是在“创造负债”。

P2: 举几个代码坏味道的例子?

(🎤 互动环节): “看过《重构》的同学应该都知道代码坏味道。来，大家一起吐槽一下，你在项目里见过最痛苦的代码坏味道是什么？” (引导大家说出几个)
其实按照我朴素的理解，能让我快速理清逻辑的就是好代码，理解起来很费劲的，那肯定就充满坏味道。
正如我在入职后接手的kitam项目，它就充满了这些味道：
- 代码逻辑不内聚：功能实现像天女散花。
- 分层过多且混乱：一个请求要穿越重重关卡。
- 外部依赖离散：数据库、缓存的调用没有统一规范。

P3: 今天分享的主题

今天分享的主题是编写可维护的代码，以及我们可探讨下面向AI编程。
面对代码的坏味道和混乱，我们有什么良药？—— 答案是：一个好的架构。今天我将分享我们kfinops项目中使用的架构：整洁架构 (Clean Architecture)。

P4: 我们的敌人是谁？——是“耦合”这头怪兽！

(🖼️ 视觉元素占位符: 此处放置一张生动的图片，比如一个身上贴满“耦合”标签的小怪兽 🐲)
在深入架构之前，我们先要认清我们真正的敌人：耦合 (Coupling)。
什么是耦合？当你修改代码的一个地方，却意外地导致另一个看似无关的地方也必须修改，甚至直接崩溃时，你就遇到了耦合。
整洁架构的核心目标只有一个：斩断不必要的耦合，为我们的代码建立“防火墙”，控制变更的“爆炸半径”。
接下来，我会通过4个我们都经历过的惨痛问题，来展示整洁架构是如何一步步帮我们驯服这头怪兽的。
(🖼️ 视觉元素占位符: 此处展示完整的整洁架构“洋葱图”，并快速解释四个环：Entities -> Use Cases -> Adapters -> Frameworks)

P5: 问题一：“我只想改个业务规则，为什么还要动数据库和API的代码？”

(🖼️ 视觉元素占位符: 洋葱图高亮最内层的 “Entities” 环)
痛点场景： 你想修改一个实体（比如 User）的业务规则。但在很多项目中，这个实体被定义成了一个“万能Struct”：
```
// user.go
// 它既是业务实体，又是GORM模型，还是HTTP响应体
type User struct {
    ID        uint      `json:"id" gorm:"primaryKey"` // <-- 高亮此行
    Name      string    `json:"name" gorm:"size:255"`
    Points    int       `json:"points"`
    // ...
}
```
- 现在，产品说：为了兼容新App，ID 字段对外要改成 user_id。
- 你只能修改：ID uint \json:“user_id” gorm:“primaryKey”``。
- 问题来了： 你只是在修改一个前端展示字段的名称，却迫使你修改了一个核心业务实体（User）的文件。这就是业务逻辑和展示细节的耦合。
解药：一个纯净的【领域层 Domain Layer】
- 它的唯一职责：建立一个“无菌室”，只存放最核心、最纯粹的业务实体和业务规则。
- kfinops 的实践:
```
// internal/domain/subdomain.go
// 只有业务属性，没有json，gorm等任何技术标签
type SubDomain struct {
    ID         string // 纯粹的业务ID
    FullDomain string
    Status     SubDomainStatus
}
```
- 效果： 业务核心完全稳定。前端/数据库的任何变化，都不会触碰到这个文件。

P6: 问题二：“‘创建子域名’这个功能，代码到底在哪？”

(🖼️ 视觉元素占位符: 洋葱图高亮第二层的 “Use Cases” 环)
(🎤 互动环节): “举个手，谁遇到过想看懂一个功能，结果在IDE里跳了十几个文件的情况？”
痛点场景： 业务流程像天女散花，心智负担极大，你根本找不到一个地方能看清这个功能的“剧本”。这就是业务流程的逻辑离散。

解药：一个清晰的【用例层 Use Case Layer】

它的唯一职责：像一个“导演”，负责编排一个完整的业务故事。一个Use Case就代表系统的一个能力。

kfinops 的实践:

// in internal/usecase/subdomain/service.go
type SubDomainUseCase struct {
    repo repository.SubDomainRepository // 依赖接口
}
func (uc *SubDomainUseCase) CreateSubDomain(...) error {
    // 1. 验证输入 (DTO)                <-- 高亮
    // 2. 创建 Domain 实体             <-- 高亮
    // 3. 调用 Domain 实体业务方法      <-- 高亮
    // 4. 通过【接口】进行持久化          <-- 高亮
    return uc.repo.Save(ctx, domainEntity)
}

效果： 想理解一个功能，只需要看这一个文件。它清晰地讲述了“做什么（What）”，而不关心“怎么做（How）”。

P7: 问题三：“数据库要从MySQL换成MongoDB，完了，项目要重写了！”

(🖼️ 视觉元素占位符: 洋葱图高亮第三层的 “Adapters” 环，并画一个箭头表示依赖反转)
痛点场景： 你的代码里到处都是 gorm.DB.Where(...).Find(...)。你的业务逻辑“知道”你正在使用GORM和MySQL。这就是业务逻辑和数据存储技术的强耦合。
解药：【适配器层 Adapter】 + 【依赖倒置原则】
- 它的唯一职责：将技术细节“适配”成业务层能理解的“插件”。
- 核心魔法——依赖倒置：
  1. Use Case（使用者） 在自己包里定义接口。
  2. Adapter（实现者） 去实现这个接口。
- 效果： 技术实现变成了可插拔的“零件”。更换数据库？只需要写一个新的Repository实现，然后在DI配置里换掉即可，Use Case层的代码一行都不用改！

P8: 问题四：“这代码根本没法写单元测试！”

(🖼️ 视觉元素占位符: 一张图片，左边是混乱的毛线球代表紧耦合，右边是整齐的乐高积木代表可测试)
(🎤 互动环节): “诚实地举手，谁因为代码太难测试而放弃写单元测试的？”
痛点场景： 业务逻辑里 new 了一个数据库连接，导致单元测试必须依赖真实环境。这是【可测试性灾难】。

解药：【接口】 + 【依赖注入 Dependency Injection】

它的唯一职责：将组件之间的依赖关系从“硬编码”变为“外部配置”。

效果：在单元测试中，我们可以轻松地“骗”过 Use Case：

// 我们可以轻易地用一个 "假的" mockRepo 替换掉 "真的" GormRepo
mockRepo := new(MockSubDomainRepository)
// 告诉 mockRepo: "当有人调用Save方法时，假装成功"
mockRepo.On("Save", mock.Anything, mock.Anything).Return(nil) // <-- 高亮

useCase := NewSubDomainUseCase(mockRepo) // 依赖被注入了！ <-- 高亮
err := useCase.CreateSubDomain(...)

assert.NoError(t, err) // 测试通过！全程没有碰过数据库！

这让编写快速、可靠的单元测试成为可能，极大地保证了代码质量。

P9: 可维护性的延伸：构建强大的可观测性

作为SRE团队，我们不仅要写出可维护的代码，更要确保系统在生产环境中是‘可理解’、‘可诊断’的。
可观测性三大支柱：
- 🪵 日志 (Logging) - 定位“哪里”出错了: 接入KAE，结构化日志，包含request_id。
- 📊 指标 (Metrics) - 了解“怎么样”了: Prometheus + Grafana Dashboard。
- 🔗 追踪 (Tracing) - 分析“为什么”慢了: OpenTelemetry 分布式追踪。
小结：整洁的架构让代码在“静态时”易于理解；完善的可观测性体系则让系统在“运行时”易于诊断。

P10: 面向AI编程：架构即契约，约束即指导

(🖼️ 视觉元素占位符: 一个对比图)
- 左边 (无架构): 人类 🤯 → prompt → AI 🤖 → 一堆散乱代码 💩
- 右边 (有架构): 人类 😎 → 短prompt → AI 🤖 → 精准、分层的代码 ✅
一个好的架构，就是整个项目的“代码契约 (Code Contract)”，它为AI提供了一个清晰、明确的上下文环境。
有了这份“契约”，约束就变成了对AI最有效的指导：
1. 架构定义了“剧本 (Playbook)”: AI会像一个熟悉项目的老手一样，在正确的地方写代码。
2. 约束提供了“护栏 (Guardrails)”: AI不会在usecase层直接写SQL。
3. “契约”简化了我们的“指令 (Prompt)”: 从“一步步告诉AI怎么做”，变成了“为 CreateUser 用例实现API”这样简单的指令。
结论：架构即提示 (Architecture as the Prompt)。

P11: 总结与行动指南

编写可维护代码的核心是“降低理解成本”和“控制变更影响”。
整洁架构是一份强大的“代码契约”，通过强制规则保证了项目的一致性。
(🚀 行动号召):
- 团队可以马上尝试的实践: 在下一个新功能里，先和同事花10分钟讨论一下它的 Use Case 是什么。
- 推荐大家试用: 克隆我们的 kfinops 项目或go-clean-arch模板，亲手运行一下，感受分层的清晰。
面向AI编程不是一句口号，而是一种新的工作范式。 你的架构越清晰、约束越明确，AI就越能成为你的得力助手。

P12: Q&A

谢谢大家！
项目模板参考: https://github.com/zhu327/go-clean-arch
大家有什么问题吗？或者对我们团队未来的代码规范有什么建议？

Vibe Coding有感: 从PingSIX重构说起

Tue, 02 Sep 2025 14:55:52 +0800

说到“Vibe Coding”，这个词最近在开发者圈子里越来越流行。在过去，我的实践很大程度上还停留在比较初级的阶段：把需求和代码片段在 ChatGPT、Google AI Studio 或是 Grok 之间来回地复制粘贴。来到新公司后，虽然开通了 GitHub Copilot，体验有所提升，但感觉它更多时候还是一个“超级智能补全”工具。直到今年7月份，公司给配上了 Cursor，我的编程体验才真正开启了一场变革，正式进入了 Vibe Coding 的奇妙旅程。

恰好，距离我上次更新个人项目 PingSIX 已经有一段时间了。PingSIX 是一个我基于 Cloudflare 高性能框架 Pingora 开发的 API 网关。两周前，Pingora 发布了 0.6.0 版本，这给了我一个绝佳的契机。我决定利用这个机会，彻底实践一次全程使用 Cursor 的 Vibe Coding，对 PingSIX 进行一次大重构。

这次重构断断续续花了一周时间，最终新增了 6636 行代码，删除了 3578 行。这不仅仅是数字上的变化，整个项目在架构、可维护性、可读性、安全性及性能上，都达到了一个我自己非常满意的状态。

我的 Vibe Coding 工作流

在这次重构之旅中，我逐渐摸索出了一套与 AI 高效协作的工作流。这套流程的核心思想是：你，作为程序员，依然是掌舵者；而 AI，是你最强大的副驾驶。

1. 选择对的“副驾”：模型很重要

工欲善其事，必先利其器。我尝试了 Cursor 内置的多个模型，最终发现 claude-4-sonnet 是我的首选。它表现最稳定，理解复杂上下文的能力很强，生成代码的质量也相当高，而且价格合适。其它模型或多或少会有些小问题，而 Sonnet 则提供了一种“无脑用”的稳定预期。

2. 精准的指令：上下文工程是关键

把 AI 当成一个需要明确指令的初级程序员。在你让 Cursor 写代码前，必须先自己整理好需求。需求描述得越详细、越清晰，AI 生成的代码质量就越高。我会把相关的代码文件、需要调用的函数定义，都通过 @ 符号添加到上下文中，为 AI 提供一个完整的“作战地图”。

3. 从战略到战术：让 AI 先当“架构师”

如果你自己对某个功能也一头雾水，不知道该如何下手，那就先别急着让 AI 写代码。我会先打开 “Ask” 模式，把我的难题抛给它，让 LLM 帮我出谋划策。通过一遍遍的追问和迭代，更新我的需求，最终将 AI 提供的方案整理成一份详尽的文档，甚至细化到某个具体逻辑的实现步骤。有时，我还会让它先为我的设想编写单元测试，然后再让 Agent 遵循这份“蓝图”去实现功能代码。

4. 你永远是代码的最终责任人

要时刻记住，LLM 的回答具有不确定性。它是一个强大的工具，但不能替代你的专业判断。我的原则是：先由我来确定“怎么写”的顶层设计，再让 LLM 来完成“体力活”。当代码生成后，Code Review 是必不可少的一环。仔细审查每一行代码，确保它完全符合你的预期。如果不确定，那就让 LLM 继续为这段代码补充单元测试，用测试用例来验证逻辑的正确性。

5. 让 AI 成为你的“代码评审专家”

除了写代码，AI 在 Code Review 方面也表现出色。有时我们自己很难发现项目中的潜在问题，这时就可以借助 LLM 的视角。我会用下面这个 Prompt 来请求一次全面的“代码体检”：

你是一个Rust编程大师, API网关领域的专家, 请你从代码总体的架构, 可读性, 可维护性, 安全性, 性能方面全面的review我的项目代码, 给出你的分析报告, 并对有哪些代码需要修改给出具体的修改建议。

从局部优化到全局审视：当AI助手遇到架构难题

在使用上述 Prompt 的过程中，我发现了一个 Cursor 的局限性。它的文件索引方式似乎是基于代码片段的向量化，这导致它在进行 Review 时，非常擅长发现局部的、函数级别的问题，但很难从项目整体的架构、分层和依赖关系上给出宏观的分析。

为了解决这个问题，我引入了两个外部工具，形成了一套组合拳：

gitingest.com: 这个小工具能把整个项目的代码，按照文件结构，完整地生成一个 Markdown 文本。
aistudio.google.com: 我使用的是 Gemini 2.5 Pro 模型，它支持百万级别的 Token 上下文，足以一次性“吞下”我的整个项目代码。

我的工作流变成了：使用 gitingest 打包项目 -> 将生成的 Markdown 完整地粘贴到 Google AI Studio -> 使用上面那个专家 Prompt 让 Gemini 进行全局审查。

经过这个流程，我得到了一份详尽的“体检报告”，其深度和广度甚至超出了我的预期。下面是最近一次 Gemini Review 报告的一部分摘录：

好的，作为一名在 Rust 编程和 API 网关领域都有深入研究的专家，我非常荣幸能为您审查 PingSIX 这个项目。

首先，请允许我表达我的赞赏：这是一个非常出色、设计精良的项目。它不仅基于 Cloudflare Pingora 这一高性能框架，还在架构设计、代码实现和功能完整性上达到了很高的水準。许多设计决策，例如配置热加载的实现方式、插件系统的设计以及对安全性的关注，都体现了作者深厚的技术功底和对 API 网关领域的深刻理解。

以下是我的综合分析报告，涵盖了总体架构、可读性、可维护性、安全性、性能以及具体的修改建议。

1. 总体架构 (Overall Architecture)

分析: 项目的整体架构是现代、模块化且高度可扩展的，非常符合云原生 API 网关的设计理念。

坚实的基础: 项目选择基于 Cloudflare 的 Pingora 框架，这是一个明智的决定。Pingora 提供了经过生产环境严酷考验的高性能、多线程的异步 I/O 核心，让项目可以专注于网关业务逻辑的实现，而不是底层网络细节。

配置驱动: … 特别是 Etcd 的集成，通过 arc-swap 和 dashmap 实现的配置热加载机制，是高性能网关的黄金标准…

逻辑分层清晰: 项目代码在 src 目录下按功能清晰地划分了模块（config, proxy, plugin, admin, core 等），职责分明。

共享服务设计: SharedHealthCheckService 的设计是一个关键的性能优化…

评价: 架构设计堪称典范，无论是性能、可扩展性还是可靠性方面都考虑得非常周到，达到了业界领先水平。

2. 代码可读性 (Readability)

分析: * 命名规范: … * 注释质量高: …更重要的是解释了“为什么这么做”（The Why）… * 错误处理: …ProxyError 枚举类型非常完善…

评价: 代码可读性极佳。

3. 可维护性 (Maintainability)

分析: * 高内聚，低耦合: … * 强大的配置校验: …在 src/config/mod.rs 中大量使用了 validator crate… * 泛型编程的极致运用: src/admin/mod.rs 中的 AdminResource Trait 和 ResourceHandler<T> 泛型结构是可维护性的典范…

评价: 项目的可维护性非常出色。

4. 安全性 (Security)

分析: * 容器安全: Dockerfile 遵循了最佳实践，使用了多阶段构建…并且创建了一个低权限的非 root 用户… * API 认证: …在比较密钥时使用了 constant_time_eq 函数，有效防止了时序攻击（Timing Attack）。 * TLS 配置: …代码强制将 TLS 的最低版本设置为 TLS 1.3…

评价: 安全性设计考虑周全，遵循了行业内的安全最佳实践。

5. 性能 (Performance)

分析: * 无锁热加载: 使用 arc-swap 来实现路由表…避免了读写锁带来的性能开销… * 高效的路由匹配: …通过反转主机名来巧妙地利用 matchit 的前缀匹配能力实现对通配符域名…这是一个极其聪明和高效的实现。 * 预编译与缓存: …

评价: 性能设计和优化做到了极致…README.md 中提到的性能指标（100K+ RPS, <10ms P99 延迟）基于此架构是完全可信的。

总结

PingSIX 是一个非常优秀的项目，其代码质量、架构设计和性能考量都达到了专业甚至顶尖的水平。它不仅是一个功能强大的 API 网关，更是一个极佳的 Rust 工程实践范例。 … 希望这份详尽的审查报告对您有所帮助！

拿到这份宏观报告后，我就可以把其中具体的修改建议，一段段地贴回 Cursor，让它帮我完成代码的微调和优化。改完一轮，再打包给 Gemini 重新审查，如此循环，直到臻于完美。

一点感想

LLM Agent 的强大无疑极大地提升了我的开发效率，但它也像一把双刃剑。这种前所未有的效率有时也会让上游的 PM 或 Leader 觉得：“反正你很快就能做出来，那我们就快速地改需求吧。” 结果可能导致我们做了很多功能，但真正沉淀和落地的却不多，这或许是“高效”时代下新的烦恼。

面对层出不穷的新工具和新范式，我的建议是：先用起来再说。用的多了，体会自然就深了。别人的经验可以参考，但更重要的是在实践中找到最适合自己的那套 Vibe。

我不确定 LLM 最终会不会淘汰程序员这个职业，但我能确定的是，会 Vibe Coding 的程序员，一定会淘汰不会 Vibe Coding 的程序员。所以，朋友们，都 Vibe起来吧！

整洁架构落地实践

Mon, 04 Aug 2025 14:55:52 +0800

最近在新公司接手了一个历史悠久的项目，功能不多，代码量却不小。深入其中，才发现有太多太多的槽点，简直让人头大。每当要新增一个功能或者修复一个 Bug，都感觉像是在雷区里跳舞，步步惊心。

总结下来，这个项目主要有这么几个“硬伤”：

代码逻辑不内聚：同一个功能的实现，像天女散花一样分散在好几个不同的文件里，想理清完整的逻辑链条，得在 IDE 里跳来跳去，极其耗费心智。
分层过多且混乱：一个简单的请求，要穿越重重关卡，经过好几个层级的调用才能抵达终点。有时你都分不清某一层到底是干嘛的，感觉纯粹是为了分层而分层。
内部自研框架不好用：项目依赖了一个内部的 kgo 框架，但文档缺失，设计理念也比较陈旧，出了问题排查起来非常困难。
外部依赖离散：对数据库、缓存、外部 API 的调用封装得五花八门，没有统一的规范和入口，整个项目像一个杂乱的“百宝箱”。

恰好，Leader 对这个项目制定了新的方向与目标，之前这些遗留问题实实在在成了我们前进路上的绊脚石。因此，一次彻底的架构升级与重构势在必行。同时，部门内也正在推广项目规范化和最佳实践输出，这简直是天赐良机。

很久以前我就读过《架构整洁之道》这本书，在之前的项目中也或多或少受到一些启发，但从未有机会从一个项目初始就完整地贯彻整洁架构的理念。这次，我决定抓住机会，来一场彻彻底底的整洁架构实践。在这个过程中，我感觉自己对整洁架构的理解，以及对 SOLID 原则的落地方式，都有了前所未有的深入体会。

在实践的过程中，我将心得与经验沉淀下来，开源了一个即开即用的 Go 整洁架构项目模板，希望能给有同样需求的同学一些参考： https://github.com/zhu327/go-clean-arch

项目模板特性

Clean Architecture: 清晰地分离业务逻辑与基础设施。
Dependency Injection: 使用 Google Wire 实现编译时依赖注入，避免反射。
Structured Logging: 开箱即用的结构化日志。
Configuration Management: 基于 Viper 的环境化配置管理。
Docker Support: 包含 Dockerfile 和 docker-compose.yaml，便于部署。

架构设计

这个项目严格遵循整洁架构（Clean Architecture）的原则，确保代码库的可扩展性、可维护性和可测试性。

各层描述

🔵 Domain 层: 包含核心的业务逻辑和实体。它是最独立的层，不依赖于任何其他层。
🟣 Use Case 层: 通过与 Domain 层交互来编排业务工作流。它定义了供 Adapter 层实现的接口。
🟠 Adapter 层: 作为与外部世界（如 UI、数据库、外部 API）沟通的桥梁。它实现了 Use Case 层定义的接口。
🟢 External World: 代表与应用程序交互的外部系统，如 Web 客户端、数据库或第三方服务。

核心原则

依赖方向: 所有依赖都必须指向内部。Domain 层位于中心，任何内层都不能依赖于外层。这是依赖倒置的核心。
接口隔离: 接口由消费者（Use Case 层）定义，由提供者（Adapter 层）实现。这使得业务逻辑与基础设施细节解耦。
分层隔离: 每一层只与它的相邻层交互，保持清晰的职责分离。

项目结构

internal/
├── domain/          # Domain 层 (业务实体和规则)
├── usecase/         # Use Case 层 (业务逻辑, 接口, DTOs)
├── adapter/         # Adapter 层
│   ├── delivery/    # 交付机制 (例如, HTTP, gRPC handlers)
│   ├── repository/  # 仓库实现 (数据库访问)
│   └── gateway/     # 到外部服务的网关
└── di/              # 依赖注入配置 (Wire)

实践中的思考与“顿悟”

理论总是美好的，但实践才是检验真理的唯一标准。在重构过程中，我遇到了不少困惑，也收获了很多“原来如此”的顿悟时刻。

1. 每一层到底应该放什么？

刚开始划分代码时，我经常会纠结一个结构体、一个文件到底该放在哪。经过反复的思考和试错，我总结出了一套相对清晰的指导方针。

internal/domain/
- ✅ 应该包含: 核心业务实体（代表业务对象的 Struct）、值对象、领域服务接口、与领域相关的枚举和常量。
- ❌ 不应包含: HTTP 请求/响应结构体、分页或 API 特定数据等应用级概念、任何基础设施细节（如 JSON 标签）。
internal/usecase/
- ✅ 应该包含: 具体业务用例的实现（如 CreateUser, LoginUser）、依赖项的接口定义（如 UserRepository）、请求和响应的 DTO（数据传输对象）。
internal/adapter/
- ✅ 应该包含: 将请求转换为用例调用的 HTTP/gRPC 处理器、实现 Use Case 层接口的数据库仓库、外部服务的客户端（网关）。

通过这个项目我深刻地体会到，项目的根本目的是解决现实世界的问题。我们需要对现实中的实体进行建模，这就是 domain 层的使命。这个实体必须纯粹，不依赖任何外部技术，只包含自身的业务规则和逻辑。

而 usecase 层，则是针对领域模型的一次具体应用和落地。它需要依赖外部能力，比如查询一次数据库、调用一次 gRPC。这时，我们不应该直接在 usecase 中去 new 一个 DB client。而是应该在 usecase 中定义业务所需的 interface，然后由 adapter 层的 repository 或 gateway 来实现这些接口。

这样一来，repository 就不再只是对 GORM 或 sqlx 的简单封装，它变成了 usecase 接口的具体“提供者”。它需要将从数据库查出的数据模型，转换为 usecase 能理解的 domain 模型。最后，通过依赖注入，实现了完美的依赖倒置。

2. 关于依赖注入：从排斥到接受

在以往的项目中，我基本没用过依赖注入，项目里充斥着各种 init() 函数和全局变量，给测试和维护带来了无尽的痛苦。后来接触到依赖注入，有个老哥自己撸了一套基于反射的 DI 框架，读他的代码真的太难受了，完全不知道依赖到底是怎么注入进来的，魔法感十足，这导致我对依赖注入一度有先入为主的排斥。

但在实践整洁架构的过程中，由于 usecase 必须做依赖倒置，我不得不引入 DI 工具。最终选择了 Google 的 wire。用过之后才发现，它其实并没有什么魔法，只是通过扫描代码，自动生成了那些“手动挡”的初始化代码而已（wire_gen.go）。相对于通过反射实现的“自动挡”，这种代码生成的方式让一切依赖关系都变得明确和可知，可读性好太多了。

3. DTO 的归属之争

这是一个让我纠结了很久的问题。usecase 理想情况下只应该依赖 domain 定义的模型。然而在实际业务中，总会有一些不属于 domain 核心模型的结构，比如 CreateUserRequest、UserListResponse。注意，这并非 delivery 层用于解析 JSON 的结构体，而是 usecase 自身执行业务逻辑所需要的数据结构。

我曾经犹豫过，要不要把这些结构体也塞进 domain 层？

纠结过后，我得出的结论是：不能！一定要保持 domain 层的纯粹性。这些结构体实际上是和某个具体的 usecase 强绑定的，它们应该属于 usecase 层。所以，我在 usecase 层下也创建了 dto 目录，用来存放这些用例专属的请求/响应结构。

这确实会导致 delivery (HTTP) 层和 usecase 层可能都有各自的 DTO，初看可能会有些冗余和困惑。但这样做的好处是职责更清晰，usecase 不会因为 delivery 层的变化（比如修改一个 JSON 字段名）而被迫修改。这是为了层与层之间的解耦，必须付出的代价。

4. 我终于悟了：“在调用者包中定义接口”

我之前读到过 Go 社区的一个广为流传的建议（出自 colobu.com/gotips/018.html）：

在使用者的包中定义接口，而不是提供者的包中定义。

说实话，在没有深入实践整洁架构之前，我对这条原则一直是一知半解。为什么接口要让“用的人”来定义，而不是“做的人”来定义呢？

在这次重构之后，我“悟了”。这不就是对“依赖倒置原则”最精准、最通俗的诠释吗！

在我们的架构里： - usecase 是接口的使用者（消费者）。 - adapter 是接口的实现者（提供者）。

usecase 说：“我需要一个能根据用户 ID 找到用户，并返回 domain.User 的能力，我不管你是从 MySQL、Redis 还是从文件中获取，总之，你得满足我定义的这个 UserRepository 接口。”

// in usecase/iface/repository.go
package iface

import "your_project/internal/domain"

type UserRepository interface {
    FindByID(ctx context.Context, id uint) (*domain.User, error)
}

然后，adapter/repository 层去实现它。

// in adapter/repository/user_gorm.go
package repository

// ...
func (r *userRepository) FindByID(ctx context.Context, id uint) (*domain.User, error) {
    // gorm query logic...
    // convert gorm model to domain.User
}

这样做的好处是巨大的：

完美解耦：usecase 只关心它需要什么，不关心底层如何实现。更换数据库实现对 usecase 毫无影响。
易于测试：在为 usecase 写单元测试时，我们可以轻而易举地 mock 这个 UserRepository 接口，而无需一个真实的数据库连接。
符合最小知识原则：如果让 adapter 来定义接口，它可能会暴露很多 usecase 根本不需要的方法，增加了使用者的心智负担。而由使用者定义，则可以确保接口的精简和必要。

总结

从一个混乱的遗留项目开始，到最终落地一套清晰、可维护的整洁架构，这次重构之旅让我收获颇丰。整洁架构并不仅仅是一套死板的目录结构或分层规则，它更是一种引导我们写出高内聚、低耦合代码的思维方式。

它迫使我们去思考： - 什么是业务的核心？（Domain） - 业务流程是怎样的？（UseCase） - 技术细节如何与业务逻辑解耦？（Adapter & Dependency Inversion）

通过这次实践，我对依赖倒置、接口隔离等 SOLID 原则有了远比书本上更深刻的理解。当你真正理解了“为什么”要这么做，而不是仅仅停留在“是什么”和“怎么做”的层面时，你会发现，写出整洁、健壮的代码，其实是一件充满乐趣的事情。

希望这篇文章能为同样在重构道路上探索的你，提供一些有价值的参考与启发。

打造一个属于自己的AI书签

Mon, 07 Jul 2025 14:55:52 +0800

前言

我一直是个重度的书签使用者，多年来都依赖 Pocket 来收藏和沉淀那些在网上看到的、值得一读的文章。然而，最近 Pocket 宣布其通知服务即将关闭，这对我来说像是一个信号，是时候去寻找一个更稳定、更可控的替代品了。

我的探索之旅就这样开始了：

Raindrop.io：社区里很多人推荐，功能也确实强大。但不知道是不是网络原因，我这边访问起来总是感觉有点慢，而且用惯了 Pocket 的我，对它的界面和交互逻辑始终有些不太习惯。
自建服务：作为程序员，第一反应自然是自己动手。我找到了像 linkding 这样的优秀开源项目。我尝试把它部署在 fly.io 的免费实例上，但 linkding 对资源的要求不低，最低配的 256M 内存实例直接就 OOM (Out of Memory) 了，升级配置又意味着成本。
从零开始写一个？ 这个念头一闪而过。我甚至构思好了技术选型：参照 linkding 的功能，用我最近在学习的 Rust 实现后端，部署在 Cloudflare Workers 上，再配上 Cloudflare D1 的 SQLite 数据库。这套方案 Serverless、成本极低，堪称完美。但转念一想，这工程量可不小，对于业余项目来说，我实在没有那么多时间投入进去。

就在我快要放弃，准备将就着用某个方案时，我想起了一篇以前收藏过的文章。

1. 灵感乍现：LLM x GitHub 书签

那篇文章是 LLM x 书签收藏：摘要 & 全文索引，作者提供了一个极具创意的思路：通过一个浏览器插件 osmos::memo，可以将书签直接保存到指定 GitHub 仓库的 README.md 文件里。

这个方案瞬间击中了我！它足够简单，没有多余的功能，完美符合我的需求。数据就躺在自己的 GitHub 仓库里，再也不用担心服务关停。虽然原文后续介绍了如何利用 LLM 对书签进行摘要和索引，但我觉得还可以更进一步，改造成一个完全自动化、更符合我使用习惯的流程。

说干就干，我立刻创建了一个新的仓库 bookmark，准备开始我的改造计划。

2. 存量数据的漫漫迁移路

要打造新家，首先得把老家的家当搬过去。第一步，就是处理从 Pocket 导出的几百条存量书签。

我写了一个简单的 Python 脚本，将 Pocket 导出的 HTML 文件解析成 Markdown 格式，然后一股脑儿地塞进了 README.md。但这只是万里长征的第一步。我的目标是让每个书签都有 AI 生成的摘要和分类。

我想到了最近很火的 Gemini，它的命令行工具 gemini-cli 看起来很适合用来做批处理。于是，我开始了我的踩坑之旅：

初次尝试（失败）：我用 Playwright 写了个脚本，模拟浏览器去访问我的 230 个书签链接，把每个页面的完整 HTML 都抓取下来。结果，所有内容加起来足足有 165MB。
分割文件 + Gemini CLI（失败）：我把这 165MB 的内容按每个网页一个文件进行分割，然后尝试用 gemini-cli 遍历所有文件，让它为每个 HTML 生成摘要和分类。结果，Gemini 的上下文窗口有限，而且 API 调用非常非常慢，一个下午过去，才处理了不到 80 个。果断放弃。
打包上传 AI Studio（失败）：我想，单个处理不行，那就打包处理。我用 Python 脚本把网页按每 20 个一组进行打包，但每个包的文件大小仍在 5MB ~ 14MB 之间。这个大小对于直接上传到 Google AI Studio 来说还是太大了，此路不通。
精简内容 + 手动处理（成功！）：看来问题出在原始 HTML 内容太庞杂了。我再次修改脚本，在分割文件的同时，引入 html2text 库，将臃肿的 HTML 转换成纯文本。这下效果立竿见影，每 20 个网页打包成的文件只有 400KB ~ 600KB。
AI 手工操作：我将这 13 个（230/20 ≈ 13）处理过的文本文件，手动一个个上传到 Google AI Studio。然后，通过精心设计的 Prompt，让 AI 为文件里的每一个链接都生成摘要，并整理成我想要的 Markdown 格式。
最终分类：我把 AI 生成的所有摘要内容汇总到一个 summary.md 文件里。最后，再把这个汇总文件上传给 AI Studio，给它下达最终指令：“请根据这些内容的摘要，将所有链接按技术领域、生活、思考等类别进行分类整理。”

最终，我得到了完美的分类归档文件：category.md。虽然过程曲折，但看到整齐划一的成果时，一切都值了。

3. 新增书签？交给 GitHub Actions 吧！

处理完存量数据，接下来就要考虑如何自动化地处理每一个新增的书签了。我的思路是，让万能的 GitHub Actions 来扮演这个智能管家的角色。

整个流程如下：

触发：每当我通过 osmos::memo 插件向 README.md 添加新链接并推送到 GitHub 时，就会自动触发 GitHub Actions 的 workflow。
解析：在 workflow 中运行的 Python 脚本 (process_bookmarks.py) 会使用 git diff 命令，精准地找出 README.md 中新增加的那一行书签链接。
抓取内容：为了避免自己写爬虫遇到的各种反爬问题，我选择了一个非常棒的工具——jina reader。通过调用它的 API (https://r.jina.ai/URL)，可以直接获取到目标链接页面的干净、规范的 Markdown 文本。
生成摘要：将获取到的 Markdown 文本发送给 LLM API，让它生成一段简洁的摘要。
智能分类：将链接的原始标题和 AI 生成的摘要再次组合，发送给 LLM API，让它判断这个链接应该属于哪个分类。
写入归档：最后，脚本会按照 [标题](链接) - 摘要 的格式，将这条全新的、处理好的书签信息，追加到 category.md 文件对应的分类下。

就这样，一套完全自动化的 AI 书签整理流程就诞生了。我只需要在浏览器上点一下收藏，剩下的抓取、摘要、分类、归档工作，都由我的 AI 管家在云端默默完成。

4. 拥有你自己的 AI 书签

这套方案我已经开源在 GitHub 上：https://github.com/zhu327/bookmark

目前我使用的 LLM API 是由硅基流动提供的免费模型 deepseek-ai/DeepSeek-R1-0528-Qwen3-8B，效果相当不错。如果你也对这个方案感兴趣，可以非常简单地拥有自己的 AI 书签：

Fork 这个仓库。
在你的仓库 Settings -> Secrets and variables -> Actions 中，添加两个 Repository secrets：
- LLM_API_URL: 兼容 OpenAI API 格式的大模型接口地址，例如 https://api.siliconflow.cn/v1/chat/completions。
- OPENAI_API_KEY: 调用该 API 所需的 Key。

当然，这个方案也并非完美。比如对于有严格反爬策略的网站（点名微信公众号），jina reader 也无能为力，无法直接获取到文章内容。

总结

在后 Pocket 时代，借助 LLM 的强大能力，我的个人书签系统完成了一次有趣的进化。它不再是一个依赖于第三方在线服务的传统书签，而是变成了一个由我自己掌控、活在 GitHub 上的智能知识库。所有数据都以 Markdown 格式清晰地存储，检索也变得前所未有的简单——打开 category.md，按下 CTRL + F 即可。

这个小项目让我再次感受到，将 AI 作为一种工具融入到个人工作流中，能够迸发出巨大的能量。它不仅解决了我的实际问题，也让整个过程充满了探索和创造的乐趣。

我理解的AI Agent与MCP

Wed, 02 Apr 2025 10:55:52 +0800

前言

最近AI圈子里Manus这个项目可以说是相当火了，连带着MCP（Model Context Protocol）这个概念也开始频繁出现在各种技术讨论区。作为一个程序员，自然也对这些新东西充满了好奇，于是花时间捣鼓了一下AI Agent和MCP相关的知识。这篇文章就是我学习和思考后，对这两个概念的一些个人理解和梳理。

1. 从Workflow到AI Agent：大脑的进化

回顾我们以前做自动化任务，比如搞个自动抢票、自动下单之类的，思路基本都是围绕着一个固定的workflow。我们会预先设定好一套流程逻辑：收到指令 -> 判断条件 -> 走对应分支 -> 调用特定工具（API、脚本等）。整个过程就像一个流程图，每个节点和路径都是我们程序员预先设计好的。在这个模式下，我们程序员就是这个workflow的“大脑”，我们把执行计划通过代码逻辑，“硬编码”到系统里。比如预定机票这个场景，我们会写代码一步步调用查询接口、选择航班接口、填写乘机人信息接口、支付接口等等。

2. LLM登场：有了“大脑”，但还缺“手脚”

随着大语言模型（LLM）技术的突飞猛进，特别是像DeepSeek R1这样强大的推理模型出现，它们的推理和规划能力越来越接近人类大脑。这就让我们自然而然地想到：能不能让LLM来充当这个自动化流程的“大脑”，代替我们来制定执行计划呢？

想法很美好，但LLM本质上还是一个文本补全的模型。它能“思考”并告诉你计划是什么，但它自己并不能直接撸起袖子去调用那些具体的工具（API、函数等）来完成任务。为了解决这个问题，OpenAI在其API中引入了tools（或称为 Function Calling）的概念。

这个流程大致是这样的：

我们的应用程序（可以称为Agent）调用LLM API时，在请求的上下文中详细描述可用的工具：每个工具是干嘛的、输入需要什么参数、输出是什么格式。
Agent把用户的自然语言指令（Prompt）发给LLM。
LLM根据用户的需求，结合它所知道的工具信息，判断是否需要以及需要调用哪个（或哪些）工具。
如果需要调用工具，LLM不会直接执行，而是返回一个包含调用指令的响应，里面说明了要调用哪个工具以及需要传递的参数（通常是JSON格式）。
Agent收到这个响应后，解析出调用指令，在Agent自己的环境里执行相应的工具（比如调用一个本地函数或一个外部API）。
Agent拿到工具的执行结果后，把这个结果再次作为上下文信息，传回给LLM。
LLM根据工具的执行结果，决定下一步是继续调用其他工具，还是生成最终的回复给用户。

这个基于tools的交互模式，让LLM有了指挥“手脚”（工具）的能力。但这里也暴露了一个比较明显的弊端：完成一个任务可能需要多次与LLM进行交互（LLM决策 -> Agent执行 -> Agent反馈结果 -> LLM再决策…），并且为了让LLM理解上下文，每次交互都需要传递越来越长的历史信息，这既增加了延迟，也增加了API调用成本和Token消耗。

3. CodeAct：让LLM直接写代码执行

我们知道，当前LLM最强的能力之一就是代码生成。于是，就有人想出了另一种更直接的思路：既然LLM擅长写代码，而我们提供的工具本身很多就是函数或者可以通过代码调用的API，那何不让LLM直接生成一小段可执行的代码（比如Python），然后在我们的Agent里内置一个安全的代码执行沙箱来运行这段代码呢？

在这段生成的代码里，LLM可以直接包含对我们提供的工具（函数）的调用，甚至可以编写一些简单的流程控制逻辑（if/else、循环等）。这样一来，多个步骤和工具调用可能通过一次LLM生成、一次代码执行就完成了，大大减少了与LLM的交互次数。这种方法就被称为CodeAct（代码作为行动）。

4. 到底什么是AI Agent？

聊了这么多，我们再来尝试给AI Agent下一个定义。我认为，AI Agent = LLM（大脑） + Tools（手脚） + Agent Runtime（执行器） + 决策循环。

具体来说，AI Agent通过调用LLM API，并结合一系列可用的工具（Tools），来理解并执行用户的自然语言任务。它通常采用一种决策-执行-观察的循环模式（ReAct）：

决策（Reason）：由LLM根据当前任务目标和上下文信息，决定下一步是调用工具还是直接回复。
执行（Act）：由Agent Runtime根据LLM的决策，执行相应的工具调用或代码片段。
观察（Observe）：Agent Runtime将执行结果反馈给LLM，作为新的上下文信息，供LLM进行下一轮决策。

这个循环一直持续，直到任务完成。

但这里有个关键问题：LLM本身具有一定的不确定性。对于相同的输入（Prompt），它每次返回的结果可能都不完全一样。这就给AI Agent的执行带来了挑战，有时候可能会偏离预期或者卡在某个环节。因此，在开发AI Agent时，接入Tracing（追踪）系统变得非常重要。我们需要能够实时跟踪Agent与LLM的每一次交互、上下文内容、工具调用情况以及执行结果，这样才能在出现问题时快速定位和调试，进而优化我们的Prompt或者Agent逻辑。

5. 多Agent协作：专业的事交给专业的Agent

随着Manus的流行，多Agent编排（Multi-Agent Orchestration）的理念也开始受到关注。核心思路是化整为零，分工协作。

我们不再试图构建一个“万能”的超级Agent，而是将复杂的任务拆解，构建多个功能单一、职责明确的专家Agent。比如，我们可以把web_search和web_fetch这两个工具组合起来，封装成一个专门负责网页抓取的web_scraper_agent。这种单一功能的Agent，它的大脑（LLM）可能不需要最顶级的推理能力，我们可以选用一个性能足够且成本更低的模型（比如一些中小型模型或者特定领域的微调模型）。

当我们有了多个这样的专家Agent后，再引入一个Planner Agent（规划器Agent）。这个Planner Agent通常需要一个推理能力较强的LLM作为大脑，它的职责是：

接收用户的原始任务。
将任务拆解成若干子步骤。
根据每个子步骤的需求，选择并调用合适的专家Agent。
收集专家Agent的执行结果。
根据执行结果，动态调整后续的计划（可能需要重新规划或调用其他Agent）。
循环这个过程，直到最终任务完成，然后将结果汇总返回给用户。

这种多Agent架构带来的好处显而易见：

成本效益：在大量执行具体任务的专家Agent上可以使用更便宜的LLM。
维护性：每个Agent功能单一，更容易开发、测试和维护。
扩展性：可以方便地增加新的专家Agent来扩展整个系统的能力。
可能更优化的上下文管理：Planner Agent可能只需要关注子任务的目标和专家Agent返回的关键结果，而不需要承载所有底层工具调用的详细上下文。

6. Prompt工程：Agent的灵魂

无论是使用ReAct还是CodeAct，无论是单Agent架构还是多Agent编排，有一个环节始终是绕不开的，那就是Prompt Engineering（提示工程）。

我们需要为每一个与LLM交互的环节（无论是Planner Agent制定计划，还是专家Agent执行任务，或是Function Calling/CodeAct的触发）精心设计Prompt。好的Prompt需要能够引导LLM按照我们的预期来思考和输出：

让Planner Agent生成结构化、可分步执行的计划。
让LLM在需要时准确地选择并调用我们提供的工具。
让LLM返回格式规范、易于解析的文本（比如JSON），方便Agent Runtime处理。

可以说，Prompt就是我们给AI Agent注入灵魂的方式。

7. MCP：Agent间沟通的标准语

随着多Agent架构的兴起，Agent之间如何发现彼此、如何调用彼此的能力就成了一个问题。这时，MCP（Model Context Protocol）这个概念应运而生。

你可以把MCP理解为一套为Agent（或者说LLM的工具）设计的标准化接口规范。

在没有MCP之前，我们实现的工具可能五花八门：一段本地Python代码、一个内部HTTP API调用、一个第三方云服务接口等等。每次要给Agent添加新工具，都需要手动编写关于这个工具的描述（功能、参数、格式），然后注入到Agent的上下文中。

有了MCP之后，情况就可能变得更规范：

工具提供方可以将其能力封装成一个遵循MCP协议的MCP Server。
Agent可以通过标准的MCP方法（比如list_tools）来动态发现某个MCP Server提供了哪些工具及其描述。
Agent可以通过标准的MCP RPC Call来执行这些工具。

MCP不仅仅规范了工具的调用，它通常也试图规范Prompt模板、资源管理等Agent开发中常见的元素。如果MCP能够被广泛采用，理论上可以：

降低Agent的开发门槛：开发者可以直接复用社区提供的、遵循MCP标准的工具服务，而不需要自己重复实现和描述工具。
提高Agent的互操作性：不同开发者、不同团队开发的Agent或许能更容易地进行协作。

当然，MCP目前似乎还在发展初期，但它指明了一个让Agent生态更加规范化、标准化的方向。

8. 总结：门槛不高，精通不易

以上就是我这段时间学习下来，对AI Agent和MCP的一些粗浅理解。在阅读了几个开源的Manus实现（或者类似的多Agent框架）之后，我的一个直观感受是：

对于掌握Python的程序员来说，上手开发一个基础的AI Agent，或者编写一个简单的Tool/MCP Server，技术门槛似乎并不算特别高。很多框架（如LangChain、LlamaIndex等）已经帮我们处理了与LLM交互、管理上下文、执行工具等繁琐的底层工作。

然而，真正的挑战在于：如何在一个特定的业务场景下，设计和实现一个稳定、可靠、高效的AI Agent。这需要：

深刻理解业务需求，并将其转化为适合Agent执行的任务流程。
精心的Prompt设计与调优，不断尝试，引导LLM给出期望的输出。
有效的Tracing和Debugging，快速定位Agent执行过程中的问题并进行修复。
合理的架构选择（单Agent vs 多Agent，ReAct vs CodeAct）和成本控制。

就像当年我们从写简单脚本到构建复杂系统一样，AI Agent的世界也是易学难精。工具和框架降低了入门门槛，但要做出真正好用的Agent，还需要大量的实践、思考和打磨。

9. 参考

云原生开发入门

Fri, 28 Mar 2025 10:55:52 +0800

作为一名在云原生领域摸爬滚打了一段时间的开发者，我时常会遇到一些刚接触这个领域的朋友，他们面对 Kubernetes (K8s)、容器这些概念时，常常感到有些迷茫，不知道从何学起。这篇文章，我想结合自己的一些学习体会，为想要入门云原生开发的同学提供一个相对清晰的指引。

我自己并非科班出身，从最初接触软件测试写 Lua 脚本，到后来学习 Python 做后端，再到进入腾讯接触 Golang 和 K8s 相关开发，一路走来也踩了不少坑。云原生技术栈确实庞大，但核心的理念是利用容器、微服务、声明式 API 等方式，去构建更可靠、更具弹性的分布式系统。而 K8s 作为这个生态的核心编排引擎，可以说是我们必须掌握的关键技能。

这篇文章，我会从基础概念聊起，分享几本我学习过程中觉得非常有帮助的书籍，一个不错的社区文章集合，以及两个可以动手实践的代码项目。最后，还会结合实际工作经验，聊聊 K8s 运维实践中一些重要的事情。希望这些能帮助大家在学习云原生的路上少走一些弯路。

一、云原生与 Kubernetes：从基础概念开始

云原生到底是什么？

我理解的云原生（Cloud Native），它不是指某一个具体的技术，更像是一种面向云环境的应用设计、开发和部署的最佳实践集合。它鼓励我们使用像容器、微服务、不可变基础设施、声明式 API 这些技术和方法，目标是让我们的应用能更好地利用云计算的弹性、分布式、自动化等优势。根据 CNCF（云原生计算基金会）的定义，这些是关键要素。简单说，就是让应用为云而生，能在云上运行得更好。

为什么 Kubernetes 这么重要？

容器技术（比如 Docker）解决了环境一致性的问题，但当你有成百上千个容器需要管理时，手动操作就变得不现实了。Kubernetes 就是来解决这个问题的。它是一个开源的容器编排平台，最初由 Google 开发，现在由 CNCF 维护。它可以自动化地完成应用的部署、扩缩容、服务发现、负载均衡、故障恢复等一系列复杂工作。在我看来，掌握 K8s 是进入现代后端开发、特别是平台工程领域的一张重要门票。

我的学习路径建议：

回顾我自己的学习过程，我建议可以按以下步骤来：

先搞懂容器：理解 Docker 的基本概念，比如镜像（Image）、容器（Container）、Dockerfile，能自己动手构建、运行一个简单的容器化应用。
再深入 K8s 核心：学习 K8s 的核心组件（比如 Pod、Service、Deployment、StatefulSet、Namespace 等）都是做什么的，它们之间是如何协作的。了解控制平面（Master）和数据平面（Node）的基本工作原理。
动手实践是关键：理论学习后，一定要动手实践。尝试编写 YAML 文件部署应用，使用 kubectl 与集群交互。然后可以去探索存储（Volumes, PV, PVC）、网络（Ingress, CNI）、配置（ConfigMap, Secret）等更深入的主题。
理解运维视角：开发的应用最终要跑在生产环境。了解 K8s 集群的监控、日志、告警、排错等运维实践，对于写出更健壮、更易于维护的应用非常有帮助。

接下来，分享一些我在学习过程中用过且觉得不错的资源。

二、推荐书籍：理论与实践结合

市面上关于 K8s 的书不少，但下面这两本是我个人觉得非常经典，值得花时间去读的。

1. 《Kubernetes in Action》

豆瓣评分参考：8.8 分
我的推荐理由：这本书非常侧重实践。作者 Marko Lukša 通过大量可操作的例子，一步步带你上手 K8s。从最基础的 Pod、Service 到 Deployment 实现滚动更新，都讲得很清楚。对于刚入门 K8s，希望快速看到效果、建立信心的同学来说，这本书是极好的选择。我当初就是跟着这本书敲代码，对 K8s 的基本操作有了直观的认识。
可以重点关注的章节：
- 第 2 章：用一个 Node.js 例子带你跑通第一个 K8s 应用。
- 第 5 章：讲解 Service，理解应用如何被访问。
- 第 9 章：讲解 Deployment，掌握应用发布的核心方式。
适合谁：K8s 新手，特别是喜欢通过动手实践来学习的开发者。

2. 《深入剖析 Kubernetes》

豆瓣评分参考：9.3 分
我的推荐理由：张磊大佬写的这本书，更侧重于 K8s 的设计理念和底层实现原理。如果你不满足于仅仅会用 K8s，还想知道它内部是怎么工作的（比如调度器如何决策？网络 CNI 如何实现？），那这本书绝对值得一读。对我自己而言，阅读这本书加深了我对 K8s 架构的理解，对于后来做一些 K8s 相关的开发工作非常有帮助。它不仅仅是讲技术，还融入了作者在一线的实践思考。
可以重点关注的章节：
- 第 3 章：K8s 整体架构和设计哲学。
- 第 5 章：控制器（Controller）和编排原理，这是 K8s 自动化的核心。
- 第 7 章：网络原理，CNI、Service 等机制讲得很透彻。
适合谁：对 K8s 有一定基础，想深入理解其工作原理和设计思想的开发者。

怎么选？ 我的建议是，如果你是新手，可以先看《Kubernetes in Action》动手实践，建立基本概念；然后再读《深入剖析 Kubernetes》加深理解。如果你已经有基础，可以直接看《深入剖析 Kubernetes》。

三、社区文章合集：K8s Club

除了书籍，社区里也有很多高质量的文章。我个人比较关注 K8s Club 这个 GitHub 仓库。

它汇集了不少国内云原生开发者撰写的技术文章，内容覆盖从基础到进阶，也有源码分析和实践经验分享，质量普遍不错。

值得关注的内容：

概念梳理与入门：比如用问答形式总结 K8s 核心概念的文章。
知识图谱：帮助你了解 K8s 的整体知识体系。
核心组件原理分析：比如 Informer 机制、调度器原理等，对深入理解 K8s 或做二次开发很有帮助。
实践操作指南：比如手动搭建集群、Pod 生命周期管理等。

如何利用？ 遇到具体问题时可以去搜索相关的文章；也可以系统性地阅读某个系列；最重要的是，看完之后尽量动手在自己的环境（比如 Minikube）中验证一下。

四、代码示例项目：动手实践出真知

理论学习最终还是要落到实践上。就像我学习 Rust 会自己动手写项目一样，学习 K8s 也需要通过代码来加深理解。下面是我找到的两个 GitHub 上的项目集合，提供了不错的练手机会：

1. Kubernetes Learning Playground

地址：https://github.com/Kubernetes-Learning-Playground
简介：这个组织下有不少关于 K8s 扩展开发的项目示例，比如如何与 K8s API 交互（client-go）、简单的 CSI/CNI 插件实现、自定义调度器等。
可以看看的项目：
- multi-cluster-informer：学习如何监控多个 K8s 集群。
- csi-interface-study：一个简单的 CSI 存储插件示例。
适合：对 K8s 内部机制、API 编程、插件开发感兴趣的同学。

2. Operator Learning Playground

地址：https://github.com/Operator-Learning-Playground
简介：专注于 K8s Operator 开发模式的练习项目。Operator 是用来管理有状态应用或自动化复杂运维任务的重要模式。
可以看看的项目：
- proxy-operator：一个简单的 Operator 例子，感受下基本结构。
- podReStarter-operator：实现特定条件下自动重启 Pod 的控制器。
适合：想学习如何使用 CRD (自定义资源) 和 Controller 来扩展 K8s 功能的同学。

实践建议： * 在本地用 Minikube 或 Kind 搭个 K8s 环境，方便实验。 * 从简单的项目开始，先跑起来，再尝试理解代码，然后可以试着修改或扩展它。

五、学习路线与个人心得

结合上面的资源，我梳理了一个学习 K8s 的大致路线：

基础入门：通过《Kubernetes in Action》和动手实验，掌握 Docker 和 K8s 的基本概念与操作。能部署简单应用，会用 kubectl。
深入原理：阅读《深入剖析 Kubernetes》，理解 K8s 的核心架构和工作机制。结合 K8s Club 的文章，针对性学习。
实践进阶：研究上面提到的代码示例项目，尝试理解并动手修改。开始关注 K8s 生态中的其他工具，如 Helm、Prometheus 等。
持续学习：云原生技术发展很快，保持学习状态很重要。多看官方文档，关注社区动态。

我自己的一些体会：

动手非常重要：看再多文档不如自己动手敲一遍。遇到问题、解决问题的过程是最好的学习。
非科班不用怕：像我一样非科班出身的同学，可能基础会薄弱一些，那就多花点时间去补基础（比如《深入理解计算机系统》这样的书）。关键是持续学习和实践。
利用好 GitHub：无论是学习别人的项目，还是像我一样把自己写的东西放上去，GitHub 都是一个很好的平台。它不仅能记录你的成长，有时还能带来意想不到的机会。

六、K8s 运维实践：开发者也需关注

开发完应用部署到 K8s 只是第一步，如何保障它在生产环境稳定运行，是同样重要的事情。虽然可能有专门的运维团队，但作为开发者，了解一些基本的运维实践，能帮助我们写出更符合生产要求的应用，也能在排查问题时更有思路。

这部分我参考了腾讯云 K8s 运维开发工程师整理的《Kubernetes 实践指南》（这份指南写得挺实用的），结合自己的一些经验，提炼几点：

熟练使用 kubectl：这是与 K8s 交互的基础。get, describe, logs, exec 等命令要常用常练。学会看 describe 里的 Events 信息，对排错很有帮助。
镜像管理：注意使用小的基础镜像、多阶段构建来优化镜像体积。生产环境用私有镜像仓库，配置好拉取密钥。
监控告警是标配：Prometheus + Grafana 是社区主流方案，需要了解如何暴露应用的 metrics，如何配置基本的告警规则。日志收集（如 EFK/ELK）也要考虑。
资源管理（Requests & Limits）：一定要给 Pod 设置合理的 CPU 和内存 requests（用于调度）和 limits（用于限制），避免资源抢占导致应用不稳定或影响其他应用。
健康检查（Probes）：配置好 Liveness Probe（存活探针，判断容器是否需要重启）和 Readiness Probe（就绪探针，判断容器是否准备好接收流量），让 K8s 能准确管理应用状态。
理解 Namespace 和 RBAC：Namespace 用于资源隔离，RBAC 用于权限控制，都是保障集群安全和管理有序性的重要机制。

运维学习建议：同样需要动手，可以在本地环境模拟一些场景，比如手动删除 Pod 看 K8s 如何恢复，调整资源限制看效果等。

七、结语

回头看，云原生开发这条路确实内容不少，但走下来收获也很大。从 K8s 的基础操作到深入理解其原理，再到关注运维实践，是一个逐步深入的过程。

希望我分享的这些学习资源和路径建议，能对正在入门或打算入门云原生开发的你有所帮助。我自己也是在不断学习中，云原生技术日新月异，保持好奇心和动手实践的热情非常重要。

如果你在学习过程中有任何问题或心得，也欢迎一起交流。

从《软件设计的哲学》谈代码的复杂性与应对

Fri, 10 Jan 2025 10:55:52 +0800

几个月前读完了《软件设计的哲学》这本书，在结合自己多年的工作体会，对于代码的可读性，可维护性有了系统性的体会，然后基于我记录的读书笔记然后经过AI的润色，形成了这篇笔记。希望对你也有所帮助。

读完《软件设计的哲学》，感觉像经历了一次代码的“深度体检”。这本书没有讲解具体的编码技巧，而是从更高的维度帮助我们重新审视代码复杂性的问题，并提出了许多实用的建议。今天，我想结合自己的理解，分享这本书带来的启发。

什么是代码的复杂性？

简单来说，复杂性就是那些让系统难以理解和修改的因素。它不仅仅指代码的行数或逻辑深度，还包括：

难以理解：即便是自己写的代码，过一段时间可能也看不懂，更别提其他人。
修改成本高：一个小改动需要改动多个地方，甚至引发新的问题。
模糊的改动范围：不知道该修改哪些模块才能实现目标，或者不确定修改后是否会引发其他问题。
难以修复的错误：修复一个 bug 可能需要大量时间，还可能引入新的问题。

复杂性的表现形式

复杂性并非抽象概念，它常以以下形式体现：

变更放大：一个简单需求改动需要修改多个模块甚至代码库。
认知负荷：完成一个任务需要了解大量背景知识或复杂细节。
未知的未知：修改代码时，不确定是否会引入新的问题。

复杂性的来源

复杂性通常来源于以下几点：

模块之间的依赖：一个模块的改动可能需要同步修改依赖它的其他模块。
晦涩难懂的代码：不清晰的变量名、函数名以及缺乏注释的逻辑。
文档不足：缺乏解释代码意图和约束的文档。

面对复杂性的两大策略

书中提到了解决代码复杂性的两种核心策略：

让代码更简单、更直观
- 通过清晰的命名、简洁的逻辑、规范的实现，让代码易于理解。
封装复杂性
- 将复杂逻辑封装起来，通过简洁的接口暴露给外部，用户无需关心内部细节。

如何应对复杂性？

以下是书中提到的一些有效方法：

模块化设计
- 将系统分解为独立模块，减少模块间的依赖。每个模块应只负责一个明确任务，提供清晰接口。
抽象
- 忽略不重要的细节，只暴露必要的信息。好的抽象能降低认知负荷并提高代码复用性。
信息隐藏
- 隐藏模块的内部实现细节，只暴露接口。这样能减少模块之间的耦合，降低修改风险。
设计通用接口
- 通用接口能隐藏细节并提高代码复用性。
专注于任务的知识
- 设计模块时，应关注任务所需的知识，而非任务发生的顺序。
注释代码
- 注释应解释代码的“为什么”，而非“是什么”。例如，描述变量单位、边界条件等。
清晰命名
- 使用准确且一致的命名，避免歧义。
先写注释，再写代码
- 先用注释明确表达代码意图，然后再实现。
设计两次
- 初步完成代码后，重新审视设计，思考是否有更好的接口和实现方式。
统一规范
- 制定团队代码规范，保持一致性，提高可读性。
显式代码优于隐式代码
- 代码应尽可能清晰易懂，避免晦涩技巧。

危险信号：什么时候该警惕复杂性？

以下是书中提到的一些“危险信号”，遇到这些情况时，需要考虑重构：

浅模块：接口与实现的复杂性相差无几。
信息泄漏：设计决策导致多个模块之间耦合。
时间分解：代码结构依赖操作执行顺序，而非基于信息隐藏。
过度暴露：API 暴露了不常用的功能。
重复代码：相同代码反复出现。
联合方法：两个方法间依赖性强，难以单独理解。
注释重复代码：注释仅重复代码内容。
含糊不清的名称：变量或方法名称传递不了有用信息。
难以描述：需要冗长文档解释变量或方法意图。
非显而易见的代码：代码行为或意图不直观。

软件设计的核心原则

书中总结了以下关键原则：

复杂性是逐步增加的：从小事做起，持续改进。
代码跑起来并不够：还需关注可读性和可维护性。
持续投入改善系统设计：不要忽视代码的长期维护成本。
模块应该足够深：接口要比实现简单得多。
简化接口：接口设计应尽可能简化最常见用法。
通用与专用分离：通用代码与专用代码应明确区分。
层次分明：不同层次应有不同抽象。
降低复杂性：始终关注减少认知负荷和模块耦合。
先设计，再实现：避免仓促决策，多次设计迭代。
注释不明显内容：好的注释可显著降低认知负荷。
代码是写给人看的：清晰性优先于实现技巧。

结语

《软件设计的哲学》让我意识到，软件开发不仅是实现功能，更是一门需要深思熟虑的艺术。它提醒我们，代码的核心目标是易于理解和维护。毕竟，代码是写给人看的，其次才是给机器看的。希望这些心得对你有所启发，让我们一起写出更清晰、更优雅的代码！

如何快速上手项目

Wed, 08 Jan 2025 10:55:52 +0800

职业生涯中接手过很多项目了，各种项目都接触过，一个对新人友好的项目一般具备如下特征：

完备的安装/功能文档
完备的技术方案，架构设计文档
合理的分层，清晰的代码目录结构
可读，可维护性高的代码

但是往往我们会忽略一个一个简单的指引性的文档：Quick Start，这个文档不需要很详细，只需要说明，如何快速上手的过程，具体的步骤链接到对应的文档即可。一般我们会在Quick Start上写明：

最简安装的步骤
主流程功能的使用
开发环境的搭建
开发注意事项
1. 包含组件的架构图
2. 包含代码的分层目录说明

这个文档需要由项目的负责人编写，在后续由项目的新人实践的过程中逐步完善。

当然这都是比较理想的情况，实际情况中，我们可能遇到的项目可能根本就没有文档，然后只有一个代码仓库的情况，那怎么才能快速上手呢？其实还是按照Quick Start的思路，只不过需要自己来摸索来了。

1. 安装

我相信不管什么项目，或多或少都有一些如何安装的文档，如果连一点这样的文档都没有，那就需要问其它同事了，如果连问都问不出来，那恭喜你赶快跑路吧，😂

因为我们是初次接触项目，不必搞懂安装的每个步骤，每个配置的含义，目标仅仅是把项目跑起来，能用起来，所以这里的目标就是安装最简化的方式把项目跑起来。当前的后端项目一般采用容器交付的形式，一般就交付镜像与helm chart，这种方式的安装理论来说是非常简单的，一条helm install 的命令就可以搞定。所以我们在交付的的时一定要在默认的配置中写好最简化的配置，这样新人就可以直接用默认的配置来安装。

2. 功能体验

安装好之后，我们就可以从产品的角度开始体验项目的相关功能，这里我们要聚焦到项目的核心功能上，跑完整个主要流程，不要在意细节，也不要急于把体验的功能与代码实现结合起来，我们只要梳理功能流程，数据的流转，数据的建模。然后有经验的程序员往往会在这个过程中思考，这个功能如果是我来做，我会怎么做。在这个过程中一定要有自己的输出，比如：

功能清单
功能流程图
数据模型
数据流转图

如果有思考如何实现，还可以记录这些：

技术选型
技术方案
架构设计

在体验过程中如果发现了问题，也需要记录下来，还有自己对项目的疑问，为什么要这么设计，这个功能解决的什么实际问题等等。

但是我们需要注意的是避免陷入细节，有些东西没搞懂就没搞懂，没有关系，我们是一个新人，搞不懂也正常，把没搞懂的问题记录下来，后续再逐步熟悉。

3. 组件拆解与用途分析

在功能体验完成后，我们就有了自己的对与项目的思考，也有了一些疑问，然后我们就可以从项目的依赖的各个组件来逐步搞清楚这些问题。比如项目中用了什么数据库，用了什么缓存等等。然后我们可以对照我们自己的分析来看看项目是不是真的就是想我们想想的来实现的，数据库的表设计是不是也跟我们的数据建模一致。经验丰富的程序员往往很快就能猜出项目的主要组件依赖，快速画出一个简单的架构图。

4. 项目代码分析

搞明白各个组件的用途后，我们需要的是单刀直入，从主要功能流程出发，找到对应代码的入口，然后按照我们整理的功能流程，梳理出代码流转的过程，在这个过程中我们就可以大体分析出项目代码中目录的分层，各个模块的功能了。我们还可以借助工具来绘制代码的依赖图，这样可以帮助我们快速的理解代码。

在阅读的过程中代码本身可能也会有我们看不惯的地方，这个时候我们需要把代码切出一个分支来，专门用来记录自己阅读时写的注释以及一些觉得要重构的点，但是千万不要直接开始动手，一定只是记录，打上标记，比如：

// TODO: 这里有待重构
// ? 为什么这里用的是这种方式

等等，也是把自己的疑问记录下来，后续有需要可以带着疑问去问同事。

在代码阅读的过程中，切记不要陷入细节，不要陷入细节，不要陷入细节。我们只需要搞清楚代码流转的过程即可，至于代码的实现细节，我们后续在解BUG的过程中再去逐步熟悉。

5. 从小问题入手，逐步上手

入手项目的初期不要好高骛远，我们从解小的BUG开始熟悉怎么正确的提交第一个PR，在这个过程中我们可以学习项目的规范，正确的写单元测试，然后解BUG的过程中我们不要看哪里的代码就只是哪里的代码，我们还需要关注模块的边界，了解整个模块都有一些什么功能。很多的BUG往往不是主要功能流程中的问题，在处理这些小的BUG的时候正是我们去了解其它非主要流程功能的好机会。

6. 新功能与重构

当我们对项目有一定的了解后，就可以做一些新功能了，然后在规划新功能时，往往我们需要对涉及到已有的代码做一些重构，我们需要把握代码重构的一个度，一定是有限处理对我们写新功能有阻碍的代码，然后需要考虑功能的后续迭代与未来的演进来重构。渐进式的重构，不要上来就搞大的，我相信很多程序员都希望能把代码写的跟符合自己的审美，但是初期还是要以功能为主，再实现功能的同时小步渐进式的重构。重构有很多技巧，我们可以把我们改不动的代码做隔离，先保证能跑起来，然后再完善。

总结

初入一个项目，我们可能会遇到很多很多问题，但是没有关系的，我们需要做的是把这些疑问都记录下来，然后带着疑问慢慢去熟悉，熟悉一个项目也需要一个过程，不要着急，1个星期不行，就1个月，遇到困难就及时寻求帮助。前人种树，后人乘凉。如果前人没能帮你种好树，那我们就把我们熟悉项目的过程整理成文档，留给后人，这样后人就可以少走很多弯路。

我的2024

Tue, 31 Dec 2024 10:55:52 +0800

今天是2024年的最后一天，我有这一下午的空闲时间，所以就让我来絮絮叨叨的写写我这神奇的2024年吧。

我是龙年出生的，所以2024年是我的本命年，年初的时候，老婆还有姐姐就给我准备了红内裤，红袜子。由于红袜子太过显眼了，所以这一年我的内裤都是红色的，哈哈。本命年，犯太岁，这一年工作上，心态上，都有一些变化，就让我在本命年的最后一天瞎写写吧。

我自己

我是80年代末生人，出生在一个小镇，是标准的小镇做题家。从高中开始基本就不怎么回家了，然后上大学，跑去了云南，双非一本，学的是热能与动力工程。我的同学大都找到了水电厂，火电厂的工作。工作好的去了三峡，一般就去了云南一些比较偏僻的电厂。而我呢毕业就失业了，后来找到一个海南的小电厂。工作2年后，我就来到了深圳，在躺了好几个月后，经一个亲戚的介绍到一个华为的软件外包公司学习做软件测试。

软件测试本身是没什么门槛的，然后我自认为还有点小聪明，也由于亲戚的安排，我所在的项目并不是纯粹的手工测试。而是偏向自动化的TCP/IP协议栈的测试，这个测试需要我写一些Lua脚本来模拟发送一些数据包来做测试。虽然这不是一个开发的工作，但是在这个过程中我还是学到不少东西，基本的协议栈，socket，还有一些基础的编程语言方面的知识。

后来又换了别的项目，做GUI跟网页的功能测试，我接手这个项目的测试的时候，里面还维护了一堆Java写的基于一个IBM的测试框架的自动化测试用例。这可难倒我了，以至于大半年的时间我都没跑过这个自动化的测试，一直都是手动测试。想想不是办法，还是搞搞自动化的测试吧，Java是一时半会学不会的，不如自己学一学Python自动化吧，就这样我接触到Python编程。我依然记得在某一天我用Python写了一个自动匹配关键字的工具用来做安全检查后，获得了华为的持续集成奖。

就这样我在这个软件外包公司做测试做了4年，然后我决定还是找一份Python开发的工作吧，于是在学习了Django开发后，我就裸辞了。

在2015年的那个激荡的万众创业，万众创新的2015年，只要你会写点代码，就能找到工作。于是我入职了一家很小的公司做Python后端开发，然后半年之后，我就被优化了。这个时候我确实怀疑过自己，我是不是真的适合做开发呢，我能拿出手的项目只有我在github上写的一个Django的论坛。

然后就又开始找工作了，不是很顺利，直到2015年下半年的某一天，我收到了一封邮件，嗯，一家我没有投递的公司邀请我去面试。后来才从这家公司的CTO口中得知，他是在看到我的github才邀请我去面试的，然后我就入职了这家公司，继续做Python的后端开发。在这家公司我又找到了自信。然后在这里我发现我做测试的经历还是有用的，毕竟我的自测做的比较细致，以至于我的效率以及质量都远超其他同事。然后由于效率的提升，很快我就开始负责更基础的框架开发，引入了DRF框架，还尝试做了RPC框架，然后又引入了API网关，认识了Openresty，你看，Openresty又回到了我最初做测试的老本行Lua上面。

由于在github上面尝到了甜头，后续我又在github上写了一些Openresty的小项目，也有Python RPC相关的项目，然后也写了一些我觉得还行的博客文章。我感觉我的能力还是又比较大的提升的，我想我是不是再出去找找机会呢？所以我又开始面试了，不出意外的还是被打击到了，无非是因为非科班出生，然后基础很差。有一个比较nice的面试官推荐我去读一读深入理解计算机系统，然后我就买了这本书。年轻的时候还是比较要强的，不喜欢认输，所以花了好几个月死啃这本书，然后再回顾自己的在工作中点点滴滴，确实对编程这个工作有了更多的理解。再然后我就买了更多的书，在douban上找评分高的书，补齐了很多基础知识。

时间来到了2018年，很幸运的是我通过了腾讯的面试，这里面有我读书的能力提升，也有不停在github上写项目的努力，还有我那几年积累下来的工作经验。

腾讯

初入腾讯，我是在一个运维组里的唯一的开发，我接的需求都是我的运维同事通过开发工具来改善他们的运维工作。这期间有一个直播推流相关的需求对我来说算是一个契机，促成了我从Python程序转向Golang程序员。在这个组里做了一年后，我觉得我做的的事情都不具备持久性，没有一个清晰的未来，所以我决定换一个组，于是我来到了蓝鲸的开发组。

在腾讯作为一个非科班出身的新人，我并没有觉得自己能做很久，我脑子里一直有一个念想就是做个几年，有了大厂光环，然后再出去作为一个架构师找一份新的工作。但是我在蓝鲸确实认识了一群nice的同事，然后这一做就是5年。这期间我一直专注在一个项目上，可以说成为了领域内的专家。持续的一直做一件事情有好处，也有坏处，好处是你可以在这个领域内做到极致，坏处是你很难跳出这个领域。

在大厂，每半年一次的考核，催促着我成长，沟通能力，项目管理能力，架构能力，规划能力等等，我都有实实在在的成长。然而在本命年的这一年，我还是觉得我可以离开了，毕竟互联网35岁的危机，年纪越大感受越深。

新工作

虽然顶着大厂光环，但是在2024年36岁的年纪，找工作还是很困难，面试了很多，只要涉及写算法什么的基本都挂了，然后我就降薪入职了现在的公司。我有了更多的时间，然后写了更多的文章，也学习了Rust编程，新的Rust的项目也都放到了github上。我不知道自己的职业生涯还能走多远，但是我觉得我依然热爱编程。

随着AI编程应用越来越多，我觉得对于头部的程序员来说，他们的优势会越来越大，因为AI会极大的提升他们的效率，这对中下部的程序员可能是一个灾难。可能会因为这个整个市场的行情会越来越差，所以我个人觉得持续学习，终身学习在这个时代是必须的。

生活

3月的时候跟老婆来了一次广西自驾游，从深圳出发，开着我的电车第一次长途自驾，感谢老婆的辛苦做了攻略，在广西边境看了大瀑布，也第一次体验了溶洞速降，还看到了美丽梦幻的三门海。也去了一些小众的景点。在广西的山间小路悬崖边小心的开着车，在溶洞里面听着水流的声音，看着头顶的灯光，那种感觉真的很棒。

7月的时候，正式从腾讯离职了，然后也没找到工作，就在家里躺平静静的思考了，关于工作不焦虑是假的，但是生活也是要继续的。新的工作开始后，我有了更多的时间陪小孩，看着小孩的成长，确实又感觉生活不一样了，小孩的需求没那么多，更多是我都是作为一个捧哏的角色，看着她玩耍，配合她的各种需求。

关于未来，世界变化很快，我也不知道未来会怎么样，在深圳还没有买房，没啥压力，在广西游的过程中有个小小的种子种在了心里，什么时候能在广西找个山好水好的地方过上慢生活呢。

结尾

回头看2024年，这一年过得挺特别的，有变化也有成长。无论是工作上的转折，还是生活中的点滴，我都在慢慢适应、慢慢调整。虽然未来会怎样还不好说，但我想继续保持学习的习惯，保持对生活的热情，也尽量多陪陪家人。生活总是这样，充满未知，但也正因为如此，每一天都值得认真过好。