UFO² 帮助文档学习机制全解析从 JSON 文档构建到离线 RAG 检索增强 AppAgent【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO本文围绕 UFO² 的从帮助文档中学习Learning from Help Documents知识能力展开讲解用户或应用如何以任务-解决方案对task-solution pairs的形式向 AppAgent 提供离线帮助文档使 AppAgent 在处理具体请求时检索相关知识以提升任务理解、计划质量与应用交互效率。读完本文你将掌握帮助文档的 JSON 编写规范、learner索引器的完整命令行用法、rag.yaml中的关键配置参数以及从索引创建到在线检索注入提示词的全链路源码级原理。一、机制概述帮助文档如何增强 AppAgent在 UFO² 中AppAgent 的能力并不仅仅来源于底层大模型的先验知识。通过 知识基底Knowledge Substrate用户可以主动向 AppAgent 投喂针对特定应用的帮助文档使其在任务执行时像该应用的专家一样思考。这一能力位于 UFO² RAG检索增强生成体系的四类知识来源之首知识来源说明帮助文档本文主题从为特定应用构建索引的离线帮助文档中检索知识Bing 在线搜索通过 Bing 检索实时在线信息自我经验从 Agent 自身成功执行历史中学习用户演示从用户演示的动作轨迹中学习帮助文档的核心理念是将其组织为任务-解决方案对task-solution pairs。当 AppAgent 处理一个请求时执行如下三步机制检索将用户请求与文档中的任务描述进行匹配召回最相关的帮助文档参考将召回文档中的解决方案作为计划生成阶段的参考依据适配将解决方案适配到当前具体上下文与界面状态中。值得强调的是由于检索到的文档可能与当前任务并非完全契合AppAgent 会将其视为参考references而非严格指令strict instructions允许在执行过程中根据真实任务需求灵活调整而不是机械照搬文档步骤。二、第一步编写 JSON 格式的帮助文档UFO² 目前支持处理json格式的帮助文档源码中的 learner/indexer.py 显示加载器映射表_doc_loader_mapper已为后续扩展预留了xml加载器说明更多格式正在规划中。一份标准的帮助文档 JSON 示例来源Help Document Provision 指南{ application: chrome, request: How to change the username in chrome profiles?, guidance: [ Click the profile icon in the upper-right corner of the Chrome window., Click the gear icon labeled Manage Chrome Profiles in the profile menu., In the list of profiles, locate the profile whose name you want to change., Hover over the desired profile and click the three-dot menu icon on that profile card., Select Edit from the dropdown menu., In the Edit Profile dialog, click inside the name field., Delete the current name and type your new desired username., Click Save to confirm the changes., Verify that the profile name is updated in the profile list and in the top-right corner of Chrome. ] }字段语义如下字段类型说明applicationString目标应用名称用于文档归属标识requestString用户任务/请求的自然语言描述作为检索匹配的查询文本guidanceString[]完成该任务的分步操作指引作为检索命中后提供给 LLM 的解决方案内容将每份帮助文档单独保存为一个.json文件放入目标文件夹中即可。从源码角度可以更精确地理解这三个字段的用途learner/json_loader.py 中的JsonLoader.construct_document()逐文件读取 JSON将request作为 langchainDocument的page_content即参与向量检索的主文本并将guidance数组按行拼接为元数据中的text字段request document.get(request, ) guidance_steps document.get(guidance, []) guidance \n.join([step for step in guidance_steps]) metadata {title: request, summary: request, text: guidance} document Document(page_contentrequest, metadatametadata)也就是说检索匹配发生在request字段上而命中后供 LLM 参考的则是guidance步骤列表两者互为任务-解决方案对的检索键与内容值。三、第二步将帮助文档放入指定目录编写完成所有帮助文档及其元数据后将其放入一个统一文件夹。允许使用子文件夹组织文档但必须保证每份帮助文档与其元数据位于同一目录下否则索引器扫描时可能漏检。文档目录与 UFO² 的索引产物目录默认约定如下源文档目录任意你指定的路径例如path_of_the_docs索引产物目录默认输出到vectordb/docs/下与仓库中的 vectordb/docs 目录对应。四、第三步使用 learner 创建离线索引器组织好文档后在克隆的 UFO 仓库根目录执行以下命令构建离线 RAG 索引python -m learner --app app_name --docs path_of_the_docs命令行参数详解依据 learner/learner.py 中的 argparse 定义参数默认值说明--app./应用名称用于索引文件命名与后续在线检索匹配--docs./帮助文档所在文件夹路径--formatjson帮助文档格式当前支持jsonxml已预留--incrementalFalseflag开启增量更新新文档与既有索引合并--save_path./vectordb/docs/索引保存路径--app必须使用应用的精确进程名例如 Microsoft Word 填WINWORD.EXE、PowerPoint 填POWERPNT.EXE。这一约束至关重要app_name会用于在线 RAG 阶段与目标应用进程的匹配定义不准确将导致运行时无法命中索引器。索引构建的底层流程执行python -m learner后learner/indexer.py 中的DocumentsIndexer.create_indexer()依次完成读取记录文件加载learner/records.json不存在则初始化为空字典该文件维护应用名 → 索引绝对路径的映射加载文档根据--format从_doc_loader_mapper选择JsonLoader或预留的XMLLoader调用construct_document()将每个 JSON 文件转换为 langchainDocument构建向量库使用 Hugging Face embeddingget_hugginface_embedding()默认基于 sentence-transformer 模型将文档向量化并通过FAISS.from_documents()构建 FAISS 向量库增量合并若开启--incremental且records.json中已存在该应用的旧索引则通过FAISS.merge_from()将新旧索引合并落盘与登记索引保存到vectordb/docs/app_name绝对路径随后更新records.json记录。db FAISS.from_documents(documents, embeddings) if incremental: if app in records: prev_db FAISS.load_local(records[app], embeddings, allow_dangerous_deserializationTrue) db.merge_from(prev_db) db_file_path os.path.join(save_path, app) db.save_local(db_file_path) records[app] db_file_path完成索引后终端会输出Indexer for app created successfully. Save in path.的绿色提示。五、配置在 rag.yaml 中启用离线文档检索索引创建完毕后需在 RAG 配置中启用离线文档检索开关。配置文件位于 config/ufo/rag.yaml涉及的两个核心参数如下与 Learning from Help Documents 中的参数表一致配置项类型默认值说明RAG_OFFLINE_DOCSBooleanFalse是否启用离线帮助文档检索RAG_OFFLINE_DOCS_RETRIEVED_TOPKInteger1每个子任务召回的文档数量最小启用配置# config/ufo/rag.yaml RAG_OFFLINE_DOCS: True RAG_OFFLINE_DOCS_RETRIEVED_TOPK: 1完整 RAG 配置示例含全部知识源# Offline docs RAG_OFFLINE_DOCS: True RAG_OFFLINE_DOCS_RETRIEVED_TOPK: 1 # Online search RAG_ONLINE_SEARCH: True BING_API_KEY: ${BING_API_KEY} RAG_ONLINE_SEARCH_TOPK: 5 RAG_ONLINE_RETRIEVED_TOPK: 1 # Experience RAG_EXPERIENCE: True RAG_EXPERIENCE_RETRIEVED_TOPK: 5 EXPERIENCE_SAVED_PATH: vectordb/experience/ # Demonstration RAG_DEMONSTRATION: True RAG_DEMONSTRATION_RETRIEVED_TOPK: 5 DEMONSTRATION_SAVED_PATH: vectordb/demonstration/注BING_API_KEY默认读取环境变量${BING_API_KEY}不要将密钥硬编码进配置文件。RAG 功能整体为可选能力——即使全部关闭UFO² 依然可以正常工作只是对复杂或领域化任务的执行质量会打折扣。完整参数说明与场景化配置组合可参考 RAG 配置指南。Top-K 取值建议字段建议范围说明RAG_OFFLINE_DOCS_RETRIEVED_TOPK1–2帮助文档通常篇幅较长1~2 篇已足够提供上下文RAG_ONLINE_SEARCH_TOPK3–10越大上下文越丰富但检索越慢RAG_EXPERIENCE_RETRIEVED_TOPK3–5召回最相关的历史经验RAG_DEMONSTRATION_RETRIEVED_TOPK1–3演示示例通常只需少量若出现 token 超限或响应缓慢的上下文过多问题优先下调各RETRIEVED_TOPK数值。六、运行时检索链路从配置开关到提示词注入当RAG_OFFLINE_DOCS: True时UFO² 在运行时的完整检索链路如下1. 加载离线检索器context_provisionAppAgent 启动时会调用context_provision()见 ufo/agents/agent/app_agent.py。当检测到ufo_config.rag.offline_docs为真时控制台打印 Loading offline help document indexer for 进程名...随后调用build_offline_docs_retriever()self.offline_doc_retriever self.retriever_factory.create_retriever( offline, self._app_root_name )注意这里传入的是_app_root_name应用进程的根名称RetrieverFactoryufo/rag/retriever.py依据retriever_type offline实例化OfflineDocRetriever。2. 定位索引路径records.json 匹配OfflineDocRetriever.__init__接收app_name并通过get_offline_indexer_path()定位索引offline_records get_offline_learner_indexer_config() for key in offline_records: if key.lower() in self.app_name.lower(): return offline_records[key]其中get_offline_learner_indexer_config()ufo/config/init.py直接读取构建索引时写入的learner/records.json。匹配是大小写不敏感的子串匹配只要应用根名称包含记录中的 key即可命中对应索引。这解释了为何--app必须与真实进程名保持一致——它是连接索引构建与在线检索的唯一纽带。随后通过FAISS.load_local(path, get_hugginface_embedding(), allow_dangerous_deserializationTrue)加载向量库若加载失败例如索引路径不存在检索器优雅降级返回None并在日志中输出警告不会中断任务。3. 子任务级知识召回_knowledge_retrieval在处理每个子任务时app_agent_processing_strategy.py 中的_knowledge_retrieval()会调用agent.external_knowledge_prompt_helper(subtask, offline_docs_retrieved_topk, online_retrieved_topk)将当前子任务作为查询文本对离线索引执行similarity_search(query, top_k, filterNone)基类 Retriever.retrieve按向量相似度召回 Top-K 篇帮助文档。若索引为空则返回空列表。4. 注入提示词召回的文档内容作为offline_docs与其他知识经验、演示、在线搜索一起拼装进dynamic_knowledge通过message_constructor注入 AppAgent 的上下文提示词app_agent_processing_strategy.py。此后 LLM 在做 UI 控制决策时就能参考帮助文档中的分步指引并结合当前屏幕截图与控件信息将通用步骤适配为具体可执行的 GUI 操作。七、工程实践要点与注意事项应用名准确性是匹配前提索引构建--app与运行时应用进程根名称必须匹配OfflineDocRetriever的匹配逻辑为大小写不敏感的包含判断命名混乱如大小写、前后缀不一致会导致索引无法命中。参考而非指令的定位召回文档可能并非完全契合当前任务因此帮助文档只作为计划生成的参考依据AppAgent 会结合实时界面状态灵活适配避免机械照搬导致执行失败。增量更新的使用当帮助文档持续迭代时使用--incremental可在不重建全部索引的前提下将新文档并入既有 FAISS 索引降低维护成本。Top-K 与上下文预算的权衡帮助文档通常较长建议RAG_OFFLINE_DOCS_RETRIEVED_TOPK保持 1–2避免挤占提示词上下文窗口。索引文件管理索引产物默认保存在vectordb/docs/映射关系持久化于learner/records.json若删除或移动了索引目录需同步更新记录文件或重新执行索引命令。八、相关文档Knowledge Substrate 总览 —— 理解 RAG 整体架构与四类知识来源帮助文档提供指南 —— 本文所述三步准备流程的完整原文RAG 配置指南 —— 全量 RAG 参数、场景组合与排障方法增强 AppAgent 能力总览 —— 对比演示教学、应用原生 API 封装等其余增强手段核心源码learner/learner.py、learner/indexer.py、learner/json_loader.py、ufo/rag/retriever.py、ufo/agents/agent/app_agent.py核心配置config/ufo/rag.yaml【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
UFO² 帮助文档学习机制全解析从 JSON 文档构建到离线 RAG 检索增强 AppAgent【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO本文围绕 UFO² 的从帮助文档中学习Learning from Help Documents知识能力展开讲解用户或应用如何以任务-解决方案对task-solution pairs的形式向 AppAgent 提供离线帮助文档使 AppAgent 在处理具体请求时检索相关知识以提升任务理解、计划质量与应用交互效率。读完本文你将掌握帮助文档的 JSON 编写规范、learner索引器的完整命令行用法、rag.yaml中的关键配置参数以及从索引创建到在线检索注入提示词的全链路源码级原理。一、机制概述帮助文档如何增强 AppAgent在 UFO² 中AppAgent 的能力并不仅仅来源于底层大模型的先验知识。通过 知识基底Knowledge Substrate用户可以主动向 AppAgent 投喂针对特定应用的帮助文档使其在任务执行时像该应用的专家一样思考。这一能力位于 UFO² RAG检索增强生成体系的四类知识来源之首知识来源说明帮助文档本文主题从为特定应用构建索引的离线帮助文档中检索知识Bing 在线搜索通过 Bing 检索实时在线信息自我经验从 Agent 自身成功执行历史中学习用户演示从用户演示的动作轨迹中学习帮助文档的核心理念是将其组织为任务-解决方案对task-solution pairs。当 AppAgent 处理一个请求时执行如下三步机制检索将用户请求与文档中的任务描述进行匹配召回最相关的帮助文档参考将召回文档中的解决方案作为计划生成阶段的参考依据适配将解决方案适配到当前具体上下文与界面状态中。值得强调的是由于检索到的文档可能与当前任务并非完全契合AppAgent 会将其视为参考references而非严格指令strict instructions允许在执行过程中根据真实任务需求灵活调整而不是机械照搬文档步骤。二、第一步编写 JSON 格式的帮助文档UFO² 目前支持处理json格式的帮助文档源码中的 learner/indexer.py 显示加载器映射表_doc_loader_mapper已为后续扩展预留了xml加载器说明更多格式正在规划中。一份标准的帮助文档 JSON 示例来源Help Document Provision 指南{ application: chrome, request: How to change the username in chrome profiles?, guidance: [ Click the profile icon in the upper-right corner of the Chrome window., Click the gear icon labeled Manage Chrome Profiles in the profile menu., In the list of profiles, locate the profile whose name you want to change., Hover over the desired profile and click the three-dot menu icon on that profile card., Select Edit from the dropdown menu., In the Edit Profile dialog, click inside the name field., Delete the current name and type your new desired username., Click Save to confirm the changes., Verify that the profile name is updated in the profile list and in the top-right corner of Chrome. ] }字段语义如下字段类型说明applicationString目标应用名称用于文档归属标识requestString用户任务/请求的自然语言描述作为检索匹配的查询文本guidanceString[]完成该任务的分步操作指引作为检索命中后提供给 LLM 的解决方案内容将每份帮助文档单独保存为一个.json文件放入目标文件夹中即可。从源码角度可以更精确地理解这三个字段的用途learner/json_loader.py 中的JsonLoader.construct_document()逐文件读取 JSON将request作为 langchainDocument的page_content即参与向量检索的主文本并将guidance数组按行拼接为元数据中的text字段request document.get(request, ) guidance_steps document.get(guidance, []) guidance \n.join([step for step in guidance_steps]) metadata {title: request, summary: request, text: guidance} document Document(page_contentrequest, metadatametadata)也就是说检索匹配发生在request字段上而命中后供 LLM 参考的则是guidance步骤列表两者互为任务-解决方案对的检索键与内容值。三、第二步将帮助文档放入指定目录编写完成所有帮助文档及其元数据后将其放入一个统一文件夹。允许使用子文件夹组织文档但必须保证每份帮助文档与其元数据位于同一目录下否则索引器扫描时可能漏检。文档目录与 UFO² 的索引产物目录默认约定如下源文档目录任意你指定的路径例如path_of_the_docs索引产物目录默认输出到vectordb/docs/下与仓库中的 vectordb/docs 目录对应。四、第三步使用 learner 创建离线索引器组织好文档后在克隆的 UFO 仓库根目录执行以下命令构建离线 RAG 索引python -m learner --app app_name --docs path_of_the_docs命令行参数详解依据 learner/learner.py 中的 argparse 定义参数默认值说明--app./应用名称用于索引文件命名与后续在线检索匹配--docs./帮助文档所在文件夹路径--formatjson帮助文档格式当前支持jsonxml已预留--incrementalFalseflag开启增量更新新文档与既有索引合并--save_path./vectordb/docs/索引保存路径--app必须使用应用的精确进程名例如 Microsoft Word 填WINWORD.EXE、PowerPoint 填POWERPNT.EXE。这一约束至关重要app_name会用于在线 RAG 阶段与目标应用进程的匹配定义不准确将导致运行时无法命中索引器。索引构建的底层流程执行python -m learner后learner/indexer.py 中的DocumentsIndexer.create_indexer()依次完成读取记录文件加载learner/records.json不存在则初始化为空字典该文件维护应用名 → 索引绝对路径的映射加载文档根据--format从_doc_loader_mapper选择JsonLoader或预留的XMLLoader调用construct_document()将每个 JSON 文件转换为 langchainDocument构建向量库使用 Hugging Face embeddingget_hugginface_embedding()默认基于 sentence-transformer 模型将文档向量化并通过FAISS.from_documents()构建 FAISS 向量库增量合并若开启--incremental且records.json中已存在该应用的旧索引则通过FAISS.merge_from()将新旧索引合并落盘与登记索引保存到vectordb/docs/app_name绝对路径随后更新records.json记录。db FAISS.from_documents(documents, embeddings) if incremental: if app in records: prev_db FAISS.load_local(records[app], embeddings, allow_dangerous_deserializationTrue) db.merge_from(prev_db) db_file_path os.path.join(save_path, app) db.save_local(db_file_path) records[app] db_file_path完成索引后终端会输出Indexer for app created successfully. Save in path.的绿色提示。五、配置在 rag.yaml 中启用离线文档检索索引创建完毕后需在 RAG 配置中启用离线文档检索开关。配置文件位于 config/ufo/rag.yaml涉及的两个核心参数如下与 Learning from Help Documents 中的参数表一致配置项类型默认值说明RAG_OFFLINE_DOCSBooleanFalse是否启用离线帮助文档检索RAG_OFFLINE_DOCS_RETRIEVED_TOPKInteger1每个子任务召回的文档数量最小启用配置# config/ufo/rag.yaml RAG_OFFLINE_DOCS: True RAG_OFFLINE_DOCS_RETRIEVED_TOPK: 1完整 RAG 配置示例含全部知识源# Offline docs RAG_OFFLINE_DOCS: True RAG_OFFLINE_DOCS_RETRIEVED_TOPK: 1 # Online search RAG_ONLINE_SEARCH: True BING_API_KEY: ${BING_API_KEY} RAG_ONLINE_SEARCH_TOPK: 5 RAG_ONLINE_RETRIEVED_TOPK: 1 # Experience RAG_EXPERIENCE: True RAG_EXPERIENCE_RETRIEVED_TOPK: 5 EXPERIENCE_SAVED_PATH: vectordb/experience/ # Demonstration RAG_DEMONSTRATION: True RAG_DEMONSTRATION_RETRIEVED_TOPK: 5 DEMONSTRATION_SAVED_PATH: vectordb/demonstration/注BING_API_KEY默认读取环境变量${BING_API_KEY}不要将密钥硬编码进配置文件。RAG 功能整体为可选能力——即使全部关闭UFO² 依然可以正常工作只是对复杂或领域化任务的执行质量会打折扣。完整参数说明与场景化配置组合可参考 RAG 配置指南。Top-K 取值建议字段建议范围说明RAG_OFFLINE_DOCS_RETRIEVED_TOPK1–2帮助文档通常篇幅较长1~2 篇已足够提供上下文RAG_ONLINE_SEARCH_TOPK3–10越大上下文越丰富但检索越慢RAG_EXPERIENCE_RETRIEVED_TOPK3–5召回最相关的历史经验RAG_DEMONSTRATION_RETRIEVED_TOPK1–3演示示例通常只需少量若出现 token 超限或响应缓慢的上下文过多问题优先下调各RETRIEVED_TOPK数值。六、运行时检索链路从配置开关到提示词注入当RAG_OFFLINE_DOCS: True时UFO² 在运行时的完整检索链路如下1. 加载离线检索器context_provisionAppAgent 启动时会调用context_provision()见 ufo/agents/agent/app_agent.py。当检测到ufo_config.rag.offline_docs为真时控制台打印 Loading offline help document indexer for 进程名...随后调用build_offline_docs_retriever()self.offline_doc_retriever self.retriever_factory.create_retriever( offline, self._app_root_name )注意这里传入的是_app_root_name应用进程的根名称RetrieverFactoryufo/rag/retriever.py依据retriever_type offline实例化OfflineDocRetriever。2. 定位索引路径records.json 匹配OfflineDocRetriever.__init__接收app_name并通过get_offline_indexer_path()定位索引offline_records get_offline_learner_indexer_config() for key in offline_records: if key.lower() in self.app_name.lower(): return offline_records[key]其中get_offline_learner_indexer_config()ufo/config/init.py直接读取构建索引时写入的learner/records.json。匹配是大小写不敏感的子串匹配只要应用根名称包含记录中的 key即可命中对应索引。这解释了为何--app必须与真实进程名保持一致——它是连接索引构建与在线检索的唯一纽带。随后通过FAISS.load_local(path, get_hugginface_embedding(), allow_dangerous_deserializationTrue)加载向量库若加载失败例如索引路径不存在检索器优雅降级返回None并在日志中输出警告不会中断任务。3. 子任务级知识召回_knowledge_retrieval在处理每个子任务时app_agent_processing_strategy.py 中的_knowledge_retrieval()会调用agent.external_knowledge_prompt_helper(subtask, offline_docs_retrieved_topk, online_retrieved_topk)将当前子任务作为查询文本对离线索引执行similarity_search(query, top_k, filterNone)基类 Retriever.retrieve按向量相似度召回 Top-K 篇帮助文档。若索引为空则返回空列表。4. 注入提示词召回的文档内容作为offline_docs与其他知识经验、演示、在线搜索一起拼装进dynamic_knowledge通过message_constructor注入 AppAgent 的上下文提示词app_agent_processing_strategy.py。此后 LLM 在做 UI 控制决策时就能参考帮助文档中的分步指引并结合当前屏幕截图与控件信息将通用步骤适配为具体可执行的 GUI 操作。七、工程实践要点与注意事项应用名准确性是匹配前提索引构建--app与运行时应用进程根名称必须匹配OfflineDocRetriever的匹配逻辑为大小写不敏感的包含判断命名混乱如大小写、前后缀不一致会导致索引无法命中。参考而非指令的定位召回文档可能并非完全契合当前任务因此帮助文档只作为计划生成的参考依据AppAgent 会结合实时界面状态灵活适配避免机械照搬导致执行失败。增量更新的使用当帮助文档持续迭代时使用--incremental可在不重建全部索引的前提下将新文档并入既有 FAISS 索引降低维护成本。Top-K 与上下文预算的权衡帮助文档通常较长建议RAG_OFFLINE_DOCS_RETRIEVED_TOPK保持 1–2避免挤占提示词上下文窗口。索引文件管理索引产物默认保存在vectordb/docs/映射关系持久化于learner/records.json若删除或移动了索引目录需同步更新记录文件或重新执行索引命令。八、相关文档Knowledge Substrate 总览 —— 理解 RAG 整体架构与四类知识来源帮助文档提供指南 —— 本文所述三步准备流程的完整原文RAG 配置指南 —— 全量 RAG 参数、场景组合与排障方法增强 AppAgent 能力总览 —— 对比演示教学、应用原生 API 封装等其余增强手段核心源码learner/learner.py、learner/indexer.py、learner/json_loader.py、ufo/rag/retriever.py、ufo/agents/agent/app_agent.py核心配置config/ufo/rag.yaml【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
