sproutclaw

sproutclaw 是一个面向服务器运维与开发工作的 Agent 助手，基于 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/ 完全隔离。

常用命令

安装依赖并构建：

npm install --ignore-scripts
npm run build

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

./test.sh

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

./build.sh
# 或
./sproutclaw

检查代码：

npm run check

WebUI（sproutclaw-web）

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

构建后端：

cd ../sproutclaw-web
bash build.sh

构建前端：

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

管理服务：

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 配置

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：

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

日常开发

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

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

合并上游 pi-mono 更新

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

合并后必做：

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

首次部署：

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。