butubb/auto_control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2a3775ffd51300f8d2cc9fd160f688aab346588f
auto_control/doc/README.md
T
butubb 24d57d3b96 docs: doc/ 全量重整——按现状重写并建立文档索引；项目统一更名 auto_control 
背景：文档长期落后于代码（Tab 数、任务类型、接口示例等多处与现状不符），
且信息分散重复。这次按当前代码状态逐篇重写，并建立统一的文档体系。

新增
- doc/README.md：文档总索引（文档地图 / 推荐阅读路径 / **文档维护约定**）
- doc/DATA_MODEL.md：数据模型（7 张模型表 + 5 张非模型表、迁移机制、app_meta 键、
  数据目录、备份覆盖清单与双向自检）
- doc/AI_CONSOLE.md：AI 控制台机制（会话与 SSE、经验库/动作库蒸馏与召回、巡检、
  Markdown 渲染、推理链、token 统计、故障排查）

重写（按现状，去掉过时与重复）
- README.md：7 个 Tab、18 种步骤、设备生命周期、调度/窗口语义、常见问题；修掉
  「6 个 Tab / 分组为顶级 Tab」等过时内容与损坏的目录树
- doc/ARCHITECTURE.md：补启动装配顺序（import 期副作用、A~G 七阶段）、线程与锁清单、
  设备状态机、调度全链路、前端结构与实时通道、设计决策、**已知缺陷与踩坑清单**、扩展点
- doc/API.md：按蓝图重建「接口总索引」（107 条路由含鉴权）+ 分域详细说明 +
  非 JSON 响应汇总 + 错误分支速查
- doc/TASK_DEV.md：18 种步骤全表（参数/默认值/语义）、容器与公共参数、
  选择器与 XPath 序号语义、抓取器建议规则、新增任务类型骨架
- doc/DEPLOY.md：容器入口 start.sh 三件事、发布流程与检查清单、备份覆盖红线、
  按现象分类的故障排查
- doc/DEVELOPMENT.md：流程/红线/本地开发/**测试与写测试的约定**/配置速查/文档同步
- doc/MCP.md：19 个工具的参数级清单、坐标空间、写门控三连、安全与审计
- doc/MCP_DESIGN.md、doc/AI_TASK_GEN.md：标注设计 vs 实现现状，补交叉链接
- doc/backlog/TODO.md：新增「已知缺陷」小节（含复现与影响）+ 已完成留档
- .env.example：按代码实际读取的键重写（补 USB/DISCOVERY/MCP/AGENT，删死配置）

其它
- 项目名统一 auto_control：README/文档/scripts/pack.py 产物名；代码内的
  doc 章节引用（templates/admin/monitor.html）同步更新
- 校验：16 篇文档 156 条相对链接全部可解析；文档中的关键数字与代码核对一致
  （19 个 MCP 工具 / 18 种步骤 / 12 张备份表 / 1 种任务类型）
2026-09-10 22:19:18 +08:00

5.1 KiB
Raw Blame History

auto_control 文档总索引

本目录是 auto_control（Android 多设备自动化任务平台）的唯一权威文档源。代码即事实，文档与代码不一致时以代码为准，并顺手把文档改对（见文末维护约定）。

项目名称统一为 auto_control（历史文档里出现过的 platform-tools 均为旧名，已全部改名）。

1. 文档地图

文档 内容 主要读者
ARCHITECTURE.md 架构详解：分层、启动装配顺序、线程与并发模型、设备生命周期、任务调度链路、状态机、关键设计决策与扩展点 所有开发者（先读这篇）
DATA_MODEL.md 数据模型：SQLite 表与字段、schema 迁移、非模型表、app_meta 配置键、数据目录、备份覆盖清单 后端开发、运维
API.md HTTP 接口全量：按蓝图分组的路由表、鉴权、请求/响应示例、非 JSON 响应、错误分支 前端开发、外部接入
TASK_DEV.md 任务与步骤开发：TaskType/TaskJob 概念、18 种步骤全表、选择器与定位、自定义动作、新增任务类型模板 写任务的开发
MCP.md MCP 手机控制手册：19 个 de_* 工具用法、写操作门控、坐标换算、接入示例 接入方、数字员工
MCP_DESIGN.md MCP 设计文档：边界划分、错误码、白名单/审计设计、演进方向 平台开发者
AI_CONSOLE.md AI 控制台：会话/SSE、经验库、动作库、巡检、Markdown 渲染、推理链、token 统计 使用者、平台开发者
AI_TASK_GEN.md AI 建任务：设计稿与里程碑（P0 未实现，属规划） 平台开发者
DEPLOY.md 部署与运维：环境准备、生产容器、数据备份导出/导入、故障排查 运维、部署者
DEVELOPMENT.md 开发手册：git 流程、技术红线、本地开发与调试、常见开发任务、文档同步约定 所有开发者
STF_REMOVAL.md 历史记录：摘除 OpenSTF 的迁移过程（阶段 0-3） 追溯背景时参考
staffdeck/KNOWLEDGE_BASE.md 给 StaffDeck 数字员工的知识库（MCP 接入/工具/约定/红线） 外部 AI 接入方
staffdeck/JOB_SPEC.md 数字员工岗位说明（岗位描述/看板摘要/执行约束） 外部 AI 接入方
backlog/TODO.md 已确认但暂缓的待办（含已知问题） 所有开发者

项目根目录的 README.md 是项目总览与快速上手（面向第一次接触项目的人），细节都在本目录。

2. 推荐的阅读路径

你的目的 按顺序读
第一次接触项目 根 README.md → ARCHITECTURE.md → DATA_MODEL.md
搭环境跑起来 根 README.md 的「快速上手」→ DEPLOY.md
写/改任务 TASK_DEV.md → ARCHITECTURE.md §任务调度
改后端/前端 DEVELOPMENT.md（流程+红线+本地开发）→ ARCHITECTURE.md → API.md
对外提供手机控制 MCP.md → staffdeck/KNOWLEDGE_BASE.md
排故障 DEPLOY.md §故障排查 → DEVELOPMENT.md §调试

3. 文档维护约定（红线）

与「doc 同步红线」一致：任何功能/配置/接口/表结构的增删改，必须在同一个 commit 里同步更新对应文档。

改动类型 必须同步的文档
HTTP 接口（新增/改参数/改返回/改鉴权） API.md
数据库表/字段/迁移 DATA_MODEL.md + ARCHITECTURE.md
新增持久化表 还要登记进 core/system_backup.py 的 SUMMARY_TABLES + DEPLOY.md §3.5（备份覆盖红线）
config.py / .env 键 DEVELOPMENT.md 配置速查 + DEPLOY.md + .env.example
页面 Tab / 子分栏 / 前端 JS 拆分 ARCHITECTURE.md §前端 + DEVELOPMENT.md
任务类型 / 步骤 schema TASK_DEV.md
常驻线程 / 进程装配 ARCHITECTURE.md §线程与并发
MCP 工具 MCP.md + MCP_DESIGN.md
对外接入约定 staffdeck/KNOWLEDGE_BASE.md
暂缓项 / 已知问题 backlog/TODO.md（完成时移出并同步相关文档）

新增文档时：在本文 §1 表格里登记一行，并在根 README 的「更多文档」里加链接——否则等于没写。

历史文档不追改：STF_REMOVAL.md 是迁移阶段的历史记录，只增不改，不随现状改写。

Reference in New Issue View Git Blame Copy Permalink