chore: add sproutclaw git workflow and track local extensions

Document main/upstream-sync/feature branch strategy, add sync/push scripts, track .pi/agent extensions and webui in git, and disable startup changelog via showChangelogOnStartup. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-22 20:38:20 +08:00
parent a8daa1d8ff
commit 0a91cc99d0
80 changed files with 15061 additions and 64 deletions
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # sproutclaw

-`sproutclaw` 是一个面向服务器运维与开发工作的 Agent 助手，基于 pi-mono 改造，重点服务于日常服务器管理、Docker 部署、项目开发、故障排查和自动化工作流。
+`sproutclaw` 是一个面向服务器运维与开发工作的 Agent 助手，基于 [pi-mono](https://github.com/badlogic/pi-mono) 改造，重点服务于日常服务器管理、Docker 部署、项目开发、故障排查和自动化工作流。

 ## 定位

@@ -14,16 +14,19 @@

 | 路径 | 说明 |
 | --- | --- |
-| `packages/coding-agent` | 交互式 Agent CLI 与 TUI 主体 |
+| `packages/coding-agent` | 交互式 Agent CLI 与 TUI 主体（含 sproutclaw 定制补丁） |
 | `packages/agent` | Agent 运行时、工具调用和状态管理 |
 | `packages/ai` | 多模型、多 provider 的 LLM 接入层 |
 | `packages/tui` | 终端 UI 渲染库 |
-| `.pi/agent/extensions/webui` | 本地扩展的网页对话入口 |
+| `.pi/agent/extensions/webui` | 网页对话入口（React 前端 + HTTP 服务） |
+| `.pi/agent/extensions/*.ts` | sproutclaw 本地扩展（中文启动页、命令安装等） |
+| `scripts/sync-upstream.sh` | 合并上游 pi-mono 更新 |
+| `scripts/push-sproutclaw.sh` | 推送到 GitHub / Gitea |

 ## 常用命令

 ```bash
-npm install
+npm install --ignore-scripts
 npm run build
 npm run check
 ./test.sh
@@ -48,70 +51,114 @@ npm run check
 /webui off
 ```

-## 说明
-
-这个仓库是自用分支，默认会围绕树萌芽的服务器环境、部署规范和日常开发习惯进行调整。上游能力来自 pi-mono，后续会继续精简、增强并沉淀适合服务器运维开发场景的 Agent 工作流。
-
-To learn more about pi:
-
-* [Visit pi.dev](https://pi.dev), the project website with demos
-* [Read the documentation](https://pi.dev/docs/latest), but you can also ask the agent to explain itself
-
-## Share your OSS coding agent sessions
-
-If you use pi or other coding agents for open source work, please share your sessions.
-
-Public OSS session data helps improve coding agents with real-world tasks, tool use, failures, and fixes instead of toy benchmarks.
-
-For the full explanation, see [this post on X](https://x.com/badlogicgames/status/2037811643774652911).
-
-To publish sessions, use [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). Read its README.md for setup instructions. All you need is a Hugging Face account, the Hugging Face CLI, and `pi-share-hf`.
-
-You can also watch [this video](https://x.com/badlogicgames/status/2041151967695634619), where I show how I publish my `pi-mono` sessions.
-
-I regularly publish my own `pi-mono` work sessions here:
-
- [badlogicgames/pi-mono on Hugging Face](https://huggingface.co/datasets/badlogicgames/pi-mono)
-
-## All Packages
-
-| Package | Description |
-|---------|-------------|
-| **[@earendil-works/pi-ai](packages/ai)** | Unified multi-provider LLM API (OpenAI, Anthropic, Google, etc.) |
-| **[@earendil-works/pi-agent-core](packages/agent)** | Agent runtime with tool calling and state management |
-| **[@earendil-works/pi-coding-agent](packages/coding-agent)** | Interactive coding agent CLI |
-| **[@earendil-works/pi-tui](packages/tui)** | Terminal UI library with differential rendering |
-
-For Slack/chat automation and workflows see [earendil-works/pi-chat](https://github.com/earendil-works/pi-chat).
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and [AGENTS.md](AGENTS.md) for project-specific rules (for both humans and agents).
-
-## Development
+WebUI 前端单独构建：

 ```bash
-npm install --ignore-scripts  # Install all dependencies without running lifecycle scripts
-npm run build        # Build all packages
-npm run check        # Lint, format, and type check
-./test.sh            # Run tests (skips LLM-dependent tests without API keys)
-./pi-test.sh         # Run pi from sources (can be run from any directory)
+cd .pi/agent/extensions/webui/frontend && npm install && npm run build
 ```

-## Supply-chain hardening
+## Git 分支策略

-We treat npm dependency changes as reviewed code changes.
+本仓库是 pi-mono 的 fork，采用三层分支，同时维护**上游同步**和 **sproutclaw 定制**。

- Direct external dependencies are pinned to exact versions. Internal workspace packages remain version-ranged.
- `.npmrc` sets `save-exact=true` and `min-release-age=2` to avoid same-day dependency releases during npm resolution.
- `package-lock.json` is the dependency ground truth. Pre-commit blocks accidental lockfile commits unless `PI_ALLOW_LOCKFILE_CHANGE=1` is set.
- `npm run check` verifies pinned direct deps, native TypeScript import compatibility, and the generated coding-agent shrinkwrap.
- The published CLI package includes `packages/coding-agent/npm-shrinkwrap.json`, generated from the root lockfile, to pin transitive deps for npm users.
- Release smoke tests use `npm run release:local` to build, pack, and create isolated npm and Bun installs outside the repo before publishing.
- Local release installs, documented npm installs, and `pi update --self` use `--ignore-scripts` where supported.
- CI installs with `npm ci --ignore-scripts`, and a scheduled GitHub workflow runs `npm audit --omit=dev` plus `npm audit signatures --omit=dev`.
- Shrinkwrap generation has an explicit allowlist for dependency lifecycle scripts; new lifecycle-script deps fail checks until reviewed.
+| 分支 | 用途 |
+| --- | --- |
+| `main` | 稳定可跑版本：已合并的上游 + sproutclaw 定制，推送到 GitHub |
+| `upstream-sync` | 临时同步分支：专门用来 `merge upstream/main`，解决冲突后再合回 `main` |
+| `feature/*` | 日常开发：WebUI、扩展、补丁等，完成后 merge 进 `main` |

-## License
+### Remote 配置

-MIT
+```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
+./pi-test.sh
+```
+
+### sproutclaw 相对 upstream 的 intentional 改动
+
+合并上游时，以下定制**不要误删**：
+
+- `showChangelogOnStartup` 设置项（关闭启动 What's New）
+- `.pi/agent/extensions/webui/` 网页 UI
+- `.pi/agent/extensions/startup-chinese.ts` 等本地扩展
+- 本 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`。