企业官网建设流程全解析

AgentsView Recall：为编码 Agent 构建带证据锚点的经验知识库

【免费下载链接】agentsviewLocal-first session search, analytics, insights, and token use statistics for coding agents, supporting Claude Code, Codex, and more than 20 other agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agentsview

AgentsView 的 Recall 是一项实验性功能：它把过去 Agent 会话中沉淀的事实、流程、偏好与警告提炼为带证据链接的条目（entry），让你可以浏览、检索这些条目，或把它们打包成一份可信的任务简报。本文基于 docs/recall.md 与仓库源码，讲清 Recall 的条目模型、CLI 与 Web 表面、向量/混合检索、自动抽取的完整配置、证据与信任策略、评审导入与取代机制，以及测量账本的数据生命周期；读完后你将能在本地安全地启用并运维一套"可重建的研究语料"，并理解它为什么刻意把会话存档设为唯一权威。

重要前提：Active research。Recall 的 schema、打分、信任策略与工作流都仍可能变化。它的条目和测量行应当被视为可重建的研究语料：在 Recall 稳定之前，升级可能需要重建其新表而不是迁移。会话存档（session archive）始终是唯一权威数据，绝不能为了"重置 Recall"而删除、截断或重建它。

Recall 的条目模型：与语义搜索的分工

语义搜索在转录文本里检索段落；Recall 检索的是已提炼的条目。两者互补：前者回答"哪段对话提到过 X"，后者回答"我以前从哪些会话里学到了关于 X 的可复用结论"。

Recall 支持三种检索模式：

• lexical（默认）：按词匹配；
• vector：按语义匹配，检索独立的 Recall 向量库；
• hybrid：词法与向量排名融合。

每条条目都有明确的结构语义。从 internal/recall/types.go 可以看到条目类型与范围的取值集合：

• 类型（type）：fact、decision、procedure、debugging_method、warning、preference、open_question；
• 范围（scope）：global、project、repository、branch、file、tool、agent；
• 状态（status）：accepted、archived；
• 评审状态（review_state）：见下文"证据与信任"一节。

持久化层面，recall_entries表定义在 internal/db/schema.sql 中：每条记录携带title、body、trigger、confidence、uncertainty，以及project、cwd、git_branch、agent等会话上下文字段；source_session_id外键指向sessions(id)且ON DELETE CASCADE，保证条目永远锚定在源会话上；transferable、provenance_ok、supersedes_entry_id、superseded_by_entry_id等列则支撑信任判定与取代链。

当前实现是local 且仅支持 SQLite的：PostgreSQL 或 DuckDB 商店没有 Recall 后端，因此这些只读服务器打开 Recall 页面时会直接进入"Generated insights"标签。

当前表面：CLI、Web 页面与守护进程 API

CLI 子命令

recall命令组在 cmd/agentsview/recall.go 中注册，提供以下子命令：

list/query支持一组完整的过滤旗标（定义于 cmd/agentsview/recall.go）：--query、--project、--cwd、--git-branch、--agent、--type、--scope、--status、--extractor-method、--source-session-id、--source-episode-id、--source-run-id、--supersedes-entry-id、--superseded-by-entry-id、--trusted-only、--limit，以及--mode（默认lexical）、--context、--context-max-bytes。此外还有三个"当前环境"快捷旗标：--current-cwd（当前工作目录）、--current-git-branch（当前 git 分支，通过git symbolic-ref解析）、--current-worktree（同时应用 worktree 根目录与分支，且不能与--cwd/--current-cwd/--git-branch混用）。查询结果还可加--scores（排序分数诊断）、--evidence（证据片段）、--summary（聚合摘要）。

词法排序的分数构成在 internal/recall/types.go 的ScoreBreakdown中可见：关键词重叠、关键词 IDF、证据片段关键词重叠与 IDF、标识符/短语/实体加权、时间加权、置信度加分与基础分。--scores输出的正是这些诊断值。

Web 页面

顶层Recall页面有两个标签，可从页头进入，或直接导航到/recall：

• Corpus：提炼条目的只读浏览器。显示抽取覆盖率与生成状态，可按文本、项目、条目类型、generation、评审状态过滤。展开条目可查看正文、触发条件、不确定性、来源元数据，以及指回源转录的证据链接。
• Generated insights：在显式的会话范围内创建并存储更长的报告。表单总是展示下一次报告所用的日期范围、项目、会话 agent、自动化会话范围、报告模板、生成器与可选 focus。已保存的报告可以从存档中导出、发布、链接或删除。

生成报告的链接形式为/recall?tab=generated&insight=<id>。在本地 SQLite UI 中，Session Vital Signs 还包含一个针对当前打开会话的只读 Recall 面板，并把每个证据范围链回转录。而语料填充、评审、抽取 generation 管理与排序查询仍属于CLI 与 HTTP API 工作流。

守护进程通过 HTTP API 暴露同样的检查与查询操作。当 SQLite 商店可写时，普通查询会记录测量数据；只读存档同样可查询，只是不记录。

Generated insights 的模型端点配置

Generated insights 在[insights]同时配置了endpoint和model时，使用已配置的 OpenAI 兼容端点；[insights]缺省时，回退到本机选定的 agent CLI。部分配置（只有 endpoint 或只有 model）会在配置校验时被拒绝——internal/config/config.go 中对[insights]的校验要求 endpoint 与 model 成对出现。端点模式发起一次非流式POST /chat/completions请求，把生成的 prompt 作为 user message；只接受第一个 choice 中message.content为字符串的assistant消息及可选的 responsemodel。它不支持流式、/responses、旧版 completions、工具调用或 content-part 数组；端点失败会直接返回错误，不会降级重试 CLI。

[insights] endpoint = "http://127.0.0.1:11434/v1" model = "llama3.1" api_key_env = "OPENAI_API_KEY" # 可选；值在运行时读取 # allow_http = true # 非 loopback 的 HTTP 端点必需

传输规则：loopback HTTP 端点对本地模型放行；远程端点必须使用 HTTPS，除非显式allow_http = true接受明文风险。端点会收到源自转录的内容，使用前应审查供应商的隐私与留存策略。API key 只留在环境变量中、仅作为 bearer 头发送，不会写入 AgentsView 配置。内置报告的缓存 key 包含生效后端、模型与安全的端点身份标识，因此重启服务器后修改[insights]会命中另一份缓存报告；而凭据或传输选项的变化不会改变该身份——如果这类变化需要重新生成报告，应使用强制刷新。

配置 agent 二进制

AgentsView 默认通过PATH解析claude、codex、copilot、gemini与kiro-cli。要固定某个可执行文件，为对应 agent 表配置binary：

[agent.claude] binary = "/usr/local/bin/claude" [agent.gemini] binary = "/usr/local/bin/gemini"

每个已知 agent 有独立的覆盖项。该设置只影响报告生成；会话发现仍读取已配置的会话目录。

向量与混合检索

recall query和recall brief接受--mode lexical、--mode vector、--mode hybrid，词法为默认。向量检索对独立的 Recall 向量库排序，混合检索则融合词法与向量排名。

Recall 与会话语义搜索共用同一套[vector]模型与 embeddings 服务器配置，但拥有独立的索引 generation。需要显式构建：

agentsview embeddings build --store recall

由于已接受的条目可能包含被提炼过的私密内容，自动化的 Recall embedding 需要单独的同意：

[vector.embed] recall = true

该设置允许启动时、语料变更时与周期性刷新把已接受 Recall 条目的标题、正文与 trigger 发送到已配置的 embeddings 端点；默认关闭。手动运行构建命令视为对该次调用的一次性同意（对应 docs/semantic-search.md 中"该命令无需同意即可手动执行"的说明）。

两条重要的检索语义：

1. 失败闭合（fail closed）：当活动 Recall 语料比上一次完成的向量构建更新时，向量与混合查询会直接失败。此时要么重建 Recall 库，要么在自动刷新追上之前继续使用词法模式。
2. 过滤在候选排序之后：向量候选在 Recall 过滤条件生效之前已被排序。embedding 后端限定候选窗口，因此当 project、cwd 或其他过滤很窄时，若触及该边界，向量分页可能很短。混合搜索则对为该查询选定的词法候选排序后，再与可用的向量候选融合。

自动抽取：[recall.extract]完整指南

抽取是可选且默认关闭的。启用[recall.extract]后，一个本地 OpenAI 兼容模型把已结束的会话提炼为条目，守护进程自动调度：同步活动触发增量 pass，周期性 backstop 重新访问转录在抽取之后发生过变化的会话。这样产出的条目以unreviewed_auto状态存储——在被提升之前，它们始终位于可信 Recall 之外。

最小本地配置：

[recall.extract] enabled = true model = "your-model-name" [recall.extract.servers.local] endpoint = "http://127.0.0.1:30000/v1"

远程 OpenAI 兼容供应商（如 Atlas Cloud）示例，key 留在环境变量、端点指向供应商的/v1基址：

[recall.extract] enabled = true model = "deepseek-ai/deepseek-v4-pro" server = "atlascloud" [recall.extract.servers.atlascloud] endpoint = "https://api.atlascloud.ai/v1" api_key_env = "ATLASCLOUD_API_KEY" timeout = "120s"

可选键及默认值（对照 internal/config/recall.go 的结构定义与校验逻辑）：

传输隐私规则由ValidateExtractTransport（internal/config/recall.go）在配置校验与客户端重定向策略两处共同执行：非 loopback 端点必须使用 HTTPS，因为抽取会把转录内容发往端点，机器外的明文 HTTP 可能被截获；server 条目可设allow_http = true在可信内网显式接受该风险。重定向永不被跟随——一次重定向会把请求（含转录内容）原样重放到端点命名的任何目的地，甚至同源的放行也可能被主机名重新解析引向别处；请用最终 URL 配置端点（HTTP 客户端装配见 cmd/agentsview/recall_extract.go 的RefuseRedirects）。

会话资格与密钥门禁

一个会话只有同时满足以下全部条件才会被抽取：不是自动化会话、未被 trash、拥有干净且当前有效的 full 密钥扫描。默认情况下，带有任何置信度的密钥发现的会话、从未扫描过的会话、只被快速内联同步扫描覆盖的会话，都不会到达模型。运行agentsview secrets scan --backfill让会话变得有资格。会话内容只会发往你配置的端点。

candidate_findings = "allow"是唯一有意收窄这条边界的旋钮：候选级发现——那些易误报的启发式（high-entropy-assignment、JWT 形态的 token、basic-auth URL，即secrets list默认隐藏的部分）——仍会被记录供评审，但不再排除会话；只有确定性发现才在发现阶段、发送前转录检查、提交与对账中阻断。默认"block"让每条已记录发现都保持阻断。当端点是你自己拥有的机器、且档案里满是路径与标识符不断触发熵启发式时，可考虑"allow"；对于你不会把疑似密钥发往的任何端点，保持默认。

这些隐私谓词不可配置——quiet_period只是调度旋钮。设计契约详见 docs/internal/recall-extraction.md：资格在 SQL 中由ExtractCandidates强制、Go 侧对单会话运行再检查；每次模型调用前与每次输出落库前都会重验会话快照；transcript 任何变更都会推进transcript_revision并清除扫描戳，使会话在重扫前重新失去资格；发送前还会对"模型实际可见内容"（按转录顺序拼接的单元文本，含换行拼接与无分隔符聚合两种形态）做一次独立重扫，任何命中即失败闭合。

Generation、指纹与运维命令

每份蒸馏配置（模型、prompt、分段、请求形态）被指纹化为一个generation；改变配置会构建新语料而不是混合输出，且任一时刻只有一个 generation 处于 active（生命周期building → active → retired，见 docs/internal/recall-extraction.md）。指纹是 SHA-256，覆盖协议版本、模型身份（模型名 + 可选 deployment 标签；端点被刻意排除，同一部署搬迁不应孤立语料）、分段器名称与参数、按角色的 prompt 摘要、请求形态（temperature、max_tokens、extra body）。

CLI 子命令（cmd/agentsview/recall_extract.go）：

agentsview recall extract run [--session <id>] [--full] [--limit N] # 手动跑一个 pass agentsview recall extract status # 显示当前 generation 的覆盖率 agentsview recall extract activate # 激活已配置的 generation agentsview recall extract retire <fingerprint> [--force] agentsview recall extract doctor # 打印解析后的配置与指纹，并做一次探针调用 agentsview recall extract preview --session <id> # 不調用模型，预览确定性会话切块

run的--session绕过静默期但绝不绕过隐私过滤；--full重新访问已完成但转录增长的会话；--limit不得为负（0 表示全部）。doctor会输出一行形如probe: ok (N entries, P prompt + C completion tokens)的探针结果，且错误消息会先经终端清洗再呈现，防止恶意服务端注入转义序列。手动写命令在守护进程拥有档案时会被拒绝（守护进程会自己跑 pass），并显式拒绝--server，同时持有离线写锁，保证多步抽取 pass 不会与其他直接写者或 resync 交叠。

守护进程调度（docs/internal/recall-extraction.md "Scheduling" 一节）与 embedding 调度器同形：同步完成事件经 30 秒防抖进入增量 pass，其发现带有水位线，稳态成本随近期活动而非档案规模增长；backstop_interval（默认 1h）驱动全量 pass，只重访其单元快照之后被写入过的已完成会话；backstop 禁用时，按静默期节拍（最快每分钟一次）的 catchup 计时器接管增量 pass。每个守护进程生命周期都以一次全量 pass 开始，因此空闲自回收（默认 20 分钟）不会漏掉静默期已过的会话。抽取被禁用但曾有 generation 被激活时，守护进程退化为reconcile-only 调度器：模型循环不跑，但失去资格的会话（被 trash、标记自动化、检出密钥）仍会停止服务其条目——隐私撤回不能被调度策略绕过。

证据与信任

每条持久条目标识其源会话；其证据记录精确的消息序数（ordinal）、可用的稳定消息身份、被选中的工具使用，以及模型可见内容的摘要。转录被重新解析或改写时，AgentsView 会机械地验证这些证据。

如果锚定的消息消失、变得含糊，或其选中内容变化，条目的 provenance 即被吊销。吊销是粘性的：后续解析器输出不会自动恢复信任或替换已存摘要。实验性用户应预期解析器改进会导致部分或全部 Recall 语料需要重新生成。

证据授权是主机所有的：模型或导入者可以收窄窗口，但不能选择另一个会话、引用供应窗口之外的消息、或伪造稳定消息 ID 与摘要。证据必须与其条目同属一个源会话。这些检查走共享的插入与评审导入边界，而不是单独的模型写路径。

四种评审状态（与 internal/db/schema.sql 中review_state的 CHECK 约束、internal/recall/types.go 的NormalizeReviewState一致）：

信任语义：

• 仅可信（trusted-only）读取要求条目既是被接受的human_reviewed，又是可转移的（transferable）且 provenance 有效；自动化标签不能授予human_reviewed。
• 原始评测条目被刻意排除：评测脚手架若要检查eval_raw材料，必须显式请求trusted_only=false。
• 构建标签（build tag）下的 eval-ingest 响应返回版本化的corpus_id；查询时把它作为source_session_id传入，使同一 run 中变化的轨迹内容或源版本不会与更早的语料版本混杂。
• 省略的评审状态失败闭合为unreviewed_auto；已存档条目永不可信；带显式非接受状态的 trusted-only 请求会被拒绝，而不是返回一个误导性的空结果。

评审 JSONL 导入与取代

评审 JSONL 导入是当前的实验性填充入口，不是稳定、也不推荐面向最终用户的工作流。实验请使用隔离的AGENTSVIEW_DATA_DIR：导入命令拒绝默认数据目录，除非操作员显式覆盖该防护。

取代（supersession）规则：候选 ID 是不可变的导入身份——重导已有 ID 是幂等跳过（即使其转录随后被重新解析），但新候选仍须通过当前会话、证据与取代校验。一个替代者只能取代活跃、已接受且尚无后继的条目；AgentsView 在同一事务中存档被取代条目并建立指向替代者的链接，防止两个已接受的替代者从一个历史条目分叉。使用占位会话的导入具有未验证的 provenance：它们可以替换其他未验证条目用于评测，但不能取代 provenance 有效的条目，也不能把它移出可信 Recall。

导入确认旗标（cmd/agentsview/recall.go）：

• 先运行--dry-run校验并计数；
• 写入需要--yes；远程写入（--server）还需要--allow-remote-import；
• 本地导入拒绝默认生产数据目录，除非显式提供--allow-production-import；
• 另有--require-existing-sessions（默认开，拒绝源会话或证据不在库中的条目）与--allow-placeholder-sessions。

这些确认是对风险的承认，不会放松证据、评审状态或取代校验。

测量账本与数据生命周期

完成的 Recall 查询会记录一条只增测量事件，包含：表面（surface）、序列化过滤条件、结果与打包计数、miss 原因、以及暴露给调用方的排序条目。该账本支持检索校准，且不改动源会话存档。

• 记录成功时响应返回不透明 query ID。初始 miss 原因区分"无排序结果"与"结果放不进请求的上下文"。排序与打包的暴露不被视为"答案使用了该条目"或"条目有帮助"的证明。
• 普通记录是尽力而为的：账本失败不会掩盖有用的 Recall 输出；校准调用方可要求严格记录。事件及其排序暴露快照在全量 resync 后依然保留，即使被引用的 Recall 条目已不存在。
• 该实验账本目前只增、没有修剪策略。在规模化跑校准之前，项目必须定义有界请求尺寸加上保留与导出行为。

研究阶段的数据重建规则：Recall 条目与测量行在 schema、解析器、打分或抽取策略变化时可能需要重建；只通过未来显式的工作流重置实验性 Recall 语料，永远不要把删除或重建会话存档当作 Recall 的重置手段。

实验性边界（小结）

Recall 仍是可选的研究特性：自动抽取永远不会把条目提升进可信 Recall，会话面板只读，没有 PostgreSQL 或 DuckDB 后端，没有稳定的最终用户导入工作流，测量账本也没有修剪策略。随着 schema、打分、抽取策略与信任模型演化，请预期语料重建。

延伸阅读：docs/recall.md（本文主体来源）、docs/internal/recall-extraction.md（抽取设计契约）、docs/semantic-search.md（共用的 embedding 配置与端点隐私）、internal/db/schema.sql（recall_entries与向量新鲜度触发器：recall_corpus_state单调修订号与recall_embedding_changes变更日志）。

【免费下载链接】agentsviewLocal-first session search, analytics, insights, and token use statistics for coding agents, supporting Claude Code, Codex, and more than 20 other agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agentsview