docs(接口): 5、接口分层重组 01～05 子目录

规范/对接/Hook/OpenAPI/交互图分目录；Hub 与机擎 Skill 路径同步；Obsidian 子目录配色。

Co-authored-by: Cursor <cursoragent@cursor.com>

.obsidian/snippets/workphone-devdoc.css

@@ -60,6 +60,12 @@
   color: #0277BD !important;
   font-weight: 600;
 }
+.nav-folder-title[data-path^="开发文档/5、接口/0"] > .nav-folder-title-content {
+  color: #0288D1 !important;
+}
+.nav-folder-title[data-path="开发文档/5、接口/images"] > .nav-folder-title-content {
+  color: #78909C !important;
+}
 .nav-folder-title[data-path="开发文档/6、后端"] > .nav-folder-title-content {
   color: #0277BD !important;
   font-weight: 600;

sdk/app/main.py

@@ -32,7 +32,7 @@ _APP_DIR = os.path.dirname(__file__)
 _STATIC_DIR = os.path.join(_APP_DIR, "static")
 _DOCS_ROOT = os.path.normpath(os.path.join(_APP_DIR, "..", "..", "开发文档"))
 _DOC_PAGE_MAP = {
-    "api-architecture": os.path.join(_DOCS_ROOT, "5、接口", "API架构与交互流程图.html"),
+    "api-architecture": os.path.join(_DOCS_ROOT, "5、接口", "05-交互图", "API架构与交互流程图.html"),
     "anti-ban-architecture": os.path.join(_DOCS_ROOT, "2、架构", "04-交互图", "防封模块架构图.html"),
     "wechat-server-flow": os.path.join(_DOCS_ROOT, "2、架构", "04-交互图", "微信控制-设备服务器交互图.html"),
 }
@@ -157,7 +157,7 @@ _WORKBENCH_DOCS = [
         "category": "api",
         "section": "接口与协议",
         "folder": "5、接口",
-        "file": "接口规范.md",
+        "file": "01-规范与统一层/接口规范.md",
         "keywords": ["接口", "协议", "字段", "规范"],
     },
     {
@@ -167,7 +167,7 @@ _WORKBENCH_DOCS = [
         "category": "api",
         "section": "接口与协议",
         "folder": "5、接口",
-        "file": "存客宝对接规范.md",
+        "file": "02-业务对接/存客宝对接规范.md",
         "keywords": ["存客宝", "对接", "SDK", "聚合"],
     },
     {

sdk/app/routers/hook_modules.py

@@ -1,6 +1,6 @@
 """
 Hook 模块管理路由
-对标文档：开发文档/5、接口/Hook模块管理接口.md
+对标文档：开发文档/5、接口/03-Hook与微信/Hook模块管理接口.md
 """
 
 from __future__ import annotations

开发文档/10、项目管理/Frida接口开发与对接进度.md

@@ -110,7 +110,7 @@
 | [cunke_bao_service.py](../6、后端/cunke_bao_service.md) | 存客宝服务实现 |
 | [cunke_bao.py](../5、接口/cunke_bao_router.md) | 存客宝路由实现 |
 | [wechat_hook_ckb_patch.js](../6、后端/wechat_hook_ckb_patch.md) | Hook扩展实现 |
-| [存客宝对接规范.md](../5、接口/存客宝对接规范.md) | 存客宝API规范 |
+| [存客宝对接规范.md](../5、接口/02-业务对接/存客宝对接规范.md) | 存客宝API规范 |
 | [项目落地执行表.md](../10、项目管理/项目落地执行表.md) | 项目整体进度 |
 
 ---

开发文档/10、项目管理/工作日志.md

@@ -3048,3 +3048,14 @@ v3.1: Agent 内置 AI Brain → 心跳驱动自主决策 → Frida优先/u2兜
 **进度**: 99.5%（文档结构无功能阻塞）
 
 **下一步**: 新功能文档当场按 Skill 归类；Gitea NAS 在线后 `bash docs/gitea/sync_when_online.sh`
+
+---
+
+### 2026-05-24 | 5、接口 目录分层重组
+
+**完成项**:
+1. 根目录 8+ 文件迁入 `01-规范与统一层/`～`05-交互图/`
+2. 各层 README + `images/` 占位；`sdk/app/main.py` Hub 路径对齐
+3. 机擎/开发文档 Skill/资料/手册 引用路径批量更新
+
+**进度**: 99.5%

开发文档/10、项目管理/验收与项目说明.md

@@ -59,7 +59,7 @@
 > 四层：设备端 | 服务端 | 中间层 | 数据库。代码根：设备端 `sdk/agent/`，服务端 `sdk/app/`，中间层 `sdk/php-sdk/`、`sdk/typescript-sdk/`。
 
 - **设备端**（`sdk/agent/`）：agent.py、skill_executor、skills/wechat|douyin|xhs|xianyu 已 100%；_execute_agent_task 已接 SkillExecutor（微信/抖音任务可执行）；待：Frida/抓包（按需）。
-- **服务端**（`sdk/app/`）：unified、ws_hub、device_manager、adb、skills 已 100%；联调契约见 5、接口/接口规范 §1.5；M6 抓包按需。
+- **服务端**（`sdk/app/`）：unified、ws_hub、device_manager、adb、skills 已 100%；联调契约见 5、接口/01-规范与统一层/接口规范 §1.5；M6 抓包按需。
 - **中间层**（`sdk/php-sdk/`、`sdk/typescript-sdk/`）：PHP/TS SDK 与 unified 契约 100%；unified 新增时两 SDK 同步更新。
 - **数据库**：MongoDB/Redis/MySQL 已就绪；按模块扩展集合/表。
 - **并行边界**：改 agent.py/ws_hub/device_manager 时与改 Skill/unified 的人协调；中间层仅依赖服务端契约，冲突少。

开发文档/1、需求/项目概述.md

@@ -189,7 +189,7 @@
 ## 六、下一步
 
 1. **架构设计**：查看 [2、架构/01-总览/系统架构.md](../2、架构/01-总览/系统架构.md)
-2. **接口对接**：查看 [5、接口/接口规范.md](../5、接口/接口规范.md)
+2. **接口对接**：查看 [5、接口/01-规范与统一层/接口规范.md](../5、接口/01-规范与统一层/接口规范.md)
 3. **开发计划**：查看 [10、项目管理/开发进度总表.md](../10、项目管理/开发进度总表.md)
 
 ---

开发文档/5、接口/01-规范与统一层/README.md

@@ -0,0 +1,10 @@
+---
+obsidian-color: "#0277BD"
+---
+
+# 01 · 规范与统一层
+
+| 文档 | 说明 |
+|------|------|
+| [接口规范.md](接口规范.md) | 统一 API（消息/好友/群/设备/脚本）+ §1.5 联调契约 |
+| [通用服务交互层.md](通用服务交互层.md) | Facade + ChannelRouter + 三通道 |

开发文档/5、接口/02-业务对接/README.md

@@ -0,0 +1,10 @@
+---
+obsidian-color: "#0277BD"
+---
+
+# 02 · 业务对接
+
+| 文档 | 说明 |
+|------|------|
+| [存客宝对接规范.md](存客宝对接规范.md) | 存客宝/触客宝调用机擎 |
+| [外部对接网关接口说明.md](外部对接网关接口说明.md) | 外部系统三种对接方式 |

开发文档/5、接口/03-Hook与微信/README.md

@@ -0,0 +1,11 @@
+---
+obsidian-color: "#0277BD"
+---
+
+# 03 · Hook 与微信
+
+| 文档 | 说明 |
+|------|------|
+| [Hook模块管理接口.md](Hook模块管理接口.md) | 模块 CRUD + 脚本 + 设备模块 + Hook 事件 |
+| [微信全功能矩阵_v8.0.56.md](微信全功能矩阵_v8.0.56.md) | 微信 v8.0.56 能力矩阵 |
+| [微信Frida_API契约.md](微信Frida_API契约.md) | **跳转** → [9、手册/工作手机·五图总览与使用手册.md](../../9、手册/工作手机·五图总览与使用手册.md) §三 |

开发文档/5、接口/04-OpenAPI/README.md

@@ -0,0 +1,9 @@
+---
+obsidian-color: "#455A64"
+---
+
+# 04 · OpenAPI
+
+| 文件 | 说明 |
+|------|------|
+| [openapi_v3.0.json](openapi_v3.0.json) | v3.0 机器可读契约；Hub `/docs` 同步 |

开发文档/5、接口/05-交互图/README.md

@@ -0,0 +1,9 @@
+---
+obsidian-color: "#00838F"
+---
+
+# 05 · 交互图
+
+| 文件 | 说明 |
+|------|------|
+| [API架构与交互流程图.html](API架构与交互流程图.html) | 浏览器打开的 API 架构交互图 |

开发文档/5、接口/README.md

@@ -1,19 +1,45 @@
+---
+obsidian-color: "#0277BD"
+cssclasses:
+  - devdoc-index
+---
+
 # 5、接口
 
-**项目**：工作手机SDK v3.0（统一API + Hook模块管理API）
-
-**规则**：本目录除本 README 外最多 **3 个主文档**。
-
-**当前状态**：统一API已完成；Hook模块管理接口已设计。进度以 [开发进度总表](../10、项目管理/开发进度总表.md) 为准。
+**项目**：工作手机SDK v3.0（统一 API + Hook 模块管理 + OpenAPI）  
+**规则**：按 **大类 → 子类** 分层；每子目录除 README 外 ≤3 主文档；HTML/JSON 不进 MD 混放根目录。
 
 ---
 
-## 本目录主文档（≤3）
+## 目录树
 
-| 文档 | 说明 |
+```text
+5、接口/
+├── README.md
+├── images/                   ← 接口类配图（暂无则留空）
+├── 01-规范与统一层/          ← 接口规范 + Facade/ChannelRouter
+├── 02-业务对接/              ← 存客宝 + 外部网关
+├── 03-Hook与微信/            ← Hook 模块 API + 微信矩阵 + Frida 跳转
+├── 04-OpenAPI/               ← openapi_v3.0.json
+└── 05-交互图/                ← API 架构 HTML
+```
+
+---
+
+## 快速跳转
+
+| 大类 | 入口 |
 |------|------|
-| [接口规范.md](接口规范.md) | 统一API规范（消息/好友/群/标签/朋友圈/设备/脚本）+ PHP SDK |
-| [通用服务交互层.md](通用服务交互层.md) | Facade+ChannelRouter+三通道实现 |
-| [Hook模块管理接口.md](Hook模块管理接口.md) | **新增**：模块管理+脚本管理+Hook事件+设备模块API |
+| **01 规范与统一层** | [接口规范.md](01-规范与统一层/接口规范.md) · [通用服务交互层.md](01-规范与统一层/通用服务交互层.md) |
+| **02 业务对接** | [存客宝对接规范.md](02-业务对接/存客宝对接规范.md) · [外部对接网关接口说明.md](02-业务对接/外部对接网关接口说明.md) |
+| **03 Hook与微信** | [Hook模块管理接口.md](03-Hook与微信/Hook模块管理接口.md) · [微信全功能矩阵](03-Hook与微信/微信全功能矩阵_v8.0.56.md) |
+| **04 OpenAPI** | [openapi_v3.0.json](04-OpenAPI/openapi_v3.0.json) |
+| **05 交互图** | [API架构与交互流程图.html](05-交互图/API架构与交互流程图.html) |
 
-> 补全包 `微信Frida_API契约.md` 已收敛入主手册 §三，本目录该文件仅为跳转锚点。
+**维护规范**：[机擎/阿表/开发文档结构规范/SKILL.md](../../机擎/阿表/开发文档结构规范/SKILL.md)
+
+---
+
+## 合并记录
+
+- 2026-05-24：根目录 8+ 文件分层迁入 `01～05` 子目录

开发文档/5、接口/images/README.md

@@ -0,0 +1,3 @@
+# images
+
+接口类 PNG/SVG 放此目录；按 `01-子类/` 分子文件夹（与 `2、架构/images` 规则一致）。

开发文档/8、部署/上线与运维操作手册.md

@@ -83,7 +83,7 @@ WORKPHONE_BASE=http://127.0.0.1:8899 sdk/scripts/real_device_connect_check.sh
 
 - **日志**: Docker 下 `docker compose logs -f workphone-sdk`；本地看终端 uvicorn 输出。  
 - **重启**: `./deploy.sh stop && ./deploy.sh docker` 或重启进程。  
-- **文档**: 外部对接见 `开发文档/5、接口/外部对接网关接口说明.md`；OpenAPI：`/docs`。
+- **文档**: 外部对接见 `开发文档/5、接口/02-业务对接/外部对接网关接口说明.md`；OpenAPI：`/docs`。
 
 ---
 

开发文档/9、手册/工作手机·五图总览与使用手册.html

@@ -480,7 +480,7 @@ python3 tools/wireless_frida_wechat_batch_verify.py
 </tr>
 <tr>
 <td>接口 OpenAPI</td>
-<td><a href="../5、接口/openapi_v3.0.json">5、接口/openapi_v3.0.json</a></td>
+<td><a href="../5、接口/04-OpenAPI/openapi_v3.0.json">5、接口/04-OpenAPI/openapi_v3.0.json</a></td>
 </tr>
 <tr>
 <td>进度</td>

开发文档/9、手册/工作手机·五图总览与使用手册.md

@@ -296,7 +296,7 @@ python3 tools/wireless_frida_wechat_batch_verify.py
 | 命令速查 | [SDK操作手册.md](SDK操作手册.md) |
 | E2E 验收 | [微信消息E2E验证指南.md](微信消息E2E验证指南.md) |
 | 存客宝对接 | [工作手机·一键接入与存客宝对接操作手册.md](工作手机·一键接入与存客宝对接操作手册.md) |
-| 接口 OpenAPI | [5、接口/openapi_v3.0.json](../5、接口/openapi_v3.0.json) |
+| 接口 OpenAPI | [5、接口/04-OpenAPI/openapi_v3.0.json](../5、接口/04-OpenAPI/openapi_v3.0.json) |
 | 进度 | [开发进度总表.md](../10、项目管理/开发进度总表.md) |
 
 以下文档 **已并入本章**，保留文件仅为旧链接锚点，勿再扩写：

开发文档/README.md

@@ -77,7 +77,7 @@
 | [2、架构](2、架构/) | **分层目录** `01-总览/` `02-技术基座/` `03-通道与设备/` `04-交互图/` `05-规范/`；PNG 在 `images/01～04/` | 架构与 §3.0 模块拆解；规范见 [机擎/阿表/开发文档结构规范](../机擎/阿表/开发文档结构规范/SKILL.md) |
 | [3、原型](3、原型/) | 原型设计规范 | 原型规范 |
 | [4、前端](4、前端/) | 前端开发规范、管理端前端开发规范、v0配置 | 前端规范 |
-| [5、接口](5、接口/) | 接口规范、通用服务交互层、Hook模块管理接口 | API 与对接 |
+| [5、接口](5、接口/) | **分层** `01-规范与统一层/`～`05-交互图/`；OpenAPI 在 `04-OpenAPI/` | API 与对接 |
 | [6、后端](6、后端/) | SDK服务端实现文档、Agent端技能实现文档、后端规范与代码汇总 | 服务端+Agent+规范 |
 | [7、数据库](7、数据库/) | 数据库设计文档、数据库管理规范 | 数据层 |
 | [8、部署](8、部署/) | 本地Docker部署指南、设备端Hook安装部署、本地环境凭证 | 部署与凭证 |

机擎/SKILL.md

@@ -345,7 +345,7 @@
 | 服务端SDK抽象 | 机擎/references/工作手机服务端SDK抽象.md |
 | 设备端SDK抽象 | 机擎/references/工作手机设备端SDK抽象.md |
 | 中间层抽象 | 机擎/references/工作手机中间层抽象.md |
-| 存客宝对接规范 | 开发文档/5、接口/存客宝对接规范.md |
+| 存客宝对接规范 | 开发文档/5、接口/02-业务对接/存客宝对接规范.md |
 | 开发文档总入口 | 开发文档/README.md |
 | 存客宝侧进度 | cunkebao_v3/开发文档/工作手机对接/工作手机开发进度.md |
 

机擎/references/工作手机中间层抽象.md

@@ -43,4 +43,4 @@
 - [工作手机服务端SDK抽象](./工作手机服务端SDK抽象.md)
 - [工作手机设备端SDK抽象](./工作手机设备端SDK抽象.md)
 - 开发文档/10、项目管理/多端并行开发模块拆解.md § 三、中间层
-- 开发文档/5、接口/存客宝对接规范.md
+- 开发文档/5、接口/02-业务对接/存客宝对接规范.md

机擎/references/工作手机服务端SDK抽象.md

@@ -65,5 +65,5 @@
 ## 六、相关文档
 
 - [工作手机设备端SDK抽象](./工作手机设备端SDK抽象.md)
-- 开发文档/5、接口/存客宝对接规范.md
+- 开发文档/5、接口/02-业务对接/存客宝对接规范.md
 - 开发文档/10、项目管理/开发进度总表.md

机擎/阿机/SKILL.md

@@ -41,7 +41,7 @@
 
 | 技能点 | 来源 | 可执行动作 |
 |--------|------|------------|
-| **unified 路由与契约** | 5、接口/接口规范；unified.py | 新增/改 POST /api/v3/* 路由与参数；保持与交互矩阵一致 |
+| **unified 路由与契约** | 5、接口/01-规范与统一层/接口规范；unified.py | 新增/改 POST /api/v3/* 路由与参数；保持与交互矩阵一致 |
 | **WebSocket Hub** | ws_hub.py | 设备连接/断开、心跳、execute 下发、response 匹配、pending_commands |
 | **通道选择** | 2、架构；ws_hub + unified | 官方 API → SDK 控制 → Hook → AI Agent；channel_used 回传 |
 | **Frida Hook 通道** | sdk/agent/hook/ | FridaManager 连接管理、wechat_hook_v2.js 脚本、RPC 调用、WCDB 适配 |
@@ -50,7 +50,7 @@
 | **发消息超时** | config.py MESSAGE_SEND_TIMEOUT | 默认 60s；超时返回 200 + success=false + error=timeout |
 | **设备端 Agent** | agent.py、skill_executor.py | execute → _execute_skill(script, action, params)；心跳 --heartbeat 可配 |
 | **设备端 Skill** | sdk/agent/skills/ | 实现 action：send_message、get_messages、add_friend 等 |
-| **联调契约** | 5、接口/接口规范 §1.5 | 下发 execute{script,action,params}；设备回 response{command_id,code,message,data} |
+| **联调契约** | 5、接口/01-规范与统一层/接口规范 §1.5 | 下发 execute{script,action,params}；设备回 response{command_id,code,message,data} |
 | **状态检查** | check_system.sh | adb devices；curl localhost:8899/health；devices_online |
 | **启动命令** | SDK操作手册 | cd sdk && ./scripts/start_sdk.sh；Agent：agent.py -d <device_id> -s ws://127.0.0.1:8899/ws/device |
 

机擎/阿桥/SKILL.md

@@ -97,8 +97,8 @@
 | 存客宝配置 | cunkebao_v3/Server/config/workphone.php |
 | 设备端 | sdk/agent/agent.py、sdk/agent/skills/{wechat,douyin,xhs,xianyu}/ |
 | 交互矩阵 | 机擎/references/业务-服务端-设备端交互矩阵.md |
-| 对接规范 | 开发文档/5、接口/存客宝对接规范.md |
-| 接口规范 | 开发文档/5、接口/接口规范.md |
+| 对接规范 | 开发文档/5、接口/02-业务对接/存客宝对接规范.md |
+| 接口规范 | 开发文档/5、接口/01-规范与统一层/接口规范.md |
 | 中间层进度 | 开发文档/10、项目管理/多端并行开发模块拆解.md § 三 |
 | 中间层抽象 | 机擎/references/工作手机中间层抽象.md |
 

机擎/阿表/开发文档结构规范/SKILL.md

@@ -51,6 +51,21 @@ version: 1.0.0
 └── 05-规范/              # 架构图风格标准.md
 ```
 
+## 二B、`5、接口` 标准树（2026-05-24 起）
+
+```text
+开发文档/5、接口/
+├── README.md
+├── images/
+├── 01-规范与统一层/      # 接口规范.md + 通用服务交互层.md
+├── 02-业务对接/          # 存客宝 + 外部网关
+├── 03-Hook与微信/        # Hook模块 + 微信矩阵 + Frida 跳转
+├── 04-OpenAPI/           # openapi_v3.0.json
+└── 05-交互图/            # API架构 HTML
+```
+
+**接口文档归类**：规范/统一层 → 01；对接方文档 → 02；Hook/微信 → 03；JSON → 04；HTML → 05。
+
 ### 新架构资产归类决策树
 
 ```text

资料/XESlciw与Frida及机擎详细对比分析.md

@@ -349,6 +349,6 @@
 | XESlciw 接口与 Hook 手册 | `资料/XESlciw接口与设备Hook开发手册.md` |
 | XESlciw 详解与技术方案对比 | `资料/XESlciw详解与工作手机技术方案对比.md` |
 | 系统架构 | `开发文档/2、架构/01-总览/系统架构.md` |
-| 接口规范 | `开发文档/5、接口/接口规范.md` |
+| 接口规范 | `开发文档/5、接口/01-规范与统一层/接口规范.md` |
 | Frida 官方文档 | https://frida.re/docs/javascript-api/ |
 | LSPosed Native Hook | https://github.com/LSPosed/LSPosed/wiki/Native-Hook |

资料/奥创微信控制接口与插件提取复用指南.md

@@ -327,4 +327,4 @@ batch_send_message
 | XESlciw 接口手册 | 资料/XESlciw接口与设备Hook开发手册.md |
 | XESlciw 详解 | 资料/XESlciw详解与工作手机技术方案对比.md |
 | 机擎架构 | 开发文档/2、架构/01-总览/系统架构.md |
-| 机擎接口规范 | 开发文档/5、接口/接口规范.md |
+| 机擎接口规范 | 开发文档/5、接口/01-规范与统一层/接口规范.md |