Beacon MCP

一、为什么需要它

1.1 一个每天都在发生的浪费

一次真实的工程日常：

09:00  你在 Claude Code 里花了 40 分钟，
       教会 Agent 你们仓库的数据库迁移正确姿势
       （要先跑 pre-migrate 检查，再备份，再执行，最后校验 checksum）

11:30  你切到 Cursor 改另一个模块。
       Cursor 的 Agent 完全不知道刚才那 40 分钟发生过什么，
       它直接写了一句 migrate --force。

14:00  你用 Codex CLI 跑一个批量脚本。
       它踩了和你早上踩过的同一个坑，
       你又花 20 分钟解释一遍。

17:00  下班。三段知识，全部蒸发。

这不是模型笨，是架构缺了一层。 每个 harness 都把会话历史存在自己的私有格式里，彼此不通，会话结束即丢弃。

1.2 知识被锁死的三层原因

层级	现象	后果
会话层	transcript 用完即弃	单次会话内学到的东西不带走
Harness 层	Claude Code 的记忆进不了 Cursor	换工具等于清零
团队层	你的经验传不到同事的 Agent	同一件事全团队每人教一遍

Beacon 直接针对这三层：

会话层  → 完整捕获（prompts / 工具调用 / 命令 / 文件改动 / 批准 / MCP / token）
Harness 层 → 归一化成统一的 OpenTelemetry 事件模型
团队层  → 知识评审后可共享，通过 MCP 被任意 Agent 检索

1.3 它站在哪一层

┌─────────────────────────────────────────┐
│  Claude Code   Cursor   Codex   OpenCode │  ← 20+ 个 harness
└──────────────┬──────────────────────────┘
               │  hooks / OTLP / plugin / poll
┌──────────────▼──────────────────────────┐
│           Beacon（记忆层）                │
│  捕获 → 归一化 → Jev 打分 → 提炼 → 评审    │
└──────────────┬──────────────────────────┘
               │  MCP / Agent Skills
┌──────────────▼──────────────────────────┐
│      未来任意 harness 的 Agent            │
└─────────────────────────────────────────┘

关键点：它不替换你的 harness，也不替换你的模型。 它是插在中间的一层记忆。你可以继续用 Claude Code 写代码、用 Cursor 做 UI、用 Codex 跑批量，但三者共享同一份知识。

二、能力总览

2.1 核心闭环

跑 Agent
   ↓
捕获会话历史（prompts / 响应 / 工具 / 命令 / 文件 / 批准 / MCP / token）
   ↓
Jev 打分（证据强度 / 复用潜力 / 人工纠错信号）
   ↓
提炼知识（工作流 / 纠错 / 调试模式 / 仓库约定）
   ↓
人工评审（promote / review / discard）
   ↓
沉淀为可复用 Skills
   ↓
未来 Agent 通过 MCP 检索

2.2 MCP 工具集

Beacon 通过 MCP 暴露的核心工具：

工具名	作用	典型调用时机
`beacon_search_memory`	语义检索已沉淀的知识条目	Agent 开始新任务前
`beacon_get_session`	取回某次会话的完整 trace	复盘 / 复现问题
`beacon_list_skills`	列出已审批的可复用 Skill	任务规划阶段
`beacon_promote_knowledge`	把当前会话的某段流程提为知识候选	会话中出现成功模式时
`beacon_review_queue`	查看待评审的知识候选队列	每日/每周人工评审
`beacon_record_correction`	记录一次人工纠错（高信号）	你纠正 Agent 时
`beacon_repo_conventions`	读取当前仓库的已沉淀约定	进入陌生仓库时
`beacon_stats`	查看捕获量、命中率、token 统计	评估收益时
`beacon_dead_ends`	查询某仓库已记录的死路清单	避免重复踩坑

死路清单（beacon_dead_ends）是被低估的一个。大多数记忆系统只记「成功的做法」，但工程里最有价值的知识往往是你已经证明过行不通的路径。

2.3 捕获的事件维度

维度	内容
Session	会话 ID、harness 名、起止时间、状态
Prompt / Response	每一轮的完整输入与输出
Tool	工具名、入参、返回值（含截断标记）
Command	执行的 shell 命令与退出码
File	文件读写改动（路径 + diff 摘要）
Approval	人类批准/拒绝的操作
MCP	MCP 工具调用记录
Tokens	每轮的 token 消耗

统一基于 OpenTelemetry 事件模型归一化，本地存为 JSONL，无账号、无云依赖。

2.4 Jev 打分：为什么需要判断模型

Beacon 用 TypeSafe 的 Jev 作为打分引擎。Jev 是 2026 年 9 月 15 日发布的判断模型，特点：

特性	数值
输出形态	Choice / Score / Null（Noul）三类带概率的类型化答案
端到端延迟	70–500 ms
输入价格	$0.042 / 百万 token
输出价格	免费
相比通用大模型	快 20–200 倍

为什么必须用这种模型：给成千上万条会话打分，用旗舰模型在经济上不可行。Vercel 用 Jev 替换原分类器后提速 5–18 倍。判断模型让「大规模评估哪些会话值得学」这件事第一次变得划算。

Jev 对每条会话输出三个信号：

Evidence（证据强度）：这次流程是否真的跑通了（有没有测试/验证支撑）
Reuse（复用潜力）：这个模式未来还会不会再遇到
Human correction（人工纠错信号）：你有没有纠正过它（纠错是最高信号）

打分结果分三档：promote（自动提为知识）/ review（进人工队列）/ discard。

三、安装

3.1 安装 Beacon 本体

macOS / Linux（Homebrew）：

brew tap asymptote-labs/tap
brew install beacon

beacon endpoint install        # 安装捕获端点

Linux（deb / rpm）：

# 从 Release 页下载对应包
sudo apt install ./beacon_linux_amd64.deb
# 或
sudo dnf install ./beacon_linux_amd64.rpm

Windows（MSI）：

msiexec /i BeaconEndpointAgent--x64.msi
# 静默安装
msiexec /i BeaconEndpointAgent--x64.msi /qn

从源码：

git clone https://github.com/Asymptote-Labs/agent-beacon
cd agent-beacon
make install            # 或 cargo build --release（Rust 实现）

3.2 初始化与隐私模式

beacon init

向导会让你选择隐私级别，这一步要认真选：

模式	捕获内容	适用场景
`standard`	完整内容（prompt、响应、工具出入参、文件内容）	个人项目 / 可外发的代码
`metadata-only`	只捕获元数据（工具名、耗时、token、文件路径），不存正文	公司代码 / 有合规要求

beacon endpoint connect --privacy-mode metadata-only
beacon whoami            # 确认当前使用的身份与模式

公司环境默认选 metadata-only。 完整模式下，你的每一行代码改动、每一条 shell 命令都会被写进本地 JSONL。虽然不出本机，但一旦这台设备被审计、被同步、被备份，风险就来了。

3.3 验证捕获在工作

# 打开本地只读面板
beacon endpoint dashboard

# 或直接看原始事件流
tail -f ~/.beacon/endpoint/logs/runtime.jsonl | jq .

正常应该看到类似：

{
  "ts": "2026-09-22T10:14:32.118Z",
  "harness": "claude-code",
  "session_id": "sess_01J9ZQ...",
  "event": "tool_call",
  "tool": "Bash",
  "args": {"command": "npm test -- orders"},
  "exit_code": 0,
  "tokens": {"in": 12480, "out": 812}
}

四、客户端配置

4.1 Claude Code

claude mcp add beacon -- npx -y @asymptote-labs/beacon-mcp

或手动写入 ~/.claude.json：

{
  "mcpServers": {
    "beacon": {
      "command": "npx",
      "args": ["-y", "@asymptote-labs/beacon-mcp"],
      "env": {
        "BEACON_HOME": "/Users/you/.beacon",
        "BEACON_PRIVACY_MODE": "standard"
      }
    }
  }
}

验证：

claude mcp list
# 应看到 beacon: connected

4.2 Cursor

写入项目级 .cursor/mcp.json（或全局 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "beacon": {
      "command": "npx",
      "args": ["-y", "@asymptote-labs/beacon-mcp"],
      "env": {
        "BEACON_HOME": "/Users/you/.beacon",
        "BEACON_AUTO_RECALL": "true",
        "BEACON_MAX_RECALL_ITEMS": "5"
      }
    }
  }
}

BEACON_AUTO_RECALL=true 会让 Agent 在开始新任务时自动检一次记忆，不用你提醒。

4.3 VS Code（Copilot / Cline / Roo 等 MCP 客户端）

.vscode/mcp.json：

{
  "servers": {
    "beacon": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@asymptote-labs/beacon-mcp"],
      "env": {
        "BEACON_HOME": "/Users/you/.beacon",
        "BEACON_PRIVACY_MODE": "metadata-only"
      }
    }
  },
  "inputs": []
}

4.4 Trae

~/.trae/mcp.json：

{
  "mcpServers": {
    "beacon": {
      "command": "npx",
      "args": ["-y", "@asymptote-labs/beacon-mcp"],
      "disabled": false,
      "env": {
        "BEACON_HOME": "/Users/you/.beacon"
      }
    }
  }
}

4.5 Codex CLI

~/.codex/config.toml：

[mcp_servers.beacon]
command = "npx"
args = ["-y", "@asymptote-labs/beacon-mcp"]
env = { BEACON_HOME = "/Users/you/.beacon" }

4.6 通用环境变量

变量	默认	说明
`BEACON_HOME`	`~/.beacon`	数据目录
`BEACON_PRIVACY_MODE`	`standard`	`standard` / `metadata-only`
`BEACON_AUTO_RECALL`	`false`	新任务自动检索记忆
`BEACON_MAX_RECALL_ITEMS`	`3`	单次召回条数（别调太大，吃上下文）
`BEACON_REDACT`	`true`	捕获时脱敏密钥
`BEACON_TTL_DAYS`	`90`	原始 trace 保留天数

五、三个实战场景

5.1 场景一：新 Agent 接手老仓库的「隐性约定」

问题：你接手一个 30 万行的老仓库。README 写了三行，AGENTS.md 不存在。真正的约定散落在：

「这个服务的重启必须走灰度脚本，不能 systemctl restart」
「订单金额一律用 Decimal，禁止 float」
「tests/ 下的 mock 数据库是禁用的，要用 testcontainers」

这些知识存在于老员工的脑子里，以及——存在于过去半年几百次 Agent 会话的纠错记录里（如果你们之前开着捕获）。

做法：

1. beacon endpoint install（如果之前没装）
2. 全团队跑两周，正常用各自的 Agent
3. 期间每次纠正 Agent 时，用 beacon_record_correction 显式记一条
4. 两周后跑：
   beacon extract --repo . --min-score 0.7 --out CONVENTIONS.md
5. 人工评审 CONVENTIONS.md，删掉错的，留下真的
6. 结果转成 AGENTS.md 提交进仓库

产出示例：

# 仓库隐性约定（从 214 次会话中提取）

## 高置信度（出现 ≥ 10 次，人工纠错 ≥ 3 次）
- 金额计算必须用 Decimal，出现 float 的 PR 一律打回（12 次纠错）
- 服务重启走 ./scripts/rolling-restart.sh，禁止 systemctl restart（9 次纠错）
- 集成测试用 testcontainers，禁止 mock 数据库（7 次纠错）

## 中置信度（出现 3-9 次）
- 新增 API 必须同时补 OpenAPI 注解
- 日志用结构化 logger，禁止 console.log

## 死路清单（已证明行不通）
- ❌ 用 jest.mock('pg') 做集成测试 → 会漏掉真实的事务行为
- ❌ 在 migration 里直接改大表 → 触发过一次线上锁表

死路清单的价值最高。它记录的是「团队已经付过学费的地方」。

5.2 场景二：跨工具复用调试经验

问题：你在 Cursor 里花了两小时排查一个诡异的构建失败——根因是 pnpm workspace 里某个包的 exports 字段写错了，导致 ESM/CJS 解析不一致。你修好了，很爽。

三个月后，Codex CLI 在另一个仓库遇到同类问题。它不知道你排查过。

做法：

1. 修完之后立刻：
   beacon_promote_knowledge \
     --session sess_xxx \
     --title "pnpm workspace exports 字段导致的 ESM/CJS 解析失败" \
     --tags "pnpm,esm,cjs,build"

2. 系统用 Jev 打分 → 因为是成功修复 + 有明确根因 + 通用模式 → promote

3. 进评审队列确认：
   beacon_review_queue --list
   beacon_review_queue --approve kn_01J9Z...

4. 以后任何 harness 的 Agent 遇到构建解析错误时：
   beacon_search_memory --query "ESM CJS 解析失败 pnpm" 
   → 直接命中三个月前那条

关键收益：这条知识从 Cursor 产生，被 Codex 消费。这是 Beacon 区别于任何单 harness 记忆方案的核心。

5.3 场景三：团队级知识库与新人 onboarding

问题：新人入职第一天，Agent 对他一无所知，他也不知道仓库的坑在哪。

做法：

1. 团队共用一份已评审的知识库（导出为 Git 仓库里的 .beacon/knowledge/）
2. 新人 clone 仓库后：
   beacon load --from .beacon/knowledge/
3. 他的 Agent 从第一次会话起就能召回团队的集体经验
4. 他踩的新坑，经过评审后回流进知识库

配套的工作流约定：

环节	谁做	频率
纠错记录	每个人，随时	日常
知识评审	轮值一人	每周 30 分钟
死路清单更新	谁踩坑谁加	随时
过期知识清理	轮值一人	每月

评审这一步不能省。自动提炼的知识有噪音，未评审直接喂给 Agent，等于给上下文里灌垃圾。

5.4 场景四：CI 里的回归拦截

问题：Agent 改了代码，通过了它自己写的测试，但违反了团队三个月前定下的约定（比如「金额不能用 float」）。这类问题在 review 时才被发现，往返成本高。

做法：把 Beacon 的死路清单接进 CI。

# .github/workflows/convention-check.yml
name: convention-check
on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Load team knowledge
        run: |
          npx -y @asymptote-labs/beacon-cli load --from .beacon/knowledge/

      - name: Check conventions
        run: |
          npx -y @asymptote-labs/beacon-cli check \
            --diff "$(git diff origin/main...HEAD)" \
            --rules .beacon/rules.yaml \
            --out convention-report.md

      - name: Comment
        if: always()
        run: |
          gh pr comment ${{ github.event.number }} --body-file convention-report.md

.beacon/rules.yaml：

rules:
  - id: no-float-money
    source: beacon_dead_ends
    pattern: '(float|double)\s+\w*(amount|price|money|total)'
    severity: BLOCKER
    message: "金额必须用 Decimal。这条约定来自 12 次人工纠错。"

  - id: no-mock-db-in-integration
    source: beacon_dead_ends
    pattern: "jest\\.mock\\(['\"]pg['\"]\\)"
    severity: MAJOR
    message: "集成测试用 testcontainers。mock 数据库会漏掉真实事务行为。"

  - id: rolling-restart-only
    source: beacon_dead_ends
    pattern: "systemctl\\s+restart"
    severity: BLOCKER
    message: "重启走 ./scripts/rolling-restart.sh。"

关键点：这些规则不是人拍脑袋写的，是从真实纠错记录里提取出来的。这正是 Beacon 相比普通 lint 规则的价值——规则来源是被证明过的失败，而不是想象中的风险。

5.5 知识条目的结构

了解条目长什么样，才知道评审时该看什么：

{
  "id": "kn_01J9ZQ8X4T",
  "title": "pnpm workspace exports 字段导致 ESM/CJS 解析失败",
  "type": "debugging_pattern",
  "source_session": "sess_01J9ZQ7M2K",
  "source_harness": "cursor",
  "repo": "github.com/acme/frontend-monorepo",
  "jev_scores": {
    "evidence": 0.91,
    "reuse": 0.84,
    "human_correction": 0.67
  },
  "verdict": "promote",
  "content": {
    "symptom": "构建报 ERR_MODULE_NOT_FOUND，但文件确实存在",
    "root_cause": "子包 package.json 的 exports 只声明了 import，缺 require 条件",
    "fix": "补齐 exports 的 require 分支，或用条件导出",
    "verification": "node -e \"require('./dist/index.js')\" 不再报错"
  },
  "tags": ["pnpm", "esm", "cjs", "build", "workspace"],
  "review": {
    "status": "approved",
    "by": "zhangsan",
    "at": "2026-09-18T09:22:11Z"
  },
  "usage_stats": {
    "recalled": 34,
    "helped": 27,
    "helpless": 7
  }
}

usage_stats 是被低估的字段。helpless 次数高的条目说明「召回但不解决问题」，应该降权或重写。定期看这个字段清理知识库：

beacon_review_queue --list --sort-by helpless --min-recalled 10

5.6 与 Agent Skills 的关系

Beacon 沉淀的知识有两种消费方式：

方式	载体	优点	缺点
MCP 检索	运行时按需召回	不占固定上下文	需要 Agent 主动检索
Agent Skills	写成 skill 文件常驻	被动生效，不用检索	占上下文，数量有限

用法建议：

高频 + 通用  → 写成 Skill（如「本仓库的迁移流程」）
低频 + 专用  → 留在 MCP 检索（如「某个罕见报错的解法」）
死路清单     → 两者都要（Skill 里放 Top 5，MCP 里放完整清单）

导出为 Skill：

beacon export --format skill \
  --min-score 0.85 \
  --max-items 10 \
  --out .claude/skills/repo-conventions/

上限 10 条。Skill 常驻上下文，多了就是长期缴税。

5.7 团队同步的三种模式

模式	做法	适合
Git 提交	知识库导出成 JSON 放仓库 `.beacon/knowledge/`	小团队、知识变更不频繁
独立仓库	知识库单独一个 Git 仓库，各项目 submodule 引入	多个项目共享一套约定
中心服务	自建 Beacon 同步服务，客户端定时拉取	大团队、需要权限分级

Git 模式最容易起步，且天然有 review 流程（知识变更走 PR）。缺点是没有权限分级——任何人都能看到全部知识。

中心服务模式要注意：一旦知识集中，泄露半径就从「一台设备」变成「全公司」。合规评审必须前置。

5.8 四个常见误用

误用	表现	后果	正解
把 Beacon 当聊天记录备份	开了 standard 模式但不做评审	几百 MB JSONL 堆在磁盘，零收益	评审是收益的必经环节，不开就别装
召回条数调很大	`BEACON_MAX_RECALL_ITEMS=20`	上下文被知识条目撑满，主任务反而变差	保持 3–5 条
知识条目写得太抽象	「写代码要规范」	永远不会被命中，因为无法匹配具体场景	每条必须含具体症状 + 根因 + 验证方式
不做清理	知识库只增不删	过期知识（旧框架、旧 API）误导 Agent	每季度清理 `helpless` 高的条目 + 标记废弃时间

「知识条目写得太抽象」是最常见也最难自察的一个。判断标准：这条知识能不能直接变成一条可执行的动作？如果不能，它就是废话，会被检索到但没用。

六、选型对比

6.1 与相邻方案的关系

方案	解决什么	不解决什么	与 Beacon 的关系
Beacon	跨 harness 的会话经验沉淀与复用	不定义当前任务的目标	—
`AGENTS.md` / `CLAUDE.md`	声明式项目规范	只写你想到要写的，学不到新东西	互补：Beacon 提炼出的约定，最终应固化进 AGENTS.md
Cursor Rules / Copilot Instructions	单 harness 的静态指令	锁死在单一工具	Beacon 是它们的跨工具超集
Context7 MCP	拉最新官方文档	不管你自己的代码与约定	互补：一个管外部知识，一个管内部经验
向量数据库 + RAG	通用检索	需要自己搭采集、打分、评审全流程	Beacon 是「Agent 会话」这个特定场景的开箱实现
模型自带记忆（如 ChatGPT Memory）	跨平台记住用户偏好	粒度粗、不可评审、不沉淀工程知识	不同层次

6.2 什么时候不该用 Beacon

情况	建议
单人、单工具、短期项目	不值得，AGENTS.md 就够了
强合规环境（金融/医疗/涉密）	用 `metadata-only`，且先过法务
一次性脚本任务	用不上
代码完全不能出本机的场景	可以本地用，但禁用一切共享与同步

6.3 与 AGENTS.md 的正确分工

              ┌──────────────────────────┐
              │       AGENTS.md          │  ← 你主动声明的规范（权威、稳定、少量）
              │   "金额用 Decimal"        │
              └────────────┬─────────────┘
                           │
              ┌────────────▼─────────────┐
              │        Beacon            │  ← 从实践中自动学到的（发现性的、大量）
              │  "12 次纠错证明 float 会被打回"│
              └────────────┬─────────────┘
                           │ 定期沉淀
              ┌────────────▼─────────────┐
              │   更新后的 AGENTS.md      │
              └──────────────────────────┘

闭环：Beacon 负责发现约定，AGENTS.md 负责固化约定。只用一个都不完整——没有 Beacon，你永远不知道该写哪条；没有 AGENTS.md，学来的知识没有权威载体。

七、安全与隐私：必须先想清楚

7.1 三条红线

红线一：它会捕获你的完整会话

standard 模式下，以下内容全部落盘到 ~/.beacon/：

你写的每一句 prompt
模型的每一次完整输出
每一条 shell 命令及其输出
每一次文件读写的完整内容

这意味着：如果你的 prompt 里贴过生产数据库密码、API Key、用户数据，它们会以明文 JSONL 形式留在磁盘上（除非 BEACON_REDACT 生效，但脱敏规则不一定覆盖所有格式）。

必做：

# 1. 公司环境强制 metadata-only
beacon endpoint connect --privacy-mode metadata-only

# 2. 开启脱敏
export BEACON_REDACT=true

# 3. 定期自查
grep -rIlE "sk-[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|password" ~/.beacon/ | head

红线二：共享知识库等于共享代码上下文

把知识库导出给团队时，知识条目里可能夹带代码片段、内部服务名、架构细节。导出前必须人工过一遍。

beacon export --out team-knowledge.json
# 导出后先自己读一遍再提交

红线三：MCP 是双向的

Agent 能读 Beacon，也能写 Beacon。一个被注入攻击的 Agent 可以往你的知识库里写入恶意「约定」，污染后续所有会话。

缓解：

{
  "beacon": {
    "BEACON_WRITE_SCOPE": "skills-only",
    "BEACON_REQUIRE_REVIEW": "true"
  }
}

BEACON_REQUIRE_REVIEW=true 时，任何知识条目必须人工批准才能被召回。

7.2 一份安全配置基线

beacon endpoint connect \
  --privacy-mode metadata-only \
  --redact true \
  --ttl-days 30 \
  --require-review true \
  --no-telemetry-egress

参数	值	理由
`--privacy-mode`	`metadata-only`	公司环境默认不存正文
`--redact`	`true`	兜底脱敏
`--ttl-days`	`30`	原始 trace 定期老化
`--require-review`	`true`	知识必须人工批准
`--no-telemetry-egress`	—	禁止任何外发

八、故障排查表

#	症状	根因	排查命令	解法
1	`beacon mcp` 起不来	Node 版本过低 / npx 缓存问题	`node -v`	升到 Node 20+；`npx clear-npx-cache`
2	Claude Code 显示 `beacon: disconnected`	MCP 配置路径写错	`claude mcp list`	检查 `~/.claude.json` 的 `mcpServers` 层级
3	面板打开但没有任何会话	端点未安装	`beacon endpoint status`	跑 `beacon endpoint install`
4	`runtime.jsonl` 空文件	隐私模式挡掉了全部内容	`beacon whoami`	确认模式；切 `standard` 测试
5	JSONL 里搜到明文密钥	脱敏未开或规则不全	`grep -rIl "sk-" ~/.beacon/`	开 `BEACON_REDACT`；扩展自定义正则
6	知识条目质量很差	没做人工评审	`beacon_review_queue --list`	开 `BEACON_REQUIRE_REVIEW=true`
7	召回结果不相关	召回条数太大灌水	看 `BEACON_MAX_RECALL_ITEMS`	降到 3
8	上下文被召回内容撑爆	同上 + 条目太长	`beacon_stats` 看命中条数	限制条数；摘要化长条目
9	某 harness 完全没被捕获	该 harness 用 poll 模式，间隔长	`beacon endpoint status --verbose`	缩短 poll 间隔或改用 hooks
10	Cursor 里 MCP 工具不出现	配置文件放错目录	检查 `.cursor/mcp.json` vs `~/.cursor/mcp.json`	项目级优先，放项目根
11	Windows 上 MSI 装完无反应	未以管理员权限	事件查看器	用管理员 PowerShell 重装
12	Homebrew tap 失败	网络问题	`brew update`	换源或走 Release 包
13	磁盘占用暴涨	trace 未老化	`du -sh ~/.beacon`	设 `--ttl-days 30`，加定时清理
14	不同 harness 的同一会话被拆成两条	会话 ID 不统一	`jq '.session_id' runtime.jsonl \| sort -u`	升级到最新版，用统一 session 规范
15	导出给团队后别人加载失败	版本不兼容	`beacon --version` 两边对比	统一版本；导出时带 schema 版本
16	Jev 打分全为 discard	打分阈值配置过严	`beacon config get scoring`	调 `--min-score` 到 0.5 试试
17	死路清单为空	没记录过失败路径	`beacon_dead_ends --repo .`	显式用 `beacon_record_correction` 记失败
18	两个项目知识串味	未按仓库隔离	`beacon_stats --by-repo`	开启按 repo 隔离的命名空间

九、成本与收益评估

9.1 成本

项	量级
本地存储	每千次会话约 200MB–1GB（standard 模式）
Jev 打分	输入 $0.042/百万 token，输出免费；千次会话约几美分
捕获开销	进程常驻约 100–150MB 内存
人工评审	每周 30 分钟（不可省）

9.2 收益的判断方法

跑一个月后看这三个数字：

beacon_stats --window 30d

指标	健康值	说明
知识召回命中率	> 40%	Agent 检索时确实找到有用东西的比例
重复纠错下降率	> 30%	同一个错误被重复纠正的次数是否在下降
死路清单命中数	> 0	Agent 有没有因为死路清单避开已知坑

召回命中率低于 20% 说明知识库没沉淀出真东西，检查两件事：评审是否认真做了；知识条目是否太抽象（「要注意代码质量」这种废话不会被命中）。

十、一句话总结

Beacon 解决的是 Agent 工程里最隐蔽的一种浪费：同一个教训，每个 Agent、每个人、每个工具都要重新学一遍。

它不让你变聪明，它让你的团队不再重复变笨。

但请记住这次的先后顺序：

1. 先想清楚隐私模式（公司环境默认 metadata-only）
2. 再装端点、跑两周
3. 然后认真做人工评审
4. 最后把学到的约定固化进 AGENTS.md

跳过第 1 步会有合规风险，跳过第 3 步会得到一库垃圾。这两步是这套东西唯一的门槛。

Beacon MCP：让 Claude Code 学到的东西，Codex 和 Cursor 也能用上

简介

安装命令