DevOS v1 + Phase 2: unified resource model, infra ops, website deployment, AI chat ops
- Monorepo: NestJS API (Fastify) + React web (antd/ProComponents) + shared packages - PostgreSQL/Prisma (unified resources, relations graph, audit, events, jobs) - Auth/RBAC/workspace isolation, credential vault (AES-256-GCM) - Servers/SSH, Docker discovery & lifecycle, Job Center - Websites & deployments (git provider credential clone, env, health verification) - Domains/DNS (Cloudflare adapter), certificates (TLS probe), monitoring - Automation (cron/event/webhook HMAC + notifications), AI Gateway, MCP (29 tools) - AI chat window (LLM function-calling + rules fallback, SSE streaming, approvals) - Notes: Vditor WYSIWYG markdown editor, non-blocking autosave - Tests: 35 unit/security tests; UI audit clean (desktop+mobile, deep links)
This commit is contained in:
phptits
@@ -0,0 +1,45 @@
|
||||
# 00 — Gap Analysis
|
||||
|
||||
## 当前状态判断
|
||||
现有实现已经具备优秀的基础设施骨架：NestJS/Fastify、React/Ant Design/ProComponents、PostgreSQL/Prisma、Redis、SSH、Docker、DNS、部署、监控、Automation、AI/MCP、Credential Vault、RBAC/Audit。
|
||||
|
||||
问题不是“没有基础”，而是大量模块停留在 MVP/adapter/demo 层，尚未形成真正的 Developer Work OS。
|
||||
|
||||
## 最大缺口
|
||||
|
||||
### P0 — 必须补齐
|
||||
1. 统一 Resource Model 没有成为所有模块的真正核心。
|
||||
2. Project → Repository → Website → Server → Deployment → Domain → Monitoring 关系链不完整。
|
||||
3. Website 部署仍依赖 HTTPS 仓库 URL 内嵌 token，必须改成 Git Provider Credential + clone adapter。
|
||||
4. Git Provider 集成需要 GitHub/GitLab/Gitea 可扩展模型，而不是只存 URL。
|
||||
5. Server 管理需要从“连接/发现”升级为完整生命周期管理。
|
||||
6. Docker 管理需要更多实际操作、实时日志、资源信息。
|
||||
7. Domain/DNS/SSL 需要从 CRUD 升级为真实 provider abstraction。
|
||||
8. Automation 需要完整 trigger/action/event/job 模型和 UI。
|
||||
9. AI Agent 需要真正的 planning → approval → execution → verification，而不是 AI run demo。
|
||||
10. MCP 必须复用内部 application services，不能形成第二套业务逻辑。
|
||||
11. Email、Knowledge/Notes、Documents、Projects/Tasks 仍明显不足。
|
||||
12. Dashboard 必须成为跨资源工作台，而非统计页。
|
||||
|
||||
### P1
|
||||
- 通知中心
|
||||
- 全局搜索
|
||||
- Command Palette
|
||||
- Activity Timeline
|
||||
- Job Center
|
||||
- Resource relation UI
|
||||
- Provider connection management
|
||||
- Environment/secret 管理
|
||||
- Backup/restore abstraction
|
||||
- Webhook HMAC
|
||||
|
||||
### P2
|
||||
- Kubernetes
|
||||
- Cloud provider
|
||||
- 多租户高级策略
|
||||
- 完整邮件客户端
|
||||
- 高级文档协作
|
||||
- DAG/parallel workflow
|
||||
|
||||
## 核心判断
|
||||
后续开发不得继续以“增加一个页面/接口”为单位。必须以“完整业务闭环”为单位。
|
||||
@@ -0,0 +1,45 @@
|
||||
# 01 — Target Scope
|
||||
|
||||
DevOS 的目标不是替代每个专业软件，而是建立统一的开发者工作入口。
|
||||
|
||||
## 一级能力
|
||||
- Dashboard
|
||||
- AI
|
||||
- Projects
|
||||
- Infrastructure
|
||||
- Websites
|
||||
- Code
|
||||
- Domains
|
||||
- Email
|
||||
- Knowledge
|
||||
- Tasks
|
||||
- Automation
|
||||
- Credentials
|
||||
- Monitoring
|
||||
- Audit
|
||||
- Settings
|
||||
|
||||
## 四个核心抽象
|
||||
|
||||
```text
|
||||
Resource → Action → Event → Agent
|
||||
```
|
||||
|
||||
所有业务能力都应该尽可能映射到这四个抽象。
|
||||
|
||||
## Developer Workspace
|
||||
用户进入平台后，应能从 Project 出发看到：
|
||||
- 代码仓库
|
||||
- 网站
|
||||
- 服务器
|
||||
- 容器
|
||||
- 数据库
|
||||
- 域名
|
||||
- SSL
|
||||
- 部署
|
||||
- 监控
|
||||
- 任务
|
||||
- 文档
|
||||
- 自动化
|
||||
|
||||
并能从任何资源进入关联资源。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 02 — Unified Resource Model
|
||||
|
||||
## 原则
|
||||
Resource Registry 必须从“通用 CRUD”升级为平台的统一索引层。
|
||||
|
||||
## Resource 基础字段
|
||||
```ts
|
||||
interface Resource {
|
||||
id: string
|
||||
workspaceId: string
|
||||
type: ResourceType
|
||||
name: string
|
||||
status: string
|
||||
provider?: string
|
||||
externalId?: string
|
||||
metadata: Record<string, unknown>
|
||||
createdAt: Date
|
||||
updatedAt: Date
|
||||
}
|
||||
```
|
||||
|
||||
## 必须支持的类型
|
||||
Server, Container, Website, Domain, Certificate, Repository, Deployment, Database, Project, Task, Note, Document, Credential, Automation, Job, Monitor。
|
||||
|
||||
## Relation
|
||||
实现有方向关系并支持 relation type，例如：
|
||||
- PROJECT_HAS_REPOSITORY
|
||||
- PROJECT_HAS_WEBSITE
|
||||
- WEBSITE_DEPLOYED_TO_SERVER
|
||||
- WEBSITE_USES_DOMAIN
|
||||
- WEBSITE_HAS_DEPLOYMENT
|
||||
- DEPLOYMENT_FROM_REPOSITORY
|
||||
- DEPLOYMENT_TO_SERVER
|
||||
- SERVER_HAS_CONTAINER
|
||||
- PROJECT_HAS_TASK
|
||||
- PROJECT_HAS_DOCUMENT
|
||||
|
||||
## 关键要求
|
||||
- 所有资源必须 workspace scoped。
|
||||
- 资源详情页必须显示 Relations。
|
||||
- 支持反向关系。
|
||||
- 支持按关系跳转。
|
||||
- 删除资源前检查关系影响。
|
||||
- 不要让 Resource Registry 替代领域模型；它负责索引/关系/统一查询，领域模块负责业务规则。
|
||||
@@ -0,0 +1,58 @@
|
||||
# 03 — Infrastructure Completion
|
||||
|
||||
## Server
|
||||
完善：
|
||||
- create/edit/delete
|
||||
- connect/disconnect
|
||||
- connection health
|
||||
- OS/kernel/arch
|
||||
- CPU/RAM/disk/network
|
||||
- uptime
|
||||
- running processes摘要
|
||||
- Docker availability
|
||||
- last seen
|
||||
- tags
|
||||
- credentials reference
|
||||
|
||||
## SSH
|
||||
必须：
|
||||
- connect timeout
|
||||
- command timeout
|
||||
- output size limit
|
||||
- stderr separation
|
||||
- exit code
|
||||
- audit log
|
||||
- secret masking
|
||||
- cancellation
|
||||
|
||||
## Docker
|
||||
至少实现：
|
||||
- list containers
|
||||
- inspect
|
||||
- start/stop/restart
|
||||
- logs with tail/follow abstraction
|
||||
- image list
|
||||
- container resource usage
|
||||
- ports
|
||||
- environment key names（禁止返回 secret values）
|
||||
- status/health
|
||||
|
||||
## Jobs
|
||||
所有长任务统一 Job Center：
|
||||
- queued/running/success/failed/cancelled
|
||||
- progress
|
||||
- logs
|
||||
- retry
|
||||
- actor
|
||||
- resource relation
|
||||
|
||||
## Monitoring
|
||||
建立 provider-neutral model：
|
||||
- HTTP health check
|
||||
- TCP check
|
||||
- uptime state
|
||||
- response time
|
||||
- incident
|
||||
- recovery event
|
||||
|
||||
V1 不需要复杂 Prometheus clone，但必须让 Website/Server/Deployment 都能进入统一 monitoring/activity 体系。
|
||||
@@ -0,0 +1,61 @@
|
||||
# 04 — Website & Deployment Completion
|
||||
|
||||
## Website 生命周期
|
||||
```text
|
||||
Website
|
||||
→ Repository
|
||||
→ Environment
|
||||
→ Server
|
||||
→ Build
|
||||
→ Deploy
|
||||
→ Health Check
|
||||
→ Domain
|
||||
→ SSL
|
||||
→ Monitoring
|
||||
```
|
||||
|
||||
## Repository access
|
||||
禁止要求用户把 private repository token 放进 URL。
|
||||
|
||||
建立：
|
||||
```text
|
||||
GitProviderConnection
|
||||
├── provider
|
||||
├── credentialId
|
||||
├── externalAccountId
|
||||
└── metadata
|
||||
```
|
||||
|
||||
Repository 使用 provider + externalId/clone metadata。
|
||||
|
||||
## Deployment
|
||||
Deployment 必须成为 Job 的一种领域操作，并保存：
|
||||
- commit/ref
|
||||
- source repository
|
||||
- target server
|
||||
- environment
|
||||
- build strategy
|
||||
- deployment strategy
|
||||
- started/finished
|
||||
- logs
|
||||
- result
|
||||
- health check
|
||||
|
||||
## 部署策略
|
||||
V1 支持：
|
||||
1. Docker Compose / Dockerfile 项目
|
||||
2. 静态网站
|
||||
3. 可扩展 deployment adapter
|
||||
|
||||
不要把部署逻辑硬编码到 Website Controller。
|
||||
|
||||
## Environment
|
||||
支持：
|
||||
- development
|
||||
- staging
|
||||
- production
|
||||
|
||||
环境变量值使用 Credential Vault 或加密存储，UI 默认 mask。
|
||||
|
||||
## Health verification
|
||||
部署成功不能只看 SSH exit code，必须执行 health check；失败则 Deployment 状态为 failed/verification_failed，并展示证据。
|
||||
@@ -0,0 +1,60 @@
|
||||
# 05 — Code / Domain / Email / Knowledge
|
||||
|
||||
## Git
|
||||
建立 provider adapter：
|
||||
- GitHub
|
||||
- GitLab
|
||||
- Gitea
|
||||
|
||||
统一能力：
|
||||
- account connection
|
||||
- repositories
|
||||
- branches
|
||||
- commits
|
||||
- pull/merge requests
|
||||
- issues（基础）
|
||||
- webhook
|
||||
|
||||
V1 不需要实现 Git hosting，只需要聚合外部 provider。
|
||||
|
||||
## Domain/DNS
|
||||
建立 provider interface：
|
||||
- listZones
|
||||
- listRecords
|
||||
- createRecord
|
||||
- updateRecord
|
||||
- deleteRecord
|
||||
- verify
|
||||
|
||||
Cloudflare 是第一个正式 adapter，Manual 是 fallback。
|
||||
|
||||
DNS 操作必须有 preview + audit。
|
||||
|
||||
## SSL
|
||||
统一 Certificate 模型，provider/adaptor 可插拔。
|
||||
至少支持状态：pending/active/expired/error。
|
||||
|
||||
## Email
|
||||
V1 不做完整 Gmail clone。先实现：
|
||||
- EmailAccount
|
||||
- provider connection
|
||||
- inbox message metadata
|
||||
- send email abstraction
|
||||
- search metadata
|
||||
- attachments metadata
|
||||
|
||||
支持 SMTP/IMAP adapter；Provider OAuth 可后续加入。
|
||||
|
||||
## Knowledge
|
||||
实现：
|
||||
- Note
|
||||
- Document
|
||||
- folder/tree
|
||||
- tags
|
||||
- markdown/rich editor
|
||||
- code block
|
||||
- backlinks/resource links
|
||||
|
||||
TipTap 为默认编辑器。
|
||||
|
||||
重点：Note/Document 可以关联 Project/Resource/Task，成为操作上下文的一部分。
|
||||
@@ -0,0 +1,50 @@
|
||||
# 06 — Projects / Tasks / Automation
|
||||
|
||||
## Project
|
||||
Project 是用户工作的顶层业务上下文，而不是简单 CRUD。
|
||||
|
||||
Project overview 必须汇总：
|
||||
- repositories
|
||||
- websites
|
||||
- servers
|
||||
- domains
|
||||
- deployments
|
||||
- tasks
|
||||
- notes
|
||||
- documents
|
||||
- automations
|
||||
- recent activity
|
||||
|
||||
## Task
|
||||
支持：
|
||||
- backlog/todo/doing/review/done
|
||||
- priority
|
||||
- labels
|
||||
- due date
|
||||
- relations
|
||||
- resource links
|
||||
- activity
|
||||
|
||||
## Automation
|
||||
统一：
|
||||
```text
|
||||
Trigger → Condition → Action → Job → Event
|
||||
```
|
||||
|
||||
Triggers:
|
||||
- manual
|
||||
- cron
|
||||
- webhook
|
||||
- event
|
||||
|
||||
Actions 至少：
|
||||
- deployment.run
|
||||
- server.command（受权限和风险策略限制）
|
||||
- container.restart
|
||||
- task.create/update
|
||||
- note.create
|
||||
- notification.send
|
||||
|
||||
Webhook 必须从明文 secret 比对升级到 HMAC 签名，支持 timestamp/replay protection。
|
||||
|
||||
Automation UI 必须能创建、编辑、启停、测试、查看执行历史。
|
||||
@@ -0,0 +1,57 @@
|
||||
# 07 — AI Agent / MCP Completion
|
||||
|
||||
## Agent architecture
|
||||
```text
|
||||
Intent
|
||||
→ Context Discovery
|
||||
→ Plan
|
||||
→ Risk
|
||||
→ Approval
|
||||
→ Execute
|
||||
→ Verify
|
||||
→ Report
|
||||
```
|
||||
|
||||
## Tool registry
|
||||
每个 tool 必须包含：
|
||||
- name
|
||||
- description
|
||||
- input schema
|
||||
- output schema
|
||||
- required permissions
|
||||
- risk level
|
||||
- idempotency behavior
|
||||
- audit event
|
||||
|
||||
## V1 必须支持的 AI 场景
|
||||
1. “列出所有服务器和当前状态。”
|
||||
2. “查看 blog 项目最近一次部署。”
|
||||
3. “分析为什么网站不可用。”
|
||||
4. “部署 blog 到指定服务器。”
|
||||
5. “重启异常容器。”
|
||||
6. “创建任务记录这个问题。”
|
||||
7. “把这个事件配置成自动化。”
|
||||
|
||||
## Approval
|
||||
LOW read-only 可直接执行。
|
||||
MEDIUM 根据 policy。
|
||||
HIGH/CRITICAL 必须二次确认。
|
||||
|
||||
审批内容必须显示：
|
||||
- 操作
|
||||
- 资源
|
||||
- 影响
|
||||
- 参数摘要
|
||||
- 风险
|
||||
|
||||
## Verification
|
||||
任何 mutation tool 都应该定义 verify handler。
|
||||
例如 deployment.run → deployment.status + health.check。
|
||||
|
||||
## Memory
|
||||
V1 先做短期运行上下文 + resource references，不要过早建设复杂向量数据库。
|
||||
|
||||
## MCP
|
||||
MCP 是 DevOS Tool Registry 的 adapter。
|
||||
REST、Web UI、Agent、MCP 必须共享 application service。
|
||||
禁止 MCP 直接访问 Prisma。
|
||||
@@ -0,0 +1,35 @@
|
||||
# 08 — Security Hardening
|
||||
|
||||
这是继续开发前的 P0 gate。
|
||||
|
||||
## 立即处理
|
||||
1. 修改/禁用 README 中暴露的默认管理员账号密码。
|
||||
2. 轮换 APP_SECRET。
|
||||
3. 轮换 ENCRYPTION_KEY 前先设计 credential migration/clear strategy；不要盲目轮换导致现有凭据全部不可解密。
|
||||
4. 检查公网注册策略；生产模式默认关闭公开注册，或增加 invite-only。
|
||||
5. 检查 `/root/.ldns/config.toml`，确认 token 不进入项目、日志、git、API 响应。
|
||||
6. 删除冒烟测试 credential/test-token。
|
||||
|
||||
## Auth
|
||||
增加：
|
||||
- password change
|
||||
- session invalidation strategy（即使 V1 暂不实现完整 revoke list，也必须保留扩展点）
|
||||
- login rate limit
|
||||
- register rate limit
|
||||
- optional invite-only mode
|
||||
|
||||
## Credentials
|
||||
- AES-256-GCM 保留
|
||||
- key 不存数据库
|
||||
- secret access audit
|
||||
- API never returns plaintext
|
||||
- logs redact tokens/passwords/keys
|
||||
- export disabled by default
|
||||
|
||||
## Command security
|
||||
危险命令检测只是最后一道防线，不是授权机制。
|
||||
真正权限模型必须先于 command execution。
|
||||
|
||||
## Production config
|
||||
生产启动时必须拒绝明显开发默认 secret。
|
||||
`.env.example` 可以有 placeholder，但 runtime 必须校验。
|
||||
@@ -0,0 +1,50 @@
|
||||
# 09 — Unified Workspace UX
|
||||
|
||||
## Global shell
|
||||
ProLayout + workspace switcher + global search + notifications + AI entry。
|
||||
|
||||
## Command Palette
|
||||
支持：
|
||||
- search resource
|
||||
- go to project
|
||||
- create task
|
||||
- deploy website
|
||||
- open server
|
||||
- run automation
|
||||
- ask AI
|
||||
|
||||
## Global Search
|
||||
搜索：
|
||||
- projects
|
||||
- resources
|
||||
- repositories
|
||||
- websites
|
||||
- domains
|
||||
- tasks
|
||||
- notes
|
||||
- deployments
|
||||
|
||||
结果显示 resource type + status + project。
|
||||
|
||||
## Activity
|
||||
统一 Activity Feed，至少包括：
|
||||
- deployment
|
||||
- server command
|
||||
- automation execution
|
||||
- credential access
|
||||
- task changes
|
||||
- AI tool call
|
||||
|
||||
## Dashboard
|
||||
Dashboard 不以数字 KPI 为核心，而以“今天我要处理什么”为核心：
|
||||
- infrastructure incidents
|
||||
- failed deployments
|
||||
- pending approvals
|
||||
- tasks due
|
||||
- recent projects
|
||||
- recent activity
|
||||
- AI recommendations
|
||||
|
||||
## Resource detail
|
||||
统一 tabs：Overview / Relations / Activity / Logs / Actions。
|
||||
按资源类型隐藏不适用 tab。
|
||||
@@ -0,0 +1,41 @@
|
||||
# 10 — API/UI Contract
|
||||
|
||||
## API
|
||||
统一 `/api/v1`。
|
||||
|
||||
所有 response/error 使用已有错误契约，不得出现模块私有错误格式。
|
||||
|
||||
Mutation API：
|
||||
- authorization
|
||||
- validation
|
||||
- audit
|
||||
- job if long-running
|
||||
|
||||
## Pagination
|
||||
列表统一 cursor 或 page/limit，避免每个模块自定义。
|
||||
|
||||
## Filtering
|
||||
Resource list 支持：
|
||||
- type
|
||||
- status
|
||||
- tag
|
||||
- project
|
||||
- search
|
||||
|
||||
## UI
|
||||
ProTable + ProForm + ProDescriptions 作为默认模式。
|
||||
|
||||
长任务统一 JobDrawer/JobDetail。
|
||||
|
||||
危险操作统一 Confirm + risk explanation。
|
||||
|
||||
## Loading/error/empty
|
||||
所有页面必须处理：
|
||||
- loading
|
||||
- empty
|
||||
- permission denied
|
||||
- network error
|
||||
- operation failure
|
||||
|
||||
## API client
|
||||
前端不得在页面中直接拼 fetch URL；统一 api client/service。
|
||||
@@ -0,0 +1,35 @@
|
||||
# 11 — Test & Acceptance
|
||||
|
||||
## Quality gate
|
||||
每个 milestone 必须：
|
||||
- typecheck
|
||||
- unit tests
|
||||
- API integration tests
|
||||
- critical E2E
|
||||
- security regression
|
||||
|
||||
## Critical E2E
|
||||
1. login → workspace → dashboard
|
||||
2. add server → connect → inspect
|
||||
3. server → containers → restart → audit
|
||||
4. create project → connect repository
|
||||
5. create website → deploy → health check
|
||||
6. domain → DNS verify
|
||||
7. create task → link project/resource
|
||||
8. create automation → run → inspect job
|
||||
9. AI read-only query
|
||||
10. AI mutation → approval → execution → verification
|
||||
11. MCP tool call → same permission/audit behavior
|
||||
12. credential create → access → redaction
|
||||
|
||||
## Security tests
|
||||
- cross-workspace resource access denied
|
||||
- unauthorized server command denied
|
||||
- secret never returned by API
|
||||
- secret never appears in logs
|
||||
- webhook replay rejected
|
||||
- destructive AI action requires approval
|
||||
- production defaults rejected
|
||||
|
||||
## Done definition
|
||||
V1 Phase 2 不是“页面全部存在”，而是上述闭环可真实运行。
|
||||
@@ -0,0 +1,95 @@
|
||||
# 12 — Codex Execution Plan
|
||||
|
||||
## Rules
|
||||
- Continue from `/home/dev/bun/devos`.
|
||||
- Do NOT recreate the project.
|
||||
- Before changes, inspect current source and Prisma schema.
|
||||
- Preserve working functionality.
|
||||
- Make incremental migrations only.
|
||||
- Do not reset/drop production-like databases.
|
||||
- Do not expose secrets.
|
||||
|
||||
## Phase A — Audit and hardening
|
||||
1. Inspect auth, workspace guard, credential vault, mask utilities.
|
||||
2. Remove/disable default admin credential exposure.
|
||||
3. Add production secret validation.
|
||||
4. Disable public registration by default in production.
|
||||
5. Remove test credential.
|
||||
6. Upgrade webhook authentication to HMAC + timestamp.
|
||||
7. Add security regression tests.
|
||||
|
||||
## Phase B — Resource graph
|
||||
1. Extend ResourceRelation.
|
||||
2. Build relation service.
|
||||
3. Add resource relation endpoints.
|
||||
4. Add relation UI.
|
||||
5. Add project-centric overview.
|
||||
|
||||
## Phase C — Infrastructure
|
||||
1. Complete server lifecycle.
|
||||
2. Complete Docker operations.
|
||||
3. Standardize Job Center.
|
||||
4. Add monitoring/incident model.
|
||||
|
||||
## Phase D — Website/deployment
|
||||
1. Git provider connection model.
|
||||
2. Repository model.
|
||||
3. Credential-based private repo access.
|
||||
4. Deployment adapters.
|
||||
5. Environment management.
|
||||
6. Health verification.
|
||||
7. Deployment timeline/logs.
|
||||
|
||||
## Phase E — Code/domain/productivity
|
||||
1. GitHub/GitLab/Gitea adapters.
|
||||
2. Domain/DNS provider abstraction.
|
||||
3. Certificate model.
|
||||
4. Project/Task completion.
|
||||
5. Note/Document completion.
|
||||
6. Email account/send/search foundation.
|
||||
|
||||
## Phase F — Automation
|
||||
1. Event catalog.
|
||||
2. Trigger/action schemas.
|
||||
3. Sequential workflow executor.
|
||||
4. HMAC webhook.
|
||||
5. Job Center integration.
|
||||
6. Automation UI.
|
||||
|
||||
## Phase G — AI
|
||||
1. Tool registry.
|
||||
2. Tool permission resolver.
|
||||
3. Risk engine.
|
||||
4. Approval model/UI.
|
||||
5. Planner.
|
||||
6. Executor.
|
||||
7. Verification.
|
||||
8. Execution report.
|
||||
|
||||
## Phase H — MCP
|
||||
Expose selected stable tools through MCP, reusing the exact application services and authorization pipeline.
|
||||
|
||||
## Phase I — Unified UX
|
||||
1. Global search.
|
||||
2. Command palette.
|
||||
3. Activity feed.
|
||||
4. Job center.
|
||||
5. AI command entry.
|
||||
6. Project dashboard.
|
||||
7. Resource relation navigation.
|
||||
|
||||
## Execution protocol
|
||||
For each phase:
|
||||
1. inspect current implementation
|
||||
2. write/update design notes
|
||||
3. implement backend
|
||||
4. migrate DB safely
|
||||
5. implement frontend
|
||||
6. add tests
|
||||
7. run typecheck
|
||||
8. run unit/integration/E2E
|
||||
9. update docs
|
||||
10. report files changed and verification
|
||||
|
||||
## Important
|
||||
Do not mark a feature complete merely because its endpoint returns 200. Acceptance requires a complete user-facing workflow and tests.
|
||||
@@ -0,0 +1,21 @@
|
||||
# DevOS V1 Phase 2 — Completion Specification
|
||||
|
||||
目标：在现有 `/home/dev/bun/devos` V1 基础上继续开发，不推倒重来，补齐当前与目标产品约 80% 的差距。
|
||||
|
||||
## 使用方式
|
||||
建议先阅读：
|
||||
1. 00-GAP-ANALYSIS.md
|
||||
2. 01-TARGET-SCOPE.md
|
||||
3. 02-RESOURCE-MODEL.md
|
||||
4. 03-INFRASTRUCTURE.md
|
||||
5. 04-WEBSITE-DEPLOYMENT.md
|
||||
6. 05-GIT-DOMAIN-EMAIL-KNOWLEDGE.md
|
||||
7. 06-PROJECT-TASK-AUTOMATION.md
|
||||
8. 07-AI-AGENT-MCP.md
|
||||
9. 08-SECURITY-HARDENING.md
|
||||
10. 09-UX-UNIFIED-WORKSPACE.md
|
||||
11. 10-API-UI-CONTRACT.md
|
||||
12. 11-TEST-ACCEPTANCE.md
|
||||
13. 12-CODEX-EXECUTION.md
|
||||
|
||||
本文件包是“增量开发规范”，不是要求重新创建 DevOS。
|
||||
@@ -0,0 +1,83 @@
|
||||
# DevOS v1 Product Requirements Document
|
||||
|
||||
## 1. Product Definition
|
||||
DevOS is a Developer Work OS: a unified workspace for servers, websites, domains, code, databases, email, notes, tasks, documents, monitoring and automation, with AI as an operational Agent rather than merely a chat interface.
|
||||
|
||||
## 2. Core Product Model
|
||||
The platform is organized around four primitives:
|
||||
|
||||
**Resource + Action + Event + Agent**
|
||||
|
||||
- Resource: everything managed by DevOS.
|
||||
- Action: an operation performed against a resource.
|
||||
- Event: a state change or external signal.
|
||||
- Agent: observes resources, plans actions, executes through tools, verifies outcomes and reports.
|
||||
|
||||
The central architectural principle is the **Unified Resource Model**.
|
||||
|
||||
## 3. Primary Users
|
||||
- Individual developers
|
||||
- Small development teams
|
||||
|
||||
## 4. V1 Scope
|
||||
V1 focuses on Infrastructure OS capabilities:
|
||||
- Server
|
||||
- Docker / Containers
|
||||
- Website
|
||||
- Domain
|
||||
- Deployment
|
||||
- Monitoring
|
||||
- Authentication, Workspace, Resource, Permission and Audit foundations
|
||||
|
||||
## 5. V2 Scope
|
||||
Developer OS:
|
||||
- GitHub / GitLab / other Git providers
|
||||
- Projects
|
||||
- Tasks
|
||||
- Notes
|
||||
- Documents
|
||||
- Email
|
||||
|
||||
## 6. V3 Scope
|
||||
Automation OS:
|
||||
- Event Bus
|
||||
- Workflow Engine
|
||||
- Cron
|
||||
- Webhook
|
||||
- Notifications
|
||||
|
||||
## 7. V4 Scope
|
||||
AI OS:
|
||||
- Resource Discovery
|
||||
- Planning
|
||||
- Tool Calling
|
||||
- Execution
|
||||
- Verification
|
||||
- Memory
|
||||
- Approval
|
||||
|
||||
## 8. Representative User Journey
|
||||
“Deploy my blog to the Tokyo server, use Docker, configure blog.example.com and enable HTTPS.”
|
||||
|
||||
The intended Agent flow:
|
||||
1. Find Project and Repository
|
||||
2. Find target Server
|
||||
3. Check Docker
|
||||
4. Clone repository
|
||||
5. Build image
|
||||
6. Run container
|
||||
7. Configure reverse proxy
|
||||
8. Configure DNS
|
||||
9. Obtain SSL
|
||||
10. Health check
|
||||
11. Return an action log and result
|
||||
|
||||
## 9. Non-Goals
|
||||
- Reimplementing Git
|
||||
- Reimplementing SMTP
|
||||
- Building a Kubernetes control plane in V1
|
||||
- Building a full Notion replacement in the first release
|
||||
- Starting with microservices
|
||||
|
||||
## 10. Product Success Criteria
|
||||
A developer can manage the core infrastructure lifecycle from one workspace, while resources remain related and discoverable enough for later automation and AI operation.
|
||||
@@ -0,0 +1,105 @@
|
||||
# DevOS v1 Product Architecture
|
||||
|
||||
## 1. System Concept
|
||||
|
||||
```text
|
||||
DevOS AI
|
||||
Agent / Copilot / MCP
|
||||
|
|
||||
+-------------------+-------------------+
|
||||
| | |
|
||||
Infrastructure Projects Productivity
|
||||
| | |
|
||||
Server / Docker / DB Git / Website / API Notes / Tasks / Docs
|
||||
+-------------------+-------------------+
|
||||
|
|
||||
Unified Resource Model
|
||||
```
|
||||
|
||||
## 2. Core Primitives
|
||||
|
||||
```text
|
||||
Resource
|
||||
|
|
||||
Action
|
||||
|
|
||||
Event
|
||||
|
|
||||
Automation / Agent
|
||||
|
|
||||
Resource
|
||||
```
|
||||
|
||||
Example:
|
||||
- Resource: Website/blog.com
|
||||
- Action: Deploy
|
||||
- Event: deployment.success
|
||||
- Automation: Send notification
|
||||
- Agent: Analyze deployment
|
||||
|
||||
## 3. Resource Graph
|
||||
Resources are related rather than isolated:
|
||||
|
||||
```text
|
||||
Project
|
||||
├── Repository
|
||||
├── Website
|
||||
├── Server
|
||||
├── Database
|
||||
├── Deployment
|
||||
├── Domain
|
||||
├── Email
|
||||
└── Monitoring
|
||||
```
|
||||
|
||||
## 4. Architectural Style
|
||||
- Frontend: React application
|
||||
- Backend: modular monolith
|
||||
- Persistence: PostgreSQL
|
||||
- Cache/async infrastructure: Redis
|
||||
- Integrations: provider adapters
|
||||
- AI: Agent + Tool + MCP + Workflow layer
|
||||
- Infrastructure execution: SSH, Docker API, provider APIs
|
||||
|
||||
## 5. Module Boundaries
|
||||
Core modules:
|
||||
- Identity
|
||||
- Workspace
|
||||
- Resource
|
||||
- Permission
|
||||
- Audit
|
||||
|
||||
Infrastructure:
|
||||
- Server
|
||||
- Container
|
||||
- Website
|
||||
- Domain
|
||||
- Deployment
|
||||
- Monitoring
|
||||
|
||||
Integration:
|
||||
- Git Provider
|
||||
- DNS Provider
|
||||
- Cloud Provider
|
||||
- Email Provider
|
||||
- Docker
|
||||
|
||||
Automation:
|
||||
- Event
|
||||
- Workflow
|
||||
- Trigger
|
||||
- Action
|
||||
- Job
|
||||
|
||||
AI:
|
||||
- AI Gateway
|
||||
- Agent
|
||||
- Planner
|
||||
- Executor
|
||||
- Memory
|
||||
- Approval
|
||||
- Tools
|
||||
- MCP
|
||||
|
||||
## 6. Key Principle
|
||||
Do not turn every domain into a separate service in V1. Modules must have explicit boundaries while sharing one deployable backend.
|
||||
@@ -0,0 +1,40 @@
|
||||
# DevOS v1 Technology Stack
|
||||
|
||||
## Frontend
|
||||
- React
|
||||
- TypeScript
|
||||
- Ant Design
|
||||
- Ant Design ProComponents
|
||||
- React Router
|
||||
- TanStack Query
|
||||
- Zustand
|
||||
- TipTap
|
||||
|
||||
## Backend
|
||||
- Node.js
|
||||
- TypeScript
|
||||
- NestJS
|
||||
- Prefer Fastify adapter where appropriate
|
||||
|
||||
## Data
|
||||
- PostgreSQL
|
||||
- Prisma
|
||||
- Redis
|
||||
|
||||
## Infrastructure
|
||||
- Docker
|
||||
- SSH
|
||||
- Docker API
|
||||
- Nginx or Caddy integration
|
||||
- Linux
|
||||
- External DNS / cloud / Git / email APIs
|
||||
|
||||
## Architecture Decision
|
||||
Prefer NestJS + Prisma for the initial implementation because the source discussion prioritizes modular structure and AI-friendly code comprehension.
|
||||
|
||||
## Dependency Rule
|
||||
Do not introduce a new dependency without documenting:
|
||||
1. Why existing dependencies cannot satisfy the requirement
|
||||
2. Security and maintenance implications
|
||||
3. Operational impact
|
||||
4. Alternative considered
|
||||
@@ -0,0 +1,105 @@
|
||||
# DevOS v1 Domain Model
|
||||
|
||||
## 1. Resource
|
||||
|
||||
```typescript
|
||||
interface Resource {
|
||||
id: string
|
||||
type: ResourceType
|
||||
name: string
|
||||
workspaceId: string
|
||||
provider?: string
|
||||
status: ResourceStatus
|
||||
metadata: Record<string, unknown>
|
||||
createdAt: Date
|
||||
updatedAt: Date
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Resource Types
|
||||
Initial model:
|
||||
- Server
|
||||
- Domain
|
||||
- Website
|
||||
- Repository
|
||||
- Database
|
||||
- Container
|
||||
- EmailAccount
|
||||
- Project
|
||||
- Task
|
||||
- Note
|
||||
- Document
|
||||
- Backup
|
||||
- Deployment
|
||||
- Monitor
|
||||
- Credential
|
||||
|
||||
## 3. Core Entities
|
||||
|
||||
### Workspace
|
||||
Tenant/security boundary for users and resources.
|
||||
|
||||
### Project
|
||||
Business/work boundary connecting repositories, websites, servers, databases, deployments, domains, email and monitoring.
|
||||
|
||||
### Server
|
||||
Managed compute target. Supports SSH connection and infrastructure discovery.
|
||||
|
||||
### Website
|
||||
Deployable application resource associated with domain, repository, deployment, server/container, database, SSL, environment, logs, monitoring and backup.
|
||||
|
||||
### Deployment
|
||||
A concrete execution of deploying a repository/version to a target.
|
||||
|
||||
### Credential
|
||||
Encrypted provider or infrastructure secret reference. Secret material is never exposed as ordinary resource metadata.
|
||||
|
||||
### Task
|
||||
Work item associated with a project and optionally related to resources and automations.
|
||||
|
||||
## 4. Relationships
|
||||
|
||||
```text
|
||||
Workspace
|
||||
├── Projects
|
||||
├── Resources
|
||||
├── Users
|
||||
├── Credentials
|
||||
└── Automations
|
||||
|
||||
Project
|
||||
├── Repository*
|
||||
├── Website*
|
||||
├── Server*
|
||||
├── Database*
|
||||
├── Deployment*
|
||||
├── Domain*
|
||||
├── Task*
|
||||
└── Monitoring*
|
||||
```
|
||||
|
||||
## 5. Actions
|
||||
Every mutable operation should be modeled as an auditable action:
|
||||
- server.exec
|
||||
- server.restart
|
||||
- server.installPackage
|
||||
- website.deploy
|
||||
- website.logs
|
||||
- domain.updateRecords
|
||||
- deployment.create
|
||||
- container.restart
|
||||
|
||||
## 6. Events
|
||||
Canonical event names should use `<resource>.<verb>` or `<domain>.<verb>`:
|
||||
- deployment.created
|
||||
- deployment.started
|
||||
- deployment.success
|
||||
- deployment.failed
|
||||
- server.online
|
||||
- server.offline
|
||||
- website.down
|
||||
- website.recovered
|
||||
- email.received
|
||||
- github.push
|
||||
- task.created
|
||||
- task.completed
|
||||
@@ -0,0 +1,119 @@
|
||||
# DevOS v1 Database Schema
|
||||
|
||||
## 1. Persistence Strategy
|
||||
PostgreSQL is the system of record. Prisma is the initial ORM.
|
||||
|
||||
## 2. Core Tables
|
||||
|
||||
Recommended initial tables:
|
||||
- users
|
||||
- workspaces
|
||||
- workspace_members
|
||||
- resources
|
||||
- resource_relations
|
||||
- projects
|
||||
- project_resources
|
||||
- credentials
|
||||
- audit_logs
|
||||
- events
|
||||
- jobs
|
||||
- deployments
|
||||
- servers
|
||||
- websites
|
||||
- domains
|
||||
- containers
|
||||
- monitors
|
||||
|
||||
## 3. Resource Table
|
||||
|
||||
Conceptual schema:
|
||||
|
||||
```text
|
||||
resources
|
||||
- id
|
||||
- workspace_id
|
||||
- type
|
||||
- name
|
||||
- provider
|
||||
- status
|
||||
- metadata_json
|
||||
- created_at
|
||||
- updated_at
|
||||
```
|
||||
|
||||
Use a typed domain table when the resource has substantial operational state; use `resources` for identity, discovery and graph-level common fields.
|
||||
|
||||
## 4. Resource Relations
|
||||
|
||||
```text
|
||||
resource_relations
|
||||
- id
|
||||
- workspace_id
|
||||
- source_resource_id
|
||||
- target_resource_id
|
||||
- relation_type
|
||||
- metadata_json
|
||||
- created_at
|
||||
```
|
||||
|
||||
This allows the resource graph to evolve without embedding every relationship into one giant table.
|
||||
|
||||
## 5. Credential Storage
|
||||
Store encrypted credential payloads separately from general resource metadata.
|
||||
|
||||
```text
|
||||
credentials
|
||||
- id
|
||||
- workspace_id
|
||||
- type
|
||||
- provider
|
||||
- encrypted_data
|
||||
- metadata_json
|
||||
- created_at
|
||||
- updated_at
|
||||
```
|
||||
|
||||
The application must never log decrypted credential material.
|
||||
|
||||
## 6. Audit Log
|
||||
|
||||
```text
|
||||
audit_logs
|
||||
- id
|
||||
- workspace_id
|
||||
- actor_type
|
||||
- actor_id
|
||||
- action
|
||||
- resource_type
|
||||
- resource_id
|
||||
- risk_level
|
||||
- status
|
||||
- request_id
|
||||
- metadata_json
|
||||
- created_at
|
||||
```
|
||||
|
||||
## 7. Event
|
||||
|
||||
```text
|
||||
events
|
||||
- id
|
||||
- workspace_id
|
||||
- event_type
|
||||
- resource_id
|
||||
- payload_json
|
||||
- correlation_id
|
||||
- created_at
|
||||
```
|
||||
|
||||
## 8. Indexing
|
||||
At minimum index:
|
||||
- workspace_id
|
||||
- resource type/status
|
||||
- resource relation endpoints
|
||||
- event type + created_at
|
||||
- audit workspace + created_at
|
||||
- deployment website/project + created_at
|
||||
- jobs status + scheduled_at
|
||||
|
||||
Exact migrations should be generated from the implementation model and reviewed before production.
|
||||
@@ -0,0 +1,109 @@
|
||||
# DevOS v1 API Specification
|
||||
|
||||
## 1. API Style
|
||||
Use versioned HTTP APIs under `/api/v1`.
|
||||
|
||||
All mutations use explicit DTOs and return structured resources/results.
|
||||
|
||||
## 2. Core Endpoints
|
||||
|
||||
### Auth
|
||||
```text
|
||||
POST /api/v1/auth/login
|
||||
POST /api/v1/auth/logout
|
||||
GET /api/v1/auth/me
|
||||
```
|
||||
|
||||
### Workspaces
|
||||
```text
|
||||
GET /api/v1/workspaces
|
||||
POST /api/v1/workspaces
|
||||
GET /api/v1/workspaces/:workspaceId
|
||||
```
|
||||
|
||||
### Resources
|
||||
```text
|
||||
GET /api/v1/resources
|
||||
POST /api/v1/resources
|
||||
GET /api/v1/resources/:id
|
||||
PATCH /api/v1/resources/:id
|
||||
DELETE /api/v1/resources/:id
|
||||
GET /api/v1/resources/:id/relations
|
||||
```
|
||||
|
||||
### Servers
|
||||
```text
|
||||
GET /api/v1/servers
|
||||
POST /api/v1/servers
|
||||
GET /api/v1/servers/:id
|
||||
POST /api/v1/servers/:id/connect
|
||||
GET /api/v1/servers/:id/status
|
||||
GET /api/v1/servers/:id/containers
|
||||
POST /api/v1/servers/:id/exec
|
||||
POST /api/v1/servers/:id/restart
|
||||
```
|
||||
|
||||
### Websites
|
||||
```text
|
||||
GET /api/v1/websites
|
||||
POST /api/v1/websites
|
||||
GET /api/v1/websites/:id
|
||||
POST /api/v1/websites/:id/deploy
|
||||
GET /api/v1/websites/:id/logs
|
||||
GET /api/v1/websites/:id/health
|
||||
```
|
||||
|
||||
### Deployments
|
||||
```text
|
||||
GET /api/v1/deployments
|
||||
GET /api/v1/deployments/:id
|
||||
POST /api/v1/deployments
|
||||
POST /api/v1/deployments/:id/cancel
|
||||
```
|
||||
|
||||
### Domains
|
||||
```text
|
||||
GET /api/v1/domains
|
||||
POST /api/v1/domains
|
||||
GET /api/v1/domains/:id
|
||||
POST /api/v1/domains/:id/records
|
||||
```
|
||||
|
||||
### Automation
|
||||
```text
|
||||
GET /api/v1/automations
|
||||
POST /api/v1/automations
|
||||
GET /api/v1/automations/:id
|
||||
POST /api/v1/automations/:id/enable
|
||||
POST /api/v1/automations/:id/disable
|
||||
```
|
||||
|
||||
### AI
|
||||
```text
|
||||
POST /api/v1/ai/runs
|
||||
GET /api/v1/ai/runs/:id
|
||||
POST /api/v1/ai/runs/:id/approve
|
||||
```
|
||||
|
||||
## 3. Mutation Contract
|
||||
Every mutation:
|
||||
- validates a DTO
|
||||
- checks workspace authorization
|
||||
- determines risk
|
||||
- writes an audit record
|
||||
- emits domain events when appropriate
|
||||
- returns a request/correlation identifier
|
||||
|
||||
## 4. Error Contract
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "RESOURCE_NOT_FOUND",
|
||||
"message": "Resource was not found",
|
||||
"requestId": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Never expose stack traces, credentials or provider secrets through API errors.
|
||||
@@ -0,0 +1,71 @@
|
||||
# DevOS v1 Frontend Architecture
|
||||
|
||||
## 1. Stack
|
||||
React + TypeScript + Ant Design + ProComponents + TanStack Query + Zustand + React Router + TipTap.
|
||||
|
||||
## 2. Application Layout
|
||||
|
||||
```text
|
||||
apps/web
|
||||
├── app
|
||||
├── routes
|
||||
├── layouts
|
||||
├── features
|
||||
│ ├── auth
|
||||
│ ├── dashboard
|
||||
│ ├── resources
|
||||
│ ├── servers
|
||||
│ ├── websites
|
||||
│ ├── deployments
|
||||
│ ├── domains
|
||||
│ ├── monitoring
|
||||
│ ├── automation
|
||||
│ └── ai
|
||||
├── components
|
||||
└── services
|
||||
```
|
||||
|
||||
Shared packages:
|
||||
|
||||
```text
|
||||
packages/
|
||||
├── ui/
|
||||
├── api-client/
|
||||
├── types/
|
||||
└── auth/
|
||||
```
|
||||
|
||||
## 3. UI Principle
|
||||
Use Ant Design and ProComponents instead of building common enterprise controls from scratch.
|
||||
|
||||
Primary components:
|
||||
- ProLayout
|
||||
- ProTable
|
||||
- ProForm
|
||||
- ProDescriptions
|
||||
- ProCard
|
||||
- ProList
|
||||
|
||||
## 4. State
|
||||
- Server state: TanStack Query
|
||||
- Local UI state: Zustand / React state
|
||||
- Do not duplicate server state into global stores without a clear reason.
|
||||
|
||||
## 5. Dashboard
|
||||
The home page should prioritize:
|
||||
- AI command entry
|
||||
- Infrastructure health
|
||||
- Projects
|
||||
- Recent activity
|
||||
- Deployment/monitoring warnings
|
||||
|
||||
## 6. Resource UI
|
||||
Resource detail pages should expose:
|
||||
- Overview
|
||||
- Relations
|
||||
- Actions
|
||||
- Activity/Audit
|
||||
- Logs where applicable
|
||||
- Related resources
|
||||
|
||||
Dangerous actions require explicit confirmation and risk presentation.
|
||||
@@ -0,0 +1,73 @@
|
||||
# DevOS v1 Backend Architecture
|
||||
|
||||
## 1. Style
|
||||
Modular monolith with NestJS.
|
||||
|
||||
## 2. Suggested Structure
|
||||
|
||||
```text
|
||||
apps/api/
|
||||
├── src/
|
||||
│ ├── modules/
|
||||
│ │ ├── identity/
|
||||
│ │ ├── workspace/
|
||||
│ │ ├── resource/
|
||||
│ │ ├── permission/
|
||||
│ │ ├── audit/
|
||||
│ │ ├── server/
|
||||
│ │ ├── container/
|
||||
│ │ ├── website/
|
||||
│ │ ├── domain/
|
||||
│ │ ├── deployment/
|
||||
│ │ ├── monitoring/
|
||||
│ │ ├── automation/
|
||||
│ │ └── ai/
|
||||
│ ├── integrations/
|
||||
│ │ ├── ssh/
|
||||
│ │ ├── docker/
|
||||
│ │ ├── git/
|
||||
│ │ ├── dns/
|
||||
│ │ ├── cloud/
|
||||
│ │ └── email/
|
||||
│ ├── common/
|
||||
│ └── main.ts
|
||||
```
|
||||
|
||||
## 3. Rules
|
||||
- Controllers handle transport only.
|
||||
- DTOs define input/output contracts.
|
||||
- Business logic belongs in application/domain services.
|
||||
- Provider-specific logic belongs behind adapters.
|
||||
- Credential access is centralized.
|
||||
- Mutations are auditable.
|
||||
- Long-running operations run asynchronously.
|
||||
- External calls have timeouts, retries where safe, and idempotency where possible.
|
||||
|
||||
## 4. Infrastructure Adapters
|
||||
DevOS does not reimplement:
|
||||
- SSH
|
||||
- Git
|
||||
- Docker
|
||||
- DNS
|
||||
- SMTP
|
||||
- cloud control planes
|
||||
|
||||
It provides unified adapters over those systems.
|
||||
|
||||
## 5. Async Execution
|
||||
Use Redis-backed jobs for:
|
||||
- deployment
|
||||
- server discovery
|
||||
- monitoring checks
|
||||
- long-running SSH commands
|
||||
- automation execution
|
||||
|
||||
## 6. Observability
|
||||
Every operation should carry:
|
||||
- request ID
|
||||
- correlation ID
|
||||
- actor
|
||||
- workspace
|
||||
- resource
|
||||
- action
|
||||
- outcome
|
||||
@@ -0,0 +1,96 @@
|
||||
# DevOS v1 AI Agent Architecture
|
||||
|
||||
## 1. Principle
|
||||
AI is an operating layer, not merely a chat feature.
|
||||
|
||||
```text
|
||||
AI Gateway
|
||||
|
|
||||
+----------+----------+
|
||||
| |
|
||||
Agent Memory
|
||||
|
|
||||
+------+------+------+
|
||||
| | | |
|
||||
Tools MCP Workflow Approval
|
||||
```
|
||||
|
||||
## 2. Agent Loop
|
||||
|
||||
```text
|
||||
Observe
|
||||
↓
|
||||
Discover Resources
|
||||
↓
|
||||
Plan
|
||||
↓
|
||||
Risk Evaluation
|
||||
↓
|
||||
Approval if required
|
||||
↓
|
||||
Execute Tools
|
||||
↓
|
||||
Verify
|
||||
↓
|
||||
Report
|
||||
```
|
||||
|
||||
## 3. Tool Examples
|
||||
- server.list
|
||||
- server.exec
|
||||
- server.restart
|
||||
- server.getStatus
|
||||
- server.getDockerContainers
|
||||
- website.list
|
||||
- website.deploy
|
||||
- website.logs
|
||||
- git.repositories
|
||||
- git.commits
|
||||
- domain.records
|
||||
- email.search
|
||||
- note.create
|
||||
- task.create
|
||||
|
||||
## 4. Context
|
||||
Agent context should be built from:
|
||||
- workspace
|
||||
- user permissions
|
||||
- relevant resources
|
||||
- resource relations
|
||||
- recent events
|
||||
- task/run history
|
||||
- tool schemas
|
||||
|
||||
Do not indiscriminately inject the entire database into the model.
|
||||
|
||||
## 5. Risk
|
||||
Risk levels:
|
||||
- LOW
|
||||
- MEDIUM
|
||||
- HIGH
|
||||
- CRITICAL
|
||||
|
||||
HIGH and CRITICAL operations require user approval by default.
|
||||
|
||||
Examples:
|
||||
- production deployment
|
||||
- destructive filesystem operations
|
||||
- database deletion
|
||||
- credential changes
|
||||
|
||||
## 6. Verification
|
||||
An Agent action is not successful merely because a command returned zero. The Agent should perform domain-specific verification where possible:
|
||||
- deployment health
|
||||
- HTTP health check
|
||||
- container state
|
||||
- DNS propagation/result
|
||||
- SSL availability
|
||||
|
||||
## 7. Action Log
|
||||
Agent runs should expose human-readable steps such as:
|
||||
- found target server
|
||||
- Docker available
|
||||
- repository connected
|
||||
- deployment created
|
||||
- container started
|
||||
- health check passed
|
||||
@@ -0,0 +1,54 @@
|
||||
# DevOS v1 MCP Specification
|
||||
|
||||
## 1. Purpose
|
||||
DevOS should expose its capabilities as an MCP Server so external Agents such as ChatGPT, Claude, Cursor, Codex and other compatible agents can operate the developer infrastructure layer.
|
||||
|
||||
## 2. Conceptual Interface
|
||||
|
||||
```text
|
||||
External Agent
|
||||
|
|
||||
v
|
||||
DevOS MCP
|
||||
|
|
||||
+-- Servers
|
||||
+-- Websites
|
||||
+-- Git
|
||||
+-- Domains
|
||||
+-- Email
|
||||
+-- Notes
|
||||
+-- Tasks
|
||||
+-- Automation
|
||||
```
|
||||
|
||||
## 3. Tool Design Rules
|
||||
Tools should:
|
||||
- have narrow, explicit responsibilities
|
||||
- declare structured input/output schemas
|
||||
- be workspace-aware
|
||||
- enforce authorization server-side
|
||||
- expose risk classification
|
||||
- return stable machine-readable results
|
||||
- never return raw secrets
|
||||
|
||||
## 4. Initial Tool Set
|
||||
```text
|
||||
devos.server.list
|
||||
devos.server.status
|
||||
devos.server.exec
|
||||
devos.website.list
|
||||
devos.website.deploy
|
||||
devos.website.logs
|
||||
devos.deployment.get
|
||||
devos.domain.list
|
||||
devos.domain.records
|
||||
devos.task.create
|
||||
devos.note.create
|
||||
devos.automation.run
|
||||
```
|
||||
|
||||
## 5. Safety
|
||||
MCP is not a bypass around DevOS security. All requests must pass the same permission, credential, risk and audit layers as first-party UI/API actions.
|
||||
|
||||
## 6. Resource Exposure
|
||||
Prefer references and summarized metadata. Secrets and unnecessary infrastructure internals must not be exposed by default.
|
||||
@@ -0,0 +1,72 @@
|
||||
# DevOS v1 Automation Engine
|
||||
|
||||
## 1. Model
|
||||
|
||||
```text
|
||||
Trigger
|
||||
↓
|
||||
Condition
|
||||
↓
|
||||
Action
|
||||
↓
|
||||
Action
|
||||
↓
|
||||
Action
|
||||
```
|
||||
|
||||
## 2. Triggers
|
||||
Initial trigger classes:
|
||||
- Manual
|
||||
- Cron
|
||||
- Webhook
|
||||
- Event
|
||||
- AI Trigger
|
||||
|
||||
## 3. Example
|
||||
|
||||
```text
|
||||
WHEN github.push
|
||||
IF branch = main
|
||||
THEN build
|
||||
THEN deploy
|
||||
THEN health check
|
||||
THEN notify
|
||||
```
|
||||
|
||||
## 4. Execution Model
|
||||
Automation execution should be represented as a job/run with:
|
||||
- automation ID
|
||||
- trigger event
|
||||
- execution ID
|
||||
- step index
|
||||
- input/output references
|
||||
- status
|
||||
- retry state
|
||||
- timestamps
|
||||
- correlation ID
|
||||
|
||||
## 5. Event Bus
|
||||
Canonical events include:
|
||||
- deployment.created
|
||||
- deployment.started
|
||||
- deployment.success
|
||||
- deployment.failed
|
||||
- server.online
|
||||
- server.offline
|
||||
- website.down
|
||||
- website.recovered
|
||||
- email.received
|
||||
- github.push
|
||||
- task.created
|
||||
- task.completed
|
||||
|
||||
## 6. Reliability
|
||||
- idempotency for externally triggered workflows
|
||||
- bounded retries
|
||||
- timeout per action
|
||||
- explicit failure states
|
||||
- dead-letter handling for unrecoverable jobs
|
||||
- full audit trail
|
||||
|
||||
## 7. AI Integration
|
||||
AI may create or execute automation, but generated workflows must still pass schema validation, permissions and risk policies.
|
||||
@@ -0,0 +1,78 @@
|
||||
# DevOS v1 Security Specification
|
||||
|
||||
## 1. Threat Model
|
||||
DevOS manages highly sensitive credentials:
|
||||
- SSH keys
|
||||
- API keys
|
||||
- cloud tokens
|
||||
- Git tokens
|
||||
- SMTP credentials
|
||||
- DNS API credentials
|
||||
- database passwords
|
||||
|
||||
Therefore security is a core architecture boundary.
|
||||
|
||||
## 2. Credential Vault
|
||||
Credentials are stored encrypted, separately from ordinary resource metadata.
|
||||
|
||||
```text
|
||||
Application Master Key
|
||||
↓
|
||||
Envelope Encryption
|
||||
↓
|
||||
Encrypted Credential
|
||||
```
|
||||
|
||||
Do not store plaintext passwords or tokens in PostgreSQL.
|
||||
|
||||
## 3. Authorization
|
||||
Implement:
|
||||
- authentication
|
||||
- workspace isolation
|
||||
- RBAC
|
||||
- resource-level permission checks where required
|
||||
- action-level authorization
|
||||
|
||||
## 4. Audit
|
||||
All mutations and sensitive reads/actions should be auditable:
|
||||
- actor
|
||||
- workspace
|
||||
- action
|
||||
- resource
|
||||
- risk
|
||||
- outcome
|
||||
- timestamp
|
||||
- correlation/request ID
|
||||
|
||||
## 5. Secret Masking
|
||||
Secrets must be masked in:
|
||||
- logs
|
||||
- UI
|
||||
- Agent context
|
||||
- error messages
|
||||
- audit metadata
|
||||
- tool results
|
||||
|
||||
## 6. AI Safety
|
||||
AI execution must use the same authorization path as humans.
|
||||
|
||||
HIGH / CRITICAL:
|
||||
```text
|
||||
Plan
|
||||
↓
|
||||
User Approval
|
||||
↓
|
||||
Execute
|
||||
↓
|
||||
Verify
|
||||
```
|
||||
|
||||
## 7. Infrastructure Execution
|
||||
- SSH command execution must be scoped and logged.
|
||||
- Command timeouts are mandatory.
|
||||
- Production targets should be distinguishable.
|
||||
- Destructive actions require explicit confirmation.
|
||||
- Never allow prompt text alone to override security policy.
|
||||
|
||||
## 8. Security Non-Goals
|
||||
This document does not claim a complete production security certification. Before public production deployment, perform threat modeling, dependency review, penetration testing and secret-rotation drills.
|
||||
@@ -0,0 +1,77 @@
|
||||
# DevOS v1 UI Specification
|
||||
|
||||
## 1. Navigation
|
||||
|
||||
```text
|
||||
DevOS
|
||||
├── Dashboard
|
||||
├── AI
|
||||
├── Projects
|
||||
├── Infrastructure
|
||||
│ ├── Servers
|
||||
│ ├── Containers
|
||||
│ ├── Databases
|
||||
│ ├── Storage
|
||||
│ └── Monitoring
|
||||
├── Websites
|
||||
│ ├── Websites
|
||||
│ ├── Domains
|
||||
│ ├── SSL
|
||||
│ └── Deployments
|
||||
├── Code
|
||||
│ ├── Repositories
|
||||
│ ├── Issues
|
||||
│ ├── Pull Requests
|
||||
│ └── Releases
|
||||
├── Email
|
||||
├── Knowledge
|
||||
│ ├── Notes
|
||||
│ ├── Documents
|
||||
│ └── Knowledge Base
|
||||
├── Tasks
|
||||
├── Automation
|
||||
├── Credentials
|
||||
└── Settings
|
||||
```
|
||||
|
||||
## 2. Dashboard
|
||||
The dashboard is an operational command center, not a conventional analytics page.
|
||||
|
||||
```text
|
||||
Good morning.
|
||||
|
||||
[ AI: What do you want to do? ]
|
||||
|
||||
Infrastructure
|
||||
3 Servers | 24 Containers | 99.98% Uptime
|
||||
|
||||
Projects
|
||||
Blog | DevOS | SaaS
|
||||
|
||||
Activity
|
||||
Deployment successful
|
||||
SSL renewed
|
||||
Server disk 82%
|
||||
```
|
||||
|
||||
## 3. Resource Detail
|
||||
Every major resource should expose a consistent information architecture:
|
||||
- Summary
|
||||
- Status
|
||||
- Relations
|
||||
- Actions
|
||||
- Activity
|
||||
- Logs/metrics where relevant
|
||||
|
||||
## 4. Action UX
|
||||
Actions should show:
|
||||
- what will happen
|
||||
- target resource
|
||||
- risk level
|
||||
- expected impact
|
||||
- confirmation requirement
|
||||
- progress
|
||||
- final verification
|
||||
|
||||
## 5. Design System
|
||||
Use Ant Design as the primary visual/system foundation and ProComponents for data-heavy administration.
|
||||
@@ -0,0 +1,75 @@
|
||||
# DevOS v1 Roadmap
|
||||
|
||||
## V0 — Foundation
|
||||
- Monorepo
|
||||
- React
|
||||
- Ant Design
|
||||
- NestJS
|
||||
- PostgreSQL
|
||||
- Prisma
|
||||
- Redis
|
||||
- Docker
|
||||
- Auth
|
||||
- User
|
||||
- Workspace
|
||||
- Resource
|
||||
- Permission
|
||||
- Audit
|
||||
|
||||
## V1 — Infrastructure OS
|
||||
- Server
|
||||
- SSH
|
||||
- Docker/container discovery
|
||||
- Website
|
||||
- Domain
|
||||
- Deployment
|
||||
- SSL integration
|
||||
- Logs
|
||||
- Monitoring
|
||||
|
||||
Target flow:
|
||||
```text
|
||||
Add Server
|
||||
↓
|
||||
SSH
|
||||
↓
|
||||
Discover Docker
|
||||
↓
|
||||
View Containers
|
||||
↓
|
||||
Deploy Website
|
||||
↓
|
||||
Bind Domain
|
||||
↓
|
||||
SSL
|
||||
↓
|
||||
Logs
|
||||
```
|
||||
|
||||
## V2 — Developer OS
|
||||
- GitHub / GitLab
|
||||
- Projects
|
||||
- Tasks
|
||||
- Notes
|
||||
- Documents
|
||||
- Email
|
||||
|
||||
## V3 — Automation OS
|
||||
- Event Bus
|
||||
- Workflow Engine
|
||||
- Cron
|
||||
- Webhook
|
||||
- Notifications
|
||||
|
||||
## V4 — AI OS
|
||||
- Resource discovery
|
||||
- Planning
|
||||
- Tool calling
|
||||
- Execution
|
||||
- Verification
|
||||
- Memory
|
||||
- Approval
|
||||
- MCP
|
||||
|
||||
## Delivery Rule
|
||||
Do not start by implementing every product category. Deliver vertical slices that prove the Resource + Action + Event model.
|
||||
@@ -0,0 +1,56 @@
|
||||
# AGENTS.md — DevOS Coding Rules
|
||||
|
||||
## Mission
|
||||
Build DevOS as a maintainable modular monolith and preserve the Resource + Action + Event + Agent architecture.
|
||||
|
||||
## Mandatory Rules
|
||||
1. TypeScript strict mode.
|
||||
2. Never use `any` unless explicitly justified.
|
||||
3. All API endpoints use DTOs.
|
||||
4. Controllers contain transport concerns only.
|
||||
5. Business logic belongs in services/domain/application layers.
|
||||
6. Every mutation requires an audit record.
|
||||
7. Every credential is encrypted at rest.
|
||||
8. Secrets must never appear in logs or model context unless explicitly required and policy-approved.
|
||||
9. UI uses Ant Design / ProComponents unless there is a documented exception.
|
||||
10. Every feature must have an API contract.
|
||||
11. Every module must have tests appropriate to its risk.
|
||||
12. Do not introduce dependencies without justification.
|
||||
13. Provider-specific behavior belongs behind integration adapters.
|
||||
14. Long-running work must be asynchronous.
|
||||
15. External operations require timeout and explicit failure handling.
|
||||
16. HIGH/CRITICAL AI actions require approval.
|
||||
17. Security controls cannot be bypassed by UI, API, MCP or Agent paths.
|
||||
18. Preserve workspace isolation.
|
||||
19. Prefer idempotent operations.
|
||||
20. Update documentation when changing a domain contract.
|
||||
|
||||
## Development Sequence
|
||||
```text
|
||||
Requirement
|
||||
↓
|
||||
Domain Model
|
||||
↓
|
||||
API Contract
|
||||
↓
|
||||
UI / Interaction
|
||||
↓
|
||||
Tests
|
||||
↓
|
||||
Implementation
|
||||
↓
|
||||
Verification
|
||||
↓
|
||||
Documentation
|
||||
```
|
||||
|
||||
## Definition of Done
|
||||
A feature is not done until:
|
||||
- type checks pass
|
||||
- tests pass
|
||||
- API contract is documented
|
||||
- authorization is enforced
|
||||
- audit behavior is implemented where applicable
|
||||
- error handling exists
|
||||
- UI states cover loading/empty/error/success
|
||||
- documentation is updated
|
||||
@@ -0,0 +1,240 @@
|
||||
# DevOS v1 ZCODE Development Specification
|
||||
|
||||
## 1. Purpose
|
||||
This document converts the architecture into executable work units for an AI coding agent such as ZCODE, Codex, Cursor or Claude Code.
|
||||
|
||||
The agent must work from specifications instead of inventing architecture during implementation.
|
||||
|
||||
## 2. Repository Target
|
||||
|
||||
```text
|
||||
devos/
|
||||
├── apps/
|
||||
│ ├── web/
|
||||
│ └── api/
|
||||
├── packages/
|
||||
│ ├── ui/
|
||||
│ ├── api-client/
|
||||
│ ├── types/
|
||||
│ └── auth/
|
||||
├── packages/integrations/
|
||||
├── prisma/
|
||||
├── docs/
|
||||
├── specs/
|
||||
└── AGENTS.md
|
||||
```
|
||||
|
||||
## 3. Initial Task Queue
|
||||
|
||||
### Task 001 — Monorepo
|
||||
Create the workspace structure for web, API and shared packages.
|
||||
|
||||
Acceptance:
|
||||
- package manager/workspaces configured
|
||||
- TypeScript shared configuration
|
||||
- lint/format/test commands
|
||||
- build pipeline
|
||||
|
||||
### Task 002 — Backend Bootstrap
|
||||
Create NestJS API with versioned `/api/v1` routing.
|
||||
|
||||
Acceptance:
|
||||
- health endpoint
|
||||
- configuration management
|
||||
- structured logging
|
||||
- error handling
|
||||
- request ID
|
||||
|
||||
### Task 003 — Frontend Bootstrap
|
||||
Create React + Ant Design application.
|
||||
|
||||
Acceptance:
|
||||
- ProLayout
|
||||
- routing
|
||||
- authentication shell
|
||||
- dashboard shell
|
||||
- API client
|
||||
- loading/error/empty states
|
||||
|
||||
### Task 004 — Database
|
||||
Create PostgreSQL + Prisma setup.
|
||||
|
||||
Acceptance:
|
||||
- migrations
|
||||
- core identity/workspace/resource schema
|
||||
- seed strategy
|
||||
- database documentation
|
||||
|
||||
### Task 005 — Authentication
|
||||
Implement authentication and current-user endpoint.
|
||||
|
||||
Acceptance:
|
||||
- login/logout
|
||||
- session/token strategy
|
||||
- password/credential handling appropriate to chosen auth design
|
||||
- authorization guards
|
||||
|
||||
### Task 006 — Workspace
|
||||
Implement workspace and membership.
|
||||
|
||||
Acceptance:
|
||||
- create/list/read workspace
|
||||
- membership
|
||||
- workspace isolation in service and query layers
|
||||
|
||||
### Task 007 — Resource System
|
||||
Implement unified Resource abstraction.
|
||||
|
||||
Acceptance:
|
||||
- CRUD
|
||||
- typed resource type
|
||||
- status
|
||||
- metadata
|
||||
- relation graph
|
||||
- workspace scope
|
||||
|
||||
### Task 008 — Audit
|
||||
Implement audit service and mutation hooks.
|
||||
|
||||
Acceptance:
|
||||
- audit record for every mutation
|
||||
- actor/workspace/resource/action
|
||||
- request/correlation ID
|
||||
- sensitive data masking
|
||||
|
||||
### Task 009 — Server Module
|
||||
Implement Server resource and provider adapter.
|
||||
|
||||
Acceptance:
|
||||
- create server
|
||||
- credential reference
|
||||
- connectivity check
|
||||
- status
|
||||
- SSH execution
|
||||
- audit
|
||||
- timeout/error handling
|
||||
|
||||
### Task 010 — Docker
|
||||
Implement Docker discovery through Server integration.
|
||||
|
||||
Acceptance:
|
||||
- list containers
|
||||
- inspect container
|
||||
- restart container
|
||||
- resource relation
|
||||
- audit
|
||||
|
||||
### Task 011 — Website
|
||||
Implement Website domain model and UI.
|
||||
|
||||
Acceptance:
|
||||
- website CRUD
|
||||
- repository/server/domain relations
|
||||
- status
|
||||
- detail page
|
||||
|
||||
### Task 012 — Deployment
|
||||
Implement deployment job model and asynchronous execution.
|
||||
|
||||
Acceptance:
|
||||
- create deployment
|
||||
- run deployment
|
||||
- progress
|
||||
- logs
|
||||
- cancellation where safe
|
||||
- verification
|
||||
- success/failure events
|
||||
|
||||
### Task 013 — Domain
|
||||
Implement domain and DNS provider adapter.
|
||||
|
||||
Acceptance:
|
||||
- domain CRUD
|
||||
- record read/update
|
||||
- authorization
|
||||
- audit
|
||||
|
||||
### Task 014 — Monitoring
|
||||
Implement initial health checks.
|
||||
|
||||
Acceptance:
|
||||
- website health
|
||||
- server status
|
||||
- monitor result history
|
||||
- down/recovered events
|
||||
|
||||
### Task 015 — Event Bus
|
||||
Implement internal domain events and persistence/dispatch model.
|
||||
|
||||
Acceptance:
|
||||
- canonical event names
|
||||
- correlation IDs
|
||||
- durable execution for required events
|
||||
|
||||
### Task 016 — Automation
|
||||
Implement Trigger → Condition → Action workflow model.
|
||||
|
||||
Acceptance:
|
||||
- manual trigger
|
||||
- event trigger
|
||||
- cron design
|
||||
- execution history
|
||||
- retries/timeouts
|
||||
|
||||
### Task 017 — AI Gateway
|
||||
Implement an AI run abstraction without allowing unrestricted execution.
|
||||
|
||||
Acceptance:
|
||||
- create AI run
|
||||
- plan
|
||||
- tool registry
|
||||
- risk evaluation
|
||||
- approval state
|
||||
- execution history
|
||||
- verification result
|
||||
|
||||
### Task 018 — MCP
|
||||
Expose selected DevOS capabilities through MCP.
|
||||
|
||||
Acceptance:
|
||||
- server list/status
|
||||
- website list/deploy
|
||||
- deployment get
|
||||
- domain list/records
|
||||
- task/note tools when corresponding modules exist
|
||||
- all requests pass normal authorization/audit/risk controls
|
||||
|
||||
## 4. Agent Execution Protocol
|
||||
|
||||
For each task:
|
||||
1. Read relevant docs.
|
||||
2. Inspect existing code.
|
||||
3. State implementation plan internally.
|
||||
4. Implement the smallest coherent change.
|
||||
5. Add/update tests.
|
||||
6. Run typecheck/lint/tests.
|
||||
7. Verify API and UI contracts.
|
||||
8. Update documentation.
|
||||
9. Do not refactor unrelated code.
|
||||
|
||||
## 5. Stop Conditions
|
||||
The coding agent must stop and ask for a human decision when:
|
||||
- architecture requires a new major dependency
|
||||
- a security boundary must change
|
||||
- destructive production behavior is requested
|
||||
- domain terminology conflicts with existing specifications
|
||||
- an API breaking change is unavoidable
|
||||
- two specification documents materially conflict
|
||||
|
||||
## 6. Priority
|
||||
When requirements conflict, use this order:
|
||||
1. Security
|
||||
2. Explicit user requirement
|
||||
3. Domain model
|
||||
4. API contract
|
||||
5. Architecture
|
||||
6. UI convenience
|
||||
7. Implementation preference
|
||||
|
||||
## 7. Important Constraint
|
||||
Do not convert DevOS into microservices during V1 unless a concrete operational requirement proves modular monolith insufficient.
|
||||
@@ -0,0 +1,20 @@
|
||||
# DevOS v1 Development Document Package
|
||||
|
||||
This package was generated from the supplied architecture discussion.
|
||||
|
||||
## Source basis
|
||||
The source defines DevOS as a Developer Work OS centered on:
|
||||
- Unified Resource Model
|
||||
- Resource + Action + Event + Agent
|
||||
- Modular Monolith
|
||||
- React + Ant Design + ProComponents
|
||||
- NestJS + TypeScript
|
||||
- PostgreSQL + Prisma + Redis
|
||||
- Infrastructure/provider adapters
|
||||
- Event Bus / Automation
|
||||
- AI Agent + MCP
|
||||
- Credential Vault / RBAC / Audit / Approval
|
||||
- V0 → V1 → V2 → V3 → V4 roadmap
|
||||
|
||||
## Important
|
||||
This package preserves the source decisions and turns them into implementation-oriented specifications. Where the source did not define exact production-level details (for example exact auth protocol, complete SQL constraints, or a full MCP wire contract), this package intentionally leaves them as implementation decisions rather than pretending they were already decided.
|
||||
Reference in New Issue
Block a user