前言¶

在 DeepSeek Harness（DSH）里做长程故障排查时，上下文压缩、换会话或切换任务很常见。对话摘要能留下几句「结论」，却容易丢掉证据链和适用条件：压缩后重复跑同一探针、直觉被写成「已证实」、换分支后仍套用旧 commit 下的判断，都是可复现的失败模式。工作日志记的是事件顺序，AGENTS.md 管的是流程规则，它们都不擅长单独承担「这条工程结论现在还信不信、在什么条件下信」。

下面介绍社区目录中的 Finding Ledger（dsh-finding-ledger，维护者 Aression）。它是 DSH 分类为「记忆」的插件：把排查中的发现（finding）连同证据、适用范围和状态演化写入本地 SQLite，并在新会话、压缩完成等时机按确定性规则与 token 预算注入上下文——不是堆满对话，而是只交回仍然相关且条件仍成立的结论。

这是什么¶

Finding Ledger 面向长程故障排查的证据化发现账本。核心资产包括仓库内的设计契约与可运行的 DSH 插件实现（package.json 版本 0.1.0，许可证 MIT）。README 明确区分：设计文档描述目标行为；某项能力是否已落地以代码与测试为准。仓库说明当前插件对应路线图 P0 已完成、P1 与 P2 主体完成。

与完整会话记忆或文档检索不同，它只持久化「当前还值得相信、以及在什么条件下值得相信」的工程发现：观察、诊断、约束、决策、步骤等，并绑定证据与三维度状态。

核心设计：三状态与证据¶

每条 finding 同时由三个正交维度描述，任意两个不能替代第三个：

设计上的几条硬约束值得写进排查习惯：supported 必须至少有一条支撑证据（服务层校验）；refuted 与 superseded 含义不同——被反证的路径通常仍保持 current，作为「已排除路径」注入，避免重复踩坑；条件不明时落到 unknown / needs_revalidation，不能静默当成适用。

证据是独立实体：evidence 记录来源（source_kind、source_ref、excerpt 等），finding_evidence 记录该来源对主张是 supports / contradicts / context。状态变更、反证、取代通过 finding_events 只追加审计，而不是静默覆盖。

核心功能：工具、存储与注入¶

十个业务工具¶

模型通过 Cordis 注册的工具操作账本，返回统一信封 { ok, data, warnings, error }：

另有一个只读诊断工具 ledger_status，用于排查「注入未出现」：账本路径、记录数、修订号、触发计数与最近一次注入结果。失败时返回稳定错误码（如 EVIDENCE_REQUIRED、INVALID_STATE_TRANSITION 等）。

技术栈与架构¶

运行时要求 Node.js ≥ 24（ESM），存储为单机 SQLite（Node 24 内置 node:sqlite，零原生编译依赖）。插件通过 cordis.patch.yml 作为 bundle patch 接入 DSH：apply(ctx, config) 注册工具并订阅会话事件。五层结构为工具接口 → 应用服务（状态机、事务）→ SQLite → 检索层 → 宿主适配（注入上下文）。

检索与注入¶

检索不用向量相似度决定「是否正确或适用」，首期是可解释的确定性规则：

1. 建立任务上下文（project_id、目标、branch/commit 等；缺失标 unknown）。
2. 硬过滤：项目隔离；排除 superseded / withdrawn / archived 与 retrieval_policy = never；保留 refuted 且 current 的记录（已排除路径）。
3. 适用性分类、排序、关系处理（如 contested 并列冲突方）。
4. 在 token 预算内格式化；状态字段不可被截断。

触发时机：新会话 / 项目初始化、上下文压缩完成后、显式查询、任务切换。宿主事件不可用时回退到显式查询，回退路径不注入未经确认的历史结论。

注入片段示例（格式来自 README，ID 与 run 编号仅为演示）：

## Finding Ledger：当前任务相关发现

### 当前有证据支持
- [F-123 | supported | applicable]
  结论：探针 A 的结果不支持 off-by-one 是主因。
  依据：实验 run-4472；shift -1/0/+1 的指标近似。
  范围：commit 0862527 / 配置 config-A。
  细节：get_finding F-123

### 已排除路径
- [F-081 | refuted | applicable]
  路径：当前条件下不必再优先排查 tokenizer shift。
  反证：4 个探针均未复现该假设（实验 run-4480）。
  注意：结论仅限上述版本与配置。

实现说明：agent/pre-step 装配点负责注入；新会话、resume、压缩完成与账本修订号变化会触发重新注入；异常时降级为不注入，不阻塞主任务。

安装与启用¶

DSH 生态采用「一切皆插件」思路；SkillHub 目录页是社区站点，与 DeepSeek / 幻方无官方从属关系。安装前请自行阅读仓库源码与 MIT 许可证——插件以当前 DSH 进程权限运行，能读写本地账本文件。

按仓库「快速开始」，步骤如下：

1. 环境：安装 Node.js 24 及以上。node:sqlite 为内置模块，无需单独装数据库或编译原生扩展。
2. 取得包目录：从 GitHub 发布或本地开发工作区获得 dsh-finding-ledger 包根目录（含 cordis.patch.yml 与 index.js）。
3. 作为 bundle 安装：使用宿主插件管理入口 plugin_manager install_bundle，target 指向该包目录；开发阶段也可用本地 link 挂载工作区。
4. 确认：插件加载后工具即注册；用一次显式 query_findings 确认可用。

README 写明：安装命令的具体参数、不同 profile 的差异以及事件名称与时序，以 DSH 插件管理文档为准；本文不复制命令输出，因其依赖宿主版本。

本地开发与自检（脚本以 package.json 为准）：

pnpm install
pnpm test
pnpm run check

pnpm test 对应 node --test test/*.test.js；pnpm run check 对入口与各 src/*.js 做 node --check 语法检查。

典型用法¶

长程排查中，可以把工作流理解为「记发现 → 挂证据 → 改状态 → 靠检索恢复连续性」：

1. 记录观察或假设：用 log_finding 写入 finding，设置 claim_kind（如 observation、diagnosis、constraint）与 retrieval_policy；无充分证据时认知状态保持 provisional，不要标成 supported。
2. 补证据：实验、日志、commit、代码阅读等通过 add_evidence 关联；要标 supported 时至少一条 supports 关系。
3. 排除或更新：路径走不通时用 refute_finding；分析被新版本取代时用 supersede_finding；换分支或后端后用 revalidate_finding 或把适用性落到 needs_revalidation。
4. 压缩或换会话后：依赖宿主在压缩完成等时机注入摘要；若未出现，用 ledger_status 查触发与最近结果，再用 query_findings / get_finding 按 ID 拉全量。
5. 规则沉淀（可选）：propose_rule 仅提议写入 AGENTS.md 类规则；首期不会自动修改任何项目文档，需人工审批。

工具参数契约见仓库文档「06 工具 API」；行为与状态机见「04 证据、认知状态与生命周期」「05 检索与上下文压缩恢复」。

适用场景与注意¶

适合：单次排查跨很多轮对话、需要保留「已排除路径」与带 scope 的结论、希望在压缩后少重复劳动的 DSH 用户。

不适合或首期不做（仓库明确排除）：完整会话存档、文档平台、未经评测的向量检索、自动把所有对话写入账本、未经批准改 AGENTS.md、仅凭记录年龄判过期、把模型自评当成证据升级。

安全与隐私：数据库默认落在用户可控本地位置；设计强调秘密过滤、项目隔离默认关闭跨项目检索、证据正文中的指令不得当作系统指令执行。存什么、如何脱敏见文档「07 安全、评测与路线图」。

实现边界：P3（评测闭环、embedding/reranker）仍在路线图；语义向量检索、证据自动升级与数值置信度不是首期依赖。Stars 与社区热度不代表成熟度，以你的宿主版本与本地测试为准。

结尾¶

Finding Ledger 把长程排查里可复用的部分从对话摘要里拆出来：证据、三状态、适用范围和审计事件进 SQLite，再在 DSH 会话关键节点按预算注入。若你在做 Harness 上的深度排障，值得对照设计契约看一遍状态机与注入规则，再决定是否以 bundle 方式装入当前环境。

• 社区目录：https://www.skillhub.cn/plugins/Aression/Finding-Ledger
• 源码与文档：https://github.com/Aression/Finding-Ledger