sayacode 1.4.0

基于 LangChain / LangGraph 的终端 AI 编程 Agent。
为真实代码仓库工作，集成多模型协议适配、32 个核心工具、3 个编排工具与三层权限治理。

目录

• SAYACODE 是什么
• 核心特性
• 快速开始
• 模型配置
• 常用命令
• 工作模式
• 内置工具
• 安全与权限
• MCP、Hook 与项目记忆
• 自定义 Slash 命令
• 本地状态文件
• 开发
• 项目结构
• 适合谁
• License

SAYACODE 是什么

SAYACODE 是一个面向真实代码仓库工作的终端 AI 编程助手，基于 LangChain / LangGraph 生态构建。它不是只会回答问题的聊天壳，而是一个带运行时上下文、工具注册、权限策略、Hook 事件、MCP 扩展、会话持久化和项目记忆的 CLI Agent。

你可以把它放在任意项目目录里，然后让它：

• 梳理仓库结构、入口、依赖和测试布局。
• 读取、搜索、编辑、批量修改文件。
• 执行非交互式 Shell 命令并保存超长输出。
• 查看 Git diff、暂存、提交、拉取、推送。
• 维护多会话、多模型配置和持久项目记忆。
• 接入 Claude Code 风格的 .mcp.json 与 .claude/commands/*.md。

SAYACODE 默认假设你是在本机可信项目里工作，因此能力边界偏向“能干活”。同时，它也提供权限策略、危险操作拦截、敏感文件保护、审计日志和只读模式，避免高权限 Agent 变成不可追踪的黑箱。

核心特性

快速开始

环境要求

• Python >= 3.11
• 推荐使用支持 UTF-8 的终端
• 如使用本地模型，先启动 Ollama 服务

安装

pip install sayacode

Conda 用户：

conda create -n sayacode python=3.13 -y
conda activate sayacode
pip install sayacode

从源码安装：

git clone https://github.com/saya-ch/sayacode.git
cd sayacode
pip install .

开发模式安装：

git clone https://github.com/saya-ch/sayacode.git
cd sayacode
pip install -e ".[dev]"

启动

sayacode

指定工作区：

sayacode --workspace ./my-project

常见启动参数：

sayacode --model-type ollama
sayacode --model-type openai --model-name gpt-4 --context-window 128000
sayacode --model-type gemini --model-name gemini-2.5-flash
sayacode --style concise --mode review
sayacode --doctor

脚本或 CI 中执行一次任务并退出：

sayacode -p "检查当前改动并报告测试风险"
sayacode -p "输出项目摘要" --output-format json
echo "解释这段失败日志" | sayacode -p - --output-format json
sayacode -p "检查项目并说明调用了哪些工具" --output-format jsonl

一次性模式不会显示 Logo、启动卡片或交互式权限弹窗。现有权限策略仍然生效，ask 类操作在无人值守时按拒绝处理，避免 CI 卡在输入提示。 jsonl 会逐行输出带版本号和序号的 run.started、assistant.delta、 tool.started、tool.completed、run.completed / run.failed 事件；只暴露可见回复和工具生命周期，不输出模型隐藏推理字段。 模型错误、重试耗尽或无法恢复的流中断会返回非零退出码；json 输出 ok: false， jsonl 以 run.failed 结束，并通过 transition 区分失败类型。若流中断前已有可见文本，失败事件会保留 partial_response。

首次启动时，SAYACODE 会引导你选择模型协议、Base URL、API Key、模型名和上下文窗口。配置会保存在本机 ~/.sayacode/，不会写进项目仓库。

模型配置

SAYACODE 的模型配置由 APIConfigManager 管理，支持保存多个 profile 并自动恢复当前 profile。下表中的 model-type 是兼容接口/协议适配器，而不是对单一厂商的硬绑定；只要服务端提供相应兼容接口，就可以通过 --base-url 接入。

你可以通过环境变量提供密钥：

export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
export GEMINI_API_KEY="..."

Windows PowerShell：

$env:OPENAI_API_KEY="..."

本地或自托管的兼容接口可以通过 --base-url 覆盖默认地址。本地 OpenAI-compatible 服务可使用 loopback HTTP：

sayacode --model-type openai --base-url http://127.0.0.1:8000/v1 --model-name local-model

上下文窗口很重要。SAYACODE 会尽量探测模型上下文；探测不到时会要求你显式输入，例如 128000、256k 或 1M。这避免把未知模型能力伪装成一个错误默认值。

常用命令

CLI 参数

交互式 Slash 命令

工作模式

SAYACODE 的模式不是单纯改变提示词，而是会同步调整运行时权限策略。

切换模式：/mode plan

人格风格

SAYACODE 内置 9 种 prompt style：

standard | concise | tsundere | genki | mesugaki | onee-san | idol | catgirl | mukuchi

也支持中文别名：

标准 | 简洁 | 傲娇 | 元气 | 雌小鬼 | 姐姐 | 偶像 | 猫娘 | 无口

切换示例：

/style concise
/style 傲娇

人格风格只影响表达方式，不改变工具权限和安全边界。

内置工具

SAYACODE 的工具通过 LangChain StructuredTool 注册，并统一包裹 Hook 与审计逻辑。当前包含 32 个核心工具和 3 个编排工具。

工具发现与批量编排

• ToolSearch：按名称、关键词和分组搜索工具；延迟工具会返回完整参数 schema。
• invoke_tool：调用 ToolSearch 找到的延迟工具，底层权限、Hook 与审计继续生效。
• batch_execute：一次提交最多 8 个彼此独立的调用；只并发相邻的并发安全调用，不跨写入/Shell/Git 边界重排。

get_system_info、list_environment_variables、read_output_file、git_remote 和 6 个项目分析工具默认延迟加载。这样模型启动时只绑定 25 个工具，而不是把全部 schema 一次性放入上下文。

文件操作

• read_file
• write_file
• search_replace
• batch_edit
• glob_search
• grep_search
• create_directory
• delete_file
• list_directory

Shell

• execute_command_tool
• check_command_safety_tool
• read_output_file
• get_system_info
• list_environment_variables

Shell 工具默认是非交互式执行。需要输入的命令应使用 input_text 一次性传入，或改写为命令行参数、环境变量、配置文件、here-string/管道输入。超长 stdout/stderr 会保存到 .sayacode_outputs/，再用 read_output_file 按 head、tail 或 grep 读取。

Git

• git_status
• git_diff
• git_log
• git_branch
• git_checkout
• git_add
• git_commit
• git_stash
• git_pull
• git_push
• git_remote

Web 搜索

• web_search

web_search 默认使用免 API Key 的 DuckDuckGo HTML 搜索，返回标题、URL 和摘要；如果你有自托管 SearXNG，可设置 SAYACODE_SEARCH_PROVIDER=searxng 和 SAYACODE_SEARXNG_URL 切换。

项目分析

• analyze_project
• get_project_summary
• list_project_files
• get_file_info
• list_symbols
• find_symbol

符号索引支持 Python、JavaScript、TypeScript、JSX、TSX。Python 文件使用 ast 解析，JS/TS 使用轻量正则索引类、函数和箭头函数。

安全与权限

SAYACODE 面向高权限本地 Agent 场景设计。它不会假装 Agent 没有能力，而是把危险边界做成可解释、可审计、可切换的系统。

危险操作拦截

独立安全模块会拦截高风险命令和路径，例如：

• rm -rf /、format、curl ... | sh 等危险命令。
• Windows / Unix 系统目录。
• .ssh、私钥、证书、.npmrc、.pypirc、.netrc、credentials、secrets、tokens。
• .env、.env.local 等真实环境文件。

模板文件如 .env.example、.env.sample、.env.template、.env.dist 会被允许。

权限策略

权限策略支持 user/project/session 三类来源：

• 用户级权限：~/.sayacode/permissions.json
• 项目级权限：<workspace>/.sayacode/permissions.json
• 会话级权限：由 /mode 或运行时临时策略注入

常用命令：

/permissions
/permissions allow write_file user
/permissions ask execute_command_tool project
/permissions deny delete_file project
/permissions audit

审计日志

工具调用、权限判断、Hook、MCP 调用都会写入本机审计日志：

~/.sayacode/audit.jsonl

诊断

sayacode --doctor
sayacode --doctor --json
sayacode --doctor --bundle support.json

--bundle 会输出脱敏支持包，方便排查配置、工作区、依赖和状态问题。

MCP、Hook 与项目记忆

MCP

SAYACODE 支持 Claude Code 风格的项目 .mcp.json。

项目存在 .mcp.json 时，默认不会直接启动项目 MCP server。你需要显式信任当前工作区：

/mcp
/mcp trust
/mcp reload
/mcp tools
/mcp untrust

加载后的 MCP 工具默认延迟注册：模型先通过 ToolSearch 获得工具 schema，再经 invoke_tool 调用。MCP 原有权限检查、Hook 和审计链不会被绕过；MCP 工具在 batch_execute 中默认按非并发安全工具串行处理。

信任记录保存在：

~/.sayacode/mcp_trusted_projects.json

多 Agent 团队

/team 会启动独立的无交互 SAYACODE 进程。任务从 Worker 邮箱消费，结构化结果写回 Leader 邮箱，并持久化 Worker 状态，避免子进程因无人读取 stdout/stderr 而阻塞。

/team status
/team spawn reviewer 检查认证模块并给出证据
/team spawn planner 设计迁移方案
/team spawn builder 在独立分支实现修复并运行测试
/team wait w1234abcd 120
/team result w1234abcd
/team diff w1234abcd
/team cleanup

• planner 使用 plan 模式，reviewer 使用 review 模式，其他类型使用 build 模式。
• builder 等写入型 Worker 要求源 Git 工作区干净，并自动创建 sayacode/team-<worker-id> 分支及独立 worktree；源工作区不会被直接修改。
• /team diff 只读显示 Worker 分支、worktree、状态、diff 统计和新增提交。
• Worktree 会在 Worker 完成后保留，/team cleanup 只终止进程，不会删除代码交付；确认合并或废弃后再用 Git 手动移除。
• 非 Git 项目或必须共享未提交改动时，可显式使用 shared-builder；这会放弃隔离，应避免与其他写入 Worker 并行。
• 最多同时运行 4 个 Worker；任务结果保存在 ~/.sayacode/teams/default/ 与邮箱目录中。
• 子 Agent 使用临时配置目录运行，模型配置和权限规则只在任务期间复制，完成后自动删除。
• Planner/Reviewer 仍共享源工作区进行只读分析；当前尚未提供操作系统级沙箱。无交互权限询问会安全拒绝，不能把 worktree 当作完整安全沙箱。

Hook

Hook 可用于把工具调用接入本地自动化流程，例如检查、日志、阻断策略或自定义提醒。

支持事件：

SessionStart
UserPromptSubmit
PreToolUse
PostToolUse
ToolFailure
SessionEnd

常用命令：

/hooks
/hooks audit
/hooks trust
/hooks untrust

项目 Hook 位于：

<workspace>/.sayacode/hooks.json

用户 Hook 位于：

~/.sayacode/hooks.json

项目记忆

SAYACODE 会自动加载：

• 用户级记忆：~/.sayacode/memory.md
• 项目级记忆：SAYACODE.md
• 兼容记忆：CLAUDE.md

项目记忆会从当前工作区向上查找。记忆文件支持 @./other.md 导入，但导入会被限制在可信根目录内，并且会拒绝导入密钥、.env、私钥等敏感文件。

自定义 Slash 命令

SAYACODE 支持 Claude Code 风格 Markdown 命令：

<workspace>/.claude/commands/*.md
~/.claude/commands/*.md

例如：

.claude/commands/review.md
.claude/commands/ops/deploy.md

可调用为：

/review
/deploy
/ops:deploy

命令内容中的参数会被展开：

Review this change with focus on: $ARGUMENTS

调用：

/review security and regression risk

本地状态文件

SAYACODE 的用户级状态默认在：

~/.sayacode/

主要文件：

项目级状态：

可以用环境变量覆盖用户状态目录：

export SAYACODE_HOME=/path/to/state

开发

git clone https://github.com/saya-ch/sayacode.git
cd sayacode
pip install -e ".[dev]"
python -m pytest -q

常用检查：

python -m compileall -q lib run.py tests scripts
python -m pytest -q
python -m ruff check .
python -m mypy
python scripts/check_release.py

MyPy 当前采用逐步扩展的阻断棘轮，已覆盖完整 lib/core、lib/tools 包及 Agent、 headless、JSONL 事件协议、运行时组合与交互、启动配置、会话存储、模型配置等共 48 个模块；这些模块出现新的类型错误会直接使 CI 失败。其余历史模块会在清理既有 类型债务后分批加入覆盖列表；已覆盖模块中未显式标注的函数体也会接受检查。

构建包：

pip install build twine
python -m build
python -m twine check dist/*

项目结构

lib/
  agent.py                  # Agent 入口与模型/工具绑定
  api_config/               # 模型 profile 与配置向导
  cli/                      # CLI 参数、交互启动与 headless 一次性执行
  commands/                 # 交互式 slash command handlers
  core/                     # 权限、Hook、MCP、会话、记忆、诊断、符号索引
  models/                   # 模型兼容接口实现与 provider registry
  prompts/                  # 系统提示词与人格风格
  runtime/                  # AppState 到运行时上下文的同步
  tools/                    # 文件、Shell、Git、项目分析工具
tests/                      # pytest 回归测试
scripts/check_release.py    # 发布前检查脚本

适合谁

SAYACODE 适合希望在终端里使用高权限 AI Agent 的开发者：

• 希望 Agent 真正改项目，而不是只给代码块。
• 希望保留本地模型路线，同时兼容云端 API。
• 希望工具调用有权限边界和审计记录。
• 希望一个 CLI 同时覆盖项目分析、代码修改、命令执行、Git 和 MCP 扩展。

License

MIT © saya-ch

Discussion

有问题或建议？欢迎在 GitHub Discussions 参与讨论。