Almanac Metrics Blueprint
External Console Integration · Draft 0.1

把知识能力，变成可复算的看板

面向外部 Console 的指标蓝图：从知识供给、加工可用、检索消费，一直到回答价值和权限安全。所有指标按“现成可算、代理口径、需要补埋点”分层，避免展示层直接依赖底层表或演示假数据。

Audience
外部 AIInsight / AiConsole
Scope
个人 · 受管目录 · 平台
Evidence
当前仓库 + Issue #18
Status
设计建议，未实施
01 · Business spine

一条指标链，五个业务阶段

外部 Console 不应只做接口 QPS 大盘。Almanac 的核心价值在于“知识能否及时进入系统、是否可检索、是否被使用、是否解决问题，以及整个过程是否安全”。

知识供给

目录、知识库、逻辑文档、版本与内容类型。

事实数据已具备
加工可用

同步、解析、切片、向量化、图谱与发布。

任务数据已具备
检索消费

用户、入口、请求、空结果、命中文档与耗时。

事件数据已具备
回答价值

可信、解决、反馈、正确拒答与问题闭环。

缺任务结果事件
权限安全

ACL 事实、重建健康、授权拒绝与越权暴露。

事实有，决策事件缺
02 · First release

首期六项真实指标

这六项可以由当前 PostgreSQL 事实聚合。首页建议只放核心卡片；失败文档、卡死任务、ACL 注册和权限重建积压作为红色护栏单独告警。

按数据成熟度筛选

M-01 · ADOPTION

检索 WAU

近 7 日 count(distinct user_id)

说明 仅代表发生过检索的用户数据源 kp_retrieval_events维度 时间、入口
现成可算
M-02 · DEMAND

检索请求数

时间窗内已记录检索事件总数

说明 不等于稳定 task 数数据源 kp_retrieval_events维度 时间、入口、用户
现成可算
M-03 · EVIDENCE

已记录检索非空率

已记录事件内 success / (success + empty)

限制 best-effort 写入，异常与提前拒绝可能缺失数据源 retrieval status下钻 当前仅入口；KB / 目录需补 effective_scope
现成可算
M-04 · INVENTORY

PG 可检索候选数

活跃 KB + 当前有效源文档 + KB 文档未删除且 enabled + published / completed

说明 仅 PG 就绪代理，不校验向量索引漂移数据源 documents + kp_kb_docs下钻 目录、KB、类型
代理口径
M-05 · PIPELINE

加工成功率

成功终态 /（成功终态 + 失败终态）

排除 cancelled、superseded数据源 kp_process_runs下钻 operation、step
现成可算
M-06 · FRESHNESS

入库时延 P95

p95(finished_at - created_at)

拆分 排队时延 + 执行时延数据源 process runs / steps限制 不是真实源端 SLA
代理口径
03 · Role-aware views

三类用户，三种看板

个性化不是前端隐藏几个卡片，而是服务端按调用者解析 self、managed scope 和 platform scope。任何明细下钻都要再次校验当前 ACL。

VIEW 01

个人使用

回答“我用得怎么样、哪些问题还没有解决”。

  • 有效任务、可信解决、未解决任务
  • 常用知识来源与任务模式
  • 本人历史、引用、反馈、重新提问
  • 总响应 P95 与反馈覆盖率
范围：仅本人任务；已撤权来源只保留聚合，不展示标题与正文。
VIEW 02

知识运营

回答“目录里的知识是否健康、缺什么、该治理什么”。

  • 范围内 WAU、非空证据率、命中覆盖率
  • 同步覆盖、加工失败、陈旧高频文档
  • 空问题聚类与知识缺口治理队列
  • 目录 → KB → 文档的逐层下钻
范围：服务端解析可管理目录子树，不只认共享根目录。
VIEW 03

平台运营

回答“全平台的价值、稳定性、成本与安全状态”。

  • 可信解决、WAU、新鲜度 SLA、成本
  • 服务错误、总响应 P95、队列 lag
  • 模型与供应商使用、成本结构
  • 正常拒绝和越权暴露分栏
范围：授权租户或全平台聚合，默认不暴露问题正文。
04 · Dimension model

统一的分析维度

维度先统一，指标才能跨页面复用。组织、场景和任务结果是当前最需要补齐的三类字段。

统一分析维度、用途与当前数据状态
维度建议字段典型用途当前状态
时间hour / day / week / month / timezone趋势、环比、SLA、完整水位已具备
组织范围tenant、组织、部门、角色租户运营、组织对比、权限隔离部分具备；tenant / 部门未贯通
知识范围主目录、子目录、KB、稳定文档内容健康、使用归因、治理下钻ID 具备；历史目录映射会漂移
内容TXT/QA、file_ext、chunk_strategy、status类型分布、加工质量、失败分析已具备
场景入口Agent、search、API、MCP、task_type渠道使用、任务模式、场景价值入口有，任务类型缺
检索结果success/empty、result_count、source、rank非空率、来源分布、Top 内容已具备
加工过程operation、step、status、retry、duration成功率、积压、卡死、失败归因已具备
质量结果trusted、resolved、feedback、refusal_reason可信解决、反馈、正确拒答需要事件
平台运行env、service、version、model、provider稳定性、成本、版本对比仅日志/配置占位
05 · Drill-down catalog

二级下钻指标目录

首页只回答“怎么样”；二级页面负责解释“为什么”。以下指标适合作为知识运营和平台运营的下钻目录。

知识供给与内容健康

判断知识库存、覆盖、更新与利用是否健康。

目录同步覆盖率已进入活跃 KB 的逻辑文档 / 子树活跃文档
可算
文档命中覆盖率被返回过的去重文档 / 可检索文档
可算
长期未使用文档仅当事件观察窗 ≥ 90 天时计算；否则返回 unknown
观察窗限制
陈旧高频文档超过 90/180 天未更新且近期高频命中
平台时间代理
内容类型与容量按 file_ext、knowledge_type、chunk_strategy
可算

检索使用与知识效果

判断用户是否找到证据、哪些知识真正被使用。

人均检索次数请求数 / 活跃检索用户数
可算
平均返回文档数avg(result_count)
可算
入口占比retrieval_query / knowledge_search / future channels
可算
热门知识与集中度Top KB、稳定文档与 Top10 占比
可算
热门目录当前 folder_id 映射代理；事件时目录快照或 SCD 落地后再提供历史归因
当前映射代理
知识缺口候选重复空请求 + 脱敏后的问题聚类
需增强事件流

同步与加工健康

判断知识从上传到可检索的链路是否稳定。

批次完成率completed / 全部终态批次
可算
排队 / 执行 P95started-created / finished-started
可算
重试率与步骤失败按 parse、clean、chunk、vectorize、graph
可算
当前积压与卡死非终态数量、最大年龄、无心跳任务
可算
图谱降级文档索引成功但 graph_extract 失败
可算

权限与安全治理

区分授权事实、运行健康与真实访问决策。

目录 Owner 完整率活跃 folder 节点中 owner_principal_key 非空比例；Owner 是 resource_node 事实，不是 grant
可算
权限索引层级事实分布effective index 按 tenant / resource / principal / tier 去重；不是用户最终权限分布
可算
CREATE_SUB 显式本地授权数活跃目录上未过期的 local allow grant，action=create_sub；该显式 action 不向后代继承；也不等于有效可创建主体数，MANAGE 仍可能隐含该能力
可算
重建 / outbox 积压状态、失败率和最老任务年龄
可算
实际拒绝 / 越权暴露authz.decision 与专项安全校验
需新增事件
06 · North-star metrics

目标态：可信解决体系

Issue #18 的五项指标适合作为最终首页，但只有在 task、quality、feedback、freshness、usage 事件齐全后，才能从事件明细复算。

最终首页五项

所有指标必须带版本、完整水位和清晰的分子分母。

  1. 可信解决任务数distinct task_id where trusted=true and resolved=true
  2. 可信解决率可信且已解决任务 / 有效任务
  3. 周活跃用户 WAU有效任务中的 7 日去重用户
  4. 数据新鲜度与 SLA 达标率count(searchable_at - source_updated_at ≤ target) / eligible content；同时报告 P95 时延
  5. 单次可信解决成本模型与检索成本 / 可信解决任务数

最小事件模型

与 Issue #18 保持一致：task_id 贯穿一个用户目标；turn_id 表示一次外部请求或用户回合；每次检索、模型或工具调用使用独立 interaction_id；event_id 用于事件幂等。

task.startedanswer.completedquality.checkedtask.feedbacksource.updatedcontent.searchablemodel.usageauthz.decision
公共字段event_idoccurred_attask_idturn_idinteraction_idtrace_idtenant_idaccount_idscenario_idkb_idstatuslatency_msschema_version
07 · Data contract

对外供数架构

业务指标与运行指标分流：高基数业务事实进入事件库和聚合层，低基数运行指标进入时序平台。外部 Console 不直接读生产业务库。

业务事实

资产、KB 文档、process runs / steps、retrieval events、ACL audit。

运行遥测

HTTP、依赖调用、队列 lag、worker 并发、错误与 trace。

规划：事件库 / OLAP / 物化汇总

小时与日粒度；统一指标口径、快照、去重、完整水位和 ACL 范围。

规划：OTLP → TSDB

吞吐、错误率、P95/P99 和基础设施运行指标。

规划：Metrics Provider API

GET /metrics/catalog
POST /metrics/query:batch

对接目标：External Console

首页、趋势、维度拆分、治理队列和受控明细下钻。

每次响应携带 as_of、complete_through、partial、metric_version。库存类指标必须做小时或每日快照，否则无法还原历史状态。

LAYER 01 · DATA SOURCES

当前业务事实仍以各服务 PostgreSQL 表为权威来源；新增价值指标通过版本化领域事件补齐。

资产事实

目录、逻辑文档、版本、文件类型、大小与生命周期。

asset_folderdocumentsasset_file
知识加工

知识库文档、同步批次、流水线运行、步骤、错误与耗时。

kp_kb_docskp_batch_jobskp_process_runskp_process_steps
检索使用

用户检索事件和最终返回给用户的文档快照。

kp_retrieval_eventskp_retrieval_event_documents
权限治理

Owner 资源事实、显式授权、最终权限索引、变更审计、事件 outbox 与异步重建任务。

resource_nodeaccess_granteffective_resource_permission_indexpermission_audit_logpermission_event_outboxpermission_rebuild_task
新增价值事件

任务、回答质量、反馈、新鲜度、模型用量与真实授权决策。

task.*quality.*model.usageauthz.decision
LAYER 02 · COLLECTION & PROCESSING

采集、标准化、事实建模和汇总分层处理；每一步都可重放、可校验、可观察。

STEP 01

采集

  • 首版通过日期 + cursor 增量读取现有 inner feed 或只读副本
  • 新增业务事件与业务事务同提交到 transactional outbox
  • HTTP、模型与 worker 运行数据通过 OTLP 采集
STEP 02

校验与标准化

  • 按 schema_version 校验必填字段与枚举
  • 以 event_id 幂等，task_id / turn_id / interaction_id / trace_id 关联
  • 服务端补 tenant、effective scope、场景和内容维度
  • 目录归因保存事件时 folder/path 快照，或使用 SCD 历史维表
  • 问题正文脱敏；外部默认只使用 hash 或聚类主题
STEP 03

事实建模

  • 检索 interaction 事实
  • 任务 outcome 与质量事实
  • 内容加工与新鲜度事实
  • 模型 usage 与授权 decision 事实
  • 时间、租户、范围、内容、场景、模型维表
STEP 04

聚合与完整水位

  • 小时增量汇总、每日快照
  • 处理迟到事件并按窗口回补
  • 维护 as_of / complete_through / partial
  • 支持按 metric_version 重算和审计
LAYER 03 · STORAGE

不同类型的数据进入不同存储；Redis 队列和应用日志不能充当业务指标事实库。

CURRENT · SYSTEM OF RECORD

业务 PostgreSQL

存：现有资产、知识、加工、检索和 ACL 权威事实。
原则：业务写入来源，不承载外部看板的大范围聚合查询。

PLANNED · EVENT & DETAIL

Reporting PG → OLAP

MVP：独立 reporting PostgreSQL 保存标准事件和事实表。
规模化：迁移到双方选定的 OLAP，或复用 AIInsight 已有数据平台，承载高基数分析。

PLANNED · METRIC MART

物化指标层

存：小时/日聚合、库存快照、指标分子分母、完整水位和版本。
用途：Metrics API 的唯一查询来源。

PLANNED · RUNTIME SERIES

AIInsight TSDB

存：吞吐、错误率、P95/P99、队列 lag、worker 并发与依赖健康。
限制：不放 user_id、task_id、doc_id。

LAYER 04 · EXTERNAL SERVING

浏览器只读取聚合指标；原始明细供服务间入仓或经授权下钻，不作为看板主查询接口。

业务指标：Metric Catalog + Batch Query

Catalog 固化口径和可用维度，Batch API 一次返回多项指标，避免页面逐卡请求。

POST /api/v1/insight/metrics/query:batch
{
  "metric_ids": [
    "retrieval_wau",
    "non_empty_evidence_rate",
    "searchable_document_count"
  ],
  "time_range": {
    "start": "2026-08-01T00:00:00+08:00",
    "end": "2026-08-31T23:59:59+08:00"
  },
  "granularity": "day",
  "group_by": ["entrypoint"],
  "scope": {"type": "managed_folder"}
}

统一返回：值、序列与可信元数据

以下为结构示意。scope 由服务端根据 service principal 或当前用户解析；即使请求携带 scope_id，也必须验证其管理权限。

{
  "data": [{
    "metric_id": "retrieval_wau",
    "value": 123,
    "series": [],
    "dimensions": {"entrypoint": "agent"}
  }],
  "meta": {
    "as_of": "2026-08-31T12:00:00+08:00",
    "complete_through": "2026-08-31T11:00:00+08:00",
    "partial": false,
    "metric_version": "1.0.0"
  }
}

原始增量：仅服务间使用

保留现有资产与召回 inner feed，用于首次回填、增量入仓和审计对账。

  • /asset/inner/assets：资产最新版本和变更
  • /knowledge/inner/retrieval-records：只含有命中的文档明细
  • 使用专用 service credential、私网路由和重叠窗口幂等 upsert
  • 不能把召回明细行数当作请求数

运行指标：OTLP / Remote Write

由 Almanac 采集侧推送到 AIInsight 管理的时序平台，Console 从平台侧 TSDB 读取。

  • HTTP 请求量、错误率、首字和总响应 P95/P99
  • 数据库、向量库、模型供应商依赖耗时与错误
  • Redis Stream lag、pending、active、worker 并发
  • 低基数标签：env、service、route、status、version、model
08 · Release blockers

上线前的安全与口径门禁

这些问题不解决，外部看板即使能展示，也可能发生越权、重复计数或把代理数据误报为业务价值。

P0 · DATA ACCESS

原始 inner 接口不能直连浏览器

现有召回明细包含请求人、文档名、目录和 KB；当前只有身份认证，没有专门的 metrics scope、tenant 或目录范围校验。只允许 service credential 入仓，浏览器调用聚合 API。

P0 · COUNTING

命中明细不能直接统计请求量

召回接口一行代表一个命中文档，必须按 distinct request_id 计数；空结果完全不会返回，因此不能从该接口计算完整 WAU 或无答案率。

P0 · IDEMPOTENCY

request_id 不能充当唯一调用事件

当前 request_id 是唯一键；同一 Agent 请求触发多次检索时，后续事件可能因冲突被 best-effort 丢弃。应新增独立 event_id / interaction_id；request_id 映射 turn_id，只作请求关联而不作唯一事件键。

P0 · ACL SEMANTICS

三层事实不能跨层合并

最终鉴权必须先汇总调用者全部主体，再按资源选择完整最高层级 owner > local > inherited；仅在选中层内处理 deny / allow。索引层级分布不能冒充用户最终权限分布。

P0 · SEMANTICS

占位字段和演示数据不得上线

现有使用分析页面全部数字硬编码；call_count、accuracy_rate 没有真实维护链路。“非空证据”不能命名为“回答准确”或“问题解决”。

09 · Delivery plan

三阶段实施路线

先把能复算的事实接出去，再补价值事件和运营闭环，避免第一版同时建设全量埋点、数仓和复杂前端。

真实首版

建立物化汇总和聚合 API，发布六项首期指标。

  • 检索 WAU / 请求 / 非空证据率
  • 可检索文档、加工成功率、入库 P95
  • service principal + metrics:read
  • 真实 loading / empty / error / partial 状态

可信解决

落地八类事件与统一任务口径。

  • task_id / turn_id / interaction_id / trace_id
  • 质量、反馈、模型 usage、新鲜度
  • Issue #18 五项核心指标
  • 测试数据复算与汇总一致性验证

运营闭环

建设目录治理、知识缺口与成本优化能力。

  • 目录 → KB → 文档下钻
  • 问题聚类与治理待办
  • SLA 告警、异常检测、趋势预测
  • 预算权限、成本归因和优化建议
10 · Evidence map

现有依据与数据源

本页不展示任何真实生产数字；结论来自当前仓库的模型、接口与开放 Issue。

设计基线GitLab Issue #18 · 核心指标口径与埋点链路打开 Issue
外部明细接口docs/api/inner-interfaces.md可作入仓源，不宜直连看板
检索事件libs/almanac_infra/.../models/retrieval_events.py请求与命中文档事实
加工任务models/kb_docs.py · process_runs.py · process_steps.py状态、步骤、耗时与错误
现有前端原型apps/web/src/App.tsx · PersonalUsageAnalytics全部为演示数据