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 当工作台的旧手测口径
2026-10-19 21:23:59 +08:00
1 parent 64bc8b1552
commit 9304b0e98c
@@ -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。
@@ -0,0 +1,8 @@
+# OpsxAPI 项目入口
+
+请先阅读 [AGENTS.md](AGENTS.md)。公共规则只维护在该文件中。
+
+- 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)
+- 架构一页：[docs/architecture.md](docs/architecture.md)
@@ -60,7 +60,7 @@ make install
 ./run.sh stop | status
 ```

-打开 http://127.0.0.1:8787/ 看落地页；操作请用 `./run.sh gui`。`:5173` 只是桌面 WebView 源。
+打开 http://127.0.0.1:8787/ 看落地页；操作只走 `./run.sh gui`。不要用浏览器打开 Vite 开发源当工作台。

 ## 官网 / 文档 / 定价（homepage/，纯静态）

@@ -104,14 +104,14 @@ cd server && go test ./...

 ## P0 自动化演示（本地）

-1. `./run.sh gui` → 桌面工作台（Gin `:8787` + Vite 源）
+1. `./run.sh gui` → 桌面操作入口（本机 Gin 默认 `:8787`）
 2. 进入自动化测试 → **装载回归示例** → **运行**（依赖本机 Gin `:8787/v1/echo`）
 3. AI：**保存并运行** 与手动/定时共用同一执行器与报告
 4. 定时：支持 5 段 Cron 或间隔；应用保持打开；见 `docs/HANDTEST-P0.md`

-## 根目录 Tauri 开发布局
+## 开发布局

-前端全部位于 `src/`（`core/`、`transport/`、`features/`、`components/`），Rust 位于 `src-tauri/`。不再使用 `apps/` 或 npm workspace；`homepage/` 落地页保持独立，`server/` 保留本地辅助服务。
+前端在 `src/`（`core/`、`transport/`、`features/`、`components/`），Rust 在 `src-tauri/`，Gin 在 `server/`。本仓没有 `apps/` / `packages/` monorepo。`homepage/` 独立。边界与安全底线见 [docs/architecture.md](docs/architecture.md)。

 ```bash
 npm install
@@ -139,10 +139,10 @@ cargo test --manifest-path src-tauri/Cargo.toml --lib
 - Mock 页面顶部可直接启用或关闭 HTTP 响应，并可一键创建 `GET /demo` 示例；保存草稿后点击「发布全部已保存接口」，在已发布版本中试运行。设置 → Mock 服务保留相同开关及分享地址、环境关联配置。关闭后返回 503，保留数据和监听端口；彻底停止进程使用 `./run.sh stop`。随机数据生成规则位于「设置 → 数据生成」。
 - 第一版使用单服务、方法 + 完整路径匹配（忽略尾斜杠），暂不支持路径参数、多响应条件及请求体匹配。JSON 可使用已有 `@integer` 等模板表达式；文本响应原样返回。
 - `./run.sh gui` 默认启动本机管理服务 `127.0.0.1:8787` 和独立 Mock 响应监听 `0.0.0.0:8798`。后者默认仅接受回环/私有网段来源，不注册账号、发布或代理管理路由；内网同事按实际 HTTP 方法访问 `http://本机内网IP:8798/mock/<token>/接口路径`。
- Mock 页的路径输入框只填写 `/example` 等相对路径；保存并发布后，编辑器顶部会显示可复制的完整地址。`http://localhost:5173/mock/example` 指向桌面开发界面，不是 Mock 响应。默认无需额外 Header，完整地址包含随机地址令牌。若要进一步限制已获知地址的访问，可在「设置 → Mock 服务 → 访问验证」生成并保存 Bearer 密钥；访问者须发送 `Authorization: Bearer <密钥>`，服务只保存密钥摘要。浏览器地址栏无法设置此 Header，请使用接口请求页或 curl；试运行框可临时填写密钥。
+- Mock 页的路径输入框只填写 `/example` 等相对路径；保存并发布后，编辑器顶部会显示可复制的完整地址。浏览器里的 Vite 开发源（含 `/mock/...`）不是 Mock 响应，也不是工作台入口。默认无需额外 Header，完整地址包含随机地址令牌。若要进一步限制已获知地址的访问，可在「设置 → Mock 服务 → 访问验证」生成并保存 Bearer 密钥；访问者须发送 `Authorization: Bearer <密钥>`，服务只保存密钥摘要。浏览器地址栏无法设置此 Header，请使用接口请求页或 curl；试运行框可临时填写密钥。
 - 分享域名需由内网 DNS/hosts 解析到运行本机服务的机器；HTTPS 由内网反向代理提供，可将域名解析到内网 IP，也可自行端口映射或反向代理至公网 IP；数据仍保存在自有机器。输入分享地址不会自动修改 DNS、监听或部署。
 - 若只允许本机访问，启动前设置 `OPSXAPI_MOCK_ADDR=127.0.0.1:8798`；更改监听配置需停止后重新启动。设置页会显示配置的监听地址及本机地址候选；访问仍需端口可达。
- 更新后运行 `./run.sh gui` 会检查 Mock 管理接口，并在本项目旧后端缺少该接口时重启服务；也可手动运行 `./run.sh stop && ./run.sh gui`。`http://localhost:5173/mock` 不是内网 Mock 服务入口，`:5173` 只是桌面界面的开发源。已发布示例的分享地址为 `http://本机内网IP:8798/mock/<随机令牌>/demo`；令牌可在 Mock 页面「已发布版本」中复制。`homepage/` 不参与 Mock 数据保存。
+- 更新后运行 `./run.sh gui` 会检查 Mock 管理接口，并在本项目旧后端缺少该接口时重启服务；也可手动运行 `./run.sh stop && ./run.sh gui`。不要把 Vite 开发源当成内网 Mock 入口或浏览器工作台。已发布示例的分享地址为 `http://本机内网IP:8798/mock/<随机令牌>/demo`；令牌可在 Mock 页面「已发布版本」中复制。`homepage/` 不参与 Mock 数据保存。

 ### 环境地址联动与自定义域名

@@ -1,8 +1,8 @@
 # OpsxAPI P0 手测脚本（10 步）

-前置：`export PATH="$HOME/.nvm/versions/node/v24.19.0/bin:$PATH"`，在仓库根目录 `./run.sh web`，打开 http://127.0.0.1:5173 。
+前置：`export PATH="$HOME/.nvm/versions/node/v24.19.0/bin:$PATH"`，在仓库根目录 `./run.sh gui`（桌面是唯一操作入口；不要用浏览器打开 Vite 开发源）。

-1. 打开工作台，确认左上可切到「自动化测试」（或顶栏进入测试视图）。
+1. 在桌面里确认左上可切到「自动化测试」（或顶栏进入测试视图）。
 2. 点 **装载回归示例**；环境应切到「本地」；出现用例「HTTP 八组合回归（本地 echo）」。
 3. 点该用例右上 **运行**；8 步应全绿（需 :8787 已起）。失败则看报告里哪一步断言挂了。
 4. 在报告区分别点 **导出 MD**、**导出 JSON**，确认文件可打开且 JSON 含 `schema: opsxapi.test-run.v1`。
@@ -11,6 +11,6 @@
 7. 对任一用例点定时图标：填 Cron `*/5 * * * *`（或短间隔），启用；保持页面打开。
 8. 等到命中分钟后，报告出现 trigger=定时；定时对话框可见「日志 …」一行；控制台有 `[OpsxAPI 定时]`。
 9. 手工再跑一遍八组合，确认与定时/AI 共用同一报告列表。
-10. 刷新页面：用例与最近报告仍在（localStorage）；`./run.sh status` 仍显示 server/web UP。
+10. 重启桌面后再开：用例与最近报告仍在（本机存储）；`./run.sh status` 里 desktop / server 为 UP。不要改用浏览器当工作台。

 回滚演示数据：设置里如有「重置工作区」则用之；或清站点 localStorage。
@@ -0,0 +1,12 @@
+# 文档索引
+
+| 文档 | 何时看 |
+| --- | --- |
+| [architecture.md](architecture.md) | 两套壳、目录、数据流、安全底线 |
+| [sdd-template.md](sdd-template.md) | S2/S3 短模板（与 OpsxShell / OpsxDB 同款） |
+| [specs/README.md](specs/README.md) | SDD 分级、评审状态、规格索引 |
+| [specs/_template.md](specs/_template.md) | 入库用长表；不与短模板并行第三套 |
+| [ROADMAP_ACTIVE.md](ROADMAP_ACTIVE.md) | 主动排期 |
+| [HANDTEST-P0.md](HANDTEST-P0.md) | P0 手测（走桌面，不走开浏览器工作台） |
+
+S0/S1 直接改代码。入口规则在仓库根 [AGENTS.md](../AGENTS.md)。
@@ -0,0 +1,50 @@
+# 架构说明
+
+一页。细节以代码和 [AGENTS.md](../AGENTS.md) 为准，不在这里重写功能清单。
+
+## 两套壳
+
+| 壳 | 入口 | 做什么 | 不做什么 |
+| --- | --- | --- | --- |
+| 浏览器 | `./run.sh web` → `http://127.0.0.1:8787/` | 官网、`/docs`、定价（`homepage/dist`） | 请求、集合、Mock 管理、自动化测试 |
+| 桌面 | `./run.sh gui` | 全部操作（Tauri WebView + Rust） | 不把这套 UI 当成浏览器产品 |
+
+Vite 开发源只给桌面 WebView。不要用浏览器打开它当工作台。
+
+## 目录权威
+
+当前 `main` 是扁平根目录，**不是** monorepo：
+
+```text
+src/                     唯一产品 UI（React）
+src/transport/           请求传输；Tauri 调用只走 ipc.ts
+src/features/            功能域
+src/components/          界面组合
+src-tauri/               Tauri 2；command 适配，业务在 src/services/
+server/                  Gin 管理面（默认 127.0.0.1:8787）+ Mock 响应监听
+homepage/                官网与文档源
+tools/homepage-build/    静态站构建
+```
+
+`apps/desktop`、`apps/web`、`apps/server`、`packages/*` 在本仓库不存在。`docs/recovery/2026-10-14.md` 里的 `packages/` 是扁平化中途快照，不是现行路径。不要迁回，也不要再建第二棵 UI。
+
+## 数据流
+
+```text
+桌面 UI
+  → src/transport（直连 / Gin 代理 / Tauri）
+  → 127.0.0.1:8787  代理、账号、工作区、Mock 发布（仅本机管理）
+  → :8798           已发布 Mock 与只读文档分享（默认仅回环/私网来源）
+homepage/dist
+  → Gin 静态托管，与集合数据无关
+```
+
+- 集合、环境、Mock 草稿在本机；发布进本机 SQLite，不因登录改存公网。
+- 实时协议会话不落盘。
+- 分享快照不含鉴权、环境变量和运行历史。
+
+## 安全底线
+
+1. **浏览器只站 + 文档。** 工作台只在 `./run.sh gui`。不要把操作面加回官网。
+2. **Mock 不上公网。** 管理 API 留在 `127.0.0.1:8787`。`:8798` 默认拒绝公网来源；要放开必须显式 `OPSXAPI_MOCK_ALLOW_PUBLIC=1`，且仍不开放发布/账号/代理管理。只本机时用 `OPSXAPI_MOCK_ADDR=127.0.0.1:8798`。
+3. **敏感不明文。** 无对公 `/admin`。令牌、密钥、未发布数据不进官网、文档分享和 Mock 响应正文。分享用随机令牌，不暴露空间归属。
@@ -0,0 +1,64 @@
+# SDD 模板路径: docs/sdd-template.md
+
+# SDD 模板（S2 / S3 使用）
+
+# SDD-xxx：<功能名称>
+
+| 字段           | 内容                  |
+|----------------|-----------------------|
+| 版本 / 变更级别 | 0.1 / S2 或 S3        |
+| 设计状态       | Draft                 |
+| 实现状态       | Not Started           |
+| 负责人 / 日期  | 待指定 / YYYY-MM-DD   |
+| 关联需求       | -                     |
+| 批准状态       | 未批准                |
+
+## 1. 背景、目标与范围
+- **当前行为与证据**：
+- **本次目标**：
+- **非目标**：
+- **必须保留的行为**：
+
+## 2. 需求与约束
+- FR-01：当 <条件> 时，系统必须 <行为>。
+- NFR-01：<性能 / 安全 / 兼容要求及测量方式>
+- 边界条件、异常场景、权限要求
+
+## 3. 架构与方案
+- 涉及模块及职责
+- 关键数据流 / 调用关系
+- 复用哪些现有能力
+- 关键取舍及理由
+- Agent 可自主决定的实现细节
+
+## 4. 接口、数据与配置契约
+（已有权威文件时直接引用路径，仅说明差异）
+- 接口变更：
+- 数据模型 / 迁移：
+- 配置变更：
+- 兼容性：
+
+## 5. 风险与验收
+
+### 风险
+| 风险或失败场景 | 防护 / 降级 / 恢复 | 可观察信号 |
+|----------------|--------------------|------------|
+|                |                    |            |
+
+### 验收标准
+| AC    | 对应需求 | 前置条件与操作 | 预期结果 | 验证方式 | 结果     |
+|-------|----------|----------------|----------|----------|----------|
+| AC-01 | FR-01    |                |          |          | Not Run  |
+
+## 6. 发布与恢复（S3 必填）
+- 前置条件（配置、迁移、备份等）
+- 发布顺序与健康检查
+- 回滚或前向修复步骤
+- 不可逆操作说明
+
+## 7. 待决问题
+| 问题 | 是否阻塞 | 推荐方案 |
+|------|----------|----------|
+|      |          |          |
+
+细流程、状态机与规格索引见 [docs/specs/README.md](specs/README.md)，长表用 [docs/specs/_template.md](specs/_template.md)。两套不并行发明第三份字段；S2/S3 起草可先填本短模板，评审入库时落到 `docs/specs/<domain>/<slug>.md`。
@@ -0,0 +1,53 @@
+# SDD 流程与规格索引
+
+SDD 是 Software Design Document（软件设计文档）；本项目以版本化设计契约驱动开发。需求说明“做什么”，设计说明“如何实现”，测试证据说明“是否做到”。
+
+## 分级与最小产物
+
+按最高影响定级，不以代码行数定级。
+
+| 级别 | 范围 | 实施前产物 |
+| --- | --- | --- |
+| S0 | 文案、格式、无行为变化的文档纠错 | 明确范围和检查方式，无需单独规格 |
+| S1 | 恢复已批准行为的缺陷修复、契约内重构 | 任务记录中的问题、依据、不变量、验收步骤 |
+| S2 | 新功能、API/IPC/配置/数据模型及跨模块行为变更 | 使用 [_template.md](_template.md) 创建或修订功能规格并评审 |
+| S3 | 权限、安全、迁移、删除数据、生产部署 | S2 + 风险、兼容、审计/观测（按产品边界）、发布与恢复方案 |
+
+规格保存在 `docs/specs/<domain>/<slug>.md`。持续开发同一能力时修订已有规格，不重复创建。小功能可将需求与设计分节写在同一文件；大型需求可单独成文并引用。不适用项写明原因。
+
+## 工作流与权限
+
+1. 调研：读取实际代码、适用规则、测试和未提交改动；区分事实、假设、提案。
+2. 需求：定义范围、非目标、用户场景、FR/NFR 及 AC；未知指标标待确认。
+3. 设计：明确边界、接口、数据、失败路径与测试预期，再评审。
+4. 实现：依据已批准版本实施，允许自主选择契约内实现细节。
+5. 验证：将每条 AC 映射至实现位置和测试证据，记录未运行项。
+6. 交付：报告差异、结果和剩余问题，不把构建成功等同功能验收。
+
+S2/S3 的业务行为和契约在实施前需要明确批准依据。已有明确授权覆盖该设计版本与范围时，记录原授权，不重复询问。Agent 不得将“需求看起来清楚”视为自行批准新设计的依据。
+阻塞问题只暂停依赖它的实现，其他调研、设计和独立工作可继续。
+
+## 版本与状态
+
+- 设计状态：Draft → In Review → Approved → Superseded。
+- 实现状态单独记录：Not Started / In Progress / Implemented / Verified。
+- 批准记录包含版本、批准人、日期和可追溯依据；模板不预填批准人。
+- 冻结代表版本受控。改变接口、数据语义、权限或验收预期时，先记录旧/新差异及影响，新版本重新评审；批准旧版本不等于批准新版本。
+- 现有代码只能作为“待评审现状基线”，不能直接标为已批准设计。
+- 文档更正但不改变契约时记录更正即可；不得借文档修订掩盖实现偏差。
+
+## 契约归属与完成条件
+
+SDD 明确接口、Schema、迁移及依赖锁文件的权威路径和版本，不复制多份字段表。当前代码与设计冲突时先判断是缺陷还是设计变更；不能自动以代码覆盖设计。
+仓库规范不覆盖适用的系统/工具限制；后续明确用户指令导致契约变化时应同步修订，不静默执行旧设计。
+
+测试场景和预期结果在实现前定义，测试代码可随实现完成。覆盖受影响的成功、边界、失败、权限和兼容行为。
+所有 AC 有通过证据且实现与契约一致，才可标 Verified。Blocked/Not Run 不算通过；记录命令/环境/日期或人工步骤及结果，不能仅写“已检查”。
+本文件是工作约定，不代表已启用 CI 或分支保护；需要强制禁止合并时须另行配置仓库门禁。
+
+## 规格索引
+
+当前仅建立流程与模板，尚无已批准功能规格。
+
+| 规格 | 版本 | 设计状态 | 实现状态 | 批准依据 |
+| --- | --- | --- | --- | --- |
@@ -0,0 +1,74 @@
+# SDD-<编号>：<功能名称>
+
+> 按需填写；不适用项说明原因。先写第 1–2 节需求，再写设计；实现前确定第 7 节的场景和预期。占位符不代表已完成评审。
+
+| 字段 | 内容 |
+| --- | --- |
+| 版本 / 变更级别 | 0.1 / S2 或 S3 |
+| 设计状态 / 实现状态 | Draft / Not Started |
+| 负责人 / 日期 | 待指定 / YYYY-MM-DD |
+| 关联需求 / 替代规格 | 待填写 / 无 |
+| 批准版本 / 人 / 日期 / 依据 | 未批准 |
+
+## 1. 现状、目标与范围
+
+- 当前行为与证据：<代码/配置/测试路径，区分事实和推测>
+- 用户角色与场景：<谁在什么条件下做什么>
+- 本次目标：<可观察结果>
+- 非目标及必须保留的行为：<明确边界>
+
+## 2. 需求（不写实现）
+
+- FR-01：当 <条件> 时，系统必须 <行为>。
+- NFR-01：<指标、适用规模、测量方式；未知值标待确认，不编造>。
+- 涉及的权限、兼容、输入边界和异常场景：<说明>。
+
+## 3. 架构与职责
+
+<模块、所有权、依赖方向、复用点、关键流程；复杂交互按需附时序图。>
+<备选方案及选择理由；契约内可自主决定的实现细节。>
+
+## 4. 接口、数据与配置契约
+
+| 契约 | 权威文件/版本或本节定义 | 本次差异及兼容策略 |
+| --- | --- | --- |
+| HTTP / IPC / 事件 | <路径、方法、请求、响应、错误码、校验、权限> | <填写或不适用原因> |
+| 数据 / 配置 | <字段、默认值、约束、持久化、迁移、锁文件> | <填写或不适用原因> |
+
+<涉及任务时明确超时、取消、重试、幂等、并发和状态转换；涉及列表时明确分页/排序；避免重复抄写已有 Schema。>
+
+## 5. UI 与交互（不适用则注明）
+
+<入口、主要操作、保存/失败恢复、空/加载/错误/禁用状态。>
+<最小尺寸、全局分栏、滚动区域、长内容、亮暗主题、键盘可达性及国际化。>
+
+## 6. 风险、安全与运行约束
+
+| 失败/风险场景 | 防护、降级或恢复 | 日志/指标/可观察状态 |
+| --- | --- | --- |
+| <场景> | <策略> | <验证方式> |
+
+<权限、凭据、脱敏、执行目标、外部调用及数据保留按需填写；不得扩展产品未授权的审计/审批能力。>
+
+## 7. 验收与验证证据
+
+| AC | FR/NFR | 给定/当/则（含明确预期） | 设计章节/实现位置 | 测试或人工步骤 | 结果及证据 |
+| --- | --- | --- | --- | --- | --- |
+| AC-01 | FR-01 | <正常场景> | <实现前可待填> | <用例/步骤> | Not Run |
+| AC-02 | FR-01 | <异常/边界场景> | <实现前可待填> | <用例/步骤> | Not Run |
+
+<运行后填写命令、环境、日期、结果或证据链接；阻塞与跳过必须说明原因。>
+
+## 8. 发布、迁移与恢复
+
+<适用时：前置条件、备份、发布顺序、健康检查、兼容窗口、回退触发条件、恢复步骤和不可逆限制；S3 必填。>
+
+## 9. 待决问题与变更记录
+
+| 问题 | 影响/是否阻塞 | 负责人/结论依据 |
+| --- | --- | --- |
+| <问题或明确无> | <影响> | <依据> |
+
+| 日期/版本 | 旧→新差异、原因与影响 | 批准依据 |
+| --- | --- | --- |
+| YYYY-MM-DD / 0.1 | 初始草案 | 未批准 |
@@ -0,0 +1,35 @@
+# 主指令路径: AGENTS.md
+# 软件设计与开发规范
+
+你是本项目的软件设计与开发助手，采用 **SDD 驱动开发**。公共规则以 [AGENTS.md](AGENTS.md) 为准。
+
+## 核心原则
+1. 若本次任务写明「只设计」，则不改业务代码；已授权实现则按批准范围继续，不重复审批。
+2. 不编造业务规则、性能指标、依赖版本或批准记录。未知内容标记「待确认」。
+3. 不擅自扩展需求范围，不改变现有接口、数据语义和权限。
+4. 优先引用项目中已有的权威来源（代码、OpenAPI、配置、测试）。
+5. 按实际影响定级，发现契约变化时必须升级。
+
+## 变更级别
+| 级别 | 适用场景 | 文档要求 |
+|------|----------|----------|
+| S0 | 文案、格式、无行为变化的修正 | 直接改；简要说明即可 |
+| S1 | 缺陷修复、契约内重构 | 直接改；说明问题、依据、不变量和验收方式 |
+| S2 | 新功能、接口、数据模型、跨模块行为变更 | 使用 `docs/sdd-template.md` |
+| S3 | 权限、安全、数据迁移/删除、生产变更 | S2 + 风险与回滚（模板第 6 节） |
+
+细流程与规格索引见 `docs/specs/README.md`，长表见 `docs/specs/_template.md`。与短模板二选一落盘，不并行第三套。
+
+## 输出要求
+按以下顺序回复：
+
+1. **变更分级及理由**
+2. **设计文档**
+   - S0 / S1：直接简要描述，然后改代码
+   - S2 / S3：严格按照 `docs/sdd-template.md` 输出
+3. **需要负责人决策的问题**（附推荐方案；无则省略）
+
+## 补充说明
+- 设计批准 ≠ 实现完成 ≠ 验证通过。
+- 未运行的检查不能标记为通过。
+- 只暂停依赖阻塞问题的实现，可继续独立的调研和设计工作。