AUTOSAR CP 文档切分方法说明 AUTOSAR CP 文档语义切分说明本文按process_autosar_markdown()的真实执行顺序说明 AUTOSAR CP SWS 文档的切分链路先做什么、为什么做、怎么做以及每一步的产出是什么。文档采用正式技术说明口径。1. 模块定位platform/autosar_chunker是一个本地规则化语义切分引擎。对于 AUTOSAR CP SWS 文档它不是按固定长度切片也不依赖大模型判断语义而是把 Markdown 文档转换成以下结构化链路Markdown 原文 - MarkdownBlock - SectionNode - AutoDocumentProfile - SemanticUnit - Chunk - 输出文件CP SWS 的切分重点是规范性 requirement 保持一条一个 chunk。Requirements Tracing 表保留父子需求关系。Classic BSW C API 单独建模。ECUC、Container、Parameter、Pre-compile、Link-time、Post-build 等配置证据单独保留。E_OK、E_NOT_OK、DET、DEM、NRC、Development Error、Service ID 等错误行为证据单独识别。front matter、contents、change history、disclaimer 等低价值区域进行降权或过滤。当前链路只负责本地切分不调用 LLM、视觉模型、RAGFlow API不做 embedding、rerank、向量库写入也不生成 questions。2. 主入口统一入口是fromplatform.autosar_chunker.pipelineimportprocess_autosar_markdown resultprocess_autosar_markdown(input_md_pathtemplate/AUTOSAR_SWS_Dcm.md,output_diroutput,profile_override{platform:CP,spec_type:SWS,module:Dcm,release:R22-11,},)入口函数只负责编排不把所有规则写死在一个函数里。解析、画像识别、block 增强、策略选择、语义单元构建、chunk 生成、输出校验分别拆在不同模块中。3. 总执行顺序process_autosar_markdown()的执行顺序如下1. 解析输入路径和输出路径合并 metadata、defaults、config 2. 创建 normalized、debug、chunks、chunks_md、reports 输出目录 3. load_markdown 读取 Markdown 原文 4. normalize_markdown 规范化 Markdown 文本 5. parse_markdown_blocks 解析为有序 MarkdownBlock 6. build_section_tree 构建章节树并把章节信息写回 block 7. detect_auto_profile 识别文档画像并标注 doc_region 8. enrich_requirement_blocks 增强需求块 9. enrich_table_blocks 增强表格块 10. enrich_figure_blocks 增强图片块 11. enrich_api_blocks 标记 API 候选块 12. select_chunk_strategy 选择 autosar_cp_sws 策略 13. AutosarCpSwsStrategy.build_units 构造 SemanticUnit 14. _blocks_from_semantic_units 恢复参与切分的 block 流 15. bind_contexts 绑定局部上下文 16. build_chunks_from_units 生成最终 Chunk 17. 写出 debug 文件 18. 写出 chunks.jsonl 19. 写出 chunks_md 20. validate_output_consistency 校验输出一致性 21. write_ingest_report 生成质量报告 22. 返回 ChunkingResult4. 第一步解析参数并准备输出环境入口首先把input_md_path和output_dir转成绝对路径然后复制并合并三类配置DOCUMENT_METADATA CHUNK_METADATA_DEFAULTS CHUNKING_CONFIG如果调用方传入document_metadata、chunk_metadata_defaults、chunking_config或profile_override则使用入参覆盖默认值。入口还会强制设置generate_questionsFalse保证当前流程只做切分不生成问题。随后根据输入文件名推导文档级 metadatasource_file stem.pdf source_markdown_file input_md_path.name source_original_file stem.pdf然后创建输出目录output/normalized output/debug output/chunks output/chunks_md output/reports这些目录分别保存规范化 Markdown、中间调试数据、最终 JSONL、逐片 Markdown 和质量报告。5. 第二步读取并规范化 Markdown入口调用load_markdown()读取原文检查路径是否存在、是否是文件、是否能用 UTF-8 读取。随后调用normalize_markdown()主要做统一换行符。调用clean_autosar_text清理 AUTOSAR 文本噪声。压缩过多连续空行。保留原文结尾换行语义。规范化结果写入output/normalized/doc_stem.normalized.md这一步的目的是让后续 parser 基于稳定输入工作。如果后续切分异常应先检查 normalized 文件是否保留了章节号、需求 ID、表格和 API 字段。6. 第三步解析 MarkdownBlock入口调用parse_markdown_blocks()按原文顺序把 Markdown 转成MarkdownBlock。每个 block 包含block_id、global_order、type、text、line_start、line_end、metadata支持的 block 类型包括heading、paragraph、requirement、table、image、figure_caption、list、code_block解析顺序是heading - code_block - HTML table - Markdown table - image - figure_caption - list - paragraph关键规则是只有 paragraph 可以升级为 requirement。这样可以避免 Requirements Tracing 表、API 参数表、目录、变更历史中的 SWS/RS ID 被误判为规范性需求。7. 第四步构建章节树入口调用build_section_tree()根据 heading 构建SectionNode树并把章节信息写回每个 blocksection_number、section_title、section_path、section_level、parent_sections、top_level_chapter例如7 Functional Specification 7.2 Diagnostic Session Control 7.2.1 General behavior章节树的目的是让后续逻辑知道每个 block 位于哪个文档区域。CP 文档里同样的表格或 ID 在不同章节含义不同Requirements Tracing 区域中的表格应生成 traceability 证据。Functional Specification 区域中的 requirement 是主需求证据。API Specification 区域中的 Service ID、Return value、Reentrancy 是 API 证据。ECU Configuration 区域中的 Container、Parameter 是配置证据。Contents、front matter、change history 通常需要过滤或降权。8. 第五步识别文档画像和 doc_region入口调用detect_auto_profile()识别AutoDocumentProfile。主要字段包括字段说明platformAP、CP 或 UNKNOWNspec_typeSWS、RS、TPS、ECUC 等release标准版本例如 R22-11module模块名例如 Dcm、Dem、NvM、CanIfapi_styleCP 通常是classic_bsw_c_apiconfig_styleCP 通常是classic_ecucrequirement_prefixes需求前缀例如SWS_Dcmdetected_api_names识别到的 BSW API 名detected_error_codes识别到的错误码detected_config_terms识别到的配置术语doc_regions章节到文档区域的映射CP 平台识别主要参考Classic Platform、Basic Software、BSW、RTE、ECU Configuration、ECUC、BSW Module、CanIf、PduR、ComM、Dcm、Dem、NvM、SchM、Det、Service ID、Reentrancy 等信号。CP API 风格识别主要参考Std_ReturnType、_Init、_MainFunction、_GetVersionInfo、Service ID、Reentrancy、Synchronous、Asynchronous、E_OK、E_NOT_OK。CP 配置风格识别主要参考ECU Configuration、ECUC、BSW Module Configuration、ECUC parameter definition。doc_region是后续防误判的关键。同样出现 SWS ID在 Functional Specification 中可能是规范需求在 Requirements Tracing 中是追溯关系在 Contents 或 Change History 中则不应作为主证据。9. 第六步增强 block metadata入口按顺序执行enrich_requirement_blocks enrich_table_blocks enrich_figure_blocks enrich_api_blocks9.1 Requirement 增强识别 AUTOSAR requirement ID并补充requirement_id、requirement_status、requirement_family、requirement_text该增强只处理 paragraph不处理 table避免追溯表中的 ID 被当作规范性需求。9.2 Table 增强给表格补充table_id、table_row_count、traceability_ids、referenced_requirement_ids、related_rs_ids、table_type、retrieval_usage、priority_for_generationCP 文档中重点关注这些表格类型requirements_tracing、api_parameter、api_error、error_mapping、config_parameter、generic_tableRequirements Tracing 表进入 traceability 逻辑api_error、error_mapping 表辅助生成 error_codeconfig_parameter 表辅助生成 ECUC 配置证据。9.3 Figure 增强图片只基于 caption、正文引用和附近上下文判断是否入库当前模式是caption_only。没有 caption、没有引用、没有有效上下文的图片会被标记为image_noise并设置enabled_for_ingestFalse。9.4 API 候选增强如果 paragraph 或 table 中出现多个 API 字段标签例如 Kind、Symbol、Scope、Syntax、Parameters、Return value、Errors、Description则标记api_candidateTrue。真正的 Classic BSW C API unit 会在策略阶段生成。10. 第七步选择 CP SWS 策略入口调用select_chunk_strategy(profile)。当满足profile.platform CP profile.spec_type SWS选择AutosarCpSwsStrategy该策略的名称是autosar_cp_sws它的职责是把 CP SWS 文档里的 requirement、BSW API、ECUC 配置、错误码、追溯关系、表格和图示转换成SemanticUnit。11. 第八步构造 CP SemanticUnitAutosarCpSwsStrategy.build_units()的真实构造顺序是1. build_requirement_units 2. build_requirement_group_units 3. build_traceability_units 4. build_classic_bsw_api_units 5. build_service_interface_units 6. build_error_code_units 7. _build_config_units 8. build_figure_units 9. build_table_units 10. build_section_explanation_units 11. _sort_and_deduplicate_units引入SemanticUnit的原因是MarkdownBlock只表示原文结构不一定等于业务语义。例如一个 BSW API 可能跨多个正文块、表格和代码块一个 ECUC 参数可能需要表格和周边说明共同表达Requirements Tracing 表应表达父子需求关系而不是普通表格。11.1 Requirement Unit正式 requirement 满足block.type requirement 且 doc_region 不在 blocked regionsblocked regions 包括 requirements_tracing、contents、front_matter、disclaimer、change_history、appendix_not_applicable_requirements。设计原则是一条规范性 requirement 一个 requirement unit 一个 requirement chunk主要 metadata 包括 primary_requirement_id、requirement_ids、section_path、section_context、lead_context、post_context、bridge_context、sibling_requirement_ids、previous_requirement_id、next_requirement_id、explicit_related_requirement_ids、related_rs_ids优先级为 P0。11.2 Traceability Unit只处理 Requirements Tracing 表。默认按父需求聚合RS_xxx_00001 - [SWS_xxx_00010, SWS_xxx_00011]最终生成traceabilitychunk用于保留上层需求与 SWS 需求的满足关系。11.3 Classic BSW C API Unitbuild_classic_bsw_api_units()会按 API section 聚合 paragraph、code_block、table、list。识别信号包括Std_ReturnType、void、boolean、uint8、uint16、uint32、_Init、_DeInit、_MainFunction、_GetVersionInfo、Service ID、Reentrancy、Synchronous、Asynchronous、E_OK、E_NOT_OK会提取 service_name、api_name、service_id、sync_async、reentrancy、return_type、related_requirement_ids最终生成apichunk优先级为 P1。11.4 Error Code Unitbuild_error_code_units()只允许从 functional_specification、api_specification、service_interfaces 等有效区域生成错误码证据。CP 错误行为信号包括E_OK、E_NOT_OK、DET、DEM、NRC、Development Error、Diagnostic Event、Service ID、Return value最终生成error_codechunk优先级为 P1。11.5 ECUC Config Unit_build_config_units()是 CP 策略的专有配置证据构造逻辑。它扫描 paragraph、list、table、code_block并要求命中ECUC、EcucModuleConfigurationValues、Container、Parameter、Pre-compile、Link-time、Post-build命中后生成config_parameterunit最终转成config_parameterchunk。它用于保留 BSW Module Configuration、容器、参数和配置变体时机。11.6 Table、Figure 和 Section Background有效 figure 会生成figurechunk。普通表格会生成tablechunk大表按行数和字符预算拆分并保留表头。普通章节说明会生成section_background作为低优先级背景证据。最后_sort_and_deduplicate_units()会按原文顺序排序并去重避免 API 表、配置表、错误码表被重复输出。12. 第九步恢复 block 流并绑定上下文入口先从 SemanticUnit 中恢复参与切分的 block_blocks_from_semantic_units然后调用bind_contexts绑定的上下文包括section_intro、lead_context、post_context、bridge_context、related_tables、related_figures、nearby_context_before、nearby_context_after、caption_block目的不是把整节内容塞进 chunk而是给 requirement、table 和 figure 补充有限、可控的局部上下文。13. 第十步SemanticUnit 转 Chunk入口调用build_chunks_from_units()。最终Chunk包含local_chunk_id、chunk_order、chunk_type、content、important_keywords、tag_kwd、metadata、global_order_start、global_order_end、previous_chunk_id、next_chunk_id核心映射关系unit_typechunk_typerequirementrequirementtraceability_row_grouptraceabilityapiapierror_codeerror_codeconfig_parameterconfig_parameterfigurefiguretabletablesection_explanationsection_backgroundrequirement_group不输出image_noise不输出典型优先级chunk_typepriorityrequirementP0apiP1error_codeP1tableP1config_parameterP2section_backgroundP2figureP2traceabilityP2所有 chunks 会按global_order_start、global_order_end排序然后重新设置chunk_order、previous_chunk_id、next_chunk_id。因此最终 JSONL 的顺序与原文语义顺序一致。14. 第十一步写出结果文件如果export_debugTrue会写出output/debug/doc_stem.auto_profile.json output/debug/doc_stem.semantic_units.json output/debug/doc_stem.blocks.json output/debug/doc_stem.section_tree.json随后写出最终产物output/chunks/doc_stem.chunks.jsonl output/chunks_md/*.mdchunks.jsonl按chunk_order写入一行一个 JSON chunk。chunks_md会先删除旧文件再按 chunk 顺序写出逐片 Markdown便于检查内容和 metadata。15. 第十二步输出一致性校验和质量报告所有文件写出后入口调用validate_output_consistency()主要检查chunks.jsonl 是否存在且非空 chunks.jsonl 行数是否等于 expected_total_chunks chunks_md 文件数是否等于 expected_total_chunks blocks.json 是否非空 section_tree.json 是否非空 auto_profile.json 是否非空 semantic_units.json 是否非空随后调用write_ingest_report()生成output/reports/doc_stem.ingest_report.json重点检查字段字段意义output_consistency.matched输出文件是否一致requirements_detected检测到的正式 requirement 数requirements_chunked生成的 requirement chunk 数requirements_missing_chunk_ids检测到但没切出来的需求tables_misclassified_as_requirement表格误判成需求的数量期望为 0traceability_tables_detected追溯表检测数量api_sections_detectedAPI 章节检测数量api_chunks_generatedAPI chunk 数量questions_generated固定为 016. 返回结果入口最后返回ChunkingResult包含input_md_path、output_dir、normalized_md_path、blocks_json_path、section_tree_json_path、auto_profile_json_path、semantic_units_json_path、chunks_jsonl_path、chunks_md_dir、report_json_path、total_blocks、total_semantic_units、total_chunks、total_requirements、total_figures、total_tables、profile、warnings调用方可以直接使用chunking_result.chunks_jsonl_path chunking_result.normalized_md_path chunking_result.report_json_path chunking_result.profile后续 RAGFlow 上传逻辑不需要重复手写路径从而减少跨模块参数不一致。17. CP 与 AP 的主要差异对比项AP SWSCP SWSAPI 风格C API常见 ara::、class、methodClassic BSW C API常见 Std_ReturnType、Service ID、Reentrancy配置风格Manifest、Execution Manifest、Machine Manifest、Model ElementsECUC、BSW Module Configuration、Container、Parameter错误码风格kXxx、ErrorCode、ErrorDomain、ExceptionE_OK、E_NOT_OK、DET、DEM、NRC、Development Error配置证据Manifest / model elementECUC 配置参数主要策略autosar_ap_swsautosar_cp_swsCP 的核心链路可以概括为requirement 原子化 Classic BSW C API 结构化 ECUC 配置证据 CP 错误行为证据 traceability 关系保留 输出一致性审计18. 简要说明口径这个模块是 AUTOSAR CP SWS 的语义切分器。它先把 Markdown 解析成 block再根据章节编号构建 section tree自动识别 CP/SWS 文档画像和 doc_region。之后通过 CP SWS 策略把内容组织成 requirement、Classic BSW C API、ECUC config、Error Code、Traceability、Table、Figure 等 SemanticUnit最后转换成带 metadata 的 Chunk。Requirement 保持一条一个 chunkBSW API 和错误码作为 P1 补充证据ECUC 配置和 traceability 作为 P2 支撑证据。最后输出 chunks.jsonl、chunks_md、debug 文件和 ingest_report用报告检查表格误判、需求漏切、输出一致性和 API 覆盖情况。19. 技术问答Q1为什么 CP 文档不能直接套 AP 策略AP 重点是 ara:: C API、Manifest、Service Interface 和模型元素CP 重点是 BSW C API、Service ID、Reentrancy、ECUC 配置、DET/DEM/NRC 等错误行为。因此 CP 需要独立的autosar_cp_sws策略。Q2为什么 requirement 要一条一个 chunk需求覆盖和测试设计通常以 requirement ID 为最小追溯单元。多个 requirement 合并后会导致覆盖归属不清、测试点混淆、审计困难。因此每条规范性 requirement 保持原子化输出。Q3如何避免 Requirements Tracing 表被误判成 requirementblock parser 阶段只有 paragraph 能升级为 requirementtable_detector 阶段表格里的 requirement ID 只作为 traceability/reference metadata。因此 Requirements Tracing 表最终进入 traceability 逻辑而不是 requirement 逻辑。Q4Classic BSW C API 如何识别系统按 API section 聚合 paragraph、table、code_block、list然后用 Std_ReturnType、Service ID、Reentrancy、Synchronous、Asynchronous、E_OK、E_NOT_OK、_Init、_MainFunction、_GetVersionInfo 等信号提取 API metadata。Q5ECUC 配置参数如何识别CP 策略中的_build_config_units()会扫描 paragraph、list、table、code_block命中 ECUC、EcucModuleConfigurationValues、Container、Parameter、Pre-compile、Link-time、Post-build 后生成config_parameter。Q6现在对markdown文档的切片里面有overlap吗当前 Markdown 切片没有传统 sliding-window overlap但部分语义 chunk 会主动复制相邻上下文形成少量语义级 overlap。类型是否有传统 overlap是否有上下文复制requirement否有section_intro / lead / post / bridgeapi否基本无固定邻接 overlap主要是 API 表格自身重复到多个标题区error_code否无固定 overlapconfig_parameter否可能带 section contextsection_background否否table否有 lead/post context表格拆分时可能重复表头figure否有 before/after context超长 chunk 拆分否只保留 metadata prefix不复制正文 overlapQ7为什么错误码识别要限制 doc_region错误相关词可能出现在目录、变更历史、附录或普通说明中。只有在 functional_specification、api_specification、service_interfaces 等有效区域且具有 CP 错误上下文时才生成 error_code chunk。20. 新文档处理检查清单处理一个新的 CP SWS 文档时按顺序检查1. normalized/*.normalized.md 是否结构正常 2. debug/*.blocks.json 中 block 类型是否合理 3. debug/*.section_tree.json 中 section_path 是否完整 4. debug/*.auto_profile.json 中 platform 是否为 CP 5. debug/*.auto_profile.json 中 spec_type 是否为 SWS 6. debug/*.auto_profile.json 中 api_style 是否为 classic_bsw_c_api 7. debug/*.auto_profile.json 中 config_style 是否为 classic_ecuc 8. debug/*.semantic_units.json 中 requirement 是否一条一个 unit 9. debug/*.semantic_units.json 中 traceability 是否按父需求聚合 10. debug/*.semantic_units.json 中 API / error_code / config_parameter 是否符合预期 11. chunks/*.chunks.jsonl 是否非空 12. chunks/*.chunks.jsonl 行数是否等于 total_chunks 13. chunks_md/*.md 数量是否等于 total_chunks 14. reports/*.ingest_report.json 中 output_consistency.matched 是否为 true 15. reports/*.ingest_report.json 中 tables_misclassified_as_requirement 是否为 0 16. reports/*.ingest_report.json 中 requirements_missing_chunk_ids 是否为空或可解释 17. reports/*.ingest_report.json 中 api_chunks_generated 是否符合文档实际情况 18. 确认 questions_generated 固定为 021. 总结这套 CP 文档切分链路的本质是把 AUTOSAR CP SWS 长文档转换成按原文顺序排列、带完整 metadata、可追溯、可检索、可审计的语义 chunk 集合。核心价值1. 入口 pipeline 清晰阶段职责明确 2. 不依赖 LLM结果稳定可复现 3. requirement 保持原子化适合需求追溯 4. Classic BSW C API、Service ID、Return value 单独建模 5. ECUC、Container、Parameter、Pre-compile、Link-time、Post-build 配置证据单独保留 6. E_OK、E_NOT_OK、DET、DEM、NRC 等错误行为证据单独识别 7. traceability 表保留父子需求关系 8. chunks.jsonl 顺序与原文语义顺序一致 9. report 能做质量审计和问题定位