Phlow MCP Server

Phlow

本地、有界的规划器 → 编码器 → 审查器工作流，配备真实文件工具和由宿主强制执行的验证关卡。Ollama 是默认后端。CLI、终端 UI 和 MCP 服务共用一个安全运行时；均不使用旧版不受限制的 shell 或自动加载插件路径。

Flow 可以独立运行，也可以与 Rose 双向协作： Rose 通过 MCP stdio 调用 Flow；Flow 则通过私有 Neovim 套接字调用 Rose 的原生编辑器工具。

开始使用

要求：Python 3.11+、uv，以及已安装支持工具的模型的 Ollama。Flow 的安全本地文件 I/O 要求使用 POSIX；主要目标平台为 Linux 和 macOS。

在此代码库检出目录中：

uv venv .venv
uv pip install --python .venv/bin/python -e '.[editor,dev]'

# In a separate terminal, if not already running:
ollama serve
ollama pull qwen2.5-coder:7b

# No model request or command execution; this also works without Ollama running:
.venv/bin/flow status --workspace /absolute/path/to/project

editor 附加项会安装可选的 pynvim。dev 会安装 pytest、Ruff 和 wheel 构建器。基础 CLI/TUI 运行时无需附加项。依赖应安装在项目环境中，而非全局 Python 安装中。

批准检查，然后运行

创建一个经运维人员审核的 TOML 文件，例如 flow-operator.toml。 工作区值必须放在根目录，位于任何 TOML 表头之前。

workspace_dir = "/absolute/path/to/project"

[ollama]
base_url = "http://127.0.0.1:11434"
model = "qwen2.5-coder:7b"
timeout = 120 # seconds

[models]
planner = "qwen2.5-coder:7b"
coder = "qwen2.5-coder:7b"
reviewer = "qwen2.5-coder:7b"

[agent]
max_iterations = 6      # model turns per role invocation
max_cycles = 2          # coder → verification → reviewer cycles
max_tool_calls = 64     # total across the entire run
max_context_chars = 100000

[checks.tests]
cmd = [".venv/bin/python", "-m", "pytest", "-q"]
timeout = 60000         # milliseconds, as in Rose
required = true
kind = "test"
filetypes = ["python"]

[checks.lint]
cmd = [".venv/bin/ruff", "check", "."]
timeout = 30000
required = true
kind = "lint"
filetypes = ["python"]

这些可执行文件必须存在于目标项目的环境中；Flow 不会安装项目依赖，也不会替你选择命令。对于此 Flow 代码库，自带的 config.toml 提供了自身的测试和 lint 检查。

.venv/bin/flow check --config /absolute/path/to/flow-operator.toml --trusted
.venv/bin/flow run --config /absolute/path/to/flow-operator.toml --trusted \
  "Fix the failing parser tests and explain the changes"
.venv/bin/flow status --workspace /absolute/path/to/project
.venv/bin/flow tui --config /absolute/path/to/flow-operator.toml --trusted

run、check 和 status 会输出一个 JSON 对象。退出代码：结果为 ok 时为 0，失败或未验证时为 1，配置或用法错误时为 2，会话中断时为 130。常用标志可放在命令之前或之后。--workspace 会在运行时/工具构建之前覆盖配置；--model 会覆盖所有角色。不带子命令时，flow 会启动 TUI。

TUI 命令：/help、/status、/check [name]、/tools、/models、 /model <installed-model>、/build <request>、/clear、/quit。按 Ctrl-D 退出。 自然语言任务和 /build 使用相同的已验证运行时。每个任务的各角色上下文彼此隔离且均为全新上下文。旧版 /plugins、/evolve、/memory 和 /feedback 明确不可用，不会被暗中接入不安全的辅助工具。

“已验证”的含义

仅当满足以下条件时，一次运行才会标记为 verified: true：

1. 规划器／编码器在各自预算内完成任务。
2. 至少运行一项必需的指定检查，且所有必需检查均通过。
3. 通过 Flow 修改的每个源文件都通过了相关静态分析。
4. 独立的只读审核器返回结构化批准。
5. 在验证／审核期间，已编辑文件未发生变化，且已附加的编辑器缓冲区均未处于未保存状态。

静态分析证据指明确配置的必需检查，其 kind = "lint"、"typecheck" 或 "diagnostics"，并且 filetypes 匹配；或者已完成的原生 Rose 代码检查器返回 status="ok", verified=true。kind="test"、"build" 和 "check" 本身无法证明覆盖了静态语言分析。使用语言名称（"python"）、扩展名（".py"），或仅在检查确实覆盖你所编辑的所有语言时使用明确的 "*"。未知源文件扩展名可以使用其扩展名或后缀作为覆盖键。.md、.json 和 .toml 等文档／数据扩展名仍须通过指定的门禁，但不需要源语言代码检查器。

所有必需检查都会运行：filetypes 描述覆盖范围，绝不会悄悄跳过必需命令。可选检查会报告，但不能替代必需门禁。检查使用与语言无关的精确 argv：Rust、Go、TypeScript、C、Nix 或其他语言均可使用相同机制。不会推断并下载 npx，也不会自动安装包管理器。

缺少可执行文件／检查、超时、审核器输出无效、缺少静态分析覆盖范围以及预算耗尽，均不视为成功。失败的检查和审核问题会进入下一轮有次数限制的修复周期。报告会保留 checks、verification.coverage、verification_history、变更文件、角色／模型／轮次数以及工具调用 ID／错误。缓存的 LSP 诊断为空仅表示一个快照，并不代表验证通过；即使真实代码检查器独立验证了其配置范围，缺少 LSP 仍会明确标记为 unavailable。实际诊断错误或过期结果会否决原生覆盖范围。

这些证据仅适用于已配置检查的范围，并不能证明所有行为、所有语言或整个应用都正确。

信任与安全

• 默认模式为只读。--trusted 允许编辑项目并运行明确配置的命名检查。它不会批准新选出的模型命令。
• --config FILE 明确批准加载该操作员文件。 工作区中的 config.toml/.flow.toml 永远不会自动加载，即使使用 --trusted 也不例外。 只有 $XDG_CONFIG_HOME/flow/config.toml（默认为 ~/.config/flow/config.toml） 会作为用户配置自动加载。
• 不支持由模型控制的 shell、Python/Bash 代码执行、可执行文件参数、 当前工作目录、环境覆盖、删除工具、插件、Lua 或 Ex 命令。 命名检查可以调用解释器，但其完整 argv由操作员配置固定， 并在运行前创建快照。
• 文件工具要求使用相对路径。拒绝父目录遍历、绝对路径/Windows 风格 路径、.git、符号链接、多重链接文件和根目录外路径。写入是原子操作、 有大小限制、相对于文件描述符执行且不跟随链接。检测到根目录被替换时， 会将其视为过期。无法通过模型文件工具编辑操作员配置。
• 文件读写限制为 256 KiB。目录列表有数量上限，且排除生成目录。 工具输出和模型响应的大小均有上限。
• Ollama 默认 URL 指向环回地址。禁用 HTTP 重定向和环境代理。 非环回端点需要显式设置 ollama.allow_remote=true； 不存在云端回退、API 密钥查找或自动外部搜索。
• 受信任项目的测试/构建/代码检查工具会执行代码，并可像你的用户一样访问操作系统、网络和文件。 命名命令可以运行项目配置、插件或钩子。这不是操作系统沙箱： 请审查项目和确切的检查命令，对不受信任的项目使用容器/虚拟机， 切勿以提升的权限运行 Flow。同一用户下并发运行的恶意进程不在 安全保障范围内。

旧版可执行工厂现在会安全地拒绝执行。以前的应用生成器和编排器名称现在要求显式传入 Runtime； 其原始写入/文本转 shell 路径已移除。捆绑的提示词/配置文件安装在 flow/skills 中， 并作为软件包资源读取，绝不会从项目的 skills/ 目录隐式读取。

Rose 集成

使用相同的绝对工作区和信任配置 Rose 的原生入口点：

require('rose').setup({
  workspace = '/absolute/path/to/project',
  trusted = true,
  ollama = { base_url = 'http://127.0.0.1:11434', model = 'qwen2.5-coder:7b' },
  flow = {
    cmd = { '/absolute/path/to/flow/.venv/bin/flow', 'serve',
            '--config', '/absolute/path/to/flow-operator.toml' },
    bridge = true,
    timeout = 300000, -- milliseconds; budget for the complete bounded run
  },
})

Rose 会附加工作区/信任标志，并启动/传递一个私有套接字用于反向桥接。手动调用的接口相同：

flow serve --workspace /absolute/root --trusted \
  --config /absolute/operator.toml --nvim /private/directory/nvim.sock \
  --editor-timeout 120

必须明确提供套接字，并确保它仅限同一用户访问且为私有：在 POSIX 系统上，使用权限为 0700 的父目录，或确保套接字无法被群组/其他用户访问。不接受 TCP。 Neovim 套接字会向其他同一用户的客户端授予任意代码执行权限；请妥善保护。Flow 本身只会发送固定表达式 return require('rose.tools').schemas() 和 return require('rose.tools').call(...)，并将名称/参数作为参数传入。

编辑器架构会动态发现，并筛选为 editor_context、 editor_diagnostics、editor_symbols、editor_references、editor_lint、 editor_check、editor_scip 和 editor_debug。调试启动/探测仍需手动执行：Agent 只能看到 editor_debug 状态。规划器/审阅器仅接收只读工具，不会获得检查/代码检查或写入工具。

为确保缓冲区安全，反向桥接还会将调用限制为固定的 file_read 和 file_write。Flow 会先验证路径、信任、角色、大小和受保护的配置，确认 Rose 解析出的工作区一致，然后使用 Rose 的缓冲区感知 I/O。未保存/只读缓冲区不会被覆盖；已加载缓冲区会与磁盘写入同步。桥接不可用/不匹配时，不会回退到不安全的磁盘写入。命名检查会拒绝未保存的缓冲区。 Rose 的编辑器上下文新鲜度 API v1 是必需的：Flow 会检查全局脏缓冲区列表，并在检查和审阅期间比较已加载/已观察到的工作区快照，包括非当前缓冲区。缺少新鲜度字段时会采取失败关闭策略。

在附加之前，会先在主线程导入 pynvim（pynvim 会在导入时记录信号所属线程）；连接创建、请求和关闭均由同一个工作线程负责。编辑器请求超时默认为 120 秒，可配置范围为 0.1–660 秒。模型和检查超时使用不同的单位。SCIP 支持由 Rose 提供已解码的 JSON，而非原始 protobuf 解码。 不会公开反向 flow_run 调用。

MCP 线协议契约

每行一个 UTF-8 JSON-RPC 2.0 对象；不使用 Content-Length 分帧。 协议版本为 2025-11-25；也接受兼容日期 2025-06-18 和 2025-03-26。 在执行 tools/list 或 tools/call 之前，先发送 initialize，然后发送 notifications/initialized。ping 始终可用。

工具	参数
flow_status	{}
flow_run	{"task":"..."}
flow_check	{} 或 {"name":"configured-name"}

工具响应包含 content=[{type:"text",text:"<JSON report>"}]、 structuredContent=report，并会对非 ok 结果设置 isError。MCP 工具列表有意仅包含这三个工具。标准输出仅用于协议；标准错误用于诊断。对于有效的 JSON-RPC ID，解析/方法/参数错误会保留该 ID。帧过大时会在返回错误后关闭会话。

该服务器有意采用顺序处理，以适应设备运行。运行中的请求不会协同处理 notifications/cancelled。如需取消，请终止 Flow 会话（RoseStop）：SIGTERM/KeyboardInterrupt 会触发活动检查的进程组清理并关闭编辑器客户端；之后可重新连接。已保存的编辑不会回滚。空闲会话遇到 EOF 时会关闭；繁忙请求会在其时限内完成，除非监督进程将其终止。此标准输入/输出传输需要客户端监督进程，不能将标准输出重定向到 systemd 日志并假装成网络守护进程。

开发与验证

uv pip install --python .venv/bin/python -e '.[editor,dev]'
.venv/bin/pytest -q
.venv/bin/ruff check flow tests
.venv/bin/python -m compileall -q flow
.venv/bin/python -m build --wheel --no-isolation

# Include real headless editor tests when Neovim is not on PATH:
NVIM=/absolute/path/to/nvim .venv/bin/pytest -q

测试使用确定性的虚假后端、本地虚假 HTTP Ollama 端点、真实的 CLI/MCP 子进程，以及可选的真实无头 Neovim。测试涵盖角色分离、修复上限、验证、工具 ID/错误、信任/配置/路径回归、超时/进程清理、缓冲区桥接，以及在检出目录之外加载的 wheel 资源。如果没有可用的 Neovim 可执行文件，Neovim 专项测试会报告跳过。 不包含实时 Ollama 推理/GPU 质量测试。真实模型可能会选择较差的编辑方案，或耗尽预算；请检查生成的报告和差异。

保留了 Nix 表达式，但未在此环境中构建。

许可证

本项目采用 Apache License, Version 2.0 许可。