From ceffed25ce46af3921a41ceaf72fe82c269af648 Mon Sep 17 00:00:00 2001
From: MacMini2 <macmini2@MacMini2deMac-mini.local>
Date: Mon, 20 Jul 2026 01:01:33 +0800
Subject: [PATCH] docs: explain Agent Node in plain language

---
 README.md       | 39 ++++++++++++++++++++++++++++++---------
 README.zh-CN.md | 42 +++++++++++++++++++++++++++++++-----------
 2 files changed, 61 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 8b4ce39..235b22e 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,35 @@
 # OpenLinker Agent Node
 
-OpenLinker Agent Node is a temporary Adapter binary for existing HTTP, command,
-A2A, and Codex backends. It starts the pinned `openlinker-go` Runtime Worker and
-injects one process-level Adapter. Applications with a native SDK
-`RuntimeHandler`, a stable HTTPS endpoint, or a remote MCP endpoint do not need
-Agent Node.
-
 Chinese documentation: [README.zh-CN.md](./README.zh-CN.md)
 
-## OpenLinker Runtime
+Agent Node connects an Agent you already have to OpenLinker. It runs next to the
+existing backend, receives a task from OpenLinker Runtime, starts or calls the
+backend, and returns the answer.
+
+It can adapt:
+
+- a local HTTP service;
+- an operator-chosen command;
+- an A2A JSON-RPC Agent;
+- a non-interactive Codex process.
+
+Agent Node is mainly a migration adapter. If a new Go, TypeScript, or Python
+Agent can use an OpenLinker SDK Runtime Worker directly, it does not need Agent
+Node. A stable public HTTPS Agent or remote MCP server also does not need it.
+
+## How it works
+
+1. The `openlinker-go` Runtime Worker receives and safely records a task.
+2. Agent Node passes the task to the selected local backend.
+3. The backend returns its answer; Agent Node sends it back through the SDK.
+4. If OpenLinker cancels the task, command and Codex adapters stop their process
+   trees.
+
+The long-lived Agent Token stays inside Agent Node. A backend that needs to call
+another Agent receives a short-lived localhost helper for the current task
+instead.
+
+## Technical boundary
 
 Agent Node does not implement a Runtime client or state machine. The pinned Go
 SDK owns discovery, mTLS, Session identity, WebSocket/Pull switching,
@@ -16,7 +37,7 @@ assignment confirmation, lease renewal, resume, cancellation, drain, the
 encrypted journal, and stable Event/Result replay. The same SDK behavior is
 available directly to any Go application through `NewRuntimeWorker`.
 
-This repository owns only environment and CLI parsing, Adapter selection,
+This repository owns environment and CLI parsing, Adapter selection,
 localhost helper sessions, process-tree control, the public A2A compatibility
 listener shell (cards, authentication, and request limits), and the choice of
 SDK file-store directory. The SDK proxies that listener's A2A operations to
@@ -25,7 +46,7 @@ the AgentNode listener. Cancellation reaches an Adapter through the SDK handler
 context; command and Codex Adapters terminate their own process trees before
 returning.
 
-Agent Node connects only to the Core Runtime contract. It does not call hosted
+Agent Node connects only to the Core Runtime contract. It does not call Hosted
 service-listing, order, wallet, billing, or marketplace-operation APIs, and it
 does not provide an MCP Adapter.
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 6c1b4f1..4996ea8 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,25 +1,45 @@
 # OpenLinker Agent Node
 
-OpenLinker Agent Node 是现有 HTTP、command、A2A、Codex backend 的临时 Adapter 程序。
-它启动固定版本的 `openlinker-go` Runtime Worker，再注入一个进程级 Adapter。已经直接实现
-SDK `RuntimeHandler`、稳定 HTTPS endpoint 或远程 MCP endpoint 的 Agent 不需要 Agent Node。
-
 English documentation: [README.md](./README.md)
 
-## OpenLinker Runtime
+Agent Node 用来把已经存在的 Agent 接进 OpenLinker。它运行在原有后端旁边，从 OpenLinker
+Runtime 接收任务，再启动或调用后端，最后把答案传回 OpenLinker。
+
+它可以接入：
+
+- 本地 HTTP 服务；
+- 管理员指定的命令；
+- A2A JSON-RPC Agent；
+- 非交互运行的 Codex 进程。
+
+Agent Node 主要用于兼容和迁移已有后端。新写的 Go、TypeScript 或 Python Agent 如果能直接
+使用 OpenLinker SDK Runtime Worker，就不需要 Agent Node。拥有稳定公网 HTTPS 地址的
+Agent 和远程 MCP 服务也不需要它。
+
+## 工作过程
+
+1. `openlinker-go` Runtime Worker 收到任务并先安全保存。
+2. Agent Node 把任务交给选定的本地后端。
+3. 后端返回答案，Agent Node 再通过 SDK 交给 OpenLinker。
+4. OpenLinker 取消任务时，command 和 Codex 适配器会停止自己拉起的整个进程树。
+
+长期 Agent Token 只留在 Agent Node 内。后端需要调用其他 Agent 时，拿到的是只对当前
+任务有效的本地 helper，不是长期 Token。
+
+## 技术边界
 
-Agent Node 不实现 Runtime client 或状态机。固定版本的 Go SDK 负责发现、mTLS、Session 身份、
-WebSocket/Pull 切换、assignment confirmation、续租、resume、取消、drain、加密 journal，
-以及 Event/Result 的稳定 ID 重传。Go 应用也可以直接通过 `NewRuntimeWorker` 使用同一套能力。
+Agent Node 不重复实现 Runtime client 或状态机。固定版本的 Go SDK 负责地址发现、mTLS、
+连接身份、WebSocket/Pull 切换、任务确认、续租、恢复、取消、停止接收新任务、加密任务记录，
+以及事件和结果的可靠重传。Go 应用也可以直接通过 `NewRuntimeWorker` 使用同一套能力。
 
-本仓库只负责环境变量和 CLI、Adapter 选择、localhost helper、进程树控制、public A2A
+本仓库负责环境变量和 CLI、适配器选择、本地 helper、进程树控制、公开 A2A
 兼容监听器外壳（Card、鉴权与请求限制），以及 SDK 文件存储目录的选择。该监听器的 A2A
 有状态操作由 SDK 转发给 Core；为保持外部 URL 指向 AgentNode listener，无状态 Agent Card
-响应仍在本地生成。取消通过 SDK handler context 传入 Adapter；command 和 Codex Adapter
+响应仍在本地生成。取消通过 SDK 任务上下文传入适配器；command 和 Codex 适配器
 在返回前终止自己的进程树。
 
 Agent Node 只连接 Core Runtime 契约，不调用 Hosted 的服务商品、订单、钱包、计费或市场
-运营 API，也不提供 MCP Adapter。
+运营 API，也不提供 MCP 适配器。
 
 ```mermaid
 flowchart LR