PROCESIO

PROCESIO CLI + Agent

PROCESIO 自动化平台的命令行工具和 AI Agent：可通过终端或 AI 编码助手驱动流程、表单、文档和自定义操作。

这里的所有工具都通过 PROCESIO 的公共 API 与其安装实例通信。你只需指定工作区，将凭据存储在操作系统自带的密钥存储中，然后通过终端、脚本或 AI 编码助手驱动流程、表单、文档和自定义操作。

• 此工具连接的平台，工作区所在位置：https://procesio.app
• API 和平台文档：https://docs.procesio.com
• 关于 PROCESIO：https://procesio.com

安装

需要 Python 3.11。uv 是最快捷的方式，不过普通的虚拟环境也同样适用。

git clone https://github.com/Procesio-Externals/procesio-cli.git
cd procesio-cli
uv sync

基础安装包含六个软件包。其他较重的内容都是可选扩展，只有在使用相应工具时才会安装：

uv sync --extra browser      # real-browser form testing (then: uv run playwright install chromium)
uv sync --extra excel        # reading .xlsx workbooks
uv sync --extra databases    # SQL Server / MySQL queries (pyodbc also needs an ODBC driver)
uv sync --all-extras         # everything

连接到工作区

凭据不会存放在此代码库的文件中，而是存入你计算机自带的密钥存储：Windows Credential Manager、macOS 登录 Keychain 或 Linux 桌面密钥环，名称均为 agents-and-tools:procesio:<secret>。

PROCESIO 支持两种身份验证方式，二者并不等同。将其中一种存储为具名配置：

# Your user account. Carries everything that account can do.
python scripts/run-tool.py procesio add-credential --name account --type userpass     --username [email protected] --make-default

# An API key, scoped to one workspace.
python scripts/run-tool.py procesio add-credential --name qa --type apikey     --workspace-id <workspace-guid>

python scripts/run-tool.py procesio check-auth

省略 --password、--key 或 --value 时，系统会在不回显的情况下提示输入，因此密钥不会进入 shell 历史记录或进程列表。添加 --environment <Client>-<ENV> 可将配置绑定到特定安装实例。

该使用哪一种

	用户名和密码	API 密钥
可访问范围	该账户可访问的所有内容，包括跨工作区内容	一个工作区
是否需要工作区 GUID	否	是，只能使用该工作区自己的 GUID
适用场景	日常构建、任何涉及多个工作区的操作	CI、固定到单个环境的脚本、共享有限访问权限

访问范围由平台强制执行，而非由此工具控制。工作区范围的密钥会发送三个标头：密钥名称、密钥值和 workspaceid。如果不发送该标头，请求会返回 401；如果发送的是其他工作区的 GUID，请求也会返回 401。因此，API 密钥配置必须存储其 workspace_id 才能通过身份验证。运行 python scripts/run-tool.py procesio list-workspaces 可获取 GUID。

在选择前，值得了解一个实际影响：用户配置可以访问 API 密钥无法访问的端点。例如，列出主工作区的子工作区时，API 密钥会返回 401，而用户账户会返回 200。构建期间优先使用用户账户；只有在确实要将内容固定到单个工作区时，才使用密钥。

在无头机器上，没有可写入的操作系统密钥环。请明确选择一种存储方式：

export AAT_CREDS_BACKEND=encrypted-file
export AAT_SECRETS_PASSPHRASE='...'      # or you will be prompted on a terminal
python scripts/set-credential.py procesio username

AAT_CREDS_BACKEND=file 和 =env 会读取主机或集群已管理的密钥（例如挂载的 Kubernetes Secret，或单个 JSON 数据块），并且按设计只读，因此容器绝不会假装拥有它所读取的存储。

首批命令

python scripts/list-tools.py                       # what is installed, and is it ready
python scripts/run-tool.py procesio --help         # every action, with its arguments
python scripts/run-tool.py procesio list-processes
python scripts/run-tool.py procesio run-process --id <process-id> --payload '{}'

每个工具都会在 stdout 上恰好输出一个 JSON 对象，不输出其他内容，因此可以直接将其传递给 jq 或其他脚本。进度信息和警告会输出到 stderr。失败时会输出 {"error": {"code", "message", "details"}}，并以非零状态码退出。

在 AI 助手中使用

此仓库的设计目标是便于发现，而非需要记忆；因此，即使助手之前从未见过它，也能使用它。

• CLAUDE.md 包含自动生成的能力路由表：一张精简映射表，将“用户提出的需求”对应到完成该需求的确切命令。它通过 python scripts/build-router.py 根据清单重新生成，因此不会与代码脱节。
• tools/procesio/SKILL.md 是该工具的完整手册，也根据清单自动生成。助手会读取它，而不是猜测 --help 输出。
• python scripts/list-tools.py 会以 JSON 返回相同的信息，包括缺少哪些凭据，让助手可以区分“尚未安装”和“尚未配置”。

将助手指向仓库根目录，然后让它运行 scripts/run-tool.py 即可。无需其他操作。

或者将其作为插件安装到 Claude Code

只需一条命令，Claude Code 就会同时加载这些工具、MCP 服务和 Agent Skills。无需克隆仓库，也无需将路径写入配置文件。

/plugin marketplace add Procesio-Externals/procesio-cli
/plugin install procesio@procesio-cli

该插件位于 plugin/ 文件夹中，包含 MCP 服务配置、四个技能和一个图标。它通过 uvx 启动此软件包在 PyPI 上的准确版本，因此机器上必须安装 uv；其他依赖都会在首次运行时自动解析。使用下方的 add-credential 进行身份验证；没有克隆仓库时，请通过 uvx --from procesio-cli procesio add-credential ... 运行。

安装内容的版本是固定的。 插件在 plugin/ 中附带一个小型运行时项目：pyproject.toml 指定一个 procesio-cli 版本，uv.lock 则将它和每个依赖项固定为带哈希的确切版本；服务以 uvx procesio-cli==<that release> 启动。遵循锁定文件进行安装，就会准确安装为此版本锁定的内容，而不是当天 PyPI 上的最新版本。克隆仓库后也可以使用 constraints.txt 和 build-constraints.txt 达到相同效果；这两个文件会将每个软件包固定为带预构建 wheel 的版本，适用于 Python 3.11 至 3.14，以及 Windows、Linux（x86-64 和 ARM）和 Apple Silicon。Intel Mac 不在支持范围内：cryptography 已不再为其发布 wheel，因此在这些设备上安装需要 Rust 工具链。

在启用了 Smart App Control 的 Windows 上。 Windows 11 可能会拒绝加载无法确认发布者身份的 Python 文件，并为每个文件显示“此应用的部分内容已被阻止”。uv 为自身下载的 Python 构建未经过签名，因此插件会先让 uv 使用已安装的 Python（在其环境中设置 UV_PYTHON_PREFERENCE=system，且版本不低于 3.11），仅在没有已安装版本时才使用 uv 自行构建的版本。如果看到这些通知，请从 python.org 安装 Python 3.11 或更高版本（例如 winget install Python.Python.3.12）；该版本的文件带有签名。然后重启 Claude Code。请勿忽略这些通知：如果被拒绝的文件是 Python 的网络模块，任何工具调用都无法连接到 PROCESIO。

你可以检查收到的工具列表。 MCP 服务发布的工具按版本固定，server.json 会在 _meta > io.modelcontextprotocol.registry/publisher-provided > com.procesio/toolsDigest 下记录其摘要。MCP Registry 中的版本一经发布，该文件便无法更改。对 tools/list 调用返回的 tools 数组进行哈希，并进行比较：

import hashlib, json
raw = json.dumps(tools, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
print("sha256:" + hashlib.sha256(raw.encode("utf-8")).hexdigest())

如果不匹配，说明该服务提供的内容与此版本发布的内容不一致。服务还会在 server/discover 中报告其摘要，但只能将其视为标签：服务无法为自身背书。

或通过 MCP 连接，完全不需要 shell

webplatform/aat_mcp/ 中有两个 MCP 服务，基于相同底层架构，分别用于不同任务。两者都通过 stdio 使用 JSON-RPC。

	procesio-mcp-chat	procesio-mcp
工具	21 个，每个操作对应一个	6 个，通用型
是否会拾取你添加的工具	不会，它是一个声明式列表	会，立即生效
用途	聊天客户端，每个工具都必须说明自己的功能	驱动整个注册表
启动方式	插件通过 .mcp.json 启动	你自己的客户端配置

可从 MCP Registry 获取，也可作为一键安装包使用。 聊天服务已列入官方 MCP Registry，名称为 io.github.Procesio-Externals/procesio-cli，每个版本都会在其 GitHub release 中附上 procesio-mcp-<version>.mcpb。在 Claude Desktop 中打开该文件即可安装；宿主会使用 uv 获取 Python 依赖。两者均由基于标签的 release 工作流生成，该工作流会填入安装包的哈希值并发布 server.json，因此无需手动编辑注册表中的任何内容。

精心整理的工具集按你正在构建的内容分组——流程、表单、连接器——其中没有任何工具会接受调用方提供的操作，因此列表中的每个工具都清晰易懂，无论是阅读它的人，还是在其中进行选择的模型。其内容在 webplatform/aat_mcp/chat_surface.yaml 中声明，CI 会检查其中列出的每个操作是否仍然存在，以及是否仍使用所声明的参数。

如果你需要覆盖范围而非短列表，可以选择通用工具集。它通过 6 个工具而不是每个操作各设一个工具，提供对整个注册表的访问：

工具	功能
capabilities	列出工具、Agent 和技能，或查看某项能力的完整参数架构
run_tool	使用结构化 JSON 参数运行工具
run_agent	运行 Agent
run_tool_confirmed, run_agent_confirmed	执行相同操作，包括不可逆操作
get_skill	获取技能的 markdown

由于它会读取注册表，你添加到 tools/procesio/ 旁边的工具会立即出现在你的助手中，并附带其参数架构，而且你无需为它编写任何集成代码。

将 MCP 客户端指向该服务，并使用此代码库中 Python 的绝对路径：

{
  "mcpServers": {
    "procesio": {
      "command": "/abs/path/to/procesio-cli/.venv/bin/python",
      "args": ["/abs/path/to/procesio-cli/webplatform/aat_mcp/server.py"]
    }
  }
}

在 Windows 上，解释器路径为 .venv\Scripts\python.exe。不同客户端使用的键名有所不同（Claude Desktop 和 Cursor 使用 mcpServers，opencode 使用 "type": "local" 的 mcp），但命令和参数在所有客户端中都相同。容器还可以使用 HTTP 传输：python webplatform/aat_mcp/http_server.py --host 0.0.0.0 --port 8901 --token <secret>，每个请求都必须携带 Authorization: Bearer <secret>。没有令牌时，不要将其绑定到 loopback 以外的地址。

关于安全门。 如果可逆性检查判定某项操作不可逆，run_tool 就会拒绝执行，并返回 approval_required，指出应使用 *_confirmed 路径。MCP 客户端会将这些操作标记为需要询问，因此每项副作用都须经人批准，模型无法通过选择普通工具绕过安全门。请了解这项检查的工作原理：它会匹配操作名称和参数中的英文动词。如果操作名称中没有它认识的动词，结果就会被判定为可逆；因此，没有警告并不代表有保证。应将其视为防范明显错误的护栏，而不是沙箱；发现遗漏时，请将动词添加到 agents/_lib/reversibility.py。对于无头运行，即使是经确认的操作也必须拒绝时，请设置 AAT_MCP_DENY_IRREVERSIBLE。

不那么显而易见的规则

开始构建之前，请阅读 tools/procesio/PROCESIO-USAGE-GUIDE.md。它 汇总了那些在你了解之前看起来像是失败的平台行为，而且它们有一个共同特点：调用成功了，状态显示已完成，没有任何日志，但你要求执行的操作并未发生。没有错误可供搜索，所以你会查错地方。

列举几个，方便你判断是否值得花时间了解：Node 中的 <%N%> 会将值直接粘贴到源代码中，而不是绑定该值，因此字符串会变成减法；Python 操作只返回脚本 PRINTS 的内容，因此赋值会返回空值；而绑定到类型化变量的空表单控件，会在屏幕上毫无提示的情况下导致启动失败。

本指南由工具自身的说明生成，包含规则和链接，推理则保留在说明中。每条信息只保留一份。

Agent

除了原始 API 工具，还有一个构建与测试 Agent，它传授的是方法而非机制：如何正确构建流程、如何通过实时运行验证流程，以及如何识别他人流程中的问题。

python scripts/run-agent.py procesio guidance          # the playbook and best practices
python scripts/run-agent.py procesio checklist         # the self-test discipline
python scripts/run-agent.py procesio verify --process-id <id>
python scripts/run-agent.py procesio audit --process-id <id>

verify 值得接入 CI：它会验证流程，将设计器显示的内容与运行时行为进行比较，启动流程并读取实例状态。

改用浏览器进行设置

如果你不想在设置时使用终端，可以使用本地控制台：

python dashboard/serve.py

它仅绑定到回环地址，并打开一个页面，列出实时注册表中的所有工具、Agent 和技能。在那里，你可以将凭据直接存入操作系统凭据存储区（不会写入任何文件），编辑经过架构验证的配置，查看哪些工具已就绪、哪些工具缺少密钥，并运行工具来检查其是否正常工作。你输入的任何内容都不会离开你的设备。

根据 API 文档构建连接器

自定义操作是该平台的主要扩展点：流程通过它调用 PROCESIO 尚未支持的 API。connector-builder 会将 API 文档转换为已编译的自定义操作，因此，从第三方 API 到流程可调用的功能，整个过程是构建操作，而不是编写 C# 项目。

构建器是一项托管服务，位于 connector-builder.procesio.app。任何人都可以在那里创建账户；你不需要先向我们申请任何东西。开始之前，有两点需要了解：

• 请使用你自己的 LLM 密钥。 构建流水线由模型驱动，使用的是你的服务商账户，而不是我们的账户。你可以在构建器中设置一次，也可以从此处设置。
• 你可以使用 acb_ API 密钥进行身份验证，也可以使用账户的电子邮件地址和密码进行身份验证。 API 密钥长期有效，最适合脚本使用；登录则会生成 JWT。

python scripts/set-credential.py connector-builder api-key      # acb_...
# or: set-credential.py connector-builder username / password

python scripts/run-tool.py connector-builder set-llm-key --provider anthropic --api-key sk-ant-...
python scripts/run-tool.py connector-builder create-build --api-url <docs-url>     --user-requirements "what the connector should do"

之后，Agent 会引导你完成整个流程，无需你记住各个阶段：

python scripts/run-agent.py connector-builder next-step --build-id <id>

它会回答构建器的澄清问题、批准计划、生成并编译，最后将 .nupkg 交给你，以便上传到你的工作区。

测试刚构建的表单

构建表单只是工作的一半。Agent 的操作手册对另一半的要求十分明确：只有实时测试过每个选项卡、每个控件和每个事件，并确认运行时诊断没有问题，表单才算完成。截图无法显示 JS 错误、启动失败和闪烁。

python scripts/run-tool.py web save-session --name mine --url https://forms.procesio.app
python scripts/run-tool.py web run --session mine --url <form-url> --steps @steps.json

结果中包含一个 diagnostics 区块，其中有控制台输出、页面错误、失败的请求和错误响应。任何页面错误、任何控制台错误，或表单自身调用出现任何 4xx 或 5xx 错误，都意味着工作尚未完成。

此处包含的内容

七个工具、两个 Agent、两项技能，以及两个既非工具也非 Agent 的组件。注册表是所有内容的权威来源：python scripts/list-tools.py 会列出已安装的内容、每个工具公开的操作数量，以及仍缺少哪些凭据。下方的数量均来自该列表。

工具

使用 python scripts/run-tool.py <tool> <action> [options] 运行任意工具。必须指定操作；--help 会列出工具支持的操作。

工具	操作数	功能
procesio	442	平台 API：流程、表单、文档、自定义操作、环境、凭据、计划。
connector-builder	55	将 API 文档转换为已编译的 PROCESIO 自定义操作。自定义操作是平台的主要扩展点，因此这是将第三方 API 接入流程可调用功能的最快途径。
mysql	9	查询 SQL 操作所连接的 MySQL 数据库，查看流程实际写入的内容。
sqlserver	9	SQL Server 的同类工具。
web	9	操作真实浏览器：渲染、点击、填写、截图、读取运行时诊断信息。
xlsx	3	在流程之外读取工作簿。PROCESIO 的 Node 允许列表未包含 xlsx 库。
framework-map	2	将所有已安装内容呈现为双语页面：python scripts/run-tool.py framework-map build。

Agent

Agent 承载的是方法，而非机制。使用 python scripts/run-agent.py <agent> <action> 运行。

Agent	操作数	功能
procesio	5	构建和测试：操作手册、自测清单、针对实时流程的验证关卡，以及用于审查低效和稳健性问题的静态审计。
connector-builder	4	端到端驱动连接器循环：收集、规划、生成、编译，并根据反馈改进。

技能

AI 助手会根据描述自行加载知识；无需运行。python scripts/get-skill.py <name> --content 会打印技能内容。

技能	内容
procesio-platform-advisor	平台知识：功能、用例、可行性评估、实施实践。
sql-server-optimizer	审查流程运行的 T-SQL。将流程变量内联到 SQL 文本中既容易导致注入，也属于错误的操作配置；此技能会发现这类问题。

两个非工具组件

dashboard/ 是设置控制台，通过 python dashboard/serve.py 启动。它不在注册表中，也不会通过 run-tool.py 运行。

webplatform/aat_mcp/ 是 MCP 服务，由 MCP 客户端启动，而非由你启动。请参阅上文对应章节。

目录结构

tools/procesio/      the API client, DTOs, flow model, layout engine, handlers
agents/procesio/     the build-and-test agent and its doctrine
tools/_lib/          credentials, JSON I/O contract, manifest loading
skills/              knowledge your assistant loads on its own
dashboard/           the local setup console
scripts/             run-tool, run-agent, list-tools, set-credential, build-router
registry.py          manifest discovery; nothing has a hardcoded tool list

工具是一个目录，包含 tool.yaml 清单、入口点和 README。清单就是契约：注册表读取清单，其他所有内容则读取注册表。如果你在 tools/procesio/ 旁边添加自己的工具，它就会出现在 list-tools.py 和路由器中，无需在其他任何地方注册。

贡献

请参阅 CONTRIBUTING.md，了解如何提交问题或拉取请求，以及本仓库构建方式所带来的两条规则：不要移动文件，也不要提交 .procesio 导出文件。简而言之：本仓库由内部单体仓库生成，因此合并的更改会被复制回上游，并在下一次发布时同步回来。作为贡献者，你不会看到这个过程，但这解释了为什么这里的提交会成批出现。

如果发现安全问题，请不要提交问题。请参阅 SECURITY.md。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。