agentstracer

AgentsTrace（Privacy-First Fork）

原版：kaiaiagent/clawtrace

---

快速开始

安装

pip install agentstracer

或从源码安装：

git clone https://github.com/cyijun/agentstracer.git
cd agentstracer
pip install -e .

基本使用

# 1. 配置导出源并明确确认项目范围
agentstracer config --source all --confirm-projects

# 2. 导出对话记录
agentstracer export -o my_conversations.jsonl

私人使用（保留 API Keys）

# 禁用 secrets 脱敏（仅建议本地私人使用）
agentstracer config --no-secrets-redaction

# 导出（包含原始 API keys）
agentstracer export -o my_data.jsonl

# ⚠️ 此模式仅适合隔离的本机存储；文件可能包含明文凭据，绝对不要分享或同步。

其他命令

# 列出发现的项目
agentstracer list

# 启动本地 Workbench API（当前发行包不包含浏览器前端）
agentstracer serve

# 查看配置
agentstracer config

Langfuse 可观测性

Langfuse 凭据只从环境变量读取，不会写入 AgentsTrace 配置或同步账本：

export LANGFUSE_BASE_URL="https://langfuse.example.com"
export LANGFUSE_PUBLIC_KEY="..."
export LANGFUSE_SECRET_KEY="..."

# 检查服务端版本和凭据
agentstracer langfuse doctor

# 写入并回读一条不含本机对话的合成 trace
agentstracer langfuse smoke

# 只在本机解析、脱敏和检查，不发起网络请求
agentstracer langfuse preview --source all

# 增量同步并通过 Observations API v2 回读验证
agentstracer langfuse sync --source all --verify

同步会保留 agent / subagent / user-turn / generation / tool / event 树、时间边界与质量标记、模型和 token usage。Codex 会优先消费官方 codex-rollout-trace bundle，得到真实 inference、tool dispatch、code cell、terminal、subagent 边和严格递增 seq；未启用 bundle 的历史会话回退到 session JSONL。schema 覆盖以官方协议类型为基准，真正未知的类型以 WARNING observation 显式呈现。默认进行 secrets、用户名和路径脱敏，并以本地 SQLite 账本防止同一快照重复上传。启用方式、实现与数据源能力说明见 Langfuse 采集设计。

---

支持的 AI 工具

---

导出格式

JSONL（每行一个 JSON 对象）：

{"session_id": "abc-123", "model": "kimi-k2", "messages": [...], ...}
{"session_id": "def-456", "model": "claude-3-7", "messages": [...], ...}

主要字段

messages 结构

{
  "role": "user|assistant",
  "content": "消息内容",
  "thinking": "思考过程（assistant）",
  "timestamp": "2024-01-01T12:00:00Z",
  "tool_uses": [{
    "tool": "bash",
    "input": {"command": "ls -la"},
    "output": {"text": "..."},
    "status": "success"
  }]
}

---

关于本版本

这是 AgentsTrace 的修改版本，默认专注于本地隐私保护。普通导出和 Workbench 留在本机；只有显式执行 agentstracer langfuse doctor、smoke 或 sync 时才会访问用户配置的 Langfuse 服务，其中 smoke 和 sync 会写入远端。

主要修改点

1. 移除公共数据上传功能

• ❌ 云上传功能
• ❌ Skill 下载功能
• ❌ 浏览器自动打开
• ✅ 可选、显式的私有 Langfuse OTLP 同步

2. 可选禁用 Secrets 脱敏

• 新增 --no-secrets-redaction 配置
• 私人使用时保留 API keys
• 路径/用户名脱敏始终启用

3. 安全审查

• ✅ 无 eval() / exec() / compile()
• ✅ 无动态代码执行
• ✅ 无反序列化风险
• ✅ 路径遍历已防护

与原版对比

---

许可证

MIT License - 详见 LICENSE

Copyright (c) 2024 kaiaiagent (Original Author)
Copyright (c) 2024 cyijun (Modified Version)