> 本目录是对外发布版（SkillHub 包）。内部工作版位于 ~/.workbuddy/skills/resource-credit-estimation/，
> 其中 references/ 保留了本节目的真实实测值（含项目目录名与池规模），不得进入本目录。
> 改内容时两边同步；本目录任何改动在发布前必须先过内部披露检查（命中即中断，不要绕过）。
> 判断标准一句话：「这份文件被互联网上任何人读到时，会不会暴露不该暴露的东西？」
> 公开 skill 的源文件任何人都能下载 —— 内部锚点、项目路径、池子规模一律不得进本目录。
开工前所需资源与积分预估
在动手之前，把一项工作的磁盘 / 时间 / 积分成本估出来，并给出「是否构成约束」的结论。
> 核心立场：估算的目的是改流程，不是出一张表。
> 一张只有数字的表没有价值；有价值的是「所以这个约束不存在，真约束是别的」或「这一点很贵，这样改就能省掉」。
零、先判断：这次要不要估？
估算本身也要花积分。先过一遍前置判断 —— 命中任一条才值得展开，否则直接给一句话结论即可。
| 值得展开 | 说明 |
|---|---|
| 可能撞上硬边界 | 磁盘剩余、时间窗、月额度 |
| 不可逆决策依赖它 | 「要不要扩池子」「要不要换方案」 |
| 估算会改变计划形状 | 结论可能导致缩范围 / 分批 / 放弃 |
| 不值得展开 | 说明 |
|---|---|
| 量级显然可忽略 | 单文件操作、读一个小 JSON ⇒ 直接说「不构成约束」 |
| 没有可实测的同类产物 | 先做小样本探针（见 §二·法则 4），不要在零依据上推演 |
| 纯属「把成本变成一条长期追踪线」 | ⚠️ 这是发散，不是本 skill 的用途 |
> ⚠️ 明确禁止：不要为了「算得更准」而设计一套需要人工持续记录余额/用量的观测流程。
> 那是把一个优化话题无限延伸。能消除明确的浪费就够了，不要把估算做成常态化的账本。
一、⭐ 先分类：哪些环节根本不计费
这是本 skill 里最省事、也最容易被忽略的一步。先分类，再估算 —— 很多时候分类完就发现「没什么可估的」。
把工作拆成三类：
| 类别 | 例子 | 成本类型 |
|---|---|---|
| 本地计算 | 脚本下载数据、回测、编译、批量转码、跑校验 | 磁盘 + 时间，不耗积分 |
| 连接器 / MCP 读写 | 邮件、云盘、文档、数据库连接器 | 不耗积分（官方口径） |
| AI 会话 | 读脚本输出、分析、写文档、逐轮汇报进度 | ⭐ 唯一消耗积分的环节 |
⇒ 由此得到本 skill 最重要的一条推论：
> 省积分的本质不是「少做事」，而是「减少 AI 参与的轮数 × 上下文长度」。
一次跑 172 个下载任务的脚本 = 0 积分；把它拆成 172 轮进度汇报 = 极贵。
同一个工作量，成本可以差两个量级 —— 差别只在流程。
二、四项法则
法则 1：能实测就别推演
- ❌ 反例：
11.7 年 × 40+ 只 × 243 交易日 × 5 个频率档—— 乘法看起来很严谨，但错在每个个体都不同。 - ✅ 正解：从已有的同类产物量出单位成本（bytes/条、秒/只、KB/次），再乘上真实的规模。
单位成本必须实测，规模必须真实。两者缺一，估算就会错一个量级。
单位成本的实测方式（时序类数据）→ 用 scripts/measure_unit_cost.py（见 §七）。
法则 2：套用实测比率前，先验证格式同构
致命陷阱：比率是从 A 产物量出来的，若 B 产物的字段、编码、分隔符不同，比率不成立。
反推法：把 A 的原始字节 与 代码两种输出模式（默认分隔符 / 紧凑分隔符）比长度，
长度相等的那种即 A 的实际编码方式；
再核对 B 的写入代码是否用同一模式。
⚠️ 同构不只是「字段名一致」—— 数值表示精度也会让比率失真 40%。
真实案例（同一个缓存目录内，字段名完全相同）：
{"open": 3.179875479492476, ...} ← 前复权长浮点，187 B/条
{"open": 0.519, ...} ← 短小数， 135 B/条
⇒ 该目录的 bytes/条是双峰分布（低精度 ~134 / 高精度 ~170），
只取全体中位会得到 ~137，若目标产物是高精度，就低估了 24%。
判据：先给缓存内的文件做精度分档（scripts/measure_unit_cost.py 会自动输出），
再选与目标产物同一档的中位数做投影。目标精度判断方法：看目标写入代码的取值来源
（如 dividend_type='front' 之类的前复权 ⇒ 通常落高精度档）。
> 宁可取高一档 —— 估算用于判断「是否构成约束」，偏保守的误差是无害的，偏乐观的误差会误导决策。
法则 3：规模要用真实分布，不要用统一值
本次：按每只标的的真实上市日分别计算，而不是统一按 11.7 年。
后果：池内 2024-12 上市的那只实际只可拉 1.8 年 —— 按统一值会高估 6 倍。
⇒ 遇到「每个个体的窗口 / 规模不同」时，先花很小成本把真实分布探出来再算。
（本次用月线接口批量探上市年月 —— 对按年估算完全够用，且请求量极小。）
法则 4：把隐性成本单列出来
容易漏的三类：
- 间接产物：工具自己也会存一份缓存（如客户端的数据目录、模型的本地副本）
- 中间态：临时文件、日志、解压副本
- 重试成本：失败重试会同时放大时间与体积
⇒ 做法：主口径给一个 ±10~20% 区间，隐性项另起一行单独列，不要混进去含糊。
三、积分部分：只能做结构性优化，不能精确预算
3.1 诚实边界（先讲清）
无法在事前精确算出「这次要花多少积分」。 因为消耗量 = 上下文长度 × 轮数，
而二者都取决于执行过程中 AI 会读什么、会被拆成几轮 —— 这在动手前不可知。
⇒ 所以本 skill 对积分只做两件事：
1. 量级分类：这一项是「0 / 低 / 中 / 高」
2. 给出省法：把高变低，把低变 0
不要编造精确的积分数字。 编出来的数字会被下游当成依据，比留空危险得多。
3.2 消耗量级判断
| 量级 | 特征 |
|---|---|
| 0 | 纯本地脚本执行；连接器读写 |
| 低 | AI 只读几 KB 摘要、一次成文 |
| 中 | AI 需要读若干中等文件、多轮次修改 |
| 高 ⚠️ | 逐条/逐个汇报进度；读入 MB 级文件本体；把批量任务拆成多轮 |
3.3 ⭐ 省积分纪律（这一节比估算数字有用）
- ✅ 脚本化 —— 把批量操作写成一个脚本，一次执行
- ✅ 后台一次跑完 —— 用后台运行，不要开着会话等
- ✅ 只回读摘要 —— 脚本自产
_summary.json/_fail_log.json（几 KB）供 AI 读 - ❌ 绝不逐条汇报 —— 每轮都带全文上下文，是「上下文 × 轮数」双重放大
- ❌ 绝不让 AI 读大文件本体 —— 单文件可达数 MB；需要事实时让脚本先用脚本摘要再喂给 AI
- ❌ 不要把上下文窗口调大、关闭「Max」类扩展 —— 直接抬高每轮基数
额度口径会变，用到时去查当前规则（不要硬编码记忆里的数字）。
查法：项目记忆的运维/积分小节，或平台文档。
四、输出模板
按这个骨架输出，六节缺一不可：
## 一、结论先行
<这一项是否构成约束？占预算的百分比是多少？一句话给答案>
## 二、主要成本
| 项 | 量 | 占可用预算 |
（必须含「占百分比」列 —— 它才回答了「是不是约束」）
## 三、边际增量
| 单位 | 增量 |
（用户真正要决策的常是「再加一个要多少」）
## 四、可复现依据
- 单位成本怎么实测的（脚本 / 数据位置）
- 规模怎么来的（真实分布 / 探针）
- 格式同构性怎么验的
## 五、无法测的项
| 项 | 为什么测不了 | 何时能补 |
（留空 + 标注，绝不编数字）
## 六、所以呢（流程建议）
- 该改哪个环节
- 如果某项 ≪ 预算 ⇒ 明确说「不构成约束」，并指出**真正的约束是什么**
⭐ 「占 0.33%」比「492 MB」有用得多。 前者直接回答了决策问题，后者还要读者自己换算。
五、精度声明
| 项 | 可信度 | 前提 |
|---|---|---|
| 磁盘（同类产物已有） | 高（±10~20%） | 有可实测的同类基线 + 规模分布真实 |
| 磁盘（全新产物） | 低 | 须先做小样本探针 |
| 时间 | 中 | 有历史耗时样本；外部服务速度不可控 |
| 积分 | 仅量级 | 结构性判断，不给精确数字 |
⚠️ 估算被证伪时：留存实测值，回填文档，并记录偏差原因。
不要为了「估得准」而反复重估 —— 那本身就是浪费。
六、常见坑
| 坑 | 后果 | 对策 |
|---|---|---|
| 用统一窗口乘全部个体 | 高估数倍 | 探真实分布（法则 3） |
| 把测得比率直接套到异构产物 | 估算失真且不自知 | 先验同构（法则 2） |
| 漏算工具自身的缓存 | 低估，且是别人踩过的坑 | 单列隐性项（法则 4） |
| 只给总量不给边际量 | 无法支撑「要不要扩」的决策 | 输出模板第三节 |
| 只有绝对数字没有占比 | 读者无法判断是不是约束 | 输出模板第二节 |
| 编造无法测的项 | 下游当依据，错误传导 | 第五节留空 + 标注 |
| 为估准而建长期账本 | 发散，不改善产品质量 | §零 的禁止条 |
| 批量任务拆多轮汇报 | 积分双重放大 | §三 纪律 |
七、资源
scripts/measure_unit_cost.py
从已有的同类缓存实测单位成本（bytes/记录），产出可直接用于投影的表与 JSON。
PY scripts/measure_unit_cost.py <缓存目录> \
[--groups daily,hour60,min15] # 只统计这些分组（缺省=全部）
[--select 510300,159915] # 只统计这些个体
[--out unit_cost.json]
它会做（并规避本次踩过的坑）：
- 兼容裸 JSON 数组与 {"rows": [...]} / {"bars": [...]} 等带容器键的结构
- 按 <个体>_<分组>.json 拆解命名；报告每组的字节数中位数与分布
- ⭐ 自动做「数值精度分档」 并在检测到多档并存时报警
—— 这是本项目实际踩过的坑：只取全体中位会低估 25%
- 主动标出空文件、解析失败、命名不符、显著偏小的条目（静默跳过是危险的）
- 输出每个个体的时间跨度与记录数，便于和真实窗口对照
它不会做：投影。投影需要「每个个体的真实窗口」，那是领域知识 ——
拿到脚本输出的单位成本后，由 AI 结合真实分布自行相乘（法则 3）。
references/anchor-values.md
实测锚点值（时序 CSV/JSON 类数据的量级校准）。
是实测快照，不是通用常数 —— 用于校验自己算出来的数是否离谱，不要直接引用。
> 本目录为对外发布版：锚点已脱敏为通用示意值（不含项目目录名、标的代码、池规模）。
> 其中保留了「双峰分布导致低估 14~31%」这一教训本身 —— 那才是这个文件的价值所在，
> 数字只是佐证。内部版锚点不随本包分发。
八、一句话备忘
> 先分类（很多环节根本不计费）→ 再实测单位成本 → 用真实分布算规模 → 给占比不给绝对值。
> 积分只做量级判断和流程优化，不编精确数字。
