diff --git a/README.md b/README.md
new file mode 100644
index 0000000..be9c36a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,71 @@
+# linkwork-executor
+
+English | [中文](./README_zh-CN.md)
+
+`linkwork-executor` is the LinkWork task worker. It consumes tasks from Redis queues, prepares workspace context, invokes `AgentEngine`, handles interrupts/archive, and performs lifecycle scale-down on idle timeout.
+
+## Entry Points
+
+- Python package entry: `linkwork_executor.Worker`
+- CLI entry: `linkwork-executor-worker`
+- Default config path: `/opt/agent/config.json`
+
+## Local Development
+
+### 1) Requirements
+
+- Python 3.11+
+- Redis
+
+### 2) Install
+
+```bash
+cd linkwork-agent-sdk && pip install -e .
+cd ../linkwork-executor && pip install -e .
+```
+
+### 3) Start worker
+
+```bash
+cd linkwork-executor
+WORKSTATION_ID=ws-demo \
+REDIS_URL=redis://127.0.0.1:6379 \
+linkwork-executor-worker --config ./config.json
+```
+
+Required env var:
+
+- `WORKSTATION_ID`
+
+Common env vars:
+
+- `REDIS_URL` (default: `redis://redis:6379`)
+- `IDLE_TIMEOUT`
+- `TASK_RUNTIME_IDLE_TIMEOUT`
+- `WORKER_DESTROY_API_BASE`
+- `WORKER_DESTROY_API_PASSWORD`
+
+## Deploy Flow
+
+### Option A: Run inside role image (primary path)
+
+In `LinkWork/back`, build flow copies `linkwork-executor` source into role images. Runtime is started through:
+
+- `start-single.sh` (single-container mode)
+- `start-dual.sh` (agent + runner mode)
+
+These scripts manage permission setup, `zzd` startup, worker startup, and graceful shutdown.
+
+### Option B: Publish as standalone package (optional)
+
+```bash
+cd linkwork-executor
+python -m build
+# twine upload dist/*   # use your internal release process
+```
+
+## Related Components
+
+- Depends on `linkwork-agent-sdk`
+- Upstream scheduler: `LinkWork/back`
+- Data channel: Redis queue + Redis stream
diff --git a/README_zh-CN.md b/README_zh-CN.md
new file mode 100644
index 0000000..5b3f575
--- /dev/null
+++ b/README_zh-CN.md
@@ -0,0 +1,69 @@
+# linkwork-executor
+
+`linkwork-executor` 是 LinkWork 任务执行器，负责从 Redis 队列消费任务、准备工作区、调用 `AgentEngine`、处理中断与归档，并在空闲超时后执行生命周期回收。
+
+## 核心入口
+
+- Python 包入口：`linkwork_executor.Worker`
+- CLI 入口：`linkwork-executor-worker`
+- 默认配置路径：`/opt/agent/config.json`
+
+## 本地开发
+
+### 1) 环境要求
+
+- Python 3.11+
+- Redis
+
+### 2) 安装
+
+```bash
+cd linkwork-agent-sdk && pip install -e .
+cd ../linkwork-executor && pip install -e .
+```
+
+### 3) 启动 Worker
+
+```bash
+cd linkwork-executor
+WORKSTATION_ID=ws-demo \
+REDIS_URL=redis://127.0.0.1:6379 \
+linkwork-executor-worker --config ./config.json
+```
+
+必需环境变量：
+
+- `WORKSTATION_ID`
+
+常用环境变量：
+
+- `REDIS_URL`（默认 `redis://redis:6379`）
+- `IDLE_TIMEOUT`
+- `TASK_RUNTIME_IDLE_TIMEOUT`
+- `WORKER_DESTROY_API_BASE`
+- `WORKER_DESTROY_API_PASSWORD`
+
+## Deploy 流程
+
+### 方案 A：随角色镜像运行（主路径）
+
+`LinkWork/back` 构建阶段会把 `linkwork-executor` 源码复制到镜像中；运行阶段由以下脚本拉起：
+
+- 单容器：`start-single.sh`
+- 双容器（Agent + Runner）：`start-dual.sh`
+
+脚本会完成权限初始化、`zzd` 启动、Worker 启动与优雅退出管理。
+
+### 方案 B：独立打包发布（可选）
+
+```bash
+cd linkwork-executor
+python -m build
+# twine upload dist/*  # 按内部流程发布
+```
+
+## 与其他模块关系
+
+- 依赖：`linkwork-agent-sdk`
+- 上游调度：`LinkWork/back`（任务下发与状态管理）
+- 数据通道：Redis 队列 + Redis Stream