Skip to content

ge3m0r/transparent-agent

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

5 Commits
docs
docs
 
 
examples
examples
 
 
src
src
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 

Repository files navigation

transparent-agent

transparent-agent 是一个面向 CLI Agent 的可观测性 shim。

它的目标不是去拿厂商私有隐藏 prompt，而是稳定拿到两类信息：

  • wire context：实际发给模型的请求和响应
  • effective context：本地工具、文件、MCP、RAG、hooks 等最终影响回答的上下文

当前重点面向：

  • Claude Code
  • Anthropic-compatible API
  • Moonshot 的 Anthropic 兼容接口
  • 支持 OPENAI_BASE_URL 的 OpenAI-compatible CLI

它能做什么

  • 记录模型请求和流式响应
  • 接 Claude Code hooks，记录 prompt、工具调用、文件读取、compact 事件
  • 重建 turn 级上下文
  • 给每次会话和每轮任务自动打标签
  • 一边写文件，一边实时输出到控制台
  • 支持 Windows 和 Linux

3 分钟上手

1. 安装

开发阶段本地使用：

npm link

如果已经发布到 npm，按当前配置安装：

npm install -g @germer/transparent-agent

安装后实际执行的命令仍然是：

transparent-agent

2. 给 Claude Code 做一次初始化

用户级配置：

transparent-agent setup-claude --scope user --proxy-url http://127.0.0.1:8787

项目级配置：

transparent-agent setup-claude --scope local --project-dir .

这条命令会自动写入：

  • ANTHROPIC_BASE_URL
  • ENABLE_TOOL_SEARCH
  • AGENT_OBS_STORE_DIR
  • transparent-agent ingest-claude-hook

3. 启动代理

Moonshot：

transparent-agent serve-claude --provider moonshot --live

Anthropic 官方：

transparent-agent serve-claude --provider anthropic --live

4. 跟随事件流

另开一个终端：

transparent-agent watch-events --session latest --follow

推荐的实际使用方式就是这两条同时开着：

终端 A：

transparent-agent serve-claude --provider moonshot --live

终端 B：

transparent-agent watch-events --session latest --follow

最常用命令

下面这些是日常最常用、最值得先记住的命令。

配置和启动

初始化 Claude Code：

transparent-agent setup-claude --scope user

启动 Moonshot 代理：

transparent-agent serve-claude --provider moonshot --live

启动 Anthropic 官方代理：

transparent-agent serve-claude --provider anthropic --live

看最近一次会话

列出最近的 sessions：

transparent-agent list-sessions

看最近一次会话摘要：

transparent-agent replay --session latest

看最近一次会话的 turn 级上下文：

transparent-agent reconstruct --session latest

看 JSON 格式的对话过程

看最近一个 session 的 JSON 视图：

transparent-agent reconstruct --session latest --format json

看指定 session_id 的 JSON 视图：

transparent-agent reconstruct --session <session-id> --format json

如果你先不知道 session_id，先执行：

transparent-agent list-sessions

说明：

  • reconstruct --format json 输出的是 turn 级重建视图
  • 它适合看“这轮对话到底喂了什么上下文”
  • 如果你想看最底层原始事件，请直接看 events.jsonl

实时看事件

跟随最新 session：

transparent-agent watch-events --session latest --follow

跟随指定 session：

transparent-agent watch-events --session <session-id> --follow

输出文件

每个 session 默认会落到：

<store>/sessions/<session-id>/
  meta.json
  turns.json
  events.jsonl

这几个文件分别表示：

  • meta.json：会话级摘要，包含 label、firstPromptPreview、latestPromptPreview
  • turns.json：任务级索引，包含 task-001、task-002 等 turn 标识
  • events.jsonl：原始事件流

如果你已经知道 session_id，也可以直接看文件：

<store>/sessions/<session-id>/meta.json
<store>/sessions/<session-id>/turns.json
<store>/sessions/<session-id>/events.jsonl

实时输出模式

当前有两种实时模式。

1. --live

示例：

transparent-agent serve-claude --provider moonshot --live

作用：

  • 事件一边写文件
  • 一边由当前进程实时打印到控制台

适合：

  • 你想在代理终端里直接看实时流

2. watch-events --follow

示例：

transparent-agent watch-events --session latest --follow

作用：

  • 直接跟随最终落盘的 events.jsonl
  • 能看到其他进程写入的事件，比如 Claude hooks

适合：

  • 你想看更完整的实时事件流
  • 你希望代理和观察分开两个终端

不常用但有用的命令

列出支持的 provider / profile：

transparent-agent profiles

给旧数据补齐 session / task 标识：

transparent-agent reindex --all

启动任意自定义上游：

transparent-agent serve-proxy --proxy-target https://your-provider.example.com/anthropic

启动自定义上游并设置超时：

transparent-agent serve-proxy --proxy-target https://your-provider.example.com/anthropic --upstream-timeout-ms 180000 --drain-timeout-ms 30000

手动注入事件：

transparent-agent ingest-event --session my-session

Claude Code hooks 默认调用：

transparent-agent ingest-claude-hook

当前支持的上下文来源

  • 用户 prompt
  • Claude Code 指令文件加载
  • 文件读取 / 文件搜索
  • 工具调用前后
  • MCP request / response
  • RAG hit
  • context compact summary
  • 实际发给模型的 messages / tools / instructions

兼容性说明

当前一等支持

  • Claude Code + Anthropic 官方
  • Claude Code + Moonshot Anthropic 兼容接口
  • Claude Code + 其他 Anthropic-compatible provider
  • 支持 OPENAI_BASE_URL 的 OpenAI-compatible CLI

当前已覆盖的请求格式

  • /v1/messages
  • /v1/responses
  • /v1/chat/completions

当前边界

下面这些暂时不是“完全等价支持”：

  • 只做纯网络代理、但不暴露请求体的 TLS forward proxy
  • 只部分兼容 Anthropic / OpenAI 协议的厂商接口
  • 厂商私有隐藏 system prompt
  • 模型内部推理过程

也就是说，这个项目的目标是：

  • 稳定拿到本地有效上下文
  • 稳定拿到 wire context

不是保证拿到厂商服务端私有注入内容。

关于 ENABLE_TOOL_SEARCH=false

对 Claude Code 来说，这不是“禁用工具”，而是：

  • 不走按需 Tool Search
  • 改成 upfront 加载 MCP 工具

当你把 ANTHROPIC_BASE_URL 指向第三方兼容接口时，这样通常更稳。
尤其 Moonshot 这类 Anthropic-compatible 路径下，这个设置更保守也更兼容。

Windows 和 Linux

核心命令是跨平台的：

transparent-agent setup-claude --scope user --proxy-url http://127.0.0.1:8787
transparent-agent serve-claude --provider moonshot

之所以能做到这一点，是因为 setup-claude 会自动把 AGENT_OBS_STORE_DIR 写进 settings，后续命令默认读取这个环境变量，不需要每次手写存储路径。

只有在你手动传 --store 时，路径表达才需要区分平台。

Windows：

transparent-agent serve-claude --store "%USERPROFILE%\\.transparent-agent" --provider moonshot

Linux：

transparent-agent serve-claude --store "$HOME/.transparent-agent" --provider moonshot

仓库结构

src/
  adapters/
    claude-code/
    launcher/
    model/
    tool/
  context/
  core/
  replay/
  providers/
examples/
docs/

适合的使用场景

  • 想知道 Claude Code 到底把什么发给了模型
  • 想知道某次回答是由哪次任务、哪轮对话产生的
  • 想把工具调用、文件读取、MCP 结果和模型请求串成统一审计流
  • 想为自研 agent 做可观测性层

不适合的预期

  • 获取厂商服务端未公开的内部 prompt
  • 获取模型完整推理链
  • 把所有兼容接口都当成 100% 协议等价

开发说明

当前是零依赖 Node.js ESM 原型，主要入口在：

  • src/cli.mjs
  • src/adapters/model/http-proxy.mjs
  • src/adapters/claude-code/hook-events.mjs
  • src/context/session-artifacts.mjs

本地开发常用：

npm link
npm run profiles
npm run claude:setup:user
npm run claude:serve -- --provider moonshot
npm run claude:watch

安装

发布成功后，用户安装方式是：

npm install -g @germer/transparent-agent

然后直接使用：

transparent-agent setup-claude --scope user
transparent-agent serve-claude --provider moonshot --live

如果你第一次用，建议先记住这几条：

transparent-agent setup-claude --scope user
transparent-agent serve-claude --provider moonshot --live
transparent-agent list-sessions
transparent-agent reconstruct --session latest --format json
transparent-agent watch-events --session latest --follow

Claude Code Skill 和斜杠命令

setup-claude 在安装设置补丁的同时，会安装两个 Claude Code 配套组件：

  • 一个名为 transparent-agent 的 Claude Code skill
  • 一个名为 /transparent-agent 的斜杠命令

这意味着用户不必一开始就记住所有可观测性命令。设置完成后，他们可以直接在 Claude Code 中询问工作流。

常用示例：

/transparent-agent latest
/transparent-agent session <session-id>
使用 transparent-agent skill 将最新会话以 JSON 格式展示。
使用 transparent-agent skill 排查为什么只捕获了用户 prompt。

安装位置：

  • 用户级：~/.claude/skills/transparent-agent/SKILL.md 和 ~/.claude/commands/transparent-agent.md
  • 项目/本地级：.claude/skills/transparent-agent/SKILL.md 和 .claude/commands/transparent-agent.md

generated skill 和斜杠命令由 transparent-agent setup-claude 管理。如果用户稍后手动编辑这些文件并移除了 managed 标记，后续设置运行将保留现有文件而不覆盖。

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages