feat(文档): 接入 VitePress 与 GitHub Pages 部署

- 添加 VitePress 配置、文档构建脚本与 Pages workflow
- 修复架构文档运行流程图链接，并补充本地预览说明

feat(agent-runtime): 支持 Python venv 沙箱执行命令

- 新增 python-runtime 工具并接入 workspace 工厂
- 补充 requirements.txt 与开发环境 venv 自动检测

fix(web): 修复空会话列表与会话用量展示问题

- 无历史会话时自动创建首个会话
- 修正 TaskConsole 中 sessionView 的重复引用

Author: wangjk9527

.env.example

@@ -13,6 +13,11 @@ EMBEDDING_OUTPUT_TYPE=dense
 EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
 EMBEDDING_API_KEY=
 
+# Agent execute_command sandbox: Python venv with numpy/pandas/matplotlib/scikit-learn.
+# Default auto-detects repo `.venv` (also checks npm INIT_CWD). Override with absolute path:
+# WORKSPACE_PYTHON_VENV=/path/to/dataagent/.venv
+# WORKSPACE_COMMAND_TIMEOUT_MS=120000
+
 STORAGE_ROOT_DIR=storage
 METADATA_DB_PATH=storage/metadata/workbench.sqlite
 SECRET_MASTER_KEY=replace-with-a-long-random-local-key

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+      - "package.json"
+      - "package-lock.json"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build docs
+        run: npm run docs:build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,5 @@
+.venv/
+venv/
 node_modules/
 **/node_modules/
 dist/
@@ -15,5 +17,6 @@ storage/
 .env.*
 !.env.example
 *.tsbuildinfo
-package-lock.json.win.bak
-package-lock.json.*.bak
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+docs/public/assets/

apps/web/src/app/data-tasks/components/task-console/TaskConsole.tsx

@@ -509,6 +509,10 @@ function ConclusionZone({
       ? `${Math.round((runUsage.toolCalls.success / runUsage.toolCalls.total) * 100)}%`
       : "—";
 
+  const sessionView = useMemo(
+    () => deriveLiveSessionView(sessionUsage, liveRun),
+    [liveRun, sessionUsage],
+  );
   const tokenReported = sessionView.tokenUsageReported;
   const displayTokens = sessionView.tokens;
   const displayModels = sessionView.models;

apps/web/src/app/data-tasks/page.tsx

@@ -710,6 +710,9 @@ function DataTaskWorkspace({
       .then((response) => {
         if (cancelled) return;
         if (response.sessions.length === 0) {
+          const first = createChatSession();
+          setSessions([first]);
+          setActiveSessionId(first.id);
           setSessionSyncError(null);
           return;
         }

docs/.vitepress/config.ts

@@ -0,0 +1,63 @@
+import { defineConfig } from "vitepress";
+
+export default defineConfig({
+  title: "Open Data Agent",
+  description: "面向数据分析场景的 AI 工作台文档",
+  lang: "zh-CN",
+  base: "/dataagent/",
+  srcDir: ".",
+  srcExclude: ["README.md", "assets/**"],
+  cleanUrls: false,
+  themeConfig: {
+    logo: "/assets/readme/hero.svg",
+    siteTitle: "Open Data Agent",
+    nav: [
+      { text: "产品概览", link: "/zh/overview" },
+      { text: "快速开始", link: "/zh/quick-start" },
+      { text: "GitHub", link: "https://github.com/datagallery-lab/dataagent" }
+    ],
+    sidebar: [
+      {
+        text: "入门",
+        items: [
+          { text: "文档首页", link: "/zh/" },
+          { text: "产品概览", link: "/zh/overview" },
+          { text: "快速开始", link: "/zh/quick-start" },
+          { text: "能力全览", link: "/zh/capabilities" }
+        ]
+      },
+      {
+        text: "使用指南",
+        items: [
+          { text: "Web 工作台", link: "/zh/guides/web-workbench" },
+          { text: "TUI", link: "/zh/guides/tui" },
+          { text: "数据源", link: "/zh/guides/data-sources" }
+        ]
+      },
+      {
+        text: "参考",
+        items: [
+          { text: "支持的数据源", link: "/zh/reference/supported-datasources" },
+          { text: "REST API", link: "/zh/reference/rest-api" },
+          { text: "配置 API", link: "/zh/reference/configuration-api" },
+          { text: "Agent Runtime", link: "/zh/reference/agent-runtime" }
+        ]
+      },
+      {
+        text: "架构与安全",
+        items: [
+          { text: "架构概览", link: "/zh/architecture/overview" },
+          { text: "安全说明", link: "/zh/security" }
+        ]
+      }
+    ],
+    socialLinks: [{ icon: "github", link: "https://github.com/datagallery-lab/dataagent" }],
+    search: {
+      provider: "local"
+    },
+    footer: {
+      message: "Apache-2.0 Licensed",
+      copyright: "Copyright © DataGallery Lab"
+    }
+  }
+});

docs/README.md

@@ -34,3 +34,19 @@
 - 不保留来源敏感叙述。
 - 修改文档后运行 `npm run smoke:docs`。
 
+## 本地预览与 GitHub Pages
+
+本地预览：
+
+```bash
+npm run docs:dev
+npm run docs:build
+npm run docs:preview
+```
+
+推送到 `main` 后，`.github/workflows/docs.yml` 会把站点发布到 GitHub Pages：
+
+`https://datagallery-lab.github.io/dataagent/`
+
+私有仓库需要先启用 GitHub Pages（Settings → Pages → Source 选 **GitHub Actions**），并确认当前 GitHub 计划允许私有仓使用 Pages；站点是否对外公开可在 Pages 设置里单独控制。
+

docs/index.md

@@ -0,0 +1,21 @@
+---
+layout: home
+hero:
+  name: Open Data Agent
+  text: 中文文档
+  tagline: 面向数据分析场景的 AI 工作台
+  actions:
+    - theme: brand
+      text: 开始阅读
+      link: /zh/
+    - theme: alt
+      text: 快速开始
+      link: /zh/quick-start
+features:
+  - title: 本地优先
+    details: 在本地运行 Web 工作台、TUI 与后端 Runtime，数据与凭据留在你的环境内。
+  - title: 只读 SQL 边界
+    details: Agent 先理解 schema，再在受控策略下执行只读查询，过程可追溯。
+  - title: 统一工作台
+    details: 自然语言提问、数据源管理、分析追溯与产出沉淀在同一工作流中完成。
+---

docs/zh/architecture/overview.md

@@ -13,7 +13,7 @@ Web 工作台 / TUI / 其他客户端
   -> Metadata 与审计存储
 ```
 
-精选架构图可参考仓库首页使用的运行流程图：[`docs/assets/readme/runtime-flow.png`](../../assets/readme/runtime-flow.png)。
+精选架构图可参考仓库首页使用的运行流程图：[`docs/assets/readme/runtime-flow.svg`](../../assets/readme/runtime-flow.svg)。
 
 ## 主要模块