devos/Docs/DevOS-Platform-v2/23_ZCODE_IMPLEMENTATION_PROTOCOL.md

# 23 — Zcode Implementation Protocol

> **文件名：`23_ZCODE_IMPLEMENTATION_PROTOCOL.md`**
>
> 本文是 DevOS 项目对 Zcode / AI Coding Agent 的**强制实施协议**。
>
> 前 01–22 文档定义“DevOS 是什么、应该具备什么能力”。
>
> 本文定义：
>
> **Zcode 应该如何读取这些规范、如何审计现有代码、如何实施、如何测试、如何控制变更范围，以及什么情况下绝对不能自行修改架构。**

---

# 1. Document Status

```yaml
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 的目标不是：

> “把当前项目改得更漂亮。”

也不是：

> “尽可能多写代码。”

更不是：

> “把现有功能全部保留下来。”

真正目标：

```text
将现有 DevOS
        ↓
逐步迁移
        ↓
成为 01–22 定义的 DevOS Platform
```

最终形成：

```text
DevOS Core Runtime
        ↓
Resource
        ↓
Action
        ↓
Execution
        ↓
Task / Job / Event
        ↓
Capability
        ↓
Plugin / MCP / Skill / Agent
        ↓
UI
        ↓
Project Factory
        ↓
Business Applications
```

---

# 3. Zcode 的第一原则

## 3.1 不允许直接开始编码

任何非 trivial 任务，第一步必须：

```text
READ
 ↓
AUDIT
 ↓
CLASSIFY
 ↓
PLAN
 ↓
IMPLEMENT
 ↓
TEST
 ↓
VERIFY
 ↓
REPORT
```

而不是：

```text
READ
 ↓
CODE
 ↓
CODE
 ↓
CODE
 ↓
发现架构不对
 ↓
大规模重构
 ↓
项目失控
```

---

# 4. Architecture Documents Are the Source of Truth

Zcode 必须首先读取 DevOS Architecture Documents。

推荐：

```text
01_*.md
02_*.md
...
23_ZCODE_IMPLEMENTATION_PROTOCOL.md
```

读取顺序：

```text
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 必须按照以下优先级处理：

```text
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 永远不是架构真相。**

旧代码只是：

```text
Legacy Implementation
```

不能因为：

```text
现在代码是这样
```

就反推：

```text
DevOS 应该就是这样
```

---

# 6. Architecture Conflict Protocol

如果 Zcode 发现：

```text
Document A:
Action Runtime

Existing Code:
Controller → Service → Database
```

不得自行判断：

> “Service 其实也可以。”

必须按照：

```text
Architecture Requirement
        ↓
Identify Legacy
        ↓
Plan Migration
        ↓
Implement Adapter / Refactor
        ↓
Remove Legacy Path
```

---

# 7. Absolute Architecture Rule

如果出现以下情况：

```text
现有代码与新架构冲突
```

默认选择：

```text
新架构
```

但不能立即删除旧代码。

必须：

```text
Classify
 ↓
Migrate
 ↓
Verify
 ↓
Delete
```

---

# 8. Existing Code Classification

Zcode 在每个模块改造前必须将现有代码分类为四种：

```text
REUSE
REFACTOR
REPLACE
DELETE
```

---

## 8.1 REUSE

满足：

```text
接口正确
职责正确
依赖方向正确
安全模型正确
测试可复用
```

则：

```text
REUSE
```

---

## 8.2 REFACTOR

功能有价值，但架构不符合要求：

```text
REFACTOR
```

例如：

```text
旧：
Controller
 ↓
Service
 ↓
DB

新：
Controller
 ↓
Action Runtime
 ↓
Action
 ↓
Data Runtime
 ↓
DB
```

---

## 8.3 REPLACE

旧实现无法合理迁移：

```text
REPLACE
```

例如：

```text
旧 Queue
旧 EventBus
旧 Plugin Runtime
旧 Agent Runtime
```

如果与统一 Runtime 冲突，应替换。

---

## 8.4 DELETE

满足以下条件之一：

```text
重复 Runtime
无调用
死代码
过时 API
安全风险
架构冲突且无法兼容
重复业务实现
```

才能：

```text
DELETE
```

---

# 9. Mandatory Audit Before Coding

每个大模块开始之前，Zcode 必须产生：

```text
MODULE_AUDIT.md
```

至少包含：

```yaml
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

禁止：

```text
“我大概看过项目了。”
```

必须能够回答：

```text
当前入口在哪里？

谁调用它？

数据从哪里来？

谁执行副作用？

有没有绕过 Runtime？

有没有重复 Runtime？

有没有旧 API？

有没有测试？

有没有数据库依赖？

有没有 Plugin / MCP / Agent 依赖？

有没有 UI 直接调用基础设施？
```

---

# 11. No Autonomous Architecture Changes

Zcode 不允许因为实现困难而自行改变核心架构。

禁止：

```text
“Action Runtime 太复杂，所以直接 Service。”

“Queue 不方便，所以 Worker 直接执行。”

“Agent 调数据库更快。”

“MCP 自己执行一套逻辑。”

“Plugin 自己维护 EventBus。”

“UI 自己做权限。”

“Secret 直接放 config。”
```

这些都属于：

> Architecture Violation

---

# 12. Architecture Change Request

如果确实需要改变架构，必须创建：

```text
docs/architecture/ADR-XXXX-*.md
```

格式：

```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
```

然后：

```text
STOP
```

等待架构决策。

---

# 13. Do Not Continue After Architecture Block

如果某个任务依赖未经批准的架构变化：

```text
STOP IMPLEMENTATION
```

不得：

```text
先偷偷实现
之后再说
```

---

# 14. Task Decomposition

Zcode 必须将大任务拆成：

```text
P0
P1
P2
```

---

## P0

阻塞系统运行或架构正确性的内容：

```text
Core Runtime
Action Runtime
Resource Registry
Permission
Identity
Data Runtime
Task Runtime
Event Runtime
```

---

## P1

平台核心能力：

```text
Storage
Search
UI Shell
Plugin
MCP
Skill
Agent
Workflow
Notification
Observability
Versioning
```

---

## P2

扩展能力：

```text
Project Factory
Official Modules
SEO
DevOps
CRM
Content
Business Applications
```

---

# 15. Never Implement the Whole Roadmap at Once

禁止：

```text
“现在一次把 Plugin + MCP + Agent + UI + SEO 全部完成。”
```

正确方式：

```text
Core Runtime
 ↓
Vertical Slice
 ↓
Tests
 ↓
Next Runtime
 ↓
Vertical Slice
 ↓
Tests
```

---

# 16. Vertical Slice Rule

每个阶段至少完成一个真正可运行的 Vertical Slice。

例如：

```text
User
 ↓
Permission
 ↓
Resource
 ↓
Action
 ↓
Action Runtime
 ↓
Execution
 ↓
Audit
 ↓
UI
```

而不是：

```text
只写 100 个 interface
```

---

# 17. First Golden Vertical Slice

DevOS 第一条完整 Vertical Slice 应为：

```text
User
 ↓
Session
 ↓
Permission
 ↓
Resource
 ↓
Action
 ↓
Action Runtime
 ↓
Execution
 ↓
Audit
 ↓
Event
 ↓
Task
 ↓
UI
```

建议使用：

```text
core.user
```

实现：

```text
core.user.create
core.user.get
core.user.update
core.user.delete
```

---

# 18. Runtime Before UI

如果一个功能还没有 Runtime：

```text
禁止先写复杂 UI。
```

错误：

```text
UI
 ↓
fetch("/api/xxx")
 ↓
Controller
 ↓
DB
```

正确：

```text
UI
 ↓
Action Client
 ↓
Action Runtime
 ↓
Action
 ↓
Data Runtime
 ↓
DB
```

---

# 19. Unified Action Runtime

所有副作用必须最终经过：

```ts
ActionRuntime.execute(...)
```

包括：

```text
REST
GraphQL
CLI
UI
MCP
Plugin
Skill
Agent
Workflow
Scheduler
Webhook
System Job
```

---

# 20. No Duplicate Runtime

Zcode 必须主动搜索重复实现。

重点搜索：

```text
*Service
*Manager
*Executor
*Runner
*Engine
*Runtime
*Worker
*Queue
*Bus
*Scheduler
*Agent
*PluginManager
*MCP*
```

但不是所有这些名字都必须删除。

必须检查：

> 是否存在两个承担同一职责的 Runtime？

例如：

```text
packages/action-runtime/
src/services/action-executor/
src/core/executor/
```

如果三者实际上都执行 Action：

```text
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 禁止：

```ts
db.query()
redis.get()
queue.add()
fs.readFile()
secret.get()
worker.execute()
```

UI 只能：

```text
Query
Action
Task
Search
Realtime
Agent
```

---

# 23. Agent Boundary

Agent 禁止：

```ts
db.query()
redis.get()
queue.add()
fs.readFile()
process.env.SECRET
```

Agent 只能：

```text
Goal
 ↓
Capability Discovery
 ↓
Skill
 ↓
Plan
 ↓
Action / Task
```

---

# 24. Plugin Boundary

Plugin 可以定义：

```text
Resource
Action
Skill
MCP
Workflow
UI
Config
Provider
```

Plugin 不可以创建：

```text
自己的 Auth
自己的 RBAC
自己的 Action Runtime
自己的 Queue
自己的 EventBus
自己的 Secret Store
自己的 Notification Runtime
自己的 Task Runtime
自己的 Router
```

---

# 25. MCP Boundary

MCP 是：

```text
Capability Access / Transport
```

不是：

```text
Second Business Runtime
```

正确：

```text
MCP
 ↓
Capability
 ↓
Action Runtime
```

禁止：

```text
MCP
 ↓
Direct DB
```

或者：

```text
MCP
 ↓
Private Service
 ↓
Private Permission
```

---

# 26. Skill Boundary

Skill 描述：

```text
怎么解决问题
```

而不是：

```text
直接执行数据库操作
```

Skill 可以定义：

```text
requiredCapabilities
instructions
examples
workflow guidance
```

不能直接：

```text
SQL
Redis
Filesystem
Secret
```

---

# 27. Agent Must Not Persist Chain-of-Thought

禁止保存：

```text
hidden reasoning
chain of thought
private internal reasoning
```

可以保存：

```text
decision summary
plan
action
action input summary
action result summary
observation
error
reason code
```

例如：

```json
{
  "decisionSummary": "选择使用网站扫描能力检查技术 SEO",
  "capability": "seo.website.scan",
  "result": "发现 12 个高优先级问题"
}
```

---

# 28. Database Access Rule

Business code 不得随意：

```ts
prisma.user.findMany()
```

必须：

```text
Data Runtime
 ↓
Repository / Query
```

写操作：

```text
Action
 ↓
Action Runtime
 ↓
Data Runtime
```

---

# 29. Redis Rule

Redis 只能由对应 Runtime 使用。

例如：

```text
Queue Runtime
Cache Runtime
Realtime Runtime
Lock Runtime
```

业务 Plugin 不得：

```ts
redis.set(...)
```

然后自行实现状态机。

---

# 30. Secret Rule

禁止：

```ts
process.env.OPENAI_API_KEY
```

出现在业务代码中。

必须：

```text
Configuration Runtime
 ↓
Provider Runtime
 ↓
Credential Runtime
 ↓
Secret Runtime
```

---

# 31. Storage Rule

禁止：

```ts
fs.writeFile(...)
```

作为业务文件存储机制。

必须：

```text
Storage Runtime
 ↓
Storage Provider
```

Agent 工作文件同样如此。

---

# 32. Queue Rule

禁止：

```text
Plugin → Redis → 自己消费
```

必须：

```text
Task
 ↓
Job
 ↓
Queue
 ↓
Worker
 ↓
Action Runtime
```

---

# 33. Event Rule

禁止：

```text
Plugin A
 ↓
自己的 EventEmitter

Plugin B
 ↓
自己的 WebSocket

Plugin C
 ↓
自己的 PubSub
```

必须：

```text
Action
 ↓
Execution
 ↓
Event Runtime
```

---

# 34. API Rule

Controller 只能负责：

```text
HTTP parsing
validation
authentication context
response mapping
```

不能承担：

```text
business logic
transaction logic
queue logic
agent logic
database workflow
```

---

# 35. Service Rule

`Service` 不是架构层。

如果存在：

```text
UserService
SeoService
AgentService
PluginService
```

必须明确它属于：

```text
Application Service
Domain Service
Runtime Adapter
Repository
Policy
```

否则容易重新形成：

```text
God Service
```

---

# 36. Package Dependency Direction

推荐：

```text
apps
 ↓
modules
 ↓
runtime
 ↓
contracts
```

禁止：

```text
core
 ↓
business module
```

禁止：

```text
runtime
 ↓
SEO
```

禁止：

```text
Action Runtime
 ↓
Plugin UI
```

---

# 37. Recommended Package Structure

Zcode 应逐步形成：

```text
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/
```

前端：

```text
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。

例如：

```text
packages/action/
    README.md
    package.json
    src/
    tests/
```

其中：

```text
README.md
```

必须说明：

```text
Responsibility
Public API
Dependencies
Forbidden Dependencies
Integration
Tests
```

---

# 39. Forbidden Dependencies

例如：

```text
packages/action-runtime
```

不得依赖：

```text
seo
crm
content
business modules
plugin UI
agent profile
```

可以依赖：

```text
contracts
resource
permission
execution
observability
audit
```

---

# 40. Code Generation Boundary

Zcode 生成代码时必须区分：

```text
GENERATED
HANDWRITTEN
MIGRATED
```

推荐：

```text
src/generated/
src/core/
src/modules/
src/business/
```

禁止把所有代码都标记成：

```text
generated
```

否则后续无法安全升级。

---

# 41. Generated Code Rule

如果文件明确：

```text
AUTO-GENERATED
```

Zcode 不应该手工修改。

应该修改：

```text
generator
template
schema
manifest
```

然后重新生成。

---

# 42. Business Code Boundary

推荐：

```text
packages/business/
modules/
apps/
```

业务代码不得进入：

```text
packages/core/
packages/action/
packages/task/
packages/event/
```

例如：

```text
seo.website
```

应该属于：

```text
modules/seo/
```

而不是：

```text
packages/core/src/seo/
```

---

# 43. Migration Protocol

任何数据库结构变化必须：

```text
Migration
```

禁止：

```text
启动时自动 ALTER TABLE
```

禁止：

```text
代码发现字段不存在就自动创建
```

---

# 44. Database Migration Rules

使用：

```text
Prisma Migration
+
DevOS Migration Registry
```

而不是重新发明 Migration Engine。

每个 Migration：

```text
version
namespace
checksum
status
```

---

# 45. Expand / Contract

生产环境数据库变更优先：

```text
Expand
 ↓
Deploy
 ↓
Migrate Data
 ↓
Switch Read/Write
 ↓
Contract
```

不要：

```text
删除字段
 ↓
马上部署新代码
```

---

# 46. Destructive Migration

以下操作必须特别标记：

```text
DROP TABLE
DROP COLUMN
数据覆盖
数据删除
不可逆转换
```

要求：

```text
backup
impact analysis
rollback strategy
approval
```

---

# 47. Runtime Contract Tests

每个 Runtime 必须拥有 Contract Test。

例如：

```text
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

至少测试：

```text
registration
discovery
permission
scope
validation
execution
sync
async
error
timeout
cancellation
idempotency
audit
event
observability
```

---

# 49. Task Runtime Contract

至少测试：

```text
Task creation
Job creation
Queue
Worker
Lease
Heartbeat
Retry
Cancellation
Progress
Dependency
Batch
Dead Letter
Recovery
```

---

# 50. Plugin Contract

Plugin 必须测试：

```text
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

必须测试：

```text
connect
authenticate
capability discovery
schema
permission filtering
scope filtering
action execution
timeout
error mapping
audit
disconnect
```

---

# 52. Agent Contract

必须测试：

```text
goal
context
capability discovery
permission
planning
action execution
task creation
observation
replan
retry
budget
approval
completion
failure
```

---

# 53. Integration Tests

Runtime Contract Test 不够。

还必须有：

```text
Integration Tests
```

例如：

```text
User
 ↓
Action
 ↓
Task
 ↓
Job
 ↓
Worker
 ↓
Execution
 ↓
Event
 ↓
Notification
```

---

# 54. E2E Tests

核心 Vertical Slice 必须有 E2E。

至少：

```text
Login
 ↓
Create Resource
 ↓
Execute Action
 ↓
Observe Task
 ↓
Receive Event
 ↓
View Audit
```

---

# 55. CI Required Checks

推荐 CI：

```text
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

建议建立：

```text
scripts/check-architecture.ts
```

检查：

```text
business → core
UI → DB
Agent → DB
Plugin → Redis
MCP → DB
business → process.env
business → fs
duplicate runtime
forbidden dependency
```

---

# 57. Example Architecture Rules

```ts
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

每一个任务必须定义：

```yaml
changeBudget:
  files: 30
  packages: 3
  migrations: 2
  architectureChanges: 0
```

默认：

```text
architectureChanges = 0
```

如果超过：

```text
STOP
```

重新拆任务。

---

# 59. Scope Creep Prevention

如果任务是：

```text
实现 Action Runtime
```

Zcode 不应该顺手：

```text
重写 UI
重写 Agent
重写 Plugin
更换数据库
更换 ORM
重写全部 API
```

即使这些东西“顺便更好”。

---

# 60. Allowed Opportunistic Refactoring

只有以下情况可以顺手修：

```text
安全漏洞
编译错误
阻塞当前 Runtime
明显重复代码
直接违反本架构的代码
```

而且必须记录：

```text
Why
Impact
Files
Tests
```

---

# 61. Legacy Compatibility

迁移期间允许：

```text
Legacy Adapter
```

例如：

```text
OldService
 ↓
Legacy Adapter
 ↓
Action Runtime
```

但必须：

```yaml
legacy:
  owner: migration
  status: temporary
  removalTarget: "phase-X"
```

---

# 62. Legacy Code Must Have Exit Strategy

禁止永久：

```text
new architecture
+
legacy architecture
```

最终必须：

```text
Legacy
 ↓
Adapter
 ↓
Migration
 ↓
Delete
```

---

# 63. Feature Flags

大型迁移允许：

```text
legacy path
new path
```

通过：

```text
Feature Flag
```

控制。

例如：

```text
devos.actionRuntime.v2
```

迁移完成：

```text
100% new path
 ↓
remove flag
 ↓
delete old path
```

---

# 64. Rollback Strategy

每个重大任务必须说明：

```text
What can fail?
How to detect?
How to rollback?
What data changes?
Can rollback be automatic?
```

---

# 65. Code Rollback

代码问题：

```text
git revert
```

或：

```text
feature flag off
```

---

# 66. Database Rollback

不要假设：

```text
所有 migration 都能 down。
```

生产数据库优先：

```text
forward-compatible migration
+
backup
+
compensating migration
```

---

# 67. Failed Implementation Recovery

如果 Zcode 连续出现：

```text
compile failure
test failure
architecture violation
```

不得继续堆代码。

必须：

```text
STOP
 ↓
Diagnose
 ↓
Restore last known good state
 ↓
Re-plan
```

---

# 68. Three-Failure Rule

同一任务连续三次修复仍失败：

```text
STOP IMPLEMENTATION
```

输出：

```text
Failure Analysis
Root Cause
Current State
Options
Recommended Plan
```

不得无限循环。

---

# 69. Test-First for Runtime Contracts

对于核心 Runtime：

```text
Contract
 ↓
Test
 ↓
Implementation
```

优先于：

```text
Implementation
 ↓
猜测测试
```

---

# 70. Definition of Done

一个 Runtime 不允许以：

```text
“代码写完了”
```

作为完成标准。

必须：

```text
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 至少回答：

```text
谁调用？

怎么调用？

权限在哪里？

错误在哪里？

审计在哪里？

事件在哪里？

指标在哪里？

取消在哪里？

超时在哪里？

重试在哪里？

版本在哪里？

测试在哪里？
```

---

# 72. Action Definition of Done

每个 Action：

```ts
{
  id,
  version,
  description,
  inputSchema,
  outputSchema,
  permissions,
  handler,
  mode,
  timeout,
  idempotency,
  audit,
  events
}
```

必须能够：

```text
discover
authorize
execute
observe
audit
```

---

# 73. Agent Definition of Done

Agent 不只是：

```text
chat UI
```

必须：

```text
Goal
Context
Capability Discovery
Plan
Execution
Task
Observation
Replan
Budget
Approval
Audit
Result
```

---

# 74. Plugin Definition of Done

Plugin 不只是：

```text
npm package
```

而是：

```text
Manifest
 ↓
Dependency
 ↓
Resource
 ↓
Action
 ↓
Capability
 ↓
Config
 ↓
UI
 ↓
Health
 ↓
Lifecycle
```

---

# 75. Project Factory Definition of Done

Project Factory 不只是：

```text
copy template
```

必须：

```text
Requirement
 ↓
Project Type
 ↓
Capabilities
 ↓
Dependency Resolution
 ↓
Manifest
 ↓
Template
 ↓
Generate
 ↓
Validate
 ↓
Run
```

---

# 76. Zcode Working Loop

每个任务严格执行：

```text
┌───────────────┐
│ Read Docs     │
└───────┬───────┘
        ↓
┌───────────────┐
│ Audit Code    │
└───────┬───────┘
        ↓
┌───────────────┐
│ Classify      │
└───────┬───────┘
        ↓
┌───────────────┐
│ Plan          │
└───────┬───────┘
        ↓
┌───────────────┐
│ Implement     │
└───────┬───────┘
        ↓
┌───────────────┐
│ Test          │
└───────┬───────┘
        ↓
┌───────────────┐
│ Verify        │
└───────┬───────┘
        ↓
┌───────────────┐
│ Report        │
└───────┬───────┘
        ↓
     Next Slice
```

---

# 77. Required Task Plan

Zcode 开始任务时应该先产生：

```md
# 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

这是非常重要的保护机制。

如果任务是：

```text
Action Runtime
```

可以：

```text
packages/action/*
packages/execution/*
packages/permission/*
```

但：

```text
modules/seo/*
apps/business/*
```

默认：

```text
DO NOT TOUCH
```

除非确实需要集成测试。

---

# 79. Implementation Report

任务结束后必须生成：

```md
# 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

只能使用：

```text
PASS
PARTIAL
BLOCKED
FAILED
```

不能使用：

```text
almost done
mostly done
should work
looks good
```

---

# 81. Acceptance Criteria

每个任务必须有明确：

```text
AC-001
AC-002
AC-003
```

例如：

```text
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

以下行为属于失败：

```text
TODO
placeholder
mock implementation
fake success
return {}
return true
empty handler
console.log("implemented")
```

除非明确标记：

```text
prototype
stub
not production-ready
```

---

# 83. No Silent Simplification

如果需求是：

```text
retry
```

不能实现成：

```text
一次执行
```

然后说：

> “基础版本已经支持。”

如果需求是：

```text
permission
```

不能：

```text
if (user)
```

如果需求是：

```text
Agent budget
```

不能：

```text
hardcoded 100
```

---

# 84. No Fake Architecture

禁止仅创建：

```text
interfaces
folders
empty classes
```

然后声称：

```text
Runtime implemented
```

Runtime 必须能够：

```text
execute real operation
```

并通过：

```text
Contract Test
```

---

# 85. Progressive Implementation

如果完整 Runtime 太大：

```text
Phase A
Contract + minimal implementation

Phase B
Production implementation

Phase C
Advanced features
```

但必须明确状态。

例如：

```yaml
status:
  registration: complete
  execution: complete
  retry: partial
  distributed: pending
```

---

# 86. CLI Verification

核心能力应该可以通过 CLI 验证。

推荐：

```bash
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

最终：

```bash
devos doctor
```

至少检查：

```text
Database
Redis
Migrations
Runtime Registry
Action Registry
Plugin Registry
Capability Registry
Event Runtime
Task Runtime
Storage
Configuration
Secrets
Workers
```

输出：

```text
PASS
WARN
FAIL
```

---

# 88. Runtime Health

每个 Runtime 都应该支持：

```ts
interface RuntimeHealth {
  name: string;
  status: "healthy" | "degraded" | "unhealthy";
  version: string;
  dependencies: RuntimeDependencyHealth[];
}
```

---

# 89. Observability Requirement

每个 Execution 至少可以追踪：

```text
requestId
correlationId
traceId
executionId
taskId
jobId
actor
organizationId
projectId
environmentId
```

---

# 90. Version Traceability

任何执行必须能够回答：

```text
Runtime Version?
Plugin Version?
Action Version?
Skill Version?
MCP Version?
Event Version?
```

---

# 91. Security Verification

Zcode 每个阶段必须主动检查：

```text
Auth
Permission
Scope
Tenant isolation
Secret leakage
Audit
SSRF
Path traversal
XSS
Injection
Privilege escalation
```

尤其是：

```text
Plugin
MCP
Agent
Webhook
File
Storage
Provider
```

---

# 92. Performance Verification

核心 Runtime 必须考虑：

```text
latency
throughput
concurrency
memory
queue depth
database queries
N+1
external API calls
token usage
```

不要求一开始极致优化。

但是：

> 不允许架构上明显制造不可扩展路径。

---

# 93. Agent Cost Control

Agent Runtime 必须支持：

```text
maxTokens
maxIterations
maxExecutionTimeMs
maxTasks
maxMoney
maxExternalCalls
```

并记录：

```text
actual usage
```

---

# 94. Task Scaling Rule

例如：

```text
生成 100 篇文章
```

禁止：

```text
Agent
 ↓
100 次直接 Action
```

应该：

```text
Agent
 ↓
Task
 ↓
100 Jobs
 ↓
Queue
 ↓
Workers
```

---

# 95. Event Scaling Rule

禁止：

```text
同步调用所有订阅者
```

应该支持：

```text
Event
 ↓
Bus
 ↓
Handlers
```

必要时：

```text
Event
 ↓
Queue
 ↓
Handler Worker
```

---

# 96. UI Scaling Rule

禁止：

```text
一个页面加载所有数据
```

必须：

```text
Query
Pagination
Cursor
Virtualization
Lazy loading
Realtime incremental update
```

---

# 97. Search Scaling Rule

不要默认：

```text
ElasticSearch
```

一开始可以：

```text
PostgreSQL FTS
+
pgvector
```

只有确实需要时再：

```text
OpenSearch
ElasticSearch
Meilisearch
Typesense
```

---

# 98. Infrastructure Pragmatism

Zcode 不允许因为“平台架构”而无意义增加基础设施。

例如：

```text
Kafka
Kubernetes
Elasticsearch
NATS
Temporal
ClickHouse
```

都不是默认必选。

先建立：

```text
Provider Abstraction
```

再根据规模替换。

---

# 99. Prefer Mature Components

如果成熟方案已经满足需求：

```text
Prisma Migration
Redis
BullMQ / compatible queue abstraction
OpenTelemetry
Zod
React Router
TanStack Query
Ant Design
```

优先复用。

不要：

```text
重新发明 ORM
重新发明 Migration
重新发明 Queue
重新发明 Schema Validator
重新发明 Tracing
```

---

# 100. But Avoid Vendor Lock-in

复用成熟组件不意味着：

```text
业务代码直接绑定 Provider
```

应该：

```text
DevOS Runtime
 ↓
Provider Interface
 ↓
Implementation
```

---

# 101. Provider Rule

例如：

```ts
interface SearchProvider {}

interface StorageProvider {}

interface ModelProvider {}

interface QueueProvider {}

interface EventProvider {}
```

业务模块不应该直接依赖：

```text
OpenAI SDK
S3 SDK
Redis API
Elastic SDK
```

除非它是对应 Provider Implementation。

---

# 102. Plugin Installation Flow

最终必须：

```text
Plugin Package
 ↓
Manifest
 ↓
Compatibility
 ↓
Dependencies
 ↓
Migration
 ↓
Registration
 ↓
Capability Registry
 ↓
UI Registry
 ↓
Health Check
 ↓
Enabled
```

---

# 103. Plugin Removal

必须检查：

```text
running tasks
resources
data
artifacts
dependencies
actions
skills
mcp
ui
config
```

然后：

```text
disable
 ↓
drain
 ↓
migrate/archive
 ↓
unregister
 ↓
remove
```

---

# 104. Agent Capability Discovery

Zcode 实现 Agent 时必须采用：

```text
summary
 ↓
schema
 ↓
instructions
 ↓
execution
```

而不是一次将全部：

```text
Action
MCP
Plugin
Skill
```

完整 schema 发给模型。

---

# 105. Capability Ranking

至少考虑：

```text
relevance
permission
scope
availability
quality
cost
latency
risk
```

---

# 106. Human Approval

危险操作必须：

```text
requiresApproval
```

例如：

```text
delete production
deploy production
send bulk email
modify DNS
rotate critical credential
delete storage
```

Agent 不能绕过。

---

# 107. Audit Chain

Agent 操作应该形成：

```text
Human
 ↓
Agent Goal
 ↓
Agent Plan
 ↓
Action
 ↓
Execution
 ↓
Audit
```

不能只记录：

```text
Agent did something.
```

---

# 108. Correlation

跨 Runtime 必须传递：

```text
correlationId
causationId
requestId
executionId
taskId
jobId
```

例如：

```text
Agent
 ↓ correlationId
Task
 ↓ correlationId
Job
 ↓ correlationId
Execution
 ↓ correlationId
Event
 ↓ correlationId
Notification
```

---

# 109. No Context Loss

Zcode 不允许在 Runtime 之间重新创建：

```text
actor
organization
project
environment
permission
```

必须通过：

```ts
ActionContext
TaskContext
ExecutionContext
```

传递。

---

# 110. Testing Pyramid

推荐：

```text
                 E2E
                /   \
          Integration
             /       \
       Contract Tests
          /           \
        Unit Tests
```

Runtime 越底层：

```text
Unit + Contract
```

越重要。

---

# 111. Test Naming

建议：

```text
action-runtime.contract.spec.ts
task-runtime.contract.spec.ts
plugin-runtime.contract.spec.ts
agent-runtime.contract.spec.ts
```

而不是：

```text
test1.ts
test2.ts
```

---

# 112. Repository Quality

每个 package 至少：

```text
README.md
package.json
src/
tests/
```

核心 Runtime：

```text
architecture.md
contracts/
integration-tests/
```

---

# 113. Documentation Is Part of Implementation

如果 API 改变：

```text
API docs
```

必须同步。

如果 Resource 改变：

```text
Resource schema
```

必须同步。

如果 Action 改变：

```text
Action contract
```

必须同步。

---

# 114. No Stale Documentation

如果 Zcode 改了：

```text
runtime architecture
```

但文档仍写旧架构：

```text
FAIL
```

---

# 115. Git Commit Strategy

建议按 Vertical Slice 提交：

```text
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
```

不要：

```text
feat: massive devos rewrite
```

---

# 116. Small Commits

一个 Commit 应该回答：

```text
为什么？
改了什么？
如何验证？
```

---

# 117. Migration Commits

数据库迁移建议：

```text
migration
code
backfill
cleanup
```

分开。

---

# 118. Zcode Must Preserve Buildability

任何阶段结束：

```bash
bun install
bun run typecheck
bun run lint
bun run test
bun run build
```

至少必须保证：

```text
project remains buildable
```

---

# 119. Broken Main Branch Is Not Acceptable

禁止：

```text
“后面会修。”
```

如果当前任务确实必须暂时破坏：

```text
feature branch
```

并且不能合并。

---

# 120. No Massive Blind Rewrite

禁止：

```text
删除整个 src
重新生成项目
```

除非：

```text
明确架构决策
明确迁移计划
明确 rollback
```

---

# 121. Refactor Strategy

优先：

```text
Strangler Pattern
```

即：

```text
Legacy
   ↓
Adapter
   ↓
New Runtime
   ↓
New Path
   ↓
Delete Legacy
```

而不是：

```text
Big Bang Rewrite
```

---

# 122. Runtime Migration Example

旧：

```text
POST /users
 ↓
UserController
 ↓
UserService
 ↓
Prisma
```

迁移：

```text
POST /users
 ↓
UserController
 ↓
Action Runtime
 ↓
core.user.create
 ↓
Data Runtime
 ↓
Prisma
```

最后：

```text
UserService
```

删除。

---

# 123. Agent Migration Example

旧：

```text
Agent
 ↓
OpenAI
 ↓
custom tool
 ↓
custom API
```

新：

```text
Agent Runtime
 ↓
Capability Registry
 ↓
Skill
 ↓
Action
 ↓
Action Runtime
```

---

# 124. Plugin Migration Example

旧：

```text
Plugin
 ↓
PluginService
 ↓
Plugin DB
```

新：

```text
Plugin Runtime
 ↓
Manifest
 ↓
Registry
 ↓
Resource / Action / Capability
```

---

# 125. MCP Migration Example

旧：

```text
MCP Server
 ↓
business service
```

新：

```text
MCP
 ↓
MCP Adapter
 ↓
Capability
 ↓
Action Runtime
```

---

# 126. UI Migration Example

旧：

```text
React
 ↓
fetch
 ↓
business API
```

新：

```text
React
 ↓
API Client
 ↓
Action / Query
 ↓
Runtime
```

---

# 127. Required Architecture Inventory

Zcode 应维护：

```text
docs/ARCHITECTURE_INVENTORY.md
```

至少：

```text
Runtime
Package
Owner
Status
Dependencies
Public APIs
Tests
```

例如：

```md
| Runtime | Package | Status |
|---|---|---|
| Action | packages/action | DONE |
| Task | packages/task | PARTIAL |
| Event | packages/event | TODO |
```

---

# 128. Capability Inventory

维护：

```text
docs/CAPABILITY_INVENTORY.md
```

记录：

```text
Capability
Type
Provider
Permission
Action
Plugin
Skill
MCP
Status
```

这样 Agent 不会重复创建能力。

---

# 129. Duplicate Capability Prevention

新增能力前：

```text
Search Capability Registry
```

如果已有：

```text
seo.website.scan
```

禁止再创建：

```text
seo.scanWebsite
website.seoScanner
seo.auditWebsite
```

除非它们语义不同。

---

# 130. Duplicate Resource Prevention

新增：

```text
Resource
```

之前必须搜索：

```text
Resource Registry
```

避免：

```text
user
core.user
users
account.user
```

同时存在。

---

# 131. Duplicate Action Prevention

新增 Action 前：

```text
Action Registry
```

检查：

```text
name
namespace
semantic meaning
input
output
```

---

# 132. Naming Rule

统一：

```text
namespace.resource.action
```

例如：

```text
core.user.create
core.task.cancel
storage.file.upload
seo.website.scan
devops.server.deploy
```

---

# 133. Version Rule

可变 Action 使用：

```text
action@1
action@2
```

而不是偷偷改变：

```text
action
```

的语义。

---

# 134. Agent Plan Lock

Agent 产生 Plan 后：

```text
Capability Version
Action Version
Skill Version
Plugin Version
```

应该锁定。

执行过程中如果版本发生变化：

```text
detect
 ↓
replan
 ↓
record reason
```

---

# 135. Production Reproducibility

生产执行必须能够恢复：

```text
what happened
```

必须记录：

```text
Runtime Version
Plugin Version
Action Version
Skill Version
MCP Version
Config Snapshot
Environment
```

---

# 136. Config Snapshot

长时间运行 Task 推荐：

```text
Pinned Configuration
```

而不是执行到一半突然：

```text
API key
model
provider
behavior
```

全部改变。

---

# 137. No Secret in Snapshot

配置 Snapshot：

```text
secret reference
```

而不是：

```text
secret plaintext
```

---

# 138. Zcode Security Stop Conditions

遇到：

```text
secret leak
permission bypass
tenant isolation failure
arbitrary filesystem access
SSRF
RCE risk
SQL injection
unsafe plugin execution
Agent privilege escalation
```

必须：

```text
STOP
```

优先修复。

---

# 139. Production Destructive Actions

Zcode 不应该让 Agent 自动执行：

```text
production destructive migration
```

除非：

```text
explicit approval
```

---

# 140. Definition of Platform Complete

DevOS 不能因为：

```text
页面很多
```

就认为完成。

平台完成的判断是：

```text
新业务可以快速创建
```

例如：

```text
创建 CRM
```

不应该重新实现：

```text
Auth
RBAC
Organization
Task
Queue
Event
File
Search
Notification
Agent
Plugin
Settings
Audit
Observability
```

而应该：

```text
devos create crm
```

然后添加业务模块。

---

# 141. Final Project Test

最终必须验证：

```text
能否从 DevOS 创建一个全新项目？
```

例如：

```bash
devos create test-app --preset saas
```

然后：

```text
Login
Organization
Project
Resource
Action
Task
File
Search
Notification
Agent
Plugin
```

全部可以使用平台能力。

---

# 142. Zcode Master Prompt

以下内容可以直接作为：

```text
Zcode Master Prompt
```

放入：

```text
ZCODE_MASTER_PROMPT.md
```

或者每次任务开始时提供给 Zcode。

---

# 143. MASTER PROMPT

```text
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

开始任务前：

```text
[ ] 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

完成任务后：

```text
[ ] 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

如果发现：

```text
[ ] 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
```

则：

```text
ARCHITECTURE VIOLATION
```

必须修复或创建迁移计划。

---

# 147. What Zcode Must Never Do

```text
❌ 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

```text
✓ Read
✓ Audit
✓ Classify
✓ Plan
✓ Implement
✓ Test
✓ Verify
✓ Migrate
✓ Document
✓ Report
```

并且：

```text
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 最终必须将代码实现成：

```text
                         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 架构的实施者。**

它的职责不是：

```text
“我认为应该这样设计。”
```

而是：

```text
读取规范
 ↓
理解规范
 ↓
审计现状
 ↓
找出差距
 ↓
按规范实施
 ↓
测试
 ↓
验证
 ↓
报告
```

最终必须保证：

```text
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
```

而不是：

```text
Core Runtime
+
Plugin Runtime
+
Agent Runtime
+
SEO Runtime
+
MCP Runtime
+
UI Runtime
+
Old Service Runtime
+
Legacy Runtime
+
某个新模块自己的 Runtime
```

---

# 151. The Real Goal

DevOS 最终成功的标准不是：

```text
代码量增加
页面增加
API 增加
```

而是：

```text
新项目开发成本下降
新能力可以复用
插件可以安装
MCP 可以接入
Agent 可以调用
Task 可以执行
Event 可以传播
UI 可以自动生成
项目可以快速创建
旧项目可以升级
业务模块不会污染 Core
```

最终：

```text
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 的任务，就是把这个目标一步一步真正落成代码。**