ai制作系统操作手册

可以，而且方向比单纯 Playwright 或"路径动态规划"更对。但要先纠正一个判断：

Harness Agent 能做得更多，不是因为 Agent 天生更强，而是因为你给它构建了完整的运行环境：工具、约束、状态、验证器、记忆和产物标准。

没有这些，所谓 Harness Agent 只是"让大模型乱点页面"，稳定性甚至不如 Playwright。

一、三种方案的本质区别

1. Playwright：脚本驱动

核心逻辑是：

text 复制代码

打开页面
→ 找元素
→ 点击
→ 输入
→ 截图
→ 下一步

适合：

固定流程
回归测试
页面结构稳定
已知操作路径

问题：

DOM 变化就容易失败
不理解业务语义
不能主动判断下一步
异常分支需要人工提前编写
最终只能生成"操作记录"，很难生成高质量手册

Playwright 本质是执行工具，不是完整解决方案。

2. 路径动态规划：页面路径驱动

核心是把系统抽象成图：

text 复制代码

页面 = 节点
点击、跳转 = 边

然后搜索路径：

text 复制代码

登录页 → 项目列表 → 项目详情 → 报告下载

它比固定 Playwright 强，因为可以动态寻找路径。

但它仍然有明显缺陷：

关注"怎么到页面"，不关注"为什么这样操作"
很难识别表单业务含义
无法理解权限、状态、前置条件
路径数量容易爆炸
弹窗、iframe、新标签页、异步任务会让状态图非常复杂
很难生成异常处理、注意事项和业务说明

它适合做页面探索，不适合单独承担操作手册生成。

3. Harness Agent：任务驱动

Harness Agent 的核心不是"找路径"，而是：

text 复制代码

明确任务
→ 收集当前状态
→ 选择工具
→ 执行动作
→ 验证结果
→ 记录证据
→ 失败恢复
→ 生成结构化产物

例如任务不是：

text 复制代码

点击项目管理，再点击新增

而是：

text 复制代码

创建一个资产评估项目，并确认项目已成功进入待审核状态

Agent 可以综合使用：

Playwright
浏览器 CDP
DOM
Accessibility Tree
页面截图
OCR/视觉模型
网络请求
后端 API
数据库查询
日志分析
文件下载
Word/PDF 生成
知识库检索

这才是它能做更多事情的真正原因。

二、操作手册 Harness Agent 架构

建议分成七层。

text 复制代码

┌───────────────────────────────────────┐
│         操作手册生成任务               │
│  例如：创建项目、上传附件、提交审核     │
└──────────────────┬────────────────────┘
                   ↓
┌───────────────────────────────────────┐
│ 1. Planner 任务规划器                  │
│ 将业务目标拆成步骤、条件和验证点         │
└──────────────────┬────────────────────┘
                   ↓
┌───────────────────────────────────────┐
│ 2. Observer 状态感知层                 │
│ URL / DOM / 截图 / 弹窗 / 网络 / 权限   │
└──────────────────┬────────────────────┘
                   ↓
┌───────────────────────────────────────┐
│ 3. Tool Harness 工具层                 │
│ Playwright / API / DB / 文件 / OCR      │
└──────────────────┬────────────────────┘
                   ↓
┌───────────────────────────────────────┐
│ 4. Executor 执行器                     │
│ 点击、输入、上传、下载、切换窗口         │
└──────────────────┬────────────────────┘
                   ↓
┌───────────────────────────────────────┐
│ 5. Verifier 验证器                     │
│ 验证页面状态、提示信息、数据库结果       │
└──────────────────┬────────────────────┘
                   ↓
┌───────────────────────────────────────┐
│ 6. Evidence Store 证据库               │
│ 截图、动作、页面状态、日志、失败原因     │
└──────────────────┬────────────────────┘
                   ↓
┌───────────────────────────────────────┐
│ 7. Manual Generator 手册生成器         │
│ Word / PDF / HTML / Markdown / Obsidian │
└───────────────────────────────────────┘

三、最终手册不应该只是截图加文字

每一个操作步骤至少要记录这些内容：

json 复制代码

{
  "step_no": 3,
  "title": "填写项目基本信息",
  "page_name": "项目新增页面",
  "url": "/project/create",
  "preconditions": [
    "当前用户拥有项目新增权限",
    "已进入项目管理模块"
  ],
  "actions": [
    {
      "type": "input",
      "target": "项目名称",
      "value": "测试评估项目"
    },
    {
      "type": "select",
      "target": "项目类型",
      "value": "资产评估"
    }
  ],
  "expected_result": "项目名称和项目类型显示正确",
  "verification": {
    "method": "dom",
    "condition": "input[name=projectName].value != ''"
  },
  "screenshot": "step_003.png",
  "notes": [
    "项目名称不能重复"
  ],
  "exceptions": [
    {
      "condition": "项目名称已存在",
      "solution": "修改项目名称后重新提交"
    }
  ]
}

后续 Word、PDF、Markdown 都从这份中间数据生成。

不要让 Agent 一边操作页面，一边直接写 Word。那样流程不可复用，也无法回放和校验。

正确顺序是：

text 复制代码

执行系统
→ 生成结构化步骤 JSON
→ 人工或 Agent 校验
→ 生成最终手册

四、Harness Agent 能比之前多做什么

1. 自动识别业务步骤

Playwright 只知道：

text 复制代码

点击按钮

Harness Agent 可以生成：

text 复制代码

单击"提交审核"，将当前项目提交到审核流程。
提交后，项目状态由"编辑中"变为"待审核"。

它能把技术动作转成用户能理解的业务说明。

2. 自动识别前置条件

例如按钮不存在，可能不是定位器坏了，而是：

当前用户没有权限
项目状态不允许操作
当前步骤尚未完成
当前环境配置不同

Harness Agent 可以先判断条件，而不是盲目重试。

3. 自动处理异常分支

例如：

text 复制代码

上传文件失败
→ 检查格式
→ 检查大小
→ 检查网络返回
→ 保存错误截图
→ 在手册中增加常见问题

Playwright 通常只会抛出异常。

4. 自动补充截图标注

可以基于元素坐标：

给按钮加红框
添加序号
模糊敏感数据
裁剪关键区域
自动生成图片说明

例如：

text 复制代码

步骤 5：单击右上角"提交审核"按钮。

截图中自动标记对应按钮，而不是整张屏幕直接塞进 Word。

5. 自动验证操作是否成功

验证不能只依赖页面显示。

可以组合验证：

text 复制代码

页面提示成功
+ URL 已变化
+ 项目状态变成待审核
+ 后端接口返回成功
+ 数据库记录已生成

这比"点完按钮截图"可靠得多。

6. 自动维护手册

当系统升级后：

text 复制代码

重新执行任务
→ 对比旧页面和新页面
→ 找出变化步骤
→ 替换截图
→ 更新文案
→ 输出变更报告

这才是 Harness Agent 最有价值的地方。

第一次生成手册不是最难的，真正昂贵的是后续持续维护。

五、核心组件设计

1. Task Definition

用 Markdown 或 YAML 定义业务任务：

yaml 复制代码

task_id: create_project
task_name: 新建评估项目

goal:
  创建一个评估项目，并提交审核

preconditions:
  - 用户已登录
  - 用户拥有项目新增权限

inputs:
  project_name: 自动化测试项目
  project_type: 资产评估

success_criteria:
  - 页面出现"提交成功"
  - 项目状态为"待审核"

output:
  - 操作步骤
  - 步骤截图
  - 异常说明
  - Word操作手册

这就是 Agent 的任务合同。

2. Tool Contract

不要允许 Agent 随意执行代码，要提供明确工具：

python 复制代码

open_page(url)
click_element(element_id)
input_text(element_id, value)
select_option(element_id, value)
upload_file(element_id, file_path)
read_page_state()
capture_screenshot()
query_api(request)
query_database(sql)
verify_condition(condition)

每个工具都必须返回：

json 复制代码

{
  "success": true,
  "before_state": {},
  "after_state": {},
  "evidence": [],
  "error": null
}

3. State Snapshot

每一步执行前后都保存：

json 复制代码

{
  "url": "",
  "title": "",
  "visible_text": "",
  "interactive_elements": [],
  "dialogs": [],
  "network_errors": [],
  "screenshot": "",
  "timestamp": ""
}

否则 Agent 无法判断自己到底做了什么。

4. Verifier

每一步需要独立验证：

python 复制代码

def verify_submit_success(state):
    return (
        "提交成功" in state.visible_text
        and state.project_status == "待审核"
    )

不能把验证完全交给大模型自由判断，否则稳定性差。

六、推荐的执行模式

不要让 Agent 每一步都完全自由规划。采用三级模式。

一级：确定性执行

已知、稳定步骤直接使用 Playwright：

text 复制代码

登录
打开模块
输入固定字段

二级：受约束选择

页面轻微变化时，让 Agent 从候选元素中选择：

json 复制代码

{
  "goal": "打开项目详情",
  "candidates": [
    "详情",
    "查看",
    "项目名称链接"
  ]
}

三级：自主恢复

只有执行失败时才允许 Agent分析：

text 复制代码

元素未找到
→ 重新读取页面
→ 检查弹窗
→ 检查 iframe
→ 检查权限
→ 尝试替代路径

不要一上来就完全自主。完全自主意味着不可预测、成本高、难调试。

七、建议的项目目录

text 复制代码

manual-agent/
├─ tasks/
│  ├─ create_project.yaml
│  ├─ upload_report.yaml
│  └─ submit_review.yaml
│
├─ harness/
│  ├─ planner.py
│  ├─ executor.py
│  ├─ observer.py
│  ├─ verifier.py
│  └─ recovery.py
│
├─ tools/
│  ├─ browser_tool.py
│  ├─ api_tool.py
│  ├─ database_tool.py
│  ├─ screenshot_tool.py
│  └─ file_tool.py
│
├─ schemas/
│  ├─ task.schema.json
│  ├─ step.schema.json
│  └─ manual.schema.json
│
├─ evidence/
│  └─ create_project/
│     ├─ step_001_before.png
│     ├─ step_001_after.png
│     └─ execution.json
│
├─ generators/
│  ├─ word_generator.py
│  ├─ markdown_generator.py
│  └─ pdf_generator.py
│
├─ templates/
│  └─ operation_manual.docx
│
└─ main.py

八、正确的技术组合

建议使用：

text 复制代码

浏览器执行：Playwright
任务编排：Python Agent / LangGraph
页面理解：DOM + Accessibility Tree + 视觉模型
截图处理：Pillow / OpenCV
结构数据：JSON Schema
手册生成：python-docx
PDF生成：Word转PDF或ReportLab
任务存储：SQLite / PostgreSQL
证据文件：本地目录或OSS
知识库：Obsidian / Markdown

Playwright 不应该被替换。

正确关系是：

text 复制代码

Harness Agent
    ├── 调用 Playwright 执行网页操作
    ├── 调用视觉模型理解页面
    ├── 调用验证器确认结果
    └── 调用文档生成器输出操作手册

你之前的思路容易陷入一个误区：把 Playwright、动态规划和 Harness Agent 当成三个相互替代的方案。

实际上：

Playwright 是执行层
路径规划是规划层的一部分
Harness Agent 是总控制层

它们应该组合，而不是三选一。

九、最合理的开发顺序

不要一开始就做"自动探索整个系统并生成所有手册"，那会直接失控。

优先顺序：

选择一个完整但不复杂的业务流程，例如"新增项目"。
手动定义任务目标和成功标准。
使用 Playwright 完成确定性操作。
记录动作前后状态和截图。
生成结构化步骤 JSON。
从 JSON 生成 Word 手册。
加入失败恢复。
最后才加入 Agent 动态规划。
稳定后扩展到批量任务和系统全量手册。

第一个 MVP 应只解决：

text 复制代码

输入一个任务
→ 自动操作系统
→ 截取关键步骤
→ 生成一份可用的 Word 操作手册

不要一开始追求"全自动理解任何系统"。那不是 MVP，而是在制造一个没有边界、无法验收的研究项目。