企业官网建设流程全解析

• 数据目录
• AI Agent
• 人工智能
• 知识管理
• 示例工程

导读

分阶段交付计划 是toolbox/mdcode（kcmd / Metadata as Code）项目的工程路线图，它以五个 Phase 定义了如何在 Knowledge Catalog（Dataplex）之上构建"元数据即代码"（Metadata as Code）基础设施：从 Phase 1 的只读快照与消费（TypeScript 库 + CLI + MCP），到 Phase 2 的基础发布（push），再到 Phase 3 的布局抽象与知识库（kb）表示、Phase 4 的健壮同步与状态管理，以及 Phase 5 的未来工作流。读完本文，你将掌握这套路线图中每个阶段的交付目标、对应的关键特性与验收测试，并能对照仓库源码（src/libts 与 tests/scenarios）核实各阶段的实际落地程度，从而在自己的项目里复刻这套"库 + CLI + MCP"三层架构与增量交付节奏。

一、路线图背景：为什么需要分阶段交付

Metadata as Code 的核心主张是：让数据管理员、数据生产者与 AI Agent 用**源码工件（YAML + Markdown）**来创作、管理与消费元数据，并借助版本控制与 CI/CD 完成上下文工程（context engineering）。概念文档 将其拆解为若干基石：面向人与 Agent 双端友好的文件表示、与 Catalog 服务的双向同步、以及 1st party / 3rd party 元数据构造的完整支持。

分阶段交付计划 正是这份构想的工程化拆解。它把庞大的能力面切成可独立验收的五个阶段，每个阶段都包含四类交付物：

1. Library（TypeScript）：核心库能力；
2. CLI（TypeScript-based）：kcmd命令行；
3. MCP（TypeScript-based）：供外部 Agent 调用的工具服务器；
4. Distribution 与 Testing：分发方式与验收测试。

之所以采用"先只读、后写入、再重构表示、最后加固状态"的顺序，是为了尽早把"快照消费"这条价值链路打通——Phase 1 即可让用户与 Agent 通过 MCP 读取本地元数据快照，随后再逐步补齐发布与数据完整性能力。这与 规范文档 中"Library 面向 Knowledge Catalog Enrichment Agent，但设计上可被任何构建 Agent 或自定义工具的开发者复用"的定位一致。

二、Phase 1：MVP —— 只读快照与消费

2.1 阶段目标

Phase 1 的目标是：用 TypeScript 库把元数据拉取到本地文件结构，并通过 MCP 提供对该快照的只读访问，支持早期分发。这一阶段刻意不写入服务端，先把"消费"闭环跑通。

2.2 关键特性与源码对照

计划文档为 Phase 1 列出的关键工作如下：

2.3 分页拉取与 ADC 认证的实现细节

"分页拉取"在源码中体现为CatalogSource.entries()返回AsyncGenerator，由 CatalogSync.pull() 用for await逐条消费：

async pull(): Promise<SyncResult> { const entries = this._snapshot.manifest.source.entries(this._catalog.context); for await (const entry of entries) { // 按 snapshot 配置过滤 entryType，逐条 lookup 并写入本地快照 const res = await this._catalog.lookupEntry(project, location, entry.name, [...this._snapshot.aspectTypes.keys()]); if (res.status != 200 || !res.result) { continue; } await this._snapshot._storeEntry(res.result); } return { success: true }; }

例如 BigQueryDatasetSource.entries() 先通过 BigQuery API 枚举数据集，再逐个数据集枚举表，然后以@bigquery系统 EntryGroup 内的 Entry 名逐条lookupEntry。这一"枚举 + 逐条读取"的模式天然支持大规模资源的分页消费。

认证方面，设计文档 明确采用Application Default Credentials（ADC）：ApiContext.default()通过gcloud读取默认 project 与 token，并在收到 401 时自动调用context.refresh()（gcloud auth print-access-token）。使用前需执行gcloud auth application-default login。

2.4 Phase 1 验收形态：本地快照目录

Phase 1 交付的本地快照采用 Standard 布局，其目录形态（见 概念文档 与 规范文档）：

path/to/root/ ├── catalog.yaml # Manifest：scope、snapshot 等配置 └── catalog/ # 快照内容 └── <dir1>/ ├── <entry-id1>.yaml # 单文件 Entry，元数据全部内联 └── <dir2>/ ├── <entry-id2>.yaml # 多文件 Entry └── <entry-id2>.<aspect>.md # 非结构化方面的 Markdown sidecar

其中 bq-dataset.ts 的localName()给出了 BigQuery 资源的本地命名规则：数据集映射为<projectId>.<datasetId>，表映射为<projectId>.<datasetId>/<tableId>，routine/model 则进入routines/<projectId>.<datasetId>/<id>子目录以避免与同名表冲突。这正对应计划文档强调的"目录结构与资源层级对齐"。

三、Phase 2：MVP —— 基础 Push（发布）

3.1 阶段目标

Phase 2 补上双向同步的另一半：允许本地修改被推回 Catalog 服务。计划要求库支持读取本地 YAML 并重建 API payload、按 Entry 逐个推送更新、支持通过catalog.yaml中的publishing配置做解析与过滤；CLI 侧实现基础kcmd push。

3.2 关键特性与源码对照

3.3publishing是snapshot的子集：Manifest 的硬校验

Phase 2 的核心语义是"发布集合必须是快照集合的子集"，这在 manifest.ts 中做了强校验：publishing中列出的 entry 或 aspect 类型若未出现在snapshot对应列表中，CatalogManifest.load()会直接抛错。同时，snapshot中被列出但未列入publishing的类型（如>scope: bq-dataset.ecommerce-prod.ecommerce-dataset snapshot: entries: - bigquery-dataset - bigquery-table aspects: - overview - descriptions - queries - guidelines ->赞分享

• OpenChamber Isolated Spaces 分阶段落地路线图：STAGES.md 全解读

  OpenChamber Isolated Spaces 分阶段落地路线图：STAGES.md 全解读 STAGES.md 是 OpenChamber 隔离空间（

  AI Agent人工智能代码智能体交互助手

• Screenshot-to-code代码重构路线图：从基础到高级的分阶段改进计划

  Screenshot to code代码重构路线图：从基础到高级的分阶段改进计划 Screenshot to code是一个革命性的开源项目，它能够将网页截图自

  示例工程

• 因子回测完整实战指南：用backtrader快速验证选股策略

  因子回测完整实战指南：用backtrader快速验证选股策略 很多人说"回测是正收益，实盘就亏"，坑往往不在策略，而在回测环节：佣金设得太低、数据缺了几年、信号

  金融科技数据分析机器学习