PiFlow Skill Generator Planner

核心规则

本技能是一个模板驱动的 PiFlow skill 生成器。它的职责不是找一个相似 skill 来改改，而是基于统一模板，把用户明确提供的信息、已经验证成功的流程、已有脚本和必要资源，整理成一个结构清晰、参数契约稳定、可被 PiFlow 直接识别的技能目录。

生成目标始终是一次性产出完整、可靠、符合约定的 skill 目录，包括 UTF-8 编码的 SKILL.md、DAG 可读的 input_params / output_params、skill.json、scripts/、references/、assets/，以及必要的校验与注册结果。每个生成的 skill 必须包含一个可执行 Python 入口脚本：优先复用已验证实现；没有现成实现时也必须生成 scripts/run_<skill_name>.py，使其可解析参数并输出结构化运行结果，禁止只生成元数据文件。但它不是默认优先入口；只有在用户明确要“生成/保存为 skill”，或某个流程已经真实跑通并值得沉淀时，才进入这条链路。

所有文本文件必须使用 UTF-8 读写，尤其是中文内容；Python 读写文件时显式使用 encoding="utf-8"，JSON 输出使用 ensure_ascii=False。

目录内容按职责分层：

• SKILL.md：只放触发条件、处理流程、参数契约和必要说明；
• scripts/：放稳定、可执行、可测试的入口脚本或处理逻辑；
• references/：放长规则、字段字典、复杂 schema、补充说明；
• assets/：放图标、模板、示例素材或需要随技能一起交付的资源。

本技能的实现指引遵循同一条主线：模板优先，参考次之，禁止默认整体仿写。

• 先以 references/piflow_skill_template.md 作为 SKILL.md、skill.json、参数组织方式、脚本入口形状和资源分层的统一骨架；
• 再把用户确认的信息、成功流程、已有脚本、现有 skill 中真正有用的规则和参数事实，填回模板对应位置； -当 spec 中提供 core_features、trigger_conditions、processing_logic、supported_formats、output_structure、output_examples 等字段时，将它们填入模板对应章节

因此，无论是直接生成、基于已验证流程生成，还是生成后的再次改写，最终输出都必须回到模板定义的结构，而不是回到某个历史 skill 的结构。

本技能必须能在没有其他技能辅助的环境中独立生成可靠技能：只依赖当前技能目录内的 SKILL.md、references/piflow_skill_template.md、scripts/generate_piflow_skill.py、scripts/generate_skill_files.py、scripts/register_skill_artifacts.py、scripts/rewrite_piflow_skill.py 和 scripts/validate_piflow_skill.py。生成时不要假设另一个 skill 会补全文档、脚本或元数据。本技能负责 skill 化与沉淀，不负责代替用户完成所有真实处理任务本身。

本技能支持两种使用方式：

1. 直接生成 当用户明确要求“生成 skill”“保存为 skill”“封装为 skill”“创建自定义技能”时，根据已确认的规格生成 skill。

2. 基于已验证流程生成或改写 当用户提供已验证成功的流程、脚本或输入输出约定时，优先复用这些事实生成或最小改写 skill；改写时默认保留原 skill 名称和目录位置，避免生成含义重复的新 skill。

在涉及安装、环境准备或可执行脚本验证时，优先完成最小必要依赖，再运行一个简单冒烟测试确认关键入口可执行、基础参数可解析、输出路径可写。若安装或测试失败，允许自动重试，单个阶段最多重试 5 次；若 5 次后仍失败，停止流程并把失败原因、失败步骤和最后一次错误返回给用户。

安装依赖或配置前置环境时，若不明确安装的流程或操作，需要调用网络工具获取安装指南或官方文档，或者直接调用搜索查询安装步骤，不要假设已经知道如何安装或配置。

路径规则

deepagent 的虚拟文件环境以 workspace 为根。生成的技能必须放在 skills/generated/<skill-name>（相对于 workspace 根），这样 PiFlow 才能发现。

• 默认 output_root 使用 skills/generated，表示 <workspace>/skills/generated。
• write_file/read_file 等工具调用时使用相对于 workspace 根的虚拟路径（如 skills/generated/<skill_name>/），不要带 workspace/ 前缀。
• Shell 命令中使用 --output-root skills/generated。
• 如果用户传入旧路径 workspace/skills 或 flow-deepagents/workspace/skills，脚本会归一化为当前 deepagent workspace 下的 skills/generated。
• spec_path、icon、script.source、references[].source、assets[].source 可以使用相对路径；脚本会先按当前工作目录解析，再按 deepagent workspace 根解析。
• 不要把生成目录写到仓库外层、flow-deepagents/workspace/workspace/skills 或 workspace/skills/skills。

PiFlow 技能结构

每个技能目录至少包含：

skill-name/
├── SKILL.md
├── skill.json             # 推荐，DAG 执行/画板读取的结构化元数据
├── scripts/               # 推荐，稳定可执行逻辑
├── references/            # 可选，按需读取的长文档
└── assets/
    └── icon.png           # 必须选定的主图标；若没有自定义图标，需明确兜底到分类图标

SKILL.md

SKILL.md 由 YAML frontmatter 和 Markdown body 组成。

• name：必须与目录名完全一致。
• description：主要触发入口。必须同时说明技能做什么、用户在什么表达或场景下应触发。触发信息写在这里，不要只写在正文。
• version：技能版本，默认 1.0.0。
• input_params：PiFlow DAG 面板读取的输入参数列表，必须保留。
• output_params：PiFlow DAG 面板读取的输出参数列表，必须保留。
• allowed-tools、compatibility、license、metadata：仅在确实需要时添加。
• tag：面向 DAG 面板的技能类型；当前入库逻辑会读取 tag 作为 skill_type。

参数项使用：

- name: input_path
  type: string
  required: true
  default: optional-default
  description: 输入文件路径

SKILL.md frontmatter 的参数项禁止包含 role。role 是 DAG 专用元数据，只应写入 skill.json；生成器会依据参数的 type、name 和 description 在 JSON 中推断 input_data、output_data 或 data。

skill.json

当 skill_json 未显式设为 false 时生成。该文件用于 DAG 执行链路和画板解析，包含：

• name、version、description
• language
• script_path
• entrypoint
• input_params、output_params，其中参数保留 role
• command_template
• 可选 tag

只在用户或 spec 明确提供时写入 dependencies 或 policy 等扩展字段。

Bundled Resources

• scripts/：每个 skill 都必须包含一个确定性、可执行的 Python 入口脚本。优先复用已验证逻辑；若没有现成逻辑，生成 scripts/run_<skill_name>.py，它必须接受声明的输入参数并输出 JSON 运行摘要。脚本应可通过 python scripts/<name>.py ... 调用，并使用 UTF-8 读写。
• references/：放长规则、字段字典、API 说明、数据 schema、复杂示例。正文中必须说明何时读取哪个引用文件。
• assets/：放图标、模板、示例素材、字体或输出需要复制的资源。每个 skill 在生成阶段都应明确一个主图标方案：优先提供 assets/icon.png；若暂时没有自定义图标，也必须在设计与交付时明确兜底使用对应分类图标，不要让图标策略处于未定义状态。

不要生成与执行无关的 README.md、安装指南、变更日志或重复说明文档；这些内容会稀释技能目录的信号。

生成流程

A. 手动生成链路

1. 先判断用户是否明确要求生成或保存 skill。若是，则直接进入本链路。
2. 明确具体用例。优先收集用户会怎样调用技能、输入输出文件长什么样、是否需要脚本、是否有字段规则或外部依赖。
3. 规划资源分层。重复且要求稳定的逻辑进入 scripts/；长规则进入 references/；图标和模板素材进入 assets/。这一阶段同时确定图标策略：选一个主图标来源，并明确一个兜底图标。
4. 规范命名。已有业务技能名可保留大小写和下划线，例如 QC3_NumericDataThresholdCheck、Pi_DataSorting；新通用技能优先使用 lowercase snake_case 或 hyphen-case；目录名必须等于 name。
5. 先按 references/piflow_skill_template.md 搭骨架，再填内容。正文章节顺序、frontmatter 结构、skill.json 参数契约、脚本入口和资源目录都应先服从模板；随后再把用户确认的信息、成功流程信息、脚本信息和必要规则填入对应章节。不要先挑一个相似 skill 作为底稿整体改写。
6. 生成资源目录。必须写入 scripts/run_<skill_name>.py 或用户提供的等价 Python 脚本；脚本必须与 skill.json 的 script_path、entrypoint 和 command_template 一致。只有引用资料和素材可按需省略；图标必须有明确结论：若 spec 提供 icon，复制为 assets/icon.png 作为主图标；若未提供自定义图标，则记录并验证可兜底到分类图标。
7. 校验并迭代。运行 validate_piflow_skill.py，检查 UTF-8、YAML、参数契约、目录名、资源布局和 UI metadata。
8. 安装后冒烟测试。若该技能需要额外依赖或运行时环境，在环境配置完成后先执行一个最小可运行示例或健康检查脚本，确认关键入口能正常启动并完成一次基础输入输出。
9. 失败重试与兜底。安装与冒烟测试过程中若失败，先重试再继续；单阶段最多 5 次。若 5 次都失败，停止自动化流程并把失败原因、失败步骤和最后一次错误返回给用户。

B. 基于已验证流程生成或改写

1. 读取用户提供的成功流程、脚本、样例输入输出和验证结果。
2. 优先将已有事实恢复为 spec 草稿；仅补问无法从现有材料确定的字段。
3. 使用与直接生成相同的生成、校验、注册和冒烟测试流程。
4. 若目标 skill 已存在，则复用其名称和目录，通过 overwrite 做最小改写。

三层调用模型

当前实现按职责拆成三层，并保留一个一键封装入口：

1. 生成层 负责把 spec 落成技能目录本身，包括 SKILL.md、skill.json、scripts/、references/、assets/ 等内容。 对应脚本：scripts/generate_skill_files.py

2. 注册层 负责把已生成好的技能接入 PiFlow 可见索引，包括更新 docs/skill分类.txt，以及同步 storage/skills 下的技能图标与分类图标。 对应脚本：scripts/register_skill_artifacts.py

3. 一键封装层 按顺序调用“生成层 -> 注册层”，适合默认使用。 对应脚本：scripts/generate_piflow_skill.py

调用建议

• 当你需要“先生成草稿、再人工检查、最后再发布/注册”时： 先调用生成层，再调用 validate_piflow_skill.py --mode files-only，确认通过后再调用注册层。

• 当你需要“一次性生成并接入系统可见列表”时： 直接调用一键封装层。

• 当你只是想更新技能正文、脚本、资源，但暂时不希望污染全局分类列表或图标存储时： 只调用生成层，不调用注册层。

• 当技能目录已经存在，只是因为分类列表或图标丢失，需要补注册时： 只调用注册层。

• 当用户提供一次成功的真实处理流程时： 优先恢复流程草稿 spec，再补缺失字段，然后根据是否需要立即可见，选择“只生成”或“一键生成并注册”。

• 当用户为已生成 skill 提供新的流程指引时： 保留原 skill 名称并使用 overwrite 重建，避免从零生成同义 skill。

Spec 字段

推荐使用 UTF-8 JSON spec：

• name：必填，技能目录名和 frontmatter 名称。
• title：可选，正文标题和 UI 显示名的候选值。
• description：必填，技能能力说明。仅在用户明确要求生成/保存 skill，或任务完成后需要沉淀成功流程时描述 skill 生成能力；不要把宽泛的数据处理诉求直接写成触发词。
• description：必填，技能能力说明。描述用户如何显式触发此 skill，不要把宽泛的数据处理诉求写成默认优先入口。
• version：可选，默认 1.0.0。
• triggers：可选，触发短语列表，会并入 frontmatter description。触发短语应收敛为“生成 skill”“保存为 skill”“把这次流程沉淀成 skill”等手动或收尾场景，不要把“数据清洗”“数据分析”“处理文件”等本应先直接执行的任务写成优先触发短语。
• tag：可选，写入 frontmatter 和 skill.json，用于 DAG 技能类型。
• language：可选，写入 skill.json，默认按脚本推断为 python。
• script_path、entrypoint、command_template：必填，写入 skill.json；必须指向 skill 内存在的 Python 脚本，并与输入参数一致。
• input_params、output_params：PiFlow 参数契约。参数项可包含 role。
• input_params、output_params 在 SKILL.md frontmatter 和 skill.json 中都必须是“参数对象数组”，禁止写成 { params: {...} }、{input_path: {...}} 或任何对象映射形状；每个参数必须独立占一个数组元素。
• command：可选，显式命令；缺省时根据 script.path 和输入参数生成。
• script：必填对象，支持 path、content、source；也可用 scripts 列表生成多个脚本。未提供时生成器默认创建 scripts/run_<name>.py。若来自成功流程或旧实现，优先恢复其可执行事实，但最终脚本路径、入口命名、参数契约和目录组织仍要服从模板，而不是服从原始样例的偶然结构。
• script / scripts：优先从成功运行的脚本、流程文件或实现产物恢复，再将这些内容回填进模板约定的目录结构、参数契约和资源分层；不要因为参考了旧脚本或旧 skill，就偏离模板去整体复刻旧实现。
• references：可选列表，支持 path + content 或 source。
• assets：可选列表，支持 path + content 或 source；icon 会复制为 assets/icon.png。无论是否提供自定义 icon，都必须在生成时明确一个兜底图标方案，默认可回退到分类图标。
• dependencies：可选，正文依赖列表。
• examples：可选，正文示例列表。
• core_features、trigger_conditions、processing_logic、supported_formats、output_structure、output_examples：可选，填入通用模板对应章节。
• body_sections：可选，自定义正文段落。
• skill_json：可选，默认 true；设为 false 时不生成 skill.json。
• metadata：可选；可用于记录流程来源、验证摘要和沉淀时间。
• rewrite_followup_hint：可选；用于在生成结果中覆盖默认的改写 follow-up 提示语。

命令

一键生成并注册技能：

python scripts/generate_piflow_skill.py --spec path/to/spec.json --thread-id <thread_id>

前端预览生成结果时，传入当前 thread_id；生成器会将会话 ID、skill 名称和 workspace 相对目录写入 generating_skills。同一会话再次生成时会更新该记录。

也可以显式传 --output-root skills：

python scripts/generate_piflow_skill.py --spec path/to/spec.json --output-root skills

如果已有一次已经跑通的成功流程，也可以直接传流程摘要：

python scripts/generate_piflow_skill.py --flow path/to/flow-summary.json --restored-spec-out path/to/restored-spec.json --output-root skills

若 skill 已生成完成，且用户随后提供了新的流程作为改写指引：

python scripts/rewrite_piflow_skill.py --skill-dir skills/<skill-name> --flow path/to/new-flow-summary.json --restored-spec-out artifacts/rewrite-spec.json

改写链路的依赖说明与边界约束见：

references/rewrite_followup_internal.md

仅在明确要替换生成目录时使用：

python scripts/generate_piflow_skill.py --spec path/to/spec.json --overwrite

仅生成技能文件，不注册列表和图标：

python scripts/generate_skill_files.py --spec path/to/spec.json --output-root skills

若只想把成功流程恢复为 draft spec 再人工检查：

python scripts/restore_flow_to_spec.py --flow path/to/flow-summary.json --output path/to/restored-spec.json

若想直接从成功流程生成技能文件而不注册：

python scripts/generate_skill_files.py --flow path/to/flow-summary.json --restored-spec-out path/to/restored-spec.json --output-root skills

仅注册已有技能目录的列表和图标：

python scripts/register_skill_artifacts.py --spec path/to/spec.json --skill-dir skills/<skill-name>

若当前只有成功流程摘要，也可以直接在注册时恢复 spec：

python scripts/register_skill_artifacts.py --flow path/to/flow-summary.json --restored-spec-out path/to/restored-spec.json --skill-dir skills/<skill-name>

校验技能：

python scripts/validate_piflow_skill.py skills/<skill-name>

仅校验生成层产物：

python scripts/validate_piflow_skill.py skills/<skill-name> --mode files-only

Spec 示例

{
  "name": "clean_example_transformer",
  "title": "Clean Example Transformer",
  "description": "清理文本中的示例片段。",
  "version": "1.0.0",
  "triggers": ["清理示例", "删除示例片段"],
  "tag": "数据清洗",
  "language": "python",
  "input_params": [
    {"name": "input_path", "role": "input_data", "type": "string", "required": true, "description": "输入 JSON 文件路径"},
    {"name": "output_path", "role": "output_data", "type": "string", "required": true, "description": "输出 JSON 文件路径"}
  ],
  "output_params": [
    {"name": "output_path", "role": "output_data", "type": "json_file", "description": "清理后的 JSON 文件"}
  ],
  "script": {
    "path": "scripts/run_clean_example_transformer.py",
    "content": "import argparse\n\n# TODO: implement operator\n"
  },
  "command_template": ["python", "{script_path}", "--input_path", "{input_path}", "--output_path", "{output_path}"],
  "references": [
    {"path": "references/rules.md", "content": "# 清理规则\n\n- 删除示例片段。"}
  ],
  "dependencies": ["Python 3.x"],
  "examples": [
    {
      "title": "基本调用",
      "command": "python scripts/run_clean_example_transformer.py --input_path input.json --output_path output.json"
    }
  ]
}

必要的测试

完成前确认：

• <workspace>/skills/<name>/SKILL.md 可被 PiFlow 发现；在 deepagent 环境中不要生成到其他根目录。
• name 与目录名一致，description 包含触发语义。
• 暴露机器可读的 version、tag、input_params 和 output_params。
• 生成的 skill.json 包含 entrypoint、script_path、command_template 和带 role 的参数元数据。
• 正文足够让另一个 agent 调用或继续实现技能，不依赖隐含上下文。
• 长规则没有塞进正文，而是放入 references/ 并在正文指明何时读取。
• 脚本、JSON 和 Markdown 都能 UTF-8 往返，中文不转义、不乱码。
• 可执行 Python 脚本已生成或复制，且与 skill.json 的入口元数据一致；禁止省略。
• 输出结构以 references/piflow_skill_template.md 为主骨架；即使引用了旧脚本、旧 skill 或成功流程，也没有退化为对相似 skill 的整体复刻。
• 技能通过 validate_piflow_skill.py。
• 需要运行时依赖的技能，已在环境就绪后做过最小冒烟测试。
• 安装或测试失败时已进行重试；若达到 5 次仍失败，则已向用户反馈明确错误。
• 触发表达已经收敛为“仅手动指定或任务完成后沉淀”，没有把本技能写成默认优先入口。
• 如果 skill 生成后用户又提供了新的成功流程，已考虑是否提示进入内部改写链路继续做最小改写。
• 如果 skill 声明了报告文件或类似结果工件，则失败路径也已实测验证：脚本会优先落盘最小失败摘要和问题清单，再以非零状态码结束，而不是未经兜底直接抛异常退出。

失败路径可观测性约束

复盘结论：对于会生成报告文件或其他结果工件的 skill，不能只设计成功路径；失败路径也必须可观测、可追溯。入口脚本应优先捕获异常、尽可能落盘最小失败摘要与问题清单，明确失败步骤、原因和上下文，再以非零状态码结束；不要在核心流程中未经兜底地直接抛出异常后退出。

生成此类 skill 时，额外遵守：

• 若 spec 定义了摘要、问题清单、报告或其他结果工件，脚本必须同时实现成功和失败两条输出路径。
• strict_mode 或其他失败条件触发时，不应在关键失败产物尚未落盘前直接中断。
• 若只能生成部分结果，也应先写出部分结果，并在失败摘要中标明失败阶段、最后一次错误和未完成项。

不要记录以下内容（这些会变成长期存在的自我约束，并在环境变化后反过来带来影响）：

环境相关故障：缺失二进制文件、全新安装错误、迁移后路径不匹配、command not found、未配置凭据、未安装软件包等。用户可以修复这些问题，它们不是持久规则。 关于工具或功能的负面断言：如“浏览器工具无法工作”、“X 工具已损坏”、“远程资源不包含 Y”等。这些会固化成长期拒绝理由，即使实际问题早已被修复。 会话中已经解决的临时错误。如果重试后成功了，应记录重试模式，而不是原始失败。 一次性任务叙述。用户要求“总结今天的市场”或“分析这个 PR”，并不构成一个值得创建技能的工作类别。

自测引导

除 validate_piflow_skill.py 外，生成中等及以上复杂度 skill 时，至少执行以下自测：

1. 语法检查：对入口脚本和内部模块运行 python -m py_compile ...，先排除最基础的语法问题。
2. 正常样例测试：准备一组最小有效输入，实跑入口脚本，确认关键输出工件全部实际生成，并核对 summary 与核心报告内容。
3. 失败样例测试：故意缺少关键输入、配置或依赖，再运行一次，确认脚本返回非零状态码，同时仍能落盘最小失败摘要和问题清单。
4. 输出核对：检查 skill.json 中声明的关键输出参数，在正常路径和失败路径下都能找到对应产物，或至少有明确的失败说明。
5. 严格模式核对：若存在 strict_mode，必须额外做一次 strict_mode 实测，确认它改变的不只是退出码，还包括完整的失败可观测行为。