hivelore

Hivelore

为 Agent 编写的代码提供确定性策略门禁——如果提交重复了团队已经为之付出代价的错误，它就会拒绝该提交。
面向编码 Agent 执行框架的仓库原生上下文策略；规则以团队记忆的形式保存。此前以 hAIve（@hiveai/*）的名称发布。

Hivelore 是 AI 编码 Agent 执行框架中的强制执行层。它会在 Agent 行动前向其提供团队的非显而易见知识，然后将每条来之不易的经验转化为确定性门禁——通过 MCP、Git 钩子和 CI 阻止即将重犯错误的更改。在任何机器上，相同的差异都会得到相同的判定。记忆是基础；门禁才是产品。

能力出众的模型已经了解通用最佳实践。它无法猜到的是你们团队任意且特定于仓库的知识：公开 ID 是以 AC- 为前缀的 id + 100000，状态字段必须是 "OK"/"KO"，已应用的迁移绝不能编辑。如果放任不管，自信满满的 Agent 会编造一个看似合理的答案——代码整洁、测试通过、状态全绿，却违反策略。Hivelore 会将这些无法猜到的知识带入任务，并阻止即将违反它的更改。

Hivelore 的职责不是取代测试、代码检查工具或可观测性。它让这些工具无法推断的仓库专属知识变得可用、可审计且可强制执行。

_{捕获错误 → 附上经过验证的防护规则 → 拒绝重犯错误的提交。在每台机器和 CI 中，相同的差异都会得到相同的判定。60 秒内复现 ↓}

---

问题所在

AI 编码 Agent 功能强大，但它们常常缺少完整的仓库上下文。上下文压缩、并行会话、Agent 切换和过时的参考文档都会导致同一种失败：Agent 更改代码时，没有将团队当前的决策带入工作中。

大多数团队会用说明和希望来应对：

• “请先阅读我们的架构决策。”
• “别再犯上个迭代中的迁移错误。”
• “记得记录你学到的经验。”
• “不要合并会使团队决策失效的代码。”

这些规则很容易被忽略。Hivelore 将它们转化为仓库原生上下文策略。

---

工作原理

AI agent ──▶ Hivelore briefing ──▶ code change ──▶ Hivelore policy gate ──▶ merge
                  ▲                                       │
                  └── context breadcrumbs · decisions · gotchas · anchors

1. hivelore init 会在你的代码库中创建 .ai/ 上下文策略层。
2. Agent 每次会话开始时都会调用 get_briefing——一次 MCP 调用即可返回精简的默认上下文，以及按任务相关性排序的深入线索。
3. 决策、注意事项、失败尝试和会话回顾都以 Markdown 文件的形式保存，并锚定到它们所描述的代码路径。当代码移动时，Hivelore 会检测失效的锚点。
4. hivelore enforce check 和 CI 强制检查会阻止不安全状态：缺少简报、关键决策过时、即将被你的差异重复的已锚定反模式，或未记录的会话知识。

记忆是基础，而上下文强制执行是产品承诺。 AI 变更在参考团队当前知识之前，不应进入代码库。

如需了解针对 9 月 18 日客户端报告所做的变更，包括证据检查、更简洁的简报以及限定于任务的完成检查，请参阅实现说明。

Hivelore 在工具链中的定位

工具链工程关注的是模型周围的环境：行动前提供前馈指导，行动后设置反馈传感器，并通过工作流关卡阻止不良状态进入代码库。Hivelore 负责这套工具链中的代码库专属上下文策略部分。

工具链关注点	Hivelore 的作用
前馈指导	get_briefing、模块上下文、技能、决策、注意事项、失败尝试
反馈与关卡	MCP 调用顺序策略、pre_commit_check、Git hooks、CI 强制检查、失效锚点检测
知识生命周期	Git 原生 Markdown 记录、路径／符号锚点、置信度、淘汰、lint 检查
边界	Hivelore 与单元／端到端测试、类型检查、运行时跟踪、安全扫描器和 LLM 评估互为补充；它不会试图取代它们

这种聚焦的定位是有意为之：Hivelore 不是通用记忆数据库，也不是 Agent 仪表板。它是一个控制层，帮助编码 Agent 运用团队已验证但不显而易见的知识。

范围与边界——三类工具链

工具链工程会规范 Agent 编写的代码的三个不同方面。Hivelore 有意涵盖其中两个，并且目前将第三个排除在范围之外。

工具链维度	它回答的问题	Hivelore 当前的支持情况
可维护性	代码是否整洁？（模式、易错点、约定）	✅ 已覆盖——可执行传感器 + 反模式关卡
架构适配性	是否遵循团队的结构性决策？	🟡 部分覆盖——已锚定的 decision／architecture 记忆 + 决策覆盖关卡
行为	代码在功能上是否正确？	🟡 已搭桥——命令传感器将你自己的测试关联到经验教训（见下文）

为何尚未提供行为工具链。 验证功能正确性需要一个判定标准——独立于代码、用于确定代码应该如何运行的真实依据。这个判定标准问题（以及 Agent 给自己的工作打分所带来的陷阱）是该领域中发展最不成熟的部分。这部分应由你的测试、基于属性的检查和 LLM 评估负责；Hivelore 不会试图取代它们。Hivelore 确实会将行为测试原本必须编码的不可推断意图（status must be OK/KO、public ids = id + 100000）作为前馈上下文和确定性传感器传递出去——这只是行为控制中局部、静态的一部分，并非运行时功能判定标准。

桥接能力已推出（v0.33.0）：命令传感器。 经验教训可以关联一条命令，而不是正则表达式——也就是你自己的测试或不变量脚本。当差异涉及传感器监控的路径时，关卡会执行该命令；如果退出码非零，就会以该经验教训作为提示拒绝提交。Hivelore 不会发明判定标准（这是尚未解决的问题）；它会将团队已有的判定标准关联到其所保护的经验教训：

hivelore memory tried \
  --what "refund exceeded the captured amount" \
  --why-failed "prod incident #442 — refunds must clamp to capture" \
  --paths src/payments/ \
  --sensor-command "npx vitest run tests/payments/refund-invariants.spec.ts"
# → validated (the oracle must PASS on the current tree), then enforced at commit + CI
#   Saved team-scoped by default: an enforced lesson must travel to every machine and CI.

确保诚实的规则：每个仓库都必须选择加入（enforcement.runCommandSensors: true——它会执行仓库编写的命令）；如果提案的预言机 在假定正确的代码树上失败，则会被拒绝；仍是待处理的存根的预言机不能启用阻断型传感器；而无法运行的命令（找不到、超时）只会发出警告，绝不会阻断——不能让损坏的测试框架冒充失败的测试。命令会在清理过的环境中运行（仅包含测试运行器的基本环境，不含云凭证或令牌）。你还可以让这项保证得到验证：--red-ref <pre-fix-commit> 会在临时工作树中重放事件，并要求预言机在那里失败——传感器随后会记录 red_proven: true，并显示在防护回执中。如果预言机在事件状态下到达断言之前出错（受保护的代码尚不存在、导入或语法错误、“没有找到测试”），崩溃不算 RED：重放会报告 red-unrunnable，并拒绝声称已验证。完整的行为验证（测试生成、LLM 评估）仍由你的测试套件负责。

从 v0.43.0 起，阻断型 shell／测试传感器必须通过 prove-RED：没有可复现事件状态的预言机仍会保持 warn。CI 还可以设置 commandSensorUnrunnable: "block"，让缺少必需预言机的情况作为测试框架损坏而失败；也可以设置 sensorWeakeningGate: "block"，防止保护被悄悄降级或移除。

入门路径（v0.36.0）：根据事件搭建测试骨架。 命令传感器需要一个测试来路由——因此 Hivelore 会根据经验教训生成骨架。hivelore sensors scaffold <memory-id>（或 scaffold_test MCP 工具，让 Agent 能在会话中完成此操作）会检测你的测试框架（vitest / jest / pytest / go），写入一个待处理测试，并在其标头中附带事件的溯源信息，然后打印用于启用传感器的精确 sensors propose --kind test 命令。它本身绝不会启用传感器（propose_sensor 仍是唯一经过验证的写入途径）；存根会保持待处理状态，因此在你编写断言之前，测试套件仍会通过。在单体仓库中，测试框架和位置取自拥有经验教训锚点路径的包（位于 packages/api/ 下的经验教训会在 packages/api/tests/… 中搭建测试骨架），而不是仓库根目录；如果一条经验教训涉及多个包，则会为每个所属包搭建一个待处理测试，并由一个传感器启用，该传感器会串联运行这些测试的命令。尚待处理或从未启用的测试骨架会形成未闭环事项：在预言机完成路由之前，doctor 和 enforce finish 会通过 post-incident-test-unarmed 提醒你。

传入事件信息，存根就会围绕修复自动生成（v0.46.0）。 添加 --red-ref <pre-fix-commit> 后，测试骨架会指出修复（red_ref..HEAD）实际修改的符号，并据此预填示例——例如 import { refund } …、expect(refund(/* incident input */)).toBe(/* post-fix expected */)，而不是空白的 subjectUnderTest()。它仍会是待处理的注释存根（没有生效的导入，测试套件仍会通过）——这是确定性的起步方案，绝不是让 LLM 猜测你的断言。

hivelore sensors scaffold 2026-07-03-attempt-refund-exceeds-capture --red-ref <pre-fix-commit>
# → tests/incidents/refund-exceeds-capture.test.ts (pending; names the touched symbols from the fix)
#   then: fill the assertion → run it → arm it with the printed propose command.

降低表达不变量的成本（v0.48.0）：--style。 行为测试框架会把预言机留给你编写，因此测试骨架提供两种确定性方式来降低成本（不让 LLM 猜测你的断言）：

• --style property — 一个 fast-check / Hypothesis 骨架：只需声明一次不变量（refund(a, b) ≤ b），然后用许多生成的输入对其进行检查。
• --style differential --reference <impl> — 完全无需声明不变量：断言主题实现对所有生成的输入都与参考实现（旧版本、另一个实现）一致。

hivelore sensors scaffold <lesson> --red-ref <pre-fix-commit> --style property
hivelore sensors scaffold <lesson> --style differential --reference ../legacy/refund

两者都会保持为待处理的注释存根（测试套件仍会通过），填好后再通过相同的、经过验证的 prove-RED 流程启用。 测量行为测试框架（v0.45.0）。 hivelore doctor 会按主要代码区域报告行为表面有多少受到保护：Behaviour harness: X/N area(s) guarded by a behavioural oracle (K armed, P red-proven)——这样就能看到分支的进展，而不必猜测。人工生成的 stats receipt 会在页脚打印同一行。自 v0.47.0 起，该发现会形成完整的行动闭环：对每个未覆盖区域，它都会在 Suggested commands 中打印准确的 hivelore sensors scaffold <lesson> --red-ref <pre-fix-commit> 命令（如果尚无 lesson，则打印 memory tried … then scaffold 行）。

冻结的 1.0 表面请参阅 STABILITY.md，扩展 Hivelore 请参阅 CONTRIBUTING.md。

可执行的记忆传感器

现在，部分 gotcha 和 attempt 记忆可以包含 sensor 区块：一种扫描差异的确定性防护机制。它有三种形式，但遵循同一验证原则（代码正确时保持静默，出现错误时触发）：

• regex — 在新增行中进行匹配；简单且无需依赖，是默认选项。
• ast — ast-grep 结构性模式 （stripe.paymentIntents.create($$$)，并设置 absent: idempotencyKey）：注释和字符串字面量绝不会造成误报，而且“调用 X 时缺少 Y”可直接在调用本身上表达。需要可选的 @ast-grep/napi 引擎——没有该引擎时，传感器无法运行（发出警告，绝不阻止）。
• shell/test — 将你自己的测试作为判定依据的命令（下文的行为桥接方式）。

传感器将已记录的经验教训转化为可重复的反馈信号，不依赖嵌入或模型判断。自动生成的传感器初始状态为 warn；经人工审核后，可将其提升为 block。该原则也会检查反转情况：若 block 模式匹配到 lesson 自身建议的修复方式（其 Instead, use: 代码片段），则会拒绝该模式（fires-on-correct）——否则它会阻止正确代码，而放过错误代码。

hivelore sensors list
hivelore sensors check                          # scans git diff --cached
hivelore sensors propose <lesson> --from-fix <pre-fix-ref>   # MINE the pattern from the fix diff
hivelore sensors promote <id> --yes             # promote a vetted sensor to block
hivelore sensors export --format grep

降低启用成本（--from-fix）。 在已记录的经验教训和强制执行之间，主要成本是编写能区分正误的正则表达式——现在可以让修复过程帮你编写。sensors propose --from-fix <pre-fix-ref> 会从修复差异中提取模式：修复中移除的行就是错误写法（pattern），新增的行就是正确标记（absent）。你只需确认候选项，而不必自己编写正则表达式——在其能够阻止代码之前，它仍须通过完整验证（对当前代码保持静默、遇到错误时触发、未反转）。

---

安装

npm install -g @hivelore/cli
# Optional: local semantic search (downloads ~110MB model once)
npm install -g @hivelore/embeddings

---

验证完整集成

运行 hivelore agent check --exercise --json，即可在隔离的临时仓库中测试 MCP 简报、针对性的钩子上下文，以及针对正确和错误代码进行验证的传感器。它还会报告首次编辑延迟，以及读取、重复编辑和 shell 调用的十次采样中位数和 p95 耗时。这是合成的安装验证，并非生产力基准测试。 新项目默认启用本地任务完成和草稿捕获；现有策略保持不变。 请参阅审计修复和升级指南。

升级后，运行 hivelore agent setup --no-global 修复受管理的旧版 Git 钩子，然后重启 AI 客户端。新的握手成功，并不意味着正在运行的会话已完成升级。 hivelore agent check --json 会列出已知的运行中 MCP 版本和尚未完成的迁移工作。 旧版 CI 工作流会收到一个 .candidate 替代文件供审核；自定义钩子命令会保留。

完整的策略与可追溯的结果

简短且适用的策略会在编辑前注入。当策略内容无法全部容纳时，钩子会明确提示未传递指令，而不是悄悄丢弃其中的例外情况。不完整的简报不算完整查阅。使用 mem_get 并提供钩子的 session_id，或运行 hivelore memory get <id> --session-id <session>，以阅读完整策略并注明已查阅。

默认 MCP 配置中提供 mem_feedback。使用提交、测试报告或事件的 reference，报告 applied/rejected，或 corrected/verified。可选的 catch_id 可将反馈关联到 hivelore stats outcomes 列出的拦截记录。关联验证需要先有更正。报告会区分已声明的结果与后续观察到的静默传感器检查；它们不会验证引用，也不会推断避免了哪些错误或节省了多少时间。

基准报告必须至少包含 10 个不同任务 × 3 次重复，具备可比的模型、检出版本、预算和提示词元数据、独立评估证明，以及相匹配的 protocol.json/run.json 清单，才符合 decision-ready 资格。重复单个任务或移除一个实验组，均不能满足预先准备的协议。此评级描述的是证据完整性，而非已证实的优越性或经过验证的执行情况。

60 秒验证——观看一条经验教训阻止提交

这是上方演示中展示的确切流程。

hivelore init -y                     # .ai/ layer + git hooks + bridges for the agents you actually use (detected)

# 1. Capture a failed approach (agents do this via the mem_tried MCP tool)
hivelore memory tried \
  --what "importing moment.js" \
  --why-failed "bundle bloat — team standard is date-fns" \
  --instead "date-fns" --paths src/
#    → prints the new memory id, e.g. 2026-07-02-attempt-importing-momentjs

# 2. Give the lesson teeth: a validated, deterministic guardrail
hivelore sensors propose 2026-07-02-attempt-importing-momentjs \
  --pattern "from ['\"]moment['\"]" --severity block
#    Hivelore validates it first: silent on your current code, fires on the mistake.

# 3. Reintroduce the mistake — the commit is refused
echo "import moment from 'moment';" >> src/dates.ts
git add . && git commit -m "add date helper"
#    🛡️  A documented lesson refused this commit — about the change you just made:
#        • 2026-07-02-attempt-importing-momentjs (src/dates.ts)  use date-fns
#          import moment from 'moment';

在每台机器和 CI 中，相同的差异都会得到相同的结果——门禁的设计就是确定性的。所有内容都以可审阅的 Markdown 文件存放在 .ai/ 中，并与代码一同进行版本管理。运行 rm -rf .ai 即可撤销所有更改。

---

快速开始

1. 初始化项目

cd my-project
hivelore init          # Creates .ai/, bridge files, MCP config, hooks, CI template

hivelore init 现在也会运行 Agent 设置。它会写入项目级 MCP 配置，记录当前可用的最佳模式，并在更改用户级客户端配置前征求许可。在非交互式 Shell 中，它会跳过全局配置，并告知你如何完成设置。

2. 连接 AI 客户端

Claude Code（~/.claude.json）：

{
  "mcpServers": {
    "hivelore": {
      "command": "hivelore",
      "args": ["mcp", "--stdio", "--root", "/absolute/path/to/my-project"]
    }
  }
}

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "hivelore": {
      "command": "hivelore",
      "args": ["mcp", "--stdio", "--root", "/absolute/path/to/my-project"]
    }
  }
}

VS Code：

code --add-mcp '{"name":"hivelore","command":"hivelore","args":["mcp","--stdio","--root","/path/to/project"]}'

3. 初始化项目上下文

在 AI 客户端中，调用 bootstrap_project MCP 提示词。Agent 会分析代码库并自动写入 .ai/project-context.md。

4. 通过 Hivelore 开始工作

每个会话都从一次调用开始：

get_briefing(task: "add a Stripe payment integration", files: ["src/payments/PaymentService.ts"])

Agent 一次调用即可获取项目上下文、相关模块上下文和按优先级排列的上下文线索——无需再通过 grep 重新发现团队已掌握的信息。

对于不支持原生 MCP 的 CLI Agent，可通过包装器运行：

hivelore run -- claude --dangerously-skip-permissions -p "$(cat task.md)"

随时检查所选模式：

hivelore agent status
hivelore agent check          # initialize the server and discover its tools
hivelore agent setup          # re-run setup later
hivelore agent setup --yes    # approve user-level MCP config without prompting

设置过程会迁移过时的 haive MCP 命令，包括 Codex 用户配置，并保留其他服务和 JSONC 注释。它支持 Claude Code、Cursor、VS Code、Windsurf、Codex，以及检测到的 Gemini CLI/Roo Code 配置。设置完成后重启客户端，然后在新会话中调用 get_briefing：服务检查成功并不代表现有会话已能访问。参见 MCP 连接故障排除。

5. 拦截提交和拉取请求

hivelore enforce install       # Installs Git hooks + CI enforcement template
hivelore enforce status        # Current enforcement posture
hivelore enforce check --stage pre-commit  # Scan the staged change
hivelore enforce ci            # CI entrypoint (exits 1 on violations)

由一个设置决定拦截行为：enforcement.posture。

posture	拦截内容
advisory	不拦截任何内容——只报告所有问题。适用于在进行中的仓库里采用 Hivelore
balanced（默认）	仅拦截确定性、与代码绑定的问题：拦截传感器、已锚定的反模式、你修改过的文件中的过期锚点、产物卫生问题
strict	除上述内容外，还会在共享节点——pre-push 和 CI——拦截流程关卡（任务简报、回顾、决策覆盖、引导）

mode、processGate 和 humanCommits 是姿态设置的单独开关；明确固定其中一个，即可仅覆盖该开关的姿态设置。hivelore doctor 始终会输出生效的姿态和所有覆盖项，因此关卡会执行什么操作绝非猜测。

有一条规则不是姿态开关，也不可协商：流程关卡绝不会拦截本地提交，无论处于何种姿态。在每次提交前都拦截它们，会让刚接触仓库的用户养成使用 --no-verify 的习惯。通过提交时关卡会输出一行信息；--verbose 会显示所有检查。如果旧安装留下的 Git 钩子损坏，hivelore doctor --fix 会重新生成它。

当有内容被拦截时，系统会指出具体行。

🛡️  A documented lesson refused this commit — about the change you just made:
    • 2026-07-02-attempt-importing-momentjs (src/dates.ts)  use date-fns, not moment
      import moment from 'moment';

一条经验，一行说明，并附上文件和问题来源。不使用任何综合评分：关卡会报告是什么拦截了更改，以及应如何处理；否则就保持安静。

---

CLI 速览——推荐路径

hivelore --help 只显示日常使用的命令。其他所有功能（审查、导入、诊断、基准测试）都可以通过 hivelore --advanced --help 找到——精简的命令界面是有意为之，并非功能缺失。

完整命令手册： packages/cli/README.md 记录了每个命令及其标志和示例。它是参考手册；本页介绍概念。每项说明只会出现在两者之一中。

阶段	命令	功能
设置	hivelore init	创建 .ai/、桥接文件、MCP 配置、钩子和 CI
	hivelore doctor	检查安装是否正常
	hivelore agent setup	配置 AI 客户端（MCP、钩子）
编辑前	hivelore briefing	前馈上下文——CLI 版的 get_briefing
记录知识	hivelore memory save	记录决策／约定／注意事项
	hivelore memory tried	记录失败的方法，避免重复尝试
	（被动）	钩子观察到的会话失败会在会话结束时自动提炼为 proposed 草稿——使用 memory list --status proposed 审查；它们绝不会自行验证，也绝不会携带传感器
检索	hivelore memory search · get	查找记录，然后读取
反馈	hivelore sensors check	对照已记录的经验扫描差异
拦截	hivelore enforce finish	在宣布任务完成前运行退出关卡
同步	hivelore sync	重新检查过期锚点，刷新桥接文件
收尾	hivelore session end	保存回顾，供下一次会话使用

CLI 和 MCP 共用一套术语。 记忆操作动词与 MCP 工具名称对应，因此 Agent 只需学习一次：hivelore memory save/search/get/delete ↔ mem_save/mem_search/mem_get/mem_delete（较早的 add/query/show/rm 仍可作为别名使用）。

---

在你的仓库中试用（5 分钟，可撤销）

想在一个真正的代码库上评估 Hivelore，而不是玩具项目？它不会造成破坏——它写入的所有内容都位于 .ai/ 目录和少数几个桥接文件中，均可移除。

cd your-project
npm install -g @hivelore/cli
hivelore init -y            # seeds stack packs + git-history scars; writes .ai/ and bridges
hivelore briefing --task "the change you're about to make" --files path/to/file
hivelore doctor             # health + coverage report
hivelore sensors check      # scan your staged diff against documented lessons
hivelore eval --fail-under 50   # retrieval + sensor quality on your own corpus

要移除 Hivelore 添加的所有内容：rm -rf .ai CLAUDE.md AGENTS.md GEMINI.md .cursorrules .clinerules .continuerules .windsurfrules .rules CONVENTIONS.md .github/copilot-instructions.md，并删除 .github/workflows/hivelore-*.yml 文件。来自非本项目仓库的反馈最有价值——请提交 issue，告诉我们哪些有效、哪些无效。

Hivelore 强制执行的规则

Gate	检查内容
首个 Agent 初始化	在冷启动语料库中，系统会要求首个 Agent 填充知识层：填写项目上下文、为每个组件编写模块上下文、为每个主要代码区域添加锚定记忆，以及为每个主要代码区域添加一个传感器。触发条件是语料库状态——基线一旦建立，此 Gate 对之后的所有 Agent 都会保持静默。默认只报告；设置 posture: "strict" 时会拒绝
已加载简报	Agent 在编辑前加载了最新的上下文线索。默认只报告
决策覆盖	最近一次简报中的相关锚定决策覆盖了已更改的文件。默认只报告
反模式匹配	在 Gate 处展示与差异相关的反模式；如果已验证的拦截传感器在新增行上触发，就会阻止提交。可通过 enforcement.antiPatternGate 调整严格程度（off · review · anchored（默认） · strict）
Gate 表面完整性	对削弱传感器的差异（将拦截降级为警告、更改或移除判定逻辑、扩大抑制范围、删除拦截传感器记忆）会被提请审查（sensor-weakened）——Gate 位于 .ai/ 中，因此削弱它绝不能在无人提及的情况下蒙混过关
过期锚点	锚定到已删除或已移动路径的记忆会被阻止——但仅当锚点位于本次更改涉及的文件时才会阻止。其他位置的过期锚点属于语料库维护问题，会作为警告报告
会话回顾	Agent 在结束前记录了更改内容和待办事项。默认只报告
CI 强制执行	任何 Gate 失败都会导致必需检查阻止合并

这里的“阻止”是什么意思。 Gate 只会在有确定且与代码绑定的证据时拒绝：已验证的传感器在新增行上触发、锚定的反模式，或你修改的文件上存在过期锚点——相同的差异，在每台机器和 CI 中都会得到相同的结果。锚点匹配、字面标记匹配和语义匹配（无论多么可靠）都只会提请审查，绝不会阻止：相关性信号会因环境而异，共同出现并不代表重新引入。 propose_sensor 是将已记录的经验转化为拦截式防护措施的途径。

流程 Gate 只报告，不会拒绝。 从 v0.55.0 起，“你没有加载简报”和“你没有编写会话回顾”只是要求，并非对差异作出判定。原因来自实际经验：一份实地报告记录了两次提交被拒的情况，提交中包含经过测试的代码，质量 Gate 通过且没有任何违规——所有处罚都针对流程，与代码无关。开发者接下来学会的就是使用 --no-verify，这会让他们失去整个 Gate，包括传感器；而一个会被绕过的 Gate 什么也保护不了。如果你也希望强制执行工作流，请设置 enforcement.posture: "strict"。

---

冷启动——会话一即见价值

hivelore init 可以根据仓库已有的信号进行初始化种子注入，并且每条种子都必须达到质量下限， 确保冷启动时不会提供泛泛而谈、轻易猜到的建议。

自 v0.55.0 起，技术栈包默认不启用（--stack auto）。默认注入这些种子，会让新语料库充斥着无人针对该仓库撰写的建议，而真实会话的第一份简报会显示 thin · must_read=0 useful=0 background=3——这 3 条全是技术栈包中的空话，占据了简报，却毫无助益。空语料库更诚实：它会直白地说明还需要填充。Git 历史种子注入在自动驾驶模式下仍保持开启，因为你自己的历史中的一次回滚，就是你自己的伤痕。

来源	注入的内容	质量门槛
技术栈包（--stack auto，默认不启用）	检测到的框架陷阱（Next/Nest/Prisma/Flask/Rails/Tailwind/Docker……20 多个包），在高信号场景下提供阻断传感器	特异性下限——删除泛泛的建议，并在 CI 中进行审查
Git 历史（--seed，默认开启）	根据回滚／热修复／变通方案提交生成的草稿记忆——仓库中的真实伤痕	噪声主题拒绝列表（删除 merge/bump/deps/wip/format）
扫描器发现项（hivelore ingest）	将 SonarQube / SARIF / ESLint / npm audit 发现项作为提议的、带锚点的记忆和传感器	删除可自动修复的风格规则（包括 Sonar 数字键）；使用 --include-stylistic 保留

hivelore init                                   # Initialize + seed from git history
hivelore init --stack auto                      # ...and add starter packs for the detected stack
hivelore ingest --from sonar issues.json --min-severity major
hivelore ingest --from eslint report.json
hivelore ingest --from sarif report.sarif --dry-run   # Preview without writing

摄取和 Git 种子注入的记忆会标记为 proposed（传感器仅发出警告）。使用 hivelore memory list --status proposed 查看；使用 hivelore sensors promote 将审核通过的传感器提升为 block。

---

.ai/ 目录布局

your-project/
├── .ai/
│   ├── project-context.md          # Shared project overview
│   ├── modules/                    # Per-component context files
│   │   ├── backend/context.md
│   │   └── frontend/context.md
│   ├── memories/
│   │   ├── personal/               # Private — gitignored
│   │   ├── team/                   # Shared — committed to git
│   │   └── module/<name>/          # Module-scoped memories
│   ├── code-map.json               # Symbol index — deterministic, safe to commit
│   ├── .runtime/                   # Local session state — gitignored
│   └── .cache/                     # Indexes, churn, telemetry — gitignored
├── CLAUDE.md                       # Auto-generated bridge (Claude Code)
├── AGENTS.md / GEMINI.md / …       # …and 10 more native bridges (see below)
└── .github/
    ├── copilot-instructions.md     # Auto-generated bridge for Copilot
    └── workflows/
        ├── hivelore-sync.yml       # Anchor verification on merge
        └── hivelore-enforcement.yml # Required policy gate

原生桥接——适配每一种 Agent

对于不支持 MCP 的命令行／IDE Agent，hivelore init 会从同一份语料库生成原生配置文件，让团队的记忆和阻断传感器能够应用于开发者使用的任何 Agent——不仅是空模板，也包括强制执行能力。hivelore sync 会使其保持最新；切勿手动编辑（使用 hivelore bridges sync 重新生成）。

Agent	文件	Agent	文件
Claude Code	CLAUDE.md	Cline	.clinerules
Cursor	.cursor/rules/haive-memories.mdc	Windsurf	.windsurfrules
Codex / 通用	AGENTS.md	Continue	.continuerules
GitHub Copilot	.github/copilot-instructions.md	Cody	.sourcegraph/cody-rules.md
Gemini CLI	GEMINI.md	Zed	.rules
Aider	CONVENTIONS.md	Roo	.roo/rules/haive.md

hivelore bridges list                 # Show target status
hivelore bridges sync --all           # Regenerate every native bridge
hivelore init --bridge-targets cursor,copilot   # Or scope to specific agents

---

上下文策略记录

类型	描述
decision	团队已确定的架构或设计选择
gotcha	不明显的约束、已知的易错点、微妙的不变量
convention	此代码库特有的命名、模式和风格规则
attempt	失败的方案——避免 Agent 重蹈覆辙
architecture	组件边界、接口、数据流

所有记录都可以锚定到文件路径和符号名称。锚定的代码发生变化时，Hivelore 会将相应记录标记为可能已过时。

---

MCP 工具参考

工具	描述
get_briefing	⭐ 一次调用获取项目上下文、决策、注意事项和按优先级排序的线索
mem_feedback	报告已应用或已拒绝的结果，或已引用的已纠正／已验证结果；也可选择关联一条传感器捕获记录
mem_save	保存仓库策略知识（决策、注意事项、惯例、尝试、架构）
mem_tried	记录失败的方法，避免未来的 Agent 重复尝试
mem_search	在上下文记录中进行全文或语义搜索
mem_relevant_to	项目上下文已加载时，为任务提供按相关性排序的上下文记录
mem_get	在简要说明或搜索结果后获取一条上下文记录
mem_update	原地修订现有记录——补上经验教训中缺失的锚点路径
propose_sensor	⭐ 将捕获的经验教训转化为已验证的防护规则。你编写模式；Hivelore 会证明它在当前代码中不会误触发，并能在错误发生时触发，然后才会信任它来阻止错误
report_friction	在本地记录使用 Hivelore 本身时遇到的不便。绝不会发送任何内容——由人工通过 hivelore report 审核，并决定哪些内容应成为问题
code_map	在代码映射已建立索引时，无需手动 grep 即可查找符号
code_search	对导出的符号进行语义搜索（需要 @hivelore/embeddings 和 hivelore index code-search）
mem_verify	检查锚点是否仍然有效，并检测过时记录
scaffold_test	根据经验教训生成待处理的事后测试，以及用于启用该测试的 sensors propose --kind test 命令（支持单体仓库）
pre_commit_check	将差异与已知注意事项、决策和过时锚点进行比对
mem_session_end	保存本次会话总结，供下一个 Agent 使用

MCP 配置文件让产品保持专注：

• HAIVE_TOOL_PROFILE=enforcement（默认）：精简的编码 Agent 工具框架。
• HAIVE_TOOL_PROFILE=maintenance：语料审查、生命周期管理、提炼、代码搜索和项目上下文维护。
• HAIVE_TOOL_PROFILE=experimental / full：maintenance 的旧版别名（实验性诊断功能已在 v0.32.0 中移除——数月的使用情况表明，所有这些功能加起来也只被调用过一次）。

---

MCP 提示词参考

提示词	描述
post_task	⭐ 任务后检查清单——在每次会话结束前记录经验教训
bootstrap_repo	⭐ 首个 Agent 的引导流程——填充引导门槛所要求的整个知识层（项目上下文、模块上下文、带锚点的记忆，以及每个主要领域一个已验证的传感器）。根据当前语料状态定制具体的检查清单，并执行 bootstrap_project_save → mem_save → propose_sensor，直至就绪
bootstrap_project	分析代码库并编写 .ai/project-context.md

---

软件包

软件包	安装	描述
@hivelore/cli	npm i -g @hivelore/cli	主要产品：初始化、强制执行策略、运行 Agent、简报、记忆、同步、CI/Git 钩子
@hivelore/mcp	随 @hivelore/cli 一同打包	感知策略的 MCP 服务
@hivelore/core	依赖项	类型、架构、锚点、策略基元、令牌预算
@hivelore/embeddings	npm i -g @hivelore/embeddings	可选：本地语义排序（bge-small-en-v1.5，完全离线）

**此仓库还包含：**一个 VS Code 扩展（可在代码中内联显示记忆，并通过 CLI 的可观测性功能提供战略驾驶舱），以及一个 GitHub Action（以 PR 评论的形式发布相关团队记忆，让审阅者和 Agent 不会错过不明显的约束）。

PR 流程。 审查反馈是团队共识的雏形：在任意审查讨论串中回复 /hivelore remember <rule>，Action 会确认并提供准确的持久化命令；也可以运行 hivelore ingest --from github-pr <number>，将 PR 中人工审查的指示（“绝不……”“始终……”“优先选择 X，而不是……”）转化为 proposed 状态、锚定到文件的记忆——每条记忆都可作为 sensors propose 的候选项，而这正是推断式审查机器人无法完成的一步。启用 persist-review-learnings（默认开启）后，Action 会创建专用分支和 PR，其中包含提议的记忆；如果没有仓库写入权限，则会回退到本地 ingest 命令。顶层 PR 评论和审查讨论串中的回复也采用相同流程。

结构传感器。 sensors propose --kind ast 接受简洁的 --pattern，也接受完整的 ast-grep --rule <json>（inside/has/not/all/any）。JavaScript/TypeScript 已内置；Python、Go、Rust 和 Java 则由随 CLI 提供的可选语言软件包支持。规则在生效拦截前，仍须通过 Hivelore 的静默于当前状态、有问题时触发的验证。 嵌套关系规则默认不会递归：如果 has 或 inside 必须搜索所有后代节点，请添加 "stopBy":"end"，例如 {"has":{"kind":"interpolation","stopBy":"end"}}。

---

自适应简报

简报只有在包含无法猜出的知识时才有价值，因此 get_briefing 会返回 briefing_value: "high" | "low"。当没有与文件或任务相匹配的团队专属信息时，自动生成的项目上下文会缩减为一行提示（配置项：adaptiveBriefing，默认开启）——因此，只有当 Hivelore 确实知道模型不知道的信息时，它才会展示更深入的上下文。

锚点根据实际区分能力加权

锚点匹配是最强的排序信号——但前提是锚点足够具体。对于每次提交都会改动的文件，锚点匹配几乎毫无区分度。在此仓库中的测量结果：149 次提交中有 106 次改动了 package.json，因此每条锚定于该文件的经验都会在每次发布提交时声明自己为 must_read。中位数提交中，34 条记忆争夺 8 个名额中的最高排名，最终显示哪 8 条完全是随机的。

从 v0.57.0 开始，匹配权重会根据匹配路径的稀有程度调整——即应用于锚点的普通 IDF。最近提交中超过 35% 涉及的锚点，必须获得佐证（强语义匹配或符号匹配），才能排在所有其他内容之前；同一等级内则由具体程度决定优先级。对 25 次真实提交进行测量后，简报名额中分配给低信息量锚点的比例从 17% 降至 4%。

变更频率通过一次缓存的 git log 计算，并在 HEAD 变化时失效。样本过小——例如浅克隆或新建仓库——会报告为 未知，并完全按原有方式排序，绝不会被视为“所有内容都很常见”。

hivelore doctor 会报告 memory-broad-anchors，列出几乎声称涵盖每次变更的记忆，以及每个锚点覆盖的提交比例。解决方法始终是增补内容：为经验指定它实际对应的精确路径。

---

CLI 参考

# Setup
hivelore init [--with-ci] [--no-bridges]         # Initialize .ai/ + bridge files + seed from git history
hivelore init --stack auto                       # Opt in to generic starter packs for the detected stack
hivelore init --bridge-targets <all|csv>         # Scope generated bridges to specific agents
hivelore enforce install                         # Install Git hooks + CI enforcement
hivelore enforce status                          # Enforcement posture report
hivelore bridges list/sync [--all]               # Inspect / regenerate native agent bridges
hivelore index code                              # Build .ai/code-map.json
hivelore index code --status [--json]            # Report code-map / code-search index freshness

# Daily use
hivelore briefing [--task <text>] [--files] [--json]   # Print context + relevant memories
hivelore run -- <agent command>                  # Wrap any CLI agent in Hivelore session
hivelore enforce check [--stage pre-commit]      # Policy gate
hivelore enforce ci                              # CI entrypoint
hivelore enforce finish                          # Final agent-exit gate: commit/push, version/tag, CI, npm + GitHub Release
hivelore coverage [--source git|agent|both]      # Find changed files no memory covers
hivelore sync [--since <ref>] [--embed]          # Verify anchors + auto-promote
hivelore sensors list/check/export/promote       # Operate executable memory sensors
hivelore sensors propose <id> --pattern <re>     # Turn a lesson into a VALIDATED guardrail
hivelore report list|submit|dismiss              # Friction agents hit with Hivelore itself

# Memory
hivelore memory save --type <type> --body "<text>" [--paths <csv>]  # Save a memory (anchor to files)
hivelore memory list [--scope] [--status]        # List memories
hivelore memory search <text>                    # Full-text / semantic search
hivelore memory get <id>                         # Read one record
hivelore memory approve [<id>|--all]             # Mark as validated
hivelore memory promote <id>                     # personal → team
hivelore memory tried [--sensor-pattern <re>]    # Record a failed approach (one-shot guardrail)
hivelore memory conflicts [<a> <b>] [--yes]      # List conflict candidates / resolve one pair
hivelore memory verify [--update] [--json]       # Check anchor freshness
hivelore memory import --from <file> [--changelog]  # Import docs or a CHANGELOG as memories
hivelore memory seed [stack|--git]               # Re-seed stack packs / git-history scars

# Cold start (seed from existing signals)
hivelore ingest --from sonar|sarif|eslint|npm-audit <file>  # Scanner findings → anchored memories
hivelore ingest --from <fmt> <file> --dry-run    # Preview without writing

# Indexes (symbol map + semantic search)
hivelore index code [--status]                   # Build .ai/code-map.json / report freshness
hivelore index memories                          # Build the semantic index (first run: ~110MB model)
hivelore index query <text>                      # Semantic search over memories

# Release protocol
hivelore release bump <patch|minor|major>        # Lockstep version bump + CHANGELOG scaffold
hivelore release tag                             # Tag vX.Y.Z at HEAD, push branch + tag
hivelore release ship                            # After the bump commit: pull --rebase → tag+push → poll CI

# Diagnostics
hivelore doctor                                  # Analyze setup, emit recommendations
hivelore eval --fail-under 80                    # Retrieval + sensor quality gate
hivelore eval --semantic-ranking                 # Real embeddings lane (requires index)
hivelore selftest                                # Self-test MCP tools (latency + payloads)

hivelore eval 会根据锚定记忆自动合成检索案例；如果存在 .ai/eval/spec.json，还会加载其中已标注的检索／传感器案例。本仓库使用该文件在 CI 中保留可执行的记忆传感器，确保发布前发现失效的防护措施。 已提交的回归基线仅使用有版本控制的团队／模块记忆，以及确定性的锚点／词法排序；本地使用计数器、个人记忆和可选的嵌入缓存不会导致基线在本地通过、却在干净的 CI 克隆中失败。语义搜索仍由嵌入／搜索测试套件，以及单独的 --semantic-ranking CI 流程覆盖；该流程由 .ai/eval/semantic-baseline.json 提供支持。当软件包或索引不可用时，该流程会按失败处理。

hivelore doctor 会报告可能导致 Agent 误判仓库状况的本地环境偏差：缺少 pnpm、过时的工作区 dist 构建产物、全局 CLI/MCP 版本不一致、代码搜索索引过时，以及记忆锚点覆盖率偏低。

---

多组件项目

对于包含多个组件（前端／后端／微服务）的项目，请为每个组件创建一个模块上下文。get_briefing 会根据正在编辑的文件自动加载相关模块上下文。

mkdir -p .ai/modules/backend .ai/modules/frontend

cat > .ai/modules/backend/context.md << 'EOF'
# Module: backend
- Spring Boot, Java 17, PostgreSQL
- Always filter by tenantId in every repository query
- Never modify existing Flyway migrations — create V{N+1}__desc.sql
EOF

cat > .ai/modules/frontend/context.md << 'EOF'
# Module: frontend
- React 19, TypeScript, TanStack Query v5
- All API calls go through hooks in features/<domain>/api/
- Env vars must start with VITE_ to be exposed to the client
EOF

---

开发

git clone https://github.com/Doucs91/hivelore.git
cd Hivelore
pnpm install
pnpm -r build    # Build all packages
pnpm -r test     # Run tests

需要 Node 20 LTS+、pnpm 9+。

---

贡献

欢迎提交问题和 PR。开始重要工作前，请先提交问题，以便我们就方向达成一致。

---

许可证

Apache 2.0 — 参见 LICENSE。