Steps
用条件、转换、脚本和一个最终输出组成线性流程。在独立检查器中配置每一步,并对比测试前后的值。
用可视化步骤或代码构建工作流,选择它支持的剪贴板类型,然后直接在 Pasteon 内置操作旁运行。
Workflow 是保存的处理配方;只有当前剪贴板项目匹配你选择的输入条件时,它的 Action 才会出现在 Pasteon 中。
用条件、转换、脚本和一个最终输出组成线性流程。在独立检查器中配置每一步,并对比测试前后的值。
使用指定解释器、参数、工作目录和超时运行内联代码或外部脚本。单一结果用 Simple,运行时选择用 Script Filter。
这个示例会清理复制文本的空白、统一命名格式,并把结果返回到你正在使用的 App。
打开“设置 → Workflows”,新增工作流,填写名称和图标,再选择它应该在哪些剪贴板类型下出现。
添加清理文本、转换命名格式等步骤,并拖拽排序。Output 固定在末尾,让流程始终可预测。
测试不会真正复制、粘贴或打开内容。你可以查看每一步的前后值、耗时和校验状态。
工作流会直接显示在内置 Primary Actions 之后。点击或按 Enter 粘贴结果;按住 Command 则只复制。
步骤从上到下执行。条件决定 Action 何时可用,转换更新当前值,一个输出决定 Pasteon 如何处理结果。
Pasteon 通过 stdin 发送版本化 JSON,并从 stdout 读取协议 JSON。日志写入 stderr;超时、取消和输出限制让运行过程保持可控。
当一个 Action 只需要生成一份文本、文件或 URL 结果时,使用 Simple 模式。
{
"version": 1,
"result": {
"type": "text",
"value": "Ready to paste"
}
}Filter 阶段只返回轻量候选信息。用户选择某一项后,Pasteon 才运行 execute。
{
"version": 1,
"actions": [
{
"id": "swift",
"title": "Generate Swift Model",
"argument": { "language": "swift" }
}
]
}脚本收到 phase “filter”,最多返回 20 个候选 Action。
Pasteon 展示标题、说明、图标和 JSON 参数,不提前计算最终结果。
被选中的 actionId 和 argument 回传脚本,只计算当前这一项。
stdout 只能输出协议 JSON,诊断信息请写入 stderr。内联代码与外部脚本使用同一套输入输出契约。
编写 Code Workflow 或生成 .pasteon-workflow 文件时可查阅这里。字段名和限制与当前 Pasteon Runner 完全一致。
这些字段决定 Workflow 在什么内容下出现,以及 Pasteon 如何启动脚本。
| 字段 | 类型 | 是否必需 | 作用 |
|---|---|---|---|
id | UUID | 是 | Workflow 的稳定标识,用于更新、Filter 会话、导入冲突判断和 workflowID 输入。 |
defaultIntroducedVersion | Integer | null | 仅内置 | 该默认 Workflow 首次加入的 Catalog 版本,升级时只安装新增项,不恢复用户已删除的旧默认项。 |
name | String | 是 | 设置页和 Pasteon Action 列表中显示的名称。 |
nameLocalizationKey | String | null | 仅内置 | 内置 Workflow 名称的本地化 key;用户编辑名称后会清除。 |
summary | String | 否 | Action 旁的简短说明,不参与脚本执行。 |
summaryLocalizationKey | String | null | 仅内置 | 内置 Workflow 摘要的可选本地化 key。 |
symbolName | SF Symbol 名称 | 是 | Workflow Action 使用的图标;候选项图标无效时也会回退到它。 |
isEnabled | Boolean | 是 | 关闭后配置仍会保存,但不会生成 Action。 |
requiresTrustConfirmation | Boolean | null | 导入项 | 标记导入代码尚未信任。Pasteon 会将它设为 true 并关闭 Workflow,直到用户确认。 |
sortOrder | Number | 是 | 决定 Workflow Action 在内置 Primary Actions 后的排序。 |
mode | simple | scriptFilter | 是 | Simple 直接执行;Script Filter 先执行 filter,用户选择候选项后再 execute。 |
supportedTypes | PasteType[] | 是 | 允许显示 Action 的类型:text、markdown、html、json、url、color、date、timestamp、fileURL、imageURL、videoURL、image 或 appObject。 |
editorMode | steps | code | 否 | 选择线性可视化编辑器或代码编辑器。旧文件没有该字段时按 Code 处理。 |
script.source | inline | external | Code | Inline 把代码保存在 Workflow 内;External 引用磁盘上的脚本。 |
script.code | String | Inline | 内联脚本正文,每次运行时会写入临时脚本文件。 |
script.codeResource | 资源名称 | null | 仅内置 | 内置默认 Workflow 的 Bundle 脚本资源;导出用户 Workflow 时会写入解析后的内联代码。 |
script.scriptPath | 文件路径 | External | 外部脚本路径,支持展开 ~。文件不存在时保留配置,但不显示 Action。 |
script.interpreterPath | 可执行文件路径 | Inline | 运行脚本的解释器,例如 /bin/zsh 或 which node 的结果。外部脚本本身可执行时可留空。 |
script.arguments | String[] | 否 | 在脚本路径前传给解释器的参数数组,不会拼接成 Shell 字符串。 |
script.workingDirectory | 目录路径 | 否 | 进程当前目录。留空时,外部脚本使用脚本所在目录,内联脚本使用临时输入目录。 |
script.filterTimeout | 秒 | Filter | Filter 最长运行时间,限制为 1–120 秒,默认 5 秒。 |
script.executeTimeout | 秒 | 是 | Execute 最长运行时间,限制为 1–120 秒,默认 15 秒。 |
steps | WorkflowStep[] | null | Steps | 按顺序保存的线性步骤。Steps 模式要求 Simple,并且只能有一个最终输出。OCR 支持图片输入;PNG File 和 Open in Finder 有更严格的输入类型限制。 |
variables | WorkflowVariableDefinition[] | null | No | Reusable Text or Secret values available to Steps templates and Code Workflow stdin. Names must be unique within the Workflow. |
只有用户真正执行 Workflow 后,Pasteon 才会构造该对象。二进制剪贴板数据会写成临时文件,不会嵌入 JSON。
| 字段 | 类型 | 是否必需 | 作用 |
|---|---|---|---|
version | Integer | 是 | Workflow 协议版本,当前唯一支持的值是 1。 |
workflowID | UUID String | 是 | 当前 Workflow 的稳定标识。 |
phase | filter | execute | 是 | 告诉同一个脚本当前运行哪个阶段。Simple 只会收到 execute。 |
paste.id | UUID String | 是 | 当前选中 Pasteon 历史项的标识。 |
paste.type | PasteType | 是 | Pasteon 派生的内容类型,用于可见性判断和脚本逻辑。 |
paste.text | String | null | 否 | 可文本化时提供当前内容。文件和二进制图片可能没有文本。 |
paste.sourceAppBundleIdentifier | String | null | 否 | 该内容最初复制自哪个 App 的 Bundle ID。 |
paste.representations | Representation[] | 是 | 全部可用 Pasteboard representation。文本可内联,二进制数据通过路径提供。 |
targetApp.bundleIdentifier | String | null | 否 | 将接收执行结果的前台 App Bundle ID。 |
targetApp.name | String | null | 否 | 前台目标 App 的本地化显示名称。 |
directories.input | 目录路径 | 是 | 包含内联脚本和二进制输入的本次临时目录,运行结束后删除。 |
directories.output | 目录路径 | 是 | 脚本应在这里创建需要返回的文件;超过 24 小时的输出目录会被清理。 |
actionID | String | null | Filter 后 Execute | 用户从 Filter 结果中选中的候选 ID;Filter 阶段和 Simple 模式为 null。 |
argument | JSON value | null | Filter 后 Execute | 被选中候选项携带的参数,原样回传,让 execute 只计算该结果。 |
argument | JSON value | null | Execute after Filter | The selected candidate’s argument, returned unchanged so execute can compute only that choice. |
{
"version": 1,
"workflowID": "5F604A89-7AC2-45D9-B48C-BB540B60CA67",
"phase": "execute",
"paste": {
"id": "D0A4E45A-61F6-4DAF-BC1E-4E17A23AA5C0",
"type": "json",
"text": "{\"name\":\"Pasteon\"}",
"sourceAppBundleIdentifier": "com.apple.Safari",
"representations": [
{
"type": "public.utf8-plain-text",
"value": "{\"name\":\"Pasteon\"}",
"path": null,
"fileName": null,
"fileSize": 18,
"temporary": false
}
]
},
"targetApp": {
"bundleIdentifier": "com.apple.dt.Xcode",
"name": "Xcode"
},
"directories": {
"input": "/tmp/Pasteon/WorkflowInputs/RUN_ID",
"output": "~/Library/Application Support/Pasteon/WorkflowOutputs/RUN_ID"
},
"variables": {
"API_BASE_URL": "https://api.example.com",
"API_TOKEN": "••••••••"
},
"actionID": "swift",
"argument": { "language": "swift" }
}每个示例都会读取完整 stdin、访问 paste.text 和 PREFIX Workflow 变量,然后只向 stdout 写入一个合法的 Simple Workflow 结果。
使用 Node.js 标准库读取文件描述符 0。
/opt/homebrew/bin/nodeconst fs = require("node:fs");
const payload = JSON.parse(fs.readFileSync(0, "utf8"));
const text = payload.paste?.text ?? "";
const prefix = payload.variables?.PREFIX ?? "";
process.stdout.write(JSON.stringify({
version: 1,
result: { type: "text", value: prefix + text }
}));使用 json.load 读取 sys.stdin,并通过 json.dump 写入 sys.stdout。
/opt/homebrew/bin/python3import json
import sys
payload = json.load(sys.stdin)
text = payload.get("paste", {}).get("text") or ""
prefix = payload.get("variables", {}).get("PREFIX", "")
json.dump({
"version": 1,
"result": {"type": "text", "value": prefix + text}
}, sys.stdout)读取 $stdin、使用 JSON 解析,并确保 stdout 只有协议 JSON。
/opt/homebrew/bin/rubyrequire "json"
payload = JSON.parse($stdin.read)
text = payload.dig("paste", "text") || ""
prefix = payload.dig("variables", "PREFIX") || ""
$stdout.write(JSON.generate({
version: 1,
result: { type: "text", value: prefix + text }
}))读取 STDIN 流,并使用 PHP 内置 JSON 函数。
/opt/homebrew/bin/php<?php
$payload = json_decode(stream_get_contents(STDIN), true);
$text = $payload["paste"]["text"] ?? "";
$prefix = $payload["variables"]["PREFIX"] ?? "";
echo json_encode([
"version" => 1,
"result" => ["type" => "text", "value" => $prefix . $text]
]);通过 FileHandle.standardInput 读取,并使用 Foundation 解析。
/usr/bin/swiftimport Foundation
let data = FileHandle.standardInput.readDataToEndOfFile()
let payload = try JSONSerialization.jsonObject(with: data) as? [String: Any]
let paste = payload?["paste"] as? [String: Any]
let variables = payload?["variables"] as? [String: String]
let text = paste?["text"] as? String ?? ""
let prefix = variables?["PREFIX"] ?? ""
let response: [String: Any] = [
"version": 1,
"result": ["type": "text", "value": prefix + text]
]
let output = try JSONSerialization.data(withJSONObject: response)
FileHandle.standardOutput.write(output)Zsh 读取原始内容,JSON 的解析和编码由 jq 完成。
/bin/zsh#!/bin/zsh
set -euo pipefail
payload="$(cat)"
text="$(printf '%s' "$payload" | jq -r '.paste.text // ""')"
prefix="$(printf '%s' "$payload" | jq -r '.variables.PREFIX // ""')"
jq -n --arg value "$prefix$text" '{
version: 1,
result: {type: "text", value: $value}
}'Pasteon 不内置语言运行时或 jq。请将 interpreterPath 设置为当前 Mac 上真实存在的可执行文件。Apple 芯片和 Intel Mac 的 Homebrew 路径可能不同,可使用 “which node”“which python3” 等命令确认路径。
每个 Step 都有标识、类型、启用状态和一份共用配置;只有当前 kind 使用的配置字段会参与执行。
| 字段 | 类型 | 是否必需 | 作用 |
|---|---|---|---|
steps[].id | UUID | 是 | 用于选择、拖拽排序、校验和逐步测试结果的稳定标识。 |
steps[].kind | WorkflowStepKind | 是 | 选择条件、转换、脚本或输出操作。 |
steps[].isEnabled | Boolean | 是 | 关闭的非输出步骤会跳过;最终 Output 不能关闭。 |
configuration.pattern | String | 匹配 / 替换 | 用于判断或替换的文本、App 标识片段或正则表达式。 |
configuration.replacement | String | 替换 | 替换内容;Regex 模式遵循 NSRegularExpression 的 replacement template 规则。 |
configuration.matchMode | contains | equals | startsWith | endsWith | regularExpression | 匹配 / 替换 | 决定 pattern 的比较方式;Replace 只有选择 regularExpression 时才按正则替换。 |
configuration.isCaseSensitive | Boolean | 匹配 / 替换 | 为 false 时,文本比较和正则替换忽略大小写。 |
configuration.trimMode | whitespaceAndNewlines | whitespace | newlines | Trim | 决定从文本两端移除哪类字符。 |
configuration.caseStyle | camel | pascal | snake | screamingSnake | kebab | train | dot | Change Case | 当前文本要转换成的目标命名格式。 |
configuration.template | String | Template | 包含 {{input}}、{{date}} 等支持占位符的文本模板。 |
configuration.fileName | String | Output File | 输出文件名,可使用模板变量;为安全起见会丢弃其中的目录部分。 |
configuration.script | ScriptConfiguration | Run Script | 该步骤的脚本配置;Run Script 必须返回 text,供下一个可视化步骤继续处理。 |
textCondition只有当前文本匹配 pattern 时才显示并运行。
sourceAppCondition匹配创建该剪贴板内容的来源 App Bundle ID。
targetAppCondition匹配当前前台目标 App Bundle ID。
trimText从文本两端移除指定类型的空白字符。
replaceText执行普通替换或正则替换。
changeCase把当前文本转换为配置的命名格式。
urlEncode / urlDecode对当前文本做 URL 百分号编码或解码。
jsonPretty / jsonMinify解析 JSON、排序 key,再格式化或压缩输出。
template替换文本模板中的受支持占位符。
runScript执行必须返回 text 的 Simple Code Workflow 步骤。
recognizeText使用 macOS Vision 对 Clipboard Image 或 ImageURL 输入执行 OCR,并把识别文本传给后续步骤。
outputText / outputFile / outputOpenURL返回文本、创建文本文件或打开受支持 URL。有效的 Steps Workflow 末尾只能保留一个输出。
outputPNGFile把 Clipboard Image 或 ImageURL 输入转换为 PNG 文件;使用其他输入类型会让 Workflow 无效。
outputRevealInFinder在 Finder 中显示本地 FileURL、ImageURL 或 VideoURL。测试 Workflow 时只展示路径,不打开 Finder。
每一项代表一种 Pasteboard 数据。文本读取 value;文件或物化后的二进制数据读取 path。
| 字段 | 类型 | 是否必需 | 作用 |
|---|---|---|---|
type | UTI String | 是 | Pasteboard 类型,例如 public.utf8-plain-text、public.file-url、public.png 或 public.html。 |
value | String | null | 否 | 文本类型的 UTF-8 内容,或原始文件 URL 字符串。 |
path | 文件路径 | null | 否 | 原始本地文件路径,或 Pasteon 为二进制数据生成的临时路径。 |
fileName | String | null | 否 | 该 representation 的原始文件名或安全生成的文件名。 |
fileSize | Int64 | 是 | 字节长度,优先使用已经存储的元数据。 |
temporary | Boolean | 是 | 为 true 表示该文件由 Pasteon 为本次运行写入 input 目录,不应长期保存该路径。 |
Filter 只描述可选项,不应返回最终生成内容,也不应提前执行每个候选项的实际工作。
| 字段 | 类型 | 是否必需 | 作用 |
|---|---|---|---|
version | Integer | 是 | 必须等于当前协议版本 1。 |
actions | Action[] | 是 | 不能为空。Pasteon 会校验并最多展示前 20 个候选项。 |
actions[].id | String | 是 | 候选标识,Execute 时作为 actionID 回传;去除空白后长度为 1–120。 |
actions[].title | String | 是 | 候选 Action 标题;去除空白后长度为 1–120。 |
actions[].subtitle | String | null | 否 | 候选项辅助说明,Pasteon 最多保留前 240 个字符。 |
actions[].icon | SF Symbol | null | 否 | 候选项 SF Symbol 名称;无效时回退到父 Workflow 图标。 |
actions[].argument | JSON value | null | 否 | Execute 时原样回传的不透明 JSON,可为对象、数组、字符串、数字、布尔值或 null。 |
Execute 必须只返回一个 result 对象,并且只填写该 result.type 所需的字段。
| 字段 | 类型 | 是否必需 | 作用 |
|---|---|---|---|
version | Integer | 是 | 必须等于当前协议版本 1。 |
result | Object | 是 | Pasteon 要执行的唯一最终结果。 |
result.type | text | files | openURL | revealFile | 是 | 决定校验方式及普通模式与 Command 模式的行为。 |
result.value | String | text | 非空文本;普通模式粘贴,Command 模式只复制。 |
result.paths | String[] | files | revealFile | files 使用非空路径数组,相对路径基于 output 目录且文件必须存在;revealFile 使用第一条路径作为 Finder 中定位的本地项目。 |
result.url | String | openURL | 合法的 http、https 或 mailto URL;普通模式打开,Command 模式复制。 |
revealFile behavior | 本地文件操作 | revealFile | 从 Action 执行时在 Finder 中显示第一条路径并隐藏 Pasteon;Command 模式不会把它切换为仅复制。 |
{
"version": 1,
"result": {
"type": "files",
"paths": ["GeneratedModel.swift"]
}
}Runner 不拼接 Shell 命令字符串,会流式读取两路输出,并在用户离开当前会话时终止任务。
stdout 只能包含一份协议 JSON,不能混入日志;超过上限会终止进程。
日志和诊断写入 stderr,测试和错误界面会读取它。
Filter 与 Execute 分别配置超时;到期后 Pasteon 会终止进程。
非零退出码视为失败,错误中会包含捕获的 stderr。
切换 Paste、返回 Filter、编辑或删除 Workflow、关闭窗口都会取消运行。
参数以数组传入,不会展开管道、通配符、变量或其他 Shell 语法。
应用清理时会删除超过 24 小时的 Workflow 输出目录。
脚本以当前 macOS 用户权限在本机运行,启用导入脚本前请先检查代码。
在设置中定义一次,即可在可视化 Steps 或 Code Workflow 中复用。Text 值随 Workflow 保存;Secret 值保存在 macOS 钥匙串中,导出文件不会包含密钥内容。
| 字段 | 类型 | 是否必需 | 作用 |
|---|---|---|---|
variables[].id | UUID | 是 | 稳定标识,用于将 Secret 定义关联到钥匙串中的值。复制 Workflow 时会生成新的变量 ID。 |
variables[].name | String | 是 | 区分大小写的读取名称,必须匹配 [A-Za-z_][A-Za-z0-9_]*,并在同一 Workflow 内保持唯一。 |
variables[].kind | text | secret | 是 | Text 将值保存在 Workflow 中;Secret 将值保存在 macOS 钥匙串中。 |
variables[].value | String | 仅 Text | Text 值会随 Workflow 保存和导出;Secret 定义导出时该字段始终为空字符串。 |
{
"variables": [
{
"id": "C3EEAF0E-0AD8-4A26-924C-CB867088D955",
"name": "API_BASE_URL",
"kind": "text",
"value": "https://api.example.com"
},
{
"id": "7E05B2EE-E745-4558-A267-E63B7D1E2235",
"name": "API_TOKEN",
"kind": "secret",
"value": ""
}
]
}Template 和文件名步骤会在运行时替换以下内置占位符及任意 {{variables.NAME}}。
{{input}}上一步输出的当前文本。{{sourceApp}}来源 App Bundle ID;不存在时为空字符串。{{targetApp}}前台目标 App Bundle ID;不存在时为空字符串。{{clipboardType}}当前 PasteType 原始值。{{date}}ISO 8601 格式的当前日期和时间。{{variables.NAME}}读取名称完全匹配且区分大小写的用户自定义 Text 或 Secret 变量值。除 stdin JSON 外,Code Workflow 还可以读取以下环境变量。
PASTEON_WORKFLOW_ID当前 Workflow 的 UUID。PASTEON_WORKFLOW_PHASEfilter 或 execute。PASTEON_INPUT_DIR与 directories.input 相同的路径。PASTEON_OUTPUT_DIR与 directories.output 相同的路径。导出文件是可阅读的版本化 JSON,可包含一个 Workflow 或完整 Workflow 列表。
| 字段 | 类型 | 是否必需 | 作用 |
|---|---|---|---|
version | Integer | 是 | 外层协议版本,当前导入只接受版本 1。 |
installedDefaultsVersion | Integer | null | 否 | 内部默认 Catalog 状态;用户导出时为 null,导入时不会用它启用默认项。 |
workflows | WorkflowDefinition[] | 是 | 一项或多项完整 Workflow;为兼容旧文件,也支持直接导入单个 WorkflowDefinition。 |
同一脚本处理两个阶段:Filter 返回两个轻量选项,Execute 只计算用户选择的结果。
解释器: /opt/homebrew/bin/nodeasync function main() {
let input = "";
process.stdin.setEncoding("utf8");
for await (const chunk of process.stdin) input += chunk;
const payload = JSON.parse(input);
const text = payload.paste?.text ?? "";
let response;
if (payload.phase === "filter") {
response = {
version: 1,
actions: [
{
id: "uppercase",
title: "Convert to Uppercase",
subtitle: "Uppercase the copied text",
icon: "textformat",
argument: null
},
{
id: "wrap",
title: "Wrap in Brackets",
subtitle: "Add [ and ]",
icon: "curlybraces",
argument: { prefix: "[", suffix: "]" }
}
]
};
} else {
const argument = payload.argument ?? {};
const value =
payload.actionID === "uppercase"
? text.toUpperCase()
: (argument.prefix ?? "") + text + (argument.suffix ?? "");
response = {
version: 1,
result: { type: "text", value }
};
}
process.stdout.write(JSON.stringify(response));
}
main().catch((error) => {
process.stderr.write(`${error.stack ?? error.message}\n`);
process.exit(1);
});请使用 Mac 上 “which node” 返回的路径。不要使用 console.log,它会写入 stdout;诊断信息请使用 console.error。
普通执行会立即处理结果。Command 点击或 Command + Enter 会把文本、文件和 URL 切换为仅复制;Finder 定位始终直接显示文件。
text返回生成文本、清理后的内容、模板、代码或任意字符串。
files在提供的输出目录创建文件,并把路径返回给 Pasteon。
openURL普通模式打开支持的网页或邮件链接,Command 模式复制 URL。
revealFile在 Finder 中定位返回的本地文件;测试 Workflow 时只展示路径,不打开 Finder。
Pasteon 默认启用这些工作流。你可以像处理其他 Workflow 一样检查、编辑、关闭、复制、导出或删除它们。
Script Filter.json.txt.mdopenURLScript FilterSimpleScript FilterOCR → 文本图片 → .pngrevealFileWorkflow 文件保持可读和可迁移。导入的 Workflow 默认关闭,检查并信任代码后才能启用。
不需要。Steps 模式通过线性可视化编辑器提供常用条件、文本转换、模板、脚本和输出;需要自定义行为时再使用 Code。
Simple 执行一次并返回一个结果。Script Filter 先返回轻量候选项,再在独立的 execute 阶段运行用户选择的那一项。
启用的 Workflow 会在当前剪贴板项目匹配输入类型和可视化条件时,显示在内置 Primary Actions 之后。
脚本使用你配置的解释器和工作目录在本机运行。导入的 Workflow 在你检查并启用前不会执行。
是。Pasteon Pro 支持创建、测试、导入、导出和运行自定义 Workflow。
下载 Pasteon for Mac,从可视化 Workflow 开始,只有流程真正需要时再进入脚本。