OpenMetadata 文档索引与新鲜度体系docs/index.md 如何组织跨仓库技术知识库【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadataOpenMetadata 仓库把分散在docs/、UI、ingestion 与 bootstrap 目录下的设计文档、计划稿、自动生成参考和质量审计记录统一登记在 docs/index.md 中。这篇索引不只是文件清单它为每篇文档标注了“何时该读”、最近修改时间以及基于工作树核对得出的新鲜度结论CURRENT / STALE / SUPERSEDED 等。读完本文你将掌握这套文档知识地图的查法、其背后“生成即门禁”的防漂移机制以及如何通过索引快速定位 impersonation、多节点会话、RDF、日志流式化、UI 双栈规范等核心主题的实现文档。索引的定位先查文档再读代码docs/index.md 开篇即定义了它的用途在反向工程代码或凭空猜测之前先用它找到已有的文档。它登记的知识覆盖了四类来源仓库根级指南不在docs/下CLAUDE.md、ARCHITECTURE.md、DEVELOPER.md、AGENTS.md后端与平台设计文档docs/下认证、会话、RDF、日志流等子系统的设计稿计划与规格docs/plans/、docs/superpowers/已交付或历史性的重构计划仓库外参考文档UI 开发者手册与设计系统规格openmetadata-ui/下、ingestion 诊断设计与数据库迁移体系文档ingestion/与bootstrap/下。索引明确声明了自己的边界它只登记文件不移动、不重链任何文档迁移不在其职责范围内。这保证了索引本身不会成为一次大规模重构的牵涉方。新鲜度评级体系每个结论都引用一个被核实的工件索引顶部给出了一套五级新鲜度判定标准并声明其新鲜度验证是在 2026-07-24 对照工作树逐项完成的“不是按文件年龄推断——每个结论都引用一个被核实仍然存在的工件”评级含义CURRENT其“承重”引用依赖的路径/类/配置项仍然存在且与代码一致STALE引用的路径/类/标志已不存在SUPERSEDED被更新的文档或实现取代在表格行或脚注中注明⚠整体 CURRENT但存在脚注中列出的具体注意事项by construction由源码再生成且受 CI 门禁保护结构上不可能与源码漂移这套体系的关键点在于“举证”一个 CURRENT 结论不是编辑者的主观判断而是对应工件在树中实际存在且匹配的结果。文末的Caveats验证注记一节就是举证记录共 6 条逐条说明某个 CURRENT ⚠ 文档具体“对在哪里、漂移在哪里”详见后文“Caveats 精读”一节。根级指南四个入口文档及其已知差异索引的第一张表登记了不在docs/下的四个根级指南指南定位CLAUDE.md会话常驻指导指向.claude/rules/*与 skills 的指针索引ARCHITECTURE.md系统地图——模块划分、请求/摄取/搜索路径、必须维持的不变量DEVELOPER.md构建、测试、新增实体或连接器的端到端检查清单AGENTS.mdCodex 入口文档——携带已知矛盾Webpack→Vite、antd、Python 版本上限见docs/tech-debt.md#6从当前树可以确认 CLAUDE.md 所指的规则目录.claude/rules/真实存在包含frontend-styling.md、java.md、python-ingestion.md、schema-first.md、migrations.md等 12 个规则文件。值得注意的是索引对 AGENTS.md 的诚实标注它与现行实现存在已登记的矛盾例如 UI 构建工具与组件库演进后未同步这类“已知不一致”被明确指向 docs/tech-debt.md 的对应条目而不是静默忽略——这正是该索引作为知识基础设施的价值。后端与平台设计文档docs/索引登记了 11 篇后端设计文档。以下完整继承其“用途 / 何时该读 / 最近修改 / 新鲜度”四要素文档用途何时该读新鲜度docs/impersonation-design.mdBot→用户伪装updatedBy用户 /impersonatedBybot由allowImpersonation RBACImpersonate策略范围控制触碰 bot 伪装认证——该标志、BotImpersonationPolicy种子、checkImpersonationAuthorization§4.4 为权威版本CURRENT ⚠¹docs/session-management-multi-node-design.md已交付的多节点服务端会话 WebSocket 体系共享 JDBC/Redis 存储、OM_SESSIONCookie、会话绑定的 JWT、CAS 刷新处理跨 Pod 的登录/刷新/登出、SessionService/SessionStore、JWT 会话校验、WebSocket 握手CURRENTdocs/streamable-logs.mdS3/MinIO 支撑的可流式摄取日志HTTP append/close、partial.txt→logs.txt、SSE 实时尾随、废弃 run 清扫器处理摄取日志的存储/流式化——S3LogStorage、LogStorageInterface、/logs/{fqn}/{runId}端点CURRENTdocs/ingestion-log-streaming.mdSSE 实时日志尾随LogStreamEvent模式、断点续传游标、每 run 一个共享 reader、约束每条流的边界条件构建或调试实时尾随摄取日志的客户端——/logs/{fqn}/stream/{runId}、IngestionLogTailer、LogStreamSettingsCURRENTdocs/rdf-local-development.md用 Apache Jena Fuseki 本地运行 RDF/知识图谱支持——启动脚本、环境变量、rdf.*配置、/api/v1/rdf/*、RdfIndexApp搭建或调试本地 RDF/Fuseki 开发环境CURRENTdocs/rdf-production-setup.md远端 Fuseki 三元组存储的生产 sizing/调优——TDB2 堆 vs 页缓存、批量/超时、每周重建、压实为生产 Fuseki 部署做 sizing/排障调优 RDF 批量写入CURRENTdocs/rdf-ontology-contract.mdRDF 谓词可用性、规范血缘方向、扩展键值投影与契约测试新增 RDF 谓词或升级既有 RDF 存储CURRENTdocs/rdf-scale-validation.md全目录 RDF 重建、查询时延、资源采样、中断重建与重启验证复现 RDF 容量测量或评估 #32057CURRENTdocs/csv-relation-types-plan.md通过relationType:termFQN前缀默认relatedTo在 CSV 导出/导入中携带术语关系类型修改术语 CSV 往返——CsvUtil.addTermRelations、GlossaryRepository.getTermRelationsFromCsvCURRENTdocs/auto-classification/add-support-for-another-entity.md分步指南通过EntityAdapter注册表把自动分类PII 样本数据扩展到 schema/Java/Python/UI 全链路的新实体为新实体类型增加自动分类/样本数据支持CURRENTdocs/perf/cdn-deployment-guide.mdAWS 设计提案单个 CloudFront S3 分发按客户/按版本的 UI 包用内嵌 CloudFront Function 路由不用 LambdaEdge规划/评审 UI 包的 CDN 分发 按客户版本固定——属于基础设施设计非既有代码CURRENT未实现提案从源码结构看这些文档覆盖的正是服务端的几条关键链路认证伪装与会话、可观测性日志存储与 SSE 流、知识图谱RDF 本地开发、生产调优、本体契约、规模验证四个文档构成一个完整的 RDF 文档簇以及数据往返术语 CSV。其中 CDN 指南被明确标注为“未实现提案”避免读者误以为仓库里已有对应代码——这是索引对“设计意图 vs 落地状态”的显式区分。计划与规格docs/plans/、docs/superpowers/文档用途新鲜度docs/plans/2026-01-27-search-indexing-stats-redesign.md把SearchIndexingApp统计重构为分阶段管道模型StageStatsTracker/StageCounter、索引别名提升、向量批量处理器CURRENT已交付设计——在触碰搜索重建统计、search_index_server_stats、索引提升、向量索引之前阅读docs/plans/2026-06-22-bulk-deletion-redesign.md按 id 集合快速、无孤儿、可恢复的服务级递归硬删除自检“落在main上的是什么、还差什么”CURRENT已交付设计——在处理递归/批量删除、entity_relationship孤儿清理、删除锁门禁之前阅读docs/superpowers/specs/2026-06-22-logviewer-modal-design.md可复用LogViewerModal基于melloware/react-logviewer的深色终端弹窗设计规格文档自标“已实现2026-06-24 修订”CURRENTdocs/superpowers/plans/2026-06-22-logviewer-modal.mdLogViewerModal的原始 TDD 构建计划内建 LazyLog 搜索、CopyToClipboardButtonSUPERSEDED ²——仅作历史上下文交付组件遵循的是修订版规格而非此计划这里的 SUPERSEDED 示例展示了索引如何处理“计划稿与交付物分叉”原始计划把搜索做在 LazyLog 内、附带CopyToClipboardButton但 2026-06-24 的修订版规格把这些反了过来搜索移入头部、新增底部状态栏。从当前树可以确认交付组件确实落在 LogViewerModal 目录包含LogViewerModal.utils.tsx、LogViewerModal.component.tsx与useLogStream.ts——与 Caveat 2 描述的“交付目录遵循修订规格”一致。生成式参考docs/generated/by construction 防漂移文档用途何时该读docs/generated/entity-index.md自动生成81 个一等实体 → schema JSON、Java POJO、Python 模型、TS 类型、REST 资源类不用 grep 四棵树就能定位某个实体的全部 codegen 产物 / REST 资源docs/generated/api-reference.md自动生成全部 1748 个 REST 端点method path Operationsummary按资源包分组查端点的精确 path/method或枚举某个包的路由而不用读 JAX-RS 类这两份文档被标注为CURRENT (by construction)因为它们由源码确定性再生成且受 CI 门禁保护。生成链路在当前仓库中可以完整验证Makefile 定义了三个 targetgenerate-entity-index执行python3 scripts/generate_entity_index.py从 schema resources 生成实体索引generate-api-reference执行python3 scripts/generate_api_reference.py从 JAX-RS 资源类生成 API 参考聚合 targetgenerate-reference-docs同时执行两者门禁侧.github/workflows/harness-integrity.yml 会运行 scripts/harness/check_harness.py该脚本的检查项包括死引用、以及“生成文档与其源码源是否漂移漂移则提示运行make generate-reference-docs并提交”的校验。也就是说“不能漂移”不是文档上的承诺而是由“生成脚本 提交比对”构成的工程闭环提交里的生成文档若与源码推导结果不一致CI 会失败。仓库审计与质量文档文档用途何时该读docs/golden-principles.md8 条待批准的仓库级不变量DRAFT 状态每条附实测遵循率 复现命令引用/执行某个不变量模块无环、ServiceSpec 契约、generated 即只写、禁止裸except:等docs/tech-debt.md按“影响÷体量”分三档的 21 条审计发现台账每条含位置、体量、agent 可修复性领取一个有边界的清理任务或在下手前了解已知结构性债务docs/quality.md每个 Maven 模块一个带证据的质量评级A–C / 未评估大型改动前评估模块的结构健康度 / 已知债务这三份文档与索引本身构成互补索引回答“关于某个主题去哪里读”审计文档回答“某个区域的健康度如何”。例如 AGENTS.md 的已知矛盾被索引直接链接到 docs/tech-debt.md #6读者可以在两处互相印证。资源文件docs/assets/docs/assets/ 下有 4 张 PNGhero、architecture、context graph、memory-primitives是根 README.md 中“Open Context Layer for AI”章节的配图其唯一消费者就是根 README。索引将它们登记进来是为了让“改 README 视觉”的人知道图源位置而不是让读者去翻目录树。UI 参考文档位于openmetadata-ui/下UI 的规范性文档刻意放在 UI 代码树内而非docs/索引为其中 5 处建立了目录条目文档用途何时该读DEVELOPER_HANDBOOK.mdUI 目录结构 文件命名规范。components/、pages/、rest/、utils/、hooks/保持顶层、按domain/feature/内部分组五个域discovery、governance、observability、insights、platform横切特性放在域层级。新文件用“单词干 角色后缀”GlossaryList.tsx、.types.ts、.utils.ts、.test.tsx遗留代码用.component.tsx/.interface.ts。另含导入、barrel、路由与状态位置在ui/src/下创建任何新文件之前或纠结代码该放哪里时specs/ 目录机器可读的设计系统41 个文件。其README.md声明双栈策略——推进方向 UntitledUI Tailwindtw:遗留已弃用 Ant Design Less含foundations/*色彩、间距、字体、圆角、 elevation、动效、tokens/*Tailwind 工具类 master token 参考、untitled/*推进方向组件规格与遗留components/*编写或修改任何 UI 代码之前——从specs/README.md开始再到所触碰组件对应的foundations/tokens与untitled/component.md或遗留components/*规格docs/colors.md语义化色彩 token 体系tw:bg-primary、tw:text-fg-*、tw:border-*含亮/暗色值与强制的ring→border迁移§2.3.1编写/评审任何 Tailwind 色彩类或暗色模式样式之前或当你想用ring-*或裸 hex 时docs/formutils.md现代 react-hook-form react-aria 表单栈FieldProp、getField/FormFields/HookForm对比遗留 antdutils/formUtilsAPI构建/修改任何 UI 表单前——该用哪套 API以及如何接入useFormDrawerWithHook 纯函数变换playwright/docs/自动生成的 E2E 测试覆盖目录README.md Discovery/Governance/Integration/Observability/Platform映射“组件 → spec 文件 → 场景”写 Playwright 测试前先确认哪些 UI 行为已有 E2E 覆盖或推理覆盖缺口从当前树验证specs/目录下的foundations/、tokens/、untitled/、components/子目录与 playwright/docs/ 下的Discovery.md、Governance.md等分域文件都真实存在。Caveat 6 还确认了设计系统的“机器可读”是实打实的specs/README.md引用的四个审计命令tw-audit、tw-audit:report、tw-guard、token-audit在 ui/package.json 中均有对应脚本且tw-guard会阻止新的antd导入与新的.less文件与声明的双栈弃用策略一致规则文件 .claude/rules/frontend-styling.md 会把 AI 编码代理导向specs/README.md。Ingestion 与 Bootstrap 参考位于仓库其他树中文档用途何时该读ingestion/docs/design/ingestion-diagnostics.mdDEBUG 门控的摄取诊断子系统操作注册表、看门狗、心跳、内存追踪、HTTP 自省、阶段背压、信号转储在给摄取挂死/OOM 加探针之前理解该子系统为何/如何工作bootstrap/MIGRATION_SYSTEM.md混合数据库迁移架构——Flyway→native→extension 执行顺序、SERVER_CHANGE_LOG追踪、文件布局Flyway 目录是解析器而非 Flyway runner在bootstrap/sql/migrations/下新增/调试迁移或推理执行顺序、追踪表、MySQLPostgres 双路径之前Caveat 5 对迁移文档给出了精细的核对结论conf/openmetadata.yaml 中flywayPath: ./bootstrap/sql/migrations/flyway、nativePath: ./bootstrap/sql/migrations/native、extensionPath: 三项均已核实存在目录布局与SERVER_CHANGE_LOG追踪机制属实但两处细节有出入——runner 类实际是MigrationProcessImpl文档写的是MigrationProcess且extensions/目录并未在磁盘上物化extensionPath: 尽管路径机制仍被支持。这种“文档骨架可信、个别标识符需以代码为准”的标注正是 ⚠ 评级的典型用法。Caveats 精读六条验证注记如何修正读者预期索引的“验证注记”一节把每个 ⚠ 与 SUPERSEDED 标记背后的证据展开是全文信息密度最高的部分impersonation-design§4.4v1.1为权威版本与已交付代码一致createBot.json/user.json中的allowImpersonation、DefaultAuthorizer.java中的checkImpersonationAuthorization、四个策略/角色种子、BotImpersonationIT测试。而早前的 §4.1/4.2POST /users/impersonatetoken 交换端点从未交付——实际伪装走X-Impersonate-User请求头JwtFilter.java§4.4 已取代 4.1/4.2 以反映该事实。读 §4.4不要读 4.1/4.2。logviewer-modal plan被 2026-06-24 修订版设计规格取代。计划中的内建 LazyLog 搜索 CopyToClipboardButton被反转搜索移入头部、新增底部状态栏交付目录LogViewerModal.utils.tsx、LogsViewerModalContainer.tsx、useLogStream.ts遵循修订版规格而非该计划。by construction 机制docs/generated/*由make generate-reference-docs再生成并受 reference-docs 新鲜度 CI job 门禁Playwright 文档由playwright/doc-generator/generate.js 对应的 docs-check workflow 再生成。被观察路径上它们不可能与源码漂移。存在一处良性滞后PlaywrightREADME.md汇总页脚写的是2026-03-09而Governance.md于2026-07-16再生成下一次触碰 spec 的 PR 会自我修正。ingestion-diagnostics设计已交付ingestion/src/metadata/ingestion/diagnostics/在loggerLevel DEBUG时激活挂载于metadata/workflow/base.py但文档 §5/§7 的扁平文件映射已漂移文件现在位于collectors/、monitors/、samplers/子目录且不存在独立的heartbeat.py挂载点是base.py而非文档写的base_workflow.py。把文件映射当设计期信息把行为描述当当前事实。MIGRATION_SYSTEM整体准确flyway/native/布局、SERVER_CHANGE_LOG、MigrationWorkflow/FlywayMigrationFile、conf/openmetadata.yaml的三个路径项均已核实除两处——runner 类名是MigrationProcessImpl文档写MigrationProcessextensions/目录未物化但路径仍受支持。ui/specs受版本控制41 个文件且 CURRENT——README.md引用的四个审计命令全部解析为真实的package.json脚本tw-audit、tw-audit:report、tw-guard、token-audit且其声明的双栈策略推进 UntitledUITailwind、遗留 AntdLess 弃用与强制执行规则一致tw-guard阻止新的antd导入与新的.less文件.claude/rules/frontend-styling.md将代理路由进specs/README.md。使用建议把索引当成仓库的“文档路由表”综合以上结构可以总结出一套基于该索引的工作方式定位主题先按“Read when”列在索引里检索关键词如“impersonation”“Fuseki”“form”“migration”命中后直接读对应文档生成类问题某实体对应哪些产物、某端点路径优先查 docs/generated/entity-index.md 与 docs/generated/api-reference.md避免跨四棵代码树 grep。信任分级CURRENT 文档可直接作为实现依据CURRENT ⚠ 文档先读对应脚注再使用SUPERSEDED 文档只作历史上下文例如 logviewer 原始计划标注“未实现提案”的文档CDN 指南不能当作既有代码的说明。保持防漂移闭环改动 schema/JAX-RS 资源后运行make generate-reference-docs并提交再生成结果否则 harness-integrity 检查会报漂移UI 代码改动前按 DEVELOPER_HANDBOOK.md 决定文件位置按specs/规格选组件与 token。留意边界声明索引末尾注明docs/harness-audit/目录虽存在于工作树但未被跟踪工作区审计笔记有意不进版本控制因此不属于已提交知识库——引用文档时不要以它为依据。这套“索引 新鲜度评级 举证脚注 生成门禁”的组合让 OpenMetadata 的文档知识在快速演进的代码库中保持可追溯每个 CURRENT 结论都能落到一个被核实的工件每处已知偏差都被显式登记并指向更正来源。【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenMetadata 文档索引与新鲜度体系：docs/index.md 如何组织跨仓库技术知识库
OpenMetadata 文档索引与新鲜度体系docs/index.md 如何组织跨仓库技术知识库【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadataOpenMetadata 仓库把分散在docs/、UI、ingestion 与 bootstrap 目录下的设计文档、计划稿、自动生成参考和质量审计记录统一登记在 docs/index.md 中。这篇索引不只是文件清单它为每篇文档标注了“何时该读”、最近修改时间以及基于工作树核对得出的新鲜度结论CURRENT / STALE / SUPERSEDED 等。读完本文你将掌握这套文档知识地图的查法、其背后“生成即门禁”的防漂移机制以及如何通过索引快速定位 impersonation、多节点会话、RDF、日志流式化、UI 双栈规范等核心主题的实现文档。索引的定位先查文档再读代码docs/index.md 开篇即定义了它的用途在反向工程代码或凭空猜测之前先用它找到已有的文档。它登记的知识覆盖了四类来源仓库根级指南不在docs/下CLAUDE.md、ARCHITECTURE.md、DEVELOPER.md、AGENTS.md后端与平台设计文档docs/下认证、会话、RDF、日志流等子系统的设计稿计划与规格docs/plans/、docs/superpowers/已交付或历史性的重构计划仓库外参考文档UI 开发者手册与设计系统规格openmetadata-ui/下、ingestion 诊断设计与数据库迁移体系文档ingestion/与bootstrap/下。索引明确声明了自己的边界它只登记文件不移动、不重链任何文档迁移不在其职责范围内。这保证了索引本身不会成为一次大规模重构的牵涉方。新鲜度评级体系每个结论都引用一个被核实的工件索引顶部给出了一套五级新鲜度判定标准并声明其新鲜度验证是在 2026-07-24 对照工作树逐项完成的“不是按文件年龄推断——每个结论都引用一个被核实仍然存在的工件”评级含义CURRENT其“承重”引用依赖的路径/类/配置项仍然存在且与代码一致STALE引用的路径/类/标志已不存在SUPERSEDED被更新的文档或实现取代在表格行或脚注中注明⚠整体 CURRENT但存在脚注中列出的具体注意事项by construction由源码再生成且受 CI 门禁保护结构上不可能与源码漂移这套体系的关键点在于“举证”一个 CURRENT 结论不是编辑者的主观判断而是对应工件在树中实际存在且匹配的结果。文末的Caveats验证注记一节就是举证记录共 6 条逐条说明某个 CURRENT ⚠ 文档具体“对在哪里、漂移在哪里”详见后文“Caveats 精读”一节。根级指南四个入口文档及其已知差异索引的第一张表登记了不在docs/下的四个根级指南指南定位CLAUDE.md会话常驻指导指向.claude/rules/*与 skills 的指针索引ARCHITECTURE.md系统地图——模块划分、请求/摄取/搜索路径、必须维持的不变量DEVELOPER.md构建、测试、新增实体或连接器的端到端检查清单AGENTS.mdCodex 入口文档——携带已知矛盾Webpack→Vite、antd、Python 版本上限见docs/tech-debt.md#6从当前树可以确认 CLAUDE.md 所指的规则目录.claude/rules/真实存在包含frontend-styling.md、java.md、python-ingestion.md、schema-first.md、migrations.md等 12 个规则文件。值得注意的是索引对 AGENTS.md 的诚实标注它与现行实现存在已登记的矛盾例如 UI 构建工具与组件库演进后未同步这类“已知不一致”被明确指向 docs/tech-debt.md 的对应条目而不是静默忽略——这正是该索引作为知识基础设施的价值。后端与平台设计文档docs/索引登记了 11 篇后端设计文档。以下完整继承其“用途 / 何时该读 / 最近修改 / 新鲜度”四要素文档用途何时该读新鲜度docs/impersonation-design.mdBot→用户伪装updatedBy用户 /impersonatedBybot由allowImpersonation RBACImpersonate策略范围控制触碰 bot 伪装认证——该标志、BotImpersonationPolicy种子、checkImpersonationAuthorization§4.4 为权威版本CURRENT ⚠¹docs/session-management-multi-node-design.md已交付的多节点服务端会话 WebSocket 体系共享 JDBC/Redis 存储、OM_SESSIONCookie、会话绑定的 JWT、CAS 刷新处理跨 Pod 的登录/刷新/登出、SessionService/SessionStore、JWT 会话校验、WebSocket 握手CURRENTdocs/streamable-logs.mdS3/MinIO 支撑的可流式摄取日志HTTP append/close、partial.txt→logs.txt、SSE 实时尾随、废弃 run 清扫器处理摄取日志的存储/流式化——S3LogStorage、LogStorageInterface、/logs/{fqn}/{runId}端点CURRENTdocs/ingestion-log-streaming.mdSSE 实时日志尾随LogStreamEvent模式、断点续传游标、每 run 一个共享 reader、约束每条流的边界条件构建或调试实时尾随摄取日志的客户端——/logs/{fqn}/stream/{runId}、IngestionLogTailer、LogStreamSettingsCURRENTdocs/rdf-local-development.md用 Apache Jena Fuseki 本地运行 RDF/知识图谱支持——启动脚本、环境变量、rdf.*配置、/api/v1/rdf/*、RdfIndexApp搭建或调试本地 RDF/Fuseki 开发环境CURRENTdocs/rdf-production-setup.md远端 Fuseki 三元组存储的生产 sizing/调优——TDB2 堆 vs 页缓存、批量/超时、每周重建、压实为生产 Fuseki 部署做 sizing/排障调优 RDF 批量写入CURRENTdocs/rdf-ontology-contract.mdRDF 谓词可用性、规范血缘方向、扩展键值投影与契约测试新增 RDF 谓词或升级既有 RDF 存储CURRENTdocs/rdf-scale-validation.md全目录 RDF 重建、查询时延、资源采样、中断重建与重启验证复现 RDF 容量测量或评估 #32057CURRENTdocs/csv-relation-types-plan.md通过relationType:termFQN前缀默认relatedTo在 CSV 导出/导入中携带术语关系类型修改术语 CSV 往返——CsvUtil.addTermRelations、GlossaryRepository.getTermRelationsFromCsvCURRENTdocs/auto-classification/add-support-for-another-entity.md分步指南通过EntityAdapter注册表把自动分类PII 样本数据扩展到 schema/Java/Python/UI 全链路的新实体为新实体类型增加自动分类/样本数据支持CURRENTdocs/perf/cdn-deployment-guide.mdAWS 设计提案单个 CloudFront S3 分发按客户/按版本的 UI 包用内嵌 CloudFront Function 路由不用 LambdaEdge规划/评审 UI 包的 CDN 分发 按客户版本固定——属于基础设施设计非既有代码CURRENT未实现提案从源码结构看这些文档覆盖的正是服务端的几条关键链路认证伪装与会话、可观测性日志存储与 SSE 流、知识图谱RDF 本地开发、生产调优、本体契约、规模验证四个文档构成一个完整的 RDF 文档簇以及数据往返术语 CSV。其中 CDN 指南被明确标注为“未实现提案”避免读者误以为仓库里已有对应代码——这是索引对“设计意图 vs 落地状态”的显式区分。计划与规格docs/plans/、docs/superpowers/文档用途新鲜度docs/plans/2026-01-27-search-indexing-stats-redesign.md把SearchIndexingApp统计重构为分阶段管道模型StageStatsTracker/StageCounter、索引别名提升、向量批量处理器CURRENT已交付设计——在触碰搜索重建统计、search_index_server_stats、索引提升、向量索引之前阅读docs/plans/2026-06-22-bulk-deletion-redesign.md按 id 集合快速、无孤儿、可恢复的服务级递归硬删除自检“落在main上的是什么、还差什么”CURRENT已交付设计——在处理递归/批量删除、entity_relationship孤儿清理、删除锁门禁之前阅读docs/superpowers/specs/2026-06-22-logviewer-modal-design.md可复用LogViewerModal基于melloware/react-logviewer的深色终端弹窗设计规格文档自标“已实现2026-06-24 修订”CURRENTdocs/superpowers/plans/2026-06-22-logviewer-modal.mdLogViewerModal的原始 TDD 构建计划内建 LazyLog 搜索、CopyToClipboardButtonSUPERSEDED ²——仅作历史上下文交付组件遵循的是修订版规格而非此计划这里的 SUPERSEDED 示例展示了索引如何处理“计划稿与交付物分叉”原始计划把搜索做在 LazyLog 内、附带CopyToClipboardButton但 2026-06-24 的修订版规格把这些反了过来搜索移入头部、新增底部状态栏。从当前树可以确认交付组件确实落在 LogViewerModal 目录包含LogViewerModal.utils.tsx、LogViewerModal.component.tsx与useLogStream.ts——与 Caveat 2 描述的“交付目录遵循修订规格”一致。生成式参考docs/generated/by construction 防漂移文档用途何时该读docs/generated/entity-index.md自动生成81 个一等实体 → schema JSON、Java POJO、Python 模型、TS 类型、REST 资源类不用 grep 四棵树就能定位某个实体的全部 codegen 产物 / REST 资源docs/generated/api-reference.md自动生成全部 1748 个 REST 端点method path Operationsummary按资源包分组查端点的精确 path/method或枚举某个包的路由而不用读 JAX-RS 类这两份文档被标注为CURRENT (by construction)因为它们由源码确定性再生成且受 CI 门禁保护。生成链路在当前仓库中可以完整验证Makefile 定义了三个 targetgenerate-entity-index执行python3 scripts/generate_entity_index.py从 schema resources 生成实体索引generate-api-reference执行python3 scripts/generate_api_reference.py从 JAX-RS 资源类生成 API 参考聚合 targetgenerate-reference-docs同时执行两者门禁侧.github/workflows/harness-integrity.yml 会运行 scripts/harness/check_harness.py该脚本的检查项包括死引用、以及“生成文档与其源码源是否漂移漂移则提示运行make generate-reference-docs并提交”的校验。也就是说“不能漂移”不是文档上的承诺而是由“生成脚本 提交比对”构成的工程闭环提交里的生成文档若与源码推导结果不一致CI 会失败。仓库审计与质量文档文档用途何时该读docs/golden-principles.md8 条待批准的仓库级不变量DRAFT 状态每条附实测遵循率 复现命令引用/执行某个不变量模块无环、ServiceSpec 契约、generated 即只写、禁止裸except:等docs/tech-debt.md按“影响÷体量”分三档的 21 条审计发现台账每条含位置、体量、agent 可修复性领取一个有边界的清理任务或在下手前了解已知结构性债务docs/quality.md每个 Maven 模块一个带证据的质量评级A–C / 未评估大型改动前评估模块的结构健康度 / 已知债务这三份文档与索引本身构成互补索引回答“关于某个主题去哪里读”审计文档回答“某个区域的健康度如何”。例如 AGENTS.md 的已知矛盾被索引直接链接到 docs/tech-debt.md #6读者可以在两处互相印证。资源文件docs/assets/docs/assets/ 下有 4 张 PNGhero、architecture、context graph、memory-primitives是根 README.md 中“Open Context Layer for AI”章节的配图其唯一消费者就是根 README。索引将它们登记进来是为了让“改 README 视觉”的人知道图源位置而不是让读者去翻目录树。UI 参考文档位于openmetadata-ui/下UI 的规范性文档刻意放在 UI 代码树内而非docs/索引为其中 5 处建立了目录条目文档用途何时该读DEVELOPER_HANDBOOK.mdUI 目录结构 文件命名规范。components/、pages/、rest/、utils/、hooks/保持顶层、按domain/feature/内部分组五个域discovery、governance、observability、insights、platform横切特性放在域层级。新文件用“单词干 角色后缀”GlossaryList.tsx、.types.ts、.utils.ts、.test.tsx遗留代码用.component.tsx/.interface.ts。另含导入、barrel、路由与状态位置在ui/src/下创建任何新文件之前或纠结代码该放哪里时specs/ 目录机器可读的设计系统41 个文件。其README.md声明双栈策略——推进方向 UntitledUI Tailwindtw:遗留已弃用 Ant Design Less含foundations/*色彩、间距、字体、圆角、 elevation、动效、tokens/*Tailwind 工具类 master token 参考、untitled/*推进方向组件规格与遗留components/*编写或修改任何 UI 代码之前——从specs/README.md开始再到所触碰组件对应的foundations/tokens与untitled/component.md或遗留components/*规格docs/colors.md语义化色彩 token 体系tw:bg-primary、tw:text-fg-*、tw:border-*含亮/暗色值与强制的ring→border迁移§2.3.1编写/评审任何 Tailwind 色彩类或暗色模式样式之前或当你想用ring-*或裸 hex 时docs/formutils.md现代 react-hook-form react-aria 表单栈FieldProp、getField/FormFields/HookForm对比遗留 antdutils/formUtilsAPI构建/修改任何 UI 表单前——该用哪套 API以及如何接入useFormDrawerWithHook 纯函数变换playwright/docs/自动生成的 E2E 测试覆盖目录README.md Discovery/Governance/Integration/Observability/Platform映射“组件 → spec 文件 → 场景”写 Playwright 测试前先确认哪些 UI 行为已有 E2E 覆盖或推理覆盖缺口从当前树验证specs/目录下的foundations/、tokens/、untitled/、components/子目录与 playwright/docs/ 下的Discovery.md、Governance.md等分域文件都真实存在。Caveat 6 还确认了设计系统的“机器可读”是实打实的specs/README.md引用的四个审计命令tw-audit、tw-audit:report、tw-guard、token-audit在 ui/package.json 中均有对应脚本且tw-guard会阻止新的antd导入与新的.less文件与声明的双栈弃用策略一致规则文件 .claude/rules/frontend-styling.md 会把 AI 编码代理导向specs/README.md。Ingestion 与 Bootstrap 参考位于仓库其他树中文档用途何时该读ingestion/docs/design/ingestion-diagnostics.mdDEBUG 门控的摄取诊断子系统操作注册表、看门狗、心跳、内存追踪、HTTP 自省、阶段背压、信号转储在给摄取挂死/OOM 加探针之前理解该子系统为何/如何工作bootstrap/MIGRATION_SYSTEM.md混合数据库迁移架构——Flyway→native→extension 执行顺序、SERVER_CHANGE_LOG追踪、文件布局Flyway 目录是解析器而非 Flyway runner在bootstrap/sql/migrations/下新增/调试迁移或推理执行顺序、追踪表、MySQLPostgres 双路径之前Caveat 5 对迁移文档给出了精细的核对结论conf/openmetadata.yaml 中flywayPath: ./bootstrap/sql/migrations/flyway、nativePath: ./bootstrap/sql/migrations/native、extensionPath: 三项均已核实存在目录布局与SERVER_CHANGE_LOG追踪机制属实但两处细节有出入——runner 类实际是MigrationProcessImpl文档写的是MigrationProcess且extensions/目录并未在磁盘上物化extensionPath: 尽管路径机制仍被支持。这种“文档骨架可信、个别标识符需以代码为准”的标注正是 ⚠ 评级的典型用法。Caveats 精读六条验证注记如何修正读者预期索引的“验证注记”一节把每个 ⚠ 与 SUPERSEDED 标记背后的证据展开是全文信息密度最高的部分impersonation-design§4.4v1.1为权威版本与已交付代码一致createBot.json/user.json中的allowImpersonation、DefaultAuthorizer.java中的checkImpersonationAuthorization、四个策略/角色种子、BotImpersonationIT测试。而早前的 §4.1/4.2POST /users/impersonatetoken 交换端点从未交付——实际伪装走X-Impersonate-User请求头JwtFilter.java§4.4 已取代 4.1/4.2 以反映该事实。读 §4.4不要读 4.1/4.2。logviewer-modal plan被 2026-06-24 修订版设计规格取代。计划中的内建 LazyLog 搜索 CopyToClipboardButton被反转搜索移入头部、新增底部状态栏交付目录LogViewerModal.utils.tsx、LogsViewerModalContainer.tsx、useLogStream.ts遵循修订版规格而非该计划。by construction 机制docs/generated/*由make generate-reference-docs再生成并受 reference-docs 新鲜度 CI job 门禁Playwright 文档由playwright/doc-generator/generate.js 对应的 docs-check workflow 再生成。被观察路径上它们不可能与源码漂移。存在一处良性滞后PlaywrightREADME.md汇总页脚写的是2026-03-09而Governance.md于2026-07-16再生成下一次触碰 spec 的 PR 会自我修正。ingestion-diagnostics设计已交付ingestion/src/metadata/ingestion/diagnostics/在loggerLevel DEBUG时激活挂载于metadata/workflow/base.py但文档 §5/§7 的扁平文件映射已漂移文件现在位于collectors/、monitors/、samplers/子目录且不存在独立的heartbeat.py挂载点是base.py而非文档写的base_workflow.py。把文件映射当设计期信息把行为描述当当前事实。MIGRATION_SYSTEM整体准确flyway/native/布局、SERVER_CHANGE_LOG、MigrationWorkflow/FlywayMigrationFile、conf/openmetadata.yaml的三个路径项均已核实除两处——runner 类名是MigrationProcessImpl文档写MigrationProcessextensions/目录未物化但路径仍受支持。ui/specs受版本控制41 个文件且 CURRENT——README.md引用的四个审计命令全部解析为真实的package.json脚本tw-audit、tw-audit:report、tw-guard、token-audit且其声明的双栈策略推进 UntitledUITailwind、遗留 AntdLess 弃用与强制执行规则一致tw-guard阻止新的antd导入与新的.less文件.claude/rules/frontend-styling.md将代理路由进specs/README.md。使用建议把索引当成仓库的“文档路由表”综合以上结构可以总结出一套基于该索引的工作方式定位主题先按“Read when”列在索引里检索关键词如“impersonation”“Fuseki”“form”“migration”命中后直接读对应文档生成类问题某实体对应哪些产物、某端点路径优先查 docs/generated/entity-index.md 与 docs/generated/api-reference.md避免跨四棵代码树 grep。信任分级CURRENT 文档可直接作为实现依据CURRENT ⚠ 文档先读对应脚注再使用SUPERSEDED 文档只作历史上下文例如 logviewer 原始计划标注“未实现提案”的文档CDN 指南不能当作既有代码的说明。保持防漂移闭环改动 schema/JAX-RS 资源后运行make generate-reference-docs并提交再生成结果否则 harness-integrity 检查会报漂移UI 代码改动前按 DEVELOPER_HANDBOOK.md 决定文件位置按specs/规格选组件与 token。留意边界声明索引末尾注明docs/harness-audit/目录虽存在于工作树但未被跟踪工作区审计笔记有意不进版本控制因此不属于已提交知识库——引用文档时不要以它为依据。这套“索引 新鲜度评级 举证脚注 生成门禁”的组合让 OpenMetadata 的文档知识在快速演进的代码库中保持可追溯每个 CURRENT 结论都能落到一个被核实的工件每处已知偏差都被显式登记并指向更正来源。【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考