docs(v5): 新增 15_V5阶段开发计划(对齐 V4 颗粒度,M0-M4 施工级)

承接 13 号草稿,每个 M 含目标/当前真实状态(file:line)/已拍板/待拍板/涉及文件/开发顺序/验证

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tech_documents/工程落地/15_V5阶段开发计划.md

@@ -0,0 +1,213 @@
+# V5 阶段开发计划
+
+状态:正式版(评审中)。
+版本:2026-06-28。
+承接文件:`tech_documents/工程落地/13_V5迭代计划草稿.md`(并入其三层设计、现状体检、配置文件夹重组方案;草稿保留作素材源)。
+粒度说明:对齐 `12——V4阶段开发计划.md` 的主计划颗粒度。施工级 file:line 细节后续下沉 `v5_implementation_briefs/M{0-4}/`;本文定业务口径、模块边界、字段合同、接口改动、验证方式、每阶段待拍板。所有"当前真实状态"的 file:line 均经真实代码/JSON/Excel/数据库核对。
+
+---
+
+## 1. 为什么做 V5
+
+| 问题 | 真实证据 | 对策 |
+|---|---|---|
+| 只有抖音一本规则包,程序写死只翻抖音 | `policy_json.py:17`(路径写死)、`:95`(默认 platform=douyin)、`:121/154`(字面量 ==douyin) | 规则包按平台选(M2) |
+| 打分配比焊死且 3 处副本 | `evaluator.py:226/239/242`、`run_record/validation.py:969/971/973`、`flow_ledger_service.py:1500/1506` | 搬进每平台手册,三处联动(M2) |
+| 评分维度被离线校验锁死恰两维 | `validate_rule_pack_config.py:99`、`validate_v4_config_contract.py:470` | 放开支持可变维度集(M1) |
+| 游走只认两态,非抖快视平台一跑即崩 | `walk_graph_json.py:156` 只认 supported/blocked;bilibili/youtube/weixin/github 写 unsupported/weak、toutiao/zhihu 写 `_all` | 扩四态 + 规范化(M1) |
+| 边目录绑死抖音 | `walk_strategy_json.py:87` 硬断言 strategy_id=douyin_walk_strategy_v1;`walk_graph_json.py:19` EDGE_CATALOG_PATH 抖音文件 | 解耦成平台无关总章程(M1) |
+| 小红书/公众号无 client | `content_agent/integrations/` 仅 douyin/kuaishou/shipinhao | 新建 client(M3) |
+| 学习算法要调权重,但权重焊代码、改要发版 | 同打分配比焊死 | 把权重/门槛搬进可写配置铺路(M2/M4) |
+
+---
+
+## 2. 范围锁定
+
+| 子系统 | V5 要做 | V5 不做 |
+|---|---|---|
+| 打分顶层公式 | 维度集+权重搬进每平台手册;evaluator 只读不算 | 不改非抖音 0.5/0.5 行为(快照零变化);不改 AI 出契合分 |
+| 评分卡 schema | 固定两维→按平台激活可变特征集 | 不做配置 DSL(不在配置写控制流) |
+| 规则包加载 | `load_policy_bundle` 加 platform、按平台选包 | 不强制每平台立刻拆包(抖音先维持) |
+| 游走边目录/四态 | 边目录解耦成总章程;校验扩四态 | 不打墙③(引擎即插即用大重构) |
+| 游走预算 | walk_policy 从全局改 default+平台段 | 不改抖音/视频号现有游走行为 |
+| 平台接入 | 公众号/小红书建 client;快手/视频号补齐手册 | 不接头条/知乎(平台侧坏) |
+| 作者作品 | 打通快手/小红书(client 加方法+profile 改 supported) | 视频号上游 blocked,保持空返回 |
+| 门槛 | 维持按平台分段 | 不做"平台×品类"细分 |
+| 学习算法 | 只铺路:权重门槛搬可写配置 + 回流 fake 验 join + 人审流程约定 | 本体留下期;不接真实回流源;不自动反写上线 |
+| 数据库 | 零改动(已真连库核对) | 不动表结构(仅 performance_feedback 按需补列) |
+
+### V4 复用边界
+
+一句话:V5 **复用 V4 的工程容器,不复用"抖音专属、焊死"那部分**。
+- 复用:graph/runtime/evaluator 框架、`rule_decisions.scorecard` JSON 列、`tests/replay_harness.py`、`score_thresholds.json` 按平台分段样板、`platform_profiles/*.json` 一平台一文件范式。
+- 不继承:抖音专属规则包路径写死、打分权重焊死、游走边目录绑死抖音、四态炸弹。
+
+---
+
+## 3. 模块路线图
+
+| M | 名称 | 主要目标 | 依赖 |
+|---|---|---|---|
+| M0 | 安全网与零变化基准 | 在 v5 分支做;建金标准 case(已拉 v4_douyin_57663)+ 复用 replay_harness | 现状代码 + corpus |
+| M1 | 打地基 | 修四态炸弹 + 边目录解耦成总章程 + 放开评分两维限制 | M0 基准 |
+| M2 | 通机制 | 激活按平台选规则包 + 打分公式搬手册(3处联动)+ 抖音迁标准手册零变化 | M1 |
+| M3 | 填平台手册 | 公众号/小红书建 client+手册;快手/视频号补齐;打通快手/小红书作者作品 | M2 |
+| M4 | 收尾 | 清死配置 + Excel 每平台重组 + 学习算法铺入口 + 回流 fake 验 join | M1-M3 |
+
+---
+
+## 4. 受控变化总原则
+
+| 原则 | 说明 |
+|---|---|
+| 先合同后代码 | 先定评分卡新 schema、手册字段、平台代号口径,再改逻辑 |
+| 等价迁移优先 | M2 先原样搬(数值不改),金标准快照逐条复现=零变化,再谈加平台 |
+| 改行为先贴 diff | 行为中性的批快照零重钉;改行为的批(如快手作者作品)先贴 diff 给用户 |
+| 平台差异显式声明 | 不靠 `if platform==douyin`;靠手册声明"有无该维度/线索" |
+| 删除先归档 | 删配置先 grep 确认无引用;删数据走归档脚本可回灌 |
+| 不打墙③/不上学习本体 | V5 不做游走引擎即插即用、不做学习算法本体,只铺路 |
+
+---
+
+## 5. M0 安全网与零变化基准
+
+**目标**:动手前建好"怎么证明没弄坏 V4"的基准 + 隔离开发环境。
+
+**当前真实状态**:
+- 已在 `v5` 分支(本地+`origin/v5`);`main`/`V4-已完成-已上线`=纯 V4(43d28d69)。
+- 金标准 case 已拉:`tests/fixtures/cases/v4_douyin_57663/input/`(13 文件);110 条决策四分支全(入池20/复看37/技术18/淘汰35);scorecard 完整 V4 三维。
+- 复用机制已存在:`tests/replay_harness.py`(`replay_case()` L63-104、`load_corpus()` L44-50、`CorpusPlatformClient`)、`tests/fixtures/snapshots/`(6 个决策摘要/指纹快照)。
+
+**已拍板**:金标准用 V4 真实 case;只在打分逻辑层比对、不端到端重跑;V3 老快照作废、机制复用数据重建。
+
+**🟠 待拍板**:① 快手两维基准是否再配一条(如 `v1_run_57627_kuaishou_1782549424`);② 金标准 corpus 要不要进 git(已脱敏可提交)。
+
+**本阶段不处理**:不改任何业务代码;不接学习算法。
+
+**涉及文件**:`tests/fixtures/cases/v4_douyin_57663/`、`tests/replay_harness.py`、`tests/fixtures/snapshots/`。
+
+**开发顺序**:① 用 corpus + replay_harness 跑出抖音基线快照并钉死;②(待拍板)补快手两维 case;③ 把"快照逐条比对"接成 M1-M3 每批的回归门。
+
+**验证**:`uv run pytest tests/ -k replay`;基线快照可重放、逐条稳定。
+
+---
+
+## 6. M1 打地基(修炸弹 + 搭总章程 + 放开两维)
+
+**目标**:填平"接新平台就崩"的坑;把游走边目录从抖音专属解耦成平台无关总章程;放开评分卡"只能两维"。三件都不碰抖快视现有打分行为。
+
+**当前真实状态**:
+- 四态炸弹:`walk_graph_json.py:49` `edge_supported` 只认 supported;`:156` `_validate_profile` 只接受 `{supported,blocked}`;非法值在 youtube.json(L76/80/83)、bilibili.json(L96/100)、weixin.json(L76/80/83/87)、github.json(L24-26)、toutiao/zhihu(L11 `_all`)。`walk_engine.py:80` 每次 run 调 `load_profile(platform)` → 这些平台一跑即抛 ValueError。
+- 边目录:`walk_strategy_json.py:87` 硬断言 `strategy_id=="douyin_walk_strategy_v1"`;`walk_graph_json.py:19` `EDGE_CATALOG_PATH` 指抖音文件。
+- 两维锁死:`validate_rule_pack_config.py:99`、`validate_v4_config_contract.py:470` 写死 `keys==["query_relevance","platform_performance"]`。
+
+**已拍板**:四态=能走/屏蔽(blocked)/没接口(no_interface)/将来做(planned);边目录解耦成平台无关全集;数据库零改动。
+
+**🟠 待拍板**:① 四态的具体命名(no_interface/planned 还是别的词);② `edge_supported` 对 no_interface/planned 的语义(都按"不走"处理?);③ toutiao/zhihu 的 `_all` 简写是改成逐边声明还是保留并在校验器特判。
+
+**可先按当前默认值推进**:四态语义=只有 supported 才走,其余三态都跳过留痕(与现状兼容)。
+
+**本阶段不处理**:不动 evaluator 打分逻辑;不接新平台 client;不改抖快视行为。
+
+**涉及文件**:`walk_graph_json.py`(校验器+edge_supported)、`walk_strategy_json.py`(strategy_id 断言)、`validate_rule_pack_config.py`/`validate_v4_config_contract.py`(两维)、`platform_profiles/*.json`(7 个非法状态值规范化)、`walk_graph.json`/`douyin_walk_strategy.v1.json`(边目录解耦)。
+
+**字段合同**:profile `edges.<edge>.status` 取值域 supported|blocked|no_interface|planned;边目录全集新增"平台无关"标识,去 douyin strategy_id 硬绑(放宽成 `*_walk_strategy_v1` 或独立 catalog)。
+
+**开发顺序**:① 校验器状态白名单 2→4 + 处理 `_all`;② 规范化 7 个 profile 的非法值;③ 放宽 strategy_id 断言/解耦 EDGE_CATALOG_PATH;④ 放开两维校验脚本;⑤ 跑金标准快照零变化 + 全测试绿。
+
+**验证**:`uv run pytest`;`load_profile("bilibili")` 不再崩;抖音金标准快照逐条零变化。
+
+**失败归因**:profile 校验仍崩→白名单/`_all` 没覆盖;抖音快照变了→误碰了打分(本阶段不该碰)。
+
+---
+
+## 7. M2 通机制(激活每平台规则包 + 打分公式搬手册 + 抖音迁标准手册)
+
+**目标**:激活"按平台选规则包"内建开关;打分配比从代码搬进手册;抖音先迁成第一本标准手册且**行为零变化**。
+
+**当前真实状态**:
+- 规则包写死:`policy_json.py:17`(路径)、`:95`(默认 douyin)、`:121/154`(字面量)。多平台派发机制已内建:`_select_dispatch`/`_enabled_dispatches`(`policy_json.py:88-126`),规则包 `rule_pack_dispatch` 段已带 platform 字段但仅 1 条 enabled。
+- 打分配比焊死 3 处:`evaluator.py:226`(非抖音 0.5/0.5)、`:239`(抖音 0.35/0.35/0.30)、`:242`(抖音不完整 35/35);`validation.py:969/971/973`(跑验反算副本);`flow_ledger_service.py:1500/1506`(前端展示副本)。
+- 门槛已配置化样板:`score_thresholds.json`(default+douyin 段),`evaluator.py:292-300` `_v4_thresholds` 合并。
+
+**已拍板**:抖音 35/35/30、非抖音 0.5/0.5 原样搬配置(数值不改);抖音迁移行为零变化作基线;3 处副本联动改。
+
+**🟠 待拍板**:① 策略手册粒度——打分+游走合一本 vs 分两本(草稿推荐合一本);② 接口档案(profile)与策略手册关系——分离 vs 合并(推荐分离);③ 规则包目标路径/命名(`rule_packs/{平台}.json`?)。
+
+**本阶段不处理**:不接新平台;不改游走预算(留 M1 已做的边目录/M4 的预算分段);不动门槛数值。
+
+**涉及文件**:`policy_json.py`(加 platform 参/去 douyin 写死)、`policy_version.py`/`interfaces.py`(协议加 platform)、`evaluator.py`(`_v4_scorecard_total` 改读手册维度+权重)、`run_record/validation.py` + `flow_ledger_service.py`(两份副本联动)、`product_documents/规则包/douyin_rule_packs.v1.json`(迁成标准手册)。
+
+**字段合同**:规则包 scorecard 段新增每维 `weight`/`active`/`platform_scope`;`load_policy_bundle(strategy_version, platform)` 加参;dispatch 按 platform 选。
+
+**开发顺序**:① `load_policy_bundle` 加 platform、路径按平台解析(缺则回退默认);② dispatch 去 douyin 字面量;③ 抖音规则包补 weight/active 字段;④ `_v4_scorecard_total` 改"读维度列表按权重合成";⑤ 同步改 validation/flow_ledger 两副本;⑥ 跑抖音金标准快照**逐条零变化**(核心验收)。
+
+**达到效果**:能按平台选规则包;抖音决策与 V4 分毫不差;改权重只改手册不改引擎。
+
+**验证**:`uv run pytest`;抖音金标准 110 条决策 scorecard/decision 逐条复现;`grep "0.35\|0.30\|platform==" evaluator.py` 打分主路径清零。
+
+**失败归因**:抖音分数变了→搬配置时数值/分流写错;跑验失败→validation 副本没同步。
+
+---
+
+## 8. M3 填平台手册(公众号/小红书优先 + 快手/视频号补齐 + 作者作品打通)
+
+**目标**:多平台真正铺开。新建公众号/小红书 client+手册;快手/视频号补齐手册;打通快手/小红书作者作品。
+
+**当前真实状态**:
+- client 仅 3 个:`douyin.py:143`/`kuaishou.py:121`/`shipinhao.py:127`;小红书/公众号无 client。平台工厂 `run_service.py:572-576` `real_clients` dict 三平台。
+- 7 个 profile 缺 `observable_performance`(打分参数):bilibili/github/toutiao/weixin/xiaohongshu/youtube/zhihu。
+- 作者作品:`kuaishou.py` 无 `fetch_author_works`;`shipinhao.py:340-342` 硬返回 `[]`;抖音 `fetch_author_works`(`douyin.py:143`)是模板。实测(2026-06-26)快手/小红书 blogger 上游可用(各 20 条)。
+- 引擎侧 author_to_works 边 + `_expand_authors` 已就绪,加 client 方法+profile 改 supported 即可,引擎零改。
+
+**已拍板**:公众号/小红书优先;打通快手/小红书作者作品;视频号作者保持空(上游 blocked);头条/知乎不接。
+
+**🟠 待拍板**:① 公众号/小红书谁先做(都标优先,需排序);② 快手/小红书作者作品打通是否算"运作规则变化"需单独贴 diff 确认(方案 A 严格零变化 vs 方案 B 评分零变化+游走增强,前述已倾向 B);③ 公众号图文牵动视频判定链,判定环节怎么降级(图文无视频)。
+
+**本阶段不处理**:不接头条/知乎;不做合集/原声/地理/相似新游走(上游无接口)。
+
+**涉及文件**:新建 `integrations/xiaohongshu.py`/`weixin.py`(参照 kuaishou.py ~300 行);`run_service.py:572`(工厂加分支);新增/补 `platform_profiles/{xiaohongshu,weixin}.json` 的 observable_performance;`kuaishou.py`/`xiaohongshu.py` 加 `fetch_author_works`;`platform_profiles/{kuaishou,xiaohongshu}.json` author_to_works→supported;各平台规则包手册 `rule_packs/{平台}.json`。
+
+**开发顺序**:① 快手 client 加 fetch_author_works + profile 改 supported(最小、引擎零改);② 小红书建 client + fetch_author_works + profile;③ 公众号建 client(图文,接判定链);④ 补 7 平台 observable_performance JSON;⑤ 各平台写打分+游走手册;⑥ 验证三平台(抖快视)快照零变化 + 新平台跑通。
+
+**达到效果**:公众号/小红书能跑完整流程;快手/小红书能顺着作者挖;各平台用各自手册互不影响。
+
+**验证**:`uv run pytest`;抖快视金标准零变化;新平台 smoke(真实接口单发,间隔 15s)。
+
+**失败归因**:新平台字段映射错→normalize 没按平台 raw 结构;老平台快照变→新平台手册污染了共享层。
+
+---
+
+## 9. M4 收尾(清死配置 + Excel 重组 + 学习算法铺入口 + 回流 fake)
+
+**目标**:清 V3 死配置;Excel 改成每平台可维护;给学习算法把"可写入口"留好;回流用假数据验通 join 链路。
+
+**当前真实状态**:
+- 死配置:`douyin_rule_packs.v1.json` scorecard.dimensions 恰两维(50/50)、scoring_rules、thresholds 为 V3 残留(V4 实走 score_thresholds.json + 硬编码权重,搬配置后这些应清)。
+- Excel:`规则包映射配置表.xlsx`(`build_config_from_excel.py:60-73` 8 sheet,dispatch/meta 有 platform 列)、`游走策略配置表.xlsx`(`:78-84` 4 sheet 无 platform 列)。坑:`build_config_from_excel.py:155` 新增行被静默跳过(`if obj is not None`)。
+- 回流:`performance_feedback` 表(`sql/content_agent_schema.sql:496-526` 完整字段)0 写入、无写入器;`database_runtime.py:301` 只读;`rule_decisions.scorecard JSON`(`:158`)已存特征。`learning_review.py` 只统计+待批建议、不反喂。
+- 数据库:真连库核对零改动、无 ENUM/CHECK。
+
+**已拍板**:学习算法本体 V5 不做、只铺路;回流先 fake 验 join;门槛只到平台层;权重门槛改了人审才生效。
+
+**🟠 待拍板**:① Excel 组织——每平台一分页 vs 每平台一独立 Excel(对应草稿待拍 ③);② 死配置是删还是留空壳(建议删,先确认 evaluator V4 路径不读);③ 回流 fake 的 case 用哪条(可复用 M0 的 v4_douyin_57663 的 content_id 造假成绩)。
+
+**本阶段不处理**:不接真实回流源;不做跨 run 学习器;不做自动反写。
+
+**涉及文件**:`douyin_rule_packs.v1.json`(清 V3 段)、两个 Excel + `build_config_from_excel.py`(先改底稿防静默跳过)、`performance_feedback` 写入器(新,fake)、join 校验脚本(新)、`learning_review.py`(可选扩跨 run,留下期)。
+
+**开发顺序**:① 确认 V3 死配置无运行时读取→清掉;② Excel 底稿改造支持加平台行/分页;③ 写 fake performance_feedback 写入器 + 灌假数据;④ 验证假成绩能 join 回 `rule_decisions.scorecard`(命中率报告);⑤ 约定"改权重→人审→写手册生效"流程文档。
+
+**达到效果**:运营能在 Excel 改任一平台手册并生效;死配置清干净;假数据能对回打分记录,学习算法入口就绪。
+
+**验证**:`uv run pytest`;`build_config_from_excel.py --check` 字节等价;fake join 命中率达标。
+
+**失败归因**:Excel 改了不生效→新行被静默跳过(没先改底稿);join 对不上→content_id 关联键口径不一致。
+
+---
+
+## 文末技术附录(小字)
+
+- 颗粒度对齐 12 号;施工级函数/Schema/Test 下沉 `v5_implementation_briefs/M{0-4}/`。
+- 关键证据见各 M"当前真实状态"的 file:line;数据库零改动已真连国内库(`192.168.82.27 / content-deconstruction-supply`)逐表核对。
+- 三层"策略手册"设计、配置文件夹重组方案、各平台游走能力实测(2026-06-26)详见承接的 `13_V5迭代计划草稿.md` 与 `product_documents/全平台游走策略.md`。