diff --git a/ui/AGENTS.md b/ui/AGENTS.md
index 30cb7e43ce4..0450eedfa23 100644
--- a/ui/AGENTS.md
+++ b/ui/AGENTS.md
@@ -1,232 +1,67 @@
 # MaxKB v3 Frontend
 
-This document is for frontend agents working in the `ui/` project.
-
-## Documentation Workflow
-
-`AGENTS.md` is the Codex-maintained entry point for project-wide instructions. It provides the project overview, shared conventions, and an index of topic-specific rule documents; it does not replace the detailed rules owned by those documents.
-
-Before making changes, determine which areas the task touches and read the corresponding rule documents:
-
-- Styles: `src/styles/STYLE_README.md` is the source of truth for styling rules.
-- Router: `src/router/ROUTE_README.md` is the source of truth for routing rules.
-- Components: `src/components/COMPONENT_README.md` is the source of truth for component rules.
-- Constants: `src/constants/CONSTANT_README.md` is the source of truth for shared constant rules.
-- Utilities: `src/utils/UTILS_README.md` is the source of truth for shared utility rules.
-- API: `src/api/API_README.md` is the source of truth for request infrastructure, business API
-  organization, and API type ownership.
-- Views: `src/views/VIEW_README.md` is the source of truth for page responsibilities and
-  feature-local code organization.
-- Workflow canvas: `src/workflow-canvas/WORKFLOW_README.md` is the source of truth for LogicFlow canvas
-  responsibilities, configuration boundaries, node maintenance, and View integration.
-
-Follow this maintenance flow:
-
-1. Use `AGENTS.md` to understand the project-wide context and locate applicable rule documents.
-2. Read every applicable rule document before implementing or reviewing changes in that area.
-3. Keep detailed, area-specific guidance in its owning README; keep only the summary and document index in `AGENTS.md`.
-4. When a new area-specific rule README is added, append it to the list above and reference it in the relevant project-structure or responsibility section of `AGENTS.md`.
-5. When a rule changes, update its owning README and adjust the summary in `AGENTS.md` only when the project-wide guidance or index also changes.
-
-## Stack
-
-- Vue 3.5 with `<script setup lang="ts">`
-- TypeScript 6
-- Vite 8
-- Vue Router 5
-- Pinia 3
-- Tailwind CSS 4 through `@tailwindcss/vite`
-- Sass through Vite's native Sass support
-- Element Plus
-
-## Project Structure
-
-```text
-ui/
-├── admin.html                 # Admin application HTML entry
-├── chat.html                  # Chat application HTML entry
-├── env/                       # Environment variables for each application mode
-├── public/                    # Static files copied to the build output as-is
-├── src/
-│   ├── App.vue               # Root Vue component and router outlet
-│   ├── main.ts               # Admin application bootstrap
-│   ├── chat.ts               # Chat application bootstrap
-│   ├── assets/                # Images and other source-controlled visual assets
-│   │   ├── iconfont.js        # Generated SVG Symbol resource; replace, do not edit
-│   │   ├── logo/             # Product and brand logos
-│   │   └── workflow/         # Workflow-related visual assets
-│   ├── api/                   # Request infrastructure, business APIs, enums, and shared API types
-│   │   ├── enums/             # Backend fixed-value enums, exposed through one public entry
-│   │   ├── types/             # Types shared by APIs and their View or Component consumers
-│   │   └── API_README.md      # API layering, placement, typing, and request rules
-│   ├── components/            # Shared UI and cross-page business components
-│   │   ├── COMPONENT_README.md # Shared component conventions and usage
-│   │   ├── business/          # Cross-page business components, imported explicitly
-│   │   ├── global/            # Frequently used components auto-registered by Vite
-│   │   │   └── mk-icon/       # Unified SVG Symbol and Element Plus icon component
-│   │   └── <component-name>/   # Less-frequent shared components imported explicitly
-│   ├── conversation-panel/    # Conversation UI, local state, streaming, and API mode selection
-│   ├── constants/             # Cross-feature constants grouped by domain
-│   │   └── CONSTANT_README.md # Shared constant placement and naming rules
-│   ├── layout/                # Shared application shells, headers, sidebars, types, and helpers
-│   ├── permission/            # Permission policies, business permission methods, and Admin $perm plugin
-│   ├── workflow-canvas/       # LogicFlow canvas and workflow domain components
-│   │   ├── component/         # Reusable workflow canvas UI
-│   │   ├── config/            # Maintainable node data, menus, mappings, and constants
-│   │   ├── core/              # Stable canvas behavior and shared node infrastructure
-│   │   ├── Execution-details/ # Node execution detail dispatch and shared presentation
-│   │   ├── icons/             # Workflow node icons
-│   │   ├── node-menu/         # Basic, tool, and application node selection menus
-│   │   ├── nodes/             # Workflow node definitions and components
-│   │   ├── plugins/           # Canvas-local plugins
-│   │   ├── store/             # Resource API adapters, query caching, and request deduplication
-│   │   ├── WORKFLOW_README.md # Canvas boundaries and maintenance rules
-│   │   ├── types.ts           # Workflow canvas protocol types
-│   │   └── index.vue          # WorkflowCanvas canvas entry
-│   ├── router/                # Vue Router routes and router instance
-│   │   └── ROUTE_README.md    # Routing conventions and rules
-│   ├── stores/                # Shared Pinia instance and state stores
-│   ├── styles/                # Global styles, theme tokens, and third-party style integration
-│   │   ├── font/             # Locally hosted application fonts
-│   │   ├── variables.scss    # Canonical runtime `--mk-*` color and theme variables
-│   │   ├── element-plus.scss # Element Plus Sass configuration and CSS-variable mapping
-│   │   ├── tailwind.css      # Tailwind import and `mk-*` theme token mapping
-│   │   ├── app.scss          # Fonts, base element styles, and app-wide defaults
-│   │   ├── index.scss        # Sass entry that aggregates global Sass modules
-│   │   └── STYLE_README.md    # Local UI conventions and color-variable usage examples
-│   ├── utils/                 # Cross-feature utilities grouped by domain or capability
-│   │   └── UTILS_README.md    # Shared utility placement and naming rules
-│   ├── views/                 # Route-level page components grouped by feature
-│   │   ├── VIEW_README.md     # Page responsibilities and feature-local code rules
-│   │   ├── home/             # Workspace home page
-│   │   ├── application/      # Application list and creation
-│   │   ├── application-detail/ # Application overview and settings
-│   │   ├── knowledge/        # Knowledge base list and cards
-│   │   ├── knowledge-detail/ # Knowledge base details, document lists, and settings
-│   │   ├── document-detail/  # Document details and paragraph management
-│   │   ├── model/            # Model list, creation, and settings
-│   │   ├── tool/             # Tool list, forms, and tool store
-│   │   ├── trigger/          # Workspace trigger list
-│   │   ├── system/           # System-management pages
-│   │   ├── login/            # Admin login, account recovery, and login modes
-│   │   ├── chat/             # Chat entry placeholder page
-│   │   ├── error/            # Not-found page
-│   │   ├── details-demo/     # Temporary execution-detail preview page
-│   │   └── workflow/         # Full-screen workflow route pages
-├── vite.config.ts            # Vite entries, plugins, aliases, proxy, and build output
-├── tsconfig*.json            # TypeScript configuration
-└── package.json              # Dependencies and npm scripts
-```
-
-Internationalization is not yet integrated; `src/locales/` has not been created. Chat currently has a
-placeholder route page and an independent API client with conversation endpoints. Add files to the matching feature
-directory instead of creating parallel top-level structures.
-
-Structural responsibilities:
-
-- Put cross-page business components in `components/business/`, name them after their business
-  responsibility without the `Mk` prefix, and keep page-specific components in their owning View.
-- Put reusable application chrome in `layout/`, not in individual route views.
-- Keep LogicFlow initialization, node registration, and canvas behavior inside `workflow-canvas/`.
-  Every page rendering this canvas belongs in `views/workflow/`; those Views own the page header,
-  route and page-level actions around `WorkflowCanvas`.
-- Request version guards are reserved for `MkInfiniteScroll`; add them elsewhere only when explicitly requested. See `src/api/API_README.md`.
-- Put server communication in `api/`, isolate Admin and Chat request systems, and group business APIs
-  by domain and resource according to `src/api/API_README.md`.
-- Put backend fixed-value enums in `api/enums/` and import them through `@/api/enums`; keep
-  `api/types/` as the type-only public entry for API and UI consumers.
-- Put constants shared by most pages or multiple business modules in `constants/`, and split files by a specific domain. Keep constants used by only one page or feature with their owning code.
-- Put shared client state in `stores/`; component-local state should remain in the component.
-- Reuse the Pinia instance exported by `stores/index.ts`; application code accesses Store instances
-  through `useStore()`. Store modules may import a specific Store directly when coordinating state
-  internally to avoid circular access through the aggregate entry.
-- Put functions shared by most pages or multiple business modules in `utils/`; detailed placement, file organization, and naming rules are maintained in `src/utils/UTILS_README.md`.
-- Treat application, knowledge, model, and tool as the four special resource domains that can span
-  Workspace resources, Workspace shared resources, System resource management, and System shared resources. Their route scope, API
-  selection, reusable cards, and context-specific Actions follow `ROUTE_README.md`,
-  `API_README.md`, and `VIEW_README.md`; do not extend this resource-scope pattern to ordinary pages.
-- Import source assets through `src/assets/`; use `public/` only when a file must retain its original filename and URL.
-
-## Entry Points
-
-The frontend is designed as a multi-entry app:
-
-- Admin entry: `admin.html` -> `src/main.ts`
-- Chat entry: `chat.html` -> `src/chat.ts`
-
-Environment files live in `env/`:
-
-- `env/.env` for admin
-- `env/.env.chat` for chat
-
-Important variables:
-
-- `VITE_APP_NAME`: app name, such as `admin` or `chat`
-- `VITE_BASE_PATH`: deployed base path, such as `/admin/` or `/chat/`
-- `VITE_APP_PORT`: local dev server port
-- `VITE_APP_TITLE`: HTML title
-- `VITE_ENTRY`: HTML entry file
-- `VITE_API_TARGET`: optional backend proxy target; currently defaults to `http://47.120.55.164:38080`
-  through `defaultBackendTarget` in `vite.config.ts`. Override it locally for a different backend.
-
-Build output mirrors the v2 layout:
-
-- Admin builds to `dist/admin/index.html`
-- Chat builds to `dist/chat/index.html`
-
-The Vite config builds `admin.html` or `chat.html` first, then renames the entry HTML to `index.html` inside the relevant output directory.
-
-## Commands
-
-Run commands from `ui/`.
-
-```bash
-npm install
-npm run dev          # admin dev server
-npm run chat         # chat dev server
-npm run build        # default admin build with type-check
-npm run build-chat   # chat build with type-check
-npm run type-check
-npm run format
-```
-
-Node.js must satisfy `^22.18.0 || >=24.12.0` as declared in `package.json`.
-Admin and Chat use ports 3000 and 3001 respectively, with `strictPort` enabled.
-`npm run lint` currently delegates to `lint:*`, but no matching scripts are defined. Use
-`npx eslint <changed-files>` for targeted linting until those scripts are configured.
-ESLint enforces multi-word Vue component names, with `index` globally exempted in `eslint.config.ts`.
-
-## Vite Configuration
-
-Main config: `vite.config.ts`.
-
-Keep these behaviors:
-
-- `base: './'` for v2-compatible static deployment.
-- `envDir: './env'`.
-- Proxy `/admin/api`, `/chat/api`, `/doc`, `/schema`, `/static`, and `oss` file paths to the backend.
-- Keep Tailwind, Vue, Vue JSX, and component auto registration plugins.
-- Do not add `unplugin-vue-define-options`; Vue 3.5 already supports `defineOptions`.
-- Avoid adding `vite-plugin-html` unless multi-template requirements exceed Vite's built-in HTML env replacement.
-
-## Frontend Implementation Notes
-
-- Newly implemented frontend features must not add permission checks or permission-based visibility
-  or disabled states until the user explicitly requests them. Preserve existing permission logic
-  outside the requested scope; page-specific guidance is maintained in `src/views/VIEW_README.md`.
-- Prefer existing project structure and naming.
-- Do not modify shared components under `src/components/` without an explicit user instruction to
-  change those components. Follow the modification boundary in `src/components/COMPONENT_README.md`.
-- Do not write `aria-label` attributes in project source. Add concise Chinese HTML comments before
-  buttons to describe their purpose, following `src/components/COMPONENT_README.md`.
-- Before changing existing behavior, trace the affected flow and dependent requirements, including
-  why the current implementation exists. If the requested change is likely to remove a requirement
-  or introduce a regression, pause before editing, explain the risk, recommend a safer approach,
-  and wait for confirmation.
-- 表单创建、保存和提交使用页面／弹窗内容 loading 或按钮 loading，不逐项禁用表单字段；
-  详细规则见 `src/views/VIEW_README.md`。
-- Keep UI code typed and data-driven.
-- Use Lodash `cloneDeep` for deep cloning; do not use `structuredClone`.
-- Explicitly import APIs used from Vue, Vue Router, and Pinia; do not restore API auto import.
-- Name business variables after their domain and purpose. Avoid context-free collection names such as
-  `items` or `list` when a name such as `systemMenuItems` makes the contents clear.
+本文是 `ui/` 的共享开发规则入口。项目采用 Vue 3.5、TypeScript 6、Vite 8、Vue Router 5、
+Pinia 3、Element Plus、Tailwind CSS 4 和 Sass；工作流画布基于 LogicFlow。
+
+## 文档分工
+
+修改或评审前读取涉及领域的文档。每条详细规则只在所属文档维护，其他文档通过链接引用；
+更新时保留当前职责、公开接口及必要约束，不记录迁移步骤、改动历史或内部函数清单。
+
+| 文档                                                         | 负责内容                             |
+| ------------------------------------------------------------ | ------------------------------------ |
+| [README.md](README.md)                                       | 开发、环境变量、命令与部署           |
+| [STYLE_README.md](src/styles/STYLE_README.md)                | 样式、主题、布局与 Element Plus 覆盖 |
+| [COMPONENT_README.md](src/components/COMPONENT_README.md)    | 共享组件边界、接口与使用约定         |
+| [API_README.md](src/api/API_README.md)                       | 请求、业务 API、类型与枚举           |
+| [ROUTE_README.md](src/router/ROUTE_README.md)                | 路由、导航、认证与资源范围           |
+| [VIEW_README.md](src/views/VIEW_README.md)                   | 页面职责、功能本地组织与业务约束     |
+| [WORKFLOW_README.md](src/workflow-canvas/WORKFLOW_README.md) | 画布内核、节点、资源查询与接入接口   |
+| [CONSTANT_README.md](src/constants/CONSTANT_README.md)       | 共享展示常量                         |
+| [UTILS_README.md](src/utils/UTILS_README.md)                 | 共享工具函数与组合式函数             |
+
+新增专题规则文档时补充此索引；仅在目录、公开接口或使用规则变化时同步对应章节。
+文档描述当前工作区的实现；已有未提交改动不得擅自覆盖或回退。
+
+## 目录职责
+
+| 位置                                    | 职责                                                     |
+| --------------------------------------- | -------------------------------------------------------- |
+| `admin.html` → `src/main.ts`            | Admin 入口                                               |
+| `chat.html` → `src/chat.ts`             | Chat 入口，包含单应用与门户对话                          |
+| `env/`                                  | 各入口环境配置                                           |
+| `src/api/`                              | Admin / Chat 请求、业务接口、共享类型与后端枚举          |
+| `src/components/`                       | 全局 UI、显式导入的共享 UI 与跨页面业务组件              |
+| `src/layout/`                           | 应用头部、侧栏与资源详情布局                             |
+| `src/views/`                            | 路由页面及功能本地代码；全屏画布页面在 `views/workflow/` |
+| `src/conversation-panel/`               | 对话装配、流式处理、组件与局部状态                       |
+| `src/workflow-canvas/`                  | LogicFlow、节点、画布配置与资源查询适配器                |
+| `src/router/`                           | Admin / Chat 独立 Router                                 |
+| `src/stores/admin/`、`src/stores/chat/` | 各入口独立 Pinia 实例和 Store                            |
+| `src/permission/`                       | 权限策略、业务权限方法及 Admin `$perm` 插件              |
+| `src/styles/`                           | 全局样式、主题变量与第三方样式集成                       |
+| `src/constants/`、`src/utils/`          | 跨功能常量与工具                                         |
+| `src/assets/`、`public/`                | 源码导入资源／需要保留原文件名和 URL 的静态文件          |
+
+国际化尚未集成，未创建 `src/locales/`。文件放入现有功能边界，不创建平行的顶层结构。
+各入口复用自己的 Pinia：Admin 使用 `@/stores/admin`，Chat 使用 `@/stores/chat` 的 `useStore()`；
+Store 内部协调状态时可直接引用同入口的具体 Store，避免聚合入口循环依赖。
+`src/stores/index.ts` 当前是 Admin 兼容入口，不能用它获取 Chat Store。
+
+## 通用开发约束
+
+- 新功能未经用户明确要求不增加权限判断；保留范围外既有权限逻辑。
+- 未经用户明确指令不修改共享组件实现；具体边界见组件文档。
+- 不编写 `aria-label`；操作入口前添加简短中文 HTML 用途注释，细则见组件文档。
+- 变更现有行为前追踪调用流程与依赖；可能删除已有要求或引入回归时，先说明风险和安全方案，等待确认。
+- Vue、Vue Router、Pinia API 显式导入，不恢复 API 自动导入。
+- 深拷贝使用 Lodash `cloneDeep`，不使用 `structuredClone`。
+- 类型化、数据驱动；变量以领域和用途命名，不使用脱离上下文的 `items`、`list`。
+- 共享规则与功能本地实现分别按专题文档维护，不为单页需求提前提升公共代码。
+- 不手工修改 `src/components.d.ts` 等生成文件，通过正常开发或构建流程生成。
+
+## 验证
+
+只改文档：核对代码、路径引用、Prettier 格式及 `git diff --check`。
+Vue / TypeScript 改动：运行定向 ESLint 和 `npm run type-check`；影响入口或构建时增加对应生产构建。
+命令、Node 版本和 `lint` 脚本现状见 [README.md](README.md)。
diff --git a/ui/README.md b/ui/README.md
index 920cb8d572f..6e78c4687b8 100644
--- a/ui/README.md
+++ b/ui/README.md
@@ -4,7 +4,7 @@ MaxKB 企业级 AI 智能体平台的前端工程，使用 Vue 3.5、TypeScript
 Tailwind CSS 4、Pinia 3 和 Vue Router 5，工作流画布基于 LogicFlow。
 
 项目采用 Admin 和 Chat 双入口。Admin 包含登录、工作空间资源、系统管理和工作流编辑等功能；
-Chat 已配置独立入口与路由，当前 `ChatView.vue` 仍为空白占位页，`src/api/chat/` 的独立请求体系尚未实现。
+Chat 包含单应用与门户认证、智能体列表及正式对话，使用独立的 Router、Pinia 和请求客户端。
 
 ## 本地开发
 
@@ -65,35 +65,7 @@ ESLint 检查的依据。需要检查代码时，可运行 `npx eslint <待检
 静态资源使用相对路径（`base: './'`）；部署时仍需为 History 路由配置对应入口回退，
 并由部署服务转发 API 和文件请求。Vite 的开发代理不会随静态构建产物部署。
 
-## 代码目录
-
-| 目录或文件                      | 职责                                                 |
-| ------------------------------- | ---------------------------------------------------- |
-| `src/main.ts` / `src/chat.ts`   | Admin / Chat 启动入口                                |
-| `src/api/`                      | 请求基础设施、业务 API、后端枚举与共享类型           |
-| `src/components/`               | 全局 Mk 组件、跨页面业务组件及其他共享组件           |
-| `src/layout/`                   | 应用头部、侧栏与资源详情布局                         |
-| `src/views/`                    | 登录、工作空间、系统管理、资源详情和工作流等路由页面 |
-| `src/workflow-canvas/`          | 画布内核、节点配置、节点实现、执行详情与资源查询缓存 |
-| `src/router/`                   | Admin / Chat 独立路由                                |
-| `src/permission/`               | 权限策略、分业务权限方法与 Admin `$perm` 插件        |
-| `src/stores/`                   | 共享 Pinia 实例及认证、用户、主题状态                |
-| `src/styles/`                   | 主题变量、Tailwind、Element Plus 集成与全局样式      |
-| `src/constants/` / `src/utils/` | 跨功能常量与工具函数                                 |
-| `src/assets/` / `public/`       | 源码导入资源 / 保留原始路径的静态资源                |
-
-## 开发约定与文档
-
-修改前先阅读 [AGENTS.md](AGENTS.md)，再阅读涉及领域的规则文档：
-
-- [样式](src/styles/STYLE_README.md)
-- [组件](src/components/COMPONENT_README.md)
-- [路由](src/router/ROUTE_README.md)
-- [API](src/api/API_README.md)
-- [页面](src/views/VIEW_README.md)
-- [工作流画布](src/workflow-canvas/WORKFLOW_README.md)
-- [常量](src/constants/CONSTANT_README.md)
-- [工具函数](src/utils/UTILS_README.md)
-
-详细规则由各领域 README 维护；目录、公共接口或使用约定变化时同步对应文档。
-`src/components.d.ts` 由组件自动注册插件生成，不手动编辑。
+## 开发规则
+
+目录职责、开发约束和专题文档索引统一见 [AGENTS.md](AGENTS.md)。
+修改代码前读取对应专题，文档只维护当前实现和使用规则。
diff --git a/ui/src/api/API_README.md b/ui/src/api/API_README.md
index f62732e46a6..276c6d6a748 100644
--- a/ui/src/api/API_README.md
+++ b/ui/src/api/API_README.md
@@ -3,51 +3,20 @@
 `src/api` 负责前端与服务端之间的通信，按照应用入口隔离 Admin 与 Chat 请求体系。
 Admin 与 Chat 分别维护请求客户端和业务接口。
 
-```text
-src/api/
-├── constants.ts                     # Admin 与 Chat 的 API base 路径常量
-├── admin/
-│   ├── file.ts                       # 通用文件上传、进度与取消
-│   ├── auth/                         # Admin 登录认证与当前用户接口
-│   │   └── types.ts                  # 认证 API 与认证 Store 共用类型
-│   ├── core/                         # Admin 请求基础能力
-│   │   ├── request.ts                # Axios 实例、HTTP 方法与统一响应解包
-│   │   └── types.ts                  # Admin 请求协议类型
-│   ├── system/                       # 系统管理业务接口
-│   │   ├── chat-user/                # 对话用户、用户组及认证接口
-│   │   ├── settings/                 # 登录认证、邮件与外观设置接口
-│   │   ├── resource-management/      # System 资源管理接口
-│   │   ├── shared-resources/         # System 共享资源接口
-│   │   └── <resource>.ts             # 其他 System 单资源接口
-│   ├── workspace/                    # 工作空间业务接口
-│   │   ├── conversation.ts           # 调试对话、历史会话与语音接口
-│   │   ├── application/              # 智能体接口
-│   │   ├── knowledge/                # 知识库接口
-│   │   ├── shared/                   # 工作空间可用的共享模型、工具、知识库查询
-│   │   ├── model.ts                  # 模型接口
-│   │   ├── trigger/                   # 触发器查询及维护接口
-│   │   ├── tool/                     # 工具、工具工作流及工具商店接口
-│   │   └── <resource>.ts             # 工作空间公共资源接口
-│   └── model-provider.ts                   # Workspace 与 System 共用的模型供应商接口
-├── chat/                             # Chat 独立请求体系
-│   ├── core/request.ts               # JSON 与流式请求
-│   ├── core/types.ts                 # Chat 请求协议类型
-│   ├── file.ts                       # Chat 文件上传、进度与取消
-│   ├── auth.ts                       # 门户与单应用的认证前置配置、匿名认证、登录与登出
-│   ├── chat-user.ts                  # 当前对话用户档案
-│   ├── application.ts                # 对话端智能体信息（v3 application/<id>/profile）
-│   ├── portal.ts                     # 门户全部智能体（v3 portal/application）与按智能体分组的历史对话（v3 portal/chat）
-│   ├── conversation.ts               # 正式对话、历史会话与语音接口
-│   └── README.md                     # Chat API 边界说明
-├── enums/                            # 后端固定枚举值
-│   ├── index.ts                      # API 枚举值的唯一导入入口
-│   └── <domain>.ts                   # 按明确业务域拆分的枚举值
-├── types/                            # API 与 View/Component 共用的业务类型
-│   ├── index.ts                      # API 公共类型的唯一导入入口
-│   ├── common.ts                     # 多个 API 业务域共用的基础类型
-│   └── <domain>.ts                   # 按明确业务域拆分的共享类型
-└── API_README.md
-```
+## 目录职责
+
+| 位置                            | 职责                                                             |
+| ------------------------------- | ---------------------------------------------------------------- |
+| `constants.ts`                  | Admin／Chat API base 路径                                        |
+| `admin/core/`、`chat/core/`     | 各入口请求客户端与传输协议                                       |
+| `admin/auth/`                   | Admin 认证及当前账号                                             |
+| `admin/workspace/`              | Workspace 资源及业务接口                                         |
+| `admin/workspace/shared/`       | 工作空间可用的共享资源查询                                       |
+| `admin/system/`                 | 系统管理、资源管理、共享资源及设置                               |
+| `admin/model-provider.ts`       | 公共模型供应商查询                                               |
+| `admin/file.ts`、`chat/file.ts` | 各入口文件请求                                                   |
+| `chat/`                         | 正式对话、门户、认证和对话用户；见 [Chat README](chat/README.md) |
+| `enums/`、`types/`              | 后端枚举／跨 API 与 UI 共用业务类型，各自由 index.ts 对外导出    |
 
 ## 分层职责
 
@@ -66,15 +35,9 @@ src/api/
 
 ## 业务接口组织
 
-`admin/system/chat-management/portal-setting.ts` 通过 Admin `/portal` 读取和局部保存门户配置，
-公共类型维护在 `types/portal.ts`。JSON 用于访问开关和认证、跨域配置，门户名称与 Logo 使用
-FormData；保存返回完整配置，页面以该返回值作为唯一数据来源。
-认证配置保留未编辑字段，仅提交后端读取的 `login_value`、`max_attempts`、`failed_attempts`、
-`lock_time`；跨域地址直接提交后端 `Portal.cross_domain_list` 数组字段，不再维护 `cors_config`。
-
 - 业务 API 先按 Admin 入口下的 `auth`、`workspace`、`system` 等一级业务域归类。Workspace 和
   System 内部可继续按明确的功能域建立子目录，例如 `workspace/application/`、
-  `workspace/tool/`、`system/chat-user/` 和 `system/settings/`；不需要分组的单资源接口直接放在
+  `workspace/tool/`、`system/chat-management/` 和 `system/settings/`；不需要分组的单资源接口直接放在
   所属一级业务域下。
 - 一类资源的增删改查放在同一个最终资源文件中。调用方直接导入该文件，不为业务目录创建聚合
   入口，也不创建汇总所有业务接口的 `api.ts`。
@@ -93,182 +56,10 @@ FormData；保存返回完整配置，页面以该返回值作为唯一数据来
   `import WorkspaceApi from '@/api/admin/system/workspace'`；System 登录设置使用
   `import AuthSettingApi from '@/api/admin/system/settings/auth-setting'`。
 
-### 当前账号密码
-
-`admin/auth/current-user.ts` 的 `postCurrentUserPassword` 向 `/user/current/reset_password`
-提交 RSA 加密的 `{ encryptedData }`。头像菜单的 `layout/avatar-dropdown/ChangePasswordDialog.vue`
-负责新密码与确认密码校验、加密和提交，成功后清除本地登录凭据并跳转登录页。
-
-### 四类特殊资源 API
-
-根据资源范围或业务上下文选择出的 API 对象统一命名为 `requestApi`，包括 `computed` 结果和
-局部变量，不使用 `toolApi`、`authorizationApi` 或 `request` 等名称。同一作用域确需同时使用
-多套 API 时，以 `request` 为前缀加业务名区分，例如 `requestModelApi`、`requestToolApi`。
-知识库详情上下文的多模块接口入口使用 `resourceApi.knowledge / sync`，通过响应式 getter
-读取当前范围，无需 `.value`；方法内选定单个接口对象时仍命名为 `requestApi`。
-直接导入的 API 保持 PascalCase 命名；请求返回的 Promise 不属于此命名规则。
-
-`application`、`knowledge`、`model`、`tool` 是需要同时考虑 Workspace 普通资源、Workspace 共享资源、System 资源管理和
-System 共享资源的四类特殊资源。其接口按真实后端边界分别维护在 `admin/workspace/` 与
-`admin/system/` 下，不把不同范围的 URL 合并为页面侧 API Map，也不让卡片或 Action 根据路由拼接
-System 接口地址。
-
-页面根据路由 `resourceScope` 选择当前范围的完整业务 API 对象；知识库详情由功能本地
-`views/knowledge-detail/context.ts` 集中装配，当前由详情入口与 setting 子页复用该选择，library 暂不迁移。缺失设置 API 模块保持未提供，
-不回退其他资源范围。页面将选定对象传给需要请求的 Card
-Action、Drawer 或 Dialog。复用方直接使用 `typeof XxxApi` 约束完整 API 对象；不要为每组 Action
-额外维护逐方法接口，例如 `ModelActionApi`，也不要使用不断扩展的 `Pick<typeof XxxApi, ...>`。
-完整 API 对象的方法集合不同时，共用组件使用完整对象类型的联合，例如
-`typeof ModelApi | typeof SystemSharedModelApi`，不为凑齐类型添加其他范围不存在的接口。
-仅展示数据的组件不接收 API。
-
-### 工作流发布历史
-
-`workspace/application/workflow.ts` 维护智能体 `application_version` 资源：
-`getWorkflowVersions(applicationId)` 返回按创建时间倒序的完整 `WorkflowVersion[]`；
-`putWorkflowVersion(applicationId, versionId, payload)` 编辑标题与更新说明，返回更新后的版本。
-共用类型 `WorkflowVersion` 和 `WorkflowVersionPayload` 位于 `types/workflow-version.ts`，
-通过 `@/api/types` 导出。`ButtonApplicationPublishHistory` 内部调用智能体版本 API，公共发布历史
-UI 组件只接收数据和事件，不接收 API 或推测其他工作流的接口地址。
-`workspace/tool/workflow.ts` 同时维护工具 `tool_version` 资源，提供
-`getWorkflowVersions(toolId)` 和 `putWorkflowVersion(toolId, versionId, payload)`，
-复用上述版本类型，由 `views/workflow/tool/ButtonPublishHistory.vue` 调用。
-工具版本接口同样尚未支持 `description`，且未返回版本的默认模型配置。
-`workspace/knowledge/workflow.ts` 维护知识库 `knowledge_version` 资源，提供同名查询与编辑方法，
-由知识库 `ButtonPublishHistory.vue` 调用；知识库版本也尚未支持更新说明和默认模型配置。
-
-v3 编辑表单提交 `{ name, description }`，标题上限 64、更新说明上限 1000。
-当前仓库后端的版本编辑序列化器只处理 `name`，列表和详情也未返回 `description`；
-更新说明的持久化与回显需要后端补齐，前端不将智能体自身的 `desc` 当作版本更新说明。
-
-### 智能体模板中心
-
-`admin/store.ts` 的 `getStoreApplicationList(query)` 查询智能体模板，直接返回
-`ApplicationStoreResponse`，不再返回 `unknown`。公共模板元数据为 `api/types/workflow-template.ts` 的 `WorkflowStoreTemplate`，
-智能体 `ApplicationStoreTemplate` 为其类型别名，响应结构仍由 `api/types/application.ts` 维护。
-类型统一经 `@/api/types` 导入；各资源业务入口整理响应字段，公共 UI 不调用接口。
-创建或覆盖工作流时通过已有智能体 API 提交 `work_flow_template`，成功后的刷新与导航由 View 负责。
-
-### 模型选项查询
-
-`model-provider.ts` 的 `getProviderList(query?)` 统一查询 `GET /provider`；不传参数获取全部供应商，
-传入 `{ model_type }` 筛选支持指定模型类型的供应商，不再单独封装按类型查询方法。
-
-`workspace/model.ts` 的 `getModelListWithShared(query)` 请求
-`/workspace/<workspaceId>/model_list`，支持 `name`、`model_type`、`model_name` 筛选。
-将 `shared_model` 与 `model` 按共享在前的顺序合并为 `ModelItem[]`，分别标记
-`source: 'shared'` 与 `source: 'workspace'`。`SelectModel` 的接口选项统一通过此方法查询，
-工作流通过 Store 同名方法使用缓存或强制刷新。模型管理列表继续使用 `getModelList`。
-
-`system/shared-resources/model.ts` 同样提供 `getModelListWithShared(query)`，沿用
-`/system/shared/model` 查询共享模型，为每项标记 `source: 'shared'`；不查询工作空间模型。
-共享工作流、代码生成和默认模型设置统一调用此方法，模型管理继续使用 `getModelList`。
-
-### 资源选择弹窗查询
-
-三个资源选择弹窗按 Workspace、System 资源管理和 System 共享资源选择接口，不配置
-Workspace 共享页面来源分支，不调用 Workspace Shared API。仅普通工作空间显示文件夹，不显示共享目录；其他范围不显示或查询文件夹。
-System 资源管理智能体提供 `getAllApplication`（`/system/resource/application`），System 共享
-不提供智能体选择。System 共享知识库提供 `getAllKnowledge`（`/system/shared/knowledge`），
-与 System 资源管理知识库的同名方法均直接返回全量列表。工具选择统一调用对应范围的
-`getAllTool`：System 资源管理请求 `/system/resource/tool`，System 共享请求 `/system/shared/tool`，
-返回 `ToolItem[]`，不附带工作空间文件夹筛选。`getToolListWithShared` 保留用于其他包含共享工具的选项查询。
-
-### 工具列表查询
-
-`workspace/tool/tool.ts` 的 `getAllTool(query)` 查询支持 `folder_id` 筛选的工作空间工具
-非分页列表，用于文件夹菜单和工具选择弹窗。`getToolListWithShared(query)` 请求 `tool/tool_list`，
-将响应的 `tools` 与 `shared_tools` 合并为 `ToolItem[]`，用于包含已授权共享工具的选项查询；
-按工具类型筛选时使用 `tool_type`。`workspace/shared/tool.ts` 的 `getAllTool(query)` 仅查询共享工具。
-
-### System 共享工具
-
-`system/shared-resources/tool/tool.ts` 使用 `/system/shared/tool`，维护分页、详情、创建、更新、删除、
-导入导出、连接测试、代码检查与调试、Skill 上传下载。路径沿用 v2 System 共享工具协议。
-共享工具 API 不提供工作空间文件夹移动或批量接口；复用卡片、Action 和表单接收完整 Workspace
-与 System 共享 API 的联合类型，不补造接口以匹配 Workspace 方法集合。
-
-### System 共享知识库
-
-`system/shared-resources/knowledge/knowledge.ts` 使用 `/system/shared/knowledge`，维护分页、详情、
-通用 / Web / 飞书 / 工作流创建、导入、删除、重新向量化、Web 同步、关联问题、分词索引、MCP
-配置与三种导出。工作流创建在 Workspace 与 System 共享范围均由同一个 Knowledge API 的
-`postKnowledgeWorkflow` 提交；工作流转换由各范围的 `knowledge.ts` 维护，
-`workspace/knowledge/workflow.ts` 仅维护已创建知识库的画布接口。System 共享范围没有工作空间文件夹、批量接口或独立的知识库工作流 API 文件。复用创建入口
-和卡片 Action 时使用完整 Workspace / System 资源管理 / System 共享知识库 API 的联合类型，由页面显式传入当前范围的 API。
-
-### 工具代码生成
-
-三个范围的 `tool/tool.ts` 均提供 `postToolGenerateCode(payload)`，沿用 v2 的
-`/workspace/<workspaceId>/tool/generate_code`、`/system/resource/tool/generate_code` 和
-`/system/shared/tool/generate_code`。无需工具或智能体 ID，创建中的工具也可生成代码。
-`ToolGenerateCodePayload`、`ToolGenerateMessage` 定义在 `types/tool.ts`；请求包含 `messages`、
-`prompt`、`init_field_list`、`input_field_list`、`model_id` 和 `model_params_setting`。
-返回原始 SSE Response，业务入口通过 `request(messages)` 回调交给 `GenerateContent`，
-公共组件复用 `ConversationStream` 读取数据，处理 `content` 和 `error` 数据块。
-停止生成与 AI 节点一致，通过 `ConversationStream.cancel()` 停止读取并清理流实例。
-工具表单组件 `ToolCodeGenerate` 内部通过资源上下文选择完整 Tool/Model API；
-调用方只传工具表单，不逐层传递 API、工作空间及参数列表。
-
-### 系统提示词生成
-
-Workspace、System 资源管理和 System 共享资源均把 `postPromptGenerate(modelId, payload)` 放在对应范围的
-`model.ts`，请求结构共用 `PromptGeneratePayload`（含 `model_params_setting`）。
-路径为 `/workspace/<workspaceId>/model/<modelId>/prompt_generate` 与 `/system/model/<modelId>/prompt_generate`，
-System 接口不依赖工作空间 ID。
-均返回原始 SSE Response，由公共生成组件读取。画布的 `PromptGenerate` 通过
-`useWorkflowStore(resourceScope).postPromptGenerate` 调用；三个范围的 Store 适配器分别引用对应的
-Model API，直接转发生成请求，不使用查询缓存或请求去重。
-
-### 知识库维护
-
-关联问题生成按资源归属提交：`putGenerateKnowledgeQuestions` PUT 到
-`/<knowledgeId>/generate_related`；`putGenerateDocumentQuestions` PUT 到
-`/<knowledgeId>/document/batch_generate_related`，单项也使用单元素 `document_id_list`。
-`RelatedQuestionsConfig` 共用模型、模型参数及提示词，`KnowledgeGeneratePayload` 增加
-`state_list`，`DocumentGeneratePayload` 再增加 `document_id_list`，类型从 `@/api/types` 导入。
-公共配置弹窗只返回表单与状态，各 Action 调用各自完整业务 API。
-
-`getKnowledgeMcpConfig(knowledgeId)` 与 `postKnowledgeKeywordIndex(knowledgeId)` 为预留接口方法，
-目前不发送 HTTP 请求：前者返回空配置文本，后者模拟成功。后续确认后端协议后替换方法内部实现。
-MCP 入口加载配置后打开只读及复制弹窗；分词索引入口仅调用方法并在成功后提示“操作成功”。
-
-`exportKnowledgeExcel`、`exportKnowledgeZip`、`exportKnowledge` 分别通过 GET 请求知识库
-`/<knowledgeId>/export`、`export_zip`、`export_knowledge`，复用 `getExportFile` 下载。
-三种结果分别为文档 Excel、包含图片的文档 ZIP 和可导入创建的知识库 ZIP；优先使用服务端文件名。
-
-`postKnowledgeImport(file, folderId)` 将文件与 `folder_id` 组装为 FormData，POST 到
-`/workspace/<workspaceId>/knowledge/import_knowledge`，响应为 `{ knowledge_id, type }`。
-后端校验知识库导出包并创建资源；导入成功后的用户权限和列表刷新由调用页面负责。
-
-`workspace/knowledge/knowledge.ts` 与 `workspace/shared/knowledge/knowledge.ts` 的 `getAllKnowledge(query)`
-分别查询工作空间及共享知识库的非分页列表，返回 `KnowledgeItem[]`，用于关联知识库选择等
-需要全量选项的场景。原有 `getKnowledgePage` 继续用于分页列表。
-
-`workspace/knowledge/knowledge.ts` 的 `putKnowledge` 更新普通知识库，`putLarkKnowledge`
-更新飞书知识库；单项转移提交 `folder_id`。`putBatchMoveKnowledge` 将知识库 ID 数组和目标目录
-组装为 `{ id_list, folder_id }`，`putBatchDeleteKnowledge` 将 ID 数组组装为 `{ id_list }`，
-分别使用 PUT 请求 `batch_move` 和 `batch_delete`。页面和 Action 负责类型判断及 loading。
-
-`putReEmbeddingKnowledge` 使用 PUT 请求 `/<knowledgeId>/embedding` 重新向量化。
-设置页更换向量模型时先确认、保存，再调用该接口；Web、飞书配置通过 `meta` 提交，保留未编辑的
-已有配置，文件数量与大小限制仍作为知识库顶层字段提交。
-
-`putSyncWebKnowledge(knowledgeId, syncType)` 使用 PUT 请求 `/<knowledgeId>/sync`，
-Workspace 与 System 资源管理接口的查询参数 `sync_type` 均支持 `incremental`（增量同步）、
-`replace`（替换同步）和 `complete`（整体同步），不传请求体。
-仅用于 Web 知识库；页面负责方式选择、覆盖提示、loading 与任务提交成功提示。
-
-知识库创建通过 `postKnowledge`、`postWebKnowledge` 分别提交到 `/base`、`/web`；
-`postLarkKnowledge` 沿用飞书扩展接口 `/lark/save`，当前开源后端未包含该实现。
-基础创建字段由 `KnowledgeCreatePayload` 统一维护，Web、飞书请求扩展对应类型；工作流创建
-复用基础字段并附加 `work_flow` 及可选的 `KnowledgeWorkflowTemplate` 商店模板。
-成功后的用户资料刷新、列表刷新和路由跳转由创建弹窗负责。
-
 ## 枚举与类型组织
 
 `enums/state.ts` 的 `STATE_TYPES` 维护跨业务复用的任务状态，联合类型 `State` 定义在
-`types/state.ts`。触发器及后续文件等业务直接引用公共状态，新增状态时保持已有接口值不变。
+`types/state.ts`。触发器及工具／知识库执行记录引用公共状态；文档任务使用 DOCUMENT_TASK_STATE，新增状态时保持已有接口值不变。
 
 API 枚举与类型统一在 `src/api` 范围内管理，相关规则由本文档统一维护。
 
@@ -298,7 +89,7 @@ API 枚举与类型统一在 `src/api` 范围内管理，相关规则由本文
 - API 专用的请求参数、响应包装、请求配置和基础设施类型，放在对应 API 文件、资源目录的
   `types.ts`，或该 API 业务域的 `common.ts`。
 - 字符串键字典统一使用 `@/api/types` 导出的 `Dict<T>`；未收窄值类型的请求查询参数使用
-  `Dict<unknown>`，不再为相同结构声明额外别名。
+  `Dict<unknown>`，不为相同结构声明额外别名。
 - `src/api/types` 只存放 API 与 View 或 Component 跨层共用的业务类型，使用方统一通过
   `import type { ... } from '@/api/types'` 导入，不写 `/index.ts`。
 - `src/api/types/index.ts` 只负责导出各业务域类型，不直接声明类型。
@@ -345,9 +136,8 @@ API 枚举与类型统一在 `src/api` 范围内管理，相关规则由本文
 - 业务代码通过 `api.method().then(...)` 处理接口成功后的状态变化；通用接口错误由请求层统一
   提示，不在调用处重复使用 `try/catch` 或 `.catch()` 提示相同错误。只有业务降级、状态恢复等
   非提示类失败处理可以按需保留失败分支。
-- token 和平台公开档案由 `stores/auth.ts` 管理，语言由 `stores/user.ts` 管理；Router、Axios 等业务代码通过
-  `stores/index.ts` 导出的 `useStore()` 按需访问 Store；401 响应统一清除 token 并跳转 Admin
-  登录页。
+- Admin token、公开档案和语言由 `stores/admin/` 管理；请求层使用该入口的 `useStore()`，401 清理凭据并跳转登录。
+  Chat 使用 `stores/chat/`，认证和重新认证见 [Chat README](chat/README.md)。
 - loading 不作为业务 API 或 Admin、Chat 底层请求封装的参数；JSON 请求、文件上传和下载均遵循此规则。
   由调用接口的页面、组件或 Store 在请求前开启 loading，并在 Promise 的 `finally` 中释放，确保成功和失败都恢复状态。
 - 流式 POST 请求使用 `postStream` 返回原始 `Response`，由业务组件按具体协议解析数据块；
@@ -355,6 +145,143 @@ API 枚举与类型统一在 `src/api` 范围内管理，相关规则由本文
   鉴权、语言请求头和错误状态仍由请求基础设施统一处理。
 - 上传、下载和其他特殊请求在真实需求出现时独立设计，不提前塞入普通 JSON 请求客户端。
 
+## 业务协议与范围差异
+
+以下只登记跨层协议、容易混淆的参数和真实能力差异；逐项函数签名以对应 API 源码及 JSDoc 为准。
+页面流程见 [VIEW_README.md](../views/VIEW_README.md)，共享组件用法见组件文档。
+
+### 门户配置
+
+`admin/system/chat-management/portal-setting.ts` 通过 Admin `/portal` 读取和局部保存门户配置，
+公共类型维护在 `types/portal.ts`。JSON 用于访问开关和认证、跨域配置，门户名称与 Logo 使用
+FormData；保存返回完整配置，页面以该返回值作为唯一数据来源。
+认证配置保留未编辑字段，仅提交后端读取的 `login_value`、`max_attempts`、`failed_attempts`、
+`lock_time`；跨域地址提交 `cross_domain_list` 数组，不另建 `cors_config`。
+
+### 当前账号密码
+
+`admin/auth/current-user.ts` 的 postCurrentUserPassword 向 `/user/current/reset_password`
+提交 RSA 加密的 `{ encryptedData }`；调用方校验与加密，成功清除凭据后进入登录。
+
+### 四类特殊资源 API
+
+根据资源范围或业务上下文选择出的 API 对象统一命名为 `requestApi`，包括 `computed` 结果和
+局部变量，不使用 `toolApi`、`authorizationApi` 或 `request` 等名称。同一作用域确需同时使用
+多套 API 时，以 `request` 为前缀加业务名区分，例如 `requestModelApi`、`requestToolApi`。
+知识库详情上下文的多模块接口入口使用 `resourceApi.knowledge / scheduledSync`，通过响应式 getter
+读取当前范围，无需 `.value`；方法内选定单个接口对象时仍命名为 `requestApi`。
+文档分段详情通过 `views/document-detail/context.ts` 装配四种范围的
+`resourceApi.document / paragraph`，保留完整 API 对象及真实方法差异，不补造共享写入方法。
+直接导入的 API 保持 PascalCase 命名；请求返回的 Promise 不属于此命名规则。
+
+`application`、`knowledge`、`model`、`tool` 是需要同时考虑 Workspace 普通资源、Workspace 共享资源、System 资源管理和
+System 共享资源的四类特殊资源。其接口按真实后端边界分别维护在 `admin/workspace/` 与
+`admin/system/` 下，不把不同范围的 URL 合并为页面侧 API Map，也不让卡片或 Action 根据路由拼接
+System 接口地址。
+
+页面根据路由 `resourceScope` 选择当前范围的完整业务 API 对象；知识库详情由功能本地
+`views/knowledge-detail/context.ts` 集中装配，由详情入口及 setting、library、对话用户子页复用该选择。缺失设置 API 模块保持未提供，
+不回退其他资源范围。页面将选定对象传给需要请求的 Card
+Action、Drawer 或 Dialog。复用方直接使用 `typeof XxxApi` 约束完整 API 对象；不要为每组 Action
+额外维护逐方法接口，例如 `ModelActionApi`，也不要使用不断扩展的 `Pick<typeof XxxApi, ...>`。
+完整 API 对象的方法集合不同时，共用组件使用完整对象类型的联合，例如
+`typeof ModelApi | typeof SystemSharedModelApi`，不为凑齐类型添加其他范围不存在的接口。
+仅展示数据的组件不接收 API。
+
+### 版本与模板
+
+智能体、工具、知识库 Workflow API 分别维护 application_version、tool_version、knowledge_version，
+使用同名 getWorkflowVersions／putWorkflowVersion，类型为 WorkflowVersion／WorkflowVersionPayload。
+前端版本标题上限 64、更新说明上限 1000，提交字段为 name、publish_desc，
+不将资源 desc 当作版本说明。智能体后端已支持 publish_desc；工具和知识库版本当前只处理 name。
+三个版本列表均未返回历史默认模型配置，预览与恢复保留当前配置。
+
+`admin/store.ts` 的 getStoreApplicationList、getStoreToolWorkflowList、getStoreKnowledgeList 查询三类模板，
+共用 WorkflowStoreTemplate 元数据，各响应类型保留本领域结构。工作流保存 work_flow 与覆盖 work_flow_template
+是互斥载荷；覆盖成功后重新查询详情，不把模板响应直接当图数据。知识库创建使用 Knowledge API，画布使用 Workflow API。
+
+### 模型选项查询
+
+`model-provider.ts` 的 `getProviderList(query?)` 统一查询 `GET /provider`；不传参数获取全部供应商，
+传入 `{ model_type }` 筛选支持指定模型类型的供应商，不单独封装按类型查询方法。
+
+`workspace/model.ts` 的 `getModelListWithShared(query)` 请求
+`/workspace/<workspaceId>/model_list`，支持 `name`、`model_type`、`model_name` 筛选。
+将 `shared_model` 与 `model` 按共享在前的顺序合并为 `ModelItem[]`，分别标记
+`source: 'shared'` 与 `source: 'workspace'`。`SelectModel` 的接口选项统一通过此方法查询，
+工作流通过 Store 同名方法使用缓存或强制刷新。模型管理列表继续使用 `getModelList`。
+
+`system/shared-resources/model.ts` 同样提供 `getModelListWithShared(query)`，沿用
+`/system/shared/model` 查询共享模型，为每项标记 `source: 'shared'`；不查询工作空间模型。
+共享工作流、代码生成和默认模型设置统一调用此方法，模型管理继续使用 `getModelList`。
+
+### 资源选择查询
+
+知识库／智能体／工具选择使用各范围的 getAllKnowledge、getAllApplication、getAllTool 全量查询。
+System 不传 Workspace 文件夹条件；System 共享不提供智能体选择。
+弹窗的范围和交互见 [组件文档](../components/COMPONENT_README.md#selectapplicationdialogselecttooldialog)。
+
+### 工具列表查询
+
+`workspace/tool/tool.ts` 的 `getAllTool(query)` 查询支持 `folder_id` 筛选的工作空间工具
+非分页列表，用于文件夹菜单和工具选择弹窗。`getToolListWithShared(query)` 请求 `tool/tool_list`，
+将响应的 `tools` 与 `shared_tools` 合并为 `ToolItem[]`，用于包含已授权共享工具的选项查询；
+按工具类型筛选时使用 `tool_type`。`workspace/shared/tool.ts` 的 `getAllTool(query)` 仅查询共享工具。
+
+### System 共享工具
+
+`system/shared-resources/tool/tool.ts` 使用 `/system/shared/tool`，维护分页、详情、创建、更新、删除、
+导入导出、连接测试、代码检查与调试、Skill 上传下载。路径沿用 v2 System 共享工具协议。
+共享工具 API 不提供工作空间文件夹移动或批量接口；复用卡片、Action 和表单接收完整 Workspace
+与 System 共享 API 的联合类型，不补造接口以匹配 Workspace 方法集合。
+
+### System 共享知识库
+
+`system/shared-resources/knowledge/knowledge.ts` 使用 `/system/shared/knowledge`，维护分页、详情、
+通用 / Web / 飞书 / 工作流创建、导入、删除、重新向量化、Web 同步、关联问题、分词索引、MCP
+配置与三种导出。工作流创建在 Workspace 与 System 共享范围均由同一个 Knowledge API 的
+`postKnowledgeWorkflow` 提交；工作流转换由各范围的 `knowledge.ts` 维护，
+`workspace/knowledge/workflow.ts` 仅维护已创建知识库的画布接口。System 共享范围没有工作空间文件夹、批量接口或独立的知识库工作流 API 文件。复用创建入口
+和卡片 Action 时使用完整 Workspace / System 资源管理 / System 共享知识库 API 的联合类型，由页面显式传入当前范围的 API。
+
+### 工具代码生成
+
+三套 `tool/tool.ts` 的 postToolGenerateCode 向各范围 `/tool/generate_code` 提交
+ToolGenerateCodePayload，无需已创建资源 ID。类型在 types/tool.ts，返回原始 SSE Response。
+流式消费与生成 UI 见 GenerateContent 组件，业务表单负责模型、参数和载荷。
+
+### 系统提示词生成
+
+Workspace、System 资源管理和 System 共享资源均把 `postPromptGenerate(modelId, payload)` 放在对应范围的
+`model.ts`，请求结构共用 `PromptGeneratePayload`（含 `model_params_setting`）。
+路径为 `/workspace/<workspaceId>/model/<modelId>/prompt_generate` 与 `/system/model/<modelId>/prompt_generate`，
+System 接口不依赖工作空间 ID。
+均返回原始 SSE Response，由公共生成组件读取。画布的 `PromptGenerate` 通过
+`useWorkflowStore(resourceScope).postPromptGenerate` 调用；三个范围的 Store 适配器分别引用对应的
+Model API，直接转发生成请求，不使用查询缓存或请求去重。
+
+### 知识库维护
+
+Workspace、System 资源管理、System 共享各自的 knowledge.ts 保留真实能力，Workspace 共享只查询。
+知识库生成问题 PUT `/<id>/generate_related`，配置为 RelatedQuestionsConfig + state_list；文档生成
+PUT `/<id>/document/batch_generate_related`，单项也传 document_id_list，不改成分段协议。
+
+getKnowledgeMcpConfig 查询 external_service 并格式化 mcp_config；putKnowledgeKeywordIndex PUT tokenize 提交索引。
+exportKnowledgeExcel、exportKnowledgeZip、exportKnowledge 下载文档 Excel、带图片文档 ZIP、可导入知识库 ZIP；
+postKnowledgeImport 以 FormData file、folder_id 上传，响应 knowledge_id、type。
+
+putKnowledge 更新通用字段，Workspace 飞书使用 putLarkKnowledge；移动传 folder_id，批量移动／删除传 id_list。
+更换向量模型保存后通过 putReEmbeddingKnowledge 提交 embedding。Web 同步的 sync_type 为 incremental／replace／complete，
+不自行改写协议值。Web doc_strategy 使用 DocumentStrategy，顶层详情可为 null，保存不立即同步。
+
+postTransformWorkflow POST `/<id>/transform_workflow`，提交 `{ work_flow }`，保留已有文档；不能用工作流保存接口代替。
+知识库 Workflow API 通过 getKnowledgeDetail 的 work_flow 加载，putKnowledgeWorkflow 保存，发布接口单独调用。
+默认模型协议使用 DefaultModelSettingPayload，知识库后端已保存 default_model_setting 并在详情回传。
+
+导入／导出工作流专用 `.kbwf`，接口为 workflow/import（FormData file）与 workflow/export，
+不能使用包含文档的知识库包接口。正式文档执行用 upload_document，调试用 debug，复用 KnowledgeWorkflowDebugPayload。
+知识库工作流 View 当前仍直接使用 Workspace Knowledge／Workflow API，其他来源仅有导航入口。
+
 ### 资源用户授权
 
 `admin/workspace/resource-authorization.ts` 按指定资源查询和更新用户权限，使用
@@ -378,9 +305,9 @@ System 资源管理的用户授权维护在 `admin/system/resource-management/re
 使用 `/system/workspace/<workspaceId>/resource_management/resource/<target>/resource/<resource>`。
 查询与保存方法以必填的 `workspaceId` 为首个参数，由调用方从资源数据的 `workspace_id` 传入，
 不得读取或回退到路由工作空间。其余参数、分页类型、响应类型及提交类型与 Workspace 用户授权一致。
-loading 由组件管理。`ResourceAuthorizationDrawer` 内部通过 `isSystemResource()` 选择完整的用户授权
-API 对象和工作空间上下文，作为该抽屉的范围选择例外；用户组仍使用
-现有 Workspace 接口，不推测 System 用户组路径。
+`ResourceAuthorizationDrawer` 内部通过 `isSystemResource()` 选择完整的用户授权
+API 对象和工作空间上下文，作为该抽屉的范围选择例外。System 用户组查询／保存已提供，路径在同前缀下为
+`user_group_resource/<target>/resource/<resource>`，两种授权均使用当前范围 API。
 
 ### 关联资源
 
@@ -397,90 +324,19 @@ API 对象和工作空间上下文，作为该抽屉的范围选择例外；用
 `/system/shared/mapping_resource`，方法只接收资源类型、资源 ID、分页和查询条件，不接收
 `workspaceId`。工作空间筛选继续通过 `query.workspace_ids` 传入；两类 API 使用相同参数签名，抽屉直接调用页面传入的完整 API。
 
-### 触发器维护
-
-`workspace/trigger/trigger.ts` 维护分页、详情、新建、编辑、删除及批量接口。
-`getTriggerTaskRecordPage` 按触发器查询执行记录，支持名称、状态、资源类型和执行时间排序；
-`getTriggerTaskRecordDetails` 通过触发器、任务、记录 ID 查询执行详情，类型定义在 `api/types/trigger.ts`。
-`putBatchActivateTrigger(ids, isActive)` 提交 `{ id_list, is_active }` 到 `batch_activate`；
-`putBatchDeleteTrigger(ids)` 提交 `{ id_list }` 到 `batch_delete`。单项启停通过 `putTrigger`
-仅提交 `is_active`。`Trigger` 为分页摘要，`TriggerDetail` 为含任务参数的完整详情；
-`TriggerPayload` 用于新建和编辑，ID 在新建前生成以展示事件回调 URL。
-
-### 资源触发器
-
-`workspace/trigger/resource-trigger.ts` 独立维护工具、智能体资源端的触发器列表、详情、新建、编辑和移除。
-接口前缀为 `/workspace/<workspaceId>/<sourceType>/<sourceId>/trigger`，资源类型使用
-`RESOURCE_TYPE.TOOL` / `RESOURCE_TYPE.APPLICATION` 的后端值；工作空间从资源上下文显式传入。
-`ResourceTriggerResource`、`ResourceTrigger`、`ResourceTriggerDetail` 定义在 `types/trigger.ts`。
-详情的 `trigger_task` 是单对象，普通触发器详情是数组，调用表单负责统一结构。
-新建提交含一个固定任务的 `TriggerPayload`；资源编辑只更新当前资源任务的参数和 meta，保留其他任务，
-名称和周期等配置仍属于整个触发器。移除删除当前资源任务，最后一个任务移除后删除触发器。
-列表沿用后端仅返回已启用触发器的行为，loading 由调用组件维护。
-
-### 知识库工作流
-
-`workspace/knowledge/knowledge.ts` 的 `getKnowledgeDetail` 返回 `KnowledgeDetail`，包含知识库
-名称、所属目录，以及工作流类型的 `work_flow` 和发布状态；进入画布只调用此详情接口加载。
-`workspace/knowledge/workflow.ts` 维护保存和发布，保存提交 `work_flow`，响应使用
-`KnowledgeWorkflowDetail`。前端详情与保存协议的 `default_model_setting` 复用
-`DefaultModelSettingPayload`；服务端需支持该字段的持久化与回传（当前仓库知识库后端尚未实现）。
-
-`postKnowledgeWorkflowImport(knowledgeId, payload)` 使用 POST `/<knowledgeId>/upload_document`
-执行已发布版本的文档导入，参数复用 `KnowledgeWorkflowDebugPayload`，结果为
-`KnowledgeWorkflowAction`；调试仍调用独立的 `/debug`。文档页导入 Drawer 复用工作流的
-数据源、知识库输入及结果 Action，执行详情沿用 `getKnowledgeWorkflowAction`。
-
-### 智能体复制
-
-`ApplicationDetail` 复用 `ApplicationFormPayload` 中的配置字段，并保留详情接口的 `model`
-和可空描述。复制通过 `getApplicationDetail` 获取完整配置，将 `model` 映射为 `model_id`，
-再调用 `postApplication` 创建副本；不使用卡片列表摘要作为复制数据。
-
-### 工具执行记录
-
-`workspace/tool/workflow.ts` 的 `getToolExecutionRecordPage` 查询 `/<toolId>/tool_record/<currentPage>/<pageSize>`，
-支持 `source_name`、`source_type`、`state` 筛选，后端固定按创建时间倒序返回。
-`getToolExecutionRecordDetail` 查询 `/<toolId>/tool_record/<recordId>`，返回状态、耗时和 `meta` 中的输入、输出、
-错误及节点详情。共用类型 `ToolExecutionRecord`、`ToolExecutionRecordDetail` 维护在 `types/tool.ts`；
-调用来源使用 `TOOL_RECORD_SOURCE`。抽屉负责 loading 和分页状态，不重复解包响应。
-
-### 知识库执行记录
-
-`workspace/knowledge/workflow.ts` 集中维护工作流、发布版本和执行记录接口。
-`getKnowledgeExecutionRecordPage` 请求 `/<knowledgeId>/action/<currentPage>/<pageSize>`，
-支持 `user_name`、`state` 筛选；详情和取消复用 `getKnowledgeWorkflowAction`、
-`postCancelKnowledgeWorkflowAction`，对应 GET `action/<actionId>` 和 POST `action/<actionId>/cancel`。
-`KnowledgeExecutionRecord` 为分页摘要，`KnowledgeWorkflowAction` 扩展节点详情；均从 `@/api/types` 导入。
-
-### 工具工作流调试
-
-`workspace/tool/workflow.ts` 的 `postToolWorkflowDebug(toolId, parameters)` 使用 Admin `postStream`
-请求 `/<toolId>/debug`，返回原始 SSE Response；输入参数来自工具基础节点，`chat_record_id` 用于识别
-执行记录，表单续跑沿用该 ID 并传入 `position`。调试结果与执行详情统一通过
-`getToolExecutionRecordDetail(toolId, recordId)` 查询 `/<toolId>/tool_record/<recordId>`，
-返回 `ToolExecutionRecordDetail` 的运行状态、输出及节点详情。Workspace、System 资源管理和
-System 共享资源分别保留各自路径下的同名接口，不再重复封装调试专用查询。
-工具调试读取服务端已保存工作流，画布页面在调试前保存未提交改动。
-
-### 工具工作流模板中心
-
-`admin/store.ts` 的 `getStoreToolWorkflowList(query)` 查询 `/workspace/store/tool_workflow_template`，
-返回 `ToolWorkflowStoreResponse`，其中 `apps` 复用 `WorkflowStoreTemplate[]`。
-`workspace/tool/workflow.ts` 的 `putToolWorkflow` 支持两种互斥载荷：保存 `work_flow` 与默认模型设置，
-或提交 `work_flow_template` 由服务端下载并覆盖当前工具工作流。模板覆盖后由 View 重新查询详情，
-同步默认模型设置、保存时间和图快照；确认取消或请求失败不关闭模板中心。
-
-### 知识库工作流模板与导入导出
-
-`admin/store.ts` 的 `getStoreKnowledgeList(query)` 查询 `/workspace/store/knowledge_template`，
-返回 `KnowledgeWorkflowStoreResponse`，其中 `apps` 使用公共 `WorkflowStoreTemplate[]`。
-`putKnowledgeWorkflow` 接受互斥的 `work_flow` 保存载荷或 `work_flow_template` 覆盖载荷，覆盖成功后由 View 重载详情。
-`exportKnowledgeWorkflow(knowledgeId, name)` 通过 GET `/<knowledgeId>/workflow/export` 下载 `.kbwf` 文件，
-只导出工作流，不调用包含文档的知识库包导出接口。
-`importKnowledgeWorkflow(knowledgeId, file)` 沿用 v2 的 POST `/<knowledgeId>/workflow/import`，
-使用 FormData 的 `file` 字段上传 `.kbwf`，由服务端覆盖草稿、处理关联工具与默认模型设置。
-接口结果不作为图数据使用，页面确认覆盖后调用，成功重新查询知识库详情并渲染画布。
+### 触发器与执行记录
+
+- `workspace/trigger/trigger.ts` 提供普通触发器维护、记录分页与详情，Trigger 为摘要，TriggerDetail 含完整任务，
+  TriggerPayload 新建前生成 ID。批量启停传 `{ id_list, is_active }`，批量删除传 `{ id_list }`，单项启停仅提交 is_active。
+- `workspace/trigger/resource-trigger.ts` 前缀为 `/workspace/<workspaceId>/<sourceType>/<sourceId>/trigger`，
+  workspaceId 从资源显式传入，sourceType 使用 RESOURCE_TYPE。资源详情 trigger_task 是对象，普通详情为数组。
+  资源编辑保留其他任务，移除仅删除当前关联，最后任务移除后删除触发器；列表只返回启用触发器。
+- 工具 Workflow API 记录为 `/<toolId>/tool_record/<page>/<size>` 及 `/<recordId>`，
+  查询 source_name、source_type、state，返回 ToolExecutionRecord／ToolExecutionRecordDetail，按创建时间倒序。
+  调试 POST debug 返回 SSE，chat_record_id 与 position 用于续跑，详情复用记录接口，不重复封装调试查询。
+- 知识库 Workflow API 记录为 `/<id>/action/<page>/<size>`，筛选 user_name、state；
+  详情和取消为 GET action/<actionId>、POST action/<actionId>/cancel。
+- 智能体复制查询完整 ApplicationDetail，model 映射 model_id 后创建，不使用卡片摘要。
 
 ### 工作空间首页
 
@@ -497,20 +353,11 @@ System 首页的智能体选项使用 `system/resource-management/application/ap
 工作空间筛选通过 `query.workspace_ids` 传入所选工作空间 ID 的 JSON 数组字符串；名称筛选使用 `name`。
 Workspace 智能体分页方法只接收分页与查询条件，从当前资源上下文读取工作空间。
 
-### 对话面板接口
-
-`admin/workspace/conversation.ts` 集中维护调试对话的打开、发送、取消、续传、历史会话、
-记录分页、删除、修改和语音识别接口，保留可选 `applicationId` 对历史资源范围的选择。
-其中 `postSpeechToText(applicationId, data)` 请求指定智能体的
-`/workspace/<workspaceId>/application/<applicationId>/speech_to_text`，loading 由调用方管理。
-`chat/conversation.ts` 维护正式对话对应的 v3 接口，路径为 `/v3/application/<applicationId>/...`，除取消生成外均以
-`applicationId` 为首个参数；chat 模式的 `createChatConversation(getApplicationId)` 由使用方提供当前智能体 ID。两者使用各自 `core/request.ts` 的请求方法；
-`postStream` 返回原始 `Response`，由 `conversation-panel/stream.ts` 解析。
+### 对话接口
 
-面板内部的 `conversation-panel/common/get-api.ts` 通过 `ChatType` 选择完整 API 对象，
-仅负责模式判断，不声明 URL 或发送请求；固定模式的 Store 直接导入对应业务 API。
-面板模式值统一维护在 `conversation-panel/common/enums.ts` 的 `CHAT_TYPE`，
-`common/types.ts` 中的 `ChatType` 从该对象派生。
+Admin 调试接口在 `admin/workspace/conversation.ts`，正式 Chat 接口在 `chat/conversation.ts`，
+使用各自请求客户端。面板 `common/get-api.ts` 仅按 ChatType 选择完整 API，不拼 URL。
+Chat 协议及认证接口见 [chat/README.md](chat/README.md)。
 
 ### 通用文件上传
 
@@ -554,10 +401,9 @@ System 接口由资源管理服务提供；本地开源后端没有对应扩展
 
 ### System 共享工具工作流
 
-`system/shared-resources/tool/tool-workflow.ts` 维护共享工具的工作流详情、保存、发布、调试、
-版本和执行记录，前缀为 `/system/shared/tool`，调用只传资源 ID，不读取工作空间。
-两种 System 工具 API 的 `getToolListWithShared` 查询各自 `/tool_list` 并合并 `tools`、`shared_tools`，
-供画布的工具菜单及 MCP 选项使用。系统扩展接口需连接支持相应协议的部署进行联调。
+`system/shared-resources/tool/tool-workflow.ts` 提供详情、保存、发布、调试、版本和执行记录，
+前缀 `/system/shared/tool`，只接收资源 ID。两种 System 工具的 getToolListWithShared 查询各自
+`/tool_list`，合并 tools／shared_tools；需相应部署支持扩展协议。
 
 ### 知识库工作流转换
 
@@ -569,170 +415,86 @@ Workspace、System 资源管理及 System 共享资源的 `knowledge.ts` 提供
 保留已有文档，已是工作流类型时拒绝重复转换。页面负责确认、loading、成功提示及进入画布。
 默认图复用知识库创建模板，不用保存工作流接口代替转换。
 
-### 知识库文档
-
-`workspace/knowledge/document.ts` 的 `getDocumentDetail(knowledgeId, documentId)` 通过 GET
-`/<knowledgeId>/document/<documentId>` 查询文档详情，支持分段页刷新和直接访问。
-`workspace/knowledge/paragraph.ts` 维护普通 Workspace 文档分段接口，前缀为
-`/workspace/<workspaceId>/knowledge/<knowledgeId>/document/<documentId>/paragraph`。
-`getParagraphList` 查询完整分段列表，供位置调整定位相邻分段；
-`getParagraphPage(knowledgeId, documentId, page, query?)` 查询 `/<currentPage>/<pageSize>`，
-返回 `ResponsePage<ParagraphItem>`，供分段详情滚动加载。两者均支持 `title`、`content`，
-服务端按 `position`、创建时间排序；
-`postParagraph` 提交 `title`、`content`、`is_active` 和可选的 `problem_list: [{ content }]`，
-返回新增分段详情，默认插入首位并触发索引。
-新增载荷可传 `position`，在目标位置插入，用于当前分段上方添加。
-`getParagraphDetail` 查询 `/<paragraphId>`，返回 `ParagraphDetail`，包含 `problem_list`、
-`hit_num` 和 `last_hit_time`。`putParagraph` 向同一路径提交标题和正文，直接返回最新详情对象；
-后端内部三元素返回值经后置处理转换为详情对象，不作为数组解析。不提交 `problem_list`，关联关系通过专属接口维护。
-编辑载荷使用 `ParagraphEditPayload`，允许仅传 `is_active` 更新启用状态，正文表单仍使用
-必填标题及正文的 `ParagraphUpdatePayload`。`deleteParagraph` DELETE `/<paragraphId>` 删除单个分段。
-`putParagraphPosition` PUT `/adjust_position`，查询参数为 `paragraph_id`、`new_position`，
-不传请求体，由服务端调整当前分段及受影响分段的位置。
-`postParagraphProblem` 向 `/<paragraphId>/problem` 提交 `{ content }`，创建或复用问题并关联分段；
-`getParagraphProblems` GET 同一路径，返回当前分段的 `ParagraphProblem[]`，用于关联变更后刷新。
-`putAssociateParagraphProblem` PUT 到 `/association`，通过查询参数传递 `paragraph_id`、`problem_id`，
-不传请求体，用于关联已存在的问题。
-`putUnassociateParagraphProblem` PUT 到 `/unassociation`，以查询参数传递 `paragraph_id`、
-`problem_id`，不传请求体，仅解除当前分段的关联。
-`workspace/knowledge/problem.ts` 的 `getProblemsPage(knowledgeId, page, query?)` 查询知识库问题分页，
-路径为 `/workspace/<workspaceId>/knowledge/<knowledgeId>/problem/<currentPage>/<pageSize>`，
-支持 `content` 搜索，返回 `ResponsePage<ParagraphProblem>`。分段添加问题沿用 v2 查询第一页 100 条候选。
-`putMigrateParagraphs` 向分段前缀下的 `/migrate/knowledge/<targetKnowledgeId>/document/<targetDocumentId>`
-提交 PUT `{ id_list }`，将所选分段迁移到目标文档；目标不能为当前文档。
-`putGenerateParagraphQuestions` 向分段前缀下的 `/batch_generate_related` 提交 PUT
-`ParagraphGeneratePayload`，包含生成配置与 `paragraph_id_list`，不包含 `state_list`。
-`putBatchDeleteParagraphs` 向分段前缀下的 `/batch_delete` 提交 PUT `{ id_list }`，
-删除所选分段并由服务端清理关联问题、映射及索引。
-响应及载荷类型维护在 `types/paragraph.ts`，通过 `@/api/types` 导入。
-标题最多 256 字符，内容必填且最多 102400 字符；loading、弹窗和成功后刷新由页面维护。
-本次只接入普通 Workspace，不为其他范围推测接口或回退 Workspace。
-
-文档地址及飞书导入也维护在 `workspace/knowledge/document.ts`：
-`postWebDocument` 向 `/<knowledgeId>/document/web` 提交 `WebDocumentImportPayload`，包含
-`source_url_list`、`selector` 与 `doc_strategy`。
-`getLarkDocumentList` 沿用 POST `/lark/<knowledgeId>/<folderToken>/doc_list`，支持 `page_token`，
-返回 `LarkDocumentList` 的 `files`、`has_more` 和 `next_page_token`。
-`postImportLarkDocuments` 沿用 POST `/lark/<knowledgeId>/import` 的文档数组协议，
-每项为 `LarkDocumentImportPayload`（名称、token、类型及处理策略）。飞书接口属于扩展端；
-当前仓库未包含 v3 实现，`doc_strategy` 的持久化与执行需要扩展端支持，不能视为已联调。
-上述跨 API 与 UI 的类型统一通过 `@/api/types` 导出。
-
-文档上传复用 `workspace/knowledge/document.ts`：`postSplitDocuments` 向 `document/split`
-发送多文件 FormData（重复 `file` 字段）与 JSON 字符串 `doc_strategy`，返回 `DocumentSplitResult[]`；
-页面将解析结果的 `content` 转为 `paragraphs`，保留 `source_file_id` 与策略，再通过
-`putBatchCreateDocuments` PUT `document/batch_create` 创建文档，与空白文档创建共用同一接口封装。
-策略页直接导入使用 `postImportTextDocuments` POST `document/import`，提交 JSON
-`{ file_id_list, doc_strategy }`，复用上传成功后的文件 ID，由服务端解析并创建，返回 `DocumentItem[]`；
-不再次上传文件，也不先请求 `split`。
-`postImportTableDocumentsByFileIds` 和 `postImportQADocumentsByFileIds` 分别向
-`document/table_by_file_ids` 和 `document/qa_by_file_ids` 发送 `DocumentFileImportPayload`
-（`{ file_id_list: string[] }`），复用上传成功后的文件 ID，由服务端解析并创建，不再次上传文件。
-`exportTableDocumentTemplate` 和 `exportQADocumentTemplate` 分别使用 GET
-`/workspace/knowledge/document/table_template/export` 和 `/workspace/knowledge/document/template/export`，查询参数 `type` 为
-`excel` / `csv`。上传解析与创建类型维护在 `types/document.ts`，统一通过 `@/api/types` 导入。
-共享文档 API 不提供上传写入方法。
-
-`putDocument(knowledgeId, documentId, data)` 统一通过 PUT `/<documentId>` 更新名称、启用状态和单项设置，
-不按更新字段重复封装同一接口。载荷 `DocumentUpdatePayload` 仅包含可更新字段，按需传入
-`name`、`is_active`、`hit_handling_method`、`directly_return_similarity`、`meta`，返回更新后的
-`DocumentItem`。名称上限 128 字符；共享文档仍只提供查询。
-
-`workspace/knowledge/document.ts` 同时维护文档启停、删除、召回设置、向量化、分词索引、
-任务取消、生成问题、迁移、同步、导出、原文件下载/替换。
-批量任务沿用 v2 的 `id_list` / `state_list`；生成问题使用 `document_id_list`，
-添加标签使用 `document_ids` / `tag_ids`，迁移和批量导出直接提交文档 ID 数组。
-文档导出分别提供四个接口，不以单元素批量请求代替单项接口：
-`exportDocument`、`exportDocumentZip` 使用 GET 请求 `/<documentId>/export`、`/<documentId>/export_zip`；
-`exportMulDocument`、`exportMulDocumentZip` 使用 POST 请求 `batch_export`、`batch_export_zip`，请求体直接为 ID 数组。
-单项参数为知识库 ID、文档 ID、文档名称；批量参数为知识库 ID、文档 ID 数组、知识库名称。
-服务端未提供文件名时，分别以文档名称或知识库名称加 `.xlsx` / `.zip` 回退，沿用 v2 下载命名。
-向量化、生成问题默认排除成功分段，也可选择全部分段。任务类型使用 `DOCUMENT_TASK_TYPE`。
-单项向量化使用 `putDocumentRefresh(knowledgeId, documentId, stateList)` 请求 `/<documentId>/refresh`；
-单项取消使用 `putCancelTask(knowledgeId, documentId, taskType)` 请求 `/<documentId>/cancel_task`，提交 `{ type }`。
-批量向量化与取消分别沿用 `batch_refresh` 和 `batch_cancel_task`，不以单元素批量请求代替单项接口。
-单项分词使用 `putDocumentTokenize(knowledgeId, documentId, stateList)` 请求 `/<documentId>/tokenize`，
-提交 `{ state_list }`；批量分词使用 `putBatchTokenizeDocuments` 请求 `batch_tokenize`，
-提交 `{ id_list, state_list }`。两者均包含全部七种分段状态；单项取消分词复用 `putCancelTask`，任务类型为 `TOKENIZE`。
-文档设置的共享载荷为 `DocumentSettingPayload`，生成问题使用 `DocumentGeneratePayload`；
-单项设置通过 `meta` 保留来源数据，批量设置将 `allow_download` 放在顶层。
-文档同步区分单项和批量，不以单元素批量请求代替单项接口：
-`putDocumentSync` 请求 `/<knowledgeId>/document/<documentId>/sync`，
-`putMulSyncDocument` 请求 `/<knowledgeId>/document/batch_sync`；
-`putLarkDocumentSync` 请求 `/lark/<knowledgeId>/document/<documentId>/sync`，
-`putMulLarkSyncDocument` 请求 `/lark/<knowledgeId>/_batch`。上述路径均相对工作空间的 `knowledge` 前缀，
-全部使用 PUT；单项不传请求体，批量提交 `{ id_list }`。飞书接口需部署环境支持。
-共享文档 API 继续仅提供查询，不增加写入方法。
-
-`system/resource-management/knowledge/document.ts` 与 `system/shared-resources/knowledge/document.ts`
-提供与 `workspace/knowledge/document.ts` 相同的完整文档接口集合，方法名、参数、请求体和返回类型保持一致。
-普通文档前缀分别为 `/system/resource/knowledge/<knowledgeId>/document` 和
-`/system/shared/knowledge/<knowledgeId>/document`，不读取工作空间 ID。
-飞书接口在各自的知识库资源前缀后追加 `/lark/<knowledgeId>`；模板下载使用各自前缀下的
-`/document/table_template/export` 和 `/document/template/export`，不包含知识库 ID。
-系统路径组织沿用 v2，新增的 v3 文件 ID 导入和策略协议需对应部署环境支持，尚未联调。
-文档标签关联接口统一维护在各范围的 `tags.ts`。四套现有 Document API 由知识库详情 context 按范围装配。
-
-`workspace/knowledge/document.ts` 维护文档分页查询，路径为
-`/workspace/<workspaceId>/knowledge/<knowledgeId>/document/<currentPage>/<pageSize>`。
-`putBatchCreateDocuments(knowledgeId, documents)` 统一通过 PUT `document/batch_create` 批量创建文档，
-空白创建提交 `DocumentQuickCreatePayload[]`（仅含 `name`），解析后创建提交 `DocumentImportPayload[]`，
-返回 `DocumentItem[]`；名称上限 128 字符。不按创建场景重复封装同一接口。
-共享文档 API 不增加创建接口；文档页监听公共 MkQuickCreate 的 `create` 事件，管理创建请求和提交状态。
-分页使用 `ParamsPage` / `ResponsePage<DocumentItem>`，支持 `name`、`create_user`、`status`、`task_type`、`is_active`、`hit_handling_method` 和 `tags` 筛选；
-文件任务使用 `DOCUMENT_TASK_STATE` 的字符状态及 `DOCUMENT_TASK_TYPE` 的任务位置，
-不使用通用 `STATE_TYPES`；选择全部时省略状态与任务类型，非任务专属状态省略任务类型。
-文件状态响应还包含 `REVOKE: '4'`、`REVOKED: '5'`、`IGNORED: 'n'`。
-`DocumentItem.status_meta` 使用可空的 `DocumentStatusMeta`：`aggs` 为 `{ status, count }[]`，
-`state_time` 按任务编号、状态字符两级索引时间字符串；两项均可缺省。
-无分段时聚合项的 `status` 可为 `null`，按忽略状态解析，不计入成功数量。
-`DocumentTaskState` 和 `DocumentTaskType` 从文档枚举派生，统一从 `@/api/types` 导入。
-启用状态传布尔值，`false` 不省略；单选全部时省略该字段。`tags` 传数组，沿用 Axios 的
-`tags[]` 序列化，内容为标签 ID 或特殊值 `NO_TAG`，不传标签名称或 JSON 字符串。
-`workspace/knowledge/tags.ts` 和 `workspace/shared/knowledge/tags.ts` 的
-`getKnowledgeTags(knowledgeId)` 分别请求对应资源前缀的 `/<knowledgeId>/tags`，返回
-`KnowledgeTagGroup[]`；页面将分组转换为级联选项，MkTableFilter 内部展开父组并去重，页面直接用组件返回的叶子标签 ID 数组查询。
-文档页传 `resource_type: 'document'`，创建者选项复用 Workspace `common.ts` 的 `getAllUsers`。
-类型从 `@/api/types` 导入，命中处理枚举从 `@/api/enums` 导入。API 不接收 loading，不重复包装响应。
-
-### 知识库标签与文档关联
-
-`workspace/knowledge/tags.ts` 维护标签查询、创建、编辑和删除，前缀为
-`/workspace/<workspaceId>/knowledge/<knowledgeId>/tags`，工作空间由 `getWorkspaceId()` 读取。
-`getKnowledgeTags(knowledgeId, query?)` 返回非分页 `KnowledgeTagGroup[]`；
-可选 `query.name` 用于标签管理列表搜索，不传时仍查询全部标签供下拉候选使用。
-标签值中的可选 `doc_count` 表示关联文档数量。`postKnowledgeTags` 直接提交
-`KnowledgeTagPayload[]`（`key`、`value`），用于创建标签和新增标签值；
-`putKnowledgeTag` 向 `/<tagId>` 提交完整 `KnowledgeTagUpdatePayload`（`id`、`key`、`value`），
-路径 `tagId` 与载荷 `id` 保持一致。重命名提交新 `key` 与该行原 `value`，服务端更新当前标签所属同名组；
-编辑单个值提交原 `key` 与新 `value`，保留同组重复值校验，不提交其他行的值。
-`deleteKnowledgeTag` 按路径末尾 `key` 删除整个标签、`one` 删除单个标签值；
-`putBatchDeleteKnowledgeTags` 使用 PUT `batch_delete`，请求体直接为标签 ID 数组，不包装为 `id_list`。
-`postImportKnowledgeTags(knowledgeId, file)` POST 到 `import`，使用 FormData 的单个 `file` 字段上传 XLS 或 XLSX，
-响应解包为 `void`。文件第一行为“标签、标签值”，每行对应一个标签与值；同名标签可重复出现，
-服务端跳过文件内及知识库已有的重复组合，校验所有工作表后统一写入。空行跳过，标签与值分别限制为 64、128 字。
-`exportKnowledgeTagTemplate(knowledgeId)` GET 到 `template/export`，复用 `getExportFile` 下载“标签模板.xlsx”，
-服务端返回与提供的模板一致的表头和示例数据。两个接口均校验目标知识库的工作空间及标签创建权限。
-标签类型统一维护在 `types/knowledge.ts`。创建支持多行，编辑仅支持重命名或单个值修改，
-不声明多行编辑接口，也不组合旧接口模拟多行保存。
-
-`system/resource-management/knowledge/tags.ts` 与 `system/shared-resources/knowledge/tags.ts`
-提供与普通 Workspace 相同的七个标签接口及四个文档标签关联接口，参数、请求体和返回类型保持一致。
-公共前缀分别为 `/system/resource/knowledge/<knowledgeId>` 和 `/system/shared/knowledge/<knowledgeId>`，
-不读取工作空间 ID；各接口追加对应的 `tags`、`document` 或 `tag` 路径。
-具体接口需部署环境支持。四套现有标签 API 由知识库详情 context 按范围装配；
-Workspace 共享标签 API 保持现有只读查询，不补写入方法。
-
-文档与标签的关联由 `workspace/knowledge/tags.ts` 维护，不使用标签删除接口代替取消关联。
-该模块公共前缀为知识库路径，各接口按后端协议追加 `tags`、`document` 或 `tag`，不因文件归属改变请求地址。
-`getDocumentTags(knowledgeId, documentId, query?)` 查询 `document/<documentId>/tags`，返回分组标签，支持 `query.name` 搜索；
-`postBatchAddDocumentTags` POST 到 `document/batch_add_tag`，提交 `{ document_ids, tag_ids }`；
-`putDeleteDocumentTags` PUT 到 `document/<documentId>/tags/batch_delete`，直接提交标签 ID 数组。
-`putUnlinkTagDocuments` PUT 到知识库下的 `tag/<tagId>/docs_delete`，提交 `{ id_list: documentIds }`，
-用于取消同一标签与单个或多个文档的关联。
-关联文档列表复用 `getDocumentPage`，传 `resource_type: 'document'`、`tags: [tagId]`，
-未关联列表另传 `tag_exclude: true`；标签数组沿用请求层的 `tags[]` 序列化。
-名称使用 `name`；关联文档抽屉不传 `order_by`，按接口默认顺序展示。
+### 文档与分段
+
+四范围 document.ts、paragraph.ts 的对象由详情上下文装配。Workspace 与 System 两种范围提供完整维护，
+Workspace 共享只提供已有查询，不添加写方法或回退其他来源。
+
+| 范围            | 知识库资源前缀                                     |
+| --------------- | -------------------------------------------------- |
+| Workspace       | `/workspace/<workspaceId>/knowledge`               |
+| Workspace 共享  | `/system/shared/workspace/<workspaceId>/knowledge` |
+| System 资源管理 | `/system/resource/knowledge`                       |
+| System 共享     | `/system/shared/knowledge`                         |
+
+文档接口在前缀后追加 `/<knowledgeId>/document`，分段再追加 `/<documentId>/paragraph`。
+System 不读取 workspaceId；飞书在知识库前缀追加 lark/<knowledgeId>，模板下载不带知识库 ID。
+System／飞书扩展及文件 ID 导入、策略协议需对应部署支持，不能因前端接口存在认定已联调。
+
+文档分页使用 ParamsPage／ResponsePage<DocumentItem>，名称／创建者／任务／启用／命中／标签筛选支持组合。
+is_active 为 false 时保留，“全部”省略；tags 传叶子 ID 数组或 NO_TAG，按 tags[] 序列化。
+状态使用 DOCUMENT_TASK_STATE 与 DOCUMENT_TASK_TYPE，不用通用 STATE_TYPES；非任务状态省略 task_type。
+status_meta 可空，aggs 为 `{ status, count }[]`，state_time 按任务和状态索引；null 聚合状态按忽略处理。
+
+putDocument 统一更新名称、启停及设置，不按字段重复封装；名称最多 128。
+单项设置 meta 保留来源，批量 allow_download 在顶层。任务载荷通常用 id_list／state_list，
+生成用 document_id_list，标签用 document_ids／tag_ids，迁移及批量导出直接传 ID 数组。
+
+| 操作         | 协议差异                                                                                               |
+| ------------ | ------------------------------------------------------------------------------------------------------ |
+| 创建         | PUT batch_create；空白名称与解析后内容使用同一方法，返回 DocumentItem[]                                |
+| 文本预览     | POST split，多文件 FormData 重复 file 字段，doc_strategy 为 JSON 字符串；响应 content 转为 paragraphs  |
+| 文本直接导入 | POST import，JSON `{ file_id_list, doc_strategy }`，服务端解析并创建，不先 split 或再次上传            |
+| 表格／QA     | POST table_by_file_ids／qa_by_file_ids，提交 `{ file_id_list }`，模板 GET 支持 excel／csv              |
+| Web          | POST web，提交 source_url_list、selector、doc_strategy                                                 |
+| 飞书         | POST lark/<id>/<folderToken>/doc_list，读取 files／has_more／next_page_token；import 提交文档数组      |
+| 向量化       | 单项 PUT <documentId>/refresh，批量 batch_refresh；state_list 可选全部或排除成功                       |
+| 分词         | 单项 PUT <documentId>/tokenize，批量 batch_tokenize，全部七种状态                                      |
+| 取消任务     | 单项 PUT <documentId>/cancel_task，提交 `{ type }`；批量 batch_cancel_task                             |
+| 同步         | 单项 <documentId>/sync 不传体，批量 batch_sync 传 `{ id_list }`；飞书批量 lark/<id>/\_batch，均 PUT    |
+| 导出         | 单项 GET <documentId>/export 或 export_zip；批量 POST batch_export 或 batch_export_zip，直接传 ID 数组 |
+
+除文档生成问题的批量协议外，不以单元素批量接口代替单项。导出文件名优先服务端，
+缺失时单项使用文档名、批量使用知识库名加 xlsx／zip。
+
+分段协议类型在 types/paragraph.ts，分页支持 title、content，后端按 position 和创建时间排列。
+
+| 方法                                                         | 协议                                                                                      |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| postParagraph                                                | title、content、is_active、可选 problem_list；position 指定插入，默认首位                 |
+| getParagraphDetail／putParagraph                             | 返回 ParagraphDetail 对象，不按数组解析；正文更新不提交 problem_list，启停仅传 is_active  |
+| putParagraphPosition                                         | PUT adjust_position，query paragraph_id、new_position，无请求体                           |
+| postParagraphProblem／getParagraphProblems                   | <paragraphId>/problem，提交 content 或读取已关联问题                                      |
+| putAssociateParagraphProblem／putUnassociateParagraphProblem | association／unassociation，query paragraph_id、problem_id，仅改变关联                    |
+| putMigrateParagraphs                                         | PUT migrate/knowledge/<targetId>/document/<targetId>，`{ id_list }`，目标不能是当前文档   |
+| putGenerateParagraphQuestions                                | PUT batch_generate_related，ParagraphGeneratePayload + paragraph_id_list，不传 state_list |
+| putBatchDeleteParagraphs                                     | PUT batch_delete，`{ id_list }`，服务端清理关联与索引                                     |
+
+标题最多 256，后端内容上限 102400；界面限制见 View 文档。
+问题候选在 knowledge/problem.ts 的 getProblemsPage，支持 content 搜索，类型 ParagraphProblem。
+Workspace 共享 Paragraph API 仅 getParagraphPage、getParagraphDetail，不补问题查询或维护。
+
+### 标签与文档关联
+
+四范围 tags.ts 按上述知识库前缀维护；Workspace 共享只 getKnowledgeTags，其余范围提供维护和关联。
+公共类型为 KnowledgeTagGroup 及 types/knowledge.ts 的载荷，文档关联不混用标签删除。
+
+| 方法                        | 路径／载荷                                                                              |
+| --------------------------- | --------------------------------------------------------------------------------------- |
+| getKnowledgeTags            | GET <id>/tags，非分页分组；可写范围可传 name，共享无查询参数；值可含 doc_count          |
+| postKnowledgeTags           | POST tags，直接提交 `{ key, value }[]`，兼容创建组及新增值                              |
+| putKnowledgeTag             | PUT tags/<tagId>，完整 id、key、value；重命名保留 value，改单值保留 key，不模拟多行编辑 |
+| deleteKnowledgeTag          | key 删除整组，one 删除单值                                                              |
+| putBatchDeleteKnowledgeTags | PUT tags/batch_delete，直接 ID 数组                                                     |
+| postImportKnowledgeTags     | POST tags/import，FormData 单个 file，XLS／XLSX；跳过重复组合，校验整份文件后写入       |
+| exportKnowledgeTagTemplate  | GET tags/template/export，下载标签模板.xlsx                                             |
+| getDocumentTags             | GET document/<documentId>/tags，支持 name                                               |
+| postBatchAddDocumentTags    | POST document/batch_add_tag，`{ document_ids, tag_ids }`                                |
+| putDeleteDocumentTags       | PUT document/<documentId>/tags/batch_delete，直接标签 ID 数组，仅解除关联               |
+| putUnlinkTagDocuments       | PUT tag/<tagId>/docs_delete，`{ id_list }`，取消同一标签的文档关联                      |
+
+标签名称／值上限 64／128；导入第一行“标签、标签值”，空行跳过，所有工作表统一校验。
+关联文档复用 getDocumentPage，resource_type: document、tags: [tagId]；未关联另传 tag_exclude: true。
 
 ### 工作空间共享资源查询
 
@@ -766,7 +528,7 @@ Workspace 共享知识库详情由 `resourceScope: 'workspace-shared'` 选择上
 - `system/resource-management/chat-user.ts`：`/system/resource/knowledge/{resource_type}/{resource_id}`。
 - `system/shared-resources/chat-user.ts`：`/system/shared/knowledge/{resource_type}/{resource_id}`。
 
-后三套沿用 V2 可核对的接口路径并标注 V3 联调 TODO；Workspace 共享在 V2 只核对到 KNOWLEDGE 查询，不能据此认定共享智能体接口已支持。
+后三套接口保留联调 TODO；Workspace 共享在 V2 只核对到 KNOWLEDGE 查询，不能据此认定共享智能体接口已支持。
 System 前缀中的额外 `knowledge` 段暂按 V2 保留，不能依据普通资源接口自行删减。
 资源类型使用 `RESOURCE_TYPE.APPLICATION / KNOWLEDGE` 的大写值；后台按原值读写授权记录，不会将小写转换为大写。
 仓库中的 `system_manage/urls.py` 已注册普通 Workspace 授权路径，其他范围需在提供对应接口的后端环境联调。
@@ -774,10 +536,12 @@ System 前缀中的额外 `knowledge` 段暂按 V2 保留，不能依据普通
 通过 `user_group` 查询和保存组自动授权，通过 `user_group_id/<groupId>` 保存逐用户授权，
 分页查询在其后追加 `/<currentPage>/<pageSize>`；沿用 `ParamsPage`、`ResponsePage` 和原有数组请求体。
 调用方直接读取已解包数据并管理 loading；共享只读 API 不补写方法以凑齐接口集合。
-公共类型维护在 `types/chat-user.ts`，经 `@/api/types` 导出；用户组当前没有已授权人数统计字段，待后台确定字段后补充，不用分页用户数据推算全组人数。
+公共类型维护在 `types/chat-user.ts`，经 `@/api/types` 导出；用户组已授权人数读取 `authorized_count`，不用分页用户数据推算全组人数。
 
-当前智能体、知识库对话用户页仅直接调用普通 `workspace/chat-user.ts`，分别传自己的资源类型和路由 ID，暂不接入详情 context。
-其他三个范围的 API 文件保留，但页面暂不选择调用；页面不判断资源范围，当前请求统一使用 Workspace API，其他入口的 API 切换尚未接入。
+智能体对话用户页继续直接调用普通 `workspace/chat-user.ts`。知识库对话用户页通过详情 context
+的 `resourceApi.chatUser` 选择四套现有完整 API，传 `RESOURCE_TYPE.KNOWLEDGE` 和上下文知识库 ID。
+共有查询方法为必填，部分范围缺失的保存方法按 ScheduledSync、Tags、Document 同样的规则标记为可选，
+调用使用 `?.`；缺失方法不发请求、不提示保存成功，不回退普通 Workspace，不修改现有接口协议。
 
 ### 智能体对话日志
 
@@ -793,13 +557,6 @@ System 前缀中的额外 `knowledge` 段暂按 V2 保留，不能依据普通
 目标文档选项通过 `workspace/knowledge/document.ts` 的 `getAllDocuments(knowledgeId)`
 请求不分页的文档列表。聊天记录与标注接口保留在同一 API 文件，尚未接入日志详情正文。
 
-Web 知识库创建的 `WebKnowledgeCreatePayload.doc_strategy` 使用公共 `DocumentStrategy` 类型，
-包含 `split`、`visual` 和 `index`，字段与后端文档处理策略协议一致。
-
-Web 知识库详情及更新响应的顶层 `doc_strategy` 使用 `DocumentStrategy | null`，由
-`KnowledgeItem` 声明；非 Web 类型返回 null。文档处理策略设置通过 `putKnowledge` 仅提交
-`{ doc_strategy }`，服务端合并到知识库 meta，保留其他来源配置，保存不立即发起同步。
-
 ### 知识库外部检索服务
 
 四个知识库范围分别在自己的 `external-retrieval.ts` 中维护相同的查询与保存方法，仅资源前缀不同：
@@ -818,19 +575,18 @@ Web 知识库详情及更新响应的顶层 `doc_strategy` 使用 `DocumentStrat
 保存只更新 payload 传入的 `enabled` 或 `authentication`，保留未提交字段，并返回包含最新 `api_example` 的完整配置。
 响应与提交类型共用 `types/knowledge-external-retrieval.ts`，通过 `@/api/types` 导入；请求层统一解包 `data`。
 页面已实现加载、开关保存、回显与只读内容复制；接口字段有差异时在各自 API 模块适配，不要求联调人员补写页面交互。
-当前页面仅直接调用普通 `workspace/knowledge/external-retrieval.ts`，暂不接入详情 context；
-其他三个范围的 API 文件保留，页面暂不请求并禁用开关、显示待接入提示，不回退普通 Workspace。
+外部检索页面当前直接使用 Workspace API，尚未选择其他三种范围的接口；页面接入边界见 View 文档。
 
 ### 知识库定时同步
 
 `setting/scheduled-sync/` 页面调用设置查询、保存和日志分页接口；保存返回的规范化配置用于回填。
 
-四个知识库范围分别在自己的 `sync.ts` 中维护接口，由 `views/knowledge-detail/context.ts`
-按资源范围装配为 `resourceApi.sync`。Workspace、System 资源管理、System 共享资源提供查询、保存及日志分页；
+四个知识库范围分别在自己的 `scheduled-sync.ts` 中维护接口，由 `views/knowledge-detail/context.ts`
+按资源范围装配为 `resourceApi.scheduledSync`。Workspace、System 资源管理、System 共享资源提供查询、保存及日志分页；
 Workspace 共享版本只提供设置查询和日志分页。定时同步设置页通过 `useKnowledgeDetailContext()`
 取得当前范围的查询 API 和可管理范围的保存 API，不回退其他范围，也不为只读范围补写接口。
 
-`workspace/knowledge/sync.ts` 提供 `getKnowledgeSyncSetting`、`putKnowledgeSyncSetting`，
+`workspace/knowledge/scheduled-sync.ts` 提供 `getKnowledgeSyncSetting`、`putKnowledgeSyncSetting`，
 分别通过 GET、PUT `/<knowledgeId>/sync_setting` 查询和保存 Web、飞书及工作流知识库同步设置。
 `KnowledgeSyncSetting` 定义在 `types/knowledge-sync.ts`，包含 `enabled`、`schedule_type`、
 `sync_type` 及当前周期的时间、日期、间隔或 Cron 字段；`time` 为 HH:mm 数组，
diff --git a/ui/src/api/admin/system/resource-management/knowledge/paragraph.ts b/ui/src/api/admin/system/resource-management/knowledge/paragraph.ts
new file mode 100644
index 00000000000..0219111ca20
--- /dev/null
+++ b/ui/src/api/admin/system/resource-management/knowledge/paragraph.ts
@@ -0,0 +1,86 @@
+import { del, get, post, put } from '@/api/admin/core/request'
+import type { ParamsPage, ResponsePage } from '@/api/admin/core/types'
+import type {
+  ParagraphCreatePayload,
+  ParagraphDetail,
+  ParagraphEditPayload,
+  ParagraphGeneratePayload,
+  ParagraphItem,
+  ParagraphProblem,
+  ParagraphQuery,
+} from '@/api/types'
+
+const getPrefix = (knowledgeId: string, documentId: string) => `/system/resource/knowledge/${knowledgeId}/document/${documentId}/paragraph`
+
+/** 分页查询文档分段，供详情页滚动加载。 */
+const getParagraphPage = (knowledgeId: string, documentId: string, page: ParamsPage, query?: ParagraphQuery) =>
+  get<ResponsePage<ParagraphItem>>(`${getPrefix(knowledgeId, documentId)}/${page.currentPage}/${page.pageSize}`, { ...query })
+
+/** 在指定位置新增分段，默认首位，由服务端触发索引。 */
+const postParagraph = (knowledgeId: string, documentId: string, payload: ParagraphCreatePayload) =>
+  post<ParagraphCreatePayload, ParagraphDetail>(getPrefix(knowledgeId, documentId), payload)
+
+/** 查询分段正文、召回统计及关联问题。 */
+const getParagraphDetail = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  get<ParagraphDetail>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`)
+
+/** 更新分段正文或启用状态，返回最新详情。 */
+const putParagraph = (knowledgeId: string, documentId: string, paragraphId: string, payload: ParagraphEditPayload) =>
+  put<ParagraphEditPayload, ParagraphDetail>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`, payload)
+
+/** 新增问题并关联到当前分段。 */
+const postParagraphProblem = (knowledgeId: string, documentId: string, paragraphId: string, content: string) =>
+  post<{ content: string }, ParagraphProblem>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}/problem`, { content })
+
+/** 获取当前分段关联的全部问题。 */
+const getParagraphProblems = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  get<ParagraphProblem[]>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}/problem`)
+
+/** 将知识库中的已有问题关联到当前分段。 */
+const putAssociateParagraphProblem = (knowledgeId: string, documentId: string, paragraphId: string, problemId: string) =>
+  put<undefined, boolean>(`${getPrefix(knowledgeId, documentId)}/association`, undefined, { paragraph_id: paragraphId, problem_id: problemId })
+
+/** 解除当前分段的问题关联，保留问题及其他分段的关联。 */
+const putUnassociateParagraphProblem = (knowledgeId: string, documentId: string, paragraphId: string, problemId: string) =>
+  put<undefined, boolean>(`${getPrefix(knowledgeId, documentId)}/unassociation`, undefined, { paragraph_id: paragraphId, problem_id: problemId })
+
+/** 将所选分段迁移至目标知识库的文档。 */
+const putMigrateParagraphs = (knowledgeId: string, documentId: string, targetKnowledgeId: string, targetDocumentId: string, paragraphIds: string[]) =>
+  put<{ id_list: string[] }, boolean>(`${getPrefix(knowledgeId, documentId)}/migrate/knowledge/${targetKnowledgeId}/document/${targetDocumentId}`, {
+    id_list: paragraphIds,
+  })
+
+/** 为所选分段生成问题。 */
+const putGenerateParagraphQuestions = (knowledgeId: string, documentId: string, payload: ParagraphGeneratePayload) =>
+  put<ParagraphGeneratePayload, void>(`${getPrefix(knowledgeId, documentId)}/batch_generate_related`, payload)
+
+/** 批量删除当前文档中所选的分段。 */
+const putBatchDeleteParagraphs = (knowledgeId: string, documentId: string, paragraphIds: string[]) =>
+  put<{ id_list: string[] }, boolean>(`${getPrefix(knowledgeId, documentId)}/batch_delete`, { id_list: paragraphIds })
+
+/** 删除当前文档的单个分段及其关联数据。 */
+const deleteParagraph = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  del<undefined, boolean>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`)
+
+/** 调整分段顺序，由服务端同步更新受影响的分段位置。 */
+const putParagraphPosition = (knowledgeId: string, documentId: string, paragraphId: string, position: number) =>
+  put<undefined, void>(`${getPrefix(knowledgeId, documentId)}/adjust_position`, undefined, {
+    paragraph_id: paragraphId,
+    new_position: position,
+  })
+
+export default {
+  getParagraphPage,
+  postParagraph,
+  getParagraphDetail,
+  putParagraph,
+  postParagraphProblem,
+  getParagraphProblems,
+  putAssociateParagraphProblem,
+  putUnassociateParagraphProblem,
+  putMigrateParagraphs,
+  putGenerateParagraphQuestions,
+  putBatchDeleteParagraphs,
+  deleteParagraph,
+  putParagraphPosition,
+}
diff --git a/ui/src/api/admin/system/resource-management/knowledge/sync.ts b/ui/src/api/admin/system/resource-management/knowledge/scheduled-sync.ts
similarity index 100%
rename from ui/src/api/admin/system/resource-management/knowledge/sync.ts
rename to ui/src/api/admin/system/resource-management/knowledge/scheduled-sync.ts
diff --git a/ui/src/api/admin/system/shared-resources/knowledge/paragraph.ts b/ui/src/api/admin/system/shared-resources/knowledge/paragraph.ts
new file mode 100644
index 00000000000..5586752f375
--- /dev/null
+++ b/ui/src/api/admin/system/shared-resources/knowledge/paragraph.ts
@@ -0,0 +1,86 @@
+import { del, get, post, put } from '@/api/admin/core/request'
+import type { ParamsPage, ResponsePage } from '@/api/admin/core/types'
+import type {
+  ParagraphCreatePayload,
+  ParagraphDetail,
+  ParagraphEditPayload,
+  ParagraphGeneratePayload,
+  ParagraphItem,
+  ParagraphProblem,
+  ParagraphQuery,
+} from '@/api/types'
+
+const getPrefix = (knowledgeId: string, documentId: string) => `/system/shared/knowledge/${knowledgeId}/document/${documentId}/paragraph`
+
+/** 分页查询文档分段，供详情页滚动加载。 */
+const getParagraphPage = (knowledgeId: string, documentId: string, page: ParamsPage, query?: ParagraphQuery) =>
+  get<ResponsePage<ParagraphItem>>(`${getPrefix(knowledgeId, documentId)}/${page.currentPage}/${page.pageSize}`, { ...query })
+
+/** 在指定位置新增分段，默认首位，由服务端触发索引。 */
+const postParagraph = (knowledgeId: string, documentId: string, payload: ParagraphCreatePayload) =>
+  post<ParagraphCreatePayload, ParagraphDetail>(getPrefix(knowledgeId, documentId), payload)
+
+/** 查询分段正文、召回统计及关联问题。 */
+const getParagraphDetail = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  get<ParagraphDetail>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`)
+
+/** 更新分段正文或启用状态，返回最新详情。 */
+const putParagraph = (knowledgeId: string, documentId: string, paragraphId: string, payload: ParagraphEditPayload) =>
+  put<ParagraphEditPayload, ParagraphDetail>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`, payload)
+
+/** 新增问题并关联到当前分段。 */
+const postParagraphProblem = (knowledgeId: string, documentId: string, paragraphId: string, content: string) =>
+  post<{ content: string }, ParagraphProblem>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}/problem`, { content })
+
+/** 获取当前分段关联的全部问题。 */
+const getParagraphProblems = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  get<ParagraphProblem[]>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}/problem`)
+
+/** 将知识库中的已有问题关联到当前分段。 */
+const putAssociateParagraphProblem = (knowledgeId: string, documentId: string, paragraphId: string, problemId: string) =>
+  put<undefined, boolean>(`${getPrefix(knowledgeId, documentId)}/association`, undefined, { paragraph_id: paragraphId, problem_id: problemId })
+
+/** 解除当前分段的问题关联，保留问题及其他分段的关联。 */
+const putUnassociateParagraphProblem = (knowledgeId: string, documentId: string, paragraphId: string, problemId: string) =>
+  put<undefined, boolean>(`${getPrefix(knowledgeId, documentId)}/unassociation`, undefined, { paragraph_id: paragraphId, problem_id: problemId })
+
+/** 将所选分段迁移至目标知识库的文档。 */
+const putMigrateParagraphs = (knowledgeId: string, documentId: string, targetKnowledgeId: string, targetDocumentId: string, paragraphIds: string[]) =>
+  put<{ id_list: string[] }, boolean>(`${getPrefix(knowledgeId, documentId)}/migrate/knowledge/${targetKnowledgeId}/document/${targetDocumentId}`, {
+    id_list: paragraphIds,
+  })
+
+/** 为所选分段生成问题。 */
+const putGenerateParagraphQuestions = (knowledgeId: string, documentId: string, payload: ParagraphGeneratePayload) =>
+  put<ParagraphGeneratePayload, void>(`${getPrefix(knowledgeId, documentId)}/batch_generate_related`, payload)
+
+/** 批量删除当前文档中所选的分段。 */
+const putBatchDeleteParagraphs = (knowledgeId: string, documentId: string, paragraphIds: string[]) =>
+  put<{ id_list: string[] }, boolean>(`${getPrefix(knowledgeId, documentId)}/batch_delete`, { id_list: paragraphIds })
+
+/** 删除当前文档的单个分段及其关联数据。 */
+const deleteParagraph = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  del<undefined, boolean>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`)
+
+/** 调整分段顺序，由服务端同步更新受影响的分段位置。 */
+const putParagraphPosition = (knowledgeId: string, documentId: string, paragraphId: string, position: number) =>
+  put<undefined, void>(`${getPrefix(knowledgeId, documentId)}/adjust_position`, undefined, {
+    paragraph_id: paragraphId,
+    new_position: position,
+  })
+
+export default {
+  getParagraphPage,
+  postParagraph,
+  getParagraphDetail,
+  putParagraph,
+  postParagraphProblem,
+  getParagraphProblems,
+  putAssociateParagraphProblem,
+  putUnassociateParagraphProblem,
+  putMigrateParagraphs,
+  putGenerateParagraphQuestions,
+  putBatchDeleteParagraphs,
+  deleteParagraph,
+  putParagraphPosition,
+}
diff --git a/ui/src/api/admin/system/shared-resources/knowledge/sync.ts b/ui/src/api/admin/system/shared-resources/knowledge/scheduled-sync.ts
similarity index 100%
rename from ui/src/api/admin/system/shared-resources/knowledge/sync.ts
rename to ui/src/api/admin/system/shared-resources/knowledge/scheduled-sync.ts
diff --git a/ui/src/api/admin/workspace/knowledge/paragraph.ts b/ui/src/api/admin/workspace/knowledge/paragraph.ts
index 42862544ab5..98c45123922 100644
--- a/ui/src/api/admin/workspace/knowledge/paragraph.ts
+++ b/ui/src/api/admin/workspace/knowledge/paragraph.ts
@@ -14,10 +14,6 @@ import { getWorkspaceId } from '@/utils/resource-context'
 const getPrefix = (knowledgeId: string, documentId: string) =>
   `/workspace/${getWorkspaceId()}/knowledge/${knowledgeId}/document/${documentId}/paragraph`
 
-/** 查询文档的全部分段，按位置排序，支持标题和内容筛选。 */
-const getParagraphList = (knowledgeId: string, documentId: string, query?: ParagraphQuery) =>
-  get<ParagraphItem[]>(getPrefix(knowledgeId, documentId), { ...query })
-
 /** 分页查询文档分段，供详情页滚动加载。 */
 const getParagraphPage = (knowledgeId: string, documentId: string, page: ParamsPage, query?: ParagraphQuery) =>
   get<ResponsePage<ParagraphItem>>(`${getPrefix(knowledgeId, documentId)}/${page.currentPage}/${page.pageSize}`, { ...query })
@@ -76,7 +72,6 @@ const putParagraphPosition = (knowledgeId: string, documentId: string, paragraph
   })
 
 export default {
-  getParagraphList,
   getParagraphPage,
   postParagraph,
   getParagraphDetail,
diff --git a/ui/src/api/admin/workspace/knowledge/sync.ts b/ui/src/api/admin/workspace/knowledge/scheduled-sync.ts
similarity index 100%
rename from ui/src/api/admin/workspace/knowledge/sync.ts
rename to ui/src/api/admin/workspace/knowledge/scheduled-sync.ts
diff --git a/ui/src/api/admin/workspace/shared/knowledge/paragraph.ts b/ui/src/api/admin/workspace/shared/knowledge/paragraph.ts
new file mode 100644
index 00000000000..e69ed591d83
--- /dev/null
+++ b/ui/src/api/admin/workspace/shared/knowledge/paragraph.ts
@@ -0,0 +1,17 @@
+import { get } from '../../../core/request'
+import type { ParamsPage, ResponsePage } from '../../../core/types'
+import type { ParagraphDetail, ParagraphItem, ParagraphQuery } from '@/api/types'
+import { getWorkspaceId } from '@/utils/resource-context'
+
+const getPrefix = (knowledgeId: string, documentId: string) =>
+  `/system/shared/workspace/${getWorkspaceId()}/knowledge/${knowledgeId}/document/${documentId}/paragraph`
+
+/** 分页查询共享知识库文档分段。 */
+const getParagraphPage = (knowledgeId: string, documentId: string, page: ParamsPage, query?: ParagraphQuery) =>
+  get<ResponsePage<ParagraphItem>>(`${getPrefix(knowledgeId, documentId)}/${page.currentPage}/${page.pageSize}`, { ...query })
+
+/** 查询共享知识库分段正文、召回统计及关联问题。 */
+const getParagraphDetail = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  get<ParagraphDetail>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`)
+
+export default { getParagraphPage, getParagraphDetail }
diff --git a/ui/src/api/admin/workspace/shared/knowledge/sync.ts b/ui/src/api/admin/workspace/shared/knowledge/scheduled-sync.ts
similarity index 100%
rename from ui/src/api/admin/workspace/shared/knowledge/sync.ts
rename to ui/src/api/admin/workspace/shared/knowledge/scheduled-sync.ts
diff --git a/ui/src/components/COMPONENT_README.md b/ui/src/components/COMPONENT_README.md
index cab604bb0eb..457c0cc06a0 100644
--- a/ui/src/components/COMPONENT_README.md
+++ b/ui/src/components/COMPONENT_README.md
@@ -35,12 +35,6 @@ Element Plus 已在 Admin、Chat 入口注册。使用前先检查原生 API，
 
 手动组件从具体入口导入；动态表单通过自己的公开入口导入：
 
-```ts
-import SelectModel from '@/components/business/select-model/index.vue'
-import MkSearchList from '@/components/mk-search-list/index.vue'
-import { MkDynamicsForm, MkDynamicsFormConstructor } from '@/components/mk-dynamics-form'
-```
-
 ## 通用规则
 
 - 按钮组件统一使用 `Button` 前缀：操作按钮按 `Button + 动作 + 对象` 命名，例如
@@ -78,7 +72,7 @@ import { MkDynamicsForm, MkDynamicsFormConstructor } from '@/components/mk-dynam
     只销毁内部内容，不等于销毁外层业务组件，不能据此删除外层状态重置。
   - `close()` 只发起关闭，表单清理放在 `closed`，避免关闭动画中内容跳变；依赖本次参数的默认值、
     编辑快照、动态字段及每次打开必须重新查询的数据仍在 `open()` 初始化。
-  父级负责校验或请求时，子组件提交数据后由父级成功调用 `close()`，失败保持打开。
+    父级负责校验或请求时，子组件提交数据后由父级成功调用 `close()`，失败保持打开。
 - 仅登录表单支持回车提交；其他业务表单使用 `@submit.prevent`，保存、添加由按钮触发。
   自定义 `submit` 事件不等于原生表单提交。
 
@@ -86,44 +80,17 @@ import { MkDynamicsForm, MkDynamicsFormConstructor } from '@/components/mk-dynam
 
 ### MkHorizontalScroll
 
-全局横向滚动组件，位于 `global/mk-horizontal-scroll/index.vue`，模板自动注册。
-通过默认插槽传入内容，内部横向 Flex 排列并提供 8px 间距；固定宽度的内容应设置 `shrink-0`。
-左右箭头分别在对应方向可滚动时显示，到达边界即隐藏；按钮绝对定位在容器两侧并垂直居中，
-不占用内容宽度。每次点击平滑滚动可视宽度的 80%。
-底层使用 `el-scrollbar`，隐藏横向滚动条，保留触控板和触屏的原生横向滚动。
-`ResizeObserver` 监听容器和内容尺寸，自动响应内容增删、图片加载及窗口缩放；卸载时清理监听。
-外部间距由使用方通过 `class` 设置，不在组件内绑定附件业务。
-
-```vue
-<MkHorizontalScroll class="mb-3">
-  <template v-for="file in files" :key="file.uid">
-    <el-card class="w-60 shrink-0">{{ file.name }}</el-card>
-  </template>
-</MkHorizontalScroll>
-```
+位于 `global/mk-horizontal-scroll/index.vue`。默认插槽横向排列、间距 8px，固定宽度子项使用 `shrink-0`。
+左右箭头仅在对应方向可滚动时显示，点击滚动可视宽度的 80%；使用 el-scrollbar，保留触控板／触屏滚动。
+内容及容器尺寸变化自动更新，外部间距由调用方设置。
 
 ### MkAudio、MkVideo
 
-位于 `global/mk-media-preview/`，两个全局组件分别提供音频、视频遮罩播放器。
-传入必填 `src`、`name`；通过默认插槽传入触发内容，卡片、图标、文件大小及样式由调用方维护。
-`src` 为空时不打开预览；触发区域支持点击、Enter 和空格打开，遮罩内居中显示原生音频或视频控制条并尝试自动播放；
-自动播放受浏览器策略限制时可手动播放。关闭按钮、点击遮罩或 Esc 关闭预览，立即卸载播放器。
-附件删除或列表清空导致组件卸载时也会清理播放器；地址变化时关闭旧预览。
-预览采用页面遮罩，不主动请求浏览器全屏，视频原生控制条仍可提供全屏功能。
-内部入口 `index.vue`（`MkMediaPreview`） 统一无样式的触发容器与媒体遮罩，不使用 `MkDialog`。
-遮罩通过 Teleport 挂载到 body，使用 `ElOverlay` 与 `useZIndex` 管理遮罩和层级，
-`useLockscreen` 锁定背景滚动，`TrapFocus` 约束键盘焦点；打开时聚焦关闭按钮，关闭后焦点返回触发区。
-预览区处理 Esc 关闭，界面只展示居中的播放器和右上角关闭按钮。业务方使用两个公开组件，
-不直接调用内部组件。组件不创建或释放 Object URL，由调用方维护地址生命周期。
-
-```vue
-<MkAudio :src="audioUrl" name="录音.mp3">
-  <el-card>录音附件卡片</el-card>
-</MkAudio>
-<MkVideo :src="videoUrl" name="演示.mp4">
-  <el-card>视频附件卡片</el-card>
-</MkVideo>
-```
+位于 `global/mk-media-preview/`，公开 `MkAudio`、`MkVideo`，不使用内部 `MkMediaPreview`。
+必填 `src`、`name`，默认插槽放触发内容；空地址不打开。点击、Enter 或空格打开原生播放器遮罩，
+关闭按钮、遮罩和 Esc 关闭；尝试自动播放，浏览器限制时手动播放。
+预览 Teleport 到 body，管理遮罩层级、滚动锁定、焦点约束和返回；地址变化或卸载清理播放器。
+Object URL 由调用方创建和释放，组件不管理其生命周期。
 
 ### MkTooltip
 
@@ -158,8 +125,6 @@ Admin、Chat 入口调用 `configureMarkdownEditor()` 配置本地高亮、KaTeX
 `trigger` 默认 `header`，点击标题区域切换；设置为 `indicator` 时，仅点击箭头按钮切换，
 标题文字和空白区域不触发。箭头按钮支持键盘操作。
 
-`v-model:expanded` 可控制展开状态；未绑定时沿用 `defaultExpanded` 的内部状态。
-
 标题折叠区，`title` 或 `label` 插槽提供标题，默认插槽提供内容。
 `defaultExpanded` 默认 `true`，仅设置初始状态；展开状态通过 `v-model:expanded` 同步。
 `indicatorPosition` 默认 `before`，可设为 `after`；`triggerClass`、`triggerStyle` 调整触发区。
@@ -227,23 +192,6 @@ Drawer 没有 `MkDialog` 的外壳挂载控制；需要按需挂载时，由业
   用 `v-model:batch-selection` 绑定唯一值数组，`batch-values` 传当前列表全部值。
   插槽提供 `batchSelection`；取消清空选择并触发 `batch-cancel`。
 
-```vue
-<MkViewLayout :loading="loading">
-  <template #default="{ title, Header, Footer }">
-    <component :is="Header"><h4>{{ title }}</h4></component>
-    <ResourceList />
-    <component :is="Footer" v-if="batchMode"
-      v-model:batch-selection="selectedIds" :batch-values="resourceIds"
-      @batch-cancel="batchMode = false">
-      <template #footer-batch-actions="{ batchSelection }">
-        <!-- 删除选中资源 -->
-        <el-button :disabled="!batchSelection.length" @click="removeResources(batchSelection)">删除</el-button>
-      </template>
-    </component>
-  </template>
-</MkViewLayout>
-```
-
 ### MkIcon
 
 `name` 接收完整 SVG Symbol ID，`icon` 接收显式导入的 Element Plus 图标，二选一；
@@ -307,13 +255,7 @@ Element Plus 的 `v-infinite-scroll`。组件通过 `v-model` 管理已经加载
 `activeText`、`inactiveText` 可修改文案，`inactiveIcon` 可覆盖未激活图标（默认 `icon_ban_filled`）。
 成功图标固定为 `icon_succeed_colorful`，失败图标为 `icon_close_colorful`，加载类型使用 `LoadingIcon`，
 禁用图标使用灰色样式。`inactiveIcon` 仅影响布尔模式。
-不再接收 `status`；未知业务状态由调用方显示原始文案，不伪装成成功或禁用状态。
-
-```vue
-<MkStatusLabel :active="enabled" />
-<MkStatusLabel type="loading" label="索引中" />
-<MkStatusLabel v-bind="executionStatus" />
-```
+接口使用 type／label，未知业务状态由调用方显示原始文案，不伪装成成功或禁用状态。
 
 ### MkTable
 
@@ -341,16 +283,6 @@ Element Plus `append`，仅在传入该插槽时将直属表体滚动容器设
 组件不使用 Form 或表单校验；空名称、纯空白及提交期间禁用创建按钮，提交前 trim。
 Esc 或取消清理草稿；`loading` 默认为 false，为 true 时禁止创建和取消。组件不等待 Promise，不自动收起。
 
-```vue
-<MkTable :data="documentData">
-  <template #body-prepend>
-    <!-- 快速创建空白文档 -->
-    <MkQuickCreate ref="quickCreateRef" text="快速创建空白文档" placeholder="请输入文档名称" :loading="creatingDocument" @create="handleCreateDocument" />
-  </template>
-  <el-table-column prop="name" label="文档名称" />
-</MkTable>
-```
-
 `paginationConfig` 包含 `currentPage`、`pageSize`、`total` 和可选 `pageSizes`；不传则隐藏分页器，
 `pageSizes` 默认 `[10, 20, 50, 100]`。
 
@@ -377,13 +309,8 @@ Dialog、Drawer、Popover、嵌套区域等其他大、小表格均禁止开启
 虚拟表格、跨页和跨列表拖拽不属于该接口。排序工具不会深拷贝普通表格的行对象；工作流使用方应在
 数据写回边界自行 `cloneDeep`，保持 LogicFlow 的可观察树约束。
 
-`MkTableFilter` 放在 `global/mk-table/mk-table-filter/`，公共入口为 `index.vue`。
-入口统一选择模式、渲染触发按钮、计算筛选高亮和回写模型；四个内部组件分别维护对应交互：
-`TableFilterSingle.vue` 复用 `MkDropdown`、`MkDropdownMenu` 和 `MkDropdownItem`，
-`TableFilterMultiple.vue` 管理多选草稿及确认，`TableFilterCascader.vue` 管理级联面板及即时提交，
-`TableFilterCustom.vue` 管理对象草稿和自定义内容；多选与自定义模式共用 `TableFilterActions.vue` 的重置、确定按钮。
-内部组件通过默认插槽接收同一个触发按钮，只向入口发送 `select` 和 `open`；页面只使用
-`MkTableFilter`，不直接引用模式组件。多选与级联继续使用 Popover，不强行统一其提交和关闭行为。
+`MkTableFilter` 的公开入口为 `global/mk-table/mk-table-filter/index.vue`，不直接引用内部模式组件。
+页面只维护生效条件、业务选项和查询映射，草稿、显隐、提交及重置由组件负责。
 
 表头筛选使用 `MkTableFilter`，`label` 设置表头文案，必填 `v-model` 保存已生效的条件。
 `mode` 支持以下模式，默认 `multiple`；调用时显式填写 `mode`，便于区分筛选方式：
@@ -393,7 +320,7 @@ Dialog、Drawer、Popover、嵌套区域等其他大、小表格均禁止开启
 | `multiple` | `TableFilterOption[]` / 字符串、数字或布尔值数组          | 打开时复制草稿，确定后提交；重置提交 `[]`；点击外部丢弃草稿 |
 | `single`   | `TableFilterOption[]` / 字符串、数字或布尔值，加 `null`   | 点击立即提交并关闭；“全部”提交 `null`                       |
 | `cascader` | Element Plus `CascaderOption[]` / 由 `cascaderProps` 决定 | 勾选立即提交；多选保持打开，单选提交后关闭                  |
-| `custom` | 不传 options / 自定义对象 | 打开时深拷贝草稿，确定后提交；重置提交 `resetValue` |
+| `custom`   | 不传 options / 自定义对象                                 | 打开时深拷贝草稿，确定后提交；重置提交 `resetValue`         |
 
 `TableFilterOption` 位于 `global/mk-table/mk-table-filter/types.ts`，包含 `label`、`value` 和可选
 `disabled`；扁平选项不使用空字符串作为业务值。`false`、`0` 都是有效筛选条件，正确高亮筛选图标。
@@ -420,36 +347,6 @@ Dialog、Drawer、Popover、嵌套区域等其他大、小表格均禁止开启
 组件不请求业务接口、不转换查询参数。文档文件状态用唯一选项值映射为 `status` 和 `task_type`，
 映射和分页重置由页面负责，切换条件时一起更新这两个参数，避免残留任务类型。
 
-```vue
-<!-- 多选：保留确定与重置 -->
-<MkTableFilter mode="multiple" v-model="workspaceIds" label="工作空间" :options="workspaceOptions" @change="reload" />
-<!-- 单选：enabled 声明为 boolean | null -->
-<MkTableFilter
-  v-model="enabled"
-  mode="single"
-  label="启用状态"
-  :options="[
-    { label: '已启用', value: true },
-    { label: '已禁用', value: false },
-  ]"
-  @change="reload"
-/>
-<!-- 级联：tagIds 为标签值数组，选项通过 children 组织 -->
-<MkTableFilter v-model="tagIds" mode="cascader" label="标签" :options="tagOptions" @open="loadTagOptions" @change="reload" />
-```
-
-```vue
-<!-- 自定义反馈筛选；feedback 为 { min_star: 0, min_trample: 0 } -->
-<MkTableFilter v-model="feedback" mode="custom" label="用户反馈" :reset-value="{ min_star: 0, min_trample: 0 }" @change="reload">
-  <template #default="{ value }">
-    <div class="space-y-3">
-      <el-input-number v-model="value.min_star" :min="0" :value-on-clear="0" controls-position="right" align="left" />
-      <el-input-number v-model="value.min_trample" :min="0" :value-on-clear="0" controls-position="right" align="left" />
-    </div>
-  </template>
-</MkTableFilter>
-```
-
 表格操作列需要 More 菜单时使用 `MkTableMoreDropdown`。组件统一提供点击型、右下定位的 More
 按钮以及 `MkDropdownMenu`，默认插槽中直接放置 `MkDropdownItem`；插槽为空，或其中的条件菜单项
 均未渲染时，不显示 More 触发器。其他 Dropdown 属性和事件通过 `$attrs` 传入，菜单容器样式通过
@@ -475,14 +372,6 @@ Dialog、Drawer、Popover、嵌套区域等其他大、小表格均禁止开启
 原生 `select` 事件仍透传；业务批量操作使用 `selection-change` 的最终结果。
 搜索、分页、切换业务对象后的清理以及提交 ID 的业务去重由页面负责。
 
-```vue
-<MkTable :data="tagRows" selection-group-key="key" :span-method="spanMethod" @selection-change="handleSelectionChange">
-  <el-table-column type="selection" width="40" />
-  <el-table-column prop="key" label="标签" />
-  <el-table-column prop="value" label="标签值" />
-</MkTable>
-```
-
 ### MkAction
 
 `global/mk-table/MkAction.vue` 统一单个操作的两种外观，通过 `display="menu"`（默认）或
@@ -513,19 +402,6 @@ Dialog、Drawer、Popover、嵌套区域等其他大、小表格均禁止开启
 点击卡片或复选框切换，`Action` 在选择模式下不渲染；页面负责选择集合、批量操作和特殊内容显隐。
 `disabled` 只控制指针和阴影，不阻止点击或选择；需要禁用交互时由使用方处理。
 
-```vue
-<MkSourceCard title="工作流工具" :selectable="batchMode" :selected="selected" @selected="selected = $event">
-  <template #footer="{ Action, ActionDropdown }">
-    <MkStatusLabel :active="enabled" />
-    <component :is="Action">
-      <component :is="ActionDropdown">
-        <MkDropdownItem @click="editTool">编辑</MkDropdownItem>
-      </component>
-    </component>
-  </template>
-</MkSourceCard>
-```
-
 ### MkFormList
 
 用于多个业务字段组成的动态表单行，负责重复行布局、添加、删除和可选排序，不管理业务字段、校验规则或
@@ -570,30 +446,13 @@ Dialog、Drawer、Popover、嵌套区域等其他大、小表格均禁止开启
 编辑期间根节点自动设置内部标记 `data-mk-edit-name-editing`，供 `MkTable` 识别编辑焦点；
 退出编辑时移除，调用方无需传入标记或编辑状态。
 
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import MkEditName from '@/components/mk-edit-name/index.vue'
-
-const documentName = ref('DataEase 快速入门')
-// 示例：真实使用时在这里等待业务 API，返回服务端最终名称。
-async function saveDocumentName(name: string): Promise<string> {
-  return name
-}
-</script>
-
-<template>
-  <MkEditName v-model="documentName" :save="saveDocumentName" />
-</template>
-```
-
 表格通过列默认插槽使用，列表以资源 ID 为 key；该列不再启用 `show-overflow-tooltip`，避免编辑时
 叠加表格提示。单元格可用宽度控制组件宽度，业务图标在编辑态隐藏。
 
 ### MkEditAvatar（修改头像）
 
 手动导入 `@/components/mk-edit-avatar/index.vue`，不参与全局注册。字符串 `v-model` 为当前
-自定义头像 URL，空字符串表示使用默认图标；不再接收 `defaultIcon`。
+自定义头像 URL，空字符串表示使用默认图标；默认图标通过插槽提供。
 `size` 默认为 `32`（px），只设置 `referenceRef` 触发容器的宽高；弹层预览和上传区域固定为 80px。
 `disabled` 默认为 `false`，直接传给 `el-popover` 控制禁用，不额外维护禁用状态监听。
 
@@ -615,23 +474,6 @@ async function saveDocumentName(name: string): Promise<string> {
 组件只通过 `change(file)` 通知调用方，不请求接口，也不规定文件何时上传。
 调用方按业务流程处理文件，通过 `v-model` 传入用于展示的头像地址。
 
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import MkEditAvatar from '@/components/mk-edit-avatar/index.vue'
-
-const avatar = ref('')
-</script>
-
-<template>
-  <MkEditAvatar v-model="avatar">
-    <template #default="{ icon }">
-      <PortalIcon :icon="icon" />
-    </template>
-  </MkEditAvatar>
-</template>
-```
-
 ### MkFilterableDropdown
 
 带搜索过滤和滚动列表的下拉选择。组件不限制选项字段，默认使用 `label` 作为展示和搜索字段、
@@ -684,10 +526,6 @@ Logo 数据统一从 Theme Store 获取。
 透明度为 `0.05`；`area: false` 可关闭默认填充，显式 `areaStyle` 可覆盖默认配置。尺寸属性与基础容器一致。
 标题由页面展示；内置图例、坐标轴与提示，两条及以上系列显示图例，单条隐藏。`valueFormatter` 默认使用 `numberFormat`，Tokens 图表传入 `formatTokenNumber`，当前图表颜色直接使用固定颜色值，不跟随主题切换。
 
-```vue
-<MkLineChart :option="{ xData: dates, yData: [{ name: '对话轮次', data: counts, area: true }] }" />
-```
-
 ### MkDateRange
 
 组合日期预设下拉框和自定义日期区间选择器。默认显示“过去 7 天”，仅在用户修改筛选条件时通过
@@ -699,38 +537,19 @@ Logo 数据统一从 Theme Store 获取。
 
 ### MkDragUpload
 
-`mk-drag-upload/index.vue` 为统一入口，根据 `multiple` 选择 `SingleFileUpload.vue` 或
-`MultipleFileUpload.vue`，转发 Props、事件、插槽和公开方法。单文件的卡片、更换及整体清理逻辑
-放在 `SingleFileUpload.vue`，多文件的常驻拖拽区、文件列表及逐项删除逻辑放在
-`MultipleFileUpload.vue`，不在一个实现中混合两种模式的状态分支。
-两种模式均通过 `v-model` 管理兼容 Element Plus `UploadUserFile[]` 的 `DragUploadFile[]`，
-类型定义位于 `mk-drag-upload/types.ts`，可携带 `file_id`、`errMsg` 和 `canRetry`。
-`multiple` 默认为 `false`，单文件模式选择后展示默认卡片和更换入口；传入 `multiple` 后支持
-多文件选择，拖拽区保持显示。`accept`、`limit` 直接传给上传控件，多文件模式内部也校验文件格式、
-空文件和重复文件；超出数量时提示并发出 `exceed`。`sizeLimit` 为多文件的单文件大小上限（MB），
-默认 100；超限保留 `fail` 卡片和大小错误提示，不允许重试。格式不支持、空文件及重复选择移除；
-重复选择保留列表中最先加入的文件，移除时同步清理上传控件内部列表，避免回写未上传的重复项。
-目录中的 `.DS_Store` 格式不支持时静默移除。
-`dragText`、`selectText`、`tipText` 和 `replaceText` 可替换默认文案，格式或限制说明通过
-`tipText` 展示。文件列表由各模式组件直接展示，多文件模式展示
-已选数量或上传完成汇总和两列 `el-card.small` 文件卡片；`download` 作用域插槽为文件卡片提供下载操作。
-多文件列表使用 Element Plus 的 `ready`、`uploading`、`success`、`fail` 状态展示进度和失败原因，
-可重试失败文件、其他失败文件、上传中文件依次置顶。尚未上传的文件显示已选择，不计入完成数。
-多文件组件通过 `inject('upload')` 获取调用方提供的 `DragUploadHandler`：
-`(file, onProgress) => { request: Promise<string>, abort }`。选择文件后先发出 `change`，等待
-调用方列表回写并完成组件校验，再上传保留的 `ready` 文件；进度回调更新 `percentage`，请求成功后
-从响应地址提取 `file_id` 并标记 `success`，网络失败标记 `fail` 并允许重试。100% 表示传输完成，成功状态以请求响应为准。
-单个和全部重试仅对 `fail` 且 `canRetry` 的文件生效，有注入接口时直接重新上传；未注入时
-保持文件选择模式，重试逐文件发出 `retry(file)`。删除、清空和卸载时取消仍在进行的上传。
-使用方可通过 `change` 增加业务校验，通过 `remove` 清理业务数据。具体接口由页面
-`provide<DragUploadHandler>('upload', handler)` 提供，不写入公共组件。
-多文件组件移除 `success` 且具有 `file_id` 的文件时，直接调用 Admin `FileApi.deleteFile(file_id)`
-删除服务端文件；`remove` 事件仍用于通知调用方清理业务数据。
-数量限制使用 `limit`，不通过展示插槽控制行为。
-组件暴露 `clearFiles()` 清空控件状态、`handleRemove(file)` 移除文件和响应式 `uploadingCount` 上传中数量。
-多文件组件的默认选择文案内提供“选择文件夹”，内部维护隐藏的目录选择 input，选择后逐项
-加入上传控件并触发相同的 `change` 流程；等待调用方校验回写后再计算数量限制，超限发出
-`exceed`。多文件通用校验由组件负责，具体请求由业务页面提供。
+入口 `mk-drag-upload/index.vue`，内部按单／多文件分离实现。`v-model` 为 `DragUploadFile[]`，
+兼容 UploadUserFile，支持 file_id、errMsg、canRetry；类型从组件 `types.ts` 导入。
+
+- `multiple` 默认 false；单文件展示卡片和更换入口，多文件保留拖拽区、文件夹选择与列表。
+- `accept`、`limit` 控制格式／数量，多文件 `sizeLimit` 默认 100MB；格式、空文件、重复选择移除，
+  大小超限保留不可重试 fail 卡片，网络失败可重试。超量发出 exceed，DS_Store 格式不支持时静默移除。
+- `dragText`、`selectText`、`tipText`、`replaceText` 覆盖文案；download 作用域插槽提供下载操作。
+- 多文件通过 `inject('upload')` 获取 `DragUploadHandler`，返回 `{ request: Promise<string>, abort }`。
+  change 后等待调用方回写和校验，再上传 ready 文件；响应成功才标记 success 并提取 file_id，100% 仅表示传输完成。
+- 未注入请求时只选择文件，重试发出 retry(file)。删除／清空／卸载取消上传；移除有 file_id 的成功文件会调用
+  Admin FileApi.deleteFile 删除服务端文件，remove 事件通知业务清理。
+- 暴露 clearFiles()、handleRemove(file)、响应式 uploadingCount；公开选择状态 ready／uploading／success／fail。
+  页面提供具体上传请求与业务校验，不通过展示插槽控制数量限制。
 
 ### PythonCodeEditor
 
@@ -774,21 +593,10 @@ JSON 专用输入框，通过 `v-model` 接收并回传解析后的 JSON 值，
 参数与优先级沿用 `MkListItem`，下拉直接放 `MkDropdownItem`。`click(row, index)` 返回原始行。
 `empty` 可自定义空态；默认空数据使用 `emptyText`（“暂无数据”），有搜索词时显示“没有找到相关内容”。
 
-```vue
-<MkSearchList v-model="keyword" :data="workspaces" :props="{ label: 'displayName', value: 'workspaceId' }" @click="selectWorkspace">
-  <template #default="{ row, active }">
-    <span :class="{ 'font-medium': active }">{{ row.displayName }}</span>
-  </template>
-  <template #action-dropdown="{ row }">
-    <MkDropdownItem @click="editWorkspace(row)">编辑</MkDropdownItem>
-  </template>
-</MkSearchList>
-```
-
 ### MkDynamicsForm、MkDynamicsFormConstructor
 
 表单配置加载、字段联动请求与 Tree 懒加载的 loading 由组件在请求前开启，并在 `finally` 中释放；
-不向 API 请求方法传递 loading，动态请求脚本也不再通过 `extra.loading` 获取状态。
+不向 API 请求方法传递 loading，动态请求脚本不通过 `extra.loading` 获取状态。
 
 动态表单 `Tree` 字段使用 `MkTable` 展示文档与文件夹，复用原生复选列、全选和父子选择联动。
 保留 `text_field`、`value_field`、`childrenField` 映射，选中值仍为原始节点对象数组；
@@ -830,7 +638,7 @@ JSON 专用输入框，通过 `v-model` 接收并回传解析后的 JSON 值，
 
 启用显隐设置时，配置器将 Tabs 导航与内容分开，只继承容器的最大高度，内容较少时自然撑开。
 `el-scrollbar` 及其内部滚动容器使用可收缩的 Flex 布局，并覆盖默认的百分比高度；达到最大高度后
-仅内容区滚动，Tabs 保持固定。普通 `MkDialog` 已提供内容最大高度，调用方不需要设置固定高度。
+仅内容区滚动，Tabs 保持固定。普通 `MkDialog` 已提供内容最大高度，调用方不设置固定高度。
 两个表单通过 `v-show` 切换并保持挂载，确保未选中的页签也能回填、取值和校验。
 
 字段配置中的动态校验器和表格行表达式属于受信任的服务端协议，只允许加载可信配置；普通业务
@@ -845,7 +653,7 @@ MultiRow、RadioRow 的配置器与运行时复用字段组件，分别使用复
 禁用、键盘和校验行为；仅展示完整选项，输出仍为 `MultiRow`、`RadioRow`。
 
 动态表单的 Model 字段使用 `SelectModel`，将 `attrs.provider_list` 中的模型快照映射为
-扁平 `ModelItem[]`，由选择器统一分组和展示供应商。旧快照未保存状态时保留可选行为，已保存的
+扁平 `ModelItem[]`，由选择器统一分组和展示供应商。已有快照未保存状态时保留可选行为，已保存的
 状态按 `SelectModel` 的可用性规则处理。切换模型一次性回写 `model_id` 和深拷贝后的
 `model_params_setting`；清空时回写空 ID 和空参数，避免修改原配置中的参数对象。
 
@@ -866,14 +674,14 @@ Model 配置器的默认模型也使用 `SelectModel`，仅展示已选的可选
 
 ### GenerateQuestionsDialog
 
-`business/generate-questions/GenerateQuestionsDialog.vue` 共用关联问题配置，
+`business/generate-questions/index.vue` 共用关联问题配置，
 知识库和文档 Action 显式导入，打开时挂载、`closed` 后卸载，局部状态依赖重新挂载初始化。传入提交
 `loading`，通过 `open()` 打开、`close()` 关闭，不传 `modelApi`。
 弹窗通过 `isSystemResource()`、`isSystemSharedResource()` 选择 System 资源管理、System 共享资源
 或 Workspace Model API，统一查询当前范围的 LLM 选项和模型参数；供应商使用公共 API 查询，
 并为 `SelectModel` 提供模型参数查询；支持创建模型后刷新，
 下拉使用 `teleported`。模型选项与参数查询共用一个 `modelLoading`，通过 `finally` 释放；
-表单禁用状态统一为 `loading || modelLoading`，失败提示由请求层处理。
+内容遮罩使用 `loading || modelLoading`，模型选择与提交入口保留相应禁用条件；失败提示由请求层处理。
 提交请求状态由 Action 传入的 `loading` 管理，表单校验后再次检查状态，避免重复提交。
 
 弹窗只通过资源上下文工具判断范围，不持有知识库/文档/段落 ID，也不调用生成接口。`submit(config, stateList)`
@@ -884,7 +692,7 @@ Model 配置器的默认模型也使用 `SelectModel`，仅展示已选的可选
 表单状态保留在 Dialog，同目录 `prompt-cache.ts` 负责按用户读取与保存模型、参数、提示词，
 不注册专用 Store；每次打开读取缓存，提交时保留其他用户的最新记录。
 沿用 v2 的 `localStorage.PROMPT_CACHE` 及 `[{ user, formValue }]` 数组结构，直接读取已有配置，
-保存时只替换当前用户记录，同一用户跨工作空间共用配置；不再传入工作空间 ID。
+保存时只替换当前用户记录，同一用户跨工作空间共用配置；不传工作空间 ID。
 不保存目标 ID 或分段范围；缓存用 `cloneDeep` 隔离。模型未选择或已失效时，默认选中接口返回的第一个
 可用模型并清空旧参数；没有可用模型时保持空选。已有可用选择及参数在加载或刷新后保留。
 取消不保存，提交前校验必填与纯空白提示词；提交失败保留表单，缓存不可用不阻止生成。
@@ -940,7 +748,6 @@ Workspace 的文件夹虚拟树业务组件。组件根据当前资源上下文
 通过 `open(knowledge)` 传入已选知识库快照，确认后通过 `submit` 返回新的选择；取消不修改调用方
 数据，关闭后统一清理临时状态。选择数据直接基于 `KnowledgeItem` 声明为
 `(Partial<KnowledgeItem> & { id: string })[]`，保留必需的 ID 并兼容缺少详情的旧数据，
-不再维护弹窗专用类型文件。
 组件采用 `MkViewLayout` 左右布局，搜索栏位于内容区右上角，刷新位于弹窗标题栏。
 选项使用紧凑三列布局（窄屏减少列数），左侧图标与省略名称、右侧复选框。点击卡片或复选框
 切换选择，选中后仅展示相同 Embedding 模型的选项，清空后恢复；悬停展示知识库详情。
@@ -1023,9 +830,8 @@ Skills 场景传入 `[TOOL_TYPE.SKILL]`，并通过 `title` 指定标题。两
 根目录隐藏“不授权”，已有该值按“查看”展示；包含子资源时传入完整文件夹子树，
 按资源所属工作空间筛选可管理的文件夹 ID，无可管理目录时禁用该范围。
 
-用户授权按 `isSystemResource()` 选择 System 或 Workspace API；用户组列表当前使用 Workspace API。
-现有提交分支却使用所选的 `authorizationApi` 调用用户组保存，System API 尚无该方法，
-因此不能将 System 用户组保存视为已支持。用户和用户组列表目前也没有请求版本校验。
+用户与用户组查询、保存均由入口按 `isSystemResource()` 选择当前范围完整 requestApi，
+Workspace 使用 Workspace API，System 资源管理使用 System API；不以路由工作空间代替资源 workspaceId。
 
 ### UserGroupMembersDrawer
 
@@ -1045,15 +851,12 @@ Workspace API 内部使用 `getWorkspaceId()`，System 共享 API 不接收工
 抽屉内部通过 `isSystemSharedResource() && (auth.isEE || auth.isPE)` 判断是否显示工作空间列及筛选，
 不接收 `showWorkspace` Prop。仅条件成立时查询工作空间选项并传递 `workspace_ids`（JSON 字符串）。
 供应商图标由抽屉查询后传给内部 `ResourceIcon`，模型供应商标识来自关系记录的 `icon`。
-当前查询没有请求版本校验，不保证旧响应在切换或关闭后被忽略。
+请求版本控制遵循 [API 文档](../api/API_README.md#请求版本控制)。
 
 工作空间模型、知识库、应用、工具列表已分别通过 `RelatedResourcesModelAction`、
 `RelatedResourcesKnowledgeAction`、`RelatedResourcesApplicationAction`、`RelatedResourcesToolAction` 接入。
 
-## 维护与检查
-
-新增或调整公共组件时，先确定目录及公开入口，按本文约定实现类型化接口；仅在接口、目录或使用规则变化时
-同步对应章节，不记录内部函数清单。变更全局注册组件时，通过 Vite 开发或构建刷新声明。
+## 文档维护
 
-Vue/TypeScript 改动运行定向 ESLint、类型检查及必要的入口构建；仅修改文档时检查引用、
-Prettier 和 `git diff --check`，无需构建。`npm run lint` 尚无对应 `lint:*` 子脚本，使用定向 ESLint。
+仅在目录、公开接口或使用规则变化时更新对应组件章节；不登记内部函数和修复过程。
+验证规则统一见 [AGENTS.md](../../AGENTS.md)。
diff --git a/ui/src/constants/CONSTANT_README.md b/ui/src/constants/CONSTANT_README.md
index eaa44aa0a4d..2a9406a55e5 100644
--- a/ui/src/constants/CONSTANT_README.md
+++ b/ui/src/constants/CONSTANT_README.md
@@ -3,20 +3,12 @@
 `src/constants` 只存放大部分页面或多个业务模块都会使用的共享常量。只被个别页面、组件或
 业务模块使用的常量，应保留在所属代码附近，不要提前提升为全局常量。
 
-共享常量按照明确的业务领域或能力拆分文件，例如：
-
-```text
-src/constants/
-├── CONSTANT_README.md
-├── folder.ts
-└── validation.ts
-```
+共享常量按明确业务领域或能力拆分，不维护会过时的逐文件目录树。
 
 不要创建收集无关常量的通用文件，也不要为了统一导出而新增只做二次转发的 `index.ts`。
 常量名称使用能够表达所属领域和用途的全大写命名，使用方从具体文件直接导入。
 
-后端字段的固定枚举值不是前端展示常量，应在对应的 `src/api/enums/<domain>.ts` 中维护，并
-统一从 `@/api/enums` 导入。`constants` 只维护标签、颜色、选项等前端映射；映射的键应引用
+后端枚举与类型归属统一见 [API_README.md](../api/API_README.md#枚举与类型组织)。`constants` 只维护标签、颜色、选项等前端映射；映射的键应引用
 API 枚举值。例如角色类型和登录方式以 `src/api/enums` 为唯一数据源，`constants/auth.ts`
 只维护它们的展示文案。
 
@@ -25,12 +17,6 @@ API 枚举值。例如角色类型和登录方式以 `src/api/enums` 为唯一
 供前端判断及知识库详情路由 `type` 参数使用，地址不传数字；`KNOWLEDGE_TYPE_LABELS` 按这些字符串提供展示文案。提交接口时仍使用数字枚举值。
 字符串标识统一由 `KNOWLEDGE_TYPE_KEY` 维护，映射、文案和业务判断均引用该常量，避免重复写裸字符串。
 
-```ts
-const knowledgeType = KNOWLEDGE_TYPE_MAP[knowledge.type]
-const isWebKnowledge = knowledgeType === KNOWLEDGE_TYPE_KEY.WEB
-const knowledgeTypeLabel = KNOWLEDGE_TYPE_LABELS[knowledgeType]
-```
-
 `resource-authorization.ts` 的 `RESOURCE_PERMISSION_OPTIONS` 统一维护权限标签和说明；
 资源授权页面与资源用户授权抽屉按版本和根目录约束筛选选项。
 
diff --git a/ui/src/router/ROUTE_README.md b/ui/src/router/ROUTE_README.md
index d3e5b5ad346..cbb28eb1d96 100644
--- a/ui/src/router/ROUTE_README.md
+++ b/ui/src/router/ROUTE_README.md
@@ -4,39 +4,13 @@
 
 项目包含 Admin 和 Chat 两个独立入口，两者分别创建自己的 Router 实例，不共享路由表。
 
-## 目录结构
-
-```text
-src/router/
-├── ROUTE_README.md
-├── admin/
-│   ├── index.ts                 # Admin Router、拦截器、导航目录生成
-│   ├── utils.ts                 # 导航目录等公共路由工具
-│   ├── types.ts                 # RouteMeta 类型扩展
-│   ├── login/
-│   │   └── index.ts             # 登录等无框架页面
-│   ├── workflow/
-│   │   └── index.ts             # Workflow 全屏页面
-│   ├── system/
-│   │   ├── index.ts             # 系统管理路由汇总
-│   │   └── modules/
-│   │       ├── application.ts         # System 来源的智能体详情路由
-│   │       ├── knowledge-system-resource.ts # System 资源管理知识库详情路由
-│   │       └── knowledge-system-shared.ts # System 共享资源知识库详情路由
-│   └── workspace/
-│       ├── index.ts             # 工作空间模块汇总
-│       └── modules/
-│           ├── home.ts          # 首页
-│           ├── application.ts         # 智能体
-│           ├── knowledge.ts     # 知识库列表及普通详情
-│           ├── knowledge-shared.ts # 工作空间共享知识库详情
-│           ├── tool.ts          # 工具
-│           ├── model.ts         # 模型
-│           └── trigger.ts       # 触发器
-└── chat/
-    ├── index.ts                 # Chat Router 与认证守卫
-    └── routes.ts                # Chat 路由表（门户与单应用对话）
-```
+## 目录职责
+
+- `admin/index.ts`：Router、导航初始化与认证；`types.ts`：RouteMeta；`utils.ts`：导航生成。
+- `admin/workspace/modules/`：按业务维护工作空间路由，`workspace/index.ts` 汇总。
+- `admin/system/modules/`：System 复用页面；`system/index.ts`：系统导航及汇总。
+- `admin/login/`、`admin/workflow/`：无 AppLayout 的登录和全屏画布路由。
+- `chat/index.ts`、`chat/routes.ts`：独立认证守卫和单应用／门户路由。
 
 ## 路由分类
 
@@ -158,20 +132,22 @@ Chat 导航守卫（`chat/index.ts`）：
 
 路由扩展字段定义在 `admin/types.ts`：
 
-| 字段                 | 类型                                                                        | 说明                                                                 |
-| -------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `scope`              | `'workspace' \| 'system'`                                                   | 标记生成哪一套框架导航，只配置在布局根路由上                         |
-| `resourceScope`      | `'workspace' \| 'workspace-shared' \| 'system-resource' \| 'system-shared'` | 标记页面使用的资源范围，由对应资源父路由配置并向下继承               |
-| `activeIcon`         | `string`                                                                    | 菜单激活状态的 iconfont Symbol ID                                    |
-| `activeMenu`         | `string`                                                                    | 进入子页面时需要保持激活的侧栏菜单路径                               |
-| `resourceDetailRoot` | `boolean`                                                                   | 标记资源详情根，详情容器和独立文档分段页配置，用于目录与工作空间切换 |
-| `detailActiveMenu`   | `string`                                                                    | 更深层详情页面需要保持激活的二级菜单路由名称                         |
-| `title`              | `string`                                                                    | 页面标题，同时作为导航名称                                           |
-| `icon`               | `string`                                                                    | iconfont Symbol ID，子目录通常可以不配置                             |
-| `order`              | `number`                                                                    | 同级导航排序，数字越小越靠前                                         |
-| `hidden`             | `boolean`                                                                   | 设置为 `true` 时不显示在导航中                                       |
-| `hideSidebar`        | `boolean`                                                                   | 隐藏 AppLayout 应用侧栏，保留顶部栏和页面自身导航；子页继承          |
-| `resource`           | `ResourceAuthorizationType`                                                 | 系统资源授权页面当前管理的后端资源类型                               |
+| 字段                 | 类型                                                                        | 说明                                                                      |
+| -------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `scope`              | `'workspace' \| 'system'`                                                   | 标记生成哪一套框架导航，只配置在布局根路由上                              |
+| `resourceScope`      | `'workspace' \| 'workspace-shared' \| 'system-resource' \| 'system-shared'` | 标记页面使用的资源范围，由对应资源父路由配置并向下继承                    |
+| `activeIcon`         | `string`                                                                    | 菜单激活状态的 iconfont Symbol ID                                         |
+| `activeMenu`         | `string`                                                                    | 进入子页面时需要保持激活的侧栏菜单标识（Workspace 为名称，System 为路径） |
+| `resourceDetailRoot` | `boolean`                                                                   | 标记资源详情根，详情容器和独立文档分段页配置，用于目录与工作空间切换      |
+| `detailActiveMenu`   | `string`                                                                    | 更深层详情页面需要保持激活的二级菜单路由名称                              |
+| `title`              | `string`                                                                    | 页面标题，同时作为导航名称                                                |
+| `icon`               | `string`                                                                    | iconfont Symbol ID，子目录通常可以不配置                                  |
+| `order`              | `number`                                                                    | 同级导航排序，数字越小越靠前                                              |
+| `hidden`             | `boolean`                                                                   | 设置为 `true` 时不显示在导航中                                            |
+| `hideSidebar`        | `boolean`                                                                   | 隐藏 AppLayout 应用侧栏，保留顶部栏和页面自身导航；子页继承               |
+| `detailMenuVisible`  | `(params) => boolean`                                                       | 按业务类型过滤详情菜单，不用于权限                                        |
+| `canAccess`          | `(params) => boolean`                                                       | 工作流返回详情时的访问判断                                                |
+| `resource`           | `ResourceAuthorizationType`                                                 | 系统资源授权页面当前管理的后端资源类型                                    |
 
 ## 导航生成
 
@@ -207,21 +183,12 @@ System 侧栏默认使用当前页面的 `route.path` 匹配菜单激活项。Wo
 
 Layout 对 Workspace、System 模式的判断统一维护在 `src/layout/utils.ts`：
 
-```ts
-import { isSystem, isWorkspace } from '@/layout/utils'
-```
-
 `scope` 来自 Vue Router 合并后的路由 `meta`。Workspace、System 子页面会分别继承根路由的 `workspace`、`system`。
 
 `getChildRouteList` 属于公共路由工具，继续维护在 `admin/utils.ts`；仅供 Layout 使用的模式判断不要放入 Router。
 
 路由对象是响应式的，不要在 setup 顶层解构 `route.meta.scope`，否则切换路由后 Scope 不会更新。需要响应路由变化时，应在 `computed` 中读取：
 
-```ts
-const route = useRoute()
-const mode = computed(() => route.meta.scope ?? 'workspace')
-```
-
 ## 资源范围判断
 
 `application`、`knowledge`、`model`、`tool` 是需要跨资源范围维护的四类特殊资源。
@@ -239,255 +206,75 @@ Drawer、Dialog 通常不根据 path、路由名称或 Scope 自行维护 API 
 资源授权抽屉 `ResourceAuthorizationDrawer` 例外：由抽屉入口通过 `isSystemResource()`
 选择 System 资源管理或 Workspace 用户授权接口，再传给标签子组件。
 
-## 业务路由层级
-
-Workspace 页面：
-
-```text
-/admin/workspace/:workspaceId/tools
-/admin/workspace/:workspaceId/model
-
-/admin/workspace/:workspaceId/tool/:toolId/workflow
-
-/admin/workspace/:workspaceId/application
-/admin/workspace/:workspaceId/application/:applicationId/workflow
-/admin/workspace/:workspaceId/application/:applicationId/:type/overview
-/admin/workspace/:workspaceId/application/:applicationId/:type/setting
-
-/admin/workspace/:workspaceId/knowledge
-/admin/workspace/:workspaceId/knowledge/:knowledgeId/workflow
-/admin/workspace/:workspaceId/knowledge/:knowledgeId/:type
-/admin/workspace/:workspaceId/knowledge/:knowledgeId/:type/document
-/admin/workspace/:workspaceId/knowledge/:knowledgeId/:type/setting
-/admin/workspace/:workspaceId/knowledge/:knowledgeId/:type/setting/base
-/admin/workspace/:workspaceId/knowledge/:knowledgeId/:type/setting/document-strategy
-/admin/workspace/:workspaceId/knowledge/:knowledgeId/:type/setting/scheduled-sync
-/admin/workspace/:workspaceId/knowledge/:knowledgeId/:type/workflow-entry
-/admin/workspace/:workspaceId/knowledge/:knowledgeId/:type/document/:documentId
-```
-
-智能体详情路由的 `type` 来自当前 `ApplicationDetail.type`；卡片概览和简易智能体设置等详情入口
-必须与 `applicationId` 一并传入该参数。高级智能体设置继续进入独立的 Workflow 路由。
-智能体详情返回列表时，根据 `ApplicationDetail.folder` 通过可选的 `folderId` query 标记所属文件夹；
-列表中的 `FolderTree` 初始化时读取该 query 并恢复选中项。用户在列表中切换文件夹时不写入新的
-文件夹 ID，只清除已有的 `folderId`；进入详情时也不继续携带该 query。`folderId` 不作为详情 path
-参数。
-
-System 复用页面：
-
-```text
-/admin/system/application/:applicationId
-/admin/system/application/:applicationId/edit
-
-/admin/system/resource/knowledge/:knowledgeId/:type
-/admin/system/resource/knowledge/:knowledgeId/:type/document
-/admin/system/shared/knowledge/:knowledgeId/:type
-/admin/system/shared/knowledge/:knowledgeId/:type/document
-```
-
-不同来源的详情路由使用独立名称并复用相同页面组件。System 知识库详情沿用对应列表的
-`resource` / `shared` 目录，详情地址不携带 `workspaceId`。
-
-System 共享资源页面：
-
-```text
-/admin/system/shared/knowledge
-/admin/system/shared/models
-/admin/system/shared/tools
-```
-
-`system-shared-knowledge` 渲染 `views/system/shared-resources/knowledge/index.vue`，提供共享知识库
-卡片管理页面；`system-shared-tools` 渲染 `views/system/shared-resources/tool/index.vue`，提供共享工具管理页面。
-
-共享资源路由是 System 导航的一部分，继续在 `admin/system/index.ts` 的 `shared` 子路由中维护。
-已实现的共享资源页面放在 `views/system/shared-resources/`，由页面处理 System 范围的查询和操作，
-可按需复用 Workspace 对应资源的卡片等展示组件。
-
-## 一级导航示例
-
-```ts
-{
-  path: 'settings',
-  name: 'system-settings',
-  component: () => import('@/views/system/index.vue'),
-  meta: {
-    title: '系统设置',
-    icon: 'icon_setting',
-    order: 60,
-  },
-}
-```
-
-## 子目录示例
-
-```ts
-{
-  path: 'identity',
-  name: 'system-identity',
-  redirect: { name: 'system-users' },
-  meta: {
-    title: '身份与权限',
-    icon: 'icon_user_outlined',
-    order: 10,
-  },
-  children: [
-    {
-      path: 'users',
-      name: 'system-users',
-      component: () => import('@/views/system/identity/users/index.vue'),
-      meta: {
-        title: '用户管理',
-        order: 10,
-      },
-    },
-  ],
-}
-```
-
-对应地址为 `/admin/system/identity/users`。
-
-## 不显示在导航中的页面
-
-详情、创建、编辑等页面仍可以放在对应模块的路由树中，通过 `hidden` 隐藏：
-
-```ts
-{
-  path: 'users/:id/edit',
-  name: 'system-user-edit',
-  component: () => import('@/views/system/user-edit/index.vue'),
-  meta: {
-    title: '编辑用户',
-    hidden: true,
-  },
-}
-```
-
-使用 `ResourceDetailLayout` 的详情路由只在详情父路由配置 `hidden: true`；需要显示在二级导航中的
-直接子路由继续配置 `title`、`icon` 和 `order`，不要再配置 `hidden: true`。一级导航生成时会排除
-整个详情父路由，详情布局则读取该父路由的直接子路由生成自己的二级导航。
-
-## 新增路由约定
-
-- 每条路由必须使用全局唯一的 `name`。
-- 导航页面配置 `title` 和 `order`。
-- 详情、创建、编辑页面配置 `hidden: true`。
-- 有真实层级关系时使用 `children`，不要自行增加菜单分组字段。
-- Workspace 新模块需要在 `workspace/index.ts` 中汇总。
-- System 复用 Workspace 页面时，在 `system/modules` 中创建对应模块文件并由 `system/index.ts` 汇总。
-- Login、Workflow 等全屏页面不要挂载 `AppLayout`。
-- Admin 与 Chat 路由不要相互引用。
-- 每次新增、删除、移动或修改路由时，必须同步更新本文件。
-
-工作空间知识库卡片进入 `workspace-knowledge-detail`，默认重定向到“文档”子路由。
-普通与共享知识库详情的 `type` 通过 `KNOWLEDGE_TYPE_MAP[knowledge.type]` 转换为
-`BASE`、`WEB`、`LARK`、`WORKFLOW`，地址不使用接口数字枚举；卡片、设置、创建成功跳转及工作流返回详情
-必须与 `knowledgeId` 一并传入。独立知识库工作流地址保持不变。
-详情容器复用 `ResourceDetailLayout`，菜单依次为“资料库（文档、图片、标签管理）”、
-“工作流”、“检索优化（召回测试、问题、自定义分词）”、“授权与集成（对话用户、外部检索服务）”、
-“设置”。资料库分组使用空 path，保留原 `/document` 地址；图片和标签分别使用 `/image`、`/tag`。
-图片菜单通过路由 `detailMenuVisible(params)` 判断，仅 `BASE` 类型显示，其他类型不显示。
-对应 View 统一位于 `views/knowledge-detail/library/` 下的 `document/`、`image/`、`tag/`；
-普通和共享文档路由均引用 `library/document/index.vue`，文件分组不增加 URL 层级。
-检索优化使用 `/retrieval/recall`、`/retrieval/question`、`/retrieval/dictionary`；
-授权与集成使用 `/integration/chat-user`、`/integration/external-retrieval`。
-分组不挂载页面组件，直接访问分组时重定向到首个子页。新增七个页面暂为占位 View。
-设置菜单使用 `detailMenuVisible(params)` 按知识库类型筛选，不增加权限判断：
-通用知识库保留单个“设置”，沿用 `/setting` 和 `workspace-knowledge-setting`；
-Web 展示“设置 → 基础设置、文档处理策略、定时同步”；飞书和工作流展示
-“设置 → 基础设置、定时同步”。设置分组使用空 path，子页分别使用
-`/setting/base`、`/setting/document-strategy`、`/setting/scheduled-sync`，路由名分别为
-`workspace-knowledge-base-setting`、`workspace-knowledge-document-strategy`、
-`workspace-knowledge-scheduled-sync`。基础设置与通用设置复用
-`knowledge-detail/setting/base/index.vue` 和容器提供的详情。文档处理策略页复用
-`DocumentStrategyForm` 回填及保存策略，定时同步页提供同步设置与分页日志。
-设置路由不配置类型访问守卫，菜单显隐由 `detailMenuVisible` 控制。
-列表设置按钮按知识库类型直接进入通用设置或基础设置。
-`workspace-knowledge-settings` 仅提供菜单分组层级，
-命名访问时重定向到基础设置，保留参数、query 和 hash。`workflow-entry`
-（`workspace-knowledge-workflow`）直接挂载 `knowledge-detail/workflow-transform/index.vue`，
-保留“工作流”菜单。路由 `beforeEnter` 按 `type` 参数判断：工作流类型重定向至独立的
-`workflow-knowledge` 全屏画布，其他类型挂载转换页。转换成功后进入画布；直接访问画布时也查询真实
-知识库类型，非工作流类型先返回转换页。画布返回知识库详情。
-普通 Workspace 文档分段页使用 `workspace-knowledge-paragraph`，地址为
-`/admin/workspace/:workspaceId/knowledge/:knowledgeId/:type/document/:documentId`，
-在 `knowledge.ts` 中与知识库详情容器同级注册，复用 Workspace AppLayout，保持知识库一级菜单激活。
-页面位于 `views/document-detail/index.vue`，使用自身的分段目录，不挂载
-`ResourceDetailLayout`。配置 `hidden` 与 `resourceDetailRoot`，使工作空间切换继续返回知识库列表；
-返回按钮进入 `workspace-knowledge-document-list`，保留知识库类型和 query。
-文档行点击进入分段页，选择列、名称编辑和操作按钮不触发跳转。
-Workspace 共享及 System 两种来源也注册独立的文档分段路由，路径在各自详情地址后追加 `/document/:documentId`；
-分段页不挂载详情容器，返回各自文档列表；各范围分段 API 接入暂缓。
-
-智能体工作流返回通过 `views/workflow/application/navigation.ts` 动态读取详情父路由的 `children`。
-Workspace 父路由为 `workspace-application-detail-layout`；System 详情实现时使用
-`system-application-detail-layout`。按照菜单的 `meta.order` 顺序选择首个具备名称、标题、未隐藏
-且 `meta.canAccess(params)` 返回 true 的子路由；未配置该方法时默认可访问。
-`canAccess` 接收目标路由参数，维护本页权限和类型约束；当前只用于详情返回导航，不代替路由守卫或后端鉴权。
-概览配置 v3 的 `overviewRead` 权限，简易设置要求 SIMPLE 类型及编辑权限。
-新增或调整详情页时在路由中维护这些条件，不在工作流返回函数中新增页面名称分支。
-无可访问子页面或详情父路由尚未实现时，分别返回 `workspace-application-list` 或
-`system-resource-applications`。
-
-### 智能体详情导航
-
-详情导航依次显示概览、设置、接入第三方、对话用户、对话日志。
-`detailMenuVisible(params)` 仅用于详情菜单的业务类型筛选，不用于权限判断，也不影响一级导航。
-简易设置保留 `setting` 和 `workspace-application-simple-setting`；高级设置使用
-`workflow-entry` 和 `workspace-application-workflow-setting`，重定向至 `workflow-application`，
-携带当前工作空间、智能体 ID 和 query。两个入口都显示“设置”，按 `APPLICATION_TYPE` 互斥显示。
-高级设置的 `canAccess` 固定返回 false，避免工作流返回时重新进入画布；原有概览和简易设置的
-返回权限条件保持不变。新增页面未添加权限判断。
-`integration` 对应接入第三方占位页面，`chat-user` 对应对话用户授权页面。
-对话日志沿用 `operation-log` 路径和 `workspace-application-operation-log` 路由名，
-组件改为 `views/application-detail/chat-log/index.vue`，标题为“对话日志”。
-
-### System 资源管理模型与工具
-
-`/system/resource/models`、`/system/resource/tools` 分别渲染
-`views/system/resource-management/model/index.vue` 和 `tool/index.vue`，
-继承 `resourceScope: 'system-resource'`，保留原导航名称、顺序与权限。
-资源管理工具的全屏工作流使用 `system-resource-workflow-tool`，地址为
-`/system/resource/tool/:toolId/workflow`，在 `admin/workflow/index.ts`
-注册，复用 `ToolWorkflowView`。系统工作流路由不携带 `workspaceId`，画布辅助查询使用对应 System API；
-工具自身的查询、编辑、调试和发布使用 System API，返回 `system-resource-tools`。
-
-共享工具工作流使用 `system-shared-workflow-tool`，地址为 `/system/shared/tool/:toolId/workflow`，
-与资源管理共用 `ToolWorkflowView`，通过 `resourceScope` 选择接口。共享工具卡片点击及创建成功后
-进入该路由，Ctrl / Command 点击支持新标签页；退出返回 `system-shared-tools`。
-
-### Workspace 共享知识库详情
-
-共享知识库卡片进入 `workspace-shared-knowledge-detail`，地址为
-`/admin/workspace/:workspaceId/shared/knowledge/:knowledgeId/:type`，默认重定向到
-`workspace-shared-knowledge-document-list`（`document`）。详情父路由配置
-`resourceScope: 'workspace-shared'` 和 `activeMenu: 'workspace-knowledge'`，复用知识库详情容器和文档页，侧栏仍高亮 Workspace 知识库。
-共享详情与其他三种范围维护相同菜单及知识库类型显隐规则；新增页面的共享 API 接入暂缓，不假定各范围接口相同。
-返回列表时使用 `folderId: 'shared'` 恢复共享目录。
-
-### System 知识库详情路由
-
-`admin/system/modules/knowledge-system-resource.ts` 导出 `systemResourceKnowledgeRoutes`，
-`admin/system/modules/knowledge-system-shared.ts` 导出 `systemSharedKnowledgeRoutes`，由 `system/index.ts`
-展开到 System 根路由的 children，使用完整的 `/system/resource/knowledge/:knowledgeId/:type`、
-`/system/shared/knowledge/:knowledgeId/:type` 地址，继承系统管理的 AppLayout。
-详情父路由显式配置 `scope: 'system'` 和对应 `resourceScope`，子页继承资源范围。共享资源统一使用 `shared` 前缀，父路由名为 `system-shared`，相关 `next` 同步使用该名称。
-不保留 `/system/share` 别名，列表及详情均使用 `/system/shared` 地址。
-两种详情父路由分别为 `system-resource-knowledge-detail`、`system-shared-knowledge-detail`，
-均配置 `hidden`、`hideSidebar`、`resourceDetailRoot`，隐藏系统应用侧栏并保留系统顶部栏与详情目录，复用 `knowledge-detail/index.vue`，默认重定向到各自的文档页。
-参数 `type` 沿用 Workspace 的字符串知识库类型。
-
-各来源在自己的模块文件中显式维护 children，不使用共用子路由生成函数。
-四种来源均配置资料库、工作流、检索优化、授权与集成和设置目录，共用 View 组件并保持相同的
-菜单顺序与知识库类型显隐规则。工作流入口对 WORKFLOW 类型跳转对应全屏画布，其他类型进入转换页。
-Workspace 普通保留 `workflow-knowledge`；其他三种来源分别使用
-`workspace-shared-workflow-knowledge`、`system-resource-workflow-knowledge`、`system-shared-workflow-knowledge`，
-地址分别为 `/workspace/:workspaceId/shared/knowledge/:knowledgeId/workflow`、
-`/system/resource/knowledge/:knowledgeId/workflow`、`/system/shared/knowledge/:knowledgeId/workflow`。
-
-System 资源管理知识库表格的详情按钮和共享知识库卡片分别进入对应详情父路由，
-携带 `knowledgeId` 和经 `KNOWLEDGE_TYPE_MAP` 转换的 `type`，不携带 `workspaceId`。
-`AppLayout` 响应当前路由 `meta.hideSidebar` 控制应用侧栏；返回普通列表后自动恢复侧栏。
-预览模式继续保留侧栏占位。`hidden` 仅控制菜单项显隐，不代替 `hideSidebar`。
-详情容器使用 System 主区的高度，按来源查询知识库详情，并返回对应 System 列表。
-本轮仅补齐四套菜单与导航，API 及其上下文装配保持原实现，各范围接口差异后续独立接入。
-新增路由不代表对应范围 API 已完成；不复制 Workspace 协议补造其他来源的接口。
+## 新增与维护
+
+- 路由 name 全局唯一；导航页配置 title、order；详情／创建／编辑父页使用 hidden。
+  详情二级菜单需要展示的子页保留 title、icon、order，不再隐藏。
+- 层级直接用 children，不增加菜单分组字段。新增 Workspace 模块由 workspace/index.ts 汇总；
+  System 复用路由按模块汇总。Admin 和 Chat 不相互引用。
+- View 路径、功能登记见 [VIEW_README.md](../views/VIEW_README.md)，不在本文登记业务交互。
+- 路由变化更新所属配置及本文的导航规则，不复制完整路由树或记录迁移过程。
+
+## 资源详情与工作流导航
+
+### 知识库
+
+四种来源独立维护 children，不使用共享子路由生成函数；复用相同 View，菜单顺序和类型条件一致。
+以下路径相对 Admin base，详情后默认进入 `/document`。
+
+| 来源            | 详情路径                                                      | 详情父路由名                        | 全屏工作流名                          |
+| --------------- | ------------------------------------------------------------- | ----------------------------------- | ------------------------------------- |
+| Workspace       | `/workspace/:workspaceId/knowledge/:knowledgeId/:type`        | `workspace-knowledge-detail`        | `workflow-knowledge`                  |
+| Workspace 共享  | `/workspace/:workspaceId/shared/knowledge/:knowledgeId/:type` | `workspace-shared-knowledge-detail` | `workspace-shared-workflow-knowledge` |
+| System 资源管理 | `/system/resource/knowledge/:knowledgeId/:type`               | `system-resource-knowledge-detail`  | `system-resource-workflow-knowledge`  |
+| System 共享     | `/system/shared/knowledge/:knowledgeId/:type`                 | `system-shared-knowledge-detail`    | `system-shared-workflow-knowledge`    |
+
+`type` 由 KNOWLEDGE_TYPE_MAP 转为 BASE／WEB／LARK／WORKFLOW，地址不使用数字枚举；
+创建、卡片、设置及返回详情均传 knowledgeId 和字符串类型。全屏工作流不含 type，路径在各来源
+知识库 ID 后追加 `/workflow`。System 地址不携带 workspaceId，shared 使用统一前缀，不保留 share 别名。
+
+详情父页配置 hidden、resourceDetailRoot；System 另加 hideSidebar，在 AppLayout 内隐藏系统侧栏，
+保留头部和详情目录。hidden 仅影响导航，不替代 hideSidebar；普通列表恢复系统侧栏。
+Workspace 共享覆盖 resourceScope，保留 Workspace scope 及知识库 activeMenu。
+
+| 菜单       | 路径与条件                                                                                                            |
+| ---------- | --------------------------------------------------------------------------------------------------------------------- |
+| 资料库     | 空 path 分组；document、image、tag；仅 BASE 显示图片                                                                  |
+| 工作流     | workflow-entry；WORKFLOW 类型 beforeEnter 重定向对应全屏画布，其他类型显示转换页                                      |
+| 检索优化   | retrieval/recall、retrieval/question、retrieval/dictionary                                                            |
+| 授权与集成 | integration/chat-user、integration/external-retrieval                                                                 |
+| 设置       | BASE 单独 setting；WEB 分组含 setting/base、document-strategy、scheduled-sync；LARK／WORKFLOW 含 base、scheduled-sync |
+
+分组不挂 View，直接访问重定向首个子页，保留参数、query、hash。
+设置只用 detailMenuVisible 控制菜单类型，不添加类型访问守卫。资料库 View 的目录是 library/tags，URL 仍为 tag。
+
+分段地址在各来源详情后追加 `/document/:documentId`，路由名为 `<resourceScope>-knowledge-paragraph`。
+与详情容器同级挂载，使用自身分段目录；配置 hidden 和 resourceDetailRoot，返回对应文档列表并保留 query。
+全屏画布直接访问时检查真实知识库类型，非工作流返回转换页；返回导航集中在 workflow/knowledge/navigation.ts。
+菜单与路由存在不代表该范围全部 API 已支持，真实接口边界见 API 文档。
+
+### 智能体
+
+Workspace 详情父路由为 workspace-application-detail-layout，详情参数包含 applicationId 与 ApplicationDetail.type。
+菜单为概览、设置、接入第三方、对话用户、对话日志；SIMPLE 的 setting 与高级 workflow-entry 互斥显示。
+高级设置重定向 workflow-application，保留 workspaceId、applicationId 和 query。
+对话日志保留 operation-log 路径和 workspace-application-operation-log 名称。
+
+workflow/application/navigation.ts 按详情子路由 order 查找首个有名称、标题、未隐藏且 canAccess 允许的页面。
+未配置 canAccess 默认允许；它仅用于返回导航，不替代守卫或后端鉴权。
+概览使用 overviewRead，简易设置要求 SIMPLE 与编辑权限，高级设置 canAccess 为 false，避免返回画布。
+无可访问详情或 System 详情父路由未实现时返回对应列表，不在导航函数硬编码子页分支。
+
+### 工具
+
+Workspace 工作流为 `/workspace/:workspaceId/tool/:toolId/workflow`；System 两种入口为
+`/system/resource/tool/:toolId/workflow` 和 `/system/shared/tool/:toolId/workflow`，
+名称分别 system-resource-workflow-tool、system-shared-workflow-tool，统一复用 ToolWorkflowView。
+工具／模型范围由各路由的 resourceScope 传递；System 不传路由工作空间。
+返回导航集中在 workflow/tool/navigation.ts，Workspace 带可选 folderId，System 返回各自工具列表。
+
+### 文件夹恢复
+
+详情返回列表用资源 folder 写入 folderId query；FolderTree 初始化恢复，切换文件夹只清除旧 query，
+不写新的文件夹 ID，进入详情不携带它。Workspace 共享知识库返回 folderId: shared。
+该参数不进入详情 path。
diff --git a/ui/src/styles/STYLE_README.md b/ui/src/styles/STYLE_README.md
index ebcd2c0daab..b5b0ab8349b 100644
--- a/ui/src/styles/STYLE_README.md
+++ b/ui/src/styles/STYLE_README.md
@@ -16,15 +16,9 @@
 `@layer components`、`@utility` 的顺序组织；不存在的部分直接省略。`@theme` 内部按照颜色、
 背景图片、间距、阴影、排版分组，每组通过注释标明职责，不将不同类型的 Token 混合排序。
 
-`src/main.ts` 和 `src/chat.ts` 应按以下顺序加载样式：
-
-```ts
-import 'element-plus/dist/index.css'
-import './styles/tailwind.css'
-import './styles/index.scss'
-```
-
-项目样式必须位于 Element Plus 官方样式之后，确保 `element-plus.scss` 中的 CSS 变量映射可以生效。Tailwind 必须与 Sass 入口分开，不要在 `index.scss` 中引入 Tailwind，避免 Tailwind 经过 Sass 处理而产生构建警告或错误结果。
+Admin 入口先引入 `tailwind.css`，再引入 `index.scss`；后者已按顺序加载第三方 CSS、
+Element Plus 覆盖、主题变量和应用样式。Chat 入口还显式引入 Element Plus 官方 CSS。
+保持项目覆盖位于官方样式之后，Tailwind 与 Sass 入口分开，不在 Sass 中引入 Tailwind。
 
 ## 对话模块公共样式
 
@@ -64,16 +58,7 @@ import './styles/index.scss'
 Admin 和 Chat 共用。组件不单独恢复焦点 `outline`，包括通过隐藏输入框的焦点为相邻可见元素
 绘制轮廓的情况；组件原有的 `border`、`box-shadow` 和焦点行为不受此规则影响。
 
-不要使用会影响所有元素间距的宽泛重置规则，例如：
-
-```scss
-* {
-  margin: 0;
-  padding: 0;
-}
-```
-
-这类规则会破坏 Element Plus 组件的默认间距。仅设置必要的基础规则，例如统一 `box-sizing`、清除 `body` 默认外边距和定义应用级布局。
+不要使用全元素 margin／padding 重置，会破坏 Element Plus 组件的默认间距。仅设置必要的基础规则，例如统一 `box-sizing`、清除 `body` 默认外边距和定义应用级布局。
 
 ## Markdown 表格
 
@@ -97,7 +82,7 @@ Tailwind 在 `tailwind.css` 中显式重写了项目字号及对应行高：
 | `text-lg`   | 16px | 24px | Tailwind 固定值                                 |
 | `text-xl`   | 18px | 26px | Tailwind 固定值                                 |
 
-使用字号工具类时会同时应用表中的字号和行高。例如，`text-lg` 等价于 `font-size: 16px; line-height: 24px`。
+使用字号工具类时会同时应用表中的字号和行高。`text-lg` 等价于 `font-size: 16px; line-height: 24px`。
 
 普通正文直接继承 `body` 的 `14px / 22px`，不需要重复添加 `text-base`。仅在元素需要明确覆盖继承字号或行高时使用以上工具类；如设计稿对行高另有明确要求，再使用 `leading-*` 单独覆盖。
 
@@ -115,12 +100,7 @@ Tailwind 在 `tailwind.css` 中显式重写了项目字号及对应行高：
 | `h5` | 五级标题 | 16px/24px | 400  |
 | `h6` | 辅助标题 | 14px/22px | 500  |
 
-标题默认清除浏览器 margin。布局、颜色、省略等非排版需求仍可通过 class 补充：
-
-```html
-<h1>页面标题</h1>
-<h2 class="truncate text-primary" title="完整的内容标题">完整的内容标题</h2>
-```
+标题默认清除浏览器 margin。布局、颜色、省略等非排版需求仍可通过 class 补充。
 
 设计规范中的特大标题为 `30px/38px/600`，仅用于特殊页面级展示，不占用 `h1` 至 `h6`
 的常规内容层级。
@@ -131,11 +111,6 @@ Tailwind 在 `tailwind.css` 中显式重写了项目字号及对应行高：
 使鼠标悬停时可以查看完整内容。动态文本使用 `:title` 绑定，组合文本应复用同一个格式化结果，
 确保页面显示内容与 `title` 完全一致。
 
-```vue
-<span class="truncate" :title="workspace.name">{{ workspace.name }}</span>
-<p class="line-clamp-2" :title="description">{{ description }}</p>
-```
-
 ## 样式实现优先级
 
 - 业务组件的布局、间距、尺寸、排版、颜色和常见交互状态优先使用 Tailwind 工具类。
@@ -154,14 +129,6 @@ CSS、SCSS 先按照 `/* button */`、`/* dropdown */` 等业务注释划分样
 同一业务分组内部的选择器按名称字母顺序排列；同一声明块内的属性按属性名字母顺序排列，
 CSS 自定义属性同样按变量名排序。嵌套选择器、伪类和媒体查询放在普通属性声明之后。
 
-示例：
-
-```vue
-<div class="flex-align-center gap-2 rounded-md px-3 py-2 text-N900 hover:bg-gray-100">
-  菜单项
-</div>
-```
-
 ## 常用布局工具类
 
 稳定重复使用的布局组合统一定义在 `tailwind.css`。当前提供：
@@ -176,41 +143,6 @@ CSS 自定义属性同样按变量名排序。嵌套选择器、伪类和媒体
 | `flex-column`       | Flex 布局，纵向排列，等价于 `flex flex-col`       |
 | `flex-wrap`         | 横向排列，自动换行，行间距为 8px                  |
 
-```vue
-<div class="relative h-40">
-  <div class="absolute-center">居中内容</div>
-</div>
-
-<div class="flex-align-center gap-2">
-  <span>图标</span>
-  <span>文字</span>
-</div>
-
-<div class="flex-between">
-  <span>左侧</span>
-  <span>右侧</span>
-</div>
-
-<div class="flex-center">
-  <span>居中内容</span>
-</div>
-
-<div class="flex-col-center">
-  <MkIcon name="icon_home_filled" />
-  <span>首页</span>
-</div>
-
-<div class="flex-column h-full">
-  <div class="shrink-0">头部</div>
-  <div class="min-h-0 flex-1">内容</div>
-</div>
-
-<div class="flex-wrap">
-  <span>选项一</span>
-  <span>选项二</span>
-</div>
-```
-
 普通布局中的 `flex items-center` 统一使用 `flex-align-center`；间距、尺寸继续组合原子类。
 该工具类仅设置 `display: flex` 和 `align-items: center`，不设置方向、主轴对齐或间距；
 `inline-flex items-center` 保留原写法，不替换为块级 Flex 布局。
@@ -237,12 +169,6 @@ CSS 自定义属性同样按变量名排序。嵌套选择器、伪类和媒体
 | 中（默认） | `mk-gray-card`    | 12px                | 6px  |
 | 小         | `mk-gray-card-sm` | 上下 8px、左右 12px | 12px |
 
-```html
-<div class="mk-gray-card-lg">大号卡片</div>
-<div class="mk-gray-card">中号卡片</div>
-<div class="mk-gray-card-sm">小号卡片</div>
-```
-
 符合以上规格的卡片直接使用对应类名，不再叠加 `p-4!`、`py-2!` 或 `rounded-xl!`。
 自定义工具的输出参数结果展示保留 6px 圆角，使用 `mk-gray-card-sm rounded-md!`。
 
@@ -255,20 +181,11 @@ CSS 自定义属性同样按变量名排序。嵌套选择器、伪类和媒体
 禁用样式添加 `disabled`，标题、Markdown 正文和辅助文字使用 N400 浅灰色；此类只改变展示，
 悬停时背景和边框不变色，保留选中和操作交互，实际禁用行为由使用方控制。
 
-```html
-<el-card class="mk-paragraph-card disabled" shadow="never">禁用的段落内容</el-card>
-```
-
 ## 阴影
 
 大号阴影统一由 `variables.scss` 中的 `--mk-box-shadow-lg` 定义，值为
 `0 6px 24px 0 rgb(var(--mk-N900-rgb) / 8%)`。`tailwind.css` 将其映射为 `shadow-lg`，
-业务模板直接使用该工具类，悬停效果使用 `hover:shadow-lg`：
-
-```html
-<div class="shadow-lg">常驻阴影</div>
-<div class="hover:shadow-lg">悬停阴影</div>
-```
+业务模板直接使用该工具类，悬停效果使用 `hover:shadow-lg`。
 
 普通 CSS/SCSS 使用 `box-shadow: var(--mk-box-shadow-lg)`。Element Plus 卡片的常驻、
 悬停和焦点阴影复用该变量。现有 `shadow-sm`、`shadow-md` 分别保持映射到
@@ -283,47 +200,20 @@ CSS 自定义属性同样按变量名排序。嵌套选择器、伪类和媒体
 该类由 `app.scss` 统一设置整行宽度、自适应高度、文字换行和左右间距；卡片边框与选中状态
 仍由外层卡片控制。
 
-```vue
-<el-card>
-  <el-radio :value="option.value" class="mk-card-radio">
-    <h6>{{ option.label }}</h6>
-    <span class="mt-1 block text-sm text-N600">{{ option.description }}</span>
-  </el-radio>
-</el-card>
-```
-
 `group-hover-visible` 用于列表项、卡片等父级带有 `group` 的悬浮操作区。操作区默认透明且不响应
 鼠标事件；距离操作区最近的 `group` 悬浮或内部获得焦点时显示并恢复交互，外层 `group` 不会越过
 内层 `group` 触发操作区。该工具类只负责显隐，布局继续由使用方组合。
 
-```html
-<div class="group">
-  <div>始终显示的内容</div>
-  <div class="group-hover-visible ml-auto flex-align-center">悬浮操作</div>
-</div>
-```
-
 ## 状态圆点
 
 成功与失败状态的圆点样式统一由 `app.scss` 提供。根据业务状态使用 `mk-dot-success` 或
 `mk-dot-danger`，文字和圆点的布局继续由使用方通过 Tailwind 组合。
 
-```html
-<span class="inline-flex items-center gap-2">
-  <span class="mk-dot-success"></span>
-  <span>成功</span>
-</span>
-```
-
 ## 进行中动态点
 
 进行中状态文案使用全局 `mk-dotting` 类，通过 `::after` 生成循环变化的省略号。类名直接放在
 文案元素上，不额外添加仅用于点号的空节点；伪元素预留固定宽度，避免动画过程中正文位置抖动。
 
-```html
-<span class="mk-dotting">下载中</span>
-```
-
 ## Tailwind 中的 `p`（padding）
 
 - Tailwind 默认间距标尺中，`1` 个单位等于 `0.25rem`。
@@ -333,16 +223,7 @@ CSS 自定义属性同样按变量名排序。嵌套选择器、伪类和媒体
 在 Sass/CSS 中覆盖 Element Plus 等第三方组件时，属性值能够自然对应 Tailwind 4px 基础
 间距刻度时使用 `--spacing` 计算，包括 `padding`、`margin`、`gap` 以及基于间距刻度的
 宽高。设计稿明确给出的 5px、7px、9px、11px、13px、18px、34px 等非 4px 整数倍值直接
-使用 `px`，不要为了使用 `--spacing` 而换算成小数倍数。例如：
-
-```scss
-.example {
-  gap: calc(var(--spacing) * 2);
-  min-width: calc(var(--spacing) * 20);
-  padding: 7px calc(var(--spacing) * 3);
-}
-```
-
+使用 `px`，不要为了使用 `--spacing` 而换算成小数倍数。
 圆角、边框宽度、字体尺寸、阴影偏移等不使用 Tailwind spacing scale 的固定尺寸使用 `px`；
 零值直接写 `0`，不要写 `0px`。
 
@@ -382,13 +263,6 @@ Tailwind 类。
 | `N900`      | `--mk-N900` | `text-N900` | 默认文字、主要内容   |
 | `N600`      | `--mk-N600` | `text-N600` | 提示、说明和描述文字 |
 
-示例：
-
-```html
-<p class="text-N900">默认正文</p>
-<p class="text-N600">提示或描述信息</p>
-```
-
 这里描述的是一般使用原则；如果 Figma 对具体组件给出了明确颜色标注，应以对应原型为准。
 
 ### 主题色
@@ -397,16 +271,7 @@ Tailwind 类。
 颜色配置使用 RGB 通道字符串，模板通过 `rgb()` 设置原色、`rgba()` 设置浅色背景。
 卡片背景由上层半透明渐变和下层白色渐变组成，CSS 背景列表中前面的图层位于上方。
 
-当前主题色为：
-
-```scss
-:root {
-  --mk-primary: #3370ff;
-  --mk-primary-gradient-end: #7f3bf5;
-  --mk-primary-gradient: linear-gradient(180deg, var(--mk-primary) 0%, var(--mk-primary-gradient-end) 100%);
-  --mk-primary-rgb: 51 112 255;
-}
-```
+默认主题色为 `#3370ff`，渐变终点为 `#7f3bf5`。
 
 修改主题色时，修改 `--mk-primary`。如果代码使用了 RGB 通道变量，也要同步修改 `--mk-primary-rgb`：
 `--mk-primary-gradient` 是 CSS 渐变背景入口，`--mk-primary-gradient-end` 是 SVG 渐变终点。
@@ -417,62 +282,27 @@ Tailwind 类。
 不要直接写这些变量，也不要绕过项目变量写入 Element Plus 的 `--el-*` 主题变量。Element Plus
 色阶继续由 `element-plus.scss` 基于 `--mk-primary` 映射生成。
 
-普通 CSS 中直接使用：
-
-```scss
-.link {
-  color: var(--mk-primary);
-}
-```
+普通 CSS 使用 `color: var(--mk-primary)`。
 
 ### Tailwind
 
-`tailwind.css` 通过 Tailwind v4 的 `@theme` 将项目颜色变量注册为 Tailwind 颜色：
-
-```css
-@theme {
-  --color-primary: var(--mk-primary);
-}
-```
+`tailwind.css` 通过 Tailwind v4 的 `@theme` 将项目颜色变量注册为 Tailwind 颜色。
 
 变量名称与工具类名称的对应关系如下：
 
-| Tailwind Token       | 来源变量       | 工具类后缀   |
-| -------------------- | -------------- | ------------ |
-| `--color-mk-primary` | `--mk-primary` | `mk-primary` |
-
-`--color-*` 注册后可以组合生成文字、背景、边框、轮廓等颜色工具类：
+| Tailwind Token    | 来源变量       | 工具类后缀 |
+| ----------------- | -------------- | ---------- |
+| `--color-primary` | `--mk-primary` | `primary`  |
 
-```html
-<div class="bg-primary text-white">确认</div>
-<a class="text-primary">链接文字</a>
-<div class="border border-primary">主题色边框</div>
-<input class="outline-primary" />
-```
+`--color-*` 注册后生成 `text-primary`、`bg-primary`、`border-primary` 等颜色类。
 
-交互状态直接添加 Tailwind 状态前缀：
+交互状态使用 `hover:`、`focus:` 等 Tailwind 前缀。
 
-```html
-<div class="bg-primary hover:bg-primary/90 focus:ring-2 focus:ring-primary">确认</div>
-```
+在颜色类后添加 `/透明度`，例如 `bg-primary/10`、`border-primary/30`。
 
-在颜色类后添加 `/透明度`，可以使用主题色叠加透明效果：
+任意透明度使用 `bg-primary/[0.08]` 等写法。
 
-```html
-<div class="bg-primary/10">10% 主题色背景</div>
-<div class="border border-primary/30">30% 主题色边框</div>
-<span class="text-primary/70">70% 主题色文字</span>
-```
-
-透明度也可以使用任意值：
-
-```html
-<div class="bg-primary/[0.08]">8% 主题色背景</div>
-```
-
-业务组件优先使用这些语义类，不要直接写颜色值：
-
-````
+业务组件优先使用这些语义类，不要直接写颜色值。
 
 ### 默认边框色
 
@@ -485,29 +315,12 @@ Tailwind v4 的 `border` 只设置边框宽度和样式，不提供 `--tw-border
 
 ### Tailwind 渐变背景
 
-渐变值属于背景图片，不能注册到只接受普通颜色的 `--color-*` 命名空间。需要使用 `--background-image-*`：
-
-例如：
-```css
-@theme {
-  --background-image-layout-gradient: var(--mk-layout-gradient);
-}
-````
+渐变值属于背景图片，不能注册到只接受普通颜色的 `--color-*` 命名空间。需要使用 `--background-image-*`。
 
-注册后通过 `bg-layout-gradient` 使用：
-
-```html
-<div class="bg-layout-gradient">页面布局</div>
-```
+`layout-gradient` 当前映射仅为注释，不能当作可用工具类。
 
 `--mk-primary-gradient` 在默认主题下是渐变、非默认主题下是纯色，不能注册为只生成
-`background-image` 的 Token。项目通过自定义 Utility 使用 `background` 简写同时兼容两种值：
-
-```css
-@utility bg-primary-gradient {
-  background: var(--mk-primary-gradient);
-}
-```
+`background-image` 的 Token。项目通过 `bg-primary-gradient` Utility 的 `background` 简写兼容两种值。
 
 需要主题渐变或主题纯色自动切换的背景统一使用 `bg-primary-gradient`。
 
@@ -548,48 +361,16 @@ Steps 默认使用数字和标题横向排列，并保留 Element Plus 的 `acti
 Drawer 的 `header` 插槽内时，组合 `absolute-center` 和宽度工具类即可相对完整 Header 居中，
 不受左侧标题和右侧关闭按钮影响。
 
-```vue
-<el-steps :active="0" class="absolute-center w-75!">
-  <el-step title="选择供应商" />
-  <el-step title="添加模型" />
-</el-steps>
-```
-
 图片预览遮罩 `.el-image-viewer__mask` 统一使用 `var(--el-overlay-color-lighter)`，
 并将元素 `opacity` 设为 `1`，避免与背景色自身透明度叠加；与媒体预览遮罩保持一致。
 
 ### 普通 CSS 中叠加透明度
 
-使用 `color-mix()`，只依赖一个主题色变量：
-
-```scss
-.selected {
-  background: color-mix(in srgb, var(--mk-primary) 10%, transparent);
-  border-color: color-mix(in srgb, var(--mk-primary) 30%, transparent);
-}
-```
-
-需要明确的 RGB alpha 写法时，可以使用 RGB 通道变量：
-
-```scss
-.selected {
-  background: rgb(var(--mk-N600-rgb) / 10%);
-}
-```
-
-### 后续切换主题
-
-主题通过覆盖 `--mk-*` 变量实现，业务组件、Tailwind 和 Element Plus 会同步更新。
-
-## 修改后检查
+使用 `color-mix(in srgb, var(--mk-primary) 10%, transparent)`。
 
-完成配置或样式修改后运行：
+RGB alpha 写法使用 `rgb(var(--mk-N600-rgb) / 10%)`。
 
-```bash
-npm run type-check
-npm run build-only
-npm run build-only-chat
-```
+主题切换通过上述 Theme Store 统一更新，业务组件不重复维护变量。
 
 ## 排行名次
 
diff --git a/ui/src/utils/UTILS_README.md b/ui/src/utils/UTILS_README.md
index e95305d5d4b..6eee82432ce 100644
--- a/ui/src/utils/UTILS_README.md
+++ b/ui/src/utils/UTILS_README.md
@@ -84,13 +84,10 @@ MkTable、MkFormList 的排序优先使用其公开属性；普通列表再直
 
 ## 资源上下文
 
-`application`、`knowledge`、`model`、`tool` 是使用资源上下文的四类特殊资源。工作空间 id 和这
-四类资源的当前路由范围统一通过 `resource-context.ts` 读取。Workspace API、权限等非组件代码使用
-`getWorkspaceId()` 获取当前工作空间；页面和组件使用 `isWorkspaceResource()`、
-`isWorkspaceSharedResource()`、`isSystemResource()`、`isSystemSharedResource()` 区分 Workspace
-普通资源、Workspace 共享资源、System 资源管理和 System 共享资源。`isWorkspaceResource()` 仅匹配
-`workspace`，不包含 `workspace-shared`。资源范围只读取路由 `meta.resourceScope`，不要根据 path 或路由名称重复判断，也不要把这些
-判断扩展到普通 System 页面。
+资源范围定义见 [ROUTE_README.md](../router/ROUTE_README.md#资源范围判断)。
+`resource-context.ts` 提供 getWorkspaceId、getResourceScope 和四种 isXxxResource 判断。
+非组件代码通过 getWorkspaceId 获取工作空间；页面／组件通过现有判断读取当前资源范围。
+isWorkspaceResource 仅匹配 workspace，不包含 workspace-shared；未配置范围时不推测来源。
 
 ## VNode 插槽内容判断
 
@@ -107,15 +104,6 @@ MkTable、MkFormList 的排序优先使用其公开属性；普通列表再直
 确认操作统一按需导入 `MsgConfirm(title, message, options?)`，默认提供确认、取消按钮和
 warning 类型；输入和普通警告弹窗继续直接使用 `ElMessageBox`。
 
-```ts
-/** 提供跨页面复用的数组处理函数。 */
-
-/** 根据指定字段对数组进行去重。 */
-export function uniqueBy() {
-  // ...
-}
-```
-
 ## 文件类型与图标
 
 `icon.ts` 的 `getFileExtension()` 返回不含点号的大写后缀，无有效后缀时返回空字符串。
diff --git a/ui/src/views/VIEW_README.md b/ui/src/views/VIEW_README.md
index b628ed8bca3..cb03e3082f2 100644
--- a/ui/src/views/VIEW_README.md
+++ b/ui/src/views/VIEW_README.md
@@ -1,1569 +1,250 @@
-# views 目录说明
-
-本文档是页面职责和页面功能代码组织规则的唯一依据。新增、移动、删除页面，改变页面职责，或
-调整页面专用代码的位置前，应先阅读并同步更新本文档。
-
-## 放置规则
-
-- 创建、保存或提交表单时，使用页面／弹窗内容容器的 loading 遮罩，或仅使用提交按钮的 loading，
-  不使用 `el-form.disabled` 或给每个字段、子表单逐项传入提交状态的 `disabled`。
-  方法入口保留重复提交保护，关闭、取消及步骤切换仍可按提交状态禁用；权限、只读、字段联动和
-  选项加载等业务禁用条件继续保留，不与提交 loading 混用。
-
-- 当前新增功能暂不接入前端权限判断，包括按权限隐藏入口、禁用控件或拦截操作，等待用户明确
-  指令后再增加。已有功能的权限逻辑不随新功能开发移除；导入或创建后的用户资料刷新继续保留。
-- `views/<feature>/` 是页面功能边界。每个独立功能页面使用自己的目录，路由页面和该页面专用
-  代码放在同一目录或其子目录中，不要把多个无关页面平铺在上级目录。
-- 路由级 Vue 组件统一命名为 `index.vue`。一个功能目录只有一个入口页时直接使用
-  `views/<feature>/index.vue`；同级存在多个入口页时，先按业务职责拆分子目录，再在各自目录中使用
-  `index.vue`，例如 `system/resource-management/model/index.vue` 与
-  `system/resource-management/tool/index.vue`。
-- 页面按钮组件遵循 [COMPONENT_README.md](../components/COMPONENT_README.md) 的 `Button` 前缀命名规则，
-  文件名、导入名和模板引用保持一致。
-- 页面拆分出的普通子组件统一放在当前功能目录的 `components/` 中，不与路由页面或 Drawer
-  混放。属于同一业务流程的入口、Dialog 和配套组件可以使用职责明确的业务目录集中维护，例如
-  `create-application/`；Dialog 文件使用 `PascalCase` 并以 `Dialog.vue` 结尾。
-- 页面使用的 Drawer 放在当前功能目录中，文件使用 `PascalCase` 并以 `Drawer.vue` 结尾，
-  例如 `AddMemberDrawer.vue`。Drawer 不放入 `components/`。
-- `action-dropdown/` 目录目前只优先用于 `application`、`knowledge`、`model`、`tool` 四类特殊
-  资源，用于维护跨 Workspace、System 资源管理或 System 共享资源复用的卡片 Action。其他业务
-  暂不主动创建这类目录，操作入口和配套流程优先留在所属页面或组件中；出现明确的跨范围共享需求
-  后再评估是否采用相同结构。按明确需求，文档页使用 `knowledge-detail/library/document/action-dropdown/`
-  集中维护行操作、批量操作及其专属弹窗；分段页按明确需求使用 `document-detail/action-dropdown/`，
-  按迁移和生成问题分组维护批量按钮与单项菜单 Action，不因此扩展其他普通页面的目录规则。
-- 仅供一个页面使用的代码放在该页面功能目录；同一功能下多个页面复用的代码放在它们最近的
-  共同功能目录中。
-- 不要为了复用一个页面内部实现而提前移动到 `src/components`。
-- 页面类型的归属和复用遵循 `src/api/API_README.md`；API 与页面共用的业务类型从
-  `@/api/types` 导入。页面常量可使用 `constants.ts`；其他逻辑文件应按具体职责命名，避免
-  `helpers.ts` 等含义模糊的名称。
-- 只有代码确实跨多个功能复用时，才按对应专项规则上移到 `src/components`、`src/constants`、
-  `src/utils`、`src/stores` 或 `src/api`。
-- 所有使用 `src/workflow-canvas/` 渲染画布的路由页面统一放在 `views/workflow/`。这些页面负责
-  路由参数、页面头部、保存或发布等页面动作以及后续接口编排；LogicFlow 初始化、节点注册和
-  画布内部行为遵循 `src/workflow-canvas/WORKFLOW_README.md`，不移入 View。
-- 页面目录存在多个层级时，目录名应表达业务层级，例如
-  `system/identity/groups/index.vue`，不要创建无业务含义的分组目录。
-- 页面脚本中的状态、计算属性和处理方法按照同一业务流程集中放置，并使用简短的业务备注划分
-  列表查询、批量操作等流程。流程较长的函数应在确认、请求、刷新等关键阶段添加说明，重点解释
-  Promise 返回、执行顺序和业务约束，不为含义明确的单行代码逐句添加注释。
-- 同类业务页面的模板必须在各操作入口前添加简短的中文 HTML 备注，覆盖顶部操作、行操作、
-  更多菜单项和批量操作，例如 `<!-- 导入用户 -->`、`<!-- 创建用户 -->`、`<!-- 编辑 -->`、
-  `<!-- 修改用户密码 -->`、`<!-- 更多 -->`、`<!-- 删除 -->`、`<!-- 批量设置角色 -->`。
-  备注紧邻对应按钮、菜单项或封装后的入口组件；批量操作明确标注“批量”，名称按实际业务职责
-  填写。今后新增或调整同类页面时统一补齐，不因操作已封装为组件或按钮已有文案而省略。
-- 下拉菜单中包含自带 Dialog 或 Drawer 的 Action 时，使用公共组件的延迟保留机制：
-  `MkTableMoreDropdown` 和资源卡片菜单默认启用，直接使用 `MkDropdown` 时传入 `persistent`。
-  公共组件在首次展开后保留菜单，页面不自行维护菜单挂载状态或通过 `visible-change` 控制保留。
-  仅调用页面方法、且浮层挂载在菜单外的操作不需要保留菜单。
-- Dialog 生命周期遵循 `COMPONENT_README.md` 的挂载方式规则：常驻实例在 `closed` 清理，
-  关闭后卸载的实例依赖重新初始化，`open()` 不重复清空，只处理业务回填和查询。
-- 页面模板的事件绑定不直接调用 Dialog、Drawer 等组件实例暴露的 `open()` 方法。应在对应业务
-  流程的方法区域定义语义明确的 `handleOpenXxx` 处理函数，由处理函数调用组件实例的 `open()`，
-  模板只绑定该处理函数；创建和编辑共用同一浮层时，可通过处理函数的可选参数区分操作场景。
-- 表单联动或请求明确由当前组件的用户交互触发时，优先绑定组件的 `change` 等语义事件，并在
-  `handleXxxChange` 方法中处理副作用，不使用 `watch` 间接监听同一个 `v-model`。只有变化来源不
-  受当前组件事件控制时，例如监听父级 Props、异步配置或多个响应式来源，才使用 `watch`。
-
-参考结构：
-
-```text
-src/views/<feature>/<page>/
-├── index.vue                     # 路由级页面
-├── FeatureEditDrawer.vue         # 页面抽屉，统一以 Drawer.vue 结尾
-├── components/                   # 页面拆分出的普通子组件
-│   └── FeatureSetting.vue
-├── create-feature/               # 创建流程的入口、弹窗和配套组件
-│   └── CreateFeatureDialog.vue
-└── constants.ts                  # 仅供该功能使用的常量
-```
-
-不需要为了匹配示例创建空目录；有对应代码时再创建。
-
-## 四类特殊资源
-
-`application`、`knowledge`、`model`、`tool` 是需要同时支持 Workspace 普通资源、Workspace 共享资源、System 资源管理和
-System 共享资源的四类特殊资源。它们统一遵循以下页面组织规则：
-
-- 可跨范围复用的资源卡片保留在对应基础资源目录的 `<resource>-card/` 中；System 页面复用该
-  卡片，不在 `views/system/` 复制展示组件。
-- 卡片负责展示、固定的卡片内交互以及 `actions`、`action-dropdown` 等组合插槽，不读取路由
-  Scope，也不自行选择 API；固定交互需要请求时，使用页面传入的完整业务 API 对象。
-- 页面根据当前 `resourceScope` 组合本场景需要的 Action，并显式传入中文 `label`、当前资源数据和
-  完整业务 API 对象；不在 Card 内维护菜单数组或 API Map。
-- 多个范围共用的 Action 跟随基础资源卡片维护；仅供 Workspace 使用的 Action 留在对应基础资源
-  目录；仅供 System 资源管理或 System 共享资源使用的 Action 放在对应 System 页面功能目录的
-  `<resource>-card/action-dropdown/`。
-- 单文件菜单 Action 直接放在 `action-dropdown/`；包含专属 Drawer、Dialog 或其他配套文件的 Action
-  使用 `<action-name>-action/` 业务目录。专属浮层点击时按需挂载，并在 `closed` 后卸载；多个 Action
-  共用的浮层才提升到最近共同功能目录。
-
-资源卡片的共享外壳使用全局自动注册的 `MkSourceCard`，模板无需手动导入。其操作插槽约定
-以 `../components/COMPONENT_README.md` 为准；各资源的业务 Card 与 Action 继续显式导入。
-
-这套资源范围规则只适用于上述四类特殊资源，不扩展到普通 System 设置、身份管理或其他页面。
-
-当前智能体列表按卡片展示、菜单 Action 和页面批量流程分层维护：
-
-```text
-src/views/application/
-├── index.vue
-├── application-card/
-│   ├── ApplicationCard.vue        # 智能体卡片展示、选择状态和 Action 插槽
-│   └── action-dropdown/
-│       ├── index.ts
-│       ├── DeleteApplicationAction.vue
-│       ├── ExportApplicationAction.vue
-│       ├── MoveApplicationAction.vue
-│       ├── SettingApplicationAction.vue
-│       └── TriggerApplicationAction.vue
-├── create-application/
-│   ├── AdvancedCreateDialog.vue      # 高级智能体创建弹窗
-│   ├── CreateApplicationDropdown.vue # 简易、高级和导入创建入口
-│   └── SimpleCreateDialog.vue        # 简易智能体创建弹窗
-└── template.ts
-
-src/views/application-detail/
-├── index.vue                      # 提供工作空间智能体详情上下文并组合资源详情布局
-├── context.ts                      # 智能体详情子路由共享数据与刷新能力
-├── overview/
-│   └── index.vue                    # 智能体概览内容
-└── setting/
-    └── index.vue                    # 简易智能体设置内容
-```
-
-`ApplicationCard` 只维护展示内容、批量选择状态和 `action-dropdown` 插槽；`ApplicationView` 组合
-设置、触发器、移动、导出和删除 Action，并管理批量选择、批量移动和批量删除流程。需要请求的 Action 接收
-页面传入的完整 Application API。单项移动在具体目录中通过 `delete` 通知页面局部移除卡片，在
-“全部智能体”中保留卡片；移动弹窗复用公共 `MoveToDialog`。非批量选择状态点击卡片时，卡片通过
-`click` 事件通知 `ApplicationView` 进入详情路由。`WorkspaceApplicationDetail` 返回列表时根据详情的
-`folder` 字段写入 `folderId` query，由 `FolderTree` 恢复所属文件夹；列表切换文件夹时只清除该
-query，不写入新的文件夹 ID，进入详情时也不携带该 query。`WorkspaceApplicationDetail` 负责工作
-空间智能体详情上下文，共享的返回入口、二级导航和右侧子路由结构由
-`layout/ResourceDetailLayout.vue` 维护。详情子路由通过
-`useApplicationDetailContext()` 读取只读详情；接口返回完整详情时调用 `replaceApplicationDetail()`
-局部替换，接口只返回布尔值或部分数据时调用 `refreshApplicationDetail()` 重新获取详情。切换二级
-菜单不会重新挂载详情容器，也不会自动重复请求详情。
-
-`application/components/ButtonCreateApplication.vue` 支持通过 `trigger` Prop 配置下拉触发方式，
-默认为 `click`，传入 `hover` 时悬停展开，也支持响应式切换；同名 `trigger` 插槽用于自定义触发内容，
-自定义触发区域统一使用全宽和手型光标。
-
-工作流模板中心的公共 UI 放在 workflow 下，application、knowledge 列表与工作流分别提供业务入口：
-
-```text
-src/views/workflow/components/template-store/
-├── TemplateStoreDialog.vue        # 模板列表、搜索、加载及空状态
-├── TemplateStoreDetailDrawer.vue  # 模板详情与使用入口
-└── components/
-    └── TemplateCard.vue           # 模板卡片及详情抽屉的按需挂载
-```
-
-公共组件接收 `WorkflowStoreTemplate`，不调用 API、不依赖资源创建弹窗。
-`TemplateStoreDialog` 接收 `templates`、`resource`、`loading`；`resource` 为
-`application` / `knowledge` / `tool`，只决定卡片与详情图标。通过 `open()` 打开并发送空关键词
-`search`，名称搜索发送去除首尾空格后的关键词；使用模板统一发出 `use(template)`。
-列表平铺模板，不展示分类导航、锚点或分类文字。`loading` 期间禁止搜索和使用，成功后由业务入口
-调用 `close()`；取消或失败保留模板中心。详情在关闭动画结束后卸载。
-
-`application/components/ButtonTemplateStore.vue` 调用智能体模板查询接口，整理描述字段，
-记录打开时的目标 `folderId`，收到 `use` 后按需挂载 `AdvancedCreateDialog`。
-创建弹窗关闭后卸载，取消创建时保留模板中心；创建成功沿用原流程进入智能体工作流。
-`create-application/AdvancedCreateDialog.open(template?)` 同时承接普通高级创建与商店模板创建。
-传入模板时回填名称、描述，隐藏内置模板选择并提交 `work_flow_template`；无参数时保留空白和知识库问答助手选择，
-提交 `work_flow` 及开场白。创建成功刷新用户基础资料并进入智能体工作流，提交期间禁止重复提交与关闭。
-`ApplicationView` 在批量选择按钮之后、创建入口之前组合 `components/ButtonTemplateStore.vue`，
-传入当前文件夹 ID，批量选择模式下隐藏。
-
-`workflow/application/ButtonTemplateStore.vue` 负责工作流页按钮、模板查询和弹窗实例，
-通过 `v-model:loading` 与页面共用加载状态，查询和应用模板均使用该状态；
-发出 `open`、`use`，通过 `close()` 供 View 在应用成功后关闭。View 负责覆盖确认、提交模板及重载画布。
-`workflow/tool/ButtonTemplateStore.vue` 使用相同的公共 UI，查询工具工作流模板接口并整理描述字段。
-工具 View 在确认覆盖后提交 `work_flow_template`，重新加载工具与工作流详情，更新默认模型、画布和
-保存基准，成功后关闭模板中心；打开模板中心时关闭调试。
-`workflow/knowledge/ButtonTemplateStore.vue` 按相同边界查询知识库模板，由知识库 View 确认覆盖、重载详情并关闭弹窗。
-
-知识库列表按相同方式维护卡片、菜单 Action 和批量流程：
-
-```text
-src/views/knowledge/
-├── index.vue
-├── knowledge-card/
-│   ├── KnowledgeCard.vue
-│   └── action-dropdown/
-│       ├── index.ts
-│       ├── EmbeddingKnowledgeAction.vue # 提交知识库向量化任务
-│       ├── GenerateQuestionsAction.vue # 知识库生成关联问题
-│       ├── sync-knowledge-action/       # Web 知识库同步入口与方式选择弹窗
-│       ├── KeywordIndexKnowledgeAction.vue # 分词索引入口
-│       ├── McpConfigKnowledgeAction.vue # MCP 配置查询、展示与复制
-│       ├── ExportKnowledgeAction.vue    # Excel、文档 ZIP 与知识库包导出
-│       ├── MoveKnowledgeAction.vue
-│       └── DeleteKnowledgeAction.vue
-├── components/
-│   ├── ButtonCreateKnowledge.vue        # 知识库创建菜单与弹窗入口
-│   └── ButtonTemplateStore.vue          # 知识库模板中心与模板创建入口
-├── create-knowledge/
-│   ├── CreateBaseKnowledgeDialog.vue     # 通用知识库创建
-│   ├── WebKnowledgeDrawer.vue            # Web 站点配置与两步创建抽屉
-│   ├── CreateLarkKnowledgeDialog.vue     # 飞书应用配置与创建
-│   ├── CreateWorkflowKnowledgeDialog.vue # 工作流知识库创建
-│   └── components/
-│       └── KnowledgeBaseForm.vue         # 名称、描述与 Embedding 模型表单
-└── template.ts
-```
-
-`KnowledgeCard` 只负责展示、选择状态和 `action-dropdown` 插槽；页面传入完整 Knowledge API，
-组合单项转移、删除 Action，并管理批量选择、全选、批量转移与批量删除。工作空间共享知识库保持只读，
-不传操作插槽并传入 `disabled`；System 共享知识库页传入 `shared`、不传 `disabled`，保留共享标识，
-并组合同步、向量化、生成问题、设置、分词索引、MCP 配置、关联资源、导出及删除等菜单操作。
-`GenerateQuestionsAction` 在非共享知识库菜单提供“生成问题”，复用公共
-`GenerateQuestionsDialog`，打开时固定知识库 ID，提交知识库生成接口；共用页面 loading，
-成功提示并关闭，失败保留表单。不新增权限判断。
-`EmbeddingKnowledgeAction` 在非共享知识库菜单中提供“向量化”，接收完整 Knowledge API，
-直接调用 `putReEmbeddingKnowledge`，提交成功后提示“提交成功”；复用页面操作 loading，
-阻止重复提交并在请求结束后恢复，不额外增加权限判断或配置弹窗。
-`SyncKnowledgeAction` 仅在非共享 Web 知识库菜单展示，不增加权限判断。专属弹窗按需挂载、
-关闭后卸载，默认“增量同步”，也支持“替换同步”和“整体同步”；增量同步提示跳过未更新文档、
-更新已变更文档的分段，其他方式展示数据覆盖提示；调用
-`putSyncWebKnowledge`，成功提示“同步任务发送成功”并关闭。复用页面操作 loading，
-提交期间禁止重复提交和关闭，失败保留弹窗与当前选择。
-设置菜单由 Workspace、System 资源管理和 System 共享知识库列表各自使用 `MkDropdownItem` 渲染，
-通过页面的 `handleOpenKnowledgeSetting` 跳转，不单独封装 Action，也不新增权限判断。
-通用类型进入各自的 `workspace-knowledge-setting`、`system-resource-knowledge-setting`、
-`system-shared-knowledge-setting`，其他类型进入对应前缀的 `knowledge-base-setting`。
-三个入口均传入知识库 ID 和 `KNOWLEDGE_TYPE_MAP[knowledge.type]`；仅 Workspace 传入当前
-`workspaceId`。点击阻止事件冒泡，避免同时进入卡片详情；Workspace 共享知识库仍不展示操作菜单。
-“设置”之后依次组合 `KeywordIndexKnowledgeAction` 和 `McpConfigKnowledgeAction`，接收完整
-Knowledge API 并复用页面操作 loading。分词索引不增加确认弹窗，调用成功后只提示“操作成功”；
-`McpConfigKnowledgeAction` 内直接查询 MCP 配置字符串，通过 `MkDialog` 只读展示并提供悬浮复制，
-配置为空时禁用复制，关闭动画结束后清理配置；弹窗外壳由 `MkDialog` 按需挂载和卸载。
-两者接口暂为本地占位，MCP 返回空文本，分词索引模拟成功，尚不执行服务端操作。
-`ExportKnowledgeAction` 接收完整 Knowledge API，暂不增加权限判断；悬停“导出”展开右侧
-子菜单，分别导出文档 Excel、文档 ZIP 和可再次导入的知识库包。
-导出复用页面操作 loading，防止重复请求，结束或失败后恢复；共享知识库不展示该入口。
-子菜单使用默认挂载方式，不查询父级浮层或指定 `append-to`；Action 不额外解析下载错误并弹出提示。
-切换文件夹退出批量模式，搜索或刷新列表清空选择。转移复用公共 `MoveToDialog`：单项飞书知识库
-调用 `putLarkKnowledge`，其他类型调用 `putKnowledge`，只提交 `folder_id`；成功后通过 `move`
-更新卡片所属目录，在具体目录转出时通过 `delete` 移除卡片，在全部目录或转入当前目录时保留。
-批量转移与删除使用对应批量接口，成功后退出选择模式并刷新列表。
-
-`knowledge/components/ButtonTemplateStore.vue` 在非共享、非批量选择模式下展示于创建入口前，
-查询知识库模板并记录打开时的目标文件夹。选择模板后按需挂载 `WorkflowKnowledgeDialog`，
-回填模板名称与描述，仍需选择向量模型；提交沿用 `work_flow_template`。创建成功关闭模板中心、
-刷新列表并进入知识库工作流，取消创建保留模板中心；创建弹窗在 `closed` 后卸载。
-
-`WebKnowledgeDrawer` 使用底部两步抽屉，基本信息校验后进入文档处理策略，支持返回修改。
-`create-knowledge/components/DocumentStrategyForm.vue` 维护分段、视觉增强和标题问题索引，
-通过 `doc_strategy` 提交；智能分段默认策略与后端一致，高级分段使用与触发器类型相同的卡片外壳，
-在选中卡片内展开配置，默认选择一级至四级标题标识、500–4096 分段长度、256 子块长度并开启自动清洗。
-分段标识支持自定义正则表达式，留空使用后端默认规则；启用视觉增强后必须选择模型或工具。
-表单挂载时不请求视觉选项；开启视觉增强、切换增强策略或回填已启用的策略时，模型增强只加载
-视觉模型和供应商，工具增强只加载工具。两类请求分别维护 loading，模型刷新只请求模型及供应商。
-视觉模型和工具选项按当前资源范围选择 Workspace、System 资源管理或 System 共享资源的完整 API，
-通过 `isSystemResource()`、`isSystemSharedResource()` 判断，供应商继续使用共用 Provider API。
-
-`ButtonCreateKnowledge` 内聚四类创建浮层 Ref 和打开动作，列表页传入目标 `folderId`，通过
-`refresh` 刷新列表。入口支持 `trigger` 插槽替换默认创建按钮，下拉使用 `persistent`。默认使用
-Workspace 知识库 API；System 共享知识库页传入完整 System 共享知识库 API，创建、导入与工作流创建
-均不读取工作空间 ID。创建入口及模板中心只接收一个完整 Knowledge API，工作流创建也使用该对象的
-`postKnowledgeWorkflow`；已创建知识库的工作流画布接口仍由 `workspace/knowledge/workflow.ts` 维护。
-各创建浮层接收 `folderId`，通过 `open()` 打开；工作流额外接受可选的商店模板。共用的
-`KnowledgeBaseForm` 负责名称、描述、Embedding 模型必填校验以及工作空间和共享模型查询，
-根据资源范围在组件内部选择模型接口：System 资源管理使用 System Model API，
-System 共享使用 System 共享 Model API，Workspace 普通与共享资源均使用 Workspace Model API，
-通过 `getModelListWithShared({ model_type: 'EMBEDDING' })` 加载模型选项；
-Workspace 普通与共享场景均合并当前工作空间模型与已授权共享模型，
-复用 `SelectModel`，允许创建模型后刷新选项。Web、飞书的特有字段留在对应弹窗中。
-模型加载后仅在未选择时默认选中首个可用模型；重置表单时恢复该默认值，无可用模型时保持为空。
-刷新选项不覆盖用户选择或设置页回填的模型。
-创建前校验表单，提交期间禁止重复提交和关闭；成功后刷新用户基础资料并通知列表刷新，
-普通类型将接口返回的 `knowledge.type` 通过 `KNOWLEDGE_TYPE_MAP` 转为字符串后进入文档列表，工作流进入画布。常驻弹窗在关闭动画结束后清理表单，打开时只回填本次模板与显示，工作流模板使用
-`cloneDeep` 隔离；创建流程默认使用 Workspace API，不通过路由字符串推测 System 范围；System
-共享页通过入口显式传入对应 API，创建成功后仅刷新共享列表，不进入工作空间详情或工作流路由。
-飞书创建沿用扩展接口 `/lark/save`，部署环境需要提供该接口。
-“导入创建”沿用智能体和工具的菜单文件选择交互，调用 `postKnowledgeImport` 上传文件及当前
-`folderId`，导入成功后先刷新用户基础资料，再通知知识库列表刷新。上传期间禁止重复导入，
-请求结束后清理文件列表，允许重新选择同一文件；文件内容由后端校验。
-
-当前工具页面按工具类型组织维护表单，共用的参数和代码设置保留在
-`tool-form/component/` 中：
-
-```text
-src/views/tool/
-├── index.vue
-├── components/
-│   ├── ButtonCreateTool.vue     # 工具创建入口
-│   └── ButtonToolStore.vue    # 工具商店入口
-├── tool-form/                     # 各类型工具创建、编辑表单
-│   ├── DataSourceFormDrawer.vue
-│   ├── McpFormDrawer.vue
-│   ├── SkillToolFormDrawer.vue
-│   ├── WorkflowFormDialog.vue
-│   ├── component/                 # 工具表单共用片段
-│   │   ├── init-field/
-│   │   ├── input-field/
-│   │   └── python-code/
-│   └── tool-custom/
-├── tool-card/
-│   ├── ToolCard.vue               # 工具卡片展示与操作插槽
-│   ├── InitParamDialog.vue        # 配置工具启动参数
-│   ├── ToolStatusSwitch.vue       # 工具启停及启动参数配置入口
-│   ├── ButtonUpdateVersion.vue    # 根据页面传入的商店数据检测并更新工具版本
-│   └── action-dropdown/           # 工作空间工具菜单 Action
-│       ├── index.ts
-│       ├── CopyToolAction.vue
-│       ├── DeleteToolAction.vue
-│       ├── EditToolAction.vue
-│       ├── ExportToolAction.vue
-│       ├── ExecutionRecordToolAction.vue
-│       ├── InitParamAction.vue
-│       ├── MoveToolAction.vue
-│       ├── ToolWorkflowAction.vue
-│       └── McpConfigAction.vue      # MCP 配置查询、展示与复制
-└── tool-store/                    # 工具商店列表、详情与添加流程
-    ├── component/
-    │   └── ToolStoreCard.vue      # 商店工具卡片及详情、添加入口
-    ├── StoreToolFormDialog.vue    # 商店工具应用表单及提交
-    ├── ToolStoreDetailDrawer.vue  # 商店工具详情
-    └── ToolStoreDialog.vue        # 商店分类、查询及添加成功后的列表刷新
-```
-
-`tool-card/action-dropdown/ExecutionRecordToolAction.vue` 维护执行记录入口，两个抽屉
-`ExecutionRecordDrawer.vue` 和 `ExecutionDetailDrawer.vue` 统一放在 `workflow/tool/execution-record/`。
-Workspace 的自定义工具和工作流工具菜单
-展示“执行记录”，页面传入工具的完整 Workflow API；点击后挂载抽屉，关闭动画结束后卸载。
-列表使用 `MkComplexSearch`、`MkTable` 和 `MkStatusLabel`，支持触发来源名称、类型、状态筛选；
-接口按执行时间倒序返回。详情保留输入、输出、错误及工作流节点详情，支持上一条／下一条跨页浏览。
-
-`ToolCard` 仅在非 `disabled`、非批量选择模式下发出 `click` 事件。`ToolView` 点击工作流工具进入
-工作流画布（支持 Ctrl / Command 新标签页打开），其他类型复用编辑 Action 打开对应表单。
-`EditToolAction` 通过 `defineExpose` 暴露 `handleOpenToolForm()`；列表按工具 ID 保存组件 ref，
-卡片点击通过 ref 调用，与编辑菜单共用同一表单实例，保存后继续局部更新卡片。
-
-各类型表单只维护本类型特有字段和流程，并统一放在 `tool/tool-form/`；创建入口和编辑 Action
-共同复用这些表单。启动参数、输入参数、Python 内容等已有表单片段应从
-`tool/tool-form/component/` 复用，
-不在类型目录中重复实现。`ToolCodeGenerate` 的生成入口默认隐藏，只由普通自定义工具表单通过
-`showGenerate` 显式开启。`python-code/CodeGenerate.vue` 直接复用公共业务组件
-`GenerateContent`，在普通编辑区及放大编辑器的 `header-extra` 插槽提供生成入口，
-不再单独封装 Python 生成组件。`ToolFormDrawer` 只绑定代码并传入完整 `toolForm`，不管理生成弹窗。
-`CodeGenerate` 内部按当前资源范围选择 Tool/Model API，从 `toolForm` 读取工作空间及参数定义，
-打开时复制启动参数与输入参数。表单中的 `workspace_id` 仅供生成时筛选模型，保存工具前移除。
-`CodeGenerate` 维护模型选择、参数设置、v2 工具代码模板及 `generate_code` 请求载荷，通过
-`request` 属性提供请求函数、`header-extra` 插槽放置模型选择；替换时移除外层 Python Markdown
-代码围栏，普通编辑区直接回写表单草稿，放大编辑器通过 `header-extra` 的 `replaceCode` 回调
-替换全屏草稿，点击“确定”后再同步表单。公共组件统一处理 `ConversationStream`、停止、重新生成和输入交互，
-不接收工具表单、不判断资源范围，不维护原始输入、暂停或继续状态。
-
-`ToolFormDrawer` 通过 `MkEditAvatar` 暂存确认后的头像文件；保存校验通过后先调用 Admin
-`postUploadFile`，将返回地址写入 `toolForm.icon` 再提交工具。恢复默认时直接提交空字符串，
-未更换图片时不上传；上传失败保留文件供重试，上传成功后清空暂存文件，避免工具保存失败后重复上传。
-
-工具列表页面通过 `ToolCard` 的 `actions` 和 `action-dropdown` 插槽组合
-操作；编辑 Action 负责按 `TOOL_TYPE` 打开对应类型表单，启动参数 Action 获取工具详情后打开
-`InitParamDialog`，`McpConfigAction` 获取 MCP 工具详情后，在 Action 内通过 `MkDialog` 只读展示
-`code ?? ''` 并提供悬浮复制，配置为空时禁用复制，关闭动画结束后清理配置。
-弹窗外壳由 `MkDialog` 按需挂载和卸载。工作流 Action 进入
-独立的工具工作流画布；创建工作流工具后直接进入该画布，其他类型表单创建成功后通过 `refresh`
-事件刷新列表。编辑成功后通过 `update` 事件返回接口响应的完整工具数据，由页面局部更新对应卡片；不要
-把不同工具类型的字段重新合并到一个通用表单中。所有调用 `postTool` 创建工具的流程在接口成功后
-先调用 `auth.loadAuthBaseProfile()` 刷新当前用户基础资料，再执行成功提示以及列表刷新或工作流页面
-跳转；`putTool` 编辑流程不触发该刷新。跨资源范围复用且需要请求的 Action 和表单接收页面传入的完整 Tool API，不额外
-维护逐方法接口类型；`ApplyStoreToolDialog` 内聚商店应用请求，提交时通过
-`isSystemSharedResource()` 选择 System 共享资源或 Workspace 的 Tool API 和 Tool Store API，
-覆盖工作流模板及商店工具两个分支；历史内置工具由 ToolStore 提供，不再从数据库加载。
-工具启用状态由 Workspace 工具页和 System 共享工具页通过 `ToolCard` 的 `actions` 插槽组合
-`ToolStatusSwitch`，页面直接传入对应 Tool API 和操作 loading，并通过 `update` 事件替换列表数据。
-`ToolCard` 不再接收 Tool API，仅提供操作插槽；版本更新仍通过卡片的 loading 和 update 通道处理。工具批量选择状态、
-批量移动和批量删除流程由 `ToolView` 管理；`MoveToolAction` 复用公共 `MoveToDialog` 完成单个工具移动，
-在具体目录中通过 `delete` 通知页面局部移除卡片，在“全部工具”中保留卡片。`ToolCard` 只把选择模式与选中状态传给 `MkSourceCard`。
-工具商店列表由 `ToolView` 统一加载并经 `ToolCard` 传给 `ButtonUpdateVersion`，卡片和更新按钮
-不重复请求商店列表。`ToolStoreCard` 负责卡片展示与详情抽屉的按需挂载；卡片和详情中的
-“应用”操作统一通过 `apply(tool)` 交给 `ToolStoreDialog`。
-`ToolStoreDialog` 管理一份 `tool-store/StoreToolFormDialog.vue`，应用时按需挂载并传入目标
-`folderId`，关闭动画结束后卸载；应用成功后关闭商店并发出 `refresh` 通知页面刷新。
-`StoreToolFormDialog` 保留表单校验、各工具类型的提交请求及提交状态管理，根据打开时的新增或编辑
-上下文完成请求。新增成功发出无数据的 `refresh` 事件；编辑成功通过 `update` 返回接口响应的完整工具数据。
-
-System 共享资源页面统一放在 `views/system/shared-resources/`。页面负责 System 范围的资源查询、
-筛选和页面动作；资源卡片、供应商列表等可复用展示能力继续使用对应 Workspace 功能目录中的
-组件，不在共享资源目录复制实现。两个页面共用的资源卡片 Action 跟随对应 Workspace 功能维护；
-只被 Workspace 页面使用的 Action 保留在 Workspace 功能目录，只被 System 共享资源页面使用的
-Action 放入 `views/system/shared-resources/<card-name>/action-dropdown/`。Action 目录结构遵循单文件
-扁平放置、多文件使用 `<action-name>-action/` 的规则，对应的菜单文案由使用页面通过 `label` 显式传入。
-
-```text
-src/views/system/shared-resources/
-├── knowledge/
-│   └── index.vue
-├── model/
-│   └── index.vue
-└── tool/
-    └── index.vue
-```
-
-`ToolSharedView` 使用 System 共享工具 API，复用 `ToolCard` 和编辑、启动参数、MCP 配置、
-导出、删除 Action。列表使用 `MkInfiniteScroll` 分页加载，支持类型、名称和创建者筛选；
-创建与删除后重新查询，编辑和启停成功后替换对应卡片数据。
-`ButtonCreateTool` 可接收完整 `api`，默认使用 Workspace Tool API；`showWorkflow` 默认开启，
-共享页开启工作流创建，创建后进入 `system-shared-workflow-tool`。共享页支持普通工具、Skills、MCP、数据源及
-导入创建，工作流卡片点击进入画布（支持 Ctrl / Command 新标签页），编辑菜单仍修改基础信息。共享页不组合工作空间专用的移动、授权和触发器入口。
-
-`KnowledgeSharedView` 使用 System 共享知识库 API，复用 `KnowledgeCard`、创建入口和模板中心。
-卡片点击通过页面的 `handleOpenKnowledge` 进入 `system-shared-knowledge-detail`，
-携带知识库 ID 和由 `KNOWLEDGE_TYPE_MAP` 转换的类型。资源管理知识库表格在向量化按钮旁组合
-`icon_admin_outlined` 详情按钮，进入 `system-resource-knowledge-detail`。两个入口不携带 Workspace ID。
-创建、模板创建和导入均使用 System 共享接口；Web 同步、向量化、关联问题、分词索引、
-MCP 配置、关联资源、导出与删除通过复用 Action 组合，设置菜单由页面直接跳转到 System 共享设置页。
-授权工作空间暂保留 TODO，不组合工作空间专用的文件夹移动或批量操作。
-
-System 用户页面按业务流程归拢操作入口和专属 Dialog。入口组件管理弹窗 Ref、打开动作并转发
-`refresh`；列表页负责查询、批量选择和刷新策略，创建与编辑共用的 `UserFromDrawer` 仍由页面管理。
-
-```text
-src/views/system/identity/users/
-├── index.vue
-├── UserFromDrawer.vue
-├── components/
-│   └── UserGroupSetting.vue
-├── import-users/
-│   ├── ButtonImportUsers.vue
-│   └── ImportUsersDialog.vue
-├── user-password/
-│   ├── ButtonChangeUserPassword.vue
-│   └── UserPwdDialog.vue
-└── batch-set-user-role/
-    ├── ButtonBatchSetUserRole.vue
-    └── BatchSetUserRoleDialog.vue
-```
-
-`system/chat/users/` 同样使用 `import-users/`、`user-password/`，批量用户组设置放在
-`batch-set-user-group/`（`ButtonBatchSetUserGroup.vue` 与 `BatchSetUserGroupDialog.vue`）；
-单人和批量配额设置统一放在 `quota-settings/`（`ButtonQuotaSettings.vue` 与
-`QuotaSettingsDialog.vue`）。配额入口通过 `dropdown` 区分行菜单与批量按钮，传入单个用户 ID
-或选中用户 ID 数组。行操作菜单开启 `persistent`，避免菜单关闭时卸载其内部的配额弹窗。
-两套用户页面保留各自业务 API 和导入成功后的查询刷新方式。
-
-`system/identity/workspaces/index.vue` 的成员表按用户合并选择框、姓名和用户名，
-通过 `MkTable.selectionGroupKey="user_id"` 联动当前页同一用户的角色记录；
-行标识仍使用 `user_relation_id:role_id`，底栏按选中记录行数统计，不按用户数统计。
-批量移除确认说明记录数与涉及用户数，请求按 `user_relation_id` 去重，不按用户 ID 丢弃角色记录。
-列表加载前清空选择，覆盖搜索、分页、工作空间切换及操作后的刷新；不新增跨页选择或修改接口协议。
-
-操作日志页面的清除策略入口与弹窗统一放在 `system/operate-logs/clean-strategy/`：
-`ButtonCleanStrategy.vue` 管理打开动作和弹窗 Ref，`CleanStrategyDialog.vue` 负责策略查询与保存，
-`index.vue` 只组合入口组件。
-
-资源授权页面的 `UserGroupAuthorizationList` 通过人数链接打开共享业务组件
-`components/business/resource-authorization-drawer/user-group/UserGroupMembersDrawer.vue`，按用户组所属工作空间查询成员，提供姓名、用户名搜索、用户来源表头筛选和分页，
-并使用 `MkTagGroup` 折叠展示角色；点击人数不切换当前授权对象。
-
-## 文件命名
-
-| 文件职责     | 命名格式                            | 示例                                |
-| ------------ | ----------------------------------- | ----------------------------------- |
-| 路由页面     | `index.vue`                         | `system/identity/users/index.vue`   |
-| 抽屉         | `XxxDrawer.vue`                     | `AddMemberDrawer.vue`               |
-| 弹窗         | `XxxDialog.vue`                     | `CreateOrUpdateWorkspaceDialog.vue` |
-| 页面普通组件 | 按具体业务职责使用 `PascalCase.vue` | `UserGroupSetting.vue`              |
-
-不要使用缺少组件职责后缀的页面文件名，也不要把 Dialog 命名为 Drawer 或把 Drawer 命名为
-Dialog。新增或重命名文件时，应同步更新所有导入和页面功能登记。
-
-## 页面功能登记
-
-| 页面                                            | 功能说明                                                             |
-| ----------------------------------------------- | -------------------------------------------------------------------- |
-| `application/index.vue`                         | 工作空间智能体目录与智能体卡片页面                                   |
-| `application-detail/index.vue`                  | 工作空间智能体详情上下文与资源详情布局                               |
-| `application-detail/overview/index.vue`         | 智能体概览内容                                                       |
-| `application-detail/setting/index.vue`          | 简易智能体设置内容                                                   |
-| `workflow/application/index.vue`                | 智能体工作流页面头部与全屏画布                                       |
-| `workflow/knowledge/index.vue`                  | 知识库工作流加载、自动保存、发布历史、模板覆盖、导出、调试与全屏画布 |
-| `workflow/tool/index.vue`                       | 工具工作流页面头部与全屏画布                                         |
-| `chat/index.vue`                                | Chat 入口的对话页面                                                  |
-| `error/index.vue`                               | Admin 未匹配路由和全局 404 页面                                      |
-| `home/index.vue`                                | Workspace 首页                                                       |
-| `knowledge/index.vue`                           | 工作空间知识库目录与知识库卡片页面                                   |
-| `knowledge-detail/index.vue`                    | 知识库详情页面                                                       |
-| `knowledge-detail/external-retrieval/index.vue` | 外部检索服务开关、API 地址与调用示例、MCP 配置的只读展示及复制       |
-| `knowledge-detail/library/tags/index.vue`       | 标签分组查询、创建、重命名、单值编辑、删除与关联文档管理             |
-| `knowledge-detail/workflow-transform/index.vue` | 非工作流知识库转换说明、确认与进入画布                               |
-| `document-detail/index.vue`                     | 普通 Workspace 文档分段查询、目录定位、批量操作、新增、编辑与详情    |
-
-|
-| `knowledge-detail/setting/base/index.vue` | 知识库基本信息、来源配置与上传限制设置 |
-| `knowledge-detail/setting/document-strategy/index.vue` | Web 知识库文档处理策略回填、校验与保存 |
-| `knowledge-detail/setting/scheduled-sync/index.vue` | Web、飞书与工作流知识库定时同步设置与日志 |
-| `login/index.vue` | Admin 登录页面 |
-| `login/forgot-password/index.vue` | 忘记密码页面 |
-| `model/index.vue` | 工作空间模型目录与模型卡片页面 |
-| `system/identity/groups/index.vue` | 用户组列表页面 |
-| `system/identity/resource-authorization/index.vue` | 工作空间用户组与用户的分类资源授权页面 |
-| `system/identity/roles/index.vue` | 角色列表页面 |
-| `system/identity/users/index.vue` | 用户列表页面 |
-| `system/identity/workspaces/index.vue` | 工作空间列表页面 |
-| `system/chat-management/user-groups/index.vue` | 对话用户组及组成员管理页面 |
-| `system/chat-management/users/index.vue` | 对话用户列表、配额及用户导入管理页面 |
-| `system/chat-management/portal-setting/index.vue` | 门户基本信息、访问开关、认证配置、跨域地址编辑与门户预览 |
-| `system/settings/theme/index.vue` | 系统外观设置和登录外观预览页面 |
-| `system/settings/authentication/index.vue` | 系统登录及认证源配置页面 |
-| `system/settings/email/index.vue` | 系统邮件 SMTP 服务配置页面 |
-| `system/operate-logs/index.vue` | 系统操作日志查询与清理页面 |
-| `system/resource-management/model/index.vue` | System 模型分页、筛选、编辑、授权与删除 |
-| `system/resource-management/tool/index.vue` | System 工具分页、筛选、维护与工作流入口 |
-| `system/shared-resources/model/index.vue` | System 共享模型查询与模型卡片页面 |
-| `system/shared-resources/tool/index.vue` | System 共享工具查询与工具维护页面 |
-| `trigger/index.vue` | 工作空间触发器查询、新建、编辑及单项和批量启停、删除 |
-| `tool/index.vue` | 工作空间工具目录与工具卡片页面 |
-
-身份与权限用户组页（`system/identity/groups/index.vue`）的成员顶部搜索仅提供用户名、姓名；
-用户来源使用 `MkTableFilter mode="single"` 放在表头，与搜索条件合并后向接口传 `source`。
-筛选变化回到第一页；选择“全部”移除来源条件，保留用户名、姓名搜索。
-
-## 备注要求
-
-门户设置的 `components/ButtonEditPortal.vue`、`ButtonPortalAuthSetting.vue` 和
-`ButtonPortalCorsSetting.vue` 分别封装对应按钮、浮层及表单状态，通过 `disabled` 接收页面统一的
-编辑限制。页面使用 `perm.system.portal.edit()` 判断门户编辑权限，无权限时禁用配置、复制按钮、
-访问开关及浮层表单和按钮，保存入口同步校验权限。认证组件使用 `MkDrawer`，
-打开时与系统 `LoginSetting` 共用 `AuthSettingApi.getLoginSetting()`，通过返回的 `login_methods`
-生成登录方式选项，复用登录方式标签，初始保留账号登录。提供默认登录方式及验证码与账号锁定设置；默认方式
-仅可选已勾选项，取消勾选当前默认项时回退到首个可选项。认证组件暴露 `open()` 供首次开启认证
-时联动打开；当前认证配置仅保存到页面内存，取消不回写，刷新后恢复默认配置，待接口接入后持久化。
-跨域组件通过 `v-model` 接收地址数组，弹窗按一行一个地址编辑；保存时清理行首尾空白和空行，
-取消不回写，关闭后清理草稿。空数组表示不限制来源的配置意图；目前地址仅保存在页面内存，
-尚未对接 `cors_config` 或实际跨域策略。
-
-- 新增路由级页面时，必须在“页面功能登记”中添加一条简洁、明确的功能说明。
-- 页面职责改变、文件重命名或目录移动时，必须同步修改登记内容。
-- 对职责不直观的页面专用 TypeScript 文件，在文件顶部用一句话说明负责的业务领域和用途。
-- 注释说明“为什么”和业务约束，不重复描述能够从文件名、类型或代码直接看出的内容。
-
-## 登录页实现约定
-
-- Element Plus 登录表单通过 `formEl.validate((valid, fields) => {})` 回调处理校验结果。
-- LDAP 与本地账号登录保留清晰的条件分支，请求结果使用 `.then().catch()` 处理；未经明确要求，
-  不改写为 `try/catch` 或额外抽象登录提交流程。
-
-## 工作流页面布局
-
-`workflow/components/WorkflowViewLayout.vue` 由 `ApplicationWorkflowView`、`ToolWorkflowView` 和 `KnowledgeWorkflowView`
-共同使用，统一全屏容器、页面头部、返回按钮、标题和保存时间展示。通过 `loading`、`title`、
-`saveTime` 传入展示状态，点击返回按钮触发 `back` 事件。
-标题前的 `icon` 插槽由各页面分别传入 `ApplicationIcon`、`ToolIcon`、`KnowledgeIcon`，
-统一使用 32px 头像，并根据资源详情展示自定义图标或对应类型图标。
-
-`actions` 插槽用于默认模型设置、保存、调试等页面操作，默认插槽放置画布及页面浮层；画布继续使用
-`min-h-0 flex-1` 占满头部下方空间。页面保留画布 Ref、资源与模式配置、接口调用、保存和退出确认
-逻辑，布局组件只负责展示。添加组件入口由画布右上角的 `AddNode` 统一提供，页面不再转发节点选择事件。
-
-## 工作流自动保存
-
-`ApplicationWorkflowView` 使用 `workflowAutoSave:application:<applicationId>` 浏览器存储开关，
-`ToolWorkflowView` 使用 `workflowAutoSave:tool:<toolId>`，
-`KnowledgeWorkflowView` 使用 `workflowAutoSave:knowledge:<knowledgeId>`，按资源类型与资源 ID 独立记录，
-不读取旧的全局 `workflowAutoSave` 开关。默认关闭，开启后每
-60 秒检查并保存未保存的画布改动。加载、保存、发布、发布历史和退出确认期间跳过，关闭开关或卸载页面时
-清理定时器；仅开启时写入存储，关闭开关时删除当前资源的存储项。自动保存复用页面保存流程，不弹成功提示；成功更新保存时间和本次提交的图快照，
-失败保留未保存状态供后续周期重试。请求期间继续编辑的内容不会被标记为已保存。
-
-## 工作流发布历史
-
-`workflow/application/ButtonPublishHistory.vue` 封装智能体发布历史菜单入口、
-面板显隐、列表查询以及版本编辑请求。内部直接调用 application 的版本 API；页面仅传
-`applicationId`、`selectedId`、`disabled` 和 `visible`，接收 `update:visible`、`open`、`preview`、
-`restore` 事件。每次打开重新查询，编辑成功后关闭弹窗并重新调用 `getWorkflowVersions` 刷新列表，
-不向页面发送更新事件；保存失败保留弹窗与草稿。所在 `MkDropdown` 设置 `persistent`，避免收起菜单时销毁面板入口。
-
-`workflow/components/publish-history/PublishHistoryDrawer.vue` 为纯 UI 面板，接收 `versions`、`loading`、
-`saving`、`selectedId`，保留传入顺序并将首项标为“最近发布”，显示标题、发布人及创建时间。
-内部管理编辑与更新说明弹窗，通过 `submit(payload, versionId)` 交给业务组件保存，成功后由业务组件
-调用 `closeEdit()` 关闭编辑弹窗。通过 `preview`、`restore` 通知业务组件，不接收 API、不查询数据，
-也不操作路由或画布。面板复用 `MkDrawer`，通过 `v-model` 控制显隐，宽度 320，使用
-`top-header`、`h-layout-content` 留出页面头部，不显示遮罩、不锁定滚动，内部复用 Drawer 的滚动区。
-抽屉实例保留，由 `MkDrawer` 延迟渲染并在关闭动画结束后销毁内容，不再额外维护挂载状态或转发
-`close` / `closed` 事件。页面在 `update:visible` 事件与头部返回方法中统一处理显隐，关闭时立即恢复草稿并清理预览；
-恢复版本时先清空草稿快照再关闭，保留已恢复的版本。编辑弹窗的 `closeEdit()` 仅用于保存成功后关闭表单。
-
-同目录 `EditPublishVersionDialog.vue` 只维护表单副本与校验。`mode` 默认为 `edit`，显示“编辑”，
-通过 `open(version)` 回填；`mode="publish"` 显示“发布内容”，通过 `open()` 打开空白表单。通过
-`submit(payload)` 提交、`close()` 关闭，外部传入 `saving`。标题必填且最多 64 字，更新说明最多
-1000 字，标题拒绝纯空白；两种模式的提交按钮均显示“发布”。编辑请求由业务组件执行，
-不创建新发布；提交期间使用表单内容 loading 遮罩，保留关闭保护，不设置表单 disabled。
-`DescriptionDialog.vue` 通过 `open(content)` 展示纯文本更新说明并保留换行，空内容显示
-“暂无更新说明”。两个弹窗均不依赖业务 API，复用 `MkDialog` 的延迟挂载和关闭销毁能力。
-
-`workflow/tool/ButtonPublishHistory.vue` 为工具提供独立业务入口，调用工具 `tool_version` API，
-编辑成功后重新查询列表。复用 `PublishHistoryDrawer`、历史模式头部与预览/恢复交互。
-工具头部采用默认模型设置、带图标的保存、发布和更多菜单；更多菜单包含发布历史与自动保存。
-工具历史模式下返回仅退出预览，恢复版本回到编辑态后由手动或自动保存持久化；版本接口未返回
-默认模型配置，预览与恢复保留当前配置。
-`workflow/knowledge/ButtonPublishHistory.vue` 使用独立 `knowledge_version` API，复用相同 UI 和预览/恢复流程，
-编辑成功只重新查询列表；知识库版本同样不含默认模型配置，不引入通用 API 适配层。
-
-`ApplicationWorkflowView` 已接入更多菜单中的发布历史。打开时关闭调试，面板打开期间跳过
-自动保存；首次预览保留当前画布草稿，切换版本不覆盖草稿，关闭预览恢复原草稿。
-面板打开后头部保留智能体图标、名称与保存时间，操作区仅显示“恢复此版本”；未选择版本时禁用，
-选择版本后启用。通过历史面板关闭按钮或头部返回按钮退出历史模式，并恢复常规头部操作。
-这部分展示判断统一由 `WorkflowViewLayout` 的 `historyVisible`、`canRestoreVersion` Props 控制，
-点击恢复发出 `restoreVersion`，页面负责具体画布恢复。常规 `actions` 插槽使用 `v-show` 保留实例，
-避免历史模式下销毁菜单内的 `ButtonPublishHistory`。其他工作流不传这些 Props 时保持原头部展示。
-恢复版本只将历史图数据放回编辑态，不立即保存或发布，后续沿用手动与自动保存流程。
-服务端当前版本接口只返回工作流图，不返回历史默认模型设置，页面保留当前默认模型配置。
-更新说明使用 `description` 字段，服务端支持要求见 `../api/API_README.md`。
-
-## 工作流默认模型设置
-
-`workflow/components/default-model-setting/ButtonDefaultModelSetting.vue` 负责顶部“默认模型设置”按钮与抽屉按需挂载，
-由 `ApplicationWorkflowView` 在 `WorkflowViewLayout` 的 `actions` 插槽中接入。同目录的
-`DefaultModelSettingDrawer.vue` 负责抽屉、模型查询、暂存表单及应用与关闭确认。入口挂载后
-通过组件 Ref 调用 `open(settings)`；抽屉内部管理显隐，打开时先重置再回填配置，关闭动画结束后
-清理状态并触发 `closed`，入口据此卸载。保存事件由入口转发。抽屉复用 `MkDrawer`，
-顶部使用 `top-header` 留出页面头栏，高度使用
-`h-layout-content`，不显示遮罩，也不阻挡头栏和左侧画布交互。表单由抽屉统一滚动，页脚固定显示
-应用到所有节点、取消和保存。
-
-通过 `modelValue` 接收详情配置；`disabled` 控制顶部按钮。
-编辑及参数弹窗只修改抽屉副本，通过 `save(settings)` 提交副本；取消或关闭时选择不保存，
-直接丢弃副本，详情中的原配置不受影响。API 与组件共用的模型类别
-`DefaultModelType`、单项配置 `ModelConfig` 和按类别组织的 `DefaultModelSettingPayload` 维护在
-`api/types/model.ts`，避免在组件 Props、Emits 和状态中重复展开工具类型。
-`ApplicationWorkflowView` 用 `applicationDetail` 保存完整详情，用 `defaultModelSetting` 单独承接
-模型配置，在详情加载或保存成功后从接口的 `default_model_setting` 深拷贝回填，缺省为空对象。
-抽屉的 `save(settings)` 调用页面 `handleSaveDefaultModelSetting(settings)`，先暂存到
-`defaultModelSetting`，再复用 `handleSave()` 和 `saveApplication` 将配置与 `work_flow` 一起提交。
-页面顶部保存使用当前 `defaultModelSetting`；保存成功更新详情，失败则从详情深拷贝回滚配置，
-提示错误并继续抛出异常，阻止保存并退出、保存后调试等成功分支。
-点击保存后抽屉保持打开；`modelValue` 更新时刷新比较基准，`hasChanges` 自动重新计算。
-提交时比较基准会暂时更新，失败回滚后恢复；抽屉编辑副本不被覆盖，保存期间继续编辑的内容仍保留。
-页面将 `defaultModelSetting` 通过画布的 `defaultModelSettings` Props 传入，AI 对话节点通过节点 model
-获取当前 `LLM` 模型及参数；提交期间使用暂存配置，失败后随页面回滚，不通过 `provide` 同步抽屉草稿。
-
-模型查询通过必填的完整 `modelApi` 对象执行（类型使用 `typeof ModelApi`）；调用方负责选择 API，
-组件不从 URL 推断资源范围。每次打开或刷新只查询一次模型列表，保存在 `models` 中，由
-`getModelOptions(type)` 按 `model_type` 过滤。默认模型类型保留页面展示顺序，标签复用
-`MODEL_TYPE_LABELS`。供应商列表通过当前公共供应商接口查询。模型选择及参数设置复用
-`SelectModel`，通过 `canEditParams` 控制参数入口，重排序模型隐藏该入口。
-默认模型抽屉开启 `canAdd`，创建成功后通过 `refresh` 重新加载模型列表。
-
-入口接收 `getGraphData` 函数并传给抽屉。“应用到所有节点”确认后，抽屉调用该函数获取最新图数据，
-克隆后切换节点的模型来源，保留自定义模型 ID 和参数，递归处理循环体，并保留基本信息节点中
-关闭的语音/长期记忆配置及浏览器语音播放模式。存在变更时触发 `applyToAll(graphData)`，入口
-转发给 `ApplicationWorkflowView`，页面只负责通过自己的画布 Ref 渲染结果，抽屉不接收画布实例。
-`disabled` 同时控制顶部入口和应用操作，确认完成后再次检查，避免保存期间修改画布。
-该操作修改画布，由页面原有保存流程持久化，不自动提交抽屉内暂存的默认模型设置。
-
-## 模型创建入口
-
-`model/create-model/ButtonAddModel.vue` 和 `CreateModelDrawer.vue` 通过必填的 `api` 接收完整
-模型 API 对象。Workspace 模型页传入 `ModelApi`，System 共享模型页传入 `SystemSharedModelApi`；
-`SelectModel` 在 System 资源管理范围传入 `SystemModelApi`，复用同一创建流程。
-创建抽屉只调用传入的 API，不再自行判断资源范围。
-`ButtonAddModel` 默认渲染主按钮，也支持通过默认作用域插槽的 `open()` 定制触发按钮，
-`SelectModel` 的下拉页脚使用该插槽复用同一创建流程。创建成功后保留基础资料刷新，再触发
-`refresh` 通知调用方重新加载模型列表。
-
-## 资源授权 Action
-
-四类资源卡片的 `action-dropdown/` 分别提供 `AuthorizeModelAction`、`AuthorizeToolAction`、
-`AuthorizeKnowledgeAction` 和 `AuthorizeApplicationAction`，由列表页面组合，显式传入 `label`
-和当前资源，保存成功后通过 `refresh` 刷新列表。Action 使用对应资源的 Workspace 或 System
-`auth` 权限判断，共享资源不展示入口。点击后按需挂载公共 `ResourceAuthorizationDrawer`，
-传入资源类型及 `workspaceId` Prop（来自资源数据的 `workspace_id`），调用 `open(resource.id)`；
-Workspace 与 System 授权均使用该工作空间 ID，不读取路由工作空间。
-在 `closed` 后卸载，不再复制授权表格或请求逻辑。
-
-## 触发器维护
-
-`trigger/index.vue` 负责列表查询、当前页选择、单项启停/删除及批量操作，通过
-`trigger/trigger-form/TriggerFormDrawer.vue` 共用新建和编辑流程，编辑时查询详情并保留任务 ID、参数、
-启用状态及 meta。定时支持每日、每周、每月、间隔和五段 Cron；事件支持 URL、Token 和请求参数。
-任务选择复用 `SelectApplicationDialog` 与 `SelectToolDialog`，工具限定自定义和工作流类型。
-`trigger/trigger-form/request-parameters/RequestParameters.vue` 用 `MkTable` 展示事件请求参数，
-表格包含参数、数据类型、描述、必填开关和编辑/删除操作，标题栏的加号打开新增 Dialog，
-同目录 `RequestParameterDialog.vue` 负责新增、编辑及参数名必填与重名校验；确认后回写，取消保留原值。
-`trigger/trigger-form/task-execution/` 直接按三个场景组织任务执行组件：
-
-- `TriggerTaskExecution.vue`：触发器页面的多任务分组、选择、移除、折叠与校验；组件内管理
-  智能体和工具选择弹窗，使用 `v-model` 回写任务、`v-model:loading` 同步加载状态，提供 `validate`、`reset`。
-- `ToolTaskExecution.vue`：资源入口固定当前工具，只编辑参数，不允许增删或替换执行资源。
-- `ApplicationTaskExecution.vue`：资源入口固定当前智能体，遵循相同的单任务约束。
-- `TaskParameterForm.vue`：三个组件共用的参数表单，接收按资源类型区分的 `resource`，内部生成
-  智能体或工具字段，统一处理自定义输入、事件引用、默认值及校验；字段描述类型保留在文件内。
-
-参数初始化只补全缺失值，不覆盖已有自定义配置；切回定时或移除全部事件参数时，引用参数恢复自定义默认值。
-智能体包含 Question、启用的文件类型、用户输入和接口参数；工具包含普通输入和工作流用户输入。
-抽屉采用类型卡片选择，选中卡片内显示配置，触发周期与 Cron 通过切换按钮切换；新建时需选择周期。
-任务 UI 使用 `MkCollapse` 分组和紧凑资源卡片，保存前展开任务并校验所有参数，包括折叠的任务。
-`TriggerFormDrawer` 负责请求与保存，通过可选 `resource` 区分普通触发器和固定资源模式；
-资源模式使用传入的完整 `resourceApi`，将资源详情中的单任务转换为内部任务数组，保存时保留任务 ID 和参数。
-加载工具任务时补查完整工具详情和必要的工作流定义，避免后端摘要缺少工作流输入字段。
-接口失败保持抽屉打开并禁止提交不完整详情，提交期间禁止关闭抽屉。
-
-`trigger/resource-trigger/ResourceTriggerDialog.vue` 负责资源端的触发器列表弹窗，接收完整
-`ResourceTriggerApi` 和资源上下文（所属工作空间、资源类型、资源 ID），展示名称、周期和空状态。
-添加、编辑按需挂载 `TriggerFormDrawer`，保存成功刷新列表，抽屉关闭后卸载；移除调用资源关联删除接口。
-工具菜单的 `tool/tool-card/action-dropdown/TriggerToolAction.vue` 为自定义工具、工作流工具提供入口，
-智能体菜单通过 `application/application-card/action-dropdown/TriggerApplicationAction.vue` 提供相同入口，
-由 `ApplicationView` 传入完整 `ResourceTriggerApi` 和当前智能体，固定当前智能体为执行资源。
-两个入口均在点击后挂载列表弹窗，关闭后卸载，暂不增加权限判断。
-
-`trigger/components/TriggerTaskPopover.vue` 接收分页记录的 `tasks`，在任务列按智能体和工具
-展示数量标签，悬浮时分组显示资源图标及名称；无任务时显示 `-`，不发起额外请求。
-
-`trigger/execution-record/TriggerTaskRecordDrawer.vue` 通过列表操作列打开，负责执行记录分页、
-名称/状态/类型筛选、执行时间排序及跨页浏览。`ExecutionDetailDrawer.vue` 根据当前记录查询详情，
-展示智能体问答、工具输入输出、触发错误及工作流节点详情；状态展示通过共享 `EXECUTION_STATUS_OPTIONS` 向 `MkStatusLabel` 传入 `type + label`，筛选复用同一配置的文案。
-
-## 查看关联资源 Action
-
-模型、知识库、应用、工具卡片的 `action-dropdown/` 分别提供
-`RelatedResourcesModelAction`、`RelatedResourcesKnowledgeAction`、
-`RelatedResourcesApplicationAction`、`RelatedResourcesToolAction`，在更多菜单展示“查看关联资源”。
-工作空间列表保留已有入口行为；System 共享模型页增加该 Action，不新增权限判断。
-页面传入完整 `RelatedResourcesApi` 和当前资源。Action 点击后按需挂载
-`RelatedResourcesDrawer`，传入对应 `RESOURCE_TYPE` 和包含 `workspace_id` 的资源快照；
-工作空间 ID 来自资源数据，缺失时提示并停止打开，关闭后卸载抽屉。
-共享模型页只传入模型数据、文案和完整 System 共享关联资源 API，不传 `shared` 或工作空间显示标记。
-共享模型允许缺少 `workspace_id`；抽屉内部仅在 System 共享资源且为企业版或专业版时显示工作空间列与筛选。
-抽屉调用接口时不传工作空间 ID，
-Workspace API 内部通过 `getWorkspaceId()` 读取当前路由工作空间。
-模型及非工作流工具默认展示“引用此资源的资源”，其他资源默认展示“依赖的资源”。
-资源名称仅展示文本，暂不支持打开目标资源。
-
-知识库工作流页面使用 `WorkflowMode.Knowledge` 和 `WorkflowMode.KnowledgeLoop`，空画布使用本地文件数据源节点。
-页面只通过 `getKnowledgeDetail` 返回的 `work_flow` 加载画布数据，发布前先校验并保存；返回知识库详情时检查未保存改动。
-
-`KnowledgeCard` 在非批量选择模式下通过 `click` 通知列表进入知识库详情。
-`knowledge-detail/index.vue` 查询并展示知识库名称，复用
-`ResourceDetailLayout` 生成资料库、工作流、检索优化、授权与集成、设置目录，返回列表时恢复所属文件夹。
-资料库包含文档、图片、标签管理；检索优化包含召回测试、问题、自定义分词；授权与集成包含
-对话用户、外部检索服务。资料库页面统一放在 `knowledge-detail/library/` 下，包含 `document/`、
-`image/`、`tags/`；文档专属组件及 Action 随 `document/` 集中维护。其他页面继续放在
-`knowledge-detail/` 下的 `recall-test/`、`question/`、`dictionary/`、`chat-user/`、`external-retrieval/`。
-对话用户已实现按用户组查询及授权，接口与交互规则见“智能体与知识库对话用户”章节。
-容器通过 `knowledge-detail/context.ts` 装配资源范围、知识库 ID、设置所需的完整业务 API 对象和返回列表路由，
-并提供只读详情与替换能力。详情入口、setting 与 library 的 API 选择集中在该上下文。
-Action、Drawer、Dialog 可通过 props 接收完整 API；关联文档抽屉直接读取详情上下文中的 Document API。设置页复用已加载详情，保存成功后
-更新容器数据，同步名称等展示。基本信息复用创建流程的 `KnowledgeBaseForm`，类型配置和校验留在
-`setting/base/index.vue` 中，通用知识库标题为“设置”，其他类型为“基础设置”。
-通用知识库只有单个设置菜单；Web 的设置分组包含基础设置、文档处理策略、定时同步，
-飞书和工作流包含基础设置、定时同步。`setting/document-strategy/` 复用
-`DocumentStrategyForm`，通过 `setStrategy()` 回填详情的 `doc_strategy` 为独立草稿，
-通过 `validate()` 和 `getStrategy()` 校验并单独保存该字段。保存成功合并接口返回数据到详情上下文，
-失败保留草稿，保存期间使用内容容器 loading 遮罩和按钮 loading，不禁用表单字段。
-方法入口防止重复提交。标题栏通过 Teleport 展示下次同步生效说明，
-保存不立即发起同步。智能分段回填时保留高级分段的编辑默认值，提交仍使用智能分段的固定策略。
-`setting/scheduled-sync/` 维护“同步设置”和“同步日志”两个页签。进入页面和切换知识库时，
-通过 `SyncApi.getKnowledgeSyncSetting` 回填独立草稿，后台默认值为关闭、每日 01:00、增量同步。
-未读取成功前不允许保存默认草稿，重新进入页面可重试查询。
-同步周期复用 `el-cascader` 和 `SCHEDULE_OPTION`，支持每日、每周、每月、间隔和 Cron。
-周日期使用 1（周一）至 7（周日），同步间隔至少 5 分钟；前端校验周期，完整 Cron 校验由后台完成。
-保存使用内容 loading 与按钮 loading，入口防止重复提交，不禁用各表单字段。
-`putKnowledgeSyncSetting` 成功后，以后台返回值更新草稿和详情 `meta.sync_setting`；失败保留草稿。
-同步方式复用 `constants/knowledge.ts` 的 `KNOWLEDGE_SYNC_OPTIONS`，按当前来源描述三种方式。
-`components/SyncLogTable.vue` 在日志页签按需挂载，接收知识库 ID 和 `index.vue` 传入的完整同步 API 对象，
-通过 `api.getKnowledgeSyncLogPage` 调用分页日志接口；接口仅返回定时任务触发的记录，手动同步不写入此日志。
-日志表格沿用同步时间、同步内容、同步方式、同步状态、耗时五列，不新增操作入口。
-同步内容按“共 N 个文档（已同步、跳过、删除、失败）”展示，仅附加非零的跳过、删除和失败计数；
-跳过执行时直接展示原因，后台结果信息通过同步内容的悬停提示查看。
-状态复用 `MkStatusLabel`，同步中使用 `loading`，成功和失败分别使用 `success`、`failure`，
-不配置跳过状态；完整同步使用“完整同步”标签。
-进入日志页签、切换知识库和分页时查询，不做定时刷新。
-设置菜单的类型筛选由路由维护；基础设置和文档策略通过上下文接入 Workspace 与 System 管理接口，
-定时同步通过同步上下文接入四个资源范围的查询接口，Workspace 共享资源保持只读，不新增前端权限判断。
-更换向量模型需确认，先保存再重新向量化，整条流程禁止重复提交；向量化失败时保留原模型比较基准，
-允许再次保存重试。Web、飞书设置保留未编辑的 `meta` 字段，上传限制使用详情顶层值。
-`knowledge-detail/library/document/index.vue` 维护文档列表查询、多选和文档操作，使用 `MkComplexSearch`、`MkTable`。
-搜索只提供名称 `name` 和创建者 `create_user`；创建者通过 Workspace `CommonApi.getAllUsers`
-加载，支持按 `nick_name` 远程搜索。列表使用 `documentData`、`paginationConfig`、`documentQuery`，
-查询方法为 `loadDocuments`，搜索处理为 `handleSearchChange`，搜索变化后回到第一页。
-文档名称列显式导入非全局 `MkEditName`，名称上限 128 字符，保存成功后按文档 ID 更新当前行的
-名称与更新时间；失败交由组件保留草稿。共享文档只读展示名称，列不叠加表格溢出提示。
-名称校验通过 `validate` 回调拒绝 `: \ / ? * [ ]`，命中任一字符时弹出提示并阻止保存。
-
-文档页通过 `onMounted` 加载文档列表，创建者选项在展开下拉或输入关键词时通过 `remoteMethod`
-按需加载，不在进入页面时预加载；其他列表页的同类创建者筛选遵循相同方式。不额外监听路由重置状态。切换工作空间
-整页加载并返回知识库列表；当前知识库与共享资源入口均从其他页面进入，挂载时初始化筛选和分页。
-普通与共享文档列表沿用 v2 的 6 秒轮询间隔，在请求结束后安排下一次静默刷新，保留当前筛选、
-分页和勾选，不显示列表 loading；操作请求期间推迟轮询，失败后继续重试，卸载时停止且不再重新调度。
-无排序入口。非共享文档显示选择列，只支持当前页选择，翻页、切换每页条数、搜索或筛选变化时清空；
-选中后通过 `footer-batch-actions` 展示批量操作。右侧固定操作列提供启停、向量化、分词索引和更多菜单，
-运行或排队中的任务切换为取消入口。Web、飞书提供同步；工作流知识库仅为 `meta.source_type=web`
-的文档提供单项同步，沿原 Web 数据源分支执行提取、分段并只合并所选文档，不抓取链接或清理其他来源。
-手动同步通过工作流执行记录跟踪任务与合并结果，不写入定时同步日志。
-本地上传的工作流文档不提供同步入口。普通与工作流文档提供原文下载和替换。
-单项与批量操作共用页面请求状态，删除和同步先确认，成功后清空选择并刷新，导出和下载保留选择。
-文档页及其 Action 的知识库类型统一读取响应式路由参数 `route.params.type`，使用
-`KNOWLEDGE_TYPE_KEY` 判断，不从详情或文档数据读取类型，也不通过 `knowledgeType` Prop 传递。
-Web 来源地址与选择器仅在单项设置中编辑，批量设置不展示这两个字段。
-文档操作统一放在 `document/action-dropdown/`，通过该目录 `index.ts` 导出，页面显式组合各 Action。
-文档页行操作使用 `MkTableMoreDropdown` 默认的延迟保留机制，批量操作菜单显式设置 `persistent`；
-首次展开才挂载菜单内容，收起后保留 Action 及其弹窗，生命周期统一由公共组件管理。
-文档状态展示、筛选配置和任务运行状态判断统一维护在 `document/status.ts`。
-文档任务是否排队或执行中通过其中的 `isDocumentTaskRunning(document, taskType)` 判断，
-页面及 Action 不重复解析状态字符串；文档或任务状态缺失时返回 `false`。
-`EmbeddingDocumentAction` 负责单项向量化与取消向量化，`BatchEmbeddingAction` 负责批量向量化按钮，`GenerateQuestionsAction` 负责单项生成问题与取消生成，`BatchGenerateQuestionsAction` 负责批量生成问题，`SettingDocumentAction` 负责召回及来源设置，
-`MigrateDocumentAction` 选择目标知识库；`setting-tags/DocumentTagsAction.vue` 内部管理标签设置抽屉的挂载、打开和关闭。
-生成问题复用公共配置弹窗，其余 Action 按下文维护各自专属弹窗。组件接收完整 Document API、知识库 ID、文档 ID 或文档数组及禁用状态，
-点击时快照本次操作对象，内部管理弹窗和请求，成功后通过 `refresh` 通知页面刷新，失败保留输入。
-迁移操作集中在 `document/action-dropdown/migrate/`，`MigrateDocumentAction.vue` 负责入口与弹窗按需挂载，
-`DocumentMigrateDialog.vue` 负责目标知识库查询、选择及迁移请求；关闭动画结束后卸载，失败保留输入。
-Action 继续通过上层 `action-dropdown/index.ts` 导出，单项与批量入口共用；入口文案由必填 `label` 传入，
-图标由可选 `icon` 传入，不传时不显示图标。
-单项向量化仅传 `document`，内部判断排队或执行状态，固定展示行内图标按钮，分别调用单项向量化和取消接口。
-批量向量化仅传 `document-ids`，使用独立的 `BatchEmbeddingAction` 普通按钮；
-批量取消向量化继续使用 `BatchCancelTaskAction` 菜单项，单项和批量请求均通过 `v-model:loading` 共用页面操作状态。
-向量化相关文件集中在 `document/action-dropdown/embedding/`，包含两个 Action 和共用的 `DocumentEmbeddingDialog.vue`；
-Action 仍通过上层 `action-dropdown/index.ts` 导出，弹窗仅在目录内部使用，管理分段范围与确认事件，
-请求和成功关闭由各自 Action 负责；打开时快照文档目标，失败保留范围选择。
-生成问题相关 Action 集中在 `document/action-dropdown/generate-questions/`，通过上层 `index.ts` 导出。
-`GenerateQuestionsAction` 接收单个 `document`，内部判断任务状态并处理生成与单项取消，通过 `display` 区分菜单与图标按钮。
-`BatchGenerateQuestionsAction` 接收 `documentIds`，使用独立的批量生成按钮；批量取消继续使用 `BatchCancelTaskAction`。
-单项与批量复用公共 `GenerateQuestionsDialog`，Action 打开时保存知识库、文档 ID 快照，
-提交同一文档批量接口并通过 `refresh` 刷新状态；通过 `v-model:loading` 复用页面操作状态。
-公共弹窗按需挂载、关闭后卸载，不负责选择提交接口。段落页复用公共弹窗时关闭
-`showParagraphScope`，由段落按钮提交段落接口，不扩展公共弹窗的接口分支。
-设置操作集中在 `document/action-dropdown/setting/`，通过上层 `index.ts` 导出两个入口。
-`SettingDocumentAction` 接收单个 `document`，展示菜单项；`BatchSettingDocumentAction` 接收
-`documentIds`，展示批量设置按钮。入口文案由 `label` 传入，单项图标由可选 `icon` 传入。
-两个入口通过 `v-model:loading` 共用页面操作状态，打开时固定操作目标，分别调用单项和批量设置接口。
-共用的 `DocumentSettingDialog.vue` 负责表单回填、校验和提交数据，按需挂载、关闭动画结束后卸载；
-弹窗通过 `batch` 参数区分批量模式，批量入口显式传入；文档地址和选择器仅在 `!batch` 且为 Web 知识库时显示。
-单项保留文档原有 `meta`，批量使用默认配置并将 `allow_download`
-放在顶层。请求与成功关闭由 Action 负责，成功通知页面刷新，失败保留表单。
-标签操作集中在 `document/action-dropdown/setting-tags/`。`DocumentTagsDrawer.vue` 管理单篇文档的标签关联，
-由 `DocumentTagsAction` 按需挂载、关闭后卸载；仅提供添加、搜索、单值删除及批量删除，不提供编辑和分页。
-抽屉每次打开都查询最新关联；增删后立即刷新自身列表，Action 记录成功变更，关闭后再通过 `refresh` 通知文档页刷新。
-查询使用 `TagsApi.getDocumentTags`，搜索使用单一 `MkSearchInput`，通过 `change` 将关键词作为 `name` 请求接口，清空时省略该参数；
-查询前清除勾选，直接展示接口返回的分组，不再本地过滤。选择列和标签名单元格合并；
-通过 `MkTable selection-group-key="key"` 联动组内标签值，已选数量按标签值行数统计；标签值列复用 `border-l!` 展示与合并标签列之间的分隔线。
-单项及批量删除均直接调用 `putDeleteDocumentTags`，不弹二次确认；仅移除当前文档关联，不调用知识库标签删除接口。
-`AddTagDialog.vue` 为标签列、抽屉与批量操作栏共用的下拉式添加弹窗，接收完整 Tags API 和知识库 ID。
-三个入口分别由 `DocumentTags`、`DocumentTagsDrawer`、`BatchDocumentTagsAction` 管理弹窗实例，不通过页面 Ref 打开。
-候选项使用 `tagsApi.getKnowledgeTags`，按返回顺序截取前 100 个标签组，然后由 `el-select filterable` 本地搜索；
-右侧显示所选组的全部标签值，切换标签名清空本行标签值，不增加远程搜索或自动扩展候选范围。
-单篇与批量均允许选择已关联标签值和重复选择，不为禁选查询文档已有标签，也不区分 `batch` 模式。
-表单复用 `MkFormList`，至少一行，字段只做必填校验；提交前检查标签值归属，失效时用 `MsgError` 提示“请重新选择标签值”并保留选择。
-通过 `postBatchAddDocumentTags` 提交所选 ID，由后台去重并追加关联。
-下拉 footer 复用模型选择器的创建入口，直接打开输入式 `tags/components/CreateTagDialog.vue`；
-标签名入口调用 `open()`；标签值下拉始终可展开，未选标签时点击“创建标签值”也调用 `open()` 创建标签，
-已选标签时调用 `open(key)` 新增标签值，不合并两类弹窗的模式。
-弹窗每次打开都查询候选；内部创建成功后重载前 100 组候选，保留当前选择，不自动选中新数据。
-候选查询的 `queryLoading` 仅用于两个 `el-select` 的加载状态及下拉内创建入口禁用；表单遮罩、提交与取消只使用提交 `loading`。
-`BatchDocumentTagsAction.vue` 使用普通按钮外放在底部批量操作栏，内部按需挂载 `AddTagDialog`，打开时固定知识库和文档 ID，
-即使只勾选一篇，也按批量添加处理。添加成功后关闭并立即通知刷新；取消关闭时只通知卸载，不刷新。
-三个外层标签入口只通过 `refresh` 通知页面刷新，沿用文档列表原有轮询，不为标签浮层单独暂停。
-页面不持有标签浮层 Ref 或控制其挂载。标签维护入口通过上下文的完整写接口控制，
-目前仅 Workspace 普通资源提供维护 API；Workspace 共享只读，System library 的文档与标签 API 尚未提供，
-不显示维护入口，也不回退 Workspace 请求。
-分词索引集中在 `document/action-dropdown/tokenize/`：`TokenizeDocumentAction` 接收单个 `document`，
-按运行状态调用单项分词或取消接口；`BatchTokenizeAction` 接收 `documentIds`，仅调用批量分词接口。
-两个 Action 均处理全部分段状态，通过 `v-model:loading` 共用页面操作状态，成功后通知页面刷新。
-`BatchCancelTaskAction`、
-`ExportDocumentAction`、`DownloadDocumentAction`、`ReplaceDocumentAction` 和 `DeleteDocumentAction`
-分别负责任务取消、导出、下载、替换与删除，单项和批量入口复用对应组件。
-导出操作集中在 `document/action-dropdown/export/`，通过上层 `index.ts` 导出。
-`ExportDocumentAction` 接收 `label` 和单个 `document`；`BatchExportDocumentAction` 接收 `label`、
-`documentIds`。两个 Action 直接从路由读取 `knowledgeId`，批量 Action 从详情上下文读取知识库名称
-作为下载回退文件名，页面不再传 `knowledge-id` 或 `knowledge-name`。
-两个 Action 分别调用单项、批量的 Excel/ZIP 接口，批量仅选一个文档时仍调用批量接口。
-知识库类型仍只从路由读取。行操作与批量操作均只组合一个“导出”入口，
-悬停展开“导出文档 Excel”“导出文档 ZIP”，不再从页面传入 `format`。
-子菜单使用默认挂载方式，不指定 `append-to`；下载复用页面 loading，保留列表和勾选状态，
-不额外解析下载错误或提示成功，请求结束后统一恢复 loading。
-同步操作集中在 `document/action-dropdown/sync/`，通过上层 `index.ts` 导出。
-`SyncDocumentAction` 接收 `label` 和单个 `document`，`BatchSyncDocumentAction` 接收 `label` 和
-`documentIds`（模板使用 `:document-ids`），不使用 `documents` 或 `batch`。单项 Web 文档同步前校验来源地址；确认前固定本次目标与路由类型，
-分别调用 Web 或飞书的单项、批量同步接口；工作流 Web 文档复用单项接口，由后台启动工作流，
-确认内容说明沿原提取、分段配置同步，提交成功提示“同步任务发送成功”。共用页面 loading，成功后通知页面刷新。
-直接请求的 Action 通过 `v-model:loading` 共用页面操作状态，各 Action 自行管理请求、
-防重复提交、成功提示与失败处理，不额外抽取统一请求封装；需要刷新时发出 `refresh`，导出与下载不发出。
-`DeleteDocumentAction` 单个删除传 `document`，确认框展示文档名称并调用单个删除接口；
-批量删除传 `batch` 和 `document-ids`，确认框展示数量并调用批量删除接口。
-删除后分页总数和页码回退由页面重新查询服务端处理，不在 Action 中维护分页数据。
-启停开关直接使用页面内的 `el-switch`，由页面 `handleChangeActive` 管理请求，
-接口成功后刷新列表回显，不在请求前切换状态，不单独封装 Action。
-页面保留列表、多选、任务状态展示判断与刷新方法，不维护各 Action 的请求流程。
-`DocumentStatus` 和标签列组件 `DocumentTags` 继续留在 `document/components/`，后者同时管理本入口的添加弹窗。
-弹窗 Ref 和打开方法由对应 Action 或标签列入口组件维护，页面只传参、处理刷新。行内更多菜单使用 `MkTableMoreDropdown`；批量操作栏使用
-`MkDropdown` 搭配非 text 的 More 图标按钮和 `MkDropdownMenu`，点击展开。
-批量 More 开启 `hide-when-empty`，按标准菜单插槽判断空内容，不强制开启 `persistent`；不检查业务 Action 内部的条件渲染。
-不新增前端权限判断；Workspace 共享文档不展示选择列、操作列及批量操作，标签列保留禁用的添加按钮。
-文档分页接口维护在 `workspace/knowledge/document.ts`，页面管理 loading。文件状态表头使用
-`MkDropdown` 单选筛选全部、成功、失败、索引中、分词索引中、排队中和生成中；查询组合
-`status` 与可选的 `task_type`，切换选项清除旧任务类型并回到第一页，保留名称和创建者条件。
-
-文档详情页面及其专属组件统一放在 `views/document-detail/`，与 `knowledge/`、`knowledge-detail/` 平级。
-普通 Workspace 文档行点击进入 `document-detail/index.vue`，选择列、名称编辑及行操作
-保留自身交互。分段页与知识库详情容器路由同级，复用 `MkViewLayout` 的顶部栏、侧栏和主区滚动；
-顶部展示接口查询的文档名称、标题／内容搜索、批量选择和添加分段，主区使用 `MkInfiniteScroll`
-按组件配置的每页数量加载分段，显示接口返回的筛选结果总数。侧栏按服务端位置排列已加载分段，
-点击定位正文，滚动同步高亮；批量全选仅覆盖已加载分段，追加加载不清空已有勾选。
-搜索、新增后通过 `refreshParagraphs()` 重置到第一页，显示首次加载状态并回到顶部；
-编辑、启停局部替换卡片，删除、迁移局部移除，保留其他已加载数据和滚动位置。
-局部移除后，下一次滚动请求按剩余列表长度定位服务端分页，必要时拼接相邻两页，避免漏载。
-正文使用 `MdPreview`；第一页加载完成且无分段时展示空态。
-左侧目录和右侧卡片分别通过 `useSortable` 绑定同一份分段数组，拖拽图标使用与 `MkFormList`
-一致的 link 按钮、`text-N600` 和 `h-8!`。左右图标均仅在悬浮所属目录项／卡片或获得焦点时显示，
-绝对定位在所属目录项／卡片右侧并向外露出 8px，不占据布局空间；目录图标垂直居中。
-左右均可按住整条目录项／整张卡片或拖拽图标排序，只允许在已加载分段中排序。
-右侧整体过滤悬浮操作区，并过滤正文链接及拖拽图标以外的按钮，保留原有点击行为；
-普通点击卡片仍打开详情，位置保存期间不打开详情；左侧点击手柄不触发目录定位。
-左侧使用普通 `div.paragraph-directory-row` 作为排序行，手柄与 `ElAnchorLink` 并列。
-页面局部 `v-disable-link-drag` 指令将 `ElAnchorLink` 内部的 a 设为 `draggable=false`，
-不使用 `dragstart.prevent`，避免原生链接拖出浏览器，并让整条目录项正常参与 Sortable 排序。
-拖拽后两侧同步重排，通过目标分段原有的真实 `position` 提交位置接口，搜索不改变位置语义。
-成功后同步移动区间内已加载分段的 `position`，失败恢复原顺序；不重新查询或重置列表。
-批量模式、分段加载、删除确认或提交、弹窗打开、位置保存以及不足两条时禁用拖拽。
-拖拽和保存期间暂停滚动补页，保存时仅在标题栏显示状态，不使用整页 loading 遮挡落位动画；
-保存锁继续禁止再次拖拽和修改操作。与 `MkFormList` 一致，两侧使用普通 DOM 容器，
-右侧以普通 `div.paragraph-sort-row` 承载卡片，由 `useSortable` 统一提供 150ms 位移动画；
-不在可排序元素上叠加 `TransitionGroup`，也不直接对带默认过渡样式的 `ElCard` 做位移动画。
-批量选择支持点击整张卡片或复选框切换勾选、全选、取消、“迁移至”、“生成问题”和“删除”；
-复选框阻止点击冒泡，避免重复切换。`document-detail/action-dropdown/migrate/` 集中维护
-批量按钮 `BatchMigrateParagraphAction`、单项菜单 `MigrateParagraphAction` 和 `ParagraphMigrateDialog`，沿用 chat-log 添加知识库的知识库／文档
-选择样式，保留知识库和文档图标；迁移 API 由分段页传入完整 Paragraph API 对象。
-打开时固定所选分段 ID，选择知识库后查询全部文档并排除当前文档，允许迁移至同知识库其他文档。
-目标知识库和文档查询在 `ParagraphMigrateDialog` 内按 Workspace、System 资源管理、System 共享资源
-选择各自完整 Knowledge、Document API，不接收外部查询 API；迁移提交继续使用页面传入的 Paragraph API。
-知识库和文档必选，成功关闭动画结束后通过 `success(paragraphIds)` 返回本次迁移的固定 ID，
-页面局部移除对应分段、扣减总数并移除对应勾选，不重载列表；失败保留表单。
-`document-detail/action-dropdown/generate-questions/` 维护批量按钮 `BatchGenerateQuestionsAction`
-和单项菜单 `GenerateQuestionsAction`，
-接收页面传入的完整 Paragraph API，打开时固定知识库、文档和勾选分段。复用公共
-`GenerateQuestionsDialog` 并传入 `showParagraphScope=false`，仅提交生成配置和所选分段 ID，
-不传 `state_list`；生成问题属于异步任务，提交成功关闭后仅清空选择，不重载列表；失败保留配置。
-批量删除按钮和请求逻辑直接维护在 `document-detail/index.vue`，不单独拆分组件。
-确认前固定所选分段与所属文档，确认后提交批量删除接口；成功从本地列表移除本次删除的分段、
-扣减总数并移除对应勾选，保留其他卡片与滚动位置。
-取消或失败保留选择，确认及请求期间阻止重复操作。
-`document-detail/paragraph-dialog/` 维护两个独立弹窗，以本地组件组合左右布局：
-
-- `CreateParagraphDialog.vue` 组合 `components/ParagraphForm.vue` 与 `components/ParagraphQuestions.vue`，
-  管理添加请求，底部提供取消和添加；`open(position?)` 可指定插入位置，默认添加到文档首位。
-- `EditParagraphDialog.vue` 组合 `ParagraphForm`、`ParagraphPreview` 与 `ParagraphQuestions`，
-  支持 `open(paragraph, initialMode?)`，初始模式默认为 `detail`，也可传入 `edit`。
-  详情点击编辑进入表单；取消编辑回到原详情，保存成功回到更新后的详情。
-- `ParagraphForm` 使用 `v-model` 接收标题和正文，通过 `validate()` 暴露校验；标题最多 256 字符，
-  内容必填且最多 100000 字符。正文使用 `MdEditor`，默认关闭预览，提供 Markdown 工具栏及字数统计；
-  通过必填的 `knowledgeId` 将图片上传到当前知识库，复用 `FileApi` 和 `FILE_SOURCE_TYPE.KNOWLEDGE`。
-  提交由 Dialog 编排。
-- `ParagraphPreview` 只展示标题、Markdown 正文、召回次数和最近召回时间；Dialog 管理使用 `mk-paragraph-card` 样式的详情卡片容器及绝对定位的编辑按钮。
-- `ParagraphQuestions` 沿用 v2 的添加及移除流程：点击加号显示 `el-select`，使用远程搜索、
-  `allow-create` 和首项默认选择，选择已有问题或输入新问题后立即添加；失焦取消输入。
-  问题去除首尾空格、非空、最多 256 字符且不重复，已关联候选不可重复选择。
-  候选通过 `ProblemApi.getProblemsPage` 查询第一页 100 条；已有分段分别调用创建或关联接口，
-  添加或解除关联成功后重新查询当前分段问题。列表使用卡片，左侧显示问题文字，右侧提供移除按钮；移除只解除关联，
-  不删除问题本身。无 `paragraphId` 时维护 `{ content }` 本地草稿并随新增分段提交。
-  问题输入状态和请求 loading 均在组件内部维护，不向 Dialog 传递 `adding` 或 `loading`，
-  不阻止分段创建、正文保存、取消或关闭。新增分段只提交已加入列表的问题草稿；
-  问题请求失败保留输入与现有问题。
-
-两个 Dialog、`ParagraphForm` 和 `ParagraphQuestions` 均不提供或传递 `disabled` Prop；
-详情模式通过悬浮编辑入口进入表单，问题区始终提供添加与移除入口。
-每个 Dialog 统一使用一个 `loading` 管理自身加载和提交、内容遮罩、按钮状态及重复操作保护；
-问题请求使用子组件内部独立的 `loading`，只覆盖右侧问题区。提交状态不作为表单 `disabled`。
-两个 Dialog 均接收完整 Paragraph API 和知识库／文档 ID，打开时固定目标，点击时挂载、关闭动画结束后卸载。
-详情加载失败提供重试；请求失败保留草稿。正文保存不提交 `problem_list`，也不使用保存响应回填问题列表，
-避免覆盖并行的问题操作；取消编辑不撤销即时保存的问题关联。
-新增成功关闭弹窗并通知页面清空搜索、从第一页重新加载；编辑成功通过 `success(paragraph)`
-返回保存响应，页面通过 `handleReplaceParagraph()` 按 ID 局部替换，标题和内容不再匹配当前搜索时局部移除。
-分段卡片在非批量模式点击打开详情弹窗，批量模式点击切换勾选；批量生成问题使用 `action-dropdown` 导出的 `BatchGenerateQuestionsAction`。
-非批量卡片右上角使用与文档导入预览相同的 sticky 悬浮操作区和白色阴影 Card，
-提供启停、直接编辑及上方插入；更多菜单提供单段生成问题、迁移、移动位置与删除。
-更多菜单及移动位置子菜单通过 `visible-change` 维护各自展开状态，展开期间对应操作 Card
-保持显示；关闭后恢复悬浮或焦点显隐，刷新、切换批量模式及移除对应分段时清理状态。
-该状态只控制操作区显隐，菜单与业务弹窗的挂载仍由 `MkDropdown` 的 `persistent` 管理。
-`BatchGenerateQuestionsAction` 和 `BatchMigrateParagraphAction` 直接渲染批量按钮；
-`GenerateQuestionsAction` 和 `MigrateParagraphAction` 直接渲染单项 `MkDropdownItem`；
-`GenerateQuestionsAction` 的入口文案由页面通过必填 `label` 传入。
-四个 Action 各自管理目标快照、入口和弹窗，不提供触发插槽，也不通过批量 Action 包装单项操作；
-单项与批量迁移复用 `ParagraphMigrateDialog`，生成问题复用公共 `GenerateQuestionsDialog`。
-页面通过 `action-dropdown/index.ts` 导入并组合，弹窗均点击后挂载、关闭动画结束后卸载；
-更多菜单使用 `persistent` 保留 Action 实例，迁移弹窗关闭后由重新挂载初始化状态。
-启停仅提交 `is_active`，成功后复用局部替换方法；单段删除确认后调用独立 DELETE 接口并局部移除。
-`action-dropdown/MoveParagraphAction.vue` 封装位置菜单及四个方向选项，接收 `label` 和 `disabled`，
-通过 `move(direction)` 通知页面执行移动，通过 `visible-change` 通知页面维护操作 Card 显隐；
-方向类型 `ParagraphMoveDirection` 放在同目录 `types.ts`，由 `index.ts` 类型导出。
-位置菜单包含置于顶部、上移、下移、置于底部，页面先查询完整文档分段顺序再调整位置，
-不按搜索结果计算相邻位置；调整成功后仅查询并替换当前已加载范围，保留分页与滚动位置。
-Workspace 共享及 System 分段路由已注册并保持来源导航；各范围分段 API 接入暂缓。
-
-System 资源管理与共享资源已注册共用知识库详情路由，
-列表导航已接入。System 详情路由在 System 根路由的 children 汇总，通过详情父路由的 `hideSidebar: true` 隐藏系统管理 Sidebar，保留系统 Header 和知识库详情目录；
-容器使用上下文选定的详情 API，并返回各自 System 列表。System 基础设置、策略保存使用对应 Knowledge API，
-基础表单 `KnowledgeBaseForm` 内部根据资源范围选择完整模型 API，不接收外部 `modelApi`；
-Workspace 普通与共享资源均使用 Workspace 模型选项接口，System 资源管理使用 System 模型接口，
-System 共享使用系统共享模型接口。
-四种范围的定时同步查询和日志均使用各自现有 Sync API；Workspace 普通和 System 两种范围支持保存，
-Workspace 共享只读，不发送保存请求，不回退 Workspace 接口。
-library 通过 `useKnowledgeDetailContext` 装配现有文档、标签 API；System 两种范围未提供对应模块，
-保持未接入状态，不回退 Workspace。Workspace 共享仅查询，普通 Workspace 提供已有维护接口。
-路由结构及来源配置见 `src/router/ROUTE_README.md`。
-
-### 资料库标签管理
-
-`knowledge-detail/library/tags/index.vue` 复用详情布局的 `customHeader` 与 Teleport，
-维护搜索、导入入口、创建入口和标签表格，不嵌套页面布局或修改路由。
-通过 `workspace/knowledge/knowledge.ts` 查询分组，使用单一 `MkSearchInput`，通过 `change` 将关键词作为 `name` 请求接口；
-清空时省略该参数，搜索后回到第一页并清除勾选，不在前端过滤匹配结果。
-对接口返回结果先按标签组分页，再展开各组标签值，分页总数为返回的标签组数。
-`MkTable` 合并选择列和标签名，通过 `selection-group-key="key"` 联动当前页同组标签值；
-批量底栏按实际选中标签值行数／当前页标签值总行数统计，不按标签组计数。
-删除提交全部选中标签值 ID，批量确认数量与底栏已选行数一致；标签、标签值及批量删除统一提示关联资源上的标签也会删除。
-标签名旁提供新增值、编辑标签、删除标签；行末提供编辑值和删除值，
-数量链接打开同目录 `AssociatedDocumentDrawer.vue`。
-
-`library/tags/components/CreateTagDialog.vue` 为顶部创建和标签旁新增值共用的创建弹窗，
-接收知识库 ID 与完整 Tags API，参考添加成员流程复用 `MkDialog`、`el-form` 和 `MkFormList`。
-创建允许多行标签名与值；新增值通过 `open(key)` 回填并锁定标签名，新增行沿用该名称。
-顶部创建标题为“创建标签”，传入标签名时标题为“添加标签值”。
-两个入口统一通过 `postKnowledgeTags` 提交标签数组，提交前检查表单内重复组合，沿用模型参数的 `MsgError` 消息提示并保留输入；
-与知识库已有标签重复的组合由后端跳过，接口错误由请求层统一提示。
-同目录 `EditTagDialog.vue` 共用标签重命名和单值编辑，通过 `open(tag, field)` 回填独立草稿。
-重命名只显示标签名；编辑值只显示一行并锁定标签名。两个入口均提交完整 `id`、`key`、`value`，
-请求路径 ID 与载荷 ID 一致，仅修改当前编辑字段，未编辑字段原样保留。
-两种编辑均使用 `putKnowledgeTag`，不提供增删行或多行编辑，不组合多个请求模拟保存。
-两个弹窗均保留 `MkDialog` 默认 600px 宽度，标签名最多 64 字、标签值最多 128 字，
-校验必填与纯空白，提交时清理可编辑字段首尾空格。各自维护 loading、防重复提交与关闭保护；
-成功后提示、关闭并发出 `refresh`，失败保留草稿；常驻实例在 `closed` 清理草稿和校验。
-后续文档入口直接复用上述弹窗，不复制创建和编辑逻辑。
-
-`library/tags/components/ButtonImportTags.vue` 在同一组件内维护导入按钮与弹窗，
-复用 `MkDialog`、`el-form` 和 `MkDragUpload`，不再单独拆分导入 Dialog。
-支持单个 XLS、XLSX 文件的选择、拖拽、更换、删除及必填校验，关闭后清理文件和校验状态。
-接收知识库 ID 与完整 Tags API，页面监听 `refresh` 重新查询标签列表；已预接提交 loading、重复提交保护、
-成功提示和关闭弹窗，失败保留文件。模板下载有独立 loading 和重复点击保护，下载期间禁止提交与关闭，
-结束后恢复状态，不关闭弹窗或刷新列表。导入调用 Tags API 的 `postImportKnowledgeTags`，
-通过单个 `file` 字段提交原始文件；模板下载调用 `exportKnowledgeTagTemplate`，复用请求层文件下载。
-模板第一行为“标签、标签值”，每行填写一个组合；后端校验整份文件并跳过重复组合，错误包含工作表及行号。
-
-`AssociatedDocumentDrawer.vue` 接收知识库 ID 与完整 Tags API，文档查询直接读取
-`useKnowledgeDetailContext().resourceApi.document`，不从标签页传入 Document API；通过 `open(tag)` 固定当前标签，
-以“已关联文档／未关联文档”两页签共用表格，提供搜索、启用状态筛选、分页、单个与批量关联／取消关联；创建时间仅展示，不提供排序入口。
-启用状态复用 `MkTableFilter mode="single"`，支持全部、已启用、已禁用；查询传布尔 `is_active`，全部时省略。
-名称或状态筛选后回到第一页并清空选择，切换页签时重置筛选条件。
-文档图标和时间格式沿用文档列表，状态使用 `MkStatusLabel`；批量操作放在顶部，不再显示页面批量底栏。
-搜索、分页和页签切换清空选择，关联变更后重新查询并通知标签页刷新数量，末页为空时回退。
-抽屉在 `closed` 重置标签、筛选、分页和选择，不新增权限判断或共享范围接口。
-文档页标签候选查询通过资料库上下文选择当前范围 Tags API，共享标签查询保持原接口；普通文档标签入口使用上述独立添加弹窗与抽屉。
-
-`KnowledgeWorkflowView` 复用 `ButtonDefaultModelSetting`，从知识库详情读取默认模型配置，
-随工作流保存提交并将配置传入画布；支持应用到所有节点，保存失败回滚至已保存配置。
-
-## 智能体复制 Action
-
-`application/application-card/action-dropdown/copy-application-action/` 提供 `CopyApplicationAction`
-和 `CopyApplicationDialog`。列表按 `application.workspace.copy(id)` 控制入口，传入完整应用 API、
-源应用及当前文件夹 ID。点击后查询完整详情，深拷贝配置并移除原 ID 等资源元数据，名称默认追加
-“副本”，确认后创建到打开时的当前文件夹。复制成功刷新列表及用户权限，简易应用进入设置页，
-工作流应用进入画布；请求失败保留表单。弹窗按需挂载，在 `closed` 后卸载。
-
-`workflow/application/index.vue` 在默认模型设置之前引用 `ButtonTemplateStore`，
-通过 `open` 关闭调试面板，通过 `use(template)` 执行覆盖确认和请求；加载、保存或发布期间禁止打开。
-页面确认覆盖后提交 `work_flow_template`，重新加载详情、画布和已保存基准；完成后通过按钮组件的
-`close()` 关闭模板中心并提示成功。取消或失败保留模板中心。
-
-## 智能体工作流调试
-
-调试对话面板已内聚到会话模块:`@/conversation-panel/view/debug/index.vue` 自带面板显隐、
-放大/还原(放大/关闭按钮由 `@/conversation-panel/components/header/debug/index.vue` 提供)及局部样式，
-通过 `open()`、`close()` 控制,关闭时重置放大状态,保留关闭动画。
-`ApplicationWorkflowView` 直接渲染调试按钮和 `<DebugPanel ref="debugPanelRef" />`(即上述 debug 视图),
-通过 `handleDebug` 在存在未保存改动时先保存，成功后调用面板的 `open()`。
-打开模板中心或默认模型设置时，页面调用 `close()` 关闭调试。
-
-## 智能体工作流返回导航
-
-`workflow/application/navigation.ts` 的 `goBack(applicationId)` 读取当前资源范围的智能体详情父路由，
-按子路由 `meta.order` 选择首个有名称、标题、未隐藏且通过 `meta.canAccess(params)` 的页面。
-返回逻辑不固定概览、访问、访客或日志路径；新增、重命名和排序子页面只需维护路由配置。
-未配置 `canAccess` 的详情页默认可访问；有权限或类型限制的页面必须显式配置。
-当前概览使用 v3 `overviewRead` 权限；简易设置只允许 SIMPLE 类型及编辑权限，不作为工作流返回目标。
-无可访问详情时回退对应列表。System 暂无详情父路由，当前回退 System 资源管理智能体列表。
-`ApplicationWorkflowView` 保留未保存确认以及保存后退出流程，导航统一调用该工具函数。
-
-## 工具工作流调试
-
-`workflow/tool/index.vue` 在默认模型设置后提供调试按钮，先校验画布，有未保存改动时
-保存成功后再打开调试。打开默认模型设置或发布历史时关闭调试抽屉。
-`tool/debug/DebugDrawer.vue` 接收 `toolId`，通过 `open(graph)` 从已保存图的工具基础节点读取输入字段，
-管理字符串、整数、浮点数、布尔值及 JSON 数组/对象参数，校验后交给 `ResultDrawer` 运行。
-`ResultDrawer.vue` 负责 SSE 消费、流式回复、输出参数和节点执行详情，复用现有
-`ConversationStream`、回复块聚合与渲染组件、`ExecutionDetailContent`，不使用 v2 的动态 API 或聊天 Store。
-运行结束后读取执行记录；表单节点通过同一 `chat_record_id` 和 `position` 续跑。
-运行期间禁止重复执行，返回参数保留输入，再次运行创建新记录；关闭或卸载中断前端读取，
-不表示服务端任务已停止。两个抽屉复用 `MkDrawer`，关闭动画期间保持挂载。
-
-## 工具工作流返回导航
-
-`workflow/tool/navigation.ts` 统一提供 `goBack(folderId?)`，使用资源上下文判断返回范围：
-System 资源管理返回 `system-resource-tools`，System 共享资源返回 `system-shared-tools`，
-Workspace 返回 `workspace-tools` 并携带当前 `workspaceId` 和可选 `folderId` query，
-由工具列表的 `FolderTree` 恢复所属目录。工具 View 只负责历史预览退出、未保存确认及保存后退出，
-不再维护路由跳转细节。
-
-## 工具工作流导出
-
-`ToolWorkflowView` 更多菜单底部提供“导出工作流”，复用 `ToolApi.exportTool` 下载 `.tool` 文件。
-存在未保存画布改动时先保存，保存失败不发起导出；导出期间禁止重复操作并暂停自动保存。
-文件内容由后端从已保存工作流生成，沿用公共下载方法的文件名与错误响应处理。
-
-## 工作流页面加载状态
-
-application、tool、knowledge 的 WorkflowView 统一使用一个 `loading` 控制整页遮罩和操作禁用，
-不再拆分 `saving`、`publishing`、`exporting` 或 `openingDebug`。最外层操作负责开启状态并在
-`finally` 中释放；内部保存、加载详情方法只返回 Promise，不修改 loading。发布的校验、保存、发布，
-模板覆盖及重新加载，以及调试前保存、导出前保存均保持完整流程的 loading。
-自动保存同样复用该状态；历史显隐和退出确认属于交互状态，独立维护。抽屉内部请求状态仍由抽屉管理。
-
-### 知识库工作流导航与导入导出
-
-`workflow/knowledge/navigation.ts` 统一返回入口：Workspace 将详情中的 `type` 通过 `KNOWLEDGE_TYPE_MAP` 转为字符串后返回当前知识库详情，详情尚未加载时使用 `WORKFLOW`；System 资源管理和共享资源返回各自知识库详情；Workspace 共享也返回共享详情。
-历史模式下返回只退出预览；普通编辑态返回保留未保存确认。更多菜单的导出工作流先保存未提交改动，
-再调用专用 `.kbwf` 导出接口；保存失败不导出。知识库原有文件上传、数据源表单与任务轮询调试流程保持独立。
-更多菜单在“导出工作流”上方依次提供“导入文档”和“导入工作流”。导入文档要求工作流已发布，
-复用文档页的 `WorkflowImportDocumentDrawer`，按需挂载并在关闭动画结束后卸载；发布成功即时更新
-本页发布状态。导入工作流选择单个 `.kbwf` 文件，确认覆盖后上传，不先保存旧草稿；确认及请求期间
-暂停自动保存，成功重新加载图、默认模型设置、保存时间与保存基准。取消或请求失败保留当前画布，
-文件选择使用 `el-upload`，关闭自动上传与文件列表展示；选择后调用 `clearFiles()`，
-允许再次选择同一个文件。不增加权限判断。
-
-## 智能体工作流发布
-
-`ApplicationWorkflowView` 直接管理发布按钮与 `EditPublishVersionDialog` 的发布模式，
-点击后先校验画布，通过后调用弹窗的 `open()` 打开“发布内容”表单；
-校验失败不打开弹窗。表单通过 `submit` 将标题和更新说明交给 `ApplicationWorkflowView`。
-页面复用整页 `loading`，提交时保存当前工作流、调用发布接口，映射 `name` 为
-`publish_name`，更新说明使用 `publish_desc`。成功后更新详情与保存时间，关闭弹窗并提示；
-保存或发布失败保留表单以便重试。旧 `ApplicationPublishDialog` 不再使用。
-
-## 工作空间首页
-
-`home/index.vue` 组合快捷创建、资源概况、使用统计和 Top 5 排行榜。首页按当前路由
-`workspaceId` 重新挂载各业务区，切换工作空间时清理旧筛选、数据和抽屉。
-首页普通组件放在 `home/components/`；排行榜流程集中在 `home/ranking/`，包含
-`HomeRankings.vue` 和 `RankingDrawer.vue`。
-排行配置与展示计算保留在各自组件内，不单独维护首页 `constants.ts`、`statistics.ts`。
-`HomeView` 向 `HomeResourceOverview` 传入完整首页 API 对象，组件通过 `typeof HomepageApi`
-约束 `api` Prop 并调用 `props.api`。资源概况、使用统计和排行均由 `HomeView` 显式传入
-`workspaceId`，排行榜继续向详情抽屉传递；调用首页接口时逐次传入此 ID，不在 API 内读取路由。
-顶部切换工作空间时统一整页加载，重载统计数据并清理旧筛选与排行榜详情，统计组件无需额外设置工作空间 key。
-
-快捷创建通过插槽复用智能体、知识库、工具和模型的现有入口，目标文件夹为当前工作空间根目录；
-保留创建流程中的用户资料刷新及详情／工作流导航，停留首页的成功操作刷新资源概况与智能体选项。
-资源卡片使用命名路由进入当前工作空间的对应列表。
-
-`HomeView` 管理监控区的智能体列表查询、选择器和 `applicationId`，向 `HomeStatistics`
-传入完整 `HomepageApi` 与选中的 ID。统计组件监听工作空间和智能体 ID 变化加载数据，
-通过 `application` 插槽提供 `loading`，由 View 渲染选择器并控制请求期间禁用。
-选择器通过 `remote-method` 按名称请求前 200 个智能体；选项和选中值复用 `ApplicationIcon`，
-全部智能体使用 `icon_all_outlined`。清空回到全部，已选智能体图标独立保留，避免搜索结果变化后丢失。
-
-统计区、排行榜和详情抽屉直接复用 `MkDateRange`，将 `change` 的 `startTime`、`endTime`
-映射为接口的 `start_time`、`end_time`。默认查询与组件的过去 7 天预设一致，结束日期为当天。
-抽屉初始查询继承排行日期，通过 `MkDateRange.defaultValue` 同步回填日期选择器；
-公共组件暂不支持禁用。智能体筛选仅影响使用统计。
-活跃用户汇总是每日活跃人数之和，标为“累计活跃人次”；反馈展示点赞和点踩数量。
-`HomeStatistics` 直接使用公共 `MkLineChart`，传入日期和指标系列；实例、尺寸监听和销毁由
-`MkEchart` 管理，不再保留首页专用图表包装组件。
-
-排行榜详情继承打开时的日期与排行类型，独立维护名称搜索、分页和导出；搜索、日期及页容量
-变化重置页码，排名包含分页偏移。占比使用工作空间同期总量，不用 Top 5 或搜索结果合计替代。
-各业务区分别维护 loading 和失败状态，失败不伪装为零数据；首页不新增前端权限控制。
-
-`application/components/ButtonCreateApplication.vue`、`knowledge/components/ButtonCreateKnowledge.vue`
-与 `tool/components/ButtonCreateTool.vue` 支持 `trigger`（默认 `click`）、
-`popperStyle`、`popperClass` 和 `fitTriggerWidth`，三者保持相同的触发与浮层配置约定。
-`popperClass` 同时应用到浮层和菜单。
-默认菜单保持固定宽度；传入 `popperStyle.width` 或 `popperClass` 时，菜单填满浮层，宽度由调用方控制。
-`fitTriggerWidth` 默认关闭，只有显式开启时才在展开时测量自定义触发器宽度，并覆盖 `popperStyle.width`；
-首页快捷创建开启此配置，其他页面不因使用触发器插槽而自动等宽。`w-full` 样式类不触发测量。
-
-首页排行榜卡片由 `home/components/ranking/RankingCard.vue` 渲染，接收 `title`、`records`、
-`loading`、排行类型 `kind` 及总量 `total`，名称读取与占比计算由卡片内部处理；`detail` 事件交给父组件打开抽屉，`description` 插槽提供
-`record`、`index`，由父组件定义每行说明文案。
-
-排行榜 API 由 `HomeView` 传入 `HomeRankings`，再传给 `RankingDrawer`。两者的 `api`
-均使用 `typeof HomepageApi` 约束，查询、汇总和导出统一通过 `props.api` 调用。
-
-## 知识库工作流转换与执行记录
-
-### 知识库工作流转换
-
-`knowledge-detail/workflow-transform/index.vue` 承接 Workspace 非工作流知识库的“工作流”入口，
-路由统一使用 `workflow-entry`（`workspace-knowledge-workflow`），不另设转换路由。
-复用详情布局并隐藏标题栏，展示 v2 转换说明与工作流示例图。知识库详情从已有上下文读取，
-路由 `beforeEnter` 将工作流类型直接重定向至全屏画布，页面不监听类型跳转。
-转换需确认不可回退，页面管理 loading 与重复提交保护，
-通过 `useKnowledgeDetailContext()` 的 `resourceApi.knowledge.postTransformWorkflow` 提交
-深拷贝后的 `knowledge/template.ts` 默认模板，按上下文选择 Workspace、System 资源管理或
-System 共享管理 Knowledge API；成功后进入画布，失败保留转换页。
-四种范围的路由与画布跳转已配置；API 保留原实现，Workspace 共享和 System 工作流接口接入暂缓。
-
-### 执行记录
-
-`workflow/knowledge/ButtonExecutionRecord.vue` 封装更多菜单入口、抽屉挂载与打开逻辑，接收
-`knowledgeId`，菜单属性（如 `divided`）透传到 `MkDropdownItem`，内部提供知识库 Workflow API。
-`workflow/knowledge/execution-record/` 维护记录列表和详情抽屉，由该按钮组件打开；
-工作流文档页在“导入文档”左侧使用 `knowledge-detail/library/document/components/ButtonExecutionRecord.vue`
-封装“执行记录”按钮与同一个记录抽屉，页面传入当前知识库 ID 与完整知识库 Workflow API，
-按钮组件维护抽屉挂载状态和打开逻辑。两个入口均在点击时挂载抽屉，
-关闭动画结束后卸载。列表复用 `MkComplexSearch`、`MkTable` 和 `MkStatusLabel`，支持发起人、
-状态筛选及跨页浏览，每 6 秒刷新；关闭或卸载停止轮询。待执行、执行中任务经确认后取消，成功刷新列表。
-抽屉接收完整知识库 Workflow API；详情查询复用调试任务接口，使用 `ExecutionDetailContent` 展示节点结果。
-
-## 智能体详情占位页面
-
-`application-detail/integration/index.vue` 承接接入第三方，目前仅展示占位内容，
-标题及详情框架继续由 `ResourceDetailLayout` 提供。设置菜单按资源类型选择现有简易设置页面
-或高级智能体全屏工作流，不另建高级设置 View。
-
-## System 资源管理模型与工具
-
-`system/resource-management/model/index.vue` 与 `tool/index.vue` 使用
-`MkViewLayout`、`MkComplexSearch` 和 `MkTable` 展示跨工作空间资源。
-模型操作列使用 `EditModelAction display="button"` 展示编辑按钮，其余操作放入 `MkTableMoreDropdown`；
-`EditModelAction` 透传 `display` 给 `MkAction`，默认保持菜单模式，内部管理编辑抽屉，保存后发出 `refresh`。
-模型和工具仅编辑、资源授权四个 Action 使用 `MkAction` 并透传显式 `display`，默认菜单模式；
-其他业务 Action 继续使用 `MkDropdownItem`，页面按现有布局显式选择按钮或菜单。
-工具操作列保留独立启停开关，
-其余操作放入 `MkTableMoreDropdown`。菜单开启 `persistent`，业务 Action 使用 `MkDropdownItem`，
-保留各自 API、权限条件、事件和浮层生命周期。资源管理页保留带引用提示和分页回退的独立删除流程。
-名称、类型、创建者（工具另含来源）筛选和工作空间表头筛选变化后回到第一页；分页大小变化由
-`MkTable` 重置页码。工作空间列及选项查询只在企业版开启，`workspace_ids` 沿用 JSON 数组字符串。
-页面使用 v3 的 System 权限方法保留迁移前已有的操作权限，不增加创建、导入、批量或复制入口。
-删除保留资源引用数量提示，删除末页最后一条后退回上一页。
-
-模型复用编辑抽屉、参数设置、授权和关联资源 Action；工具复用各类型编辑表单、启停、启动参数、
-MCP 配置、授权、导出、触发器和执行记录。页面显式传入对应 System 业务 API。
-商店工具只修改名称，不开放模板代码编辑；编辑与启停合并返回数据，保留列表中的工作空间等展示字段。
-工具维护表单的 API 联合包含 System 资源对象，该范围没有 `postTool`，不通过伪造创建接口满足类型。
-
-资源管理中的工作流进入 `system-resource-workflow-tool`，由 `ToolWorkflowView` 选择 System
-工具、工作流和模型 API，并把工作流 API 传给发布历史与调试抽屉；返回资源管理工具列表。
-`TriggerToolAction` 和 `ResourceTriggerDialog` 透传可选 `toolApi`、`toolWorkflowApi`，
-由 `TriggerFormDrawer` 查询当前资源的完整输入定义；未传时保持 Workspace 默认接口。
-
-工具工作流按三种 `resourceScope` 选择完整工具、工作流与模型 API，并透传到默认模型、历史、调试抽屉。
-System 两种工作流入口只传 `toolId`，不传路由工作空间；共享范围默认模型选项使用共享模型列表。
-
-## 资源详情页自定义标题栏
-
-标题栏能力统一放在 `layout/ResourceDetailLayout.vue`，不另建 Header 组件或注入上下文。
-Layout 预留整个右侧标题栏的 `headerTarget`，通过 `RouterView` 作用域插槽将 `headerTarget`
-和当前路由 `title` 作为 props 直接传给子页面，不修改路由配置。
-详情子页面从该 Vue 文件导入 `ResourceDetailPageProps` 并声明 props。普通页面无需编写标题栏模板，
-由 Layout 显示默认路由标题。需要自定义的页面通过 `defineExpose({ customHeader: true })` 声明，
-再使用 `<Teleport v-if="headerTarget" :to="headerTarget">` 组合标题、搜索与操作。
-Layout 读取当前页面实例的声明决定是否显示默认标题；默认和自定义标题模式均保留挂载位置，不增加路由字段。
-不需要标题栏的页面通过 `defineExpose({ hideHeader: true })` 隐藏整个主区 Header，包括挂载位置和留白；
-`hideHeader` 优先于 `customHeader`，未声明时保持原有标题行为，切换页面后按当前实例恢复。
-Layout 保留标题栏固定位置和外层间距，页面负责内部布局。
-切换子页面时随 Teleport 卸载清理内容，不需要注册计数或 DOM 检测。
-资源入口只负责详情数据和侧栏 `resource-header`，无需转发标题栏属性。
-文档页将标题、搜索与上传入口放入标题栏，表格在正文中独立显示 loading。
-
-通用知识库的非共享文档页在标题栏使用 `document/upload-document/ButtonUploadDocument.vue`，
-提供文本文件、表格和 QA 问答对菜单。页面通过 `api` 传入完整 Document API，由按钮转交抽屉，
-模板下载、文本解析和文档导入均调用传入的 API。点击后按需挂载 `UploadDocumentDrawer.vue`，
-使用全屏底部抽屉，关闭动画结束后卸载。文件支持多选、拖拽和文件夹选择，最多 50 个文件，
-同时遵循知识库的文件数量、单文件大小限制；文件卡片支持下载和删除。
-上传区复用公共 `MkDragUpload` 的多文件模式；多文件组件负责文件夹选择、上传汇总及两列卡片。
-抽屉通过 `provide('upload')` 提供 Admin `FileApi.postUploadFile`，使用 `TEMPORARY_120_MINUTE`
-上传临时文件，由多文件组件维护实际传输进度、重试及取消；页面通过公开的 `uploadingCount`
-阻止上传中进入下一步或导入，没有成功文件时提示，上传结束后仅处理 `success` 文件。
-页面通过 `accept`、`limit`、`sizeLimit` 提供校验规则，由多文件组件校验格式、大小、空文件和重复选择；
-大小超限保留不可重试的失败卡片，网络失败可重试。移除成功文件时，多文件组件直接
-调用 `FileApi.deleteFile(file_id)` 删除服务端临时文件；上传中文件由组件取消请求。
-具体上传接口与导入请求仍由本页负责。
-文本分段解析接口仍提交原始文件。表格和 QA 导入从成功文件的 `file_id` 获取上传结果，
-提交 `{ file_id_list }` 到对应的 `table_by_file_ids` / `qa_by_file_ids` 接口，不重复上传文件；
-缺少文件 ID 时提示重新上传，不回退到再次上传原始文件。
-文本上传分为文件选择和文档处理策略两步，复用 `DocumentStrategyForm`，首次进入第二步才挂载，
-开启视觉增强后按当前策略加载选项，返回上一步保留策略及已加载选项；
-策略页的“生成预览”按当前策略解析文件，进入 `upload-document/DocumentImportPreview.vue`，
-使用 `MkViewLayout` 的侧栏切换文档、正文展示分段，复用其主区滚动和固定标题；
-支持本地编辑和删除，编辑须保存或取消后再导入。
-分段编辑使用同目录的 `EditParagraphDialog.vue`，复用添加分段的 `ParagraphForm` 与
-`ParagraphQuestions`，提供 Markdown 编辑、知识库图片上传和关联问题草稿；不传入已有分段 ID，
-保存仅更新当前导入草稿，不创建分段或立即写入问题关联，取消不修改预览。
-编辑弹窗按需挂载，关闭动画结束后卸载；关联问题随最终导入的 `problem_list` 提交。
-预览仍属于第二步，返回策略页保留设置，重新生成时以新的解析结果替换预览。
-预览导入直接批量创建编辑后的分段，保留来源文件及处理策略，不再次解析。
-策略页“开始导入”将已上传的 `file_id_list` 与当前 `doc_strategy` 一次提交到 `document/import`，
-由服务端读取已有文件直接解析并入库，不再次上传文件；缺少文件 ID 时提示重新上传。
-不调用预览接口或在前端传递分段结果；解析和入库在同一事务内完成，空分段结果提示失败。
-表格、QA 直接调用各自导入接口，支持下载 Excel、CSV 模板。
-选择文件阶段显示实际上传状态，导入成功后关闭、清空搜索和表格筛选，并回到第一页重新加载；
-失败保留文件与策略。
-不新增权限判断或修改共享文档的查询边界。
-
-Web、飞书和工作流知识库的非共享文档页在标题栏组合
-`document/import-document/ButtonImportDocument.vue`，页面传入已有路由变量 `knowledgeId`、
-`knowledgeType`（`KNOWLEDGE_TYPE_KEY` 标识），从详情上下文读取飞书 `folderToken` 和工作流图 `workflow`；
-不传完整 `knowledge`，不重复查询知识库。
-入口按类型挂载独立的 `WebImportDocumentDrawer.vue`、`LarkImportDocumentDrawer.vue`、
-`WorkflowImportDocumentDrawer.vue`，关闭动画结束后卸载。
-Web 和飞书使用全屏底部 Drawer，分别通过地址表单和飞书 `MkTable` 懒加载目录表格进入文档处理策略；
-策略复用 `DocumentStrategyForm`，使用组件默认策略，不回显知识库策略，上一步保留草稿。
-Web 抽屉只接收完整 Document API 与知识库 ID，地址和选择器初始为空；
-飞书抽屉额外接收文件夹 Token，工作流抽屉只通过 Prop 接收知识库 ID，图数据在打开时通过
-`open(workflow)` 传入并保存在抽屉本地；所有导入组件均不接收 `KnowledgeDetail`。
-Web 地址按行去空白、去重并校验 HTTP/HTTPS；空选择器提交 `body`。
-飞书按 `meta.folder_token` 查询目录并读取全部分页，已导入文档勾选且不可重复导入；
-表格使用原生 `type="selection"` 选择列和名称列，表头全选覆盖当前已加载节点；
-初始化仅加载根目录，文件夹默认收起，展开与收起由 Table 维护。
-不重复保存表格选择状态，在下一步通过 `getSelectionRows()` 获取待导入文档。
-文件夹持续保留懒加载标记，由 Table 维护层级和缩进，避免与普通树数据混用导致层级丢失。
-原生选择维护已加载节点的父子联动与半选，勾选文件夹不请求子目录，只有展开时加载。
-展开已选文件夹时新加载的节点继承勾选，加载期间禁止进入下一步。
-正式导入沿用 v2，仅过滤已导入项，保留所选文件夹的名称、Token 和类型，不在前端递归展开文件夹。
-两者提交成功关闭并刷新列表，失败保留输入、选择和策略。
-工作流导入 Drawer 与 DebugDrawer 使用相同的三步 Action，直接引用
-`views/workflow/knowledge/debug/action/` 的 DataSource、KnowledgeBase 和 Result，
-有知识库用户输入字段时显示第二步；通过正式 `/upload_document` 接口执行已发布工作流。
-上传提供临时文件、进度及取消能力，上传中阻止切换或提交，失败文件不提交；
-`file_id` 与上传成功状态校验仅用于本地文件数据源；飞书等工具数据源的 `file_list`
-保留远程文件或文件夹选择值，由后端工具负责下载，不要求本地上传 ID。
-继续导入重建 Action 并清空载荷，提交及完成后通知列表刷新。不新增权限判断。
-飞书扩展接口沿用 v2；当前仓库缺少 v3 飞书后端，新增的每文件 `doc_strategy` 字段需扩展端联调确认。
-
-普通资料库（`KNOWLEDGE_TYPE.BASE`）的非共享文档页通过 MkTable 的 `body-prepend` 插槽展示
-公共 `MkQuickCreate`，类型读取已有知识库详情上下文，不重复请求详情。
-页面通过 `@create="handleCreateDocument"` 接收名称，管理创建请求及 `creatingDocument`，通过 `loading` 传给组件。
-创建成功后调用组件 `close()`、显示成功提示、保留筛选条件并回到第一页刷新，刷新失败不恢复已提交草稿。
-组件只维护输入及空名称禁用，创建失败时页面不关闭组件，保留草稿供重试。
-入口独立于文档数组，在空列表中同样显示，不计入分页或批量选择；不新增前端权限判断。
-
-文档页的筛选选项、状态和事件集中在 `// 过滤项` 下：文件状态、启用状态、召回处理显式使用
-`MkTableFilter mode="single"`，标签使用 `mode="cascader"`。文件状态按 v2 提供成功、失败、
-索引中、分词索引中、排队中、生成中，同时映射 `status` 与可选 `task_type`；切换到非任务状态
-或全部时清除任务类型。启用状态保留布尔 `false`，召回处理复用 `DOCUMENT_HIT_HANDLING_LABELS`。
-表头标签筛选每次展开时按普通／共享范围重新查询知识库标签，不因已有选项而跳过请求；
-普通布尔请求锁防止重复请求，失败释放后下次打开可重试。
-标签级联沿用 MkTableFilter 默认的父子独立选择和隐藏复选框外观；组件内部保留原始勾选，
-对外将父组转换为叶子值并去重。页面直接将回写的叶子标签 ID 数组用于查询，
-“无标签”使用 `NO_TAG`；页面不维护父组展开或去重逻辑。
-任一筛选确认或重置后回到第一页查询，保留其他筛选和名称／创建者搜索条件。
-标签列使用页面专属 `components/DocumentTags.vue`，接收 `document`、知识库 ID 和完整 Document API，展示标签数量，
-悬浮时显示标签名与值，长文本省略并保留 title。数量优先读取 `tag_count`，缺省时使用标签数组长度，
-添加按钮始终显示，通过 `disabled` 接收页面的 Workspace 共享只读状态，通过 `v-model:loading` 共用操作状态，不隐藏加号和“标签”文案；已有标签的悬浮查看不受影响。
-添加按钮阻止点击冒泡，组件内部按需挂载并打开 `AddTagDialog`；打开方法同时检查只读、操作中和重复打开状态。
-添加成功关闭弹窗后通过 `refresh` 通知页面刷新文档列表与数量；不新增权限判断。
-
-文件状态的解析、聚合与展示统一放在文档页的 `components/DocumentStatus.vue`。组件接收 `status`、`statusMeta`，按从右起的任务位置解析向量化、生成问题、
-同步、分词索引；聚合优先级为取消中、执行中、排队中、失败、取消完成、成功，
-同优先级取字符串最左侧的任务，忽略 `n` 及未知状态；无有效任务时显示 `-`。
-汇总与悬浮明细均复用 `MkStatusLabel`，通过文档本地 `status.ts` 的 `DOCUMENT_STATUS_OPTIONS`
-传入图标类型和文案；`DOCUMENT_STATUS_FILTER_OPTIONS` 复用对应文案并维护筛选请求映射。
-文档配置独立于执行记录配置。保持 v2 的取消完成显示成功规则，不修改通用状态语义。
-悬浮内容按需渲染，展示各任务名称、状态、成功分段数／总数和时间；分段计数读取 `status_meta.aggs`，
-成功数只累计状态 `2`，失败与取消完成的进度使用危险色。
-时间读取 `state_time[taskType]` 的排队时间，取消完成读取取消完成时间；缺失元数据使用 0/0 并隐藏时间。
-
-## Workspace 共享知识库详情
-
-知识库列表根据当前目录进入普通或 `workspace-shared-knowledge-detail` 共享详情路由。
-两者复用 `knowledge-detail/index.vue` 和文档页；详情容器通过上下文选择对应详情 API，
-文档页与标签页通过 `useKnowledgeDetailContext` 选择普通或共享的现有完整 API 对象。
-共享详情已补齐与其他三种范围一致的菜单，设置与工作流接口接入暂缓。
-容器监听工作空间、知识库和资源范围变化重新加载；共享详情返回列表携带 `folderId: 'shared'`，
-普通详情继续恢复所属文件夹。文档创建者选项在共享范围使用 System `CommonApi`，普通范围使用
-Workspace `CommonApi`；文档页通过 `onMounted` 首次加载，不监听路由参数或资源范围重置状态。
-
-## 知识库外部检索服务
-
-`knowledge-detail/external-retrieval/index.vue` 由四个资源范围共用，复用详情布局的自定义标题栏，
-当前仅直接调用普通 `workspace/knowledge/external-retrieval.ts`，不新增 context 配置。
-通过 `isWorkspaceResource()` 限定请求范围；其他三个范围显示待接入提示、禁用开关，不回退普通 Workspace。
-普通 Workspace 提供身份认证及服务启停开关；查询与提交共用内容 loading，
-开关仅在保存成功后按完整响应回显，每次只提交变化字段，失败保留原状态。
-API 地址、调用示例及 MCP 配置只读；后两个展示区参考工具 MCP 详情，使用文本域和悬浮复制按钮。
-地址与调用示例均来自接口；调用示例直接绑定 `api_example` 字符串，不在前端拼接或执行检索；MCP 配置直接格式化接口结果。
-四套 API 文件及联调 TODO 保留，均使用真实请求封装，不返回占位 null；其他范围的页面接入待后续处理。
-查询失败不回填配置，不允许在未知配置上保存；页面不伪造配置或保存成功。
-
-## 智能体与知识库对话用户
-
-`application-detail/chat-user/index.vue` 与 `knowledge-detail/chat-user/index.vue` 分别维护智能体、知识库的用户组和用户授权，
-使用对应路由 ID 及 `RESOURCE_TYPE.APPLICATION / KNOWLEDGE`；授权类型必须大写，与后台授权记录及对话端查询一致。
-两页通过 `hideHeader: true` 隐藏详情标题栏，使用普通 Flex 双栏容器，不嵌套 `MkViewLayout`。
-外层 `ResourceDetailLayout` 统一管理整体滚动；侧栏复用 `w-sidebar-expanded`、`MkSearchList` 的搜索、选中和空态。
-“按用户组”列表通过插槽展示名称及自动授权状态；接口返回组已授权人数 `authorized_count`，自动授权组显示“（自动授权）”，手动授权组显示“（已授权 N）”，不以当前页勾选数代替。
-右侧第一行展示组名和用户查询总数；下方工具栏左侧为默认按姓名查询的 `MkComplexSearch` 及自动授权开关，右侧为保存。
-顶部 `MkComplexSearch` 按姓名、用户名排列；用户来源只在表头使用 `MkTableFilter mode="single"` 筛选，向接口传 `source`。
-用户名、姓名搜索与表头来源可组合查询，清空一处条件不影响另一处，不额外重置搜索组件。
-筛选变更回到第一页，选择“全部”移除来源条件。保留 `MkTable` 分页及高度约束。
-
-两页当前仅直接调用普通 `workspace/chat-user.ts`，分别传自己的资源类型和路由 ID，不配置到详情 context。
-页面不判断资源范围，也不显示范围待接入提示；当前请求均使用 Workspace API，其他入口的 API 切换尚未接入。
-其他范围的 API 文件及联调 TODO 保留，页面接入待后续处理。
-当前不接入 `perm`。授权勾选只维护当前页，保存只提交当前页用户；翻页、筛选或切换组时重新读取服务端状态。
-无修改、无用户或自动授权开启时禁用保存；保存失败保留勾选，成功更新已保存快照并刷新当前用户列表，保留当前组与页码。
-自动授权切换立即保存，成功后更新组状态、清空旧用户与勾选快照，再查询用户；开启时禁用手动授权。
-保存与自动授权切换不重新查询用户组，避免用户刷新依赖无关请求。筛选和切换用户组回到第一页。
-用户组查询、用户查询与提交共用页面 loading；由各操作的最外层管理，内部查询不提前关闭遮罩。
-查询和提交期间页面容器通过 inert 防止交叉操作。
-页面通过 `onMounted` 加载用户组；工作空间切换由顶部入口整页加载，不额外监听路由重置。
-来源标签沿用登录方式枚举与现有“本地创建”文案，兼容 `OAUTH2` 返回值。
-
-## 智能体对话日志
-
-`application-detail/chat-log/index.vue` 参考 `system/operate-logs`，通过 `customHeader` 和 Teleport
-使用详情布局的标题栏，组合标题、`MkDateRange`、`MkComplexSearch`、导出和清除策略入口，
-不嵌套 `MkViewLayout`。挂载时查询过去 7 天，搜索、日期和反馈筛选变化后回到第一页，
-不监听工作空间路由参数，也不新增权限判断。
-列表使用 `MkTable`，勾选用于导出和批量添加到知识库；无勾选时导出当前筛选结果。列表和导出使用同一组查询条件，
-切换筛选或分页后清空旧选择。点赞、点踩最小值使用 `MkTableFilter mode="custom"` 的默认作用域插槽编辑，
-页面只维护已生效值和全 0 的 `resetValue`；浮层、草稿、重置与确认由公共组件管理，确认或重置后重新查询。
-自定义日期清空后清空列表并禁用导出，重新选择有效日期再查询。
-来源枚举位于 `api/enums/chat-log.ts`，页面标签位于本功能的 `constants.ts`。
-
-`chat-log/index.vue` 统一导入完整 ChatLog API 对象，通过 `api` Prop 传给清除策略与添加知识库
-按钮，并继续透传至弹窗；子组件仅类型导入 ChatLog API。知识库及文档选项 API 暂由添加知识库弹窗直接导入。
-
-`clean-strategy/` 按操作日志页拆分 `ButtonCleanStrategy` 和 `CleanStrategyDialog`，
-每次打开重新读取智能体详情；日志保留天数为 1–100000，文件保留天数不超过日志保留天数。
-保存使用专用清除策略接口，只更新当前智能体，成功刷新详情上下文后关闭，失败保留弹窗。
-详情上下文的 `refreshApplicationDetail(showLoading = true)` 默认显示整页 loading；
-清除策略弹窗在打开和保存后均传 `false`，仅由弹窗自身的 loading 管理请求，避免内外重复遮罩。
-传 `false` 的请求不修改外层 loading 的开始或结束状态。
-点击日志行打开本功能的 `ChatLogDetailDrawer.vue`，选择列只处理勾选，不打开详情。
-详情抽屉参考 v2 使用当前摘要作为标题，宽度为 `60%`，暴露 `open()`、`close()`。
-页面按需挂载后调用 `open()`，在 `closed` 后清空当前记录并卸载，保留关闭动画。
-底部上一条／下一条切换整条对话日志；页面负责当前记录、首尾禁用及跨列表分页查询，
-跨页成功后同步列表页码并切换至首条／末条，失败保留原记录和页码，加载期间禁用切换。
-正文暂时留空，不查询或展示聊天内容，也不显示聊天记录分页器。
-`add-knowledge/` 集中维护 `ButtonAddKnowledge` 和 `AddKnowledgeDialog`，批量入口固定打开时的
-对话 ID，弹窗参考 `DocumentMigrateDialog` 的顶部标签表单与带知识库图标的可搜索下拉框。
-每次打开查询当前工作空间知识库，选择知识库后查询全部文档并清空旧文档选择；知识库与
-文档必选，提交期间使用内容 loading。成功关闭、清空表格勾选并刷新标注数量，失败保留选择。
-
-## 对话端单应用与门户对话页面
-
-`views/chat/index.vue`（`chat-home`、`chat-home-detail`）与 `views/portal/index.vue`
-（`portal-application`、`portal-application-chat`）分别渲染对话面板的 chat、portal 视图。页面只负责：
-
-- 以 `auth.token` 作为面板的 `key`，token 变化（401 重新认证、登录）时重建面板并重新加载数据；
-  token 被清除后不渲染面板，等待守卫重新认证。
-- token 变化时重新加载当前对话用户档案，供侧栏账户入口展示。
-
-对话面板 chat 模式的装配函数 `view/chat/index.ts` 通过 `ChatConversationRouting` 获取智能体 ID
-与会话地址，单应用使用默认实现（智能体 ID 取自 `auth.applicationId`，地址为 `/:accessToken/c/:chatId`），
-portal 模式传入门户实现（智能体 ID 取自路由 `applicationId`，地址为 `/portal/a/:applicationId/c/:chatId`）：
-
-- 加载智能体名称与图标；切换智能体时停止当前生成，重新加载智能体信息与会话列表。
-- 当前会话与地址双向同步：`currentChatId` 变化时替换地址，新建对话（ID 为空）去掉会话 ID；
-  地址变化（含浏览器前进、后退）时切换到对应会话；初始地址带会话 ID 时打开该会话。
-- 会话列表 Store 不感知路由；debug 模式的地址不含会话 ID，不做同步。
-- 侧栏账户信息由 chat、debug 装配函数分别从各自入口的用户 Store 提供，侧栏组件不直接读取 Store。
-
-portal 模式（`view/portal/`）复用 chat 模式装配，左侧使用 `left-sidebar/portal-conversation-list/`：
-按智能体分组展示门户历史对话（`/v3/portal/chat`），每组最多显示最近 5 条。当前智能体的分组以会话列表
-Store 为准，新建、重命名、删除即时生效；离开某个智能体时把其最新会话写回分组，并先用进入分组已有的会话填充会话列表，
-避免列表加载完成前显示上一个智能体的会话。展开其他智能体的分组时
-按智能体查询最近 5 条会话（`/v3/application/:id/chat/1/5`）刷新分组，失败时保留分组接口返回的会话。点击当前智能体的会话
-直接切换，点击其他智能体的会话跳转到对应地址。
-点击智能体行选中该智能体并进入其新建对话（`portal-application`），没有选中会话时该行高亮；点击右侧箭头只展开或收起会话。
-
-门户首页 `portal-home` 也渲染该页面：地址中没有智能体时不请求会话与智能体信息，分组加载后替换到第一个
-智能体的 `portal-application`；没有可访问的智能体时消息区显示“暂无可用智能体”空状态。
-门户主区域使用 `main/portal-chat-panel`，不修改共用的 `main/chat-panel`：标题栏的新建对话使用门户侧栏 Store 的
-`newConversation`，没有当前智能体时以空状态代替消息列表。没有当前智能体时，
-chat 装配函数通过 `disabled` 禁用输入框与附件。
-
-“全部智能体”（`portal-application-list`）在同一门户布局中把主区域换成 `main/portal-application-panel`：
-按名称搜索（输入防抖 300ms）并以卡片展示智能体，点击卡片或悬停显示的“去对话”进入该智能体的新建对话。
-卡片由 `components/portal-application-cards` 提供，全部智能体页与选择智能体抽屉共用。
-
-侧栏“新建对话”与侧栏收起时标题栏的“新建对话”（门户视图向 `ChatHeader` 传入 `newConversation`）
-在当前智能体中新建；没有当前智能体时（全部智能体页、门户首页空状态）打开 `SelectApplicationDrawer` 选择智能体，抽屉的搜索条件与结果独立于全部智能体页，每次打开重新查询。
-抽屉自己管理显隐并暴露 `open()`；门户视图持有抽屉的 ref，通过 `createPortalConversation` 的
-`openApplicationSelector` 传入门户侧栏 Store。Store 的 `newConversation` 有当前智能体时打开其
-`portal-application` 地址，地址中会话 ID 清空后由 chat 装配函数的会话同步新建对话。
-
-### 知识库详情上下文装配
-
-上下文只维护共享详情数据、更新能力及多个子页面共用的接口。仅由单个子页面使用的接口，
-在该页面内部按资源范围选择，不为单页接口增加 context 配置或转发 getter。
-定时同步接口属于定时同步页自身职责；未提供对应范围接口时，不回退到 Workspace，
-也不为 Workspace 共享只读资源增加写接口。同步接口由 `useKnowledgeDetailContext` 提供给定时同步页，
-按现有四套 Sync API 的真实方法集合装配，不扩展接口。
-
-`provideKnowledgeDetailContext` 在详情入口装配并提供上下文，`useKnowledgeDetailContext` 供子页读取。
-基础设置、文档策略、定时同步及资料库统一通过 `useKnowledgeDetailContext` 读取同一份上下文；
-不为设置页重建或覆盖 `resourceApi`。定时同步读取当前
-`resourceApi.sync`。Workspace 共享只查询设置和日志，表单只读且不显示保存。
-上下文保留各范围完整 API 的真实方法集合；只读范围未提供的写方法不补造，
-调用处进行类型收窄，不将只读 API 当作可写 API。
-上下文内部按响应式资源范围选择各范围现有完整 Knowledge、Sync、Document、Tags API 对象，
-不对外暴露 `resourceScope`；消费方通过 `utils/resource-context.ts` 的现有方法读取和判断资源范围。
-统一通过响应式 `resourceApi.knowledge / sync / document / tags` 提供接口，脚本调用不需要 `.value`；
-详情查询与保存使用同一个完整 Knowledge API 对象，不存在的设置模块保持 undefined。
-返回列表路由独立提供；不要在 setup 时解构 `resourceApi` 内的具体 API，以免固定为旧范围的对象。
-不根据 URL 猜测来源，不为补齐方法集合构造请求，不让缺失模块回退 Workspace。
-目前仅详情入口及 setting 下的基础设置、文档策略、定时同步页面采用上下文 API；
-library 下的文档、标签与迁移入口通过 `useKnowledgeDetailContext` 读取现有 API，
-`resourceApi.document / tags` 已装配四套现有 API 对象；Workspace 共享保留原有只读方法集合。
-查询和维护均通过 `resourceApi.document / tags / workflow / knowledge` 的现有完整 API 对象进行；
-维护操作分别传给已有操作组件；不为只读范围补造写接口。共享标签页按现有无查询参数接口读取，
-在本地按标签名称筛选；缺失的维护方法通过可选调用跳过，不增加方法存在性显隐判断。
-同步日志通过完整 Sync API props 请求。展示组件不接收上下文 API。
-System 飞书专用保存方法尚未提供，基础设置沿该范围现有 `putKnowledge` 协议；Workspace 飞书保留专用方法。
-
-四套知识库详情菜单及来源导航已统一，详情内的 `routeNames / routeParams` 合入同一份详情上下文。
-独立文档详情及全屏工作流没有详情容器父级，直接使用自身路由数据处理导航，不依赖详情注入。各范围接口存在差异，API 模块保持原实现；目前已补齐 sync 与 library 的现有接口装配与消费，
-其他模块后续按每套真实接口分别接入，不将菜单完整度视为接口接入完成。
-
-### 资料库上下文与只读范围
-
-`useKnowledgeDetailContext` 复用详情数据和知识库 ID，文档及标签查询通过
-`resourceApi.document / tags` 访问四套当前范围的完整 API，不回退到 Workspace。
-文档页通过 `onMounted` 首次加载并启动轮询，卸载时停止轮询；不监听知识库、工作空间或资源范围来重置筛选、分页和选择。
-标签页通过 `onMounted` 首次加载，不监听路由参数或资源范围来重置状态；搜索和维护操作后显式刷新。
-Workspace 共享文档保留查询和标签展示，标签页保留标签组查询；只支持共享接口现有的方法。
-创建标签弹窗必须由入口传入完整 Tags API，不再默认使用普通 Workspace；文档标签添加及迁移的
-候选查询同样通过资料库上下文选择。图片页保持占位，不配置不存在的接口。
-
-资料库和 Sync 所有消费方统一通过 `resourceApi.xx` 的响应式 getter 访问完整 API，
-不增加查询／维护双入口或模块别名。只读范围和缺失模块保留现有业务边界；
-Document、Tags 与 Sync 在上下文类型中保留共有方法为必填，将部分范围缺失的方法标记为可选；
-调用处使用 `?.`，不补造方法或跨范围回退。
-未约定的 API 方法、上下文入口或返回结构必须先与用户商议并确认后再实现。
-
-资料库模板不使用“API 对象存在且包含某方法”的组合判断来控制操作显隐；
-只保留原有业务资源范围条件，接口联合类型的收窄不增加可见性规则。
-
-知识库详情上下文仅保留两个公开入口：父页面通过 `provideKnowledgeDetailContext` 提供，
-子页面、弹窗和 Action 通过 `useKnowledgeDetailContext` 获取同一对象。接口统一为 `resourceApi.xx`，
-不增加设置、导航、资料库或同步专属 Context hook，也不增加查询／维护接口别名。
-
-`useKnowledgeDetailContext()` 的无参数用法保持不变。仅支持部分资源范围的消费方可声明
-`useKnowledgeDetailContext({ resourceScopes: [...] })`，API 类型从对应范围现有完整对象推导，
-不新增 Context hook 或补造方法。转换页声明 Workspace 普通、System 资源管理、System 共享三种范围；
-共享只读范围由上下文统一提示并返回该来源的文档页，保留知识库类型、query 和 hash。
-范围变化后再次校验；不支持的范围不能通过类型收窄后的入口发送请求。
-
-基础设置和文档处理策略页同样通过 `resourceScopes` 声明现有可管理的三个范围，
-不在页面探测 Knowledge API 是否存在保存方法。飞书专用保存按 Workspace 来源选择，System 沿用通用保存。
-定时同步仍支持共享只读查询，保存保留原有共享只读范围边界，不探测保存方法是否存在。
-
-Sync 的上下文类型保留共有查询方法为必填，只有部分范围提供的保存方法标记为可选，
-调用使用 `resourceApi.sync.putKnowledgeSyncSetting?.(...)`。此处理仅作用于类型，
-运行时仍使用各范围现有完整 API 对象；共享范围不存在的保存方法保持 undefined，不发请求、不显示保存成功。
-
-Tags 沿用 Sync 的可选方法类型规则，四套完整 API 对象由上下文按范围选择。
-`getKnowledgeTags` 为共有方法；创建、编辑、删除、导入、模板下载及文档标签关联按实际方法集合可选调用。
-缺失方法不触发成功提示或刷新，loading 清理覆盖未发出请求的情况。标签操作组件的 API props 类型
-从 `useKnowledgeDetailContext` 的 `resourceApi.tags` 推导，不固定为 Workspace 可写类型。
-
-Document 沿用 Sync、Tags 的可选方法类型规则；四套 API 保持实际对象与方法集合，
-`getDocumentPage` 为共有必填方法，其余仅部分范围提供的方法通过 `?.` 调用。
-文档 Action、上传和导入组件的完整 API props 类型从 `useKnowledgeDetailContext` 的
-`resourceApi.document` 推导，不固定为 Workspace 可写类型，不增加方法存在性判断或接口别名。
-缺失方法不触发成功提示、关闭弹窗、刷新或修改列表，loading 正常清理；名称编辑未发请求时返回原名称。
-工作流文档导入读取已有 `resourceApi.workflow`，缺失模块不回退 Workspace。
+# 页面职责与组织
+
+本文维护页面边界、功能本地目录和关键业务约束。请求协议见
+[API_README.md](../api/API_README.md)，路由与导航见
+[ROUTE_README.md](../router/ROUTE_README.md)，公共组件接口与生命周期见
+[COMPONENT_README.md](../components/COMPONENT_README.md)，画布内部规则见
+[WORKFLOW_README.md](../workflow-canvas/WORKFLOW_README.md)。
+
+## 功能本地组织
+
+- 路由页使用 `views/<feature>/index.vue`；多个独立页面按业务职责拆分子目录，不平铺无关页面。
+- 普通子组件放在功能的 `components/`；Drawer 留在所属流程目录，命名 `XxxDrawer.vue`；
+  Dialog 命名 `XxxDialog.vue`。按钮命名遵循组件文档，不把 Dialog 与 Drawer 混用。
+- 完整业务流程可使用 `create-application/` 等目录，入口、浮层及配套逻辑一起维护。
+- 单页类型、常量、函数留在功能内；同一功能复用代码放在最近共同目录。跨功能复用再按专题规则提升。
+- TypeScript 文件名表达具体职责，顶部注明用途；注释解释业务约束和执行顺序。
+- 脚本按列表查询、批量操作等业务流程组织状态和方法，较长流程在确认、请求、刷新等关键点添加备注。
+- 模板不直接调用浮层 Ref 的 `open()`，通过 `handleOpenXxx` 语义方法打开。
+- 用户交互触发的联动优先使用 `change` 等事件；父级 Props、异步配置或多个来源的变化才使用 `watch`。
+- 创建、保存、提交使用内容容器或按钮 loading，不逐字段禁用，也不设置提交态的 `el-form.disabled`。
+  入口保留重复提交保护，关闭、取消、步骤切换可按提交状态禁用；只读、权限、字段联动和选项加载禁用保留。
+- 新功能权限边界遵循 [AGENTS.md](../../AGENTS.md)，创建或导入后原有用户基础资料刷新保留。
+- 顶部、行内、菜单和批量操作前添加中文用途注释，批量操作明确标注“批量”。
+- 菜单内含自带浮层的 Action 时复用组件的 `persistent`，不自行维护菜单挂载状态。
+  常驻浮层与关闭后卸载浮层的清理遵循组件文档。
+
+`action-dropdown/` 优先用于 application、knowledge、model、tool 四类跨范围资源。
+文档和分段按现有需求使用各自 `action-dropdown/`，不据此扩展到所有普通页面。
+单文件 Action 平铺，多文件流程放在职责明确的子目录；公共浮层才提升到最近共同功能目录。
+
+## 页面功能索引
+
+新增、移动、重命名或改变路由页职责时更新本表。路径均相对 `src/views/`；同一行列出的子目录
+各自以 `index.vue` 为入口，不登记内部组件或函数。
+
+| 功能目录                                                                              | 当前职责                                     |
+| ------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `home/`、`system/home/`                                                               | 工作空间／系统首页统计、资源概况和排行       |
+| `application/`、`knowledge/`、`model/`、`tool/`                                       | 工作空间资源列表、创建及维护                 |
+| `application-detail/`                                                                 | 智能体详情上下文与资源详情布局               |
+| `application-detail/overview/`、`setting/`                                            | 概览、简易智能体设置                         |
+| `application-detail/chat-user/`、`chat-log/`                                          | 对话授权、日志与标注                         |
+| `application-detail/integration/`                                                     | 接入第三方占位页                             |
+| `knowledge-detail/`                                                                   | 四范围知识库详情、菜单与上下文               |
+| `knowledge-detail/library/document/`、`tags/`                                         | 文档及标签维护                               |
+| `knowledge-detail/library/image/`                                                     | 图片占位页                                   |
+| `knowledge-detail/recall-test/`、`question/`、`dictionary/`                           | 检索优化占位页                               |
+| `knowledge-detail/chat-user/`、`external-retrieval/`                                  | 对话授权与外部检索配置                       |
+| `knowledge-detail/setting/base/`、`document-strategy/`、`scheduled-sync/`             | 基础设置、文档策略、定时同步与日志           |
+| `knowledge-detail/workflow-transform/`                                                | 非工作流知识库转换说明与确认                 |
+| `document-detail/`                                                                    | 四范围文档分段查询、详情及可管理范围维护     |
+| `workflow/application/`、`tool/`、`knowledge/`                                        | 全屏画布、加载、保存、发布、历史、模板与调试 |
+| `trigger/`                                                                            | 触发器列表、任务配置、启停及执行记录         |
+| `system/resource-management/application/`、`knowledge/`、`model/`、`tool/`            | 跨工作空间资源管理                           |
+| `system/shared-resources/knowledge/`、`model/`、`tool/`                               | System 共享资源管理                          |
+| `system/identity/users/`、`groups/`、`roles/`、`workspaces/`                          | 用户、用户组、角色与工作空间管理             |
+| `system/identity/resource-authorization/`                                             | 分类资源授权                                 |
+| `system/chat-management/users/`、`user-groups/`、`authentication/`、`portal-setting/` | 对话用户、组、认证和门户设置                 |
+| `system/settings/theme/`、`authentication/`、`email/`                                 | 外观、登录认证与邮件设置                     |
+| `system/operate-logs/`                                                                | 操作日志与清除策略                           |
+| `login/`、`login/forgot-password/`                                                    | Admin 登录与找回密码                         |
+| `chat/`、`portal/`                                                                    | 单应用与门户对话                             |
+| `chat/login/`、`chat/error/`、`error/`                                                | Chat 登录、Chat／Admin 错误页                |
+| `details-demo/`                                                                       | 临时执行详情预览                             |
+
+## 资源列表与详情
+
+四类资源的范围定义由路由文档维护，完整 API 选择规则由 API 文档维护。
+资源卡片放在基础资源目录 `<resource>-card/`，System 页面复用，不复制展示实现。
+卡片只负责展示、选择和操作插槽；页面按场景组合 Action，传入中文 `label`、资源及完整 API。
+跨范围 Action 留在基础资源目录，仅 System 使用的 Action 留在对应 System 功能目录。
+
+- 单项移动复用 `MoveToDialog`，具体目录转出后局部移除，“全部”目录保留；批量移动和删除由页面管理。
+- 切换文件夹退出批量模式，搜索／刷新清空选择；创建或导入成功保留资料刷新和原有导航。
+- 普通 Workspace 详情返回列表时恢复所属 `folderId`；共享知识库返回 `folderId: 'shared'`。
+  文件夹地址同步与工作空间切换规则见路由文档。
+- `application-detail/context.ts` 提供只读详情、替换和刷新；完整响应局部替换，部分响应重新查询。
+  切换二级菜单不重复挂载详情容器。
+- 创建模型入口接收完整 Model API；创建成功刷新基础资料后通知调用方刷新选项。
+- 工具表单按类型放在 `tool-form/`，共用参数及 Python 设置放在 `tool-form/component/`。
+  创建和编辑复用同一表单，不把不同类型字段合并成通用表单。
+- `ToolCard` 点击工作流进入画布，其他类型调用编辑 Action 的同一表单实例；编辑、启停成功局部更新。
+  商店列表由页面加载，卡片和版本更新按钮不重复查询。
+- 工具头像由 `MkEditAvatar` 暂存文件，校验后先上传再保存；上传成功后清理暂存文件，避免保存失败后重复上传。
+- Python 生成入口由 `CodeGenerate` 选择 Tool／Model API，复用 `GenerateContent`；全屏替换只修改草稿，确认后回写。
+- System 模型／工具使用表格，保留既有权限、引用数量删除提示和末页回退；不新增不存在的创建／导入能力。
+  工作空间列与选项仅企业版显示，筛选 `workspace_ids` 使用 JSON 数组字符串。
+- Workspace 共享知识库只读；System 共享资源页面按自身 API 维护，不组合 Workspace 文件夹移动等操作。
+
+资源授权和关联资源入口按需挂载公共抽屉，关闭动画结束后卸载。授权使用资源数据的
+`workspace_id`；关联资源抽屉的查询与工作空间展示规则见组件和 API 文档。
+
+## 详情布局与知识库上下文
+
+`layout/ResourceDetailLayout.vue` 提供侧栏和固定标题栏。子页声明 `ResourceDetailPageProps`，
+普通页使用默认标题；`defineExpose({ customHeader: true })` 配合 Teleport 到 `headerTarget`
+自定义标题、搜索及操作；`hideHeader: true` 隐藏整个标题栏且优先于自定义标题。
+不再嵌套页面布局、创建 Header 注入或增加路由字段。
+
+`knowledge-detail/context.ts` 仅通过 `provideKnowledgeDetailContext` 和
+`useKnowledgeDetailContext` 公开详情、更新能力、ID、来源导航及完整 API。
+`resourceApi.knowledge / scheduledSync / document / tags / chatUser` 按当前范围响应式读取，无需 `.value`，
+不要在 setup 时解构具体 API。`workflow` 当前仅普通 Workspace 提供，其他范围不回退。
+共有查询方法必填，部分范围缺失的方法可选调用；未发请求时不提示成功、不关闭、不刷新或修改快照，loading 正常清理。
+不增加查询／维护双入口、接口别名或专属 Context hook，也不以方法存在性新增操作显隐规则。
+
+仅支持部分来源的消费方可传 `useKnowledgeDetailContext({ resourceScopes: [...] })`，
+由上下文统一校验并返回来源文档页，保留类型、query 和 hash。未约定接口或返回结构先与用户确认。
+基础设置、文档策略、定时同步及转换说明允许 Workspace 共享访问；本地设置可编辑，仅隐藏保存／转换按钮，
+提交入口同时阻止共享写入。System 文档、标签与分段 API 已装配，具体服务能力仍需对应部署支持。
+知识库全屏 WorkflowView 的加载、保存、模型查询仍直接使用 Workspace API，其他来源仅完成导航，不能视为范围接入完成。
+
+### 创建与设置
+
+四类知识库创建入口集中在 `knowledge/create-knowledge/`：`BaseKnowledgeDialog`、
+`WebKnowledgeDrawer`、`LarkKnowledgeDialog`、`WorkflowKnowledgeDialog`。
+`KnowledgeBaseForm` 负责名称、描述及 Embedding 选择，内部按范围查询模型；未选择时默认首个可用模型，
+刷新不覆盖用户选择。创建浮层接收完整 Knowledge API，工作流创建使用其 `postKnowledgeWorkflow`。
+
+`DocumentStrategyForm` 由 Web 创建、文档上传及策略设置复用；视觉增强仅在启用、切换策略或回填启用配置时
+查询对应模型／工具，刷新模型不请求工具。Web 创建两步，策略设置回填独立草稿并单独保存 `doc_strategy`，下次同步生效。
+基础设置保留未编辑的来源 `meta` 和顶层上传限制；更换向量模型先确认、保存，再向量化。
+向量化失败保留原比较基准以便重试；Workspace 飞书使用专用保存，System 使用通用保存。
+
+定时同步提供设置与日志；查询成功后才允许保存，成功以规范化响应更新草稿和详情。
+复用周期及同步方式常量，支持日、周、月、间隔和 Cron，间隔至少 5 分钟；完整 Cron 由后台校验。
+日志页按需挂载 `SyncLogTable`，传完整 API，仅展示定时任务，不轮询；跳过执行展示原因。
+
+### 文档列表与导入
+
+`library/document/index.vue` 管理查询、分页、选择、启停及刷新；Action 管理各自请求和浮层。
+类型统一读取路由 `type`，使用 `KNOWLEDGE_TYPE_KEY`，不逐层传递类型 Prop。
+挂载时查询并启动 6 秒轮询，请求结束后安排下一次；静默刷新保留筛选、页码和当前页选择，
+操作中推迟轮询，卸载后停止。创建者选项打开或远程搜索时加载，不在页面进入时预查。
+
+- 名称使用 `MkEditName`，最长 128，禁止 `: \ / ? * [ ]`；成功按 ID 更新名称与时间。
+- 文件状态、启用、命中处理用 `MkTableFilter single`，标签用 `cascader`；改变条件回第一页并清空选择，保留其他条件。
+  状态查询同步更新 `status` 与 `task_type`；布尔 false 保留，“全部”省略条件；标签传叶子 ID 或 `NO_TAG`。
+- 任务解析及筛选统一在 `document/status.ts`，展示由 `DocumentStatus.vue` 负责；不复用执行记录状态。
+  汇总优先级为取消中、执行中、排队中、失败、取消完成、成功；忽略未知和 n，保留取消完成显示成功的既有规则。
+- 文档 Action 按 embedding、generate-questions、setting、setting-tags、tokenize、export、sync、migrate 等职责分组，
+  通过 `action-dropdown/index.ts` 导出。打开前快照目标，单项和批量使用真实对应接口，共用页面操作 loading。
+- 删除和同步先确认；成功清空选择刷新，导出／下载保留选择。启停成功后才回显，不在请求前改变状态。
+- 生成问题复用 `GenerateQuestionsDialog`，向量化与生成可选分段状态范围，分词处理全部状态。
+- 单项 Web 设置保留来源 meta，批量隐藏地址／选择器并使用顶层 `allow_download`。
+- Web、飞书提供同步；工作流仅 Web 来源文档支持单项同步，本地上传文档不提供；手动同步不写定时日志。
+- 批量 More 使用 `hide-when-empty` 判断标准插槽，浮层生命周期遵循公共菜单保留规则。
+- Workspace 共享隐藏选择、操作和批量入口，名称只读；标签加号保留禁用展示，不探测 API 方法控制显隐。
+
+通用知识库通过 `MkTable.body-prepend` 组合 `MkQuickCreate`；页面创建请求成功才调用 `close()`，失败保留草稿。
+快速创建不插入占位数据，也不计入分页与选择。
+
+通用上传由 `upload-document/` 管理，Web／飞书／工作流导入由 `import-document/` 管理独立 Drawer。
+复用 `MkDragUpload` 和 `DocumentStrategyForm`，传完整 Document API；使用成功文件 ID，不二次上传。
+文本直接导入提交文件 ID 与策略；生成预览才请求 split，预览可本地编辑／删除，最终创建使用编辑后结果。
+预览编辑复用 `ParagraphForm`、`ParagraphQuestions`，不传已有分段 ID，不即时写入问题关联。
+表格／QA 支持模板下载；飞书懒加载仅展开时查子目录，已导入项不可取消，不在前端递归展开文件夹。
+工作流导入执行已发布版本，复用知识库调试的 DataSource、KnowledgeBase、Result 三步流程。
+本地文件校验上传成功及 `file_id`，远程工具数据源保留其文件／目录协议。
+导入成功清空搜索、筛选并回第一页，失败保留文件、选择与策略。
+
+### 标签管理
+
+`library/tags/` 按标签组前端分页，再展开标签值；`MkTable.selectionGroupKey="key"`
+联动组内选择，统计与删除按实际标签值数量。普通查询将名称传后端，共享无参数查询后本地筛选。
+`CreateTagDialog` 创建多行组合或为 `open(key)` 添加值；`EditTagDialog` 只重命名或编辑单值，
+保留完整 id、key、value，不模拟多行保存。名称／值上限 64／128，提交清理可编辑文本并检查重复。
+`ButtonImportTags` 内聚 XLS／XLSX 导入及模板下载，失败保留文件。
+
+`AssociatedDocumentDrawer` 从上下文读取 Document API，按已关联／未关联切换，搜索与布尔启用筛选可组合；
+切换、分页和搜索清空选择，变更刷新数量，末页为空回退。
+文档 `DocumentTags`、标签 Drawer 和批量 Action 各自维护添加弹窗；添加候选仅取前 100 组并本地搜索，
+不禁选已关联值，后台去重。创建候选成功重载但不自动选择。删除仅解除文档关联，不删除知识库标签。
+
+## 文档分段
+
+`document-detail/context.ts` 装配四范围完整 Document／Paragraph API 和返回导航，
+无注入时按当前路由创建上下文，供导入预览复用。页面提供上下文；Action 接收选定 Paragraph API，
+`paragraph-dialog/` 直接读取上下文，不透传 API。共有查询必填，维护方法按真实差异可选。
+Workspace 共享只读，隐藏创建、编辑、排序、关联修改及批量操作；缺少详情接口保留默认标题，不回退。
+
+主区通过 `MkInfiniteScroll` 加载分段，侧栏定位已加载卡片并同步高亮；全选只覆盖已加载数据，追加保留选择。
+搜索／新增／删除／迁移通过 `refreshParagraphs()` 回第一页并清理选择；编辑与启停按 ID 局部替换，
+不匹配筛选时刷新。不补偿分页偏移或改写服务端总数。
+
+`action-dropdown/move/useParagraphSort.ts` 统一两侧 `useSortable`、位置请求、快照恢复和 loading。
+菜单及拖拽共用 `putParagraphPosition`；成功本地同步受影响位置，失败恢复顺序，不重载分页。
+普通 DOM 承载排序，不叠加 TransitionGroup；目录链接禁原生拖动但不阻断 Sortable。
+拖拽仅覆盖已加载数据，保留原生链接／按钮交互；批量、加载、浮层、确认或位置保存中禁用。
+菜单方向类型留在 move 目录，上下移动使用相邻真实位置，置顶为 1，置底以末段位置和总数兜底。
+
+迁移和生成问题各维护独立单项与批量 Action，打开时固定目标，浮层关闭后卸载。
+迁移允许同知识库其他文档，排除当前文档；成功刷新分段。生成问题隐藏状态范围，提交后仅清空选择，不重载列表。
+批量删除留在页面，确认前快照目标；取消或失败保留选择。更多菜单展开状态只控制操作区显隐，挂载仍由 persistent 管理。
+
+`paragraph-dialog/` 使用 `CreateParagraphDialog` 和 `ParagraphDialog`（详情／编辑），组合
+`ParagraphForm`、`ParagraphPreview`、`ParagraphQuestions`。创建可指定插入位置；正文表单支持 Markdown 和知识库图片上传。
+问题区使用远程候选和即时关联／解除，不删除问题本身；无分段 ID 时保存本地问题草稿，随新增提交。
+正文保存不提交或回填 `problem_list`，避免覆盖并行关联操作；取消编辑不撤销问题修改。
+问题区请求状态独立，不阻止正文保存／关闭；共享模式只展示，不查询可关联候选。
+详情查询失败可重试，失败保留草稿；标题最多 256，正文界面最多 100000 字符。
+
+## 工作流页面
+
+三个入口均为 `views/workflow/<resource>/index.vue`，使用 `WorkflowViewLayout`。
+View 负责路由、资源与模式、图加载、保存／发布／调试编排；画布公开接口及节点行为见画布文档。
+整条页面操作共用一个 loading，最外层 finally 释放，内部保存／加载只返回 Promise。
+
+- 自动保存默认关闭，按 `workflowAutoSave:<resource>:<id>` 独立记录；开启后每 60 秒保存未提交修改。
+  加载、保存、发布、历史和退出确认中跳过；成功只更新本次快照，请求期间继续编辑仍算未保存；失败留待重试。
+- 保存使用规范化 `getGraphData()`；默认模型与图一起持久化，失败回滚已保存配置并保持抽屉编辑草稿。
+- 默认模型抽屉接收完整 Model API；“应用到所有节点”递归修改图，保留自定义配置及禁用功能，不自动提交模型草稿。
+- 发布历史入口各自查询版本，共用纯 UI `publish-history/`；第一次预览保存草稿，关闭恢复，恢复版本只回编辑态，后续保存。
+  版本缺少默认模型时保留当前配置；更新说明后端支持情况见 API 文档。
+- 智能体发布先校验，再打开发布内容表单，提交先保存再发布；失败保留表单。
+- 模板中心共享 UI 在 `workflow/components/template-store/`，业务入口查模板，View 确认覆盖、提交并重载详情和保存基准。
+  创建模板由资源创建流程负责，取消／失败保留模板中心。
+- 调试与导出先保存未提交修改，保存失败不继续；打开历史、模板或默认模型时按原流程关闭调试。
+- 智能体复用对话模块 DebugPanel；工具使用 debug Drawer、SSE 和执行详情；知识库保留任务轮询与导入 Action。
+  客户端停止读取不等于服务端停止任务。
+- 知识库导出仅工作流 `.kbwf`；导入确认覆盖后直接上传，不先保存旧草稿，成功重载；取消／失败保留图。
+  正式导入文档要求已发布；转换使用 Knowledge API，保留已有文档，不能用保存代替转换。
+- 返回方法集中在各资源 `navigation.ts`；历史模式先退出预览，编辑态保留保存并退出／直接退出确认。
+  当前没有通用路由离开或浏览器关闭守卫。
+- 工具、知识库执行记录抽屉按需挂载，关闭后卸载；知识库记录每 6 秒刷新，关闭停止。
+
+## 其他页面约束
+
+- 首页组件位于 `home/components/`，排行位于 `components/ranking/`。完整 Homepage API 和 workspaceId 由 View 传入。
+  智能体筛选只影响趋势；日期复用 MkDateRange，默认过去 7 天；占比使用工作空间同期总量，累计活跃人次为每日人数之和。
+  失败不伪装成零。快捷创建复用资源入口，`fitTriggerWidth` 仅显式开启时测量触发器。
+- 触发器表单共用创建／编辑，保留任务 ID 和参数；资源模式固定单任务，完整输入定义不足时补查详情。
+  保存校验全部折叠任务；参数初始化不覆盖已配置值，移除事件引用时恢复自定义默认值。
+- 智能体／知识库对话用户页使用双栏布局和当前页授权；知识库从 context 取四范围 ChatUser API。
+  自动授权立即保存，手动保存只提交当前页；请求共用 loading 与 inert，失败保留勾选。
+  授权人数取 `authorized_count`，不以分页勾选推算。
+- 对话日志筛选、导出使用同组查询；无勾选导出筛选结果，日期清空禁用导出。
+  清除策略使用专用接口、弹窗自身 loading；添加知识库固定所选对话 ID。
+  `ChatLogDetailDrawer` 目前正文为空，上一条／下一条与跨页由页面管理。
+- 外部检索页当前直接使用 Workspace ExternalRetrieval API，尚未按四范围装配；仅 Workspace 共享开关禁用。
+  其他范围的 API 文件虽存在，页面仍未选择对应 API。示例与地址来自响应，只读展示／复制，不在前端拼接。
+- 门户设置已通过 Portal API 持久化，JSON 保存开关、认证及 `cross_domain_list`，FormData 保存名称／Logo。
+  成功以完整响应回显，保留现有编辑权限；认证选项来自 LoginSetting，跨域地址按行清理，取消不回写。
+- 用户导入、改密、批量角色／配额流程留在各自业务目录；工作空间成员按用户联动角色行选择，
+  删除按 `user_relation_id` 去重，不按用户 ID 丢弃角色记录。
+- 登录页使用 `formEl.validate` 回调和清晰的 LDAP／本地分支，不额外抽象或改写提交控制流程。
+- Chat／Portal 页面以 auth token 为面板 key，token 变化重建并加载用户档案；路由认证见路由文档。
+  会话装配在 conversation-panel，列表 Store 不感知 Router；门户复用 chat 装配，保留各智能体最近会话分组。
+  没有当前智能体时不查询其信息／会话、禁用输入，分组加载后选首个；无可用智能体显示空态。
+  全部智能体与选择抽屉复用卡片，抽屉每次打开重新查询，搜索状态独立。
diff --git a/ui/src/views/document-detail/action-dropdown/generate-questions/BatchGenerateQuestionsAction.vue b/ui/src/views/document-detail/action-dropdown/generate-questions/BatchGenerateQuestionsAction.vue
index 07742242d4f..a70ea9435a0 100644
--- a/ui/src/views/document-detail/action-dropdown/generate-questions/BatchGenerateQuestionsAction.vue
+++ b/ui/src/views/document-detail/action-dropdown/generate-questions/BatchGenerateQuestionsAction.vue
@@ -1,13 +1,13 @@
 <script setup lang="ts">
 import { nextTick, ref, useTemplateRef } from 'vue'
-import type ParagraphApi from '@/api/admin/workspace/knowledge/paragraph'
+import type { DocumentParagraphApi } from '@/views/document-detail/context'
 import type { RelatedQuestionsConfig } from '@/api/types'
-import GenerateQuestionsDialog from '@/components/business/generate-questions/GenerateQuestionsDialog.vue'
+import GenerateQuestionsDialog from '@/components/business/generate-questions/index.vue'
 import { MsgSuccess } from '@/utils/message'
 
 defineOptions({ name: 'BatchGenerateQuestionsAction' })
 const props = defineProps<{
-  api: typeof ParagraphApi
+  api: DocumentParagraphApi
   knowledgeId: string
   documentId: string
   paragraphIds: string[]
@@ -37,22 +37,23 @@ function handleOpenDialog() {
 function handleSubmit(config: RelatedQuestionsConfig) {
   if (props.disabled || loading.value || !targetParagraphIds.value.length) return
   loading.value = true
-  return props.api
-    .putGenerateParagraphQuestions(targetKnowledgeId.value, targetDocumentId.value, {
-      ...config,
-      paragraph_id_list: [...targetParagraphIds.value],
-    })
-    .then(() => {
-      MsgSuccess('操作成功')
-      refreshOnClosed.value = true
-      dialogRef.value?.close()
-    })
-    .catch(() => {
-      // 请求层统一提示错误，保留生成配置。
-    })
-    .finally(() => {
-      loading.value = false
-    })
+  return (
+    props.api
+      .putGenerateParagraphQuestions?.(targetKnowledgeId.value, targetDocumentId.value, {
+        ...config,
+        paragraph_id_list: [...targetParagraphIds.value],
+      })
+      .then(() => {
+        MsgSuccess('操作成功')
+        refreshOnClosed.value = true
+        dialogRef.value?.close()
+      })
+      .catch(() => {
+        // 请求层统一提示错误，保留生成配置。
+      }) ?? Promise.resolve()
+  ).finally(() => {
+    loading.value = false
+  })
 }
 
 function handleClosed() {
diff --git a/ui/src/views/document-detail/action-dropdown/generate-questions/GenerateQuestionsAction.vue b/ui/src/views/document-detail/action-dropdown/generate-questions/GenerateQuestionsAction.vue
index 8c1aaa785e7..5371c0dbd20 100644
--- a/ui/src/views/document-detail/action-dropdown/generate-questions/GenerateQuestionsAction.vue
+++ b/ui/src/views/document-detail/action-dropdown/generate-questions/GenerateQuestionsAction.vue
@@ -1,13 +1,13 @@
 <script setup lang="ts">
 import { nextTick, ref, useTemplateRef } from 'vue'
-import type ParagraphApi from '@/api/admin/workspace/knowledge/paragraph'
+import type { DocumentParagraphApi } from '@/views/document-detail/context'
 import type { RelatedQuestionsConfig } from '@/api/types'
-import GenerateQuestionsDialog from '@/components/business/generate-questions/GenerateQuestionsDialog.vue'
+import GenerateQuestionsDialog from '@/components/business/generate-questions/index.vue'
 import { MsgSuccess } from '@/utils/message'
 
 defineOptions({ name: 'GenerateQuestionsAction' })
 const props = defineProps<{
-  api: typeof ParagraphApi
+  api: DocumentParagraphApi
   knowledgeId: string
   documentId: string
   paragraphId: string
@@ -38,22 +38,23 @@ function handleOpenDialog() {
 function handleSubmit(config: RelatedQuestionsConfig) {
   if (props.disabled || loading.value || !targetParagraphId.value) return
   loading.value = true
-  return props.api
-    .putGenerateParagraphQuestions(targetKnowledgeId.value, targetDocumentId.value, {
-      ...config,
-      paragraph_id_list: [targetParagraphId.value],
-    })
-    .then(() => {
-      MsgSuccess('操作成功')
-      refreshOnClosed.value = true
-      dialogRef.value?.close()
-    })
-    .catch(() => {
-      // 请求层统一提示错误，保留生成配置。
-    })
-    .finally(() => {
-      loading.value = false
-    })
+  return (
+    props.api
+      .putGenerateParagraphQuestions?.(targetKnowledgeId.value, targetDocumentId.value, {
+        ...config,
+        paragraph_id_list: [targetParagraphId.value],
+      })
+      .then(() => {
+        MsgSuccess('操作成功')
+        refreshOnClosed.value = true
+        dialogRef.value?.close()
+      })
+      .catch(() => {
+        // 请求层统一提示错误，保留生成配置。
+      }) ?? Promise.resolve()
+  ).finally(() => {
+    loading.value = false
+  })
 }
 
 function handleClosed() {
diff --git a/ui/src/views/document-detail/action-dropdown/index.ts b/ui/src/views/document-detail/action-dropdown/index.ts
index 2d8d8edd65b..baa89fffeba 100644
--- a/ui/src/views/document-detail/action-dropdown/index.ts
+++ b/ui/src/views/document-detail/action-dropdown/index.ts
@@ -2,5 +2,4 @@ export { default as BatchMigrateParagraphAction } from './migrate/BatchMigratePa
 export { default as MigrateParagraphAction } from './migrate/MigrateParagraphAction.vue'
 export { default as BatchGenerateQuestionsAction } from './generate-questions/BatchGenerateQuestionsAction.vue'
 export { default as GenerateQuestionsAction } from './generate-questions/GenerateQuestionsAction.vue'
-export { default as MoveParagraphAction } from './MoveParagraphAction.vue'
-export type { ParagraphMoveDirection } from './types'
+export { default as MoveParagraphAction } from './move/MoveParagraphAction.vue'
diff --git a/ui/src/views/document-detail/action-dropdown/migrate/BatchMigrateParagraphAction.vue b/ui/src/views/document-detail/action-dropdown/migrate/BatchMigrateParagraphAction.vue
index f7a29dfbb65..c61701a2b6c 100644
--- a/ui/src/views/document-detail/action-dropdown/migrate/BatchMigrateParagraphAction.vue
+++ b/ui/src/views/document-detail/action-dropdown/migrate/BatchMigrateParagraphAction.vue
@@ -1,11 +1,11 @@
 <script setup lang="ts">
 import { nextTick, ref, useTemplateRef } from 'vue'
-import type ParagraphApi from '@/api/admin/workspace/knowledge/paragraph'
+import type { DocumentParagraphApi } from '@/views/document-detail/context'
 import ParagraphMigrateDialog from './ParagraphMigrateDialog.vue'
 
 defineOptions({ name: 'BatchMigrateParagraphAction' })
 const props = defineProps<{
-  api: typeof ParagraphApi
+  api: DocumentParagraphApi
   knowledgeId: string
   documentId: string
   paragraphIds: string[]
diff --git a/ui/src/views/document-detail/action-dropdown/migrate/MigrateParagraphAction.vue b/ui/src/views/document-detail/action-dropdown/migrate/MigrateParagraphAction.vue
index 03d4bd423bc..2fafb0e29bf 100644
--- a/ui/src/views/document-detail/action-dropdown/migrate/MigrateParagraphAction.vue
+++ b/ui/src/views/document-detail/action-dropdown/migrate/MigrateParagraphAction.vue
@@ -1,11 +1,11 @@
 <script setup lang="ts">
 import { nextTick, ref, useTemplateRef } from 'vue'
-import type ParagraphApi from '@/api/admin/workspace/knowledge/paragraph'
+import type { DocumentParagraphApi } from '@/views/document-detail/context'
 import ParagraphMigrateDialog from './ParagraphMigrateDialog.vue'
 
 defineOptions({ name: 'MigrateParagraphAction' })
 const props = defineProps<{
-  api: typeof ParagraphApi
+  api: DocumentParagraphApi
   knowledgeId: string
   documentId: string
   paragraphId: string
diff --git a/ui/src/views/document-detail/action-dropdown/migrate/ParagraphMigrateDialog.vue b/ui/src/views/document-detail/action-dropdown/migrate/ParagraphMigrateDialog.vue
index 7dcabacb041..f0fd468b083 100644
--- a/ui/src/views/document-detail/action-dropdown/migrate/ParagraphMigrateDialog.vue
+++ b/ui/src/views/document-detail/action-dropdown/migrate/ParagraphMigrateDialog.vue
@@ -1,13 +1,11 @@
 <script setup lang="ts">
 import { computed, reactive, ref, useTemplateRef } from 'vue'
 import type { FormInstance, FormRules } from 'element-plus'
-import type ParagraphApi from '@/api/admin/workspace/knowledge/paragraph'
+import type { DocumentParagraphApi } from '@/views/document-detail/context'
 import KnowledgeApi from '@/api/admin/workspace/knowledge/knowledge'
-import DocumentApi from '@/api/admin/workspace/knowledge/document'
 import SystemKnowledgeApi from '@/api/admin/system/resource-management/knowledge/knowledge'
 import SystemSharedKnowledgeApi from '@/api/admin/system/shared-resources/knowledge/knowledge'
-import SystemDocumentApi from '@/api/admin/system/resource-management/knowledge/document'
-import SystemSharedDocumentApi from '@/api/admin/system/shared-resources/knowledge/document'
+import { useDocumentDetailContext } from '@/views/document-detail/context'
 import { isSystemResource, isSystemSharedResource } from '@/utils/resource-context'
 import type { DocumentItem, KnowledgeItem } from '@/api/types'
 import { MsgSuccess } from '@/utils/message'
@@ -15,11 +13,12 @@ import { getFileIconUrl } from '@/utils/icon'
 
 defineOptions({ name: 'ParagraphMigrateDialog' })
 const props = defineProps<{
-  api: typeof ParagraphApi
+  api: DocumentParagraphApi
   knowledgeId: string
   documentId: string
 }>()
 const emit = defineEmits<{ success: [paragraphIds: string[]]; closed: [] }>()
+const { resourceApi } = useDocumentDetailContext()
 
 // 固定本次勾选的分段，查询知识库与联动文档选项。
 const visible = ref(false)
@@ -63,19 +62,20 @@ function handleKnowledgeChange(knowledgeId: string) {
   documentOptions.value = []
   formRef.value?.clearValidate('document_id')
   if (!knowledgeId) return
+
   documentLoading.value = true
-  const requestApi = isSystemResource() ? SystemDocumentApi : isSystemSharedResource() ? SystemSharedDocumentApi : DocumentApi
-  return requestApi
-    .getAllDocuments(knowledgeId)
-    .then((documents) => {
-      documentOptions.value = documents.filter(({ id }) => id !== props.documentId)
-    })
-    .catch(() => {
-      // 请求层统一提示错误，文档保持空选。
-    })
-    .finally(() => {
-      documentLoading.value = false
-    })
+  return (
+    resourceApi.document
+      .getAllDocuments?.(knowledgeId)
+      .then((documents) => {
+        documentOptions.value = documents.filter(({ id }) => id !== props.documentId)
+      })
+      .catch(() => {
+        // 请求层统一提示错误，文档保持空选。
+      }) ?? Promise.resolve()
+  ).finally(() => {
+    documentLoading.value = false
+  })
 }
 
 // 迁移成功后关闭并通知页面移除本次分段，失败保留当前选择以便重试。
@@ -83,19 +83,20 @@ async function handleSubmit() {
   if (loading.value || optionLoading.value || !targetParagraphIds.value.length) return
   if (!(await formRef.value?.validate().catch(() => false)) || loading.value) return
   loading.value = true
-  return props.api
-    .putMigrateParagraphs(props.knowledgeId, props.documentId, migrateForm.knowledge_id, migrateForm.document_id, [...targetParagraphIds.value])
-    .then(() => {
-      MsgSuccess('迁移成功')
-      migrationSucceeded.value = true
-      visible.value = false
-    })
-    .catch(() => {
-      // 请求层统一提示错误，保留表单。
-    })
-    .finally(() => {
-      loading.value = false
-    })
+  return (
+    props.api
+      .putMigrateParagraphs?.(props.knowledgeId, props.documentId, migrateForm.knowledge_id, migrateForm.document_id, [...targetParagraphIds.value])
+      .then(() => {
+        MsgSuccess('迁移成功')
+        migrationSucceeded.value = true
+        visible.value = false
+      })
+      .catch(() => {
+        // 请求层统一提示错误，保留表单。
+      }) ?? Promise.resolve()
+  ).finally(() => {
+    loading.value = false
+  })
 }
 
 function handleBeforeClose(done: () => void) {
diff --git a/ui/src/views/document-detail/action-dropdown/MoveParagraphAction.vue b/ui/src/views/document-detail/action-dropdown/move/MoveParagraphAction.vue
similarity index 100%
rename from ui/src/views/document-detail/action-dropdown/MoveParagraphAction.vue
rename to ui/src/views/document-detail/action-dropdown/move/MoveParagraphAction.vue
diff --git a/ui/src/views/document-detail/action-dropdown/types.ts b/ui/src/views/document-detail/action-dropdown/move/types.ts
similarity index 100%
rename from ui/src/views/document-detail/action-dropdown/types.ts
rename to ui/src/views/document-detail/action-dropdown/move/types.ts
diff --git a/ui/src/views/document-detail/action-dropdown/move/useParagraphSort.ts b/ui/src/views/document-detail/action-dropdown/move/useParagraphSort.ts
new file mode 100644
index 00000000000..70411145ce7
--- /dev/null
+++ b/ui/src/views/document-detail/action-dropdown/move/useParagraphSort.ts
@@ -0,0 +1,110 @@
+/** 分段菜单移动和两处拖拽共用位置保存及本地排序。 */
+import type { Ref } from 'vue'
+import type { ParagraphItem } from '@/api/types'
+import type { useDocumentDetailContext } from '@/views/document-detail/context'
+import type { ParagraphMoveDirection } from './types'
+import { useSortable, type SortableChange } from '@/utils/use-sortable'
+import { MsgSuccess } from '@/utils/message'
+
+interface ParagraphSortOptions {
+  paragraphs: Ref<ParagraphItem[]>
+  loading: Ref<boolean>
+  disabled: Readonly<Ref<boolean>>
+  directoryRef: Ref<HTMLElement | undefined>
+  cardsRef: Ref<HTMLElement | undefined>
+  knowledgeId: Readonly<Ref<string>>
+  documentId: Readonly<Ref<string>>
+  resourceApi: ReturnType<typeof useDocumentDetailContext>['resourceApi']
+  onStart: () => void
+}
+
+export function useParagraphSort(options: ParagraphSortOptions) {
+  let sortSnapshot: ParagraphItem[] = []
+
+  // 菜单和拖拽均使用移动前的位置；索引只用于本地排序，不作为接口位置。
+  function savePosition(previousParagraphs: ParagraphItem[], oldIndex: number, newIndex: number, position = previousParagraphs[newIndex]?.position) {
+    const movedParagraph = previousParagraphs[oldIndex]
+    if (!movedParagraph || position === undefined || (oldIndex === newIndex && position === movedParagraph.position)) {
+      options.paragraphs.value = previousParagraphs
+      sortSnapshot = []
+      return
+    }
+    const oldPosition = movedParagraph.position
+    options.loading.value = true
+    return (
+      options.resourceApi.paragraph
+        .putParagraphPosition?.(options.knowledgeId.value, options.documentId.value, movedParagraph.id, position)
+        .then(() => {
+          // 拖拽已经移动数组；按当前索引移动到目标索引，两种入口得到相同的本地顺序。
+          const reorderedParagraphs = [...options.paragraphs.value]
+          const currentIndex = reorderedParagraphs.findIndex(({ id }) => id === movedParagraph.id)
+          if (currentIndex < 0) return
+          const currentParagraph = reorderedParagraphs.splice(currentIndex, 1)[0]!
+          reorderedParagraphs.splice(newIndex, 0, currentParagraph)
+          options.paragraphs.value = reorderedParagraphs.map((paragraph) => {
+            let nextPosition = paragraph.position
+            if (paragraph.id === movedParagraph.id) nextPosition = position
+            else if (oldPosition < position && nextPosition > oldPosition && nextPosition <= position) nextPosition -= 1
+            else if (oldPosition > position && nextPosition >= position && nextPosition < oldPosition) nextPosition += 1
+            return nextPosition === paragraph.position ? paragraph : { ...paragraph, position: nextPosition }
+          })
+          MsgSuccess('移动成功')
+        })
+        .catch(() => {
+          options.paragraphs.value = previousParagraphs
+        }) ??
+      Promise.resolve().then(() => {
+        options.paragraphs.value = previousParagraphs
+      })
+    ).finally(() => {
+      options.loading.value = false
+      sortSnapshot = []
+    })
+  }
+
+  function handleMoveParagraph(paragraph: ParagraphItem, direction: ParagraphMoveDirection) {
+    if (options.loading.value) return
+    const previousParagraphs = [...options.paragraphs.value]
+    const oldIndex = previousParagraphs.findIndex(({ id }) => id === paragraph.id)
+    if (oldIndex < 0) return
+    const newIndex = direction === 'top' ? 0 : direction === 'bottom' ? previousParagraphs.length - 1 : oldIndex + (direction === 'up' ? -1 : 1)
+    if (newIndex < 0 || newIndex >= previousParagraphs.length) return
+    const position = direction === 'top' ? 1 : previousParagraphs[newIndex]!.position
+    if (position === paragraph.position) return
+    options.onStart()
+    return savePosition(previousParagraphs, oldIndex, newIndex, position)
+  }
+
+  function handleSortStart() {
+    sortSnapshot = [...options.paragraphs.value]
+    options.onStart()
+  }
+
+  function handleSortEnd() {
+    if (!options.loading.value) sortSnapshot = []
+  }
+
+  function handleSort({ oldIndex, newIndex }: SortableChange<ParagraphItem>) {
+    return savePosition(sortSnapshot, oldIndex, newIndex)
+  }
+
+  const getSortOptions = () => ({
+    disabled: options.disabled.value,
+    preventOnFilter: false,
+    onStart: handleSortStart,
+    onEnd: handleSortEnd,
+    onReorder: handleSort,
+  })
+  useSortable(options.directoryRef, options.paragraphs, () => ({
+    ...getSortOptions(),
+    filter: 'button:not(.paragraph-directory-drag-handle)',
+    draggable: '> .paragraph-directory-row',
+  }))
+  useSortable(options.cardsRef, options.paragraphs, () => ({
+    ...getSortOptions(),
+    filter: '.paragraph-card-actions, a, button:not(.paragraph-card-drag__handle)',
+    draggable: '> .paragraph-sort-row',
+  }))
+
+  return { handleMoveParagraph }
+}
diff --git a/ui/src/views/document-detail/context.ts b/ui/src/views/document-detail/context.ts
new file mode 100644
index 00000000000..356cdfd0757
--- /dev/null
+++ b/ui/src/views/document-detail/context.ts
@@ -0,0 +1,73 @@
+/** 文档分段页的资源 API 配置与返回导航。 */
+import { computed, inject, provide, reactive, type InjectionKey } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import DocumentApi from '@/api/admin/workspace/knowledge/document'
+import SharedDocumentApi from '@/api/admin/workspace/shared/knowledge/document'
+import SystemResourceDocumentApi from '@/api/admin/system/resource-management/knowledge/document'
+import SystemSharedDocumentApi from '@/api/admin/system/shared-resources/knowledge/document'
+import ParagraphApi from '@/api/admin/workspace/knowledge/paragraph'
+import SharedParagraphApi from '@/api/admin/workspace/shared/knowledge/paragraph'
+import SystemResourceParagraphApi from '@/api/admin/system/resource-management/knowledge/paragraph'
+import SystemSharedParagraphApi from '@/api/admin/system/shared-resources/knowledge/paragraph'
+import type { ResourceScope } from '@/router/admin/types'
+
+const resourceConfigs = {
+  workspace: { document: DocumentApi, paragraph: ParagraphApi },
+  'workspace-shared': { document: SharedDocumentApi, paragraph: SharedParagraphApi },
+  'system-resource': { document: SystemResourceDocumentApi, paragraph: SystemResourceParagraphApi },
+  'system-shared': { document: SystemSharedDocumentApi, paragraph: SystemSharedParagraphApi },
+} satisfies Record<ResourceScope, { document: typeof SharedDocumentApi; paragraph: typeof SharedParagraphApi }>
+
+/** 共有查询方法保持必填，仅部分范围提供的方法标记为可选。 */
+type ApiKeys<Api> = Api extends unknown ? keyof Api : never
+type OptionalApiMethods<Api> = Pick<Api, keyof Api> & {
+  [Method in Exclude<ApiKeys<Api>, keyof Api>]?: Api extends unknown ? (Method extends keyof Api ? Api[Method] : never) : never
+}
+
+export type DocumentParagraphApi = OptionalApiMethods<(typeof resourceConfigs)[ResourceScope]['paragraph']>
+
+function createDocumentDetailContext() {
+  const route = useRoute()
+  const router = useRouter()
+  const resourceConfig = computed(() => {
+    const scope = route.meta.resourceScope
+    if (!scope) throw new Error('Document detail resource scope is unavailable')
+    return resourceConfigs[scope]
+  })
+  const resourceApi = reactive({
+    get document(): OptionalApiMethods<(typeof resourceConfigs)[ResourceScope]['document']> {
+      return resourceConfig.value.document
+    },
+    get paragraph(): DocumentParagraphApi {
+      return resourceConfig.value.paragraph
+    },
+  })
+
+  function handleBack() {
+    const scope = route.meta.resourceScope
+    if (!scope) throw new Error('Document detail resource scope is unavailable')
+    void router.push({
+      name: `${scope}-knowledge-document-list`,
+      params: {
+        ...(scope === 'workspace' || scope === 'workspace-shared' ? { workspaceId: route.params.workspaceId } : {}),
+        knowledgeId: String(route.params.knowledgeId ?? ''),
+        type: route.params.type,
+      },
+      query: route.query,
+    })
+  }
+
+  return { resourceApi, handleBack }
+}
+
+const documentDetailContextKey: InjectionKey<ReturnType<typeof createDocumentDetailContext>> = Symbol('document-detail-context')
+
+export function provideDocumentDetailContext() {
+  const context = createDocumentDetailContext()
+  provide(documentDetailContextKey, context)
+  return context
+}
+
+export function useDocumentDetailContext() {
+  return inject(documentDetailContextKey, createDocumentDetailContext, true)
+}
diff --git a/ui/src/views/document-detail/index.vue b/ui/src/views/document-detail/index.vue
index d8008af4915..e10acf1fa6e 100644
--- a/ui/src/views/document-detail/index.vue
+++ b/ui/src/views/document-detail/index.vue
@@ -1,15 +1,13 @@
 <script setup lang="ts">
-import { computed, nextTick, onBeforeUnmount, onMounted, ref, type Directive } from 'vue'
-import { useRoute, useRouter } from 'vue-router'
-import type { ElAnchor } from 'element-plus'
+import { computed, nextTick, onMounted, ref, type Directive } from 'vue'
+import { useRoute } from 'vue-router'
 import type MkViewLayout from '@/components/global/mk-view-layout/index.vue'
-import DocumentApi from '@/api/admin/workspace/knowledge/document'
-import ParagraphApi from '@/api/admin/workspace/knowledge/paragraph'
+import { provideDocumentDetailContext } from './context'
 import type { ParamsPage } from '@/api/admin/core/types'
 import type { DocumentItem, ParagraphItem, ParagraphQuery } from '@/api/types'
 import { getFileIconUrl } from '@/utils/icon'
 import { MsgConfirm, MsgSuccess } from '@/utils/message'
-import { useSortable, type SortableChange } from '@/utils/use-sortable'
+import { useParagraphSort } from './action-dropdown/move/useParagraphSort'
 import CreateParagraphDialog from './paragraph-dialog/CreateParagraphDialog.vue'
 import EditParagraphDialog from './paragraph-dialog/ParagraphDialog.vue'
 import {
@@ -19,14 +17,13 @@ import {
   GenerateQuestionsAction,
   MoveParagraphAction,
 } from './action-dropdown'
-
-import type { ParagraphMoveDirection } from './action-dropdown'
+import { isWorkspaceSharedResource } from '@/utils/resource-context'
 
 defineOptions({ name: 'KnowledgeParagraphView' })
 
 /* 文档详情与分段查询 */
 const route = useRoute()
-const router = useRouter()
+const { resourceApi, handleBack } = provideDocumentDetailContext()
 const knowledgeId = computed(() => String(route.params.knowledgeId ?? ''))
 const documentId = computed(() => String(route.params.documentId ?? ''))
 const documentDetail = ref<DocumentItem>()
@@ -40,34 +37,11 @@ const searchFields = [
   { label: '内容', value: 'content' },
 ]
 
-async function loadParagraphPage(pagination: ParamsPage) {
-  // 拖拽及位置保存完成后再接续分页，避免补页改变拖拽索引或读取旧顺序。
-  await paragraphSortSettled
-  paragraphPageLoading.value = true
-  try {
-    // 局部删除后按剩余列表长度接续，最多拼接相邻两页，避免分页偏移导致漏载。
-    const loadedCount = pagination.currentPage === 1 ? 0 : paragraphs.value.length
-    const currentPage = Math.floor(loadedCount / pagination.pageSize) + 1
-    const offset = loadedCount % pagination.pageSize
-    const query = paragraphQuery.value
-    const page = await ParagraphApi.getParagraphPage(knowledgeId.value, documentId.value, { ...pagination, currentPage }, query)
-    let records = page.records.slice(offset)
-    if (offset && currentPage * page.size < page.total) {
-      const nextPage = await ParagraphApi.getParagraphPage(
-        knowledgeId.value,
-        documentId.value,
-        { ...pagination, currentPage: currentPage + 1 },
-        query,
-      )
-      records = [...records, ...nextPage.records].slice(0, pagination.pageSize)
-    }
+function loadParagraphPage(pagination: ParamsPage) {
+  return resourceApi.paragraph.getParagraphPage(knowledgeId.value, documentId.value, pagination, paragraphQuery.value).then((page) => {
     paragraphTotal.value = page.total
-    // 组件页码记录已消费页数，补回局部移除的数量以维持正确的结束判断。
-    const removedCount = (pagination.currentPage - 1) * pagination.pageSize - loadedCount
-    return { ...page, records, current: pagination.currentPage, total: page.total + removedCount }
-  } finally {
-    paragraphPageLoading.value = false
-  }
+    return page
+  })
 }
 
 function refreshParagraphs() {
@@ -79,27 +53,13 @@ function refreshParagraphs() {
 }
 
 function handleSearchChange(query?: ParagraphQuery) {
+  if (loading.value) return
   paragraphQuery.value = query ?? {}
   void refreshParagraphs()
 }
 
-function handleBack() {
-  void router.push({
-    name: `${route.meta.resourceScope}-knowledge-document-list`,
-    params: {
-      ...(route.meta.resourceScope === 'workspace' || route.meta.resourceScope === 'workspace-shared'
-        ? { workspaceId: route.params.workspaceId }
-        : {}),
-      knowledgeId: knowledgeId.value,
-      type: route.params.type,
-    },
-    query: route.query,
-  })
-}
-
 /* 分段目录定位与滚动高亮 */
 const layoutRef = ref<InstanceType<typeof MkViewLayout>>()
-const paragraphAnchorRef = ref<InstanceType<typeof ElAnchor>>()
 const paragraphScrollContainer = computed(() => layoutRef.value?.getScrollContainer())
 // AnchorLink 的 a 在组件内部渲染，只关闭链接原生拖动，排序行仍由 Sortable 管理。
 const vDisableLinkDrag: Directive<HTMLElement> = {
@@ -114,17 +74,19 @@ const selectedParagraphIds = ref<string[]>([])
 const paragraphIds = computed(() => paragraphs.value.map(({ id }) => id))
 
 function handleToggleBatchMode() {
+  if (loading.value) return
   batchMode.value = !batchMode.value
   selectedParagraphIds.value = []
   openParagraphMenuIds.value = { more: '', position: '' }
 }
 
 function handleSelectBatchParagraph(paragraphId: string, selected: boolean) {
+  if (loading.value) return
   selectedParagraphIds.value = selected ? [...selectedParagraphIds.value, paragraphId] : selectedParagraphIds.value.filter((id) => id !== paragraphId)
 }
 
 function handleClickParagraphCard(paragraph: ParagraphItem) {
-  if (paragraphMoving.value) return
+  if (loading.value) return
   if (batchMode.value) {
     handleSelectBatchParagraph(paragraph.id, !selectedParagraphIds.value.includes(paragraph.id))
     return
@@ -132,18 +94,7 @@ function handleClickParagraphCard(paragraph: ParagraphItem) {
   return handleOpenParagraphDetail(paragraph)
 }
 
-// 迁移、删除只移除对应分段，保留其他卡片、选择与滚动位置。
-function handleRemoveParagraphs(removedParagraphIds: string[]) {
-  const removedIds = new Set(removedParagraphIds)
-  if (removedIds.has(openParagraphMenuIds.value.more)) openParagraphMenuIds.value.more = ''
-  if (removedIds.has(openParagraphMenuIds.value.position)) openParagraphMenuIds.value.position = ''
-  const previousCount = paragraphs.value.length
-  paragraphs.value = paragraphs.value.filter(({ id }) => !removedIds.has(id))
-  paragraphTotal.value = Math.max(0, paragraphTotal.value - (previousCount - paragraphs.value.length))
-  selectedParagraphIds.value = selectedParagraphIds.value.filter((id) => !removedIds.has(id))
-}
-
-// 编辑和启停共用局部替换，编辑后不再匹配搜索条件的分段局部移除。
+// 编辑和启停共用局部替换，编辑后不再匹配搜索条件时刷新列表。
 function handleReplaceParagraph(paragraph: ParagraphItem) {
   const paragraphIndex = paragraphs.value.findIndex(({ id }) => id === paragraph.id)
   if (paragraphIndex < 0) return
@@ -151,8 +102,7 @@ function handleReplaceParagraph(paragraph: ParagraphItem) {
     (paragraph[field as keyof ParagraphQuery] ?? '').toLowerCase().includes(keyword.toLowerCase()),
   )
   if (!matchesQuery) {
-    handleRemoveParagraphs([paragraph.id])
-    return
+    return refreshParagraphs()
   }
   paragraphs.value.splice(paragraphIndex, 1, paragraph)
 }
@@ -163,29 +113,24 @@ function handleGenerateQuestionsSuccess() {
 }
 
 // 批量删除：确认前固定目标，取消或失败保留勾选。
-const deleteConfirming = ref(false)
-const deleting = ref(false)
-
 function handleBatchDeleteParagraphs() {
-  if (loading.value || deleteConfirming.value || deleting.value || !selectedParagraphIds.value.length) return
+  if (loading.value || !selectedParagraphIds.value.length) return
   const targetParagraphIds = [...selectedParagraphIds.value]
   const targetKnowledgeId = knowledgeId.value
   const targetDocumentId = documentId.value
-  deleteConfirming.value = true
+  loading.value = true
   return MsgConfirm(`确认删除选中的 ${targetParagraphIds.length} 个分段？`, '删除后无法恢复，请谨慎操作。')
     .then(() => {
-      deleting.value = true
-      return ParagraphApi.putBatchDeleteParagraphs(targetKnowledgeId, targetDocumentId, targetParagraphIds).then(() => {
+      return resourceApi.paragraph.putBatchDeleteParagraphs?.(targetKnowledgeId, targetDocumentId, targetParagraphIds).then(() => {
         MsgSuccess('删除成功')
-        return handleRemoveParagraphs(targetParagraphIds)
+        return refreshParagraphs()
       })
     })
     .catch(() => {
       // 取消无需提示，请求失败由请求层统一提示。
     })
     .finally(() => {
-      deleteConfirming.value = false
-      deleting.value = false
+      loading.value = false
     })
 }
 
@@ -197,14 +142,14 @@ const editDialogRef = ref<InstanceType<typeof EditParagraphDialog>>()
 const searchKey = ref(0)
 
 async function handleOpenCreateParagraph(position?: number) {
-  if (paragraphMoving.value) return
+  if (loading.value) return
   createDialogMounted.value = true
   await nextTick()
   createDialogRef.value?.open(position)
 }
 
 async function handleOpenParagraphDetail(paragraph: ParagraphItem, initialMode: 'detail' | 'edit' = 'detail') {
-  if (paragraphMoving.value) return
+  if (loading.value) return
   editDialogMounted.value = true
   await nextTick()
   editDialogRef.value?.open(paragraph, initialMode)
@@ -220,171 +165,67 @@ function handleParagraphMenuVisibleChange(paragraphId: string, menu: 'more' | 'p
 }
 
 function handleToggleParagraph(paragraph: ParagraphItem) {
-  if (loading.value || paragraphMoving.value) return false
+  if (loading.value) return false
   loading.value = true
-  return ParagraphApi.putParagraph(knowledgeId.value, documentId.value, paragraph.id, { is_active: !paragraph.is_active })
-    .then((updatedParagraph) => {
-      handleReplaceParagraph(updatedParagraph)
-      MsgSuccess('操作成功')
-      // 服务端响应已更新受控开关，阻止 before-change 再触发一次切换。
-      return false
-    })
-    .catch(() => false)
-    .finally(() => {
-      loading.value = false
-    })
+  return (
+    resourceApi.paragraph
+      .putParagraph?.(knowledgeId.value, documentId.value, paragraph.id, { is_active: !paragraph.is_active })
+      .then((updatedParagraph) => {
+        handleReplaceParagraph(updatedParagraph)
+        MsgSuccess('操作成功')
+        // 服务端响应已更新受控开关，阻止 before-change 再触发一次切换。
+        return false
+      })
+      .catch(() => false) ?? Promise.resolve(false)
+  ).finally(() => {
+    loading.value = false
+  })
 }
 
 function handleDeleteParagraph(paragraph: ParagraphItem) {
-  if (loading.value || paragraphMoving.value) return
+  if (loading.value) return
   const targetKnowledgeId = knowledgeId.value
   const targetDocumentId = documentId.value
   const targetParagraphId = paragraph.id
+  loading.value = true
   return MsgConfirm(`是否删除分段：${paragraph.title || '-'}？`, '删除后无法恢复，请谨慎操作。')
     .then(() => {
-      return ParagraphApi.deleteParagraph(targetKnowledgeId, targetDocumentId, targetParagraphId).then(() => {
+      return resourceApi.paragraph.deleteParagraph?.(targetKnowledgeId, targetDocumentId, targetParagraphId).then(() => {
         MsgSuccess('删除成功')
-        return handleRemoveParagraphs([targetParagraphId])
-      })
-    })
-    .catch(() => {})
-}
-
-function handleMoveParagraph(paragraph: ParagraphItem, direction: ParagraphMoveDirection) {
-  if (loading.value || paragraphMoving.value || paragraphPageLoading.value) return
-  handleParagraphSortStart()
-  paragraphMoving.value = true
-  const targetKnowledgeId = knowledgeId.value
-  const targetDocumentId = documentId.value
-  // 搜索只影响展示；移动始终按完整文档的顺序定位相邻分段。
-  return ParagraphApi.getParagraphList(targetKnowledgeId, targetDocumentId)
-    .then((documentParagraphs) => {
-      const index = documentParagraphs.findIndex(({ id }) => id === paragraph.id)
-      if (index < 0) return
-      const target =
-        direction === 'top'
-          ? documentParagraphs[0]
-          : direction === 'bottom'
-            ? documentParagraphs.at(-1)
-            : documentParagraphs[index + (direction === 'up' ? -1 : 1)]
-      if (!target || target.id === paragraph.id) return
-      return ParagraphApi.putParagraphPosition(targetKnowledgeId, targetDocumentId, paragraph.id, target.position).then(() => {
-        MsgSuccess('移动成功')
-        // 位置变更影响多个分段，替换当前已加载范围，保留分页和滚动位置。
-        return ParagraphApi.getParagraphPage(
-          targetKnowledgeId,
-          targetDocumentId,
-          { currentPage: 1, pageSize: paragraphs.value.length },
-          paragraphQuery.value,
-        ).then((page) => {
-          paragraphs.value = page.records
-          paragraphTotal.value = page.total
-          const loadedIds = new Set(page.records.map(({ id }) => id))
-          selectedParagraphIds.value = selectedParagraphIds.value.filter((id) => loadedIds.has(id))
-        })
+        return refreshParagraphs()
       })
     })
     .catch(() => {})
     .finally(() => {
-      paragraphMoving.value = false
-      finishParagraphSort()
+      loading.value = false
     })
 }
 
 /* 左侧目录与右侧卡片共用分段数组和位置保存流程。 */
 const paragraphCardsRef = ref<HTMLElement>()
 const paragraphDirectoryRef = ref<HTMLElement>()
-const paragraphPageLoading = ref(false)
-const paragraphMoving = ref(false)
 const paragraphSortDisabled = computed(
   () =>
+    isWorkspaceSharedResource() ||
     loading.value ||
-    paragraphPageLoading.value ||
-    paragraphMoving.value ||
     batchMode.value ||
-    deleting.value ||
-    deleteConfirming.value ||
     createDialogMounted.value ||
     editDialogMounted.value ||
     paragraphs.value.length < 2,
 )
-let paragraphSortSnapshot: ParagraphItem[] = []
-let paragraphSortSettled: Promise<void> = Promise.resolve()
-let resolveParagraphSort: (() => void) | undefined
-
-function handleParagraphSortStart() {
-  paragraphSortSnapshot = [...paragraphs.value]
-  openParagraphMenuIds.value = { more: '', position: '' }
-  paragraphSortSettled = new Promise((resolve) => {
-    resolveParagraphSort = resolve
-  })
-}
-
-function finishParagraphSort() {
-  paragraphSortSnapshot = []
-  resolveParagraphSort?.()
-  resolveParagraphSort = undefined
-  paragraphSortSettled = Promise.resolve()
-}
-
-function handleParagraphSortEnd() {
-  // 无顺序变化时不会触发保存；有变化时等待请求完成后释放分页。
-  if (!paragraphMoving.value) finishParagraphSort()
-}
-
-function handleParagraphSort({ newIndex, data }: SortableChange<ParagraphItem>) {
-  const previousParagraphs = paragraphSortSnapshot
-  const movedParagraph = data[newIndex]
-  const targetParagraph = previousParagraphs[newIndex]
-  if (!movedParagraph || !targetParagraph) {
-    paragraphs.value = previousParagraphs
-    finishParagraphSort()
-    return
-  }
-  const oldPosition = movedParagraph.position
-  const newPosition = targetParagraph.position
-  paragraphMoving.value = true
-  return ParagraphApi.putParagraphPosition(knowledgeId.value, documentId.value, movedParagraph.id, newPosition)
-    .then(() => {
-      // 库已经重排数组，只同步服务端移动区间内的 position，不再次移动数组。
-      paragraphs.value = paragraphs.value.map((paragraph) => {
-        let position = paragraph.position
-        if (paragraph.id === movedParagraph.id) position = newPosition
-        else if (oldPosition < newPosition && position > oldPosition && position <= newPosition) position -= 1
-        else if (oldPosition > newPosition && position >= newPosition && position < oldPosition) position += 1
-        return position === paragraph.position ? paragraph : { ...paragraph, position }
-      })
-      MsgSuccess('移动成功')
-    })
-    .catch(() => {
-      paragraphs.value = previousParagraphs
-    })
-    .finally(() => {
-      paragraphMoving.value = false
-      finishParagraphSort()
-    })
-}
-
-useSortable(paragraphDirectoryRef, paragraphs, () => ({
-  disabled: paragraphSortDisabled.value,
-  filter: 'button:not(.paragraph-directory-drag-handle)',
-  preventOnFilter: false,
-  draggable: '> .paragraph-directory-row',
-  onStart: handleParagraphSortStart,
-  onEnd: handleParagraphSortEnd,
-  onReorder: handleParagraphSort,
-}))
-useSortable(paragraphCardsRef, paragraphs, () => ({
-  disabled: paragraphSortDisabled.value,
-  // 整张卡片可拖拽，操作区和正文链接保持原有点击行为。
-  filter: '.paragraph-card-actions, a, button:not(.paragraph-card-drag__handle)',
-  preventOnFilter: false,
-  draggable: '> .paragraph-sort-row',
-  onStart: handleParagraphSortStart,
-  onEnd: handleParagraphSortEnd,
-  onReorder: handleParagraphSort,
-}))
-onBeforeUnmount(finishParagraphSort)
+const { handleMoveParagraph } = useParagraphSort({
+  paragraphs,
+  loading,
+  disabled: paragraphSortDisabled,
+  directoryRef: paragraphDirectoryRef,
+  cardsRef: paragraphCardsRef,
+  knowledgeId,
+  documentId,
+  resourceApi,
+  onStart: () => {
+    openParagraphMenuIds.value = { more: '', position: '' }
+  },
+})
 
 function handleCreateParagraphSuccess() {
   paragraphQuery.value = {}
@@ -394,21 +235,23 @@ function handleCreateParagraphSuccess() {
 
 onMounted(() => {
   loading.value = true
-  void DocumentApi.getDocumentDetail(knowledgeId.value, documentId.value)
-    .then((document) => {
-      documentDetail.value = document
-    })
-    .catch(() => {})
-    .finally(() => {
-      loading.value = false
-    })
+  void (
+    resourceApi.document
+      .getDocumentDetail?.(knowledgeId.value, documentId.value)
+      .then((document) => {
+        documentDetail.value = document
+      })
+      .catch(() => {}) ?? Promise.resolve()
+  ).finally(() => {
+    loading.value = false
+  })
 })
 </script>
 
 <template>
   <MkViewLayout ref="layoutRef" title="" :loading="loading" collapsible class="[&_aside+button]:top-4!">
     <template #top>
-      <div class="flex-between gap-4" :inert="paragraphMoving">
+      <div class="flex-between gap-4" :inert="loading">
         <div class="flex-align-center min-w-0 gap-2">
           <!-- 返回文档列表 -->
           <el-button text @click="handleBack"><MkIcon name="icon_arrow-left_outlined" :size="20" /></el-button>
@@ -418,14 +261,14 @@ onMounted(() => {
         <div class="flex-align-center shrink-0 gap-3">
           <MkComplexSearch :key="searchKey" :fields="searchFields" @change="handleSearchChange" />
           <!-- 切换批量选择 -->
-          <span>
+          <span v-if="!isWorkspaceSharedResource()">
             <el-button :type="batchMode ? 'primary' : undefined" :disabled="!paragraphs.length" plain @click="handleToggleBatchMode">
               <MkIcon name="icon_Batch_outlined" />
               <span>{{ batchMode ? '取消选择' : '批量选择' }}</span>
             </el-button>
           </span>
           <!-- 添加文档分段 -->
-          <el-button v-if="!batchMode" type="primary" @click="handleOpenCreateParagraph()">
+          <el-button v-if="!isWorkspaceSharedResource() && !batchMode" type="primary" @click="handleOpenCreateParagraph()">
             <MkIcon name="icon_add_outlined" />
             <span>添加分段</span>
           </el-button>
@@ -499,7 +342,7 @@ onMounted(() => {
                 @click="handleClickParagraphCard(paragraph)"
               >
                 <div
-                  v-if="!batchMode"
+                  v-if="!isWorkspaceSharedResource() && !batchMode"
                   class="paragraph-card-actions sticky top-3 z-10 h-0"
                   :class="{ 'group-hover-visible': openParagraphMenuIds.more !== paragraph.id && openParagraphMenuIds.position !== paragraph.id }"
                   @click.stop
@@ -509,7 +352,7 @@ onMounted(() => {
                       <!-- 启用或禁用当前分段 -->
                       <el-switch
                         :model-value="paragraph.is_active"
-                        :disabled="loading || paragraphMoving"
+                        :disabled="loading"
                         size="small"
                         class="ml-1"
                         :before-change="() => handleToggleParagraph(paragraph)"
@@ -542,32 +385,32 @@ onMounted(() => {
                             <!-- 生成当前分段的问题 -->
                             <GenerateQuestionsAction
                               label="生成问题"
-                              :api="ParagraphApi"
+                              :api="resourceApi.paragraph"
                               :knowledge-id="knowledgeId"
                               :document-id="documentId"
                               :paragraph-id="paragraph.id"
-                              :disabled="loading || paragraphMoving"
+                              :disabled="loading"
                               @refresh="handleGenerateQuestionsSuccess"
                             />
                             <!-- 迁移当前分段 -->
                             <MigrateParagraphAction
-                              :api="ParagraphApi"
+                              :api="resourceApi.paragraph"
                               :knowledge-id="knowledgeId"
                               :document-id="documentId"
                               :paragraph-id="paragraph.id"
-                              :disabled="loading || paragraphMoving"
-                              @success="handleRemoveParagraphs"
+                              :disabled="loading"
+                              @success="refreshParagraphs"
                             />
                             <!-- 展开分段位置菜单 -->
                             <MoveParagraphAction
                               label="移动位置"
                               divided
-                              :disabled="loading || paragraphMoving || paragraphPageLoading"
+                              :disabled="loading"
                               @move="handleMoveParagraph(paragraph, $event)"
                               @visible-change="handleParagraphMenuVisibleChange(paragraph.id, 'position', $event)"
                             />
                             <!-- 删除当前分段 -->
-                            <MkDropdownItem divided :disabled="loading || paragraphMoving" @click="handleDeleteParagraph(paragraph)">
+                            <MkDropdownItem divided :disabled="loading" @click="handleDeleteParagraph(paragraph)">
                               <template #icon><MkIcon name="icon_delete-trash_outlined" /></template>
                               删除
                             </MkDropdownItem>
@@ -608,30 +451,24 @@ onMounted(() => {
         <template #footer-batch-actions>
           <!-- 批量迁移分段 -->
           <BatchMigrateParagraphAction
-            :api="ParagraphApi"
+            :api="resourceApi.paragraph"
             :knowledge-id="knowledgeId"
             :document-id="documentId"
             :paragraph-ids="selectedParagraphIds"
-            :disabled="loading || paragraphMoving"
-            @success="handleRemoveParagraphs"
+            :disabled="loading"
+            @success="refreshParagraphs"
           />
           <!-- 批量生成问题 -->
           <BatchGenerateQuestionsAction
-            :api="ParagraphApi"
+            :api="resourceApi.paragraph"
             :knowledge-id="knowledgeId"
             :document-id="documentId"
             :paragraph-ids="selectedParagraphIds"
-            :disabled="loading || paragraphMoving"
+            :disabled="loading"
             @refresh="handleGenerateQuestionsSuccess"
           />
           <!-- 批量删除分段 -->
-          <el-button
-            type="danger"
-            plain
-            :loading="deleting"
-            :disabled="loading || deleteConfirming || !selectedParagraphIds.length"
-            @click="handleBatchDeleteParagraphs"
-          >
+          <el-button type="danger" plain :loading="loading" :disabled="loading || !selectedParagraphIds.length" @click="handleBatchDeleteParagraphs">
             删除
           </el-button>
         </template>
@@ -641,7 +478,6 @@ onMounted(() => {
   <CreateParagraphDialog
     v-if="createDialogMounted"
     ref="createDialogRef"
-    :api="ParagraphApi"
     :knowledge-id="knowledgeId"
     :document-id="documentId"
     @success="handleCreateParagraphSuccess"
@@ -650,7 +486,6 @@ onMounted(() => {
   <EditParagraphDialog
     v-if="editDialogMounted"
     ref="editDialogRef"
-    :api="ParagraphApi"
     :knowledge-id="knowledgeId"
     :document-id="documentId"
     @success="handleReplaceParagraph"
diff --git a/ui/src/views/document-detail/paragraph-dialog/CreateParagraphDialog.vue b/ui/src/views/document-detail/paragraph-dialog/CreateParagraphDialog.vue
index 6d9d0115d83..db29d8e0bd8 100644
--- a/ui/src/views/document-detail/paragraph-dialog/CreateParagraphDialog.vue
+++ b/ui/src/views/document-detail/paragraph-dialog/CreateParagraphDialog.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { ref } from 'vue'
-import type ParagraphApi from '@/api/admin/workspace/knowledge/paragraph'
+import { useDocumentDetailContext } from '@/views/document-detail/context'
 import type { ParagraphUpdatePayload } from '@/api/types'
 import type { ParagraphQuestionDraft } from './types'
 import ParagraphForm from './components/ParagraphForm.vue'
@@ -9,10 +9,10 @@ import { MsgSuccess } from '@/utils/message'
 
 defineOptions({ name: 'CreateParagraphDialog' })
 const props = defineProps<{
-  api: typeof ParagraphApi
   knowledgeId: string
   documentId: string
 }>()
+const { resourceApi } = useDocumentDetailContext()
 const emit = defineEmits<{ success: [mode: 'create']; closed: [] }>()
 
 /* 添加弹窗按需挂载，草稿在关闭后随实例释放。 */
@@ -47,22 +47,23 @@ function handleSubmit() {
     .then((valid) => {
       if (!valid || loading.value) return
       loading.value = true
-      return props.api
-        .postParagraph(targetKnowledgeId.value, targetDocumentId.value, {
-          title: paragraphForm.value.title.trim(),
-          content: paragraphForm.value.content,
-          is_active: true,
-          ...(targetPosition.value === undefined ? {} : { position: targetPosition.value }),
-          problem_list: relatedQuestions.value.map(({ content }) => ({ content })),
-        })
-        .then(() => {
-          visible.value = false
-          MsgSuccess('添加成功')
-          emit('success', 'create')
-        })
-        .finally(() => {
-          loading.value = false
-        })
+      return (
+        resourceApi.paragraph
+          .postParagraph?.(targetKnowledgeId.value, targetDocumentId.value, {
+            title: paragraphForm.value.title.trim(),
+            content: paragraphForm.value.content,
+            is_active: true,
+            ...(targetPosition.value === undefined ? {} : { position: targetPosition.value }),
+            problem_list: relatedQuestions.value.map(({ content }) => ({ content })),
+          })
+          .then(() => {
+            visible.value = false
+            MsgSuccess('添加成功')
+            emit('success', 'create')
+          }) ?? Promise.resolve()
+      ).finally(() => {
+        loading.value = false
+      })
     })
     .catch(() => {})
 }
@@ -83,7 +84,7 @@ defineExpose({ open, close })
     <div v-loading="loading" class="flex w-full gap-4">
       <ParagraphForm ref="paragraphFormRef" v-model="paragraphForm" :knowledge-id="targetKnowledgeId" />
       <!-- 关联问题 -->
-      <ParagraphQuestions v-model="relatedQuestions" :api="api" :knowledge-id="targetKnowledgeId" :document-id="targetDocumentId" />
+      <ParagraphQuestions v-model="relatedQuestions" :knowledge-id="targetKnowledgeId" :document-id="targetDocumentId" />
     </div>
     <template #footer>
       <!-- 取消添加分段 -->
diff --git a/ui/src/views/document-detail/paragraph-dialog/ParagraphDialog.vue b/ui/src/views/document-detail/paragraph-dialog/ParagraphDialog.vue
index 94726ec6c87..869f8e511a6 100644
--- a/ui/src/views/document-detail/paragraph-dialog/ParagraphDialog.vue
+++ b/ui/src/views/document-detail/paragraph-dialog/ParagraphDialog.vue
@@ -1,19 +1,20 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
-import type ParagraphApi from '@/api/admin/workspace/knowledge/paragraph'
+import { useDocumentDetailContext } from '@/views/document-detail/context'
 import type { ParagraphDetail, ParagraphItem, ParagraphUpdatePayload } from '@/api/types'
 import type { ParagraphQuestionDraft } from './types.ts'
 import ParagraphForm from './components/ParagraphForm.vue'
 import ParagraphQuestions from './components/ParagraphQuestions.vue'
 import ParagraphPreview from './components/ParagraphPreview.vue'
+import { isWorkspaceSharedResource } from '@/utils/resource-context'
 import { MsgSuccess } from '@/utils/message'
 
 defineOptions({ name: 'EditParagraphDialog' })
 const props = defineProps<{
-  api: typeof ParagraphApi
   knowledgeId: string
   documentId: string
 }>()
+const { resourceApi } = useDocumentDetailContext()
 const emit = defineEmits<{ success: [paragraph: ParagraphItem]; closed: [] }>()
 
 /* 详情加载：打开时固定目标，关闭动画后由页面卸载。 */
@@ -32,7 +33,7 @@ function loadParagraphDetail() {
   if (loading.value) return
   loading.value = true
   detailFailed.value = false
-  return props.api
+  return resourceApi.paragraph
     .getParagraphDetail(targetKnowledgeId.value, targetDocumentId.value, targetParagraphId.value)
     .then((paragraph) => {
       paragraphDetail.value = paragraph
@@ -51,7 +52,7 @@ function open(paragraph: ParagraphItem, initialMode: 'edit' | 'detail' = 'detail
   targetKnowledgeId.value = props.knowledgeId
   targetDocumentId.value = props.documentId
   targetParagraphId.value = paragraph.id
-  mode.value = initialMode
+  mode.value = isWorkspaceSharedResource() ? 'detail' : initialMode
   visible.value = true
   void loadParagraphDetail()
 }
@@ -86,21 +87,22 @@ function handleSubmit() {
       if (!valid || loading.value) return
       loading.value = true
       // 正文与问题使用独立接口，保存正文不会覆盖问题关联。
-      return props.api
-        .putParagraph(targetKnowledgeId.value, targetDocumentId.value, targetParagraphId.value, {
-          title: paragraphForm.value.title.trim(),
-          content: paragraphForm.value.content,
-        })
-        .then((paragraph) => {
-          // 问题由独立接口更新，正文保存响应不回填问题列表，避免覆盖并行操作结果。
-          paragraphDetail.value = paragraph
-          mode.value = 'detail'
-          MsgSuccess('保存成功')
-          emit('success', paragraph)
-        })
-        .finally(() => {
-          loading.value = false
-        })
+      return (
+        resourceApi.paragraph
+          .putParagraph?.(targetKnowledgeId.value, targetDocumentId.value, targetParagraphId.value, {
+            title: paragraphForm.value.title.trim(),
+            content: paragraphForm.value.content,
+          })
+          .then((paragraph) => {
+            // 问题由独立接口更新，正文保存响应不回填问题列表，避免覆盖并行操作结果。
+            paragraphDetail.value = paragraph
+            mode.value = 'detail'
+            MsgSuccess('保存成功')
+            emit('success', paragraph)
+          }) ?? Promise.resolve()
+      ).finally(() => {
+        loading.value = false
+      })
     })
     .catch(() => {})
 }
@@ -114,7 +116,7 @@ defineExpose({ open, close })
       <div class="flex h-[480px] max-h-[calc(100vh-272px)] w-full gap-4">
         <el-card v-if="mode === 'detail'" shadow="never" class="mk-paragraph-card group relative min-w-0 flex-1" body-class="flex-column h-full">
           <!-- 编辑分段标题和内容 -->
-          <el-button circle class="group-hover-visible absolute! top-4 right-4 shadow-md" @click="handleEdit">
+          <el-button v-if="!isWorkspaceSharedResource()" circle class="group-hover-visible absolute! top-4 right-4 shadow-md" @click="handleEdit">
             <MkIcon name="icon_edit_outlined" />
           </el-button>
           <ParagraphPreview :paragraph="paragraphDetail" />
@@ -133,7 +135,6 @@ defineExpose({ open, close })
         <!-- 关联问题 -->
         <ParagraphQuestions
           v-model="relatedQuestions"
-          :api="api"
           :knowledge-id="targetKnowledgeId"
           :document-id="targetDocumentId"
           :paragraph-id="targetParagraphId"
diff --git a/ui/src/views/document-detail/paragraph-dialog/components/ParagraphQuestions.vue b/ui/src/views/document-detail/paragraph-dialog/components/ParagraphQuestions.vue
index f224e9f67fc..46776b8ad95 100644
--- a/ui/src/views/document-detail/paragraph-dialog/components/ParagraphQuestions.vue
+++ b/ui/src/views/document-detail/paragraph-dialog/components/ParagraphQuestions.vue
@@ -1,19 +1,20 @@
 <script setup lang="ts">
 import { nextTick, onMounted, ref } from 'vue'
 import type { SelectInstance } from 'element-plus'
-import type ParagraphApi from '@/api/admin/workspace/knowledge/paragraph'
+import { useDocumentDetailContext } from '@/views/document-detail/context'
 import ProblemApi from '@/api/admin/workspace/knowledge/problem'
 import type { ParagraphProblem } from '@/api/types'
 import type { ParagraphQuestionDraft } from '../types'
+import { isWorkspaceSharedResource } from '@/utils/resource-context'
 import { MsgWarning } from '@/utils/message'
 
 defineOptions({ name: 'ParagraphQuestions' })
 const props = defineProps<{
-  api: typeof ParagraphApi
   knowledgeId: string
   documentId: string
   paragraphId?: string
 }>()
+const { resourceApi } = useDocumentDetailContext()
 const relatedProblems = defineModel<ParagraphQuestionDraft[]>({ required: true })
 const loading = ref(false)
 const problemAdding = ref(false)
@@ -35,19 +36,21 @@ function loadProblemOptions(query = '') {
 }
 
 onMounted(() => {
-  void loadProblemOptions()
+  if (!isWorkspaceSharedResource()) void loadProblemOptions()
 })
 
 /* 新增分段维护本地草稿；已有分段创建或关联问题后刷新关联列表。 */
 function refreshRelatedProblems() {
   if (!props.paragraphId) return Promise.resolve()
-  return props.api.getParagraphProblems(props.knowledgeId, props.documentId, props.paragraphId).then((problems) => {
-    relatedProblems.value = problems
-  })
+  return (
+    resourceApi.paragraph.getParagraphProblems?.(props.knowledgeId, props.documentId, props.paragraphId).then((problems) => {
+      relatedProblems.value = problems
+    }) ?? Promise.resolve()
+  )
 }
 
 async function handleAddProblem() {
-  if (loading.value) return
+  if (loading.value || isWorkspaceSharedResource()) return
   problemAdding.value = true
   await nextTick()
   problemSelectRef.value?.focus()
@@ -60,7 +63,7 @@ function handleCancelProblem() {
 }
 
 function handleSelectProblem(value: string) {
-  if (loading.value) return
+  if (loading.value || isWorkspaceSharedResource()) return
   const existingProblem = problemOptions.value.find(({ id }) => id === value)
   const content = (existingProblem?.content ?? value).trim()
   if (!content || content.length > 256) {
@@ -80,23 +83,24 @@ function handleSelectProblem(value: string) {
 
   loading.value = true
   const associationRequest = existingProblem
-    ? props.api.putAssociateParagraphProblem(props.knowledgeId, props.documentId, props.paragraphId, existingProblem.id)
-    : props.api.postParagraphProblem(props.knowledgeId, props.documentId, props.paragraphId, content)
-  return associationRequest
-    .then(() => {
-      return refreshRelatedProblems().then(() => {
-        problemAdding.value = false
-        problemValue.value = ''
+    ? resourceApi.paragraph.putAssociateParagraphProblem?.(props.knowledgeId, props.documentId, props.paragraphId, existingProblem.id)
+    : resourceApi.paragraph.postParagraphProblem?.(props.knowledgeId, props.documentId, props.paragraphId, content)
+  return (
+    associationRequest
+      ?.then(() => {
+        return refreshRelatedProblems().then(() => {
+          problemAdding.value = false
+          problemValue.value = ''
+        })
       })
-    })
-    .catch(() => {})
-    .finally(() => {
-      loading.value = false
-    })
+      .catch(() => {}) ?? Promise.resolve()
+  ).finally(() => {
+    loading.value = false
+  })
 }
 
 function handleRemoveProblem(index: number) {
-  if (loading.value) return
+  if (loading.value || isWorkspaceSharedResource()) return
   const problem = relatedProblems.value[index]
   if (!problem) return
   if (!props.paragraphId) {
@@ -105,13 +109,14 @@ function handleRemoveProblem(index: number) {
   }
   if (!problem.id) return
   loading.value = true
-  void props.api
-    .putUnassociateParagraphProblem(props.knowledgeId, props.documentId, props.paragraphId, problem.id)
-    .then(() => refreshRelatedProblems())
-    .catch(() => {})
-    .finally(() => {
-      loading.value = false
-    })
+  void (
+    resourceApi.paragraph
+      .putUnassociateParagraphProblem?.(props.knowledgeId, props.documentId, props.paragraphId, problem.id)
+      .then(() => refreshRelatedProblems())
+      .catch(() => {}) ?? Promise.resolve()
+  ).finally(() => {
+    loading.value = false
+  })
 }
 </script>
 
@@ -120,7 +125,7 @@ function handleRemoveProblem(index: number) {
     <div class="mb-4 flex-between shrink-0 gap-3">
       <h4>关联问题</h4>
       <!-- 添加关联问题 -->
-      <el-button text :disabled="loading || problemAdding" @click="handleAddProblem">
+      <el-button v-if="!isWorkspaceSharedResource()" text :disabled="loading || problemAdding" @click="handleAddProblem">
         <MkIcon name="icon_add_outlined" :size="16" />
       </el-button>
     </div>
@@ -152,7 +157,7 @@ function handleRemoveProblem(index: number) {
               <div class="flex-between gap-2">
                 <span class="min-w-0 flex-1 truncate" :title="problem.content">{{ problem.content }}</span>
                 <!-- 解除问题关联 -->
-                <el-button text :disabled="loading" @click="handleRemoveProblem(index)">
+                <el-button v-if="!isWorkspaceSharedResource()" text :disabled="loading" @click="handleRemoveProblem(index)">
                   <MkIcon name="icon_close_outlined" :size="16" />
                 </el-button>
               </div>
diff --git a/ui/src/views/knowledge-detail/chat-user/index.vue b/ui/src/views/knowledge-detail/chat-user/index.vue
index ec811515a7d..efb2b3fd94b 100644
--- a/ui/src/views/knowledge-detail/chat-user/index.vue
+++ b/ui/src/views/knowledge-detail/chat-user/index.vue
@@ -1,22 +1,22 @@
 <script setup lang="ts">
 import { computed, onMounted, ref } from 'vue'
-import { useRoute } from 'vue-router'
 import type { CheckboxValueType } from 'element-plus'
-import ChatUserApi from '@/api/admin/workspace/chat-user'
+import { useKnowledgeDetailContext } from '@/views/knowledge-detail/context'
 import { LOGIN_METHOD, RESOURCE_TYPE } from '@/api/enums'
 import type { ChatUserAuthorization, ChatUserAuthorizationGroup, ChatUserAuthorizationResource, Dict, LoginMethod, OptionItem } from '@/api/types'
 import { LOGIN_METHOD_LABELS } from '@/constants'
 import MkSearchList from '@/components/mk-search-list/index.vue'
 import type { ResourceDetailPageProps } from '@/layout/ResourceDetailLayout.vue'
 import { MsgSuccess } from '@/utils/message'
+import { isWorkspaceSharedResource } from '@/utils/resource-context'
 
 defineOptions({ name: 'KnowledgeChatUserListView' })
 defineProps<ResourceDetailPageProps>()
 defineExpose({ hideHeader: true })
 
-const route = useRoute()
+const { resourceApi, knowledgeId } = useKnowledgeDetailContext()
 const resource = computed<ChatUserAuthorizationResource>(() => ({
-  resource_id: String(route.params.knowledgeId ?? ''),
+  resource_id: knowledgeId.value,
   resource_type: RESOURCE_TYPE.KNOWLEDGE,
 }))
 
@@ -28,7 +28,8 @@ const currentGroup = ref<ChatUserAuthorizationGroup>()
 
 function loadChatUserGroups() {
   loading.value = true
-  return ChatUserApi.getUserGroupList(resource.value)
+  return resourceApi.chatUser
+    .getUserGroupList(resource.value)
     .then((groups) => {
       chatUserGroups.value = groups
       currentGroup.value = groups[0]
@@ -41,7 +42,7 @@ function loadChatUserGroups() {
 
 // 仅刷新用户组列表及已授权人数，保留当前选中的用户组。
 function refreshChatUserGroups() {
-  return ChatUserApi.getUserGroupList(resource.value).then((groups) => {
+  return resourceApi.chatUser.getUserGroupList(resource.value).then((groups) => {
     const currentId = currentGroup.value?.id
     chatUserGroups.value = groups
     currentGroup.value = groups.find((group) => group.id === currentId) ?? groups[0]
@@ -87,11 +88,13 @@ function formatUserSource(source: string) {
 
 function loadChatUsers() {
   if (!currentGroup.value) return Promise.resolve()
-  return ChatUserApi.getUserGroupUserList(resource.value, currentGroup.value.id, paginationConfig.value, chatUserQuery.value).then((page) => {
-    chatUsers.value = page.records
-    savedAuthorization.value = Object.fromEntries(page.records.map(({ id, is_auth }) => [id, is_auth]))
-    paginationConfig.value.total = page.total
-  })
+  return resourceApi.chatUser
+    .getUserGroupUserList(resource.value, currentGroup.value.id, paginationConfig.value, chatUserQuery.value)
+    .then((page) => {
+      chatUsers.value = page.records
+      savedAuthorization.value = Object.fromEntries(page.records.map(({ id, is_auth }) => [id, is_auth]))
+      paginationConfig.value.total = page.total
+    })
 }
 
 function refreshChatUsers() {
@@ -134,16 +137,16 @@ function handleSave() {
   if (!group || saveDisabled.value) return
   const payload = chatUsers.value.map(({ id, is_auth }) => ({ chat_user_id: id, is_auth }))
   loading.value = true
-  return ChatUserApi.putUserGroupUser(resource.value, group.id, payload)
-    .then(() => {
+  return (
+    resourceApi.chatUser.putUserGroupUser?.(resource.value, group.id, payload).then(() => {
       // 先记住已保存结果，列表刷新失败时不重复提示未保存。
       savedAuthorization.value = Object.fromEntries(payload.map(({ chat_user_id, is_auth }) => [chat_user_id, is_auth]))
       MsgSuccess('保存成功')
       return loadChatUsers().then(refreshChatUserGroups)
-    })
-    .finally(() => {
-      loading.value = false
-    })
+    }) ?? Promise.resolve()
+  ).finally(() => {
+    loading.value = false
+  })
 }
 
 // 自动授权成功后清空旧勾选，重新读取服务端授权状态
@@ -152,17 +155,17 @@ function handleAutoAuthorizationChange(value: string | number | boolean) {
   if (!group || loading.value) return
   loading.value = true
   const isAuth = value === true
-  return ChatUserApi.putUserGroupAuthorization(resource.value, [{ user_group_id: group.id, is_auth: isAuth }])
-    .then(() => {
+  return (
+    resourceApi.chatUser.putUserGroupAuthorization?.(resource.value, [{ user_group_id: group.id, is_auth: isAuth }]).then(() => {
       group.is_auth = isAuth
       chatUsers.value = []
       savedAuthorization.value = {}
       MsgSuccess('保存成功')
       return loadChatUsers().then(refreshChatUserGroups)
-    })
-    .finally(() => {
-      loading.value = false
-    })
+    }) ?? Promise.resolve()
+  ).finally(() => {
+    loading.value = false
+  })
 }
 
 onMounted(() => loadChatUserGroups())
@@ -203,11 +206,16 @@ onMounted(() => loadChatUserGroups())
             <!-- 设置用户组自动授权 -->
             <div class="flex-align-center shrink-0 gap-2">
               <span>自动授权</span>
-              <el-switch :model-value="currentGroup.is_auth" size="small" @change="handleAutoAuthorizationChange" />
+              <el-switch
+                :disabled="isWorkspaceSharedResource()"
+                :model-value="currentGroup.is_auth"
+                size="small"
+                @change="handleAutoAuthorizationChange"
+              />
             </div>
           </div>
           <!-- 保存对话用户授权 -->
-          <el-button type="primary" :disabled="saveDisabled" @click="handleSave">保存</el-button>
+          <el-button v-if="!isWorkspaceSharedResource()" type="primary" :disabled="saveDisabled" @click="handleSave">保存</el-button>
         </div>
 
         <MkTable
@@ -228,7 +236,12 @@ onMounted(() => loadChatUserGroups())
           <el-table-column :width="140" align="center">
             <template #header>
               <!-- 批量设置当前页授权 -->
-              <el-checkbox :model-value="allChecked" :indeterminate="allIndeterminate" :disabled="authorizationDisabled" @change="handleCheckAll">
+              <el-checkbox
+                :model-value="allChecked"
+                :indeterminate="allIndeterminate"
+                :disabled="authorizationDisabled || isWorkspaceSharedResource()"
+                @change="handleCheckAll"
+              >
                 授权
               </el-checkbox>
             </template>
@@ -236,7 +249,7 @@ onMounted(() => loadChatUserGroups())
               <!-- 设置对话用户授权 -->
               <el-checkbox
                 :model-value="row.is_auth"
-                :disabled="authorizationDisabled"
+                :disabled="authorizationDisabled || isWorkspaceSharedResource()"
                 @change="(value: CheckboxValueType) => handleRowChange(value, row)"
               />
             </template>
diff --git a/ui/src/views/knowledge-detail/context.ts b/ui/src/views/knowledge-detail/context.ts
index 88b9bdb3dd5..022140a7e0b 100644
--- a/ui/src/views/knowledge-detail/context.ts
+++ b/ui/src/views/knowledge-detail/context.ts
@@ -16,10 +16,14 @@ import SharedTagsApi from '@/api/admin/workspace/shared/knowledge/tags'
 import SystemResourceTagsApi from '@/api/admin/system/resource-management/knowledge/tags'
 import SystemSharedTagsApi from '@/api/admin/system/shared-resources/knowledge/tags'
 import WorkflowApi from '@/api/admin/workspace/knowledge/workflow'
-import SyncApi from '@/api/admin/workspace/knowledge/sync'
-import SharedSyncApi from '@/api/admin/workspace/shared/knowledge/sync'
-import SystemResourceSyncApi from '@/api/admin/system/resource-management/knowledge/sync'
-import SystemSharedSyncApi from '@/api/admin/system/shared-resources/knowledge/sync'
+import ScheduledSyncApi from '@/api/admin/workspace/knowledge/scheduled-sync'
+import SharedScheduledSyncApi from '@/api/admin/workspace/shared/knowledge/scheduled-sync'
+import SystemResourceScheduledSyncApi from '@/api/admin/system/resource-management/knowledge/scheduled-sync'
+import SystemSharedScheduledSyncApi from '@/api/admin/system/shared-resources/knowledge/scheduled-sync'
+import ChatUserApi from '@/api/admin/workspace/chat-user'
+import SharedChatUserApi from '@/api/admin/workspace/shared/chat-user'
+import SystemResourceChatUserApi from '@/api/admin/system/resource-management/chat-user'
+import SystemSharedChatUserApi from '@/api/admin/system/shared-resources/chat-user'
 import type { KnowledgeDetail } from '@/api/types'
 import type { ResourceScope } from '@/router/admin/types'
 
@@ -30,13 +34,18 @@ type OptionalApiMethods<Api> = Pick<Api, keyof Api> & {
 }
 
 interface KnowledgeResourceApi {
+  readonly chatUser: OptionalApiMethods<
+    typeof ChatUserApi | typeof SharedChatUserApi | typeof SystemResourceChatUserApi | typeof SystemSharedChatUserApi
+  >
   readonly workflow?: typeof WorkflowApi
   readonly document: OptionalApiMethods<
     typeof DocumentApi | typeof SharedDocumentApi | typeof SystemResourceDocumentApi | typeof SystemSharedDocumentApi
   >
   readonly tags: OptionalApiMethods<typeof TagsApi | typeof SharedTagsApi | typeof SystemResourceTagsApi | typeof SystemSharedTagsApi>
   readonly knowledge: typeof KnowledgeApi | typeof SharedKnowledgeApi | typeof SystemResourceKnowledgeApi | typeof SystemSharedKnowledgeApi
-  readonly sync: OptionalApiMethods<typeof SyncApi | typeof SharedSyncApi | typeof SystemResourceSyncApi | typeof SystemSharedSyncApi>
+  readonly scheduledSync: OptionalApiMethods<
+    typeof ScheduledSyncApi | typeof SharedScheduledSyncApi | typeof SystemResourceScheduledSyncApi | typeof SystemSharedScheduledSyncApi
+  >
 }
 
 interface KnowledgeResourceConfig {
@@ -47,24 +56,44 @@ interface KnowledgeResourceConfig {
 /** 仅配置真实存在的完整 API 对象；缺失模块不回退到 Workspace。 */
 const resourceConfigs = {
   workspace: {
-    resourceApi: { knowledge: KnowledgeApi, sync: SyncApi, document: DocumentApi, tags: TagsApi, workflow: WorkflowApi },
+    resourceApi: {
+      chatUser: ChatUserApi,
+      knowledge: KnowledgeApi,
+      scheduledSync: ScheduledSyncApi,
+      document: DocumentApi,
+      tags: TagsApi,
+      workflow: WorkflowApi,
+    },
     listRouteName: 'workspace-knowledge-list',
   },
   'workspace-shared': {
-    resourceApi: { knowledge: SharedKnowledgeApi, sync: SharedSyncApi, document: SharedDocumentApi, tags: SharedTagsApi },
+    resourceApi: {
+      chatUser: SharedChatUserApi,
+      knowledge: SharedKnowledgeApi,
+      scheduledSync: SharedScheduledSyncApi,
+      document: SharedDocumentApi,
+      tags: SharedTagsApi,
+    },
     listRouteName: 'workspace-knowledge-list',
   },
   'system-resource': {
     resourceApi: {
+      chatUser: SystemResourceChatUserApi,
       knowledge: SystemResourceKnowledgeApi,
-      sync: SystemResourceSyncApi,
+      scheduledSync: SystemResourceScheduledSyncApi,
       document: SystemResourceDocumentApi,
       tags: SystemResourceTagsApi,
     },
     listRouteName: 'system-resource-knowledge',
   },
   'system-shared': {
-    resourceApi: { knowledge: SystemSharedKnowledgeApi, sync: SystemSharedSyncApi, document: SystemSharedDocumentApi, tags: SystemSharedTagsApi },
+    resourceApi: {
+      chatUser: SystemSharedChatUserApi,
+      knowledge: SystemSharedKnowledgeApi,
+      scheduledSync: SystemSharedScheduledSyncApi,
+      document: SystemSharedDocumentApi,
+      tags: SystemSharedTagsApi,
+    },
     listRouteName: 'system-shared-knowledge',
   },
 } satisfies Record<ResourceScope, KnowledgeResourceConfig>
@@ -92,6 +121,9 @@ function createKnowledgeDetailContext(state: KnowledgeDetailState): KnowledgeDet
   })
   // 保持接口入口稳定，通过 getter 在路由范围变化时读取当前配置。
   const resourceApi = reactive({
+    get chatUser() {
+      return resourceConfig.value.resourceApi.chatUser
+    },
     get workflow() {
       return resourceConfig.value.resourceApi.workflow
     },
@@ -104,8 +136,8 @@ function createKnowledgeDetailContext(state: KnowledgeDetailState): KnowledgeDet
     get knowledge() {
       return resourceConfig.value.resourceApi.knowledge
     },
-    get sync() {
-      return resourceConfig.value.resourceApi.sync
+    get scheduledSync() {
+      return resourceConfig.value.resourceApi.scheduledSync
     },
   })
   const routeNames = computed(() => {
@@ -152,8 +184,9 @@ type ScopedResourceApi<Scope extends ResourceScope> = {
 }
 
 type ScopedKnowledgeDetailContext<Scope extends ResourceScope> = Omit<KnowledgeDetailContext, 'resourceApi'> & {
-  resourceApi: Omit<ScopedResourceApi<Scope>, 'sync' | 'tags' | 'document'> & {
-    readonly sync: OptionalApiMethods<(typeof resourceConfigs)[Scope]['resourceApi']['sync']>
+  resourceApi: Omit<ScopedResourceApi<Scope>, 'scheduledSync' | 'tags' | 'document' | 'chatUser'> & {
+    readonly chatUser: OptionalApiMethods<(typeof resourceConfigs)[Scope]['resourceApi']['chatUser']>
+    readonly scheduledSync: OptionalApiMethods<(typeof resourceConfigs)[Scope]['resourceApi']['scheduledSync']>
     readonly tags: OptionalApiMethods<(typeof resourceConfigs)[Scope]['resourceApi']['tags']>
     readonly document: OptionalApiMethods<(typeof resourceConfigs)[Scope]['resourceApi']['document']>
   }
diff --git a/ui/src/views/knowledge-detail/external-retrieval/index.vue b/ui/src/views/knowledge-detail/external-retrieval/index.vue
index 75b1e49f592..b8a2e5d49d4 100644
--- a/ui/src/views/knowledge-detail/external-retrieval/index.vue
+++ b/ui/src/views/knowledge-detail/external-retrieval/index.vue
@@ -6,6 +6,7 @@ import type { KnowledgeExternalRetrievalPayload, KnowledgeExternalRetrievalSetti
 import type { ResourceDetailPageProps } from '@/layout/ResourceDetailLayout.vue'
 import { copyText } from '@/utils/clipboard'
 import { MsgSuccess } from '@/utils/message'
+import { isWorkspaceSharedResource } from '@/utils/resource-context'
 
 defineOptions({ name: 'ExternalRetrievalView' })
 defineProps<ResourceDetailPageProps>()
@@ -72,13 +73,22 @@ onMounted(() => {
         <span class="text-N600">（开启后仅授权的对话用户可通过 API Key 检索该知识库）</span>
       </div>
       <!-- 切换身份认证 -->
-      <el-switch :model-value="setting?.authentication ?? false" @change="handleSettingChange('authentication', $event)" />
+      <el-switch
+        :disabled="isWorkspaceSharedResource()"
+        :model-value="setting?.authentication ?? false"
+        @change="handleSettingChange('authentication', $event)"
+      />
     </section>
     <section>
       <div class="flex-between mb-2 gap-2">
         <span>API 服务地址</span>
         <!-- 切换外部检索服务 -->
-        <el-switch :model-value="setting?.enabled ?? false" size="small" @change="handleSettingChange('enabled', $event)" />
+        <el-switch
+          :disabled="isWorkspaceSharedResource()"
+          :model-value="setting?.enabled ?? false"
+          size="small"
+          @change="handleSettingChange('enabled', $event)"
+        />
       </div>
       <el-input :model-value="setting?.api_url ?? ''" readonly>
         <template #suffix>
diff --git a/ui/src/views/knowledge-detail/library/document/components/DocumentTags.vue b/ui/src/views/knowledge-detail/library/document/components/DocumentTags.vue
index d18d78798ee..3a244981503 100644
--- a/ui/src/views/knowledge-detail/library/document/components/DocumentTags.vue
+++ b/ui/src/views/knowledge-detail/library/document/components/DocumentTags.vue
@@ -56,7 +56,7 @@ function handleDialogClosed() {
       </div>
     </el-popover>
     <!-- 添加文档标签 -->
-    <el-button class="mk-add-tag-button" plain :disabled="!api || disabled || loading" @click.stop="handleOpenDialog">
+    <el-button class="mk-add-tag-button" plain v-if="!disabled" :disabled="loading" @click.stop="handleOpenDialog">
       <MkIcon name="icon_add_outlined" size="14" />
       <span>标签</span>
     </el-button>
diff --git a/ui/src/views/knowledge-detail/library/document/index.vue b/ui/src/views/knowledge-detail/library/document/index.vue
index 1315771cbc8..2f373c2a14a 100644
--- a/ui/src/views/knowledge-detail/library/document/index.vue
+++ b/ui/src/views/knowledge-detail/library/document/index.vue
@@ -16,7 +16,7 @@ import { datetimeFormat } from '@/utils/time'
 import { numberFormat } from '@/utils/number'
 import { MsgSuccess } from '@/utils/message'
 import { getFileIconUrl } from '@/utils/icon'
-import { isWorkspaceResource } from '@/utils/resource-context'
+import { isWorkspaceResource, isWorkspaceSharedResource } from '@/utils/resource-context'
 import ButtonUploadDocument from './upload-document/ButtonUploadDocument.vue'
 import ButtonImportDocument from './import-document/ButtonImportDocument.vue'
 import ButtonExecutionRecord from './components/ButtonExecutionRecord.vue'
@@ -305,31 +305,28 @@ onBeforeUnmount(() => {
       <div class="flex-align-center gap-3">
         <MkComplexSearch :fields="searchFields" @change="handleSearchChange" />
         <!-- 查看工作流执行记录 -->
-        <ButtonExecutionRecord
-          v-if="resourceApi.workflow && knowledgeType === KNOWLEDGE_TYPE_KEY.WORKFLOW"
-          :api="resourceApi.workflow"
-          :knowledge-id="knowledgeId"
-        />
-
-        <!-- 导入 Web、飞书或工作流文档 -->
-        <ButtonImportDocument
-          v-if="!showQuickCreate"
-          :api="resourceApi.document"
-          :knowledge-id="knowledgeId"
-          :knowledge-type="knowledgeType"
-          :folder-token="String(knowledge?.meta?.folder_token ?? '')"
-          :workflow="knowledge?.work_flow"
-          @refresh="handleImportDocumentSuccess"
-        />
-        <!-- 上传文档 -->
-        <ButtonUploadDocument
-          v-if="showQuickCreate"
-          :api="resourceApi.document"
-          :knowledge-id="knowledgeId"
-          :file-count-limit="knowledge?.file_count_limit"
-          :file-size-limit="knowledge?.file_size_limit"
-          @refresh="handleImportDocumentSuccess"
-        />
+        <ButtonExecutionRecord v-if="knowledgeType === KNOWLEDGE_TYPE_KEY.WORKFLOW" :api="resourceApi.workflow" :knowledge-id="knowledgeId" />
+        <template v-if="!isWorkspaceSharedResource()">
+          <!-- 导入 Web、飞书或工作流文档 -->
+          <ButtonImportDocument
+            v-if="!showQuickCreate"
+            :api="resourceApi.document"
+            :knowledge-id="knowledgeId"
+            :knowledge-type="knowledgeType"
+            :folder-token="String(knowledge?.meta?.folder_token ?? '')"
+            :workflow="knowledge?.work_flow"
+            @refresh="handleImportDocumentSuccess"
+          />
+          <!-- 上传文档 -->
+          <ButtonUploadDocument
+            v-if="showQuickCreate"
+            :api="resourceApi.document"
+            :knowledge-id="knowledgeId"
+            :file-count-limit="knowledge?.file_count_limit"
+            :file-size-limit="knowledge?.file_size_limit"
+            @refresh="handleImportDocumentSuccess"
+          />
+        </template>
       </div>
     </div>
   </Teleport>
@@ -346,12 +343,12 @@ onBeforeUnmount(() => {
     row-class-name="cursor-pointer"
     resizable
   >
-    <template v-if="showQuickCreate" #body-prepend>
+    <template v-if="showQuickCreate && !isWorkspaceSharedResource()" #body-prepend>
       <!-- 快速创建空白文档 -->
       <MkQuickCreate ref="quickCreateRef" text="快速创建空白文档" placeholder="请输入文档名称" @create="handleCreateDocument" />
     </template>
 
-    <el-table-column type="selection" width="40" reserve-selection />
+    <el-table-column type="selection" width="40" reserve-selection v-if="!isWorkspaceSharedResource()" />
 
     <el-table-column prop="name" label="文档名称" min-width="220" show-overflow-tooltip>
       <template #default="{ row }: { row: DocumentItem }">
@@ -362,6 +359,7 @@ onBeforeUnmount(() => {
           :maxlength="128"
           :validate="validateDocumentName"
           :save="(name) => saveDocumentName(row.id, name)"
+          :disabled="isWorkspaceSharedResource()"
         >
           <template #prefix>
             <img v-if="knowledgeType === KNOWLEDGE_TYPE_KEY.WEB" src="@/assets/file-type/web-link-icon.svg" alt="" class="size-5" />
@@ -426,6 +424,7 @@ onBeforeUnmount(() => {
           :document="row"
           v-model:loading="operationLoading"
           @refresh="refreshAfterOperation"
+          :disabled="isWorkspaceSharedResource()"
         />
       </template>
     </el-table-column>
@@ -459,7 +458,7 @@ onBeforeUnmount(() => {
     <el-table-column label="创建时间" width="180">
       <template #default="{ row }">{{ datetimeFormat(row.create_time) }}</template>
     </el-table-column>
-    <el-table-column label="操作" width="160" fixed="right">
+    <el-table-column label="操作" width="160" fixed="right" v-if="!isWorkspaceSharedResource()">
       <template #default="{ row }: { row: DocumentItem }">
         <div class="flex-align-center" @click.stop>
           <!-- 启用或禁用文档 -->
diff --git a/ui/src/views/knowledge-detail/library/document/upload-document/EditParagraphDialog.vue b/ui/src/views/knowledge-detail/library/document/upload-document/EditParagraphDialog.vue
index 6427caa04f9..08ed4696948 100644
--- a/ui/src/views/knowledge-detail/library/document/upload-document/EditParagraphDialog.vue
+++ b/ui/src/views/knowledge-detail/library/document/upload-document/EditParagraphDialog.vue
@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import { ref } from 'vue'
 import { cloneDeep } from 'lodash'
-import ParagraphApi from '@/api/admin/workspace/knowledge/paragraph'
 import type { DocumentImportParagraph, ParagraphUpdatePayload } from '@/api/types'
 import type { ParagraphQuestionDraft } from '@/views/document-detail/paragraph-dialog/types'
 import ParagraphForm from '@/views/document-detail/paragraph-dialog/components/ParagraphForm.vue'
@@ -71,7 +70,7 @@ defineExpose({ open, close })
     <div v-loading="loading" class="flex w-full gap-4">
       <ParagraphForm ref="paragraphFormRef" v-model="paragraphForm" :knowledge-id="knowledgeId" />
       <!-- 关联问题仅保存到导入草稿，未创建文档不传入分段 ID -->
-      <ParagraphQuestions v-model="relatedQuestions" :api="ParagraphApi" :knowledge-id="knowledgeId" document-id="" />
+      <ParagraphQuestions v-model="relatedQuestions" :knowledge-id="knowledgeId" document-id="" />
     </div>
     <template #footer>
       <!-- 取消分段编辑 -->
diff --git a/ui/src/views/knowledge-detail/library/tags/index.vue b/ui/src/views/knowledge-detail/library/tags/index.vue
index d7e07251bcc..8cacf911154 100644
--- a/ui/src/views/knowledge-detail/library/tags/index.vue
+++ b/ui/src/views/knowledge-detail/library/tags/index.vue
@@ -10,6 +10,7 @@ import CreateTagDialog from './components/CreateTagDialog.vue'
 import EditTagDialog from './components/EditTagDialog.vue'
 import ButtonImportTags from './components/ButtonImportTags.vue'
 import AssociatedDocumentDrawer from './AssociatedDocumentDrawer.vue'
+import { isWorkspaceSharedResource } from '@/utils/resource-context'
 
 defineOptions({ name: 'TagManagementView' })
 defineProps<ResourceDetailPageProps>()
@@ -191,12 +192,12 @@ onMounted(() => {
     @cell-mouse-enter="handleCellEnter"
     @cell-mouse-leave="handleCellLeave"
   >
-    <el-table-column type="selection" width="40" />
+    <el-table-column type="selection" width="40" v-if="!isWorkspaceSharedResource()" />
     <el-table-column prop="key" label="标签" min-width="240">
       <template #default="{ row }: { row: TagTableRow }">
         <div class="flex-align-center gap-1">
           <span class="min-w-0 truncate" :title="row.key">{{ row.key }}</span>
-          <div class="flex-align-center shrink-0" :class="{ 'group-hover-visible': hoveredTagKey !== row.key }">
+          <div v-if="!isWorkspaceSharedResource()" class="flex-align-center shrink-0" :class="{ 'group-hover-visible': hoveredTagKey !== row.key }">
             <!-- 添加标签值 -->
             <MkTooltip content="添加标签值" placement="top">
               <el-button type="primary" text @click="handleOpenAddTagValue(row)">
@@ -228,7 +229,7 @@ onMounted(() => {
         </el-button>
       </template>
     </el-table-column>
-    <el-table-column label="操作" width="100" fixed="right">
+    <el-table-column label="操作" width="100" fixed="right" v-if="!isWorkspaceSharedResource()">
       <template #default="{ row }: { row: TagTableRow }">
         <div class="flex-align-center">
           <!-- 编辑标签值 -->
diff --git a/ui/src/views/knowledge-detail/setting/base/index.vue b/ui/src/views/knowledge-detail/setting/base/index.vue
index f145fd00481..6db2011aa0c 100644
--- a/ui/src/views/knowledge-detail/setting/base/index.vue
+++ b/ui/src/views/knowledge-detail/setting/base/index.vue
@@ -7,14 +7,13 @@ import { KNOWLEDGE_TYPE } from '@/api/enums'
 import type { KnowledgeItem } from '@/api/types'
 import { KNOWLEDGE_TYPE_LABELS, KNOWLEDGE_TYPE_MAP } from '@/constants/knowledge'
 import { MsgConfirm, MsgSuccess } from '@/utils/message'
+import { isWorkspaceSharedResource } from '@/utils/resource-context'
 import KnowledgeBaseForm from '@/views/knowledge/create-knowledge/components/KnowledgeBaseForm.vue'
 import { useKnowledgeDetailContext } from '../../context'
 
 defineOptions({ name: 'KnowledgeBaseSettingView' })
 
-const { knowledge, replaceKnowledgeDetail, resourceApi } = useKnowledgeDetailContext({
-  resourceScopes: ['workspace', 'system-resource', 'system-shared'],
-})
+const { knowledge, replaceKnowledgeDetail, resourceApi } = useKnowledgeDetailContext()
 
 /* 详情与基本信息 */
 
@@ -75,6 +74,8 @@ watch(
 
 /* 保存设置；更换向量模型时先确认，保存完成后重新向量化 */
 function handleSave() {
+  const knowledgeApi = resourceApi.knowledge
+  if (saving.value || isWorkspaceSharedResource() || !('putKnowledge' in knowledgeApi)) return
   saving.value = true
   return Promise.all([baseFormRef.value?.validate(), settingFormRef.value?.validate().catch(() => false)])
     .then(([baseValid, settingValid]) => {
@@ -110,12 +111,10 @@ function handleSave() {
 
       return confirmation.then(() => {
         const request =
-          detail.type === KNOWLEDGE_TYPE.LARK
-            ? resourceApi.knowledge.putLarkKnowledge(detail.id, payload)
-            : resourceApi.knowledge.putKnowledge(detail.id, payload)
+          detail.type === KNOWLEDGE_TYPE.LARK ? knowledgeApi.putLarkKnowledge(detail.id, payload) : knowledgeApi.putKnowledge(detail.id, payload)
         // 返回完整请求链，向量化失败时保留原模型基准，允许再次保存重试。
         return request.then((savedKnowledge) => {
-          const embeddingRequest = embeddingModelChanged ? resourceApi.knowledge.putReEmbeddingKnowledge(detail.id) : Promise.resolve()
+          const embeddingRequest = embeddingModelChanged ? knowledgeApi.putReEmbeddingKnowledge(detail.id) : Promise.resolve()
           return embeddingRequest.then(() => {
             replaceKnowledgeDetail({ ...detail, ...savedKnowledge })
             MsgSuccess('保存成功')
@@ -205,6 +204,6 @@ defineProps<ResourceDetailPageProps>()
     </el-form>
 
     <!-- 保存知识库设置 -->
-    <el-button class="mt-4" type="primary" :loading="saving" @click="handleSave">保存</el-button>
+    <el-button v-if="!isWorkspaceSharedResource()" class="mt-4" type="primary" :loading="saving" @click="handleSave">保存</el-button>
   </div>
 </template>
diff --git a/ui/src/views/knowledge-detail/setting/document-strategy/index.vue b/ui/src/views/knowledge-detail/setting/document-strategy/index.vue
index de12cfeae39..53583988093 100644
--- a/ui/src/views/knowledge-detail/setting/document-strategy/index.vue
+++ b/ui/src/views/knowledge-detail/setting/document-strategy/index.vue
@@ -3,6 +3,7 @@ import type { ResourceDetailPageProps } from '@/layout/ResourceDetailLayout.vue'
 import { ref, useTemplateRef, watch } from 'vue'
 import DocumentStrategyForm from '@/views/knowledge/create-knowledge/components/DocumentStrategyForm.vue'
 import { MsgSuccess } from '@/utils/message'
+import { isWorkspaceSharedResource } from '@/utils/resource-context'
 import { useKnowledgeDetailContext } from '../../context'
 
 defineOptions({ name: 'KnowledgeDocumentStrategyView' })
@@ -10,9 +11,7 @@ defineOptions({ name: 'KnowledgeDocumentStrategyView' })
 defineProps<ResourceDetailPageProps>()
 
 /* 复用详情回填策略，草稿由表单维护。 */
-const { knowledge, replaceKnowledgeDetail, resourceApi } = useKnowledgeDetailContext({
-  resourceScopes: ['workspace', 'system-resource', 'system-shared'],
-})
+const { knowledge, replaceKnowledgeDetail, resourceApi } = useKnowledgeDetailContext()
 const strategyFormRef = useTemplateRef<InstanceType<typeof DocumentStrategyForm>>('strategyFormRef')
 const saving = ref(false)
 watch(
@@ -25,6 +24,8 @@ watch(
 
 /* 只保存文档处理策略，不触发同步或修改其他设置。 */
 function handleSave() {
+  const knowledgeApi = resourceApi.knowledge
+  if (isWorkspaceSharedResource() || !('putKnowledge' in knowledgeApi)) return
   const detail = knowledge.value
   const strategyForm = strategyFormRef.value
   if (saving.value || !detail || !strategyForm) return
@@ -33,7 +34,7 @@ function handleSave() {
     .validate()
     .then((valid) => {
       if (!valid) return
-      return resourceApi.knowledge.putKnowledge(detail.id, { doc_strategy: strategyForm.getStrategy() }).then((savedKnowledge) => {
+      return knowledgeApi.putKnowledge(detail.id, { doc_strategy: strategyForm.getStrategy() }).then((savedKnowledge) => {
         replaceKnowledgeDetail({ ...detail, ...savedKnowledge })
         MsgSuccess('保存成功')
       })
@@ -59,6 +60,6 @@ defineExpose({ customHeader: true })
   <div v-loading="saving" class="max-w-200">
     <DocumentStrategyForm ref="strategyFormRef" />
     <!-- 保存文档处理策略 -->
-    <el-button type="primary" class="mt-4" :loading="saving" @click="handleSave">保存</el-button>
+    <el-button v-if="!isWorkspaceSharedResource()" type="primary" class="mt-4" :loading="saving" @click="handleSave">保存</el-button>
   </div>
 </template>
diff --git a/ui/src/views/knowledge-detail/setting/scheduled-sync/components/SyncLogTable.vue b/ui/src/views/knowledge-detail/setting/scheduled-sync/components/SyncLogTable.vue
index 5096f70009c..308533e8827 100644
--- a/ui/src/views/knowledge-detail/setting/scheduled-sync/components/SyncLogTable.vue
+++ b/ui/src/views/knowledge-detail/setting/scheduled-sync/components/SyncLogTable.vue
@@ -1,9 +1,9 @@
 <script setup lang="ts">
 import { ref, watch } from 'vue'
-import type SyncApi from '@/api/admin/workspace/knowledge/sync'
-import type SharedSyncApi from '@/api/admin/workspace/shared/knowledge/sync'
-import type SystemResourceSyncApi from '@/api/admin/system/resource-management/knowledge/sync'
-import type SystemSharedSyncApi from '@/api/admin/system/shared-resources/knowledge/sync'
+import type ScheduledSyncApi from '@/api/admin/workspace/knowledge/scheduled-sync'
+import type SharedScheduledSyncApi from '@/api/admin/workspace/shared/knowledge/scheduled-sync'
+import type SystemResourceScheduledSyncApi from '@/api/admin/system/resource-management/knowledge/scheduled-sync'
+import type SystemSharedScheduledSyncApi from '@/api/admin/system/shared-resources/knowledge/scheduled-sync'
 import { KNOWLEDGE_SYNC_STATUS, KNOWLEDGE_SYNC_TYPE } from '@/api/enums'
 import type { KnowledgeSyncLog, KnowledgeSyncStatus } from '@/api/types'
 import type { StatusLabelOptions } from '@/components/global/mk-status-label/types'
@@ -13,7 +13,7 @@ import { datetimeFormat } from '@/utils/time'
 defineOptions({ name: 'KnowledgeSyncLogTable' })
 const props = defineProps<{
   knowledgeId: string
-  api: typeof SyncApi | typeof SharedSyncApi | typeof SystemResourceSyncApi | typeof SystemSharedSyncApi
+  api: typeof ScheduledSyncApi | typeof SharedScheduledSyncApi | typeof SystemResourceScheduledSyncApi | typeof SystemSharedScheduledSyncApi
 }>()
 
 // 进入日志页签时挂载查询，翻页由表格事件重新查询。
diff --git a/ui/src/views/knowledge-detail/setting/scheduled-sync/index.vue b/ui/src/views/knowledge-detail/setting/scheduled-sync/index.vue
index 6b8e77f6770..a58bea1cfcd 100644
--- a/ui/src/views/knowledge-detail/setting/scheduled-sync/index.vue
+++ b/ui/src/views/knowledge-detail/setting/scheduled-sync/index.vue
@@ -116,7 +116,7 @@ function handleSave() {
     .then(() => {
       if (!syncSetting.value.schedule_type) return
       const setting: KnowledgeSyncSetting = { ...cloneDeep(syncSetting.value), schedule_type: syncSetting.value.schedule_type }
-      return resourceApi.sync.putKnowledgeSyncSetting?.(detail.id, setting).then((savedSetting) => {
+      return resourceApi.scheduledSync.putKnowledgeSyncSetting?.(detail.id, setting).then((savedSetting) => {
         syncSetting.value = cloneDeep(savedSetting)
         replaceKnowledgeDetail({ ...detail, meta: { ...detail.meta, sync_setting: savedSetting } })
         MsgSuccess('保存成功')
@@ -131,7 +131,7 @@ function handleSave() {
 function loadSyncSetting(knowledgeId: string) {
   loading.value = true
   settingLoaded.value = false
-  return resourceApi.sync
+  return resourceApi.scheduledSync
     .getKnowledgeSyncSetting(knowledgeId)
     .then((setting) => {
       syncSetting.value = cloneDeep(setting)
@@ -165,15 +165,7 @@ watch(
       <el-tab-pane label="同步日志" name="logs" />
     </el-tabs>
     <div v-show="activeTab === 'settings'" v-loading="loading || saving" class="min-h-40">
-      <el-form
-        ref="formRef"
-        :model="syncSetting"
-        :rules="rules"
-        class="max-w-200 pb-6"
-        label-position="top"
-        :disabled="isWorkspaceSharedResource()"
-        @submit.prevent
-      >
+      <el-form ref="formRef" :model="syncSetting" :rules="rules" class="max-w-200 pb-6" label-position="top" @submit.prevent>
         <el-form-item>
           <template #label>
             <span>
@@ -224,6 +216,6 @@ watch(
         </el-button>
       </el-form>
     </div>
-    <SyncLogTable v-if="activeTab === 'logs' && knowledge" :api="resourceApi.sync" :knowledge-id="knowledge.id" />
+    <SyncLogTable v-if="activeTab === 'logs' && knowledge" :api="resourceApi.scheduledSync" :knowledge-id="knowledge.id" />
   </div>
 </template>
diff --git a/ui/src/views/knowledge-detail/workflow-transform/index.vue b/ui/src/views/knowledge-detail/workflow-transform/index.vue
index fc735ab56f8..68b6e398d87 100644
--- a/ui/src/views/knowledge-detail/workflow-transform/index.vue
+++ b/ui/src/views/knowledge-detail/workflow-transform/index.vue
@@ -4,6 +4,7 @@ import { useRoute, useRouter } from 'vue-router'
 import { cloneDeep } from 'lodash'
 import type { ResourceDetailPageProps } from '@/layout/ResourceDetailLayout.vue'
 import { MsgConfirm, MsgSuccess } from '@/utils/message'
+import { isWorkspaceSharedResource } from '@/utils/resource-context'
 import { knowledgeTemplate } from '@/views/knowledge/template'
 import workflowDemo from '@/assets/workflow/workflow-demo.png'
 import { useKnowledgeDetailContext } from '../context'
@@ -14,9 +15,7 @@ defineExpose({ hideHeader: true })
 
 const route = useRoute()
 const router = useRouter()
-const { knowledgeId, resourceApi, routeNames, routeParams } = useKnowledgeDetailContext({
-  resourceScopes: ['workspace', 'system-resource', 'system-shared'],
-})
+const { knowledgeId, resourceApi, routeNames, routeParams } = useKnowledgeDetailContext()
 
 /* 转换成功后进入全屏画布。 */
 function enterWorkflow() {
@@ -29,13 +28,15 @@ function enterWorkflow() {
 
 const loading = ref(false)
 function handleTransformWorkflow() {
+  const knowledgeApi = resourceApi.knowledge
+  if (loading.value || isWorkspaceSharedResource() || !('postTransformWorkflow' in knowledgeApi)) return
   return MsgConfirm('转换为工作流知识库', '转换后无法回退，请谨慎操作。', {
     confirmButtonText: '转换',
     confirmButtonType: 'primary',
   })
     .then(() => {
       loading.value = true
-      return resourceApi.knowledge.postTransformWorkflow(knowledgeId.value, { work_flow: cloneDeep(knowledgeTemplate.default) }).then(() => {
+      return knowledgeApi.postTransformWorkflow(knowledgeId.value, { work_flow: cloneDeep(knowledgeTemplate.default) }).then(() => {
         MsgSuccess('转换成功')
         return enterWorkflow()
       })
@@ -58,7 +59,7 @@ function handleTransformWorkflow() {
       </div>
       <p class="mt-6 mb-2 text-warning">注意：转换后不可撤回。</p>
       <!-- 转换为工作流知识库 -->
-      <el-button type="primary" :loading="loading" @click="handleTransformWorkflow">转换</el-button>
+      <el-button v-if="!isWorkspaceSharedResource()" type="primary" :loading="loading" @click="handleTransformWorkflow">转换</el-button>
     </div>
     <img :src="workflowDemo" class="w-full min-w-0" />
   </div>
diff --git a/ui/src/views/knowledge/create-knowledge/components/KnowledgeBaseForm.vue b/ui/src/views/knowledge/create-knowledge/components/KnowledgeBaseForm.vue
index 9428c3bb390..264b7f745e3 100644
--- a/ui/src/views/knowledge/create-knowledge/components/KnowledgeBaseForm.vue
+++ b/ui/src/views/knowledge/create-knowledge/components/KnowledgeBaseForm.vue
@@ -8,7 +8,7 @@ import ModelApi from '@/api/admin/workspace/model'
 import SystemSharedModelApi from '@/api/admin/system/shared-resources/model'
 import ModelProviderApi from '@/api/admin/model-provider'
 import SelectModel from '@/components/business/select-model/index.vue'
-import { isSystemResource, isSystemSharedResource } from '@/utils/resource-context'
+import { isSystemResource, isSystemSharedResource, isWorkspaceSharedResource } from '@/utils/resource-context'
 
 defineOptions({ name: 'KnowledgeBaseForm' })
 defineProps<{ disabled?: boolean }>()
@@ -90,7 +90,7 @@ defineExpose({ form, validate, reset })
         :provider-options="providerOptions"
         :disabled="disabled || loading"
         placeholder="请选择向量模型"
-        can-add
+        :can-add="!isWorkspaceSharedResource()"
         @refresh="loadModelOptions"
       />
     </el-form-item>
diff --git a/ui/src/views/knowledge/knowledge-card/action-dropdown/GenerateQuestionsAction.vue b/ui/src/views/knowledge/knowledge-card/action-dropdown/GenerateQuestionsAction.vue
index 3fc1aa8f3ae..4b3a49cbb01 100644
--- a/ui/src/views/knowledge/knowledge-card/action-dropdown/GenerateQuestionsAction.vue
+++ b/ui/src/views/knowledge/knowledge-card/action-dropdown/GenerateQuestionsAction.vue
@@ -2,13 +2,17 @@
 import { nextTick, ref, useTemplateRef } from 'vue'
 import type KnowledgeApi from '@/api/admin/workspace/knowledge/knowledge'
 import type { DocumentTaskState, KnowledgeItem, RelatedQuestionsConfig } from '@/api/types'
-import GenerateQuestionsDialog from '@/components/business/generate-questions/GenerateQuestionsDialog.vue'
+import GenerateQuestionsDialog from '@/components/business/generate-questions/index.vue'
 import { MsgSuccess } from '@/utils/message'
 import type SystemResourceKnowledgeApi from '@/api/admin/system/resource-management/knowledge/knowledge'
 import type SystemSharedKnowledgeApi from '@/api/admin/system/shared-resources/knowledge/knowledge'
 
 defineOptions({ name: 'GenerateQuestionsAction' })
-const props = defineProps<{ api: typeof KnowledgeApi | typeof SystemResourceKnowledgeApi | typeof SystemSharedKnowledgeApi; knowledge: KnowledgeItem; label: string }>()
+const props = defineProps<{
+  api: typeof KnowledgeApi | typeof SystemResourceKnowledgeApi | typeof SystemSharedKnowledgeApi
+  knowledge: KnowledgeItem
+  label: string
+}>()
 const loading = defineModel<boolean>('loading', { default: false })
 
 /* 知识库生成问题配置：按需挂载并固定本次操作目标。 */
diff --git a/ui/src/views/tool/index.vue b/ui/src/views/tool/index.vue
index 5de84a334f7..4f970f77c4d 100644
--- a/ui/src/views/tool/index.vue
+++ b/ui/src/views/tool/index.vue
@@ -241,7 +241,13 @@ onMounted(() => {
           <template v-if="!isShared">
             <!-- 批量选择 -->
             <span>
-              <el-button v-if="perm.tool.workspace.batchMove() || perm.tool.workspace.batchDelete()" :disabled="!toolsData.length" :type="batchSelectionMode ? 'primary' : undefined" plain @click="toggleBatchSelection">
+              <el-button
+                v-if="perm.tool.workspace.batchMove() || perm.tool.workspace.batchDelete()"
+                :disabled="!toolsData.length"
+                :type="batchSelectionMode ? 'primary' : undefined"
+                plain
+                @click="toggleBatchSelection"
+              >
                 <MkIcon name="icon_Batch_outlined" />
                 <span>{{ batchSelectionMode ? '取消选择' : '批量选择' }}</span>
               </el-button>
@@ -274,8 +280,14 @@ onMounted(() => {
               >
                 <template #actions>
                   <!-- 修改工具状态 -->
-                  <ToolStatusSwitch :disabled="!perm.tool.workspace.switch(tool.id)" v-model:loading="toolOperationLoading" :api="ToolApi" :tool="tool" @update="handleToolUpdate" />
-                  <el-divider direction="vertical" class="ml-1!"/>
+                  <ToolStatusSwitch
+                    :disabled="!perm.tool.workspace.switch(tool.id)"
+                    v-model:loading="toolOperationLoading"
+                    :api="ToolApi"
+                    :tool="tool"
+                    @update="handleToolUpdate"
+                  />
+                  <el-divider direction="vertical" class="ml-1!" />
                 </template>
                 <template #action-dropdown>
                   <!-- 编辑工具 -->
@@ -294,7 +306,14 @@ onMounted(() => {
                   />
                   <ToolWorkflowAction v-if="tool.tool_type === TOOL_TYPE.WORKFLOW" label="工作流" :tool="tool" />
                   <!-- 复制 -->
-                  <CopyToolAction v-if="perm.tool.workspace.copy(tool.id)" v-model:loading="toolOperationLoading" label="复制" :api="ToolApi" :tool="tool" @refresh="refreshTool" />
+                  <CopyToolAction
+                    v-if="perm.tool.workspace.copy(tool.id)"
+                    v-model:loading="toolOperationLoading"
+                    label="复制"
+                    :api="ToolApi"
+                    :tool="tool"
+                    @refresh="refreshTool"
+                  />
                   <InitParamAction
                     v-if="(tool.init_field_list?.length ?? 0) > 0"
                     v-model:loading="toolOperationLoading"
@@ -321,7 +340,12 @@ onMounted(() => {
                     :tool="tool"
                   />
                   <!-- 查看关联资源 -->
-                  <RelatedResourcesToolAction v-if="perm.tool.workspace.relateMap(tool.id)" label="查看关联资源" :api="RelatedResourcesApi" :tool="tool" />
+                  <RelatedResourcesToolAction
+                    v-if="perm.tool.workspace.relateMap(tool.id)"
+                    label="查看关联资源"
+                    :api="RelatedResourcesApi"
+                    :tool="tool"
+                  />
 
                   <!-- 查看执行记录 -->
                   <ExecutionRecordToolAction
@@ -340,9 +364,22 @@ onMounted(() => {
                     @delete="handleDeleteTool"
                   />
                   <!-- 导出 -->
-                  <ExportToolAction v-if="!tool.template_id && perm.tool.workspace.export(tool.id)" v-model:loading="toolOperationLoading" label="导出" :api="ToolApi" :tool="tool" />
+                  <ExportToolAction
+                    v-if="!tool.template_id && perm.tool.workspace.export(tool.id)"
+                    v-model:loading="toolOperationLoading"
+                    label="导出"
+                    :api="ToolApi"
+                    :tool="tool"
+                  />
                   <!-- 删除 -->
-                  <DeleteToolAction v-if="perm.tool.workspace.delete(tool.id)" v-model:loading="toolOperationLoading" label="删除" :api="ToolApi" :tool="tool" @delete="handleDeleteTool" />
+                  <DeleteToolAction
+                    v-if="perm.tool.workspace.delete(tool.id)"
+                    v-model:loading="toolOperationLoading"
+                    label="删除"
+                    :api="ToolApi"
+                    :tool="tool"
+                    @delete="handleDeleteTool"
+                  />
                 </template>
               </ToolCard>
             </template>
@@ -361,8 +398,12 @@ onMounted(() => {
         @batch-cancel="cancelBatchSelection"
       >
         <template #footer-batch-actions>
-          <el-button v-if="perm.tool.workspace.batchMove()" type="primary" plain :disabled="!selectedToolCount" @click="handleOpenBatchMove">移动到</el-button>
-          <el-button v-if="perm.tool.workspace.batchDelete()" type="danger" plain :disabled="!selectedToolCount" @click="handleBatchDelete">删除</el-button>
+          <el-button v-if="perm.tool.workspace.batchMove()" type="primary" plain :disabled="!selectedToolCount" @click="handleOpenBatchMove">
+            移动到
+          </el-button>
+          <el-button v-if="perm.tool.workspace.batchDelete()" type="danger" plain :disabled="!selectedToolCount" @click="handleBatchDelete">
+            删除
+          </el-button>
         </template>
       </component>
     </template>
diff --git a/ui/src/workflow-canvas/WORKFLOW_README.md b/ui/src/workflow-canvas/WORKFLOW_README.md
index 0b85d30f4be..0d43dc05679 100644
--- a/ui/src/workflow-canvas/WORKFLOW_README.md
+++ b/ui/src/workflow-canvas/WORKFLOW_README.md
@@ -26,7 +26,7 @@ src/workflow-canvas/
 │   └── node-container/ # 节点容器、锚点按钮及私有的条件、操作下拉组件
 ├── icons/              # 节点图标及图标解析工具
 ├── node-menu/          # 按模式组织基础组件、数据源、工具与智能体菜单
-├── nodes/              # 已迁入节点的注册文件和 Vue 实现
+├── nodes/              # 节点的注册文件和 Vue 实现
 ├── plugins/            # 仅供画布使用的 LogicFlow 插件
 ├── store/              # 按资源范围适配查询接口，提供缓存及在途请求去重
 ├── index.vue           # 画布入口组件 WorkflowCanvas
@@ -146,10 +146,7 @@ System 资源管理合并普通与共享模型，System 共享范围仅返回标
 `system-resource` 与 `system-shared` 独立提供系统模型、供应商、参数表单、工具选项与详情、MCP 和标签查询，
 不继承 Workspace 适配器，不要求路由工作空间。System MCP 查询要求部署提供对应
 `/system/resource/<resourceType>/<id>/mcp_tools` 或 `/system/shared/<resourceType>/<id>/mcp_tools` 扩展接口，尚未完成运行验证。
-`workspace-shared` 仍为空占位。知识库及工具选择弹窗按 Workspace、System 资源管理、System 共享资源
-调用对应 API；智能体选择支持 Workspace 和 System 资源管理，System 共享入口不提供智能体选择。
-选择弹窗不增加 Workspace 共享页面来源分支、不调用 Workspace Shared API；仅普通工作空间显示
-文件夹，且不显示共享目录，其他范围不显示或查询文件夹。
+`workspace-shared` 仍为空占位。选择弹窗的资源范围和交互以组件文档为准。
 节点资源查询可调用此适配器或既有业务 API；工作流加载、保存与发布仍由 View 编排，核心层不承载请求。
 
 ### 表格文本省略
@@ -158,14 +155,6 @@ System 资源管理合并普通与共享模型，System 共享范围仅返回标
 需要省略的文本通过列的默认插槽渲染，统一使用 `span.block.truncate` 并绑定原生 `title`；
 标题与展示内容使用同一字段或格式化结果，参考 `nodes/base-node/component/user-input/UserInputTable.vue`。
 
-```vue
-<el-table-column prop="field" label="参数">
-  <template #default="{ row }">
-    <span class="block truncate" :title="row.field">{{ row.field }}</span>
-  </template>
-</el-table-column>
-```
-
 ### `nodes/`
 
 每个已实现节点使用一个目录，目录中包含 LogicFlow 注册文件 `index.ts` 和节点视图
@@ -200,8 +189,8 @@ Vue `computed` 的 `set` 和原生 `Map.set()` 按各自 API 正常使用。
 节点入口负责输出字段同步、刷新事件和下游失效引用清理，表格与弹窗不直接读写节点模型。
 非登录表单使用 `@submit.prevent`，保存和添加由按钮触发。
 
-设置弹窗打开时重置并用 `cloneDeep` 生成草稿，校验通过并保存后回写；取消不修改节点，
-关闭动画结束后清理草稿与校验。带开关的设置组件由节点入口按开关挂载。
+设置弹窗 open() 使用 cloneDeep 回填本次草稿，保存后回写，取消不修改节点，closed 清理。
+带开关的设置组件由节点入口按开关挂载；通用生命周期遵循组件文档。
 
 ### 模型选择
 
@@ -270,7 +259,7 @@ AI 对话、意图识别、问题优化、参数提取、图片理解、视频
 本地文件与 Web 数据源节点使用统一节点模型和容器，输出分别保留 `file_list` 与 `document_list`。
 本地文件节点在初始化时补齐文件格式、数量和大小限制，保留自定义格式；表单校验必选格式和
 1–1000 范围的整数限制。格式选择器不 Teleport，并接入锚点保护。Web 节点没有可编辑配置，
-不再保留未使用的文档引用表单，也不改写已有 `node_data`。
+仅保留输出协议，不改写已有 `node_data`。
 
 知识库写入节点使用统一 `WorkflowNodeModel`、`NodeContainer` 和 `NodeCascader`，保留
 `node_data.document_list` 引用协议；必填和引用有效性校验统一由表单执行。初始化补齐引用数组，
@@ -280,7 +269,7 @@ AI 对话、意图识别、问题优化、参数提取、图片理解、视频
 `UserInputFieldTable` 通过 `v-model` / `v-model:config` 编辑文档设置和标题，使用 `MkTable` 排序。
 字段弹窗复用 `MkDynamicsFormConstructor`，保留原有七种输入类型及旧 input/select/date 字段兼容，
 标题和字段弹窗统一使用 `MkDialog`。增删、编辑及排序后同步 `config.globalFields` 并失效下游缓存，
-输出固定保留 `global.knowledge`，复制引用使用 `copyText`；输出计算不再修改节点数据。
+输出固定保留 `global.knowledge`，复制引用使用 `copyText`；输出计算不修改节点数据。
 
 #### 基本信息设置
 
@@ -317,7 +306,7 @@ AI 对话、意图识别、问题优化、参数提取、图片理解、视频
 #### AI 对话与提示词
 
 AI 对话节点的 `component/resource-setting` 仅渲染技能卡片内的 MCP、工具、Skills 和智能体分组，
-各分组直接在入口使用 `MkCollapse`，不再拆分普通列表子组件，仅选择弹窗独立封装。
+各分组直接在入口使用 `MkCollapse`，普通列表区直接维护，仅选择弹窗独立封装。
 工具和 Skills 的添加入口复用 `SelectToolDialog`，智能体入口使用 `SelectApplicationDialog`；
 System 共享资源不展示智能体分组，也不挂载智能体选择弹窗。
 Skills 仅查询 SKILL 类型，选择器排除当前路由对应的智能体或工具。确认后同时更新执行用的
@@ -336,7 +325,7 @@ AI 对话节点的提示词、历史记录、视觉理解和输出思考表单
 组件将画布注入的 `resourceScope` 传给 `useWorkflowStore`，通过 `store.postPromptGenerate` 发起生成；
 Store 适配器统一选择 Workspace、System 资源管理或 System 共享资源的 Model API。
 循环画布已转发同一上下文，组件不再单独判断资源范围。生成方法不使用 Store 的查询缓存或请求去重。
-生成接口不再依赖应用，改用节点自身已保存的模型参数（`model_params_setting`）并随请求体提交，
+生成接口使用节点自身已保存的模型参数（`model_params_setting`）并随请求体提交，
 因此智能体、工具和知识库工作流均可使用；弹窗不提供独立模型或参数设置。
 公共组件统一维护主题输入、会话消息与 `ConversationStream`；重新生成在历史中追加用户消息
 `Re generate` 后请求，停止通过 `cancel()` 终止读取，关闭动画结束后清理会话。
@@ -421,7 +410,7 @@ MkFormList 的排序、增删均以 `cloneDeep` 回写；MkTable 保留普通行
 - `Execution-details/index.vue`（`ExecutionDetailContent`）是顶层分发层：接收 `detail` 数组和 `workflowMode`，
   按 `index` 升序，逐项按节点类型渲染对应节点的详情组件。类型到详情组件的映射来自
   `import.meta.glob('../nodes/*/index.ts')` 收集的默认导出中的 `details` 字段，与画布节点注册同一份
-  清单，不按目录名推断，也不再单独维护映射表。未注册详情的类型当前跳过渲染。
+  清单，不按目录名推断，不单独维护映射表。未注册详情的类型当前跳过渲染。
 - `Execution-details/DetailContainer.vue` 是与节点类型无关的布局容器：提供 `#header` 具名
   插槽、折叠体默认插槽承载节点内容，以及 `showContentOnError` 决定失败时是否仍
   展示内容（默认失败只显示错误日志块）。
@@ -460,8 +449,7 @@ MkFormList 的排序、增删均以 `cloneDeep` 回写；MkTable 保留普通行
 
 ## View 接入约定
 
-- 所有画布路由页面均放在 `src/views/workflow/`，并以 `XxxWorkflowView.vue` 命名，例如
-  `ApplicationWorkflowView.vue`、`KnowledgeWorkflowView.vue`。
+- 所有画布路由页面使用 `src/views/workflow/<resource>/index.vue`。
 - View 在 `WorkflowCanvas` 外部组织页面头部的保存、发布、调试等页面级操作；添加组件属于画布操作，
   由 `WorkflowCanvas` 内的 `NodeAdd` 统一提供。
 - 画布页面需要独立全屏展示时，由 `src/router/admin/workflow/` 配置不挂载业务 Layout 的路由；
@@ -469,8 +457,7 @@ MkFormList 的排序、增删均以 `cloneDeep` 回写；MkTable 保留普通行
 - View 通过 Props 或实例方法传入图数据，加载、保存及错误处理由 View 或所属业务层编排；
   当前三个页面加载完成后调用 `render()`，等待 Vue 更新后记录图快照并 `fitView()`。
 - View 显式传入成对的 `workflowMode` / `loopWorkflowMode`，分别用于主画布和循环体菜单。
-- 页面共用 `views/workflow/components/WorkflowViewLayout.vue`，由其展示标题、保存时间与返回入口，
-  页面通过 `actions` 插槽提供按钮；智能体与知识库为 Workspace 全屏路由，工具额外支持两种 System 全屏路由。
+- 页面布局、保存／发布／调试及来源导航见 [VIEW_README.md](../views/VIEW_README.md#工作流页面)。
 
 `WorkflowCanvas` 的 Props：
 
@@ -500,14 +487,9 @@ MkFormList 的排序、增删均以 `cloneDeep` 回写；MkTable 保留普通行
 当前 `renderGraphData()` 不主动销毁上一实例；普通数据加载使用 `render()`，不要将前者当作
 已封装完整清理的重置方法。画布卸载时销毁当前实例并清理 Teleport。
 
-默认模型入口由 `ButtonDefaultModelSetting` 延迟挂载抽屉；`save` 交由页面持久化配置。
-“应用到所有节点”确认后深拷贝图数据，递归切换循环体及相关节点的模型来源，保留自定义模型和参数，
-基本信息仅处理已启用的语音、长期记忆设置并保留浏览器语音。`apply-to-all` 由页面调用
-`renderGraphData()` 更新画布，本身不保存图数据，也不提交抽屉中的模型草稿。
-
 ## 节点维护流程
 
-新增或迁入节点时，按实际需要检查以下位置：
+新增节点时，按实际需要检查以下位置：
 
 1. 在 `types.ts` 的 `WorkflowNodeType` 中声明稳定的 LogicFlow 节点类型值。
 2. 在 `config/node-data.ts` 中添加节点静态配置。
@@ -521,43 +503,14 @@ MkFormList 的排序、增删均以 `cloneDeep` 回写；MkTable 保留普通行
 节点协议值统一使用 `WorkflowNodeType` 等枚举或画布常量，不在判断和映射中重复书写
 `ai-chat-node`、`tool-custom-node` 等字符串字面量。
 
-## 当前接入状态
-
-以下按当前源码启用的行为记录；节点实现与详情覆盖分别以 `nodes/*/index.ts` 的模型注册和
-`details` 字段为准，不以文件存在或注释中的预留代码判断完成。
-
-| 页面                                      | 已接入                                                                       | 尚未启用                                       |
-| ----------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------- |
-| `application/ApplicationWorkflowView.vue` | 详情加载、默认节点、手动与自动保存、默认模型设置、调试对话、发布历史与版本预览恢复 | 发布按钮目前仅校验，发布请求被注释；更新说明需后端支持 |
-| `tool/ToolWorkflowView.vue`               | 工具与工作流详情加载、默认节点、手动与自动保存、默认模型设置、发布、历史预览与恢复、参数调试与执行详情、模板覆盖 | —                                 |
-| `knowledge/KnowledgeWorkflowView.vue`     | 从知识库详情加载、本地文件默认节点、手动与自动保存、默认模型设置、校验后保存并发布、历史预览恢复、模板覆盖、导出与任务调试 | —                                 |
-
-三个页面的返回按钮均提供“保存并退出 / 直接退出”确认；选择保存时成功后才退出，
-关闭确认框则留在当前页。当前没有路由离开或浏览器关闭守卫。
-智能体调试使用 `Conversation` 的 `DEBUG` 模式，有未保存图改动时先保存，再打开右侧可放大的对话面板。
-知识库默认模型已接入前端详情与保存协议，服务端持久化要求见 `../api/API_README.md` 的“知识库工作流”。
-
-执行详情已包含知识库检索、多路召回、文档标签检索、表单收集和语音节点；文档分段、知识库写入、
-本地/Web 数据源尚无 `details` 注册。基本信息类节点和循环体辅助节点同样未注册独立详情。
-智能体发布历史由 `views/workflow/components/publish-history/` 提供，预览期间禁止保存历史图；
-退出预览恢复原草稿，恢复版本后回到编辑态。工具与知识库均复用该面板并使用各自的版本 API。
-完整国际化尚未接入；资源范围适配的限制见“资源查询”。
-
-## 检查
-
-修改后至少运行与改动范围相符的检查：
-
-```bash
-npm run type-check
-npx eslint <本次修改的Vue或TypeScript文件>
-git diff --check
-```
+## 当前实现边界
 
-当前 `npm run lint` 尚未配置对应的 `lint:*` 子脚本，不能替代实际 ESLint 检查。
-仅修改 Markdown 文档时，检查修改文件的 Prettier 格式、路径引用及 `git diff --check` 即可。
+以 `nodes/*/index.ts` 的模型和 details 注册判断节点／执行详情是否支持，不以文件存在推断。
+文档分段、知识库写入、本地／Web 数据源及基本信息类和循环辅助节点未注册独立 details。
+缺少详情的节点由分发层跳过。资源适配器的范围限制见“资源查询”。
 
-若当前迁移中的预留文件仍存在已知类型错误，应在交付说明中明确区分，不要通过改变现有画布业务
-逻辑来绕过。
+知识库页面尚未注入 resourceScope，画布沿默认 workspace 查询，
+其他来源路由已存在，但不能据此认定画布辅助查询已按来源适配。
 
-System 工具节点菜单直接查询当前范围工具选项，不展示 Workspace 文件夹；普通工具节点通过
-Store 强制刷新工具详情，与工作流工具节点保持相同的资源范围。
+页面发布、历史、自动保存、调试和返回确认的当前行为统一见 View 文档，验证规则见
+[AGENTS.md](../../AGENTS.md#验证)。