PackHorizon Agent 化实施方案 v0

§0 · 目标 & 4 铁律 · Goal & Iron Laws

一句话目标 + 4 条不可动摇的边界

One-Line Goal

在不动老 workflow 一行代码的前提下,新建 backend/app/agent_v2/ 独立模块, 把 11 阶段用 LangGraph 重实现;前端 /generate 页加开关让用户主动选新版试用 · 老版永远兜底。

Law 01

老 workflow 完全不动

process_report_run 及所有依赖代码保持原样,不允许"顺手重构"

Law 02

共用底层 prompt DB

两个版本都从同一 prompt_definitions 表读 prompt · 只是编排逻辑不同

Law 03

灰度可秒回滚

新版跑不好用户关掉开关立刻回老版 · 无需运维介入

Law 04

Prompt 变更全 PR review

禁止直接改 prompt_definitions 表 · 必须走 YAML → PR → CI → apply 流程

三阶段交付概览

Phase	时长	风险	核心交付
Phase 0	1 周	零	11 个 YAML + apply 脚本 + CI drift check + 修复 27 段 drift
Phase 1	1 周	低	`agent_v2/` 骨架 + 3 个 node + benchmark 报告 + 继续/停决策
Phase 2	3-4 周	低	剩余 8 agent + 3 新工具 + 前端开关 + 5 观测看板 + 灰度

§1 · Phase 0 · Prompt YAML 迁移 · 1 周 · 零风险

先修当前最痛的债 · 不做后续也稳赚

修 27/27 段 prompt drift · 建 prompt 变更的规范化流程 · 为 Phase 1 铺路。 核心洞察:这一步做完就算不做后续,已经把当前最大黑盒解决了。

P0.1

建 YAML 目录结构与 schema

后端 0.5d

输出

backend/app/prompts/ 目录 · 11 个 stage YAML + _schema.yaml 定义 7 段结构(identity / prompt / input / output / gate / tools / model)

验收

11 个 YAML 文件建成(可占位)
schema 文件定义完整 7 段
README 说明每段含义 + 修改流程

P0.2

从生产 pg_dump 拉当前 prompt

后端 0.5d 依赖 P0.1

输出

scripts/pull-prompts-from-prod.py · 生成 db-dumps/prompts-current-v36-YYYYMMDD.json(73KB · 7 版历史 · 11 stage)

验收

JSON 里 version_history 包含 7 版
stages 包含 11 个 stage(intake + source + 9 AI)
每 stage 有完整 3 段 prompt

P0.3

JSON → YAML 转换 · 补齐 7 段

后端 1d 依赖 P0.2

输出

11 个 YAML 填充完整。JSON 里已有的 → prompt 段 · 手工补齐 identity/input/gate/tools/model 段(从 ai_workflow_service.py + _stage_output_contract_issues 反推)

验收

11 YAML 全部有完整 7 段
与生产 prompt 内容逐字节一致(diff pass)
identity.boundary 手工 review 一遍确认可读

P0.4

建 apply 脚本 & 反向对比脚本

后端 1d 依赖 P0.3

输出

scripts/apply-prompts-to-db.py(YAML→DB 新版本)· scripts/verify-prompts-drift.py(diff 有则 exit 1)· 都支持 --dry-run

验收

apply 脚本在测试库跑通
verify 脚本对齐时 exit 0 · 有 drift 时 exit 1
两脚本都有 --dry-run 模式

P0.5

CI drift check + 飞书告警

DevOps 0.5d 依赖 P0.4

输出

CI job 每日凌晨(UTC 22:00 / 北京 6:00)跑 verify · drift 时飞书 webhook 报警到 Park Horizon 群

验收

CI 每日跑一次
drift 时飞书报警
README 写明"生产 prompt 只能通过 PR 改"

P0.6

修复 27 段 drift · 灰度上线

后端 + 内容 2d 依赖 P0.4

动作

决策 D1(以生产 V36 为准) → repo YAML 已经从 P0.3 拉的生产版本 → drift 天然消失 → apply 上线 → 生产 SQL SET is_current

验收

verify-prompts-drift 脚本 exit 0
CI 连续 3 天跑通
生产报告生成流程无异常(观察 1 周)

Phase 0 总验收(全部打钩才算完成):

6 个任务全部完成
生产任何 prompt 变更 只能通过 PR 走 YAML → apply → SET is_current 三步
agent_v2 未来可直接从同一 prompt_definitions 读 · 两版一份 prompt

§2 · Phase 1 · Spike 试跑验证 · 1 周 · 低风险

3 个 agent 试跑 · 用数据决定要不要投 Phase 2

核心洞察:花 1 周省下 4 周的方向错误。
只搬 S2/S3/S4 三个 agent · 拿到真实并行数据 · Benchmark 报告决定 GO/NO-GO。

P1.1

装依赖 & 建 `agent_v2/` 独立目录

后端 0.5d 依赖 Phase 0

输出

目录树 · state.py / loaders.py / graph.py / nodes/ / run.py · pip 装 langgraph>=0.2.55 + langgraph-checkpoint-postgres

验收

pip install 通过 · from app.agent_v2 import graph 无报错
目录 & 空文件建成

P1.2

State schema & YAML loader

后端 1d 依赖 P1.1

输出

PackagingState TypedDict · fan-out 字段用 Annotated[dict, merge_by_id] 按 id 合并 · load_agent_skill(stage_code) loader

验收

load_agent_skill("packaging-intelligence") 返回完整对象
state schema 单测 pass

P1.3

实现 3 个 node(S2 / S3 / S4)

后端 2d 依赖 P1.2

输出

packaging_intelligence / brand_strategy / copy_compliance 三个 node · 每个自带 repair loop · gate fail 时 error_hint 塞进下一轮 prompt

验收

3 个 node 用 dummy state 都能跑
gate fail 时能进入 repair loop
repair 用完后正确 raise AgentFailure

P1.4

建 DAG & 跑通端到端

后端 1d 依赖 P1.3

输出

3-node 串行 DAG · PostgresSaver 挂测试库 · graph.invoke(state, config) 能从 confirmation 跑到 copy_compliance

验收

graph.invoke 端到端跑通
graph.get_state 能看到 3 步完整输出
中间人为杀掉 rerun 能从 checkpoint 续跑

P1.5

Benchmark 报告 & GO / NO-GO 决策

后端 + PM 1d 依赖 P1.4

输入

10-20 份真实历史 intake · 老 workflow vs agent_v2 spike 对跑

对比指标

前 3 步耗时 · 输出质量抽查(内容运营人评)· token 消耗 · gate 首次通过率 · 失败可续跑(binary)

GO 阈值

质量不劣化(≥ baseline 80%)+ 耗时 ≤ 110% + 至少一项收益兑现

验收

Benchmark 报告写完
决策会开完 · 结论进 docs/decisions/

Phase 1 总验收:

5 个任务全部完成
GO / NO-GO 决策明确 · 写入 docs/decisions/2026-XX-agent-v2-go-nogo.md

§3 · Phase 2 · 全量 Agent 化 + UI 开关 · 3~4 周 · 低风险

剩余 8 agent + 3 新工具 + 前端开关 + 5 观测 + 灰度

核心洞察:老 workflow 永远不动 · 用户关掉开关秒回。

P2.1

抽 `compliance-router` 工具

后端 + 内容 2d

输出

tools/compliance_router.py + data/compliance_rules.yaml(7 品类合规规则表)· 品类分流从 prompt 里 2096 字 if 变成表查询

验收

7 品类规则完整 · 内容运营 review 可读
tool 单测 pass

P2.2

抽 `quality-scorer` 工具

后端 2d

输出

tools/quality_scorer.py + data/scoring_weights.yaml(5 维权重可配)· director 阶段打分从 prompt 描述变成显式函数 · 分数落 stage_artifacts

验收

tool 单测 pass
权重可后台改(YAML → agent config)

P2.3

抽 `report-template` 工具

后端 1.5d

输出

tools/report_template.py + data/report_templates/new-packaging.yaml / upgrade.yaml · 9 sections + 4 表 columns 从 prompt 硬编码搬到 YAML registry

验收

new-packaging + upgrade 两个模板齐
tool 按 kind 拉模板 · 未来国际化只需加语言子目录

P2.4

剩余 8 个 agent 实现 & 完整 DAG

后端(可并行 CC) 5d 依赖 P2.1-P2.3

Agent 实现顺序

source_intake(纯装配)→ creative_exploration → director_selection(内置 quality_scorer)→ designer_directions_fan_out + worker(Send() 6 并行)→ image_brief_fan_out + worker(6 图并行 · 主推同步)→ difference_review(条件边)→ report_presentation(内置 report_template)

验收

每个 node 单测 pass
完整 DAG 从空 state 跑通端到端(测试库)
6 sub-agent 并行验证(耗时 ≈ 单方向 1.2x 非 6x)
fail 后从 checkpoint 续跑验证

P2.5

后端 API 加 `engine` 参数

后端 1d 依赖 P2.4

输出

POST /api/reports/generate?engine=workflow|agent_v2 · 默认 workflow · agent_v2 走新 celery task · workflow_run.engine 字段记录用哪版跑

验收

默认 engine=workflow · 老用户完全无感
engine=agent_v2 走新 celery task

P2.6

前端 `/generate` 页加开关

前端 1.5d 依赖 P2.5

交互

开关:"使用新版并行引擎(实验)" · 默认 off · localStorage 记住偏好 · 失败自动 fallback 到老版并提示"新版遇到问题 · 已切回稳定版"

验收

开关能开 / 关
关掉走老版 · 打开走新版
新版失败自动 fallback · 用户体验平滑
开关状态记住

P2.7

5 类观测看板(M1-M5)

后端 + 数据 3d 依赖 P2.5

5 张看板

M1 Agent 健康度 · M2 Prompt 版本对比 · M3 单份 Trace 详情 · M4 供应商成本 · M5 满意度归因 · 用 Metabase 或 admin 页自建

验收

5 张看板都能打开
M1 异常时飞书报警
M3 客服可用来快速定位问题

P2.8

灰度上线 10% → 50% → 100%

PM + 后端 3 周依赖 P2.6 + P2.7

节奏

W1 10% opt-in(vip 试用) → W2 50% opt-in(默认 off 显示"推荐尝试") → W3 100% opt-in(默认 on 用户可关) · 老 workflow 保留 ≥ 30 天

回滚阈值

任一触发立刻默认 off:报告完成率 -5% · P95 耗时 > 老版 · 投诉工单陡增 · 供应商成本 > 老版 2 倍

验收

W1 结束 agent_v2 完成率 ≥ workflow
W2 结束用户 opt-in 率 ≥ 40%
W3 结束主动关闭率 ≤ 10%

Phase 2 总验收:

8 个任务全部完成
老 workflow 完整保留 · 未被"顺手重构"
用户主动选新版率 > 50% 才算真赢

§4 · Per-Agent 版本管理 & 秒级回滚 · Version Management

核心补强 · 每个 Agent 独立版本 · 单独回滚

review 时发现的关键盲点:现在生产 prompt_versions 表是整体版本(V24 → V36 全局升级)· 想只回滚 brand-strategy 一个 stage 做不到。 Agent 化必须顺便升级版本模型 —— 每个 agent 独立版本 · 出问题精准回滚。

业务场景对比

现在的痛

V37 上线后发现 brand-strategy 变差了

怎么办?只能全量回滚 V37 → V36。其他 10 个 agent 的改进跟着一起被撤销。

结果:内容运营不敢改 · 一改就全 stack 回滚 · 迭代速度慢 · 一个大版本堆几周才发。

V24 V25 V26 … V35 V36 ← rollback here V37

Agent 化后

每个 agent 独立版本 · 一键秒回滚

只回滚 brand-strategy 到 v3 · 其他 10 个 agent 继续用最新版。运营敢改 · 出问题 30 秒回滚。

结果:每周都能给某个 agent 发新版 · 迭代速度 3-5x · 独立 A/B 也变得可能。

packaging-intelligence · v5 current
brand-strategy · v3 rolled ← v4 出问题回滚
copy-compliance · v7 current
director-selection · v4 current

数据模型 · 从整体版本 → per-agent 版本

表	关键字段	作用
agent_skill_versions	`id` · `stage_code` · `version_no` · `yaml_hash` · `changelog` · `created_by` · `created_at` · `is_current` · `is_frozen`	每次 apply YAML 生成一条 · per-agent 版本 · `is_current` 唯一(单 stage 内)· `is_frozen` 标已上生产不能删
agent_skill_activation	`stage_code` · `version_id` · `activated_at` · `activated_by` · `previous_version_id` · `reason`	激活历史表 · 每次 SET is_current 追加一行 · 回滚只需插入历史里的老 version_id · 秒级
workflow_runs	+ `skill_versions` JSONB 如 `{"brand-strategy": "v3", "copy-compliance": "v7", ...}`	每份报告记录用了每 agent 的哪个版本 · 可回溯 · Loop 1 快速定位
stage_artifacts	+ `skill_version_id`	每个中间产物挂 version_id · 判断是哪版跑出来的 · A/B 对比数据基础

3 种回滚场景 · 分层预案

Level 1 · Prompt 层

单 agent 秒级回滚

运营发现 brand-strategy v4 出问题 · admin 后台点"回滚到 v3" · 立刻生效 · 影响面 = 只有这一个 agent。

触发条件 Loop 1 定位到具体 agent · gate fail 率 ↑ · 客服反馈某个方面变差

Level 2 · Tool 层

工具配置回滚

compliance-router 品类规则 / quality-scorer 权重 / report-template 模板 · 也是 YAML 版本化 · 可独立回滚 · 不影响 prompt 版本。

触发条件 某品类误伤率上升 · 主推打分明显不合理 · 报告结构 bug

Level 3 · Engine 层

整个 agent_v2 关掉

agent_v2 编排层出严重 bug(如 fan-out 死锁 / checkpoint 崩溃)· admin 一键"engine=workflow" · 所有用户回老 workflow。

触发条件 agent_v2 完成率 -10% · P0 事故 · LangGraph 版本坑

Admin 后台 · 版本管理 UI 示意

packhorizon.com/admin/agent-versions

Agent 版本管理 · 11 agent · 共 43 版本历史

+ 发布新版本

Agent	当前版本	激活时间	激活人	历史版本	操作
packaging-intelligence	v5	3 天前	@yifan	v1 v2 v3 v4 v5	History Diff Rollback
brand-strategy	v3 (rolled back)	2 小时前	@qing	v1 v2 v3 v4 (rolled)	History Diff Rollback
copy-compliance	v7	1 周前	@yifan	v1..v6 v7	History Diff Rollback
director-selection	v5 pending A/B	—	@qing	v1..v3 v4 (v5 A/B 中)	History Diff Rollback
designer-directions	v2	3 周前	@qing	v1 v2	History Diff Rollback
· · · 其余 6 agent · · ·

与已有方案的整合

版本管理会渗透到哪些任务

Phase 0 · P0.1 YAML schema 加 version_no + changelog 字段
Phase 0 · P0.4 apply 脚本从"整体新版本"改成"per-stage 增量版本"
Phase 0 · P0.5 CI drift check 变成 verify(stage_code, is_current_version)
Phase 2 · P2.5 API 加 skill_versions 参数(默认从 activation 表读)
Phase 2 · P2.7 Admin 后台 /agent-versions 页(如上图)
Section 07 · Loop 2 A/B 天然基于 per-agent 版本 · 单 agent 分流
业务对比 HTML Section 07 · M2 Prompt 版本对比看板改成"per-agent diff"
Loop 1 · trace 详情 每份报告能看"这份用了每 agent 的哪个版本"

§5 · 报告执行追溯 · 打开一份报告能看到什么

页面从上往下滚 · 分 3 大块 · 每块是啥一目了然

客服 / 运营 / 老板打开一份已跑完的报告 · 点"查看执行过程"进入追溯页 · 从上往下滚 3 大块: 1 用户对话过程 · 2 报告生成时间线(11 步)· 3 每个 agent 展开细节(工具调用 / 内部推理 / 输入输出)。

整体结构 · 3 大块从上往下

Block 01 · 页面顶部

用户对话过程

用户跟 AI 顾问对话的 4 轮反问 · 完整对话记录 · 上传的素材 / logo / 竞品图。这一段是"用户到底说了什么" · 客服看这里判断是不是用户表达有歧义。

Block 02 · 页面中部

报告生成时间线

11 个 agent 的执行时间线(顾问 → 装配 → 情报 → 定位 → 合规 → 发散 → 总监 → 6 设计师并行 → 6 图并行 → 对比 → 报告)· 每步显示 耗时 / 用了哪版 skill / 有没有报错。

Block 03 · 展开细节

Agent 内部干了什么

点开任何一个 agent 步骤 · 展开看它调了什么工具 / 内部怎么推理 / 输入是啥 / 输出是啥。这一段回答"AI 为什么这样干" · 开发排 bug 靠这里。

Agent 内部是怎么运行的 · LangGraph 的 5 步循环

每个 agent 展开后 · 你会看到它在 LangGraph 里跑的 5 步循环。以"情报研究员"为例 —— 它需要自己判断该搜什么 · 自己去联网找竞品 · 抓官网原文 · 然后组织成报告。不是我们写死"先搜 A 再搜 B" · 是 agent 自己想 · 自己调工具 · 循环到觉得够了才停。

1

拿到任务 & 上下文

LangGraph 把上游 agent 的产出打包成 state(比如"品牌名 = 无糖气泡水 · 品类 = 饮料 · 目标市场 = 中国")传给这个 agent · agent 从自己的 YAML 里读到 身份 + prompt + 可用工具清单(如 web_search / web_extract)。

2

LLM 决定下一步做什么

Agent 把 prompt + state + 工具清单一起丢给 LLM(Claude / GPT)· LLM 输出:"我需要先搜'无糖气泡水中国市场竞品'"(tool_call)· 或者"我信息够了 · 输出最终 JSON"(final_answer)。这步是 agent 的"大脑"。

3

LangGraph 执行工具调用

如果 LLM 想调 web_search · LangGraph 帮忙真的去调 Google/Bing API · 拿到 8 条结果 · 塞回给 LLM。agent 不用自己写 HTTP 请求 · LangGraph 管所有工具的执行 / 超时 / 重试。

4

LLM 消化结果 · 决定还要不要继续

LLM 看到 8 条竞品 · 判断"元气森林信息够了 · 但清泉出山还缺" → 决定再调 web_extract 抓清泉出山官网 · 回到第 2 步循环。或者判断"信息齐了" → 进入第 5 步。

5

Agent 输出 & Gate 校验

Agent 觉得够了 · 输出结构化 JSON({competitorReports: [5 家], trends: [3 条]})· LangGraph 用 Gate 规则校验(要求至少 3 家竞品 · 每家至少 5 字段)· 通过 → 存进 checkpoint · 交给下游 agent。fail → repair loop 让 LLM 修。

关键 · 追溯页会显示这个循环 —— 情报研究员这一步展开后 · 你能看到"LLM 决定调 web_search"(第 2 步)· "web_search 返回 8 条"(第 3 步)· "LLM 觉得不够再调 web_extract"(第 4 步 · 回到 2)· 一共调了 3 次工具 · 循环 3 圈 · 最后输出。这是老 workflow 完全看不到的黑盒。

追溯页面示意 · 从上往下滚一遍

packhorizon.com/admin/reports/rp_9k2f2b/trace

无糖气泡水 · 执行追溯 rp_9k2f2b · 4 天前完成

用了 Agent 模式 总耗时 4:12 花费 ¥3.72

— Block 01 · 用户对话过程(4 轮 · 5 分 24 秒)—

第 1 轮

用户 "我要给一款无糖气泡水做包装 · 25-35 岁轻健康人群"

—

展开

第 1 轮

AI 顾问 "好的 · 包装形态是易拉罐 / 玻璃瓶 / 其他?"

¥0.02

展开

2-4 轮

对话继续 3 轮 · 确认卡收敛完整 · 用户上传 1 logo + 2 竞品图

¥0.14

全部展开

— Block 02 · 报告生成时间线(11 步 · 4 分 12 秒)—

00:00

启动 Agent 模式 · 锁定各 agent 版本

—

展开

00:06

情报研究员 v5 联网搜索 3 次 · 抓竞品官网 5 家 · 用时 1:32

¥0.68

收起重跑

▶ 拿到的任务(来自上游装配)

品牌:无糖气泡水 · 品类:饮料 · 形态:330ml 易拉罐 · 市场:中国 · 素材:1 logo + 2 竞品图

▶ LangGraph 循环 · 第 1 圈(agent 自己决定搜什么)

LLM 想:先搜中国市场同品类竞品
→ tool_call: web_search("无糖气泡水 中国市场 竞品")
→ 返回 8 条 · 含元气森林/清泉出山/汉口二厂/nomo/Vinut

▶ LangGraph 循环 · 第 2 圈(agent 觉得还不够)

LLM 想:8 条国内够了 · 再搜国际参考丰富视觉参照
→ tool_call: web_search("sparkling water package design 2026")
→ 返回 12 条 · 含 waterloo/spindrift/liquid death

▶ LangGraph 循环 · 第 3 圈(抓具体页面)

LLM 想:每个竞品需要 hero 视觉细节
→ tool_call: web_extract(5 个 URL 并行)
→ 返回每家的 hero 图 + 主视觉描述

▶ Agent 输出(结构化 JSON)

{
  "categorySnapshot": {...},
  "competitorReports": [5 家 · 每家 8 字段],
  "packagingBenchmarks": [3 趋势]
}

▶ Gate 校验

[pass] 至少 3 家竞品 · 实际 5 家
[pass] 每家至少 5 字段 · 实际 8 字段
[pass] gate 全过 · 存进 checkpoint · 交给下游

01:38 → 02:26

并行 · 品牌顾问 v3 + 文案合规员 v7 同时开工 · 两步一起完成

¥0.41

展开

02:26 → 03:30

创意员 v4 发散出 15 个概念 · 覆盖 10 条路线

¥0.33

展开

03:30 → 03:59

设计总监 v4 5 维打分 · 从 15 个概念收敛到 6 方向

¥0.36

展开

03:59 → 04:12

6 位设计师并行 v2 6 个 sub-agent 同时深化 6 个方向

¥0.92

展开 6

04:12

图片模型 × 3 主推同步生成 · 2 张附加异步

¥0.87

展开

04:00 → 04:12

报告总监 v4 装配 9 sections · 生成最终 HTML 报告

¥0.61

展开

— Block 03 · 每个 agent 都可以像"情报研究员"那样点开看细节 —

总结 · 追溯页解决什么问题

3 大块 · 各自回答一个问题

Block 01 · 用户对话 回答"用户到底说了什么" · 客服判断是不是用户表达歧义
Block 02 · 时间线 回答"跑到哪一步慢 / 哪一步 fail" · 运营看整体节奏
Block 03 · 展开细节 回答"AI 为什么这样干" · 开发排 bug 的一手证据
Agent 循环 让 LLM 自己决定搜什么 · 不是我们写死"先搜 A 再搜 B"
LangGraph 负责 编排调工具 / 检查 gate / 存 checkpoint / 处理 fan-out 并行
老 workflow 的黑盒 是"只能看到最终输入输出" · 中间循环几圈全丢了

§6 · 里程碑时间线 · Milestones

3 个月 · 每个 M 都有明确交付 + Gate

M0

W0 · Kick-off

PRD review 通过

团队集体过一遍方案 · 决定 D1 / D2 走向

Gate团队签字 · 决策 D1 有结论

M1

W1 · Phase 0 完成

27 段 drift 修完 + CI drift check 上线

11 YAML + apply / verify 脚本 + CI 每日跑

Gateverify 脚本连续 3 天 pass

M2

W2 · Phase 1 决策

Benchmark 报告 · GO / NO-GO

3-node spike 完 · 老 vs 新对比数据

Gate会议纪要写决策 · 决策 D2 有结论

M3

W6 · Phase 2 代码就绪

agent_v2 全量 · 前端开关 · 5 看板

11 agent 全实现 · 3 新工具 · UI + 观测就位

Gate内部 dogfood 通过

M4

W7 · 10% 灰度

前端默认 off · vip 用户试用

公告 vip 试用 · 观察完成率

Gate完成率 ≥ workflow

M5

W8 · 50% opt-in

默认 off · 显示"推荐尝试"

观察 opt-in 率与满意度

Gateopt-in 率 ≥ 40%

M6

W9-W10 · 100% opt-in

默认 on · 用户可关

老 workflow 保留至少 30 天

Gate主动关闭率 ≤ 10%

M7

W12+ · 稳定运行

Loop 1/2/3 常态化 · V37 首次发布

调优体系跑起来 · 数据驱动改 prompt

Gate无 P0 事故 30 天

§7 · 关键决策点 · Key Decisions

必须开会 · 会议纪要写进 `docs/decisions/`

#	决策点	触发时机	决策人	影响
D1	prompt drift 修复方向	Phase 0 前	后端 + PM	以生产 V36 为准 vs repo V24 为准?—— 建议前者(生产在用 · 无回归风险)
D2	Phase 1 GO / NO-GO	Benchmark 报告出后	后端 + PM + 老板	决定是否投 4 周做 Phase 2
D3	主推方向失败策略	P2.4 期间	后端	跟老版一致(整 run fail)还是允许降级?
D4	UI 开关默认状态	P2.6 前	PM + 前端	默认 off / on / 推荐尝试?
D5	灰度回滚阈值	P2.8 前	PM + 后端	什么指标下降多少触发回滚
D6	老 workflow 何时下线	100% opt-in 稳定 30 天后	老板 + 后端	下线简化维护 vs 永不下线兜底
D7	版本粒度到 agent 还是到 stage_prompt 3 段	Phase 0 前	后端 + 内容运营	per-agent(推荐)/ per-3段 · 后者可分开改 system 和 user 但复杂度翻 3 倍

§8 · 风险与护栏 · Risks & Mitigation

7 类风险 · 每个都有对应护栏(含版本回滚风险)

#	风险	概率	影响	应对
R1	两版长期共存的维护成本	高	中	共用 prompt DB · 只有编排逻辑不同(Phase 0 已铺路)
R2	并发放大 API 成本	中	中-高	agent_v2 内置并行度上限可配 · 供应商余额告警 · 主推同步其他异步
R3	Phase 2 撞产品迭代	高	中	分阶段可停 · 老 workflow 继续接需求 · agent_v2 由独立 team owner
R4	灰度期用户体感差	低	高	前端 fallback + 秒回滚 · 5 观测看板异常必报警
R5	LangGraph 版本坑	低	中	用 0.2.55+ 稳定版 · 关键 API(Send / PostgresSaver)已 GA
R6	生产 prompt 有未捕获 drift	低	中	CI 每日 verify · 一发现 PR 回归
R7	工具抽出后运营改不动	中	低	3 个 tool 的 YAML 都提供 admin 后台可视化编辑(P2.7 一起做)
R8	版本回滚做得不对 · 数据错位	低	高	workflow_runs.skill_versions 记录每份报告用了哪版 · 回滚前必 dry-run 影响面预览 · frozen 版本不能删

§9 · 附录 · Appendix

路径速查 & 黑名单 & 决策对比

关键文件路径速查

backend/app/prompts/*.yaml11 个 agent skill 定义
backend/app/agent_v2/新模块根 · 完全独立
agent_v2/state.pyLangGraph state schema
agent_v2/graph.pyDAG 定义
agent_v2/nodes/*.py每个 agent 一个 node
agent_v2/tools/*.py3 个新工具
data/compliance_rules.yaml品类合规规则表
data/scoring_weights.yamlquality-scorer 权重
data/report_templates/*.yaml报告结构模板
scripts/apply-prompts-to-db.pyYAML → DB 版本
scripts/verify-prompts-drift.pyCI drift check
docs/decisions/*.md关键决策会议纪要

老 workflow 黑名单(禁改)

任何 PR 涉及以下文件 · 不允许作为"agent 化重构"的一部分改动。若必须改 · 单独提 PR + 附业务原因 · 不与 agent_v2 混。

backend/app/services/ai_workflow_service.py
backend/app/services/model_runtime_service.py
backend/app/services/prompt_version_service.py
backend/app/bootstrap/seed_defaults.py
backend/app/bootstrap/packaging_stage_prompts.py
backend/app/api/reports.py(除新加 engine 参数)

Phase 0 决策 D1 · 两种选择对比

选项	优点	缺点
A · 以生产 V36 为准	生产在用 · 无回归风险 · 立刻 CI 生效	repo 里 27 段全变 · git log 大变化
B · 以 repo V24 为准	repo 版本"更早"	27 段回退 · 生产要真跑测试 · 高风险

建议 A · 走安全路径。

与 Loop Lab / pi-yunzhan 的边界

pi-yunzhan 的 Loop Lab 是通用 loop engineering 平台(基于 pi runtime)。

本方案的 agent_v2 是 PackHorizon 报告生成专用(基于 LangGraph)。

两者不共用编排框架 · 不共用 state · 只在 prompt YAML 组织方式上互相借鉴。未来若发现共通抽象再考虑合并。

TL;DR · 一页纸摘要 · 老板直接看这段

做什么

把 PackHorizon 11 阶段报告流水线从 workflow 改成 agent(LangGraph)· 用户端加开关 opt-in

为什么

1 修 27 段 prompt drift 债 · 2 6 方向 fan-out 并行省 8 分钟 · 3 每步中间产物可回溯 · 失败可续跑 · 局部重跑成为可能 · 4 未来加新品类从 2-4 周降到 2-3 天

怎么做

Phase 0(1 周 · 零风险)→ Phase 1(1 周 · 低风险)→ Phase 2(3-4 周 · 低风险)

关键约束

老 workflow 完全不动 · 新模块独立目录 · 前端开关 opt-in · 老版本永远兜底

总周期

约 3 个月到稳定运行 · 期间业务不受影响

下一步

PRD review → 决定 D1 → 开始 Phase 0

PackHorizonAgent 化实施方案3 个月 · 3 阶段 · 19 任务