TavernHeadless

主题

Operation Logs（操作日志） ​

Operation Log 记录一次用户、LLM 或系统操作留下的审计信息。它保存操作的来源、动作、目标、引用和摘要 diff。

它不是运行时真相源。Floor 快照、资产版本、工具执行记录、Session State mutation 仍然由各自的表保存。

什么时候需要看这页 ​

  • 你要追踪一个会话被谁改过
  • 你要查看某个楼层由哪个 run 提交
  • 你要按目标、动作、请求 ID 查询审计记录
  • 你要做回滚、排查或治理审计

先理解几个词 ​

词这里的意思
actor操作者，可以是用户、LLM 或系统
source操作来源，例如 HTTP 请求或 LLM run
target被操作的对象，例如 session、floor、preset
ref对业务对象的引用快照，只保存必要字段
diffbefore_ref 和 after_ref 之间的摘要差异

安全边界 ​

Operation Log 不保存完整提示词、完整用户消息、完整 LLM 输出、工具参数、工具结果或模型密钥。

写入日志时应只保存引用和摘要。敏感字段会被摘要 diff 默认遮蔽。

例如，POST /floors/:id/branch 成功创建 checkout 分支时会写入 checkout_branch，目标类型是 session_branch，引用中只包含分支 ID、来源楼层 ID 和资产绑定 ID / 版本 ID。显式 reset 会写入 reset_branch。资产版本回滚会写入 rollback_preset、rollback_worldbook 或 rollback_regex_profile。VC Tag 创建和删除会写入 create_tag / delete_tag。

备份与恢复 ​

Operation Log 是审计数据。核心资产恢复不会用它重放业务状态，也不会要求备份文件必须包含日志。

POST /backup/jobs/export 的 include_operation_logs 有三个取值：

值说明
none默认值，不导出 Operation Log
referenced只导出被资产版本或 VC Tag 的 created_by_operation_id 引用到的日志
selected_scope导出与已导出 session、floor、资产、资产版本、VC Tag 相关的日志

恢复时会为日志生成新 id。同一个 operation_group_id 会映射到同一个新分组 ID。request_id 会清空，原始 operation_log_id、operation_group_id、request_id 和 run_id 会保存在 metadata.restore.source。

列出操作日志 ​

http
GET /operation-logs

查询参数 ​

参数类型说明
session_idstring按会话过滤
floor_idstring按楼层过滤
run_idstring按 run 过滤
target_typestring按目标类型过滤，例如 session
target_idstring按目标 ID 过滤
actionstring按动作过滤，例如 update_session
actor_typestring按操作者类型过滤，例如 user
statusstringsucceeded / failed / denied / cancelled
operation_group_idstring按操作分组过滤
request_idstring按请求 ID 过滤
limitinteger每页条数，默认 50，最大 200
offsetinteger偏移量，默认 0
sort_orderstringasc / desc，默认 desc

响应 200 ​

json
{
  "data": [
    {
      "id": "op_001",
      "account_id": "default-admin",
      "actor_type": "user",
      "actor_id": "default-admin",
      "operation_group_id": null,
      "request_id": "req-001",
      "source_type": "http",
      "action": "update_session",
      "status": "succeeded",
      "session_id": "sess_001",
      "branch_id": null,
      "floor_id": null,
      "run_id": null,
      "target_type": "session",
      "target_id": "sess_001",
      "before_ref": {
        "session_id": "sess_001",
        "title": "Old title"
      },
      "after_ref": {
        "session_id": "sess_001",
        "title": "New title"
      },
      "diff": {
        "mode": "summary",
        "total_changes": 1,
        "changes": [
          {
            "path": "title",
            "change_type": "changed"
          }
        ],
        "truncated": false,
        "max_bytes": 16000
      },
      "metadata": {
        "route": "PATCH /sessions/:id"
      },
      "created_at": 1735689600000
    }
  ],
  "meta": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "has_more": false,
    "sort_by": "created_at",
    "sort_order": "desc"
  }
}

列出某个会话的操作日志 ​

http
GET /sessions/:id/operation-logs

路径参数 ​

参数类型说明
idstring会话 ID

查询参数 ​

同 GET /operation-logs，但 session_id 会由路径参数决定。

响应 200 ​

返回结构同 GET /operation-logs。

错误 ​

状态码code说明
404not_found会话不存在，或不属于当前账号

列出某个楼层的操作日志 ​

http
GET /floors/:id/operation-logs

路径参数 ​

参数类型说明
idstring楼层 ID

查询参数 ​

同 GET /operation-logs，但 floor_id 会由路径参数决定。

响应 200 ​

返回结构同 GET /operation-logs。

错误 ​

状态码code说明
404not_found楼层不存在，或不属于当前账号