企业官网建设流程全解析

• AI 应用
• AI 写作
• 人工智能
• AI Agent
• 企业应用

本文以 使用说明/使用/06-常见问题.md 为骨架，系统讲解易标（OpenBidKit）AI 标书编写工具在使用中最常遇到的六类问题——步骤按钮不可用、文件解析效果差、生成或检查失败、字数不达标、超长知识库解析慢、Word 导出图片缺失——并逐一结合仓库源码与配置项给出可落地的排查路径。读完本文，你不仅能按图索骥解决上述问题，还能理解易标在文件解析、字数控制、图片渲染等环节的底层机制，做到“知其然更知其所以然”。

一、排查前的准备：理解易标的核心工作流程

易标是一款开箱即用的 AI 标书编写工具，其核心流程在 使用说明/使用/01-生成技术方案.md 中有完整介绍，大致链路为：选择招标文件 → 文件解析 → 目录生成与编辑 → 全局事实设定 → 正文生成与导出。绝大多数“按钮点了没反应”“步骤进行不下去”的问题，都源于这条链路上的某个前置环节未真正完成，因此排查时务必先定位当前处在哪一步。

从源码结构看，文件解析由 fileService.cjs 负责，正文生成由 contentGenerationTask.cjs 与 contentGenerationAgent.cjs 承担，它们对每一步都有明确的输入前置条件与状态判定。理解这条链路，是高效排障的第一步。

二、“下一步”不能点击：先确认当前步骤是否真正完成

这是最高频的入口性问题。出现“下一步”置灰或点击无效时，按以下顺序自检：

1. 文件是否已上传成功：文件列表为空或上传尚未完成时，流程无法推进；
2. 解析是否仍在进行：解析进度条未到 100%、状态未变为“完成”时，需要等待；
3. 必填结果是否已生成：例如目录尚未生成、全局事实尚未设定等关键输出缺失时，“下一步”不会放行。

这条规则与源码中“每个环节先校验输入再放行”的设计一致——解析服务会先判定文件格式是否被当前解析器支持（见下文），正文生成任务也会在目录与字数控制配置就绪后才允许进入生成阶段。判断要点就一句话：当前步骤缺了什么、还在跑什么，补全它，按钮自然可用。

三、文件解析效果不好：本地解析与 MinerU 精准解析的取舍

易标内置了多套文件解析方案，配置入口在设置 → 组件设置。从 config.ts 的类型定义看，文件解析器共有三种 provider：

在 SettingsPage.tsx 中可以看到界面提示：招标文件大多是 Word 或 Word 导出的带文字层 PDF，本地解析可以适应 95% 以上的情况；如果解析失败，再尝试 MinerU 精准解析 API。选择mineru-accurate-api后还需填写MinerU Token，代码中对应components.file_parser.mineru_token配置项。

从 fileService.cjs 的实现可以确认三点底层机制：

• 每种解析器有各自的受支持扩展名集合（mineruAgentSupportedExtensions/mineruAccurateSupportedExtensions），不支持的格式会直接报“当前解析方式不支持该文件格式”；
• 解析前会做支持性检查，检查结果（parser.supported、fallback_to_local）会被写入解析日志，便于回溯；
• MinerU 云端解析走mineru.net的 API 通道，包括上传申请、任务轮询、结果下载三个环节，轮询超时或鉴权失败都会抛出明确错误。

因此排查解析问题的标准动作是：

1. 先确认文件本身能正常打开（排除文件损坏）；
2. 普通文件确认当前使用的是本地解析；
3. 扫描件或本地解析失败的复杂文档，到设置 → 组件设置切换为 MinerU 精准解析 API，并检查 Token 是否填写正确、网络是否可达；
4. 若更换解析器后仍失败，结合任务日志中记录的parser_provider、fallback_to_local等信息判断是哪一环出错。

四、生成或检查失败：文本模型测试与智能体自检的联动排查

当正文生成或查重、废标项检查等环节报错时，官方 FAQ 给出的第一动作是：先到 设置 → 文本模型 点击“测试”。这一步能快速区分问题在模型层还是在流程层：

• 若文本模型测试失败，说明 API Key、Base URL、模型名或网络配置存在问题，应回到 配置文本模型 核对各项参数；
• 若模型测试通过但提示“智能体异常”，再到设置 → 智能体配置点击自检，按自检报告处理。

“智能体自检”并非黑盒操作，其实现位于 piSelfCheckService.cjs：它会创建标准自检步骤列表，包含自动诊断环节，在 Pi 实际 Shell 环境中逐项执行共享命令，关键命令失败即判定自检失败；随后会执行普通文本请求、流式文本请求、工具调用等多项探测（probe），并将结果汇总为脱敏的自检报告（Markdown 格式，包含自动诊断结论、规则诊断与文本模型分析等）。自检失败时还会匹配内置诊断规则、结合诊断数据定位根因，并给出推荐修复动作。

换句话说，自检报告就是一份“面向智能体的体检单”：它验证的是文本模型能否正常对话、流式模式是否可用、工具调用是否完整、工作区是否可写。按报告中的recommended_action_ids与manual_actions逐项处理，即可覆盖绝大多数“生成或检查失败”的场景。

五、生成字数没有达到设置值：字数控制机制与目录重生成的正确姿势

字数不达标是长文档生成中最容易困惑的问题，需要先理解易标的字数控制模型。

5.1 字数设置的自动保存与生效时机

在设置 → 组件设置或生成设置页中修改的字数参数会自动保存，这一点与普通表单不同。关键约束是：目录已经生成后，修改字数设置不会对旧目录生效，必须重新生成目录。这一点在 GenerationSettingsPage.tsx 中有明确提示：“生成目录后若修改了字数设置，需要重新生成目录才能生效”。

5.2 字数参数体系

生成设置页提供三个核心维度（见 GenerationSettingsPage.tsx 中的“全文字数/页数预设”区）：

填写约定：填 2 代表 20000 字，填 0.15 代表 1500 字。此外还提供“字数不达标修复”开关（对应配置项wordCountRepair）：开启后，正文生成完成时按全文字数范围进行扩写或缩写；关闭时只统计字数、不做调整。

5.3 底层实现：字数是如何被“编排”出来的

易标的字数控制是编排期分配 + 生成期校验的双层机制，从 contentGenerationAgent.cjs 的提示词与 layoutBudget 目录源码可以看得很清楚：

• 目录生成阶段会为每个小节分配content_plan.target_words（目标字数），0 表示不设目标；正文 Agent 被明确要求“按本节 target_words 安排篇幅，不能用全文上下限或其他小节字数代替本节目标”，且“目标已经在编排阶段分配，不再自行分摊全文目标”；
• 所有并发生成结束后，主 Agent 调用check-word-count工具（实现在 contentGenerationWordTools.cjs），统计时排除 HTML 标签、配图提示词及未完成文件，返回总字数、上下限与差额；
• 差额较大时生成扩缩写.json任务并调用adjust-sections调整；差额较小时由主 Agent 直接微调；调整后重新计数并提交真实结果。

这也解释了为什么 FAQ 强调“最终字数仍会受目录结构和内容完整性影响”：目标字数早在目录编排阶段就按小节分配完毕，若目录本身章节很少、每节内容自然就短，正文生成阶段只能围绕既定结构尽力贴近目标，无法凭空补足。强控小节字数（v2 版本新增，可将单节控制在目标值正负 20% 范围内并预估成稿页数，见 v2版本更新日志.md）能加强控制力度，但同样不能突破目录结构的天然约束。

5.4 实操结论

• 已生成目录后再改字数 →重新生成目录，让新设置参与编排；
• 想提升达标率 → 开启“字数不达标修复”与“强控小节字数”；
• 仍不达标 → 优先检查目录结构是否过简、小节目标分配是否合理，而非一味调大总字数。

六、超长知识库文档解析很慢：分段处理与耐心等待的正确姿势

知识库导入超长文档（如数万字的招标文件、行业规范）时，易标会自动分段处理，因此耗时较长是正常现象，不是死机或卡死。正确做法是：

1. 保持软件运行，不要中途关闭窗口或切换任务导致解析中断；
2. 等待进度达到 100% 且状态变为“完成”，以状态字段而非进度条观感为准；
3. 不要重复上传同一文件——重复上传会触发多次解析，既拖慢进度又可能造成知识库重复条目。

从源码看，文档解析链路（fileService.cjs）本身就包含多阶段工作：格式支持校验 → 调用对应解析器（本地或 MinerU 云端）→ 任务轮询 → Markdown 结果下载与入库，云端解析还受网络往返与轮询间隔影响。超长文档在分段后每一段都要走完这一链路，总体耗时呈线性增长，属于预期行为。若某一段解析持续失败，则回到第三节的解析器排查流程，先确认文档本身可读、再考虑切换解析方案。

七、导出的 Word 图片不完整：本地转换、并发量与生图模型的协同

导出 Word 时图片缺失或不全，原因通常不是 Word 模板问题，而是图片来源链路中的某一环没有跑通。易标导出的图片按来源分三类，排查要点各不相同：

7.1 本地转换类图片（Mermaid 图、HTML 配图）

Mermaid 流程图和 HTML 排版图是在本地完成渲染与截图的，因此依赖“组件设置”中的两项并发参数（见 SettingsPage.tsx）：

对应的底层配置项为components.mermaid_concurrency_limit与components.html_concurrency_limit（定义见 config.ts）。并发量过低时，大批量配图导出会明显变慢甚至超时；本地渲染环境异常时，则会出现整类图片缺失。

7.2 AI 生成图片

AI 图片依赖生图模型可用与网络正常。生图模型配置在设置 → 生图模型（参考 配置生图模型），类型包括 jinlong、volcengine、google-ai-studio、agnes、custom、comfyui 等（见 config.ts 的ImageModelProvider）。若生图模型未测试通过或余额不足、网络抖动，AI 图片就会在生成环节失败，进而导致导出缺图。

7.3 处理与重导出的正确姿势

FAQ 给出的最终动作是：根据导出进度提示处理失败项后重新导出。易标的导出服务会逐项报告失败原因（失败项及其归属类型），据此分类处理：

• 本地转换类失败 → 检查组件设置的转换并发量，必要时调高后重试；
• AI 图片失败 → 先到生图模型页测试连通性，确认模型可用、网络正常后再重导；
• 重复出现的个别失败项 → 定位到具体小节，检查该处配图块是否在正文生成阶段就未被正确写入（可参考 contentGenerationTask.cjs 对图片块的校验逻辑）。

八、总结：一套可复用的排障方法论

把六类常见问题放到一起看，易标的排障其实遵循同一条主线——先定位环节，再验证依赖：

1. 定位环节：问题发生在解析、模型、字数编排、图片渲染中的哪一层？依据任务日志、进度状态、导出提示判断；
2. 验证依赖：该环节的前置条件是否满足？——文件是否可读、解析器是否支持该格式、文本模型测试是否通过、生图模型是否可用、转换并发量是否合理、目录是否已按新设置重新生成；
3. 对照自检：涉及智能体异常时，优先用设置 → 智能体配置 → 自检生成的脱敏报告定位根因，而不是盲改配置；
4. 按证据处理：每次调整后重新触发对应环节，观察是否真正解决，避免“重复上传、反复点击”等无效操作。

以上排查路径均可结合仓库源码进一步验证：解析链路见 fileService.cjs，配置项定义见 config.ts，字数控制与扩缩写机制见 contentGenerationAgent.cjs 与 layoutBudget 目录，智能体自检见 piSelfCheckService.cjs。掌握这些底层实现，不仅能让常见问题“一次修好”，也能在遇到新问题时快速定位根因。

• AI 应用
• AI 写作
• 人工智能
• AI Agent
• 企业应用