diff --git a/configs/.env.dev.example b/configs/.env.dev.example
new file mode 100644
index 00000000..e8fe5d25
--- /dev/null
+++ b/configs/.env.dev.example
@@ -0,0 +1,36 @@
+# =============================================================================
+# 开发环境 (dev) 环境变量配置模板 (configs/.env.dev)
+# 作用域：dev 分支及 feature/* 子分支日常开发调试
+# =============================================================================
+
+ENV=dev
+COMPOSE_PROJECT_NAME=agent-dev
+
+# 1. 业务 HTTP 服务
+HTTP_PORT=8080
+APP_PUBLISH_HOST=127.0.0.1
+ADMIN_TOKEN=dev-admin-token-change-me
+ALLOW_INSECURE_ADMIN=1
+
+# 2. 对话数据与工作区隔离目录 (禁止跨环境共享)
+DATA_DIR=./data/dev
+AUX_FILE_DSN=file:/var/lib/feishu/outbox_dev.db?_journal_mode=WAL&_busy_timeout=5000
+
+# 3. 开发环境专属数据库 (禁止与 test/main 共享)
+SYSTEM_DB_USER=app
+SYSTEM_DB_PASSWORD=dev_secret_db_pass
+SYSTEM_DB_NAME=agent_system_dev
+SYSTEM_DB_PUBLISH_PORT=5433
+
+# 4. 共享知识库连接 (只读检索共享数据)
+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 服务
+CURSOR_RUNNER_PORT=18765
+AGENT_BACKEND=stub
+AGENT_TIMEOUT=30m
diff --git a/configs/.env.main.example b/configs/.env.main.example
new file mode 100644
index 00000000..04c39648
--- /dev/null
+++ b/configs/.env.main.example
@@ -0,0 +1,35 @@
+# =============================================================================
+# 生产/主分支环境 (main) 环境变量配置模板 (configs/.env.main)
+# 作用域：main 分支正式线上发布与生产运营
+# =============================================================================
+
+ENV=prod
+COMPOSE_PROJECT_NAME=agent-main
+
+# 1. 业务 HTTP 服务
+HTTP_PORT=8000
+APP_PUBLISH_HOST=0.0.0.0
+ADMIN_TOKEN=main-prod-admin-token-super-secure
+ALLOW_INSECURE_ADMIN=0
+
+# 2. 对话数据与工作区隔离目录 (禁止跨环境共享)
+DATA_DIR=./data/main
+AUX_FILE_DSN=file:/var/lib/feishu/outbox_main.db?_journal_mode=WAL&_busy_timeout=5000
+
+# 3. 生产环境专属数据库 (禁止与 dev/test 共享)
+SYSTEM_DB_USER=app
+SYSTEM_DB_PASSWORD=prod_highly_secure_db_pass
+SYSTEM_DB_NAME=agent_system_main
+SYSTEM_DB_PUBLISH_PORT=5435
+
+# 4. 共享知识库连接 (只读检索共享数据)
+KB_DB_USER=regkb
+KB_DB_PASSWORD=shared_kb_secret_pass
+KB_DB_NAME=regulations
+KB_DB_HOST=shuimu-kb-shared
+KB_DB_PORT=5432
+
+# 5. Cursor / LLM Agent Runner 服务
+CURSOR_RUNNER_PORT=18767
+AGENT_BACKEND=stub
+AGENT_TIMEOUT=60m
diff --git a/configs/.env.shared.example b/configs/.env.shared.example
new file mode 100644
index 00000000..518679f8
--- /dev/null
+++ b/configs/.env.shared.example
@@ -0,0 +1,13 @@
+# =============================================================================
+# 共享基础设施环境变量配置模板 (configs/.env.shared)
+# 作用域：所有分支与环境共享的知识库、向量检索与底层公共网络
+# =============================================================================
+
+COMPOSE_PROJECT_NAME=agent-infra
+
+# 共享知识库 PostgreSQL (带 pgvector)
+KB_DB_USER=regkb
+KB_DB_PASSWORD=shared_kb_secret_pass
+KB_DB_NAME=regulations
+KB_PUBLISH_PORT=5432
+KB_DATA_DIR=./data/shared/kb
diff --git a/configs/.env.test.example b/configs/.env.test.example
new file mode 100644
index 00000000..78d67762
--- /dev/null
+++ b/configs/.env.test.example
@@ -0,0 +1,35 @@
+# =============================================================================
+# 测试环境 (test) 环境变量配置模板 (configs/.env.test)
+# 作用域：test 分支阶段集成、长期部署实测与运维验证
+# =============================================================================
+
+ENV=test
+COMPOSE_PROJECT_NAME=agent-test
+
+# 1. 业务 HTTP 服务
+HTTP_PORT=8081
+APP_PUBLISH_HOST=0.0.0.0
+ADMIN_TOKEN=test-admin-token-secure-key
+ALLOW_INSECURE_ADMIN=0
+
+# 2. 对话数据与工作区隔离目录 (禁止跨环境共享)
+DATA_DIR=./data/test
+AUX_FILE_DSN=file:/var/lib/feishu/outbox_test.db?_journal_mode=WAL&_busy_timeout=5000
+
+# 3. 测试环境专属数据库 (禁止与 dev/main 共享)
+SYSTEM_DB_USER=app
+SYSTEM_DB_PASSWORD=test_secret_db_pass
+SYSTEM_DB_NAME=agent_system_test
+SYSTEM_DB_PUBLISH_PORT=5434
+
+# 4. 共享知识库连接 (只读检索共享数据)
+KB_DB_USER=regkb
+KB_DB_PASSWORD=shared_kb_secret_pass
+KB_DB_NAME=regulations
+KB_DB_HOST=shuimu-kb-shared
+KB_DB_PORT=5432
+
+# 5. Cursor / LLM Agent Runner 服务
+CURSOR_RUNNER_PORT=18766
+AGENT_BACKEND=stub
+AGENT_TIMEOUT=60m
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
new file mode 100644
index 00000000..8aee114b
--- /dev/null
+++ b/docker-compose.dev.yml
@@ -0,0 +1,88 @@
+# =============================================================================
+# 开发环境编排 (Dev Branch Environment)
+# 特性：
+# 1. 独占系统业务库 (5433:5432) 与专属数据卷
+# 2. 独占对话记录、工作区及日志目录 (./data/dev)
+# 3. 共享连接知识库服务 (shuimu-kb-shared:5432)
+# =============================================================================
+name: agent-dev
+
+services:
+  system-db:
+    image: postgres:16-alpine
+    container_name: shuimu-system-pg-dev
+    command: ["postgres", "-c", "shared_buffers=256MB", "-c", "max_connections=100"]
+    environment:
+      POSTGRES_USER: ${SYSTEM_DB_USER:-app}
+      POSTGRES_PASSWORD: ${SYSTEM_DB_PASSWORD:-dev_secret_db_pass}
+      POSTGRES_DB: ${SYSTEM_DB_NAME:-agent_system_dev}
+    ports:
+      - "127.0.0.1:${SYSTEM_DB_PUBLISH_PORT:-5433}:5432"
+    volumes:
+      - dev-system-pgdata:/var/lib/postgresql/data
+      - ./deploy/postgres/system_init.sql:/docker-entrypoint-initdb.d/01-init.sql:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${SYSTEM_DB_USER:-app} -d ${SYSTEM_DB_NAME:-agent_system_dev}"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+    restart: unless-stopped
+    networks:
+      - dev-net
+
+  cursor-agent:
+    image: alpine:latest
+    container_name: shuimu-cursor-agent-dev
+    command: ["sh", "-c", "echo 'Dev Agent Runner is standby' && sleep infinity"]
+    environment:
+      CURSOR_RUNNER_ADDR: ":18765"
+      DATA_DIR: /app/data/workspaces
+    ports:
+      - "127.0.0.1:${CURSOR_RUNNER_PORT:-18765}:18765"
+    volumes:
+      - ./data/dev/workspaces:/app/data/workspaces
+    restart: unless-stopped
+    networks:
+      - dev-net
+
+  app:
+    image: alpine:latest
+    container_name: shuimu-agent-app-dev
+    command: ["sh", "-c", "echo 'Dev Agent App service is running on :8080' && sleep infinity"]
+    depends_on:
+      system-db:
+        condition: service_healthy
+    environment:
+      ENV: dev
+      HTTP_ADDR: ":${HTTP_PORT:-8080}"
+      DATA_DIR: /app/data
+      # 独占业务与对话库
+      APP_DB_DSN: postgres://${SYSTEM_DB_USER:-app}:${SYSTEM_DB_PASSWORD:-dev_secret_db_pass}@system-db:5432/${SYSTEM_DB_NAME:-agent_system_dev}?sslmode=disable
+      # 共享知识库
+      POSTGRES_SHARED_KB_DSN: postgres://${KB_DB_USER:-regkb}:${KB_DB_PASSWORD:-shared_kb_secret_pass}@shuimu-kb-shared:5432/${KB_DB_NAME:-regulations}?sslmode=disable
+      CURSOR_RUNNER_URL: http://cursor-agent:18765
+      AUX_FILE_DSN: file:/var/lib/feishu/outbox_dev.db?_journal_mode=WAL&_busy_timeout=5000
+    ports:
+      - "${APP_PUBLISH_HOST:-127.0.0.1}:${HTTP_PORT:-8080}:${HTTP_PORT:-8080}"
+    volumes:
+      # 独占对话记录与环境数据
+      - ./data/dev:/app/data
+      - dev-aux-sqlite-data:/var/lib/feishu
+    restart: unless-stopped
+    networks:
+      - dev-net
+      - shared-net
+
+networks:
+  dev-net:
+    name: chat-agent-dev-net
+    driver: bridge
+  shared-net:
+    name: chat-agent-shared-net
+    external: true
+
+volumes:
+  dev-system-pgdata:
+    name: agent-dev-system-pgdata
+  dev-aux-sqlite-data:
+    name: agent-dev-aux-sqlite-data
diff --git a/docker-compose.main.yml b/docker-compose.main.yml
new file mode 100644
index 00000000..84b3b1f5
--- /dev/null
+++ b/docker-compose.main.yml
@@ -0,0 +1,88 @@
+# =============================================================================
+# 主分支/生产环境编排 (Main Branch Production Environment)
+# 特性：
+# 1. 独占系统业务库 (5435:5432) 与专属高稳定性数据卷
+# 2. 独占生产对话记录、工作区及审计日志目录 (./data/main)
+# 3. 共享连接知识库服务 (shuimu-kb-shared:5432)
+# =============================================================================
+name: agent-main
+
+services:
+  system-db:
+    image: postgres:16-alpine
+    container_name: shuimu-system-pg-main
+    command: ["postgres", "-c", "shared_buffers=512MB", "-c", "max_connections=300"]
+    environment:
+      POSTGRES_USER: ${SYSTEM_DB_USER:-app}
+      POSTGRES_PASSWORD: ${SYSTEM_DB_PASSWORD:-prod_highly_secure_db_pass}
+      POSTGRES_DB: ${SYSTEM_DB_NAME:-agent_system_main}
+    ports:
+      - "127.0.0.1:${SYSTEM_DB_PUBLISH_PORT:-5435}:5432"
+    volumes:
+      - main-system-pgdata:/var/lib/postgresql/data
+      - ./deploy/postgres/system_init.sql:/docker-entrypoint-initdb.d/01-init.sql:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${SYSTEM_DB_USER:-app} -d ${SYSTEM_DB_NAME:-agent_system_main}"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+    restart: always
+    networks:
+      - main-net
+
+  cursor-agent:
+    image: alpine:latest
+    container_name: shuimu-cursor-agent-main
+    command: ["sh", "-c", "echo 'Main/Prod Agent Runner is running' && sleep infinity"]
+    environment:
+      CURSOR_RUNNER_ADDR: ":18767"
+      DATA_DIR: /app/data/workspaces
+    ports:
+      - "127.0.0.1:${CURSOR_RUNNER_PORT:-18767}:18767"
+    volumes:
+      - ./data/main/workspaces:/app/data/workspaces
+    restart: always
+    networks:
+      - main-net
+
+  app:
+    image: alpine:latest
+    container_name: shuimu-agent-app-main
+    command: ["sh", "-c", "echo 'Main/Prod Agent App service is running on :8000' && sleep infinity"]
+    depends_on:
+      system-db:
+        condition: service_healthy
+    environment:
+      ENV: prod
+      HTTP_ADDR: ":${HTTP_PORT:-8000}"
+      DATA_DIR: /app/data
+      # 独占生产业务与对话库
+      APP_DB_DSN: postgres://${SYSTEM_DB_USER:-app}:${SYSTEM_DB_PASSWORD:-prod_highly_secure_db_pass}@system-db:5432/${SYSTEM_DB_NAME:-agent_system_main}?sslmode=disable
+      # 共享知识库
+      POSTGRES_SHARED_KB_DSN: postgres://${KB_DB_USER:-regkb}:${KB_DB_PASSWORD:-shared_kb_secret_pass}@shuimu-kb-shared:5432/${KB_DB_NAME:-regulations}?sslmode=disable
+      CURSOR_RUNNER_URL: http://cursor-agent:18767
+      AUX_FILE_DSN: file:/var/lib/feishu/outbox_main.db?_journal_mode=WAL&_busy_timeout=5000
+    ports:
+      - "${APP_PUBLISH_HOST:-0.0.0.0}:${HTTP_PORT:-8000}:${HTTP_PORT:-8000}"
+    volumes:
+      # 独占生产对话记录与环境数据
+      - ./data/main:/app/data
+      - main-aux-sqlite-data:/var/lib/feishu
+    restart: always
+    networks:
+      - main-net
+      - shared-net
+
+networks:
+  main-net:
+    name: chat-agent-main-net
+    driver: bridge
+  shared-net:
+    name: chat-agent-shared-net
+    external: true
+
+volumes:
+  main-system-pgdata:
+    name: agent-main-system-pgdata
+  main-aux-sqlite-data:
+    name: agent-main-aux-sqlite-data
diff --git a/docker-compose.shared.yml b/docker-compose.shared.yml
new file mode 100644
index 00000000..7cb19a7e
--- /dev/null
+++ b/docker-compose.shared.yml
@@ -0,0 +1,36 @@
+# =============================================================================
+# 共享基础设施编排：知识库 (Knowledge Base) 服务
+# 三个分支 (dev / test / main) 共享同一个知识库向量检索服务
+# =============================================================================
+name: agent-infra
+
+services:
+  shared-kb-db:
+    image: pgvector/pgvector:pg16
+    container_name: shuimu-kb-shared
+    environment:
+      POSTGRES_USER: ${KB_DB_USER:-regkb}
+      POSTGRES_PASSWORD: ${KB_DB_PASSWORD:-shared_kb_secret_pass}
+      POSTGRES_DB: ${KB_DB_NAME:-regulations}
+    ports:
+      - "127.0.0.1:${KB_PUBLISH_PORT:-5432}:5432"
+    volumes:
+      - shared-kb-pgdata:/var/lib/postgresql/data
+      - ./deploy/postgres/kb_init.sql:/docker-entrypoint-initdb.d/01-init.sql:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${KB_DB_USER:-regkb} -d ${KB_DB_NAME:-regulations}"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+    restart: unless-stopped
+    networks:
+      - shared-net
+
+networks:
+  shared-net:
+    name: chat-agent-shared-net
+    driver: bridge
+
+volumes:
+  shared-kb-pgdata:
+    name: chat-agent-shared-kb-pgdata
diff --git a/docker-compose.test.yml b/docker-compose.test.yml
new file mode 100644
index 00000000..92a25e38
--- /dev/null
+++ b/docker-compose.test.yml
@@ -0,0 +1,88 @@
+# =============================================================================
+# 测试环境编排 (Test Branch Environment)
+# 特性：
+# 1. 独占系统业务库 (5434:5432) 与专属数据卷
+# 2. 独占对话记录、工作区及日志目录 (./data/test)
+# 3. 共享连接知识库服务 (shuimu-kb-shared:5432)
+# =============================================================================
+name: agent-test
+
+services:
+  system-db:
+    image: postgres:16-alpine
+    container_name: shuimu-system-pg-test
+    command: ["postgres", "-c", "shared_buffers=256MB", "-c", "max_connections=150"]
+    environment:
+      POSTGRES_USER: ${SYSTEM_DB_USER:-app}
+      POSTGRES_PASSWORD: ${SYSTEM_DB_PASSWORD:-test_secret_db_pass}
+      POSTGRES_DB: ${SYSTEM_DB_NAME:-agent_system_test}
+    ports:
+      - "127.0.0.1:${SYSTEM_DB_PUBLISH_PORT:-5434}:5432"
+    volumes:
+      - test-system-pgdata:/var/lib/postgresql/data
+      - ./deploy/postgres/system_init.sql:/docker-entrypoint-initdb.d/01-init.sql:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${SYSTEM_DB_USER:-app} -d ${SYSTEM_DB_NAME:-agent_system_test}"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+    restart: unless-stopped
+    networks:
+      - test-net
+
+  cursor-agent:
+    image: alpine:latest
+    container_name: shuimu-cursor-agent-test
+    command: ["sh", "-c", "echo 'Test Agent Runner is standby' && sleep infinity"]
+    environment:
+      CURSOR_RUNNER_ADDR: ":18766"
+      DATA_DIR: /app/data/workspaces
+    ports:
+      - "127.0.0.1:${CURSOR_RUNNER_PORT:-18766}:18766"
+    volumes:
+      - ./data/test/workspaces:/app/data/workspaces
+    restart: unless-stopped
+    networks:
+      - test-net
+
+  app:
+    image: alpine:latest
+    container_name: shuimu-agent-app-test
+    command: ["sh", "-c", "echo 'Test Agent App service is running on :8081' && sleep infinity"]
+    depends_on:
+      system-db:
+        condition: service_healthy
+    environment:
+      ENV: test
+      HTTP_ADDR: ":${HTTP_PORT:-8081}"
+      DATA_DIR: /app/data
+      # 独占测试业务与对话库
+      APP_DB_DSN: postgres://${SYSTEM_DB_USER:-app}:${SYSTEM_DB_PASSWORD:-test_secret_db_pass}@system-db:5432/${SYSTEM_DB_NAME:-agent_system_test}?sslmode=disable
+      # 共享知识库
+      POSTGRES_SHARED_KB_DSN: postgres://${KB_DB_USER:-regkb}:${KB_DB_PASSWORD:-shared_kb_secret_pass}@shuimu-kb-shared:5432/${KB_DB_NAME:-regulations}?sslmode=disable
+      CURSOR_RUNNER_URL: http://cursor-agent:18766
+      AUX_FILE_DSN: file:/var/lib/feishu/outbox_test.db?_journal_mode=WAL&_busy_timeout=5000
+    ports:
+      - "${APP_PUBLISH_HOST:-0.0.0.0}:${HTTP_PORT:-8081}:${HTTP_PORT:-8081}"
+    volumes:
+      # 独占对话记录与环境数据
+      - ./data/test:/app/data
+      - test-aux-sqlite-data:/var/lib/feishu
+    restart: unless-stopped
+    networks:
+      - test-net
+      - shared-net
+
+networks:
+  test-net:
+    name: chat-agent-test-net
+    driver: bridge
+  shared-net:
+    name: chat-agent-shared-net
+    external: true
+
+volumes:
+  test-system-pgdata:
+    name: agent-test-system-pgdata
+  test-aux-sqlite-data:
+    name: agent-test-aux-sqlite-data