From 3ad0a77f798e9d6499718bb5d8371cf4d34866b4 Mon Sep 17 00:00:00 2001
From: cfdaily <cfdaily@gitee.com>
Date: Thu, 14 May 2026 09:27:57 +0800
Subject: [PATCH] auto-sync: 2026-05-14 09:27:57

---
 docs/design/architecture-v2.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

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
 
 ```