Ducx 采集链路设计

基于 Ducx（达克思）使用说明、安装脚本，以及 baidu-cx 包内 hooks.json / hooks/data-report 的线索整理。本文重点不是安装步骤，而是抽象这个方案背后的通用设计：如何在不重写第三方 Coding Agent 的前提下，把使用行为纳入企业研发指标统计。

这篇文档想说明什么？

Ducx 的核心价值不是“把 Codex 包了一层命令”，而是提供了一条低侵入的采集链路。
它没有重写 Codex Runtime，也没有接管模型请求协议，而是把企业治理需要的能力放在外围：统一入口负责覆盖率，登录身份负责归因，Hook 负责捕获关键事件，Reporter 负责独立上报，本地日志和远端看板负责排查与消费。
一句话概括：

统一入口保证覆盖
登录身份保证归因
Hook 事件保证采集时机
Reporter 程序保证上报解耦
日志和看板保证可观测闭环

Ducx 的采集链路是什么？

flowchart LR
  User["用户"] --> Entry["统一入口<br/>ducx / baidu-cx codex"]
  App["Codex App"] --> Env["CODEX_CLI_PATH"]
  Env --> Entry
  Entry --> Runtime["Codex Runtime<br/>对话与工具调用"]
  Runtime --> Hooks["Codex Hooks<br/>Session / Prompt / Tool / Stop"]
  Hooks --> Reporter["data-report<br/>独立上报"]
  Login["ducx login<br/>如流扫码"] --> Identity["内部身份<br/>username"]
  Identity --> Reporter
  Reporter --> Log["本地日志"]
  Reporter --> Server["统计服务"]
  Server --> Dashboard["Sugar 看板"]

这条链路可以理解为旁路采集。Codex 仍然做原本的对话、模型交互和工具调用，Ducx 只在入口、身份、事件和上报这些位置补上企业治理能力。
最关键的边界是：采集发生在 Hook 层，而不是模型请求层。这样既能拿到更贴近用户行为的事件，又不会把统计逻辑绑死在模型协议上。

每一层分别解决什么问题？

层级	解决的问题	Ducx 中的体现
入口层	用户是否从可控路径进入	`ducx` 命令、封装版 `codex`、`CODEX_CLI_PATH`
身份层	使用行为归因到谁	`ducx login`、如流扫码、解析 `username`
事件层	在什么时机采集	`SessionStart`、`UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`Stop`
Reporter 层	采集和主流程解耦	`hooks/data-report` 独立读取事件并上报
可观测层	失败时如何排查	`~/.baidu-cx/reportlog/data-report.log`
治理层	数据如何被消费	统计服务、Sugar 看板、研发指标
这种拆法比把所有逻辑塞进主程序更稳。主流程只负责完成用户任务，采集链路只负责记录和上报行为；即使上报失败，也不应该影响用户继续使用 Agent。

采集字段应该怎么设计？

字段设计不要从“能采什么”出发，而要从“要回答什么问题”出发。

问题	字段示例
谁在使用	username、domain、team
在哪里使用	cwd、repo、branch
哪个会话	session_id、thread_id
发生了什么	event、hook_type、timestamp
调用了什么工具	tool_name、tool_status、duration
成本和产出如何	model、token、diff lines、generated code ratio
是否失败	success、error_code、error_message
涉及 prompt 正文、代码内容、完整文件路径等敏感信息时，不应默认明文上报，优先使用脱敏、hash 或聚合统计。

可复用模板是什么？

这类方案可以抽象成一个通用模板：当企业需要治理一个第三方研发工具时，不一定要改造工具内核，而是可以在工具外围建立一条旁路采集链路。

flowchart LR
  A["统一入口层<br/>收敛入口"] --> B["身份层<br/>绑定企业账号"]
  B --> C["事件层<br/>接入 Hook / Plugin"]
  C --> D["Reporter 层<br/>采集、脱敏、上报"]
  D --> E["可观测层<br/>本地日志 + 远端看板"]
  E --> F["治理层<br/>成本、质量、采纳率、ROI"]

这个模板的重点是职责分离：入口层解决覆盖率，身份层解决归因，事件层解决采集时机，Reporter 层解决解耦，可观测层解决排查，治理层解决数据消费。
只要这些边界清楚，这套模式就可以迁移到其他 AI Coding Agent、IDE 插件、内部 CLI 或研发平台工具上。

落地时要注意什么？

这个思路低侵入，但仍然要补安全和透明度。安装包应使用 HTTPS 下载，并配合 checksum、签名校验和版本回滚机制；采集字段也要提前说明清楚，尤其是哪些字段会上报、哪些字段会脱敏、谁有权限看这些数据。
采集系统越靠近研发工具链，越要明确边界：不影响正常使用、不改变模型行为、不吞掉用户错误、不让上报失败阻塞主流程。

一句话总结

Ducx 值得学习的地方，是把 AI Coding 工具治理拆成了一条低侵入的旁路采集链路：统一入口保证覆盖，扫码登录保证归因，Hook 事件保证采集语义，独立 Reporter 保证上报解耦，日志和看板保证可观测闭环。

MarkZ

探索