orbit-runtime

PromptaFlow

简体中文 | English

PromptaFlow 把一个目标变成持久、可检查的 Agent 工作流。描述你想完成的工作，让 Agent 生成静态 Workflow DSL，检查并发布，然后通过已安装的 Agent CLI 或当前对话执行它。

功能

• 根据自然语言要求生成、修改和复用工作流。
• 先校验静态 Workflow DSL，再由可信编译器编译成 LangGraph，不直接执行 Agent 生成的程序。
• 在已注册的 Agent CLI 上运行步骤，支持分支、条件、重试、审批和其他人工中断。
• 持久保存工作流版本、运行进度、控制台输出和生成的 Artifact，随时可以检查。
• 通过浏览器工作台、HTTP API、MCP 工具和五张 MCP App 卡片使用同一套工作流。
• 按 Workspace 隔离执行状态，同时在本机共享已发布的工作流库和可复用源码模板。

架构与实现

固定在 127.0.0.1:8848 的本地 Hub 是统一入口。它选择 Workspace，并把 MCP、API 和 UI 流量路由到该 Workspace 的 Control Runtime；Control Runtime 持有图状态、权限和 作为唯一操作依据的 allowed_commands[]。每个 Runtime 通过带鉴权的 Execution Worker 运行 Agent CLI 等可信 Handler。工作流定义编译为 LangGraph，持久状态保存在 ~/.promptaflow/projects/。

Agent App / 浏览器 / API
           │
           ▼
 Hub :8848（MCP Gateway）
           │
           ▼
 Workspace Control Runtime ──► Execution Workers ──► Agent CLI / Handler
           │
           └── LangGraph 状态、运行记录与 Artifact

安装

PromptaFlow 需要 Python 3.10 或更高版本，以及 uv。

通过 PyPI 安装

推荐把最新稳定版 CLI 安装到独立环境：

uv tool install promptaflow
paf --version
paf serve --project-root /你的项目绝对路径

安装预发布版本时，需要显式允许预发布版本：

uv tool install --prerelease allow promptaflow

也可以使用 pip 安装到当前 Python 环境：

python -m pip install promptaflow
# 安装预发布版本：
python -m pip install --pre promptaflow

PyPI 包提供 Runtime 以及 paf/promptaflow 命令，但不会安装 Agent App 集成或 MCP App 卡片；需要这些功能时，请继续按照下方对应宿主的文档安装。

使用提示词安装

把下面这句话发给受支持的 Agent App。Agent 会读取仓库里持续维护的文档，并为当前 App 选择正确的安装方式：

请为当前 App 安装这个仓库中的 PromptaFlow：https://github.com/TNJ2026/promptaflow

如果仓库已经 clone 到本地，请先在 Agent App 中打开该 checkout，再使用：

请从当前本地仓库为这个 App 安装或配置 PromptaFlow。不要重新 clone 或下载 Release；请阅读当前 checkout 中对应宿主的文档，保留本地修改，并在需要我亲自重启 App 或 Profile 之前停止并提醒我。

如果该 checkout 不是当前工作区，请把“当前本地仓库”替换为它的绝对路径。

各 App 的详细文档：

• Codex app
• WorkBuddy
• DeepSeek Harness

从源码运行

git clone https://github.com/TNJ2026/promptaflow.git
cd promptaflow
uv sync --extra dev
uv run paf serve

统一的 serve 命令会复用或启动 Hub、注册当前 Workspace，并等待受管 Runtime 就绪。 打开 http://127.0.0.1:8848/ui 可以查看正在运行的 Workspace。

Windows 可直接从 PowerShell、CMD 或资源管理器使用原生启动器，而且无需修改 PowerShell 执行策略：

start-promptaflow.cmd
restart-promptaflow.cmd
stop-promptaflow.cmd

需要启动其他 Workspace 时传入路径：

start-promptaflow.cmd "D:\Develop\your-project"

MCP App 卡片

PromptaFlow 提供五张紧凑的 MCP App 视图。在支持 MCP Apps 的 App 中，调用对应工具时， 卡片会显示在对话旁边。下面的提示词可以直接用自然语言说出，Agent 会把它们映射到工具。

Workspace

• 提示词：打开 PromptaFlow。
• **功能：**在同一张卡中打开目标、工作流、历史记录和 Agents，并显示当前或最近的目标。

Workflows

• 提示词：显示我的 PromptaFlow 工作流。
• **功能：**列出已发布的工作流；选择后查看流程图和定义，并可新建目标、修改或删除。

Workflow generation

• 提示词：创建一个工作流：拆解并总结文章，然后生成一份简洁的演示文稿。
• **功能：**启动 Agent 编写流程，显示原始要求、生成进度和最终工作流。

Goal execution

• 提示词：使用文章转演示文稿工作流处理这篇文章。
• **功能：**启动目标并跟踪每个步骤、需要的人工输入、执行状态和最终结果。

Goals

• 提示词：显示我最近的 PromptaFlow 目标。
• **功能：**列出最近的目标运行及其当前状态，并可进入单次运行详情。

工具映射、卡片行为和缓存刷新方式见卡片文档。

运行目标

1. 打开 目标。
2. 选择已发布的工作流，或者描述一个工作流并让 Agent 创建。
3. 输入目标并启动。
4. 在 Workspace 中跟踪步骤，或在 历史记录 中检查已完成的运行。

通过 MCP 使用时，主要工具是 list_workflows、generate_workflow、start_run、 inspect_run 和 cancel_run。客户端必须使用 Runtime 当前返回的 allowed_commands[]， 不得自行构造写操作 URL。

委托给当前对话执行

Agent 步骤通常交给工作流指定的 CLI。当系统没有安装 CLI，或希望当前 App 直接完成工作时， 可以用 execution_mode="current_app" 启动。PromptaFlow 不改变工作流结构，而是把每个 Agent 步骤排队交给发起运行的对话，并把实际执行图随运行保存。该模式异步执行，支持并行分支， 也支持从 checkpoint 安全恢复。

有哪几种触发方式

只能显式指定。没有 CLI 开关，界面上也没有切换项，更不会因为缺少 CLI 而自动降级—— 运行以哪种模式启动，就一直是哪种模式。

Agent 步骤指定了你未安装的 CLI 的工作流，默认会被目录过滤掉。为这个模式挑工作流时请用 ready_only=false 列出——缺 CLI 正是这个模式要抹平的事情。inspect_workflow_definition 也接受 execution_mode，可以在启动前先看它在这个模式下编译成什么样。

提示词

以该模式启动一次运行：

用 PromptaFlow 执行：<目标原文>。Agent 步骤都由你在当前对话里完成，不要调用 CLI。

用工作流 workflow:<id> 执行目标：<目标原文>，委托给当前对话执行。

还不确定有没有合适的工作流时，先挑：

列出可以完全在当前对话里跑完的 PromptaFlow 工作流，包括那些我没装 CLI 的。

跟进一次已经委托出来的运行：

继续你正在替我执行的 PromptaFlow 运行——领取下一个步骤，做完并汇报产出。

对话通过委托工具驱动整个运行：list_delegations 查看排队的工作，claim_delegation 领取一个步骤，长时间执行期间用 checkpoint_delegation 和 renew_delegation， complete_delegation 交回结果。领取后未完成的步骤由 reconcile_delegation 回收。

CLI 快速参考

安装 promptaflow 会在 PATH 上放两个指向同一命令的名字:promptaflow——装的是什么就能敲 什么;以及 paf,下面所有示例用的都是它。

paf serve
paf serve --project-root /absolute/path/to/project
paf hub register /absolute/path/to/project --no-agent-project-access
paf --version
paf runtimes --json
paf mcp
paf mcp --project-root /absolute/path/to/project --agent-project-access
paf run list
paf run inspect <run_id>
paf workflow validate <file> --catalog <catalog.json>
paf workflow publish <file> --catalog <catalog.json> --expected-version <n>

开发

uv sync --extra dev
.venv/bin/python -m unittest discover -s tests
node --test tests/ui/client_modules.test.mjs

构建 Python 包和插件包：

uv build
RELEASE_VERSION=X.Y.Z # 替换为本次发布版本，例如 X.Y.Z-alpha。
python scripts/build-marketplace-release.py \
  --version "$RELEASE_VERSION" \
  --output "dist/promptaflow-marketplace-${RELEASE_VERSION}.zip" \
  --plugin-output "dist/promptaflow-plugin-${RELEASE_VERSION}.zip"

推送 vX.Y.Z 或 vX.Y.Z-alpha 这样的完整 SemVer 标签后，会执行跨平台 Release workflow，并上传 GitHub 分发产物。PyPI 发布只在手动运行 workflow 时按需启用；普通标签发布仍仅发布到 GitHub。