SAYACODE

把编程 Agent 的工作过程，带到你看得见、管得住的本机工作台。

从一次提问到多 Agent 协作：对话、计划、工具、审批与代码交付，集中在一个浏览器页面。

快速开始 · 探索工作台 · 运行架构 · 使用指南 · 更新日志

SAYACODE 是基于 LangChain / LangGraph 的本机编程助手。左侧管理工作区与会话，中间呈现对话和工具轨迹，右侧展示计划、子 Agent、审批与代码交付。Agent 由 LangChain create_agent 构建；LangGraph 管理消息、待办、检查点和审批中断。Web 页面只展示和操作运行结果，不另建一套 Agent 执行协议。

**3.x 的运行方式：**交互式 TUI 已由 FastAPI + React 工作台取代；适合脚本和 CI 的无头 CLI 继续保留。3.1 增加运行中消息队列、整棵子 Agent 任务树停止和会话管理；3.2 整理四档信任策略；3.2.1 将工具与模型过程放入对话时间线。

快速开始

需要 Windows 或 Linux、Python 3.11–3.13。安装已发布的包无需 Node.js：

python -m pip install --upgrade sayacode
sayacode --workspace .

也可以从源码启动：

git clone https://github.com/saya-ch/sayacode.git
cd sayacode
uv sync --locked
uv run sayacode --workspace .

sayacode 启动后会打印本机地址并尝试打开浏览器。关闭浏览器标签不会结束已启动的 Agent 运行；结束 CLI 进程会按配置宽限期停止后台工作并保存检查点。若不希望自动打开浏览器，使用 sayacode --no-open；如需指定端口，使用 sayacode --port 8765。默认只监听 127.0.0.1，--port 0 自动选择可用端口。

首次打开页面后，从输入框底部的设置按钮进入“模型连接”，添加并启用模型。左侧可用目录选择器加入工作区、新建会话，再在底部输入任务；不会自动扫描整台电脑。模型尚未配置时，页面仍可打开并完成设置。

界面语言可在设置中选择中文、English 或跟随浏览器；Agent 回答语言仍遵循用户输入和运行偏好。

完整操作见 WebUI 使用指南。

工作台

运行事件通过本机 SSE 连接推送到页面。每条轨迹带所属线程；切换到子 Agent 可以查看其对话、工具调用和待办。页面断线后会重新读取检查点快照，并在可用范围内补收事件。浏览器只承担观察与操作，运行任务由 CLI 进程持有。

运行中继续输入时，消息先进入输入框旁的持久队列。排队项可编辑、删除，或点击“直接发送”让同一条消息尽快在 Agent 的下一模型步骤生效；已经发出的模型请求和正在执行的工具不会被这个操作中途改写。输入框为空时，右下角的发送位置会按会话状态显示停止或恢复；停止主会话会同时请求所有子 Agent 停止，保留检查点和未处理交付，待用户显式继续。

模型接入

模型配置不预设供应商。添加模型时填写协议、接口地址、API Key、模型 ID、上下文长度和最大输出 token 数；只有端点明确无需认证时才选择无密钥。配置保存在本机，模型密钥不会自动从环境变量读取。

协议决定使用哪个官方 LangChain 模型适配器；SAYACODE 不根据 URL 或模型名称猜测供应商。Web 设置支持新增、修改、测试、启用和删除模型。模型测试会实际请求所配端点，请留意服务商费用。

无密钥模式不会读取环境变量中的服务商密钥。部分官方适配器要求提供非空密钥参数，SAYACODE 会传非秘密占位值；若自建端点严格拒绝任意认证头，需要在端点侧允许该占位值。

审批与执行边界

输入框底部可为当前线程选择模型和信任档；新会话读取用户默认值。子 Agent 派发时复制父线程的档位，此后独立保存，父线程切换不会改动已创建的子 Agent。模型切换在下一次运行时生效。

审批窗口展示工具与参数，可逐项批准或拒绝；只有询问档允许在本会话内记住完全相同的调用。审批继续使用 LangGraph 原生中断与恢复。workspace_auto 是文件工具的路径限制，不是操作系统沙箱：批准后的原生 Shell 仍以当前用户身份运行，可访问网络与工作区外路径。工作区内路径检查会解析符号链接，但不能防御其他本地进程同时改动路径。planner/reviewer 子 Agent 不能调用文件写入、Shell 或外部 MCP，但可以更新待办并向父线程回报；builder 继承派发时父线程的档位。worktree 用于组织子任务的代码交付，不隔离进程。

Web 服务只绑定本机地址，并使用启动令牌、会话 Cookie 和请求校验保护本机 API；这不改变 Agent 工具的系统权限。

子 Agent 与交付

主 Agent 可以派发 builder、planner 和 reviewer。子 Agent 有独立 LangGraph 线程、检查点和待办，可以在主 Agent 继续工作时运行。任务卡显示标题、角色、状态和结果；完成后的结果进入父任务 Inbox，父 Agent 可在空闲时继续处理，也可对既有子 Agent 追问。

对 Git 工作区，builder 可使用独立 worktree，也可选择共享工作区。独立 worktree 会带入派发时的已提交、未提交和未跟踪内容，新增差异需在右侧查看并显式应用；发生冲突时不会部分应用。共享工作区直接修改文件，没有独立差异交付。非 Git 项目的 builder 使用共享工作区。

页面提供子任务的停止、恢复、追问、审批、差异查看与应用。停止主会话会一并停止其所有未结束子 Agent；单独停止子 Agent 只影响该任务。子 Agent 需要人工审批时，审批卡会指明对应线程。

扩展与记忆

• MCP：通过 LangChain MCPAdapter 接入，Web 设置可管理用户或项目服务器、项目信任和重载。MCP 工具仍经过会话信任策略。
• Skill：读取项目 .agents/skills/<名称>/SKILL.md 与用户 SAYACODE_HOME/skills/<名称>/SKILL.md。页面可查看并为当前线程启用；Agent 也能按需调用 Skill 工具加载正文与参考文件。Skill 不提升工具权限。
• 长期记忆：用户偏好和项目事实保存在 LangGraph Store，会话消息仍保存在各自的 checkpoint。自动学习默认关闭，可在 Web 设置中启用、查找、查看依据、固定、更正、确认或遗忘记录。人工项目约定读取 SAYACODE.md 和 CLAUDE.md；用户说明读取 SAYACODE_HOME/instructions.md。详见记忆系统设计。
• 诊断：Web 设置提供 Git 状态、项目分析、符号定位和运行检查。
• 会话与运行：在当前线程查看工具目录、追踪和检查点；空闲时可手动聚焦摘要或回退对话。回退只改变图状态，不撤销文件。工作区 Hook 可在同一面板查看、信任和重载。

本地状态默认位于 ~/.sayacode/，可用 SAYACODE_HOME 指定其他目录。

脚本与 CI：单次运行

-p 保留无需浏览器的单次任务接口，适合脚本和 CI：

sayacode -p "审查当前改动" --trust read_only
sayacode -p "分析项目入口" --output-format json
sayacode -p "检查构建失败" --output-format jsonl

-p - 从标准输入读取任务。输出格式有 text、json、jsonl；--skill <名称> 可以为单次任务启用 Skill。--doctor 运行无头诊断。无头执行遇到人工审批时保存暂停检查点并以退出码 3 结束。

运行架构

flowchart LR
    UI[React / TypeScript 工作台] -->|HTTP + SSE| WEB[FastAPI Web API]
    WEB --> HOST[多工作区宿主]
    CLI[无头 CLI] --> APP[应用组装]
    HOST --> APP
    APP --> AGENT[LangChain create_agent]
    AGENT --> GRAPH[LangGraph 图、检查点与 Store]
    APP --> TASKS[子 Agent、Inbox 与可选 worktree]
    APP --> EXT[MCP、Skill、Hook 与工具]

**状态各有归属：**LangGraph checkpoint 保存消息、待办、摘要和审批中断；LangGraph Store 保存工作区、会话目录、任务关系、Inbox 和长期记忆；宿主仅保存进程内任务句柄与近期展示事件。页面和本地审计不保存第二份聊天历史。详细的生命周期与数据边界见架构说明。

frontend/                   React、TypeScript、Vite 页面
src/sayacode/web/           FastAPI 路由、请求校验、静态资源
src/sayacode/host/          多工作区宿主、事件广播、产品操作
src/sayacode/application.py 单工作区 Agent 组装
src/sayacode/agent/          官方模型、图与检查点运行
src/sayacode/tasks/          可继续子 Agent、Inbox 与交付
src/sayacode/approvals/      信任策略与原生审批
src/sayacode/tools/          文件、Shell、Git、搜索与分析
src/sayacode/extensions/     MCP、Skill、Hook 与人工说明
src/sayacode/memory/         跨会话记忆
src/sayacode/cli/            Web 启动器与无头输出

从 2.x 升级

3.0 是破坏性交互更新。普通 sayacode 改为启动本机 WebUI；原交互式 TUI 和斜杠命令入口已移除，相关操作转到页面。-p、--doctor 与三种无头输出格式继续可用。升级前请备份 SAYACODE_HOME 并阅读更新日志；不要将旧版终端交互教程直接用于 3.0。

开发与贡献

源码开发需要 Node.js 来构建前端；安装已构建的 wheel 不需要 Node.js。构建产物随 Python 包分发。常用检查：

uv sync --locked --extra dev
uv run --no-sync python -m pytest -q
uv run --no-sync python -m ruff check src tests scripts
uv run --no-sync python -m mypy src
cd frontend
npm ci
npm run build

发布检查还包含 wheel 安装后的本机 Web 冒烟。仓库使用 MIT 许可证；欢迎通过 Issues 反馈问题。