diff --git a/README.md b/README.md
index b1ba8cb..5101cba 100644
--- a/README.md
+++ b/README.md
@@ -113,7 +113,8 @@ platform-tools/
 │   └── login.html               #   登录页
 │
 ├── static/admin/
-│   └── custom.css               # 自定义样式
+│   ├── custom.css               # 自定义样式
+│   └── monitor.js               # 前端 JS（已从 monitor.html 拆分）
 │
 ├── data/                        # 运行时数据
 │   ├── users.db                 #   SQLite（用户/分组/任务/自定义动作/APK记录）
@@ -306,7 +307,7 @@ self.set_progress(done=5, total=80, unit="视频",
 
 ### 新增 App 任务
 
-参照 `tasks/douyin/` 结构，6 步即可新增一个 App 任务，详见 [doc/TASK_DEV.md](file:///d:/platform-tools/doc/TASK_DEV.md)。
+参照 `tasks/douyin/` 结构，6 步即可新增一个 App 任务，详见 [doc/TASK_DEV.md](doc/TASK_DEV.md)。
 
 ---
 
@@ -406,10 +407,13 @@ finally:
 
 | 文档 | 内容 |
 |------|------|
-| [doc/TASK_DEV.md](file:///d:/platform-tools/doc/TASK_DEV.md) | 任务开发指南（新增 App 任务的完整模板和规范） |
-| [doc/ARCHITECTURE.md](file:///d:/platform-tools/doc/ARCHITECTURE.md) | 架构详解（分层设计、数据流、关键设计决策） |
-| [doc/DEPLOY.md](file:///d:/platform-tools/doc/DEPLOY.md) | 部署指南（环境准备、STF 配置、生产部署） |
-| [doc/API.md](file:///d:/platform-tools/doc/API.md) | API 接口文档（全部 HTTP 接口说明） |
+| [doc/DEVELOPMENT.md](doc/DEVELOPMENT.md) | **开发手册**：开发流程、git 工作流、技术红线、环境、本地开发 |
+| [doc/TASK_DEV.md](doc/TASK_DEV.md) | 任务开发指南（新增 App 任务的完整模板和规范） |
+| [doc/ARCHITECTURE.md](doc/ARCHITECTURE.md) | 架构详解（分层设计、数据流、关键设计决策） |
+| [doc/DEPLOY.md](doc/DEPLOY.md) | 部署指南（环境准备、STF 配置、生产部署） |
+| [doc/API.md](doc/API.md) | API 接口文档（全部 HTTP 接口说明） |
+
+> **注意**：所有 git 操作（含 push 到 dev）都需负责人确认后才能执行，详见开发手册。修改 `core/`、`tasks/`、`templates/` 后需重启服务/强刷浏览器才生效。
 
 ---
 
diff --git a/doc/DEVELOPMENT.md b/doc/DEVELOPMENT.md
new file mode 100644
index 0000000..43b9373
--- /dev/null
+++ b/doc/DEVELOPMENT.md
@@ -0,0 +1,218 @@
+# 开发手册（DEVELOPMENT）
+
+面向本项目开发者：开发流程、git 工作流、环境说明、技术红线、本地开发、常见开发任务。
+
+---
+
+## 1. 开发流程与 git 工作流
+
+### 1.1 分支策略
+
+| 分支 | 用途 |
+|------|------|
+| `dev` | **开发分支**，所有新功能/修复都在这里开发 |
+| `main` | **生产分支**（主分支），只放已确认的稳定版本 |
+
+生产环境 = STF 主机 `192.168.20.220` 的 `/mnt/data/openstf/auto_control`（python-app 容器运行 `web_server.py`）。
+
+### 1.2 git 操作铁律（重要）
+
+**所有 git 操作都必须先经项目负责人明确确认后才能执行**，包括但不限于：
+
+- `commit` / `push`（**即使 push 到 dev 也要确认**）
+- `merge`（dev → main）
+- `revert` / `checkout` / `reset` / `branch -D` 等
+
+**标准流程：**
+
+```
+1. 在 dev 分支开发、本地测试
+2. 完成改动 → 把改动清单 + 建议 commit 信息 列给负责人
+3. 负责人确认 → 才能 commit + push dev
+4. 需要发布 → 负责人确认后再合并到 main
+5. 部署生产 → 负责人明确指示后才 pull 到 220
+```
+
+> 不允许"开发完顺手就 commit/push"。即使是一次性小改动，也要先确认。
+
+---
+
+## 2. 环境说明
+
+| 环境 | 位置 | 说明 |
+|------|------|------|
+| 开发机 | 本机（192.168.20.57） | `.venv` + 本地运行 `web_server.py` |
+| 生产机 | STF 主机 220 的 `auto_control` | python-app 容器，`network_mode: host` |
+| STF 服务 | `192.168.20.220:7100` | 设备农场（REST API） |
+| 设备 | Tailscale `100.100.10.x:5555` | 5 台 Xiaomi，本机 `100.100.10.2` 在 tailnet 内 |
+| uiautodev | 本机 `20242` | 元素抓取服务（web_server 自动拉起） |
+
+### 2.1 adb key（关键）
+
+- 本机 `~/.android/adbkey` 已换成 **STF adb 容器的 key**（5 台设备都信任）
+- **不要随意更换 key**——设备会变 unauthorized 连不上
+- 旧 key 备份在 `~/.android/adbkey.local.bak`
+- 生产环境的容器也需要用这把 key（部署时处理）
+
+### 2.2 设备连接方式
+
+- 设备 serial 是 `IP:5555`（Tailscale 地址），**直连**优先
+- STF 桥接（remoteConnect）在此环境**不可用**（隧道 adb key 认证失败，显示 unauthorized）
+- 本机已在 tailnet 内，直连可靠且快（<1s）
+
+---
+
+## 3. 技术红线（开发限制）—— 违反会打断 STF，需人工恢复
+
+这些是踩过坑后总结的，**任何修改都不能引入**。违反任何一条都会导致设备被 STF 误判离线、需人工处理：
+
+1. **绝不 `adb kill-server`**
+   - 会断开所有设备的 adb transport，STF 对全网设备误判离线并触发重连
+   - 见 `core/adb_helper.py`
+
+2. **绝不对 `IP:5555` 设备 `adb disconnect`**
+   - STF provider 共享该地址的 adb transport，disconnect 会断 STF
+   - 直连模式下 `release()` 不 disconnect
+   - 见 `core/device_worker.py` `STFDevice.release()`
+
+3. **空闲设备扫描不主动 connect/disconnect**
+   - STF provider 内部通过 IP:5555 维持连接，外部 connect/disconnect 会让 STF 误判离线
+   - `_ForegroundScanner._scan_free` 对空闲设备直接返回"空闲"，不碰 adb
+   - 见 `core/task_manager.py`
+
+4. **adb key 保持为 STF 容器的 key**（见 2.1）
+
+5. **直连优先，不引入 STF 桥接**（见 2.2）
+
+### 3.1 其他开发限制
+
+- **`web_server.py` 以 `debug=False` 运行，不热重载**：改 `core/`、`tasks/`、`templates/`、`static/` 后必须重启 web_server（前端 HTML 改完强刷浏览器）
+- **任务参数放各自 `tasks/<app>/task.py` 顶部，不放 `config.py`**
+- **生产环境（220）默认只读**：任何写操作（改文件/重启容器/部署）都必须先经负责人确认
+- **数据库是 SQLite**（`data/users.db`，WAL 模式）：运行时数据不提交 git
+- **前端 JS 在 `static/admin/monitor.js`**（已从 HTML 拆分），HTML 里用 `<script src>` 引用
+- **监控页/大列表已加分页**：100 台设备也只渲染 10 行/页，不要移除分页逻辑
+- **任务批量触发已错峰**（`_START_STAGGER_SEC`）：避免大量设备同时启动造成 adb/STF 风暴，不要移除
+
+---
+
+## 4. 本地开发手册
+
+### 4.1 首次安装
+
+```bash
+# 用 Python 3.12 建 venv（README 推荐版本）
+/opt/homebrew/bin/python3.12 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+
+# macOS：adb 用系统自带的（bin/adb/adb 是被 gitignore 的符号链接）
+ln -sf /opt/homebrew/bin/adb bin/adb/adb
+
+# 确认 adb key（必须是 STF 容器的 key，否则设备连不上）
+ls -la ~/.android/adbkey
+```
+
+### 4.2 启动
+
+```bash
+.venv/bin/python web_server.py
+# 访问 http://localhost:18050/  账号 admin/admin123
+```
+
+启动日志看到以下即成功：
+```
+[INFO] [core.worker] 心跳看门狗已启动
+[INFO] [web] 管理后台: http://localhost:18050/ (admin/admin123)
+[INFO] [web] 启动服务: http://localhost:18050/
+```
+
+### 4.3 测试
+
+- **后端逻辑**：直接 `.venv/bin/python -c "..."` 调用（如 `tasks/`、`core/` 的函数）
+- **前端 UI**：Playwright（系统 `python3` 已装），脚本示例见下
+- **浏览器冒烟**：切 6 个 tab、开任务编辑器，确认无 JS 错误
+
+```python
+# Playwright 冒烟示例（python3 运行）
+from playwright.sync_api import sync_playwright
+with sync_playwright() as p:
+    b = p.chromium.launch(headless=True)
+    pg = b.new_page()
+    pg.goto("http://127.0.0.1:18050/login")
+    pg.fill("input[name=username]", "admin")
+    pg.fill("input[name=password]", "admin123")
+    pg.click("input[type=submit], button[type=submit]")
+    pg.wait_for_load_state("networkidle")
+    # ... 检查各 tab、编辑器
+    b.close()
+```
+
+### 4.4 常用调试
+
+- **看日志**：`logs/` 下 `core.log` / `task.log` / `web.log` / `action.log`（10MB 滚动，保留 5 份）
+- **看设备/任务状态**：浏览器监控页，或 `GET /api/status`、`GET /api/health`
+- **清理 STF 残留占用**：`python scripts/cleanup.py`（或前端"强制释放占用"）
+- **打包项目**：`python scripts/pack.py`
+
+---
+
+## 5. 常见开发任务
+
+### 5.1 新增 App 任务
+
+参照 `tasks/douyin/` 结构，详见 **[doc/TASK_DEV.md](TASK_DEV.md)**（6 步模板）。
+
+```
+tasks/<app>/
+  __init__.py     # from . import task
+  task.py         # DEFAULT_PARAMS + Worker + @register_task
+  actions/        # 专属操作（可选）
+```
+
+### 5.2 新增专属操作
+
+在 `tasks/<app>/actions/` 建 `.py`，继承 `BaseAction` + `@register_action(ACTIONS)`，在 `__init__.py` import。
+
+### 5.3 修改前端
+
+| 文件 | 内容 |
+|------|------|
+| `templates/admin/monitor.html` | HTML 结构 + CSS + `<script src>` 引用 |
+| `static/admin/monitor.js` | 全部前端 JS |
+
+改完**强刷浏览器**（Cmd/Ctrl+Shift+R），必要时重启 web_server。
+
+### 5.4 新增 API
+
+在 `web_server.py` 加 Flask 路由，更新 **[doc/API.md](API.md)**。
+
+### 5.5 新增数据库字段/表
+
+- 模型改 `core/models.py`，首次建表用 `create_all()`
+- **已有数据的老库**：在 `core/models.py` 的 `SCHEMA_MIGRATIONS` 里加迁移（版本号递增 + SQL）
+
+---
+
+## 6. 发布流程
+
+详见 **[doc/DEPLOY.md](DEPLOY.md)**。摘要：
+
+1. dev 开发测试完成
+2. 负责人确认 → 合并到 main
+3. 负责人确认 → 生产 220 `git pull`
+4. 重启 python-app 容器生效
+
+**发布前检查**：生产容器 adb key、依赖、数据库迁移。
+
+---
+
+## 7. 文档索引
+
+| 文档 | 内容 |
+|------|------|
+| [README](../README.md) | 项目总览、快速上手 |
+| **[DEVELOPMENT.md](DEVELOPMENT.md)** | 本文档：流程/准则/限制/手册 |
+| [TASK_DEV.md](TASK_DEV.md) | 任务开发指南（新增 App 任务模板） |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | 架构详解（分层、数据流、设计决策） |
+| [API.md](API.md) | 全部 HTTP 接口说明 |
+| [DEPLOY.md](DEPLOY.md) | 部署指南（环境、生产、故障排查） |