一个本地优先、事件驱动、可审计的 AI Coding Agent 运行时。
SztuCode 面向真实代码仓库工作。用户通过 TUI、桌面工作台或 CLI 提交任务，后台 daemon 负责运行 Agent Loop、调用工具、管理权限和保存会话，并通过 JSON-RPC 事件流持续反馈执行状态。
它既是一个持续完善的本地 AI 编程工具，也是一个用于学习 Agent 工程、软件协作与可信 AI Coding 的开放项目。
那有同学就要问了，为什么都有了codex和Claude code，甚至是其他agent产品如workbuddy，tare work等，我们还是要搭建一个自己的Agent呢，原因就是现阶段Agent岗层出不穷，梁圣自己也说了Agent harness很重要，所以希望有这么一个学习的平台，来让大家接触一些前沿的Agent知识，但贡献知名的coding agent项目还是太难了，opencode和herms agent这些，上手难，理解慢，也不好去根据issue去做相应的pr，所以我就想着做一个学校里大家最方便接触的开源项目，所以我们搞了这么一个项目，而且还尝试接入了一些内置模型，大家能直接通过项目使用免费的deepseek-v4-flash和mimo-v2.5，欢迎大家尝试并点个star。
并不是说要重复造轮子，做一个超越codex和claude code的产品，而是理解与学习，带着批判的目光去看清现有的agent真正的运作方式，知己知彼方能百战不殆。
Important
项目目前处于 0.x 快速开发阶段，接口和界面仍可能变化。请在独立分支和可恢复的工作区中使用 Agent，并谨慎启用 auto 权限模式。
Note
SztuCode 由社区成员发起和维护，不代表任何学校、学院或社团的官方立场。未经授权，项目不使用相关组织的官方名称、标识或背书。
项目不止封装模型 API，而是尝试复现当前 AI Coding Agent 的完整工程链路：
用户目标
→ 项目与会话上下文
→ Agent 规划和模型推理
→ 工具调用与权限审批
→ 文件修改、测试和结果回填
→ Diff 审阅、Trace 与会话恢复
当前项目适合：
- 学习 Agent Loop、工具调用、上下文治理和多智能体协作；
- 构建本地优先、可观察、可扩展的 Coding Agent；
- 研究项目级代码理解、权限安全、RAG 与执行轨迹评测；
- 通过 Issue、Pull Request、Review 和 Release 参与真实开源协作。
| 能力 | 当前实现 |
|---|---|
| Agent Runtime | 基于 ReAct 的多步推理、工具调用、结果回填和终止控制 |
| 多种客户端 | Textual TUI、Tauri 2 + Vue 3 桌面工作台，以及调试用 CLI |
| 模型接入 | Anthropic 与 OpenAI-compatible 双协议，可连接兼容服务商 |
| 工作区工具 | 文件读取、目录浏览、搜索、写入、精确编辑和受控 Shell 执行 |
| 权限系统 | normal、plan、accept_edits、auto 四种运行模式 |
| 会话与记忆 | 持久化会话、分层上下文、Notes、历史恢复和上下文压缩 |
| 扩展机制 | Skills、Subagents 与 MCP 外部工具统一接入 |
| 可观测性 | IPC、EventBus、LLM 三层 Trace，支持事件跟踪和回放 |
| 变更审阅 | 桌面端展示文件变化和 Diff，支持接受、暂存与回退 |
| 项目指令 | 自动发现并注入工作区及父目录的 CLAUDE.md、SZTUCODE.md 等规则 |
| Agent 评测 | sztu-eval 统一任务协议、重复运行、指标报告和 SWE-bench 适配 |
项目级语义索引、统一 LSP、领域 RAG、安全扫描闭环和完整多智能体工作流仍在路线图中，不将设计目标描述为已完成能力。
SztuCode 使用 daemon 与客户端分离的架构。长任务不依赖某个界面窗口的生命周期，不同客户端共享一致的会话、权限和执行状态。
Tauri Desktop ─┐
Textual TUI ───┼─ TCP / NDJSON / JSON-RPC 2.0 ─ sztu-code daemon
CLI ───────────┘ │
├─ Workspace / Session
├─ Agent Runner / Loop
├─ LLM Provider
├─ Tools / Permissions
├─ Skills / Subagents / MCP
├─ Memory / Compaction
└─ EventBus / Trace
默认监听 127.0.0.1:7437。IPC 命令和事件使用 Pydantic v2 模型定义，详情见 架构说明和自动生成的 Wire Protocol。架构取舍记录在 ADR 中。
- Git；
- Python
3.12.x； - uv；
- Anthropic 或 OpenAI-compatible API 凭据；
- 可选：Node.js 20+、Rust 和 Tauri 平台依赖，用于桌面端开发。
git clone https://github.com/rojim666/SztuCode.git
cd SztuCode
uv sync复制配置模板：
cp .env.example .envWindows PowerShell：
Copy-Item .env.example .env在 .env 中选择 Provider，并填写服务商实际提供的模型 ID 和凭据：
# Anthropic
SZTU_LLM_PROVIDER=anthropic
SZTU_LLM_DEFAULT_MODEL=<your-provider-model-id>
ANTHROPIC_API_KEY=<your-api-key>
# 或 OpenAI-compatible
# SZTU_LLM_PROVIDER=openai
# SZTU_LLM_DEFAULT_MODEL=<your-provider-model-id>
# OPENAI_API_KEY=<your-api-key>
# OPENAI_BASE_URL=https://api.example.com不要提交 .env。完整字段和优先级见配置参考。
推荐直接在目标项目目录启动：
uv run sztucode /path/to/your/project首次打开目录时需要确认信任。常用选项：
uv run sztucode . --trust
uv run sztucode . --read-only
uv run sztucode . --replay RUN_ID也可以分别启动 daemon 和 TUI：
# 终端 1
uv run sztu-code
# 终端 2
uv run sztu-tuiCLI 主要用于连通性检查和调试：
uv run sztu ping
uv run sztu run --goal "分析当前项目并修复测试失败"
uv run sztu chat
uv run sztu trace --follow更完整的安装说明见安装与启动。
desktop/ 是基于 Tauri 2、Vue 3 和 TypeScript 的图形客户端，提供项目与会话管理、执行时间线、权限审批、文件浏览、代码预览和 Git 变更审阅。
# 终端 1：仓库根目录
uv run sztu-code
# 终端 2
cd desktop
npm install
npm run tauri dev桌面端验证：
cd desktop
npm run build
npm run test:visual
cd src-tauri
cargo check平台依赖和已知限制见 Desktop README 与开发环境。
SztuCode/
├─ src/sztu_code/
│ ├─ core/ # daemon、Agent Loop、协议、工具、权限与扩展系统
│ ├─ evaluation/ # 统一评测协议、runner、任务集与报告
│ ├─ tui/ # Textual 终端界面
│ └─ cli/ # 命令行客户端
├─ desktop/ # Tauri 2 + Vue 3 桌面工作台
├─ tests/ # 单元测试与集成测试
├─ eval/ # 轨迹分析、报告和 SWE-bench 适配
├─ scripts/ # 协议生成等工程脚本
└─ docs/ # 使用、开发、架构、运维、评测和历史文档
完整模块边界和运行链路见架构说明。
Python 基础检查：
uv run ruff check src tests scripts
uv run mypy src
uv run pytest tests/unit -v
uv run pytest tests/integration -v
uv run python scripts/gen_protocol_doc.py --check修改协议模型时，先运行 uv run python scripts/gen_protocol_doc.py 更新生成文档。测试范围、桌面验证和模块修改清单见测试指南与开发环境。
离线运行 10 个内部 Coding Agent 基准并生成 JSON/Markdown 报告：
uv run sztu-eval run --suite internal --runner reference --repeat 3任务格式、真实 daemon runner、指标定义和 SWE-bench Lite 小样本流程见 评测指南。
项目按可验证能力逐步推进：
| 阶段 | 目标 |
|---|---|
| Contributor Ready | 新成员能理解项目、运行检查并提交第一个聚焦 PR |
| v0.1 | 稳定本地任务闭环、自动化评测基线和更可靠的权限边界 |
| v0.2 | 项目级语义索引、分层上下文、统一 LSP 和多语言评测 |
| v0.3 | 领域 RAG、安全扫描闭环和角色化多智能体协作 |
| v1.0 | 稳定升级路径、发行流程、安全响应和兼容性政策 |
详细版本门槛、研究轨道和明确非目标见项目路线图。当前研究与工程任务可在 GitHub Issues 查看。
欢迎同学、开发者和研究者通过代码、测试、文档、设计、评测和问题分析参与。新贡献者可以从 good first issue 开始，需要社区协作的任务会标注 help wanted。
开始前请阅读：
安全漏洞、权限绕过和凭据泄漏请使用 Private Vulnerability Reporting，不要创建公开 Issue。
感谢所有参与代码、测试、文档和工程建设的贡献者。以下名单依据仓库可验证的 Git 历史整理，本地同邮箱别名已合并；完整记录以 GitHub Contributors 为准。
 rojim666 发起人与维护者 |
 charon2121 Contributor |
 szzhangkkk Contributor |
 GuanG-1008 Contributor |
 neutronstar238 Contributor |
 Shuang-su Contributor |
 crazy19-69 Contributor |
 electrojay27 Contributor |
贡献以公开 Issue、Commit、Pull Request、Review 和 Release 为准；持续贡献者可以逐步承担模块 Review 和维护职责。
SztuCode 使用 MIT License。