shumengya
539599dbb8
Some checks failed
CI / build-check-test (push) Has been cancelled
Use piConfig name sproutclaw and configDir .sproutclaw so commands, env vars, and project config no longer collide with the stock pi install. Co-authored-by: Cursor <cursoragent@cursor.com>
200 lines
5.7 KiB
Markdown
200 lines
5.7 KiB
Markdown
# 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`。
|