HelloAGENTS 项目知识库实战:.helloagents 目录如何让 Agent 跨会话记住项目

原创2026-10-31 23:54:321,926 阅读

HelloAGENTS 项目知识库实战:.helloagents 目录如何让 Agent 跨会话记住项目

用 AI 写代码最让人抓狂的一点,是它经常"转头就忘"。你刚纠正过的命名习惯、上周踩过的坑、项目的技术栈和验证命令,每次新开会话都要从头再讲一遍。HelloAGENTS 用一个项目级的 .helloagents/ 目录解决了这个问题:它把项目知识库、方案包和会话恢复状态都落到磁盘上,让 Agent 跨会话、跨工作区都能"记住"项目,不用反复重新理解同一批事实。

本文带你从零看懂这个目录的每个文件,以及它如何把 Agent 从"健忘实习生"变成"熟悉项目的老成员"。

为什么 Agent 总是"失忆"?

没有持久化时,Agent 的所有"记忆"都活在聊天窗口里。窗口一关、会话一切换,项目上下文就清零:

  • 反复解释:技术栈、架构、模块划分每次都要重新描述。
  • 约定丢失:命名规范、提交格式、测试要求等"从代码看不出来的约定"无处安放。
  • 状态断裂:长任务做到一半中断,恢复时 Agent 不知道上一步做到哪、下一步该干什么。
  • 重复踩坑:上次调试发现的坑,这次又会原样踩一遍。

HelloAGENTS 的思路是:把"应该记住的东西"从对话里挪到 .helloagents/ 目录,形成一份可被后续会话随时读取的项目知识库。下图对比了同一任务在有无 HelloAGENTS 加持下的交付效果——接入后,Agent 能按项目已有的设计规范完整实现,而不是各写各的。

接入 HelloAGENTS 知识库后,Agent 按项目设计规范完整交付贪吃蛇游戏界面

而没有任何项目记忆时,交付结果往往缺失、风格不一致,需要人工反复补刀:

没有 HelloAGENTS 知识库支撑时,Agent 交付的界面残缺且风格不统一

.helloagents 目录结构全解

~init 会在项目根目录生成 .helloagents/,它是项目本地知识、方案、状态和运行态的统一存放地。一个初始化后的目录大致长这样:

.helloagents/
├── context.md        # 项目概述、技术栈、架构、模块索引
├── guidelines.md     # 从代码看不出来的编码约定
├── verify.yaml       # 验证命令(lint / test / build)
├── DESIGN.md         # UI 设计契约(有界面时生成)
├── CHANGELOG.md      # 项目级变更历史
├── modules/          # 每个模块的经验笔记
│   └── xxx.md
├── plans/            # 进行中的方案包
│   └── <feature>/
├── archive/          # 已归档的方案包
└── sessions/         # 会话恢复状态与证据
    └── <workspace>/<session>/
        ├── STATE.md
        ├── runtime.json
        ├── active.json
        └── artifacts/   # 结构化交付证据

你可以把它分成三层来理解:知识库(长期、稳定,给人和 Agent 共享)、方案包(一次复杂任务的拆解)、会话运行态(短期、可恢复,含过期自动清理)。

一键初始化:~init 如何生成知识库

你不需要手写这些文件。在 AI CLI 的聊天框里输入:

~init

HelloAGENTS 会分析代码库后,按官方模板自动生成并填充知识库文件,为受支持的宿主写入项目级完整规则标记,并把 .helloagents/ 追加进 .gitignore。整个过程是幂等的——重复执行是安全的,缺失的文件会补全,已存在的文件按模板增量更新,不会自由改写你的结构。

这套生成逻辑由 skills/commands/init/SKILL.md 定义,所有文件都对应 templates/ 目录下的一份模板。空项目会先保留目录骨架,等首次编码任务时再补全知识文件。

知识库文件逐个看懂

下面这几个文件,是 Agent"记住项目"的核心载体。

context.md — 项目的自我介绍

对应 templates/context.md,记录项目做什么、用什么技术栈、架构如何、关键目录各自负责什么,并链接到 modules/ 下各模块文档。Agent 新会话一读它就"入坑"。

guidelines.md — 那些代码看不出来的约定

对应 templates/guidelines.md。命名规范、Git 工作流、测试要求里"非显而易见的部分"都写在这里。模板里特意强调:能从代码推断的风格不必写,只记 AI 猜不到的约定。

verify.yaml — 验证命令清单

对应 templates/verify.yaml。质量闭环(~qa)会优先从这里读取 lint / test / build 命令,而不是每次现猜。检测顺序是:.helloagents/verify.yaml → 包管理器脚本 → 自动探测。

DESIGN.md — 设计契约

对应 templates/DESIGN.md。当项目有 UI 时生成,沉淀设计 token、组件与模式、状态覆盖、无障碍要求、禁止事项等。UI 工作的约束优先级固定为:当前 plan.md / PRD 决策 → DESIGN.md → 已加载的 hello-ui 规则,保证界面风格跨会话一致。

modules/*.md — 模块经验笔记

对应 templates/modules/module.md。每个关键模块一份,记录用途、关键文件、依赖,以及最重要的"经验"章节——调试发现、架构决策、踩坑记录,增量追加、不重写。

CHANGELOG.md — 变更历史

对应 templates/CHANGELOG.md,维护项目级变更日志,让后续会话能快速感知"最近改了什么"。

会话恢复:STATE.md 与 sessions 目录

知识库管"长期记忆",sessions/ 则管"这次任务做到哪了"。HelloAGENTS 把状态文件放在按工作区和会话隔离的路径下,例如 .helloagents/sessions/<workspace>/<session>/STATE.md,其中 <workspace> 通常就是当前 Git 分支。

templates/STATE.md 是一份简洁的恢复快照,只记几样东西:主线目标、正在做什么、关键上下文、下一步具体动作、阻塞项。它不是全对话的万能记忆,而是让中断后的会话能精准续跑。同一 CLI 会话会稳定落在同一个目录里,/resume 时可直接复用;短期运行态和证据默认 72 小时后过期清理,避免目录越堆越乱。

这套会话作用域与存储路径的解析逻辑,核心实现在 scripts/project-storage.mjs 里,它会根据项目是否初始化、是否为 Git 仓库、是否多工作树等条件,动态决定状态和证据落盘到哪里。

经验沉淀:hello-reflect 让踩坑不再重演

知识库不只是"读",还会"长"。skills/hello-reflect/SKILL.md 定义了会话反思机制:当一次任务经历了多次验证循环才通过、调试超过几次才修复、方案中途变更、或你纠正了 Agent 的错误假设时,Agent 会把这些发现提炼成抽象的经验教训,追加到对应 modules/*.md 的"经验"章节,或写入 context.md 末尾。

要求很克制:每条经验不超过两行,必须是可指导方向的抽象结论而非具体代码模板,不记录显而易见的事。正是这种"只留真正有价值的发现"的纪律,让知识库随使用越来越懂你的项目,而不是越积越杂。

整体技能调度、质量三重保障和流程纪律,由 skills/helloagents/SKILL.md 统一约束,确保"读取知识库"和"回写经验"发生在正确的阶段。

进阶:repo-shared 共享知识库

默认情况下,知识就存在项目本地的 .helloagents/ 里。当你在 ~/.helloagents/helloagents.json 中把 project_store_mode 设为 "repo-shared" 时,稳定的知识文件(context.md、guidelines.md、DESIGN.md、verify.yaml、modules/、plans/、archive/)会集中存到 ~/.helloagents/projects/<repo-key>/,多个 worktree 可以共享同一份知识;而会话状态和证据仍留在各自的工作项目里,互不干扰。这对"同一个仓库、多个分支/工作目录并行开发"的团队特别友好。

上手三步与最佳实践

  1. 装好后初始化:在项目里输入 ~init,一次性生成 .helloagents/ 知识库骨架。
  2. 让知识跟着任务长:日常用 ~commit、~qa 收尾,配合 kb_create_mode 让知识库在编码任务中自动同步。
  3. 定期 ~clean:归档已完成的方案包、清理临时运行态,保持目录清爽。

三条小贴士:把"代码猜不出来的约定"写进 guidelines.md 收益最大;有界面的项目务必维护好 DESIGN.md,它能显著提升跨会话的视觉一致性;经验章节坚持"增量追加、抽象表达",避免知识库退化成流水账。

小结:.helloagents/ 是 HelloAGENTS 的"项目记忆中枢"。context.md 讲清项目是什么,guidelines.md 记牢约定,verify.yaml 锁定验证方式,modules/ 沉淀踩坑经验,sessions/ 负责断点续跑。把它用起来,Agent 就不再是每次都要从零开始的新人,而是一位真正熟悉你项目的长期伙伴。

登录后查看全文
helloagents