sproutclaw

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

定位

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

项目结构

路径	说明
packages/coding-agent	交互式 Agent CLI 与 TUI 主体（含 sproutclaw 定制补丁）
packages/agent	Agent 运行时、工具调用和状态管理
packages/ai	多模型、多 provider 的 LLM 接入层
packages/tui	终端 UI 渲染库
.pi/agent/extensions/webui	网页对话入口（React 前端 + backend/ HTTP 服务 + systemd 集成）
.pi/agent/extensions/*/index.ts	sproutclaw 本地扩展（中文启动页、状态行、命令安装等）
.pi/agent/prompts/	自定义 slash prompt（cl/is/pr/wr 等）
.pi/agent/skills/	可复用 Skills（Gitea、SSH、GitHub 等）
pi-built.sh	使用已构建 dist/cli.js 启动 Agent
scripts/sync-upstream.sh	合并上游 pi-mono 更新
scripts/push-sproutclaw.sh	推送到 GitHub / Gitea

常用命令

npm install --ignore-scripts
npm run build
npm run check
./test.sh
./pi-test.sh

运行本地源码版 Agent（开发调试）：

./pi-test.sh

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

npm run build
./pi-built.sh

启动 WebUI 时，在 TUI 中执行：

/webui on 19133

关闭 WebUI：

/webui off

WebUI 前端单独构建：

cd .pi/agent/extensions/webui/frontend && npm install && npm run build

Git 分支策略

本仓库是 pi-mono 的 fork，采用三层分支，同时维护上游同步和 sproutclaw 定制。

分支	用途
main	稳定可跑版本：已合并的上游 + sproutclaw 定制，推送到 GitHub
upstream-sync	临时同步分支：专门用来 merge upstream/main，解决冲突后再合回 main
feature/*	日常开发：WebUI、扩展、补丁等，完成后 merge 进 main

Remote 配置

origin    → https://github.com/shumengya/sproutclaw.git   （你的 GitHub）
upstream  → https://github.com/badlogic/pi-mono.git       （上游 pi）
gitea     → ssh://git@git.shumengya.top:8022/shumengya/sproutclaw.git （内网备份，可选）

首次配置 upstream：

git remote add upstream https://github.com/badlogic/pi-mono.git

GitHub 网络不稳定时：

export GIT_HTTP_VERSION=1.1

日常开发（feature 分支）

./scripts/new-feature.sh webui-avatar-fix   # 从 main 创建 feature/webui-avatar-fix
# ... 开发、测试 ...
git add <改动的具体文件>                    # 不要用 git add -A
git commit -m "fix(webui): agent avatar during tool calls"
git checkout main
git merge feature/webui-avatar-fix
./scripts/push-sproutclaw.sh
git branch -d feature/webui-avatar-fix      # 合并后可删

推送本地更新到 GitHub

git checkout main
./scripts/push-sproutclaw.sh

合并上游 pi-mono 更新

./scripts/sync-upstream.sh
# 若有冲突，按下方规则解决后：
git add <resolved-files>
git commit
git checkout main && git merge upstream-sync
./scripts/push-sproutclaw.sh

合并冲突处理惯例：

文件	处理方式
README.md、sproutclaw 定制代码	保留本仓库版本
package-lock.json	采用 upstream，再执行 npm install --ignore-scripts
*.generated.ts	采用 upstream
.pi/agent/extensions/	保留 sproutclaw 版本

合并后必做：

npm install --ignore-scripts
npm run build
./pi-test.sh

sproutclaw 相对 upstream 的 intentional 改动

合并上游时，以下定制不要误删：

• showChangelogOnStartup 设置项（关闭启动 What's New）
• .pi/agent/extensions/webui/ 网页 UI
• .pi/agent/extensions/startup-chinese/ 等本地扩展目录
• .pi/agent/extensions/webui/backend/ WebUI 后端模块化拆分
• 本 README（仅 sproutclaw 说明，不含上游文档）

本地配置

.pi/agent/ 中以下内容不进 Git（含密钥/内网地址）：

• settings.json → 参考 settings.example.json 本地复制
• models.json、auth.json
• sessions/

首次部署：

cp .pi/agent/settings.example.json .pi/agent/settings.json
# 编辑 settings.json 填入 provider / model

说明

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