# Workflow Framework Generator

> 根据用户指定的工作流类型与目标AI IDE平台，生成一套完整的、可运行的CataForge风格智能体与Skill编程工作流框架。 支持任意领域（软件开发、内容创作、电商运营、研究分析等），自动适配Claude Code / Cursor / CodeX / OpenCode的能力差异。 当用户需要为新领域或新平台构建AI工作流时触发。

- Skill: `lync-cyber/workflow-framework-generator` (Agent Skill, multi-file: 22 files)
- Install (CLI): `npx skillmds@latest add lync-cyber/workflow-framework-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lync-cyber/workflow-framework-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: lync-cyber (https://skillmd.com/u/lync-cyber)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lync-cyber/workflow-framework-generator

---


# 工作流框架生成器 (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 解析用户输入

从用户消息中提取以下字段：

```yaml
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 领域调研增强（条件触发）

当用户需求涉及你不熟悉的领域知识时：

1. 读取 `references/domain-patterns.md` 查找是否有匹配的领域模式
2. 若无匹配，使用 web_search 检索该领域的标准工作流程和最佳实践
3. 将调研结果结构化为：关键角色、核心流程、产出物清单、质量标准
4. 将结构化结果融入后续的架构设计

---

### Phase 2: 架构规划

#### 2.1 加载平台能力矩阵

读取 `references/platform-capabilities.md`，提取目标平台的：
- 支持的工具映射（tool_map）
- 可用特性（features）
- 代理调度方式（dispatch）
- Hook 支持程度
- 降级策略需求

#### 2.2 设计 Agent 角色体系

基于工作流需求，设计 Agent 角色列表。每个 Agent 必须包含：

```yaml
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 职责中提取可复用的能力单元：

```yaml
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 编排

定义工作流的阶段、依赖和状态流转：

```yaml
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 生成目录结构

根据规划结果，生成以下目录结构：

```text
<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 提取策略 / 工作流编排模式 / 平台适配）。

---

## 多平台同时生成

当用户请求为多个平台生成框架时：

1. 先生成平台无关的核心结构（agents/, skills/, workflows/）
2. 为每个目标平台生成独立的 `platforms/<platform_id>/profile.yaml`
3. 共享 framework.json 但 runtime.platform 设为首选平台
4. 在 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 项目惯例一致），技术标识符和配置键使用英文
- 生成的文件不包含任何未实现占位符，每个文件都是完整可用的，不依赖后续手动补全