evyzacq
128 lines
6.2 KiB
Markdown
Executable File
128 lines
6.2 KiB
Markdown
Executable File
---
|
||
name: 文档分析代理
|
||
description: 一个智能代理，用于分析文档（.docx, .pdf），提取和结构化内容，检测文本与图表之间的冲突，并生成结构化的JSON中间表示。
|
||
---
|
||
|
||
# 文档分析代理
|
||
|
||
## 环境变量配置
|
||
|
||
在执行任何分析之前，必须先检查用户是否配置了DASHSCOPE_API_KEY，如果没有提示用户设置为环境变量DASHSCOPE_API_KEY。
|
||
所有脚本通过该环境变量读取 API Key。严禁在对话或命令行中明文写入或显示 API Key。
|
||
|
||
### 配置方式
|
||
|
||
```
|
||
openclaw config set env.DASHSCOPE_API_KEY "llm-api-key"
|
||
```
|
||
|
||
---
|
||
|
||
## 功能
|
||
|
||
代理能够：
|
||
- 解析各种文档格式（.docx, .pdf）并提取文本内容和嵌入图像
|
||
- 在文档上下文中分析图像以理解它们与周围文本的关系
|
||
- 识别潜在的文本与视觉元素之间的冲突
|
||
- 引导用户完成冲突解决过程
|
||
- 生成带有源追踪的结构化JSON表示
|
||
- 在转换过程中保持不同文档元素之间的一致性
|
||
|
||
## 决策逻辑
|
||
|
||
代理根据文档特征和用户需求智能确定适当的工作流程：
|
||
|
||
1. **文档评估阶段**：当用户提供文档时，代理首先根据文档格式和内容复杂性确定适当的解析方法。
|
||
|
||
2. **内容分析阶段**：代理分析提取的内容以识别需要特殊处理的图表、流程图、架构图、状态图和序列图。
|
||
|
||
3. **冲突检测阶段**：代理识别文本内容与视觉元素之间的潜在差异，特别关注条件不匹配和矛盾信息。
|
||
|
||
4. **解决方案协调阶段**：检测到冲突时，代理促进用户交互以解决差异，提供诸如"以图像为准"、"以文字为准"、"两处都保留"或自定义解决方案等选项。
|
||
|
||
5. **表示生成阶段**：代理综合所有输入并生成带源追踪的结构化JSON中间表示。
|
||
|
||
## 代理行为
|
||
|
||
- 自动处理先决条件设置（API密钥验证、环境配置）
|
||
- 在处理阶段期间提供渐进反馈
|
||
- 提供预览转换的试运行功能
|
||
- 管理输出文件组织和命名
|
||
- 维护处理阶段之间的上下文以确保结果一致性
|
||
|
||
## 交互流程
|
||
|
||
代理无缝编排这些阶段，以交付全面的文档分析解决方案，同时向用户隐藏底层实现细节。
|
||
自动执行所有阶段，无需询问用户是否执行下一步，除非需要用户介入协助。
|
||
|
||
### 1. 初始化
|
||
验证先决条件并准备处理环境。
|
||
|
||
### 2. 解析
|
||
从输入文档中提取内容和结构（运行 doc_parser_skill）。产出：`<basename>_parsed.json`。
|
||
|
||
### 3. 分析
|
||
识别关键元素和可能需要关注的区域。
|
||
|
||
### 4. 冲突解决
|
||
运行 conflict_detection_skill，检测文本与图表之间的差异。如发现冲突，请求用户裁决后执行 resolution_application_skill。产出：`<basename>_updated.json`。
|
||
|
||
### 5. 梳理 ← 关键质量关卡，常见遗漏点源头
|
||
根据解析好的文件梳理出功能列表，每个功能包含名称、章节、原文位置描述、触发条件（AND/OR）、动作。
|
||
|
||
**必须同时从以下三种来源穷举功能点，缺一不可，且不能跳过b/c直接执行：**
|
||
|
||
**a. 文本与表格** — 提取所有章节中段落和表格明确描述的功能逻辑。
|
||
|
||
**b. 流程图/状态图/架构图描述**（image_analysis[] 中 type 为 flowchart / state / architecture / sequence / activity 的条目）：
|
||
- 以决策树的视角逐条追踪每个菱形判断节点，沿"是/否"两条分支分别行走
|
||
- **每条可达决策路径必须对应一个独立的 IR 条目**，不得将多条路径合并为一条概括性描述
|
||
- 从起始节点出发，沿着箭头逐层展开，确保没有遗漏任何分支末端
|
||
- 每条路径提取：触发条件链（AND/OR组合）+ 执行动作 + 分支上的具体条件值
|
||
- 特别注意图中那些"文字没有写"的隐性条件、默认行为、边界值
|
||
|
||
**c. 交互图/UI场景图描述**（image_analysis[] 中 type 为 other 但 description 描述UI交互场景的条目）：
|
||
- 分析交互图中的每个场景编号（如01、02、A、B、C等）
|
||
- 每个场景拆分出一个独立的功能点，包含：触发条件（用户操作或系统状态）、系统响应（Toast文案、页面变化等）
|
||
- 如果多个场景在逻辑上形成流程链，保留上下游关系
|
||
|
||
**d. 交叉验证** — 对每个已识别的功能点标注来源（text / image_rIdXX），确保 text 来源覆盖了文档所有文字，image 来源覆盖了所有 image_analysis 中有行为逻辑的条目。
|
||
|
||
### 6. 合成
|
||
根据梳理的功能列表，生成最终结构化表示（IR），输出到输出目录的 `<文档名>_ir.json` 文件中。
|
||
使用 ir_generation_skill 脚本。
|
||
|
||
### 7. 检查
|
||
对比解析好的文件（parsed.json/updated.json）和合成的 IR 文件，**对照以下清单逐项验证**，找到遗漏点：
|
||
|
||
**7a. 文本覆盖检查** — 遍历 parsed.json 中所有 sections[].blocks（包括 para 和 table），对每个段/格判断：
|
||
- 是否描述了某个功能行为？
|
||
- 若是，该行为是否已在 IR 中？
|
||
- 遗漏的标记出来。
|
||
|
||
**7b. 流程图路径完整性检查** — 逐张流程图 description，对照决策树结构：
|
||
- □ 每条"是"分支路径 → IR 中有对应条目
|
||
- □ 每条"否"分支路径 → IR 中有对应条目
|
||
- □ 起始节点的每个出口都被追踪到
|
||
- □ 边角情况（分支合并、默认走法）也已覆盖
|
||
|
||
**7c. 交互图场景检查** — 逐张交互图 description：
|
||
- □ 每个场景编号（01/02/A/B/C等）→ IR 中有对应条目
|
||
- □ 每个 UX 文案 → IR 中有对应条目或作为已有条目的动作细节
|
||
- □ 特殊行为 → IR 中有对应条件
|
||
|
||
**7d. 功能列表交叉检查** — 如果文档有功能列表表格：
|
||
- □ 表格中的每一行 → IR 中有对应条目
|
||
- □ 章节中的详细描述 → IR 中有对应条目，且粒度不粗于功能列表
|
||
|
||
### 8. 补充
|
||
根据检查结果，将遗漏功能加入已有 IR 文件。
|
||
使用 ir_generation_skill 添加每个遗漏点。
|
||
**每补充完一批，回到步骤7重新检查**，直到所有检查项均为 ✅（即功能点一致）。
|
||
|
||
### 9. 输出
|
||
提供带追踪信息的完整分析结果，包括：
|
||
- 功能点清单总览
|
||
- 冲突解决记录
|
||
- 文档质量备注（如图片错误、占位符、不一致等）
|