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/DEVELOPMENT.md

@@ -43,7 +43,7 @@
 |------|------|------|
 | 开发机 | 本机（192.168.20.57） | `.venv` + 本地运行 `web_server.py` |
 | 生产机 | 部署机 220 的 `auto_control` | python-app 容器，`network_mode: host` |
-| STF 服务 | ~~`192.168.20.220:7100`~~ | 已停用（2026-08-18 `docker stop stf`，代码已摘除依赖） |
+| STF 服务 | ~~`192.168.20.220:7100`~~ | 已停用（代码已摘除依赖）。注意：此处"已停用"与 [STF_REMOVAL.md](STF_REMOVAL.md) 的"待人工确认"项矛盾（220 侧是否已 `docker stop stf` 未核实），需以 220 实际为准 |
 | adb 容器 | 220 上 `adb`（host 网络 5037） | USB 设备远程 adb server；网络设备补连用 |
 | 设备 | Tailscale `100.100.10.x:5555` | Xiaomi 舰队，本机 `100.100.10.2` 在 tailnet 内 |
 | uiautodev | 本机 `20242` | 元素抓取服务（web_server 自动拉起） |
@@ -62,6 +62,22 @@
 - 本机已在 tailnet 内，直连可靠且快（<1s）
 - 设备加入/退出平台：工具 → 设备池管理（SQLite 清单，自动连接 + 型号采集）
 
+### 2.3 配置键速查（`config.py` / `.env`）
+
+`.env` 加载方式：项目根目录逐行解析、`os.environ.setdefault`（环境变量已设则不覆盖）。以下默认值以 `config.py` 为准：
+
+| 键 | 默认值 | 说明 |
+|------|------|------|
+| `WEB_HOST` / `WEB_PORT` | `0.0.0.0` / `18050` | Web 后台监听（18050 避开 Windows 动态端口范围） |
+| `DATA_DIR` / `APK_DIR` | `data/` / `data/apks/` | 持久化数据目录 / APK 存储目录 |
+| `BACKUP_DIR` / `RESTORE_STAGING_DIR` / `RESTORE_PENDING_DIR` | `data/backups` / `data/restore_staging` / `data/restore_pending` | 系统备份：导出 zip、导入暂存、待重启生效的恢复目录 |
+| `ADB_PATH` | `bin/adb/adb`（Windows 为 `adb.exe`） | 按平台自动识别，代码只拼路径 |
+| `USB_ADB_HOST` / `USB_ADB_PORT` | `100.100.10.1` / `5037` | 220 的 adb 容器（host 网络），驱动远程 USB 设备 |
+| `DISCOVERY_PORT` / `DISCOVERY_SUBNETS` / `DISCOVERY_INTERVAL` | `5555` / 局域网+Tailscale 网段 / `60` | 设备自动发现；可在工具页设备池面板改，存 `app_meta` `discovery_*` 覆盖默认 |
+| `TAILSCALE_API_KEY` / `TAILSCALE_TAILNET` | 空 / 空 | 工具页 Tailscale 管理（官方 API v2） |
+| `WEB_SECRET_KEY` | 未配置则随机生成 | 会话密钥（web_server 读 `.env`；不配则重启登录态失效） |
+| `STF_URL` / `STF_TOKEN` / `STF_SSH_*` | 废弃 | STF 摘除后仅历史保留，代码不再使用 |
+
 ---
 
 ## 3. 技术红线（开发限制）—— 违反会打断共享 adb transport，需人工恢复
@@ -92,7 +108,7 @@
 - **任务参数放各自 `tasks/<app>/task.py` 顶部，不放 `config.py`**
 - **生产环境（220）默认只读**：任何写操作（改文件/重启容器/部署）都必须先经负责人确认
 - **数据库是 SQLite**（`data/users.db`，WAL 模式）：运行时数据不提交 git
-- **前端 JS 在 `static/admin/monitor.js`**（已从 HTML 拆分），HTML 里用 `<script src>` 引用
+- **前端 JS 已拆分多文件**（均位于 `static/admin/`）：`monitor.html` 按 `base.js → list.js → monitor.js → editor.js → tasks.js → tools.js → apps.js → admin.js → agent.js → system.js` 的顺序用 `<script src>` 加载
 - **监控页/大列表已加分页**：100 台设备也只渲染 10 行/页，不要移除分页逻辑
 - **任务批量触发已错峰**（`_START_STAGGER_SEC`）：避免大量设备同时启动造成 adb 连接风暴，不要移除
 
@@ -153,7 +169,7 @@ with sync_playwright() as p:
 
 - **看日志**：`logs/` 下 `core.log` / `task.log` / `web.log` / `action.log`（10MB 滚动，保留 5 份）
 - **看设备/任务状态**：浏览器监控页，或 `GET /api/status`、`GET /api/health`
-- **清理 STF 残留占用**：前端监控页"强制释放占用"（或 `.env` 配 `AUTO_RELEASE_STALE_OCCUPY=true` 启动自动清理）
+- **停止设备/清异常**：监控页工具条用"停止全部 / 停止选中 / 清除全部异常"（`AUTO_RELEASE_STALE_OCCUPY` 等 STF occupy 残留清理配置代码已不再读取）；崩溃残留的 worker 状态重启即清零
 - **打包项目**：`python scripts/pack.py`
 
 ---
@@ -180,18 +196,41 @@ tasks/<app>/
 | 文件 | 内容 |
 |------|------|
 | `templates/admin/monitor.html` | HTML 结构 + CSS + `<script src>` 引用 |
-| `static/admin/monitor.js` | 全部前端 JS |
+| `static/admin/`（base/list/monitor/editor/tasks/tools/apps/admin/agent/system.js） | 前端 JS（按 monitor.html 中 `<script src>` 顺序拆分加载，功能归属见各文件） |
 
 改完**强刷浏览器**（Cmd/Ctrl+Shift+R），必要时重启 web_server。
 
 ### 5.4 新增 API
 
-在 `web_server.py` 加 Flask 路由，更新 **[doc/API.md](API.md)**。
+路由按功能域放在 `web/` 蓝图包（`web/__init__.py` 的 `register_blueprints(app)` 统一注册 10 个蓝图：auth / monitor / tasks / admin / tools / devices / apks / tailscale / agent / system）。
+
+- 新增 API：在对应功能域的 `web/xxx_api.py` 里加 `@bp.route(...)` + 权限装饰器（如 `admin_required`）
+- 新建蓝图：需在 `web/__init__.py` 里 import 并加进 `register_blueprints` 的注册元组
+- `web_server.py` 只做 app 装配（初始化、`register_blueprints(app)`、常驻线程启动），一般不改
+- 最后更新 **[doc/API.md](API.md)**
 
 ### 5.5 新增数据库字段/表
 
-- 模型改 `core/models.py`，首次建表用 `create_all()`
+- 模型改 `core/models.py`，首次建表用 `create_all()`；SQLAlchemy 模型未写 `__tablename__` 时默认表名 = 小写类名
 - **已有数据的老库**：在 `core/models.py` 的 `SCHEMA_MIGRATIONS` 里加迁移（版本号递增 + SQL）
+- `app_meta`（KV 配置表）由 `core/models.py` 的 `_migrate_schema()` 建表并维护 `schema_version`
+- `agent_conversation` / `agent_experience` / `experience_audit` 由 `web/agent_api.py` 顶部的原生 `CREATE TABLE IF NOT EXISTS` 幂等创建（模块内首次用时执行），**不经 `SCHEMA_MIGRATIONS`，无版本管理**
+
+### 5.6 改动必须同步文档
+
+任何功能/配置/接口/页面改动，须与代码同一 commit 同步更新对应文档：
+
+| 改动类型 | 对应文档 |
+|------|------|
+| HTTP 接口 | [API.md](API.md) |
+| 数据表 / schema | [ARCHITECTURE.md](ARCHITECTURE.md) §3.6 |
+| `config.py` / `.env` 键增删 | 本文档 §2 + [.env.example](../.env.example) |
+| 页面 Tab / 子分栏 / 前端拆分 | [ARCHITECTURE.md](ARCHITECTURE.md) §5 |
+| 任务 / 步骤 | [TASK_DEV.md](TASK_DEV.md) |
+| 常驻线程 / 进程与装配 | [ARCHITECTURE.md](ARCHITECTURE.md) §7 |
+| MCP 工具 | [MCP.md](MCP.md) 与 [MCP_DESIGN.md](MCP_DESIGN.md) |
+
+注：STF_REMOVAL.md 是历史迁移记录，不改写。
 
 ---
 
@@ -218,3 +257,7 @@ tasks/<app>/
 | [ARCHITECTURE.md](ARCHITECTURE.md) | 架构详解（分层、数据流、设计决策） |
 | [API.md](API.md) | 全部 HTTP 接口说明 |
 | [DEPLOY.md](DEPLOY.md) | 部署指南（环境、生产、故障排查） |
+| [STF_REMOVAL.md](STF_REMOVAL.md) | 摘除 STF 的历史迁移记录（2026-08，不随现状改写） |
+| [MCP.md](MCP.md) | MCP 手机控制使用手册（工具清单/用法） |
+| [MCP_DESIGN.md](MCP_DESIGN.md) | MCP 架构与演进设计 |
+| [AI_TASK_GEN.md](AI_TASK_GEN.md) | AI 建任务设计文档 |