AgentSight 数据与存储
AgentSight 采集到的一切都以 SQLite 数据库形式留在本机。Dashboard、CLI 和 HTTP API 只是同一批文件的三种 视图。
数据放在哪里
所有数据库位于 /var/log/sysak/.agentsight/，以私有 umask 创建，仅 root 可读。
| 文件 | 内容 |
|---|---|
genai_events.db | 主库：保存 LLM 调用及其 Agent 进程的定时 CPU/RSS 采样，含耗时、会话与对话 ID |
agentsight.db | 审计记录（LLM 调用与进程动作）以及 Token 消费聚合 |
interruption_events.db | 检测到的中断，含类型、严重级别与证据 |
optimization.db | Dashboard 优化分析的结果 |
trajectories.db | ATIF v1.7 轨迹，仅在开启 features.trajectory_collection 时存在 |
.agentsight-private/security.db | 安全事件、案例、证据与处置状态 |
.agentsight-private/enforcement.db | 拦截策略、违规记录与状态流转 |
.agentsight-private/reuse.db | 轨迹复用标签、人工决定、LLM verdict 与标签审计事件 |
.agentsight-private/causal.db | 持久化的因果归因 case |
.dashboard_token | Dashboard 访问令牌（64 位十六进制，仅 root 可读） |
optimization_config.json | 在 Dashboard 设置页填写的 LLM 配置（API Key 存于此） |
*.db-wal、*.db-shm | SQLite 预写日志与共享内存；属正常文件，干净退出时会做 checkpoint |
serve、dashboard、skill-metrics、audit、metrics、summary、interruption 支持用 --db
指向别的数据库文件，这也是浏览副本或归档的方式。tracer 自身始终写入默认目录。
serve --db <path>会让所有兄弟库都从--db所在目录解析——GenAI 事件、中断库、轨迹库以及 health checker 都跟着它走。私有的安全、拦截、复用与因果库从其.agentsight-private/子目录解析。 因此归档副本是隔离展示的，不会混入当前主机的数据。请把兄弟.db文件以及存在时的.agentsight-private/目录放在你传入的那个文件的同一目录下。裸相对路径--db name.db使用当前目录。
这些文件包含完整的提示词与模型回答，请按敏感数据对待：保持安装时的目录权限，往外拷贝时务必谨慎。
SQLite 为唯一活跃输出时会立即保存已经完成的调用。默认 Logtail 即使已注册，只要部署文件不存在 或 telemetry 已关闭，就不会增加 session 等待。如果之后才识别出 Agent 的会话，会同时更新已存储 的 session ID 与完整事件 JSON。FFI callback 和活跃的外部 exporter 仍在投递前等待 session 解析。 每次调用都会检查输出门控，因此启用或恢复 Logtail 后，后续调用会恢复该等待。
保留与容量上限
trajectories.db 通过 source_session_states 保存 Hermes 扫描指纹，按采集会话 ID、来源和
规范化数据库路径区分。该元数据在正文容量淘汰和采集器重启后仍保留，未变化的会话保持被淘汰状态，
直到源发生变化。可写打开旧库时自动建表，并从已有 Hermes 轨迹元数据补齐状态，不读取 ATIF 正文。
维护时清理源消息时间已过保留期或源文件已消失的状态；关闭按时间保留限制时，源库存在则保留状态。
不需要改变 JSON 配置版本，也不会修改源 Hermes 数据库。
SSE 调用超过采集字节上限或因连接容量被驱逐时，AgentSight 仅输出有界元数据，标记
incomplete=true、metadata_only=true 和 abandon_reason，不保留正文、消息或 token 用量；
字节超限还设置 truncated=true。容量驱逐跳过最近 5 秒活跃的在途调用，包括请求组装和等待响应阶段；
所有条目均受保护时，
拒绝新调用并标记 abandon_reason=capacity_rejected。HTTP/1 调用完成后保留不含 payload 的名额 5 秒，
供下一次 keep-alive 请求复用。活跃连接与保留名额合计不超过 connection_capacity；名额过期前可能拒绝新连接。
硬字节上限仍可回收活跃条目。有界标记会跳过该调用的
后续尾流，避免反复输出 incomplete 记录和驱逐其他连接。新请求或 HTTP 响应清除标记，
但容量拒绝的调用必须等到新请求到达才清除标记。标记可能因
容量限制被提前移除；定期维护按配置的连接软超时、硬超时和 60 秒三者中的最大值使标记过期。
硬超时移除仍允许迟到响应恢复为 response-only 证据。
schema v4 为每个 AgentSight 自有数据库统一配置 retention_days、max_db_size_mb 和
check_interval_secs：
| 存储 | 默认策略 | 清理覆盖范围 | 配置项 |
|---|---|---|---|
agentsight.db | 30 天、500 MiB、每 60 秒 | 完整：审计、Token、HTTP 与消费历史 | storage.primary |
genai_events.db | 30 天、200 MiB、每 60 秒 | 完整：GenAI 事件、资源采样与 evaluation run 共用这个物理库 | storage.genai |
interruption_events.db | 30 天、100 MiB、每 60 秒 | 完整的中断历史 | storage.interruptions |
trajectories.db | 30 天、500 MiB、每 300 秒 | 部分：清理轨迹正文，但保护近期文件和 Hermes 会话的指纹 | storage.trajectories |
optimization.db | 30 天、200 MiB、每 300 秒 | 完整的优化结果历史 | storage.optimization |
.agentsight-private/security.db | 30 天、200 MiB、每 3,600 秒 | 部分：清理终态案例图和无引用事件，保护活动案例图 | storage.security_audit |
.agentsight-private/reuse.db | 30 天、200 MiB、每 300 秒 | 部分：仅旧标签事件与未确认的纯自动标签 | storage.reuse |
.agentsight-private/causal.db | 30 天、200 MiB、每 300 秒 | 部分：淘汰最旧缓存，但至少保留最新一条 | storage.causal |
.agentsight-private/enforcement.db | 30 天、100 MiB、每 60 秒 | 部分：仅 violation 与终态 transition | storage.enforcement |
Tokenless 的 stats.db 会在状态 API 中列为外部存储。AgentSight 只读打开它，不执行生命周期治理；该文件
仍由 Tokenless 管理。
storage.max_total_size_mb 为 9 个 AgentSight 自有数据库设置总物理占用上限，默认值为 2200 MiB。设为
0 可关闭总量限制；启用时必须至少为 9 MiB，确保每个数据库至少保留可执行治理的 1 MiB 配额。
每项值为 0 时分别关闭按时间清理、按容量清理或定时检查。因而检查间隔为零时，即使保留天数和容量上限
非零，也不会自动治理该存储。旧 check_interval_inserts 字段已不支持；v4 之前的配置会按既有 schema
升级机制先备份再替换。
每个现有的长期运行 trace、serve、本地 trace 或本地 serve 进程最多启动一个轻量
sqlite-maintenance 线程，不会另起维护进程。该线程顺序执行本进程负责的所有数据库任务。trace 与
serve 同时覆盖同一物理文件时，通过 <db>.maintenance.lock 协调；拿到锁的进程会重新测量保留与容量
状态后再执行操作。
GenAI 维护使用独立于采集投递与查询的连接。删除分成小批次，并在批次之间释放写锁；数据库忙时，维护 延后到下一轮。WAL checkpoint 先通过 passive 模式复制页面，再尝试立即截断，避免长期读事务使维护 等待时阻塞采集写入。 采集写入或排队重试需要写锁时，维护不会再启动下一批删除，而是延后到后续调度轮次。
开启定时维护时，trace 进程将 primary 和 GenAI 的 WAL checkpoint 交给该维护线程，避免在采集提交时触发。
保留与容量检查之间约每秒执行一次 passive checkpoint；清理周期仍由 check_interval_secs 控制。
SQLite 的同步持久性设置保持原值。关闭定时维护时，采集连接保留自动 WAL checkpoint。
开启 runtime_limits.cpu_budget_percent 后，primary 与 GenAI 清理会在有界操作之间让出执行权，
并在后续调度继续。维护与采集投递共用 CPU 准入，既有保留和容量目标继续生效，但清理一轮可能耗时更长。
完成的采集记录遇到临时 SQLite 写锁冲突时，会留在现有 pending 队列中重试，与等待 session ID 的事件
共享 pending_genai_max_count 和 pending_genai_max_bytes_mb。重试不会向外部出口重复发送记录。
超出预算或永久写入失败会记录日志；agentsight_genai_sqlite_retry_total 按 queued、busy、stored、
over_budget、failed 区分排队、锁冲突、写入成功、预算拒绝和失败次数。
每次维护遵循同一顺序：
- 按各业务 Store 的 schema 安全规则，删除早于保留截止时间且允许淘汰的记录。
- 如果按时间删除改变了数据库，必须成功完成 WAL checkpoint 后才能继续。
- 仅在物理占用（database、WAL 与 SHM）超过上限时触发容量淘汰。
- 按最旧且允许淘汰的记录清理，每轮 checkpoint，直到逻辑占用降至上限的 90%。
总量分配排序同样计入 WAL 与 SHM，因此 WAL 较大的数据库可能在一轮中优先治理。该数据库会在淘汰前执行 checkpoint，后续轮次再按新的物理占用重新分配。
自动维护永远不执行 VACUUM。释放页保留在 freelist 中供后续写入复用，因此物理文件较大但逻辑占用在
目标内时仍属正常。如需向文件系统归还空间，请先停止服务，再在维护窗口手动执行
sudo sqlite3 /var/log/sysak/.agentsight/<db> 'VACUUM;'。
两个部分覆盖的存储会刻意保护持久决定与控制状态。复用库不会删除人工持有、已确认或已覆盖的标签；拦截库 会保护 binding、pending 或 indeterminate transition，以及 credential intent/snapshot 状态。因果条目是缓存， 被淘汰后再次请求可能重新触发付费归因计算。
容器部署请注意：这些保留语义只在数据目录持久化时才有意义。不挂卷时容器每次重启都会清空全部数据， 详见 容器与 Sidecar 的持久化一节。
Settings 页面通过 POST /api/storage/config 修改总量上限。使用配置文件启动的长期运行 trace、
serve、本地 trace 和本地 serve 进程都会在维护前重读有效配置，无需重启；本地进程未指定 --config
时不能持久化修改。配置文件缺失、未写完或无效时继续使用最近一次有效上限。页面还会展示物理/逻辑占用、
清理覆盖范围与维护 worker 状态。
通过 API 查看当前占用：
TOKEN=$(sudo cat /var/log/sysak/.agentsight/.dashboard_token)
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7396/api/storage/status \
| python3 -m json.tool
响应使用 schema version 3。每个存储都返回 availability、size、policy、coverage、size_state，以及包含
scheduled、worker_running、worker_heartbeat_unix_ms、last_attempt_unix_ms、
last_success_unix_ms、last_result、consecutive_failures、next_run_unix_ms 的 maintenance 对象。
轨迹、安全审计、复用、因果与拦截库会因受保护数据而报告 partial。运行态字段只描述提供当前响应的进程，
trace 负责的库显示未调度，并不能证明另一个 trace 进程没有运行。接口不返回数据库路径。
within_policy 只表示容量状态；worker 是否健康必须结合调度、heartbeat、尝试、结果与失败字段判断。
也可以直接检查目录：
sudo du -sh /var/log/sysak/.agentsight
sudo ls -la /var/log/sysak/.agentsight
清空数据
sudo systemctl stop agentsight.service
sudo rm -rf /var/log/sysak/.agentsight
sudo systemctl start agentsight.service
删掉目录也会删掉 Dashboard 令牌，下次启动会重新生成。如果想保留历史，先把目录拷到别处，之后用
agentsight serve --db /path/to/genai_events.db 浏览。
HTTP API
服务自己会给出路由清单，不用猜：
curl -s http://127.0.0.1:7396/api/docs | python3 -m json.tool
非本机请求需要令牌：
TOKEN=$(sudo cat /var/log/sysak/.agentsight/.dashboard_token)
curl -s -H "Authorization: Bearer $TOKEN" http://<host>:7396/api/sessions
0.11 的端点分组：
| 分组 | 示例 | 用途 |
|---|---|---|
| 服务 | GET /health、GET /metrics、GET /api/docs | 存活探测、Prometheus 指标、路由清单（/health 与 /metrics 仅本机可访问） |
| 认证 | GET /api/auth/status、GET /api/auth/verify、POST /api/auth/login | 认证状态、能力列表、令牌换 cookie |
| 会话与调用 | GET /api/sessions、GET /api/sessions/{id}/traces、GET /api/sessions/{id}/resources、GET /api/traces/{id}、GET /api/conversations/{id}、POST /api/sessions/search | 会话列表、会话内对话摘要（以 conversation_id 为键）与进程资源、按 response_id 的单次调用详情、语义搜索 |
| 指标 | GET /api/timeseries、GET /api/metrics/latency、GET /api/agent-names | Token 时序、延迟分位、Agent 过滤项 |
| 中断 | GET /api/interruptions、/count、/stats、/session-counts、/conversation-counts、POST /api/interruptions/{id}/resolve | 排查与关闭 |
| Agent 健康 | GET /api/agent-health、DELETE /api/agent-health/{pid}、POST /api/agent-health/{pid}/restart | 实时状态与恢复动作 |
| Tokenless 记录 | POST /api/tokenless/refresh、GET /api/tokenless/records、GET /api/tokenless/records/{cache_id} | 刷新已保存统计、列出元数据和读取详情；内容需显式指定 include_content=true。三条路由即使来自 loopback 也需要 Dashboard 凭据 |
| Token 节省 | GET /api/token-savings、GET /api/token-savings/session/{id} | Tokenless 节省量 |
| ATIF 导出 | GET /api/export/atif/session/{id}（还有 trace、conversation） | 轨迹导出 |
| 轨迹 | GET /api/trajectories、/filters、/steps、/{session_id} | 已采集轨迹。列表支持可选的 label、exclude_label、human_backed 过滤；label 是逗号分隔的有效标签，例如 good,bad |
| 复用标签 | POST /api/reuse/triage、GET /api/reuse/sessions、POST /api/reuse/sessions/{session_id}/label、POST /api/reuse/sessions/labels:batch-confirm、GET /api/reuse/label-stats、POST /api/reuse/judge | 规则分诊与人工标签决定。judge 需要 features.reuse_llm_judge=true 与已配置的 LLM 凭据，并会产生付费模型调用 |
| 偏好 | GET /api/preferences、/export、/turns | 用户偏好分析、Markdown 导出，以及供 Agent 侧推理使用的用户原始轮次 |
| 存储 | GET /api/storage/status、POST /api/storage/config | schema v3 的总量上限、容量、覆盖范围与维护 worker 状态；存在配置文件时可通过 POST 持久化总量上限 |
| Skill 指标 | GET /api/skill-metrics、/downloads、/loads、/usage-ratio、/distribution、/hotness | Skill 采纳情况 |
| 优化分析 | POST /api/optimize/sessions/{id}/{dimension}、GET /api/optimize/results、GET 与 POST /api/optimize/config | LLM 辅助分析 |
| 质量与归因 | POST /api/grader/evaluate、GET /api/grader/latest、POST /api/causal-attribution | 会话质量评分、根因归因 |
| 安全与审计 | GET /api/security/*、GET /api/audit/*、POST /api/audit/cases/{id}/review | 装了 agent-sec-core 时可用 |
| 拦截 | GET /api/enforcement/health、POST /api/enforcement/bindings、GET /api/enforcement/violations | 装了 enforcer 时可用；写操作始终要求令牌 |
时间范围参数是纳秒时间戳（start_ns、end_ns），与 CLI 的 --last 窗口对应。
# 最近一小时的会话
NOW=$(date +%s%N); AGO=$((NOW - 3600000000000))
curl -s "http://127.0.0.1:7396/api/sessions?start_ns=$AGO&end_ns=$NOW" | python3 -m json.tool | head
获取某个 Session 的原始 CPU/RSS 采样点和活动区间：
curl -s "http://127.0.0.1:7396/api/sessions/<SESSION_ID>/resources?max_points=2000" | python3 -m json.tool
每个采样点都是进程级数据，包含 Epoch 纳秒时间戳、PID、CPU 百分比和以字节计的 RSS 内存。对于多进程
Agent，Dashboard 会汇总该 Session 关联的所有 PID。这些数据表示 Session 运行时的进程环境，并非严格的
Session 资源归因：同一个共享 Agent 进程可能同时服务多个 Session。LLM 区间使用采集到的请求和响应时间；
Tool Call 区间从产生工具请求的 LLM 响应结束开始，到携带对应工具结果的下一次 LLM 请求开始为止。未被
LLM 调用或已匹配 Tool Call 覆盖的间隙会返回为 idle；无法匹配结果的 Tool Call 不会虚构结束时间。
Chrome Trace 中的进程输出
对于聚合的进程生命周期，Chrome Trace 只保留 stdout 和 stderr 的开头内容，每条流最多 64 KiB。 任一流达到上限后，其后续输出不再保留；另一条流仍可继续保留到自己的上限。若上限截断 UTF-8 字符， 则舍弃不完整的尾部。其他无效字节沿用有损文本解码。
Prometheus 指标
curl -s http://127.0.0.1:7396/metrics | head
# HELP agentsight_token_input_total Total input tokens consumed by agent (all-time)
# TYPE agentsight_token_input_total counter
agentsight_token_input_total{agent="CoshNG"} 100000
agentsight_token_input_total{agent="Cosh"} 50000
计数器按 Agent 维度、取累计值：agentsight_token_input_total、agentsight_token_output_total、
agentsight_token_total_total、agentsight_llm_requests_total。/metrics 只允许本机访问，因此请用
节点本地的 Prometheus agent 抓取，或者通过本机反向代理暴露。agentsight metrics 在命令行输出同样内容。
agentsight_http_sse_discarded_bytes_total{reason} 统计保留废弃 SSE 标记期间跳过的尾流字节。
结合 agentsight_http_conn_removed_total{reason,state} 可区分资源压力与正常完成。
Aggregator 阶段耗时包含 compact SSE 读取。
agentsight_http2_closed_stream_discarded_bytes_total 统计 HTTP/2 正常完成或因资源、协议问题终止后
跳过的 DATA payload 字节；trailer 仍更新 header 解码器。
轨迹导出（ATIF v1.7）
任意会话、对话或单次调用都能导出为自包含的 JSON 轨迹——Agent 元信息、步骤、消息、工具调用与 Token 汇总：
curl -s http://127.0.0.1:7396/api/export/atif/session/<SESSION_ID> > session.atif.json
Dashboard 的轨迹查看页通过下载 JSON 提供同一份文件，也能导入在别的机器上采集的轨迹。适合离线分析、 共享复现场景，或喂给评测流水线。
外部日志导出
AgentSight 可以把结构化事件写入文件，供外部日志采集器读取：
{
"runtime": { "sls_logtail_path": "/var/log/anolisa/agentsight/events.jsonl" },
"features": { "sls_logtail": true }
}
该路径支持运行期修改——设为 "" 即暂停导出。如果希望数据完全留在本机，保持默认即可。采集器侧的配置
（端点、凭证）不属于 AgentSight 的范围。
备份
sudo systemctl stop agentsight.service
sudo tar czf agentsight-data-$(date +%F).tar.gz -C /var/log/sysak .agentsight
sudo systemctl start agentsight.service
先停服务可以确保 WAL 已 checkpoint，归档内容才是一致的。
相关页面
- CLI 参考——用命令行查同一批数据
- Dashboard 指南——这些数据库之上的界面
- 配置——存储与保留相关开关
查询到的 Tokenless 统计数据保存在现有 GenAI store 的 genai_events.db 中。同一端点、
源 ID 和原始时间戳的重复查询更新元数据，保留显式获取的完整内容与原始源会话 ID。
这些副本遵循 storage.genai 的保留期限和容量清理策略，不修改 Tokenless 数据库。