Project Scaffold Skill v2

Core Philosophy

Flow first, scaffold second. Before touching any technical parameter, the project must be understood as a process. The flowchart is the source of truth — all config (cron, skills, routing, state files) is derived from it.

How It Works — Four Phases

用户触发 → 阶段零：LLM推理 → 阶段一：确认流程图 → 阶段二：节点配置 → 阶段三：技术初始化 → 生成项目

Phase 0: LLM Reasoning (Automatic)

Triggered as soon as the user describes a project in plain language.

Step 0.1 — Infer Project Structure

Synthesize a project structure from the user's plain-language description using the LLM's own reasoning, guided by the flow_design_language node vocabulary.

Model selection:

• Default: MiniMax-M2.5 (FAST tier, cost-efficient)
• Upgrade to GPT-4.1 (SMART tier) when: the project involves 5+ nodes, multiple conditions/branches, or non-standard sources
• Upgrade to POWER/MAX only when the user explicitly requests it or the project involves mission-critical logic

Reasoning process (not an external API call):

Phase 0 does not call another model or external API. The LLM synthesizes the structure internally by applying the following reasoning steps to the user's plain-language description:

1. Classify project type (content monitoring / auto-publish / data collection / hybrid)
2. Determine trigger type (cron / event / manual)
3. Map the core flow: which nodes are required from trigger to end
4. Assign a skill recommendation to each node
5. Identify whether conditions or wait nodes are needed

Output fields:

{
  "project_type": "...",
  "trigger_type": "cron | event | manual",
  "flowchart": "<single-line Mermaid, flowchart LR>",
  "nodes": [{"id": "FETCH", "label": "抓取内容", "type": "fetch", "skill": "...", "config": {}}],
  "complexity": "low | medium | high",
  "recommended_model": "minimax | gpt-4.1 | power | max"
}

Present the result to the user as a draft:

LLM 推理结果（模型：MiniMax-M2.5） 项目类型：内容监控 推荐流程：trigger → fetch → filter → rewrite → publish → report → end

flowchart LR
    START([开始]) --> TRIGGER{{定时触发}}
    ...

模型推荐：GPT-4.1（项目较复杂）— 如需调整请说"用 GPT-4.1"或"切换到快速模式"

Model switch trigger: if the user's description mentions "复杂"、"高要求"、"多条件"，auto-escalate model to GPT-4.1 and confirm.

Step 0.2 — User Confirms or Adjusts

The user may:

• Confirm: "没问题，继续"
• Adjust: "把 X 改成 Y" → regenerate with adjusted nodes
• Switch model: "用 GPT-4.1 重来" or "快速模式就够了"
• Skip reasoning: "直接告诉我流程，我自己调整"

Once confirmed → proceed to Phase 1.

JSON validation sanity check (do not skip): Before presenting Phase 0 output, verify the flowchart Mermaid syntax is valid (all nodes use correct {{ }} for conditions, [ ] for processes, matching brackets). If malformed, regenerate rather than present broken diagrams to the user.

Phase 1: Design the Flowchart

Step 1.0 — Model Declaration (from Phase 0)

At the start of Phase 1, state the active model based on Phase 0 output:

Phase 1 模型：GPT-4.1（Phase 0 推荐：项目涉及多条件分支） 如需切换，请说"切换到 MiniMax"或"用 POWER"

If Phase 0 was skipped, infer model from the confirmed flowchart: low complexity (≤4 nodes, no conditions) → MiniMax-M2.5; medium/higher → GPT-4.1.

Step 1.1 — Confirm or Edit Flowchart

The Phase 0 LLM reasoning output becomes the starting point. Ask:

"以上流程图是否准确？需要调整吗？"

If the user made no prior description (Phase 0 skipped), fall back to the original Step 1.1: ask "这个项目要自动化什么？最终产出是什么？谁会用到它？"

Supported node types:

Step 1.2 — Edit if Needed

If the user requests changes, update the Mermaid diagram directly. Use the same syntax rules from Phase 0.

Mermaid syntax rules (for edits):

• Use {{ }} for conditions/decision nodes
• Use [ ] for process nodes
• Use (-->) for main flow arrows
• Use -->| for conditional arrows with label
• Use (|label|) for conditional branches

Step 1.3 — Iterative Refinement

Ask the user if the flowchart is correct. Allow edits:

• User says "把 X 和 Y 合并成一个节点" → regenerate
• User says "在 A 和 B 之间加一个过滤节点" → insert node
• User says "X 之后要等 10 分钟再发布" → add wait node
• User says "改写之前还要翻译成英文" → insert translate node

Repeat until the user confirms: "没问题，继续" or "可以了".

Phase 2: Configure Each Node

After flowchart is confirmed, go through each node (except START/END) and ask. Use the nodes array from Phase 0 as the starting config draft for each node — pre-fill known fields (type, skill) and confirm or override.

"节点 [X] 需要配置什么？"

For each node, derive and confirm:

Skill auto-recommendation logic:

node.type = "fetch" + source contains "youtube" → recommend "yt-dlp / summarize"
node.type = "fetch" + source contains "rss" → recommend "summarize"
node.type = "fetch" + source is "webpage" → recommend "summarize / browser-use"
node.type = "rewrite" → recommend MiniMax-M2.5 by default
node.type = "generate" + "image" → recommend image_generate (gemini/gpt-image-2)
node.type = "generate" + "video" → recommend video_generate
node.type = "publish" + "wechat" → recommend wechat-api (agent-reach)
node.type = "publish" + "telegram" → recommend telegram bot
node.type = "filter" → recommend regex / keyword / LLM
node.type = "report" → always available (pipeline_reporter)

For each node, confirm:

1. The recommended skill(s)
2. Any required credentials or tokens (e.g. WeChat API key, bot token)

Step 2.1 — Compile Final nodes_json

After all nodes are configured, serialize the final node list as a JSON array. This becomes --nodes-json for bootstrap_project.py:

nodes_json='[
  {"id": "FETCH", "label": "抓取内容", "type": "fetch", "skill": "summarize", "config": {"source": "..."}},
  {"id": "FILTER", "label": "过滤", "type": "filter", "skill": "regex", "config": {"keywords": "..."}}
]'

Verify before proceeding: JSON validation runs automatically during --interactive bootstrap via the script layer. If running manual invocation, verify with echo $nodes_json | python3 -m json.tool > /dev/null before passing to --nodes-json.

Phase 3: Technical Initialization

After all nodes are configured, collect the remaining technical parameters:

Required (*)

Optional

Step 4: Generate Project

After all parameters confirmed, run the bootstrap script:

python3 skills/project-scaffold/scripts/bootstrap_project.py \
  --project-key "<project_key>" \
  --project-name "<project_name>" \
  --description "<description>" \
  --flowchart "<mermaid_flowchart_as_single_line>" \
  --bot-token "<bot_token>" \
  --chat-id "<chat_id>" \
  --thread-ids "<thread_ids>" \
  --cron-schedule "<cron_schedule>" \
  --cron-timeout "<cron_timeout_seconds>" \
  --nodes-json '<nodes_json>'

The script generates:

• All identity/project/workflow files
• config/runtime.env with skill deps
• WORKFLOW.md with the Mermaid flowchart embedded
• scripts/run_pipeline.sh with nodes wired as pipeline stages
• scripts/<project>_bot.py as a stub placeholder — node logic is commented, requires manual implementation per node after scaffold
• Telegram routing + Cron registration

Stub bot note: <project>_bot.py is generated as a bare placeholder. The nodes_json config is written to WORKFLOW.md for reference, but the stub does not auto-wire skills or credentials. After scaffold, implement each node handler in the stub using the skill calls documented in WORKFLOW.md.

Bootstrap Flags

交互式引导步骤：

1. project_key — 英文小写+短横线，自动验证格式
2. project_name — 中文名
3. description — 项目描述
4. chat_id — 格式验证
5. bot_token — 长度验证
6. routing_group — 默认 new
7. cron_schedule — 5位 cron 验证
8. 线程 ID — general/report/chat 默认 1/2/3
9. 确认后自动进入 --fix-and-continue 流程 |

推荐工作流（简化版）：

1. bootstrap_project.py --interactive → 交互式引导，参数自动验证，一步完成 bootstrap
2. 或分步：bootstrap_project.py --plan ... → bootstrap_project.py --fix-and-continue --validate-only <path>
3. 定期：bootstrap_project.py --all-projects → 全项目体检，优先修复 FAIL 数量最多的项目

完整五步（当需要细粒度控制时）：

1. bootstrap_project.py --plan ...
2. bootstrap_project.py --dry-run ...
3. bootstrap_project.py --fix-dry-run --validate-only <path>
4. bootstrap_project.py --fix --validate-only <path>
5. bootstrap_project.py --continue-from-fix <path>

Required References

Before running, read:

• references/architecture.md — shared pipeline pattern (unchanged, still valid)
• references/flow_design_language.md — node type definitions, Mermaid syntax guide, and skill recommendation rules
• references/onboarding_checklist.md — project setup checklist
• references/shared_routing_group_schema.md — shared routing group schema

Constraints

• Never start with technical parameters. Flowchart must be confirmed before asking for bot_token / chat_id / cron_schedule.
• Every non-START/END node must have a skill assignment before generation.
• WeChat publish is optional. Only include WeChat config if a publish node targets WeChat.
• Cron delivery is always mode=none. Reporter controls delivery to prevent dual-reporting.
• Mermaid is primary; ASCII is fallback if Telegram cannot render the code block.
• If user is unsure about a node, ask a clarifying question rather than guessing. A vague flow is better than a wrong one — the flowchart is a thinking tool, not a constraint.
• Report nodes are mandatory for automated pipelines. Human-in-the-loop approval steps should also appear as report nodes.

Example Conversation Flow

用户: 创建一个新的内容监控项目
AK:    收到，正在推理项目结构...

  LLM 推理结果（模型：MiniMax-M2.5）
  项目类型：内容监控 + 自动发布
  推荐流程：trigger → fetch → filter → rewrite → publish → report → end

  ```mermaid
  flowchart LR
      START([开始]) --> TRIGGER{{定时触发}}
      TRIGGER --> FETCH[抓取油管频道]
      FETCH --> FILTER{新视频?}
      FILTER -->|是| REWRITE[改写为公众号风格]
      FILTER -->|否| END1([结束])
      REWRITE --> PUBLISH[发布到微信公众号]
      PUBLISH --> REPORT[汇报结果]
      REPORT --> END2([结束])

模型推荐：GPT-4.1（涉及多平台判断）— 如需调整请说"用 GPT-4.1"

确认这个流程？ 用户: 可以，但我想在改写之前先加一个质量判断 AK: 收到，更新后的图：

flowchart LR
    START --> TRIGGER{{定时触发}}
    TRIGGER --> FETCH[抓取油管频道]
    FETCH --> FILTER{新视频?}
    FILTER -->|否| END1
    FILTER -->|是| QUALITY{内容质量够高?}
    QUALITY -->|否| END2
    QUALITY -->|是| REWRITE[改写为公众号风格]
    REWRITE --> PUBLISH[发布到微信公众号]
    PUBLISH --> REPORT --> END3

这样可以吗？ 用户: 没问题，继续 AK: 好，现在配置每个节点：

节点 [定时触发] — cron 表达式是什么？比如每天早上 9 点：0 9 * * * 用户: 每天早上9点 AK: 收到。节点 [抓取油管频道] — 频道 RSS 或 URL 是什么？ 用户: 有三个频道... （继续逐节点配置...）