主站对AGC请求头做特殊处理和记录 #246
2 Participants
Notifications
Due Date
No due date set.
Blocks
#271 主站对AGC请求头做特殊处理和记录
GenarrativeAI/Genarrative
Reference: GenarrativeAI/Genarrative#246
Reference in New Issue
Block a user
Delete Branch "feat/agc_call_rec"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
WIP: 添加客户端埋点统计 #225to WIP: 添加客户端埋点统计位置：
record_route_tracking_event_after_success 当前只判断：
resolve_route_tracking_spec(...)
should_record_route_tracking(status, &spec)
没有要求 client_marker == Some(TrackingClientMarker::Agc)。
而本分支新增了大量 route spec，例如：
所以，未携带 X-Genarrative-Client: agc 的普通网页请求，只要返回 2xx，也会新增 tracking event；区别只是 metadata 中没有 client 字段。
这会带来两个后果：
这与方案文档中“追加 AGC 标记，但不改变现有统计口径”的描述不完全一致：
需产品决策：是否只记录AGC请求？
审查 head sha f28e4b52e7fa218f1ddc05fef2183d49f5d1e094：未发现明确问题。
代码审查（head sha f28e4b52e7fa218f1ddc05fef2183d49f5d1e094）：未发现明确问题。已执行 api-server cargo check，并运行与 AGC 埋点相关的 15 个测试，全部通过。
代码审查（head sha 4d8a0603a0ccf2809e005d957f4b098fc5845653）：未发现明确问题。基于 base
025f627297的真实 diff 审查已完成；干净 worktree 中执行 cargo check --locked -p api-server -j 1 通过。代码审查（head sha 4d8a0603a0ccf2809e005d957f4b098fc5845653）：未发现明确问题。已审查 base
025f627297到当前 head 的真实 diff；并在干净 worktree 执行cargo check --locked -p api-server -j 1，编译通过。代码审查（head sha bea820da57bc280d11b722752a36aa9b14f0b496）：未发现明确问题。
代码审查（head sha bea820da57bc280d11b722752a36aa9b14f0b496）：未发现明确问题。已基于 base
025f627297执行真实 diff 审查；api-server tracking 相关测试 5 项全部通过。AGC 调用记录的最终落点是主站 SpacetimeDB 的
tracking_event表，不是在 AGC 客户端本地单独建表。链路大致是：
表中的核心字段包括：
AGC 标识放在
metadata_json里，例如：相关代码位置：
tracking_event表定义：profile.rs需要区分两种写入路径：
默认先写入 api-server 本机的临时 outbox：
文件是 NDJSON 格式，通常会出现：
后台 worker 批量调用
record_tracking_events_and_return写入tracking_event。成功入库后对应 sealed 文件会被删除。因此这个目录只是可靠投递缓冲，不是最终数据存储。例如资产详细事件、登录事件或其他显式 tracking 事件，会直接调用
record_tracking_event_and_return写入 SpacetimeDB；如果 outbox 不可用，普通路由事件也会回退到同步直写。写入
tracking_event后，SpacetimeDB 还会同步更新tracking_daily_stat，它是按事件和业务日聚合的统计表；原始调用记录仍然在tracking_event。后台读取入口是：
后台查询实际执行的是：
所以目前查看 AGC 调用记录时，重点是查看
tracking_event.metadata_json中是否存在：目前后台接口支持按事件 key、用户、scope 和日期筛选，但还没有单独的
client=agc查询参数；需要从返回的metadata_json中识别 AGC 标记。PR246 的核心是 Issue #225：主站侧把 AGC 调用记录下来，并补齐来源与用户归属。它依赖已经合入的 #226 提供
X-Genarrative-Client: agc，但 PR246 本身不负责给 AGC 客户端注入 Header。可以把它理解为：
一、PR246 具体做了什么
1. 在主站统一解析 AGC 标记
在主站 tracking middleware 中识别：
只有值经过空白裁剪后严格等于小写
agc才认为是 AGC 请求。Header 只用于判断“是否来自 AGC”，不参与身份认证，也不会根据 Header 推导用户 ID。
主要代码：
2. 给主站请求增加统一的 route tracking 记录
PR246 建立了主站请求的显式 route tracking spec，覆盖主要 AGC 调用类别：
/api/external/v1/*外部编辑器接口。记录条件不是“所有 HTTP 请求”，而是：
/admin/*等后台路由不进入用户 route tracking。因此这是“显式路由清单”，不是全局无差别记录。
3. 将
client: "agc"写入已有 tracking metadata典型记录会包含：
没有新增
agc_xxx的平行事件体系，而是复用现有 event key 和 metadata 结构。4. 补齐账号态用户归属
对于已经有认证主体的请求：
user_id= 登录用户；owner_user_id= 登录用户；scope_id= 登录用户。owner_user_id= API Key 对应 owner；user_id可以为空。对于登录成功请求，进入 handler 时还没有 access token extension，因此 PR246 增加了一个请求级的一次性主体传递：
涉及：
不会从响应体、Cookie 或 Header 解析用户身份，也不会把 token 写入埋点。
5. 修复资产读取请求的用户归属
/api/assets/read-url和/api/assets/read-bytes同时支持：所以不能直接改成强制 Bearer 鉴权。PR246 保留原来的可选鉴权逻辑：
结果是：
涉及：
6. 接通持久化链路
tracking event 的完整链路变成：
PR246 没有新增 tracking 表，而是复用现有
tracking_event。outbox 可以在 SpacetimeDB 暂时不可用时先落本地文件，之后由后台 flush。相关代码：
后台已有的 tracking readback 逻辑也增加了 AGC metadata、user/owner 字段的回归验证。
7. 保持
daily_login原有语义PR246 没有给
daily_login追加client: "agc"。原因是
daily_login是：的幂等事件。如果把 AGC 来源写进去，会出现：
因此：
daily_login继续只表示“用户当天完成过登录”；metadata.client = "agc"的登录 route event。8. 增加定向测试
覆盖内容包括：
build_routermiddleware 链路；二、做了和没做的区别
三、哪些事情 PR246 没有做
以下内容不属于 PR246：
不负责 AGC 客户端注入 Header
这是 #226 的职责，包括 TS
fetchClientHttp、Rust 主站 client factory、default headers、同源重定向边界等。不是所有主站 HTTP 请求都自动记录
只有显式登记在 route tracking spec 中的路由才会记录，且主要记录成功请求。
不记录 OSS、签名 URL、Provider、搜索、loopback 等非主站业务请求
这些不是主站用户行为 route tracking 的目标。
不回填历史 tracking 数据
旧记录缺少可信 AGC 来源或真实用户信息，PR246 不做猜测性补写。
不新增
agc_login_success事件继续复用现有登录 route event。
不修改认证协议
不改变 access token、refresh token、Cookie、登录响应体或鉴权流程。
不修改 SpacetimeDB schema
没有新增表、字段、migration 或 bindings。
不改后台 UI
主要是保证现有 tracking readback 能正确解析和展示新增 metadata、user、owner 信息。
四、当前 PR 中的附带维护性修复
当前分支相对
origin/master还包含两项与 Issue225 业务逻辑无关、但为 CI 修复所做的维护：server-rs/Cargo.toml中crates/platform-agent的 workspace exclude，修复 Rust workspace 格式检查；scripts/check-native-shells.mjs和vitest.config.ts中已经删除组件和测试的旧引用，修复 Native shell 检查。另外，当前分支 diff 中还存在若干
local-docs验收材料。它们不是运行时代码，也不应作为团队长期交接依据；正式可见的方案和决策已经写入：总结
PR246 的实际价值不是改变 AGC 的业务功能，而是补上主站侧的“来源识别—请求记录—用户归属—持久化—后台查询”闭环：
同时它保持了非 AGC 请求、匿名公开素材、External API Key、
daily_login和认证协议的原有边界。添加客户端埋点统计to 主站对AGC请求头做特殊处理和记录