Back to Details

mthds-fix

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Fix MTHDS bundles

修复MTHDS bundles

Automatically fix issues in MTHDS method bundles.
自动修复MTHDS方法包中的问题。

Process

流程

Step 0 — CLI Check (mandatory, do this FIRST)

步骤0 — CLI检查（强制要求，优先执行）

Run 
mthds-agent --version
. The minimum required version is 0.1.0 (declared in this skill's front matter as 
min_mthds_version
).
  • If the command is not found: STOP. Do not proceed. Tell the user:
The 
mthds-agent
CLI is required but not installed. Install it with:
npm install -g mthds
Then re-run this skill.
  • If the version is below 0.1.0: STOP. Do not proceed. Tell the user:
This skill requires 
mthds-agent
version 0.1.0 or higher (found X.Y.Z). Upgrade with:
npm install -g mthds@latest
Then re-run this skill.
  • If the version is 0.1.0 or higher: proceed to the next step.
Do not write 
.mthds
files manually, do not scan for existing methods, do not do any other work. The CLI is required for validation, formatting, and execution — without it the output will be broken.
No backend setup needed: This skill works without configuring inference backends or API keys. You can start building/validating methods right away. Backend configuration is only needed to run methods with live inference — use 
/pipelex-setup
when you're ready.
运行
mthds-agent --version
。最低要求版本为0.1.0（在本技能的前置信息中声明为
min_mthds_version
）。
  • 如果未找到该命令：停止操作，不要继续，告知用户：
需要
mthds-agent
CLI但尚未安装。请使用以下命令安装：
npm install -g mthds
安装完成后重新运行本技能。
  • 如果版本低于0.1.0：停止操作，不要继续，告知用户：
本技能要求
mthds-agent
版本为0.1.0或更高（当前版本为X.Y.Z）。请使用以下命令升级：
npm install -g mthds@latest
升级完成后重新运行本技能。
  • 如果版本为0.1.0或更高：继续执行下一步。
不要手动编写
.mthds
文件，不要扫描现有方法，不要执行任何其他操作。校验、格式化和执行都需要用到CLI，没有它输出内容会出错。
无需后端配置：本技能无需配置推理后端或API密钥即可运行，你可以立即开始构建/校验方法。仅当需要通过实时推理运行方法时才需要配置后端，准备就绪后可使用
/pipelex-setup
命令配置。

Step 1: Validate and Identify Errors

步骤1：校验并识别错误

Always use 
-L
pointing to the bundle's own directory to avoid namespace collisions:
bash
mthds-agent pipelex validate pipe <file>.mthds -L <bundle-directory>/
Parse the JSON output:
  • If 
    success: true
    — nothing to fix, report clean status
  • If 
    error_type: "ValidateBundleError"
    — iterate through 
    validation_errors
    array and fix each (Step 2)
  • If model/config error — see Error Handling Reference (cannot be fixed by editing the .mthds file)
始终使用
-L
参数指向包自身的目录，避免命名空间冲突：
bash
mthds-agent pipelex validate pipe <file>.mthds -L <bundle-directory>/
解析JSON输出：
  • 如果
    success: true
    — 无需修复，报告状态正常
  • 如果
    error_type: "ValidateBundleError"
    — 遍历
    validation_errors
    数组逐一修复（步骤2）
  • 如果是模型/配置错误 — 参考错误处理参考（无法通过编辑.mthds文件修复）

Step 2: Fix .mthds Validation Errors

步骤2：修复.mthds校验错误

Use the 
error_type
field from each validation error to determine the fix:
Error TypeFix Strategy
missing_input_variable
Add the missing variable(s) to the parent pipe's 
inputs
line
extraneous_input_variable
Remove the unused variable(s) from the pipe's 
inputs
line
input_stuff_spec_mismatch
Correct the concept type in 
inputs
to match what the sub-pipe expects
inadequate_output_concept
Change the 
output
field to the correct concept type
inadequate_output_multiplicity
Add or remove 
[]
from the output concept
circular_dependency_error
Restructure the method to break the cycle
llm_output_cannot_be_image
Use PipeImgGen instead of PipeLLM for image generation
img_gen_input_not_text_compatible
Ensure PipeImgGen input is text-based (use 
ImgGenPrompt
)
invalid_pipe_code_syntax
Rename the pipe to valid snake_case
unknown_concept
Add the concept definition to the bundle, or fix the typo
batch_item_name_collision
Rename 
input_item_name
(or 
batch_as
) to a distinct singular form of the list name. Also update the branch pipe's 
inputs
to use the new item name.
For error type descriptions, see Error Handling — Validation Error Types.
使用每个校验错误的
error_type
字段确定修复方案：
错误类型修复策略
missing_input_variable
将缺失的变量添加到父管道的
inputs
行
extraneous_input_variable
从管道的
inputs
行中移除未使用的变量
input_stuff_spec_mismatch
修正
inputs
中的概念类型，匹配子管道的预期要求
inadequate_output_concept
将
output
字段修改为正确的概念类型
inadequate_output_multiplicity
为输出概念添加或移除
[]
circular_dependency_error
重构方法逻辑打破循环依赖
llm_output_cannot_be_image
使用PipeImgGen而非PipeLLM生成图像
img_gen_input_not_text_compatible
确保PipeImgGen输入为文本格式（使用
ImgGenPrompt
）
invalid_pipe_code_syntax
将管道重命名为符合要求的snake_case格式
unknown_concept
向包中添加概念定义，或修正拼写错误
batch_item_name_collision
将
input_item_name
（或
batch_as
）重命名为列表名称对应的单数形式，同时更新分支管道的
inputs
使用新的条目名称。
如需错误类型说明，请参考错误处理 — 校验错误类型。

Step 3: Fix TOML Formatting Issues

步骤3：修复TOML格式问题

These aren't always reported by validation but cause problems:
Multi-line inputs — must be on a single line:
toml
undefined
这类问题通常不会被校验报告，但会导致运行故障：
多行输入 — 必须写在单行：
toml
undefined

WRONG

错误写法

inputs = { a = "A", b = "B" }
inputs = { a = "A", b = "B" }

CORRECT

正确写法

inputs = { a = "A", b = "B" }

**Pipe ordering** — controllers before sub-pipes:
```toml
inputs = { a = "A", b = "B" }

**管道排序** — 控制器放在子管道前面：
```toml

CORRECT: main pipe first, then sub-pipes in execution order

正确写法：主管道优先，子管道按执行顺序排列

[pipe.main_workflow] type = "PipeSequence" steps = [ { pipe = "step_one", result = "intermediate" }, { pipe = "step_two", result = "final" } ]
[pipe.step_one] ...
[pipe.step_two] ...

**Missing required fields** — add with sensible defaults:
- `description` on every pipe and concept
- `type` on every pipe
- `output` on every pipe
[pipe.main_workflow] type = "PipeSequence" steps = [ { pipe = "step_one", result = "intermediate" }, { pipe = "step_two", result = "final" } ]
[pipe.step_one] ...
[pipe.step_two] ...

**缺失必填字段** — 添加合理的默认值：
- 每个管道和概念都需要添加`description`
- 每个管道都需要有`type`字段
- 每个管道都需要有`output`字段

Step 4: Re-validate

步骤4：重新校验

After applying fixes, re-validate:
bash
mthds-agent pipelex validate pipe <file>.mthds -L <bundle-directory>/
Continue the fix-validate loop until 
success: true
is returned. Some fixes reveal new issues — for example, fixing a 
missing_input_variable
may expose an 
input_stuff_spec_mismatch
on the newly added input.
If the fix-validate loop gets stuck or errors are unclear, re-run with 
--log-level debug
for additional context:
bash
mthds-agent --log-level debug pipelex validate pipe <file>.mthds -L <bundle-directory>/
应用修复后，重新执行校验：
bash
mthds-agent pipelex validate pipe <file>.mthds -L <bundle-directory>/
持续执行“修复-校验”循环，直到返回
success: true
。部分修复可能会暴露新问题：例如修复
missing_input_variable
后，新添加的输入可能会出现
input_stuff_spec_mismatch
错误。
如果“修复-校验”循环陷入僵局，或错误信息不明确，可以添加
--log-level debug
参数重新运行获取更多上下文：
bash
mthds-agent --log-level debug pipelex validate pipe <file>.mthds -L <bundle-directory>/

Step 5: Report Results

步骤5：报告结果

  • List all changes made (which pipes were modified and how)
  • Show the final validation result
  • Flag any remaining warnings or suggestions
  • 列出所有执行的修改（哪些管道被修改，以及修改方式）
  • 展示最终的校验结果
  • 标注所有剩余的警告或建议

Reference

参考

  • Error Handling — read when CLI returns an error to determine recovery
  • MTHDS Agent Guide — read for CLI command syntax or output format details
  • MTHDS Language Reference — read when writing or modifying .mthds TOML syntax
  • Native Content Types — read when fixing type mismatches involving native concepts, to verify available attributes
  • 错误处理 — CLI返回错误时阅读，确定恢复方案
  • MTHDS Agent指南 — 阅读了解CLI命令语法或输出格式详情
  • MTHDS语言参考 — 编写或修改.mthds TOML语法时阅读
  • 原生内容类型 — 修复涉及原生概念的类型不匹配问题时阅读，确认可用属性