diff --git a/README.md b/README.md
index 9fc1d78..840e3b9 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,28 @@
-# storage
+# 跨中心存储系统
 
+
+## 目录结构
+此仓库是一个go module，但包含了多个服务的源码，你可以在每个服务的目录中找到main.go。可以通过编译脚本的参数来指定生成哪一个服务。
+
+- `agent`：Agent服务的源码。
+- `client`：Client服务的源码。
+- `common`：存放在几个服务之间共享的代码以及一些数据结构定义。
+- `coordinator`：Coordinator服务的源码。
+- `scanner`：Scanner服务的源码。
+
+同时还有以下两个与编译相关的目录：
+- `build`：服务编译后的输出目录，只会在编译后生成。
+- `magefiles`：mage工具使用的编译脚本。
+
+## 编译
+运行编译脚本需要使用mage工具，此处是[仓库链接](https://github.com/magefile/mage)。
+
+安装好mage工具之后，进入到仓库根目录，使用`mage agent`即可编译Agent服务。与此相同的还有`mage client`、`mage coodinator`、`mage scanner`。可以同时指定多个参数来编译多个服务，如果要一次性编译所有服务，可以使用`mage bin`。
+
+使用`mage confs`命令可以将`common/assets/confs`的配置文件拷贝到输出目录，使用`mage scripts`将`scripts`目录里的脚本拷贝到输出目录。
+
+使用`mage all`可以一次性完成编译、拷贝工作。
+
+可以通过增加额外的参数来指定编译目标平台，比如`mage win amd64 agent`。支持的操作系统参数有`win`、`linux`，支持的CPU架构参数有`amd64`、`arm64`。这些参数同样可以和`bin`、`all`参数一起使用。
+
+注意：编译目标平台参数必须在编译二进制参数之前。
diff --git a/agent/README.md b/agent/README.md
index ac900ba..7b452e2 100644
--- a/agent/README.md
+++ b/agent/README.md
@@ -1,2 +1,10 @@
-# storage-agent
+# Agent服务
 
+## 目录结构
+- `internal`：服务源码。
+  - `config`：服务使用的配置文件结构定义。
+  - `grpc`：通过grpc对外提供的接口。实现了.proto文件里定义的接口，这个文件位于`common\pkgs\grpc\agent\agent.proto`。
+  - `mq`：通过rabbitmq对外提供的接口。实现了`common\pkgs\mq\agent`目录里文件定义的接口。
+  - `task`：需要在后台异步运行的任务。
+
+ 
\ No newline at end of file
diff --git a/client/README.md b/client/README.md
index 3e52ab1..82768fb 100644
--- a/client/README.md
+++ b/client/README.md
@@ -1,2 +1,18 @@
-# storage-client
+# Client服务
 
+## 目录结构
+- `internal`：服务源码。
+  - `cmdline`：此服务提供的命令行功能。
+  - `config`：服务使用的配置文件结构定义。
+  - `http`：此服务提供的http接口。
+  - `services`：服务的功能，被cmdline和http调用。
+  - `task`：需要在后台异步运行的任务。
+
+## 命令行
+Client程序可以作为一个命令行程序使用，能在`internal/cmdline`中找到它提供的所有命令。
+
+使用时按照`./client <命令前缀1> <命令前缀2>... <命令函数参数1> <命令函数参数2>...`的方式编写命令。命令前缀在每个文件的init函数中能找到。
+
+以列出某个Bucket下所有Package的命令PackageListBucketPackages为例，它的命令前缀是`pkg ls`，它的函数签名是`PackageListBucketPackages(ctx CommandContext, bucketID cdssdk.BucketID)`，忽略掉会自动填写的ctx参数，需要通过命令行提供的就是bucketID参数，假设为5，因此调用它的命令是：`./client pkg ls 5`。
+
+可以通过使用`serve http`命令将Client程序作为一个http服务启动，并保持运行。
\ No newline at end of file
diff --git a/common/README.md b/common/README.md
index e2f2215..5459cf5 100644
--- a/common/README.md
+++ b/common/README.md
@@ -1,2 +1,21 @@
-# storage-common
+# 公共库
+这个目录存放的是在storage仓库的几个程序之间共享的代码和数据结构定义。
 
+## 目录结构
+- `assets`：存放程序会读取使用的配置文件等。会在编译时一并复制到输出目录。
+  - `confs`：服务的配置文件。
+  - `scripts`：脚本文件。
+- `consts`：常量定义。
+- `globals`：全局变量定义，主要是各种客户端的Pool。
+- `magefiles`：mage工具的脚本。
+- `models`：公共数据结构定义。
+- `pkgs`：一些相对独立的功能模块。
+  - `cmd`：公用的业务逻辑，比如上传Package和下载Package。
+  - `db`：数据库的数据结构和操作函数。
+  - `distlock`：分布式锁服务，核心机制使用的是`common/pkgs/distlock`，增加了根据存储系统的业务需求设计的锁。
+  - `ec`：纠删码的库。
+  - `grpc`：存放proto文件，以及使用protogen工具生成的代码文件。
+  - `ioswitch`：IOSwitch模块。
+  - `iterator`：迭代器。
+  - `mq`：各个服务的rabbitmq接口的声明。
+- `utils`：一些暂时没有归类的工具函数。
\ No newline at end of file
diff --git a/coordinator/README.md b/coordinator/README.md
index d09937e..6bb9407 100644
--- a/coordinator/README.md
+++ b/coordinator/README.md
@@ -1,2 +1,6 @@
-# storage-coordinator
+# Coordinator服务
 
+## 目录结构
+- `internal`：服务源码。
+  - `config`：服务使用的配置文件结构定义。
+  - `mq`：通过rabbitmq对外提供的接口。实现了`common\pkgs\mq\coodinator`目录里文件定义的接口。
diff --git a/scanner/README.md b/scanner/README.md
index 2ebec19..b0fda77 100644
--- a/scanner/README.md
+++ b/scanner/README.md
@@ -1,2 +1,8 @@
-# storage-scanner
+# Scanner服务
 
+## 目录结构
+- `internal`：服务源码。
+  - `config`：服务使用的配置文件结构定义。
+  - `event`：被投递到队列顺序执行的事件。
+  - `mq`：通过rabbitmq对外提供的接口。实现了`common\pkgs\mq\scanner`目录里文件定义的接口。
+  - `tickevent`：定时执行的事件。
\ No newline at end of file