# sproutclaw

`sproutclaw` 是一个面向服务器运维与开发工作的 Agent 助手，基于 [pi-mono](https://github.com/badlogic/pi-mono) 改造，重点服务于日常服务器管理、Docker 部署、项目开发、故障排查和自动化工作流。

## 定位

- 服务器运维助手：协助 SSH 登录、服务状态检查、日志分析、配置调整和部署排障。
- 开发协作助手：理解本地项目结构，执行代码修改、测试验证和 Git 工作流。
- Docker 部署助手：按项目目录组织 `docker compose` 服务，关注数据持久化、端口规划和资源限制。
- 内网服务助手：适配 smallmengya、bigmengya、alycd 等内网服务器使用习惯。
- WebUI/TUI 双入口：保留控制台 TUI，同时提供独立的网页前端（`sproutclaw-web`）。

## 项目结构

| 路径 | 说明 |
| --- | --- |
| `packages/coding-agent` | 交互式 Agent CLI 与 TUI 主体（含 sproutclaw 定制补丁） |
| `packages/agent` | Agent 运行时、工具调用和状态管理 |
| `packages/ai` | 多模型、多 provider 的 LLM 接入层 |
| `packages/tui` | 终端 UI 渲染库 |
| `sproutclaw` / `sproutclaw.bat` | 启动入口（从已构建 `dist/cli.js` 启动） |
| `build.sh` / `build.bat` | 同上，使用已构建版启动 |
| `test.sh` / `test.bat` | 从源码（tsx）启动，用于开发调试 |
| `scripts/sync-upstream.sh` | 合并上游 pi-mono 更新 |
| `scripts/push-sproutclaw.sh` | 推送到 GitHub / Gitea |

> `.sproutclaw/agent/` 为本地持久化配置目录（settings、auth、sessions、extensions、skills 等），已整体加入 `.gitignore`，不进入版本控制。与原版 pi 的 `~/.pi/agent/` 完全隔离。

## 常用命令

安装依赖并构建：

```bash
npm install --ignore-scripts
npm run build
```

从源码运行（开发调试，无需 build）：

```bash
./test.sh
```

从已构建版运行（日常更快）：

```bash
./build.sh
# 或
./sproutclaw
```

检查代码：

```bash
npm run check
```

## WebUI（sproutclaw-web）

WebUI 是独立项目，位于 `../sproutclaw-web/`，通过 systemd 以服务形式运行。

构建后端：

```bash
cd ../sproutclaw-web
bash build.sh
```

构建前端：

```bash
cd ../sproutclaw-web/frontend
npm install && npm run build
```

管理服务：

```bash
systemctl start sproutclaw-web
systemctl stop sproutclaw-web
systemctl restart sproutclaw-web
systemctl status sproutclaw-web
```

## Git 分支策略

本仓库是 pi-mono 的 fork，同时维护**上游同步**和 **sproutclaw 定制**。

| 分支 | 用途 |
| --- | --- |
| `main` | 稳定可跑版本：已合并的上游 + sproutclaw 定制，推送到 GitHub / Gitea |
| `feature/*` | 日常开发：WebUI、扩展、补丁等，完成后 merge 进 `main` |

### Remote 配置

```text
origin    → https://github.com/shumengya/sproutclaw.git
upstream  → https://github.com/badlogic/pi-mono.git
gitea     → ssh://git@git.shumengya.top:8022/shumengya/sproutclaw.git
```

首次配置 upstream：

```bash
git remote add upstream https://github.com/badlogic/pi-mono.git
git remote add gitea ssh://git@git.shumengya.top:8022/shumengya/sproutclaw.git
```

### 日常开发

```bash
git checkout -b feature/my-fix
# ... 开发、测试 ...
git add <改动的具体文件>
git commit -m "fix: ..."
git checkout main
git merge feature/my-fix
./scripts/push-sproutclaw.sh
git branch -d feature/my-fix
```

### 推送到 GitHub / Gitea

```bash
./scripts/push-sproutclaw.sh
# 或手动
git push origin main && git push gitea main
```

### 合并上游 pi-mono 更新

```bash
git fetch upstream
git merge upstream/main --no-commit --no-ff
# 解决冲突（见下方惯例），然后：
git add <resolved-files>
PI_ALLOW_LOCKFILE_CHANGE=1 git commit
./scripts/push-sproutclaw.sh
```

**合并冲突处理惯例：**

| 文件类型 | 处理方式 |
| --- | --- |
| `README.md`、sproutclaw 定制代码 | 保留本仓库版本 |
| `*.generated.ts` | 采用 upstream |
| `package-lock.json` | 采用 upstream，再 `npm install --ignore-scripts` |
| 测试/文档/新增上游功能 | 采用 upstream |

合并后必做：

```bash
npm install --ignore-scripts
npm run build
./test.sh
```

### sproutclaw 相对 upstream 的定制改动

合并上游时，以下内容**不要误删**：

- `packages/coding-agent/package.json` 中 `piConfig.name = sproutclaw`、`configDir = .sproutclaw`（命名空间隔离）
- `showChangelogOnStartup` 设置项（关闭启动 What's New）
- RPC 扩展：`reload` 命令、bash 流式输出（`bash_update`）、`get_extensions` 接口
- `sproutclaw` / `build.sh` / `test.sh` 等启动脚本
- `scripts/sync-upstream.sh`、`scripts/push-sproutclaw.sh` 等工具脚本
- 本 README 及中文版 CONTRIBUTING.md / SECURITY.md

## 本地配置

`.sproutclaw/agent/` 中以下内容不进 Git：

- `settings.json` → 参考 `settings.example.json` 本地复制
- `models.json`、`auth.json`、`mcp.json`
- `sessions/`、`skills/`、`extensions/`、`prompts/`

环境变量（可选）：

- `SPROUTCLAW_CODING_AGENT_DIR` — 覆盖 agent 配置目录，默认 `<repo>/.sproutclaw/agent`

首次部署：

```bash
cp .sproutclaw/agent/settings.example.json .sproutclaw/agent/settings.json
# 编辑 settings.json 填入 provider / model / auth 信息
```

### 与原版 pi 并存

| | 原版 pi | SproutClaw |
|---|---|---|
| 命令 | `pi` | `sproutclaw` / `mengya` |
| 全局配置 | `~/.pi/agent/` | `~/.sproutclaw/agent/` |
| 项目配置 | `.pi/` | `.sproutclaw/` |
| 环境变量 | `PI_CODING_AGENT_DIR` | `SPROUTCLAW_CODING_AGENT_DIR` |

## 说明

这个仓库是自用 fork，默认围绕树萌芽的服务器环境、部署规范和日常开发习惯调整。上游能力来自 pi-mono，通过 `git fetch upstream && git merge upstream/main` 定期同步，sproutclaw 定制在 `feature/*` 开发后合入 `main`。