diff --git a/README.md b/README.md
index 37fe327..31b1169 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,180 @@
 # gori-agent
 
+通过 QQ 等 IM 调用 ACP Coding Agent。当前默认后端是 Kimi Code：
+
+```text
+用户 → QQ → gori-agent Gateway → ACP → Kimi Code → 工具/脚本 → QQ
+```
+
+## 五分钟上手
+
+### 1. 准备 Kimi Code
+
+确认 Kimi Code 已登录且 ACP 可用：
+
+```bash
+kimi --version
+kimi doctor
+kimi acp --help
+```
+
+ACP 使用 `~/.kimi-code/config.toml` 中的 `default_model`。模型切换应先在 Kimi Code 中完成，再重启 gori-agent；已有聊天要使用新模型时，在 QQ 中发送 `/new` 创建新 session。
+
+### 2. 构建并迁移配置
+
+```bash
+cd /home/ubuntu/gori-space/gori-agent
+npm install
+npm run build
+./gori-agent.sh setup --config ./config.json
+```
+
+建议向导选择：
+
+```text
+Assistant workspace: /home/ubuntu/gori-space/gori-agent
+Include ops role with the existing gori-update skill: yes
+Write config: yes
+```
+
+迁移会把旧的 `kimi -p` 改为 `kimi acp`，并完整保留已有 QQ appId、secret 和连接模式。
+
+### 3. 检查配置
+
+```bash
+./gori-agent.sh discover-backends --config ./config.json
+./gori-agent.sh doctor --config ./config.json
+```
+
+预期看到 Kimi ACP `ready`，并支持 session `load/resume`。
+
+### 4. 前台启动并从 QQ 验收
+
+```bash
+./gori-agent.sh start --config ./config.json
+```
+
+启动日志应包含：
+
+```text
+QQ websocket connected
+QQ websocket ready
+```
+
+在 QQ 群中 @bot 并发送：
+
+```text
+/status
+/roles
+/role assistant
+只读回答当前工作目录，不要修改文件
+```
+
+运维角色先做只读测试：
+
+```text
+/role ops
+/status
+请只读取并概述 gori-update skill，不要 pull、构建或部署
+```
+
+常用聊天命令：
+
+```text
+/roles          列出角色
+/role <id>      切换角色
+/status         查看当前 role/workspace/session 状态
+/cancel         取消正在执行的任务
+/new            为当前角色创建新的 Agent session
+```
+
+同一个 `平台 + chat + role` 会持续使用同一个 Kimi session；Gateway 或 ACP 子进程重启后会恢复。不同 role 的 session 相互独立。
+
+### 5. 后台运行
+
+前台验收通过后：
+
+```bash
+export GORI_AGENT_HOME=/home/ubuntu/.gori-agent
+./gori-agent.sh start-daemon --config ./config.json
+./gori-agent.sh status --config ./config.json
+./gori-agent.sh logs
+./gori-agent.sh stop
+```
+
+运行状态和日志位于：
+
+```text
+/home/ubuntu/.gori-agent/state/
+/home/ubuntu/.gori-agent/logs/gori-agent.log
+```
+
+`config.json` 包含 IM secret，不要提交，建议执行：
+
+```bash
+chmod 600 config.json
+```
+
+## 配置角色
+
+角色定义在 `config.json` 的 `roles[]` 中：
+
+```json
+{
+  "id": "ops",
+  "backend": "kimi",
+  "workspace": "/home/ubuntu/gori-space",
+  "persona": "你是 Gori 团队运维角色，严格遵循 gori-update skill。",
+  "skills": ["gori-update"],
+  "policy": {
+    "permissionMode": "allowlist",
+    "allowedTools": ["read", "grep", "glob", "bash"],
+    "allowedCommandPatterns": ["允许的命令正则"]
+  }
+}
+```
+
+- `backend`：ACP 后端 ID，默认 `kimi`。
+- `workspace`：该角色的工作目录，必须是绝对路径。
+- `persona`：角色职责。
+- `skills`：引用顶层 `skills[]` 中的 SKILL.md。
+- `permissionMode`：`deny` 全拒绝；`allowlist` 按工具和命令规则放行；`auto` 全放行（高风险）。
+
+修改 persona、workspace、skill 内容或 policy 后，角色 fingerprint 会变化；下一条消息会创建新的 native session，避免沿用旧角色上下文。
+
+## 配置 QQ
+
+`config.json` 的最小 QQ websocket 配置：
+
+```json
+{
+  "policy": {
+    "allowedUsers": [],
+    "allowedChats": [],
+    "requireMentionInGroup": true
+  },
+  "platforms": {
+    "qq": {
+      "enabled": true,
+      "connectionMode": "websocket",
+      "appId": "你的 AppID",
+      "clientSecret": "你的 ClientSecret",
+      "botSecret": "",
+      "verifySignature": true,
+      "botNames": ["你的机器人名称"],
+      "intents": 33554432,
+      "shard": [0, 1]
+    }
+  }
+}
+```
+
+初次测试可让 `allowedUsers` 和 `allowedChats` 为空；正式运维 bot 应限制到指定用户或群。群聊 chat ID 的格式为 `group:<group_openid>`。
+
+---
+
+## Detailed reference
+
 Multi-IM gateway that drives coding agents through the official Agent Client Protocol (ACP):
 
 ```text