generate-pi-task

# MaaFramework Project Interface 任务生成 ## 功能说明 - 读取 Pipeline JSON 文件，识别可切换节点（通常是含 `enabled` 字段的节点）。 - 分析节点关系，确定选项类型：`switch`、`select`、`checkbox`、`input`。 - 生成或更新 `assets/tasks/*.json`，遵循 `tools/schema/interface_import.schema.json`。 - 更新 `assets/interface.json` 的 `import[]`。 - 补充 `assets/locales/interface/` 下项目实际支持语言的 i18n 键。 ## 使用场景 - 为 Pipeline 创建新的 Project Interface 任务文件。 - 向已有任务文件添加选项。 - 把 Pipeline 的可配置节点暴露为用户可选配置。 - 用户提到“生成任务”、“PI 任务”、“pipeline 选项”、“interface 任务”、“pipeline_override”。 ## 工作流程 ### 1. 读取规范文件 从当前项目读取： 1. `tools/schema/interface_import.schema.json` — 任务文件 schema。 2. `tools/schema/interface.schema.json` — 主 PI schema。 3. `tools/schema/pipeline.schema.json` — Pipeline 节点 schema。 如果 schema 路径不同，先按当前项目实际结构查找，不要硬编码。 ### 2. 读取 Interface 上下文 1. 读取 `assets/interface.json`。 2. 读取 `import[]` 中已有任务文件，收集已有任务名和 option key，避免冲突。 3. 记录 `group[]` 定义，确认新任务应归属哪个分组。 4. 检查 `assets/locales/interface/` 实际有哪些语言文件；只维护项目已经存在的语言。 ### 3. 确定目标文件 1. 当前活动文件在 `assets/tasks/` 且已被 `interface.json` import → 编辑该文件。 2. 当前活动文件是 Pipeline JSON → 从 `assets/resource/pipeline/{PipelineName}/` 推导 pipeline 名称，检查 `assets/tasks/{PipelineName}.json` 是否存在。 3. 无上下文 → 询问用户要为哪个 pipeline 生成。 4. 新建任务文件时，同步在 `assets/interface.json` 的 `import[]` 中添加相对路径，例如 `tasks/MyTask.json`。 ### 4. 读取 Pipeline 文件 1. 读取 `assets/resource/pipeline/{PipelineName}/` 下相关 `.json` 文件。 2. 提取每个节点的：节点名、`enabled`、`next[]`、`desc`、`recognition`、`action`。 3. 构建节点图：通过 `next[]` 建立父→子映射，识别兄弟节点和嵌套选项。 4. 如果 Pipeline 跨目录引用公共节点，只把当前任务应由用户配置的业务节点纳入选项。 ### 5. 确定选项类型 详见 [选项类型决策参考](references/option-types.md)。快速规则： - 单个含 `enabled` 的独立节点 → `switch`。 - 同一父节点下互斥的 `enabled` 子节点 → `select`。 - 多个可同时启用的独立项目 → `checkbox`。 - 选择某个 case 后才显示的子选项 → 嵌套 `case.option[]`。 - 可配置数值/文本参数 → `input`，配合 `pipeline_type` 和 `「FieldName」` 引用。 ### 6. 生成任务 JSON 严格遵循 `interface_import.schema.json`。典型结构： ```json { "task": [ { "name": "PipelineName", "label": "$task.PipelineName.label", "entry": "PipelineName", "description": "$task.PipelineName.description", "option": ["OptionKey"], "group": ["daily"] } ], "option": { "OptionKey": { "type": "switch", "label": "$option.OptionKey.label", "cases": [ { "name": "Yes", "pipeline_override": { "TargetNode": {"enabled": true} } }, { "name": "No", "pipeline_override": { "TargetNode": {"enabled": false} } } ] } } } ``` ## Locale 规则 向 `assets/locales/interface/` 下项目实际存在的语言文件补充键： - `task.{Name}.label` - `task.{Name}.description` - `option.{OptionKey}.label` - `option.{OptionKey}.{CaseName}` 或项目 schema 要求的 case label key 原则： - 用户可见字符串使用 `$` i18n key，不在任务文件中硬编码显示文案。 - 中文描述可优先参考 Pipeline 节点的 `desc`。 - 其它语言无法确定官方译名时，给出合理占位并在回复中请用户确认。 - 只维护当前项目已有 locale 文件，不要凭空新增语言文件，除非用户明确要求。 ## 注意事项 - `interface_import.schema.json` 才是任务文件 schema，不是 `interface.schema.json`。 - `entry` 必须与 Pipeline 入口节点名完全一致，区分大小写。 - `interface.json` 中的 import 路径通常相对 `assets/interface.json`，例如 `tasks/MyTask.json`。 - `enabled: false` 表示节点默认关闭，选项通常让用户将其开启。 - `enabled: true` 表示节点默认开启，选项通常让用户将其关闭。 - `switch` 的 cases 通常为 `Yes` 和 `No` 两个。 - `select` 的每个 case 需要启用自身节点，同时禁用同组互斥兄弟节点。 - `checkbox` 的每个 case 通常只启用自身节点，不禁用兄弟节点。 - 若项目已有同类任务采用不同顺序或 default_case，优先保持项目一致性。 ## 验证清单 - [ ] JSON 语法合法。 - [ ] `task[].option[]` 的 key 都在 `option` 对象中存在。 - [ ] `case.option[]` 的嵌套引用都能解析。 - [ ] 所有 `pipeline_override` 目标节点在 Pipeline 文件中存在。 - [ ] 新任务文件已加入 `assets/interface.json` 的 `import[]`。 - [ ] 所有 `$...` locale key 在项目已有 interface locale 文件中存在。 - [ ] 选项默认值与 Pipeline `enabled` 默认状态一致。