workflow-framework-generator

name workflow-framework-generator description 根据用户指定的工作流类型与目标AI IDE平台，生成一套完整的、可运行的CataForge风格智能体与Skill编程工作流框架。 支持任意领域（软件开发、内容创作、电商运营、研究分析等），自动适配Claude Code / Cursor / CodeX / OpenCode的能力差异。 当用户需要为新领域或新平台构建AI工作流时触发。 argument-hint <workflow_type: 如'公众号写作'> <target_ide: 如'Claude Code'> [--multi-agent] [--structured-output] suggested-tools file_read, file_write, file_edit, file_glob, file_grep, shell_exec, web_search, user_question depends [] disable-model-invocation false user-invocable true 工作流框架生成器 (workflow-framework-generator) 能力边界 能做 : 根据工作流类型+目标平台，生成完整的CataForge兼容框架（agents/skills/workflows/configs） 不做 : 执行生成的工作流、替代领域专家做业务决策、硬编码特定工作流逻辑 输入规范 必填: workflow_type 工作流类型（自由文本，如"公众号写作"）+ target_ide 目标平台（枚举: claude-code | cursor | codex | opencode） 可选: multi_agent / tool_calls / structured_output / output_format / project_name / output_dir 约束字段（详见 Phase 1.1） 上游知识源: references/domain-patterns.md （领域模式库）+ references/platform-capabilities.md （平台能力矩阵） 输出规范 输出目录: <output_dir>/ （默认 ./generated-frameworks/<project_name>/ ） 完整产出: .cataforge/{framework.json, PROJECT-STATE.md, agents/, skills/, workflows/, hooks/hooks.yaml, rules/, platforms/, schemas/} + 根目录 README.md + docs/ 空目录 设计决策记录: 控制台输出 §设计决策输出 段定义的四节内容 不写入: 用户项目源码、CI 配置、运行时数据 执行流程 本 Skill 按三个阶段执行： 解析 → 规划 → 生成 。每个阶段有明确的输入输出契约。 Phase 1: 输入解析与需求澄清 1.1 解析用户输入 从用户消息中提取以下字段： workflow_type: <string> # 工作流类型 (必填) target_ide: <string> # 目标平台 (必填，枚举: claude-code | cursor | codex | opencode) constraints: multi_agent: <bool> # 是否需要多智能体协作 (默认: true) tool_calls: <bool> # 是否需要工具调用 (默认: true) structured_output: <bool> # 是否需要结构化产出 (默认: true) output_format: <string> # 产出格式 (默认: markdown) project_name: <string> # 项目名称 (可选，默认从 workflow_type 派生) output_dir: <string> # 输出目录 (可选，默认: ./generated-frameworks/<project_name>) 1.2 输入验证 target_ide 必须是已知平台之一。若用户输入模糊（如"vscode"），映射到最接近的平台并确认 workflow_type 为自由文本，但需确认其属于可识别的领域类别 1.3 需求澄清（条件触发） 当以下条件满足时， 必须 向用户提出澄清问题（每批 ≤ MAX_QUESTIONS_PER_BATCH）： 条件 澄清问题方向 workflow_type 含糊（如仅"写作"） 具体写作类型、目标平台/渠道、产出格式 领域不熟悉 核心业务流程、关键产出物、质量标准 multi_agent 未指定 工作流复杂度是否需要多角色协作 涉及外部系统 需要集成的API/服务/数据源 澄清问题格式： 为了生成最适合的工作流框架，我需要确认以下信息： 1. [具体问题] 2. [具体问题] 3. [具体问题] 1.4 领域调研增强（条件触发） 当用户需求涉及你不熟悉的领域知识时： 读取 references/domain-patterns.md 查找是否有匹配的领域模式 若无匹配，使用 web_search 检索该领域的标准工作流程和最佳实践 将调研结果结构化为：关键角色、核心流程、产出物清单、质量标准 将结构化结果融入后续的架构设计 Phase 2: 架构规划 2.1 加载平台能力矩阵 读取 references/platform-capabilities.md ，提取目标平台的： 支持的工具映射（tool_map） 可用特性（features） 代理调度方式（dispatch） Hook 支持程度 降级策略需求 2.2 设计 Agent 角色体系 基于工作流需求，设计 Agent 角色列表。每个 Agent 必须包含： agent_id: <kebab-case> name: <display_name> role: <一句话角色定义> responsibilities: - <职责1> - <职责2> capabilities_needed: # 使用 CataForge 能力标识符 - file_read - file_write - shell_exec interaction_pattern: <orchestrated | autonomous | reactive> upstream_agents: [ <agent_id> ] # 上游依赖 downstream_agents: [ <agent_id> ] # 下游消费 设计原则 ： 每个 Agent 有且仅有一个核心职责（单一职责原则） Agent 之间通过文件系统传递状态，不依赖共享内存 至少包含一个 orchestrator 角色（当 multi_agent=true 时） 总 Agent 数量控制在 3-10 个（避免过度设计） 单代理降级 ：当 multi_agent=false 或目标平台不支持 agent_dispatch 时： 将所有角色合并为单一 Agent 使用 Skill 模块化拆分不同职责 工作流编排退化为 prompt 级顺序执行 2.3 设计 Skill 模块 从 Agent 职责中提取可复用的能力单元： skill_id: <kebab-case> name: <display_name> type: instructional | executable | hybrid description: <一句话描述> input: <输入描述> output: <输出描述> used_by: [ <agent_id> ] depends: [ <skill_id> ] suggested-tools: [ <capability_id> ] # 注意短横线，非下划线 — SkillLoader 仅识别带短横线的键名 提取规则 ： 跨 Agent 复用的逻辑 → 独立 Skill 可独立测试的处理逻辑 → 独立 Skill 特定于单一 Agent 且不复用 → 保留在 Agent 指令中 不创建仅被一个 Agent 使用且逻辑简单的 Skill 2.4 设计 Workflow 编排 定义工作流的阶段、依赖和状态流转： workflow_id: <kebab-case> phases: - id: <phase_id> name: <phase_name> agent: <agent_id> skills: [ <skill_id> ] inputs: [ <doc_path or previous_phase_output> ] outputs: [ <doc_path> ] gate: <quality_gate_description> # 可选 next: <phase_id> | [ <phase_id> ] # 支持分支 编排原则 ： 阶段间通过文件产出物传递状态 每个阶段有明确的输入/输出契约 关键阶段设置质量门禁（gate） 支持线性、分支、并行三种流转模式 2.5 平台适配决策 按 references/platform-capabilities.md 中目标平台的能力矩阵做出适配决策并记录理由。对每个不支持的能力，选择降级策略： 替代实现 : 用可用工具组合实现等效功能 规则注入 : 将逻辑嵌入 Agent 指令中 跳过 : 标记为不可用并说明影响 Phase 3: 框架生成 3.1 生成目录结构 根据规划结果，生成以下目录结构： <output_dir>/ ├── .cataforge/ │ ├── framework.json # 框架主配置 │ ├── PROJECT-STATE.md # 项目状态文档 │ ├── agents/ # Agent 定义 │ │ ├── <agent-id>/ │ │ │ └── AGENT.md │ │ └── ... │ ├── skills/ # Skill 模块 │ │ ├── <skill-id>/ │ │ │ └── SKILL.md │ │ └── ... │ ├── workflows/ # 工作流定义 │ │ └── <workflow-id>.yaml │ ├── hooks/ # Hook 规范 │ │ └── hooks.yaml │ ├── rules/ # 通用规则 │ │ ├── COMMON-RULES.md │ │ └── SUB-AGENT-PROTOCOLS.md │ ├── platforms/ # 平台适配 │ │ └── <target_ide>/ │ │ └── profile.yaml │ └── schemas/ # 数据模型 │ └── agent-result.schema.json ├── docs/ # 工作产出目录（空，由 context 在生成首份文档时调用 `cataforge context index` 创建 .doc-index.json） └── README.md # 框架说明 3.2 生成 Agent 定义 读取 templates/agent.md.tmpl ，为每个 Agent 生成 AGENT.md。 关键规则 ： tools 字段使用 CataForge 能力标识符（如 file_read ），不使用平台原生名称 skills 字段引用 Phase 2.3 中设计的 Skill ID allowed_paths 根据 Agent 职责设置写入范围限制 maxTurns 根据任务复杂度设置（简单任务: 30, 中等: 80, 复杂: 150） Agent 指令部分使用中文（与 CataForge 惯例一致），技术标识符使用英文 章节骨架以 templates/agent.md.tmpl 为准；其中 Identity / Input Contract / Output Contract / Anti-Patterns 必须各为独立的 ## 二级标题（validate_framework.py 强制）。 3.3 生成 Skill 定义 读取 templates/skill.md.tmpl ，为每个 Skill 生成 SKILL.md（章节骨架与 frontmatter 字段以 tmpl 为准）。 3.4 生成 Workflow 定义 读取 templates/workflow.yaml.tmpl ，生成工作流编排文件（phase 字段结构以 tmpl 内注释为准）。 3.5 生成框架配置 framework.json — 读取 templates/framework.json.tmpl ，填充： version: "1.0.0" runtime.platform: target_ide 的 platform_id constants: 根据工作流特性设置 features: 根据 Skill 依赖启用 hooks.yaml — 读取 templates/hooks.yaml.tmpl ，生成适用的 Hook 规范。仅生成目标平台支持的 Hook，不支持的标记降级策略。 profile.yaml — 读取 templates/platform-profiles/<target_ide>.yaml.tmpl ，生成目标平台的能力映射。 COMMON-RULES.md — 读取 templates/common-rules.md.tmpl 生成工作流通用规则。 SUB-AGENT-PROTOCOLS.md — 读取 templates/sub-agent-protocols.md.tmpl 生成子代理协议。 PROJECT-STATE.md — 读取 templates/project-state.md.tmpl 生成项目状态文档。 3.6 生成 README.md 生成项目级 README，包含： 框架概述与设计目标 目录结构说明 快速开始指南（针对目标平台） Agent 与 Skill 清单 工作流阶段说明 平台限制与降级说明 扩展指南 Phase 4: 输出验证 生成完成后，执行以下验证： 4.1 自动化检查 运行 scripts/validate_framework.py （覆盖：frontmatter 合法性、必填章节、framework.json / profile.yaml / hooks.yaml 结构、交叉引用、孤立 Skill、Agent 依赖 DAG）。 4.2 LLM 独有检查（脚本无法判定） 无未实现占位符（禁止出现待办标记或空壳逻辑） 无冗余 Agent（每个 Agent 的职责不与其他 Agent 显著重叠，无大面积职责交叉） 降级策略覆盖所有不支持的能力 Workflow 有且仅有一个入口阶段和至少一个终止阶段 设计决策输出 生成完成后，按 templates/design-decisions.md.tmpl 输出四节设计决策说明（Agent 角色划分 / Skill 提取策略 / 工作流编排模式 / 平台适配）。 多平台同时生成 当用户请求为多个平台生成框架时： 先生成平台无关的核心结构（agents/, skills/, workflows/） 为每个目标平台生成独立的 platforms/<platform_id>/profile.yaml 共享 framework.json 但 runtime.platform 设为首选平台 在 README.md 中说明多平台切换方式 扩展机制 生成的框架遵循开闭原则：新增 Agent / Skill / Workflow / 平台 / Hook 均在 §3.1 目录树对应子目录下新建文件（ agents/ / skills/ / workflows/ / platforms/ / hooks/hooks.yaml ），不需修改已有文件。 Anti-Patterns 禁止: 生成的 SKILL.md / AGENT.md 含硬约束违规（版本里程碑 / PR 编号 / 特定语言关键字）— 下游项目会继承腐化，应在 Phase 3 模板填充后跑 check_no_design_residue / check_no_language_coupling 守卫 禁止: 生成的 Anti-Patterns 段少于 ANTI_PATTERN_MIN_COUNT_SKILL / ANTI_PATTERN_MIN_COUNT_AGENT — framework-review Layer 1 的 Anti-Patterns 数量下限检查会 FAIL，下游 framework-review 阻塞 禁止: 生成的 agent allowed_paths 与 Anti-Patterns 行为约束矛盾 — 机制层放行 vs 行为层禁止的矛盾会让 reviewer 兜底失效 避免: 生成框架时跳过 Phase 4 验证 — 自动化检查 + LLM 独有检查是防止半成品产出的关键 注意事项 生成的框架使用 CataForge 能力标识符，部署时由 deployer 自动翻译为平台原生名称 Agent 指令内容使用中文（与 CataForge 项目惯例一致），技术标识符和配置键使用英文 生成的文件不包含任何未实现占位符，每个文件都是完整可用的，不依赖后续手动补全