shumengya
f1c5e7dc1d
Some checks failed
CI / build-check-test (push) Has been cancelled
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
176 lines
5.2 KiB
Markdown
176 lines
5.2 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，同时扩展网页前端，方便在浏览器里管理会话和模型。
|
||
|
||
## 项目结构
|
||
|
||
| 路径 | 说明 |
|
||
| --- | --- |
|
||
| `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 等） |
|
||
| `build.sh` | 使用已构建 `dist/cli.js` 启动 Agent |
|
||
| `scripts/sync-upstream.sh` | 合并上游 pi-mono 更新 |
|
||
| `scripts/push-sproutclaw.sh` | 推送到 GitHub / Gitea |
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
npm install --ignore-scripts
|
||
npm run build
|
||
npm run check
|
||
./test.sh
|
||
././test.sh
|
||
```
|
||
|
||
运行本地源码版 Agent（开发调试）：
|
||
|
||
```bash
|
||
././test.sh
|
||
```
|
||
|
||
运行已构建版 Agent（日常更快）：
|
||
|
||
```bash
|
||
npm run build
|
||
./build.sh
|
||
```
|
||
|
||
启动 WebUI 时，在 TUI 中执行：
|
||
|
||
```text
|
||
/webui on 19133
|
||
```
|
||
|
||
关闭 WebUI：
|
||
|
||
```text
|
||
/webui off
|
||
```
|
||
|
||
WebUI 前端单独构建：
|
||
|
||
```bash
|
||
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 配置
|
||
|
||
```text
|
||
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：
|
||
|
||
```bash
|
||
git remote add upstream https://github.com/badlogic/pi-mono.git
|
||
```
|
||
|
||
GitHub 网络不稳定时：
|
||
|
||
```bash
|
||
export GIT_HTTP_VERSION=1.1
|
||
```
|
||
|
||
### 日常开发（feature 分支）
|
||
|
||
```bash
|
||
./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
|
||
|
||
```bash
|
||
git checkout main
|
||
./scripts/push-sproutclaw.sh
|
||
```
|
||
|
||
### 合并上游 pi-mono 更新
|
||
|
||
```bash
|
||
./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 版本 |
|
||
|
||
合并后必做：
|
||
|
||
```bash
|
||
npm install --ignore-scripts
|
||
npm run build
|
||
././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/`
|
||
|
||
首次部署：
|
||
|
||
```bash
|
||
cp .pi/agent/settings.example.json .pi/agent/settings.json
|
||
# 编辑 settings.json 填入 provider / model
|
||
```
|
||
|
||
## 说明
|
||
|
||
这个仓库是自用 fork，默认围绕树萌芽的服务器环境、部署规范和日常开发习惯调整。上游能力来自 pi-mono，通过 `upstream-sync` 分支定期同步，sproutclaw 定制在 `feature/*` 开发后合入 `main`。
|