Agent 使用情况报告生成器（支持日/周/月/年）
本文件是操作手册。详细的数据源路径、计价表、Token/成本口径、任务分类规则、36 问 FAQ 收口到
references/FAQ.md与docs/ADAPTERS.md，按需查阅，不在此展开。
文件角色：本技能 = 1 个声明（本 SKILL.md）+ 5 个数据源适配器（
adapters/）+ 核心引擎（scripts/）。tests/与tools/是开发期资产（测试 / CI 渲染），不在用户运行路径上、也不进发布包；docs/与examples/是文档与示例，不含可执行逻辑。
一、贯穿性硬约束（每轮必须遵守）
以下规则在每一次执行时都必须成立，即使上下文被压缩也不能丢：
- 只读采集 + 离线优先：采集阶段只读取本机数据（
~/.workbuddy等），默认零网络、不上传。仅当用户显式传入--pricing-api/--task-llm-endpoint时才访问用户自己的端点；--lookup-pricing online只本地拼接搜索链接、不发请求。绝不接受从 trace / 会话内容派生的 URL（防 SSRF）。 - 写文件必须用户逐条确认：只有
scripts/pricing.local.json（补自定义模型单价）与scripts/task_rules.json（调分类权重）会被写；且必须先回显待写入清单、等用户确认后才落盘。pricing.local.json不进发布包、升级不覆盖；task_rules.json是发布资产、升级会覆盖（改前备份）—— 该文件为纯 pattern 列表、不含可执行代码，改动后任务分类结果会在报告标注_task_confidence。 - 归属告警（dumate）：
--source dumate按 WorkBuddy 布局读目录，记录里没有任何字段能区分它来自百度搭子还是 WorkBuddy（实测workbuddy.db217 会话匹配 qianfan/dumate 命中 0 行）。报告标题用中性措辞「Dumate 数据源使用情况报告（数据归属未证实）」，不暗示确认的百度搭子归属；报告数据来源行与清单强制带「归属未证实、勿当作百度搭子用量引用」告警，内容可能完全是 WorkBuddy 的。 - 估算 ≠ 账单（qwenwork 等）：服务端不回传 token 的源（千问办公），token 为字符估算、金额一律
tokens_only，不可用于对账或账单核对，真实消耗以官方账单为准。 - 成本口径分级标注：默认 L2 估算（静态单价 × token），报告顶部横幅必须标注「不含服务端时段减免，请勿据此做预算或账单对账」；传入
--import-official <xlsx>才升级为 L1 真值。 - 报告标题统一：标题固定为
Workbuddy使用情况报告，周期由报告头部「报告类型」行以日历日期标识（日报/周报/月报/年报/自定义），不随周期带后缀。
一·附 权限与作用域声明（最小权限）
本节为 ClawHub 审核所需的可执行权限 manifest（
_meta.json的permissions块与此一致）。作用域严格最小：
| 能力 | 作用域 | 触发条件 | 默认 |
|---|---|---|---|
| 文件读（只读） | 本机用户数据目录：~/.workbuddy/、~/.claude/projects/<cwd哈希>/*.jsonl（仅一级工程目录）、~/.codex/sessions/、~/.qwenworkcn/、DUMATE 覆盖目录 |
采集阶段 | 始终；不递归扫 ~/.workbuddy；claude-code/codex 仅枚举一级工程/日期目录；越窗会话元数据整体跳过（见适配器日期窗口过滤） |
| 文件写 | 仅 --output 指定路径（报告）；~/.workbuddy/pricing.local.json / task_rules.json（确认后） |
写配置须先回显清单 + 用户确认 | 主流程零写盘 |
| 网络 | 仅用户自己的端点：--pricing-api / --task-llm-endpoint |
显式传入才联网；--lookup-pricing online 只拼链接、绝不发请求 |
零网络；无内置默认端点；URL 绝不从 trace/会话派生（防 SSRF） |
| 环境变量 | CLAUDE_PROJECTS_DIR / CLAUDE_CONFIG_DIR / CODEX_HOME / DUMATE_HOME / DUMATE_OUTPUTS_DIR |
仅用于指向数据源根 | 不读任何密钥 |
- 默认能力（始终成立）：本机只读采集 + 完全离线；不写文件、不发任何网络请求、不上传任何数据。
- 可选网络（仅显式启用）：仅当用户传入
--pricing-api <URL>或--task-llm-endpoint <URL>（均指向用户自己的端点）时才联网；--lookup-pricing online只本地拼接搜索链接、绝不发请求。无内置默认端点，URL 绝不从 trace / 会话内容派生（防 SSRF）。 - 可选写（仅确认后）：仅
scripts/pricing.local.json/scripts/task_rules.json，且必须先回显待写清单、用户确认后才落盘；pricing.local.json不进发布包、升级不覆盖。 - 报告产物写（默认流程）：
scripts/analyze_tokens.py是 Token 子报告生成器，读入你采集好的data.json（或实时采集），只向你指定的输出路径写 Markdown/HTML 报告与 ASCII 图表（如--output token_report.md）；不写任何~/.workbuddy内部文件、不读网络、不修改定价/配置；该输出路径由你控制，与pricing.local.json/task_rules.json无关。 - 维护工具隔离：
scripts/fetch_pricing.py为发布者专用的定价维护助手，不在用户采集 / 报告生成路径上、也不随 ClawHub / SkillHub 发布包分发（仅源码仓库scripts/提供）；默认只出候选与差异、不落盘、不抓厂商网页（须显式 apply 选项才写）。
二、单次执行流程（5 步闭环）
输入：用户的自然语言请求（如「出本周报告」）或显式参数。 输出：报告文件（默认 Markdown）+ 3–5 条核心发现的摘要。
- 确定时间范围
- 输入：用户说的周期或参数。
- 行为：默认
--period week；用户可给--period day|week|month|year、--days N、或--start/--end绝对范围（优先级：绝对 >--days>--period）。 - 兜底：用户没说就按周（最近 7 天）；无法解析时回问用户而非猜。
- 确定数据源
- 输入：用户在哪个 Agent 里跑。
- 行为：
--source默认workbuddy；在千问办公内跑必须--source qwenwork；想显示「百度搭子」标题用--source dumate（见硬约束 3）。 - 兜底：默认源采到 0 条数据时，提示可能选错源并列出可用源。
- 采集数据
- 命令：
python scripts/collect_usage_data.py --source <src> --period week --output data.json（或实时模式：不传 data_file 直接进第 4 步）。 - 兜底：trace 未启用 / 目录不存在 → 报错并提示开启 trace 或换
--source。
- 命令：
- 生成报告
- 命令：
python scripts/generate_report.py data.json --output report.md（或--format html|json）；想实时生成可合并为generate_report.py --period week --output report.md。 - 兜底：data.json 缺字段 → 提示重跑采集。
- 命令：
- 展示结果：输出 3–5 条核心发现摘要，用
present_files展示完整报告。
三、快速参考
数据源（--source）
| 取值 | 读哪 | 注意 |
|---|---|---|
workbuddy（默认） |
~/.workbuddy/（traces + workbuddy.db + usage-log.json + 会话目录） |
能力最全 |
claude-code |
~/.claude/projects/**/*.jsonl |
无技能/自动化维度；CLAUDE_PROJECTS_DIR 可覆盖 |
codex |
~/.codex/sessions/.../rollout-*.jsonl |
CODEX_HOME 可覆盖 |
qwenwork |
~/.qwenworkcn/（转录 + runs 日志 + agents.db + outputs） |
千问办公里跑用它；token 估算、金额 tokens_only |
dumate |
~/.workbuddy/（按 WorkBuddy 布局） |
归属未证实，见硬约束 3；DUMATE_HOME / DUMATE_OUTPUTS_DIR 可覆盖 |
计价模式（--cost-mode）
auto（默认）：一个单价都没命中时自动切tokens_only。tokens-only：强制隐藏金额维度。priced：无论如何都按现状出金额。
时间窗口
4 种预设（day/week/month/year）+ --days N + --start/--end 绝对范围；标题统一 Workbuddy使用情况报告，周期见报告头「报告类型」。
自定义模型（不碰发布版）
只写本地 pricing.local.json（不进发布包、升级不丢）：custom_local 段（名带 custom-local: 前缀）或 models 段（裸名）。普通用量报告严格只读、离线，不会触发本注入流程；仅当你明确发起「自定义模型注入」流程（说一句"把我的自定义模型加进报告"）时，Agent 才会在你确认单价后写入。流程与确认闸门见 references/add-custom-models.md 与 references/on-download-inject.md。
四、隐私与联网行为（完整清单）
分阶段口径（硬约束已列）：采集阶段只本机只读、默认离线；配置阶段仅确认单价后写本地 pricing.local.json / task_rules.json。
| 行为 | 触发条件 | 目标 | 说明 |
|---|---|---|---|
| 定价查价 | 显式 --pricing-api <URL> |
你自己的镜像端点 | 不内置默认端点；URL 只来自命令行参数，不从 trace/会话派生；价标 🌐 不计入总额 |
| 任务分类 | 显式 --task-classifier llm + --task-llm-endpoint <URL> |
你自己的 OpenAI 兼容端点 | ⚠️ 高风险出站路径：启用时会话派生文本（可能含 prompt / 代码 / 内部推理上下文）会发往你自己的端点，不再是纯本地；默认关闭，须显式开启；失败自动回退本地启发式；不内置任何默认端点 |
| 搜索链接 | --lookup-pricing online |
不发请求 | 纯字符串拼接 DuckDuckGo 链接，交你自点 |
| 默认 | 都不传 | 零网络 | 本机只读 + 本地渲染（任务分类走本地启发式，零出站） |
scripts/fetch_pricing.py 是独立、手动触发的定价维护助手（发布者用，非用户采集路径）：默认只出候选与差异报告、不落盘、不抓厂商网页；数据源由你自备。该脚本不随发布包分发，仅源码仓库提供，终端用户无需它即可生成报告。
关于
config.json的update_url：仅由skillhub upgrade在用户手动升级时拉取 manifest JSON（GET，无需 token，返回 200 仅含版本号），报告生成流程永不触发任何网络访问、绝不发送本地数据。update_url是升级元数据机制，不构成数据外传或远程代码执行证据。
五、扩展与参考（按需查阅，不在此展开）
- 详细数据源路径、已知偏差、适配器接缝与验收清单：
docs/ADAPTERS.md - 36 问 FAQ（安装 / 生成 / 计价 / 分类 / 隐私 / 故障排查）：
references/FAQ.md - 自定义模型注入流程与确认闸门：
references/add-custom-models.md、references/on-download-inject.md - 报告章节结构、Token 口径（原始总量 vs 实际消耗计费等效）、成本口径（L1 真值 / L2 估算）、任务分类加权规则：随报告一起输出说明，并见代码
scripts/内 docstring（如collect_usage_data.py的classify_task/collect_task_types、ca_core.py的口径常量）。
六、示例
✅ 触发（应启用本技能）
「帮我出一份本周的 Agent 使用情况报告，看看这周 token 花在哪了」
❌ 不触发（不应启用本技能）
「帮我把 Claude 的配置改成用 GLM-5.2 跑」——这是修改 Agent 配置 / 实时操控，不是基于本地已有数据出报告，本技能不做。