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

流程

Prerequisite: See CLI Prerequisites

前置条件：查看CLI前置条件

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>/`
目录中的特定管道	`mthds-agent pipelex run pipe <bundle-dir>/ --pipe my_pipe`
直接指定包文件	`mthds-agent pipelex run pipe bundle.mthds -L <bundle-dir>/`
从库中通过代码指定管道	`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

/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

/build

(which saves a placeholder template) or after

/inputs

with the template strategy.

如果在本次对话中已经准备好输入——通过

/inputs

（用户数据、合成数据或混合策略），或者在本次会话早期手动组装了包含真实值的

inputs.json

——则跳过获取架构和就绪检查步骤。输入已就绪，直接执行步骤3进行常规运行。

此情况适用于你刚刚编写或看到

inputs.json

被写入真实内容值的场景。不适用于

/build

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

/inputs

之后的情况。

Full check — cold start

完整检查——冷启动

/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 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 /inputs skill.

如果在本次会话中未提前准备输入就调用

/run

，则执行完整的就绪检查：

获取目标的输入架构：

bash

mthds-agent pipelex inputs 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

字段中填入实际值。对于复杂输入，使用

/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

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

返回空的

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
```
存在，且所有内容值均为真实值（无占位符，引用的文件存在）→ 执行步骤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
```
/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

并告知用户：

"此流水线的输入包含占位符值（非真实数据）。我将使用模拟输入进行空运行，以验证流水线结构。"

空运行后，为用户提供以下选项：

准备真实输入——使用
```
/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	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
模式下，输出结构取决于管道架构：

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

管道类型	是否存在main_stuff	展示内容
PipeLLM、PipeCompose、PipeExtract、PipeImgGen	始终存在	`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字段。对于结构化概念，格式化以提升可读性。

存在
main_stuff
的
--with-memory
模式（大多数管道类型）：

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

main_stuff
为空的
--with-memory
模式（不带

combined_output

的PipeParallel）：

遍历
```
working_memory.root
```
并展示每个命名结果。
对于每个条目，以其键为标签展示
```
content
```
字段。
示例："french_translation: Bonjour le monde" / "spanish_translation: 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
```
可禁用此功能。
图谱文件路径显示在运行时日志（标准错误）中，不会出现在紧凑模式的标准输出中。使用
```
--with-memory
```
时，返回的JSON信封中会包含
```
graph_files
```
。

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

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

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

时，运行命令会接受标准输入中的管道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

参考

CLI Prerequisites — read at skill start to check CLI availability
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前置条件——开始使用功能时查看，以检查CLI可用性
错误处理——当CLI返回错误时查看，以确定恢复策略
MTHDS Agent指南——查看CLI命令语法或输出格式详情
MTHDS语言参考——查看.mthds语法文档
原生内容类型——解读流水线输出或准备输入JSON时查看，以了解每种内容类型的属性