@polardbx/pxfuse0

v0.1.5

Published

15 hours ago

PXFuse agent observability CLI: hook management, trace capture, stats query, and cost tracking

0High
0Medium
0Low

polardbx-codematrix

hustfxj

@polardbx/pxfuse0

PXFuse Agent 可观测性 CLI — hook 安装/卸载、trace 与统计终端查询、内置 Skill 交付。

特性

Hook 全生命周期管理 — 一条命令为 AI agent 安装可观测性 hook，自动写入 agent 配置、部署 hook 脚本与 skill；卸载时干净还原
终端数据查询 — 无需打开浏览器，直接在终端查询 trace 列表、单条 trace 详情、每日统计指标、score 列表，支持 --json 机器输出
内置 Skill — 安装时将 pxfuse-query skill 部署到 agent 的 skills 目录，让 agent 在对话中自然语言查询可观测数据

支持的 Agent

qoder · claude · codex · hermes · qoderwork · qwen

安装

要求 Node.js >= 22

# npm
npm install -g @polardbx/pxfuse0

# pnpm
pnpm add -g @polardbx/pxfuse0

# 免安装直接运行
npx @polardbx/pxfuse0 <command>

安装后可使用 pxfuse0 或 pxfuse 两个命令（等价）。包还提供 pxfuse0-hook 可执行入口，供 agent hook 运行时内部调用，日常无需直接执行。

快速开始

1. 连接 PXFuse 服务

setup 需要 --host 与 --public-key 两个必填参数，secret key 始终从 stdin 读入（不作为命令行参数，避免进入 shell history）。可通过管道传入，也可在交互提示 Secret Key: 后手动输入。

# 管道模式：secret key 从 stdin 读入，不会进入 shell history
echo "sk-lf-xxx" | pxfuse0 setup \
  --host https://your-pxfuse.example.com \
  --public-key pk-lf-xxx \
  --secret-key-stdin

# 交互模式：省略管道，命令会打印 "Secret Key:" 提示后从 stdin 读入
pxfuse0 setup --host https://your-pxfuse.example.com --public-key pk-lf-xxx

setup 在保存前会调用 GET /api/public/health 做一次连通性校验；校验失败则不写入配置。校验通过后凭据保存到 ~/.pxfuse0/config.json（权限 0600）。

2. 为 agent 安装 hook + skill

pxfuse0 attach qoder      # 给 Qoder 装上可观测性 hook
pxfuse0 attach claude      # 或 Claude Code
pxfuse0 attach codex       # 或 Codex
pxfuse0 attach hermes      # 或 Hermes（YAML 配置）
pxfuse0 attach qoderwork   # 或 QoderWork
pxfuse0 attach qwen        # 或 Qwen Code

3. 在终端查看数据

pxfuse0 traces                          # 列出最近 trace
pxfuse0 traces --name "chat" --limit 5  # 按名称过滤
pxfuse0 trace <traceId>                 # 查看单条 trace 详情
pxfuse0 stats --from 2024-08-01         # 查看每日统计
pxfuse0 scores --limit 10              # 查看 score 列表

4. 在 agent 对话中通过 Skill 查询

安装 hook 后，agent 的 skills 目录会自动部署 pxfuse-query skill。在 agent 对话里直接说：

"帮我查看最近的 trace 列表" "今天的 token 使用量和费用是多少？" "查一下最近的 score 评分数据"

agent 会自动调用 pxfuse0 CLI 查询并返回结果。

命令参考

| 命令 | 说明 | 关键参数 | |------|------|----------| | setup | 配置 PXFuse 服务连接 | --host(必填) --public-key(必填) --secret-key-stdin | | config show | 显示当前连接配置（secret 脱敏） | — | | attach <host> | 为指定 agent 安装 hook + skill | 位置参数: host 名称 | | detach <host> | 从指定 agent 卸载 hook + skill | 位置参数: host 名称 | | doctor | 检查安装健康状态与 API 连通性 | --host(可选，仅检查指定 agent) | | traces | 查询 trace 列表 | --limit --page --name --tags --from --to --json | | trace <traceId> | 查看单条 trace 详情 | --json | | stats | 查看每日统计指标 | --from --to --daily --json | | scores | 查询 score 列表 | --limit --page --name --from --to --json | | status | 显示连接状态与已安装的 agent 列表 | — |

时间参数 --from / --to 使用 ISO 8601 格式
--json 输出机器可读格式（trace/scores 为 NDJSON，其余为 JSON）
--tags 支持逗号分隔的多标签过滤

全局用法

pxfuse0 --version          # 打印版本，如: pxfuse0 v0.1.2
pxfuse0 --help             # 全局帮助与命令列表
pxfuse0 <command> --help   # 查看单个命令的完整参数

数据结果写入 stdout；提示信息、错误、Secret Key: 输入提示均写入 stderr，方便脚本重定向
命令失败时以非零退出码结束（一般为 1；参数错误为 2）
有效 host 名称固定为：qoder claude codex hermes qoderwork qwen

命令详解

`setup`

pxfuse0 setup --host <url> --public-key <pk> [--secret-key-stdin]

--host（必填）：PXFuse 服务地址，如 https://your-pxfuse.example.com
--public-key（必填）：Public API key（pk-lf-...）
--secret-key-stdin（可选）：显式声明从 stdin 读取 secret key；无论是否带此 flag，secret key 都从 stdin 读入
成功输出：✓ Configured PXFuse connection to <host>

`config show`

pxfuse0 config show

显示当前连接配置，secret key 自动脱敏（仅显示末 4 位）：

host:       https://your-pxfuse.example.com
publicKey:  pk-lf-xxx
secretKey:  ****abcd

`attach <host>` / `detach <host>`

pxfuse0 attach qoder      # 安装 hook + skill
pxfuse0 detach qoder      # 卸载 hook + skill

pxfuse0 attach hermes     # 非 qoder 示例：Hermes 走 YAML adapter，命令体验一致
pxfuse0 detach hermes     # 卸载同理

attach 成功输出示例（含 hook 脚本、hook 配置、skill 与被备份的原设置文件）：

✓ Attached PXFuse to qoder
  Hook script: ~/.qoder/plugins/pxfuse-hook/hook.mjs
  Hook config: ~/.qoder/plugins/pxfuse-hook/config.json
  Skill:       ~/.qoder/skills/pxfuse-query
  Backups:     ~/.pxfuse0/backups/20240801T....-settings.json

attach 要求先完成 setup（否则报错提示未配置）。详见下文卸载 / detach 流程。

`doctor`

pxfuse0 doctor            # 检查全部已安装 agent + API 连通性
pxfuse0 doctor --host claude   # 仅检查指定 agent

输出总体状态、API 健康状态与逐 agent 明细；任一项不健康时退出码为 1：

Overall: ✓ healthy

API:     ✓ ok (v3.x.x)

HOST    STATUS   DETAIL
------  -------  ---------------------------------------
qoder   healthy  hook=yes script=yes config=yes

`traces` / `trace <traceId>`

pxfuse0 traces                          # 列出最近 trace
pxfuse0 traces --name "chat" --limit 5  # 按名称过滤，限制数量
pxfuse0 traces --tags "cli,prod" --from 2024-08-01T00:00:00Z
pxfuse0 traces --json                   # NDJSON 输出（每行一个对象）
pxfuse0 trace <traceId>                 # 单条 trace 详情
pxfuse0 trace <traceId> --json          # 单条 trace 的完整 JSON

traces 表格输出（末尾附分页信息）：

ID                                    NAME              TIMESTAMP             USER
------------------------------------  ----------------  --------------------  ----------------
0a1b2c...                             chat              2024-08-01T10:00:00Z  user-42

page 1/3 — 42 item(s) total

`stats`

pxfuse0 stats --from 2024-08-01 --to 2024-08-31   # 指定日期范围
pxfuse0 stats --json                              # JSON 对象输出（含 data + meta）

指标始终以每日粒度返回（DATE / TRACES / OBSERVATIONS / COST）
--daily flag 被接受但不改变输出（统计本就是按日聚合）

`scores`

pxfuse0 scores --limit 10                 # 最近 10 条 score
pxfuse0 scores --name "helpfulness"       # 按 score 名称过滤
pxfuse0 scores --json                     # NDJSON 输出

`status`

pxfuse0 status

显示连接状态（含脱敏 secret）与已安装 agent 清单：

Connection:
  ✓ configured
  host:      https://your-pxfuse.example.com
  publicKey: pk-lf-xxx
  secretKey: ****abcd

Installations:
  HOST    INSTALLED             HOOK SCRIPT
  ------  --------------------  --------------------------------------
  qoder   2024-08-01T10:00:00Z  ~/.qoder/plugins/pxfuse-hook/hook.mjs

支持的 Agent 详情

| Agent | 配置目录 | 配置格式 | Hook 事件 | Hook 脚本（源文件） | |-------|----------|----------|-----------|-----------| | Qoder | ~/.qoder/ | JSON | Stop | qoder-pxfuse-hook.mjs | | Claude Code | ~/.claude/ | JSON | SessionStart UserPromptSubmit PreToolUse PostToolUse PostToolUseFailure Stop SubagentStart SubagentStop SessionEnd | langfuse-hook.mjs | | Codex | ~/.codex/ | JSON | UserPromptSubmit Stop | codex-pxfuse-hook.mjs | | Hermes | ~/.hermes/ | YAML | on_session_start pre_llm_call post_llm_call on_session_finalize | hermes-pxfuse-hook.mjs | | QoderWork | ~/.qoderwork/ | JSON | UserPromptSubmit Stop | qoderwork-pxfuse-hook.mjs | | Qwen Code | ~/.qwen/ | JSON | SessionStart UserPromptSubmit PreToolUse PostToolUse PostToolUseFailure Stop SubagentStart SubagentStop SessionEnd | qwen-pxfuse-hook.mjs |

部署位置与差异说明

attach 对每个 agent 的落地方式一致：

Hook 脚本：源文件（上表最后一列）被复制到 <配置目录>/plugins/pxfuse-hook/hook.mjs，统一命名为 hook.mjs
Hook 配置：连接凭据写入同目录 config.json（权限 0600）
Skill：pxfuse-query 部署到 <配置目录>/skills/pxfuse-query
原设置文件备份：注册 hook 前，若已存在 settings.json / config.yaml，会先备份到 ~/.pxfuse0/backups/

各 agent 的关键差异：

Qoder / QoderWork / Codex / Claude Code / Qwen Code 使用 JSON settings.json，hook 条目通过 _pxfuse: true 标记以支持幂等安装/卸载；Qoder 的 Stop 事件使用 matcher: "*"
Codex 额外将 .codex-plugin/ 复制到 ~/.codex/plugins/pxfuse，用于插件市场发现
Claude Code / Qwen Code 覆盖最完整的生命周期事件（9 个），采集粒度最细
Qwen Code 的 command hook timeout 单位为毫秒（其他 JSON agent 为秒），因此写入 timeout: 15000（即 15s）
Hermes 使用 YAML config.yaml，hook 条目带 timeout: 5 与 _pxfuse: true 标记（其余 agent 的 JSON 条目 timeout: 15，单位为秒）

工作原理

Agent (Qoder/Claude/Codex/Hermes/QoderWork/Qwen)
  │
  ├─ Hook 脚本拦截 agent 事件
  │  (LLM 调用前后、会话开始/结束等)
  │
  ├─ 构造 trace/span/generation 数据
  │
  └─ POST /api/public/ingestion ──→ PXFuse Web
       (Basic Auth: publicKey:secretKey)        │
                                                 ▼
                                          存储 & 分析
                                                 │
  pxfuse0 CLI ←── Public API (GET) ─────────────┘
  (traces / stats / scores 查询)

Hook 采集：pxfuse0 attach 在 agent 配置中注册 hook 脚本，agent 运行时自动触发
数据上报：hook 脚本将 trace、span、generation 等数据通过 POST /api/public/ingestion 上报到 PXFuse Web（使用 Basic Auth 认证）
终端查询：pxfuse0 traces / stats / scores 等命令通过 PXFuse Public API（GET，Basic Auth，10s 超时）查询数据：
- traces → GET /api/public/traces
- trace <id> → GET /api/public/traces/{id}
- scores → GET /api/public/scores
- stats → GET /api/public/metrics/daily
- doctor / setup 连通性检查 → GET /api/public/health
Skill 查询：agent 通过内置 pxfuse-query skill 调用 CLI，在对话中直接返回查询结果

配置与数据存储

如何设置连接（无环境变量）

pxfuse0 不读取任何环境变量，所有连接信息（服务地址 host、public key、secret key）统一通过 pxfuse0 setup 一次性写入本地配置文件：

API base URL → --host
Public API key → --public-key
Secret API key → 从 stdin 读入（不落 shell history）

配置写入后，traces / stats / scores / trace 等查询命令会自动读取 ~/.pxfuse0/config.json；attach 时该凭据会被复制到各 agent hook 目录下的 config.json 供 hook 脚本上报使用。

存储位置

所有本地数据存储在 ~/.pxfuse0/ 目录下：

| 路径 | 说明 | 权限 | |------|------|------| | config.json | 服务连接凭据（host, publicKey, secretKey） | 0600（仅当前用户可读写） | | installations.json | 已安装 agent 的清单（host、安装时间、hook 路径、完整性哈希） | 0644 | | backups/ | attach 前对 agent 原设置文件的时间戳备份 | 目录 0700 |

安全设计

~/.pxfuse0/ 目录以 0700 创建，config.json 以 0600 权限保护，仅文件所有者可读写
secret key 通过 stdin 读入（管道或 Secret Key: 交互提示），不会出现在 shell history 中
config show / status 命令显示 secret key 时自动脱敏（仅显示末 4 位）
文件写入使用原子操作（temp + rename），避免部分写入导致的数据损坏

卸载 / detach 流程

pxfuse0 detach <host>     # 例如 pxfuse0 detach qoder

detach 会按以下顺序清理，且尽量保护用户改动：

从 agent 设置文件（settings.json / config.yaml）中移除所有带 _pxfuse 标记的 hook 条目；若某事件清空则删除该事件键
删除 hook 脚本 plugins/pxfuse-hook/hook.mjs 与同目录 config.json
若 plugins/pxfuse-hook 目录已空则一并删除
Skill 保护：仅当 skills/pxfuse-query 内容与安装时记录的哈希一致时才删除；若检测到本地改动则保留，并提示 Skill preserved (locally modified since install).
从 ~/.pxfuse0/installations.json 移除该 host 记录

若该 host 从未安装，命令会输出 PXFuse is not installed for <host>; nothing to remove. 并正常退出。

detach 不会自动删除 ~/.pxfuse0/backups/ 中的备份文件，如需可手动清理。

故障排查

先运行 pxfuse0 doctor 获取整体健康快照（API 连通性 + 各 agent 的 hook / script / config 三项检查）。任一项异常时退出码为 1，可用于脚本判断。

| 现象 | 可能原因与处理 | |------|----------------| | setup 报 connection check failed | host/凭据错误或服务不可达；确认 --host 可访问、/api/public/health 正常，再重试 | | 查询命令报 not configured. Run 'pxfuse0 setup' first. | 尚未配置连接；先执行 pxfuse0 setup | | attach 报未配置 | attach 依赖 ~/.pxfuse0/config.json，需先 setup | | doctor 显示某 agent hook=no | hook 未注册；重新 pxfuse0 attach <host> | | doctor 显示 script=no / config=no | hook 脚本或配置文件缺失；重新 attach 修复 | | API 报 HTTP 401 / 403 | public/secret key 无效或权限不足；用 config show 核对后重新 setup | | 请求超时（request timed out） | 网络或服务问题；确认服务地址可达（客户端超时为 10s） | | invalid or missing host | host 名称拼写错误；仅支持 qoder claude codex hermes qoderwork qwen |

内置 Skill

pxfuse-query

安装时自动部署到各 agent skills 目录下的 pxfuse-query/ 子目录（如 ~/.qoder/skills/pxfuse-query/、~/.claude/skills/pxfuse-query/），使 agent 具备通过 CLI 查询 PXFuse 数据的能力。attach / detach 只会整体覆盖或删除这一个子目录，同 skills 根目录下其他来源的 skill 不受影响。

触发场景：用户在 agent 对话中询问 trace、统计、score、token 用量、费用追踪等可观测数据。

行为规范：

agent 调用 CLI 时使用 --json 参数获取机器可读输出
不会伪造 trace ID、score ID 或统计数据
需要先完成 pxfuse0 setup 配置连接后才能查询

License

Apache-2.0

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@polardbx/pxfuse0

特性

支持的 Agent

安装

快速开始

1. 连接 PXFuse 服务

2. 为 agent 安装 hook + skill

3. 在终端查看数据

4. 在 agent 对话中通过 Skill 查询

命令参考

全局用法

命令详解

setup

config show

attach <host> / detach <host>

doctor

traces / trace <traceId>

stats

scores

status

支持的 Agent 详情

部署位置与差异说明

工作原理

配置与数据存储

如何设置连接（无环境变量）

存储位置

安全设计

卸载 / detach 流程

故障排查

内置 Skill

pxfuse-query

License

`setup`

`config show`

`attach <host>` / `detach <host>`

`doctor`

`traces` / `trace <traceId>`

`stats`

`scores`

`status`