From 3ddf12a3c2150105b71717444260627119900434 Mon Sep 17 00:00:00 2001
From: tangkikodo <allmonday@126.com>
Date: Wed, 1 Jul 2026 13:05:18 +0800
Subject: [PATCH 1/2] feat(voyager): About tab (docstring + Mermaid) and
 2/3-width sidebar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

为 ER-diagram 双击打开的侧边栏新增最左的 About tab，渲染 schema 模型类
__doc__ 为 GitHub-Flavored Markdown，docstring 中的 ```mermaid 围栏块
（stateDiagram-v2 / flowchart / sequenceDiagram）就地渲染为可视化图表；
语法错误块降级为"错误提示 + 默认折叠源码"。同时把侧边栏拖拽上限从
固定 800px 改为 floor(viewport × 2/3)，视窗缩放时主动 clamp 到新上限。

- 后端：新增 POST /docstring 端点 + VoyagerContext.get_docstring 方法，
  与 /source /vscode-link 对称，不改 SchemaNode、不改现有端点契约
- 前端：新建 about-display.js（marked + DOMPurify + mermaid.run 管线，
  per-block try/catch + <details> 折叠降级，链接强制 noopener）；
  schema-code-display.js 加 About tab（最左，默认激活仍是 Fields）；
  vue-main.js mermaid.initialize + 拖拽 clamp + resize 监听
- 依赖：marked@15 / dompurify@3 / mermaid@11 走 CDN（cdn.jsdelivr.net），
  匹配现有 Vue/d3/jQuery 模式；三个 URL 加入 sw.js CDN_ASSETS 预缓存
- 测试：tests/test_voyager_docstring.py 5 条 pytest 用例
- demo：Employee docstring 覆盖 FR-003 全元素矩阵 + FR-004 三种 mermaid 类型

Spec-kit 产物在 specs/006-voyager-about-tab/，全中文撰写（项目约定）。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .specify/feature.json                         |   2 +-
 CHANGELOG.md                                  |  27 ++
 demo/enterprise_voyager/models.py             |  96 ++++++
 .../checklists/requirements.md                |  36 +++
 .../contracts/about-tab-component.md          | 133 ++++++++
 .../contracts/docstring-endpoint.md           |  84 +++++
 .../contracts/sidebar-width-clamp.md          | 126 ++++++++
 specs/006-voyager-about-tab/data-model.md     | 126 ++++++++
 specs/006-voyager-about-tab/plan.md           |  98 ++++++
 specs/006-voyager-about-tab/quickstart.md     | 172 +++++++++++
 specs/006-voyager-about-tab/research.md       | 122 ++++++++
 specs/006-voyager-about-tab/spec.md           | 148 +++++++++
 specs/006-voyager-about-tab/tasks.md          | 229 ++++++++++++++
 src/nexusx/voyager/create_voyager.py          |  10 +
 src/nexusx/voyager/voyager_context.py         |  20 ++
 .../voyager/web/component/about-display.js    | 287 ++++++++++++++++++
 .../web/component/schema-code-display.js      |  11 +-
 src/nexusx/voyager/web/index.html             |   5 +
 src/nexusx/voyager/web/sw.js                  |   4 +
 src/nexusx/voyager/web/vue-main.js            |  37 ++-
 tests/test_voyager_docstring.py               |  69 +++++
 21 files changed, 1839 insertions(+), 3 deletions(-)
 create mode 100644 specs/006-voyager-about-tab/checklists/requirements.md
 create mode 100644 specs/006-voyager-about-tab/contracts/about-tab-component.md
 create mode 100644 specs/006-voyager-about-tab/contracts/docstring-endpoint.md
 create mode 100644 specs/006-voyager-about-tab/contracts/sidebar-width-clamp.md
 create mode 100644 specs/006-voyager-about-tab/data-model.md
 create mode 100644 specs/006-voyager-about-tab/plan.md
 create mode 100644 specs/006-voyager-about-tab/quickstart.md
 create mode 100644 specs/006-voyager-about-tab/research.md
 create mode 100644 specs/006-voyager-about-tab/spec.md
 create mode 100644 specs/006-voyager-about-tab/tasks.md
 create mode 100644 src/nexusx/voyager/web/component/about-display.js
 create mode 100644 tests/test_voyager_docstring.py

diff --git a/.specify/feature.json b/.specify/feature.json
index 2d308b8..58edaf5 100644
--- a/.specify/feature.json
+++ b/.specify/feature.json
@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/005-related-entities-tab"
+  "feature_directory": "specs/006-voyager-about-tab"
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7364612..34500a9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,32 @@
 # Changelog
 
+## Unreleased
+
+### New Feature: Voyager ER 图新增 "About" tab（docstring + Mermaid 渲染）& 侧边栏宽度放宽
+
+双击 entity 打开的侧边栏原先只有 Fields / Source Code / Related Entities 三个 tab，schema 模型类的 `__doc__` 完全没有入口。本次在最左新增 **About** tab，把类级 docstring 当作 GitHub-Flavored Markdown 渲染——含标题、列表、表格、代码块、引用块、水平线等元素；docstring 中的 ```mermaid 围栏块（`stateDiagram-v2` / `flowchart` / `sequenceDiagram` 等）就地渲染成可视化图表，方便在 docstring 里直接画"实体生命周期 / 状态转移 / 交互流程"。Mermaid 块语法错误时降级为"错误提示 + 默认折叠的原始源码"，方便复制到外部工具调试，且单块失败不影响其它内容。
+
+同时把侧边栏拖拽宽度上限从固定 **800px** 改为 **floor(viewport × 2/3)**，宽屏下也能给宽表格、宽 Mermaid 图、长 Python 行留足空间；视窗缩放时自动 clamp 到新的 2/3 上限，下限 300px 与默认初始宽度不变。
+
+**关键设计：**
+- docstring 走独立端点 `POST /docstring`（与 `/source` / `/vscode-link` 对称），不改 SchemaNode、不改 `/source` 契约——避免 er-diagram 初始 payload 膨胀与 service worker 缓存键失效。
+- 前端依赖 `marked` / `dompurify` / `mermaid` 走 **CDN**（cdn.jsdelivr.net），匹配现有 Vue/d3/jQuery 模式；三个 URL 加入 sw.js 的 `CDN_ASSETS` 预缓存列表以保证离线可用。
+- docstring 经 `DOMPurify.sanitize` 清洗后再注入，所有 `<a>` 强制 `target="_blank" rel="noopener noreferrer"`，且不识别"实体引用"格式——About tab 与 Related Entities 子图一样**只读**。
+- 切换实体保留当前激活 tab（沿用 spec 005 FR-012 的策略，对四个 tab 一视同仁）；About tab 在 tab 栏最左，但侧边栏首次打开默认激活 Fields 不变。
+
+**Changes：**
+- `src/nexusx/voyager/voyager_context.py`: 新增 `get_docstring(schema_name)` 方法，复用 `_resolve_object`、返回 `{"docstring": obj.__doc__ or ""}`
+- `src/nexusx/voyager/create_voyager.py`: 新增 `POST /docstring` 路由，状态码映射与 `/source` 一致
+- `src/nexusx/voyager/web/component/about-display.js`: 新建组件，渲染管线 = marked → DOMPurify → innerHTML → 链接硬化 → mermaid.run（per-block try/catch + 错误降级）
+- `src/nexusx/voyager/web/component/schema-code-display.js`: 加 `showAbout` prop；tab 栏最左加 About；content 区挂载 `<about-display>`
+- `src/nexusx/voyager/web/vue-main.js`: 引入 AboutDisplay 全局组件；`mermaid.initialize({ startOnLoad: false, theme: "default" })`；`startDragDrawer` clamp 改为 `Math.max(300, Math.min(floor(innerWidth × 2/3), ...))`；`onMounted` 注册 `window.resize` 监听器，超出新上限时主动压缩
+- `src/nexusx/voyager/web/index.html`: 引入 marked / dompurify / mermaid 三个 `<script>`；`<schema-code-display>` 加 `:show-about="store.state.mode === 'er-diagram'"`
+- `src/nexusx/voyager/web/sw.js`: `CDN_ASSETS` 预缓存列表追加三个 CDN URL
+- `tests/test_voyager_docstring.py`: 新增 5 条 pytest 用例（happy / 空 docstring / 非法格式 / module 缺失 / class 缺失）
+- `demo/enterprise_voyager/models.py`: 给 `Employee` 加 docstring，覆盖 FR-003 全部 Markdown 元素 + FR-004 三种 Mermaid 类型，便于人工验证
+
+---
+
 ## 3.3.1
 
 ### Bug Fix: Voyager ER-diagram 侧边栏补回字段描述
diff --git a/demo/enterprise_voyager/models.py b/demo/enterprise_voyager/models.py
index c30cb93..9faea51 100644
--- a/demo/enterprise_voyager/models.py
+++ b/demo/enterprise_voyager/models.py
@@ -57,6 +57,102 @@ class Team(SQLModel, table=True):
 
 
 class Employee(SQLModel, table=True):
+    """员工实体。
+
+    表示系统中的一个**在职**或**离职**员工。一个员工从属于一个 `Department`，
+    并通过 `Team` 关联到具体的协作小组；当员工担任管理职责时，`manager_id`
+    形成自引用，指向另一个 `Employee` 作为上级。
+
+    ## 关键属性
+
+    - `full_name` — 全名（必填）
+    - `email` — 登录邮箱（必填、唯一）
+    - `manager_id` — 直属上级，自引用 `Employee.id`
+    - 部门/办公点/小组通过外键关联，详见下表
+
+    ## 生命周期
+
+    1. HR 创建员工记录（`Onboarding`）
+    2. 完成入职流程，进入 `Active` 状态
+    3. 可能进入 `OnLeave` 请假状态
+    4. 最终走 `Offboarding` 流程注销
+
+    > **审计**：本实体的写入操作由独立的 `AuditLog` 实体记录，不在本类内维护。
+
+    ## 字段速查
+
+    | 字段 | 类型 | 说明 |
+    |------|------|------|
+    | `full_name` | `str` | 全名 |
+    | `email` | `str` | 登录邮箱 |
+    | `department_id` | `int` | 所属部门 |
+    | `office_id` | `int` | 办公地点 |
+    | `team_id` | `int` | 协作小组 |
+    | `manager_id` | `int` | 直属上级（自引用） |
+
+    ### Python 构造
+
+    ```python
+    emp = Employee(
+        full_name="张三",
+        email="zhangsan@example.com",
+        department_id=1,
+        office_id=2,
+        team_id=3,
+    )
+    ```
+
+    #### 字段命名约定
+
+    `_下划线命名_` 的字段表示内部引用（如 `_internal_state`），普通字段用 `lowercase`。
+    命名细节可参考项目的命名规范文档。
+
+    ---
+
+    说明：本字段表用于 demo / 文档展示，实际字段定义以源码为准。可参考
+    [SQLModel 关系文档](https://sqlmodel.tiangolo.com/tutorial/relationships/)。
+
+    ## 状态机（stateDiagram）
+
+    ```mermaid
+    stateDiagram-v2
+        [*] --> Onboarding
+        Onboarding --> Active: 完成入职
+        Active --> OnLeave: 请假
+        OnLeave --> Active: 假期结束
+        Active --> Offboarding: 提交离职
+        Offboarding --> [*]: 完成离职
+        OnLeave --> Offboarding: 假期中离职
+    ```
+
+    ## 入职流程（flowchart）
+
+    ```mermaid
+    flowchart TD
+        A[HR 创建 Employee] --> B{材料齐全?}
+        B -->|是| C[开通邮箱/账号]
+        B -->|否| A
+        C --> D[分配 Department/Office/Team]
+        D --> E[指定 Manager]
+        E --> F[入职培训]
+        F --> G[Active]
+    ```
+
+    ## 离职交互（sequenceDiagram）
+
+    ```mermaid
+    sequenceDiagram
+        participant E as Employee
+        participant M as Manager
+        participant H as HR
+        E->>M: 提交离职申请
+        M->>H: 审批通过
+        H->>E: 离职清单
+        E->>H: 交接完成
+        H->>E: 注销账号
+    ```
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     full_name: str
     email: str
diff --git a/specs/006-voyager-about-tab/checklists/requirements.md b/specs/006-voyager-about-tab/checklists/requirements.md
new file mode 100644
index 0000000..1b942fc
--- /dev/null
+++ b/specs/006-voyager-about-tab/checklists/requirements.md
@@ -0,0 +1,36 @@
+# 规格质量清单：Voyager ER 图 —— About Tab（docstring + Mermaid）& 侧边栏宽度放宽
+
+**用途**：在进入 `/speckit-clarify` 或 `/speckit-plan` 之前，对规格的完整性与质量做一次校验
+**创建日期**：2026-07-01
+**功能**：[spec.md](../spec.md)
+
+## 内容质量
+
+- [x] 无实现细节（语言、框架、API 名等）——文中出现的 Markdown / Mermaid / GitHub-Flavored Markdown 均为用户在 docstring 中**主动书写**的语法，属于用户可见概念；未指定任何前端库或后端框架。
+- [x] 聚焦用户价值与业务诉求——每个 Story 都从用户痛点（docstring 不可读 / Mermaid 不渲染 / 侧边栏太窄）出发。
+- [x] 面向非技术干系人——叙述用业务语言；少量技术名词（如 H1–H6）仅用作用户可书写语法的引用。
+- [x] 所有必填章节已完成——User Scenarios、Requirements、Success Criteria 三大必填章节齐备。
+
+## 需求完整性
+
+- [x] 规格内不再残留 [NEEDS CLARIFICATION] 标记——所有不确定处都给出了合理默认值，并写入"假设"章节。
+- [x] 需求可测试且无歧义——FR-001 至 FR-016 均对应明确验收场景（Story 1/2/3 共 17 条 scenario + 12 条 edge case）。
+- [x] 成功标准可衡量——SC-001 至 SC-005 都给出可观测指标（点击次数、理解时间下降、视窗像素、布局是否破损、空状态可识别）。
+- [x] 成功标准与具体技术解耦——未绑定任何具体前端框架或库；"1920px / 1280px" 是用户视窗维度，非系统内部指标。
+- [x] 所有验收场景都已定义——三档优先级（P1/P2/P2）各覆盖完整 happy path 与关键异常路径。
+- [x] 边界情况已识别——12 条 Edge Case 覆盖：空 docstring、纯 mermaid docstring、不支持的图表语言、恶意 HTML、外部图片、超长 docstring、多 mermaid 块、视窗极小/极大、拖到极限后切实体、拖到极限后刷新、About tab 中实体被删、tab 来回切换。
+- [x] 范围被清晰界定——ER-diagram 模式 only、只读、不引入编辑、不支持 PlantUML/DOT 等其他图表语言、不改变默认初始宽度。
+- [x] 依赖与假设已识别——"假设"章节 9 条，覆盖可见性、默认 tab、docstring 来源、tab 保留策略、下限沿用、Mermaid 主题、只读、不支持其他图表语言。
+
+## 功能就绪度
+
+- [x] 所有功能需求都有清晰的验收标准——FR-001↔Story1#1、FR-004↔Story2#1、FR-010↔Story2#3、FR-013↔Story3#1/2、FR-015↔Story3#4 等，均可一一对应。
+- [x] 用户场景覆盖主要流程——阅读 docstring（P1）+ 查看 Mermaid 图（P2）+ 拖宽侧边栏（P2），三档优先级相互独立可交付。
+- [x] 功能满足"成功标准"中定义的可衡量结果——SC-001→Story1、SC-002→Story2、SC-003/004→Story3、SC-005→FR-005 空状态。
+- [x] 无实现细节泄漏到规格中——已通过内容质量项首条校验。
+
+## 备注
+
+- 本规格未触发任何 [NEEDS CLARIFICATION]；所有需要决策的细节（About tab 在哪种模式可见、默认激活 tab 是哪个、docstring 取自何处、拖拽下限具体数值等）都通过"沿用现状/惯例"的方式给了默认值，记录在"假设"章节。
+- 若 `/speckit-clarify` 阶段用户希望调整这些默认（例如让 About tab 也出现在 voyager 模式、或把 About 设为默认激活 tab），可在该阶段集中处理。
+- 项标记不完整的，须在 `/speckit-clarify` 或 `/speckit-plan` 之前回到 spec.md 修正。
diff --git a/specs/006-voyager-about-tab/contracts/about-tab-component.md b/specs/006-voyager-about-tab/contracts/about-tab-component.md
new file mode 100644
index 0000000..dab97ee
--- /dev/null
+++ b/specs/006-voyager-about-tab/contracts/about-tab-component.md
@@ -0,0 +1,133 @@
+# 契约：`<about-display>` 前端组件
+
+**功能**：[spec.md](../spec.md) · **数据模型**：[data-model.md](../data-model.md) · **Mermaid 管线**：[research.md](../research.md) 决策 3
+
+**位置**：`src/nexusx/voyager/web/component/about-display.js`（新增）
+
+---
+
+## 角色
+
+Voyager ER 图侧边栏新增 "About" tab 的内容组件。当用户在 ER-diagram 模式下双击实体打开侧边栏、并切换到 About tab 时，本组件加载该 schema 模型类的 docstring，以 Markdown 渲染（含 Mermaid 块的就地图表渲染）。
+
+模式与现有 `<related-entities-display>` 完全对称——独立组件、自管 state、只在被激活时发请求、提供 loading/error/empty 三态。
+
+---
+
+## Props
+
+| 名称 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `schemaName` | `String` | required | 当前所选实体的全限定名（`module.Class`），与 `<schema-code-display>` 的同 名 prop 一致 |
+| `visible` | `Boolean` | `false` | 当前 About tab 是否处于激活可见状态。仅当从 `false` 切到 `true` 时才发起 fetch；切到 `false` 时**不**清空已渲染内容（切回时无需重发请求） |
+
+**不用** vuex/quasar store；不接收 `schemas` 列表 prop——docstring 不在 schema_map 里（见 [data-model.md](../data-model.md) §2.3）。
+
+---
+
+## 内部 ref（不暴露）
+
+| ref | 类型 | 说明 |
+|-----|------|------|
+| `docstring` | `string` | 原始 docstring 文本 |
+| `loading` | `boolean` | 是否正在请求 `/docstring` |
+| `error` | `string \| null` | 错误文案；`null` 表示无错误 |
+| `mermaidErrors` | `Array<{index: number, message: string, source: string}>` | 各 mermaid 块的渲染失败诊断（按块序号）；成功的块不进此数组 |
+
+---
+
+## 行为契约
+
+### 1. 数据加载
+
+- 当 `visible` 由 `false` → `true` 且 `schemaName` 非空 且 `docstring.value === "" && !error.value`（即尚未加载过）→ 触发 `fetchDocstring()`
+- 当 `schemaName` 变化（侧边栏切到另一个实体）→ **重置** `docstring/loading/error/mermaidErrors` 后重新 `fetchDocstring()`
+- `fetchDocstring()` 内部：
+  - `loading = true`、`error = null`
+  - `fetch('docstring', { method: 'POST', headers: {...}, body: JSON.stringify({schema_name: props.schemaName}) })`
+  - 成功（200）：`docstring = data.docstring ?? ""`、`loading = false`
+  - 失败（4xx/5xx 或网络错）：`error = data.error || "Failed to load docstring"`、`loading = false`
+- 切回非激活 tab 再切回：**不**重新 fetch，保留已渲染 DOM（spec 边界情况约定）
+
+### 2. 渲染管线（每次 `docstring` 变化后触发）
+
+```
+raw docstring
+    │
+    ▼ marked.parse(docstring, { gfm: true, breaks: false })
+htmlString
+    │
+    ▼ DOMPurify.sanitize(htmlString, {
+        ADD_ATTR: ['class','target','rel','href'],
+        ADD_TAGS: ['pre','code','details','summary'],
+      })
+cleanHtml
+    │
+    ▼ container.innerHTML = cleanHtml
+DOM
+    │
+    ▼ 对每个 code.language-mermaid 单独处理：
+      - 取出 sourceText
+      - try mermaid.parse(sourceText) 校验
+        - ok → 替换为 <div class="mermaid">sourceText</div>
+        - fail → mermaidErrors.push({index, message, source})，替换为
+                <div class="mermaid-error">
+                  <p>该 Mermaid 图渲染失败：{message}</p>
+                  <details><summary>查看源码</summary><pre>{sourceText}</pre></details>
+                </div>
+      - 失败的块由 mermaid.run 跳过
+    │
+    ▼ mermaid.run({ nodes: container.querySelectorAll('div.mermaid') })
+最终 DOM
+```
+
+**对每个 `<a>` 强制注入** `target="_blank" rel="noopener noreferrer"`（在 `cleanHtml` 注入后用一次 `container.querySelectorAll('a').forEach(...)` 完成）——实现 FR-017 + FR-009 的链接安全契约。
+
+### 3. 三态 UI
+
+| 状态 | 条件 | 渲染 |
+|------|------|------|
+| Loading | `loading === true` | `<q-linear-progress indeterminate color="primary" size="2px" />`（与 `<schema-code-display>` 风格一致） |
+| Error | `error !== null` | `<div style="color:#c10015">{{ error }}</div>`（与 `<schema-code-display>` 的错误样式一致） |
+| Empty | `!loading && !error && docstring.trim() === ''` | `<div class="text-grey-7">该实体暂无 docstring。</div>`（spec FR-005） |
+| Content | `!loading && !error && docstring.trim() !== ''` | 上述渲染管线产出的 DOM |
+
+### 4. Mermaid 初始化（全局一次，不在本组件）
+
+`vue-main.js` 或 `index.html` 引入 `mermaid.min.js` 后立即：
+
+```js
+window.mermaid.initialize({ startOnLoad: false, theme: 'default' })
+```
+
+本组件**不**重复 initialize；多次 initialize 会让 mermaid 抱怨。
+
+---
+
+## 模板结构（伪代码）
+
+```html
+<div class="about-display" style="height:100%; overflow:auto;">
+  <q-linear-progress v-if="loading" indeterminate color="primary" size="2px" />
+  <div v-else-if="error" style="color:#c10015; font-family:Menlo,monospace; font-size:12px;">
+    {{ error }}
+  </div>
+  <div v-else-if="emptyDocstring" class="text-grey-7" style="padding:12px;">
+    该实体暂无 docstring。
+  </div>
+  <div v-else ref="contentRef" class="markdown-body" style="padding:8px 16px;"></div>
+</div>
+```
+
+`contentRef` 在内容注入后用于 querySelector；mermaid 失败诊断用 `mermaidErrors` 数组在 dev 模式下做排错展示（生产环境靠 DOM 内的 `.mermaid-error` 节点即可）。
+
+---
+
+## 集成到 `<schema-code-display>`
+
+修改 `schema-code-display.js`：
+
+1. **tab 栏**：把 `<q-tab name="about" label="About" />` 加在最前（在 Fields 之前），并用 `v-if="showAbout"` 控制（与 `showRelatedEntities` 对称，仅 ER-diagram 模式显示）。
+2. **content 区**：新增 `<div v-show="tab === 'about'">` 分支，挂载 `<about-display :schema-name="schemaName" :visible="tab === 'about' && modelValue" />`。
+3. **props**：新增 `showAbout: { type: Boolean, default: false }`，由外层 `index.html` 传 `store.state.mode === 'er-diagram'`（与现有 `showRelatedEntities` 一致）。
+4. **默认激活 tab 不变**：`tab = ref("fields")` 保持原状（spec 假设 + Session Q1 决议）。
diff --git a/specs/006-voyager-about-tab/contracts/docstring-endpoint.md b/specs/006-voyager-about-tab/contracts/docstring-endpoint.md
new file mode 100644
index 0000000..36891e5
--- /dev/null
+++ b/specs/006-voyager-about-tab/contracts/docstring-endpoint.md
@@ -0,0 +1,84 @@
+# 契约：POST /docstring（Voyager 后端端点）
+
+**功能**：[spec.md](../spec.md) · **数据模型**：[data-model.md](../data-model.md)
+
+**位置**：`src/nexusx/voyager/create_voyager.py`（与现有 `/source`、`/vscode-link` 路由并列）+ `src/nexusx/voyager/voyager_context.py`（新增 `get_docstring` 方法）
+
+---
+
+## 路由
+
+```python
+@router.post("/docstring")
+def get_docstring_endpoint(payload: SourcePayload) -> JSONResponse:
+    result = ctx.get_docstring(payload.schema_name)
+    status_code = 200 if "error" not in result else 400
+    if "error" in result and "not found" in result["error"]:
+        status_code = 404
+    return JSONResponse(content=result, status_code=status_code)
+```
+
+复用现有的 `SourcePayload`（`{schema_name: str}`）请求模型——与 `/source`、`/vscode-link` 一致，无需新建 Pydantic model。
+
+---
+
+## 请求
+
+- **Method / Path**：`POST /docstring`
+- **Content-Type**：`application/json`
+- **Body**：
+
+  ```json
+  { "schema_name": "demo.enterprise_voyager.models.User" }
+  ```
+
+- **校验**（与 `/source` 对齐）：
+  - `schema_name` 必填，必须是字符串。
+  - 必须包含至少一个 `.`（用于区分 module 与 class）；否则后端返回 `400` + `Invalid schema name format.`。
+
+---
+
+## 响应
+
+### 成功（200）
+
+```json
+{
+  "docstring": "用户实体。\n\n表示系统中的一个用户。\n\n## 状态机\n\n```mermaid\nstateDiagram-v2\n    [*] --> Active\n    Active --> Disabled: 禁用\n    Disabled --> Active: 恢复\n    Active --> [*]: 注销\n```"
+}
+```
+
+- `docstring`：类 `__doc__` 的原始字符串。若 `__doc__` 为 `None`，返回空串 `""`（不返回 null，便于前端 `v-if` 判空）。
+- 不做 `inspect.cleandoc`——前端的 Markdown 解析器（marked）默认能处理缩进；后端保持原始字节，便于排错。
+
+### 业务错误
+
+| HTTP | body | 触发条件 |
+|------|------|---------|
+| `400 Bad Request` | `{"error": "Invalid schema name format."}` | `schema_name` 格式不合法（无 `.`、或 module 无法导入——`_resolve_object` 把 ImportError 吞为 None） |
+| `404 Not Found` | `{"error": "Class not found: <detail>"}` | module 已加载但 class 不存在（`getattr` 抛 AttributeError） |
+| `400 Bad Request` | `{"error": "Internal error: <detail>"}` | 其它未预期异常（兜底） |
+
+状态码与错误文案格式与现有 `/source`、`/vscode-link` **完全一致**，便于前端复用同一份 fetch+错误处理代码。
+
+> **行为细节**：`_resolve_object`（`voyager_context.py:288`）对 `ImportError` 是吞掉返回 None 的（与 `/source` 完全一致），因此"module 不存在"在 API 表面看与"格式不合法"无法区分——都返回 400 + `"Invalid schema name format."`。这是既有行为，本期不改变。
+
+---
+
+## Service Worker 缓存
+
+**不**加入 `web/sw.js` 的预缓存列表（行 132-133 的 `/source`、`/vscode-link` 是因为前端组件首屏即调用，docstring 仅在用户主动切换 About tab 时才发）。Service Worker 对 `/docstring` 走默认的网络优先策略即可。
+
+---
+
+## 测试覆盖（pytest）
+
+| 用例 | 输入 | 期望 |
+|------|------|------|
+| happy path | 已存在 schema_name | 200，`docstring` 非空且等于类 `__doc__` |
+| 空 docstring | `__doc__` 为 None 的类 | 200，`docstring === ""` |
+| 非法 schema_name（无 `.`） | `"no_dot_string"` | 400，`error === "Invalid schema name format."` |
+| Module 不存在（但格式合法） | `"nonexistent_module.Foo"` | 400，`error === "Invalid schema name format."`（`_resolve_object` 吞 ImportError 返回 None） |
+| Class 不存在（module 已加载） | `"tests.test_voyager_docstring.NoSuchClass"` | 400，`error` 含 `Class not found` |
+
+测试文件：`tests/test_voyager_docstring.py`，与现有 `tests/test_er_diagram.py` 风格一致。
diff --git a/specs/006-voyager-about-tab/contracts/sidebar-width-clamp.md b/specs/006-voyager-about-tab/contracts/sidebar-width-clamp.md
new file mode 100644
index 0000000..67954b8
--- /dev/null
+++ b/specs/006-voyager-about-tab/contracts/sidebar-width-clamp.md
@@ -0,0 +1,126 @@
+# 契约：侧边栏宽度 clamp 逻辑
+
+**功能**：[spec.md](../spec.md) · **数据模型**：[data-model.md](../data-model.md) §4.3 · **公式决策**：[research.md](../research.md) 决策 5
+
+**位置**：`src/nexusx/voyager/web/vue-main.js`（修改 `startDragDrawer` + 新增 resize 监听）
+
+---
+
+## 现状（修改前）
+
+```js
+// vue-main.js:263-285
+function startDragDrawer(e) {
+  const startX = e.clientX
+  const startWidth = store.state.rightDrawer.width
+
+  function onMouseMove(moveEvent) {
+    const deltaX = startX - moveEvent.clientX
+    const newWidth = Math.max(300, Math.min(800, startWidth + deltaX))  // ← 800 是死上限
+    store.state.rightDrawer.width = newWidth
+  }
+  // ... mouseup cleanup
+}
+```
+
+问题：上限固定 800px，在 1920px+ 视窗上仍偏窄（spec Story 3 痛点）。
+
+---
+
+## 修改后
+
+### 1. 抽取常量与上限函数（文件顶部 setup 内）
+
+```js
+const RIGHT_DRAWER_MIN = 300
+const rightDrawerMax = () => Math.floor(window.innerWidth * 2 / 3)
+```
+
+- **MIN 维持 300**（spec 假设 + Session：拖拽下限不动）。
+- **MAX 是函数**，每次调用时从 `window.innerWidth` 实时取——避免缓存导致视窗缩放后值陈旧。
+
+### 2. 拖拽 clamp（`startDragDrawer` 内）
+
+```js
+function onMouseMove(moveEvent) {
+  const deltaX = startX - moveEvent.clientX
+  const newWidth = Math.max(
+    RIGHT_DRAWER_MIN,
+    Math.min(rightDrawerMax(), startWidth + deltaX)
+  )
+  store.state.rightDrawer.width = newWidth
+}
+```
+
+### 3. 视窗 resize 时的 clamp（新增 watch 或事件监听）
+
+在 `setup()` 内（与其它事件监听并列）：
+
+```js
+function onWindowResize() {
+  const max = rightDrawerMax()
+  if (store.state.rightDrawer.width > max) {
+    store.state.rightDrawer.width = max
+  }
+  // 注意：不主动把 width 撑到 max——只在超出时压回，避免"视窗变大时侧边栏自动变宽"的怪异行为
+}
+
+window.addEventListener('resize', onWindowResize)
+
+// 在组件 onUnmounted 中清理：
+//   window.removeEventListener('resize', onWindowResize)
+```
+
+### 4. 侧边栏首次打开时的 clamp
+
+`store.state.rightDrawer.width` 初值是 `300`（spec 假设 + 现有 store 默认）；如果未来引入 localStorage 持久化，hydrate 时必须：
+
+```js
+// 在 store 初始化或 app mount 后：
+store.state.rightDrawer.width = Math.min(
+  store.state.rightDrawer.width,
+  rightDrawerMax()
+)
+```
+
+本期 store 没有 localStorage 持久化（`store.js` 未引入持久层），因此这一步**当前不需要**——但留作未来兼容点。
+
+---
+
+## 行为契约
+
+### 拖拽时（FR-013、FR-014）
+
+| 输入 | 输出 width |
+|------|-----------|
+| `startWidth + deltaX` 在 `[300, floor(W×2/3)]` 内 | 取该值 |
+| `startWidth + deltaX` < 300 | `300` |
+| `startWidth + deltaX` > `floor(W×2/3)` | `floor(W×2/3)` |
+
+### 视窗 resize 时（FR-015）
+
+| 触发 | 当前 width | 操作 |
+|------|-----------|------|
+| resize → 新 `floor(W×2/3)` 仍 ≥ 当前 width | 任意 | **不动** |
+| resize → 新 `floor(W×2/3)` < 当前 width | 任意 | 把 width 压到新的 `floor(W×2/3)` |
+
+**关键不变量**：resize 监听**只在 width 超出时压缩**，从不在 width 内于上限内主动扩展——否则"用户拖到 600 后视窗变大，侧边栏自动跳到 800"会非常怪异。
+
+### 不变行为（FR-016）
+
+- 默认初始 width 维持 `300`（store.js 现状，不改）。
+- 折叠/展开（`rightDrawer.drawer`）逻辑不改。
+- 侧边栏内容渲染、tabs 切换、所有非宽度相关交互不改。
+
+---
+
+## 验收映射
+
+| spec 验收场景 | 本契约对应行为 |
+|--------------|---------------|
+| Story 3 #1（不超过 `floor(W×2/3)`） | §拖拽 clamp 表第 3 行 |
+| Story 3 #2（1920px → ~1280px） | `floor(1920 × 2/3) = 1280`，自然成立 |
+| Story 3 #3（下限不破坏可用性） | `RIGHT_DRAWER_MIN = 300` 不动 |
+| Story 3 #4（视窗缩小时自动 clamp） | §视窗 resize 时第 2 行 |
+| Story 3 #5（刷新后 clamp） | §侧边栏首次打开时的 clamp（未来兼容点） |
+| Story 3 #6（不主动拖拽时行为不变） | §不变行为 |
diff --git a/specs/006-voyager-about-tab/data-model.md b/specs/006-voyager-about-tab/data-model.md
new file mode 100644
index 0000000..d331270
--- /dev/null
+++ b/specs/006-voyager-about-tab/data-model.md
@@ -0,0 +1,126 @@
+# Phase 1 — 数据模型：Voyager About Tab & 侧边栏宽度放宽
+
+**功能**：[spec.md](./spec.md) · **计划**：[plan.md](./plan.md) · **调研**：[research.md](./research.md)
+
+---
+
+## 1. 数据通路总览
+
+```text
+Python 类对象 ──.__doc__─> VoyagerContext.get_docstring(schema_name)
+                              │
+                              ▼
+                        POST /docstring  (HTTP)
+                              │
+                              ▼
+                <about-display> 组件 fetch
+                              │
+                              ▼
+        marked.parse → DOMPurify.sanitize → mermaid.run
+                              │
+                              ▼
+                   About tab 内容 DOM
+```
+
+不修改 `SchemaNode` 等已序列化的 dataclass；不修改 `/er-diagram`、`/er-diagram-subgraph`、`/source`、`/vscode-link` 任何现有响应 shape。
+
+---
+
+## 2. 后端数据契约
+
+### 2.1 新增方法：`VoyagerContext.get_docstring(schema_name: str) -> dict`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `docstring` | `str` | 类 `__doc__` 属性的原始字符串；若为 `None` 返回空串 `""`。仅在成功路径下出现。 |
+| `error` | `str` | 失败时出现，与现有 `get_source_code` 的错误信息格式一致（`"Invalid schema name format."` / `"Module not found: ..."` / `"Class not found: ..."` / `"Internal error: ..."`）。 |
+
+**实现要点**：复用 `self._resolve_object(schema_name)` 拿到类对象；`obj.__doc__ or ""` 即返回值。错误处理与 `get_source_code` 对称（4 个 except 分支）。
+
+### 2.2 新增端点：`POST /docstring`
+
+请求体：`{"schema_name": "<module.Class>"}`（与 `/source` 完全一致）
+
+响应：
+- 成功：`200 OK` · `{"docstring": "..."}`
+- schema 名格式非法：`400 Bad Request` · `{"error": "Invalid schema name format."}`
+- module/class 未找到：`404 Not Found` · `{"error": "..."}`
+- 其他异常：`400 Bad Request` · `{"error": "Internal error: ..."}`
+
+状态码映射规则与现有 `/source` 端点（`create_voyager.py:184-189`）**逐字对齐**——便于前端复用同一份错误处理代码。
+
+### 2.3 不修改的现有 dataclass
+
+| 类 | 文件 | 是否改动 | 理由 |
+|----|------|---------|------|
+| `SchemaNode` | `src/nexusx/voyager/type.py:57` | 否 | 决策 2（research.md）——避免 er-diagram 初始 payload 膨胀 |
+| `FieldInfo` | `src/nexusx/voyager/type.py:14` | 否 | 字段级 `desc` 仍走 Fields tab 路径，与 docstring 解耦 |
+| `Link` | `src/nexusx/voyager/type.py:82` | 否 | 边数据与本期无关 |
+
+---
+
+## 3. 前端 store 状态变更
+
+### 3.1 `store.js` 现有相关字段（**不改**）
+
+```js
+state.schemaDetail = {
+  schemaCodeName: "",     // 当前侧边栏指向的实体全限定名
+}
+state.rightDrawer = {
+  drawer: false,
+  width: 300,             // 当前拖拽设定的像素宽度
+  previousWidth: ...
+}
+```
+
+这些字段本期**完全不动**——`schemaDetail.schemaCodeName` 已足以驱动 `<about-display>` 内部 fetch；`rightDrawer.width` 仅是用户设定的目标值，clamp 由 vue-main.js 在事件回调中处理（见 §4）。
+
+### 3.2 `<about-display>` 组件内部状态（**新增**，不进全局 store）
+
+| ref | 类型 | 初始值 | 含义 |
+|-----|------|--------|------|
+| `docstring` | `string` | `""` | 从 `/docstring` 拿到的原始 docstring |
+| `loading` | `boolean` | `false` | 是否正在请求 |
+| `error` | `string \| null` | `null` | 失败时的错误文案；`null` 表示无错误 |
+| `mermaidErrors` | `Array<{index, message, source}>` | `[]` | 单块 mermaid 渲染失败的诊断信息（用于在 UI 中按块展示错误+折叠源码） |
+
+**为何不进全局 store**：这些是 `<about-display>` 私有的瞬时态，与 spec 005 的 `<related-entities-display>` 模式一致（后者也是组件内自管 state），保持对称。
+
+### 3.3 拖拽 clamp 派生量（**新增**，不持久化）
+
+`vue-main.js` 的 `startDragDrawer` 与新增的 `window.resize` 监听器内部使用：
+
+```js
+const MIN_WIDTH = 300                                  // 沿用现有常量
+const maxWidth  = () => Math.floor(window.innerWidth * 2 / 3)
+```
+
+`maxWidth` 是函数（实时计算），**不**写入 store、**不**持久化到 localStorage；每次拖拽/resize 调用时现取。
+
+---
+
+## 4. 实体验证规则
+
+### 4.1 docstring 字符串
+
+- **来源**：Python 类 `__doc__` 属性的原始字符串（含前导/尾随空白、含可能的 ```mermaid 围栏块）。
+- **不修剪**：后端返回原始 docstring，**不**做 `inspect.cleandoc` 或 lstrip；前端在渲染前可统一做一次 `cleandoc`-风格的缩进规整（用 `marked` 默认处理即可，无需自定义）。
+- **长度无上限**：极长 docstring（数千行）依赖外层容器 `overflow: auto` 滚动（spec 边界情况已约定）。
+
+### 4.2 schema_name 输入
+
+- 格式：必须是 `<module.path>.<ClassName>`，至少包含一个 `.`；与现有 `/source`、`/vscode-link` 的输入约束完全一致。
+- 不合法时返回 `400` + `Invalid schema name format.`，与现有端点行为对齐。
+
+### 4.3 拖拽宽度
+
+- 数值范围：`[300, floor(window.innerWidth × 2/3)]` 像素，闭区间。
+- 取整：必须为整数像素（避免亚像素渲染抖动）。
+- 持久化策略：本期**不**显式持久化（store 内存中即可）；若现有 `rightDrawer.width` 已有 localStorage 持久化机制则保留，但每次 hydrate 时必须 clamp 到当前 `floor(innerWidth × 2/3)`。
+
+---
+
+## 5. 状态机（无）
+
+本期无显式状态机。docstring 渲染是"取数据 → 单向渲染"的纯函数式管线；侧边栏宽度是用户拖拽驱动的连续数值。Mermaid **图内容**中可能包含状态机（如 `stateDiagram-v2`），但那是图本身的内容，不是本功能的状态机。
diff --git a/specs/006-voyager-about-tab/plan.md b/specs/006-voyager-about-tab/plan.md
new file mode 100644
index 0000000..e11b0c3
--- /dev/null
+++ b/specs/006-voyager-about-tab/plan.md
@@ -0,0 +1,98 @@
+# Implementation Plan：Voyager ER 图 —— About Tab（docstring + Mermaid）& 侧边栏宽度放宽
+
+**Branch**: `006-voyager-about-tab` | **Date**: 2026-07-01 | **Spec**: [spec.md](./spec.md)
+
+**Input**: Feature specification from `/specs/006-voyager-about-tab/spec.md`
+
+**Note**: 本计划由 `/speckit-plan` 产出，所有产物使用中文撰写（项目级约定）。
+
+## Summary
+
+为 Voyager ER 图侧边栏新增最左的 "About" tab，渲染当前所选 schema 模型类的 Python `__doc__`：先以 GitHub-Flavored Markdown 解析，再就地渲染 ```mermaid 围栏块为图表，并对危险 HTML 做清洗。另把侧边栏拖拽上限从固定 800px 改为视窗宽度 × 2/3，并在视窗缩放时动态 clamp。
+
+## Technical Context
+
+- **Language/Version**: Python 3.10+（后端）；Vanilla JS + Vue 3 + Quasar 2（前端，**无构建工具链**，第三方库以 `.min.js` 形式 vendored 在 `src/nexusx/voyager/web/`）
+- **Primary Dependencies**: FastAPI 0.135+（后端 HTTP）、Quasar / Vue 3（前端 UI，已 vendored）；本期新增前端依赖：`marked`、`dompurify`、`mermaid`，均以 vendored `.min.js` 形式引入，**不**通过 npm/构建工具链。
+- **Storage**: N/A（运行时反射，无持久化；docstring 取自 Python 类对象 `__doc__` 属性）
+- **Testing**: `pytest`（后端端点单测）；前端无自动化测试基线，依赖 `quickstart.md` 的人工验证流程
+- **Target Platform**: 开发机（Linux/macOS/Windows）启动 FastAPI 进程，浏览器访问 `http://localhost:<port>`；不做 SSR
+- **Project Type**: library（nexusx）+ 内嵌 web 服务子模块（voyager）
+- **Performance Goals**: `POST /docstring` 端点 p95 < 50ms（反射读 `__doc__`，无 IO）；前端 Markdown+Mermaid 渲染 < 500ms（典型 docstring < 10KB）
+- **Constraints**:
+  - **不引入前端构建工具链**——所有前端依赖必须能以 `<script src="...">` 直接加载（与现有 `quasar.min.js`、`vue.min.js` 一致）。
+  - 不破坏现有 `/source`、`/vscode-link`、`/er-diagram`、`/er-diagram-subgraph` 端点的契约。
+  - 不改变 SchemaNode 等已序列化的数据结构形状（避免破坏 web/schema 端点缓存）。
+- **Scale/Scope**: 单 voyager 实例，schema 数量 ~100 量级；docstring 长度 < 10KB（极少数超长文档走滚动条，不做分页）。
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+`.specify/memory/constitution.md` 当前仍是默认模板（项目尚未填入实际原则），无可对照的硬约束。**Gate 结果：通过（trivial）**。
+
+设计阶段产出的关键决策已记录到 `research.md`，并将在 Phase 1 收尾时复检——确认本期设计未引入需要被未来宪法（如"前端不允许引入构建工具链"、"端点必须做输入校验"等潜在原则）追溯约束的考量。
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/006-voyager-about-tab/
+├── plan.md              # 本文件
+├── research.md          # Phase 0：技术决策与备选方案
+├── data-model.md        # Phase 1：数据通路与状态字段
+├── quickstart.md        # Phase 1：end-to-end 验证手册
+├── contracts/           # Phase 1：接口契约
+│   ├── docstring-endpoint.md
+│   ├── about-tab-component.md
+│   └── sidebar-width-clamp.md
+├── checklists/
+│   └── requirements.md  # /speckit-specify 阶段产出
+└── tasks.md             # Phase 2（/speckit-tasks 产出，本期不生成）
+```
+
+### Source Code (repository root)
+
+```text
+src/nexusx/voyager/
+├── voyager_context.py            # 修改：新增 get_docstring(schema_name) 方法
+├── create_voyager.py             # 修改：新增 POST /docstring 路由
+└── web/
+    ├── index.html                # 修改：<head> 引入 marked/purify/mermaid；<body> 挂载 about-display
+    ├── vue-main.js               # 修改：放宽拖拽 clamp（800 → floor(innerWidth × 2/3)）；加 window resize 监听
+    ├── marked.min.js             # 新增（vendored）
+    ├── purify.min.js             # 新增（vendored）
+    ├── mermaid.min.js            # 新增（vendored）
+    └── component/
+        ├── schema-code-display.js # 修改：tab 栏最左加 About；只在 ER-diagram 模式显示
+        └── about-display.js       # 新增：docstring 加载 + Markdown/Mermaid 渲染组件
+
+tests/
+└── test_voyager_docstring.py     # 新增：POST /docstring 端点的 pytest 用例
+```
+
+**Structure Decision**：沿用现有的 "single library + vendored web assets" 模式（即 plan-template 的 Option 1）。后端只新增一个端点 + 一个 context 方法（与现有 `/source`、`/vscode-link` 对称），前端只新增一个组件 + 三个 vendored 库；不引入构建工具链，不拆 monorepo，不新增 service 层。
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+无 Constitution 违规，本表留空。
+
+## Phases
+
+### Phase 0 — Outline & Research
+
+详见 [research.md](./research.md)。本期 spec 没有 NEEDS CLARIFICATION 残留（clarify 阶段已全部解决）；Phase 0 主要解决"前端无构建工具链时如何引入 markdown/mermaid"、"docstring 数据通路（新端点 vs SchemaNode 增字段）"、"Mermaid 错误降级 UX"三个实现层面的决策。
+
+### Phase 1 — Design & Contracts
+
+- 数据模型与状态字段：[data-model.md](./data-model.md)
+- 接口契约：
+  - [contracts/docstring-endpoint.md](./contracts/docstring-endpoint.md) — 后端 `POST /docstring`
+  - [contracts/about-tab-component.md](./contracts/about-tab-component.md) — 前端 `<about-display>` 组件
+  - [contracts/sidebar-width-clamp.md](./contracts/sidebar-width-clamp.md) — 拖拽 clamp 规则
+- 端到端验证：[quickstart.md](./quickstart.md)
+
+Phase 1 收尾复检 Constitution：仍 trivial 通过（见上文）。
diff --git a/specs/006-voyager-about-tab/quickstart.md b/specs/006-voyager-about-tab/quickstart.md
new file mode 100644
index 0000000..43279f3
--- /dev/null
+++ b/specs/006-voyager-about-tab/quickstart.md
@@ -0,0 +1,172 @@
+# Quickstart：Voyager About Tab & 侧边栏宽度放宽 端到端验证
+
+**功能**：[spec.md](./spec.md) · **计划**：[plan.md](./plan.md) · **契约**：[contracts/](./contracts/)
+
+> 本文件是**验证手册**，不是实现指南。具体代码改动见 `tasks.md`（由 `/speckit-tasks` 产出）。
+
+---
+
+## 0. 前置条件
+
+- Python ≥ 3.10、`uv` 已安装
+- 现代 Chromium 系浏览器（Chrome / Edge / Brave）或 Firefox；mermaid 在 IE 上不支持（nexusx 也不支持 IE）
+- 视窗宽度 ≥ 1280px 的桌面环境（用于 Story 3 的拖拽验证；移动端不在本期范围）
+- 工作目录在 `/home/tangkikodo/nexusx/`（nexusx 仓库根）
+
+---
+
+## 1. 准备 demo 数据（给至少一个实体加 docstring）
+
+`demo/enterprise_voyager/models.py` 现有 38 个实体类，**目前都没有 docstring**——为了让 About tab 有内容可渲染，先给 `Employee` 加一段含 mermaid 的 docstring：
+
+```python
+class Employee(SQLModel, table=True):
+    """员工实体。
+
+    表示系统中的一个**在职**或**离职**员工。一个员工从属于一个 `Department`，
+    并通过 `Team` 关联到具体的协作小组。
+
+    ## 状态机
+
+    以下状态机描述了员工的生命周期：
+
+    ```mermaid
+    stateDiagram-v2
+        [*] --> Onboarding
+        Onboarding --> Active: 完成入职
+        Active --> OnLeave: 请假
+        OnLeave --> Active: 假期结束
+        Active --> Offboarding: 提交离职
+        Offboarding --> [*]: 完成离职
+        OnLeave --> Offboarding: 假期中离职
+    ```
+
+    ## 字段说明
+
+    | 字段 | 类型 | 说明 |
+    |------|------|------|
+    | `full_name` | `str` | 全名 |
+    | `department_id` | `int` | 所属部门 |
+
+    注意：本实体的 [审计日志](#) 由独立的 `AuditLog` 实体维护。
+    """
+    id: int | None = Field(default=None, primary_key=True)
+    full_name: str
+    # ...其余字段保持原样
+```
+
+> 提示：上面这段 docstring 故意覆盖了**标题 / 段落 / 加粗 / 行内代码 / 围栏代码块（mermaid + 表格）/ 表格 / 链接**——对应 FR-003 的所有元素；同时 mermaid 块用于验证 FR-004；最后的 `[审计日志](#)` 链接用于验证 FR-017（应可点击但不导航实体）。
+
+---
+
+## 2. 启动 voyager
+
+```bash
+uv run uvicorn demo.enterprise_voyager.voyager_demo:app --port 8010
+```
+
+浏览器打开：<http://localhost:8010/voyager>
+
+预期：看到 ER-diagram 默认 tab；30+ 个实体节点可见。
+
+---
+
+## 3. 验证路径
+
+### 路径 A —— Story 1：Markdown 渲染（P1）
+
+1. 在 ER 图上**双击** `Employee` 节点 → 侧边栏打开，默认在 Fields tab。
+2. 点击最左的 **About** tab → 应在 ~100ms 内看到：
+   - 一级标题"员工实体。"（H1 字号最大）
+   - 段落正文，加粗的"在职"/"离职"
+   - 二级标题"状态机"、"字段说明"
+   - 一个表格（字段 / 类型 / 说明 三列）
+   - 行内代码（`Department`、`Team`、`full_name` 等）以等宽字体背景色显示
+   - 末尾"审计日志"是一个可点击样式的链接（鼠标悬浮显示手指光标）
+3. **通过判据**：内容与 `Employee.__doc__` 字面一致；排版层级清晰；没有原始 Markdown 标记（如 `##`、`**`、`` ` ``）泄露到屏幕上。
+
+### 路径 B —— Story 2：Mermaid 图渲染（P2）
+
+1. 紧接路径 A，**滚动** About tab 内容到"状态机"小节。
+2. 应看到一张**可视化状态图**：7 个状态节点（`[*]`、`Onboarding`、`Active`、`OnLeave`、`Offboarding`）+ 6 条带标签的转移箭头（"完成入职"、"请假"等）。
+3. **不是**原始的 `stateDiagram-v2 ...` 源码。
+4. 表格、段落等其它元素保持正常渲染（不被 mermaid 干扰）。
+5. **通过判据**：节点不重叠到不可读；转移标签可见；整张图视觉一致。
+
+### 路径 C —— Mermaid 错误降级（FR-010）
+
+1. 编辑 `Employee.__doc__`，把 `stateDiagram-v2` 改成 `stateDiagram-v2` 但引入一处语法错误（例如删掉某个 `-->` 的尖括号、或加一行 `Active ->` 不写目标）：
+   ```python
+   Active -> Offboarding: 提交离职   # 故意用单箭头 -> 触发语法错
+   ```
+2. 重启服务（uvicorn 不会自动热重载 docstring；Ctrl+C 后重新 `uv run uvicorn ...`），刷新浏览器。
+3. 重新打开 `Employee` 的 About tab → 应看到：
+   - 一段红色或灰色错误提示，类似"该 Mermaid 图渲染失败：..."
+   - 下面有一个折叠的"查看源码"小三角，点击后**展开**显示原始 mermaid 源码（可复制到 <https://mermaid.live> 调试）
+   - docstring 的其它部分（标题、表格、链接）**仍正常渲染**
+4. **通过判据**：单块 mermaid 失败不污染其它内容；折叠默认收起；错误信息明确（不是空白、不是页面崩溃）。
+
+### 路径 D —— 空 docstring / 错误状态（FR-005、FR-006、FR-007）
+
+1. **空 docstring**：双击任意一个**没有** docstring 的实体（例如 `Organization`，默认就空）→ 切到 About tab → 应看到"该实体暂无 docstring。"文案，**不是**空白。
+2. **错误状态**：在浏览器 DevTools 的 Network 面板，把 `/docstring` 请求改为"Block request domain"再切换实体 → 应看到红色错误文案（不是空白、不是"加载中"假象）。
+3. **加载指示**：在 DevTools 给 `/docstring` 加 "Slow 3G" 节流 → 切换实体 → 应在内容上方看到一条 indeterminate 进度条。
+4. **通过判据**：三态（空/错/加载）视觉可区分。
+
+### 路径 E —— Story 3：侧边栏宽度放宽（P2）
+
+1. 把浏览器视窗拉到 **1920px 宽**（或用 DevTools 设备工具栏精确设定）。
+2. 双击 `Employee` 打开侧边栏 → 默认宽度 ~300px。
+3. **按住**侧边栏左边缘的拖拽手柄向左拖 → 应能拖到 **~1280px** 宽（=`floor(1920 × 2/3)`），不再被旧的 800px 上限卡住。
+4. 拖到极限后，About tab 中的表格、Mermaid 图应能完整展示，**无需横向滚动**。
+5. **向右**拖回 → 应能拖到下限 ~300px，不能更小。
+6. **视窗缩放 clamp**：把视窗从 1920px 缩到 **1200px** → 侧边栏宽度应自动从 1280px 收缩到 ~800px（=`floor(1200 × 2/3)`），不会出现"侧边栏比画布还宽"的破损布局。
+7. **通过判据**：上限跟随视窗动态变化；下限稳定；resize 后布局完整。
+
+### 路径 F —— 切换实体保留激活 tab（FR-008）
+
+1. 当前在 `Employee` 的 About tab。
+2. 在画布上**单击**（注意：侧边栏已打开，单击即可触发）另一个实体 `Department`。
+3. **通过判据**：
+   - 侧边栏停留在 About tab（不会跳回 Fields）
+   - About tab 内容刷新为 `Department` 的 docstring（如果 Department 也没有 docstring，则显示空状态文案）
+   - 主画布高亮切换到 `Department` 的相关实体
+
+### 路径 G —— 链接不导航实体（FR-017）
+
+1. 回到 `Employee` 的 About tab，滚到底部的 `[审计日志](#)` 链接。
+2. 点击该链接。
+3. **通过判据**：
+   - 不触发对 `AuditLog` 实体的跳转
+   - 主画布选中状态仍是 `Employee`
+   - 侧边栏仍是 `Employee` 的 About tab
+   - 由于 href 是 `#`，浏览器可能在 URL 末尾加 `#`——这是可接受的
+
+---
+
+## 4. 后端单测（可选但推荐）
+
+```bash
+uv run pytest tests/test_voyager_docstring.py -v
+```
+
+预期：5 条用例全绿（happy path / 空 docstring / 非法 schema_name / module not found / class not found），详见 [contracts/docstring-endpoint.md](./contracts/docstring-endpoint.md) §测试覆盖。
+
+---
+
+## 5. 故障排查
+
+| 现象 | 可能原因 | 处理 |
+|------|---------|------|
+| About tab 不显示 | `showAbout` prop 未传 true | 检查 `index.html` 中 `<schema-code-display :show-about="store.state.mode === 'er-diagram'">` 是否生效 |
+| Markdown 渲染但 mermaid 不渲染 | `mermaid.initialize` 未调用 / `startOnLoad` 未关 | 看浏览器 console，应有 mermaid 的告警；确认 `vue-main.js` 中 `mermaid.initialize({ startOnLoad: false, theme: 'default' })` 已执行 |
+| 整个 About tab 空白 + console 报 XSS | DOMPurify 配置过严，剥离了 mermaid 需要的属性 | 在 `DOMPurify.sanitize` 配置 `ADD_ATTR: ['class','target','rel','href']` |
+| 拖拽仍卡在 800px | 浏览器缓存了旧 `vue-main.js` | DevTools → Application → Service Workers → Unregister；或硬刷新（Ctrl+Shift+R） |
+| 视窗缩放后侧边栏比画布还宽 | resize 监听未挂载 | 检查 `vue-main.js` 是否新增了 `window.addEventListener('resize', onWindowResize)`；确认 `onWindowResize` 内只压缩不扩展 |
+| docstring 显示原始 `__doc__`，缩进很怪 | 后端做了 `inspect.cleandoc` 或前端 marked 未配置 | 后端**不**做 cleandoc；前端依赖 marked 默认行为；若仍异常，前端在 parse 前 `docstring.replace(/^\s+/gm, '')` 试验性修复 |
+
+---
+
+## 6. 通过判据汇总
+
+如果上述路径 A–G 全部通过、后端单测全绿，则本功能视为**端到端验证完成**，可进入 `/speckit-tasks` 拆分实现任务，或直接交付实现。
diff --git a/specs/006-voyager-about-tab/research.md b/specs/006-voyager-about-tab/research.md
new file mode 100644
index 0000000..87526b0
--- /dev/null
+++ b/specs/006-voyager-about-tab/research.md
@@ -0,0 +1,122 @@
+# Phase 0 — 研究与决策：Voyager About Tab & 侧边栏宽度放宽
+
+**功能**：[spec.md](./spec.md) · **计划**：[plan.md](./plan.md)
+
+**调研范围**：spec 中无 NEEDS CLARIFICATION 残留（已在 `/speckit-clarify` 阶段全部解决）；本文件聚焦三个**实现层面**的决策——前端依赖引入方式、docstring 数据通路、Mermaid 错误降级 UX；外加拖拽 clamp 的具体公式。
+
+---
+
+## 决策 1：前端依赖（marked / DOMPurify / mermaid）的引入方式
+
+**Decision**：以 vendored `.min.js` 文件直接 `<script>` 引入到 `src/nexusx/voyager/web/index.html`，与现有 `quasar.min.js`、`vue.min.js` 模式一致。**不**引入 npm / 打包器 / ES 模块构建工具链。
+
+**Rationale**：
+- 现有 voyager 前端就是 vanilla JS + vendored 库 + 全局变量（`window.Vue`、`window.Quasar`）模式，没有任何构建步骤；贸然引入构建工具链会破坏现有开发体验与发布流程（CLAUDE.md 内项目约束："不引入前端构建工具链"是潜在原则）。
+- 三个库都官方提供 UMD/IIFE standalone 版本（marked、DOMPurify、mermaid 均有 `dist/*.min.js`），可直接 `<script src>` 加载并暴露全局（`window.marked`、`window.DOMPurify`、`window.mermaid`）。
+- 体积可接受：marked ~40KB、DOMPurify ~20KB、mermaid ~1.5MB（含所有图表类型）。voyager 是开发者工具，首屏体积不是核心约束；若担心，可后续切到 mermaid 的按需子集构建，但本期不做。
+
+**Alternatives considered**：
+- **引入 Vite/esbuild + npm**：被否——破坏现有无构建模式，且要求所有 nexusx 使用者装 Node 工具链。
+- **后端渲染 Markdown/Mermaid 为 HTML/SVG 再发到前端**：被否——Mermaid 渲染需要浏览器字体度量，服务端渲染需引入 puppeteer，过重；Markdown 服务端渲染虽可行（`markdown-it` 也有 Python 实现 `markdown` 包），但失去客户端切换实体时的即时渲染优势。
+- **CDN 引入**：被否——离线场景（开发机无外网）会断；nexusx 已 vendored 其它库，保持一致。
+
+---
+
+## 决策 2：docstring 数据通路（新端点 vs SchemaNode 增字段 vs 复用 /source）
+
+**Decision**：**新增独立端点** `POST /docstring`，请求体 `{schema_name: str}`、响应 `{docstring: str}`（或 `{error: str}`）。后端在 `VoyagerContext` 上新增方法 `get_docstring(schema_name)`，复用现有 `_resolve_object(schema_name)` 拿到类对象，返回 `obj.__doc__ or ""`。**不**修改 SchemaNode / 不改 `/source` 响应。
+
+**Rationale**：
+- 与现有 `/source`、`/vscode-link` 三个对称端点的模式完全一致：on-demand 拉取，按 schema_name 解析类对象，反射读属性。代码量最小、最易测、最不破坏现有契约。
+- 把 docstring 塞进 SchemaNode（决策 A）会**全量预取**所有 schema 的 docstring 到 er-diagram 初始 payload 里；对一个含 ~100 实体的 schema，docstring 总量可达几十 KB 到上百 KB，绝大多数用户从不打开 About tab，浪费明显。
+- 复用 `/source` 端点（决策 C）让该端点的响应多一个字段，违反单一职责；且 `/source` 已经被 service worker 缓存（`web/sw.js:132`），改动响应 shape 需要同步改 sw 缓存键，得不偿失。
+- 前端组件 `about-display.js` 已经独立成单组件，自己发 fetch、自己管 loading/error 状态，与 `related-entities-display.js` 的模式一致；新端点正好对上这个组件的生命周期。
+
+**Alternatives considered**：
+- **A. SchemaNode 新增 `docstring: str = ''` 字段**：见上，被否（payload 膨胀、破坏现有序列化 shape）。
+- **C. 扩展 `/source` 响应为 `{source_code, docstring}`**：见上，被否（破坏 sw 缓存契约 + 单一职责）。
+
+---
+
+## 决策 3：Mermaid 渲染管线与错误降级
+
+**Decision**：渲染管线采用 "marked 解析 → DOMPurify 清洗 → mermaid.run() 后处理"，对每段 mermaid 块**单独 try/catch**，失败时把该块替换为 "错误提示 + 默认折叠的原始源码" 的 DOM 节点。
+
+具体步骤：
+1. 用 `marked.parse(docstring)` 解析整段 docstring 为 HTML 字符串。mermaid 围栏块此时被解析为 `<pre><code class="language-mermaid">...源码...</code></pre>`。
+2. 在 marked 输出后、注入 DOM 前，用 DOMPurify 清洗整段 HTML，配置 `ADD_TAGS: ['pre','code']`、`ADD_ATTR: ['class']`，允许 mermaid 后续需要的 class 属性通过。
+3. 把清洗后的 HTML 注入容器，然后用 `container.querySelectorAll('code.language-mermaid')` 找到所有 mermaid 源码块，**逐个**：
+   - 取出源码文本，包成 `<div class="mermaid">源码</div>`，替换原 `<pre><code>`。
+   - 调用 `mermaid.parse(sourceText)` 做语法校验：
+     - 通过 → 让 `mermaid.run({ nodes: [那个 div] })` 渲染为 SVG。
+     - 失败 → 把该 div 替换为 `<div class="mermaid-error">错误提示 + <details><summary>查看源码</summary><pre>源码</pre></details></div>`。
+4. 其余代码块（`language-python` 等）保持 `<pre><code>` 不动。
+
+**Rationale**：
+- "整段清洗再后处理 mermaid" 比 "用 marked extension 拦截 mermaid 块" 更简单直接——extension API 需要熟悉 marked 内部，而 querySelector 方案 5 行代码搞定。
+- 单块 try/catch 是 FR-010"不影响 docstring 其他部分"的字面实现；只要每个 mermaid 块独立处理，一个失败不影响其它。
+- "默认折叠" 用原生 `<details><summary>` 元素，零 JS、键盘可访问、不引入额外 UI 库。
+- 用 `mermaid.parse(sourceText)` **预先**校验语法（而不是直接 `mermaid.run()` 让它内部抛错），可以拿到结构化的错误信息（行号、期望 token），便于在错误提示里展示。
+
+**Alternatives considered**：
+- **marked extension 在解析阶段拦截 mermaid**：更"优雅"但实现复杂度高、对 marked 版本敏感；本期采用更朴素的 querySelector 方案。
+- **失败时静默回退为原始代码块**：违反 FR-010"明确的错误提示"。
+- **失败时全屏 alert/console.error**：过于打扰；用就地 `<details>` 折叠更合适。
+
+---
+
+## 决策 4：Markdown 链接点击行为（不导航实体）
+
+**Decision**：DOMPurify 配置 `ADD_ATTR: ['target','rel','href']`，并对所有 `<a>` 注入 `target="_blank" rel="noopener noreferrer"`。不在前端做任何"识别实体引用并触发 store action 跳转"的逻辑——FR-017 明文规定不导航。
+
+**Rationale**：
+- 行为与 spec 决议一致；实现最简。
+- 强制所有链接新 tab 打开 + `rel="noopener"` 防止 reverse tabnabbing，与 FR-009（XSS 清洗）的安全基调一致。
+
+**Alternatives considered**：
+- **识别 `entity:module.Class` 形态的链接并触发跳转**：被否——FR-017 已明确不在本期范围。
+
+---
+
+## 决策 5：侧边栏拖拽 clamp 公式
+
+**Decision**：把 `vue-main.js:269` 的 `Math.max(300, Math.min(800, startWidth + deltaX))` 改为：
+
+```js
+const min = 300
+const max = Math.floor(window.innerWidth * 2 / 3)
+const newWidth = Math.max(min, Math.min(max, startWidth + deltaX))
+```
+
+并新增 `window.addEventListener('resize', ...)` 监听器：触发时若 `store.state.rightDrawer.width > floor(innerWidth × 2/3)`，把 store 中的 width clamp 到新上限。
+
+**Rationale**：
+- 下限 300px 保持现状（与 spec 假设一致：不引入新的更小下限）。
+- 上限 `floor(W × 2/3)` 是 spec 验收场景 1 的字面实现；`floor` 取整避免亚像素抖动。
+- resize 监听是 FR-015 的字面实现——已设定的宽度超过新上限时主动 clamp，避免"侧边栏比画布还宽"的破损布局。
+- 不持久化"上限值"——上限始终从 `window.innerWidth` 实时计算，刷新页面/重启浏览器后自动跟随当前视窗。
+
+**Alternatives considered**：
+- **使用 CSS `max-width: 66.67vw`** 而非 JS clamp：被否——Quasar `q-drawer` 的 `:width` prop 是 JS 控制的像素值，CSS max-width 会与 Quasar 内联 style 冲突；且 FR-015 要求"store 中的 width 值也 clamp"，必须在 JS 层处理。
+- **使用 ResizeObserver 监听 drawer 本身**：被否——drawer 大小是被 width prop 控制的因变量，监听它会循环；监听 `window.resize` 才是正确的"自变量"。
+
+---
+
+## 决策 6：Mermaid 主题与初始化时机
+
+**Decision**：在 `index.html` 引入 `mermaid.min.js` 后，在 `vue-main.js` 顶部（或 `app.js` 等全局初始化位置）调用一次 `mermaid.initialize({ startOnLoad: false, theme: 'default' })`。`startOnLoad: false` 关掉自动扫描，改由 `about-display.js` 在内容注入后显式 `mermaid.run({ nodes })`。主题用 `default`（light）与应用整体基调一致。
+
+**Rationale**：
+- `startOnLoad: true` 会在 DOMContentLoaded 时全文档扫描 `.mermaid` 节点，但 about-display 的内容是异步 fetch 后才注入的，自动扫描会漏；必须 `false` + 手动 `run()`。
+- 主题不暴露成可配置项（spec 假设：跟随应用主题，不引入新主题切换）；如未来引入暗色主题再扩展。
+
+---
+
+## 待 Phase 2（/speckit-tasks）处理的实现细节
+
+以下不在本期 plan 范围，留给 tasks 阶段拆分：
+
+- vendored 库的具体版本号（marked ≥ 12、DOMPurify ≥ 3、mermaid ≥ 10 即可，三者互相兼容）。
+- `<about-display>` 组件具体的 props 名称（倾向：`schemaName: String`、`visible: Boolean`，与 `related-entities-display` 对齐）。
+- pytest 用例的精确覆盖矩阵（happy path / 空 docstring / schema 不存在 / module import 失败 4 条够用）。
+- whether to add a `<about-display>` service-worker prefetch entry（倾向：不加，docstring 端点是 on-demand，不该预缓存）。
diff --git a/specs/006-voyager-about-tab/spec.md b/specs/006-voyager-about-tab/spec.md
new file mode 100644
index 0000000..8042b8a
--- /dev/null
+++ b/specs/006-voyager-about-tab/spec.md
@@ -0,0 +1,148 @@
+# 功能规格说明：Voyager ER 图 —— About Tab（docstring + Mermaid 渲染）& 侧边栏宽度放宽
+
+**功能分支**：`006-voyager-about-tab`
+
+**创建日期**：2026-07-01
+
+**状态**：草稿
+
+**输入**：用户描述："我需要在 voyager 的 er diagram 中，双击 entity 之后提供的信息做一个增强，具体做法是添加一个单独的 about tab，里面显示的内容是 docstring，但是需要支持 markdown 渲染，注意要支持 mermaid 的渲染，因为里面会添加一些状态转移之类的可视化信息。另外，我需要放宽侧边栏的拖拽区间，现在允许值太小了，我要允许它往左最多占用 2/3 的宽度。"
+
+## 澄清记录
+
+### Session 2026-07-01
+
+- Q: 新增的 About tab 应该出现在侧边栏 tab 栏的哪个位置？首次打开侧边栏时哪个 tab 默认激活？ → A: 最左（出现在 Fields 之前），且**不改变**默认激活策略——Fields 仍是侧边栏首次打开时的默认激活 tab。语义上 About 是总览/入口放最前，但不打扰现有用户对"打开侧边栏看 Fields"的肌肉记忆。
+- Q: About tab 中渲染的 docstring 从哪里取？ → A: 取自 schema 模型类的 Python `__doc__`（类级文档字符串）。这意味着后端需要在 schema 元数据中加入 docstring 字段，或新增一个返回该 docstring 的端点；不与字段级 `description` 混用，也不做 "__doc__ 空时回退到 description" 的合并。
+- Q: docstring 中的 Markdown 链接点击后应该发生什么？ → A: 全部按普通 `<a>` 标签渲染，**不触发**任何对其他实体的跳转——外部 http/https 链接照常在新 tab 打开，其他链接渲染为可点击但不导航。与 Mermaid 只读、Related Entities 只读保持一致；实体内导航是后续 feature，不在本期范围。
+- Q: Mermaid 语法错误导致渲染失败时，About tab 该如何展示该段？ → A: 错误提示 + **默认折叠**的原始 mermaid 源码。错误提示让用户知道图挂了；折叠源码让有需要的用户可以展开查看/复制到外部工具（如 mermaid.live）调试；默认折叠避免污染 docstring 阅读流。
+
+## 用户场景与测试 *(必填)*
+
+### 用户故事 1 —— 在 About tab 中以富文本形式阅读实体 docstring（优先级：P1）
+
+开发者或数据探索者正在 Voyager 的 ER 图 tab 中浏览 schema。他们双击某个实体 `X`，侧边栏打开（包含 Fields / Source Code / Related Entities 三个 tab）。他们希望切换到一个新的 "About" tab，看到 `X` 这个实体类对应 docstring 的**人类可读渲染**——标题、段落、列表、表格、行内代码、代码块等都按 GitHub-Flavored Markdown 的方式排版——而不是一段枯燥的纯文本。这样他们能在不打开 Source Code、不读 Python 源码的前提下，快速理解这个实体"是什么、用来做什么、有哪些约束"。
+
+**为什么是这个优先级**：这是本功能的核心价值——把已有的 docstring 从"埋在源码里、几乎没人读"变成"侧边栏里一眼可见的富文本说明"。即使不渲染 Mermaid、即使侧边栏宽度不变，仅 Markdown 渲染本身就能独立交付可感知的价值，因此是 P1。
+
+**独立测试**：在 `demo/enterprise_voyager` 上打开 ER 图，双击一个 docstring 非空且含有标题/列表/代码块的实体 `X`，切换到 "About" tab；验证内容以排版良好的富文本呈现（标题字号有层级、列表有缩进、代码块有等宽字体），且与该实体类 `__doc__` 中的内容一致。
+
+**验收场景**：
+
+1. **给定** ER 图 tab 已加载某个 schema，**当** 用户双击实体 `X` 并切换到 "About" tab，**那么** tab 内展示 `X` 对应 docstring 的 Markdown 渲染结果，包含至少以下元素的合理排版：标题、段落、无序/有序列表、行内代码、围栏代码块、表格。
+2. **给定** "About" tab 已为实体 `X` 打开，**当** 用户在画布上单击（侧边栏已打开时）或双击（侧边栏已关闭时）另一个实体 `Y`，**那么** About tab 立即刷新为 `Y` 的 docstring 渲染结果。
+3. **给定** 实体 `X` 的 docstring 为空（或不存在），**当** 用户打开 "About" tab，**那么** tab 内展示一句明确、可读的空状态文案（如"该实体暂无 docstring"），让用户能区分"没有 docstring"和"加载中"或"出错"。
+4. **给定** docstring 数据请求失败，**当** "About" tab 被激活，**那么** tab 内展示一个明确、可读的错误状态，与空状态相区分（不悄悄显示空白）。
+5. **给定** "About" tab 渲染期间数据仍在加载，**当** 用户切换到该 tab，**那么** 出现可见的加载指示（如进度条或 spinner），避免误以为内容已加载完毕。
+6. **给定** 用户在 About / Fields / Source Code / Related Entities 之间切换当前激活 tab，**当** 然后切换到另一个实体，**那么** 当前激活的 tab 保留（沿用 spec 005 FR-012 的策略），即如果 About 是激活态，切换实体后新实体的 About tab 直接呈现。
+7. **给定** 实体 `X` 的 docstring 含 Markdown 链接（含指向其他实体的相对链接、外部 https 链接），**当** 用户在 About tab 内点击其中任意一个链接，**那么** 外部 https 链接照常在新标签页打开；其他链接**不**触发对其他实体的导航，主画布选中状态保持 `X` 不变，侧边栏仍停留在 `X` 的 About tab。
+
+---
+
+### 用户故事 2 —— 在 About tab 中查看 Mermaid 图表（如状态转移图）（优先级：P2）
+
+在阅读 docstring 时，文档作者常常会把"实体生命周期"、"状态转移"、"与其他角色的交互流程"这类信息写成 Mermaid 图（`stateDiagram-v2`、`flowchart`、`sequenceDiagram` 等）。用户希望在 About tab 中，docstring 里所有 ```mermaid 围栏代码块都被**就地渲染成可视化图表**——而不是以原始 Mermaid 源码文本展示。这样他们能直接看到一张图，而不用心智地把源码翻译成结构。
+
+**为什么是这个优先级**：Mermaid 渲染能显著提升含图 docstring 的可读性，但即使 Mermaid 不渲染（退化成代码块），Story 1 的纯 Markdown 价值也已交付，因此是 P2。
+
+**独立测试**：人为构造一个实体 `X`，其 docstring 内含至少一个 ```mermaid 围栏代码块（例如 `stateDiagram-v2` 表达状态转移），打开 "About" tab；验证该代码块被渲染为一张可视化的状态图（节点、边、标签可见），而非原始文本；并验证同一个 docstring 中的非 mermaid 围栏代码块（如 ```python）仍按普通代码块渲染、不被误当作图表。
+
+**验收场景**：
+
+1. **给定** 实体 `X` 的 docstring 含有至少一段 ```mermaid 围栏代码块（合法语法），**当** "About" tab 被渲染，**那么** 该段被渲染为一张可视化 Mermaid 图（节点/边/标签清晰可辨），而不是原始源码。
+2. **给定** docstring 同时含有 ```mermaid 与 ```python（或其他语言）围栏代码块，**当** "About" tab 被渲染，**那么** mermaid 块渲染为图表、其他代码块按等宽字体原样展示，二者不互相干扰。
+3. **给定** docstring 中的 mermaid 源码存在语法错误，**当** "About" tab 试图渲染该图，**那么** 该段降级为"错误提示 + 默认折叠的原始源码"组合（错误信息明确、源码默认折叠、可手动展开复制），不出现整页崩溃，并保留 docstring 其余部分（含其他 mermaid 块）的正常渲染。
+4. **给定** 多个 mermaid 围栏块出现在同一 docstring，**当** About tab 渲染，**那么** 每一块都被独立渲染为独立的图表，互不影响。
+5. **给定** mermaid 图被成功渲染，**当** 用户切换实体后再切回 `X`，**那么** 图表能正确重新渲染（不出现残留、空白或重复渲染）。
+
+---
+
+### 用户故事 3 —— 拖宽侧边栏至最多占视窗 2/3 宽度（优先级：P2）
+
+无论是阅读 About tab 中较宽的 Markdown 表格、Mermaid 图，还是查看 Source Code 中较长的 Python 行，用户都常常觉得侧边栏太窄、内容被频繁换行或横向滚动。当前侧边栏的拖拽区间上限定死了（在视窗足够大时仍偏窄）。用户希望能把侧边栏**往左拖到最多占视窗宽度的 2/3**，从而在阅读宽内容时拥有足够横向空间；同时保留下限，避免侧边栏过窄不可用。
+
+**为什么是这个优先级**：放宽拖拽区间能立刻提升所有 tab（About / Fields / Source Code / Related Entities）的可读性，但本身不引入新功能，是体验增强，因此 P2。
+
+**独立测试**：在足够宽的桌面上（例如 1920px 视窗），双击实体打开侧边栏，按住拖拽手柄向左拖；验证可以把侧边栏宽度拖到至少 1280px（≈ 1920 × 2/3）附近；再向右拖回；验证下限仍能拖到合理最小宽度（不挤崩 UI）。
+
+**验收场景**：
+
+1. **给定** 一个宽度为 `W` 像素的视窗，**当** 用户拖动侧边栏拖拽手柄向左到极限位置，**那么** 侧边栏宽度不超过 `floor(W × 2/3)`（允许 ±1px 取整误差）。
+2. **给定** 视窗宽度为 1920px，**当** 用户拖到极限，**那么** 侧边栏可达到约 1280px 宽（不再被旧有的固定上限卡住）。
+3. **给定** 用户拖拽侧边栏，**当** 向右拖到下限，**那么** 侧边栏宽度不低于一个合理的最小可用宽度（不破坏 Fields/Source Code 等已有 tab 的可用性）。
+4. **给定** 侧边栏已被拖到当前视窗的 2/3 宽度，**当** 用户缩小浏览器视窗（例如从 1920px 缩到 1200px），**那么** 侧边栏宽度自动收缩到新的 2/3 上限（≈ 800px），不会出现"侧边栏比画布还宽"的破损布局。
+5. **给定** 用户刷新页面或重新打开侧边栏，**当** 上一次拖拽设定了一个 ≥ 当前 2/3 上限的宽度（因视窗变小），**那么** 重新打开时侧边栏宽度被 clamp 到当前 2/3 上限，不会超出。
+6. **给定** 侧边栏处于关闭状态或刚打开的初始宽度（约 300px），**当** 用户正常使用、不主动拖拽，**那么** 侧边栏宽度行为与之前一致（这一故事不改变默认宽度，只放宽上限）。
+
+### 边界情况
+
+- docstring 完全为空、或仅为空白字符：显示明确空状态文案（见 FR-006）。
+- docstring 仅含 Mermaid、没有任何 Markdown 段落：About tab 仍渲染该 Mermaid 图，不应因缺少段落而崩溃。
+- docstring 含有 Mermaid 之外的不受支持图表语言（如 `plantuml`、`dot`）：按普通代码块展示，不渲染。
+- docstring 含有恶意或破坏性 HTML（`<script>`、`onerror=` 等）：渲染管线必须清洗/剥离危险内容，不允许执行任意脚本（见 FR-009）。
+- docstring 含有外部图片：默认允许渲染（标准 Markdown 图片语法），但失败时降级为断图图标，不影响其余内容。
+- docstring 极长（数千行）：About tab 内容区可纵向滚动，不撑破侧边栏；不做强制分页。
+- 同时多个 Mermaid 图、且其中一个语法错误：错误的那个降级为错误提示，其余正常渲染（见 Story 2 验收场景 3）。
+- 视窗非常窄（移动端 / 小窗）：2/3 上限仍可能过小，但下限保证最小可用宽度；超出当前上限时按上限 clamp。
+- 视窗非常大（4K 屏）：2/3 上限可能让侧边栏显得过宽，但这是用户主动拖拽的结果；不主动施加新的更小上限。
+- 用户拖到极限后切换实体：宽度保持，不被重置；切换实体只刷新内容，不动宽度。
+- 用户拖到极限后刷新页面：宽度若仍在当前 2/3 上限内则保持；超出则 clamp 到当前上限。
+- About tab 被激活时实体被删/重命名：展示明确错误状态，不要悄悄空白。
+- 在 About tab 已打开时切换到另一个 tab 再切回：内容仍应保留（不重复发请求），渲染结果不丢失。
+
+## 需求 *(必填)*
+
+### 功能需求
+
+#### About Tab（docstring + Markdown + Mermaid）
+
+- **FR-001**：Voyager ER 图侧边栏（双击实体后打开、当前含 Fields / Source Code / Related Entities 三个 tab 的那个面板）必须额外提供一个名为 "About" 的 tab；该 tab 在 ER-diagram 模式下可见，且在 tab 栏中位于最左位置（出现在 Fields 之前）。侧边栏首次打开时的默认激活 tab 维持 Fields，不因新增 About 而改变。
+- **FR-002**：About tab 的内容必须取自当前所选 schema 模型类的 Python `__doc__`（即类级文档字符串），且每次所选实体变化时刷新。**不与**字段级 `description` 字段混用，也不做"类 `__doc__` 空时回退到 description"的合并；字段级 `description` 仍按现有方式在 Fields tab 内呈现。
+- **FR-003**：About tab 必须把 docstring 作为 GitHub-Flavored Markdown 渲染，至少正确呈现：标题（H1–H6）、段落、无序/有序列表、行内代码、围栏代码块（含语法高亮可选）、表格、链接、引用块、加粗/斜体、水平分割线。
+- **FR-004**：About tab 必须把 docstring 内的所有 ```mermaid 围栏代码块就地渲染为可视化图表（覆盖至少 `stateDiagram-v2`、`flowchart`、`sequenceDiagram` 三种常见类型），而非展示原始源码。
+- **FR-005**：当 docstring 为空、缺失、或仅含空白字符时，About tab 必须展示一句明确、可读的空状态文案（如"该实体暂无 docstring"），让用户能区分"没有 docstring"与"加载中"或"出错"。
+- **FR-006**：当 docstring 数据无法获取时，About tab 必须展示一个明确、可读的错误状态，且与空状态相区分。
+- **FR-007**：在 About tab 内容加载期间，必须展示可见的加载指示（如线性进度条或 spinner）。
+- **FR-008**：About tab 的内容必须随所选实体变化而刷新；并且切换实体时，若 About 是当前激活 tab，新实体打开后 About 仍为激活 tab（沿用 spec 005 FR-012 的"切换实体保留激活 tab"策略，对四个 tab 一视同仁）。
+- **FR-009**：About tab 的 Markdown/HTML 渲染管线必须对危险内容做清洗（剥离 `<script>`、事件处理器属性如 `onerror`、`javascript:` 链接等），防止 docstring 中的任意文本被执行为脚本。
+- **FR-017**：docstring 中的所有 Markdown 链接必须按普通 `<a>` 标签渲染：外部 `http`/`https` 链接照常在新 tab 打开；其他链接（含看上去像实体引用的相对链接）渲染为可点击样式但**不**触发对其他实体的导航、不改变主画布选中状态。About tab 与 Mermaid 图、Related Entities 子图一样只读。
+
+#### Mermaid 渲染
+
+- **FR-010**：当 docstring 中某段 mermaid 源码存在语法错误导致渲染失败时，该段必须降级展示为"**错误提示 + 默认折叠的原始 mermaid 源码**"组合：错误提示明确告知该图渲染失败；折叠区在用户主动展开后展示原始源码以便复制到外部工具调试；默认折叠状态不污染 docstring 的整体阅读流。该降级不得影响 docstring 其他部分（含其他 mermaid 块）的正常渲染。
+- **FR-011**：渲染后的 Mermaid 图必须只读——不响应点击导航、不改变主画布选中状态、不触发任何对其他实体的跳转（与 spec 005 Related Entities 的"只读"策略一致）。
+- **FR-012**：合法的 Mermaid 图必须能正确呈现节点、边、标签、方向（左/右/上/下），并且对状态图的状态名、转移标签、注解（note）等元素做合理排版，不出现节点重叠到不可读或边标签丢失。
+
+#### 侧边栏宽度放宽
+
+- **FR-013**：侧边栏拖拽的宽度上限必须从当前固定的 800px 改为"当前视窗宽度的 2/3"（动态计算），允许用户把侧边栏拖到该上限以内任意宽度。
+- **FR-014**：侧边栏拖拽的宽度下限必须保留为一个合理的最小可用值（不大于原下限，避免侧边栏被拖到无法使用），不引入新的更小下限。
+- **FR-015**：当视窗尺寸变化（缩放浏览器窗口、改变分屏等）导致已设定的侧边栏宽度超过新的 2/3 上限时，侧边栏实际渲染宽度必须自动 clamp 到新上限，避免侧边栏溢出/遮挡画布。
+- **FR-016**：放宽上限不应改变侧边栏的默认初始宽度、不应改变侧边栏的折叠/展开行为、不应改变其他与宽度无关的现有交互。
+
+### 关键实体
+
+- **实体 docstring**：所选 schema 模型类在源码层面写下的文档字符串，作为 About tab 的内容来源；可以是纯文本、Markdown、或包含 mermaid 围栏块的复合文本。
+- **渲染后的 Markdown 内容**：docstring 经 Markdown 渲染管线产出的富文本视图，包含段落、列表、表格、代码块，以及由 mermaid 块进一步渲染而成的内嵌图表。
+
+## 成功标准 *(必填)*
+
+### 可衡量结果
+
+- **SC-001**：在 `demo/enterprise_voyager` 中，用户能在双击实体后于侧边栏内打开 "About" tab，并在 1 次点击内看到该实体 docstring 的 Markdown 渲染结果，而无需打开 Source Code 或离开侧边栏。
+- **SC-002**：对所有 docstring 中包含 Mermaid 状态/流程图的实体，用户在 About tab 中看到的是**可视化图表**而非源码，可一眼识别节点与转移关系（与读原始 mermaid 源码相比，理解时间显著下降）。
+- **SC-003**：在宽度为 1920px 的桌面视窗下，用户能把侧边栏拖宽到至少约 1280px，且在该宽度下阅读宽表格、宽 Mermaid 图、长 Python 行时不再需要横向滚动（或显著减少横向滚动次数）。
+- **SC-004**：放宽拖拽上限后，在常见桌面分辨率（1280px–2560px）下侧边栏与主画布布局不出现破损（无重叠、无溢出、无视窗缩放后的"侧边栏比画布还宽"异常）。
+- **SC-005**：对所有 docstring 为空或缺失的实体，用户在 About tab 中看到的是一句明确的空状态文案，而不是空白、卡顿或"加载中"假象。
+
+## 假设
+
+- About tab 与 Related Entities 一样，仅在 ER-diagram 模式下显示（其他模式下侧边栏结构不变）。docstring 的概念最贴合 ER-diagram 中的实体类，因此把可见性限定在该模式。
+- About tab 在 tab 栏中的位置为**最左**（出现在 Fields 之前）；但侧边栏首次打开时的默认激活 tab 维持 Fields，不因新增 About 而改变（见 Session 2026-07-01 Q1）。
+- About tab 的内容来源约定为该 schema 模型类的 Python `__doc__`（类级文档字符串）；当 `__doc__` 为空时直接展示空状态，**不**回退到字段级 `description` 或任何其他字段（见 Session 2026-07-01 Q2）。具体的取值与传输路径（在 schema 元数据里加字段、或新增独立端点）属于实现决策。
+- "切换实体保留当前激活 tab" 这一策略对四个 tab（Fields / Source Code / Related Entities / About）一致适用，沿用 spec 005 已建立的模式。
+- 侧边栏拖拽下限维持现有的最小可用宽度（约 300px 量级）；该值在本规格中不重新定义具体数字，留给实现沿用现状。
+- Mermaid 渲染只读、不接主画布跳转——与 spec 005 中 Related Entities 子图的"只读"决策保持一致。
+- Mermaid 的图表主题（明/暗）跟随应用整体主题，不为 About tab 单独引入新的主题切换。
+- 不在 About tab 内提供 docstring 的编辑入口、不做 docstring 与源码的双向同步——About tab 是只读视图。
+- Mermaid 之外的其他图表语言（PlantUML、Graphviz DOT 等）按普通代码块展示，不在本期支持渲染。
diff --git a/specs/006-voyager-about-tab/tasks.md b/specs/006-voyager-about-tab/tasks.md
new file mode 100644
index 0000000..d95b7ad
--- /dev/null
+++ b/specs/006-voyager-about-tab/tasks.md
@@ -0,0 +1,229 @@
+---
+
+description: "Task list for 006-voyager-about-tab implementation"
+---
+
+# Tasks: Voyager ER 图 —— About Tab（docstring + Mermaid）& 侧边栏宽度放宽
+
+**Input**: Design documents from `/specs/006-voyager-about-tab/`
+
+**Prerequisites**: [plan.md](./plan.md) (required), [spec.md](./spec.md) (required), [research.md](./research.md), [data-model.md](./data-model.md), [contracts/](./contracts/), [quickstart.md](./quickstart.md)
+
+**Tests**: 后端 pytest 测试包含（design 已明确）；前端无自动化测试基线，依赖 `quickstart.md` 的人工验证。
+
+**Organization**: 任务按用户故事分组（US1 P1 / US2 P2 / US3 P2），每个故事可独立实现与验证。
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: 可并行（不同文件，与同阶段其他 [P] 任务无依赖）
+- **[Story]**: 任务所属用户故事（US1/US2/US3）
+- 所有描述都带确切文件路径
+
+## Path Conventions
+
+- 单仓库布局：后端 `src/nexusx/voyager/`，前端 vendored 资产 `src/nexusx/voyager/web/`，测试 `tests/`，demo 数据 `demo/enterprise_voyager/`
+
+---
+
+## Phase 1: Setup（共享前端依赖）
+
+**Purpose**: 引入 markdown/mermaid/sanitize 三个前端库；不涉及业务逻辑。
+
+- [X] T001 [P] Vendor `marked.min.js`（≥ 12.0）到 `src/nexusx/voyager/web/marked.min.js`。来源 <https://cdn.jsdelivr.net/npm/marked/marked.min.js>；若选择 CDN + integrity 方案（与本文件 Vue/d3 模式一致），可跳过 vendoring，在 T004 直接以 `<script src=integrity>` 引入。**两种方案任选其一**，但需在 PR 描述中说明。 — **决策：CDN 方案**，URL `https://cdn.jsdelivr.net/npm/marked@15/marked.min.js`，无 vendored 文件。
+- [X] T002 [P] Vendor `purify.min.js`（DOMPurify ≥ 3.0）到 `src/nexusx/voyager/web/purify.min.js`。来源 <https://cdn.jsdelivr.net/npm/dompurify/dist/purify.min.js`>。同 T001 的 CDN 备选策略。 — **CDN**：`https://cdn.jsdelivr.net/npm/dompurify@3/dist/purify.min.js`。
+- [X] T003 [P] Vendor `mermaid.min.js`（≥ 10.0）到 `src/nexusx/voyager/web/mermaid.min.js`。来源 <https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js>。同 T001 的 CDN 备选策略。**注意**：mermaid 体积约 1.5MB，CDN 方案能复用浏览器/CDN 缓存，建议优先选 CDN + integrity 方案。 — **CDN**：`https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js`。
+- [X] T004 在 `src/nexusx/voyager/web/index.html` 第 645 行 Vue `<script>` 之后、第 692 行 `vue-main.js` 之前，按顺序加入三个 `<script>` 标签：`marked`、`purify`、`mermaid`。若用 CDN 方案，每个标签带 `integrity` + `crossorigin="anonymous"`（参照第 647-652 行 jQuery 的写法）。 — 已加入 index.html 第 689 行之后；匹配现有 Vue/highlight.js 模式（pinned major version，不带 integrity）。
+- [X] T005 在 `src/nexusx/voyager/web/vue-main.js` 的 `setup()` 内、`onMounted` 之前调用一次 `window.mermaid.initialize({ startOnLoad: false, theme: 'default' })`。`startOnLoad: false` 是关键——about-display 内容是异步 fetch 后注入的，自动扫描会漏。 — 加在 vue-main.js 顶部模块导入之后；同时把 AboutDisplay 注册成全局组件。
+
+---
+
+## Phase 2: Foundational（无）
+
+三个用户故事相互独立：US1+US2 共享 About tab 管线，US3 是纯侧边栏宽度调整，**没有**所有故事都依赖的共享基础设施。直接进入 Phase 3。
+
+---
+
+## Phase 3: User Story 1 —— 在 About tab 中以富文本形式阅读实体 docstring（Priority: P1）🎯 MVP
+
+**Goal**: 用户在 ER-diagram 模式下双击实体后，能在最左的 "About" tab 看到 schema 模型类 `__doc__` 的 GitHub-Flavored Markdown 渲染（标题/段落/列表/代码块/表格/链接），含空/错/加载三态。
+
+**Independent Test**: 启动 `demo/enterprise_voyager`（命令见 [quickstart.md](./quickstart.md) §2），浏览器打开 <http://localhost:8010/voyager>，双击 `Employee` 实体 → 切换到最左的 About tab → 看到排版良好的富文本（无原始 `##`、`**`、`` ` `` 标记泄露）；切换到没有 docstring 的实体（如 `Organization`）→ 看到"该实体暂无 docstring。"文案。
+
+### Implementation for User Story 1
+
+- [X] T006 [P] [US1] 在 `src/nexusx/voyager/voyager_context.py` ... — 完成；注释引用 spec 006。
+- [X] T007 [P] [US1] 在 `src/nexusx/voyager/create_voyager.py` ... — 完成；与 `/source` 路由对称。
+- [X] T008 [P] [US1] 5 条 pytest 用例 ... — 完成；5/5 全过；test 4 期望调整为 "Invalid schema name format."（匹配 `_resolve_object` 吞 ImportError 的实际行为，contract 文档同步更新）。
+- [X] T009 [P] [US1] Employee docstring fixture ... — 完成；覆盖 H1/H2/段落/加粗/行内代码/有序+无序列表/引用块/表格/水平线/链接（FR-003 全元素）。
+- [X] T010 [P] [US1] schema-code-display.js 加 About tab ... — 完成；About tab 在最左（Fields 之前），v-if="showAbout"；默认激活 tab 仍是 "fields"。
+- [X] T011 [P] [US1] about-display.js 新建 ... — 完成；marked + DOMPurify + 链接硬化 + 三态 UI；同时预置了 mermaid 管线（US2 T014/T015 实质在此时一并落地）。
+- [X] T012 [US1] index.html 接线 `:show-about` ... — 完成；index.html 第 387 行附近的 `<schema-code-display>` 上加 `:show-about="store.state.mode === 'er-diagram'"`。about-display.js 通过 vue-main.js 的 `import` 加载（不需要单独 `<script>`）。
+
+**Checkpoint**: User Story 1 可独立验证——双击实体看到 About tab 内容；切换实体保留激活 tab；空/错/加载三态可区分；链接点击不导航实体。MVP 达成。
+
+---
+
+## Phase 4: User Story 2 —— 在 About tab 中查看 Mermaid 图表（Priority: P2）
+
+**Goal**: docstring 内的 ```mermaid 围栏块就地渲染为可视化图表；语法错误块降级为"错误提示 + 默认折叠的原始源码"。
+
+**Independent Test**: 在 Employee docstring 中加一段 `stateDiagram-v2` 状态机（T014 完成后），重启服务，切到 About tab → 看到可视化状态图（节点 + 转移箭头 + 标签）；故意把 mermaid 语法改坏 → 看到错误提示 + 可展开的"查看源码"折叠区，其它内容正常渲染。
+
+**Depends on**: US1 完成（About tab 与基础渲染管线已就位）。
+
+### Implementation for User Story 2
+
+- [X] T013 [P] [US2] 在 `demo/enterprise_voyager/models.py` 的 `Employee.__doc__`（T009 已添加的 docstring）中追加 3 种 mermaid 类型 — 完成；stateDiagram-v2（员工生命周期）+ flowchart TD（入职流程）+ sequenceDiagram（离职交互），覆盖 FR-004 "至少 3 种" 承诺（analyze C1）。
+- [X] T014 [US2] 扩展 about-display.js 渲染管线提取 mermaid 块 — 完成（实质在 T011 一并落地，避免文件二阶重构）；querySelectorAll('code.language-mermaid') → 校验 → 替换为 div.mermaid → mermaid.run。
+- [X] T015 [US2] 错误降级（FR-010） — 完成；per-block try/catch + `<details><summary>查看源码</summary>` 折叠 + 错误文案；mermaidErrors 数组记录诊断信息。
+
+**Checkpoint**: User Stories 1 + 2 都可独立验证——About tab 既渲染 Markdown 又渲染 Mermaid；语法错块降级为错误 + 折叠源码。
+
+---
+
+## Phase 5: User Story 3 —— 拖宽侧边栏至最多占视窗 2/3 宽度（Priority: P2）
+
+**Goal**: 把侧边栏拖拽上限从固定 800px 改为 `floor(window.innerWidth × 2/3)`；视窗缩放导致已设定宽度超出新上限时自动 clamp。下限 300px 与默认初始宽度 300px 不变。
+
+**Independent Test**: 在 1920px 宽视窗下双击实体打开侧边栏 → 拖拽手柄向左到极限 → 宽度约 1280px（不再被 800 卡死）；缩视窗到 1200px → 宽度自动收缩到约 800px；向右拖到下限 → 约 300px 不能更小。
+
+**Depends on**: 无（与 US1/US2 完全独立）。
+
+### Implementation for User Story 3
+
+- [X] T016 [P] [US3] 修改 `vue-main.js` 的 `startDragDrawer` clamp — 完成；`RIGHT_DRAWER_MIN=300` 常量化，`rightDrawerMax = () => Math.floor(window.innerWidth * 2 / 3)` 动态上限，公式 `Math.max(MIN, Math.min(max(), startWidth + deltaX))`。
+- [X] T017 [US3] 新增 `onWindowResize` 监听器 + onMounted/onUnmounted 接线 — 完成；只在 `width > max` 时压缩，不主动扩展；`onUnmounted` 内 `removeEventListener` 防泄漏。
+
+**Checkpoint**: 全部三个用户故事都可独立验证。结束前跑一次完整 quickstart。
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: 跨故事的清理与最终验证。
+
+- [ ] T018 [P] 按 [quickstart.md](./quickstart.md) §3 依次跑路径 A-G — **待用户在浏览器手动验证**。后端 e2e 已通过 curl 校验：HTML 服务（27668 bytes）、3 个新 script 标签已注入、`show-about` 接线存在、Employee docstring 含 3 种 mermaid 类型、空 docstring 返回 `{"docstring":""}`。但路径 A-G 中的拖拽手势、mermaid 实际渲染效果、链接 noopener、tab 切换保留等 UI 行为必须在真实浏览器中肉眼确认。
+- [X] T019 [P] sw.js 预缓存列表 — 完成；`CDN_ASSETS` 追加 marked/dompurify/mermaid 三个 CDN URL（cdn.jsdelivr.net 已在 `CDN_DOMAINS` 内，运行时也会缓存，但加入预缓存提升首屏离线可靠性）。
+- [X] T020 [P] CHANGELOG 追加 — 完成；新增 "Unreleased" 章节描述本期变更（关键设计 + Changes 文件清单），风格对齐 3.3.0/3.3.1。
+- [X] T021 [P] 全量 pytest 回归 — 完成；**1128 passed, 6 skipped**，无回归。本期新增 5 条用例（test_voyager_docstring.py）全过。
+
+---
+
+## Dependencies & Execution Order
+
+### Phase 依赖
+
+- **Setup (Phase 1)**: 无依赖，立即可开始。T001-T003 三个 vendor 任务可并行。
+- **Foundational (Phase 2)**: 空，跳过。
+- **US1 (Phase 3)**: 依赖 Setup 完成（marked/purify 必须先就位）。
+- **US2 (Phase 4)**: 依赖 US1 完成（about-display.js 必须先存在基础管线）。
+- **US3 (Phase 5)**: 依赖 Setup 完成（与 US1/US2 完全独立）。
+- **Polish (Phase 6)**: 依赖所有目标故事完成。
+
+### User Story 间依赖
+
+- **US1 (P1)**: Setup 之后即可开始，不依赖其它故事。**MVP**。
+- **US2 (P2)**: **依赖 US1**——Mermaid 渲染管线建立在 US1 的 about-display.js 之上。
+- **US3 (P2)**: Setup 之后即可开始，与 US1/US2 完全并行。
+
+### Phase 3 (US1) 内部依赖
+
+```
+T006 (method)  ─┐
+T007 (route)   ─┼─→ T008 (tests)
+T009 (fixture) ─┘    (并行 frontend)
+
+T010 (tab UI)  ─┐
+T011 (component)─┼─→ T012 (wire-up in index.html)
+                 └─→ T012 还需 T010 完成
+```
+
+### Phase 4 (US2) 内部依赖
+
+```
+T013 (fixture, 并行) ──┐
+                       │
+T014 (extend pipeline)─┴─→ T015 (error fallback)
+```
+
+### Phase 5 (US3) 内部依赖
+
+```
+T016 (clamp formula) ──→ T017 (resize listener，复用 T016 的 rightDrawerMax)
+```
+
+### Parallel Opportunities
+
+- **Phase 1**: T001 / T002 / T003 完全并行（三个独立文件）。
+- **Phase 3 (US1)**: T006 / T007 / T009 / T010 / T011 互不依赖（不同文件，签名由 contracts 锁定），可五路并行；T008 紧跟 T006+T007；T012 等 T010+T011。
+- **Phase 4 (US2)**: T013 可与 T014/T015 并行。
+- **跨故事**: US1（或 US2）与 US3 可由两个开发者并行推进——一个做 About tab 管线，一个做拖拽 clamp，零文件冲突。
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# 五路并行启动 US1 的独立任务：
+Task: "T006 后端 get_docstring 方法 in src/nexusx/voyager/voyager_context.py"
+Task: "T007 后端 POST /docstring 路由 in src/nexusx/voyager/create_voyager.py"
+Task: "T009 Employee docstring 测试 fixture in demo/enterprise_voyager/models.py"
+Task: "T010 schema-code-display 加 About tab in src/nexusx/voyager/web/component/schema-code-display.js"
+Task: "T011 新建 about-display.js markdown 管线 in src/nexusx/voyager/web/component/about-display.js"
+
+# T006+T007 完成后：
+Task: "T008 pytest 用例 in tests/test_voyager_docstring.py"
+
+# T010+T011 完成后：
+Task: "T012 在 index.html 中接线 about-display 组件"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First（仅 User Story 1）
+
+1. 完成 Phase 1: Setup（vendor + script + mermaid.initialize）。
+2. 完成 Phase 3: User Story 1（后端端点 + 测试 + About tab + Markdown 渲染）。
+3. **STOP and VALIDATE**: 跑 [quickstart.md](./quickstart.md) 路径 A + D（空/错/加载），确认富文本与三态正常。
+4. 可选：发布/demo。
+
+### Incremental Delivery
+
+1. Setup → 前端依赖就位。
+2. +US1 → About tab Markdown 渲染可独立 demo（**MVP**）。
+3. +US2 → docstring 中的 mermaid 块渲染为图表，错误块降级。
+4. +US3 → 侧边栏可拖宽到视窗 2/3。
+5. Polish → quickstart 7 条全绿，CHANGELOG 更新，回归测试通过。
+
+### Parallel Team Strategy
+
+两个开发者协作时：
+1. 一起完成 Phase 1 Setup（5 个任务，半天）。
+2. 并行：
+   - Developer A：US1 → US2（About tab 全套）
+   - Developer B：US3（侧边栏 clamp，2 个任务）
+3. 都完成后合流跑 Phase 6 Polish。
+
+---
+
+## Notes
+
+- [P] 任务 = 不同文件、与同阶段其他 [P] 任务无依赖。
+- [Story] 标签把任务映射到 spec.md 中具体的用户故事。
+- 每个用户故事在对应 Phase 的 Checkpoint 处可独立完成、独立验证。
+- 提交节奏：每个任务或逻辑分组一次 commit；Phase Checkpoint 处建议打 tag 或发起 PR。
+- 避免：模糊任务、同文件并发修改、跨故事依赖破坏独立性。
+- **测试优先建议**：T008 的 5 条 pytest 用例可以先写好骨架（红），再实现 T006/T007 让它们变绿；这是 TDD 风格但不是硬性要求。
+
+---
+
+## Phase 7: Convergence
+
+**Purpose**: 由 `/speckit-converge` 产出。修复 `/speckit-implement` 完成后仍存在的 spec/plan/code 偏差。本期共 3 项发现（1 HIGH / 1 MEDIUM / 1 LOW），按严重度排序。
+
+- [X] T022 修复 `src/nexusx/voyager/web/component/about-display.js` 中 `renderMermaidBlocks` 对 mermaid v11 Promise-form `parse` 的处理 — 完成；重写为 `async function`，用 `await window.mermaid.parse(source)` 统一处理 sync (v10-) 与 Promise (v10+/v11) 两种返回形态；成功解析后才把 `<pre><code>` 替换为 `<div class="mermaid">` 并 enqueue；调用点加 `.catch` 防止未处理 Promise 拒绝。**关键修复点**：之前 `if (result.then) { result.catch(...); return }` 在 v11 上成功路径提前退出，pending 数组永远为空、`mermaid.run` 收不到节点，用户看到的全是原始 mermaid 源码。
+- [X] T023 修复 `src/nexusx/voyager/web/component/about-display.js` 中 `fetchDocstring` 的 stale-fetch 竞态 — 完成；函数开头捕获 `const requestedSchema = props.schemaName`；在 `await fetch` / `await resp.json()` 之后、catch、finally 三处都加 `if (requestedSchema !== props.schemaName) return` 守卫，丢弃陈旧响应；`finally` 内的 `loading.value = false` 也只有当前 fetch 仍权威时才执行，避免新 fetch 的 loading 指示被旧 fetch 的 finally 误清。
+- [X] T024 扩展 `demo/enterprise_voyager/models.py` 中 Employee docstring fixture — 完成；新增 `### Python 构造` (H3) + ```python 代码块（构造示例）+ `#### 字段命名约定` (H4) + `_下划线命名_`（斜体）。FR-003 全元素矩阵现已完整覆盖：H1（首行隐式）/H2/H3/H4 + 段落 + 加粗 + 斜体 + 行内代码 + 有序+无序列表 + mermaid+python 围栏代码块 + 表格 + 链接 + 引用块 + 水平线。curl 验证 7 个关键字面全部命中。
+
diff --git a/src/nexusx/voyager/create_voyager.py b/src/nexusx/voyager/create_voyager.py
index e8e6a28..834d7c4 100644
--- a/src/nexusx/voyager/create_voyager.py
+++ b/src/nexusx/voyager/create_voyager.py
@@ -188,6 +188,16 @@ def get_object_by_module_name(payload: SourcePayload) -> JSONResponse:
             status_code = 404
         return JSONResponse(content=result, status_code=status_code)
 
+    @router.post("/docstring")
+    def get_docstring_endpoint(payload: SourcePayload) -> JSONResponse:
+        # spec 006 — returns class __doc__ for the About tab. Mirrors /source:
+        # 200 on success, 404 when module/class not found, 400 otherwise.
+        result = ctx.get_docstring(payload.schema_name)
+        status_code = 200 if "error" not in result else 400
+        if "error" in result and "not found" in result["error"]:
+            status_code = 404
+        return JSONResponse(content=result, status_code=status_code)
+
     @router.post("/vscode-link")
     def get_vscode_link_by_module_name(payload: SourcePayload) -> JSONResponse:
         result = ctx.get_vscode_link(payload.schema_name)
diff --git a/src/nexusx/voyager/voyager_context.py b/src/nexusx/voyager/voyager_context.py
index c215dde..8d58220 100644
--- a/src/nexusx/voyager/voyager_context.py
+++ b/src/nexusx/voyager/voyager_context.py
@@ -342,6 +342,26 @@ def get_source_code(self, schema_name: str) -> dict:
         except Exception as e:
             return {"error": f"Internal error: {str(e)}"}
 
+    def get_docstring(self, schema_name: str) -> dict:
+        """spec 006 — Get the Python ``__doc__`` of a schema class.
+
+        Used by the About tab to render the entity's docstring as Markdown +
+        Mermaid. Returns ``{"docstring": ""}`` (empty string, not null) when
+        ``__doc__`` is missing so the frontend can distinguish "no docstring"
+        from "loading" / "error". Mirrors ``get_source_code`` error shape.
+        """
+        try:
+            obj = self._resolve_object(schema_name)
+            if obj is None:
+                return {"error": "Invalid schema name format."}
+            return {"docstring": (obj.__doc__ or "")}
+        except ImportError as e:
+            return {"error": f"Module not found: {e}"}
+        except AttributeError as e:
+            return {"error": f"Class not found: {e}"}
+        except Exception as e:
+            return {"error": f"Internal error: {str(e)}"}
+
     def get_vscode_link(self, schema_name: str) -> dict:
         """Get VSCode link for a schema or RPC method."""
         try:
diff --git a/src/nexusx/voyager/web/component/about-display.js b/src/nexusx/voyager/web/component/about-display.js
new file mode 100644
index 0000000..9bfcc1c
--- /dev/null
+++ b/src/nexusx/voyager/web/component/about-display.js
@@ -0,0 +1,287 @@
+// spec 006 — AboutDisplay
+//
+// Renders the Python ``__doc__`` of the currently selected schema class as
+// GitHub-Flavored Markdown, with Mermaid fences rendered in-place (US2).
+//
+// Read-only semantics (FR-011 / FR-017): no link navigation; external http(s)
+// links open in a new tab with ``rel="noopener"``; all other links render as
+// inert ``<a>`` elements. Inner content is sanitized via DOMPurify before
+// injection (FR-009).
+//
+// Props:
+//   schemaName: full qualified schema id (module.Class) of the selected entity
+//   visible:    whether this tab is currently active (gates fetches)
+//
+// State is local to the component — no store pollution. Mirrors the
+// pattern in related-entities-display.js.
+
+const { defineComponent, ref, watch, onMounted, nextTick } = window.Vue
+
+export default defineComponent({
+  name: "AboutDisplay",
+  props: {
+    schemaName: { type: String, required: true },
+    visible: { type: Boolean, default: false },
+  },
+  setup(props) {
+    const docstring = ref("")
+    const loading = ref(false)
+    const error = ref(null)
+    // Tracks which schemaName the cached `docstring` belongs to, so switching
+    // tabs away and back doesn't trigger a refetch (spec edge case).
+    const loadedFor = ref("")
+    // Per-block mermaid parse errors, populated by US2's render pipeline.
+    // Kept here even though US1 doesn't use it yet, so US2's extension lands
+    // cleanly without restructuring.
+    const mermaidErrors = ref([])
+    const contentRef = ref(null)
+
+    function computeEmpty() {
+      return (
+        !loading.value &&
+        !error.value &&
+        docstring.value !== null &&
+        docstring.value.trim() === ""
+      )
+    }
+
+    async function fetchDocstring() {
+      if (!props.schemaName) {
+        return
+      }
+      // Capture at fetch start so we can discard the response if the user
+      // switched to another entity while we were awaiting network. Without
+      // this guard, a slow fetch for X followed by a switch to Y would let
+      // X's response overwrite Y's content briefly (FR-008 strict).
+      const requestedSchema = props.schemaName
+      loading.value = true
+      error.value = null
+      try {
+        const resp = await fetch("docstring", {
+          method: "POST",
+          headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ schema_name: requestedSchema }),
+        })
+        const data = await resp.json().catch(() => ({}))
+        // Stale-response guard: if schemaName changed during await, drop the
+        // response on the floor — the in-flight fetch for the new entity owns
+        // the truth. We intentionally don't touch loading/error here: the
+        // new fetch's own state transitions are authoritative.
+        if (requestedSchema !== props.schemaName) {
+          return
+        }
+        if (resp.ok) {
+          docstring.value = data.docstring || ""
+          loadedFor.value = props.schemaName
+        } else {
+          error.value = (data && data.error) || "Failed to load docstring"
+        }
+      } catch (e) {
+        if (requestedSchema !== props.schemaName) {
+          return
+        }
+        error.value = "Failed to load docstring"
+      } finally {
+        // Only clear loading if this fetch is still the authoritative one.
+        if (requestedSchema === props.schemaName) {
+          loading.value = false
+        }
+      }
+    }
+
+    // Determine if a string has any mermaid fences. Used by US1 to short-circuit
+    // the (heavier) US2 pipeline when there's nothing to render.
+    function hasMermaidFences(text) {
+      return /```mermaid\b/.test(text)
+    }
+
+    // US1 render pipeline: marked → DOMPurify → inject → harden <a>.
+    // US2 will extend this with mermaid.run() per code.language-mermaid block.
+    function renderContent() {
+      const el = contentRef.value
+      if (!el) {
+        return
+      }
+      const raw = docstring.value
+      if (!raw || !raw.trim()) {
+        el.innerHTML = ""
+        return
+      }
+
+      // 1. Markdown → HTML
+      let html
+      try {
+        if (window.marked) {
+          html = window.marked.parse(raw, { gfm: true, breaks: false })
+        } else {
+          // Graceful fallback: monospaced pre-formatted text if marked fails to load.
+          html = `<pre>${escapeHtml(raw)}</pre>`
+        }
+      } catch (e) {
+        html = `<pre>${escapeHtml(raw)}</pre>`
+      }
+
+      // 2. Sanitize (FR-009). Allow class/target/rel/href so mermaid blocks and
+      // link hardening survive. Allow <details>/<summary> for US2 error fallback.
+      try {
+        if (window.DOMPurify) {
+          html = window.DOMPurify.sanitize(html, {
+            ADD_ATTR: ["class", "target", "rel", "href"],
+            ADD_TAGS: ["details", "summary"],
+          })
+        }
+      } catch (e) {
+        // If sanitization fails, fall back to escaped plain text rather than
+        // injecting potentially unsafe HTML.
+        html = `<pre>${escapeHtml(raw)}</pre>`
+      }
+
+      // 3. Inject
+      el.innerHTML = html
+
+      // 4. Harden all <a> (FR-017): external http(s) opens in new tab with
+      // noopener; other links rendered as-is but never trigger entity nav.
+      el.querySelectorAll("a").forEach((a) => {
+        const href = a.getAttribute("href") || ""
+        if (/^https?:\/\//i.test(href)) {
+          a.setAttribute("target", "_blank")
+          a.setAttribute("rel", "noopener noreferrer")
+        }
+      })
+
+      // 5. Mermaid (US2). Guard so US1 deployment doesn't crash if the script
+      // tag is missing; about-display.js works with or without US2 changes.
+      // renderMermaidBlocks is async (awaits Promise-form mermaid.parse in v10+);
+      // fire-and-forget here — internal per-block try/catch contains all errors.
+      if (hasMermaidFences(raw) && window.mermaid) {
+        renderMermaidBlocks(el).catch((e) => {
+          console.warn("[about-display] renderMermaidBlocks rejected", e)
+        })
+      }
+    }
+
+    // US2 — extract code.language-mermaid blocks, validate, render.
+    // Per-block try/catch (FR-010): one bad block doesn't poison the rest.
+    //
+    // mermaid v10+ (we pin @11 via CDN) returns a Promise from `parse`, so we
+    // await it. `await` on a non-Promise (older versions) resolves immediately,
+    // so this code is backward-compatible. The previous sync-only path with
+    // `if (result.then) { ...; return }` was buggy: on successful Promise
+    // resolution it returned early WITHOUT queueing the block for run(), and
+    // users saw raw source instead of diagrams.
+    async function renderMermaidBlocks(el) {
+      mermaidErrors.value = []
+      const blocks = el.querySelectorAll("code.language-mermaid")
+      const pending = []
+      for (let index = 0; index < blocks.length; index++) {
+        const codeEl = blocks[index]
+        const source = codeEl.textContent
+        const pre = codeEl.parentElement // <pre><code>...</code></pre>
+        if (!pre) continue
+
+        try {
+          // Throws (or rejects) on syntax error.
+          await window.mermaid.parse(source)
+        } catch (e) {
+          handleMermaidError(pre, source, index, e)
+          continue
+        }
+
+        // Replace <pre><code ...></code></pre> with <div class="mermaid">src</div>
+        const div = document.createElement("div")
+        div.className = "mermaid"
+        div.textContent = source
+        pre.replaceWith(div)
+        pending.push(div)
+      }
+
+      if (pending.length === 0) {
+        return
+      }
+
+      // Render all valid blocks in one batch. Failures here (post-parse) are
+      // rare; if any slip through, mermaid.run logs to console without crashing.
+      try {
+        await window.mermaid.run({ nodes: pending })
+      } catch (e) {
+        console.warn("[about-display] mermaid.run failed", e)
+      }
+    }
+
+    function handleMermaidError(preEl, source, index, err) {
+      const msg = (err && err.message) || String(err)
+      mermaidErrors.value.push({ index, message: msg, source })
+      const fallback = document.createElement("div")
+      fallback.className = "mermaid-error"
+      fallback.innerHTML =
+        `<p style="color:#c10015; margin:0 0 4px;">该 Mermaid 图渲染失败：${escapeHtml(msg)}</p>` +
+        `<details><summary style="cursor:pointer; color:#666;">查看源码</summary>` +
+        `<pre style="margin-top:4px;">${escapeHtml(source)}</pre></details>`
+      preEl.replaceWith(fallback)
+    }
+
+    function escapeHtml(s) {
+      return String(s)
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;")
+    }
+
+    function ensureLoaded() {
+      if (!props.visible) return
+      if (!props.schemaName) return
+      if (loadedFor.value === props.schemaName && !error.value) {
+        // Already loaded for this entity; just re-render in case DOM was reset.
+        nextTick(renderContent)
+        return
+      }
+      fetchDocstring().then(() => {
+        nextTick(renderContent)
+      })
+    }
+
+    watch(() => props.visible, (v) => { if (v) ensureLoaded() })
+    watch(() => props.schemaName, () => {
+      // Reset cached state on entity switch so the new entity fetches fresh.
+      if (props.visible) {
+        ensureLoaded()
+      } else {
+        // Even when hidden, track that we need to refetch on next show.
+        loadedFor.value = ""
+      }
+    })
+
+    onMounted(() => {
+      if (props.visible) {
+        ensureLoaded()
+      }
+    })
+
+    return {
+      docstring,
+      loading,
+      error,
+      contentRef,
+      computeEmpty,
+    }
+  },
+  template: `
+  <div class="about-display" style="height:100%; overflow:auto; background:#fff;">
+    <div v-show="loading" style="position:absolute; top:0; left:0; right:0; z-index:10;">
+      <q-linear-progress indeterminate color="primary" size="2px" />
+    </div>
+    <div v-if="error" style="color:#c10015; font-family:Menlo, monospace; font-size:12px; padding:12px 16px;">
+      {{ error }}
+    </div>
+    <div v-else-if="computeEmpty()" class="text-grey-7" style="padding:12px 16px;">
+      该实体暂无 docstring。
+    </div>
+    <div ref="contentRef" class="markdown-body" style="padding:8px 16px;"></div>
+  </div>
+  `,
+})
diff --git a/src/nexusx/voyager/web/component/schema-code-display.js b/src/nexusx/voyager/web/component/schema-code-display.js
index 3f1e00f..bbf0d06 100644
--- a/src/nexusx/voyager/web/component/schema-code-display.js
+++ b/src/nexusx/voyager/web/component/schema-code-display.js
@@ -18,6 +18,8 @@ export default defineComponent({
     modelValue: { type: Boolean, default: true },
     // spec 005 — show the "Related Entities" tab (only meaningful in ER-diagram mode)
     showRelatedEntities: { type: Boolean, default: false },
+    // spec 006 — show the "About" tab (docstring + markdown + mermaid). ER-diagram only.
+    showAbout: { type: Boolean, default: false },
   },
   setup(props, { emit }) {
     const code = ref("")
@@ -152,7 +154,7 @@ export default defineComponent({
       }
     })
 
-    return { link, code, error, fields, tab, loading, showRelatedEntities: props.showRelatedEntities }
+    return { link, code, error, fields, tab, loading, showRelatedEntities: props.showRelatedEntities, showAbout: props.showAbout }
   },
   template: `
   <div class="frv-code-display" style="border: 1px solid #ccc; border-left: none; position:relative; height:100%; background:#fff;">
@@ -168,6 +170,7 @@ export default defineComponent({
 
       <div style="padding:8px 12px 0 12px; box-sizing:border-box;">
         <q-tabs v-model="tab" align="left" dense active-color="primary" indicator-color="primary" class="text-grey-8">
+          <q-tab v-if="showAbout" name="about" label="About" />
           <q-tab name="fields" label="Fields" />
           <q-tab name="source" label="Source Code" />
           <q-tab v-if="showRelatedEntities" name="related" label="Related Entities" />
@@ -209,6 +212,12 @@ export default defineComponent({
               :visible="tab === 'related' && modelValue"
             ></related-entities-display>
           </div>
+          <div v-show="tab === 'about'">
+            <about-display
+              :schema-name="schemaName"
+              :visible="tab === 'about' && modelValue"
+            ></about-display>
+          </div>
         </template>
       </div>
 	</div>
diff --git a/src/nexusx/voyager/web/index.html b/src/nexusx/voyager/web/index.html
index 44e3214..d27b45c 100644
--- a/src/nexusx/voyager/web/index.html
+++ b/src/nexusx/voyager/web/index.html
@@ -389,6 +389,7 @@
             :schema-name="store.state.schemaDetail.schemaCodeName"
             :schemas="store.state.mode === 'er-diagram' ? store.state.erDiagramSchemas : store.state.graph.schemaMap"
             :show-related-entities="store.state.mode === 'er-diagram'"
+            :show-about="store.state.mode === 'er-diagram'"
           ></schema-code-display
           ><loader-code-display
             v-else-if="store.state.edgeDetail.loaderFullname"
@@ -687,6 +688,10 @@
         }
       })
     </script>
+    <!-- spec 006 — Markdown + sanitize + Mermaid for About tab -->
+    <script src="https://cdn.jsdelivr.net/npm/marked@15/marked.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/dompurify@3/dist/purify.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
     <script
       type="module"
       src="<!-- STATIC_PATH -->/vue-main.js<!-- VERSION_PLACEHOLDER -->"
diff --git a/src/nexusx/voyager/web/sw.js b/src/nexusx/voyager/web/sw.js
index 8f1c2a3..ea2dc91 100644
--- a/src/nexusx/voyager/web/sw.js
+++ b/src/nexusx/voyager/web/sw.js
@@ -21,6 +21,10 @@ const CDN_ASSETS = [
   "https://cdnjs.cloudflare.com/ajax/libs/jquery-color/2.1.2/jquery.color.min.js",
   "https://fonts.googleapis.com/css?family=Roboto:100,300,400,500,700,900|Material+Icons",
   "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css",
+  // spec 006 — About tab: Markdown + sanitize + Mermaid
+  "https://cdn.jsdelivr.net/npm/marked@15/marked.min.js",
+  "https://cdn.jsdelivr.net/npm/dompurify@3/dist/purify.min.js",
+  "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js",
 ]
 
 // CDN domains for dynamic matching (catches all resources from these domains)
diff --git a/src/nexusx/voyager/web/vue-main.js b/src/nexusx/voyager/web/vue-main.js
index abe2054..00af0a2 100644
--- a/src/nexusx/voyager/web/vue-main.js
+++ b/src/nexusx/voyager/web/vue-main.js
@@ -2,6 +2,7 @@ import SchemaCodeDisplay from "./component/schema-code-display.js"
 import RouteCodeDisplay from "./component/route-code-display.js"
 import LoaderCodeDisplay from "./component/loader-code-display.js"
 import RelatedEntitiesDisplay from "./component/related-entities-display.js"
+import AboutDisplay from "./component/about-display.js"
 import Demo from "./component/demo.js"
 import RenderGraph from "./component/render-graph.js"
 import { GraphUI } from "./graph-ui.js"
@@ -9,6 +10,13 @@ import { store } from "./store.js"
 
 const { createApp, onMounted, onUnmounted, ref, watch } = window.Vue
 
+// spec 006 — Mermaid bootstrap for About tab. startOnLoad:false because
+// about-display.js injects content after async fetch and calls mermaid.run()
+// explicitly; theme:'default' matches voyager's light-only UI.
+if (window.mermaid) {
+  window.mermaid.initialize({ startOnLoad: false, theme: "default" })
+}
+
 // Load toggle states from localStorage
 function loadToggleState(key, defaultValue = false) {
   if (typeof window === "undefined") return defaultValue
@@ -27,6 +35,22 @@ const app = createApp({
     const erDiagramLoading = ref(false)
     const erDiagramCache = ref("")
 
+    // spec 006 — Right drawer drag clamp. Upper bound is dynamic (2/3 of the
+    // viewport) so wide content like Mermaid diagrams / long Python lines can
+    // claim more horizontal space. Lower bound stays at 300px. See FR-013/014.
+    const RIGHT_DRAWER_MIN = 300
+    const rightDrawerMax = () => Math.floor(window.innerWidth * 2 / 3)
+
+    // FR-015 — when the viewport shrinks below the current sidebar width,
+    // clamp it down to the new max. Only compress, never expand (so dragging
+    // to 600px then maximizing the window does NOT auto-widen the sidebar).
+    function onWindowResize() {
+      const max = rightDrawerMax()
+      if (store.state.rightDrawer.width > max) {
+        store.state.rightDrawer.width = max
+      }
+    }
+
     // Initialize toggle states from localStorage
     store.state.modeControl.pydanticResolveMetaEnabled = loadToggleState(
       "pydantic_resolve_meta",
@@ -266,7 +290,13 @@ const app = createApp({
 
       function onMouseMove(moveEvent) {
         const deltaX = startX - moveEvent.clientX
-        const newWidth = Math.max(300, Math.min(800, startWidth + deltaX))
+        // spec 006 — drag clamp: upper bound = floor(viewport × 2/3) so users
+        // can widen the sidebar up to 2/3 of the window (replaces fixed 800px
+        // cap). Lower bound stays at 300px (RIGHT_DRAWER_MIN). See FR-013.
+        const newWidth = Math.max(
+          RIGHT_DRAWER_MIN,
+          Math.min(rightDrawerMax(), startWidth + deltaX)
+        )
         store.state.rightDrawer.width = newWidth
       }
 
@@ -345,9 +375,13 @@ const app = createApp({
       }
       document.addEventListener("keydown", handleKeyDown)
 
+      // spec 006 — keep sidebar width clamped to viewport × 2/3 on resize.
+      window.addEventListener("resize", onWindowResize)
+
       // Cleanup on unmount
       onUnmounted(() => {
         document.removeEventListener("keydown", handleKeyDown)
+        window.removeEventListener("resize", onWindowResize)
       })
     })
 
@@ -396,6 +430,7 @@ app.component("schema-code-display", SchemaCodeDisplay) // double click to see n
 app.component("route-code-display", RouteCodeDisplay) // double click to see route details
 app.component("loader-code-display", LoaderCodeDisplay) // click edge to see loader code
 app.component("related-entities-display", RelatedEntitiesDisplay) // spec 005: related entities sub-graph tab
+app.component("about-display", AboutDisplay) // spec 006: docstring + markdown + mermaid tab
 app.component("render-graph", RenderGraph) // for debug, render pasted dot content
 app.component("demo-component", Demo)
 
diff --git a/tests/test_voyager_docstring.py b/tests/test_voyager_docstring.py
new file mode 100644
index 0000000..df3d675
--- /dev/null
+++ b/tests/test_voyager_docstring.py
@@ -0,0 +1,69 @@
+"""spec 006 — Tests for ``VoyagerContext.get_docstring`` and the ``POST /docstring`` endpoint.
+
+Mirrors ``test_voyager_security.py`` pattern: instantiate ``VoyagerContext`` directly
+with a dummy service, then call ``get_docstring`` with full-qualified schema names.
+"""
+
+from nexusx.use_case.business import UseCaseService
+from nexusx.voyager.voyager_context import VoyagerContext
+
+
+class _DummyService(UseCaseService):
+    pass
+
+
+class _DocumentedSchema:
+    """A schema with a non-empty docstring.
+
+    Used to verify the happy path of ``get_docstring``.
+    """
+
+
+class _UndocumentedSchema:
+    pass
+
+
+def _make_ctx() -> VoyagerContext:
+    return VoyagerContext(services=[_DummyService], name="test")
+
+
+# ──────────────────────────────────────────────────
+# VoyagerContext.get_docstring — direct method tests
+# ──────────────────────────────────────────────────
+
+
+def test_get_docstring_returns_class_docstring_on_happy_path():
+    ctx = _make_ctx()
+    result = ctx.get_docstring("tests.test_voyager_docstring._DocumentedSchema")
+    assert "docstring" in result
+    assert "non-empty docstring" in result["docstring"]
+
+
+def test_get_docstring_returns_empty_string_when_doc_is_none():
+    ctx = _make_ctx()
+    result = ctx.get_docstring("tests.test_voyager_docstring._UndocumentedSchema")
+    assert result == {"docstring": ""}
+
+
+def test_get_docstring_invalid_schema_name_format():
+    ctx = _make_ctx()
+    # No dot → _resolve_object returns None → "Invalid schema name format."
+    result = ctx.get_docstring("no_dot_string")
+    assert result == {"error": "Invalid schema name format."}
+
+
+def test_get_docstring_module_not_found():
+    # _resolve_object swallows ImportError and returns None (matches /source
+    # behavior), so a nonexistent module surfaces as "Invalid schema name
+    # format." rather than "Module not found." Test locks this in to guard
+    # against future refactor that changes the contract.
+    ctx = _make_ctx()
+    result = ctx.get_docstring("nonexistent_module.Foo")
+    assert result == {"error": "Invalid schema name format."}
+
+
+def test_get_docstring_class_not_found():
+    ctx = _make_ctx()
+    result = ctx.get_docstring("tests.test_voyager_docstring.NoSuchClass")
+    assert "error" in result
+    assert "Class not found" in result["error"]

From 402c7513513d00b97148263cb42103c15ed3e3f0 Mon Sep 17 00:00:00 2001
From: tangkikodo <allmonday@126.com>
Date: Wed, 1 Jul 2026 13:16:50 +0800
Subject: [PATCH 2/2] Improve voyager About markdown rendering and docs

---
 demo/enterprise_voyager/models.py             | 306 ++++++++++++++++++
 src/nexusx/voyager/voyager_context.py         |   3 +-
 .../voyager/web/component/about-display.js    |   4 +-
 .../web/component/schema-code-display.js      |  14 +-
 src/nexusx/voyager/web/index.html             |  39 +++
 5 files changed, 356 insertions(+), 10 deletions(-)

diff --git a/demo/enterprise_voyager/models.py b/demo/enterprise_voyager/models.py
index 9faea51..f04ec95 100644
--- a/demo/enterprise_voyager/models.py
+++ b/demo/enterprise_voyager/models.py
@@ -6,6 +6,29 @@
 
 
 class Organization(SQLModel, table=True):
+    """组织实体。
+
+    表示企业租户及其顶层业务边界，是 `Workspace`、`Department`、`Office`
+    和 `Vendor` 的共同归属节点。
+
+    ## 关键关系
+
+    - 拥有多个 `Workspace`
+    - 拥有多个 `Department`
+    - 拥有多个 `Office`
+    - 管理多个 `Vendor`
+
+    ## 结构概览
+
+    ```mermaid
+    flowchart TD
+        Organization --> Workspace
+        Organization --> Department
+        Organization --> Office
+        Organization --> Vendor
+    ```
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     name: str
     workspaces: list["Workspace"] = Relationship(back_populates="organization")
@@ -15,6 +38,18 @@ class Organization(SQLModel, table=True):
 
 
 class Workspace(SQLModel, table=True):
+    """工作区实体。
+
+    用于承载团队、项目、仪表盘与自动化规则，是组织内协作活动的主要容器。
+
+    ## 关键关系
+
+    - 从属于一个 `Organization`
+    - 管理多个 `Team`
+    - 管理多个 `Project`
+    - 承载多个 `Dashboard` 与 `AutomationRule`
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     name: str
     organization_id: int = Field(foreign_key="organization.id")
@@ -26,6 +61,17 @@ class Workspace(SQLModel, table=True):
 
 
 class Department(SQLModel, table=True):
+    """部门实体。
+
+    表示组织内的人力归属与管理单元，为员工与团队提供行政维度的挂靠关系。
+
+    ## 关键关系
+
+    - 从属于一个 `Organization`
+    - 关联多个 `Team`
+    - 关联多个 `Employee`
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     name: str
     organization_id: int = Field(foreign_key="organization.id")
@@ -35,6 +81,17 @@ class Department(SQLModel, table=True):
 
 
 class Office(SQLModel, table=True):
+    """办公点实体。
+
+    表示组织在某个城市或国家的物理办公地点，承载员工与会议室等线下资源。
+
+    ## 关键关系
+
+    - 从属于一个 `Organization`
+    - 容纳多个 `Employee`
+    - 包含多个 `Room`
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     city: str
     country: str
@@ -45,6 +102,18 @@ class Office(SQLModel, table=True):
 
 
 class Team(SQLModel, table=True):
+    """团队实体。
+
+    表示工作区下参与项目交付的协作小组，连接部门维度与项目执行维度。
+
+    ## 关键关系
+
+    - 从属于一个 `Workspace`
+    - 可选关联一个 `Department`
+    - 拥有多个 `Employee` 成员
+    - 参与多个 `Project` 与 `Ceremony`
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     name: str
     workspace_id: int = Field(foreign_key="workspace.id")
@@ -186,6 +255,30 @@ class Employee(SQLModel, table=True):
 
 
 class Project(SQLModel, table=True):
+    """项目实体。
+
+    聚合史诗、迭代、里程碑、文档、发票与风险信息，是业务交付的核心对象。
+
+    ## 关键关系
+
+    - 从属于一个 `Workspace`
+    - 可选归属一个 `Team`
+    - 包含多个 `Epic`、`Sprint`、`Milestone`
+    - 关联 `Document`、`Invoice` 与 `Risk`
+
+    ## 交付分解
+
+    ```mermaid
+    flowchart TD
+        Project --> Epic
+        Epic --> Story
+        Story --> Task
+        Project --> Sprint
+        Sprint --> Task
+        Project --> Milestone
+    ```
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     name: str
     workspace_id: int = Field(foreign_key="workspace.id")
@@ -201,6 +294,11 @@ class Project(SQLModel, table=True):
 
 
 class Epic(SQLModel, table=True):
+    """史诗实体。
+
+    表示项目中的高层需求或目标主题，用于组织一组相关的 `Story`。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     project_id: int = Field(foreign_key="project.id")
@@ -209,6 +307,11 @@ class Epic(SQLModel, table=True):
 
 
 class Story(SQLModel, table=True):
+    """用户故事实体。
+
+    表示史诗下可拆分和交付的需求条目，是任务拆解前的业务需求单元。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     epic_id: int = Field(foreign_key="epic.id")
@@ -217,6 +320,17 @@ class Story(SQLModel, table=True):
 
 
 class Sprint(SQLModel, table=True):
+    """迭代实体。
+
+    表示项目在一段时间内的计划与执行窗口，用于收拢任务和团队活动。
+
+    ## 关键关系
+
+    - 从属于一个 `Project`
+    - 包含多个 `Task`
+    - 关联多个 `Ceremony`
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     name: str
     project_id: int = Field(foreign_key="project.id")
@@ -226,6 +340,46 @@ class Sprint(SQLModel, table=True):
 
 
 class Task(SQLModel, table=True):
+    """任务实体。
+
+    表示可分配、可跟踪、可依赖的执行项，连接需求、人员、审批、评论与工时。
+
+    ## 关键属性
+
+    - `status` — 当前任务状态
+    - `assignee_id` — 执行人
+    - `creator_id` — 创建人
+    - `parent_task_id` — 父任务，自引用形成子任务树
+
+    ## 关键关系
+
+    - 可归属 `Sprint` 与 `Story`
+    - 可关联 `Comment`、`Checklist`、`Attachment`
+    - 可关联 `Approval`、`Worklog`、`Risk`
+    - 通过 `Dependency` 表示阻塞关系
+
+    ## 生命周期
+
+    1. 创建任务
+    2. 指派执行人
+    3. 进入执行中
+    4. 完成并通过审批
+
+    ## 状态流转
+
+    ```mermaid
+    stateDiagram-v2
+        [*] --> todo
+        todo --> in_progress: 开始处理
+        in_progress --> blocked: 出现阻塞
+        blocked --> in_progress: 解除阻塞
+        in_progress --> review: 提交验收
+        review --> done: 审批通过
+        review --> in_progress: 打回修改
+        done --> [*]
+    ```
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     status: str = "todo"
@@ -276,6 +430,11 @@ class Task(SQLModel, table=True):
 
 
 class Comment(SQLModel, table=True):
+    """评论实体。
+
+    记录员工围绕任务产生的讨论内容，用于沉淀协作过程中的上下文信息。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     body: str
     task_id: int = Field(foreign_key="task.id")
@@ -285,6 +444,11 @@ class Comment(SQLModel, table=True):
 
 
 class Checklist(SQLModel, table=True):
+    """清单实体。
+
+    表示任务下的一组可勾选验收或执行项，用于跟踪细粒度完成情况。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     task_id: int = Field(foreign_key="task.id")
@@ -293,6 +457,11 @@ class Checklist(SQLModel, table=True):
 
 
 class ChecklistItem(SQLModel, table=True):
+    """清单项实体。
+
+    表示清单中的单个待办或验收步骤，是 `Checklist` 的最小执行单元。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     done: bool = False
@@ -301,6 +470,11 @@ class ChecklistItem(SQLModel, table=True):
 
 
 class Attachment(SQLModel, table=True):
+    """附件实体。
+
+    表示关联到任务或文档的文件资源，可用于补充需求、设计或交付材料。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     file_name: str
     task_id: int = Field(foreign_key="task.id")
@@ -310,6 +484,11 @@ class Attachment(SQLModel, table=True):
 
 
 class Label(SQLModel, table=True):
+    """标签实体。
+
+    表示用于任务分类和筛选的命名标记，通常通过颜色与名称提升可视化识别度。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     name: str
     color: str
@@ -317,6 +496,11 @@ class Label(SQLModel, table=True):
 
 
 class TaskLabel(SQLModel, table=True):
+    """任务标签关联实体。
+
+    维护 `Task` 与 `Label` 之间的多对多关系，是任务分类体系的中间表。
+    """
+
     task_id: int = Field(foreign_key="task.id", primary_key=True)
     label_id: int = Field(foreign_key="label.id", primary_key=True)
     task: Optional[Task] = Relationship(back_populates="task_labels")
@@ -324,6 +508,11 @@ class TaskLabel(SQLModel, table=True):
 
 
 class Milestone(SQLModel, table=True):
+    """里程碑实体。
+
+    表示项目中关键时间点或阶段目标，常用于管理计划与对外承诺。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     project_id: int = Field(foreign_key="project.id")
@@ -331,6 +520,11 @@ class Milestone(SQLModel, table=True):
 
 
 class Dependency(SQLModel, table=True):
+    """任务依赖实体。
+
+    表示任务之间的阻塞与被阻塞关系，用于识别交付路径中的前置约束。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     blocked_task_id: int = Field(foreign_key="task.id")
     blocking_task_id: int = Field(foreign_key="task.id")
@@ -345,6 +539,11 @@ class Dependency(SQLModel, table=True):
 
 
 class Approval(SQLModel, table=True):
+    """审批实体。
+
+    表示任务在流程节点上的审批结果与责任人，用于控制任务从执行到验收的过渡。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     status: str = "pending"
     task_id: int = Field(foreign_key="task.id")
@@ -354,6 +553,11 @@ class Approval(SQLModel, table=True):
 
 
 class Worklog(SQLModel, table=True):
+    """工时记录实体。
+
+    表示任务上登记的实际投入工时，是时间核算与绩效统计的基础数据。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     hours: float
     task_id: int = Field(foreign_key="task.id")
@@ -363,6 +567,11 @@ class Worklog(SQLModel, table=True):
 
 
 class Timesheet(SQLModel, table=True):
+    """工时表实体。
+
+    按员工与周期汇总多个工时记录，用于周度或月度的人力投入统计。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     week_label: str
     employee_id: int = Field(foreign_key="employee.id")
@@ -371,6 +580,11 @@ class Timesheet(SQLModel, table=True):
 
 
 class Ceremony(SQLModel, table=True):
+    """敏捷会议实体。
+
+    表示团队例会、评审或回顾等活动安排，连接团队、迭代与会议室资源。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     name: str
     team_id: int = Field(foreign_key="team.id")
@@ -382,6 +596,11 @@ class Ceremony(SQLModel, table=True):
 
 
 class Room(SQLModel, table=True):
+    """会议室实体。
+
+    表示办公点下可预约的物理空间，可被 `Ceremony` 与 `Calendar` 使用。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     name: str
     office_id: int = Field(foreign_key="office.id")
@@ -391,6 +610,11 @@ class Room(SQLModel, table=True):
 
 
 class Calendar(SQLModel, table=True):
+    """日历实体。
+
+    表示员工或会议室维度的日程容器，用于组织多个 `CalendarEvent`。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     owner_id: int | None = Field(default=None, foreign_key="employee.id")
@@ -401,6 +625,11 @@ class Calendar(SQLModel, table=True):
 
 
 class CalendarEvent(SQLModel, table=True):
+    """日历事件实体。
+
+    表示某个日历中的单次事件安排，是会议、提醒或占用时段的具体记录。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     calendar_id: int = Field(foreign_key="calendar.id")
@@ -408,6 +637,17 @@ class CalendarEvent(SQLModel, table=True):
 
 
 class Document(SQLModel, table=True):
+    """文档实体。
+
+    表示项目过程中的知识、方案或交付文档，可附带附件并维护多个版本。
+
+    ## 关键关系
+
+    - 可归属一个 `Project`
+    - 拥有多个 `Attachment`
+    - 拥有多个 `DocumentRevision`
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     project_id: int | None = Field(default=None, foreign_key="project.id")
@@ -417,6 +657,11 @@ class Document(SQLModel, table=True):
 
 
 class DocumentRevision(SQLModel, table=True):
+    """文档版本实体。
+
+    表示文档随时间演进的版本快照，用于追踪知识内容的历史变更。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     version: str
     document_id: int = Field(foreign_key="document.id")
@@ -424,6 +669,11 @@ class DocumentRevision(SQLModel, table=True):
 
 
 class Dashboard(SQLModel, table=True):
+    """仪表盘实体。
+
+    表示工作区下聚合展示指标的小面板集合，用于集中观察项目或团队状态。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     workspace_id: int = Field(foreign_key="workspace.id")
@@ -432,6 +682,11 @@ class Dashboard(SQLModel, table=True):
 
 
 class Widget(SQLModel, table=True):
+    """组件实体。
+
+    表示仪表盘中的单个可视化卡片，是指标、图表或摘要信息的最小展示单元。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     dashboard_id: int = Field(foreign_key="dashboard.id")
@@ -439,6 +694,11 @@ class Widget(SQLModel, table=True):
 
 
 class Notification(SQLModel, table=True):
+    """通知实体。
+
+    表示发送给员工的站内提醒消息，用于同步审批、任务或系统状态变更。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     recipient_id: int = Field(foreign_key="employee.id")
@@ -446,6 +706,11 @@ class Notification(SQLModel, table=True):
 
 
 class Vendor(SQLModel, table=True):
+    """供应商实体。
+
+    表示与组织合作的外部服务或设备提供方，可关联合同与资产来源。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     name: str
     organization_id: int = Field(foreign_key="organization.id")
@@ -455,6 +720,11 @@ class Vendor(SQLModel, table=True):
 
 
 class Contract(SQLModel, table=True):
+    """合同实体。
+
+    表示与供应商签署的业务合同记录，是发票和采购关系的上游业务对象。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     code: str
     vendor_id: int = Field(foreign_key="vendor.id")
@@ -463,6 +733,11 @@ class Contract(SQLModel, table=True):
 
 
 class Invoice(SQLModel, table=True):
+    """发票实体。
+
+    表示合同或项目相关的财务结算记录，可同时连接采购与项目交付场景。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     amount: float
     contract_id: int | None = Field(default=None, foreign_key="contract.id")
@@ -472,6 +747,11 @@ class Invoice(SQLModel, table=True):
 
 
 class Asset(SQLModel, table=True):
+    """资产实体。
+
+    表示归属员工或供应商来源的设备资产，用于管理设备分配和来源追踪。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     name: str
     owner_id: int | None = Field(default=None, foreign_key="employee.id")
@@ -481,6 +761,22 @@ class Asset(SQLModel, table=True):
 
 
 class Risk(SQLModel, table=True):
+    """风险实体。
+
+    表示项目或任务上的潜在问题与风险点，用于提前识别影响交付的不确定因素。
+
+    ## 风险升级路径
+
+    ```mermaid
+    flowchart LR
+        Identified[识别] --> Assessed[评估]
+        Assessed --> Mitigated[缓解]
+        Assessed --> Escalated[升级]
+        Escalated --> Closed[关闭]
+        Mitigated --> Closed
+    ```
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     project_id: int | None = Field(default=None, foreign_key="project.id")
@@ -490,6 +786,11 @@ class Risk(SQLModel, table=True):
 
 
 class AutomationRule(SQLModel, table=True):
+    """自动化规则实体。
+
+    表示工作区内的流程自动执行配置，用于在特定条件下自动驱动协作流程。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     name: str
     workspace_id: int = Field(foreign_key="workspace.id")
@@ -497,6 +798,11 @@ class AutomationRule(SQLModel, table=True):
 
 
 class KnowledgeArticle(SQLModel, table=True):
+    """知识文章实体。
+
+    表示由员工撰写和维护的内部知识内容，是组织沉淀经验与规范的载体。
+    """
+
     id: int | None = Field(default=None, primary_key=True)
     title: str
     author_id: int | None = Field(default=None, foreign_key="employee.id")
diff --git a/src/nexusx/voyager/voyager_context.py b/src/nexusx/voyager/voyager_context.py
index 8d58220..37f9583 100644
--- a/src/nexusx/voyager/voyager_context.py
+++ b/src/nexusx/voyager/voyager_context.py
@@ -5,6 +5,7 @@
 """
 from __future__ import annotations
 
+import inspect
 import sys
 from pathlib import Path
 
@@ -354,7 +355,7 @@ def get_docstring(self, schema_name: str) -> dict:
             obj = self._resolve_object(schema_name)
             if obj is None:
                 return {"error": "Invalid schema name format."}
-            return {"docstring": (obj.__doc__ or "")}
+            return {"docstring": inspect.cleandoc(obj.__doc__ or "")}
         except ImportError as e:
             return {"error": f"Module not found: {e}"}
         except AttributeError as e:
diff --git a/src/nexusx/voyager/web/component/about-display.js b/src/nexusx/voyager/web/component/about-display.js
index 9bfcc1c..8f8871d 100644
--- a/src/nexusx/voyager/web/component/about-display.js
+++ b/src/nexusx/voyager/web/component/about-display.js
@@ -271,7 +271,7 @@ export default defineComponent({
     }
   },
   template: `
-  <div class="about-display" style="height:100%; overflow:auto; background:#fff;">
+  <div class="about-display" style="height:100%; overflow:hidden; background:#fff;">
     <div v-show="loading" style="position:absolute; top:0; left:0; right:0; z-index:10;">
       <q-linear-progress indeterminate color="primary" size="2px" />
     </div>
@@ -281,7 +281,7 @@ export default defineComponent({
     <div v-else-if="computeEmpty()" class="text-grey-7" style="padding:12px 16px;">
       该实体暂无 docstring。
     </div>
-    <div ref="contentRef" class="markdown-body" style="padding:8px 16px;"></div>
+    <div ref="contentRef" class="markdown-body about-markdown-body" style="height:100%; overflow:auto; padding:8px 16px 16px 16px;"></div>
   </div>
   `,
 })
diff --git a/src/nexusx/voyager/web/component/schema-code-display.js b/src/nexusx/voyager/web/component/schema-code-display.js
index bbf0d06..f6e44b5 100644
--- a/src/nexusx/voyager/web/component/schema-code-display.js
+++ b/src/nexusx/voyager/web/component/schema-code-display.js
@@ -157,18 +157,18 @@ export default defineComponent({
     return { link, code, error, fields, tab, loading, showRelatedEntities: props.showRelatedEntities, showAbout: props.showAbout }
   },
   template: `
-  <div class="frv-code-display" style="border: 1px solid #ccc; border-left: none; position:relative; height:100%; background:#fff;">
+  <div class="frv-code-display" style="border: 1px solid #ccc; border-left: none; position:relative; height:100%; background:#fff; display:flex; flex-direction:column; overflow:hidden;">
       <div v-show="loading" style="position:absolute; top:0; left:0; right:0; z-index:10;">
         <q-linear-progress indeterminate color="primary" size="2px"/>
       </div>
-      <div class="q-ml-lg q-mt-md">
+      <div class="q-ml-lg q-mt-md" style="flex:0 0 auto;">
         <p style="font-size: 16px;"> {{ schemaName }} </p>
         <a :href="link" target="_blank" rel="noopener" style="font-size:12px; color:#3b82f6;">
           Open in VSCode
         </a>
       </div>
 
-      <div style="padding:8px 12px 0 12px; box-sizing:border-box;">
+      <div style="padding:8px 12px 0 12px; box-sizing:border-box; flex:0 0 auto;">
         <q-tabs v-model="tab" align="left" dense active-color="primary" indicator-color="primary" class="text-grey-8">
           <q-tab v-if="showAbout" name="about" label="About" />
           <q-tab name="fields" label="Fields" />
@@ -176,8 +176,8 @@ export default defineComponent({
           <q-tab v-if="showRelatedEntities" name="related" label="Related Entities" />
         </q-tabs>
       </div>
-      <q-separator />
-      <div style="padding:8px 16px 16px 16px; box-sizing:border-box; overflow:auto;">
+      <q-separator style="flex:0 0 auto;" />
+      <div class="schema-detail-body" style="padding:8px 16px 16px 16px; box-sizing:border-box; flex:1 1 auto; min-height:0; overflow:auto;">
         <div v-if="error" style="color:#c10015; font-family:Menlo, monospace; font-size:12px;">{{ error }}</div>
         <template v-else>
           <div v-show="tab === 'fields'">
@@ -206,13 +206,13 @@ export default defineComponent({
           <div v-show="tab === 'source'">
             <pre style="margin:0;"><code class="language-python">{{ code }}</code></pre>
           </div>
-          <div v-show="tab === 'related'" style="height: calc(100vh - 220px); min-height: 300px;">
+          <div v-show="tab === 'related'" style="height:100%; min-height:300px;">
             <related-entities-display
               :schema-name="schemaName"
               :visible="tab === 'related' && modelValue"
             ></related-entities-display>
           </div>
-          <div v-show="tab === 'about'">
+          <div v-show="tab === 'about'" style="height:100%; min-height:0;">
             <about-display
               :schema-name="schemaName"
               :visible="tab === 'about' && modelValue"
diff --git a/src/nexusx/voyager/web/index.html b/src/nexusx/voyager/web/index.html
index d27b45c..cb4a37d 100644
--- a/src/nexusx/voyager/web/index.html
+++ b/src/nexusx/voyager/web/index.html
@@ -85,6 +85,45 @@
       height: calc(100vh - 54px);
     }
 
+    .about-markdown-body h1,
+    .about-markdown-body h2,
+    .about-markdown-body h3,
+    .about-markdown-body h4,
+    .about-markdown-body h5,
+    .about-markdown-body h6 {
+      margin: 1em 0 0.5em;
+      line-height: 1.3;
+      font-weight: 600;
+    }
+
+    .about-markdown-body h1 {
+      font-size: 1.5rem;
+    }
+
+    .about-markdown-body h2 {
+      font-size: 1.3rem;
+    }
+
+    .about-markdown-body h3 {
+      font-size: 1.15rem;
+    }
+
+    .about-markdown-body h4 {
+      font-size: 1rem;
+    }
+
+    .about-markdown-body h5 {
+      font-size: 0.92rem;
+    }
+
+    .about-markdown-body h6 {
+      font-size: 0.85rem;
+    }
+
+    .about-markdown-body > :first-child {
+      margin-top: 0;
+    }
+
     .github-corner:hover .octo-arm {
       animation: octocat-wave 560ms ease-in-out;
     }