SkillTrace

它解决什么问题

AI Skill 的执行链路是个黑盒：开发者不知道哪个步骤被频繁触发、错误集中在哪、用户在哪一步流失。SkillTrace 用埋点机制把 skill 的运行过程变成可查询的事件流，同时保证不侵入主流程、不上报敏感数据。

核心能力与工作流程

• 专属 API Key：每个被埋点的 skill 必须使用独立 Key，仅写入当前 shell 环境变量 SKILLTRACE_API_KEY，不落盘、不写入 ~/.zshrc 等持久化配置
• 只读分析：先识别 skill 入口、工具调用、模型调用与异常路径，此阶段不修改任何文件
• 事件方案确认：按业务流程生成事件表，包含事件 code、触发时机、metadata 字段和隐私说明，用户确认前不动手埋点
• 注入运行时：复制 scripts/track.sh（Unix-like 环境优先）或 scripts/skilltrace_runtime.py（Python 兜底）到目标 skill 的 scripts/ 目录
• 异步上报：在关键步骤插入 bash scripts/track.sh ... >/dev/null 2>&1 & 形式的后台调用，上报失败静默忽略，绝不打断主流程

会话标识与强制事件

• 每次执行必须以 skill_invoked 开始、以 session_end 结束，缺少任何一个都会导致会话数据不完整
• SESSION_ID 基于工作目录哈希写入 ${TMPDIR}/skilltrace-session-${CWD_MD5}.tmp，同一次执行内所有 shell 调用共享，不依赖 PID
• session_end 发送结束上报并删除临时文件，确保下次执行生成全新 ID

隐私与适用边界

• 只上报分类数据：事件名、耗时、token 数、输入类型、输出是否被采纳；用户原始输入、文件内容、完整日志、API Key 等一律不采集
• 埋点对终端用户完全透明，AI 回答中不得出现"埋点已上报"这类内容
• 事件命名必须贴合具体业务（如报告类用 report_uploaded、问答类用 question_submitted），不能机械套用固定模板
• 适合需要度量使用情况的自研 skill；metadata 只能填枚举、计数、布尔值和脱敏错误分类