Skip to content

About

Evidence-native RAG/Agent research workspace: immutable citations, durable execution, hybrid retrieval and storage integrity.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

溯知 Evidence OS

Evidence-Native Research Agent — 以 RAG 为证据引擎,把“问一句、答一段”升级为可计划、可暂停、可审阅、可复现的研究智能体。

CI Version Python FastAPI Next.js License

溯知 Evidence OS Workbench

30 秒看懂

一句话:把 RAG 从“生成一段答案”做成“可回放、可恢复、可验证的证据流水线”。

可验证结果 当前值 边界
后端回归 1014 passed / 4 skipped 本机 + CI
前端单测 / 浏览器回归 206 / 59 生产构建 Chromium
固定 Agent 评测 60 / 60,citation completeness 1.0 合成固定集,不是真实模型质量
中文检索(严格模式) 24 题,Hit@1/5 = 1.0 小样本,不代表开放域

快速入口:

它解决什么问题

传统 RAG 通常止步于“检索几段文本,再让模型生成答案”。一旦来源发生更新、任务跨越多份资料、执行中断,或者用户要求解释“这条结论究竟来自哪一版证据”,系统就很难给出可信回答。

溯知把 RAG 放在 Agent 的中心,但不把模型当作系统权限边界:

普通 RAG 溯知 Evidence Agent
一次 query → answer goal → route → plan → retrieve → assess → artifact
citation 只指向当前文本片段 EvidenceRef 固定 source/revision/index/chunk/hash/locator
来源更新可能静默改变答案 新任务使用 active revision,已开始任务继续使用 pinned revision
请求失败后从头开始 checkpoint、event journal、outbox 与幂等 command 支持恢复
模型直接决定下一步 工具、scope、预算、审批和取消由确定性策略控制
最终只返回一段文本 生成逐 claim 绑定证据的 Artifact,证据不足则输出 Gap Report

核心工作流

flowchart LR
    A["选择知识空间与 active 来源"] --> B["提交研究目标"]
    B --> C{"Quick or Agent"}
    C -->|单一事实| D["直接检索"]
    C -->|跨来源任务| E["结构化计划"]
    E --> F["逐 requirement 检索与充分性判断"]
    D --> G["Immutable Evidence Ledger"]
    F --> G
    G --> H{"需要人类决定?"}
    H -->|澄清 / 审批| F
    H -->|证据充分| I["Claim-level Artifact"]
    H -->|证据不足| J["Evidence Gap Report"]
    I --> K["回跳 PDF 页 / 媒体时间 / 代码行"]
Loading

Agent Run 与 Evidence Ledger

真正体现工程水准的部分

  • Evidence lifecycle:所有新文档、代码、图片、音频与视频证据统一进入 Stage → Upsert → Activate;数据库约束保证每个 Source 最多一个 active revision/index。
  • 跨存储一致性:Qdrant point 先有 manifest,再执行写入;失败可补偿,reconciler 默认 dry-run,能够发现 orphan、missing 与 payload mismatch。
  • Durable Agent runtime:Run、Plan、Requirement、ToolCall、ModelCall、Checkpoint、Gate、Event 与 Artifact 都是持久状态,不依赖浏览器连接存活。
  • 受控模型智能:生产 AgentModel 使用严格结构化输出完成 route、plan、sufficiency/next-query 与 synthesis;provider 调用发生在 SQL 事务外,非法结构只允许一次受预算约束的 repair,未配置真实模型时明确拒绝运行。
  • 硬预算与 execution fence:step、tool、model、token、time、cost、query rewrite、无新证据轮数均有边界;取消会推进 epoch,迟到结果不能写回。
  • 持久恢复:Run 与 outbox 使用原子 lease/CAS;Worker 重启会校验 checkpoint,恢复中断的只读检索,对未知模型结果 fail-closed;poison message 进入有界重试与 dead-letter,不阻塞同批任务。
  • Human-in-the-loop:clarification、approval、reject、pause、resume、cancel 都是带 version/digest 的幂等 command,而不是前端假状态。
  • 可核验证据:每个 factual claim 至少关联一个 EvidenceRef;Artifact → Claim → Evidence → Revision → Source 支持 revision/hash/chunk 精确深链与历史退休版本回放。
  • 多模态定位:当前与历史 revision 都支持文档页、媒体时间戳、OCR 区域与代码行 locator,并经过浏览器深链回归。
  • 产品边界清晰:主导航只保留 Workbench、Agent Runs、Library、Artifacts;诊断和旧功能收进 Developer Mode。

Claim-level Artifact 与 Evidence Inspector

可复现实验,而不是“看起来很智能”

仓库内置 60 条固定评测集,覆盖单跳、多跳、跨模态、版本冲突、证据不足、prompt injection 与取消恢复。报告通过真实模块接口执行:

EvidenceIndex.stage/upsert/activate
  → HybridAgentSearch (pinned snapshot + RRF; Agent rerank disabled)
  → EvidenceAgent.submit
  → AgentRunner.advance_one

Independent retrieval evaluation arms: dense / sparse / fusion / labeled recording rerank

当前确定性评测结果来自 V5.8 原始 JSON:

指标 结果
固定场景通过率 60 / 60
Fusion Recall@10 1.0000
Citation completeness 1.0000
Immutable evidence identity 1.0000
Active-revision precision 1.0000
Recovery scenarios 6 / 6
Unauthorized action rate 0.0000
多跳 Agent task success 100%
V4.9-style single-shot proxy 41.67%
多跳提升 +58.33 percentage points

边界说明:这是 synthetic fixed corpus + deterministic recording model/embedding 的架构与回归评测,不是真实大模型质量基准;Agent 分支实际经过 HybridAgentSearch 的 pinned-snapshot dense/sparse RRF,固定报告中明确禁用 Agent reranker。独立 rerank 评测臂使用带标签的 deterministic feature-overlap recording adapter,仅验证重排契约。“V4.9-style”是同一 canonical corpus 上、top-4 单次检索的可重复代理实验,不冒充历史版本原样复跑。仓库已提供可选真实 HTTP rerank Adapter,但固定报告和默认环境未配置它,因此不宣称生产 rerank 质量。

V5.2 把这套评测变成可操作的产品能力:

  • /evaluations 启动并保存固定评测,显示指标、门禁、类别和 60 个案例。
  • 两份快照只有在 schema 与 dataset hash 一致时才能比较,否则明确显示不可比较。
  • /runs/{run_id}/trace 重放持久化事件,核对顺序、Trace ID、终态和检查点。
  • 私有事件、prompt、工具参数和 checkpoint state 只显示脱敏标记,不进入前端响应。
  • 失败由确定性 Triage 分类,并给出可重试性与下一步动作。

V5.3 进一步把检索策略做成可治理的产品能力:

  • /policies 保存不可变策略版本,支持草稿、活动、退役和审计回滚。
  • 事实型、比较型和时间型 requirement 使用不同 Top-K,并应用分数、来源多样性和相邻上下文边界。
  • 每个 Run 固定策略 id/version/hash/config;后续启用或回滚不会改变进行中或历史任务。
  • 候选策略可以对历史决策做无副作用反事实模拟,并通过固定 60 场景评测后才能启用。
  • Policy Lab 串起“创建 → 比较 → 模拟 → 评测 → 启用 → 固定新 Run → 回滚”的完整流程。

完整的通俗技术解释见 V5.3 策略与自适应检索:通俗解释版。

V5.4A–V5.7 把“策略可治理”继续推进成一个可操作的离线优化闭环:

  • /policies/optimizer 用质量优先、平衡、成本优先模板创建可重复实验,预算只能收窄,不能扩大。
  • 每个 Trial(候选实验)固定策略快照和 SHA-256 指纹,通过 60 个确定性案例后才参与排序。
  • Pareto Frontier(帕累托前沿)保留无法被其他候选在全部指标上同时超过的方案,并给出可核验推荐理由。
  • Observation-guided Search(历史结果引导搜索)用线性趋势与随机探索生成下一轮候选,同时执行累计预算、去重和幂等约束。历史代码名保留 Bayesian,但实现没有贝叶斯后验与不确定性估计。
  • 推荐最多转换成 Draft(草稿);系统不会自动启用策略,仍须经过人工评测门禁。
  • Workbench(实验工作台)展示轮次、完整指标、策略差异、分类胜负、事件日志和确定性对比报告。
  • Run Trace(运行轨迹)可创建 7 天有效的脱敏只读分享,并支持复制路径与即时撤销。

通俗实现说明见 V5.7 通俗解释。

V5.7.1 发布后审计补齐了预算与超时执行守卫、并发轮次/草稿保护、结果评分原子保存、 暖启动快照、报告身份核对、三方分类比较,以及页面自动更新和刷新后的分享撤销。 该修订的验收依据见 V5.7.1 审计报告。 想了解每项修复的原理与英文术语,可看 这轮改了什么、怎么实现。

V5.8:从错误反馈积累可审阅的评测样例

  • 在真实保存的成果页,对整份报告或单条结论提出反馈;服务器固定任务、策略、正文和原证据快照,不接受客户端伪造事实。
  • /evaluations/feedback 提供人工接受/驳回、版本冲突保护和幂等重试。接受决定与唯一评测样例同事务保存,不修改原答案或知识库。
  • 样例区分 tuning(调参)与 holdout(留出测试),并按真实/演示/录制运行模式隔离导出;下载前核对样例选择及 SHA-256 内容指纹。
  • 反馈是待审阅意见,人工参考答案也不是自动验证的真理。新样例格式不冒充固定 60 场景的输入,尚未接入自动评分或真实模型质量评测。

查看 V5.8 验收记录 和 通俗实现说明。

复现:

python scripts/evaluate_agentic_rag.py --mode demo --output docs/v5_agentic_rag/evaluation_report.json
python scripts/check_v5_acceptance.py

架构

flowchart TB
    UI["Next.js Workbench / Run Workspace / Evaluation Studio / Policy & Optimizer Lab"]
    API["FastAPI command/query/SSE API"]
    EA["EvidenceAgent deep module"]
    AC["AgentControl deep module"]
    AP["AgentPolicy deep module"]
    AO["AgentPolicyOptimizer deep module"]
    RS["AgentRunShare deep module"]
    EI["EvidenceIndex deep module"]
    SQL["SQLite + SQLAlchemy\nRun state / event journal / provenance"]
    OUTBOX["Transactional Outbox"]
    RQ["Redis / RQ one-slice workers"]
    VDB["Qdrant vector points"]
    MODEL["Structured AgentModel"]
    PROVIDERS["LLM / Embedding / OCR / STT"]

    UI -->|submit / inspect / command| API
    API --> EA
    API --> AC
    API --> AP
    API --> AO
    API --> RS
    EA --> SQL
    EA --> OUTBOX
    OUTBOX --> RQ
    AC --> OUTBOX
    AC --> SQL
    AP --> SQL
    AP --> EA
    AP --> AC
    AO --> AP
    AO --> AC
    AO --> SQL
    AO --> OUTBOX
    RS --> AC
    RS --> SQL
    RQ --> AC
    RQ --> EA
    EA -->|pinned search| EI
    EI --> SQL
    EI --> VDB
    EA -->|outside DB transaction| MODEL
    MODEL --> PROVIDERS
    API -->|cursor + Last-Event-ID| UI
Loading

六个公开模块都有类型化边界。基础模块使用小型 command/query 接口;优化器为了让路由直接拿到精确返回类型,额外提供了命名明确的工作台命令与查询:

EvidenceIndex.command / query / search
EvidenceAgent.submit / inspect / follow
AgentControl.submit / inspect / execute / recover
AgentPolicy.submit / inspect / simulate
AgentPolicyOptimizer.submit / start / cancel / execute / recover
AgentPolicyOptimizer.start_next_round / retry_trial / fail_study / convert_to_draft
AgentPolicyOptimizer.list_* / inspect_* / export_comparison / create_from_template
AgentRunShare.submit / inspect

这让 SQL、Qdrant、RQ、SSE 和模型 provider 都被封装在稳定 seam 后面,便于替换、故障注入和 AI 辅助维护。完整设计见 V5 Spec 与 Implementation Plan。

五分钟本地启动

一键 demo(Docker,推荐)

Docker 可用时,从仓库根目录执行:

docker compose --profile demo up --build

首次启动会自动 seed 演示数据;打开 http://127.0.0.1:3000,API 在 http://127.0.0.1:8000。

这个 profile 会启动 backend、worker、frontend、Redis 与 Qdrant。停止并保留数据用 docker compose --profile demo down;清空演示数据用 docker compose --profile demo down -v。

手动启动(开发)

要求:Python 3.12、Node.js 20、Docker。

git clone https://github.com/DZH166/AI-Knowledge-OS-Pro.git
cd AI-Knowledge-OS-Pro
Copy-Item .env.example .env
Copy-Item backend/.env.example backend/.env
Copy-Item frontend/.env.local.example frontend/.env.local
docker compose up -d redis qdrant

后端:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r backend/requirements.txt
python -m alembic upgrade head
python -m uvicorn app.main:app --app-dir backend --reload --host 127.0.0.1 --port 8000

Agent / ingestion worker(另一个已激活虚拟环境的终端):

cd backend
python -m app.worker

Worker 同时消费 RQ 并派发 durable SQL outbox;只启动 Uvicorn 不会执行已排队的 Agent Run。

前端(第三个终端):

cd frontend
npm ci
$env:NEXT_PUBLIC_API_BASE_URL="http://127.0.0.1:8000"
npm run dev

打开:

  • 真实接口模式:http://127.0.0.1:3000/workbench
  • 明确标记的 Recording Demo:http://127.0.0.1:3000/workbench?demo=1
  • API 文档:http://127.0.0.1:8000/docs

真实模型、embedding、OCR 和转写需要在本地环境文件配置 provider;缺少配置时系统返回明确错误,不静默生成假结果。

关键 API

Purpose Endpoint
创建/列出 Run POST/GET /api/v1/evidence-runs
读取 Run projection GET /api/v1/evidence-runs/{run_id}
人工决定与取消 POST /api/v1/evidence-runs/{run_id}/commands
可恢复事件流 GET /api/v1/evidence-runs/{run_id}/stream
运行轨迹与投影重放 GET /api/v1/evidence-runs/{run_id}/trace
存储完整性与版本台账自检 GET /api/system/storage-health
启动/列出固定评测 POST/GET /api/v1/agent-evaluations
评测详情与对比 GET /api/v1/agent-evaluations/{id}、/compare
Artifact catalog/detail GET /api/v1/artifacts、/{artifact_id}
Evidence detail GET /api/v1/evidence/{evidence_id}
优化实验与工作台 POST/GET /api/v1/optimizer/studies、/{study_id}/overview
Trial 比较与草稿转换 POST /api/v1/optimizer/studies/{study_id}/export-comparison、/convert-draft
Run 只读分享 POST /api/v1/agent-runs/{run_id}/share、DELETE /api/v1/agent-runs/shared/{token}

SSE 只公开状态、计划、工具结果、证据关系与产物事件,不公开 chain-of-thought。

存储完整性与备份

证据资料库 页面直接显示存储自检结果:数据库完整性、外键、引用文件是否存在、大小/内容指纹、active revision 与 index 台账、孤儿上传文件。命令行入口同样可用:

python scripts/check_storage_integrity.py --deep-hash
python scripts/backup_storage.py --output backups/evidence-20261107.zip --label before-upgrade
python scripts/restore_storage.py --archive backups/evidence-20261107.zip --force

备份使用 SQLite 在线备份 API,归档内包含逐文件 SHA-256 清单并在创建后立即复核;恢复前会完整验证,且把旧数据库和旧上传目录保留为 .before-restore-<时间戳> 副本。能力边界见 存储完整性与备份。

最新全量审查(2026-11-10)与分优先级升级建议见 审查报告 和 升级路线图。

验证

python -m compileall backend/app scripts
python -m ruff check backend/app backend/tests scripts
python -m pytest backend/tests -q
python -m alembic heads
python -m alembic upgrade head
python scripts/evaluate_agentic_rag.py --mode demo --output docs/v5_agentic_rag/evaluation_report.json
python scripts/check_v5_acceptance.py
python scripts/check_storage_integrity.py

cd frontend
npm ci
npm run lint
npm run typecheck
npm run test:unit
npm run build
npm run test:e2e:strict
npm audit --omit=dev --audit-level=high

CI 运行后端完整回归与迁移、60 场景评测、前端 lint/unit/build/audit、Chromium Agent/citation E2E,以及 release archive 安全检查。

项目结构

backend/app/modules/evidence_index/   revision lifecycle、Saga、search、reconciler
backend/app/modules/evidence_agent/   state machine、controller、budget、journal
backend/app/modules/agent_control/    trace、replay、evaluation、comparison、triage
backend/app/modules/agent_policy/     version、adaptive decision、simulation、activation、rollback
backend/app/modules/agent_policy_optimizer/ offline experiment、observation-guided rounds、report、draft conversion
backend/app/modules/agent_run_share/  expiring read-only Run Trace sharing
backend/app/services/storage_integrity.py  read-only database/upload/revision audit
backend/app/services/storage_backup.py     consistent SQLite + uploads backup/restore
scripts/check_storage_integrity.py         CLI storage audit
scripts/backup_storage.py                  create or verify a backup archive
scripts/restore_storage.py                 verified restore with previous-state copies
backend/app/api/                      command/query/SSE adapters
backend/app/tasks/                    RQ one-slice workers
frontend/modules/evidence-agent/      runtime contracts、HTTP/SSE/Recording adapters
frontend/components/evidence-agent/   Workbench、Run、Evidence、Artifact product UI
frontend/components/agent-control/    Run Trace、Evaluation Studio、snapshot comparison
frontend/components/agent-policy/     Policy Lab、diff、simulation、release control
frontend/components/optimizer/        Study creation、rounds、metrics、recommendation、reports
evaluation/v5/                        fixed corpus and reviewed cases
docs/v5_agentic_rag/                  spec、plan、checklist、evaluation、acceptance

当前边界

  • 默认面向单用户本地工作区;多租户鉴权、配额与云部署不在 V5.7 范围。
  • SQLite 适合个人项目和演示,不代表生产级横向扩展方案。
  • 真实 provider 的答案质量、延迟和费用取决于你的配置;仓库中的固定报告不调用付费 API。
  • 可选真实 HTTP rerank Adapter 只有在 RERANK_API_KEY、RERANK_URL、RERANK_MODEL 三项完整时启用;默认环境和固定报告未配置,系统会诚实退化到 dense/sparse fusion。
  • Reconciler 能识别 missing vector 并标记 rebuild,但不会在没有原始 embedding 时凭空重建。
  • 代码仍保留 V4.x Developer Mode 页面用于兼容与工程诊断;核心产品路径已经收敛到四个一级入口。

简历表达

独立设计并实现“溯知 Evidence OS”,将多模态 RAG 升级为 evidence-native research agent。以 immutable revision/index/chunk provenance 保证引用可回放,通过 transactional outbox、checkpoint、idempotent command 与 execution fence 实现可恢复 Agent 执行;构建版本化 AgentPolicy、adaptive retrieval、counterfactual simulation 和离线检索策略优化器,以确定性 60 案例评测、Pareto/observation-guided 候选选择、人工激活门禁及真实 Redis/Qdrant/RQ/Chromium 流程控制上线与回滚。

面试时建议重点讲三件事:为什么 Agent 之前必须先修证据身份、如何避免取消后的迟到结果污染状态、为什么模型不能拥有 scope/permission/budget 的最终决定权。

名字

“溯知”强调从结论反向追溯到知识来源;Evidence OS 强调它不是聊天壳,而是一套围绕 evidence lifecycle、Agent execution 与 review artifact 组织的工作系统。英文定位统一为 Evidence-Native Research Agent。

License

MIT,见 LICENSE。

About

Evidence-native RAG/Agent research workspace: immutable citations, durable execution, hybrid retrieval and storage integrity.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages