活动技术方案生成器

使用场景

当用户提供标准化需求文档，需要生成技术实现方案时使用。

支持两种模式：

全量生成：帮我生成方案 → 生成所有页面
指定页面：帮我生成集合页的方案 / 只生成玩法页 → 仅生成指定页面

职责：技术方案生成（组件匹配、Hook判断、方案输出）。输入应是已拆解好的标准化需求文档。

输出物不仅是叙事型方案，还须包含：

活动配置 JSON（widget 组件配置，字段可追溯至 Go struct）
基础资源 JSON（盲盒/礼盒后台配置，按需）
代码骨架（Hook/Model/Store，按需）

除非用户明确只要大纲。

知识来源

基于 knowledge-query skill 检索，由它自动路由到对应仓库并返回相关组件、Event、基础资源和开发规范。

调用方式：

主 Agent：在 Step 1 中直接 Read 路由表 + 快速索引文件（内联路由，不调 Skill），在同一轮推理中完成需求解析 + 组件选型 + 路径捕获
子 Agent：使用 Read 工具直接读取主 Agent 传递的绝对路径，不调用任何 Skill

架构：主 Agent 选型调度，子 Agent 精读实现

主 Agent 职责（轻量）：
  - Read 路由表 + 快速索引 + 解析需求文档 → 识别页面和玩法 + 组件选型 + 路径捕获（Step 1 一次推理，不调 Skill）
  - 统一分配 chip_id / lottery_type / task_id 等跨需求 ID
  - 声明跨需求依赖关系
  - 并行派发子 Agent（传文档绝对路径列表）

子 Agent 职责（重量）：
  - 接收主 Agent 给定的组件名 + 文档绝对路径列表
  - 用 Read 工具并行读取所有文档绝对路径（不调 knowledge-query）
  - 生成完整方案 + JSON + 代码骨架
  - **直接返回完整方案正文**（不写文件，由主 Agent 统一落盘）

主 Agent 绝对不做的事：

不生成任何方案正文或 JSON 配置
不预读文档（子 Agent 并行读取更快，主 Agent 串行预读反而拖慢整体）

核心原则（主 Agent + 子 Agent 共用）

绝对禁止

凭空编造组件能力 — 必须基于知识库文档
想象配置字段 — 所有配置必须来自真实结构体
跳过组件检查直接用Hook — 必须优先检查是否有现成组件
过度设计 — 能用纯配置就不要用Hook，能用Event就不要纯开发
无中生有 Hook 方法 — 严禁凭空编造 Hook 方法名或签名。知识库无该方法 → 标记「⏳ [待确认]」+ 列待选方案
子 Agent 自行编 ID — chip_id / lottery_type / task_id 必须使用主 Agent 预分配的值

必须遵守

决策优先级：基础资源 → 组件配置 → 组件Hook → Event → 纯开发
组件优先：extra_gift、redpacket、charge_coupon、gift_pkg 等配置后自动注册，无需手动写Hook
不确定时标注 "需要确认"
知识库优先，不足时才读源码
组件 JSON 字段以知识库为准 — key 必须与 struct json tag 一致
盲盒/礼盒 JSON 须配合 weblindboxconfig/wegiftboxconfig 结构体，禁止与 widget 组件 schema 混用
自定义业务配置走 special_info — 概率、阈值、比例、奖励列表等可配置数值禁止硬编码在 Go 代码中，必须定义 Config 结构体 + ParseSpecialInfoV2 解析，并输出对应的 special_info JSON
存储选型按活动周期：短期活动（≤30天）优先用 Redis，长期活动/永久玩法才用 MySQL。避免为短期活动引入 MySQL 建表

常见错误

完整常见错误列表已移入 references/sub-agent-guide.md（子 Agent 自行 Read）。主 Agent 在 Step 1 组件选型时同样须遵守：组件优先于 Hook，禁止编造字段/方法名。

主 Agent 在组件选型时必须记住的高频误判：

错误选型	正确选型	说明
charge_coupon + task（用 task 触发追加次数）	charge_coupon（纯配置）	charge_coupon 原生支持"消耗达标后追加充值优惠次数"，`coin_cost + extra_times` 即可，不需要 task
送礼爆大礼物 → 基础 Hook	extra_gift 组件	自动注册，纯配置
语音房红包雨 → 基础 Hook	redpacket 组件	自动注册，纯配置
消耗金币送充值优惠 → 纯开发	charge_coupon 组件	自动注册，纯配置

生成流程

══════════════════ 主 Agent（轻量调度器）══════════════════
Step 0  → 权限预热（并行 Read sub-agent-guide + source-map + mkdir 落盘目录）
Step 1  → Read 快速索引 + 解析需求 + 组件选型 + 路径捕获（一次推理，不调 Skill）
Step 1.5→ 需求澄清（影响选型的模糊点，无则跳过）
Step 2  → ID 预分配 + 跨需求依赖声明 + 派发计划
Step 2P → 并行派发子 Agent（传文档绝对路径列表）
══════════ 各子 Agent 并行执行（重量级）══════════════════
每个子 Agent：Read 公共指南+文档 → 生成方案 → 返回完整方案正文
══════════ 所有子 Agent 完成后 ════════════════════════
Step 3  → 主 Agent 按页面拼接子 Agent 返回内容 → 每页写入独立 design-{页面名}.md
Step 4  → 【可选】询问用户是否拉取飞书原始文档对齐功能点，确认无遗漏需求

Step 0: 权限预热（主 Agent，Step 1 之前执行）

在正式开始前，通过以下操作预热文件读写权限，避免后续子 Agent 并行 Read 时反复弹窗。该步骤主要面向存在逐文件权限弹窗的旧版客户端；若当前环境不会弹窗，可将其视为路径可达性预检。

Read 本 skill base directory 的 references/sub-agent-guide.md（预热 Read 权限 + 验证路径可达）
Read ../knowledge-query/references/source-map.md（预热知识库 Read 权限）
mkdir -p {workspace_path}（预热目录创建权限）

这 3 个操作可并行执行。完成后，子 Agent 的 Read 操作将自动继承权限，不再逐个弹窗。

Step 1: 解析需求 + 组件选型 + 路径捕获（主 Agent，一次推理完成）

前置读取（内联路由，不调 Skill，避免嵌套 Skill 导致上下文断裂）：

Read 对应仓库的 quick-index.md（如 ../knowledge-query/references/wejoy-http-go/quick-index.md）（Step 0 已预热 source-map.md，此处根据其结果选择仓库）
记录 quick-index.md 的绝对路径，去掉 /quick-index.md 即为 {KB_ROOT}

拿到 quick-index 后，在同一轮推理中解析需求文档，识别每个玩法的：行为、条件、数量、奖励、特殊逻辑。同时根据 quick-index.md 中的关键词匹配表和决策流程确定每个需求的组件选型，构造文档绝对路径。

识别多页面/多活动结构：需求文档可能包含多个独立页面（活动），每个页面通常对应一个独立的 act_id。

页面过滤：如果用户指定了某个页面（如「只生成集合页」），则：

页面清单中标注 [本次生成] / [跳过]
需求拆解只保留目标页面的需求，跳过其他页面
后续 Step 2/2P/3 均只处理目标页面

输出格式：

知识库根目录：{KB_ROOT}

页面清单：
├─ <页面名称A>（act_id: TBD）— 一句话描述
└─ <页面名称B>（act_id: TBD）— 一句话描述

需求拆解 + 组件选型：
├─ R1 [页面A] <需求名称> → extra_gift，标签: [纯配置] → {KB_ROOT}/widgets/extra_gift.md
├─ R2 [页面A] <需求名称> → task + crowd_type_ids，标签: [纯配置] [Crowd] → {KB_ROOT}/widgets/task.md, {KB_ROOT}/dev-guides/activity-crowd-guide.md
├─ R3 [页面B] <需求名称(组合)> → gift_box_star + lottery + collect_chip，标签: [组合玩法] → {KB_ROOT}/widgets/gift_box_star.md, {KB_ROOT}/widgets/lottery.md, {KB_ROOT}/widgets/collect_chip.md
├─ R4 [页面A] <需求名称> → 盲盒 BlindBoxHook，标签: [Hook] [Redis] [Model] → {KB_ROOT}/base-resources/blind_box.md, {KB_ROOT}/dev-guides/actmodel-patterns.md, {KB_ROOT}/dev-guides/actredis-patterns.md
└─ ...

需求拆解原则：

一个独立玩法 = 一条需求
组合玩法不拆：send_gift_lottery、cat_day+collect_chip+exchange_store 等多组件联动作为一条需求
标签打标：[纯配置] / [Hook] / [Event] / [Redis] / [MySQL] / [Model] / [组合玩法] / [Crowd]
组件选型依据 quick-index.md：按「决策优先级」和「快速匹配表」确定，不读组件完整文档，仅确认组件存在且名称正确
[纯配置] 文档精简：标签为 [纯配置] 的需求，文档列表只保留组件文档本身，不分配 dev-guides（actredis/actmodel/mysql-patterns）路径，子 Agent 也无需读取 Hook 章节

[Crowd] 人群过滤识别：

需求信号词	推荐 crowd_type_name
根据近N天累充/历史充值分档	`user_total_paid_yuan_in_range` / `act_total_charge`
新用户、注册N天内	`act_new_user` / `user_register_days`
大R、高价值用户	`user_history_paid_yuan`
回流用户	`is_old_activated`

Step 1.5: 需求澄清（主 Agent）

触发条件（必须同时满足）：

需求描述模糊或数值缺失
不同答案导致架构层面不可逆差异

规则：每次只问1个问题，无明确分歧点则跳过直接进 Step 2。

Step 2: ID 预分配 + 派发计划（主 Agent）

2a. ID 预分配（跨需求协调的核心）：

完整示例参见 references/design-templates.md 中的「ID 预分配示例」。

分配原则：

核心规则：每个页面（act_id）的 ID 空间完全独立。 集合页和玩法页是不同的 act_id，chip_id / lottery_type / task_id / box_type 等均按 act_id 隔离，不同页面的 ID 各自从 1 起编号，互不影响。只有需求文档明确说明跨页面关联时（如「集合页的碎片可在玩法页消耗」），才复用同一 act_id 下的 ID。

chip_id：页面内从 1 起连续编号（不同页面各自从 1 起）
lottery type：页面内每个抽奖实例使用有语义的命名（不用数字编号），格式为 "<玩法缩写>" 或 "<玩法缩写>_<子类型>"。例如："gift_box_3star" / "gift_box_4star" / "gift_box_5star" / "heartbeat_noputback" / "ice_pool" / "fire_pool"。命名须在页面内唯一，跨页面可重复。
task_id：页面内连续编号（不同页面各自从 1 起）。同一玩法的多阶段/多里程碑用 task + 多个 stage 实现（1 个 task_id 配 N 个 stage），不要拆成 N 个独立 task。只有不同玩法才分配不同 task_id。例如：分层累消三档 = 3 个 task_id（每档 1 个 task，内含多个 stage），每日任务4种 = 4 个 task_id。
box_type：页面内每个抽奖实例独立编号（不同页面各自从 1 起）
rank type：数字递增（1, 2, 3...），页面内从 1 起，不同页面各自从 1 起。不使用语义化命名。

2b. 声明派发计划：

正在并行生成 N 条需求的技术方案：
├─ R1 [集合页] 送礼爆大礼物 → extra_gift [纯配置]
├─ R2 [集合页] 分层累消 → task + crowd [纯配置]
├─ R3 [集合页] 礼盒星级抽奖+充能 → gift_box_star+lottery+gift_charge+collect_chip [组合玩法]
├─ R4 [玩法页] 碎片抽奖 → lottery+collect_chip [纯配置]
└─ ...

Step 2P：并行 Agent 派发（主 Agent）

强制使用并行 Agent，最多 12 个子 Agent 并行。全部子 Agent 必须在同一条消息内同时发出。

🔴 一次性派发协议（违反即为错误）

在发出 Agent tool call 之前，先写出轻量清单：

派发 N 个子 Agent：
1. R1+R2 [charge_coupon + gift_pkg]
2. R3 [task + crowd]
3. R4+R5 [extra_gift + room_gift_top]
...
✅ 共 N 个，一次发出

然后在同一条消息内紧接着发出全部 N 个 Agent tool call。

关键：子 Agent prompt 已精简（公共指南由子 Agent 自行 Read），每个 prompt 仅 ~25 行，12 个 Agent 总输出量可控，必须一次全发。

允许分 2 批的唯一场景：

子 Agent 总数 >12 个
后批依赖前批数据输出

严禁分批的场景：

"简单先发，复杂后发" — ID 已预分配，无依赖
"等前批确认" — Step 2 已完成协调
"担心并发太多" — 并行是目标

子 Agent 拆分原则：

条件	合并为 1 个 Agent	拆分为多个 Agent
共享同一组件配置块（如 gift_box_star + gift_charge 由同一礼盒触发）	✅
仅通过 chip_id / lottery_type 松散关联		✅ 主 Agent 已预分配 ID
单个 Agent 预计需读取 >10 份文档		✅ 拆开降低串行读取耗时
单个 Agent 预计输出 >4000 字（如多个完整 lottery 奖池 JSON）		✅ 拆开降低推理时间
不同页面（act_id）的需求		✅ 必须拆开，不同页面 ID 空间独立

典型拆分示例：

❌ 错误：collect_chip(碎片获取) + lottery(碎片消耗抽奖) + rank(排行榜) 塞一个 Agent
✅ 正确：拆为 3 个 Agent，各自使用主 Agent 预分配的 chip_id / lottery_type / rank_type
✅ 合并：gift_box_star + gift_charge + collect_chip + lottery（同一礼盒触发的组合玩法，配置紧密耦合）

纯配置且简单的需求（如 charge_coupon、gift_pkg、extra_gift）可合并到同一个 Agent 以减少 Agent 数量，但单个 Agent 不超过 4 个简单需求。

每个子 Agent 的 prompt 模板（精简版，公共指南由子 Agent 自行 Read）：

你是活动技术方案生成助手，负责生成需求「{需求名称}」的完整技术方案。

# 第一步：Read 公共指南（必须先读）
Read("{SKILL_BASE}/references/sub-agent-guide.md")
该文件包含：文档阅读规则、核心原则、Hook接口速查、输出格式、生成规则、输出规则、礼盒模板、代码骨架示例。

# 需求信息
- 需求编号：{R1/R2/...}
- 所属页面：{页面名}（act_id: {TBD 或已分配}）
- 标签：{[纯配置] / [Hook] / [组合玩法] 等}

# 需求详情
{从需求文档中提取该需求的完整描述，含关键数值、概率、保底、奖励ID等，不能省略}

# 预分配 ID（必须使用，不得自行编号）
- chip_id: {分配值}
- lottery type: {语义化名称}
- task_id: {起始值}
- box_type: {分配值}

# 跨需求依赖（无则留空）
{如「本需求的 gift_charge 产出 chip_id=2，由 R5 的 lottery 消耗」}

# 需要读取的文档（绝对路径，与公共指南并行 Read）
{列出该需求涉及的所有文档绝对路径}

{SKILL_BASE} 替换为本 skill base directory 的绝对路径（主 Agent 在 Step 1 已获取）。子 Agent 在第一条消息中并行 Read 公共指南 + 所有文档路径。

礼盒模板、代码骨架要求、Redis Store 示例 均已移入 references/sub-agent-guide.md，子 Agent 自行 Read。

Step 3: 汇总落盘（主 Agent）

前置条件：所有子 Agent 已返回完整方案正文。

主 Agent 职责：将所有子 Agent 的返回内容按页面分组，每个页面写入独立文件 design-{页面名}.md，末尾各自追加该页面的「待确认事项」。

存储位置：

用户未指定路径 → 存到 skill base directory 下的 workspace/<业务名称>/
用户已指定路径 → 存到指定路径

落盘结构：

workspace/<业务名称>/
├── requirement.md              ← 需求文档原文（主 Agent 写，可选）
├── design-<页面A名称>.md       ← 页面A 技术方案（含 special_info JSON）
├── design-<页面B名称>.md       ← 页面B 技术方案（含 special_info JSON）
└── ...                         ← 每个页面一个文件

文件名规则：design- + 页面名称（中文或英文均可，与 Step 1 页面清单一致），如 design-集合页.md、design-玩法页.md。单页面活动只有一个文件也按此格式命名。

special_info JSON：每个页面的方案末尾须包含该页面的 special_info JSON 配置（自定义业务配置），由子 Agent 根据需求中的真实数值填写。详见 references/sub-agent-guide.md 中的 special_info 配置模式。

每个 design-{页面名}.md 文件结构参见 references/design-templates.md。单页面活动同格式，只有一个 design 文件。ID 无需二次校验（Step 2 已预分配，子 Agent 强制使用）。

Step 4: 飞书文档对齐（可选，主 Agent）

所有 design 文件落盘后，询问用户：

方案已生成完毕 ✅

是否需要拉取飞书原始文档，对照功能点确认有无遗漏的需求？
输入飞书文档链接（或直接回车跳过）：

触发条件（满足其一即询问）：

用户在输入中提供了飞书链接
需求文档来源是本地分析文件（可能与原始文档存在偏差）

用户选择拉取时：

根据系统已安装的 skill 选择合适的飞书文档拉取方式（如 feishu2stdout、feishu2md 等）获取文档 Markdown 内容
对比已生成的各页面方案，逐页检查：
- 原始文档中有、但方案未覆盖的功能点 → 标记为「⚠️ 疑似遗漏」
- 方案中有、但原始文档未提及的 → 忽略（可能是分析文档已拆解合并）
若发现遗漏，列出清单并询问用户是否补充生成对应方案
若无遗漏，回复「已对齐，功能点无遗漏」

用户选择跳过时：直接结束，不做任何额外操作。

质量检查清单

主 Agent 和子 Agent 的完整自检项参见 references/sub-agent-guide.md 中的「质量检查清单」。

成功标准

准确性：所有推荐的组件/Hook/Event 都来自知识库
优先级正确：基础资源 → 组件配置 → 组件Hook → Event → 纯开发
ID 无冲突：跨需求的 chip_id/lottery_type/task_id 由主 Agent 统管
完整性：每个玩法有方案，复杂玩法标注了风险
可落地：配置字段来自真实结构体，代码骨架可编译
配置外置：自定义业务配置通过 special_info JSON 存储，禁止硬编码，每个页面输出 Config 结构体 + JSON 示例

版本: v8.1 | 变更: ① 落盘按页面分文件；② Redis 骨架更新为 actredis 声明式；③ 子 Agent prompt 公共部分抽到 references/sub-agent-guide.md；④ 派发协议精简；⑤ special_info 配置模式（禁止硬编码）；⑥ 常见错误移入 sub-agent-guide.md（子 Agent 可读）；⑦ 质量检查+成功标准补充 special_info；⑧ Step 2 标号修正；⑨ 输出长度上调（含 special_info 额度）。

activity-design-generator