SAYACODE 2.1

在终端中阅读代码、实施修改并验证结果的编程 Agent。

SAYACODE 使用 LangChain create_agent 执行工具调用，由 LangGraph 保存会话、待办、审批中断和检查点。它提供本地文件、Shell、只读 Git 查询、MCP 工具，以及可继续的后台子 Agent。终端会显示每个 Agent 的工具活动、审批请求和任务结果。

本文描述 2.1 系列与 main 分支的当前行为。2.x 是破坏性重写，不读取或迁移 1.4.0 的配置与会话；旧版保存在 legacy/1.4.0。

快速开始

需要 Windows 或 Linux，以及 Python 3.11、3.12 或 3.13。安装已发布版本：

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

从源码运行最新的 main：

git clone https://github.com/saya-ch/sayacode.git
cd sayacode
python -m pip install uv==0.12.5
uv sync --locked
uv run sayacode --workspace .

源码使用单一 uv.lock；已有 uv 时可跳过安装步骤。首次启动会引导配置模型；之后也可以输入 /model add 重新打开向导。直接运行 sayacode 时，当前目录就是默认工作区。

sayacode --workspace "C:\develop\my-project"

交互终端可以直接输入任务。输入 / 会显示命令候选；继续输入可匹配命令和常用子命令，使用上下方向键选择，Enter 填入候选，再补参数或再次按 Enter 执行。底部状态栏显示当前模型、信任档位、会话、后台任务数和主 Agent 待办进度。

❯ /model add
  选择接口协议，填写地址、密钥、模型 ID 和 token 预算

❯ 请检查这个项目的入口和测试，修复发现的问题并验证
SAYA  读取项目文件...
SAYA  更新待办...
SAYA  运行测试...

上面的对话是操作示意；实际工具、审批和子 Agent 活动由任务及信任档位决定。主 Agent 在终端中标为 SAYA，子 Agent 使用各自的标题、任务 ID 和线程颜色。

单次执行

已配置模型后，可在脚本或 CI 中运行一个任务：

sayacode -p "分析当前改动" --trust read_only
sayacode -p "审查当前改动" --output-format json
sayacode -p "检查项目" --output-format jsonl

-p - 从标准输入读取任务。输出格式支持 text、json、jsonl。无交互运行遇到需要人工审批的操作时会保存暂停状态并以退出码 3 结束；成功为 0，运行失败为 1，参数或配置错误为 2，用户中断为 130。--skill 必须与 -p 同用。

模型配置

SAYACODE 不预设供应商。每个模型配置都由用户明确填写协议、接口地址、API Key、模型 ID、上下文长度和最大输出 token 数。向导中的协议使用方向键选择。

协议决定使用哪个 LangChain 模型适配器；地址和模型 ID 不会被用来猜测供应商。API Key 在向导中隐藏输入，并保存在本地配置；SAYACODE 不从环境变量读取模型密钥。仅当端点无需认证时输入 none。

/models                  查看已保存模型
/model add               添加模型
/model use <名称>        切换当前模型
/model key <名称>        在隐藏输入框更新密钥
/model test [名称]       检查文本、工具调用和流式输出

本地状态默认保存在 ~/.sayacode/，可通过 SAYACODE_HOME 指定其他目录。需要检查配置与诊断时可使用 /paths、/status 和 /doctor。

Skill：按需加载工作方法

Skill 使用标准 SKILL.md，用于保存可复用的任务流程和参考资料。SAYACODE 先让 Agent 看到名称与描述；只有显式启用或 Agent 调用 load_skill 时，正文才进入当前线程的 LangGraph 状态。Skill 不授予额外工具权限；其脚本仍需通过现有 Shell 工具和审批。

<工作区>/.agents/skills/code-review/SKILL.md
~/.sayacode/skills/code-review/SKILL.md

设置 SAYACODE_HOME 后，用户级 Skill 位于该目录的 skills/ 下。同名 Skill 以项目版本为准。一个最小的文件示例：

---
name: code-review
description: 检查代码变更，报告能定位和验证的问题
---

# 代码审查

先读取相关文件和差异，再核对实际调用路径与测试结果。
报告问题位置、影响和验证方式。

/skills                     列出当前工作区可用 Skill
/skill show code-review     查看正文
/skill use code-review      启用到当前会话

Agent 也能调用 list_skills 搜索目录、load_skill 激活所需 Skill，再用 read_skill_resource 按需读取同一 Skill 目录里的文本参考文件。正文有大小和上下文预算限制，较长材料宜放在引用文件中。创建上面的示例文件后，无交互运行可使用 sayacode --skill code-review -p "审查当前改动"。格式参考 Agent Skills 规范。

权限与审批

信任档位属于当前会话；新会话使用用户默认档位。切换档位使用 /trust <档位>，设置新会话默认值使用 /trust default <档位>。

/trust ask
/reviewer setup
/reviewer test
/trust jev

ask 档可以在本会话记住完全相同的调用。审批卡片会显示工具、目标和脱敏参数；拒绝与批准走 LangGraph 原生中断恢复。SAYACODE 没有操作系统沙箱：文件工具可以接受工作区外的绝对路径，Shell 以当前用户权限执行。Git 变更也通过 Shell 进行；内建 Git 工具只做查询。

可继续的子 Agent

主 Agent 可以派发 builder、planner 和 reviewer。每个子 Agent 有独立线程、待办与检查点；主 Agent 在子 Agent 运行时可以继续工作。工具活动会在同一终端按线程标题和颜色区分。子 Agent 完成一轮后进入可继续的 idle 状态，结果进入父 Agent 的持久 Inbox；空闲的父 Agent 可自动继续处理结果。

/team spawn planner 梳理认证流程
/team spawn builder 修复解析器并运行测试
/team list
/team status <任务 ID>
/team followup <任务 ID> 请再检查边界条件

Git 工作区中的 builder 默认创建独立 worktree，并带入派发时的已提交、未提交和未跟踪文件。差异需显式应用；如果希望 builder 直接共享父工作区，可选 --shared。非 Git 工作区中的 builder 使用共享工作区。

/team spawn builder --shared 直接修改当前工作区
/team diff <任务 ID>       查看 worktree 交付
/team apply <任务 ID>      显式应用交付
/team cleanup <任务 ID>    清理已结束任务的 worktree

共享工作区没有独立差异和 apply 阶段。worktree 用来组织交付，不是安全沙箱。子 Agent 的待批准操作可以通过 /team pending <任务 ID> 查看，再用 /team approve <任务 ID> 或 /team reject <任务 ID> 处理。

会话、计划与上下文

复杂任务由 LangChain TodoListMiddleware 管理待办，Agent 可根据验证结果或子任务发现调整计划。消息、待办、摘要和审批中断保存在 LangGraph checkpoint；Store 保存会话目录、任务关系、Inbox 与交付元数据。

自动摘要默认按模型上下文与最大输出预算动态计算，触发目标不超过上下文窗口的约 80%；上下文编辑默认关闭。/rewind 只改变对话状态，不撤销文件或 Git 操作。

MCP、Hook 与项目约定

SAYACODE 通过 LangChain MCPAdapter 发现 MCP 工具。用户级服务器在本地配置中管理；项目 .mcp.json 需要先显式信任工作区。MCP 工具仍经过当前会话的权限策略。

/mcp status
/mcp trust
/mcp reload
/mcp untrust

Hook 支持 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、ToolFailure、SessionEnd 六类事件。SAYACODE.md、CLAUDE.md 与 /memory 提供项目约定和记忆；它们与 Skill 都是提示上下文，不会改变工具权限。

架构与开发

src/sayacode/
├── agent/          create_agent、模型、运行时与事件
├── approvals/      信任策略、Jev 审理与人工中断
├── tasks/          子 Agent 生命周期、Inbox 与 worktree
├── tools/          文件、Shell、Git、搜索与代码分析
├── extensions/     Skill、MCP、Hook 与项目记忆
├── cli/            交互终端、斜杠命令与单次输出
└── application.py  组装模型、工具、中间件和存储

SAYACODE 的产品代码负责工具和终端适配；Agent 循环、工具调度、状态持久化、摘要和审批中断由 LangChain / LangGraph 组件承担。架构细节见 docs/architecture.md。

uv sync --locked --extra dev
uv run --no-sync python scripts/check_release.py
uv build

发布门禁运行 Pytest、Ruff、MyPy、锁文件检查、wheel 构建与安装后 CLI 冒烟。GitHub Actions 覆盖 Windows、Ubuntu 和 Python 3.11 至 3.13。问题与改进建议可提交到 Issues。

版本与许可

变更记录见 CHANGELOG.md。项目使用 MIT 许可证。