docs(web): 整理文档结构并优化工作台左侧面板布局

- 将散落的设计/实现文档迁入 .docs-internal，完善 docs/zh 与安全说明
- 支持左侧面板拖拽调整宽度，更新 AGENTS 与链接校验脚本

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: wangjk9527

.docs-internal/README.md

@@ -0,0 +1,43 @@
+# Internal Documentation
+
+工程契约、设计说明与 ADR。供贡献者与 AI Agent 阅读，不是公开文档入口。
+
+公开文档见 [docs/README.md](../docs/README.md)。
+
+## 维护规则
+
+- 不包含凭据、个人路径、个人信息或来源敏感描述。
+- 公开文档（`docs/`、`README*.md`）不得链接本目录。
+- 修改文档后运行 `npm run smoke:docs`。
+
+## 工程契约
+
+| 文档 | 说明 |
+| --- | --- |
+| [copilotkit-ag-ui-frontend-protocol.md](engineering/copilotkit-ag-ui-frontend-protocol.md) | AG-UI 前端协议与事件契约 |
+| [config-management-api.md](engineering/config-management-api.md) | 配置 REST API 与 `run_config` 合并模型 |
+| [backend-rest-api-reference.md](engineering/backend-rest-api-reference.md) | 后端 REST API 完整参考 |
+| [supported-databases.md](engineering/supported-databases.md) | 数据源 adapter 与注册说明 |
+| [data-tasks-workbench-design.md](engineering/data-tasks-workbench-design.md) | Web `/data-tasks` 工作台 UI 设计 |
+| [tui-protocol-client.md](engineering/tui-protocol-client.md) | TUI CopilotKit 协议客户端 |
+| [tui-state-management.md](engineering/tui-state-management.md) | TUI 状态管理与 Store API |
+
+## 架构与设计
+
+| 文档 | 说明 |
+| --- | --- |
+| [agent-context-management-design.md](engineering/agent-context-management-design.md) | Agent 上下文治理设计 |
+| [conversation-memory-design.md](engineering/conversation-memory-design.md) | 会话记忆设计 |
+| [skill-system-design.md](engineering/skill-system-design.md) | Skill 系统设计 |
+| [file-asset-workspace-artifact-knowledge-design.md](engineering/file-asset-workspace-artifact-knowledge-design.md) | 文件资产、工作区与知识库设计 |
+| [context-turn-grouping-unification-design.md](engineering/context-turn-grouping-unification-design.md) | Context turn 分组统一设计 |
+| [tokenizer-caching.md](engineering/tokenizer-caching.md) | Tokenizer 缓存实现说明 |
+
+## ADR
+
+| 文档 | 说明 |
+| --- | --- |
+| [adr-0001-context-governance-fail-closed.md](engineering/adr-0001-context-governance-fail-closed.md) | 上下文治理 fail-closed |
+| [adr-0002-context-compile-every-mastra-step.md](engineering/adr-0002-context-compile-every-mastra-step.md) | 每 Mastra step 编译上下文 |
+| [adr-0002-memory-authority-and-mastra-memory-boundary.md](engineering/adr-0002-memory-authority-and-mastra-memory-boundary.md) | 记忆权威与 Mastra memory 边界 |
+| [adr-0003-context-layering-and-naming.md](engineering/adr-0003-context-layering-and-naming.md) | 上下文分层与命名 |

.docs-internal/engineering/adr-0002-memory-authority-and-mastra-memory-boundary.md

@@ -171,6 +171,6 @@ Neutral:
 
 ## Related Documents
 
-- `docs/engineering/2026-06-23-memory-context-prompt-walkthrough.html`
+- [mastra-memory-controlled-integration.html](./mastra-memory-controlled-integration.html)
 - `docs/plans/2026-06-23-memory-context-source-unification.md`
 - `docs/plans/2026-06-23-mastra-memory-controlled-integration.md`

.docs-internal/engineering/adr-0003-context-layering-and-naming.md

@@ -571,8 +571,8 @@ Negative:
 
 ## Related Documents
 
-- `docs/engineering/context-governance-pipeline.svg`
-- `docs/engineering/context-governance-pipeline.mmd`
-- `docs/engineering/adr-0002-memory-authority-and-mastra-memory-boundary.md`
-- `docs/plans/2026-06-23-memory-context-source-unification.md`
-- `docs/engineering/2026-06-23-memory-context-prompt-walkthrough.html`
+- [context-governance-pipeline.svg](./context-governance-pipeline.svg)
+- [context-governance-pipeline.mmd](./context-governance-pipeline.mmd)
+- [adr-0002-memory-authority-and-mastra-memory-boundary.md](./adr-0002-memory-authority-and-mastra-memory-boundary.md)
+- [mastra-memory-controlled-integration.html](./mastra-memory-controlled-integration.html)
+- [agent-context-architecture.html](./agent-context-architecture.html)

.docs-internal/engineering/agent-context-management-design.md

@@ -49,7 +49,7 @@ Context Sources
 - 摘要模型的具体 provider 选择。
 - Knowledge retrieval 的召回和 rerank 算法。
 
-这些事项保留在仓库根目录的 `todo_list.md`。
+这些事项作为后续迭代工作跟踪，不在本文档展开。
 
 ## 3. 当前实现
 

.docs-internal/engineering/config-management-api.md

@@ -6,7 +6,7 @@
 关联：
 
 - [copilotkit-ag-ui-frontend-protocol.md](./copilotkit-ag-ui-frontend-protocol.md)（AG-UI run 协议，配置 run 时如何透传）
-- [apps/web/src/app/data-tasks/DESIGN.md](../../apps/web/src/app/data-tasks/DESIGN.md)（前端三层配置模型）
+- [data-tasks-workbench-design.md](./data-tasks-workbench-design.md)（前端三层配置模型）
 
 ## 1. 背景与定位
 

apps/web/src/app/data-tasks/DESIGN.md …gineering/data-tasks-workbench-design.mdapps/web/src/app/data-tasks/DESIGN.md renamed to .docs-internal/engineering/data-tasks-workbench-design.md apps/web/src/app/data-tasks/DESIGN.md renamed to .docs-internal/engineering/data-tasks-workbench-design.md

@@ -1,5 +1,6 @@
-# Data Agent Session Page — Design
+# Data Tasks Workbench — Design
 
+> **Code:** `apps/web/src/app/data-tasks/`  
 > **Last verified against code:** 2026-06-24  
 > **Maintenance:** When changing `TaskConsole`, layout/responsive behavior, config
 > REST integration, or design tokens, update this document in the same change.
@@ -10,13 +11,13 @@ This page (`/data-tasks`) is a **data-agent workbench** built on CopilotKit v2
 the backend actually streams. There is no mock scenario or scripted demo.
 
 The backend protocol surface is the source of truth for what is renderable; see
-[copilotkit-ag-ui-frontend-protocol.md](../../../../../.docs-internal/engineering/copilotkit-ag-ui-frontend-protocol.md).
+[docs/zh/reference/agent-runtime.md](../../docs/zh/reference/agent-runtime.md).
 This document describes how the page maps that protocol to UI.
 
 ## Layout
 
 Three-column responsive grid, driven by
-[workspace-layout.ts](./workspace-layout.ts) rather than static Tailwind
+[workspace-layout.ts](../../apps/web/src/app/data-tasks/workspace-layout.ts) rather than static Tailwind
 breakpoints:
 
 ```
@@ -58,8 +59,8 @@ Layout behavior:
   right console first, then collapse the left panel. User preferences are
   restored when space returns.
 - When the viewport cannot fit a docked right panel (`canDockRightPanel` in
-  [workspace-layout.ts](./workspace-layout.ts)), `TaskConsole` opens in
-  [TaskConsoleDrawer.tsx](./components/task-console/TaskConsoleDrawer.tsx)
+  [workspace-layout.ts](../../apps/web/src/app/data-tasks/workspace-layout.ts)), `TaskConsole` opens in
+  [TaskConsoleDrawer.tsx](../../apps/web/src/app/data-tasks/components/task-console/TaskConsoleDrawer.tsx)
   (full-screen overlay, Esc / backdrop dismiss) instead of the grid column. The
   chat header「打开控制台」button opens the drawer on narrow viewports.
 - Opening `WorkspaceConfigPanel` makes the workspace two-column: left config
@@ -68,12 +69,12 @@ Layout behavior:
 
 ## Workspace configuration model (DB / KB / MCP / LLM / Skill)
 
-State + schema live in [data-task-state.ts](./data-task-state.ts); UI lives in
-[page.tsx](./page.tsx). Backend config I/O is handled by
-[use-workspace-config-api.ts](./hooks/use-workspace-config-api.ts), which wraps
+State + schema live in [data-task-state.ts](../../apps/web/src/app/data-tasks/data-task-state.ts); UI lives in
+[page.tsx](../../apps/web/src/app/data-tasks/page.tsx). Backend config I/O is handled by
+[use-workspace-config-api.ts](../../apps/web/src/app/data-tasks/hooks/use-workspace-config-api.ts), which wraps
 `lib/config-api`. The backend-side contract and runtime capability surface:
 
-- [config-management-api.md](../../../../../.docs-internal/engineering/config-management-api.md)
+- [docs/zh/reference/configuration-api.md](../../docs/zh/reference/configuration-api.md)
   — REST contract for config management and the **`run_config` merge model**
   section (server-side merge of workspace defaults, session overrides, and per-run
   selections).
@@ -230,7 +231,7 @@ Two `useAgentContext` items (+ `forwardedProps.datasourceId`):
 - `datasource_id` — the one field the backend currently honors (protocol §2).
 - `run_config` — single forward-compatible payload built by `buildRunConfig`
   matching the **`run_config` merge model** in
-  [config-management-api.md](../../../../../.docs-internal/engineering/config-management-api.md);
+  [docs/zh/reference/configuration-api.md](../../docs/zh/reference/configuration-api.md);
   **ids / selections only, no secrets**:
 
 ```jsonc
@@ -332,9 +333,9 @@ flowchart LR
 
 - The `CopilotKit` provider points at `NEXT_PUBLIC_AGENT_RUNTIME_URL`
   (default `http://127.0.0.1:8787/api/copilotkit`) with `agentId="dataAgent"`.
-- [use-data-agent-run.ts](./use-data-agent-run.ts) subscribes to the agent and
+- [use-data-agent-run.tsx](../../apps/web/src/app/data-tasks/use-data-agent-run.tsx) subscribes to the agent and
   reduces the AG-UI stream into a `LiveRun` via
-  [live-run-state.ts](./live-run-state.ts).
+  [live-run-state.ts](../../apps/web/src/app/data-tasks/live-run-state.ts).
 - Events consumed: `RUN_STARTED/FINISHED/ERROR`, `STATE_SNAPSHOT/DELTA`,
   `ACTIVITY_SNAPSHOT/DELTA` (plan + step), `TOOL_CALL_*`, and
   `CUSTOM` (`sql_audit`, `artifact`, `token_usage`, `workspace.metadata`,
@@ -474,8 +475,8 @@ The middle→right linkage mirrors the Step / Tool hierarchy:
 
 ## Design tokens and visual semantics
 
-The workbench uses Tailwind v4 CSS variables from [globals.css](../globals.css)
-and shared class bundles from [ui-tokens.ts](./ui-tokens.ts). New UI should prefer
+The workbench uses Tailwind v4 CSS variables from [globals.css](../../apps/web/src/app/globals.css)
+and shared class bundles from [ui-tokens.ts](../../apps/web/src/app/data-tasks/ui-tokens.ts). New UI should prefer
 semantic tokens over hardcoded `slate-*` / `blue-*` colors so the dense dashboard
 can evolve consistently.
 

TOKENIZER_CACHING.md …nternal/engineering/tokenizer-caching.mdTOKENIZER_CACHING.md renamed to .docs-internal/engineering/tokenizer-caching.md TOKENIZER_CACHING.md renamed to .docs-internal/engineering/tokenizer-caching.md

@@ -1,7 +1,8 @@
-# Tokenizer Cache Implementation Note
+# Tokenizer Cache
 
-更新时间：2026-06-22
-状态：基础缓存已实现；request path 预加载尚未实施
+> **Code:** `packages/agent-runtime/src/context/token-counter.ts`  
+> **Updated:** 2026-06-22  
+> **Status:** 基础缓存已实现；request path 预加载尚未实施
 
 ## Current Behavior
 

apps/tui/src/protocol/README.md …ernal/engineering/tui-protocol-client.mdapps/tui/src/protocol/README.md renamed to .docs-internal/engineering/tui-protocol-client.md apps/tui/src/protocol/README.md renamed to .docs-internal/engineering/tui-protocol-client.md

@@ -1,6 +1,7 @@
-# CopilotKit Protocol Client
+# TUI Protocol Client
 
-Node client for the DataAgent CopilotKit single-route runtime.
+> **Code:** `apps/tui/src/protocol/`  
+> **Maintenance:** Update when changing CopilotKit client request shape or SSE parsing.
 
 ## Request Shape
 

…ps/tui/src/state/store-usage-examples.md …rnal/engineering/tui-state-management.mdapps/tui/src/state/store-usage-examples.md renamed to .docs-internal/engineering/tui-state-management.md apps/tui/src/state/store-usage-examples.md renamed to .docs-internal/engineering/tui-state-management.md

@@ -1,4 +1,109 @@
-# TUI Store 使用指南
+# TUI State Management
+
+> **Code:** `apps/tui/src/state/`  
+> **Maintenance:** Update this document when changing TUI store shape, selectors, or session stats.
+
+This directory contains the state management implementation for the TUI application.
+
+## Structure
+
+### Symbolic Links (Reused from Web App)
+- `live-run-state.ts` → `../../../web/src/app/data-tasks/live-run-state.ts`
+  - Core LiveRun state types and reducer logic
+  - Handles run status, plan tasks, events, artifacts, audits, tool calls
+  - Event processing for AG-UI protocol (RUN_STARTED, RUN_FINISHED, TOOL_CALL_*, etc.)
+
+- `data-task-state.ts` → `../../../web/src/app/data-tasks/data-task-state.ts`
+  - Data task types (TimelineEvent, DataArtifact, SchemaTable, etc.)
+  - Utility functions for data step kinds and labels
+
+- `workspace-layout.ts` → `../../../web/src/app/data-tasks/workspace-layout.ts`
+  - Layout constants and utilities (required by data-task-state.ts)
+
+### TUI-Specific Files
+
+#### `tui-state.ts`
+Extends `LiveRun` with TUI-specific fields:
+- `messages: DisplayMessage[]` - Chat message history for display
+- `inputBuffer: string` - Current user input buffer
+- `connectionStatus: 'connected' | 'disconnected' | 'error'` - WebSocket connection status
+- `threadId?: string` - Current session thread ID
+- `lastError?: string` - Last error message
+
+Functions:
+- `createInitialTuiState()` - Create initial state
+- `updateConnectionStatus()` - Update connection status
+- `updateInputBuffer()` / `clearInputBuffer()` - Manage input buffer
+- `setThreadId()` - Set thread ID
+
+#### `message-history.ts`
+Message accumulation and display formatting:
+- `addUserMessage()` - Add user message to history
+- `addAssistantMessage()` - Add assistant message to history
+- `addSystemMessage()` - Add system message to history
+- `updateLastAssistantMessage()` - Update last assistant message (for streaming)
+- `appendToLastAssistantMessage()` - Append delta to last assistant message
+- `finalizeLastAssistantMessage()` - Mark streaming as complete
+- `formatMessageForDisplay()` - Format message for terminal display
+- `formatMessagesForDisplay()` - Format all messages
+- `getRecentMessages()` - Get last N messages
+
+#### `store.ts`
+Central state store with observer pattern:
+- Singleton `StateStore` class
+- Subscribe to state changes
+- Wrapper methods for all state operations
+- Integrates `reduceLiveRunEvent` for AG-UI protocol events
+
+#### `index.ts`
+Re-exports all state types and functions for easy consumption.
+
+## Usage
+
+```typescript
+import { store } from './state/store';
+import { formatMessagesForDisplay } from './state';
+
+// Subscribe to state changes
+const unsubscribe = store.subscribe((state) => {
+  console.log('State updated:', state);
+});
+
+// Add user message
+store.addUserMessage('Query sales data');
+
+// Handle protocol event
+store.handleLiveRunEvent({ type: 'RUN_STARTED' });
+
+// Update connection status
+store.setConnectionStatus('connected');
+
+// Stream assistant response
+store.addAssistantMessage('', true); // Start streaming
+store.appendToAssistantMessage('Analyzing ');
+store.appendToAssistantMessage('data...');
+store.finalizeAssistantMessage(); // Complete streaming
+
+// Format messages for display
+const state = store.getState();
+const formatted = formatMessagesForDisplay(state.messages);
+```
+
+## Integration with Protocol
+
+The state management integrates with the CopilotKit protocol through `reduceLiveRunEvent`:
+
+1. **Run Lifecycle**: `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`
+2. **Tool Calls**: `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END`, `TOOL_CALL_RESULT`
+3. **Activity Events**: `ACTIVITY_SNAPSHOT`, `ACTIVITY_DELTA` (for plan updates)
+4. **State Updates**: `STATE_SNAPSHOT`, `STATE_DELTA`
+5. **Custom Events**: `sql_audit`, `artifact`, `token_usage`
+
+All these events are processed by `reduceLiveRunEvent` and update the LiveRun portion of the state, while TUI-specific fields (messages, input, connection) are managed separately.
+
+---
+
+# Store API Reference
 
 ## 概述
 

README.md

@@ -4,6 +4,10 @@
   A TypeScript data-agent runtime and workbench for safe, auditable analysis over databases, files, knowledge, and generated artifacts.
 </p>
 
+<p align="center">
+  English · <a href="README_zh.md">简体中文</a>
+</p>
+
 <p align="center">
   <a href="docs/zh/quick-start.md"><strong>Quick Start</strong></a>
   ·