prd/01-业务目标与全局Harness.md

@@ -0,0 +1,93 @@
+# 业务目标与全局 Harness
+
+## 1. 业务问题
+
+上游每天产生大量需求词和关联数据，来源包含内部、外部、近期、持续、周期和内容后验等不同维度。这些信号彼此交织，但含义保持正交。
+
+系统不能只做词语归类，也不能只生成一批模型文案。它需要把原始信号稳定转化为平台可以持续使用的需求资产，并通过真实内容表现不断校正判断。
+
+## 2. Harness 的定义
+
+本项目中的 Harness 是一套每天自动运行的业务控制结构。它负责：
+
+- 约束各模块只能在自己的边界内工作；
+- 规定模块之间交换什么业务产物；
+- 保留每一步的输入、输出、reason 和策略版本；
+- 让你参与定义规则，而不参与实现和每日执行；
+- 让模型行为受数据证据和业务定义约束；
+- 让失败、冲突、拒绝和未知状态也可查询；
+- 将下游内容结果和线上表现带回下一日评估。
+
+## 3. 推荐结构
+
+采用“C 分层控制闭环为主干，B 事件机制为变化入口”的结构。
+
+- 分层控制闭环保证每日结果稳定、可比较、可追溯。
+- 事件机制接收外部信号、人工反馈、内容发现和真实表现。
+- 事件不能直接越过模块边界修改正式需求，只能成为新证据或明确的管理指令。
+
+核心结构：
+
+```text
+业务协作与策略控制
+          ↓
+证据收集 → 需求认知 → 评估分配 → 发布、解释与反馈
+                                      ↓
+                           人 / 寻找 Agent
+                                      ↓
+                                 内容承接
+                                      ↓
+                                 真实表现
+                                      ↺ 次日证据
+```
+
+## 4. 每日核心业务产物
+
+### 4.1 每日证据包
+
+当天全部原始信号及其来源、时间、维度、指标、内容、关系和质量状态。
+
+### 4.2 每日需求认知版本
+
+当天形成的标准需求词、平台需求、层级、多点挂靠、关系和 reason。
+
+### 4.3 每日评估结果
+
+每条需求的需求成立度、局部供给优先级、置信度、行动层和变化原因。
+
+### 4.4 每日需求任务包
+
+两个下游共同消费的唯一标准输出。寻找 Agent 使用结构化执行视图，人使用自然语言理解和反馈视图。
+
+### 4.5 每日决策账本
+
+记录运行批次、策略版本、候选接受与拒绝、模块过程、异常、人工操作和最终发布结果。
+
+## 5. 系统边界
+
+### 5.1 系统负责
+
+- 每日自动采集、认知、评估、分配和发布；
+- 基于数据生成 reason；
+- 形成可查询的历史过程；
+- 自动分析需求变化；
+- 生成两个下游视图；
+- 接收人和 Agent 的反馈；
+- 归因内容表现并进入次日闭环。
+
+### 5.2 你负责
+
+- 定义什么是需求；
+- 定义有效来源、维度和业务口径；
+- 定义合并、拆分、多挂靠和关系原则；
+- 定义评价、行动层、探索和后验规则；
+- 审核重要定义变更；
+- 对系统无法自行判断的业务冲突作最终裁决。
+
+### 5.3 系统不负责
+
+- 脱离数据自由推演正式需求；
+- 用模型常识覆盖上游事实；
+- 将一次内容失败直接解释为需求不存在；
+- 无记录地修改历史、定义或评分；
+- 让某个下游私自维护另一套需求口径。

prd/02-模块业务契约.md

@@ -0,0 +1,186 @@
+# 模块业务契约
+
+## 1. 模块一：证据收集 Harness
+
+### 原理
+
+负责完整接收和保存每天变化的事实，不负责判断最终需求。不同维度保持正交，缺失、冲突和迟到数据都有明确语义。
+
+### 输入
+
+- 内外部需求词和原始表达；
+- 外部热度、平台持续热度、去年同期热度、近期热度；
+- 上游提供的关联关系；
+- 内容、视频和语言证据；
+- 真实 ROV/VOV 等后验反馈；
+- 人和寻找 Agent 的反馈；
+- 数据质量、样本量和统计周期信息。
+
+### 处理规则
+
+- 原始数据只追加、不改写；
+- 没有数据不等于数值为零；
+- 冲突数据全部保留；
+- 只保存上游明确给出的关系语义；
+- 重复可以标记，但保留每个来源和出现次数；
+- 迟到数据形成更正版本；
+- 后验首先关联具体内容和需求，再参与汇总。
+
+### 输出
+
+每日证据包。每条证据拥有可引用标识、来源、时间、维度、原值、质量状态和关联对象。
+
+### 你定义
+
+来源清单、维度字典、有效周期、样本要求、反馈类型和质量报警原则。
+
+### 系统执行
+
+采集、格式统一、去重标记、质量检查、来源记录、快照封存和异常隔离。
+
+## 2. 模块二：需求认知与智能汇总 Harness
+
+### 原理
+
+将零散表达组织为可搜索、可执行的平台需求，同时完整保留原始表达和判断过程。
+
+### 三层对象
+
+```text
+原始需求表达 → 标准需求词 → 平台需求
+```
+
+- 原始表达保留上游原文。
+- 标准需求词统一别名和同义表达。
+- 平台需求形成面向内容寻找的业务意图。
+
+### 处理规则
+
+- 识别别名、重复、歧义和同义表达；
+- 依据数据决定合并或拆分；
+- 平台需求可以宽泛，例如“战争”，只要能够在外部平台搜索并具有内容意义；
+- “表象、转发”等没有独立内容意图的词不成为正式需求；
+- 需求可挂靠一个或多个分类节点；
+- 全局树保持父子骨架，横向关系形成图；
+- 上游关联保持原样；
+- 新增语义关系标注为推断关系，并附 reason 和置信度；
+- 推断关系不能单独证明需求成立。
+
+### 输出
+
+每条平台需求包含稳定 ID、当日版本、名称、说明、层级、多条挂靠路径、原始词、搜索扩展、关系、证据、reason、认知置信度和跨日变化。
+
+### 你定义
+
+需求定义、层级含义、合并拆分、多挂靠、关系类型、reason 要求和人工复核边界。
+
+### 系统执行
+
+候选识别、别名统一、合并拆分、多点挂树、关系解释、reason 生成、版本比较和冲突标记。
+
+## 3. 模块三：需求评估与供给分配 Harness
+
+### 原理
+
+评估模块只决定需求当日如何被使用，不删除需求事实和历史。
+
+### 两个核心结果
+
+#### 需求成立度，0～1
+
+回答“这个需求本身有多大概率真实成立”。依据先验信号、来源覆盖、数据一致性、后验验证、跨日稳定性、数据质量和风险。
+
+#### 局部供给优先级，0～1
+
+回答“它在所属主题或树分支中，今天应该获得多少寻找和供给资源”。依据局部冷热、近期变化、供需缺口、已有供给、周期窗口和探索价值。
+
+### 指标规则
+
+- 四项先验和真实 ROV/VOV 分别保留；
+- 所有面向人的展示分数归一化到 0～1；
+- 无后验不按后验为零处理；
+- 后验经过内容质量、曝光、时间、供给量和样本量归因；
+- 关系推断只提供低权重增益；
+- 综合判断可展开到每项贡献、扣减和 reason；
+- 全局冷不等于没有局部供给价值。
+
+### 五类行动层
+
+| 行动层 | 业务含义 | 当日处理 |
+|---|---|---|
+| 保供 | 已验证且持续成立 | 必须保留并持续寻找内容 |
+| 优先 | 当前机会明确 | 重点下发给两个下游 |
+| 定向验证 | 可能成立但缺少关键证据 | 下发明确验证任务 |
+| 探索 | 低分、新需求或冷区机会 | 按分支和配额随机保留 |
+| 抑制 | 持续不支持或明显过供 | 暂停主动供给，保留并等待再激活 |
+
+探索按树分支、新老需求、数据来源、有无后验、冷热区域和需求粒度分层抽样，避免大分支垄断探索额度。
+
+### 你定义
+
+评价维度、后验有效条件、行动层原则、主题额度、探索比例、风险和时间衰减原则。
+
+### 系统执行
+
+每日全量评价、表现归因、跨日稳定处理、行动分层、探索抽样和变化 reason。
+
+## 4. 模块四：发布、可视化与反馈入口 Harness
+
+### 原理
+
+把当日决策变成两个下游可执行、可理解、可反馈的业务产品，而不是只展示一张热力图。
+
+### 标准输出
+
+唯一的每日需求任务包，包含需求 ID、版本、自然语言解释、层级、全部挂靠路径、关系、成立度、局部优先级、行动层、搜索要求、证据、评分过程、已有内容、真实表现、待验证问题和反馈动作。
+
+### 寻找 Agent 视图
+
+明确寻找什么、用什么词、去哪里找、排除什么、什么算命中、验证什么，以及结果关联哪个需求。
+
+### 人的视图
+
+说明需求是什么、为什么值得关注、全局与局部位置、挂靠路径、支持与反对证据、行动层原因、已有内容和证据缺口。
+
+### 可视化尺度
+
+1. 全局冷热图：完整展示热区和冷区，保留树层级。
+2. 局部分支下钻：保持祖先路径与子树结构，观察分支内部冷热。
+3. 单条需求路径：展示全部挂靠点、父节点、祖先和横向关系。
+4. 决策解释：展示证据、认知、评分、行动和下游任务的完整过程。
+
+颜色主要表达 0～1 的局部供给优先级；面积表达需求或证据规模，不能同时混用为热度。
+
+### 你定义
+
+两个下游的发布范围、主题额度、主展示指标、reason 深度、反馈权限和异常提示。
+
+### 系统执行
+
+生成任务包、双下游视图、热力图、需求路径、决策解释和反馈事件。
+
+## 5. 横向模块：业务协作与策略控制 Harness
+
+### 原理
+
+让你通过对话定义、提问、查询、分析和调整整个系统，同时保证修改受控、可预览、可追溯。
+
+### 核心能力
+
+- 回答“为什么 XX 是需求”；
+- 回答“为什么 XX 不是需求”；
+- 查询原始数据、树节点、评分过程、内容、真实表现和历史批次；
+- 自动分析冷热变化、先验后验冲突、证据缺口和策略影响；
+- 展示当前业务定义；
+- 将自然语言修改转成结构化定义草案；
+- 使用历史数据预览影响；
+- 经你确认后形成新策略版本。
+
+### 约束
+
+- 查询默认只读；
+- 无法从数据回答时明确说明证据不足；
+- 临时分析不能自动变成正式规则；
+- 定义修改必须确认后生效；
+- 历史版本不能被覆盖；
+- 保存成功、拒绝、未决和异常的全部业务过程。

prd/03-业务定义与决策规范.md

@@ -0,0 +1,134 @@
+# 业务定义与决策规范
+
+## 1. 需求的定义
+
+平台需求是可以被人或寻找 Agent 理解，并能在外部内容平台搜索、寻找或验证的内容需求。
+
+判断重点不是词语是否宽泛，而是是否具有实际内容意义：
+
+- “战争”可以是需求，因为可以搜索并形成内容供给；
+- “抗日战争中的诗词创作”可以是更具体的需求；
+- “表象、转发”等没有独立内容意图的词不是正式需求。
+
+## 2. 证据三层规范
+
+### 2.1 原始事实
+
+上游需求词、时间、来源、指标、关联、视频、真实 ROV/VOV 和人工反馈原文。
+
+### 2.2 可计算结论
+
+热度变化、局部位置、供需缺口、共同出现、样本量、稳定性和冲突。
+
+### 2.3 模型解释
+
+合并 reason、拆分 reason、挂靠 reason、关系语义、自然语言需求和分析结论。
+
+模型解释必须引用前两层；没有数据锚点的自由推演不能成为正式需求。
+
+## 3. 树和图规范
+
+- 全局分类树是稳定骨架；
+- 分类节点保持明确父子关系；
+- 需求是独立图节点；
+- 一条需求可以挂靠多个分类节点；
+- 多条挂靠路径全部保留；
+- 跨树关系用关系线表达；
+- 关系保存类型、来源、reason、置信度、审核状态和有效时间；
+- 上游只有“关联”时，不擅自升级语义；
+- 模型新增语义必须标记为推断。
+
+## 4. 合并与拆分规范
+
+### 4.1 可以合并
+
+- 明确别名或同义表达；
+- 指向相同内容意图且证据高度重合；
+- 合并后仍能完整追溯每个原始表达。
+
+### 4.2 应当拆分
+
+- 同一词在不同语境表达不同意图；
+- 下游搜索方式、目标内容或评价方式显著不同；
+- 合并后会让 reason 或后验归因失真。
+
+### 4.3 无法确定
+
+分别保留，记录候选关系和证据缺口，不强行合并。
+
+## 5. reason 规范
+
+reason 不是模型总结句，必须回答具体问题：
+
+- 使用了哪些事实；
+- 做了什么判断；
+- 命中了哪条业务定义；
+- 哪部分是模型推断；
+- 有哪些反对或缺失证据；
+- 为什么与昨日不同；
+- 什么新证据可能改变结论。
+
+## 6. “不是需求”的规范
+
+系统必须保存负向判断，区分：
+
+| 类型 | 含义 | 后续处理 |
+|---|---|---|
+| 语义不成立 | 没有独立内容意图 | 保留拒绝原因，可因定义变更重算 |
+| 证据不足 | 可能是需求但依据不足 | 进入候选或探索 |
+| 重复合并 | 已被另一需求吸收 | 保留原表达和目标需求 |
+| 暂时抑制 | 需求成立但当前不供给 | 等待新信号或时间窗口 |
+| 待人工判断 | 规则或数据冲突 | 进入业务复核队列 |
+
+## 7. 后验规范
+
+- 真实 ROV/VOV 是内容上线后的需求验证信号；
+- 内容与需求必须建立多对多映射；
+- 区分主需求、辅助需求和覆盖程度；
+- 单条内容差不能直接否定需求；
+- 归因考虑内容质量、标题封面、表达方式、流量、发布时间、竞争、供给量和样本量；
+- 没有后验不等于后验表现差；
+- 只有形成有效样本后才提高后验权重；
+- 历史后验随时间衰减；
+- 已验证需求仍需持续复验。
+
+## 8. 评分与展示规范
+
+- 需求成立度和局部供给优先级分别展示；
+- 所有展示分归一化为 0～1；
+- 各原始维度独立保留；
+- 分数必须能展开计算过程；
+- 样本不足通过置信度表达，不用错误的零分表达；
+- 局部冷热和全局位置同时保留；
+- 颜色只承载一个主要热度含义；
+- 冷区不得因低分被隐藏。
+
+## 9. 版本规范
+
+下列对象均需版本化：
+
+- 每日证据快照；
+- 平台需求认知结果；
+- 业务定义和策略；
+- 每日评估和行动层；
+- 需求任务包；
+- 人工管理指令；
+- 内容归因结果。
+
+新版本不能覆盖旧版本，每个变化都要记录原因和影响范围。
+
+## 10. 尚需通过历史数据校准的业务参数
+
+以下参数不在总纲阶段固定数值，由你在策略控制台中基于历史模拟确认：
+
+- 各来源的可信权重；
+- 后验最小有效样本；
+- 五类行动层的进入与退出条件；
+- 各主题每日供给额度；
+- 探索比例和分层抽样配额；
+- 历史衰减周期；
+- 快速升级和连续降级条件；
+- 关系增益上限；
+- 需要人工复核的置信度范围。
+
+这些参数必须属于策略版本，而不是散落在模型提示或执行过程中的隐含规则。

prd/04-当前代码基础与问题.md

@@ -0,0 +1,74 @@
+# 当前代码基础与问题
+
+## 1. 可复用基础
+
+| 当前能力 | 对目标 Harness 的价值 |
+|---|---|
+| 自研 Agent、Tool、Skill | 可承载归类、汇总、寻找、解释和分析角色 |
+| Agent 的 log、JSONL、HTML 和 OSS 留档 | 可演进为业务决策账本的运行基础 |
+| ODPS、MySQL、OSS 链路 | 具备每日自动处理数据的基础设施 |
+| 全局分类树及树下元素 | 可继续作为需求理解的稳定骨架 |
+| 四项先验 | 已覆盖外部、持续、周期和近期视角 |
+| 真实 ROV/VOV | 已具备后验闭环入口 |
+| 需求词归类 Agent | 已开始连接原始词和分类树 |
+| `generated_demand` | 已开始形成平台需求对象 |
+| 分类树热度向上汇总 | 具备局部到全局的观察基础 |
+| Vue 热力图和视频下钻 | 已验证树形观察与内容证据下钻方向 |
+| 定时任务 | 具备自动执行基础 |
+
+## 2. 主要业务问题
+
+### 2.1 缺少统一每日运行批次
+
+当前是若干定时任务，不是可整体查询、重放和比较的每日业务运行。
+
+### 2.2 证据与结论未彻底分层
+
+指标较多直接进入业务表，缺少不可变证据快照、来源版本、缺失语义和冲突保留。
+
+### 2.3 三层需求对象没有贯通
+
+需求词、`generated_demand` 和下游任务包没有形成统一生命周期；主展示对象仍是需求词。
+
+### 2.4 多挂靠与关系图未落入正式业务结构
+
+当前一个需求词只能保存一个分类节点，缺少关系类型、reason、置信度、审核状态和版本。
+
+### 2.5 评估仍是先验热度加总
+
+当前全局分只合成四项先验；真实 ROV/VOV 未进入最终决策，也没有成立度、局部优先级、行动层、探索和跨日稳定机制。
+
+### 2.6 后验尚未完成需求归因
+
+虽有关联视频和真实 ROV/VOV，但缺少内容主辅需求、覆盖度、质量、分发环境及归因后的有效贡献。
+
+### 2.7 寻找 Agent 尚未形成稳定下游
+
+搜索和视频分析已有基础，但保存、历史查询、标准任务输入和结果回流未形成完整契约。
+
+### 2.8 缺少策略中心和业务对话入口
+
+业务定义散落在提示、任务和页面逻辑中，无法集中展示、解释、版本化或安全修改。
+
+### 2.9 缺少负向决策记录
+
+没有结构化保存拒绝、证据不足、重复合并和待人工判断的候选，因而无法可靠回答“为什么不是需求”。
+
+### 2.10 稳定性保障不足
+
+缺少正式测试体系；部分同步以总行数是否相同判断数据变化，存在内容变化未同步的风险。
+
+## 3. 总体判断
+
+当前仓库是“数据管道 + 若干业务 Agent + 分类树热力展示”的有效原型，但还不是完整业务 Harness。
+
+演进重点不是推翻已有能力，而是：
+
+1. 用每日运行批次组织现有任务；
+2. 用证据包隔离原始事实；
+3. 让平台需求成为核心业务对象；
+4. 建立成立度、局部优先级和行动层；
+5. 打通标准任务包、内容归因和次日反馈；
+6. 用业务协作控制台集中定义和解释。
+
+更细的代码结构事实见仓库根目录的 `zhangbo.md`。

prd/05-每日运行与历史追踪.md

@@ -0,0 +1,101 @@
+# 每日运行与历史追踪
+
+## 1. 每日运行原则
+
+每天自动执行一次完整业务闭环，因为上游需求数据、外部信号和后验反馈都按天变化。
+
+业务上每天对全部有效需求重新评价；执行层可以只计算变化部分，但必须产出完整的当日结果快照。
+
+## 2. 每日运行阶段
+
+```text
+冻结当日输入和策略版本
+→ 形成每日证据包
+→ 生成每日需求认知版本
+→ 全量评估成立度和局部优先级
+→ 形成行动层与探索样本
+→ 发布标准需求任务包
+→ 两个下游寻找并关联内容
+→ 接收内容表现和人工反馈
+→ 进入次日证据
+```
+
+## 3. 每日运行记录
+
+每个运行批次必须记录：
+
+- 日期和唯一批次标识；
+- 输入数据快照；
+- 使用的定义与策略版本；
+- 各模块开始、完成和异常状态；
+- 每一步中间产物；
+- 每条候选的接受、拒绝或未决过程；
+- 模型输入、输出及引用证据；
+- 自动重试和人工操作；
+- 最终发布的需求任务包；
+- 与前一日的变化及 reason；
+- 后续内容和表现回流情况。
+
+## 4. 异常原则
+
+### 4.1 某项上游数据缺失
+
+标记该维度缺失和置信度变化，不把它当作零，不阻断其他有效维度。
+
+### 4.2 数据迟到
+
+形成更正批次，并说明影响哪些需求；不覆盖原始日版本。
+
+### 4.3 模型步骤失败
+
+保留已完成中间结果，自动重试；仍失败则进入异常队列，不伪造结论。
+
+### 4.4 某个模块整体失败
+
+不得静默发布不完整结果。系统说明缺失模块、影响范围和当前可用的最后稳定版本。
+
+### 4.5 数据冲突
+
+保留冲突证据，降低置信度或进入人工复核，不擅自删除一方。
+
+## 5. 跨日稳定原则
+
+- 没有新数据也是一种日状态；
+- 突发信号可以快速升级；
+- 普通降级需要连续多日证据；
+- 历史信号和后验按策略逐渐衰减；
+- 行动层变化都要生成 reason；
+- 周期需求在窗口到来前可以重新激活；
+- 抑制需求永不物理删除。
+
+## 6. 定义修改流程
+
+```text
+自然语言修改要求
+→ 结构化定义草案
+→ 修改前后差异
+→ 历史数据影响模拟
+→ 风险与影响范围
+→ 你明确确认
+→ 新策略版本
+→ 下一每日批次生效
+```
+
+紧急情况可以发起临时批次，但仍保存完整策略版本和影响记录。
+
+## 7. 历史查询能力
+
+支持按以下入口查询：
+
+- 需求；
+- 候选词；
+- 分类节点；
+- 内容；
+- 日期或运行批次；
+- 业务定义；
+- 策略版本；
+- 人工操作；
+- Agent 执行；
+- 异常类型。
+
+系统应能重建任意一天“当时看到什么数据、依据什么规则、为什么得到这个结果”。

prd/06-下游应用与反馈闭环.md

@@ -0,0 +1,102 @@
+# 下游应用与反馈闭环
+
+## 1. 一份任务包，两个应用
+
+寻找 Agent 和人不得维护各自独立的需求池。两者共同消费同一份每日标准需求任务包，只生成不同视图。
+
+## 2. 寻找 Agent
+
+### 输入视图
+
+- 需求 ID 和版本；
+- 搜索词、扩展词和排除词；
+- 目标平台和内容类型；
+- 全部挂靠路径和相关关系；
+- 当日优先级和行动层；
+- 命中判定条件；
+- 需要验证的假设；
+- 已有内容和证据缺口。
+
+### 输出
+
+- 内容链接、平台和时间；
+- 命中的需求；
+- 主需求或辅助需求；
+- 命中依据和覆盖程度；
+- 未找到的原因；
+- 新发现的候选需求；
+- 可进一步使用的语言和内容证据。
+
+寻找 Agent 只能报告发现，不能直接修改正式需求。
+
+## 3. 人的应用
+
+### 需求理解
+
+人能看到需求自然语言说明、全局和局部冷热、全部路径、reason、数据贡献、内容和历史变化。
+
+### 内容寻找
+
+人依据需求寻找内容，并将内容关联回需求。
+
+### 反馈
+
+人可以反馈：
+
+- 新需求；
+- 新挂靠点；
+- 合并或拆分建议；
+- reason 错误；
+- 相关内容；
+- 当前业务判断；
+- 数据或分析问题。
+
+普通反馈作为新证据；明确的管理指令才直接改变当日状态，并保留审计记录。
+
+## 4. 内容承接关系
+
+需求和内容是多对多关系：
+
+- 一条需求可以由多条内容承接；
+- 一条内容可以承接多个需求；
+- 必须区分主需求与辅助需求；
+- 必须记录每个需求的覆盖程度；
+- 必须记录内容上线时间、供给数量和有效样本状态。
+
+## 5. 内容表现归因
+
+真实 ROV/VOV 是原始后验，不直接等于需求表现。
+
+归因时至少考虑：
+
+- 内容质量；
+- 标题、封面和表达方式；
+- 分发曝光；
+- 发布时间；
+- 平台环境；
+- 同类竞争；
+- 当前供给量；
+- 内容对需求的覆盖程度；
+- 样本量和多条内容一致性。
+
+归因输出包括：
+
+- 内容原始表现；
+- 内容和分发条件；
+- 可归因给需求的有效反馈；
+- 归因置信度；
+- 支持、反对或暂不判断；
+- 对次日成立度和优先级的影响建议。
+
+## 6. 协作控制台
+
+人可以提问：
+
+- 为什么 XX 是需求？
+- 为什么 XX 不是需求？
+- 为什么它今天变热或变冷？
+- 哪项原始数据影响最大？
+- 为什么真实 ROV/VOV 没有改变等级？
+- 某条定义修改后会影响哪些需求？
+
+回答必须直接查询数据和历史过程，并区分数据事实、计算发现和模型解释。证据不足时明确说明，不得自由补全。

prd/07-核心业务图.md

@@ -0,0 +1,144 @@
+# 核心业务图
+
+## 1. 全局业务 Harness
+
+```mermaid
+flowchart TB
+    GOV[业务协作与策略控制 Harness<br/>定义·提问·查询·分析·版本管理]
+
+    subgraph DAILY[每日自动全量业务运行]
+        E[① 证据收集<br/>每日证据包]
+        C[② 需求认知与智能汇总<br/>平台需求当日版本]
+        A[③ 评估与供给分配<br/>成立度·局部优先级·行动层]
+        P[④ 发布、可视化与反馈<br/>标准需求任务包]
+        E --> C --> A --> P
+    end
+
+    GOV -.策略版本.-> E
+    GOV -.定义与规则.-> C
+    GOV -.评分与配额.-> A
+    GOV -.展示与权限.-> P
+
+    P --> FA[寻找 Agent 视图]
+    P --> HU[人的工作视图]
+    FA --> CL[统一内容承接账本]
+    HU --> CL
+    CL --> PF[真实线上表现<br/>真实 ROV/VOV 等]
+    PF --> AT[表现归因<br/>质量·流量·样本·覆盖度]
+    AT --> EV[反馈事件]
+    HU --> EV
+    FA --> EV
+    EV --> E
+
+    LEDGER[(全过程业务决策账本)]
+    E -.过程与产物.-> LEDGER
+    C -.过程与产物.-> LEDGER
+    A -.过程与产物.-> LEDGER
+    P -.过程与产物.-> LEDGER
+    GOV -.定义与操作.-> LEDGER
+```
+
+## 2. 树为骨架、需求为图节点
+
+```mermaid
+flowchart LR
+    ROOT[全局分类树]
+    H[历史]
+    PERSON[历史人物]
+    WAR[战争]
+    LIT[文学创作]
+    EMO[人物情感]
+
+    ROOT --> H
+    H --> PERSON
+    H --> WAR
+    H --> LIT
+    H --> EMO
+
+    M[毛泽东]
+    K[抗日战争]
+    L[解放战争]
+    POEM[写诗]
+    D[平台需求<br/>毛泽东在战争时期的诗词创作]
+
+    PERSON --> M
+    WAR --> K
+    WAR --> L
+    LIT --> POEM
+
+    D -.挂靠点 1.-> M
+    D -.挂靠点 2.-> K
+    D -.挂靠点 3.-> L
+    D -.挂靠点 4.-> POEM
+    M ---|上游关联或推断关系<br/>保留类型、reason、置信度| K
+    M --- L
+    M --- POEM
+```
+
+## 3. 需求—内容—表现闭环
+
+```mermaid
+flowchart LR
+    D[平台需求<br/>先验与认知依据] --> T[每日需求任务包]
+    T --> F1[寻找 Agent]
+    T --> F2[人]
+    F1 --> C[找到或生产内容]
+    F2 --> C
+    C --> M[需求—内容映射<br/>主/辅需求·覆盖程度]
+    M --> O[上线与分发]
+    O --> R[真实表现<br/>真实 ROV/VOV]
+    R --> A[归因校正<br/>内容质量·流量·时间·样本·供给]
+    A --> B[有效需求反馈<br/>支持·反对·暂不判断]
+    B --> N[次日证据包]
+    N --> D
+```
+
+## 4. 需求判断链
+
+```mermaid
+flowchart LR
+    R[原始事实] --> K[可计算结论]
+    K --> X[模型解释]
+    X --> D{是否形成平台需求}
+    D -->|是| Y[正式需求<br/>多挂靠·reason·认知置信度]
+    D -->|重复| M[合并并保留原表达]
+    D -->|证据不足| C[候选/探索]
+    D -->|语义不成立| N[负向决策记录]
+    D -->|冲突| H[人工复核]
+```
+
+## 5. 每日评估与行动分配
+
+```mermaid
+flowchart TB
+    P[四项先验] --> S[需求成立度 0～1]
+    V[归因后的真实 ROV/VOV] --> S
+    Q[数据质量与一致性] --> S
+    S --> D[每日业务决策]
+
+    L[局部冷热与供需缺口] --> U[局部供给优先级 0～1]
+    C[已有内容与供给量] --> U
+    W[周期窗口与探索价值] --> U
+    U --> D
+
+    D --> G1[保供]
+    D --> G2[优先]
+    D --> G3[定向验证]
+    D --> G4[分层探索]
+    D --> G5[抑制但保留]
+```
+
+## 6. 对话修改定义
+
+```mermaid
+flowchart LR
+    U[你的自然语言要求] --> D[结构化定义变更草案]
+    D --> C[修改前后差异]
+    C --> S[历史数据影响模拟]
+    S --> R[风险和影响范围]
+    R --> A{你是否确认}
+    A -->|否| D
+    A -->|是| V[生成新策略版本]
+    V --> N[下一每日批次生效]
+    N --> H[保留完整历史与效果比较]
+```

prd/README.md

@@ -0,0 +1,60 @@
+# SupplyAgent 业务 PRD 总纲
+
+## 1. 文档定位
+
+本目录是 SupplyAgent 的业务核心大纲，定义“为什么建设、系统每天做什么、各模块如何协作、业务人员如何参与、两个下游如何使用，以及内容表现如何反向优化需求”。
+
+本文档集只定义业务 Harness，不规定具体代码、数据库、接口或模型实现。
+
+## 2. 核心目标
+
+SupplyAgent 每天自动接收变化的需求信号、外部信号和后验反馈，在不破坏原始信息的前提下，形成分层、可解释、可追溯的平台需求，并输出给寻找 Agent 和人使用。
+
+系统最终形成：
+
+- 一张以全局分类树为稳定骨架、允许需求多点挂靠和跨树关联的需求图；
+- 数百条可搜索、可执行的平台需求；
+- 每条需求完整的来源、路径、reason、评价过程和历史版本；
+- 面向寻找 Agent 和人的统一需求任务包；
+- “需求—内容—表现—次日需求”的自动反馈闭环；
+- 一个可提问、查数据、做分析、查看历史和修改业务定义的协作控制台。
+
+## 3. 已确认的核心原则
+
+1. 原始事实与系统决策分开，原始信息只追加、不覆盖。
+2. 评估只决定当日如何使用需求，不删除需求历史。
+3. 两个下游消费同一份标准需求任务包，只使用不同视图。
+4. 人的普通反馈先作为证据；明确管理指令才改变业务状态。
+5. 同时评价“需求成立度”和“局部供给优先级”，不使用一个黑盒总分替代所有判断。
+6. 每日全量评估，底层允许增量执行。
+7. 模型只能组织、解释和分析数据，不能脱离数据制造正式需求。
+8. 系统以分层控制闭环为主干，以事件机制承接每日变化和反馈。
+9. 所有业务定义和策略版本化。
+10. 对话修改定义必须先形成草案和影响预览，经确认后生效。
+
+## 4. 文档导航
+
+| 文件 | 内容 |
+|---|---|
+| [01-业务目标与全局Harness.md](01-业务目标与全局Harness.md) | 系统边界、总体结构和关键业务产物 |
+| [02-模块业务契约.md](02-模块业务契约.md) | 五个模块的原理、输入、输出和职责 |
+| [03-业务定义与决策规范.md](03-业务定义与决策规范.md) | 需求、证据、关系、评价、行动层和版本规范 |
+| [04-当前代码基础与问题.md](04-当前代码基础与问题.md) | 当前仓库的优点、缺点及与目标的差距 |
+| [05-每日运行与历史追踪.md](05-每日运行与历史追踪.md) | 每日运行批次、异常、历史和策略变更 |
+| [06-下游应用与反馈闭环.md](06-下游应用与反馈闭环.md) | 寻找 Agent、人、内容映射和后验归因 |
+| [07-核心业务图.md](07-核心业务图.md) | 全局 Harness、需求图、闭环和定义变更图 |
+
+## 5. 业务成功标准
+
+系统达到目标时，应能稳定回答：
+
+- 今天形成了哪些平台需求，为什么？
+- 哪些候选没有形成需求，为什么？
+- 每条需求来自哪些原始数据和关系？
+- 它挂在树的哪些位置，为什么允许多点挂靠？
+- 它在全局和局部分支中是热还是冷？
+- 它为什么进入当前行动层？
+- 人和寻找 Agent 今天应该寻找什么内容？
+- 找到的内容承接了哪些需求？
+- 真实 ROV/VOV 如何经过归因后影响次日判断？
+- 某条定义何时修改、由谁确认、影响了哪些历史结果？

zhangbo.md

@@ -0,0 +1,809 @@
+# SupplyAgent 代码仓库结构总结
+
+## 1. 阅读基线
+
+本文档完全基于当前代码仓库重新阅读后形成，不继承此前对项目的业务推演或可视化设计理解。
+
+代码快照：
+
+- 分支：`feature/zhangbo`
+- 阅读时提交：`2ab77ce`
+- Python 要求：`>= 3.11`
+- 后端：FastAPI + SQLAlchemy 2.x + PyMySQL
+- Agent：OpenRouter/OpenAI 兼容 API + 自研 Tool/Skill/ReAct 框架
+- 数据源：ODPS（MaxCompute）
+- 数据库：MySQL
+- 对象存储：阿里云 OSS
+- 前端：Vue 3 + TypeScript + Vite
+
+`.env` 已被 `.gitignore` 忽略。本文不会记录其中的密码、密钥、数据库地址或 Token。
+
+---
+
+## 2. 当前项目的实际定位
+
+当前 SupplyAgent 由两部分组成：
+
+1. 一套通用 AI Agent 运行框架；
+2. 一套围绕“需求词、全局分类树、热度、视频和需求生成”的业务系统。
+
+业务系统当前主要完成：
+
+- 从 ODPS 同步全局分类树和树下元素；
+- 从 ODPS 同步多策略需求池；
+- 将需求词挂到分类树节点；
+- 汇总四项先验热度和真实 ROV/VOV；
+- 把词级热度沿分类树向上聚合；
+- 按单一热度维度生成并保存平台需求；
+- 把需求词连接到真实视频和视频最终选题；
+- 通过 API 和 Vue 页面展示分类树、热力图和下钻证据；
+- 记录 Agent 完整执行过程，生成 HTML，上传 OSS 并在 MySQL 留档。
+
+当前系统的核心业务链路是：
+
+```text
+ODPS 全局分类与元素
+        ↓
+MySQL 全局分类树
+        ↑
+需求池词语 → 归类 Agent → 需求词挂靠
+        ↓
+四项先验 + 真实 ROV/VOV
+        ↓
+词级统计 → 分类树节点聚合 → 四维全局排名
+        ↓
+需求生成 Agent → generated_demand
+        ↓
+FastAPI → Vue 分类树/热力图/证据下钻
+```
+
+---
+
+## 3. 仓库分层
+
+```text
+SupplyAgent/
+├── supply_agent/       通用 Agent 框架
+├── agents/             业务 Agent 和专属工具
+├── supply_infra/       MySQL、ODPS、OSS、定时任务
+├── api/                FastAPI 查询接口和静态前端托管
+├── web/                Vue 3 业务前端
+├── jobs/               数据任务的手动 CLI 入口
+├── scripts/            部署、日志上传、日志可视化脚本
+├── visualization/      早期/独立的业务设计可视化材料
+├── Dockerfile          前端构建 + Python 运行镜像
+├── pyproject.toml      Python 包、依赖和命令入口
+└── requirements.txt    另一份运行依赖清单
+```
+
+模块之间的依赖方向：
+
+```text
+web
+  ↓ HTTP
+api
+  ↓
+supply_infra.db.repositories
+  ↓
+MySQL
+
+agents
+  ↓
+supply_agent（Agent 框架）
+  ↓
+supply_infra（数据库/ODPS/OSS）
+
+jobs / scheduler
+  ↓
+supply_infra.scheduler.jobs
+  ↓
+ODPS + MySQL + 业务 Agent
+```
+
+---
+
+## 4. 通用 Agent 框架：`supply_agent/`
+
+### 4.1 `supply_agent/config.py`
+
+负责 Agent 侧配置：
+
+- OpenRouter API Key、模型和 Base URL；
+- Agent 最大迭代次数和温度；
+- Skills 目录；
+- 日志目录和日志开关。
+
+配置来自环境变量或项目根目录 `.env`，相对路径会解析到项目根目录。
+
+### 4.2 `supply_agent/llm/client.py`
+
+基于 OpenAI Python SDK 连接 OpenRouter，提供：
+
+- 同步对话 `chat`；
+- 异步对话 `achat`；
+- 同步文本流 `stream`；
+- 异步文本流 `astream`；
+- Tool Calling；
+- OpenRouter reasoning effort；
+- LLM 输入和输出日志。
+
+模型可以在运行时切换。
+
+### 4.3 `supply_agent/tools/`
+
+`base.py` 提供：
+
+- `@tool` 装饰器；
+- 从 Python 函数签名生成 JSON Schema；
+- Optional 和基础类型转换；
+- 同步/异步工具执行；
+- 异常转为 JSON 错误结果。
+
+`registry.py` 提供：
+
+- 工具注册、删除和查询；
+- OpenAI ToolDefinition 列表；
+- 根据模型返回的工具名执行工具；
+- 同步和异步执行；
+- 批量注册被 `@tool` 装饰的函数。
+
+### 4.4 `supply_agent/skills/`
+
+Skill 机制读取指定目录下的 `SKILL.md`：
+
+- 支持 YAML frontmatter 的名称和描述；
+- 启动时把 Skill 目录作为目录索引加入系统提示词；
+- Agent 通过内置 `load_skill` 工具按需加载全文；
+- Skill 加载后会重建系统消息并注入当前上下文。
+
+当前仓库根目录的 `skills/` 被 `.gitignore` 忽略，因此代码支持 Skill，但仓库没有可随代码分发的业务 Skill 内容。
+
+### 4.5 `supply_agent/agent/`
+
+`core.py` 的 `Agent` 负责组装：
+
+- LLMClient；
+- ToolRegistry；
+- SkillRegistry；
+- AgentLoop；
+- AgentLogger。
+
+对外提供：
+
+- `run`；
+- `arun`；
+- `stream`；
+- `astream`。
+
+`loop.py` 实现标准 ReAct/Tool Calling 循环：
+
+```text
+系统消息 + 对话历史
+        ↓
+调用 LLM
+        ↓
+有工具调用？──否──→ 返回最终结果
+        │是
+        ↓
+执行工具并写入 Tool Message
+        ↓
+下一轮 LLM
+```
+
+达到最大迭代次数时，同步和普通异步运行会追加一条用户消息，要求模型给出当前最佳答案；流式路径则直接发出 Max iterations reached。
+
+### 4.6 `supply_agent/logging/`
+
+每次 Agent 运行生成：
+
+- 人类可读 `.log`；
+- 结构化 `.jsonl`。
+
+日志记录：
+
+- run_start；
+- 完整 LLM 输入；
+- 模型输出和 reasoning；
+- 工具调用参数和结果；
+- Skill 加载；
+- run_end。
+
+运行结束后：
+
+1. 将日志渲染成 HTML；
+2. 上传 `.log`、`.jsonl`、`.html` 到 OSS；
+3. 把 HTML 公网地址写入 `oss_logs`；
+4. 上传失败只记录错误，不影响 Agent 主结果。
+
+---
+
+## 5. 三个业务 Agent
+
+## 5.1 `demand_belong_category_agent`
+
+目标：把需求词挂到真实存在的全局分类树节点。
+
+工具：
+
+- `query_global_tree_category`：读取整棵树或指定子树；
+- `batch_insert_demand_belong_category`：批量写入需求词、分类 ID 和原因。
+
+业务流程：
+
+1. 查看顶层分类；
+2. 选择最相关分支；
+3. 逐层下钻；
+4. 不确定时停在更可靠的上层节点；
+5. 将结果写入 `demand_belong_category`。
+
+系统提示允许一个词选择一个或多个高置信节点，但当前数据库和写入工具以 `name` 唯一：
+
+- `demand_belong_category.name` 有唯一约束；
+- 同一次请求也按 name 去重；
+- 因此当前实现实际上只能保存“一词一个分类节点”；
+- 多挂靠尚未在当前表结构中实现。
+
+定时任务会把新需求词按 100 个一批交给该 Agent。
+
+## 5.2 `generate_demand_agent`
+
+目标：从分类树局部热度和已挂靠需求词中，按单一维度生成平台需求结果。
+
+支持的来源维度只有四项先验：
+
+- `ext_pop`：外部热度；
+- `plat_sust_pop`：平台持续热度；
+- `plat_ly_pop`：平台去年同期热度；
+- `recent_pop`：近期热度。
+
+一次运行只允许处理一个维度。
+
+工具：
+
+- `query_latest_biz_dt`：取两张统计表都有数据的最新日期；
+- `query_category_tree_by_dim`：查看指定维度有数据的树；
+- `query_category_leaves_by_dim`：定位有数据的叶子节点；
+- `query_demand_words_by_category`：查询节点或子树下的真实需求词；
+- `query_category_path`：补充根到节点的路径；
+- `batch_save_generated_demands`：写入 `generated_demand`。
+
+输出结构固定为：
+
+```text
+source_dim
+  └── overall_direction
+        └── summary_event
+              └── demand_name
+```
+
+重要约束：
+
+- `demand_name` 必须原样来自 `demand_belong_category.name`；
+- Agent 不能新造需求词；
+- `summary_event` 尽量对应一个需求，最多轻量合并 2～3 个强相关需求；
+- 写入时保存类目、路径、维度 avg/count 快照、reason、业务日和 run_id；
+- 同一次工具调用按 `(source_dim, demand_name)` 去重；
+- 当前 `generated_demand` 没有数据库唯一约束，不同 run 可以重复生成相同需求。
+
+真实 ROV/VOV 当前不属于该 Agent 的 `source_dim`，也没有参与其单维生成工具链。
+
+## 5.3 `find_agent`
+
+目标：搜索和解析抖音视频。
+
+当前真正注册的工具只有：
+
+- `douyin_search`：调用外部抖音关键词搜索服务；
+- `douyin_detail`：按 content_id 获取视频详情和可播放地址；
+- `qwen_video_analyze`：调用千问视频模型解析视频。
+
+搜索和详情接口有约 10 秒的请求间隔限制。
+
+当前系统提示还要求调用：
+
+- `save_video_content`；
+- `query_video_content`。
+
+但仓库中没有这两个工具，也没有被注册。因此当前 `find_agent` 能搜索、取详情和解析视频，但不能按提示完成内容入库或历史查询。
+
+---
+
+## 6. 基础设施：`supply_infra/`
+
+### 6.1 配置
+
+`supply_infra/config.py` 管理：
+
+- MySQL；
+- ODPS；
+- APScheduler；
+- 阿里云 OSS；
+- Agent 日志上传开关。
+
+配置文件固定从项目根目录 `.env` 读取，不依赖当前工作目录。
+
+### 6.2 数据库会话
+
+`supply_infra/db/session.py`：
+
+- 懒加载全局 SQLAlchemy Engine；
+- 使用连接池和 `pool_pre_ping`；
+- `get_session()` 自动提交；
+- 异常时自动回滚；
+- `init_db()` 通过 ORM metadata 创建缺失表。
+
+### 6.3 Repository 规则
+
+业务 Agent、API 和定时任务原则上不直接执行 MySQL SQL，而是通过 Repository：
+
+- 基础 CRUD；
+- 批量插入；
+- insert ignore；
+- upsert；
+- 条件查询；
+- 批量更新。
+
+ODPS 查询仍在 `supply_infra/odps/client.py` 内直接组织 SQL。
+
+### 6.4 ODPS 客户端
+
+当前读取的主要 ODPS 数据：
+
+- `public_pattern_mining_category`：全局分类；
+- `pattern_mining_element`：树下元素；
+- `dwd_multi_demand_pool_di`：多策略需求池；
+- `dwd_topic_decode_result_di`：视频解析和最终选题；
+- `dwd_video_produce_plan_stat_hour`：真实 ROV/VOV。
+
+### 6.5 OSS 客户端
+
+负责：
+
+- 生成对象路径；
+- 上传本地文件；
+- 返回 CDN 公网地址。
+
+---
+
+## 7. MySQL 数据模型
+
+当前 ORM 定义 10 张表。
+
+| 表 | 作用 | 关键唯一性/关联 |
+|---|---|---|
+| `global_tree_category` | 全局分类树节点 | `source_id` 唯一；`parent_id` 形成树 |
+| `global_tree_element` | ODPS 元素与分类挂靠 | `(name, category_id)` 唯一 |
+| `multi_demand_pool_di` | 按日同步的策略需求池 | 代码按 `(strategy, demand_id, biz_dt)` 管理差异 |
+| `demand_belong_category` | 需求词归属分类 | `name` 唯一；当前一词只能保存一个分类 |
+| `demand_belong_pool_rel` | 需求词与需求池行的匹配边 | `(demand_belong_category_id, multi_demand_pool_di_id)` 唯一 |
+| `demand_popularity_stats` | 词级六维 avg/count | `(demand_category_id, biz_dt)` 唯一 |
+| `category_tree_weight` | 分类树节点六维聚合和四维排名分 | `(category_id, biz_dt)` 唯一 |
+| `multi_demand_video_detail` | 视频标题与最终选题 JSON | `vid` 唯一 |
+| `generated_demand` | 需求生成 Agent 输出 | 按 run_id 记录，无数据库唯一约束 |
+| `oss_logs` | Agent 日志 HTML 的 OSS 地址 | 按 agent_name 查询 |
+
+### 7.1 关键关系
+
+```text
+global_tree_category.id
+  ├── global_tree_category.parent_id
+  ├── global_tree_element.category_id
+  ├── demand_belong_category.category_id
+  ├── category_tree_weight.category_id
+  └── generated_demand.category_id
+
+demand_belong_category.id
+  ├── demand_popularity_stats.demand_category_id
+  ├── demand_belong_pool_rel.demand_belong_category_id
+  └── generated_demand.demand_belong_id
+
+multi_demand_pool_di.id
+  └── demand_belong_pool_rel.multi_demand_pool_di_id
+```
+
+这些关联在 ORM 中主要以整数 ID 表达，没有使用 SQLAlchemy relationship，也没有显式数据库 ForeignKey。
+
+---
+
+## 8. 热度数据的真实代码口径
+
+### 8.1 策略到四项先验的映射
+
+代码把需求池策略映射为：
+
+| ODPS strategy | 统计字段 | 页面含义 |
+|---|---|---|
+| `新热事件` | `ext_pop` | 外部热度 |
+| `逐月` | `plat_sust_pop` | 平台持续热度 |
+| `去年同期阳历` | `plat_ly_pop` | 去年同期热度 |
+| `去年同期阴历` | `plat_ly_pop` | 去年同期热度 |
+| `当下供需gap` | `recent_pop` | 近期热度 |
+
+### 8.2 真实 ROV/VOV
+
+从近 7 日 `dwd_video_produce_plan_stat_hour` 获取人工 AGC 和自动 AGC 数据：
+
+- ROV = 回流 UV / 分发曝光 PV；
+- VOV = 拉回曝光 PV / 分发曝光 PV；
+- 同一特征值存在多行时，优先保留 `rov_diff`、`vov_diff` 较高的一行；
+- 按特征值与 `demand_name` 精确匹配，回填 `multi_demand_pool_di`。
+
+### 8.3 词级统计
+
+对每个 `demand_belong_category.name`：
+
+1. 在当日 `multi_demand_pool_di.demand_name` 中执行子串 LIKE 匹配；
+2. 按策略收集非零 weight；
+3. 分别计算四项先验的 avg/count；
+4. 汇总匹配行的真实 ROV/VOV avg/count；
+5. 写入 `demand_popularity_stats`。
+
+因此当前词与需求池的匹配核心是字符串包含关系，不是分词索引、向量匹配或显式语义关系。
+
+### 8.4 分类树节点聚合
+
+分类节点聚合六个独立维度：
+
+- 外部热度；
+- 平台持续热度；
+- 去年同期热度；
+- 近期热度；
+- 真实 ROV；
+- 真实 VOV。
+
+每个节点统计其整个子树内有需求词挂靠的节点：
+
+```text
+节点维度 avg = Σ(挂靠点 avg × count) / Σ(count)
+节点维度 count = Σ(count)
+```
+
+结果写入 `category_tree_weight`。
+
+### 8.5 四维排名分和全局热度
+
+`update_category_tree_rank_scores.py` 只对四项先验排名：
+
+- 各维只让 `count > 0` 的节点参与；
+- 按 avg 降序排名；
+- 同分取平均名次；
+- 映射到 `(0, 1]`；
+- 无数据节点为 0；
+- `total_score` 是四个排名分直接相加，范围 `[0, 4]`。
+
+真实 ROV/VOV 会被聚合并通过 API 返回，但当前不进入 `total_score`。
+
+前端显示“全局热度”时再使用 `total_score / 4` 映射为 `0～1` 色阶。
+
+单一维度热度则由前端根据该维所有有数据节点的 avg 做百分位色阶，不直接使用数据库中的四维 rank score 字段。
+
+---
+
+## 9. 定时任务和数据流水线
+
+### 9.1 已注册的两个定时任务
+
+`supply_infra/scheduler/app.py` 当前只注册：
+
+1. 每天 `02:30`：同步昨天的全局树和元素；
+2. 每天 `12:00`：同步当天的策略需求池并执行后续完整流水线。
+
+时区来自 `SCHEDULER_TIMEZONE`。
+
+### 9.2 全局树同步
+
+`sync_global_tree_odps_to_mysql`：
+
+1. 拉取有效元素；
+2. 拉取全部分类；
+3. 从元素命中的分类向上补齐祖先；
+4. 按 ODPS source_id 去重；
+5. 已有分类保持不变，只插入新分类；
+6. 给新分类分配 MySQL ID 并转换 parent_id；
+7. 写入元素及其 MySQL category_id。
+
+该任务是增量插入，不会根据 ODPS 当前状态自动删除或更新历史分类。
+
+### 9.3 策略需求池完整流水线
+
+`sync_multi_demand_pool_odps_to_mysql` 实际执行顺序：
+
+1. 比较 ODPS 与 MySQL 当日去重行数；
+2. 行数不同时执行差异同步；
+3. 对当日所有 demand_name 按空格拆词；
+4. 调用归类 Agent 处理未出现过的新词；
+5. 建立需求词与需求池的子串匹配边，并回填词级 video_list；
+6. 获取并回填近 7 日真实 ROV/VOV；
+7. 计算词级六维 avg/count；
+8. 计算整棵分类树六维聚合；
+9. 计算四项先验全局排名分和 total_score；
+10. 同步全部待处理视频的标题和最终选题。
+
+当前有一个同步判断风险：只要 ODPS 和 MySQL 行数相同，就跳过需求池差异拉取；如果内容发生变化但总行数不变，该轮不会发现这些变化。
+
+### 9.4 手动任务入口
+
+`jobs/` 提供：
+
+- 初始化数据库；
+- 启动 Scheduler；
+- 单独同步需求池视频；
+- 回填视频列表和标题；
+- 单独计算词级热度；
+- 单独计算树节点权重；
+- 单独计算四维排名；
+- 单独同步需求词与需求池关系。
+
+---
+
+## 10. FastAPI：`api/`
+
+服务端口：`8080`。
+
+| 接口 | 作用 |
+|---|---|
+| `GET /health` | 健康检查 |
+| `GET /api/category-tree?biz_dt=YYYYMMDD` | 返回嵌套分类树、六维 avg/count、total_score 和挂靠词数 |
+| `GET /api/demand-belong-category` | 返回所有有效需求词挂靠 |
+| `GET /api/demand-belong-category/{id}/videos` | 返回需求词关联的视频标题和最终选题 JSON |
+| `GET /api/demand-belong-oss-logs` | 返回归类 Agent 的 OSS 日志列表 |
+
+如果 `web/dist` 存在，FastAPI 会把它挂到 `/`，同一个 8080 服务同时提供 API 和生产前端。
+
+API 当前是同步 SQLAlchemy 查询，没有分页、鉴权或缓存。
+
+---
+
+## 11. Vue 前端：`web/`
+
+### 11.1 路由
+
+| 路由 | 页面 |
+|---|---|
+| `/` | 平台全局需求地图 |
+| `/demand-tree` | 传统横向分类树 |
+| `/demand-process` | 需求归类 Agent 日志 |
+| `/demand-map` | 重定向到 `/` |
+
+当前顶部导航只显示“平台全局需求地图”，另外两个页面有路由但没有导航入口。
+
+### 11.2 平台全局需求地图
+
+`GlobalDemandMapView.vue` 并行读取：
+
+- 完整分类树和热度；
+- 全部需求词挂靠。
+
+`IcicleHeatTree.vue` 使用 Canvas 绘制从左到右的冰柱树：
+
+- 每层固定 `200px` 宽；
+- 全局状态适配视口高度；
+- 选择层级或聚焦节点后按可读高度纵向扩展；
+- 最大逻辑画布高度 `24000px`；
+- 实际 Canvas 始终只有视口大小，只绘制可见区域；
+- 普通滚轮滚动；
+- 拖拽平移；
+- `Ctrl/Command + 滚轮` 缩放；
+- 点击节点聚焦子树；
+- 支持层级起点和祖先面包屑。
+
+热力标签：
+
+- 全局树结构；
+- 全局热度 `total_score`；
+- 外部热度；
+- 平台持续热度；
+- 去年同期热度；
+- 近期热度。
+
+API 虽然返回真实 ROV/VOV，但当前冰柱图标签没有提供真实 ROV/VOV 的独立切换入口。
+
+### 11.3 节点证据下钻
+
+分类节点存在需求词时显示搜索标识。点击后通过 `DemandPathPanel.vue` 展开：
+
+```text
+当前分类节点
+  → 细节元素/需求词
+  → 真实视频实例
+  → 最终选题 JSON
+```
+
+这里展示的是 `demand_belong_category` 需求词，不是 `generated_demand` 中由生成 Agent 产出的四层平台需求。
+
+当前前端没有读取或展示 `generated_demand` 的 API。
+
+### 11.4 传统分类树页面
+
+`CategoryTree.vue` 使用 Vue DOM 递归组件展示：
+
+- 默认展开 3 层；
+- 支持选择展开深度；
+- 支持手动展开和收起；
+- 支持按维度过滤有数据的节点；
+- 支持拖动画布；
+- 支持导出包含数据的独立 HTML；
+- 同样可以下钻需求词、视频和最终选题。
+
+### 11.5 需求归类过程页面
+
+读取 `demand_belong_category_agent` 的 `oss_logs`，按时间倒序显示，点击打开 Agent 运行过程 HTML。
+
+---
+
+## 12. 部署和运行
+
+### 12.1 Python 命令入口
+
+`pyproject.toml` 注册：
+
+- `supply-api`；
+- `supply-scheduler`；
+- `supply-visualize`。
+
+### 12.2 本地开发
+
+后端：
+
+```bash
+python -m api
+```
+
+前端：
+
+```bash
+cd web
+npm install
+npm run dev
+```
+
+Vite 在 `5173`，将 `/api` 代理到 `127.0.0.1:8080`。
+
+### 12.3 Docker
+
+Docker 使用两阶段构建：
+
+1. Node 20 构建 Vue；
+2. Python 3.11 安装项目和 ODPS 可选依赖；
+3. 把 `web/dist` 放入 Python 镜像；
+4. 通过 `python -m api` 启动 8080。
+
+`scripts/docker-deploy.sh` 可以构建并向指定镜像仓库推送时间戳标签和 `latest`。
+
+---
+
+## 13. 当前代码已经实现的能力
+
+- 通用同步/异步 Agent 和 Tool Calling；
+- 动态 Skill 加载机制；
+- 三个业务 Agent；
+- 全量 Agent 日志和 OSS 发布；
+- ODPS 到 MySQL 的全局树同步；
+- 多策略需求池增量同步；
+- 新词自动归类；
+- 需求词与需求池匹配边；
+- 真实 ROV/VOV 回填；
+- 词级六维统计；
+- 分类树六维向上聚合；
+- 四项先验排名和 total_score；
+- 单维度平台需求生成与落库；
+- 视频标题和最终选题同步；
+- FastAPI 查询接口；
+- Vue 全局冰柱热力图；
+- 分类节点到需求词、视频和最终选题的下钻；
+- Docker 构建和部署脚本。
+
+---
+
+## 14. 当前代码未完成或存在偏差的部分
+
+### 14.1 需求多挂靠尚未实现
+
+`demand_belong_category.name` 唯一，当前一个需求词只能保存一个 category_id。系统提示中的“一词多个节点”无法真实落库。
+
+### 14.2 `generated_demand` 未进入产品展示
+
+需求生成 Agent 已能写 `generated_demand`，但：
+
+- 没有对应 API；
+- 前端没有需求清单；
+- 没有与内容、反馈的展示闭环；
+- 当前全局图下钻的是需求词，不是最终生成需求。
+
+### 14.3 后验没有进入全局综合分
+
+真实 ROV/VOV 已采集、聚合并由 API 返回，但：
+
+- 不进入 `total_score`；
+- 不进入 generate_demand_agent 的 source_dim；
+- 当前主热力图没有 ROV/VOV 标签；
+- 尚未形成“后验反向调整最终需求排序”的完整实现。
+
+### 14.4 `find_agent` 提示和工具不一致
+
+提示要求保存和查询视频内容，但相应工具不存在。
+
+### 14.5 关系语义较弱
+
+当前主要关系是：
+
+- 树父子；
+- 需求词到单一分类；
+- 需求词和需求池的字符串子串匹配；
+- 需求词到视频列表。
+
+尚没有独立的语义关系表、关系类型、关系 reason、置信度和人工审核状态。
+
+### 14.6 同步完整性风险
+
+需求池同步先比较总行数。总行数相同但内容变化时，会跳过 ODPS 明细同步。
+
+### 14.7 测试体系缺失
+
+当前仓库没有 `tests/`，并且 `.gitignore` 直接忽略 `tests/`，会阻止正常提交测试目录。
+
+### 14.8 文档已滞后
+
+现有 `README.md`、`ARCHITECTURE.md` 和 `agents/README.md` 包含已经不存在或未实现的结构，例如：
+
+- `video_content` 模型/Repository；
+- find_agent 的保存和历史查询工具；
+- 旧的 Agent 数量和数据流。
+
+后续应以本文和源码为准，并更新旧文档。
+
+---
+
+## 15. 当前本地运行环境与数据库状态
+
+### 15.1 本地 Python 环境不匹配
+
+当前机器默认环境：
+
+- Python `3.10.19`；
+- SQLAlchemy `1.4.51`；
+- 项目根目录没有 `.venv`。
+
+源码要求：
+
+- Python `>=3.11`；
+- SQLAlchemy `>=2.0`。
+
+因此直接使用当前默认 `python3` 导入数据库层会在 `DeclarativeBase` 处失败。应建立 Python 3.11+ 虚拟环境后安装项目依赖。
+
+### 15.2 `.env` 的 MySQL 配置问题
+
+只读连接检查发现：
+
+1. `MYSQL_HOST` 的值开头多了一个 `=`，会导致主机名解析失败；
+2. 临时去掉该字符后可以到达 MySQL 服务，但返回错误 `1045 Access denied`；
+3. 需要核对用户名/密码、RDS 白名单或该用户允许连接的 Host 范围。
+
+由于未通过鉴权，本次无法确认数据库真实表数量、行数和最新业务日。本文的数据结构来自当前 ORM 和 Repository 源码，不冒充线上运行态数据。
+
+### 15.3 前端依赖未安装
+
+当前没有 `web/node_modules`。Node `20.11.1`、npm `10.2.4` 已存在，执行前需要先在 `web/` 运行 `npm install` 或 `npm ci`。
+
+---
+
+## 16. 建议的后续阅读顺序
+
+如果继续开发，建议按以下顺序进入代码：
+
+1. `supply_infra/scheduler/jobs/sync_multi_demand_pool_odps_to_mysql.py`：理解主业务流水线；
+2. `supply_infra/db/models/`：理解真实数据对象；
+3. `supply_infra/scheduler/jobs/compute_category_tree_weight.py`：理解树上热度；
+4. `agents/demand_belong_category_agent/`：理解需求词挂树；
+5. `agents/generate_demand_agent/`：理解平台需求生成；
+6. `api/services/category_tree.py`：理解后端对前端的数据形态；
+7. `web/src/components/IcicleHeatTree.vue`：理解全局热力图；
+8. `web/src/components/DemandPathPanel.vue`：理解节点证据下钻；
+9. `supply_agent/agent/`：理解底层 Agent 执行机制；
+10. `supply_agent/logging/`：理解可追溯运行日志。
+
+---
+
+## 17. 一句话总结
+
+当前 SupplyAgent 是一套以 ODPS 和 MySQL 为数据底座、以全局分类树为组织骨架、以自研 Agent 框架完成需求词归类和单维需求生成、并通过 FastAPI/Vue 展示分类热度与视频证据的业务系统；核心数据流水线已经形成，但多挂靠、最终需求产品化、后验反馈进入综合决策、语义关系图和自动化测试仍未完成。