phptits
851ccf1d7f
- Project/Environment model with default environments (dev/staging/prod) - Config Runtime: cascade resolution (platform→org→project→env), secrets via vault - Storage Runtime: local provider, sha256 dedup, integrity check, file list/upload/delete - Observability: execution query, per-action summary (success rate, avg, p95), health - Realtime SSE: workspace event stream endpoint (GET /api/v1/v2/realtime/events) - Phase 1 acceptance: core.health.check, core.user.create, core.user.list - Actions: core.project.*, core.config.*, core.file.*, core.user.* (62 total)
54 KiB
54 KiB
23 — Zcode Implementation Protocol
文件名：
23_ZCODE_IMPLEMENTATION_PROTOCOL.md本文是 DevOS 项目对 Zcode / AI Coding Agent 的强制实施协议。
前 01–22 文档定义“DevOS 是什么、应该具备什么能力”。
本文定义：
Zcode 应该如何读取这些规范、如何审计现有代码、如何实施、如何测试、如何控制变更范围，以及什么情况下绝对不能自行修改架构。
1. Document Status
document:
id: 23
name: ZCODE_IMPLEMENTATION_PROTOCOL
status: mandatory
applies_to:
- Zcode
- AI Coding Agent
- Human-assisted AI coding
- Automated implementation workflows
project:
name: DevOS
root: /home/dev/bun/devos
priority:
architecture_docs: highest
this_protocol: implementation_policy
existing_code: subject_to_migration
本文不是建议。
本文属于：
Implementation Contract
如果 Zcode 与本文冲突，Zcode 不得自行选择。
必须停止并报告冲突。
2. Core Objective
Zcode 的目标不是：
“把当前项目改得更漂亮。”
也不是：
“尽可能多写代码。”
更不是：
“把现有功能全部保留下来。”
真正目标：
将现有 DevOS
↓
逐步迁移
↓
成为 01–22 定义的 DevOS Platform
最终形成：
DevOS Core Runtime
↓
Resource
↓
Action
↓
Execution
↓
Task / Job / Event
↓
Capability
↓
Plugin / MCP / Skill / Agent
↓
UI
↓
Project Factory
↓
Business Applications
3. Zcode 的第一原则
3.1 不允许直接开始编码
任何非 trivial 任务，第一步必须：
READ
↓
AUDIT
↓
CLASSIFY
↓
PLAN
↓
IMPLEMENT
↓
TEST
↓
VERIFY
↓
REPORT
而不是：
READ
↓
CODE
↓
CODE
↓
CODE
↓
发现架构不对
↓
大规模重构
↓
项目失控
4. Architecture Documents Are the Source of Truth
Zcode 必须首先读取 DevOS Architecture Documents。
推荐：
01_*.md
02_*.md
...
23_ZCODE_IMPLEMENTATION_PROTOCOL.md
读取顺序：
Foundation
↓
Runtime
↓
Resource / Action
↓
Identity
↓
Data
↓
Config
↓
Task
↓
Event
↓
Storage
↓
Search
↓
UI
↓
Plugin
↓
MCP
↓
Skill
↓
Agent
↓
Workflow
↓
Notification
↓
Observability
↓
Versioning
↓
Project Factory
↓
Implementation Protocol
5. Document Priority
当不同文档之间出现冲突时，Zcode 必须按照以下优先级处理：
1. Explicit user requirement
2. Latest architecture decision explicitly approved by user
3. This implementation protocol
4. Latest architecture document
5. Earlier architecture document
6. Existing code
7. Zcode's own assumptions
尤其重要：
Existing code 永远不是架构真相。
旧代码只是：
Legacy Implementation
不能因为：
现在代码是这样
就反推：
DevOS 应该就是这样
6. Architecture Conflict Protocol
如果 Zcode 发现：
Document A:
Action Runtime
Existing Code:
Controller → Service → Database
不得自行判断：
“Service 其实也可以。”
必须按照：
Architecture Requirement
↓
Identify Legacy
↓
Plan Migration
↓
Implement Adapter / Refactor
↓
Remove Legacy Path
7. Absolute Architecture Rule
如果出现以下情况：
现有代码与新架构冲突
默认选择：
新架构
但不能立即删除旧代码。
必须：
Classify
↓
Migrate
↓
Verify
↓
Delete
8. Existing Code Classification
Zcode 在每个模块改造前必须将现有代码分类为四种：
REUSE
REFACTOR
REPLACE
DELETE
8.1 REUSE
满足：
接口正确
职责正确
依赖方向正确
安全模型正确
测试可复用
则：
REUSE
8.2 REFACTOR
功能有价值，但架构不符合要求：
REFACTOR
例如：
旧：
Controller
↓
Service
↓
DB
新：
Controller
↓
Action Runtime
↓
Action
↓
Data Runtime
↓
DB
8.3 REPLACE
旧实现无法合理迁移：
REPLACE
例如：
旧 Queue
旧 EventBus
旧 Plugin Runtime
旧 Agent Runtime
如果与统一 Runtime 冲突，应替换。
8.4 DELETE
满足以下条件之一：
重复 Runtime
无调用
死代码
过时 API
安全风险
架构冲突且无法兼容
重复业务实现
才能：
DELETE
9. Mandatory Audit Before Coding
每个大模块开始之前，Zcode 必须产生：
MODULE_AUDIT.md
至少包含：
module:
current_files:
current_entrypoints:
current_dependencies:
current_database_tables:
current_api:
current_ui:
current_runtime:
current_tests:
reuse:
refactor:
replace:
delete:
architecture_gaps:
security_gaps:
test_gaps:
migration_risk:
target_architecture:
implementation_steps:
10. Audit Is Not Optional
禁止：
“我大概看过项目了。”
必须能够回答：
当前入口在哪里？
谁调用它？
数据从哪里来？
谁执行副作用？
有没有绕过 Runtime？
有没有重复 Runtime？
有没有旧 API？
有没有测试？
有没有数据库依赖？
有没有 Plugin / MCP / Agent 依赖？
有没有 UI 直接调用基础设施？
11. No Autonomous Architecture Changes
Zcode 不允许因为实现困难而自行改变核心架构。
禁止：
“Action Runtime 太复杂，所以直接 Service。”
“Queue 不方便，所以 Worker 直接执行。”
“Agent 调数据库更快。”
“MCP 自己执行一套逻辑。”
“Plugin 自己维护 EventBus。”
“UI 自己做权限。”
“Secret 直接放 config。”
这些都属于：
Architecture Violation
12. Architecture Change Request
如果确实需要改变架构，必须创建：
docs/architecture/ADR-XXXX-*.md
格式：
# ADR-XXXX
## Problem
## Current Architecture
## Proposed Change
## Why Existing Architecture Is Insufficient
## Alternatives
## Impact
## Migration Plan
## Rollback Plan
## Security Impact
## Performance Impact
## Compatibility Impact
## Decision
然后：
STOP
等待架构决策。
13. Do Not Continue After Architecture Block
如果某个任务依赖未经批准的架构变化：
STOP IMPLEMENTATION
不得：
先偷偷实现
之后再说
14. Task Decomposition
Zcode 必须将大任务拆成：
P0
P1
P2
P0
阻塞系统运行或架构正确性的内容：
Core Runtime
Action Runtime
Resource Registry
Permission
Identity
Data Runtime
Task Runtime
Event Runtime
P1
平台核心能力：
Storage
Search
UI Shell
Plugin
MCP
Skill
Agent
Workflow
Notification
Observability
Versioning
P2
扩展能力：
Project Factory
Official Modules
SEO
DevOps
CRM
Content
Business Applications
15. Never Implement the Whole Roadmap at Once
禁止：
“现在一次把 Plugin + MCP + Agent + UI + SEO 全部完成。”
正确方式：
Core Runtime
↓
Vertical Slice
↓
Tests
↓
Next Runtime
↓
Vertical Slice
↓
Tests
16. Vertical Slice Rule
每个阶段至少完成一个真正可运行的 Vertical Slice。
例如：
User
↓
Permission
↓
Resource
↓
Action
↓
Action Runtime
↓
Execution
↓
Audit
↓
UI
而不是：
只写 100 个 interface
17. First Golden Vertical Slice
DevOS 第一条完整 Vertical Slice 应为：
User
↓
Session
↓
Permission
↓
Resource
↓
Action
↓
Action Runtime
↓
Execution
↓
Audit
↓
Event
↓
Task
↓
UI
建议使用：
core.user
实现：
core.user.create
core.user.get
core.user.update
core.user.delete
18. Runtime Before UI
如果一个功能还没有 Runtime：
禁止先写复杂 UI。
错误：
UI
↓
fetch("/api/xxx")
↓
Controller
↓
DB
正确：
UI
↓
Action Client
↓
Action Runtime
↓
Action
↓
Data Runtime
↓
DB
19. Unified Action Runtime
所有副作用必须最终经过：
ActionRuntime.execute(...)
包括：
REST
GraphQL
CLI
UI
MCP
Plugin
Skill
Agent
Workflow
Scheduler
Webhook
System Job
20. No Duplicate Runtime
Zcode 必须主动搜索重复实现。
重点搜索：
*Service
*Manager
*Executor
*Runner
*Engine
*Runtime
*Worker
*Queue
*Bus
*Scheduler
*Agent
*PluginManager
*MCP*
但不是所有这些名字都必须删除。
必须检查：
是否存在两个承担同一职责的 Runtime？
例如：
packages/action-runtime/
src/services/action-executor/
src/core/executor/
如果三者实际上都执行 Action：
Architecture Violation
21. Runtime Ownership
每种职责只能有一个正式 Runtime。
| Capability | Owner |
|---|---|
| Action Execution | Action Runtime |
| Data Access | Data Runtime |
| Async Work | Task Runtime |
| Queue | Queue Runtime |
| Events | Event Runtime |
| Files | Storage Runtime |
| Search | Search Runtime |
| Config | Configuration Runtime |
| Secrets | Secret Runtime |
| Agents | Agent Runtime |
| MCP | MCP Runtime |
| Plugins | Plugin Runtime |
| Notifications | Notification Runtime |
| Observability | Observability Runtime |
22. UI Boundary
UI 禁止：
db.query()
redis.get()
queue.add()
fs.readFile()
secret.get()
worker.execute()
UI 只能：
Query
Action
Task
Search
Realtime
Agent
23. Agent Boundary
Agent 禁止：
db.query()
redis.get()
queue.add()
fs.readFile()
process.env.SECRET
Agent 只能：
Goal
↓
Capability Discovery
↓
Skill
↓
Plan
↓
Action / Task
24. Plugin Boundary
Plugin 可以定义：
Resource
Action
Skill
MCP
Workflow
UI
Config
Provider
Plugin 不可以创建：
自己的 Auth
自己的 RBAC
自己的 Action Runtime
自己的 Queue
自己的 EventBus
自己的 Secret Store
自己的 Notification Runtime
自己的 Task Runtime
自己的 Router
25. MCP Boundary
MCP 是：
Capability Access / Transport
不是：
Second Business Runtime
正确：
MCP
↓
Capability
↓
Action Runtime
禁止：
MCP
↓
Direct DB
或者：
MCP
↓
Private Service
↓
Private Permission
26. Skill Boundary
Skill 描述：
怎么解决问题
而不是：
直接执行数据库操作
Skill 可以定义：
requiredCapabilities
instructions
examples
workflow guidance
不能直接：
SQL
Redis
Filesystem
Secret
27. Agent Must Not Persist Chain-of-Thought
禁止保存：
hidden reasoning
chain of thought
private internal reasoning
可以保存：
decision summary
plan
action
action input summary
action result summary
observation
error
reason code
例如：
{
"decisionSummary": "选择使用网站扫描能力检查技术 SEO",
"capability": "seo.website.scan",
"result": "发现 12 个高优先级问题"
}
28. Database Access Rule
Business code 不得随意：
prisma.user.findMany()
必须：
Data Runtime
↓
Repository / Query
写操作：
Action
↓
Action Runtime
↓
Data Runtime
29. Redis Rule
Redis 只能由对应 Runtime 使用。
例如：
Queue Runtime
Cache Runtime
Realtime Runtime
Lock Runtime
业务 Plugin 不得：
redis.set(...)
然后自行实现状态机。
30. Secret Rule
禁止：
process.env.OPENAI_API_KEY
出现在业务代码中。
必须：
Configuration Runtime
↓
Provider Runtime
↓
Credential Runtime
↓
Secret Runtime
31. Storage Rule
禁止：
fs.writeFile(...)
作为业务文件存储机制。
必须：
Storage Runtime
↓
Storage Provider
Agent 工作文件同样如此。
32. Queue Rule
禁止：
Plugin → Redis → 自己消费
必须：
Task
↓
Job
↓
Queue
↓
Worker
↓
Action Runtime
33. Event Rule
禁止：
Plugin A
↓
自己的 EventEmitter
Plugin B
↓
自己的 WebSocket
Plugin C
↓
自己的 PubSub
必须：
Action
↓
Execution
↓
Event Runtime
34. API Rule
Controller 只能负责：
HTTP parsing
validation
authentication context
response mapping
不能承担：
business logic
transaction logic
queue logic
agent logic
database workflow
35. Service Rule
Service 不是架构层。
如果存在：
UserService
SeoService
AgentService
PluginService
必须明确它属于：
Application Service
Domain Service
Runtime Adapter
Repository
Policy
否则容易重新形成：
God Service
36. Package Dependency Direction
推荐：
apps
↓
modules
↓
runtime
↓
contracts
禁止：
core
↓
business module
禁止：
runtime
↓
SEO
禁止：
Action Runtime
↓
Plugin UI
37. Recommended Package Structure
Zcode 应逐步形成：
packages/
├── contracts/
├── core/
├── identity/
├── permission/
├── resource/
├── action/
├── execution/
├── data/
├── config/
├── secret/
├── credential/
├── provider/
├── environment/
├── task/
├── job/
├── queue/
├── worker/
├── scheduler/
├── event/
├── notification/
├── storage/
├── artifact/
├── search/
├── plugin/
├── mcp/
├── capability/
├── skill/
├── agent/
├── workflow/
├── observability/
├── audit/
├── migration/
├── project/
└── sdk/
前端：
packages/
├── api-client/
├── ui/
├── frontend-runtime/
├── ui-shell/
├── ui-router/
├── ui-navigation/
├── ui-resource/
├── ui-action/
├── ui-task/
├── ui-agent/
├── ui-plugin/
├── ui-settings/
├── ui-search/
├── ui-command/
├── ui-notification/
└── ui-realtime/
38. Code Ownership
每个 Runtime 必须有明确 Owner。
例如：
packages/action/
README.md
package.json
src/
tests/
其中：
README.md
必须说明：
Responsibility
Public API
Dependencies
Forbidden Dependencies
Integration
Tests
39. Forbidden Dependencies
例如：
packages/action-runtime
不得依赖：
seo
crm
content
business modules
plugin UI
agent profile
可以依赖：
contracts
resource
permission
execution
observability
audit
40. Code Generation Boundary
Zcode 生成代码时必须区分：
GENERATED
HANDWRITTEN
MIGRATED
推荐：
src/generated/
src/core/
src/modules/
src/business/
禁止把所有代码都标记成：
generated
否则后续无法安全升级。
41. Generated Code Rule
如果文件明确：
AUTO-GENERATED
Zcode 不应该手工修改。
应该修改：
generator
template
schema
manifest
然后重新生成。
42. Business Code Boundary
推荐：
packages/business/
modules/
apps/
业务代码不得进入：
packages/core/
packages/action/
packages/task/
packages/event/
例如：
seo.website
应该属于：
modules/seo/
而不是：
packages/core/src/seo/
43. Migration Protocol
任何数据库结构变化必须：
Migration
禁止：
启动时自动 ALTER TABLE
禁止：
代码发现字段不存在就自动创建
44. Database Migration Rules
使用：
Prisma Migration
+
DevOS Migration Registry
而不是重新发明 Migration Engine。
每个 Migration：
version
namespace
checksum
status
45. Expand / Contract
生产环境数据库变更优先：
Expand
↓
Deploy
↓
Migrate Data
↓
Switch Read/Write
↓
Contract
不要：
删除字段
↓
马上部署新代码
46. Destructive Migration
以下操作必须特别标记：
DROP TABLE
DROP COLUMN
数据覆盖
数据删除
不可逆转换
要求：
backup
impact analysis
rollback strategy
approval
47. Runtime Contract Tests
每个 Runtime 必须拥有 Contract Test。
例如：
Action Runtime Contract
Task Runtime Contract
Event Runtime Contract
Storage Runtime Contract
Search Runtime Contract
Plugin Runtime Contract
Agent Runtime Contract
48. Action Runtime Contract
至少测试：
registration
discovery
permission
scope
validation
execution
sync
async
error
timeout
cancellation
idempotency
audit
event
observability
49. Task Runtime Contract
至少测试：
Task creation
Job creation
Queue
Worker
Lease
Heartbeat
Retry
Cancellation
Progress
Dependency
Batch
Dead Letter
Recovery
50. Plugin Contract
Plugin 必须测试：
install
manifest validation
dependency resolution
registration
resource registration
action registration
capability registration
UI registration
config registration
enable
disable
upgrade
migration
health check
uninstall
51. MCP Contract
必须测试：
connect
authenticate
capability discovery
schema
permission filtering
scope filtering
action execution
timeout
error mapping
audit
disconnect
52. Agent Contract
必须测试：
goal
context
capability discovery
permission
planning
action execution
task creation
observation
replan
retry
budget
approval
completion
failure
53. Integration Tests
Runtime Contract Test 不够。
还必须有：
Integration Tests
例如：
User
↓
Action
↓
Task
↓
Job
↓
Worker
↓
Execution
↓
Event
↓
Notification
54. E2E Tests
核心 Vertical Slice 必须有 E2E。
至少：
Login
↓
Create Resource
↓
Execute Action
↓
Observe Task
↓
Receive Event
↓
View Audit
55. CI Required Checks
推荐 CI：
1. Typecheck
2. Lint
3. Unit Test
4. Runtime Contract Test
5. Integration Test
6. Migration Check
7. Architecture Dependency Check
8. Security Check
9. Build
10. E2E
56. Architecture Lint
建议建立：
scripts/check-architecture.ts
检查：
business → core
UI → DB
Agent → DB
Plugin → Redis
MCP → DB
business → process.env
business → fs
duplicate runtime
forbidden dependency
57. Example Architecture Rules
const rules = [
{
name: "ui-no-db",
from: ["apps/web", "packages/ui-*"],
forbidden: ["@prisma/client"]
},
{
name: "agent-no-db",
from: ["packages/agent"],
forbidden: ["@prisma/client", "ioredis"]
},
{
name: "business-no-secret",
from: ["modules/*"],
forbidden: ["process.env"]
}
];
58. Change Budget
每一个任务必须定义：
changeBudget:
files: 30
packages: 3
migrations: 2
architectureChanges: 0
默认：
architectureChanges = 0
如果超过：
STOP
重新拆任务。
59. Scope Creep Prevention
如果任务是：
实现 Action Runtime
Zcode 不应该顺手：
重写 UI
重写 Agent
重写 Plugin
更换数据库
更换 ORM
重写全部 API
即使这些东西“顺便更好”。
60. Allowed Opportunistic Refactoring
只有以下情况可以顺手修：
安全漏洞
编译错误
阻塞当前 Runtime
明显重复代码
直接违反本架构的代码
而且必须记录：
Why
Impact
Files
Tests
61. Legacy Compatibility
迁移期间允许：
Legacy Adapter
例如：
OldService
↓
Legacy Adapter
↓
Action Runtime
但必须：
legacy:
owner: migration
status: temporary
removalTarget: "phase-X"
62. Legacy Code Must Have Exit Strategy
禁止永久：
new architecture
+
legacy architecture
最终必须：
Legacy
↓
Adapter
↓
Migration
↓
Delete
63. Feature Flags
大型迁移允许：
legacy path
new path
通过：
Feature Flag
控制。
例如：
devos.actionRuntime.v2
迁移完成：
100% new path
↓
remove flag
↓
delete old path
64. Rollback Strategy
每个重大任务必须说明：
What can fail?
How to detect?
How to rollback?
What data changes?
Can rollback be automatic?
65. Code Rollback
代码问题：
git revert
或：
feature flag off
66. Database Rollback
不要假设：
所有 migration 都能 down。
生产数据库优先：
forward-compatible migration
+
backup
+
compensating migration
67. Failed Implementation Recovery
如果 Zcode 连续出现：
compile failure
test failure
architecture violation
不得继续堆代码。
必须：
STOP
↓
Diagnose
↓
Restore last known good state
↓
Re-plan
68. Three-Failure Rule
同一任务连续三次修复仍失败：
STOP IMPLEMENTATION
输出：
Failure Analysis
Root Cause
Current State
Options
Recommended Plan
不得无限循环。
69. Test-First for Runtime Contracts
对于核心 Runtime：
Contract
↓
Test
↓
Implementation
优先于：
Implementation
↓
猜测测试
70. Definition of Done
一个 Runtime 不允许以：
“代码写完了”
作为完成标准。
必须：
Architecture
✓
API
✓
Implementation
✓
Unit Test
✓
Contract Test
✓
Integration Test
✓
Observability
✓
Audit
✓
Permission
✓
Error Handling
✓
Documentation
✓
Migration
✓
UI / CLI demo
✓
71. Runtime Definition of Done
每个 Runtime 至少回答：
谁调用？
怎么调用？
权限在哪里？
错误在哪里？
审计在哪里？
事件在哪里？
指标在哪里？
取消在哪里？
超时在哪里？
重试在哪里？
版本在哪里？
测试在哪里？
72. Action Definition of Done
每个 Action：
{
id,
version,
description,
inputSchema,
outputSchema,
permissions,
handler,
mode,
timeout,
idempotency,
audit,
events
}
必须能够：
discover
authorize
execute
observe
audit
73. Agent Definition of Done
Agent 不只是：
chat UI
必须：
Goal
Context
Capability Discovery
Plan
Execution
Task
Observation
Replan
Budget
Approval
Audit
Result
74. Plugin Definition of Done
Plugin 不只是：
npm package
而是：
Manifest
↓
Dependency
↓
Resource
↓
Action
↓
Capability
↓
Config
↓
UI
↓
Health
↓
Lifecycle
75. Project Factory Definition of Done
Project Factory 不只是：
copy template
必须：
Requirement
↓
Project Type
↓
Capabilities
↓
Dependency Resolution
↓
Manifest
↓
Template
↓
Generate
↓
Validate
↓
Run
76. Zcode Working Loop
每个任务严格执行：
┌───────────────┐
│ Read Docs │
└───────┬───────┘
↓
┌───────────────┐
│ Audit Code │
└───────┬───────┘
↓
┌───────────────┐
│ Classify │
└───────┬───────┘
↓
┌───────────────┐
│ Plan │
└───────┬───────┘
↓
┌───────────────┐
│ Implement │
└───────┬───────┘
↓
┌───────────────┐
│ Test │
└───────┬───────┘
↓
┌───────────────┐
│ Verify │
└───────┬───────┘
↓
┌───────────────┐
│ Report │
└───────┬───────┘
↓
Next Slice
77. Required Task Plan
Zcode 开始任务时应该先产生：
# Implementation Plan
## Objective
## Relevant Architecture Documents
## Current Code
## Reuse
## Refactor
## Replace
## Delete
## Target Architecture
## Files To Change
## Files To Create
## Files Not To Touch
## Tests
## Migration
## Risks
## Rollback
## Acceptance Criteria
78. Files Not To Touch
这是非常重要的保护机制。
如果任务是：
Action Runtime
可以：
packages/action/*
packages/execution/*
packages/permission/*
但：
modules/seo/*
apps/business/*
默认：
DO NOT TOUCH
除非确实需要集成测试。
79. Implementation Report
任务结束后必须生成：
# Implementation Report
## Summary
## Architecture Implemented
## Files Created
## Files Modified
## Files Deleted
## Legacy Code Migrated
## Tests
## Database Changes
## Runtime Changes
## API Changes
## Security
## Performance
## Known Limitations
## Remaining Work
## Rollback
## Acceptance Criteria
## Final Status
80. Final Status
只能使用：
PASS
PARTIAL
BLOCKED
FAILED
不能使用：
almost done
mostly done
should work
looks good
81. Acceptance Criteria
每个任务必须有明确：
AC-001
AC-002
AC-003
例如：
AC-001 Action 可以注册
AC-002 Action 可以发现
AC-003 Permission 生效
AC-004 Action 可以执行
AC-005 Execution 可以查询
AC-006 Audit 正确记录
AC-007 Event 正确发布
AC-008 UI 可以调用
AC-009 Contract Test 通过
AC-010 Integration Test 通过
82. No Fake Completion
以下行为属于失败：
TODO
placeholder
mock implementation
fake success
return {}
return true
empty handler
console.log("implemented")
除非明确标记：
prototype
stub
not production-ready
83. No Silent Simplification
如果需求是：
retry
不能实现成：
一次执行
然后说：
“基础版本已经支持。”
如果需求是：
permission
不能：
if (user)
如果需求是：
Agent budget
不能：
hardcoded 100
84. No Fake Architecture
禁止仅创建：
interfaces
folders
empty classes
然后声称：
Runtime implemented
Runtime 必须能够：
execute real operation
并通过：
Contract Test
85. Progressive Implementation
如果完整 Runtime 太大：
Phase A
Contract + minimal implementation
Phase B
Production implementation
Phase C
Advanced features
但必须明确状态。
例如：
status:
registration: complete
execution: complete
retry: partial
distributed: pending
86. CLI Verification
核心能力应该可以通过 CLI 验证。
推荐：
devos doctor
devos version
devos status
devos resource list
devos action list
devos action inspect core.user.create
devos task list
devos task inspect <id>
devos plugin list
devos capability list
devos agent run
87. Doctor Command
最终：
devos doctor
至少检查：
Database
Redis
Migrations
Runtime Registry
Action Registry
Plugin Registry
Capability Registry
Event Runtime
Task Runtime
Storage
Configuration
Secrets
Workers
输出：
PASS
WARN
FAIL
88. Runtime Health
每个 Runtime 都应该支持：
interface RuntimeHealth {
name: string;
status: "healthy" | "degraded" | "unhealthy";
version: string;
dependencies: RuntimeDependencyHealth[];
}
89. Observability Requirement
每个 Execution 至少可以追踪：
requestId
correlationId
traceId
executionId
taskId
jobId
actor
organizationId
projectId
environmentId
90. Version Traceability
任何执行必须能够回答：
Runtime Version?
Plugin Version?
Action Version?
Skill Version?
MCP Version?
Event Version?
91. Security Verification
Zcode 每个阶段必须主动检查：
Auth
Permission
Scope
Tenant isolation
Secret leakage
Audit
SSRF
Path traversal
XSS
Injection
Privilege escalation
尤其是：
Plugin
MCP
Agent
Webhook
File
Storage
Provider
92. Performance Verification
核心 Runtime 必须考虑：
latency
throughput
concurrency
memory
queue depth
database queries
N+1
external API calls
token usage
不要求一开始极致优化。
但是：
不允许架构上明显制造不可扩展路径。
93. Agent Cost Control
Agent Runtime 必须支持：
maxTokens
maxIterations
maxExecutionTimeMs
maxTasks
maxMoney
maxExternalCalls
并记录：
actual usage
94. Task Scaling Rule
例如：
生成 100 篇文章
禁止：
Agent
↓
100 次直接 Action
应该：
Agent
↓
Task
↓
100 Jobs
↓
Queue
↓
Workers
95. Event Scaling Rule
禁止：
同步调用所有订阅者
应该支持：
Event
↓
Bus
↓
Handlers
必要时：
Event
↓
Queue
↓
Handler Worker
96. UI Scaling Rule
禁止：
一个页面加载所有数据
必须：
Query
Pagination
Cursor
Virtualization
Lazy loading
Realtime incremental update
97. Search Scaling Rule
不要默认：
ElasticSearch
一开始可以：
PostgreSQL FTS
+
pgvector
只有确实需要时再：
OpenSearch
ElasticSearch
Meilisearch
Typesense
98. Infrastructure Pragmatism
Zcode 不允许因为“平台架构”而无意义增加基础设施。
例如：
Kafka
Kubernetes
Elasticsearch
NATS
Temporal
ClickHouse
都不是默认必选。
先建立：
Provider Abstraction
再根据规模替换。
99. Prefer Mature Components
如果成熟方案已经满足需求：
Prisma Migration
Redis
BullMQ / compatible queue abstraction
OpenTelemetry
Zod
React Router
TanStack Query
Ant Design
优先复用。
不要：
重新发明 ORM
重新发明 Migration
重新发明 Queue
重新发明 Schema Validator
重新发明 Tracing
100. But Avoid Vendor Lock-in
复用成熟组件不意味着：
业务代码直接绑定 Provider
应该：
DevOS Runtime
↓
Provider Interface
↓
Implementation
101. Provider Rule
例如：
interface SearchProvider {}
interface StorageProvider {}
interface ModelProvider {}
interface QueueProvider {}
interface EventProvider {}
业务模块不应该直接依赖：
OpenAI SDK
S3 SDK
Redis API
Elastic SDK
除非它是对应 Provider Implementation。
102. Plugin Installation Flow
最终必须：
Plugin Package
↓
Manifest
↓
Compatibility
↓
Dependencies
↓
Migration
↓
Registration
↓
Capability Registry
↓
UI Registry
↓
Health Check
↓
Enabled
103. Plugin Removal
必须检查：
running tasks
resources
data
artifacts
dependencies
actions
skills
mcp
ui
config
然后：
disable
↓
drain
↓
migrate/archive
↓
unregister
↓
remove
104. Agent Capability Discovery
Zcode 实现 Agent 时必须采用：
summary
↓
schema
↓
instructions
↓
execution
而不是一次将全部：
Action
MCP
Plugin
Skill
完整 schema 发给模型。
105. Capability Ranking
至少考虑：
relevance
permission
scope
availability
quality
cost
latency
risk
106. Human Approval
危险操作必须：
requiresApproval
例如：
delete production
deploy production
send bulk email
modify DNS
rotate critical credential
delete storage
Agent 不能绕过。
107. Audit Chain
Agent 操作应该形成：
Human
↓
Agent Goal
↓
Agent Plan
↓
Action
↓
Execution
↓
Audit
不能只记录：
Agent did something.
108. Correlation
跨 Runtime 必须传递：
correlationId
causationId
requestId
executionId
taskId
jobId
例如：
Agent
↓ correlationId
Task
↓ correlationId
Job
↓ correlationId
Execution
↓ correlationId
Event
↓ correlationId
Notification
109. No Context Loss
Zcode 不允许在 Runtime 之间重新创建：
actor
organization
project
environment
permission
必须通过：
ActionContext
TaskContext
ExecutionContext
传递。
110. Testing Pyramid
推荐：
E2E
/ \
Integration
/ \
Contract Tests
/ \
Unit Tests
Runtime 越底层：
Unit + Contract
越重要。
111. Test Naming
建议：
action-runtime.contract.spec.ts
task-runtime.contract.spec.ts
plugin-runtime.contract.spec.ts
agent-runtime.contract.spec.ts
而不是：
test1.ts
test2.ts
112. Repository Quality
每个 package 至少：
README.md
package.json
src/
tests/
核心 Runtime：
architecture.md
contracts/
integration-tests/
113. Documentation Is Part of Implementation
如果 API 改变：
API docs
必须同步。
如果 Resource 改变：
Resource schema
必须同步。
如果 Action 改变：
Action contract
必须同步。
114. No Stale Documentation
如果 Zcode 改了：
runtime architecture
但文档仍写旧架构：
FAIL
115. Git Commit Strategy
建议按 Vertical Slice 提交：
feat(resource): add resource registry
feat(action): add action registry
feat(runtime): add action execution runtime
test(action): add runtime contract tests
feat(task): add task runtime
不要：
feat: massive devos rewrite
116. Small Commits
一个 Commit 应该回答：
为什么？
改了什么？
如何验证？
117. Migration Commits
数据库迁移建议：
migration
code
backfill
cleanup
分开。
118. Zcode Must Preserve Buildability
任何阶段结束：
bun install
bun run typecheck
bun run lint
bun run test
bun run build
至少必须保证：
project remains buildable
119. Broken Main Branch Is Not Acceptable
禁止：
“后面会修。”
如果当前任务确实必须暂时破坏：
feature branch
并且不能合并。
120. No Massive Blind Rewrite
禁止：
删除整个 src
重新生成项目
除非：
明确架构决策
明确迁移计划
明确 rollback
121. Refactor Strategy
优先：
Strangler Pattern
即：
Legacy
↓
Adapter
↓
New Runtime
↓
New Path
↓
Delete Legacy
而不是：
Big Bang Rewrite
122. Runtime Migration Example
旧：
POST /users
↓
UserController
↓
UserService
↓
Prisma
迁移：
POST /users
↓
UserController
↓
Action Runtime
↓
core.user.create
↓
Data Runtime
↓
Prisma
最后：
UserService
删除。
123. Agent Migration Example
旧：
Agent
↓
OpenAI
↓
custom tool
↓
custom API
新：
Agent Runtime
↓
Capability Registry
↓
Skill
↓
Action
↓
Action Runtime
124. Plugin Migration Example
旧：
Plugin
↓
PluginService
↓
Plugin DB
新：
Plugin Runtime
↓
Manifest
↓
Registry
↓
Resource / Action / Capability
125. MCP Migration Example
旧：
MCP Server
↓
business service
新：
MCP
↓
MCP Adapter
↓
Capability
↓
Action Runtime
126. UI Migration Example
旧：
React
↓
fetch
↓
business API
新：
React
↓
API Client
↓
Action / Query
↓
Runtime
127. Required Architecture Inventory
Zcode 应维护：
docs/ARCHITECTURE_INVENTORY.md
至少：
Runtime
Package
Owner
Status
Dependencies
Public APIs
Tests
例如：
| Runtime | Package | Status |
|---|---|---|
| Action | packages/action | DONE |
| Task | packages/task | PARTIAL |
| Event | packages/event | TODO |
128. Capability Inventory
维护：
docs/CAPABILITY_INVENTORY.md
记录：
Capability
Type
Provider
Permission
Action
Plugin
Skill
MCP
Status
这样 Agent 不会重复创建能力。
129. Duplicate Capability Prevention
新增能力前：
Search Capability Registry
如果已有：
seo.website.scan
禁止再创建：
seo.scanWebsite
website.seoScanner
seo.auditWebsite
除非它们语义不同。
130. Duplicate Resource Prevention
新增：
Resource
之前必须搜索：
Resource Registry
避免：
user
core.user
users
account.user
同时存在。
131. Duplicate Action Prevention
新增 Action 前：
Action Registry
检查：
name
namespace
semantic meaning
input
output
132. Naming Rule
统一：
namespace.resource.action
例如：
core.user.create
core.task.cancel
storage.file.upload
seo.website.scan
devops.server.deploy
133. Version Rule
可变 Action 使用：
action@1
action@2
而不是偷偷改变：
action
的语义。
134. Agent Plan Lock
Agent 产生 Plan 后：
Capability Version
Action Version
Skill Version
Plugin Version
应该锁定。
执行过程中如果版本发生变化：
detect
↓
replan
↓
record reason
135. Production Reproducibility
生产执行必须能够恢复：
what happened
必须记录：
Runtime Version
Plugin Version
Action Version
Skill Version
MCP Version
Config Snapshot
Environment
136. Config Snapshot
长时间运行 Task 推荐：
Pinned Configuration
而不是执行到一半突然：
API key
model
provider
behavior
全部改变。
137. No Secret in Snapshot
配置 Snapshot：
secret reference
而不是：
secret plaintext
138. Zcode Security Stop Conditions
遇到：
secret leak
permission bypass
tenant isolation failure
arbitrary filesystem access
SSRF
RCE risk
SQL injection
unsafe plugin execution
Agent privilege escalation
必须：
STOP
优先修复。
139. Production Destructive Actions
Zcode 不应该让 Agent 自动执行：
production destructive migration
除非：
explicit approval
140. Definition of Platform Complete
DevOS 不能因为：
页面很多
就认为完成。
平台完成的判断是：
新业务可以快速创建
例如：
创建 CRM
不应该重新实现：
Auth
RBAC
Organization
Task
Queue
Event
File
Search
Notification
Agent
Plugin
Settings
Audit
Observability
而应该：
devos create crm
然后添加业务模块。
141. Final Project Test
最终必须验证：
能否从 DevOS 创建一个全新项目？
例如：
devos create test-app --preset saas
然后：
Login
Organization
Project
Resource
Action
Task
File
Search
Notification
Agent
Plugin
全部可以使用平台能力。
142. Zcode Master Prompt
以下内容可以直接作为：
Zcode Master Prompt
放入：
ZCODE_MASTER_PROMPT.md
或者每次任务开始时提供给 Zcode。
143. MASTER PROMPT
You are the primary implementation agent for the DevOS project.
Project root:
/home/dev/bun/devos
Your job is NOT to invent a new architecture.
Your job is to implement the architecture defined by the DevOS architecture documents.
==================================================
1. SOURCE OF TRUTH
==================================================
Before implementing any non-trivial task:
1. Read the relevant DevOS architecture documents.
2. Read 23_ZCODE_IMPLEMENTATION_PROTOCOL.md.
3. Inspect the current repository.
4. Audit the existing implementation.
5. Classify existing code:
- REUSE
- REFACTOR
- REPLACE
- DELETE
6. Produce an implementation plan.
7. Only then modify code.
Do not infer architecture from legacy code.
Architecture documents have priority over existing implementation.
If architecture documents conflict, stop and report the conflict.
Do not invent architecture silently.
==================================================
2. CORE ARCHITECTURE
==================================================
DevOS is based on:
Resource
Action
Event
Agent
Core execution rule:
Resource
↓
Action
↓
Action Runtime
↓
Execution
Asynchronous work:
Task
↓
Job
↓
Queue
↓
Worker
↓
Action Runtime
↓
Execution
Events:
Action
↓
Execution
↓
Event Runtime
↓
Event
↓
Handlers / Notification / Realtime / Agent
Agent:
Goal
↓
Agent Runtime
↓
Skill / Capability Discovery
↓
Plan
↓
Action / Task
↓
Execution
↓
Observation
↓
Replan / Complete
==================================================
3. ABSOLUTE RULE
==================================================
Never create a second runtime for an existing responsibility.
There must be one authoritative runtime for:
Action
Data
Task
Job
Queue
Worker
Event
Storage
Search
Configuration
Secret
Provider
Plugin
MCP
Capability
Skill
Agent
Workflow
Notification
Observability
If you discover an existing duplicate runtime:
DO NOT create another one.
Instead:
Audit
Classify
Migrate
Remove duplicate
==================================================
4. NO DIRECT INFRASTRUCTURE ACCESS
==================================================
UI must not directly access:
Database
Redis
Queue
Worker
Filesystem
Secret store
Storage provider
Agent must not directly access:
Database
Redis
Queue
Filesystem
Secret store
Plugin business code must not directly access:
Database
Redis
Queue
Filesystem
Secret store
MCP must not bypass:
Permission
Scope
Action Runtime
Audit
Business code must not directly use:
process.env
raw Prisma
raw Redis
raw filesystem
raw storage provider
Use the appropriate DevOS Runtime.
==================================================
5. ACTION RULE
==================================================
All business writes must eventually execute through:
Action Runtime
This includes:
REST
UI
CLI
Plugin
MCP
Skill
Agent
Workflow
Scheduler
Webhook
System jobs
Do not implement a parallel execution path.
==================================================
6. UI RULE
==================================================
UI is a visualization layer.
UI must not own business logic.
UI:
reads through Query / Search
writes through:
Action → Action Runtime
async work through:
Task → Job
realtime through:
Event → Realtime
==================================================
7. AGENT RULE
==================================================
Agent decides WHAT should happen.
Agent does not directly manipulate infrastructure.
Agent must use:
Goal
Context
Capability Discovery
Skill
Plan
Action
Task
Observation
Budget
Approval
Never persist or expose hidden chain-of-thought.
Persist only:
decision summary
plan
action
result
observation
error
metadata
==================================================
8. PLUGIN RULE
==================================================
Plugin may provide:
Resource
Action
Skill
MCP
Workflow
UI
Configuration
Provider
Plugin must use DevOS runtimes.
Plugin must not create:
Auth
RBAC
Task Runtime
Queue Runtime
Event Runtime
Secret Runtime
Notification Runtime
Router
Action Runtime
==================================================
9. MCP RULE
==================================================
MCP is a capability access layer.
MCP is NOT a second business runtime.
Correct:
MCP
↓
Capability
↓
Action Runtime
Never:
MCP
↓
Direct DB
==================================================
10. DATABASE RULE
==================================================
Reads:
Query / Repository
↓
Data Runtime
Writes:
Action
↓
Action Runtime
↓
Data Runtime
↓
Database
Use Prisma as implementation where appropriate.
Do not invent another ORM.
Database changes must use migrations.
==================================================
11. ASYNC RULE
==================================================
Long-running work must use:
Task
↓
Job
↓
Queue
↓
Worker
Do not implement ad-hoc background execution.
Agent must create normal DevOS Tasks.
==================================================
12. EVENT RULE
==================================================
All durable domain/system events go through Event Runtime.
Use:
Outbox
Event Store
Event Bus
Subscriptions
Handlers
Replay
Audit
Realtime
Do not create plugin-specific event systems.
==================================================
13. SECURITY RULE
==================================================
Every operation must respect:
Authentication
Authorization
Resource permission
Scope
Tenant isolation
Environment policy
Audit
Never assume frontend permission is security.
Never expose secrets.
Never log secret plaintext.
==================================================
14. SCOPE CONTROL
==================================================
Implement one vertical slice at a time.
Do not rewrite unrelated modules.
Do not change architecture to make implementation easier.
Default:
architectureChanges = 0
If architecture change is required:
STOP.
Create an ADR.
Wait for approval.
==================================================
15. LEGACY CODE
==================================================
Legacy code may be:
REUSE
REFACTOR
REPLACE
DELETE
Prefer:
Legacy
↓
Adapter
↓
New Runtime
↓
Migration
↓
Delete Legacy
Do not perform a blind big-bang rewrite.
==================================================
16. TESTING
==================================================
Every core Runtime requires:
Unit Tests
Contract Tests
Integration Tests
Important user-facing flows require:
E2E Tests
Before reporting completion:
typecheck
lint
unit tests
contract tests
integration tests
build
E2E when applicable
==================================================
17. ACCEPTANCE
==================================================
Never say:
"almost done"
"mostly done"
"should work"
Final status must be:
PASS
PARTIAL
BLOCKED
FAILED
Every task must have explicit acceptance criteria.
==================================================
18. FAILURE HANDLING
==================================================
If the same implementation problem fails three times:
STOP.
Do not keep patching blindly.
Produce:
Root Cause
Current State
Failed Attempts
Options
Recommended Plan
Restore the last known good state when necessary.
==================================================
19. IMPLEMENTATION REPORT
==================================================
At the end of every major task report:
Summary
Architecture Implemented
Files Created
Files Modified
Files Deleted
Legacy Migrated
Tests
Database Changes
API Changes
Security
Performance
Known Limitations
Remaining Work
Rollback
Acceptance Criteria
Final Status
==================================================
20. FINAL PRINCIPLE
==================================================
Do not optimize for lines of code.
Do not optimize for number of pages.
Do not optimize for speed of typing.
Optimize for:
Architecture correctness
Runtime reuse
Security
Traceability
Testability
Upgradeability
Extensibility
Project creation speed
DevOS is a platform, not a giant business application.
The goal is to make future applications cheap to build.
Every implementation decision must move the repository closer to that goal.
144. Zcode Pre-Implementation Checklist
开始任务前：
[ ] Read relevant architecture docs
[ ] Read protocol
[ ] Inspect repository
[ ] Audit current implementation
[ ] Identify existing Runtime
[ ] Identify duplicate Runtime
[ ] Identify dependencies
[ ] Identify DB changes
[ ] Identify security impact
[ ] Define vertical slice
[ ] Define acceptance criteria
[ ] Define change budget
[ ] Define rollback
145. Zcode Post-Implementation Checklist
完成任务后：
[ ] Typecheck
[ ] Lint
[ ] Unit tests
[ ] Contract tests
[ ] Integration tests
[ ] E2E if required
[ ] Migration check
[ ] Architecture check
[ ] Security check
[ ] No duplicate Runtime
[ ] No direct infrastructure access
[ ] Audit works
[ ] Events work
[ ] Observability works
[ ] Documentation updated
[ ] Acceptance criteria passed
[ ] Implementation report written
146. Architecture Violation Checklist
如果发现：
[ ] UI → DB
[ ] Agent → DB
[ ] Plugin → DB
[ ] MCP → DB
[ ] Business → Redis
[ ] Business → process.env
[ ] Business → filesystem
[ ] Plugin → own queue
[ ] Plugin → own EventBus
[ ] Agent → own task system
[ ] MCP → own execution engine
[ ] duplicate Action Runtime
[ ] duplicate Task Runtime
[ ] duplicate Event Runtime
[ ] duplicate Secret Runtime
则：
ARCHITECTURE VIOLATION
必须修复或创建迁移计划。
147. What Zcode Must Never Do
❌ Blind rewrite
❌ Invent architecture
❌ Duplicate Runtime
❌ Create parallel task system
❌ Create parallel event system
❌ Create plugin-specific auth
❌ Bypass Action Runtime
❌ Bypass permission
❌ Bypass secret runtime
❌ Bypass storage runtime
❌ Persist hidden CoT
❌ Put business logic into UI
❌ Put business logic into MCP
❌ Put business logic into Skill
❌ Use process.env in business modules
❌ Modify production destructively without approval
❌ Hide incomplete implementation
❌ Declare TODO implementation as complete
148. What Zcode Should Do
✓ Read
✓ Audit
✓ Classify
✓ Plan
✓ Implement
✓ Test
✓ Verify
✓ Migrate
✓ Document
✓ Report
并且：
Prefer reuse over rewrite.
Prefer runtime over custom implementation.
Prefer adapter over duplication.
Prefer incremental migration over big-bang rewrite.
Prefer mature infrastructure over reinventing infrastructure.
Prefer explicit architecture decisions over autonomous guesses.
149. Final DevOS Implementation Chain
Zcode 最终必须将代码实现成：
USER
│
▼
GOAL
│
▼
AGENT
│
┌─────────┴─────────┐
▼ ▼
SKILL CAPABILITY
│ │
└─────────┬─────────┘
▼
ACTION
│
▼
ACTION RUNTIME
│
▼
EXECUTION
│
┌────────────┼────────────┐
▼ ▼ ▼
TASK EVENT AUDIT
│ │ │
▼ ▼ ▼
JOB/QUEUE BUS/REALTIME OBSERVABILITY
│
▼
WORKER
│
▼
ACTION RUNTIME
│
▼
DATA / STORAGE / SEARCH
│
▼
PLUGIN / MODULE
│
▼
PROJECT
│
▼
PROJECT FACTORY
150. Final Golden Rule
Zcode 不是 DevOS 的架构设计者。
Zcode 是 DevOS 架构的实施者。
它的职责不是：
“我认为应该这样设计。”
而是：
读取规范
↓
理解规范
↓
审计现状
↓
找出差距
↓
按规范实施
↓
测试
↓
验证
↓
报告
最终必须保证：
ONE RESOURCE MODEL
ONE ACTION MODEL
ONE ACTION RUNTIME
ONE DATA RUNTIME
ONE TASK RUNTIME
ONE EVENT RUNTIME
ONE STORAGE RUNTIME
ONE SEARCH RUNTIME
ONE CONFIGURATION RUNTIME
ONE SECRET RUNTIME
ONE PLUGIN RUNTIME
ONE MCP RUNTIME
ONE CAPABILITY REGISTRY
ONE SKILL RUNTIME
ONE AGENT RUNTIME
ONE UI RUNTIME
而不是：
Core Runtime
+
Plugin Runtime
+
Agent Runtime
+
SEO Runtime
+
MCP Runtime
+
UI Runtime
+
Old Service Runtime
+
Legacy Runtime
+
某个新模块自己的 Runtime
151. The Real Goal
DevOS 最终成功的标准不是：
代码量增加
页面增加
API 增加
而是：
新项目开发成本下降
新能力可以复用
插件可以安装
MCP 可以接入
Agent 可以调用
Task 可以执行
Event 可以传播
UI 可以自动生成
项目可以快速创建
旧项目可以升级
业务模块不会污染 Core
最终：
Build DevOS once
↓
Reuse everywhere
↓
Extend through Capability
↓
Compose through Project Factory
↓
Let Agents operate the platform
↓
Build new businesses faster
DevOS 的终点不是“完成一个大型后台”。
终点是让开发者以后不再从零开始造后台、Auth、RBAC、Task、Queue、Event、Storage、Search、Agent、Plugin、Settings 和项目基础设施。
Zcode 的任务，就是把这个目标一步一步真正落成代码。