diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..32bf368
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,9 @@
+# DevChat Workflow Documentation
+
+自定义你的智能编程助手。
+
+- [快速入门](./quickstart.md)
+- [自定义工作流管理：命名空间](./namespace.md)
+- [工作流定义文件规范](./command_spec.md)
+- [工作流开发指南](./workflow.md)
+- [用户设置](./user_settings.md)
diff --git a/docs/command_spec.md b/docs/command_spec.md
new file mode 100644
index 0000000..240ed31
--- /dev/null
+++ b/docs/command_spec.md
@@ -0,0 +1,140 @@
+# 工作流定义文件规范
+
+工作流定义文件固定使用文件名`command.yml`，用来配置工作流的相关信息、使用内置变量、运行脚本等。
+
+## 工作流属性
+
+### `description`
+
+工作流的描述信息，将在DevChat聊天栏的Workflow List中展示。
+
+示例:
+```yaml
+description: Say hello to the world
+```
+
+### `steps`
+
+工作流的执行步骤，包含一个或多个`run`字段，用于依次运行命令或脚本。运行输出的内容将被视为 Markdown 格式的消息显示在聊天窗口中。
+
+> **NOTE:** 当前版本执行命令的工作目录为编辑器所打开的的工作区目录，不久后命令的工作目录将会变更为用户目录（`~`）。
+
+示例:
+```yaml
+steps:
+  - run: echo "Hello World!"
+  - run: date +"%Y-%m-%d %H:%M:%S"
+```
+
+### `help`
+
+定义工作流的帮助文档（Markdown格式），通过 `/<workflow_name> --help` 在聊天窗口中显示帮助文档内容。
+
+`help`的形式为以下之一：
+- 单个字符串：帮助文档的相对于此`command.yml`的文件路径。
+- `key: value` 对：多语言的帮助文档，`key`为语言代码，`value`为帮助文档的相对于此`command.yml`的文件路径。可通过`--help.{lang}`显示指定语言对应的文档。
+
+示例一:
+```yaml
+help: readme.md
+```
+
+以下命令均将显示`readme.md`的内容：
+```
+/<workflow_name> --help
+/<workflow_name> --help.en
+/<workflow_name> --help.zh
+/<workflow_name> --help.xxx
+```
+
+示例二:
+```yaml
+help:
+  en: 1.md
+  zh: 2.md
+```
+
+```
+/<workflow_name> --help      # 默认显示第一个文档，即`1.md`
+/<workflow_name> --help.en   # 显示`1.md`
+/<workflow_name> --help.zh   # 显示`2.md`
+/<workflow_name> --help.xxx  # 默认显示第一个文档，即`1.md`
+```
+
+### `workflow_python`
+
+DevChat Workflow Engine为执行 Python 脚本提供了更多便利。可通过`workflow_python`为当前工作流创建独立的Python环境、安装依赖（需能访问公网）。
+
+- `workflow_python.env_name`(Optional)
+  - Python环境名称，用于区分不同工作流的Python环境。默认与工作流同名。
+- `workflow_python.version`
+  - 指定该环境的Python版本。
+- `workflow_python.dependencies`
+  - Python依赖包文件（即`requirements.txt`）相对于此`command.yml`的文件路径，用于安装Python依赖。
+  - 关于`requirements.txt`的更多信息，请参考[Python官方文档](https://pip.pypa.io/en/stable/user_guide/#requirements-files)。
+  
+示例，创建一个名为`my_env`的Python环境用于在当前工作流中运行Python脚本：
+```yaml
+workflow_python:
+  env_name: my_env
+  version: 3.8
+  dependencies: dep.txt
+```
+
+> **拓展：** [无法访问公网时，需手动配置workflow_python](user_settings.md#external_workflow_python)
+
+
+## 内置变量
+
+### `$input`
+
+`$input`用于获取用户在DevChat聊天栏中的输入（`/<workflow_name>`之后的部分）。
+
+使用示例
+```yaml
+steps:
+  - run: echo $input
+```
+
+### `$command_path`
+
+`$command_path`当前工作流目录的路径。可用于引用工作流目录下的文件。
+
+使用示例
+```yaml
+steps:
+  - run: cat $command_path/README.md
+```
+
+### `$devchat_python`
+
+DevChat Workflow Engine内置Python，可用来执行简单的Python脚本（无特殊包依赖）。
+
+使用示例
+```yaml
+
+steps:
+  - run: $devchat_python -c "print('Hello World!')"
+  - run: $devchat_python $command_path/main.py
+```
+
+### `$workflow_python`
+
+当前工作流独立的Python环境，必须定义了`workflow_python`属性后才可使用。
+
+使用示例
+```yaml
+workflow_python:
+    env_name: my-py
+    version: 3.12.0
+    dependencies: my_dep.txt
+steps:
+  - run: $workflow_python $command_path/main.py
+```
+
+
+## 其他
+
+### 路径表示方式
+
+在`command.yml`中，表示路径应使用POSIX风格，即，使用正斜杠`/`作为路径分隔符。
diff --git a/docs/images/quickstart-my_hello.jpeg b/docs/images/quickstart-my_hello.jpeg
new file mode 100644
index 0000000..6fd4796
Binary files /dev/null and b/docs/images/quickstart-my_hello.jpeg differ
diff --git a/docs/namespace.md b/docs/namespace.md
new file mode 100644
index 0000000..c6238b3
--- /dev/null
+++ b/docs/namespace.md
@@ -0,0 +1,24 @@
+# 自定义工作流管理：命名空间
+
+命名空间是`custom`目录下的子目录，用于将工作流分组，以便更好地管理和组织自定义工作流。
+
+## `config.yml` 配置
+
+### `namespaces`字段
+
+命名空间注册列表，列表中的每个元素为一个命名空间名。
+
+命名空间需要显式注册后才会被启用，列表顺序为命名空间的优先级顺序。当多个命名空间下存在同名工作流时，只会执行优先级最高的命名空间下的工作流。
+
+例如，以下配置文件中，`demo`命名空间的优先级高于`team_a`命名空间。如果`demo`和`team_a`下都存在`hello`工作流，则`/hello`只会触发`demo`命名空间下的`hello`工作流。
+```yaml
+namespaces: 
+  - demo
+  - team_a
+```
+
+#### 自定义命名空间与默认命名空间的优先顺序
+DevChat Workflow Engine中有两个默认命名空间`merico`和`community`，它们与自定义命名空间的优先顺序从高到低为：
+- 所已注册的自定义命名空间
+- `merico`
+- `community`
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 0000000..b773fd5
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,51 @@
+# DevChat 自定义工作流快速入门
+
+通过创建一个简单的 Hello 工作流了解 DevChat Workflow 的基本概念。
+
+## 基本要求
+
+在开始之前，需要安装DevChat插件:
+- VSCode
+- JetBrains IDE
+
+## 创建自定义工作流
+
+安装DevChat插件后，你的用户目录下会有`.chat/scripts`目录，这个目录用于DevChat Workflows相关管理，其中`custom`目录用于存放自定义工作流。
+
+### 1. 创建并注册自定义命名空间`demo`
+
+- 在`.chat/scripts/custom`目录下创建一个名为`demo`的目录。
+- 在`.chat/scripts/custom`目录下创建`config.yml`文件，其内容如下：
+```yaml
+namespaces: 
+  - demo
+```
+
+了解更多：[命名空间](./namespace.md)
+
+
+### 2. 在`demo`中创建`my_hello`的工作流
+
+- 在`demo`目录下创建`my_hello`目录。
+- 在`my_hello`目录下创建`command.yml`文件，其内容如下：
+```yaml
+description: Say hello to the world
+steps:
+  - run: echo "Hello World!"
+  - run: echo "Have a nice day!"
+```
+
+了解更多：[工作流定义文件规范](./command_spec.md)
+
+### 3. 运行`my_hello`工作流
+
+打开DevChat聊天栏，输入`/my_hello`并发送。
+
+![image](./images/quickstart-my_hello.jpeg)
+
+
+## 总结
+
+- 自定义工作流统一存放在`~/.chat/scripts/custom`目录下，通过命名空间进行管理，每个命名空间下可以有多个工作流。
+- 每个工作流由一个包含`command.yml`的目录组成，目录名即为工作流名。`command.yml`为工作流的定义文件。
+- 通过在 DevChat 聊天栏中发送以`/<workflow_name> `开头的消息触发工作流。
diff --git a/docs/user_settings.md b/docs/user_settings.md
new file mode 100644
index 0000000..d256f26
--- /dev/null
+++ b/docs/user_settings.md
@@ -0,0 +1,33 @@
+# 用户设置`user_settings.yml`
+
+`~/.chat/scripts/user_settings.yml`文件用于配置用户的个性化设置。
+
+## `external_workflow_python`
+ 
+在不能访问公网的环境下，DevChat Workflow Engine无法按照`command.yml`中定义的`workflow_python`自动创建 Python 环境。此时，需要用户自行准备好相应 Python 环境，并在`external_workflow_python`中配置。
+
+
+- `external_workflow_python.env_name`: 应与`command.yml`中的`workflow_python.env_name`一致。表示下面指定的 Python 将被用于<env_name>环境。
+- `external_workflow_python.python_bin`: 为用户准备的 Python 路径，用来替代`$workflow_python`运行 Python 脚本。
+
+
+#### 示例
+
+某工作流定义了独立的`workflow_python`配置：
+
+```yaml
+workflow_python:
+  env_name: foo-env
+  version: 3.12
+  dependencies: requirements.txt
+```
+
+在无法访问公网的环境下，需要用户（用其他手段）自行准备一个 Python 版本为3.12、并安装了`requirements.txt`中依赖包的环境。
+
+然后在`user_settings.yml`添加如下配置：
+
+```yaml
+external_workflow_python:
+  - env_name: foo-env
+    python_bin: path/to/the/user/prepared/python
+```
diff --git a/docs/workflow.md b/docs/workflow.md
new file mode 100644
index 0000000..076fee3
--- /dev/null
+++ b/docs/workflow.md
@@ -0,0 +1,77 @@
+# 工作流开发指南
+
+在[快速入门](./quickstart.md)中，我们创建了一个简单的DevChat Workflow。本文将展示更丰富的 DevChat Workflow 特性。
+
+
+## 多层级 Workflow
+
+工作流可随目录结构进行多层级扩展，用`.`连接各级目录组成子工作流的完整名称。
+
+例如，对于如下`custom`目录结构：
+
+```
+custom
+├── config.yml
+└── demo
+    ├── lang
+    │   ├── command.yml
+    │   ├── en
+    │   │   ├── command.yml
+    │   │   └── main.py
+    │   ├── jp
+    │   │   ├── command.yml
+    │   │   └── main.py
+    │   └── main.py
+    └── my_hello
+        └── command.yml
+```
+当`demo`被注册为命名空间后，4个`command.yml`文件分别对应4个工作流：
+- `/lang`
+- `/lang.en`
+- `/lang.jp`
+- `/my_hello`
+
+`/lang.en` 和 `/lang.jp` 便是`lang`下的子工作流。
+
+TODO: 引用example 
+
+### 多层级 Workflow 的 workflow_python 环境共用
+
+上级目录中`command.yml`里定义的`workflow_python`环境可在其子工作流中直接使用。子工作流也可另行定义自己单独的`workflow_python`环境。
+
+但上级工作流无法使用子工作流中定义的`workflow_python`环境。`workflow_python`环境也不支持跨目录引用。
+
+
+TODO: 引用example
+
+
+## ChatMark: 在消息中进行用户交互的标记语法
+
+语法介绍：
+- [chatmark](https://github.com/devchat-ai/devchat-docs/blob/main/docs/specs/chatmark.md)
+
+
+### Python 封装
+
+为了方便开发者在 Python 脚本中使用 ChatMark，我们提供了 ChatMark Python 封装。
+- [ChatMark Python](../lib/chatmark/README.md)
+- [使用示例](../lib/chatmark/chatmark_example/main.py)
+
+
+## IDE Service Protocol：在工作流中与编辑器交互的协议
+
+[IDE Service Protocol 介绍](https://merico.feishu.cn/wiki/A3LCwOUE8igbHRkhqE5cviJunyd)
+
+TODO: 有些新接口没写到文档里，待补充
+
+
+### Python 封装
+
+为了方便开发者在 Python 脚本中使用 IDE Service，我们提供了IDE Service Python 封装。
+
+- [IDE Service Python](../lib/ide_service/service.py)
+
+
+## 其他示例
+
+TODO:
\ No newline at end of file