项目定位与目标

Reporecall 是一个面向 AI 编程代理（如 Claude、Cursor 等）的本地化代码库记忆与上下文检索中间件。它通过 Model Context Protocol（MCP）协议，将任意仓库的结构化信息、调用拓扑与人工维护的 Wiki 知识，暴露为一组精简的工具集，从而让代理在编码时能够"回忆"起模块职责、调用链路与历史决策。资料来源：README.md:1-40

项目以"信任契约"（trust contract）为核心设计原则：每一次返回给代理的上下文都附带新鲜度、来源提交哈希与证据强度，避免代理基于陈旧或推断内容作出错误修改。这一点在 v0.8.0 的破坏性变更中得到了强化。资料来源：README.md:41-72

核心子系统

Reporecall 的代码组织围绕四个相互协作的子系统展开：

1. 索引与解析管线：负责在 index_codebase 命令触发后，遍历仓库文件、抽取符号与定义，并写入 SQLite 存储。该管线同时计算每个文件的提交指纹，以支持后续的新鲜度比对。资料来源：src/storage/sqlite.ts:1-60
2. 拓扑分析器：基于调用图运行 Louvain 社区检测，识别架构枢纽节点，并对跨边界连接进行"反常度"打分，结果以调查问题列表的形式注入到提示中。资料来源：src/topology/analyzer.ts:20-95
3. MCP 服务器：对外暴露六个经过精简的工具——search_context、search_code、explain_flow、memory、refresh_context、get_stats，将前两个子系统的查询结果按需返回。资料来源：src/server/mcp.ts:30-110
4. Wiki 与 Lens 层：Wiki 提供持久化的、由人或代理编写的知识页面；Lens 则在 v0.6.2 引入，将架构可视化生成为自包含的 HTML 仪表盘，二者共同构成"上下文双层"。资料来源：README.md:88-130

部署与运行形态

仓库同时提供 CLI 与守护进程两种入口。CLI 入口位于 src/cli/index.ts，负责调度 index、search、lens、wiki 等子命令；守护进程入口位于 src/index.ts，常驻后台并通过 stdio 与 MCP 客户端通信。资料来源：src/cli/index.ts:1-45, src/index.ts:1-40

package.json 中定义的 bin 字段将 reporecall 注册为全局命令，依赖仅包含 better-sqlite3 与 MCP SDK 等少量原生模块，便于在受限环境中快速部署。资料来源：package.json:15-55

下面以 Mermaid 图描述请求在系统内的典型流转路径：

sequenceDiagram
    participant Agent as AI 代理
    participant MCP as MCP 服务器
    participant Store as SQLite 存储
    participant Wiki as Wiki/Lens
    Agent->>MCP: search_context(query)
    MCP->>Store: 查询符号 + 拓扑 + 新鲜度
    MCP->>Wiki: 关键字匹配 Wiki 页面
    Store-->>MCP: 命中片段 + sourceCommit
    Wiki-->>MCP: 相关页面摘要
    MCP-->>Agent: 带证据引用的上下文块

关键设计权衡

• 精简而非穷举的 MCP 表面：v0.8.0 将工具数量从十多个压缩为六个，目的是减少代理在工具选择上的犹豫与误用。资料来源：README.md:55-72
• 新鲜度优先于完整性：索引写入前会记录 sourceCommit，refresh_context 与 Wiki writePage 均会比较磁盘哈希与存储哈希，跳过未变更内容，从而保证返回给代理的引用始终可信。资料来源：src/storage/sqlite.ts:80-130
• 拓扑作为一等公民：社区反馈表明，单纯的关键字检索不足以回答"这个改动会影响哪些模块"这类问题，因此拓扑结果在每次索引后立即生成并常驻 SQLite，而非按需懒计算。资料来源：src/topology/analyzer.ts:110-160
• Wiki 与索引解耦：Wiki 页面可在 MCP 服务器或守护进程启动时自动生成，也可由人或代理通过 wiki_write 手工维护，两条路径共享同一 sourceCommit 比对逻辑。资料来源：docs/architecture-overview.md:30-75

适用场景与边界

Reporecall 适合中型以上、需要长期演进而代理需频繁重访历史决策的代码库；对于一次性脚本或极小仓库，直接读取文件反而更高效。当前版本（v0.8.0）对外部依赖（如 Git LFS 跟踪的二进制）以及非文本产物的索引仍不完善，社区在后续版本中计划扩展产物感知能力。资料来源：README.md:130-170, docs/architecture-overview.md:90-120

概述

v0.8.0 是 reporecall 的一次破坏性「信任契约」（Trust Contract）修订。它把 MCP（Model Context Protocol）的公开面收敛到六个工具，统一在 mcp-server.ts 注册；同时引入更严格的「新鲜度诚实」（freshness honesty）、更精简的注入上下文、更小的本地存储占用，并降低 agent 在工具选择上的歧义。其核心承诺是：agent 拿到的每一条结论都能追溯到具体的 sourceCommit 与 generatedAt，过期条目会被显式标记，而不是被静默使用。

资料来源：src/daemon/mcp-server.ts:1-1

精简后的六个 MCP 工具

mcp-server.ts 在启动时统一注册以下六个工具，覆盖检索、解释、记忆、刷新与自检五大类需求：

折叠前分散的 wiki、topology、capability 等独立工具被并入对应类别，避免 agent 在相似名称之间反复试探，也使 prompt 上下文里的工具描述更短、更稳定。

资料来源：src/daemon/mcp-server.ts:1-1

注入上下文与工具选择治理

prompt-context.ts 负责在每轮对话前注入受控的仓库上下文，v0.8.0 把注入体积作为一等指标收敛：仅保留命中当前问题的高分片段，并随附 sourceCommit 与 generatedAt，让 agent 能在生成答案时区分「索引结论」与「未索引推断」。

pre-tool-use.ts 拦截 agent 的工具调用请求，依据「最小可用集合」原则拒绝显然冗余的请求（例如参数未变的连续两次 search_context）。这层前置策略是 v0.8.0「更少工具选择困惑」承诺的直接落地。

session-start.ts 在会话开始时一次性预热索引摘要、wiki 入口与新鲜度标记，避免每次都重复检索同一背景；同时复用 v0.6.1 引入的 wiki 启动生成能力，确保上下文从第一条消息起就可信。

资料来源：src/hooks/prompt-context.ts:1-1 资料来源：src/hooks/pre-tool-use.ts:1-1 资料来源：src/hooks/session-start.ts:1-1

新鲜度契约与统计自检

staleness.ts 是信任契约的核心：它根据源码 HEAD 与索引时的 sourceCommit 计算新鲜度差值，并在差值越界时把对应条目标记为「过期」。refresh_context 工具背后即调用此模块触发增量重算；get_stats 则经由 cli/stats.ts 输出当前过期占比、命中数与索引体量，便于人工或 agent 自行判断上下文是否仍可信。

下面以流程图呈现一次典型的 agent 调用链：

flowchart LR
  SS[session-start] --> PC[prompt-context 注入]
  PC --> Agent{Agent 选择工具}
  Agent -- 检索/解释/记忆 --> MCP[mcp-server 六个工具]
  Agent -- 工具调用 --> PTU[pre-tool-use 拦截]
  PTU -- 通过 --> MCP
  MCP --> ST[staleness 计算]
  ST --> Stats[get_stats 输出]
  MCP --> RC[refresh_context 增量刷新]
  Stats --> Agent
  RC --> ST

资料来源：src/core/staleness.ts:1-1 资料来源：src/cli/stats.ts:1-1

小结

v0.8.0 用更窄的 MCP 表面、更薄的注入上下文与更显式的新鲜度标记，把 reporecall 从「尽可能多给信息」调整为「只给当下可信的信息」。任何 agent 调用在通过 pre-tool-use 之后，都能拿到带 sourceCommit 与 generatedAt 的结果，并由 staleness.ts 持续担保其时效；遇到不确定时，调用方可通过 refresh_context 与 get_stats 自助刷新与自检。

1. 概览与目标

v0.7.x 在 reporecall 中引入了两个互补特性：能力证据解析（Capability Evidence Resolution） 与 商业上下文导出（Business Context Export）。前者的目标是当用户提出 trace / architecture / change 类高层提示时，返回可验证的代码层证据；后者把仓库的"产品区域"知识以结构化方式固化到 Wiki 与上下文注入产物中，方便代理与读者快速定位业务范围。资料来源：src/search/capability-evidence.ts:1-40

二者共同服务于 v0.7.x 的核心命题：让 LLM 代理在不依赖捏造的前提下，拿到"与业务相关、来源可追溯、范围清晰"的代码上下文，并被后续 v0.8.0 的 Trust Contract 继续延用。

2. 能力证据解析（Capability Evidence Resolution）

2.1 提示意图分类

capability-evidence.ts 把传入的提示解析为三种能力类别：trace（调用链追踪）、architecture（架构分解）和 change（变更影响）。每种类别对应不同的证据选取策略与排序权重，从而避免 LLM 在面对高层问题时被淹没在通用 chunk 中。资料来源：src/search/capability-evidence.ts:42-90

2.2 证据合并流程

解析后的能力证据通过 ContextAssembler 注入到下游检索结果中。context-assembler.ts 把"能力证据"作为一个独立槽位，与 search_context / search_code 的命中文档并行组装，使高层提示在不被稀释的条件下仍可被代理消费。资料来源：src/search/context-assembler.ts:55-130

2.3 排序与去噪

排名阶段（ranker.ts）对能力证据使用专门的 boost：当候选命中与所解析的能力类别匹配时，会叠加一个 +capabilityBoost 权重；不匹配的命中则被降权。这一步显著降低"无关 chunk 顶替证据"的概率，是 v0.7.x 自评修复中保留的稳定行为。资料来源：src/search/ranker.ts:88-140

3. 商业上下文导出（Business Context Export）

3.1 产品区域定义

src/business/product-areas.ts 定义了仓库的产品区域清单（product areas）。每个区域是一组带有关键字、入口文件和说明的结构化记录，可被检索、Wiki 与评测同时消费，构成"商业上下文"的唯一事实源。资料来源：src/business/product-areas.ts:1-60

3.2 Wiki 业务页写入

Wiki 生成器（src/wiki/generator.ts）在 MCP server/daemon 启动或 index_codebase 收尾阶段调用 src/wiki/business.ts，把每个 product area 渲染为一张 Wiki 页面。这些页面会进入 wiki_query / wiki_read 的索引，使代理能像搜代码一样搜"业务概念"。资料来源：src/wiki/business.ts:30-95 资料来源：src/wiki/generator.ts:120-180

3.3 双路径导出

商业上下文导出同时落到两个目标：(a) Wiki 页面内的人类可读说明；(b) 注入到检索上下文中的机器可读条目（如 [PRODUCT_AREA] payments）。两条路径共享同一份 source-of-truth，避免后续版本出现漂移。资料来源：src/business/product-areas.ts:60-110 资料来源：src/search/context-assembler.ts:131-170

4. 与 Trust Contract（v0.8.0）的衔接

v0.8.0 的 Trust Contract Remediation 将 MCP 表面折叠为六个工具：search_context、search_code、explain_flow、memory、refresh_context、get_stats。能力证据解析与商业上下文导出并没有成为独立工具，而是被 search_context 与 explain_flow 透明复用——它们的产物（能力证据 + 业务锚点）成为"更瘦的注入上下文"的一部分，从而同时满足"新鲜度诚实"与"更小存储占用"两项约束。

数据流小结

概述与定位

reporecall 自 v0.5.0 起将"代码库即图"的理念贯穿索引与检索流程，并在 v0.6.0–v0.6.2 之间构建了三层互补的输出：拓扑分析管道（结构事实）、Wiki 知识层（语义注释）、Lens 仪表盘（人类可读的静态可视化）。三者共享同一份 SQLite 索引作为真值源，分别面向机器（agent 工具调用）、编辑者（人工知识沉淀）与浏览者（架构评审与新成员 onboarding）。

flowchart LR
  Index[索引 SQLite] --> Topo[拓扑管道<br/>src/topology/index.ts]
  Topo --> Lens[Lens HTML<br/>src/visualize/*]
  Topo --> Wiki[Wiki 页面<br/>src/wiki/generator.ts]
  Wiki --> Lens
  Lens --> 浏览器[单文件 HTML]
  Wiki --> MCP[MCP 工具<br/>wiki_*]

拓扑感知检索

每次索引完成后，拓扑管道在调用图上运行 Louvain 社区检测，识别架构枢纽节点，并对跨越模块边界的"令人意外"的连接进行打分，最终生成引导性问题清单。资料来源：src/topology/index.ts:1-120

检测结果以 JSON 形式持久化到 SQLite 的拓扑表，在随后的 search_context、explain_flow 调用中被作为上下文注入。这意味着 agent 检索不再只匹配文本相似度，还会获得"哪些文件处于同一社区""哪些函数是枢纽""哪些连接看起来异常"的图结构提示，从而让回答更具架构意识。资料来源：src/topology/index.ts:120-260

Wiki 知识层

Wiki 层（v0.6.0 引入）在拓扑结果之上提供持久化的"代码库维基百科"。它暴露四个 MCP 工具：wiki_query（关键词搜索）、wiki_read（读取单页或列出全部页面及反向链接）、wiki_write（手动创建或更新页面），以及一个用于链接关系解析的能力。资料来源：src/wiki/links.ts:1-80

页面由 wiki/generator.ts 自动生成：索引或 MCP 服务器/守护进程启动时（v0.6.1 起），生成器遍历 SQLite 中的拓扑社区与枢纽节点，按模板产出社区概述页、枢纽节点页与跨边界异常页。writePage 实现了一个新鲜度守卫：写入前读取磁盘上的 sourceCommit，若与当前索引的源码提交一致则跳过，避免无意义的覆盖。资料来源：src/wiki/generator.ts:60-180

页面之间通过内部链接互相引用，由 src/wiki/links.ts 中的解析器在写入时插入反向链接锚点，从而形成一个可被 wiki_query 检索的小型知识图谱。

Lens 仪表盘

Lens 是面向人类的可视化入口。CLI 命令 reporecall lens 调用 src/cli/lens.ts 中的处理器，依次执行三步：

1. 通过 src/visualize/data-extractor.ts 从 SQLite 中抽取节点、社区、枢纽、Wiki 页面摘要与文件统计。资料来源：src/visualize/data-extractor.ts:1-160
2. 将抽取结果注入 src/visualize/html-template.ts 中的五标签页模板（社区、枢纽、文件、Wiki、异常连接）。资料来源：src/visualize/html-template.ts:1-220
3. 由 src/visualize/index.ts 组装并写入单文件、自包含的 HTML——所有 CSS/JS 与数据都内联，浏览器离线即可打开。资料来源：src/visualize/index.ts:1-140

输出特性使其特别适合在没有 Node 环境的审查会议上分发，也便于新人作为"代码库地图"快速建立心智模型。

协同与边界

三者的边界在于：拓扑管道是只读计算，Wiki 层允许双向写入（用户或生成器），Lens 是单向只读渲染。这保证了即使人工编辑 Wiki 也不会污染底层的图事实。

与 v0.8.0 Trust Contract 的关系

v0.8.0 将 MCP 公共表面压缩为六个工具，独立的 wiki_* 工具被折叠进 memory 工具族以减少 agent 的工具选择歧义；然而底层 Wiki 存储与生成管道并未移除，Lens 与拓扑检索继续保持当前形态，仅在注入到 agent prompt 时遵循新的新鲜度契约。资料来源：src/visualize/index.ts:40-80

Pitfall Log / 踩坑日志

项目：proofofwork-agency/reporecall

摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: v0.5.0 — Topology-Aware Search & Architecture Decomposition。

1. 安装坑 · 失败模式：installation: v0.5.0 — Topology-Aware Search & Architecture Decomposition

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.5.0 — Topology-Aware Search & Architecture Decomposition
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.0 — Topology-Aware Search & Architecture Decomposition
• 证据：failure_mode_cluster:github_release | https://github.com/proofofwork-agency/reporecall/releases/tag/v0.5.0 | v0.5.0 — Topology-Aware Search & Architecture Decomposition

2. 安装坑 · 失败模式：installation: v0.6.2 — Lens Architecture Dashboard

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

3. 安装坑 · 失败模式：installation: v0.7.1 — Capability Evidence + Business Context Export + Self-Eval Patches

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.7.1 — Capability Evidence + Business Context Export + Self-Eval Patches
• 对用户的影响：Upgrade or migration may change expected behavior: v0.7.1 — Capability Evidence + Business Context Export + Self-Eval Patches
• 证据：failure_mode_cluster:github_release | https://github.com/proofofwork-agency/reporecall/releases/tag/v0.7.1 | v0.7.1 — Capability Evidence + Business Context Export + Self-Eval Patches

4. 安装坑 · 失败模式：installation: v0.8.0 — Trust Contract Remediation

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

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

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

6. 配置坑 · 失败模式：configuration: v0.6.0: Wiki Layer, Topology Tools & Memory Precision

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.6.0: Wiki Layer, Topology Tools & Memory Precision
• 对用户的影响：Upgrade or migration may change expected behavior: v0.6.0: Wiki Layer, Topology Tools & Memory Precision
• 证据：failure_mode_cluster:github_release | https://github.com/proofofwork-agency/reporecall/releases/tag/v0.6.0 | v0.6.0: Wiki Layer, Topology Tools & Memory Precision

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

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

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

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

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

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

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

11. 运行坑 · 失败模式：performance: v0.6.1: Wiki Startup Generation & Version Sync

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: v0.6.1: Wiki Startup Generation & Version Sync
• 对用户的影响：Upgrade or migration may change expected behavior: v0.6.1: Wiki Startup Generation & Version Sync
• 证据：failure_mode_cluster:github_release | https://github.com/proofofwork-agency/reporecall/releases/tag/v0.6.1 | v0.6.1: Wiki Startup Generation & Version Sync

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

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

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

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

14. 维护坑 · 失败模式：maintenance: v0.3.1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.3.1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.3.1
• 证据：failure_mode_cluster:github_release | https://github.com/proofofwork-agency/reporecall/releases/tag/v0.3.1 | v0.3.1