diff --git a/common/README.md b/common/README.md
new file mode 100644
index 0000000..723bf88
--- /dev/null
+++ b/common/README.md
@@ -0,0 +1,11 @@
+# common
+
+通用小工具（自 remote-backend-server internal/libs/common 裁剪）。
+
+## 用法
+
+```go
+import "git.zeroonesoft.cn/golib/remote-core/common"
+
+exists, err := common.PathExists("C:\\data") // 文件/目录是否存在
+```
diff --git a/file/README.md b/file/README.md
new file mode 100644
index 0000000..825a1f7
--- /dev/null
+++ b/file/README.md
@@ -0,0 +1,26 @@
+# file
+
+被控端文件管理 HTTP 能力（自 remote-backend-server internal/handlers/file 移植，
+去 DB 依赖）：目录浏览、改名、删除、上传、下载（断点支持）、目录创建。
+
+## 路由
+
+```go
+import "git.zeroonesoft.cn/golib/remote-core/file"
+
+file.RegisterRoutersGatewayFile(r *gin.RouterGroup)
+```
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET/POST | `/file/list` | 目录列表（POST 收 JSON `{path}`，避免路径含 `#` 等字符被 query 截断） |
+| PUT | `/file/name` | 重命名 |
+| DELETE | `/file` | 删除文件/目录 |
+| GET/HEAD | `/file/download` | 下载（HEAD 取大小，GET 支持 Range 续传） |
+| POST | `/file/upload` | 上传 |
+| POST | `/file/dir` | 创建目录 |
+
+## 注意
+
+- 与 shell/process 同为被控 HTTP 能力，经 zonat 隧道 + web-gateway 反代出网。
+- 路径参数来自控制端，接入公网前务必在网关侧做鉴权与路径白名单校验。
diff --git a/process/README.md b/process/README.md
new file mode 100644
index 0000000..436989d
--- /dev/null
+++ b/process/README.md
@@ -0,0 +1,23 @@
+# process
+
+远程进程管理（被控 HTTP 能力）：进程列表 / 结束进程。gopsutil 跨平台实现，
+与 file/shell 同为被控 HTTP 能力——BS 与客户机被控端共用，经 zonat 隧道 +
+web-gateway 反代出网（typ=process，页面 www/process.html）。
+
+## 路由
+
+```go
+import "git.zeroonesoft.cn/golib/remote-core/process"
+
+process.RegisterRoutersProcess(r *gin.RouterGroup)
+```
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/process/list` | 全量进程列表（`ProcItem`：pid/名称/用户/CPU/内存/启动时间/可执行路径/命令行），按内存占用降序 |
+| POST | `/process/kill` | 结束进程，入参 `{pid, name?}` |
+
+## 注意
+
+- `kill` 带 `name` 时做防误杀校验：实际进程名与传入不符则拒绝（防 pid 复用）。
+- Windows 上 gopsutil 权限不足时自动回退 `taskkill /F /T`（连子进程树强杀）。
diff --git a/shell/README.md b/shell/README.md
new file mode 100644
index 0000000..bdb58ba
--- /dev/null
+++ b/shell/README.md
@@ -0,0 +1,27 @@
+# shell
+
+被控端 Web 终端（自 remote-backend-server internal/handlers/shell 移植，去 DB
+依赖）：WebSocket 交互式终端（Windows ConPTY / Unix pty）+ asciinema 会话录制。
+
+## 路由
+
+```go
+import "git.zeroonesoft.cn/golib/remote-core/shell"
+
+shell.RegisterRoutersWebShell(r *gin.RouterGroup, recDir)
+```
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/web/shell` | WebSocket 升级，启动终端（Windows 优先 powershell.exe，缺失回退 cmd.exe；Unix 为 bash） |
+| GET | `/web/shell/record` | 录制文件列表 |
+
+## 协议
+
+WebSocket JSON 信封 `OpDataType{op, data}`：输入/输出流与 `resize`（`ResizeDataType`
+调整行列）走同一连接。
+
+## 注意
+
+- 录制为 asciinema 格式，落盘 `recDir`，可用 asciinema 播放器回放审计。
+- `CheckOrigin` 放开所有来源（跨域），接入公网必须由网关侧补鉴权。