StuFlow

StuFlow 是一个基于 Open Multi-Agent 和 DeepSeek 的 AI 编码助手，提供命令行、交互式 REPL 和 Claude Code 风格 Ink TUI 三种使用方式。当前实现将配置、Provider、Agent 模板、核心任务执行、CLI 和 TUI 拆分为独立模块，便于后续扩展更多模型或替换编排层。

功能

• 多 Agent 编排：默认创建 architect、developer、reviewer 三个 StuFlow Agent，并通过 Open Multi-Agent 的内部 coordinator 进行任务规划与调度。
• 轻量路由：普通聊天、帮助和澄清问题走单 assistant，不启动多 Agent DAG；编码、审查、分析、规划和计划模式仍走 Open Multi-Agent DAG。
• DeepSeek 独立 Provider 模块：集中管理模型、Base URL 和思考参数映射。
• Vercel AI SDK 辅助入口：项目导出了 DeepSeek generate/stream helper；当前 CLI/TUI 主执行路径仍通过 Open Multi-Agent 运行。
• Agent 工作区：默认在 STUFLOW_WORKSPACE 真实项目目录中读写，便于用 git diff 审查；同时创建 STUFLOW_WORKSPACE/.agent-workspace/ 作为临时草稿目录。
• CLI 与 TUI：支持一次性任务、计划模式、交互式 REPL 和 Claude Code 风格全屏 TUI。
• 多 Agent TUI：使用终端原生 scrollback、Agent 执行日志块、轻量状态栏和紧凑输入 composer，并降低运行中重绘频率以减少滚动回看时的跳动。
• 智能上下文：在 .stuflow/ 保存会话、摘要、项目记忆、代码索引和上下文缓存，并支持 STUFLOW.md / AGENTS.md 项目规则注入。

安装

环境要求：

• Node.js 与 npm。
• Windows 用户如果启用 developer Agent 的 bash 工具，需要安装 Git Bash、MSYS2 或 WSL，并确保 bash 可在 PATH 中访问。

npm install

复制环境变量示例并填写 DeepSeek API Key：

cp .env.example .env

Windows PowerShell 可使用：

Copy-Item .env.example .env

配置

变量	默认值	说明
DEEPSEEK_API_KEY	无	实际执行模型调用时必需，不能使用 .env.example 中的占位值。REPL 可先启动，但执行任务会失败。
STUFLOW_PROVIDER	deepseek	当前运行路径仅支持 deepseek。
DEEPSEEK_BASE_URL	https://api.deepseek.com	可选，用于代理或兼容网关。
STUFLOW_MODEL	deepseek-v4-pro	DeepSeek 或兼容网关实际支持的模型名称。
STUFLOW_THINKING	high	可选 off、low、high、max。
STUFLOW_WORKSPACE	当前目录	StuFlow 的真实项目工作目录。默认 Agent 会直接在该目录读写。
STUFLOW_WORKSPACE_MODE	project	可选 project 或 scratch。project 直接面向真实项目；scratch 仅在 .agent-workspace/ 中工作。
STUFLOW_SECURITY_MODE	full	可选 safe、balanced、full。safe 禁用 bash、file_write、file_edit；balanced 禁用 bash；full 保留完整工具能力。日常建议先用 balanced。
STUFLOW_VERBOSE	true	影响传统 CLI 详细输出；TUI 使用自己的事件渲染。

使用

开发模式：

npm run dev -- "修复登录接口的类型错误"

构建后运行：

npm run build
npm start -- "实现一个文件扫描工具"

计划模式只生成执行计划：

npm run dev -- --plan "重构配置加载模块"

启动 TUI：

npm run dev:tui

TUI 采用接近 Claude Code 的终端交互方式：历史内容通过终端原生 scrollback 自然向上推，当前输入区保持在底部；助手输出按实际产生输出的 Agent 分块展示，便于查看协作过程；运行状态压缩为底部单行状态栏，输入区使用紧凑 composer。

默认 StuFlow Agent 包括 architect、developer、reviewer；coordinator 是 Open Multi-Agent 的内部协调器。根据任务复杂度、OMA 调度策略和事件输出，实际执行时不保证每轮都显示所有角色。

TUI 默认折叠多 Agent 的详细输出，只在主界面展示当前运行状态和必要提示，避免 architect/developer/reviewer 的长日志把对话刷乱。可用 /agents 查看后台输出摘要，或 /agent architect、/agent developer、/agent reviewer 打开单个 Agent 输出；/agent off 关闭详情展开。普通 chat 路由的 Assistant 输出仍直接显示在主面板。

为了避免简单输入触发过多子 Agent，StuFlow 会先进行轻量任务路由：

• 普通聊天、模型/帮助询问、澄清类输入：使用单 assistant 直接回答。
• 编码、审查、项目分析、规划、完善类输入：进入 Open Multi-Agent DAG。
• /plan 或 --plan：进入只生成计划的 DAG 路径。

每轮结束后，StuFlow 会在 Git 项目中显示轻量 worktree 摘要，包括变更文件数、已跟踪/未跟踪数量和 diff stat 提示；可使用 /diff 预览已跟踪文件 diff，或直接运行 git diff && git status --short 审查本轮改动。

示例输出结构：

● Design · Architect
  分析目标、约束和实现路径...

● Implement · Developer
  执行代码修改并汇报关键变更...

● Review + Verify · Reviewer
  复核风险、遗漏和验证结果...

常用命令：

/help, /h             显示帮助
/quit, /q             退出
/clear, /cls          清屏
/plan <目标>           仅预览任务计划
/workspace [路径]      显示/切换工作目录
/workspace-mode <project|scratch> 切换真实项目/草稿工作区
/model [名称]          显示/切换模型
/thinking [级别]       显示/设置思考深度 (off/low/high/max)
/security [模式]       显示/设置安全模式 (safe/balanced/full)
/agents               TUI 中查看后台 Agent 输出摘要
/agent <name|off>     TUI 中展开单个 Agent 输出或关闭展开
/sessions              列出最近 StuFlow 会话
/resume <ID>           恢复会话摘要并注入后续任务
/fork <ID>             从已有会话摘要创建分支
/context [查询]         预览本轮智能上下文；`/context on|off` 开关
/index [查询]           构建轻量代码索引并可选搜索
/diff                  预览当前 Git diff（已跟踪文件）
/memory                查看项目记忆
/memory add <内容>      显式添加项目记忆
/memory remove <ID>    删除项目记忆
/rules                 查看 `STUFLOW.md` / `AGENTS.md` 规则来源
/init-context          创建 `STUFLOW.md` 项目规则模板

TUI 快捷键：

↑/↓                  切换输入历史
终端滚动条            回看历史消息
Ctrl+L               清屏
Ctrl+C               空闲时退出，运行中软中断
Esc                  运行中软中断

安全模型与风险

当前 StuFlow 仍是本地 AI 编码助手原型，不应把 .agent-workspace/ 视为强安全沙箱。STUFLOW_SECURITY_MODE=full 时 developer Agent 拥有 file_write、file_edit 和 bash 等高权限工具；这些工具可能读写本机文件、执行 shell 命令，并访问当前进程环境变量。

安全模式：

• safe：只读模式，禁用 bash、file_write、file_edit。
• balanced：允许文件读写和编辑，禁用 bash，适合多数日常编码任务。
• full：保留完整工具能力，适合可信项目和需要运行命令的任务。

当前版本不提供：

• 工具级 Allow/Deny 确认。
• 强制路径隔离或容器沙箱。
• 网络隔离。
• 自动 diff 审批。
• 自动回滚。

请只在可信目录、可信提示和可接受风险的环境中运行。不要在包含敏感凭据或重要未备份文件的目录中直接运行。

工作区语义

STUFLOW_WORKSPACE 是 StuFlow 的真实项目工作目录。默认 STUFLOW_WORKSPACE_MODE=project，Agent 的当前工作目录就是该项目根目录，因此编码任务会直接产生可通过 git diff 审查的源码变更。

运行时仍会创建：

STUFLOW_WORKSPACE/.agent-workspace/

.agent-workspace/ 现在只作为草稿区或实验区。只有当 STUFLOW_WORKSPACE_MODE=scratch，或在 REPL/TUI 中执行 /workspace-mode scratch 后，Agent 才会把 .agent-workspace/ 作为当前工作目录；该模式不会默认修改真实项目源码。

StuFlow 还会按需创建运行态目录：

STUFLOW_WORKSPACE/.stuflow/
  sessions/   会话元数据与 JSONL transcript
  memory/     用户显式保存的项目记忆
  index/      轻量代码上下文索引
  cache/      最近一次 context pack 预览或注入缓存

.stuflow/ 不等同于 Agent 工作区，也不是代码修改目录。它可能包含用户输入、模型输出、项目摘要或路径信息，默认已加入 .gitignore，不建议提交到版本库。

智能上下文

StuFlow 会在 REPL/TUI 运行任务时自动创建或沿用当前会话，并在每轮任务完成后更新会话摘要。下一轮任务会以受限的 context pack 注入上下文，而不是直接重放完整 transcript。

默认 context pack 的来源包括：

1. STUFLOW.md 项目规则。
2. AGENTS.md 兼容规则。
3. 当前会话摘要。
4. 用户通过 /memory add <内容> 显式保存的项目记忆。
5. /index 生成的轻量代码索引命中。

常见工作流：

/init-context          创建可版本化的 STUFLOW.md 项目规则模板
/index                 扫描项目并生成轻量 code map
/context 登录          预览“登录”相关任务会注入哪些上下文
/memory add 测试命令使用 npm run check 和 npm run build
/sessions              查看历史会话
/resume <ID>           恢复某个会话摘要
/fork <ID>             从某个会话摘要创建分支探索

注意：项目记忆必须通过 /memory add 显式写入；StuFlow 不会静默把模型推断写入长期记忆。上下文包如果与实际代码冲突，以实际代码为准。

当前限制

• .agent-workspace/ 不是强制安全沙箱。
• scratch 模式不会自动复制真实项目源码到 .agent-workspace/，也不会自动把草稿变更应用回真实项目。
• 默认 project 模式会直接读写真实项目文件；请用 git 审查变更。
• full 安全模式下 developer Agent 拥有 shell 和文件写入能力；如需降低风险，请使用 /security balanced 或 /security safe。
• Ctrl+C / Esc 在运行中只会停止 TUI 继续接收并显示本轮输出；它不保证取消底层 LLM 请求、工具调用或 shell 子进程。
• 后台任务真正结束前，文件写入或命令执行仍可能继续；不建议立即启动另一个会写同一目录的任务。
• TUI/REPL 会注入会话摘要和 context pack，但不会把上一轮完整屏幕内容自动作为下一轮模型上下文。
• 一次性 CLI 默认每次运行创建独立会话；如需连续体验，请使用 REPL/TUI 或通过 API 传入 context.sessionId。
• coordinator 可见性取决于 Open Multi-Agent 的事件和调度路径。
• 结果摘要包含 Git 变更数量、tracked/untracked 数量和 diff stat 提示；/diff 可预览已跟踪文件 diff，但会按长度截断。
• 当前项目未配置 ESLint/Prettier；npm run quality 使用类型检查和测试作为基础质量门。

无参数启动时会进入 REPL，可输入 /help 查看命令，/quit 退出。

项目结构

src/
  agents/       Agent 模板与类型
  cli/          CLI banner、命令解析、输出和 REPL
  config/       环境变量加载与配置校验
  context/      会话、项目规则、记忆、代码索引和 context pack
  core/         沙箱、任务分类、目标构造、OMA 工厂和 run-task
  providers/    DeepSeek 与 Vercel AI SDK 适配层
  tui/          Ink TUI 状态、事件适配器、组件和 hooks
  agent.ts      兼容旧 API 的门面
  cli.ts        CLI 入口
  cli-tui.ts    TUI 入口
  index.ts      包导出入口

验证

npm run check
npm test
npm run quality
npm run build
node dist/cli.js --help

当前项目尚未配置 ESLint/Prettier；npm run quality 会运行类型检查和测试，未来可接入更严格的 lint/format。