我们团队做了多年自研算法，最近遇到一个棘手的问题：新算法理论上更好，但无法客观证明。这篇文章分享我们从零开始设计评测体系的思路，以及背后借鉴的业界方法论。

一、问题从哪里来

团队的自研算法已经跑了好几年了，线上版本整体稳定。随着持续迭代，新版本出来了——直觉和小范围测试都感觉好不少。但老板问"能不能证明新算法更好、好多少"的时候，我们沉默了。

问题出在哪？历史积累的标注数据，是由当前算法自己打的标签。 用"当前算法的判断"来评测新算法，像让运动员给自己裁判，偏差是天然存在的。

而且这不只是一个数据问题，暴露出来的是整套评测体系的缺失：

• 没有标准数据集：历史标注由当前算法产出，不中立
• 人工标注成本高：全靠人工既慢又贵，难以规模化
• 没有评测机制：每次评估都要从零开始，结论无法横向对比
• 切换决策没有依据：算法切换是高风险操作，不能只靠直觉

二、业界是怎么解决这类问题的

着手设计方案前，我们调研了业界的成熟做法。有意思的是，这些方法各自解决一个子问题，拼在一起刚好能覆盖我们的困境。

1. LLM-as-Judge：让 AI 当裁判

没有标准答案，能不能让一个够强的 AI 来替代人工做判断？

这就是 LLM-as-Judge 的出发点。MT-Bench（NeurIPS 2023）的研究表明，GPT-4 与人类专家的评判一致率超过 80%。更重要的是，AI 裁判不只给分，还会解释理由——而这些理由本身就是定位算法问题的线索。

当然 AI 裁判也有自己的偏见：

• 位置偏见：倾向于选排在前面的答案（对策：评两次并交换顺序）
• 啰嗦偏见：回答越长越容易高分（对策：评分细则里明确"不因长度加分"）
• 自恋偏见：偏好与自身风格相近的内容（对策：换不同家族的模型当裁判）

对我们来说，LLM-as-Judge 最大的价值不是"替代人工打分"，而是用来生产标准数据集。让 LLM 和现有算法同时跑一批数据，盯着分歧案例让人工仲裁——LLM 承担初筛，人工只处理真正有争议的地方，成本直接降一个数量级。

2. Weak Supervision：让不完美的规则联合投票

数据量大的时候，不可能每条都过 AI 裁判。弱监督提供了一条批量打标的路。

思路很直接：把多个"不完美但有用的信号"组合起来投票。比如：

• 现有算法的判断（准确率 70%）
• 大模型的判断（准确率 85%）
• 规则判断：文本长度差异超过 50%（准确率 60%）

单看每条规则都不够可靠，但斯坦福开发的 Snorkel 框架能自动推算每条规则的可信度，加权投票后准确率大幅提升。关键是不需要任何标准答案——它靠规则之间的"同意/打架"模式反推各规则的可靠性。这个方案 Google 已经在工业规模落地（DryBell，2019）。

LLM-as-Judge 解决质量问题（谁来判断对错），弱监督解决规模问题（怎么批量打标）。前者精但慢，后者快但粗——两者配合，弱监督负责大批量初标，LLM-as-Judge 负责精细复核。

3. Active Learning：让模型告诉你标哪些数据最值钱

标注预算有限，怎么把钱花在刀刃上？

主动学习的答案是：标那些模型最拿不准的数据，因为标了之后进步最大。就像一道一眼就会的题做了没什么收获，而那道做到一半卡住的题，看答案才真的有提升。

具体策略之一是分歧采样：让多个模型对同一条数据投票，意见最不一致的优先标注。这和我们的直觉不谋而合——评测时优先看各算法分歧大的案例，本质上就是主动学习。

4. ELO 评分：不需要标准答案的排行榜

王者荣耀的段位系统背后是 ELO 算法：不需要知道每个人的"绝对实力"，只需要积累大量"A 和 B 谁赢了"的相对比较，就能得出全局排名。

在算法评测里，它的价值在于：在标准数据集还不够多的早期，先给出一个相对排名，让初步决策有据可依。

具体操作：让各算法对同一批数据分别给出判断和解释，由 AI 裁判选"哪个解释更有道理"，记录胜负。积累几百次 PK 之后，排行榜自然浮现。

这套机制还天然支持多维度评价——不只看结论对不对，也评推理过程合不合理。两个算法都答对了，但一个靠真正理解语义，另一个靠碰巧匹配关键词，只看结论是区分不出来的。

5. Data Flywheel：把前四个方法串成闭环

前四个方法各自解决评测的某个子问题。数据飞轮不是一个新方法，而是一种设计理念——把这些方法连成一个持续自动迭代的闭环，让整个体系越用越好。

微软的 Arena Learning（2024）是目前最先进的工程实践：用 AI 模拟对战替代人工投票，效率是人工方式的 40 倍，与人类判断一致率达到 98.79%，整个训练过程几乎不需要人工介入。

三、我们的设计：自举评测飞轮

把上述方法论落到具体场景，核心是一个自举（Bootstrapping）的评测飞轮：

整个体系的核心是 AI 裁判 Agent——它不是静态的打分工具，而是一个会持续成长的 Agent：

其他所有模块——标准数据集、难例库、Skill 库、报告层——都在围绕这个 Agent 服务。

四、系统模块设计

完整系统由以下模块构成：

几个关键设计决策值得单独说：

标准数据集分公开集和保留集。 公开集供算法调优参考，保留集只在最终评测时用。防止算法针对评测集过拟合（"刷榜"）——这和 Kaggle 的 public/private leaderboard 设计同理。

难例库单独管理。 各算法分歧大、人工也难判断的边界案例单独收录。这批数据是提升 AI 裁判天花板的核心资产，也是算法改进最值得攻坚的方向。

评测结果要版本化。 AI 裁判在升级，标准数据集也在扩充。如果评测结果不绑定具体的裁判版本和数据集版本，历史数据就失去了可比性。

五、落地路径

MVP：先回答"新算法是否比当前算法更好"

MVP 不追求完整系统，只要能支撑第一次切换决策就够了：

1. 定义评分维度：明确从哪几个维度打分，为每个维度写评分细则
2. 搭基础 AI 裁判：把维度和细则写入 Prompt，跑通单条打分
3. 采集 300-500 条数据：重点选各算法分歧大的案例，少量随机抽取防止盲区
4. 人工标注：逐条确认正确答案，建立初始标准数据集（⚠️ 标注人员需要有领域判断力，这一步偷不了懒）
5. 跑离线对比评测：AI 裁判对各算法输出打分，人工复核不确定案例
6. 归因 AI 裁判的错误：补充 Skill，迭代直到准确率 ≥ 85%（⚠️ 需提前定好阈值，避免无限迭代）
7. 输出切换决策报告：指标对比 + 典型错误案例 + 切换风险评估

第二阶段：扩充评测基准

• 建立难例库，对高频错误类型专项攻坚
• 引入多信号融合批量生成初始标签，降低人工成本
• 标准数据集切分公开集 / 保留集

第三阶段：线上持续监控，形成飞轮

• 线上流量分层抽样，自动进入评测流程
• 周期性输出质量报告，设置报警阈值
• 线上发现的新难例自动进难例库，人工复核结果反哺 AI 裁判
• 引入 ELO/Pairwise 排行榜，作为标准数据集评测的补充

六、几个反直觉的地方

回顾整个体系，有几点讨论时觉得别扭，但仔细想都有道理：

LLM 不是用来替代人工的，是用来生产 GT 数据的。 很多人提到 LLM-as-Judge，第一反应是"用 AI 替代人工打分"。但在没有标准数据集的阶段，LLM 更大的价值是充当 GT 数据的初筛器——它处理大量案例，人工只处理 LLM 和算法产生分歧的那一部分。

ELO 不是成熟后用的，是数据集不够时用的。 很多人会觉得 ELO 是更"高级"的评测方式，应该等体系成熟后再上。但它真正的价值在早期——标准数据集还不够的时候，用 ELO 先给出相对排名，支撑初步决策。数据集建好后，ELO 反而退场。

评算法不只评结论，还要评推理过程。 两个算法都答对了，但一个靠真正理解语义，另一个靠碰巧匹配关键词——只看结论无法区分。评推理过程，才能判断算法在新场景下的泛化能力。

七、总结

这套方案的本质，是用自举 + 飞轮的方式，绕开"没有 GT 就无法评测"的死结：

• 用 LLM 做初始裁判，生产第一批 GT 数据
• 用主动学习，把有限的人工精力花在最值钱的地方
• 用弱监督，在数据集扩充阶段降低成本
• 用 ELO，在数据集不足时提供相对排名
• 把以上连成飞轮，让整个体系自动越转越好

这套方法论不局限于我们的场景，任何面临缺乏标准数据集、需要客观评测多版本算法问题的团队，都可以参考这个框架。

飞轮刚开始推很费力，但只要转起来，就会越来越省力。

参考文献

• Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena（Zheng et al., NeurIPS 2023）
• G-Eval: NLG Evaluation using GPT-4（Liu et al., EMNLP 2023）
• Snorkel: Rapid Training Data Creation with Weak Supervision（Ratner et al., VLDB 2018）
• Chatbot Arena: An Open Platform for Evaluating LLMs（LMSYS, 2024）
• Arena Learning: Build Data Flywheel for LLMs Post-training（Microsoft Research, 2024）

Let Me Introduce Myself — A Developer Working on WFM Systems

Hi, my name is [Your Name], and I'm a software developer based in China. Let me tell you a little bit about who I am and what I do every day.

大家好，我叫[你的名字]，是一名在中国工作的软件开发者。让我简单介绍一下我是谁，以及我每天在做什么。

I studied Computer Science in university. Back then, I spent a lot of time learning the fundamentals — things like algorithms, data structures, operating systems, and databases. At first, some of it felt very theoretical. But as I started working, I realized how much that foundation actually matters. The things I learned in school show up in my work more often than I expected.

我大学学的是计算机科学。那时候花了很多时间学基础知识——算法、数据结构、操作系统、数据库这些。一开始觉得有些内容特别理论化，但等到真正工作之后才发现，这些基础知识其实非常重要，在工作中用到的频率比我预想的高得多。

After graduating, I joined a tech company focused on Workforce Management systems, which is often called WFM. In simple terms, WFM software helps businesses manage their employees more efficiently. It covers things like predicting how busy a company will be, automatically creating work schedules, tracking attendance, and generating reports. Our clients are usually large companies that need to manage hundreds or even thousands of employees across different locations.

毕业后，我加入了一家专注于劳动力管理系统的科技公司，这类系统通常被称为 WFM。简单来说，WFM 软件帮助企业更高效地管理员工，包括预测业务量、自动生成排班表、追踪考勤、生成报表等功能。我们的客户通常是大型企业，需要在不同地点管理成百上千的员工。

My role is on the research and development side. That means I'm part of the team that actually builds the system. My day-to-day work includes developing new features, fixing bugs, improving system performance, and reviewing my teammates' code. I work closely with product managers, QA engineers, and business analysts. It's not just about writing code — it's also about understanding what the business needs and finding the best technical way to solve it.

我的岗位属于研发方向，也就是说我是真正构建这套系统的团队中的一员。我日常的工作包括开发新功能、修复 bug、优化系统性能，以及审查同事的代码。我跟产品经理、测试工程师和业务分析师密切合作。这份工作不仅仅是写代码，更重要的是理解业务需求，并找到最佳的技术方案来解决问题。

One thing I really enjoy about my job is that the problems are practical and real. When I build a scheduling feature, I know that real managers will use it every day. That sense of impact keeps me motivated.

我很喜欢这份工作的一点是，面对的问题都是实际的、真实的。当我开发一个排班功能的时候，我知道真正的管理者每天都会用到它。这种实实在在的影响力让我一直保持着动力。

Of course, the work comes with challenges too. Requirements can change, technical problems pop up unexpectedly, and deadlines are always there. But I've learned to stay calm, break problems into smaller pieces, and communicate clearly with my team.

当然，工作中也会遇到挑战。需求可能会变，技术问题会突然冒出来，截止日期也总是如影随形。但我已经学会了保持冷静，把问题拆解成小块，并且跟团队保持清晰的沟通。

Outside of work, I'm always trying to learn something new — whether it's a new technology, a better way to write code, or even improving my English. I believe that curiosity and a willingness to keep growing are the most important qualities for anyone working in tech.

工作之外，我一直在尝试学习新东西——不管是新技术、更好的编码方式，还是提升英语水平。我相信，好奇心和持续成长的意愿，是在科技行业工作的人最重要的品质。

That's a little bit about me. Nice to meet you!

以上就是关于我的一点简单介绍。很高兴认识大家！

What is Workforce Management?

Have you ever walked into a store and noticed that there are always enough staff to help you, even on busy days? Or called a customer service hotline and got connected to someone quickly? That doesn't happen by accident. There is a lot of planning behind it. That's where Workforce Management, or WFM, comes in.

你有没有走进一家商店，发现即使在最忙的日子里，也总是有足够的员工来帮助你？或者打客服热线的时候，很快就有人接听？这些都不是碰巧发生的，背后有大量的规划工作。这就是劳动力管理（Workforce Management，简称 WFM）发挥作用的地方。

So, what exactly is WFM? Simply put, it's a system that helps companies manage their employees more smartly. It covers several key areas.

那么，WFM 到底是什么？简单来说，它是一套帮助企业更聪明地管理员工的系统，涵盖了几个关键领域。

First, there's forecasting. This means predicting how busy a company will be in the future. For example, a call center might get a lot more calls on Monday mornings than on Friday afternoons. A good WFM system can predict these patterns and help managers plan ahead.

首先是预测。也就是预判公司未来的业务量。比如说，一个呼叫中心周一早上的来电量通常比周五下午多很多。一个好的 WFM 系统能识别这些规律，帮助管理者提前做好安排。

Next is scheduling. Once you know how many people you need, you have to arrange their shifts. This sounds simple, but it's actually quite complex. You need to balance business needs, employee preferences, and labor laws all at the same time. A WFM system can do this automatically and much faster than doing it by hand.

接下来是排班。当你知道需要多少人之后，就得安排他们的班次。这听起来简单，实际上非常复杂。你需要同时兼顾业务需求、员工偏好和劳动法规。WFM 系统可以自动完成这些工作，比手动操作快得多。

There's also real-time monitoring. Even the best plan can go wrong on the day. Maybe too many people called in sick, or there's a sudden rush of customers. WFM tools help managers see what's happening right now and make quick adjustments.

还有实时监控。再好的计划到了当天也可能出问题。也许太多人请了病假，或者突然涌来一大批客户。WFM 工具能帮助管理者看到当前的实时情况，并快速做出调整。

Finally, there is reporting and analytics. After everything is done, companies want to know: did we have the right number of people? Were our predictions accurate? These reports help businesses keep improving over time.

最后是报表和数据分析。一切结束后，企业想知道：我们的人手安排合理吗？我们的预测准确吗？这些报表帮助企业不断优化改进。

I work as a developer on a WFM system, which means my job is to build and improve these tools. It's really interesting because I get to see how technology can solve real business problems. Every feature I work on has a direct impact on how companies run their day-to-day operations.

我是一名 WFM 系统的开发者，我的工作就是构建和改进这些工具。这份工作非常有趣，因为我能亲眼看到技术是如何解决实际业务问题的。我做的每一个功能，都会直接影响企业的日常运营。

WFM might not be the most well-known field in tech, but it plays a huge role in keeping businesses running smoothly. And honestly, I think that's pretty cool.

WFM 也许不是科技行业里最广为人知的领域，但它在保障企业顺畅运转方面发挥着巨大的作用。说实话，我觉得这挺酷的。

A Day in My Life as a WFM Developer

Have you ever wondered what a software developer actually does all day? People sometimes think we just sit in front of a computer and type code for eight hours straight. But the reality is quite different — and honestly, a lot more interesting.

你有没有好奇过软件开发者一整天到底在干什么？有些人觉得我们就是坐在电脑前连续敲八个小时的代码。但现实其实大不相同——而且说实话，有趣得多。

Let me walk you through a typical day in my life as a WFM developer.

让我带你看看我作为一名 WFM 开发者的典型一天。

My day usually starts with checking messages and emails. Before I even open my code editor, I want to know if anything urgent came up overnight. Sometimes a client reports a bug, or a teammate has a question about a feature I built. I try to handle these things first so nobody is blocked waiting for me.

我的一天通常从查看消息和邮件开始。在打开代码编辑器之前，我会先看看昨晚有没有什么紧急的事情。有时候客户报了一个 bug，或者同事对我做的某个功能有疑问。我会优先处理这些事情，免得有人因为等我而耽误了工作。

After that, I join our daily standup meeting. This is a short team meeting — usually just fifteen minutes — where everyone shares what they did yesterday, what they plan to do today, and if they have any problems. It's a great way to stay in sync with the team without spending too much time in meetings.

然后是参加每日站会。这是一个简短的团队会议——通常只有十五分钟——每个人分享自己昨天做了什么、今天打算做什么、以及遇到了什么问题。这是一种既能和团队保持同步，又不用花太多时间开会的好方式。

Then comes the main part of my day: coding. Right now I'm working on improving our scheduling module. This could mean writing new features, fixing bugs, or refactoring old code to make it cleaner and faster. I usually put on some music and get into a focused mode. These deep work hours are my favorite part of the day.

接下来就是一天中最主要的部分了：写代码。我目前在优化我们的排班模块。这可能是开发新功能、修复 bug，也可能是重构旧代码让它更简洁高效。我通常会放点音乐，进入专注模式。这些深度工作的时间是我一天中最喜欢的部分。

Around midday, I might have a meeting with the product team. They explain what the business needs, and I help figure out how to build it technically. These conversations are really valuable because they help me understand the "why" behind the work I'm doing.

中午前后，我可能会和产品团队开个会。他们讲解业务需求，我来帮忙想怎么从技术上实现。这类对话非常有价值，因为它们能帮助我理解自己工作背后的"为什么"。

In the afternoon, I often do code reviews. This means reading my teammates' code and giving feedback. It's not just about finding bugs — it's also about sharing knowledge and keeping the codebase consistent.

下午我经常会做代码审查。就是阅读队友写的代码并给出反馈。这不仅仅是为了找 bug，也是为了分享知识、保持代码风格的一致性。

By the end of the day, I write a quick note to myself about where I stopped and what I need to pick up tomorrow. This small habit saves me a lot of time the next morning.

一天结束的时候，我会给自己写一个简短的笔记，记录做到哪里了、明天需要接着做什么。这个小习惯能帮我第二天早上节省不少时间。

Every day is a little different, and that's what I enjoy most about this job. There's always something new to learn or solve.

每一天都有些不同，这正是我最享受这份工作的地方。总有新的东西要学，新的问题要解决。

How We Turn Business Needs into Technical Solutions

One of the most interesting parts of my job is bridging the gap between business and technology. Our clients don't come to us saying "I need an API endpoint." They come to us saying "I need my managers to spend less time on scheduling." My job is to translate that into something we can actually build.

我工作中最有意思的部分之一，就是在业务和技术之间架起桥梁。客户不会跑来跟我们说"我需要一个 API 接口"，他们会说"我希望我的管理者能少花点时间在排班上"。而我的工作，就是把这些需求转化成我们能实际构建的东西。

So how does that process work? Let me break it down.

那这个过程是怎样的呢？让我来拆解一下。

It usually starts with a requirement discussion. The product manager or business analyst talks to the client to understand their pain points. Then they bring those findings to us, the developers. At this stage, I ask a lot of questions. What exactly is the problem? How often does it happen? How many people are affected? The more I understand the problem, the better solution I can design.

通常从需求讨论开始。产品经理或业务分析师和客户沟通，了解他们的痛点。然后把这些发现带给我们开发者。在这个阶段，我会问很多问题。问题到底是什么？多久发生一次？影响了多少人？我对问题理解得越深，设计出来的方案就越好。

Next comes technical planning. I think about how to solve the problem within our existing system. Can I reuse something we already have? Do I need to build something new? Are there any risks or limitations I should be aware of? I usually write a short document explaining my plan before I start coding. This helps me think clearly and gives my teammates a chance to spot any issues early.

接下来是技术方案设计。我会思考如何在现有系统内解决这个问题。能不能复用已有的东西？需不需要重新开发？有没有需要注意的风险或限制？在开始写代码之前，我通常会写一个简短的文档来说明我的方案。这帮助我理清思路，也让队友有机会尽早发现潜在问题。

Then I start building. This is where the actual coding happens. I try to write clean, readable code because other people will need to read and maintain it in the future. I also write tests to make sure everything works as expected.

然后就开始动手开发了。这是真正写代码的环节。我会尽量写出干净、易读的代码，因为以后其他人也需要阅读和维护它。我还会写测试来确保一切按预期运行。

After that, we go through testing and review. My teammates review my code, the QA team tests the feature, and we fix any issues that come up. This part takes more time than most people expect, but it's really important for quality.

之后是测试和评审阶段。队友们审查我的代码，QA 团队测试功能，我们修复发现的所有问题。这个环节花的时间比大多数人想象的要多，但对保证质量来说非常重要。

Finally, we release and monitor. Once the feature is live, we watch closely to make sure it's working well in the real world. Sometimes things look fine in testing but behave differently with real data.

最后是发布和监控。功能上线后，我们会密切关注它在真实环境中的运行情况。有时候测试环境里一切正常，但到了真实数据下表现却不一样。

This whole process taught me that good software is not just about writing code. It's about deeply understanding people's problems and caring about the solution you deliver.

整个过程让我明白，好的软件不仅仅是写代码。更重要的是深入理解用户的问题，并用心打磨你交付的解决方案。

Working Across Teams: Developers and Non-Technical Colleagues

When I first started working as a developer, I thought the hardest part would be writing complex code. But over time, I realized that one of the biggest challenges is actually communication — especially with colleagues who have a different background.

刚开始做开发的时候，我以为最难的部分是写复杂的代码。但随着时间的推移，我发现最大的挑战其实是沟通——尤其是和背景不同的同事之间的沟通。

In my daily work, I collaborate with product managers, QA engineers, business analysts, and sometimes even clients. Not everyone has a technical background, and that's completely fine. But it does mean I need to adjust the way I explain things.

在日常工作中，我需要和产品经理、QA 工程师、业务分析师合作，有时甚至直接和客户打交道。不是每个人都有技术背景，这完全没问题。但这意味着我需要调整自己表达的方式。

For example, when a product manager asks me "how long will this feature take?", I can't just say "it depends." I need to give a rough estimate and explain the key factors. If I say "there might be database performance issues that could slow us down," I should also explain what that means in plain language — something like "the system might run slowly when too many people use it at the same time."

比如说，当产品经理问我"这个功能要做多久？"的时候，我不能只回答"看情况"。我得给一个大概的估时，并解释关键的影响因素。如果我说"可能会有数据库性能问题拖慢进度"，我还应该用通俗的语言解释清楚——比如说"同时使用的人太多时，系统可能会变慢"。

I've learned a few things that really help with cross-team communication.

我总结了几条对跨团队沟通真正有帮助的经验。

First, avoid jargon when possible. Technical terms are efficient among developers, but they can confuse others. I try to use simple, everyday language when talking to non-technical colleagues.

第一，尽量避免使用专业术语。技术词汇在开发者之间很高效，但容易让其他人困惑。和非技术同事交流时，我尽量使用简单、日常的语言。

Second, use examples and comparisons. Abstract concepts become much clearer with a concrete example. Instead of explaining what an API is in technical terms, I might say "it's like a waiter in a restaurant — it takes your order and brings back what you asked for."

第二，多用例子和类比。抽象的概念配上一个具体的例子就清楚多了。与其用技术术语解释 API 是什么，我可能会说"它就像餐厅里的服务员——接你的单，然后把你要的东西端过来"。

Third, listen more than you talk. Understanding what the other person actually needs is more important than showing off your technical knowledge. I've saved a lot of time by asking "what problem are you trying to solve?" before jumping into solutions.

第三，多听少说。理解对方真正需要什么，比展示你的技术知识更重要。在急着给方案之前先问一句"你想解决什么问题？"，帮我省了不少时间。

Working across teams has made me a better developer and a better communicator. I think the best engineers are not just good at coding — they're good at understanding people too.

跨团队协作让我成为了更好的开发者，也成为了更好的沟通者。我认为最优秀的工程师不仅代码写得好，也善于理解他人。

Work-Life Balance in a Tech Company

If you ask most developers about work-life balance, you'll probably get a mixed response. Some will say the tech industry is full of long hours and burnout. Others will say they love what they do and don't even notice the time. My experience is somewhere in between.

如果你问大多数开发者关于工作与生活平衡的看法，得到的答案可能五花八门。有些人会说科技行业加班成风、容易倦怠。也有人说他们热爱自己的工作，根本感觉不到时间的流逝。我的体验介于两者之间。

Let me share what work-life balance actually looks like for me, and what I've learned along the way.

让我分享一下工作与生活的平衡对我来说到底是什么样的，以及我在这个过程中学到了什么。

When I first started my job, I often worked late. There was always one more bug to fix or one more feature to finish. I thought putting in extra hours showed dedication. But after a while, I noticed that I was getting tired, making more mistakes, and actually becoming less productive. That was a wake-up call.

刚开始工作的时候，我经常加班。总有一个 bug 没修完，或者一个功能没做完。我以为多加班体现的是敬业精神。但过了一段时间，我发现自己越来越疲惫，犯的错越来越多，效率反而更低了。这给我敲响了警钟。

I started making some changes. The first thing I did was set a clear end time for my workday. Unless there was a real emergency, I would stop working at a certain hour. This sounds simple, but it was actually hard to stick to at first.

于是我开始做出一些改变。第一件事就是给自己设定一个明确的下班时间。除非遇到真正的紧急情况，到了那个时间我就停下工作。这听起来简单，但一开始其实很难坚持。

I also started protecting my weekends. I try not to check work messages on weekends unless something is truly urgent. Having two full days to rest and recharge makes a huge difference. I come back on Monday feeling much more energetic and focused.

我还开始保护自己的周末时间。除非有真正紧急的事，我尽量不在周末查看工作消息。拥有完整的两天休息和充电时间，效果完全不一样。周一回来的时候，我感觉精力充沛、注意力也更集中。

Outside of work, I make time for things I enjoy. Whether it's exercise, spending time with family, reading, or just taking a walk, these activities help me reset mentally.

工作之外，我会留出时间做自己喜欢的事情。不管是锻炼、陪家人、看书还是出去走走，这些活动都能帮我从精神上恢复过来。

I've also learned to communicate boundaries at work. If I'm overwhelmed with tasks, I say so instead of silently struggling. Most managers appreciate honesty and would rather adjust the workload than have a burnt-out team member.

我还学会了在工作中表达自己的边界。如果任务太多扛不住了，我会直接说出来，而不是默默硬撑。大多数管理者都欣赏坦诚，他们宁愿调整工作量，也不愿意看到团队成员累垮。

Work-life balance doesn't mean working less. It means working sustainably. In the long run, taking care of yourself makes you a better employee — and a happier person.

工作与生活的平衡不是说要少工作，而是要可持续地工作。从长远来看，照顾好自己才能让你成为更好的员工——也成为更快乐的人。

Growing in Your Career as a Software Developer

Career growth is something almost every developer thinks about. How do I get better at my job? When will I get promoted? What skills should I focus on? These are questions I've asked myself many times.

职业成长是几乎每个开发者都会思考的事情。怎样才能把工作做得更好？什么时候能升职？应该重点提升哪些技能？这些问题我自己也问过很多次。

Let me share some things I've learned from my own experience.

让我分享一些从自身经历中学到的东西。

The most obvious way to grow is to improve your technical skills. This means writing better code, learning new technologies, and understanding your system more deeply. In WFM development, for example, I've had to learn about scheduling algorithms, data processing, and system performance. Each new challenge taught me something valuable.

最直接的成长方式就是提升技术能力。这意味着写出更好的代码、学习新技术、更深入地理解你的系统。以 WFM 开发为例，我需要学习排班算法、数据处理和系统性能优化。每一个新挑战都让我学到了有价值的东西。

But technical skills are only part of the picture. As you move up in your career, soft skills become just as important. Can you explain your work clearly? Can you help junior teammates grow? Can you manage a project without someone telling you what to do every step of the way? These abilities matter a lot when it comes to promotions.

但技术能力只是全貌的一部分。随着职业发展，软技能变得同样重要。你能清楚地表达自己的工作吗？你能帮助初级同事成长吗？你能在没人手把手指导的情况下独立管理项目吗？这些能力在晋升时非常关键。

Another thing that helped me grow was taking on challenges outside my comfort zone. When a difficult task came up and no one was rushing to take it, I volunteered. It was stressful sometimes, but I always learned something new. Comfort zones are cozy, but they don't help you grow.

另一个帮助我成长的做法是主动承担舒适区之外的挑战。当一个棘手的任务出现而没人主动认领时，我会站出来。压力有时候确实很大，但我总能学到新东西。舒适区虽然安逸，但它不会帮你成长。

I also think it's important to ask for feedback regularly. Don't wait for your annual performance review. Talk to your manager and teammates more often. Find out what you're doing well and where you can improve. This kind of honest feedback is one of the best tools for growth.

我还认为定期寻求反馈非常重要。不要等到年度绩效评估才去了解情况。多和你的主管、队友交流。弄清楚自己哪些方面做得好，哪些方面还可以改进。这种坦诚的反馈是最好的成长工具之一。

Finally, be patient. Career growth is not always a straight line. There will be times when you feel stuck or overlooked. That's normal. Keep learning, keep contributing, and trust the process.

最后，要有耐心。职业成长并不总是一条直线。有时候你会觉得停滞不前或者被忽视，这很正常。保持学习、持续贡献，相信这个过程。

The best investment you can make in your career is in yourself.

你能为自己的职业生涯做出的最好投资，就是投资自己。

Challenges and Solutions During Project Development

Every project sounds great at the beginning. The goals are clear, the team is motivated, and the timeline seems reasonable. But somewhere along the way, things get complicated. That's just the reality of software development — and honestly, how you handle those challenges says a lot about you as a developer.

每个项目一开始听起来都很美好。目标清晰、团队干劲十足、时间表看起来也合理。但做着做着，事情就变得复杂了。这就是软件开发的现实——说实话，你如何应对这些挑战，很大程度上反映了你作为开发者的能力。

Let me share some common challenges I've faced in my projects and how I dealt with them.

让我分享一些我在项目中遇到的常见挑战，以及我是如何应对的。

One of the most frequent problems is unclear requirements. Sometimes a client or product manager describes what they want, but the details are vague. If I just start coding based on my assumptions, I might build the wrong thing entirely. My solution is to ask more questions upfront and write down my understanding for confirmation before I start. A short document that says "here's what I think we're building" can save weeks of rework later.

最常见的问题之一是需求不明确。有时候客户或产品经理描述了他们想要的东西，但细节很模糊。如果我只凭自己的假设就开始写代码，可能会做出完全不对的东西。我的解决办法是在动手之前多问问题，把自己的理解写下来让对方确认。一份简短的"这是我理解的我们要做的东西"的文档，可以避免后续好几周的返工。

Another common challenge is unexpected technical difficulties. You start building a feature and suddenly discover that the existing system doesn't support what you need. Or a third-party tool doesn't work the way the documentation says. My approach here is not to panic. I take a step back, research the problem, and talk to teammates who might have faced something similar. Most technical problems have solutions — you just need to find them.

另一个常见的挑战是意料之外的技术难题。你开始做一个功能，突然发现现有系统不支持你的需求。或者第三方工具的实际行为和文档描述的不一样。我的应对方式是不要慌。退一步，研究问题，和可能遇到过类似情况的队友聊聊。大多数技术问题都有解决办法——你只需要找到它。

Changing requirements mid-project is another headache. The client changes their mind, or the business situation shifts. This is frustrating, but it's also a normal part of working in a real business environment. I've learned to stay flexible and think about how to minimize the impact of changes on work that's already done.

项目中途需求变更也是一个让人头疼的问题。客户改了主意，或者业务形势发生了变化。这确实让人沮丧，但在真实的商业环境中这再正常不过了。我学会了保持灵活，思考如何把变更对已完成工作的影响降到最低。

Finally, time pressure is always a challenge. Deadlines can be stressful. My strategy is to break big tasks into smaller pieces and focus on the most important things first. If something is at risk of being late, I communicate early rather than waiting until the last minute.

最后，时间压力始终是一个挑战。截止日期带来的压力不小。我的策略是把大任务拆分成小块，优先做最重要的事情。如果有延期风险，我会尽早沟通，而不是拖到最后一刻。

Projects are never perfect, but every challenge is a chance to learn and improve.

项目永远不会完美，但每一个挑战都是学习和进步的机会。

What Factors Are Important to the Success of Overseas Business?

Working in a tech company that serves international clients has given me a lot of exposure to the challenges of doing business overseas. It's not as simple as translating your product into another language and calling it done. There's a lot more to it.

在一家服务国际客户的科技公司工作，让我对海外业务的挑战有了很多切身体会。这件事远不是把产品翻译成另一种语言就算完了那么简单，里面的门道多得很。

From what I've seen and experienced, here are the factors I think matter most.

根据我的观察和经历，以下是我认为最重要的几个因素。

First and most importantly, you need to understand the local market. Every country has different business cultures, customer expectations, and working habits. What works perfectly in one market might completely miss the mark in another. Before entering a new market, it's worth spending real time learning about local needs rather than just assuming your existing product fits.

首先也是最重要的，你需要了解当地市场。每个国家都有不同的商业文化、客户期望和工作习惯。在一个市场上完美运作的东西，到了另一个市场可能完全不对路。在进入新市场之前，值得花时间真正去了解当地的需求，而不是想当然地认为现有产品能直接适用。

Second, communication and trust are everything in overseas business. When you're working across different time zones and cultures, misunderstandings happen easily. Being clear, responsive, and honest builds trust over time. Clients in any country want to feel that you understand their problems and that you'll follow through on your promises.

第二，沟通和信任在海外业务中至关重要。当你跨越不同时区和文化开展工作时，误解很容易发生。保持清晰、及时回应和诚实守信，能够逐步建立起信任。任何国家的客户都希望感受到你理解他们的问题，并且会兑现你的承诺。

Third, you need to respect local regulations and compliance requirements. Labor laws, data privacy rules, and business regulations vary significantly from country to country. In WFM, for example, scheduling rules and overtime policies are very different in different markets. Ignoring these differences can cause serious problems for your clients.

第三，你需要尊重当地的法规和合规要求。劳动法、数据隐私规则和商业法规在不同国家之间差异很大。以 WFM 为例，不同市场的排班规则和加班政策截然不同。忽视这些差异可能会给客户带来严重的问题。

Fourth, having a local presence or support team makes a big difference. Even in the age of remote work, having someone who speaks the local language and understands the local culture can help close deals and resolve issues much faster.

第四，在当地有驻点或支持团队会带来很大的不同。即使在远程办公的时代，有一个能说当地语言、了解当地文化的人，也能帮助更快地达成交易和解决问题。

Finally, long-term thinking is key. Overseas business takes time to build. Companies that rush for short-term profits often lose client trust. The ones that succeed are usually the ones that invest patiently in relationships and reputation.

最后，长远思维是关键。海外业务需要时间来构建。急于追求短期利润的公司往往会失去客户的信任。最终成功的，通常是那些耐心投资于关系和口碑的公司。

Going global is a big challenge, but with the right mindset and preparation, it can also be a great opportunity.

走向全球是一个很大的挑战，但只要心态对、准备充分，它也可以是一个绝佳的机遇。

How I Use Social Media in My Daily Life

Social media is everywhere these days. Whether it's WeChat, Weibo, LinkedIn, Instagram, or Twitter, most of us check our phones multiple times a day. But have you ever stopped to think about how you use social media — and whether it's actually working for you?

如今社交媒体无处不在。不管是微信、微博、LinkedIn、Instagram 还是 Twitter，我们大多数人每天都会刷好几次手机。但你有没有停下来想过，你是怎么使用社交媒体的——它真的对你有帮助吗？

Let me share how I approach it.

让我来分享一下我的做法。

First, I try to be clear about my purpose. Different platforms serve different needs. For me, LinkedIn is for professional networking — I follow people in the tech industry, read articles about software development, and occasionally share something work-related. WeChat is more personal — it's how I stay in touch with friends and family. Mixing these up can get messy, so I try to keep them separate.

首先，我会明确自己使用社交媒体的目的。不同的平台满足不同的需求。对我来说，LinkedIn 是用来拓展职业人脉的——我关注科技行业的人、阅读软件开发相关的文章，偶尔也分享一些跟工作有关的内容。微信则更私人——是我跟朋友和家人保持联系的方式。把这些搞混会很乱，所以我尽量把它们分开。

Second, I use social media to keep learning. There are a lot of great developers and industry experts who share useful content online. Following the right people is like having a free news feed of things that actually matter to your career. I've learned about new tools, read about other people's project experiences, and even found solutions to technical problems just by scrolling through my feed.

第二，我用社交媒体来持续学习。网上有很多优秀的开发者和行业专家在分享有价值的内容。关注对的人就像拥有了一个免费的信息流，里面都是对你职业发展真正有用的东西。我通过刷信息流了解过新工具、读到过别人的项目经验，甚至找到过技术问题的解决方案。

Third, I'm careful about how much time I spend on it. It's very easy to open an app "just for a minute" and suddenly realize thirty minutes have gone by. I try to set a rough limit for myself — checking social media at specific times rather than constantly throughout the day. This helps me stay focused during work hours.

第三，我会注意控制花在上面的时间。打开一个 App "就看一分钟"然后突然发现已经过了半小时，这种事太容易发生了。我会给自己设一个大致的限制——在特定的时间查看社交媒体，而不是一整天都在不停地刷。这有助于我在工作时间保持专注。

Fourth, I think about what I post. I don't post very often, but when I do, I try to share something that might actually be useful or interesting to others. Random complaints or oversharing personal drama — I try to avoid that. Your online presence is part of how people see you, especially professionally.

第四，我会考虑自己发什么内容。我发帖不多，但每次发的时候，我会尽量分享对别人真正有用或有趣的东西。随意吐槽或者过度暴露私人生活——这些我都尽量避免。你的网络形象是别人看待你的一部分，尤其是在职业层面。

Finally, I remind myself that social media is not real life. People usually share their highlights — their achievements, their travels, their best moments. It's easy to compare yourself to others and feel like you're falling behind. But what you see online is rarely the full picture. I try to enjoy the content without letting it affect how I feel about my own life.

最后，我会提醒自己，社交媒体不是真实的生活。人们通常只分享精彩瞬间——他们的成就、旅行、最美好的时刻。你很容易拿自己跟别人比，然后觉得自己落后了。但你在网上看到的几乎从来都不是全貌。我会享受这些内容，但不让它影响我对自己生活的感受。

Social media can be a great tool if you use it with intention. The key is to stay in control of it — and not let it control you.

社交媒体如果有目的地使用，可以是一个很好的工具。关键是你要掌控它——而不是让它来掌控你。

Can Data Really Prove Your Results?

In the workplace, we often hear things like "let the data speak" or "show me the numbers." Data has become one of the most common ways to prove that your work is delivering results. But can data really tell the whole story?

在职场中，我们经常听到"用数据说话"或者"拿数字来看"这样的话。数据已经成为证明工作成果最常用的方式之一。但数据真的能说明全部问题吗？

In many cases, data is genuinely useful. If a new feature I built reduces the time managers spend on scheduling by 30%, that number is clear and convincing. It shows that something real changed because of my work. Data like this is hard to argue with, and it gives both me and my manager a shared way to measure progress.

在很多情况下，数据确实很有用。如果我开发的一个新功能让管理者在排班上花费的时间减少了 30%，这个数字就很清晰、很有说服力。它说明因为我的工作，确实有了实际的改变。这样的数据很难反驳，而且它给了我和我的上级一个共同衡量进展的方式。

But data also has its limits. Some of the most valuable work is difficult to measure. For example, if I help a junior teammate grow by mentoring them, there's no direct number for that. If I improve the structure of the codebase so it's easier to maintain in the future, the benefit might not show up in any report for months. Does that mean the work didn't matter? Of course not.

但数据也有它的局限性。有些最有价值的工作是很难量化的。比如说，如果我通过指导帮助一个初级同事成长，这件事没有直接的数字可以衡量。如果我优化了代码库的结构，让它在未来更容易维护，这个好处可能几个月之后才会体现出来。但这是不是意味着这些工作不重要？当然不是。

There's also the risk of measuring the wrong things. If a team is judged only by how many features they ship, they might rush and sacrifice quality. The numbers look good, but the actual results are poor. Data can be misleading if we're not careful about what we choose to measure.

还有一个风险是衡量错了指标。如果一个团队只按上线了多少功能来评判，他们可能会赶进度而牺牲质量。数字看起来很好看，但实际效果很差。如果我们不注意选择衡量什么，数据是会产生误导的。

I think the honest answer is: data is a powerful tool, but it's not the whole picture. Good results need both — numbers that show impact, and context that explains the story behind them.

我觉得实话实说就是：数据是一个强大的工具，但它不是全貌。好的成果展示需要两者兼备——能体现影响力的数字，以及解释背后故事的上下文。

Data can support your case. But it takes judgment and communication to truly prove your value.

数据可以支撑你的论点。但要真正证明你的价值，还需要判断力和沟通能力。

What I Do During My Holidays

Holidays are something I always look forward to. After weeks of meetings, coding, and deadlines, having a few days to slow down feels really good.

假期是我一直期待的事情。经过几周的会议、写代码和赶截止日期之后，能有几天慢下来的时间，感觉真的很好。

I don't usually plan my holidays too carefully. I like to keep things relaxed. Sometimes I sleep in, cook a proper meal instead of ordering takeout, and just enjoy doing nothing for a while. It sounds boring, but honestly, it feels great after a busy stretch at work.

我通常不会把假期安排得太详细，喜欢保持轻松随意的状态。有时候睡个懒觉，自己好好做顿饭而不是叫外卖，然后就享受一会儿什么都不干的感觉。听起来很无聊，但说实话，忙了一阵之后这样做感觉特别好。

If the holiday is long enough, I might travel somewhere. It doesn't have to be far — even a short trip to a nearby city can feel refreshing. I enjoy walking around unfamiliar streets, trying local food, and taking photos of random things that catch my eye. Traveling, even on a small scale, helps me see things from a different perspective.

如果假期够长，我可能会去旅行。不一定要去很远的地方——哪怕是去附近的城市短途走走也会让人感到神清气爽。我喜欢在陌生的街道上闲逛、尝尝当地的美食、随手拍一些吸引我的东西。旅行，哪怕规模很小，也能帮我换一个角度看事情。

I also use holidays to catch up on things I don't have time for during the week. Reading a book I've been putting off, watching a documentary, or learning something new out of pure curiosity — not because it's useful for work, just because it's interesting. That kind of learning feels the most enjoyable.

我也会利用假期去做平时没时间做的事情。读一本一直拖着没看的书、看一部纪录片，或者纯粹出于好奇学点新东西——不是因为对工作有用，只是因为有意思。这种学习的感觉是最愉快的。

Of course, spending time with family and friends is a big part of holidays too. A simple meal together or a long conversation over tea can be more meaningful than any fancy trip.

当然，和家人朋友在一起也是假期很重要的一部分。一起吃顿简单的饭，或者喝着茶聊很久，有时候比任何精心安排的旅行都更有意义。

After a good holiday, I always come back to work feeling more energized and clear-headed. I think rest is not the opposite of productivity — it's actually part of it.

好好休完一个假之后，我回到工作中总是感觉更有精力、头脑也更清醒。我觉得休息不是效率的对立面——它其实是效率的一部分。

Everyone deserves a proper break. Don't feel guilty about enjoying your holidays.

每个人都值得好好休息一下。享受你的假期，不要有负罪感。

上一篇我解剖了 OpenClaw，拆出了它的八层架构，末尾说：下一篇动手造一只。

这篇就是兑现承诺。我真的造了一只出来——叫 CodyClaw，跑在飞书上，效果还不错。

如果你也想自己动手造一只 Agent，这篇可以帮你少走一些弯路。下面讲三件事：砍什么留什么、造的过程中踩了哪些坑、最后跑起来是什么样。

如果要自己实现OpenClaw，没必要都做

先回顾一下上一篇拆出的八层架构。这张表值得花一分钟看看——它能帮你判断，如果自己动手造，哪些值得做、哪些该果断砍掉：

数一下：两层完整实现（Gateway、Agent 执行），一层只做一半（Cron），两层大幅简化（记忆、Provider），三层不做（入口、多渠道、基础设施）。

真正绕不过去的就两件事：Gateway（消息怎么进来、怎么路由、怎么出去）和 Agent 执行（AI 怎么想、怎么调工具、怎么管上下文）。

先说最重的那个。

Agent 执行层这个最重的活，我把它抽成了框架

Agent 执行层是 OpenClaw 代码量最大的一层。它要干的事情包括：工具系统（文件读写、Shell、代码搜索……）、流式输出、会话上下文管理、权限控制、多模型适配。

我一开始试着自己写。写了两天发现不对——这些东西跟"龙虾"本身的业务逻辑完全无关。不管你是造龙虾还是造别的什么 Agent 应用，这些脏活都得干一遍。

所以我干了一件事：把这层抽出来，做成了一个独立框架 Cody。一句话说清楚它的定位：让你用几行代码就拿到一个带工具、带流式、带上下文管理、带MCP、Skill热加载机制的 Agent。它怎么设计的我后面会专门写一篇。

为什么要跟你说这个？因为如果你也想造自己的 Agent 应用，最大的建议就是：不要从零写执行层。不管用 Cody 还是 LangChain 还是别的什么，找一个趁手的框架把这层给承接了，把精力留给真正有跟你业务特性有关的部分——Gateway 和业务逻辑。

有了框架之后，CodyClaw 的 Agent 执行层就变成了这样：

client = AsyncCodyClient(
    model="claude-sonnet-4-6",
    api_key=config.api_key,
    base_url=config.base_url,
    skills_dirs=["./skills"],
    tools=[*feishu_tools, *cron_tools],
)

async for chunk in client.stream("你把xxx活给我干了"):
    if isinstance(chunk, TextDeltaChunk):
        response += chunk.text

工具、流式、会话、上下文压缩、多模型——全在这个 client 里面。我只需要告诉它用什么模型、有哪些额外的自定义工具。

当我实现 Gateway 的时候，有三个值得讲的坑

Gateway 要做的事说起来简单：消息从飞书进来，路由到对应的 Agent，AI 处理完再把结果发回飞书。但真正写起来，有几个地方比想象中麻烦。

这三个坑我都踩过了，分享出来希望能帮你省点时间。

坑一：飞书 SDK 跟 asyncio 打架

飞书有官方 SDK lark-oapi，支持 WebSocket 长连接——连接从你的机器主动发出去，不需要公网 IP，接入本身很简单。

但它有个坑：SDK 在 import 的时候就把当前的 event loop 捕获到了模块级变量里。如果你的服务跑在 uvicorn 上，SDK 会抓到正在运行的 loop，然后调 loop.run_until_complete()——直接报 "this event loop is already running"。

解法有点 hack：在独立线程里建一个全新的 event loop，然后直接替换 SDK 模块里的 loop 变量。

def _run_ws_in_thread(self) -> None:
    import lark_oapi.ws.client as ws_module

    new_loop = asyncio.new_event_loop()
    asyncio.set_event_loop(new_loop)
    ws_module.loop = new_loop  # 替换 SDK 模块级的 loop

    self._ws_client = lark.ws.Client(...)
    self._ws_client.start()  # 阻塞在独立线程里，不影响 uvicorn

SDK 线程收到消息后，通过 asyncio.run_coroutine_threadsafe() 跳回 uvicorn 的主循环处理。两个世界就这么接上了。

这个解法不够优雅，飞书 SDK 升级后可能失效。如果你遇到同样的问题，先查一下 SDK 是否已经修复了这个 event loop 的问题，没修再用这个 hack。

坑二：AI 回复太慢，用户在干等

AI 生成一条回复可能要 10-30 秒。如果等它全部生成完再发，用户体验很差——你不知道它是在想还是挂了。

我的做法是流式卡片：先发一张"思考中"的蓝色卡片，然后随着 AI 一边生成一边更新卡片内容。

_CARD_UPDATE_INTERVAL = 1.5  # 再快会触发飞书 API 速率限制

async def _update_streaming_card(self, run, msg, force=False):
    now = time.monotonic()
    if not force and (now - run.last_card_update) < _CARD_UPDATE_INTERVAL:
        return  # 节流

    content = run.accumulated_text.strip() or "⏳ 思考中..."
    card = build_streaming_card("执行中", content, "running")

    if run.card_message_id is None:
        run.card_message_id = await self._channel.send_card(msg.chat_id, card)
    else:
        await self._channel.update_card(run.card_message_id, card)

1.5 秒这个数字是试出来的——飞书卡片更新的速率限制大约是每秒 5 次，但实测超过 1 秒一次就容易偶发 429，1.5 秒是个稳妥的值。完成后卡片变绿，附带 AI 调了哪些工具的列表。

还有个容易忽略的边界情况：如果 AI 通过工具自己给用户发了消息（比如调用 feishu_send_text），结束时就不应该再发一张卡片，否则用户会收到重复信息。所以收尾逻辑要分三种情况：有卡片就更新为完成态，没卡片但 AI 也没主动发消息就兜底发一张，AI 已经发过消息就什么都不做。

坑三：工具注册时，依赖还没初始化好

CodyClaw 要给 AI 注册自定义工具——比如发飞书消息、建定时任务。但有个时序问题：注册工具的时候，飞书 channel 可能还没连上，后续也可能断线重建。

如果你直接把 self._channel 传进去，工具拿到的是注册那一刻的实例——后面换了新实例，工具还在用旧的。

解法是闭包捕获 getter，而不是实例本身：

def make_feishu_tools(get_channel):
    async def feishu_send_text(ctx, chat_id: str, text: str) -> str:
        channel = get_channel()  # 每次调用时取最新实例
        if channel is None:
            return "Error: Feishu channel is not available."
        await channel.send_text(chat_id, text)
        return "Message sent."
    return [feishu_send_text, ...]

# 注册时传 lambda，不传实例
self._feishu_tools = make_feishu_tools(lambda: self._channel)

getter lambda 每次调用时拿活实例，组件之间完全解耦。这个模式在初始化顺序不确定的系统里非常好用——如果你做过依赖注入，会觉得很眼熟，本质上就是延迟绑定。

其余的常规模块的实现，就很简单了

除了上面三个坑，剩下的模块都是比较常规的工程实现。虽然不难，但有几个的实现细节值得展开聊聊。

消息路由

CodyClaw 支持同时跑多个 Agent——比如一个专门写代码，一个专门查资料。那问题来了：用户发了一条消息，该交给谁处理？

我的做法是按三级优先级匹配：

1. 先看群：这个群有没有绑定过特定 Agent？比如"前端技术群"绑了代码 Agent，那群里所有消息都交给它。
2. 再看人：如果群没绑定，看发消息的这个人有没有绑定？比如你把自己绑到了资料 Agent，那你的消息就走资料 Agent。
3. 最后兜底：群没绑、人也没绑，走默认 Agent。

另外还有个触发条件：私聊机器人时每条消息都会触发，但在群聊里只有 @ 机器人才会触发——不然群里随便聊句天，AI 都要插嘴，太吵了。

实现就是几十行 if-else，没什么花活。但建议一开始就想清楚优先级顺序，后面改起来会牵一发动全身。

会话管理：懒过期比你想的好用

你跟 OpenClaw 聊天的时候，发完一句它会记得你前面说了什么，这就是"会话"。但如果你关掉页面明天再来，它会开一个新的对话——旧的上下文不会自动带过来。

CodyClaw 也需要这个能力。用户在飞书里连续发了三条消息，AI 得知道这三条是一个对话、要联系起来理解。但如果用户隔了一天才来，就应该开一个全新的会话，不然 AI 还在接着昨天的话题说，会很奇怪。

实现上，每个会话用 {agent_id}:{chat_id}（群聊）或 {agent_id}:{user_id}（单聊）做 key。每次写入同步落 SQLite，进程重启后能恢复。

有意思的地方在过期策略——一个会话超过 24 小时没活动，就该作废。最直觉的做法是跑一个后台定时器，每隔几分钟扫一遍所有会话，把超时的清掉。但这样你就多了一个需要管理的后台任务，还要操心并发锁。

我用的是懒过期——不主动清理，下次 get() 的时候顺手检查一下：

def get(self, key: str) -> Optional[Session]:
    session = self._store.get(key)
    if session is None:
        return None
    if time.time() - session.last_active > self._ttl:
        self._store.pop(key, None)  # 过期了，顺手删掉
        return None
    return session

好处是：没有后台线程、没有锁、代码量极少。代价是过期的会话会在内存里多待一会儿——但对于一个飞书机器人来说，会话数量本身就不多，这点内存完全无所谓。

Redis 的 key 过期其实也是类似思路（惰性删除 + 定期采样），只是多了一层定期兜底。对于这个量级，纯懒过期就够了。

如果你用 Docker 部署，记得给 SQLite 文件挂 volume，否则容器重建数据就没了。

实现用户记忆的时候，我没用向量检索

会话解决的是"这次对话里记得前面说了什么"，但跨对话的记忆是另一回事。比如用户上周告诉 AI "我是后端开发，主要用 Go"，这周问它"帮我写个脚本"，它应该默认用 Go 而不是 Python——这就需要把用户的偏好、习惯这些信息持久化下来，下次对话还能用。

很多人一提到"记忆"就想到 RAG——把记忆向量化存进向量数据库，对话时检索最相关的几条注入 prompt。这是对的，但不是所有场景都需要这么做。

我的做法更粗暴：每个用户一个 JSON 文件，AI 通过工具写入，上限 100 条，满了就 FIFO 淘汰最早的。每次对话把这个用户的所有记忆全量注入 prompt，预算 1500 token。

为什么不用向量检索？因为检索会漏。向量相似度是语义匹配，如果用户之前说"我不喜欢早上被打扰"，而当前对话在讨论"定时任务的执行时间"，这两个语义不一定能匹配上——但这恰恰是最该被召回的记忆。

全量注入不会漏，代价是占 token。但 100 条短记忆压在 1500 token 以内，对于现在动辄 100K+ 上下文的模型来说根本不是问题。

当然，这个方案有边界：如果你的用户量大、每个用户记忆多、并发写入频繁，JSON 文件就顶不住了（并发写可能丢数据，量大了全量注入也会太贵）。到那个阶段再上向量数据库也不迟——先跑起来，别过早优化。

Cron 定时任务对OpenClaw来说真的很重要

前面的模块都是"用户说一句，AI 做一件事"。但有些事情你希望 AI 自己定时去做——比如每天早上 9 点抓一波技术新闻发到群里，每隔 30 分钟检查一下服务是否健康。你不可能每天早上准时爬起来跟它说"帮我看看新闻"，这就需要 Cron。

实现上用的是 APScheduler，支持 crontab（0 9 * * 1-5）和自然语言（every 30m）两种写法。值得一提的是，每个定时任务有自己独立的持久化会话，AI 跨多次执行能积累上下文——比如早报任务，它能记得昨天推过哪些新闻，今天就不会重复推。这块没什么坑，APScheduler 文档很全，照着来就行。

一些关键指令，我们需要人工审批

AI Agent 能调工具、能跑命令，这很强大，但也很危险。你肯定不希望它自作主张把某个文件删了，或者在生产机器上跑了个 rm -rf。所以高危操作需要先问一下人："我打算做这件事，你同意吗？"

这件事如果从零写，你得拦截工具调用、挂起执行流、等人类响应、超时处理……想想就头大。但前面说的 Cody 框架天然支持 Human-in-the-Loop——它在 Agent 执行工具之前会触发一个回调，你可以在回调里决定放行还是拦截。

所以 CodyClaw 要做的事就很简单了：在 Cody 的回调里接上飞书的审批卡片。

async def on_tool_approval(self, run, tool_name: str, tool_input: dict) -> bool:
    event = asyncio.Event()
    run.pending_approval = event

    # 给用户发一张审批卡片，带"同意"和"拒绝"按钮
    desc = f"即将执行: {tool_name}"
    await self._channel.send_approval_card(
        run.chat_id, desc, run_id=run.id
    )

    # 挂起，等用户点按钮
    await asyncio.wait_for(event.wait(), timeout=300)
    return run.approval_result

用户在飞书里点"同意"时，回调把 run.approval_result 设为 True 然后 event.set()，上面的 await 就放行了。点"拒绝"或者 5 分钟超时就走拒绝逻辑。

这里又体现了把 Agent 执行层抽成框架的好处：拦截、挂起、恢复这些脏活 Cody 都干了，CodyClaw 只需要关心"用飞书卡片问用户同不同意"这一件事。如果哪天你想把审批从飞书换成钉钉、Slack，改的只是发卡片那几行，核心逻辑一行不动。

让CodyClaw跑起来，然后体验下我们自研的小龙虾

如果出于学习的目的，你可以去看这个Github：https://github.com/CodyCodeAgent/codyclaw

项目结构大概如下：

codyclaw/
├── main.py          ← FastAPI 应用入口
├── config.py        ← YAML 配置加载（支持 ${ENV_VAR}）
├── channel/         ← 飞书 WebSocket 接入
├── gateway/         ← 路由、调度、会话、记忆
├── automation/      ← Cron 调度、事件总线
├── web/             ← 管理后台
└── skills/          ← 内置的Skill技能包

对，我们还做了Web的管理后台，不过这都不是必须的。

按照项目里的README就可以完整的跑起来整个项目，下面是几个真实的交互截图，看看实际用起来是什么感觉。

让它自己装个技能

发一句"帮我装一下 self-improving-agent 这个 skill"，它就把技能装好了。装完之后它会记录自己犯过的错误、总结新学到的东西——下次不会再犯同样的错。不需要 ssh、不需要重启，一条消息搞定。

让他自己查看操作定时任务

问它"现在有什么定时任务"，它把所有 cron 列出来：工作日早 9 点的技术新闻、每 30 分钟一次的健康检查、每天 10 点的 AI 早报。这些任务都是之前聊天时让它帮忙建的，它自己写进了数据库。

让它写代码并且跑起来

"帮我写个 Python 的 Hello World 页面，跑在 12346 端口。" 它写了文件、启动进程、发现卡住了、自己重启、curl 验证通过，最后把地址告诉你。这不是在跟你说"你可以这样做"——它直接在你的机器上把事情做了。

有了Cody，那我自己到底实现了多少

回到开头那张八层表，对比一下：

核心功能基本都有了。砍掉的是多渠道、浏览器、移动端 App 这些"外延"——对于一个跑在飞书上的个人 AI Agent，这些本来也用不着。

最后说两句

写这篇不是要做一个 OpenClaw 的替代品。说实话，OpenClaw 的工程量和社区生态不是一个人能比的。

我真正想做的事情是：通过自己动手造一只，把上一篇拆解出来的技术细节从"看懂了"变成"摸过了"。

上一篇你知道了 OpenClaw 有消息路由、有会话管理、有 cron、有执行审批、有 SKILL.md、有 BOOT.md。但那些都是别人的代码。自己写一遍之后你会发现：消息路由就是几十行 if-else，会话管理就是一个 {agent_id}:{user_id} 的 key，cron 就是 APScheduler 加个 SQLite，执行审批就是在消息流里插一个 asyncio.Event。每一个单独拿出来都不复杂，OpenClaw 的厉害之处在于把它们粘成了一个 7x24 在线的整体。

而粘合这件事本身，真没那么玄——CodyClaw 的 gateway 目录去掉空行和注释，不到 800 行 Python。

如果你也想试试，所有代码都在这里，随便拿去改：

• Cody 框架：github.com/CodyCodeAgent/cody
• CodyClaw 源码：github.com/CodyCodeAgent/codyclaw

别再卷模型了，套在外面的 Harness 才是胜负手

Humans steer, agents execute. 人类掌舵，智能体执行。

一个重新理解 AI 工程的发现

2025 年大家都在证明一件事：AI Agent 能写代码。到了 2026 年，一个更有意思的事实——Agent 写得好不好，跟模型本身的关系没那么大，跟模型外面那层"壳"的关系才大。

LangChain 的人在 Terminal Bench 2.0 上做了个实验：同一个模型（GPT-5.2-Codex），一行代码没改，只动了模型周围的系统设计——提示词怎么组织、工具怎么调用、中间件怎么插。结果得分从 52.8% 飙到 66.5%，排名从 Top 30 开外直接杀进 Top 5。

OpenAI 自己的 Codex 团队更猛。一个小团队 5 个月时间，用 Agent 生成了超过 100 万行代码——零行手写。不是玩具项目，是可以跑的东西：应用逻辑、文档、CI 配置、可观测性、内部工具，全是 Agent 干的。工程师全程在干嘛呢？在设计让 Agent 能可靠干活的那套系统。

Vercel 他们的数据团队把 Agent 能用的工具从 15 个砍到 2 个——对，你没看错，砍掉了 80%。结果成功率从 80% 跳到 100%，速度快了 3.5 倍，token 还省了 37%。

三个故事都在讲述一个道理：决定 Agent 干活质量的，不是模型多聪明，是你给它搭的环境多靠谱。这个环境，行业里现在叫它 Harness。围绕 Harness 做工程，就是所谓的 Harness Engineering。

先说清楚：从提示词到 Harness，我们到底经历了什么

2022-2024：提示词工程

最早大家就是在琢磨怎么"问个好问题"。Chain-of-thought、few-shot、角色扮演……花了两年研究怎么在一个文本框里写出完美指令。有用，但说白了就是一句话的事——你写一段，它回一段。

2025：上下文工程

2025 年 Andrej Karpathy 给了个更精准的说法：上下文工程就是"往上下文窗口里精确地塞对的信息"。他打了个比方——LLM 是 CPU，上下文窗口是 RAM。提示词工程是在 RAM 里写指令，上下文工程是决定 RAM 里该放什么。

这个阶段大家意识到：模型能不能干好活，很大程度取决于它"看到"了什么。同一个模型，上下文给得不一样，输出天差地别。到 2025 年底，"Context Engineer"这个头衔开始正经出现在招聘里了。

2026：Harness Engineering

但光管"给模型看什么"还不够。当 Agent 不再是一问一答，而是要连续跑五十一百次工具调用、跨十几个文件改代码、自己做架构决策——你还得管它的行为边界、验它的输出、清理它搞出来的烂摊子。

Epsilla 有个特别直觉的比喻：

• 提示词工程 = 写一封完美的邮件
• 上下文工程 = 把该附的文件都附上
• 驾驭工程 = 设计整套办公基础设施——工位、流程、权限、审批、质检

Philipp Schmid 的比喻更极客一点：Model 是 CPU，Context Window 是 RAM，Harness 是操作系统，Agent 是应用程序。这一下就说清楚了——Harness 不是模型本身，也不是上层应用，是让一切跑起来的那个操作系统层。

所以 Harness 到底是啥？

Harness 这词来自马具——套在马身上的缰绳和鞍具。不是让马跑更快，而是把马的力量引到你想去的方向。

放到 AI 这边：模型是引擎，Harness 是整辆车。

具体一点，一个好的 Harness 干四件事：

1. 约束——Agent 能干啥不能干啥（架构边界、依赖规则、文件权限）
2. 告知——Agent 该干啥（上下文、文档、代码规范）
3. 验证——Agent 干对没有（测试、linter、CI）
4. 纠正——干错了怎么修（反馈回路、自修复机制）

有人会问：这跟 SDK、框架有啥区别？SDK 和框架解决的是"怎么构建 Agent"，Harness 解决的是"Agent 怎么跑"。Claude Code、Codex CLI、LangChain DeepAgents 这些东西，本身就是 Harness 的实现——它们提供了 prompt 预设、工具调用的默认处理、生命周期钩子、子 Agent 管理这些现成能力。

其实 Harness 比模型更重要

LangChain：模型没换，排名从 30 开外冲进 Top 5

同一个 GPT-5.2-Codex，只改 harness：

他们做了三件事：加了个 Self-Verification Loop（提交前强制自测），写了个 Loop Detection（检测 Agent 在同一个文件上反复改来改去的死循环），优化了启动时的上下文注入。

有意思的是他们发现了个叫"Reasoning Sandwich"的技巧：不让模型全程开最高推理（那样会超时，只有 53.9%），而是规划阶段用最高推理、写码阶段用中等、验证阶段再拉回最高。跟人脑一个道理——想方案时深思熟虑，写代码时进入心流，review 时再切回审慎模式。这一招直接拿到 66.5%。

Vercel：砍掉 80% 的工具，成功率反而到了 100%

原来有 15 个工具（schema lookup、query validation、error recovery 之类的），团队后来发现自己是在"替模型思考"——帮它过滤信息、帮它规划路径。结果砍到只剩 bash 和 SQL 两个工具：

最夸张的对比：旧系统最差情况跑了 724 秒、烧了 14.5 万 token 还失败了；新系统干同一个查询只用 141 秒、6.7 万 token，成功。

他们总结了一句特别到位的话："当我们不再替模型做选择时，模型反而做出了更好的选择。"

不过有个前提——他们的语义层文档写得很好。他们自己也说了：如果你的数据层一团糟，给 Claude 直接文件访问也救不了你。

Nate B Jones：同一个模型，差的 harness 42%，好的 78%

差距接近一倍。Harness 带来的影响是模型原始能力的两倍。

OpenAI：5 个月，100 万行代码，零行手写

一个小团队，全程 depth-first——把大目标拆成小积木块，让 Agent 搭积木，再用积木解锁更复杂的东西。他们最后说了句让我印象很深的话：

"我们最大的挑战不在于模型的能力，而在于设计环境、反馈回路和控制系统。严谨的工程设计并没有因为 AI 而变得简单——它变得更重要了。"

有这么一个道理：约束越多，Agent 反而表现越好

我们总觉得给 AI 更多自由它就能发挥得更好。但实际上限制了解空间，Agent 才能在有限范围内找到正确答案，而不是在无穷可能性里迷路。就像 TypeScript 比 JavaScript 多了一堆"限制"，但正是这些限制让你写出更靠谱的代码。

HumanLayer 的 Kyle 说得更直白：Agent 出问题时，第一反应别想着等更强的模型，先检查你的配置。这不是模型问题，是配置问题。

就像高速公路上有护栏你反而敢开快，Agent 在好的约束下反而能更自主——因为 harness 替它兜底了。

Harness的三大支柱

OpenAI 的实践加上 Birgitta Böckeler 在 Martin Fowler 博客上的分析，Harness 可以拆成三根柱子。

第一根柱子：上下文工程——Agent 看不到的东西等于不存在

你团队的 Google Docs、Slack 里的默契、大家脑子里那些"这个大家都知道"的东西——Agent 统统看不到。它能看到的只有仓库里的文件和运行时能拿到的信息。

所以核心就一句话：一切知识必须编码到仓库中。

静态上下文就是 Agent 的"入职文档"：

项目根目录/
├── AGENTS.md          # Agent 行为指南
├── CLAUDE.md          # Claude Code 专用指南
├── ARCHITECTURE.md    # 架构决策记录
├── docs/
│   ├── api-design.md
│   ├── patterns.md
│   └── decisions/

AGENTS.md 是 2026 年冒出来的一个好东西——面向 AI Agent 的 README，Claude Code、Cursor、Codex 都认。HumanLayer 建议控制在 60 行以内。为啥？上下文窗口是有限资源，塞太多模型反而会迷失。

这些文件该告诉 Agent 什么？技术栈和版本、代码风格的硬规则（不是"写得优雅"，是"函数不超过 50 行"）、哪些模式推荐哪些禁止、测试怎么跑、提交规范是啥。

动态上下文是运行时感知：监控数据、CI 状态、目录结构映射。LangChain 的 LocalContextMiddleware 会在启动时自动扫描项目结构和可用工具注入进去，这个挺聪明的。

还有个重要理念叫渐进式披露——别在启动时把所有信息一股脑塞给 Agent，让信息随着任务推进按需浮现。MCP Servers、Skills、Sub-Agents 都是做这个的。

有条反直觉的原则值得记住：成功应该是沉默的，只有失败才需要产出。早期有人跑完整测试套件，5 分钟的通过结果全丢给 Agent，那些无关信息反而淹没了真正需要关注的失败用例。

还有一点——写得好的代码本身就是最好的文档。清晰的命名、一致的模式、合理的抽象，比注释更能帮 Agent 理解你的意图。Böckeler 甚至预测：未来开发会趋向更少的、对 AI 更友好的技术栈——不是为了人类偏好，是为了 Agent 好维护。

第二根柱子：架构约束——别跟 Agent 讲道理，直接拦住它

团队里的代码规范如果靠人自觉都经常破防，Agent 就更不会自觉了。必须把约束变成可执行的检查。

约束分四层：

第一层：确定性 Linter（ESLint、checkstyle、golangci-lint）
第二层：结构化测试（ArchUnit——Service 层不能直接调 Repository）
第三层：自定义 Linter（禁止在 Controller 层写业务逻辑）
第四层：LLM 审计 Agent（用 AI 审查 AI 的输出）

最简单有效的是 pre-commit hooks。Agent 提交代码时 hook 自动跑，不通过就不让提交。Agent 不需要"理解"规则，被规则拦住就行了。

HumanLayer 管这叫 Back-Pressure——测试、类型检查、linter 形成一种反压力，让 Agent 犯错后能"感知"到错误并自我修正。这比让 Agent 自己评估靠谱多了——Anthropic 的研究表明模型自评时过于宽容，很容易说服自己 bug 不严重。

Loop Detection 也很关键。LangChain 发现 Agent 经常在同一个文件上改了又改，每次改一点每次还失败，陷入死循环。他们的解法很简单：追踪每个文件编辑次数，超过 N 次就中断，提示 Agent 换个思路。简单但管用。

Sub-Agents 做任务隔离也很重要。Agent 跑久了会出现"上下文腐化"——上下文越来越长，性能越来越差。Sub-Agent 就是一道防火墙，子任务的中间噪音不会污染主 Agent 的上下文。

举个真实例子：OpenAI 发现 Agent 老喜欢把所有逻辑塞一个函数里。他们没去"教育"Agent，直接写了个 linter——函数超过 50 行就报错。结果 Agent 学会了拆函数。不是因为它理解了为什么要拆，是因为不拆过不了检查。

第三根柱子：熵管理——AI 生成的代码天然趋向混乱

OpenAI 团队以前每周五花 20% 时间清理"AI 垃圾"——重复代码、不一致的命名、偏离模式的实现。太痛苦了。后来他们想通了：把"黄金规则"编码到仓库里，然后用专门的 Agent 定期巡检。

Böckeler 在 Martin Fowler 博客上专门强调了这一点，引用了 OpenAI 的原则："When the agent struggles, we treat it as a signal"——Agent 挣扎的地方，就是 harness 需要加强的地方。

垃圾回收 Agent 干的事很直接：查文档跟代码是否一致、找偏离约定模式的代码、识别冗余实现、检查依赖是否过时。可以定时跑、PR 合并后跑、或者发现问题后针对性扫。

Philipp Schmid 还指出了一个新问题叫 Agent Drift——模型跑久了会慢慢偏离指令，像车慢慢跑偏一样。排行榜上 1% 的差距根本测不出来这种东西。所以 Harness 不光要在开始前设好规则，还要全程持续监测纠偏。

有个重要的反馈循环：垃圾回收 Agent 反复发现同一类问题时，说明你的约束不够。这时候该回到第二根柱子去补规则，别每次手动修。

超姐 OpenAI Codex，Harness 长什么样

OpenAI 把 Codex 的内部架构细节公开了，可以看看一个生产级 Harness 的真实面貌。

核心其实是一个特别简单的循环：

1. 接收输入，构造 prompt
2. 模型生成响应——要么是最终回答，要么是工具调用
3. 如果是工具调用，执行它，把结果追加回 prompt
4. 回到第 2 步，直到模型不再调用工具

就这么简单。但围绕这个循环搭的 Harness，才是真正的工程量。

Codex 跑在 CLI、VS Code、Web、macOS 桌面、JetBrains、Xcode 这些界面上，底下统一由一个 Codex App Server 驱动——基于 JSON-RPC 的双向 API。它抽象了三个核心概念：

• Item——输入输出的原子单位（消息、工具执行、审批请求、diff）
• Turn——一次完整的 Agent 工作序列
• Thread——持久化的会话容器，支持恢复、分叉、归档

还有个审批机制：Agent 要执行有风险的操作时，Server 会暂停并向客户端发审批请求，人点了"允许"才继续。自动化的同时人类始终有最终控制权。

再看看 Shopify：CEO 亲自上阵用 Agent 优化核心系统

Shopify CEO Tobi Lütke 2025 年发了份内部备忘录——"AI 使用是所有人的基线期望"，要加人先证明 AI 干不了这活。八个月后 Box、Fiverr 甚至加拿大总理都跟进了。

但 Lütke 不只是发备忘录，他自己上手做了个示范。

他用了 Karpathy 的 Autoresearch 方法——让 coding agent 半自主跑大量实验，对 Shopify 的核心模板引擎 Liquid 做性能优化。写了个 autoresearch.md 提示文件加配套脚本，让 Agent 自动跑测试报 benchmark。跑了大概 120 次实验，产出 93 次提交：

• parse+render 快了 53%
• 内存分配少了 61%

最大的单项优化是用 String#byteindex 替代正则 tokenizer，单独贡献了 12% 的解析提速。

这不是玩具。Liquid 驱动着 Shopify 560 万活跃店铺的前端渲染。CEO 亲自用 AI 对核心基础设施做出了有意义的改进——但关键不在于他用了多牛的模型，而在于他搭了一个严格的实验框架：有明确的 benchmark、自动化的测试运行器、结构化的结果收集。这就是一个轻量但有效的 harness。

怎么开始搞？从简单到复杂可以定义三个级别

Level 1：个人开发者

✅ 项目根目录放个 CLAUDE.md / AGENTS.md（控制在 60 行以内）
✅ 配好 pre-commit hooks（lint + type check + 测试）
✅ 写好测试套件
✅ 保持仓库整洁、命名一致

最低配的 harness，但已经能明显提升 Agent 输出质量。CLAUDE.md 长这样就够了：

# CLAUDE.md

## 技术栈
- Java 21 + Spring Boot 3.3
- PostgreSQL + MyBatis-Plus
- Gradle 构建

## 代码规范
- Service 层方法必须有单元测试
- Controller 层只做参数校验和响应包装，不写业务逻辑
- 所有数据库查询走 Repository 层
- 函数不超过 50 行

## 测试命令
./gradlew test

## 禁止事项
- 不要用 lombok 的 @Data，用 @Getter @Setter
- 不要在 Service 层直接拼 SQL
- 不要 catch Exception，必须 catch 具体异常类型

Level 2：小团队

Level 1 基础上加：

✅ 团队统一的 AGENTS.md（版本化管理）
✅ CI 里集成架构约束检查（ArchUnit 之类的）
✅ 共享的代码模式模板
✅ PR 审查加上 Agent 输出质量检查
✅ Loop detection（防止 Agent 在同一问题上原地打转）

Level 3：组织级别

Level 2 基础上加：

✅ 自定义中间件（拦截和约束 Agent 行为）
✅ 可观测性集成（监控 Agent 效果、检测 Agent Drift）
✅ 仪表盘（追踪成功率、Token 消耗、执行时间）
✅ 垃圾回收 Agent 定期巡检
✅ Harness 模板库（不同项目用不同模板）
✅ Agent 运行轨迹采集

最后一点 Philipp Schmid 特别强调了它的战略价值：竞争优势正在从 prompt 转向"捕获的运行轨迹"。Agent 每次在长工作流中跑偏，都是一条有价值的训练数据。

在这个时代里，代码工程师干的活变了

这不是说不用会写代码了——恰恰相反，你需要更深的架构能力和系统思维才能设计好 harness。Karpathy 说 2026 年是 Agentic Engineering 时代，人类不再写大部分代码，而是指挥、监督、编排 Agent。就像交响乐指挥不亲自演奏每件乐器，但整场演出的质量由他决定。

换句话说：工程师不再直接解决问题，工程师解决的是 Agent 在解决问题时遇到的问题。你的交付物不是代码，而是一个让 Agent 持续可靠产出代码的系统。

下面是可能要踩的坑

过度设计控制流。 给 Agent 搞了个巨复杂的状态机，结果模型一升级全废了。Manus 6 个月重构了 5 次 harness，LangChain 一年重架构了 3 次。正解是 Philipp Schmid 说的"Build to Delete"——设计时就预期会被替换，保持模块化，给强的原子工具让模型自己规划。

写了 AGENTS.md 就再也不更新。 Harness 是活的，Agent 每次犯错都问一句：这个错误能用什么约束预防？然后把答案编码进去。

文档太模糊。 "代码要写得优雅" "注意性能"——这种话 Agent 理解不了。"函数不超过 50 行"比"函数要简短"好一万倍。

Agent 写了烂代码，人肉修完拉倒。 不去想为什么。OpenAI 的原则说得好：Agent 挣扎的地方就是 harness 需要加强的地方。每次犯错都是改进的机会。

知识留在仓库外面。 架构决策记在 Confluence，规范写在 Notion 里。Agent 只能看到仓库，一切知识必须在仓库内。

一次性塞太多上下文。 CLAUDE.md 写了几百行，测试输出全丢给 Agent。上下文是有限资源，让信息按需加载。聚焦 20 分钟的 session 胜过漫无边际的 2 小时。

让 Agent 自己评价自己。 Anthropic 研究表明模型自评时太宽容，容易说服自己 bug 不严重。必须用确定性的外部工具（测试、linter）做验证。要用 LLM 审查就得用独立的、配了严格标准的评估 Agent。

Harness 也不是万能的

只对能验证的任务管用。 代码能跑、测试能过、类型能检查——这些 harness 很擅长。但产品设计决策、用户体验判断、创意工作？缺确定性验证手段的场景，harness 能帮多少还是个问号。

功能正确性有缺口。 Böckeler 分析 OpenAI 的实践时指出：他们的内部质量指标都过了（风格一致、架构合规），但没验证"代码做的是不是对的事"。Agent 可能完美遵守所有规则，写出风格一致测试通过的代码，但它理解的需求跟产品团队想要的是两回事。

现在的 harness 还挺脆弱。 大部分是 linter 规则、CI 脚本和自定义 hook 拼出来的，换个模型版本或 Agent 工具可能就得大面积改。这个领域还没有出现类似 Kubernetes 之于容器编排那样的标准化层。

组织层面才是真正的挑战。 2026 年 Deer Valley 研讨会有份报告说得很直接：技术再好，如果团队没有维护 harness 的意愿和能力，它很快就会过时。

更大的上下文窗口不等于更好。 信息多了不代表模型更擅长从中找到有用的。塞太多反而让模型更难聚焦，这也是为什么按需加载比一次性全给更有效。

最后

一句话总结：别再只想着让 AI 更聪明了，让它的运行环境更聪明。

2025 年我们卷的是"哪个模型更强"，2026 年我们发现真正的竞争力在于谁的 harness 更好。排行榜上模型差距越来越小，但真实场景里的表现差距越来越大——差距全在 harness 里。

三根柱子：

上下文工程  → 让 Agent 看到该看的
架构约束   → 让 Agent 不做不该做的
熵管理    → 让系统不会越跑越烂

三个数据：

• LangChain 同模型提升 26%，杀进 Top 5
• Vercel 砍 80% 工具，成功率从 80% 到 100%
• 好 harness 比差 harness 高出近一倍

这不是锦上添花，这是 AI Agent 时代写软件的基本功。

OpenAI 那句话我反复读了好几遍，拿来收尾刚好：

"严谨的工程设计并没有因为 AI 而变得简单——它变得更重要了。"

参考资料：

• OpenAI, "Harness engineering: leveraging Codex in an agent-first world", 2026
• OpenAI, "Unlocking the Codex harness: how we built the App Server", 2026
• OpenAI, "Unrolling the Codex agent loop", 2026
• Birgitta Böckeler (Martin Fowler's blog), "Harness Engineering", Feb 2026
• LangChain, "Improving Deep Agents with Harness Engineering", 2026
• Vercel, "We removed 80% of our agent's tools", 2026
• Philipp Schmid, "The importance of Agent Harness in 2026"
• HumanLayer, "Skill Issue: Harness Engineering for Coding Agents"
• Epsilla, "The Third Evolution: Why Harness Engineering Replaced Prompting in 2026"
• Andrej Karpathy on Context Engineering
• Shopify/liquid PR #2056: Performance: 53% faster parse+render
• Nate B Jones, Agent Harness benchmark research, Mar 2026
• Anthropic, "Demystifying evals for AI agents", 2026

AI Agent 生态的层次思考

当我们谈论 AI Agent 的时候，我们到底在谈论什么？

引言

过去一年，AI Agent 的概念被反复提及，但大多数讨论都停留在"某某框架很好用"、"某某产品很火"的层面。很少有人从生态层次的角度，去思考这个领域的整体结构。

本文尝试回答一个问题：AI Agent 生态，从底层硬件到用户交互，一共分几层？每层解决什么问题？

这不是一篇框架对比文章，而是一次关于生态结构的思考。

完整的层次结构

用一张图来看整体结构：

┌─────────────────────────────────────────────┐
│                  产品层                       │
│        OpenClaw / Claude Code / Cursor       │
├─────────────────────────────────────────────┤
│              Agent Runtime 层                │
│       长期记忆 / Skill 管理 / 任务队列        │
├─────────────────────────────────────────────┤
│               Agent SDK 层                   │
│  Tool 注册 / MCP 封装 / 多 Agent 编排         │
│  Eino / pydantic-ai / LangChain / Agents SDK │
├─────────────────────────────────────────────┤
│              Agent Loop 层                   │
│         LLM ↔ Tool 推理闭环循环               │
├─────────────────────────────────────────────┤
│             Provider SDK 层                  │
│   OpenAI SDK / Anthropic SDK / LiteLLM       │
├─────────────────────────────────────────────┤
│                LLM API                       │
│   OpenAI / Anthropic / Gemini / DeepSeek     │
├─────────────────────────────────────────────┤
│             模型推理服务层                     │
│          Ollama / vLLM / Triton              │
├─────────────────────────────────────────────┤
│                 基建层                        │
│          GPU / TPU / 云计算基础设施            │
└─────────────────────────────────────────────┘

下面逐层展开。

各层详解

基建层

核心问题：算力从哪来？

这是整个生态的物理基础。GPU、TPU、网络、存储，构成了 AI 时代的"电力和公路"。对于大多数开发者来说，这层是黑盒——要么用云厂商托管（AWS、GCP、Azure），要么自建机房。

这层的问题不是软件问题，是资源问题。

模型推理服务层

核心问题：怎么把模型跑起来？

当你不想依赖云端 API，想把模型跑在自己的机器上时，就需要这一层。Ollama、vLLM、Triton 是代表性的工具。

这层解决的问题是：

• 模型加载和版本管理
• 推理速度优化（量化、批处理）
• 对外暴露统一的 API 接口

值得注意的是，这层通常会模拟 OpenAI 的 API 格式，使得上层无需感知模型是云端还是本地。

LLM API 层

核心问题：提供标准的语言理解和生成能力。

OpenAI、Anthropic、Google Gemini、DeepSeek、通义千问……这些是 LLM API 的提供者。

这层本身不是开发者"建造"的，而是开发者"使用"的。但它是整个生态的核心驱动力——模型能力的提升，会直接影响上面所有层的可能性边界。

Provider SDK 层

核心问题：怎么屏蔽不同 LLM 之间的 API 差异？

每家 LLM 的 API 格式、鉴权方式、streaming 实现、tool call 格式都不一样。如果业务代码直接调用各家 SDK，切换模型就意味着大量重写。

这层的代表就是各家官方 SDK：

• OpenAI SDK
• Anthropic SDK
• 豆包 SDK
• Gemini SDK

以及一些统一封装的库，它们把不同 Provider 的差异抹平，让上层只需要关心"我要调用一个 LLM"，而不是"我要调用 OpenAI 的 GPT-4o"。

Agent Loop 层

核心问题：怎么实现一次完整的推理闭环？

这是 Agent 的最小工作单元，本质上是一个循环：

调用 LLM
  ↓
有 tool call？
  ↓ 是          ↓ 否
执行 tool      返回结果
  ↓
再次调用 LLM
  ↓
（重复直到结束）

这一层只知道"tool"这个抽象概念，不知道 MCP，不知道 Skill，不知道记忆。它只负责把一次推理任务跑完。

关键点：tool 从哪来、怎么注册，不是 Loop 层的问题，是上层传进来的。Loop 层只负责"执行"。

Agent SDK 层

核心问题：怎么方便地构建和编排 Agent？

在裸 Loop 之上，SDK 层提供了更丰富的能力：

• Tool 注册和管理：让开发者方便地把函数变成 tool
• MCP 封装：把 MCP server 包装成 tool，让 Loop 无感知
• Structured Output：保证模型输出符合预期的数据结构
• 多 Agent 编排：让多个 Agent 协作完成复杂任务

这层是大多数"AI 框架"存在的位置，比如 Eino、pydantic-ai、LangChainGo。

多 Agent 编排值得单独说一下。单个 Agent 能力有限，复杂任务需要多个专门的 Agent 协作。SDK 层提供了两种典型模式：

• Transfer：把任务完全交给另一个 Agent，当前 Agent 退出（类比转接电话）
• AgentAsTool：把另一个 Agent 当做 Tool 调用，拿到结果后继续处理（类比派人办事）

Agent Runtime 层

核心问题：怎么让 Agent 持续运行，而不是一次性的？

这是目前生态中最缺失、最值得关注的一层。

Agent SDK 解决的是"单次运行"的问题：给定输入，跑一次，输出结果。但真正有价值的 Agent 应该是持续运行的，它需要：

• 长期记忆：记住上周和你说过的事
• Skill 管理：知道自己能做什么，动态加载新能力
• 任务队列：有积压的任务要处理
• Heartbeat 机制：定时醒来检查是否有新任务
• 状态持久化：崩溃重启后能恢复到之前的状态

目前这层没有一个独立的、被广泛采用的解决方案。OpenClaw 这类产品顺带做了这件事，但它同时也在做产品层的事。

这层的空缺，是当前生态最大的机会之一。

产品层

核心问题：怎么让用户真正用起来？

这层面向的是终端用户，不是开发者。它解决的问题是：

• 用什么界面交互（消息 App、Web、CLI）
• 怎么让非技术用户也能扩展 Agent 的能力
• 怎么设计产品体验

OpenClaw 是这层的代表：通过 WhatsApp、Telegram 等消息 App 作为入口，普通用户发一条消息就能让 Agent 执行复杂任务。它在中国引发的"养龙虾"热潮，说明这层产品的爆发力。

关于现有框架的定位

一个容易犯的错误是把某个框架"钉"在某一层。实际上，大多数框架都是垂直跨层的：

没有任何一个框架专注只做一层。这既是现状，也是机会——每一层都有空间做一个专注、深度的解决方案。

从表中也能看到一个有趣的规律：越靠近用户的产品，覆盖的层次越多。Claude Code、Cursor 这类产品几乎从产品层一直做到 Loop 层，因为它们需要完整控制用户体验。而 LiteLLM 这样的工具则专注在一层，做到极致。

一个有趣的类比

如果用操作系统来类比：

基建层          ↔  硬件
模型推理服务    ↔  固件 / 驱动
LLM API        ↔  CPU 指令集
Provider SDK   ↔  硬件抽象层
Agent Loop     ↔  进程调度
Agent SDK      ↔  编程语言 / 标准库
Agent Runtime  ↔  操作系统
产品层         ↔  应用程序
用户           ↔  用户

OpenClaw 自称 "AI Operating System" 不是没有道理——它确实在填 Runtime 层和产品层的空白。但真正的"AI OS"应该是一个独立的 Runtime 层，让各种产品都能在上面运行，而不是一个大而全的单体。

结语

AI Agent 生态还处于早期，各层的边界还很模糊，大量工作被打包在同一个框架里。但随着生态成熟，分层会越来越清晰，专注做好一层的机会也会越来越多。

理解层次，才能找到自己的位置。

本文是一次关于 AI Agent 生态结构的思考梳理，欢迎讨论和补充。

我最近发现一件很奇怪的事：很多AI产品，用的人越多，亏得越多。

不是因为产品不好，不是因为没有用户，就是因为每个用户每发一条消息，背后都要消耗Token，这个钱是产品方出的。规模越大，窟窿越大。

然后大家想的解法是：涨价、限制用量、找愿意付费的用户。

但我觉得，这个方向可能从一开始就偏了。让App来承担Token的费用，这件事逻辑本身就是错的。

你有没有想过，也许流量费从来不是App的事

你现在用微信、刷视频、叫外卖。

这些App从来不需要替你承担上网的费用。你自己买了流量套餐，手机联网，App直接用，费用记在你头上，跟App没关系。

这件事之所以能这样运转，背后有一个很关键的东西——SIM卡。

SIM卡解决的不是"怎么上网"的问题，它解决的是身份认证和资费归属的问题。你插了哪张卡，你的流量费用就归到哪个账户。设备知道你是谁，运营商知道该向谁收钱，App完全不需要介入这件事。

AI现在缺的，正是这样一层东西。

如果Token也有一张"卡"

设想一下这个场景——

用户选择绑定某家模型厂商，就像选择运营商一样，在手机系统层完成身份认证和资费绑定。开发者调用AI能力的时候，不是"我这个App去对接某家模型的API，我来承担这次调用的费用"，而是"用户已经绑定了他自己的模型账户，这次调用的费用自动记在他头上"。

App只管调用，费用和权限的归属，交给系统层和模型厂商去结算。

这样的话——

开发者不需要申请各家的Key，不需要考虑Token成本怎么转嫁，不需要为了控制成本而克制地使用AI。

用户也不需要在每个App里单独配置、单独付费。他和某家模型厂商之间的关系，一次绑定，到处生效。

模型厂商在这个结构里，扮演的角色就是运营商。算力就是流量，Token就是流量费，用户按月订阅，App按需调用。

如果这件事成了，才会出现更多的AI原生产品

现在很多AI产品，表面上在做AI，实际上有一半精力是在算这件事划不划算——这个功能要调几次模型，每次多少钱，用户会不会用，能不能回本。

这些问题不该是产品层面要解决的。就像你做一个视频App，不需要去想用户的流量从哪来。

一旦Token的费用归属问题在系统层解决了，开发者才能真正专注在产品体验上。那个时候，才会出现真正的AI原生产品——不是现在这种在传统逻辑上套AI外壳的东西，而是从一开始就把AI当作基础能力来设计的产品。

就像真正的移动原生产品，是在流量便宜、网速快了之后才出现的，不是在2G时代硬做出来的。微信、抖音、美团，没有一个是2G时代的产物。

算力，Token，终将变成水电煤

这件事能成立，还有一个前提：Token得足够便宜。

这个我觉得不用太担心。算力的边际成本一直在降，技术在进步，市场在竞争。流量当年也很贵，现在几乎是无感的存在了。Token大概也会走这条路，只是时间问题。

芯片、能源、算力，这些东西最终会变成水电煤——你每天都在用，但完全不会去想它。

到那个时候，现在大家纠结的"AI产品怎么回本"这个问题，可能根本就不需要回答了。

你觉得AI的费用应该由谁来承担？欢迎留言聊聊。

最近 OpenClaw（前身 Clawdbot）火遍硅谷到北京，有人说它是"AI 助手的终局形态"。两个月内斩获 14 万+ GitHub Stars，一堆人专门买 Mac Mini 跑它，二手价格都被炒起来了。

但它到底是怎么做到的？我把整个仓库 clone 下来，结合 AI 辅助，读了一遍源码——4700+ 个 TypeScript 文件，38MB，800+ 个 agent 相关模块。这篇文章是我的源码拆解笔记，你可以跟着我一起从技术视角搞清楚它的内部结构。

先说结论：其实没那么玄。

这是系列文章的第一篇，专讲架构。第二篇我们动手，用现有开源工具搭一个简易版 OpenClaw。

它究竟是什么？

用一句话描述：OpenClaw 是一个跑在你本地机器上的、以消息 App 为操控界面的持久化 AI Agent。

它不是聊天机器人，不是 Zapier 那样的自动化平台，也不是套壳 AI。核心差异就三点：

• 本地运行：数据不上云，你的代码、文件、记忆全在本机
• 持久化：24 小时在线，有 cron 定时任务，会主动工作
• 消息 App 为界面：你用 WhatsApp / Telegram / Discord / iMessage 跟它聊，它在后台对着你的电脑干活

整体架构：八层结构

读完代码，我把它的架构抽象成八层：

下面从上到下逐层拆解。

第一层：入口——六种方式操控同一个 Agent

最顶层是用户入口，OpenClaw 提供了多种交互方式，全部连到同一个 Gateway：

• CLI（src/cli/）：168+ 个命令文件，涵盖 agent 管理、浏览器调试、设备配对、cron 任务、插件管理等
• TUI（src/tui/）：基于 pi-tui 的终端交互界面，支持 ! 前缀进 shell 模式、/ 前缀触发命令
• Web UI（ui/）：独立的 Vite + React SPA，通过 REST/WebSocket 连接 Gateway
• macOS App（apps/macos/）：SwiftUI 菜单栏应用，内嵌 WKWebView 渲染 Canvas
• iOS App（apps/ios/）：SwiftUI 原生应用，集成日历、摄像头、通讯录、位置等系统服务
• Android App（apps/android/）：Kotlin 原生应用

移动端和桌面端通过 Bonjour/DNS-SD 自动发现局域网内的 Gateway（服务类型 _openclaw-gw._tcp），TXT 记录里编码了 TLS 指纹和端口号。配对成功后，设备获得一个带作用域的 token，后续自动连接。

这种设计的精妙之处在于：你可以躺在沙发上用手机给 AI 下指令，它在书房的 Mac Mini 上执行。

第二层：消息渠道——用 Baileys 协议搞定 WhatsApp

很多人好奇：WhatsApp 并没有开放 API，OpenClaw 是怎么接入的？

答案藏在 src/web/ 目录。它用的是 @whiskeysockets/baileys，一个逆向工程了 WhatsApp Web 协议的开源库。

原理非常优雅——本质上就是模拟你电脑浏览器开着 WhatsApp Web：

手机 WhatsApp ←→ WhatsApp 服务器 ←→ 本地 Gateway（Baileys 长连接）

关键点：连接是从你本地主动发起的（出站），不需要公网 IP。WhatsApp 服务器会通过 WebSocket 长连接把消息实时推过来。就像你打开 WhatsApp Web 一样，只不过接收端是 OpenClaw 的 Gateway，而不是浏览器。

WhatsApp 的底层协议实现在 src/web/（登录、会话、收发消息），而 extensions/whatsapp/ 是基于 Plugin SDK 的封装层，负责把 WhatsApp 以标准渠道插件的形式接入系统。

渠道层的代码分布在 src/ 和 extensions/ 两层，每个渠道独立一个包：

src/
├── web/           ← WhatsApp Baileys 协议底层实现
├── telegram/      ← Telegram 核心逻辑
├── discord/       ← Discord 核心逻辑
├── slack/         ← Slack 核心逻辑
├── signal/        ← Signal 核心逻辑
├── imessage/      ← iMessage（仅 macOS）
└── line/          ← LINE 核心逻辑

extensions/
├── whatsapp/      ← WhatsApp 渠道插件封装
├── telegram/      ← Telegram Bot API 插件
├── discord/       ← Discord.js 插件
├── slack/         ← Slack Web API 插件
├── imessage/      ← AppleScript 插件（仅 macOS）
├── signal/        ← signal-cli 插件
├── feishu/        ← 飞书 Webhook
├── msteams/       ← Microsoft Teams
├── matrix/        ← Matrix 协议
├── googlechat/    ← Google Chat
├── irc/           ← IRC
├── bluebubbles/   ← BlueBubbles（另一种 iMessage 方案）
└── ...（还有更多）

这个两层设计值得注意：src/ 放协议级的底层实现，extensions/ 放标准化的插件封装。每个渠道实现一套统一的 ChannelPlugin 接口，包含：认证、收发消息、媒体处理、群组管理等能力。这个设计让 Gateway 完全不关心下层是什么 App，消息统一流入。

第三层：Gateway——整个系统的心脏

src/gateway/ 是整个项目最核心的目录。Gateway 是一个常驻后台的 WebSocket 服务（默认端口 18789），所有客户端（CLI、Web UI、macOS App、iOS、Android）都通过 WebSocket 连接到它。它同时也提供 HTTP 端点用于健康检查和控制面板。

先看它的内部结构：

从 server-methods-list.ts 可以看到，Gateway 对外暴露了 100+ 个 WebSocket 方法，远不止"消息转发"这么简单。下面展开几个最关键的。

消息路由与状态机

收到消息后，Gateway 会根据发送人、群组、配置等判断：这条消息该不该响应？该交给哪个 Agent？

每个对话的执行状态由一个状态机管理（src/channels/run-state-machine.ts）：

// src/channels/run-state-machine.ts
// 模块级常量：心跳间隔 60 秒
const DEFAULT_RUN_ACTIVITY_HEARTBEAT_MS = 60_000;

export function createRunStateMachine(params: RunStateMachineParams) {
  let activeRuns = 0;
  // 跟踪并发执行数、心跳、超时
  // ...
}

状态机会跟踪每个对话的并发执行数，通过 60 秒一次的心跳向上游汇报"我还活着"。

会话管理

每个对话有独立的 session，以 JSONL 文件存储在本地文件系统（路径：~/.openclaw/agents/{agentId}/sessions/{sessionId}.jsonl）。每次 LLM 调用都会带上完整的历史上下文——OpenClaw 用文件系统实现了跨进程的持久化会话。

渠道健康监控

这是保证 7×24 稳定在线的关键（src/gateway/channel-health-monitor.ts）。

健康监控器每 5 分钟巡检一次所有已连接的渠道，检测"僵尸连接"——比如 Slack 的 WebSocket 看起来是活的，但实际上已经不推送消息了。它会根据最后一次收到事件的时间判断是否需要重启渠道连接。

安全措施：每小时最多 10 次自动重启，启动后有 60 秒宽限期，防止疯狂重连。

配置热重载

Gateway 用 chokidar（文件监听库）监控配置文件变化，300ms 防抖后自动重载（src/gateway/config-reload.ts）。

它会做配置 diff：逐字段对比新旧配置，只重新加载变化的部分。如果你改了 WhatsApp 的配置，它不会重启 Telegram 的连接。重载模式支持 hybrid（按需决定热重载还是全量重启）。

Boot 机制——用人话写的启动脚本

这是我觉得体现 OpenClaw 设计哲学的一个机制。（自然语言代替机器语言）

传统软件的启动脚本是 init.d、systemd、.bashrc——都是代码。而 OpenClaw 的启动脚本是一个 Markdown 文件，内容是自然语言。

用户在 Agent 的工作目录下创建一个 BOOT.md，写上人话：

每次启动后，给我的 WhatsApp 发一条"Gateway 已上线"。
然后检查一下今天的日历，如果有会议，提前提醒我。

Gateway 启动时，会遍历所有 Agent，读取各自工作目录下的 BOOT.md，把内容塞进 prompt 交给 Agent 执行：

// src/gateway/boot.ts
function buildBootPrompt(content: string) {
  return [
    "You are running a boot check. Follow BOOT.md instructions exactly.",
    "",
    "BOOT.md:",
    content,
    "",
    "If BOOT.md asks you to send a message, use the message tool.",
    // ...
  ].join("\n");
}

几个值得注意的设计选择：

• 用户手写，系统不生成。文件不存在就跳过，存在就执行——跟 .gitignore 一个思路，约定文件名。
• 每个 Agent 独立一份。不是全局一个 BOOT.md，而是每个 Agent 工作目录下各自一个。monitor Agent 启动时检查服务状态，assistant Agent 启动时发问候语——各司其职。
• 临时会话，不污染历史。执行时生成 boot-{时间戳}-{随机ID} 的临时 session，完成后恢复原始会话映射，回复用 NO_REPLY 令牌吞掉，不会出现在用户的对话记录里。
• 失败不阻塞。BOOT.md 执行失败只记 warn 日志然后 continue 到下一个 Agent，Gateway 照常启动。
• 它是一个Hook。Boot 机制实现在 src/hooks/bundled/boot-md/handler.ts，通过监听 gateway-startup 事件触发，是可插拔的——拿掉也不影响 Gateway 启动。

本质上，OpenClaw 把传统的 init.d 启动脚本降维成了自然语言，执行者从 shell 换成了 AI Agent。非程序员也能定义"AI 开机后该干什么"，同时怎么折腾都不会把系统搞挂。

接入认证

注意：这里的认证是谁可以连接 Gateway，不是 LLM 模型的 API Key 管理（那是 Provider 层的事）。

Gateway 支持四种认证方式（src/gateway/auth.ts）：

• none：无认证（仅限回环地址访问时）
• token：令牌认证
• password：密码认证
• trusted-proxy：信任代理（Tailscale 等）

还内置了速率限制（auth-rate-limit.ts），防止暴力破解。

执行审批

当 Agent 要执行危险命令时，Gateway 充当"门卫"：

Agent 想执行 rm -rf /tmp/data
  → Gateway 拦截
    → 推送审批请求到你的 Telegram / WhatsApp
      → 你回复"允许"
        → Gateway 放行

审批请求通过 exec.approval.request 方法发出，通过 exec.approval.resolve 方法回收决策。这能让你来实现人在外面也能远程批准或拒绝 Agent 的操作。

第四层：Hooks 与 Cron——自动化引擎

这层包含两套互补的自动化机制：Hooks（事件驱动，"如果……就……"）和 Cron（时间驱动，"每当……就……"）。

Hooks 事件系统

Hooks 本质上是一个贯穿全系统的事件总线。src/hooks/internal-hooks.ts 定义了五大事件类型：

注册钩子时，可以监听整个类型（如所有 message 事件），也可以精确到 type:action（如 message:received）。触发时，系统会同时通知两层监听者。

一个关键设计：钩子异常不会阻断主流程。每个 handler 的错误被独立 catch 和日志记录，保证一个插件崩溃不会拖垮整个系统。

这套机制让你可以做到：消息进来时自动打标签、Agent 调用工具前先审批、Gateway 启动后自动发状态通知——全部通过声明式的事件订阅，不用改核心代码。

Cron 定时任务

src/cron/ 是实现"主动 AI"的关键。它底层用 croner 库，支持两种调度模式：

• every：每隔 X 分钟/小时执行一次
• at：在特定时间执行一次

// src/cron/schedule.ts
export function computeNextRunAtMs(schedule: CronSchedule, nowMs: number): number | undefined {
  if (schedule.kind === "at") {
    // 处理精确时间调度
  }
  // 处理 cron 表达式（用 croner 库解析）
  const cron = resolveCachedCron(expr, timezone);

你可以跟 OpenClaw 说"每天早上 8 点给我发今日新闻摘要"，它会创建一个 cron job，时间到了自动执行，主动发消息给你。这就是它"不用你问，它主动找你"的实现原理。

Hooks 和 Cron 合在一起，覆盖了两种自动化场景：Hooks 响应系统内部事件（被动），Cron 按时间表主动触发（主动）。两者都通过 Gateway 调度，最终都是调用 Agent 来执行具体任务。

第五层：Agent 执行——本地 Coding Agent

这层是最有趣的部分。很多人以为 OpenClaw 自己实现了一个 AI Agent，但实际上——它调用的是外部的 Coding Agent CLI。

双引擎架构

看 src/agents/cli-backends.ts，OpenClaw 内置了两个 Agent 后端：

// 后端 1：Claude Code CLI
const DEFAULT_CLAUDE_BACKEND = {
  command: "claude",
  args: ["-p", "--output-format", "json",
         "--permission-mode", "bypassPermissions"],
  // ...
};

// 后端 2：Codex CLI
const DEFAULT_CODEX_BACKEND = {
  command: "codex",
  args: ["exec", "--json", "--sandbox", "workspace-write"],
  // ...
};

默认使用 Anthropic 的 Claude Code（src/agents/defaults.ts 写死了 DEFAULT_PROVIDER = "anthropic"，DEFAULT_MODEL = "claude-opus-4-6"）。也可以切换到 OpenAI 的 Codex。

但这里有一个容易混淆的概念需要区分——"谁来执行"和"谁来思考"是两回事：

• CLI 后端（执行引擎）：负责"怎么跑"——接收 prompt、spawn 进程、执行工具调用、管理 session。内置 Claude Code 和 Codex 两个，但代码里（第 243-250 行）留了扩展口：只要在配置里提供 command、args 等字段，就能注册任意自定义后端。
• LLM Provider（思考引擎）：负责"怎么想"——哪家的模型来生成回复。这个支持极其广泛。

从 models-config.providers.static.ts 里能看到硬编码的静态 Provider 就有一大堆：MiniMax、小米 Mimo、Moonshot/Kimi、通义千问、豆包(Doubao)、BytePlus、Together、OpenRouter、NVIDIA、千帆、Kilocode……再加上动态发现的 Ollama、HuggingFace、vLLM、Vercel AI Gateway，以及文档里记录的 Anthropic、OpenAI、Google Gemini、Mistral、Perplexity、AWS Bedrock、Azure 等——总计 28+ 个 Provider。

也就是说，你可以用 Claude Code 作为执行引擎，但让它背后调用通义千问或 Ollama 本地模型来"思考"；也可以用 Codex 作为执行引擎，配上 Google Gemini 来生成回复。执行引擎和思考引擎是正交的。

那这么多 Provider，底层是怎么统一调用的？答案是一个叫 @mariozechner/pi-ai 的 SDK（版本 0.57.1）。它负责抹平不同 LLM API 之间的协议差异。从代码里看，28 个 Provider 最终只需要适配两种 API 协议：

为什么大部分国产模型都走 openai-completions？因为 OpenAI 的 Chat Completions API 已经成了事实标准，几乎所有模型厂商都做了兼容。所以 OpenClaw 接入一个新模型，通常只需要配一个 baseUrl + API Key，不用写一行适配代码。

顺便说一句，OpenRouter 不是 OpenClaw 的路由框架——它只是 28 个 Provider 中的一个选项。OpenRouter 本身聚合了很多模型，所以配上它就等于一个 API Key 接入了几百个模型。但 OpenClaw 自己的 Provider 管理（Auth Profile 轮换、failover、模型发现）是独立实现的，不依赖 OpenRouter。

这两个后端都是本地运行的 Coding Agent——它们能读写文件、执行命令、调用 API。OpenClaw 的角色是"调度器"：接收用户消息，拼装上下文，调用底层 CLI，拿到结果后发回给用户。

两层权限模型

这里有一个容易误解的设计。OpenClaw 默认给底层 CLI 传了 --permission-mode bypassPermissions，意思是 Claude Code 层面不做任何权限确认。这听起来很危险，但安全由 OpenClaw 自己的执行审批层兜底：

为什么这么设计？因为 OpenClaw 是 7×24 无人值守运行的，如果两层都要弹确认，用户一条命令要批两次。所以在自己的层面做好管控，到底层就全放行。

一次调用的完整流程

src/agents/cli-runner.ts 的 runCliAgent() 揭示了每次 Agent 调用的完整过程：

1. 解析工作目录——每个 Agent 有独立的 workspace
2. 加载 bootstrap 文件——类似 CLAUDE.md 的上下文注入，有 token 预算管理（防止 prompt 过长）
3. 拼装 system prompt——追加心跳提示、额外指令
4. 选择模型和认证——从 Auth Profile 轮换中选一个可用的 API Key
5. 调用底层 CLI——spawn 子进程，JSON 格式通信
6. 流式接收输出——支持边生成边推送给用户
7. 处理失败——认证错误、限流、上下文溢出，各有不同的 failover 策略

另一条路：嵌入式运行

除了调外部 CLI，OpenClaw 还有一个嵌入式运行模式（src/agents/pi-embedded-runner/）——直接在进程内通过 pi-ai SDK 调用 LLM API，不经过外部 CLI。这条路径支持：

• Auth Profile 轮换（Key 挂了自动换下一个）
• 上下文窗口保护（CONTEXT_WINDOW_HARD_MIN_TOKENS 硬限制）
• 会话压缩（compactEmbeddedPiSession，对话太长时自动压缩历史）
• 模型 failover（主模型挂了切备用模型）

ACP——多智能体协议

src/acp/ 目录（30 个文件）实现了 Agent Communication Protocol，这是 OpenClaw "多智能体"能力的底层基础。

它允许一个 Agent 孵化子 Agent，各自独立运行：

• src/acp/server.ts — ACP 服务端，管理子 Agent 生命周期
• src/acp/client.ts — ACP 客户端，与父 Agent 通信
• src/acp/policy.ts — 权限策略，控制子 Agent 能做什么
• src/acp/translator.ts — 协议翻译，适配不同 LLM 的消息格式
• src/acp/persistent-bindings.ts — 持久化绑定，子 Agent 可以跨会话存活

比如你说"帮我同时查三个 API 的文档"，主 Agent 可以 spawn 三个子 Agent 并行处理，各自独立工作，最后汇总结果。

第六层：LLM Provider 与浏览器——模型管理 + 自动化

这层提供 Agent 执行时依赖的两大外部能力：LLM 模型调用和浏览器自动化。

LLM Provider——28 个供应商，挂了就换

这是独立于 Agent 执行层的一整套 模型供应商管理体系。

src/agents/auth-profiles/ 实现了一个带自动轮换的认证档案系统。每个 Provider（如 OpenAI、Anthropic、Google Gemini、通义千问等）可以配多个 API Key（称为 Auth Profile），系统会自动 round-robin 轮换，并根据失败原因区分处理：

• 瞬时故障（限流、过载）→ 设置 cooldownUntil，冷却后自动重试
• 永久故障（欠费、Key 失效）→ 设置 disabledUntil + 原因，需要人工介入

失败原因按严重程度分级：auth_permanent > billing > model_not_found > overloaded > rate_limit > unknown。

更有趣的是模型自动发现机制（src/agents/models-config.providers.discovery.ts）：

• Ollama：调用本地 /api/tags 获取已拉取模型列表，再逐个 /api/show 查询上下文窗口大小，8 个并发、5 秒超时
• HuggingFace / vLLM：走 OpenAI 兼容的 /v1/models 端点
• Vercel AI Gateway / Kilocode：各有专用的发现逻辑

这意味着你本地跑了新的 Ollama 模型，OpenClaw 可以自动发现并使用，不用手动配置。

浏览器 & 媒体——让 AI 用你的浏览器

src/browser/ 有 135+ 个文件，实现了一个完整的浏览器自动化框架。底层基于 Playwright 和 Chrome DevTools Protocol (CDP)。

这不是简单的网页爬虫——它是一个有状态的浏览器会话管理器：

• PageState 跟踪每个页面的控制台消息（上限 500 条）、页面错误（200 条）、网络请求（500 条）
• 通过 角色快照（Role Snapshot）生成页面的无障碍树（Accessibility Tree），每个可交互元素分配稳定引用 ID
• 导航前做 SSRF 防护检查，禁止访问内网地址

src/media/ 则处理多媒体：解析 Agent 输出中的 MEDIA: <path> 标记，管理媒体文件的存储和生命周期（2 分钟 TTL 自动清理），检查音频格式兼容性（Telegram 语音消息只接受 ogg/opus/mpeg/m4a），文件大小限制 5MB。

第七层：记忆与技能——知识库 + 插件生态

这层让 Agent 拥有长期记忆和可扩展能力。

记忆系统——向量数据库 + SQLite + FTS

这是 OpenClaw 跟普通聊天机器人最本质的区别。记忆系统默认开启，用户不需要手动配置。

存储层：SQLite 一库多表

看 src/memory/memory-schema.ts，记忆系统建在本地 SQLite 上（路径：~/.openclaw/memory/{agentId}.sqlite），有五张核心表：

-- 1. 键值元数据
CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);

-- 2. 源文件索引（跟踪哪些文件被记忆了）
CREATE TABLE files (
  path TEXT PRIMARY KEY,
  source TEXT DEFAULT 'memory',  -- 来源：memory 目录 or sessions
  hash TEXT NOT NULL,            -- SHA256，用于判断内容是否变化
  mtime INTEGER, size INTEGER
);

-- 3. 文本分块 + 向量嵌入
CREATE TABLE chunks (
  id TEXT PRIMARY KEY,       -- hash(path:startLine:endLine:hash:model)
  path TEXT, source TEXT,
  start_line INTEGER, end_line INTEGER,  -- 在原文件中的行号范围
  hash TEXT, model TEXT,     -- 用哪个模型生成的嵌入
  text TEXT,                 -- 分块原文
  embedding TEXT NOT NULL,   -- 向量，JSON 格式的 float 数组
  updated_at INTEGER
);

-- 4. FTS5 全文检索虚拟表（只索引 text 列，其余为元数据）
CREATE VIRTUAL TABLE chunks_fts USING fts5(
  text, id UNINDEXED, path UNINDEXED, source UNINDEXED, ...
);

-- 5. 二进制向量表（用于高效向量搜索）
-- embedding 以 Float32Array buffer 存储，避免 JSON 解析开销

写入：自动索引 + 智能分块

记忆系统会自动监听 memory/ 目录和 MEMORY.md 文件的变化（用文件 watcher，1500ms 防抖），变化后自动重新分块和嵌入。

分块策略（src/memory/internal.ts）：

• 按 400 token（约 1600 字符）切分
• 相邻分块之间有 80 字符重叠，保证语义连贯
• 每个分块独立嵌入，生成一个向量

嵌入后端支持多种：

嵌入结果会缓存在 embedding_cache 表里——同一段文本不会重复计算嵌入，换模型时才重新算。

读取：混合检索

检索时不是只用向量搜索，而是混合检索（src/memory/manager.ts）：

MMR（Maximal Marginal Relevance）算法在 src/memory/mmr.ts 里，用的是 Jaccard 相似度（词集交并比）来度量已选结果之间的重复度，公式：MMR = 0.7 × 相关性 - 0.3 × 与已选最大相似度。

如果没配嵌入后端（比如纯离线环境），系统会自动降级为纯 FTS 搜索——功能打折但不会挂。

Agent 怎么用记忆

记忆不是自动塞进 prompt 的——它通过两个工具调用实现：

• memory_search：搜索记忆，返回匹配的文本片段和来源引用
• memory_get：读取记忆文件的指定行范围

Agent 的 system prompt 里有一条显式指令（src/agents/system-prompt.ts）：

"Before answering anything about prior work, decisions, dates, people, preferences, or todos: run memory_search on MEMORY.md + memory/*.md; then use memory_get to pull only the needed lines."

也就是说，Agent 被教会了要先查记忆再回答——这不是硬编码的检索逻辑，而是通过 prompt 引导 Agent 自主决定何时、搜什么。

可选：LanceDB 向量后端

除了内置的 SQLite 方案，extensions/memory-lancedb/ 提供了一个可选的 LanceDB 后端（基于 Apache Arrow 的向量数据库）。它用 L2 距离做向量搜索，支持按类别（conversation / task / decision / context）组织记忆，适合对向量检索性能有更高要求的场景。

Skills 技能系统——插件市场

skills/ 目录和 extensions/ 目录是两套不同的扩展机制：

• Extensions：核心功能扩展，消息渠道、认证提供商等，随主程序一起发布
• Skills：轻量级技能包，社区发布，用户按需安装

一个 Skill 本质上就是一个 SKILL.md 文件——Markdown 格式，头部用 YAML frontmatter 声明元数据（名称、描述、依赖的工具、安装方式），正文用自然语言告诉 Agent 这个 Skill 怎么用、什么时候用：

skills/github/
└── SKILL.md      ← YAML frontmatter（元数据）+ Markdown（使用说明）

举个例子，skills/github/SKILL.md 的 frontmatter 里声明了需要 gh CLI，并提供了 brew/apt 两种安装方式；正文则包含"什么场景该用 / 不该用"和常用命令模板。Agent 会根据这些信息自主决定何时调用、怎么调用。

没有单独的 tools.yaml——工具定义直接内嵌在 Markdown 里。这种设计的好处是一个文件就是一个完整的技能包，降低了社区贡献门槛。

社区的 ClawHub 上目前有超过 13,000 个社区技能。这是 OpenClaw 最大的护城河——生态。

第八层：基础设施——安全和配置的地基

最底层的 src/config/ 和 src/infra/（300+ 个文件）支撑着整个系统：

配置系统：支持 JSON5 格式（允许注释和尾逗号），密钥引用（Secret Refs）可以指向环境变量、文件或命令输出，在配置导出时自动替换为占位符，防止明文泄露。

执行安全：src/infra/exec-approvals.ts 维护一个动态的命令白名单，支持 safe-bin（安全二进制）、custom-allowlist（自定义白名单）、always-ask（总是询问）三种策略。每条命令执行前还会通过 detectObfuscation() 检测是否有混淆注入。

路径沙箱：boundary-path.ts 确保文件操作不会逃逸出配置的沙箱根目录；archive-path.ts 防止 zip-slip 攻击；hardlink-guards.ts 通过检查 inode 数防止硬链接攻击。

结语：没有黑魔法

读完这八层，回到开头的结论：其实没那么玄。

OpenClaw 的每一层都不是从零发明的——Baileys 是现成的，Playwright 是现成的，SQLite + FTS5 是现成的，Claude Code / Codex 是现成的。它真正做的事情是把这些东西粘成一个 7×24 在线的、多渠道的、有记忆的 Agent 系统，然后在每一层都留下扩展口。

如果要用一句话总结它的设计哲学：用自然语言代替机器语言。BOOT.md 是自然语言的启动脚本，SKILL.md 是自然语言的插件包，记忆系统是自然语言的数据库查询。这不是"套壳"——这是一种新的系统设计范式，把 AI 当成操作系统的一等公民。

下一篇，我们不光看，还要动手——用现有的开源工具，搭一个简易版的 OpenClaw。

企业权限系统技术方案

核心调整：Role 是 Permission 的打包模板，真正的授权单元是 Permission，过期时间挂在用户-权限点授权上。数据范围通过 sys_scope_data 统一管理，外部系统只需对接同步任务即可接入新的数据维度。

一、核心设计思路

Role
  └─ 只是权限点的集合模板，方便批量操作，本身不是授权单元

Permission（权限点）
  └─ 才是真正的授权单元
  └─ 关联一个 DataResource（数据资源点）

用户授权流程：
  方式一：选角色 → 展开角色下所有权限点 → 逐个配置数据范围 + 过期时间 → 批量写入授权记录
  方式二：直接选权限点 → 配置数据范围 + 过期时间 → 写入单条授权记录

授权记录（sys_user_permission_grant）
  └─ 一条记录 = 用户拥有某个权限点的一次授权
  └─ 记录来源（通过哪个角色批量授予 or 单独授予）
  └─ 记录数据范围
  └─ 记录过期时间

二、表结构设计

2.1 权限点表 sys_permission

CREATE TABLE sys_permission (
  id               BIGINT PRIMARY KEY AUTO_INCREMENT,
  tenant_id        BIGINT       NOT NULL COMMENT '租户ID',
  perm_code        VARCHAR(128) NOT NULL COMMENT '权限编码，如 order:view',
  perm_name        VARCHAR(128) NOT NULL COMMENT '权限名称',
  type             TINYINT      NOT NULL DEFAULT 2 COMMENT '1菜单 2操作按钮 3API',
  data_resource_id BIGINT       COMMENT '关联的数据资源点，NULL 表示无数据权限',
  sort             INT          DEFAULT 0,
  remark           VARCHAR(255),
  created_at       DATETIME     DEFAULT CURRENT_TIMESTAMP,

  UNIQUE KEY uk_tenant_perm_code (tenant_id, perm_code)
);

2.2 数据资源点表 sys_data_resource

CREATE TABLE sys_data_resource (
  id            BIGINT PRIMARY KEY AUTO_INCREMENT,
  resource_code VARCHAR(128) NOT NULL UNIQUE COMMENT '资源编码，如 data:order',
  resource_name VARCHAR(128) NOT NULL COMMENT '资源名称，如 订单数据',
  description   VARCHAR(255),
  created_at    DATETIME DEFAULT CURRENT_TIMESTAMP
);

2.3 数据资源点可选范围表 sys_data_resource_scope

-- 元数据：定义某个数据资源点开放哪些范围选项
-- 授权配置时用，运行时不参与请求链路
CREATE TABLE sys_data_resource_scope (
  id               BIGINT PRIMARY KEY AUTO_INCREMENT,
  data_resource_id BIGINT       NOT NULL,
  scope_code       VARCHAR(64)  NOT NULL COMMENT '范围编码，如 ALL / DEPT / SELF / CITY / PROJECT',
  scope_name       VARCHAR(128) NOT NULL COMMENT '展示给管理员的名称',
  scope_type       TINYINT      NOT NULL COMMENT '1全量 2部门树 3本人 4实体列表（对接 sys_scope_data）',
  sort             INT          DEFAULT 0,

  UNIQUE KEY uk_resource_scope (data_resource_id, scope_code)
);

scope_type = 4 表示该范围的候选值来自 sys_scope_data，前端授权页面通过 scope_code 去 sys_scope_data 查候选列表，不需要调任何外部接口。

2.4 ⭐ 范围数据字典表 sys_scope_data

-- 统一存储所有数据范围的候选值
-- 外部系统通过同步任务写入，权限系统内部完全自洽
CREATE TABLE sys_scope_data (
  id           BIGINT PRIMARY KEY AUTO_INCREMENT,
  scope_code   VARCHAR(64)  NOT NULL COMMENT '范围类型，对应 sys_data_resource_scope.scope_code，如 CITY / PROJECT',
  entity_id    VARCHAR(64)  NOT NULL COMMENT '外部实体ID，VARCHAR 兼容各种ID类型',
  entity_name  VARCHAR(128) NOT NULL COMMENT '实体名称，授权页面展示用',
  entity_extra JSON         COMMENT '扩展信息，如层级路径、所属上级等',
  status       TINYINT      DEFAULT 1 COMMENT '1有效 0已下线',
  synced_at    DATETIME     COMMENT '最后同步时间',

  UNIQUE KEY uk_scope_entity (scope_code, entity_id),
  KEY idx_scope_code (scope_code)
);

entity_extra 示例：

// 城市，带省份信息
{ "province": "广东省", "province_id": "44" }

// 项目，带所属业务线
{ "biz_line": "电商", "owner": "张三" }

外部系统接入方式（唯一入口）：

INSERT INTO sys_scope_data (scope_code, entity_id, entity_name, entity_extra, synced_at)
VALUES ('CITY', '101', '上海', '{"province":"上海市"}', NOW())
ON DUPLICATE KEY UPDATE
  entity_name  = VALUES(entity_name),
  entity_extra = VALUES(entity_extra),
  synced_at    = VALUES(synced_at);

新接入一种数据维度（如"项目"、"区域"），只需要：

1. 在 sys_data_resource_scope 新增一条 scope_type=4 的配置记录
2. 跑一个同步任务往 sys_scope_data 写数据

权限系统本身零改动。

2.5 角色表 sys_role

-- Role 只是权限点的打包模板，不是授权单元
CREATE TABLE sys_role (
  id          BIGINT PRIMARY KEY AUTO_INCREMENT,
  tenant_id   BIGINT       NOT NULL COMMENT '租户ID',
  role_code   VARCHAR(64)  NOT NULL COMMENT '角色编码',
  role_name   VARCHAR(128) NOT NULL,
  is_super    TINYINT      DEFAULT 0 COMMENT '1超管角色，鉴权时直接放行，无需配置权限点',
  status      TINYINT      DEFAULT 1,
  remark      VARCHAR(255),
  created_at  DATETIME     DEFAULT CURRENT_TIMESTAMP,

  UNIQUE KEY uk_tenant_role_code (tenant_id, role_code)
);

2.6 用户-角色关系表 sys_user_role

-- 记录"这个人被分配了哪些角色"这件事本身
-- 职责：角色列表展示、角色级撤销/续期操作
-- 不参与鉴权，运行时权限校验只走 sys_user_permission_grant
CREATE TABLE sys_user_role (
  id          BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id     BIGINT   NOT NULL,
  role_id     BIGINT   NOT NULL,
  grant_by    BIGINT   COMMENT '授权操作人 user_id',
  start_time  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '生效时间',
  expire_time DATETIME COMMENT '过期时间，冗余字段，仅用于展示，鉴权以 sys_user_permission_grant 为准',
  status      TINYINT  DEFAULT 1 COMMENT '1有效 0已撤销',
  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,

  UNIQUE KEY uk_user_role (tenant_id, user_id, role_id),
  KEY idx_user_id (user_id),
  KEY idx_role_id (role_id)
);

职责边界：

• 写入时机：管理员通过角色授权，同时写入本表（1条）+ sys_user_permission_grant（N条，每个权限点一条）
• 读取场景：展示用户持有的角色列表、角色续期、一键撤销整个角色
• expire_time 冗余存储，方便 UI 展示剩余有效期，但鉴权不依赖此字段

与 sys_user_permission_grant 的联动逻辑：

• 给用户分配角色 → 写入 sys_user_role + 展开权限点批量写入 sys_user_permission_grant（source_type=1, source_id=role_id）
• 撤销用户角色 → DELETE sys_user_role + UPDATE sys_user_permission_grant SET status=0 WHERE source_type=1 AND source_id=role_id
• 查看用户拥有哪些角色 → 查 sys_user_role JOIN sys_role

2.7 角色-权限点关联表 sys_role_permission

-- 仅描述角色包含哪些权限点，是模板定义，不涉及授权
CREATE TABLE sys_role_permission (
  id            BIGINT PRIMARY KEY AUTO_INCREMENT,
  role_id       BIGINT NOT NULL,
  permission_id BIGINT NOT NULL,

  UNIQUE KEY uk_role_perm (role_id, permission_id)
);

2.8 ⭐ 用户-权限点授权表 sys_user_permission_grant

-- 核心授权表：真正的授权单元是权限点，过期时间在这里
CREATE TABLE sys_user_permission_grant (
  id               BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id          BIGINT       NOT NULL COMMENT '被授权用户',
  permission_id    BIGINT       NOT NULL COMMENT '授权的权限点',
  data_resource_id BIGINT       COMMENT '关联的数据资源点（冗余存储，方便查询）',
  scope_code       VARCHAR(64)  COMMENT '数据范围编码，来自资源点可选范围的子集',
  -- 具体的实体ID列表已拆出到 sys_grant_scope_entity，不再存 JSON

  -- 授权来源
  source_type      TINYINT      NOT NULL COMMENT '1通过角色批量授予 2单独授予 （可扩展：3岗位模板 4用户组等）',
  source_id        BIGINT       COMMENT '来源ID，与 source_type 配合使用，source_type=2 时为 NULL',
  grant_by         BIGINT       COMMENT '授权操作人 user_id',

  -- 有效期
  start_time       DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '生效时间',
  expire_time      DATETIME     COMMENT '过期时间，NULL 表示永久有效',

  status           TINYINT      DEFAULT 1 COMMENT '1有效 0已撤销',
  revoked_at       DATETIME     COMMENT '撤销时间，status 变为 0 时记录，用于审计',
  created_at       DATETIME     DEFAULT CURRENT_TIMESTAMP,
  updated_at       DATETIME     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,

  KEY idx_user_id (user_id),
  KEY idx_expire_time (expire_time),
  KEY idx_source (source_type, source_id),
  KEY idx_user_perm (user_id, permission_id)
);

2.9 授权实体明细表 sys_grant_scope_entity

-- 将原 custom_value JSON 拆成关系表
-- 支持正向查（用户被授权了哪些实体）和反查（某实体被授权给了哪些用户）
CREATE TABLE sys_grant_scope_entity (
  id           BIGINT PRIMARY KEY AUTO_INCREMENT,
  grant_id     BIGINT      NOT NULL COMMENT '关联 sys_user_permission_grant.id',
  scope_code   VARCHAR(64) NOT NULL COMMENT '范围类型，如 CITY / PROJECT',
  entity_id    VARCHAR(64) NOT NULL COMMENT '实体ID，对应 sys_scope_data.entity_id',

  KEY idx_grant_id (grant_id),
  KEY idx_entity (scope_code, entity_id)
);

查询示例：

-- 正向查：张三在 order:view 权限下被授权了哪些城市
SELECT e.entity_id, e.scope_code
FROM sys_grant_scope_entity e
JOIN sys_user_permission_grant g ON g.id = e.grant_id
JOIN sys_permission p ON p.id = g.permission_id
WHERE g.tenant_id = #{tenantId}
  AND g.user_id = #{userId}
  AND p.perm_code = 'order:view'
  AND g.status = 1
  AND (g.expire_time IS NULL OR g.expire_time > NOW());

-- 反查：城市101被授权给了哪些用户
SELECT g.user_id, g.expire_time
FROM sys_grant_scope_entity e
JOIN sys_user_permission_grant g ON g.id = e.grant_id
WHERE e.scope_code = 'CITY'
  AND e.entity_id = '101'
  AND g.tenant_id = #{tenantId}
  AND g.status = 1;

注意：查询时必须 JOIN sys_user_permission_grant 带上 tenant_id 过滤，sys_grant_scope_entity 本身不存 tenant_id，通过 grant 的 tenant_id 完成租户隔离。

2.10 权限操作审计日志表 sys_permission_audit_log

-- 记录所有权限变更操作，用于审计和问题排查
-- 只追加写入，不做 UPDATE/DELETE
CREATE TABLE sys_permission_audit_log (
  id             BIGINT PRIMARY KEY AUTO_INCREMENT,
  tenant_id      BIGINT      COMMENT '租户ID',
  operator_id    BIGINT      NOT NULL COMMENT '操作人 user_id',
  target_user_id BIGINT      NOT NULL COMMENT '被操作用户 user_id',
  action         VARCHAR(32) NOT NULL COMMENT 'GRANT_ROLE / REVOKE_ROLE / GRANT_PERM / REVOKE_PERM / MODIFY_SCOPE / MODIFY_EXPIRE',
  source_type    TINYINT     COMMENT '1角色授权 2单独授权',
  source_id      BIGINT      COMMENT '关联角色ID等',
  biz_data       JSON        COMMENT '操作详情快照，如授权的权限点列表、数据范围等',
  created_at     DATETIME    DEFAULT CURRENT_TIMESTAMP,

  KEY idx_tenant_target (tenant_id, target_user_id),
  KEY idx_operator (operator_id),
  KEY idx_created_at (created_at)
);

biz_data 示例：

{
  "roleId": 10,
  "roleName": "销售经理",
  "permissions": [
    { "permCode": "order:view", "scopeCode": "CITY", "entityIds": ["101", "102"] }
  ],
  "expireTime": "2027-03-05T00:00:00"
}

审计日志只追加，不更新。所有授权变更操作完成后同步写入一条记录，配合 revoked_at 字段可完整还原权限的生命周期。

三、关键设计决策说明

3.1 同一用户同一权限点可以有多条记录

场景：张三通过"销售角色"获得了order:view（永久），管理员又单独给他授予了order:export（30天）。

user_id | permission_id | source_type | source_id  | expire_time
张三    | order:view    | 1(角色)     | 销售角色ID | NULL（永久）
张三    | order:export  | 2(单独)     | NULL       | 2026-04-01

查询时取所有 status=1 AND (expire_time IS NULL OR expire_time > NOW()) 的记录并集。

3.2 角色变更不影响已有授权

Role 只是批量授权的入口，授权完成后，记录独立存在。
如果角色新增了一个权限点，不会自动同步给已授权的用户，需要重新授权（或提供"同步角色权限"的操作）。
这样设计保证了授权记录的稳定性，避免角色变更产生意外的权限扩散。

如果业务需要"角色变更自动同步"，可以通过 source_id（配合 source_type=1）找到所有关联用户批量更新，但需要明确产品策略。

3.3 撤销授权的两种粒度

-- 撤销单个权限点（同时记录撤销时间）
UPDATE sys_user_permission_grant
SET status = 0, revoked_at = NOW()
WHERE id = #{grantId};

-- 撤销某次角色授权（批量撤销该角色带来的所有权限点）
UPDATE sys_user_permission_grant
SET status = 0, revoked_at = NOW()
WHERE user_id = #{userId} AND source_type = 1 AND source_id = #{roleId};

3.4 超管优先级与判断链路

鉴权链路中，超管判断优先于一切权限点校验，按以下顺序执行：

1. JWT 解析 → 拿到 userId + tenantId
        ↓
2. 查 sys_user_tenant.is_super
   → is_super = 1：租户内超管，直接放行，跳过所有后续校验
        ↓
3. 查 sys_user_role JOIN sys_role WHERE is_super = 1
   → 用户持有超管角色：直接放行
        ↓
4. 普通权限点校验：查 sys_user_permission_grant
        ↓
5. 数据范围注入：根据 scope_code 注入 WHERE 条件

两种超管的区别：

• sys_user_tenant.is_super：平台运营直接在用户-租户关系上打标，不占用角色资源
• sys_role.is_super：通过分配超管角色实现，可以走正常的角色管理流程授权/撤销，更灵活

四、授权流程

4.1 通过角色批量授权

1. 管理员选择用户 + 角色
2. 系统查询角色下所有权限点（sys_role_permission JOIN sys_permission）
3. 对每个权限点，查出其关联的数据资源点及可选范围
4. 管理员逐一配置：数据范围 + 过期时间（可批量设置默认值）
5. 提交 → 批量写入 sys_user_permission_grant（每个权限点一条记录）
   source_type = 1, source_id = 角色ID

4.2 单独授权某个权限点

1. 管理员选择用户 + 权限点
2. 系统展示该权限点关联的数据资源点及可选范围
3. 管理员配置：数据范围 + 过期时间
4. 提交 → 写入一条 sys_user_permission_grant
   source_type = 2, source_id = NULL

五、运行时校验流程

5.1 加载用户权限

SELECT
  p.perm_code,
  g.data_resource_id,
  g.scope_code,
  g.expire_time
FROM sys_user_permission_grant g
JOIN sys_permission p ON p.id = g.permission_id
WHERE g.user_id = #{userId}
  AND g.status = 1
  AND (g.expire_time IS NULL OR g.expire_time > NOW())

5.2 操作权限校验（AOP）

@RequiresPermission("order:view")
// AOP 拦截 → 检查用户权限集合中是否包含 "order:view"

5.3 数据权限注入（MyBatis 拦截器）

GrantInfo grant = permissionCache.getGrant(userId, "order:view");

switch (grant.getScopeCode()) {
    case "ALL":            // 不追加条件
    case "DEPT_AND_CHILD": // WHERE dept_id IN (当前部门及子部门)
    case "DEPT":           // WHERE dept_id = #{deptId}
    case "SELF":           // WHERE created_by = #{userId}
    case "CITY":           // WHERE city_id IN (#{entityIds})
    case "PROJECT":        // WHERE project_id IN (#{entityIds})
}

六、缓存设计

TTL 动态计算：

long ttl = grants.stream()
    .filter(g -> g.getExpireTime() != null)
    .mapToLong(g -> Duration.between(now, g.getExpireTime()).getSeconds())
    .min()
    .orElse(1800);

ttl = Math.min(ttl + 60, 1800); // 最长不超过30分钟

缓存失效触发点：

• 新增/撤销/修改授权 → 失效 perm:user:{userId}:grants
• 授权到期（定时任务扫描）→ 失效 perm:user:{userId}:grants

七、系统架构图

八、ER 图

九、接口设计

接口分两侧：管理侧（权限配置与授权操作）和使用侧（鉴权与权限查询）。

租户隔离说明： 所有接口通过 JWT payload 中的 tenant_id 隔离租户，无需在请求参数中显式传递。切换租户需调用 /auth/switch-tenant 重新签发 JWT。

9.1 管理侧接口

权限点管理

数据资源点管理

范围数据字典（外部同步入口）

角色管理

用户授权管理

POST /users/{userId}/grant/by-role 请求体示例：

{
  "roleId": 10,
  "startTime": "2026-03-05T00:00:00",
  "expireTime": "2027-03-05T00:00:00",
  "scopeConfigs": [
    {
      "permissionId": 101,
      "dataResourceId": 1,
      "scopeCode": "CITY",
      "entityIds": ["101", "102", "108"]
    },
    {
      "permissionId": 102,
      "dataResourceId": 1,
      "scopeCode": "SELF"
    }
  ]
}

9.2 使用侧接口

权限加载

响应体示例：

{
  "permCodes": ["order:view", "order:export", "customer:edit"],
  "dataScopes": {
    "order:view": { "scopeCode": "CITY", "entityIds": ["101", "102"] },
    "customer:edit": { "scopeCode": "SELF" }
  },
  "menus": [
    {
      "permCode": "menu:order",
      "name": "订单管理",
      "path": "/order",
      "icon": "order-icon",
      "sort": 1,
      "children": [
        { "permCode": "menu:order:list", "name": "订单列表", "path": "/order/list", "sort": 1 }
      ]
    }
  ]
}

菜单是权限点中 type=1 的数据，不单独提供菜单接口，由本接口统一返回。

鉴权校验

十、多租户扩展方案

适用场景：平台需要支持多个租户（App）完全隔离，每个租户有自己独立的角色、权限点配置，用户可同时属于多个租户并自由切换身份。

10.1 核心设计思路

租户完全隔离 + 用户跨租户共享 + 租户级超管

- sys_role、sys_permission、sys_data_resource 等配置表加 tenant_id，数据完全隔离
- sys_user 不加 tenant_id，用户是平台级共享身份
- 用户与租户的归属关系通过 sys_user_tenant 管理
- 鉴权时 JWT 携带当前 tenant_id，所有查询强制带 tenant_id 过滤
- 超管标记在 sys_user_tenant 上，只在该租户内生效

10.2 新增表

租户表 sys_tenant

CREATE TABLE sys_tenant (
  id           BIGINT PRIMARY KEY AUTO_INCREMENT,
  tenant_code  VARCHAR(64)  NOT NULL UNIQUE COMMENT '租户编码',
  tenant_name  VARCHAR(128) NOT NULL COMMENT '租户名称',
  status       TINYINT      DEFAULT 1 COMMENT '1正常 0禁用',
  created_at   DATETIME     DEFAULT CURRENT_TIMESTAMP
);

用户-租户关系表 sys_user_tenant

CREATE TABLE sys_user_tenant (
  id          BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id     BIGINT  NOT NULL,
  tenant_id   BIGINT  NOT NULL,
  is_super    TINYINT DEFAULT 0 COMMENT '1该租户下的超管，跳过权限校验',
  status      TINYINT DEFAULT 1,
  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,

  UNIQUE KEY uk_user_tenant (user_id, tenant_id),
  KEY idx_user_id (user_id),
  KEY idx_tenant_id (tenant_id)
);

10.3 现有表字段改动

ALTER TABLE sys_role                  ADD COLUMN tenant_id BIGINT NOT NULL COMMENT '租户ID';
ALTER TABLE sys_permission            ADD COLUMN tenant_id BIGINT NOT NULL COMMENT '租户ID';
ALTER TABLE sys_data_resource         ADD COLUMN tenant_id BIGINT NOT NULL COMMENT '租户ID';
ALTER TABLE sys_data_resource_scope   ADD COLUMN tenant_id BIGINT NOT NULL COMMENT '租户ID';
ALTER TABLE sys_user_role             ADD COLUMN tenant_id BIGINT NOT NULL COMMENT '租户ID';
ALTER TABLE sys_user_permission_grant ADD COLUMN tenant_id BIGINT NOT NULL COMMENT '租户ID';

ALTER TABLE sys_user_permission_grant ADD INDEX idx_tenant_user (tenant_id, user_id);
ALTER TABLE sys_role                  ADD INDEX idx_tenant (tenant_id);
ALTER TABLE sys_permission            ADD INDEX idx_tenant (tenant_id);

不需要加 tenant_id 的表：

10.4 鉴权链路改动

Long userId   = token.getUserId();
Long tenantId = token.getTenantId();

boolean isSuperAdmin = userTenantService.isSuper(userId, tenantId);
if (isSuperAdmin) return;

Set<String> permCodes = permissionService.getPermCodes(userId, tenantId);
GrantInfo grant = permissionService.getGrant(userId, tenantId, "order:view");

10.5 用户切换租户

GET  /auth/me/tenants    查询当前用户所属的租户列表
POST /auth/switch-tenant 切换租户，返回新 token

GET /auth/me/tenants 响应示例：

{
  "tenants": [
    { "tenantId": 1, "tenantName": "华东事业部", "isSuper": false },
    { "tenantId": 2, "tenantName": "华南事业部", "isSuper": true }
  ],
  "current": 1
}

10.6 缓存 Key 加入 tenant_id

10.7 改动量总结

现有权限模型无需推倒重建，多租户是在原有模型上套了一层租户维度的壳，改动最小化。

OAuth 2.0 完全指南：从「用 GitHub 登录」到自己实现一个授权服务器

你一定见过这类按钮——「用 Google 登录」、「用 GitHub 登录」、「微信授权登录」。点进去跳一个页面，同意一下，就登录成功了，全程没有输过密码。

这背后用的就是 OAuth 2.0。

这篇文章从概念出发，把 OAuth 的完整知识体系过一遍：它解决什么问题、流程是怎么跑的、作为接入方怎么用、作为提供方怎么实现，以及 JWT、分布式、安全这些相关话题。

一、OAuth 解决什么问题

在 OAuth 出现之前，如果一个第三方应用想访问你在某平台的数据，通常的做法是把账号密码直接交给它。

这很危险：

• 第三方拿到密码就等于拥有你账号的全部权限
• 你没办法只授权「读」而不授权「写」
• 想撤销授权只能改密码，影响所有地方

OAuth 的核心思路是：不交密码，交一张有限权限的「通行证」（token）。

这张通行证：

• 只能访问你指定范围的资源
• 有有效期，过期自动失效
• 可以随时撤销，不影响密码

二、四个核心角色

OAuth 2.0 里有四个角色，理解它们是理解整个流程的基础：

实际场景里，授权服务器和资源服务器往往是同一家公司的不同服务，甚至同一个服务。

三、OAuth 不是认证，是授权

这是很多人容易混淆的一点。

授权（Authorization）：你能做什么
认证（Authentication）：你是谁

OAuth 2.0 本身只解决授权问题，它告诉第三方「这个用户允许你访问他的 xx 数据」，但不直接告诉你「这个用户是谁」。

要做登录认证，需要在 OAuth 上面加一层 OpenID Connect（OIDC），它扩展了 OAuth，额外返回一个 id_token，里面包含用户的身份信息。

我们平时说的「用 GitHub 登录」，其实是 OAuth + OIDC 一起在工作，只是大家习惯统称为 OAuth 登录。

四、四种授权模式

OAuth 2.0 规范定义了四种授权模式，适用于不同场景：

授权码模式（Authorization Code）
最常用、最安全的模式。有后端服务器的 Web 应用都用这个，token 在服务器之间交换，不暴露给浏览器。下文重点讲这个。

客户端模式（Client Credentials）
没有用户参与，是服务之间直接调用用的。比如订单服务调库存服务，不代表任何用户，直接用 client_id + client_secret 换 token。微服务架构里用得很多。

简化模式（Implicit）
专门给纯前端应用设计，直接把 token 放在 URL 里返回。因为 token 直接暴露在 URL 中不安全，现在已基本废弃。

密码模式（Resource Owner Password）
用户直接把账号密码给第三方应用，第三方再去换 token。违背了 OAuth 的设计初衷，现在也基本废弃，只在非常可信的内部系统偶尔使用。

实际开发中，有用户的场景用授权码模式，服务间调用用客户端模式，其他两种基本不用考虑。

五、授权码模式完整流程

state 防 CSRF 攻击

流程里有个容易被忽略但很重要的细节：state 参数。

攻击场景： 攻击者用自己的 GitHub 账号走到一半，拿到回调链接（带着他自己的 code），停下来把这个链接发给你。你点了之后，你的浏览器拿着攻击者的 code 去换 token，结果你的 B系统账号绑定了攻击者的 GitHub 账号，攻击者之后用自己的 GitHub 就能登进你的账号。

state 怎么防： 你发起登录时，B系统生成随机字符串 state，存在你的 session 里，同时带到跳转链接里。GitHub 回调时原样带回 state，B系统对比 session 里存的，对不上就拒绝。攻击者的链接里带的是他自己 session 的 state，跟你的对不上，攻击失败。

本质是一个 sessionID -> state 的 map，确保回调是本次登录发起的，不是别人伪造的。

六、Token 详解

AccessToken 和 RefreshToken

换 token 接口会同时返回两个 token：

• AccessToken：真正用来访问资源的，有效期短，一般几十分钟到几小时
• RefreshToken：用来在 AccessToken 过期后换新的，有效期长，一般几天到几个月

有效期由授权方决定，接入方控制不了。不同平台策略差异很大，GitHub 默认 AccessToken 永不过期，Google 则是一小时过期。

JWT Token

token 有两种实现方式：

随机字符串 token（传统方式）：token 本身不携带信息，服务器每次验证都要去数据库或 Redis 查「这个 token 对应哪个用户」。

JWT（JSON Web Token）：token 本身携带信息，服务器不需要查存储，直接解码验证。在分布式系统里优势明显，每台服务器只需要有密钥就能验证。

JWT 由三段组成，用 . 分隔：

Header.Payload.Signature

解码后：

// Header：算法信息
{ "alg": "HS256", "typ": "JWT" }

// Payload：实际数据
{
  "userId": "user001",
  "scope": "user:email",
  "exp": 1709280000
}

// Signature：用密钥对前两段做签名，防篡改

重要：Header 和 Payload 只是 Base64URL 编码，不是加密，任何人都能解码看到内容。 JWT 保证的是「不可篡改」，不是「内容保密」。所以 JWT 里绝对不能放密码、手机号这类敏感信息。

JWT 最大的缺点是无法主动失效，只能等过期。想撤销需要维护黑名单，但这样又引入了存储查询，优势就小了。

七、作为接入方：用 Go 接入 GitHub OAuth

Go 官方维护了 golang.org/x/oauth2 这个扩展库，封装了 OAuth 流程里所有繁琐的部分：生成授权链接、用 code 换 token、自动刷新 token、构造带认证的 HTTP 请求。

package main

import (
    "context"
    "crypto/rand"
    "encoding/base64"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "sync"

    "golang.org/x/oauth2"
    "golang.org/x/oauth2/github"
)

var oauthConfig = &oauth2.Config{
    ClientID:     "你的_GITHUB_CLIENT_ID",
    ClientSecret: "你的_GITHUB_CLIENT_SECRET",
    RedirectURL:  "http://localhost:8080/callback",
    Scopes:       []string{"user:email"}, // 查 GitHub 文档获取
    Endpoint:     github.Endpoint,        // SDK 内置，不用自己填 URL
}

var stateStore = struct {
    sync.Mutex
    m map[string]bool
}{m: make(map[string]bool)}

var tokenStore = struct {
    sync.Mutex
    m map[string]*oauth2.Token
}{m: make(map[string]*oauth2.Token)}

type User struct {
    ID     string `json:"id"`
    Login  string `json:"login"`
    Email  string `json:"email"`
    Avatar string `json:"avatar_url"`
}

var userStore = struct {
    sync.Mutex
    m map[string]*User
}{m: make(map[string]*User)}

func main() {
    http.HandleFunc("/login", handleLogin)
    http.HandleFunc("/callback", handleCallback)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

func handleLogin(w http.ResponseWriter, r *http.Request) {
    state := generateState()
    stateStore.Lock()
    stateStore.m[state] = true
    stateStore.Unlock()
    url := oauthConfig.AuthCodeURL(state)
    http.Redirect(w, r, url, http.StatusTemporaryRedirect)
}

func handleCallback(w http.ResponseWriter, r *http.Request) {
    state := r.URL.Query().Get("state")
    stateStore.Lock()
    valid := stateStore.m[state]
    delete(stateStore.m, state)
    stateStore.Unlock()
    if !valid {
        http.Error(w, "invalid state", http.StatusBadRequest)
        return
    }

    code := r.URL.Query().Get("code")
    token, err := oauthConfig.Exchange(context.Background(), code)
    if err != nil {
        http.Error(w, "换取 token 失败", http.StatusInternalServerError)
        return
    }

    // SDK 创建自动带 token 的 HTTP client
    client := oauthConfig.Client(context.Background(), token)
    resp, _ := client.Get("https://api.github.com/user")
    defer resp.Body.Close()

    var user User
    json.NewDecoder(resp.Body).Decode(&user)

    userStore.Lock()
    if _, exists := userStore.m[user.ID]; !exists {
        fmt.Printf("新用户注册: %s\n", user.Login)
    }
    userStore.m[user.ID] = &user
    userStore.Unlock()

    tokenStore.Lock()
    tokenStore.m[user.ID] = token // token 结构体里含 AccessToken、RefreshToken、Expiry
    tokenStore.Unlock()
}

func generateState() string {
    b := make([]byte, 16)
    rand.Read(b)
    return base64.URLEncoding.EncodeToString(b)
}

Endpoint 和 Scopes 从哪来

Endpoint 里是两个固定 URL，SDK 对主流平台都内置好了：github.Endpoint、google.Endpoint 直接用。如果是小众平台没有内置，自己查文档填：

var myEndpoint = oauth2.Endpoint{
    AuthURL:  "https://xxx.com/oauth/authorize",
    TokenURL: "https://xxx.com/oauth/token",
}

Scopes 是权限范围，每个平台的字符串定义不一样，必须查对方文档。没有统一标准。

Token 自动刷新

oauthConfig.Client() 返回的 HTTP client 每次发请求前会自动检查 AccessToken 是否过期，过期了自动用 RefreshToken 换新的。但刷新完 SDK 不会帮你存回数据库，需要自己实现 TokenSource 接口：

type myTokenSource struct {
    userID      string
    tokenSource oauth2.TokenSource
}

func (s *myTokenSource) Token() (*oauth2.Token, error) {
    token, err := s.tokenSource.Token()
    if err != nil {
        return nil, err
    }
    // 刷新后存回数据库
    tokenStore.Lock()
    tokenStore.m[s.userID] = token
    tokenStore.Unlock()
    return token, nil
}

八、OAuth 规范接口标准

如果你要自己实现授权服务器，必须遵循 OAuth 2.0 规范（RFC 6749）。规范规定了接口的参数名和返回格式，SDK 按照这个标准实现，所以只要你符合规范，任何语言的 SDK 都能对接你。

授权接口

GET /oauth/authorize
  ?response_type=code     # 固定值
  &client_id=xxx
  &redirect_uri=xxx
  &scope=user:email
  &state=abc123

用户同意后跳转回去：

302 -> redirect_uri?code=一次性授权码&state=abc123

换 Token 接口

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=一次性授权码
&client_id=xxx
&client_secret=xxx
&redirect_uri=xxx

返回格式规范规定必须是：

{
  "access_token": "xxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "xxxxxxx",
  "scope": "user:email"
}

刷新 Token 接口

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=xxxxxxx
&client_id=xxx
&client_secret=xxx

用户信息接口

这个接口规范没有强制规定，由你自己定义：

GET /api/user
Authorization: Bearer access_token

规范固定的： 参数名（grant_type、code、client_id 等）、返回字段名（access_token、expires_in 等）。
你自己定的： 接口地址、token 有效期、权限范围的名称、用户信息接口的返回结构。

九、作为提供方：用 Go 实现授权服务器

提供方没有像接入方那样开箱即用的通用 SDK，因为涉及太多业务逻辑。但有框架级别的库帮你省掉规范层的工作，Go 里常用的是 go-oauth2/oauth2。

整体架构

接入方（B系统）
    ↓ ↑
━━━━━━━━━━━━━━━━━━━━━━━━━━━
          对外接口层
  授权页 | 换token | 刷新token | 用户信息
━━━━━━━━━━━━━━━━━━━━━━━━━━━
          内部核心模块
  应用管理 | 授权管理 | token管理 | code管理
━━━━━━━━━━━━━━━━━━━━━━━━━━━
          基础设施
  用户系统 | MySQL | Redis
━━━━━━━━━━━━━━━━━━━━━━━━━━━

实现代码

package main

import (
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "time"

    "github.com/go-oauth2/oauth2/v4/errors"
    "github.com/go-oauth2/oauth2/v4/generates"
    "github.com/go-oauth2/oauth2/v4/manage"
    "github.com/go-oauth2/oauth2/v4/models"
    "github.com/go-oauth2/oauth2/v4/server"
    "github.com/go-oauth2/oauth2/v4/store"
)

var users = map[string]*User{
    "user001": {ID: "user001", Name: "张三", Email: "zhangsan@example.com", Password: "123456"},
}

type User struct{ ID, Name, Email, Password string }

var sessions = map[string]string{} // sessionID -> userID

func main() {
    manager := manage.NewDefaultManager()
    manager.SetAuthorizeCodeTokenCfg(&manage.Config{
        AccessTokenExp:    2 * time.Hour,
        RefreshTokenExp:   7 * 24 * time.Hour,
        IsGenerateRefresh: true,
    })

    // token 存储，换成 Redis 即支持分布式
    manager.MustTokenStorage(store.NewMemoryTokenStore())
    manager.MapAccessGenerate(generates.NewAccessGenerate())

    clientStore := store.NewClientStore()
    clientStore.Set("my_client_id", &models.Client{
        ID:     "my_client_id",
        Secret: "my_client_secret",
        Domain: "http://localhost:9090",
    })
    manager.MapClientStorage(clientStore)

    srv := server.NewDefaultServer(manager)

    // 关键钩子：框架来问你「这个用户登录了吗」，你来决定怎么判断
    srv.SetUserAuthorizationHandler(func(w http.ResponseWriter, r *http.Request) (string, error) {
        cookie, err := r.Cookie("session_id")
        if err != nil {
            http.Redirect(w, r, "/login?redirect="+r.URL.String(), http.StatusFound)
            return "", errors.ErrAccessDenied
        }
        userID, ok := sessions[cookie.Value]
        if !ok {
            http.Redirect(w, r, "/login?redirect="+r.URL.String(), http.StatusFound)
            return "", errors.ErrAccessDenied
        }
        return userID, nil
    })

    http.HandleFunc("/login", handleLogin)

    // 框架帮你处理参数解析、code 生成、跳转
    http.HandleFunc("/oauth/authorize", func(w http.ResponseWriter, r *http.Request) {
        srv.HandleAuthorizeRequest(w, r)
    })

    // 框架帮你验证 code、生成 token、返回规范格式
    http.HandleFunc("/oauth/token", func(w http.ResponseWriter, r *http.Request) {
        srv.HandleTokenRequest(w, r)
    })

    // 用户信息接口，自己定义
    http.HandleFunc("/api/user", func(w http.ResponseWriter, r *http.Request) {
        tokenInfo, err := srv.ValidationBearerToken(r)
        if err != nil {
            http.Error(w, "token 无效", http.StatusUnauthorized)
            return
        }
        user := users[tokenInfo.GetUserID()]
        w.Header().Set("Content-Type", "application/json")
        json.NewEncoder(w).Encode(map[string]string{
            "id": user.ID, "name": user.Name, "email": user.Email,
        })
    })

    log.Fatal(http.ListenAndServe(":8080", nil))
}

func handleLogin(w http.ResponseWriter, r *http.Request) {
    redirect := r.URL.Query().Get("redirect")
    if r.Method == http.MethodGet {
        fmt.Fprintf(w, `<form method="POST" action="/login?redirect=%s">
            <input name="username" placeholder="user001">
            <input name="password" type="password">
            <button>登录</button></form>`, redirect)
        return
    }
    user, ok := users[r.FormValue("username")]
    if !ok || user.Password != r.FormValue("password") {
        http.Error(w, "用户名或密码错误", http.StatusUnauthorized)
        return
    }
    sessionID := fmt.Sprintf("sess_%s_%d", user.ID, time.Now().UnixNano())
    sessions[sessionID] = user.ID
    http.SetCookie(w, &http.Cookie{Name: "session_id", Value: sessionID, Path: "/"})
    if redirect != "" {
        http.Redirect(w, r, redirect, http.StatusFound)
        return
    }
    fmt.Fprintf(w, "登录成功！欢迎 %s", user.Name)
}

框架帮你做的： 规范接口的参数解析、code 生成、token 生成、返回规范 JSON 格式。

你自己要做的： 用户登录逻辑（SetUserAuthorizationHandler 钩子）、用户信息接口、应用注册管理后台、存储层适配。

HTTP 框架兼容性

go-oauth2/oauth2 基于标准库 net/http，Gin、Echo、Chi 这些框架底层都是标准库封装，可以直接传：

// Gin 示例
r.GET("/oauth/authorize", func(c *gin.Context) {
    srv.HandleAuthorizeRequest(c.Writer, c.Request)
})

Fiber 不行，它用的是 fasthttp 而非标准库，类型不兼容，避免在这个场景下使用。

十、分布式环境下的注意事项

demo 里用的是内存存储，分布式环境下会出问题：用户在服务器 A 完成授权，token 存在 A 的内存里，下次请求打到服务器 B，验证失败。

解决方案是把存储换成 Redis：

import oredis "github.com/go-oauth2/redis/v4"

manager.MustTokenStorage(
    oredis.NewRedisStore(&redis.Options{
        Addr: "localhost:6379",
    }),
)

同样，session 也要换成 Redis 存储。框架逻辑本身没问题，只需要把所有内存存储替换成集中式存储，分布式就完全支持了。

小结

OAuth 2.0 的设计哲学是：密码永远只在用户和授权方之间，第三方只拿有限权限的 token。这个核心思路理解了，其他的都是实现细节。

写在前面

作为一个软件工程师，我一直对深度学习的概念停留在"知道但不理解"的阶段。PyTorch、TensorFlow、微调、蒸馏这些词天天看到，但到底是什么、怎么工作的，一直没有真正搞清楚。

这篇文章记录了我从零开始动手训练模型的过程，用软件开发的概念来类比深度学习的核心知识点。如果你和我一样是软件工程师背景，想搞懂这些东西，这篇文章应该能帮到你。

PyTorch 和 TensorFlow 是什么？

一句话：它们就是深度学习领域的开发框架，类似于 Web 开发中的 Spring 和 Django，只不过不是用来做 Web 应用的，而是用来构建和训练 AI 模型的。

PyTorch 由 Meta 开发，采用动态计算图，写起来更像普通 Python 代码，调试方便，目前在学术研究领域最受欢迎。

TensorFlow 由 Google 开发，早期用静态计算图，2.0 之后也支持动态图。它的优势在于生产部署生态更成熟（TensorFlow Serving、TensorFlow Lite 等）。

如果刚入门，大多数人推荐从 PyTorch 开始。

深度学习核心概念的软件工程类比

在动手之前，先用我们熟悉的概念建立映射：

一个关键认知：训练框架和推理引擎往往是解耦的。很多公司用 PyTorch 训练，然后把模型转换格式部署到专门的推理引擎上。就像你在 IDE 里写代码编译，但最终跑的是 jar 包在 Tomcat 上，而不是跑在 IDE 里。

动手：训练第一个模型

选的是深度学习的 "Hello World"——MNIST 手写数字识别。在 Mac 上用 PyTorch 完成。

环境准备

brew install python@3.12          # PyTorch 暂不支持 3.14
mkdir ~/mnist-demo && cd ~/mnist-demo
python3.12 -m venv venv
source venv/bin/activate
pip install torch torchvision

注：torch 就是 PyTorch 的包名，torchvision 是配套的图像处理库。

模型结构

class SimpleNet(nn.Module):
    def __init__(self):
        super().__init__()
        self.flatten = nn.Flatten()
        self.layers = nn.Sequential(
            nn.Linear(28 * 28, 128),   # 第1层：784 → 128
            nn.ReLU(),                  # 激活函数
            nn.Linear(128, 64),         # 第2层：128 → 64
            nn.ReLU(),
            nn.Linear(64, 10),          # 第3层：64 → 10（输出0-9）
        )

这里每个 nn.Linear 就是一层。层数和大小不是固定的，是你自己设计的，相当于系统的架构设计：

• 28×28 和 10 是由数据决定的（输入图片 28×28 像素，输出 0-9 十个数字），不能随便改
• 128 和 64 是你自己定的，可以改成 256、512，想加几层加几层
• ReLU 是激活函数，给模型引入非线性能力，没有它不管堆多少层数学上都等价于一层

不同场景的模型规模差别很大：我们这个 3 层、10 万参数；ResNet 上百层、几千万参数；GPT-4 据传上百层、万亿参数。

训练模板

几乎所有深度学习项目的训练循环都长这样：

for epoch in range(5):                        # 把所有数据学5遍
    for data, target in train_loader:          # 每次取一批数据
        optimizer.zero_grad()                  # 清空上次的梯度
        output = model(data)                   # 前向传播：模型答题
        loss = criterion(output, target)       # 算损失：对比答案，错了多少
        loss.backward()                        # 反向传播：找出哪些参数导致答错
        optimizer.step()                       # 更新参数：调整参数让下次更准

这五行代码是标准模板，不管训练什么模型几乎一字不变。区别只在于外面的 model、data、criterion 怎么定义。

其中：

• optimizer（优化器）：决定怎么更新参数，Adam 是最常用的
• criterion（损失函数）：衡量预测和正确答案的差距，分类任务一般用 CrossEntropyLoss
• lr=0.001（学习率）：每次调整参数的步幅，太大学飘，太小学不动

训练结果

🚀 开始训练...
  第 1/5 轮 | 损失: 0.2743 | 训练准确率: 91.9%
  第 2/5 轮 | 损失: 0.1137 | 训练准确率: 96.5%
  第 3/5 轮 | 损失: 0.0796 | 训练准确率: 97.6%
  第 4/5 轮 | 损失: 0.0625 | 训练准确率: 98.1%
  第 5/5 轮 | 损失: 0.0492 | 训练准确率: 98.4%
🧪 测试模型...
  测试准确率: 97.6%
💾 模型已保存到 model.pth

可以看到准确率从 91.9% 提升到 98.4%。但训练轮次不是越多越好，训练太多轮会出现过拟合——模型把训练数据的噪声都"背"下来了，遇到新数据反而不准。就像对测试用例做了太多特殊处理，测试全过了但上线就出 bug。

训练产出的 model.pth 就是我们的 AI 模型文件，里面是模型学到的所有参数权重。

关于"效果好不好"

不只是看训练准确率。测试准确率更重要，它衡量模型在没见过的数据上的表现（泛化能力）。到了大模型领域更复杂，需要从准确性、流畅度、幻觉率、推理能力等多个维度评估，各家发布模型时贴的 benchmark 跑分就是这个意思。

训练好的模型跑在哪？

这是一个重要的认知：训练框架 ≠ 推理环境。

训练确实需要跑在 PyTorch/TensorFlow 上，但推理（模型上线使用）有很多选择：

现在如果听到某家公司说"自己部署了大模型"，大概率后面跑的就是 vLLM。

为什么需要 GPU？

两个核心需求：算得快 + 放得下。

深度学习的本质是大量矩阵乘法，矩阵乘法天然可以拆成成千上万个互不依赖的小计算同时做。CPU 有几十个核心，GPU 有几千到上万个核心，虽然每个核心简单，但并行能力碾压 CPU。

类比：CPU 像一个资深工程师，什么都能干但只有一个人。GPU 像几千个初级工程师，每人只会简单运算，但可以同时干活。深度学习的活恰好就是把任务拆成几千份并行做。

GPU 有自己的显存（VRAM），模型必须加载到显存里 GPU 才能直接访问。大模型动不动几十上百 GB，一张 GPU 放不下就需要多张，这就是"模型并行"。

CUDA 和 NVIDIA 的护城河

CUDA 是 NVIDIA 的 GPU 编程框架，让 GPU 能做通用计算。PyTorch 底层调用 CUDA 来驱动 GPU。CUDA 经营了十几年，整个 AI 工具链都建在上面，这就是 NVIDIA 的护城河——不光硬件好，软件生态不可替代。

DGX Spark：桌面级 AI 超级计算机

NVIDIA 2025 年推出的 DGX Spark 是一台 Mac Mini 大小的 AI 专用电脑，128GB 统一内存（CPU/GPU 共享），售价约 $3,999，能在本地跑 200B 参数以内的模型。

有趣的是，苹果的 Mac Studio 用的也是统一内存架构，思路一样。区别在于 DGX Spark 原生支持 CUDA，AI 生态支持更好；Mac 更通用但 AI 优化不如 NVIDIA。

微调（Fine-tuning）

什么是微调？

拿一个已经训练好的模型，用你自己的少量数据再训练几轮，让它适应特定场景。

类比：预训练 ≈ 从零开发一个框架，投入巨大。微调 ≈ 拿成熟框架做二次开发，改配置加业务代码，快速适配需求。

为什么微调有效？

大模型在预训练阶段已经学会了语言能力和通用知识。微调不是让它学新技能，而是调整它的注意力和表达习惯。就像一个全栈工程师来你们公司干了三个月，底层能力没变，但他熟悉了你们的代码规范和业务术语。

微调不是炼丹，它的目标很清楚：用专业数据让模型在某个方向更准。只要数据质量好、量够，效果基本是确定性的。

动手微调

我们在手写数字识别模型的基础上，微调它来识别 26 个英文字母。核心思路：复用底层"怎么看笔迹"的能力，只重新训练输出层。

关键代码：

# 1. 加载旧模型，提取底层参数
old_model = OldSimpleNet()
old_model.load_state_dict(torch.load('model.pth'))

# 2. 创建新模型（26类），复用底层参数
model = NewSimpleNet(num_classes=26)
model.layers.load_state_dict(old_layers_params)

# 3. 冻结底层，只训练输出层
for param in model.layers.parameters():
    param.requires_grad = False

requires_grad = False 就是告诉 PyTorch 这些参数锁住不要动。类比 fork 了一个开源项目，核心模块设成 read-only，只在新加的模块里写代码。

微调结果

用 5000 张数据，只训练 1,690 个参数（总参数 11 万），1.1 秒训练完成：

  测试准确率: 49.2%

26 个字母随机猜是 3.8%，用这么少的数据和参数达到 49.2% 说明微调确实有效——底层复用的"看笔迹"能力起了作用。准确率不高是因为我们故意限制了数据量和可训练参数，用全量数据或解冻更多层效果会好很多。

蒸馏（Distillation）

什么是蒸馏？

用大模型教小模型。关键在于小模型学的不是标准答案，而是大模型的思考方式。

一张潦草的手写 3：

• 标准答案（硬标签）：这是 3
• 大模型输出（软标签）：3 的概率 70%，8 的概率 15%，5 的概率 10%

软标签里包含了"暗知识"——3 和 8 长得像、3 和 5 也有点像。小模型学这个概率分布，不光学到"这是 3"，还学到了数据之间的关联关系。

类比：硬标签 ≈ 给你一份接口文档，只有输入输出。软标签 ≈ 资深工程师坐在旁边，不光告诉你答案，还告诉你"这里容易和那个混淆"。

蒸馏怎么做？

两种方式：

1. 用大模型给现有数据打软标签，然后用软标签训练小模型
2. 让大模型直接生成数据（问答对、推理过程等），拿生成的内容训练小模型

DeepSeek-R1 用的就是第二种——让大模型生成大量带思考过程的回答，蒸馏出的小模型也学会了"先思考再回答"。

蒸馏的成本优势

从零训练顶级大模型可能要几亿美元。蒸馏的话，大模型已有（别人训练好的），花推理费用生成高质量数据（可能几十万美元），再训练小模型，总成本是从零训练的百分之一，效果能达到大模型的 80-90%。

蒸馏 vs 微调 vs RAG

如果你想让 AI 更懂你们的代码风格，最佳方案通常是 RAG + 微调，而不是蒸馏。

训练 AI 模型的工作量分布

最后总结一下训练 AI 模型的主要工作：

• 数据准备（60-70%）：收集、清洗、标注数据。就像数据库设计和数据治理往往比写业务代码更耗时
• 模型架构设计：选什么类型的网络、多少层、每层多大。靠经验和实验
• 超参数调优：学习率、批量大小、训练轮次等。这些不是模型自己学的，是人手动设的
• 训练和评估的反复迭代：跑一轮看效果，不好就调整，再跑。可能重复几十上百次

入门不难，核心训练模板就那几行代码。难在数据工程、模型设计的直觉、调参、数学基础、以及大规模训练的工程挑战。就像写 CRUD 不难，但设计高并发分布式系统很难。

完整代码

本文涉及的所有代码（训练、预测、微调）都可以在 Mac 上直接运行，总共几十行，几分钟跑完。这可能是你能找到的最简单的深度学习入门实践了。