Ruflo for DeepSeek-TUI

Ruflo for DeepSeek-TUI 是一个小型适配器，用来把 Ruflo 接到 DeepSeek-TUI 的 MCP 后端上。

它保留 Ruflo 的工具和工作流，但把执行交给 DeepSeek，这样 DeepSeek-TUI 用户不用改上游源码，也能直接用 Ruflo 风格的 agent。

也叫： deepseek-tui mcp server · deepseek agent orchestration adapter · ruflo deepseek integration · tui-based ai agent bridge · multi-agent deepseek adapter · deepseek mcp wrapper

DeepSeek-TUI 在前，Ruflo 在中间，DeepSeek 负责执行。

一眼看懂

下面这块比流程图更适合在 GitHub 首页快速扫一眼：

这是一个 wrapper，不是完整 fork。控制层留在 Ruflo，执行层交给 DeepSeek。

你能得到什么

和原版 Ruflo 的区别

快速开始

安装并启动：

export DEEPSEEK_API_KEY=<your-deepseek-api-key>
npx -y ruflo-deepseek-tui-adapter

或者全局安装：

npm install -g ruflo-deepseek-tui-adapter

最小配置：

{
  "servers": {
    "ruflo": {
      "command": "npx",
      "args": ["-y", "ruflo-deepseek-tui-adapter"],
      "env": {
        "DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}"
      },
      "enabled": true
    }
  }
}

当前 npm 包名是 [email protected]。

为什么要做这个

保留 Ruflo 的控制层，把执行层交给 DeepSeek，让 DeepSeek-TUI 用户不用 改上游源码，也能把整套流程跑起来。

最小演示

• agent_execute 走 DeepSeek Chat Completions。
• workflow_execute 里的 task 走同一条 DeepSeek 执行路径。

安装方式

大多数用户可以这样安装：

{
  "servers": {
    "ruflo": {
      "command": "npx",
      "args": ["-y", "ruflo-deepseek-tui-adapter"],
      "env": {},
      "enabled": true
    }
  }
}

或者全局安装：

npm install -g ruflo-deepseek-tui-adapter

然后让 DeepSeek-TUI 调用：

ruflo-deepseek-mcp

如果 DeepSeek-TUI 需要填写 server config，可以直接用：

{
  "servers": {
    "ruflo": {
      "command": "ruflo-deepseek-mcp",
      "args": [],
      "env": {},
      "enabled": true
    }
  }
}

这个 npm 包已经把 ruflo 作为依赖带上了，所以普通用户不需要单独安装 Ruflo。

如果你机器上已经单独装过 ruflo，这个适配器也可以正常工作。对 npm 安装 来说，默认会优先走内置依赖。

确认 npm 上的已发布版本：

npm view ruflo-deepseek-tui-adapter version

本地开发时，可以直接指向当前这个 checkout。请使用仓库克隆路径的绝对 路径：

{
  "servers": {
    "ruflo": {
      "command": "node",
      "args": ["/path/to/ruflo-deepseek-tui-adapter/bin/ruflo-deepseek-mcp.mjs"],
      "env": {
        "npm_config_update_notifier": "false"
      },
      "enabled": true
    }
  }
}

在启动 DeepSeek-TUI 之前，先在 shell 里设置 API key：

export DEEPSEEK_API_KEY=<your-deepseek-api-key>
deepseek

如果 DeepSeek-TUI 是从配置文件启动 MCP server，也要确保同一个 DEEPSEEK_API_KEY 被传进那个 server 的 env 块。

自检

运行公开发布自检：

npm run check

这个检查会验证 JSON 配置、扫描仓库里是否误提交了 sk-* 风格的 API key、 启动 wrapper MCP server，并确认 MCP tools/list 能暴露 agent_execute。

如果你只想验证 MCP 启动路径，也可以单独跑：

npm run smoke:mcp

如果你想检查这个适配器自己的稳定性，包括缺 key 提示、未支持的 workflow step 处理、以及并发状态写入，可以跑：

npm run check:stability

如果你想验证已发布包的安装流程，包括 npx 和临时全局安装，可以跑：

npm run check:install

新机器或慢网络上的冷启动 npx 可能会超过一分钟。check:install 现在使 用了更长的 MCP 探测超时，如果还不够，可以继续通过 RUFLO_INSTALL_CHECK_TIMEOUT_MS 提高。

如果要跑真实的 DeepSeek 压测，并且严格限制 token 预算，需要显式开启：

export DEEPSEEK_API_KEY=<your-deepseek-api-key>
export RUFLO_LIVE_TESTS=1
export RUFLO_LIVE_TEST_MAX_TOKENS=300000
npm run check:live-load

如果要把一个小规模的 executionMode=tools 并发阶段也带上，再设置：

export RUFLO_LIVE_TEST_INCLUDE_TOOLS=1

如果要延长 soak 运行时间，再加上：

export RUFLO_LIVE_TEST_SOAK_MINUTES=10

当前预期结果是：MCP server 能启动，agent_execute 能被看到，wrapper 暴露 的 agent_execute 也会带上 DeepSeek 兼容的元数据。

这个 wrapper 也会保留请求顺序。如果客户端在同一个 stdio 批次里先发 agent_spawn 再发 agent_execute，系统会先等 agent_spawn 的响应，再执 行本地 DeepSeek 调用。

原版 Ruflo 并没有提供一个统一的 swarm_execute 工具。它的设计是： swarm_* 负责 swarm 状态，agent_execute 负责 LLM 执行，workflow_execute 负责多步骤编排。这个适配器因此是修改这些既有执行路径，而不是再额外做一 个替代的 swarm 工具。

当前这个适配器支持的 workflow step 故意保持得很窄：

• task
• wait
• condition

不支持的 workflow step 类型现在会直接失败，并返回清晰的错误，不再悄悄跳 过。

工具模式执行

agent_execute 现在支持两种模式：

• executionMode: "llm"：正常的 DeepSeek 补全，这是默认模式。
• executionMode: "tools"：面向开发任务的受限项目工具循环。

工具模式会把项目范围内的工具暴露给 DeepSeek：

• list_dir
• read_file
• write_file
• append_to_file
• replace_in_file
• exec_shell

文件工具只允许访问当前项目目录。exec_shell 默认关闭，只在确实需要时才 开启：

export RUFLO_AGENT_EXECUTION_MODE=tools
export RUFLO_ALLOW_SHELL=1
export RUFLO_ALLOWED_SHELL_COMMANDS=pwd,ls,find,rg,cat,node,npm,git
deepseek

如果没有设置 RUFLO_ALLOW_SHELL=1，DeepSeek 仍然可以查看和修改文件，但 shell 命令会返回禁用错误。即使开启了 shell，命令也必须是 allowlist 里的单条命 令，不能带 shell 控制字符。

常用的执行限制参数：

export DEEPSEEK_API_TIMEOUT_MS=105000
export RUFLO_MAX_TOOL_ITERATIONS=6
export RUFLO_MAX_TOOL_CALLS_PER_TURN=3
export RUFLO_MAX_TOOL_RESULT_CHARS=24000
export RUFLO_MAX_READ_FILE_BYTES=98304

在 DeepSeek-TUI 里，做大范围仓库工作时，尽量避免 researcher -> architect -> coder 这种长串串行流水线。更好的方式是直接执 行，或者拆成几个只看少量文件、分别返回局部结果的小任务。

关于任务怎么拆、怎么查 agent 状态、怎么理解 DeepSeek-TUI 输出，可以看 使用说明。

已验证的发布范围

最近这轮公开发布验证覆盖了：

• 通过 npx -y ruflo-deepseek-tui-adapter 和 npm install -g ruflo-deepseek-tui-adapter 启动已发布包
• 真实的 DeepSeek 版 agent_execute
• 真实的 workflow_execute，包含 task、wait、condition
• executionMode=tools 的文件查看和文件修改
• workflow_pause / workflow_resume 恢复
• 10 分钟的 live soak，并发跑 agent 和 workflow

当前主要剩余风险是外部依赖行为，比如 npm 冷启动延迟、本地网络中断，或 DeepSeek API 可用性。

GitHub 发布说明

为了公开分享，这个仓库包含了：

• MIT LICENSE
• 带上游 Ruflo 归属说明的 NOTICE
• SECURITY.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• GitHub issue 和 pull request 模板
• 一个用于语法和密钥扫描的轻量 GitHub Actions 检查

GitHub 建议公开仓库至少准备 README、license、contributing 指南、行为准则和 安全策略。上游 Ruflo 也是 MIT 许可证，所以这个适配器继续沿用 MIT 许可和归 属说明。

项目文档

• 项目目的
• DeepSeek-TUI 适配计划
• agent_execute 的 DeepSeek 实现说明
• 与上游的对比
• DeepSeek-TUI 执行优化
• 使用说明
• 架构说明

安全

不要提交真实 API key、.env 文件、私有会话、本地日志或运行时数据库。请使 用环境变量和示例配置文件。