docs: doc/ 全量同步 dev 现状——API 目录补全(AI 控制台/系统备份/自动发现等)、去 STF 过时口径、补 generic_steps 与配置键速查；确立「功能/配置改动须同步文档」红线

- doc/API.md:补方法/路径标题,权限分层修正,新增 AI 控制台(/api/agent/*)、系统备份(/api/system/backup/*)、设备自动发现(/api/devices/discovery/*)、tap_text/summary/health/devices-apps 等整节端点,去 STF 残留
- doc/TASK_DEV.md:STF 时代描述清理;新增 §2.10 generic_steps(18 节点与必填/嵌套/静默跳过语义)、§2.11 自定义动作与单步测试、/api/jobs 盲存校验语义、resolve_serials/抢占语义、模板构造函数签名修正
- doc/DEPLOY.md:数据备份改为推荐「系统→数据备份」功能并说明重启生效目录,端口表 STF7100→MCP8033,补 start.sh 生产链路与 MCP_PLATFORM_PASS 同步,故障排查去 STF
- doc/MCP.md:加「现状边界」(平台级任务 CRUD 未 MCP 化,规划见 AI_TASK_GEN §9),busy/平台会话说明,MCP_ALLOWED_SERIALS 语义纠正
- doc/MCP_DESIGN.md:加实现现状对照、错误码、独立容器改演进备选、里程碑状态、API 映射表按实现重写
- doc/ARCHITECTURE.md:Tab/子分栏/线程模型/数据表/蓝图表去 STF,补 device_discovery/agent/system_backup/经验巡检等
- doc/DEVELOPMENT.md:新增 §5.6「改动必须同步文档」红线、§2.3 配置键速查、蓝图化新增 API 流程、文档索引补登记
- doc/STF_REMOVAL.md:加历史记录状态横幅
- doc/AI_TASK_GEN.md:新增 AI 建任务设计稿(含 §9 需转 MCP 工具分层)

doc/MCP.md

@@ -30,16 +30,20 @@ Android 设备（IP:5555）
 | 环境变量 | 默认 | 说明 |
 |---|---|---|
 | `MCP_PLATFORM_URL` | `http://127.0.0.1:18050` | 平台地址（Agent 与平台同机时用本机） |
-| `MCP_PLATFORM_USER` / `MCP_PLATFORM_PASS` | `admin` / 空 | 平台登录账号 |
+| `MCP_PLATFORM_USER` / `MCP_PLATFORM_PASS` | `admin` / start.sh 兜底 `admin123`（手动直跑时默认空） | 平台登录账号 |
 | `MCP_ALLOW_WRITE` | `0` | **写门控**：=1 才允许点击/输入/开关 App 等写操作（只读工具不受限） |
-| `MCP_ALLOWED_SERIALS` | 空=不限 | 设备白名单（逗号分隔），非空时只允许列出的 serial |
+| `MCP_ALLOWED_SERIALS` | 空 | 设备白名单（逗号分隔）：**非空=只允许列出的 serial**；为空时代码只校验 serial 非空、**不校验是否在平台设备池内**（设计稿语义未实现） |
 | `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `0.0.0.0` / `8033` | 监听地址 |
 | `MCP_SCREENSHOT_WIDTH` | `540` | 截图返回宽度上限（px），模型看到的图即该坐标系 |
 | `MCP_JPEG_QUALITY` | `70` | 截图 JPEG 质量 |
 | `MCP_AUDIT_FILE` | `/var/log/mcp/audit.log` | 审计日志（每次工具调用一行） |
 | `MCP_PLATFORM_TIMEOUT` | `30` | 平台请求超时（秒） |
 
-生产（220 容器）已设 `MCP_ALLOW_WRITE=1`；`MCP_ALLOWED_SERIALS` 未设（= 平台设备池内可操作）。
+生产（220 容器）已设 `MCP_ALLOW_WRITE=1`；`MCP_ALLOWED_SERIALS` 未设（= 代码只校验 serial 非空，**不限制到平台设备池内**；如需收紧请配置白名单）。
+
+> **MCP_ENABLED**：由 `scripts/start.sh` 消费（默认 `1`，=0 可关掉后台拉起的 MCP）。
+> **MCP_PLATFORM_PASS**：start.sh 兜底 `admin123`——改过平台 admin 密码必须同步该变量，否则 MCP 登录平台失败。
+> **supervise.sh 不拉起 MCP**：只守护 web_server；容器场景 MCP 由 start.sh 后台拉起（见 DEPLOY §2.4）。
 
 ## 坐标空间（重要约定）
 
@@ -91,15 +95,30 @@ Android 设备（IP:5555）
 | `de_open_app(serial, package)` | 打开 App（adb monkey 直启，无需知道 activity——最快的打开路径） |
 | `de_stop_app(serial, package)` | 强制停止 App（am force-stop） |
 | `de_list_apps(serial, keyword="")` | 列出第三方已装应用（pm list packages -3），keyword 可过滤（如 "douyin"） |
+
+> 上表三个工具走 `direct_ops` 轻量 **adb 直连**（monkey / am force-stop / pm list packages），不建 u2 会话。
+
+### 亮屏与熄屏（平台 screen_all 通道）
+
+| 工具 | 用途 |
+|---|---|
 | `de_sleep(serial)` | 熄屏（**运行中任务会中断，慎用**） |
 | `de_wake(serial)` | 亮屏并解锁（熄屏时先调它再截图） |
 
+> `de_sleep`/`de_wake` 走平台 `POST /api/device/screen_all`（`platform_client`），同样不在 MCP 进程内建 u2 会话。
+
 ### 平台联动
 
 | 工具 | 用途 |
 |---|---|
 | `de_list_tasks()` | 列出平台任务计划（名称/类型/启用/调度），了解已自动化的工作 |
 
+### 现状边界
+
+本 Server 目前只有**设备层**的 `de_*`（控制/感知/只读）+ 平台**只读**的 `de_list_tasks`；平台级**任务增改/提交/CRUD、分组/设备池/自定义动作/APK/备份**等 REST 路由只给 Web 前端用，**未暴露 MCP 工具**。
+
+补齐分层规划见 [AI_TASK_GEN.md](AI_TASK_GEN.md) §9。**每新增/修改/删除一个 MCP 工具或平台配置，必须同步更新本手册与 [MCP_DESIGN.md](MCP_DESIGN.md)（doc 同步红线）**。
+
 ## 推荐使用模式（操作手机的正确姿势）
 
 1. **`de_list_devices`** 确认目标设备在线
@@ -116,7 +135,9 @@ Android 设备（IP:5555）
 ## 安全与审计
 
 - **写门控**：`MCP_ALLOW_WRITE=0`（默认）时点击/输入/开关 App 全部拒绝，只读工具可用
-- **设备白名单**：`MCP_ALLOWED_SERIALS` 非空时限制可操作的 serial
+- **任务占用互斥**：写工具操作前调 `_ensure_device_free` 检查设备 `worker_status`，running/connecting 直接拒 `device_busy`（只读工具不受限），AI 不与任务抢设备
+- **平台会话 + CSRF**：平台登录与会话由 `platform_client` 内部处理（`MCP_PLATFORM_USER/PASS` 登录拿 cookie、失效自动重登；POST 自动带 `X-CSRF-Token`），不向客户端暴露平台凭据
+- **设备白名单**：`MCP_ALLOWED_SERIALS` 非空时限制可操作的 serial；空名单时代码只校验 serial 非空，不按平台设备池过滤
 - **审计日志**：每次调用记录 `{ts, tool, serial, args, result}` 到 `MCP_AUDIT_FILE`（220 上 `/tmp/mcp_audit.log`）
 - 操作对象限定平台设备池；`adb kill-server` / `adb disconnect` 属项目红线，任何工具不触碰