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 result=process_autosar_markdown(input_md_path="template/AUTOSAR_SWS_Dcm.md",output_dir="output",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. 返回 ChunkingResult

4. 第一步：解析参数并准备输出环境

入口首先把input_md_path和output_dir转成绝对路径，然后复制并合并三类配置：

DOCUMENT_METADATA CHUNK_METADATA_DEFAULTS CHUNKING_CONFIG

如果调用方传入document_metadata、chunk_metadata_defaults、chunking_config或profile_override，则使用入参覆盖默认值。入口还会强制设置generate_questions=False，保证当前流程只做切分，不生成问题。

随后根据输入文件名推导文档级 metadata：

source_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树，并把章节信息写回每个 block：

section_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。

主要字段包括：

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_blocks

9.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_generation

CP 文档中重点关注这些表格类型：

requirements_tracing、api_parameter、api_error、error_mapping、config_parameter、generic_table

Requirements Tracing 表进入 traceability 逻辑；api_error、error_mapping 表辅助生成 error_code；config_parameter 表辅助生成 ECUC 配置证据。

9.3 Figure 增强

图片只基于 caption、正文引用和附近上下文判断是否入库，当前模式是caption_only。没有 caption、没有引用、没有有效上下文的图片会被标记为image_noise，并设置enabled_for_ingest=False。

9.4 API 候选增强

如果 paragraph 或 table 中出现多个 API 字段标签，例如 Kind、Symbol、Scope、Syntax、Parameters、Return value、Errors、Description，则标记api_candidate=True。真正的 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 SemanticUnit

AutosarCpSwsStrategy.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 regions

blocked 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 Unit

build_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 Unit

build_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

核心映射关系：

典型优先级：

所有 chunks 会按global_order_start、global_order_end排序，然后重新设置chunk_order、previous_chunk_id、next_chunk_id。因此最终 JSONL 的顺序与原文语义顺序一致。

14. 第十一步：写出结果文件

如果export_debug=True，会写出：

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/*.md

chunks.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

重点检查字段：

16. 返回结果

入口最后返回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 的主要差异

CP 的核心链路可以概括为：

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 保持一条一个 chunk，BSW 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 表被误判成 requirement？

block parser 阶段只有 paragraph 能升级为 requirement；table_detector 阶段表格里的 requirement ID 只作为 traceability/reference metadata。因此 Requirements Tracing 表最终进入 traceability 逻辑，而不是 requirement 逻辑。

Q4：Classic 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。

Q5：ECUC 配置参数如何识别？

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。

Q7：为什么错误码识别要限制 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 固定为 0

21. 总结

这套 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 能做质量审计和问题定位