ARTICLE · 1270680
离线数仓开发插件拆解第六篇 | 任务结束后如何将知识和记忆存下来
目录
• 上线完成以后，为什么还要留一份知识[2] • P6 先判断这次改动要不要进语义层[3] • 进入语义层必须由用户拍板[4] • finish 触发的是任务知识回写[5] • 一张知识卡从哪些产物里来[6] • 幂等、版本和双轨发布[7] • 回写失败为什么不回滚任务[8] • 自动回写能留下什么，不能替代什么[9]
上线完成以后，为什么还要留一份知识
一张表上线以后，眼前的问题解决了。几个月后，另一个开发者要改同一张表，想知道 active_flag 从哪来，为什么用户键按主键处理，调度为什么放在凌晨两点，测试和部署记录在哪个工单。如果这些答案只藏在当时的会话和某位开发者的记忆里，重新找回来要花不少时间。
流水线的 P5 已经留下了设计、DDL、测试、部署和交付摘要。P6 要做的是把这次交付里值得长期保留的部分整理出来。一部分是语义层，处理指标、维度和模型口径。另一部分是任务知识卡，记录这张表解决什么问题、包含哪些字段、来源是什么、怎样调度和曾经怎样验收。
这两部分有不同的决策方式。语义层会影响后续查询和指标复用，需要用户判断这次是否进入。任务知识回写发生在工单完成之后，可以自动整理，但不能自行编造口径。
P6 先判断这次改动要不要进语义层
不是每个离线任务都需要新增指标或修改语义模型。一次 ETL 修复、一次临时表迁移，可能只要交付代码和测试证据。指标、特征或公共层改动，通常需要把口径登记到语义层，后续报表和查询才能引用同一份定义。
流水线让模型先出建议书，写清是否更新、为什么这样判断，以及拟更新哪些模型、指标、维度或 YAML。建议书只是决策材料，还没有执行发布。用户可以确认进入，也可以不进入。
场景不同，拟更新内容也不同。指标和报表需求会关注指标口径与维度关系，特征需求会关注样本对齐和版本，公共明细或汇总层需求会关注实体关系和复用边界。场景只是生成建议的起点，具体字段仍然要回到 SDS 和本次交付产物。
如果本次需要更新，语义层要围绕 SDS 里的目标表和字段映射生成内容。每个指标或维度都要能回到本次设计，不能顺手加入一张无关表的字段。生成完成后再交给知识侧做语法检查、版本发布和检索同步。
进入语义层必须由用户拍板
语义模型会影响很多人使用数据的方式。某个字段被登记成指标，后面就可能被报表、接口和临时查询引用。口径写错，影响会超出这张表本身。流水线把进入语义层的决定保留给用户，自动模式也不能绕过。
确认过程要求先展示建议和拟更新项，再把结果写进 _user_confirmation.md。只有确认记录里包含明确标记，语义命令才会执行。没有确认，入口直接返回阻断原因。
执行后会生成 semantic_update_summary.md。摘要记录工单、场景、目标表、拟登记字段、知识来源和更新项。它是一张语义层登记单，不能当成发布成功的证明。真实发布还要经过模型生成、语法校验、知识版本化和检索同步，这些步骤的结果以知识侧产物为准。
mock 模式可以检查确认门和摘要生成是否正常，但不能证明 OpenViking 里已经能搜到这次语义更新。live 模式也要人工抽查最终可见性，不能只看摘要文件是否存在。
finish 触发的是任务知识回写
语义层拍板完成后，工单执行 finish。入口会先跑 P6 出口门，检查交付摘要、语义处理结果和必要产物。检查通过，工单状态变成完成，然后触发知识回写。
回写只处理已经完成的工单。没有完成的工单直接返回 knowledge_not_finished，不会把半成品写进知识库。这个限制很重要。测试失败的 SQL、尚未部署的字段映射和没有确认的语义口径，都不应该被当成稳定知识进入检索库。
自动回写有配置开关。默认开启，也可以显式跳过。finish --no-knowledge 会写一条跳过结果，适合已经确认不需要把本次任务写入知识库的场景。开关可以关闭自动同步，后面修好环境再单独重试，不需要把开发任务重新跑一遍。
自动回写配置要指向知识库项目与运行入口，并设置合理的超时时间。找不到知识目录或执行入口时，工单会收到 knowledge_kb_missing，不会假装已经写入。部署流水线的环境要提前把这项配置检查好，不能等任务全部结束后才发现知识库路径不可用。
一张知识卡从哪些产物里来
开发流水线不直接改知识库正文。它先把本次任务已经确认的内容整理成 knowledge_update_request.json，再交给知识库的幂等 ingest 接口。知识库是唯一写入方，负责渲染、审计和发布。
知识卡主要取下面这些内容。
dp_task/ | ||
回到 ads_user_act_di，知识卡会保留 user_id 和 active_flag 的来源，dwd_user_di 作为上游，日分区与调度时间，以及本次任务的设计、测试和部署产物。它不需要复制全部聊天记录，也不会把模型当时的临时分析写进去。
自动整理只使用已经落盘的产物。DDL 里没有写清的字段类型，解析后可能显示未知。测试记录只证明执行过，不能自动变成业务上的永久结论。知识库收到卡片后仍然要渲染成固定章节，检查是否残留 待补、TODO 或断链，再决定能不能发布。
幂等、版本和双轨发布
同一张表可能因为多次任务产生多张知识卡。重复执行 finish 时，系统不能每次都新增一份完全相同的文档。
知识库用任务来源、任务编号、表名和内容指纹组成幂等键。同一份内容再次提交，返回 reused=true，不重复发布。内容变化时保留旧文档备份，再生成新的 kb-vN 版本。这样多跑一次不会多出一堆相同文档，真有变化也还能回到旧版本。
发布分两条路。一条是 Git 版本，把文档提交到知识内容仓库，并保留版本标签。另一条是 OpenViking，把结构化文档同步到检索库。配置了消费方索引时，还会同步索引，让开发项目侧能够查到最新文档。
自动回写结果写进 knowledge_update_result.json。成功结果会带版本、内容 URI、内容指纹、审计编号和消费索引同步状态。推送远端失败时，本地提交和 OpenViking 发布不一定一起消失，结果里会单独标明失败环节，后续可以重试，不能只留一句笼统的成功或失败。
回写失败为什么不回滚任务
代码已经测试、部署和交付，知识同步因为 Git 远端不可达、OpenViking 连接失败或文档审计不通过而报错，这是交付后的独立问题。把已经上线的表重新标记为未完成，会制造新的状态冲突。
流水线因此采用完成状态与知识同步结果分开记录的方式。工单保持 finished=true，回写结果进入 knowledge_update，失败原因和门名写入 knowledge_update_result.json。开发者可以从失败点继续修配置、补产物或重试同步。
这不代表失败可以忽略。成功的开发任务应该带一份可检查的知识回写结果。需要交付审计时，要确认结果不是跳过、不是未找到知识库，也要确认版本、URI 和消费索引状态符合预期。
自动回写能留下什么，不能替代什么
自动回写适合记录单张表的事实。目标表、字段来源、验证数字、DDL、调度和验收口径都能从已完成产物里整理出来。这些内容在后续找表、改表、排查上游和复用口径时很有帮助。
它不能替代完整域建模。一个领域里的实体关系、公共口径和跨表边界，需要专门的知识库生成与人工治理流程。自动回写也不会替业务确认指标含义，只会记录本次已经确认的映射。业务口径本身错了，知识卡会把错误写得更清楚，也会传播得更快。
常见失败要能直接定位。请求字段或任务状态不合格时看 auto_ingest_request，知识卡渲染后审计不通过时看 auto_ingest_audit，Git 或 OpenViking 发布失败时看 auto_ingest_publish。错误门不同，修复动作也不同，不能统一重跑一遍碰运气。
知识卡必须有审计、有版本、有可见的写入结果。Git 推送、OpenViking 同步和消费索引任何一环出问题，都要能在结果里看见。消费索引没有同步成功时，也要明确标成未同步，不能把知识库主体发布成功说成开发项目已经能检索到。
失败可以稍后重试，记录不能模糊。
下一篇是系列收口，会讲怎么把离线数开流水线放进真实团队。包括交互模式与自动模式怎么选、首个试点任务从哪里开始、哪些角色负责确认，以及推广时最常见的误用。
项目地址 MrSuiChuan/data-development-pipeline[1]许可证 Apache-2.0
引用链接
[1] MrSuiChuan/data-development-pipeline: https://github.com/MrSuiChuan/data-development-pipeline离线数仓开发插件拆解第四篇 | 架构设计和数据研发阶段详解
