优化源文档写作规范-j9九游会登录

实践1：使用规范的标题层级组织文档结构

为文档设置清晰的一级、二级、三级标题，使文档具备明确的逻辑层次。标题应简洁准确地概括本节的核心主题，标题文字中应包含该节最重要的关键词，避免使用“方式一”、“补充说明”等无具体语义的标题。

agentarts知识库的层级分段策略专门针对具有明确标题层级的文档设计，会根据文档的目录结构和章节划分信息，将内容按标题边界切分为不同层级的知识单元，每个切片内容完整且主题独立。如果文档缺乏规范标题，系统将退而采用自动分段，切片边界由字符数决定，极易造成语义割裂。此外，标题文本本身也参与向量化，为切片提供额外的语义覆盖，提升检索命中率。

对比示例：

• 不规范写法：将多个独立主题全部挤在一个无标题的段落中，系统只能按字符数强制截断，每个切片都是混杂片段。
• 规范写法：
  每个章节聚焦单一操作，分段后每个切片内容完整、主题独立。

  ## 知识库管理
    ### 创建知识库
      #### 前置条件
      #### 操作步骤
    ### 上传文档
      #### 本地上传方式
      #### 通过 obs 接入方式
    ### 配置检索策略

操作建议：

• 使用word标题样式（标题1、标题2、标题3）或markdown中的#/##/## 语法，而非用加粗文字代替标题。
• 每个标题下的内容应聚焦单一主题，如果一节内容过多且涉及多个子主题，应主动拆分为多个子章节。
• 标题文字应包含用户可能用来提问的关键词。

实践2：保持列表编号的连续性与完整性

在描述操作步骤或枚举项目时，确保编号从1开始且连续递增，不出现跳号、重复编号或中途重置为1。对于包含条件分支的步骤，应使用缩进子编号（如步骤3a / 3b）表示，而非另起一套新的编号序列打乱整体逻辑顺序。每个步骤的描述应包含操作对象、操作路径和操作动作，使单个步骤即便脱离整体也具备可执行性。

当多步骤操作因切片长度限制被分割为多个切片时，连续的编号能够帮助大模型判断切片在整体流程中的位置，从而在回答时提示用户查阅完整步骤，而非误以为切片内容已是操作的全貌。跳号和乱序编号会严重干扰大模型对步骤完整性的判断。

对比示例：

• 不规范写法：

  步骤1：登录平台
  步骤3：选择知识库
  步骤2：进入开发中心
  步骤1：单击创建按钮

• 规范写法：

  步骤1：登录agentarts。
  步骤2：在左侧导航栏中，依次选择……
  步骤3：单击顶部"知识库"页签……
  步骤4：单击右上角"创建知识库"按钮……

操作建议：

• 每个步骤编号后的描述应包含完整的操作路径（如导航栏层级），使单个步骤切片独立可执行。
• 步骤中存在条件分支时，在该步骤下用缩进明确描述每个分支，而非在后续步骤中突然出现跳号。

实践3：添加适当的过渡说明

在分步骤说明中，可以在相邻步骤之间补充简短的过渡说明，明确前后步骤之间的因果关系、操作前提或预期的中间状态。过渡说明应回答两个核心问题：“完成上一步后，系统会发生什么变化？”以及“执行下一步的前提条件是什么？”。

过渡说明的最大价值在于提升切片的语义独立性。即便某一步骤因切片边界被单独截取，切片中的过渡语句仍保留了该步骤在整体流程中的位置信息和前置条件，帮助大模型在没有完整上下文的情况下理解操作意图，避免给出脱离流程语境的片段性回答。

对比示例：

• 无过渡写法

  步骤5：提交报销单
  步骤6：上传发票附件

• 添加适当的过渡

  步骤5：填写并提交报销金额、费用类型和报销事由。
    提交成功后，系统会自动生成报销单编号，单据状态显示为“待补充附件”。
  步骤6：在报销单详情页上传发票、行程单等证明材料。
    附件上传完成后，单据状态将更新为“待审批”，后续进入审批流程。

操作建议：

• 过渡说明2～3句即可，核心包括：操作完成的可见标志（如状态变更）和下一步的入口位置。
• 对于需要等待的异步操作，务必明确说明完成标志，避免用户在操作未完成时提前进入下一步。

实践4：针对预期用户提问，预置引导性问题语句

在文档中针对该节内容最可能被用户以何种方式提问，在章节开头预置一句或几句自然语言形式的引导语，明确指向本节的核心问题。引导语应使用用户真实提问时会使用的日常语言，而非文档作者习惯的专业术语表达。对于faq类文档，应将标准问题以完整句子形式写出，而不仅仅呈现答案。

agentarts知识库提供了faq检索模式，该模式专为问答对格式设计，将用户查询向量与知识库中预存的标准问题向量进行匹配，问题描述越完整、越贴近用户真实提问习惯，语义匹配得分越高，命中率越稳定。即便在语义检索和混合检索模式下，文档切片中出现了与用户查询高度相似的自然语言问题描述时，这两个向量在语义空间中会更加接近，从而获得更高的相似度得分，被优先召回。

对比示例：

• 无引导语写法

  差旅报销标准
    员工出差期间的交通费用按照实际发生金额报销，
    住宿费用按城市级别实行限额标准……

• 有引导语写法

  差旅报销标准
    如果您想了解出差期间交通费和住宿费的报销标准，或者想知道
    不同城市的住宿限额分别是多少，可以参考以下说明。
    员工出差期间的交通费用按照实际发生金额报销，
    住宿费用按城市级别实行限额标准……

操作建议：

• 引导语1～3句即可，核心是将用户可能使用的自然语言提问方式显式写入文档。
• 建议结合agentarts的观测功能，从线上用户的真实历史提问中提炼高频问法，将其转化为引导语预置在对应章节开头。
• 对于faq文档，每条记录的"问题"字段应覆盖用户可能使用的多种提问方式，而不仅仅写一种规范化表述。

实践5：为章节添加内容摘要

在每个一级标题或重要的二级标题下方，紧跟3～5句话的内容摘要，概括本节的核心主题、主要操作对象和关键结论。摘要的语言应精炼且信息密度高，应包含本节涉及的关键术语、核心数值限制、主要操作动作等高价值信息。

摘要会作为该节第一个切片参与向量化，价值体现在两个层面：其一，摘要包含了本节所有关键词的浓缩表达，增加了切片的语义覆盖广度，使得宽泛的宏观问题也能命中相关切片；其二，当用户查询的是概述性问题时，摘要切片能够直接作为大模型生成概述性回答的依据，无需拼凑多个细节切片，提升了回答的连贯性。摘要与正文细节切片共同构成两个层次的语义覆盖：宏观问题由摘要切片承接，细节问题由正文切片承接。

对比示例：

无摘要写法

## 员工考勤管理制度
### 标准工时制
标准工时制是指每日工作8小时……

有摘要写法

## 员工考勤管理制度
本公司考勤管理涵盖三种工时制度：标准工时制（每日8小时，每周40小时）、
综合计算工时制（按周期累计工时）和不定时工时制（适用于外勤岗位）。
迟到、早退、旷工的认定标准及扣罚规则详见各小节。
全勤奖发放标准为当月无迟到、早退、旷工记录。
### 标准工时制
  ……

操作建议：

• 摘要中应主动包含该节涉及的数量限制、版本差异、操作前置条件等关键约束信息。
• 对于包含多个子节的长章节，摘要可以起到导读作用，帮助大模型在单次检索就把握该章节的整体结构，减少多跳检索的需要。

实践6：确保每个切片独立可理解

系统排查文档中所有可能产生歧义的表达，包括但不限于：

• 代词指代不明：将“它”、“该功能”、“此配置”替换为具体名词。
• 同义术语混用：为同一概念选定唯一的规范用词，并在整份文档乃至整个知识库中一致使用。
• 多义词无上下文限定：在使用可能产生歧义的词汇时，用括号补充其在本文档中的特定含义。
• 隐含的假设条件：将默认读者已知的前提条件显式写出，例如“该配置项仅在开启xxx功能的情况下生效”而非“该配置项在满足条件时生效”。

代词指代不明的切片即便被成功检索召回，大模型也无法从中提取出完整且确定的事实，不得不依赖训练数据进行推断，这是在切片层面产生幻觉的直接原因。

对比示例：

有歧义写法

配置完成后，它需要重启才能生效。

无歧义写法

服务器网络配置更新完成后，该服务器需要执行xxx操作重新启动才能使新的网络配置生效。

操作建议：

• 检查“它”、“该”、“此”、“上述”等代词，逐一检查其指代是否在当前切片范围（约500～800字）内清晰可辨。
• 为整个知识库制作统一的术语规范对照表，列明每个概念的规范用词和禁用别名，供所有文档编写人员遵循。

实践7：专有名词补充解释

在文档中每当首次出现企业内部缩写、产品代号、行业专有术语或公司特定流程名称时，需要提供明确的全称与解释。对于整个知识库中高频出现的核心术语，建议单独整理一份“企业术语词典”文档，将其作为独立文件导入知识库，为所有智能体提供统一的术语理解基础，并在每份文档中出现的术语进行解释。

agentarts支持接入deepseek、glm、kimi等多种大模型，这些模型拥有丰富的通用知识储备，但对企业私有知识体系中的专有术语并不了解。知识库是将私有知识注入大模型推理上下文的唯一渠道，如果知识库中缺少术语定义，大模型会用训练数据中的通用含义解释企业特定术语。这是企业rag场景中幻觉发生率最高的来源之一。

对比示例：

缺乏定义写法

完成aml审查后，系统将自动触发t 1交割流程，通过dvp方式完成结算。

含定义写法

在交易执行前及结算前的各环节，均需完成aml（反洗钱审查，anti-money laundering，即对交易双方身份及交易目的进行合规性自动筛查），且确认无异常后，该笔交易方可被纳入t 1（即交易日后第一个工作日，t为trade date， 1指次日）的结算队列。
到了t 1日的规定时点，中央清算系统（通常由中央证券存管机构csd或中央对手方ccp运营）将自动启动交割流程，并强制采用dvp（券款对付结算，delivery versus payment，即证券过户与资金支付在同一时点同步完成、不可撤销）方式，完成最终的钱券交收。

操作建议：

• 整理独立的“企业术语词典”文档单独导入知识库，为所有使用该知识库的智能体提供统一的术语背景。
• 高频术语的问答对单独整理为faq文档入库，使用户以任何方式询问该术语时均能获得标准定义。

实践8：将大型综合文档拆解为小型文档

避免将涵盖多个独立主题的大型文档整体导入知识库。应按照知识单元边界，将文档拆分为每篇聚焦于单一主题的小型独立文档。每篇小文档应具备：清晰的标题（明确表明主题范围）、背景说明（说明适用场景或前提条件）和完整的核心内容（能够独立回答一类特定问题，无需依赖其他文档即可作答）。文档之间的关联关系通过正文中的文字导引保留，而非通过合并文档来体现。

切片策略直接决定了检索的精准度：切得太碎会丢失上下文，切得太大则包含噪音。大型综合文档即便经过智能分段，也往往因为主题跨度过大导致切片内容语义混杂。相比之下，小型文档天然与单一知识单元对应，切片更聚焦、噪音更少、语义更纯粹。从知识库维护的角度看，当某一知识点发生更新时，只需替换对应的小文档并重新解析，而无需在一份大型文档中定位、修改并重新解析整个文档。

对比示例：

大型文档

公司行政管理制度汇总.docx
  // 含"考勤管理"、"差旅报销"、"办公采购"、"会议室预约"、
  // "车辆使用"、"印章管理"、"保密制度"等全部内容，共 120 页

拆解后小型文档

01-员工考勤管理制度.docx              // 5-6 页，聚焦工时制度、打卡规则与全勤奖
02-差旅报销管理办法.docx              // 4-5 页，聚焦报销标准、审批流程与限额
03-办公采购申请流程.docx              // 3-4 页，聚焦采购申请、审批与验收
04-会议室预约与使用规范.docx          // 2-3 页，聚焦预约方式、使用规则与设备管理
05-公务车辆使用管理规定.docx          // 3 页，聚焦用车申请、费用分摊与违规处理
06-公司印章使用与管理办法.docx        // 3 页，聚焦印章类型、审批权限与使用登记
07-信息安全与保密制度.docx            // 4-5 页，聚焦密级分类、保密义务与违规责任

操作建议：

• 每篇文档的拆分粒度标准：能独立回答一类用户问题，不需要依赖其他文档即可完整作答。
• 同类主题的文档统一归入同一个知识库。