# DevOS Project Factory & Generator Runtime > Version: 1.0 > Status: Architecture Specification > Scope: Project Factory / Generator Runtime / Templates / Presets / Project Manifest > Depends On: 01–32 > Project: `/home/dev/bun/devos` --- # 1. 文档目标 本文定义 DevOS Project Factory。 核心目标： > 把 DevOS 从“一个可扩展平台”进一步变成“能够持续生产新应用、新服务、新 Plugin、新 Agent 项目的开发平台”。 最终开发流程： ```text 自然语言需求 ↓ Requirement Parser ↓ Capability Discovery ↓ Capability Resolver ↓ Dependency Resolver ↓ Project Manifest ↓ Template Resolver ↓ Generator Runtime ↓ Generated Project ↓ Bootstrap ↓ DevOS Runtime ↓ 可运行项目 ``` --- # 2. Project Factory 的定位 DevOS Project Factory 不是： - 一个简单 CLI 模板复制器 - 一个脚手架 - 一个 `create-react-app` - 一个代码生成脚本集合 它是： > **基于 DevOS Runtime + Capability + Module + Template 的项目生产系统。** 核心关系： ```text DevOS Runtime ↓ Capabilities ↓ Modules ↓ Templates ↓ Project Manifest ↓ Generator ↓ Project ``` --- # 3. 为什么需要 Project Factory 传统项目： ```text 新项目 ↓ 复制旧项目 ↓ 删除不需要的代码 ↓ 修改配置 ↓ 复制更多代码 ``` 最终： ```text Project A Project B Project C ``` 彼此逐渐分叉。 DevOS 希望： ```text DevOS Core ↓ Capability ↓ Project Manifest ↓ Generated Project ``` 项目只声明： > 我要什么。 而不是复制： > 以前项目是什么。 --- # 4. 核心模型 Project Factory 的核心对象： ```text Project ProjectManifest ProjectType Capability Module Preset Template Generator Dependency Feature Environment DeploymentProfile ``` 关系： ```text Project ↓ ProjectManifest ↓ ProjectType ↓ Capabilities ↓ Modules ↓ Templates ↓ Generator ``` --- # 5. Project Type 第一阶段建议支持： ```text platform-app admin-app saas-app ai-app website api-service worker-service agent-service mcp-server automation-service plugin module extension library ``` --- # 6. Project Type 定义 例如： ```yaml id: ai-app name: AI Application description: Application with Agent capabilities requiredCapabilities: - runtime - identity - security - data - config - agent optionalCapabilities: - task - storage - notification - search ``` Project Type 本身也是声明式的。 --- # 7. Project Manifest 项目的 Source of Truth： ```text devos.project.yaml ``` 示例： ```yaml version: "1" project: id: seo-agent name: SEO Agent type: ai-app runtime: devos: "^1.0.0" capabilities: - identity - security - data - config - task - event - storage - search - agent - model - notification plugins: - devos.github - devos.cloudflare modules: - seo.website - seo.content ui: shell: devos deployment: profile: docker ``` --- # 8. Manifest 是唯一真相 项目不应该同时存在： ```text package.json docker-compose.yml .env project.json devos.config.ts ``` 分别描述项目能力。 应该： ```text devos.project.yaml ↓ Resolver ↓ Generated Configuration ``` 其他文件是： > Derived Output。 --- # 9. Manifest 与代码 Manifest： ```text Desired State ``` Generated Code： ```text Materialized State ``` 因此： ```text Manifest ↓ Generator ↓ Code ``` 如果手工修改 Generated Code： ```text Generator ↓ 可能覆盖 ``` 所以必须定义： ```text Generated Custom Extension ``` 三种边界。 --- # 10. Generated / Custom Boundary 推荐： ```text src/ ├── generated/ ├── modules/ ├── extensions/ └── app/ ``` 或者： ```text src/ ├── core/ ├── generated/ └── custom/ ``` 原则： > Generator 可以重新生成 generated 区域，但不能覆盖 custom 区域。 --- # 11. Project Manifest 不应该描述代码细节 错误： ```yaml files: - src/foo.ts - src/bar.ts - src/baz.ts ``` 正确： ```yaml capabilities: - agent - task - storage ``` Manifest 描述： > 我要什么能力。 Generator 决定： > 如何实现。 --- # 12. Capability Capability 是 Project Factory 最核心的选择单位。 例如： ```text identity security data config task event storage search agent model notification communication plugin mcp workflow ``` --- # 13. Capability Dependency Graph 例如： ```text agent ├── model ├── task ├── event ├── storage └── security task ├── queue └── worker notification ├── event └── communication search └── data ``` Resolver 自动计算： ```text agent ``` 需要： ```text model task event storage security data config ``` --- # 14. Dependency Resolver Resolver 必须处理： ```text Dependency Optional Dependency Peer Dependency Conflict Version Capability Plugin Dependency Module Dependency ``` 例如： ```text Agent ↓ Model ↓ Provider ↓ Credential ↓ Secret ``` --- # 15. Dependency Cycle 必须检测： ```text A → B B → C C → A ``` 输出： ```text Capability Dependency Cycle Detected ``` 禁止生成项目。 --- # 16. Capability Conflict 例如： ```text postgresql-search elasticsearch-search ``` 可能存在： ```text defaultSearchProvider ``` 冲突。 Resolver 应输出： ```text Conflict: search.provider Candidates: postgresql elasticsearch ``` 然后： - 使用 Preset - 使用用户选择 - 使用默认策略 而不是随机选择。 --- # 17. Preset Preset 是 Capability Bundle。 例如： ```yaml id: standard-saas capabilities: - identity - security - data - config - storage - notification - search - audit ``` 然后： ```bash devos create my-saas --preset standard-saas ``` --- # 18. 官方 Preset 建议： ```text minimal api admin saas ai agent automation website worker mcp plugin ``` 例如： ```text minimal ``` 只包含： ```text runtime config logging ``` 而： ```text agent ``` 包含： ```text runtime security data config task event storage model agent ``` --- # 19. Minimal Project 这是非常重要的。 DevOS 必须支持： ```text devos-base ``` 一个可以独立 Fork 的最小平台。 例如： ```text devos-base ├── runtime ├── config ├── logging ├── security ├── data └── api ``` 用户可以： ```text DevOS Full ``` 或者： ```text DevOS Base ``` 开始项目。 --- # 20. 四种项目模式 ### Mode 1 ```text Platform Extension ``` 直接运行在 DevOS 主平台。 ### Mode 2 ```text Generated Project ``` 从 Manifest 生成独立项目。 ### Mode 3 ```text Forked Project ``` 从 `devos-base` Fork。 ### Mode 4 ```text Standalone Project ``` 完全独立。 --- # 21. 默认优先级 推荐： ```text Extension ↓ Generated Project ↓ Fork ↓ Standalone ``` 不要一开始就 Fork。 --- # 22. Project Generator Generator 输入： ```ts interface GeneratorInput { manifest: ProjectManifest; capabilities: ResolvedCapabilities; modules: ResolvedModules; plugins: ResolvedPlugins; template: Template; environment: GeneratorEnvironment; } ``` 输出： ```text Project Files Project Metadata Dependencies Configuration Migrations Docker CI Documentation ``` --- # 23. Generator Pipeline ```text Manifest ↓ Validate ↓ Resolve Project Type ↓ Resolve Capabilities ↓ Resolve Dependencies ↓ Resolve Modules ↓ Resolve Plugins ↓ Resolve Template ↓ Generate ↓ Format ↓ Typecheck ↓ Test ↓ Bootstrap ↓ Validate ``` --- # 24. Template Template 不是一个完整旧项目。 它是： > 针对 Project Type / Capability 的代码生成素材。 例如： ```text templates/ ├── project/ │ ├── ai-app/ │ ├── saas-app/ │ ├── api-service/ │ └── worker-service/ │ ├── capability/ │ ├── agent/ │ ├── task/ │ ├── storage/ │ └── notification/ │ └── plugin/ ├── basic/ ├── provider/ └── ui/ ``` --- # 25. Template Composition Generator 不应该只选择一个模板。 可以： ```text Base Template + Project Template + Capability Template + Module Template + Plugin Template ``` 例如： ```text AI App + Agent Capability + SEO Module + Cloudflare Plugin ``` 组合生成。 --- # 26. Generator Conflict 如果两个模板修改： ```text src/app.ts ``` Generator 必须： ```text detect conflict ``` 而不是： ```text last write wins ``` 解决方式： ```text Template Priority Merge Strategy Extension Hook Conflict Error ``` --- # 27. Template Layering 推荐： ```text Base ↓ Runtime ↓ Project Type ↓ Capability ↓ Module ↓ Plugin ↓ Application ``` 越上层优先级越高。 --- # 28. Generator 不应该生成 Runtime 例如： ```text Agent Project ``` 不能复制： ```text packages/agent-runtime/ ``` 而应该依赖： ```json { "@devos/agent": "^1.0.0" } ``` 否则项目就无法升级。 --- # 29. Dependency-first Generation 生成顺序： ```text Runtime Dependencies ↓ Package Manifest ↓ Configuration ↓ Database Schema ↓ Backend ↓ Frontend ↓ Tests ↓ Deployment ``` --- # 30. Package Manager 推荐支持： ```text pnpm bun npm ``` 但 DevOS 自己内部应该选择一个默认标准。 如果当前项目已经统一使用 Bun： ```text Bun ``` 可以作为 DevOS 默认开发运行时。 但 Generator 应尽量避免把： ```text Bun-specific ``` 写死到业务代码。 --- # 31. Monorepo 复杂项目可以生成： ```text apps/ ├── web ├── api ├── worker └── agent packages/ ├── domain ├── sdk └── shared ``` 例如： ```text my-project/ ├── apps/ │ ├── web/ │ ├── api/ │ ├── worker/ │ └── agent/ │ ├── packages/ │ ├── domain/ │ ├── shared/ │ └── sdk/ │ ├── devos.project.yaml ├── package.json └── README.md ``` --- # 32. Single App 小项目不要强制 Monorepo。 例如： ```text api-service ``` 可以生成： ```text my-api/ ├── src/ ├── tests/ ├── devos.project.yaml ├── package.json └── Dockerfile ``` Project Type 决定复杂度。 --- # 33. Module Module 是业务能力集合。 例如： ```text seo.website seo.content seo.backlink crm.customer crm.pipeline ``` Module 可以包含： ```text Resource Action Query Event UI Skill Migration ``` --- # 34. Module 与 Plugin 的区别 Plugin： > 外部可安装扩展。 Module： > 项目内部或官方业务能力模块。 例如： ```text GitHub → Plugin SEO Website → Module ``` 但是两者都必须使用： ```text DevOS Runtime ``` --- # 35. Module Dependency 例如： ```text seo.content ↓ seo.website ↓ data storage agent model ``` Resolver 自动安装依赖。 --- # 36. Module Registry 建议： ```text Module Registry ``` 记录： ```text Module ID Version Dependencies Capabilities Resources Actions Events UI Skills ``` Module Registry 可以与 Plugin Registry 共用基础 Registry Runtime。 不要建立两个完全独立的 Registry 系统。 --- # 37. Plugin + Module 一个项目可以： ```yaml plugins: - devos.github - devos.cloudflare modules: - seo.website - seo.content ``` 最终： ```text Project ├── DevOS Runtime ├── SEO Modules ├── GitHub Plugin └── Cloudflare Plugin ``` --- # 38. Project Factory 与 Agent 这是 DevOS 很重要的一层。 用户可以说： > 创建一个可以管理 GitHub 仓库、自动执行 SEO 检查、每天生成报告的 AI 应用。 Agent 可以解析： ```text AI Application GitHub SEO Scheduled Task Report Notification ``` 然后转换： ```text Natural Language ↓ Requirement Model ↓ Capability Discovery ↓ Project Manifest ``` --- # 39. Requirement Model 内部结构： ```ts interface ProjectRequirement { projectType?: string; capabilities: string[]; modules: string[]; plugins: string[]; integrations: string[]; ui?: UIRequirements; deployment?: DeploymentRequirements; } ``` Agent 不直接写代码。 Agent 先生成： ```text ProjectRequirement ``` --- # 40. Agent 与 Generator 正确： ```text User ↓ Agent ↓ Requirement ↓ Manifest ↓ Generator ↓ Project ``` 错误： ```text User ↓ Agent ↓ 随机生成 500 个文件 ``` Manifest 是 Agent 和 Generator 之间的稳定 Contract。 --- # 41. Manifest Preview 生成前应该支持： ```bash devos project plan ``` 显示： ```text Project: seo-agent Type: ai-app Capabilities: + agent + model + task + storage + search Modules: + seo.website + seo.content Plugins: + github + cloudflare Estimated files: 87 Dependencies: 42 Database migrations: 6 ``` 然后： ```bash devos project create ``` --- # 42. Dry Run 必须支持： ```bash devos project create --dry-run ``` 输出： ```text Would create: src/agent/ src/tasks/ src/seo/ src/plugins/ ... ``` 不会修改文件。 --- # 43. Diff 已有项目修改 Manifest 后： ```bash devos project plan ``` 输出： ```text + capability: notification + module: seo.report - plugin: old.provider ~ dependency: @devos/agent ``` 这是 Project Factory 可以长期维护项目的关键。 --- # 44. Reconciliation Project Factory 不只是 Generate。 还应该： > Reconcile Desired Manifest 与 Current Project。 模型： ```text Desired Manifest ↓ Resolver ↓ Current Project ↓ Diff ↓ Plan ↓ Apply ``` --- # 45. Project State 可以保存： ```text .devOS/ ├── project.lock ├── generated.json └── state.json ``` 其中： ```text project.lock ``` 锁定： ```text DevOS Version Capability Version Module Version Plugin Version Template Version Generator Version ``` --- # 46. Reproducible Generation 同一个： ```text devos.project.yaml + devos.lock ``` 应该尽量生成相同项目。 即： ```text Manifest + Lock + Generator Version ``` 决定： ```text Generated Project ``` --- # 47. Generator Version Generator 本身也需要版本： ```text generatorVersion ``` 否则： ```text 同一个 Manifest ``` 未来可能产生完全不同结果。 因此： ```text Project Lock ``` 必须记录 Generator Version。 --- # 48. Generated File Metadata 可以记录： ```json { "path": "src/generated/agent.ts", "source": "capability:agent", "template": "agent-default", "templateVersion": "1.2.0", "hash": "..." } ``` 用于判断： > 这个文件是否被用户修改过。 --- # 49. Customization Detection 如果： ```text Generated Hash ≠ Current Hash ``` 说明： ```text User Modified ``` Generator 升级时： ```text Do Not Overwrite ``` 或者： ```text Show Conflict ``` --- # 50. Generated Code Ownership 建议： ```text generated/ ``` 由 Factory 管理。 ```text src/app/ ``` 由开发者管理。 ```text src/extensions/ ``` 由开发者扩展。 这样： ```text Factory Update ``` 不会破坏： ```text Application Code ``` --- # 51. Project Upgrade 项目升级： ```bash devos project upgrade ``` 流程： ```text Read Manifest ↓ Read Lock ↓ Resolve New Versions ↓ Compatibility ↓ Generate Diff ↓ Migration Plan ↓ Apply ↓ Tests ``` --- # 52. Project Upgrade 与 Plugin Upgrade 两者不同。 Plugin： ```text Plugin Runtime Upgrade ``` Project： ```text Project Factory Upgrade ``` 但底层可以共用： ```text Version Runtime Migration Runtime Compatibility Runtime ``` --- # 53. Database Generation Project Manifest 可以声明： ```yaml data: database: provider: postgresql ``` Modules 提供： ```text Resource Schema Migration Index Relation ``` Generator 汇总。 但最终： ```text Migration Runtime ``` 负责执行。 --- # 54. API Generation Resource / Action / Query 定义可以生成： ```text REST API OpenAPI SDK CLI ``` 因此： ```text Project ↓ Resource / Action ↓ API Contract ↓ OpenAPI ↓ SDK ``` 不要手工生成第二套 API Model。 --- # 55. UI Generation Resource Schema 可以自动生成： ```text List Detail Create Edit Search Action Buttons ``` 因此一个 Module： ```text seo.website ``` 可以只定义： ```text Resource Fields Actions UI Metadata ``` 然后： ```text Resource UI Runtime ``` 生成大量基础 UI。 --- # 56. Project Factory 与 UI Shell Generated App 默认使用： ```text DevOS UI Shell ``` 而不是复制： ```text Header Sidebar Auth Theme Router Notification Task Center ``` 这样 DevOS UI 升级可以复用。 --- # 57. Project Factory 与 Agent UI 如果项目需要 Agent： ```yaml capabilities: - agent ``` Generator 自动加入： ```text Agent Runtime Agent UI Task UI Context UI Memory UI Model Configuration ``` 但全部依赖： ```text @devos/agent @devos/agent-context @devos/agent-memory ``` --- # 58. Deployment Profile Project 可以选择： ```text docker docker-compose kubernetes bare-metal serverless cloud ``` 第一阶段建议： ```text docker ``` 优先。 Manifest： ```yaml deployment: profile: docker ``` --- # 59. Docker Generation 生成： ```text Dockerfile docker-compose.yml .env.example ``` 但： ```text Secret ``` 不应该生成真实值。 只能生成： ```text SECRET_REF ``` 或者： ```text .env.example ``` --- # 60. Environment Generation 默认： ```text development staging production ``` 每个环境： ```text Config Secret Provider Database Storage ``` 均通过： ```text Configuration Runtime ``` 管理。 --- # 61. CI Generation Project Factory 可以生成： ```text .github/ └── workflows/ ├── test.yml ├── build.yml └── release.yml ``` 或者其他 CI。 但 CI 应调用： ```bash devos project validate devos test devos build ``` 而不是复制一套平台逻辑。 --- # 62. Project Doctor 生成后： ```bash devos project doctor ``` 检查： ```text Manifest Lock Dependencies Capabilities Modules Plugins Config Secrets Database Migrations API UI Tests Docker ``` --- # 63. Project Validate ```bash devos project validate ``` 检查： ```text Manifest Schema Dependency Graph Version Compatibility Capability Contracts Module Contracts Plugin Contracts Generated Files Architecture Rules ``` --- # 64. Project Create CLI 推荐： ```bash devos create ``` 例如： ```bash devos create seo-agent ``` 交互式： ```text Project Type? > AI Application Capabilities? > Agent > Task > Storage > Search Modules? > SEO Website > SEO Content Plugins? > GitHub > Cloudflare Deployment? > Docker ``` 最终生成： ```text devos.project.yaml ``` --- # 65. 非交互模式 CI / Agent 使用： ```bash devos create seo-agent \ --type ai-app \ --capability agent \ --capability task \ --module seo.website \ --plugin github ``` 但更推荐： ```bash devos create \ --manifest devos.project.yaml ``` --- # 66. Project Registry 平台需要知道有哪些项目： ```text Project Registry ``` 记录： ```text Project ID Name Type Manifest Version Owner Organization Environment Capabilities Modules Plugins Repository Deployment Status ``` --- # 67. Project Registry 与 Git Git 是： ```text Source Control ``` Project Registry 是： ```text DevOS Project Metadata ``` 不要替代 Git。 --- # 68. Repository Integration Project Manifest 可以： ```yaml repository: provider: github organization: acme repository: seo-agent ``` 实际操作通过： ```text GitHub Plugin ``` 完成。 Project Factory 不直接访问 GitHub API。 --- # 69. Project Factory 与 Provider 部署： ```text Cloudflare AWS GitHub Docker ``` 都属于： ```text Provider / Plugin ``` Project Factory 只描述： ```yaml deployment: provider: cloudflare ``` Resolver 选择 Provider。 --- # 70. Template Registry 模板需要 Registry： ```text Template Registry ``` 记录： ```text Template ID Version Project Type Capabilities Dependencies Generator Version Compatibility Checksum Signature ``` --- # 71. Template Trust 模板也可能有安全问题。 因此： ```text Official Verified Community Private ``` 和 Plugin 类似。 生产环境不能默认运行任意不可信 Template。 --- # 72. Template Package 可以： ```text .devos-template ``` 例如： ```text ai-app-1.2.0.devos-template ``` 内容： ```text manifest templates generators metadata tests checksum signature ``` --- # 73. Generator Plugin 未来 Generator 本身也可以扩展。 例如： ```text React Generator Vue Generator Python Generator Go Generator ``` 但第一阶段： > Generator Runtime 必须由 DevOS Core 控制。 扩展 Generator 可以后续作为受控 Plugin。 --- # 74. Generator Security Generator 可以写文件，因此必须： ```text Path Validation Sandbox No Path Traversal No Arbitrary Command No Secret Access No Production Access ``` 例如禁止： ```text ../../../../etc/passwd ``` --- # 75. Generated Command Security Generator 不应该随便执行： ```text curl wget bash rm -rf ``` 如果必须执行： ```text Command Runtime ``` 统一控制。 --- # 76. Project Factory 与 Storage 生成项目 Artifact： ```text Project Build Project Package Generated Archive ``` 使用： ```text Artifact Runtime Storage Runtime ``` 不要自己实现： ```text S3 Upload ``` --- # 77. Project Factory 与 Event 生成项目时产生： ```text project.created project.generated project.updated project.upgraded project.generation.failed ``` 进入： ```text Event Runtime ``` 然后可以： ```text Notification Audit Analytics Agent Workflow ``` --- # 78. Project Factory 与 Task 大型生成： ```text Project Create ↓ Task ↓ Jobs ↓ Worker ``` 例如： ```text Generate Install Dependencies Run Migration Run Tests Build Package Deploy ``` 都可以成为 Job。 --- # 79. Project Generation 不应该阻塞 API 小项目： ```text sync ``` 大型项目： ```text 202 Accepted ↓ Task ``` UI： ```text Project Generation 0% → 30% → 70% → 100% ``` 使用： ```text Task Runtime Realtime Runtime ``` --- # 80. Generation Steps Task 可以： ```text Resolve Generate Install Migrate Test Build Package Deploy ``` 每一步： ```text Job ``` 并记录： ```text Execution ``` --- # 81. Failure Recovery 例如： ```text Generate ✓ Install ✓ Migrate ✓ Test ✗ ``` 不应该重新： ```text Generate Install Migrate ``` 而应该： ```text Resume from Test ``` 因此 Project Factory 必须利用： ```text Task Checkpoint ``` --- # 82. Project Factory Audit 每次： ```text Create Update Generate Upgrade Delete Deploy ``` 都必须记录： ```text Actor Project Manifest Old Version New Version Capabilities Modules Plugins Result Reason ``` --- # 83. Project Factory Security Project Factory 必须使用： ```text SecurityContext Authorization Scope Environment Policy Audit ``` 例如： ```text Developer ``` 不能： ```text Generate Production Project ``` 除非拥有对应权限。 --- # 84. Production Guard 生产环境： ```text project.environment = production ``` 执行： ```text Generate Upgrade Deploy Delete ``` 可能要求： ```text Approval ``` 尤其： ```text Database Migration Plugin Permission Change Production Deployment Data Destruction ``` --- # 85. Multi-Tenancy Project Factory 必须支持： ```text Organization ↓ Project ↓ Environment ``` Project ID 在组织内唯一。 禁止： ```text Organization A ↓ Access ↓ Organization B Project ``` --- # 86. Project Ownership Project： ```ts interface Project { id: string; organizationId: string; name: string; type: string; manifestVersion: string; runtimeVersion: string; } ``` 所有 Project Factory 操作都必须带： ```text organizationId ``` --- # 87. Project Delete 删除项目： ```text project.delete ``` 必须检查： ```text Running Tasks Production Environment Artifacts Storage Database Plugins Dependencies ``` 默认： ```text Soft Delete ``` 而不是立即： ```text rm -rf ``` --- # 88. Project Export 项目可以导出： ```text Manifest Lock Metadata ``` 而不是： ```text Secret ``` 例如： ```bash devos project export seo-agent ``` 得到： ```text devos.project.yaml devos.lock ``` Secret 必须重新绑定。 --- # 89. Project Import ```bash devos project import devos.project.yaml ``` 流程： ```text Validate ↓ Resolve ↓ Compatibility ↓ Permission ↓ Generate ``` --- # 90. Project Migration 如果： ```text DevOS 1.x ``` 升级： ```text DevOS 2.x ``` Project Factory 应： ```text Manifest Migration ↓ Capability Migration ↓ Module Migration ↓ Plugin Compatibility ↓ Code Generation Migration ``` --- # 91. Manifest Migration 例如： ```yaml capabilities: - ai ``` 新版本： ```yaml capabilities: - model - agent ``` Migration： ```text ai ↓ model + agent ``` Migration Runtime 自动升级 Manifest。 --- # 92. Capability Registry 建议： ```text packages/capability/ ``` 提供： ```ts registerCapability(...) resolveCapability(...) findCapability(...) checkCompatibility(...) ``` Plugin、Module、Project Factory 都复用。 --- # 93. Capability Provider Capability 不一定由 Core 提供。 例如： ```text search ``` 可以： ```text Core PostgreSQL Search Plugin OpenSearch Plugin Meilisearch ``` Project Factory： ```text search ``` Resolver 决定： ```text provider ``` --- # 94. Capability Contract 每个 Capability 应定义： ```ts interface CapabilityDefinition { id: string; version: string; description: string; dependencies: Dependency[]; conflicts: Conflict[]; resources: string[]; actions: string[]; events: string[]; config: ConfigDefinition[]; providers?: string[]; } ``` --- # 95. Project Type Contract ```ts interface ProjectTypeDefinition { id: string; description: string; requiredCapabilities: string[]; optionalCapabilities: string[]; defaultCapabilities: string[]; allowedModules: string[]; allowedPlugins: string[]; template: string; } ``` --- # 96. Generator Contract ```ts interface GeneratorDefinition { id: string; version: string; supports: { projectTypes: string[]; capabilities: string[]; }; generate( context: GeneratorContext ): Promise; } ``` --- # 97. GeneratedProject ```ts interface GeneratedProject { files: GeneratedFile[]; dependencies: Dependency[]; devDependencies: Dependency[]; migrations: Migration[]; commands: GeneratedCommand[]; metadata: ProjectMetadata; } ``` --- # 98. Generator Context ```ts interface GeneratorContext { manifest: ProjectManifest; capabilities: ResolvedCapabilities; modules: ResolvedModules; plugins: ResolvedPlugins; projectType: ProjectTypeDefinition; template: TemplateDefinition; variables: Record; outputDir: string; } ``` 禁止把： ```text Secret Production Credential Master Key ``` 放入 GeneratorContext。 --- # 99. Template Variables 允许： ```text {{project.name}} {{project.id}} {{runtime.version}} {{organization.id}} {{module.id}} ``` 不允许： ```text {{secret.github.token}} ``` --- # 100. Template Engine 第一阶段建议使用成熟、简单的模板系统。 例如： ```text Handlebars EJS Mustache ``` 但不要让模板系统拥有： ```text eval 任意 shell 任意 JS execution ``` 模板只应该： ```text render ``` --- # 101. Generator Hooks 允许： ```text beforeGenerate generate afterGenerate validate ``` 但是： ```text afterGenerate ``` 也不能随意执行系统命令。 需要： ```text Command Runtime ``` 授权。 --- # 102. Project Bootstrap 生成后： ```bash devos project bootstrap ``` 负责： ```text Install Dependencies Create Config Create Database Run Migration Create Development Environment Seed Test Data Start Services ``` 每一步都进入： ```text Task Runtime ``` --- # 103. Development Seed 开发环境可以： ```text seed ``` 但： ```text production ``` 默认： ```text 禁止 Development Seed ``` --- # 104. Generated Tests Generator 必须生成： ```text Unit Test Contract Test Integration Test ``` 对于关键 Project Type： ```text E2E ``` 也应该生成。 --- # 105. Architecture Tests 生成项目必须自动包含： ```text Architecture Contract ``` 例如： ```text UI → no Prisma Agent → no Prisma Plugin → no Redis Business → no Queue MCP → no DB ``` --- # 106. Generated CI Gate 生成项目默认： ```text lint typecheck unit contract integration build ``` 重要项目： ```text security e2e migration ``` --- # 107. Project Factory UI DevOS UI 应提供： ```text Project Factory ``` 页面： ```text Projects Templates Capabilities Modules Plugins Presets Generators Versions Generation Tasks ``` --- # 108. Project Create UI 流程： ```text 1. Project Type 2. Capabilities 3. Modules 4. Plugins 5. Configuration 6. Deployment 7. Review 8. Generate ``` --- # 109. Project Plan UI Review 页面： ```text Project Capabilities Dependencies Modules Plugins Generated Files Database Changes Permissions Deployment ``` 用户确认后： ```text Generate ``` --- # 110. Agent Project Creation UI 用户可以： ```text 描述需求 ``` 例如： > 我要一个 AI SEO 项目，可以扫描网站、管理关键词、生成文章，并通过 GitHub 发布。 Agent 输出： ```text Project Type: ai-app Capabilities: agent model task storage search notification Modules: seo.website seo.keyword seo.content Plugins: github ``` 然后： ```text Review → Generate ``` Agent 不应直接执行： ```text rm git push production deploy ``` 除非有对应权限和审批。 --- # 111. Project Factory API 建议： ```text POST /v1/projects POST /v1/projects/:id/plan POST /v1/projects/:id/generate POST /v1/projects/:id/upgrade POST /v1/projects/:id/bootstrap GET /v1/projects/:id GET /v1/projects/:id/tasks GET /v1/projects/:id/manifest ``` API： ```text Authentication ↓ Authorization ↓ Scope ↓ Project Action ↓ Project Factory Runtime ``` --- # 112. Project Factory SDK ```text @devos/project-sdk ``` 提供： ```ts projects.create() projects.plan() projects.generate() projects.upgrade() projects.bootstrap() projects.validate() projects.export() projects.import() ``` SDK 不包含： ```text Generator Internal Logic ``` --- # 113. CLI 最终： ```bash devos project list devos project create devos project plan devos project generate devos project validate devos project bootstrap devos project upgrade devos project export devos project import devos project doctor devos project delete ``` --- # 114. Package Layout 推荐： ```text packages/ ├── project/ ├── project-factory/ ├── project-manifest/ ├── project-registry/ ├── project-generator/ ├── project-template/ ├── project-resolver/ ├── project-migration/ ├── project-testing/ └── project-sdk/ ``` 如果早期项目规模较小，可以先合并部分包。 不要为了“架构看起来完整”而机械拆包。 --- # 115. Project Factory Runtime 核心： ```text ProjectFactoryRuntime ``` 接口： ```ts interface ProjectFactoryRuntime { resolve( manifest: ProjectManifest ): Promise; plan( manifest: ProjectManifest ): Promise; generate( plan: ProjectPlan ): Promise; validate( project: Project ): Promise; upgrade( project: Project, target: UpgradeTarget ): Promise; } ``` --- # 116. Project Plan ```ts interface ProjectPlan { projectType: string; capabilities: ResolvedCapability[]; modules: ResolvedModule[]; plugins: ResolvedPlugin[]; dependencies: Dependency[]; templates: Template[]; migrations: Migration[]; generatedFiles: GeneratedFile[]; warnings: PlanWarning[]; conflicts: PlanConflict[]; } ``` --- # 117. Plan 必须是 Deterministic 相同： ```text Manifest Lock Runtime Version ``` 应该产生： ```text Same Plan ``` 否则 Agent 和 CI 无法可靠使用。 --- # 118. Plan 与 Apply 分离 必须： ```text plan ``` 然后： ```text apply ``` 不要： ```text create → 半路发现冲突 → 修改一堆文件 ``` 推荐： ```text Resolve ↓ Plan ↓ Review ↓ Apply ``` --- # 119. Atomic Generation 生成过程中： ```text Temporary Directory ``` 例如： ```text /tmp/devos-generation-xxxx ``` 完成： ```text Validate ↓ Test ↓ Atomic Move ``` 失败： ```text Discard Temporary Directory ``` 避免生成半个项目。 --- # 120. Generation Transaction Project Factory 应尽量模拟： ```text Prepare ↓ Generate ↓ Validate ↓ Commit ``` 对于数据库： ```text Migration Runtime ``` 独立处理。 --- # 121. Project Factory Observability 每次生成： ```text projectId generationId requestId correlationId actor runtimeVersion generatorVersion templateVersion ``` 必须可追踪。 --- # 122. Generation Metrics 至少： ```text generation.duration generation.success generation.failure generation.files generation.dependencies generation.conflicts generation.retry ``` 可以进一步统计： ```text project.create.time project.upgrade.time ``` --- # 123. Project Factory Cost 可以记录： ```text Generation CPU Storage Network AI Token Provider API ``` 如果 Agent 负责项目生成： ```text Agent Cost Project Generation Cost ``` 必须区分。 --- # 124. Project Factory 与 Model Runtime 如果使用 AI： ```text Requirement ↓ Model Runtime ↓ Structured Requirement ``` Model Runtime 只负责： ```text 理解 结构化 推荐 ``` Project Factory 负责： ```text Validate Resolve Generate ``` AI 不可以绕过 Factory。 --- # 125. AI Recommendation 必须可验证 Agent 推荐： ```text capability: cloudflare ``` Resolver 必须检查： ```text Capability Exists Version Compatible Permission Dependency Security ``` 不能因为 LLM 输出： ```text cloudflare ``` 就直接安装。 --- # 126. Human Approval 高风险项目操作： ```text Production External Credentials Database Destruction Deployment Plugin Permission Expansion ``` 必须： ```text Approval Runtime ``` --- # 127. Project Factory Security Model 完整链路： ```text User / Agent ↓ Security Context ↓ Project Authorization ↓ Project Scope ↓ Project Factory ↓ Capability Resolver ↓ Plugin/Module ↓ Action Runtime ``` --- # 128. No Direct Infrastructure Project Factory 业务代码： 禁止直接： ```text Prisma Redis S3 SMTP Docker Cloud API GitHub API ``` 必须通过： ```text Data Runtime Task Runtime Storage Runtime Provider Runtime Plugin Runtime ``` --- # 129. Project Factory 不应该变成“大脚本” 错误： ```text projectFactory.ts 5000 lines ├── createReact() ├── createDocker() ├── createGithub() ├── createAWS() ├── createSEO() └── createAgent() ``` 正确： ```text Project Factory ↓ Resolver ↓ Capabilities ↓ Modules ↓ Templates ↓ Generators ``` --- # 130. Official Capability Catalog DevOS 应维护： ```text Core Capability Catalog ``` 例如： ```text runtime identity security data config secret task event storage search agent model notification communication workflow plugin mcp observability ``` --- # 131. Official Module Catalog 业务能力： ```text SEO CRM Content DevOps Analytics Knowledge Automation ``` 但这些不要直接进入 Core Runtime。 --- # 132. SEO Project Example Manifest： ```yaml project: type: ai-app capabilities: - security - data - config - task - event - storage - search - agent - model - notification modules: - seo.website - seo.keyword - seo.content - seo.backlink plugins: - github - cloudflare ``` 最终： ```text DevOS Runtime + SEO Modules + External Plugins ``` 这符合： > 一个 AI SEO 产品 + 通用 Agent OS。 --- # 133. DevOps Project Example ```yaml project: type: automation-service capabilities: - security - task - event - storage - agent - notification plugins: - github - docker - ssh ``` 无需： ```text DevOps Runtime ``` 重新实现 Queue / Event / Secret。 --- # 134. CRM Project Example ```yaml project: type: saas-app capabilities: - identity - security - tenancy - data - search - task - notification modules: - crm.customer - crm.pipeline ``` --- # 135. Standalone Backend 如果两个业务完全独立： ```text Project A ``` 可以： ```text Fork devos-base ``` 然后： ```text remove unnecessary capabilities ``` 例如： ```text devos-base ↓ api-service ``` 只保留： ```text Runtime Security Data Config API ``` --- # 136. Fork Strategy Fork 时必须记录： ```text baseProject baseVersion forkVersion ``` 例如： ```yaml base: project: devos-base version: 1.4.0 ``` 这样未来可以： ```text devos project sync-base ``` 检查上游变化。 --- # 137. Fork 不等于复制后失控 Fork Project 仍然应该： ```text 使用 Runtime Packages ``` 只有真正需要修改： ```text Core Runtime ``` 才 Fork Core。 --- # 138. Project Factory 与版本体系 需要锁定： ```text DevOS Capability Module Plugin Template Generator Project ``` 例如： ```yaml versions: devos: 1.8.0 generator: 1.4.0 capabilities: agent: 1.2.0 modules: seo.website: 2.0.0 plugins: github: 3.1.0 ``` --- # 139. Project Lock 最终： ```text devos.lock ``` 应该记录完整解析结果。 它解决： ```text Developer A Developer B CI Production ``` 使用相同依赖。 --- # 140. Project Factory Acceptance Test 必须测试： ```text Minimal Project API Project SaaS Project AI Project Agent Project Worker Project Plugin Project MCP Project ``` 每一种： ```text Plan Generate Validate Build Test Bootstrap ``` --- # 141. Generator Golden Tests 每个 Template： ```text Input Manifest ↓ Generate ↓ Compare Snapshot ``` 如果输出发生意外变化： ```text Golden Test Failed ``` --- # 142. Dependency Resolver Tests 必须测试： ```text Dependency Conflict Cycle Version Optional Peer Plugin Module Capability ``` --- # 143. Upgrade Tests 测试： ```text Project 1.0 ↓ Upgrade ↓ Project 1.1 ``` 验证： ```text Manifest Code Migration Dependencies Tests ``` --- # 144. Custom Code Safety Tests 必须验证： ```text Generated Code + Custom Code ``` 升级时： ```text Custom Code ``` 不会被覆盖。 --- # 145. Security Tests 必须测试： ```text Path Traversal Command Injection Template Injection Secret Leakage Production Access Tenant Isolation Permission Bypass Untrusted Template Untrusted Plugin ``` --- # 146. Project Factory Performance 大型项目： ```text 1000+ files 100+ dependencies 50+ modules ``` Generator 不应该： ```text O(n²) ``` 重复解析。 应该： ```text Cache Dependency Graph Template Cache Incremental Generation ``` --- # 147. Incremental Generation Manifest 增加： ```yaml capabilities: - notification ``` 不应该： ```text 重新生成整个项目 ``` 应该： ```text Diff ↓ Affected Templates ↓ Affected Files ↓ Generate ``` --- # 148. Generator Cache 可以缓存： ```text Resolved Capability Resolved Template Dependency Graph Package Metadata ``` Redis 可以用于： ```text temporary coordination/cache ``` 但： ```text Project Manifest Project State Lock ``` 必须持久化。 --- # 149. Project Factory State 推荐： ```text PostgreSQL ``` 存： ```text Project Manifest Generation GenerationStep ProjectVersion ProjectLock Template Capability Module ``` Redis： ```text Queue Lease Cache Realtime Coordination ``` --- # 150. Project Factory 与 Artifact 生成结果可以保存： ```text Artifact ``` 例如： ```text project-generation.zip project-build.tar.gz ``` 通过： ```text Artifact Runtime ``` 管理。 --- # 151. Project Factory 与 Git Commit 可以提供： ```bash devos project generate --commit ``` 流程： ```text Generate ↓ Validate ↓ Test ↓ Git Commit ``` Git 操作必须通过： ```text Git Provider Plugin ``` 而不是 Factory 自己实现 GitHub API。 --- # 152. Project Factory 与 Deployment 可以： ```bash devos project deploy ``` 但： ```text Project Factory ``` 只负责： ```text Deployment Plan ``` 实际： ```text Deployment Runtime ``` 负责。 这一部分将在： ```text 34_DEPLOYMENT_INFRASTRUCTURE_RUNTIME.md ``` 详细定义。 --- # 153. 第一阶段不要做什么 不要一开始实现： ```text Kubernetes Generator Cloud Provider Matrix Multi-language Generator Visual Builder Marketplace Generator AI Autonomous Coding ``` 先完成： ```text Manifest Capability Dependency Template Generator Plan Generate Validate Lock ``` --- # 154. 第一 Vertical Slice 创建： ```text devos-base ``` 然后： ```bash devos create hello-app ``` 生成： ```text runtime config api health test ``` 执行： ```bash devos project validate devos project test devos project build ``` 成功。 --- # 155. 第二 Vertical Slice 增加： ```text data ``` 生成： ```text Prisma PostgreSQL Migration Repository ``` 但必须通过： ```text Data Runtime ``` --- # 156. 第三 Vertical Slice 增加： ```text task ``` 生成： ```text Task Job Queue Worker ``` 但直接依赖： ```text @devos/task ``` 而不是复制代码。 --- # 157. 第四 Vertical Slice 增加： ```text agent ``` 自动加入： ```text model context memory task event ``` 验证： ```text Agent → Action → Task ``` --- # 158. 第五 Vertical Slice 加入 Plugin： ```text github ``` 验证： ```text Project ↓ Plugin Resolver ↓ GitHub Plugin ↓ Action ``` --- # 159. 第六 Vertical Slice 自然语言： > 创建一个 GitHub Agent 项目。 转换： ```text Requirement ↓ Manifest ↓ Plan ↓ Generate ``` 这标志： > Project Factory 已经真正与 Agent Runtime 连通。 --- # 160. 推荐最终目录 ```text devos/ ├── apps/ │ ├── api/ │ ├── web/ │ └── worker/ │ ├── packages/ │ ├── runtime/ │ ├── capability/ │ ├── project/ │ ├── project-factory/ │ ├── project-manifest/ │ ├── project-resolver/ │ ├── project-generator/ │ ├── project-template/ │ ├── project-testing/ │ └── project-sdk/ │ ├── templates/ │ ├── project/ │ ├── capability/ │ ├── module/ │ └── plugin/ │ ├── modules/ │ ├── plugins/ │ ├── examples/ │ └── docs/ ``` --- # 161. Zcode 实施铁律 实现本章时： ```text 1. Manifest First 2. Resolver First 3. Plan Before Apply 4. Generate Atomically 5. Generated/Custom Separation 6. Lock Everything 7. Reuse Runtime 8. No Duplicate Infrastructure 9. Test Every Template 10. Never Overwrite Custom Code ``` --- # 162. Zcode 禁止事项 禁止： ```text 复制 DevOS Runtime 到 Generated Project ``` 禁止： ```text 每个 Project 自己实现 Queue ``` 禁止： ```text 每个 Project 自己实现 Auth ``` 禁止： ```text Generator 直接访问 Production ``` 禁止： ```text Template 获取 Secret ``` 禁止： ```text Agent 直接写任意文件 ``` 禁止： ```text LLM 直接决定最终 Dependency ``` 必须： ```text LLM Recommendation ↓ Resolver Validation ``` --- # 163. Zcode Project Factory Master Prompt ```text You are implementing the DevOS Project Factory. The Project Factory is a declarative project production system. Manifest is the source of truth. Project Factory must resolve: Project Type Capabilities Modules Plugins Dependencies Templates Generators Versions The correct flow is: Requirement → Project Manifest → Validate → Resolve → Plan → Review → Generate → Validate → Test → Bootstrap Never let AI directly generate an uncontrolled project. Never let Generator bypass: Security Config Secret Data Task Event Storage Provider Plugin Action Runtime Generated code must be separated from custom code. Never overwrite custom code automatically. Always support deterministic generation through: Manifest Lock Generator Version Template Version Never duplicate DevOS Runtime inside generated projects. Reuse DevOS packages whenever possible. Project Factory is a platform capability, not a collection of ad-hoc scripts. ``` --- # 164. Definition of Done Project Factory 第一阶段完成： ```text [ ] Project Manifest [ ] Project Type Registry [ ] Capability Registry [ ] Module Registry [ ] Plugin Registry integration [ ] Dependency Resolver [ ] Conflict Detection [ ] Template Registry [ ] Generator Runtime [ ] Project Plan [ ] Dry Run [ ] Diff [ ] Generate [ ] Atomic Generation [ ] Generated/Custom Boundary [ ] Project Lock [ ] Project Validate [ ] Project Doctor [ ] Project Upgrade [ ] Project Export [ ] Project Import [ ] CLI [ ] API [ ] SDK [ ] Contract Tests [ ] Golden Tests [ ] Security Tests ``` --- # 165. 最终架构 ```text USER │ ↓ Requirement │ ↓ AGENT │ ↓ Project Requirement │ ↓ Project Manifest │ ↓ ┌───────┴────────┐ ↓ ↓ Project Type Capability │ │ └───────┬────────┘ ↓ Dependency Resolver │ ┌──────────┼───────────┐ ↓ ↓ ↓ Modules Plugins Providers │ │ │ └──────────┼───────────┘ ↓ Template Resolver ↓ Generator Runtime ↓ Project Plan ↓ Review ↓ Generate ↓ Validate / Test ↓ Bootstrap ↓ PROJECT ``` --- # 166. Project Runtime 关系 生成项目之后： ```text Project ↓ DevOS Runtime ├── Security ├── Identity ├── Data ├── Config ├── Task ├── Event ├── Storage ├── Search ├── Agent ├── Model ├── Notification ├── Communication └── Plugin ``` 项目自己的业务： ```text Modules Plugins Extensions ``` 全部建立在 Runtime 上。 --- # 167. 最终 DevOS 生产链 到这里，前面的架构可以形成完整闭环： ```text DEVOS │ ┌─────────────┴─────────────┐ ↓ ↓ Runtime Platform Project Factory │ │ │ Project Manifest │ │ │ Capability Resolver │ │ │ Module / Plugin │ │ │ Generator │ │ └───────────────┬───────────┘ ↓ PROJECT │ ┌─────────┼─────────┐ ↓ ↓ ↓ Business Agent Workflow │ │ │ └─────────┼─────────┘ ↓ Action Runtime ↓ Execution ↓ Task / Event / Artifact ``` --- # 168. DevOS 的真正价值 最终 DevOS 不只是： ```text 一个后台管理系统 ``` 也不只是： ```text 一个 Agent Framework ``` 也不只是： ```text 一个 Plugin Framework ``` 更不是： ```text 一个脚手架 ``` 而是： ```text DevOS │ ┌───────────┼───────────┐ ↓ ↓ ↓ Runtime Capability Project Factory │ │ │ │ │ ↓ │ │ Manifest │ │ ↓ │ │ Generator │ │ ↓ └───────────┴──────→ Projects ``` 即： > **DevOS = 可扩展 Runtime + Capability Platform + Agent Platform + Project Factory。** --- # 169. 最终 Golden Rule > **Project Factory 不应该复制 DevOS；它应该声明项目需要什么，然后通过 Capability、Module、Plugin、Template 和 Generator 将这些能力组装成项目。生成项目继续依赖 DevOS Runtime，而不是复制 Runtime。** 最终原则： ```text Requirement ↓ Manifest ↓ Resolve ↓ Plan ↓ Generate ↓ Validate ↓ Project ↓ DevOS Runtime ``` **Manifest 决定“要什么”，Resolver 决定“依赖什么”，Generator 决定“怎么生成”，Runtime 决定“怎么运行”。** 这四个职责必须始终保持分离。