diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..a5f3a5a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,42 @@
+# 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`，重新编译并跑测试，确认本地补丁仍然需要、仍然有效。
+
+## 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 修改。