skills-smartbadge-ops

skills-smartbadge-ops

智能工牌录音管道(归档 → 清洗 → 讯飞转录 → DeepSeek 报告)的全功能 AI 运维技能(Claude Code Skill)。

一个技能覆盖:巡检、故障自诊断、补跑/重试、OSS 同步、列表排查、报告解读、月报/年报按需聚合分析、线上部署核验。

快速开始(npx 安装,无需克隆)

# 1. 一条命令安装/更新技能(自动放到 ~/.claude/skills/smartbadge-ops)
npx --yes --package=git+https://git.fmode.cn/lami/skills-smartbadge-ops.git smartbadge-ops

# 2. 配置凭据(按提示复制;Windows: copy .env.example .env)
cd ~/.claude/skills/smartbadge-ops
cp .env.example .env            # 编辑 .env,填写 SMARTBADGE_PASSWORD(及需要的 OSS 四项)

# 3. 登录并一键核查(密码亦可取自 .env,无需再传)
node scripts/api.mjs login
node scripts/check-online.mjs

之后 Claude 中直接提问即可(如「昨天管道有问题吗」「帮我出 8 月月报」),技能通过「确认门」交互流程逐步完成。

升级

重跑第 1 步即可(已配置的 .env/登录 token 自动保留,不被覆盖)。

安装到其他 AI

技能安装完成后,~/.claude/skills/smartbadge-ops 是含 SKILL.md 的完整技能目录,在其他 AI 中直接指向该目录即可。

环境要求

项	要求
Node	>= 18(内建 fetch,零 npm 依赖;建议 node:20 镜像)
Python	仅 verify-online.py 需要,含 playwright + chromium(浏览器走查;纯 Docker/无浏览器环境跳过,用 check-online.mjs)
网络	可达 recording.sh-lami.com(或本地后端)
时区	脚本日期口径固定 Asia/Shanghai(容器 UTC 时区无需配置)
凭据	登录用户名/密码(无内置默认值,见下);OSS 凭据可从服务端项目 server/.env 自动发现

Docker / Linux 部署(与服务器一致的容器环境)

# 1. 拉取安装(或 git clone 后用 node scripts/install.mjs --dest)
npm install -g 或用 npx --yes --package=git+https://git.fmode.cn/lami/skills-smartbadge-ops.git smartbadge-ops

# 2. 凭据不写入镜像——用环境变量注入(Docker 容器内 ~/.claude/skills 建议挂 volume 持久化 .token)
docker run --rm -it \
  -e SMARTBADGE_USERNAME=xxx \
  -e SMARTBADGE_PASSWORD=xxx \
  -e OSS_ACCESS_KEY_ID=xxx -e OSS_ACCESS_KEY_SECRET=xxx \
  -e OSS_BUCKET=xxx -e OSS_REGION=xxx \
  -v smartbadge-skill:/root/.claude/skills smartbadge-ops:latest \
  node scripts/check-online.mjs

要点:

• 零密钥入库:全部脚本无内置用户名/密码/密钥,凭据仅经 .env(容器内)或进程环境变量注入;仓库级 .gitignore 排除 .env/.token/out/。
• 无需 Python:容器内只跑 Node 脚本即可完成巡检/聚合/OSS 对账;浏览器走查 verify-online.py 在宿主机或带 chromium 的环境执行。
• 时区无关:日期计算(report-aggregate 默认窗口等)显式按 Asia/Shanghai,容器默认 UTC 不会错位。
• Windows Git Bash 兼容:以 / 开头的 API 路径参数需 export MSYS_NO_PATHCONV=1(仅 Windows;Linux/Docker 无此问题)。

脚本一览

脚本	用途
scripts/api.mjs	任意接口调用(login/get/post/env、--raw、--base)
scripts/check-online.mjs	线上 12 项断言一键核查(登录/health/错误/归档/列表/实时分流/心跳/设备/互斥)
scripts/verify-online.py	浏览器 5 页走查,0 pageerror 断言
scripts/oss.mjs	OSS 直连列举(顶层统计/前缀明细/--json/--find-env)
scripts/report-aggregate.mjs	区间聚合:窗口内报告 + 逐日对账 → 缺失清单与补跑建议(月报/年报原料)
scripts/fetch-report-text.mjs	报告正文拉取(HTML→纯文本,供 AI 深度分析)
scripts/lib.mjs	共享库(凭据回退链/token/httpJson/htmlToText;内部使用)
templates/monthly-report.md	月报/年报八段分析结构模板
templates/report-html.html	可选 HTML 产物模板

凭据与安全

• 本仓库不含任何密钥。登录 token 缓存 .token;OSS 凭据从服务端项目 server/.env 自动发现,或技能仓库根 .env,或进程环境变量。
• 凭据定位回退链:--env 参数 > 环境变量 SMARTBADGE_ENV_FILE > 技能仓库根 .env(cp .env.example 填值)> 自动发现(本仓库同级/兄弟目录中名称含 device|smartbadge 且带 server/.env 的项目)> 已导出的 OSS_* 环境变量。
• 排查凭据定位:node scripts/oss.mjs --find-env。
• OSS 客户端两态:同机有服务端项目(server/services/oss-client.js)时复用其模块;否则自动回退内置零依赖实现(scripts/oss-client-mini.mjs,与 ali-oss 签名行为一致)。

给 AI 的完整配置提示(安装时粘贴)

步骤 1:一条命令安装技能(自动安装到 AI 技能目录,无需克隆、无需记路径):

npx --yes --package=git+https://git.fmode.cn/lami/skills-smartbadge-ops.git smartbadge-ops

步骤 2:密钥清单。只需 SMARTBADGE_PASSWORD 登录密码(脚本自动发现同机服务端项目的 server/.env 读取 OSS 凭据);无服务端项目的环境才需要 OSS 四项(填入技能仓库 .env 或系统环境变量):

环境变量	必填	取值来源	说明
SMARTBADGE_API_BASE	否	线上 https://recording.sh-lami.com	或本机后端 http://localhost:3002
SMARTBADGE_USERNAME	是	登录用户名(无内置默认值)	缺省即报错提示
SMARTBADGE_PASSWORD	是	API 登录密码(与系统一致)	无内置默认值
OSS_ACCESS_KEY_ID	条件	自动发现服务端项目 server/.env;无则填入技能仓库 .env	需 OSS 对账时才需要
OSS_ACCESS_KEY_SECRET	条件	同上	需 OSS 对账时才需要
OSS_REGION	条件	同上(如 oss-cn-shanghai)	同上
OSS_BUCKET	条件	同上	同上

步骤 3:给 AI 的完整提示词模板(复制粘贴,替换 <...> 占位):

# 技能安装: smartbadge-ops(智能工牌录音管道全功能运维)
## 第一步 安装技能(npx 一条命令,自动装到 AI 技能目录)
npx --yes --package=git+https://git.fmode.cn/lami/skills-smartbadge-ops.git smartbadge-ops
cd ~/.claude/skills/smartbadge-ops && cp .env.example .env   # Windows: copy .env.example .env
## 第二步 配置 env(复制本块到技能仓库 .env,或配系统环境变量)
SMARTBADGE_API_BASE=https://recording.sh-lami.com
SMARTBADGE_USERNAME=<登录用户名>
SMARTBADGE_PASSWORD=<填写 API 登录密码>
OSS_ACCESS_KEY_ID=xxx
OSS_ACCESS_KEY_SECRET=xxx
OSS_BUCKET=lm-recording-files
OSS_REGION=cn-shanghai
OSS_PUBLIC_DOMAIN=lm-recording-files.oss-cn-shanghai.aliyuncs.com
## 第三步 登录核查
node scripts/api.mjs login
node scripts/check-online.mjs
## 使用规范(遵照技能 SKILL.md §1 确认门协议)
先复述我的问题与方案,回问「是这个意思吗?」再执行;
只读操作(巡检/列表/对账/聚合)可一句备案继续;写操作(补跑/重试/补传/改配置)必须先罗列将修改的数据面并等我确认。
## 上线前自检
先运行 node scripts/check-online.mjs 确认 12 项 PASS,再响应我的提问。

步骤 4:验证——让 AI 说「做一次每日巡检」,应输出三行简报(PASS 项/警告项/留痕)。

与项目内旧技能的关系

本项目内旧的 .claude/skills/smartbadge-pipeline-ops 已被本独立仓库取代(内容迁移并扩展至月报/年报与确认门交互)。安装本技能后,直接以 smartbadge-ops 使用即可。

版本

v1.2.0 — 2026-09-06,Docker/Linux 容器适配:① 零密钥原则——移除全部脚本/模板内置默认用户名与密码(登录凭据不再有任何代码内置值),凭据仅经环境变量/.env 注入,缺省脚本报错提示;② 时区固定 Asia/Shanghai(report-aggregate 默认窗在 UTC 容器不再错位一天);③ verify-online.py playwright 缺失时友好提示;④ 新增「Docker/Linux 部署」一节 v1.1.0 — 2026-09-04,npx 一条命令安装(package.json + 安装器,自动落位到 AI 技能目录,升级保留 .env/.token);check-online 密码支持 .env 回退;fetch-report-text 支持列表相对 downloadUrl