01
快速上手
Getting Started
START三步跑起来。原则只有一条：exe 在哪运行，配置与数据就在哪生成——零配置可用。
Three steps to run it. One rule: wherever the exe runs, config and data live next to it — zero config required.
① 安装① Install
Releases 下载绿色版或安装包；绿色版放任意文件夹加入 PATH 即可。也支持纯 server 形态（浏览器访问）。
Grab the portable exe or installer from Releases; the portable build just needs a folder on PATH. A plain-server mode (browser access) is also available.
README · 安装 →
② 配置模型② Pick a model
「模型」页填 apiKey：main / image / audio 三槽单选，各自带用量统计。
Enter your apiKey on the Models page: three single-choice slots (main / image / audio), each with usage stats.
README · 30 秒上手 →
③ 第一轮对话③ First chat
把任务直接交给它；需要你的时候，审批与提问会以决策卡出现在时间线与右上角通知栏。
Hand over a task; approvals and questions arrive as decision cards in the timeline and the notification corner.
README · 30 秒上手 →
docs/gif/first-chat.gif
02
用户指南
User Guide
GUIDE每个功能面一张卡——对话之外的通道，是 ezharness 的产品主张。
One card per feature surface — channels beyond the chat are the product thesis of ezharness.
对话与决策Chat & decisions
SSE 流式时间线；四档审批（每次审批/黑名单/白名单/全免审）即时生效；决策卡断线可重放。
Streaming timeline over SSE; four approval levels applied instantly; decision cards replayable after reconnect.
interaction.md →
树状会话Session tree
多线并行；任意消息处分叉（fork）；归档换代（compact）沉淀记忆；切线不打断后台运行。
Parallel branches; fork from any message; compact into long-term memory; branch switching never kills background runs.
md/session.md →
共享终端Shared terminal
人机共用同一个真实 shell（ConPTY）：agent 干活你随时接管，你敲的命令它知道。
One real shell shared by human and agent: take over anytime; your keystrokes feed the agent's context.
interaction.md →
共享浏览器Shared browser
桌面端内嵌真实 Chromium：AI 经工具操作、你在同一页面原生接管；AI 操作时窗口自动弹出共见。
Real embedded Chromium on desktop: the AI operates via tools, you take over natively; the window pops up for co-viewing.
interaction.md →
魔法画板Magic whiteboard
对象模型白板：标注截图、白板创作，所见即所得回填为对话附件。
Object-model canvas: annotate screenshots or draw, and hand it back to the chat as an attachment.
README · 核心玩法 ↗
快应用Quick apps
agent 生成的小工具一键启动为子窗口；同源页面直调 MCP（/api/mcp/call）无需令牌。
Agent-generated mini tools launch as child windows; same-origin pages call MCP directly, token-free.
README · 核心玩法 ↗
MCP
外部工具服务器（http/stdio）：探活、启停、热加载；mcp_router 工具统一入口。
External tool servers (http/stdio): health checks, start/stop, hot reload; unified via the mcp_router tool.
README · 核心玩法 ↗
技能与记忆Skills & memory
技能库 SKILL.md 即存即用；长期记忆 harness.md 索引进上下文 + user/soul/project 记忆文件。
A skill library of SKILL.md files; long-term memory with harness.md index in context plus user/soul/project memory files.
architecture.html · 数据目录 →
安全与鉴权Security & auth
全 API 令牌鉴权（设置页可复制）+ 同源放行；终端命令包含匹配拦截，宁误拦不漏拦。
Token auth on every API (copyable in settings) + same-origin pass; terminal commands blocked by substring match.
architecture.html · 人机交互 →
docs/gif/terminal.gif
03
核心概念
Core Concepts
CONCEPTSezharness 的设计语言：三支柱与两个关键模型。
The design language of ezharness: three pillars and two key models.
上下文工程Context engineering
system 两段式组装、trim 双触发（水位自动 + 模型主动）、agent_status 轮首快照、guard 窗口余量兜底。
Two-part system prompt, dual-trigger trim (watermark + model-initiated), per-turn agent_status snapshots, guard fallback by window headroom.
md/context.md →
trim 与 compacttrim vs compact
trim 是模型侧整理（就地折叠不换库）；compact 是用户侧沉淀（记忆合并 + 换代封存）——一对互补机制。
trim is the model-side cleanup (fold in place, same store); compact is the user-side distillation (merge memory, seal the generation).
md/compaction.md →
人机协同交互Human-agent interaction
对话不是唯一通道：决策、观察、操作各有专门产品面；通知全局可达，数据不绑视图。
Chat is not the only channel: deciding, watching and operating each get a dedicated surface; notifications are globally reachable.
interaction.md →
树状会话模型The session treekey model
节点是 session（一次换代内的完整对话库），线是用户视角的「会话」。树对用户只露两个操作：fork 分叉（copy 语义）与 compact 换代（沉淀式归档）；上翻沿 compress 链懒加载旧世代全文。状态即消息：全部状态是可落盘的消息库与 system，重启即恢复，折叠不丢档。
Nodes are sessions (a full message store within one generation); lines are what the user calls a "conversation". The tree exposes exactly two operations: fork (copy semantics) and compact (distilling archive); older generations lazy-load along the compress chain. State is messages: everything persists as a message store plus system — restart restores, folding never loses data.
md/session.md →
hook 与 warpHooks & warps
16 个 hook 塑造上下文、2 条 warp 链包装模型与工具调用——ezharness 与 ezloop 的扩展点分界。
16 hooks shape the context and two warp chains wrap model/tool calls — the extension-point boundary between ezharness and ezloop.
md/hooks.md →
04
深入设计
Deep Dives
DEEP给读代码与做二次开发的人：全景页 + 各主题底稿，改代码前先扫对应篇。
For readers of the code and fellow builders: a panorama page plus per-topic source notes — scan the matching one before changing code.
架构全景（深读主页）Architecture panoramahtml
四章：系统整体架构（分层/三通道/数据目录/生命周期）· session 树 · 上下文全动作（16 hook 详解 + 消息全表 + 场景演练）· 产品视角。
Four chapters: overall architecture (layering / channels / data dir / lifecycle) · the session tree · context in action (16 hooks, message tables, walkthroughs) · product view.
architecture.html →
architecture.md
系统架构底稿
Architecture source notes
md/ →
runtime.md
一轮 chat 全流程与 hook 组成
A chat turn end-to-end
md/ →
frontend.md
SSE 事件全集、历史重建、tag 契约
SSE events, history rebuild, tag contracts
md/ →
session.md
SessionSnap、三种演进、恢复与不变量
SessionSnap, three evolutions, invariants
md/ →
context.md
system 组装与 trim 双触发
System assembly and dual-trigger trim
md/ →
compaction.md
trim 与 compact 分工方案
trim vs compact design
md/ →
hooks.md
封装范式与仓库分界判据
Wrapping patterns and repo boundary
md/ →
05
参考
Reference
REF构建、开发备忘与速查。
Build, dev memo and quick reference.
build.md
构建方案与发布链
Build and release pipeline
build.md →
AGENTS.md
开发备忘：变更连带检查清单与易踩的坑
Dev memo: change-ripple checklists and pitfalls
AGENTS.md →
ezloop sister repo
agent loop 引擎：hook / warp / fork / provider
The agent loop engine: hooks / warps / forks / providers
GitHub ↗
API 速查：API quick reference:
全部
/api/* 需鉴权——X-EZ-Token 头或 ?token=（设置页可复制）；同源页面（前端与快应用）免令牌。对话事件流 GET /api/sessions/:id/events（SSE）；共享终端 GET /api/terminal/ws；浏览器桥 GET /api/browser/bridge（desktop 连入）；MCP 直调 POST /api/mcp/call。
Every /api/* route is authenticated — via the X-EZ-Token header or ?token= (copyable in settings); same-origin pages are exempt. Event stream: GET /api/sessions/:id/events (SSE); shared terminal: GET /api/terminal/ws; browser bridge: GET /api/browser/bridge (desktop connects); direct MCP: POST /api/mcp/call.