witness

witness——一款蒸馏引擎，记录事物随时间变化的历程。

witness 可将一串文本转化为一份带日期的记录，呈现其主题如何变化。 将 AI 编码会话交给它，它会追踪你的思考和工作方式如何变化。也可以交给它市场评论、研究笔记或任何文档流，它便会追踪相应内容的变化。它是一个纯 Go 二进制程序，使用本地 SQLite 归档和纯 Markdown，并通过 MCP 提供给你的 Agent。

它围绕的核心是随时间发生的变化及其来源。当某个属性的值发生变化时，witness 不会覆盖它，而是为旧值标注结束日期，再开启一个新值，并记录哪些来源记录促成了这一变化。因此，归档可以回答*“这是如何形成的”，而不只是“现在是什么情况”*。

“啊，你一直都在我身边。 我真正的导师…… 我指引前行的月光……” — 路德维希，圣剑

两种使用方式

1. 观察自己在与 AI 协作时的成长。 将它安装到 Claude Code 或 OpenCode 中，它便会在后台捕获你的会话——无需提示词，也无须刻意安排。它会提炼数月间你的思维、工作方式、习惯和盲点如何变化，并为每条判断提供证据。这是 witness 开箱即用的默认配置。

它的设计侧重自我反思，而非复制人格：目的是让你的 Agent 理解你，并为你留下可反复阅读的记录，回顾你的思考与成长。它是一个纯粹的工具，而非教练——负责捕获、整理并提供信息。至于在此基础上构建教练（“你已经这样做了三次……”），则留给读取其输出的其他项目。

2. 为任意文本语料构建变化历史。 编写一个 lens——用提示词描述需要关注的内容以及要追踪的维度——将 witness ingest 指向 NDJSON 记录，同一套四阶段引擎便会运行。整个机制并非针对个人设计：原始记录 → 观察结果 → 带日期的属性 → 叙述。

以下是一个完整的实操示例，本文这一节就是用它撰写的。在一个完全没有启用人物 lens 的归档中，使用覆盖市场评论的 regime lens：7 条新闻记录生成了 22 条观察结果和 13 个属性。随后，市场状态从鹰派转向鸽派，归档将其记录为历史，而不是直接替换：

inflation/core_trend
  "Disinflation has broken rather than paused: core CPI reaccelerating…"   valid_to 2026-06-…
  "Core is disinflating persistently rather than reaccelerating…"          (current)

一次审查中，有五个属性以这种方式结束旧值并重新开启。生成的简报甚至指出，新的数据证伪了它自己先前关于事件先后顺序的论断——这正是保留历史而非只保留最新快照的意义。

坦诚说明： 引擎通用，但 witness 随附的所有内容都围绕个人设计——内置的 default lens、示例 lens 和摘要提示词都要求“关注与这个人有关的情况”。对于非个人语料，你需要自行编写 lens（三个文件），还可以按需用一个文件覆盖摘要提示词。目前还没有市场 lens 或研究 lens 预设；引擎不依赖特定领域，但内置配置并非面面俱到。

这是你吗？

如果你曾经希望：

• 记住在 AI 编码会话中学到的内容——无论是 Claude Code 还是 OpenCode——而不是在上下文窗口重置时丢失这些内容。
• 为你的思考、工作方式和习惯拥有一个第二大脑 / AI 记忆，供你的 Agent 查询。
• 追踪自己随着时间成长为开发者的过程——包括反复陷入又走出的陷阱——并为每项记录的变化保留来源信息。
• 保留一份日志 / 回顾，记录自己的思考与变化，并能在数月后重新阅读。
• 提炼你关心的语料库——市场新闻、知识库、研究笔记、会议记录——形成一份有日期的历史，记录其状态如何变化，而不是堆积一批摘要。使用 witness ingest 以 NDJSON 格式导入。
• 通过 MCP 从你的 Agent 查询以上任何内容，而不必在每次会话中重新解释上下文。

目录： 工作原理 · 视角 · 示例 · 阅读档案 · 命令 · 安装 · 配置 · 你的数据归你所有

工作原理

四个层级——一个真实来源，三个由其派生且可重新生成的层级：

层级	类型	内容
raw（L0）	真实来源	原样捕获每一轮对话——来自 Claude Code 的稳定钩子字段（UserPromptSubmit.prompt、Stop.last_assistant_message），或 OpenCode 的本地 SQLite 会话数据库（message/part 文本）。仅追加，绝不经过 LLM 处理。
observations（L1）	派生	一个轻量的逐会话工作器会挖掘关于你的、以证据为依据的原子观察，并按视角标记。仅追加。
facets（L2）	派生，双时间	一个定期运行的审阅器会将观察综合为不断演变的特征，每项特征都会保留其变更历史（valid_from/valid_to）——这样档案回答的是“我如何变化”，而不只是“我现在是什么样”。旧值永不删除。
profile（L4）	派生叙述	从特征提炼出的简短、便于阅读的 Markdown 摘要——每个视角一份，另有一份跨视角的 unified 概述。读取时生成：witness profile（或 MCP get_profile）仅在特征发生变化时才会重建，因此未读取的概述不会产生任何开销。读取缓存内容会立即返回；重建约需 13 秒。

该档案采用仅采集 / 仅拉取模式：witness 会在各处捕获并提炼内容，但绝不会向会话注入任何内容。它不会主动推送任何信息——你（或 Agent）可按需读取概述。raw/observations/facets 存储在同一个内嵌 SQLite 数据库（witness.db）中；概述则以纯 Markdown 格式存放在 profile/ 下。

视角

每项观察/特征都带有一个视角标签：

• default — 全局视角，每个会话都会运行，跨领域。它能做到单领域跟踪器无法做到的事：发现“能精准诊断知识盲区”这一特征同时出现在数学、编码和职业发展中。
• 已注册的视角（例如 math）——特定领域的视角，只需注册一次并全局启用。witness lens register math ./math/ 会将定义（一个目录）添加到中央注册表；witness lens enable math 会使其在每个会话中运行（与 default 一同运行）。视角是共享的，不绑定到任何代码仓库，因此同一个 math 视角适用于你所有的数学工作。

编写 lens

一个 lens 是由 3 个文件组成的目录：

math/
  lens.json     settings: name, dimensions, optional per-lens models
  extract.md    per-session — mines observations (the whole file is the prompt)
  review.md     periodic — synthesizes observations into facets (the whole file is the prompt)

// math/lens.json
{ "name": "math", "dimensions": ["speed", "independence", "proof_rigor", "abstraction", "confusion_tolerance"] }

You are observing one session through a MATH-LEARNING lens. Notice things about the
person as a mathematician — how they reason, get stuck, and climb out…
Return ONLY a JSON array. Each element:
[{ "dimension": "proof_rigor", "observation": "…", "evidence": "…", "poignancy": 6 }]

请记住一条规则：每个提示词文件都会原样用作系统提示词，并且会替换内置的 default 提示词，而不是扩展它们——因此，每个文件都必须独立完整，包含输出 JSON 架构（工具会将对话记录 / 观察结果追加为用户消息，但不会为你注入架构）。

项目附带两个完整且可直接复制粘贴的 lens，供你作为起点。复制目录，并根据你的领域改写维度和文案：

• prompts/lens/example/ — 个人 lens（数学学习），用于跟踪某人的工作过程。
• prompts/lens/corpus-example/ — 非个人 lens（市场状态），用于跟踪非你本人的对象。研究笔记、知识库、事件报告或任何文档流都可以从这里开始；其 README 说明了当跟踪对象不再是个人时需要做哪些调整。

cp -R "$CLAUDE_PLUGIN_ROOT/prompts/lens/example" ./math   # edit the files, then:
witness lens register math ./math      # copies the definition into your store (a snapshot)
witness lens enable  math               # start running it on every session

register 会存储一份副本——之后编辑原文件不会产生影响，除非重新注册。 enable 是单独的开关，只有启用后才会实际运行。

每个 lens 的模型（可选）。 默认情况下，所有 lens 都使用默认模型（witness config set triage_model / distill_model）。对于少数需要较强模型的 lens，可以仅为其指定更强的模型——而不用让每个会话都承担相应成本——方法是在其 lens.json 中添加 extract_model / review_model：

{ "name": "math", "dimensions": ["proof_rigor"], "extract_model": "claude-sonnet-5" }

省略某个字段（或将其留空）即可使用默认模型。由于 register 存储的是快照，请编辑已注册副本 <witness-data-dir>/lenses/<name>/lens.json，或编辑源文件后重新注册。运行 witness lens show <name>，即可查看 lens 实际解析出的配置。

源目录可以位于任意位置。作为推荐的规范位置，witness 会将已注册副本保存在 config.toml 旁边的 <witness-data-dir>/lenses/<name>/ 下（通常是 ~/.local/share/witness/lenses/<name>/，或 $WITNESS_HOME/lenses/<name>/）。你可以直接编辑已注册副本，但这只是惯例，并不限制传递给 lens register 的目录位置。

示例：一个瞬间的完整流程

假设某个会话中有以下对话（虚构）：

你： 迁移在生产环境里总是失败，但在本地能通过——我就手动跑一下，然后继续吧

你： ……等等，生产环境到底哪里不同？先对比一下这两个架构，再动手

下面是各层对它的处理方式。

原始记录（L0） — 原样捕获，不作任何解读：

user  the migration keeps failing on prod but passes locally — I'll just run it by hand and move on
user  wait, what's actually different about prod? let me diff the two schemas before I touch anything

观察结果（L1） — worker 提取一条原子化、以证据为依据的观察：

[thinking] Caught the urge to hand-patch around a failure and redirected to isolating the
           prod/local difference before acting.
  evidence: "run it by hand and move on" → "what's different about prod? diff before I touch anything"
  poignancy: 6    lens: default

维度（L2） — 经过若干个这样的瞬间后，reviewer 会综合形成一个不断演变的属性，并且保留历史记录（这正是关键所在——它展现的是变化，而不只是当前状态）：

default · thinking · diagnoses_before_acting                        confidence 0.82
  2026-05 → now       Catches the reflex to work around a failure and isolates the
                      mechanism first; gates action on understanding the cause.
  2026-02 → 2026-05   Tended to apply the first workaround that unblocked the task.   (superseded)

个人档案（L4） — 你实际阅读的叙述内容（witness profile）：

default

你正在逐渐形成一种先诊断再行动的工作方式。几个月前，你还会倾向于先用任何能让任务继续推进的方法；现在，你会经常察觉到这种冲动，并转而在动手前先找出问题的机制……

这些内容不会被推送到你的会话中——你可以在需要时自行阅读（witness profile），也可以由 Agent 按需提取相关维度。

编写自己的摘要提示词

随附的 unified 提示词会撰写一份个人成长画像。如果你的档案记录的是其他内容 ——市场记录、研究笔记、项目日志——放入你自己的提示词即可，它会优先生效：

<data-root>/summarize/unified.md    your prompt (overrides the built-in one)
<data-root>/summarize/lens.md       same, for the per-lens summaries

witness doctor 会打印数据根目录。该文件就是完整接口：无需运行命令，也无需注册。删除它即可恢复使用内置提示词。

这样，相同的维度就能生成截然不同的文档——例如简洁的风险备忘录，而非人物画像。由于没有自定义提示词时仍会使用内置提示词，因此 witness 升级并附带改进后的默认提示词时，你仍能用上；一旦自定义，升级就永远不会触碰你的文件。

阅读档案

人类阅读叙述；Agent 阅读结构化数据。通过 MCP：

• get_profile(lens) — 叙述性档案（散文）；省略 lens 可获取统一画像。
• get_facets(lens) — 当前的结构化维度。
• search_observations(query, lens) — 对观察记录进行本地向量搜索。
• record_observation(...) — 会话中的 Agent 直接写入一条与决策相关的观察记录（原样传递），记录后续审阅者可能会遗漏的上下文。
• delete_observation(obs_id) — 删除错误的观察记录。

命令

可见的入口，完全按照 witness --help 中的分组方式排列：

分组	命令
阅读你的档案	status · profile · facets · observations · ingest
视角	lens
配置	config
设置	doctor · install · wire · unwire
维护	cleanup · export

采集、worker 和 MCP 服务都是由 Claude Code/OpenCode 调用的内部入口，不需要手动输入。witness import 和 witness worker … 是隐藏命令： 它们用于恢复和调试，且它们执行的所有操作也会自动完成。

• witness profile [lens] — 输出叙事画像（默认：统一画像）。
• witness facets [lens] — 输出当前结构化维度（MCP get_facets 的 CLI 等效命令）。
• witness observations search <query> [--lens <lens>] [-k N] — 对观察记录进行语义搜索。
• witness observations record --session <id> --dimension <name> --observation <text> — 暂存一条有效观察记录并启动工作进程。
• witness observations delete <obs_id> — 删除错误的观察记录。
• witness worker review [--full] — 强制执行 L2 审查，并根据现有观察记录重新生成 L4 画像。（与其余 worker 命令一样，此命令隐藏；审查通常按自身计划运行——review_every / review_poignancy——因此手动调用属于例外。--full 还会运行涌现式长期轨迹处理。）
• witness lens register|enable|disable|list — 管理视角。
• witness lens backfill <name> [--fresh] — 在完整历史记录中重新挖掘一个视角并刷新其维度；--fresh 会先删除该视角的观察记录和维度（适用于提示词有变更的情况）。
• witness lens load-default — 重新植入 / 恢复内置的“default”个人成长视角（首次使用时会自动植入一次，且可完全删除，因此可用此命令将其恢复）。
• witness import --agent opencode — 将 OpenCode 的本地会话数据库增量同步到 L0，并启动后台提炼，无需等待。
• witness import --agent claude — 为已捕获的 Claude Code hook 数据启动提炼。
• witness status — 查看已捕获的内容、工作进程是否正在运行，以及提炼数据的新鲜度（脚本可使用 --json）。
• witness worker run / witness worker stop — 后台提炼工作进程的操作员应急入口（在 --help 中隐藏；通常由编辑器 hook 启动）。run 会在前台处理完队列，--detach 会将其转到后台。它接受 --since / --until，用于按会话最新原始时间戳筛选待处理会话——例如，witness worker run --since 7d 会提炼过去七天内更新的会话。时间范围也接受 RFC3339 时间戳或 UTC 日期（YYYY-MM-DD），且不会丢弃所选范围之外的会话。
• witness cleanup — 以交互方式回收旧的原始转录（保留观察记录和画像）。
• witness export <path> — 写入一致的单文件数据库快照（可安全备份 / 云同步）。添加 --all 后，<path> 会变为一个目录，其中包含完整归档：该快照以及 config.toml、lenses/ 和 profile/。备份时请使用 --all——参见你的数据属于你。
• witness install [--path <dir>] — 在指定路径（或默认数据根目录）创建新的 witness 归档。创建目录结构和数据库架构。通常每台机器只需调用一次；对于从源码检出的用户，install.sh 会处理此操作。
• witness wire <claude|opencode> — 接入编辑器集成（Claude Code 使用 hook + MCP；OpenCode 使用插件 + MCP）。此命令供源码检出的版本使用；install.sh 会为你调用此命令。
• witness unwire <claude|opencode> — 移除编辑器集成接线，不会改动你的归档。
• witness ingest [--file <path>] — 以 NDJSON 格式接收结构化记录（笔记、日志、市场数据），并将其提炼到归档中。可从 stdin 或文件读取。参见prompts/SCHEMA.md中的记录规范。
• witness doctor — 健康检查（验证嵌入器能否运行，以及 EN/ZH 检索是否正常）。

单一二进制文件，无需运行时

整个程序是一个独立的 Go 二进制文件——无需 Python、外部服务、向量数据库或云密钥。本地多语言（英语和中文）嵌入通过 GoMLX 以纯 Go 运行（CGO_ENABLED=0，已验证：与 ONNX Runtime 完全一致）。提炼默认使用你现有的 Claude Code 身份验证，通过 claude -p 执行；设置 runner = opencode 可改用私有的 opencode serve 执行器。

安装

./install.sh claude    # Claude Code: build, fetch model (~448MB once), wire hooks + MCP
./install.sh opencode  # OpenCode: build, fetch model, wire local plugin + MCP

就是这么简单——此操作具有幂等性，在 git pull 后可安全地重新运行。目标为必填项：脚本会构建二进制文件、配置归档，并将匹配的蒸馏运行时绑定到 config.toml（runner = claude 或 runner = opencode）。脚本还会询问是否将 witness 命令添加到 PATH（用于 witness profile、doctor、lens、import、status、cleanup、ingest）。也提供了等效的 make 目标（make install、make install-opencode、make build、make doctor、make uninstall、make uninstall-opencode、make clean）。移除编辑器集成：运行 make uninstall 或 make uninstall-opencode（移除集成配置，不会触碰你的数据）。

Windows

Windows 使用独立 zip 包，而非 shell 安装脚本（没有可保证用于运行钩子封装程序的 shell）。从发布页面下载 witness-windows-amd64.zip（Intel/AMD）或 witness-windows-arm64.zip，解压后会得到一个 witness\ 文件夹，其中包含 witness.exe 和嵌入模型。然后，在 PowerShell 中进入该文件夹并运行：

.\witness.exe wire claude      # Claude Code
.\witness.exe wire opencode    # OpenCode

任一命令都会将整个包复制到 %LOCALAPPDATA%\witness，将其添加到用户 PATH，并配置归档。zip 包中包含提示词模板和约 448MB 的模型，以及 exe 文件；二进制文件会相对于自身路径查找这两项。两条命令都运行也没问题——复制操作具有幂等性，而且它们配置的是不同的编辑器。

两者配置的内容以及差异原因：Claude Code 会自行启动钩子，因此 wire claude 会将 exec 格式的钩子（{command: witness.exe, args: [...]}）写入 settings.json。而 OpenCode 正好相反——它的 插件 会启动 witness，因此 wire opencode 会将已安装的 witness.exe 路径写入插件和 MCP 条目。两者都不需要 shell 或 Git Bash。

移除编辑器集成：运行 witness.exe unwire claude / unwire opencode（移除钩子/插件及 MCP 条目）。复制的文件和 PATH 条目会保留，因为另一个集成可能仍在使用它们。

OpenCode 支持

OpenCode 支持包含两部分：

• 插件会在启动时以及会话进入空闲状态时协调 OpenCode 的 SQLite 数据库，然后在允许时请求适合笔记本电脑的自动启动门控执行蒸馏。从源码安装会在 ~/.config/opencode/plugins/witness.js 写入本地插件；已发布的安装可以使用 npm 插件 @witness-ai/opencode。（Windows 上的路径相同——OpenCode 会将 XDG_CONFIG_HOME 作为配置目录，否则使用 ~/.config，没有 Windows 专用分支，因此插件会放在 %USERPROFILE%\.config\opencode\plugins\。）
• 名为 witness 的 OpenCode MCP 条目会启动与 Claude Code 相同的 MCP 服务，并提供 get_profile、get_facets、search_observations、record_observation 和 delete_observation。

npm 包包含 OpenCode 插件、witness CLI 封装程序、预构建的 witness 二进制文件和提示词。默认方式仅配置配置文件：将插件添加到 ~/.config/opencode/opencode.json，OpenCode 会在启动时通过 Bun 自动安装它。如果缺少 mcp.witness，插件会自动为你注册该条目。

npm 包支持 OpenCode 集成和常规 CLI 用法（witness profile、ingest 等）。编辑器集成配置（witness wire / unwire）是源码检出目录中的命令——npm 用户应直接在 opencode.json 中配置插件，插件会自动注册 MCP。归档配置和记录导入（witness install、witness ingest）在 npm 包中也可正常使用。

npm 发行版仅支持以下平台：

操作系统	架构	npm 平台包
macOS	Apple Silicon（darwin/arm64）	@witness-ai/opencode-darwin-arm64
Linux	x86-64（linux/x64）	@witness-ai/opencode-linux-x64

npm 发行版不支持 macOS Intel、Linux ARM 和 Windows。每个二进制文件都作为可选平台包发布，因此 npm 只会安装适用于当前计算机的二进制文件。

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@witness-ai/opencode"]
}

要测试当前的预发布版本且不替换 latest，请固定插件条目：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@witness-ai/opencode@beta"]
}

可选：如果还想在 Shell 的 PATH 中使用 witness 命令，请全局安装：

npm install -g @witness-ai/opencode

可选：无需全局安装，按需运行：

npm exec --yes --package=@witness-ai/opencode -- witness doctor

主 npm 包包含插件、CLI 封装器和提示词；对应的可选平台包 包含一个二进制文件。首次下载嵌入模型约为 470MB。安装这些包不会 启动下载：插件会在 OpenCode 下次运行时启动下载。首次下载完成前，请保持 OpenCode 运行。 插件负责下载，关闭时会停止下载器，并在之后以有限退避策略重试。 如果你已有自己的 mcp.witness 配置，插件会保持不变。npm 封装器不 支持 witness wire / witness unwire；这些命令用于从源码检出版本进行编辑器接线。 自定义模型镜像必须在 WITNESS_MODEL_BASE_URL 之外提供 WITNESS_MODEL_SHA256 和 WITNESS_TOKENIZER_SHA256。

首次下载完成后，请验证模型、OpenCode 运行器、归档和队列：

npm exec --yes --package=@witness-ai/opencode@beta -- witness doctor
npm exec --yes --package=@witness-ai/opencode@beta -- witness status

升级说明： 较旧版本的 witness 在蒸馏被中断时，可能会留下一个 Agent 或标题为 witness-distill 的 OpenCode 会话。当前版本不再在 OpenCode 的用户数据库中创建或筛选 这些会话。升级后首次导入前，请使用 OpenCode 支持的会话管理工具移除所有 残留的 witness-distill 会话，以免将其作为正常归档数据捕获。

npm 包位于 npm/opencode。发布前，请暂存预构建二进制文件和提示词：

make npm-opencode-package
npm publish ./npm/platform/darwin-arm64 --access public --tag beta
npm publish ./npm/platform/linux-x64 --access public --tag beta
(cd npm/opencode && npm publish --access public --ignore-scripts --tag beta)

使用发布工作流前，请分别为主包和两个平台包配置 npm Trusted Publishing。npm 包页面会显示 npm/opencode/README.md；工作流会在发布后验证 npm 是否将其识别为包 README，以及已发布的 tarball 是否包含该文件。

仅在首次发布平台包时，请在创建 GitHub Release 前手动发布两个平台包，然后在 npm 上配置其 Trusted Publishers。npm 要求包必须先存在， 才能为其配置包级 Trusted Publisher。发布工作流具有幂等性：如果某个包版本已发布，则跳过；先发布所有缺失的平台版本，再发布主包。

手动验证路径：

witness lens register math prompts/lens/example   # optional: register an extra lens
witness lens enable math
witness import --agent opencode    # reconciles ~/.local/share/opencode/opencode.db and returns
witness status                    # watch non-blocking distillation progress
witness worker review              # forces L2 facets + L4 markdown profiles (hidden cmd)
witness profile opencode           # per-lens L4 report
witness profile                    # unified L4 report

配置

~/.local/share/witness/config.toml（均为可选；默认值合理）：

runner           = "claude"   # "claude" (default) or "opencode"
triage_model     = ""         # MINING (L0 -> L1), once per session; "" = the runner's default
distill_model    = ""         # REVIEW (L1 -> L2/L4), batched; "" falls back to triage_model
review_every     = 5          # run the reviewer every N distilled sessions...
review_poignancy = 30         # ...or sooner once accumulated salience crosses this (0 = off)
auto_distill     = true       # hooks/plugins may start model work automatically
mine_concurrency = 4          # parallel per-session miners (<= 0 restores the default)

模型 ID 会传递给绑定的运行器，因此请使用相应运行时的写法—— 对于 runner = "claude"，使用 claude-haiku-4-5 或 claude-sonnet-5；对于 runner = "opencode"，使用 openai/gpt-5.5 这类 ID。将两者都留空是安全的默认设置，也是 witness install 写入的配置； 请注意，在 claude 运行器下，空的 triage_model 会继承你当前交互会话中使用的 模型，这个模型可能比你希望用于逐会话挖掘的模型更大，因此通常值得指定一个轻量模型。

在电量受限的机器上，将 auto_distill = false 设为仅捕获模式，然后在接通电源时手动运行 witness worker run --detach。自动工作进程的运行时间很短：它们只会在处理排队的会话时加载嵌入模型，随后退出。

当 runner = opencode 时，triage_model 和 distill_model 应使用 OpenCode 模型名称，例如 openai/gpt-5.5；空值则使用你的 OpenCode 默认值。蒸馏前会通过 opencode models <provider> 验证非空的 OpenCode 模型名称，而 witness doctor 会通过 opencode models: OK 或明确的无效模型错误报告相同的检查结果。

已启用的透镜由你通过 witness lens enable/disable <name> 管理，并以简单的行列出；每行对应一个已注册的透镜，它会在每个会话中运行：

lens = math

没有自动保留期限设置：原始转录会一直保留，直到你使用 witness cleanup 主动清理（该命令绝不会触及你的观察记录或个人资料）。

你的数据由你掌控

所有内容都存储在 ~/.local/share/witness/ 下（可通过 WITNESS_HOME 覆盖；重命名前的安装仍使用 ~/.local/share/claude-witness/，并会自动迁移），权限为 0700 （数据库和个人资料文件为 0600），且不会离开你的机器。此仓库包含框架、 架构和提示词——绝不包含任何人的档案。

故障排查。 蒸馏在分离的工作进程中运行，因此失败信息会写入 $WITNESS_HOME/witness.log（JSON 行），而不是显示在终端中。日志会记录工作进程的 启动步骤、每次挖掘的输入大小和耗时，以及每次模型调用的结果——足以判断是模型运行缓慢还是进程卡住。如需更多详情，可设置 WITNESS_LOG_LEVEL=debug（也接受 warn / error；任何无法识别的值都会回退到默认的 info，因此即便拼错，也绝不会导致 witness 停止捕获）。

备份 / 同步。 使用 witness export --all <dir>——它会写入一份完整档案，可将其交给同步工具处理。不要直接同步实时数据目录：数据库使用 WAL 模式（.db + -wal + -shm），同步工具若与这些文件的写入同时操作，可能会损坏数据库。你可以自行配置，例如使用 cron/launchd 作业：

witness export --all ~/Dropbox/witness-backup --force   # complete archive, safe to sync

--all 很重要，因为你的数据目录中的四项内容里，只有一项是数据库：

	包含在 --all 中	包含在普通 export 中	没有备份时能否恢复？
witness.db — 原始轮次、观察记录、特征	是	是	否
config.toml — 已启用的透镜、运行器、模型	是	否	手动重新配置；在此之前，蒸馏会静默关闭
lenses/ — 你的透镜定义	是	否	否 — 提示词文本不在任何数据库中。内置透镜会重新生成；你编写的透镜则会丢失
profile/ — 叙述文本	是	否	通过审核重建，但手动编辑过的 unified.md 除外

有意排除的内容：witness.log（诊断信息）、runtime/（OpenCode 的临时私有运行时） 以及锁文件。两种导出方式都可以在工作进程写入时安全运行——无需停止工作进程。

恢复无需单独的命令。 --all 目录与数据目录具有相同的布局，因此可以直接让 witness 使用该目录（WITNESS_HOME=~/Dropbox/witness-backup），也可以在停止 witness 后将其中的内容复制到数据目录。仅包含数据库的普通快照也可以像恢复 witness.db 一样恢复，而 witness worker review 会据此重建叙述文本。

许可证

MIT — 请参阅 LICENSE。