docs: AGENTS/SDD 对齐 Shell·DB，补架构页并清浏览器工作台口径

- 重写 AGENTS：浏览器只站+文档、操作走 ./run.sh gui；目录以现仓 src/src-tauri/server 为准
- docs/sdd-template.md 填成与 Shell/DB 同款短模板；sdd-agents/CLAUDE 指向它与 specs
- 新增 docs/architecture.md（两套壳、数据流、安全三底线）与 docs/README 索引
- HANDTEST/README 去掉用 :5173 当工作台的旧手测口径

AGENTS.md

@@ -0,0 +1,79 @@
+# OpsxAPI 开发指南
+
+接口调试**桌面**客户端（HTTP / GraphQL / WebSocket / SSE / Socket.IO / MQTT）。请使用中文沟通。
+
+## 产品形态（硬边界）
+
+```text
+浏览器  →  只看官网 + 文档（homepage/，Gin 托管 :8787）
+操作    →  只走桌面 Tauri（./run.sh gui）
+Vite    →  仅桌面 WebView 源，不是浏览器产品，不要把工作台加回浏览器
+```
+
+| 职责 | 放哪 |
+| --- | --- |
+| 桌面操作（请求 / 文档编辑 / Mock 管理 / 自动化测试） | **本仓** `src/` + `src-tauri/` |
+| 官网 + 用户文档 | **本仓** `homepage/`（`tools/homepage-build` 出 dist，Gin 只托管） |
+| 本机 API、Mock 响应、代理 | **本仓** `server/`（Go / Gin） |
+
+同族：`opsxshell` / `opsxdb` 同形态（浏览器 = 官网/docs，操作 = 桌面）。`src/` 里的 React 是 **Tauri WebView UI**，不是浏览器 SaaS。
+
+### 安全三句（写进日常约束，不另开专章）
+
+1. 浏览器只站 + 文档。不要把请求工作台、集合或测试跑在浏览器里；Vite 开发源不是对外入口。
+2. 管理服务默认只听 `127.0.0.1:8787`。Mock **响应**口默认 `0.0.0.0:8798` 且只接受回环/私网来源；不上公网，除非显式 `OPSXAPI_MOCK_ALLOW_PUBLIC=1`。官网不挂 Mock 管理或代理 API。
+3. 没有对公网开放的 `/admin`。账号、令牌、密钥、未发布集合不得出现在官网、文档分享或 Mock 响应里的明文。以后若加管理面，敏感字段仍不明文。
+
+## 目录（以当前 `main` 磁盘为准）
+
+```text
+src/            React / TS 桌面 UI（core、transport、features、components）
+src-tauri/      Tauri 2 + Rust services
+server/         Gin：官网静态托管、代理、账号/工作区、Mock 管理 API；另起 :8798 只出 Mock/文档分享
+homepage/       官网与文档源（与 GUI 解耦）
+tools/homepage-build   静态站构建
+```
+
+旧 monorepo（`apps/desktop`、`apps/web`、`apps/server`、`packages/*`）**本仓已不存在**（见 `docs/recovery/2026-10-14.md` 的迁移中快照）。不要把代码迁回去，也不要并行再造一套客户端。能 `./run.sh gui` 跑起来的就是这棵根目录树。
+
+## 架构（怎么改代码）
+
+```text
+UI / store  →  src/transport（browser | gin-proxy | tauri-native；IPC 走 transport/ipc.ts）
+            →  Tauri command  →  src-tauri/src/services/
+server      →  Gin :8787（默认回环）+ Mock 响应 :8798（私网）
+```
+
+- UI 复用 `src/features/`、`src/components/` 与现有 store；不另起同功能架构。
+- Rust command 只做边界校验和适配；业务优先 `src-tauri/src/services/`。
+- 不把本机数据库、访问令牌、AI 密钥或真实请求体提交进 git。
+- 实时会话（WS/SSE/Socket.IO/MQTT）不落盘。
+
+一页说明见 [docs/architecture.md](docs/architecture.md)。
+
+## 怎么跑
+
+```bash
+make install          # 或 npm install
+./run.sh web          # 仅官网 + docs → http://127.0.0.1:8787/
+./run.sh gui          # 桌面操作入口（推荐；默认顺带 Gin）
+./run.sh stop | status
+```
+
+改功能后按范围：`npm test`、`npm run build`、`server/` 下 `go test ./...`、`cargo test --manifest-path src-tauri/Cargo.toml --locked`。交互改动在桌面里点，构建通过不等于验收。
+
+## 给 AI
+
+- 需求清楚就直接改；不确定用最小假设并在回复里写明。
+- 跟仓内模式，禁止平行架构或第二套客户端。
+- 少造文档；只改文档时核对链接，不要求重跑业务测试。
+- 依赖版本以锁文件为准，规划中的能力不要写成已实现。
+- 设计验收：请求 / 环境 / 文档 / Mock / 测试的标识、保存、失败与删除要一致；Mock 写清监听、鉴权、发布范围；自动化测试写清顺序、失败、取消、超时与定时。
+
+## SDD 开发
+
+- 按实际影响取最高级别：S0 文案/格式；S1 契约内修复/重构；S2 新功能、契约或数据模型；S3 安全权限、迁移/删除或生产变更。跨文件不自动升级。
+- **S0 / S1 直接改代码**（S0 简述；S1 写问题、依据、不变量和验收），不套全模板。
+- **S2 / S3** 用 [docs/sdd-template.md](docs/sdd-template.md)。评审入库与状态机用 [docs/specs/README.md](docs/specs/README.md) 和 [docs/specs/_template.md](docs/specs/_template.md)，不另造第三套字段。S3 写清风险与恢复。
+- 引用仓内契约与测试；未知标「待确认」。已授权的范围不重复审批；契约变化至少升到 S2。
+- 设计批准 ≠ 实现完成 ≠ 验证通过；没跑的检查标 Not Run。