mthds-run

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Run MTHDS methods

运行MTHDS方法

Execute MTHDS method bundles and interpret their JSON output.

执行MTHDS方法包并解析其JSON输出。

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.

运行

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是校验、格式化和执行的必备工具，没有它输出结果会出错。

Step 0.5 — Pipelex Runtime Check (mandatory)

步骤0.5 — Pipelex运行时检查（强制要求）

Running methods requires the Pipelex runtime to be installed and configured.

First, check if

pipelex-agent

is available:

bash

pipelex-agent --version

If the command is not found: STOP. Tell the user:

The Pipelex runtime is not installed. Install it with:
curl -fsSL https://pipelex.com/install.sh | sh

Then, if

pipelex-agent

is installed, check configuration health:

bash

mthds-agent pipelex doctor

If the doctor reports config issues (missing backends, missing API keys) AND the user is requesting a live run (not
```
--dry-run
```
): STOP. Tell the user:

Pipelex needs to be configured with inference backends before running methods. Use
/pipelex-setup
for guided configuration.

If the user is requesting a dry run (
```
--dry-run
```
): config issues are OK — dry runs work without backend configuration. Proceed.
If healthy: proceed to Step 1.

运行方法需要先安装并配置Pipelex运行时。

首先，检查

pipelex-agent

是否可用：

bash

pipelex-agent --version

如果未找到该命令：停止操作，告知用户：

Pipelex运行时尚未安装。请使用以下命令安装：
curl -fsSL https://pipelex.com/install.sh | sh

接下来，如果已经安装

pipelex-agent

，检查配置健康状态：

bash

mthds-agent pipelex doctor

如果健康检查报告配置问题（缺少后端、缺少API密钥） 且用户请求的是正式运行（不是
```
--dry-run
```
）：停止操作，告知用户：

运行方法前需要为Pipelex配置推理后端。使用
/pipelex-setup
获取引导式配置指引。

如果用户请求的是试运行（
```
--dry-run
```
）：配置问题不影响，试运行不需要后端配置，继续操作即可。
如果健康状态正常：继续执行步骤1。

Step 1: Identify the Target

步骤1：确定运行目标

Target	Command
Pipeline directory (recommended)	`mthds-agent pipelex run pipe <bundle-dir>/`
Specific pipe in a directory	`mthds-agent pipelex run pipe <bundle-dir>/ --pipe my_pipe`
Bundle file directly	`mthds-agent pipelex run pipe bundle.mthds -L <bundle-dir>/`
Pipe by code from library	`mthds-agent pipelex run pipe my_pipe`

Directory mode (recommended): Pass the pipeline directory as target. The CLI auto-detects
bundle.mthds
,
inputs.json
, and sets
-L
automatically — no need to specify them explicitly. This also avoids namespace collisions with other bundles.

目标	命令
流水线目录（推荐）	`mthds-agent pipelex run pipe <bundle-dir>/`
目录下的指定pipe	`mthds-agent pipelex run pipe <bundle-dir>/ --pipe my_pipe`
直接指定包文件	`mthds-agent pipelex run pipe bundle.mthds -L <bundle-dir>/`
调用库中的pipe代码	`mthds-agent pipelex run pipe my_pipe`

目录模式（推荐）：传入流水线目录作为目标，CLI会自动检测
bundle.mthds
、
inputs.json
并自动设置
-L
参数，无需显式指定，同时还能避免与其他包产生命名空间冲突。

Step 2: Prepare Inputs and Check Readiness

步骤2：准备输入并检查就绪状态

Fast path — inputs just prepared

快速路径 — 输入已提前准备

If inputs were already prepared during this conversation — via

/mthds-inputs

(user-data, synthetic, or mixed strategy), or by manually assembling

inputs.json

with real values earlier in this session — skip the schema fetch and readiness check. The inputs are ready. Proceed directly to Step 3 with a normal run.

This applies when you just wrote or saw

inputs.json

being written with real content values. It does NOT apply after

/mthds-build

(which saves a placeholder template) or after

/mthds-inputs

with the template strategy.

如果在本次对话中已经通过

/mthds-inputs

准备好输入（用户数据、合成数据或混合策略），或者在本次会话的更早阶段已经手动组装好包含真实值的

inputs.json

，可以跳过schema获取和就绪检查，输入已准备完成，直接进入步骤3正常运行即可。

该规则仅适用于你刚刚编写或看到

inputs.json

被写入了真实内容的场景，不适用于

/mthds-build

（仅保存占位符模板）或使用模板策略执行

/mthds-inputs

之后的场景。

Full check — cold start

完整检查 — 冷启动

/mthds-run

is invoked without prior input preparation in this session, perform the full readiness check:

Get the input schema for the target:

bash

mthds-agent pipelex inputs pipe bundle.mthds

Output:

json

{
  "success": true,
  "pipe_code": "process_document",
  "inputs": {
    "document": {
      "concept": "native.Document",
      "content": {"url": "url_value"}
    },
    "context": {
      "concept": "native.Text",
      "content": {"text": "text_value"}
    }
  }
}

Fill in the

content

fields with actual values. For complex inputs, use the /mthds-inputs skill.

如果调用

/mthds-run

前本次会话中没有提前准备输入，执行完整的就绪检查：

获取目标的输入schema：

bash

mthds-agent pipelex inputs pipe bundle.mthds

输出示例：

json

{
  "success": true,
  "pipe_code": "process_document",
  "inputs": {
    "document": {
      "concept": "native.Document",
      "content": {"url": "url_value"}
    },
    "context": {
      "concept": "native.Text",
      "content": {"text": "text_value"}
    }
  }
}

使用真实值填充

content

字段，复杂输入可以使用/mthds-inputs技能处理。

Input Readiness Check

输入就绪检查

Before running, assess whether inputs are ready. This prevents runtime failures from placeholder values.

No inputs required: If

mthds-agent pipelex inputs pipe

returns an empty

inputs

object (

{}

), inputs are ready — skip to Step 3.

Inputs required: If inputs exist, check

inputs.json

for readiness:

Does
```
inputs.json
```
exist in the bundle directory?
If it exists, scan all
```
content
```
values for placeholder signals:
- Template defaults:
```
"url_value"
```
  ,
```
"text_value"
```
  ,
```
"number_value"
```
  ,
```
"integer_value"
```
  ,
```
"boolean_value"
```
  , or any value matching the pattern
```
*_value
```
- Angle-bracket placeholders: values containing
```
<...>
```
  (e.g.
```
<path-to-cv.pdf>
```
  ,
```
<your-text-here>
```
  )
- Non-existent file paths:
```
url
```
  fields pointing to local files that don't exist on disk

Readiness result:

Ready:
```
inputs.json
```
exists AND all content values are real (no placeholders, referenced files exist) → proceed to Step 3 with normal run
Not ready:
```
inputs.json
```
is missing, OR contains any placeholder values → proceed to Step 3 with dry-run fallback

运行前评估输入是否就绪，避免占位符值导致运行时失败。

无需输入：如果

mthds-agent pipelex inputs pipe

返回空的

inputs

对象（

{}

），说明输入已就绪，直接跳转到步骤3。

需要输入：如果存在输入，检查

inputs.json

的就绪状态：

包目录下是否存在
```
inputs.json
```
？
如果存在，扫描所有
```
content
```
值是否存在占位符信号：
- 模板默认值：
```
"url_value"
```
  、
```
"text_value"
```
  、
```
"number_value"
```
  、
```
"integer_value"
```
  、
```
"boolean_value"
```
  ，或任何匹配
```
*_value
```
  模式的值
- 尖括号占位符：包含
```
<...>
```
  的值（例如
```
<path-to-cv.pdf>
```
  、
```
<your-text-here>
```
  ）
- 不存在的文件路径：
```
url
```
  字段指向的本地文件在磁盘上不存在

就绪结果：

就绪：
```
inputs.json
```
存在且所有content值都是真实的（无占位符、引用的文件存在）→ 进入步骤3正常运行
未就绪：
```
inputs.json
```
缺失，或包含任意占位符值 → 进入步骤3，默认使用试运行回退方案

Step 3: Choose Run Mode

步骤3：选择运行模式

If inputs are not ready

如果输入未就绪

Default to

--dry-run --mock-inputs

and inform the user:

"The inputs for this pipeline contain placeholder values (not real data). I'll do a dry run with mock inputs to validate the pipeline structure."

After the dry run, offer the user these options:

Prepare real inputs — use
```
/mthds-inputs
```
to fill in actual values, then re-run
Provide files — if the pipeline expects file inputs (documents, images), ask the user to supply file paths
Keep dry run — accept the dry-run result as-is

默认使用

--dry-run --mock-inputs

并告知用户：

"该流水线的输入包含占位符值（非真实数据），我将使用模拟数据执行试运行，验证流水线结构是否正常。"

试运行结束后，为用户提供以下选项：

准备真实输入 — 使用
```
/mthds-inputs
```
填充真实值后重新运行
提供文件 — 如果流水线需要文件输入（文档、图片），请用户提供文件路径
保留试运行结果 — 直接接受试运行结果

Run modes reference

运行模式参考

Mode	Command	Use When
Dry run + mock inputs	`mthds-agent pipelex run pipe <bundle-dir>/ --dry-run --mock-inputs`	Quick structural validation, no real data needed, or inputs not ready
Dry run with real inputs	`mthds-agent pipelex run pipe <bundle-dir>/ --dry-run`	Validate input shapes without making API calls (auto-detects `inputs.json` )
Full run	`mthds-agent pipelex run pipe <bundle-dir>/`	Production execution (auto-detects `inputs.json` )
Full run inline	`mthds-agent pipelex run pipe <bundle-dir>/ --inputs '{"theme": ...}'`	Quick execution with inline JSON inputs
Full run without graph	`mthds-agent pipelex run pipe <bundle-dir>/ --no-graph`	Execute without generating graph visualization
Full run with memory	`mthds-agent pipelex run pipe <bundle-dir>/ --with-memory`	When piping output to another method

Graph by default: Execution graphs (
live_run.html
/
dry_run.html
) are now generated automatically. Use
--no-graph
to disable.

模式	命令	使用场景
试运行 + 模拟输入	`mthds-agent pipelex run pipe <bundle-dir>/ --dry-run --mock-inputs`	快速结构验证，不需要真实数据，或输入未就绪
使用真实输入试运行	`mthds-agent pipelex run pipe <bundle-dir>/ --dry-run`	无需调用API即可验证输入格式（自动检测 `inputs.json` ）
全量运行	`mthds-agent pipelex run pipe <bundle-dir>/`	生产环境执行（自动检测 `inputs.json` ）
内联输入全量运行	`mthds-agent pipelex run pipe <bundle-dir>/ --inputs '{"theme": ...}'`	使用内联JSON输入快速执行
不生成图谱全量运行	`mthds-agent pipelex run pipe <bundle-dir>/ --no-graph`	执行时不生成图谱可视化内容
带内存全量运行	`mthds-agent pipelex run pipe <bundle-dir>/ --with-memory`	需要将输出传递给其他方法时使用

默认生成图谱：现在执行时会自动生成执行图谱（
live_run.html
/
dry_run.html
），使用
--no-graph
可关闭该功能。

Inline JSON for Inputs

内联JSON输入

The

--inputs

flag accepts both file paths and inline JSON. The CLI auto-detects: if the value starts with

, it is parsed as JSON directly. This is the fastest path — no file creation needed for simple inputs.

bash

undefined

--inputs

参数同时支持文件路径和内联JSON，CLI会自动检测：如果值以

开头，就会直接解析为JSON。这是最快的输入方式，简单输入不需要创建文件。

bash

undefined

Inline JSON

内联JSON

mthds-agent pipelex run pipe <bundle-dir>/ --inputs '{"theme": {"concept": "native.Text", "content": {"text": "nature"}}}'

File path (auto-detected in directory mode)

文件路径（目录模式下自动检测）

mthds-agent pipelex run pipe <bundle-dir>/

undefined

mthds-agent pipelex run pipe <bundle-dir>/

undefined

Step 4: Present Results

步骤4：呈现结果

After a successful run, always show the actual output to the user — never just summarize what fields exist.

运行成功后，始终向用户展示真实输出 — 不要仅总结存在哪些字段。

Output format modes

输出格式模式

The CLI has two output modes:

Compact (default): stdout is the concept's structured JSON directly — no envelope, no
```
success
```
wrapper. This is the primary output of the method's main concept. Parse the JSON directly for field access.
With memory (
--with-memory
): stdout has
```
main_stuff
```
(with
```
json
```
,
```
markdown
```
,
```
html
```
renderings) +
```
working_memory
```
(all named stuffs and aliases). Use this when piping output to another method.

The

output_file

and

graph_files

are written to disk as side effects (paths appear in logs/stderr), not in compact stdout.

CLI有两种输出模式：

精简模式（默认）：标准输出直接返回概念的结构化JSON，没有外壳，没有
```
success
```
包装，这是方法核心概念的主要输出，可直接解析JSON获取字段。
带内存模式（
--with-memory
）：标准输出包含
```
main_stuff
```
（带有
```
json
```
、
```
markdown
```
、
```
html
```
渲染结果） +
```
working_memory
```
（所有命名内容和别名），需要将输出传递给其他方法时使用该模式。

output_file

和

graph_files

会作为副作用写入磁盘（路径出现在日志/标准错误输出中），不会出现在精简模式的标准输出中。

4a. Determine what to show

4a. 确定展示内容

In compact mode (default), the output is the concept JSON directly. Show the fields to the user:

json

{
  "clauses": [...],
  "overall_risk": "high"
}

In
--with-memory
mode, the output structure depends on the pipe architecture:

if main_stuff is non-empty (not {} or null):
    → main_stuff is the primary output (single unified result)
else:
    → working_memory.root holds the primary output (multiple named results)

Pipe Type	`main_stuff` present?	What to show
PipeLLM, PipeCompose, PipeExtract, PipeImgGen, PipeSearch	Always	`main_stuff`
PipeSequence	Always (last step)	`main_stuff`
PipeBatch	Always (list)	`main_stuff`
PipeCondition	Always	`main_stuff`
PipeParallel with `combined_output`	Yes	`main_stuff`
PipeParallel without `combined_output`	No ( `{}` )	`working_memory.root` entries

**精简模式（默认）**下，输出直接是概念JSON，向用户展示字段即可：

json

{
  "clauses": [...],
  "overall_risk": "high"
}

--with-memory
模式下，输出结构取决于pipe架构：

如果main_stuff非空（不是{}或null）：
    → main_stuff是主要输出（单一统一结果）
否则：
    → working_memory.root保存主要输出（多个命名结果）

Pipe类型	是否存在 `main_stuff` ？	展示内容
PipeLLM、PipeCompose、PipeExtract、PipeImgGen、PipeSearch	始终存在	`main_stuff`
PipeSequence	始终存在（最后一步结果）	`main_stuff`
PipeBatch	始终存在（列表）	`main_stuff`
PipeCondition	始终存在	`main_stuff`
带 `combined_output` 的PipeParallel	是	`main_stuff`
不带 `combined_output` 的PipeParallel	否（ `{}` ）	`working_memory.root` 条目

4b. Show the output content

4b. 展示输出内容

In compact mode: show the JSON fields directly. For structured concepts, format for readability.

In
--with-memory
mode when
main_stuff
is present (most pipe types):

Show
```
main_stuff.markdown
```
directly — this is the human-readable rendering. Display it as-is so the user sees the full output.
For structured concepts with fields, also show
```
main_stuff.json
```
formatted for readability.

In
--with-memory
mode when
main_stuff
is empty (PipeParallel without

combined_output

Iterate
```
working_memory.root
```
and present each named result.
For each entry, show the
```
content
```
field with its key as a label.
Example: "french_translation: Bonjour le monde" / "spanish_translation: Hola mundo"

For dry runs: Show the same output but clearly label it as mock/simulated data.

精简模式：直接展示JSON字段，结构化概念请格式化以提升可读性。

--with-memory
模式且存在
main_stuff
时（大多数pipe类型）：

直接展示
```
main_stuff.markdown
```
— 这是人类可读的渲染结果，原样展示即可让用户看到完整输出。
对于带字段的结构化概念，同时展示格式化后易读的
```
main_stuff.json
```
。

--with-memory
模式且
main_stuff
为空时（不带
combined_output
的PipeParallel）：

遍历
```
working_memory.root
```
，逐个展示每个命名结果。
每个条目以键作为标签，展示
```
content
```
字段。
示例："法语翻译：Bonjour le monde" / "西班牙语翻译：Hola mundo"

试运行场景：展示相同输出，但要明确标注为模拟/仿真数据。

4c. Output file

4c. 输出文件

The CLI automatically saves the full JSON output next to the bundle (
```
live_run.json
```
or
```
dry_run.json
```
).
The output file path appears in runtime logs (stderr), not in compact stdout.

CLI会自动将完整JSON输出保存在包目录旁（
```
live_run.json
```
或
```
dry_run.json
```
）。
输出文件路径出现在运行时日志（标准错误输出）中，不会出现在精简模式的标准输出中。

4d. Present graph files

4d. 展示图谱文件

Graph visualizations are generated by default (
```
live_run.html
```
/
```
dry_run.html
```
). Use
```
--no-graph
```
to disable.
The graph file path appears in runtime logs (stderr), not in compact stdout.

默认生成执行图谱可视化文件（
```
live_run.html
```
/
```
dry_run.html
```
），使用
```
--no-graph
```
可关闭该功能。
图谱文件路径出现在运行时日志（标准错误输出）中，不会出现在精简模式的标准输出中。

4e. Mention intermediate results

4e. 提及中间结果

If the pipeline has multiple steps, briefly note key intermediate values from
```
working_memory
```
(e.g., "The match analysis intermediate step scored 82/100").
Offer: "I can show the full working memory if you want to inspect any intermediate step."

如果流水线包含多个步骤，简要说明
```
working_memory
```
中的关键中间值（例如："匹配分析中间步骤得分为82/100"）。
提供选项："如果你想要查看任意中间步骤的详情，我可以展示完整的工作内存。"

4f. Suggest next steps

4f. 建议后续步骤

Re-run with different inputs
Adjust prompts or pipe configurations if output quality needs improvement

使用不同输入重新运行
如果输出质量需要提升，调整提示词或pipe配置

Step 5: Handle Errors

步骤5：处理错误

When encountering runtime errors, re-run with

--log-level debug

for additional context:

bash

mthds-agent --log-level debug pipelex run pipe <bundle-dir>/ --inputs data.json

For all error types and recovery strategies, see Error Handling Reference.

遇到运行时错误时，使用

--log-level debug

重新运行以获取更多上下文：

bash

mthds-agent --log-level debug pipelex run pipe <bundle-dir>/ --inputs data.json

所有错误类型和恢复策略请参考错误处理参考。

Execution Graphs

执行图谱

Execution graph visualizations are generated by default alongside the run output. Use

--no-graph

to disable.

bash

mthds-agent pipelex run pipe <bundle-dir>/

Graph files (

live_run.html

dry_run.html

) are written to disk next to the bundle. Their paths appear in runtime logs on stderr, not in compact stdout. When using

--with-memory

graph_files

is included in the returned JSON envelope.

运行输出旁默认会生成执行图谱可视化文件，使用

--no-graph

可关闭该功能。

bash

mthds-agent pipelex run pipe <bundle-dir>/

图谱文件（

live_run.html

dry_run.html

）会写入包目录旁的磁盘中，路径出现在标准错误输出的运行时日志里，不会出现在精简模式的标准输出中。使用

--with-memory

时，返回的JSON外壳中会包含

graph_files

。

Piping Methods

方法管道

The run command accepts piped JSON on stdin when

--inputs

is not provided. This enables chaining methods:

bash

mthds-agent pipelex run method extract-terms --inputs data.json --with-memory \
  | mthds-agent pipelex run method assess-risk --with-memory \
  | mthds-agent pipelex run method generate-report

When methods are installed as CLI shims, the same chain is:

bash

extract-terms --inputs data.json --with-memory \
  | assess-risk --with-memory \
  | generate-report

Use
```
--with-memory
```
on intermediate steps to pass the full working memory envelope.
The final step omits
```
--with-memory
```
to produce compact output.
```
--inputs
```
always overrides stdin when both are present.
Upstream stuff names are matched against downstream input names. Method authors should name their outputs to match the downstream's expected input names.

未提供

--inputs

时，run命令接受标准输入传入的管道JSON，可实现方法链式调用：

bash

mthds-agent pipelex run method extract-terms --inputs data.json --with-memory \
  | mthds-agent pipelex run method assess-risk --with-memory \
  | mthds-agent pipelex run method generate-report

如果方法已安装为CLI垫片，相同的链式调用写法为：

bash

extract-terms --inputs data.json --with-memory \
  | assess-risk --with-memory \
  | generate-report

中间步骤使用
```
--with-memory
```
传递完整的工作内存外壳。
最后一步省略
```
--with-memory
```
以生成精简输出。
同时存在
```
--inputs
```
和标准输入时，
```
--inputs
```
始终优先。
上游内容名称会与下游输入名称匹配，方法开发者应将输出命名为与下游预期输入名称匹配的值。

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 for .mthds syntax documentation
Native Content Types — read when interpreting pipeline outputs or preparing input JSON, to understand the attributes of each content type

错误处理 — CLI返回错误时阅读，确定恢复方案
MTHDS Agent指南 — 了解CLI命令语法或输出格式详情时阅读
MTHDS语言参考 — 了解.mthds语法文档时阅读
原生内容类型 — 解析流水线输出或准备输入JSON时阅读，了解各内容类型的属性