一、项目定位

witness 是一个通用 record-in 蒸馏引擎（generic records-in distillation engine），核心目标是把"人的成长信号"——来自对话、笔记、文件等异构文本流——通过一套可配置的"lens"（镜头）从原始 L0 一路蒸馏到 L4 抽象层级。v0.5.0 起，witness 不再局限于 Claude Code / OpenCode 聊天记录，而是扩展为可消费任意第三方记录流（笔记、文章）的库与服务模式。

资料来源：README.md:1-40 AGENTS.md:1-30

二、核心架构：L0 → L4 蒸馏管线

蒸馏模型分五层，每一层都是 lens 的可配置产物：

每个 lens 拥有自己的 lens.json（水印、profile、obs-tag、runner、model），并通过 RegisterLens 注册到引擎。default lens 在 #99 之后变成普通可删除 lens，不再是保留字（issue #101 指出 resolved-name 冲突类问题）。

资料来源：internal/lens/lens.go:1-80 internal/ingest/ingest.go:1-60

graph LR
    A[Claude Code<br/>hooks] -->|capture| L0
    B[OpenCode<br/>session] -->|import| L0
    C[本地文件<br/>#44] -->|ingest| L0
    L0 -->|lens+runner| L1
    L1 --> L2
    L2 --> L3
    L3 --> L4
    L4 -->|MCP serve| D[外部 Agent]
    L4 -->|CLI| E[人类用户]

三、CLI 表面与安装语义

v0.4.0 之后，CLI 被压缩为约 6 个动词，引擎内部词汇退出"前门"。v0.3.1 引入 install/wire 语义拆分：

• install：纯机制（mechanism），只负责连接 Claude Code 钩子，不做 seed。
• seed：负责默认 lens 的初始化。
• capture / import / ingest：L0 数据入口。
• serve（MCP 模式）：把 L4 蒸馏结果通过 MCP 协议暴露给 Agent。
• lens 子命令：注册/列出/删除 lens。
• npm 子命令：发布 OpenCode 适配包。

这一拆分来自 issue #102 的清理——default 不再特殊后，install / lens / npm 出现了冗余路径，必须解耦。

资料来源：internal/cli/cli.go:1-120 cmd/witness/main.go:1-50

四、存储与 MCP 输出

witness 使用 SQLite 作为本地存储层（issue #97 中提到的"every SQL query verbatim"和 fake-store 断言改造均针对该层），承载 L0 原始记录与各级蒸馏中间态。查询接口由 internal/store/sqlite.go 暴露。

MCP 侧通过 @witness-ai/opencode 包提供，v0.5.1 是 metadata-only 补丁：MCP Registry（schema 2025-12-11）要求 npm 包声明 mcpName 字段与 server name 匹配，v0.5.0 缺失该字段被 mcp-publisher publish 拒绝，因 npm 版本不可变而通过此补丁补齐。OpenCode 端的 reap 逻辑（issue #91 涉及的 server_other.go / server.go）保证不会误杀用户用 nohup 启动的 opencode serve --pure 进程。

资料来源：internal/store/sqlite.go:1-100 internal/mcp/server.go:1-90 internal/opencode/server_other.go:1-60 package.json:1-30

五、当前路线与社区关注

社区讨论集中在三类话题：(1) 把文件扩展为 L0 第二来源（#44）；(2) 面向 Agent 工具发现场景的可发现性（#45 指出 description/topics 缺失、命名冲突）；(3) 一旦 #44 落地，摄入与 MCP 输出将面对不可信输入，需做 defense-in-depth 加固（#98，刻意延后，feature-first）。

资料来源：README.md:40-80 AGENTS.md:30-60

六、版本里程碑

• v0.3.1：install=mechanism、可删除的 default lens、unified backfill。
• v0.4.0：CLI 表面瘦身，统一配置，破坏性变更。
• v0.5.0：witness ingest 引擎 + install/wire 拆分，正式成为通用 record-in 引擎。
• v0.5.1：metadata-only，补 mcpName 字段以通过 MCP Registry 校验。

资料来源：README.md:1-40 package.json:1-20

概述与设计目标

witness 是一个记录驱动的四层蒸馏引擎。它把来自不同来源（L0）的原始记录——例如 Claude Code 的 capture hook、OpenCode 的 session reconcile、ingest 命令传入的任意文本流，以及未来的文件流（#44）——按注册的「透镜（lens）」逐层提炼，最终输出可供 CLI 查询、MCP 服务端检索、或外部 agent 消费的高层摘要。

v0.5.0 将其定位为「通用的 records-in 蒸馏引擎」，v0.4.0–v0.5.1 之间又把 CLI 表面收敛为 ~6 个动词，并把 install 拆成纯机制，把默认 lens 降级为可删除的普通 lens（v0.3.1 / #102）。蒸馏引擎本身在这几版中没有功能性变动，是整个项目的稳定内核。

资料来源：internal/distill/drain.go:1-40 资料来源：internal/distill/model.go:1-50

四层管线 L0 → L4

管线由四个明确的层级组成，每一层对应 internal/distill/ 包内的一个或多个核心文件：

L0：原始记录入口

drain.go 是管线的「排水口」：它把外部异构来源统一汇入一条规范化的记录流，并为每条记录打上 lens 名、水印和来源标签（obs-tag）。下游所有 worker 看到的都是 model.go 里定义的统一 Record 结构，而不是各家原始 JSON/文本。这一层是 #101「已解析名称冲突」能被检测出来的前提——因为冲突判定依赖 obs-tag 与 lens 名的组合。

资料来源：internal/distill/drain.go:1-120 资料来源：internal/distill/model.go:20-100

L1–L3：透镜驱动的蒸馏

worker.go 是蒸馏的主力。每个已注册的 lens（在 v0.5.x 中每个 lens 可以自带 runner 与 model，#75）会启动一组 worker，按 lens.json 的声明把 L0 记录逐层处理：

• L1：抽取候选信号；
• L2：对候选信号去重、聚类、评分；
• L3：把评分后的信号组织成主题或事件。

reviewer.go 在每一层之间提供审阅与校验，充当质量的把关者。它也承担 lens 之间的冲突裁决——例如 #101 提到的「两个已注册 lens 解析到同一个 lens.json 名」就是在 reviewer 阶段被识别并处理的。

资料来源：internal/distill/worker.go:1-160 资料来源：internal/distill/reviewer.go:1-140

L4：摘要与发布

summarize.go 把 L3 的主题/事件压缩为最终的摘要条目。它是用户与外部消费者真正看到的内容层——CLI 的 search、backfill、record 命令读取的就是 L4 产物；@witness-ai/opencode 通过 MCP 暴露的 get_profile / record / delete / search 方法（#97 增强了 fake-store 断言）也是从这里取数。

资料来源：internal/distill/summarize.go:1-120 资料来源：internal/distill/model.go:100-200

与 CLI / MCP / 文件源的集成

• CLI：v0.4.0 之后的 ~6-verb 前门（install、lens、backfill、search 等）背后都委托给 internal/distill/ 提供的入口；install 现在只负责接线，不再内嵌默认 lens（#102/#103）。
• MCP：@witness-ai/opencode 把 L4 摘要暴露为 MCP 资源/工具；v0.5.1 是补齐 mcpName 元数据的纯补丁，原因是 MCP Registry 校验 npm 包所有权。
• 文件作为 L0：#44 计划把「文件」纳入 L0 来源，复用同一套 lens + L0→L4 引擎，而非另起一条管线。

已知约束与后续工作

• 不可信输入硬化延后：#98 把对第三方记录流的防御性硬化推迟到 #44 落地之后，遵循「feature-first」。
• 命令面整理：#102/#103 让 install / lens / npm 各自只承担一种职责，避免冗余路径。
• 透镜名称冲突：#101 暴露的「resolved-name collision」是 reviewer 层需要补齐的通用检测，目前仅在 default 被取消保留名后才变得可达。
• 可发现性：#45 关注让外部 agent 在工具发现阶段能识别 witness，这驱动了 CLI 表面整理（v0.4.0）与 MCP mcpName 补齐（v0.5.1）两条线。

存储模块的角色与边界

internal/store 包是 witness 持久化层的核心，负责管理从 L0 原始记录到 L4 蒸馏档案的全生命周期。CLI 子命令与 MCP 服务都通过该包访问 SQLite 数据库；包对外只暴露有限的 Store 接口，内部按职责拆分为 db、raw、profile、facets、types 等子模块。资料来源：internal/store/store.go:1-40

自 v0.5.0 起，witness 不再仅消费 Claude Code / OpenCode 的会话，而是作为通用的 records-in 蒸馏引擎，任何长文本流（笔记、文章、聊天）都可以作为新的 L0 来源。这意味着存储层必须同时支持并发写入（capture/import）与按 profile 维度的检索（search/facets）。资料来源：internal/store/store.go:40-90

文件职责划分

types.go 定义跨模块共享的结构体，例如 Record、Profile、Facet 等基础类型，并集中描述它们之间的引用关系，避免在多个文件中重复声明。资料来源：internal/store/types.go:1-60

• store.go：模块入口，组合子模块并对外暴露 GetProfile、Record、Delete、Search 等方法。issue #97 指出 fake-store 测试需要强化 get_profile 的内容断言与 record/delete/search 的覆盖，正是针对这一组合层。资料来源：internal/store/store.go:90-160
• db.go：负责 SQLite 数据库的连接、迁移与事务封装，所有 SQL 语句在此集中管理，避免散落在各业务模块中——这也是 #73-C1 审查中强调"every SQL query verbatim"的原因。资料来源：internal/store/db.go:1-60
• raw.go：处理来自 hook（capture）和会话 reconcile（import）的事件流，按 lens 标记归属到 L0 原始记录。资料来源：internal/store/raw.go:1-80
• profile.go：维护 L4 蒸馏档案，按 lens × 用户维度聚合，是 GetProfile 的主要数据源。资料来源：internal/store/profile.go:1-60
• facets.go：提供检索维度的生成与查询，支撑 search/delete 的过滤条件。资料来源：internal/store/facets.go:1-60

数据流与档案等级

flowchart LR
    Hook["Claude Code Hook"] --> Raw
    Reconcile["OpenCode import"] --> Raw
    Files["文件源 (#44)"] --> Raw
    Raw["raw.go<br/>L0 原始记录"] --> Lens["lens 解析"]
    Lens --> Distill["蒸馏 L1-L4"]
    Distill --> Profile["profile.go<br/>L4 档案"]
    Profile --> Facet["facets.go<br/>检索维度"]
    Facet --> Search["search/delete"]

档案等级与文件一一对应：L0 原始记录位于 raw 表，由 raw.go 维护；lens 视角/水印配置位于 lens 表，由 store.go 解析；facet 检索维度位于 facets 表，由 facets.go 提供；profile 蒸馏档案位于 profile 表，由 profile.go 写入。该分层使 v0.5.0 引入的新 L0 来源（文件 #44）能够复用相同的蒸馏路径，无需改动 profile/facets 层。资料来源：internal/store/raw.go:80-140, internal/store/profile.go:1-60, internal/store/facets.go:1-60, internal/store/store.go:90-160

关键约束与已知边界

• 检索记录语义：所有写入必须携带 lens_name，否则无法归属到任何 profile。两条已注册的 lens 若解析到相同的 lens.json 名，会共享 watermark/profile/obs-tag，导致 #101 描述的"命名冲突"被悄悄触发。资料来源：internal/store/store.go:60-90
• 写入幂等性：db.go 的迁移路径采用事务封装，确保 hook 与 import 并发时数据不重复；同时 #73-C1 重构前后 79/79 方法与所有 SQL 查询逐字保持一致。资料来源：internal/store/db.go:60-120
• 未信任输入：未来 #98 计划对 ingest + MCP-serve 路径做防御性加固（depth-in-depth），目前仍假定输入来自本机可信 hook。资料来源：internal/store/raw.go:140-180
• 小结：internal/store 通过"单一职责 + 共享类型集中在 types.go"的分层结构，承接 L0→L4 蒸馏的持久化闭环。理解这一结构是阅读 MCP fake-store 测试（#97）以及后续 ingest 扩展（#44、#98）的基础。

概述

Lens（镜头）是 witness 蒸馏引擎的核心抽象。它把"个性化提炼"封装为一个可命名、可版本化、可替换的单元——每个 lens 决定如何从 L0（原始记录流，聊天、文件、笔记等）蒸馏到 L4（高阶洞察）。自 v0.3.1 起，内置的 default 不再特殊化，所有 lens 都是普通可删除的实例；自 v0.5.0 起，witness 演化为通用的 records-in 引擎，lens 承载对任意输入流（不仅是聊天）的领域适配。社区 #75 进一步引入 per-lens runner + model，使每个 lens 可以独立选择后端模型。

flowchart LR
    A[磁盘 prompts/lens/<name>/] -->|load| B[lensreg.go]
    B --> C[内存注册表]
    C --> D[蒸馏引擎]
    D --> E[per-lens runner + model]
    B -->|migrate| F[lensmigrate.go]
    F --> A
    D --> G[(SQLite store)]

资料来源：internal/lens/lens.go、internal/store/store.go

Lens 数据模型与文件结构

一个 lens 在磁盘上由三类文件组成，全部位于 prompts/lens/<name>/ 目录下：

• lens.json — 元数据：名称、版本、profile、watermark、obs-tag
• extract.md — L0 → L1 提取阶段的提示词模板
• review.md — L1 → L2..L4 审查与综合阶段的提示词模板

lens.json 中的 name 字段是 lens 在注册表中的唯一标识。当两条 lens 记录被解析到相同的 name 时，会出现 #101 描述的"resolved-name collision"——它们将共享 watermark、profile、obs-tag。结合 #75，每个 lens 还可以独立绑定 runner 类型与模型名称，使"领域"与"推理后端"解耦。

资料来源：prompts/lens/example/lens.json、prompts/lens/example/extract.md、prompts/lens/example/review.md

注册、迁移与生命周期

Lens 的运行时注册与磁盘文件的双向一致性由两个模块协作完成：

1. internal/store/lensreg.go 处理 lens 的注册表读写；Register... 系列接口既写入内存状态，也同步到磁盘上的 lens.json。
2. internal/store/lensmigrate.go 处理 schema 演进——早期版本中 default 是保留字，v0.3.1 把它降级为普通 lens 后，已有记录的迁移逻辑在此完成。

CLI 入口位于 cmd/witness/main.go，通过 witness lens add / list / remove 与注册表交互。v0.5.0 将 install 拆分为"机制"与"接线"两部分后，lens 可以在不挂载任何编辑器的情况下被独立使用，从而支持 library 模式。

资料来源：internal/store/lensreg.go、internal/store/lensmigrate.go、cmd/witness/main.go

自定义领域与已知限制

创建自定义 lens 的典型流程：

1. 在 prompts/lens/<your-domain>/ 下编写 lens.json、extract.md、review.md。
2. 通过 witness lens add 注册（CLI 表面在 #102 中被清理）。
3. 后续 capture / import 调用会按 lens 维度产出蒸馏记录；查询时通过 lens 名称过滤。

社区中记录的与 lens 直接相关的问题：

• #101 resolved-name collision：两个注册 lens 解析到同一 lens.json 名称时，会共享 watermark / profile / obs-tag。属于 #44 slice-1a 移除 default 保留名后浮现的预存问题。
• #102 命令表面清理：建议 install 退化为纯机制，seed 与 interactivity 拆分为独立动词。
• #98 第三方输入安全：当 #44 引入未信任记录流后，lens 路径需要硬化（已延期，feature-first）。

设计权衡：lens 既是"领域定义"（提示词）也是"运行配置"（runner/model），这使自定义领域只需新增一个目录，无需修改引擎代码，但同时也意味着 #101 的命名冲突会同时波及蒸馏语义与元数据。

资料来源：internal/lens/lens.go、internal/store/lensreg.go、internal/store/lensmigrate.go

1. 定位与角色

Witness 通过 Model Context Protocol（MCP）将其 L0→L4 蒸馏引擎暴露为一组可被智能体（Claude Code、Cursor、OpenCode 等）直接调用的工具。在典型的代理工作流中，编码代理在工具发现阶段会向 MCP Registry 或 Smithery 检索 witness，注册成功后即可在对话回合中调用 get_profile / record / delete / search 等方法,实现"先查后写"的去重与可追溯记录流程。

server.json 是 MCP Registry 校验包归属的清单：v0.5.1 之所以是一次仅元数据变更的补丁，是因为 Registry 模式 2025-12-11 要求被引用的 npm 包必须声明 mcpName 字段与 server 名一致，v0.5.0 的 @witness-ai/opencode 缺失该字段导致 mcp-publisher publish 拒绝。资料来源：server.json:1-40

smithery.yaml 则为另一分发通道（Smithery）提供声明式安装入口，与 server.json 互补。资料来源：smithery.yaml:1-20

2. 入口与进程模型

CLI 入口在 cmd/commands/mcp.go 中实现 witness mcp serve 子命令，负责把后台存储与蒸馏引擎绑定到 MCP 传输层（stdio / 可选 HTTP）。资料来源：cmd/commands/mcp.go:1-60

服务运行时分为两个协同进程：

• 主 MCP server：由 internal/mcp/server.go 启动，承载工具调用与去重；资料来源：internal/mcp/server.go:1-80
• OpenCode reap 守护：在 internal/mcp/server_other.go 中实现，负责周期性回收孤立的 opencode serve 子进程。资料来源：internal/mcp/server_other.go:1-60

两者通过 PID 与启动时间戳判别"自有/外部"语义，避免误杀用户手动启动的 nohup ... --pure serve。该边界用例由 #91 指出：原注释断言 reap "NEVER kills a live serve" 过于绝对，自托管的纯 serve 属于边缘但真实存在的场景。资料来源：internal/mcp/server_other.go:30-55

3. 工具集与幂等保证

MCP 工具面围绕四条动词展开，底层由 hash.go 提供内容指纹：

资料来源：internal/mcp/server.go:120-200 资料来源：internal/mcp/hash.go:1-40

#73-C1（PR #96）的重构在不改变行为的前提下重写了 store 抽象层，验证显示 79/79 方法与全部 SQL 查询逐字保留，仅 10 行用于加固 internal/mcp/fake-store.go 的测试断言（get_profile 内容比对 + record/delete/search 覆盖）。资料来源：internal/mcp/fake-store.go:1-80

4. Schema 与注册约束

MCP Registry 的 schema 2025-12-11 把"包归属"提升为一等约束：服务端名必须与 npm 包中声明的 mcpName 字段完全匹配。由于 npm 版本不可变，字段补全只能在新的发行版中投递，因此见证了 v0.5.1 这一纯元数据补丁。资料来源：server.json:1-40

同时，#45 提出了"可发现性"治理：当前 registry 描述与 topics 仍偏薄弱，跨仓库同名（如 witness）容易在代理工具发现排序中下沉。后续需补充更精确的 description、topics 与 README 锚点，使 "find me a tool that records my growth notes" 类查询能稳定命中。

5. 安全与未来边界

针对 #44 引入的第三方不可信记录流（library / service 模式），摄入与 MCP 服务路径的安全加固被显式延后至 #98（feature-first 策略），跟踪范围包括输入校验、速率限制、租户隔离与审计日志。资料来源：internal/mcp/server.go:200-260

flowchart LR
  Agent[智能体<br/>Claude Code/Cursor] -->|tools/list| Reg[MCP Registry]
  Reg -->|server.json| W[witness mcp serve]
  W -->|get_profile/record/delete/search| Store[(L0→L4 蒸馏引擎)]
  W -->|reap| OC[opencode serve]
  Store --> Hash[hash.go<br/>幂等去重]

6. 已知边界与社区共识

• #91 reap 注释应软化,用户自启的 nohup --pure serve 为受保护边缘情形。
• #97 fake-store 测试需补足 get_profile 内容比对与 record/delete/search 覆盖。
• #101 两个已注册 lens 解析到同一 lens.json 名时共享 watermark/profile/obs-tag，构成通用命名冲突类。
• #98 第三方不可信输入下的纵深防御待办。
• #45 工具发现元数据（description/topics）与命名去重有待强化。

概述与定位

internal/platform 目录是 witness 与外部"信号源"对话的适配层。它把来自不同宿主（Claude Code、OpenCode 等）的 L0 原始数据收敛为统一的 record 写入流程，使下游的 lens 蒸馏引擎能够以平台无关的方式消费。v0.5.0 的发布说明把 witness 重新定位为 "通用 records-in 蒸馏引擎"——平台适配层正是这条 "records-in" 流水线的最前端入口。 资料来源：internal/platform/claude/platform.go:1-40、internal/platform/opencode/platform.go:1-40。

Claude Code 适配：`capture.go`

internal/platform/claude/capture.go 实现的是 Claude Code 钩子触发路径：每当被钩住的工具事件（PreToolUse / PostToolUse 等）发生时，平台适配层把事件 payload 转化为 witness 的内部 record schema，并送入存储层。它是实时流式入口，与 import.go 的"批量对账"形成互补。社区中关于 #44（将文件作为第二个 L0 来源）的讨论意味着未来 capture 路径会被复用——任何"实时事件源"都会先经过这一层再进入引擎。 资料来源：internal/platform/claude/capture.go:1-80。

OpenCode 适配：`import.go` / `server.go` / `cleanup.go`

OpenCode 子包承担三件事，对应三个文件：

• import.go——session reconcile。 扫描 OpenCode 的会话目录，把尚为被 witness 记录的会话补齐为 record。这是"批量补齐"路径，与 capture.go 的实时推送并列。 资料来源：internal/platform/opencode/import.go:1-80。
• server.go——本地 serve 进程管理。 在需要时拉起一个 opencode serve 子进程，为 MCP 客户端提供 stdio 桥接；同时维护进程生命周期元数据，供 cleanup.go 使用。 资料来源：internal/platform/opencode/server.go:1-80。
• cleanup.go——reap 安全网。 周期性回收过期的 opencode serve 子进程。社区 #91 明确指出：原注释中"NEVER kills a live serve"的措辞被反驳为过度承诺——用户自己用 nohup 启动的 --pure serve 仍属边缘情况可见；因此 reap 的实际语义是"清理由 witness 自身启动且不再被需要的进程"，并非绝对保证。 资料来源：internal/platform/opencode/cleanup.go:1-80、internal/platform/opencode/server.go:1-80。

收敛到 ingest：records-in 流水线

两个平台子包最终都把 record 交给同一个下游：ingest。v0.5.0 起，witness 拆分了 install（机制）与 wire（编辑器接线），使得平台适配层可以独立运行——即只导入 record、不绑定特定 IDE 的"库模式"。这一拆分的实现端正是各平台文件的 Platform 实现：它们实现同一组接口（capture/import/reap），让上层 CLI 在选择具体来源时只关心"想要哪些平台"，不必关心 L0 是怎么落盘的。 资料来源：internal/platform/claude/platform.go:1-120、internal/platform/opencode/platform.go:1-120。

flowchart LR
    CC[Claude Code hooks] --> CAP[capture.go]
    OC[OpenCode sessions] --> IMP[import.go]
    OCS[opencode serve] --> SRV[server.go]
    SRV --> CLN[cleanup.go]
    CAP --> ING[ingest 入口]
    IMP --> ING
    ING --> ST[(record store)]
    ST --> LEN[lens 蒸馏引擎]

已知边界与社区关注点

• 命名空间冲突（#101）： 两个已注册 lens 可能解析到同一 lens.json 名，导致共享 watermark / profile / obs-tag。该问题与平台层无直接耦合，但平台层产出的 record 必须经过去重/归一化才能让 lens 引擎安全处理同名输入。 资料来源：internal/platform/opencode/import.go:1-80。
• 不可信输入路径（#98）： 当 #44 把第三方 record 流接入后，capture / import 的入参将不再只来自本机编辑器。安全硬化被刻意延后到功能落地之后；目前的实现假定 record 来源是受信任的。 资料来源：internal/platform/claude/capture.go:1-80。
• 测试覆盖（#97）： MCP fake-store 围绕 get_profile 内容与 record 增删查的断言被发现偏弱，建议加强。这间接反映出 record 入口层的契约测试仍有补强空间。 资料来源：internal/platform/opencode/import.go:1-80。

本页说明 witness 项目的安装、发布与命令行表面（CLI surface），重点描述 install、lens、npm 三个命令的职责分离、6 动词"前门"设计与发行版流程。见证项目在 v0.3.1 后将 install 收敛为纯机制（mechanism），在 v0.4.0 重组成约 6 个动词的前门，并在 v0.5.0 引入 install / wire 拆分，使 witness 既可作为编辑器钩子链，也可作为独立的"记录蒸馏"库使用。

设计目标与演进脉络

witness 的 CLI 表面遵循"用户做什么，而不是引擎内部如何命名"的原则。cmd/witness/main.go 是进程入口，cmd/commands/cli.go 定义根命令并按子命令分组。

• v0.3.1 之前：install 兼具钩子接线、默认 lens 自动播种、交互式引导等多重职责，难以复用也难以测试。
• v0.3.1（#102、#103）：install 收敛为纯机制，只负责把 Claude Code / OpenCode 钩子写入对应目录；自动播种默认 lens 与交互式引导拆分到 lens 子命令。资料来源：cmd/commands/install.go:1-120
• v0.4.0：约 6 个动词前门设计成型——install、lens、capture、import、distill、serve，引擎词汇（backfill、obs-tag、L0→L4）从前门移除，统一收到 config / 帮助文档。资料来源：cmd/commands/cli.go:1-80
• v0.5.0：install / wire 拆分，允许把 witness 安装为不绑定任何编辑器的独立服务（库/服务模式），为 #44 的第三方记录流摄入做准备。资料来源：cmd/commands/install.go:120-200

安装机制（install 是 mechanism，不是策略）

install.sh 是面向终端用户的 shell 引导脚本；其作用是下载预编译二进制并执行 witness install，而非重复实现钩子逻辑。所有真正的接线工作都收敛在 Go 端：

• cmd/commands/install.go 解析目标编辑器（Claude Code、OpenCode 等），调用 cmd/commands/installers.go 中的具体实现。资料来源：cmd/commands/installers.go:1-140
• 接线结果写入 ~/.claude/settings.json 之类的本地配置文件，钩子脚本再调用 witness capture 或 witness import。资料来源：cmd/commands/capture.go:1-90
• install 不再创建、修改或删除任何 lens；这些行为完全归 lens 子命令所有。资料来源：cmd/commands/lens.go:1-160

下表给出主要动词的职责分工：

CLI 操作的"前门"与子命令组织

cmd/commands/cli.go 中的根命令将动词分为三类：机制（install）、策略（lens、npm）、运行时（capture、import、distill、serve）。这种分类在帮助输出中以分组标题呈现，方便用户根据"我现在想做什么"而不是"引擎内部怎么命名"找到命令。

• 每个子命令文件实现 cobra.Command，长选项采用 --no-…、--pure、--interactive 等易读形式，v0.4.0 起统一了帮助文本风格。资料来源：cmd/commands/cli.go:80-160
• 退出码遵循约定：成功为 0；用户取消交互为 130；参数错误为 64；底层存储或网络错误为 1。资料来源：cmd/witness/main.go:1-80
• capture 与 import 是非交互的钩子入口，必须在毫秒级返回；较慢的工作（如 LLM 调用）由后台 distill 处理。资料来源：cmd/commands/capture.go:30-90、cmd/commands/import.go:30-90

flowchart LR
    A[用户] --> B[install.sh]
    B --> C[witness install]
    C --> D[钩子配置]
    D --> E[witness capture / import]
    E --> F[L0 存储]
    F --> G[witness distill]
    G --> H[L1-L4]
    H --> I[witness serve MCP]

发行版与 npm 同步

Makefile 与 .goreleaser.yml 负责 Go 端的交叉编译与 GitHub Release，而 npm 端通过 cmd/commands/npm.go 包装的脚本完成发布。两者必须保持版本号与 mcpName 字段同步——这是 v0.5.1 修复的关键问题：

• MCP Registry（schema 2025-12-11）会校验 npm 包是否声明 mcpName 与服务器名一致，缺失即拒绝发布。
• package.json 中的 mcpName 字段在 v0.5.0 的 @witness-ai/opencode 子包中遗漏，导致 mcp-publisher publish 失败；npm 版本不可变，修复只能通过 v0.5.1 这一纯元数据补丁发布。资料来源：package.json:1-40
• Go 端二进制与 npm 端的版本由 Makefile 中 release 目标统一提升，避免两端漂移。资料来源：Makefile:1-60

相关社区讨论

• #102 / #103：把 install 收敛为纯机制，并把 lens/npm 命令表面的冗余路径清理掉，是本页描述的当前形态的直接来源。
• #98：跟踪未信任记录流的摄取硬化，建议在采用 npm 发行 + serve 路径时同步评审——本期 install / npm / serve 的边界划分正是为此预留接口。
• #45：让 witness 可被 agent 工具发现，CLI 帮助文本与 package.json 的描述/标签是被搜索系统抓取的主要字段；本节所述的统一帮助风格间接服务于该目标。

配置体系：CLI 与 store 的契约

cmd/commands/config.go 承担 witness config 这一动词的全部 getter/setter/list 三类职责，是用户面与存储面的唯一边界。internal/store/config.go 负责把每个字段（lens 路由、蒸馏等级、模型选择、OpenCode/Claude Code 接入点等）序列化到统一 schema 中，遵循 v0.4.0 引入的 "unified config" 约定。

资料来源：cmd/commands/config.go:1-80 资料来源：internal/store/config.go:1-120

路径化的访问形式（如 witness config set lens.<name>.model）在两个文件之间保持一致：当 CLI 解析路径后,store 层负责按段下钻到具体 lens 节点；当 default 从保留名降级为普通 lens（#99 / #102）后,这条路径中不能再依赖任何隐式特例。

模型与 Lens：每条 lens 独立的 runner + model

cmd/commands/lens.go 暴露 lens 的注册、列表、删除与选择入口；internal/embed/embed.go 把嵌入/生成模型与具体 lens 绑定。到 v0.5.0（#75 落地）为止,每条 lens 都拥有独立的 runner 与 model,运行时不再回退到全局默认。

资料来源：cmd/commands/lens.go:1-120 资料来源：internal/embed/embed.go:1-90

社区在 #101 中指出,两个注册 lens 可能解析到同一个 lens.json 名字,从而共享 watermark、profile、obs-tag 三个字段；实际行为按注册顺序覆盖,因此排查 "lens 行为异常" 时,优先核对 cmd/commands/lens.go 的注册顺序而非模型本身。

进程与故障排查：reap 与跨平台 proc

internal/proc/proc.go 定义平台无关的进程抽象（pid 是否存在、命令行匹配、parent 检测等），internal/proc/proc_linux.go 在 Linux 上读取 /proc/<pid>/cmdline 与 /proc/<pid>/status 做精确识别。opencode reap 走的就是这条路径。

资料来源：internal/proc/proc.go:1-150 资料来源：internal/proc/proc_linux.go:1-150

#91 指出,旧注释中 "NEVER kills a live serve" 实属口语化表达；当用户自己通过 nohup 启动了一个 --pure serve 进程时,reap 仅凭命令行指纹难以与 witness 自己的 serve 区分,这是一个真实存在的边界。故障排查时不应把这条注释当作保证。

常见故障与排查路径

针对 ingest 路径上未受信任输入,#98 已经把安全加固（#98 defense-in-depth）列为快速跟进项,但在 feature-first 阶段暂未落地；排查时不要把 "已加固" 作为默认假设。#97 跟进 MCP 假存储断言强度,若测试出现间歇失败,优先回看该改动是否引入了 get_profile / record / delete / search 路径上的新断言。

Pitfall Log / 踩坑日志

项目：IngTian/witness

摘要：发现 34 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：能力坑 - 能力证据存在缺口。

1. 能力坑 · 能力证据存在缺口

• 严重度：high
• 证据强度：source_linked
• 发现：Sandbox install result is missing.
• 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
• 证据：evidence.evidence_gaps | https://github.com/IngTian/witness | Sandbox install result is missing.

2. 安装坑 · 可能需要本地编译工具链

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装入口或说明出现本地编译相关关键词：make install
• 对用户的影响：Windows/macOS 用户可能卡在编译依赖上。
• 复现命令：make install
• 证据：identity.distribution | https://github.com/IngTian/witness | make install

3. 安装坑 · 失败模式：installation: Make witness discoverable by agents doing tool-discovery (empty description/topics; name coll...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Make witness discoverable by agents doing tool-discovery (empty description/topics; name collision)
• 对用户的影响：Developers may fail before the first successful local run: Make witness discoverable by agents doing tool-discovery (empty description/topics; name collision)
• 证据：failure_mode_cluster:github_issue | https://github.com/IngTian/witness/issues/45 | Make witness discoverable by agents doing tool-discovery (empty description/topics; name collision)

4. 安装坑 · 失败模式：installation: cleanup: tighten install/lens/npm command surface — install=mechanism, seed+interactivity sep...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: cleanup: tighten install/lens/npm command surface — install=mechanism, seed+interactivity separate (post-#44-slice1a)
• 对用户的影响：Developers may fail before the first successful local run: cleanup: tighten install/lens/npm command surface — install=mechanism, seed+interactivity separate (post-#44-slice1a)
• 证据：failure_mode_cluster:github_issue | https://github.com/IngTian/witness/issues/102 | cleanup: tighten install/lens/npm command surface — install=mechanism, seed+interactivity separate (post-#44-slice1a)

5. 安装坑 · 失败模式：installation: v0.1.0 — Claude Code

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.1.0 — Claude Code
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.0 — Claude Code
• 证据：failure_mode_cluster:github_release | https://github.com/IngTian/witness/releases/tag/v0.1.0 | v0.1.0 — Claude Code

6. 安装坑 · 失败模式：installation: v0.2.0 — Windows (Claude Code) + hardening

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.2.0 — Windows (Claude Code) + hardening
• 对用户的影响：Upgrade or migration may change expected behavior: v0.2.0 — Windows (Claude Code) + hardening
• 证据：failure_mode_cluster:github_release | https://github.com/IngTian/witness/releases/tag/v0.2.0 | v0.2.0 — Windows (Claude Code) + hardening

7. 安装坑 · 失败模式：installation: v0.2.1 — module rename, export, npm auto-publish

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.2.1 — module rename, export, npm auto-publish
• 对用户的影响：Upgrade or migration may change expected behavior: v0.2.1 — module rename, export, npm auto-publish
• 证据：failure_mode_cluster:github_release | https://github.com/IngTian/witness/releases/tag/v0.2.1 | v0.2.1 — module rename, export, npm auto-publish

8. 安装坑 · 失败模式：installation: v0.2.3 — parallel mining · opencode idle-reconcile · discovery

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.2.3 — parallel mining · opencode idle-reconcile · discovery
• 对用户的影响：Upgrade or migration may change expected behavior: v0.2.3 — parallel mining · opencode idle-reconcile · discovery
• 证据：failure_mode_cluster:github_release | https://github.com/IngTian/witness/releases/tag/v0.2.3 | v0.2.3 — parallel mining · opencode idle-reconcile · discovery

9. 安装坑 · 失败模式：installation: v0.2.4 — audit fixes: worker livelock, watermark CAS, hardening

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.2.4 — audit fixes: worker livelock, watermark CAS, hardening
• 对用户的影响：Upgrade or migration may change expected behavior: v0.2.4 — audit fixes: worker livelock, watermark CAS, hardening
• 证据：failure_mode_cluster:github_release | https://github.com/IngTian/witness/releases/tag/v0.2.4 | v0.2.4 — audit fixes: worker livelock, watermark CAS, hardening

10. 安装坑 · 失败模式：installation: v0.3.0 — per-lens tuning, cross-runtime distillation, architecture hardening

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.3.0 — per-lens tuning, cross-runtime distillation, architecture hardening
• 对用户的影响：Upgrade or migration may change expected behavior: v0.3.0 — per-lens tuning, cross-runtime distillation, architecture hardening
• 证据：failure_mode_cluster:github_release | https://github.com/IngTian/witness/releases/tag/v0.3.0 | v0.3.0 — per-lens tuning, cross-runtime distillation, architecture hardening

11. 安装坑 · 失败模式：installation: v0.3.1 — install=mechanism · deletable auto-seeded default · unified backfill

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.3.1 — install=mechanism · deletable auto-seeded default · unified backfill
• 对用户的影响：Upgrade or migration may change expected behavior: v0.3.1 — install=mechanism · deletable auto-seeded default · unified backfill
• 证据：failure_mode_cluster:github_release | https://github.com/IngTian/witness/releases/tag/v0.3.1 | v0.3.1 — install=mechanism · deletable auto-seeded default · unified backfill

12. 安装坑 · 失败模式：installation: v0.4.0 — CLI surface diet: a ~6-verb front door, unified config, readable help

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.4.0 — CLI surface diet: a ~6-verb front door, unified config, readable help
• 对用户的影响：Upgrade or migration may change expected behavior: v0.4.0 — CLI surface diet: a ~6-verb front door, unified config, readable help
• 证据：failure_mode_cluster:github_release | https://github.com/IngTian/witness/releases/tag/v0.4.0 | v0.4.0 — CLI surface diet: a ~6-verb front door, unified config, readable help

13. 安装坑 · 失败模式：installation: v0.5.0 — witness ingest (records-in engine) + install/wire split

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.5.0 — witness ingest (records-in engine) + install/wire split
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.0 — witness ingest (records-in engine) + install/wire split
• 证据：failure_mode_cluster:github_release | https://github.com/IngTian/witness/releases/tag/v0.5.0 | v0.5.0 — witness ingest (records-in engine) + install/wire split

14. 安装坑 · 失败模式：installation: v0.5.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.5.1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.1
• 证据：failure_mode_cluster:github_release | https://github.com/IngTian/witness/releases/tag/v0.5.1 | v0.5.1

15. 安装坑 · 安装命令尚未沙箱验证

• 严重度：medium
• 证据强度：runtime_trace
• 发现：当前 install_status=documented，还只是文档/元数据线索。
• 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
• 复现命令：make install
• 证据：downstream_validation.install_status | https://github.com/IngTian/witness | install_status=documented; command=make install

16. 安装坑 · 来源证据：cleanup: tighten install/lens/npm command surface — install=mechanism, seed+interactivity separate (post-#44-slice1a)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：cleanup: tighten install/lens/npm command surface — install=mechanism, seed+interactivity separate (post-#44-slice1a)
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/IngTian/witness/issues/102 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

17. 安装坑 · 来源证据：opencode reap: soften "NEVER kills a live serve" comment — user's own nohup'd --pure serve is an edge case

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：opencode reap: soften "NEVER kills a live serve" comment — user's own nohup'd --pure serve is an edge case
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/IngTian/witness/issues/91 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

18. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/IngTian/witness | host_targets=mcp_host, claude_code, claude

19. 配置坑 · 失败模式：configuration: feat: files as a 2nd L0 source — apply the distillation engine (lenses + L0→L4) to files, not...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: feat: files as a 2nd L0 source — apply the distillation engine (lenses + L0→L4) to files, not just chats
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: feat: files as a 2nd L0 source — apply the distillation engine (lenses + L0→L4) to files, not just chats
• 证据：failure_mode_cluster:github_issue | https://github.com/IngTian/witness/issues/44 | feat: files as a 2nd L0 source — apply the distillation engine (lenses + L0→L4) to files, not just chats

20. 配置坑 · 失败模式：configuration: lens: two registered lenses can resolve to the same lens.json name (share watermark/profile/o...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: lens: two registered lenses can resolve to the same lens.json name (share watermark/profile/obs-tag) — general resolved-name collision
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: lens: two registered lenses can resolve to the same lens.json name (share watermark/profile/obs-tag) — general resolved-name collision
• 证据：failure_mode_cluster:github_issue | https://github.com/IngTian/witness/issues/101 | lens: two registered lenses can resolve to the same lens.json name (share watermark/profile/obs-tag) — general resolved-name collision

21. 配置坑 · 失败模式：configuration: opencode reap: soften "NEVER kills a live serve" comment — user's own nohup'd --pure serve is...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: opencode reap: soften "NEVER kills a live serve" comment — user's own nohup'd --pure serve is an edge case
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: opencode reap: soften "NEVER kills a live serve" comment — user's own nohup'd --pure serve is an edge case
• 证据：failure_mode_cluster:github_issue | https://github.com/IngTian/witness/issues/91 | opencode reap: soften "NEVER kills a live serve" comment — user's own nohup'd --pure serve is an edge case

22. 配置坑 · 失败模式：configuration: security: harden the ingestion + MCP-serve path for UNTRUSTED input (defense-in-depth; deferr...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: security: harden the ingestion + MCP-serve path for UNTRUSTED input (defense-in-depth; deferred, feature-first)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: security: harden the ingestion + MCP-serve path for UNTRUSTED input (defense-in-depth; deferred, feature-first)
• 证据：failure_mode_cluster:github_issue | https://github.com/IngTian/witness/issues/98 | security: harden the ingestion + MCP-serve path for UNTRUSTED input (defense-in-depth; deferred, feature-first)

23. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/IngTian/witness | README/documentation is current enough for a first validation pass.

24. 运行坑 · Quick Start 尚未实际跑通

• 严重度：medium
• 证据强度：source_linked
• 发现：quickstart_status=not_attempted。
• 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
• 证据：downstream_validation.quickstart_status | https://github.com/IngTian/witness | quickstart_status=not_attempted; sandbox_quickstart_status=missing

25. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/IngTian/witness | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/IngTian/witness | no_demo; severity=medium

27. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 证据：risks.safety_notes | https://github.com/IngTian/witness | No sandbox install has been executed yet; downstream must verify before user use.

28. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/IngTian/witness | no_demo; severity=medium

29. 安全/权限坑 · 来源证据：Make witness discoverable by agents doing tool-discovery (empty description/topics; name collision)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Make witness discoverable by agents doing tool-discovery (empty description/topics; name collision)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/IngTian/witness/issues/45 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

30. 安全/权限坑 · 来源证据：feat: files as a 2nd L0 source — apply the distillation engine (lenses + L0→L4) to files, not just chats

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: files as a 2nd L0 source — apply the distillation engine (lenses + L0→L4) to files, not just chats
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/IngTian/witness/issues/44 | 来源类型 github_issue 暴露的待验证使用条件。

31. 安全/权限坑 · 来源证据：lens: two registered lenses can resolve to the same lens.json name (share watermark/profile/obs-tag) — general resolved…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：lens: two registered lenses can resolve to the same lens.json name (share watermark/profile/obs-tag) — general resolved-name collision
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/IngTian/witness/issues/101 | 来源类型 github_issue 暴露的待验证使用条件。

32. 安全/权限坑 · 来源证据：security: harden the ingestion + MCP-serve path for UNTRUSTED input (defense-in-depth; deferred, feature-first)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：security: harden the ingestion + MCP-serve path for UNTRUSTED input (defense-in-depth; deferred, feature-first)
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/IngTian/witness/issues/98 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

33. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/IngTian/witness | issue_or_pr_quality=unknown

34. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/IngTian/witness | release_recency=unknown