Octopus 设计理念分析
从代码结构、门禁规则、契约设计和运行时行为中提炼 Octopus 的核心设计哲学。
1. 确定性优先（Determinism First）
理念
Kernel 的一切行为必须可预测、可重放、可审计。相同输入必须产生相同输出。
代码证据
冻结数据类：
# kernel/contracts/ — 全部 552 个数据类均使用 frozen=True
@dataclass(frozen=True)
class Intent:
...确定性门禁：
gate_determinism()— 验证所有契约使用frozen=Truegate_deterministic_smoke()— 确定性烟雾测试gate_curiosity_goal_determinism()— 探索信号确定性gate_self_awareness_determinism()— 自省可重现gate_cerebellum_routing_determinism()— 技能路由一致性gate_cognition_replay_consistency()— 回放可复现
确定性端口标记：
# kernel/ports/interfaces.py
class ClockPort(Protocol):
def is_deterministic_source(self) -> bool: ...
class RandomPort(Protocol):
def is_deterministic_source(self) -> bool: ...设计意义
非确定性源（时钟、随机数）通过 Port 隔离，测试时可注入确定性实现。所有业务逻辑为纯函数，不依赖外部状态。
2. 零 I/O 内核（Zero-I/O Kernel）
理念
Kernel 层绝对不执行任何 I/O 操作。文件读写、网络调用、数据库查询全部通过 Port 协议委托给外层。
代码证据
纯净门禁（gate_kernel_purity）：
# kernel/ops/gates.py — 禁止列表
BANNED_WORDS = ["system", "teams", "slack", "email", "web", "ui",
"bridge", "requests", "discord", "telegram"]
BANNED_IO = ["open(", "subprocess", "httpx", "requests.",
"urllib", "sqlite3", "os.environ"]
BANNED_FRAMEWORKS = ["fastapi", "flask", "uvicorn"]运行时无 I/O 门禁：
gate_runtime_no_io()— Runtime 引擎确定性验证gate_no_env_outside_bootstrap()— 仅facilities/可读环境变量gate_transport_no_fork()— 传输层禁止 subprocess/multiprocessing
设计意义
Kernel 可独立测试、可嵌入任何运行时、可在 WASM 等受限环境运行。所有 1612+ kernel 测试不需要网络、磁盘或数据库。
3. 契约即边界（Contracts as Boundaries）
理念
所有跨层通信使用不可变契约（frozen dataclass），契约一旦发布即冻结，通过 SHA256 哈希锁定。
代码证据
冻结锁定机制：
# scripts/update_freeze_lock.sh — 更新冻结清单
# kernel/ops/gates.py — gate_kernel_freeze_lock() 验证 SHA256冻结门禁：
gate_linkage_spec_freeze()— 连接契约不可变gate_rpc_spec_freeze()— RPC 规范不可变gate_os_store_freeze()— OS 存储契约不可变gate_wave0_foundation()— 调度、审计回放、策略引擎冻结gate_wave1_foundation()— 注册表、计划恢复、LLM 就绪冻结
语义状态契约：
# kernel/contracts/semantic_state.py
# 8 个状态域，5 种事实类型，每种有置信度范围
# observed: 0.9-1.0, derived: 0.7-0.95, inferred: 0.5-0.95,
# declared: 0.0-0.5, reconciled: 0.8-1.0设计意义
契约是系统的”宪法”，确保 kernel 升级不破坏 shared/product 层。新功能通过新增契约（加法原则），永不修改已冻结契约。
4. 端口-适配器模式（Port-Adapter Pattern）
理念
Kernel 通过 Protocol 接口（Port）定义能力需求，外层通过具体适配器（Adapter）注入实现。依赖反转。
代码证据
端口定义（Kernel 层）：
# kernel/ports/screen/interfaces.py
class ScreenPort(Protocol):
def capture_snapshot(self) -> ScreenSnapshot: ...
def execute_action(self, cmd: ActionCommand) -> ActionResult: ...
def capture_visual(self) -> bytes: ...
def is_available(self) -> bool: ...适配器实现（Shared 层）：
# server/shared/ports_impl/screen_playwright.py — Playwright 浏览器
# server/shared/ports_impl/screen_desktop/ — pyautogui/UIA 桌面
# server/shared/ports_impl/screen_mobile/ — Appium 移动端
# server/shared/ports_impl/screen_stub.py — 空实现（无 GUI 环境）必需端口注册：
# kernel/ops/gates.py — REQUIRED_PORTS（46 个）
# gate_ports_completeness() 验证全部端口已定义设计意义
同一个 ScreenPort，可以在服务器用 Playwright、在 macOS 用 pyautogui、在 Android 用 Appium、在 CI 用 stub。Kernel 完全不知道底层实现。
5. 安全治理四象限（Governance Quartet）
理念
每个 Capability 必须同时满足四个治理维度：策略(Policy)、审计(Audit)、配额(Quota)、标准化(Normalize)。
代码证据
Capability 包的 7 个必需文件：
handler.py — 执行逻辑
policy.py — 授权策略 ← 治理
audit.py — 审计记录 ← 治理
quota.py — 配额限流 ← 治理
normalizer.py — 输出标准化 ← 治理
state_mapper.py — 状态映射
manifest.json — 元数据Gate 5: Mutation Governance（写操作治理）：
# server/shared/capability_base/gate_validator.py
# 含 write/delete/mutate/deploy/execute 的操作必须：
# 1. approval_required_for 非空
# 2. risk_tier >= MEDIUM角色策略（policies.yaml）：
# roles/linux-engineer/policies.yaml
safety_contract:
hard_red_lines:
- "rm requires high-risk recognition"
low_risk_action_allowlist:
- "all non-destructive linux ops"设计意义
没有”无治理”的操作。即使是只读查询，也有策略检查和审计记录。破坏性操作需要更高级别的审批和风险标记。
6. 证据驱动（Evidence-Driven）
理念
所有执行过程必须产生可审计、可回放的证据链。不是”做了什么”，而是”能证明做了什么”。
代码证据
证据存储结构：
state/evidence/run-{id}/
├── replay.jsonl # 执行回放日志
├── manifest.json # 执行清单
└── brain_learning_report.json # 学习报告证据门禁：
gate_memory_write_audited()— 所有写操作必须有 AuditEventgate_memory_revoke_audited()— 撤销必须追踪gate_kb_ref_in_evidence()— KB 引用必须关联证据- Gate 4: Replay Readiness — 每个 Capability 必须声明
evidence_tags
EvidenceStorePort：
class EvidenceStorePort(Protocol):
def put_manifest(self, run_id: str, manifest: dict) -> None: ...
def get_manifest(self, run_id: str) -> dict | None: ...
def put_replay(self, run_id: str, events: list) -> None: ...
def get_replay(self, run_id: str) -> list: ...100+ LiveEvent 种类： kernel/ops/gates.py 第 228-400 行 — REQUIRED_LIVE_EVENT_KINDS
设计意义
每次执行都像”黑匣子”一样完整记录。可以回放任何历史操作、审计任何决策过程、追溯任何学习结论的来源。
7. 追加式记忆（Append-Only Memory）
理念
记忆只增不删，撤销通过标记（revocation）而非物理删除。
代码证据
记忆门禁：
gate_memory_append_only()— 禁止破坏性写入gate_memory_write_audited()— 每次写入产生审计事件gate_memory_revoke_audited()— 撤销有审计追踪gate_revocation_effective()— 已撤销数据不可读取gate_memory_app_isolation()— 应用间记忆隔离gate_no_cross_app_memory()— 严格的应用边界
设计意义
数据不会因 bug 或误操作永久丢失。撤销操作本身也是历史的一部分。可以审计”何时撤销了什么以及为什么”。
8. 渐进式自治（Progressive Autonomy）
理念
Agent 不是一开始就完全自主，而是通过四阶段逐步获得自治权，每一步都需要证据支撑。
代码证据
四阶段自治策略：
# roles/linux-engineer/policies.yaml
autonomy_execution:
stages:
- observe # 仅观察，不行动
- experiment # shadow 模式实验
- promote # 验证后提升
- expand # 扩展到新场景学习事件日志：
learning_events:
- DRIVE_DETECTED # 驱动信号检测
- EXPERIMENT_STARTED # 实验开始
- QUALITY_EVALUATED # 质量评估
- PLAYBOOK_GENERATED # Playbook 生成
- ROLLED_BACK # 回滚
- MODE_TIGHTENED # 收紧模式
- PROMOTED # 晋升三级安全路由（Capability Learning）：
understand → experiment → absorb
│ │ │
│ │ └── 完全吸收到生产
│ └── 沙盒中实验验证
└── 仅理解，不执行设计意义
自治不是开关，而是连续光谱。系统通过 Bayesian 信念跟踪每个能力的可靠性，只有统计上可信的能力才被提升。
9. 语义状态平面（Semantic State Plane）
理念
所有 Capability 执行结果必须映射到统一的语义状态平面，而不是留在各自的数据孤岛中。
代码证据
8 个状态域：
# kernel/contracts/semantic_state.py
domains = [
"resource", # 资源状态（服务器、容器、网络）
"artifact", # 产物状态（代码、文档、包）
"external", # 外部系统状态（API、SaaS）
"knowledge", # 知识状态（文档、KB）
"execution", # 执行状态（任务、计划）
"policy", # 策略状态（权限、配额）
"evidence", # 证据状态（审计、日志）
"intent", # 意图状态（用户目标）
]5 种事实类型及置信度：
| 类型 | 来源 | 置信度范围 |
|---|---|---|
observed | 直接观测 | 0.9 - 1.0 |
derived | 推导计算 | 0.7 - 0.95 |
inferred | LLM 推理 | 0.5 - 0.95 |
declared | 用户声明 | 0.0 - 0.5 |
reconciled | 多源协调 | 0.8 - 1.0 |
Gate 3 强制映射：
# gate_validator.py — Semantic State Outputs
# state_outputs 必须非空，前缀必须是 8 域之一
valid_prefixes = ["resource.", "artifact.", "external.", "knowledge.",
"execution.", "policy.", "evidence.", "intent."]设计意义
任何 Capability 的输出都可以被任何其他 Capability 感知和使用。系统建立了统一的”世界观”。
10. 最小基底原则（Minimal Substrate）
理念
主机只提供计算资源，所有智能能力由 Octopus 能力平面提供。主机越薄越好。
代码证据
主机文件系统标准：
# docs/host_filesystem_standard.md
Host = compute (Ubuntu + Docker + NVIDIA + Tailscale)
Octopus = capability plane (一切由 Octopus 管理)主机允许工具列表（仅 7 个）：
- Ubuntu（基础 OS）
- Docker（容器运行时）
- NVIDIA（GPU 驱动）
- Tailscale（安全网络）
- Node.js（via nvm）
- Python
- git, tmux
反模式警告：
# MEMORY.md
Anti-pattern: avoid infrastructure perfection trap
— focus on agent behaviour设计意义
不在主机上安装 AWS CLI、kubectl 等工具。所有云操作通过 Octopus Skill 容器执行。主机故障时，只需重建最小基底，Octopus 能力层自动恢复。
11. 角色驱动设计（Role-Driven Design）
理念
系统行为由”角色”定义，而非硬编码逻辑。切换角色即切换整套行为、指标、策略和界面。
代码证据
46+ 角色定义： roles/ 目录
角色成熟度光谱：
- v0.3+（完整）：linux-engineer, programmer, database-engineer, frontend-engineer
- v0.1（部分）：security-analyst, cloud-engineer, devops-engineer
- v0.1（模板）：30+ 商务/销售/运维角色
角色切换 API：
POST /api/server/switch-role → 切换活跃角色
GET /api/server/roles → 列出可用角色驱动系统（drives.yaml）：
# 每个驱动有触发器和目标
reliability:
triggers: ["service crashes", "downtime alerts"]
targets: ["reduce MTTR", "improve uptime"]设计意义
同一个 Octopus 实例，设为 linux-engineer 就是运维专家，设为 programmer 就是开发助手，设为 security-analyst 就是安全审计员。能力相同，行为模式完全不同。
12. 学习闭环（Learning Loop）
理念
系统不是静态的工具集合，而是会自主发现、学习、验证和晋升新能力的有机体。
代码证据
完整学习闭环：
发现 (Discovery)
↓ GitHub trending / npm popular / Docker official / PyPI
分类 (Classify)
↓ ResourceClassification
提取 (Extract)
↓ ExtractedCapability (7 种资产类型)
风险评估 (Risk)
↓ ExternalRiskProfile (分值/等级)
验证 (Verify)
↓ 沙盒执行
吸收 (Assimilate)
↓ shadow 模式注册
监控 (Monitor)
↓ Bayesian Beta 信念追踪
晋升/降级 (Promote/Demote)
↓ 统计阈值触发
重验证 (Reverify)
↓ 版本漂移检测 + 定期重验反馈闭环：
# DispatchRouter.outcome_sink → feedback_sink.py → Bayesian store
# 每次执行结果自动反馈到信念系统设计意义
Octopus 的能力不是固定的。它可以从 GitHub 发现新工具、学习新 API、验证新能力，并在积累足够成功记录后自动提升为正式能力。失败的能力会被自动降级或阻止。
设计理念总结
┌────────────────────────────────────────────────┐
│ Octopus 设计宪法 │
│ │
│ 1. 确定性优先 — 可预测、可重放 │
│ 2. 零 I/O 内核 — 纯逻辑、无副作用 │
│ 3. 契约即边界 — 不可变、SHA256 锁定 │
│ 4. 端口-适配器 — 依赖反转、可替换 │
│ 5. 治理四象限 — 策略/审计/配额/标准化 │
│ 6. 证据驱动 — 一切可审计、可回放 │
│ 7. 追加式记忆 — 只增不删、撤销不物理删除 │
│ 8. 渐进式自治 — 四阶段递进、信念驱动 │
│ 9. 语义状态 — 8 域统一世界观 │
│ 10. 最小基底 — 主机薄、能力平面厚 │
│ 11. 角色驱动 — 行为由角色定义 │
│ 12. 学习闭环 — 自主发现-学习-验证-晋升 │
└────────────────────────────────────────────────┘