diff --git a/docs/design/architecture-v2.md b/docs/design/architecture-v2.md
index a2bb79e..868976b 100644
--- a/docs/design/architecture-v2.md
+++ b/docs/design/architecture-v2.md
@@ -1480,6 +1480,16 @@ sanguo_moziplus_v2/
 > RESTful + JSON，端口 8080（沿用 v1.0）。
 > 所有请求/响应都记录到 moments 表。
 
+#### 3.10.0 API 设计原则（调研审视）
+
+| 原则 | 来源 | 实现方式 |
+|------|------|----------|
+| **幂等性** | Wanman JSON-RPC | 所有写操作可安全重试，重复回报不产生副作用 |
+| **标准错误码** | Wanman JSON-RPC | 统一错误格式 `{ok: false, error: {code, message}}` |
+| **事务保护** | Edict Outbox | 关键写操作（步骤完成）原子化：产出验证 + 状态更新 + 事件记录同一事务 |
+| **版本化** | Gstack | API 版本号前缀 `/api/v1/...`，未来升级不破坏兼容性 |
+| **Agent 零SDK** | Wanman CLI | Agent 只需 curl，不需要任何 SDK |
+
 #### 3.10.1 任务生命周期 API
 
 ```