# SztuCode

> 本地优先的 AI 编程 Agent，支持 TUI/桌面端、工具权限、会话记忆、Skills、Subagents 与 MCPA local-first AI coding agent with TUI and desktop clients, tool permissions, memory, Skills, Subagents, and MCP support.。

- **Type:** MCP server
- **Install:** `agentstack add mcp-rojim666-sztucode`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [rojim666](https://agentstack.voostack.com/s/rojim666)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [rojim666](https://github.com/rojim666)
- **Source:** https://github.com/rojim666/SztuCode

## Install

```sh
agentstack add mcp-rojim666-sztucode
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SztuCode

> 一个本地优先、事件驱动、可审计的 AI Coding Agent 运行时。

[](https://www.python.org/)
[](https://tauri.app/)
[](https://vuejs.org/)
[](LICENSE)

## 项目界面

### 桌面工作台

### TUI 终端界面

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 由社区成员发起和维护，不代表任何学校、学院或社团的官方立场。未经授权，项目不使用相关组织的官方名称、标识或背书。

## 为什么是 SztuCode

项目不止封装模型 API，而是尝试复现当前 AI Coding Agent 的完整工程链路：

```text
用户目标
  → 项目与会话上下文
  → 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，支持接受、暂存与回退               |
| Agent 评测    | `sztu-eval` 统一任务协议、重复运行、指标报告和 SWE-bench 适配 |

项目级语义索引、统一 LSP、领域 RAG、安全扫描闭环和完整多智能体工作流仍在路线图中，不将设计目标描述为已完成能力。

## 系统架构

SztuCode 使用 daemon 与客户端分离的架构。长任务不依赖某个界面窗口的生命周期，不同客户端共享一致的会话、权限和执行状态。

```text
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 模型定义，详情见 [架构说明](docs/reference/architecture.md)和自动生成的 [Wire Protocol](docs/reference/wire-protocol.md)。架构取舍记录在 [ADR](docs/adr/README.md) 中。

## 快速开始

### 环境要求

- Git；
- Python `3.12.x`；
- [uv](https://docs.astral.sh/uv/)；
- Anthropic 或 OpenAI-compatible API 凭据；
- 可选：Node.js 20+、Rust 和 Tauri 平台依赖，用于桌面端开发。

### 安装

```bash
git clone https://github.com/rojim666/SztuCode.git
cd SztuCode
uv sync
```

复制配置模板：

```bash
cp .env.example .env
```

Windows PowerShell：

```powershell
Copy-Item .env.example .env
```

在 `.env` 中选择 Provider，并填写服务商实际提供的模型 ID 和凭据：

```dotenv
# Anthropic
SZTU_LLM_PROVIDER=anthropic
SZTU_LLM_DEFAULT_MODEL=
ANTHROPIC_API_KEY=

# 或 OpenAI-compatible
# SZTU_LLM_PROVIDER=openai
# SZTU_LLM_DEFAULT_MODEL=
# OPENAI_API_KEY=
# OPENAI_BASE_URL=https://api.example.com
```

不要提交 `.env`。完整字段和优先级见[配置参考](docs/getting-started/configuration.md)。

### 启动 TUI

推荐直接在目标项目目录启动：

```bash
uv run sztucode /path/to/your/project
```

首次打开目录时需要确认信任。常用选项：

```bash
uv run sztucode . --trust
uv run sztucode . --read-only
uv run sztucode . --replay RUN_ID
```

也可以分别启动 daemon 和 TUI：

```bash
# 终端 1
uv run sztu-code

# 终端 2
uv run sztu-tui
```

CLI 主要用于连通性检查和调试：

```bash
uv run sztu ping
uv run sztu run --goal "分析当前项目并修复测试失败"
uv run sztu chat
uv run sztu trace --follow
```

更完整的安装说明见[安装与启动](docs/getting-started/installation.md)。

## 桌面工作台

`desktop/` 是基于 Tauri 2、Vue 3 和 TypeScript 的图形客户端，提供项目与会话管理、执行时间线、权限审批、文件浏览、代码预览和 Git 变更审阅。

```bash
# 终端 1：仓库根目录
uv run sztu-code

# 终端 2
cd desktop
npm install
npm run tauri dev
```

桌面端验证：

```bash
cd desktop
npm run build
npm run test:visual

cd src-tauri
cargo check
```

平台依赖和已知限制见 [Desktop README](desktop/README.md) 与[开发环境](docs/development/development.md)。

## 项目结构

```text
SztuCode/
├─ src/sztu_code/
│  ├─ core/          # daemon、Agent Loop、协议、工具、权限与扩展系统
│  ├─ evaluation/    # 统一评测协议、runner、任务集与报告
│  ├─ tui/           # Textual 终端界面
│  └─ cli/           # 命令行客户端
├─ desktop/          # Tauri 2 + Vue 3 桌面工作台
├─ tests/            # 单元测试与集成测试
├─ eval/             # 轨迹分析、报告和 SWE-bench 适配
├─ scripts/          # 协议生成等工程脚本
└─ docs/             # 使用、开发、架构、运维、评测和历史文档
```

完整模块边界和运行链路见[架构说明](docs/reference/architecture.md)。

## 开发与验证

Python 基础检查：

```bash
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` 更新生成文档。测试范围、桌面验证和模块修改清单见[测试指南](docs/development/testing.md)与[开发环境](docs/development/development.md)。

离线运行 10 个内部 Coding Agent 基准并生成 JSON/Markdown 报告：

```bash
uv run sztu-eval run --suite internal --runner reference --repeat 3
```

任务格式、真实 daemon runner、指标定义和 SWE-bench Lite 小样本流程见
[评测指南](docs/guides/evaluation.md)。

## 路线图

项目按可验证能力逐步推进：

| 阶段              | 目标                                               |
| ----------------- | -------------------------------------------------- |
| Contributor Ready | 新成员能理解项目、运行检查并提交第一个聚焦 PR      |
| v0.1              | 稳定本地任务闭环、自动化评测基线和更可靠的权限边界 |
| v0.2              | 项目级语义索引、分层上下文、统一 LSP 和多语言评测  |
| v0.3              | 领域 RAG、安全扫描闭环和角色化多智能体协作         |
| v1.0              | 稳定升级路径、发行流程、安全响应和兼容性政策       |

详细版本门槛、研究轨道和明确非目标见[项目路线图](docs/ROADMAP.md)。当前研究与工程任务可在 [GitHub Issues](https://github.com/rojim666/SztuCode/issues) 查看。

## 参与贡献

欢迎同学、开发者和研究者通过代码、测试、文档、设计、评测和问题分析参与。新贡献者可以从 [`good first issue`](https://github.com/rojim666/SztuCode/labels/good%20first%20issue) 开始，需要社区协作的任务会标注 [`help wanted`](https://github.com/rojim666/SztuCode/labels/help%20wanted)。

开始前请阅读：

- [贡献指南](CONTRIBUTING.md)
- [社区行为准则](CODE_OF_CONDUCT.md)
- [安全政策](SECURITY.md)
- [文档中心](docs/README.md)

安全漏洞、权限绕过和凭据泄漏请使用 [Private Vulnerability Reporting](https://github.com/rojim666/SztuCode/security/advisories/new)，不要创建公开 Issue。

## Contributors

感谢所有参与代码、测试、文档和工程建设的贡献者。以下名单依据仓库可验证的 Git 历史整理，本地同邮箱别名已合并；完整记录以 [GitHub Contributors](https://github.com/rojim666/SztuCode/graphs/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 和维护职责。

## License

SztuCode 使用 [MIT License](LICENSE)。

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rojim666](https://github.com/rojim666)
- **Source:** [rojim666/SztuCode](https://github.com/rojim666/SztuCode)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-rojim666-sztucode
- Seller: https://agentstack.voostack.com/s/rojim666
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.