@fgbg/mdocs 0.8.16 → 0.8.18

package/README.md

@@ -1,116 +1,154 @@
 # mdocs
 
-Markdown knowledge base for small teams.
+**开源 Markdown 知识库** — 给人用，也给 Agent 用。
 
-- TypeScript front-end and back-end
-- Vite + React web, Express back-end
-- SQLite metadata, Markdown files as primary storage
-- Lightweight visitor identity, no account system
-- Runs locally or on a small team server
+面向个人开发者与小团队：产品内 **智能助手 + 帮写**，外部 **CLI / Skills** 接入 Cursor / Claude；SQLite + 本地文件，**无账户**即可协作。
 
-> 文档站点：[xuhuafeifei.github.io/mdocs-site](https://xuhuafeifei.github.io/mdocs-site/)
+[文档站点](https://xuhuafeifei.github.io/mdocs-site/) · [GitHub](https://github.com/xuhuafeifei/mdocs) · [npm `@fgbg/mdocs`](https://www.npmjs.com/package/@fgbg/mdocs) · 当前版本 **0.8.18**
 
-编辑界面图片:
-<img width="1440" height="812" alt="image" src="https://github.com/user-attachments/assets/605e7299-7485-4809-a9e1-0918c686d5fd" />
-**上述文章是通过mdocs-cli由agent阅读Deepseek-TUI代码后推送的**
+<p align="center">
+  <img src="image/site主页.png" alt="mdocs 文档站点首页" width="860" />
+</p>
 
-后台界面
-<img width="1440" height="812" alt="image" src="https://github.com/user-attachments/assets/aba8ae95-40d5-49ba-a469-7665f8e3f21b" />
+## 为什么选 mdocs
 
+| 能力 | 说明 |
+|------|------|
+| **AI 双模式** | **智能助手**：答疑、搜文、结构操作、有条件全文覆写（低交互），帮你省操作时间。**帮写**：左聊右 Diff、按段接受后再写回（高交互），精细控制每一段文字。 |
+| **Agent 开发闭环** | CLI Token + [mdocs-cli](https://github.com/xuhuafeifei/mdocs-cli) Skills：在 Cursor / Claude 里搜索、读写知识库；`mdocs-dev` / `diagram` 把契约与 Mermaid 落进仓库，减少决策不落盘与知识漂移。 |
+| **本地私有** | 单进程，SQLite + 磁盘文件，无外部 DB / 缓存 / 队列。 |
+| **无账户协作** | 访客即身份；域隔离 + 文档级邀请，从私有到开放按需放开。 |
+| **双模编辑与草稿** | Markdown + 富文本工具栏；Meta2d / Mermaid / Markmap；本地草稿自动保存，空闲可同步云端。 |
 
-## Clean-room policy
+<p align="center">
+  <img src="image/mdocs%20主页.png" alt="mdocs 编辑主界面" width="860" />
+</p>
 
-`mdocs` is implemented from scratch. It MUST NOT reuse any code from
-`markdown-docs` (located at `~/ddmc/markdown-docs`). That includes, but is
-not limited to:
+## 快速开始
 
-- Source files, functions, classes, interfaces, types
-- SQL statements or schema definitions
-- React components, hooks, CSS
-- Utility helpers and configuration shapes
-- API route wiring or identity logic
+```bash
+npm install -g @fgbg/mdocs
+mdocs
+# 浏览器打开 http://localhost:4000
+```
+
+临时体验：
+
+```bash
+npx @fgbg/mdocs
+```
+
+需要 **Node.js 22+**。更细的安装（含低内存机器 Swap 说明）见 [文档 · 安装](https://xuhuafeifei.github.io/mdocs-site/docs/getting-started/installation.html)。
+
+## 功能速览
+
+### 智能助手
+
+左下角悬浮入口（可拖动）：答疑、搜文、建空文档 / 文件夹、移动文档。已有正文时写作会弹出选择卡：**直接覆写 / 打开帮写审阅 / 取消**。
+
+<p align="center">
+  <img src="image/Snipaste_2026-08-03_17-39-39.png" alt="智能助手入口标注" width="860" />
+</p>
+
+DeepSeek API Key 在设置页配置（按访客隔离）：
+
+<p align="center">
+  <img src="docs/screenshots/ai-settings.png" alt="AI 设置" width="720" />
+</p>
+
+### 帮写
+
+顶栏 **帮写** 进入全屏工作台：左 AI、右 Markdown Diff，按段接受 / 拒绝后再「完成并写回」。改稿前可查手册 skill、读工作稿，避免盲改。
+
+<p align="center">
+  <img src="image/mdocs帮写主页.png" alt="帮写工作台" width="860" />
+</p>
 
-Reuse of the `agent-demo` logger design is permitted because it is the
-author's own demo project.
+### Agent / CLI
 
-The **Meta2d / Vditor flow** matches `markdown-docs`: `useFlowRenderer`,
-`registerPens`, fenced `` ```meta2 `` blocks with inline JSON, **wysiwyg**
-mode (not IR), SVG preview in the preview half of each block, and
-`window.vditorInstance` for `getValue` / `setValue` when editing or deleting
-blocks.
+为 Agent 准备 CLI Token 后，可用 Skills 读写知识库（不必背完整命令，粘贴文章 URL 即可）。
 
-## Diagrams (Meta2d in Markdown)
+<p align="center">
+  <img src="docs/screenshots/mdocs-cli.png" alt="mdocs-cli" width="720" />
+</p>
 
-Diagrams live in the `.md` source as fenced blocks:
+详见：[Agent 开发闭环](https://xuhuafeifei.github.io/mdocs-site/docs/usage/agent-dev-loop.html) · [CLI Token](https://xuhuafeifei.github.io/mdocs-site/docs/usage/cli-token.html)
 
-````markdown
-```meta2
-{ "pens": [ … ] }
+### 编辑、域与协作
+
+斜杠菜单插入 Meta2d / Markmap 等；域管理、评论、收藏等能力齐全。
+
+<p align="center">
+  <img src="docs/screenshots/slash-menu.png" alt="斜杠菜单" width="420" />
+  <img src="docs/screenshots/domain-manager.png" alt="域管理" width="420" />
+</p>
+
+<p align="center">
+  <img src="docs/screenshots/doc-tree.png" alt="文档树" width="280" />
+  <img src="docs/screenshots/comments.png" alt="评论" width="560" />
+</p>
+
+## 从源码开发
+
+```bash
+git clone https://github.com/xuhuafeifei/mdocs.git
+cd mdocs
+pnpm install
+pnpm dev          # API :4000 + Vite :5173（代理 /api）
 ```
-````
 
-The editor renders them as SVG (via `canvas2svg` + Meta2d, same approach as
-`markdown-docs`). Saving the modal rewrites that JSON in the document with
-`Vditor#setValue`. Use the toolbar **Insert diagram** (or double-click a
-diagram). Switch **edit-mode** / **both** in the Vditor toolbar for source vs
-wysiwyg. Large documents: API JSON body limit is 32&nbsp;MiB.
+```bash
+pnpm build && pnpm start   # 生产：同端口提供静态资源与 API
+pnpm test
+pnpm typecheck
+pnpm mdocs visitor list    # 管理 CLI（开发用 tsx 入口）
+```
 
-## Layout
+仓库布局：
 
 ```
 src/
-  server/    Node back-end
-  web/       Vite React front-end
-  shared/    Cross-cutting types and schemas
+  server/    Express API、Agent、文档/域服务、CLI
+  web/       Vite + React 前端
+  shared/    两侧共用类型与路径工具
 ```
 
-Runtime data lives under `~/.mdocs/`:
+## 运行时数据
+
+默认目录 `~/.mdocs/`（可用 `MDOCS_DATA_DIR` 覆盖）：
 
 ```
 ~/.mdocs/
-  data.sqlite
-  files/
-    docs/
-    assets/
+  sqlite/data.sqlite
+  files/docs/          # 文档内容
+  files/assets/        # 附件
   logs/
 ```
 
-`domain_id` is a logical grouping inside SQLite and does not appear in file
-paths. Moving a document between domains only updates the database.
+`domain_id` 只存在于 SQLite，**不会**出现在文件路径里。
 
-## Development
+## 访客身份与迁移
 
-```bash
-pnpm install
-pnpm dev:server   # http://localhost:4000
-pnpm dev:web      # http://localhost:5173, proxies /api
-```
+首次访问输入昵称 → 获得 `visitor_id` + 高熵 token；浏览器存明文，服务端只存 `SHA-256(token)`，请求头 `x-visitor-token`。
 
-## Build and run
+清缓存后重新注册可用迁移合并身份：
 
 ```bash
-pnpm build
-pnpm start        # serves web static files and /api on one port
+mdocs visitor migrate --from Alice --to Bob --dry-run
+mdocs visitor migrate --from Alice --to Bob --confirm
 ```
 
-## Visitor identity
-
-On first visit the user enters a nickname. The server issues a
-`visitor_id` (UUID) and a high-entropy `visitor_token`. The browser keeps
-the raw token; the server only stores `SHA-256(token)`. Each request
-sends the raw token in an `x-visitor-token` header; the server hashes it
-and looks up the visitor.
+## 相关链接
 
-## Visitor migration
+| | |
+|--|--|
+| 产品文档 | https://xuhuafeifei.github.io/mdocs-site/ |
+| 文档源码站 | https://github.com/xuhuafeifei/mdocs-site |
+| CLI / Skills | https://github.com/xuhuafeifei/mdocs-cli |
+| 问题反馈 | https://github.com/xuhuafeifei/mdocs/issues |
 
-If the browser cache is cleared a user will register a new visitor. An
-administrator can merge the old identity into the new one:
+截图：[`image/`](./image/) 为最新实拍；[`docs/screenshots/`](./docs/screenshots/) 另有站点素材补充。
 
-```bash
-pnpm mdocs visitor migrate --from OLD_VISITOR_ID --to NEW_VISITOR_ID --dry-run
-pnpm mdocs visitor migrate --from OLD_VISITOR_ID --to NEW_VISITOR_ID --confirm
-```
+## License
 
-The script backs up the SQLite file, runs inside a transaction, updates
-ownership, disables the old visitor, and appends an entry to
-`visitor_migrations` and `audit_logs`. Markdown files are never moved.
+[MIT](./LICENSE)

package/agent-skills/changelog/SKILL.md

@@ -1,13 +1,27 @@
 ---
 id: changelog
 name: "更新日志"
-description: "- **帮写（coding）**：编辑器顶栏 / 欢迎页入口进入全屏工作台；左 AI、右纯 Markdown；按段接受/拒绝提案后再写回（已有文进草稿，空白帮写可新建） - **帮写上下文**：每轮请求携带进场快照与当前工作稿；助手可「读取帮写工作稿」后再「设置帮写正文」，避免盲改 - **帮写会话**：独立于上手助手；按文档隔离（A 文 / B 文各自历史）；空白帮写写回成文后会话绑到新文档 -"
+description: "- **首屏加速**：编辑器 / 设置 / 助手 / 帮写按需懒加载；Vite 拆分重型 vendor chunk，入口 JS 从约 6MB 降到约 134KB - **更快看到侧栏树**：启动时延后全文索引重建（默认约 15s，可用 `MDOCS_INDEX_INITIAL_DELAY_MS` 调整），减轻 HTML TTFB 被 CPU 拖慢 - **加载壳**：`index.html` 增加"
 keywords: []
 source: changelog.md
 ---
 
 # 更新日志
 
+## v0.8.18
+
+- **首屏加速**：编辑器 / 设置 / 助手 / 帮写按需懒加载；Vite 拆分重型 vendor chunk，入口 JS 从约 6MB 降到约 134KB
+- **更快看到侧栏树**：启动时延后全文索引重建（默认约 15s，可用 `MDOCS_INDEX_INITIAL_DELAY_MS` 调整），减轻 HTML TTFB 被 CPU 拖慢
+- **加载壳**：`index.html` 增加「mdocs 加载中…」占位，减少白屏感
+
+## v0.8.17
+
+- **AI 双模式定位明确**：智能助手（Ask）偏低交互——可答疑、搜文、结构操作，也能直接全文覆写；帮写（Coding）偏高交互——左聊右 Diff、按段接受、你拍板后才写回
+- **智能助手：覆写选择卡**：有正文时请求写作，弹出三选一：直接覆写 / 打开帮写审阅 / 取消
+- **智能助手：写后同步**：覆写成功后若当前打开该文档，自动触发拉取更新逻辑，刷新 headCommitId
+- **帮写欢迎文案**：明确「精细改稿请用帮写」，不再说「不协助写作」
+- **官网文档**：补充双模式 8 维度对比表，更新首页卖点
+
 ## v0.8.16
 
 - **帮写（coding）**：编辑器顶栏 / 欢迎页入口进入全屏工作台；左 AI、右纯 Markdown；按段接受/拒绝提案后再写回（已有文进草稿，空白帮写可新建）

package/agent-skills/index/SKILL.md

@@ -17,7 +17,7 @@ source: index.md
 
 ## AI 与 Agent
 
-- [上手助手（AI）](./usage/onboarding-ai.md)——Ask 答疑 / 帮写改稿；共用 DeepSeek 配置
+- [智能助手（AI）](./usage/onboarding-ai.md)——低交互覆写 vs 帮写高交互审阅
 - [Agent 开发闭环](./usage/agent-dev-loop.md)——CLI + Skills 接入 Cursor / Claude
 - [CLI Token](./usage/cli-token.md)——命令行与 Agent 身份令牌
 

package/agent-skills/index.json

@@ -2,7 +2,7 @@
   {
     "id": "changelog",
     "name": "更新日志",
-    "description": "- **帮写（coding）**：编辑器顶栏 / 欢迎页入口进入全屏工作台；左 AI、右纯 Markdown；按段接受/拒绝提案后再写回（已有文进草稿，空白帮写可新建） - **帮写上下文**：每轮请求携带进场快照与当前工作稿；助手可「读取帮写工作稿」后再「设置帮写正文」，避免盲改 - **帮写会话**：独立于上手助手；按文档隔离（A 文 / B 文各自历史）；空白帮写写回成文后会话绑到新文档 -",
+    "description": "- **首屏加速**：编辑器 / 设置 / 助手 / 帮写按需懒加载；Vite 拆分重型 vendor chunk，入口 JS 从约 6MB 降到约 134KB - **更快看到侧栏树**：启动时延后全文索引重建（默认约 15s，可用 `MDOCS_INDEX_INITIAL_DELAY_MS` 调整），减轻 HTML TTFB 被 CPU 拖慢 - **加载壳**：`index.html` 增加",
     "keywords": [],
     "source": "changelog.md"
   },
@@ -155,8 +155,8 @@
   },
   {
     "id": "usage-onboarding-ai",
-    "name": "上手助手（AI）",
-    "description": "mdocs 内置两种 AI 能力，共用设置页里的 DeepSeek 配置：",
+    "name": "智能助手（AI）",
+    "description": "mdocs 内置 **两种 AI 能力模式**，共用设置页里的 DeepSeek 配置。",
     "keywords": [],
     "source": "usage/onboarding-ai.md"
   },
@@ -177,7 +177,7 @@
   {
     "id": "usage-settings",
     "name": "设置页面",
-    "description": "设置页面是 mdocs 的集中配置中心：身份与密码、收藏与文章、域与成员模板、上手助手、草稿同步等都在这里。",
+    "description": "设置页面是 mdocs 的集中配置中心：身份与密码、收藏与文章、域与成员模板、智能助手、草稿同步等都在这里。",
     "keywords": [],
     "source": "usage/settings.md"
   },

package/agent-skills/usage-agent-dev-loop/SKILL.md

@@ -10,13 +10,13 @@ source: usage/agent-dev-loop.md
 
 mdocs 不只给人在浏览器里写文档，也让 **外部 AI Agent**（Cursor、Claude Code、Codex 等）把知识库嵌进日常工作。
 
-这和产品内的 [上手助手（AI）](./onboarding-ai.md) 是两条路：
+这和产品内的 [智能助手（AI）](./onboarding-ai.md) 是两条路：
 
-| | 上手助手 | Agent 开发闭环 |
+| | 智能助手 | Agent 开发闭环 |
 |--|----------|----------------|
-| 在哪 | mdocs Web 浮层 | 你的 IDE / Agent 终端 |
-| 干什么 | 答「怎么用 mdocs」 | 读知识库、按契约开发、按需写回文档 |
-| 会不会改正文 | **不会**（不代写） | 会按你的指令经 CLI 读写文档 |
+| 在哪 | mdocs Web 浮层 / 帮写 | 你的 IDE / Agent 终端 |
+| 干什么 | 答疑、搜文、结构操作；精细改稿走「帮写」 | 读知识库、按契约开发、按需写回文档 |
+| 会不会改正文 | 智能助手可有条件覆写；帮写需分段接受 | 会按你的指令经 CLI 读写文档 |
 
 ---
 
@@ -171,9 +171,9 @@ Agent 会按 **mdocs-dev** skill 工作：在项目根维护 **`.mdocs-docs/`
 
 ---
 
-## 和上手助手的知识关系
+## 和智能助手的知识关系
 
 - **本站文档**是给人读的手册真源。
-- mdocs 上手 Agent 构建时会把本站手册打成包内 Skills。
+- mdocs 智能助手构建时会把本站手册打成包内 Skills。
 - 因此：改好本站使用说明，既服务人类读者，也服务产品内 AI。
 

package/agent-skills/usage-onboarding-ai/SKILL.md

@@ -1,65 +1,134 @@
 ---
 id: usage-onboarding-ai
-name: "上手助手（AI）"
-description: "mdocs 内置两种 AI 能力，共用设置页里的 DeepSeek 配置："
+name: "智能助手（AI）"
+description: "mdocs 内置 **两种 AI 能力模式**，共用设置页里的 DeepSeek 配置。"
 keywords: []
 source: usage/onboarding-ai.md
 ---
 
-# 上手助手（AI）
+# 智能助手（AI）
 
-mdocs 内置两种 AI 能力，共用设置页里的 DeepSeek 配置：
+mdocs 内置 **两种 AI 能力模式**，共用设置页里的 DeepSeek 配置。
 
-| 模式 | 入口 | 做什么 |
-|------|------|--------|
-| **上手助手（Ask）** | 左下角悬浮球 | 答疑 + 账号内结构操作（搜文、列树、读文、建空文档/文件夹等）。**不会**代写或改正文 |
-| **帮写（Coding）** | 编辑器顶栏「帮写」/ 欢迎页「AI 帮写」 | 全屏工作台起草或改稿；右侧是纯 Markdown，按段接受后再写回 |
+**最大区别是用户交互度：**
+
+| | 🤖 智能助手 | ✍️ 帮写（Coding） |
+|--|-------------|-------------------|
+| **交互度** | **低**：以结果为导向，正文侧偏 **一次覆写**（空文可直写；有正文需你点确认或改走帮写） | **高**：以过程为导向，必须和你 **交互审阅**——分段提案、接受/拒绝，你拍板后才写回 |
+| **你在干什么** | 提需求 →（必要时确认）→ 看结果 | 提需求 → 看 Diff → 逐段/整批决定 → 完成并写回 |
+
+其他差异是为此服务的：
+
+| 对比维度 | 智能助手（Ask / Normal） | 帮写（Coding） |
+|---------|--------------------------|----------------|
+| **入口** | 左下角悬浮球（可拖动） | 编辑器顶栏「帮写」/ 欢迎页「AI 帮写」 |
+| **UI** | 小浮层 | 全屏工作台（左对话、右 Markdown Diff） |
+| **写回时机** | 确认后直接写服务端（覆写） | 在缓冲区改到满意，点「完成并写回」才进本地草稿 |
+| **能力侧重** | 答疑、搜文、建空文档/文件夹、找位置、全文一键生成/重写 | 起草、改稿、润色、续写，精细控制每一段 |
+| **会话** | 全局历史（不绑文档） | 按文档隔离 |
+| **存储** | `tenant/<id>/agent/session/` | `tenant/<id>/agent/coding-session/` |
+
+**一句话：** 要快、愿意一次覆写 → 智能助手；要和 AI 来回改、段段把关 → 帮写。
 
 若你要用 Cursor / Claude 等**外部 Agent** 读写知识库、落开发契约，见 [Agent 开发闭环](./agent-dev-loop.md)。
 
-## 入口（上手助手）
+---
 
-左下角有圆形 **上手助手** 悬浮按钮（不占用正文区）。点击后打开浮层 **「mdocs 智能助手」**，主编辑区仍保持打开，可边问边写。可**按住拖动**入口到任意位置（本地记住）；挪过之后会出现「重置位置」。
+## 智能助手（Ask / Normal）
 
-![上手助手入口与聊天浮层](./onboarding-ai/entry.png)
+左下角圆形 **智能助手** 入口（可拖动）。点击打开浮层 **「mdocs 智能助手」**，主编辑区仍保持打开。按住拖动可改位置（本地记住）；挪过之后会出现「重置位置」。
 
-浮层内：
+![智能助手入口（可拖动）与聊天浮层](./onboarding-ai/entry.png)
 
+浮层开场会说明分工：**答疑用智能助手**（可搜文、建空文档、帮你找位置）；**写 / 精细改正文请用顶栏「帮写」**。
+
+浮层内：
 - 顶部：**+** 新建会话、历史列表、关闭
-- 中间：对话与指引内容（可含步骤、表格、工具结果折叠块等）；回复中的代码块可一键复制
+- 中间：问候语、快捷提问（如「如何发布文档？」「草稿是什么？」「如何创建域？」）与对话内容
 - 底部输入框：占位「把你的问题告诉我…」
 - 页脚提示：内容由 AI 生成，仅供参考
 
-## 帮写（Coding）
+### 可以做什么
 
-需要代写、润色或改某一篇正文时，用 **帮写**，不要用上手助手浮层。
+直接问，例如：
+- 如何发布文档？草稿是什么？
+- 如何创建域？权限怎么设置？
+- 帮我搜索 / 列出某域文档，并打开其中一篇说明要点
+- 帮我创建一个空文档「XXX」
+- 这篇文档几乎是空的，帮我写个大纲并直接写好
+
+### 覆写机制（有正文时）
+
+当文档已有实质内容，智能助手不会静默改写。你若要求覆写，助手会弹出**选择卡**，三选一：
+1. **直接覆写** → 同意后线性写入服务端（带版本冲突校验）
+2. **打开帮写审阅** → 跳帮写模式，先在右侧看提案再决定
+3. **取消** → 不写
+
+### 明确不会做
 
-1. 打开一篇文档（或欢迎页点「AI 帮写」从空白开始）
-2. 点顶栏 **帮写**（带 DeepSeek 标志）进入全屏层：左侧对话，右侧 Markdown
-3. 描述要写/改的内容；助手会先读当前工作稿与进场快照，再提交完整 Markdown 提案
-4. 右侧按变更段 **接受 / 拒绝**；也可继续手改
-5. **完成并写回**：已有文档写入本地草稿（需你再发布）；空白帮写则创建新文档
+- 静默改写有实质正文的文档（必须经你确认或走帮写）
+- 越权读取你无权查看的文档（与网页端同一套权限）
+- 精细改稿 / 逐段审阅（请用顶栏 **帮写**）
+
+---
 
-会话说明：
+## 帮写（Coding 模式）
 
-- 帮写会话与上手助手**分开存放**（`agent/coding-session/`）
+需要和 AI **高交互**地改正文（逐段看 Diff、接受/拒绝）时用 **帮写**。智能助手偏覆写结果；帮写偏过程协作。
+
+### 入口
+
+打开一篇文档后，在编辑器**顶栏工具条右侧**（发布 / 删除附近）点击 **帮写**（带星标图标）进入全屏工作台。欢迎页也可点「AI 帮写」从空白开始。
+
+![文档顶栏「帮写」入口](./onboarding-ai/ai-write-entry.png)
+
+### 工作流
+
+1. 通过顶栏 **帮写**（或欢迎页「AI 帮写」）进入全屏层：左侧对话，右侧 Markdown
+2. 描述要写/改的内容；助手会先读当前工作稿与进场快照，再提交完整 Markdown 提案
+3. 右侧按变更段 **接受 / 拒绝**；也可继续手改
+4. **完成并写回**：已有文档写入本地草稿（需你再发布）；空白帮写则创建新文档
+
+### 工作台界面
+
+![帮写全屏：左对话、右 Diff 审阅](./onboarding-ai/ai-write-workbench.png)
+
+| 区域 | 说明 |
+|------|------|
+| **顶栏** | 文档名；**取消**退出；**完成并写回**把已接受内容写回（已有文进本地草稿） |
+| **左侧 · 对话** | 说明要写/改什么；助手可「读取帮写工作稿」再「设置帮写正文」更新提案；**+** / 历史管理会话 |
+| **右侧 · 提案** | 红删绿增的分段 Diff；可 **全部接受 / 全部拒绝**，或逐段操作；也可切 **纯编辑** 手改；底部可在变更间跳转 |
+
+### 核心设计：高交互审阅
+
+帮写的核心不是「更能写」，而是 **必须和你交互**：
+- AI 吐出的是**完整 Markdown 提案**，不是直接改文件
+- 前端 diff 计算后**按段高亮**，每段你可独立「接受」或「拒绝」
+- 接受的段落合并进「当前稿」，剩余可继续手改或再次 AI 续写
+- 全程**不碰服务端**，直到你点「完成并写回」才写入本地草稿
+
+### 会话说明
+
+- 帮写会话与智能助手**完全隔离**，互不干扰
 - **按文档隔离**：文章 A 的历史看不到文章 B
 - 左侧同样有 **+** / 历史；历史只回放对话文字，不恢复右侧稿
 - 从空白帮写写回成文后，当前对话会绑到新文档，下次打开该文帮写可续聊
 
+---
+
 ## 开始使用前：配置模型
 
 1. 打开 **设置 → AI**（侧栏底部访客信息进入设置）
 2. 选择模型：`deepseek-v4-flash` 或 `deepseek-v4-pro`
 3. 填写你的 DeepSeek API Key 并保存
 
-![设置 → AI：上手助手模型配置](./onboarding-ai/ai-settings.png)
+![设置 → AI：智能助手模型配置](./onboarding-ai/ai-settings.png)
 
 未配置 Key 时，入口可用但无法发送消息，浮层 / 帮写会提示去设置页配置。
 
 每人一份配置，仅本人可用；Key 在服务端按访客隔离存储，不会出现在别的访客界面上。配置页可查看配置名称、模型、脱敏后的 Key 与配置 ID；需要改时可点 **编辑**。
 
-## 怎么问（上手助手）
+## 怎么问（智能助手）
 
 可以直接问，例如：
 
@@ -71,7 +140,7 @@ mdocs 内置两种 AI 能力，共用设置页里的 DeepSeek 配置：
 
 助手会按需阅读 [mdocs 用户手册](https://xuhuafeifei.github.io/mdocs-site/) 相关章节，也可在你有权阅读的范围内读取知识库文档。工具结果（搜索表、域树、读文预览等）会出现在对话时间线中，**默认折叠**，展开可查看；历史会话重开后通常只保留文字、不再回放这些工具块。答完后通常会附带一两个可继续追问的示例。
 
-## 会话（上手助手）
+## 会话（智能助手）
 
 - 同一访客的对话会保存在数据目录 `tenant/<访客ID>/agent/session/` 下，刷新或重开浮层仍可续聊。
 - 浮层标题栏 **「+」**：新建空会话并切换过去。
@@ -79,11 +148,11 @@ mdocs 内置两种 AI 能力，共用设置页里的 DeepSeek 配置：
 - 会话标题取自**第一条用户消息**（过长会截断），不是模型摘要。
 - 删除、重命名、按天数自动清理尚未提供。
 
-## 明确不会做（上手助手）
+## 明确不会做（智能助手）
 
-- 代写、润色、按选区改文档正文（请改用 **帮写**）
+- 静默改写有实质正文的文档（必须经你弹出选择卡确认）
 - 越权读取你无权查看的文档（与网页端同一套权限）
-- 静默替你发布或改权限档（结构操作会走工具；写作类请求会拒绝并引导去帮写）
+- 静默替你发布或改权限档（结构操作会走工具；写作类请求会根据上下文决定直写或弹选择卡）
 
-若你在上手助手里要求写作，助手会拒绝，并提示打开 **帮写**。
+若你在智能助手里要求写作，助手会根据文档状态决定：空文直接覆写，有正文则弹出选择卡。
 

package/agent-skills/usage-settings/SKILL.md

@@ -1,7 +1,7 @@
 ---
 id: usage-settings
 name: "设置页面"
-description: "设置页面是 mdocs 的集中配置中心：身份与密码、收藏与文章、域与成员模板、上手助手、草稿同步等都在这里。"
+description: "设置页面是 mdocs 的集中配置中心：身份与密码、收藏与文章、域与成员模板、智能助手、草稿同步等都在这里。"
 keywords: []
 source: usage/settings.md
 ---
@@ -10,7 +10,7 @@ source: usage/settings.md
 
 ## 功能概述
 
-设置页面是 mdocs 的集中配置中心：身份与密码、收藏与文章、域与成员模板、上手助手、草稿同步等都在这里。
+设置页面是 mdocs 的集中配置中心：身份与密码、收藏与文章、域与成员模板、智能助手、草稿同步等都在这里。
 
 ## 入口
 
@@ -33,7 +33,7 @@ source: usage/settings.md
 | [我的文章](./my-documents.md) | 自己创建的文档、邀请成员、打开 |
 | [域管理](./domain-members.md) | 创建 / 筛选 / 重命名 / 改类型 / 删除域；受限域成员 |
 | [域成员模板](./domain-members.md) | 可复用的访客名单 |
-| [AI](./onboarding-ai.md) | 上手助手的 DeepSeek 配置 |
+| [AI](./onboarding-ai.md) | 智能助手与帮写的 DeepSeek 配置 |
 | [保存与发布](./drafts.md) | 本地快照、自动同步、未发布草稿 |
 
 ---
@@ -76,7 +76,7 @@ Token / Cookie 丢失时的自助找回；引入登录密码后已边缘化。
 | 我的收藏 | [收藏功能](./bookmarks.md) |
 | 我的文章 | [我的文章](./my-documents.md) |
 | 域管理 / 域成员模板 | [受限域成员与名单模板](./domain-members.md) |
-| AI | [上手助手（AI）](./onboarding-ai.md) |
+| AI | [智能助手（AI）](./onboarding-ai.md) |
 | 保存与发布 | [草稿与同步](./drafts.md) |
 
 ---

package/dist/server/agent/Agent/almost-empty.js

@@ -0,0 +1,15 @@
+/**
+ * Ask 覆写判空：以纯文本判断「几乎空」。
+ * 约定：去空白无正文，或仅一行标题。
+ */
+export function isAlmostEmptyDocumentText(plainText) {
+    const trimmed = plainText.replace(/\u00a0/g, " ").trim();
+    if (!trimmed)
+        return true;
+    const lines = trimmed
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+    return lines.length <= 1;
+}
+//# sourceMappingURL=almost-empty.js.map

package/dist/server/agent/Agent/almost-empty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"almost-empty.js","sourceRoot":"","sources":["../../../../src/server/agent/Agent/almost-empty.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAAiB;IACzD,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACzD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE1B,MAAM,KAAK,GAAG,OAAO;SAClB,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE/B,OAAO,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;AAC3B,CAAC"}

package/dist/server/agent/Agent/almost-empty.test.js

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { isAlmostEmptyDocumentText } from "./almost-empty.js";
+describe("isAlmostEmptyDocumentText", () => {
+    it("empty / whitespace", () => {
+        expect(isAlmostEmptyDocumentText("")).toBe(true);
+        expect(isAlmostEmptyDocumentText("  \n\t  ")).toBe(true);
+    });
+    it("single title line", () => {
+        expect(isAlmostEmptyDocumentText("# 周报")).toBe(true);
+        expect(isAlmostEmptyDocumentText("周报")).toBe(true);
+    });
+    it("title plus blank lines only", () => {
+        expect(isAlmostEmptyDocumentText("# 周报\n\n\n")).toBe(true);
+    });
+    it("has real body", () => {
+        expect(isAlmostEmptyDocumentText("# 周报\n\n今天做了三件事。")).toBe(false);
+        expect(isAlmostEmptyDocumentText("第一段\n第二段")).toBe(false);
+    });
+});
+//# sourceMappingURL=almost-empty.test.js.map

package/dist/server/agent/Agent/almost-empty.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"almost-empty.test.js","sourceRoot":"","sources":["../../../../src/server/agent/Agent/almost-empty.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,QAAQ,CAAC,2BAA2B,EAAE,GAAG,EAAE;IACzC,EAAE,CAAC,oBAAoB,EAAE,GAAG,EAAE;QAC5B,MAAM,CAAC,yBAAyB,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,CAAC,yBAAyB,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mBAAmB,EAAE,GAAG,EAAE;QAC3B,MAAM,CAAC,yBAAyB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrD,MAAM,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACrC,MAAM,CAAC,yBAAyB,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,eAAe,EAAE,GAAG,EAAE;QACvB,MAAM,CAAC,yBAAyB,CAAC,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClE,MAAM,CAAC,yBAAyB,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}