ezharness

flowchart TB
    UI["🖥 前端 SPA（Svelte 5 runes）<br/>store.svelte · api.ts · term.ts"]:::ui

    subgraph shell["core 装配 · core/main.go / app.go"]
        CFG["config · ezharness.json（应用根）<br/>chdir 数据目录 · 换代 restart · boot 代际"]:::layer
    end

    subgraph EZH["ezharness 宿主 · 装配 + 产品域"]
        C["controller 表现层<br/>10 组 gin handler"]:::layer
        S["service 用例层<br/>Chat / Session / Topic / Settings / Terminal / Agent…"]:::layer
        D["domain · Session 聚合 + Hub<br/>零 HTTP 依赖"]:::layer
        H["internal/hooks（宿主侧）<br/>sysprompt · remind · trim · sessionstore<br/>reference_file · guard · trace"]:::layer
        TL["internal/tools<br/>save_app · term_* · browser_*"]:::layer
        WP["internal/warp<br/>modeldump · visionguard · toolarg"]:::layer
    end

    subgraph EZL["ezloop 引擎 · 本地 replace"]
        CORE["core · loop / agent / fork"]:::engine
        EXT["ext 组件 · filetools · skilltool · mcp<br/>approve · askuser · task · offload · contextfix"]:::engine
        PROV["provider · anthropic / openai / responses"]:::engine
    end

    DISK[("数据目录 = 进程 cwd<br/>sessions/ · memory/ · workspace/ · apps/")]

    UI -- "HTTP REST（用例）" --> C
    UI -- "SSE /events（对话事件流）" --> C
    UI -- "WS /terminal/ws（共享终端）" --> C
    C --> S --> D
    D --> H
    S --> TL
    D --> WP
    H --> EZL
    WP --> PROV
    CORE --> PROV
    CORE -.->|hook 调用| H
    H --> DISK

    classDef ui fill:#0b1322,stroke:#33496e,color:#c4cede
    classDef layer fill:#072331,stroke:#00add8,color:#9be5f7
    classDef engine fill:#07281b,stroke:#34d399,color:#a7f3d0
    style shell fill:#0a101d,stroke:#33496e,stroke-dasharray:6 4
    style EZH fill:#0a101d,stroke:#00add8,stroke-dasharray:6 4
    style EZL fill:#0a101d,stroke:#34d399,stroke-dasharray:6 4

flowchart TB
    subgraph DESK["desktop/ · ezharness.exe · Electron 壳"]
        MW["主窗口 / 托盘 / 快应用子窗<br/>无边框主窗（前端 TitleBar 自绘）"]:::role
        BW["内嵌浏览器窗口<br/>WebContentsView 标签页（desktop 资产）"]:::role
    end

    subgraph COREP["core/ · ezharness-core.exe · Go sidecar"]
        G["gin server<br/>前端页面 · /api/* · SSE 事件流 · /apps/*"]:::layer
        A["agent 引擎<br/>ezloop core · 随会话装配"]:::engine2
    end

    UI["🖥 前端页面 · Svelte 单入口 SPA<br/>主窗 / 抽屉弹窗 / 浏览器抽屉同一份页面"]:::ui
    BR["🌐 浏览器（web 端形态）"]:::misc

    DESK -. "spawn + health 轮询<br/>退出随壳 kill" .-> COREP
    MW -- "loadURL 同源页面" --> G
    BW -- "承载 SPA 的浏览器抽屉/弹窗<br/>（标签条/地址栏 UI，?popout=browser）" --> G
    BW -. "browser_* 工具<br/>WS 桥 /api/browser/bridge" .-> G
    BR --> G
    G --> A

    classDef role fill:#072331,stroke:#00add8,color:#9be5f7
    classDef layer fill:#072331,stroke:#00add8,color:#9be5f7
    classDef engine2 fill:#07281b,stroke:#34d399,color:#a7f3d0
    classDef ui fill:#0b1322,stroke:#33496e,color:#c4cede
    classDef misc fill:#0b1322,stroke:#33496e,color:#c4cede
    style DESK fill:#0a101d,stroke:#33496e,stroke-dasharray:6 4
    style COREP fill:#0a101d,stroke:#00add8,stroke-dasharray:6 4

flowchart TD
    subgraph line1["线 root-1（TopicEntry：ID=root-1，LeafID=gen-3）"]
        gen1["gen-1 世代<br/>Archived=true 封存"]:::gen -- "compact（用户手动）<br/>摘要归档 + PrevSession 边" --> gen2["gen-2 世代<br/>Archived=true"]:::gen
        gen2 -- "compact" --> gen3["gen-3 当前叶<br/>（Active，ID 随换代更新）"]:::leaf
    end

    gen1 -. "fork@anchor<br/>携带 0,anchor 完整副本" .-> line2root

    subgraph line2["线 root-2（Kind=fork，自成新根）"]
        line2root["root-2 世代 0<br/>标题 = 锚点消息内容"]:::fork
    end

    taskFork["轮内 task 分身（ForkID ≠ ''）<br/>并行子循环 · 增量存 forks/<fid>/<br/>不开线，answer 汇回主循环"]:::task

    gen3 -. "task 工具" .-> taskFork
    prev["上翻链：PrevSession<br/>（前端懒加载旧世代全文）"]:::note
    gen2 --- prev

    classDef gen fill:#072331,stroke:#00add8,color:#9be5f7
    classDef leaf fill:#0b2e40,stroke:#38bdf8,color:#bae6fd
    classDef fork fill:#1d1636,stroke:#a78bfa,color:#ddd3fc
    classDef task fill:#07281b,stroke:#34d399,color:#a7f3d0
    classDef note fill:#0b1322,stroke:#33496e,color:#8b98b0

flowchart LR
    subgraph mem["内存 · domain.Session"]
        HIST["history []Message<br/>全量（含 marker 前档案）"]:::m
        VIEW["modelView()<br/>= 最后 context_trim marker 之后"]:::m
        WIRED["wiring：Agent / Provider<br/>ApproveCh / AnswerCh / Trace"]:::m
    end
    subgraph disk["磁盘 sessions/<id>/"]
        SNAP["session.json（状态）<br/>SystemPrompt / Snapshot 基线<br/>Edge / Usage / Archived…"]:::d
        TRC["trace.jsonl<br/>消息行 + span（追加式）"]:::d
        DEC["decisions.jsonl"]:::d
        FK["forks/<fid>/session.json"]:::d
    end
    HIST -- "sessionstore.OnEnd 每轮落盘：<br/>新增消息追加 trace.jsonl；<br/>状态覆盖写 session.json" --> SNAP
    SNAP -- "bootstrap restoreFrom<br/>（history / 基线 / 水位 / LineRoot）" --> HIST
    WIRED -.-> TRC

    classDef m fill:#072331,stroke:#00add8,color:#9be5f7
    classDef d fill:#0b1322,stroke:#33496e,color:#c4cede
    style mem fill:#0a101d,stroke:#00add8,stroke-dasharray:6 4
    style disk fill:#0a101d,stroke:#33496e,stroke-dasharray:6 4

sequenceDiagram
    autonumber
    participant FE as 前端
    participant CS as ChatService/Session
    participant E as ezloop 引擎
    participant HK as hooks（startHooks/endHooks）
    participant P as Provider（模型 warp 链）
    participant T as 工具（工具 warp 链）

    FE->>CS: POST /messages {text, files}
    CS->>CS: 附件落盘 workspace/tmp/（base64 不入上下文）
    CS->>E: RunAsync(WithHistory(modelView), WithUploadFiles)

    E->>E: AppendMessage(input)  ← 用户输入入史
    E->>HK: startHooks[].OnStart（按序）
    Note over HK: sys(system) → trace(观测层，须在会 Skip 短路的 hook 之前)<br/>→ loopguard(护栏) → contextfix(修理) → filetools(注册工具) → skilltool<br/>→ remind(变更段 resource_change? + 快照段 agent_status) → reference_file(路径告知?)<br/>→ approver/asker/task/mcp(注册) → offload/guard/trim/sessionstore(就位)

    loop 迭代（≤MaxIterations）
        E->>P: 模型调用
        Note over P: modeldump(打印) → modelretry(退避)<br/>→ visionguard(无视觉剥图) → 真实 API
        P-->>E: 流式响应 / tool_calls
        E->>FE: SSE model_chunk / tool_chunk …
        alt 有工具调用
            E->>HK: OnToolStart（approve 审批 / skilltool·asker·task·trim 拦截，可 Skip）
            E->>T: toolarg(参数展开) → limit(并发) → safetool → 工具本体
            T-->>E: 结果
            E->>HK: OnToolEnd（offload 卸载 → guard 兜底 → trace）
            E->>HK: OnLoop（filetools 图片标记→图片消息+事件 → trim 水位 → mcp 热加载）
        else 纯文本
            E-->>E: break
        end
    end

    E->>HK: endHooks[].OnEnd
    Note over HK: remind(LastOutputAt + end_reason) → trace<br/>→ sessionstore 落盘（MergeFull）
    CS-->>FE: SSE turn_end（stopReason/usage）

flowchart LR
    subgraph 模型链
        MD["modeldump<br/>调试打印（最外，重试不重打）"]:::m --> MR["modelretry<br/>指数退避（流式已出 chunk 不重试）"]:::m --> VG["visionguard<br/>无视觉剥请求图"]:::m --> API["provider 真实 API"]:::m
    end

flowchart LR
    subgraph 工具链
        TA["toolarg<br/><@toolArg> 执行前展开"]:::t --> LM["limit(4)<br/>同轮并发上限"]:::t --> ST["safetool<br/>panic 恢复为 error"]:::t --> TOOL["工具本体"]:::t
    end

flowchart LR
    subgraph TERM["ConPTY 全局公共池 · 跨会话共享"]
        PT["真实 shell<br/>环形缓冲 256KB"]:::core
    end
    AG["🤖 agent<br/>term_action send / read"]:::side --> PT
    US["👤 用户<br/>xterm 直接敲"]:::side --> PT
    PT -- "readMark 单游标<br/>读即消费" --> AG

    classDef core fill:#072331,stroke:#00add8,color:#9be5f7
    classDef side fill:#0b1322,stroke:#33496e,color:#c4cede
    style TERM fill:#0a101d,stroke:#33496e,stroke-dasharray:6 4

flowchart LR
    subgraph COREP["core · 桥服务端"]
        BT["browser_* 工具两件套（browser_tab / browser_action）<br/>定义/审批在 core（tools 层不感知实现）"]:::core
    end
    subgraph DESK["desktop · 浏览器窗口 = 壳的资产"]
        EXE["执行器<br/>WebContentsView.webContents 直接操作"]:::side
        VIEW["👤 用户共见<br/>原生交互（点击 / IME / 视频）"]:::side
    end
    AI["🤖 agent"]:::side -- "工具调用" --> BT
    BT -- "WS 桥 /api/browser/bridge<br/>JSON-RPC 转发 + 回执" --> EXE
    EXE --- VIEW

    classDef core fill:#072331,stroke:#00add8,color:#9be5f7
    classDef side fill:#0b1322,stroke:#33496e,color:#c4cede
    style COREP fill:#0a101d,stroke:#00add8,stroke-dasharray:6 4
    style DESK fill:#0a101d,stroke:#33496e,stroke-dasharray:6 4