# 开发指南

从开发基础开始，选择通用 AI Coding 或百积木平台开发路径，完成实现、验证与发布。

开发指南面向创建、修改、测试和发布项目的开发者。第一次开发时，先完成开发基础，再根据目标选择通用 AI Coding 开发或百积木平台开发。

## 开发者快速开始

1. [安装与配置开发环境](/development/environment-setup/)，完成百积木客户端和 CLI 的安装与验收。
2. [选择工作区并获取项目](/development/project-setup/)，确认项目归属并检出当前用户的开发分支。
3. [使用 Codex 开发](/development/codex-development/)，让 Codex 定位、实现、测试并复核变更。
4. 根据开发路径执行构建、发布和正式入口验证。

> **先确认三个不同的目标**
>
> 工作区决定账号授权和资源归属，项目决定源码与 Git 历史，环境决定最终运行位置。切换 CLI 工作区不会自动切换本地仓库，也不会自动改变开发、测试或生产环境。

## 选择开发路径

开发内容分为两条主路径。通用 AI Coding 面向普通网站和后端服务；百积木平台开发面向需要进入工作区、Runtime、Bundle 或百积木客户端的扩展能力。

| 路径                                                    | 适用对象                                | 主要交付物                                       | 平台边界                            |
| ----------------------------------------------------- | ----------------------------------- | ------------------------------------------- | ------------------------------- |
| [通用 AI Coding 开发](/development/frontend-development/) | 网站、前端应用、后端应用和微服务                    | Web 构建产物、Artifact、Hosted Service Deployment | 不要求进入百积木平台；可被平台能力调用             |
| [百积木平台开发](/development/bundle-development/)           | 平台应用、运行时模块、Bundle、生命周期插件和 Connector | 平台应用版本、模块版本、Bundle Version 或 Connector 版本   | 遵循工作区安装、Runtime、Bundle 或客户端生命周期 |

通用 AI Coding 路径从[前端网站开发](/development/frontend-development/)或[后端应用开发](/development/backend-development/)进入；前端项目可以进一步选择[多页面前端开发](/development/frontend-development/multi-page-applications/)，后端项目可以进一步选择[微服务后端开发](/development/backend-development/microservices/)。

百积木平台路径中的正式开发对象使用“平台应用”这一术语。平台应用定义和版本通过 Bundle 安装到工作区；安装完成后形成当前工作区可见、可打开的应用实例，产品界面可以称为“工作区应用”。

## 组合关系

```text
通用前端项目
  -> 构建和发布 Web 站点
  -> 平台应用版本引用入口 URL

平台模块定义
  -> 在所属 Bundle 内创建不可变模块版本

平台应用版本 + 模块版本
  -> Bundle Manifest
  -> 创建不可变 Bundle Version
  -> 工作区安装、升级、卸载

通用后端项目
  -> 主线项目版本发布
  -> hosted_service_release
  -> Hosted Service 按版本独立部署

本地应用项目
  -> Connector 清单、服务和本机构建产物
  -> 固定版本压缩包与 SHA-256
  -> 本地应用市场审核
  -> 百积木客户端安装和运行
```

Bundle 生命周期插件服务是独立进程，属于百积木平台开发的高级能力。服务先按后端方式
部署并单独注册，再由 Bundle 引用注册记录；Bundle 不包含插件服务二进制。
开发、注册或联调这类服务时，从
[生命周期插件开发](/development/lifecycle-plugin-development/) 进入，统一使用生命周期 `3.0.0`
与引用访问解析 `2.0.0`。Bundle 顶层跨资源编排的预览边界在该章节单独说明。

> **不要把不同发布对象混在一起**
>
> 前端站点发布、后端项目版本部署、平台应用版本创建、Bundle 内模块版本创建、Bundle 版本创建和 Connector 市场发布是独立动作。任一动作成功都不能自动代表完整产品已经升级；模块版本创建也不是独立市场发布或安装。