butubb
24d57d3b96
背景：文档长期落后于代码（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 种任务类型）
92 lines
4.5 KiB
Bash
92 lines
4.5 KiB
Bash
# ==============================================================================
|
||
# auto_control 环境变量示例
|
||
# - 复制为项目根目录的 .env 再按需修改（.env 已被 .gitignore 排除，不会进 git）
|
||
# - 加载方式：config.py 逐行解析后用 os.environ.setdefault 注入
|
||
# → 因此"真实环境变量"优先于 .env（容器/CI 里用 env 覆盖更方便）
|
||
# - 标【必须】的项务必设置；其余留空即用代码默认值
|
||
# - 完整说明见 doc/DEVELOPMENT.md §4 配置速查、doc/DEPLOY.md §2.2
|
||
# ==============================================================================
|
||
|
||
# ==================== Web 服务 ====================
|
||
# 会话密钥【必须，生产务必固定】：不配则每次启动随机生成，重启后登录态失效。
|
||
# 生成：python -c "import secrets; print(secrets.token_hex(32))"
|
||
WEB_SECRET_KEY=请填写随机密钥
|
||
|
||
# 监听地址与端口是 config.py 里的常量（不进 .env）：WEB_HOST=0.0.0.0、WEB_PORT=18050
|
||
# 需要修改直接改 config.py（18050 是为了避开 Windows 动态端口段）
|
||
|
||
|
||
# ==================== 设备与 adb ====================
|
||
# USB 设备（serial 无冒号）所在的部署机 —— 平台经它的 adb server 驱动这些设备。
|
||
# 默认 100.100.10.1:5037（220 的 Tailscale IP + adb 容器端口，host 网络模式）。
|
||
# USB_ADB_HOST=100.100.10.1
|
||
# USB_ADB_PORT=5037
|
||
|
||
# 设备自动发现（扫描网段找开放 5555 的设备）。
|
||
# 扫描网段在「工具 → 设备池管理」界面里配置（存数据库 app_meta），此处只管端口与周期。
|
||
# DISCOVERY_PORT=5555
|
||
# DISCOVERY_INTERVAL=60
|
||
|
||
# 把本机的 adb 客户端指向远程 adb server（注意：这三个键由 adb/adbutils 自己读取，
|
||
# 不是本项目代码读的；两个变量名都要设，adb 实际认 ADDRESS，部分库读 HOST）。
|
||
# 用途：让本机 adb 直接看到 220 侧插着的 USB 设备。
|
||
# ANDROID_ADB_SERVER_ADDRESS=192.168.20.220
|
||
# ANDROID_ADB_SERVER_HOST=192.168.20.220
|
||
# ANDROID_ADB_SERVER_PORT=5037
|
||
|
||
|
||
# ==================== Tailscale 管理（工具 → Tailscale 管理） ====================
|
||
# API key：Tailscale 后台 → Settings → API Access Tokens 生成
|
||
TAILSCALE_API_KEY=请填写Tailscale_API_key
|
||
|
||
# tailnet 名/ID（一般填登录邮箱，如 [email protected]）
|
||
# [email protected]
|
||
|
||
|
||
# ==================== MCP Server（外部 AI 接入，:8033） ====================
|
||
# 注意：mcp_server 只读进程环境变量，**不读本文件**！
|
||
# 容器场景由 scripts/start.sh 用下面这些变量拉起进程；
|
||
# 本机手动启动请直接在命令行前加环境变量（见 doc/MCP.md §2）。
|
||
#
|
||
# MCP_ENABLED=1 # 仅 start.sh 消费：=0 则不自动拉起 MCP
|
||
# MCP_ALLOW_WRITE=1 # 写操作总开关（0=只读；start.sh 内强制为 1）
|
||
# MCP_PLATFORM_URL=http://127.0.0.1:18050
|
||
# MCP_PLATFORM_USER=admin
|
||
# MCP_PLATFORM_PASS=请填写平台admin密码 # 【改过 admin 密码必须同步，否则 MCP 登录失败】
|
||
# MCP_ALLOWED_SERIALS= # 设备白名单（逗号分隔）；空=不限制（语义缺口见 backlog）
|
||
# MCP_HTTP_HOST=0.0.0.0
|
||
# MCP_HTTP_PORT=8033
|
||
# MCP_SCREENSHOT_WIDTH=540 # 返回给模型的截图宽度
|
||
# MCP_JPEG_QUALITY=70
|
||
# MCP_AUDIT_FILE=/tmp/mcp_audit.log
|
||
# MCP_PLATFORM_TIMEOUT=30
|
||
|
||
|
||
# ==================== AI Agent（mcp_agent，命令行/独立运行时用） ====================
|
||
# 注意：同样只读进程环境变量、不读本文件。
|
||
# Web 的「AI 控制台」配置走数据库（app_meta 的 agent_* 键），与本组变量互不影响。
|
||
#
|
||
# AGENT_API_BASE=https://api.deepseek.com
|
||
# AGENT_MODEL=deepseek-v4-flash-vision-exp
|
||
# AGENT_API_KEY=请填写模型 API Key
|
||
# DEEPSEEK_API_KEY= # AGENT_API_KEY 的兼容别名
|
||
# AGENT_MCP_URL=http://127.0.0.1:8033/mcp
|
||
# AGENT_DEFAULT_SERIAL=
|
||
# AGENT_MAX_STEPS=40
|
||
# AGENT_TIMEOUT=120
|
||
# AGENT_LANG=zh
|
||
|
||
|
||
# ==================== 开发/测试 ====================
|
||
# 设置后不启动 cron 调度器（跑测试脚本时避免真实触发任务、占用设备）
|
||
# DISABLE_SCHEDULER=1
|
||
|
||
|
||
# ==============================================================================
|
||
# 已废弃的历史配置（STF 已从代码层摘除，下列键代码不再使用，保留仅为兼容旧 .env）
|
||
# STF_URL / STF_TOKEN / STF_SSH_TARGET / STF_SSH_PASSWORD /
|
||
# STF_DOCKER_CONTAINER / STF_ADB_CONTAINER / STF_SCRIPT_PATH /
|
||
# AUTO_RELEASE_STALE_OCCUPY
|
||
# 迁移背景见 doc/STF_REMOVAL.md
|
||
# ==============================================================================
|