52 lines
5.7 KiB
Markdown
52 lines
5.7 KiB
Markdown
# ADR-008: 交互式 AI 应用使用显式 Scaffold Skill
|
||
|
||
- Status: Accepted / implemented, amended 2026-09-07
|
||
- Date: 2026-09-04
|
||
- Last amended: 2026-09-07
|
||
- Applies to: Project creation, `ProjectType`, official bundled Marketplace Plugins, scaffold Skill, release readiness
|
||
|
||
## Context
|
||
|
||
历史客户端把 `mini_game` 和 `mini_program` 作为两个可发布产品类型，并在创建项目时自动生成两套业务模板。这把项目身份、起步文件和发布规则绑定在同一次创建操作中，使模板演进和平台发布约束难以独立维护。
|
||
|
||
项目服务当前已经只负责 `.makelore/project.json` 与 `knowledge/`。用户确认将小游戏和小程序合并为一个“交互式 AI 应用”类型，并把生成文件、目录以及提交审批要求放进由官方 Marketplace 管理、随签名客户端交付的 Skill。
|
||
|
||
后续面向青少年用户的验证表明，要求用户在创建时理解产品类型、模板、UUID 与初始化状态仍是多余门槛。用户进一步确认普通创建只应选择目录，其余身份与安全默认由客户端和 Main 自动处理；Scaffold Skill 保持可选能力，而不是创建或进入聊天的前置步骤。
|
||
|
||
## Decision
|
||
|
||
- 普通新建项目只要求选择目录，不展示产品类型、模板、原始 UUID、绑定或独立副本选项。Renderer 写入内部默认 `interactive_ai_app`，Main 生成规范 UUID；`ProjectType` 创建后仍不可变。既有 `custom` 项目和底层兼容入口继续支持，但 `custom` 不再作为普通新建选项。
|
||
- `mini_game` 与 `mini_program` 只作为历史读取和脚手架兼容别名，在内存中归一为 `interactive_ai_app`。读取或运行脚手架不会改写原配置；后续普通配置变更可以保存规范值。缺少类型字段的旧项目仍归一为 `custom`。
|
||
- 项目创建只生成 `.makelore/project.json` 和 `knowledge/`，不生成业务源码、依赖、锁文件或发布模板。
|
||
- Main 为新项目自动生成 UUID，并为“其他 metadata 有效、仅缺 `projectId`”的旧配置串行补齐并持久化一次。原始 UUID、bind/independent-copy 选择不进入普通 UI；其他 metadata 缺失或无效仍是配置错误。旧 `initialized` 布尔只保留为 schema 兼容字段，不得阻断有效项目导航、聊天或首个 Agent 创建。
|
||
- 代码内置的官方 Marketplace Plugin `makelore.project-scaffold` 提供可选显式 Skill `makelore-project-scaffold`。它不是项目创建或聊天前置条件；其 Account Library 获取、项目启用和 Agent 分配语义保持独立，固定版本资源随 MakeLore 客户端交付且不经过 Package Store 下载。脚本生成六个交互式 AI 应用起步文件；写入前预检全部目标，不覆盖已有路径，受控失败时只回滚本次创建的文件和目录。
|
||
- Scaffold Skill 不安装依赖、不访问网络、不执行构建、不上传、不提交审核，也不提供 `--force`、类型覆盖或模板迁移状态。Main 继续独占固定 npm/Vite 构建、同字节预检、打包和上传；Works Square 继续独占服务端校验、不可变 Release 与运营审核。
|
||
- 官方 Plugin 的 `.mjs` 仅因它位于客户端固定、代码所有的 bundled resource root 中而可执行。应用通过不可覆盖的 `MAKELORE_NODE_EXECUTABLE` 向父 Pi worker/Agent Server 提供自身 Node；不得回退系统 Node。该例外不适用于 Marketplace 下载 artifact：P0 下载包仍只接受文本/图片 Skill 资源并拒绝 `.mjs`。第三方 Device Package 的可执行代码继续走自身的披露与确认边界。
|
||
- Skill 的发布检查只是只读准备度指导：区分确定阻断、源码包排除影响、运行时/平台待确认项和静态已满足项，并引用项目相对证据。它不能宣称构建、上传、审核或生产发布成功。
|
||
|
||
## Consequences
|
||
|
||
- 模板可随官方 Plugin 版本演进，不再扩大项目创建服务的职责，也不需要把脚本上传为 Marketplace artifact。
|
||
- 普通用户可从目录选择直接进入 `/chat`；没有 Agent 时显示非阻塞空状态并提供创建首个 Agent 的入口。Project Configuration 仍处理真正无效的 metadata，但不再承担初始化仪式。
|
||
- 旧项目无需批量迁移即可继续打开、生成脚手架和发布；普通新写入使用内部默认 `interactive_ai_app`，既有 `custom` 与历史类型保持兼容。
|
||
- 发布规则在 Skill 中可被 Agent 解释和预检，但权威执行仍只有 Main 与 Works Square，避免形成第二套发布实现。
|
||
- 对外分发仍需不可变 SemVer/Git 版本、服务端 bundled Release 元数据、已安装 Windows、签名 macOS 与 native Linux 运行证据；工作区测试不能替代这些发布门禁。
|
||
|
||
## Supersedes
|
||
|
||
本决定取代 2026-08-09 的双可发布类型与创建时自动生成模板行为，并于 2026-09-07 取代创建时的类型/身份选择及 `initialized` 工作区 gate；固定 Vite 构建、artifact contract、运营审核与公共播放边界保持不变。
|
||
|
||
## Related Evidence
|
||
|
||
- Source commit: `959b633`
|
||
- Integration merge: `4bc3e0ea5331a7d3f3576768c0119c02c0f0f952`
|
||
- Official Marketplace source commit: `ddb678b46ff10a28e04beeafcfc00c8c8a23ff9f`
|
||
- Official Marketplace integration merge: `2bc3e4420852388ce46841e05c1cbf49e80b250c`
|
||
- Source task: `20260904-project-scaffold-implementation-7e4c2a91`
|
||
- Marketplace source task: `20260904-marketplace-scaffold-client-6c4e8a21`
|
||
- Marketplace integration task: `20260904-project-scaffold-integration-client-4f2a8c71`
|
||
- Proposal: `10-decisions/proposals/20260904-project-scaffold-implementation-7e4c2a91__interactive-ai-app-type.md`
|
||
- Simplified-creation source commit: `af13aca`
|
||
- Simplified-creation integration merge: `39d7b7e`
|
||
- Simplified-creation source task: `20260906-remove-project-gate-7c31`
|