witness

# witness — 让 Claude Code 和 OpenCode 见证你的成长。 [](LICENSE) [](https://www.npmjs.com/package/@witness-ai/opencode)    **witness 是一个用于 Claude Code 和 OpenCode 的本地内存和自我改进引擎。** 它记录你的编码会话，并提炼出你的模式、习惯和知识如何**随着时间演变**—— 一个以人为中心的成长档案，带有出处，服务于 MCP 服务器和普通文件，作为单个纯 Go 二进制文件。 可以认为它是 *第二大脑 / AI 记忆*，用于思考和成长，而不是项目记忆，用于代码做了什么。 *(文件和 PDF 正在路上——参见路线图，以便同一个引擎也可以提炼出你的笔记和文档中知识的演变。)* > *"啊，你一直站在我身边。* > *我的真正导师...* > *我的指引月光..."* > — 路德维希，圣剑 一个 Claude Code / OpenCode 插件，悄悄地保持着 **一个关于你如何成长和改变的人性化档案**——你的思考方式、工作风格、习惯、你陷入和爬出的认知陷阱，以及所有这些如何随着时间而改变。 不是一个记录 *你的代码做了什么*（其他工具会记录项目记忆）——而是一个记录 **你正在成为什么人** 的档案。 它是 **面向教练，而不是克隆**：重点是让 Claude 了解你，并将你反馈给自己，并给你留下可读的记录，记录你如何思考和成长。 它是一个 **纯粹的工具**——它捕获、结构和提供档案（通过 MCP 服务器和普通文件）。 在它之上构建一个 *教练*（主动反思，“你已经这样做了三次……”） 留给其他项目读取其输出。 **内容：** [工作原理](#工作原理) · [镜头](#镜头) · [示例](#示例) · [阅读档案](#阅读档案) · [命令](#命令) · [安装](#安装) · [配置](#配置) · [您的数据](#您的数据是您的) ## 工作原理 四层 — 一个基本事实，三层可再生： | 层 | 类型 | 它是什么 | |-------|------|------------| | **原始（L0）** | 基本事实 | 每个环节都被原样捕获——来自稳定的 Claude Code 钩子字段（`UserPromptSubmit.prompt`，`Stop.last_assistant_message`）或 OpenCode 的本地 SQLite 会话数据库（`message`/`part` 文本）。 仅追加，永不 LLM 触及。 | | **观察（L1）** | 派生 | 一个廉价的每会话工作程序挖掘关于 *你* 的原子、证据锚定观察，并按镜头标记。 仅追加。 | | **方面（L2）** | 派生、双时间 | 定期审查员将观察结果综合成不断演变的 *方面*，每个方面都保持其 **变更历史**（`valid_from`/`valid_to`）——因此档案可以回答“我是如何改变的”，而不只是“我现在是谁”。 旧值永不删除。 | | **配置文件（L4）** | 派生叙事 | 从方面中提取的简短、人类可读的 Markdown 摘要，在每次审查后重新生成：每个镜头一个，加上跨镜头的统一肖像。 | 档案是 **仅收集 / 拉取**：witness 在任何地方捕获和提炼，但从不将任何内容注入会话。 没有被推送 — 您（或代理）按需读取配置文件。 原始/观察/方面存放在单个嵌入式 SQLite 数据库（`witness.db`）中；配置文件是 `profile/` 下的纯 Markdown。 ### 镜头 每个观察/方面都带有 **镜头** 标签： - **`默认`** — 全局，在每个会话上运行，跨领域。 这是任何单一领域跟踪器都无法实现的：它看到“精确诊断差距”在数学 *和* 编码 *和* 职业中触发。 - **已注册的镜头**（例如 `math`）— 领域特定的镜头，您 **一次性注册** 并 **全局启用**。 `witness lens register math ./math-lens.md` 将定义添加到中央注册表；`witness lens enable math` 使其在每个会话上运行（与 `默认`一起）。 镜头是共享的，不绑定到任何存储库，因此相同的 `math` 镜头涵盖了您所有的数学工作。 - **`opencode` 示例镜头** — [`prompts/lens/opencode.md`](prompts/lens/opencode.md) 观察代理协作工作流：工具纪律、验证、上下文管理和自主校准。 #### 编写镜头 镜头是一个带有两个提示的小 Markdown 文件： **`## EXTRACT`** （每个会话 — 挖掘观察）和 **`## REVIEW`** （定期 — 将它们综合成方面），以及一个可选的 `name`/`dimensions` 头部： ```markdown # 名称：数学 # 维度：速度、独立性、证明严谨性、抽象性、混淆容忍度 ## EXTRACT 您正在通过数学学习镜头观察一个会话。 注意这个人作为数学家的特征 — 他们如何推理、陷入困境以及如何摆脱困境… … 仅返回 JSON 数组。 每个元素： [{ "维度": "证明严谨性", "观察": "…", "证据": "…", " poignant": 6 }] ## REVIEW 您是数学镜头的审查员… 将观察结果综合成几个尖锐、可以证伪的方面；仅标记持续变化… 仅返回 JSON 数组。 每个元素： [{ "维度": "…", "键": "…", "值": "…", "置信度": 0.7, "因为": ["obs_…"], "与先前相矛盾": false }] ``` 请记住一个规则：每个部分 **原样用于系统**，并 *替换* 内置的 `默认` 提示 — 它不扩展它们 — 因此每个部分都必须 **自包含，包括其输出 JSON 模式**（工具附加转录/观察结果作为用户消息，但不为你注入模式）。 一个 **完整、可直接复制的** 镜头位于 [`prompts/lens/example.md`](prompts/lens/example.md) — 最快的开始方法是复制它并为您的领域重写维度 和 文本： ```sh cp "$CLAUDE_PLUGIN_ROOT/prompts/lens/example.md" ./math-lens.md # 编辑它，然后： witness lens register math ./math-lens.md # 将定义复制到您的存储中（快照） witness lens enable math # 开始在每个会话上运行它 ``` `register` 存储一个 **副本** — 以后编辑原始文件不会产生影响，直到您重新注册。 `enable` 是一个单独的开关，使其实际运行。 源文件可以位于任何位置。 作为推荐的规范位置，witness 将已注册的副本保存在 `<witness-data-dir>/lenses/<name>/lens.md` 下（通常 `~/.local/share/witness/lenses/<name>/lens.md`，或 `$WITNESS_HOME/lenses/<name>/lens.md`）。 您可以直接编辑已注册的副本，但此位置是一个约定，而不是对传递给 `lens register` 的文件的限制。 ## 示例：一个时刻，端到端 假设一个会话包含以下交换（虚构）： > **您：** 迁移在生产环境中一直失败，但在本地通过 — 我就手动运行一下，然后继续 > > **您：** …等一下，生产环境中到底 **有什么不同**？ 在我修改任何内容之前，让我先对比两个模式。 以下是每一层的内容。 **原始（L0）** — 原样捕获，什么也不解释： ``` 用户 迁移在生产环境中一直失败，但在本地通过 — 我就手动运行一下，然后继续 用户 等一下，生产环境中到底有什么不同？ 在我修改任何内容之前，让我先对比两个模式。 ``` **观察（L1）** — 工作器挖掘一个原子、证据锚定的观察： ``` [思考] 抓住了绕过失败的冲动，并转向隔离生产环境/本地差异后再采取行动。 证据： “手动运行并继续” → “有什么不同？ 在我修改之前先进行差异对比” 深刻性： 6 镜头： 默认 ``` **方面（L2）** — 在几个这样的时刻之后，审查员综合出一个不断演变的属性，并 **保持历史记录**（重点 — 它显示 **变化**，而不仅仅是当前状态）： ``` 默认 · 思考 · 诊断前行动 置信度 0.82 2026-05 → 现在 抓住了绕过失败的冲动，并隔离了机制； 在行动前需要了解原因。 2026-02 → 2026-05 倾向于应用第一个补丁来解决任务。 （已过时） ``` **配置文件（L4）** — 您实际阅读的叙述（`witness profile`）： > ## 默认 > > 您一直在趋同于一种先诊断的 工作方式。 几个月前，模式是达到解决任务的第一个补丁； 现在您经常抓住这个冲动，转而隔离机制，然后再采取行动… 这里的任何内容都 **不会被推送到您的会话中** — 您在需要时阅读它（`witness profile`），或代理按需拉取相关方面。 ## 阅读档案 人类阅读 **叙述**； 代理阅读 **结构化** 数据。 通过 MCP： - `get_profile(lens)` — 叙述配置文件（散文）； 省略 `lens` 以获取统一的肖像。 - `get_facets(lens)` — 当前结构化方面。 - `search_observations(query, lens)` — 观察的本地向量搜索。 - `record_observation(...)` — 会话代理直接写入决策感知观察（原样传递），捕获后期审查员会错过的上下文。 - `delete_observation(obs_id)` — 清除错误的观察。 ## 命令 `witness <doctor | profile | facets | observations | review | lens | import | distill | cleanup | export | install | uninstall>` （捕获、 worker 和 MCP 服务器是 Claude Code/OpenCode 调用的内部入口点，不需要手动输入）： - `witness profile [lens]` — 打印叙述配置文件（默认：统一肖像）。 - `witness facets [lens]` — 打印当前结构化方面（CLI 等效于 MCP `get_facets`）。 - `witness observations search <query> [--lens <lens>] [-k N]` — 观察的语义搜索。 - `witness observations record --session <id> --dimension <name> --observation <text>` — 暂存主动观察并启动 worker。 - `witness observations delete <obs_id>` — 清除错误的观察。 - `witness review` — 强制执行 L2 审查，并从现有观察中重新生成 L4 配置文件。 - `witness lens register|enable|disable|list` — 管理镜头。 - `witness import --agent opencode` — 渐进地将 OpenCode 的本地会话数据库调和到 L0 并启动后台蒸馏，无需等待。 - `witness import --agent claude` — 为已捕获的 Claude Code 钩子数据启动蒸馏。 - `witness distill start|status|stop` — 管理后台蒸馏 worker。 手动启动接受 `--since`/`--until` 以按最新原始时间戳选择待处理会话； 例如， `witness distill start --since 7d` 蒸馏最近七天内更新的会话。 界限也接受 RFC3339 时间戳或 UTC 日期（`YYYY-MM-DD`）并且不丢弃会话范围外的会话。 - `witness cleanup` — 交互式地回收旧原始转录（保留观察 + 配置文件）。 - `witness export <path>` — 编写档案的一致性单文件快照（安全备份/云同步）。 - `witness doctor` — 健康检查（验证嵌入器运行和 EN/ZH 检索工作）。 ## 单二进制文件，无运行时 整个东西是一个 **自包含的 Go 二进制文件** — 没有 Python，没有外部服务，没有向量 DB，没有云密钥。 本地多语言（英语 **和** 中文）嵌入式通过 GoMLX 运行纯 Go（`CGO_ENABLED=0`，已验证：与 ONNX Runtime 完全匹配）。 蒸馏默认使用 `claude -p` 进行身份验证； 设置 `runner = opencode` 以使用私有 `opencode serve` 运行器代替。 ## 安装 ```sh ./install.sh claude # Claude Code： 构建、获取模型（~448MB 一次）、连接钩子 + MCP ./install.sh opencode # OpenCode： 构建、获取模型、安装本地插件 + MCP ``` 就是这样 — 幂等，安全地在 `git pull` 后重新运行。 目标是必需的； 安装始终将匹配的蒸馏运行时绑定到 `config.toml`（`runner = claude` 或 `runner = opencode`）。 它还提供将 `witness` 命令添加到您的 PATH（用于 `witness profile`、`doctor`、`lens`、`import`、`distill`、`cleanup`）。 存在等效的 `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.exe` 和嵌入式模型的 `witness\` 文件夹。 然后，从 PowerShell 中的该文件夹内部： ```powershell .\witness.exe install claude ``` 这将包复制到 `%LOCALAPPDATA%\witness`，将其添加到您的用户 PATH，并使用 **exec-form 钩子** 将 Claude Code 连接到 `witness.exe`（无需 shell，无需 Git Bash）。 zip 携带提示模板和 ~448MB 模型以及 exe； 二进制文件相对于自身解析两者。 卸载会剥离钩子 + MCP（`witness.exe uninstall claude`）； 复制的文件和 PATH 条目现在保留。 ### OpenCode 支持 OpenCode 支持有两个部分： - 插件在启动时和会话空闲时协调 OpenCode 的 SQLite 数据库，然后在允许时请求笔记本友好型自动启动门控进行蒸馏。 从源代码安装会将本地插件写入 `~/.config/opencode/plugins/witness.js`； 已发布的安装可以使用 npm 插件 `@witness-ai/opencode`。 - 命名为 `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 分发支持以下平台： | 操作系统 | 架构 | npm 平台包 | | --- | --- | --- | | macOS | Apple Silicon (`darwin/arm64`) | `@witness-ai/opencode-darwin-arm64` | | Linux | x86-64 (`linux/x64`) | `@witness-ai/opencode-linux-x64` | macOS Intel、Linux ARM 和 Windows 不受 npm 分发支持。 每个二进制文件都作为可选的平台包发布，因此 npm 只安装当前机器的二进制文件。 ```json { "$schema": "https://opencode.ai/config.json", "plugin": ["@witness-ai/opencode"] } ``` 要测试当前预发布版本而不替换 `latest`，请固定插件条目： ```json { "$schema": "https://opencode.ai/config.json", "plugin": ["@witness-ai/opencode@beta"] } ``` 可选：全局安装它，如果您还希望在 shell `PATH` 上使用 `witness` 命令： ```sh npm install -g @witness-ai/opencode ``` 可选：无需全局安装即可临时运行： ```sh npm exec --yes --package=@witness-ai/opencode -- witness doctor ``` 主 npm 包包含插件、CLI 包装器和提示； 匹配的平台包包含一个二进制文件。 第一次嵌入式模型下载约为 470MB。 安装包不会启动下载：插件在 OpenCode 下次运行时启动它。 插件拥有下载器，在关闭时停止它，并在以后以有限的回退重试。 如果您已经拥有自己的 `mcp.witness` 配置，插件将保持不变。 npm 包装器不支持 `witness install` / `witness uninstall`；这些命令适用于源代码检出安装。 自定义模型镜像必须提供 `WITNESS_MODEL_SHA256` 和 `WITNESS_TOKENIZER_SHA256`，以及 `WITNESS_MODEL_BASE_URL`。 在第一次下载后，请验证模型、OpenCode 运行器、存档和队列： ```sh npm exec --yes --package=@witness-ai/opencode@beta -- witness doctor npm exec --yes --package=@witness-ai/opencode@beta -- witness distill status ``` npm 包位于 [`npm/opencode`](npm/opencode)。 在发布之前准备预构建的二进制文件和提示： ```sh 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 是否将它识别为包 README，并且发布的 tarball 包含它。 对于仅限于第一个平台包的发布，请在创建 GitHub Release 之前手动发布这两个平台包，然后配置它们的 Trusted Publishers on npm。 发布工作流是幂等的：如果已经发布了包版本，则会跳过它，首先发布任何缺失的平台版本，然后发布主包。 手动验证路径： ```sh witness lens register opencode prompts/lens/opencode.md witness lens enable opencode witness import --agent opencode # 将 ~/.local/share/opencode/opencode.db 调和到 L0 并返回 witness distill status # 监视非阻塞蒸馏进度 witness review # 强制执行 L2 方面 + L4 Markdown 配置文件 witness profile opencode # 每镜头 L4 报告 witness profile # 统一 L4 报告 ``` ## 配置 `~/.local/share/witness/config.toml`（所有配置项均为可选，默认配置合理）： ```toml runner = "claude" # "claude"（默认）或 "opencode" triage_model = "claude-haiku-4-5" # 经济实惠的每会话挖掘（"" = claude -p 默认） distill_model = "claude-opus-4-8" # 审查者（"" = claude -p 默认） review_every = 5 # 每 N 次蒸馏会话运行审查者... review_poignancy = 30 # ...或在累积显著性超过此阈值时提前（0 = 关闭） auto_distill = true # 钩子/插件可以自动启动模型工作 auto_distill_interval_minutes = 10 # 自动工作线程启动之间的最小间隔 auto_distill_session_budget = 0 # 每次自动运行的会话数（0 = 清空当前队列） ``` 在电池供电的设备上设置为 `auto_distill = false` 以进入仅捕获模式，然后在插入电源时手动运行 `witness distill start`。自动工作线程是短暂的：它们只在排空队列会话时加载嵌入模型，然后退出。 当 `runner = opencode` 时，`triage_model` 和 `distill_model` 应使用 OpenCode 模型名称，例如 `openai/gpt-5.5`；空值使用您的 OpenCode 默认值。非空 OpenCode 模型名称在蒸馏前会针对 `opencode models <provider>` 进行验证，`witness doctor` 会报告与 `opencode models: OK` 相同的检查结果或显式的无效模型错误。 已启用的镜头由系统管理（`witness lens enable/disable <name>`），并以简单的行形式出现，每行命名一个在每个会话上运行的已注册镜头： ```toml lens = math ``` 没有自动保留控制：原始转录稿将保留，直到您使用 `witness cleanup`（它不会触及您的观察或配置文件）显式回收它们。 ## 您的数据属于您 所有数据都存放在 `~/.local/share/witness/` 下（可以通过 `WITNESS_HOME` 环境变量覆盖；早期版本会继续使用 `~/.local/share/claude-witness/`，并自动采用新路径），权限设置为 `0700`（数据库和配置文件权限为 `0600`），并且永远不会离开您的机器。存储库中包含框架、模式和提示 — **绝不会包含任何人的存档**。 **备份/同步。** 要备份存档或同步（iCloud/Dropbox/Drive），请使用 `witness export <path>` — 它会生成一个一致的 `.db` 快照，您可以将该快照指向同步工具。**不要** 直接同步活动数据目录：数据库在 WAL 模式（`.db` + `-wal` + `-shm`）下运行，而同步工具竞争这些文件可能会损坏数据库。您可以自己配置，例如设置 cron/launchd 作业： ```sh witness export ~/Dropbox/witness-backup.db --force # 一致的快照，可以安全同步 ``` 要恢复，请停止 witness 并将快照复制到数据目录中，作为 `witness.db`（或将 `WITNESS_HOME` 设置为其文件夹），然后运行 `witness review` — 快照保留了源真相（原始回合、观察、方面）；叙事配置文件将从中重新生成。 ## 许可证 MIT — 请参阅 [LICENSE](LICENSE)。