hllqk blog

每周的总结

Sun, 01 Nov 2026 00:00:00 GMT

我已经很久没有写过周报了，与其叫周报，应该叫每周的复盘，听起来像是公司的复盘会一样，其实也大差不大了

日报我是一直有写的，但是每天都一两行，or 一两个字，复盘意义不大，而周报则可以总结一周的学习和工作，无论是公司 or 个人角度来看都是很有必要和价值的

现在开始复盘吧，这周其实都在处理公司的业务没有花太多时间学习自己的内容，这个是需要注意的，要多花时间提升自己，学习新知识和新的认知

论新知识，就凭着兴趣研究了一下量化策略，搞了一个量化 agent，经过几天的研究，终于还是抵不过腾讯理财通的年化率😂

除了学习了我一直都想学的量化，我要把自己心里一直想要的的博客给搭建出来了，现在我已经用上这个博客来发文章了，反正这个博客也没什么人看，就当我个人在这发内容了，然后还搞了最近很火的大肥鱼，成功让它能在 B 站上刷视频，然后发总结到我的 QQ 里面，让它自己去刷一些技术向的、对我有用的、工作上的视频内容，让我每天进行一个学习，感觉还是美滋滋的，而且还可以陪我聊聊天，也可以顺便帮我干一些电脑的杂活，毕竟它的底层是基于 Deepseekharness 的干活能力也不错，虽然相比 claude，codex 可能差远了

然后最近听了一些有关爱情的播客，现在对爱情有了更多新的认知，还有思考。然后也认识到自己，要以自己的情绪为主，多为自己考虑，多对自己好，多让自己开心，这是最重要的，别人的情绪你接不住，那就不用接，没必要专门为他人兜底，或者对他人有期待也更不要内耗，要学会转移注意力去做其他事情，转移注意力的方式有很多，但都比专门躺下休息好多，躺下的话，脑子空空，就只会不断回想你目前的担忧内容，然后反复咀嚼，这是毫无价值的，所以学会转移注意力也是处理情绪的一种很重要的课题，我们总是想要在情绪中找到解决方案，不亚于身在此山中，不知庐山真面目的感觉

只有当我们清醒理智的时候，我们才能做出正确的判断和选择

这正好也印证了我前几天看到的视频，不要在吵架的时候，对爱的人说伤人的话，也不要在晚上做决定

回到休息这个话题，我们前面提到，我们要学会转移注意力，而不是在有情绪的时候专门躺下休息，这样子会让我们完全无法休息到。但是有时候休息也是很重要的，在大部分方面。学习都讲就劳逸结合，但是这个道理谁不懂呢？只是也没有多少人能够做到，我大一在图书馆卷的时候，也是每天都是早出晚归，一天都要学满多少个小时才罢休，累了就还要学，直到累的不行了才趴着睡一会，这个时候搭子的翻书声就显得格外刺耳……有一个很卷的搭子其实并不是一件很好的事情，你也会被他的节奏所影响，而失去自己的节奏，如果没有自己的内核和节奏，花再多时间学习也是徒劳，不亚于一种流行的打卡文化，纯粹是一种自我感动式的学习

努力的人不一定成功，有效努力的人才能成功

我们要多做有效学习，比如一种心流状态的学习，我们可以不对自己设置一个下限，比如最少进入状态多少个小时，人的精力本来就很有限，很难保持一直高精力学习，有一种很著名的学习方式叫做番茄工作法，也顶多是 25 分钟专注学习然后休息 5 分钟

当然我们在公司肯定是不能 25 分钟专注再休息的，有些活是需要连续性的打磨的，至于到底该多久，还是看个人的精力和感受吧

如果你感觉自己精力低下，那就休息，在没精力的时候休息几分钟，可以恢复很多，如果几分钟不够，可能是被消耗的精力实在是太多了，已经为 0 电量了，那就需要花几个 h 休息了，不要硬撑，也不要自责没有花足够时间专注你的每一次休息都是为了更好的专注，为了更高效率。

如果感觉自己精力很多的话，那就可以进行一个连续几个小时的学习，当然，真别忘了放松，比如走一走，久坐的危害还是很多的，像我有些同事，年纪轻轻就已经…（

在这个高度信息化的时代，如何保持极度专注进行高效学习而不是纯靠意志力，是一个值得深入探讨的话题，有关这个话题，李大钊先生早就教导过我们：要学就学个痛快，要玩就玩个痛快

在累的时候休息，正好符合我们在舒适区边缘学习的原则，当我们疲惫的时候，正好是处于精力的边缘区，往里是高精力，往外是低精力，这个是我们休息，正好可以保持我们在高精力的状态里去处理舒适区边缘的内容，而且正因为有舒适区边缘的内容，我们才会消耗我们的精力，也才会学习到对我们来说不算困难、但价值比较大的内容，人只能赚到认知内的钱，也只能处理力所能及的事情

总之，我们要把困难的事情分解开来，处理我们力所能及的区域，累的时候就休息

真正的自控高手，不是只会一味地咬牙坚持，而是懂得主动休息，保持平衡的人

我也经常陷入这种自控困境，平时工作日都是奋力工作学习的，一到节假日就无法控制住自己，大玩特玩，又或者是熬夜通宵，明明知道不好，还总是控制不住，这也是因为没有得到足够的休息和放松，有时候太压抑自己、太控制自己，反而会适得其反，在学习的时候，给自己玩的时间，才不会让自己一直有一种亏欠的心理，才不会把这种亏欠以熬夜的方式补回来

要玩就白天玩，晚上是绝对要休息的！熬夜的危害实在是太多太多了……

有时候我总想把自己量化成机器，每天完成多少时长的学习，每天按部就班，有足够的自制力，希望自己能坚持，特别是在堕落后这种想法更加强烈，但是人的本能脑和情绪脑是天生趋利避害的，完全不是理性脑可以抗衡的，当一个想玩的念头出现，理性脑很难控制得住，去对抗是很难成功的，在经历了无数次失败和堕落和后悔后，我也渐渐地明白与天性作对是不可为，制止力也不一定代表行动力

这有一个很经典的列子，在堕落的时候，比如控制不住熬夜刷视频，玩游戏，然后晚上时间很晚了才睡觉，基本上都会后悔自己为何不早点睡觉，为何要做出那个选择，后悔的时候理智脑占据了上风，我们巴不得立刻改正，还列举了一大堆早睡早起的方案，结果第二天就忘了一个精光

改变自己的天性很难，人人都想玩，想放松，放松不够多了就会放纵，所以我们还是需要把安排时间放松的，比如休息，又或者娱乐，把他们放到白天，你的晚上就不会一塌糊涂，这也是对身体和精神的一种保护

当然有时候我们熬夜也不是单纯因为没有放松，可能是单纯无聊，又或者是孤独，又或者遇到了焦虑的事情

与其纠结怎么样解决这些事情，我也没有很好的办法，这些事情本身就很难解决，而且往往会在我们要入睡前来影响我们的情绪

但是我们可以提升认知，认知到第二天早起的重要性，是可以帮助我们在这些胡乱的思绪里面做出一个平衡的，就像第二天要早起上班一样

我们也可以改变环境，设置一些神经反馈机制，比如刷完牙之后、洗完澡之后就睡觉，又比如，遇到烦心事的时候，去干其他不相关的事情 15 分钟，往往是一种很好的解决情绪方案，再比如，我们每次坚持完之后，给自己一些正向奖励，我们才能不断地坚持，坚持坚持，再坚持，贯穿昆虫记的自始至终只有两字，坚持。

如果坚持早睡的话，那每天早上我们都会有一份很好的礼物，那就是纯净的注意力，我晚上的各种焦虑、各种烦心事，第二天起来都会少很多，或者直接清零，这是大脑的工作机制：它每天都要清空大脑里的各种缓存。这时候我们的精力和注意力是最强的，正是我们开始专注的最佳时机，然后通过这种专注，我们在触发我们的专注回路，越来越专注，久而久之就可以形成一个注意力的回路，我要早起专注，就相当于早上有工作要干，我们就会渐渐的养成一个早睡的习惯，早睡真的益处很多，我们不仅要意识到，还要实现它

关于早睡，网上有很多教程，我们要做的不单单是收藏，还要去学习，去运用，然后再输出相关教程，再通过输出倒闭输入，只有输出到其他人能通俗易懂的程度，我们才算真正的理解了这么一个事，真正才能运用这么一个事

我写博客，也是这么一个原理

而且不单单要让他能通俗易懂，还要让看的人能有收获感，所以要细心打磨自己的每一篇文章，像是孩子一样培养他，它也会渐渐的长大，在未来的某一天回馈你的，如果连自己写的文章都不用心，用 AI 随意生成一篇，又或者随便写点没用的内容，其他人又怎么会看呢

这周的总结就先到这吧，下周也要设置个待办提醒自己写总结，不能每次都忘记了，然后后面再搞一个年度总结、季度总结这些的，先有周总结，再有季度，再有年总结，感觉这样才能不断的进步和成长，加油，给自己说一句，“你是最棒的！”，我们干活需要有正向反馈，每天给自己打打气，多做做正向冥想之类的，有一个积极的心态，无论是对精神层面还是身体健康都有莫大好处！记住，人活着就是为了开心啊~

关于爱情的几件事

Sat, 31 Oct 2026 00:00:00 GMT

摘要：

1.他不是你的全部，你也不是他的全部。 2.再亲密的两个人也需要有自己的空间。 3.不要把你付出变成对方不知道存在的账单。 4.很多问题不是后来才出现的，只是你们以前没有聊过。 5.不是因为关系稳定了就停止吸引对方。 6.可以听别人的意见，但不要把自己的感情交给别人决定。

本来写了很多，但是都删了，要说的话太多了，但是又不知道从何说起，后面再写一篇专门讲讲吧

我是怎么样从零开始折腾的一个新博客

Fri, 30 Oct 2026 00:00:00 GMT

从我初中开始，搞过很多博客，最开始是从 GitHub Pages 上的 Jekyll 起步，后来换到 hllqk.cn 的 Hexo，以及各种常规的动态博客，比如 wordpress，最后现在搬到了 Notion + NotionNext

为什么选择了 Notion 呢？我平时也是把它当做知识库用来存文档的，后面听说可以拿来用博客，正好我也喜欢在手机上记录内容，Notion就成为了一个很好的同步平台。

选择 Notion 主要是因为它的方便，还有是因为它的图床是免费的，像是Jekyll它已经过时了，所以我后面选择了 Hexo，我花了整整 1 年时间提升它的 UI 和性能，还做了 SEO 优化，在这期间我花了不少心思，但最后还是弃用了，因为当时那个 hexo 版本太低了，导致了各种奇奇怪怪的前端问题，解决也很复杂。想要做一个兼容性的版本提升的话，在当时我也没有想出一个很好的办法。因为当时还是没有 AI 的，现在已经有 AI 了，应该可以非常方便的实现一个兼容性的提升。但是最后我还是选择了弃用，主要是因为，首先它想要实现在手机上发文章有点麻烦。我个人还是比较喜欢 Notion 这个软件，然后想实现在 Notion 上进行发文章的，正好看到有 Notion Next 这个项目，所以我就直接搭建了，由于用的是 Cf Page，所以是免费的，而且还可以做一个托管，也不单单是因为这一个点，还有一个点是因为以前做的那个博客太花里胡哨了，而且太花里胡哨的博客加载也很慢，这个博客的速度已经提升到了极致，至于怎么提升的，就是通过LightHouse 排查和各种性能测试，如果感兴趣，完全可以交给 CC 出一版方案，我个人觉得网站的速度提升还是很重要的，目前我现在的审美变成了比较喜欢简约风，而不是以前那种花里胡哨的页面，现在是喜欢类似 Claude 的那种页面，读起来不烧心，很舒服，非常感兴趣，所以我就搭建了现在这个博客，全程依靠 claude 开发，整体布局也参考了 claude，字体选用我最喜欢的白鹭文楷，由于这个博客遵循我的简约主旨，所以很快就搭起来上线了，目前算是定官盖论，不打算折腾了

果然正如三年前说的话一样，美化的尽头是默认，前几年搞的各种花里胡哨的博客，最终还是回到了朴朴素素的样子

至于为什么这么多年了，又重新开始写文章了，是因为我在想，自己学到一些东西，也要进行产出，只有能用文字来描述，才算真正的学习，只有能输出的内容能让一个不了解的人进行学习，自己才算是真正的了解透了这个内容

确实也有很多年没有写文章了，无论是写小说，还是写个人的日记，已经没有以前那种文采了，哈哈，感觉最近几年 AI 爆火，用 AI 写文本越来越多，越来越多那种 AI 生成的内容，看着非常的咬文嚼字，我本人感觉也深受其害，现在输出的内容，感觉自己也有点像 AI 生成的，已经没有人话了😃，但这些内容都是我一个个手敲的加上语音输入

希望自己能多多产出文章，提升自己的文笔，同时也能把一个内容了解透彻，通过输出、再输入、再输出，不断学习

在手机上用 Notion App 发博客：从写到上线

Wed, 28 Oct 2026 00:00:00 GMT

三步发出去

在博客数据库点「新建」，会自动带上 type=Post、status=Draft、date=今天。

写标题和正文。

status 改成 Published，放下手机就行。

停手约 10 分钟后网站开始更新，一般 15 到 25 分钟能看到，不用手动点。

发布和撤稿

Draft：怎么改都不会发。撤稿也是改回 Draft，会自动下线。

Invisible：不进首页和列表，知道链接的人能打开。

date：填未来的时间，到点自动发布；清空就用页面创建时间。

属性按需填

slug：空着会自动生成短链接，改标题也不变。自己填就用小写英文和短横线。发布后别改，旧链接会打不开。

summary：空着取正文开头约 120 字，加密文章不取。

category：空着归到「随笔」。可选 AI 与工具、算法与深度学习、开发笔记、环境配置、建站与博客、随笔、转载。

tags：可多选，也能直接打新标签，空着就没有。

password：填了就加密。读者输对一次，这台设备会记住；点「锁上」就要重新输。密码要长，别用 123456。

其余几个平时不用管：CAN_COPY 留空就允许复制，填 false 禁止复制这一篇；icon 不用填；featured 勾上会进首页「从这里读起」；series 和 seriesOrder 用来把几篇串成系列；source_url 是文章在别处首发时填原文地址。

正文和更新

图片：输入 /图片（英文界面 /image），选上传，从相册挑。

代码：输入 /代码（/code），点代码块左上角选语言。选对才有高亮，Plain Text 没颜色。

没更新：等了 25 分钟左右还没看到，就查 type 是不是 Post、status 是不是 Published。

页面顶部蓝条「This page is live on the web」说的是 Notion 自己的公开页，不是博客。

A/B 看不出来的时候，搜索排序还能怎么评

Mon, 26 Oct 2026 00:00:00 GMT

假设你改了一版搜索排序，开了 A/B 实验，跑了两周，数据上上下下地晃，就是不显著。那这次到底改好了还是改坏了？说不清。

这几天我在补搜索评估的资料，发现这种情况很常见，也有不少现成的办法。下面按我自己理解的顺序整理一遍。

✻ 01 · SCOPE

先想清楚：你到底想知道什么

「排序好不好」其实是三个不同的问题：

1.搜出来的东西和搜索词对不对得上。这叫相关性。

2.用户更爱点哪一版的结果。这是行为偏好。

3.换了排序以后，留存、转化有没有变。这是业务结果。

很多人会把点击直接当成「搜得准」，但这两件事不一样。排在第一位的东西，哪怕一般，被点的机会也比排第二十的好东西大得多，这叫位置偏差。后面讲的几种办法，各自只回答其中一个问题，先想清楚要哪个答案，再挑办法。

✻ 02 · POWER

实验看不出来，先算算样本够不够

A/B 没结论，最先该怀疑的是样本不够。当然也可能改动本来就没什么效果，或者指标选得不对。

样本要多少，有个现成的估算公式。Ron Kohavi 等人 2007 年在 KDD 发的实验指南里写的是：显著性水平 5%、想有 90% 的把握看出差别、各组人数差不多的时候，总共大约需要 n = (4rσ/Δ)² 个用户。r 是一共几个版本（对照组也算，普通 A/B 就是 2），σ 是指标的标准差，也就是它平时晃得有多厉害，Δ 是你想看出来的最小差别，按绝对值算。

论文里举了个假设的例子：转化率 5%，想看出 5% 的相对变化，也就是从 5% 涨到 5.25%，总共要不到 50 万人；要是只想看出 20% 的相对变化，也就是涨到 6%，3 万多人就够了。差别放大 4 倍，人数降到原来的 1/16，因为公式里是平方。

打个比方：想看清的东西越小，放大镜就得越大，而且是成倍地大。

有两个地方容易理解错：

●公式算出来的是「有 90% 的把握看出这么大的变化」要多少人，不是说小于这个变化就一定看不出来。

●不显著不等于没效果。更该看的是效果大概有多大、置信区间有多宽。区间很宽，说明还不知道；区间很窄、紧贴着零，才比较像是真没影响。

所以开实验之前，最好先拿自己的流量和指标的波动算一遍。如果你预计的改动幅度比能看出来的范围小一大截，就提前想别的办法，别等跑完了对着「不显著」发愁。

✻ 03 · SENSITIVITY

样本加不上去，就让实验更灵敏

第一招叫 CUPED，用老数据把噪声扣掉。这是微软的 Deng 等人 2013 年在 WSDM 发的方法。道理是：每个人的行为本来就有高有低，有人天天搜，有人一周搜一次。如果用实验开始前每个人的历史数据，把这部分「本来就有」的差异扣掉，剩下的波动就小多了。论文总结 Bing 上的结果时说，波动（方差）降一半，就只需要一半的用户或者一半的时间。

不过要注意三点：不同指标能扣掉多少差别很大；「时间减半」还要看用户多久回来一次、观察多长时间；拿来扣的历史数据必须是实验开始前的，不能被这次实验影响。另外它不是一种新实验，只是分析 A/B 结果的一种算法。

第二招叫交错实验（interleaving），把两版结果混在一起给同一个人看。普通 A/B 是分两拨人、各看一版；交错实验是同一次搜索里，把两版的结果按一定规则混成一个列表，看用户点的更多来自哪一版。

常用的混法叫 Team-Draft，有点像两个队长轮流挑队员：每轮随机决定谁先挑，各自挑自己排序里还没被选走的最好结果，这样哪一版都不会总占着前排。点击记给挑中那条结果的一方。因为是同一个人在同一个列表里比较，人和人之间的差异就不干扰了，比较排序时通常比分组实验灵敏得多。

它的局限是只能告诉你「用户更爱点哪一版」，看不到整页体验、长期留存、收入这些。

✻ 04 · OFFLINE

线上信号不够，就在线下评相关性

还有一种办法是不等用户点，自己准备一批搜索词，给每条结果打「相关不相关」，算个分，两版用同样的词比一比。几个要点：

1.先想好要评什么，再挑词。想知道整体体验，就按真实搜索的频率来挑，热门词多挑；想专门看冷门词，就把热门、中等、冷门分开挑、分开算。两种目的别混在一个平均数里。

2.相关分几档。「很相关、有点相关、不相关」比只分对错更能看出两版的差别。

3.用 NDCG@k 算总分。每条结果按相关程度给分，越靠前的权重越大，最后除以「理想排法」能拿到的分数。k 是只看前几条，比如前 10 条。两版要用同一批词、同一套打分标准、同一个 k。

4.算一下误差。一批词上分数高一点，可能只是碰巧挑到了好词。可以把这批词反复重新抽样来算，看差值的置信区间有多宽。

5.简单规则只能粗筛。比如「结果的标签包含全部搜索词就算相关」，算起来快，但包含了不代表用户想要，没包含也不代表不相关。

✻ 05 · LABELS

打分谁来打：人还是模型

人来标最常见，但慢、贵，而且人也会看错，会对规则理解不一。现在有一种做法是让大模型来标。

微软的 Paul Thomas 等人在 SIGIR 2024 的论文里讲了 Bing 怎么做：先拿真实搜索者的详细反馈当参照，挑出跟这些反馈最一致的模型和提示词，再让模型大批量地标。在他们的设置下，模型标出来的质量能跟人工差不多，在 Bing 的数据上还比他们对比的外包标注员好。论文也提到，提示词只是换个说法，跟参照的一致程度就会变。

所以用模型来打分，一定要留一批没用来调提示词的数据做检验：

1.准备一批人工认真标过的参照答案，尽量贴近真实用户想要什么。

2.按搜索词把它分成两份：一份用来调，一份用来验。同一个词不要两份里都有。

3.在第一份上挑模型、改提示词；定下来以后，只在第二份上看一次准不准。

4.正式评的时候，把两版结果混在一起、不告诉模型哪条来自哪版，免得它偏心。

5.过一阵子再抽一批让人看一遍，确认标准没有慢慢跑偏。

还有一个坑：如果简单规则和模型其实看的是同一份标签，它俩说法一致也证明不了什么，标签一错，两边一起错。这也是为什么要单独留一批人工检验的数据。

✻ ∞ · EPILOGUE

最后

这些办法回答的不是同一个问题。线下评相关性，看的是搜得准不准；交错实验，看的是用户更爱哪一版；A/B 加上 CUPED，看的是业务数据有没有变。流量够，三件事都能做。流量不够，A/B 最后可能还是给不出明确结论，这时候老老实实写「还不确定」，比硬下结论强。

我自己还没想明白的一点：线下评下来相关性变好了，线上点击却变差了，这时候该信哪个？你们碰到过吗？

✻ ✻ ✻

AI 写代码变快以后，我卡在了哪里

Wed, 21 Oct 2026 00:00:00 GMT

✻

写代码已经不是瓶颈了，瓶颈到了 git、构建和 CI 这些环节。

—— 转述自 Anthropic 工程博客

10 月 13 日，Anthropic 发了一篇工程博客，讲他们为什么自己做了一套版本控制系统。

起因是合并量。今年 5 月，他们的主仓库每天大约合并 2500 次，到 9 月超过了 3 万次，Claude 让代码产出涨得太快。主分支历史大约 100GB，CI 每天要 checkout 约 2500 万次，原来的 git 镜像在容量和运维上都吃不消。新系统把提交、合并、rebase 放到服务端执行，文件用到才拉，CI 拉代码从几分钟缩到几秒。

我在一家公司做后端实习，量级跟他们没法比，卡住的原因也不一样。他们是机器扛不住吞吐，我这边多半是拿不准 AI 写的东西到底对不对。相同的一点是，代码写完之后的那些环节，开始比写代码本身更费时间。

本文看点

01测试是绿的，不代表真测过

02三篇 agent 工程文章，和我的对照

03评估这件事，我还没做好

✻ 01 · IN PRACTICE

我这边的情况

实习三个多月，我合了 140 多个 PR，分在 11 个仓库，大部分代码是 Claude Code 和 Codex 写的。我的时间越来越多花在三件事上：看它改了什么，核对测试环境里跑的是不是这版代码，决定这次改动要验到什么程度才算完。这是体感，我没拿数据算过。

踩得最多的几个坑：

●本地跑 lint 太吃内存，两个同时跑会被系统杀掉。后来我就不在本地跑了，交给 CI。

●测试显示通过，不代表真跑过。缺一个依赖工具，相关的那几条测试会自动跳过，结果照样是绿的。

●测试环境就绪了，跑的也不一定是我这次的提交。我会先核对版本号，对上了再测。

✻ 02 · READING NOTES

读到的几篇文章

最近几个月读了些讲 agent 工程的文章，有几篇正好能对上。

✻ 出一次错，补一处环境

Terraform 的作者 Mitchell Hashimoto 今年 2 月写了自己用 AI 的经历，提到“engineer the harness”：agent 每犯一次错，就在它的工作环境里补一样东西，让这类错少犯。补法有两种，一是写进 AGENTS.md 这类说明文件，二是给它写专门的工具，比如截图、只跑相关测试、做验证。

我也是这么一条条补上来的，分两类。一类是说明文件：每个模块目录下有一份 AGENTS.md，要求动代码前先读。它只起提醒作用，AI 偶尔还是会漏看。另一类是钩子，由程序直接拦：数据库迁移有个校验文件只能用命令生成，为了防止 AI 手改，碰它就拦下；一轮对话结束时还有没提交的改动，也会被拦住提醒。

能写成钩子的我尽量写成钩子。说明文件靠模型自觉，钩子不用。

✻ 上下文要管

LangChain 10 月 14 日写了他们的 Deep Agents 怎么管理记忆。按文中的默认配置：工具返回超过约 2 万 token 就存成文件，模型只看一段预览和路径；上下文用到 85% 时把旧消息压成摘要，完整记录另存，需要时能翻回去；skill 平时只给简介，用到才读全文；长期记忆放在一个 markdown 文件里，每次调用模型都带上。文件在自己手里，换了模型也能接着用。

我给 Claude Code 也攒了一个记忆文件夹，现在 141 条，一条记一件事：哪个环境的地址是什么，哪个测试本来就会随机失败，哪类消息不许它自己发出去，某个功能上线后该看哪条日志。另有一个索引，每条一行。开新对话时先读索引，具体内容用到再打开。

好处是不用每次从头交代背景。问题是会过期，我隔一阵就得清一遍，不然它会把三周前的状态当成现在。

✻ 一个写，一个审

Cognition（做 Devin 的公司）去年 6 月写过《Don’t Build Multi-Agents》，反对让多个 agent 同时改代码，理由是每个 agent 都会做别人看不到的决定，合到一起就冲突。今年 4 月同一位作者写了续篇，说法有了调整：多个 agent 一起改代码，现在仍然不太行；只让一个 agent 改，其他 agent 负责审查或者在难题上出主意，这种做法已经能用了。

他们 6 月推出的 Fusion 就是这个思路，9 月又放进了桌面端和命令行。一个强模型当 lead，定计划、审结果；一个便宜的模型当 sidekick，翻代码、改代码、跑测试，两边只传任务说明和结果。按他们贴出的数据，成本降了一到四成多。得分方面，Fable 那组和单用强模型基本持平，Astra 那组有两项掉了 5 到 6 分，比如 Terminal-Bench 4 从 55.6 降到 50.0。

我平时的做法简单得多：Claude Code 写完，让 Codex 用高推理强度看一遍这次改动的文件，它提的问题我核过再决定改不改，接近续篇里说的“上下文干净的审查者”。至于效果来自换了个模型，还是来自换了一个没被前面对话带偏的上下文，我没对比过，说不准。

✻ 03 · OPEN QUESTIONS

还没解决的

最难的还是判断一件事做完了没有。

LangChain 10 月 15 日讲 agent 评估的那篇，建议从一个具体行为入手：从真实运行记录里挑 10 到 20 个例子做成测试集，先跑出基线，之后每次改动都跟基线比，线上发现的新失败再补进去。能用代码判断的用代码，判断不了的让模型打分，再用人工抽查这两者。

我做搜索排序时用过类似的办法：拿一批真实的搜索结果，先用规则打分，再让模型抽查，两边一致才往下推。现在回头看，缺了人工校准这一步。规则和模型可能偏向同一种错，两边一致也说明不了结果就是对的。

Anthropic 那篇最后提到，做这套系统的工程师把更多精力放在了定设计约束和审查改动意图上，因为 agent 有时会违反系统约束，或者写一堆没必要的防御代码。我现在花时间最多的，也是想清楚这次要验什么、验到哪一步。

你们用 AI 写代码以后，有没有被“测试是绿的，但其实没测到”坑过？

✻ ✻ ✻

我是 hllqkb，一名后端实习生，在这里记录用 AI 写代码时踩过的坑。

Claude Code 进阶使用指南

Wed, 29 Jul 2026 00:00:00 GMT

本文档基于 Claude Code 官方文档（code.claude.com/docs）核实整理，整理日期 2026-07-29。每节末尾附来源链接，可点击查看最新版本。

1. CLI 命令与常用 Flags

1.1 启动方式

方式	命令	说明
交互模式	`claude`	启动交互式会话
交互 + 初始提示	`claude "query"`	启动会话并附加初始提示
无头模式	`claude -p "query"`	执行后退出，返回结果
管道输入	`cat file.txt \| claude -p "query"`	从 stdin 读取，处理后退出
继续最近会话	`claude -c` / `claude --continue`	继续最近对话
恢复指定会话	`claude -r "session-id"` / `claude --resume`	恢复指定会话或显示选择器

1.2 核心 Flags

会话管理

Flag	短形式	说明
`--continue`	`-c`	加载最近对话
`--resume`	`-r`	按 ID 或名称恢复会话
`--name`	`-n`	设置会话显示名称
`--session-id`	—	使用特定 UUID 会话
`--fork-session`	—	恢复时创建新会话 ID，不覆盖原会话

输入 / 输出

Flag	说明
`--print` / `-p`	非交互模式，打印结果后退出
`--output-format`	`text` / `json` / `stream-json`
`--input-format`	`text` / `stream-json`
`--json-schema`	用 JSON Schema 约束结构化输出
`--verbose`	详细日志

模型与推理深度

Flag	说明	有效值
`--model`	指定模型	完整模型名或别名 `opus` / `sonnet` / `haiku`
`--effort`	推理努力级别	`low` / `medium` / `high` / `xhigh` / `max`
`--fallback-model`	主模型不可用时的备用模型	逗号分隔模型名

权限与安全

Flag	说明
`--permission-mode`	`default` / `acceptEdits` / `plan` / `auto` / `dontAsk` / `bypassPermissions`
`--dangerously-skip-permissions`	跳过所有权限提示，等同 bypassPermissions，仅在完全信任输入时使用
`--allowedTools`	无需提示即可执行的工具，支持前缀匹配，如 `"Bash(git diff *),Read"`
`--disallowedTools`	禁用指定工具
`--tools`	限制可用的内置工具集

流控制与自动化

Flag	说明
`--max-turns`	限制 agent 轮次（无头模式常用）
`--max-budget-usd`	最大支出限制，超过即停止
`--bare`	跳过 hooks / skills / MCP / CLAUDE.md 等自动发现，用于 CI 可重现执行
`--mcp-config`	指定 MCP 配置文件或 JSON
`--strict-mcp-config`	只用指定的 MCP 配置，忽略自动发现

工作树与并行

Flag	说明
`--worktree` / `-w`	创建或进入隔离 git worktree
`--tmux`	为工作树创建 tmux 会话
`--background` / `--bg`	启动后台会话

1.3 实用组合示例


# 无头 + 限定工具 + 限制轮次：一次性修复任务
claude -p "Find and fix type errors in src/" \
  --allowedTools "Bash,Read,Edit" \
  --max-turns 5

# 无头 + JSON 输出 + 成本追踪
claude -p "Analyze this codebase" \
  --output-format json | jq '.total_cost_usd'

# 工作树隔离 + 计划模式：大改动前先出方案
claude --worktree feature-x --permission-mode plan

# 管道处理日志
cat error.log | claude -p "解释这个报错的根因"

来源：https://code.claude.com/docs/en/cli-reference.md

2. 交互模式进阶

2.1 常用内置斜杠命令

命令	说明
`/init`	生成或改进项目 CLAUDE.md
`/clear`	清空上下文开始新对话（保留项目记忆）
`/compact [说明]`	总结压缩上下文，可附压缩侧重点
`/context`	可视化当前上下文占用
`/memory`	编辑 CLAUDE.md 与自动记忆
`/model [name]`	切换模型
`/effort [level]`	设置推理努力级别
`/plan`	切换到计划模式
`/rewind`	回滚代码与对话到检查点
`/resume`	会话选择器
`/fork`	复制当前对话到新后台会话
`/diff`	交互式差异查看器
`/code-review [--fix]`	审查当前差异，可自动应用修复
`/security-review`	检查差异中的安全问题
`/usage` / `/cost`	查看 token 使用与成本
`/permissions`	管理批准规则
`/mcp`	MCP 服务器管理
`/hooks`	查看 hook 配置
`/doctor`	环境诊断
`/export [文件名]`	导出对话为纯文本
`/add-dir`	添加额外工作目录
`/config`	打开设置界面

2.2 键盘与输入技巧

操作	说明
`!`	直接在会话内执行 bash 命令，输出进入上下文
`#`	添加记忆备注（写入自动记忆）
`@`	引用文件，缩小问题空间
`Esc`	中断当前生成
`Shift+Tab`	循环切换权限模式
`Ctrl+R`	搜索命令历史
`Ctrl+G`	用外部编辑器编辑当前输入
`Ctrl+V`	粘贴图像
`Ctrl+T`	切换待办列表显示
`Ctrl+O`	切换详细转录
Tab	补全命令、文件路径

Vim 模式：/config 中 Editor mode 设为 vim；用 vimInsertModeRemaps 可配置如 jj 映射 Escape。

来源：https://code.claude.com/docs/en/interactive-mode.md 、https://code.claude.com/docs/en/keybindings.md

3. 记忆体系（CLAUDE.md）

3.1 层级与加载顺序（优先级从低到高）

优先级	作用域	位置
1	用户全局	`~/.claude/CLAUDE.md`
2	项目	`./CLAUDE.md`（随 git 提交，团队共享）
3	项目本地	`./CLAUDE.local.md`（gitignored，个人私有）
4	嵌套目录	`/CLAUDE.md`（读到该目录文件时按需加载）
5	项目规则	`./.claude/rules/*.md`（支持路径作用域）
6	用户规则	`~/.claude/rules/*.md`
7	托管策略	IT 管理下发，不可排除

3.2 Import 语法


@README.md                      # 相对路径
@~/.claude/shared-rules.md      # 主目录展开

最大递归 4 层；代码块和反引号内的 @ 视为字面量

3.3 自动记忆

存储位置：~/.claude/projects//memory/，MEMORY.md 为索引

每次会话只加载索引前 200 行或 25 KB（先到为准），主题文件按需读取

用 /memory 管理，或设置 autoMemoryEnabled: false 关闭

来源：https://code.claude.com/docs/en/memory.md

4. Skills（自定义斜杠命令）

自定义命令已合并进 Skills；.claude/commands/ 仍向后兼容，但推荐用 Skills

位置：.claude/skills//SKILL.md（项目级）或 ~/.claude/skills/（用户级），可带支持脚本和子目录


---
name: deploy
description: 何时触发的说明，Claude 据此自动调用
model: haiku            # 可选，专用模型
tools: ["Read", "Bash"] # 可选，限制工具
invocation: user        # auto 自动触发 / user 仅手动 / never 禁用
---

技能正文：具体指令与流程...

来源：https://code.claude.com/docs/en/skills.md

5. Subagents（子代理）

位置：.claude/agents/.md 或 ~/.claude/agents/

Claude 遇到匹配 description 的任务时自动派发；子代理有独立上下文、工具集与权限，完成后只把摘要带回主会话

典型场景：探索性搜索（隔离上下文污染）、代码审查、并行实现


---
name: code-reviewer
description: 审查代码改动时使用
model: sonnet
tools: ["Read", "Bash"]
isolation: worktree     # 可选，独立工作树防止文件冲突
---

代理系统提示...

来源：https://code.claude.com/docs/en/sub-agents.md

6. Hooks（钩子）

6.1 常用事件

事件	触发时机	exit 2 行为
`PreToolUse`	工具执行前	阻止该工具调用
`PostToolUse`	工具成功后	不阻止，stderr 反馈给 Claude
`UserPromptSubmit`	用户提交提示前	阻止该提示处理
`Stop`	Claude 准备结束响应时	阻止停止，强制继续
`SessionStart` / `SessionEnd`	会话开始 / 结束	不可阻止
`SubagentStop`	子代理完成	可阻止
`PreCompact` / `PostCompact`	上下文压缩前后	—
`PermissionRequest`	需要权限决策时	拒绝权限
`Notification`	Claude 发送通知时	—

6.2 配置格式（settings.json）


{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": "/path/to/check.sh" }
        ]
      }
    ]
  }
}

matcher 支持精确名（Bash）、多选（Bash|Edit）、正则（mcp__.*__write.*）、全部（*）

hook 类型：command（本地脚本）与 http（POST 到远程 URL）

输入通过 stdin 传 JSON（含 session_id、tool_name、tool_input 等）

6.3 Exit code 语义

Exit code	含义
0	成功，解析 stdout 中的 JSON
2	阻止性错误，stderr 内容作为原因
其他	非阻止错误，继续执行

提示：CLAUDE.md 里的规则是「建议」，Claude 可能遗忘；hooks 是「硬约束」，由 harness 强制执行。硬性纪律（如禁止 push main、提交前必须 lint）应沉淀为 hooks。

来源：https://code.claude.com/docs/en/hooks-guide.md 、https://code.claude.com/docs/en/hooks.md

7. MCP（Model Context Protocol）

7.1 常用命令


claude mcp add  stdio -- node /path/to/server.js   # 本地 stdio
claude mcp add  http https://example.com/mcp       # 远程 HTTP
claude mcp add  sse https://example.com/sse        # 远程 SSE
claude mcp list                                          # 列出服务器
claude mcp login                                   # OAuth 认证
claude mcp remove                                  # 移除

7.2 作用域

Scope	位置	共享方式
local	`~/.claude.json`	个人所有项目
project	`.mcp.json`（随 git 提交）	团队共享
managed	服务器下发	IT 管理

7.3 .mcp.json 示例


{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/github-mcp/index.js"],
      "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN" }
    },
    "remote-api": { "type": "sse", "url": "https://api.example.com/mcp" }
  }
}

来源：https://code.claude.com/docs/en/mcp.md

8. 设置与权限（settings.json）

8.1 层级优先级（从低到高）

~/.claude/settings.json（用户全局）

.claude/settings.json（项目，git 提交）

.claude/settings.local.json（项目本地，gitignored）

--settings 参数

托管设置（IT 下发，最高）

CLI flags（--model 等）临时覆盖当次调用。

8.2 权限规则语法


{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Bash 规则用前缀匹配（* 通配参数）；文件规则支持 glob（Edit(src/**)）

deny 优先于 allow；敏感文件（.env、密钥）建议显式 deny

MCP 工具可整体匹配：mcp__github__*

来源：https://code.claude.com/docs/en/settings.md 、https://code.claude.com/docs/en/permissions.md

9. 无头模式与自动化

9.1 Print mode 脚本化


# 结构化输出
claude -p "Extract all function names" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}}}'

# 流式输出（适合接入其他程序）
claude -p "Explain" --output-format stream-json --include-partial-messages

# 批量并行任务
for f in $(cat files.txt); do
  claude -p "迁移 $f" --allowedTools "Edit,Bash" &
done

JSON 输出包含 structured_output、session_id、total_cost_usd 等字段，方便脚本消费。

9.2 Bare mode（CI 推荐）

--bare 跳过 hooks、skills、MCP 自动发现、auto memory、CLAUDE.md 加载，保证 CI 中行为可重现；需要的配置用 --settings / --mcp-config / --append-system-prompt 显式传入。

9.3 GitHub Actions

在 Claude Code 交互模式运行 /install-github-app 一键安装，或手动配置：


jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this PR for security issues"
          claude_args: "--max-turns 5 --model claude-sonnet-5"

来源：https://code.claude.com/docs/en/headless.md 、https://code.claude.com/docs/en/github-actions.md

10. 其他进阶技巧

10.1 Worktree 并行开发


claude -w feature-auth            # 创建或进入隔离工作树
claude -w feature-auth --tmux     # 配合 tmux

多个功能互不干扰，可同时开多个 Claude 会话并行开发

gitignored 但构建必需的文件（如 .env、嵌入资源）可通过 .worktreeinclude 声明自动复制

settings.json 中 worktree.baseRef 控制基于远程默认分支（fresh）还是当前 HEAD

10.2 Plan mode

大改动前用 /plan 或 --permission-mode plan：先只读探索并产出方案，批准后再动手，避免方向错了浪费轮次。

10.3 成本控制

/cost 查看当前会话花费；--max-budget-usd 给无头任务设硬上限

模型选择：简单任务用 Haiku，日常用 Sonnet，复杂推理和审查用 Opus

上下文优化：/context 看占用、/compact 主动压缩、不相关任务之间 /clear

10.4 会话管理


claude -n "auth-refactor"         # 命名当前会话
claude --resume "auth-refactor"   # 按名称恢复
claude --resume abc123 --fork-session   # 恢复并分叉，不影响原会话

来源：https://code.claude.com/docs/en/worktrees.md 、https://code.claude.com/docs/en/sessions.md 、https://code.claude.com/docs/en/costs.md

附：官方文档索引

主题	URL
文档地图	https://code.claude.com/docs/en/claude_code_docs_map.md
CLI 参考	https://code.claude.com/docs/en/cli-reference.md
交互模式	https://code.claude.com/docs/en/interactive-mode.md
记忆系统	https://code.claude.com/docs/en/memory.md
Skills	https://code.claude.com/docs/en/skills.md
Subagents	https://code.claude.com/docs/en/sub-agents.md
Hooks	https://code.claude.com/docs/en/hooks.md
MCP	https://code.claude.com/docs/en/mcp.md
设置	https://code.claude.com/docs/en/settings.md
权限	https://code.claude.com/docs/en/permissions.md
无头模式	https://code.claude.com/docs/en/headless.md
GitHub Actions	https://code.claude.com/docs/en/github-actions.md
Worktrees	https://code.claude.com/docs/en/worktrees.md
Agent SDK	https://code.claude.com/docs/en/agent-sdk/overview.md

Matt Pocock Skills 使用指南

Fri, 24 Jul 2026 00:00:00 GMT

mattpocock-skills 插件怎么用。2026-07-24 整理自官方仓库和网络资料，2026-07-29 用大白话重写了一遍。

一套给 Claude Code 用的工程纪律 skills，作者 Matt Pocock，就是写 Total TypeScript 的那位。GitHub 上很火，不同来源统计 54k 到 80k+ star。

这是什么

核心想法就一句话：别让 AI 凭感觉瞎写（所谓 vibe coding），把它按进正经软件工程的流程里。写之前先把需求盘清楚，写的时候走 TDD，写完自己 review，隔几天治理一次架构。

它跟 GSD、BMAD、Spec-Kit 那类框架的区别是不接管你的流程。每个 skill 都很小，能单独用，能自己改，换个模型也能跑。

本机已经用 Claude Code 插件方式装好了：marketplace 是 mattpocock（仓库 github.com/mattpocock/skills），插件 mattpocock-skills@mattpocock，v1.2.0，启用 22 个 skills。

为什么需要它

Matt 把 AI 写代码的翻车归成四类，每类给一个解法：

翻车现场	根因	解法
AI 做的不是我想要的	你没说清楚，或者你自己也没想清楚	/grill-me、/grill-with-docs，动手前让 agent 反过来拷问你
AI 老是理解偏、说话绕	项目黑话没有共享定义	/grill-with-docs 顺手建一份 CONTEXT.md 术语表
代码跑不对	写完没有反馈回路去验证	/tdd 红绿重构、/diagnosing-bugs 调试循环
架构越写越烂	AI 只是把熵增加速了	/improve-codebase-architecture，隔几天跑一次

最出名的是 grilling（拷问）系列。用法很简单：每次要动手改东西，先被拷问一轮，agent 会追着问，直到需求的每个分支都清楚为止。别嫌烦，这一步收益最大。

先做 setup，一个仓库一次

每个仓库第一次用之前跑：


/setup-matt-pocock-skills

它问三件事然后落成配置：用哪个 issue tracker（GitHub / Linear / 本地文件）、triage 给 ticket 打什么标签、生成的 spec / ADR / 术语表放哪。不跑这一步，工程类 skills 缺配置干不了活。

ps. 插件装的 skills 是只读的，跟着作者更新走。想改成自己的版本，用 npx skills@latest add mattpocock/skills 把文件拷进项目里再改。

核心工作流(常规开发流程)

从想法到合并，一条链路把 skills 串起来：


想清楚          →  /grill-me 或 /grill-with-docs   拷问对齐，顺手建领域文档
产出规格        →  /to-spec                        把对话固化成 spec 发到 tracker
拆任务          →  /to-tickets                     拆成一个个小 ticket，带阻塞关系(很少使用)
动手实现        →  /implement                      按 spec/ticket 写，内部走 /tdd
写代码走 TDD    →  /tdd                            红-绿-重构，一次一个纵切片
调试            →  /diagnosing-bugs                复现、最小化、假设、插桩、修、回归测试
提交前审查      →  /code-review or 叫ai review一下（如果有review工作流）                  规范和需求两个轴并行审
定期治理架构    →  /improve-codebase-architecture  扫改进点，出可视化报告

活太大、一个会话装不下，用 /wayfinder：把工作拆成 tracker 上的一张决策 ticket 地图，一个个啃，直到通往目标的路清晰。

拿不准该用哪个，直接问 /ask-matt，它就是个路由器。

Skills 全清单

skills 分两种调用方式。user-invoked 只能你手打 /xxx 触发，负责编排流程；model-invoked 你能手动调，agent 匹配到任务时也会自己调，装的是可复用的纪律。

工程类，日常写代码用

user-invoked：

Skill	干嘛的
/ask-matt	路由器，告诉你当前情况该用哪个 skill
/grill-with-docs	拷问的同时建领域模型，更新 CONTEXT.md 和 ADR，作者自称本仓库最酷的技巧
/triage	用状态机给 issue 和外部 PR 分类、验证，产出 agent 能直接执行的简报
/improve-codebase-architecture	扫描架构改进点，出可视化 HTML 报告，挑一个拷问细化
/setup-matt-pocock-skills	每个仓库首次使用前的一次性配置
/to-spec	把当前对话直接合成规格发到 tracker，不再访谈
/to-tickets	把计划或规格拆成小 ticket，带阻塞边
/implement	按 spec 或 ticket 实现，接缝处驱动 /tdd，收尾走 /code-review
/wayfinder	超大工作量的规划，产出决策 ticket 地图

model-invoked：

Skill	干嘛的
/tdd	测试驱动开发，红绿重构，一次一个纵切片
/diagnosing-bugs	硬骨头 bug 和性能回归的纪律化诊断循环
/code-review	双轴审查 diff：守没守规范，有没有忠实实现需求，并行子 agent 跑
/research	只查高可信一手来源，产出带引用的 md，后台 agent 跑
/domain-modeling	构建和打磨领域模型，拿术语表和边界场景压测
/codebase-design	深模块设计的共享词汇：小接口藏大行为、放在干净接缝、可测
/prototype	建一次性原型回答设计问题，可跑的终端 app 或多套 UI 变体
/resolving-merge-conflicts	逐 hunk 解 merge/rebase 冲突，按意图溯源，绝不 --abort

生产力类，不限代码

user-invoked 有四个：/grill-me 纯拷问对齐、/handoff 把对话压缩成交接文档给下一个 agent、/teach 多会话教你一个概念、/writing-great-skills 是写 skill 的参考。

model-invoked 一个：/grilling，拷问循环的本体，grill-me 和 grill-with-docs 背后复用的就是它。

杂项

/git-guardrails-claude-code 装 hook 拦危险 git 命令（push、reset --hard、clean、branch -D 这些）、/setup-pre-commit 配 Husky + lint-staged + 类型检查 + 测试、/migrate-to-shoehorn、/scaffold-exercises。

其它，谨慎用

personal：/edit-article、/obsidian-vault，Matt 个人写作和笔记用的

in-progress 实验性：/loop-me、/wizard、/claude-handoff、/batch-grill-me、/to-questionnaire、/writing-*、/setup-ts-deep-modules

deprecated 别用：/qa、/ubiquitous-language、/design-an-interface、/request-refactor-plan

常见场景速查

你想干嘛	用这个
开始一个新功能，需求还很模糊	/grill-me 或 /grill-with-docs
讨论完了，固化成正式规格	/to-spec 然后 /to-tickets
有 spec 或 ticket，开始写	/implement，内部会用 /tdd
想测试先行地写代码	/tdd
有个诡异 bug 或变慢了	/diagnosing-bugs
提 PR 前自查	/code-review
感觉代码越来越难改	/improve-codebase-architecture
活太大一个会话装不下	/wayfinder
不知道该用哪个	/ask-matt
会话要结束，交给下一个 agent	/handoff

注意事项

刚装完的会话里 skills 可能还没加载，下次启动才完全生效。

新仓库先跑 /setup-matt-pocock-skills，不然工程类 skills 缺 tracker 和文档配置。

token 开销：整套常驻大约 1.4k tokens 每会话，单个 skill 被调用时另算，diagnosing-bugs 约 2.8k，triage 约 2.2k。claude plugin details mattpocock-skills@mattpocock 能看明细，不用的可以 claude plugin disable 关掉。

插件版是只读的，想 hack 就用 skills.sh 的安装器把文件拷进项目。

再说一遍，grilling 是精髓，改动前先被拷问一轮，收益最大。

参考来源

官方仓库：github.com/mattpocock/skills · skills.sh 页面

The Two Matt Pocock Skills I Use in Almost Every AI Coding Session — Medium

Matt Pocock's 5 Claude Code skills made me rewrite how I work with AI agents — Medium

Claude Code Skills: mattpocock's 80K-Star Framework — AI Agents First

Matt Pocock's Skills Review — andrew.ooo

mattpocock/skills Explained — knightli.com

How to Use Matt Pocock's Skills for Claude Code: A Complete Guide — Tosea.ai

Matt Pocock's Skills Repo Is a Better Pattern Than Vibe Coding — Developers Digest

mattpocock-skills — Claude Plugin Hub

补充：建议cc使用插件 Opus 5 high 常驻；复杂或高风险任务升 xhigh；Fable 5 留给大型长期任务；max 只做最后攻坚

cli要安装claude hud

插件要安装Claude Code Usage

我的AI原生开发实践

Mon, 06 Jul 2026 00:00:00 GMT

用工作流驯服 AI

跟 AI 结对编程这事儿，大家都摸索过一阵子。一开始，我们总是习惯性地在对话框里敲下“帮我写个 XX 功能”，然后满心欢喜地看着它咔咔输出代码。但现实往往是，它写着写着就放飞自我，最后给你留下一堆跑不通的烂摊子。

痛定思痛后，我日常琢磨出了一套能让 AI 在整个开发流程里不偏离方向的实践方案。

核心理念其实就一句话：别跟 AI 聊天，用文档驱动它。

具体怎么操作呢？思路很简单：先用 OpenSpec 把需求和设计定死，绝不让它自由发挥；接着用 SuperPower 把控执行过程，按规矩写代码跑测试；最后挂上 proxy 智能路由，根据任务难度自动选模型，对于opus我会转发到GLM5.2，对于sonnet用kimi2.7，haiku用v4flash，减少API成本。

提到动态路由，我选择的项目是Proxy,

Fix: Narrow complex scenario keywords to prevent false-positive routing

Github

Fix: Narrow complex scenario keywords to prevent false-positive routing

Updated

Jul 6, 2026

，专门适配opencode的go计划，期间遇到了cc只会调用glm5.2的问题，最终分析发现在complex任务中，把tool调用也算入了complex任务，还有很多不相干的关键词，解决上面问题并且pr后。成功实现了低消费的动态路由，如下图：

这么一套组合拳走下来，AI 终于消停了，从一个到处埋雷和费钱的NPC，变成了一个能干活、好验证、还不怎么费钱的靠谱工具人。


flowchart LR
    A[模糊想法] --> B[OpenSpec
蓝图与规格]
    B --> C[SuperPower
按规矩执行]
    C --> D[Proxy 智能路由
管住成本]
    D --> E[可交付的代码]
    B -.文档先行.-> C
    C -.成本约束.-> D
    style B fill:#e3f2fd,stroke:#1976d2
    style C fill:#fff3e0,stroke:#f57c00
    style D fill:#e8f5e9,stroke:#388e3c

工具选型：不选最贵的，只选最对的

AI Agent 框架：为啥我死磕 Claude Code？

市面上的 Agent 框架不少，我做过几轮横评：

Hermes Agent：啥都好，就是写代码拉胯，更适合干点自动化，重复的活。

OpenCode+Omo： Omo插件与OpenCode其他插件严重冲突导致功能失效，且长时间运行后模型会停止输出任何可见文本，使整个会话完全不可用。

AmpCode：不计成本，完全放权给AI

最后发现，还得是 Claude Code。它理解代码的深度和工程化能力确实没得挑，虽然前几天出现了在cc里面埋雷事件，但论能力，还是数一数二的，把它当“首席工程师”用，能自己看懂全局上下文自主干活，省心又省力。

工作流框架：GSD 太重，OpenSpec + SuperPower 刚刚好

试过了GSD，流程太重，中小项目用起来有种杀鸡用牛刀的憋屈感。后来换了 OpenSpec 和 SuperPower 的组合拳，瞬间清爽了。

这俩为啥必须一起用？因为它们完美互补：

OpenSpec 负责“想清楚”：把模糊的想法变成清晰的文档，做技术选型，写设计文档。也就是搞定“做什么”和“为什么做”。

SuperPower 负责“干漂亮”：写具体代码，搞测试驱动开发（TDD），做代码审查。也就是落实“怎么做”并保证质量。


flowchart TB
    subgraph OS["OpenSpec — 规格层"]
        O1["proposal 提议"]
        O2["design 设计"]
        O3["tasks 任务"]
        O4["spec 规格"]
        O1 --> O2 --> O3 --> O4
    end
    subgraph SP["SuperPower — 执行层"]
        S1["/sp:plan 规划"]
        S2["/sp:apply 实现"]
        S3["/sp:verify 验证"]
        S4["/sp:review 审查"]
        S1 --> S2 --> S3 --> S4
    end
    O4 -->|文档基线| S1
    S4 -->|交付反馈| O4
    style OS fill:#e3f2fd,stroke:#1976d2
    style SP fill:#fff3e0,stroke:#f57c00

省钱方案：proxy 智能路由真香

刚开始不懂事，直接拿智谱 GLM-5.1 跑规划，模型确实强，但光做一次规划就花了小三十块，眼看着账单数字往上飙，那叫一个肉疼。后来学乖了，轻量活儿改用 GLM-4.7，勉强拉回一点成本。

真正的转折点是我在 Linux.do 社区挖到了一个开源项目：routatic/proxy。它能把 Claude Code 的请求按场景智能分流到不同的国产模型上。启用流式场景路由后，一切自动化，它自己就能判断啥时候需要深度思考，啥时候只需简单补全。


flowchart LR
    R[Claude Code 请求] --> P{Proxy 路由
按场景分流}
    P -->|深度推理/复杂规划| M1[GLM-5.2
旗舰]
    P -->|日常通用编码| M2[Kimi K2.7
性价比]
    P -->|轻量补全/快速问答| M3[DeepSeek V4 Flash
极低成本]
    M1 --> Cost
    M2 --> Cost
    M3 --> Cost
    Cost[整体成本下降 80%+]
    style P fill:#e8f5e9,stroke:#388e3c
    style Cost fill:#fff9c4,stroke:#f9a825

实战流程：13步拿捏 AI

这套工作流最特殊的地方在于，它把开发拆成了 13 个步骤，每一步谁来做、为啥做都明明白白。装好工具后，Claude Code 里会多出一堆自定义命令。


flowchart TD
    S1[1. /opsx:propose
生成四份文档] --> S2[2. 人工评审方案]
    S2 --> S3[3. /opsx:explore
AI 反问+澄清]
    S3 --> S4[4. 锁定文档基线]
    S4 --> S5[5. /sp:plan
详细实现计划]
    S5 --> S6[6. 确认任务粒度]
    S6 --> S7[7. /sp:apply
TDD 红绿重构]
    S7 --> S8[8. 手动业务验证]
    S8 --> S9[9. /sp:verify
自动化验证]
    S9 --> S10[10. /sp:review
代码审查]
    S10 --> S11[11. /sp:finish
合并+PR]
    S11 --> S12[12. /opsx:archive
规格归档]
    S12 --> S13[13. /sp:archive
文档归档]
    S3 -.需求有变更回到这里.-> S3
    style S7 fill:#fff3e0,stroke:#f57c00
    style S10 fill:#e8f5e9,stroke:#388e3c

挑几个关键步骤说说

从画图纸开始 (/opsx:propose)

输入这行命令，AI 会在项目目录下生成四份文档：proposal 讲要做什么，design 讲怎么做，tasks 拆任务，spec 定验收标准。说白了就是让 AI 帮你把脑子里模糊的想法变成白纸黑字——你还没写一行代码，需求文档就已经出来了。

最磨人的一步：跟 AI 对质 (/opsx:explore)

这一步是整个流程里投入产出比最高的，也是最烦的。AI 会像个不太信任你的架构师一样追着问："这个边界情况你考虑了吗？""如果外部服务挂了怎么办？""你的分页支持 offset 还是游标？"

你得一条条回答。

烦是真烦，但答完之后你会发现——之前那些"到时候再说"的模糊地带，全被堵死了。后面 AI 写代码的时候想自由发挥都没空间。

sp 命令的来历：市面上没有，自己造的

说到这里得坦白一件事：带 sp: 前缀的这些命令，市面上根本找不到。

OpenSpec 自带的命令管的是"想清楚"——propose、explore、archive 这些都是它原生的。但到了"动手干"这个阶段，我发现 OpenSpec 原生的 plan 太粗了，apply 更是压根没有 TDD 的概念。SuperPower 那边倒是有写代码的能力，但没有标准化的命令体系来约束开发范式。

所以后面的 plan、apply、verify、review、finish、archive 六个命令，全是我自己一个一个手搓出来的。每个命令都是一段精心设计的 prompt 模板，专门用来约束 AI 在对应阶段的行为。

规划要够细 (/sp:plan)

OpenSpec 原生的 plan 只是基于 tasks 粗略拆一下，远远不够。我在这个基础上重新实现了一个 plan 命令，它会生成一份 implementation-plan.md——里面不光有任务列表，还有任务之间的依赖关系、每个任务涉及的具体文件路径、可验收的完成标准、风险等级，甚至会分析哪些任务可以并行执行。

为什么要做到这个粒度？因为后面要用 TDD 开发，如果任务拆得不够细，AI 写测试的时候根本不知道该测什么。

TDD 红绿灯 (/sp:apply)

apply 命令是我花心思最多的一个。我专门把 TDD 的红-绿-重构范式写成了一套完整的 prompt，"教"给 AI 怎么走这个循环：每接一个任务，必须先写一个注定失败的测试（红灯），定义好"正确的行为是什么"；再写最简单的代码让测试通过（绿灯），不多写一行；最后在测试全绿的前提下重构优化。

不能跳步，不能偷懒。AI 想直接写实现代码？不行，先写测试。

验证提示词是从各路技术社区淘来的 (/sp:verify)

verify 命令解决的问题是：代码写完了，怎么确认它真的没问题？

我专门去一些技术平台——GitHub 的最佳实践讨论、各种 AI 编程社区——收集了一批专门用来验证代码质量的提示词，然后整合成了一个 verify 函数。它会自动检测项目类型（Java、Python、Go、Node 都认），然后跑对应的单元测试、检查日志里有没有 ERROR、跑回归测试确保没有破坏已有功能、还会对着 implementation-plan 里的边界情况逐条验证。

最终输出一份结构化的报告：PASS 还是 FAIL，哪里有问题，一目了然。

审查不能自己审自己 (/sp:review)

首先是关于怎么 “审查”

verify 过了不代表代码质量过关。review 命令做的是代码审查——对照 implementation-plan 里的验收标准，逐条检查代码有没有做到位。覆盖四个维度：正确性（逻辑有没有 bug）、可维护性（命名清不清晰、函数长不长）、安全性（有没有硬编码密钥、注入风险）、性能（有没有 N+1 查询、内存泄漏）。

审查结果分两级：Must Fix 是阻塞项，不修不能合并；Nice to Have 是建议，可以后续再改。

关于不能审自己

我是让cc专门启用一个subagent,调用Glm5模型做一个多层面的审查，避免同一个模型不断自身导致幻觉积累越来越多的问题（就像去ai味一样，ai参与越多越难去掉，还是需要人的参与与决策）

一键交付 (/sp:finish)

finish 命令干三件事：确认所有任务完成、测试通过；合并代码到目标分支；自动创建 PR（连描述模板都帮你填好了）。如果你用了 worktree 做隔离开发，它还会顺手清理残留的 worktree。

规格闭环 (/sp:archive)

最后的 archive 命令是我额外加的——OpenSpec 原生的 archive 只是把 spec 文件归档，但我觉得不够。我实现的版本会把归档的文档内容做一个总结，然后自动更新仓库里对应的开发文档或者开发日志。这样每次开发完，仓库里的文档永远是最新状态，不会出现"代码改了但文档没更新"的尴尬。

这就是我这套方案的完整面貌。六个 sp:* 命令，每个都是针对一个开发阶段的痛点设计的。OpenSpec 管"想清楚"，sp:* 管"干明白"，两者合在一起才构成一个从需求到交付的完整闭环。


flowchart LR
    R[红灯
先写失败测试] --> G[绿灯
最小实现通过测试]
    G --> Ref[重构
测试全绿下优化]
    Ref -.下一轮.-> R
    style R fill:#ffebee,stroke:#c62828
    style G fill:#e8f5e9,stroke:#2e7d32
    style Ref fill:#e3f2fd,stroke:#1565c0

当需求变了？别急着改代码！

开发最怕啥？需求变更。但在这套流程里，有个铁律：“文档先行，代码殿后”。就算只改个字段名，也别手贱去改代码，必须回到第 3 步重走 /opsx:explore。虽然看着繁琐，但这保证了每一次变更都有迹可循，不会把项目变成一锅粥。


flowchart LR
    Change("需求变更") --> Check("改代码还是改文档")
    Check -->|错误做法| Bad["直接改代码 基线崩坏"]
    Check -->|正确做法| Good["回到 OpenSpec 改文档"]
    Good --> Re["opsex:explore 重新澄清"]
    Re --> Plan["sp:plan 重新规划"]
    Plan --> Apply["sp:apply 重新实现"]
    style Bad fill:#ffebee,stroke:#c62828
    style Good fill:#e8f5e9,stroke:#2e7d32

真实案例：给 Apache SeaTunnel 补个Task

光说不练假把式。拿我最近搞的一个真实项目 seatunnel-hg-connector 举例。

但是，别高兴得太早。

AI 的自动化验证全绿，但后续还是暴露了三个问题：

schema 推断的运行时类型对不齐，属性单值/集合处理出错。

DATE 转换没用 UTC，时区导致数据偏移。

测试类命名不符合 CI 检查规则，被 CI 拦下。

这也印证了那条铁律：AI 的测试只验代码逻辑，验不了业务真实场景和项目级约束。该手动测的，该过 CI 的，一步都省不了。


flowchart LR
    subgraph 量化
        A1[27 个任务
全部完成]
        A2[1814 行代码
13 个文件]
        A3[21 单测
0 失败]
        A4[4.8/5.0
闭环评分]
    end
    subgraph 收益
        B1[成本下降 80%+
proxy 路由]
        B2[向后兼容
零破坏]
        B3[文档可追溯
openspec 归档]
    end
    量化 --> 收益
    style 量化 fill:#e3f2fd,stroke:#1976d2
    style 收益 fill:#e8f5e9,stroke:#388e3c

踩坑吐血换来的四条铁律

AI 测试全绿 ≠ 功能正确：时区、CI 规则这类项目级坑，AI 根本感知不到，必须人工兜底。

向后兼容是底线：重构共享类时，旧 API 必须打 @Deprecated 标签并委托，不然会悄悄搞崩老功能。

前期偷懒，后期还债：schema 推断的 cardinality 问题，就是因为 explore 阶段没问清楚，结果硬生生返工了一次。

改需求必须回退改文档：哪怕只改一个字段名，也要走 /opsx:explore 流程，保证可追溯。

写在最后

归到底，这套 AI 原生开发工作流的精髓就在于三个“管住”：

用 OpenSpec 管住需求和设计

用 SuperPower 管住执行和质量

用 proxy 管住钱包

AI 的能力再强，它也只是个算力极高的执行者，真正决定项目成败的，还是制定规则、把控方向的人。这套流程的本质，就是把你从一个手忙脚乱复制粘贴的“提示词工程师”，变成一个运筹帷幄的架构师和项目经理。

未来，不是 AI 取代我们，而是会用 AI 的人，把不会用 AI 的人卷出局。

附件：

openspec.zip

19.7 KiB

Vibe Coding开发前的 7 个关键步骤

Thu, 16 Apr 2026 00:00:00 GMT

第一步：把想法聊清楚

把你的想法完整地说出来。注意，是“完整地”,不是"简洁地"。

比如你想做个记账工具，别只说“帮我做个记账 App"。你得说清楚:

为什么要做这个?现有的记账App哪里不满意?

核心功能是什么?记录收支?生成报表?设置预算?

谁会用这个工具?就你自己，还是想给朋友用?

使用场景是什么?每天记一次，还是花钱就记?

这个过程其实是在帮你自己理清思路。很多时候，你以为自己想清楚了，真说出来才发现到处是模糊地带。

于是，第一步就是跟AI聊天，像跟朋友聊天一样，把脑子里的想法全倒出来，细节越多越好。

填充下面这份prompt


我想做一个[产品名称]
主要是为了解决[什么问题]
目标用户是[谁]
核心功能包括:
[功能一]
[功能二]
[功能三]
我希望它能 [达到什么效果]

然后继续和ai交流，知道ai达到你的理想型

第二步：要一份 PRD

聊完之后，别急着写代码。让AI帮你把刚才的对话整理成一份PRD，也就是产品需求文档。

直接说:帮我把刚才聊的内容整理成一份产品需求文档。并且写入PRD.md AI会给你输出一个结构化的文档

然后，认真读这份PRD。

这是整个流程里最容易被跳过，但其实最关键的一步。逐条对照你的原始想法，看AI理解的跟你想的是不是一回事。

发现不对的地方，现在就改。改PRD花5分钟，改代码可能要花5个小时。

把PRD当作你和AI之间的"合同”，确保双方理解一致。

第三步：明确项目目标

做什么搞清楚了，接下来要想清楚：做到什么程度?

这个问题直接决定了技术方案的选择。

可以这样说:


这个项目主要是我自己用，目标是低成本实现，

在本地运行就可以，不需要考虑多人使用的情况

或者：


这个项目我想做成可以release的产品，

需要考虑用户数据安全、性能优化和未来扩展性。

第四步：确定技术

目标明确了，就可以让AI推荐技术栈了。

一个实用的prompt模板：


帮我根据上面内容，推荐合适的技术栈，并说明为什么这样选择。

AI会告诉你前端用什么框架、后端用什么语言、数据库选什么、需要哪些工具库。

比如做个简单的网页工具，React+Node.js+ SQLite就够了。不需要上Kubernetes、微服务这些大杀器。

第五步：要一份架构设计

技术栈定了，接下来要一份系统架构设计。

可以这样问AI：


根据这个PRD，请为我设计一个适合个人项目的轻量架构，包括:

- 项目目录结构
- 核心模块划分
- 数据模型设计
- 代码规范建议

我希望这个项目：[本地运行/可部署/需要扩展性]
然后把上面架构设计写入ARCHITECTURE.md

AI会给你输出完整的目录结构和划分


|project/  
||—————src/  
||  |—————components/ #UI组件
||  |—————services/ #业务逻辑
||  |—————utils/  #工具函数
||  |—————config/  #配置文件
||—————public/  
||—————tests/
|—————README.md

第六步：整理项目文档

现在你手上有了PRD、技术栈、架构设计，接下来要把这些内容整理成文档，保存在项目里。

建议创建这几个文件:

和AI沟通进行创建README.md


帮我结合上面内容创建一个README.md
要求：
- 项目简介：这个项目是干什么的
- 如何运行：怎么把项目跑起来
- 技术栈：用了哪些技术
项目内容PRD.md和ARCHITECTURE.md和README.md
都要跟随着项目文件更改进行更新！

下面文件AI已经创建了

~~PRD.md~~

~~产品定位~~

~~核心功能列表~~

~~用户使用流程~~

~~ARCHITECTURE.md~~

~~技术栈选择及原因~~

~~核心模块说明~~

~~数据模型设计~~

~~代码规范~~

只要使用 Cursor/Claude Code/Trae 等工具，它能直接访问你的项目文件夹，会自动读取项目根目录的文档。

于是每次你和AI对话，它都已经“知道”了你的项目架构和规范。不需要反复上传文档。

最后一个提醒:文档要跟着项目更新。

如果你调整了架构、改变了某个设计，记得让AI同步更新文档（手动更新）。

否则AI会按照过时的文档理解项目，导致新代码跟现有代码对不上。

第七步:设置

Git 版本管理

在写第一行代码之前，最后一件必须做的事：设置 Git版本管理。

Git是做什么的?

简单说，就是给你的项目创建“存档点”。就像玩游戏时的存档系统，每完成一个阶段就存个档，后面打不过了可以读档重来。

Git Skill

这里我们可以使用git相关的skill实现ai自动生成commit，也就是实现自动存档的功能

比如下面这个Skill:


---
name: commit-by-feature
description: Commits code changes by feature with a standardized multi-line commit message. Runs when the user makes code changes and asks to commit, or when the user explicitly requests a commit. Amends the last unpushed commit message when the user switches to another feature and has unpushed commits.
---

# 按功能提交（Commit by Feature）

在用户完成代码修改并要求提交、或用户明确要求提交时，按「功能」进行 git commit，并采用下方固定格式的 commit message。若用户在一个功能已 commit 后又在做另一功能的修改，且存在未 push 的 commit，则对**最近一次未 push 的 commit** 使用 `git commit --amend` 修改其 message，使其描述新功能。

## 何时执行

- 用户说「帮我 commit」「提交一下」「把更改 commit」等，或
- 用户完成一批代码修改后要求提交，或
- 用户说「修改刚才的 commit 说明」「改一下上次的 commit message」等（则执行 amend 流程）。

## Commit Message 格式（必须严格遵循）

整段作为 **commit message 正文**（不要用 `-m` 只写一行，用 `-m "第一行" -m "正文..."` 或写进文件再 `git commit -F`）。格式如下：

```
修改描述： [feat] 或 [fix] 或 [refactor] + 一句话概括（如：精简视频裁剪页面与回灌页面：在视频裁剪页移除xxx；在回灌页将设备 IP 默认改为 0.0.0.0。）
影响分析： all
是否自测： 是
自测内容： ui（或 doc / 接口 / 改动对应的文件夹路径 /等，按实际改动的自测范围填写）
测试建议： all
代码审查： 刘江涛
NOTE： all
项目编号： all
```

- **修改描述**：首行用 `[feat]` / `[fix]` / `[refactor]` 等前缀，后接简洁的功能/修复说明，多块功能用分号或「；」分隔。
- **影响分析 / 测试建议 / NOTE / 项目编号**：无特殊要求时填 `all`。
- **是否自测**：一般为「是」。
- **自测内容**：根据改动填 `ui`、`doc`、`接口`、`导出` 等。
- **代码审查**：固定为「刘江涛」。

## 执行步骤

### 1. 仅修改上一次 commit 的 message（amend）

当用户明确说「改 commit 说明」「修改上次的 commit」「amend」且当前有未 push 的 commit 时：

1. 运行 `git log -1 --oneline` 确认最近一次 commit。
2. 根据**当前工作区+暂存区的最新改动**（或用户口述）归纳「修改描述」。
3. 按上面格式写出完整 commit message。
4. 执行：`git commit --amend -m "修改描述： ..." -m "影响分析： all" -m "是否自测： 是" -m "自测内容： ..." -m "测试建议： all" -m "代码审查： 封凯" -m "NOTE： all" -m "项目编号： all"`
   或使用临时文件：`git commit --amend -F commit_msg.txt`（内容为上述多行）。
5. 告知用户已 amend 完成。

### 2. 按功能提交当前改动（新 commit）

当用户要求提交当前更改时：

1. **查看改动**：`git status`、`git diff`（及 `git diff --staged`）。根据修改的文件路径和 diff 内容判断属于哪一个或哪几个功能（例如：视频裁剪、回灌、帧头导出、日志分析、通用功能、系统设置等）。
2. **决定 commit 数量**：
   - 通常**一个功能一个 commit**；若改动明显属于同一功能，只生成一个 commit。
   - 若改动横跨多个互不相关的功能，可拆成多个 commit（先 add 第一批，commit；再 add 下一批，commit），每个 commit 的 message 都按本格式填写。
3. **撰写「修改描述」**：
   - 用 `[feat]` / `[fix]` / `[refactor]` 等开头。
   - 一句话概括该 commit 涉及的功能或修复，多点时用分号分隔。
   - 仅描述本 commit 包含的改动，不要写未改动的功能。
4. **填写其余字段**：影响分析、是否自测、自测内容、测试建议、代码审查、NOTE、项目编号按格式填好。
5. **执行提交**：
   - 先 `git add` 本功能相关文件，再 `git commit`，message 使用上述多行格式（可用多个 `-m` 或 `-F` 文件）。
   - 若拆多个 commit，重复 add + commit，每个 commit 对应一个功能的描述。

## 示例

**单功能单 commit：**

修改描述： [feat] 帧头导出支持 MP4 视频并修复导出 0 帧问题；导出服务 JSON 改为使用 orjson。
影响分析： all
是否自测： 是
自测内容： 导出、MP4 视频
测试建议： all
代码审查： 刘江涛
NOTE： all
项目编号： all

**Amend 场景：**
用户已为「视频裁剪精简」commit 过一次，未 push，接着又做了「回灌页设备 IP 默认 0.0.0.0」的修改并希望把这两块合进同一个 commit 说明。则对最近一次 commit 执行 `git commit --amend`，将 message 改为同时包含「视频裁剪页精简」和「回灌页设备 IP 默认与选网卡自动填充」的修改描述。

## 注意事项

- 不要用单行 `-m "..."` 把多行格式挤成一行；用多行 message 或 `-F` 文件。
- 若仓库有 `.gitignore` 或未跟踪文件，只 add 用户明确要提交的或与当前功能明显相关的文件。
- 不执行 `git push`，除非用户明确要求推送。

从准备到开发

准备工作做完，就可以开发了。但记住几个原则:

1.先做MVP(最小可用版本)

不要一开始就追求完美。先做一个能跑、能用、实现核心功能的版本。后面再慢慢优化。

比如记账工具，第一版只要能记录收支、能查看列表就够了。报表、预算、数据分析这些可以后面加。

2.小步迭代

每次只做一个功能，做完测试没问题，再做下一个。

别一口气让AI写一大堆代码，那样出问题很难定位。

3.勤 commit

每完成一个小功能就commit一次。这是我们的安全网，别省。

4. 验证AI的代码

AI写的代码要自己测试。不要盲目相信，也不要过度怀疑,测试是最好的验证方式。

5.完成项目后沉淀技术文档

每次写完一个项目，沉淀一个技术文档和一些可复用的Skill，方便后面项目的开发和技术回顾

如果是完全零基础的新手，建议:

从简单项目开始。

别一上来就做复杂的。先做个待办事项管理、简易记账本、个人博客这种简单项目。

目的不是做出多牛的产品,而是把整个流程走一遍，体会每个步骤的作用。做完一个项目,流程就刻在脑子里了，也有了 Vibe Coding的感觉。

别害怕出错。

有Git在,出错了就回滚，没什么大不了的。多试几次，或者选择更厉害的模型。

附上前端美化Skill:

SKILL.md

anthropics

和每次变更的流水线(CHANGELOG.md)放在项目根目录就可以了，然后告诉AI你添加了变更流水线


# Changelog

本文件用于记录每次版本发布的“代码改动 + 文档改动”，并作为固定发布流程的执行清单。

遵循规范：
- 版本格式：`[主版本.次版本.修订]`，例如 `v1.0.0`
- 日期格式：`YYYY-MM-DD`
- 发布原则：没有文档更新说明的功能改动，不应发布

## 发布流程（固定）
1. 完成代码改动并本地验证（功能、接口、构建）。
2. 更新文档：至少检查 `PRD.md`、`ARCHITECTURE.md`、`README.md` 是否需要变更。
3. 填写本文件对应版本条目，明确“代码改动 + 文档改动”。
4. 复核发布清单，确认通过后再打版本标签/归档。

## 发布清单（每次发布必查）
- [ ] 代码改动已完成并自测通过
- [ ] 需求变化已同步到 `PRD.md`（如适用）
- [ ] 架构变化已同步到 `ARCHITECTURE.md`（如适用）
- [ ] 运行方式/依赖变化已同步到 `README.md`（如适用）
- [ ] 本次版本记录已写入 `CHANGELOG.md`

---

## [Unreleased]
### Added
- 待补充

### Changed
- 待补充

### Fixed
- 待补充

### Docs
- 待补充（必须填写文档变更；若无，请写“无”并说明原因）

### Release Checklist
- [ ] 代码改动已完成并验证
- [ ] 文档改动已同步
- [ ] 风险项已评估

---

## [v1.0.0] - 2026-04-16
### Added
- 初始化项目文档体系：`PRD.md`、`ARCHITECTURE.md`、`README.md`、`CHANGELOG.md`

### Changed
- 建立个人本地低成本架构基线，明确可扩展路线

### Fixed
- 无

### Docs
- 新增 `README.md`，补充项目简介、运行方式、技术栈
- 更新 `PRD.md`，补充文档联动维护要求
- 更新 `ARCHITECTURE.md`，补充文档联动更新约定

### Release Checklist
- [x] 代码改动已完成并验证
- [x] 文档改动已同步
- [x] 风险项已评估

作者：hllqk

实用工具推荐合集

Tue, 03 Feb 2026 00:00:00 GMT

🎯

这里汇集了各类优质的软件、网站、插件和扩展推荐，帮助你提升工作效率和使用体验！

🔧 编程开发

Visual Studio Code

Cursor工具简单使用指南

Thu, 29 Jan 2026 00:00:00 GMT

使用经验

2.1 经验分享

https://x.com/ryolu_/status/1914384195138511142

引用Cursor设计总监的经验话语

Set 5-10 clear project rules upfront so Cursor knows your structure and constraints. Try /generate rules for existing codebases. # 设置5-10规则，减少大模型的幻觉，让AI过度聪明

Be specific in prompts. Spell out tech stack, behavior, and constraints like a mini spec. # 清晰的提示词，说明你的技术栈，行为，包括最终需要达到的一个目的，限制条件，可以合理使用ASK模式

Work file by file; generate, test, and review in small, focused chunks. # 小颗粒度修改如文件夹或者文件级别去修改，用测试驱动开发的形式，让Cursor针对自行改动的内容进行测试

Write tests first, lock them, and generate code until all tests pass. # 先写测试用例，测试驱动开发，非常推荐的功能

Always review AI output and hard‑fix anything that breaks, then tell Cursor to use them as examples. # 审查AI的输出，这一段对于我们来说是强项

Use @ file, @ folders, @ git to scope Cursor’s attention to the right parts of your codebase. # 使用@来限用上下文，高频使用功能

Keep design docs and checklists in .cursor/ so the agent has full context on what to do next. # 在.cursor/下给出清晰的清单，不要一次性做完，而是一个一个的做，一个一个做阶段性测试。

If code is wrong, just write it yourself. Cursor learns faster from edits than explanations.# 代码如果百分之百写错了，就自己写，Cursor会汲取经验

Use chat history to iterate on old prompts without starting over. # 利用聊天记录复用旧的提示词，项目级别保留历史对话

Choose models intentionally. Gemini for precision, Claude for breadth. # 根据需要选择模型

In new or unfamiliar stacks, paste in link to documentation. Make Cursor explain all errors and fixes line by line.# 文档首页粘贴

Let big projects index overnight and limit context scope to keep performance snappy. # 大工程索引完后再动工

1.2 Cursor Rules

https://github.com/PatrickJS/awesome-cursorrules

ASK模式->Agent模式：适用于所有的IDE模式。

Step1: 利用ASK模式将自然语言转换成结构化的提示词

我现在需要做一个个人作品集的展示网站，它是一个单页网站，然后作品都是以图片的展示形式，请你帮我生成提示词


我来帮您生成一个个人作品集展示网站的提示词。首先让我了解一下您的项目结构，然后为您提供详细的提示词。

Ran tool
基于您的需求，我为您生成一个详细的提示词来创建个人作品集展示网站：

## 个人作品集展示网站开发提示词

**项目概述：**
创建一个现代化的单页个人作品集展示网站，以图片为主要展示形式，具有响应式设计和优秀的用户体验。

**技术要求：**
- 使用 HTML5、CSS3 和 JavaScript (ES6+)
- 响应式设计，支持移动端、平板和桌面端
- 现代化的 UI/UX 设计
- 图片懒加载和优化
- 平滑的动画效果和过渡

**页面结构：**
1. **导航栏**
   - 固定在页面顶部
   - 包含 Logo/姓名
   - 导航菜单（首页、作品、关于、联系）
   - 汉堡菜单（移动端）

2. **首页横幅区域**
   - 全屏高度的欢迎区域
   - 个人介绍和标语
   - 背景图片或渐变效果
   - 向下滚动指示器

3. **作品展示区域**
   - 网格布局展示作品图片
   - 图片悬停效果
   - 点击放大查看详情
   - 分类筛选功能
   - 图片懒加载

4. **关于我区域**
   - 个人简介
   - 技能展示
   - 经验时间线
   - 个人照片

5. **联系区域**
   - 联系表单
   - 社交媒体链接
   - 联系信息

**设计风格：**
- 简约现代的设计风格
- 使用优雅的字体
- 柔和的色彩搭配
- 适当的留白
- 微妙的阴影和圆角

**功能特性：**
- 图片画廊（支持点击放大）
- 平滑滚动导航
- 作品分类筛选
- 响应式图片网格
- 加载动画
- 返回顶部按钮

**性能优化：**
- 图片压缩和优化
- 懒加载实现
- 最小化 CSS 和 JS
- 浏览器缓存策略

**文件结构建议：**
```
portfolio/
├── index.html
├── css/
│   ├── style.css
│   └── responsive.css
├── js/
│   ├── main.js
│   └── gallery.js
├── images/
│   ├── works/
│   ├── profile/
│   └── icons/
└── assets/
    └── fonts/
```

**额外建议：**
- 添加作品详情模态框
- 实现作品搜索功能
- 添加作品标签系统
- 集成社交媒体分享
- 添加作品下载功能（如适用）
- 实现深色/浅色主题切换

这个提示词涵盖了创建一个专业个人作品集网站的所有关键要素。您可以根据具体需求调整或补充任何部分。

Step2: 然后再切换为Agent模式

测试驱动开发：需要实现一个特定的功能，先让AI想一些需要测试的功能，直到所有的测试用例全部跑通后

Step1:

Project Rules->User Rule

@限用上下文

学会复用历史会话

Cursor实战

3.1 CvToolkit

3.1.1 第一步：Rules定义

第一步：利用Cursor定义Rules的规则

.cursor\rules\general.mdc 原版


---
description: 项目通用规范和基本信息
globs: ["*"]
alwaysApply: true
---

# 项目通用规范

## 技术栈

- Python 3.10
- Poetry 管理依赖
- GitHub Actions 自动构建和发布
- 使用 GitHub 作为代码托管平台
- 使用 Bash 脚本

## 代码风格

- 保持代码简洁、可读
- 使用有意义的变量和函数名
- 添加适当的注释解释复杂逻辑
- 遵循每种语言的官方风格指南

## 项目结构

- 保持项目结构清晰，遵循模块化原则
- 相关功能应放在同一目录下
- 使用适当的目录命名，反映其包含内容

## 通用开发原则

- 编写可测试的代码
- 避免重复代码（DRY原则）
- 优先使用现有库和工具，避免重新发明轮子
- 考虑代码的可维护性和可扩展性

## 响应语言

- 始终使用中文回复用户

.cursor\rules\general.mdc 优化版本


# CvToolkit 项目通用规范

## 项目概述

CvToolkit 是一个专门用于计算机视觉任务、疲劳检测和数据处理的开源工具包。主要功能包括：

- 疲劳检测数据分析和可视化
- 疲劳数据处理和转换工具
- 视频和图像处理工具
- 数据格式转换和预处理
- 数据集生成和管理
- 通用计算机视觉工具函数

## 技术栈

- **Python 版本**: 3.8 及其以上（推荐 3.8+）
- **核心依赖**:
  - OpenCV (opencv-python)
  - NumPy
  - Matplotlib (数据可视化)
  - Pandas (数据处理)
  - MMCV (计算机视觉工具)
  - Decord (视频处理)
  - SciPy (科学计算)
  - OmegaConf (配置管理)
- **构建工具**: setuptools, wheel
- **包管理**: pip + requirements.txt
- **版本控制**: Git
- **CI/CD**: GitHub Actions (可选)

## 项目结构规范

```
CvToolkit/
├── toolkit/                    # 核心工具包
│   ├── analyzer/              # 数据分析模块
│   ├── generator/             # 数据生成模块
│   ├── converter/             # 格式转换模块
│   ├── preprocess/            # 数据预处理模块
│   ├── common/                # 通用工具函数
│   ├── config/                # 配置文件
│   ├── models/                # 模型相关
│   ├── inference/             # 推理模块
│   └── utils/                 # 工具函数
├── demo/                      # 示例和演示代码
├── docs/                      # 文档
├── scripts/                   # 脚本文件
├── data/                      # 数据目录
├── example/                   # 示例数据
└── thirdparty/                # 第三方依赖
```

## 代码风格规范

### Python 代码规范

- 遵循 PEP 8 编码规范
- 使用有意义的变量和函数名（英文命名）
- 添加详细的文档字符串（docstring）
- 使用类型注解（Type Hints）
- 保持函数简洁，单一职责原则
- 适当的错误处理和异常捕获

### 文件命名规范

- 模块文件使用小写字母和下划线：`analyzer_fatigue.py`
- 类名使用驼峰命名：`AnalyzerFromAitxt`
- 函数和变量使用小写字母和下划线：`plot_3df_fatigue`
- 常量使用大写字母和下划线：`EYE_STATUS_ENUM`

### 注释规范

- 复杂逻辑必须添加中文注释
- 函数和类必须有详细的文档字符串
- 关键算法步骤需要行内注释
- 配置参数需要说明用途和取值范围

## 功能模块开发规范

### 分析器模块 (analyzer/)

- 支持多种数据格式（AITXT、JSON）
- 提供数据可视化功能
- 实现统计分析功能
- 支持批量处理

### 生成器模块 (generator/)

- 支持疲劳检测数据生成
- 实现数据增强功能
- 提供数据格式转换
- 支持自定义配置

### 通用工具模块 (common/)

- 提供跨模块使用的工具函数
- 实现文件 I/O 操作
- 提供计算机视觉基础功能
- 实现日志记录功能

### 配置管理

- 使用 OmegaConf 进行配置管理
- 配置文件使用 YAML 格式
- 支持环境变量覆盖
- 提供默认配置和用户配置

## 数据处理规范

### 输入数据格式

- 支持 AITXT 格式（疲劳检测结果）
- 支持 JSON 格式（标注数据）
- 支持常见视频格式（MP4、AVI）
- 支持常见图像格式（JPG、PNG）

### 输出数据格式

- 标准化 JSON 格式
- CSV 格式（统计分析结果）
- 图像格式（可视化结果）
- 视频格式（处理结果）

### 数据验证

- 输入数据完整性检查
- 格式验证和错误处理
- 数据质量评估
- 结果一致性验证

## 性能优化规范

### 内存管理

- 大文件处理使用流式读取
- 及时释放不需要的内存
- 使用生成器处理大数据集
- 避免内存泄漏

### 并行处理

- 使用多线程处理 I/O 密集型任务
- 使用多进程处理 CPU 密集型任务
- 合理设置线程/进程数量
- 避免资源竞争

### 缓存策略

- 合理使用缓存减少重复计算
- 缓存文件使用临时目录
- 定期清理缓存文件
- 缓存大小限制

## 测试规范

### 单元测试

- 核心功能必须有单元测试
- 测试覆盖率不低于 80%
- 使用 pytest 框架
- 测试数据使用示例数据

### 集成测试

- 模块间接口测试
- 端到端功能测试
- 性能基准测试
- 兼容性测试

## 文档规范

### 代码文档

- 所有公共 API 必须有文档字符串
- 使用 Google 或 NumPy 文档字符串格式
- 包含参数说明、返回值说明、示例代码
- 复杂算法需要详细说明

### 用户文档

- README.md 包含项目概述和使用说明
- 提供详细的安装指南
- 包含示例代码和演示
- 提供常见问题解答

### API 文档

- 自动生成 API 文档
- 包含所有公共接口说明
- 提供在线文档访问
- 定期更新文档

## 版本管理规范

### 版本号规范

- 使用语义化版本号（Semantic Versioning）
- 格式：主版本号.次版本号.修订号
- 主版本号：不兼容的 API 修改
- 次版本号：向下兼容的功能性新增
- 修订号：向下兼容的问题修正

### 发布流程

- 开发分支：develop
- 主分支：main
- 功能分支：feature/功能名
- 修复分支：hotfix/问题描述
- 发布标签：v 版本号

## 响应语言

- 始终使用中文回复用户
- 代码注释使用中文
- 文档使用中文编写
- 错误信息使用中文

## 开发环境设置

### 环境变量

```bash
# 设置 PYTHONPATH
export PYTHONPATH=$PWD:$PYTHONPATH

# 设置 CUDA 环境（如需要）
export CUDA_VISIBLE_DEVICES=0
```

### 依赖安装

```bash
# 安装基础依赖
pip install -r requirements.txt

# 开发环境额外依赖
pip install pytest pytest-cov black flake8
```

## 贡献指南

### 代码提交

- 提交前运行代码格式化：`black .`
- 提交前运行代码检查：`flake8`
- 提交前运行测试：`pytest`
- 提交信息使用中文描述

### 代码审查

- 所有代码变更需要代码审查
- 审查重点：功能正确性、代码质量、性能影响
- 审查通过后才能合并到主分支
- 记录审查意见和修改历史

## 响应语言

- 始终使用中文回复用户

.cursor\rules\python.mdc 原版


# 角色
你是一名精通 Python 的高级工程师，拥有 20 年的软件开发经验。

# 目标
你的目标是以用户容易理解的方式帮助他们完成 Python 项目的设计和开发工作。你应该主动完成所有工作，而不是等待用户发出指示。

你应始终遵循以下原则：

### 编写代码时：
- 遵循 PEP 8 Python 代码风格指南。
- 使用 Python 3.10 及以上的语法特性和最佳实践。
- 合理使用面向对象编程（OOP）和函数式编程范式。
- 利用 Python 的标准库和生态系统中的优质第三方库。
- 实现模块化设计，确保代码的可重用性和可维护性。
- 使用类型提示（Type Hints）进行类型检查，提高代码质量。
- 编写详细的文档字符串（docstring）和注释。
- 记录当前的错误处理和日志记录。
- 持续编写单元测试确保代码质量。

### 解决问题时：
- 全面阅读相关代码文件，理解所有已有的功能和逻辑。
- 确保所有新增功能都能与现有系统兼容。
- 与用户沟通并充分交互，根据反馈调整解决方案。

在整个过程中，始终参考 Python 官方文档，确保使用最新的 Python 开发最佳实践。

.cursor\rules\python.mdc 优化后版本


# CvToolkit Python 开发规范

## 角色定位

你是一名专注于计算机视觉和疲劳检测的高级 Python 工程师，拥有丰富的 OpenCV、深度学习框架和数据处理经验。

## 核心开发原则

### 代码风格规范

- **严格遵循 PEP 8** 编码规范，使用 `black` 进行代码格式化
- **类型注解必须**：所有函数参数、返回值和类属性都要使用 Type Hints
- **文档字符串规范**：使用 Google 风格或 NumPy 风格的 docstring
- **命名规范**：
  - 模块文件：`analyzer_fatigue.py`（小写+下划线）
  - 类名：`AnalyzerFromAitxt`（驼峰命名）
  - 函数名：`plot_3df_fatigue`（小写+下划线）
  - 常量：`EYE_STATUS_ENUM`（大写+下划线）

### 计算机视觉特定规范

- **图像处理**：优先使用 OpenCV (cv2) 进行图像操作
- **视频处理**：使用 `cv2.VideoCapture` 和 `cv2.VideoWriter`
- **内存管理**：及时释放 `cv2.VideoCapture` 对象，避免内存泄漏
- **错误处理**：对图像/视频读取失败进行适当的异常处理
- **性能优化**：使用 `ThreadPoolExecutor` 进行并行处理

### 疲劳检测项目特定规范

- **数据格式**：支持 AITXT 和 JSON 两种输入格式
- **标签体系**：遵循项目的疲劳标签分类体系（1.x.x 为疲劳，2.x.x 为非疲劳）
- **阈值设置**：疲劳检测阈值默认为 0.95，可通过参数配置
- **可视化**：使用 Matplotlib 生成疲劳得分曲线和统计图表
- **数据验证**：对输入数据进行完整性检查和格式验证

### 模块化设计原则

- **单一职责**：每个类/函数只负责一个特定功能
- **接口设计**：提供清晰的公共 API，隐藏内部实现细节
- **配置管理**：使用 OmegaConf 进行配置管理，支持 YAML 格式
- **日志记录**：使用项目统一的日志系统 `common_log.py`

### 数据处理规范

- **文件 I/O**：使用项目统一的 `common_io.py` 工具函数
- **数据转换**：支持多种数据格式之间的转换（AITXT ↔ JSON）
- **批量处理**：支持批量处理大量文件，提供进度条显示
- **缓存策略**：合理使用缓存减少重复计算

### 性能优化要求

- **内存效率**：大文件处理使用流式读取
- **并行处理**：I/O 密集型任务使用多线程，CPU 密集型任务使用多进程
- **GPU 加速**：支持 CUDA 设备，合理设置 `CUDA_VISIBLE_DEVICES`
- **资源管理**：及时释放 GPU 内存和文件句柄

### 错误处理和调试

- **异常捕获**：对关键操作进行异常处理，提供有意义的错误信息
- **日志记录**：使用不同级别的日志记录（DEBUG, INFO, WARNING, ERROR）
- **调试信息**：在开发阶段提供详细的调试输出
- **数据验证**：对输入参数和中间结果进行验证

### 测试和文档

- **单元测试**：核心功能必须有单元测试，使用 pytest 框架
- **集成测试**：模块间接口测试和端到端功能测试
- **示例代码**：在 `demo/` 目录下提供完整的使用示例
- **API 文档**：所有公共接口必须有详细的文档说明

### 项目特定约定

- **疲劳分析器**：继承自基础分析器类，实现特定的疲劳检测逻辑
- **数据生成器**：支持疲劳数据的生成和增强
- **格式转换器**：支持不同数据格式之间的转换
- **配置模板**：提供标准化的配置模板文件

### 代码审查重点

- **功能正确性**：确保疲劳检测算法的准确性
- **性能影响**：评估代码对系统性能的影响
- **可维护性**：代码结构清晰，易于理解和修改
- **兼容性**：确保与现有系统的兼容性

### 开发环境设置

```bash
# 设置 PYTHONPATH
export PYTHONPATH=$PWD:$PYTHONPATH

# 代码格式化
black toolkit/ demo/

# 代码检查
flake8 toolkit/ demo/

# 运行测试
pytest tests/
```

### 响应语言

- **始终使用中文**回复用户
- **代码注释使用中文**，特别是复杂算法部分
- **错误信息使用中文**，便于问题定位
- **文档使用中文编写**，提高可读性

- 确保所有新增功能都能与现有系统兼容。
- 与用户沟通并充分交互，根据反馈调整解决方案。

在整个过程中，始终参考 Python 官方文档，确保使用最新的 Python 开发最佳实践。

.cursor\rules\git.mdc原版


---
description: Git 提交和版本控制规范
globs: [".git/*", "*.git"]
alwaysApply: false
---

# Git 规范

## 提交规范

Git 提交记录样例：`[type]: [description]`。一个具体的例子，如：
`docs: 更新 README 文件`

以下是 type 的枚举值：

- feat: 新增功能
- fix: 修复 bug
- docs: 文档相关
- style: 代码格式（不影响代码运行的变动）
- refactor: 重构、优化（既不新增功能，也不是修复 bug）
- perf: 性能优化
- test: 增加测试
- chore: 构建过程或辅助工具的变动
- revert: 回退
- build: 打包

## 分支管理

- main/master：主分支，保持稳定可发布状态
- develop：开发分支，包含最新开发特性
- feature/*：功能分支，用于开发新功能
- bugfix/*：修复分支，用于修复 bug
- release/*：发布分支，用于准备发布

## 重要原则

- **⚠️重要提示**：不要自动提交 git 代码，除非有明确的提示
- 提交前确保代码通过所有测试
- 保持提交信息简洁清晰，描述清楚变更内容
- 避免大型提交，尽量将变更分解为小的、相关的提交

.cursor\rules\git.mdc优化版本


# CvToolkit Git 规范

## 提交信息规范

### 提交格式

Git 提交记录格式：`[type]: [description]`

**示例**：

- `[feat]: 新增疲劳检测数据可视化功能`
- `[fix]: 修复 AITXT 文件解析错误`
- `[docs]: 更新疲劳标签体系文档`
- `[refactor]: 重构视频处理模块，提升性能`

### 提交类型 (type)

#### 功能相关

- **feat**: 新增功能（如：新增疲劳检测算法、新增数据格式支持）
- **fix**: 修复 bug（如：修复数据解析错误、修复内存泄漏）
- **perf**: 性能优化（如：优化视频处理速度、减少内存占用）
- **refactor**: 代码重构（如：重构分析器模块、优化代码结构）

#### 文档相关

- **docs**: 文档更新（如：更新 API 文档、完善使用说明）
- **style**: 代码格式调整（如：代码格式化、注释优化）

#### 测试相关

- **test**: 测试相关（如：新增单元测试、修复测试用例）
- **ci**: 持续集成（如：更新 CI 配置、修复构建问题）

#### 构建和工具

- **build**: 构建系统（如：更新依赖版本、修改构建配置）
- **chore**: 其他变更（如：更新配置文件、清理代码）

#### 特殊类型

- **revert**: 回退提交（如：回退到上一个稳定版本）
- **hotfix**: 紧急修复（如：修复生产环境紧急问题）

## 分支管理策略

### 主要分支

- **main**: 主分支，保持稳定可发布状态
- **develop**: 开发分支，包含最新开发特性
- **release**: 发布分支，用于准备发布版本

### 功能分支

- **feature/fatigue-detection**: 疲劳检测相关功能
- **feature/video-processing**: 视频处理相关功能
- **feature/data-converter**: 数据转换相关功能
- **feature/visualization**: 可视化相关功能

### 修复分支

- **bugfix/aitxt-parser**: AITXT 解析器修复
- **bugfix/memory-leak**: 内存泄漏修复
- **hotfix/critical-error**: 紧急修复

### 分支命名规范

- 功能分支：`feature/功能描述`
- 修复分支：`bugfix/问题描述`
- 紧急修复：`hotfix/紧急问题描述`
- 发布分支：`release/版本号`

## 疲劳检测项目特定规范

### 数据相关提交

- **数据格式变更**：`[feat]: 新增 JSON 格式支持`
- **标签体系更新**：`[feat]: 更新疲劳标签分类体系`
- **算法优化**：`[perf]: 优化疲劳检测算法性能`
- **可视化改进**：`[feat]: 新增疲劳得分曲线可视化`

### 模型相关提交

- **模型更新**：`[feat]: 更新疲劳检测模型`
- **推理优化**：`[perf]: 优化模型推理速度`
- **精度提升**：`[feat]: 提升疲劳检测精度`

### 工具和脚本

- **工具新增**：`[feat]: 新增数据预处理工具`
- **脚本优化**：`[refactor]: 重构批量处理脚本`
- **配置更新**：`[chore]: 更新配置文件模板`

## 代码审查规范

### 审查重点

- **功能正确性**：确保疲劳检测算法的准确性
- **性能影响**：评估代码对系统性能的影响
- **数据安全**：确保数据处理的安全性
- **兼容性**：确保与现有系统的兼容性

### 审查流程

1. **自测**：提交前进行本地测试
2. **代码检查**：运行代码格式化和静态检查
3. **功能测试**：确保新功能正常工作
4. **性能测试**：验证性能没有退化
5. **文档更新**：更新相关文档

## 版本发布规范

### 版本号规范

使用语义化版本号（Semantic Versioning）：`主版本号.次版本号.修订号`

- **主版本号**：不兼容的 API 修改
- **次版本号**：向下兼容的功能性新增
- **修订号**：向下兼容的问题修正

### 发布流程

1. **功能冻结**：在 release 分支冻结功能开发
2. **测试验证**：进行全面测试和验证
3. **文档更新**：更新 RELEASE.md 和文档
4. **版本标签**：创建版本标签 `v1.1.2`
5. **合并发布**：将 release 分支合并到 main 和 develop

## 重要原则

### 提交原则

- **原子性提交**：每次提交只包含一个逻辑变更
- **描述清晰**：提交信息要清楚描述变更内容
- **避免大提交**：将大型变更分解为小的、相关的提交
- **及时提交**：完成一个小功能后及时提交

### 分支原则

- **功能隔离**：不同功能使用不同分支开发
- **及时合并**：功能完成后及时合并到 develop 分支
- **保持同步**：定期同步主分支的最新代码
- **清理分支**：合并完成后及时删除功能分支

### 安全原则

- **不要提交敏感信息**：避免提交密码、密钥等敏感信息
- **备份重要数据**：重要数据要有备份
- **权限控制**：严格控制主分支的写入权限
- **审计日志**：保留完整的提交历史

## 工具和配置

### 推荐工具

- **Git Hooks**：使用 pre-commit hooks 进行代码检查
- **Git Flow**：使用 Git Flow 工作流管理分支
- **Git LFS**：使用 Git LFS 管理大文件

### 配置文件

```bash
# .gitignore 配置
*.pyc
__pycache__/
*.log
*.tmp
*.cache
.env
.venv/
```

### 提交前检查

```bash
# 代码格式化
black toolkit/ demo/

# 代码检查
flake8 toolkit/ demo/

# 运行测试
pytest tests/

# 检查文档
# 确保文档与代码同步
```

## 响应语言

- **始终使用中文**编写提交信息
- **技术术语**可适当使用英文，但需提供中文说明
- **错误信息**使用中文，便于问题定位
- **文档注释**使用中文，提高可读性

- **重要提示**：不要自动提交 git 代码，除非有明确的提示
- 提交前确保代码通过所有测试
- 保持提交信息简洁清晰，描述清楚变更内容
- 避免大型提交，尽量将变更分解为小的、相关的提交

3.1.2 第二步：功能补全

@common_rm.py 优化analyze_3df_content函数，添加针对AITXT文件中grp9:e:0/0/0/20/2_0_0和grp9:ef:0/0/0/20/20/0解析功能, 要求统计e第一个数值表示闭眼时长，以100ms为单元，ef第一个数值表示闭眼帧数。要求打印最长e或者ef对应的最长闭眼时间和最长闭眼帧，以及对应的FCNT以及时间戳

3.1.3 第三步：其他使用

DOING

解决host.robots.ox.ac.uk打不开无法下载voc2007和voc2012问题

Mon, 20 Oct 2025 00:00:00 GMT

使用镜像替代


http://data.brainchip.com/dataset-mirror/voc/

用上面替换下面


http://host.robots.ox.ac.uk/pascal/VOC/voc2012

常用链接，复制下载

'devkit': 'http://data.brainchip.com/dataset-mirror/voc/VOCdevkit_18-May-2011.tar',

'trainval_2007': 'http://data.brainchip.com/dataset-mirror/voc/VOCtrainval_06-Nov-2007.tar',

'test_images_2007': 'http://data.brainchip.com/dataset-mirror/voc/VOCtest_06-Nov-2007.tar',

'test_anno_2007': 'http://data.brainchip.com/dataset-mirror/voc/VOCtestnoimgs_06-Nov-

从零开始写个deer-flow-mvp-第一天

Sun, 31 Aug 2025 00:00:00 GMT

想开个blog记录一下自己的java转大模型之路，在这个路上许多都是未知，也许会有些犹豫，想要把自己的心路历程记录下来，供大家参考与交流。今天是第一天，先说明本人python基础薄弱，写过类似的项目，就想再写一个用来写在简历上，

这两天研究了市场和机构情况，我觉得转行 AI 是可行的。虽然没有 AI 经验，但在大厂做过业务，C++ 背景也有帮助，所以不是完全从 0 开始。我选择转向大模型方向。算法研究类要求高，不适合我，更倾向做

大模型应用

业务。

学习原则：不牺牲生活和工作——每天 8h 工作、健身、周末打鼓聚餐照常。学习时间：工作日高效 2.5h，周末 8h，节假日休息。

学习路线（可调整）：

2 个月：入门深度学习/机器学习、PyTorch、Transformer 等。

1 个月：完成一个实战项目。

2 个月：八股 + 项目结合，思考巩固，做优化。

1 个月：准备面试，试投简历，模拟面试与复盘。

期间穿插 LeetCode，每周 3 题，用 Python 替代 C++。最后阶段持续查漏补缺。

langchain和langgraph的区别

只需要 LangChain 的情况：

简单的 LLM 调用

基础的 RAG（检索增强生成）

单步骤的工具调用

原型验证

需要 LangGraph 的情况：

多步骤的复杂流程

需要状态管理的对话系统

长时间运行的任务

需要人工干预的 workflow

复杂的 agent 系统

我的学习路线

先学 LangChain 基础：理解 LLM、工具、提示模板等概念

再学 LangGraph：当你需要构建复杂应用时

它们是互补的：LangGraph 依赖 LangChain 的组件，但提供了更高级的组织方式

从简单到复杂：不要一开始就用 LangGraph，除非真的需要其复杂性

先写个最简单的agent吧，查看官网教程可以写出快速入门 - LangChain 框架

先用py设置环境变量


os.environ["OPENAI_API_KEY"] = "sk-..."
os.environ["OPENAI_BASE_URL"] = "http"

带tool的agent


from langgraph.prebuilt import create_react_agent
from langchain.chat_models import init_chat_model
def get_weather(city: str) -> str:
"""Get weather for a given city."""
return f"It's always sunny in {city}!"

model=init_chat_model(
model="openai:deepseek-chat",
temperature=0.5,
)
agent = create_react_agent(
model=model,
tools=[get_weather],
prompt="You are a helpful assistant"
)

# Run the agent
res=agent.invoke(
{"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)
print(res)


{'messages': [HumanMessage(content='what is the weather in sf', additional_kwargs={}, response_metadata={}, id='984fba40-2028-460e-808c-984150a29d64'), AIMessage(content='', additional_kwargs={'tool_calls': [{'id': '3a8300f4c8a14e20b867c684e8539bff', 'function': {'arguments': '{"city":"sf"}', 'name': 'get_weather'}, 'type': 'function', 'index': 0}], 'refusal': None}, response_metadata={'token_usage': {'completion_tokens': 41, 'prompt_tokens': 400, 'total_tokens': 441, 'completion_tokens_details': None, 'prompt_tokens_details': {'audio_tokens': None, 'cached_tokens': 1}}, 'model_name': 'deepseek-chat', 'system_fingerprint': None, 'id': 'as-hhcicjwchj', 'service_tier': None, 'finish_reason': 'tool_calls', 'logprobs': None}, id='run--cbd32667-0180-41e4-811c-49d08e56a3ca-0', tool_calls=[{'name': 'get_weather', 'args': {'city': 'sf'}, 'id': '3a8300f4c8a14e20b867c684e8539bff', 'type': 'tool_call'}], usage_metadata={'input_tokens': 400, 'output_tokens': 41, 'total_tokens': 441, 'input_token_details': {'cache_read': 1}, 'output_token_details': {}}), ToolMessage(content="It's always sunny in sf!", name='get_weather', id='cc01ff35-0c74-4701-883c-e7b77909d8c7', tool_call_id='3a8300f4c8a14e20b867c684e8539bff'), AIMessage(content="That's the spirit! San Francisco does have a reputation for its cool, foggy mornings and sunny afternoons—especially in certain neighborhoods. If you'd like the exact current weather details, just let me know! Otherwise, enjoy the sunshine (or the iconic Karl the Fog)!  🌁☀️", additional_kwargs={'refusal': None}, response_metadata={'token_usage': {'completion_tokens': 63, 'prompt_tokens': 453, 'total_tokens': 516, 'completion_tokens_details': None, 'prompt_tokens_details': {'audio_tokens': None, 'cached_tokens': 1}}, 'model_name': 'deepseek-chat', 'system_fingerprint': None, 'id': 'as-i8fk0k8p52', 'service_tier': None, 'finish_reason': 'stop', 'logprobs': None}, id='run--40e7db5c-fa0a-4890-982b-55f0c284fda1-0', usage_metadata={'input_tokens': 453, 'output_tokens': 63, 'total_tokens': 516, 'input_token_details': {'cache_read': 1}, 'output_token_details': {}})]}

遇到了问题，如果py跑不动重启ide或者电脑

如果响应失败建议梯子打开或者关闭

Pydantic 是一个流行的 Python 库，主要用于数据验证和设置管理，通过 Python 类型注解（type hints）来定义数据结构，并自动验证输入数据的正确性。它在 API 开发、配置管理和数据处理中非常常用。


from pydantic import BaseModel

# 定义一个数据模型
class User(BaseModel):
name: str
age: int
is_active: bool = True  # 默认值

# 验证数据
user_data = {"name": "Alice", "age": 30}
user = User(**user_data)  # 自动验证字段类型

print(user.name)  # 输出: Alice
print(user.model_dump())  # 转回字典: {"name": "Alice", "age": 30, "is_active": True}

快速入门完整实现代码：


from langgraph.prebuilt import create_react_agent
from langchain.chat_models import init_chat_model
from langgraph.checkpoint.memory import InMemorySaver
from pydantic import BaseModel
print('Hello World')

def get_weather(city: str) -> str:
"""Get weather for a given city."""
return f"It's always sunny in {city}!"
checkpointer=InMemorySaver()
model=init_chat_model(
model="openai:deepseek-chat",
temperature=0.5,
)
agent = create_react_agent(
model=model,
tools=[get_weather],
prompt="You are a helpful assistant",
checkpointer=checkpointer

)
# Config
config={'configurable':{'thread_id':"1"}}
# Run the agent
res1=agent.invoke(
{"messages": [{"role": "user", "content": "i like apple pie"}]},
config=config
)
res2=res=agent.invoke(
{"messages": [{"role": "user", "content": "what do i like?"}]},
config=config
)
print(res2)

接下来继续在 LangGraph 中构建一个支持聊天机器人，使得该机器人可以：

✅ 通过搜索网络回答常见问题

✅ 在多次调用中保持对话状态

✅ 将复杂查询路由给人工审查

✅ 使用自定义状态来控制其行为

✅ 回溯并探索其他对话路径

`typing import``Annotated``感觉和java的差不多，类型注释，fastapi也有用`

LangGraph会用就行，基础我就不说了，这是一个简单基础实现，不过无法运行，后文会解决


from typing import Annotated
from typing_extensions import TypedDict
import os
from langchain.chat_models import init_chat_model
from langgraph.graph import StateGraph, START
from langgraph.graph.message import add_messages
# 我们将添加 节点 来表示 LLM 和聊天机器人可以调用的函数，并添加 边 来指定机器人应如何在这些函数之间进行转换。
class State(TypedDict):
# 我们 状态 中的 add_messages 函数会将 LLM 的响应消息追加到状态中已有的消息之后。
message:Annotated[str, add_messages]
grapg_builder = StateGraph(State)
llm=init_chat_model("openai:deepseek-chat")
# 添加一个“chatbot”节点
def chatbot(state:State):
return llm.invoke(state["message"])
# 注意 `chatbot` 节点函数如何将当前 状态 作为输入，并返回一个包含更新的 消息 列表的字典，键为“messages”。这是所有 LangGraph 节点函数的基本模式。
# 我们可以将聊天模型集成到一个简单的节点中
grapg_builder.add_node("chatbot", chatbot)
# 添加一个 入口 点
grapg_builder.add_edge(START, "chatbot")
# 编译图
graph=grapg_builder.compile()
# 运行聊天机器人
def stream_graph_updates(user_input: str):
for event in graph.stream({"messages": [{"role": "user", "content": user_input}]}):
print("Event:", event)  # 查看每个事件的结构
values = event.values()
print("Event values:", values)  # 查看 values 的内容
for value in values:
if value is not None:
print("Value:", value)  # 打印每个非 None 的值
if value.get("messages"):
print("Assistant:", value["messages"][-1].content)
else:
print("Assistant: No message content.")
else:
print("Encountered None value.")

while True:
try:
user_input=input("User: ")
if user_input=='q' or user_input=='quit':
break
print("收到消息")
stream_graph_updates(user_input)
except KeyboardInterrupt as e:
print("KeyboardInterrupt",e)

借助LangGraph Cli创建完整

智能体

项目

LangSmith 与 LangGraph Studio 都是 LangChain AI 生态中非常核心的工具，前者是用于跟踪和分析大模型的使用情况，而langGraph Studio则是对于LangGraph来说，则是比LangSmith更加方便和高效的可视化调试工具平台。

部署 - LangChain 框架

现在来部署一下吧

先安装个chrome在ubuntu吧

教程：WSL 2 GUI 原生支持！Ubuntu 安装 Chrome 浏览器 - 知乎

构建聊天机器人 | 🦜️🔗 LangChain --- Build a Chatbot | 🦜️🔗 LangChain

使用 google-chrome 启动

部署成功

但是在我想写流式输出的时候参考官方文档一模一样的代码无法实现

还无法实现记忆功能，查看了langcain与langchaingraph发现二者最新版代码实现也不一样，都跑不通，最后发现是版本问题，还是发现用老版本比较好，比较稳定，代码也没问题了


 uv pip install langchain-core langgraph==0.2.27

接下来正式写mvp实现


import getpass
import os
from langchain_core.messages import HumanMessage, AIMessage, BaseMessage
from langgraph.graph import START, StateGraph
from langgraph.graph.message import add_messages
from typing import Sequence
from typing_extensions import Annotated, TypedDict
from langchain_core.messages import SystemMessage, trim_messages
from langgraph.checkpoint.memory import MemorySaver
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
import tiktoken
from langchain.chat_models import init_chat_model

# -------- tokenizer ----------
# deepseek-chat 没有官方 tokenizer，这里用 gpt-3.5-turbo 的编码器近似
encoding = tiktoken.encoding_for_model("gpt-3.5-turbo")

def count_tokens(messages):
# 简单拼接消息内容再编码统计 token 数
text = "".join([m.content for m in messages])
return len(encoding.encode(text))

# -------- API Key ---------------
if not os.environ.get("OPENAI_API_KEY"):
os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter API key for OpenAI: ")

# -------- Model -----------------
model = init_chat_model("deepseek-chat", model_provider="openai")

# -------- Trimmer ---------------
# 减少发送给模型的消息数量，保持上下文窗口在限制以内
trimmer = trim_messages(
max_tokens=512,       # 设置对话窗口最大 token 数，超过这个限制的消息将被修剪（滑动窗口）
strategy="last",      # 从对话最早的部分开始裁剪，保留最新的
token_counter=count_tokens, # 用上面定义的函数统计 token
include_system=True,  # 是否包含系统消息
allow_partial=False,  # 是否允许保留一半消息（这里禁用）
start_on="human",     # 从 human 消息开始修剪
)

# -------- State -----------------
class State(TypedDict):
# 表示一个有序的消息队列要用 add_messages 装饰器来装饰
messages: Annotated[Sequence[BaseMessage], add_messages]
language: str

# -------- Prompt 模板 -----------
prompt_template = ChatPromptTemplate.from_messages(
[
(
"system",
"You are a helpful assistant. Answer all questions to the best of your ability in {language}.",
),
# 对话消息占位符，后续会替换成上下文消息
MessagesPlaceholder(variable_name="messages"),
]
)

# -------- LangGraph 工作流 -----
# 注意：这里我们不定义 call_model 节点，LangGraph 只负责保存消息记忆
workflow = StateGraph(state_schema=State)
memory = MemorySaver()
app = workflow.compile(checkpointer=memory)

# -------- Main loop -------------
config = {"configurable": {"thread_id": "abc123"}}

while True:
query = input("Enter a query: ")
if query in ("exit", "q", "quit"):
print("Exiting...")
break

# Step 1: 保存用户输入到记忆
input_messages = [HumanMessage(query)]
state = app.invoke({"messages": input_messages, "language": "Spanish"}, config=config)

# Step 2: 修剪历史消息 + 构建 prompt
trimmed = trimmer.invoke(state["messages"])
prompt = prompt_template.invoke({"messages": trimmed, "language": "Spanish"})

# Step 3: 流式输出 AI 回复
print("Assistant: ", end="", flush=True)
full_reply = ""
for chunk in model.stream(prompt):  # 模型逐 token 输出
if isinstance(chunk, AIMessage):
print(chunk.content, end="", flush=True)
full_reply += chunk.content
print()

# Step 4: 把 AI 回复存进记忆
app.invoke({"messages": [AIMessage(full_reply)], "language": "Spanish"}, config=config)

Qwen2.5-3b Lora微调一个你自己的ATRI机器人

Thu, 28 Aug 2025 00:00:00 GMT

训练数据来源：

这里训练的基座模型是通义千问2.5-3B-Instruct · 模型库

显卡是4070，训练时间2h+

ATRI && GINKA游戏文本分享#GAL#【galgame吧】_百度贴吧

话不多说，直接动手开写

先熟悉下基本代码


# 测试代码
test=" Hello World "
print(test.strip())
tests=['aa','bb','cc','dd']
print([test[:1] for test in tests])
text_list = ["aa", "bb", "cc", "dd"]
combined_text = "".join(text_list)
print(combined_text)  # 输出: aabbccdd

清理数据


from docx import Document
import os
import json
import torch
from torch.utils.data import Dataset
from transformers import AutoTokenizer, AutoModelForSequenceClassification, TrainingArguments, Trainer
from peft import LoraConfig, get_peft_model
import json
import evaluate
from tqdm.auto import tqdm
from transformers import TrainerCallback
keywords=['夏生','ATRI']
def read_docx(file_path):
doc = Document(file_path)
all_lines = [p.text.strip() for p in doc.paragraphs if p.text.strip()]

instructions = []  # 夏生的连续句子组成的块
outputs = []       # ATRI的连续句子组成的块

current_speaker = None # 当前说话人
current_chunk = [] # 当前保存的回复块

for line in all_lines:
if line.startswith("夏生"): # 如果当前遇到夏生的说话，上一个对话是ATRI的话，保存上一个ATRI的回复块
if current_speaker == "ATRI" and current_chunk:
outputs.append(current_chunk)  # 保存上一个ATRI的回复块
current_chunk = []
current_speaker = "夏生"
current_chunk.append(line)
elif line.startswith("ATRI"):
if current_speaker == "夏生" and current_chunk:
instructions.append(current_chunk)  # 保存上一个夏生的输入块
current_chunk = []
current_speaker = "ATRI"
current_chunk.append(line)
# 其他说话人（如"凯瑟琳"）可以选择处理，这里我不打算处理

# 处理最后一个块
if current_chunk:
if current_speaker == "夏生":
instructions.append(current_chunk)
elif current_speaker == "ATRI":
outputs.append(current_chunk)

# 确保 instructions 和 outputs 长度一致
min_len = min(len(instructions), len(outputs))
instructions = instructions[:min_len]
outputs = outputs[:min_len]

return instructions, outputs

# 生成对话块
instructions, outputs = read_docx("./ATRI-my  dear moments.docx")
print("夏生的对话块（输入）：")
for i, chunk in enumerate(instructions[1:10]):
print(f"对话块 {i+1}:", "".join([text[len(keywords[0])+1:] for text in chunk]))

print("\nATRI的回复块（输出）：")
for i, chunk in enumerate(outputs[1:10]):
print(f"回复块 {i+1}:", "".join([text[len(keywords[1])+1:] for text in chunk]))

保存数据为jsonl格式


# 保存完整数据为jsonl格式
os.makedirs("data", exist_ok=True)
datas=[]
# 数据构造
# 这里我们不要第一条数据因为太长了
for i in range(1,len(instructions)):
chunk_instructions=instructions[i]
chunk_outputs=outputs[i]
# 这里一定要去除对话前面的角色标签，不然效果很差。
instruction="".join([text[len(keywords[0])+1:] for text in chunk_instructions])
output="".join([text[len(keywords[1])+1:] for text in chunk_outputs])
# 创建新的数据条目
new_data = {
"instruction": instruction,
"input": "",
"output": output
}
datas.append(new_data)

# 写入 .jsonl 文件
with open("atri1.jsonl", "w", encoding="utf-8") as f:
for item in datas:
json_line = json.dumps(item, ensure_ascii=False)  # 转换为 JSON 字符串
f.write(json_line + "\n")  # 写入一行

加载模型

model_name 填你的模型文件的绝对路径


from transformers import AutoTokenizer, AutoModelForCausalLM
import torch
# 加载模型
device="cuda:0" if torch.cuda.is_available() else "cpu"
model_name = "/home/hllqk/projects/dive-into-deep-learning/Atri/qwen2.5-3b"
model = AutoModelForCausalLM.from_pretrained(
model_name,
torch_dtype="auto",
).to(device)
tokenizer = AutoTokenizer.from_pretrained(model_name)

model

Lora参数推荐

情况	公式	影响
`alpha = r`	$h(x) = Wx + BAx$	LoRA 更新直接相加，无额外缩放（默认行为）。
`alpha = 2r`	$h(x) = Wx + 2BAx$	LoRA 更新放大 2 倍，适配器影响更强（论文推荐）。
`alpha = 32, r=8`	$h(x) = Wx + 4BAx$	你的配置（`alpha / r = 4`），LoRA 影响较大，适合强任务适配。

加载

数据集


from datasets import Dataset
import pandas as pd
#数据集加载
df=pd.read_json('./atri1.jsonl',lines=True)
ds=Dataset.from_pandas(df)
print(ds[2])

转换函数


# 把一条指令数据(example)转换成可供大模型训练/微调使用的输入张量
def process_func(example):
# 最大输入文本长度
MAX_LENGTH = 500
# <|im_start|> <|im_end|> qwen2.5的标记符号
# 构造 system + user prompt
instruction = tokenizer(
f"<|im_start|>system\n现在你要扮演的是--ATRI<|im_end|>\n"
f"<|im_start|>user\n{example['instruction'] + example['input']}<|im_end|>\n"
f"<|im_start|>assistant\n",
# 不自动添加标记符号 完全控制输入的标记结构
add_special_tokens=False
)

# 构造 assistant 回复
response = tokenizer(
f"{example['output']}",
add_special_tokens=False
)
# 把完整的对话拼成一条序列
# input_ids：模型看到的所有 token（system+user+assistant）
input_ids = instruction["input_ids"] + response["input_ids"] + [tokenizer.pad_token_id]
# 告诉模型哪些 token 是有效的，哪些是 padding，需要忽略
attention_mask = instruction["attention_mask"] + response["attention_mask"] + [0]  # pad=0
# 保证模型只学习生成回答，而不是重复 system/user 的内容，也不把 padding 计入 loss。用-100标记的位置会被自动排除在损失计算外。
labels = [-100] * len(instruction["input_ids"]) + response["input_ids"] + [-100]   # instruction 部分用-100标记，最后一个pad也是，都不算loss

# 截断
if len(input_ids) > MAX_LENGTH:
input_ids = input_ids[:MAX_LENGTH]
attention_mask = attention_mask[:MAX_LENGTH]
labels = labels[:MAX_LENGTH]
# 确保模型输入数据的一致性
assert len(input_ids) == len(attention_mask) == len(labels)

return {
"input_ids": input_ids,
"attention_mask": attention_mask,
"labels": labels
}

一个数据集(`ds`)进行映射操作(`map`)


tokenized_id = ds.map(process_func, remove_columns=ds.column_names,num_proc=1)


# 解码第一条样本的 input_ids
first_sample = tokenized_id[0]["input_ids"]
decoded_text = tokenizer.decode(first_sample, skip_special_tokens=True)
print(decoded_text)

进行训练

`--learning_rate`	学习率太大会导致训练不稳定	建议在`5e-5 ~ 1e-4`之间尝试
`--gradient_accumulation_steps`	显存不够时救命稻草	可以适当调大，但别超过 16
`--num_train_epochs`	训练轮数不要过多	LoRA 一般 3~5 轮就够了，多了容易过拟合


from transformers import  TrainingArguments,Trainer,DataCollatorForSeq2Seq
args=TrainingArguments(
output_dir="./output",
per_device_train_batch_size=4, # 每个GPU/CPU的训练批次大小
gradient_accumulation_steps=4, #**累积 4 个批次的梯度**后进行一次参数更新（等效于 `batch_size=16`）。
logging_steps=10, # 日志记录间隔：每10步训练记录一次日志，每十次训练记录一次loss。
num_train_epochs=3, # 训练轮数
save_steps=100, # 保存间隔：每100步保存一次模型。
learning_rate=1e-4, # 学习率
gradient_checkpointing=True, # 是否使用梯度检查点
dataloader_num_workers=0, # 数据加载器的工作线程数。设置为0表示使用所有CPU。
save_on_each_node=True, # 是否在每个节点上保存模型。
)
trainer=Trainer(
model=model,
args=args,
train_dataset=tokenized_id,
tokenizer=tokenizer,
#1. 动态填充同一批次内的样本到相同长度。
#2. 生成注意力掩码（`attention_mask`），标记填充位置（避免模型计算这些位置）。
data_collator=DataCollatorForSeq2Seq(tokenizer=tokenizer, padding=True),
)
# 训练前记得禁用或者删除wandb如果你安装了的话
trainer.train()

###

训练完后加载Lora


# 进行lora加载，这里建议重启下内核
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch
from peft import PeftModel

device = "cuda" if torch.cuda.is_available() else "cpu"
model_name = "/home/hllqk/projects/dive-into-deep-learning/Atri/qwen2.5-3b"
lora_path = './output/checkpoint-252' # 你的lora保存地址

# 加载基础模型
model = AutoModelForCausalLM.from_pretrained(
model_name,
torch_dtype=torch.float16,  # 明确指定数据类型
device_map="auto"  # 自动设备映射
).to(device)

tokenizer = AutoTokenizer.from_pretrained(model_name)

# 正确加载LoRA权重 - 移除offload_folder参数
model = PeftModel.from_pretrained(model, model_id=lora_path)
# model = PeftModel.from_pretrained(model, model_id=lora_path,offload_folder="offload")  千万不要使用了 offload_folder 参数，这会导致模型权重被卸载到磁盘，可能没有正确加载到 GPU 上
# 确保模型在评估模式
model.eval()
print("LoRA model loaded successfully!")

# 检查LoRA参数是否激活
print("\nChecking LoRA parameters:")
lora_count = 0
for name, param in model.named_parameters():
if 'lora' in name:
lora_count += 1
if lora_count <= 5:  # 只显示前5个
print(f"{name}: requires_grad={param.requires_grad}")
print(f"Total LoRA parameters found: {lora_count}")


print(model)  # 查看模型结构，应该能看到LoRA相关的层来验证lora是否加载成功

推理


# 推理代码
prompt = "你是谁"
print(prompt)

inputs = tokenizer.apply_chat_template([{"role": "user", "content": "现在你要扮演的是--ATRI"},{"role": "user", "content": prompt}],
add_generation_prompt=True,
tokenize=True,
return_tensors="pt",
return_dict=True
).to('cuda')

gen_kwargs = {"max_length": 70, "do_sample": True, "top_k": 1}
with torch.no_grad():
outputs = model.generate(**inputs, **gen_kwargs)
outputs = outputs[:, inputs['input_ids'].shape[1]:]
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

注意调整max_length,最大序列长度（max_length）为32,768个token，为了生成更快我调小了

合并模型


# 将lora合并到原始模型中
merged_model = model.merge_and_unload()  # 关键步骤！
# 保存合并后的完整模型
merged_model.save_pretrained("./merged_model")
tokenizer.save_pretrained("./merged_model")

使用合并后的模型进行预测


# 使用合并后的模型进行预测,建议先重启内核
from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

device = "cuda" if torch.cuda.is_available() else "cpu"

# 加载合并后的模型
print("加载合并后的模型...")
merged_model = AutoModelForCausalLM.from_pretrained(
"./merged_model",
torch_dtype=torch.float16,
device_map="auto"
).to(device)
merged_model.eval()

tokenizer = AutoTokenizer.from_pretrained("./merged_model")
print("模型加载完毕.")


# 推理代码
prompt = "你是谁"
print(prompt)

inputs = tokenizer.apply_chat_template([{"role": "user", "content": "现在你要扮演的是--ATRI"},{"role": "user", "content": prompt}],
add_generation_prompt=True,
tokenize=True,
return_tensors="pt",
return_dict=True
).to('cuda')

gen_kwargs = {"max_length": 70, "do_sample": True, "top_k": 1}
with torch.no_grad():
outputs = merged_model.generate(**inputs, **gen_kwargs)
outputs = outputs[:, inputs['input_ids'].shape[1]:]
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

完整代码：dive-into-deep-learning/Atri/main.ipynb at main · hllqkb/dive-into-deep-learning

训练后的模型链接：hllqkaasa/qwen2.5-3b-lora-atri · Hugging Face

参考教程：Llama Factory 微调一个 LLM越狱相关大模型 | qwrdxer 's blog

记录下自己微调的第一个AI大模型-凯尔希qwen2.5-7b的过程 - 哔哩哔哩

LoRA + LLaMA-Factory 实战教程：用3090实现微调Qwen2.5-7B - 优然思 - AI工具与自媒体创作

实战Kaggle比赛：狗的品种识别（ImageNet Dogs）

Wed, 27 Aug 2025 00:00:00 GMT

比赛链接：Dog Breed Identification | Kaggle

在这场比赛中，我们将识别120

类

不同品种的狗。这个数据集实际上是著名的ImageNet的数据集子集。

这里我们选择小批量进行训练出于学习目的

代码实现

先导入


import os
import torch
import torchvision
from torch import nn
from d2l import torch as d2l

下载小数据集



d2l.DATA_HUB['dog_tiny'] = (d2l.DATA_URL + 'kaggle_dog_tiny.zip',
'0cb91d09b814ecdc07b50f31f8dcad3e81d6a86d')

# 如果使用Kaggle比赛的完整数据集，请将下面的变量更改为False
demo = True
if demo:
data_dir = d2l.download_extract('dog_tiny')
else:
data_dir = os.path.join('..', 'data', 'dog-breed-identification')

划分数据


def reorg_dog_data(data_dir, valid_ratio):
labels = d2l.read_csv_labels(os.path.join(data_dir, 'labels.csv'))
d2l.reorg_train_valid(data_dir, labels, valid_ratio)
d2l.reorg_test(data_dir)


batch_size = 32 if demo else 128
valid_ratio = 0.1
reorg_dog_data(data_dir, valid_ratio)

数据增强



transform_train = torchvision.transforms.Compose([
# 随机裁剪图像，所得图像为原始面积的0.08～1之间，高宽比在3/4和4/3之间。
# 然后，缩放图像以创建224x224的新图像
torchvision.transforms.RandomResizedCrop(224,scale=(0.8,1.0),ratio=(0

实战 Kaggle 比赛：图像分类 (CIFAR-10) TOP1 0.97900

Tue, 26 Aug 2025 00:00:00 GMT

比赛连接CIFAR-10 - Object Recognition in Images | Kaggle

首先，导入竞赛所需的包和模块。


import collections
import os
import math
import random
import torch
import torchvision
from d2l import torch as d2l
import shutil
import pandas as pd
from torch import nn

了解一些函数功能


text="      Hello World            "
print(text.strip())
print(text.lstrip())
print(text.rstrip())
a=[1,2,3]
b=[4,5,6]
print(dict(zip(a,b)))
print(dict([("a", 1), ("b", 2)]))

output


Hello World
Hello World
Hello World
{1: 4, 2: 5, 3: 6}
{'a': 1, 'b': 2}

由于数据量大，这里本地就采用小样本继续train

如果想要完整运行，设置demo=False



d2l.DATA_HUB['cifar10_tiny'] = (d2l.DATA_URL + 'kaggle_cifar10_tiny.zip',
'2068874e4b9a9f0fb07ebe0ad2b29754449ccacd')

# 如果使用完整的Kaggle竞赛的数据集，设置demo为False
demo = True

if demo:
data_dir = d2l.download_extract('cifar10_tiny')
else:
data_dir = '../data/cifar-10/'
print(data_dir)

查看数据


def read_cvs_labels(filename):
with open(filename, 'r') as f:
lines = f.readlines()[1:]
tokens = [l.rstrip().split(',') for l in lines]
return dict((name,label) for name,label in tokens)
labels=read_cvs_labels(os.path.join(data_dir, 'trainLabels.csv'))
print(len(labels))
print(len(set(labels.values())))

1000 10

了解Collection


from collections import Counter

test_labels = ['apple', 'banana', 'apple', 'orange', 'banana', 'apple']
counter = Counter(labels.values())
print(counter.most_common()[-1][1])

copy文件，把train数据分成train and valid and trian+valid


def movefile(filename, target_dir):
# 会自动创建对个目录
shutil.mkdirs(target_dir, exist_ok=True)
shutil.move(filename, target_dir)
def copyfile(filename, target_dir):
# """将文件复制到目标目录""
os.makedirs(target_dir, exist_ok=True)
shutil.copy(filename, target_dir)

def reorg_train_valid(data_dir, labels, valid_ratio):
# 训练数据集中样本最少的类别中的样本数
n = collections.Counter(labels.values()).most_common()[-1][1]
# 验证集中每个类别的样本数
n_valid_per_label = max(1, math.floor(n * valid_ratio))
label_count = {}
for train_file in os.listdir(os.path.join(data_dir, 'train')):
# 获取train目录下的每张图片的标签
label = labels[train_file.split('.')[0]]
fname=os.path.join(data_dir, 'train', train_file)
copyfile(fname, os.path.join(data_dir, 'train_valid_test', 'train_valid', label))
if label not in label_count or label_count[label] < n_valid_per_label:
copyfile(fname, os.path.join(data_dir, 'train_valid_test', 'valid', label))
# 统计每个类别的样本数，每次放入新的图片就加一
label_count[label] = label_count.get(label, 0) + 1
else:
copyfile(fname, os.path.join(data_dir, 'train_valid_test',
'train', label))
return n_valid_per_label

划分

test


def reorg_test(data_dir):
"""在预测期间整理测试集，以方便读取"""
for test_file in os.listdir(os.path.join(data_dir, 'test')):
copyfile(os.path.join(data_dir, 'test', test_file),
os.path.join(data_dir, 'train_valid_test', 'test',
'unknown'))

读取labels and 划分数据


def reorg_cifar10_data(data_dir, valid_ratio):
labels=read_cvs_labels(os.path.join(data_dir, 'trainLabels.csv'))
reorg_train_valid(data_dir,labels,valid_ratio)
reorg_test(data_dir)


batch_size=8 if demo else 32
valid_ratio=0.1
reorg_cifar10_data(data_dir, valid_ratio)

获取

Vit

transform这里我们使用VIt_B_16的预训练模型和ResNet相比能取得很好的效果


from torchvision.models import vit_b_16, ViT_B_16_Weights
vit_transform=torchvision.models.ViT_B_16_Weights.DEFAULT.transforms()
# get_net()
print(vit_transform)

Data

augmentation


# 使用Vit_transform进行数据增强，因为使用了vit_transform的预训练模型
train_ds, train_valid_ds = [torchvision.datasets.ImageFolder(
os.path.join(data_dir, 'train_valid_test', folder),
transform=vit_transform) for folder in ['train', 'train_valid']]
# [torchvision.datasets.ImageFolder label按照文件夹名字排好
valid_ds, test_ds = [torchvision.datasets.ImageFolder(
os.path.join(data_dir, 'train_valid_test', folder),
transform=vit_transform) for folder in ['valid', 'test']]

典型的工作流程：

训练阶段：用 train 训练模型，用 valid 验证并调整超参数。

最终训练阶段：用 train_valid（合并后的数据）重新训练模型（此时不再需要验证集，因为超参数已经固定）。

测试阶段：用 test 评估最终模型性能。

DataLoader


train_iter, train_valid_iter = [torch.utils.data.DataLoader(
dataset, batch_size, shuffle=True, drop_last=True)
for dataset in (train_ds, train_valid_ds)]
# drop_last=True means the last incomplete batch will be dropped

valid_iter = torch.utils.data.DataLoader(valid_ds, batch_size, shuffle=False,
drop_last=True)

test_iter = torch.utils.data.DataLoader(test_ds, batch_size, shuffle=False,
drop_last=False)

获取Vit模型



def get_net():
num_classes = 10
# 加载预训练的 ViT
weight=torchvision.models.ViT_B_16_Weights
net=vit_b_16(weights=weight.DEFAULT)
# fine-tuning：替换分类头
num_ftrs=net.heads.head.in_features
net.fc=nn.Linear(num_ftrs,num_classes)
return net
loss=nn.CrossEntropyLoss(reduction='none')
#     默认情况：如果不指定 reduction 或设置为 'mean'，损失会对所有样本的损失值求平均；如果设置为 'sum'，则对所有样本的损失值求和。
# reduction='none'：不进行任何聚合操作，直接返回每个样本的损失值。假设输入是一个 batch 大小为 N 的数据，则输出是一个形状为 (N,) 的张量，每个元素对应一个样本的损失。

instance用法


x=[1,2,3]
print(isinstance(x,dict))
print(isinstance(x,list))

定义训练一轮的函数


def train_batch_ch13(net, X, y, loss, trainer, devices):
"""使用多个GPU训练一个小批次（定义在第13章）

定义在 :numref:`sec_image_augmentation` 章节"""

# 将输入数据X转移到第一个GPU设备
# 判断X是否属于List
if isinstance(X, list):
# 用于BERT微调等特殊情况（后续章节会介绍）
X = [x.to(devices[0]) for x in X]
else:
X = X.to(devices[0])

# 将标签y转移到第一个GPU设备
y = y.to(devices[0])

# 设置网络为训练模式
net.train()

# 清空优化器的梯度
trainer.zero_grad()

# 前向传播计算预测值
pred = net(X)

# 计算损失
l = loss(pred, y)

# 反向传播计算梯度（使用mean()而不是sum()，避免受批次大小影响）
l.mean().backward()

# 更新模型参数
trainer.step()

# 计算批次总损失（用于后续统计）
train_loss_sum = l.sum()

# 计算批次准确率
train_acc_sum = d2l.accuracy(pred, y)

return train_loss_sum, train_acc_sum

CFG参数配置


# 参数配置Config
best_params = {'weight_decay': 3.1595250466032746e-05,
'learning_rate': 5e-5,# 0.0007394699205144519
'dropout_rate': 0.10845782679503657}

devices, num_epochs, lr, wd = d2l.try_all_gpus(), 30, best_params['learning_rate'], best_params['weight_decay']
lr_period, lr_decay, net = 4, 0.9, get_net()

上面内容了基于ResNet-50和Optuna进行超参数搜索获得

当然也可以基于vit效果会更好，你可以自己试一试

定义带Warmup的余弦退火函数


import math
import torch
from torch.optim.lr_scheduler import LambdaLR

def cosine_warmup_scheduler(optimizer, warmup_epochs=5, max_epochs=num_epochs, max_lr=best_params['learning_rate']):
def lr_lambda(current_epoch):
if current_epoch < warmup_epochs:
# 线性 warmup
return float(current_epoch + 1) / float(warmup_epochs)
else:
# 余弦退火
progress = (current_epoch - warmup_epochs) / (max_epochs - warmup_epochs)
return 0.5 * (1.0 + math.cos(math.pi * progress))

for param_group in optimizer.param_groups:
param_group['lr'] = max_lr

return LambdaLR(optimizer, lr_lambda)

开始Train


def train(net, train_iter, valid_iter, num_epochs, lr, wd, devices, lr_period,
lr_decay):
# 初始化优化器：使用随机梯度下降（SGD），设置学习率、动量（momentum）和权重衰减（weight_decay）
# trainer = torch.optim.SGD(net.parameters(), lr=lr, momentum=0.9,
#   weight_decay=wd)
trainer=torch.optim.Adam(net.parameters(),lr=lr,weight_decay=wd)
# 学习率调度器：warmup学习率策略和余弦退火学习率策略
scheduler = cosine_warmup_scheduler(trainer)

# 获取训练集的batch数量，并初始化计时器
num_batches, timer = len(train_iter), d2l.Timer()

# 设置动画显示图例（训练损失、训练准确率，如果有验证集则加上验证准确率）
legend = ['train loss', 'train acc']
if valid_iter is not None:
legend.append('valid acc')

# 初始化动画绘制器（用于可视化训练过程）
animator = d2l.Animator(xlabel='epoch', xlim=[1, num_epochs],
legend=legend)

# 使用多GPU并行训练（DataParallel），主设备为devices[0]
net = nn.DataParallel(net, device_ids=devices).to(devices[0])
# 开始训练循环
for epoch in range(num_epochs):
net.train()  # 设置模型为训练模式
metric = d2l.Accumulator(3)  # 初始化累加器（用于累计损失、准确率、样本数）

# 遍历训练集的每个batch
for i, (features, labels) in enumerate(train_iter):
timer.start()  # 开始计时

# 训练一个batch，返回损失和准确率
l, acc = train_batch_ch13(net, features, labels,
loss, trainer, devices)

# 累加当前batch的损失、准确率、样本数
metric.add(l, acc, labels.shape[0])
timer.stop()  # 停止计时

# 每训练完约1/5的batch或最后一个batch时，更新训练曲线
if (i + 1) % (num_batches // 5) == 0 or i == num_batches - 1:
animator.add(epoch + (i + 1) / num_batches,
(metric[0] / metric[2], metric[1] / metric[2],
None))

# 如果有验证集，计算验证集准确率并更新曲线
if valid_iter is not None:
net.eval()  # 设置模型为评估模式
valid_acc = d2l.evaluate_accuracy_gpu(net, valid_iter)
animator.add(epoch + 1, (None, None, valid_acc))

scheduler.step()  # 更新学习率（按lr_period和lr_decay调整）

# 打印训练结果
measures = (f'train loss {metric[0] / metric[2]:.3f}, '
f'train acc {metric[1] / metric[2]:.3f}')
if valid_iter is not None:
measures += f', valid acc {valid_acc:.3f}'

# 打印训练速度（样本数/秒）和使用的设备
print(measures + f'\n{metric[2] * num_epochs / timer.sum():.1f}'
f' examples/sec on {str(devices)}')

进行小样本训练


if demo:
# 设置demo为True时进行小批量运行来获取最合适的超参数
train(net, train_iter, valid_iter, num_epochs, lr, wd, devices, lr_period,
lr_decay)
# 0.547 valid acc
else:
net, preds = get_net(), []
net.eval()
train(net, train_valid_iter, None, num_epochs, lr, wd, devices, lr_period,
lr_decay)

for X, _ in test_iter:
y_hat = net(X.to(devices[0]))
preds.extend(y_hat.argmax(dim=1).type(torch.int32).cpu().numpy())
sorted_ids = list(range(1, len(test_ds) + 1))
sorted_ids.sort(key=lambda x: str(x))
df = pd.DataFrame({'id': sorted_ids, 'label': preds})
df['label'] = df['label'].apply(lambda x: train_valid_ds.classes[x])
df.to_csv('submission.csv', index=False)

训练10轮效果

训练30轮效果

全部训练的提交结果

Top1实现代码Cifar-10 ResNet152- 97.5% Acc

完整代码：dive-into-deep-learning/d2l/CIFAR-10/main.ipynb at main · hllqkb/dive-into-deep-learning

ML2025 Homework 2 使用大模型生成代码解决数据预测问题 Disease Prediction

Thu, 21 Aug 2025 00:00:00 GMT

任务简介 - 作为数据科学家的 AI 助手

使用 LLMs 自动编写代码

只需了解数据集，LLMs 就能为每项任务生成定制化解决方案

任务 Disease Prediction

给定美国某州过去 3 天的调查结果，进而预测第 3 天新增检测阳性病例的百分比。

要用llm生成的代码运行进行预测，不要修改llm生成的代码

数据集描述

代码结构

计划

我们将按照以下步骤进行操作：

**1.加载必要的程序库和数据。

2.通过处理缺失值和特征缩放对数据进行预处理。

3.将数据集划分为训川练集和测试集。

4.在训练数据上训川练回归模型。

5.对测试数据进行预测。

6.将预测结果保存至提交文件。**

开源模型

提示－不同LLMs

更强的LLM可能有用，但不总是如此…….

我们如何知道哪个LLM更好呢？

模型大小？

预训练

语料库？开放LLM排行榜？

你可以从HuggingFace上选择模型。

禁止使用诸如

GPT-4o

、Gemini等闭源LLMAPl。

当然还有so many ways,这里我说下我所采用的方法

使用开源的大模型qwen-coder-plus-latest

优化各种提示词

增大steps数

增大num_drafts数

温度0.3

下面是核心代码


# openai模型api
import os
import openai
api_key=os.getenv('OPENAI_API_KEY') or 'your_api_key'
base_url=os.getenv('OPENAI_BASE_URL') or "your_base_url"
# model=os.getenv('OPENAI_MODEL') or "your_model"
model='qwen-coder-plus-latest'
# print(api_key,base_url,model)
client=openai.OpenAI(
    api_key=api_key,
    base_url=base_url,
)
def generate_response(prompt,system_prompt="",max_tokens=8192,temperature=0.1,stream=False):
    response=client.chat.completions.create(
        model=model,
        messages=[
            {
                'role': 'system',
                'content':system_prompt
            },
            {

                'role':'user',
                'content':prompt
            }
        ]
        ,max_tokens=max_tokens,
        temperature=temperature,
        stream=stream
    )
    if stream:
        # 处理流式输出
        def generate():
            for chunk in response:
                if chunk.choices[0].delta.content is not None:
                    yield chunk.choices[0].delta.content
        return generate()
    else:
        # 处理非流式输出
        return response.choices[0].message.content
print("模型api调用成功！")
# # 非流式调用
# result = generate_response("你是谁")
# print(result)

# # 流式调用
# for chunk in generate_response(prompt="喜欢什么", stream=True):
#     print(chunk, end="", flush=True)


import random
from typing import Any, Callable, cast

import re
import sys
import json
import humanize

from pydantic import BaseModel

ExecCallbackType = Callable[[str, bool], ExecutionResult]

class Agent:
    def __init__(
        self,
        cfg,
        journal: Journal,
    ):
        super().__init__()
        self.cfg = cfg
        self.journal = journal
        self.data_preview: str | None = None

    def search_policy(self) -> Node | None:
        """Select a node to work on (or None to draft a new node)."""
        search_cfg = self.cfg.agent.search

        # initial drafting
        if len(self.journal.draft_nodes) < search_cfg.num_drafts:
            return None

        # debugging
        if random.random() < search_cfg.debug_prob:
            # nodes that are buggy + leaf nodes + debug depth < max debug depth
            debuggable_nodes = [
                n
                for n in self.journal.buggy_nodes
                if n.is_leaf
            ]
            if debuggable_nodes:
                return random.choice(debuggable_nodes)

        # back to drafting if no nodes to improve
        good_nodes = self.journal.good_nodes
        if not good_nodes:
            return None

        # greedy
        greedy_node = self.journal.get_best_node()

        return greedy_node

    def plan_and_code_query(self, system_message, user_message, retries=3) -> tuple[str, str]:
        """Generate a natural language plan + code in the same LLM call and split them apart."""
        completion_text = None
        for _ in range(retries):

            response = generate_response(
                prompt=user_message,
                system_prompt=system_message,
            )
            completion_text = response
            code = extract_code(completion_text)
            nl_text = extract_text_up_to_code(completion_text)

            if code:
                return nl_text, code

            print("Plan + code extraction failed, retrying...")
        print("Final plan + code extraction attempt failed, giving up...")
        return "", completion_text

    def _draft(self) -> Node:

        # ================ TODO: ask LLM agents to come up with a solution and then implement ================

        # system_prompt = "You are an AI agent."

        # user_prompt = [
        #     "You have to come up with a solution for machine learning task and then implement this solution in Python."
        #     f"The task is to {str(self.cfg.task_goal)} ",
        #     f'All the provided input data is stored in "{self.cfg.data_dir}" directory.',
        #     f"{str(self.data_preview)}",
        #     'You have to save the predictions result on testing set in "/content/submission.csv".',
        #     'Note that the testing file DOES NOT have the target column.'
        # ]
        system_prompt = """You are an expert AI agent specializing in time series prediction and data analysis.
You are running on Ubuntu 22.04.5 LTS with Python 3.11.
Your task is to develop a solution that predicts testing probabilities based on survey data.
You should:
1. Analyze the data structure and features
2. Design an appropriate model architecture
3. Implement the solution in Python
4. Ensure the code is well-documented and follows best practices
5. Save predictions to the specified output file

Focus on creating a robust solution that minimizes Mean Squared Error (MSE)."""

        user_prompt = [
            "Task: Develop a machine learning model to predict testing probabilities.",
            f"Goal: {str(self.cfg.task_goal)}",
            f"Data Location: {self.cfg.data_dir}",
            f"Data Overview:\n{str(self.data_preview)}",
            "Requirements:",
            "1. Save predictions to '/content/submission.csv'",
            "2. Note that the testing file DOES NOT have the target column",
            "3. Implement proper data preprocessing",
            "4. Use appropriate model selection and validation",
            "\nNeed to provide:",
            "1. A detailed plan explaining your approach",
            "2. Full Python implementation",
            "\nNote:",
            "1. Token limit is 8192.",
        ]
        system_message = system_prompt
        user_message = "\n".join(user_prompt)
        print(f'user_message: {user_message}')

        plan, code = self.plan_and_code_query(system_message=system_message, user_message=user_message)
        return Node(plan=plan, code=code)

    def _improve(self, parent_node: Node) -> Node:

        # ================  TODO: ask LLM agent to improve drafts ================

        # system_prompt = "You are an AI assistant."

        # user_prompt = [
        #     f"Task description: {str(self.cfg.task_goal)} "
        #     f"Memory: {str(self.journal.generate_summary())} "
        #     f"Previous solution: Code: {str(wrap_code(parent_node.code))} "
        # ]
        system_prompt = """You are an expert AI agent tasked with improving an existing prediction model.
You are running on Ubuntu 22.04.5 LTS with Python 3.11.
Your goal is to enhance the model's performance by:
1. Analyzing the current implementation
2. Identifying potential improvements
3. Implementing optimizations
4. Maintaining or improving code quality

Focus on reducing the Mean Squared Error (MSE) while keeping the solution practical and efficient."""

        user_prompt = [
            "Task: Improve the existing prediction model",
            f"Original Goal: {str(self.cfg.task_goal)}",
            "Previous Solutions:",
            f"{str(self.journal.generate_summary())}",
            "Current Implementation:",
            f"Code:\n{str(wrap_code(parent_node.code))}",
            "\nNeed to provide:",
            "1. Analysis of current implementation",
            "2. Specific improvement plan",
            "3. Enhanced implementation"
        ]
        system_message = system_prompt
        user_message = "\n".join(user_prompt)

        print(f'user_message: {user_message}')

        plan, code = self.plan_and_code_query(system_message=system_message, user_message=user_message)
        return Node(plan=plan, code=code, parent=parent_node)

    def _debug(self, parent_node: Node) -> Node:

        # ================  TODO: ask LLM agent to debug ================
        # system_prompt = "You are an AI agent."

        # user_prompt = [
        #     f"Task description: {str(self.cfg.task_goal)}\n\n",
        #     f"Previous (buggy) implementation: {str(wrap_code(parent_node.code))}\n\n",
        #     f"Execution output: {str(wrap_code(parent_node.term_out, lang=''))}\n\n",
        #     str(self.data_preview)
        # ]
        system_prompt = """You are an expert AI agent debugger specializing in machine learning code.
You are running on Ubuntu 22.04.5 LTS with Python 3.11.
Your task is to:
1. Analyze the error or issue in the current implementation
2. Identify the root cause
3. Propose and implement a fix
4. Ensure the solution maintains good performance

Focus on creating a robust fix that resolves the issue while maintaining or improving the model's performance."""

        user_prompt = [
            "Task: Debug and fix the prediction model",
            f"Original Goal: {str(self.cfg.task_goal)}",
            "Current Implementation:",
            f"Code:\n{str(wrap_code(parent_node.code))}",
            "Execution Output:",
            f"{str(wrap_code(parent_node.term_out, lang=''))}",
            "Data Context:",
            f"{str(self.data_preview)}",
            "\nNeed to provide:",
            "1. Analysis of the error/issue",
            "2. Root cause identification",
            "3. Proposed fix",
            "4. Corrected implementation"
        ]

        system_message = system_prompt
        user_message = "\n".join(user_prompt)
        print(f'user_message: {user_message}')

        plan, code = self.plan_and_code_query(system_message=system_message, user_message=user_message)
        return Node(plan=plan, code=code, parent=parent_node)

    def update_data_preview(
        self,
    ):
        self.data_preview = data_preview_generate(cfg.data_dir)

    def step(self, exec_callback: ExecCallbackType):
        if not self.journal.nodes or self.data_preview is None:
            self.update_data_preview()

        parent_node = self.search_policy()
        if parent_node is None:
            result_node = self._draft()
        elif parent_node.is_buggy:
            result_node = self._debug(parent_node)
        else:
            result_node = self._improve(parent_node)

        self.parse_exec_result(
            node=result_node,
            exec_result=exec_callback(result_node.code, True),
        )
        self.journal.append(result_node)

    def parse_exec_result(self, node: Node, exec_result: ExecutionResult):
        node.absorb_exec_result(exec_result)

        system_prompt = "You are an AI assistant. You are running on Ubuntu 22.04.5 LTS with Python 3.11."

        # ================  TODO: ask LLM agent to extract evaluation result from the execution output. ================
        # save log file
        # user_prompt = f"""
        #     The task is:
        #     {self.cfg.task_goal}

        #     The code implementation is:
        #     {wrap_code(node.code)}

        #     The execution output is:
        #     {wrap_code(node.term_out, lang="")}
        # """
        user_prompt = f"""
Task: Evaluate the prediction model implementation

Original Goal:
{self.cfg.task_goal}

Implementation:
{wrap_code(node.code)}

Execution Output:
{wrap_code(node.term_out, lang="")}

Need to provide a structured analysis including:
1. Execution Status (Success/Error)
2. Performance Metrics (especially MSE)
3. Issues or Concerns (if any)
4. Overall Assessment"""

        system_message = system_prompt
        # user_message = " ".join(user_prompt)
        user_message = user_prompt

        print(f'user_message: {user_message}')
        response = generate_response(
                prompt=user_message,
                system_prompt=system_message,
            )

        # ================  TODO: evaluation ================
        # you can force the LLM to structure the output to extract the metric
        # reference: https://python.useinstructor.com/integrations/llama-cpp-python/#llama-cpp-python
        # node.analysis = response.summary
        # node.is_buggy = (
        #     response.is_buggy
        #     or node.exc_type is not None
        #     or response.metric is None
        # )

        try:
            parsed_response = json.loads(response)
            node.analysis = parsed_response.get("assessment", "")
            node.metric = parsed_response["mse"] if parsed_response.get("mse") is not None else 0.0
            node.is_buggy = (
                parsed_response.get("execution_status", "Error") == "Error"
                or node.exc_type is not None
                or node.metric is None
            )
        except Exception as e:
            print("Failed to parse evaluation response:", e)
            node.analysis = "Failed to parse evaluation response."
            node.is_buggy = False
            node.metric = 0.0


# ================  TODO: config ================
config = {
    # experiment configurations
    "exp_name": "ML2025_HW2",
    "data_dir":  Path("./ML2025Spring-hw2-public").resolve(),

    # the description of the task
    "task_goal": "Given the survey results from the past two days in a specific state in the U.S.,\
                  predict the probability of testing positive on day 3. \
                  The evaluation metric is Mean Squared Error (MSE).",

    "agent": {
        # the number of iterations
        "steps": 5,
        "search": {
            # decide whether to debug or improve
            "debug_prob": 0.5,
            # the number of draft generated before improving/debugging
            "num_drafts": 5,
        },
    },
}

cfg = Config(config)

完整代码

https://github.com/hllqkb/ML2025Spring_HUNG_YI_LEE_Machine_Learning_Homework/blob/master/ML2025Spring-hw2/ML2025Spring_hw2_bossline.ipynb

根据下面的Baseline表

前往比赛提交并且查看我们的成绩

比赛链接

输出结果0.947

‼️ 目前仍难以获得可复现且稳定的结果。 ‼️

当然你想拿高分的话可以偷偷作弊一下，直接自己写一个，肯定比ai写的好

0.8300

best.py完整代码


# 引入必要模块
# 数据操作
import pandas as pd
import numpy as np
import math
import csv
import random
import os
from monai.utils import set_determinism
from torch.utils.data import Dataset, DataLoader
# 进度条
from tqdm import tqdm
# 特征选择
from sklearn.feature_selection import SelectKBest, f_regression
# pytorch
import torch
import torch.nn as nn
# 绘制图像
from torch.utils.tensorboard import SummaryWriter
# set random seed
def split_valid_set(data_set, valid_ratio, seed):
    np.random.seed(seed)
    indices = np.random.permutation(len(data_set))
    valid_size = int(len(data_set) * valid_ratio)
    valid_idx = indices[:valid_size]
    train_idx = indices[valid_size:]
    return data_set[train_idx], data_set[valid_idx]
def select_features(train_data,valid_data,test_data,select_all=True):
    # choose label
    y_train=train_data[:,-1]
    y_valid=valid_data[:,-1]
    # choose all features except label
    raw_x_train=train_data[:,:-1]
    raw_x_valid=valid_data[:,:-1]
    raw_x_test=test_data
    if select_all:
        feat_idx=list(range(raw_x_train.shape[1]))
        all_to_remove = {0}
        feat_idx = [x for x in feat_idx if x not in all_to_remove]

    else:
        # Feature selection
        feat_idx = [34, 35, 36, 43, 46, 47, 51, 52, 53,
                    54, 61, 64, 65, 69, 70, 71, 72, 79, 82, 83]
    return raw_x_train[:,feat_idx],raw_x_valid[:,feat_idx],raw_x_test[:,feat_idx],y_train,y_valid

class COVID19Dataset(Dataset):
    def __init__(self, features,target=None):
        if target is None:
            # predict
            self.target=target
        else:
            # train
            self.target = torch.FloatTensor(target)
        self.features = torch.FloatTensor(features)
    def __getitem__(self,idx):
        # idx means index of sample
        if self.target is None:
            return self.features[idx]
        else:
            return self.features[idx],self.target[idx]
    def __len__(self):
        return len(self.features)
# define model
class MyModel(nn.Module):
    def __init__(self, input_dim):
        super(MyModel, self).__init__()
        hidden_dims = config['layer']  # 如 [128, 64, 32]

        layers = []
        dims = [input_dim] + hidden_dims

        for in_dim, out_dim in zip(dims[:-1], dims[1:]):
            layers.append(nn.Linear(in_dim, out_dim))
            layers.append(nn.GELU())  # 更先进的激活函数

        # 可选：加入 Dropout 或 BatchNorm 以提升泛化能力
        # layers.append(nn.Dropout(0.2))

        layers.append(nn.Linear(dims[-1], 1))  # 输出层：无激活

        self.layers = nn.Sequential(*layers)

    def forward(self, x):
        x = self.layers(x)
        return x.squeeze(1)  # 输出 (B)
# Set CFG
device=torch.device('cuda' if torch.cuda.is_available() else 'cpu')
config={
    'layer': [128, 64, 32],
    'k':20,
    'seed': 3407,
    'select_all': False,
    'normalize': True,
    'batch_size': 128,
    'lr': 0.00035099698616997447,
    'n_epochs': 20000,
    'valid_ratio': 0.2,
    'early_stop': 400,
    'save_path': './models/model.ckpt',
    'beta1': 0.95,  # β₁
    'eps': 1e-7,  # ϵ
}

# train
def train(train_loader,valid_loader,model,config,device):
    criterion=nn.MSELoss()
    optimizer = torch.optim.Adam(
    model.parameters(),
    lr=config['lr'],
    betas=(config['beta1'], 0.999),  # 调整 β₁
    eps=config['eps'],               # 调整 ϵ
    # weight_decay=0  # 可选：是否加入 L2 正则化
)
    writer=SummaryWriter()
    best_loss=math.inf
    early_stop_count=0
    step=0
    for epoch in range(config['n_epochs']):
        loss_record=[]
        model.train()
        train_bar=tqdm(train_loader)
        for x,y in train_bar:
            x,y=x.to(device),y.to(device)
            optimizer.zero_grad()
            outputs=model(x)
            loss=criterion(outputs,y)
            loss.backward()
            optimizer.step()
            loss_record.append(loss.detach().item())
            step+=1
        # validate
        model.eval()
        valid_loss_record=[]
        valid_bar=tqdm(valid_loader)
        for x,y in valid_bar:
            x,y=x.to(device),y.to(device)
            with torch.no_grad():
                outputs=model(x)
                loss=criterion(outputs,y)
                valid_loss_record.append(loss.detach().item())
        valid_loss=np.mean(valid_loss_record)
        writer.add_scalar('valid_loss',valid_loss,step)
        # save best model
        if valid_loss=config['early_stop']:
            return best_loss
    return best_loss
# set same seed
set_determinism(seed=config['seed'])

# 读取数据（保留 DataFrame 或 NumPy）
train_data = pd.read_csv('./ML2025Spring-hw2-public/train.csv').values
test_data = pd.read_csv('./ML2025Spring-hw2-public/test.csv').values

# 切分数据（不转成 Subset）
train_data, valid_data = split_valid_set(train_data, config['valid_ratio'], config['seed'])

# 检查标签是否有 NaN
if np.isnan(train_data[:, -1]).sum() > 0 or np.isnan(valid_data[:, -1]).sum() > 0:
    raise ValueError("Labels contain NaN values. Please check your data.")
# Normalization with Min-Max scaling 可以加一个点
if config['normalize']:
    train_min = np.min(train_data[:, 35:-1], axis=0)  # 计算每列最小值
    train_max = np.max(train_data[:, 35:-1], axis=0)  # 计算每列最大值
    # 防止除以0的情况，可以加一个很小的数
    epsilon = 1e-8
    train_range = train_max - train_min + epsilon
    # 归一化训练集
    train_data[:, 35:-1] = (train_data[:, 35:-1] - train_min) / train_range
    # 用相同的min和range归一化验证集
    valid_data[:, 35:-1] = (valid_data[:, 35:-1] - train_min) / train_range
    # 用相同的min和range归一化测试集
    test_data[:, 35:] = (test_data[:, 35:] - train_min) / train_range
x_train,x_valid,x_test,y_train,y_valid=select_features(train_data,valid_data,test_data,config['select_all'])
# convert to tensor
train_dataset=COVID19Dataset(x_train,y_train)
valid_dataset=COVID19Dataset(x_valid,y_valid)
test_dataset=COVID19Dataset(x_test)
# pin memory能保存数据到GPU的高速缓存中，能加快数据加载速度,shuffle=True表示每个epoch打乱数据
train_loader=DataLoader(train_dataset,batch_size=config['batch_size'],shuffle=True,pin_memory=True)
valid_loader=DataLoader(valid_dataset,batch_size=config['batch_size'],shuffle=True,pin_memory=True)
test_loader=DataLoader(test_dataset,batch_size=config['batch_size'],shuffle=False,pin_memory=True)
# create model
model=MyModel(input_dim=x_train.shape[1]).to(device)

# train

print('Training model...')
best_loss=train(train_loader,valid_loader,model,config,device)
print(f'Best validation loss: {best_loss:.3f}')
def predict(test_loader,model,device):
    model.eval()
    preds=[]
    with torch.no_grad():
        for x in tqdm(test_loader):
            x=x.to(device)
            outputs=model(x)
            # 把数据从GPU转移到CPU，才能转换为numpy数组
            preds.append(outputs.detach().cpu())
    preds = torch.cat(preds, dim=0).numpy()
    return preds
# predict
predictions=predict(test_loader,model,device)
# save predictions
def save_pred(preds, file):
    ''' Save predictions to specified file '''
    with open(file, 'w') as fp:
        writer = csv.writer(fp)
        writer.writerow(['id', 'tested_positive'])
        for i, p in enumerate(preds):
            writer.writerow([i, p])
save_pred(predictions, './predictions.csv')
print('Predictions saved in ./predictions.csv')

代码库：https://github.com/hllqkb/ML2025Spring_HUNG_YI_LEE_Machine_Learning_Homework

ML2025 Homework 1 基于Agent系统的检索增强生成技术 Retrieval Augmented Generation with Agentic System

Thu, 21 Aug 2025 00:00:00 GMT

什么是RAG

Retrieval augmeted generation (RAG)是一种方法允许llm使用外部知识回答问题

关于RAG的概念不多概述

什么是代理系统

代理系统是一个框架，其中LLM作为个体并合作完成复杂的任务

结果如图

Task Overview

RAG with

Agentic

System

The goal of HW1 is building an RAG system with agents

要构建rag系统这个在baseline已经完成了

TODOs

Learn how an RAG system operates.

Design the prompts for agents to solve some tasks.

Submit your code to NTU COOL and submit your results to JudgeBoi

这是要做的TODOs

不过无法提交到JudgeBoi了结果，但是可以直接自己用gpt4o验证正确性

Dataset

There are 90 hand-crafted questions.

The answers to these questions are a word or a phrase.

The dataset contains two parts: public and private

关于数据集的描述，有public.txt和private.txt，public有答案,private没有答案

由于无法提交评分，我们这里直接实现hint就行了

Hints

Please note that the following hints are just for your reference. You are not required to follow

them. And you are not guaranteed to beat the baselines by simply following them.

For the simple baseline, you don’t need to do anything. Directly feed the questions to

the LLM. (Just run the sample code!)

For the medium baseline, you will need to integrate the search tool into your system.

The search tool has already been implemented in the sample code. You need to

integrate it into your pipeline

让我们来实现这个架构并且实现web搜索和rag和使用能调用huggingface的模型

关键改进

移除Meta-Llama-3.1-8B-Instruct-Q8_0.gguf和相关依赖，因为这个模型使用rag实在是太过复杂了，选择了别的模型


!python3 -m pip install googlesearch-python bs4 charset-normalizer requests-html lxml_html_clean

from pathlib import Path
if not Path('./public.txt').exists():
    !wget https://www.csie.ntu.edu.tw/~ulin/public.txt
if not Path('./private.txt').exists():
    !wget https://www.csie.ntu.edu.tw/~ulin/private.txt

搜索代码改进，使用博查ai搜索，最后测试ai搜索没什么用对于一个问句，或者关键词搜索，更别提web爬虫搜索相关信息用google or bing,要实现一个完善的ai搜索比较复杂，调用api也没有好的效果，建议使用一些开源项目或者别的api可以取得更好效果


from typing import List
from googlesearch import search as _search
from bs4 import BeautifulSoup
from charset_normalizer import detect
import asyncio
from requests_html import AsyncHTMLSession
import urllib3
urllib3.disable_warnings()

async def worker(s:AsyncHTMLSession, url:str):
    try:
        header_response = await asyncio.wait_for(s.head(url, verify=False), timeout=10)
        if 'text/html' not in header_response.headers.get('Content-Type', ''):
            return None
        r = await asyncio.wait_for(s.get(url, verify=False), timeout=10)
        return r.text
    except:
        return None
from typing import List
from requests_html import AsyncHTMLSession
from bs4 import BeautifulSoup
from charset_normalizer import detect
import asyncio
import requests
import json
import urllib.parse
import re
import urllib3
urllib3.disable_warnings()

async def fetch_html(s: AsyncHTMLSession, url: str) -> str | None:
    try:
        r = await asyncio.wait_for(s.get(url, verify=False), timeout=10)
        if 'text/html' not in r.headers.get('Content-Type', ''):
            return None
        return r.text
    except:
        return None

async def get_htmls(urls: List[str]) -> List[str]:
    session = AsyncHTMLSession()
    tasks = [fetch_html(session, url) for url in urls]
    return await asyncio.gather(*tasks)

async def search(keyword: str, n_results: int = 3) -> List[str]:

    url = "https://api.bochaai.com/v1/ai-search"
    headers = {
        'Authorization': 'Bearer 你的key',
        'Content-Type': 'application/json'
    }
    payload = {
        "query": keyword,
        "freshness": "oneYear",
        "summary": True,
        "count": n_results
    }
    response = requests.post(url, headers=headers, json=payload)
    response_json= response.json()
    result=[]
    for message in response_json['messages']:
        result.append(message['content'])
    return result

定义agent字典，为啥要这样做，因为无法使用LLMAgent


# 定义agents字典
agents = {
    "question_extraction_agent": {
        "role_description": "你是一個專門負責問題過濾的 AI 助手，能從輸入中識別出與問題相關的核心描述，去除掉無關或冗餘的內容。",
        "task_description": "請從以下輸入中篩選並保留與問題相關的部分，刪除與問題無關的句子或細節："
    },
    "keyword_extraction_agent": {
        "role_description": "你是一個關鍵詞提取助手，能從問題中找出最重要的詞彙與短語，幫助搜尋工具更準確地找到答案。",
        "task_description": "請從以下問題中抽取最能代表問題核心的關鍵詞或短語，並以逗號分隔："
    }
}

# 调用示例
def call_agent(agent_name, input_text):
    agent = agents.get(agent_name)
    return agent['role_description']+agent['task_description']+input_text

# 使用question_extraction_agent处理问题
result1 = call_agent("question_extraction_agent", "我想知道如何学习Python，顺便问一下今天天气怎么样？")
print(result1)

# 使用keyword_extraction_agent提取关键词
result2 = call_agent("keyword_extraction_agent", "学习Python的最佳方法是什么？")
print(result2)

使用嵌入模型


from langchain_huggingface import HuggingFaceEmbeddings

# 指定要加载的预训练模型的名称，参考排行榜：https://huggingface.co/spaces/mteb/leaderboard
model_name = "chuxin-llm/Chuxin-Embedding"

# 创建 Hugging Face 的嵌入模型实例，这个模型将用于将文本转换为向量表示（embedding）
embedding_model = HuggingFaceEmbeddings(model_name=model_name)

# # 打印嵌入模型的配置信息，显示模型结构和其他相关参数
# print(embedding_model)

# # embed_query() 方法会将文本转换为嵌入的向量
# query_embedding = embedding_model.embed_query("Hello")

# # 打印生成的嵌入向量的长度，向量长度应与模型的输出维度一致（这里是 1024），你也可以选择打印向量看看
# print(f"嵌入向量的维度为: {len(query_embedding)}")


# 直接保存搜索的结果的嵌入的相关函数
from langchain.vectorstores import FAISS
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.docstore.document import Document
import numpy as np
import os

text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=100,  # 尝试调整它
    chunk_overlap=10,  # 尝试调整它
    #length_function=len,  # 可以省略
    # separators=["\n\n", "\n", " ", "。", ""]  # 可以省略
)

def build_faiss_index(texts):
    # 添加public.txt的内容到知识库里面
        # 读取并预处理public.txt
    with open("./public.txt", 'r', encoding='utf-8') as f:
        public_text = f.read()

    # 先将public_text分块
    public_docs = text_splitter.split_documents([Document(page_content=public_text)])
    # 保存和加载向量数据库
    # 把文本列表转化为文档列表
    document=[Document(page_content=text) for text in texts]
    # 使用预训练嵌入模型生成向量并创建向量数据库
    docs = text_splitter.split_documents(document)
        # 合并文档
    all_docs = docs + public_docs
    # 创建向量数据库
    vectorstore = FAISS.from_documents(all_docs, embedding_model)
    # 创建检索器
    retriever = vectorstore.as_retriever(search_kwargs={"k": 3})

    return vectorstore,retriever

剩下代码不一一概述了

完整代码：https://github.com/hllqkb/ML2025Spring_HUNG_YI_LEE_Machine_Learning_Homework/blob/master/ML2025Spring-hw1/mlhw1-bossline.ipynb

最后输出


问题过滤结果: 你是一個專門負責問題過濾的 AI 助手，能從輸入中識別出與問題相關的核心描述，去除掉無關或冗餘的內容。請從以下輸入中篩選並保留與問題相關的部分，刪除與問題無關的句子或細節：校歌為學校（包括小學、中學、大學等）宣告或者規定的代表該校的歌曲。用於體現該校的治學理念、辦學理想等學校文化。「虎山雄風飛揚」是哪間學校的校歌歌詞？

虎山雄風飛揚是哪間學校的校歌歌詞？

(去除： 校歌為學校（包括小學、中學、大學等）宣告或者規定的代表該校的歌曲。用於體現該校的治學理念、辦學理想等學校文化。)
提取的关键词: 你是一個關鍵詞提取助手，能從問題中找出最重要的詞彙與短語，幫助搜尋工具更準確地找到答案。請從以下問題中抽取最能代表問題核心的關鍵詞或短語，並以逗號分隔：校歌為學校（包括小學、中學、大學等）宣告或者規定的代表該校的歌曲。用於體現該校的治學理念、辦學理想等學校文化。「虎山雄風飛揚」是哪間學校的校歌歌詞？

虎山、雄風、飛揚、校歌、歌詞、學校、宣告、規定、治學、辦學、理念、理想、學校文化
检索到 3 篇相关文档
最终输入内容已拼接完成
生成式模型已完成回答
最终回答: 問題: 你是一個專門負責問題過濾的 AI 助手，能從輸入中識別出與問題相關的核心描述，去除掉無關或冗餘的內容。請從以下輸入中篩選並保留與問題相關的部分，刪除與問題無關的句子或細節：校歌為學校（包括小學、中學、大學等）宣告或者規定的代表該校的歌曲。用於體現該校的治學理念、辦學理想等學校文化。「虎山雄風飛揚」是哪間學校的校歌歌詞？

虎山雄風飛揚是哪間學校的校歌歌詞？

(去除： 校歌為學校（包括小學、中學、大學等）宣告或者規定的代表該校的歌曲。用於體現該校的治學理念、辦學理想等學校文化。)
關鍵詞: 你是一個關鍵詞提取助手，能從問題中找出最重要的詞彙與短語，幫助搜尋工具更準確地找到答案。請從以下問題中抽取最能代表問題核心的關鍵詞或短語，並以逗號分隔：校歌為學校（包括小學、中學、大學等）宣告或者規定的代表該校的歌曲。用於體現該校的治學理念、辦學理想等學校文化。「虎山雄風飛揚」是哪間學校的校歌歌詞？

虎山、雄風、飛揚、校歌、歌詞、學校、宣告、規定、治學、辦學、理念、理想、學校文化

相關文檔:
校歌為學校（包括小學、中學、大學等）宣告或者規定的代表該校的歌曲。用於體現該校的治學理念、辦學理想等學校文化。「虎山雄風飛揚」是哪間學校的校歌歌詞？,光華國小
「如果你朋友唱歌沒有跑調，一定是他的伴侶跑掉了」是一句用來形容失戀之人唱歌模樣的網路笑話。「短暫交會的旅程就此分岔」是哪個歌唱團體歌曲中的歌詞？,動力火車
无

請基於以上內容回答問題： 虎山雄風飛揚是哪間學校的校歌歌詞？

虎山雄風飛揚是光華國小的校歌歌詞。
問題: 你是一個專門負責問題過濾的 AI 助手，能從輸入中識別出與問題相關的核心描述，去除掉無關或冗餘的內容。請從以下輸入中篩選並保留與問題相關的部分，刪除與問題無關的句子或細節：校歌為學校（包括小學、中學、大學等）宣告或者規定的代表該校的歌曲。用於體現該校的治學理念、辦學理想等學校文化。「虎山雄風飛揚」是哪間學校的校歌歌詞？

虎山雄風飛揚是哪間學校的校歌歌詞？

(去除： 校歌為學校（包括小學、中學、大學等）宣告或者規定的代表該校的歌曲。用於體現該校的治學理念、辦學理想等學校文化。)
關鍵詞: 你是一個關鍵詞提取助手，能從問題中找出最重要的詞彙與短語，幫助搜尋工具更準確地找到答案。請從以下問題中抽取最能代表問題核心的關鍵詞或短語，並以逗號分隔：校歌為學校（包括小學、中學、大學等）宣告或者規定的代表該校的歌曲。用於體現該校的治學理念、辦學理想等學校文化。「虎山雄風飛揚」是哪間學校的校歌歌詞？

虎山、雄風、飛揚、校歌、歌詞、學校、宣告、規定、治學、辦學、理念、理想、學校文化

相關文檔:
校歌為學校（包括小學、中學、大學等）宣告或者規定的代表該校的歌曲。用於體現該校的治學理念、辦學理想等學校文化。「虎山雄風飛揚」是哪間學校的校歌歌詞？,光華國小
「如果你朋友唱歌沒有跑調，一定是他的伴侶跑掉了」是一句用來形容失戀之人唱歌模樣的網路笑話。「短暫交會的旅程就此分岔」是哪個歌唱團體歌曲中的歌詞？,動力火車
无

請基於以上內容回答問題： 虎山雄風飛揚是哪間學校的校歌歌詞？

虎山雄風飛揚是光華國小的校歌歌詞。


請基於以上內容回答問題：
NCC 規定每案加收審查費多少錢？

NCC 規定每案加收審查費 750 元。

手写MNIST数字识别底层实现

Wed, 20 Aug 2025 00:00:00 GMT

mnist已经写了很多遍了，这次再全部从零底层实现一遍，顺便附上具体原理

数字识别就是个分类问题，神经网络可以用于回归任务和分类任务，回归问题用恒等函数，分类问题用softmax函数。

什么是softmax函数：

这个函数就是，我们代码实现


def softmax(x):
    """
    计算softmax函数
    """
    return np.exp(x) / np.sum(np.exp(x), axis=0)

正常输出


print(softmax(np.array([1, 2, 3])))


[0.09003057 0.24472847 0.66524096]


print(softmax(np.array([1010, 2000, 3000])))

我们试一试大数运行函数输出


[nan nan nan]

上面的softmax函数的实现虽然正确描述了式子，但在计算机的运算

上有一定的缺陷。这个缺陷就是溢出问题。softmax函数的实现中要进行指

数函数的运算，但是此时指数函数的值很容易变得非常大。比如，e^10的值

会超过20000，e^100会变成一个后面有40多个0的超大值，

e^1000的结果会返回一个表示无穷大的inf。如果在这些超大值之间进行除法运算，结果会出现“不确定”的情况

我们可以改进函数,通过减去输入信号中的最大值（上例中的c），我们发现原

本为nan（not a number，不确定）的地方，现在被正确计算了。


def softmax(x):
    """
    计算softmax函数，解决溢出问题
    """
    x = x - np.max(x)
    exp_x = np.exp(x)
    return exp_x / np.sum(exp_x)
print(softmax(np.array([1010, 1000, 990])))

最终得到正常结果


[9.99954600e-01 4.53978686e-05 2.06106005e-09]

softmax函数的输出是0.0到1.0之间的实数。并且，softmax

函数的输出值的总和是1。输出总和为1是softmax函数的一个重要性质。正

因为有了这个性质，我们才可以把softmax函数的输出解释为‘概率’

输出层的神经元数量

输出层的神经元数量需要根据待解决的问题来决定。对于分类问题，输

出层的神经元数量一般设定为类别的数量。比如，对于某个输入图像，预测

是图中的数字0到9中的哪一个的问题（10类别分类问题），

所以我们将输出层的神经元设定为10个

介绍完神经网络的结构之后，现在我们来试着解决实际问题。这里我们

来进行手写数字图像的分类。假设学习已经全部结束，我们使用学习到的参

数，先实现神经网络的“

推理

处理”。这个推理处理也称为神经网络的**前向

传播（forward propagation）**。

MNIST数据集

这里使用的数据集是MNIST手写数字图像集。MNIST是

机器学习

领域

最有名的数据集之一，被应用于从简单的实验到发表的论文研究等各种场合。

实际上，在阅读图像识别或机器学习的论文时，MNIST数据集经常作为实

验用的数据出现。

MNIST数据集是由0到9的数字图像构成的。训练图像有6万张，

测试图像有1万张，这些图像可以用于学习和推理。MNIST数据集的一般

使用方法是，先用训练图像进行学习，再用学习到的模型度量能在多大程度

上对测试图像进行正确的分类

NIST的图像数据是28像素 × 28像素的灰度图像（1通道），各个像素

的取值在0到255之间。每个图像数据都相应地标有“7”“2”“1”等标签

了解上面的知识差不多可以直接手写实现了

代码实现


import torch
from torchvision import datasets, transforms
from torch.utils.data import DataLoader
# 数据预处理：归一化
transform = transforms.Compose([
transforms.ToTensor(),
transforms.Normalize((0.1307,), (0.3081,))
])

# 加载训练集和测试集
train_dataset = datasets.MNIST(root='./data', train=True, download=True, transform=transform)
test_dataset = datasets.MNIST(root='./data', train=False, download=True, transform=transform)
# 加载训练集和测试集的DataLoader,每次加载64个样本,train_loader的shuffle参数设为True表示每次迭代时都打乱数据
train_loader = DataLoader(train_dataset, batch_size=64, shuffle=True)
test_loader = DataLoader(test_dataset, batch_size=64, shuffle=False)

展示MNIST数据集


# 查看shape和图片
from matplotlib import pyplot as plt
print(train_dataset.train_data.shape)
fig=plt.figure()
for i in range(12):
    # 创建一个 3×4 的网格，共 12 个子图
    plt.subplot(3,4,i+1)
    # 自动调整子图之间的间距和边距
    plt.tight_layout()
    # 显示图片 ，'gray' 表示灰度图
    plt.imshow(train_dataset.train_data[i], cmap='gray')
    # 不显示x,y刻度
    plt.xticks([])
    plt.yticks([])
    # 设置标题
    plt.title(f'Label: {train_dataset.train_labels[i]}')
# 显示图片
plt.show()

定义神经网络

了解这个神经网络的组成

1.首先用到了一个二维卷积层,卷积原理如图

torch.nn.Conv2d(in_channels, out_channels, kernel_size, stride, padding)

参数：

in_channels：输入通道

out_channels：输出通道

kernel_size：卷积核大小

stride：步长

padding：填充

2.激活层使用ReLU激活函数。

torch.nn.ReLU()

要手动实现也是很简单


def ReLU(x):
    return np.maximum(0, x)

3 池化层请添加图片描述

池化原理

torch.nn.MaxPool2d(input, kernel_size, stride, padding)

这些参数上文已经说明

4 全连接层

self.fc1 = nn.Linear(64 * 7 * 7, 128)

self.fc2 = nn.Linear(128, 10)

作用

维度转换：从空间特征到分类决策

输入处理：

卷积层输出的四维张量 (B, C, W, H)（批大小、通道数、宽、高）通过 view 或 flatten 操作被展平为二维张量 (B, C*W*H)，即将空间和通道信息合并为一维特征向量。

例如：若卷积层输出为 (64, 128, 7, 7)，展平后为 (64, 128 * 7 * 7=6272)。

输出映射：

全连接层通过权重矩阵将高维特征映射到目标维度（如分类类别数）。例如，输入 6272 维特征可通过全连接层输出 (64, 10)（10分类任务）。

好的，我们已经了解了大概的结构组成

接下来我们根据结构图来实现代码

神经网络的代码实现


import torch.nn as nn
import torch.nn.functional as F

# 定义一个简单的卷积神经网络（CNN），用于图像分类
class CNN(nn.Module):
    def __init__(self):
        super(CNN, self).__init__()
        # 第一层卷积：输入通道 1（灰度图），输出通道 32，卷积核大小 5x5，padding=2 保持尺寸不变
        self.conv1 = nn.Conv2d(1, 32, kernel_size=5, padding=2)
        # 第二层卷积：输入通道 32，输出通道 64，卷积核大小 5x5，同样 padding=2
        self.conv2 = nn.Conv2d(32, 64, kernel_size=5, padding=2)
        # 最大池化层，窗口大小 2x2，相当于下采样一半
        self.pool = nn.MaxPool2d(2)
        # 全连接层 1：输入 64*7*7 个特征，输出 128 个神经元
        self.fc1 = nn.Linear(64 * 7 * 7, 128)
        # 全连接层 2：输入 128，输出 10（对应 10 个类别，比如 MNIST）
        self.fc2 = nn.Linear(128, 10)

    def forward(self, x):
        # 第一次卷积 -> ReLU 激活 -> 池化
        x = F.relu(self.pool(self.conv1(x)))
        # 第二次卷积 -> ReLU 激活 -> 池化
        x = F.relu(self.pool(self.conv2(x)))
        # 将特征图展平成一维向量，方便送入全连接层
        x = x.view(-1, 64 * 7 * 7)  # -1 表示自动计算 batch size
        # 第一个全连接层 + ReLU
        x = F.relu(self.fc1(x))
        # 第二个全连接层，输出 10 类
        x = self.fc2(x)
        return x

# 实例化模型
model = CNN()

定义

损失函数

和优化器

使用交叉熵损失函数和

Adam优化器

：


import torch.optim as optim
# 交叉熵损失函数用于分类问题
criterion = nn.CrossEntropyLoss()
# Adam优化器
optimizer = optim.Adam(model.parameters(), lr=0.001)

模型训练

定义训练过程：


from tqdm import tqdm  # 用于显示进度条

def train_model(model, train_loader, optimizer, criterion, epochs=10):
    """
    训练模型函数
    参数:
        model: 神经网络模型
        train_loader: 训练数据 DataLoader
        optimizer: 优化器 (如 Adam, SGD)
        criterion: 损失函数 (如 CrossEntropyLoss)
        epochs: 训练轮数
    """
    model.train()  # 设置为训练模式（启用 dropout、BN 等）

    for epoch in range(epochs):  # 外层循环：共训练 epochs 轮
        running_loss = 0.0  # 记录一个 epoch 内的累计 loss

        # tqdm 用于显示进度条，每个 batch 迭代时会实时刷新
        progress_bar = tqdm(train_loader, desc=f"Epoch {epoch+1}/{epochs}", leave=False)

        for images, labels in progress_bar:
            # 梯度清零（防止梯度累积）
            optimizer.zero_grad()

            # 前向传播
            outputs = model(images)

            # 计算损失
            loss = criterion(outputs, labels)

            # 反向传播
            loss.backward()

            # 参数更新
            optimizer.step()

            # 累加损失，用于 epoch 统计
            running_loss += loss.item()

            # tqdm 实时显示当前 batch 的 loss
            progress_bar.set_postfix({"Batch Loss": f"{loss.item():.4f}"})

        # 一个 epoch 结束后，计算平均损失
        avg_loss = running_loss / len(train_loader)
        print(f"Epoch [{epoch+1}/{epochs}] - Average Loss: {avg_loss:.4f}")

模型测试

定义测试过程并计算准确率：


def test_model(model, test_loader):
    """
    测试模型函数
    参数:
        model: 已训练好的神经网络模型
        test_loader: 测试数据 DataLoader
    """
    model.eval()  # 设置为评估模式（关闭 dropout、BN 等）
    correct = 0   # 预测正确的样本数
    total = 0     # 总样本数

    # 测试时不需要计算梯度，节省显存和加速
    with torch.no_grad():
        # tqdm 进度条显示测试进度
        for images, labels in tqdm(test_loader, desc="Testing", leave=False):
            # 前向传播
            outputs = model(images)

            # 取概率最大的类别作为预测结果
            _, predicted = torch.max(outputs.data, 1)

            # 累加总数和正确数
            total += labels.size(0)
            correct += (predicted == labels).sum().item()

    # 计算总体准确率
    accuracy = 100 * correct / total
    print(f"Test Accuracy: {accuracy:.2f}%")

开始训练与测试

运行训练和测试：


if __name__ == "__main__":
	train_model(model, train_loader,optimizer,criterion,epochs=10)
	test_model(model, test_loader)

输出



Epoch [1/10] - Average Loss: 0.0391

Epoch [2/10] - Average Loss: 0.0239

Epoch [3/10] - Average Loss: 0.0176

Epoch [4/10] - Average Loss: 0.0134

Epoch [5/10] - Average Loss: 0.0105

Epoch [6/10] - Average Loss: 0.0102

Epoch [7/10] - Average Loss: 0.0085

Epoch [8/10] - Average Loss: 0.0069

Epoch [9/10] - Average Loss: 0.0058

Epoch [10/10] - Average Loss: 0.0084

Test Accuracy: 99.19%

进行预测


import torch
from torchvision import transforms
from PIL import Image

def predict_image(model, image_path, class_names, transform=None, device="cpu"):
    model.eval()  # 评估模式
    model.to(device) # 移动到指定设备

    # 打开图片
    image = Image.open(image_path).convert("L")  # 转灰度 (1 通道)，如果是彩色就改成 "RGB"

    # 预处理
    if transform is not None:
        image = transform(image)
    else:
        # 默认 transform: 转 tensor + 标准化
        image = transforms.ToTensor()(image)

    # 增加 batch 维度: [1, C, H, W]
    image = image.unsqueeze(0).to(device)

    with torch.no_grad():
        # 输出预测结果 tensor
        outputs = model(image)
        # softmax 归一化
        probs = torch.softmax(outputs, dim=1).cpu().numpy()  # 转成 NumPy
        print(f"Probabilities: {probs.round(3)}")  # 打印并保留3位小数
        _, predicted = torch.max(outputs, 1)  # 获取预测类别索引

    predicted_class = class_names[predicted.item()]
    print(f"Predicted Class: {predicted_class}")
    return predicted_class


# 定义类别
class_names = [str(i) for i in range(10)]  # 如果是MNIST: 0~9

# 单张图片预测
predict_image(model, "../3.jpg", class_names, transform, device="cuda")

输出结果


Probabilities: [[0.001 0.047 0.027 0.831 0.002 0.049 0.002 0.026 0.009 0.006]]
Predicted Class: 3