arms-inspector

Claude Code plugin — 阿里云 ARMS RUM 错误自动巡检

打开 Claude Code 自动扫描线上前端异常，新错误立即推到会话顶部 brief；按需深挖某条、定位根因、写报告。完全独立运行，不依赖团队配置。

Demo

打开 Claude Code 进入项目目录的瞬间——

$ cd ~/code/my-vue-app && claude

<arms-session-context>
ARMS 巡检: 已自动扫描 prod env 最近 24h.

- 🆕 新增指纹 3 条
- 🔁 复发指纹 1 条 (建议复审)
- ⏳ 进行中 2 条

首条新增: "conv list failed: 33001" @ agent.abc.js:onResponse (8 次, prod)

完整列表: /home/me/code/my-vue-app/.plans/my-vue-app/inbox.md
深挖某条 → /arms:deepen task=<task-id>
</arms-session-context>

> 这条 conv list failed 帮我深挖一下

Claude 跑 /arms:deepen task=arms-20260526-001 → 拉堆栈、定位源码、写 findings.md。修完代码：

> /arms:resolve task=arms-20260526-001 commit=a1b2c3d branch=fix/conv-retry
ARMS task arms-20260526-001 已标记 resolved ✓
- branch: fix/conv-retry
- commit: a1b2c3d
- resolution: .plans/my-vue-app/arms-20260526-001/resolution.md

下次同指纹复现，brief 自动标 "🔁 复发"——不会被当成新问题重复打扰。

安装

A. 通过 marketplace（推荐，持久装机）

进入任意 Claude Code 会话，依次输入：

/plugin marketplace add beerui/arms-inspector
/plugin install arms@arms-inspector-marketplace

/reload-plugins 或 完成后退出再进（让 SessionStart hook 生效）：

# Ctrl-D 退出当前会话
cd <你的前端项目根目录>
claude

预期：未配置项目不会产生 brief 或 .plans/；完成 /arms:setup 后，下一次进会话顶部会出现 <arms-session-context> brief。

B. 本地调试（不持久，session-only）

git clone https://github.com/beerui/arms-inspector.git /path/to/arms-inspector
cd <你的前端项目根目录>
claude --plugin-dir /path/to/arms-inspector

进会话后 plugin 仅在本次会话激活。

C. 验证 plugin 真加载了

在 Claude Code 会话里输：

/plugin list

应该看到 arms 条目。在输入框输 /arms: 应该有 6 个补全：setup / scan / list / deepen / fix / resolve。

Qoder / Claude Code / Codex 一键安装（npx）

本工具同时支持 Qoder（CLI + IDE）、Claude Code 与 OpenAI Codex CLI，功能对等（自动巡检 brief + 全套 arms 命令）。底层 Python 核心共用，安装走跨平台 Node 安装器，原生支持 Windows（无需 WSL/bash）。

需要 Node ≥18 + Python ≥3.10：

# 装 Qoder + Claude Code
npx @shendu-sdt/arms-inspector --target both
# 三端全装
npx @shendu-sdt/arms-inspector --target all
# 单端
npx @shendu-sdt/arms-inspector --target qoder
npx @shendu-sdt/arms-inspector --target claude-code
npx @shendu-sdt/arms-inspector --target codex
# 卸载
npx @shendu-sdt/arms-inspector --uninstall --target all

装后重启对应工具，进项目目录运行 /arms:setup（Codex 端为 $arms-setup，且需先 /hooks 信任，见 docs/CODEX.md）。Qoder 详情见 docs/QODER.md；接入 sdt-dev-agent catalog 见 docs/SDT-DEV-AGENT-CATALOG.md。

完整使用路径（5 分钟跑通）

从零到产出第一份 findings.md 的完整路线。每一步都可以照抄。

Step 1 — 准备阿里云物料（在浏览器做）

到阿里云控制台找 4 件东西：

| 物料 | 取处 | |---|---| | ARMS RUM 应用 PID | ARMS 控制台 → 前端监控 → 你的应用 → "应用设置" → 应用 ID（形如 c67ee5ri5a@a02e69a18ed6a39） | | SLS region / project / logstore | ARMS 控制台 → 你的应用 → "数据源 / 数据存储" → 看"日志服务投递目标"。或直接打开 SLS 控制台某条日志的 URL，从 URL 解析（形如 .../project/proj-xtrace-<hash>-cn-hangzhou/logsearch/logstore-rum）。 | | AK ID + AK Secret | 阿里云 RAM → 用户 → 新建子账号 → 给策略 AliyunLogReadOnlyAccess → 创建 AccessKey |

⚠️ 强烈建议只读子账号，不要用主账号 AK。

Step 2 — 装 plugin

走上面 安装 / A 或 B 路径，进入 <你的前端项目> 目录里的 Claude Code 会话。

Step 3 — 首次配置

/arms:setup

Claude 会用 AskUserQuestion 一步步引导你填，不需要提前手写 .env：

1. 选 SLS region（cn-hangzhou / cn-shanghai / cn-beijing）
2. 选默认查询环境（prod / daily / pre / all）
3. 粘 PID + SLS project + SLS logstore（一次三行）
4. 粘 AK ID + AK Secret（一次两行）

完成后 Claude 自动：

• 写 .env（6 个变量）
• 给 .gitignore 加 .env 行
• 跑自检确认 SLS 能连通

预期看到：ARMS plugin 配置完成 ✓

Step 4 — 看错误（两种用法挑一种）

用法 A: 自动模式（推荐日常）

什么都不做。每次进 Claude Code 会话顶部会有 <arms-session-context> brief 列最近 24h 新错误（24h 防抖一次）。看到感兴趣的 task-id 直接深挖（跳到 Step 5）。

用法 B: 手动列+选+挖

/arms:list hours=2 env=prod

输出形如：

ARMS 列表 (env=prod, 2026-05-26 08:00 ~ 10:00, 共 4 种)

#  count  env   conv_message                  view        stack_top_frame
1  ×8     prod  conv list failed: 33001       /agent      agent.abc.js:onResponse
2  ×3     prod  token 无效或已过期            /agent/lo…  auth.def.js:verify
3  ×2     prod  global is not defined         /agent/se…  vendor.xyz.js:bootstrap
4  ×1     prod  ResizeObserver loop completed /           noise.js:onResize

下一步: /arms:deepen N=1 深挖第 1 条

选哪条都行，下一步 N=<n> 深挖。

Step 5 — 深挖某条

/arms:deepen N=1                            # 来自 /arms:list 的编号
# 或
/arms:deepen task=arms-20260526-001         # 来自 SessionStart brief 的 task-id

Claude 会：

1. 解析堆栈、定位 src/ 下的源码文件
2. Read 相关代码做根因分析
3. 写 .plans/<project>/<task-id>/findings.md（核心交付物）
4. 报告：根因 one-liner + findings 路径 + 推荐分支名

Step 6 — 修代码 + 归档

推荐：一条命令端到端修复

/arms:fix task=arms-20260526-001        # 或 N=<n> / 粘 ARMS 控制台 URL

Claude 会：切 fix/<task-id> 分支 → 按 findings 改源码 → 跑验证（test/typecheck/build）→ 自动 commit → 自动归档（含 code review）。验证不过或改动超范围会刹车交还你，不会硬提交。

或：手动修复

git checkout -b fix/arms-20260526-001   # 推荐分支名取自 findings.md
# 改代码...
git commit -m "fix: <一句话>"

回到 Claude Code 会话：

/arms:resolve task=arms-20260526-001 commit=<hash> branch=fix/arms-20260526-001

Claude 写 resolution.md、把 SQLite 状态改为 resolved。下次同指纹复现会被识别为"🔁 复发"。

Step 7（可选）— 这个先不修

/arms:resolve task=arms-20260526-001 ignore="业务方接受该报错"

下次复现仍会显示"🔁 复发"但带备注"曾被忽略"。

命令速查

| 命令 | 作用 | 例 | |---|---|---| | /arms:setup | 首次配置 / 重补缺失变量（幂等） | /arms:setup | | /arms:scan | 立即手动巡检，自动深挖 Top 5-10 | /arms:scan env=daily days=3 keywords=验证码 | | /arms:scan <URL> | 单点 URL 模式（粘 ARMS 控制台 URL） | /arms:scan https://arms.console.aliyun.com/#/rum/rum-explorer/... | | /arms:list | 只列不深挖，含编号，配合 /arms:deepen N=<n> 用 | /arms:list hours=2 keywords=验证码 | | /arms:deepen task=<id> | 深挖 SessionStart 自动采集的指纹 | /arms:deepen task=arms-20260526-001 | | /arms:deepen N=<n> | 深挖 /arms:list 输出清单的第 n 条 | /arms:deepen N=3 | | /arms:fix task=<id> | 端到端自动修复（改源码+验证+commit+归档） | /arms:fix task=arms-20260526-001 | | /arms:fix N=<n> / /arms:fix <URL> | 同上，list 编号 / ARMS 控制台 URL 入口 | /arms:fix N=3 | | /arms:resolve task=<id> commit=<h> branch=<b> | 标记修复完成 | /arms:resolve task=arms-20260526-001 commit=abc1234 branch=fix/auth | | /arms:resolve task=<id> ignore="<原因>" | 决定不修 | /arms:resolve task=arms-20260526-001 ignore="业务方接受" |

数据落点

<你的项目根>/
├── .env                                        # 凭证（被 .gitignore）
└── .plans/<项目目录名>/
    ├── archive.db                              # SQLite 指纹库（可配，默认 90 天保留）
    ├── inbox.md                                # SessionStart 写的最近 brief
    ├── last-list.json                          # /arms:list 缓存（供 /arms:deepen N= 用）
    ├── config.json                             # 可选 — per-project 高级配置
    └── arms-YYYYMMDD-NNN/                      # 每个深挖任务一夹
        ├── task_plan.md
        ├── progress.md
        ├── findings.md                         # 分析报告（核心交付物）
        ├── fingerprint.md                      # 指纹元数据
        └── resolution.md                       # /arms:resolve 后产物

.plans/ 默认不入 git（plugin 没强制 ignore，由你决定）。若想团队共享指纹历史，可手动从 .gitignore 移除该路径。

配置进阶（可选）

写 .plans/<project>/config.json 调高级行为：

{
  "schema_version": 1,
  "auto_scan_enabled": true,
  "default_env": "prod",
  "ignore_patterns": [
    "ResizeObserver loop completed",
    "Script error"
  ],
  "retention_days": 90,
  "severity_thresholds": {
    "P1": 50,
    "P2": 5,
    "P3": 1
  }
}

| 字段 | 默认 | 含义 | |---|---|---| | schema_version | 1 | config schema 版本号，未来 breaking 变更时按此分支处理 | | auto_scan_enabled | false | 是否允许 SessionStart hook 自动巡检；/arms:setup 会写为 true | | default_env | prod | SessionStart hook 默认扫的环境 | | ignore_patterns | [] | 子串匹配后过滤掉的错误消息（已知噪声） | | retention_days | 90 | SQLite resolved/ignored 保留天数 | | severity_thresholds | {"P1":50,"P2":5,"P3":1} | brief 里 severity 标签的 count 门槛 |

SessionStart hook 行为

每次 claude 启动会调 scripts/arms-on-session.py：

1. 未显式启用项目（无 ARMS_FORCE_SCAN、无 ARMS_ENABLE_AUTO_SCAN、且 .plans/<project>/config.json 未声明 "auto_scan_enabled": true）→ exit 0 静默，且不创建 .plans/ 或 archive.db。
2. 检查 archive.db.meta.last_global_scan —— 距今 ≤24h → exit 0 静默
3. 距今 >24h（或首次）→ 拉 SLS 默认环境最近 1 天 → 聚合 → 比对 SQLite → 新指纹 INSERT
4. 写 inbox.md + stdout brief
5. 失败永远 exit 0（凭证缺、SLS 不可达、db 损坏都不阻塞 Claude Code 启动）

/arms:scan 主动触发会 export ARMS_FORCE_SCAN=1 绕过 24h 防抖。

常见问题

Q: 哪些操作系统支持？

| OS | 支持 | 备注 | |---|---|---| | Linux | ✓ | 主力测试平台 | | macOS | ✓ | 0.4.3+ 已修 POSIX 兼容 (BSD shell 不再依赖 GNU xargs -d) | | Windows + WSL2 | ✓ | 跟 Linux 等价 | | Windows 原生 (PowerShell, 无 WSL) | ✓ (Qoder) / ✗ (Claude Code) | Qoder 端原生支持（胶水已 Python 化，见 docs/QODER.md）；Claude Code 端仍建议 WSL2 |

Windows 用户在原生 PowerShell 下跑 /arms:scan 会因 bash 语法 (export $(...)、set -a 等) 失败. 安装 WSL2 (wsl --install) 后, 在 WSL 里跑 Claude Code 即可获得 Linux 一致体验.

Q: 找不到 PID？

ARMS 控制台 → 前端监控 → 选你的应用 → "应用设置" → 顶部"应用 ID"那一长串（形如 c67ee5ri5a@a02e69a18ed6a39）。

Q: 装完没看到 brief？

按顺序排查：

1. 是否带 --plugin-dir 启动（本地装法）or 跑过 marketplace install（持久装法）？
2. /plugin list 有没有 arms？没有 → plugin 没加载
3. /arms: tab 补全有没有 5 个命令？没有 → plugin manifest 解析失败，看 ~/.claude/logs/
4. 都有但没 brief → v2.1.150+ 可能不直接渲染 SessionStart hook 输出，brief 仍存在但注入到模型 context，模型能用看不见。手测 python3 <plugin>/scripts/arms-on-session.py 看脚本本身能跑

Q: 报 ProjectNotExist？

SLS_PROJECT 填错了。常见误区：把 ARMS 应用名当 SLS project 名。SLS project 是阿里云日志服务的项目（形如 proj-xtrace-<hash>-cn-hangzhou），不是 ARMS 应用本身。控制台 → ARMS → 数据源 → 看"日志服务投递目标"。

Q: 报 Unauthorized / SignatureNotMatch？

AK 权限不够。RAM 给子账号加 AliyunLogReadOnlyAccess，确认 AccessKey 状态是"启用"。

Q: 错误数据其实在 daily 环境，怎么扫？

显式参数：

/arms:scan env=daily days=3
/arms:list env=daily hours=4

或写持久化默认：.plans/<project>/config.json:

{ "auto_scan_enabled": true, "default_env": "daily" }

之后 SessionStart hook 也默认扫 daily。

Q: 凭证安全吗？

• 真值只落项目根 .env，由 /arms:setup 自动加入 .gitignore
• findings.md / fingerprint.md / SQLite 都不写凭证
• 强烈建议用最小权限 RAM 子账号（AliyunLogReadOnlyAccess + 仅当前 SLS project 读权限）
• 如果 AK 不慎泄漏（commit 进 git 或截图分享），立即在阿里云 RAM 删除重建

Q: 想触发但 24h 防抖拦着？

/arms:scan 命令已自动加 ARMS_FORCE_SCAN=1，不会被防抖。SessionStart hook（自动那次）才受 24h 防抖控制。

开发

git clone https://github.com/beerui/arms-inspector.git
cd arms-inspector
pip3 install --user --break-system-packages pytest pytest-cov aliyun-log-python-sdk
python3 -m pytest                                       # 121 tests, ≥80% coverage

修代码必须先写 / 改测试（TDD）。所有 PR 需 121 测试全绿 + coverage ≥80%。

详细贡献指南见 docs/E2E_WALKTHROUGH.md 和 docs/INTEGRATION_TEST.md。

License

MIT