From 294ce758922dcbe5f497c9e9be8c8b551d7958e5 Mon Sep 17 00:00:00 2001 From: shumengya Date: Sun, 21 Jun 2026 20:56:31 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=EF=BC=8C?= =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E8=BF=87=E6=97=B6=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 移除 .pi/ 目录条目（已 gitignore） - 更新 WebUI 说明为独立 sproutclaw-web 服务 - 修正 build.sh/test.sh 说明和脚本引用错误 - 更新合并上游流程（直接 merge，不再用临时分支） - 补充 Gitea remote 配置说明 Co-Authored-By: Claude Sonnet 4.6 --- README.md | 148 +++++++++++++++++++++++++++++------------------------- 1 file changed, 79 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index c79513ba..2170b5d6 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ - 开发协作助手：理解本地项目结构，执行代码修改、测试验证和 Git 工作流。 - Docker 部署助手：按项目目录组织 `docker compose` 服务，关注数据持久化、端口规划和资源限制。 - 内网服务助手：适配 smallmengya、bigmengya、alycd 等内网服务器使用习惯。 -- WebUI/TUI 双入口：保留控制台 TUI，同时扩展网页前端，方便在浏览器里管理会话和模型。 +- WebUI/TUI 双入口：保留控制台 TUI，同时提供独立的网页前端（`sproutclaw-web`）。 ## 项目结构 @@ -18,158 +18,168 @@ | `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 | +| `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 | +> `.pi/agent/` 为本地持久化配置目录（settings、auth、sessions、extensions、skills 等），已整体加入 `.gitignore`，不进入版本控制。 + ## 常用命令 +安装依赖并构建： + ```bash npm install --ignore-scripts npm run build -npm run check +``` + +从源码运行（开发调试，无需 build）： + +```bash ./test.sh -././test.sh ``` -运行本地源码版 Agent（开发调试）： +从已构建版运行（日常更快）： ```bash -././test.sh -``` - -运行已构建版 Agent（日常更快）： - -```bash -npm run build ./build.sh +# 或 +./sproutclaw ``` -启动 WebUI 时，在 TUI 中执行： - -```text -/webui on 19133 -``` - -关闭 WebUI： - -```text -/webui off -``` - -WebUI 前端单独构建： +检查代码： ```bash -cd .pi/agent/extensions/webui/frontend && npm install && npm run build +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 定制**。 +本仓库是 pi-mono 的 fork，同时维护**上游同步**和 **sproutclaw 定制**。 | 分支 | 用途 | | --- | --- | -| `main` | 稳定可跑版本：已合并的上游 + sproutclaw 定制，推送到 GitHub | -| `upstream-sync` | 临时同步分支：专门用来 `merge upstream/main`，解决冲突后再合回 `main` | +| `main` | 稳定可跑版本：已合并的上游 + sproutclaw 定制，推送到 GitHub / Gitea | | `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 （内网备份，可选） +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 ``` -GitHub 网络不稳定时： +### 日常开发 ```bash -export GIT_HTTP_VERSION=1.1 -``` - -### 日常开发（feature 分支） - -```bash -./scripts/new-feature.sh webui-avatar-fix # 从 main 创建 feature/webui-avatar-fix +git checkout -b feature/my-fix # ... 开发、测试 ... -git add <改动的具体文件> # 不要用 git add -A -git commit -m "fix(webui): agent avatar during tool calls" +git add <改动的具体文件> +git commit -m "fix: ..." git checkout main -git merge feature/webui-avatar-fix +git merge feature/my-fix ./scripts/push-sproutclaw.sh -git branch -d feature/webui-avatar-fix # 合并后可删 +git branch -d feature/my-fix ``` -### 推送本地更新到 GitHub +### 推送到 GitHub / Gitea ```bash -git checkout main ./scripts/push-sproutclaw.sh +# 或手动 +git push origin main && git push gitea main ``` ### 合并上游 pi-mono 更新 ```bash -./scripts/sync-upstream.sh -# 若有冲突，按下方规则解决后： +git fetch upstream +git merge upstream/main --no-commit --no-ff +# 解决冲突（见下方惯例），然后： git add -git commit -git checkout main && git merge upstream-sync +PI_ALLOW_LOCKFILE_CHANGE=1 git commit ./scripts/push-sproutclaw.sh ``` **合并冲突处理惯例：** -| 文件 | 处理方式 | +| 文件类型 | 处理方式 | | --- | --- | | `README.md`、sproutclaw 定制代码 | 保留本仓库版本 | -| `package-lock.json` | 采用 upstream，再执行 `npm install --ignore-scripts` | | `*.generated.ts` | 采用 upstream | -| `.pi/agent/extensions/` | 保留 sproutclaw 版本 | +| `package-lock.json` | 采用 upstream，再 `npm install --ignore-scripts` | +| 测试/文档/新增上游功能 | 采用 upstream | 合并后必做： ```bash npm install --ignore-scripts npm run build -././test.sh +./test.sh ``` -### sproutclaw 相对 upstream 的 intentional 改动 +### sproutclaw 相对 upstream 的定制改动 -合并上游时，以下定制**不要误删**： +合并上游时，以下内容**不要误删**： - `showChangelogOnStartup` 设置项（关闭启动 What's New） -- `.pi/agent/extensions/webui/` 网页 UI -- `.pi/agent/extensions/startup-chinese/` 等本地扩展目录 -- `.pi/agent/extensions/webui/backend/` WebUI 后端模块化拆分 -- 本 README（仅 sproutclaw 说明，不含上游文档） +- 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 ## 本地配置 -`.pi/agent/` 中以下内容**不进 Git**（含密钥/内网地址）： +`.pi/agent/` 中以下内容不进 Git： - `settings.json` → 参考 `settings.example.json` 本地复制 -- `models.json`、`auth.json` -- `sessions/` +- `models.json`、`auth.json`、`mcp.json` +- `sessions/`、`skills/`、`extensions/`、`prompts/` 首次部署： ```bash cp .pi/agent/settings.example.json .pi/agent/settings.json -# 编辑 settings.json 填入 provider / model +# 编辑 settings.json 填入 provider / model / auth 信息 ``` ## 说明 -这个仓库是自用 fork，默认围绕树萌芽的服务器环境、部署规范和日常开发习惯调整。上游能力来自 pi-mono，通过 `upstream-sync` 分支定期同步，sproutclaw 定制在 `feature/*` 开发后合入 `main`。 +这个仓库是自用 fork，默认围绕树萌芽的服务器环境、部署规范和日常开发习惯调整。上游能力来自 pi-mono，通过 `git fetch upstream && git merge upstream/main` 定期同步，sproutclaw 定制在 `feature/*` 开发后合入 `main`。