docs: add worktree lifecycle and cleanup rules

Feature work happens in D:/OPC/synapbus-wt/issue-<N>; after the branch is merged into opc/main (and the running binary replaced if needed) the implementing agent removes the worktree with git worktree remove, after restoring the skip-worktree go.mod/go.sum patch. Never --force, never delete branches, never remove unmerged or dirty worktrees. OPC local patch (opc/main only). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
merge: agent-key authenticated SSE stream /api/agent-events (#1 )
2026-10-06 14:21:44 +08:00 · 2026-10-05 16:20:19 +08:00 · 2026-10-05 16:01:39 +08:00 · 2026-10-05 16:00:53 +08:00
3 changed files with 56 additions and 0 deletions
@@ -0,0 +1,50 @@
+# OPC SynapBus 开发规则
+
+本仓库是 GitHub `synapbus/synapbus` 的 OPC fork，托管在 Gitea `https://git.ilapage.cn/OPC/synapbus`。技术栈、目录结构和编码约定以上游 `CLAUDE.md` 为准；本文件只补充 OPC 本地的分支、运行和安全规则。两者冲突时，安全规则以本文件为准。
+
+## 1. 远程与分支
+
+- `origin` = Gitea（OPC 改动推送到这里）；`upstream` = GitHub（只拉取，推送地址设为 `DISABLED`，禁止向上游直接推送）。
+- `main`：只同步上游，不放 OPC 改动。同步方式：`git fetch upstream` 后把 `upstream/main` 快进推到 `origin/main`。
+- `opc/main`：上游 + OPC 补丁，是本机实际编译运行的版本。
+- 新功能或修复从 `main` 拉分支（如 `feat/<工单号>-<简述>`），在分支上开发和测试，合入 `opc/main`。这样以后可以把同一分支直接提给上游。
+- 本地专用、不打算提给上游的补丁（如 Windows 编译修复）直接提交到 `opc/main`，并在提交信息中注明 `OPC local patch`。
+- 同步上游后把 `main` 合入 `opc/main`，重新编译并跑测试，确认本地补丁仍然需要、仍然有效。
+
+### worktree 使用与清理
+
+- 功能分支在独立 worktree 中开发，统一放在 `D:/OPC/synapbus-wt/issue-<N>`；`D:/OPC/synapbus` 是正在运行服务的检出，不在其中切分支开发。
+- Windows 编译补丁（renameio）在功能 worktree 中以未提交 + `skip-worktree` 的方式放置，不提交到功能分支。
+- 功能分支合入 `opc/main` 并推送后（需要替换运行中二进制的，在替换完成后），由实施该工单的 Agent 删除对应 worktree，并在工单记录。删除前确认：HEAD 已合入 `opc/main`；除 skip-worktree 文件外 `git status --porcelain` 为空；没有进程引用；目录内指向外部的链接先断开。
+- 删除前先撤销 skip-worktree 标记并还原 `go.mod`/`go.sum`（`git update-index --no-skip-worktree go.mod go.sum` 后 `git checkout -- go.mod go.sum`），再执行 `git worktree remove <路径>`，不加 `--force`，不删除分支；之后 `git worktree prune`。
+- 未合并或有未提交改动的 worktree 不得删除，先向用户报告。
+
+## 2. 工单
+
+- 功能、缺陷修复，以及鉴权、权限、接口、数据库迁移方面的改动，先在 Gitea `OPC/synapbus` 建工单，写清目标、非目标、方案、验收、风险和测试；方案经用户确认后再写代码。
+- 涉及鉴权、权限边界、数据库迁移、删除数据的改动属于高风险：实施前和替换运行中的服务前都要等用户确认。
+- 提交信息引用工单号，例如 `feat(#1): ...`。
+
+## 3. 本机运行
+
+- 运行命令：`D:/OPC/synapbus/bin/synapbus.exe serve --host 127.0.0.1 --port 8182 --data D:/OPC/synapbus/data`。
+- **只监听 127.0.0.1**：不使用 `0.0.0.0` 或局域网地址，不设置 `SYNAPBUS_ALLOW_PRIVATE_NETWORKS=true`；需要对外开放时先建单评估。
+- 管理命令要显式指定 socket：`bin/synapbus.exe --socket ./data/synapbus.sock <command>`（Windows 上默认的 `/tmp/synapbus.sock` 连不上）。
+- 编译输出到 `bin/`，不要把 `synapbus.exe` 留在仓库根目录。替换 `bin/synapbus.exe` 意味着重启服务，会断开所有 Agent 的连接，需要先告知用户。
+- `internal/web/dist/` 下只有 `index.html` 受版本控制，前端资源文件（`_app/`）被忽略。本机对 `index.html` 设置了 `skip-worktree`，不要还原或提交它，否则会和当前构建的资源文件名对不上。
+
+## 4. 数据与密钥
+
+- `data/`（`synapbus.db`、`secrets.key`、`vapid_keys.json`、附件）和 `bin/` 已被 `.gitignore` 忽略，**永远不要提交**，也不要复制到工单、日志或消息里。
+- Agent API Key 只保存在 `C:\Users\ila20\synapbus.env`；创建或重新生成 key 时，用脚本把 key 直接写入该文件，不在屏幕或对话中显示。
+- 测试使用临时数据目录，不读写正在运行的 `data/`。
+
+## 5. 验证
+
+- 改动后至少运行：`go build ./cmd/synapbus`（输出到 `bin/` 或临时目录）和受影响包的 `go test`；修改 Web 时按上游 `Makefile` 构建前端。
+- 鉴权和权限相关改动必须有越权测试，例如某个 Agent 的 key 不能看到其他 Agent 的私信或事件。
+- 测试结果必须如实记录；没跑的、跑不了的要写明。
+
+## 6. 许可证
+
+- 上游为 Apache-2.0：保留 `LICENSE`；修改过的文件在文件头或改动处注明 OPC 修改。
@@ -142,3 +142,8 @@ require (
 	sigs.k8s.io/structured-merge-diff/v6 v6.3.0 // indirect
 	sigs.k8s.io/yaml v1.6.0 // indirect
 )
+
+// OPC local patch: github.com/TFMV/hnsw calls renameio.TempFile, which
+// renameio v1 does not provide on Windows. Pin v0.1.0 so the binary builds
+// on Windows. Drop this once upstream hnsw/renameio no longer needs it.
+replace github.com/google/renameio => github.com/google/renameio v0.1.0
@@ -232,6 +232,7 @@ github.com/google/pprof v0.0.0-20201203190320-1bf35d6f28c2/go.mod h1:kpwsk12EmLe
 github.com/google/pprof v0.0.0-20201218002935-b9804c9f04c2/go.mod h1:kpwsk12EmLew5upagYY7GY0pfYCcupk39gWOCRROcvE=
 github.com/google/pprof v0.0.0-20250403155104-27863c87afa6 h1:BHT72Gu3keYf3ZEu2J0b1vyeLSOYI8bm5wbJM/8yDe8=
 github.com/google/pprof v0.0.0-20250403155104-27863c87afa6/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
+github.com/google/renameio v0.1.0 h1:GOZbcHa3HfsPKPlmyPyN2KEohoMXOhdMbHrvbpl2QaA=
 github.com/google/renameio v0.1.0/go.mod h1:KWCgfxg9yswjAJkECMjeO8J8rahYeXnNhOm40UhjYkI=
 github.com/google/renameio v1.0.1 h1:Lh/jXZmvZxb0BBeSY5VKEfidcbcbenKjZFzM/q0fSeU=
 github.com/google/renameio v1.0.1/go.mod h1:t/HQoYBZSsWSNK35C6CO/TpPLDVWvxOHboWUAweKUpk=
Author	SHA1	Message	Date
QiuSWandClaude Opus 5.5	198b043186	docs: add worktree lifecycle and cleanup rules Feature work happens in D:/OPC/synapbus-wt/issue-<N>; after the branch is merged into opc/main (and the running binary replaced if needed) the implementing agent removes the worktree with git worktree remove, after restoring the skip-worktree go.mod/go.sum patch. Never --force, never delete branches, never remove unmerged or dirty worktrees. OPC local patch (opc/main only). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-06 14:21:44 +08:00
QiuSWandClaude Opus 5.5	92a2e034c0	merge: agent-key authenticated SSE stream /api/agent-events (#1 ) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-05 16:20:19 +08:00
QiuSWandClaude Opus 5.5	352f9f6c61	docs: add OPC AGENTS.md with fork, run and secret rules Document the Gitea fork workflow (origin/upstream, main vs opc/main), localhost-only runtime, admin socket path, skip-worktree on the built index.html, and that data/ and API keys must never be committed. OPC local patch (opc/main only). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-05 16:01:39 +08:00
QiuSWandClaude Opus 5.5	cdae55e1d5	build(windows): pin renameio v0.1.0 for hnsw on Windows github.com/TFMV/hnsw uses renameio.TempFile, which renameio v1 does not provide on Windows, so the pristine tree fails to build there with "undefined: renameio.TempFile". Pin v0.1.0 via a replace directive. OPC local patch (opc/main only); not intended for upstream as-is. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-05 16:00:53 +08:00