devos/Docs/DevOS-Platform-v2/33_PROJECT_FACTORY_GENERATOR_RUNTIME.md

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 项目的开发平台”。

最终开发流程：

自然语言需求
      ↓
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 的项目生产系统。

核心关系：

DevOS Runtime
      ↓
Capabilities
      ↓
Modules
      ↓
Templates
      ↓
Project Manifest
      ↓
Generator
      ↓
Project

---

3. 为什么需要 Project Factory

传统项目：

新项目
 ↓
复制旧项目
 ↓
删除不需要的代码
 ↓
修改配置
 ↓
复制更多代码

最终：

Project A
Project B
Project C

彼此逐渐分叉。

DevOS 希望：

DevOS Core
     ↓
Capability
     ↓
Project Manifest
     ↓
Generated Project

项目只声明：

我要什么。

而不是复制：

以前项目是什么。

---

4. 核心模型

Project Factory 的核心对象：

Project
ProjectManifest
ProjectType
Capability
Module
Preset
Template
Generator
Dependency
Feature
Environment
DeploymentProfile

关系：

Project
  ↓
ProjectManifest
  ↓
ProjectType
  ↓
Capabilities
  ↓
Modules
  ↓
Templates
  ↓
Generator

---

5. Project Type

第一阶段建议支持：

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 定义

例如：

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：

devos.project.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 是唯一真相

项目不应该同时存在：

package.json
docker-compose.yml
.env
project.json
devos.config.ts

分别描述项目能力。

应该：

devos.project.yaml
        ↓
Resolver
        ↓
Generated Configuration

其他文件是：

Derived Output。

---

9. Manifest 与代码

Manifest：

Desired State

Generated Code：

Materialized State

因此：

Manifest
    ↓
Generator
    ↓
Code

如果手工修改 Generated Code：

Generator
 ↓
可能覆盖

所以必须定义：

Generated
Custom
Extension

三种边界。

---

10. Generated / Custom Boundary

推荐：

src/
├── generated/
├── modules/
├── extensions/
└── app/

或者：

src/
├── core/
├── generated/
└── custom/

原则：

Generator 可以重新生成 generated 区域，但不能覆盖 custom 区域。

---

11. Project Manifest 不应该描述代码细节

错误：

files:
  - src/foo.ts
  - src/bar.ts
  - src/baz.ts

正确：

capabilities:
  - agent
  - task
  - storage

Manifest 描述：

我要什么能力。

Generator 决定：

如何实现。

---

12. Capability

Capability 是 Project Factory 最核心的选择单位。

例如：

identity
security
data
config
task
event
storage
search
agent
model
notification
communication
plugin
mcp
workflow

---

13. Capability Dependency Graph

例如：

agent
 ├── model
 ├── task
 ├── event
 ├── storage
 └── security

task
 ├── queue
 └── worker

notification
 ├── event
 └── communication

search
 └── data

Resolver 自动计算：

agent

需要：

model
task
event
storage
security
data
config

---

14. Dependency Resolver

Resolver 必须处理：

Dependency
Optional Dependency
Peer Dependency
Conflict
Version
Capability
Plugin Dependency
Module Dependency

例如：

Agent
 ↓
Model
 ↓
Provider
 ↓
Credential
 ↓
Secret

---

15. Dependency Cycle

必须检测：

A → B
B → C
C → A

输出：

Capability Dependency Cycle Detected

禁止生成项目。

---

16. Capability Conflict

例如：

postgresql-search
elasticsearch-search

可能存在：

defaultSearchProvider

冲突。

Resolver 应输出：

Conflict:
search.provider

Candidates:
postgresql
elasticsearch

然后：

• 使用 Preset
• 使用用户选择
• 使用默认策略

而不是随机选择。

---

17. Preset

Preset 是 Capability Bundle。

例如：

id: standard-saas

capabilities:
  - identity
  - security
  - data
  - config
  - storage
  - notification
  - search
  - audit

然后：

devos create my-saas --preset standard-saas

---

18. 官方 Preset

建议：

minimal
api
admin
saas
ai
agent
automation
website
worker
mcp
plugin

例如：

minimal

只包含：

runtime
config
logging

而：

agent

包含：

runtime
security
data
config
task
event
storage
model
agent

---

19. Minimal Project

这是非常重要的。

DevOS 必须支持：

devos-base

一个可以独立 Fork 的最小平台。

例如：

devos-base
├── runtime
├── config
├── logging
├── security
├── data
└── api

用户可以：

DevOS Full

或者：

DevOS Base

开始项目。

---

20. 四种项目模式

Mode 1

Platform Extension

直接运行在 DevOS 主平台。

Mode 2

Generated Project

从 Manifest 生成独立项目。

Mode 3

Forked Project

从 devos-base Fork。

Mode 4

Standalone Project

完全独立。

---

21. 默认优先级

推荐：

Extension
    ↓
Generated Project
    ↓
Fork
    ↓
Standalone

不要一开始就 Fork。

---

22. Project Generator

Generator 输入：

interface GeneratorInput {
  manifest: ProjectManifest;

  capabilities: ResolvedCapabilities;

  modules: ResolvedModules;

  plugins: ResolvedPlugins;

  template: Template;

  environment: GeneratorEnvironment;
}

输出：

Project Files
Project Metadata
Dependencies
Configuration
Migrations
Docker
CI
Documentation

---

23. Generator Pipeline

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 的代码生成素材。

例如：

templates/
├── project/
│   ├── ai-app/
│   ├── saas-app/
│   ├── api-service/
│   └── worker-service/
│
├── capability/
│   ├── agent/
│   ├── task/
│   ├── storage/
│   └── notification/
│
└── plugin/
    ├── basic/
    ├── provider/
    └── ui/

---

25. Template Composition

Generator 不应该只选择一个模板。

可以：

Base Template
 +
Project Template
 +
Capability Template
 +
Module Template
 +
Plugin Template

例如：

AI App
+
Agent Capability
+
SEO Module
+
Cloudflare Plugin

组合生成。

---

26. Generator Conflict

如果两个模板修改：

src/app.ts

Generator 必须：

detect conflict

而不是：

last write wins

解决方式：

Template Priority
Merge Strategy
Extension Hook
Conflict Error

---

27. Template Layering

推荐：

Base
 ↓
Runtime
 ↓
Project Type
 ↓
Capability
 ↓
Module
 ↓
Plugin
 ↓
Application

越上层优先级越高。

---

28. Generator 不应该生成 Runtime

例如：

Agent Project

不能复制：

packages/agent-runtime/

而应该依赖：

{
  "@devos/agent": "^1.0.0"
}

否则项目就无法升级。

---

29. Dependency-first Generation

生成顺序：

Runtime Dependencies
 ↓
Package Manifest
 ↓
Configuration
 ↓
Database Schema
 ↓
Backend
 ↓
Frontend
 ↓
Tests
 ↓
Deployment

---

30. Package Manager

推荐支持：

pnpm
bun
npm

但 DevOS 自己内部应该选择一个默认标准。

如果当前项目已经统一使用 Bun：

Bun

可以作为 DevOS 默认开发运行时。

但 Generator 应尽量避免把：

Bun-specific

写死到业务代码。

---

31. Monorepo

复杂项目可以生成：

apps/
├── web
├── api
├── worker
└── agent

packages/
├── domain
├── sdk
└── shared

例如：

my-project/
├── apps/
│   ├── web/
│   ├── api/
│   ├── worker/
│   └── agent/
│
├── packages/
│   ├── domain/
│   ├── shared/
│   └── sdk/
│
├── devos.project.yaml
├── package.json
└── README.md

---

32. Single App

小项目不要强制 Monorepo。

例如：

api-service

可以生成：

my-api/
├── src/
├── tests/
├── devos.project.yaml
├── package.json
└── Dockerfile

Project Type 决定复杂度。

---

33. Module

Module 是业务能力集合。

例如：

seo.website
seo.content
seo.backlink
crm.customer
crm.pipeline

Module 可以包含：

Resource
Action
Query
Event
UI
Skill
Migration

---

34. Module 与 Plugin 的区别

Plugin：

外部可安装扩展。

Module：

项目内部或官方业务能力模块。

例如：

GitHub
→ Plugin

SEO Website
→ Module

但是两者都必须使用：

DevOS Runtime

---

35. Module Dependency

例如：

seo.content
 ↓
seo.website
 ↓
data
storage
agent
model

Resolver 自动安装依赖。

---

36. Module Registry

建议：

Module Registry

记录：

Module ID
Version
Dependencies
Capabilities
Resources
Actions
Events
UI
Skills

Module Registry 可以与 Plugin Registry 共用基础 Registry Runtime。

不要建立两个完全独立的 Registry 系统。

---

37. Plugin + Module

一个项目可以：

plugins:
  - devos.github
  - devos.cloudflare

modules:
  - seo.website
  - seo.content

最终：

Project
 ├── DevOS Runtime
 ├── SEO Modules
 ├── GitHub Plugin
 └── Cloudflare Plugin

---

38. Project Factory 与 Agent

这是 DevOS 很重要的一层。

用户可以说：

创建一个可以管理 GitHub 仓库、自动执行 SEO 检查、每天生成报告的 AI 应用。

Agent 可以解析：

AI Application
GitHub
SEO
Scheduled Task
Report
Notification

然后转换：

Natural Language
 ↓
Requirement Model
 ↓
Capability Discovery
 ↓
Project Manifest

---

39. Requirement Model

内部结构：

interface ProjectRequirement {
  projectType?: string;

  capabilities: string[];

  modules: string[];

  plugins: string[];

  integrations: string[];

  ui?: UIRequirements;

  deployment?: DeploymentRequirements;
}

Agent 不直接写代码。

Agent 先生成：

ProjectRequirement

---

40. Agent 与 Generator

正确：

User
 ↓
Agent
 ↓
Requirement
 ↓
Manifest
 ↓
Generator
 ↓
Project

错误：

User
 ↓
Agent
 ↓
随机生成 500 个文件

Manifest 是 Agent 和 Generator 之间的稳定 Contract。

---

41. Manifest Preview

生成前应该支持：

devos project plan

显示：

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

然后：

devos project create

---

42. Dry Run

必须支持：

devos project create --dry-run

输出：

Would create:
src/agent/
src/tasks/
src/seo/
src/plugins/
...

不会修改文件。

---

43. Diff

已有项目修改 Manifest 后：

devos project plan

输出：

+ capability: notification
+ module: seo.report

- plugin: old.provider

~ dependency: @devos/agent

这是 Project Factory 可以长期维护项目的关键。

---

44. Reconciliation

Project Factory 不只是 Generate。

还应该：

Reconcile Desired Manifest 与 Current Project。

模型：

Desired
Manifest
    ↓
Resolver
    ↓
Current
Project
    ↓
Diff
    ↓
Plan
    ↓
Apply

---

45. Project State

可以保存：

.devOS/
├── project.lock
├── generated.json
└── state.json

其中：

project.lock

锁定：

DevOS Version
Capability Version
Module Version
Plugin Version
Template Version
Generator Version

---

46. Reproducible Generation

同一个：

devos.project.yaml
+
devos.lock

应该尽量生成相同项目。

即：

Manifest
+
Lock
+
Generator Version

决定：

Generated Project

---

47. Generator Version

Generator 本身也需要版本：

generatorVersion

否则：

同一个 Manifest

未来可能产生完全不同结果。

因此：

Project Lock

必须记录 Generator Version。

---

48. Generated File Metadata

可以记录：

{
  "path": "src/generated/agent.ts",
  "source": "capability:agent",
  "template": "agent-default",
  "templateVersion": "1.2.0",
  "hash": "..."
}

用于判断：

这个文件是否被用户修改过。

---

49. Customization Detection

如果：

Generated Hash
≠
Current Hash

说明：

User Modified

Generator 升级时：

Do Not Overwrite

或者：

Show Conflict

---

50. Generated Code Ownership

建议：

generated/

由 Factory 管理。

src/app/

由开发者管理。

src/extensions/

由开发者扩展。

这样：

Factory Update

不会破坏：

Application Code

---

51. Project Upgrade

项目升级：

devos project upgrade

流程：

Read Manifest
 ↓
Read Lock
 ↓
Resolve New Versions
 ↓
Compatibility
 ↓
Generate Diff
 ↓
Migration Plan
 ↓
Apply
 ↓
Tests

---

52. Project Upgrade 与 Plugin Upgrade

两者不同。

Plugin：

Plugin Runtime Upgrade

Project：

Project Factory Upgrade

但底层可以共用：

Version Runtime
Migration Runtime
Compatibility Runtime

---

53. Database Generation

Project Manifest 可以声明：

data:
  database:
    provider: postgresql

Modules 提供：

Resource Schema
Migration
Index
Relation

Generator 汇总。

但最终：

Migration Runtime

负责执行。

---

54. API Generation

Resource / Action / Query 定义可以生成：

REST API
OpenAPI
SDK
CLI

因此：

Project
 ↓
Resource / Action
 ↓
API Contract
 ↓
OpenAPI
 ↓
SDK

不要手工生成第二套 API Model。

---

55. UI Generation

Resource Schema 可以自动生成：

List
Detail
Create
Edit
Search
Action Buttons

因此一个 Module：

seo.website

可以只定义：

Resource
Fields
Actions
UI Metadata

然后：

Resource UI Runtime

生成大量基础 UI。

---

56. Project Factory 与 UI Shell

Generated App 默认使用：

DevOS UI Shell

而不是复制：

Header
Sidebar
Auth
Theme
Router
Notification
Task Center

这样 DevOS UI 升级可以复用。

---

57. Project Factory 与 Agent UI

如果项目需要 Agent：

capabilities:
  - agent

Generator 自动加入：

Agent Runtime
Agent UI
Task UI
Context UI
Memory UI
Model Configuration

但全部依赖：

@devos/agent
@devos/agent-context
@devos/agent-memory

---

58. Deployment Profile

Project 可以选择：

docker
docker-compose
kubernetes
bare-metal
serverless
cloud

第一阶段建议：

docker

优先。

Manifest：

deployment:
  profile: docker

---

59. Docker Generation

生成：

Dockerfile
docker-compose.yml
.env.example

但：

Secret

不应该生成真实值。

只能生成：

SECRET_REF

或者：

.env.example

---

60. Environment Generation

默认：

development
staging
production

每个环境：

Config
Secret
Provider
Database
Storage

均通过：

Configuration Runtime

管理。

---

61. CI Generation

Project Factory 可以生成：

.github/
└── workflows/
    ├── test.yml
    ├── build.yml
    └── release.yml

或者其他 CI。

但 CI 应调用：

devos project validate
devos test
devos build

而不是复制一套平台逻辑。

---

62. Project Doctor

生成后：

devos project doctor

检查：

Manifest
Lock
Dependencies
Capabilities
Modules
Plugins
Config
Secrets
Database
Migrations
API
UI
Tests
Docker

---

63. Project Validate

devos project validate

检查：

Manifest Schema
Dependency Graph
Version Compatibility
Capability Contracts
Module Contracts
Plugin Contracts
Generated Files
Architecture Rules

---

64. Project Create CLI

推荐：

devos create <name>

例如：

devos create seo-agent

交互式：

Project Type?
> AI Application

Capabilities?
> Agent
> Task
> Storage
> Search

Modules?
> SEO Website
> SEO Content

Plugins?
> GitHub
> Cloudflare

Deployment?
> Docker

最终生成：

devos.project.yaml

---

65. 非交互模式

CI / Agent 使用：

devos create seo-agent \
  --type ai-app \
  --capability agent \
  --capability task \
  --module seo.website \
  --plugin github

但更推荐：

devos create \
  --manifest devos.project.yaml

---

66. Project Registry

平台需要知道有哪些项目：

Project Registry

记录：

Project ID
Name
Type
Manifest
Version
Owner
Organization
Environment
Capabilities
Modules
Plugins
Repository
Deployment
Status

---

67. Project Registry 与 Git

Git 是：

Source Control

Project Registry 是：

DevOS Project Metadata

不要替代 Git。

---

68. Repository Integration

Project Manifest 可以：

repository:
  provider: github
  organization: acme
  repository: seo-agent

实际操作通过：

GitHub Plugin

完成。

Project Factory 不直接访问 GitHub API。

---

69. Project Factory 与 Provider

部署：

Cloudflare
AWS
GitHub
Docker

都属于：

Provider / Plugin

Project Factory 只描述：

deployment:
  provider: cloudflare

Resolver 选择 Provider。

---

70. Template Registry

模板需要 Registry：

Template Registry

记录：

Template ID
Version
Project Type
Capabilities
Dependencies
Generator Version
Compatibility
Checksum
Signature

---

71. Template Trust

模板也可能有安全问题。

因此：

Official
Verified
Community
Private

和 Plugin 类似。

生产环境不能默认运行任意不可信 Template。

---

72. Template Package

可以：

.devos-template

例如：

ai-app-1.2.0.devos-template

内容：

manifest
templates
generators
metadata
tests
checksum
signature

---

73. Generator Plugin

未来 Generator 本身也可以扩展。

例如：

React Generator
Vue Generator
Python Generator
Go Generator

但第一阶段：

Generator Runtime 必须由 DevOS Core 控制。

扩展 Generator 可以后续作为受控 Plugin。

---

74. Generator Security

Generator 可以写文件，因此必须：

Path Validation
Sandbox
No Path Traversal
No Arbitrary Command
No Secret Access
No Production Access

例如禁止：

../../../../etc/passwd

---

75. Generated Command Security

Generator 不应该随便执行：

curl
wget
bash
rm -rf

如果必须执行：

Command Runtime

统一控制。

---

76. Project Factory 与 Storage

生成项目 Artifact：

Project Build
Project Package
Generated Archive

使用：

Artifact Runtime
Storage Runtime

不要自己实现：

S3 Upload

---

77. Project Factory 与 Event

生成项目时产生：

project.created
project.generated
project.updated
project.upgraded
project.generation.failed

进入：

Event Runtime

然后可以：

Notification
Audit
Analytics
Agent
Workflow

---

78. Project Factory 与 Task

大型生成：

Project Create
 ↓
Task
 ↓
Jobs
 ↓
Worker

例如：

Generate
Install Dependencies
Run Migration
Run Tests
Build
Package
Deploy

都可以成为 Job。

---

79. Project Generation 不应该阻塞 API

小项目：

sync

大型项目：

202 Accepted
 ↓
Task

UI：

Project Generation
0% → 30% → 70% → 100%

使用：

Task Runtime
Realtime Runtime

---

80. Generation Steps

Task 可以：

Resolve
Generate
Install
Migrate
Test
Build
Package
Deploy

每一步：

Job

并记录：

Execution

---

81. Failure Recovery

例如：

Generate ✓
Install ✓
Migrate ✓
Test ✗

不应该重新：

Generate
Install
Migrate

而应该：

Resume
from Test

因此 Project Factory 必须利用：

Task Checkpoint

---

82. Project Factory Audit

每次：

Create
Update
Generate
Upgrade
Delete
Deploy

都必须记录：

Actor
Project
Manifest
Old Version
New Version
Capabilities
Modules
Plugins
Result
Reason

---

83. Project Factory Security

Project Factory 必须使用：

SecurityContext
Authorization
Scope
Environment
Policy
Audit

例如：

Developer

不能：

Generate Production Project

除非拥有对应权限。

---

84. Production Guard

生产环境：

project.environment = production

执行：

Generate
Upgrade
Deploy
Delete

可能要求：

Approval

尤其：

Database Migration
Plugin Permission Change
Production Deployment
Data Destruction

---

85. Multi-Tenancy

Project Factory 必须支持：

Organization
 ↓
Project
 ↓
Environment

Project ID 在组织内唯一。

禁止：

Organization A
 ↓
Access
 ↓
Organization B Project

---

86. Project Ownership

Project：

interface Project {
  id: string;

  organizationId: string;

  name: string;

  type: string;

  manifestVersion: string;

  runtimeVersion: string;
}

所有 Project Factory 操作都必须带：

organizationId

---

87. Project Delete

删除项目：

project.delete

必须检查：

Running Tasks
Production Environment
Artifacts
Storage
Database
Plugins
Dependencies

默认：

Soft Delete

而不是立即：

rm -rf

---

88. Project Export

项目可以导出：

Manifest
Lock
Metadata

而不是：

Secret

例如：

devos project export seo-agent

得到：

devos.project.yaml
devos.lock

Secret 必须重新绑定。

---

89. Project Import

devos project import devos.project.yaml

流程：

Validate
 ↓
Resolve
 ↓
Compatibility
 ↓
Permission
 ↓
Generate

---

90. Project Migration

如果：

DevOS 1.x

升级：

DevOS 2.x

Project Factory 应：

Manifest Migration
 ↓
Capability Migration
 ↓
Module Migration
 ↓
Plugin Compatibility
 ↓
Code Generation Migration

---

91. Manifest Migration

例如：

capabilities:
  - ai

新版本：

capabilities:
  - model
  - agent

Migration：

ai
 ↓
model + agent

Migration Runtime 自动升级 Manifest。

---

92. Capability Registry

建议：

packages/capability/

提供：

registerCapability(...)
resolveCapability(...)
findCapability(...)
checkCompatibility(...)

Plugin、Module、Project Factory 都复用。

---

93. Capability Provider

Capability 不一定由 Core 提供。

例如：

search

可以：

Core PostgreSQL Search
Plugin OpenSearch
Plugin Meilisearch

Project Factory：

search

Resolver 决定：

provider

---

94. Capability Contract

每个 Capability 应定义：

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

interface ProjectTypeDefinition {
  id: string;

  description: string;

  requiredCapabilities: string[];

  optionalCapabilities: string[];

  defaultCapabilities: string[];

  allowedModules: string[];

  allowedPlugins: string[];

  template: string;
}

---

96. Generator Contract

interface GeneratorDefinition {
  id: string;

  version: string;

  supports: {
    projectTypes: string[];
    capabilities: string[];
  };

  generate(
    context: GeneratorContext
  ): Promise<GeneratedProject>;
}

---

97. GeneratedProject

interface GeneratedProject {
  files: GeneratedFile[];

  dependencies: Dependency[];

  devDependencies: Dependency[];

  migrations: Migration[];

  commands: GeneratedCommand[];

  metadata: ProjectMetadata;
}

---

98. Generator Context

interface GeneratorContext {
  manifest: ProjectManifest;

  capabilities: ResolvedCapabilities;

  modules: ResolvedModules;

  plugins: ResolvedPlugins;

  projectType: ProjectTypeDefinition;

  template: TemplateDefinition;

  variables: Record<string, unknown>;

  outputDir: string;
}

禁止把：

Secret
Production Credential
Master Key

放入 GeneratorContext。

---

99. Template Variables

允许：

{{project.name}}
{{project.id}}
{{runtime.version}}
{{organization.id}}
{{module.id}}

不允许：

{{secret.github.token}}

---

100. Template Engine

第一阶段建议使用成熟、简单的模板系统。

例如：

Handlebars
EJS
Mustache

但不要让模板系统拥有：

eval
任意 shell
任意 JS execution

模板只应该：

render

---

101. Generator Hooks

允许：

beforeGenerate
generate
afterGenerate
validate

但是：

afterGenerate

也不能随意执行系统命令。

需要：

Command Runtime

授权。

---

102. Project Bootstrap

生成后：

devos project bootstrap

负责：

Install Dependencies
Create Config
Create Database
Run Migration
Create Development Environment
Seed Test Data
Start Services

每一步都进入：

Task Runtime

---

103. Development Seed

开发环境可以：

seed

但：

production

默认：

禁止 Development Seed

---

104. Generated Tests

Generator 必须生成：

Unit Test
Contract Test
Integration Test

对于关键 Project Type：

E2E

也应该生成。

---

105. Architecture Tests

生成项目必须自动包含：

Architecture Contract

例如：

UI
→ no Prisma

Agent
→ no Prisma

Plugin
→ no Redis

Business
→ no Queue

MCP
→ no DB

---

106. Generated CI Gate

生成项目默认：

lint
typecheck
unit
contract
integration
build

重要项目：

security
e2e
migration

---

107. Project Factory UI

DevOS UI 应提供：

Project Factory

页面：

Projects
Templates
Capabilities
Modules
Plugins
Presets
Generators
Versions
Generation Tasks

---

108. Project Create UI

流程：

1. Project Type
2. Capabilities
3. Modules
4. Plugins
5. Configuration
6. Deployment
7. Review
8. Generate

---

109. Project Plan UI

Review 页面：

Project
Capabilities
Dependencies
Modules
Plugins
Generated Files
Database Changes
Permissions
Deployment

用户确认后：

Generate

---

110. Agent Project Creation UI

用户可以：

描述需求

例如：

我要一个 AI SEO 项目，可以扫描网站、管理关键词、生成文章，并通过 GitHub 发布。

Agent 输出：

Project Type:
ai-app

Capabilities:
agent
model
task
storage
search
notification

Modules:
seo.website
seo.keyword
seo.content

Plugins:
github

然后：

Review
→ Generate

Agent 不应直接执行：

rm
git push
production deploy

除非有对应权限和审批。

---

111. Project Factory API

建议：

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：

Authentication
 ↓
Authorization
 ↓
Scope
 ↓
Project Action
 ↓
Project Factory Runtime

---

112. Project Factory SDK

@devos/project-sdk

提供：

projects.create()
projects.plan()
projects.generate()
projects.upgrade()
projects.bootstrap()
projects.validate()
projects.export()
projects.import()

SDK 不包含：

Generator Internal Logic

---

113. CLI

最终：

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

推荐：

packages/
├── project/
├── project-factory/
├── project-manifest/
├── project-registry/
├── project-generator/
├── project-template/
├── project-resolver/
├── project-migration/
├── project-testing/
└── project-sdk/

如果早期项目规模较小，可以先合并部分包。

不要为了“架构看起来完整”而机械拆包。

---

115. Project Factory Runtime

核心：

ProjectFactoryRuntime

接口：

interface ProjectFactoryRuntime {
  resolve(
    manifest: ProjectManifest
  ): Promise<ResolvedProject>;

  plan(
    manifest: ProjectManifest
  ): Promise<ProjectPlan>;

  generate(
    plan: ProjectPlan
  ): Promise<ProjectGeneration>;

  validate(
    project: Project
  ): Promise<ValidationResult>;

  upgrade(
    project: Project,
    target: UpgradeTarget
  ): Promise<UpgradePlan>;
}

---

116. Project Plan

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

相同：

Manifest
Lock
Runtime Version

应该产生：

Same Plan

否则 Agent 和 CI 无法可靠使用。

---

118. Plan 与 Apply 分离

必须：

plan

然后：

apply

不要：

create
→ 半路发现冲突
→ 修改一堆文件

推荐：

Resolve
 ↓
Plan
 ↓
Review
 ↓
Apply

---

119. Atomic Generation

生成过程中：

Temporary Directory

例如：

/tmp/devos-generation-xxxx

完成：

Validate
 ↓
Test
 ↓
Atomic Move

失败：

Discard Temporary Directory

避免生成半个项目。

---

120. Generation Transaction

Project Factory 应尽量模拟：

Prepare
 ↓
Generate
 ↓
Validate
 ↓
Commit

对于数据库：

Migration Runtime

独立处理。

---

121. Project Factory Observability

每次生成：

projectId
generationId
requestId
correlationId
actor
runtimeVersion
generatorVersion
templateVersion

必须可追踪。

---

122. Generation Metrics

至少：

generation.duration
generation.success
generation.failure
generation.files
generation.dependencies
generation.conflicts
generation.retry

可以进一步统计：

project.create.time
project.upgrade.time

---

123. Project Factory Cost

可以记录：

Generation CPU
Storage
Network
AI Token
Provider API

如果 Agent 负责项目生成：

Agent Cost
Project Generation Cost

必须区分。

---

124. Project Factory 与 Model Runtime

如果使用 AI：

Requirement
 ↓
Model Runtime
 ↓
Structured Requirement

Model Runtime 只负责：

理解
结构化
推荐

Project Factory 负责：

Validate
Resolve
Generate

AI 不可以绕过 Factory。

---

125. AI Recommendation 必须可验证

Agent 推荐：

capability: cloudflare

Resolver 必须检查：

Capability Exists
Version Compatible
Permission
Dependency
Security

不能因为 LLM 输出：

cloudflare

就直接安装。

---

126. Human Approval

高风险项目操作：

Production
External Credentials
Database Destruction
Deployment
Plugin Permission Expansion

必须：

Approval Runtime

---

127. Project Factory Security Model

完整链路：

User / Agent
    ↓
Security Context
    ↓
Project Authorization
    ↓
Project Scope
    ↓
Project Factory
    ↓
Capability Resolver
    ↓
Plugin/Module
    ↓
Action Runtime

---

128. No Direct Infrastructure

Project Factory 业务代码：

禁止直接：

Prisma
Redis
S3
SMTP
Docker
Cloud API
GitHub API

必须通过：

Data Runtime
Task Runtime
Storage Runtime
Provider Runtime
Plugin Runtime

---

129. Project Factory 不应该变成“大脚本”

错误：

projectFactory.ts
  5000 lines
  ├── createReact()
  ├── createDocker()
  ├── createGithub()
  ├── createAWS()
  ├── createSEO()
  └── createAgent()

正确：

Project Factory
 ↓
Resolver
 ↓
Capabilities
 ↓
Modules
 ↓
Templates
 ↓
Generators

---

130. Official Capability Catalog

DevOS 应维护：

Core Capability Catalog

例如：

runtime
identity
security
data
config
secret
task
event
storage
search
agent
model
notification
communication
workflow
plugin
mcp
observability

---

131. Official Module Catalog

业务能力：

SEO
CRM
Content
DevOps
Analytics
Knowledge
Automation

但这些不要直接进入 Core Runtime。

---

132. SEO Project Example

Manifest：

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

最终：

DevOS Runtime
+
SEO Modules
+
External Plugins

这符合：

一个 AI SEO 产品 + 通用 Agent OS。

---

133. DevOps Project Example

project:
  type: automation-service

capabilities:
  - security
  - task
  - event
  - storage
  - agent
  - notification

plugins:
  - github
  - docker
  - ssh

无需：

DevOps Runtime

重新实现 Queue / Event / Secret。

---

134. CRM Project Example

project:
  type: saas-app

capabilities:
  - identity
  - security
  - tenancy
  - data
  - search
  - task
  - notification

modules:
  - crm.customer
  - crm.pipeline

---

135. Standalone Backend

如果两个业务完全独立：

Project A

可以：

Fork devos-base

然后：

remove unnecessary capabilities

例如：

devos-base
 ↓
api-service

只保留：

Runtime
Security
Data
Config
API

---

136. Fork Strategy

Fork 时必须记录：

baseProject
baseVersion
forkVersion

例如：

base:
  project: devos-base
  version: 1.4.0

这样未来可以：

devos project sync-base

检查上游变化。

---

137. Fork 不等于复制后失控

Fork Project 仍然应该：

使用 Runtime Packages

只有真正需要修改：

Core Runtime

才 Fork Core。

---

138. Project Factory 与版本体系

需要锁定：

DevOS
Capability
Module
Plugin
Template
Generator
Project

例如：

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

最终：

devos.lock

应该记录完整解析结果。

它解决：

Developer A
Developer B
CI
Production

使用相同依赖。

---

140. Project Factory Acceptance Test

必须测试：

Minimal Project
API Project
SaaS Project
AI Project
Agent Project
Worker Project
Plugin Project
MCP Project

每一种：

Plan
Generate
Validate
Build
Test
Bootstrap

---

141. Generator Golden Tests

每个 Template：

Input Manifest
 ↓
Generate
 ↓
Compare Snapshot

如果输出发生意外变化：

Golden Test Failed

---

142. Dependency Resolver Tests

必须测试：

Dependency
Conflict
Cycle
Version
Optional
Peer
Plugin
Module
Capability

---

143. Upgrade Tests

测试：

Project 1.0
 ↓
Upgrade
 ↓
Project 1.1

验证：

Manifest
Code
Migration
Dependencies
Tests

---

144. Custom Code Safety Tests

必须验证：

Generated Code
+
Custom Code

升级时：

Custom Code

不会被覆盖。

---

145. Security Tests

必须测试：

Path Traversal
Command Injection
Template Injection
Secret Leakage
Production Access
Tenant Isolation
Permission Bypass
Untrusted Template
Untrusted Plugin

---

146. Project Factory Performance

大型项目：

1000+ files
100+ dependencies
50+ modules

Generator 不应该：

O(n²)

重复解析。

应该：

Cache
Dependency Graph
Template Cache
Incremental Generation

---

147. Incremental Generation

Manifest 增加：

capabilities:
  - notification

不应该：

重新生成整个项目

应该：

Diff
 ↓
Affected Templates
 ↓
Affected Files
 ↓
Generate

---

148. Generator Cache

可以缓存：

Resolved Capability
Resolved Template
Dependency Graph
Package Metadata

Redis 可以用于：

temporary coordination/cache

但：

Project Manifest
Project State
Lock

必须持久化。

---

149. Project Factory State

推荐：

PostgreSQL

存：

Project
Manifest
Generation
GenerationStep
ProjectVersion
ProjectLock
Template
Capability
Module

Redis：

Queue
Lease
Cache
Realtime Coordination

---

150. Project Factory 与 Artifact

生成结果可以保存：

Artifact

例如：

project-generation.zip
project-build.tar.gz

通过：

Artifact Runtime

管理。

---

151. Project Factory 与 Git Commit

可以提供：

devos project generate --commit

流程：

Generate
 ↓
Validate
 ↓
Test
 ↓
Git Commit

Git 操作必须通过：

Git Provider Plugin

而不是 Factory 自己实现 GitHub API。

---

152. Project Factory 与 Deployment

可以：

devos project deploy

但：

Project Factory

只负责：

Deployment Plan

实际：

Deployment Runtime

负责。

这一部分将在：

34_DEPLOYMENT_INFRASTRUCTURE_RUNTIME.md

详细定义。

---

153. 第一阶段不要做什么

不要一开始实现：

Kubernetes Generator
Cloud Provider Matrix
Multi-language Generator
Visual Builder
Marketplace Generator
AI Autonomous Coding

先完成：

Manifest
Capability
Dependency
Template
Generator
Plan
Generate
Validate
Lock

---

154. 第一 Vertical Slice

创建：

devos-base

然后：

devos create hello-app

生成：

runtime
config
api
health
test

执行：

devos project validate
devos project test
devos project build

成功。

---

155. 第二 Vertical Slice

增加：

data

生成：

Prisma
PostgreSQL
Migration
Repository

但必须通过：

Data Runtime

---

156. 第三 Vertical Slice

增加：

task

生成：

Task
Job
Queue
Worker

但直接依赖：

@devos/task

而不是复制代码。

---

157. 第四 Vertical Slice

增加：

agent

自动加入：

model
context
memory
task
event

验证：

Agent
→ Action
→ Task

---

158. 第五 Vertical Slice

加入 Plugin：

github

验证：

Project
 ↓
Plugin Resolver
 ↓
GitHub Plugin
 ↓
Action

---

159. 第六 Vertical Slice

自然语言：

创建一个 GitHub Agent 项目。

转换：

Requirement
 ↓
Manifest
 ↓
Plan
 ↓
Generate

这标志：

Project Factory 已经真正与 Agent Runtime 连通。

---

160. 推荐最终目录

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 实施铁律

实现本章时：

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 禁止事项

禁止：

复制 DevOS Runtime 到 Generated Project

禁止：

每个 Project 自己实现 Queue

禁止：

每个 Project 自己实现 Auth

禁止：

Generator 直接访问 Production

禁止：

Template 获取 Secret

禁止：

Agent 直接写任意文件

禁止：

LLM 直接决定最终 Dependency

必须：

LLM Recommendation
 ↓
Resolver Validation

---

163. Zcode Project Factory Master Prompt

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 第一阶段完成：

[ ] 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. 最终架构

                    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 关系

生成项目之后：

Project
   ↓
DevOS Runtime
   ├── Security
   ├── Identity
   ├── Data
   ├── Config
   ├── Task
   ├── Event
   ├── Storage
   ├── Search
   ├── Agent
   ├── Model
   ├── Notification
   ├── Communication
   └── Plugin

项目自己的业务：

Modules
Plugins
Extensions

全部建立在 Runtime 上。

---

167. 最终 DevOS 生产链

到这里，前面的架构可以形成完整闭环：

                    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 不只是：

一个后台管理系统

也不只是：

一个 Agent Framework

也不只是：

一个 Plugin Framework

更不是：

一个脚手架

而是：

                    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。

最终原则：

Requirement
   ↓
Manifest
   ↓
Resolve
   ↓
Plan
   ↓
Generate
   ↓
Validate
   ↓
Project
   ↓
DevOS Runtime

Manifest 决定“要什么”，Resolver 决定“依赖什么”，Generator 决定“怎么生成”，Runtime 决定“怎么运行”。

这四个职责必须始终保持分离。