diff --git a/.env.example b/.env.example
index d037e01b..e345eff5 100644
--- a/.env.example
+++ b/.env.example
@@ -1,87 +1,94 @@
 # =============================================================================
-# 商务对接智能体系统 (Chat-Agent-System) - 开发环境配置文件模板 (.env.example)
+# 商务对接智能体系统 (Chat-Agent-System) - 环境配置模板 (.env.example)
+#
+# 使用说明：
+#   1. 复制为 .env 并填写密钥：cp .env.example .env && chmod 600 .env
+#   2. 本文件供 Go 后端 (bin/server)、launch.sh 默认 compose 变量替换使用
+#   3. 若通过 ./scripts/env-service.sh dev start 启容器，还需同步密钥到 configs/.env.dev
+#      （见 configs/.env.dev.example 第 6 节）
 # =============================================================================
 
 # --- 1. 运行环境与基础目录 ---
 ENV=dev
+COMPOSE_PROJECT_NAME=agent-dev
 DATA_DIR=./data/dev
 APP_PUBLISH_HOST=127.0.0.1
 HTTP_PORT=8080
 
-# --- 2. 智能体后端调度配置 ---
+# --- 2. 智能体后端调度（Go 宿主进程 / 容器 app 服务）---
 # 可选值: pi-agent | cursor-cli | stub
 AGENT_BACKEND=pi-agent
 AGENT_TIMEOUT=30m
+MAX_CONCURRENT_AGENTS=8
 
-# --- 3. Cursor CLI / SDK 后端配置 ---
-# Cursor API Key (格式通常为 crsr_...)
+# --- 3. Cursor CLI / SDK 后端 ---
 CURSOR_API_KEY=
-# 模型选择 (auto, claude-3-7-sonnet, gpt-4o 等)
 CURSOR_MODEL=auto
-# Cursor 可执行程序路径
 CURSOR_BIN=/usr/local/bin/cursor
-# Cursor Node 桥接脚本路径
 CURSOR_BRIDGE_BIN=tools/cursor-bridge/index.mjs
+CURSOR_RUNNER_PORT=18765
 
-# --- 4. Pi-Agent 容器与模型参数配置 (MiniMax-M3) ---
-# 1) ENDPOINT URL (MiniMax API 地址)
+# --- 4. Pi-Agent 容器与 MiniMax 模型（pi-agent 容器 entrypoint 读取）---
 MINIMAX_ENDPOINT_URL=https://api.minimaxi.com/v1
-# 2) API TOKEN (用户自行设定，必填)
 MINIMAX_API_KEY=
-# 3) MODEL ID (模型名称)
 MINIMAX_MODEL_ID=MiniMax-M3
-# 4) API 协议类型 (openai-compatible 兼容协议)
 MINIMAX_API_TYPE=openai-compatible
 
-# --- 5. 网络搜索工具配置 (Tavily Search API Key 池) ---
-# 支持单 Key 或多 Key 池 (逗号/分号/换行分隔，例如: tvly-xxx1,tvly-xxx2,tvly-xxx3)
-# 当遇到 429 配额耗尽或 401/403 异常时，容器内的 Tavily 工具会自动轮询切换下一个 Key
+# --- 5. Tavily 联网搜索（pi-agent 容器内工具；多 Key 逗号分隔）---
 TAVILY_API_KEYS=
 
-# --- 6. Pi-Agent 容器服务端口与远程调用 (可选) ---
+# --- 6. Pi-Agent Runner 远程调用（Go 宿主连容器时使用）---
 PI_AGENT_RUNNER_PORT=18865
-# 若希望 Go 程序通过 HTTP 直连 pi-agent 容器，解除下方注释；若留空则走本机本地 pi CLI
+# 宿主 bin/server 直连本机 pi-agent 容器时启用；容器内 app 服务由 compose 注入 http://pi-agent:18865
 # PI_AGENT_RUNNER_URL=http://127.0.0.1:18865
-# Runner 服务间认证（生产必填；app 与 pi-agent 容器需相同值）
-# RUNNER_AUTH_TOKEN=change-me-in-production
+# Runner 服务间认证（main 必填；dev 可留空）
+# RUNNER_AUTH_TOKEN=
 
-# --- 7. 本机 Pi CLI 本地回退配置 (当不使用容器时) ---
+# --- 7. 本机 Pi CLI 回退（不使用容器 runner 时）---
 PI_AGENT_BIN=/opt/homebrew/bin/pi
 PI_AGENT_BRIDGE_BIN=tools/pi-bridge/index.mjs
 PI_AGENT_PROVIDER=minimax
 PI_AGENT_MODEL=MiniMax-M3
 
-# --- 8. 法规知识库配置 (复用已有 agent-regkb Docker 容器) ---
+# --- 8. 共享法规知识库（宿主 Go 进程：127.0.0.1:5432；容器 app：compose 注入 shuimu-kb-shared）---
 KB_DB_HOST=127.0.0.1
-KB_DB_PORT=55432
+KB_DB_PORT=5432
 KB_DB_USER=regkb
 KB_DB_PASSWORD=shared_kb_secret_pass
 KB_DB_NAME=regulations
 
-# 向量检索 Embedding 配置 (复用原系统配置，用于合规检索条目召回)
+# --- 9. 向量 Embedding / Reranker（Go 宿主 KB 检索；容器 app 当前未透传，宿主模式必填）---
 EMBEDDING_ENDPOINT_URL=https://www.dmxapi.cn/v1/embeddings
 EMBEDDING_PROVIDER=openai_compatible
 EMBEDDING_MODEL=bge-m3
 EMBEDDING_API_KEY=
 
-# 重排 Reranker 配置
 RERANKER_ENDPOINT_URL=https://www.dmxapi.cn/v1/rerank
 RERANKER_PROVIDER=openai_compatible
 RERANKER_MODEL=bge-reranker-v2-m3-free
 RERANKER_API_KEY=
 
-# --- 9. 系统管理员与认证准入配置 ---
-# 超级管理员凭据 (系统启动时自动初始化为 role-admin)
+# --- 10. 专属业务/上下文库（Go 宿主：CONTEXT_DB_*；compose 同时认 SYSTEM_DB_* 别名）---
+CONTEXT_DB_HOST=127.0.0.1
+CONTEXT_DB_PORT=5433
+CONTEXT_DB_USER=app
+CONTEXT_DB_PASSWORD=dev_secret_db_pass
+CONTEXT_DB_NAME=agent_system_dev
+
+# docker-compose.dev.yml 变量别名（与 CONTEXT_DB_* 保持一致）
+SYSTEM_DB_USER=app
+SYSTEM_DB_PASSWORD=dev_secret_db_pass
+SYSTEM_DB_NAME=agent_system_dev
+SYSTEM_DB_PUBLISH_PORT=5433
+
+# --- 11. 系统管理员与认证准入 ---
 ADMIN_USERNAME=admin
 ADMIN_PASSWORD=admin-secret-password-123
-
-# 全局准入策略 (是否开放自主注册与注册是否必须审批)
 AUTH_REGISTRATION_ENABLED=true
 AUTH_REQUIRE_APPROVAL=false
 
-# CORS 允许来源（逗号分隔）；main 环境必须显式配置，禁止 *
-# dev/test 未配置时使用 localhost 默认值
+# --- 12. 可选：CORS / 内存降级 ---
+# dev/test 未配置时 CORS 由代码填充 localhost 默认值
 # CORS_ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:8080
-
-# 生产环境必须为 false；main 启动时若 true 将拒绝加载配置
+# 生产必须为 false；main 启动时若 true 将拒绝加载
 # ALLOW_IN_MEMORY=false
diff --git a/configs/.env.dev.example b/configs/.env.dev.example
index e8fe5d25..6fdbf039 100644
--- a/configs/.env.dev.example
+++ b/configs/.env.dev.example
@@ -1,6 +1,11 @@
 # =============================================================================
-# 开发环境 (dev) 环境变量配置模板 (configs/.env.dev)
-# 作用域：dev 分支及 feature/* 子分支日常开发调试
+# 开发环境 Compose 专用配置模板 (configs/.env.dev)
+# 作用域：./scripts/env-service.sh dev * 与 docker compose --env-file configs/.env.dev
+#
+# 重要：本文件与根目录 .env 分工不同
+#   - 根 .env     → Go bin/server、launch.sh 默认 compose
+#   - 本文件      → env-service.sh 启停 dev 容器组
+# 密钥（MINIMAX_API_KEY / TAVILY_API_KEYS 等）须与根 .env 保持一致，否则 pi-agent 容器无 Token！
 # =============================================================================
 
 ENV=dev
@@ -12,25 +17,33 @@ APP_PUBLISH_HOST=127.0.0.1
 ADMIN_TOKEN=dev-admin-token-change-me
 ALLOW_INSECURE_ADMIN=1
 
-# 2. 对话数据与工作区隔离目录 (禁止跨环境共享)
+# 2. 对话数据与工作区（禁止跨环境共享）
 DATA_DIR=./data/dev
 AUX_FILE_DSN=file:/var/lib/feishu/outbox_dev.db?_journal_mode=WAL&_busy_timeout=5000
 
-# 3. 开发环境专属数据库 (禁止与 test/main 共享)
+# 3. 开发环境专属数据库
 SYSTEM_DB_USER=app
 SYSTEM_DB_PASSWORD=dev_secret_db_pass
 SYSTEM_DB_NAME=agent_system_dev
 SYSTEM_DB_PUBLISH_PORT=5433
 
-# 4. 共享知识库连接 (只读检索共享数据)
+# 4. 共享知识库（容器 app 经 shuimu-kb-shared 访问）
 KB_DB_USER=regkb
 KB_DB_PASSWORD=shared_kb_secret_pass
 KB_DB_NAME=regulations
-# 容器间网络域名 (shuimu-kb-shared) 或 宿主访问 127.0.0.1:5432
 KB_DB_HOST=shuimu-kb-shared
 KB_DB_PORT=5432
 
-# 5. Cursor / LLM Agent Runner 服务
+# 5. Agent 后端与 Runner 端口
 CURSOR_RUNNER_PORT=18765
-AGENT_BACKEND=stub
-AGENT_TIMEOUT=30m
+PI_AGENT_RUNNER_PORT=18865
+AGENT_BACKEND=pi-agent
+AGENT_TIMEOUT=60m
+
+# 6. Pi-Agent / MiniMax / Tavily（pi-agent 容器必填；从根 .env 复制）
+MINIMAX_ENDPOINT_URL=https://api.minimaxi.com/v1
+MINIMAX_API_KEY=
+MINIMAX_MODEL_ID=MiniMax-M3
+MINIMAX_API_TYPE=openai-compatible
+TAVILY_API_KEYS=
+# RUNNER_AUTH_TOKEN=