@yxzpro/agent-acta

dsh plugin --profile web add @yxzpro/agent-acta

AgentActa

[English](./README.en.md) | 中文

本地 AI agent 请求日志面板：聚合多款 AI agent 写在磁盘上的会话日志，在浏览器里查看每一「轮次/请求」的耗时、token、缓存命中、上下文占用与工具调用明细。

• 本地常驻服务 + SSE 实时推送，无外部依赖、无网络上报、纯只读旁路（不注入、不改各 agent 的配置）
• 一个页面看 32 家 agent：atomcode / codebuddy / workbuddy / claude / codex / cursor / trae / qoder / opencode / gemini / copilot / windsurf / codearts / kimi / dsh / zcode / doubao / hermes / devin / minimax / mimocode / kilo / openclaw / comate / cline / pi / qwen / crush / droid / goose / openhands / commandcode
• 另有桌面悬浮卡片（Electron 小窗）：今日/累计 token + 最新卡片流

要求：机器上有 node（node -v 可用即可，>=22.5）。Windows 是主要验证平台；mac / Linux / 鸿蒙 PC

的代码路径（候选目录按平台展开、跨平台搬运的自愈、POSIX 权限）已就位并有回归钉着，但未在真机端到端跑过 ——

换平台前先看 [REFERENCE.md](REFERENCE.md)「跨平台」一节，那里写明了两边不一致的地方与要手工处理的两三件事。

完整口径、原理与排障详解见 [REFERENCE.md](REFERENCE.md)；各 agent 日志格式的字段口径与解析边界见 [LOGFORMATS.md](LOGFORMATS.md)。

安装与快速上手

从 npm 装

npm i -g @yxzpro/agent-acta        # 装完多出命令 agentacta 与 agentacta-mcp
agentacta --open                   # 起服务并打开 http://127.0.0.1:14570

⚠ 包名带作用域 @yxzpro/：裸名 agent-acta 与 npm 上已存在的 agentacta（别人的同类项目）被判定太像而发不出去。命令名不受影响，敲的还是 agentacta。国内镜像同步有先后（实测 npmmirror 还没同步到，腾讯云镜像已可回源），装不上就加 --registry=https://registry.npmjs.org/。

拿到的是压缩包（tgz）

npm i -g agent-acta-<版本>.tgz   # 装完多出命令 agentacta
agentacta --install-hooks          # 可选：会话启动时自动拉起服务
agentacta --open                   # 起服务并打开 http://127.0.0.1:14570

拿到的是源码目录

npm i -g <本目录>                                # 软链安装，改源码即时生效
node <本目录>/agent-acta-server.mjs --ensure     # 或者不装 npm，直接一条命令起服务

然后浏览器打开 <http://127.0.0.1:14570>。支持的服务已自动发现，无需配置。

命令一览

命令 · 作用

agentacta · 前台常驻（服务本体）

agentacta --ensure · 确保端口上跑的是本版服务：同版幂等退出，旧版自动重启（hook 调的就是它）

agentacta --open · 起服务并打开浏览器

agentacta --client · 起桌面悬浮卡片（首次执行会装 ~100MB Electron 运行时到 ~/.agent-acta/widget-runtime/）

agentacta --stop · 停止服务（先优雅关闭并落盘索引，拿不到响应才按 pid 强杀）

agentacta --status · 查状态：服务在不在跑、端口上那版与本地包是否一致、悬浮卡片开着没（退出码 0 一致 / 1 不一致或问不出 / 2 没在跑）

agentacta --doctor · 自检并输出一段可粘贴的病历：配置能不能解析、配置指向的目录还在不在、索引片有没有损坏或口径对不上、端口上跑的是不是这一版、页面文件齐不齐、归档现在多大（退出码 0 无失败 / 1 有失败）。只读，不改数据也不改配置

agentacta --install-hooks [--dry] [--agent atomcode,claude] · 把「会话启动自动拉起」写进 atomcode / claude 的配置（幂等，改前自动备份）

agentacta --uninstall-hooks · 移除上面写入的 hook

agentacta --where · 打印自身安装路径 + 可直接抄的 hook 命令

agentacta --archive · 归档一次：把「已结束、且早于今天」的日志条目连详情快照冻进 ~/.agent-acta/archive/（有些 agent 自己删日志，不冻就永久没了）。服务在跑时也会每天自动归档；这条是手动补跑/排查用的

agentacta --archive --list · 只看归档清单，不做归档

agentacta --archive --dry · 只报要写什么、不落盘（可配 --list）

agentacta --search-reindex [--dry] · 手动重建全文搜索索引（页面搜索框回车搜的就是它）。日常不用跑：服务启动 60 秒后自己建首轮、之后每 10 分钟一轮增量。服务在跑时拒绝执行（先 --stop），--dry 只统计不落盘

agentacta-mcp · 以 MCP server 身份跑（stdio）：给 Claude / Cursor / Qoder 这类客户端当只读工具用，见下节

agentacta --version / -v · 版本号 + 服务脚本指纹（判断端口上跑的是不是这一版）

agentacta --help / -h · 用法

未知参数会报错并以退出码 2 结束，不会默默起服务。

改完服务端代码后：agentacta --ensure 一步到位（比对代码指纹，不一致就停旧拉新）。改页面只需刷新浏览器。

当 MCP server 用（让 agent 自己查日志）

agentacta-mcp 是随包发的第二个命令，把本机日志以 MCP 工具的形式开放给客户端；它是独立进程、直读日志与索引，不连 14570、不写任何文件，所以常驻服务在不在跑都能用（首次握手后要全量扫一遍本机日志，约 2s，期间不打日志）。

配置片段（把路径换成本机实际装的那份，agentacta --where 可查）：

{ "mcpServers": { "agent-acta": { "command": "node", "args": ["<安装目录>/mcp-server.mjs"] } } }

工具 · 干什么

overview · 有哪些 agent、各多少条、索引新旧

search_entries · 按 agent/项目/时间范围列轮次（时间倒序，默认 50 条）

get_entry · 按条目 id 取全文（提问、输出、工具调用、LLM 明细）

list_sessions · 按会话聚合：几轮、多少 token、跨多久

usage_stats · by=day 逐日 / by=model 按模型的汇总

slowest_turns · 最慢的 N 轮 + p50/p95

tool_fails · 哪个工具最常失败 / 超时（三分类排行 + 逐 agent 覆盖度，超时算失败、软失败单列）

工具口径与页面/HTTP API 同源（同一批聚合函数），不另算一套。完整说明与逐客户端配置在 REFERENCE 的「作为 MCP server 接入」。

当 DSH 插件用（在 DeepSeek Harness 里看同一块面板）

装了 DeepSeek Harness（DSH）的话，可以把它当 Cordis 插件装进去：左侧栏多一个「AgentActa」图标，点开在中间栏占一整块面板 —— 就是同一个 Vue3 页面（iframe 承载，筛选 / 详情 / SSE 实时推送都在），不需要你再开浏览器或常驻服务。

dsh plugin --profile desktop add "@yxzpro/agent-acta"                      # npm 包名
dsh plugin --profile desktop add "git+https://github.com/elegant01/agent-acta.git#v2.14.7"   # 或直接从仓库

包名带 @yxzpro/ 是因为 npm 的相似性规则：裸名 agent-acta 与已存在的 agentacta（别人的同类项目，2026-02 就发了）判为太像而被拒。

产品名没改 —— 命令仍是 agentacta，仓库、面板标题、URL 全不变；只有 npm 标识与 DSH 的 bundle 名跟着包名走。

• dsh plugin 的参数逐字转发给 pnpm，认 registry / git / tarball / path 四态；只想要文件就把上面换成 "file:C:/绝对路径/yxzpro-agent-acta-2.14.7.tgz"（作用域包打出来的 tgz 文件名会去掉 @、把 / 变成 -）。⚠ URL 里的 # 与带 @ 的包名在 Git Bash / PowerShell 里整条加引号。把 v2.14.7 换成你要的版本即可（git ls-remote --tags https://github.com/elegant01/agent-acta 能看全）。
• 本项目以 MIT 许可发布（见 LICENSE），代码里没有网络出口、也不上传任何日志内容 —— 它只读你自己机器上那些 agent 已经落盘的文件。
• 装完要彻底退出 DSH 再启动（进程全没才算，只关窗口无效 —— 宿主有模块缓存）。
• 图标没出现，先按这两条查：① 宿主按 semver 判插件兼容（不匹配只进 skippedBundles、不报错，表现就是不出现）；② --profile 有没有指对你实际在用的那个 profile。已在 DSH 0.1.7-rc.2 / runtime 0.2.0-rc.1 上验通。

和命令行服务怎么共处（这条最常问）：插件每次请求现判 127.0.0.1:14570 在不在（环回探测约 1ms，结果缓存 2 秒），所以不用你选：

14570 · 面板给你什么

在跑 · 就是它的面板，原样递进 iframe（数据、SSE、写操作全通）—— 本机仍然只有它那一个扫描器，插件不另起一套

没在跑 · 插件自己在宿主进程里起一套（不监听端口、不写 pid、不空闲自停），面板照常用

CLI 中途退出时插件自己接手：下一条请求现判探测到 14570 没了，就在宿主进程里起 hosted 并照常递面板，不再给你一页「让插件接手」按钮（2026-10-09 改掉；原先那页要点一下才起，理由是怕和你又把 CLI 拉回来撞成两个写者 —— 但装载那一刻本来就是「探不到就起」，拦在按钮上只是多一次点击）。接手之后本进程一直是那个扫描器，之后再把 CLI 起回来也不会换回代理（要换回得重启 DSH）。

不需要为了看面板去 agentacta --stop 或重启整个 DSH（早先那版要你这么做，体验很差，已改掉）。

边界（有意为之，不是漏做）：插件不唤起悬浮卡片 —— 顶栏那颗「悬浮卡片」按钮在宿主里直接不渲染（入口 src 带 ?dsh=1，页面据此收起），/（宿主的认证兜底位）、/api/shutdown、/api/client、/api/trae/capture-key、/widget 这五条路由在宿主里根本不注册（防一次误触把宿主进程带走）；面板保持自家深色皮、不跟宿主明暗切换；数据面照旧只读本机、零网络出口。细节在 REFERENCE 的「作为 DSH 插件接入」。

页面用法速查

打开 <http://127.0.0.1:14570>：

• 筛选：Agent / 项目 / 时间范围（今天 / 近 7 天 / 近 30 天，按本地自然日）/ 状态 / 关键词
• 全文搜索：搜索框里敲字 = 只筛当前窗口（即时、免费）；按回车 = 全库检索 —— 搜的是每条轮次的正文

（用户输入 + AI 回复

…(truncated)