butubb
bf5071b14d
按 git 红线撤回：该功能未经 dev 验收就被合并进 main（是我提交时没切分支、
又把自己的自测当成了用户验收）—— main 必须保持"已验收可部署"的状态。
功能本身没问题，代码仍在 **dev**（dad1af8）与 feature 分支上，等设备端 Agent
写出来、端到端验收通过后，再从 dev 合并回 main。
main 内容已回到 66632bb（git diff 66632bb HEAD 为空）。
65 lines
5.1 KiB
Markdown
65 lines
5.1 KiB
Markdown
# auto_control 文档总索引
|
||
|
||
本目录是 `auto_control`（Android 多设备自动化任务平台）的**唯一权威文档源**。代码即事实，文档与代码不一致时以代码为准，并**顺手把文档改对**（见文末维护约定）。
|
||
|
||
> 项目名称统一为 **auto_control**（历史文档里出现过的 `platform-tools` 均为旧名，已全部改名）。
|
||
|
||
---
|
||
|
||
## 1. 文档地图
|
||
|
||
| 文档 | 内容 | 主要读者 |
|
||
|------|------|---------|
|
||
| [ARCHITECTURE.md](ARCHITECTURE.md) | **架构详解**：分层、启动装配顺序、线程与并发模型、设备生命周期、任务调度链路、状态机、关键设计决策与扩展点 | 所有开发者（先读这篇） |
|
||
| [DATA_MODEL.md](DATA_MODEL.md) | **数据模型**：SQLite 表与字段、schema 迁移、非模型表、`app_meta` 配置键、数据目录、备份覆盖清单 | 后端开发、运维 |
|
||
| [API.md](API.md) | **HTTP 接口全量**：按蓝图分组的路由表、鉴权、请求/响应示例、非 JSON 响应、错误分支 | 前端开发、外部接入 |
|
||
| [TASK_DEV.md](TASK_DEV.md) | **任务与步骤开发**：TaskType/TaskJob 概念、18 种步骤全表、选择器与定位、自定义动作、新增任务类型模板 | 写任务的开发 |
|
||
| [MCP.md](MCP.md) | **MCP 手机控制手册**：19 个 `de_*` 工具用法、写操作门控、坐标换算、接入示例 | 接入方、数字员工 |
|
||
| [MCP_DESIGN.md](MCP_DESIGN.md) | **MCP 设计文档**：边界划分、错误码、白名单/审计设计、演进方向 | 平台开发者 |
|
||
| [AI_CONSOLE.md](AI_CONSOLE.md) | **AI 控制台**：会话/SSE、经验库、动作库、巡检、Markdown 渲染、推理链、token 统计 | 使用者、平台开发者 |
|
||
| [AI_TASK_GEN.md](AI_TASK_GEN.md) | **AI 建任务**：设计稿与里程碑（P0 未实现，属规划） | 平台开发者 |
|
||
| [DEPLOY.md](DEPLOY.md) | **部署与运维**：环境准备、生产容器、数据备份导出/导入、故障排查 | 运维、部署者 |
|
||
| [DEVELOPMENT.md](DEVELOPMENT.md) | **开发手册**：git 流程、技术红线、本地开发与调试、常见开发任务、文档同步约定 | 所有开发者 |
|
||
| [STF_REMOVAL.md](STF_REMOVAL.md) | **历史记录**：摘除 OpenSTF 的迁移过程（阶段 0-3） | 追溯背景时参考 |
|
||
| [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) | 给 StaffDeck 数字员工的知识库（MCP 接入/工具/约定/红线） | 外部 AI 接入方 |
|
||
| [staffdeck/JOB_SPEC.md](staffdeck/JOB_SPEC.md) | 数字员工岗位说明（岗位描述/看板摘要/执行约束） | 外部 AI 接入方 |
|
||
| [backlog/TODO.md](backlog/TODO.md) | 已确认但暂缓的待办（含已知问题） | 所有开发者 |
|
||
|
||
项目根目录的 [README.md](../README.md) 是**项目总览与快速上手**（面向第一次接触项目的人），细节都在本目录。
|
||
|
||
---
|
||
|
||
## 2. 推荐的阅读路径
|
||
|
||
| 你的目的 | 按顺序读 |
|
||
|---------|---------|
|
||
| **第一次接触项目** | 根 [README.md](../README.md) → [ARCHITECTURE.md](ARCHITECTURE.md) → [DATA_MODEL.md](DATA_MODEL.md) |
|
||
| **搭环境跑起来** | 根 [README.md](../README.md) 的「快速上手」→ [DEPLOY.md](DEPLOY.md) |
|
||
| **写/改任务** | [TASK_DEV.md](TASK_DEV.md) → [ARCHITECTURE.md](ARCHITECTURE.md) §任务调度 |
|
||
| **改后端/前端** | [DEVELOPMENT.md](DEVELOPMENT.md)（流程+红线+本地开发）→ [ARCHITECTURE.md](ARCHITECTURE.md) → [API.md](API.md) |
|
||
| **对外提供手机控制** | [MCP.md](MCP.md) → [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) |
|
||
| **排故障** | [DEPLOY.md](DEPLOY.md) §故障排查 → [DEVELOPMENT.md](DEVELOPMENT.md) §调试 |
|
||
|
||
---
|
||
|
||
## 3. 文档维护约定（红线）
|
||
|
||
> 与「doc 同步红线」一致：**任何功能/配置/接口/表结构的增删改，必须在同一个 commit 里同步更新对应文档。**
|
||
|
||
| 改动类型 | 必须同步的文档 |
|
||
|---------|--------------|
|
||
| HTTP 接口（新增/改参数/改返回/改鉴权） | [API.md](API.md) |
|
||
| 数据库表/字段/迁移 | [DATA_MODEL.md](DATA_MODEL.md) + [ARCHITECTURE.md](ARCHITECTURE.md) |
|
||
| **新增持久化表** | 还要登记进 `core/system_backup.py` 的 `SUMMARY_TABLES` + [DEPLOY.md](DEPLOY.md) §3.5（**备份覆盖红线**） |
|
||
| `config.py` / `.env` 键 | [DEVELOPMENT.md](DEVELOPMENT.md) 配置速查 + [DEPLOY.md](DEPLOY.md) + `.env.example` |
|
||
| 页面 Tab / 子分栏 / 前端 JS 拆分 | [ARCHITECTURE.md](ARCHITECTURE.md) §前端 + [DEVELOPMENT.md](DEVELOPMENT.md) |
|
||
| 任务类型 / 步骤 schema | [TASK_DEV.md](TASK_DEV.md) |
|
||
| 常驻线程 / 进程装配 | [ARCHITECTURE.md](ARCHITECTURE.md) §线程与并发 |
|
||
| MCP 工具 | [MCP.md](MCP.md) + [MCP_DESIGN.md](MCP_DESIGN.md) |
|
||
| 对外接入约定 | [staffdeck/KNOWLEDGE_BASE.md](staffdeck/KNOWLEDGE_BASE.md) |
|
||
| 暂缓项 / 已知问题 | [backlog/TODO.md](backlog/TODO.md)（完成时移出并同步相关文档） |
|
||
|
||
**新增文档时**：在本文 §1 表格里登记一行，并在根 README 的「更多文档」里加链接——否则等于没写。
|
||
|
||
**历史文档不追改**：[STF_REMOVAL.md](STF_REMOVAL.md) 是迁移阶段的历史记录，只增不改，不随现状改写。
|