DemandAgent 输出调整 MVP 技术方案

Summary

这次不是“DemandAgent 对接 ContentFindingAgent”，而是 DemandAgent 自身输出结构升级：在不改真实 DB schema 的前提下，核心只调整普通需求池 demand_content.ext_data，增加结构化 evidence_pack。V1 同时保留两种受控输出模式：local_json 用于本地回归，只写本地 JSON；mysql_demand_content 用于云端测试服，只写 MySQL demand_content 单表。原本会写入 dwd_multi_demand_pool_di、feature_point_data、demand_task 的数据，V1 阶段不真实写入这些表，也不改它们的业务字段结构。

本次 DemandAgent 侧补齐的是上游 exact evidence 基础：它能让需求单携带真实 DB 校验过的 Pattern/itemset/category 证据，但最终链路还要求 ContentFindAgent 读取、继承并沉淀结构化 source_evidence，否则最终结果仍无法从 post_id/aweme_id exact 回到 Pattern 和分类树节点。

PG Pattern V2 替换更新：正式证据源已经切到 PG open_aigc.public 主事实表，evidence_pack.pattern_source_system 固定为 pg_pattern_v2。MVP 只使用 pattern_itemset.scope='topic' 的分类 Pattern；topic_element、script、paragraph、group scope 不进入下游 exact 输出，因为它们不能保证每条证据都有 category_id/category_path 可回到分类树节点。

改动范围判断：不改 agent 框架层，只改 examples/demand 这个业务领域实现。agent/ 框架里的 runner、tool registry、trace store、LLM 调用链路都保持不动。本次即使涉及 @tool 参数、trace_id 透传，也只是修改 Demand 业务工具和业务输出，不修改通用 Agent 框架机制。

模块改动归类

模块	是否改	原因
`agent/` 框架	不改	不改 runner、tool registry、trace store、LLM 调用链路；本次只消费现有框架能力，把 Demand 业务输出补充为本地 JSON 和 evidence_pack。
`examples/demand/demand_build_agent_tools.py`	改	DemandItem 需要新增可选证据引用字段，保留原字段兼容旧能力。
`examples/demand/demand.md`	改	Prompt 要求 LLM 在创建需求时带上输出证据引用。
`examples/demand/run.py`	改	当前真实写库入口集中在这里，需要加本地 JSON 输出模式。
`examples/demand/data_query_tools.py`	改	不改 `dwd_multi_demand_pool_di` / `feature_point_data` 业务字段；把现有 Hive 输出拆成可复用的纯映射函数，local 模式只调用映射不写 Hive。
`examples/demand/db_manager.py`	改	保留旧函数名作为 PG facade，底层改读 PG Pattern V2，只读补齐 `category/element/itemset/post` 证据。
新增 `examples/demand/pg_pattern_repository.py`	新增	PG Pattern V2 只读 repository，统一读取 `pattern_mining_`、`pattern_itemset`。
新增 `examples/demand/pattern_builds/pg_pattern_service.py`	新增	保持旧工具返回结构，底层替换为 PG `scope='topic'` Pattern 查询。
新增 `examples/demand/pg_weight_score_builder.py`	新增	从 PG topic 元素/分类聚合本地权重 JSON，替代旧 prepare 产物。
新增 `examples/demand/evidence_pack_builder.py`	新增	专门构造并强校验 `ext_data.evidence_pack`；校验失败的 DemandItem 进入 reject，不进入 `demand_content`。
新增 `examples/demand/local_output_sink.py`	新增	统一本地 JSON sink，稳定输出 7 个本地文件；不进入通用 Agent 框架。
新增 `examples/demand/run_existing_execution_local.py`	新增	MVP 测试入口：用已有 `execution_id` 只读 DB，禁止跑写库 prepare。

输出表改动收敛

虽然 DemandAgent 当前有三类业务结果输出，但本次面向下游证据链的结构性改动只落在 demand_content。

输出	当前业务角色	本次是否改业务字段	MVP 处理方式
`demand_content`	普通需求池；ContentFindAgent 当前直接领取的需求卡片	改	在 `ext_data` 中新增 `evidence_pack`，保留原 `reason/desc/type/video_ids` 兼容旧消费。
`dwd_multi_demand_pool_di`	数仓侧需求池同步 / 策略表现参考	不改	不新增 evidence 字段，不作为下游主证据链载体；MVP 只把原两类策略行镜像到本地 JSON。
`feature_point_data`	`全局树` 特征点输出 / 特征表现参考	不改	和 ContentFindAgent 当前主链路无关；MVP 只保留原字段并镜像到本地 JSON。

demand_task 是任务台账，不算业务结果输出表。本地模式只模拟它的创建和完成状态，方便串起 demand_task_id，不改变业务输出结构。

V1 阶段开发清单

本清单用于承接“待决策事项”与当前开发执行状态。当前 checkout 中未找到独立的 待决策事项.md 文件，因此本节只吸收已经在本方案、demandagent给下游的迭代需求.md、真实代码和已拍板沟通中能被证实的事项；未找到原文依据的内容统一放入“待补充”，不擅自替用户补决策。

1. 已拍板并进入 V1 的事项

事项	V1 处理方式	真实依据
Pattern 证据源	只使用 PG Pattern V2，`pattern_source_system` 唯一合法值为 `pg_pattern_v2`	`pg_pattern_repository.py` 只读 PG `pattern_mining_` / `pattern_itemset`；`evidence_pack_builder.py` 固定 `PATTERN_SOURCE_SYSTEM = "pg_pattern_v2"`
Pattern scope	V1 只输出 `pattern_itemset.scope='topic'`	`evidence_pack_builder.py` 校验 `PATTERN_ITEMSET_SCOPE = "topic"`；`pg_pattern_repository.py` 定义 `TOPIC_SCOPE = "topic"`
旧 MySQL Pattern	删除弃用，不作为任何新版 evidence 来源	`demandagent给下游的迭代需求.md` 已明确旧 `topic_pattern_` 链路删除弃用；当前 PG repository 不读取旧 `topic_pattern_`
下游主载体	`demand_content.ext_data.evidence_pack` 是给下游的主证据包	`run.py` 构造 `ext_data.evidence_pack`；`mysql_demand_content_sink.py` 入库前强校验该字段
LLM 与证据真实性边界	LLM 只产出候选 `evidence_refs`；最终 `evidence_pack` 必须由代码 DB 强校验补齐	`run.py` 读取候选 `evidence_refs` 后调用 `build_evidence_pack()`；`evidence_pack_builder.py` 失败返回 reject
云端 V1 输出	开发/测试服可以真实写云端 MySQL 单表 `demand_content`，但只写这一张表	`run_existing_execution_mysql.py` 注释和入口约束；`mysql_demand_content_sink.py` 只执行 `INSERT/UPDATE demand_content`
本地 V1 输出	local 回归仍保留 `local_json`，产物写入 `examples/demand/test_output_data/{run_id}`	`run_existing_execution_local.py` 与 `local_output_sink.py`
Agent 框架边界	不改 `agent/` 通用框架；只改 `examples/demand` 业务域	本方案“改动归属”已定义；代码改动集中在 `examples/demand`
下游消费口径	当前验收按本输出契约，不按尚未适配完成的 ContentFindAgent 旧 scheduler 代码验收	已拍板：下游代码未完成最新结构适配，本轮按 `demand_output_improve_plan.md` 验收

2. 需按默认值推进的事项

这些不是新决策，而是当前代码已经存在的默认值或运行约束；V1 执行时按代码默认推进，后续如产品要改，需要单独决策。

事项	默认值 / 默认行为	代码位置与含义
PG execution 入参	CLI 必须显式传已有 `pattern_mining_execution.id`；测试默认样本使用已验证的 `581`	`run_existing_execution_mysql.py` / `run_existing_execution_local.py` 都要求 `--execution-id`
execution 状态	只允许 `status='success'`	`run_existing_execution_mysql.py` 启动前调用 `query_execution_for_evidence()` 校验
MySQL 写入模式	`DEMAND_OUTPUT_MODE=mysql_demand_content` 只能通过 `examples.demand.run_existing_execution_mysql` 入口设置	`run.py` 的 `_require_mysql_entrypoint()`
本地 JSON 模式	`DEMAND_OUTPUT_MODE=local_json` 只能通过 `examples.demand.run_existing_execution_local` 入口设置	`run.py` 的 `_require_local_entrypoint()`
ID 语义	`case_id_type` 固定为 `post_id`	`evidence_pack_builder.py` 构造 `case_id_type="post_id"`
Pattern case 列表	`video_ids` 与 `case_ids` 默认等于 DB 校验后的 `matched_post_ids`	`evidence_pack_builder.py` 构造两者；`mysql_demand_content_sink.py` 入库前校验相等
decode 兼容字段	`decode_case_ids` 在 PG-only V1 中默认可为空数组，不参与 Pattern exact 闭合	`evidence_pack_builder.py` 单独查询并写入；未命中不影响 Pattern itemset 通过
证据状态	accepted demand 固定为 `source_certainty=db_validated`、`validation_status=passed`	`evidence_pack_builder.py` 构造固定状态；MySQL sink 入库前复验
MySQL 单表去重	同一 `run_label + name + evidence_pack.source_post_id` 已存在时跳过	`mysql_demand_content_sink.py` 的 `_row_exists_for_run()`
MySQL 入库回填	插入后用真实自增 `id` 回填 `ext_data.evidence_pack.demand_content_id`	`mysql_demand_content_sink.py` 插入后 update 同一行
单表模式任务 ID	不建 `demand_task` 时，`demand_task_id` 不能伪装成真实 DB ID；可为 `null` 或运行侧模拟值，语义必须在 run manifest / 日志中说明	当前 `run_existing_execution_mysql.py` 调用 `main(..., task_id=None)`
MySQL entrypoint 工具白名单	只开放 `get_frequent_itemsets/get_itemset_detail/create_demand_item/create_demand_items`	`run.py` 的 `_enabled_tools_for_run()`
工具返回压缩	`DEMAND_ITEMSET_DETAIL_MAX_IDS=12`、`DEMAND_ITEMSET_DETAIL_MAX_POST_IDS=20`	`run_existing_execution_mysql.py` 设置默认环境变量
LLM 模型解析	优先读 `DEMAND_LLM_MODEL`，再读 `ARK_MODEL` / OpenRouter 相关变量	`run.py` 的 `resolve_model()`
PG 连接配置	优先读 `DEMAND_PATTERN_PG_DSN`，再读 `PGVECTOR_DSN`	`pg_pattern_repository.py` 的 `_resolve_dsn()`
MySQL 连接配置	优先读 `DEMAND_CONTENT_MYSQL_DSN`，否则读 `DEMAND_CONTENT_MYSQL_`，再 fallback 到 `CONTENT_SUPPLY_DB_`	`mysql_demand_content_sink.py` 的 `_resolve_mysql_config()`

3. 待补充但不能阻塞 V1 单表验证的事项

这些事项尚未形成可执行决策，或当前真实代码/文档还没有完全闭合。V1 可以继续推进 100 条测试，但必须在交付说明中标明边界。

待补充事项	当前缺口	V1 临时处理
原始 `待决策事项.md`	当前仓库及 `/Users/samlee/Documents/works` 三层内未找到该文件，无法逐条引用原文	本节先按已拍板沟通和现有两份文档吸收；若用户提供文件，需要再做一次逐条 diff
ContentFindAgent 最新适配	下游新版代码尚未完成，不按旧 scheduler 验收	只按本契约校验 `demand_content.ext_data.evidence_pack`；CFA 后续需继承并沉淀 `source_evidence`
100 条正式批次完成报告	代码和云端链路已能写 MySQL，但最终批次需要以云端 SQL 统计为准	以 `run_label` 前缀查询数量和逐条 evidence 校验，不用本地 JSON 数量替代
生产任务闭环	单表 `demand_content` 不能支撑旧调度、去重、结果回写	V1 只验收 FH/CFA 可读取需求结构；不验收旧 `server.py` 自动调度
独立 evidence 表	当前只写 `ext_data.evidence_pack`，未拆关系表	V1 不拆表；如 `ext_data` 变大或下游要 SQL join，再进入 V1.1
`topic_element` exact 方案	真实 PG 样本中存在分类路径缺失，不能保证 exact 回分类树	V1 不输出；后续必须先补齐分类树节点或定义降级语义
PG Pattern V2 页面主事实链接	当前 evidence 能回 PG 表，但未定义前端页面 URL 或跨系统跳转 ID	V1 只保证表级 exact；页面级跳转另列需求

4. V1 明确不处理的事项

不处理事项	原因
不恢复旧 MySQL `topic_pattern_*` evidence	已删除弃用，任何最终证据来自旧 MySQL 都必须 rejected
不输出 `topic_element`、script、paragraph、group scope	不能保证每条证据都有 `category_id/category_path` 回到分类树节点
不改 PG Pattern V2 数据库 schema	DemandAgent 是下游消费方，只读 PG 主事实
不改 `agent/` runner / tool registry / trace store / LLM 框架	本次是 Demand 业务域输出协议升级
不写 `demand_task`、Hive/ODPS、旧 Pattern 中间表	V1 云端只写 MySQL `demand_content` 单表；本地模式只写 JSON
不保证旧 ContentFindAgent scheduler 自动闭环	旧 scheduler 还需要 `demand_find_task` 和结果表，已超出单表 V1 范围
不把 rejected DemandItem 下发给下游	rejected 只用于 DemandAgent 排查，不能作为可消费需求

5. V1 验收清单

验收项	必须满足
证据真实性	每条 accepted row 的 `evidence_pack.source_certainty='db_validated'` 且 `validation_status='passed'`
PG-only	`evidence_pack.pattern_source_system='pg_pattern_v2'`，不得出现 `mysql_topic_pattern` 或旧 `topic_pattern_*` 来源
itemset 闭合	`pattern_execution_id/mining_config_id/itemset_ids/itemset_items/support/absolute_support` 均来自同一 PG execution 且 scope 为 `topic`
post 闭合	`matched_post_ids` 来自 `pattern_itemset_post`，`source_post_id in matched_post_ids`，`video_ids == case_ids == matched_post_ids`
分类树闭合	`itemset_items[]` 与 `category_bindings[]` 均有 `category_id/category_path`
元素证据闭合	`element_bindings[]` 非空，且来自 PG `pattern_mining_element`
写库范围	云端 V1 只能写 MySQL `demand_content`；不能写 `demand_task`、Hive、PG Pattern 或旧 MySQL Pattern
下游契约	给 FH/CFA 的主输入是 MySQL `demand_content` 行或其导出的 `demand_content.json`，不是 `demand_items` 或 `rejected_demand_items`

改动归属：Agent 框架 vs examples/demand 业务域

1. 不涉及 Agent 通用框架的改动

本次 MVP 不修改 agent/ 通用框架目录。

不改范围包括：

agent/core/runner.py
- 不改 AgentRunner 执行循环。
- 不改 trace 创建、消息持久化、工具调用调度逻辑。
- trace_id 只从现有 runner 结果中读取和透传，不改变框架生成 trace 的方式。
agent/tools / tool registry
- 不改工具注册框架。
- 不改 @tool 装饰器能力。
- 不改工具 schema 生成机制。
- 本次只是修改 examples/demand 下业务工具函数的参数和写出内容。
agent/trace
- 不改 trace store。
- 不改 .trace 文件结构。
- 只把现有 trace_id 写入 DemandAgent 本地输出 JSON，作为业务输出字段。
LLM 调用框架
- 不改模型选择、LLM client、OpenRouter 调用逻辑。
- 不改 RunConfig 的通用字段含义。

结论：本次不是 Agent 框架能力升级，而是 DemandAgent 业务输出协议升级。

2. 仅涉及 examples/demand 业务域的改动

本次实际改动都落在 examples/demand，属于 DemandAgent 示例业务域，也就是当前 Demand 生成链路的业务实现层。

当前改动已经完成业务入口、DB 强校验和受控 sink 的 V1 闭环：demand_build_agent_tools.py 产出候选 evidence_refs，evidence_pack_builder.py 用真实 DB 只读校验并补齐 evidence_pack。local_json 模式只把 passed rows 写入本地 demand_content.json，失败项写入 rejected_demand_items.json；mysql_demand_content 模式只把 passed rows 写入测试服 MySQL demand_content 单表，失败项只记日志，不进入下游需求池。

具体包括：

examples/demand/demand_build_agent_tools.py
- 增强 create_demand_item / create_demand_items。
- 新增可选 evidence_refs 字段。
- 这是业务工具输出结构调整，不是 Agent 工具框架调整。
examples/demand/demand.md
- 修改 DemandAgent prompt。
- 要求模型在生成 DemandItem 时带上来源证据引用。
- 这是业务 prompt 约束，不是框架 prompt 系统改造。
examples/demand/run.py
- 调整结果写出路径。
- 增加 local_json 本地回归模式和 mysql_demand_content 测试服单表写入模式。
- 避免 V1 测试时真实写 demand_task / Hive / PG Pattern / 旧 MySQL Pattern。
- 这是 DemandAgent 业务 orchestration 改动。
examples/demand/data_query_tools.py
- 把 Hive 写入逻辑拆成“构造输出行”和“真实写入”两层。
- 本地模式只调用纯映射生成 dwd_multi_demand_pool_di.json / feature_point_data.json 镜像。
- 不向这两张表增加 evidence_pack，不改变它们的业务字段。
examples/demand/evidence_pack_builder.py
- 新增 evidence_pack 构造逻辑。
- 从 PG Pattern V2 真实 DB 只读补齐 itemset/category/element/post 证据。
- 这是 DemandAgent 输出字段补齐逻辑。
examples/demand/local_output_sink.py
- 新增本地 JSON sink。
- 由 run.py 统一模拟 demand_task、demand_content、Hive 输出表。
- 其中只有 demand_content 的 ext_data.evidence_pack 是新增业务结构；Hive 输出表只是原样镜像。
- 这是 MVP 测试输出设施，不进入通用框架。
examples/demand/run_existing_execution_local.py
- 新增只读测试入口。
- 只允许传已有 PG pattern_mining_execution.id。
- 禁止调用 run_mining，避免写 Pattern 中间表。
examples/demand/run_existing_execution_mysql.py
- 新增云端测试服单表写入入口。
- 只允许传已有 PG pattern_mining_execution.id。
- 强制 DEMAND_OUTPUT_MODE=mysql_demand_content，只写 MySQL demand_content。
examples/demand/mysql_demand_content_sink.py
- 新增测试服 MySQL 单表 sink。
- 入库前强校验 ext_data.evidence_pack，插入后回填真实 demand_content_id。
- 不创建或写入 demand_task、Hive、PG Pattern、旧 MySQL Pattern。

Key Changes

DemandItem 输出结构增强

在 create_demand_item/create_demand_items 增加可选 evidence_refs，原有 element_names/reason/desc/type 不变。

record = {
    "element_names": element_names,
    "reason": reason,
    "desc": desc,
    "type": type,
    "evidence_refs": evidence_refs or {},
}

推荐 evidence_refs 格式：

{
  "source_kind": "pattern_itemset",
  "source_tool": "get_itemset_detail",
  "itemset_ids": [123],
  "category_ids": [456, 789],
  "source_post_id": "55157577",
  "case_ids": {
    "pattern_itemset": ["55157577"]
  },
  "seed_terms": ["猫咪", "拟人化"],
  "notes": "source_post_id 必须来自 get_itemset_detail.post_ids / matched_post_ids"
}

case_ids 在候选阶段按 source_kind 分组，而不是一个裸数组。示例：{"pattern_itemset": ["post_id"], "direct_case": ["case_id"]}。若当前来源没有 Case seed，对应 source_kind 可以填空数组，但不能把其他来源的 Case 混入本来源。

demand_content.ext_data 增加 evidence_pack

本地输出的 demand_content.json 保持真实表字段形态：

当前落地阶段已经接入 DB 强校验 builder：ext_data.evidence_refs 只作为 LLM 候选输入；只有校验通过后才会在 ext_data.evidence_pack 中写入 source_certainty=db_validated、validation_status=passed。校验失败的 DemandItem 不进入 demand_content.json。

{
  "id": 1,
  "merge_leve2": "贪污腐败",
  "name": "权钱交易,利益输送",
  "reason": "...",
  "suggestion": "...",
  "score": 0.73,
  "ext_data": {
    "reason": "...",
    "desc": "...",
    "type": "pattern",
    "video_ids": ["..."],
    "evidence_pack": {
      "pattern_source_system": "pg_pattern_v2",
      "pattern_execution_id": 581,
      "mining_config_id": 2081,
      "source_kind": "pattern_itemset",
      "case_id_type": "post_id",
      "source_post_id": "02454b8dab4c13c9fa21042bdc92d122",
      "category_bindings": [
        {
          "itemset_id": 1607313,
          "itemset_item_id": 6051234,
          "category_id": 123456,
          "category_name": "示例分类",
          "category_path": "/形式/...",
          "category_full_path": "/形式/...",
          "point_type": "关键点",
          "dimension": "形式",
          "element_name": null
        }
      ],
      "element_bindings": [
        {
          "itemset_id": 1607313,
          "itemset_item_id": 6051234,
          "category_id": 123456,
          "point_type": "关键点",
          "dimension": "形式",
          "element_name": "示例元素",
          "matched_element_count": 1,
          "matched_post_count": 1,
          "matched_post_ids": ["02454b8dab4c13c9fa21042bdc92d122"]
        }
      ],
      "itemset_ids": [1607313],
      "itemset_items": [
        {
          "itemset_id": 1607313,
          "category_id": 123456,
          "category_path": "/形式/...",
          "point_type": "关键点",
          "dimension": "形式",
          "element_name": null
        }
      ],
      "support": 0.18,
      "absolute_support": 12,
      "matched_post_ids": ["..."],
      "case_ids": ["..."],
      "decode_case_ids": [],
      "seed_terms": ["权钱交易", "利益输送"],
      "trace_id": "...",
      "demand_task_id": null,
      "demand_content_id": 1,
      "source_certainty": "db_validated",
      "validation_status": "passed"
    }
  },
  "dt": "20260604"
}

dwd_multi_demand_pool_di / feature_point_data 不改业务结构，仅做本地镜像

本地目录仍保留多文件，目的是完整复刻本次 run 的所有输出，便于回归验证 local_json 模式不真实写 DB / Hive：

test_output_data/{run_id}/
  run_manifest.json
  demand_task.json
  demand_items.json
  rejected_demand_items.json
  demand_content.json
  dwd_multi_demand_pool_di.json
  feature_point_data.json

dwd_multi_demand_pool_di.json 只镜像当前两种策略，不新增证据字段：

当下供需gap
当下供需gap-分词

feature_point_data.json 始终作为本地契约文件存在；仅在 merge_leve2 == "全局树" 时有非空业务行，字段仍沿用当前实现中的 特征点、总分发曝光pv、质bn_rovn、dt。注意：真实表/代码里的历史字段拼写是 merge_leve2，CLI 参数可以叫 --merge-level2，但输出 JSON 和文档中的表字段应保持 merge_leve2，不要误改成 merge_level2。

evidence_pack 采用强校验：LLM 只提供候选引用，代码校验失败则拒绝该需求

evidence_refs 只是 DemandAgent LLM 在生成需求时给出的候选证据引用，不直接下发给 ContentFindAgent。真正进入 demand_content.ext_data.evidence_pack 的，只能是代码按当前 execution_id 从 DB 校验通过并补齐后的证据。

原则：

下游消费的 evidence_pack 必须是真实、可追溯、DB 校验通过的证据链。
如果 itemset_ids/category_ids/element_bindings/video_ids 任一必需证据无法校验，当前 DemandItem 失败，不写入 demand_content。对 Pattern itemset 来源，case_ids 按 post_id 语义等于已校验的 matched_post_ids，可为空的是 decode_case_ids；source_post_id/itemset_ids/itemset_items/mining_config_id/matched_post_ids/support/absolute_support 必须强校验通过。若 LLM 漏填 source_kind，但已给出 itemset_ids 或 source_tool=get_itemset_detail，DemandAgent 可内部补齐为 pattern_itemset 后继续 DB 强校验。
失败的 DemandItem 只进入本地 rejected_demand_items.json 供排查，Agent 继续生成下一条需求。
不允许把候选反查、跨 execution 命中、DB 错误、LLM 抄错 ID 的结果伪装成下游可消费证据。

字段来源和校验口径如下：

字段	主要来源	真实性判断	是否可能受 LLM 影响
`pattern_source_system`	代码按当前读取链路设置，MVP 固定为 `pg_pattern_v2`	标记证据来自 PG `open_aigc.public` Pattern V2 主事实	否
`pattern_execution_id`	当前运行参数 / PG `pattern_mining_execution.id`	必须存在且 `status='success'`	否
`mining_config_id`	PG `pattern_itemset.mining_config_id` + `pattern_mining_config.id`	必须来自同一 execution，且 config `scope='topic'`	否
`case_id_type`	代码按证据类型设置，Pattern case 链路固定为 `post_id`	用于标准化 `source_post_id/matched_post_ids/aweme_id` 的 ID 语义	否
`source_post_id`	LLM 候选 + PG `pattern_itemset_post.post_id` 校验	必须出现在已校验 itemset 的 `matched_post_ids` 中，否则拒绝该需求	候选阶段受影响，最终输出必须 DB 校验通过
`itemset_ids`	LLM 在 `evidence_refs` 中给出候选，代码按 `execution_id` 回查校验	只有属于当前 execution 且和需求证据匹配时才进入 evidence_pack；否则该需求拒绝	候选阶段受影响，最终输出必须 DB 校验通过
`itemset_items[]`	PG `pattern_itemset_item` + `pattern_mining_category`	必须来自已校验 `scope='topic'` itemset，且每个 `category_id/category_path` 能 join 到当前 execution 的分类节点	否
`support` / `absolute_support`	PG `pattern_itemset`	DB 可验证事实	否
`matched_post_ids`	PG `pattern_itemset_post` 聚合	DB 可验证事实；`COUNT(DISTINCT post_id)` 必须等于 `absolute_support`	否
`category_bindings`	PG `pattern_itemset_item` + `pattern_mining_category`	必须来自已校验 itemset/category；查不到则拒绝该需求	否
`element_bindings`	PG `pattern_mining_element`，限定 `source_table='post_decode_topic_point_element'`	必须能在当前 execution/source_post 下精确绑定到 itemset item；只查到候选时拒绝该需求	否
`video_ids`	优先来自已校验 itemset 的 `matched_post_ids`	必须来自已校验证据链；不再把宽松反查结果作为下游证据	否
`case_ids`	已校验 itemset 的 `matched_post_ids`	Pattern 来源下固定是 `post_id` 语义，和 `case_id_type=post_id` 对齐	否
`decode_case_ids`	PG-only MVP 不再查旧 MySQL decode 表，保留为空数组兼容字段	可选补充字段；命中不到不影响 Pattern itemset 来源通过	否
`seed_terms`	LLM 候选 + 代码校验后的 element/category/itemset 反推	最终输出必须能被已校验证据覆盖；否则拒绝该需求	候选阶段受影响，最终输出必须被证据覆盖
`source_kind`	LLM 候选明确声明；若缺失但已有 `itemset_ids` 或 `source_tool=get_itemset_detail`，DemandAgent 内部可安全补齐为 `pattern_itemset`	MVP 只支持 `pattern_itemset`；补齐后仍必须走 DB 强校验，不是 Pattern itemset 则拒绝	候选阶段受影响，最终输出必须 DB 校验通过
`trace_id`	现有 Agent runner / trace store	框架事实	否
`demand_task_id`	本地回归可为模拟任务 ID；云端单表模式因不建 `demand_task` 可为 `null`	不能伪装成真实 DB task id	否
`demand_content_id`	云端单表写库后为真实 `demand_content.id`；本地回归为模拟 ID	云端测试服真实，本地回归模拟	否

因此最终进入 demand_content 的 evidence_pack 必须包含完整证据字段；其中状态字段的取值只能是：

{
  "source_certainty": "db_validated",
  "validation_status": "passed"
}

如果 LLM 给出的 itemset_ids/category_ids/source_post_id 查不到、跨 execution，source_post_id 不在已校验 itemset 的 matched_post_ids 中，itemset_items[] 或 mining_config_id 补不齐，和 element_names/seed_terms 没有强匹配，或者 DB 校验失败，则当前 DemandItem 不生成 demand_content，只记录到本地拒绝清单：

{
  "element_names": ["地貌水文", "互动设计"],
  "reject_reason": "itemset_id 377530 not found under execution_id 1987",
  "validation_status": "failed"
}

业务含义：给下游 ContentFindAgent 的任务证据链必须真实。只要 DemandAgent 无法确认证据真实性，这条需求就不进入需求池；Agent 应继续生成下一条可强校验的需求。

输入仍从真实 DB 拉

MVP 入口只接受已有 PG pattern_mining_execution.id：

DEMAND_OUTPUT_MODE=local_json python -m examples.demand.run_existing_execution_local \
  --execution-id 581 \
  --merge-level2 贪污腐败 \
  --platform-type piaoquan \
  --count 5 \
  --run-id local_581_smoke

local 模式只能通过 examples.demand.run_existing_execution_local 进入；run.py 会校验 DEMAND_LOCAL_ENTRYPOINT=run_existing_execution_local。该入口必须传已有 PG execution，禁止调用 run_mining 或各平台 prepare，避免写任何 Pattern 中间表。

本地入口会把三类运行产物统一重定向到 examples/demand/test_output_data/{run_id} 下。可传 --run-id 指定目录名；如果传 --output-root，也必须位于 examples/demand/test_output_data/ 之内。

{output_root}/
  intermediate/result/
  intermediate/data/
  .trace/
  output/
  run_manifest.json
  demand_task.json
  demand_items.json
  rejected_demand_items.json
  demand_content.json
  dwd_multi_demand_pool_di.json
  feature_point_data.json

若未传 --output-root，默认写到 examples/demand/test_output_data/execution_{execution_id}_{timestamp}/。local 模式会从 PG pattern_mining_element 聚合生成兼容的权重 JSON 到 intermediate/data/{execution_id}/，get_weight_score_* 读取该目录，不写 examples/demand/data。

Test Plan

写库屏障测试：local_json 模式下 monkeypatch mysql_db.insert/update/insert_many、execute_odps_sql 和 PG DML/DDL，若被调用则测试失败；PG repository 只允许 SELECT/SHOW/EXPLAIN。
云端单表写库测试：mysql_demand_content 模式下只允许 MySQL demand_content 的 INSERT/UPDATE；不得调用 _create_demand_task/_finish_demand_task、Hive/ODPS 写入、PG DML/DDL 或旧 MySQL Pattern 写入。
输出结构测试：本地回归校验 JSON 文件存在；云端测试服按 run_label 查询 MySQL demand_content 行。两种模式都重点校验 demand_content.ext_data.evidence_pack，同时确认 dwd_multi_demand_pool_di / feature_point_data 不新增业务字段。
evidence 测试：校验所有进入 demand_content 的 evidence_pack.pattern_execution_id/source_kind/seed_terms/trace_id/source_certainty/validation_status 必填，validation_status 必须为 passed，source_certainty 必须为 db_validated。
Pattern itemset evidence 测试：当 source_kind=pattern_itemset 时，pattern_source_system/case_id_type/source_post_id/mining_config_id/itemset_ids/itemset_items/matched_post_ids/support/absolute_support 必填，且 source_post_id 必须在 matched_post_ids 中，len(matched_post_ids) 必须等于 absolute_support。
严格拒绝测试：构造 LLM 声明错误 itemset、跨 execution itemset、缺少 matched_post_ids/source_post_id/itemset_items/mining_config_id、DB 校验失败等样本，验证这些 DemandItem 不进入 demand_content，只进入 rejected_demand_items.json。
回归测试：不改 agent/ 通用框架；DemandAgent pattern 工具名保持不变，但底层均走 PG adapter。
多 subagent 验证：分别做 DB 血缘审计、输出契约审计、旧能力回归审计，交叉确认没有改坏原能力。

Assumptions

V1 不做 DB schema migration；本地回归模式不写 DB，云端测试服模式只写 MySQL demand_content 单表。
本次只调整 DemandAgent 输出，不改 agent/ 通用框架。
本次下游证据链只以 demand_content.ext_data.evidence_pack 为载体；dwd_multi_demand_pool_di 和 feature_point_data 不承载 evidence_pack。
DemandAgent 当前正式证据源是 PG open_aigc.public Pattern V2 主事实；旧 MySQL Pattern 兼容层只作为历史背景，不再作为 evidence 来源。
本 MVP 只输出 PG pattern_itemset.scope='topic'；topic_element、script、paragraph、group scope 因无法保证分类树节点闭合，不进入 exact evidence。
对纯 Pattern itemset 来源，case_ids 按 post_id 语义直接等于已校验的 matched_post_ids，decode_case_ids 保留为空数组兼容字段。source_post_id、matched_post_ids、itemset_ids、itemset_items[]、mining_config_id、support、absolute_support 必须强校验通过。

demand_output_improve_plan.md 32 KB Permalink Histórico Raw