Story Data Analyze

story-data-analyze：指标体系驱动的小说数据诊断工作流

Spawn 版本提示（不阻断 spawn）：先读取项目根 .story-deployed 的 agents_version。与本版 agents_version: 39 不一致时（标记缺失、字段缺失/非整数、小于或大于 39）照常按文件存在性检查并 spawn，同时报告 Notice: agents bundle 版本不匹配（项目 {N}，本版 39） 并提示重新运行 /story-setup 后新开会话；大于 39 时额外提示先更新 oh-story-claudecode，不要用本地旧版 setup 降级覆盖。只有 agent 文件缺失、或运行时不暴露 custom agent 时才降级 solo/direct，报告 Fallback: ... -> solo。本 Skill 的具体落点仍按 lane 降级矩阵映射为 degraded / solo；当前运行时定义 malformed 与 registry 缺失同样视为 agent 不可用。

目标

本 Skill 是多 Agent 工作流的唯一入口，不是一份逐项看数清单。它以机器可读指标目录、指标树和诊断路由为共同语义层，完成以下闭环，不要停在“数字总结”或“样本不足”：

数据可信 → 漏斗定位 → 异动定级 → 阅读对应文本 → 提出因果闭合的修改 → 发布后验证

指标体系固定分为五类，不得把它们平铺成互不相干的单点指标：

1. 结果指标：作品是否持续产生有效阅读或有效触底；用于描述结果，不直接等同于可编辑抓手。
2. 驱动指标：分发、包装承接、黄金前三章/分段漏斗、深读和回访如何共同驱动结果。
3. 诊断指标：渠道结构、章节到达、条件跟读、损失人数、滚动窗进入/滚出等，用于寻找问题发生在哪里。
4. 护栏/反指标：防止为了提高一个节点而破坏上游承诺、下游追读、逻辑一致性或流量质量。
5. 数据质量指标：刷新、完整性、公式一致性、版本覆盖、范围可比性和污染；质量门不通过时关闭业务解释。

长篇的各层通常来自不同窗口或 cohort，不能把整棵树伪造成一个精确乘法公式；短故事同一快照的展示→阅读→15秒→30秒→60秒→触底在口径一致时可以严格分解。

每次至少回答六个问题：

1. 数据统计到哪一天，是否已完成刷新？
2. 最新数据相对修改前基线、前一快照分别怎样变化？
3. 变化发生在分发、包装、阅读承接、回访还是深章推进？
4. 异常对应哪一章、哪一段或哪个包装元素？
5. 为什么建议的修改在逻辑上有机会改善目标指标？
6. 发布后用什么指标、什么窗口验证，哪些指标不能变差？

把“方向”和“结论强度”分开。小样本也要如实报告绝对增量和上升/下降方向，但不得伪装成因果结论。

必读资源

处理番茄数据时按任务读取以下文件：

• 每次运行：读取 references/workflow-contract.md，遵守 Agent 分工、artifact 状态机、八道门禁和回退协议。
• 每次运行：加载 dictionary/metrics.v1.json、dictionary/metric-tree.v1.json 与 dictionary/diagnostic-routes.v1.json；它们分别是指标语义、上下游关系和异动下钻的机器权威。
• 解释指标体系或排查指标联动：读取 references/metric-system.md 与 references/diagnostic-routing.md。
• 所有番茄任务：读取 references/fanqie-metrics.md，只使用与长篇或短故事对应的章节。
• 比较前后快照、判断异动：读取 references/anomaly-rules.md。
• 给出改文建议或定位正文：读取 references/text-drilldown.md。

需要复用方法或案例时，先读 数据追踪/knowledge/index.json，再读 数据追踪/knowledge/methods/index.json 或 数据追踪/knowledge/cases/index.json，最后只加载命中的条目。知识条目是辅助证据，不能覆盖当前官方口径或当前 run 的事实。

指标定义与后台当前 tooltip 不一致时，以后台当前官方定义为准，并把差异记录到报告和参考文件；不要凭指标名猜口径。

不可违反的规则

1. 先校验数据，再解释业务。 把空值、未刷新、字段滞后、滚动窗口换日与真实变差分开。
2. 长篇和短故事使用不同漏斗。 不得用长篇跟读率解释短故事触底率，也不得用短故事点击率替代长篇章节承接。
3. 先看上游，但不得因此跳过下游事实。 上游没量会降低下游结论可信度，不代表可以不计算前三章或分段留存。
4. 百分比优先寻找权威分子/分母。 平台提供权威人数或明确 cohort 基数时，同时报绝对人数、转化率、百分点变化和样本量；只有展示百分比时不得伪造人数。可以计算“最小兼容整数下界”检查曲线是否存在整数解释，但必须标 minimum-compatible-lower-bound/display_only/non-authoritative/not-an-estimate：真实 cohort 可为任意更大的兼容解，不得跨快照相减成新增人数，也不能复用滞后的 follow 字段作同一分母。
   • 该下界不是人数估算，不得进入样本门槛、显著性检验、置信区间、MDE、绝对损失或“可挽回人数”计算。
   • 找不到与本次问题同 cohort、同口径且权威的样本分母时，必须登记 sample_size_qualified=false、sample_size=0、sample_size_authoritative=false、sample_aggregation=unavailable 和非空 sample_unavailability_reasons；analysis 使用 sample_metric_id=UNAVAILABLE。这里的 0 是“合格样本不可得”的状态编码，不是“真实读者为 0”，禁止拿别的计数或兼容下界代替。
5. 渠道阅读人数不等于曝光。 书城/分类为 0 只能说未观察到该渠道阅读 UV，不能说平台零曝光或推荐评估失败。
6. 继续阅读为 0 不等于绝对无人跨日回来。 它只是该入口没有记录到阅读 UV。
7. 在读人数不是历史累计人数。 番茄长篇在读人数是最近 14 天累计“听+读”用户，不能拿来计算章节跟读，也不能把单日 -1 直接称为流失 1 人。
8. 跟读低不只检查章末。 N→N+1 低说明读过 N 的人没有进入 N+1；检查第 N 章全章、章末、下一章标题和下一章开头。
9. 累计快照不是新读者队列。 快照差值可能混有老读者继续推进；只能称“窗口增量到达”，除非平台提供同批 cohort。
10. 不得保证改文一定涨数据。 必须证明修改与指标之间的因果链合理，再由发布后的数据验证。
11. 当前工作流不自动修改正文或发布。 默认交付具体修改方案与数据诊断卡；当前只有 UNATTESTED_PROCEDURAL 记录、没有宿主签名，即使用户在会话中明确同意也只形成可审计交接，不能由本 run 自动落文或发布。
12. 搜索流量占主导时确认自访。 未确认前保留方向事实，但把文本归因降级；不要擅自认定全部搜索都是作者或熟人。
13. 必须沿树联查，禁止孤立看点。 任一异动都要执行诊断路由规定的上游、同层、下游和护栏检查；没有完成必查项，不得进入文本归因。
14. Agent 不得越权替做。 抓取 Agent 不解释业务，指标 Agent 不读正文，校验 Agent 不润色原结论，文本 Agent 不改正文，看守 Agent 不发明分析。
15. 运行产物不得冒充知识。 日报、raw、单次推测和未验证修改都不能直接放入知识库；晋升必须经过监督门禁并保留来源 hash。

执行架构与总流程

运行模式

• full：五角色均可用，执行完整工作流。
• degraded：某一 lane 不可用，按 workflow contract 的降级矩阵执行并在报告中列出缺失能力。
• solo：runtime 无 custom agents 时由主 Agent 严格分阶段执行，但不得声称做过独立复算或监督；结论强度按缺失 gate 下调。

支持 custom agents 的运行时优先使用以下逻辑角色。先识别当前运行时，只检查对应目录：TRAE Code 为 .trae/agents/{agent}.md，Codex 为 .codex/agents/{agent}.toml；其他运行时只有部署了等价定义且暴露子 Agent 工具时才能进入 full。TRAE Code 的 .md 必须含合法 YAML frontmatter（name、description 必填，tools / disallowedTools 为逗号字符串），并通过内置 Agent 智能体选择同名 subagent；不要把 Claude 的 subagent_type 参数原样传给 TRAE。Codex 使用同名 agent_type。当前运行时对应目录或 registry 不完整时，按 references/workflow-contract.md 的 lane 降级矩阵进入 degraded / solo，不得拿磁盘上其他端残留定义冒充已注册 Agent。项目中仅并存 .zcode/ 不是当前运行时降级的依据。

WorkBuddy 使用有上限的物理 Agent 池，不再把五个逻辑角色全部注册为同名物理卡。WorkBuddy 物理注册只检查 story-data-fetcher 与 story-data-readonly-runner：前者保留 Bash 拉取能力，后者仅有 Read, Glob, Grep，承载其余四个只读逻辑角色。项目模式要求 .codebuddy/agents/ registry 真实列出这两个原始名称；plugin-only 模式只在当前 registry 真实列出时使用 oh-story:story-data-fetcher 与 oh-story:story-data-readonly-runner，不从 manifest 或磁盘文件推测注册成功。

五个逻辑角色为：

1. story-data-fetcher
2. story-data-metrics-analyst
3. story-data-method-validator
4. story-data-text-improvement-planner
5. story-data-supervisor

主 Agent 是唯一编排器和最终报告写入者。所有子 Agent 的 prompt 必须自包含 run_id、作品身份、冻结输入及 hash、截止日、改动事件、允许输出和禁区；子 Agent 不得递归 spawn。TRAE Code 每次调用都在内置 Agent 中明确选择上表的精确名称，并把完整自包含合同作为任务正文；若 Agent 工具未列出该名称，立即按 lane 降级，不通过普通对话假装完成独立角色复算。

WorkBuddy 的 story-data-fetcher 仍把完整 raw_capture 合同直接放进物理 fetcher 的 prompt。调用其余四个逻辑角色时，主 Agent 必须调用物理 story-data-readonly-runner，且 prompt 只能用以下封装：

{
  "logical_role": "<story-data-metrics-analyst|story-data-method-validator|story-data-text-improvement-planner|story-data-supervisor>",
  "logical_role_card_path": "<已解析的真实绝对路径>",
  "project_abs_path": "<当前作品项目真实绝对路径>",
  "task_contract": {"role": "<与 logical_role 相同>", "run_id": "<run_id>", "lane": "<该角色 lane>", "project_abs_path": "<与顶层字节一致>", "...": "<该逻辑角色的其余完整合同>"}
}

logical_role_card_path 项目模式只能解析到 <项目根>/.codebuddy/skills/story-data-analyze/references/workbuddy-role-cards/<logical_role>.md；plugin-only 模式只能解析到 CodeBuddy 已内联替换后的 <CODEBUDDY_PLUGIN_ROOT>/skills/story-data-analyze/references/workbuddy-role-cards/<logical_role>.md。传入 Runner 前必须取真实绝对路径，确认文件存在、直接父目录为该模式的固定 role-card 根、文件名与 logical_role 精确对应，且不含未解析占位符。Runner 或对应角色卡缺失、frontmatter 不合同、逻辑映射不唯一，均立即按该 lane 降级；不得改用旧的同名物理卡，不得把磁盘卡片存在冒充 registry 可用。

固定状态链

INIT → RAW_CAPTURED → DATA_QUALIFIED → WINDOW_BOUND → METRICS_READY
→ ANALYZED → ANALYSIS_VERIFIED → TEXT_DIAGNOSED → SUPERVISED → REPORT_COMPLETE

每一步通过 scripts/data_workflow.py 记录不可变 artifact 和 hash；禁止手改 analysis-runs 的 manifest。validator 或 supervisor 退回时，从最早错误阶段新建 attempt，最多三轮，之后标 BLOCKED。

三次是整个 run 共享的全局 RETURN 上限，不是“每个 Agent 三次”或“每种根因三次”。validator 与 supervisor 合计最多接受 3 次 RETURN，第 4 次 RETURN 请求直接把 run 标为 BLOCKED；根因计数只用于诊断，不能扩大总额度。

固定顺序：抓取 → 确定性标准化与质量门 → 指标分析 → 独立方法校验 → 文本诊断 → 看守 → 主 Agent 渲染日报。文本 Agent 的输入合同要求 validator PASS，因此不得提前读取正文；最多只能并行预载不含正文的公开方法，不能记录为有效 text artifact。

validator 的“独立复算”不是复述 metrics artifact：必须对每条 fact 重新打开冻结 raw/normalized/window 源，按其 JSON Pointer 读取 observation，并按记录的 calculation expression 复算；事实选择器、source refs、observations、formula、calculation 和结果全部一致且无遗漏时才可 PASS。

各 Agent 返回统一 envelope，工作流 CLI 记录的是角色专属 lane payload。主 Agent 必须先做确定性 adapter：验证 envelope 的 run_id/role/status/input_hashes，再只提取 schema 规定的 raw_capture/data_quality/analysis/validation/text_diagnosis/supervision 对象；禁止把整个自然语言响应或整个 envelope 原样塞进 record --payload。

Phase 0：确定作品类型和分析问题

先确定：

• 作品类型：长篇小说 / 短故事 / 两者都有。
• 用户问题：例行日报、修改效果、推荐/分发、前三章、某章断点、包装、完整诊断。
• 目标改动：改了什么、何时上线、预期影响哪个指标。
• 输入模式：拉取最新后台 / 分析用户给定快照或截图 / 只解释方法。
• 作品身份：锁定平台、作品名与作品 ID；账号有多部作品时禁止串数。

若同时分析长篇和短故事，分别建立漏斗和结论，不合并样本。

Phase 1：取数并判定数据是否可用

用户要求最新数据或例行监控时，对本项目执行：

cd "<项目根>"
for PYBIN in python3 python py; do "$PYBIN" -c "" 2>/dev/null && break; done
"$PYBIN" "数据追踪/拉取番茄数据.py"

用户明确指定本地历史快照、上传数据或只询问分析方法时，不擅自拉取新数据；先核验给定数据的截止日和作品 ID。

随后完成五项检查：

1. 登录：出现 LOGIN_INVALID 时停止，不使用旧数据冒充最新数据；通知用户重新登录。
2. 日期：确认 raw 的 date 为运行日、data_until 为前一日；平台中午更新前抓到的占位数据标记“平台尚未更新”。
3. 完整性：区分 null、空字符串、缺字段和真实 0；不得自动把前三者转成 0。
4. 内部一致性：渠道合计、阅读人数、章节到达与跟读公式应在允许的四舍五入误差内一致；不一致时标出具体字段并选择可信度更高的原始人数或等待同步。
5. 口径：记录累计/单日/7日/14日/自定义周期、是否跨日重复、是否滚动去重。

若当前问题所需样本分母不可从冻结源权威复算，不要拿日阅读人数、14 日在读、兼容整数下界或别的资格人群替代。按“样本不可用”编码继续生成事实与缺失节点，最终只能给 样本不足/SAMPLE_INSUFFICIENT，但仍可如实报告不依赖伪分母的原始观测。

若 raw 的 short_query.scope_verified_against_ui=false，短故事 yesterday_sum_*字段只能称“该快照接口原值”；打开后台核验当前周期后，才能称累计或单日口径。

输出数据质量标签：可分析 / 部分字段滞后 / 平台未更新 / 登录失效 / 口径未知。只有可用字段可以进入后续判断。