# AgentOS 原子操作体系 v2 完整规划 > 状态: 规划中 | 创建: 2026-06-21 09:30 > 目标: 建立系统性、可持续迭代的原子操作开发与测试体系 > 角色: ghai 是项目负责人/决策者，Claw 是技术搭档/建议者 --- ## 一、核心理念 ### 1.1 我们不是在写代码，是在建立一套"自动化操作知识库" 每个平台的每个操作，都应该像一本字典里的词条： - 有明确的"前提条件"（在什么页面/状态下才能做） - 有确定的"执行方式"（用什么方法做） - 有可验证的"结果"（做了之后页面变成什么样子） ### 1.2 不做"按键精灵"，做"智能操作代理" 按键精灵: 盲按 → 不管结果 → 继续按下一个 智能代理: 检测当前状态 → 确认可以操作 → 执行 → 验证结果 → 记录 ### 1.3 开发效率 > 代码量 一次录制 = 10个原子操作的新代码，比你手写10个函数快100倍。 但前提是：录制系统能捕获足够的信息（状态+操作+结果），并且你我能高效标注它。 --- ## 二、总架构：三层 + 两工具 + 一视图 ``` ┌─────────────────────────────────────────────────────────┐ │ 看板 (Dashboard) │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 操作流程图 │ │ 录制标注界面 │ │ 测试结果面板 │ │ │ │ (你的操作地图)│ │ (你的编辑器) │ │ (你的眼睛) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ ├─────────────────────────────────────────────────────────┤ │ 工具层 │ │ ┌──────────────────────┐ ┌───────────────────────┐ │ │ │ 增强录制系统 │ │ 单步调试模式 │ │ │ │ (捕获三层状态+操作) │ │ (mc debug --step) │ │ │ │ (支持人工标注命名) │ │ (3秒出结果不等待) │ │ │ └──────────────────────┘ └───────────────────────┘ │ ├─────────────────────────────────────────────────────────┤ │ 引擎层 │ │ ┌──────────────────────────────────────────────────┐ │ │ │ PageState (统一状态模型) │ │ │ │ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │ │ │ │ │L1: │→│L2: │→│L3: │→│Action│→│验证 │ │ │ │ │ │页面│ │区域│ │元素│ │执行 │ │结果 │ │ │ │ │ └────┘ └────┘ └────┘ └────┘ └────┘ │ │ │ └──────────────────────────────────────────────────┘ │ │ 原子操作库 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 抖音 ops │ │ 小红书ops │ │ 未来平台 │ │ │ │ douyin/ │ │ xhs/ │ │ ... │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────┘ ``` --- ## 三、PageState 状态模型（引擎层核心） ### 3.1 抖音页面状态定义 | 状态名 | 判断条件 | 可用操作 | |:------|:---------|:---------| | `grid` | URL含jingxuan，card_count>0 | scroll_feed, open_video, search, goto_profile | | `player_modal` | URL含modal_id，video>0 | like, collect, follow, comment, next_video, go_back | | `player_full` | URL含/video/xxx | like, collect, follow, comment, go_back | | `search` | URL含/search/ | click_result, scroll, go_back | | `profile` | URL含/user/ | read_field, go_back | ### 3.2 小红书页面状态定义 | 状态名 | 判断条件 | 可用操作 | |:------|:---------|:---------| | `grid` | URL=/explore, note-item>0 | scroll_feed, click_note, search, goto_profile | | `note_detail` | URL=/explore/xxx | like, collect, comment, post_comment, follow, go_back | | `search` | URL=/search_result | click_result, go_back | | `profile` | URL=/user/profile/xxx | read_field, go_back | ### 3.3 状态转换规则 ``` grid ──(open_video/click_note)──> player/note_detail grid ──(search)──────────────────> search grid ──(goto_profile)────────────> profile player ──(go_back)───────────────> grid player ──(next_video)────────────> player (不同视频) search ──(click_result)──────────> player/note_detail search ──(go_back)───────────────> grid profile ──(go_back)──────────────> grid ``` --- ## 四、增强录制系统（工具层） ### 4.1 录制数据的完整结构 ```json { "session": { "platform": "douyin", "account": "douyin_test", "start_time": "2026-06-21T10:00:00", "window_size": [702, 783] }, "steps": [ { "id": 1, "label": "", // 你来命名（如"点开第一个视频"） "before": { "url": "...", "page_type": "grid", "dom_snapshot": { "video_count": 0, "card_count": 20, "has_search_bar": true, "has_nav": true, "author_id": null, "is_self": false }, "mouse_position": [434, 190], "mouse_region": "feed_area", "nearby_elements": [ {"tag": "A", "class": "cover mask ld", "text": "", "x": 375, "y": 292} ] }, "action": { "type": "click", "x": 375, "y": 292, "target_tag": "A", "target_class": "cover mask ld", "target_text": "", "details": "笔记封面点击，可能打开了笔记详情页" }, "after": { "url": "https://www.douyin.com/jingxuan?modal_id=xxx", "page_type": "player_modal", "dom_snapshot": { "video_count": 1, "card_count": 0, "has_comment_list": true }, "url_changed": true, "dom_diff": "video元素从0变为1，进入了播放页" } } ] } ``` ### 4.2 录音交互流程 ``` 1. 你启动录制: mc record --account=douyin_test --platform=douyin → 浏览器打开，开始录制 2. 你做操作，按 `·` 标记每一步 → 系统自动捕获 before/action/after 3. 录制结束按 Esc → 系统保存完整录制数据 4. 进入标注界面（Dashboard新页面） → 展示每一步的 before/action/after → 自动检测操作类型（点击/按键/滚动） → 自动建议原子操作名称（like/collect/comment） → 你可以修改名称和补充说明 → 连续2步可以合并为1个原子操作（如：开评论(x) + 输入 + 发送 = post_comment） 5. 标注完成 → 系统自动生成原子操作代码模板 → 你审核通过 → 代码入库 ``` ### 4.3 录制界面的设计要点 ``` ┌──────────────────────────────────────────────┐ │ 录制回放: douyin_test - 2026-06-21 10:00 │ ├──────────────────────────────────────────────┤ │ │ │ Step 1: grid → player_modal │ │ ┌────────┐ ┌──────────┐ ┌──────────┐ │ │ │ BEFORE │→│ ACTION │→│ AFTER │ │ │ │ 首页 │ │ 双击卡片 │ │ 播放页 │ │ │ │ card=20│ │ A.cover │ │ video=1 │ │ │ └────────┘ └──────────┘ └──────────┘ │ │ 操作名: [open_video___] ← 你填或系统建议 │ │ 备注: [双击feed卡片进入首个视频___] │ │ │ │ Step 2: 播放页 → 播放页(已点赞) │ │ ┌────────┐ ┌──────────┐ ┌──────────┐ │ │ │ BEFORE │→│ ACTION │→│ AFTER │ │ │ │ 播放页 │ │ 按z键 │ │ 心变红 │ │ │ └────────┘ └──────────┘ └──────────┘ │ │ 操作名: [like_________] ← 系统建议: like │ │ 备注: [键盘z点赞_______________] │ │ │ │ [合并步骤1+2?] [导出为蓝图] [生成代码] │ └──────────────────────────────────────────────┘ ``` --- ## 五、单步调试模式（工具层） ### 5.1 命令设计 ```bash # 模式1: 启动交互式调试（浏览器保持打开） mc debug --accounts=douyin_test --platform=douyin → 浏览器打开，保持运行 → 等待命令 # 模式2: 执行单步操作 mc step open_video # 只执行这一个操作，返回结果+消耗时间 mc step like # 继续下一步 mc step collect # 3秒内出结果 # 模式3: 批量单步（自动但不跳过） mc step open_video like collect follow open_comments post_comment → 每步执行后停顿1秒，显示结果，继续下一步 ``` ### 5.2 交互流程 ``` > mc debug --accounts=douyin_test ✅ 浏览器已启动，当前状态: grid (首页) 等待命令... > open_video ✅ open_video → video_detail (5.2s) 状态: grid → player_modal 验证: video=1 ✅ 可继续下一步 > like ✅ like → 👍 (1.1s) 状态: player_modal 验证: 通过✅ > collect ❌ collect → - (0.0s) 状态: player_modal 元素未找到: [data-e2e="video-player-collect"] 回退: JS搜索也失败，坐标兜底也失败 建议: 你在浏览器里点一下收藏，我看看实际DOM是什么 ``` --- ## 六、看板集成（展示层） ### 6.1 新增三个页面 | 页面 | 路径 | 功能 | |:-----|:-----|:------| | 操作流程图 | `/ops-flow` | SVG流程图，实时显示测试状态 | | 录制标注 | `/recorder` | 回放录制，标注原子操作，合并步骤 | | 测试控制台 | `/debug` | 单步测试，查看日志，状态监控 | ### 6.2 操作流程图功能 - 展示所有平台的操作状态机 - 绿色 = 已测试通过 - 橙黄色 = 部分通过/有问题 - 灰色 = 未测试 - 点击任意节点 → 显示该操作的详细信息 - 点击连线 → 显示状态转换条件 - 底部显示当前正在测试的"路径"和进度 --- ## 七、实施计划（分阶段） ### Phase 1: 基础设施（1-2天） | 任务 | 说明 | |:-----|:------| | 1.1 实现 PageInspector | L1: 页面类型, L2: 鼠标区域, L3: 元素详情 | | 1.2 增强 Recorder | 录制时捕获完整三层状态 | | 1.3 实现 mc debug | 浏览器保持打开，接受后续命令 | ### Phase 2: 标注系统 + 流程图（1-2天） | 任务 | 说明 | |:-----|:------| | 2.1 录制标注页面 | 看板新页面，回放+标注+合并步骤 | | 2.2 操作流程图页面 | SVG流程图 + 实时状态 | | 2.3 测试控制台页面 | 单步调试 + 日志查看 | ### Phase 3: 存量修复（1天） | 任务 | 说明 | |:-----|:------| | 3.1 录一次抖音全流程 | 你录制 → 我分析 | | 3.2 修复 collect + open_comments | 基于录制数据修复 | | 3.3 录一次小红书全流程 | 你录制 → 我分析 | | 3.4 修复小红书全部操作 | 基于录制数据修复 | ### Phase 4: 扩展（持续） | 任务 | 说明 | |:-----|:------| | 4.1 新增平台 | 每个平台遵循同样流程：录制 → 标注 → 测试 | | 4.2 蓝图组合 | 基于稳定的原子操作，组合成养号/评论等蓝图 | | 4.3 定时任务 | 每日自动化执行 | --- ## 八、当前迭代聚焦 ### 本周目标（2026-06-21 ~ 06-27） ``` Week 1: 抖音全流程打通 → 小红书全流程打通 → 看板可查看流程图 ``` ### 今天目标（2026-06-21） 1. **你先录一次抖音完整流程**（约10步），我在录制过程中捕获完整状态 2. **一起标注这些步骤**，给每个操作命名 3. **基于录制数据修复问题**（collect + open_comments） 4. **完成抖音流程图**，所有路径从灰色变绿色 --- ## 九、你需要的（而不是我想要的） 这个计划的核心目标只有一个：**让你能高效地验证想法，而不是把时间花在猜代码上**。 每一步都是： 1. 你操作 → 我记录 2. 你标注 → 我理解 3. 你测试 → 我修复 4. 你确认 → 下一个 你不是在写代码。你是在教会我你的平台操作方式。 我是你的"手"和"眼"，你是"大脑"和"决策者"。