3 分钟了解如何进入开发

oak是一个快速开发业务型应用的脚手架，文档正在完善中

仓库结构

当前仓库按职责分为几类：

• src/ CLI 自身源码，包括命令实现、脚手架逻辑和 server runtime。

• tooling/ CLI 内部使用的构建与生成工具链。 其中： tooling/scripts/ 是内部脚本， tooling/config/ 是构建配置， tooling/plugins/ 是构建插件。

• scaffold/ 所有生成项目相关的资产。 其中： scaffold/base/ 是基础项目模板， scaffold/fragments/ 是生成片段， scaffold/examples/ 是可选示例模板。

• assets/ CLI 运行时依赖的静态资源，目前主要是 socket-admin。

• docs/ 架构、重构和 backlog 文档。

src/ 内部怎么读

如果你已经知道根目录分层，下一步建议直接按下面顺序理解 src/：

• src/index.ts CLI 入口，只做命令注册和 action 绑定。

• src/shared/ CLI 共用基础设施，包括命令参数类型、option builder、参数归一化、路径注册、模板与文件辅助，以及项目侧 compiler 配置类型入口。

• src/commands/ 各 CLI 命令实现，包括 build/run/clean/make*/rename。

• src/create/index.ts 入口现在位于 src/create/index.ts，负责 create / update 主编排。

• src/create/support.ts create 基础支撑：prompt、路径、scaffold、tsconfig。

• src/create/workspace.ts web / wechatMp 配置生成，以及 update 子目录同步。

• src/create/finalize.ts create 收尾：dependency AST、package.json、rename。

• src/createConfig.ts 项目侧 configuration/compiler.js 的兼容导出入口，实际实现位于 src/shared/create-compiler-config.ts。

• src/types/ 对外共享类型定义，目前主要是 CDN 配置类型。

• src/typings/ server runtime 依赖的全局类型声明，目前主要是 polyfill.d.ts。

• src/server/ CLI 内嵌 server runtime。

如果是第一次接手这仓库，建议先看 源码分层说明。 如果接下来准备继续收敛 src/ 的物理目录，可以再看 src/ 下一阶段重组方案。 如果要改构建脚本、webpack/vite/metro 配置或插件，建议直接看 tooling 分层说明。 如果已经确认问题在 tooling/plugins/，建议继续看 plugins 分层说明。 如果要改 CLI 内嵌 server runtime，建议直接看 server 分层说明。

相关文档

• 目录重组最终方案
• 目录重组草案
• Issue Backlog
• 源码分层说明
• tooling 分层说明
• plugins 分层说明
• server 分层说明
• src/ 下一阶段重组方案

包内路径兼容

目录重组后，仓库内部已经迁移到：

• tooling/
• scaffold/
• assets/

为了兼容历史项目，package.json 中保留了旧子路径到新目录的映射：

• @xuchangzju/oak-cli/config/* -> @xuchangzju/oak-cli/tooling/config/*
• @xuchangzju/oak-cli/scripts/* -> @xuchangzju/oak-cli/tooling/scripts/*
• @xuchangzju/oak-cli/plugins/* -> @xuchangzju/oak-cli/tooling/plugins/*

新代码优先使用新的目录语义路径；旧路径保留主要是为了兼容已生成项目。