GitHub
快来分享你的内容吧～
- 09-20 10:42·后端最近把自己开源的 重构了一遍。 做这个 Skill 的原因一直没变。 现在用 Codex、Claude Code 做项目，写代码已经越来越省事。问题慢慢跑到了另外一边：项目做久以后，Agent 开始忘，文档开始乱，方案改过几轮没人记得，代码写完了也不知查看全文加油鸭：太棒了！把项目状态管理得这么清晰又实用，这份重构思路既有深度又超接地气，为 Vibe Coding 项目提供了真正可持续的协作骨架！91013分享
- 09-19 20:10·后端
09-13 12:41·Node.js后端我是如何学习大模型应用开发的 大模型应用开发的一些概念关系 !image 1.png 上面整理出来的是我自己对于大模型应用开发的理解，也结合了一些技术和概念的变化时间线，仅供各位朋友参考，不一定准确，我觉得大模型应用开发最重要的是这三个东西：Agent Loop、Context Engineering、Harness Engineering 最近好像又新出了很多层的概念，在harness engi查看全文豆芽和面包：好文，收藏了。另外我非常羡慕大家，有大把时间学习，我不是计算机专业的，而且已经工作10年了，想转行AI，我现在满腔热血，但最大的问题是没有时间（如果结婚并且有小孩的，家里没老人带娃的，都应该明白我的困境），每天只能挤出最多2小时，还得熬夜到1~2点。538119分享
09-12 15:36·后端开发大家好，我是不会喷火的小火龙。今天我们来拆解一个最近频繁登上GitHub趋势榜开源的多智能体金融量化交易全流程框架。 在平常让大模型直接分析股票，往往会得到一份四平八稳的研报。但在真实交易里，单向叙事暗藏风险：只要挑选不同的技术指标或新闻切片，无论看多还是看空都能写出逻辑自洽的分析。金融决策要在信息不对称下权衡概率与风险，并不存在现成的标准答案。 一、为什么单一 Prompt 难以胜任金融决策 用查看全文加油鸭：太惊艳了！把投研组织逻辑完美复刻成多智能体系统，每个角色分工清晰、对抗有力，还自带反思闭环——这才是AI真正赋能专业决策的样子！734分享
08-07 07:57·前端开发- 07-29 17:16·后端大家好，我是汉堡。 上一篇文章《如何从0到1 Vibe Coding 一个项目，并长期维护》里，我分享了自己踩坑之后沉淀出来的一套 Harness 体系——用文档治理、AGENTS.md、范围冻结和分阶段推进来驯服 Vibe Coding 的混乱。查看全文加油鸭：把方法论沉淀成可复用的 Skill 太棒了！文档驱动 + 阶段治理，真正让 Vibe Coding 有了工程骨架，为你点赞！141025分享
- 07-17 16:18·后端开发
- 07-16 15:36·后端
07-05 02:35·后端最近写了个 Python 练手项目，本地跑得挺顺，盘算着发到 PyPI 上，让别人也能一行 就用起来。本来以为 + 就完事了，结果一脚踩进 GitHub Actions 的世界，从 CI 配置到 Trusted Publisher 认证，从 Poetry 依赖解析到版本号踩坑，一路上“惊吓”不断。折腾了一晚上，才把整条链路跑通。谨以此文，纪念熬的又一个夜——不算什么高深教程，但每个坑都是实打实踩过查看全文加油鸭：太棒了！从踩坑到打通全链路，这份实战笔记干货满满，真诚又实用，为你的坚持和分享点赞！531分享
Project Vibe Spec 大升级：我想解决 Vibe Coding 项目越写越乱的问题
> 开源地址：[github.com/dnwwdwd/project-vibe-spec](https://github.com/dnwwdwd/project-vibe-spec)如果对你有用，GitHub 上点个 Star 是最实在的支持 ⭐ 最近把自己开源的 `project-vibe-spec` 重构了一遍。 做这个 Skill 的原因一直没变。 现在用 Codex、Claude Code 做项目，写代码已经越来越省事。问题慢慢跑到了另外一边：项目做久以后，Agent 开始忘，文档开始乱，方案改过几轮没人记得，代码写完了也不知道到底验证到什么程度。 这种问题对 Vibe Coding 用户影响尤其大。 很多人不会逐行 Review 代码，我自己做一些项目时也不会每次把几百上千行 diff 从头看到尾。我更容易确认的是页面有没有做对、流程是不是我想要的、数据语义有没有问题、最后能不能跑。 一旦项目做几个月，光靠聊天记录就撑不住了。 这一轮 Agent 记得为什么这么改，换个 Session 可能就不知道了。PRD 还写着旧方案，代码已经跑到第三版。某个功能之前只做了 POC，过几轮以后 Agent 开始把它当成正式能力。数据库里多了一张表，几个月后没人知道当时为什么拆。 还有一种很常见。Agent 改完代码以后直接告诉你"已完成"，结果测试没跑，UI 没打开，migration 没验证，Windows 也没测。 我之前写 `project-vibe-spec`，主要就是在补这些东西。 ## 旧版已经能管需求，但有点重 之前的 Project Vibe Spec 已经有一套比较完整的流程。 一个需求进来以后，会经过需求确认、REQ、方案决策、实现、测试、Progress 更新。数据库、migration、权限、安全、公开 API 这种不太好回退的改动，还要求先讨论方案，再让 Agent 动代码。 这套流程用了以后，项目确实没那么容易失控。 但它自己也慢慢长胖了。 `SKILL.md` 里面要规定需求怎么分类、什么算跨模块、什么时候建 REQ、什么时候写 DEC、数据库什么时候要确认、Progress 怎么更新、哪些文档一起改、最后怎么验收。项目自己的 `AGENTS.md` 也容易继续往里面塞规则。 时间一长，Agent 接一个很小的任务，也可能先读一堆跟当前工作没关系的内容。文档都在，Agent 的上下文反而越来越重。 ## 现在项目上下文拆成了四层 新版大概是这个结构： ```text AGENTS.md ↓ 判断当前任务应该读什么 DOCUMENT_MAP.md ↓ 找到项目现在认可的文档 PRD / PDD / Design / Flow / DEC ↓ 保存产品、技术、设计和决策 REQ / Bug / Progress ↓ 记录当前正在推进的工作 ``` `AGENTS.md` 现在会尽量保持轻。里面放仓库边界、安全规则、任务路由、高风险操作和通用验证要求。 比如： ```text 修改产品行为 → 读产品文档和相关 REQ 修改 UI → 读设计规范和对应产品规则 修改数据库 → 读技术设计和 DEC 修改 Agent / MCP / 检索 → 读技术设计和业务流程 修 Bug → 读 Bug 记录和受影响模块规则 ``` 表结构、接口字段、当前开发进度、某个功能的详细需求，不继续往根 `AGENTS.md` 里堆。Agent 改哪块，再加载哪块的上下文。 ## DOCUMENT_MAP.md 现在会告诉 Agent 哪份文档能信 这个改动看起来不大，我自己挺在意。 项目做久以后，仓库里经常会出现这种文件： ```text old-design.md architecture-v2.md architecture-final.md prd-new.md some-spike.md ``` 人还能根据名字和 Git 历史猜一下。Agent 可能全部读进去，然后旧方案、新方案、实验记录一起进上下文。 新版的 `DOCUMENT_MAP.md` 会给文档标状态： ```text 现行 参考 缺失 不适用 ``` 例如： ```text 产品事实 docs/product/spec.md 现行 旧版产品设计 docs/archive/product-v1.md 参考 UI Design 缺失 Desktop 架构 docs/desktop-architecture.md 现行 ``` 至少 Agent 进项目以后知道当前应该看哪一份。 ## init 也整个重写了 旧版 `init` 主要围绕 PRD/PDD 和项目总进度工作。 现在执行： ```text $project-vibe-spec init ``` Agent 会先把仓库过一遍。它会检查 `AGENTS.md`、`CLAUDE.md`、README、docs、需求、设计、DEC、Progress、测试、构建配置、schema、migration、部署脚本和一部分实际代码。先弄清楚项目已经有什么，再决定缺什么。 假设一个项目已经用了： ```text specs/product.md architecture/backend.md docs/design-system.md adr/ ``` 新版不会再硬生生补： ```text docs/PRD.md docs/PDD.md docs/UI_GUIDE.md Decisions/ ``` `DOCUMENT_MAP.md` 里直接记现有路径： ```text 产品事实 → specs/product.md 技术事实 → architecture/backend.md 设计规范 → docs/design-system.md 架构决策 → adr/ ``` 跑 `init`，更接近给现有仓库做一次整理和审计。 ## 没有 PRD，就先记没有 以前为了把结构补齐，很容易生成一堆空模板。`PRD.md` 有了，`PDD.md` 有了，`UI_GUIDE.md` 也有了，里面没有多少能指导 Agent 的内容。 这轮把这个行为改掉了。 项目没有 PRD，可以直接记： ```text 产品事实：缺失 ``` 没有设计规范，而且项目根本没有 UI，也可以记： ```text 设计规范：不适用 ``` 后面开发真的需要产品规则，再补 PRD。模板现在只在项目缺这份信息、同时后续工作又需要它的时候才创建。 ## 历史功能也不用补几十个 REQ 一个已经做了几个月的项目第一次跑 init，如果硬套需求台账，很容易一次性生成很多历史 REQ。项目里已经有十几个功能，就补十几个需求记录。这些文件看起来规范，之后基本没人维护。 现在已有功能直接进入"当前实现基线"。 例如： ```text Agent Loop 已验证 PDF 解析 已实现待验证 多模态 PDF 已通过（POC） ``` 从这次初始化往后，新需求和还在推进的大任务再进入 REQ。需求台账里留下来的，基本都是后面还会继续看的内容。 ## "代码已经写了"单独变成一个状态 这次加了一个状态： ```text 已实现待验证 ``` 现在 Progress 有这些状态： ```text 已验证 已实现待验证 已通过（POC） 进行中 待开发 待拆分需求 待澄清 不纳入 ``` 加这个状态就是因为 Coding Agent 太容易把代码完成和功能完成混在一起。 仓库里已经有实现，只能说明代码存在。测试没跑完，就写"已实现待验证"。只验证过一个 Demo，就写"已通过（POC）"。有对应测试、构建结果或者真实用户路径验证以后，再写"已验证"。 对于不太看代码的人，这个区分比多一份技术文档有用得多。至少你问 Agent"这个功能做完没有"，它不能只因为搜到了代码就回答完成。 ## 数据库这种改动我还是卡得很死 这轮删了不少文档负担，但数据库规则没放松。 Agent 想加表、加字段、改索引、迁历史数据、删数据或者改 ORM schema，还是先调查。我要看到这个字段表示什么，谁写，谁读，旧数据怎么办，能不能为空，有没有唯一约束，需要什么索引，上线怎么迁，失败以后怎么处理。方案确认以后再改。 Vibe Coding 里面，数据库被连续改错几轮，比一个按钮颜色错了麻烦得多。这块宁愿多一次确认。 ## 这版对不 Review 代码的人有什么用 Project Vibe Spec 解决不了所有代码质量问题。竞态条件、慢 SQL、隐藏的安全问题、边界异常，该测还是得测，该 Review 还是得 Review。 我更关心的是另一个问题。 很多 Vibe Coding 项目做着做着，用户已经不知道项目现在是什么状态了。 需求当时怎么确认的？Agent 为什么用了这个方案？这个实现是临时的还是正式的？POC 后来有没有进正式版本？文档和代码现在该信哪个？哪些地方写完了还没测？下一次开新 Session 从哪里继续？ 这些信息如果全在聊天记录里，换个 Agent、换个工具或者隔一个月回来，很容易断。 新版 Project Vibe Spec 会尽量把这些信息留在仓库里。以后无论用 Claude Code 还是 Codex，Agent 先从 `AGENTS.md` 进入，根据任务找到 `DOCUMENT_MAP.md` 里的现行文档，再读对应的需求、决策和进度。 聊天记录可以丢，项目自己的状态还能接着用。 这次重构完以后，Project Vibe Spec 少了一些"必须创建什么文件"的规定，多了一套让 Agent 找到当前可信信息的办法。对大量用 Agent 写代码、又不会每次认真 Review 全部 diff 的开发方式，这比继续加几十条规范有用。 如果这套思路对你有帮助，去 GitHub 点个 Star 吧：[github.com/dnwwdwd/project-vibe-spec](https://github.com/dnwwdwd/project-vibe-spec) ⭐
喵喵搜索开源了——一个可自托管的多引擎联网搜索与 MCP 服务
大家好，我是汉堡🍔。 今天把一个做了一段时间的项目开源了：**喵喵搜索**（miaomiao-search）。 GitHub 地址：https://github.com/dnwwdwd/miaomiao-search 如果觉得有用，欢迎点个 ⭐ Star，这是我持续更新最大的动力。 --- ## 它是什么 一句话：**可自托管的多引擎联网搜索 + Remote MCP 服务**。 你可以把它部署在自己的机器或懒猫微服上，然后让 AI 客户端（比如 Codex、小龙猫）通过 MCP 协议调用它来搜索互联网、读取网页正文——完全在你自己的控制下，不依赖第三方中转。 --- ## 核心功能 **聚合 11 个搜索源**，一次搜索覆盖： - Bing、Baidu、DuckDuckGo、Sogou - CSDN、掘金 - GitHub（支持可选 Token） - B站（公开接口，返回官方 CDN 封面） - Exa、Firecrawl、Tavily（需要用户自己的 API Key，按用户加密存储） **读取网页正文**，支持 JavaScript 渲染回退（生产镜像内置 Chromium）。 **Remote MCP 服务**，通过 Streamable HTTP 暴露 MCP Tools，外部客户端用 Access Token 接入，懒猫应用间可以委托鉴权，不需要额外 Token。 **管理门户**，可以管理搜索引擎开关、缓存、限流、历史记录和审计日志。 **账号体系**，支持懒猫 OIDC 和本地账号密码两种登录方式。 --- ## 技术栈 - **前端**：Next.js 16、React 19、TypeScript、Tailwind CSS v4 - **后端**：Fastify 5、SQLite、Drizzle ORM - **MCP**：MCP TypeScript SDK v2 - **搜索底层**：`open-websearch@2.1.11` daemon 适配器 单实例运行，数据用 SQLite 持久化，按懒猫 UID 隔离用户数据，包内不含数据库或密钥。 --- ## 本地跑起来 要求：Node.js 20+、pnpm，以及一个可通过 HTTP(S) 访问的 Open-WebSearch daemon。 ```bash pnpm install ``` 启动 Open-WebSearch daemon（Windows PowerShell 示例）： ```powershell $env:SEARCH_MODE="request" $env:USE_PROXY="true" $env:PROXY_URL="http://127.0.0.1:7890/" pnpm --filter @miaomiao-search/server exec open-websearch serve --port 3210 ``` 再分别启动服务端和门户： ```bash pnpm server:dev pnpm dev ``` 默认地址： - 门户：`http://127.0.0.1:3000/` - 服务端：`http://127.0.0.1:3001/` - MCP Endpoint：`http://127.0.0.1:3000/mcp` --- ## 安全设计 几个关键点说一下： - **实例密钥**派生会话、MCP Token Hash 和设置加密密钥，生产环境由懒猫清单注入，不能写进仓库。 - Exa、Firecrawl、Tavily、GitHub 的凭据在门户"引擎管理"中按用户保存，服务端只在当前用户数据库中存加密值。 - 外部 MCP 客户端用 `Authorization: Bearer <Token>` 接入；懒猫应用间调用由 ingress 注入 `X-HC-SOURCE` 和 `X-HC-USER-ID`，委托鉴权，不需要额外 Token。 - 门户不把 `X-HC-*` 头当登录凭据，所有受保护 API 将当前 UID 与应用会话绑定校验。 --- ## 许可 Apache-2.0，详见仓库 [LICENSE](https://github.com/dnwwdwd/miaomiao-search/blob/main/LICENSE)。 --- 项目还在持续迭代中，欢迎提 Issue 和 PR。 如果觉得有用，**点个 Star** 是对我最大的支持 ⭐ 👉 https://github.com/dnwwdwd/miaomiao-search
我是如何学习大模型应用开发的
## 大模型应用开发的一些概念关系  上面整理出来的是我自己对于大模型应用开发的理解，也结合了一些技术和概念的变化时间线，仅供各位朋友参考，不一定准确，我觉得大模型应用开发最重要的是这三个东西：Agent Loop、Context Engineering、Harness Engineering > 最近好像又新出了很多层的概念，在harness engineering之上，但是我个人现在并不喜欢，所以没去做更深入的了解，我觉得新出的很多概念，没有出现新的基础元素，只是融合现有的，然后加深了一下理解，所以我个人的想法是：了解即可，知道有这么个东西就可以 > > - Agent Loop是运行的核心，是一切的基础，用户输入任务，LLM输出指令，工具执行并返回结果，不断的循环直到结束 - Context Engineering在静态系统提示词结构不断稳固之后，发现Agent Loop在运行中是需要大量的动态信息的，并且常见有效的动态信息是用户记忆、会话历史记录、用户输入、系统提示词、工具定义等，那么这个时候就有了Context Engineering这个概念，上下文是Agent Loop有效的关键，在Agent长程运行中，上下文不断积累，会出现各种各样的问题，漂移、污染、干扰、冲突等，所以我们需要上下文管理的方法，需要渐进式加载的概念 - Harness Engineering是Agent稳定运行的关键，它为Agent搭建运行空间，设计Agent的能力结构、协作机制和反馈闭环，其不能仅仅从约束的角度去理解，更应该是在创造Agent的运行环境，让LLM可以做到原本无法做到的事情 ## 推荐的学习顺序 然后我按照自己的理解，大概梳理一下学习的顺序和方向，给学习的朋友一些“经验之谈”，当然下面的这些概念我都单独梳理过一些文章和实践经验，会搭配一些代码讲解，感兴趣的朋友可以借助这个学习手册来更好的了解 > 《大模型应用开发 -上下文工程与运行空间实践指南》：https://github.com/WakeUp-Jin/Practical-Guide-to-Context-Engineering > >  还有一些其他值得多聊的事情，我这边继续补充一些我自己的理解： 对于RAG和知识图谱的理解，我认为这个来源于“背景信息”这一种类型的上下文，我没办法准确的去下定义，我只是有一种淡淡的理解。 用户输入的问题，LLM需要解决，是需要一些背景信息的，有时候用户可以手动补充，模型也可以依靠推理能力去补充澄清，但更多的情况下，LLM需要依靠工具系统去动态的检索到这些“背景信息”，那么检索流程中最关键的手段就是：RAG和知识图谱，我甚至觉得Harness Engineering诞生在Agent领域中，也是因为“背景信息”作为一个突破口出现的。 上下文管理是一个值得深入探索的方向，Agent借助Skill来达到上下文层面的自进化，是一个上下文管理的具体应用，我相信这个里面还有很多有趣的东西，值得去深挖，目前来看比较常见的是：上下文压缩，文件存储检索，上下文编排，渐进式披露等。 在工具设计中，如果要有一层“宗门长老“的概念的话，我觉得是Edit、Bash、Read、Glob、Grep、Wirte这“六位宗门长老”，Bash工具甚至可以是“大长老”级别的。而目前最有难度的是Bash工具运行时的安全和输出问题，而Browser Use和Computer Use是为数不多的有趣的方向了 Agent形态方面，现在还在不断的变化吧，之前大家还会讨论Agent是自主运行好，还是协同驾驶好，现在看来各有各的的领域优势了，在任务确定的领域中，自主运行借助如今的模型推理能力完全可以覆盖住，在创作领域中，协作驾驶还是有一席之地的，用户在Agent输出的产物中，手动的进行各种小微调，同时也可以直观的看到Agent的中间执行链路。 单智能体和多智能体的方式，我觉得单智能体\+一个SubAgent的能力，其实就非常好用啦，如果设计成比较纯净的多智能体，成本是可以下降的，但混乱系数会大大增加，不仅对于某些模型的能力要求高，同时上下文管理的难度是指数级上升的，还会添加多智能体协作的概念，这是一个很有魅力的领域，很有挑战的领域。 接下来是我近期最感兴趣的方向了，也是大模型应用开发工程师们最容易忽略的，但在Agent开发中是最重要的，甚至可以说，没有它存在，你的Agent只是一个没有方向的经验产物。 没错，这个东西就是Agent评估，在构建一个Agent之前，或者说在设计一个Harness之前，你需要先存在一批数据集，以此来确定Agent的能力边界和迭代方向，Agent评估在开发中可以帮助你不断打磨提示词、上下文、工具等。 同时在数据集评估的过程中，通过对于执行链路和结果的观察，你会产生一些Agent垂直化的方向，最后你可以通过评估结果来确定它在混乱环境中的运行情况。Agent评估非常值得成为构建的第一步 ## 我的学习经历 我是从24年大学毕业的时候，大概6月份开始学习的，当时第一个需求是批量根据一个固定的提示词生成文章，我当时调用的是百川大模型，当时要毕业答辩啦，所以回了一趟学校，我调试了很久，我记得是在宿舍晚上10点左右调通的，就是一个简单的for循环的API调用，那是第一次看到LLM API的请求格式。 之后在接触到LangChain，里面有一个概念叫做检索器，里面涉及到向量知识库\+嵌入模型，当时我们团队有一些语义上的需求检索，所以借助这个机会，我去了解LangChain和向量数据库，在学LangChain的时候，很多概念都非常懵逼，不知道什么意思，封装的在我看来很复杂，当时硬啃了好几天，慢慢的有了一些感觉，LLM供应商的封装，tools方法的定义和使用，链式调用等概念 期间不断了解到各种框架，也在系统性的学习提示词工程，我对于LangChain和LangGraph学的比较多，算是我的入门框架。再后来 Cursor 等 Coding Agent 开始火热，我被 Agent 协同的模式吸引，开始关注工作流编排、工具定义、知识图谱等方向，也用飞书多维表格 \+ RAG \+ LangGraph 搭了团队第一个 Agent 项目 在做一个Agent项目的过程中，我形成了自己对于上下文工程的理解，一个Agent是否有效，取决它注入那一刻的上下文是否正确，《大模型应用开发 \-上下文工程与运行空间实践指南》这个开源项目也是这个时候开始创建的，我开始深入了解一些技术细节，RAG的检索策略，工具的定义，LLM模块的设计，上下文编排。 同期ClaudeCode、gemini\-cli、opencode开始出现，我就开始研究这些开源框架，研究cli 的方式，发现不需要RAG，通过工具形成的本地检索，也就是搜索Agent，随着模型能力的提升，这种方式变得极其有效 这个时候我们团队的第一个Agent项目的V2版本开始迭代了，工作流的方式只能让效果还行，在模型不断提升的能力面前，工作流不仅得不到提升，反而成为了好结果的束缚，开始显露出鸡肋的感觉了，我当时在一篇文章看到“模型应用的开发，要站在模型的同一侧，不要站在模型的对立面”。所以V2版本我们决定采用多智能体\+自定义工具设计的方式。 在之后关于如何让一个Agent可以长时间稳定运行的问题开始出现了，一个Agent可以不断的运行多久才会崩溃，上下文会变得极其混乱，这个时候的上下文管理开始慢慢出现了，以此同时Harness Engineering也开始诞生，OpenAI和Anthropic都发布过工程博客的文章，一个是专注于上下文工程和反馈闭环，一个专注于编排，所以我结合这两篇文章，开始构建自己对于Harness Engineering的初步理解，并且后续也在不断的调整 这个时候我也在更深入具体的了解Coding Agent都有哪些工具，这些工具是如何定义的，上下文的压缩策略是什么，指令又有哪些，Skill对于上下文工程意味着什么等问题 现在我的方向是多智能体协作，上下文管理，Agent评估，Harness的自进化，我觉得这几个方向很有意思，值得做更多的探索和学习 还有一个比较有意思的是DeepSeek Harness的一切皆插件的理念，存在着一种可能：Agent Loop可以更换，我很喜欢这一点，它让沉默的Harness仿佛再次焕发生命力，或许可以这么理解，大模型应用开发，一切皆可能，当Agent要面对复杂环境时，静态固定的方式很大程度会失效，开发者不可能在一开始就穷举复杂环境的问题，所以动态自进化的方式是值得尝试的，甚至很可能是一种很好的解法 ## 我的学习资源的推荐 - 飞书里面的通往AGI之路知识库：[通往AGI之路](https://waytoagi.feishu.cn/wiki/QPe5w5g7UisbEkkow8XcDmOpn8e) - Anthropic工程实践文章：https://www.anthropic.com/engineering - Claude团队博客：https://claude.com/blog - Anthropic的研究文章：https://www.anthropic.com/research - Cursor团队博客：https://cursor.com/cn/blog - Lilian个人博客：https://lilianweng.github.io/ - ClaudeCode的文档：https://code.claude.com/docs/en/overview - LennysPodcast的视频：https://www.youtube.com/@LennysPodcast - Pi的文档和源码：https://github.com/earendil-works/pi、https://pi.dev/docs/latest - 我也在做一个相关的开源项目，感兴趣可以看看《大模型应用开发 -上下文工程与运行空间实践指南》：https://github.com/WakeUp-Jin/Practical-Guide-to-Context-Engineering ## 我对于大模型应用开发的理解 在我自己开源项目中，有2篇我很喜欢的博客，一篇是《两种世界的交互形态：协同Agent与自主Agent》，另外一篇是：《编程 Agent 的工程实践：来自 OpenAI 与 Anthropic 的实战经验》，这个开源项目的理念我觉得也不错：上下文工程是设计原则，Harness是建造目标 在这一大段时间的学习和实践中，我也在不断的想一个问题，对于大模型应用开发来说，什么样的思维和理解是有帮助的呢？ 我稍微整理了一些想法（**谨小认知，仅供参考）** 1. 务实的品质可以让大模型应用开发工程师走的更远，做的更多，务实让开发者不困于“过度冗长且孤立”的思考中，可以寻找到简单有效的解决方案 2. 像你的Agent一样思考，借助执行日志，观察上下文工程的设计缺陷，观察Harness的运行漏洞 3. **人类观察Agent的行为很重要，Agent观察人类的行为也很重要** 4. 「Lead, don't follow」去从第一性原理思考事情的本质，去发现和构建新的东西 5. 不要轻易放弃底层技术的学习，它们会极大的给你提供新的视角，要学会站在巨人的肩膀上 我是 WakeUp-Jin，目前在做两件事： 1. 整理一套上下文工程与Agent Harness实践指南 —— 上下文工程是设计原则，Agent Harness 是构建目标 2. 开发 Actspace Agent—— 一个本地 Agent 桌面应用，从 Coding Agent 开始，最终愿景是彻底释放模型能力 GitHub: https://github.com/WakeUp-Jin
拆解 GitHub 趋势榜 TradingAgents：多 Agent 辩论架构与本地运行实测
大家好，我是不会喷火的小火龙。今天我们来拆解一个最近频繁登上GitHub趋势榜开源的多智能体金融量化交易全流程框架。 在平常让大模型直接分析股票，往往会得到一份四平八稳的研报。但在真实交易里，单向叙事暗藏风险：只要挑选不同的技术指标或新闻切片，无论看多还是看空都能写出逻辑自洽的分析。金融决策要在信息不对称下权衡概率与风险，并不存在现成的标准答案。 ## 一、为什么单一 Prompt 难以胜任金融决策 用大模型做交易策略和财报分析的尝试很多，但单一 Prompt 很容易陷入确认偏误（Confirmation Bias）。当系统接收到偏多的技术指标时，倾向于给出顺势做多的结论；当面对负面宏观数据时，又很容易偏向防守。提示词再长，也很难在同一个上下文内保证对抗立场的客观性。 机构投研流程的设立，初衷就是利用角色分权来暴露漏洞。技术面与基本面关注的周期不同，情绪面与宏观面各有噪音。多空研究员各执一词，风控团队负责收紧止损，最终由投资经理做出权衡。TradingAgents 的核心思路就是将这套博弈逻辑转化为状态图上的确定性流程。 传统量化或对冲基金在做投资决策时，通常会有分工明确的角色：收集数据的分析师、互相挑刺的多空研究员、评估尾部风险的风控部门，以及拍板的投资经理。TradingAgents（论文 arXiv:2412.20138）把这套组织结构搬进了多智能体系统。项目开源后一度登上 GitHub 趋势榜，收获了 7000 多 Star。它的价值不仅在于生成金融研报，也在于为复杂决策型 Agent 系统的分工与对抗机制提供了一个参考实现。 下图是 TradingAgents 的完整协作流水线，从多源数据提取、观点辩论到风控评估，均由专门的 Agent 节点承接：  ## 二、核心架构：模拟基金投研的 5 阶段流水线 TradingAgents 的设计重点在于各个 Agent 之间的信息流向和制约关系。系统将决策链路划分为五个阶段： ### 1. 分析团队：四维度并行采集数据 系统启动后，四位分析师 Agent 并行运行，分别处理各自的数据源： - Market Analyst（市场分析师）：通过 Yahoo Finance 获取价格与常用技术指标（如 OHLC、移动平均线、MACD、RSI、ATR、布林带等），整理技术面研报。 - Fundamentals Analyst（基本面分析师）：梳理财务指标、估值水平与同业对比。 - News Analyst（新闻分析师）：汇总宏观新闻，评估地缘政策、利率环境等宏观因子对标的的影响。 - Sentiment Analyst（情绪分析师）：抓取 StockTwits、Reddit 等平台上的散户讨论，统计情绪比例。 四个分析师彼此独立，各自生成文件。这种隔离避免了单一维度的强结论过早干扰其他维度的信息提取。  ### 2. 多空辩论：结构化对抗 汇总四份分析报告后，流程进入多空对抗阶段。 系统没有让一个 Agent 同时总结利弊，而是分别设立了 Bull（多头研究员）和 Bear（空头研究员）。多头先列出自己的支撑论据，空头针对这些论点逐一反驳并补充利空因素，多头再就反驳进行二次防守。辩论轮数可以在配置中调整（默认为 1 轮，可设为 2 轮）。 辩论结束后，由 Research Manager（研究主管）进行裁判。研究主管负责梳理双方在关键价位和宏观逻辑上的分歧点，评估论据支撑强度，最终形成一份综合研究总结。 拆分对抗角色能够有效避免大模型常见的调和倾向，迫使模型把两端的论据和风险都完整暴露出来。 ### 3. 交易员：制定具体参数 研究主管的总结交由 Trader Agent。交易员不重复分析基本面或技术面，而是将结论翻译为具体的交易计划：方向（买入 / 卖出 / 持有）、进场区间、止损价位、目标点位和建议仓位。 ### 4. 风控委员会：三方评估 交易计划提交后，由三位风控分析师组成委员会进行审核： - Aggressive Analyst（激进派）：关注盈亏比与潜在机会，侧重执行可行性。 - Conservative Analyst（保守派）：聚焦极端回撤与黑天鹅事件，倾向于压缩风险敞口。 - Neutral Analyst（中立派）：平衡机会与潜在风险，评估赔率。 三位风控人员同样会针对仓位大小、止损距离是否合理等细节展开讨论。  ### 5. 投资经理：最终裁决 最后，Portfolio Manager（投资组合经理）统揽所有上游报告，包括分析师数据、多空辩论过程、交易员方案以及风控委员会的审议意见，给出最终结论：评级（Buy / Hold / Sell）、执行摘要、投资逻辑以及观察周期。 五个阶段构成完整的流水线，使每个环节的观点都会在下一环节接受检验。 ## 三、工程机制：反思记忆与断点恢复 TradingAgents 在工程实现上有两点值得注意：长流程容错与跨周期复盘。 ### 断点恢复（Checkpoint Resume） 一次完整的研报生成包含十余次模型调用，耗时通常需要几分钟。如果中间因为网络超时或 API 限流中断，从头重跑会浪费调用成本与时间。 TradingAgents 基于 LangGraph 的 SQLite 检查点功能实现了节点级状态保存。运行时加上 `--checkpoint` 参数后，每个 Agent 节点执行完毕都会把状态写入数据库。任务中断后重新启动，会自动从断点处继续执行。 ### 决策日志与反思机制（Reflection） 每次做出评级后，系统会把决策摘要记入本地的 `trading_memory.md`。当后续再次分析同一标的时，系统会自动执行几步复盘： 1. 调取上一次的决策（包括当时的评级、入场价与设定周期）。 2. 获取该标的在决策之后的实际走势。 3. 计算实际收益率以及相对基准指数（如 SPY）的超额表现。 4. 将偏差反思整理为文本，作为上下文注入到本次投资经理的 Prompt 中。 通过这套闭环，历史判断的偏差能够作为经验输入给下一次决策。 ## 四、本地部署：Docker 环境与模型配置 ### 1. 获取代码与构建镜像 ```bash git clone https://github.com/TauricResearch/TradingAgents.git cd TradingAgents cp .env.example .env docker compose build ``` ### 2. 模型接入配置 TradingAgents 原生集成了多家主流 LLM 接口，同时也支持任何遵循 OpenAI 协议的自定义端点。 以火山方舟 Agent Plan 为例，在 `.env` 中添加对应配置： ```bash # 采用兼容协议 TRADINGAGENTS_LLM_PROVIDER=openai_compatible # 火山方舟 Agent Plan 端点 TRADINGAGENTS_LLM_BACKEND_URL=https://ark.cn-beijing.volces.com/api/plan/v3 # 填入申请的 API Key OPENAI_COMPATIBLE_API_KEY=your_api_key_here # 指定模型名称（支持使用 deepseek-v4-flash、kimi-k3 等平台原生名称） TRADINGAGENTS_DEEP_THINK_LLM=deepseek-v4-pro TRADINGAGENTS_QUICK_THINK_LLM=deepseek-v4-flash ``` 使用火山方舟 Agent Plan 的便利之处在于可以直接配置模型名，无需单独创建 Endpoint 接入点。 ### 3. 网络与环境问题处理 TradingAgents 默认通过 Yahoo Finance 获取行情。在部分网络环境下，容器内请求 `query2.finance.yahoo.com` 可能遇到 SSL 握手断开的报错。 可通过将宿主机代理映射进容器来解决，同时将国内的模型服务地址排除在外： ```bash # 容器使用宿主机本地代理访问外部行情 HTTP_PROXY=http://host.docker.internal:7890 HTTPS_PROXY=http://host.docker.internal:7890 # 国内模型端点走直连 NO_PROXY=localhost,127.0.0.1,ark.cn-beijing.volces.com ``` 另外需要注意：在 Mac 上使用 Docker Desktop 时，如果默认的 `desktop-linux` context 受到网络代理影响导致 `docker compose run` 无响应，可以切换到原生 socket 连接： ```bash docker context create direct \ --docker "host=unix://$HOME/Library/Containers/com.docker.docker/Data/docker.raw.sock" docker context use direct ``` ### 4. 报告文件持久化挂载 容器默认将研报保存在内部路径。可以在 `docker-compose.yml` 中挂载目录，方便直接在宿主机查看： ```yaml services: tradingagents: volumes: - ./reports:/home/appuser/app/reports ``` ### 5. 启动交互式分析 ```bash docker compose run --rm tradingagents ``` 启动后会弹出交互提示，输入标的代码（如 `NVDA`、`BTC-USD`）、基准日期、参与的分析师角色、辩论轮次和输出语言即可启动流程。  ## 五、实测复盘：BTC-USD 完整研报 这里使用火山方舟的 `deepseek-v4-flash` 模型，以 BTC-USD 为标的做了一次完整运行。 终端输出展示了各模块的执行耗时与归档路径：  分析全程耗时约 6 分钟，生成了一份 186KB、1244 行的 Markdown 研报。输出文件按执行阶段分层归档： ``` reports/BTC-USD_20260910_130329/ ├── 1_analysts/ # 各分析师独立数据报告 │ ├── market.md # 8 项技术指标核算 │ ├── sentiment.md # 社区情绪量化 │ └── news.md # 宏观新闻梳理 ├── 2_research/ # 多空对抗记录 │ ├── bull.md # 看多观点 │ ├── bear.md # 看空反驳 │ └── manager.md # 研究主管综合 ├── 3_trading/ │ └── trader.md # 交易执行计划 ├── 4_risk/ # 风控三方讨论 │ ├── aggressive.md # 激进派 │ ├── conservative.md # 保守派 │ └── neutral.md # 中立派 ├── 5_portfolio/ │ └── decision.md # 投资经理裁定 └── complete_report.md # 完整报告合集 ``` ### 技术指标校验 Market Analyst 抓取并计算了当时 BTC-USD 的多项指标： | 指标 | 数值 | 研报解读 | |:---|:---|:---| | 收盘价 | 77,133.63 | 基准价格 | | 10 EMA | 78,428.41 | 现价低于该线，短期动能衰退 | | 50 SMA | 70,414.24 | 现价高于该线约 9.5%，中期趋势尚存 | | 200 SMA | 69,965.22 | 50/200 均线金叉，长期均线呈修复状态 | | RSI | 54.89 | 从高位超买（>80）回落至中性区 | | MACD 柱 | -641.58 | 死叉已现，动能转弱 | | ATR | 2,142.89 | 日均波动约 2.8%，止损需预留安全空间 | 在报告细节中，分析师还比对了 `get_stock_data` 与 `get_verified_market_snapshot` 接口返回的收盘价（差异约 54 美元，占比 0.07%），并在报告中明确说明统一以验证快照为准。 ### 多空辩论要点 多空双方在核心逻辑上的交锋较为具体： 多头论点： > 价格保持在 50 日均线上方 9.5%、200 日均线上方 10.2%，且 200 日线刚掉头向上，整体属于均线多头修复。且回调阶段成交量较 8 月突破时期缩减超过一半，缺乏主力集中派发的特征。 空头反驳： > 均线系统具有滞后性，难以直接预测短期二元风险。当前面临美国关键宏观数据公布、欧洲央行加息以及美债收益率走高的多重宏观压力，短期内指标均线无法对冲宏观利空冲击。 风控人员的讨论则聚焦在操作节奏上： > 激进派的短线试多方案将止损设在 75,400，距离现价仅 2.2%，但当前日均 ATR 达到 2,143 美元（波动率 2.8%）。这意味着在数据发布前夕，普通盘中插针就会轻易扫掉止损。 ### 终审结论 投资经理最终给出的评级为 Hold（观望）： > 中期结构偏多，短线动能偏空，且宏观上存在待公布的重大经济数据。在这种信号冲突的节点，维持现有持仓、不盲目开新仓是较优选择。等待宏观事件落地后，若价格在 76,000–77,100 区间企稳，或放量收复 10 EMA（78,428），再右侧轻仓介入。 系统没有机械地在多空结论中二选一，而是在多项指标冲突时选择等待右侧确认条件，并给出了明确的观察窗口。 ## 六、现状与实盘距离 TradingAgents 验证了多角色对抗在提升复杂分析质量上的有效性，但在走向实际自动化交易前，依然存在几处现实门槛： 1. 时效与延迟：端到端完整分析涉及十余次推理，单次运行约 3 到 6 分钟。这种耗时决定了它更适合日线级别的波段分析与复盘，无法应对秒级的日内撮合与高频风控。 2. 数据生态接入：原版基于国外数据源构建。若用于 A 股或其他本土市场，需要适配本土行情接口与研报来源。 3. 执行层的衔接：系统当前输出的是逻辑分析和参数建议，并不包含与券商交易接口的直接连通，订单管理、滑点控制和仓位风控等工程模块需要单独开发。 4. 策略回测工具链：框架主要侧重于单次决策的推理过程，目前缺少开箱即用的批量历史回测流水线，较难大规模统计在不同市场周期下的胜率与收益分布。 作为辅助工具，TradingAgents 能够帮助投资者在做决策前快速梳理多空逻辑、罗列潜在风险并量化波动指标。作为多 Agent 系统项目，它在角色拆分、辩论裁决和状态机容错上的处理方式，为探索复杂任务下的 Agent 协作提供了一个清晰的工程参考。 --- 项目地址：https://github.com/TauricResearch/TradingAgents 论文引用：arXiv:2412.20138 免责声明：TradingAgents 属于研究类开源项目，本文仅作技术与架构拆解，文中所涉及标的与实测数据均不构成任何投资建议。
用 AI + Obsidian 搭一套智能化学习产出工作流，再也不用纠结今天学什么了
大家好，我是专注探索学习本质和 AI 价值最大化实践的 Jennifer，感谢鱼皮创办的编程导航社区。 不知道你有没有过这种体验： 笔记软件里插件装了一堆，模板、看板、自动统计表全都配好了，整个系统看起来专业得像个小型项目管理平台。 结果第二天早上打开它，盯着那个空白的「今日计划」，还是不知道今天该干什么。 于是刷了会儿手机，一天就过去了。  这不是你不够自律。 **这是记录型工具的天生缺陷：它们把「记录」优化到了极致，却从来没人替你干「决定今天做什么」这件最耗神的事。** 我最近想通了一件事 —— 这个环节，现在可以交给 AI 了。 不是让 AI 帮我写笔记，而是让它每天早上替我做决策：从我的大目标里切出今天能做完的一件事，把行动计划写进我原有的日记和任务文件；晚上再把我今天真做出来的东西变成一篇成稿，当场给我一份点评。 这篇文章我会讲清三件事： 1. 我的 Obsidian 学习产出工作流有哪些功能、具体怎么实现 —— 配置和代码全给你，可以直接抄 2. 这套工作流卡在哪，以及为什么再装十个插件也解决不了 3. 我怎么用 AI + 神级 skill 把这套工作流自动化智能化 —— 代码已开源，你可以直接装 没用过 Obsidian 也能看，每个术语我都会先用白话解释一遍。已经有自己一套工作流的同学，重点看第三部分。 点个收藏，咱们开始~ ## 一、先看这套工作流能干什么 先用一句话说清楚：**我给自己搭了一个私人版的项目管理平台，外带一套自动生成的统计报表。** 具体有这些功能： - 每天新建日记，当天日期、本周链接、三块待办查询全部自动填好，我打开就是填空 - 所有待办自动分成三块 —— 五天内到期的、今天要做的、今天已完成的，不用手动搬 - 三张自动统计表：今天新建了哪些笔记、完成了哪些任务、改过哪些旧笔记 - 一块看板，四列 ⚪Todo / 🟡Doing / 🟢Done / 🟤Blocked，拖一下就换状态 - 三级项目树：目标 → 项目 → 任务，下级的完成情况自动汇总到上级 - 双周迭代编号，`26-08-A` 这种，方便按周期回顾 再一句话总结：从「今天写了什么」到「这个季度推进了哪些项目」，全都是自动统计出来的，我不用手动记一行。 听起来复杂，其实只用了四个插件，都是 Obsidian 社区里最常见的，没有任何自研： | 插件 | 干什么用 | |------|----------| | Templater | 新建笔记时自动填充日期这类动态内容 | | Tasks | 把散落在各处的待办按条件查出来，聚成一个清单 | | Dataview | 把笔记的元信息当数据库查，生成统计表 | | Kanban | 看板视图 | 如果你还没用过 Obsidian：它是一个本地优先的 markdown 笔记软件，所有笔记就是你硬盘上的 `.md` 文件，没有云端锁定，插件生态非常猛。上面这四个插件在社区插件市场搜名字就能装。 ## 二、这套工作流具体怎么实现 这部分给的是可以直接抄走的配置。不想看实现细节的同学可以直接跳到第三部分。 ### 1、在日记中让待办自动分成三块 这是 Tasks 插件干的活。在日记模板里放三个查询块，其中「今天要做的」这块是这样： ````markdown ```tasks not done happens on 2026-08-03 sort by due ``` ```` （实际用的时候，日期那行也是 Templater 变量，会自动填成当天。） 关键是 `happens on` 这个条件 —— 它会同时匹配开始日期、计划日期和截止日期，只要待办上带了当天的日期，就会被捞进来。 那待办怎么写才能被查到？Tasks 插件用 emoji 当字段标记： ```markdown - [ ] 把三种分块策略各跑一遍，记录检索命中率 🛫 2026-08-03 - [x] 整理成对比表 🛫 2026-08-03 ✅ 2026-08-03 ``` `🛫` 是开始日期，`✅` 是完成日期，`📅` 是截止日期。 这么一配，我的待办可以散落在任何一个项目笔记里，日记会自动把「今天该做的」聚过来。**不用维护一份单独的今日待办清单，这是我觉得最省事的一点。**  ### 2、让项目树自动汇总 这一步用 Dataview。它能把笔记开头的元信息（frontmatter）当成数据库字段来查。 比如我在 AI 这个主题笔记里放一段查询，就能自动列出所有挂在 AI 下面的子项目： ````markdown ```dataview TABLE status, type, DateStarted, DateDone, project WHERE contains(tags,"AI") AND (contains(type,"P") OR contains(type,"O")) sort type, DateDone Asc ``` ```` 意思是：把所有打了 `AI` 标签、并且类型是「项目」或「主题」的笔记查出来，按类型和完成日期排。 我给每篇笔记的 `type` 字段定了一套分类： | type | 含义 | |------|------| | `P` | 项目 —— 有明确交付物和完成态 | | `T` | 任务 —— 一个具体的活儿 | | `O` | 主题笔记 —— 长期积累，没有完成态 | | `S` | 学习资源 | | `D` | 概念笔记 | | `A` | 行动说明 | 有了这套标记，Dataview 就能按任意维度切：这个月完成了几个任务、哪些项目卡在 Blocked、某个技术方向下有几篇笔记。**这些统计表写一次，之后天天自动更新。**  到这儿，一套完整的学习产出工作流就搭好了。记录、聚合、统计、看板，全自动。 ## 三、但它有个补不上的窟窿 这套系统我用了不短的时间。它确实很擅长记录 —— 我想知道任何一个历史数据，翻一下就有。 **可它对「决策」这件事完全沉默。** 具体是四个坑： **第一，不知道今天该产出什么。** 系统能告诉我「有 12 个待办」，但没法告诉我「今天这 2 小时，做哪件事最值」。大目标是「掌握 AI Agent 工程能力」，可它切不出今天能做完的一小块。 **第二，每天都要自己做一遍决策。** 这是最耗神的部分。早上打开空白日记，从大目标推到今天的行动，全靠脑子现场算。做几个月之后，某天早上不想算了，系统就空转了。  **第三，学了很久拿不到反馈。** 笔记写完躺在硬盘里，没人看。发出去了，新号前两周点赞大概率是个位数。反馈迟迟不来，动力就一点点漏光。 **第四，文件都得手动整理。** 新建任务文件、填十几个 frontmatter 字段、把待办抄进日记、给待办补上 emoji 日期标记 —— 每天十来分钟的机械劳动。单看不多，但它正好卡在「刚有点动力想开始」的那个节骨眼上。  你发现了吗 —— 这四个坑，**没有一个是记录问题**。 前两个是决策问题，第三个是反馈问题，第四个是自动化问题。 而我那套系统，从模板到看板到统计表，全部是为了解决记录问题设计的。所以再装十个插件也没用，方向不对。 **这正好是 AI 该上场的地方。** ## 四、我用 Opus 5 + grill-me 造了一个 AI 智能化学习产出工作流 Skill 这套 Skill 我是用 Claude 目前最强模型之 **Opus 5** 配合一个全网安装量目前排名前三的神级 Skill —— **grill-me** 做出来的。 我一开始的需求很含糊，大概就是「帮我做一个以每日学习产出为导向的 AI 学习规划应用」。搁平时，AI 早就开始哗哗写代码了。 但 grill-me 先甩给我一堆选择题，逼我一个个钉死： - **用什么载体？** 直接写 Python 应用，还是先用 Cursor Skill + markdown 跑通流程？—— 我选了后者。写应用最大的风险是「搭工具」变成了「产出」本身，一个月过去，工具搭好了，学习一天没干。 - **数据放哪？** 新建一套数据库，还是直接读写现有的 Obsidian 库？—— 直接读写现有的。我要是再造一套平行结构，一个月后我会拥有两套系统和两份对不上的历史数据。 - **要不要自动发布？** —— 不要。只做格式转换和导出，发布这一步留给我自己。 - **验证多久再考虑写应用？** —— 连续跑 7 天。跑不满 7 天就不准写 Python，这是我给自己设的防线。 - **反馈数据怎么分析？** —— 前 7 天只记录不分析。一天一篇、样本这么小的时候，硬分析点赞波动只会得到一堆听着有道理的废话。 ### 补窟窿 1、每天早上替我做决策 早上一个命令 `df plan`，它会： 1. 读我的目标文件、昨天的日记、昨天的任务文件 —— 就这三个，不多读 2. 问我一组问题，**全部一次问完**：今天有多少可支配时间、昨天那件事做完了吗、实际花了多久 3. 然后给我一张候选表 我选一个，它就把行动计划写进任务文件和今天的日记，待办自动带上 `🛫` 日期标记 —— 我原有的 Todo 区块立刻就能查到。  ### 补窟窿 2、当天就给我反馈 晚上一个命令 `df ship`： 1. 问我今天做到哪了 —— 一句话就行，做完了 / 卡在哪 / 换方向了 / 没动 2. 把今天真做出来的东西写成成稿 3. **当场以第一读者的身份给我点评** 这里有个我觉得挺重要的判断：**反馈饥荒是个陷阱，动力不能挂在外部反馈上。**  ### 一个额外的好处：写作时间被强制预留 Skill 里有一条硬规则：行动计划必须给「把它变成成稿」这件事留出大约四分之一的时间，而且必须是一个独立的待办项。 因为一天全花在做、一点没花在写，等于什么都没产出 —— 这恰恰是最容易耗光动力的那种失败。 ## 最后 好了，一套能自己决定「今天产出什么」的学习工作流就搭完了。 早上一个命令拿到今天该做的事，晚上一个命令拿到成稿和点评，中间费事耗力的机械劳动全没了。 **工具不该只是个记录的地方，它应该能替你做掉那个最耗神的决定。** 不过这里我得说句实话：**这套 Skill 是我刚做完的，还没跑满一个完整周期。** 它的每一条规则背后都有明确的设计考量，但「设计得对」和「用起来真的有用」是两件事 —— 后者需要时间来验证，我现在还没有这个数据。 所以我想邀请你**和我一起跑这 7 天**： - 装上它，每天用 `df plan` 定计划、`df ship` 出成果 - 记下哪几步真用上了、哪几步是多余的、哪里卡住了 - 到仓库的 Issues 里说一声，或者在评论区聊 我会把这 7 天的改动全部推上去，**包括被我砍掉的步骤** —— 那部分通常比留下来的更有参考价值，它标记了哪些设计是我坐在椅子上想出来的。 第七天我会回来写一篇复盘：哪几步真用上了、哪几步是我想象出来的、以及这套东西到底值不值得继续。 > 开源指路：https://github.com/Jenniferwonder/daily-flywheel 代码全部是 markdown，没有任何黑盒，MIT 协议，随便改随便用。觉得有点意思的话，**给个 Star 支持一下~** ⭐🌹 想跟进后续改动的话，Watch 一下就行。   综上，这是我的学习产出工作流 skill 开源地址：`https://github.com/Jenniferwonder/daily-flywheel`，包含上述全部文章创作流优化，欢迎大家访问并给一个小星星鼓励支持⭐。我会继续使用并持续优化，也欢迎大家提 PR 和我一起优化！ > 开源指路：https://github.com/Jenniferwonder/daily-flywheel 我是公众号「瞻思于学」的 Jennifer，持续探索 AI 价值最大化实践，思考学习本质，分享学习工具和方法，欢迎关注我，共同进步！❤️ 欢迎在评论区聊聊：**你的笔记系统卡在哪一步？是不知道今天该做什么，还是做完了没人看？**
开源我的 Vibe Coding 工作流，已有人靠它把项目做完了
## 前言 > 如果这篇文章对你有帮助，欢迎先去给仓库点个 Star：[**project-vibe-spec**](https://github.com/dnwwdwd/project-vibe-spec)，这对我是很大的鼓励，也让更多人能找到这个工具。 大家好，我是汉堡。 上一篇文章《如何从0到1 Vibe Coding 一个项目，并长期维护》里，我分享了自己踩坑之后沉淀出来的一套 Harness 体系——用文档治理、AGENTS.md、范围冻结和分阶段推进来驯服 Vibe Coding 的混乱。 文章发出去之后，有鱼友来问我：**多个 AI Agent 接力做项目，怎么让它们互相"知道"彼此做了什么？** 答案就在那篇文章里。**多 Agent 之间通信和协作，唯一的方式只有文档。** 在项目根目录维护好 Agent 的"说明书"——Codex/OpenCode 对应 `AGENTS.md`，Claude Code 对应 `CLAUDE.md`——Agent 启动时自动注入，啥也不用说就知道项目的一切。 有人照着做了，昨天来告诉我：**"牛逼，用了文章里的内容之后，AI 的产出就稳多了，现在已经把项目做完了，感谢大佬。"** 这让我很开心。所以今天这篇文章，我想介绍一个更进一步的东西——我把那套方法论直接做成了一个可以复用的 **Agent Skill**。 --- ## 为什么要做成 Skill？ 上篇文章写的是**思路和方法**，但每次新建项目，你还是得自己手写 AGENTS.md、搭 docs/ 目录结构、想文档命名规范…… 重复劳动，而且容易遗漏。 所以我把这套体系沉淀成了一个开箱即用的 GitHub 仓库： > **👉 [https://github.com/dnwwdwd/project-vibe-spec](https://github.com/dnwwdwd/project-vibe-spec)** 如果这个 Skill 对你有帮助，欢迎点个 Star，这对我是很大的鼓励。 --- ## 这个 Skill 解决什么问题？ 回顾一下 Vibe Coding 的几个典型困境： - **上下文膨胀**：代码越多，AI 越难理解全貌 - **耦合蔓延**：改一处牵一发而动全身 - **意图退化**：没有文档，几轮对话后你自己都忘了当初为什么这么设计 - **多 Agent 失忆**：换一个 Agent 工具，之前的上下文全部归零 这些问题都可以追溯到同一个原因——缺乏工程化的文档治理。 `project-vibe-spec` 提供了一套完整的项目规范模板，让你在开始写第一行代码之前，就把"地基"打好。 --- ## Skill 里有什么？ ### 1. AGENTS.md 模板 这是整个体系的核心。AGENTS.md 干的事情只有一件：**让 AI 知道你的编码哲学和项目规范，不用每次都重复交代。** 对于 Codex/OpenCode，启动时会自动将项目级别和全局的 AGENTS.md 注入当前对话上下文。你啥也不用说，Agent 就知道： - 项目的技术栈和架构 - 代码风格和命名规范 - 禁止的行为（比如不要擅自改架构、不要顺手加功能） - 文档优先级和冲突解决规则 - 完成标准（DoD） ### 2. 文档治理体系 一套完整的文档分类规范： | 文档类型 | 命名格式 | 用途 | | --- | --- | --- | | **REQ** 需求文档 | `REQ-YYYYMMDD-XX-*.md` | 新功能或大范围改造前必写 | | **PROG** 进度日志 | `PROG-YYYYMMDD.md` | 每天一日志，记录完成了什么 | | **BUG** 缺陷记录 | `BUG-YYYYMMDD-XX-*.md` | 发现 bug 立即记录 | | **BIZ** 业务决策 | `BIZ-YYYYMMDD-XX-*.md` | 业务流程或实现策略的确认 | | **DEV** 技术方案 | `DEV-YYYYMMDD-XX-*.md` | 复杂模块拆解、阶段实施方案 | 这套体系的价值： - **上下文外挂**：AI 每次对话前先读相关文档，不会丢失上下文 - **可追溯**：三个月后回来，还能知道当初为什么这么设计 - **可交接**：换一个 AI 模型或工具，读一遍文档就能接手 ### 3. 分阶段推进模板（Phase 0 → Phase N） 大项目一口气让 AI 实现 = 灾难。必须拆阶段，每个阶段有明确的 DoD（Definition of Done）： | 阶段 | 内容 | DoD | | --- | --- | --- | | **Phase 0** | 文档体系初始化 | AGENTS.md、README.md、docs/ 结构就绪 | | **Phase 1** | 后端骨架 | 服务可启动、配置可读、数据库可初始化 | | **Phase 2\~3** | 核心链路 | 端到端链路跑通 | | **Phase 4** | 业务 API | 接口字段对齐、错误响应统一 | | **Phase 5** | 前端工程化 | 拆页拆组件、接入真实 API | | **Phase 6\~7** | 收尾上线 | 链路闭环、打包部署 | 每个 Phase 结束必须达到 DoD 才能进入下一阶段。这个纪律不能破。 ### 4. 范围冻结清单 v1 要做什么、不做什么，在一开始就写死。一旦范围冻结，后续开发中 AI 想"顺手"加功能时，你就可以说：**"不在 v1 范围，先记 REQ，下个版本再说。"** --- ## 怎么用？ 直接 clone 或 fork 这个仓库，把模板文件复制到你的项目根目录，按照说明填写你的项目信息即可。 ```bash git clone https://github.com/dnwwdwd/project-vibe-spec ``` 然后把 `AGENTS.md`、`docs/` 目录结构复制到你的项目里，根据你的项目实际情况填写内容。 --- ## 真实反馈 这套方法论有人真的用了。 有读者看了上篇文章之后，把这套文档治理的思路用到了自己的项目上。几天后来反馈：**AI 的产出稳定了很多，项目已经做完了。** 我写这篇文章、做这个 Skill，就是想把这套工程化方法变成别人可以直接用的东西，不用每个人再从头踩一遍。 --- ## 最后 Vibe Coding 的问题不在 AI 的能力，在我们给 AI 的上下文质量。 一个没有文档、没有规范、没有阶段划分的项目，再强的模型也推不动。换上完整的 Harness 体系——文档治理、阶段划分、范围冻结——用中等模型也能稳定推进。 `project-vibe-spec` 就是帮你把这个"地基"快速搭起来的工具。 仓库地址：<https://github.com/dnwwdwd/project-vibe-spec> 如果觉得有用，可以点个 Star，或者在评论区聊聊你的使用体验。 --- ## 相关文章 - [如何从0到1 Vibe Coding 一个项目，并长期维护](https://blog.hejiajun.com) --- *我的博客：[https://blog.hejiajun.com](https://blog.hejiajun.com)*
RKit：我常用的 uTools 工具的“轻量替代”
我以前一直用 `uTools`。 说实话，它在我这儿属于那种“装机必备”级别的工具：搜东西、翻译、截图、OCR、剪贴板……一堆日常零碎事，按个热键就能搞定。 但后来 uTools 越来越臃肿，也开始限制插件数量，这我还能忍，毕竟我平时用的插件也不多，最让我绷不住的是：**开始强制登录**了。 我不是说登录就一定不好，我只是很不喜欢“一个本来用来提升效率的小工具”，慢慢变成“需要账号体系才能用”的东西 于是我就去找“uTools 平替”。 我试了 `zTools`，确实和utools差不多，但用了一段时间总觉得有些地方不太对：要么是某个流程不顺手，要么是细节不符合我的习惯。也不是不能用，就是用的时候会忍不住嘀咕一句：“要是这里能这样就好了……” 结果我一想：我每天高频用的功能就那几个，**干脆我自己做一个算了**。 于是就有了 `RKit`。 --- ## RKit 是个啥？一句话 `RKit` 就是一个 **macOS 上的命令面板**(后面也会做 windows)，有点像 Spotlight： 按热键 → 弹出一个小面板 → 执行动作。 我不想做插件市场，也不想做一堆花里胡哨的功能。 我就想把我每天用的那几个能力做得**顺手、够快、够稳定**。 --- ## 它能干啥？就我常用的这几个 我现在最常用的是这些： - `截图`：区域截图 → 自动复制到剪贴板 → 顺手还能进内置编辑器改两笔 - `OCR`：对最近一次截图做文字识别（macOS 自带 `Vision`） - `翻译`：默认 Google GTX（不用 key），也可以配 Deeplx（自己搭个接口那种） - `剪贴板历史`：文本 + 图片，支持置顶/搜索，还能一键暂停采集 10 分钟 - `设置`：语言、热键录制、开机自启动、清理历史这些 你会发现，它就是“uTools 里我真正每天在用的那几个东西”。  --- ## 我做它最在意的点 ### 1）快：要像 Spotlight 那样“按下就出来” 默认热键是： - `Option + Space`：呼出/关闭 - `Esc`：关闭 我希望它是那种你不需要思考的动作： 手指一按，它就出现；你输入，回车，事情结束。 ### 2）别打扰：别把我从当前桌面/当前软件拽走 有些工具的面板会乱跳桌面，或者截图完又把焦点抢回去，这种我很难忍。 RKit 的目标是：**你在哪儿用，它就在哪儿出现**，尽量别干扰你的主工作流。 ### 3）本地优先：默认不联网 我个人比较敏感的一点是： 这种工具一旦开始“强制登录”，我就会下意识担心：我输入的东西、剪贴板、截图，会不会被上传、被统计、被分析？ RKit 的原则很简单： - 默认本地优先 - 只有“翻译”可能要联网（你选的翻译服务决定） --- ## 怎么装？（现在是未签名 ZIP） RKit 目前走的是 **未签名 ZIP** 发布（主打一个快，先让大家用起来）。 ### 安装步骤 1. 从 GitHub Releases 下载 `RKit.app.zip` 2. 解压得到 `RKit.app` 3. 把 `RKit.app` 拖到 `/Applications` 4. 打开运行 ### 如果被 Gatekeeper 拦了（无法打开 / 提示“已损坏”） 先确认你已经把 `RKit.app` 拖到了 `/Applications`，再执行： ```bash xattr -dr com.apple.quarantine /Applications/RKit.app ``` 然后 Finder 里右键 `RKit.app` → `打开`。 --- ## 权限这块：截图一定会要“屏幕录制” 截图功能需要 macOS 的“屏幕录制”权限： `系统设置 → 隐私与安全性 → 屏幕录制 → 勾选 RKit` 这块没啥好绕的，系统规则就是这样。 我能做的就是把引导写清楚、交互做顺，不搞那些“偷偷申请一堆你用不到的权限”。 --- ## 后续计划 我不会把 RKit 做成“全能工具”，我更想把它做成一种**很顺手的日常习惯**： 有什么我高频使用的功能，我会添加进去 也会尽快开发 windows 版本 --- ## 致谢 - Deeplx（DeepLX）：<https://github.com/OwO-Network/DLX> 感谢 DeepLX 开源项目：它使得在自建环境中通过本地 API 方式使用 DeepL 的免费网页翻译成为可能。 我就是使用本地部署的地址：  --- ## 最后 做 RKit 的起点其实很简单： 我只是想要一个“不臃肿、不强制登录、只做我常用功能”的工具。 如果你也跟我一样日常使用这几个工具，欢迎来试试看。 如果遇到什么问题，欢迎随时指出。 如果你觉得项目对你有帮助，欢迎点个Star，感谢！！ 项目地址：[https://github.com/Han-GR/rkit](https://github.com/Han-GR/rkit) 下载地址：[https://github.com/Han-GR/rkit/releases/download/v1.0.1/RKit.zip](https://github.com/Han-GR/rkit/releases/download/v1.0.1/RKit.zip)
开源一个能自动发现和分析 GitHub 仓库的 AI Skill 与全栈应用
大家好，我是汉堡🍔。 今天来聊一个很有意思的话题——**同一个功能，用两种完全不同的方式实现，会是什么体验？** 事情的起因是这样的：我在懒猫搬砖做副业的时候，经常需要去 GitHub 上找适合移植的开源项目。手动翻实在太累了，于是我就想——能不能写个工具自动帮我爬、帮我判断？ 说干就干。但有趣的是，我前后做了**两个版本**：一个叫 **GitHub Repo Crawler**，是个 AI Agent Skill；另一个叫 **RepoRadar**，是个完整的全栈应用。 功能核心是一样的——爬 GitHub 仓库、分析能不能用、推送到飞书。但形态天差地别。下面分别聊聊它们。 --- ## 博客文章链接 https://blog.hejiajun.com/archives/kai-yuan-yi-ge-neng-zi-dong-fa-xian-he-fen-xi-github-cang-ku-de-ai-skill-yu-quan-zhan-ying-yong ## GitHub Repo Crawler：把能力装进 AI Agent 的口袋 **仓库地址**：<https://github.com/dnwwdwd/github-repo-crawler> ### 它是什么？ 简单说，它是一个 **AI Agent Skill**——给 Claude Code、opencode、Codex 这类 AI 编程助手用的「插件」。 如果你用过 Claude Code 的 Skill 机制，就很好理解：它就是一个 `SKILL.md` 文件，告诉 AI「你现在有了爬取 GitHub 仓库的能力，遇到相关任务就自动调用」。 ### 怎么用？ 不需要部署，不需要启动服务。你只需要把这个 Skill 装到你的 AI Agent 里，然后在对话里直接说： > 「帮我搜一下最近一周 GitHub 上 Star 增长最快的 Python 开源项目」 「看看这个仓库适不适合移植到懒猫微服」 AI 就会自动激活这个 Skill，调用 GitHub API 去搜索、分析，然后把结果吐给你。 ### 适合谁？ | 场景 | 说明 | | --- | --- | | 🧑💻 **AI 重度用户** | 已经习惯了在 Claude Code / Codex 里干活的人，加个 Skill 就能用 | | ⚡ **临时需求** | 偶尔想搜一下 GitHub 仓库，不想专门跑个应用 | | 🔧 **轻量级** | 不需要持久化数据、不需要后台定时任务，用完即走 | **产物**：一次对话 + 即时结果。 --- ## RepoRadar：一个完整的 GitHub 仓库监测系统 **仓库地址**：<https://github.com/dnwwdwd/repo-radar> ### 它是什么？ RepoRadar 是一个**完整的全栈 Web 应用**，不只是「搜一下」，而是「持续监测」。 技术栈一览： | 层级 | 技术 | | --- | --- | | **后端** | Python FastAPI | | **前端** | React + Vite + TypeScript | | **数据库** | SQLite | | **调度** | APScheduler 定时任务 | | **通知** | 飞书 SDK（即时推送 + 每日汇总） | | **AI 分析** | Agent ReAct 模式分析仓库质量 | | **部署** | 单容器 Docker，一键跑起来 | ### 它做了什么？ RepoRadar 的完整工作流是这样的： ```plaintext GitHub Search 抓取 → 规则过滤 → 去重入库 → Agent 分析 → 飞书推送 ``` 并且这套流程是**自动定时跑的**，不需要人盯着。 具体来说，v1 版本冻结了以下功能： - ✅ GitHub Search 抓取（按关键词、语言、Star 数等维度搜索） - ✅ 规则过滤 + 去重 + 入库 - ✅ Token 降级与失效自动暂停 - ✅ **Agent 智能分析**：自动判断仓库质量、技术栈、移植难度 - ✅ 优先级队列 + 失败重试 - ✅ 仓库列表 + 筛选 + 详情展开（Web 界面） - ✅ 手动提交单个 GitHub URL（插队分析） - ✅ 系统状态页 + 配置中心热重载 - ✅ **飞书即时推送** + 每日汇总 - ✅ 单容器懒猫微服打包 同时，为了控制范围、避免 Vibe Coding 时「管不住手」，明确不进 v1 的功能有：Star 增速监控、批量提交、导出 CSV、多数据源、语义去重等——这些留给后续版本。 ### 适合谁？ | 场景 | 说明 | | --- | --- | | 🏢 **团队使用** | 部署一个实例，全团队都能通过 Web 界面看、飞书收推送 | | 🔄 **持续监测** | 不是搜一次就完了，而是定时跑、自动分析、主动推送 | | 📊 **数据沉淀** | 仓库数据持久化存储，有历史记录、可筛选可回溯 | | 🎯 **副业/业务场景** | 懒猫移植这种有稳定需求的工作流，需要系统化工具 | **产物**：一个跑在服务器上的 Web 应用 + 飞书群里的每日推送。 --- ## 核心对比：Skill vs 全栈应用 两个项目功能一样，形态不同，本质上是**两种解决问题思路**的体现： | 维度 | GitHub Repo Crawler（Skill） | RepoRadar（全栈） | | --- | --- | --- | | **形态** | AI Agent 插件（SKILL.md） | 独立 Web 应用 | | **启动方式** | 对话中自动激活 | Docker 部署 / 手动启动 | | **交互方式** | 自然语言对话 | Web 界面 + 飞书推送 | | **数据存储** | 不持久化（对话即数据） | SQLite 持久化，历史可查 | | **定时任务** | ❌ 无（按需触发） | ✅ APScheduler 定时抓取 | | **多用户** | ❌ 单人使用 | ✅ Web 界面多人可访问 | | **通知推送** | 对话内返回结果 | 飞书即时推送 + 每日汇总 | | **Agent 分析** | AI 本身就是 Agent | 内置 ReAct Agent 自动分析 | | **上手门槛** | 极低（装 Skill 即可） | 中等（需要部署） | | **适合场景** | 个人临时使用、AI 工作流 | 团队持续使用、业务系统 | 一句话总结： > **Skill 版是「随叫随到的超级实习生」——你问它就干。RepoRadar 是「专职的后台管家」——部署好之后自己定时跑，干完了主动通知你。** --- ## 为什么做两个版本？ 其实这背后有一个挺有意思的思考。 RepoRadar 是我用 **Harness 体系**（文档驱动 + 范围冻结 + 分阶段开发）认真做的全栈项目，前后分了 8 个 Phase，写了完整的 PRD、AGENTS.md、技术文档。它是一个**工程化的产物**。 但后来我发现：很多时候我只是想快速搜一下 GitHub 仓库，不想打开浏览器、不想登录系统。这时候如果能在 Claude Code 的对话里直接问一句就好了。 于是就有了 GitHub Repo Crawler——把核心能力抽出来，做成 AI Agent 的 Skill。**不需要部署、不需要界面、不需要数据库**，对话就是一切。 这两个版本不是替代关系，而是**互补关系**： - 日常快速搜索 → 用 Skill - 团队持续监测 → 用 RepoRadar --- ## 写在最后 同一个功能，两种形态，背后是两种截然不同的设计哲学： - **Skill 的思路**：把工具嵌入 AI 的工作流，让 AI 来调用，人只需要对话。 - **RepoRadar 的思路**：把工具做成独立系统，定时自动运转，人只需要看结果。 没有谁好谁坏，只有适不适合。如果你也是 AI 重度用户，强烈建议试试把常用功能做成 Skill——那种「在对话里随口一问就有答案」的体验，真的回不去了。 两个项目都是开源的，欢迎 Star 和 PR 👇 - 🔧 GitHub Repo Crawler：<https://github.com/dnwwdwd/github-repo-crawler> - 📡 RepoRadar：<https://github.com/dnwwdwd/repo-radar> --- *本文由汉堡🍔原创，首发于个人博客 [blog.hejiajun.com](https://blog.hejiajun.com/)*
GitHub 每周精选｜2026 W28
GitHub 上每天都会冒出很多新项目。 大多数我都会看过就忘。 有些看起来很酷，但装完就吃灰。 还有一些，会让我真的想留下来继续折腾。 我想把这些项目记录下来。 不追求“最火”。 只记录那些： 让我真正想装下来试试的东西。 **ps：最近半个月在期末周和实习中，现在算是稳定下来，可以正常恢复更新了** --- ### 1. caveman 项目名：caveman GitHub 仓库地址： https://github.com/JuliusBrussee/caveman 你在使用 AI 的时候有没有这种感觉，就是他们有时候太爱铺垫了，明明一句 "这里单位错了" 就能说清，它非要绕一圈 "根据您的需求，我建议……" 如果是直接订阅制的 GPT 这种还好，但如果是用的 API 的方式，那 AI 输出的那些可有可无的话，就真的是在烧钱了，毕竟 token 是按照输入和输出计的嘛，如果能够让 AI 在输出端减少那些可有可无的话，也算是在省钱了 这个仓库做的就是这件事情：**让 AI coding agent 少说废话** 这个仓库的 star 数量截止到目前为止有 **88.3k**，可见大家是有多么需要这个功能 严格说，它不是两个 skill，而是同一个 `caveman` skill 里的两个常用档位：`lite` 和 `full` `lite` 比较像“正常人少废话版”，句子还完整 `full` 更短，允许片段句，更像只给你结论。不用它时，回答通常最完整，但也最容易啰嗦 我也做了个很小的对比实验：同一道 JWT 过期判断题，分别让 normal、`caveman lite`、`caveman full` 回答。三组都准确指出核心问题：JWT `exp` 是秒，`Date.now()` 是毫秒，也都给出了正确修复。区别主要在表达长度：normal 最完整，lite 最均衡，full 最短但没丢关键点 **所以我会更推荐从 `lite` 开始日常用；上下文你已经很熟、只想快速看结论时，再切 `full`** --- ### 2. 办公四件套 项目名：办公四件套 GitHub 仓库地址： https://github.com/anthropics/skills/tree/main/skills 对的，经典的办公四件套，也就是 docx、xlsx、pdf、pptx 我是这周实习时一位老师和我说，ta 在使用 codex 时识别和修改 Word 文档效果不好，才知晓 ta 没有安装办公四件套对应的 skill 的，于是就把这几个 skill 推荐给 ta 简单来说一下这几个 skill 的功能，其实从名字也能看出来了，所以就简单带过一下 有了它，就能让 AI Agent 来**读取和修改**上面提到的办公四件套类型的文件了，如果不装的话，其实也是可以读取的，但是效果是没有安上好的，**建议所有职场办公的小伙伴们安装一下**，star 数量 160k，恐怖如斯  --- ### 3. CodexBar 项目名：CodexBar GitHub 仓库地址： https://github.com/steipete/CodexBar 你是不是也遇到过这种情况： 正用 AI 写代码，思路刚顺起来，结果突然弹出一句“额度用尽” **如果你只用一个 AI 编程工具，额度用完了就等它恢复，问题不大** 真正麻烦的是同时用好几个工具的人：Codex、Claude、Cursor、Copilot、Gemini，每个工具都有自己的额度、重置时间和使用窗口。信息都能查到，但散在不同地方 **CodexBar 做的就是把这些信息收拢到一起** CodexBar 是一个 macOS 菜单栏工具。装好之后，它会把你常用 AI 编程服务的用量、剩余额度、重置时间放到菜单栏里。你不用每次打开官网，也不用临时跑命令查状态，抬眼看一下菜单栏，大概就知道现在还能用多少 它有点像 AI 编程工具的“油量表” 不过这里有几个点要先说清楚 第一，CodexBar 目前的菜单栏 App 只支持 macOS 14+，**也就是主要面向 Mac 用户**。项目里有 CLI 相关构建，但如果你想要的是菜单栏里的完整体验，那目前就是 Mac。 第二，**它统计的是官方账号、官方 API、官方 CLI、本地配置或浏览器登录态能拿到的数据**。也就是说，如果你是通过普通中转 API、第三方代理站、共享 Key 之类的方式在用 OpenAI 或 Claude，它通常没法帮你统计官方账号里的真实额度和重置窗口。除非那个中转服务本身也提供了 CodexBar 支持的用量接口，否则这里看不到。 第三，它不是让你把账号密码交给它。CodexBar 主要复用你本机已有的登录状态、CLI 凭据、Cookie、OAuth、API Key 或本地文件。不同服务的数据来源不一样，有些需要浏览器 Cookie，有些需要 API Key，有些读本地 CLI 配置。 目前 CodexBar 支持的服务非常多，不只是 Codex、Claude、Cursor 这几个。按项目里的注册列表看，已经覆盖了 58 个 provider：  所以，如果你每天都在用 AI 写代码，经常在 Codex、Claude、Cursor、Gemini、Copilot 之间切换，关心今天还剩多少额度、下次什么时候重置，那 CodexBar 就很值得装一下  --- ### 4. feishu-CLI 项目名：feishu-CLI GitHub 仓库地址： https://github.com/larksuite/cli 如果你所在公司的主要内容都在飞书当中，那么 feishu-cli 一定会给你惊喜的，通过 codex、claude code 就能操作飞书当中的各种内容 如果你目前还没有上班或者公司的主平台不在飞书，但要做数据搜集之类的事情，比如我自己的 GitHub-Star-Top 所抓取的数据，所抓取的爆款封面的数据，以及现在实习期间搭建的内容都是放在飞书多维表格当中的 配合飞书机器人也能实现各种操作的自动化，比如我是实现了开源仓库初筛和选题池入池的自动化、各个平台数据抓取的自动化等等 所以如果你做数据抓取，那么 feishu-cli 很值得你去试一试，爱飞书～  --- ### 5. frontend-design & UI UX Pro Max 项目 1：frontend-design 项目 2：UI UX Pro Max 项目 1 仓库地址： https://github.com/anthropics/skills/tree/main/skills/frontend-design 项目 2 仓库地址： https://github.com/nextlevelbuilder/ui-ux-pro-max-skill AI 编程几乎是一定会需要做前端页面的，那么关于 UI 的审美问题，如果在不给 AI 任何提示的情况下，**一般都会做出来经典的蓝紫色配色的页面，丑的一批...** 这两个仓库就是来解决 AI 在做前端页面的审美问题的，那可能有小伙伴有疑问： **这两个仓库都是解决前端的审美问题的，那我应该如何选择呢？** 好问题，在测这两个仓库的时候，我用同一个主题进行了测试了，下面是我的一些个人感受，供大家参考 这轮测试里，主题均是 "睡眠" 的手机 APP 产品介绍页 frontend-design 它**只做了一轮轻量需求澄清，就直接进入执行**，产物更有品牌感和审美记忆点 ui-ux-pro-max 更像设计系统顾问，它会在设计对齐、产品类型、UX 约束和页面结构上花更多时间；如果用户只是一路说“继续”，它可能会产出更稳但不够惊艳的方案（我是一路 "继续吧" 跑下来的），**但我之前也是用 ui-ux-pro-max 做出过很漂亮的页面的，只是在这次的测试当中表现确实不好** ui-ux-pro-max 会倾向于反复给反馈、精修方向、调整风格、配色、字体和交互约束时，能更系统地把 UI 打磨起来 所以我的判断如下： - 快速 Demo：优先 `frontend-design` - 想要第一眼好看、有风格、有惊喜：优先 `frontend-design` - 想做设计系统、UX 规则、跨页面一致性：优先 `ui-ux-pro-max` - 愿意多轮对齐、精雕细琢：`ui-ux-pro-max` 更值得用 - 普通用户不想回答太多问题：`frontend-design` 体验更轻 - 有明确产品方向、愿意参与设计决策：`ui-ux-pro-max` 上限可能更高 用 frontend-design 跑的一个 demo  --- 最后： 后面肯定还会继续遇到： 让我真正想装下来试试的项目。 这个系列也会继续更新下去。
手把手教你：GitHub CI + PyPI 自动发包，从此告别手动 twine upload
> 最近写了个 Python 练手项目，本地跑得挺顺，盘算着发到 PyPI 上，让别人也能一行 `pip install` 就用起来。本来以为 `poetry build` + `twine upload` 就完事了，结果一脚踩进 GitHub Actions 的世界，从 CI 配置到 Trusted Publisher 认证，从 Poetry 依赖解析到版本号踩坑，一路上“惊吓”不断。折腾了一晚上，才把整条链路跑通。谨以此文，纪念熬的又一个夜——不算什么高深教程，但每个坑都是实打实踩过的，希望能帮后来的同学少绕几个弯。 --- ## 先搞清楚几个名词 在开始之前，得先弄明白三个东西，不然 YAML 文件抄都抄不明白。 ### CI 是啥？ CI = Continuous Integration，翻译过来就是"持续集成"。听着高大上，其实就是：**你每次提 PR，GitHub 帮你自动跑测试**。 ``` 你 push 代码 → GitHub 开一台虚拟机 → 跑 pytest → 绿了 ✅ 或者 红了 ❌ ``` 说白了就是一个比你更勤快的同事，每次你改了代码都帮你检查一遍。 ### GitHub Actions 又是啥？ 就是 GitHub 内置的"自动化引擎"。你在仓库的 `.github/workflows/` 目录下扔一个 YAML 文件，GitHub 就会在云端给你开一台机器，按你说的干活。 ```yaml on: push jobs: say-hello: runs-on: ubuntu-latest steps: - run: echo "hello world" ``` 就这么简单。每次 push 代码，GitHub 就帮你打印一个 hello world。 ### Release 呢？ Release 就是 GitHub 上的"版本快照"。你觉得代码写得差不多了，就打个 Release，绑一个 Git tag（比如 `v0.1.0`），写几句变更说明。它本身不干啥，但它是触发 PyPI 自动发包的"开关"。 ### 三者的关系 简单画个流程图： ``` 你提 PR 到 main │ ▼ GitHub Actions 自动跑测试 │ ├── 红了 ❌ → 回去改 bug │ ▼ 绿了 ✅ 合并到 main │ ▼ 在 GitHub 上打个 Release │ ▼ GitHub Actions 自动构建 + 上传 PyPI │ ▼ 别人可以 pip install 你的包了 🎉 ``` --- ## 第一步：把项目结构搞对 项目的目录长这样： ``` my-project/ ├── .github/ │ └── workflows/ │ ├── ci.yml # 自动测试 │ └── release.yml # 自动发包 ├── my_project/ # 你的 Python 代码 │ ├── __init__.py │ └── ... ├── pyproject.toml # 项目的"身份证" └── ... ``` 重点是 `pyproject.toml`，这玩意儿是整个发布流程的核心。我用的是 Poetry，配置长这样： ```toml [project] name = "my-project" version = "0.1.0" description = "一个示例项目" authors = [{name = "Your Name", email = "you@example.com"}] license = {text = "MIT"} readme = "README.md" requires-python = ">=3.12,<4.0" dependencies = [ "requests>=2.31", ] [project.scripts] my-cli = "my_project.cli:main" [tool.poetry] packages = [{include = "my_project"}] [tool.poetry.group.dev.dependencies] pytest = ">=7.0" [build-system] requires = ["poetry-core>=2.0.0,<3.0.0"] build-backend = "poetry.core.masonry.api" ``` 这里面有几个坑，我后面会专门讲。先照着抄，别自己发挥。 --- ## 第二步：搭 CI（自动测试） 创建 `.github/workflows/ci.yml`： ```yaml name: CI on: pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: ["3.12", "3.13"] steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} - name: Install Poetry run: | pip install poetry poetry config virtualenvs.create false - name: Install dependencies run: poetry install --with dev - name: Run tests run: pytest -v || [ $? -eq 5 ] ``` 几个值得注意的地方： **`matrix`**：同时在 Python 3.12 和 3.13 上跑测试。GitHub 会开两台机器并行，确保两个版本都兼容。 **`virtualenvs.create false`**：GitHub Actions 的 runner 每次都是全新的，不需要再搞个虚拟环境，直接装到系统 Python 就行。 **`pytest -v || [ $? -eq 5 ]`**：pytest 退出码 5 表示"没有收集到任何测试"。项目刚开始没测试文件的时候，CI 不会因为这个红掉。等你写了真正的测试，该红还是会红。 提 PR 到 main 之后，去 Actions tab 就能看到结果了。绿了就 merge，红了就改。 --- ## 第三步：配置 PyPI Trusted Publisher ### 什么是 Trusted Publisher？ 以前发 PyPI 要手动生成 API Token，然后存到 GitHub Secrets 里。Trusted Publisher 是 PyPI 推出的新方式：**用 OIDC 认证，不需要管 Token**。 原理说人话就是：GitHub Actions 运行的时候，可以向 GitHub 证明"我确实是这个仓库的这个 Workflow"，然后 PyPI 验证这个证明是否和你之前配置的一致。一致就放行。 ### 怎么配？ **PyPI 那边**：去 [https://pypi.org/manage/account/publishing/](https://pypi.org/manage/account/publishing/)，在「添加新的待定发布者」里填： | 字段 | 填啥 | | ----------------- | --------------------------- | | PyPI project name | 你的包名，比如 `my-project` | | Owner | GitHub 用户名 | | Repository name | GitHub 仓库名 | | Workflow name | `release.yml` | | Environment name | `pypi` | **GitHub 那边**：去仓库 → Settings → Environments → New environment，名字填 `pypi`，直接保存。 两边的名字必须**一模一样**，大小写都不能差。我当时 Environment name 填了 `Pypi`，结果报了个 `invalid-publisher`，排查花费了2.5根头发。 --- ## 第四步：配置自动发包 创建 `.github/workflows/release.yml`： ```yaml name: Release to PyPI on: release: types: [published] jobs: build: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: "3.12" - name: Install Poetry run: pip install poetry - name: Build package run: poetry build - name: Upload build artifacts uses: actions/upload-artifact@v4 with: name: dist path: dist/ publish-pypi: needs: build runs-on: ubuntu-latest environment: pypi permissions: id-token: write steps: - name: Download build artifacts uses: actions/download-artifact@v4 with: name: dist path: dist/ - name: Publish to PyPI uses: pypa/gh-action-pypi-publish@release/v1 ``` `environment: pypi` 和 `id-token: write` 是 OIDC 认证的关键，少了哪个都发不上去。 流程是这样的：你在 GitHub 上点"Create Release" → Actions 自动构建 `.whl` 和 `.tar.gz` → 用 OIDC 认证上传到 PyPI → 别人就能 `pip install` 了。 --- ## 发版的完整流程 日常开发和发版，就这三步： ```bash # 1. 改版本号（pyproject.toml 里的 version） # version = "0.2.0" # 2. 提交推送 git add pyproject.toml git commit -m "chore: bump version to 0.2.0" git push origin main # 3. 去 GitHub 打 Release（tag 填 v0.2.0，点 Publish） ``` 然后就不用管了。Actions 会自动帮你构建、上传。去 PyPI 搜一下你的包名，新版本就在那了。 版本号推荐用语义化版本（SemVer）： ``` v 主版本 . 次版本 . 补丁版本 │ │ │ │ │ └─ 修了个 bug │ └─────────── 加了个新功能 └───────────────────── 改了 API，不兼容旧版 ``` **注意**：PyPI 不让重复上传同一个版本号。你要是忘了改 version 就打 Release，Actions 会报 `400 Bad Request`。别问我怎么知道的。 --- ## 踩坑实录（血泪教训） ### 坑 1：`Group(s) not found: dev` CI 跑到 `poetry install --with dev` 就挂了，报错说找不到 dev 组。 原因是 dev 依赖写错了位置。Poetry 只认 `[tool.poetry.group.dev.dependencies]`，不认 `[project.optional-dependencies]`。 ```toml # ❌ 这样写 Poetry 不认 [project.optional-dependencies] dev = ["pytest>=7.0"] # ✅ 要这样写 [tool.poetry.group.dev.dependencies] pytest = ">=7.0" ``` 这俩长得差不多，但 Poetry 就是不认前者。属于"看起来对但就是不行"的那种坑。 ### 坑 2：`No file/folder found for package` 把 PyPI 包名从 `mochi-agent` 改成了 `mochi-assistant`，结果构建时报错说找不到包。 原因是 Poetry 默认按包名找目录。包名 `mochi-assistant`，它就找 `mochi_assistant/` 目录。但实际目录叫 `mochi_agent/`。 解决办法：要么改目录名（我选了这个），要么在 `pyproject.toml` 里显式指定： ```toml [tool.poetry] packages = [{include = "mochi_agent"}] ``` ### 坑 3：Poetry lock 报 Python 版本不兼容 `requires-python = ">=3.12"` 写得挺好，结果 `poetry lock` 报了一堆版本冲突。 原因：没写上界，Poetry 认为你的包支持 Python 4.0+。但 `langchain-core` 这些库声明了 `python < 4.0`，Poetry 发现"你的范围比它的大"，就觉得不兼容。 加个上界就好了： ```toml # ❌ 没上界 requires-python = ">=3.12" # ✅ 加上界 requires-python = ">=3.12,<4.0" ``` ### 坑 4：Trusted Publisher 认证失败 报错 `invalid-publisher: valid token, but no corresponding publisher`。 意思是：GitHub Actions 确实拿到了一个 OIDC token，但 PyPI 那边找不到和它匹配的配置。 排查方法：看 Actions 日志里的 claims，逐项和 PyPI 上的配置对比： ``` sub: repo:Owner/Repo:environment:pypi ← Environment 要对 repository: Owner/Repo ← 仓库名要对 workflow_ref: .../release.yml@refs/tags/v0.1.0 ← Workflow 名要对 environment: pypi ← 大小写要对 ``` 我当时的问题是 GitHub 上没创建 Environment。光在 PyPI 配了 Trusted Publisher，GitHub 那边也要建一个同名的 Environment 才行。 ### 坑 5：pip install 时疯狂下载历史版本 装我的包时，pip 把 `langgraph` 从 1.2.7 一路下载到 0.6.x，装了十几分钟。 原因是 `pyproject.toml` 里写了 `langgraph>=0.1.0`，pip 的依赖解析器从最新版开始试，发现和已安装的 `langchain` 版本不兼容，就一个一个往回试。 解决办法：收紧依赖下限。当前用的是 1.2.7，就写 `>=1.2.0`，别写 `>=0.1.0`。 --- ## 不用 Trusted Publisher 的话 如果你不想配 Trusted Publisher（或者要发到 TestPyPI），可以用 API Token： 1. 去 [https://pypi.org/manage/account/token/](https://pypi.org/manage/account/token/) 创建 token 2. 去 GitHub 仓库 → Settings → Secrets → Actions → New secret - Name: `PYPI_API_TOKEN` - Value: `pypi-` 开头的那串 3. `release.yml` 的 publish 步骤改成： ```yaml - name: Publish to PyPI uses: pypa/gh-action-pypi-publish@release/v1 with: password: ${{ secrets.PYPI_API_TOKEN }} ``` 不过还是推荐 Trusted Publisher，不用管 token 过期的问题，配一次就行。 --- ## 最后 整套流程搞下来，发现其实不复杂，就是 YAML 文件 + PyPI 配置 + GitHub Environment 三件套。难的是第一次配，各种小坑会把你绊住。 配好之后就很舒服了：写代码 → 提 PR → CI 自动测 → merge → 打 Release → 自动发包。全程不用碰 `twine`，也不用记密码。 希望这篇文章能帮你少踩几个坑。祝发包顺利 🚀