synapbus/AGENTS.md

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 修改。