系统架构

┌─────────────────────────────────────────────────────────────────────┐
│  用户端（飞书 / 钉钉 / 企微 / Discord / Telegram / Slack / 前端 UI） │
└─────────────┬───────────────────────────────────┬───────────────────┘
              │ 即时通讯 WebSocket / Webhook        │ WebSocket (RPC)
              ▼                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Go Gateway（主进程）                               │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐    │
│  │ 渠道插件管理  │  │  RPC 路由层   │  │  WebSocket Broadcaster  │    │
│  │ channels.Mgr │  │  (50+ 方法组) │  │  事件广播 → 前端/渠道   │    │
│  └──────┬───────┘  └──────┬───────┘  └────────────────────────┘    │
│         │                 │                                          │
│  ┌──────▼─────────────────▼────────────────────────────────────┐   │
│  │                    GatewayState（中央状态）                   │   │
│  │  ChatRunState │ EscalationMgr │ ToolRegistry │ TaskPresetMgr │   │
│  │  NodeEventDispatcher │ Broadcaster │ ChannelMgr              │   │
│  └─────────────────────────────────────────────────────────────┘   │
│         │                                                            │
│  ┌──────▼──────────────────────────────────────────────────────┐   │
│  │              Agent 运行时（EmbeddedAttemptRunner）            │   │
│  │  buildSystemPrompt → LLM API 流式调用 → 工具循环（最多30轮）  │   │
│  │  ┌──────────────────────────────────────────────────────┐   │   │
│  │  │                   工具执行层（tool_executor.go）       │   │   │
│  │  │  bash │ read │ write │ search │ glob │ lookup_skill   │   │   │
│  │  │  web_fetch │ web_search │ memory_* │ sessions_*       │   │   │
│  │  │  browser(14 action) │ canvas │ cron │ image │ tts │ nodes │   │   │
│  │  │  argus_* │ remote_* │ spawn_coder_agent               │   │   │
│  │  └──────────────────────────────────────────────────────┘   │   │
│  └─────────────────────────────────────────────────────────────┘   │
│         │            │            │            │                     │
│  ┌──────▼───┐  ┌─────▼─────┐  ┌──▼──────┐  ┌─▼───────────────┐   │
│  │ 原生沙箱  │  │ 太虚永忆  │  │ Argus   │  │  委托合约系统   │   │
│  │ (Rust)   │  │  记忆系统  │  │ 视觉AI  │  │ DelegationCtrl │   │
│  └──────────┘  └───────────┘  └─────────┘  └─────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
              │ 原生 IPC（JSON-Lines）
              ▼
┌─────────────────────────┐    ┌─────────────────────────┐
│  oa-sandbox（Rust）      │    │  oa-coder（Rust MCP）   │
│  4 平台原生 OS 隔离       │    │  编程子智能体            │
│  + 持久化 Worker          │    │  JSON-RPC 2.0 stdio     │
└─────────────────────────┘    └─────────────────────────┘

1. Broadcaster + EscalationManager + ToolRegistry 等核心组件
2. 沙箱初始化：
   优先：oa-sandbox Rust 二进制 → NativeSandboxBridge.Start()
   兜底：Docker 可用 → ContainerPool + Worker + ProgressHub
   两者均不可用 → 无沙箱（记录警告）
3. Argus 视觉子智能体：
   a. resolveArgusBinaryPath()（4 级优先级：$ARGUS_BINARY_PATH > .app bundle > ~/.crabclaw/bin > PATH 查找）
   b. IsAvailable()（存在性 + 可执行权限 + 非目录检查）
   c. EnsureCodeSigned()（macOS 裸二进制自动签名）
   d. TCC 权限预检（macOS: Screen Recording + Accessibility + Sequoia 月度过期检测）
   e. bridge.Start()（MCP 握手 5s 超时，失败保留 bridge 允许 UI 重试）
   f. 启动失败 → 广播 argus.status.changed 事件（含 phase/reason/recovery）
4. 命令审批门控（CoderConfirmationManager，无条件初始化）
5. EscalationManager.RestoreFromDisk()（恢复未过期 pending 审批）
6. 太虚永忆记忆系统（配置启用则初始化）
7. 合约 VFS 持久化（UHMS VFS 可用则初始化 contractStore + TTL 清理 goroutine）
8. 浏览器控制器（CDP URL 配置存在则创建 PlaywrightBrowserController，支持 14 种 action + ARIA snapshot + AI Browse 循环）
9. 媒体发送器（ChannelMgr 存在则创建 mediaSenderAdapter → send_media 工具可用）

Phase 0: connect.challenge（发 nonce）
Phase 1: 等待 connect 帧（握手超时 30s，支持传统/UI req 两种格式）
Phase 1.5: nonce 验证（设备认证）
Phase 2: 认证（Token/Password + 设备签名校验）
Phase 3: hello-ok（返回协议版本、方法列表、策略）
Phase 4: 注册到 Broadcaster（WsClient 实例）
Phase 5: 请求-响应循环 + ping 保活

1. 初始化 GatewayState（boot.go）
2. 注册 50+ RPC 方法 + HTTP 路由（/v1/chat/completions, /v1/responses, /ws）
3. 启动 HTTP 监听（goroutine + listenErrCh channel）
4. select 等待: 500ms 超时 = 正常 | listenErrCh 错误 = return error
5. SetPhase(BootPhaseReady)

                        ┌─ chat.send ──────────┐
                        │  agent RPC ──────────┤   buildChatProgressCallback()
6 条入站路径:            │  openai (non-stream) ─┤     → Broadcaster.Broadcast("chat.progress", ...)
                        │  openai (stream) ─────┤     → 8 秒节流 + 指纹去重
                        │  openresponses (non) ─┤
                        └─ openresponses (sse) ─┘

远程频道路径:             buildRemoteProgressCallback()
(飞书/Discord 等)          → ChannelMgr.SendMessage() 粗粒度文本

RunEmbeddedAgent()                    ← gateway/server.go 调用
  └─ runAttempt()                     ← run.go / attempt_runner.go
       ├─ 1. 加载历史消息
       ├─ 2. 检测会话状态
       ├─ 3. classifyIntent(prompt)    ← intent_router.go（六级意图分类）
       │
       ├─ 4. buildSystemPrompt(tier)   ← prompt/prompt.go
       │   ├─ 工具说明 + 安全规则
       │   ├─ 技能索引 <available_skills>
       │   ├─ 沙箱信息
       │   ├─ 委托合约段（子智能体）
       │   ├─ 太虚永忆记忆简报（L0 ~200 tokens）
       │   └─ IntentGuidance（意图行为指引，按 tier 动态注入）
       │
       ├─ 5. trimHistoryByIntent()     ← 按意图裁剪历史
       ├─ 6. filterToolsByIntent()     ← 按意图过滤工具（3-全量）
       │
       ├─ 太虚永忆压缩（超阈值时）    ← uhms.CompressChatMessages()
       │
       ├─ LLM 流式调用               ← llmclient/
       │   └─ 处理各 Provider 差异（Anthropic/OpenAI/Gemini/Ollama 等）
       │
       ├─ 工具循环（最多 30 轮）      ← tool_executor.go
       │   ├─ 工具分发 + 执行
       │   ├─ 写操作检测（looksLikeBashWrite — NativeSandbox 路径）
       │   ├─ 连续全拒绝保护（3 轮上限）
       │   ├─ 三层死循环防护:
       │   │   ├─ L1: 同工具连续熔断（连续 5 次 → 终止 + 警告）
       │   │   ├─ L2: per-tool 失败计数（累计 3 次 → 注入可操作修复指导，isToolSoftError 检测软错误）
       │   │   └─ L3: 全局失败预算（净失败数 ≥ 8 → 终止循环，成功 -1 / 失败 +1 / 下限 0）
       │   └─ 结果注入消息流
       │
       └─ 太虚永忆提交               ← uhms.CommitChatSession()

[System_Context]      ← 状态机（COLD/WARM/NORMAL）+ 时间 + Boot Brief
[身份行]              ← Crab Claw品牌 + 能力简述
[交互路由]            ← Protocol A/B/C 状态机路由
[运行准则]            ← 语言/行动/诚信/客观/范围/Emoji 规则
[任务执行]            ← 阻塞条件 + 推断优先 + 不问许可式问题
[工具说明段]          ← 可用工具列表 + 调用格式规范
[工具调用风格]        ← 静默调用 + 叙述场景
[委派指引段]          ← spawn_coder_agent 结果处理协议（仅 spawn_coder_agent 可用时注入）
[三级指挥段]          ← 站长角色 + 流程 + 规则（仅 PlanConfirmationEnabled 时注入）
[安全规则段]          ← exec approval / escalation 引导
[技能段]              ← <available_skills> 索引（按需 lookup_skill）
[记忆段]              ← 太虚永忆 L0 简报 + 相关记忆片段
[工作区段]            ← workspace 路径 + 沙箱状态
[渠道段]              ← 渠道特定指令（飞书/Discord/Telegram 等）
[意图行为指引段]      ← IntentGuidance（按 classifyIntent 结果动态注入）
[Context Files]       ← SOUL.md + 用户注入文件
[自定义追加]          ← agents.defaults.systemPrompt 用户配置

用户输入 → classifyIntent(task_write) → needsPlanConfirmation(true)
→ PlanConfirmation.RequestPlanConfirmation() [阻塞, 独立 context]
→ approve → LLM tool calls → spawn_coder_agent / spawn_argus_agent
→ SpawnSubagent() → 子智能体执行 → outcome
→ ReviewSubagentResult() [规则预检 + 可选 LLM 审核]
→ 通过 → ResultApprovalMgr.RequestResultApproval() [阻塞, 独立 context]
→ approve → contract.Status=Completed → formatSpawnResult() → 返回主智能体

意图分类 (classifyIntent)
  ├──▶ 工具树 (filterToolsByIntent)    — 按 tier 过滤可用工具
  ├──▶ 技能树 (tierToolAllowlist)      — 静态工具-技能绑定白名单
  ├──▶ 安全层 (command_rule_presets)   — rm→ask, find~→deny 规则叠加
  ├──▶ 提示词 (intentGuidanceText)     — 按 tier 注入行为指引
  └──▶ 历史 (trimHistoryByIntent)      — 按 tier 裁剪消息量

前端 {text, attachments[]}
  → processAttachmentsForChat()    # 4 类型处理 + STT/DocConv 文本增强
  → MsgContext.Attachments         # []session.ContentBlock
  → FollowupRun → AttemptParams   # 管线穿透（7 个接线点）
  → RunAttempt:
      ├─ image 附件 → LLM 多模态 ContentBlock 注入
      └─ defer persistToTranscript → JSONL（text + 附件 blocks）

cli-rust/crates/oa-sandbox/
├── lib.rs              ← 公开接口
├── config.rs           ← SandboxConfig（安全级别/网络/文件权限）
├── output.rs           ← SandboxOutput（stdout/stderr/exitCode/timeout）
├── platform.rs         ← 平台 Runner 分发
├── error.rs            ← 错误类型
├── macos/
│   ├── ffi.rs          ← sandbox_init() FFI 绑定
│   └── seatbelt.rs     ← Apple Seatbelt SBPL profile 生成 + 执行
├── linux/
│   ├── landlock.rs     ← Landlock LSM 文件访问控制
│   ├── seccomp.rs      ← Seccomp-BPF 系统调用过滤
│   ├── namespace.rs    ← User/Network/Mount namespace 隔离
│   └── cgroup.rs       ← Cgroup v2 资源限制
├── windows/
│   ├── job.rs          ← Job Object（进程组限制）
│   ├── token.rs        ← Token 权限降级
│   ├── acl.rs          ← ACL 文件权限
│   └── appcontainer.rs ← AppContainer 低完整性沙箱
├── docker/             ← Docker Fallback Runner
└── worker/             ← 持久化 Worker（JSON-Lines 协议）
    ├── mod.rs          ← Worker 事件循环
    ├── protocol.rs     ← JSON-Lines IPC 协议定义
    ├── handle.rs       ← Worker 进程 Handle（SIGKILL on Drop）
    └── launcher.rs     ← Worker 启动器

Go Gateway ──JSON-Lines──▶ Rust Worker 进程
                            ├── 事件循环（状态机）
                            ├── 健康心跳监控（30s 间隔 ping）
                            └── 崩溃自动恢复（exponential backoff, 最多 5 次）

Go 侧（sandbox/native_bridge.go，~700 行）：
  ├── NativeSandboxBridge: 状态机 Init → Starting → Ready → Degraded → Stopped
  ├── readLocked 同步（F-01 修复）
  ├── read_line_limited 防 OOM（F-07 修复）
  └── try_wait 轮询超时（非 SIGKILL 竞争）

NativeSandboxRouter.ExecuteSandboxed(securityLevel)
  ├── L1 (allowlist) → 持久 Worker IPC（l1Bridge.Execute，<1ms）
  ├── L2 (sandboxed) → 一次性 `sandbox run` CLI（executeOneShot，~50ms）
  │                     支持 --mount host:sandbox:mode（临时挂载）
  └── L3 (full) → 不经过此路由（SandboxMode=false，上层直接 spawn）

Launcher 路径（Rust launcher.rs）:
  └── pre_exec 沙箱（Seatbelt/Landlock）→ 设 OA_SANDBOX_APPLIED=1

Go bridge 路径（Go 直接 spawn worker-start）:
  └── Worker 检测无 OA_SANDBOX_APPLIED → apply_sandbox_to_self()
      （不可逆，子进程自动继承沙箱约束）

cli-rust/crates/oa-coder/（2,394 LOC）
  └── Rust MCP Server（JSON-RPC 2.0 via stdio）
       ├── edit     — 9 层模糊匹配算法（精确→归一化→Levenshtein→...）
       ├── read     — 文件读取（二进制前 8192 字节检测）
       ├── write    — 原子写入（tempfile + rename）
       ├── grep     — ripgrep 封装，MAX_LEVENSHTEIN_INPUT=10,000 防 DoS
       ├── glob     — globset 文件模式匹配
       └── bash     — 调用 oa-sandbox 隔离执行

cli-rust/crates/oa-cmd-coder/（44 LOC）
  └── CLI 入口（oa-coder 二进制）

用户请求代码任务
    ↓
Agent 调用 spawn_coder_agent 工具
    ↓ (spawn_coder_agent.go)
创建 DelegationContract（scope/constraints/timeout）
    ↓ 合约写入 VFS active/（contract_persistence.go）
    ↓ (SpawnSubagentFunc 回调)
启动独立 LLM Session（RunEmbeddedPiAgent）
    ↓
子 Agent 获得委托合约约束的工具集（oa-coder 6 工具）
    ↓ 合约审批路由: 低风险自动放行，高风险询问用户（ApprovalRouter）
    ↓
执行代码任务 → ThoughtResult 返回父 Agent
    ↓ (subagent_announce.go:209-247)
解析 ThoughtResult + 状态广播
    ↓ 合约状态转换: completed/ | suspended/ | failed/

spawn_coder_agent → 子 Agent 返回 needs_auth
    ↓
合约转入 VFS suspended/（保存 ThoughtResult 到 l2）
    ↓
主 Agent 收到结构化可操作指引（scope 扩展/约束放宽/parent_contract 提示）
    ↓ prompt 委托引导段（buildDelegationGuidanceSection）
    ↓ LOW 风险: 直接重新委托 | HIGH 风险: 询问用户
二次 spawn_coder_agent（parent_contract="{uuid}"）
    ↓ 加载父合约 ThoughtResult → 恢复上下文注入子 Agent 系统提示
    ↓
子 Agent 续接任务（不重做已完成工作）
    ↓
硬上限: 最多 3 轮协商（iterationIndex > 3 → 拒绝 spawn，升级到用户）

配置类型: types.OpenCoderSettings（pkg/types/types_crabclaw.go）
存储路径: subAgents.openCoder.*（crabclaw.json）

三级 fallback（resolveOpenCoderConfig, server.go）:
  Level 1: subAgents.openCoder.* 显式配置（最高优先级）
  Level 2: agents.defaults.model.primary（主 agent 配置）
  Level 3: 硬编码 anthropic / claude-sonnet-4（默认值）

API Key 注入: SpawnSubagent 回调浅拷贝 Config → 覆盖目标 provider 配置
配置向导: wizard_open_coder.go（3 步: Provider → API Key/BaseURL → Model）
前端入口: SubAgents tab → open-coder 卡片 → "配置 open-coder" 按钮 → wizard overlay

backend/internal/memory/uhms/
├── manager.go          ← DefaultManager（压缩/存储/检索/VFS 编排，~1100 LOC）
├── config.go           ← UHMSConfig（向量模式/VFS路径/压缩阈值）
├── compression_prompts.go ← 13 个压缩 prompt 常量
├── claude_integration.go  ← Anthropic Compaction API + Provider 感知
├── session_committer.go   ← 会话提交管线
├── store.go            ← SQLite + FTS5 持久化
├── vfs.go              ← L0/L1/L2 三级 VFS 文件系统
├── cache.go            ← LRU 内存缓存
├── dedup.go            ← FTS5 去重
├── decay.go            ← FSRS-6 记忆衰减算法
└── interfaces.go       ← LLMProvider / VectorIndex / EmbeddingProvider 接口

消息流入（超 token 阈值）
    ↓
Observation Masking（遮蔽旧 tool_result，减少噪音）
    ↓
分割：旧消息段 | 保留最近 N 条
    ↓
Anchored Iterative Summary（锚定关键节点迭代摘要）
    ↓
摘要注入回消息流（替换旧消息段）
    ↓
压缩率：60-80% token 节省

backend/internal/memory/
├── vectoradapter/（~760 LOC，CGO FFI + 纯 Go fallback）
├── embeddings_*.go     ← OpenAI / Gemini / Voyage / 本地嵌入
└── hybrid.go           ← 混合检索（FTS5 + 向量）

向量后端：Qdrant（生产）/ sqlite-vec（嵌入式）/ builtin（纯 Go）/ 混合

// delegation_contract.go

DelegationContract {
    ContractID     string          // UUID
    ParentContract string          // 父合约 ID（协商链追踪）
    AgentID        string          // 子 Agent 标识
    Status         ContractStatus  // pending/active/suspended/completed/failed/cancelled
    TaskBrief      string          // 任务摘要
    Scope          ContractScope   // 允许操作的路径/工具白名单
    Constraints ContractConstraints {
        SandboxRequired  bool     // 强制沙箱
        NoNetwork        bool     // 禁止网络（→ Docker --network=none）
        NoSpawn          bool     // 禁止再次生成子智能体
        MaxDepth         int      // 委托链最大深度
        AllowedCommands  []string // bash 白名单（审批路由用）
    }
    Budget     *ResourceBudget     // 资源预算（可选）
    TimeoutMs  int64               // 合约超时（ms）
    IssuedAt   time.Time
}

ResourceBudget {
    MaxBashCalls  uint32  // bash 调用上限
    UsedBashCalls uint32  // 已使用（atomic 递增）
    MaxTimeMs     uint64  // 时间预算（ms）
    UsedTimeMs    uint64  // 已用时间（atomic 读取）
}

CapabilitySet {
    AllowWrite       bool
    AllowExec        bool
    AllowNetwork     bool
    MaxSecurityLevel string  // "deny" < "allowlist" < "sandboxed"
    ScopePaths       []string
}

父 Agent CapabilitySet
    ↓ ValidateMonotonicDecay()（5 维检查: write/exec/network/security/scope）
子 Agent CapabilitySet（只能 ≤ 父级）

违规示例：
  parent.AllowNetwork=false → child.AllowNetwork=true → VIOLATION
  parent.MaxLevel="allowlist" → child.MaxLevel="sandboxed" → VIOLATION
  parent.ScopePaths=[src/] → child.ScopePaths=[] (全局) → VIOLATION

合约 NoNetwork=true
    ↓ deriveMaxSecurityLevel()
→ securityLevel="allowlist"（宿主机模式无法网络隔离，强制降级）
    ↓ ApplyConstraints()（delegation_contract.go L448-454）
→ params.AllowNetwork=false
→ params.BrowserController=nil（禁用 browser 工具）
→ params.MediaSender=nil（禁用 send_media 工具）
→ params.MountRequests=nil（受限合约不应扩展文件系统）
    ↓ executeBashNativeSandbox() / executeBashSandboxed()
→ SandboxExecOptions.SecurityLevel="allowlist" → NativeSandboxRouter → L1 Worker IPC
→ cfg.NetworkEnabled=false（Docker 路径）
    ↓ DockerRunner.buildDockerArgs()（Docker fallback）
→ docker run --network=none ✅

VFS 路径: _system/contracts/{status}/{contractID}/
  l0 = 任务摘要（≤80字符，搜索索引）
  l1 = 合约 JSON（DelegationContract 完整序列化）
  l2 = ThoughtResult JSON（挂起时保存，恢复时读取）
  meta = {status, issuedBy, issuedAt, parentContract, updatedAt}

ContractPersistence 接口（runner 包，解耦 VFS 实现）:
  SaveContract / LoadContract / TransitionStatus / ListContracts / CleanupCompleted

VFSContractPersistence 适配器（gateway 包）:
  基于 uhms.LocalVFS 的 WriteSystemEntry/ReadSystemL1/DeleteSystemEntry

状态机（合法转换）:
  pending → active
  active → suspended / completed / failed
  suspended → active / cancelled
  （其他转换均非法）

TTL 清理: 每小时自动清理 >24h 的 completed 合约
  可取消 goroutine（contractCleanupDone channel → Close() 时关闭）

RPC 查询: contract.list / contract.get / contract.audit（server_methods_contracts.go）

子 Agent 返回 needs_auth → ThoughtResult 包含:
  auth_request.reason       需要权限的原因
  auth_request.risk_level   风险等级
  auth_request.scope_needed 请求扩展的路径/工具
  resume_hint               恢复提示（已完成的步骤）
  iteration_count           当前迭代轮数

主 Agent 收到结构化指引 → prompt 委托引导段引导决策:
  LOW 风险  → 直接重新委托（扩大 scope，设 parent_contract）
  HIGH 风险 → 先询问用户

恢复流程:
  二次 spawn_coder_agent(parent_contract=uuid)
    → LoadContract(uuid) 读取父合约 ThoughtResult
    → ResumeContext + IterationIndex 注入子 Agent 系统提示
    → 子 Agent 续接任务（不重做已完成工作）

硬上限: iterationIndex > 3 → 拒绝 spawn，升级到用户

ApprovalRouter: 规则评估（非 LLM 调用，零延迟）
  合约存在时 → RequestConfirmation 前置路由
  合约不存在时 → 退化到现有用户审批流程（向后兼容）

风险评估矩阵:
  read/grep/glob/find/ls     → auto_approved（只读操作）
  edit 在 ScopePaths 内       → auto_approved
  edit 在 ScopePaths 外       → ask_user
  write                      → ask_user
  bash 在 AllowedCommands 内  → auto_approved
  bash 不在白名单             → ask_user
  argus_*                    → 跳过（独立 actionRiskMap 审批）

命令白名单匹配（安全强化）:
  - 精确匹配或 "allowed " 前缀（要求词边界分隔）
  - 预扫描拒绝 shell 操作符（&&, ||, ;, |, $(), `, \n）
  - 防止 "git && rm -rf /" 绕过 "git" 白名单

审计链路:
  每个审批决策记录 ApprovalAuditEntry（时间戳/工具/决策/原因/风险级别）
  合约完成时 FlushAudit → VFS 或 contract.audit RPC 查询

线程安全:
  RequestConfirmation 锁下快照 activeContract（防并发 ClearActiveContract 竞争）
  SetActiveContract/ClearActiveContract 通过 mu 互斥

Agent Contracts 论文 (arXiv:2601.08815): child_budget ≤ parent_remaining

ResourceBudget:
  MaxBashCalls / UsedBashCalls（atomic uint32）
  MaxTimeMs / UsedTimeMs（atomic uint64）
  IsExhausted() → (true, reason) 表示预算耗尽

执行守恒:
  tool_executor.go bash handler → budget.IsExhausted() 检查
    → 耗尽: 返回 "[bash] Resource budget exhausted: {reason}"
    → 未耗尽: budget.IncrementBashCalls() 原子递增

RPC 仪表盘:
  contract.list — 按状态过滤（白名单验证），limit 限制
  contract.get  — 完整合约 + ThoughtResult
  contract.audit — 审批审计日志

L0：拒绝执行
L1：受限执行，按 allowlist / ask 规则决定是否需要确认
L2：沙箱内执行默认放行；仅工作区外挂载走 `mount_access` 审批，按任务自动回收
L3：永久授权，开启后不再进入审批链

持久化：pending EscalationRequest 落盘 → RestoreFromDisk（跨重启恢复）
前端：escalation-status-panel.ts + escalation-popup.ts + escalation-audit-log.ts
飞书卡片：审批请求以互动卡片形式推送，按钮点击触发 grant/deny RPC

backend/internal/channels/
├── registry.go         ← 渠道插件注册表
├── channels.go         ← 频道接口定义
└── {渠道}/
    ├── feishu/         ← 飞书（WebSocket 长连接）
    ├── dingtalk/       ← 钉钉
    ├── wecom/          ← 企业微信
    ├── discord/        ← Discord
    ├── telegram/       ← Telegram
    ├── slack/          ← Slack
    ├── whatsapp/       ← WhatsApp
    ├── signal/         ← Signal
    ├── imessage/       ← iMessage
    └── line/           ← Line

backend/internal/channels/feishu/
├── client.go           ← FeishuClient（larkws SDK 封装）
├── plugin.go           ← 渠道插件实现 + 事件注册
└── sender.go           ← 消息/卡片/图片发送封装

larkws → OnP2MessageReceiveV1 → feishuDispatch → Agent.Run()
                                               ↘ 广播到其他渠道

EscalationMgr 生成审批请求
    ↓ broadcastCard(token, card, 去重后的 chat_id 集合优先；全部失败再回退 open_id)
发送互动卡片（含 Allow/Deny 按钮）
    ↓ 用户点击
OnP2CardActionTrigger（同一 WS 连接）
    ↓ 解析 card value = {action, id, ttl}
escalation.grant RPC → EscalationMgr.Grant()
    ↓ 广播 escalation.grant.created 事件

CoderConfirmationManager 生成审批请求
    ↓ boot.go 回调获取 LastKnownUserID
    ↓ NotifyCoderConfirm(CoderConfirmCardRequest{OriginatorChatID, OriginatorUserID})
    ↓ SendCoderConfirmRequest → broadcastCard(token, card, 去重后的 chat_id 集合优先；全部失败再回退 open_id)
发送黄色操作确认卡片（含 批准/拒绝 按钮）
    ↓ 用户点击
OnP2CardActionTrigger → value.type="coder_confirm"
    ↓ coder.confirm.grant/deny RPC

// 示例：飞书注册流程
feishuPlugin := feishu.NewPlugin(cfg, state.Broadcaster())
state.ChannelMgr().Register("feishu", feishuPlugin)
feishuPlugin.Start(ctx) // 建立 WebSocket 长连接

type CapabilitySpec struct {
    ID            string   // 唯一标识 "bash", "web_search"
    Kind          string   // "tool" | "sub-agent-entry"
    ToolName      string   // AI 调用时的工具名
    ToolGroups    []string // 所属组 ["group:runtime"]
    RuntimeOwner  string   // "attempt_runner" | "gateway"
    EnabledWhen   string   // 启用条件
    PromptSummary string   // prompt 中的一行描述
    SkillBindable bool     // 技能文档能否绑定此工具
}

LoadSkillEntries()
  1. {workspace}/.agent/skills/     ← Agent 专属（最高优先级）
  2. bundledDir（二进制同级 skills/）← 生产包捆绑
  3. extraDirs（config 配置）        ← 额外目录
  4. docs/skills/ 自动扫描          ← monorepo 开发环境主要来源
     └── 扫描 tools/(47) / providers/(19) / general/(9) / official/(16) / media/(3)

deduplicateEntries()               ← 同名技能保留首次加载者

SKILL.md tools: web_search
    ↓ LookupByToolName("web_search")
    ↓ spec != nil && spec.SkillBindable == true → 绑定生效
    ↓ spec == nil → warn "unknown tool"，跳过
    ↓ SkillBindable == false → warn "non-bindable"，跳过

技能条目（SkillEntry）
    ↓ generateSkillL0/L1/L2()
L0 摘要（name + description + tags，~100 tokens）
L1 概览（SKILL.md 前 8000 字符，~2K tokens）
L2 完整（全文）
    ↓ vfs.WriteSystemEntry("skills", category, name, L0, L1, L2, meta)
VFS: _system/skills/{category}/{name}/
    ↓ vectorIndex.Upsert（零向量，payload-only）
Qdrant: sys_skills collection（content_hash 增量去重）

// prompt_sections.go:buildSkillsSectionFull()
"## Skills (mandatory)\n" +
"Before replying: scan <available_skills>...\n" +
"- 精确匹配一个技能 → lookup_skill(name) → 遵循指令\n" +
"- 多个候选 → 选最具体的 → lookup_skill\n" +
"- 无匹配 → 不查询\n" +
"<available_skills>\n- name: description（≤80字符）\n</available_skills>"

用户操作（点击安装/筛选/搜索）
    ↓
前端控制器 → Gateway RPC (packages.*)
    ↓
Gateway → PackageCatalog.Browse() / PackageInstaller.Install()
    ↓
响应 → 前端乐观更新 isInstalled 状态

Argus/（独立子项目，C++/Rust 混合）
  ├── rust-core/         ← 核心逻辑（Rust）
  ├── build/Argus.app/   ← macOS App Bundle（本地运行）
  └── MCP Bridge（IPC）

Gateway 侧（backend/internal/argus/）：
  ├── bridge.go          ← ArgusBridge（进程管理 + MCP 工具代理 + ResolveBinary + CheckBinary + ArgusStartError）
  ├── config.go          ← BridgeConfig（路径/超时/状态回调）
  ├── available.go       ← IsAvailable()（含可执行权限+目录排除检查）+ EnsureCodeSigned()
  ├── tcc_darwin.go      ← macOS TCC 权限预检（Screen Recording + Accessibility + Sequoia 月度过期）
  └── tcc_other.go       ← 非 macOS TCC 存根（总返回 granted）

Runner 侧（Phase 5 — 完全子智能体化）：
  ├── spawn_argus_agent.go   ← spawn_argus_agent 工具定义 + 执行器
  ├── announce_argus.go      ← 灵瞳专用系统提示词构建
  └── （复用 delegation_contract / quality_review / agent_channel）

subAgents:
  screenObserver:
    provider: "anthropic"      # LLM provider
    model: "claude-sonnet-4"   # 灵瞳独立模型
    apiKey: "sk-..."           # 独立 API key（自动脱敏）
    baseUrl: ""                # OpenAI 兼容端点
    # 以下为传统视觉观测器配置（非 LLM）
    enabled: true
    intervalMs: 1000
    changeThreshold: 0.02

第一层：OS 原生隔离（oa-sandbox）
  └── Seatbelt / Landlock+Seccomp / AppContainer / Docker

第二层：委托合约（DelegationContract）
  └── 能力单调衰减 + NoNetwork 强制 + 路径 scope + 资源预算守恒

第三层：合约审批路由（ApprovalRouter）
  └── 规则评估（非 LLM）：合约内低风险自动放行，高风险路由到用户
  └── 命令白名单词边界匹配 + shell 操作符预扫描（防注入绕过）
  └── 审批审计链路（contract.audit RPC 查询）

第四层：Exec Approvals（exec_approvals）
  └── 宿主机命令执行必须明确授权，记录审计链路

第五层：Escalation（L0-L3 四级权限）
  └── 多 active grants + task-scoped 挂载 + pending 落盘恢复 + 审计日志

第六层：SSRF 防护（security/ssrf.go）
  └── validateMediaURL + 内网地址过滤

第七层：命令审批门控（CoderConfirmationManager）
  └── Ask 规则 fail-closed：无审批则阻塞（60s 超时自动 deny）

第八层：命令规则预设（command_rule_presets）
  └── find ~ → deny, find / → deny, rm → ask, rmdir → ask, gateway start/stop/restart → ask

第九层：Bash 写操作检测（looksLikeBashWrite）
  └── NativeSandbox 路径的 redirect/tee/sed -i 检测 → CoderConfirmation 审批

ui/src/ui/
├── app.ts                  ← 根组件（@state 响应式状态）
├── app-view-state.ts       ← AppViewState 类型
├── app-gateway.ts          ← WebSocket RPC 客户端 + 事件分发
├── app-render.ts           ← 主视图渲染
├── app-render.helpers.ts   ← 渲染辅助函数
├── app-settings.ts         ← 设置面板
├── navigation.ts           ← 路由导航
├── storage.ts              ← 本地持久化
├── chat/
│   ├── grouped-render.ts   ← 消息分组渲染
│   ├── agent-processing-card.ts ← Agent 处理状态卡片
│   └── tool-cards.ts       ← 工具调用卡片
├── controllers/
│   ├── chat.ts             ← 聊天状态控制器
│   ├── escalation.ts       ← 权限升级状态控制器
│   ├── subagents.ts        ← 子智能体状态控制器
│   ├── packages.ts         ← 应用中心状态控制器（browse/install/remove）
│   ├── skills.ts           ← 技能面板状态控制器
│   ├── plugins.ts          ← 插件面板状态控制器
│   ├── task-kanban.ts      ← 任务看板状态控制器
│   └── system-maintenance.ts ← 系统维护控制器
├── views/
│   ├── plugins.ts          ← 插件/工具/技能/应用中心四面板视图
│   ├── escalation-popup.ts ← 权限升级弹窗
│   ├── escalation-status-panel.ts ← Security Tab 面板
│   ├── escalation-audit-log.ts   ← 审计日志
│   ├── notification-center.ts    ← 通知中心
│   └── system-maintenance.ts     ← 系统维护视图
└── locales/
    ├── zh.ts               ← 中文国际化
    └── en.ts               ← 英文国际化