feat: support agent governance

[kylewanginchina]

This PR is for:

• Agent
• Server

Support agent governance

• Code Change Description
• 
• 

Checklist

• Added unit test.

Backport to branches

[lzf575]

ingest 部分没问题

[xiaochaoren1]

translation.go 部分，只在 INT_ENUM_PEER_TAG 里加一下即可，其他地方不用改

[kylewanginchina]

translation.go 部分，只在 INT_ENUM_PEER_TAG 里加一下即可，其他地方不用改

@xiaochaoren1 意思是下图中红框的部分不需要，只需要在 INT_ENUM_PEER_TAG中加一下biz_type？

下面是codex的回复意见：

[kylewanginchina]

关于gprocess_id的情况说明：

进程启动初期，如果调用/v1/chat/completions以及执行文件操作等，gprocess_id会有一段时间为0，光process表有数据还不行，得等platformInfoTable那边缓存同步（周期是60s）了才会让gprocess_id正常，也就是gprocess_id会少关联一部分进程初始阶段的llm请求log以及操作事件。

目前遗留问题：

1. 无限量流重组支持上还存在问题

[kylewanginchina]

AI Agent Governance

背景

这组改动为 AI Agent / 智能体治理补齐了从 识别、进程归属、治理事件采集、数据落库 到
查询暴露 的完整链路，目标是让 reviewer 能够明确回答下面 5 个问题：

1. DeepFlow 如何识别一个进程是 AI Agent。
2. AI Agent 的 biz_type、root_pid、gprocess_id 如何在子进程 / 孙进程场景下保持稳定。
3. 哪些治理事件会被采集，以及它们最终落到哪些表。
4. 上层查询如何拿到这些字段与表。
5. 为了让这套能力可上线，过程中修了哪些正确性、兼容性和噪声问题。

变更范围

deepflow（开源侧）

• 53 commits
• 120 files changed
• 3998 insertions
• 174 deletions

deepflow-core（EE / 联动依赖侧）

• 28 commits
• 25 files changed
• 1754 insertions
• 688 deletions

Reviewer Guide

建议按下面顺序评审，这样最容易建立全局上下文：

1. AI Agent 配置与识别
   • 看 AI Agent 配置项是如何引入的
   • 看 HTTP parser 如何命中 AI endpoint
   • 看 http_endpoint_disabled 与 AI endpoint 的关系
2. AI Agent 注册表与进程归属
   • 看 EE 侧 AiAgentRegistry
   • 看 child / thread / exec / proxy 场景如何处理
   • 看 root_pid / biz_type 如何稳定传播
3. eBPF 与 ProcEvent 数据面
   • 看 file I/O、file meta、permission、proc lifecycle 事件是怎么采的
   • 看 ProcEvent protobuf 是如何扩展的
4. Server 落库与新事件表
   • 看 decoder 如何路由事件
   • 看 4 张新表的字段与 reducer 逻辑
   • 看 .1s/.1s_mv 聚合为什么要关闭
5. Querier 暴露与数据源接入
   • 看新的 metrics / tag descriptions
   • 看 gprocess.biz_type 查询翻译
   • 看 data_source 默认记录注册
6. 收尾修复
   • 看 reviewer feedback 修复
   • 看 multi-controller / non-Linux / log noise / build warning 等兼容性处理

核心修改说明

1. 新增 AI Agent 配置与识别入口

这一部分的目标，是让 AI Agent 成为一个可配置、可识别、可调参的能力，而不是写死在解析器里的特殊分
支。

主要变化：

• 新增 inputs.proc.ai_agent 配置树，支持：
  • http_endpoints
  • max_payload_size
  • file_io_enabled
• 在 HTTP parser 中增加 AI endpoint 命中逻辑，命中后可把对应进程标记为 AI Agent。
• 默认 endpoint 覆盖常见 OpenAI 风格 API，包括：
  • /v1/chat/completions
  • /v1/embeddings
  • /v1/responses
• 修正了 http_endpoint_disabled=true 时 AI Agent 识别被误关掉的问题。
  • 现在普通 http_endpoint 提取开关只控制普通 endpoint 逻辑，不再屏蔽 AI endpoint 识别。

review 价值：

• 这一组提交定义了“什么叫 AI Agent”。
• 后续所有 biz_type、root_pid、治理事件，都是建立在这一步识别成功之上的。

---

2. 引入 EE 侧 AiAgentRegistry，稳定管理 AI Agent 进程状态

这一部分的目标，是把 AI Agent 的“注册 / 查询 / BPF map 同步 / 继承 / 回溯”从临时逻辑提升为一个稳定
的注册表能力。

主要变化：

• 在 deepflow-core/agent/crates/enterprise-utils 中实现 AiAgentRegistry。
• 支持：
  • 注册 / 查询 AI Agent PID
  • 同步到 BPF map
  • child 进程继承
  • thread fork 继承
  • root_pid 跟踪
  • 后续 endpoint hit 时重新对齐状态
  • 根据 socket role 区分真实 AI Agent 与代理进程
• 在 open-source 侧补了 stub，保证不开 enterprise feature 时也能编译。

review 价值：

• 这一组提交决定了 AI Agent 状态是不是“临时命中一次就丢”，还是“能被进程树稳定继承和追踪”。
• 也是 child / grandchild / exec 场景能够稳定归属的基础。

---

3. 将 AI Agent 的 biz_type 沿进程同步链路贯通

这一部分的目标，是让“AI Agent 身份”不只存在于 agent 运行时，而是进入 controller / process /
gprocess / querier 的统一元数据体系。

主要变化：

• 新增 BIZ_TYPE_AI_AGENT 常量。
• 在 agent 侧进程同步结构中加入 biz_type。
• 在 gRPC 消息中加入 biz_type：
  • message/agent.proto::ProcessInfo.biz_type
  • message/controller.proto::GenesisSyncProcess.biz_type
• 在 MySQL schema 中增加：
  • genesis_process.biz_type
  • process.biz_type
  • ch_gprocess.biz_type
• 在 process / gprocess 同步链路中保持 biz_type 的传播。
• 在 multi-controller 场景下修复 gprocess biz_type 同步。
• 在 querier 中增加 gprocess.biz_type 的查询翻译，并把相关 biz_type 展示改为枚举语义。

review 价值：

• 这组提交让 AI Agent 身份从“运行时判定结果”变成“可查询、可关联、可审计”的元数据。
• reviewer 可以重点看：
  • 标记何时写入
  • controller 何时保存
  • querier 如何暴露

---

4. 放宽 AI Agent 数据采集限制，保证大模型流量与治理数据可见

这一部分的目标，是避免 AI Agent 流量因为普通流量的限制策略而采集不完整。

主要变化：

• AI Agent 流量不再受普通 reassembly 限制。
• 协议推断完成后可以启用 reassembly。
• 对已经存在的 socket，在协议推断后也能重新启用 reassembly。
• 修复了 invalid socket info 场景下的 reasm bytes 问题。
• 将 reasm_bytes 继续向后透传到 eBPF merge / 下游逻辑。
• 子进程 file I/O 事件不再被 collect_mode 错误过滤。

review 价值：

• 如果这部分不成立，后面的 AI endpoint 命中、大 payload、文件治理事件很容易“不识别”或“只采到一
  半”。

---

5. 扩展 eBPF / ProcEvent 数据面，覆盖治理事件

这一部分的目标，是让 AI Agent 治理不只看到“请求了什么”，还要看到“文件做了什么、权限怎么改了、进程
怎么派生了”。

主要变化：

• raw file I/O 增加 access_permission。
• 扩展 message/metric.proto：
  • IoEventData.access_permission
  • EventType.FileOpEvent
  • EventType.PermOpEvent
  • EventType.ProcLifecycleEvent
  • FileOpEventData
  • PermOpEventData
  • ProcLifecycleEventData
  • ProcEvent.file_op_event_data
  • ProcEvent.perm_op_event_data
  • ProcEvent.proc_lifecycle_event_data
  • ProcEvent.ai_agent_root_pid
• 增加 / 对齐的 hook 包括：
  • file create / delete / chmod / chown
  • setuid / setgid / setreuid / setregid
  • fork / exec / exit
• 修复治理事件输出接入 __socket_data pipeline 的格式兼容性。
• 统一 file op 输出结构，便于 server 侧按统一模型解码。

review 价值：

• 这组提交定义了“治理事件的数据合同”。
• reviewer 可重点看：
  • BPF event payload 与 protobuf 是否一一对应
  • 事件含义是否足够支撑审计和进程树展示

---

6. 新增治理事件拆表与聚合逻辑

这一部分的目标，是把治理事件从原始 file_event 中拆分出来，减少噪声、提升可查询性。

主要变化：

• 保持原始 event.file_event 不变，继续写 raw read/write。
• 新增 4 张事件表：
  • event.file_agg_event
  • event.file_mgmt_event
  • event.proc_perm_event
  • event.proc_ops_event
• file_agg_event
  • 将连续相同的 raw read/write 聚合为 1 行
  • 聚合 key 显式包含 agent_id + root_pid + gprocess_id
  • 同时带上 path / permission / thread / coroutine 等维度，避免误聚合
• file_mgmt_event
  • 承载 create / delete / chmod / chown
  • 对重复 create 噪声做生命周期内去重
  • 去重 key 显式包含 agent_id + root_pid + path
• proc_perm_event
  • 承载权限变化前后值
• proc_ops_event
  • 承载 pid / parent_pid / root_pid / uid / gid / cmdline / exec_path
  • 支持上层按父子关系恢复进程树

review 价值：

• 这部分是治理数据“可用性”的核心。
• reviewer 重点看：
  • 为什么保留 raw 表
  • 为什么要拆 4 张表
  • reducer key 是否足够隔离不同 agent / gprocess

---

7. 修复 gprocess_id 在 AI Agent 子孙进程场景下的稳定性

这一部分的目标，是解决 AI Agent 根进程、子进程、孙进程、exec 之后的进程在事件落库时容易拿不到正确
gprocess_id 的问题。

主要变化：

• 在 agent 侧事件中加入 ai_agent_root_pid。
• server decoder 增加 root pid cache。
• resolveGProcessID() 增加多级 fallback：
  • 先查当前 pid
  • 再查 cached root pid
  • 再查 ai_agent_root_pid
  • lifecycle 事件再回退到 parent_pid
• 修复 child / grandchild / exec 场景下的 gprocess 继承。
• 修复 proc lifecycle 事件的 bytes / fallback 细节问题。

review 价值：

• 如果这部分不成立，新表里的事件会出现大量 gprocess_id=0 或归属错乱。
• 也是 root_pid 真正能落到治理视图中的关键。

---

8. 完善查询层、默认数据源与可观测性元数据

这一部分的目标，是让新数据“真正能被查到”，而不是只写进去。

主要变化：

• 为 4 张新表注册默认 data_source。
• 为 4 张新表补齐 querier metrics descriptions。
• 为 4 张新表补齐 tag descriptions（含中英文）。
• 新增 biz_type 枚举描述。
• 支持 gprocess.biz_type 标签查询。
• 新增 deepflow-ctl 对 AI Agent process show 的调试支持。

review 价值：

• 这部分决定了 reviewer / 用户是否能在上层正确看到新数据。
• 如果只改写入层、不补 query metadata，这个 PR 的一半价值会丢掉。

---

9. review / 环境验证驱动的可靠性修复

这一部分的目标，是把功能从“能跑”提升到“能上线”。

主要变化：

• 修复：
  • borrow / import / unused variable
  • null statement / macro injection / tracepoint 对齐
  • BPF stack usage / pid_tgid 使用
  • socket_trace 中遗漏的 AI Agent 判断
  • proc scan hook 跨平台编译告警
• 调整：
  • log level
  • sync log noise
  • registry / BPF map sync debug logs
• 清理：
  • 过时 stub
  • 简单 endpoint 唯一性约束（为 root_pid/socket role 方案让路）
• 关闭 4 张新表的 1-second aggregation，避免 .1s/.1s_mv 创建失败。
• 将 reducer 作用域进一步限制到 agent + gpid。

review 价值：

• 这些提交虽然很多是 fix/chore，但直接决定了这套能力是否可维护、可构建、可部署。

对 reviewer 的关注点

功能正确性

• AI Agent 识别是否只在期望 endpoint 命中时触发。
• http_endpoint_disabled 下 AI Agent 是否仍然成立。
• 代理进程是否会被 socket role 正确降级。
• child / thread / exec / grandchild 场景下 root_pid 与 gprocess_id 是否稳定。

数据一致性

• biz_type 是否从 agent 一路同步到 process / ch_gprocess / querier。
• ProcEvent 新字段是否在 agent、message、server 三端一致。
• 新增 4 张事件表的字段、metrics、tag descriptions 是否完整对齐。
• reducer key 是否足够避免跨 agent / 跨 gprocess 误聚合。

运维与兼容性

• open-source stub 是否保证非 EE 构建不受影响。
• non-Linux build 是否已 guard。
• .1s aggregation 关闭后是否满足查询需求。
• 日志噪声是否可控。

已验证

Go tests

• querier/engine/clickhouse/tag
• querier/engine/clickhouse/metrics
• ingester/event/common
• ingester/datasource
• ingester/event/decoder
• ingester/event/event
• ingester/event/dbwriter
• controller/http/service

Rust tests

• cargo test --package deepflow-agent proc_lifecycle

环境验证

• 4 张新表创建 / 重建 / 查询通过
• file_mgmt_event create 噪声压缩通过
• .1s/.1s_mv 不再为新表创建
• root_pid 字段替换已生效
• file_agg_event 聚合作用域已收敛到 agent + root_pid + gprocess_id

[lzf575]

ingester 写入正常。目前看新增加的几个 event 表，支持单独设置保留时长，后续需要在页面验证确认下。

[yinjiping]

ai_agent 不受io_event的配置控制，这里存在一个需要注意的问题：

• 如果文件读写是微秒甚至纳秒级别，file读写事件可能会非常非常多，吃掉节点资源，所以这里是否需要一个ai_agent 文件读写的时间限制更好一些？

[kylewanginchina]

这个担忧我确认过，但本轮不按“增加时间限制/限流”修改。PRD 在智能体数据采集里明确要求“所有文件读写事件，无需对读写时延、读写时机做限制”，功能测试用例里也有 TC-EVT-001/002/003/004 对应覆盖。因此这里不能通过在 BPF 层增加时延门槛或限流来处理。后续如果需要控制资源，只能走不改变事件可见性的优化路径，例如更强聚合、传输/存储优化或统计告警。

[yinjiping]

datadump 部分

deepflow/agent/src/ebpf/user/socket.c

Line 3784 in 010323c

" CONTAINER_ID %s SOURCE %d COMM %s " \

SOURCE 目前只是数值标识，如果可以的话可以显示具体的事件名称。

[kylewanginchina]

这个建议合理，属于调试可读性优化。我先记录为后续增强项，本轮优先处理 correctness 和语义一致性问题。