@germer/transparent-agent

v0.1.0

Published

a month ago

Observability shim for CLI agents such as Claude Code.

0High
0Medium
0Low

germer

agent cli claude-code observability proxy mcp anthropic moonshot

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 @ge3m0r/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

当前仓库已经按下面这个包名准备好了：

@ge3m0r/transparent-agent

注意：

npm 的 scope 取决于你的 npm 用户名或 npm 组织名
这里我先按 ge3m0r 处理
如果你的 npm 用户名不是 ge3m0r，发布前要把 package.json 里的包名改成你的真实 npm scope

第一次发布

npm login
npm whoami

先看即将发布的包内容

npm run pack:dry-run

正式发布

npm publish --access public

后续发新版本

补丁版本：

npm version patch
npm publish --access public

次版本：

npm version minor
npm publish --access public

大版本：

npm version major
npm publish --access public

发布前建议检查

建议至少确认这几件事：

package.json 里的包名和 scope 正确
npm whoami 对应的 npm 账号拥有这个 scope
npm run pack:dry-run 看到的文件只包含 src、README.md、LICENSE
transparent-agent setup-claude --scope user --print 可以正常输出
transparent-agent serve-claude --provider moonshot --live 本地能正常启动

用户安装方式

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

npm install -g @ge3m0r/transparent-agent

然后直接使用：

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

发布后还可以补的东西

如果你准备把这个包继续做得更完整，下一步通常会补这些：

补变更日志
补 CI 和 smoke test

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

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 and slash command

setup-claude now installs two Claude Code companions alongside the settings patch:

a Claude Code skill named transparent-agent
a slash command named /transparent-agent

That means users do not have to remember every observability command up front. After setup, they can stay inside Claude Code and ask for the workflow directly.

Common examples:

/transparent-agent latest
/transparent-agent session <session-id>
Use the transparent-agent skill to show the latest session as JSON.
Use the transparent-agent skill to troubleshoot why only the user prompt was captured.

What gets installed:

user scope: ~/.claude/skills/transparent-agent/SKILL.md and ~/.claude/commands/transparent-agent.md
project/local scope: .claude/skills/transparent-agent/SKILL.md and .claude/commands/transparent-agent.md

The generated skill and slash command are managed by transparent-agent setup-claude. If a user later edits those files manually and removes the managed marker, future setup runs will keep the existing file instead of overwriting it.