Workflows

你可以

• 点按我的工作流（管理你的活动自动化）打开列表。
• 点按从提示生成，用一句话描述一个自动化（见“AI：生成、修改和聊天”）。该卡片只在竖屏下出现。
• 在探索下，点按模板或 CI / CD。两者打开的是同一个模板标签页：CI / CD 不会筛选任何东西。

你不能做的，以及原因

• 从这里创建空白工作流：请用我的工作流上的 + 按钮。有意为之
• 在横屏下看到从提示生成（手机横过来、平板横着拿）：横屏的欢迎界面只有我的工作流、模板和 CI / CD。卡片菜单里的用 AI 修改仍然可用。尚未提供

你可以

• 搜索你的工作流：在名称、描述和标签里查找，忽略重音。
• 按最近编辑、按名称、上次运行或出错的优先排序。
• 用标签芯片筛选（全部加上你的标签，最常用的在前）。
• 用卡片上的开关开启或关闭工作流。开启一个含有不可撤销步骤的工作流时会询问一次（见“运行与查看”）。
• 点按 ▶ 图标运行主触发器为手动或定时的工作流；运行期间，对任何工作流（无论是什么启动了这次运行），该图标都会变成带进度环的 ■ 停止。
• 使用时钟图标（计划）、历史图标（运行历史）和红色垃圾桶（删除）。
• 用红色垃圾桶或卡片菜单里的删除来删除工作流。对话框会询问删除“<名称>”？（“该工作流及其计划将被删除，无法撤销。”），只有你点按删除才会真正删除；取消则保持原样。
• 长按卡片，或使用副键点击，打开它的菜单。

你不能做的，以及原因

• 在由事件或快捷方式启动的工作流的卡片上看到 ▶：这类工作流的立即运行在卡片菜单里。有意为之
• 离开界面后仍保留搜索、排序或标签筛选：筛选会隐藏内容，所以每次都会重新询问。有意为之

你可以

• 从卡片菜单打开标签，在新标签里输入并添加；在同一个对话框里移除标签。
• 按标签筛选我的工作流；芯片按使用它们的工作流数量排序。

你不能做的，以及原因

• 给一个工作流打超过 8 个标签（最多 8 个标签。）：二十个标签什么也整理不了。有意为之

你可以

• 按名称、描述、触发器或操作搜索模板；用芯片按系列筛选（全部和下面的六个系列）。
• 点按启用，得到一份可编辑的副本：它有新的 id、处于开启状态，并出现在我的工作流里；如果你已经有了，点按再添加一份。副本与模板互不共享任何东西。
• 打开预览、运行试运行，之后在编辑器里修改副本。

你不能做的，以及原因

• 在模板库里编辑模板：你编辑的是自己的副本。目录固定为 17 个模板。有意为之
• 在点启用时被问到不可撤销步骤：这个问题只会在你之后拨动某个工作流的开关时才出现。启用之前请先读需要什么。尚未提供

你可以

• 阅读触发时机、带分支的步骤树（如果成立、否则、尝试执行、如果失败）和需要什么。
• 用立即测试运行一次试运行。如果模板有必填输入，默认值会自动填好。预览会说明哪些步骤因无法模拟而被跳过，或者缺少什么，并以 n 个步骤 · n 毫秒 · 不保存 结尾。

你不能做的，以及原因

• 对声明了没有默认值的必填输入的模板做试运行：预览会显示缺少以下内容，无法试运行：并写出该输入的名称。目前 17 个模板里没有一个这样，而缺少部署服务商或 AI 密钥并不会阻止测试。有意为之

你可以

• 切换已启用：它和卡片上的是同一个开关。
• 切换可供 AI 代理使用并填写展示给 AI 的描述。开关开启且工作流含有不可撤销步骤时保存，会询问一次允许 AI 运行此工作流？（允许 AI）。
• 当一个暴露给 AI 的工作流里，shell 步骤包含 {{…}} 绑定时，请阅读安全警告：聊天代理可能通过输入把文本注入命令。

你不能做的，以及原因

• 让代理调用一个已关闭的工作流：只有同时可供 AI 代理使用且已启用的工作流才会向聊天宣告。有意为之

你可以

• 添加输入，包括名称（字母、数字和 _，不能以数字开头，且唯一）、类型（文本、长文本、数字、是 / 否、选择、JSON）、必填、默认值、选项（用逗号分隔，用于选择）、标签和描述（询问时显示，也会展示给 AI）。可以上移或下移输入，也可以移除。
• 用立即运行运行它：带有必填输入的工作流会打开运行对话框并填好默认值，所以你只需改需要改的部分。

你不能做的，以及原因

• 带着无效输入保存：名称为空、无效或重复，选择类型没有选项，或默认值不在选项里、或不是数字，都会让保存无法使用。有意为之
• 让必填输入没有默认值的工作流自己启动：定时运行、事件、快捷方式或卡片都没有人可问。编辑器会用必填但无默认值警告，调度器会记录一次失败的运行。有意为之

你可以

• 整次运行上限（秒）：留空即无上限。用完时，这次运行会像你手动停止一样被取消。
• 当某步骤失败时：停止或继续。这是每个步骤继承的默认值。写了继续的步骤保留自己的选择；但当工作流设为继续时，没有任何步骤能再要求停止。
• 当已有运行在进行时：跳过新的（默认）、排队等待（每个工作流最多 10 个在等）或取消进行中的运行。它适用于事件触发器和定时运行；手动运行和由 AI 启动的运行不受它限制。
• 保留的历史记录：保留的运行次数和保留天数。留空表示默认值（100 次运行、30 天）；你可以设置 1 到 1000 次运行和 1 到 365 天。较旧的运行会在该工作流下一次运行时被清理，而不是在你保存时。

你不能做的，以及原因

• 为被跳过新的丢弃的事件留下记录：在默认策略下，工作流正在运行时到达的事件会被直接丢弃，历史里没有任何条目，这是有意为之：否则一连串保存会让每个事件都写一行。（被队列或应用级上限拒之门外的运行，会记为已取消并附上原因。）有意为之

你可以

• 切换访问网络（HTTP 请求、AI 步骤、部署，以及 git push 或 pull）、写入文件（写入、检出和备份；读取永远不受影响）和执行终端命令（数据库备份步骤的命令也算）。
• 添加允许访问的域名：留空表示任意域名，github.com 也涵盖 api.github.com，你粘贴的内容会被清理（去掉协议、路径和端口）。
• 记住子流程的一条规则：子流程以自身权限与父流程权限的交集运行，如果两个域名列表没有任何交集，网络就是关闭的。

你不能做的，以及原因

• 把权限当作安全边界：摘要的结尾是“这不是沙箱：任何能编辑该工作流的人都能改动这些权限。”它们保护你免于粗心，而不是防范恶意的作者。有意为之
• 让域名列表限制 AI、部署或 git 步骤：该列表只覆盖 HTTP 请求步骤，摘要里也这么说。有意为之
• 从域名列表得到对 SSRF 的防护：比较的是主机名，而不是它解析到的地址，HTTP 步骤可以访问 127.0.0.1 或 10.x。有意为之

你可以

• 选择 25 种类型中的任意一种，最多添加 6 个触发器，并把其中一个提升为主触发器。
• 构建一个带类型的过滤（见下），让工作流只在你关心的事件上启动。
• 在捕获下一个事件下按捕获：编辑器会监听 60 秒，显示该类型下一个事件的真实数据，并把它保留为插入数据用的示例数据。
• 按分支过滤 git push 时（例如 main）：发出 push 的四个地方（Projects 两处、编辑器的 Git 面板和 AI 聊天）都会带上当时检出的分支，所以 push 到 main 自动部署和 push 到 main 之后跑测试会触发。

你不能做的，以及原因

• 使用项目已关闭和 AI 完成了回合：它们在下拉菜单里，但应用里没有任何地方会发出它们，所以以它们启动的工作流永远不会触发。linter 会警告（“目前应用中没有任何地方发出 PROJECT_CLOSED，因此该工作流不会被触发。”），捕获则提示“应用中还没有任何地方发出该触发器，再等也没用。”尚未提供
• 由在编辑器的 源代码管理 面板或 AI 聊天里做的提交来启动：git commit 时只对从 Projects 做的提交触发。尚未提供
• 过滤四种系统触发器（主屏快捷方式、快速设置卡片、分享到 PocketCode 的文本、分享到 PocketCode 的文件）：它们由 Android 启动，启动器只按类型选择工作流，所以过滤会被忽略。尚未提供
• 当命令是在交互式终端里输入时，从命令已完成读取真实的退出码：该事件的 exitCodeKnown 为 false。尚未提供
• 添加第七个触发器或第九个条件（最多 6 个触发器。和最多 8 个条件。）。有意为之

你可以

• 点按 + 按钮（添加步骤）打开面板：按名称、描述或输出搜索（“名称、说明或输出（stdout、url…）”），选择一个分类芯片（Shell、Git、部署、AI、数据、HTTP、文件、控制、通知、其他），并使用收藏和最近 5 次使用。每一项显示它产出什么（产出：…），并标出不可撤销、执行命令、访问网络、写入文件或无法模拟。新步骤落在你选的位置的末尾，并打开它的设置。
• 每张卡片上：排序把手、编号、标题和一行摘要、已启用 / 已停用开关（已停用的步骤会被跳过，且不算失败）、如果此步骤失败芯片、测试此步骤、铅笔（打开设置并选中该步骤）和 ⋮ 菜单。
• 菜单里有：上移、下移、复制步骤、粘贴到下方（只有剪贴板里有 PocketCode 步骤时才可用，所以你可以粘贴到另一个工作流里）、复制、备注（只在编辑器里显示）、转为子流程和删除。
• 识别固定数据：带有固定输出的步骤，其卡片上会显示示例数据。

你不能做的，以及原因

• 把步骤拖进另一个块：把手在自己的列表里每拖 48 dp 就把步骤移动一个位置；请用菜单里的上移和下移。有意为之
• 把流程画成图，或使用 N 路 switch 或自由合并：流程是一棵嵌套的树，If / Else 正好有两个分支，并行用三种策略之一合并它的分支。有意为之
• 编辑应用不认识的步骤（未知步骤，由更新的版本写入）：它会原样保留，只能移动或删除。有意为之

你可以

• 用添加条件和添加分组构建条件，用且、或和非组合，并使用分组和移除。空分组总是匹配。
• 查看条件成立或条件不成立，它是用你固定的示例数据计算的，不是用下一次运行。

你不能做的，以及原因

• 把何时放在循环、并行、try、子流程、等待或 If / Else 上：只有操作步骤才有。有意为之

你可以

• 在任何引用之后用 | 串联过滤器。
• 把某个输出固定为示例数据，让插入数据和 If / Else 可以用它来预览。

你不能做的，以及原因

• 在表达式里添加自己的函数或运行代码：13 个过滤器的列表是封闭的，没有用户函数，也没有 eval；过长的路径、过长的过滤器链，或花括号之间的文本在解析时会被拒绝。有意为之

你可以

• 循环：最多 10 000 次迭代（默认 100），同时最多 16 个；当同时进行的迭代数大于 1 时，它们分批运行。
• 并行：全部完成时会等待每个分支，只要有一个失败就失败；第一个完成时和第一个成功时会取消其余分支。
• 尝试 / 失败时：失败分支在 {{var.<name>}} 里读取错误信息；失败仍会显示在历史里。
• 子流程：把一部分只做一次，从多个工作流调用它；转为子流程会把一个步骤及其全部内容提取成一个已关闭的新工作流，并在原处留下一个子流程步骤，同时列出将会失效的引用（它们会静默解析为空值，抽取后请检查。）。

你不能做的，以及原因

• 嵌套子流程超过 5 层，或让工作流调用自己：递归的子流程会被跳过，linter 会警告。有意为之
• 循环超过 10 000 次，或同时运行超过 16 个迭代，不管字段里怎么写。有意为之

你可以

• 设置最大尝试次数（1 表示不重试）、重试间隔（文本字段：EXPONENTIAL、LINEAR 或 FIXED）、初始延迟（毫秒）、最大延迟（毫秒）和超时（毫秒）（留空表示无上限）。
• 依赖超时也会被重试：超时的步骤会被标为 TIMED_OUT，如果还有剩余尝试次数，它会像其他失败一样再次运行。
• 选择如果此步骤失败：停止（运行在此结束）、继续（继续往下，失败留在历史里）或使用工作流的设置。选了继续，该步骤仍显示红色，而整次运行仍可能以绿色结束。
• 在运行详情里查看结果：第 n 次尝试成功，或者从未成功时的尝试 n 次。

你不能做的，以及原因

• 给循环、并行或其他控制块设置重试或超时：这些字段只存在于操作步骤上。整个工作流的上限在工作流设置里。有意为之

你可以

• 点按测试此步骤：它用你固定的数据作为上下文来模拟该步骤，并显示已模拟，用时 n 毫秒：未触碰任何东西。当某个引用指向没有固定输出的步骤时，会提示以下步骤没有固定输出：…。
• 当操作无法模拟（目前只有触发部署），或你输入的值会是不可撤销的，按钮会变成真实执行此步骤。它会先询问：只运行那个步骤，工作流的其余部分不受影响，这次运行也不会存入历史。
• 把某个步骤的输出固定（以及取消固定）为示例数据，供选择器和预览使用。固定的输出保存在设备上，每个工作流最多 50 个步骤，14 天后会被丢弃。
• 点按立即测试（或按 Ctrl+Enter）对整个工作流做试运行，按屏幕上的样子，而不是上次保存的样子。它会显示测试通过或测试失败，以及 n 个步骤 · n 毫秒 · 不保存。试运行不保存运行，也不触发任何事件。

你不能做的，以及原因

• 单独测试控制流块：“只有动作步骤可以单独测试：测试分支或循环等于执行它内部的步骤。”有意为之
• 在试运行里使用密钥：它们不会被解析，步骤会被跳过，并告诉你它用了哪些密钥。有意为之
• 导出或同步固定的输出：它们留在设备上。有意为之

你可以

• 修复警告所指的问题，或者不管它：只有属于错误的那三条规则会阻止保存。
• 用跳转到步骤直接跳到对应步骤。

你不能做的，以及原因

• 带着错误保存（名称为空、没有步骤、必填参数留空）：三条错误规则针对的是会让工作流无法读取或无法保存的情况。其余的，包括权限规则，只警告而不阻止，因为想关闭网络的人通常会在删除用到网络的步骤之前先这样做。有意为之

你可以

• 在主触发器为手动或定时的工作流卡片上点按 ▶，或在任何工作流的菜单里点立即运行。如果它声明了必填输入，会先打开运行对话框（“此工作流启动前需要这些值。”），默认值已填好。
• 从卡片、菜单、历史、活动、运行详情或通知里停止它。这次运行会以已取消结束。
• 开启一个含有不可撤销步骤的工作流：会弹出标题为“此工作流包含不可撤销的操作”的对话框，列出这些步骤（第 n 步 · …），你选择仍然启用。每个工作流只问一次，并记在设备上，不同步也不导出。
• 保存一个开启了可供 AI 代理使用且含有不可撤销步骤的工作流：允许 AI 运行此工作流？（允许 AI），同样只问一次。没有这个许可，代理的工具会拒绝运行它，并告诉模型该去问谁。

你不能做的，以及原因

• 在点模板的启用、用生成器的保存并启用，或导入文件时被问到不可撤销步骤（导入的工作流是关闭的，问题要在你开启它时才出现）。尚未提供
• 在覆盖文件时得到警告：写入文件从不算作不可撤销，即使是覆盖时也一样；它的 overwritten 输出会在事后告诉你。只有 Git 的 push（或来自绑定的 Git 操作）以及带写入动词的 SQL（或来自绑定的 SQL）才算。有意为之

你可以

• 在错误信息中搜索：它会查找该次运行的信息和每个步骤的信息。
• 按状态（已完成、已失败、已取消）、日期（任意日期、今天、最近 7 天、最近 30 天）和工作流（全部工作流，包括你已经删除的工作流）筛选；清除会移除筛选。
• 加载更多会再加 50 条，可以停止一个正在进行的运行，点按某次运行即可打开它的详情。
• 用导出为 JSON 把筛选后的运行复制为 JSON：它会把文本放进剪贴板。
• 确认之后删除历史记录（“运行记录会消失，工作流本身不变。”），可以针对所有工作流，也可以只针对被筛选的那一个。

你不能做的，以及原因

• 回溯到比最近 500 次运行更早：“此页面最多显示到这里。请缩小筛选范围以查找更早的记录。”有意为之
• 把历史导出成文件：导出为 JSON 只会复制文本。尚未提供

你可以

• 查看每次运行的状态和时间、步骤数、由 … 触发，对已取消的运行还有由 … 取消；仍在进行的运行带有进行中。
• 停止本次运行，或打开某次运行查看详情。
• 还没有任何运行时会显示“暂无运行——触发此工作流以开始记录历史。”

你不能做的，以及原因

• 用文字读到每一种取消原因：应用只翻译了上一次执行仍在进行、队列已满和“应用同时运行的工作流已经过多”；其他原因（user、timeout、superseded、scope）会按原始单词显示。尚未提供

你可以

• 阅读顶部信息（状态、耗时、触发器、是谁中止的）和每个步骤：结果、耗时、第 n 次尝试成功或尝试 n 次、错误，以及可以展开和复制的 JSON 树形输出。运行结束时仍在进行的步骤显示已中断；之后已从工作流中移除的步骤显示该步骤已不在此工作流中。
• 运行期间跟随 shell 的实时输出，搜索它（搜索日志）并复制它（复制日志）。每个步骤只保留最后 500 行，丢弃了较早的行时界面会说明。
• 用 AI 分析整次运行，或在某个步骤上用 AI 分析：它会打开聊天，并带着写好的提示。
• 复制为 JSON 会复制这次运行。

你不能做的，以及原因

• 读取已经结束的运行的 shell 日志：“终端日志不会保存到历史记录，只在运行期间可见。”有意为之
• 找到系统杀掉应用时正在进行的运行：运行只在结束时写入一次，启动时不会恢复任何东西，所以被中断的运行不会留下记录。有意为之
• 看到已保存的密钥：运行写入时，值会被遮成 •••，所以数据库里也没有它们。短于 4 个字符的值无法遮盖。有意为之

你可以

• 再次运行从头运行工作流。
• 从失败的步骤重来从第一个失败的步骤开始再次运行，复用它之前各步骤的结果（复用之前的 n 个结果。）。只有当运行已结束且存在失败步骤时才会显示。
• 用这些输入运行会在运行之前再次询问输入。
• 确认之前先读一下对话框：它会说明“将按工作流当前的定义运行，而不是这次运行时的定义。”，说明工作流自那以后是否被编辑过，哪些步骤已不存在，哪些是新增的，以及从哪里继续。

你不能做的，以及原因

• 复用旧运行的输入：“那次运行的输入没有保存，因此使用声明的默认值。”它们可能是 token。有意为之
• 从嵌套在块里的步骤继续：只有第一层的步骤才能作为重启点。有意为之
• 重复一次其工作流已被你删除的运行：“工作流已不存在，无法重复这次运行。”有意为之

你可以

• 在通知栏里跟踪运行，并从那里停止它；停止按钮只作用于本应用正在进行的运行。
• 用显示通知步骤发送你自己的通知。它的 importance 决定渠道：HIGH 进入 Workflows · 提醒，其他都进静音的 Workflows 渠道。两者都遵循应用的通知设置：总开关、提醒和通知开关、Android 的通知权限以及勿扰时段。
• 点按通知：指向 pocketcode://workflows/… 的链接会打开该运行或该工作流；其他任何链接都会被丢弃，通知只会打开应用。

你不能做的，以及原因

• 在运行失败时收到自动通知：PocketCode 不会发送任何通知。如果想要，可以在尝试 / 失败时分支里添加一个显示通知步骤，或者建一个以检测到错误启动的工作流。（AI 聊天可以显示一条带试试按钮的 Workflow '…' failed 提示，但只出现在聊天里。）尚未提供
• 让每次运行都有进度通知：只有同时进行的前 5 个运行有；其余的没有它也照常运行。设备
• 在应用处于后台时指望前台服务：从 Android 12 起，系统可能会拒绝它（例如手机揣在口袋里时的定时运行）。运行会继续，只是没有那层保护，PocketCode 每 30 秒会再请求一次。Google Play

你可以

• 快捷方式：每个开启的、带有快捷方式触发器的工作流，都会作为应用图标的动态快捷方式出现（标签被截成 30 个字符）。点按它会不打开任何界面就运行该工作流，并显示工作流已启动。已被删除或关闭的工作流的固定快捷方式会如实说明。
• 卡片：把运行工作流拖进快速设置。没有工作流使用它时，显示没有工作流使用此快设卡片；有一个时直接运行它；有多个时显示选择器。
• 分享：从其他应用把文本、图片、JSON、XML、zip、PDF 或一般的二进制文件分享给运行工作流。一个标题为发送给工作流的面板会始终显示收到了什么（“分享的内容是数据，不是指令。”）以及哪个工作流会接收它；有多个时由你选一个。数据以 {{trigger.text}}、{{trigger.subject}}、{{trigger.uri}}、{{trigger.fileName}}、{{trigger.mimeType}} 的形式到达，同名的已声明输入优先。
• 如果没有任何东西在监听，你会读到“没有启用的工作流在监听它。请在工作流编辑器中添加对应的触发器。”

你不能做的，以及原因

• 用这三种方式启动必填输入没有默认值的工作流：它会显示 … 需要先填一个值，而不是盲目运行。有意为之
• 一次分享多个项目、超过 32 768 个字符的文本（会被截断并告知你），或超过 25 MB 的文件。分享的文件会被复制进 PocketCode，24 小时后删除；接受的类型列表是固定的，不是任意类型。有意为之
• 指望快捷方式的数量：由 Android 决定启动器显示几个（至少 5 个，通常是 4 或 5 个），而卡片需要你主动添加，得自己拖进去。设备
• 从其他应用直接打开 .pcwf.json：分享菜单会把文件发给分享到 PocketCode 的文件触发器，而不是导入器。请用从文件导入工作流导入。有意为之

你可以

• 在欢迎界面（竖屏）点按从提示生成，打开从提示生成工作流：写下提示词，提到触发器（push、保存、commit、错误、部署）和操作（部署、通知、备份、测试、格式化），然后按生成。
• 在卡片菜单里点按用 AI 修改，打开用 AI 修改「…」：说明你想改什么；工作流的其余部分保持不变，保存之前你会看到改了什么。
• 检查结果：预览、检查（linter 的问题）、模拟运行通过，用时 n 毫秒、模拟运行失败：…或“未测试：…您可以在编辑器中自行测试。”、对应用修复的内容显示已自动修正，以及修改时的差异（新增、删除、修改、n 个步骤未变）。
• 选择保存并启用（仅在创建时）、在编辑器中打开（检查阻止保存时的出路）或放弃。以这种方式创建的工作流保存后是开启的；修改则保留工作流的 id、开关状态和创建日期。

你不能做的，以及原因

• 指望 AI 生成的所有东西都做试运行：只有应用判断安全时才会运行，因为试运行会执行步骤。当某个步骤无法模拟、等待合计超过 10 秒、等待的是某个事件，或无法检查子流程时，它会显示未测试并给出原因。有意为之
• 在没有 AI 服务商的情况下得到由模型写成的工作流：没设密钥时，应用退回到关键词匹配，并说明“未使用模型：未配置 AI 密钥，因此由关键词匹配生成。”需要网络
• 保存被 linter 拒绝的生成结果：“保存前请先修复：此工作流尚未就绪。”有意为之

你可以

• 问代理你 push 时会运行哪些工作流，或者昨晚的备份为什么失败：它用 workflow__list、workflow__get 和 workflow__runs 读取，这些是免费的。
• 让它用 workflow__run 运行其中一个：它会按工作流声明的输入校验这些输入，并遵守你授予的不可撤销步骤许可（允许 AI）。
• 在 Pro 下，让它创建或修改一个：workflow__create 和 workflow__update。三个会写入的工具要经过代理的确认面板。

你不能做的，以及原因

• 在 Free 上从聊天创建或修改工作流：模型会收到一个拒绝，并被要求告知你，你会看到一条提示（“… 需要 PocketCode Pro，因此该操作未执行。”）和一个升级按钮。该套餐功能名为通过聊天创建工作流。Pro
• 让代理改动工作流的重试、超时、何时条件或保留策略：AI 无法设置它们，而更新会保留步骤的 id、权限、标签和保留策略。有意为之
• 把可供 AI 代理使用当作访问控制：它只决定工作流是否作为它自己的工具被宣告。workflow__run 可以按名称运行任何处于开启状态的工作流。有意为之