From 19b8a595712027dbb1875f8845ac5c21829373b9 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Tue, 16 Jun 2026 17:57:13 +0800
Subject: [PATCH 01/36] =?UTF-8?q?docs(docs):=20=E6=9B=B4=E6=96=B0=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E5=AD=90=E6=A8=A1=E5=9D=97=E5=BC=95=E7=94=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs b/docs
index 1e1b571..610f2bb 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit 1e1b571ed26967e46e2e4f0406c1e687d1141788
+Subproject commit 610f2bb3d37912f71417f4dd200cbfa76ff7e7e2

From b87270fde704590a0d4257e80a504c6745c2f505 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Wed, 17 Jun 2026 22:33:18 +0800
Subject: [PATCH 02/36] =?UTF-8?q?refactor(layout):=20=E7=94=A8=20Activity?=
 =?UTF-8?q?=20Bar=20=E5=92=8C=E5=88=86=E7=B1=BB=E9=9D=A2=E6=9D=BF=E6=9B=BF?=
 =?UTF-8?q?=E6=8D=A2=E6=96=87=E4=BB=B6=E6=A0=91?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/components/category/ChapterList.vue   | 124 ++++++++++++++++
 .../components/category/ConversationList.vue  |  23 +++
 .../src/components/category/ElementList.vue   | 123 ++++++++++++++++
 .../src/components/category/PromptList.vue    | 118 +++++++++++++++
 .../app/src/components/layout/ActivityBar.vue | 136 ++++++++++++++++++
 .../src/components/layout/CategoryPanel.vue   |  69 +++++++++
 .../src/components/layout/FileTreeSidebar.vue | 113 ---------------
 packages/app/src/constants/category.ts        |  15 ++
 packages/app/src/constants/elements.ts        |  31 ++++
 packages/app/src/stores/project.ts            |  30 ++++
 packages/app/src/utils/file-tree.ts           |  76 ++++++++++
 packages/app/src/views/ProjectView.vue        |  89 ++++++++----
 12 files changed, 810 insertions(+), 137 deletions(-)
 create mode 100644 packages/app/src/components/category/ChapterList.vue
 create mode 100644 packages/app/src/components/category/ConversationList.vue
 create mode 100644 packages/app/src/components/category/ElementList.vue
 create mode 100644 packages/app/src/components/category/PromptList.vue
 create mode 100644 packages/app/src/components/layout/ActivityBar.vue
 create mode 100644 packages/app/src/components/layout/CategoryPanel.vue
 delete mode 100644 packages/app/src/components/layout/FileTreeSidebar.vue
 create mode 100644 packages/app/src/constants/category.ts
 create mode 100644 packages/app/src/constants/elements.ts
 create mode 100644 packages/app/src/utils/file-tree.ts

diff --git a/packages/app/src/components/category/ChapterList.vue b/packages/app/src/components/category/ChapterList.vue
new file mode 100644
index 0000000..8dc59bb
--- /dev/null
+++ b/packages/app/src/components/category/ChapterList.vue
@@ -0,0 +1,124 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import type { ProjectFileNodeView } from '@novai/core/services/types'
+import { pickDirectoryChildren } from '../../utils/file-tree'
+
+const props = defineProps<{
+  files: ProjectFileNodeView[]
+  activeFilePath?: string
+}>()
+
+const emit = defineEmits<{
+  selectFile: [path: string]
+}>()
+
+/**
+ * chapters/ 目录的直接子项（保持层级，可能含子目录「卷/部」+ 章节文件）。
+ * 章节页本身展示这个平铺列表；子目录通过展开/折叠渲染其子项。
+ */
+const chapterNodes = computed(() => pickDirectoryChildren(props.files, 'chapters'))
+
+const hasChapters = computed(() => chapterNodes.value.length > 0)
+
+/** 每个目录节点的展开状态，key = 目录 path */
+const expandedDirs = ref<Set<string>>(new Set())
+
+function toggleDir(path: string) {
+  if (expandedDirs.value.has(path)) {
+    expandedDirs.value.delete(path)
+  } else {
+    expandedDirs.value.add(path)
+  }
+}
+
+function isDirExpanded(path: string) {
+  return expandedDirs.value.has(path)
+}
+</script>
+
+<template>
+  <div class="flex h-full flex-col">
+    <div class="px-4 py-3">
+      <h2 class="text-sm font-semibold text-white">章节</h2>
+    </div>
+
+    <div class="flex-1 overflow-y-auto px-2 pb-2">
+      <!-- 空状态：chapters/ 目录为空或不存在 -->
+      <div v-if="!hasChapters" class="px-2 py-8 text-center">
+        <p class="mb-1 text-sm text-gray-400">还没有章节</p>
+        <p class="text-xs text-gray-500">在对话框输入指令，让 AI 开始第一章吧</p>
+      </div>
+
+      <!-- 章节列表：平铺渲染 chapters/ 直接子项 -->
+      <ul v-else class="space-y-0.5">
+        <li v-for="node in chapterNodes" :key="node.path">
+          <!-- 目录节点（卷/部）：可折叠的分组标题 -->
+          <button
+            v-if="node.kind === 'directory'"
+            class="flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-sm text-gray-400 transition-colors hover:bg-white/10 hover:text-gray-200"
+            @click="toggleDir(node.path)"
+          >
+            <svg
+              :class="['h-3.5 w-3.5 shrink-0 text-gray-500 transition-transform', isDirExpanded(node.path) ? 'rotate-90' : '']"
+              fill="none" stroke="currentColor" viewBox="0 0 24 24"
+            >
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" />
+            </svg>
+            <svg class="h-4 w-4 shrink-0 text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path
+                v-if="isDirExpanded(node.path)"
+                stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
+                d="M5 19a2 2 0 01-2-2V7a2 2 0 012-2h4l2 2h4a2 2 0 012 2v1M5 19h14a2 2 0 002-2v-5a2 2 0 00-2-2H9a2 2 0 00-2 2v5a2 2 0 01-2 2z"
+              />
+              <path
+                v-else
+                stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
+                d="M3 7v10a2 2 0 002 2h14a2 2 0 002-2V9a2 2 0 00-2-2h-6l-2-2H5a2 2 0 00-2 2z"
+              />
+            </svg>
+            <span class="flex-1 truncate">{{ node.name }}</span>
+            <span class="shrink-0 text-xs text-gray-500">{{ node.children?.length ?? 0 }}</span>
+          </button>
+
+          <!-- 目录展开后的子项 -->
+          <ul
+            v-if="node.kind === 'directory' && isDirExpanded(node.path) && node.children?.length"
+            class="mb-1 ml-3 border-l border-white/10 pl-2"
+          >
+            <li v-for="child in node.children" :key="child.path">
+              <button
+                v-if="child.kind === 'file'"
+                :class="[
+                  'flex w-full items-center rounded-md px-2 py-1 text-left text-xs transition-colors',
+                  child.path === activeFilePath
+                    ? 'bg-white/15 text-white'
+                    : 'text-gray-400 hover:bg-white/10 hover:text-gray-200',
+                ]"
+                @click="emit('selectFile', child.path)"
+              >
+                <span class="truncate">{{ child.name }}</span>
+              </button>
+            </li>
+          </ul>
+
+          <!-- 文件节点（章节）：直接渲染 -->
+          <button
+            v-if="node.kind === 'file'"
+            :class="[
+              'flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-sm transition-colors',
+              node.path === activeFilePath
+                ? 'bg-white/15 text-white'
+                : 'text-gray-400 hover:bg-white/10 hover:text-gray-200',
+            ]"
+            @click="emit('selectFile', node.path)"
+          >
+            <svg class="h-4 w-4 shrink-0 text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
+            </svg>
+            <span class="truncate">{{ node.name }}</span>
+          </button>
+        </li>
+      </ul>
+    </div>
+  </div>
+</template>
diff --git a/packages/app/src/components/category/ConversationList.vue b/packages/app/src/components/category/ConversationList.vue
new file mode 100644
index 0000000..3cddae0
--- /dev/null
+++ b/packages/app/src/components/category/ConversationList.vue
@@ -0,0 +1,23 @@
+<script setup lang="ts">
+// 对话历史分类面板。
+// 本轮为占位实现：对话历史持久化存储功能尚未开发。
+// 后续支持会话列表切换时，这里会渲染历史会话卡片。
+</script>
+
+<template>
+  <div class="flex h-full flex-col">
+    <div class="px-4 py-3">
+      <h2 class="text-sm font-semibold text-white">对话</h2>
+    </div>
+
+    <div class="flex-1 overflow-y-auto px-2 pb-2">
+      <div class="px-2 py-8 text-center">
+        <svg class="mx-auto mb-3 h-10 w-10 text-gray-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M8 10h.01M12 10h.01M16 10h.01M9 16H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-5l-5 5v-5z" />
+        </svg>
+        <p class="mb-1 text-sm text-gray-400">对话历史功能开发中</p>
+        <p class="text-xs text-gray-500">后续将支持历史会话列表切换</p>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/packages/app/src/components/category/ElementList.vue b/packages/app/src/components/category/ElementList.vue
new file mode 100644
index 0000000..9128ae4
--- /dev/null
+++ b/packages/app/src/components/category/ElementList.vue
@@ -0,0 +1,123 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import type { ProjectFileNodeView } from '@novai/core/services/types'
+import { ELEMENT_CATEGORIES } from '../../constants/elements'
+import { collectFilesByPrefix } from '../../utils/file-tree'
+
+const props = defineProps<{
+  files: ProjectFileNodeView[]
+  activeFilePath?: string
+}>()
+
+const emit = defineEmits<{
+  selectFile: [path: string]
+}>()
+
+/**
+ * 每个分组目录下递归收集到的文件（扁平列表，不含目录）。
+ * 按 directory 前缀深入收集，所以 elements/characters/ 下无论嵌套多深都能取到。
+ */
+function filesOf(directory: string): ProjectFileNodeView[] {
+  return collectFilesByPrefix(props.files, directory)
+}
+
+/** 预计算每个分组的文件数，标题右侧展示 */
+const counts = computed(() => {
+  const map = new Map<string, number>()
+  for (const category of ELEMENT_CATEGORIES) {
+    map.set(category.key, filesOf(category.directory).length)
+  }
+  return map
+})
+
+/** 总文件数：用于判断是否所有分组都为空（控制整体空状态是否展示） */
+const totalCount = computed(() => {
+  let sum = 0
+  for (const count of counts.value.values()) {
+    sum += count
+  }
+  return sum
+})
+
+/**
+ * 每个分组的展开状态。
+ * key = category.key，默认全部折叠。
+ */
+const expandedKeys = ref<Set<string>>(new Set())
+
+function toggleGroup(key: string) {
+  if (expandedKeys.value.has(key)) {
+    expandedKeys.value.delete(key)
+  } else {
+    expandedKeys.value.add(key)
+  }
+}
+
+function isExpanded(key: string) {
+  return expandedKeys.value.has(key)
+}
+</script>
+
+<template>
+  <div class="flex h-full flex-col">
+    <div class="px-4 py-3">
+      <h2 class="text-sm font-semibold text-white">要素</h2>
+    </div>
+
+    <div class="flex-1 overflow-y-auto px-2 pb-2">
+      <!-- 6 个分组始终展示（这是固定的分类结构，不因内容为空而隐藏） -->
+      <div class="space-y-0.5">
+        <div v-for="category in ELEMENT_CATEGORIES" :key="category.key">
+          <!-- 分组标题 -->
+          <button
+            class="flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-sm text-gray-400 transition-colors hover:bg-white/10 hover:text-gray-200"
+            @click="toggleGroup(category.key)"
+          >
+            <svg
+              :class="['h-3.5 w-3.5 shrink-0 text-gray-500 transition-transform', isExpanded(category.key) ? 'rotate-90' : '']"
+              fill="none" stroke="currentColor" viewBox="0 0 24 24"
+            >
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7" />
+            </svg>
+            <span class="shrink-0 text-sm">{{ category.icon }}</span>
+            <span class="flex-1 truncate">{{ category.label }}</span>
+            <span class="shrink-0 text-xs text-gray-500">{{ counts.get(category.key) ?? 0 }}</span>
+          </button>
+
+          <!-- 分组文件（展开时） -->
+          <ul
+            v-if="isExpanded(category.key)"
+            class="mb-1 ml-3 border-l border-white/10 pl-2"
+          >
+            <li v-for="node in filesOf(category.directory)" :key="node.path">
+              <button
+                :class="[
+                  'flex w-full items-center rounded-md px-2 py-1 text-left text-xs transition-colors',
+                  node.path === activeFilePath
+                    ? 'bg-white/15 text-white'
+                    : 'text-gray-400 hover:bg-white/10 hover:text-gray-200',
+                ]"
+                @click="emit('selectFile', node.path)"
+              >
+                <span class="truncate">{{ node.name }}</span>
+              </button>
+            </li>
+            <!-- 仅在该分组展开且为空时显示组内空状态 -->
+            <li v-if="filesOf(category.directory).length === 0">
+              <p class="px-2 py-1 text-xs text-gray-600">暂无</p>
+            </li>
+          </ul>
+        </div>
+      </div>
+
+      <!--
+        不再展示整体空状态。
+        6 个分组是项目的固定分类结构，默认折叠时本身就只显示标题行，
+        没有内容时让用户看到 6 个分组标题比显示「还没有要素」更符合预期。
+      -->
+      <p v-if="totalCount === 0" class="mt-3 px-2 pb-1 text-xs text-gray-600">
+        所有分组暂无要素文件
+      </p>
+    </div>
+  </div>
+</template>
diff --git a/packages/app/src/components/category/PromptList.vue b/packages/app/src/components/category/PromptList.vue
new file mode 100644
index 0000000..ef16827
--- /dev/null
+++ b/packages/app/src/components/category/PromptList.vue
@@ -0,0 +1,118 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { ProjectFileNodeView } from '@novai/core/services/types'
+import { pickDirectoryChildren } from '../../utils/file-tree'
+
+const props = defineProps<{
+  files: ProjectFileNodeView[]
+  activeFilePath?: string
+  /** 当前激活的场景提示词路径，null 表示未激活任何场景 */
+  activeScenePromptPath: string | null
+}>()
+
+const emit = defineEmits<{
+  selectFile: [path: string]
+  /** 切换激活场景，path 为 null 表示关闭场景 */
+  changeScene: [path: string | null]
+}>()
+
+/**
+ * prompts/ 目录的直接子项。
+ * 通常包含：system.md（系统提示词文件）+ scenes/（场景提示词子目录）。
+ */
+const promptRootChildren = computed(() => pickDirectoryChildren(props.files, 'prompts'))
+
+/** 系统提示词：prompts/system.md */
+const systemPrompt = computed<ProjectFileNodeView | null>(() => {
+  return promptRootChildren.value.find(
+    n => n.kind === 'file' && n.path === 'prompts/system.md',
+  ) ?? null
+})
+
+/** 场景提示词：prompts/scenes/ 目录下的所有 .md 文件（拉平） */
+const scenePrompts = computed<ProjectFileNodeView[]>(() => {
+  const sceneChildren = pickDirectoryChildren(props.files, 'prompts/scenes')
+  return sceneChildren.filter(n => n.kind === 'file' && n.path.endsWith('.md'))
+})
+
+function isSceneActive(path: string): boolean {
+  return props.activeScenePromptPath === path
+}
+</script>
+
+<template>
+  <div class="flex h-full flex-col">
+    <div class="px-4 py-3">
+      <h2 class="text-sm font-semibold text-white">提示词</h2>
+    </div>
+
+    <div class="flex-1 overflow-y-auto px-2 pb-2">
+      <!-- 系统提示词 -->
+      <div class="mb-2">
+        <p class="px-2 py-1 text-xs font-medium uppercase tracking-wide text-gray-500">系统提示词</p>
+        <button
+          v-if="systemPrompt"
+          :class="[
+            'flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-sm transition-colors',
+            systemPrompt.path === activeFilePath
+              ? 'bg-white/15 text-white'
+              : 'text-gray-400 hover:bg-white/10 hover:text-gray-200',
+          ]"
+          @click="emit('selectFile', systemPrompt.path)"
+        >
+          <span class="shrink-0">📄</span>
+          <span class="truncate">{{ systemPrompt.name }}</span>
+          <span class="ml-auto shrink-0 text-xs text-gray-500">恒激活</span>
+        </button>
+        <p v-else class="px-2 py-2 text-xs text-gray-600">
+          未找到系统提示词（prompts/system.md）
+        </p>
+      </div>
+
+      <!-- 场景提示词 -->
+      <div>
+        <p class="px-2 py-1 text-xs font-medium uppercase tracking-wide text-gray-500">场景提示词</p>
+
+        <!-- 场景列表为空 -->
+        <p
+          v-if="scenePrompts.length === 0"
+          class="px-2 py-2 text-xs text-gray-600"
+        >
+          暂无场景提示词，在 prompts/scenes/ 下新增 .md 文件即可
+        </p>
+
+        <ul v-else class="space-y-0.5">
+          <li v-for="node in scenePrompts" :key="node.path">
+            <!-- 场景项：点击预览，右侧标记控制激活态 -->
+            <button
+              :class="[
+                'group flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-sm transition-colors',
+                node.path === activeFilePath
+                  ? 'bg-white/15 text-white'
+                  : 'text-gray-400 hover:bg-white/10 hover:text-gray-200',
+              ]"
+              @click="emit('selectFile', node.path)"
+            >
+              <span class="shrink-0">🎬</span>
+              <span class="flex-1 truncate">{{ node.name }}</span>
+              <!-- 已激活：绿色实心点，点击关闭 -->
+              <span
+                v-if="isSceneActive(node.path)"
+                class="shrink-0 text-xs text-green-400"
+                title="当前激活场景，点击关闭"
+                @click.stop="emit('changeScene', null)"
+              >●</span>
+              <!-- 未激活：空心点，hover 显示，点击激活 -->
+              <button
+                v-else
+                class="shrink-0 rounded px-1 text-xs text-gray-600 opacity-0 transition-opacity hover:text-gray-300 group-hover:opacity-100"
+                title="设为当前场景"
+                @click.stop="emit('changeScene', node.path)"
+              >○</button>
+            </button>
+          </li>
+        </ul>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/packages/app/src/components/layout/ActivityBar.vue b/packages/app/src/components/layout/ActivityBar.vue
new file mode 100644
index 0000000..d74a9ca
--- /dev/null
+++ b/packages/app/src/components/layout/ActivityBar.vue
@@ -0,0 +1,136 @@
+<script setup lang="ts">
+import type { Category } from '../../constants/category'
+
+defineProps<{
+  activeCategory: Category
+}>()
+
+const emit = defineEmits<{
+  select: [category: Category]
+  openSettings: []
+  backToHome: []
+  /** 功能占位项：暂未实现，仅保留入口 */
+  proofread: []
+  organize: []
+  version: []
+}>()
+
+/**
+ * 顶部分类项（设置走单独的 openSettings，不在此列）。
+ * 顺序按产品决策：对话 → 章节 → 要素 → 提示词。
+ */
+const categoryItems: { key: Category; label: string; icon: string }[] = [
+  { key: 'conversation', label: '对话', icon: 'chat' },
+  { key: 'chapter', label: '章节', icon: 'book' },
+  { key: 'element', label: '要素', icon: 'tag' },
+  { key: 'prompt', label: '提示词', icon: 'note' },
+]
+
+/**
+ * 底部功能占位项（暂未实现）。
+ * 仅保留入口，点击触发对应 emit，由 ProjectView 决定如何反馈。
+ * 顺序对应原 FileTreeSidebar 底部：校对 → 章节整理 → 版本管理。
+ */
+const actionItems: { key: 'proofread' | 'organize' | 'version'; label: string; icon: string }[] = [
+  { key: 'proofread', label: '校对', icon: 'check' },
+  { key: 'organize', label: '章节整理', icon: 'list' },
+  { key: 'version', label: '版本管理', icon: 'branch' },
+]
+
+/**
+ * 模板里不能直接动态调 emit（联合类型无法匹配 emit 重载），
+ * 在 script 里集中分发。
+ */
+function emitAction(key: 'proofread' | 'organize' | 'version') {
+  switch (key) {
+    case 'proofread': emit('proofread'); break
+    case 'organize': emit('organize'); break
+    case 'version': emit('version'); break
+  }
+}
+</script>
+
+<template>
+  <nav class="flex w-14 shrink-0 flex-col items-center justify-between border-r border-white/10 bg-[#171717] py-2">
+    <!-- 顶部分类图标 -->
+    <div class="flex flex-col items-center gap-1">
+      <button
+        v-for="item in categoryItems"
+        :key="item.key"
+        :title="item.label"
+        :class="[
+          'group flex h-10 w-10 items-center justify-center rounded-lg transition-colors',
+          activeCategory === item.key
+            ? 'bg-white/15 text-white'
+            : 'text-gray-400 hover:bg-white/10 hover:text-gray-200',
+        ]"
+        @click="emit('select', item.key)"
+      >
+        <!-- 对话 -->
+        <svg v-if="item.icon === 'chat'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 10h.01M12 10h.01M16 10h.01M9 16H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-5l-5 5v-5z" />
+        </svg>
+        <!-- 章节 -->
+        <svg v-else-if="item.icon === 'book'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253" />
+        </svg>
+        <!-- 要素 -->
+        <svg v-else-if="item.icon === 'tag'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A1.994 1.994 0 013 12V7a4 4 0 014-4z" />
+        </svg>
+        <!-- 提示词 -->
+        <svg v-else class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4" />
+        </svg>
+      </button>
+    </div>
+
+    <!-- 底部动作项：功能占位 + 设置 + 返回首页 -->
+    <div class="flex flex-col items-center gap-1">
+      <!-- 功能占位项（暂未实现，灰一档提示） -->
+      <button
+        v-for="item in actionItems"
+        :key="item.key"
+        :title="`${item.label}（即将推出）`"
+        class="flex h-10 w-10 items-center justify-center rounded-lg text-gray-600 transition-colors hover:bg-white/10 hover:text-gray-400"
+        @click="emitAction(item.key)"
+      >
+        <!-- 校对 -->
+        <svg v-if="item.icon === 'check'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+        </svg>
+        <!-- 章节整理 -->
+        <svg v-else-if="item.icon === 'list'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 10h16M4 14h16M4 18h16" />
+        </svg>
+        <!-- 版本管理 -->
+        <svg v-else class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 7h12m0 0l-4-4m4 4l-4 4m0 6H4m0 0l4 4m-4-4l4-4" />
+        </svg>
+      </button>
+
+      <!-- 分隔线 -->
+      <div class="my-1 h-px w-6 bg-white/10" />
+
+      <button
+        title="设置"
+        class="flex h-10 w-10 items-center justify-center rounded-lg text-gray-400 transition-colors hover:bg-white/10 hover:text-gray-200"
+        @click="emit('openSettings')"
+      >
+        <svg class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.066 2.573c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.573 1.066c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.066-2.573c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z" />
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
+        </svg>
+      </button>
+      <button
+        title="返回首页"
+        class="flex h-10 w-10 items-center justify-center rounded-lg text-gray-400 transition-colors hover:bg-white/10 hover:text-gray-200"
+        @click="emit('backToHome')"
+      >
+        <svg class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6" />
+        </svg>
+      </button>
+    </div>
+  </nav>
+</template>
diff --git a/packages/app/src/components/layout/CategoryPanel.vue b/packages/app/src/components/layout/CategoryPanel.vue
new file mode 100644
index 0000000..f42caf5
--- /dev/null
+++ b/packages/app/src/components/layout/CategoryPanel.vue
@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import type { ProjectFileNodeView } from '@novai/core/services/types'
+import type { Category } from '../../constants/category'
+import ChapterList from '../category/ChapterList.vue'
+import ElementList from '../category/ElementList.vue'
+import PromptList from '../category/PromptList.vue'
+import ConversationList from '../category/ConversationList.vue'
+
+defineProps<{
+  activeCategory: Category
+  files: ProjectFileNodeView[]
+  activeFilePath?: string
+  activeScenePromptPath: string | null
+  /** 移动端抽屉是否展开（沿用现有响应式方案） */
+  isMobileOpen: boolean
+  /** 面板是否展开（桌面端折叠/展开） */
+  isOpen: boolean
+}>()
+
+const emit = defineEmits<{
+  selectFile: [path: string]
+  changeScene: [path: string | null]
+  closeMobile: []
+}>()
+</script>
+
+<template>
+  <aside
+    :class="[
+      'flex shrink-0 flex-col bg-[#171717] text-gray-100 transition-all duration-200',
+      'max-lg:fixed max-lg:inset-y-0 max-lg:left-[56px] max-lg:z-50',
+      isOpen ? 'w-64' : 'w-0 overflow-hidden',
+      isMobileOpen ? 'max-lg:translate-x-0' : 'max-lg:-translate-x-full',
+    ]"
+  >
+    <!-- 移动端关闭按钮 -->
+    <button
+      class="absolute right-2 top-2 z-10 rounded-lg p-1.5 text-gray-400 transition-colors hover:bg-white/10 hover:text-white lg:hidden"
+      @click="emit('closeMobile')"
+    >
+      <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+      </svg>
+    </button>
+
+    <!-- 按分类切换内容 -->
+    <ConversationList v-if="activeCategory === 'conversation'" />
+    <ChapterList
+      v-else-if="activeCategory === 'chapter'"
+      :files="files"
+      :active-file-path="activeFilePath"
+      @select-file="emit('selectFile', $event)"
+    />
+    <ElementList
+      v-else-if="activeCategory === 'element'"
+      :files="files"
+      :active-file-path="activeFilePath"
+      @select-file="emit('selectFile', $event)"
+    />
+    <PromptList
+      v-else-if="activeCategory === 'prompt'"
+      :files="files"
+      :active-file-path="activeFilePath"
+      :active-scene-prompt-path="activeScenePromptPath"
+      @select-file="emit('selectFile', $event)"
+      @change-scene="emit('changeScene', $event)"
+    />
+  </aside>
+</template>
diff --git a/packages/app/src/components/layout/FileTreeSidebar.vue b/packages/app/src/components/layout/FileTreeSidebar.vue
deleted file mode 100644
index ac84aef..0000000
--- a/packages/app/src/components/layout/FileTreeSidebar.vue
+++ /dev/null
@@ -1,113 +0,0 @@
-<script setup lang="ts">
-import type { ProjectView } from '@novai/core/services/types'
-import TreeNode from '../file-tree/TreeNode.vue'
-
-defineProps<{
-  isOpen: boolean
-  isMobileOpen: boolean
-  project: ProjectView | null
-  activeFilePath?: string
-}>()
-
-const emit = defineEmits<{
-  backToHome: []
-  openSettings: []
-  closeMobile: []
-  selectFile: [path: string]
-  refreshTree: []
-}>()
-</script>
-
-<template>
-  <aside
-    :class="[
-      'flex shrink-0 flex-col bg-[#171717] text-gray-100 transition-all duration-200',
-      'max-lg:fixed max-lg:inset-y-0 max-lg:left-0 max-lg:z-50',
-      isOpen ? 'w-64' : 'w-0 overflow-hidden',
-      isMobileOpen ? 'max-lg:translate-x-0' : 'max-lg:-translate-x-full',
-    ]"
-  >
-    <!-- 头部 -->
-    <div class="flex items-center justify-between border-b border-white/10 px-4 py-3">
-      <div class="flex items-center gap-2">
-        <h2 class="text-sm font-semibold text-white">文件</h2>
-      </div>
-      <div class="flex items-center gap-1">
-        <button
-          class="rounded-lg p-1.5 text-gray-400 transition-colors hover:bg-white/10 hover:text-white"
-          title="返回首页"
-          @click="emit('backToHome')"
-        >
-          <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6" />
-          </svg>
-        </button>
-        <button
-          class="rounded-lg p-1.5 text-gray-400 transition-colors hover:bg-white/10 hover:text-white"
-          title="设置"
-          @click="emit('openSettings')"
-        >
-          <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.066 2.573c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.573 1.066c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.066-2.573c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z" />
-            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
-          </svg>
-        </button>
-        <button
-          class="rounded-lg p-1.5 text-gray-400 transition-colors hover:bg-white/10 hover:text-white lg:hidden"
-          @click="emit('closeMobile')"
-        >
-          <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
-          </svg>
-        </button>
-      </div>
-    </div>
-
-    <!-- 项目名称 -->
-    <div v-if="project" class="border-b border-white/10 px-4 py-2">
-      <p class="truncate text-xs text-gray-400">{{ project.name }}</p>
-    </div>
-
-    <!-- 文件树 -->
-    <nav class="flex-1 overflow-y-auto px-2 py-2">
-      <div v-if="!project" class="px-2 py-4 text-center text-sm text-gray-500">
-        未打开项目
-      </div>
-      <div v-else-if="project.files.length === 0" class="px-2 py-4 text-center text-sm text-gray-500">
-        项目为空
-      </div>
-      <div v-else class="space-y-0.5">
-        <TreeNode
-          v-for="node in project.files"
-          :key="node.path"
-          :node="node"
-          :level="0"
-          :active-file-path="activeFilePath"
-          @select-file="emit('selectFile', $event)"
-        />
-      </div>
-    </nav>
-
-    <!-- 底部功能入口 -->
-    <div class="border-t border-white/10 px-2 py-2">
-      <button class="flex w-full items-center gap-2 rounded-md px-3 py-2 text-sm text-gray-400 transition-colors hover:bg-white/10 hover:text-gray-200">
-        <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
-        </svg>
-        校对
-      </button>
-      <button class="flex w-full items-center gap-2 rounded-md px-3 py-2 text-sm text-gray-400 transition-colors hover:bg-white/10 hover:text-gray-200">
-        <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 10h16M4 14h16M4 18h16" />
-        </svg>
-        章节整理
-      </button>
-      <button class="flex w-full items-center gap-2 rounded-md px-3 py-2 text-sm text-gray-400 transition-colors hover:bg-white/10 hover:text-gray-200">
-        <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 7h12m0 0l-4-4m4 4l-4 4m0 6H4m0 0l4 4m-4-4l4-4" />
-        </svg>
-        版本管理
-      </button>
-    </div>
-  </aside>
-</template>
diff --git a/packages/app/src/constants/category.ts b/packages/app/src/constants/category.ts
new file mode 100644
index 0000000..5d872a9
--- /dev/null
+++ b/packages/app/src/constants/category.ts
@@ -0,0 +1,15 @@
+/**
+ * Activity Bar 的分类类型。
+ *
+ * 对应左侧 Activity Bar 的 5 个图标，每个分类切换右侧 CategoryPanel 的内容。
+ * 注意：`settings` 是动作型入口（打开模态框），不会作为 CategoryPanel 的渲染分支，
+ * 仅在此保留以统一 Activity Bar 的图标语义。
+ */
+export type Category = 'conversation' | 'chapter' | 'element' | 'prompt'
+
+/**
+ * 设置是动作型入口，不切换 CategoryPanel，单独标识以便 ActivityBar 区分行为。
+ */
+export type SettingsAction = 'settings'
+
+export type ActivityItem = Category | SettingsAction
diff --git a/packages/app/src/constants/elements.ts b/packages/app/src/constants/elements.ts
new file mode 100644
index 0000000..99c7c22
--- /dev/null
+++ b/packages/app/src/constants/elements.ts
@@ -0,0 +1,31 @@
+import type { ElementType } from '@novai/core'
+
+/**
+ * 要素分组的 UI 常量定义。
+ *
+ * core 层只有 `ElementType` 类型和散落的目录映射（writer.ts 内私有常量），
+ * 没有集中维护「type ↔ 目录 ↔ 中文标题 ↔ 图标」的常量。
+ * 分类面板需要固定的中文标题展示，因此在 app 层统一维护这份映射，
+ * 不依赖磁盘目录名做中文翻译。
+ *
+ * 顺序固定，对应 UI 中 6 个可折叠分组的展示顺序。
+ */
+export interface ElementCategory {
+  /** core 的 ElementType，作为稳定 key */
+  key: ElementType
+  /** UI 展示的中文标题（写死） */
+  label: string
+  /** 对应的磁盘目录前缀，用于从 currentProject.files 过滤 */
+  directory: string
+  /** UI 展示的图标（emoji，后续可替换为 svg） */
+  icon: string
+}
+
+export const ELEMENT_CATEGORIES: ElementCategory[] = [
+  { key: 'character', label: '人物', directory: 'elements/characters', icon: '👤' },
+  { key: 'location', label: '地点', directory: 'elements/locations', icon: '📍' },
+  { key: 'entity', label: '其他实体', directory: 'elements/entities', icon: '🔶' },
+  { key: 'timeline', label: '时间线', directory: 'elements/timeline', icon: '📅' },
+  { key: 'plot', label: '情节', directory: 'elements/plots', icon: '📌' },
+  { key: 'worldbuilding', label: '设定', directory: 'elements/worldbuilding', icon: '🌐' },
+]
diff --git a/packages/app/src/stores/project.ts b/packages/app/src/stores/project.ts
index f56b7df..d9814c3 100644
--- a/packages/app/src/stores/project.ts
+++ b/packages/app/src/stores/project.ts
@@ -17,6 +17,7 @@ import {
   readFile,
   refreshFiles,
 } from '@novai/core/services/file-service'
+import { updateConfig } from '@novai/core/services/settings-service'
 import type {
   FileContentView,
   LastProjectSummaryView,
@@ -220,6 +221,34 @@ export const useProjectStore = defineStore('project', () => {
     }
   }
 
+  /**
+   * 切换当前激活的场景提示词。
+   *
+   * 这条 action 解决了一个已知坑点：直接调 settingsStore.saveConfig 只会更新 settingsStore
+   * 自己的 config 副本，不会同步到 projectStore.currentProject.config（后者是 setCurrentProject
+   * 那一刻生成的快照）。分类面板读取的是 projectStore 侧，因此这里在写盘成功后显式调
+   * updateCurrentProjectConfig 同步本地，避免 UI 显示过期数据。
+   *
+   * @param path 场景提示词路径，传 null 表示关闭场景
+   */
+  async function changeActiveScenePromptPath(projectId: string, path: string | null) {
+    errorMessage.value = ''
+
+    try {
+      const savedConfig = await updateConfig(projectId, {
+        settings: { activeScenePromptPath: path },
+      })
+      updateCurrentProjectConfig(savedConfig)
+      statusMessage.value = path
+        ? '已切换场景提示词，新建会话后生效'
+        : '已关闭场景提示词，新建会话后生效'
+      return savedConfig
+    } catch (error) {
+      errorMessage.value = toMessage(error, '切换场景提示词失败')
+      return null
+    }
+  }
+
   async function runProjectAction<T>(action: () => Promise<T>) {
     errorMessage.value = ''
     isBusy.value = true
@@ -244,6 +273,7 @@ export const useProjectStore = defineStore('project', () => {
     lastProjectSummary,
     recentProjects,
     statusMessage,
+    changeActiveScenePromptPath,
     closeCurrentProject,
     createNewProject,
     forgetLastOpenedProject,
diff --git a/packages/app/src/utils/file-tree.ts b/packages/app/src/utils/file-tree.ts
new file mode 100644
index 0000000..d8cd57e
--- /dev/null
+++ b/packages/app/src/utils/file-tree.ts
@@ -0,0 +1,76 @@
+import type { ProjectFileNodeView } from '@novai/core/services/types'
+
+/**
+ * 文件树工具函数。
+ *
+ * currentProject.files 是嵌套结构：顶层是项目根目录的直接条目（chapters/、elements/ 等
+ * 目录节点 + novel.config.json 文件），目录的子项在 node.children 里。
+ *
+ * 分类面板需要按业务前缀从这棵嵌套树里提取内容，这里集中维护提取逻辑。
+ */
+
+/**
+ * 在嵌套树里找到路径精确匹配 prefix 的目录节点，返回它的直接子节点（保持目录层级）。
+ *
+ * 用于章节页：取 chapters/ 目录的直接子项（可能含子目录「卷/部」+ 章节文件）。
+ * 用于提示词页：取 prompts/ 目录的直接子项（system.md + scenes/ 子目录）。
+ *
+ * @param files 全量嵌套树
+ * @param prefix 目录路径，如 'chapters' 或 'prompts'
+ * @returns 该目录的直接子节点数组；目录不存在时返回 []
+ */
+export function pickDirectoryChildren(
+  files: ProjectFileNodeView[],
+  prefix: string,
+): ProjectFileNodeView[] {
+  for (const node of files) {
+    if (node.kind === 'directory' && node.path === prefix) {
+      return node.children ?? []
+    }
+    // 递归往子目录里找（应对嵌套较深的场景）
+    if (node.kind === 'directory' && node.children?.length) {
+      const found = pickDirectoryChildren(node.children, prefix)
+      if (found.length > 0) {
+        return found
+      }
+    }
+  }
+  return []
+}
+
+/**
+ * 递归收集某目录前缀下的所有文件节点（拍平，不含目录）。
+ *
+ * 用于要素页：取 elements/characters/ 等目录下的所有 .md 文件，
+ * 无论嵌套多深都收集为扁平列表。
+ *
+ * 注意：必须**无条件递归遍历所有目录**，因为目标目录的祖先（如 elements/）
+ * 自身路径不以 'elements/characters/' 开头，但它的 children 里藏着目标文件。
+ * 只在收集 file 节点时做前缀判断即可。
+ *
+ * @param files 全量嵌套树
+ * @param prefix 目录路径前缀，如 'elements/characters'
+ * @returns 该前缀下所有 file 节点（已扁平化）；目录不存在或为空时返回 []
+ */
+export function collectFilesByPrefix(
+  files: ProjectFileNodeView[],
+  prefix: string,
+): ProjectFileNodeView[] {
+  const result: ProjectFileNodeView[] = []
+  const visit = (nodes: ProjectFileNodeView[]) => {
+    for (const node of nodes) {
+      // file 节点：路径前缀匹配则收集
+      if (node.kind === 'file' && node.path.startsWith(`${prefix}/`)) {
+        result.push(node)
+        continue
+      }
+      // directory 节点：无条件递归进 children（祖先目录的 path 不匹配前缀，
+      // 但目标文件可能藏在更深层）
+      if (node.kind === 'directory' && node.children?.length) {
+        visit(node.children)
+      }
+    }
+  }
+  visit(files)
+  return result
+}
diff --git a/packages/app/src/views/ProjectView.vue b/packages/app/src/views/ProjectView.vue
index 75c8a30..bddeffa 100644
--- a/packages/app/src/views/ProjectView.vue
+++ b/packages/app/src/views/ProjectView.vue
@@ -4,11 +4,13 @@ import { useRoute, useRouter } from 'vue-router'
 import { useProjectStore } from '../stores/project'
 import { useChatStore } from '../stores/chat'
 import { useToast } from '../composables/useToast'
-import FileTreeSidebar from '../components/layout/FileTreeSidebar.vue'
+import ActivityBar from '../components/layout/ActivityBar.vue'
+import CategoryPanel from '../components/layout/CategoryPanel.vue'
 import ChatPanel from '../components/layout/ChatPanel.vue'
 import ContentPanel from '../components/layout/ContentPanel.vue'
 import Toast from '../components/ui/Toast.vue'
 import FirstTimeGuide from '../components/ui/FirstTimeGuide.vue'
+import type { Category } from '../constants/category'
 
 const route = useRoute()
 const router = useRouter()
@@ -17,11 +19,17 @@ const chatStore = useChatStore()
 const toast = useToast()
 
 const projectId = computed(() => route.params.id as string)
-const isSidebarOpen = ref(true)
+const activeCategory = ref<Category>('chapter')
+const isCategoryOpen = ref(true)
+const isMobileCategoryOpen = ref(false)
 const isContentPanelOpen = ref(false)
-const isMobileSidebarOpen = ref(false)
 const showGuide = ref(false)
 
+/** 从 currentProject 取配置里的激活场景路径（分类面板需读取它做高亮联动） */
+const activeScenePromptPath = computed(() => {
+  return projectStore.currentProject?.config.settings.activeScenePromptPath ?? null
+})
+
 onMounted(async () => {
   // 如果没有当前项目，尝试恢复
   if (!projectStore.currentProject) {
@@ -46,13 +54,13 @@ onMounted(async () => {
   }
 })
 
-// 监听文件变更，自动刷新文件树
+// 监听文件变更，自动刷新分类面板数据
 watch(
   () => chatStore.changedFiles.length,
   async (newLength, oldLength) => {
     if (newLength > oldLength && projectStore.currentProject) {
       await projectStore.refreshTree()
-      toast.success('文件树已更新')
+      toast.success('文件列表已更新')
     }
   },
 )
@@ -74,8 +82,20 @@ function handleBackToHome() {
   router.push('/')
 }
 
+/**
+ * 打开设置。
+ * R1 阶段设置模态框尚未实现（R2 的工作），这里先给提示，保留入口。
+ */
 function handleOpenSettings() {
-  router.push(`/project/${projectId.value}/settings`)
+  toast.info('设置入口将在下一阶段改为弹窗')
+}
+
+/**
+ * 功能占位项统一反馈。
+ * 校对、章节整理、版本管理暂未实现，保留入口但提示「即将推出」。
+ */
+function handleNotImplemented(name: string) {
+  toast.info(`${name}功能即将推出`)
 }
 
 async function handleSelectFile(path: string) {
@@ -83,13 +103,23 @@ async function handleSelectFile(path: string) {
   isContentPanelOpen.value = true
 }
 
-async function handleRefreshTree() {
-  await projectStore.refreshTree()
-  toast.success('文件树已刷新')
+async function handleChangeScene(path: string | null) {
+  const saved = await projectStore.changeActiveScenePromptPath(projectId.value, path)
+  if (saved) {
+    toast.info(path ? '已切换场景提示词，新建会话后生效' : '已关闭场景提示词，新建会话后生效')
+  } else {
+    toast.error(projectStore.errorMessage || '切换场景提示词失败')
+  }
+}
+
+function selectCategory(category: Category) {
+  activeCategory.value = category
+  // 切换分类时确保面板展开
+  isCategoryOpen.value = true
 }
 
 function toggleSidebar() {
-  isSidebarOpen.value = !isSidebarOpen.value
+  isCategoryOpen.value = !isCategoryOpen.value
 }
 
 function toggleContentPanel() {
@@ -97,7 +127,7 @@ function toggleContentPanel() {
 }
 
 function toggleMobileSidebar() {
-  isMobileSidebarOpen.value = !isMobileSidebarOpen.value
+  isMobileCategoryOpen.value = !isMobileCategoryOpen.value
 }
 
 function handleCloseGuide() {
@@ -117,30 +147,41 @@ async function handleElementsWritten() {
 
 <template>
   <div class="flex h-screen bg-white">
-    <!-- 移动端侧边栏遮罩 -->
+    <!-- 移动端分类面板遮罩 -->
     <div
-      v-if="isMobileSidebarOpen"
+      v-if="isMobileCategoryOpen"
       class="fixed inset-0 z-40 bg-black/50 lg:hidden"
-      @click="isMobileSidebarOpen = false"
+      @click="isMobileCategoryOpen = false"
     />
 
-    <!-- 左侧文件树 -->
-    <FileTreeSidebar
-      :is-open="isSidebarOpen"
-      :is-mobile-open="isMobileSidebarOpen"
-      :project="projectStore.currentProject"
-      :active-file-path="projectStore.activeFile?.path"
-      @back-to-home="handleBackToHome"
+    <!-- Activity Bar（最左竖条） -->
+    <ActivityBar
+      :active-category="activeCategory"
+      @select="selectCategory"
       @open-settings="handleOpenSettings"
-      @close-mobile="isMobileSidebarOpen = false"
+      @back-to-home="handleBackToHome"
+      @proofread="handleNotImplemented('校对')"
+      @organize="handleNotImplemented('章节整理')"
+      @version="handleNotImplemented('版本管理')"
+    />
+
+    <!-- 分类面板（随 Activity Bar 切换） -->
+    <CategoryPanel
+      :active-category="activeCategory"
+      :files="projectStore.currentProject?.files ?? []"
+      :active-file-path="projectStore.activeFile?.path"
+      :active-scene-prompt-path="activeScenePromptPath"
+      :is-open="isCategoryOpen"
+      :is-mobile-open="isMobileCategoryOpen"
       @select-file="handleSelectFile"
-      @refresh-tree="handleRefreshTree"
+      @change-scene="handleChangeScene"
+      @close-mobile="isMobileCategoryOpen = false"
     />
 
     <!-- 中间对话面板 -->
     <ChatPanel
       :project-id="projectId"
-      :is-sidebar-open="isSidebarOpen"
+      :is-sidebar-open="isCategoryOpen"
       :is-content-panel-open="isContentPanelOpen"
       @toggle-sidebar="toggleSidebar"
       @toggle-content-panel="toggleContentPanel"

From 8feb3a44b690f0d16d0e7170837d9956086baf3f Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Wed, 17 Jun 2026 22:49:17 +0800
Subject: [PATCH 03/36] =?UTF-8?q?feat(project):=20Agent=20=E6=94=AF?=
 =?UTF-8?q?=E6=8C=81=E8=BF=90=E8=A1=8C=E4=B8=AD=E5=81=9C=E6=AD=A2=E5=B9=B6?=
 =?UTF-8?q?=E5=8D=B3=E6=97=B6=E5=8F=8D=E9=A6=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- core/llm: 流式请求接入 AbortSignal，停止时抛 AgentAbortedError 保留已生成内容，且不触发非流式 fallback
- core/query: Agent Loop 每轮检查停止信号，工具批次执行前跳过剩余工具
- core/session: 停止作为正常结束，追加已停止摘要，状态回 waiting-user
- app/chat-store: 持有 AbortController，新增 isRunning/isStopping 与 abortRun
- app/chat-panel: 发送按钮运行中切换为停止，停止中显示禁用 spinner 与提示文本
---
 .../app/src/components/layout/ChatPanel.vue   |  50 +++++---
 packages/app/src/stores/chat.ts               |  30 +++++
 packages/core/src/core/agent/llm.test.ts      |  86 +++++++++++++-
 packages/core/src/core/agent/llm.ts           |  79 ++++++++++--
 packages/core/src/core/agent/query.ts         |  54 +++++++--
 .../src/core/agent/tool-orchestration.test.ts | 112 ++++++++++++++++++
 .../core/src/core/agent/tool-orchestration.ts |  26 ++++
 packages/core/src/core/chat/session.ts        |  39 ++++++
 packages/core/src/services/agent-service.ts   |   1 +
 packages/core/src/services/types.ts           |   2 +
 packages/core/src/types/chat.ts               |   2 +
 11 files changed, 441 insertions(+), 40 deletions(-)
 create mode 100644 packages/core/src/core/agent/tool-orchestration.test.ts

diff --git a/packages/app/src/components/layout/ChatPanel.vue b/packages/app/src/components/layout/ChatPanel.vue
index e3841e9..3938c34 100644
--- a/packages/app/src/components/layout/ChatPanel.vue
+++ b/packages/app/src/components/layout/ChatPanel.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { nextTick, ref, watch } from 'vue'
+import { computed, nextTick, ref, watch } from 'vue'
 import { useChatStore } from '../../stores/chat'
 import { shouldSubmitOnEnter } from '../../composables/keyboard'
 import MessageItem from '../chat/MessageItem.vue'
@@ -20,7 +20,11 @@ const chatStore = useChatStore()
 const inputText = ref('')
 const messagesContainer = ref<HTMLDivElement | null>(null)
 const textareaRef = ref<HTMLTextAreaElement | null>(null)
-const isSending = ref(false)
+
+// 是否正在运行，直接读 store，避免本地状态与 store 不同步
+const isSending = computed(() => chatStore.isRunning)
+// 用户已请求停止、正在等待当前工具完成
+const isStopping = computed(() => chatStore.isStopping)
 
 // 自动滚动到底部
 async function scrollToBottom() {
@@ -43,7 +47,6 @@ async function handleSend() {
 
   const message = inputText.value.trim()
   inputText.value = ''
-  isSending.value = true
 
   // 重置 textarea 高度
   if (textareaRef.value) {
@@ -52,11 +55,15 @@ async function handleSend() {
 
   try {
     await chatStore.sendMessage(message)
-  } finally {
-    isSending.value = false
+  } catch {
+    // 错误已在 store 中写入 runStatus，这里静默处理
   }
 }
 
+function handleStop() {
+  chatStore.abortRun()
+}
+
 function handleKeydown(event: KeyboardEvent) {
   // Enter 发送，Shift+Enter 换行
   if (shouldSubmitOnEnter(event)) {
@@ -159,26 +166,37 @@ function autoResize(event: Event) {
             class="flex-1 resize-none rounded-lg border border-gray-300 px-4 py-2.5 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
             placeholder="输入创作指令... (Enter 发送，Shift+Enter 换行)"
             rows="1"
-            :disabled="isSending"
             @keydown="handleKeydown"
             @input="autoResize"
           />
           <button
-            class="self-end rounded-lg bg-gray-900 px-4 py-2.5 text-sm font-medium text-white transition-colors hover:bg-gray-800 disabled:opacity-50"
-            :disabled="!inputText.trim() || isSending"
-            @click="handleSend"
+            v-if="isStopping"
+            class="self-end rounded-lg border border-gray-200 bg-gray-100 px-4 py-2.5 text-sm font-medium text-gray-400"
+            title="正在停止…"
+            disabled
           >
-            <svg
-              v-if="isSending"
-              class="h-5 w-5 animate-spin"
-              fill="none"
-              viewBox="0 0 24 24"
-            >
+            <svg class="h-5 w-5 animate-spin" fill="none" viewBox="0 0 24 24">
               <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" />
               <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
             </svg>
+          </button>
+          <button
+            v-else-if="isSending"
+            class="self-end rounded-lg border border-gray-300 bg-white px-4 py-2.5 text-sm font-medium text-gray-700 transition-colors hover:bg-gray-100"
+            title="停止运行"
+            @click="handleStop"
+          >
+            <svg class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <rect x="6" y="6" width="12" height="12" rx="1.5" fill="currentColor" stroke="none" />
+            </svg>
+          </button>
+          <button
+            v-else
+            class="self-end rounded-lg bg-gray-900 px-4 py-2.5 text-sm font-medium text-white transition-colors hover:bg-gray-800 disabled:opacity-50"
+            :disabled="!inputText.trim()"
+            @click="handleSend"
+          >
             <svg
-              v-else
               class="h-5 w-5"
               fill="none"
               stroke="currentColor"
diff --git a/packages/app/src/stores/chat.ts b/packages/app/src/stores/chat.ts
index 70fb58f..59ee8fd 100644
--- a/packages/app/src/stores/chat.ts
+++ b/packages/app/src/stores/chat.ts
@@ -20,6 +20,12 @@ export const useChatStore = defineStore('chat', () => {
   const agentEvents = ref<AgentUiEvent[]>([])
   const changedFiles = ref<ChangedFileView[]>([])
   const runStatus = ref('还没有开始执行。')
+  const isRunning = ref(false)
+  // 用户已请求停止、正在等待当前工具执行完成
+  const isStopping = ref(false)
+
+  // 当前运行持有的停止控制器；仅 isRunning 期间存在
+  let activeAbortController: AbortController | null = null
 
   const hasSessionView = computed(() => sessionView.value !== null)
   const messages = computed<ChatMessageView[]>(() => sessionView.value?.messages ?? [])
@@ -42,11 +48,17 @@ export const useChatStore = defineStore('chat', () => {
     agentEvents.value = []
     changedFiles.value = []
     runStatus.value = '正在执行本轮 Agent...'
+    isRunning.value = true
+    isStopping.value = false
+
+    // 每轮新建 controller，signal 透传到 core Agent Loop
+    activeAbortController = new AbortController()
 
     try {
       const result = await runAgentTurn({
         ...input,
         sessionId: currentSession.sessionId,
+        signal: activeAbortController.signal,
         onEvent(event) {
           handleAgentEvent(event)
           input.onEvent?.(event)
@@ -63,6 +75,21 @@ export const useChatStore = defineStore('chat', () => {
     } catch (error) {
       runStatus.value = error instanceof Error ? error.message : '执行会话失败'
       throw error
+    } finally {
+      isRunning.value = false
+      isStopping.value = false
+      activeAbortController = null
+    }
+  }
+
+  /** 用户点击停止：中断当前模型流式请求，Agent Loop 会在边界优雅结束。 */
+  function abortRun() {
+    if (activeAbortController) {
+      activeAbortController.abort()
+      activeAbortController = null
+      // 立即进入「停止中」态：UI 反馈 + 等待当前工具完成
+      isStopping.value = true
+      runStatus.value = '已请求停止，等待当前工具执行完成…'
     }
   }
 
@@ -123,10 +150,13 @@ export const useChatStore = defineStore('chat', () => {
   return {
     agentEvents,
     changedFiles,
+    isRunning,
+    isStopping,
     messages,
     sessionView,
     runStatus,
     hasSessionView,
+    abortRun,
     createSession,
     ensureSessionView,
     sendMessage,
diff --git a/packages/core/src/core/agent/llm.test.ts b/packages/core/src/core/agent/llm.test.ts
index 7f6cf77..0902703 100644
--- a/packages/core/src/core/agent/llm.test.ts
+++ b/packages/core/src/core/agent/llm.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
-import { streamAgentCompletion } from './llm'
+import { streamAgentCompletion, AgentAbortedError } from './llm'
 import type { AgentToolSchema } from './messages'
 
 const originalFetch = globalThis.fetch
@@ -186,6 +186,90 @@ describe('streamAgentCompletion', () => {
       message: expect.stringContaining('模型非流式 fallback超过 300 秒未完成'),
     }))
   })
+
+  it('aborts immediately and does not fall back to non-streaming when the user signal aborts', async () => {
+    const userController = new AbortController()
+    const encoder = new TextEncoder()
+    const fetchMock = vi.fn().mockImplementation((_url: string, init: RequestInit) => {
+      // fetch 的 signal 既是超时也是用户 abort 的载体；这里让它与用户 controller 联动
+      init.signal?.addEventListener('abort', () => {
+        if (!userController.signal.aborted) userController.abort()
+      })
+
+      let firstChunkSent = false
+      return Promise.resolve(new Response(new ReadableStream<Uint8Array>({
+        // poll 循环：第一个 chunk 吐出后，后续每次 pull 都检查用户是否已 abort
+        async pull(controller) {
+          if (!firstChunkSent) {
+            firstChunkSent = true
+            controller.enqueue(encoder.encode('data: {"choices":[{"delta":{"content":"前面这段"}}]}\n\n'))
+            return
+          }
+
+          // 等待用户 abort（最多等一小段，避免空转）
+          if (userController.signal.aborted) {
+            controller.error(new DOMException('Aborted', 'AbortError'))
+            return
+          }
+
+          await new Promise((resolve) => setTimeout(resolve, 5))
+          if (userController.signal.aborted) {
+            controller.error(new DOMException('Aborted', 'AbortError'))
+          }
+        },
+      }), {
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' },
+      }))
+    })
+
+    globalThis.fetch = fetchMock
+
+    // 启动后稍等让第一个 chunk 被消费，再触发用户停止
+    const promise = streamAgentCompletion({
+      baseUrl: 'https://api.siliconflow.cn/v1',
+      apiKey: 'test-key',
+      model: 'deepseek-ai/DeepSeek-V4-Pro',
+      messages: [{ role: 'user', content: '写第一章' }],
+      tools: [listDirectoryToolSchema],
+      signal: userController.signal,
+    }, () => {})
+
+    // 让第一个 delta 被消费
+    await new Promise((resolve) => setTimeout(resolve, 20))
+    userController.abort()
+
+    const error = await promise.catch((e: unknown) => e)
+
+    // 关键：fetch 只调用一次（没有 fallback 到非流式重试）
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(error).toBeInstanceOf(AgentAbortedError)
+    expect((error as AgentAbortedError).partialContent).toBe('前面这段')
+  })
+
+  it('throws AgentAbortedError immediately if the signal is already aborted before the request', async () => {
+    const userController = new AbortController()
+    userController.abort()
+    const fetchMock = vi.fn()
+
+    globalThis.fetch = fetchMock
+
+    const promise = streamAgentCompletion({
+      baseUrl: 'https://api.siliconflow.cn/v1',
+      apiKey: 'test-key',
+      model: 'deepseek-ai/DeepSeek-V4-Pro',
+      messages: [
+        { role: 'user', content: '写第一章' },
+      ],
+      tools: [listDirectoryToolSchema],
+      signal: userController.signal,
+    }, () => {})
+    const error = await promise.catch((e: unknown) => e)
+
+    // 请求开始前已停止：根本不会发起任何 fetch
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(error).toBeInstanceOf(AgentAbortedError)
+  })
 })
 
 function createStreamingResponse(payloads: unknown[]) {
diff --git a/packages/core/src/core/agent/llm.ts b/packages/core/src/core/agent/llm.ts
index 62fc063..3d8773e 100644
--- a/packages/core/src/core/agent/llm.ts
+++ b/packages/core/src/core/agent/llm.ts
@@ -14,6 +14,8 @@ export type AgentLlmInput = {
   model: string
   messages: AgentMessage[]
   tools: AgentToolSchema[]
+  /** 外部停止信号（用户点击停止）。一旦 abort，立即中断流式，且不触发非流式 fallback。 */
+  signal?: AbortSignal
 }
 
 export type AgentLlmEvent =
@@ -22,6 +24,18 @@ export type AgentLlmEvent =
   | { type: 'finish'; response: AgentAssistantResponse }
   | { type: 'error'; message: string }
 
+/** 用户主动停止运行时抛出的错误，用于区分超时与 fallback。 */
+export class AgentAbortedError extends Error {
+  readonly aborted = true
+  readonly partialContent: string
+
+  constructor(partialContent: string) {
+    super('Agent 已被用户停止')
+    this.name = 'AgentAbortedError'
+    this.partialContent = partialContent
+  }
+}
+
 type PendingToolCall = {
   id?: string
   name?: string
@@ -48,6 +62,11 @@ export async function streamAgentCompletion(
     throw new Error(message)
   }
 
+  // 用户在请求开始前就已经点了停止 —— 直接中止
+  if (input.signal?.aborted) {
+    throw new AgentAbortedError('')
+  }
+
   onEvent({ type: 'start' })
 
   const timeout = createRequestTimeout(LLM_STREAM_IDLE_TIMEOUT_MS, '流式响应空闲')
@@ -81,7 +100,7 @@ export async function streamAgentCompletion(
     const reader = response.body.getReader()
 
     while (true) {
-      const { done, value } = await readStreamChunk(reader, timeout.signal)
+      const { done, value } = await readStreamChunk(reader, timeout.signal, input.signal)
 
       if (done) {
         break
@@ -136,6 +155,11 @@ export async function streamAgentCompletion(
       }
     }
   } catch (error) {
+    // 用户主动停止 —— 立即中断，保留已生成内容，不触发非流式 fallback
+    if (isUserAbort(error, input.signal)) {
+      throw new AgentAbortedError(content)
+    }
+
     const fallback = await fallbackToNonStreaming(
       input,
       baseUrl,
@@ -304,20 +328,33 @@ async function fallbackToNonStreaming(
 
 async function readStreamChunk(
   reader: ReadableStreamDefaultReader<Uint8Array>,
-  signal: AbortSignal,
+  timeoutSignal: AbortSignal,
+  userSignal?: AbortSignal,
 ) {
-  if (signal.aborted) {
-    throw signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason))
+  if (timeoutSignal.aborted) {
+    throw timeoutSignal.reason instanceof Error ? timeoutSignal.reason : new Error(String(timeoutSignal.reason))
+  }
+
+  if (userSignal?.aborted) {
+    throw userSignal.reason instanceof Error ? userSignal.reason : new Error(String(userSignal.reason))
   }
 
-  return Promise.race([
+  const settle = (resolve: (value: ReadableStreamReadResult<Uint8Array>) => void, reject: (error: unknown) => void, signal: AbortSignal) => {
+    signal.addEventListener('abort', () => {
+      reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
+    }, { once: true })
+  }
+
+  const competitors: Promise<ReadableStreamReadResult<Uint8Array>>[] = [
     reader.read(),
-    new Promise<ReadableStreamReadResult<Uint8Array>>((_, reject) => {
-      signal.addEventListener('abort', () => {
-        reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)))
-      }, { once: true })
-    }),
-  ])
+    new Promise((_, reject) => settle(undefined as never, reject, timeoutSignal)),
+  ]
+
+  if (userSignal) {
+    competitors.push(new Promise((_, reject) => settle(undefined as never, reject, userSignal)))
+  }
+
+  return Promise.race(competitors)
 }
 
 function createRequestTimeout(timeoutMs: number, label: string) {
@@ -367,6 +404,26 @@ function isAbortError(error: unknown) {
   )
 }
 
+/**
+ * 判定一个错误是否由用户主动停止触发。
+ * 三种来源：外部 signal 已 abort、错误本身是 AgentAbortedError、DOMException AbortError 且 signal 已 abort。
+ */
+function isUserAbort(error: unknown, signal?: AbortSignal): boolean {
+  if (error instanceof AgentAbortedError) {
+    return true
+  }
+
+  if (!signal?.aborted) {
+    return false
+  }
+
+  if (error instanceof DOMException && error.name === 'AbortError') {
+    return true
+  }
+
+  return false
+}
+
 function toOpenAiMessage(message: AgentMessage) {
   if (message.role === 'tool') {
     return {
diff --git a/packages/core/src/core/agent/query.ts b/packages/core/src/core/agent/query.ts
index c6df2f7..d5c39f8 100644
--- a/packages/core/src/core/agent/query.ts
+++ b/packages/core/src/core/agent/query.ts
@@ -1,4 +1,4 @@
-import { streamAgentCompletion } from './llm'
+import { streamAgentCompletion, AgentAbortedError } from './llm'
 import { runAgentTools } from './tool-orchestration'
 import type { ToolExecutionEvent } from './tool-execution'
 import type { ProjectConfig, ProjectSnapshot } from '../../types/project'
@@ -19,9 +19,10 @@ export type AgentQueryEvent =
   | { type: 'model-tool-call-parse-warning'; step: number; finishReason?: string; diagnostics?: AgentLlmDiagnostics }
   | { type: 'tool-batch-start'; step: number; toolCallCount: number }
   | { type: 'tool-batch-finish'; step: number; toolResultCount: number }
+  | { type: 'aborted'; reason: 'user'; partialContent?: string }
   | { type: 'assistant-message'; message: AgentAssistantMessage }
   | ToolExecutionEvent
-  | { type: 'done'; messages: AgentMessage[] }
+  | { type: 'done'; messages: AgentMessage[]; aborted?: boolean }
 
 export async function query(input: {
   config: ProjectConfig
@@ -29,6 +30,7 @@ export async function query(input: {
   messages: AgentMessage[]
   tools: AgentRunnableToolMap
   maxTurns?: number
+  signal?: AbortSignal
   onEvent?: (event: AgentQueryEvent) => void
 }): Promise<AgentMessage[]> {
   let messages = [...input.messages]
@@ -39,6 +41,13 @@ export async function query(input: {
   for (let turn = 0; turn < maxTurns; turn += 1) {
     const step = turn + 1
 
+    // 每一轮开始前检查用户是否已停止（工具执行完毕后停止的边界）
+    if (input.signal?.aborted) {
+      input.onEvent?.({ type: 'aborted', reason: 'user' })
+      input.onEvent?.({ type: 'done', messages, aborted: true })
+      return messages
+    }
+
     input.onEvent?.({ type: 'query-step-start', step })
     input.onEvent?.({
       type: 'model-start',
@@ -52,16 +61,36 @@ export async function query(input: {
         : undefined,
     })
 
-    const assistantResponse = await streamAgentCompletion(
-      {
-        baseUrl: input.config.llm.baseUrl,
-        apiKey: input.config.llm.apiKey,
-        model: input.config.llm.model,
-        messages,
-        tools: Object.values(input.tools).map((tool) => tool.schema),
-      },
-      () => {},
-    )
+    let assistantResponse
+    try {
+      assistantResponse = await streamAgentCompletion(
+        {
+          baseUrl: input.config.llm.baseUrl,
+          apiKey: input.config.llm.apiKey,
+          model: input.config.llm.model,
+          messages,
+          tools: Object.values(input.tools).map((tool) => tool.schema),
+          signal: input.signal,
+        },
+        () => {},
+      )
+    } catch (error) {
+      // 用户主动停止 —— 保留已生成的内容作为 assistant 消息，优雅结束
+      if (error instanceof AgentAbortedError) {
+        if (error.partialContent.trim()) {
+          const partialMessage: AgentAssistantMessage = {
+            role: 'assistant',
+            content: error.partialContent,
+          }
+          messages = [...messages, partialMessage]
+          input.onEvent?.({ type: 'assistant-message', message: partialMessage })
+        }
+        input.onEvent?.({ type: 'aborted', reason: 'user', partialContent: error.partialContent })
+        input.onEvent?.({ type: 'done', messages, aborted: true })
+        return messages
+      }
+      throw error
+    }
 
     input.onEvent?.({
       type: 'model-finish',
@@ -105,6 +134,7 @@ export async function query(input: {
       project: input.project,
       tools: input.tools,
       readFileStates,
+      signal: input.signal,
       onEvent: input.onEvent,
     })
 
diff --git a/packages/core/src/core/agent/tool-orchestration.test.ts b/packages/core/src/core/agent/tool-orchestration.test.ts
new file mode 100644
index 0000000..79f319a
--- /dev/null
+++ b/packages/core/src/core/agent/tool-orchestration.test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { runAgentTools } from './tool-orchestration'
+import type { AgentRunnableTool, AgentRunnableToolMap } from './tools'
+import type { AgentToolCall } from './messages'
+import type { ProjectSnapshot } from '../../types/project'
+
+const stubProject = { handle: {} } as unknown as ProjectSnapshot
+
+function createStubTool(name: string): AgentRunnableTool {
+  return {
+    name: name as AgentRunnableTool['name'],
+    isReadOnly: true,
+    isConcurrencySafe: true,
+    schema: {
+      type: 'function',
+      function: { name, description: '', parameters: { type: 'object', properties: {} } },
+    },
+    core: {
+      name: name as AgentRunnableTool['name'],
+      validateInput: (input: unknown) => input,
+      // 故意做成异步，模拟工具执行耗时
+      run: vi.fn().mockResolvedValue({ ok: true }),
+      summarizeInput: () => `调用 ${name}`,
+      summarizeOutput: () => `${name} 执行完成`,
+    },
+    formatResult: () => `${name} 结果`,
+  }
+}
+
+function createCall(name: string, index: number): AgentToolCall {
+  return {
+    id: `call_${index}`,
+    name: name as AgentToolCall['name'],
+    input: {},
+  }
+}
+
+describe('runAgentTools', () => {
+  it('executes all calls in order when the signal is not aborted', async () => {
+    const toolA = createStubTool('ReadFile')
+    const toolB = createStubTool('ListDirectory')
+    const tools = { ReadFile: toolA, ListDirectory: toolB } as unknown as AgentRunnableToolMap
+
+    const results = await runAgentTools({
+      calls: [createCall('ReadFile', 1), createCall('ListDirectory', 2)],
+      project: stubProject,
+      tools,
+    })
+
+    expect(results).toHaveLength(2)
+    expect(toolA.core.run).toHaveBeenCalledTimes(1)
+    expect(toolB.core.run).toHaveBeenCalledTimes(1)
+  })
+
+  it('skips remaining tools in a batch once the user signal aborts', async () => {
+    const controller = new AbortController()
+    const toolA = createStubTool('ReadFile')
+    // 第一个工具执行完后触发停止
+    toolA.core.run = vi.fn().mockImplementation(async () => {
+      controller.abort()
+      return { ok: true }
+    })
+    const toolB = createStubTool('ListDirectory')
+    const toolC = createStubTool('FindFiles')
+    const tools = {
+      ReadFile: toolA,
+      ListDirectory: toolB,
+      FindFiles: toolC,
+    } as unknown as AgentRunnableToolMap
+
+    const results = await runAgentTools({
+      calls: [
+        createCall('ReadFile', 1),
+        createCall('ListDirectory', 2),
+        createCall('FindFiles', 3),
+      ],
+      project: stubProject,
+      tools,
+      signal: controller.signal,
+    })
+
+    // 第一个工具已执行；后两个被跳过，但仍补了 tool result 保证消息序列合法
+    expect(results).toHaveLength(3)
+    expect(toolA.core.run).toHaveBeenCalledTimes(1)
+    expect(toolB.core.run).not.toHaveBeenCalled()
+    expect(toolC.core.run).not.toHaveBeenCalled()
+
+    // 被跳过的工具 result 内容表明已被跳过
+    expect(results[1].content).toContain('跳过')
+    expect(results[2].content).toContain('跳过')
+    // toolCallId 仍对应原调用，保证对模型合法
+    expect(results[1].toolCallId).toBe('call_2')
+    expect(results[2].toolCallId).toBe('call_3')
+  })
+
+  it('does not skip when no signal is provided', async () => {
+    const toolA = createStubTool('ReadFile')
+    const toolB = createStubTool('ListDirectory')
+    const tools = { ReadFile: toolA, ListDirectory: toolB } as unknown as AgentRunnableToolMap
+
+    const results = await runAgentTools({
+      calls: [createCall('ReadFile', 1), createCall('ListDirectory', 2)],
+      project: stubProject,
+      tools,
+    })
+
+    expect(results).toHaveLength(2)
+    expect(toolA.core.run).toHaveBeenCalledTimes(1)
+    expect(toolB.core.run).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/packages/core/src/core/agent/tool-orchestration.ts b/packages/core/src/core/agent/tool-orchestration.ts
index 4db99f1..5f445ad 100644
--- a/packages/core/src/core/agent/tool-orchestration.ts
+++ b/packages/core/src/core/agent/tool-orchestration.ts
@@ -10,11 +10,37 @@ export async function runAgentTools(input: {
   project: ProjectSnapshot
   tools: AgentRunnableToolMap
   readFileStates?: Map<string, ReadFileState>
+  /** 用户停止信号：已停止时，批次内尚未开始执行的工具会被跳过。 */
+  signal?: AbortSignal
   onEvent?: (event: ToolExecutionEvent) => void
 }): Promise<AgentToolResultMessage[]> {
   const results: AgentToolResultMessage[] = []
 
   for (const call of input.calls) {
+    // 每个工具开始前检查：用户已停止时跳过剩余工具。
+    // 仍为被跳过的工具补一条 tool result，保证消息序列对模型合法。
+    if (input.signal?.aborted) {
+      const skipSummary = '已因用户停止而跳过该工具'
+      input.onEvent?.({
+        type: 'tool-call',
+        call,
+        inputSummary: `跳过 ${call.name}（用户已停止）`,
+      })
+      input.onEvent?.({
+        type: 'tool-result',
+        call,
+        ok: false,
+        resultSummary: skipSummary,
+      })
+      results.push({
+        role: 'tool',
+        toolCallId: call.id,
+        name: call.name,
+        content: skipSummary,
+      })
+      continue
+    }
+
     results.push(await executeAgentTool({
       call,
       project: input.project,
diff --git a/packages/core/src/core/chat/session.ts b/packages/core/src/core/chat/session.ts
index 02769dc..0b323ab 100644
--- a/packages/core/src/core/chat/session.ts
+++ b/packages/core/src/core/chat/session.ts
@@ -104,6 +104,7 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
   })
   const tools = createAgentTools()
   const enableDebugLogging = Boolean(input.config.settings.enableDebugLogging)
+  let aborted = false
 
   if (enableDebugLogging) {
     void writeAgentLog(input.project, {
@@ -125,6 +126,7 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
       project: input.project,
       messages: agentMessages,
       tools,
+      signal: input.signal,
       onEvent(event) {
         logAgentQueryEvent({
           project: input.project,
@@ -133,6 +135,18 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
           event,
         })
 
+        if (event.type === 'aborted') {
+          aborted = true
+          void writeAgentLog(input.project, {
+            sessionId: session.sessionId,
+            runId,
+            level: 'info',
+            event: 'agent_run_aborted',
+            message: 'Agent 被用户停止',
+          })
+          return
+        }
+
         if (event.type === 'assistant-message') {
           if (event.message.content.trim()) {
             pushMessage(session, createAssistantText(event.message.content.trim()), onEvent)
@@ -203,6 +217,31 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
     throw error
   }
 
+  if (aborted) {
+    pushMessage(
+      session,
+      {
+        id: createId('message'),
+        role: 'assistant',
+        kind: 'action-summary',
+        summary: session.lastWrittenPath
+          ? `本轮 Agent 已被停止，停止前已写回 ${session.lastWrittenPath}`
+          : '本轮 Agent 已被用户停止。',
+        targetPath: session.lastWrittenPath,
+        createdAt: new Date().toISOString(),
+      },
+      onEvent,
+    )
+
+    session.status = 'waiting-user'
+
+    return {
+      session,
+      target,
+      writtenPath: session.lastWrittenPath,
+    }
+  }
+
   pushMessage(
     session,
     {
diff --git a/packages/core/src/services/agent-service.ts b/packages/core/src/services/agent-service.ts
index bbaf9fb..ab65245 100644
--- a/packages/core/src/services/agent-service.ts
+++ b/packages/core/src/services/agent-service.ts
@@ -73,6 +73,7 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
         systemPrompt,
         scenePrompt,
         activeFilePath: input.activeFilePath,
+        signal: input.signal,
       },
       onEvent(event) {
         emitMessageEvent(event.message, input.onEvent)
diff --git a/packages/core/src/services/types.ts b/packages/core/src/services/types.ts
index 731aafb..8a9d72d 100644
--- a/packages/core/src/services/types.ts
+++ b/packages/core/src/services/types.ts
@@ -318,6 +318,8 @@ export type RunAgentTurnInput = {
   sessionId?: string
   instruction: string
   activeFilePath?: string
+  /** 用户停止信号，透传到 Agent Loop。 */
+  signal?: AbortSignal
   onEvent?: (event: AgentUiEvent) => void
 }
 
diff --git a/packages/core/src/types/chat.ts b/packages/core/src/types/chat.ts
index 6122430..9811d9f 100644
--- a/packages/core/src/types/chat.ts
+++ b/packages/core/src/types/chat.ts
@@ -146,6 +146,8 @@ export type ChatTurnInput = {
   systemPrompt: string
   scenePrompt?: string
   activeFilePath?: string | null
+  /** 用户停止信号，透传到 Agent Loop。 */
+  signal?: AbortSignal
 }
 
 export type ChatTurnResult = {

From 39a08990d46091ff3e5ba8d82b85345649202df4 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Wed, 17 Jun 2026 23:10:38 +0800
Subject: [PATCH 04/36] =?UTF-8?q?refactor(app):=20=E8=AE=BE=E7=BD=AE?=
 =?UTF-8?q?=E5=85=A5=E5=8F=A3=E6=94=B9=E4=B8=BA=E6=A8=A1=E6=80=81=E6=A1=86?=
 =?UTF-8?q?=E5=B9=B6=E5=A2=9E=E5=BC=BA=E5=AF=86=E7=A0=81=E8=BE=93=E5=85=A5?=
 =?UTF-8?q?=E6=A1=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新建 SettingsModal 组件，从 SettingsView 迁移为按需挂载弹窗
- ProjectView 通过 isSettingsOpen 状态用 v-if 挂载，每次打开重新读取磁盘配置
- 删除 /project/:id/settings 路由与 SettingsView 页面，设置全走模态框
- 新增 PasswordInput 通用组件，右侧眼睛切换明文/密文
- 设置弹窗三处 API Key 输入框统一替换为 PasswordInput
---
 packages/app/src/app/router.ts                |   6 -
 .../src/components/settings/SettingsModal.vue | 649 ++++++++++++++++++
 .../app/src/components/ui/PasswordInput.vue   |  50 ++
 packages/app/src/views/ProjectView.vue        |  14 +-
 packages/app/src/views/SettingsView.vue       | 645 -----------------
 5 files changed, 710 insertions(+), 654 deletions(-)
 create mode 100644 packages/app/src/components/settings/SettingsModal.vue
 create mode 100644 packages/app/src/components/ui/PasswordInput.vue
 delete mode 100644 packages/app/src/views/SettingsView.vue

diff --git a/packages/app/src/app/router.ts b/packages/app/src/app/router.ts
index 24ee20a..4188143 100644
--- a/packages/app/src/app/router.ts
+++ b/packages/app/src/app/router.ts
@@ -2,7 +2,6 @@ import { createRouter, createWebHistory } from 'vue-router'
 
 import HomeView from '../views/HomeView.vue'
 import ProjectView from '../views/ProjectView.vue'
-import SettingsView from '../views/SettingsView.vue'
 
 export const router = createRouter({
   history: createWebHistory(import.meta.env.BASE_URL),
@@ -17,10 +16,5 @@ export const router = createRouter({
       name: 'project',
       component: ProjectView,
     },
-    {
-      path: '/project/:id/settings',
-      name: 'settings',
-      component: SettingsView,
-    },
   ],
 })
diff --git a/packages/app/src/components/settings/SettingsModal.vue b/packages/app/src/components/settings/SettingsModal.vue
new file mode 100644
index 0000000..909dd99
--- /dev/null
+++ b/packages/app/src/components/settings/SettingsModal.vue
@@ -0,0 +1,649 @@
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue'
+import { useSettingsStore } from '../../stores/settings'
+import { inspectIndex, rebuildIndex } from '@novai/core/services/rag-service'
+import type { ProjectIndexMetaView } from '@novai/core/services/types'
+import PasswordInput from '../ui/PasswordInput.vue'
+
+const props = defineProps<{
+  projectId: string
+}>()
+
+const emit = defineEmits<{
+  close: []
+}>()
+
+const settingsStore = useSettingsStore()
+
+const activeTab = ref<'llm' | 'embedding' | 'rerank' | 'project'>('llm')
+
+// 表单状态
+const llmForm = ref({
+  baseUrl: '',
+  apiKey: '',
+  model: '',
+})
+
+const embeddingForm = ref({
+  baseUrl: '',
+  apiKey: '',
+  model: '',
+})
+
+const rerankForm = ref({
+  enabled: false,
+  baseUrl: '',
+  apiKey: '',
+  model: '',
+  mode: 'text' as 'text' | 'multimodal',
+  topN: 8,
+})
+
+const projectForm = ref({
+  proofreadDefaultChapters: 3,
+  organizeDefaultChapters: 10,
+  generationRecentChapters: 3,
+  ragCandidateLimit: 20,
+  ragContextMaxItems: 8,
+  conversationTokenLimit: 8000,
+  compressionKeepRecentTurns: 5,
+  enableDebugLogging: false,
+})
+
+const isTesting = ref(false)
+const testResult = ref<{ ok: boolean; message: string } | null>(null)
+const isIndexBusy = ref(false)
+const indexMeta = ref<ProjectIndexMetaView | null>(null)
+const indexStatusMessage = ref('尚未读取索引状态')
+
+const projectId = computed(() => props.projectId)
+
+/**
+ * 模态框采用 v-if 按需挂载，每次打开都会重新触发 onMounted，
+ * 从而保证配置与索引状态始终从磁盘读取最新值，无需额外刷新逻辑。
+ */
+onMounted(async () => {
+  await settingsStore.loadSettings(projectId.value)
+
+  // 填充表单
+  if (settingsStore.config) {
+    llmForm.value = {
+      baseUrl: settingsStore.config.llm?.baseUrl ?? '',
+      apiKey: settingsStore.config.llm?.apiKey ?? '',
+      model: settingsStore.config.llm?.model ?? '',
+    }
+    embeddingForm.value = {
+      baseUrl: settingsStore.config.embedding?.baseUrl ?? '',
+      apiKey: settingsStore.config.embedding?.apiKey ?? '',
+      model: settingsStore.config.embedding?.model ?? '',
+    }
+    if (settingsStore.config.rerank) {
+      rerankForm.value = {
+        enabled: settingsStore.config.rerank.enabled ?? false,
+        baseUrl: settingsStore.config.rerank.baseUrl ?? '',
+        apiKey: settingsStore.config.rerank.apiKey ?? '',
+        model: settingsStore.config.rerank.model ?? '',
+        mode: settingsStore.config.rerank.mode ?? 'text',
+        topN: settingsStore.config.rerank.topN ?? 8,
+      }
+    }
+    if (settingsStore.config.settings) {
+      applyProjectSettings(settingsStore.config.settings)
+    }
+  }
+
+  await handleInspectIndex()
+})
+
+async function handleTestLlm() {
+  isTesting.value = true
+  testResult.value = null
+  try {
+    const result = await settingsStore.testLlmConfig(llmForm.value)
+    testResult.value = result
+  } finally {
+    isTesting.value = false
+  }
+}
+
+async function handleTestEmbedding() {
+  isTesting.value = true
+  testResult.value = null
+  try {
+    const result = await settingsStore.testEmbeddingConfig(embeddingForm.value)
+    testResult.value = result
+  } finally {
+    isTesting.value = false
+  }
+}
+
+async function handleSaveLlm() {
+  await settingsStore.saveConfig(projectId.value, { llm: llmForm.value })
+}
+
+async function handleSaveEmbedding() {
+  await settingsStore.saveConfig(projectId.value, { embedding: embeddingForm.value })
+}
+
+async function handleSaveRerank() {
+  await settingsStore.saveConfig(projectId.value, { rerank: rerankForm.value })
+}
+
+async function handleSaveProject() {
+  testResult.value = null
+
+  const savedConfig = await settingsStore.saveConfig(projectId.value, {
+    settings: { ...projectForm.value },
+  })
+
+  if (!savedConfig) {
+    testResult.value = {
+      ok: false,
+      message: settingsStore.errorMessage || '项目设置保存失败',
+    }
+    return
+  }
+
+  applyProjectSettings(savedConfig.settings)
+  testResult.value = {
+    ok: true,
+    message: '项目设置已保存',
+  }
+}
+
+async function handleInspectIndex() {
+  isIndexBusy.value = true
+  try {
+    indexMeta.value = await inspectIndex(projectId.value)
+    indexStatusMessage.value = indexMeta.value
+      ? `当前状态：${getIndexStatusLabel(indexMeta.value.status)}`
+      : '当前项目还没有索引记录'
+  } catch (error) {
+    indexStatusMessage.value = error instanceof Error ? error.message : '读取索引状态失败'
+  } finally {
+    isIndexBusy.value = false
+  }
+}
+
+async function handleRebuildIndex() {
+  isIndexBusy.value = true
+  testResult.value = null
+  indexStatusMessage.value = '正在重建向量索引...'
+
+  try {
+    const result = await rebuildIndex(projectId.value)
+    indexMeta.value = await inspectIndex(projectId.value)
+    indexStatusMessage.value = result.message
+    testResult.value = {
+      ok: result.status === 'ready' || result.status === 'empty',
+      message: result.message,
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : '重建索引失败'
+    indexStatusMessage.value = message
+    testResult.value = {
+      ok: false,
+      message,
+    }
+  } finally {
+    isIndexBusy.value = false
+  }
+}
+
+function getIndexStatusLabel(status: ProjectIndexMetaView['status']) {
+  switch (status) {
+    case 'ready': return '可用'
+    case 'empty': return '空索引'
+    case 'building': return '构建中'
+    case 'rebuilding': return '重建中'
+    case 'stale': return '已过期'
+    case 'error': return '错误'
+    default: return status
+  }
+}
+
+function getIndexStatusClass(status?: ProjectIndexMetaView['status']) {
+  switch (status) {
+    case 'ready': return 'bg-green-50 text-green-700 ring-green-200'
+    case 'stale': return 'bg-amber-50 text-amber-700 ring-amber-200'
+    case 'error': return 'bg-red-50 text-red-700 ring-red-200'
+    case 'building':
+    case 'rebuilding': return 'bg-blue-50 text-blue-700 ring-blue-200'
+    default: return 'bg-gray-50 text-gray-700 ring-gray-200'
+  }
+}
+
+function formatDate(value?: string) {
+  return value ? new Date(value).toLocaleString('zh-CN') : '暂无'
+}
+
+function applyProjectSettings(settings: NonNullable<typeof settingsStore.config>['settings']) {
+  projectForm.value = {
+    proofreadDefaultChapters: settings.proofreadDefaultChapters ?? 3,
+    organizeDefaultChapters: settings.organizeDefaultChapters ?? 10,
+    generationRecentChapters: settings.generationRecentChapters ?? 3,
+    ragCandidateLimit: settings.ragCandidateLimit ?? 20,
+    ragContextMaxItems: settings.ragContextMaxItems ?? 8,
+    conversationTokenLimit: settings.conversationTokenLimit ?? 8000,
+    compressionKeepRecentTurns: settings.compressionKeepRecentTurns ?? 5,
+    enableDebugLogging: settings.enableDebugLogging ?? false,
+  }
+}
+</script>
+
+<template>
+  <!-- 遮罩层 -->
+  <div
+    class="fixed inset-0 z-50 flex items-center justify-center bg-black/40 p-4"
+    @click.self="emit('close')"
+  >
+    <!-- 模态框主体 -->
+    <div class="flex h-[85vh] w-full max-w-3xl flex-col overflow-hidden rounded-xl bg-white shadow-2xl">
+      <!-- 顶栏：标题 + 关闭按钮 -->
+      <header class="flex shrink-0 items-center justify-between border-b border-gray-200 px-6 py-4">
+        <h2 class="text-lg font-semibold text-gray-900">项目设置</h2>
+        <button
+          class="flex h-8 w-8 items-center justify-center rounded-lg text-gray-400 transition-colors hover:bg-gray-100 hover:text-gray-700"
+          title="关闭"
+          @click="emit('close')"
+        >
+          <svg class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+          </svg>
+        </button>
+      </header>
+
+      <!-- 选项卡（固定顶部，不随内容滚动） -->
+      <div class="shrink-0 border-b border-gray-200 px-6">
+        <nav class="flex gap-6">
+          <button
+            v-for="tab in [
+              { key: 'llm', label: 'LLM 配置' },
+              { key: 'embedding', label: 'Embedding 配置' },
+              { key: 'rerank', label: 'Rerank 配置' },
+              { key: 'project', label: '项目设置' },
+            ]"
+            :key="tab.key"
+            :class="[
+              'border-b-2 px-1 py-3 text-sm font-medium transition-colors',
+              activeTab === tab.key
+                ? 'border-gray-900 text-gray-900'
+                : 'border-transparent text-gray-500 hover:text-gray-700',
+            ]"
+            @click="activeTab = tab.key as typeof activeTab"
+          >
+            {{ tab.label }}
+          </button>
+        </nav>
+      </div>
+
+      <!-- 内容区域：整体滚动 -->
+      <main class="flex-1 overflow-y-auto p-6">
+        <div class="mx-auto max-w-2xl">
+          <!-- LLM 配置 -->
+          <div v-if="activeTab === 'llm'" class="space-y-4">
+            <div>
+              <label class="mb-1 block text-sm font-medium text-gray-700">API 地址</label>
+              <input
+                v-model="llmForm.baseUrl"
+                class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                placeholder="https://api.openai.com/v1"
+              />
+            </div>
+            <div>
+              <label class="mb-1 block text-sm font-medium text-gray-700">API Key</label>
+              <PasswordInput
+                v-model="llmForm.apiKey"
+                placeholder="sk-..."
+              />
+            </div>
+            <div>
+              <label class="mb-1 block text-sm font-medium text-gray-700">模型名称（可选）</label>
+              <input
+                v-model="llmForm.model"
+                class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                placeholder="gpt-4o"
+              />
+            </div>
+            <div class="flex gap-3 pt-2">
+              <button
+                type="button"
+                class="rounded-lg border border-gray-300 px-4 py-2 text-sm font-medium text-gray-700 transition-colors hover:bg-gray-50 disabled:opacity-50"
+                :disabled="isTesting"
+                @click="handleTestLlm"
+              >
+                {{ isTesting ? '测试中...' : '测试连接' }}
+              </button>
+              <button
+                type="button"
+                class="rounded-lg bg-gray-900 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-gray-800"
+                @click="handleSaveLlm"
+              >
+                保存
+              </button>
+            </div>
+          </div>
+
+          <!-- Embedding 配置 -->
+          <div v-if="activeTab === 'embedding'" class="space-y-4">
+            <div>
+              <label class="mb-1 block text-sm font-medium text-gray-700">API 地址</label>
+              <input
+                v-model="embeddingForm.baseUrl"
+                class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                placeholder="https://api.openai.com/v1"
+              />
+            </div>
+            <div>
+              <label class="mb-1 block text-sm font-medium text-gray-700">API Key</label>
+              <PasswordInput
+                v-model="embeddingForm.apiKey"
+                placeholder="sk-..."
+              />
+            </div>
+            <div>
+              <label class="mb-1 block text-sm font-medium text-gray-700">模型名称（可选）</label>
+              <input
+                v-model="embeddingForm.model"
+                class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                placeholder="text-embedding-3-small"
+              />
+            </div>
+            <div class="flex gap-3 pt-2">
+              <button
+                type="button"
+                class="rounded-lg border border-gray-300 px-4 py-2 text-sm font-medium text-gray-700 transition-colors hover:bg-gray-50 disabled:opacity-50"
+                :disabled="isTesting"
+                @click="handleTestEmbedding"
+              >
+                {{ isTesting ? '测试中...' : '测试连接' }}
+              </button>
+              <button
+                type="button"
+                class="rounded-lg bg-gray-900 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-gray-800"
+                @click="handleSaveEmbedding"
+              >
+                保存
+              </button>
+            </div>
+          </div>
+
+          <!-- Rerank 配置 -->
+          <div v-if="activeTab === 'rerank'" class="space-y-4">
+            <div class="flex items-center gap-3">
+              <label class="text-sm font-medium text-gray-700">启用 Rerank</label>
+              <button
+                :class="[
+                  'relative inline-flex h-6 w-11 items-center rounded-full transition-colors',
+                  rerankForm.enabled ? 'bg-gray-900' : 'bg-gray-300',
+                ]"
+                @click="rerankForm.enabled = !rerankForm.enabled"
+              >
+                <span
+                  :class="[
+                    'inline-block h-4 w-4 transform rounded-full bg-white transition-transform',
+                    rerankForm.enabled ? 'translate-x-6' : 'translate-x-1',
+                  ]"
+                />
+              </button>
+            </div>
+            <div v-if="rerankForm.enabled" class="space-y-4">
+              <div>
+                <label class="mb-1 block text-sm font-medium text-gray-700">API 地址</label>
+                <input
+                  v-model="rerankForm.baseUrl"
+                  class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                />
+              </div>
+              <div>
+                <label class="mb-1 block text-sm font-medium text-gray-700">API Key</label>
+                <PasswordInput v-model="rerankForm.apiKey" />
+              </div>
+              <div>
+                <label class="mb-1 block text-sm font-medium text-gray-700">模型名称</label>
+                <input
+                  v-model="rerankForm.model"
+                  class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                />
+              </div>
+              <div>
+                <label class="mb-1 block text-sm font-medium text-gray-700">保留条数</label>
+                <input
+                  v-model.number="rerankForm.topN"
+                  type="number"
+                  min="1"
+                  max="50"
+                  class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                />
+              </div>
+            </div>
+            <div class="pt-2">
+              <button
+                type="button"
+                class="rounded-lg bg-gray-900 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-gray-800"
+                @click="handleSaveRerank"
+              >
+                保存
+              </button>
+            </div>
+          </div>
+
+          <!-- 项目设置 -->
+          <div v-if="activeTab === 'project'" class="space-y-6">
+            <!-- 生成设置 -->
+            <div>
+              <h3 class="mb-3 text-sm font-semibold text-gray-800">生成设置</h3>
+              <div class="space-y-4">
+                <div>
+                  <label class="mb-1 block text-sm font-medium text-gray-700">生成上下文章节数</label>
+                  <p class="mb-1 text-xs text-gray-500">生成时携带最近 N 章的原文作为上下文</p>
+                  <input
+                    v-model.number="projectForm.generationRecentChapters"
+                    type="number"
+                    min="0"
+                    max="20"
+                    class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                  />
+                </div>
+              </div>
+            </div>
+
+            <!-- RAG 设置 -->
+            <div>
+              <h3 class="mb-3 text-sm font-semibold text-gray-800">RAG 设置</h3>
+              <div class="space-y-4">
+                <div class="rounded-lg border border-gray-200 bg-white p-4">
+                  <div class="flex items-start justify-between gap-3">
+                    <div class="min-w-0">
+                      <div class="flex items-center gap-2">
+                        <h4 class="text-sm font-semibold text-gray-800">向量索引</h4>
+                        <span
+                          :class="[
+                            'rounded-full px-2 py-0.5 text-xs font-medium ring-1',
+                            getIndexStatusClass(indexMeta?.status),
+                          ]"
+                        >
+                          {{ indexMeta ? getIndexStatusLabel(indexMeta.status) : '未创建' }}
+                        </span>
+                      </div>
+                      <p class="mt-1 text-xs text-gray-500">{{ indexStatusMessage }}</p>
+                    </div>
+                    <div class="flex shrink-0 items-center gap-1">
+                      <button
+                        class="rounded-lg p-1.5 text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-800 disabled:opacity-40"
+                        :disabled="isIndexBusy"
+                        title="刷新索引状态"
+                        @click="handleInspectIndex"
+                      >
+                        <svg
+                          v-if="isIndexBusy"
+                          class="h-4 w-4 animate-spin"
+                          fill="none"
+                          viewBox="0 0 24 24"
+                        >
+                          <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" />
+                          <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+                        </svg>
+                        <svg v-else class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 4v6h6M20 20v-6h-6M5.5 15A7 7 0 0018 18.5M18.5 9A7 7 0 006 5.5" />
+                        </svg>
+                      </button>
+                      <button
+                        class="rounded-lg p-1.5 text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-800 disabled:opacity-40"
+                        :disabled="isIndexBusy"
+                        title="重建向量索引"
+                        @click="handleRebuildIndex"
+                      >
+                        <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4.5v15m7.5-7.5h-15" />
+                        </svg>
+                      </button>
+                    </div>
+                  </div>
+
+                  <div class="mt-3 grid grid-cols-2 gap-2 text-xs text-gray-600">
+                    <div class="rounded-md bg-gray-50 px-3 py-2">
+                      <div class="text-gray-400">文档数</div>
+                      <div class="mt-1 font-medium text-gray-800">{{ indexMeta?.documentCount ?? 0 }}</div>
+                    </div>
+                    <div class="rounded-md bg-gray-50 px-3 py-2">
+                      <div class="text-gray-400">向量维度</div>
+                      <div class="mt-1 font-medium text-gray-800">{{ indexMeta?.embeddingDim ?? 0 }}</div>
+                    </div>
+                    <div class="rounded-md bg-gray-50 px-3 py-2">
+                      <div class="text-gray-400">Embedding 模型</div>
+                      <div class="mt-1 truncate font-medium text-gray-800">{{ indexMeta?.embeddingModel || '暂无' }}</div>
+                    </div>
+                    <div class="rounded-md bg-gray-50 px-3 py-2">
+                      <div class="text-gray-400">最近构建</div>
+                      <div class="mt-1 truncate font-medium text-gray-800">{{ formatDate(indexMeta?.lastBuildAt) }}</div>
+                    </div>
+                  </div>
+
+                  <p v-if="indexMeta?.lastError" class="mt-3 text-xs text-red-600">
+                    {{ indexMeta.lastError }}
+                  </p>
+                </div>
+
+                <div>
+                  <label class="mb-1 block text-sm font-medium text-gray-700">粗检索返回条数</label>
+                  <p class="mb-1 text-xs text-gray-500">粗检索阶段返回的候选要素数量</p>
+                  <input
+                    v-model.number="projectForm.ragCandidateLimit"
+                    type="number"
+                    min="1"
+                    max="100"
+                    class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                  />
+                </div>
+                <div>
+                  <label class="mb-1 block text-sm font-medium text-gray-700">上下文最大条数</label>
+                  <p class="mb-1 text-xs text-gray-500">最终拼入生成上下文的最大要素数量</p>
+                  <input
+                    v-model.number="projectForm.ragContextMaxItems"
+                    type="number"
+                    min="1"
+                    max="50"
+                    class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                  />
+                </div>
+              </div>
+            </div>
+
+            <!-- 对话设置 -->
+            <div>
+              <h3 class="mb-3 text-sm font-semibold text-gray-800">对话设置</h3>
+              <div class="space-y-4">
+                <div>
+                  <label class="mb-1 block text-sm font-medium text-gray-700">对话上下文 Token 上限</label>
+                  <p class="mb-1 text-xs text-gray-500">接近上限时触发上下文压缩</p>
+                  <input
+                    v-model.number="projectForm.conversationTokenLimit"
+                    type="number"
+                    min="1000"
+                    max="200000"
+                    step="1000"
+                    class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                  />
+                </div>
+                <div>
+                  <label class="mb-1 block text-sm font-medium text-gray-700">压缩保留轮数</label>
+                  <p class="mb-1 text-xs text-gray-500">上下文压缩时保留最近 N 轮对话的原文</p>
+                  <input
+                    v-model.number="projectForm.compressionKeepRecentTurns"
+                    type="number"
+                    min="1"
+                    max="20"
+                    class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                  />
+                </div>
+                <label class="flex items-start gap-3 rounded-lg border border-gray-200 px-3 py-3">
+                  <input
+                    v-model="projectForm.enableDebugLogging"
+                    type="checkbox"
+                    class="mt-1 h-4 w-4 rounded border-gray-300 text-blue-600 focus:ring-blue-500"
+                  />
+                  <span>
+                    <span class="block text-sm font-medium text-gray-700">开发调试日志</span>
+                    <span class="block text-xs text-gray-500">记录模型配置、请求摘要和工具调用解析诊断；正式使用建议关闭</span>
+                  </span>
+                </label>
+              </div>
+            </div>
+
+            <!-- 校对与整理设置 -->
+            <div>
+              <h3 class="mb-3 text-sm font-semibold text-gray-800">校对与整理</h3>
+              <div class="space-y-4">
+                <div>
+                  <label class="mb-1 block text-sm font-medium text-gray-700">校对默认章节数</label>
+                  <p class="mb-1 text-xs text-gray-500">自动校对最近 N 章</p>
+                  <input
+                    v-model.number="projectForm.proofreadDefaultChapters"
+                    type="number"
+                    min="1"
+                    max="50"
+                    class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                  />
+                </div>
+                <div>
+                  <label class="mb-1 block text-sm font-medium text-gray-700">整理默认章节数</label>
+                  <p class="mb-1 text-xs text-gray-500">自动整理最近 N 章</p>
+                  <input
+                    v-model.number="projectForm.organizeDefaultChapters"
+                    type="number"
+                    min="1"
+                    max="50"
+                    class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+                  />
+                </div>
+              </div>
+            </div>
+
+            <!-- 保存按钮 -->
+            <div class="pt-2">
+              <button
+                type="button"
+                class="rounded-lg bg-gray-900 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-gray-800"
+                @click="handleSaveProject"
+              >
+                保存
+              </button>
+            </div>
+          </div>
+
+          <!-- 测试结果提示 -->
+          <div
+            v-if="testResult"
+            :class="[
+              'mt-4 rounded-lg p-4',
+              testResult.ok ? 'bg-green-50 text-green-800' : 'bg-red-50 text-red-800',
+            ]"
+          >
+            {{ testResult.message }}
+          </div>
+        </div>
+      </main>
+    </div>
+  </div>
+</template>
diff --git a/packages/app/src/components/ui/PasswordInput.vue b/packages/app/src/components/ui/PasswordInput.vue
new file mode 100644
index 0000000..34e05f0
--- /dev/null
+++ b/packages/app/src/components/ui/PasswordInput.vue
@@ -0,0 +1,50 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+
+/**
+ * 带「显示/隐藏」切换的密码输入框。
+ * 右侧眼睛图标点击切换明文/密文，沿用 v-model 语义。
+ */
+defineProps<{
+  modelValue: string
+  placeholder?: string
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+}>()
+
+const isVisible = ref(false)
+
+function onInput(event: Event) {
+  emit('update:modelValue', (event.target as HTMLInputElement).value)
+}
+</script>
+
+<template>
+  <div class="relative">
+    <input
+      :type="isVisible ? 'text' : 'password'"
+      :value="modelValue"
+      :placeholder="placeholder"
+      class="w-full rounded-lg border border-gray-300 px-3 py-2 pr-10 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+      @input="onInput"
+    />
+    <button
+      type="button"
+      :title="isVisible ? '隐藏' : '显示'"
+      class="absolute inset-y-0 right-0 flex w-9 items-center justify-center text-gray-400 transition-colors hover:text-gray-600"
+      @click="isVisible = !isVisible"
+    >
+      <!-- 眼睛（显示状态） -->
+      <svg v-if="isVisible" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M2.458 12C3.732 7.943 7.523 5 12 5c4.478 0 8.268 2.943 9.542 7-1.274 4.057-5.064 7-9.542 7-4.477 0-8.268-2.943-9.542-7z" />
+      </svg>
+      <!-- 划线眼睛（隐藏状态） -->
+      <svg v-else class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13.875 18.825A10.05 10.05 0 0112 19c-4.478 0-8.268-2.943-9.542-7a9.97 9.97 0 011.563-3.029m5.858.908a3 3 0 114.243 4.243M9.878 9.878l4.242 4.242M9.88 9.88l-3.29-3.29m7.532 7.532l3.29 3.29M3 3l3.59 3.59m0 0A9.953 9.953 0 0112 5c4.478 0 8.268 2.943 9.542 7a10.025 10.025 0 01-4.132 5.411m0 0L21 21" />
+      </svg>
+    </button>
+  </div>
+</template>
diff --git a/packages/app/src/views/ProjectView.vue b/packages/app/src/views/ProjectView.vue
index bddeffa..b8ef60a 100644
--- a/packages/app/src/views/ProjectView.vue
+++ b/packages/app/src/views/ProjectView.vue
@@ -8,6 +8,7 @@ import ActivityBar from '../components/layout/ActivityBar.vue'
 import CategoryPanel from '../components/layout/CategoryPanel.vue'
 import ChatPanel from '../components/layout/ChatPanel.vue'
 import ContentPanel from '../components/layout/ContentPanel.vue'
+import SettingsModal from '../components/settings/SettingsModal.vue'
 import Toast from '../components/ui/Toast.vue'
 import FirstTimeGuide from '../components/ui/FirstTimeGuide.vue'
 import type { Category } from '../constants/category'
@@ -24,6 +25,7 @@ const isCategoryOpen = ref(true)
 const isMobileCategoryOpen = ref(false)
 const isContentPanelOpen = ref(false)
 const showGuide = ref(false)
+const isSettingsOpen = ref(false)
 
 /** 从 currentProject 取配置里的激活场景路径（分类面板需读取它做高亮联动） */
 const activeScenePromptPath = computed(() => {
@@ -83,11 +85,10 @@ function handleBackToHome() {
 }
 
 /**
- * 打开设置。
- * R1 阶段设置模态框尚未实现（R2 的工作），这里先给提示，保留入口。
+ * 打开设置模态框（R2：从路由页迁移为弹窗，按需挂载，每次打开都重新读取磁盘配置）。
  */
 function handleOpenSettings() {
-  toast.info('设置入口将在下一阶段改为弹窗')
+  isSettingsOpen.value = true
 }
 
 /**
@@ -206,6 +207,13 @@ async function handleElementsWritten() {
       @elements-written="handleElementsWritten"
     />
 
+    <!-- 设置模态框（按需挂载：关闭时销毁，再次打开重新读取磁盘配置） -->
+    <SettingsModal
+      v-if="isSettingsOpen"
+      :project-id="projectId"
+      @close="isSettingsOpen = false"
+    />
+
     <!-- Toast 提示 -->
     <Toast
       v-for="t in toast.toasts.value"
diff --git a/packages/app/src/views/SettingsView.vue b/packages/app/src/views/SettingsView.vue
deleted file mode 100644
index 5a801e8..0000000
--- a/packages/app/src/views/SettingsView.vue
+++ /dev/null
@@ -1,645 +0,0 @@
-<script setup lang="ts">
-import { computed, onMounted, ref } from 'vue'
-import { useRoute, useRouter } from 'vue-router'
-import { useProjectStore } from '../stores/project'
-import { useSettingsStore } from '../stores/settings'
-import { inspectIndex, rebuildIndex } from '@novai/core/services/rag-service'
-import type { ProjectIndexMetaView } from '@novai/core/services/types'
-
-const route = useRoute()
-const router = useRouter()
-const projectStore = useProjectStore()
-const settingsStore = useSettingsStore()
-
-const projectId = computed(() => route.params.id as string)
-const activeTab = ref<'llm' | 'embedding' | 'rerank' | 'project'>('llm')
-
-// 表单状态
-const llmForm = ref({
-  baseUrl: '',
-  apiKey: '',
-  model: '',
-})
-
-const embeddingForm = ref({
-  baseUrl: '',
-  apiKey: '',
-  model: '',
-})
-
-const rerankForm = ref({
-  enabled: false,
-  baseUrl: '',
-  apiKey: '',
-  model: '',
-  mode: 'text' as 'text' | 'multimodal',
-  topN: 8,
-})
-
-const projectForm = ref({
-  proofreadDefaultChapters: 3,
-  organizeDefaultChapters: 10,
-  generationRecentChapters: 3,
-  ragCandidateLimit: 20,
-  ragContextMaxItems: 8,
-  conversationTokenLimit: 8000,
-  compressionKeepRecentTurns: 5,
-  enableDebugLogging: false,
-})
-
-const isTesting = ref(false)
-const testResult = ref<{ ok: boolean; message: string } | null>(null)
-const isIndexBusy = ref(false)
-const indexMeta = ref<ProjectIndexMetaView | null>(null)
-const indexStatusMessage = ref('尚未读取索引状态')
-
-onMounted(async () => {
-  await settingsStore.loadSettings(projectId.value)
-
-  // 填充表单
-  if (settingsStore.config) {
-    llmForm.value = {
-      baseUrl: settingsStore.config.llm?.baseUrl ?? '',
-      apiKey: settingsStore.config.llm?.apiKey ?? '',
-      model: settingsStore.config.llm?.model ?? '',
-    }
-    embeddingForm.value = {
-      baseUrl: settingsStore.config.embedding?.baseUrl ?? '',
-      apiKey: settingsStore.config.embedding?.apiKey ?? '',
-      model: settingsStore.config.embedding?.model ?? '',
-    }
-    if (settingsStore.config.rerank) {
-      rerankForm.value = {
-        enabled: settingsStore.config.rerank.enabled ?? false,
-        baseUrl: settingsStore.config.rerank.baseUrl ?? '',
-        apiKey: settingsStore.config.rerank.apiKey ?? '',
-        model: settingsStore.config.rerank.model ?? '',
-        mode: settingsStore.config.rerank.mode ?? 'text',
-        topN: settingsStore.config.rerank.topN ?? 8,
-      }
-    }
-    if (settingsStore.config.settings) {
-      applyProjectSettings(settingsStore.config.settings)
-    }
-  }
-
-  await handleInspectIndex()
-})
-
-function handleBack() {
-  router.push(`/project/${projectId.value}`)
-}
-
-async function handleTestLlm() {
-  isTesting.value = true
-  testResult.value = null
-  try {
-    const result = await settingsStore.testLlmConfig(llmForm.value)
-    testResult.value = result
-  } finally {
-    isTesting.value = false
-  }
-}
-
-async function handleTestEmbedding() {
-  isTesting.value = true
-  testResult.value = null
-  try {
-    const result = await settingsStore.testEmbeddingConfig(embeddingForm.value)
-    testResult.value = result
-  } finally {
-    isTesting.value = false
-  }
-}
-
-async function handleSaveLlm() {
-  await settingsStore.saveConfig(projectId.value, { llm: llmForm.value })
-}
-
-async function handleSaveEmbedding() {
-  await settingsStore.saveConfig(projectId.value, { embedding: embeddingForm.value })
-}
-
-async function handleSaveRerank() {
-  await settingsStore.saveConfig(projectId.value, { rerank: rerankForm.value })
-}
-
-async function handleSaveProject() {
-  testResult.value = null
-
-  const savedConfig = await settingsStore.saveConfig(projectId.value, {
-    settings: { ...projectForm.value },
-  })
-
-  if (!savedConfig) {
-    testResult.value = {
-      ok: false,
-      message: settingsStore.errorMessage || '项目设置保存失败',
-    }
-    return
-  }
-
-  applyProjectSettings(savedConfig.settings)
-  testResult.value = {
-    ok: true,
-    message: '项目设置已保存',
-  }
-}
-
-async function handleInspectIndex() {
-  isIndexBusy.value = true
-  try {
-    indexMeta.value = await inspectIndex(projectId.value)
-    indexStatusMessage.value = indexMeta.value
-      ? `当前状态：${getIndexStatusLabel(indexMeta.value.status)}`
-      : '当前项目还没有索引记录'
-  } catch (error) {
-    indexStatusMessage.value = error instanceof Error ? error.message : '读取索引状态失败'
-  } finally {
-    isIndexBusy.value = false
-  }
-}
-
-async function handleRebuildIndex() {
-  isIndexBusy.value = true
-  testResult.value = null
-  indexStatusMessage.value = '正在重建向量索引...'
-
-  try {
-    const result = await rebuildIndex(projectId.value)
-    indexMeta.value = await inspectIndex(projectId.value)
-    indexStatusMessage.value = result.message
-    testResult.value = {
-      ok: result.status === 'ready' || result.status === 'empty',
-      message: result.message,
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : '重建索引失败'
-    indexStatusMessage.value = message
-    testResult.value = {
-      ok: false,
-      message,
-    }
-  } finally {
-    isIndexBusy.value = false
-  }
-}
-
-function getIndexStatusLabel(status: ProjectIndexMetaView['status']) {
-  switch (status) {
-    case 'ready': return '可用'
-    case 'empty': return '空索引'
-    case 'building': return '构建中'
-    case 'rebuilding': return '重建中'
-    case 'stale': return '已过期'
-    case 'error': return '错误'
-    default: return status
-  }
-}
-
-function getIndexStatusClass(status?: ProjectIndexMetaView['status']) {
-  switch (status) {
-    case 'ready': return 'bg-green-50 text-green-700 ring-green-200'
-    case 'stale': return 'bg-amber-50 text-amber-700 ring-amber-200'
-    case 'error': return 'bg-red-50 text-red-700 ring-red-200'
-    case 'building':
-    case 'rebuilding': return 'bg-blue-50 text-blue-700 ring-blue-200'
-    default: return 'bg-gray-50 text-gray-700 ring-gray-200'
-  }
-}
-
-function formatDate(value?: string) {
-  return value ? new Date(value).toLocaleString('zh-CN') : '暂无'
-}
-
-function applyProjectSettings(settings: NonNullable<typeof settingsStore.config>['settings']) {
-  projectForm.value = {
-    proofreadDefaultChapters: settings.proofreadDefaultChapters ?? 3,
-    organizeDefaultChapters: settings.organizeDefaultChapters ?? 10,
-    generationRecentChapters: settings.generationRecentChapters ?? 3,
-    ragCandidateLimit: settings.ragCandidateLimit ?? 20,
-    ragContextMaxItems: settings.ragContextMaxItems ?? 8,
-    conversationTokenLimit: settings.conversationTokenLimit ?? 8000,
-    compressionKeepRecentTurns: settings.compressionKeepRecentTurns ?? 5,
-    enableDebugLogging: settings.enableDebugLogging ?? false,
-  }
-}
-</script>
-
-<template>
-  <div class="flex h-screen flex-col bg-gray-50">
-    <!-- 顶栏 -->
-    <header class="flex items-center gap-4 border-b border-gray-200 bg-white px-6 py-4">
-      <button
-        class="flex items-center gap-2 text-sm text-gray-600 transition-colors hover:text-gray-900"
-        @click="handleBack"
-      >
-        <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7" />
-        </svg>
-        返回项目
-      </button>
-      <h1 class="text-lg font-semibold text-gray-900">项目设置</h1>
-    </header>
-
-    <!-- 选项卡 -->
-    <div class="border-b border-gray-200 bg-white px-6">
-      <nav class="flex gap-6">
-        <button
-          v-for="tab in [
-            { key: 'llm', label: 'LLM 配置' },
-            { key: 'embedding', label: 'Embedding 配置' },
-            { key: 'rerank', label: 'Rerank 配置' },
-            { key: 'project', label: '项目设置' },
-          ]"
-          :key="tab.key"
-          :class="[
-            'border-b-2 px-1 py-3 text-sm font-medium transition-colors',
-            activeTab === tab.key
-              ? 'border-gray-900 text-gray-900'
-              : 'border-transparent text-gray-500 hover:text-gray-700',
-          ]"
-          @click="activeTab = tab.key as typeof activeTab"
-        >
-          {{ tab.label }}
-        </button>
-      </nav>
-    </div>
-
-    <!-- 内容区域 -->
-    <main class="flex-1 overflow-y-auto p-6">
-      <div class="mx-auto max-w-2xl">
-        <!-- LLM 配置 -->
-        <div v-if="activeTab === 'llm'" class="space-y-4">
-          <div>
-            <label class="mb-1 block text-sm font-medium text-gray-700">API 地址</label>
-            <input
-              v-model="llmForm.baseUrl"
-              class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-              placeholder="https://api.openai.com/v1"
-            />
-          </div>
-          <div>
-            <label class="mb-1 block text-sm font-medium text-gray-700">API Key</label>
-            <input
-              v-model="llmForm.apiKey"
-              type="password"
-              class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-              placeholder="sk-..."
-            />
-          </div>
-          <div>
-            <label class="mb-1 block text-sm font-medium text-gray-700">模型名称（可选）</label>
-            <input
-              v-model="llmForm.model"
-              class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-              placeholder="gpt-4o"
-            />
-          </div>
-          <div class="flex gap-3 pt-2">
-            <button
-              type="button"
-              class="rounded-lg border border-gray-300 px-4 py-2 text-sm font-medium text-gray-700 transition-colors hover:bg-gray-50 disabled:opacity-50"
-              :disabled="isTesting"
-              @click="handleTestLlm"
-            >
-              {{ isTesting ? '测试中...' : '测试连接' }}
-            </button>
-            <button
-              type="button"
-              class="rounded-lg bg-gray-900 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-gray-800"
-              @click="handleSaveLlm"
-            >
-              保存
-            </button>
-          </div>
-        </div>
-
-        <!-- Embedding 配置 -->
-        <div v-if="activeTab === 'embedding'" class="space-y-4">
-          <div>
-            <label class="mb-1 block text-sm font-medium text-gray-700">API 地址</label>
-            <input
-              v-model="embeddingForm.baseUrl"
-              class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-              placeholder="https://api.openai.com/v1"
-            />
-          </div>
-          <div>
-            <label class="mb-1 block text-sm font-medium text-gray-700">API Key</label>
-            <input
-              v-model="embeddingForm.apiKey"
-              type="password"
-              class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-              placeholder="sk-..."
-            />
-          </div>
-          <div>
-            <label class="mb-1 block text-sm font-medium text-gray-700">模型名称（可选）</label>
-            <input
-              v-model="embeddingForm.model"
-              class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-              placeholder="text-embedding-3-small"
-            />
-          </div>
-          <div class="flex gap-3 pt-2">
-            <button
-              type="button"
-              class="rounded-lg border border-gray-300 px-4 py-2 text-sm font-medium text-gray-700 transition-colors hover:bg-gray-50 disabled:opacity-50"
-              :disabled="isTesting"
-              @click="handleTestEmbedding"
-            >
-              {{ isTesting ? '测试中...' : '测试连接' }}
-            </button>
-            <button
-              type="button"
-              class="rounded-lg bg-gray-900 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-gray-800"
-              @click="handleSaveEmbedding"
-            >
-              保存
-            </button>
-          </div>
-        </div>
-
-        <!-- Rerank 配置 -->
-        <div v-if="activeTab === 'rerank'" class="space-y-4">
-          <div class="flex items-center gap-3">
-            <label class="text-sm font-medium text-gray-700">启用 Rerank</label>
-            <button
-              :class="[
-                'relative inline-flex h-6 w-11 items-center rounded-full transition-colors',
-                rerankForm.enabled ? 'bg-gray-900' : 'bg-gray-300',
-              ]"
-              @click="rerankForm.enabled = !rerankForm.enabled"
-            >
-              <span
-                :class="[
-                  'inline-block h-4 w-4 transform rounded-full bg-white transition-transform',
-                  rerankForm.enabled ? 'translate-x-6' : 'translate-x-1',
-                ]"
-              />
-            </button>
-          </div>
-          <div v-if="rerankForm.enabled" class="space-y-4">
-            <div>
-              <label class="mb-1 block text-sm font-medium text-gray-700">API 地址</label>
-              <input
-                v-model="rerankForm.baseUrl"
-                class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-              />
-            </div>
-            <div>
-              <label class="mb-1 block text-sm font-medium text-gray-700">API Key</label>
-              <input
-                v-model="rerankForm.apiKey"
-                type="password"
-                class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-              />
-            </div>
-            <div>
-              <label class="mb-1 block text-sm font-medium text-gray-700">模型名称</label>
-              <input
-                v-model="rerankForm.model"
-                class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-              />
-            </div>
-            <div>
-              <label class="mb-1 block text-sm font-medium text-gray-700">保留条数</label>
-              <input
-                v-model.number="rerankForm.topN"
-                type="number"
-                min="1"
-                max="50"
-                class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-              />
-            </div>
-          </div>
-          <div class="pt-2">
-            <button
-              type="button"
-              class="rounded-lg bg-gray-900 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-gray-800"
-              @click="handleSaveRerank"
-            >
-              保存
-            </button>
-          </div>
-        </div>
-
-        <!-- 项目设置 -->
-        <div v-if="activeTab === 'project'" class="space-y-6">
-          <!-- 生成设置 -->
-          <div>
-            <h3 class="mb-3 text-sm font-semibold text-gray-800">生成设置</h3>
-            <div class="space-y-4">
-              <div>
-                <label class="mb-1 block text-sm font-medium text-gray-700">生成上下文章节数</label>
-                <p class="mb-1 text-xs text-gray-500">生成时携带最近 N 章的原文作为上下文</p>
-                <input
-                  v-model.number="projectForm.generationRecentChapters"
-                  type="number"
-                  min="0"
-                  max="20"
-                  class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-                />
-              </div>
-            </div>
-          </div>
-
-          <!-- RAG 设置 -->
-          <div>
-            <h3 class="mb-3 text-sm font-semibold text-gray-800">RAG 设置</h3>
-            <div class="space-y-4">
-              <div class="rounded-lg border border-gray-200 bg-white p-4">
-                <div class="flex items-start justify-between gap-3">
-                  <div class="min-w-0">
-                    <div class="flex items-center gap-2">
-                      <h4 class="text-sm font-semibold text-gray-800">向量索引</h4>
-                      <span
-                        :class="[
-                          'rounded-full px-2 py-0.5 text-xs font-medium ring-1',
-                          getIndexStatusClass(indexMeta?.status),
-                        ]"
-                      >
-                        {{ indexMeta ? getIndexStatusLabel(indexMeta.status) : '未创建' }}
-                      </span>
-                    </div>
-                    <p class="mt-1 text-xs text-gray-500">{{ indexStatusMessage }}</p>
-                  </div>
-                  <div class="flex shrink-0 items-center gap-1">
-                    <button
-                      class="rounded-lg p-1.5 text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-800 disabled:opacity-40"
-                      :disabled="isIndexBusy"
-                      title="刷新索引状态"
-                      @click="handleInspectIndex"
-                    >
-                      <svg
-                        v-if="isIndexBusy"
-                        class="h-4 w-4 animate-spin"
-                        fill="none"
-                        viewBox="0 0 24 24"
-                      >
-                        <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" />
-                        <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
-                      </svg>
-                      <svg v-else class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 4v6h6M20 20v-6h-6M5.5 15A7 7 0 0018 18.5M18.5 9A7 7 0 006 5.5" />
-                      </svg>
-                    </button>
-                    <button
-                      class="rounded-lg p-1.5 text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-800 disabled:opacity-40"
-                      :disabled="isIndexBusy"
-                      title="重建向量索引"
-                      @click="handleRebuildIndex"
-                    >
-                      <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4.5v15m7.5-7.5h-15" />
-                      </svg>
-                    </button>
-                  </div>
-                </div>
-
-                <div class="mt-3 grid grid-cols-2 gap-2 text-xs text-gray-600">
-                  <div class="rounded-md bg-gray-50 px-3 py-2">
-                    <div class="text-gray-400">文档数</div>
-                    <div class="mt-1 font-medium text-gray-800">{{ indexMeta?.documentCount ?? 0 }}</div>
-                  </div>
-                  <div class="rounded-md bg-gray-50 px-3 py-2">
-                    <div class="text-gray-400">向量维度</div>
-                    <div class="mt-1 font-medium text-gray-800">{{ indexMeta?.embeddingDim ?? 0 }}</div>
-                  </div>
-                  <div class="rounded-md bg-gray-50 px-3 py-2">
-                    <div class="text-gray-400">Embedding 模型</div>
-                    <div class="mt-1 truncate font-medium text-gray-800">{{ indexMeta?.embeddingModel || '暂无' }}</div>
-                  </div>
-                  <div class="rounded-md bg-gray-50 px-3 py-2">
-                    <div class="text-gray-400">最近构建</div>
-                    <div class="mt-1 truncate font-medium text-gray-800">{{ formatDate(indexMeta?.lastBuildAt) }}</div>
-                  </div>
-                </div>
-
-                <p v-if="indexMeta?.lastError" class="mt-3 text-xs text-red-600">
-                  {{ indexMeta.lastError }}
-                </p>
-              </div>
-
-              <div>
-                <label class="mb-1 block text-sm font-medium text-gray-700">粗检索返回条数</label>
-                <p class="mb-1 text-xs text-gray-500">粗检索阶段返回的候选要素数量</p>
-                <input
-                  v-model.number="projectForm.ragCandidateLimit"
-                  type="number"
-                  min="1"
-                  max="100"
-                  class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-                />
-              </div>
-              <div>
-                <label class="mb-1 block text-sm font-medium text-gray-700">上下文最大条数</label>
-                <p class="mb-1 text-xs text-gray-500">最终拼入生成上下文的最大要素数量</p>
-                <input
-                  v-model.number="projectForm.ragContextMaxItems"
-                  type="number"
-                  min="1"
-                  max="50"
-                  class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-                />
-              </div>
-            </div>
-          </div>
-
-          <!-- 对话设置 -->
-          <div>
-            <h3 class="mb-3 text-sm font-semibold text-gray-800">对话设置</h3>
-            <div class="space-y-4">
-              <div>
-                <label class="mb-1 block text-sm font-medium text-gray-700">对话上下文 Token 上限</label>
-                <p class="mb-1 text-xs text-gray-500">接近上限时触发上下文压缩</p>
-                <input
-                  v-model.number="projectForm.conversationTokenLimit"
-                  type="number"
-                  min="1000"
-                  max="200000"
-                  step="1000"
-                  class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-                />
-              </div>
-              <div>
-                <label class="mb-1 block text-sm font-medium text-gray-700">压缩保留轮数</label>
-                <p class="mb-1 text-xs text-gray-500">上下文压缩时保留最近 N 轮对话的原文</p>
-                <input
-                  v-model.number="projectForm.compressionKeepRecentTurns"
-                  type="number"
-                  min="1"
-                  max="20"
-                  class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-                />
-              </div>
-              <label class="flex items-start gap-3 rounded-lg border border-gray-200 px-3 py-3">
-                <input
-                  v-model="projectForm.enableDebugLogging"
-                  type="checkbox"
-                  class="mt-1 h-4 w-4 rounded border-gray-300 text-blue-600 focus:ring-blue-500"
-                />
-                <span>
-                  <span class="block text-sm font-medium text-gray-700">开发调试日志</span>
-                  <span class="block text-xs text-gray-500">记录模型配置、请求摘要和工具调用解析诊断；正式使用建议关闭</span>
-                </span>
-              </label>
-            </div>
-          </div>
-
-          <!-- 校对与整理设置 -->
-          <div>
-            <h3 class="mb-3 text-sm font-semibold text-gray-800">校对与整理</h3>
-            <div class="space-y-4">
-              <div>
-                <label class="mb-1 block text-sm font-medium text-gray-700">校对默认章节数</label>
-                <p class="mb-1 text-xs text-gray-500">自动校对最近 N 章</p>
-                <input
-                  v-model.number="projectForm.proofreadDefaultChapters"
-                  type="number"
-                  min="1"
-                  max="50"
-                  class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-                />
-              </div>
-              <div>
-                <label class="mb-1 block text-sm font-medium text-gray-700">整理默认章节数</label>
-                <p class="mb-1 text-xs text-gray-500">自动整理最近 N 章</p>
-                <input
-                  v-model.number="projectForm.organizeDefaultChapters"
-                  type="number"
-                  min="1"
-                  max="50"
-                  class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-                />
-              </div>
-            </div>
-          </div>
-
-          <!-- 保存按钮 -->
-          <div class="pt-2">
-            <button
-              type="button"
-              class="rounded-lg bg-gray-900 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-gray-800"
-              @click="handleSaveProject"
-            >
-              保存
-            </button>
-          </div>
-        </div>
-
-        <!-- 测试结果提示 -->
-        <div
-          v-if="testResult"
-          :class="[
-            'mt-4 rounded-lg p-4',
-            testResult.ok ? 'bg-green-50 text-green-800' : 'bg-red-50 text-red-800',
-          ]"
-        >
-          {{ testResult.message }}
-        </div>
-      </div>
-    </main>
-  </div>
-</template>

From 4b161683e7f3bafe24ea76ccd097117190bcf3bd Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Wed, 17 Jun 2026 23:27:46 +0800
Subject: [PATCH 05/36] =?UTF-8?q?feat(app):=20=E5=86=85=E5=AE=B9=E9=9D=A2?=
 =?UTF-8?q?=E6=9D=BF=E6=96=B0=E5=A2=9E=E7=BC=96=E8=BE=91=E6=A8=A1=E5=BC=8F?=
 =?UTF-8?q?=E5=B9=B6=E7=BB=9F=E4=B8=80=20Tooltip=20=E4=BA=A4=E4=BA=92?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ContentPanel 预览/原始两态升级为预览/编辑/原始三态分段控件
- 编辑模式：纯 textarea 编辑章节/提示词/要素三类文件，Ctrl/⌘+S 保存
- 草稿 dirty 标记：修改后头部显示未保存红点，保存后自动消失
- 可编辑范围校验：chapters/prompts/elements.md，不支持时编辑置灰
- core 新增 writeFile 通用写入封装，project store 新增 saveFile action
- 新增 Tooltip 组件并接入 ActivityBar 与 ContentPanel，替换原生 title
---
 .../app/src/components/layout/ActivityBar.vue | 136 +++++----
 .../src/components/layout/ContentPanel.vue    | 136 ++++++++-
 packages/app/src/components/ui/Tooltip.vue    | 274 ++++++++++++++++++
 packages/app/src/stores/project.ts            |  23 ++
 packages/app/src/views/ProjectView.vue        |  15 +
 packages/core/src/services/file-service.ts    |  16 +
 6 files changed, 528 insertions(+), 72 deletions(-)
 create mode 100644 packages/app/src/components/ui/Tooltip.vue

diff --git a/packages/app/src/components/layout/ActivityBar.vue b/packages/app/src/components/layout/ActivityBar.vue
index d74a9ca..e0efac9 100644
--- a/packages/app/src/components/layout/ActivityBar.vue
+++ b/packages/app/src/components/layout/ActivityBar.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import type { Category } from '../../constants/category'
+import Tooltip from '../ui/Tooltip.vue'
 
 defineProps<{
   activeCategory: Category
@@ -54,83 +55,94 @@ function emitAction(key: 'proofread' | 'organize' | 'version') {
   <nav class="flex w-14 shrink-0 flex-col items-center justify-between border-r border-white/10 bg-[#171717] py-2">
     <!-- 顶部分类图标 -->
     <div class="flex flex-col items-center gap-1">
-      <button
+      <Tooltip
         v-for="item in categoryItems"
         :key="item.key"
-        :title="item.label"
-        :class="[
-          'group flex h-10 w-10 items-center justify-center rounded-lg transition-colors',
-          activeCategory === item.key
-            ? 'bg-white/15 text-white'
-            : 'text-gray-400 hover:bg-white/10 hover:text-gray-200',
-        ]"
-        @click="emit('select', item.key)"
+        :text="item.label"
+        preferred-placement="right"
       >
-        <!-- 对话 -->
-        <svg v-if="item.icon === 'chat'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 10h.01M12 10h.01M16 10h.01M9 16H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-5l-5 5v-5z" />
-        </svg>
-        <!-- 章节 -->
-        <svg v-else-if="item.icon === 'book'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253" />
-        </svg>
-        <!-- 要素 -->
-        <svg v-else-if="item.icon === 'tag'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A1.994 1.994 0 013 12V7a4 4 0 014-4z" />
-        </svg>
-        <!-- 提示词 -->
-        <svg v-else class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4" />
-        </svg>
-      </button>
+        <button
+          :class="[
+            'group flex h-10 w-10 items-center justify-center rounded-lg transition-colors',
+            activeCategory === item.key
+              ? 'bg-white/15 text-white'
+              : 'text-gray-400 hover:bg-white/10 hover:text-gray-200',
+          ]"
+          @click="emit('select', item.key)"
+        >
+          <!-- 对话 -->
+          <svg v-if="item.icon === 'chat'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 10h.01M12 10h.01M16 10h.01M9 16H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-5l-5 5v-5z" />
+          </svg>
+          <!-- 章节 -->
+          <svg v-else-if="item.icon === 'book'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253" />
+          </svg>
+          <!-- 要素 -->
+          <svg v-else-if="item.icon === 'tag'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A1.994 1.994 0 013 12V7a4 4 0 014-4z" />
+          </svg>
+          <!-- 提示词 -->
+          <svg v-else class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4" />
+          </svg>
+        </button>
+      </Tooltip>
     </div>
 
     <!-- 底部动作项：功能占位 + 设置 + 返回首页 -->
     <div class="flex flex-col items-center gap-1">
       <!-- 功能占位项（暂未实现，灰一档提示） -->
-      <button
+      <Tooltip
         v-for="item in actionItems"
         :key="item.key"
-        :title="`${item.label}（即将推出）`"
-        class="flex h-10 w-10 items-center justify-center rounded-lg text-gray-600 transition-colors hover:bg-white/10 hover:text-gray-400"
-        @click="emitAction(item.key)"
+        :text="`${item.label}（即将推出）`"
+        :delay="300"
+        preferred-placement="right"
       >
-        <!-- 校对 -->
-        <svg v-if="item.icon === 'check'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
-        </svg>
-        <!-- 章节整理 -->
-        <svg v-else-if="item.icon === 'list'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 10h16M4 14h16M4 18h16" />
-        </svg>
-        <!-- 版本管理 -->
-        <svg v-else class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 7h12m0 0l-4-4m4 4l-4 4m0 6H4m0 0l4 4m-4-4l4-4" />
-        </svg>
-      </button>
+        <button
+          class="flex h-10 w-10 items-center justify-center rounded-lg text-gray-600 transition-colors hover:bg-white/10 hover:text-gray-400"
+          @click="emitAction(item.key)"
+        >
+          <!-- 校对 -->
+          <svg v-if="item.icon === 'check'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+          </svg>
+          <!-- 章节整理 -->
+          <svg v-else-if="item.icon === 'list'" class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 10h16M4 14h16M4 18h16" />
+          </svg>
+          <!-- 版本管理 -->
+          <svg v-else class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 7h12m0 0l-4-4m4 4l-4 4m0 6H4m0 0l4 4m-4-4l4-4" />
+          </svg>
+        </button>
+      </Tooltip>
 
       <!-- 分隔线 -->
       <div class="my-1 h-px w-6 bg-white/10" />
 
-      <button
-        title="设置"
-        class="flex h-10 w-10 items-center justify-center rounded-lg text-gray-400 transition-colors hover:bg-white/10 hover:text-gray-200"
-        @click="emit('openSettings')"
-      >
-        <svg class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.066 2.573c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.573 1.066c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.066-2.573c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z" />
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
-        </svg>
-      </button>
-      <button
-        title="返回首页"
-        class="flex h-10 w-10 items-center justify-center rounded-lg text-gray-400 transition-colors hover:bg-white/10 hover:text-gray-200"
-        @click="emit('backToHome')"
-      >
-        <svg class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6" />
-        </svg>
-      </button>
+      <Tooltip text="设置" :delay="300" preferred-placement="right">
+        <button
+          class="flex h-10 w-10 items-center justify-center rounded-lg text-gray-400 transition-colors hover:bg-white/10 hover:text-gray-200"
+          @click="emit('openSettings')"
+        >
+          <svg class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.066 2.573c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.573 1.066c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.066-2.573c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z" />
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
+          </svg>
+        </button>
+      </Tooltip>
+      <Tooltip text="返回首页" :delay="300" preferred-placement="right">
+        <button
+          class="flex h-10 w-10 items-center justify-center rounded-lg text-gray-400 transition-colors hover:bg-white/10 hover:text-gray-200"
+          @click="emit('backToHome')"
+        >
+          <svg class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6" />
+          </svg>
+        </button>
+      </Tooltip>
     </div>
   </nav>
 </template>
diff --git a/packages/app/src/components/layout/ContentPanel.vue b/packages/app/src/components/layout/ContentPanel.vue
index 7b494fc..b096344 100644
--- a/packages/app/src/components/layout/ContentPanel.vue
+++ b/packages/app/src/components/layout/ContentPanel.vue
@@ -7,6 +7,7 @@ import type {
   FileContentView,
 } from '@novai/core/services/types'
 import MarkdownRenderer from '../ui/MarkdownRenderer.vue'
+import Tooltip from '../ui/Tooltip.vue'
 
 const props = defineProps<{
   isOpen: boolean
@@ -17,9 +18,12 @@ const props = defineProps<{
 const emit = defineEmits<{
   close: []
   elementsWritten: [result: ElementWriteResultView]
+  save: [path: string, content: string]
 }>()
 
-const viewMode = ref<'preview' | 'raw'>('preview')
+const viewMode = ref<'preview' | 'edit' | 'raw'>('preview')
+const editDraft = ref('')
+const isSaving = ref(false)
 const extractionStatus = ref('尚未提取要素')
 const extractionPreview = ref<ElementExtractionResultView | null>(null)
 const elementWriteResult = ref<ElementWriteResultView | null>(null)
@@ -35,6 +39,13 @@ const canExtractElements = computed(() => {
   )
 })
 
+const canEdit = computed(() => {
+  return Boolean(props.file && isEditablePath(props.file.path))
+})
+
+/** 草稿与磁盘内容不一致时为脏，用于显示「未保存」标记 */
+const isDirty = computed(() => editDraft.value !== (props.file?.content ?? ''))
+
 const extractionCount = computed(() => {
   if (!extractionPreview.value) {
     return 0
@@ -58,11 +69,27 @@ watch(
   () => props.file?.path,
   () => {
     resetExtractionState()
+    // 切换文件时回到预览模式并重置草稿，避免跨文件残留编辑内容
+    viewMode.value = 'preview'
+    editDraft.value = ''
   },
 )
 
-function toggleViewMode() {
-  viewMode.value = viewMode.value === 'preview' ? 'raw' : 'preview'
+// 进入编辑模式时，以磁盘当前内容初始化草稿
+watch(viewMode, (mode) => {
+  if (mode === 'edit') {
+    editDraft.value = props.file?.content ?? ''
+  }
+})
+
+/**
+ * 可编辑范围（D7 决策）：章节、提示词、要素 .md。
+ * .novel 配置、原始 JSON 等不进入用户编辑视图。
+ */
+function isEditablePath(path: string): boolean {
+  return path.startsWith('chapters/') ||
+    path.startsWith('prompts/') ||
+    (path.startsWith('elements/') && /\.md$/i.test(path))
 }
 
 function getLanguageLabel(format: string) {
@@ -77,6 +104,30 @@ function shouldRenderMarkdown(format: string) {
   return format === 'markdown'
 }
 
+/**
+ * 编辑模式键盘处理：Ctrl/Cmd+S 手动保存（失焦不自动保存）。
+ */
+function handleKeydown(event: KeyboardEvent) {
+  const isSaveShortcut = (event.ctrlKey || event.metaKey) && event.key === 's'
+  if (isSaveShortcut) {
+    event.preventDefault()
+    void handleSave()
+  }
+}
+
+async function handleSave() {
+  if (!props.file || !canEdit.value || isSaving.value || !isDirty.value) {
+    return
+  }
+
+  isSaving.value = true
+  try {
+    emit('save', props.file.path, editDraft.value)
+  } finally {
+    isSaving.value = false
+  }
+}
+
 async function handlePreviewElements() {
   if (!props.file || !canExtractElements.value || isExtracting.value) {
     return
@@ -171,19 +222,62 @@ function countExtractionItems(result: ElementExtractionResultView) {
         <h2 class="truncate text-sm font-semibold text-gray-800">
           {{ file ? file.name : '内容预览' }}
         </h2>
+        <!-- 未保存标记 -->
+        <span
+          v-if="file && viewMode === 'edit' && isDirty"
+          class="flex shrink-0 items-center gap-1 text-xs text-amber-600"
+        >
+          <span class="h-1.5 w-1.5 rounded-full bg-amber-500" />
+          未保存
+        </span>
         <span v-if="file" class="shrink-0 text-xs text-gray-500">
           {{ getLanguageLabel(file.format) }}
         </span>
       </div>
       <div class="flex items-center gap-1">
-        <!-- 预览/原始切换 -->
-        <button
+        <!-- 预览/编辑/原始 三态分段控件 -->
+        <div
           v-if="file"
-          class="rounded-lg px-2 py-1 text-xs text-gray-600 transition-colors hover:bg-gray-100"
-          @click="toggleViewMode"
+          class="flex items-center rounded-lg border border-gray-200 bg-gray-50 p-0.5"
         >
-          {{ viewMode === 'preview' ? '原始' : '预览' }}
-        </button>
+          <Tooltip
+            v-for="mode in [
+              { key: 'preview', label: '预览', icon: 'eye' },
+              { key: 'edit', label: '编辑', icon: 'pencil' },
+              { key: 'raw', label: '原始', icon: 'code' },
+            ]"
+            :key="mode.key"
+            :text="mode.key === 'edit' && !canEdit ? `${mode.label}（该文件类型不支持编辑）` : mode.label"
+            :disabled="mode.key === 'edit' && !canEdit"
+            preferred-placement="bottom"
+          >
+            <button
+              :class="[
+                'flex items-center justify-center rounded-md p-1.5 transition-colors',
+                viewMode === mode.key
+                  ? 'bg-white text-gray-900 shadow-sm'
+                  : 'text-gray-500 hover:text-gray-700',
+                mode.key === 'edit' && !canEdit ? 'cursor-not-allowed opacity-40' : '',
+              ]"
+              :disabled="mode.key === 'edit' && !canEdit"
+              @click="viewMode = mode.key as typeof viewMode"
+            >
+              <!-- 预览（眼睛） -->
+              <svg v-if="mode.icon === 'eye'" class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M2.458 12C3.732 7.943 7.523 5 12 5c4.478 0 8.268 2.943 9.542 7-1.274 4.057-5.064 7-9.542 7-4.477 0-8.268-2.943-9.542-7z" />
+              </svg>
+              <!-- 编辑（铅笔） -->
+              <svg v-else-if="mode.icon === 'pencil'" class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z" />
+              </svg>
+              <!-- 原始（代码括号） -->
+              <svg v-else class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M17.25 6.75L22.5 12l-5.25 5.25m-10.5 0L1.5 12l5.25-5.25" />
+              </svg>
+            </button>
+          </Tooltip>
+        </div>
         <button
           class="rounded-lg p-1.5 text-gray-400 transition-colors hover:bg-gray-100 hover:text-gray-600 lg:hidden"
           @click="emit('close')"
@@ -311,8 +405,30 @@ function countExtractionItems(result: ElementExtractionResultView) {
           <pre v-else class="whitespace-pre-wrap text-sm text-gray-800">{{ file.content }}</pre>
         </div>
 
+        <!-- 编辑模式 -->
+        <div v-else-if="viewMode === 'edit'" class="flex flex-col rounded-lg border border-gray-200 bg-white p-2">
+          <textarea
+            v-model="editDraft"
+            :disabled="!canEdit"
+            class="min-h-[400px] w-full resize-none rounded-md border border-gray-200 p-3 font-mono text-sm text-gray-800 focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:cursor-not-allowed disabled:bg-gray-50 disabled:text-gray-400"
+            placeholder="该文件类型不支持编辑"
+            @keydown="handleKeydown"
+          />
+          <div class="mt-2 flex items-center justify-between px-1">
+            <span class="text-xs text-gray-400">Ctrl/⌘ + S 保存</span>
+            <button
+              type="button"
+              class="rounded-lg bg-gray-900 px-3 py-1 text-xs font-medium text-white transition-colors hover:bg-gray-800 disabled:opacity-40"
+              :disabled="!canEdit || !isDirty || isSaving"
+              @click="handleSave"
+            >
+              {{ isSaving ? '保存中...' : '保存' }}
+            </button>
+          </div>
+        </div>
+
         <!-- 原始模式 -->
-        <div v-else class="rounded-lg border border-gray-200 bg-gray-900 p-4">
+        <div v-else-if="viewMode === 'raw'" class="rounded-lg border border-gray-200 bg-gray-900 p-4">
           <pre class="whitespace-pre-wrap font-mono text-sm text-gray-100">{{ file.content }}</pre>
         </div>
 
diff --git a/packages/app/src/components/ui/Tooltip.vue b/packages/app/src/components/ui/Tooltip.vue
new file mode 100644
index 0000000..0a23cd1
--- /dev/null
+++ b/packages/app/src/components/ui/Tooltip.vue
@@ -0,0 +1,274 @@
+<script setup lang="ts">
+import { computed, nextTick, onUnmounted, ref, watch } from 'vue'
+
+/**
+ * 轻量 Tooltip 组件。
+ *
+ * - 包裹任意触发内容，hover / focus 时显示气泡
+ * - 支持四向 preferredPlacement：top / bottom / left / right
+ *   空间不足时自动翻转；交叉轴超出视口时自动 clamp
+ * - 箭头始终指向 trigger 中心，随翻转/避让一起移动
+ * - hoverable + hideDelay 允许鼠标移入气泡内部（适合气泡内含可交互内容）
+ * - 滚动 / resize 期间实时跟随；卸载时清理所有定时器与监听
+ * - 带 a11y：role="tooltip" 与 aria-describedby 联动
+ *
+ * 用法：
+ *   <Tooltip text="提示文字"><button>按钮</button></Tooltip>
+ *   <Tooltip text="说明" preferred-placement="right" multiline>...</Tooltip>
+ */
+const props = withDefaults(
+  defineProps<{
+    text: string
+    /** 首选方向，空间不足时自动翻转 */
+    preferredPlacement?: 'top' | 'bottom' | 'left' | 'right'
+    /** 显示延迟（ms） */
+    delay?: number
+    /** 隐藏延迟（ms），便于鼠标移入气泡 */
+    hideDelay?: number
+    /** 是否允许鼠标移入气泡内部 */
+    hoverable?: boolean
+    /** 多行文本：自动换行并限制最大宽度 */
+    multiline?: boolean
+    /** 禁用 tooltip（不显示，但仍渲染 slot） */
+    disabled?: boolean
+  }>(),
+  {
+    preferredPlacement: 'bottom',
+    delay: 0,
+    hideDelay: 0,
+    hoverable: false,
+    multiline: false,
+    disabled: false,
+  },
+)
+
+const triggerRef = ref<HTMLElement | null>(null)
+const tooltipRef = ref<HTMLElement | null>(null)
+const isVisible = ref(false)
+
+let delayTimer: ReturnType<typeof setTimeout> | null = null
+let hideTimer: ReturnType<typeof setTimeout> | null = null
+let isHovered = false
+
+/** 翻转后的实际落点方向 */
+const side = ref<'top' | 'bottom' | 'left' | 'right'>('bottom')
+/** tooltip 左上角坐标 */
+const pos = ref({ left: 0, top: 0 })
+/** 箭头沿交叉轴的偏移（垂直落点时=left，水平落点时=top） */
+const arrowOffset = ref(0)
+
+// 为 a11y 生成稳定 id
+const tooltipId = `tooltip-${Math.random().toString(36).slice(2, 9)}`
+
+const tooltipStyle = computed(() => ({
+  left: `${pos.value.left}px`,
+  top: `${pos.value.top}px`,
+}))
+
+const isHorizontalSide = computed(() => side.value === 'left' || side.value === 'right')
+
+// 箭头：方向决定贴边 + 三角朝向；交叉轴用 arrowOffset 定位
+const arrowClass = computed(() => {
+  const base = 'absolute border-4 border-transparent'
+  switch (side.value) {
+    case 'bottom':
+      return `${base} bottom-full -translate-x-1/2 border-b-gray-800`
+    case 'top':
+      return `${base} top-full -translate-x-1/2 border-t-gray-800`
+    case 'right':
+      // tooltip 在 trigger 右侧，箭头朝左，贴 tooltip 左边
+      return `${base} right-full -translate-y-1/2 border-r-gray-800`
+    case 'left':
+      // tooltip 在 trigger 左侧，箭头朝右，贴 tooltip 右边
+      return `${base} left-full -translate-y-1/2 border-l-gray-800`
+  }
+})
+
+const arrowStyle = computed(() =>
+  isHorizontalSide.value
+    ? { top: `${arrowOffset.value}px` }
+    : { left: `${arrowOffset.value}px` },
+)
+
+function clearTimers() {
+  if (delayTimer) {
+    clearTimeout(delayTimer)
+    delayTimer = null
+  }
+  if (hideTimer) {
+    clearTimeout(hideTimer)
+    hideTimer = null
+  }
+}
+
+async function updatePosition() {
+  isVisible.value = true
+  await nextTick()
+
+  if (!triggerRef.value || !tooltipRef.value) return
+
+  const rect = triggerRef.value.getBoundingClientRect()
+  const tooltipRect = tooltipRef.value.getBoundingClientRect()
+  const vpW = window.innerWidth
+  const vpH = window.innerHeight
+  const margin = 8
+  const gap = 8
+  const width = tooltipRect.width
+  const height = tooltipRect.height
+
+  if (props.preferredPlacement === 'left' || props.preferredPlacement === 'right') {
+    // —— 水平落点：tooltip 在 trigger 左/右侧，垂直方向跟随 trigger 中心 ——
+    const triggerCenterY = rect.top + rect.height / 2
+    const maxTop = Math.max(margin, vpH - height - margin)
+    const top = Math.min(Math.max(margin, triggerCenterY - height / 2), maxTop)
+
+    const fitsRight = rect.right + gap + width <= vpW - margin
+    const fitsLeft = rect.left - gap - width >= margin
+    const resolvedSide =
+      props.preferredPlacement === 'right' ? (fitsRight ? 'right' : 'left') : fitsLeft ? 'left' : 'right'
+    const left =
+      resolvedSide === 'right' ? rect.right + gap : Math.max(margin, rect.left - gap - width)
+
+    // 箭头跟随 trigger 垂直中心，clamp 在气泡上下两端
+    const arrowMin = 12
+    const arrowMax = Math.max(arrowMin, height - arrowMin)
+    const offset = Math.min(Math.max(arrowMin, triggerCenterY - top), arrowMax)
+
+    side.value = resolvedSide
+    pos.value = { left, top }
+    arrowOffset.value = offset
+  } else {
+    // —— 垂直落点：tooltip 在 trigger 上/下方，水平方向跟随 trigger 中心 ——
+    const triggerCenterX = rect.left + rect.width / 2
+    const maxLeft = Math.max(margin, vpW - width - margin)
+    const left = Math.min(Math.max(margin, triggerCenterX - width / 2), maxLeft)
+
+    const fitsBottom = rect.bottom + gap + height <= vpH - margin
+    const fitsTop = rect.top - height - gap >= margin
+    const resolvedSide =
+      props.preferredPlacement === 'top' ? (fitsTop ? 'top' : 'bottom') : fitsBottom ? 'bottom' : 'top'
+    const top =
+      resolvedSide === 'bottom' ? rect.bottom + gap : Math.max(margin, rect.top - height - gap)
+
+    const arrowMin = 12
+    const arrowMax = Math.max(arrowMin, width - arrowMin)
+    const offset = Math.min(Math.max(arrowMin, triggerCenterX - left), arrowMax)
+
+    side.value = resolvedSide
+    pos.value = { left, top }
+    arrowOffset.value = offset
+  }
+}
+
+function showTooltip() {
+  if (props.disabled || !props.text) return
+  isHovered = true
+  if (hideTimer) {
+    clearTimeout(hideTimer)
+    hideTimer = null
+  }
+
+  if (isVisible.value) {
+    updatePosition()
+    return
+  }
+
+  if (props.delay > 0) {
+    if (delayTimer) clearTimeout(delayTimer)
+    delayTimer = setTimeout(() => {
+      if (isHovered) updatePosition()
+    }, props.delay)
+  } else {
+    updatePosition()
+  }
+}
+
+function hideTooltip() {
+  isHovered = false
+  if (delayTimer) {
+    clearTimeout(delayTimer)
+    delayTimer = null
+  }
+
+  if (props.hideDelay > 0) {
+    if (hideTimer) clearTimeout(hideTimer)
+    hideTimer = setTimeout(() => {
+      if (!isHovered) isVisible.value = false
+      hideTimer = null
+    }, props.hideDelay)
+    return
+  }
+
+  isVisible.value = false
+}
+
+// 视口滚动 / resize 期间实时跟随（capture 捕获任意可滚动容器）
+function handleViewportChange() {
+  if (isVisible.value) updatePosition()
+}
+
+function bindListeners() {
+  window.addEventListener('scroll', handleViewportChange, true)
+  window.addEventListener('resize', handleViewportChange)
+}
+
+function unbindListeners() {
+  window.removeEventListener('scroll', handleViewportChange, true)
+  window.removeEventListener('resize', handleViewportChange)
+}
+
+// 随可见性挂载/卸载监听，避免不可见时无谓计算
+watch(isVisible, (v) => {
+  if (v) bindListeners()
+  else unbindListeners()
+})
+
+onUnmounted(() => {
+  clearTimers()
+  unbindListeners()
+})
+</script>
+
+<template>
+  <span
+    ref="triggerRef"
+    class="inline-flex max-w-full"
+    :aria-describedby="isVisible && text ? tooltipId : undefined"
+    @focusin="showTooltip"
+    @focusout="hideTooltip"
+    @mouseenter="showTooltip"
+    @mouseleave="hideTooltip"
+  >
+    <slot />
+  </span>
+  <Teleport to="body">
+    <Transition
+      enter-active-class="transition-opacity duration-150 ease-out"
+      enter-from-class="opacity-0"
+      enter-to-class="opacity-100"
+      leave-active-class="transition-opacity duration-100 ease-in"
+      leave-from-class="opacity-100"
+      leave-to-class="opacity-0"
+    >
+      <span
+        v-if="isVisible && text"
+        :id="tooltipId"
+        ref="tooltipRef"
+        role="tooltip"
+        class="fixed z-50 max-w-[calc(100vw-16px)] rounded-lg bg-gray-800 px-3 py-1.5 text-[11px] leading-snug text-white shadow-lg"
+        :class="[
+          hoverable ? 'pointer-events-auto' : 'pointer-events-none',
+          multiline
+            ? 'w-max max-w-80 whitespace-pre-wrap break-words'
+            : 'whitespace-nowrap',
+        ]"
+        :style="tooltipStyle"
+        @mouseenter="hoverable ? showTooltip() : undefined"
+        @mouseleave="hoverable ? hideTooltip() : undefined"
+      >
+        <span :class="arrowClass" :style="arrowStyle"></span>
+        {{ text }}
+      </span>
+    </Transition>
+  </Teleport>
+</template>
diff --git a/packages/app/src/stores/project.ts b/packages/app/src/stores/project.ts
index d9814c3..33a6e58 100644
--- a/packages/app/src/stores/project.ts
+++ b/packages/app/src/stores/project.ts
@@ -16,6 +16,7 @@ import {
 import {
   readFile,
   refreshFiles,
+  writeFile,
 } from '@novai/core/services/file-service'
 import { updateConfig } from '@novai/core/services/settings-service'
 import type {
@@ -176,6 +177,27 @@ export const useProjectStore = defineStore('project', () => {
     }
   }
 
+  /**
+   * 保存内容面板编辑模式的草稿到磁盘。
+   * 写盘成功后更新 activeFile（同步最新 updatedAt），不刷新整个文件树
+   *（文件树结构未变，仅内容更新）。
+   */
+  async function saveFile(path: string, content: string) {
+    if (!currentProject.value) {
+      return null
+    }
+
+    errorMessage.value = ''
+
+    try {
+      activeFile.value = await writeFile(currentProject.value.id, path, content)
+      return activeFile.value
+    } catch (error) {
+      errorMessage.value = toMessage(error, '保存文件失败')
+      return null
+    }
+  }
+
   async function refreshTree() {
     if (!currentProject.value) {
       return
@@ -285,6 +307,7 @@ export const useProjectStore = defineStore('project', () => {
     refreshTree,
     removeRecentProject,
     restoreLastOpenedProject,
+    saveFile,
     updateCurrentProjectConfig,
   }
 })
diff --git a/packages/app/src/views/ProjectView.vue b/packages/app/src/views/ProjectView.vue
index b8ef60a..64f2d67 100644
--- a/packages/app/src/views/ProjectView.vue
+++ b/packages/app/src/views/ProjectView.vue
@@ -104,6 +104,20 @@ async function handleSelectFile(path: string) {
   isContentPanelOpen.value = true
 }
 
+/**
+ * 内容面板编辑模式保存：写盘后由 store 更新 activeFile（同步最新 updatedAt），
+ * ContentPanel 侧的草稿会因为 watch viewMode 不再触发而保持，但 isDirty 会
+ * 因 file.content 更新而变 false，「未保存」标记自动消失。
+ */
+async function handleSaveFile(path: string, content: string) {
+  const saved = await projectStore.saveFile(path, content)
+  if (saved) {
+    toast.success('已保存')
+  } else {
+    toast.error(projectStore.errorMessage || '保存失败')
+  }
+}
+
 async function handleChangeScene(path: string | null) {
   const saved = await projectStore.changeActiveScenePromptPath(projectId.value, path)
   if (saved) {
@@ -205,6 +219,7 @@ async function handleElementsWritten() {
       :file="projectStore.activeFile"
       @close="isContentPanelOpen = false"
       @elements-written="handleElementsWritten"
+      @save="handleSaveFile"
     />
 
     <!-- 设置模态框（按需挂载：关闭时销毁，再次打开重新读取磁盘配置） -->
diff --git a/packages/core/src/services/file-service.ts b/packages/core/src/services/file-service.ts
index e50ba01..910db63 100644
--- a/packages/core/src/services/file-service.ts
+++ b/packages/core/src/services/file-service.ts
@@ -2,6 +2,7 @@ import {
   readProjectFile,
   rescanProject,
   writeChapterFile,
+  writeProjectTextFile,
 } from '../core/fs/project-fs'
 
 import {
@@ -49,3 +50,18 @@ export async function writeChapter(
   const savedName = await writeChapterFile(project.handle, fileName, content)
   return toFileContentView(await readProjectFile(project, `chapters/${savedName}`))
 }
+
+/**
+ * 按相对路径写入项目中的任意文本文件（自动创建中间目录）。
+ * 写盘后回读一次，返回含最新 updatedAt 的 FileContentView。
+ * 供内容面板编辑模式保存章节 / 提示词 / 要素三类文件使用。
+ */
+export async function writeFile(
+  projectId: string,
+  path: string,
+  content: string,
+): Promise<FileContentView> {
+  const project = requireRuntimeProject(projectId)
+  await writeProjectTextFile(project.handle, path, content)
+  return toFileContentView(await readProjectFile(project, path))
+}

From 82320ed4e3c16cf1ce127b44f46f4274b7885258 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Wed, 17 Jun 2026 23:31:15 +0800
Subject: [PATCH 06/36] =?UTF-8?q?fix(app):=20=E5=86=85=E5=AE=B9=E9=9D=A2?=
 =?UTF-8?q?=E6=9D=BF=E4=B8=89=E6=80=81=E6=8E=A7=E4=BB=B6=20Tooltip=20?=
 =?UTF-8?q?=E5=A2=9E=E5=8A=A0=20300ms=20=E6=98=BE=E7=A4=BA=E5=BB=B6?=
 =?UTF-8?q?=E8=BF=9F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/app/src/components/layout/ContentPanel.vue | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/app/src/components/layout/ContentPanel.vue b/packages/app/src/components/layout/ContentPanel.vue
index b096344..1e71da8 100644
--- a/packages/app/src/components/layout/ContentPanel.vue
+++ b/packages/app/src/components/layout/ContentPanel.vue
@@ -249,6 +249,7 @@ function countExtractionItems(result: ElementExtractionResultView) {
             :key="mode.key"
             :text="mode.key === 'edit' && !canEdit ? `${mode.label}（该文件类型不支持编辑）` : mode.label"
             :disabled="mode.key === 'edit' && !canEdit"
+            :delay="300"
             preferred-placement="bottom"
           >
             <button

From 49fde6579e332acbdcbc07f42bf8276aa2c1b38f Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Thu, 18 Jun 2026 21:07:59 +0800
Subject: [PATCH 07/36] =?UTF-8?q?feat(app):=20=E9=80=89=E4=B8=AD=E5=86=85?=
 =?UTF-8?q?=E5=AE=B9=E5=BC=95=E7=94=A8=E6=94=AF=E6=8C=81=E7=8B=AC=E7=AB=8B?=
 =?UTF-8?q?=E5=BC=95=E7=94=A8=E5=9D=97=E5=B1=95=E7=A4=BA=E4=B8=8E=E6=A8=A1?=
 =?UTF-8?q?=E5=9E=8B=E6=B3=A8=E5=85=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- core: ChatMessage / ChatMessageView / RunAgentTurnInput 加 quote 字段
- core: runTurn 透传 quote 到 runChatTurn（根因修复点）
- core: createUserMessage 与 buildAgentMessages 全链路透传 quote
- core: buildAgentUserContext 注入「用户引用的内容」段到模型输入
- core: agent_run_start 日志补充 quote 字段便于排查
- app: chatStore sendMessage 接收并透传 quote
- app: 新增 SelectionChip 引用 chip 组件
- app: ContentPanel 预览模式 mouseup 捕获选中文字（500 字截断）
- app: ChatPanel 输入区上方显示 chip 并在发送时透传 quote
- app: ProjectView 串联引用状态，切换文件自动清除
- app: MessageItem 用户气泡渲染独立引用块
---
 .../app/src/components/chat/MessageItem.vue   |  7 ++++
 .../app/src/components/chat/SelectionChip.vue | 42 +++++++++++++++++++
 .../app/src/components/layout/ChatPanel.vue   | 26 +++++++++++-
 .../src/components/layout/ContentPanel.vue    | 27 +++++++++++-
 packages/app/src/stores/chat.ts               |  3 +-
 packages/app/src/views/ProjectView.vue        | 22 ++++++++++
 packages/core/src/core/agent/prompt.ts        | 14 ++++++-
 packages/core/src/core/chat/session.ts        |  9 +++-
 packages/core/src/services/agent-service.ts   |  3 ++
 packages/core/src/services/types.ts           |  4 ++
 packages/core/src/types/chat.ts               |  4 ++
 11 files changed, 153 insertions(+), 8 deletions(-)
 create mode 100644 packages/app/src/components/chat/SelectionChip.vue

diff --git a/packages/app/src/components/chat/MessageItem.vue b/packages/app/src/components/chat/MessageItem.vue
index 7ee81de..5103dad 100644
--- a/packages/app/src/components/chat/MessageItem.vue
+++ b/packages/app/src/components/chat/MessageItem.vue
@@ -25,6 +25,13 @@ function formatTime(dateStr: string) {
         </svg>
       </div>
       <div class="rounded-lg rounded-tr-none bg-blue-600 px-4 py-2.5">
+        <!-- 引用块：选中内容作为独立引用展示在正文上方 -->
+        <div
+          v-if="message.quote"
+          class="mb-2 border-l-2 border-blue-300 bg-blue-500/40 py-1 pl-2 pr-1"
+        >
+          <p class="whitespace-pre-wrap text-xs text-blue-100">{{ message.quote }}</p>
+        </div>
         <p class="whitespace-pre-wrap text-sm text-white">{{ message.text }}</p>
         <p class="mt-1 text-right text-xs text-blue-200">{{ formatTime(message.createdAt) }}</p>
       </div>
diff --git a/packages/app/src/components/chat/SelectionChip.vue b/packages/app/src/components/chat/SelectionChip.vue
new file mode 100644
index 0000000..5ee76b4
--- /dev/null
+++ b/packages/app/src/components/chat/SelectionChip.vue
@@ -0,0 +1,42 @@
+<script setup lang="ts">
+/**
+ * 选中内容引用 chip。
+ * 显示文件名 + 截断的选中文本，点 × 清除引用。
+ * chip 内文本截断仅影响展示，实际发送的完整文本由父组件持有。
+ */
+defineProps<{
+  fileName: string
+  text: string
+}>()
+
+const emit = defineEmits<{
+  remove: []
+}>()
+</script>
+
+<template>
+  <div
+    class="inline-flex max-w-full items-center gap-1.5 rounded-md border border-blue-200 bg-blue-50 px-2 py-1 text-xs text-blue-700"
+  >
+    <svg class="h-3.5 w-3.5 shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+      <path
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        stroke-width="2"
+        d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
+      />
+    </svg>
+    <span class="shrink-0 font-medium">{{ fileName }}</span>
+    <span class="truncate">"{{ text }}"</span>
+    <button
+      type="button"
+      class="flex shrink-0 items-center justify-center rounded p-0.5 text-blue-400 transition-colors hover:bg-blue-100 hover:text-blue-600"
+      title="移除引用"
+      @click="emit('remove')"
+    >
+      <svg class="h-3.5 w-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+      </svg>
+    </button>
+  </div>
+</template>
diff --git a/packages/app/src/components/layout/ChatPanel.vue b/packages/app/src/components/layout/ChatPanel.vue
index 3938c34..27e748e 100644
--- a/packages/app/src/components/layout/ChatPanel.vue
+++ b/packages/app/src/components/layout/ChatPanel.vue
@@ -3,17 +3,27 @@ import { computed, nextTick, ref, watch } from 'vue'
 import { useChatStore } from '../../stores/chat'
 import { shouldSubmitOnEnter } from '../../composables/keyboard'
 import MessageItem from '../chat/MessageItem.vue'
+import SelectionChip from '../chat/SelectionChip.vue'
 
-defineProps<{
+/** 选中引用的数据结构，与 ContentPanel emit 的 selectQuote payload 一致 */
+type SelectionQuote = {
+  path: string
+  name: string
+  text: string
+}
+
+const props = defineProps<{
   projectId: string
   isSidebarOpen: boolean
   isContentPanelOpen: boolean
+  quote: SelectionQuote | null
 }>()
 
 const emit = defineEmits<{
   toggleSidebar: []
   toggleContentPanel: []
   toggleMobileSidebar: []
+  clearQuote: []
 }>()
 
 const chatStore = useChatStore()
@@ -46,6 +56,8 @@ async function handleSend() {
   if (!inputText.value.trim() || isSending.value) return
 
   const message = inputText.value.trim()
+  // 发送前快照引用文本（发送过程中 chip 可能被清除）
+  const quoteText = props.quote?.text
   inputText.value = ''
 
   // 重置 textarea 高度
@@ -54,7 +66,9 @@ async function handleSend() {
   }
 
   try {
-    await chatStore.sendMessage(message)
+    await chatStore.sendMessage(message, quoteText)
+    // 发送成功后清除引用 chip
+    emit('clearQuote')
   } catch {
     // 错误已在 store 中写入 runStatus，这里静默处理
   }
@@ -159,6 +173,14 @@ function autoResize(event: Event) {
     <!-- 输入区域 -->
     <div class="border-t border-gray-200 bg-white px-4 py-3">
       <div class="mx-auto max-w-3xl">
+        <!-- 选中引用 chip -->
+        <div v-if="quote" class="mb-2">
+          <SelectionChip
+            :file-name="quote.name"
+            :text="quote.text"
+            @remove="emit('clearQuote')"
+          />
+        </div>
         <div class="flex gap-2">
           <textarea
             ref="textareaRef"
diff --git a/packages/app/src/components/layout/ContentPanel.vue b/packages/app/src/components/layout/ContentPanel.vue
index 1e71da8..d9bf665 100644
--- a/packages/app/src/components/layout/ContentPanel.vue
+++ b/packages/app/src/components/layout/ContentPanel.vue
@@ -19,6 +19,7 @@ const emit = defineEmits<{
   close: []
   elementsWritten: [result: ElementWriteResultView]
   save: [path: string, content: string]
+  selectQuote: [payload: { path: string; name: string; text: string }]
 }>()
 
 const viewMode = ref<'preview' | 'edit' | 'raw'>('preview')
@@ -128,6 +129,26 @@ async function handleSave() {
   }
 }
 
+/**
+ * 预览模式下捕获用户选中的文本，生成引用 chip。
+ * 仅预览模式触发（编辑模式选中是编辑操作，原始模式选中无意义）。
+ * 单段上限 500 字符，超出截断（避免整篇复制）。
+ */
+function handleContentMouseup() {
+  if (!props.file || viewMode.value !== 'preview') return
+
+  const selection = window.getSelection()
+  const text = selection?.toString().trim() ?? ''
+  if (text.length === 0) return
+
+  const trimmed = text.length > 500 ? `${text.slice(0, 500)}…` : text
+  emit('selectQuote', {
+    path: props.file.path,
+    name: props.file.name,
+    text: trimmed,
+  })
+}
+
 async function handlePreviewElements() {
   if (!props.file || !canExtractElements.value || isExtracting.value) {
     return
@@ -401,7 +422,11 @@ function countExtractionItems(result: ElementExtractionResultView) {
         </div>
 
         <!-- 预览模式 -->
-        <div v-if="viewMode === 'preview'" class="rounded-lg border border-gray-200 bg-gray-50 p-4">
+        <div
+          v-if="viewMode === 'preview'"
+          class="rounded-lg border border-gray-200 bg-gray-50 p-4"
+          @mouseup="handleContentMouseup"
+        >
           <MarkdownRenderer v-if="shouldRenderMarkdown(file.format)" :content="file.content" />
           <pre v-else class="whitespace-pre-wrap text-sm text-gray-800">{{ file.content }}</pre>
         </div>
diff --git a/packages/app/src/stores/chat.ts b/packages/app/src/stores/chat.ts
index 59ee8fd..3148e78 100644
--- a/packages/app/src/stores/chat.ts
+++ b/packages/app/src/stores/chat.ts
@@ -136,7 +136,7 @@ export const useChatStore = defineStore('chat', () => {
     return ensureSessionView(projectId)
   }
 
-  async function sendMessage(text: string) {
+  async function sendMessage(text: string, quote?: string) {
     if (!sessionView.value) {
       throw new Error('没有活跃的会话')
     }
@@ -144,6 +144,7 @@ export const useChatStore = defineStore('chat', () => {
     return runServiceTurn({
       projectId: sessionView.value.projectId,
       instruction: text,
+      quote,
     })
   }
 
diff --git a/packages/app/src/views/ProjectView.vue b/packages/app/src/views/ProjectView.vue
index 64f2d67..2482959 100644
--- a/packages/app/src/views/ProjectView.vue
+++ b/packages/app/src/views/ProjectView.vue
@@ -26,6 +26,8 @@ const isMobileCategoryOpen = ref(false)
 const isContentPanelOpen = ref(false)
 const showGuide = ref(false)
 const isSettingsOpen = ref(false)
+/** 内容面板选中的引用，透传给 ChatPanel 显示 chip；切文件时清空 */
+const selectionQuote = ref<{ path: string; name: string; text: string } | null>(null)
 
 /** 从 currentProject 取配置里的激活场景路径（分类面板需读取它做高亮联动） */
 const activeScenePromptPath = computed(() => {
@@ -79,6 +81,14 @@ watch(
   },
 )
 
+// 切换文件时清空选中引用（引用绑定当前文件，避免跨文件残留）
+watch(
+  () => projectStore.activeFile?.path,
+  () => {
+    selectionQuote.value = null
+  },
+)
+
 function handleBackToHome() {
   projectStore.closeCurrentProject()
   router.push('/')
@@ -118,6 +128,15 @@ async function handleSaveFile(path: string, content: string) {
   }
 }
 
+/** 内容面板选中文字后，把引用存入状态供 ChatPanel 显示 chip */
+function handleSelectQuote(payload: { path: string; name: string; text: string }) {
+  selectionQuote.value = payload
+}
+
+function handleClearQuote() {
+  selectionQuote.value = null
+}
+
 async function handleChangeScene(path: string | null) {
   const saved = await projectStore.changeActiveScenePromptPath(projectId.value, path)
   if (saved) {
@@ -198,9 +217,11 @@ async function handleElementsWritten() {
       :project-id="projectId"
       :is-sidebar-open="isCategoryOpen"
       :is-content-panel-open="isContentPanelOpen"
+      :quote="selectionQuote"
       @toggle-sidebar="toggleSidebar"
       @toggle-content-panel="toggleContentPanel"
       @toggle-mobile-sidebar="toggleMobileSidebar"
+      @clear-quote="handleClearQuote"
     >
       <!-- 首次使用引导 -->
       <template #guide>
@@ -220,6 +241,7 @@ async function handleElementsWritten() {
       @close="isContentPanelOpen = false"
       @elements-written="handleElementsWritten"
       @save="handleSaveFile"
+      @select-quote="handleSelectQuote"
     />
 
     <!-- 设置模态框（按需挂载：关闭时销毁，再次打开重新读取磁盘配置） -->
diff --git a/packages/core/src/core/agent/prompt.ts b/packages/core/src/core/agent/prompt.ts
index e03c647..e045ae8 100644
--- a/packages/core/src/core/agent/prompt.ts
+++ b/packages/core/src/core/agent/prompt.ts
@@ -60,6 +60,7 @@ export function buildAgentSystemPrompt(input: {
 
 export function buildAgentUserContext(input: {
   instruction: string
+  quote?: string
   project: ProjectSnapshot
   target: ChatTargetContext | null
 }) {
@@ -67,12 +68,21 @@ export function buildAgentUserContext(input: {
     ? `${input.target.displayName} (${input.target.primaryPath})`
     : input.target?.displayName || '当前项目'
 
-  return [
+  const lines = [
     `用户意图：${input.instruction}`,
+  ]
+
+  if (input.quote?.trim()) {
+    lines.push('', '用户引用的内容：', input.quote.trim())
+  }
+
+  lines.push(
     '',
     `当前项目：${input.project.name}`,
     `默认目标：${target}`,
     '',
     '请按照系统要求，通过工具读取或修改文件。若任务已经完成，请直接总结。若需要写文件，直接调用合适的文件工具。',
-  ].join('\n')
+  )
+
+  return lines.join('\n')
 }
diff --git a/packages/core/src/core/chat/session.ts b/packages/core/src/core/chat/session.ts
index 0b323ab..c9686ad 100644
--- a/packages/core/src/core/chat/session.ts
+++ b/packages/core/src/core/chat/session.ts
@@ -75,12 +75,13 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
     message: 'Agent 开始处理用户输入',
     data: {
       instruction: input.instruction,
+      quote: input.quote,
       activeFilePath: input.activeFilePath,
       target,
     },
   })
 
-  pushMessage(session, createUserMessage(input.instruction), onEvent)
+  pushMessage(session, createUserMessage(input.instruction, input.quote), onEvent)
   pushMessage(session, createContextSummary(target), onEvent)
   pushMessage(
     session,
@@ -97,6 +98,7 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
   const agentMessages = buildAgentMessages({
     previousMessages: session.agentMessages,
     instruction: input.instruction,
+    quote: input.quote,
     systemPrompt: input.systemPrompt,
     scenePrompt: input.scenePrompt,
     project: input.project,
@@ -466,6 +468,7 @@ function previewLogText(text: string) {
 function buildAgentMessages(input: {
   previousMessages?: AgentMessage[]
   instruction: string
+  quote?: string
   systemPrompt: string
   scenePrompt?: string
   project: ChatTurnInput['project']
@@ -475,6 +478,7 @@ function buildAgentMessages(input: {
     role: 'user',
     content: buildAgentUserContext({
       instruction: input.instruction,
+      quote: input.quote,
       project: input.project,
       target: input.target,
     }),
@@ -751,12 +755,13 @@ function pushErrorMessage(
   )
 }
 
-function createUserMessage(text: string): ChatMessage {
+function createUserMessage(text: string, quote?: string): ChatMessage {
   return {
     id: createId('message'),
     role: 'user',
     kind: 'text',
     text,
+    quote,
     createdAt: new Date().toISOString(),
   }
 }
diff --git a/packages/core/src/services/agent-service.ts b/packages/core/src/services/agent-service.ts
index ab65245..391b457 100644
--- a/packages/core/src/services/agent-service.ts
+++ b/packages/core/src/services/agent-service.ts
@@ -68,6 +68,7 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
       session: previousSession,
       input: {
         instruction: input.instruction,
+        quote: input.quote,
         project,
         config: project.config,
         systemPrompt,
@@ -168,6 +169,8 @@ function toChatMessageView(message: ChatMessage): ChatMessageView {
       role: message.role,
       kind: 'text',
       text: message.text,
+      // 仅 user text 消息有 quote；assistant text 无此字段，undefined 自动忽略
+      quote: 'quote' in message ? message.quote : undefined,
       createdAt: message.createdAt,
     }
   }
diff --git a/packages/core/src/services/types.ts b/packages/core/src/services/types.ts
index 8a9d72d..decb831 100644
--- a/packages/core/src/services/types.ts
+++ b/packages/core/src/services/types.ts
@@ -283,6 +283,8 @@ export type ChatMessageView =
       role: 'user'
       kind: 'text'
       text: string
+      /** 引用的选中内容，渲染为用户气泡内的独立引用块 */
+      quote?: string
       createdAt: string
     }
   | {
@@ -317,6 +319,8 @@ export type RunAgentTurnInput = {
   projectId: string
   sessionId?: string
   instruction: string
+  /** 本轮引用的选中内容，注入到发给模型的 user context */
+  quote?: string
   activeFilePath?: string
   /** 用户停止信号，透传到 Agent Loop。 */
   signal?: AbortSignal
diff --git a/packages/core/src/types/chat.ts b/packages/core/src/types/chat.ts
index 9811d9f..20f4de5 100644
--- a/packages/core/src/types/chat.ts
+++ b/packages/core/src/types/chat.ts
@@ -17,6 +17,8 @@ export type UserTextMessage = {
   role: 'user'
   kind: 'text'
   text: string
+  /** 用户在内容面板选中的引用内容，作为独立引用块展示在用户气泡内 */
+  quote?: string
   createdAt: string
 }
 
@@ -141,6 +143,8 @@ export type ToolDefinition<TInput, TOutput> = {
 
 export type ChatTurnInput = {
   instruction: string
+  /** 本轮引用的选中内容，会注入到发给模型的 user context */
+  quote?: string
   project: ProjectSnapshot
   config: ProjectConfig
   systemPrompt: string

From 0a2fd934ac6fa619bfe17f96c6abfc65dfb98534 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Thu, 18 Jun 2026 21:22:12 +0800
Subject: [PATCH 08/36] =?UTF-8?q?docs(docs):=20=E5=90=8C=E6=AD=A5=20UI=20?=
 =?UTF-8?q?=E9=87=8D=E6=9E=84=20R1/R2/R3/R5=20=E6=96=87=E6=A1=A3=E7=8A=B6?=
 =?UTF-8?q?=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs b/docs
index 610f2bb..c12f07f 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit 610f2bb3d37912f71417f4dd200cbfa76ff7e7e2
+Subproject commit c12f07f39fd32c74771fdd05e13a599849499f6c

From 92ea7861898242d80ac63031805c177d22f31678 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Thu, 18 Jun 2026 21:30:45 +0800
Subject: [PATCH 09/36] =?UTF-8?q?fix(project):=20=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E5=88=97=E8=A1=A8=E7=AB=A0=E8=8A=82=E6=95=B0?=
 =?UTF-8?q?=E6=98=BE=E7=A4=BA=E4=B8=BA=200=20=E5=B9=B6=E6=96=B0=E5=A2=9E?=
 =?UTF-8?q?=E8=A6=81=E7=B4=A0=E6=95=B0=E5=B1=95=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

项目卡片章节数恒为 0 的根因：core 已算出的 chapterCount 在 toProjectView
映射时被丢弃，存储链路从不持久化，app 首页加载时只能硬编码 0。

- 打通计数数据流：activateProject 写入时透传 metadata.chapterCount/
  elementCount，IndexedDB 记录新增两个计数字段（兼容旧记录，读取兜底 0）
- 新增要素数：summarizeProject 统计 elements 目录文件数，HomeView 卡片
  改为「N 章 · M 个要素」横排展示
- 首屏静默刷新：首页加载后后台对已授权项目扫描目录更新计数（不弹权限框），
  解决「必须打开一遍才显示数量」；updateRecentProjectCounts 仅改计数，
  保留 lastOpenedAt 避免破坏列表排序
---
 packages/app/src/stores/project.ts            | 70 +++++++++++++++++--
 packages/app/src/views/HomeView.vue           |  4 +-
 packages/core/src/core/fs/project-fs.ts       |  2 +
 .../core/src/core/project/recent-projects.ts  | 65 ++++++++++++++++-
 packages/core/src/services/project-service.ts | 41 +++++++++++
 packages/core/src/services/types.ts           |  2 +
 packages/core/src/types/project.ts            |  1 +
 7 files changed, 176 insertions(+), 9 deletions(-)

diff --git a/packages/app/src/stores/project.ts b/packages/app/src/stores/project.ts
index 33a6e58..7281177 100644
--- a/packages/app/src/stores/project.ts
+++ b/packages/app/src/stores/project.ts
@@ -10,6 +10,7 @@ import {
   getRecentProjects,
   isProjectAccessSupported,
   openProject,
+  refreshRecentProjectCounts,
   restoreRecentProject,
   restoreLastProject,
 } from '@novai/core/services/project-service'
@@ -28,6 +29,12 @@ import type {
 } from '@novai/core/services/types'
 import type { RecentProject } from '@novai/core/types/project'
 
+/**
+ * 首屏计数刷新的并发开关。
+ * onMounted 等场景可能多次触发 loadRecentProjects，用 module 级 flag 保证同一时刻只跑一次后台刷新。
+ */
+let isRefreshingCounts = false
+
 export const useProjectStore = defineStore('project', () => {
   const currentProject = ref<ProjectView | null>(null)
   const recentProjects = ref<RecentProject[]>([])
@@ -101,13 +108,8 @@ export const useProjectStore = defineStore('project', () => {
   async function loadRecentProjects() {
     try {
       const summaries = await getRecentProjects()
-      recentProjects.value = summaries.map((summary) => ({
-        id: summary.projectId,
-        name: summary.name,
-        updatedAt: summary.lastOpenedAt,
-        chapterCount: 0,
-        wordCount: 0,
-      }))
+      recentProjects.value = toRecentProjectsFromSummaries(summaries)
+      refreshRecentProjectsInBackground()
       return recentProjects.value
     } catch (error) {
       errorMessage.value = toMessage(error, '读取最近项目列表失败')
@@ -115,6 +117,47 @@ export const useProjectStore = defineStore('project', () => {
     }
   }
 
+  /**
+   * 把 service 层返回的最近项目摘要映射成 store 内部结构。
+   */
+  function toRecentProjectsFromSummaries(summaries: LastProjectSummaryView[]): RecentProject[] {
+    return summaries.map((summary) => ({
+      id: summary.projectId,
+      name: summary.name,
+      updatedAt: summary.lastOpenedAt,
+      chapterCount: summary.chapterCount,
+      elementCount: summary.elementCount,
+      wordCount: 0,
+    }))
+  }
+
+  /**
+   * 后台静默刷新最近项目的章节数/要素数。
+   *
+   * 解决「必须打开一遍才显示计数」：对已持有目录权限的项目重新扫描计数并回写。
+   * 不阻塞首屏（loadRecentProjects 已用旧值先渲染），刷新完成后覆盖 store 触发重渲染。
+   * 单次并发保护，避免 onMounted 重复触发。
+   */
+  async function refreshRecentProjectsInBackground() {
+    if (isRefreshingCounts) {
+      return
+    }
+
+    isRefreshingCounts = true
+    try {
+      const refreshedSummaries = await refreshRecentProjectCounts()
+      // 刷新期间若用户已打开项目，避免覆盖 setCurrentProject 写入的更新数据：仅当
+      // 当前 store 状态仍是列表（非空且未被清空）时回填。
+      if (recentProjects.value.length > 0) {
+        recentProjects.value = toRecentProjectsFromSummaries(refreshedSummaries)
+      }
+    } catch {
+      // 后台刷新失败不影响首屏已有数据。
+    } finally {
+      isRefreshingCounts = false
+    }
+  }
+
   async function forgetLastOpenedProject() {
     return runProjectAction(async () => {
       await forgetLastProject()
@@ -348,6 +391,7 @@ function toRecentProject(project: ProjectView): RecentProject {
     name: project.name,
     updatedAt: project.config.project.updatedAt,
     chapterCount: countChapterFiles(project.files),
+    elementCount: countElementFiles(project.files),
     wordCount: 0,
   }
 }
@@ -363,3 +407,15 @@ function countChapterFiles(nodes: ProjectFileNodeView[]): number {
     return total + countChapterFiles(node.children ?? [])
   }, 0)
 }
+
+function countElementFiles(nodes: ProjectFileNodeView[]): number {
+  return nodes.reduce((total, node) => {
+    if (node.kind === 'file') {
+      return node.path.startsWith('elements/') && /\.(md|json|txt)$/i.test(node.name)
+        ? total + 1
+        : total
+    }
+
+    return total + countElementFiles(node.children ?? [])
+  }, 0)
+}
diff --git a/packages/app/src/views/HomeView.vue b/packages/app/src/views/HomeView.vue
index 06835e0..aeddeb3 100644
--- a/packages/app/src/views/HomeView.vue
+++ b/packages/app/src/views/HomeView.vue
@@ -163,7 +163,9 @@ async function handleConfirmDeleteProject() {
               <div class="flex items-start justify-between gap-3">
                 <div class="min-w-0">
                   <h3 class="truncate font-medium text-gray-900">{{ project.name }}</h3>
-                  <p class="mt-1 text-sm text-gray-500">{{ project.chapterCount }} 章</p>
+                  <p class="mt-1 text-sm text-gray-500">
+                    {{ project.chapterCount }} 章<span class="mx-1.5 text-gray-300">·</span>{{ project.elementCount }} 个要素
+                  </p>
                 </div>
                 <button
                   class="rounded-md p-1.5 text-gray-400 opacity-0 transition hover:bg-red-50 hover:text-red-600 focus:opacity-100 focus:outline-none focus:ring-2 focus:ring-red-200 group-hover:opacity-100"
diff --git a/packages/core/src/core/fs/project-fs.ts b/packages/core/src/core/fs/project-fs.ts
index ff1459f..9d0496e 100644
--- a/packages/core/src/core/fs/project-fs.ts
+++ b/packages/core/src/core/fs/project-fs.ts
@@ -626,6 +626,7 @@ function summarizeProject(
   manifest: ProjectManifest,
 ): RecentProject {
   const chapterDirectory = tree.find((node) => node.path === 'chapters')
+  const elementDirectory = tree.find((node) => node.path === 'elements')
   const updatedAt = config.project.updatedAt || manifest.lastOpenedAt || new Date().toISOString()
 
   return {
@@ -633,6 +634,7 @@ function summarizeProject(
     name: config.project.name,
     updatedAt,
     chapterCount: countFiles(chapterDirectory),
+    elementCount: countFiles(elementDirectory),
     wordCount: 0,
   }
 }
diff --git a/packages/core/src/core/project/recent-projects.ts b/packages/core/src/core/project/recent-projects.ts
index 813db8b..f71ad5e 100644
--- a/packages/core/src/core/project/recent-projects.ts
+++ b/packages/core/src/core/project/recent-projects.ts
@@ -22,15 +22,30 @@ export type LastProjectRecord = {
   rootName: string
   lastOpenedAt: string
   handle: FileSystemDirectoryHandle
+  /**
+   * 最近一次激活项目时统计的章节数（chapters/ 目录下的文件数）。
+   * 旧记录可能缺该字段，读取时统一兜底为 0。
+   */
+  chapterCount?: number
+  /**
+   * 最近一次激活项目时统计的要素数（elements/ 目录下的文件数）。
+   * 旧记录可能缺该字段，读取时统一兜底为 0。
+   */
+  elementCount?: number
 }
 
-export type LastProjectSummary = Omit<LastProjectRecord, 'handle' | 'key'>
+export type LastProjectSummary = Omit<LastProjectRecord, 'handle' | 'key' | 'chapterCount' | 'elementCount'> & {
+  chapterCount: number
+  elementCount: number
+}
 
 export async function saveLastProject(input: {
   projectId: string
   name: string
   rootName: string
   handle: FileSystemDirectoryHandle
+  chapterCount: number
+  elementCount: number
 }): Promise<LastProjectRecord> {
   const database = await openDatabase()
   const now = new Date().toISOString()
@@ -43,6 +58,8 @@ export async function saveLastProject(input: {
     rootName: input.rootName,
     lastOpenedAt: now,
     handle: input.handle,
+    chapterCount: input.chapterCount,
+    elementCount: input.elementCount,
   }
 
   // 保存到最近项目列表
@@ -53,6 +70,8 @@ export async function saveLastProject(input: {
     rootName: input.rootName,
     lastOpenedAt: now,
     handle: input.handle,
+    chapterCount: input.chapterCount,
+    elementCount: input.elementCount,
   }
 
   await runStoreRequest(database, 'readwrite', (store) => store.put(lastRecord))
@@ -99,6 +118,8 @@ export async function readRecentProjects(): Promise<LastProjectSummary[]> {
     name: record.name,
     rootName: record.rootName,
     lastOpenedAt: record.lastOpenedAt,
+    chapterCount: record.chapterCount ?? 0,
+    elementCount: record.elementCount ?? 0,
   }))
 }
 
@@ -128,6 +149,46 @@ export async function forgetRecentProject(projectId: string) {
   database.close()
 }
 
+/**
+ * 静默刷新某个项目的章节数与要素数，回写到 last-opened 与 project-${id} 两条记录。
+ *
+ * 与 saveLastProject 的关键区别：只覆盖 chapterCount/elementCount，
+ * lastOpenedAt / name / rootName / handle 等字段原样保留，避免刷新把项目
+ * 全部顶到列表最前（破坏时间排序）。用于首页加载时对已有权限的项目做后台计数刷新。
+ */
+export async function updateRecentProjectCounts(
+  projectId: string,
+  chapterCount: number,
+  elementCount: number,
+): Promise<void> {
+  const database = await openDatabase()
+
+  try {
+    for (const key of [LAST_PROJECT_KEY, `project-${projectId}`] as const) {
+      const record = await runStoreRequest<LastProjectRecord | undefined>(
+        database,
+        'readonly',
+        (store) => store.get(key),
+      )
+
+      // 只更新匹配该项目的记录（last-opened 可能指向别的项目），其余不动。
+      if (!record || record.projectId !== projectId) {
+        continue
+      }
+
+      await runStoreRequest(database, 'readwrite', (store) =>
+        store.put({
+          ...record,
+          chapterCount,
+          elementCount,
+        }),
+      )
+    }
+  } finally {
+    database.close()
+  }
+}
+
 export async function hasProjectPermission(handle: FileSystemDirectoryHandle) {
   const target = handle as PersistableDirectoryHandle
 
@@ -158,6 +219,8 @@ export function toLastProjectSummary(record: LastProjectRecord): LastProjectSumm
     name: record.name,
     rootName: record.rootName,
     lastOpenedAt: record.lastOpenedAt,
+    chapterCount: record.chapterCount ?? 0,
+    elementCount: record.elementCount ?? 0,
   }
 }
 
diff --git a/packages/core/src/services/project-service.ts b/packages/core/src/services/project-service.ts
index 8ea2e12..3917c6d 100644
--- a/packages/core/src/services/project-service.ts
+++ b/packages/core/src/services/project-service.ts
@@ -3,6 +3,7 @@ import {
   findFirstReadableFile,
   inspectProject as inspectCoreProject,
   isFileSystemAccessSupported,
+  loadProjectFromHandle,
   pickProjectDirectory,
   repairProject,
   rescanProject,
@@ -18,6 +19,7 @@ import {
   requestProjectPermission,
   saveLastProject,
   toLastProjectSummary,
+  updateRecentProjectCounts,
 } from '../core/project/recent-projects'
 import type { ProjectSnapshot } from '../types/project'
 
@@ -124,6 +126,43 @@ export async function getRecentProjects(): Promise<LastProjectSummaryView[]> {
   return readRecentProjects()
 }
 
+/**
+ * 首屏静默刷新最近项目的章节数与要素数。
+ *
+ * 解决「必须打开一遍才显示计数」的体验问题：对每个最近项目，若目录句柄仍持有
+ * 读写权限（只查询、不弹权限框），就重新扫描目录算出计数并回写；没有权限或扫描
+ * 失败的项目原样保留旧值。整个过程不阻塞首屏（调用方应异步触发，不 await），
+ * 且不会修改 lastOpenedAt，避免破坏列表的时间排序。
+ *
+ * @returns 刷新完成后的最新最近项目列表
+ */
+export async function refreshRecentProjectCounts(): Promise<LastProjectSummaryView[]> {
+  const summaries = await readRecentProjects()
+
+  await Promise.all(
+    summaries.map(async (summary) => {
+      try {
+        const record = await readRecentProject(summary.projectId)
+        // 没有记录，或目录权限尚未授予（不主动请求），跳过保留旧值。
+        if (!record || !(await hasProjectPermission(record.handle))) {
+          return
+        }
+
+        const project = await loadProjectFromHandle(record.handle)
+        await updateRecentProjectCounts(
+          project.id,
+          project.metadata.chapterCount,
+          project.metadata.elementCount,
+        )
+      } catch {
+        // 单个项目刷新失败不影响其它项目。
+      }
+    }),
+  )
+
+  return readRecentProjects()
+}
+
 export async function forgetLastProject(): Promise<void> {
   await forgetStoredLastProject()
 }
@@ -227,6 +266,8 @@ async function activateProject(
     name: project.name,
     rootName: project.rootName,
     handle: project.handle,
+    chapterCount: project.metadata.chapterCount,
+    elementCount: project.metadata.elementCount,
   })
 
   await writeAgentLog(project, {
diff --git a/packages/core/src/services/types.ts b/packages/core/src/services/types.ts
index decb831..c902227 100644
--- a/packages/core/src/services/types.ts
+++ b/packages/core/src/services/types.ts
@@ -208,6 +208,8 @@ export type LastProjectSummaryView = {
   name: string
   rootName: string
   lastOpenedAt: string
+  chapterCount: number
+  elementCount: number
 }
 
 export type FileContentView = {
diff --git a/packages/core/src/types/project.ts b/packages/core/src/types/project.ts
index 6a5a857..c29dd76 100644
--- a/packages/core/src/types/project.ts
+++ b/packages/core/src/types/project.ts
@@ -3,6 +3,7 @@ export type ProjectSummary = {
   name: string
   updatedAt: string
   chapterCount: number
+  elementCount: number
   wordCount: number
 }
 

From 5f04c2e6325857ba8a1f504c87c2338084180cee Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Thu, 18 Jun 2026 22:00:10 +0800
Subject: [PATCH 10/36] =?UTF-8?q?feat(layout):=20=E5=86=85=E5=AE=B9?=
 =?UTF-8?q?=E9=9D=A2=E6=9D=BF=E6=94=AF=E6=8C=81=E6=8B=96=E6=8B=BD=E6=94=B9?=
 =?UTF-8?q?=E5=AE=BD=E5=B9=B6=E6=8C=81=E4=B9=85=E5=8C=96=E5=AE=BD=E5=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

R7：新增 ResizeHandle 拖拽手柄组件，内容面板宽度可在 240~720px
区间拖拽调整，双击手柄重置默认 320px，宽度持久化到 localStorage。
拖拽基于 mousedown 起始宽度计算目标宽度，避免增量累加；拖拽中
暂停 aside 过渡动画保证跟手，松手后恢复。
---
 .../src/components/layout/ContentPanel.vue    | 31 +++++++-
 .../src/components/layout/ResizeHandle.vue    | 77 +++++++++++++++++++
 packages/app/src/views/ProjectView.vue        | 24 ++++++
 3 files changed, 130 insertions(+), 2 deletions(-)
 create mode 100644 packages/app/src/components/layout/ResizeHandle.vue

diff --git a/packages/app/src/components/layout/ContentPanel.vue b/packages/app/src/components/layout/ContentPanel.vue
index d9bf665..aceec8d 100644
--- a/packages/app/src/components/layout/ContentPanel.vue
+++ b/packages/app/src/components/layout/ContentPanel.vue
@@ -8,11 +8,14 @@ import type {
 } from '@novai/core/services/types'
 import MarkdownRenderer from '../ui/MarkdownRenderer.vue'
 import Tooltip from '../ui/Tooltip.vue'
+import ResizeHandle from './ResizeHandle.vue'
 
 const props = defineProps<{
   isOpen: boolean
   projectId: string
   file: FileContentView | null
+  /** 内容面板宽度（px），由 ProjectView 持有并持久化（R7） */
+  width: number
 }>()
 
 const emit = defineEmits<{
@@ -20,11 +23,17 @@ const emit = defineEmits<{
   elementsWritten: [result: ElementWriteResultView]
   save: [path: string, content: string]
   selectQuote: [payload: { path: string; name: string; text: string }]
+  /** 拖拽改宽：发出 clamp 后的目标宽度（R7） */
+  resize: [width: number]
+  /** 双击手柄重置到默认宽度（R7） */
+  'reset-width': []
 }>()
 
 const viewMode = ref<'preview' | 'edit' | 'raw'>('preview')
 const editDraft = ref('')
 const isSaving = ref(false)
+/** 拖拽改宽进行中（R7）：暂停 aside 过渡动画，避免宽度变化滞后于光标 */
+const isResizing = ref(false)
 const extractionStatus = ref('尚未提取要素')
 const extractionPreview = ref<ElementExtractionResultView | null>(null)
 const elementWriteResult = ref<ElementWriteResultView | null>(null)
@@ -129,6 +138,13 @@ async function handleSave() {
   }
 }
 
+/**
+ * 拖拽改宽（R7）：手柄发出目标宽度，clamp 到 240~720 后上抛。
+ */
+function handleResize(width: number) {
+  emit('resize', Math.max(240, Math.min(720, width)))
+}
+
 /**
  * 预览模式下捕获用户选中的文本，生成引用 chip。
  * 仅预览模式触发（编辑模式选中是编辑操作，原始模式选中无意义）。
@@ -231,12 +247,23 @@ function countExtractionItems(result: ElementExtractionResultView) {
   <!-- 内容面板 -->
   <aside
     :class="[
-      'flex shrink-0 flex-col border-l border-gray-200 bg-white transition-all duration-200',
+      'relative flex shrink-0 flex-col border-l border-gray-200 bg-white',
+      isResizing ? '' : 'transition-all duration-200',
       'max-lg:fixed max-lg:inset-y-0 max-lg:right-0 max-lg:z-50',
-      isOpen ? 'w-80' : 'w-0 overflow-hidden',
+      isOpen ? '' : 'w-0 overflow-hidden',
       isOpen ? 'max-lg:translate-x-0' : 'max-lg:translate-x-full',
     ]"
+    :style="isOpen ? { width: width + 'px' } : undefined"
   >
+    <!-- 拖拽改宽手柄（仅 lg: 以上显示，R7） -->
+    <ResizeHandle
+      :start-width="width"
+      @dragstart="isResizing = true"
+      @drag="handleResize"
+      @dragend="isResizing = false"
+      @reset="emit('reset-width')"
+    />
+
     <!-- 头部 -->
     <div class="flex items-center justify-between border-b border-gray-200 px-4 py-3">
       <div class="flex min-w-0 items-center gap-2">
diff --git a/packages/app/src/components/layout/ResizeHandle.vue b/packages/app/src/components/layout/ResizeHandle.vue
new file mode 100644
index 0000000..b69babd
--- /dev/null
+++ b/packages/app/src/components/layout/ResizeHandle.vue
@@ -0,0 +1,77 @@
+<script setup lang="ts">
+import { onUnmounted, ref } from 'vue'
+
+/**
+ * 面板拖拽改宽手柄（R7）。
+ *
+ * - 绝对定位在父容器左侧边缘，4px 竖条
+ * - mousedown 记录起点 x 和起始宽度，document mousemove 实时计算目标宽度
+ * - 手柄在面板左侧、面板在右侧，鼠标左移（deltaX 负）面板应变宽
+ *   因此目标宽度 = startWidth - deltaX（基于起始宽度，不依赖当前 width 做累加）
+ * - 拖拽期间锁定 body 光标与文本选中，避免误触
+ * - 双击触发 reset，恢复默认宽度
+ * - 仅 lg: 断点以上渲染（移动端浮层全屏，无需拖拽）
+ */
+const props = defineProps<{
+  /** 拖拽起始时的面板宽度，用于按位移等量计算 */
+  startWidth: number
+}>()
+
+const emit = defineEmits<{
+  /** mousedown：通知父组件进入拖拽态（用于暂停过渡动画） */
+  dragstart: []
+  /** mousemove：发出目标宽度（基于 mousedown 时的 startWidth 累计位移计算），父组件直接应用 */
+  drag: [width: number]
+  /** mouseup：拖拽结束（恢复过渡动画） */
+  dragend: []
+  /** 双击重置到默认宽度 */
+  reset: []
+}>()
+
+const isDragging = ref(false)
+let startX = 0
+let startWidth = 0
+
+function handleMousedown(e: MouseEvent) {
+  e.preventDefault()
+  isDragging.value = true
+  startX = e.clientX
+  startWidth = props.startWidth
+  emit('dragstart')
+
+  document.body.classList.add('cursor-col-resize', 'select-none')
+
+  document.addEventListener('mousemove', handleMousemove)
+  document.addEventListener('mouseup', handleMouseup)
+}
+
+function handleMousemove(e: MouseEvent) {
+  if (!isDragging.value) return
+  const deltaX = e.clientX - startX
+  // 鼠标左移 deltaX 为负，面板应变宽，故目标宽度 = 起始宽度 - deltaX
+  emit('drag', startWidth - deltaX)
+}
+
+function handleMouseup() {
+  isDragging.value = false
+  document.body.classList.remove('cursor-col-resize', 'select-none')
+  document.removeEventListener('mousemove', handleMousemove)
+  document.removeEventListener('mouseup', handleMouseup)
+  emit('dragend')
+}
+
+onUnmounted(() => {
+  document.removeEventListener('mousemove', handleMousemove)
+  document.removeEventListener('mouseup', handleMouseup)
+  document.body.classList.remove('cursor-col-resize', 'select-none')
+})
+</script>
+
+<template>
+  <div
+    class="absolute left-0 top-0 z-10 hidden h-full w-1 cursor-col-resize -translate-x-1/2 bg-transparent transition-colors hover:bg-blue-400 lg:block"
+    :class="{ 'bg-blue-400': isDragging }"
+    @mousedown="handleMousedown"
+    @dblclick="emit('reset')"
+  />
+</template>
diff --git a/packages/app/src/views/ProjectView.vue b/packages/app/src/views/ProjectView.vue
index 2482959..a6d46af 100644
--- a/packages/app/src/views/ProjectView.vue
+++ b/packages/app/src/views/ProjectView.vue
@@ -29,6 +29,27 @@ const isSettingsOpen = ref(false)
 /** 内容面板选中的引用，透传给 ChatPanel 显示 chip；切文件时清空 */
 const selectionQuote = ref<{ path: string; name: string; text: string } | null>(null)
 
+/**
+ * 内容面板宽度（R7）：从 localStorage 读取，clamp 到 240~720，无记录时默认 320。
+ * 持久化到 localStorage（界面偏好），不进 config（项目数据）。
+ */
+const CONTENT_PANEL_MIN = 240
+const CONTENT_PANEL_MAX = 720
+const CONTENT_PANEL_DEFAULT = 320
+const CONTENT_PANEL_WIDTH_KEY = 'novai:contentPanelWidth'
+
+function loadContentPanelWidth(): number {
+  const raw = Number(localStorage.getItem(CONTENT_PANEL_WIDTH_KEY))
+  if (!Number.isFinite(raw)) return CONTENT_PANEL_DEFAULT
+  return Math.max(CONTENT_PANEL_MIN, Math.min(CONTENT_PANEL_MAX, raw))
+}
+
+const contentPanelWidth = ref(loadContentPanelWidth())
+
+watch(contentPanelWidth, (width) => {
+  localStorage.setItem(CONTENT_PANEL_WIDTH_KEY, String(width))
+})
+
 /** 从 currentProject 取配置里的激活场景路径（分类面板需读取它做高亮联动） */
 const activeScenePromptPath = computed(() => {
   return projectStore.currentProject?.config.settings.activeScenePromptPath ?? null
@@ -238,10 +259,13 @@ async function handleElementsWritten() {
       :is-open="isContentPanelOpen"
       :project-id="projectId"
       :file="projectStore.activeFile"
+      :width="contentPanelWidth"
       @close="isContentPanelOpen = false"
       @elements-written="handleElementsWritten"
       @save="handleSaveFile"
       @select-quote="handleSelectQuote"
+      @resize="contentPanelWidth = $event"
+      @reset-width="contentPanelWidth = CONTENT_PANEL_DEFAULT"
     />
 
     <!-- 设置模态框（按需挂载：关闭时销毁，再次打开重新读取磁盘配置） -->

From 936358b0fbbe75370361c856319f8d06f521c9e5 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Fri, 19 Jun 2026 22:40:30 +0800
Subject: [PATCH 11/36] =?UTF-8?q?feat(ui):=20=E8=BE=93=E5=85=A5=E6=A1=86?=
 =?UTF-8?q?=E6=94=AF=E6=8C=81=20@=E5=9C=BA=E6=99=AF=20=E6=8C=87=E4=BB=A4?=
 =?UTF-8?q?=E5=88=87=E6=8D=A2=E6=BF=80=E6=B4=BB=E5=9C=BA=E6=99=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

R4：输入框输入 @ 触发场景选择弹层，支持筛选与键盘导航（↑↓/Enter/
Esc），选中后清除 @token 并激活场景。输入框上方常驻场景 chip
（📍 绿色调），点 × 关闭场景，与提示词列表的激活标记双向联动。
core 层零改动，复用现有 activeScenePromptPath 配置。
---
 .../app/src/components/chat/SceneChip.vue     |  34 +++++
 .../components/chat/SceneCommandPopover.vue   |  99 +++++++++++++
 .../app/src/components/layout/ChatPanel.vue   | 133 +++++++++++++++++-
 packages/app/src/views/ProjectView.vue        |  20 +++
 4 files changed, 281 insertions(+), 5 deletions(-)
 create mode 100644 packages/app/src/components/chat/SceneChip.vue
 create mode 100644 packages/app/src/components/chat/SceneCommandPopover.vue

diff --git a/packages/app/src/components/chat/SceneChip.vue b/packages/app/src/components/chat/SceneChip.vue
new file mode 100644
index 0000000..769669e
--- /dev/null
+++ b/packages/app/src/components/chat/SceneChip.vue
@@ -0,0 +1,34 @@
+<script setup lang="ts">
+/**
+ * 场景激活态 chip（R4）。
+ *
+ * 与引用 SelectionChip 区分：📍 图标 + 绿色调，表示当前对话应用的场景提示词。
+ * 常驻于输入框上方，点 × 关闭场景（走 changeScene(null)）。
+ */
+defineProps<{
+  sceneName: string
+}>()
+
+const emit = defineEmits<{
+  remove: []
+}>()
+</script>
+
+<template>
+  <div
+    class="inline-flex max-w-full items-center gap-1.5 rounded-md border border-green-300 bg-green-50 px-2 py-1 text-xs text-green-700"
+  >
+    <span class="shrink-0">📍</span>
+    <span class="truncate font-medium">{{ sceneName }}</span>
+    <button
+      type="button"
+      class="shrink-0 rounded p-0.5 text-green-500 transition-colors hover:bg-green-200 hover:text-green-800"
+      title="关闭场景"
+      @click="emit('remove')"
+    >
+      <svg class="h-3 w-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2.5" d="M6 18L18 6M6 6l12 12" />
+      </svg>
+    </button>
+  </div>
+</template>
diff --git a/packages/app/src/components/chat/SceneCommandPopover.vue b/packages/app/src/components/chat/SceneCommandPopover.vue
new file mode 100644
index 0000000..6746465
--- /dev/null
+++ b/packages/app/src/components/chat/SceneCommandPopover.vue
@@ -0,0 +1,99 @@
+<script setup lang="ts">
+import { computed, watch } from 'vue'
+import type { ProjectFileNodeView } from '@novai/core/services/types'
+
+/**
+ * 场景指令弹层（R4）。
+ *
+ * 输入框输入 @ 后弹出，列出 prompts/scenes/ 下的场景提示词供单选激活。
+ * 专用组件，不与 R6 的 /提取要素 多选弹层共用（交互差异大）。
+ *
+ * 键盘导航由父组件（ChatPanel）在 keydown 时调用 moveUp/moveDown/confirm/cancel；
+ * 鼠标点击直接选中。
+ */
+const props = defineProps<{
+  /** 场景提示词列表（prompts/scenes/*.md） */
+  scenes: ProjectFileNodeView[]
+  /** 当前激活的场景路径，列表中高亮标记 */
+  activeScenePath: string | null
+  /** 筛选词（@ 后用户输入的文字） */
+  query: string
+}>()
+
+const emit = defineEmits<{
+  /** 选中场景（path） */
+  select: [path: string]
+  /** 关闭弹层（Esc / 失焦 / 选中后） */
+  close: []
+}>()
+
+/** 按 query 过滤场景名称（不区分大小写，去 .md 扩展名匹配） */
+const filteredScenes = computed(() => {
+  const q = props.query.trim().toLowerCase()
+  if (!q) return props.scenes
+  return props.scenes.filter((s) => s.name.replace(/\.md$/i, '').toLowerCase().includes(q))
+})
+
+/** 当前高亮项索引（仅键盘导航用） */
+let highlightIndex = 0
+
+/** query 或列表变化时重置高亮到第一项 */
+watch(
+  () => [props.query, props.scenes.length] as const,
+  () => {
+    highlightIndex = 0
+  },
+)
+
+defineExpose({
+  /** 键盘 ↑：高亮上移（循环） */
+  moveUp() {
+    if (filteredScenes.value.length === 0) return
+    highlightIndex = (highlightIndex - 1 + filteredScenes.value.length) % filteredScenes.value.length
+  },
+  /** 键盘 ↓：高亮下移（循环） */
+  moveDown() {
+    if (filteredScenes.value.length === 0) return
+    highlightIndex = (highlightIndex + 1) % filteredScenes.value.length
+  },
+  /** 键盘 Enter：选中当前高亮项 */
+  confirm() {
+    const scene = filteredScenes.value[highlightIndex]
+    if (scene) emit('select', scene.path)
+  },
+})
+
+function displayName(name: string): string {
+  return name.replace(/\.md$/i, '')
+}
+</script>
+
+<template>
+  <div
+    class="absolute bottom-full left-0 z-50 mb-1 w-64 overflow-hidden rounded-lg border border-gray-200 bg-white shadow-lg"
+  >
+    <ul v-if="filteredScenes.length > 0" class="max-h-60 overflow-y-auto py-1">
+      <li v-for="(scene, index) in filteredScenes" :key="scene.path">
+        <button
+          type="button"
+          :class="[
+            'flex w-full items-center gap-2 px-3 py-2 text-left text-sm transition-colors',
+            index === highlightIndex ? 'bg-blue-50 text-blue-700' : 'text-gray-700 hover:bg-gray-50',
+          ]"
+          @click="emit('select', scene.path)"
+        >
+          <span class="shrink-0">🎬</span>
+          <span class="flex-1 truncate">{{ displayName(scene.name) }}</span>
+          <span
+            v-if="scene.path === activeScenePath"
+            class="shrink-0 text-xs text-green-500"
+            title="当前激活"
+          >●</span>
+        </button>
+      </li>
+    </ul>
+    <div v-else class="px-3 py-4 text-center text-xs text-gray-400">
+      {{ query ? '没有匹配的场景' : '暂无场景提示词' }}
+    </div>
+  </div>
+</template>
diff --git a/packages/app/src/components/layout/ChatPanel.vue b/packages/app/src/components/layout/ChatPanel.vue
index 27e748e..4247297 100644
--- a/packages/app/src/components/layout/ChatPanel.vue
+++ b/packages/app/src/components/layout/ChatPanel.vue
@@ -1,9 +1,12 @@
 <script setup lang="ts">
 import { computed, nextTick, ref, watch } from 'vue'
+import type { ProjectFileNodeView } from '@novai/core/services/types'
 import { useChatStore } from '../../stores/chat'
 import { shouldSubmitOnEnter } from '../../composables/keyboard'
 import MessageItem from '../chat/MessageItem.vue'
 import SelectionChip from '../chat/SelectionChip.vue'
+import SceneChip from '../chat/SceneChip.vue'
+import SceneCommandPopover from '../chat/SceneCommandPopover.vue'
 
 /** 选中引用的数据结构，与 ContentPanel emit 的 selectQuote payload 一致 */
 type SelectionQuote = {
@@ -17,6 +20,12 @@ const props = defineProps<{
   isSidebarOpen: boolean
   isContentPanelOpen: boolean
   quote: SelectionQuote | null
+  /** 场景提示词列表（prompts/scenes/*.md），供 @ 指令选择 */
+  scenes: ProjectFileNodeView[]
+  /** 当前激活的场景路径，null 表示未激活 */
+  activeScenePromptPath: string | null
+  /** 当前激活场景的显示名（已去扩展名），chip 展示用 */
+  activeSceneName: string | null
 }>()
 
 const emit = defineEmits<{
@@ -24,6 +33,8 @@ const emit = defineEmits<{
   toggleContentPanel: []
   toggleMobileSidebar: []
   clearQuote: []
+  /** 切换激活场景，path 为 null 表示关闭 */
+  changeScene: [path: string | null]
 }>()
 
 const chatStore = useChatStore()
@@ -79,6 +90,29 @@ function handleStop() {
 }
 
 function handleKeydown(event: KeyboardEvent) {
+  // @场景 弹层打开时：拦截导航键交给弹层
+  if (isSceneCommandOpen.value && scenePopoverRef.value) {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault()
+      scenePopoverRef.value.moveDown()
+      return
+    }
+    if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      scenePopoverRef.value.moveUp()
+      return
+    }
+    if (event.key === 'Enter' && !event.shiftKey) {
+      event.preventDefault()
+      scenePopoverRef.value.confirm()
+      return
+    }
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      handleCloseSceneCommand()
+      return
+    }
+  }
   // Enter 发送，Shift+Enter 换行
   if (shouldSubmitOnEnter(event)) {
     event.preventDefault()
@@ -91,6 +125,79 @@ function autoResize(event: Event) {
   textarea.style.height = 'auto'
   textarea.style.height = `${Math.min(textarea.scrollHeight, 200)}px`
 }
+
+/** textarea input 统一入口：自适应高度 + @场景 指令检测（R4） */
+function onTextareaInput(event: Event) {
+  autoResize(event)
+  detectSceneCommand()
+}
+
+// ===== R4：@场景 指令检测 =====
+
+/** @场景 弹层是否打开 */
+const isSceneCommandOpen = ref(false)
+/** @ 后的筛选词 */
+const sceneQuery = ref('')
+/** 弹层组件引用（键盘导航用） */
+const scenePopoverRef = ref<InstanceType<typeof SceneCommandPopover> | null>(null)
+
+/**
+ * 匹配光标前最近的 @ 指令。
+ * 规则：@ 前是行首或空白，@ 后到光标间不含空格/换行/@。
+ * 捕获组即筛选词（可能为空字符串）。
+ */
+const SCENE_COMMAND_RE = /(?:^|\s)@([^\s@]*)$/
+
+/**
+ * input 回调里调用：取光标位置，检测是否处于 @ 指令态。
+ * 命中则打开弹层并设置 query；否则关闭。
+ */
+function detectSceneCommand() {
+  const textarea = textareaRef.value
+  if (!textarea) {
+    isSceneCommandOpen.value = false
+    return
+  }
+  const cursor = textarea.selectionStart ?? 0
+  const beforeCursor = inputText.value.slice(0, cursor)
+  const match = SCENE_COMMAND_RE.exec(beforeCursor)
+  if (match) {
+    sceneQuery.value = match[1]
+    isSceneCommandOpen.value = props.scenes.length > 0
+  } else {
+    isSceneCommandOpen.value = false
+  }
+}
+
+/**
+ * 选中场景后：清除输入框里的 @token（含筛选词），激活场景，关闭弹层。
+ */
+function handleSelectScene(path: string) {
+  const textarea = textareaRef.value
+  if (textarea) {
+    const cursor = textarea.selectionStart ?? 0
+    const beforeCursor = inputText.value.slice(0, cursor)
+    const afterCursor = inputText.value.slice(cursor)
+    // 去掉匹配的 @token（含其前导的一个空白，若是行首则只去 @token）
+    const cleaned = beforeCursor.replace(SCENE_COMMAND_RE, '')
+    inputText.value = cleaned + afterCursor
+    // 光标移到清除点
+    nextTick(() => {
+      if (textareaRef.value) {
+        textareaRef.value.selectionStart = cleaned.length
+        textareaRef.value.selectionEnd = cleaned.length
+        textareaRef.value.focus()
+      }
+    })
+  }
+  isSceneCommandOpen.value = false
+  sceneQuery.value = ''
+  emit('changeScene', path)
+}
+
+function handleCloseSceneCommand() {
+  isSceneCommandOpen.value = false
+}
 </script>
 
 <template>
@@ -173,23 +280,39 @@ function autoResize(event: Event) {
     <!-- 输入区域 -->
     <div class="border-t border-gray-200 bg-white px-4 py-3">
       <div class="mx-auto max-w-3xl">
-        <!-- 选中引用 chip -->
-        <div v-if="quote" class="mb-2">
+        <!-- chip 区：引用 chip + 场景 chip -->
+        <div v-if="quote || activeSceneName" class="mb-2 flex flex-wrap items-center gap-2">
           <SelectionChip
+            v-if="quote"
             :file-name="quote.name"
             :text="quote.text"
             @remove="emit('clearQuote')"
           />
+          <SceneChip
+            v-if="activeSceneName"
+            :scene-name="activeSceneName"
+            @remove="emit('changeScene', null)"
+          />
         </div>
-        <div class="flex gap-2">
+        <div class="relative flex gap-2">
+          <!-- @场景 指令弹层（R4） -->
+          <SceneCommandPopover
+            v-if="isSceneCommandOpen"
+            ref="scenePopoverRef"
+            :scenes="scenes"
+            :active-scene-path="activeScenePromptPath"
+            :query="sceneQuery"
+            @select="handleSelectScene"
+            @close="handleCloseSceneCommand"
+          />
           <textarea
             ref="textareaRef"
             v-model="inputText"
             class="flex-1 resize-none rounded-lg border border-gray-300 px-4 py-2.5 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
-            placeholder="输入创作指令... (Enter 发送，Shift+Enter 换行)"
+            placeholder="输入创作指令... (Enter 发送，Shift+Enter 换行；输入 @ 切换场景)"
             rows="1"
             @keydown="handleKeydown"
-            @input="autoResize"
+            @input="onTextareaInput"
           />
           <button
             v-if="isStopping"
diff --git a/packages/app/src/views/ProjectView.vue b/packages/app/src/views/ProjectView.vue
index a6d46af..914fd66 100644
--- a/packages/app/src/views/ProjectView.vue
+++ b/packages/app/src/views/ProjectView.vue
@@ -12,6 +12,7 @@ import SettingsModal from '../components/settings/SettingsModal.vue'
 import Toast from '../components/ui/Toast.vue'
 import FirstTimeGuide from '../components/ui/FirstTimeGuide.vue'
 import type { Category } from '../constants/category'
+import { pickDirectoryChildren } from '../utils/file-tree'
 
 const route = useRoute()
 const router = useRouter()
@@ -55,6 +56,21 @@ const activeScenePromptPath = computed(() => {
   return projectStore.currentProject?.config.settings.activeScenePromptPath ?? null
 })
 
+/** 场景提示词列表（prompts/scenes/*.md，拉平），供 ChatPanel 的 @ 指令选择（R4） */
+const sceneList = computed(() => {
+  const files = projectStore.currentProject?.files ?? []
+  return pickDirectoryChildren(files, 'prompts/scenes').filter(
+    (n) => n.kind === 'file' && n.path.endsWith('.md'),
+  )
+})
+
+/** 当前激活场景的显示名（去 .md 扩展名），ChatPanel 的场景 chip 展示用（R4） */
+const activeSceneName = computed(() => {
+  if (!activeScenePromptPath.value) return null
+  const node = sceneList.value.find((n) => n.path === activeScenePromptPath.value)
+  return node ? node.name.replace(/\.md$/i, '') : null
+})
+
 onMounted(async () => {
   // 如果没有当前项目，尝试恢复
   if (!projectStore.currentProject) {
@@ -239,10 +255,14 @@ async function handleElementsWritten() {
       :is-sidebar-open="isCategoryOpen"
       :is-content-panel-open="isContentPanelOpen"
       :quote="selectionQuote"
+      :scenes="sceneList"
+      :active-scene-prompt-path="activeScenePromptPath"
+      :active-scene-name="activeSceneName"
       @toggle-sidebar="toggleSidebar"
       @toggle-content-panel="toggleContentPanel"
       @toggle-mobile-sidebar="toggleMobileSidebar"
       @clear-quote="handleClearQuote"
+      @change-scene="handleChangeScene"
     >
       <!-- 首次使用引导 -->
       <template #guide>

From 8e6c43275ff606ee9a9b4d7815bbd3b5b45d9dad Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Fri, 19 Jun 2026 22:51:13 +0800
Subject: [PATCH 12/36] =?UTF-8?q?docs(docs):=20=E5=90=8C=E6=AD=A5=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E5=AD=90=E6=A8=A1=E5=9D=97=E5=BC=95=E7=94=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

同步 R7/Agent停止/要素LLM/章节数修复的落地状态到文档子模块，
并修正 INTERFACE.md 要素提取状态描述。
---
 INTERFACE.md | 2 +-
 docs         | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/INTERFACE.md b/INTERFACE.md
index b74e035..13002b4 100644
--- a/INTERFACE.md
+++ b/INTERFACE.md
@@ -317,7 +317,7 @@ function resolvePreferredPath(changes: ChangedFileView[]) {
 - `changedFiles` 仍是 service 层推导，不是工具层结构化输出。
 - Agent 会话还没有持久化。
 - `RagSearch` 已作为正式 Agent 工具接入，但真实创作任务中的触发率和召回质量仍需验证。
-- 要素提取已能规则型提取并写入 `elements/`，但还不是 LLM 结构化提取，也缺少用户确认、去重合并和覆盖策略。
+- 要素提取已收敛为 LLM 唯一路径（不再有正则降级）并写入 `elements/`，但还缺少用户确认、去重合并和覆盖策略。
 - 旧的 `pendingFileChange / confirmPendingFileChange` 确认流程代码仍有残留，但当前主工作流没有接入。
 
 ## 协作规则
diff --git a/docs b/docs
index c12f07f..d80ad2f 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit c12f07f39fd32c74771fdd05e13a599849499f6c
+Subproject commit d80ad2fc88c1a480e9955e2eef5b839d88b5912c

From 483fae7a8aa4d91ac49d718ec09e4289452d70a5 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Fri, 19 Jun 2026 23:10:18 +0800
Subject: [PATCH 13/36] =?UTF-8?q?feat(ui):=20=E5=AE=9E=E7=8E=B0=20/?=
 =?UTF-8?q?=E6=8F=90=E5=8F=96=E8=A6=81=E7=B4=A0=20=E6=96=9C=E6=9D=A0?=
 =?UTF-8?q?=E6=8C=87=E4=BB=A4=E4=B8=8E=E5=91=BD=E4=BB=A4=E8=8F=9C=E5=8D=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

R6：输入 / 弹出斜杠命令菜单（SlashCommandMenu），列出可用命令，
支持筛选与键盘导航。选中「提取要素」后展开章节多选
（ChapterPicker），逐章提取要素并在对话流展示候选预览，确认后
写入 elements/*.md。多章节提取时同类型同名候选项智能合并。

新增命令注册表 slash-commands.ts，后续可扩展 /校对、/整理 等。
提取流程状态独立 useElementExtraction composable 管理，不污染
Agent 对话流。移除 ContentPanel 原要素提取按钮区。core 层零改动，
复用已解耦的 previewElementExtraction / writeExtractedElements。
---
 .../app/src/components/chat/ChapterPicker.vue | 128 +++++++++++
 .../components/chat/ExtractionFlowPanel.vue   | 202 +++++++++++++++++
 .../src/components/chat/SlashCommandMenu.vue  |  90 ++++++++
 .../app/src/components/layout/ChatPanel.vue   | 207 ++++++++++++++---
 .../src/components/layout/ContentPanel.vue    | 209 +-----------------
 .../src/composables/useElementExtraction.ts   | 186 ++++++++++++++++
 packages/app/src/constants/slash-commands.ts  |  29 +++
 packages/app/src/views/ProjectView.vue        |  11 +-
 8 files changed, 822 insertions(+), 240 deletions(-)
 create mode 100644 packages/app/src/components/chat/ChapterPicker.vue
 create mode 100644 packages/app/src/components/chat/ExtractionFlowPanel.vue
 create mode 100644 packages/app/src/components/chat/SlashCommandMenu.vue
 create mode 100644 packages/app/src/composables/useElementExtraction.ts
 create mode 100644 packages/app/src/constants/slash-commands.ts

diff --git a/packages/app/src/components/chat/ChapterPicker.vue b/packages/app/src/components/chat/ChapterPicker.vue
new file mode 100644
index 0000000..f8d6324
--- /dev/null
+++ b/packages/app/src/components/chat/ChapterPicker.vue
@@ -0,0 +1,128 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import type { ProjectFileNodeView } from '@novai/core/services/types'
+
+/**
+ * 章节多选弹层（R6）。
+ *
+ * 输入框输入 /提取要素 后触发，供用户多选要提取要素的章节。
+ * 与 SceneCommandPopover（单选）交互差异大，独立组件。
+ */
+const props = defineProps<{
+  /** 章节列表（chapters/*.txt|.md，已扁平化） */
+  chapters: ProjectFileNodeView[]
+}>()
+
+const emit = defineEmits<{
+  /** 确认提取，返回选中章节的 path+name */
+  confirm: [chapters: { path: string; name: string }[]]
+  /** 取消 */
+  cancel: []
+}>()
+
+const searchQuery = ref('')
+const selectedPaths = ref<Set<string>>(new Set())
+
+/** 按搜索词过滤章节名（不区分大小写） */
+const filteredChapters = computed(() => {
+  const q = searchQuery.value.trim().toLowerCase()
+  if (!q) return props.chapters
+  return props.chapters.filter((c) => c.name.toLowerCase().includes(q))
+})
+
+const selectedCount = computed(() => selectedPaths.value.size)
+
+function toggleChapter(path: string) {
+  const next = new Set(selectedPaths.value)
+  if (next.has(path)) {
+    next.delete(path)
+  } else {
+    next.add(path)
+  }
+  selectedPaths.value = next
+}
+
+function handleConfirm() {
+  const picked = props.chapters
+    .filter((c) => selectedPaths.value.has(c.path))
+    .map((c) => ({ path: c.path, name: c.name }))
+  if (picked.length === 0) return
+  emit('confirm', picked)
+  // 重置选择
+  selectedPaths.value = new Set()
+  searchQuery.value = ''
+}
+
+function handleCancel() {
+  emit('cancel')
+  selectedPaths.value = new Set()
+  searchQuery.value = ''
+}
+</script>
+
+<template>
+  <div
+    class="absolute bottom-full left-0 z-50 mb-1 w-72 overflow-hidden rounded-lg border border-gray-200 bg-white shadow-lg"
+  >
+    <!-- 搜索框 -->
+    <div class="border-b border-gray-100 p-2">
+      <input
+        v-model="searchQuery"
+        type="text"
+        class="w-full rounded-md border border-gray-200 px-2 py-1.5 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+        placeholder="筛选章节..."
+        autofocus
+      />
+    </div>
+
+    <!-- 章节列表 -->
+    <ul v-if="filteredChapters.length > 0" class="max-h-60 overflow-y-auto py-1">
+      <li v-for="chapter in filteredChapters" :key="chapter.path">
+        <button
+          type="button"
+          :class="[
+            'flex w-full items-center gap-2 px-3 py-2 text-left text-sm transition-colors',
+            selectedPaths.has(chapter.path) ? 'bg-blue-50 text-blue-700' : 'text-gray-700 hover:bg-gray-50',
+          ]"
+          @click="toggleChapter(chapter.path)"
+        >
+          <span
+            :class="[
+              'flex h-4 w-4 shrink-0 items-center justify-center rounded border transition-colors',
+              selectedPaths.has(chapter.path)
+                ? 'border-blue-500 bg-blue-500 text-white'
+                : 'border-gray-300 bg-white',
+            ]"
+          >
+            <svg v-if="selectedPaths.has(chapter.path)" class="h-3 w-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="3" d="M5 13l4 4L19 7" />
+            </svg>
+          </span>
+          <span class="flex-1 truncate">{{ chapter.name }}</span>
+        </button>
+      </li>
+    </ul>
+    <div v-else class="px-3 py-4 text-center text-xs text-gray-400">
+      {{ chapters.length === 0 ? '暂无章节' : '没有匹配的章节' }}
+    </div>
+
+    <!-- 底部操作 -->
+    <div class="flex items-center justify-end gap-2 border-t border-gray-100 p-2">
+      <button
+        type="button"
+        class="rounded-md px-3 py-1.5 text-xs font-medium text-gray-600 transition-colors hover:bg-gray-100"
+        @click="handleCancel"
+      >
+        取消
+      </button>
+      <button
+        type="button"
+        class="rounded-md bg-blue-600 px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-blue-700 disabled:opacity-50"
+        :disabled="selectedCount === 0"
+        @click="handleConfirm"
+      >
+        确认提取{{ selectedCount > 0 ? `(${selectedCount})` : '' }}
+      </button>
+    </div>
+  </div>
+</template>
diff --git a/packages/app/src/components/chat/ExtractionFlowPanel.vue b/packages/app/src/components/chat/ExtractionFlowPanel.vue
new file mode 100644
index 0000000..e3a13dc
--- /dev/null
+++ b/packages/app/src/components/chat/ExtractionFlowPanel.vue
@@ -0,0 +1,202 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import type {
+  ElementExtractionItemView,
+  ElementExtractionResultView,
+  ElementWriteResultView,
+} from '@novai/core/services/types'
+import type { ExtractionPhase } from '../../composables/useElementExtraction'
+import { countExtractionItems } from '../../composables/useElementExtraction'
+
+/**
+ * 要素提取流程面板（R6）。
+ *
+ * 按 phase 渲染：提取中（进度）→ 预览（候选分组+确认/取消）→ 完成（写入统计）→ 错误。
+ * 数据由父组件从 useElementExtraction composable 传入。
+ */
+const props = defineProps<{
+  phase: ExtractionPhase
+  extractionResult: ElementExtractionResultView | null
+  writeResult: ElementWriteResultView | null
+  progressCurrent: number
+  progressTotal: number
+  progressChapterName: string
+  errorMessage: string
+}>()
+
+const emit = defineEmits<{
+  confirm: []
+  cancel: []
+  dismiss: []
+}>()
+
+const isWriting = computed(() => props.phase === 'writing')
+
+const totalCandidates = computed(() =>
+  props.extractionResult ? countExtractionItems(props.extractionResult) : 0,
+)
+
+/** 六类配置：key + 中文名 + 图标 */
+const BUCKETS = [
+  { key: 'characters' as const, label: '人物', icon: '👤' },
+  { key: 'locations' as const, label: '地点', icon: '📍' },
+  { key: 'entities' as const, label: '实体', icon: '📦' },
+  { key: 'timeline' as const, label: '时间线', icon: '⏰' },
+  { key: 'plots' as const, label: '剧情', icon: '📖' },
+  { key: 'worldbuilding' as const, label: '世界观', icon: '🌍' },
+]
+
+/** 展开的分组（默认全部展开） */
+const expandedGroups = ref<Set<string>>(new Set(BUCKETS.map((b) => b.key)))
+
+function toggleGroup(key: string) {
+  const next = new Set(expandedGroups.value)
+  if (next.has(key)) {
+    next.delete(key)
+  } else {
+    next.add(key)
+  }
+  expandedGroups.value = next
+}
+
+function getItems(result: ElementExtractionResultView, key: keyof ElementExtractionResultView): ElementExtractionItemView[] {
+  return result[key] as ElementExtractionItemView[]
+}
+
+const progressPercent = computed(() => {
+  if (props.progressTotal === 0) return 0
+  return Math.round((props.progressCurrent / props.progressTotal) * 100)
+})
+</script>
+
+<template>
+  <div class="mx-auto mb-2 max-w-3xl rounded-lg border border-gray-200 bg-gray-50">
+    <!-- 提取中 -->
+    <div v-if="phase === 'extracting'" class="p-4">
+      <div class="mb-2 flex items-center gap-2">
+        <svg class="h-4 w-4 animate-spin text-blue-500" fill="none" viewBox="0 0 24 24">
+          <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" />
+          <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+        </svg>
+        <p class="text-sm font-medium text-gray-700">
+          正在提取要素（{{ progressCurrent }}/{{ progressTotal }}）
+        </p>
+      </div>
+      <p class="mb-2 truncate text-xs text-gray-500">{{ progressChapterName }}</p>
+      <div class="h-1.5 w-full overflow-hidden rounded-full bg-gray-200">
+        <div
+          class="h-full bg-blue-500 transition-all duration-300"
+          :style="{ width: progressPercent + '%' }"
+        />
+      </div>
+    </div>
+
+    <!-- 预览候选 -->
+    <div v-else-if="phase === 'preview' || phase === 'writing'" class="p-4">
+      <div class="mb-3 flex items-center justify-between">
+        <p class="text-sm font-medium text-gray-700">
+          已提取 {{ totalCandidates }} 个候选要素
+        </p>
+        <span v-if="phase === 'writing'" class="text-xs text-gray-400">写入中...</span>
+      </div>
+
+      <div v-if="extractionResult" class="space-y-2">
+        <div v-for="bucket in BUCKETS" :key="bucket.key">
+          <button
+            v-if="getItems(extractionResult, bucket.key).length > 0"
+            type="button"
+            class="flex w-full items-center gap-1.5 py-1 text-left text-xs font-medium text-gray-600"
+            @click="toggleGroup(bucket.key)"
+          >
+            <span class="shrink-0">{{ bucket.icon }}</span>
+            <span>{{ bucket.label }}</span>
+            <span class="text-gray-400">({{ getItems(extractionResult, bucket.key).length }})</span>
+            <svg
+              class="ml-auto h-3 w-3 text-gray-400 transition-transform"
+              :class="{ 'rotate-180': expandedGroups.has(bucket.key) }"
+              fill="none" stroke="currentColor" viewBox="0 0 24 24"
+            >
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7" />
+            </svg>
+          </button>
+          <ul
+            v-if="expandedGroups.has(bucket.key) && getItems(extractionResult, bucket.key).length > 0"
+            class="ml-5 space-y-1 border-l border-gray-200 pl-3"
+          >
+            <li
+              v-for="item in getItems(extractionResult, bucket.key)"
+              :key="item.name"
+              class="py-0.5"
+            >
+              <p class="text-xs font-medium text-gray-700">{{ item.name }}</p>
+              <p v-if="item.summary" class="truncate text-xs text-gray-500">{{ item.summary }}</p>
+            </li>
+          </ul>
+        </div>
+      </div>
+
+      <div v-if="phase === 'preview'" class="mt-3 flex items-center justify-end gap-2">
+        <button
+          type="button"
+          class="rounded-md px-3 py-1.5 text-xs font-medium text-gray-600 transition-colors hover:bg-gray-200"
+          @click="emit('cancel')"
+        >
+          取消
+        </button>
+        <button
+          type="button"
+          class="rounded-md bg-green-600 px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-green-700"
+          @click="emit('confirm')"
+        >
+          确认写入
+        </button>
+      </div>
+    </div>
+
+    <!-- 写入完成 -->
+    <div v-else-if="phase === 'done' && writeResult" class="p-4">
+      <div class="mb-2 flex items-center gap-2">
+        <svg class="h-4 w-4 text-green-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7" />
+        </svg>
+        <p class="text-sm font-medium text-gray-700">要素写入完成</p>
+      </div>
+      <div class="ml-6 space-y-0.5 text-xs text-gray-500">
+        <p>✅ 新增 {{ writeResult.created.length }} 个</p>
+        <p>🔄 更新 {{ writeResult.updated.length }} 个</p>
+        <p v-if="writeResult.skipped.length > 0">⏭️ 跳过 {{ writeResult.skipped.length }} 个（无变化）</p>
+        <p v-if="writeResult.staleIndex" class="mt-1 text-amber-600">⚠️ RAG 索引已标记为过期，可在设置中重建</p>
+      </div>
+      <div class="mt-3 flex justify-end">
+        <button
+          type="button"
+          class="rounded-md px-3 py-1.5 text-xs font-medium text-gray-600 transition-colors hover:bg-gray-200"
+          @click="emit('dismiss')"
+        >
+          关闭
+        </button>
+      </div>
+    </div>
+
+    <!-- 错误 -->
+    <div v-else-if="phase === 'error'" class="p-4">
+      <div class="mb-2 flex items-center gap-2">
+        <svg class="h-4 w-4 text-red-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01M5.07 19h13.86c1.54 0 2.5-1.67 1.73-3L13.73 4a2 2 0 00-3.46 0L3.34 16c-.77 1.33.19 3 1.73 3z" />
+        </svg>
+        <p class="text-sm font-medium text-red-600">提取失败</p>
+      </div>
+      <p class="ml-6 text-xs text-gray-500">{{ errorMessage }}</p>
+      <p class="ml-6 mt-1 text-xs text-gray-400">请检查设置页的 LLM 配置是否正确。</p>
+      <div class="mt-3 flex justify-end">
+        <button
+          type="button"
+          class="rounded-md px-3 py-1.5 text-xs font-medium text-gray-600 transition-colors hover:bg-gray-200"
+          @click="emit('dismiss')"
+        >
+          关闭
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/packages/app/src/components/chat/SlashCommandMenu.vue b/packages/app/src/components/chat/SlashCommandMenu.vue
new file mode 100644
index 0000000..abee991
--- /dev/null
+++ b/packages/app/src/components/chat/SlashCommandMenu.vue
@@ -0,0 +1,90 @@
+<script setup lang="ts">
+import { computed, watch } from 'vue'
+import { SLASH_COMMANDS, type SlashCommandId } from '../../constants/slash-commands'
+
+/**
+ * 斜杠命令菜单（R6）。
+ *
+ * 输入框输入 / 后弹出，列出可用斜杠命令（如 /提取要素）。
+ * 选中后由父组件根据命令 id 展开对应的二级界面。
+ * 与 @场景 弹层同构：单选 + 键盘导航（defineExpose moveUp/moveDown/confirm）。
+ */
+const props = defineProps<{
+  /** 筛选词（/ 后用户输入的文字） */
+  query: string
+}>()
+
+const emit = defineEmits<{
+  /** 选中命令 */
+  select: [id: SlashCommandId]
+  /** 关闭（Esc / 失焦 / 选中后） */
+  close: []
+}>()
+
+/** 按 query 过滤命令（匹配 label 或 description，不区分大小写） */
+const filteredCommands = computed(() => {
+  const q = props.query.trim().toLowerCase()
+  if (!q) return SLASH_COMMANDS
+  return SLASH_COMMANDS.filter(
+    (c) =>
+      c.label.toLowerCase().includes(q) ||
+      c.description.toLowerCase().includes(q),
+  )
+})
+
+/** 当前高亮项索引（键盘导航用） */
+let highlightIndex = 0
+
+watch(
+  () => props.query,
+  () => {
+    highlightIndex = 0
+  },
+)
+
+defineExpose({
+  moveUp() {
+    if (filteredCommands.value.length === 0) return
+    highlightIndex = (highlightIndex - 1 + filteredCommands.value.length) % filteredCommands.value.length
+  },
+  moveDown() {
+    if (filteredCommands.value.length === 0) return
+    highlightIndex = (highlightIndex + 1) % filteredCommands.value.length
+  },
+  confirm() {
+    const command = filteredCommands.value[highlightIndex]
+    if (command) emit('select', command.id)
+  },
+})
+</script>
+
+<template>
+  <div
+    class="absolute bottom-full left-0 z-50 mb-1 w-72 overflow-hidden rounded-lg border border-gray-200 bg-white shadow-lg"
+  >
+    <div class="border-b border-gray-100 px-3 py-1.5">
+      <p class="text-xs font-medium uppercase tracking-wide text-gray-400">命令</p>
+    </div>
+    <ul v-if="filteredCommands.length > 0" class="max-h-60 overflow-y-auto py-1">
+      <li v-for="(command, index) in filteredCommands" :key="command.id">
+        <button
+          type="button"
+          :class="[
+            'flex w-full items-start gap-2 px-3 py-2 text-left text-sm transition-colors',
+            index === highlightIndex ? 'bg-blue-50 text-blue-700' : 'text-gray-700 hover:bg-gray-50',
+          ]"
+          @click="emit('select', command.id)"
+        >
+          <span class="mt-0.5 shrink-0">{{ command.icon }}</span>
+          <div class="min-w-0 flex-1">
+            <p class="font-medium">{{ command.label }}</p>
+            <p class="truncate text-xs text-gray-400">{{ command.description }}</p>
+          </div>
+        </button>
+      </li>
+    </ul>
+    <div v-else class="px-3 py-4 text-center text-xs text-gray-400">
+      没有匹配的命令
+    </div>
+  </div>
+</template>
diff --git a/packages/app/src/components/layout/ChatPanel.vue b/packages/app/src/components/layout/ChatPanel.vue
index 4247297..2eb7da4 100644
--- a/packages/app/src/components/layout/ChatPanel.vue
+++ b/packages/app/src/components/layout/ChatPanel.vue
@@ -3,10 +3,15 @@ import { computed, nextTick, ref, watch } from 'vue'
 import type { ProjectFileNodeView } from '@novai/core/services/types'
 import { useChatStore } from '../../stores/chat'
 import { shouldSubmitOnEnter } from '../../composables/keyboard'
+import { useElementExtraction, type ChapterPick } from '../../composables/useElementExtraction'
 import MessageItem from '../chat/MessageItem.vue'
 import SelectionChip from '../chat/SelectionChip.vue'
 import SceneChip from '../chat/SceneChip.vue'
 import SceneCommandPopover from '../chat/SceneCommandPopover.vue'
+import ChapterPicker from '../chat/ChapterPicker.vue'
+import ExtractionFlowPanel from '../chat/ExtractionFlowPanel.vue'
+import SlashCommandMenu from '../chat/SlashCommandMenu.vue'
+import type { SlashCommandId } from '../../constants/slash-commands'
 
 /** 选中引用的数据结构，与 ContentPanel emit 的 selectQuote payload 一致 */
 type SelectionQuote = {
@@ -26,6 +31,8 @@ const props = defineProps<{
   activeScenePromptPath: string | null
   /** 当前激活场景的显示名（已去扩展名），chip 展示用 */
   activeSceneName: string | null
+  /** 章节列表（chapters/*.txt|.md），供 /提取要素 选择（R6） */
+  chapters: ProjectFileNodeView[]
 }>()
 
 const emit = defineEmits<{
@@ -35,6 +42,8 @@ const emit = defineEmits<{
   clearQuote: []
   /** 切换激活场景，path 为 null 表示关闭 */
   changeScene: [path: string | null]
+  /** 要素写入完成，通知 ProjectView 刷新文件树（R6） */
+  elementsWritten: []
 }>()
 
 const chatStore = useChatStore()
@@ -90,6 +99,37 @@ function handleStop() {
 }
 
 function handleKeydown(event: KeyboardEvent) {
+  // /提取要素 章节选择打开时：仅拦截 Esc（选择走鼠标点击）
+  if (isChapterPickerOpen.value) {
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      isChapterPickerOpen.value = false
+      return
+    }
+  }
+  // 斜杠命令菜单打开时：拦截导航键交给菜单
+  if (isSlashMenuOpen.value && slashMenuRef.value) {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault()
+      slashMenuRef.value.moveDown()
+      return
+    }
+    if (event.key === 'ArrowUp') {
+      event.preventDefault()
+      slashMenuRef.value.moveUp()
+      return
+    }
+    if (event.key === 'Enter' && !event.shiftKey) {
+      event.preventDefault()
+      slashMenuRef.value.confirm()
+      return
+    }
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      isSlashMenuOpen.value = false
+      return
+    }
+  }
   // @场景 弹层打开时：拦截导航键交给弹层
   if (isSceneCommandOpen.value && scenePopoverRef.value) {
     if (event.key === 'ArrowDown') {
@@ -126,10 +166,10 @@ function autoResize(event: Event) {
   textarea.style.height = `${Math.min(textarea.scrollHeight, 200)}px`
 }
 
-/** textarea input 统一入口：自适应高度 + @场景 指令检测（R4） */
+/** textarea input 统一入口：自适应高度 + 指令检测（R4 @场景 / R6 /提取要素） */
 function onTextareaInput(event: Event) {
   autoResize(event)
-  detectSceneCommand()
+  detectCommands()
 }
 
 // ===== R4：@场景 指令检测 =====
@@ -149,54 +189,129 @@ const scenePopoverRef = ref<InstanceType<typeof SceneCommandPopover> | null>(nul
 const SCENE_COMMAND_RE = /(?:^|\s)@([^\s@]*)$/
 
 /**
- * input 回调里调用：取光标位置，检测是否处于 @ 指令态。
- * 命中则打开弹层并设置 query；否则关闭。
+ * 清除光标处匹配指定正则的 token（@场景、/命令 共用）。
+ * 清除后光标回位并重新聚焦 textarea。
+ */
+function clearTokenAtCursor(re: RegExp) {
+  const textarea = textareaRef.value
+  if (!textarea) return
+  const cursor = textarea.selectionStart ?? 0
+  const beforeCursor = inputText.value.slice(0, cursor)
+  const afterCursor = inputText.value.slice(cursor)
+  const cleaned = beforeCursor.replace(re, '')
+  inputText.value = cleaned + afterCursor
+  nextTick(() => {
+    if (textareaRef.value) {
+      textareaRef.value.selectionStart = cleaned.length
+      textareaRef.value.selectionEnd = cleaned.length
+      textareaRef.value.focus()
+    }
+  })
+}
+
+/**
+ * 选中场景后：清除输入框里的 @token（含筛选词），激活场景，关闭弹层。
+ */
+function handleSelectScene(path: string) {
+  clearTokenAtCursor(SCENE_COMMAND_RE)
+  isSceneCommandOpen.value = false
+  sceneQuery.value = ''
+  emit('changeScene', path)
+}
+
+function handleCloseSceneCommand() {
+  isSceneCommandOpen.value = false
+}
+
+// ===== R6：斜杠命令菜单 / 提取要素 =====
+
+/** 斜杠命令菜单是否打开（输入 / 后弹出命令列表） */
+const isSlashMenuOpen = ref(false)
+/** / 后的筛选词 */
+const slashQuery = ref('')
+/** 斜杠命令菜单组件引用（键盘导航用） */
+const slashMenuRef = ref<InstanceType<typeof SlashCommandMenu> | null>(null)
+/** /提取要素 章节多选弹层是否打开（选中命令后展开） */
+const isChapterPickerOpen = ref(false)
+/** 提取流程状态（composable 单例） */
+const extraction = useElementExtraction()
+
+/**
+ * 匹配光标前最近的 / 命令前缀。
+ * 规则与 @场景 同构：/ 前是行首或空白，/ 后到光标间不含空格/换行/。
+ * 捕获组即筛选词（可能为空）。
  */
-function detectSceneCommand() {
+const SLASH_COMMAND_RE = /(?:^|\s)\/([^\s/]*)$/
+
+/** 指令检测入口：input 回调统一调用 */
+function detectCommands() {
   const textarea = textareaRef.value
   if (!textarea) {
     isSceneCommandOpen.value = false
+    isSlashMenuOpen.value = false
+    isChapterPickerOpen.value = false
     return
   }
   const cursor = textarea.selectionStart ?? 0
   const beforeCursor = inputText.value.slice(0, cursor)
-  const match = SCENE_COMMAND_RE.exec(beforeCursor)
-  if (match) {
-    sceneQuery.value = match[1]
+
+  // @场景、/ 命令、章节选择三层互斥，同一时刻只开一个
+  const sceneMatch = SCENE_COMMAND_RE.exec(beforeCursor)
+  const slashMatch = SLASH_COMMAND_RE.exec(beforeCursor)
+
+  if (slashMatch) {
+    slashQuery.value = slashMatch[1]
+    isSlashMenuOpen.value = true
+    isSceneCommandOpen.value = false
+    isChapterPickerOpen.value = false
+  } else if (sceneMatch) {
+    sceneQuery.value = sceneMatch[1]
     isSceneCommandOpen.value = props.scenes.length > 0
+    isSlashMenuOpen.value = false
+    isChapterPickerOpen.value = false
   } else {
     isSceneCommandOpen.value = false
+    isSlashMenuOpen.value = false
+    isChapterPickerOpen.value = false
   }
 }
 
 /**
- * 选中场景后：清除输入框里的 @token（含筛选词），激活场景，关闭弹层。
+ * 选中斜杠命令后：清除 / token，按命令类型展开二级界面。
  */
-function handleSelectScene(path: string) {
-  const textarea = textareaRef.value
-  if (textarea) {
-    const cursor = textarea.selectionStart ?? 0
-    const beforeCursor = inputText.value.slice(0, cursor)
-    const afterCursor = inputText.value.slice(cursor)
-    // 去掉匹配的 @token（含其前导的一个空白，若是行首则只去 @token）
-    const cleaned = beforeCursor.replace(SCENE_COMMAND_RE, '')
-    inputText.value = cleaned + afterCursor
-    // 光标移到清除点
-    nextTick(() => {
-      if (textareaRef.value) {
-        textareaRef.value.selectionStart = cleaned.length
-        textareaRef.value.selectionEnd = cleaned.length
-        textareaRef.value.focus()
-      }
-    })
+function handleSlashCommandSelect(id: SlashCommandId) {
+  // 清除输入框里的 / token（含筛选词）
+  clearTokenAtCursor(SLASH_COMMAND_RE)
+  isSlashMenuOpen.value = false
+  slashQuery.value = ''
+
+  if (id === 'extract') {
+    // 选中「提取要素」后展开章节多选
+    isChapterPickerOpen.value = props.chapters.length > 0
   }
-  isSceneCommandOpen.value = false
-  sceneQuery.value = ''
-  emit('changeScene', path)
 }
 
-function handleCloseSceneCommand() {
-  isSceneCommandOpen.value = false
+/**
+ * ChapterPicker 确认：启动提取流程。
+ */
+function handleChapterPickerConfirm(chapters: ChapterPick[]) {
+  isChapterPickerOpen.value = false
+  extraction.startExtraction(props.projectId, chapters)
+}
+
+function handleChapterPickerCancel() {
+  isChapterPickerOpen.value = false
+}
+
+/**
+ * 提取流程：确认写入。
+ */
+async function handleExtractionConfirm() {
+  const result = await extraction.confirmWrite()
+  if (result) {
+    // 写入成功，通知 ProjectView 刷新文件树
+    emit('elementsWritten')
+  }
 }
 </script>
 
@@ -277,6 +392,21 @@ function handleCloseSceneCommand() {
       </div>
     </div>
 
+    <!-- 要素提取流程面板（R6） -->
+    <ExtractionFlowPanel
+      v-if="extraction.phase.value !== 'idle'"
+      :phase="extraction.phase.value"
+      :extraction-result="extraction.extractionResult.value"
+      :write-result="extraction.writeResult.value"
+      :progress-current="extraction.progressCurrent.value"
+      :progress-total="extraction.progressTotal.value"
+      :progress-chapter-name="extraction.progressChapterName.value"
+      :error-message="extraction.errorMessage.value"
+      @confirm="handleExtractionConfirm"
+      @cancel="extraction.cancel()"
+      @dismiss="extraction.dismiss()"
+    />
+
     <!-- 输入区域 -->
     <div class="border-t border-gray-200 bg-white px-4 py-3">
       <div class="mx-auto max-w-3xl">
@@ -305,6 +435,21 @@ function handleCloseSceneCommand() {
             @select="handleSelectScene"
             @close="handleCloseSceneCommand"
           />
+          <!-- 斜杠命令菜单（R6） -->
+          <SlashCommandMenu
+            v-if="isSlashMenuOpen"
+            ref="slashMenuRef"
+            :query="slashQuery"
+            @select="handleSlashCommandSelect"
+            @close="isSlashMenuOpen = false"
+          />
+          <!-- /提取要素 章节多选弹层（R6） -->
+          <ChapterPicker
+            v-if="isChapterPickerOpen"
+            :chapters="chapters"
+            @confirm="handleChapterPickerConfirm"
+            @cancel="handleChapterPickerCancel"
+          />
           <textarea
             ref="textareaRef"
             v-model="inputText"
diff --git a/packages/app/src/components/layout/ContentPanel.vue b/packages/app/src/components/layout/ContentPanel.vue
index aceec8d..f523635 100644
--- a/packages/app/src/components/layout/ContentPanel.vue
+++ b/packages/app/src/components/layout/ContentPanel.vue
@@ -1,11 +1,6 @@
 <script setup lang="ts">
 import { computed, ref, watch } from 'vue'
-import { previewElementExtraction, writeExtractedElements } from '@novai/core/services/element-service'
-import type {
-  ElementExtractionResultView,
-  ElementWriteResultView,
-  FileContentView,
-} from '@novai/core/services/types'
+import type { FileContentView } from '@novai/core/services/types'
 import MarkdownRenderer from '../ui/MarkdownRenderer.vue'
 import Tooltip from '../ui/Tooltip.vue'
 import ResizeHandle from './ResizeHandle.vue'
@@ -20,7 +15,6 @@ const props = defineProps<{
 
 const emit = defineEmits<{
   close: []
-  elementsWritten: [result: ElementWriteResultView]
   save: [path: string, content: string]
   selectQuote: [payload: { path: string; name: string; text: string }]
   /** 拖拽改宽：发出 clamp 后的目标宽度（R7） */
@@ -34,20 +28,6 @@ const editDraft = ref('')
 const isSaving = ref(false)
 /** 拖拽改宽进行中（R7）：暂停 aside 过渡动画，避免宽度变化滞后于光标 */
 const isResizing = ref(false)
-const extractionStatus = ref('尚未提取要素')
-const extractionPreview = ref<ElementExtractionResultView | null>(null)
-const elementWriteResult = ref<ElementWriteResultView | null>(null)
-const isExtracting = ref(false)
-const isWritingElements = ref(false)
-
-const canExtractElements = computed(() => {
-  return Boolean(
-    props.file &&
-    props.file.path.startsWith('chapters/') &&
-    /\.(txt|md)$/i.test(props.file.name) &&
-    props.file.content.trim(),
-  )
-})
 
 const canEdit = computed(() => {
   return Boolean(props.file && isEditablePath(props.file.path))
@@ -56,29 +36,9 @@ const canEdit = computed(() => {
 /** 草稿与磁盘内容不一致时为脏，用于显示「未保存」标记 */
 const isDirty = computed(() => editDraft.value !== (props.file?.content ?? ''))
 
-const extractionCount = computed(() => {
-  if (!extractionPreview.value) {
-    return 0
-  }
-
-  return countExtractionItems(extractionPreview.value)
-})
-
-const extractedPaths = computed(() => {
-  if (!elementWriteResult.value) {
-    return []
-  }
-
-  return [
-    ...elementWriteResult.value.created,
-    ...elementWriteResult.value.updated,
-  ]
-})
-
 watch(
   () => props.file?.path,
   () => {
-    resetExtractionState()
     // 切换文件时回到预览模式并重置草稿，避免跨文件残留编辑内容
     viewMode.value = 'preview'
     editDraft.value = ''
@@ -164,76 +124,6 @@ function handleContentMouseup() {
     text: trimmed,
   })
 }
-
-async function handlePreviewElements() {
-  if (!props.file || !canExtractElements.value || isExtracting.value) {
-    return
-  }
-
-  isExtracting.value = true
-  extractionStatus.value = '正在用 AI 提取要素...'
-  elementWriteResult.value = null
-
-  try {
-    extractionPreview.value = await previewElementExtraction({
-      projectId: props.projectId,
-      chapterContent: props.file.content,
-      chapterPath: props.file.path,
-    })
-
-    extractionStatus.value = extractionCount.value > 0
-      ? `已提取 ${extractionCount.value} 个候选要素`
-      : '未提取到可写入的要素'
-  } catch (error) {
-    const message = error instanceof Error ? error.message : '要素提取失败'
-    extractionStatus.value = `AI 提取失败：${message}。请检查设置页的 LLM 配置。`
-  } finally {
-    isExtracting.value = false
-  }
-}
-
-async function handleWriteElements() {
-  if (!extractionPreview.value || isWritingElements.value) {
-    return
-  }
-
-  isWritingElements.value = true
-  extractionStatus.value = '正在写入要素文件...'
-
-  try {
-    elementWriteResult.value = await writeExtractedElements({
-      projectId: props.projectId,
-      extraction: extractionPreview.value,
-    })
-
-    const changedCount = elementWriteResult.value.created.length + elementWriteResult.value.updated.length
-    extractionStatus.value = changedCount > 0
-      ? `已写入 ${changedCount} 个要素文件`
-      : `没有新的要素需要写入，跳过 ${elementWriteResult.value.skipped.length} 个文件`
-    emit('elementsWritten', elementWriteResult.value)
-  } catch (error) {
-    extractionStatus.value = error instanceof Error ? error.message : '写入要素失败'
-  } finally {
-    isWritingElements.value = false
-  }
-}
-
-function resetExtractionState() {
-  extractionStatus.value = canExtractElements.value ? '尚未提取要素' : '当前文件不支持要素提取'
-  extractionPreview.value = null
-  elementWriteResult.value = null
-  isExtracting.value = false
-  isWritingElements.value = false
-}
-
-function countExtractionItems(result: ElementExtractionResultView) {
-  return result.characters.length +
-    result.locations.length +
-    result.entities.length +
-    result.timeline.length +
-    result.plots.length +
-    result.worldbuilding.length
-}
 </script>
 
 <template>
@@ -351,103 +241,6 @@ function countExtractionItems(result: ElementExtractionResultView) {
 
       <!-- 文件内容 -->
       <div v-else-if="file" class="space-y-3">
-        <!-- 章节要素提取 -->
-        <div
-          v-if="canExtractElements"
-          class="space-y-3 rounded-lg border border-gray-200 bg-white p-3"
-        >
-          <div class="flex items-center justify-between gap-2">
-            <div class="min-w-0">
-              <h3 class="text-sm font-semibold text-gray-800">故事要素</h3>
-              <p class="mt-0.5 truncate text-xs text-gray-500">{{ extractionStatus }}</p>
-            </div>
-            <div class="flex shrink-0 items-center gap-1">
-              <button
-                class="rounded-lg p-1.5 text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-800 disabled:opacity-40"
-                :disabled="isExtracting || isWritingElements"
-                title="提取要素"
-                @click="handlePreviewElements"
-              >
-                <svg
-                  v-if="isExtracting"
-                  class="h-4 w-4 animate-spin"
-                  fill="none"
-                  viewBox="0 0 24 24"
-                >
-                  <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" />
-                  <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
-                </svg>
-                <svg v-else class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19.5 14.25v-7.5A2.25 2.25 0 0017.25 4.5H6.75A2.25 2.25 0 004.5 6.75v10.5A2.25 2.25 0 006.75 19.5h7.5m2.25-3v6m3-3h-6" />
-                </svg>
-              </button>
-              <button
-                class="rounded-lg p-1.5 text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-800 disabled:opacity-40"
-                :disabled="!extractionPreview || extractionCount === 0 || isExtracting || isWritingElements"
-                title="写入 elements"
-                @click="handleWriteElements"
-              >
-                <svg
-                  v-if="isWritingElements"
-                  class="h-4 w-4 animate-spin"
-                  fill="none"
-                  viewBox="0 0 24 24"
-                >
-                  <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" />
-                  <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
-                </svg>
-                <svg v-else class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                  <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4.5 12.75l6 6 9-13.5" />
-                </svg>
-              </button>
-            </div>
-          </div>
-
-          <div
-            v-if="extractionPreview"
-            class="grid grid-cols-3 gap-1 text-center text-xs"
-          >
-            <div class="rounded-md bg-gray-50 px-1 py-1">
-              <div class="font-semibold text-gray-800">{{ extractionPreview.characters.length }}</div>
-              <div class="text-gray-500">人物</div>
-            </div>
-            <div class="rounded-md bg-gray-50 px-1 py-1">
-              <div class="font-semibold text-gray-800">{{ extractionPreview.locations.length }}</div>
-              <div class="text-gray-500">地点</div>
-            </div>
-            <div class="rounded-md bg-gray-50 px-1 py-1">
-              <div class="font-semibold text-gray-800">{{ extractionPreview.entities.length }}</div>
-              <div class="text-gray-500">实体</div>
-            </div>
-            <div class="rounded-md bg-gray-50 px-1 py-1">
-              <div class="font-semibold text-gray-800">{{ extractionPreview.plots.length }}</div>
-              <div class="text-gray-500">情节</div>
-            </div>
-            <div class="rounded-md bg-gray-50 px-1 py-1">
-              <div class="font-semibold text-gray-800">{{ extractionPreview.timeline.length }}</div>
-              <div class="text-gray-500">时间</div>
-            </div>
-            <div class="rounded-md bg-gray-50 px-1 py-1">
-              <div class="font-semibold text-gray-800">{{ extractionPreview.worldbuilding.length }}</div>
-              <div class="text-gray-500">设定</div>
-            </div>
-          </div>
-
-          <div
-            v-if="extractedPaths.length > 0"
-            class="space-y-1 border-t border-gray-100 pt-2"
-          >
-            <p class="text-xs font-medium text-gray-600">已写入</p>
-            <p
-              v-for="path in extractedPaths.slice(0, 4)"
-              :key="path"
-              class="truncate text-xs text-gray-500"
-            >
-              {{ path }}
-            </p>
-          </div>
-        </div>
-
         <!-- 预览模式 -->
         <div
           v-if="viewMode === 'preview'"
diff --git a/packages/app/src/composables/useElementExtraction.ts b/packages/app/src/composables/useElementExtraction.ts
new file mode 100644
index 0000000..35453da
--- /dev/null
+++ b/packages/app/src/composables/useElementExtraction.ts
@@ -0,0 +1,186 @@
+import { ref } from 'vue'
+import { previewElementExtraction, writeExtractedElements } from '@novai/core/services/element-service'
+import { readFile } from '@novai/core/services/file-service'
+import type {
+  ElementExtractionItemView,
+  ElementExtractionResultView,
+  ElementWriteResultView,
+} from '@novai/core/services/types'
+
+/**
+ * 要素提取流程状态（R6）。
+ *
+ * 编排「选章节 → 逐章提取 → 智能合并 → 候选预览 → 确认写入」的纯 UI 流程。
+ * 不进 Agent 对话，不污染 chatStore.messages。状态集中在 composable 里，
+ * ChatPanel 的 ExtractionFlowPanel 按 phase 渲染对应界面。
+ */
+
+export type ExtractionPhase = 'idle' | 'extracting' | 'preview' | 'writing' | 'done' | 'error'
+
+export type ChapterPick = {
+  path: string
+  name: string
+}
+
+const phase = ref<ExtractionPhase>('idle')
+const selectedChapters = ref<ChapterPick[]>([])
+const extractionResult = ref<ElementExtractionResultView | null>(null)
+const writeResult = ref<ElementWriteResultView | null>(null)
+/** 提取进度：当前章节序号（从 1 起）和名称 */
+const progressCurrent = ref(0)
+const progressTotal = ref(0)
+const progressChapterName = ref('')
+const errorMessage = ref('')
+/** 当前 projectId（流程进行中锁定） */
+let activeProjectId = ''
+
+/**
+ * 智能合并多个章节的提取结果。
+ *
+ * 同 type 同 name 的候选项合并：body 用 \n\n 拼接、relatedChapters 取并集、tags 去重。
+ * 不同 name 直接 concat。lastUpdatedChapter 取最后出现的章节。
+ */
+function mergeResults(results: ElementExtractionResultView[]): ElementExtractionResultView {
+  const buckets: Array<keyof ElementExtractionResultView> = [
+    'characters', 'locations', 'entities', 'timeline', 'plots', 'worldbuilding',
+  ]
+  const merged: ElementExtractionResultView = {
+    characters: [], locations: [], entities: [], timeline: [], plots: [], worldbuilding: [],
+  }
+
+  for (const bucket of buckets) {
+    const map = new Map<string, ElementExtractionItemView>()
+    for (const result of results) {
+      for (const item of result[bucket]) {
+        const key = item.name.trim()
+        const existing = map.get(key)
+        if (existing) {
+          // 合并：body 拼接（去重复段）、relatedChapters 并集、tags 去重、lastUpdatedChapter 取较新
+          const bodyParts = [existing.body, item.body].filter(Boolean)
+          existing.body = [...new Set(bodyParts)].join('\n\n')
+          existing.relatedChapters = [...new Set([...existing.relatedChapters, ...item.relatedChapters])]
+          existing.tags = [...new Set([...existing.tags, ...item.tags])]
+          existing.lastUpdatedChapter = item.lastUpdatedChapter || existing.lastUpdatedChapter
+        } else {
+          map.set(key, { ...item })
+        }
+      }
+    }
+    merged[bucket] = [...map.values()]
+  }
+
+  return merged
+}
+
+/** 统计候选总数 */
+export function countExtractionItems(result: ElementExtractionResultView): number {
+  return (
+    result.characters.length +
+    result.locations.length +
+    result.entities.length +
+    result.timeline.length +
+    result.plots.length +
+    result.worldbuilding.length
+  )
+}
+
+/** 重置全部状态 */
+function reset() {
+  phase.value = 'idle'
+  selectedChapters.value = []
+  extractionResult.value = null
+  writeResult.value = null
+  progressCurrent.value = 0
+  progressTotal.value = 0
+  progressChapterName.value = ''
+  errorMessage.value = ''
+  activeProjectId = ''
+}
+
+/**
+ * 启动提取流程：逐章读取正文 → 逐章 LLM 提取 → 合并 → 进入预览态。
+ */
+async function startExtraction(projectId: string, chapters: ChapterPick[]) {
+  if (chapters.length === 0) return
+  activeProjectId = projectId
+  phase.value = 'extracting'
+  selectedChapters.value = chapters
+  extractionResult.value = null
+  writeResult.value = null
+  errorMessage.value = ''
+  progressTotal.value = chapters.length
+  progressCurrent.value = 0
+
+  try {
+    const perChapterResults: ElementExtractionResultView[] = []
+    for (let i = 0; i < chapters.length; i++) {
+      const chapter = chapters[i]
+      progressCurrent.value = i + 1
+      progressChapterName.value = chapter.name
+
+      const file = await readFile(projectId, chapter.path)
+      const result = await previewElementExtraction({
+        projectId,
+        chapterContent: file.content,
+        chapterPath: chapter.path,
+      })
+      perChapterResults.push(result)
+    }
+
+    extractionResult.value = mergeResults(perChapterResults)
+    phase.value = 'preview'
+  } catch (error) {
+    errorMessage.value = error instanceof Error ? error.message : '要素提取失败'
+    phase.value = 'error'
+  }
+}
+
+/**
+ * 确认写入：调 writeExtractedElements 落盘。
+ * 返回写入结果，供调用方刷新文件树。
+ */
+async function confirmWrite(): Promise<ElementWriteResultView | null> {
+  if (!extractionResult.value || phase.value !== 'preview') return null
+
+  phase.value = 'writing'
+  try {
+    const result = await writeExtractedElements({
+      projectId: activeProjectId,
+      extraction: extractionResult.value,
+    })
+    writeResult.value = result
+    phase.value = 'done'
+    return result
+  } catch (error) {
+    errorMessage.value = error instanceof Error ? error.message : '写入要素失败'
+    phase.value = 'error'
+    return null
+  }
+}
+
+/** 取消流程（预览态/错误态可用），丢弃候选 */
+function cancel() {
+  reset()
+}
+
+/** 关闭面板（完成态/错误态），回到 idle */
+function dismiss() {
+  reset()
+}
+
+export function useElementExtraction() {
+  return {
+    phase,
+    selectedChapters,
+    extractionResult,
+    writeResult,
+    progressCurrent,
+    progressTotal,
+    progressChapterName,
+    errorMessage,
+    startExtraction,
+    confirmWrite,
+    cancel,
+    dismiss,
+  }
+}
diff --git a/packages/app/src/constants/slash-commands.ts b/packages/app/src/constants/slash-commands.ts
new file mode 100644
index 0000000..6158e88
--- /dev/null
+++ b/packages/app/src/constants/slash-commands.ts
@@ -0,0 +1,29 @@
+/**
+ * 斜杠命令注册表（R6）。
+ *
+ * 输入框输入 / 后弹出命令菜单，列出这里注册的命令。
+ * 每个命令选中后展开对应的二级交互界面（目前只有 extract）。
+ * 后续可扩展 /校对、/整理 等。
+ */
+export type SlashCommandId = 'extract'
+
+export type SlashCommand = {
+  /** 命令唯一标识 */
+  id: SlashCommandId
+  /** 显示名（含 / 前缀，用于菜单展示和匹配） */
+  label: string
+  /** 简短描述 */
+  description: string
+  /** 图标（emoji） */
+  icon: string
+}
+
+/** 当前可用的斜杠命令 */
+export const SLASH_COMMANDS: SlashCommand[] = [
+  {
+    id: 'extract',
+    label: '/提取要素',
+    description: '从章节中提取人物、地点、剧情等要素',
+    icon: '✨',
+  },
+]
diff --git a/packages/app/src/views/ProjectView.vue b/packages/app/src/views/ProjectView.vue
index 914fd66..a048b53 100644
--- a/packages/app/src/views/ProjectView.vue
+++ b/packages/app/src/views/ProjectView.vue
@@ -71,6 +71,14 @@ const activeSceneName = computed(() => {
   return node ? node.name.replace(/\.md$/i, '') : null
 })
 
+/** 章节列表（chapters/*.txt|.md），供 ChatPanel 的 /提取要素 指令多选（R6） */
+const chapterList = computed(() => {
+  const files = projectStore.currentProject?.files ?? []
+  return pickDirectoryChildren(files, 'chapters').filter(
+    (n) => n.kind === 'file' && /\.(txt|md)$/i.test(n.name),
+  )
+})
+
 onMounted(async () => {
   // 如果没有当前项目，尝试恢复
   if (!projectStore.currentProject) {
@@ -258,11 +266,13 @@ async function handleElementsWritten() {
       :scenes="sceneList"
       :active-scene-prompt-path="activeScenePromptPath"
       :active-scene-name="activeSceneName"
+      :chapters="chapterList"
       @toggle-sidebar="toggleSidebar"
       @toggle-content-panel="toggleContentPanel"
       @toggle-mobile-sidebar="toggleMobileSidebar"
       @clear-quote="handleClearQuote"
       @change-scene="handleChangeScene"
+      @elements-written="handleElementsWritten"
     >
       <!-- 首次使用引导 -->
       <template #guide>
@@ -281,7 +291,6 @@ async function handleElementsWritten() {
       :file="projectStore.activeFile"
       :width="contentPanelWidth"
       @close="isContentPanelOpen = false"
-      @elements-written="handleElementsWritten"
       @save="handleSaveFile"
       @select-quote="handleSelectQuote"
       @resize="contentPanelWidth = $event"

From b881cd653b732d6331ab9c931d76c47d0d6edc6e Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 00:34:58 +0800
Subject: [PATCH 14/36] =?UTF-8?q?docs(docs):=20=E5=90=8C=E6=AD=A5=20UI=20?=
 =?UTF-8?q?=E9=87=8D=E6=9E=84=E5=AE=8C=E6=88=90=E6=96=87=E6=A1=A3=E7=8A=B6?=
 =?UTF-8?q?=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs b/docs
index d80ad2f..8723790 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit d80ad2fc88c1a480e9955e2eef5b839d88b5912c
+Subproject commit 8723790afb330124ac7ad690ff881f23f2aa5b95

From 949d5407b0a329563ee6afa23c267fe60fa5dbe9 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 00:44:27 +0800
Subject: [PATCH 15/36] =?UTF-8?q?refactor(store):=20=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E5=8F=98=E6=9B=B4=E6=94=B9=E4=B8=BA=E5=B7=A5=E5=85=B7=E5=B1=82?=
 =?UTF-8?q?=E7=BB=93=E6=9E=84=E5=8C=96=E8=BE=93=E5=87=BA=E5=B9=B6=E7=A7=BB?=
 =?UTF-8?q?=E9=99=A4=E6=96=87=E6=9C=AC=E6=8E=A8=E5=AF=BC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent Step 1：写工具（CreateFile/EditFile/RenameFile/DeleteFile）通过
新增的 extractFileChange 在成功 output 上声明 FileChange，
经 AgentToolResultMessage.fileChange 与 tool-result 事件透传。
agent-service 的 collectChangedFiles 改读结构化字段，删除正则
isSuccessfulToolResult/extractTrashPath/collectToolResultTextById
等文本反推逻辑；session.lastWrittenPath 同步改读 fileChange。
补 file-tools extractFileChange 与 tool-execution 透传测试。
---
 packages/core/src/core/agent/messages.ts      |  8 ++
 .../src/core/agent/tool-execution.test.ts     | 96 +++++++++++++++++++
 .../core/src/core/agent/tool-execution.ts     |  8 +-
 packages/core/src/core/chat/session.ts        | 23 ++---
 .../src/core/tools/file-tools/create-file.ts  |  3 +
 .../src/core/tools/file-tools/delete-file.ts  |  3 +
 .../src/core/tools/file-tools/edit-file.ts    |  3 +
 .../core/tools/file-tools/file-tools.test.ts  | 52 ++++++++++
 .../src/core/tools/file-tools/rename-file.ts  |  3 +
 packages/core/src/core/tools/types.ts         | 15 +++
 packages/core/src/services/agent-service.ts   | 85 +++-------------
 11 files changed, 213 insertions(+), 86 deletions(-)
 create mode 100644 packages/core/src/core/agent/tool-execution.test.ts

diff --git a/packages/core/src/core/agent/messages.ts b/packages/core/src/core/agent/messages.ts
index 43fc89b..0ae245f 100644
--- a/packages/core/src/core/agent/messages.ts
+++ b/packages/core/src/core/agent/messages.ts
@@ -1,3 +1,5 @@
+import type { FileChange } from '../tools/types'
+
 export type AgentToolName =
   | 'ReadFile'
   | 'EditFile'
@@ -35,6 +37,12 @@ export type AgentToolResultMessage = {
   toolCallId: string
   name: AgentToolName
   content: string
+  /**
+   * 写工具成功执行后携带的结构化文件变更。
+   * 只读工具或失败的工具不携带（undefined）。
+   * service 层据此推导 changedFiles，不再依赖 content 文本反推。
+   */
+  fileChange?: FileChange
 }
 
 export type AgentMessage =
diff --git a/packages/core/src/core/agent/tool-execution.test.ts b/packages/core/src/core/agent/tool-execution.test.ts
new file mode 100644
index 0000000..7d22a8c
--- /dev/null
+++ b/packages/core/src/core/agent/tool-execution.test.ts
@@ -0,0 +1,96 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { executeAgentTool } from './tool-execution'
+import type { AgentRunnableTool } from './tools'
+import type { AgentToolCall } from './messages'
+import type { ProjectSnapshot } from '../../types/project'
+
+const stubProject = { handle: {} } as unknown as ProjectSnapshot
+
+function createCall(name: string, input: Record<string, unknown> = {}): AgentToolCall {
+  return {
+    id: `call_${name}`,
+    name: name as AgentToolCall['name'],
+    input,
+  }
+}
+
+function createStubTool(options: {
+  name: string
+  run?: (input: unknown) => Promise<unknown>
+  extractFileChange?: (output: unknown) => unknown
+}): AgentRunnableTool {
+  return {
+    name: options.name as AgentRunnableTool['name'],
+    isReadOnly: false,
+    isConcurrencySafe: false,
+    schema: {
+      type: 'function',
+      function: { name: options.name, description: '', parameters: { type: 'object', properties: {} } },
+    },
+    core: {
+      name: options.name as AgentRunnableTool['name'],
+      validateInput: (input: unknown) => input,
+      run: options.run ?? vi.fn().mockResolvedValue({}),
+      summarizeInput: () => `调用 ${options.name}`,
+      summarizeOutput: () => `${options.name} 执行完成`,
+      extractFileChange: options.extractFileChange as never,
+    },
+    formatResult: () => `${options.name} 结果`,
+  }
+}
+
+describe('executeAgentTool', () => {
+  it('attaches fileChange when the tool declares one on success', async () => {
+    const tool = createStubTool({
+      name: 'CreateFile',
+      run: async () => ({ path: 'chapters/new.txt' }),
+      extractFileChange: (output) => ({ type: 'created', path: (output as { path: string }).path }),
+    })
+    const tools = { CreateFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    const result = await executeAgentTool({
+      call: createCall('CreateFile', { path: 'chapters/new.txt' }),
+      project: stubProject,
+      tools,
+    })
+
+    expect(result.fileChange).toEqual({ type: 'created', path: 'chapters/new.txt' })
+  })
+
+  it('leaves fileChange undefined for read-only tools without extractFileChange', async () => {
+    const tool = createStubTool({
+      name: 'ReadFile',
+      run: async () => ({ path: 'chapters/001.txt', content: '内容' }),
+    })
+    const tools = { ReadFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    const result = await executeAgentTool({
+      call: createCall('ReadFile', { path: 'chapters/001.txt' }),
+      project: stubProject,
+      tools,
+    })
+
+    expect(result.fileChange).toBeUndefined()
+  })
+
+  it('leaves fileChange undefined when the tool throws', async () => {
+    const tool = createStubTool({
+      name: 'EditFile',
+      run: async () => {
+        throw new Error('文件已发生变化')
+      },
+      extractFileChange: (output) => ({ type: 'updated', path: (output as { path: string }).path }),
+    })
+    const tools = { EditFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    const result = await executeAgentTool({
+      call: createCall('EditFile', { path: 'chapters/001.txt' }),
+      project: stubProject,
+      tools,
+    })
+
+    expect(result.fileChange).toBeUndefined()
+    expect(result.content).toContain('文件已发生变化')
+  })
+})
diff --git a/packages/core/src/core/agent/tool-execution.ts b/packages/core/src/core/agent/tool-execution.ts
index b6a75a4..4edbeb2 100644
--- a/packages/core/src/core/agent/tool-execution.ts
+++ b/packages/core/src/core/agent/tool-execution.ts
@@ -1,11 +1,11 @@
 import type { ProjectSnapshot } from '../../types/project'
 import type { AgentToolCall, AgentToolResultMessage } from './messages'
 import type { AgentRunnableToolMap } from './tools'
-import type { ReadFileState } from '../tools/types'
+import type { FileChange, ReadFileState } from '../tools/types'
 
 export type ToolExecutionEvent =
   | { type: 'tool-call'; call: AgentToolCall; inputSummary: string }
-  | { type: 'tool-result'; call: AgentToolCall; ok: boolean; resultSummary: string }
+  | { type: 'tool-result'; call: AgentToolCall; ok: boolean; resultSummary: string; fileChange?: FileChange }
 
 export async function executeAgentTool(input: {
   call: AgentToolCall
@@ -76,12 +76,15 @@ export async function executeAgentTool(input: {
       readFileStates: input.readFileStates,
     })
     const resultSummary = tool.core.summarizeOutput(output)
+    // 写工具成功执行后提取结构化文件变更，供 service 层推导 changedFiles
+    const fileChange = tool.core.extractFileChange?.(output)
 
     input.onEvent?.({
       type: 'tool-result',
       call: input.call,
       ok: true,
       resultSummary,
+      fileChange,
     })
 
     return {
@@ -89,6 +92,7 @@ export async function executeAgentTool(input: {
       toolCallId: input.call.id,
       name: input.call.name,
       content: tool.formatResult(output),
+      fileChange,
     }
   } catch (error) {
     const message = error instanceof Error ? error.message : `${tool.name} 执行失败`
diff --git a/packages/core/src/core/chat/session.ts b/packages/core/src/core/chat/session.ts
index c9686ad..a308682 100644
--- a/packages/core/src/core/chat/session.ts
+++ b/packages/core/src/core/chat/session.ts
@@ -24,6 +24,7 @@ import type {
   ToolDefinition,
 } from '../../types/chat'
 import type { AgentMessage } from '../agent/messages'
+import type { FileChange } from '../tools/types'
 
 type SessionEvent =
   | { type: 'message'; message: ChatMessage }
@@ -173,20 +174,9 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
         }
 
         if (event.type === 'tool-result') {
-          if (
-            event.ok &&
-            (event.call.name === 'EditFile' || event.call.name === 'CreateFile') &&
-            typeof event.call.input.path === 'string'
-          ) {
-            session.lastWrittenPath = event.call.input.path
-          }
-
-          if (
-            event.ok &&
-            event.call.name === 'RenameFile' &&
-            typeof event.call.input.toPath === 'string'
-          ) {
-            session.lastWrittenPath = event.call.input.toPath
+          // lastWrittenPath 取结构化 fileChange 的目标路径，不再从 input 猜。
+          if (event.ok && event.fileChange) {
+            session.lastWrittenPath = resolveWrittenPath(event.fileChange)
           }
 
           pushMessage(
@@ -938,3 +928,8 @@ function formatRecentChapters(chapters: Array<{ path: string; title: string; con
 function createId(prefix: string) {
   return `${prefix}-${Math.random().toString(36).slice(2, 10)}`
 }
+
+// 从结构化 fileChange 取最终落点：rename 取 toPath，其余取 path。
+function resolveWrittenPath(change: FileChange): string {
+  return change.type === 'renamed' ? change.toPath : change.path
+}
diff --git a/packages/core/src/core/tools/file-tools/create-file.ts b/packages/core/src/core/tools/file-tools/create-file.ts
index e875643..25aac28 100644
--- a/packages/core/src/core/tools/file-tools/create-file.ts
+++ b/packages/core/src/core/tools/file-tools/create-file.ts
@@ -43,4 +43,7 @@ export const createFileTool: ToolDefinition<'CreateFile', CreateFileInput, Creat
   summarizeOutput(output) {
     return `已新建 ${output.path}，共 ${output.linesAdded} 行，${output.contentLength} 个字符`
   },
+  extractFileChange(output) {
+    return { type: 'created', path: output.path }
+  },
 }
diff --git a/packages/core/src/core/tools/file-tools/delete-file.ts b/packages/core/src/core/tools/file-tools/delete-file.ts
index 27252e2..c5de97b 100644
--- a/packages/core/src/core/tools/file-tools/delete-file.ts
+++ b/packages/core/src/core/tools/file-tools/delete-file.ts
@@ -45,6 +45,9 @@ export const deleteFileTool: ToolDefinition<'DeleteFile', DeleteFileInput, Delet
   summarizeOutput(output) {
     return `已将 ${output.path} 移入回收站 ${output.trashPath}，原文件共 ${output.linesRemoved} 行，${output.contentLength} 个字符`
   },
+  extractFileChange(output) {
+    return { type: 'deleted', path: output.path, trashPath: output.trashPath }
+  },
 }
 
 function createTrashPath(path: string) {
diff --git a/packages/core/src/core/tools/file-tools/edit-file.ts b/packages/core/src/core/tools/file-tools/edit-file.ts
index 69eedf9..4f2d48c 100644
--- a/packages/core/src/core/tools/file-tools/edit-file.ts
+++ b/packages/core/src/core/tools/file-tools/edit-file.ts
@@ -91,4 +91,7 @@ export const editFileTool: ToolDefinition<'EditFile', EditFileInput, EditFileOut
   summarizeOutput(output) {
     return `已修改 ${output.path}，替换 ${output.occurrences} 处，当前 ${output.contentLength} 个字符`
   },
+  extractFileChange(output) {
+    return { type: 'updated', path: output.path }
+  },
 }
diff --git a/packages/core/src/core/tools/file-tools/file-tools.test.ts b/packages/core/src/core/tools/file-tools/file-tools.test.ts
index e61174d..66257e2 100644
--- a/packages/core/src/core/tools/file-tools/file-tools.test.ts
+++ b/packages/core/src/core/tools/file-tools/file-tools.test.ts
@@ -126,6 +126,58 @@ describe('file tools', () => {
     await expect(readProjectText(runtime.project.handle, output.trashPath)).resolves.toBe('废稿')
     await expect(readProjectText(runtime.project.handle, 'chapters/old.txt')).rejects.toThrow('Not found')
   })
+
+  describe('extractFileChange', () => {
+    // 写工具成功执行后必须声明结构化文件变更，供 service 层推导 changedFiles，
+    // 不再依赖工具结果文本反推。
+    it('CreateFile declares a created change', async () => {
+      const runtime = createRuntime({})
+      const output = await createFileTool.run({ path: 'chapters/new.txt', content: '内容' }, runtime)
+
+      expect(createFileTool.extractFileChange?.(output)).toEqual({ type: 'created', path: 'chapters/new.txt' })
+    })
+
+    it('EditFile declares an updated change', async () => {
+      const runtime = createRuntime({ 'chapters/001.txt': '第一段\n第二段' })
+      await readFileTool.run({ path: 'chapters/001.txt' }, runtime)
+      const output = await editFileTool.run({
+        path: 'chapters/001.txt',
+        oldText: '第二段',
+        newText: '第二段修改',
+      }, runtime)
+
+      expect(editFileTool.extractFileChange?.(output)).toEqual({ type: 'updated', path: 'chapters/001.txt' })
+    })
+
+    it('RenameFile declares a renamed change', async () => {
+      const runtime = createRuntime({ 'chapters/source.txt': '源内容' })
+      const output = await renameFileTool.run({
+        fromPath: 'chapters/source.txt',
+        toPath: 'chapters/renamed.txt',
+      }, runtime)
+
+      expect(renameFileTool.extractFileChange?.(output)).toEqual({
+        type: 'renamed',
+        fromPath: 'chapters/source.txt',
+        toPath: 'chapters/renamed.txt',
+      })
+    })
+
+    it('DeleteFile declares a deleted change with trashPath', async () => {
+      const runtime = createRuntime({ 'chapters/old.txt': '废稿' })
+      const output = await deleteFileTool.run({ path: 'chapters/old.txt' }, runtime)
+
+      expect(deleteFileTool.extractFileChange?.(output)).toEqual({
+        type: 'deleted',
+        path: 'chapters/old.txt',
+        trashPath: output.trashPath,
+      })
+    })
+
+    it('read-only tools do not declare file changes', () => {
+      expect(readFileTool.extractFileChange).toBeUndefined()
+    })
+  })
 })
 
 function createRuntime(files: Record<string, string>): ToolRuntime {
diff --git a/packages/core/src/core/tools/file-tools/rename-file.ts b/packages/core/src/core/tools/file-tools/rename-file.ts
index e3892e8..3ace1cf 100644
--- a/packages/core/src/core/tools/file-tools/rename-file.ts
+++ b/packages/core/src/core/tools/file-tools/rename-file.ts
@@ -51,4 +51,7 @@ export const renameFileTool: ToolDefinition<'RenameFile', RenameFileInput, Renam
   summarizeOutput(output) {
     return `已将 ${output.fromPath} 移动到 ${output.toPath}，共 ${output.contentLength} 个字符`
   },
+  extractFileChange(output) {
+    return { type: 'renamed', fromPath: output.fromPath, toPath: output.toPath }
+  },
 }
diff --git a/packages/core/src/core/tools/types.ts b/packages/core/src/core/tools/types.ts
index 9746339..fe899dc 100644
--- a/packages/core/src/core/tools/types.ts
+++ b/packages/core/src/core/tools/types.ts
@@ -37,6 +37,16 @@ export type ToolExecution<TName extends CoreToolName = CoreToolName, TInput = un
   result: ToolResult<TName, TOutput>
 }
 
+/**
+ * 工具层声明的结构化文件变更，由写工具在执行成功后产出。
+ * service 层据此推导 changedFiles，不再依赖工具结果文本反推。
+ */
+export type FileChange =
+  | { type: 'created'; path: string }
+  | { type: 'updated'; path: string }
+  | { type: 'renamed'; fromPath: string; toPath: string }
+  | { type: 'deleted'; path: string; trashPath?: string }
+
 export type ToolDefinition<TName extends CoreToolName, TInput, TOutput> = {
   name: TName
   description: string
@@ -44,6 +54,11 @@ export type ToolDefinition<TName extends CoreToolName, TInput, TOutput> = {
   run(input: TInput, runtime: ToolRuntime): Promise<TOutput>
   summarizeInput(input: TInput): string
   summarizeOutput(output: TOutput): string
+  /**
+   * 写工具用它声明结构化文件变更；只读工具不实现。
+   * 返回 undefined 表示该 output 不产生文件变更。
+   */
+  extractFileChange?(output: TOutput): FileChange | undefined
 }
 
 export type ReadFileInput = {
diff --git a/packages/core/src/services/agent-service.ts b/packages/core/src/services/agent-service.ts
index 391b457..d8f7206 100644
--- a/packages/core/src/services/agent-service.ts
+++ b/packages/core/src/services/agent-service.ts
@@ -4,7 +4,7 @@ import {
 } from '../core/chat/session'
 import { deriveChatTargetFromPath } from '../core/chat/target'
 import { readScenePrompt, readSystemPrompt } from '../core/fs/project-fs'
-import type { AgentMessage, AgentToolCall } from '../core/agent/messages'
+import type { FileChange } from '../core/tools/types'
 import type { ChatMessage, ChatSessionState, ChatTargetContext } from '../types/chat'
 
 import {
@@ -231,90 +231,35 @@ function toChatMessageView(message: ChatMessage): ChatMessageView {
 
 function collectChangedFiles(session: ChatSessionState): ChangedFileView[] {
   const changes: ChangedFileView[] = []
-  const toolResultTextById = collectToolResultTextById(session.agentMessages ?? [])
 
   for (const message of session.agentMessages ?? []) {
-    if (message.role !== 'assistant' || !message.toolCalls?.length) {
+    if (message.role !== 'tool') {
       continue
     }
 
-    for (const call of message.toolCalls) {
-      const resultText = toolResultTextById.get(call.id) ?? ''
-      const change = toChangedFile(call, resultText)
-
-      if (change) {
-        changes.push(change)
-      }
+    // fileChange 由 tool-execution 在写工具成功执行后从 output 提取并挂载，
+    // 是结构化、可信的文件变更来源，不再依赖工具结果文本反推。
+    const change = message.fileChange
+    if (change) {
+      changes.push(toChangedFileView(change))
     }
   }
 
   return dedupeChangedFiles(changes)
 }
 
-function collectToolResultTextById(messages: AgentMessage[]) {
-  const result = new Map<string, string>()
-
-  for (const message of messages) {
-    if (message.role === 'tool') {
-      result.set(message.toolCallId, message.content)
-    }
-  }
-
-  return result
-}
-
-function toChangedFile(
-  call: AgentToolCall,
-  resultText: string,
-): ChangedFileView | null {
-  if (!isSuccessfulToolResult(resultText)) {
-    return null
-  }
-
-  if (call.name === 'CreateFile' && typeof call.input.path === 'string') {
-    return {
-      type: 'created',
-      path: call.input.path,
-    }
-  }
-
-  if (call.name === 'EditFile' && typeof call.input.path === 'string') {
-    return {
-      type: 'updated',
-      path: call.input.path,
-    }
+function toChangedFileView(change: FileChange): ChangedFileView {
+  // core 的 FileChange 与 service 的 ChangedFileView 形状一致；
+  // 显式映射而非直接透传，避免 service 层依赖 core 工具内部类型的结构。
+  if (change.type === 'renamed') {
+    return { type: 'renamed', fromPath: change.fromPath, toPath: change.toPath }
   }
 
-  if (
-    call.name === 'RenameFile' &&
-    typeof call.input.fromPath === 'string' &&
-    typeof call.input.toPath === 'string'
-  ) {
-    return {
-      type: 'renamed',
-      fromPath: call.input.fromPath,
-      toPath: call.input.toPath,
-    }
+  if (change.type === 'deleted') {
+    return { type: 'deleted', path: change.path, trashPath: change.trashPath }
   }
 
-  if (call.name === 'DeleteFile' && typeof call.input.path === 'string') {
-    return {
-      type: 'deleted',
-      path: call.input.path,
-      trashPath: extractTrashPath(resultText),
-    }
-  }
-
-  return null
-}
-
-function isSuccessfulToolResult(resultText: string) {
-  return /^(已读取|已修改|已新建|已将|已查看|已在)/.test(resultText)
-}
-
-function extractTrashPath(resultText: string) {
-  const match = resultText.match(/移入回收站\s+([^，\s]+)/)
-  return match?.[1]
+  return { type: change.type, path: change.path }
 }
 
 function dedupeChangedFiles(changes: ChangedFileView[]) {

From a6962bc1875a95f1dcc9af301c189ebc7d6f822e Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 00:50:17 +0800
Subject: [PATCH 16/36] =?UTF-8?q?docs(docs):=20=E5=90=8C=E6=AD=A5=20Agent?=
 =?UTF-8?q?=20=E6=8E=A7=E5=88=B6=E8=83=BD=E5=8A=9B=20Step=201=20=E8=90=BD?=
 =?UTF-8?q?=E5=9C=B0=E7=8A=B6=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs b/docs
index 8723790..a14e6f6 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit 8723790afb330124ac7ad690ff881f23f2aa5b95
+Subproject commit a14e6f6b2df15f5baf46be3ad12189770f4e79d4

From 0707809f2d2bd00758e38b97427a644c6d3bcae1 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 01:06:30 +0800
Subject: [PATCH 17/36] =?UTF-8?q?feat(project):=20=E5=86=99=E5=B7=A5?=
 =?UTF-8?q?=E5=85=B7=E6=8E=A5=E5=85=A5=E5=86=99=E5=85=A5=E5=89=8D=E7=A1=AE?=
 =?UTF-8?q?=E8=AE=A4=E4=B8=8E=20diff=20=E9=A2=84=E8=A7=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent Step 2/3：写工具（CreateFile/EditFile/RenameFile/DeleteFile）
执行前暂停等待用户确认，拒绝则返回拒绝结果回灌模型让其调整。

core 层：
- ToolDefinition 新增 buildConfirmation；4 个写工具各自实现，
  从 validatedInput 构造 WriteConfirmation（edit/create 带文本用于
  diff，rename/delete 仅路径级）。
- tool-execution 在 run 前拦截写工具：调 confirm 回调等待决定，
  拒绝不执行 run 并返回结构化拒绝结果；确认中断（停止）按拒绝处理。
- tool-orchestration/query/session 透传 confirm；query 每次写操作都确认。
- agent-service 新增确认注册表 confirmationMap + respondConfirmation，
  confirm 回调发 confirmation-required 事件并 await UI 响应；
  出错时 rejectPendingConfirmations 清理未决确认。

app 层：
- chat store 新增 pendingConfirmation + confirmWriteTool/rejectWriteTool。
- 新增 WriteConfirmationCard.vue（抄 ExtractionFlowPanel 预览样式），
  按 kind 渲染 create 内容预览 / edit old-new diff / rename from-to /
  delete 路径说明，确认/拒绝按钮。
- ChatPanel 在消息列表与输入框之间挂载确认卡片。

测试：tool-execution 新增 4 个确认用例（接受执行 / 拒绝不执行 /
只读工具不触发 / 确认中断按拒绝）。
---
 .../components/chat/WriteConfirmationCard.vue | 108 ++++++++++++++++++
 .../app/src/components/layout/ChatPanel.vue   |  12 ++
 packages/app/src/stores/chat.ts               |  35 ++++++
 packages/core/src/core/agent/query.ts         |   5 +-
 .../src/core/agent/tool-execution.test.ts     |  96 +++++++++++++++-
 .../core/src/core/agent/tool-execution.ts     |  62 +++++++++-
 .../core/src/core/agent/tool-orchestration.ts |   5 +-
 packages/core/src/core/chat/session.ts        |   1 +
 .../src/core/tools/file-tools/create-file.ts  |   3 +
 .../src/core/tools/file-tools/delete-file.ts  |   3 +
 .../src/core/tools/file-tools/edit-file.ts    |   3 +
 .../src/core/tools/file-tools/rename-file.ts  |   3 +
 packages/core/src/core/tools/types.ts         |  15 +++
 packages/core/src/services/agent-service.ts   | 104 ++++++++++++++++-
 packages/core/src/services/types.ts           |   9 +-
 packages/core/src/types/chat.ts               |   3 +
 16 files changed, 461 insertions(+), 6 deletions(-)
 create mode 100644 packages/app/src/components/chat/WriteConfirmationCard.vue

diff --git a/packages/app/src/components/chat/WriteConfirmationCard.vue b/packages/app/src/components/chat/WriteConfirmationCard.vue
new file mode 100644
index 0000000..f84bf60
--- /dev/null
+++ b/packages/app/src/components/chat/WriteConfirmationCard.vue
@@ -0,0 +1,108 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { WriteConfirmationView } from '@novai/core/services/types'
+
+/**
+ * 写工具确认卡片（Agent Step 2/3）。
+ *
+ * Agent 在执行写工具前暂停，由该卡片展示操作预览（diff / 路径），
+ * 用户确认后写入生效，拒绝则 Agent 收到拒绝结果并可调整。
+ */
+const props = defineProps<{
+  confirmation: WriteConfirmationView
+  toolName: string
+  title: string
+  summary: string
+}>()
+
+const emit = defineEmits<{
+  confirm: []
+  reject: []
+}>()
+
+const diffOldText = computed(() => props.confirmation.kind === 'edit' ? props.confirmation.oldText : '')
+const diffNewText = computed(() => props.confirmation.kind === 'edit' ? props.confirmation.newText : '')
+
+/** diff 文本过长时折叠，避免卡片撑爆对话区。 */
+const MAX_DIFF_CHARS = 600
+const oldPreview = computed(() => truncate(diffOldText.value, MAX_DIFF_CHARS))
+const newPreview = computed(() => truncate(diffNewText.value, MAX_DIFF_CHARS))
+
+function truncate(text: string, max: number) {
+  if (text.length <= max) {
+    return text
+  }
+  return `${text.slice(0, max)}…（共 ${text.length} 字符，已截断预览）`
+}
+</script>
+
+<template>
+  <div class="mx-auto mb-2 max-w-3xl rounded-lg border border-amber-200 bg-amber-50">
+    <div class="p-4">
+      <!-- 标题区 -->
+      <div class="mb-3 flex items-center gap-2">
+        <svg class="h-4 w-4 shrink-0 text-amber-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path
+            stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
+            d="M12 9v2m0 4h.01M5 19h14a2 2 0 001.84-2.75L13.74 4a2 2 0 00-3.48 0L3.16 16.25A2 2 0 005 19z"
+          />
+        </svg>
+        <p class="text-sm font-medium text-gray-700">{{ title }}</p>
+      </div>
+
+      <!-- 摘要 -->
+      <p class="mb-3 text-xs text-gray-500">{{ summary }}</p>
+
+      <!-- 新建文件：内容预览 -->
+      <div v-if="confirmation.kind === 'create'" class="mb-3">
+        <pre class="max-h-48 overflow-auto whitespace-pre-wrap rounded bg-white p-3 text-xs text-gray-700">{{ confirmation.content }}</pre>
+      </div>
+
+      <!-- 修改文件：old → new diff 预览 -->
+      <div v-else-if="confirmation.kind === 'edit'" class="mb-3 space-y-2">
+        <div>
+          <p class="mb-1 text-xs font-medium text-red-500">原文（将被替换）</p>
+          <pre class="max-h-32 overflow-auto whitespace-pre-wrap rounded bg-red-50 p-3 text-xs text-red-800">{{ oldPreview }}</pre>
+        </div>
+        <div>
+          <p class="mb-1 text-xs font-medium text-green-600">新文本</p>
+          <pre class="max-h-32 overflow-auto whitespace-pre-wrap rounded bg-green-50 p-3 text-xs text-green-800">{{ newPreview }}</pre>
+        </div>
+      </div>
+
+      <!-- 重命名：from → to -->
+      <div v-else-if="confirmation.kind === 'rename'" class="mb-3 flex items-center gap-2 text-xs">
+        <code class="rounded bg-white px-2 py-1 text-gray-700">{{ confirmation.fromPath }}</code>
+        <svg class="h-3 w-3 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M14 5l7 7m0 0l-7 7m7-7H3" />
+        </svg>
+        <code class="rounded bg-white px-2 py-1 text-gray-700">{{ confirmation.toPath }}</code>
+      </div>
+
+      <!-- 删除：路径 + 回收站说明 -->
+      <div v-else-if="confirmation.kind === 'delete'" class="mb-3">
+        <p class="text-xs text-gray-600">
+          文件 <code class="rounded bg-white px-1.5 py-0.5 text-gray-700">{{ confirmation.path }}</code> 将移入回收站（不永久删除）。
+        </p>
+      </div>
+
+      <!-- 操作按钮 -->
+      <div class="flex items-center justify-end gap-2">
+        <button
+          type="button"
+          class="rounded-md px-3 py-1.5 text-xs font-medium text-gray-600 transition-colors hover:bg-amber-100"
+          @click="emit('reject')"
+        >
+          拒绝
+        </button>
+        <button
+          type="button"
+          class="rounded-md bg-green-600 px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-green-700"
+          @click="emit('confirm')"
+        >
+          确认写入
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/packages/app/src/components/layout/ChatPanel.vue b/packages/app/src/components/layout/ChatPanel.vue
index 2eb7da4..b7f1551 100644
--- a/packages/app/src/components/layout/ChatPanel.vue
+++ b/packages/app/src/components/layout/ChatPanel.vue
@@ -10,6 +10,7 @@ import SceneChip from '../chat/SceneChip.vue'
 import SceneCommandPopover from '../chat/SceneCommandPopover.vue'
 import ChapterPicker from '../chat/ChapterPicker.vue'
 import ExtractionFlowPanel from '../chat/ExtractionFlowPanel.vue'
+import WriteConfirmationCard from '../chat/WriteConfirmationCard.vue'
 import SlashCommandMenu from '../chat/SlashCommandMenu.vue'
 import type { SlashCommandId } from '../../constants/slash-commands'
 
@@ -407,6 +408,17 @@ async function handleExtractionConfirm() {
       @dismiss="extraction.dismiss()"
     />
 
+    <!-- 写工具确认卡片（Agent Step 2/3） -->
+    <WriteConfirmationCard
+      v-if="chatStore.pendingConfirmation"
+      :confirmation="chatStore.pendingConfirmation.confirmation"
+      :tool-name="chatStore.pendingConfirmation.toolName"
+      :title="chatStore.pendingConfirmation.title"
+      :summary="chatStore.pendingConfirmation.summary"
+      @confirm="chatStore.confirmWriteTool()"
+      @reject="chatStore.rejectWriteTool()"
+    />
+
     <!-- 输入区域 -->
     <div class="border-t border-gray-200 bg-white px-4 py-3">
       <div class="mx-auto max-w-3xl">
diff --git a/packages/app/src/stores/chat.ts b/packages/app/src/stores/chat.ts
index 3148e78..7600ab0 100644
--- a/packages/app/src/stores/chat.ts
+++ b/packages/app/src/stores/chat.ts
@@ -3,6 +3,7 @@ import { defineStore } from 'pinia'
 
 import {
   createSession as createAgentSession,
+  respondConfirmation as respondAgentConfirmation,
   runTurn as runAgentTurn,
 } from '@novai/core/services/agent-service'
 
@@ -11,6 +12,7 @@ import type {
   ChangedFileView,
   ChatMessageView,
   ChatSessionView,
+  FileChangeConfirmationView,
   RunAgentTurnInput,
   RunAgentTurnResult,
 } from '@novai/core/services/types'
@@ -23,6 +25,8 @@ export const useChatStore = defineStore('chat', () => {
   const isRunning = ref(false)
   // 用户已请求停止、正在等待当前工具执行完成
   const isStopping = ref(false)
+  // 当前等待用户确认的写操作；Agent Loop 在此暂停
+  const pendingConfirmation = ref<FileChangeConfirmationView | null>(null)
 
   // 当前运行持有的停止控制器；仅 isRunning 期间存在
   let activeAbortController: AbortController | null = null
@@ -118,6 +122,12 @@ export const useChatStore = defineStore('chat', () => {
       return
     }
 
+    if (event.type === 'confirmation-required') {
+      pendingConfirmation.value = event.request
+      runStatus.value = '等待确认写入操作…'
+      return
+    }
+
     if (event.type === 'run-error') {
       runStatus.value = event.error.message
       return
@@ -148,18 +158,43 @@ export const useChatStore = defineStore('chat', () => {
     })
   }
 
+  /** 用户确认当前待确认的写操作，唤醒 Agent Loop 继续执行。 */
+  function confirmWriteTool() {
+    const confirmation = pendingConfirmation.value
+    if (!confirmation) {
+      return
+    }
+    pendingConfirmation.value = null
+    respondAgentConfirmation(confirmation.id, true)
+    runStatus.value = 'Agent 正在执行...'
+  }
+
+  /** 用户拒绝当前待确认的写操作，Agent 收到拒绝结果后可调整。 */
+  function rejectWriteTool() {
+    const confirmation = pendingConfirmation.value
+    if (!confirmation) {
+      return
+    }
+    pendingConfirmation.value = null
+    respondAgentConfirmation(confirmation.id, false)
+    runStatus.value = 'Agent 正在执行...'
+  }
+
   return {
     agentEvents,
     changedFiles,
     isRunning,
     isStopping,
     messages,
+    pendingConfirmation,
     sessionView,
     runStatus,
     hasSessionView,
     abortRun,
+    confirmWriteTool,
     createSession,
     ensureSessionView,
+    rejectWriteTool,
     sendMessage,
     runServiceTurn,
     setRunStatus,
diff --git a/packages/core/src/core/agent/query.ts b/packages/core/src/core/agent/query.ts
index d5c39f8..6d1d1db 100644
--- a/packages/core/src/core/agent/query.ts
+++ b/packages/core/src/core/agent/query.ts
@@ -1,6 +1,6 @@
 import { streamAgentCompletion, AgentAbortedError } from './llm'
 import { runAgentTools } from './tool-orchestration'
-import type { ToolExecutionEvent } from './tool-execution'
+import type { ConfirmHandler, ToolExecutionEvent } from './tool-execution'
 import type { ProjectConfig, ProjectSnapshot } from '../../types/project'
 import type {
   AgentAssistantMessage,
@@ -31,6 +31,8 @@ export async function query(input: {
   tools: AgentRunnableToolMap
   maxTurns?: number
   signal?: AbortSignal
+  /** 写工具确认回调，透传到工具执行层。 */
+  confirm?: ConfirmHandler
   onEvent?: (event: AgentQueryEvent) => void
 }): Promise<AgentMessage[]> {
   let messages = [...input.messages]
@@ -135,6 +137,7 @@ export async function query(input: {
       tools: input.tools,
       readFileStates,
       signal: input.signal,
+      confirm: input.confirm,
       onEvent: input.onEvent,
     })
 
diff --git a/packages/core/src/core/agent/tool-execution.test.ts b/packages/core/src/core/agent/tool-execution.test.ts
index 7d22a8c..e7f3ec3 100644
--- a/packages/core/src/core/agent/tool-execution.test.ts
+++ b/packages/core/src/core/agent/tool-execution.test.ts
@@ -17,12 +17,14 @@ function createCall(name: string, input: Record<string, unknown> = {}): AgentToo
 
 function createStubTool(options: {
   name: string
+  isReadOnly?: boolean
   run?: (input: unknown) => Promise<unknown>
   extractFileChange?: (output: unknown) => unknown
+  buildConfirmation?: (input: unknown) => unknown
 }): AgentRunnableTool {
   return {
     name: options.name as AgentRunnableTool['name'],
-    isReadOnly: false,
+    isReadOnly: options.isReadOnly ?? false,
     isConcurrencySafe: false,
     schema: {
       type: 'function',
@@ -35,6 +37,7 @@ function createStubTool(options: {
       summarizeInput: () => `调用 ${options.name}`,
       summarizeOutput: () => `${options.name} 执行完成`,
       extractFileChange: options.extractFileChange as never,
+      buildConfirmation: options.buildConfirmation as never,
     },
     formatResult: () => `${options.name} 结果`,
   }
@@ -61,6 +64,7 @@ describe('executeAgentTool', () => {
   it('leaves fileChange undefined for read-only tools without extractFileChange', async () => {
     const tool = createStubTool({
       name: 'ReadFile',
+      isReadOnly: true,
       run: async () => ({ path: 'chapters/001.txt', content: '内容' }),
     })
     const tools = { ReadFile: tool } as unknown as Record<string, AgentRunnableTool>
@@ -94,3 +98,93 @@ describe('executeAgentTool', () => {
     expect(result.content).toContain('文件已发生变化')
   })
 })
+
+describe('executeAgentTool confirmation', () => {
+  it('executes the write tool after the user accepts confirmation', async () => {
+    const run = vi.fn().mockResolvedValue({ path: 'chapters/new.txt' })
+    const tool = createStubTool({
+      name: 'CreateFile',
+      run,
+      buildConfirmation: (input) => ({ kind: 'create', path: (input as { path: string }).path, content: (input as { content: string }).content }),
+    })
+    const tools = { CreateFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    const result = await executeAgentTool({
+      call: createCall('CreateFile', { path: 'chapters/new.txt', content: '内容' }),
+      project: stubProject,
+      tools,
+      confirm: async () => ({ accepted: true }),
+    })
+
+    expect(run).toHaveBeenCalledTimes(1)
+    expect(result.content).toBe('CreateFile 结果')
+  })
+
+  it('skips execution and returns a rejection result when the user rejects', async () => {
+    const run = vi.fn().mockResolvedValue({})
+    const tool = createStubTool({
+      name: 'EditFile',
+      run,
+      buildConfirmation: (input) => ({ kind: 'edit', path: (input as { path: string }).path, oldText: 'a', newText: 'b' }),
+    })
+    const tools = { EditFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    const result = await executeAgentTool({
+      call: createCall('EditFile', { path: 'chapters/001.txt' }),
+      project: stubProject,
+      tools,
+      confirm: async () => ({ accepted: false }),
+    })
+
+    // 未执行 run，文件不变
+    expect(run).not.toHaveBeenCalled()
+    // 返回拒绝结果回灌模型，不含 fileChange
+    expect(result.content).toContain('用户拒绝')
+    expect(result.fileChange).toBeUndefined()
+  })
+
+  it('does not trigger confirmation for read-only tools', async () => {
+    const run = vi.fn().mockResolvedValue({ path: 'chapters/001.txt', content: '内容' })
+    const tool = createStubTool({
+      name: 'ReadFile',
+      isReadOnly: true,
+      run,
+    })
+    const tools = { ReadFile: tool } as unknown as Record<string, AgentRunnableTool>
+    const confirm = vi.fn().mockResolvedValue({ accepted: true })
+
+    await executeAgentTool({
+      call: createCall('ReadFile', { path: 'chapters/001.txt' }),
+      project: stubProject,
+      tools,
+      confirm,
+    })
+
+    // 只读工具不触发确认
+    expect(confirm).not.toHaveBeenCalled()
+    expect(run).toHaveBeenCalledTimes(1)
+  })
+
+  it('treats a confirmation error (e.g. user stop) as rejection', async () => {
+    const run = vi.fn().mockResolvedValue({})
+    const tool = createStubTool({
+      name: 'DeleteFile',
+      run,
+      buildConfirmation: (input) => ({ kind: 'delete', path: (input as { path: string }).path }),
+    })
+    const tools = { DeleteFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    const result = await executeAgentTool({
+      call: createCall('DeleteFile', { path: 'chapters/old.txt' }),
+      project: stubProject,
+      tools,
+      confirm: async () => {
+        throw new Error('aborted')
+      },
+    })
+
+    // 确认中断按拒绝处理，不执行
+    expect(run).not.toHaveBeenCalled()
+    expect(result.content).toContain('用户拒绝')
+  })
+})
diff --git a/packages/core/src/core/agent/tool-execution.ts b/packages/core/src/core/agent/tool-execution.ts
index 4edbeb2..98778d2 100644
--- a/packages/core/src/core/agent/tool-execution.ts
+++ b/packages/core/src/core/agent/tool-execution.ts
@@ -1,17 +1,34 @@
 import type { ProjectSnapshot } from '../../types/project'
 import type { AgentToolCall, AgentToolResultMessage } from './messages'
 import type { AgentRunnableToolMap } from './tools'
-import type { FileChange, ReadFileState } from '../tools/types'
+import type { FileChange, ReadFileState, WriteConfirmation } from '../tools/types'
 
 export type ToolExecutionEvent =
   | { type: 'tool-call'; call: AgentToolCall; inputSummary: string }
   | { type: 'tool-result'; call: AgentToolCall; ok: boolean; resultSummary: string; fileChange?: FileChange }
 
+/** 写工具执行前的确认请求，交由上层（service）转交 UI 等待用户决定。 */
+export type WriteConfirmationRequest = {
+  call: AgentToolCall
+  confirmation: WriteConfirmation
+}
+
+export type ConfirmDecision = { accepted: boolean }
+
+/**
+ * 写工具确认回调。返回用户是否接受写入。
+ * service 层实现：发 confirmation-required 事件 → 等待 respondConfirmation → resolve。
+ * 拒绝/停止时 resolve 为 { accepted: false }，由 tool-execution 决定是否跳过执行。
+ */
+export type ConfirmHandler = (request: WriteConfirmationRequest) => Promise<ConfirmDecision>
+
 export async function executeAgentTool(input: {
   call: AgentToolCall
   project: ProjectSnapshot
   tools: AgentRunnableToolMap
   readFileStates?: Map<string, ReadFileState>
+  /** 写工具确认回调；未传时不做确认（测试/只读场景）。 */
+  confirm?: ConfirmHandler
   onEvent?: (event: ToolExecutionEvent) => void
 }): Promise<AgentToolResultMessage> {
   const tool = input.tools[input.call.name]
@@ -70,6 +87,36 @@ export async function executeAgentTool(input: {
     inputSummary: tool.core.summarizeInput(validatedInput),
   })
 
+  // 写工具执行前确认：构造预览并等待用户决定。
+  // 拒绝时不执行 run，返回「用户已拒绝」tool result 回灌模型，让其自然调整。
+  if (!tool.isReadOnly && tool.core.buildConfirmation && input.confirm) {
+    const confirmation = tool.core.buildConfirmation(validatedInput)
+    let decision: ConfirmDecision
+    try {
+      decision = await input.confirm({ call: input.call, confirmation })
+    } catch {
+      // 确认等待被中断（如用户停止），按拒绝处理，交由 query Loop 的 abort 检查接管。
+      decision = { accepted: false }
+    }
+
+    if (!decision.accepted) {
+      const rejectedSummary = `用户已拒绝${summarizeConfirmation(confirmation)}，未修改文件`
+      input.onEvent?.({
+        type: 'tool-result',
+        call: input.call,
+        ok: false,
+        resultSummary: rejectedSummary,
+      })
+
+      return {
+        role: 'tool',
+        toolCallId: input.call.id,
+        name: input.call.name,
+        content: `用户拒绝执行该操作，文件未修改。请改用其他方式完成任务，或向用户确认后再试。`,
+      }
+    }
+  }
+
   try {
     const output = await tool.core.run(validatedInput, {
       project: input.project,
@@ -111,3 +158,16 @@ export async function executeAgentTool(input: {
     }
   }
 }
+
+function summarizeConfirmation(confirmation: WriteConfirmation): string {
+  switch (confirmation.kind) {
+    case 'create':
+      return `新建 ${confirmation.path}`
+    case 'edit':
+      return `修改 ${confirmation.path}`
+    case 'rename':
+      return `重命名 ${confirmation.fromPath} 到 ${confirmation.toPath}`
+    case 'delete':
+      return `删除 ${confirmation.path}`
+  }
+}
diff --git a/packages/core/src/core/agent/tool-orchestration.ts b/packages/core/src/core/agent/tool-orchestration.ts
index 5f445ad..d92f3f5 100644
--- a/packages/core/src/core/agent/tool-orchestration.ts
+++ b/packages/core/src/core/agent/tool-orchestration.ts
@@ -1,5 +1,5 @@
 import { executeAgentTool } from './tool-execution'
-import type { ToolExecutionEvent } from './tool-execution'
+import type { ConfirmHandler, ToolExecutionEvent } from './tool-execution'
 import type { ProjectSnapshot } from '../../types/project'
 import type { AgentToolCall, AgentToolResultMessage } from './messages'
 import type { AgentRunnableToolMap } from './tools'
@@ -12,6 +12,8 @@ export async function runAgentTools(input: {
   readFileStates?: Map<string, ReadFileState>
   /** 用户停止信号：已停止时，批次内尚未开始执行的工具会被跳过。 */
   signal?: AbortSignal
+  /** 写工具确认回调，透传给 executeAgentTool。 */
+  confirm?: ConfirmHandler
   onEvent?: (event: ToolExecutionEvent) => void
 }): Promise<AgentToolResultMessage[]> {
   const results: AgentToolResultMessage[] = []
@@ -46,6 +48,7 @@ export async function runAgentTools(input: {
       project: input.project,
       tools: input.tools,
       readFileStates: input.readFileStates,
+      confirm: input.confirm,
       onEvent: input.onEvent,
     }))
   }
diff --git a/packages/core/src/core/chat/session.ts b/packages/core/src/core/chat/session.ts
index a308682..bf9da69 100644
--- a/packages/core/src/core/chat/session.ts
+++ b/packages/core/src/core/chat/session.ts
@@ -130,6 +130,7 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
       messages: agentMessages,
       tools,
       signal: input.signal,
+      confirm: input.confirm,
       onEvent(event) {
         logAgentQueryEvent({
           project: input.project,
diff --git a/packages/core/src/core/tools/file-tools/create-file.ts b/packages/core/src/core/tools/file-tools/create-file.ts
index 25aac28..79d867f 100644
--- a/packages/core/src/core/tools/file-tools/create-file.ts
+++ b/packages/core/src/core/tools/file-tools/create-file.ts
@@ -46,4 +46,7 @@ export const createFileTool: ToolDefinition<'CreateFile', CreateFileInput, Creat
   extractFileChange(output) {
     return { type: 'created', path: output.path }
   },
+  buildConfirmation(input) {
+    return { kind: 'create', path: input.path, content: input.content }
+  },
 }
diff --git a/packages/core/src/core/tools/file-tools/delete-file.ts b/packages/core/src/core/tools/file-tools/delete-file.ts
index c5de97b..0a6b97a 100644
--- a/packages/core/src/core/tools/file-tools/delete-file.ts
+++ b/packages/core/src/core/tools/file-tools/delete-file.ts
@@ -48,6 +48,9 @@ export const deleteFileTool: ToolDefinition<'DeleteFile', DeleteFileInput, Delet
   extractFileChange(output) {
     return { type: 'deleted', path: output.path, trashPath: output.trashPath }
   },
+  buildConfirmation(input) {
+    return { kind: 'delete', path: input.path }
+  },
 }
 
 function createTrashPath(path: string) {
diff --git a/packages/core/src/core/tools/file-tools/edit-file.ts b/packages/core/src/core/tools/file-tools/edit-file.ts
index 4f2d48c..504ff08 100644
--- a/packages/core/src/core/tools/file-tools/edit-file.ts
+++ b/packages/core/src/core/tools/file-tools/edit-file.ts
@@ -94,4 +94,7 @@ export const editFileTool: ToolDefinition<'EditFile', EditFileInput, EditFileOut
   extractFileChange(output) {
     return { type: 'updated', path: output.path }
   },
+  buildConfirmation(input) {
+    return { kind: 'edit', path: input.path, oldText: input.oldText, newText: input.newText }
+  },
 }
diff --git a/packages/core/src/core/tools/file-tools/rename-file.ts b/packages/core/src/core/tools/file-tools/rename-file.ts
index 3ace1cf..826fc48 100644
--- a/packages/core/src/core/tools/file-tools/rename-file.ts
+++ b/packages/core/src/core/tools/file-tools/rename-file.ts
@@ -54,4 +54,7 @@ export const renameFileTool: ToolDefinition<'RenameFile', RenameFileInput, Renam
   extractFileChange(output) {
     return { type: 'renamed', fromPath: output.fromPath, toPath: output.toPath }
   },
+  buildConfirmation(input) {
+    return { kind: 'rename', fromPath: input.fromPath, toPath: input.toPath }
+  },
 }
diff --git a/packages/core/src/core/tools/types.ts b/packages/core/src/core/tools/types.ts
index fe899dc..e7edc51 100644
--- a/packages/core/src/core/tools/types.ts
+++ b/packages/core/src/core/tools/types.ts
@@ -47,6 +47,16 @@ export type FileChange =
   | { type: 'renamed'; fromPath: string; toPath: string }
   | { type: 'deleted'; path: string; trashPath?: string }
 
+/**
+ * 写工具执行前构造的确认预览，用于「写入前确认」流程。
+ * create/edit 携带完整文本用于 diff；rename/delete 仅路径级预览。
+ */
+export type WriteConfirmation =
+  | { kind: 'create'; path: string; content: string }
+  | { kind: 'edit'; path: string; oldText: string; newText: string }
+  | { kind: 'rename'; fromPath: string; toPath: string }
+  | { kind: 'delete'; path: string }
+
 export type ToolDefinition<TName extends CoreToolName, TInput, TOutput> = {
   name: TName
   description: string
@@ -59,6 +69,11 @@ export type ToolDefinition<TName extends CoreToolName, TInput, TOutput> = {
    * 返回 undefined 表示该 output 不产生文件变更。
    */
   extractFileChange?(output: TOutput): FileChange | undefined
+  /**
+   * 写工具用它构造写入前确认预览；只读工具不实现。
+   * 入参是经过 validateInput 校验的强类型 input，执行前调用。
+   */
+  buildConfirmation?(input: TInput): WriteConfirmation
 }
 
 export type ReadFileInput = {
diff --git a/packages/core/src/services/agent-service.ts b/packages/core/src/services/agent-service.ts
index d8f7206..16736cf 100644
--- a/packages/core/src/services/agent-service.ts
+++ b/packages/core/src/services/agent-service.ts
@@ -4,7 +4,8 @@ import {
 } from '../core/chat/session'
 import { deriveChatTargetFromPath } from '../core/chat/target'
 import { readScenePrompt, readSystemPrompt } from '../core/fs/project-fs'
-import type { FileChange } from '../core/tools/types'
+import type { ConfirmHandler } from '../core/agent/tool-execution'
+import type { FileChange, WriteConfirmation } from '../core/tools/types'
 import type { ChatMessage, ChatSessionState, ChatTargetContext } from '../types/chat'
 
 import {
@@ -16,16 +17,26 @@ import type {
   ChatMessageView,
   ChatSessionView,
   ChatTargetView,
+  FileChangeConfirmationView,
   NovAiError,
   RunAgentTurnInput,
   RunAgentTurnResult,
   ToolCallView,
   ToolNameView,
   ToolResultView,
+  WriteConfirmationView,
 } from './types'
 
 const sessionMap = new Map<string, ChatSessionState>()
 
+// 确认注册表：confirmationId -> resolve。UI 调 respondConfirmation 时取出来 resolve，
+// 唤醒在 confirm 回调里 await 的 Agent Loop。
+type PendingConfirmation = {
+  projectId: string
+  resolve: (decision: { accepted: boolean }) => void
+}
+const confirmationMap = new Map<string, PendingConfirmation>()
+
 export function deriveTargetFromPath(path?: string | null): ChatTargetView | null {
   return toChatTargetView(deriveChatTargetFromPath(path))
 }
@@ -64,6 +75,10 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
       project.handle,
       project.config.settings.activeScenePromptPath,
     )
+    // 写工具确认回调：构造预览 → 发 confirmation-required 事件 → 等 UI 调 respondConfirmation。
+    const confirm: ConfirmHandler | undefined = input.onEvent
+      ? (request) => requestConfirmation(input.projectId, request, input.onEvent!)
+      : undefined
     const turn = await runChatTurn({
       session: previousSession,
       input: {
@@ -75,6 +90,7 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
         scenePrompt,
         activeFilePath: input.activeFilePath,
         signal: input.signal,
+        confirm,
       },
       onEvent(event) {
         emitMessageEvent(event.message, input.onEvent)
@@ -99,6 +115,8 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
     input.onEvent?.({ type: 'run-finish', result })
     return result
   } catch (error) {
+    // 出错时清理未决确认，避免注册表泄漏 / UI 卡在等待态。
+    rejectPendingConfirmations(input.projectId)
     const serviceError = toNovAiError(error)
     input.onEvent?.({ type: 'run-error', error: serviceError })
     throw error
@@ -110,6 +128,90 @@ function findSessionById(projectId: string, sessionId: string) {
   return session?.sessionId === sessionId ? session : null
 }
 
+/**
+ * 构造一次写工具确认：发 confirmation-required 事件，返回 Promise 等待 respondConfirmation。
+ * Agent Loop 在 confirm 回调里 await 它，从而在用户决定前暂停。
+ */
+function requestConfirmation(
+  projectId: string,
+  request: { call: { id: string; name: ToolNameView }; confirmation: WriteConfirmation },
+  onEvent: (event: AgentUiEvent) => void,
+): Promise<{ accepted: boolean }> {
+  const confirmationId = createRunId()
+  const view: FileChangeConfirmationView = {
+    id: confirmationId,
+    toolName: request.call.name,
+    title: buildConfirmationTitle(request.confirmation),
+    summary: buildConfirmationSummary(request.confirmation),
+    confirmation: toWriteConfirmationView(request.confirmation),
+  }
+
+  onEvent({ type: 'confirmation-required', request: view })
+
+  return new Promise<{ accepted: boolean }>((resolve) => {
+    confirmationMap.set(confirmationId, { projectId, resolve })
+  })
+}
+
+/** UI 调用：响应对某次写工具确认的接受/拒绝，唤醒等待中的 Agent Loop。 */
+export function respondConfirmation(confirmationId: string, accepted: boolean) {
+  const pending = confirmationMap.get(confirmationId)
+  if (!pending) {
+    return
+  }
+  confirmationMap.delete(confirmationId)
+  pending.resolve({ accepted })
+}
+
+/** 清理某项目的全部未决确认，按拒绝 resolve（出错/停止时调用）。 */
+function rejectPendingConfirmations(projectId: string) {
+  for (const [id, pending] of confirmationMap) {
+    if (pending.projectId === projectId) {
+      confirmationMap.delete(id)
+      pending.resolve({ accepted: false })
+    }
+  }
+}
+
+function toWriteConfirmationView(confirmation: WriteConfirmation): WriteConfirmationView {
+  switch (confirmation.kind) {
+    case 'create':
+      return { kind: 'create', path: confirmation.path, content: confirmation.content }
+    case 'edit':
+      return { kind: 'edit', path: confirmation.path, oldText: confirmation.oldText, newText: confirmation.newText }
+    case 'rename':
+      return { kind: 'rename', fromPath: confirmation.fromPath, toPath: confirmation.toPath }
+    case 'delete':
+      return { kind: 'delete', path: confirmation.path }
+  }
+}
+
+function buildConfirmationTitle(confirmation: WriteConfirmation): string {
+  switch (confirmation.kind) {
+    case 'create':
+      return `新建文件：${confirmation.path}`
+    case 'edit':
+      return `修改文件：${confirmation.path}`
+    case 'rename':
+      return `重命名：${confirmation.fromPath} → ${confirmation.toPath}`
+    case 'delete':
+      return `删除文件：${confirmation.path}`
+  }
+}
+
+function buildConfirmationSummary(confirmation: WriteConfirmation): string {
+  switch (confirmation.kind) {
+    case 'create':
+      return `将新建 ${confirmation.path}（${confirmation.content.length} 字符）`
+    case 'edit':
+      return `将修改 ${confirmation.path}（替换 ${confirmation.oldText.length} 字符）`
+    case 'rename':
+      return `将 ${confirmation.fromPath} 重命名为 ${confirmation.toPath}`
+    case 'delete':
+      return `将删除 ${confirmation.path}（移入回收站）`
+  }
+}
+
 function emitMessageEvent(
   message: ChatMessage,
   onEvent?: (event: AgentUiEvent) => void,
diff --git a/packages/core/src/services/types.ts b/packages/core/src/services/types.ts
index c902227..56a4f75 100644
--- a/packages/core/src/services/types.ts
+++ b/packages/core/src/services/types.ts
@@ -337,12 +337,19 @@ export type RunAgentTurnResult = {
   session: ChatSessionView
 }
 
+export type WriteConfirmationView =
+  | { kind: 'create'; path: string; content: string }
+  | { kind: 'edit'; path: string; oldText: string; newText: string }
+  | { kind: 'rename'; fromPath: string; toPath: string }
+  | { kind: 'delete'; path: string }
+
 export type FileChangeConfirmationView = {
   id: string
   toolName: ToolNameView
   title: string
   summary: string
-  changedFiles: ChangedFileView[]
+  /** 写工具执行前的预览数据，用于 UI 展示 diff。 */
+  confirmation: WriteConfirmationView
 }
 
 export type AgentUiEvent =
diff --git a/packages/core/src/types/chat.ts b/packages/core/src/types/chat.ts
index 20f4de5..55b06db 100644
--- a/packages/core/src/types/chat.ts
+++ b/packages/core/src/types/chat.ts
@@ -1,6 +1,7 @@
 import type { ProjectConfig, ProjectSnapshot } from './project'
 import type { RetrievalResult } from './rag'
 import type { AgentMessage } from '../core/agent/messages'
+import type { ConfirmHandler } from '../core/agent/tool-execution'
 
 export type ChatToolName =
   | 'ReadFile'
@@ -152,6 +153,8 @@ export type ChatTurnInput = {
   activeFilePath?: string | null
   /** 用户停止信号，透传到 Agent Loop。 */
   signal?: AbortSignal
+  /** 写工具确认回调，透传到 Agent Loop。 */
+  confirm?: ConfirmHandler
 }
 
 export type ChatTurnResult = {

From b0651e773f3ba124df1418ff0fa96d35e36ca58b Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 01:10:43 +0800
Subject: [PATCH 18/36] =?UTF-8?q?refactor(store):=20=E6=B8=85=E7=90=86?=
 =?UTF-8?q?=E6=97=A7=E7=A1=AE=E8=AE=A4=E6=B5=81=E7=A8=8B=E6=AD=BB=E4=BB=A3?=
 =?UTF-8?q?=E7=A0=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

删除未被模型驱动 Agent Loop 调用的旧残留：
- session.ts: confirmPendingFileChange / discardPendingFileChange /
  createPendingFileChange / callTool / loadRecentChapters /
  flattenChapterPaths 及 analyzeTurnMode / buildUserPrompt 等 helper
  与对应 import（readProjectTextFile / createToolRuntimeContext 等），
  共约 390 行。
- chat/tools.ts: 整个文件删除（旧 ToolDefinition.call 体系，零外部引用）。
- types/chat.ts: 删除 PendingFileChange / ToolRuntimeContext / 旧
  ToolDefinition 类型与 ChatSessionState.pendingFileChange /
  lastTaskType 字段。

新确认流程（commit 0707809）已替代这些旧代码。
---
 packages/core/src/core/chat/session.ts | 392 -------------------------
 packages/core/src/core/chat/tools.ts   | 102 -------
 packages/core/src/types/chat.ts        |  35 ---
 3 files changed, 529 deletions(-)
 delete mode 100644 packages/core/src/core/chat/tools.ts

diff --git a/packages/core/src/core/chat/session.ts b/packages/core/src/core/chat/session.ts
index bf9da69..b778930 100644
--- a/packages/core/src/core/chat/session.ts
+++ b/packages/core/src/core/chat/session.ts
@@ -1,4 +1,3 @@
-import { readProjectTextFile } from '../fs/project-fs'
 import { buildAgentSystemPrompt, buildAgentUserContext } from '../agent/prompt'
 import { query } from '../agent/query'
 import { createAgentTools } from '../agent/tools'
@@ -6,13 +5,6 @@ import { createLogId, writeAgentLog } from '../logging/agent-log'
 import type { AgentQueryEvent } from '../agent/query'
 
 import { deriveChatTargetFromPath } from './target'
-import {
-  createToolRuntimeContext,
-  createFileTool,
-  editFileTool,
-  readFileTool,
-  ragSearchTool,
-} from './tools'
 
 import type {
   ChatMessage,
@@ -20,8 +12,6 @@ import type {
   ChatTargetContext,
   ChatTurnInput,
   ChatTurnResult,
-  PendingFileChange,
-  ToolDefinition,
 } from '../../types/chat'
 import type { AgentMessage } from '../agent/messages'
 import type { FileChange } from '../tools/types'
@@ -35,14 +25,6 @@ type RunChatTurnOptions = {
   onEvent?: (event: SessionEvent) => void
 }
 
-type ConfirmPendingFileChangeOptions = {
-  session: ChatSessionState
-  input: Pick<ChatTurnInput, 'project' | 'config'>
-  onEvent?: (event: SessionEvent) => void
-}
-
-type TurnMode = 'read-only' | 'edit-target' | 'create-chapter'
-
 export function createChatSession(projectId: string): ChatSessionState {
   return {
     sessionId: createId('session'),
@@ -60,12 +42,10 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
     ...options.session,
     status: 'running',
     lastWrittenPath: undefined,
-    pendingFileChange: undefined,
   }
 
   const target = deriveChatTargetFromPath(input.activeFilePath)
   session.currentTarget = target
-  session.lastTaskType = undefined
   const runId = createLogId('run')
 
   void writeAgentLog(input.project, {
@@ -491,231 +471,6 @@ function buildAgentMessages(input: {
   ]
 }
 
-export async function confirmPendingFileChange(
-  options: ConfirmPendingFileChangeOptions,
-): Promise<ChatTurnResult> {
-  const { input, onEvent } = options
-  const session: ChatSessionState = {
-    ...options.session,
-    status: 'running',
-  }
-  const pendingFileChange = session.pendingFileChange
-
-  if (!pendingFileChange) {
-    const message = '当前没有等待确认的文件变更'
-    session.status = 'error'
-    pushErrorMessage(session, message, true, onEvent)
-    throw new Error(message)
-  }
-
-  const runtime = createToolRuntimeContext({
-    project: input.project,
-    config: input.config,
-    target: session.currentTarget,
-    session,
-  })
-
-  if (pendingFileChange.type === 'edit') {
-    await callTool(
-      editFileTool,
-      {
-        path: pendingFileChange.path,
-        oldText: pendingFileChange.oldText,
-        newText: pendingFileChange.newText,
-      },
-      runtime,
-      session,
-      onEvent,
-    )
-  } else {
-    await callTool(
-      createFileTool,
-      {
-        path: pendingFileChange.path,
-        content: pendingFileChange.content,
-      },
-      runtime,
-      session,
-      onEvent,
-    )
-  }
-
-  session.lastWrittenPath = pendingFileChange.path
-  session.pendingFileChange = undefined
-
-  pushMessage(
-    session,
-    {
-      id: createId('message'),
-      role: 'assistant',
-      kind: 'action-summary',
-      summary: `已确认并写回 ${pendingFileChange.path}`,
-      targetPath: pendingFileChange.path,
-      relatedPaths: session.lastRagResult?.candidates.slice(0, 3).map((item) => item.sourcePath) ?? [],
-      createdAt: new Date().toISOString(),
-    },
-    onEvent,
-  )
-
-  session.status = 'waiting-user'
-
-  return {
-    session,
-    target: session.currentTarget,
-    writtenPath: pendingFileChange.path,
-  }
-}
-
-export function discardPendingFileChange(session: ChatSessionState): ChatSessionState {
-  if (!session.pendingFileChange) {
-    return session
-  }
-
-  return {
-    ...session,
-    status: 'waiting-user',
-    pendingFileChange: undefined,
-    messages: [
-      ...session.messages,
-      {
-        id: createId('message'),
-        role: 'assistant',
-        kind: 'action-summary',
-        summary: `已放弃 ${session.pendingFileChange.path} 的待写入草稿。`,
-        targetPath: session.pendingFileChange.path,
-        createdAt: new Date().toISOString(),
-      },
-    ],
-  }
-}
-
-function createPendingFileChange(input: {
-  taskType: Exclude<TurnMode, 'read-only'>
-  targetPath: string
-  targetFileContent: string
-  draftText: string
-}): PendingFileChange {
-  if (input.taskType === 'edit-target') {
-    return {
-      id: createId('pending-change'),
-      type: 'edit',
-      path: input.targetPath,
-      oldText: input.targetFileContent,
-      newText: input.draftText,
-      createdAt: new Date().toISOString(),
-    }
-  }
-
-  return {
-    id: createId('pending-change'),
-    type: 'create',
-    path: input.targetPath,
-    content: input.draftText,
-    createdAt: new Date().toISOString(),
-  }
-}
-
-async function callTool<TInput, TOutput>(
-  tool: ToolDefinition<TInput, TOutput>,
-  input: TInput,
-  runtime: ReturnType<typeof createToolRuntimeContext>,
-  session: ChatSessionState,
-  onEvent?: (event: SessionEvent) => void,
-) {
-  pushMessage(
-    session,
-    {
-      id: createId('message'),
-      role: 'system',
-      kind: 'tool-call',
-      toolName: tool.name,
-      inputSummary: tool.summarizeInput(input),
-      createdAt: new Date().toISOString(),
-    },
-    onEvent,
-  )
-
-  try {
-    const output = await tool.call(tool.validateInput(input), runtime)
-
-    pushMessage(
-      session,
-      {
-        id: createId('message'),
-        role: 'system',
-        kind: 'tool-result',
-        toolName: tool.name,
-        ok: true,
-        resultSummary: tool.summarizeOutput(output),
-        createdAt: new Date().toISOString(),
-      },
-      onEvent,
-    )
-
-    return output
-  } catch (error) {
-    const message = error instanceof Error ? error.message : `${tool.name} 执行失败`
-    session.status = 'error'
-    pushMessage(
-      session,
-      {
-        id: createId('message'),
-        role: 'system',
-        kind: 'tool-result',
-        toolName: tool.name,
-        ok: false,
-        resultSummary: message,
-        createdAt: new Date().toISOString(),
-      },
-      onEvent,
-    )
-    pushErrorMessage(session, message, true, onEvent)
-    throw error
-  }
-}
-
-async function loadRecentChapters(
-  project: ChatTurnInput['project'],
-  limit: number,
-  excludedPath?: string,
-) {
-  const chapterPaths = flattenChapterPaths(project.tree)
-    .filter((path) => path !== excludedPath)
-    .sort((left, right) => right.localeCompare(left, 'zh-Hans-CN'))
-    .slice(0, limit)
-
-  return Promise.all(
-    chapterPaths.map(async (path) => ({
-      path,
-      title: path.split('/').pop() || path,
-      content: await readProjectTextFile(project.handle, path),
-    })),
-  )
-}
-
-function flattenChapterPaths(tree: ChatTurnInput['project']['tree']) {
-  const stack = [...tree]
-  const paths: string[] = []
-
-  while (stack.length > 0) {
-    const node = stack.shift()
-
-    if (!node) {
-      continue
-    }
-
-    if (node.kind === 'file' && node.path.startsWith('chapters/') && /\.(txt|md)$/i.test(node.name)) {
-      paths.push(node.path)
-      continue
-    }
-
-    if (node.children?.length) {
-      stack.unshift(...node.children)
-    }
-  }
-
-  return paths
-}
 
 function pushMessage(
   session: ChatSessionState,
@@ -779,153 +534,6 @@ function createContextSummary(target: ChatTargetContext | null): ChatMessage {
   }
 }
 
-function shouldUseRag(instruction: string, target: ChatTargetContext | null) {
-  if (isReadOnlyIntent(instruction)) {
-    return true
-  }
-
-  if (target?.type === 'chapter' || target?.type === 'element') {
-    return true
-  }
-
-  return /人物|角色|地点|设定|世界观|剧情|线索|前文|一致性/.test(instruction)
-}
-
-function analyzeTurnMode(
-  instruction: string,
-  target: ChatTargetContext | null,
-): TurnMode {
-  const normalized = instruction.trim()
-
-  if (isReadOnlyIntent(normalized)) {
-    return 'read-only'
-  }
-
-  if (/下一章|新章节|写下一章|写一章|续写|继续写/.test(normalized)) {
-    return 'create-chapter'
-  }
-
-  if (!target?.primaryPath) {
-    return 'create-chapter'
-  }
-
-  if (target.type !== 'chapter') {
-    return 'edit-target'
-  }
-
-  if (/创建|新建/.test(normalized) && /章节|一章/.test(normalized)) {
-    return 'create-chapter'
-  }
-
-  return 'edit-target'
-}
-
-function isReadOnlyIntent(instruction: string) {
-  return /看一下|总结|概括|分析|梳理|列出|有哪些|都写了哪些|回顾|介绍一下|说明一下/.test(instruction)
-}
-
-function resolveWritePath(
-  project: ChatTurnInput['project'],
-  target: ChatTargetContext | null,
-  taskType: 'edit-target' | 'create-chapter',
-) {
-  if (taskType === 'edit-target' && target?.primaryPath) {
-    return target.primaryPath
-  }
-
-  return buildNextChapterPath(project)
-}
-
-function buildNextChapterPath(project: ChatTurnInput['project']) {
-  const chapterPaths = flattenChapterPaths(project.tree)
-  const maxSequence = chapterPaths.reduce((max, path) => {
-    const matched = path.match(/(\d{1,4})/)
-    if (!matched) {
-      return max
-    }
-
-    return Math.max(max, Number(matched[1]))
-  }, 0)
-
-  const nextSequence = String(maxSequence + 1).padStart(3, '0')
-  return `chapters/第${nextSequence}章-未命名章节.txt`
-}
-
-function summarizeTurnMode(mode: TurnMode) {
-  if (mode === 'read-only') {
-    return '本轮任务类型：只读分析，不修改文件'
-  }
-
-  if (mode === 'create-chapter') {
-    return '本轮任务类型：生成新章节'
-  }
-
-  return '本轮任务类型：修改当前目标文件'
-}
-
-function summarizeRag(result: ChatSessionState['lastRagResult']) {
-  if (!result || result.candidates.length === 0) {
-    return '无相关 RAG 候选'
-  }
-
-  return result.candidates
-    .slice(0, 5)
-    .map((item, index) => `${index + 1}. ${item.name} - ${item.summary}`)
-    .join('\n')
-}
-
-function summarizeRagContext(result: ChatSessionState['lastRagResult']) {
-  if (!result || result.candidates.length === 0) {
-    return 'RAG 未命中可用要素上下文'
-  }
-
-  return `RAG 已补充 ${result.candidates.length} 条候选，上下文优先使用前 ${Math.min(result.candidates.length, 5)} 条`
-}
-
-function buildUserPrompt(input: {
-  instruction: string
-  target: ChatTargetContext | null
-  targetFileContent: string
-  recentChapters: Array<{ path: string; title: string; content: string }>
-  ragSummary: string
-}) {
-  return [
-    '你是 NovAI 第一阶段会话引擎中的小说写作智能体。',
-    '你的输出会直接写回目标文件，所以请只输出最终文件内容，不要额外解释、不要加前言、不要用代码块。',
-    '如果任务是只读分析，请直接输出给用户看的分析结果，不要伪装成小说正文或文件内容。',
-    '如果任务是修改已有文件，请输出完整修改后的全文，而不是局部片段。',
-    '如果任务是生成新章节，请输出完整 Markdown 章节正文。',
-    '保持与当前项目设定、人物状态、情节连续性一致；若上下文不足，优先保守延续现有内容。',
-    `用户意图：${input.instruction}`,
-    `当前目标：${input.target?.displayName ?? '当前项目'}`,
-    `目标路径：${input.target?.primaryPath ?? '将创建新章节文件'}`,
-    `任务类型：${input.target?.primaryPath ? '基于当前目标执行分析或修改' : '新章节生成或项目级分析'}`,
-    '当前文件内容：',
-    input.targetFileContent || '当前目标文件为空。',
-    '近期章节上下文：',
-    formatRecentChapters(input.recentChapters),
-    'RAG 检索摘要：',
-    input.ragSummary,
-    '输出要求：',
-    '1. 只返回最终文件内容。',
-    '2. 不要解释你做了什么。',
-    '3. 不要输出 JSON、标签、标题说明或额外注释。',
-  ].join('\n\n')
-}
-
-function formatRecentChapters(chapters: Array<{ path: string; title: string; content: string }>) {
-  if (chapters.length === 0) {
-    return '无可用近期章节。'
-  }
-
-  return chapters
-    .map((chapter, index) => {
-      const excerpt = chapter.content.trim().slice(0, 1200)
-      return `${index + 1}. ${chapter.path}\n${excerpt || '（空内容）'}`
-    })
-    .join('\n\n')
-}
-
 function createId(prefix: string) {
   return `${prefix}-${Math.random().toString(36).slice(2, 10)}`
 }
diff --git a/packages/core/src/core/chat/tools.ts b/packages/core/src/core/chat/tools.ts
deleted file mode 100644
index 623bb87..0000000
--- a/packages/core/src/core/chat/tools.ts
+++ /dev/null
@@ -1,102 +0,0 @@
-import { searchRagCandidates } from '../rag/search'
-import {
-  createFileTool as coreCreateFileTool,
-  editFileTool as coreEditFileTool,
-  readFileTool as coreReadFileTool,
-} from '../tools/file-tools'
-
-import type {
-  ToolDefinition,
-  ToolRuntimeContext,
-} from '../../types/chat'
-import type { RetrievalResult } from '../../types/rag'
-import type {
-  CreateFileInput,
-  CreateFileOutput,
-  EditFileInput,
-  EditFileOutput,
-  ReadFileInput,
-  ReadFileOutput,
-} from '../tools/types'
-
-export type RagSearchInput = {
-  query: string
-  topK?: number
-}
-
-function asObject(input: unknown) {
-  if (!input || typeof input !== 'object') {
-    throw new Error('工具输入必须是对象')
-  }
-
-  return input as Record<string, unknown>
-}
-
-export const readFileTool: ToolDefinition<ReadFileInput, ReadFileOutput> = {
-  name: 'ReadFile',
-  description: coreReadFileTool.description,
-  validateInput: coreReadFileTool.validateInput,
-  async call(input, context) {
-    return coreReadFileTool.run(input, { project: context.project })
-  },
-  summarizeInput: coreReadFileTool.summarizeInput,
-  summarizeOutput: coreReadFileTool.summarizeOutput,
-}
-
-export const editFileTool: ToolDefinition<EditFileInput, EditFileOutput> = {
-  name: 'EditFile',
-  description: coreEditFileTool.description,
-  validateInput: coreEditFileTool.validateInput,
-  async call(input, context) {
-    return coreEditFileTool.run(input, { project: context.project })
-  },
-  summarizeInput: coreEditFileTool.summarizeInput,
-  summarizeOutput: coreEditFileTool.summarizeOutput,
-}
-
-export const createFileTool: ToolDefinition<CreateFileInput, CreateFileOutput> = {
-  name: 'CreateFile',
-  description: coreCreateFileTool.description,
-  validateInput: coreCreateFileTool.validateInput,
-  async call(input, context) {
-    return coreCreateFileTool.run(input, { project: context.project })
-  },
-  summarizeInput: coreCreateFileTool.summarizeInput,
-  summarizeOutput: coreCreateFileTool.summarizeOutput,
-}
-
-export const ragSearchTool: ToolDefinition<RagSearchInput, RetrievalResult> = {
-  name: 'RagSearch',
-  description: '基于项目要素索引做语义检索',
-  validateInput(input) {
-    const value = asObject(input)
-
-    if (typeof value.query !== 'string' || !value.query.trim()) {
-      throw new Error('RagSearch 需要有效的 query')
-    }
-
-    return {
-      query: value.query.trim(),
-      topK: typeof value.topK === 'number' ? value.topK : undefined,
-    }
-  },
-  async call(input, context) {
-    return searchRagCandidates({
-      projectId: context.project.id,
-      query: input.query,
-      topK: input.topK ?? context.config.settings.ragCandidateLimit,
-    }, context.config)
-  },
-  summarizeInput(input) {
-    return `检索与“${input.query}”相关的故事要素`
-  },
-  summarizeOutput(output) {
-    return output.total > 0
-      ? `共召回 ${output.total} 条候选`
-      : '索引中暂无可召回候选'
-  },
-}
-
-export function createToolRuntimeContext(context: ToolRuntimeContext): ToolRuntimeContext {
-  return context
-}
diff --git a/packages/core/src/types/chat.ts b/packages/core/src/types/chat.ts
index 55b06db..7d2e018 100644
--- a/packages/core/src/types/chat.ts
+++ b/packages/core/src/types/chat.ts
@@ -96,23 +96,6 @@ export type ChatTargetContext = {
 
 export type ChatSessionStatus = 'idle' | 'running' | 'waiting-user' | 'awaiting-confirmation' | 'error'
 
-export type PendingFileChange =
-  | {
-      id: string
-      type: 'edit'
-      path: string
-      oldText: string
-      newText: string
-      createdAt: string
-    }
-  | {
-      id: string
-      type: 'create'
-      path: string
-      content: string
-      createdAt: string
-    }
-
 export type ChatSessionState = {
   sessionId: string
   projectId: string
@@ -121,25 +104,7 @@ export type ChatSessionState = {
   status: ChatSessionStatus
   currentTarget: ChatTargetContext | null
   lastRagResult: RetrievalResult | null
-  pendingFileChange?: PendingFileChange
   lastWrittenPath?: string
-  lastTaskType?: 'read-only' | 'edit-target' | 'create-chapter'
-}
-
-export type ToolRuntimeContext = {
-  project: ProjectSnapshot
-  config: ProjectConfig
-  target: ChatTargetContext | null
-  session: ChatSessionState
-}
-
-export type ToolDefinition<TInput, TOutput> = {
-  name: ChatToolName
-  description: string
-  validateInput: (input: unknown) => TInput
-  call: (input: TInput, context: ToolRuntimeContext) => Promise<TOutput>
-  summarizeInput: (input: TInput) => string
-  summarizeOutput: (output: TOutput) => string
 }
 
 export type ChatTurnInput = {

From 924a5146964aa85b7ac50a164d3826d140586c87 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 01:23:43 +0800
Subject: [PATCH 19/36] =?UTF-8?q?docs(docs):=20=E5=90=8C=E6=AD=A5=20Agent?=
 =?UTF-8?q?=20=E6=8E=A7=E5=88=B6=E8=83=BD=E5=8A=9B=20Step=202/3=20?=
 =?UTF-8?q?=E8=90=BD=E5=9C=B0=E7=8A=B6=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs b/docs
index a14e6f6..c312e6d 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit a14e6f6b2df15f5baf46be3ad12189770f4e79d4
+Subproject commit c312e6d20732dcc730e2d76eca0832999d3fffa1

From e774d2cb57ec6a7c01438f7d4c54608725b9017f Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 02:11:13 +0800
Subject: [PATCH 20/36] =?UTF-8?q?feat(project):=20=E7=94=A8=E6=88=B7?=
 =?UTF-8?q?=E5=8D=B3=E6=97=B6=E5=B7=A5=E5=85=B7=E7=BA=A6=E6=9D=9F=E6=94=AF?=
 =?UTF-8?q?=E6=8C=81=E6=8C=87=E4=BB=A4=E8=A7=A3=E6=9E=90=E4=B8=8E=E6=89=A7?=
 =?UTF-8?q?=E8=A1=8C=E5=B1=82=E5=BC=BA=E5=88=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent Step 5：用户本轮说「不要读文件」「别改」等否定短语时，
自动解析并强制禁用对应工具，模型即使无视约束也拦得住。

约束机制（借鉴 Claude Code 双层防御）：
- 工具可见性过滤（filterAvailableTools）：被禁工具的 schema 不发
  给模型，从源头减少无效调用往返；input.tools 完整 map 保留做兜底。
- 执行层硬拦截（isToolDisabledByPolicy）：在 tool-call 事件后、写
  确认前判定，命中直接返回禁用结果回灌模型，100% 兜底。
- user context 动态注入约束声明（describeActivePolicy）：只在有
  约束时注入，说明具体禁了哪些工具，引导模型不绕过。

识别与分类：
- 新增 tool-policy.ts：parseToolPolicy 关键词解析（否定词+读/写
  动作词窗口匹配，「不要碰文件」通用全禁）+ 按 isReadOnly 二分
  （不硬编码工具名，未来加新工具自动归类）+ describePolicyDenial。
- 透传链路照抄 confirm：agent-service 解析 instruction 生成
  toolPolicy → ChatTurnInput → session → query → runAgentTools →
  executeAgentTool。
- 约束 per-turn 即时，不持久化到 session。

测试：tool-policy 19 个用例（解析 6 + 判定 3 + 描述 2 + 过滤 4 +
声明 4）+ tool-execution 4 个策略用例（禁读拒绝 / 禁写拒绝 / 允许
正常 / 策略优先于确认不弹窗）。
---
 packages/core/src/core/agent/prompt.ts        |   9 ++
 packages/core/src/core/agent/query.ts         |  12 +-
 .../src/core/agent/tool-execution.test.ts     |  80 ++++++++++
 .../core/src/core/agent/tool-execution.ts     |  22 +++
 .../core/src/core/agent/tool-orchestration.ts |   4 +
 .../core/src/core/agent/tool-policy.test.ts   | 131 ++++++++++++++++
 packages/core/src/core/agent/tool-policy.ts   | 143 ++++++++++++++++++
 packages/core/src/core/chat/session.ts        |   4 +
 packages/core/src/services/agent-service.ts   |   4 +
 packages/core/src/types/chat.ts               |   3 +
 10 files changed, 410 insertions(+), 2 deletions(-)
 create mode 100644 packages/core/src/core/agent/tool-policy.test.ts
 create mode 100644 packages/core/src/core/agent/tool-policy.ts

diff --git a/packages/core/src/core/agent/prompt.ts b/packages/core/src/core/agent/prompt.ts
index e045ae8..522c8b3 100644
--- a/packages/core/src/core/agent/prompt.ts
+++ b/packages/core/src/core/agent/prompt.ts
@@ -1,5 +1,6 @@
 import type { ChatTargetContext } from '../../types/chat'
 import type { ProjectSnapshot } from '../../types/project'
+import { describeActivePolicy, type ToolPolicy } from './tool-policy'
 
 export function buildAgentSystemPrompt(input: {
   systemPrompt?: string
@@ -63,6 +64,8 @@ export function buildAgentUserContext(input: {
   quote?: string
   project: ProjectSnapshot
   target: ChatTargetContext | null
+  /** 本轮工具约束；有禁用时注入显式声明，让模型在 prompt 层感知。 */
+  policy?: ToolPolicy
 }) {
   const target = input.target?.primaryPath
     ? `${input.target.displayName} (${input.target.primaryPath})`
@@ -76,6 +79,12 @@ export function buildAgentUserContext(input: {
     lines.push('', '用户引用的内容：', input.quote.trim())
   }
 
+  // 本轮工具约束声明（软约束）：让模型主动避免调用被禁工具。
+  const policyNotice = input.policy ? describeActivePolicy(input.policy) : ''
+  if (policyNotice) {
+    lines.push('', policyNotice)
+  }
+
   lines.push(
     '',
     `当前项目：${input.project.name}`,
diff --git a/packages/core/src/core/agent/query.ts b/packages/core/src/core/agent/query.ts
index 6d1d1db..eefbe84 100644
--- a/packages/core/src/core/agent/query.ts
+++ b/packages/core/src/core/agent/query.ts
@@ -1,6 +1,7 @@
 import { streamAgentCompletion, AgentAbortedError } from './llm'
 import { runAgentTools } from './tool-orchestration'
 import type { ConfirmHandler, ToolExecutionEvent } from './tool-execution'
+import { filterAvailableTools, type ToolPolicy } from './tool-policy'
 import type { ProjectConfig, ProjectSnapshot } from '../../types/project'
 import type {
   AgentAssistantMessage,
@@ -33,6 +34,8 @@ export async function query(input: {
   signal?: AbortSignal
   /** 写工具确认回调，透传到工具执行层。 */
   confirm?: ConfirmHandler
+  /** 用户即时工具约束，透传到工具执行层。 */
+  toolPolicy?: ToolPolicy
   onEvent?: (event: AgentQueryEvent) => void
 }): Promise<AgentMessage[]> {
   let messages = [...input.messages]
@@ -40,6 +43,10 @@ export async function query(input: {
   const readFileStates = new Map<string, ReadFileState>()
   const enableDebugLogging = Boolean(input.config.settings.enableDebugLogging)
 
+  // 被用户约束禁用的工具不发给模型（可见性过滤），从源头减少无效调用往返。
+  // input.tools（完整 map）仍传给 runAgentTools 做兜底，万一模型仍生成被禁工具调用，执行层会拦住。
+  const availableTools = filterAvailableTools(Object.values(input.tools), input.toolPolicy)
+
   for (let turn = 0; turn < maxTurns; turn += 1) {
     const step = turn + 1
 
@@ -58,7 +65,7 @@ export async function query(input: {
         ? createModelStartDebugInfo({
           config: input.config,
           messages,
-          toolCount: Object.keys(input.tools).length,
+          toolCount: availableTools.length,
         })
         : undefined,
     })
@@ -71,7 +78,7 @@ export async function query(input: {
           apiKey: input.config.llm.apiKey,
           model: input.config.llm.model,
           messages,
-          tools: Object.values(input.tools).map((tool) => tool.schema),
+          tools: availableTools.map((tool) => tool.schema),
           signal: input.signal,
         },
         () => {},
@@ -138,6 +145,7 @@ export async function query(input: {
       readFileStates,
       signal: input.signal,
       confirm: input.confirm,
+      toolPolicy: input.toolPolicy,
       onEvent: input.onEvent,
     })
 
diff --git a/packages/core/src/core/agent/tool-execution.test.ts b/packages/core/src/core/agent/tool-execution.test.ts
index e7f3ec3..a6c0f82 100644
--- a/packages/core/src/core/agent/tool-execution.test.ts
+++ b/packages/core/src/core/agent/tool-execution.test.ts
@@ -188,3 +188,83 @@ describe('executeAgentTool confirmation', () => {
     expect(result.content).toContain('用户拒绝')
   })
 })
+
+describe('executeAgentTool toolPolicy', () => {
+  it('rejects read tools when allowRead is false', async () => {
+    const run = vi.fn().mockResolvedValue({ path: 'chapters/001.txt', content: '内容' })
+    const tool = createStubTool({ name: 'ReadFile', isReadOnly: true, run })
+    const tools = { ReadFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    const result = await executeAgentTool({
+      call: createCall('ReadFile', { path: 'chapters/001.txt' }),
+      project: stubProject,
+      tools,
+      toolPolicy: { allowRead: false, allowWrite: true },
+    })
+
+    expect(run).not.toHaveBeenCalled()
+    expect(result.content).toContain('禁用')
+    expect(result.content).toContain('读取')
+    expect(result.fileChange).toBeUndefined()
+  })
+
+  it('rejects write tools when allowWrite is false', async () => {
+    const run = vi.fn().mockResolvedValue({})
+    const tool = createStubTool({
+      name: 'CreateFile',
+      run,
+      buildConfirmation: (input) => ({ kind: 'create', path: (input as { path: string }).path, content: '' }),
+    })
+    const tools = { CreateFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    const result = await executeAgentTool({
+      call: createCall('CreateFile', { path: 'chapters/new.txt' }),
+      project: stubProject,
+      tools,
+      toolPolicy: { allowRead: true, allowWrite: false },
+    })
+
+    expect(run).not.toHaveBeenCalled()
+    expect(result.content).toContain('禁用')
+    expect(result.content).toContain('修改')
+  })
+
+  it('executes normally when policy allows the tool', async () => {
+    const run = vi.fn().mockResolvedValue({ path: 'chapters/001.txt', content: '内容' })
+    const tool = createStubTool({ name: 'ReadFile', isReadOnly: true, run })
+    const tools = { ReadFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    const result = await executeAgentTool({
+      call: createCall('ReadFile', { path: 'chapters/001.txt' }),
+      project: stubProject,
+      tools,
+      toolPolicy: { allowRead: true, allowWrite: true },
+    })
+
+    expect(run).toHaveBeenCalledTimes(1)
+    expect(result.content).toBe('ReadFile 结果')
+  })
+
+  it('policy denial takes precedence over confirmation (no confirm popup for disabled tools)', async () => {
+    const run = vi.fn().mockResolvedValue({})
+    const confirm = vi.fn().mockResolvedValue({ accepted: true })
+    const tool = createStubTool({
+      name: 'EditFile',
+      run,
+      buildConfirmation: (input) => ({ kind: 'edit', path: (input as { path: string }).path, oldText: 'a', newText: 'b' }),
+    })
+    const tools = { EditFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    await executeAgentTool({
+      call: createCall('EditFile', { path: 'chapters/001.txt' }),
+      project: stubProject,
+      tools,
+      confirm,
+      toolPolicy: { allowRead: true, allowWrite: false },
+    })
+
+    // 被禁工具直接拒绝，不弹确认
+    expect(confirm).not.toHaveBeenCalled()
+    expect(run).not.toHaveBeenCalled()
+  })
+})
diff --git a/packages/core/src/core/agent/tool-execution.ts b/packages/core/src/core/agent/tool-execution.ts
index 98778d2..7dee063 100644
--- a/packages/core/src/core/agent/tool-execution.ts
+++ b/packages/core/src/core/agent/tool-execution.ts
@@ -2,6 +2,7 @@ import type { ProjectSnapshot } from '../../types/project'
 import type { AgentToolCall, AgentToolResultMessage } from './messages'
 import type { AgentRunnableToolMap } from './tools'
 import type { FileChange, ReadFileState, WriteConfirmation } from '../tools/types'
+import { type ToolPolicy, isToolDisabledByPolicy, describePolicyDenial } from './tool-policy'
 
 export type ToolExecutionEvent =
   | { type: 'tool-call'; call: AgentToolCall; inputSummary: string }
@@ -29,6 +30,8 @@ export async function executeAgentTool(input: {
   readFileStates?: Map<string, ReadFileState>
   /** 写工具确认回调；未传时不做确认（测试/只读场景）。 */
   confirm?: ConfirmHandler
+  /** 用户即时工具约束；命中则直接拒绝，不走确认流程。 */
+  toolPolicy?: ToolPolicy
   onEvent?: (event: ToolExecutionEvent) => void
 }): Promise<AgentToolResultMessage> {
   const tool = input.tools[input.call.name]
@@ -87,6 +90,25 @@ export async function executeAgentTool(input: {
     inputSummary: tool.core.summarizeInput(validatedInput),
   })
 
+  // 用户即时工具约束：命中则直接拒绝，不走确认流程。
+  // 这是硬约束，保证模型即使无视 system prompt 也拦得住。
+  if (input.toolPolicy && isToolDisabledByPolicy(tool, input.toolPolicy)) {
+    const reason = describePolicyDenial(tool, input.toolPolicy)
+    input.onEvent?.({
+      type: 'tool-result',
+      call: input.call,
+      ok: false,
+      resultSummary: `工具被禁用：${reason}`,
+    })
+
+    return {
+      role: 'tool',
+      toolCallId: input.call.id,
+      name: input.call.name,
+      content: `该工具本轮被禁用：${reason}。请遵守该约束，改用纯对话回答，或向用户确认是否解除限制后再试。`,
+    }
+  }
+
   // 写工具执行前确认：构造预览并等待用户决定。
   // 拒绝时不执行 run，返回「用户已拒绝」tool result 回灌模型，让其自然调整。
   if (!tool.isReadOnly && tool.core.buildConfirmation && input.confirm) {
diff --git a/packages/core/src/core/agent/tool-orchestration.ts b/packages/core/src/core/agent/tool-orchestration.ts
index d92f3f5..75ccdc6 100644
--- a/packages/core/src/core/agent/tool-orchestration.ts
+++ b/packages/core/src/core/agent/tool-orchestration.ts
@@ -1,5 +1,6 @@
 import { executeAgentTool } from './tool-execution'
 import type { ConfirmHandler, ToolExecutionEvent } from './tool-execution'
+import type { ToolPolicy } from './tool-policy'
 import type { ProjectSnapshot } from '../../types/project'
 import type { AgentToolCall, AgentToolResultMessage } from './messages'
 import type { AgentRunnableToolMap } from './tools'
@@ -14,6 +15,8 @@ export async function runAgentTools(input: {
   signal?: AbortSignal
   /** 写工具确认回调，透传给 executeAgentTool。 */
   confirm?: ConfirmHandler
+  /** 用户即时工具约束，透传给 executeAgentTool。 */
+  toolPolicy?: ToolPolicy
   onEvent?: (event: ToolExecutionEvent) => void
 }): Promise<AgentToolResultMessage[]> {
   const results: AgentToolResultMessage[] = []
@@ -49,6 +52,7 @@ export async function runAgentTools(input: {
       tools: input.tools,
       readFileStates: input.readFileStates,
       confirm: input.confirm,
+      toolPolicy: input.toolPolicy,
       onEvent: input.onEvent,
     }))
   }
diff --git a/packages/core/src/core/agent/tool-policy.test.ts b/packages/core/src/core/agent/tool-policy.test.ts
new file mode 100644
index 0000000..61120fc
--- /dev/null
+++ b/packages/core/src/core/agent/tool-policy.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  parseToolPolicy,
+  isToolDisabledByPolicy,
+  describePolicyDenial,
+  filterAvailableTools,
+  describeActivePolicy,
+  DEFAULT_TOOL_POLICY,
+} from './tool-policy'
+
+describe('parseToolPolicy', () => {
+  it('returns default policy when there is no constraint', () => {
+    expect(parseToolPolicy('帮我写下一章')).toEqual({ allowRead: true, allowWrite: true })
+    expect(parseToolPolicy('总结一下这个故事')).toEqual({ allowRead: true, allowWrite: true })
+    expect(parseToolPolicy('')).toEqual(DEFAULT_TOOL_POLICY)
+  })
+
+  it('disables read tools on read-denial phrases', () => {
+    expect(parseToolPolicy('直接回答，不要读任何文件')).toEqual({ allowRead: false, allowWrite: true })
+    expect(parseToolPolicy('别看文件，凭记忆回答')).toEqual({ allowRead: false, allowWrite: true })
+    expect(parseToolPolicy('不要查项目文件')).toEqual({ allowRead: false, allowWrite: true })
+    expect(parseToolPolicy('不用找文件了')).toEqual({ allowRead: false, allowWrite: true })
+  })
+
+  it('disables write tools on write-denial phrases', () => {
+    expect(parseToolPolicy('只分析，不要写文件')).toEqual({ allowRead: true, allowWrite: false })
+    expect(parseToolPolicy('别改这个章节')).toEqual({ allowRead: true, allowWrite: false })
+    expect(parseToolPolicy('不要新建任何文件')).toEqual({ allowRead: true, allowWrite: false })
+    expect(parseToolPolicy('不要删除这个文件')).toEqual({ allowRead: true, allowWrite: false })
+  })
+
+  it('disables both read and write on combined denials', () => {
+    expect(parseToolPolicy('不要读也不要写文件')).toEqual({ allowRead: false, allowWrite: false })
+    expect(parseToolPolicy('别看文件也别改')).toEqual({ allowRead: false, allowWrite: false })
+  })
+
+  it('handles generic denials like 不要碰文件', () => {
+    expect(parseToolPolicy('不要碰任何文件')).toEqual({ allowRead: false, allowWrite: false })
+    expect(parseToolPolicy('别动文件')).toEqual({ allowRead: false, allowWrite: false })
+  })
+
+  it('does not trigger on affirmative mentions', () => {
+    // 「读」「写」单独出现但无否定前缀，不应禁用
+    expect(parseToolPolicy('读一下第一章然后写第二章')).toEqual({ allowRead: true, allowWrite: true })
+    expect(parseToolPolicy('请读取文件并修改')).toEqual({ allowRead: true, allowWrite: true })
+  })
+})
+
+describe('isToolDisabledByPolicy', () => {
+  const readOnlyTool = { isReadOnly: true }
+  const writeTool = { isReadOnly: false }
+
+  it('allows everything under default policy', () => {
+    expect(isToolDisabledByPolicy(readOnlyTool, DEFAULT_TOOL_POLICY)).toBe(false)
+    expect(isToolDisabledByPolicy(writeTool, DEFAULT_TOOL_POLICY)).toBe(false)
+  })
+
+  it('disables read tools when allowRead is false', () => {
+    const policy = { allowRead: false, allowWrite: true }
+    expect(isToolDisabledByPolicy(readOnlyTool, policy)).toBe(true)
+    expect(isToolDisabledByPolicy(writeTool, policy)).toBe(false)
+  })
+
+  it('disables write tools when allowWrite is false', () => {
+    const policy = { allowRead: true, allowWrite: false }
+    expect(isToolDisabledByPolicy(readOnlyTool, policy)).toBe(false)
+    expect(isToolDisabledByPolicy(writeTool, policy)).toBe(true)
+  })
+})
+
+describe('describePolicyDenial', () => {
+  it('describes read denial', () => {
+    expect(describePolicyDenial({ isReadOnly: true }, { allowRead: false, allowWrite: true })).toContain('读取')
+  })
+
+  it('describes write denial', () => {
+    expect(describePolicyDenial({ isReadOnly: false }, { allowRead: true, allowWrite: false })).toContain('修改')
+  })
+})
+
+describe('filterAvailableTools', () => {
+  const tools = [
+    { name: 'ReadFile', isReadOnly: true },
+    { name: 'ListDirectory', isReadOnly: true },
+    { name: 'EditFile', isReadOnly: false },
+    { name: 'CreateFile', isReadOnly: false },
+  ]
+
+  it('returns all tools when no policy', () => {
+    expect(filterAvailableTools(tools, undefined)).toHaveLength(4)
+  })
+
+  it('filters out read tools when allowRead is false', () => {
+    const result = filterAvailableTools(tools, { allowRead: false, allowWrite: true })
+    expect(result.map((t) => t.name)).toEqual(['EditFile', 'CreateFile'])
+  })
+
+  it('filters out write tools when allowWrite is false', () => {
+    const result = filterAvailableTools(tools, { allowRead: true, allowWrite: false })
+    expect(result.map((t) => t.name)).toEqual(['ReadFile', 'ListDirectory'])
+  })
+
+  it('filters out everything when both are false', () => {
+    expect(filterAvailableTools(tools, { allowRead: false, allowWrite: false })).toHaveLength(0)
+  })
+})
+
+describe('describeActivePolicy', () => {
+  it('returns empty string when no constraint', () => {
+    expect(describeActivePolicy(DEFAULT_TOOL_POLICY)).toBe('')
+  })
+
+  it('mentions read tools when allowRead is false', () => {
+    const desc = describeActivePolicy({ allowRead: false, allowWrite: true })
+    expect(desc).toContain('读取类工具')
+    expect(desc).not.toContain('写入类工具')
+  })
+
+  it('mentions write tools when allowWrite is false', () => {
+    const desc = describeActivePolicy({ allowRead: true, allowWrite: false })
+    expect(desc).toContain('写入类工具')
+    expect(desc).not.toContain('读取类工具')
+  })
+
+  it('mentions both when both are false', () => {
+    const desc = describeActivePolicy({ allowRead: false, allowWrite: false })
+    expect(desc).toContain('读取类工具')
+    expect(desc).toContain('写入类工具')
+  })
+})
diff --git a/packages/core/src/core/agent/tool-policy.ts b/packages/core/src/core/agent/tool-policy.ts
new file mode 100644
index 0000000..36a9f05
--- /dev/null
+++ b/packages/core/src/core/agent/tool-policy.ts
@@ -0,0 +1,143 @@
+/**
+ * 用户即时工具约束（Agent 控制能力 Step 5）。
+ *
+ * 从用户本轮 instruction 解析出工具策略，在执行层强制禁用被约束的工具。
+ * 不依赖 system prompt 的软提示——模型即使无视约束，执行层也会拦住。
+ */
+
+export type ToolPolicy = {
+  /** 是否允许读取类工具（ReadFile/ListDirectory/FindFiles/RagSearch） */
+  allowRead: boolean
+  /** 是否允许写入类工具（EditFile/CreateFile/RenameFile/DeleteFile） */
+  allowWrite: boolean
+}
+
+/** 默认策略：全部允许。无约束关键词时不影响任何现有行为。 */
+export const DEFAULT_TOOL_POLICY: ToolPolicy = {
+  allowRead: true,
+  allowWrite: true,
+}
+
+// 否定前缀：出现在动作词之前表示禁用
+const NEGATIONS = ['不要', '不用', '无需', '别', '禁止', '不能', '不可以', '请勿']
+
+// 读取类动作词（命中则可能禁读）
+const READ_ACTIONS = ['读', '看', '查', '找', '翻', '浏览', '扫描', '检索', '读取', '查看', '查找', '读取文件', '阅读']
+
+// 写入类动作词（命中则可能禁写）
+const WRITE_ACTIONS = ['写', '改', '建', '删', '动', '修', '创建', '新建', '修改', '删除', '重命名', '写入', '改动', '保存']
+
+/**
+ * 从用户 instruction 解析工具策略。
+ *
+ * 识别"否定词 + 读/写动作词"的组合：
+ * - "不要读任何文件" → allowRead: false
+ * - "别改文件" → allowWrite: false
+ * - "直接回答，不要查文件" → allowRead: false
+ *
+ * 漏判只是没禁（执行层是兜底，不出错）；误判风险通过要求"否定+动作"成对出现来降低。
+ */
+export function parseToolPolicy(instruction: string): ToolPolicy {
+  const text = instruction.trim()
+  if (!text) {
+    return DEFAULT_TOOL_POLICY
+  }
+
+  // 找出所有否定词位置，检查其后（窗口内）是否出现动作词
+  const hasReadDenial = hasNegationBeforeAction(text, READ_ACTIONS)
+  const hasWriteDenial = hasNegationBeforeAction(text, WRITE_ACTIONS)
+
+  // "不要碰文件/别动文件"这类用通用动词的全禁表达（同时禁读禁写）
+  const hasGenericDenial = /(?:不要|别|禁止|请勿)\s*(?:碰|动)\s*(?:任何|所有)?\s*文件/.test(text)
+
+  return {
+    allowRead: !(hasReadDenial || hasGenericDenial),
+    allowWrite: !(hasWriteDenial || hasGenericDenial),
+  }
+}
+
+/**
+ * 检查文本中是否存在"否定词 + 动作词（在窗口内）"的组合。
+ * 窗口设为 6 个字符，覆盖"不要读取文件""别去查"等间隔表达。
+ */
+function hasNegationBeforeAction(text: string, actions: string[]): boolean {
+  for (const negation of NEGATIONS) {
+    let fromIndex = 0
+    while (true) {
+      const negIndex = text.indexOf(negation, fromIndex)
+      if (negIndex === -1) {
+        break
+      }
+      // 取否定词后 6 个字符的窗口
+      const window = text.slice(negIndex + negation.length, negIndex + negation.length + 6)
+      if (actions.some((action) => window.includes(action))) {
+        return true
+      }
+      fromIndex = negIndex + 1
+    }
+  }
+  return false
+}
+
+/**
+ * 判定某工具是否被策略禁用。
+ * 用 isReadOnly 二分，不硬编码工具名——未来加新工具自动归类。
+ */
+export function isToolDisabledByPolicy(
+  tool: { isReadOnly: boolean },
+  policy: ToolPolicy,
+): boolean {
+  if (tool.isReadOnly) {
+    return !policy.allowRead
+  }
+  return !policy.allowWrite
+}
+
+/**
+ * 生成面向模型的拒绝说明，回灌 tool result 让模型理解为何失败。
+ */
+export function describePolicyDenial(
+  tool: { isReadOnly: boolean },
+  policy: ToolPolicy,
+): string {
+  if (tool.isReadOnly && !policy.allowRead) {
+    return '用户本轮要求不要读取或查找文件'
+  }
+  if (!tool.isReadOnly && !policy.allowWrite) {
+    return '用户本轮要求不要修改、创建或删除文件'
+  }
+  return '该工具本轮被用户约束禁用'
+}
+
+/**
+ * 工具可见性过滤：被禁工具不发给模型，从源头减少无效的工具调用往返。
+ * 返回仍可用的工具列表（保留 isReadOnly/schema 等字段）。
+ */
+export function filterAvailableTools<T extends { isReadOnly: boolean }>(
+  tools: T[],
+  policy: ToolPolicy | undefined,
+): T[] {
+  if (!policy) {
+    return tools
+  }
+  return tools.filter((tool) => !isToolDisabledByPolicy(tool, policy))
+}
+
+/**
+ * 生成面向模型的约束声明，注入 system prompt / user context，
+ * 让模型在 prompt 层也感知本轮约束（软约束，减少尝试调用被禁工具）。
+ * 无约束时返回空字符串。
+ */
+export function describeActivePolicy(policy: ToolPolicy): string {
+  const denied: string[] = []
+  if (!policy.allowRead) {
+    denied.push('读取类工具（ReadFile / ListDirectory / FindFiles / RagSearch）')
+  }
+  if (!policy.allowWrite) {
+    denied.push('写入类工具（EditFile / CreateFile / RenameFile / DeleteFile）')
+  }
+  if (denied.length === 0) {
+    return ''
+  }
+  return `【本轮工具约束】用户本轮已禁用：${denied.join('、')}。请用纯对话回答，或向用户确认是否解除限制；不要尝试绕过该约束。`
+}
diff --git a/packages/core/src/core/chat/session.ts b/packages/core/src/core/chat/session.ts
index b778930..ba64900 100644
--- a/packages/core/src/core/chat/session.ts
+++ b/packages/core/src/core/chat/session.ts
@@ -84,6 +84,7 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
     scenePrompt: input.scenePrompt,
     project: input.project,
     target,
+    toolPolicy: input.toolPolicy,
   })
   const tools = createAgentTools()
   const enableDebugLogging = Boolean(input.config.settings.enableDebugLogging)
@@ -111,6 +112,7 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
       tools,
       signal: input.signal,
       confirm: input.confirm,
+      toolPolicy: input.toolPolicy,
       onEvent(event) {
         logAgentQueryEvent({
           project: input.project,
@@ -444,6 +446,7 @@ function buildAgentMessages(input: {
   scenePrompt?: string
   project: ChatTurnInput['project']
   target: ChatTargetContext | null
+  toolPolicy?: ChatTurnInput['toolPolicy']
 }): AgentMessage[] {
   const nextUserMessage: AgentMessage = {
     role: 'user',
@@ -452,6 +455,7 @@ function buildAgentMessages(input: {
       quote: input.quote,
       project: input.project,
       target: input.target,
+      policy: input.toolPolicy,
     }),
   }
 
diff --git a/packages/core/src/services/agent-service.ts b/packages/core/src/services/agent-service.ts
index 16736cf..ebc0a82 100644
--- a/packages/core/src/services/agent-service.ts
+++ b/packages/core/src/services/agent-service.ts
@@ -5,6 +5,7 @@ import {
 import { deriveChatTargetFromPath } from '../core/chat/target'
 import { readScenePrompt, readSystemPrompt } from '../core/fs/project-fs'
 import type { ConfirmHandler } from '../core/agent/tool-execution'
+import { parseToolPolicy } from '../core/agent/tool-policy'
 import type { FileChange, WriteConfirmation } from '../core/tools/types'
 import type { ChatMessage, ChatSessionState, ChatTargetContext } from '../types/chat'
 
@@ -79,6 +80,8 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
     const confirm: ConfirmHandler | undefined = input.onEvent
       ? (request) => requestConfirmation(input.projectId, request, input.onEvent!)
       : undefined
+    // 用户即时工具约束：从 instruction 解析（如「不要读文件」「别改」），执行层强制禁用。
+    const toolPolicy = parseToolPolicy(input.instruction)
     const turn = await runChatTurn({
       session: previousSession,
       input: {
@@ -91,6 +94,7 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
         activeFilePath: input.activeFilePath,
         signal: input.signal,
         confirm,
+        toolPolicy,
       },
       onEvent(event) {
         emitMessageEvent(event.message, input.onEvent)
diff --git a/packages/core/src/types/chat.ts b/packages/core/src/types/chat.ts
index 7d2e018..ce4841a 100644
--- a/packages/core/src/types/chat.ts
+++ b/packages/core/src/types/chat.ts
@@ -2,6 +2,7 @@ import type { ProjectConfig, ProjectSnapshot } from './project'
 import type { RetrievalResult } from './rag'
 import type { AgentMessage } from '../core/agent/messages'
 import type { ConfirmHandler } from '../core/agent/tool-execution'
+import type { ToolPolicy } from '../core/agent/tool-policy'
 
 export type ChatToolName =
   | 'ReadFile'
@@ -120,6 +121,8 @@ export type ChatTurnInput = {
   signal?: AbortSignal
   /** 写工具确认回调，透传到 Agent Loop。 */
   confirm?: ConfirmHandler
+  /** 用户即时工具约束，透传到 Agent Loop。 */
+  toolPolicy?: ToolPolicy
 }
 
 export type ChatTurnResult = {

From 71c2d42025f8e77586e57c677f58ed6e7ecc559e Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 02:17:30 +0800
Subject: [PATCH 21/36] =?UTF-8?q?fix(project):=20=E5=90=8C=E4=BC=9A?=
 =?UTF-8?q?=E8=AF=9D=E5=86=85=E4=BF=AE=E6=94=B9=20system=20prompt=20?=
 =?UTF-8?q?=E6=88=96=E5=9C=BA=E6=99=AF=E5=90=8E=E8=87=AA=E5=8A=A8=E5=88=B7?=
 =?UTF-8?q?=E6=96=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent Step 6：修复 buildAgentMessages 复用分支忽略本轮 systemPrompt/
scenePrompt 的 bug——同会话内改 prompts/system.md 或切换场景后，
Agent 仍用首轮旧 system message。

机制：runChatTurn 每轮对 buildAgentSystemPrompt(systemPrompt+scenePrompt)
的输出算 FNV-1a hash，与 session.systemPromptHash 比对；不同则 in-place
替换 agentMessages[0]（system message）的 content 并更新 hash。
system message 恒在 index 0，in-place 替换不破坏消息序列合法性。
首轮建立 hash 基线，后续轮据此检测变化。

附带：提取共享 hash 工具 util/hash.ts，统一 ReadFileState / RAG
indexer / system prompt 三处原本各自重复的 FNV-1a 实现。

测试：hash 4 个用例（稳定/差异/格式兼容/空串）+ refreshSystemMessageContent
5 个用例（替换 index0/不可变/非 system 原样返回/空数组/保留 tool 消息）。
---
 packages/core/src/core/chat/session.test.ts   | 71 +++++++++++++++++++
 packages/core/src/core/chat/session.ts        | 28 ++++++++
 packages/core/src/core/rag/indexer.ts         | 12 +---
 .../core/tools/file-tools/read-file-state.ts  | 12 +---
 packages/core/src/core/util/hash.test.ts      | 23 ++++++
 packages/core/src/core/util/hash.ts           | 18 +++++
 packages/core/src/types/chat.ts               |  2 +
 7 files changed, 144 insertions(+), 22 deletions(-)
 create mode 100644 packages/core/src/core/chat/session.test.ts
 create mode 100644 packages/core/src/core/util/hash.test.ts
 create mode 100644 packages/core/src/core/util/hash.ts

diff --git a/packages/core/src/core/chat/session.test.ts b/packages/core/src/core/chat/session.test.ts
new file mode 100644
index 0000000..378c050
--- /dev/null
+++ b/packages/core/src/core/chat/session.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest'
+
+import { refreshSystemMessageContent } from './session'
+import type { AgentMessage } from '../agent/messages'
+
+describe('refreshSystemMessageContent', () => {
+  it('replaces the system message content at index 0', () => {
+    const messages: AgentMessage[] = [
+      { role: 'system', content: '旧 system prompt' },
+      { role: 'user', content: '用户第一条' },
+      { role: 'assistant', content: '助手回复' },
+    ]
+
+    const result = refreshSystemMessageContent(messages, '新 system prompt')
+
+    expect(result[0]).toEqual({ role: 'system', content: '新 system prompt' })
+    // 后续消息原样保留
+    expect(result[1]).toEqual({ role: 'user', content: '用户第一条' })
+    expect(result[2]).toEqual({ role: 'assistant', content: '助手回复' })
+    expect(result).toHaveLength(3)
+  })
+
+  it('does not mutate the original array (returns new array)', () => {
+    const original: AgentMessage[] = [
+      { role: 'system', content: '旧' },
+      { role: 'user', content: '用户' },
+    ]
+
+    const result = refreshSystemMessageContent(original, '新')
+
+    expect(original[0].content).toBe('旧') // 原数组不变
+    expect(result).not.toBe(original) // 返回新数组
+    expect(result[0].content).toBe('新')
+  })
+
+  it('returns messages as-is when index 0 is not a system message', () => {
+    const messages: AgentMessage[] = [
+      { role: 'user', content: '首条不是 system' },
+    ]
+
+    const result = refreshSystemMessageContent(messages, '新 system prompt')
+
+    expect(result).toBe(messages)
+  })
+
+  it('returns empty array as-is', () => {
+    expect(refreshSystemMessageContent([], '新')).toEqual([])
+  })
+
+  it('preserves tool-call assistant messages after the system message', () => {
+    // 模拟真实 Agent Loop 产生的消息序列：system, user, assistant(toolCalls), tool(result)
+    const messages: AgentMessage[] = [
+      { role: 'system', content: '旧' },
+      { role: 'user', content: '读一下文件' },
+      {
+        role: 'assistant',
+        content: '',
+        toolCalls: [{ id: 'call_1', name: 'ReadFile', input: { path: 'a.txt' } }],
+      },
+      { role: 'tool', toolCallId: 'call_1', name: 'ReadFile', content: '文件内容' },
+    ]
+
+    const result = refreshSystemMessageContent(messages, '新 system')
+
+    expect(result[0].content).toBe('新 system')
+    // tool call / tool result 结构完整保留
+    expect(result[2].role).toBe('assistant')
+    expect(result[3].role).toBe('tool')
+    expect((result[2] as { toolCalls?: unknown }).toolCalls).toHaveLength(1)
+  })
+})
diff --git a/packages/core/src/core/chat/session.ts b/packages/core/src/core/chat/session.ts
index ba64900..d80f674 100644
--- a/packages/core/src/core/chat/session.ts
+++ b/packages/core/src/core/chat/session.ts
@@ -2,6 +2,7 @@ import { buildAgentSystemPrompt, buildAgentUserContext } from '../agent/prompt'
 import { query } from '../agent/query'
 import { createAgentTools } from '../agent/tools'
 import { createLogId, writeAgentLog } from '../logging/agent-log'
+import { hashContent } from '../util/hash'
 import type { AgentQueryEvent } from '../agent/query'
 
 import { deriveChatTargetFromPath } from './target'
@@ -76,6 +77,18 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
     onEvent,
   )
 
+  // 同会话内 system.md 或场景提示词变化时，刷新 agentMessages 里的 system message。
+  // buildAgentMessages 的复用分支会原样保留首轮 system message，这里先 in-place 替换为最新内容。
+  const newSystemContent = buildAgentSystemPrompt({
+    systemPrompt: input.systemPrompt,
+    scenePrompt: input.scenePrompt,
+  })
+  const newSystemHash = hashContent(newSystemContent)
+  if (session.agentMessages && session.systemPromptHash !== newSystemHash) {
+    session.agentMessages = refreshSystemMessageContent(session.agentMessages, newSystemContent)
+  }
+  session.systemPromptHash = newSystemHash
+
   const agentMessages = buildAgentMessages({
     previousMessages: session.agentMessages,
     instruction: input.instruction,
@@ -438,6 +451,21 @@ function previewLogText(text: string) {
   return normalized.length > 600 ? `${normalized.slice(0, 600)}...` : normalized
 }
 
+/**
+ * 同会话内 system prompt 变化时，in-place 替换 agentMessages 里 system message 的 content。
+ * system message 恒在 index 0（query 循环只 push assistant/tool，从不新增 system），
+ * 替换不破坏消息序列合法性。若无 system message（异常情况）则原样返回。
+ */
+export function refreshSystemMessageContent(
+  messages: AgentMessage[],
+  newContent: string,
+): AgentMessage[] {
+  if (messages.length === 0 || messages[0].role !== 'system') {
+    return messages
+  }
+  return [{ ...messages[0], content: newContent }, ...messages.slice(1)]
+}
+
 function buildAgentMessages(input: {
   previousMessages?: AgentMessage[]
   instruction: string
diff --git a/packages/core/src/core/rag/indexer.ts b/packages/core/src/core/rag/indexer.ts
index 46cd643..ef8156a 100644
--- a/packages/core/src/core/rag/indexer.ts
+++ b/packages/core/src/core/rag/indexer.ts
@@ -1,6 +1,7 @@
 import { createEmbedding } from '../embedding/client'
 import { parseElementFile } from '../elements/parser'
 import { readProjectFile } from '../fs/project-fs'
+import { hashContent } from '../util/hash'
 
 import type { ProjectSnapshot, TreeNode } from '../../types/project'
 import type { IndexBuildRequest, IndexBuildResult, ProjectIndexMeta } from '../../types/rag'
@@ -234,14 +235,3 @@ function summarizeBody(body: string) {
 function createStableElementId(path: string) {
   return `element-${hashContent(path)}`
 }
-
-function hashContent(content: string) {
-  let hash = 2166136261
-
-  for (let index = 0; index < content.length; index += 1) {
-    hash ^= content.charCodeAt(index)
-    hash = Math.imul(hash, 16777619)
-  }
-
-  return `h${(hash >>> 0).toString(16)}`
-}
diff --git a/packages/core/src/core/tools/file-tools/read-file-state.ts b/packages/core/src/core/tools/file-tools/read-file-state.ts
index 9731ca5..ca21045 100644
--- a/packages/core/src/core/tools/file-tools/read-file-state.ts
+++ b/packages/core/src/core/tools/file-tools/read-file-state.ts
@@ -1,3 +1,4 @@
+import { hashContent } from '../../util/hash'
 import { normalizeProjectPath } from '../path'
 import type { ReadFileState } from '../types'
 import { asRecord, readString } from './common'
@@ -43,14 +44,3 @@ export function assertFreshReadFileState(
     throw new Error(`文件 ${path} 已在 ReadFile 之后发生变化；请重新 ReadFile 获取最新内容后再 EditFile，避免覆盖他人或其他工具的修改`)
   }
 }
-
-function hashContent(content: string) {
-  let hash = 2166136261
-
-  for (let index = 0; index < content.length; index += 1) {
-    hash ^= content.charCodeAt(index)
-    hash = Math.imul(hash, 16777619)
-  }
-
-  return `h${(hash >>> 0).toString(16)}`
-}
diff --git a/packages/core/src/core/util/hash.test.ts b/packages/core/src/core/util/hash.test.ts
new file mode 100644
index 0000000..4661a3b
--- /dev/null
+++ b/packages/core/src/core/util/hash.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+
+import { hashContent } from './hash'
+
+describe('hashContent', () => {
+  it('returns a stable hash for the same content', () => {
+    expect(hashContent('你好，世界')).toBe(hashContent('你好，世界'))
+  })
+
+  it('returns different hashes for different content', () => {
+    expect(hashContent('版本一')).not.toBe(hashContent('版本二'))
+  })
+
+  it('produces the historical FNV-1a format (h-prefixed hex)', () => {
+    // 与原 read-file-state.ts / indexer.ts 的实现逐字节一致
+    // "abc" 的 FNV-1a 32-bit: 0xe71c2f5 -> h 后跟 hex
+    expect(hashContent('abc')).toMatch(/^h[0-9a-f]+$/)
+  })
+
+  it('handles empty string', () => {
+    expect(hashContent('')).toBe('h' + (2166136261 >>> 0).toString(16))
+  })
+})
diff --git a/packages/core/src/core/util/hash.ts b/packages/core/src/core/util/hash.ts
new file mode 100644
index 0000000..8302c80
--- /dev/null
+++ b/packages/core/src/core/util/hash.ts
@@ -0,0 +1,18 @@
+/**
+ * 共享字符串 hash（FNV-1a 32 位）。
+ *
+ * 被 ReadFileState（文件过期检测）、RAG indexer（embedding 文本版本）、
+ * Agent system prompt 刷新检测复用，保证三处算法一致。
+ *
+ * 按 UTF-16 code unit 计算（charCodeAt），与历史实现保持兼容。
+ */
+export function hashContent(content: string): string {
+  let hash = 2166136261 // FNV offset basis
+
+  for (let index = 0; index < content.length; index += 1) {
+    hash ^= content.charCodeAt(index)
+    hash = Math.imul(hash, 16777619) // FNV prime
+  }
+
+  return `h${(hash >>> 0).toString(16)}`
+}
diff --git a/packages/core/src/types/chat.ts b/packages/core/src/types/chat.ts
index ce4841a..3094ba9 100644
--- a/packages/core/src/types/chat.ts
+++ b/packages/core/src/types/chat.ts
@@ -106,6 +106,8 @@ export type ChatSessionState = {
   currentTarget: ChatTargetContext | null
   lastRagResult: RetrievalResult | null
   lastWrittenPath?: string
+  /** 当前会话已注入的 system message（systemPrompt + scenePrompt 拼接结果）hash，用于检测同会话内提示词变化并刷新。 */
+  systemPromptHash?: string
 }
 
 export type ChatTurnInput = {

From 2dcaf25662c31594ea5d6a8b5c039aa59a80cb03 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 00:44:50 +0800
Subject: [PATCH 22/36] =?UTF-8?q?feat(project):=20=E5=AE=9E=E7=8E=B0?=
 =?UTF-8?q?=E5=AF=B9=E8=AF=9D=E5=8E=86=E5=8F=B2=E4=BC=9A=E8=AF=9D=E7=9A=84?=
 =?UTF-8?q?=E4=BF=9D=E5=AD=98=E5=88=87=E6=8D=A2=E6=96=B0=E5=BB=BA=E5=88=A0?=
 =?UTF-8?q?=E9=99=A4=E9=87=8D=E5=91=BD=E5=90=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

core: 会话状态新增 title/createdAt/updatedAt 元字段；
新增 session-store，落盘到 .novel/sessions/<id>.json。

core: agent-service 的 sessionMap 升级为多会话结构，
新增 listSessions/renameSession/deleteSession，
runTurn 每轮结束落盘，首轮发送后用首句截断自动生成标题。

app: chat store 增加 sessions 列表与
initSessions/select/create/rename/delete 五个 action。

ui: 重写 ConversationList 占位为会话列表，
支持新建/切换/重命名/删除；CategoryPanel 与 ProjectView
接通 props 与事件链路。
---
 .../components/category/ConversationList.vue  | 148 +++++++++++-
 .../src/components/layout/CategoryPanel.vue   |  20 +-
 packages/app/src/stores/chat.ts               | 116 ++++++++-
 packages/app/src/views/ProjectView.vue        |  10 +-
 .../core/src/core/chat/session-store.test.ts  | 221 ++++++++++++++++++
 packages/core/src/core/chat/session-store.ts  | 173 ++++++++++++++
 packages/core/src/core/chat/session.ts        |  25 ++
 packages/core/src/services/agent-service.ts   | 171 ++++++++++++--
 packages/core/src/services/types.ts           |  17 ++
 packages/core/src/types/chat.ts               |  22 ++
 10 files changed, 887 insertions(+), 36 deletions(-)
 create mode 100644 packages/core/src/core/chat/session-store.test.ts
 create mode 100644 packages/core/src/core/chat/session-store.ts

diff --git a/packages/app/src/components/category/ConversationList.vue b/packages/app/src/components/category/ConversationList.vue
index 3cddae0..0b9de2a 100644
--- a/packages/app/src/components/category/ConversationList.vue
+++ b/packages/app/src/components/category/ConversationList.vue
@@ -1,23 +1,157 @@
 <script setup lang="ts">
-// 对话历史分类面板。
-// 本轮为占位实现：对话历史持久化存储功能尚未开发。
-// 后续支持会话列表切换时，这里会渲染历史会话卡片。
+import { ref } from 'vue'
+import type { ChatSessionSummaryView } from '@novai/core/services/types'
+
+defineProps<{
+  sessions: ChatSessionSummaryView[]
+  activeSessionId: string | null
+}>()
+
+const emit = defineEmits<{
+  select: [sessionId: string]
+  create: []
+  rename: [sessionId: string, title: string]
+  remove: [sessionId: string]
+}>()
+
+/** 当前正在内联重命名的 sessionId；null 表示无 */
+const renamingId = ref<string | null>(null)
+const renameDraft = ref('')
+
+function startRename(session: ChatSessionSummaryView) {
+  renamingId.value = session.sessionId
+  renameDraft.value = session.title
+}
+
+function commitRename(sessionId: string) {
+  const title = renameDraft.value.trim()
+  renamingId.value = null
+  if (title) {
+    emit('rename', sessionId, title)
+  }
+}
+
+function cancelRename() {
+  renamingId.value = null
+}
+
+function confirmRemove(session: ChatSessionSummaryView) {
+  // 删除不可撤销，弹原生 confirm 二次确认
+  if (window.confirm(`确定删除对话「${session.title}」吗？此操作不可撤销。`)) {
+    emit('remove', session.sessionId)
+  }
+}
+
+/** 相对时间：今天显示 HH:mm，今年显示 MM-DD，更早显示完整日期 */
+function formatRelativeTime(iso: string): string {
+  const date = new Date(iso)
+  const now = new Date()
+  const sameDay = date.toDateString() === now.toDateString()
+  if (sameDay) {
+    return date.toLocaleTimeString('zh-CN', { hour: '2-digit', minute: '2-digit' })
+  }
+  const sameYear = date.getFullYear() === now.getFullYear()
+  if (sameYear) {
+    return `${date.getMonth() + 1}月${date.getDate()}日`
+  }
+  return date.toLocaleDateString('zh-CN')
+}
 </script>
 
 <template>
   <div class="flex h-full flex-col">
-    <div class="px-4 py-3">
+    <div class="flex items-center justify-between px-4 py-3">
       <h2 class="text-sm font-semibold text-white">对话</h2>
+      <button
+        class="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-gray-300 transition-colors hover:bg-white/10 hover:text-white"
+        title="开始新对话"
+        @click="emit('create')"
+      >
+        <svg class="h-3.5 w-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4" />
+        </svg>
+        <span>新对话</span>
+      </button>
     </div>
 
     <div class="flex-1 overflow-y-auto px-2 pb-2">
-      <div class="px-2 py-8 text-center">
+      <!-- 空状态 -->
+      <div v-if="sessions.length === 0" class="px-2 py-8 text-center">
         <svg class="mx-auto mb-3 h-10 w-10 text-gray-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
           <path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M8 10h.01M12 10h.01M16 10h.01M9 16H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-5l-5 5v-5z" />
         </svg>
-        <p class="mb-1 text-sm text-gray-400">对话历史功能开发中</p>
-        <p class="text-xs text-gray-500">后续将支持历史会话列表切换</p>
+        <p class="mb-1 text-sm text-gray-400">还没有对话</p>
+        <p class="text-xs text-gray-500">点击「新对话」开始创作</p>
       </div>
+
+      <!-- 会话列表 -->
+      <ul v-else class="space-y-0.5">
+        <li v-for="session in sessions" :key="session.sessionId" class="group relative">
+          <!-- 重命名态：内联输入框 -->
+          <div
+            v-if="renamingId === session.sessionId"
+            class="flex items-center rounded-md bg-white/10 px-2 py-1.5"
+          >
+            <input
+              v-model="renameDraft"
+              class="min-w-0 flex-1 rounded bg-transparent text-sm text-white outline-none placeholder:text-gray-500"
+              placeholder="会话标题"
+              @keydown.enter="commitRename(session.sessionId)"
+              @keydown.esc="cancelRename"
+              @blur="commitRename(session.sessionId)"
+            >
+          </div>
+
+          <!-- 展示态：会话卡片 -->
+          <button
+            v-else
+            :class="[
+              'flex w-full items-start gap-2 rounded-md px-2 py-2 text-left transition-colors',
+              session.sessionId === activeSessionId
+                ? 'bg-white/15 text-white'
+                : 'text-gray-300 hover:bg-white/10 hover:text-white',
+            ]"
+            @click="emit('select', session.sessionId)"
+          >
+            <svg class="mt-0.5 h-4 w-4 shrink-0 text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 12h.01M12 12h.01M16 12h.01M21 15a2 2 0 01-2 2H7l-4 4V5a2 2 0 012-2h14a2 2 0 012 2v10z" />
+            </svg>
+            <div class="min-w-0 flex-1">
+              <p class="truncate text-sm">{{ session.title }}</p>
+              <p class="mt-0.5 flex items-center gap-2 text-xs text-gray-500">
+                <span>{{ formatRelativeTime(session.updatedAt) }}</span>
+                <span>·</span>
+                <span>{{ session.messageCount }} 条</span>
+              </p>
+            </div>
+          </button>
+
+          <!-- hover 操作按钮（重命名/删除） -->
+          <div
+            v-if="renamingId !== session.sessionId"
+            class="absolute right-1 top-1.5 flex items-center gap-0.5 opacity-0 transition-opacity group-hover:opacity-100"
+          >
+            <button
+              class="rounded p-1 text-gray-400 hover:bg-white/15 hover:text-white"
+              title="重命名"
+              @click.stop="startRename(session)"
+            >
+              <svg class="h-3.5 w-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z" />
+              </svg>
+            </button>
+            <button
+              class="rounded p-1 text-gray-400 hover:bg-red-500/20 hover:text-red-300"
+              title="删除"
+              @click.stop="confirmRemove(session)"
+            >
+              <svg class="h-3.5 w-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16" />
+              </svg>
+            </button>
+          </div>
+        </li>
+      </ul>
     </div>
   </div>
 </template>
diff --git a/packages/app/src/components/layout/CategoryPanel.vue b/packages/app/src/components/layout/CategoryPanel.vue
index f42caf5..443a433 100644
--- a/packages/app/src/components/layout/CategoryPanel.vue
+++ b/packages/app/src/components/layout/CategoryPanel.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { ProjectFileNodeView } from '@novai/core/services/types'
+import type { ChatSessionSummaryView, ProjectFileNodeView } from '@novai/core/services/types'
 import type { Category } from '../../constants/category'
 import ChapterList from '../category/ChapterList.vue'
 import ElementList from '../category/ElementList.vue'
@@ -11,6 +11,10 @@ defineProps<{
   files: ProjectFileNodeView[]
   activeFilePath?: string
   activeScenePromptPath: string | null
+  /** 历史会话列表（对话分类面板用） */
+  sessions: ChatSessionSummaryView[]
+  /** 当前激活会话 id（对话分类面板高亮用） */
+  activeSessionId: string | null
   /** 移动端抽屉是否展开（沿用现有响应式方案） */
   isMobileOpen: boolean
   /** 面板是否展开（桌面端折叠/展开） */
@@ -21,6 +25,10 @@ const emit = defineEmits<{
   selectFile: [path: string]
   changeScene: [path: string | null]
   closeMobile: []
+  selectSession: [sessionId: string]
+  createSession: []
+  renameSession: [sessionId: string, title: string]
+  deleteSession: [sessionId: string]
 }>()
 </script>
 
@@ -44,7 +52,15 @@ const emit = defineEmits<{
     </button>
 
     <!-- 按分类切换内容 -->
-    <ConversationList v-if="activeCategory === 'conversation'" />
+    <ConversationList
+      v-if="activeCategory === 'conversation'"
+      :sessions="sessions"
+      :active-session-id="activeSessionId"
+      @select="emit('selectSession', $event)"
+      @create="emit('createSession')"
+      @rename="(sessionId, title) => emit('renameSession', sessionId, title)"
+      @remove="emit('deleteSession', $event)"
+    />
     <ChapterList
       v-else-if="activeCategory === 'chapter'"
       :files="files"
diff --git a/packages/app/src/stores/chat.ts b/packages/app/src/stores/chat.ts
index 7600ab0..479274d 100644
--- a/packages/app/src/stores/chat.ts
+++ b/packages/app/src/stores/chat.ts
@@ -5,12 +5,17 @@ import {
   createSession as createAgentSession,
   respondConfirmation as respondAgentConfirmation,
   runTurn as runAgentTurn,
+  getSession as getAgentSession,
+  listSessions as listAgentSessions,
+  renameSession as renameAgentSession,
+  deleteSession as deleteAgentSession,
 } from '@novai/core/services/agent-service'
 
 import type {
   AgentUiEvent,
   ChangedFileView,
   ChatMessageView,
+  ChatSessionSummaryView,
   ChatSessionView,
   FileChangeConfirmationView,
   RunAgentTurnInput,
@@ -28,18 +33,97 @@ export const useChatStore = defineStore('chat', () => {
   // 当前等待用户确认的写操作；Agent Loop 在此暂停
   const pendingConfirmation = ref<FileChangeConfirmationView | null>(null)
 
+  // 历史会话列表（对话分类面板渲染），按 updatedAt 降序
+  const sessions = ref<ChatSessionSummaryView[]>([])
+  // 当前激活会话 id（高亮 + runTurn 路由用）
+  const activeSessionId = ref<string | null>(null)
+  const isLoadingSessions = ref(false)
+
   // 当前运行持有的停止控制器；仅 isRunning 期间存在
   let activeAbortController: AbortController | null = null
 
   const hasSessionView = computed(() => sessionView.value !== null)
   const messages = computed<ChatMessageView[]>(() => sessionView.value?.messages ?? [])
 
-  async function ensureSessionView(projectId: string) {
-    if (!sessionView.value || sessionView.value.projectId !== projectId) {
-      sessionView.value = await createAgentSession(projectId)
+  /**
+   * 项目打开时的会话初始化入口：
+   * 拉取历史会话列表，有历史则激活最近一条，无历史则新建。
+   * 取代旧的 ensureSessionView（后者只支持单会话）。
+   */
+  async function initSessions(projectId: string): Promise<ChatSessionView> {
+    await loadSessions(projectId)
+
+    if (sessions.value.length > 0) {
+      await selectSession(projectId, sessions.value[0].sessionId)
+      return sessionView.value!
+    }
+
+    return createNewSession(projectId)
+  }
+
+  /** 拉取并刷新历史会话列表，同步当前激活 id。 */
+  async function loadSessions(projectId: string) {
+    isLoadingSessions.value = true
+    try {
+      sessions.value = await listAgentSessions(projectId)
+      // 列表里已不存在当前激活会话时清空（例如被删除）
+      if (activeSessionId.value && !sessions.value.some((s) => s.sessionId === activeSessionId.value)) {
+        activeSessionId.value = null
+      }
+    } finally {
+      isLoadingSessions.value = false
+    }
+  }
+
+  /** 切换到指定历史会话：加载其完整消息体并设为激活。 */
+  async function selectSession(projectId: string, sessionId: string): Promise<ChatSessionView | null> {
+    const view = await getAgentSession(projectId, sessionId)
+    if (!view) {
+      return null
     }
 
-    return sessionView.value
+    sessionView.value = view
+    activeSessionId.value = sessionId
+    // 切换会话时清空上一轮的运行态残留，避免跨会话串扰
+    agentEvents.value = []
+    changedFiles.value = []
+    return view
+  }
+
+  /** 新建会话：创建 + 激活 + 刷新列表。 */
+  async function createNewSession(projectId: string): Promise<ChatSessionView> {
+    const view = await createAgentSession(projectId)
+    sessionView.value = view
+    activeSessionId.value = view.sessionId
+    await loadSessions(projectId)
+    return view
+  }
+
+  /** 重命名会话标题，并同步列表对应项。 */
+  async function renameSession(projectId: string, sessionId: string, title: string): Promise<void> {
+    const view = await renameAgentSession(projectId, sessionId, title)
+    // 同步列表项标题
+    sessions.value = sessions.value.map((s) =>
+      s.sessionId === sessionId ? { ...s, title: view.title ?? s.title } : s,
+    )
+    // 若是当前会话，同步视图
+    if (sessionView.value?.sessionId === sessionId) {
+      sessionView.value = { ...sessionView.value, title: view.title }
+    }
+  }
+
+  /** 删除会话；若删的是当前激活会话，则切到列表第一条或新建。 */
+  async function deleteSession(projectId: string, sessionId: string): Promise<void> {
+    await deleteAgentSession(projectId, sessionId)
+    await loadSessions(projectId)
+
+    if (activeSessionId.value === sessionId) {
+      if (sessions.value.length > 0) {
+        await selectSession(projectId, sessions.value[0].sessionId)
+      } else {
+        await createNewSession(projectId)
+      }
+    }
   }
 
   async function runServiceTurn(
@@ -47,7 +131,10 @@ export const useChatStore = defineStore('chat', () => {
       onEvent?: (event: AgentUiEvent) => void
     },
   ): Promise<RunAgentTurnResult> {
-    const currentSession = await ensureSessionView(input.projectId)
+    if (!sessionView.value) {
+      throw new Error('没有活跃的会话')
+    }
+    const currentSession = sessionView.value
 
     agentEvents.value = []
     changedFiles.value = []
@@ -83,6 +170,8 @@ export const useChatStore = defineStore('chat', () => {
       isRunning.value = false
       isStopping.value = false
       activeAbortController = null
+      // 刷新历史列表（捕获首轮后的自动标题更新与 updatedAt 变化）
+      void loadSessions(currentSession.projectId)
     }
   }
 
@@ -142,10 +231,6 @@ export const useChatStore = defineStore('chat', () => {
     }
   }
 
-  async function createSession(projectId: string) {
-    return ensureSessionView(projectId)
-  }
-
   async function sendMessage(text: string, quote?: string) {
     if (!sessionView.value) {
       throw new Error('没有活跃的会话')
@@ -185,18 +270,25 @@ export const useChatStore = defineStore('chat', () => {
     changedFiles,
     isRunning,
     isStopping,
+    isLoadingSessions,
     messages,
     pendingConfirmation,
     sessionView,
+    sessions,
+    activeSessionId,
     runStatus,
     hasSessionView,
     abortRun,
     confirmWriteTool,
-    createSession,
-    ensureSessionView,
+    createNewSession,
+    deleteSession,
+    initSessions,
+    loadSessions,
     rejectWriteTool,
-    sendMessage,
+    renameSession,
     runServiceTurn,
+    selectSession,
+    sendMessage,
     setRunStatus,
   }
 })
diff --git a/packages/app/src/views/ProjectView.vue b/packages/app/src/views/ProjectView.vue
index a048b53..3b96a86 100644
--- a/packages/app/src/views/ProjectView.vue
+++ b/packages/app/src/views/ProjectView.vue
@@ -91,8 +91,8 @@ onMounted(async () => {
     }
   }
 
-  // 初始化聊天会话
-  await chatStore.createSession(projectId.value)
+  // 初始化聊天会话（拉取历史列表，有历史则激活最近一条，否则新建）
+  await chatStore.initSessions(projectId.value)
 
   // 检查是否需要显示首次引导
   if (projectStore.currentProject) {
@@ -250,11 +250,17 @@ async function handleElementsWritten() {
       :files="projectStore.currentProject?.files ?? []"
       :active-file-path="projectStore.activeFile?.path"
       :active-scene-prompt-path="activeScenePromptPath"
+      :sessions="chatStore.sessions"
+      :active-session-id="chatStore.activeSessionId"
       :is-open="isCategoryOpen"
       :is-mobile-open="isMobileCategoryOpen"
       @select-file="handleSelectFile"
       @change-scene="handleChangeScene"
       @close-mobile="isMobileCategoryOpen = false"
+      @select-session="(sessionId) => chatStore.selectSession(projectId, sessionId)"
+      @create-session="chatStore.createNewSession(projectId)"
+      @rename-session="(sessionId, title) => chatStore.renameSession(projectId, sessionId, title)"
+      @delete-session="(sessionId) => chatStore.deleteSession(projectId, sessionId)"
     />
 
     <!-- 中间对话面板 -->
diff --git a/packages/core/src/core/chat/session-store.test.ts b/packages/core/src/core/chat/session-store.test.ts
new file mode 100644
index 0000000..b08ba7b
--- /dev/null
+++ b/packages/core/src/core/chat/session-store.test.ts
@@ -0,0 +1,221 @@
+import { describe, expect, it } from 'vitest'
+
+import { createChatSession } from './session'
+import {
+  saveSession,
+  loadSession,
+  deleteSessionFile,
+  listSessionMetas,
+  buildSessionFilePath,
+  SESSIONS_DIR,
+} from './session-store'
+import type { ProjectSnapshot } from '../../types/project'
+
+describe('chat session-store', () => {
+  it('saveSession 落盘到 .novel/sessions/<sessionId>.json，刷新 updatedAt', async () => {
+    const root = createMemoryDirectory('novel')
+    const project = buildProject(root)
+    const session = createChatSession('proj-1')
+    const beforeSave = session.updatedAt
+
+    await new Promise((r) => setTimeout(r, 5))
+    await saveSession(project, session)
+
+    const loaded = await loadSession(project, session.sessionId)
+    expect(loaded).not.toBeNull()
+    expect(loaded!.sessionId).toBe(session.sessionId)
+    // updatedAt 被 saveSession 刷新（写盘时间晚于创建时间）
+    expect(loaded!.updatedAt >= beforeSave).toBe(true)
+  })
+
+  it('loadSession 在文件缺失时返回 null，不抛错', async () => {
+    const root = createMemoryDirectory('novel')
+    const project = buildProject(root)
+
+    const loaded = await loadSession(project, 'nonexistent-session')
+    expect(loaded).toBeNull()
+  })
+
+  it('deleteSessionFile 删除文件，且对不存在的 sessionId 静默成功', async () => {
+    const root = createMemoryDirectory('novel')
+    const project = buildProject(root)
+    const session = createChatSession('proj-1')
+    await saveSession(project, session)
+
+    await deleteSessionFile(project, session.sessionId)
+    expect(await loadSession(project, session.sessionId)).toBeNull()
+
+    // 再次删除不抛
+    await expect(deleteSessionFile(project, session.sessionId)).resolves.toBeUndefined()
+  })
+
+  it('listSessionMetas 列出所有会话并按 updatedAt 降序', async () => {
+    const root = createMemoryDirectory('novel')
+    const project = buildProject(root)
+
+    const old = createChatSession('proj-1')
+    old.title = '旧对话'
+    old.createdAt = '2026-01-01T00:00:00.000Z'
+    old.updatedAt = '2026-01-01T00:00:00.000Z'
+
+    const recent = createChatSession('proj-1')
+    recent.title = '新对话'
+    recent.createdAt = '2026-02-01T00:00:00.000Z'
+    // saveSession 会刷新 updatedAt 到当前时间，使 recent 排在前面
+
+    await writeSessionRaw(project, old)
+    await saveSession(project, recent)
+
+    const metas = await listSessionMetas(project)
+    expect(metas).toHaveLength(2)
+    expect(metas[0].sessionId).toBe(recent.sessionId)
+    expect(metas[0].title).toBe('新对话')
+    expect(metas[1].sessionId).toBe(old.sessionId)
+    expect(metas[1].title).toBe('旧对话')
+    expect(metas[1].messageCount).toBe(0)
+  })
+
+  it('listSessionMetas 在无会话时返回空数组', async () => {
+    const root = createMemoryDirectory('novel')
+    const project = buildProject(root)
+
+    const metas = await listSessionMetas(project)
+    expect(metas).toEqual([])
+  })
+
+  it('listSessionMetas 跳过解析失败的损坏文件', async () => {
+    const root = createMemoryDirectory('novel')
+    const project = buildProject(root)
+
+    const good = createChatSession('proj-1')
+    good.title = '正常会话'
+    await saveSession(project, good)
+
+    // 写一个损坏的会话文件
+    await writeRawText(project, buildSessionFilePath('corrupt-session'), '{ not valid json')
+
+    const metas = await listSessionMetas(project)
+    expect(metas).toHaveLength(1)
+    expect(metas[0].sessionId).toBe(good.sessionId)
+  })
+
+  it('buildSessionFilePath / SESSIONS_DIR 路径约定正确', () => {
+    expect(SESSIONS_DIR).toBe('.novel/sessions')
+    expect(buildSessionFilePath('session-abc')).toBe('.novel/sessions/session-abc.json')
+  })
+})
+
+// ---------- 测试夹具：内存版 FileSystemDirectoryHandle ----------
+
+function buildProject(root: MemoryDirectoryHandle): ProjectSnapshot {
+  return {
+    id: 'test-project',
+    name: 'Test Novel',
+    rootName: 'novel',
+    handle: root,
+    config: {
+      project: { name: 'Test Novel', createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-01T00:00:00.000Z' },
+    } as ProjectSnapshot['config'],
+    manifest: {
+      projectId: 'test-project',
+      version: 1,
+      createdAt: '2026-01-01T00:00:00.000Z',
+      lastOpenedAt: '2026-01-01T00:00:00.000Z',
+    },
+    tree: [],
+    metadata: {} as ProjectSnapshot['metadata'],
+  }
+}
+
+/** 直接写一个会话对象（不经 saveSession 的 updatedAt 刷新），用于构造固定时间戳的旧会话 */
+async function writeSessionRaw(project: ProjectSnapshot, session: ReturnType<typeof createChatSession>) {
+  await writeRawText(project, buildSessionFilePath(session.sessionId), JSON.stringify(session, null, 2))
+}
+
+async function writeRawText(project: ProjectSnapshot, path: string, content: string) {
+  const segments = path.split('/').filter(Boolean)
+  const fileName = segments.pop()!
+  let current = project.handle as unknown as MemoryDirectoryHandle
+  for (const segment of segments) {
+    let next = current.__entry.entries.get(segment)
+    if (!next) {
+      const dir: MemoryDirectoryEntry = { kind: 'directory', name: segment, entries: new Map() }
+      current.__entry.entries.set(segment, dir)
+      next = dir
+    }
+    current = createDirectoryHandle(next as MemoryDirectoryEntry)
+  }
+  current.__entry.entries.set(fileName, {
+    kind: 'file',
+    name: fileName,
+    content,
+    lastModified: Date.now(),
+  })
+}
+
+type MemoryFileEntry = { kind: 'file'; name: string; content: string; lastModified: number }
+type MemoryDirectoryEntry = { kind: 'directory'; name: string; entries: Map<string, MemoryEntry> }
+type MemoryEntry = MemoryFileEntry | MemoryDirectoryEntry
+type MemoryDirectoryHandle = FileSystemDirectoryHandle & { __entry: MemoryDirectoryEntry }
+
+function createMemoryDirectory(name: string): MemoryDirectoryHandle {
+  return createDirectoryHandle({ kind: 'directory', name, entries: new Map() })
+}
+
+function createDirectoryHandle(entry: MemoryDirectoryEntry): MemoryDirectoryHandle {
+  return {
+    kind: 'directory',
+    name: entry.name,
+    __entry: entry,
+    async getDirectoryHandle(name: string, options?: FileSystemGetDirectoryOptions) {
+      const current = entry.entries.get(name)
+      if (current?.kind === 'directory') return createDirectoryHandle(current)
+      if (current) throw new DOMException(`Not a directory: ${name}`, 'TypeMismatchError')
+      if (!options?.create) throw new DOMException(`Not found: ${name}`, 'NotFoundError')
+      const next: MemoryDirectoryEntry = { kind: 'directory', name, entries: new Map() }
+      entry.entries.set(name, next)
+      return createDirectoryHandle(next)
+    },
+    async getFileHandle(name: string, options?: FileSystemGetFileOptions) {
+      const current = entry.entries.get(name)
+      if (current?.kind === 'file') return createFileHandle(current)
+      if (current) throw new DOMException(`Not a file: ${name}`, 'TypeMismatchError')
+      if (!options?.create) throw new DOMException(`Not found: ${name}`, 'NotFoundError')
+      const next: MemoryFileEntry = { kind: 'file', name, content: '', lastModified: Date.now() }
+      entry.entries.set(name, next)
+      return createFileHandle(next)
+    },
+    async removeEntry(name: string) {
+      if (!entry.entries.delete(name)) throw new DOMException(`Not found: ${name}`, 'NotFoundError')
+    },
+    async *values() {
+      for (const child of entry.entries.values()) {
+        yield child.kind === 'directory' ? createDirectoryHandle(child) : createFileHandle(child)
+      }
+    },
+  } as unknown as MemoryDirectoryHandle
+}
+
+function createFileHandle(entry: MemoryFileEntry): FileSystemFileHandle {
+  return {
+    kind: 'file',
+    name: entry.name,
+    async getFile() {
+      return new File([entry.content], entry.name, { type: 'text/plain', lastModified: entry.lastModified })
+    },
+    async createWritable() {
+      let nextContent = ''
+      return {
+        async write(data: FileSystemWriteChunkType) {
+          nextContent = typeof data === 'string'
+            ? data
+            : data instanceof Blob ? await data.text() : String(data)
+        },
+        async close() {
+          entry.content = nextContent
+          entry.lastModified = Date.now()
+        },
+      } as FileSystemWritableFileStream
+    },
+  } as unknown as FileSystemFileHandle
+}
diff --git a/packages/core/src/core/chat/session-store.ts b/packages/core/src/core/chat/session-store.ts
new file mode 100644
index 0000000..82ab360
--- /dev/null
+++ b/packages/core/src/core/chat/session-store.ts
@@ -0,0 +1,173 @@
+import {
+  readProjectTextFile,
+  writeProjectTextFile,
+  removeProjectFile,
+  rescanProject,
+} from '../fs/project-fs'
+import type { ProjectSnapshot, TreeNode } from '../../types/project'
+import type { ChatSessionState } from '../../types/chat'
+
+/**
+ * 会话持久化存储目录，落在 `.novel/sessions/` 下，与 `.novel/logs/`、`.novel/trash/`
+ * 同级，遵循「NovAI 内部数据按功能分子目录」的现有约定。
+ * writeProjectTextFile 会自动创建中间目录，无需预建。
+ */
+export const SESSIONS_DIR = '.novel/sessions'
+
+/** 会话文件路径：`.novel/sessions/<sessionId>.json` */
+export function buildSessionFilePath(sessionId: string) {
+  return `${SESSIONS_DIR}/${sessionId}.json`
+}
+
+/**
+ * 保存会话到项目文件系统。写前刷新 updatedAt，保证列表按最近更新排序。
+ * 整对象 JSON 覆盖写——会话是状态快照，不需要追加（区别于 agent-log 的 jsonl）。
+ */
+export async function saveSession(
+  project: ProjectSnapshot,
+  session: ChatSessionState,
+): Promise<void> {
+  const stamped: ChatSessionState = {
+    ...session,
+    updatedAt: new Date().toISOString(),
+  }
+  const text = JSON.stringify(stamped, null, 2)
+  await writeProjectTextFile(project.handle, buildSessionFilePath(session.sessionId), text)
+}
+
+/** 读取单个会话。文件缺失或解析失败时返回 null（兜底，不抛）。 */
+export async function loadSession(
+  project: ProjectSnapshot,
+  sessionId: string,
+): Promise<ChatSessionState | null> {
+  try {
+    const text = await readProjectTextFile(project.handle, buildSessionFilePath(sessionId))
+    return parseSession(text)
+  } catch {
+    return null
+  }
+}
+
+/** 删除会话文件。文件不存在时静默成功（removeEntry 对缺失条目本就抛错，这里吞掉）。 */
+export async function deleteSessionFile(
+  project: ProjectSnapshot,
+  sessionId: string,
+): Promise<void> {
+  try {
+    await removeProjectFile(project.handle, buildSessionFilePath(sessionId))
+  } catch {
+    // 文件已不存在视为删除成功
+  }
+}
+
+/**
+ * 列出项目下所有历史会话的摘要，按 updatedAt 降序（最近更新的在前）。
+ *
+ * 实现走 rescanProject 拿全树后筛选 `.novel/sessions/*.json`，再逐个读全文解析元字段。
+ * 之所以不维护 index.json：会话量在小说项目里很小，单文件自包含更可靠（对齐 agent-log 哲学），
+ * 也避免 index 与单文件一致性维护的复杂度。
+ */
+export async function listSessionMetas(
+  project: ProjectSnapshot,
+): Promise<SessionMeta[]> {
+  const tree = await rescanProject(project)
+  const sessionPaths = collectSessionPaths(tree)
+  if (sessionPaths.length === 0) {
+    return []
+  }
+
+  const metas = await Promise.all(
+    sessionPaths.map(async (path) => {
+      try {
+        const text = await readProjectTextFile(project.handle, path)
+        return parseSessionMeta(text)
+      } catch {
+        return null
+      }
+    }),
+  )
+
+  return metas
+    .filter((meta): meta is SessionMeta => meta !== null)
+    .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+}
+
+export type SessionMeta = {
+  sessionId: string
+  title: string
+  createdAt: string
+  updatedAt: string
+  messageCount: number
+}
+
+/** 从会话文件树中收集 `.novel/sessions/*.json` 的完整路径。 */
+function collectSessionPaths(tree: TreeNode[]): string[] {
+  const paths: string[] = []
+
+  for (const node of tree) {
+    if (node.kind === 'file') {
+      if (node.path.startsWith(`${SESSIONS_DIR}/`) && node.path.endsWith('.json')) {
+        paths.push(node.path)
+      }
+      continue
+    }
+
+    // 只需深入 .novel 这一支，其余根目录（chapters/elements/prompts）不可能含 sessions
+    if (node.path === '.novel' && node.children?.length) {
+      const sessionsDir = node.children.find(
+        (child) => child.path === SESSIONS_DIR && child.kind === 'directory',
+      )
+      if (sessionsDir?.children?.length) {
+        for (const file of sessionsDir.children) {
+          if (file.kind === 'file' && file.path.endsWith('.json')) {
+            paths.push(file.path)
+          }
+        }
+      }
+    }
+  }
+
+  return paths
+}
+
+/** 解析会话全文为完整状态。解析失败返回 null。 */
+function parseSession(text: string): ChatSessionState | null {
+  try {
+    const parsed = JSON.parse(text) as ChatSessionState
+    if (!parsed?.sessionId) {
+      return null
+    }
+    return normalizeSession(parsed)
+  } catch {
+    return null
+  }
+}
+
+/** 解析出列表展示所需的摘要字段，避免给前端塞完整消息体。 */
+function parseSessionMeta(text: string): SessionMeta | null {
+  const session = parseSession(text)
+  if (!session) {
+    return null
+  }
+
+  return {
+    sessionId: session.sessionId,
+    title: session.title,
+    createdAt: session.createdAt,
+    updatedAt: session.updatedAt,
+    messageCount: session.messages.length,
+  }
+}
+
+/**
+ * 容错归一化：兼容缺少 title/createdAt/updatedAt 的旧文件（理论上当前不存在，但落盘数据要稳）。
+ */
+function normalizeSession(session: ChatSessionState): ChatSessionState {
+  const now = new Date().toISOString()
+  return {
+    ...session,
+    title: session.title ?? '未命名对话',
+    createdAt: session.createdAt ?? now,
+    updatedAt: session.updatedAt ?? now,
+  }
+}
diff --git a/packages/core/src/core/chat/session.ts b/packages/core/src/core/chat/session.ts
index d80f674..cdf6e9a 100644
--- a/packages/core/src/core/chat/session.ts
+++ b/packages/core/src/core/chat/session.ts
@@ -27,6 +27,7 @@ type RunChatTurnOptions = {
 }
 
 export function createChatSession(projectId: string): ChatSessionState {
+  const now = new Date().toISOString()
   return {
     sessionId: createId('session'),
     projectId,
@@ -34,6 +35,9 @@ export function createChatSession(projectId: string): ChatSessionState {
     status: 'idle',
     currentTarget: null,
     lastRagResult: null,
+    title: DEFAULT_SESSION_TITLE,
+    createdAt: now,
+    updatedAt: now,
   }
 }
 
@@ -574,3 +578,24 @@ function createId(prefix: string) {
 function resolveWrittenPath(change: FileChange): string {
   return change.type === 'renamed' ? change.toPath : change.path
 }
+
+/** 新会话默认标题，首轮用户消息后会被首句截断覆盖 */
+export const DEFAULT_SESSION_TITLE = '新对话'
+
+/** 首句截断上限（字符），用于从首条用户消息生成会话标题 */
+const SESSION_TITLE_MAX_LENGTH = 20
+
+/**
+ * 从首条用户消息派生会话标题：取首行、压空白、超长截断加省略号。
+ * 用于新建会话首轮发送后自动更新标题，避免列表里全是「新对话」。
+ */
+export function deriveSessionTitle(firstUserText: string): string {
+  const firstLine = firstUserText.split(/\r?\n/)[0] ?? firstUserText
+  const normalized = firstLine.replace(/\s+/g, ' ').trim()
+  if (!normalized) {
+    return DEFAULT_SESSION_TITLE
+  }
+  return normalized.length > SESSION_TITLE_MAX_LENGTH
+    ? `${normalized.slice(0, SESSION_TITLE_MAX_LENGTH)}…`
+    : normalized
+}
diff --git a/packages/core/src/services/agent-service.ts b/packages/core/src/services/agent-service.ts
index ebc0a82..ed4754e 100644
--- a/packages/core/src/services/agent-service.ts
+++ b/packages/core/src/services/agent-service.ts
@@ -1,7 +1,15 @@
 import {
   createChatSession,
   runChatTurn,
+  DEFAULT_SESSION_TITLE,
+  deriveSessionTitle,
 } from '../core/chat/session'
+import {
+  saveSession,
+  loadSession,
+  deleteSessionFile,
+  listSessionMetas,
+} from '../core/chat/session-store'
 import { deriveChatTargetFromPath } from '../core/chat/target'
 import { readScenePrompt, readSystemPrompt } from '../core/fs/project-fs'
 import type { ConfirmHandler } from '../core/agent/tool-execution'
@@ -16,6 +24,7 @@ import type {
   AgentUiEvent,
   ChangedFileView,
   ChatMessageView,
+  ChatSessionSummaryView,
   ChatSessionView,
   ChatTargetView,
   FileChangeConfirmationView,
@@ -28,6 +37,10 @@ import type {
   WriteConfirmationView,
 } from './types'
 
+/**
+ * 会话内存态：key 为 sessionId（一个项目可同时驻留多个历史会话）。
+ * 从「单项目单会话」升级为「多会话」，支持历史会话切换。
+ */
 const sessionMap = new Map<string, ChatSessionState>()
 
 // 确认注册表：confirmationId -> resolve。UI 调 respondConfirmation 时取出来 resolve，
@@ -38,32 +51,139 @@ type PendingConfirmation = {
 }
 const confirmationMap = new Map<string, PendingConfirmation>()
 
+/** 每个项目当前激活的会话 id；新建/切换/删除时维护。 */
+const activeSessionByProject = new Map<string, string>()
+
 export function deriveTargetFromPath(path?: string | null): ChatTargetView | null {
   return toChatTargetView(deriveChatTargetFromPath(path))
 }
 
 export async function createSession(projectId: string): Promise<ChatSessionView> {
-  requireRuntimeProject(projectId)
+  const project = requireRuntimeProject(projectId)
 
   const session = createChatSession(projectId)
-  sessionMap.set(projectId, session)
+  sessionMap.set(session.sessionId, session)
+  activeSessionByProject.set(projectId, session.sessionId)
+
+  // 新建即落盘，确保列表能立即看到（即便用户还没发消息）
+  await saveSession(project, session)
+
+  return toChatSessionView(session)
+}
+
+/**
+ * 取会话视图。sessionId 缺省时返回该项目当前激活会话。
+ * 内存未命中时从文件系统加载并缓存，支持「冷启动后查看历史会话」。
+ */
+export async function getSession(
+  projectId: string,
+  sessionId?: string,
+): Promise<ChatSessionView | null> {
+  const targetId = sessionId ?? activeSessionByProject.get(projectId)
+  if (!targetId) {
+    return null
+  }
+
+  const session = await resolveSession(projectId, targetId)
+  if (!session) {
+    return null
+  }
+
+  // 若传了 sessionId 且与当前激活不同，则切换激活
+  if (sessionId && activeSessionByProject.get(projectId) !== sessionId) {
+    activeSessionByProject.set(projectId, sessionId)
+  }
+
+  return toChatSessionView(session)
+}
+
+/** 列出项目下所有历史会话摘要（按 updatedAt 降序）。 */
+export async function listSessions(
+  projectId: string,
+): Promise<ChatSessionSummaryView[]> {
+  const project = requireRuntimeProject(projectId)
+  const metas = await listSessionMetas(project)
+
+  return metas.map((meta) => ({
+    sessionId: meta.sessionId,
+    projectId,
+    title: meta.title,
+    createdAt: meta.createdAt,
+    updatedAt: meta.updatedAt,
+    messageCount: meta.messageCount,
+  }))
+}
+
+/** 重命名会话标题（只改 state.title，不动文件名）。返回更新后的视图。 */
+export async function renameSession(
+  projectId: string,
+  sessionId: string,
+  title: string,
+): Promise<ChatSessionView> {
+  const project = requireRuntimeProject(projectId)
+  const session = await resolveSession(projectId, sessionId)
+  if (!session) {
+    throw new Error(`会话不存在或已删除：${sessionId}`)
+  }
+
+  session.title = title.trim() || DEFAULT_SESSION_TITLE
+  await saveSession(project, session)
 
   return toChatSessionView(session)
 }
 
-export async function getSession(projectId: string): Promise<ChatSessionView | null> {
-  const session = sessionMap.get(projectId)
-  return session ? toChatSessionView(session) : null
+/** 删除会话：删文件 + 移出内存；若删的是激活会话则激活置空（由前端决定后续切到哪条）。 */
+export async function deleteSession(projectId: string, sessionId: string): Promise<void> {
+  const project = requireRuntimeProject(projectId)
+
+  await deleteSessionFile(project, sessionId)
+  sessionMap.delete(sessionId)
+
+  if (activeSessionByProject.get(projectId) === sessionId) {
+    activeSessionByProject.delete(projectId)
+  }
+}
+
+/**
+ * 取会话状态：内存优先，未命中则从盘读入并缓存。
+ * 这是 sessionMap 多会话化后的统一读取入口。
+ */
+async function resolveSession(
+  projectId: string,
+  sessionId: string,
+): Promise<ChatSessionState | null> {
+  const cached = sessionMap.get(sessionId)
+  if (cached) {
+    return cached
+  }
+
+  const project = requireRuntimeProject(projectId)
+  const loaded = await loadSession(project, sessionId)
+  if (!loaded) {
+    return null
+  }
+
+  sessionMap.set(sessionId, loaded)
+  return loaded
 }
 
 export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnResult> {
   const project = requireRuntimeProject(input.projectId)
-  const previousSession = input.sessionId
-    ? findSessionById(input.projectId, input.sessionId) ?? createChatSession(input.projectId)
-    : sessionMap.get(input.projectId) ?? createChatSession(input.projectId)
+
+  // 按 sessionId 路由到对应历史会话；都没有则新建（并落盘）。
+  const resolved = input.sessionId
+    ? await resolveSession(input.projectId, input.sessionId)
+    : null
+  const previousSession = resolved
+    ?? await resolveActiveOrCreate(input.projectId)
   const runId = createRunId()
 
-  sessionMap.set(input.projectId, previousSession)
+  // 记录首轮发送前的状态，用于判断本轮是否为「首条用户消息」以自动生成标题
+  const hadNoUserMessage = !previousSession.messages.some((m) => m.role === 'user')
+  const titleBeforeTurn = previousSession.title
+
+  sessionMap.set(previousSession.sessionId, previousSession)
+  activeSessionByProject.set(input.projectId, previousSession.sessionId)
   input.onEvent?.({
     type: 'run-start',
     runId,
@@ -101,7 +221,14 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
       },
     })
 
-    sessionMap.set(input.projectId, turn.session)
+    // 首轮用户消息后，若标题仍是默认值则用首句截断自动更新
+    if (hadNoUserMessage && titleBeforeTurn === DEFAULT_SESSION_TITLE) {
+      turn.session.title = deriveSessionTitle(input.instruction)
+    }
+
+    sessionMap.set(turn.session.sessionId, turn.session)
+    // 每轮结束落盘，刷新 updatedAt，保证历史列表排序与内容持久
+    await saveSession(project, turn.session)
 
     const changedFiles = collectChangedFiles(turn.session)
     const result: RunAgentTurnResult = {
@@ -127,9 +254,24 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
   }
 }
 
-function findSessionById(projectId: string, sessionId: string) {
-  const session = sessionMap.get(projectId)
-  return session?.sessionId === sessionId ? session : null
+/**
+ * 取当前激活会话；没有激活则新建并落盘。runTurn 在未显式传 sessionId 时走此路径。
+ */
+async function resolveActiveOrCreate(projectId: string): Promise<ChatSessionState> {
+  const activeId = activeSessionByProject.get(projectId)
+  if (activeId) {
+    const cached = await resolveSession(projectId, activeId)
+    if (cached) {
+      return cached
+    }
+  }
+
+  const project = requireRuntimeProject(projectId)
+  const session = createChatSession(projectId)
+  sessionMap.set(session.sessionId, session)
+  activeSessionByProject.set(projectId, session.sessionId)
+  await saveSession(project, session)
+  return session
 }
 
 /**
@@ -265,6 +407,9 @@ function toChatSessionView(
     messages: session.messages.map(toChatMessageView),
     currentTargetPath: session.currentTarget?.primaryPath,
     lastChangedFile,
+    title: session.title,
+    createdAt: session.createdAt,
+    updatedAt: session.updatedAt,
   }
 }
 
diff --git a/packages/core/src/services/types.ts b/packages/core/src/services/types.ts
index 56a4f75..405dc61 100644
--- a/packages/core/src/services/types.ts
+++ b/packages/core/src/services/types.ts
@@ -315,6 +315,23 @@ export type ChatSessionView = {
   messages: ChatMessageView[]
   currentTargetPath?: string
   lastChangedFile?: ChangedFileView
+  /** 会话标题，可选以兼容旧 view */
+  title?: string
+  createdAt?: string
+  updatedAt?: string
+}
+
+/**
+ * 历史会话列表项：只携带列表展示所需的摘要字段，不含完整消息体。
+ * listSessions 返回该数组，供前端对话分类面板渲染。
+ */
+export type ChatSessionSummaryView = {
+  sessionId: string
+  projectId: string
+  title: string
+  createdAt: string
+  updatedAt: string
+  messageCount: number
 }
 
 export type RunAgentTurnInput = {
diff --git a/packages/core/src/types/chat.ts b/packages/core/src/types/chat.ts
index 3094ba9..dfd395f 100644
--- a/packages/core/src/types/chat.ts
+++ b/packages/core/src/types/chat.ts
@@ -108,6 +108,28 @@ export type ChatSessionState = {
   lastWrittenPath?: string
   /** 当前会话已注入的 system message（systemPrompt + scenePrompt 拼接结果）hash，用于检测同会话内提示词变化并刷新。 */
   systemPromptHash?: string
+  /** 会话标题，列表展示用；新建默认“新对话”，首轮用户消息后自动用首句截断更新 */
+  title: string
+  /** 会话创建时间（ISO），落盘与列表排序用 */
+  createdAt: string
+  /** 会话最近更新时间（ISO），每轮保存刷新；列表按此降序 */
+  updatedAt: string
+}
+
+export type ToolRuntimeContext = {
+  project: ProjectSnapshot
+  config: ProjectConfig
+  target: ChatTargetContext | null
+  session: ChatSessionState
+}
+
+export type ToolDefinition<TInput, TOutput> = {
+  name: ChatToolName
+  description: string
+  validateInput: (input: unknown) => TInput
+  call: (input: TInput, context: ToolRuntimeContext) => Promise<TOutput>
+  summarizeInput: (input: TInput) => string
+  summarizeOutput: (output: TOutput) => string
 }
 
 export type ChatTurnInput = {

From 6a4a8e237a2941ed64ce299fc7efcb9b491a18f0 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 01:01:37 +0800
Subject: [PATCH 23/36] =?UTF-8?q?refactor(store):=20=E4=BC=98=E5=8C=96?=
 =?UTF-8?q?=E4=BC=9A=E8=AF=9D=E5=88=97=E8=A1=A8=E5=88=B7=E6=96=B0=E4=B8=8E?=
 =?UTF-8?q?=E5=88=A0=E9=99=A4=E5=88=87=E6=8D=A2=E7=9A=84=E5=88=B7=E6=96=B0?=
 =?UTF-8?q?=E5=BC=80=E9=94=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- loadSessions 不再副作用式重置 activeSessionId，激活态清理由
  明确语义的调用点自行处理，消除列表刷新竞态误清隐患。
- runServiceTurn 的 finally 改为仅标题变化时才全量刷新列表，
  避免每轮对话都全量重扫文件系统。
- deleteSession 先本地移除项减少闪烁，空列表时复用
  createNewSession(skipReload) 本地插入，省一次全量扫描。
- createNewSession 新增 skipReload 选项，initSessions 复用避免
  重复全量扫描。
---
 packages/app/src/stores/chat.ts | 76 ++++++++++++++++++++++++---------
 1 file changed, 57 insertions(+), 19 deletions(-)

diff --git a/packages/app/src/stores/chat.ts b/packages/app/src/stores/chat.ts
index 479274d..9003272 100644
--- a/packages/app/src/stores/chat.ts
+++ b/packages/app/src/stores/chat.ts
@@ -58,18 +58,20 @@ export const useChatStore = defineStore('chat', () => {
       return sessionView.value!
     }
 
-    return createNewSession(projectId)
+    // 无历史：新建。列表刚拉过且为空，跳过 createNewSession 内部的二次全量扫描，
+    // 直接本地插入新会话摘要。
+    return createNewSession(projectId, { skipReload: true })
   }
 
-  /** 拉取并刷新历史会话列表，同步当前激活 id。 */
+  /**
+   * 拉取并刷新历史会话列表。
+   * 只负责更新列表数据，**不修改 activeSessionId**——激活态的清理由明确语义的调用点
+   * （如 deleteSession）自行处理，避免列表刷新与激活态维护耦合产生的竞态误清。
+   */
   async function loadSessions(projectId: string) {
     isLoadingSessions.value = true
     try {
       sessions.value = await listAgentSessions(projectId)
-      // 列表里已不存在当前激活会话时清空（例如被删除）
-      if (activeSessionId.value && !sessions.value.some((s) => s.sessionId === activeSessionId.value)) {
-        activeSessionId.value = null
-      }
     } finally {
       isLoadingSessions.value = false
     }
@@ -90,12 +92,31 @@ export const useChatStore = defineStore('chat', () => {
     return view
   }
 
-  /** 新建会话：创建 + 激活 + 刷新列表。 */
-  async function createNewSession(projectId: string): Promise<ChatSessionView> {
+  /**
+   * 新建会话：创建 + 激活 + 刷新列表。
+   * skipReload=true 时跳过内部全量刷新（调用方已确知列表状态，如 initSessions 走过 loadSessions、
+   * 或 deleteSession 清空后），改为本地插入新会话摘要到列表头部。
+   */
+  async function createNewSession(
+    projectId: string,
+    options: { skipReload?: boolean } = {},
+  ): Promise<ChatSessionView> {
     const view = await createAgentSession(projectId)
     sessionView.value = view
     activeSessionId.value = view.sessionId
-    await loadSessions(projectId)
+
+    if (options.skipReload) {
+      sessions.value = [{
+        sessionId: view.sessionId,
+        projectId,
+        title: view.title ?? '新对话',
+        createdAt: view.createdAt ?? new Date().toISOString(),
+        updatedAt: view.updatedAt ?? new Date().toISOString(),
+        messageCount: 0,
+      }, ...sessions.value]
+    } else {
+      await loadSessions(projectId)
+    }
     return view
   }
 
@@ -112,18 +133,29 @@ export const useChatStore = defineStore('chat', () => {
     }
   }
 
-  /** 删除会话；若删的是当前激活会话，则切到列表第一条或新建。 */
+  /**
+   * 删除会话；若删的是当前激活会话，则切到列表第一条或新建空会话。
+   * 删光后保留一个空「新对话」是有意为之：否则 UI 进入无活跃会话态，发消息会报错。
+   */
   async function deleteSession(projectId: string, sessionId: string): Promise<void> {
     await deleteAgentSession(projectId, sessionId)
-    await loadSessions(projectId)
 
-    if (activeSessionId.value === sessionId) {
-      if (sessions.value.length > 0) {
-        await selectSession(projectId, sessions.value[0].sessionId)
-      } else {
-        await createNewSession(projectId)
-      }
+    const wasActive = activeSessionId.value === sessionId
+    // 先从本地列表移除，避免 await 期间 UI 闪烁残留项
+    sessions.value = sessions.value.filter((s) => s.sessionId !== sessionId)
+
+    if (!wasActive) {
+      return
+    }
+
+    // 删的是当前会话：切到剩余的第一条（列表已按 updatedAt 降序）
+    if (sessions.value.length > 0) {
+      await selectSession(projectId, sessions.value[0].sessionId)
+      return
     }
+
+    // 列表已空：新建空会话并本地插入，省一次全量重扫（skipReload）
+    await createNewSession(projectId, { skipReload: true })
   }
 
   async function runServiceTurn(
@@ -135,6 +167,8 @@ export const useChatStore = defineStore('chat', () => {
       throw new Error('没有活跃的会话')
     }
     const currentSession = sessionView.value
+    // 记录本轮前标题，用于 finally 判断是否需要刷新列表（首轮会自动生成标题）
+    const titleBeforeTurn = currentSession.title
 
     agentEvents.value = []
     changedFiles.value = []
@@ -170,8 +204,12 @@ export const useChatStore = defineStore('chat', () => {
       isRunning.value = false
       isStopping.value = false
       activeAbortController = null
-      // 刷新历史列表（捕获首轮后的自动标题更新与 updatedAt 变化）
-      void loadSessions(currentSession.projectId)
+      // 仅当标题发生变化（典型：首轮发送后自动生成标题）才全量刷新列表，
+      // 避免每轮对话都全量重扫文件系统。updatedAt 的时间戳显示精度可接受滞后。
+      const titleAfterTurn = sessionView.value?.title
+      if (titleAfterTurn && titleAfterTurn !== titleBeforeTurn) {
+        void loadSessions(currentSession.projectId)
+      }
     }
   }
 

From 31dc592a3078da45d8fbc14c3f6be3e550318e99 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 02:13:07 +0800
Subject: [PATCH 24/36] =?UTF-8?q?fix(ui):=20=E4=BF=AE=E5=A4=8D=E4=BC=9A?=
 =?UTF-8?q?=E8=AF=9D=E9=87=8D=E5=91=BD=E5=90=8D=E8=BE=93=E5=85=A5=E6=A1=86?=
 =?UTF-8?q?=E7=9A=84=E9=87=8D=E5=A4=8D=E6=8F=90=E4=BA=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Enter 提交后 input 卸载触发 blur 会再次调用 commitRename，
导致 rename 事件被 emit 两次。加入 renamingId 防重入守卫。
---
 packages/app/src/components/category/ConversationList.vue | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/packages/app/src/components/category/ConversationList.vue b/packages/app/src/components/category/ConversationList.vue
index 0b9de2a..8a2f9d9 100644
--- a/packages/app/src/components/category/ConversationList.vue
+++ b/packages/app/src/components/category/ConversationList.vue
@@ -24,6 +24,12 @@ function startRename(session: ChatSessionSummaryView) {
 }
 
 function commitRename(sessionId: string) {
+  // 防重入：Enter 会先触发 keydown 提交，随即 input 卸载又触发 blur。
+  // 第一次提交后 renamingId 已置 null，第二次进入直接返回，避免重复 emit。
+  if (renamingId.value === null) {
+    return
+  }
+
   const title = renameDraft.value.trim()
   renamingId.value = null
   if (title) {

From 5b2a5f0e89ea90b9e8ab8acfbaa75674e4713747 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 03:00:24 +0800
Subject: [PATCH 25/36] =?UTF-8?q?docs(docs):=20=E6=9B=B4=E6=96=B0=20docs?=
 =?UTF-8?q?=20=E5=AD=90=E6=A8=A1=E5=9D=97=E5=90=8C=E6=AD=A5=20Agent=20?=
 =?UTF-8?q?=E6=8E=A7=E5=88=B6=E8=83=BD=E5=8A=9B=20Step=205/6=20=E7=8A=B6?=
 =?UTF-8?q?=E6=80=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs b/docs
index c312e6d..73f9847 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit c312e6d20732dcc730e2d76eca0832999d3fffa1
+Subproject commit 73f9847bd6f7ac3be8bca3a5a950bdee4267a214

From c575d46d88bcf71ebd8d6172536a79682fd46ede Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 19:20:40 +0800
Subject: [PATCH 26/36] =?UTF-8?q?feat(project):=20=E8=A1=A5=E9=BD=90?=
 =?UTF-8?q?=E5=8F=AA=E8=AF=BB=E4=B8=8D=E5=86=99=E4=B8=8E=E5=8F=AA=E6=93=8D?=
 =?UTF-8?q?=E4=BD=9C=E5=BD=93=E5=89=8D=E6=96=87=E4=BB=B6=E5=B7=A5=E5=85=B7?=
 =?UTF-8?q?=E7=BA=A6=E6=9D=9F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Agent 控制能力 Step 5 第二轮，新增两类更细的工具约束策略：

- 只读不写：识别「只读不改」「只看不写」「只分析不修改」等正面表达，
  命中则 allowWrite:false，读取工具保留
- 只操作当前文件：识别「只改当前文件」「就在这个文件改」「别动其他文件」
  等表达，结合 activeFilePath 设 allowedWritePath 白名单；activeFilePath
  为空时降级为禁写

实现要点：
- ToolPolicy 新增 allowedWritePath 字段承载路径约束
- parseToolPolicy 签名扩展为 (instruction, activeFilePath?)，路径约束
  是更具体的意图，覆盖「别动」被误判的全禁写
- 执行层新增 isWriteBlockedByPathPolicy，RenameFile 恒拦，EditFile/
  CreateFile/DeleteFile 比对 path；插入在确认流程之前
- agent-service 解析点传入 activeFilePath
- app 层 sendMessage 补传当前打开文件路径

测试新增 12 个用例，全量 91 个测试通过，类型检查通过。
---
 docs                                          |   2 +-
 packages/app/src/stores/chat.ts               |   6 +
 .../src/core/agent/tool-execution.test.ts     |  97 ++++++++++++++
 .../core/src/core/agent/tool-execution.ts     |  22 ++-
 .../core/src/core/agent/tool-policy.test.ts   |  87 ++++++++++++
 packages/core/src/core/agent/tool-policy.ts   | 125 +++++++++++++++++-
 packages/core/src/services/agent-service.ts   |   5 +-
 7 files changed, 334 insertions(+), 10 deletions(-)

diff --git a/docs b/docs
index 73f9847..7aace5f 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit 73f9847bd6f7ac3be8bca3a5a950bdee4267a214
+Subproject commit 7aace5f8cf33c4b0d124ae8f905912e1e6cdab6b
diff --git a/packages/app/src/stores/chat.ts b/packages/app/src/stores/chat.ts
index 9003272..04cd24a 100644
--- a/packages/app/src/stores/chat.ts
+++ b/packages/app/src/stores/chat.ts
@@ -22,6 +22,8 @@ import type {
   RunAgentTurnResult,
 } from '@novai/core/services/types'
 
+import { useProjectStore } from './project'
+
 export const useChatStore = defineStore('chat', () => {
   const sessionView = ref<ChatSessionView | null>(null)
   const agentEvents = ref<AgentUiEvent[]>([])
@@ -274,10 +276,14 @@ export const useChatStore = defineStore('chat', () => {
       throw new Error('没有活跃的会话')
     }
 
+    // 把当前打开的文件路径作为隐式上下文传入，供 Agent 工具约束（如「只改当前文件」）解析使用。
+    const projectStore = useProjectStore()
+    const activeFilePath = projectStore.activeFile?.path
     return runServiceTurn({
       projectId: sessionView.value.projectId,
       instruction: text,
       quote,
+      activeFilePath,
     })
   }
 
diff --git a/packages/core/src/core/agent/tool-execution.test.ts b/packages/core/src/core/agent/tool-execution.test.ts
index a6c0f82..591dd4c 100644
--- a/packages/core/src/core/agent/tool-execution.test.ts
+++ b/packages/core/src/core/agent/tool-execution.test.ts
@@ -268,3 +268,100 @@ describe('executeAgentTool toolPolicy', () => {
     expect(run).not.toHaveBeenCalled()
   })
 })
+
+describe('executeAgentTool path policy (allowedWritePath)', () => {
+  it('blocks EditFile when its path differs from allowedWritePath', async () => {
+    const run = vi.fn().mockResolvedValue({})
+    const confirm = vi.fn().mockResolvedValue({ accepted: true })
+    const tool = createStubTool({
+      name: 'EditFile',
+      run,
+      buildConfirmation: (input) => ({ kind: 'edit', path: (input as { path: string }).path, oldText: 'a', newText: 'b' }),
+    })
+    const tools = { EditFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    const result = await executeAgentTool({
+      call: createCall('EditFile', { path: 'chapters/002.txt' }),
+      project: stubProject,
+      tools,
+      confirm,
+      toolPolicy: { allowRead: true, allowWrite: true, allowedWritePath: 'chapters/001.txt' },
+    })
+
+    // 写非当前文件被拒：不执行、不弹确认
+    expect(run).not.toHaveBeenCalled()
+    expect(confirm).not.toHaveBeenCalled()
+    expect(result.content).toContain('chapters/001.txt')
+    expect(result.fileChange).toBeUndefined()
+  })
+
+  it('allows EditFile through when its path matches allowedWritePath', async () => {
+    const run = vi.fn().mockResolvedValue({})
+    const confirm = vi.fn().mockResolvedValue({ accepted: true })
+    const tool = createStubTool({
+      name: 'EditFile',
+      run,
+      buildConfirmation: (input) => ({ kind: 'edit', path: (input as { path: string }).path, oldText: 'a', newText: 'b' }),
+    })
+    const tools = { EditFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    await executeAgentTool({
+      call: createCall('EditFile', { path: 'chapters/001.txt' }),
+      project: stubProject,
+      tools,
+      confirm,
+      toolPolicy: { allowRead: true, allowWrite: true, allowedWritePath: 'chapters/001.txt' },
+    })
+
+    // 写当前文件放行（仍走确认流程）
+    expect(confirm).toHaveBeenCalledTimes(1)
+    expect(run).toHaveBeenCalledTimes(1)
+  })
+
+  it('always blocks RenameFile under path constraint', async () => {
+    const run = vi.fn().mockResolvedValue({})
+    const confirm = vi.fn().mockResolvedValue({ accepted: true })
+    const tool = createStubTool({
+      name: 'RenameFile',
+      run,
+      buildConfirmation: (input) => ({ kind: 'rename', fromPath: (input as { fromPath: string }).fromPath, toPath: (input as { toPath: string }).toPath }),
+    })
+    const tools = { RenameFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    const result = await executeAgentTool({
+      call: createCall('RenameFile', { fromPath: 'chapters/001.txt', toPath: 'chapters/002.txt' }),
+      project: stubProject,
+      tools,
+      confirm,
+      toolPolicy: { allowRead: true, allowWrite: true, allowedWritePath: 'chapters/001.txt' },
+    })
+
+    // 即便 fromPath 是当前文件，RenameFile 仍被禁
+    expect(run).not.toHaveBeenCalled()
+    expect(confirm).not.toHaveBeenCalled()
+    expect(result.content).toContain('重命名')
+  })
+
+  it('path constraint takes precedence over confirmation', async () => {
+    const run = vi.fn().mockResolvedValue({})
+    const confirm = vi.fn().mockResolvedValue({ accepted: true })
+    const tool = createStubTool({
+      name: 'CreateFile',
+      run,
+      buildConfirmation: (input) => ({ kind: 'create', path: (input as { path: string }).path, content: '' }),
+    })
+    const tools = { CreateFile: tool } as unknown as Record<string, AgentRunnableTool>
+
+    await executeAgentTool({
+      call: createCall('CreateFile', { path: 'outline.txt' }),
+      project: stubProject,
+      tools,
+      confirm,
+      toolPolicy: { allowRead: true, allowWrite: true, allowedWritePath: 'chapters/001.txt' },
+    })
+
+    // 路径不匹配直接拒，不弹确认
+    expect(confirm).not.toHaveBeenCalled()
+    expect(run).not.toHaveBeenCalled()
+  })
+})
diff --git a/packages/core/src/core/agent/tool-execution.ts b/packages/core/src/core/agent/tool-execution.ts
index 7dee063..2bafae2 100644
--- a/packages/core/src/core/agent/tool-execution.ts
+++ b/packages/core/src/core/agent/tool-execution.ts
@@ -2,7 +2,7 @@ import type { ProjectSnapshot } from '../../types/project'
 import type { AgentToolCall, AgentToolResultMessage } from './messages'
 import type { AgentRunnableToolMap } from './tools'
 import type { FileChange, ReadFileState, WriteConfirmation } from '../tools/types'
-import { type ToolPolicy, isToolDisabledByPolicy, describePolicyDenial } from './tool-policy'
+import { type ToolPolicy, isToolDisabledByPolicy, describePolicyDenial, isWriteBlockedByPathPolicy } from './tool-policy'
 
 export type ToolExecutionEvent =
   | { type: 'tool-call'; call: AgentToolCall; inputSummary: string }
@@ -109,6 +109,26 @@ export async function executeAgentTool(input: {
     }
   }
 
+  // 路径级约束：写工具的路径必须落在允许的文件上（RenameFile 直接禁用）。
+  // 与上面的读/写布尔约束同属硬约束，同样在确认流程之前拦截。
+  const pathBlock = isWriteBlockedByPathPolicy(input.call.name, validatedInput, input.toolPolicy)
+  if (pathBlock.blocked) {
+    const reason = pathBlock.reason ?? '该工具本轮被用户约束禁用'
+    input.onEvent?.({
+      type: 'tool-result',
+      call: input.call,
+      ok: false,
+      resultSummary: `工具被禁用：${reason}`,
+    })
+
+    return {
+      role: 'tool',
+      toolCallId: input.call.id,
+      name: input.call.name,
+      content: `该工具本轮被禁用：${reason}。请遵守该约束，改用纯对话回答，或向用户确认是否解除限制后再试。`,
+    }
+  }
+
   // 写工具执行前确认：构造预览并等待用户决定。
   // 拒绝时不执行 run，返回「用户已拒绝」tool result 回灌模型，让其自然调整。
   if (!tool.isReadOnly && tool.core.buildConfirmation && input.confirm) {
diff --git a/packages/core/src/core/agent/tool-policy.test.ts b/packages/core/src/core/agent/tool-policy.test.ts
index 61120fc..0334708 100644
--- a/packages/core/src/core/agent/tool-policy.test.ts
+++ b/packages/core/src/core/agent/tool-policy.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from 'vitest'
 import {
   parseToolPolicy,
   isToolDisabledByPolicy,
+  isWriteBlockedByPathPolicy,
   describePolicyDenial,
   filterAvailableTools,
   describeActivePolicy,
@@ -45,6 +46,53 @@ describe('parseToolPolicy', () => {
     expect(parseToolPolicy('读一下第一章然后写第二章')).toEqual({ allowRead: true, allowWrite: true })
     expect(parseToolPolicy('请读取文件并修改')).toEqual({ allowRead: true, allowWrite: true })
   })
+
+  it('disables write tools on read-only intent phrases (只读不改)', () => {
+    // 「只读/只看不改」等正面表达意图是「只读不写」，应禁用写入工具但保留读取
+    expect(parseToolPolicy('只读不改')).toEqual({ allowRead: true, allowWrite: false })
+    expect(parseToolPolicy('只看不写')).toEqual({ allowRead: true, allowWrite: false })
+    expect(parseToolPolicy('只分析不修改文件')).toEqual({ allowRead: true, allowWrite: false })
+    expect(parseToolPolicy('这轮只看不改文件')).toEqual({ allowRead: true, allowWrite: false })
+  })
+
+  it('sets allowedWritePath on current-file intent when activeFilePath is provided', () => {
+    expect(parseToolPolicy('只改当前文件', 'chapters/001.txt')).toEqual({
+      allowRead: true,
+      allowWrite: true,
+      allowedWritePath: 'chapters/001.txt',
+    })
+    expect(parseToolPolicy('就在这个文件里改', 'chapters/002.txt')).toEqual({
+      allowRead: true,
+      allowWrite: true,
+      allowedWritePath: 'chapters/002.txt',
+    })
+    expect(parseToolPolicy('别动其他文件', 'elements/characters.md')).toEqual({
+      allowRead: true,
+      allowWrite: true,
+      allowedWritePath: 'elements/characters.md',
+    })
+    expect(parseToolPolicy('只改这个文件', 'prompts/system.md')).toEqual({
+      allowRead: true,
+      allowWrite: true,
+      allowedWritePath: 'prompts/system.md',
+    })
+  })
+
+  it('normalizes activeFilePath when setting allowedWritePath', () => {
+    // 反斜杠 / 前后空白在 normalizeProjectPath 里会被规整
+    expect(parseToolPolicy('只改当前文件', ' chapters\\001.txt ')).toEqual({
+      allowRead: true,
+      allowWrite: true,
+      allowedWritePath: 'chapters/001.txt',
+    })
+  })
+
+  it('degrades to allowWrite:false on current-file intent when activeFilePath is empty', () => {
+    // 用户要求「只改当前文件」但没有打开的文件，无法确定白名单，保守禁写
+    expect(parseToolPolicy('只改当前文件')).toEqual({ allowRead: true, allowWrite: false })
+    expect(parseToolPolicy('只改这个文件', undefined)).toEqual({ allowRead: true, allowWrite: false })
+    expect(parseToolPolicy('别动其他文件', null)).toEqual({ allowRead: true, allowWrite: false })
+  })
 })
 
 describe('isToolDisabledByPolicy', () => {
@@ -69,6 +117,39 @@ describe('isToolDisabledByPolicy', () => {
   })
 })
 
+describe('isWriteBlockedByPathPolicy', () => {
+  it('does not block when policy has no allowedWritePath', () => {
+    expect(isWriteBlockedByPathPolicy('EditFile', { path: 'chapters/001.txt' }, DEFAULT_TOOL_POLICY)).toEqual({ blocked: false })
+    expect(isWriteBlockedByPathPolicy('EditFile', { path: 'chapters/001.txt' }, undefined)).toEqual({ blocked: false })
+  })
+
+  it('does not block read-only tools', () => {
+    const policy = { allowRead: true, allowWrite: true, allowedWritePath: 'chapters/001.txt' }
+    expect(isWriteBlockedByPathPolicy('ReadFile', { path: 'chapters/002.txt' }, policy)).toEqual({ blocked: false })
+    expect(isWriteBlockedByPathPolicy('RagSearch', { query: 'something' }, policy)).toEqual({ blocked: false })
+  })
+
+  it('always blocks RenameFile under path constraint', () => {
+    const policy = { allowRead: true, allowWrite: true, allowedWritePath: 'chapters/001.txt' }
+    const result = isWriteBlockedByPathPolicy('RenameFile', { fromPath: 'chapters/001.txt', toPath: 'chapters/002.txt' }, policy)
+    expect(result.blocked).toBe(true)
+    expect(result.reason).toContain('重命名')
+  })
+
+  it('blocks EditFile/CreateFile/DeleteFile when path differs from allowed', () => {
+    const policy = { allowRead: true, allowWrite: true, allowedWritePath: 'chapters/001.txt' }
+    expect(isWriteBlockedByPathPolicy('EditFile', { path: 'chapters/002.txt' }, policy).blocked).toBe(true)
+    expect(isWriteBlockedByPathPolicy('CreateFile', { path: 'outline.txt' }, policy).blocked).toBe(true)
+    expect(isWriteBlockedByPathPolicy('DeleteFile', { path: 'elements/characters.md' }, policy).blocked).toBe(true)
+  })
+
+  it('allows EditFile/CreateFile/DeleteFile when path matches allowed', () => {
+    const policy = { allowRead: true, allowWrite: true, allowedWritePath: 'chapters/001.txt' }
+    expect(isWriteBlockedByPathPolicy('EditFile', { path: 'chapters/001.txt' }, policy).blocked).toBe(false)
+    expect(isWriteBlockedByPathPolicy('DeleteFile', { path: 'chapters/001.txt' }, policy).blocked).toBe(false)
+  })
+})
+
 describe('describePolicyDenial', () => {
   it('describes read denial', () => {
     expect(describePolicyDenial({ isReadOnly: true }, { allowRead: false, allowWrite: true })).toContain('读取')
@@ -128,4 +209,10 @@ describe('describeActivePolicy', () => {
     expect(desc).toContain('读取类工具')
     expect(desc).toContain('写入类工具')
   })
+
+  it('mentions current-file constraint when allowedWritePath is set', () => {
+    const desc = describeActivePolicy({ allowRead: true, allowWrite: true, allowedWritePath: 'chapters/001.txt' })
+    expect(desc).toContain('chapters/001.txt')
+    expect(desc).toContain('RenameFile')
+  })
 })
diff --git a/packages/core/src/core/agent/tool-policy.ts b/packages/core/src/core/agent/tool-policy.ts
index 36a9f05..049f3ac 100644
--- a/packages/core/src/core/agent/tool-policy.ts
+++ b/packages/core/src/core/agent/tool-policy.ts
@@ -5,11 +5,20 @@
  * 不依赖 system prompt 的软提示——模型即使无视约束，执行层也会拦住。
  */
 
+import { normalizeProjectPath } from '../tools/path'
+
 export type ToolPolicy = {
   /** 是否允许读取类工具（ReadFile/ListDirectory/FindFiles/RagSearch） */
   allowRead: boolean
   /** 是否允许写入类工具（EditFile/CreateFile/RenameFile/DeleteFile） */
   allowWrite: boolean
+  /**
+   * 路径约束：写工具的路径必须落在此文件上。
+   * - EditFile/CreateFile/DeleteFile 的 path 必须等于此值；
+   * - RenameFile 整个禁用（重命名/移动会让「当前文件」概念失效）；
+   * - undefined 表示无路径约束。
+   */
+  allowedWritePath?: string
 }
 
 /** 默认策略：全部允许。无约束关键词时不影响任何现有行为。 */
@@ -35,9 +44,13 @@ const WRITE_ACTIONS = ['写', '改', '建', '删', '动', '修', '创建', '新
  * - "别改文件" → allowWrite: false
  * - "直接回答，不要查文件" → allowRead: false
  *
+ * 也识别正面表达（"只读/只看不改"）和路径约束（"只改当前文件"）：
+ * - "只读不改" / "只看不写" → allowWrite: false
+ * - "只改当前文件" / "就在这个文件改" → allowedWritePath（需传入 activeFilePath）
+ *
  * 漏判只是没禁（执行层是兜底，不出错）；误判风险通过要求"否定+动作"成对出现来降低。
  */
-export function parseToolPolicy(instruction: string): ToolPolicy {
+export function parseToolPolicy(instruction: string, activeFilePath?: string | null): ToolPolicy {
   const text = instruction.trim()
   if (!text) {
     return DEFAULT_TOOL_POLICY
@@ -50,10 +63,46 @@ export function parseToolPolicy(instruction: string): ToolPolicy {
   // "不要碰文件/别动文件"这类用通用动词的全禁表达（同时禁读禁写）
   const hasGenericDenial = /(?:不要|别|禁止|请勿)\s*(?:碰|动)\s*(?:任何|所有)?\s*文件/.test(text)
 
-  return {
-    allowRead: !(hasReadDenial || hasGenericDenial),
-    allowWrite: !(hasWriteDenial || hasGenericDenial),
+  // 正面表达："只/仅 + 读/看/分析/讨论 + (可选否定) + 写/改/动/修"，如"只读不改""只看不写""只分析不修改"。
+  // 这类表达意图是"只读不写"，应禁用写入工具。
+  const hasReadOnlyIntent = /(?:只|仅)\s*(?:读|看|分析|讨论).{0,4}(?:不|别|勿)\s*(?:写|改|动|修|改文件|动文件|修改)/.test(text)
+    || /(?:只|仅)\s*(?:不|别)\s*(?:写|改|动|修|改文件|动文件|修改)/.test(text)
+
+  // 路径约束："只改当前文件""就在这个文件改""别动其他文件"——意图把写入限制在当前文件。
+  // 单独成句的"只改当前文件"也匹配（不要求否定词）。
+  const hasCurrentFileIntent = /(?:只|仅|就)\s*(?:在|于)?\s*(?:当前|这个|本|当前这个)\s*文件\s*(?:里|内|中)?\s*(?:改|写|动|修|编辑|操作)/.test(text)
+    || /(?:只|仅|就)\s*(?:改|写|动|修|编辑|操作|动)\s*(?:当前|这个|本|当前这个)\s*文件/.test(text)
+    || /(?:不要|别|无需|不用)\s*(?:动|改|碰|写)\s*(?:其他|其它|别的)\s*文件?/.test(text)
+    || /(?:只|仅)\s*(?:动|改|碰|写|操作)\s*(?:当前|这个|本)\s*(?:一个)?\s*文件/.test(text)
+
+  const allowRead = !(hasReadDenial || hasGenericDenial)
+
+  const policy: ToolPolicy = {
+    allowRead,
+    // allowWrite 初始值见下方路径约束分支的覆盖逻辑。
+    allowWrite: !(hasWriteDenial || hasGenericDenial || hasReadOnlyIntent),
+  }
+
+  // 路径约束：用户意图把写入限制在当前文件。
+  // - 有 activeFilePath：设白名单路径，allowWrite 保持 true（允许写，只是限定在当前文件）。
+  //   注意此时若 hasWriteDenial 误命中（如「别动其他文件」被识别为全禁写），路径约束是更具体的意图，
+  //   应覆盖全禁写——语义是「能动当前文件」而非「全禁写」。
+  // - 无 activeFilePath：无法确定白名单，保守降级为全禁写。
+  if (hasCurrentFileIntent) {
+    if (activeFilePath) {
+      try {
+        policy.allowedWritePath = normalizeProjectPath(activeFilePath)
+        policy.allowWrite = true
+      } catch {
+        // activeFilePath 本身不合法（理论上不应发生），降级为禁写。
+        policy.allowWrite = false
+      }
+    } else {
+      policy.allowWrite = false
+    }
   }
+
+  return policy
 }
 
 /**
@@ -82,6 +131,9 @@ function hasNegationBeforeAction(text: string, actions: string[]): boolean {
 /**
  * 判定某工具是否被策略禁用。
  * 用 isReadOnly 二分，不硬编码工具名——未来加新工具自动归类。
+ *
+ * 注意：此函数只处理读/写布尔级别的约束。路径级约束（allowedWritePath）
+ * 由 isWriteBlockedByPathPolicy 在执行层处理（那里能拿到工具的 input 路径）。
  */
 export function isToolDisabledByPolicy(
   tool: { isReadOnly: boolean },
@@ -93,6 +145,54 @@ export function isToolDisabledByPolicy(
   return !policy.allowWrite
 }
 
+/**
+ * 判定写工具是否被路径级约束拦截。
+ * 在执行层调用（此时 validatedInput 已规整）：
+ * - policy 无 allowedWritePath → 不拦；
+ * - RenameFile → 恒拦（重命名/移动不在「只改当前文件」覆盖范围内）；
+ * - EditFile/CreateFile/DeleteFile → path 不等于 allowedWritePath 则拦；
+ * - 只读工具 → 不拦（路径约束只管写）。
+ */
+export function isWriteBlockedByPathPolicy(
+  toolName: string,
+  validatedInput: unknown,
+  policy: ToolPolicy | undefined,
+): { blocked: boolean; reason?: string } {
+  if (!policy?.allowedWritePath) {
+    return { blocked: false }
+  }
+
+  const allowed = policy.allowedWritePath
+
+  if (toolName === 'RenameFile') {
+    return {
+      blocked: true,
+      reason: `用户本轮要求只修改当前文件（${allowed}），重命名/移动不在该约束覆盖范围内`,
+    }
+  }
+
+  if (toolName === 'EditFile' || toolName === 'CreateFile' || toolName === 'DeleteFile') {
+    const inputPath = readPathField(validatedInput)
+    if (inputPath !== undefined && inputPath !== allowed) {
+      return {
+        blocked: true,
+        reason: `用户本轮要求只修改当前文件（${allowed}），不要改动其他文件`,
+      }
+    }
+  }
+
+  return { blocked: false }
+}
+
+/** 从已校验的工具 input 中提取 path 字段（EditFile/CreateFile/DeleteFile 统一用 path）。 */
+function readPathField(validatedInput: unknown): string | undefined {
+  if (validatedInput && typeof validatedInput === 'object' && 'path' in validatedInput) {
+    const value = (validatedInput as { path: unknown }).path
+    return typeof value === 'string' ? value : undefined
+  }
+  return undefined
+}
+
 /**
  * 生成面向模型的拒绝说明，回灌 tool result 让模型理解为何失败。
  */
@@ -112,6 +212,9 @@ export function describePolicyDenial(
 /**
  * 工具可见性过滤：被禁工具不发给模型，从源头减少无效的工具调用往返。
  * 返回仍可用的工具列表（保留 isReadOnly/schema 等字段）。
+ *
+ * 注意：路径级约束（allowedWritePath）在此层无法处理——它需要知道工具的具体路径，
+ * 而可见性过滤发生在调用前。路径约束由执行层 isWriteBlockedByPathPolicy 兜底。
  */
 export function filterAvailableTools<T extends { isReadOnly: boolean }>(
   tools: T[],
@@ -136,8 +239,18 @@ export function describeActivePolicy(policy: ToolPolicy): string {
   if (!policy.allowWrite) {
     denied.push('写入类工具（EditFile / CreateFile / RenameFile / DeleteFile）')
   }
-  if (denied.length === 0) {
+
+  if (denied.length === 0 && !policy.allowedWritePath) {
     return ''
   }
-  return `【本轮工具约束】用户本轮已禁用：${denied.join('、')}。请用纯对话回答，或向用户确认是否解除限制；不要尝试绕过该约束。`
+
+  const lines: string[] = []
+  if (denied.length > 0) {
+    lines.push(`用户本轮已禁用：${denied.join('、')}`)
+  }
+  if (policy.allowedWritePath) {
+    lines.push(`写入操作仅限当前文件（${policy.allowedWritePath}），RenameFile（重命名/移动）不可用`)
+  }
+
+  return `【本轮工具约束】${lines.join('；')}。请用纯对话回答，或向用户确认是否解除限制；不要尝试绕过该约束。`
 }
diff --git a/packages/core/src/services/agent-service.ts b/packages/core/src/services/agent-service.ts
index ed4754e..7decbdc 100644
--- a/packages/core/src/services/agent-service.ts
+++ b/packages/core/src/services/agent-service.ts
@@ -200,8 +200,9 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
     const confirm: ConfirmHandler | undefined = input.onEvent
       ? (request) => requestConfirmation(input.projectId, request, input.onEvent!)
       : undefined
-    // 用户即时工具约束：从 instruction 解析（如「不要读文件」「别改」），执行层强制禁用。
-    const toolPolicy = parseToolPolicy(input.instruction)
+    // 用户即时工具约束：从 instruction 解析（如「不要读文件」「别改」「只读不改」「只改当前文件」），执行层强制禁用。
+    // 路径约束需结合当前活动文件解析，activeFilePath 无值时降级为禁写。
+    const toolPolicy = parseToolPolicy(input.instruction, input.activeFilePath)
     const turn = await runChatTurn({
       session: previousSession,
       input: {

From 53de64c134cf8de484b98a78114c721f09d10f0b Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 19:40:12 +0800
Subject: [PATCH 27/36] =?UTF-8?q?perf(project):=20=E4=BC=98=E5=8C=96?=
 =?UTF-8?q?=E4=BC=9A=E8=AF=9D=E7=BC=93=E5=AD=98=20LRU=20=E4=B8=8E=E5=8E=86?=
 =?UTF-8?q?=E5=8F=B2=E5=88=97=E8=A1=A8=E6=89=AB=E6=8F=8F=E5=BC=80=E9=94=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- agent-service: sessionMap 改 LRU 上限16，命中回插刷新顺序，超限淘汰最旧
- agent-service: 新增 evictProjectSessions，项目关闭/删除时释放驻留会话
- project-service: closeProject 与 deleteRecentProject 接入会话缓存清理
- project-fs: 新增 listFilesInDirectory 原语，只遍历单个子目录
- session-store: listSessionMetas 改用 listFilesInDirectory 去掉全树扫描
- 新增 agent-service.session-cache.test.ts 覆盖 LRU 与项目级清理
---
 packages/core/src/core/chat/session-store.ts  | 44 ++-------
 packages/core/src/core/fs/project-fs.ts       | 29 ++++++
 .../agent-service.session-cache.test.ts       | 99 +++++++++++++++++++
 packages/core/src/services/agent-service.ts   | 61 +++++++++++-
 packages/core/src/services/project-service.ts |  5 +
 5 files changed, 196 insertions(+), 42 deletions(-)
 create mode 100644 packages/core/src/services/agent-service.session-cache.test.ts

diff --git a/packages/core/src/core/chat/session-store.ts b/packages/core/src/core/chat/session-store.ts
index 82ab360..fa582b9 100644
--- a/packages/core/src/core/chat/session-store.ts
+++ b/packages/core/src/core/chat/session-store.ts
@@ -2,9 +2,9 @@ import {
   readProjectTextFile,
   writeProjectTextFile,
   removeProjectFile,
-  rescanProject,
+  listFilesInDirectory,
 } from '../fs/project-fs'
-import type { ProjectSnapshot, TreeNode } from '../../types/project'
+import type { ProjectSnapshot } from '../../types/project'
 import type { ChatSessionState } from '../../types/chat'
 
 /**
@@ -63,15 +63,15 @@ export async function deleteSessionFile(
 /**
  * 列出项目下所有历史会话的摘要，按 updatedAt 降序（最近更新的在前）。
  *
- * 实现走 rescanProject 拿全树后筛选 `.novel/sessions/*.json`，再逐个读全文解析元字段。
- * 之所以不维护 index.json：会话量在小说项目里很小，单文件自包含更可靠（对齐 agent-log 哲学），
- * 也避免 index 与单文件一致性维护的复杂度。
+ * 只打开 `.novel/sessions/` 这一个目录遍历文件，而非 rescanProject 的全树扫描——
+ * 会话列表的瓶颈在章节数众多的项目里，全树扫描会遍历 chapters/、elements/ 等无关目录。
+ * 单文件自包含、不维护 index.json，对齐 agent-log 哲学（会话量在小说项目里很小）。
  */
 export async function listSessionMetas(
   project: ProjectSnapshot,
 ): Promise<SessionMeta[]> {
-  const tree = await rescanProject(project)
-  const sessionPaths = collectSessionPaths(tree)
+  const allPaths = await listFilesInDirectory(project.handle, SESSIONS_DIR)
+  const sessionPaths = allPaths.filter((path) => path.endsWith('.json'))
   if (sessionPaths.length === 0) {
     return []
   }
@@ -100,36 +100,6 @@ export type SessionMeta = {
   messageCount: number
 }
 
-/** 从会话文件树中收集 `.novel/sessions/*.json` 的完整路径。 */
-function collectSessionPaths(tree: TreeNode[]): string[] {
-  const paths: string[] = []
-
-  for (const node of tree) {
-    if (node.kind === 'file') {
-      if (node.path.startsWith(`${SESSIONS_DIR}/`) && node.path.endsWith('.json')) {
-        paths.push(node.path)
-      }
-      continue
-    }
-
-    // 只需深入 .novel 这一支，其余根目录（chapters/elements/prompts）不可能含 sessions
-    if (node.path === '.novel' && node.children?.length) {
-      const sessionsDir = node.children.find(
-        (child) => child.path === SESSIONS_DIR && child.kind === 'directory',
-      )
-      if (sessionsDir?.children?.length) {
-        for (const file of sessionsDir.children) {
-          if (file.kind === 'file' && file.path.endsWith('.json')) {
-            paths.push(file.path)
-          }
-        }
-      }
-    }
-  }
-
-  return paths
-}
-
 /** 解析会话全文为完整状态。解析失败返回 null。 */
 function parseSession(text: string): ChatSessionState | null {
   try {
diff --git a/packages/core/src/core/fs/project-fs.ts b/packages/core/src/core/fs/project-fs.ts
index 9d0496e..ad6068b 100644
--- a/packages/core/src/core/fs/project-fs.ts
+++ b/packages/core/src/core/fs/project-fs.ts
@@ -213,6 +213,35 @@ export async function rescanProject(snapshot: ProjectSnapshot): Promise<TreeNode
   return scanDirectory(snapshot.handle)
 }
 
+/**
+ * 列出项目内某子目录下所有文件的相对路径（不递归子目录）。
+ * 目录不存在时返回空数组，不抛错——调用方按「该目录无内容」处理即可。
+ *
+ * 相比 rescanProject 的全树扫描，这里只打开单个目标目录遍历，适合「只需要某个子目录文件清单」的场景
+ * （如 .novel/sessions/ 下的会话列表），避免无关目录的开销。
+ */
+export async function listFilesInDirectory(
+  rootHandle: FileSystemDirectoryHandle,
+  dirPath: string,
+): Promise<string[]> {
+  let directory: FileSystemDirectoryHandle
+  try {
+    directory = await resolveDirectoryHandle(rootHandle, dirPath)
+  } catch {
+    // 目录不存在（或路径非法）视为空
+    return []
+  }
+
+  const paths: string[] = []
+  const prefix = dirPath.endsWith('/') ? dirPath : `${dirPath}/`
+  for await (const entry of directory.values()) {
+    if (entry.kind === 'file') {
+      paths.push(`${prefix}${entry.name}`)
+    }
+  }
+  return paths
+}
+
 /**
  * 读取 `novel.config.json` 并返回当前项目配置。
  */
diff --git a/packages/core/src/services/agent-service.session-cache.test.ts b/packages/core/src/services/agent-service.session-cache.test.ts
new file mode 100644
index 0000000..cd4beed
--- /dev/null
+++ b/packages/core/src/services/agent-service.session-cache.test.ts
@@ -0,0 +1,99 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import {
+  cacheSession,
+  evictProjectSessions,
+  _clearSessionCacheForTest,
+  _getCachedSessionIdsForTest,
+} from './agent-service'
+import type { ChatSessionState } from '../types/chat'
+
+/**
+ * 纯内存测试：验证会话缓存的上限淘汰（LRU）与项目级清理，不触及文件系统与 LLM。
+ * cacheSession 通过 Map 插入顺序实现 LRU：delete+set 把命中条目移到末尾（最近），
+ * 超过 MAX_CACHED_SESSIONS（=16）时从头部（最旧）淘汰。
+ */
+describe('agent-service 会话缓存（LRU + 项目级清理）', () => {
+  beforeEach(() => {
+    _clearSessionCacheForTest()
+  })
+
+  it('cacheSession 写入即驻留，按写入顺序排列', () => {
+    cacheSession(buildSession('s1', 'proj-a'))
+    cacheSession(buildSession('s2', 'proj-a'))
+
+    expect(_getCachedSessionIdsForTest()).toEqual(['s1', 's2'])
+  })
+
+  it('超过上限（16）时淘汰最旧条目', () => {
+    // 写入 17 条，期望最早那条被淘汰，保留 16 条
+    for (let i = 0; i < 17; i += 1) {
+      cacheSession(buildSession(`s${i}`, 'proj-a'))
+    }
+
+    const ids = _getCachedSessionIdsForTest()
+    expect(ids).toHaveLength(16)
+    // s0 最先写入、从未再被访问，应被淘汰
+    expect(ids).not.toContain('s0')
+    expect(ids[0]).toBe('s1')
+    expect(ids[15]).toBe('s16')
+  })
+
+  it('重新写入（命中）会把条目移到末尾，刷新 LRU 顺序', () => {
+    cacheSession(buildSession('s1', 'proj-a'))
+    cacheSession(buildSession('s2', 'proj-a'))
+    cacheSession(buildSession('s3', 'proj-a'))
+
+    // 把 s1 重新写入，它应移到末尾
+    cacheSession(buildSession('s1', 'proj-a'))
+
+    expect(_getCachedSessionIdsForTest()).toEqual(['s2', 's3', 's1'])
+  })
+
+  it('命中刷新使旧条目免于被淘汰', () => {
+    // 写满 16 条，再把最早的 s0 刷新一次，再写入第 17 条
+    for (let i = 0; i < 16; i += 1) {
+      cacheSession(buildSession(`s${i}`, 'proj-a'))
+    }
+    cacheSession(buildSession('s0', 'proj-a')) // s0 移到末尾
+
+    cacheSession(buildSession('s16', 'proj-a')) // 触发淘汰，最旧的现在是 s1
+
+    const ids = _getCachedSessionIdsForTest()
+    expect(ids).toHaveLength(16)
+    expect(ids).toContain('s0') // 被 refresh 保护下来
+    expect(ids).not.toContain('s1') // 变成最旧被淘汰
+  })
+
+  it('evictProjectSessions 移除指定项目的全部会话，保留其它项目', () => {
+    cacheSession(buildSession('a1', 'proj-a'))
+    cacheSession(buildSession('a2', 'proj-a'))
+    cacheSession(buildSession('b1', 'proj-b'))
+
+    evictProjectSessions('proj-a')
+
+    const ids = _getCachedSessionIdsForTest()
+    expect(ids).toEqual(['b1'])
+  })
+
+  it('evictProjectSessions 对不存在的项目不抛错', () => {
+    cacheSession(buildSession('a1', 'proj-a'))
+    expect(() => evictProjectSessions('proj-none')).not.toThrow()
+    expect(_getCachedSessionIdsForTest()).toEqual(['a1'])
+  })
+})
+
+function buildSession(sessionId: string, projectId: string): ChatSessionState {
+  const now = new Date().toISOString()
+  return {
+    sessionId,
+    projectId,
+    messages: [],
+    status: 'idle',
+    currentTarget: null,
+    lastRagResult: null,
+    title: '测试会话',
+    createdAt: now,
+    updatedAt: now,
+  }
+}
diff --git a/packages/core/src/services/agent-service.ts b/packages/core/src/services/agent-service.ts
index 7decbdc..6de075b 100644
--- a/packages/core/src/services/agent-service.ts
+++ b/packages/core/src/services/agent-service.ts
@@ -40,9 +40,16 @@ import type {
 /**
  * 会话内存态：key 为 sessionId（一个项目可同时驻留多个历史会话）。
  * 从「单项目单会话」升级为「多会话」，支持历史会话切换。
+ *
+ * 用 Map 的插入顺序天然作为 LRU：访问/写入时 delete+set 把条目移到末尾（最近），
+ * 超过 MAX_CACHED_SESSIONS 时从头部（最旧）淘汰。项目关闭时由 evictProjectSessions
+ * 整体清理该项目条目，避免长期累积内存泄漏。
  */
 const sessionMap = new Map<string, ChatSessionState>()
 
+/** 内存驻留会话上限。超过则按 LRU 淘汰最旧条目；冷数据回退到从盘读取。 */
+const MAX_CACHED_SESSIONS = 16
+
 // 确认注册表：confirmationId -> resolve。UI 调 respondConfirmation 时取出来 resolve，
 // 唤醒在 confirm 回调里 await 的 Agent Loop。
 type PendingConfirmation = {
@@ -54,6 +61,48 @@ const confirmationMap = new Map<string, PendingConfirmation>()
 /** 每个项目当前激活的会话 id；新建/切换/删除时维护。 */
 const activeSessionByProject = new Map<string, string>()
 
+/**
+ * 写入会话缓存：delete 后 set 把条目移到 Map 末尾（标记为最近使用），
+ * 再在超限时淘汰头部（最旧）。所有缓存插入统一走这里，保证 LRU 一致性。
+ *
+ * 导出仅供单测直接驱动缓存（验证 LRU 淘汰 / 项目级清理），业务代码不应直接调用。
+ */
+export function cacheSession(session: ChatSessionState) {
+  sessionMap.delete(session.sessionId)
+  sessionMap.set(session.sessionId, session)
+  while (sessionMap.size > MAX_CACHED_SESSIONS) {
+    const oldest = sessionMap.keys().next().value
+    if (oldest === undefined) {
+      break
+    }
+    sessionMap.delete(oldest)
+  }
+}
+
+/**
+ * 项目级清理：移除该项目的所有驻留会话 + 激活态。
+ * 供 closeProject / deleteRecentProject 在释放运行时项目时调用，避免历史会话累积泄漏。
+ */
+export function evictProjectSessions(projectId: string) {
+  for (const [id, session] of sessionMap) {
+    if (session.projectId === projectId) {
+      sessionMap.delete(id)
+    }
+  }
+  activeSessionByProject.delete(projectId)
+}
+
+/** 测试专用：重置 module-global 缓存，避免用例间状态串扰。 */
+export function _clearSessionCacheForTest() {
+  sessionMap.clear()
+  activeSessionByProject.clear()
+}
+
+/** 测试专用：读取当前缓存内的 sessionId 列表（按 LRU 顺序，最近使用在末尾）。 */
+export function _getCachedSessionIdsForTest(): string[] {
+  return Array.from(sessionMap.keys())
+}
+
 export function deriveTargetFromPath(path?: string | null): ChatTargetView | null {
   return toChatTargetView(deriveChatTargetFromPath(path))
 }
@@ -62,7 +111,7 @@ export async function createSession(projectId: string): Promise<ChatSessionView>
   const project = requireRuntimeProject(projectId)
 
   const session = createChatSession(projectId)
-  sessionMap.set(session.sessionId, session)
+  cacheSession(session)
   activeSessionByProject.set(projectId, session.sessionId)
 
   // 新建即落盘，确保列表能立即看到（即便用户还没发消息）
@@ -154,6 +203,8 @@ async function resolveSession(
 ): Promise<ChatSessionState | null> {
   const cached = sessionMap.get(sessionId)
   if (cached) {
+    // 命中即回插，刷新 LRU 顺序（最近使用移到末尾）
+    cacheSession(cached)
     return cached
   }
 
@@ -163,7 +214,7 @@ async function resolveSession(
     return null
   }
 
-  sessionMap.set(sessionId, loaded)
+  cacheSession(loaded)
   return loaded
 }
 
@@ -182,7 +233,7 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
   const hadNoUserMessage = !previousSession.messages.some((m) => m.role === 'user')
   const titleBeforeTurn = previousSession.title
 
-  sessionMap.set(previousSession.sessionId, previousSession)
+  cacheSession(previousSession)
   activeSessionByProject.set(input.projectId, previousSession.sessionId)
   input.onEvent?.({
     type: 'run-start',
@@ -227,7 +278,7 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
       turn.session.title = deriveSessionTitle(input.instruction)
     }
 
-    sessionMap.set(turn.session.sessionId, turn.session)
+    cacheSession(turn.session)
     // 每轮结束落盘，刷新 updatedAt，保证历史列表排序与内容持久
     await saveSession(project, turn.session)
 
@@ -269,7 +320,7 @@ async function resolveActiveOrCreate(projectId: string): Promise<ChatSessionStat
 
   const project = requireRuntimeProject(projectId)
   const session = createChatSession(projectId)
-  sessionMap.set(session.sessionId, session)
+  cacheSession(session)
   activeSessionByProject.set(projectId, session.sessionId)
   await saveSession(project, session)
   return session
diff --git a/packages/core/src/services/project-service.ts b/packages/core/src/services/project-service.ts
index 3917c6d..7859a75 100644
--- a/packages/core/src/services/project-service.ts
+++ b/packages/core/src/services/project-service.ts
@@ -29,6 +29,7 @@ import {
   requireRuntimeProject,
   setRuntimeProject,
 } from './project-runtime'
+import { evictProjectSessions } from './agent-service'
 import { toProjectView } from './mappers'
 import type { LastProjectSummaryView, ProjectStatusView, ProjectView } from './types'
 
@@ -205,6 +206,8 @@ export async function deleteRecentProject(
   }
 
   removeRuntimeProject(projectId)
+  // 同步释放该项目驻留的会话缓存，避免历史会话累积内存泄漏
+  evictProjectSessions(projectId)
 }
 
 export async function closeProject(projectId: string): Promise<void> {
@@ -224,6 +227,8 @@ export async function closeProject(projectId: string): Promise<void> {
   })
 
   removeRuntimeProject(projectId)
+  // 关闭即释放该项目驻留的会话缓存，避免历史会话累积内存泄漏
+  evictProjectSessions(projectId)
 }
 
 export async function refreshProject(projectId: string): Promise<ProjectView> {

From 1ee44d62dc01365678a39680f1496c508097a6b4 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 20:14:54 +0800
Subject: [PATCH 28/36] =?UTF-8?q?feat(ui):=20=E4=BC=98=E5=8C=96=E8=BE=93?=
 =?UTF-8?q?=E5=85=A5=E6=8C=87=E4=BB=A4=E5=BC=B9=E5=B1=82=E4=B8=8E=E8=A6=81?=
 =?UTF-8?q?=E7=B4=A0=E6=8F=90=E5=8F=96=E8=AF=A6=E6=83=85=E5=B1=95=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../app/src/components/chat/ChapterPicker.vue |  31 +-
 .../components/chat/ExtractionFlowPanel.vue   | 269 +++++++++++-------
 .../components/chat/SceneCommandPopover.vue   |  39 ++-
 .../src/components/chat/SlashCommandMenu.vue  |  34 ++-
 .../app/src/components/layout/ChatPanel.vue   |   2 +-
 5 files changed, 234 insertions(+), 141 deletions(-)

diff --git a/packages/app/src/components/chat/ChapterPicker.vue b/packages/app/src/components/chat/ChapterPicker.vue
index f8d6324..9945a27 100644
--- a/packages/app/src/components/chat/ChapterPicker.vue
+++ b/packages/app/src/components/chat/ChapterPicker.vue
@@ -62,26 +62,27 @@ function handleCancel() {
 
 <template>
   <div
-    class="absolute bottom-full left-0 z-50 mb-1 w-72 overflow-hidden rounded-lg border border-gray-200 bg-white shadow-lg"
+    class="absolute bottom-full left-0 right-0 z-50 mb-2 max-h-[min(400px,58vh)] overflow-hidden rounded-xl border border-gray-200 bg-white shadow-lg shadow-gray-900/10 ring-1 ring-gray-900/5"
   >
     <!-- 搜索框 -->
-    <div class="border-b border-gray-100 p-2">
+    <div class="border-b border-gray-100 px-4 py-3">
+      <p class="mb-2 text-xs font-semibold text-gray-400">选择章节</p>
       <input
         v-model="searchQuery"
         type="text"
-        class="w-full rounded-md border border-gray-200 px-2 py-1.5 text-sm focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500"
+        class="w-full rounded-lg border border-gray-200 bg-gray-50 px-3 py-2 text-sm font-medium text-gray-800 placeholder:text-gray-400 focus:border-blue-500 focus:bg-white focus:outline-none focus:ring-2 focus:ring-blue-100"
         placeholder="筛选章节..."
         autofocus
       />
     </div>
 
     <!-- 章节列表 -->
-    <ul v-if="filteredChapters.length > 0" class="max-h-60 overflow-y-auto py-1">
+    <ul v-if="filteredChapters.length > 0" class="max-h-64 overflow-y-auto px-1.5 py-1.5">
       <li v-for="chapter in filteredChapters" :key="chapter.path">
         <button
           type="button"
           :class="[
-            'flex w-full items-center gap-2 px-3 py-2 text-left text-sm transition-colors',
+            'flex min-h-11 w-full items-center gap-2.5 rounded-lg px-3 py-2 text-left transition-colors',
             selectedPaths.has(chapter.path) ? 'bg-blue-50 text-blue-700' : 'text-gray-700 hover:bg-gray-50',
           ]"
           @click="toggleChapter(chapter.path)"
@@ -90,39 +91,45 @@ function handleCancel() {
             :class="[
               'flex h-4 w-4 shrink-0 items-center justify-center rounded border transition-colors',
               selectedPaths.has(chapter.path)
-                ? 'border-blue-500 bg-blue-500 text-white'
+                ? 'border-blue-400 bg-blue-500 text-white'
                 : 'border-gray-300 bg-white',
             ]"
           >
-            <svg v-if="selectedPaths.has(chapter.path)" class="h-3 w-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <svg v-if="selectedPaths.has(chapter.path)" class="h-2.5 w-2.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
               <path stroke-linecap="round" stroke-linejoin="round" stroke-width="3" d="M5 13l4 4L19 7" />
             </svg>
           </span>
-          <span class="flex-1 truncate">{{ chapter.name }}</span>
+          <span class="flex-1 truncate text-sm font-semibold leading-5">{{ chapter.name }}</span>
         </button>
       </li>
     </ul>
-    <div v-else class="px-3 py-4 text-center text-xs text-gray-400">
+    <div v-else class="px-4 py-6 text-center text-xs font-medium text-gray-400">
       {{ chapters.length === 0 ? '暂无章节' : '没有匹配的章节' }}
     </div>
 
     <!-- 底部操作 -->
-    <div class="flex items-center justify-end gap-2 border-t border-gray-100 p-2">
+    <div class="flex items-center justify-between gap-3 border-t border-gray-100 px-4 py-3">
+      <div class="flex items-center gap-2.5 text-xs font-semibold text-gray-400">
+        <span class="flex h-4 w-4 items-center justify-center rounded-full border border-gray-300 text-[10px] text-gray-500">i</span>
+        <span>{{ selectedCount > 0 ? `已选择 ${selectedCount} 个章节` : '选择要提取要素的章节' }}</span>
+      </div>
+      <div class="flex items-center gap-2">
       <button
         type="button"
-        class="rounded-md px-3 py-1.5 text-xs font-medium text-gray-600 transition-colors hover:bg-gray-100"
+        class="rounded-lg px-3 py-1.5 text-xs font-semibold text-gray-600 transition-colors hover:bg-gray-100 hover:text-gray-800"
         @click="handleCancel"
       >
         取消
       </button>
       <button
         type="button"
-        class="rounded-md bg-blue-600 px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-blue-700 disabled:opacity-50"
+        class="rounded-lg bg-blue-600 px-3 py-1.5 text-xs font-semibold text-white transition-colors hover:bg-blue-700 disabled:cursor-not-allowed disabled:bg-gray-200 disabled:text-gray-400"
         :disabled="selectedCount === 0"
         @click="handleConfirm"
       >
         确认提取{{ selectedCount > 0 ? `(${selectedCount})` : '' }}
       </button>
+      </div>
     </div>
   </div>
 </template>
diff --git a/packages/app/src/components/chat/ExtractionFlowPanel.vue b/packages/app/src/components/chat/ExtractionFlowPanel.vue
index e3a13dc..b8473c8 100644
--- a/packages/app/src/components/chat/ExtractionFlowPanel.vue
+++ b/packages/app/src/components/chat/ExtractionFlowPanel.vue
@@ -31,6 +31,7 @@ const emit = defineEmits<{
 }>()
 
 const isWriting = computed(() => props.phase === 'writing')
+const isModalOpen = ref(false)
 
 const totalCandidates = computed(() =>
   props.extractionResult ? countExtractionItems(props.extractionResult) : 0,
@@ -63,140 +64,208 @@ function getItems(result: ElementExtractionResultView, key: keyof ElementExtract
   return result[key] as ElementExtractionItemView[]
 }
 
-const progressPercent = computed(() => {
-  if (props.progressTotal === 0) return 0
-  return Math.round((props.progressCurrent / props.progressTotal) * 100)
-})
+function openModal() {
+  isModalOpen.value = true
+}
+
+function closeModal() {
+  isModalOpen.value = false
+}
+
+function handleCancel() {
+  closeModal()
+  emit('cancel')
+}
+
+function handleDismiss() {
+  closeModal()
+  emit('dismiss')
+}
 </script>
 
 <template>
-  <div class="mx-auto mb-2 max-w-3xl rounded-lg border border-gray-200 bg-gray-50">
-    <!-- 提取中 -->
-    <div v-if="phase === 'extracting'" class="p-4">
-      <div class="mb-2 flex items-center gap-2">
+  <div class="absolute bottom-24 right-4 z-40 w-72 rounded-xl border border-gray-200 bg-white p-3 shadow-lg shadow-gray-900/10">
+    <!-- 右下角状态提示 -->
+    <div v-if="phase === 'extracting'">
+      <div class="flex items-center gap-2">
         <svg class="h-4 w-4 animate-spin text-blue-500" fill="none" viewBox="0 0 24 24">
           <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" />
           <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
         </svg>
-        <p class="text-sm font-medium text-gray-700">
-          正在提取要素（{{ progressCurrent }}/{{ progressTotal }}）
+        <p class="min-w-0 truncate text-sm font-medium text-gray-700">
+          正在提取要素
+          <span class="text-gray-400">[{{ progressCurrent }}/{{ progressTotal }}]</span>
+          {{ progressChapterName }}
         </p>
       </div>
-      <p class="mb-2 truncate text-xs text-gray-500">{{ progressChapterName }}</p>
-      <div class="h-1.5 w-full overflow-hidden rounded-full bg-gray-200">
-        <div
-          class="h-full bg-blue-500 transition-all duration-300"
-          :style="{ width: progressPercent + '%' }"
-        />
-      </div>
     </div>
 
-    <!-- 预览候选 -->
-    <div v-else-if="phase === 'preview' || phase === 'writing'" class="p-4">
-      <div class="mb-3 flex items-center justify-between">
-        <p class="text-sm font-medium text-gray-700">
-          已提取 {{ totalCandidates }} 个候选要素
-        </p>
-        <span v-if="phase === 'writing'" class="text-xs text-gray-400">写入中...</span>
-      </div>
-
-      <div v-if="extractionResult" class="space-y-2">
-        <div v-for="bucket in BUCKETS" :key="bucket.key">
-          <button
-            v-if="getItems(extractionResult, bucket.key).length > 0"
-            type="button"
-            class="flex w-full items-center gap-1.5 py-1 text-left text-xs font-medium text-gray-600"
-            @click="toggleGroup(bucket.key)"
-          >
-            <span class="shrink-0">{{ bucket.icon }}</span>
-            <span>{{ bucket.label }}</span>
-            <span class="text-gray-400">({{ getItems(extractionResult, bucket.key).length }})</span>
-            <svg
-              class="ml-auto h-3 w-3 text-gray-400 transition-transform"
-              :class="{ 'rotate-180': expandedGroups.has(bucket.key) }"
-              fill="none" stroke="currentColor" viewBox="0 0 24 24"
-            >
-              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7" />
-            </svg>
-          </button>
-          <ul
-            v-if="expandedGroups.has(bucket.key) && getItems(extractionResult, bucket.key).length > 0"
-            class="ml-5 space-y-1 border-l border-gray-200 pl-3"
-          >
-            <li
-              v-for="item in getItems(extractionResult, bucket.key)"
-              :key="item.name"
-              class="py-0.5"
-            >
-              <p class="text-xs font-medium text-gray-700">{{ item.name }}</p>
-              <p v-if="item.summary" class="truncate text-xs text-gray-500">{{ item.summary }}</p>
-            </li>
-          </ul>
+    <div v-else-if="phase === 'preview' || phase === 'writing'">
+      <div class="flex items-start gap-2">
+        <svg class="mt-0.5 h-4 w-4 text-green-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7" />
+        </svg>
+        <div class="min-w-0 flex-1">
+          <p class="text-sm font-medium text-gray-700">已提取 {{ totalCandidates }} 个候选要素</p>
+          <p class="mt-0.5 text-xs text-gray-500">{{ phase === 'writing' ? '正在写入 elements...' : '点击查看详情后确认写入' }}</p>
         </div>
       </div>
-
-      <div v-if="phase === 'preview'" class="mt-3 flex items-center justify-end gap-2">
-        <button
-          type="button"
-          class="rounded-md px-3 py-1.5 text-xs font-medium text-gray-600 transition-colors hover:bg-gray-200"
-          @click="emit('cancel')"
-        >
-          取消
-        </button>
+      <div class="mt-3 flex justify-end">
         <button
           type="button"
-          class="rounded-md bg-green-600 px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-green-700"
-          @click="emit('confirm')"
+          class="rounded-md bg-blue-600 px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-blue-700"
+          @click="openModal"
         >
-          确认写入
+          查看详情
         </button>
       </div>
     </div>
 
-    <!-- 写入完成 -->
-    <div v-else-if="phase === 'done' && writeResult" class="p-4">
-      <div class="mb-2 flex items-center gap-2">
-        <svg class="h-4 w-4 text-green-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+    <div v-else-if="phase === 'done' && writeResult">
+      <div class="flex items-start gap-2">
+        <svg class="mt-0.5 h-4 w-4 text-green-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
           <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7" />
         </svg>
-        <p class="text-sm font-medium text-gray-700">要素写入完成</p>
-      </div>
-      <div class="ml-6 space-y-0.5 text-xs text-gray-500">
-        <p>✅ 新增 {{ writeResult.created.length }} 个</p>
-        <p>🔄 更新 {{ writeResult.updated.length }} 个</p>
-        <p v-if="writeResult.skipped.length > 0">⏭️ 跳过 {{ writeResult.skipped.length }} 个（无变化）</p>
-        <p v-if="writeResult.staleIndex" class="mt-1 text-amber-600">⚠️ RAG 索引已标记为过期，可在设置中重建</p>
+        <div class="min-w-0 flex-1">
+          <p class="text-sm font-medium text-gray-700">要素写入完成</p>
+          <p class="mt-0.5 text-xs text-gray-500">新增 {{ writeResult.created.length }} 个，更新 {{ writeResult.updated.length }} 个</p>
+        </div>
       </div>
-      <div class="mt-3 flex justify-end">
-        <button
-          type="button"
-          class="rounded-md px-3 py-1.5 text-xs font-medium text-gray-600 transition-colors hover:bg-gray-200"
-          @click="emit('dismiss')"
-        >
+      <div class="mt-3 flex justify-end gap-2">
+        <button type="button" class="rounded-md px-3 py-1.5 text-xs font-medium text-gray-600 hover:bg-gray-100" @click="openModal">
+          查看
+        </button>
+        <button type="button" class="rounded-md bg-gray-900 px-3 py-1.5 text-xs font-medium text-white hover:bg-gray-800" @click="handleDismiss">
           关闭
         </button>
       </div>
     </div>
 
-    <!-- 错误 -->
-    <div v-else-if="phase === 'error'" class="p-4">
-      <div class="mb-2 flex items-center gap-2">
-        <svg class="h-4 w-4 text-red-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+    <div v-else-if="phase === 'error'">
+      <div class="flex items-start gap-2">
+        <svg class="mt-0.5 h-4 w-4 text-red-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
           <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01M5.07 19h13.86c1.54 0 2.5-1.67 1.73-3L13.73 4a2 2 0 00-3.46 0L3.34 16c-.77 1.33.19 3 1.73 3z" />
         </svg>
-        <p class="text-sm font-medium text-red-600">提取失败</p>
+        <div class="min-w-0 flex-1">
+          <p class="text-sm font-medium text-red-600">提取失败</p>
+          <p class="mt-0.5 truncate text-xs text-gray-500">{{ errorMessage }}</p>
+        </div>
       </div>
-      <p class="ml-6 text-xs text-gray-500">{{ errorMessage }}</p>
-      <p class="ml-6 mt-1 text-xs text-gray-400">请检查设置页的 LLM 配置是否正确。</p>
-      <div class="mt-3 flex justify-end">
-        <button
-          type="button"
-          class="rounded-md px-3 py-1.5 text-xs font-medium text-gray-600 transition-colors hover:bg-gray-200"
-          @click="emit('dismiss')"
-        >
+      <div class="mt-3 flex justify-end gap-2">
+        <button type="button" class="rounded-md px-3 py-1.5 text-xs font-medium text-gray-600 hover:bg-gray-100" @click="openModal">
+          查看
+        </button>
+        <button type="button" class="rounded-md bg-gray-900 px-3 py-1.5 text-xs font-medium text-white hover:bg-gray-800" @click="handleDismiss">
           关闭
         </button>
       </div>
     </div>
+
+    <Teleport to="body">
+      <div
+        v-if="isModalOpen"
+        class="fixed inset-0 z-[100] flex items-center justify-center bg-gray-900/40 px-4 py-6"
+        @click.self="closeModal"
+      >
+        <div class="flex max-h-[86vh] w-full max-w-2xl flex-col overflow-hidden rounded-xl border border-gray-200 bg-white shadow-2xl">
+          <div class="flex items-center justify-between border-b border-gray-100 px-5 py-4">
+            <div>
+              <p class="text-base font-semibold text-gray-800">
+                {{ phase === 'done' ? '要素写入结果' : phase === 'error' ? '提取失败' : '要素提取详情' }}
+              </p>
+              <p v-if="phase === 'preview' || phase === 'writing'" class="mt-0.5 text-xs text-gray-500">
+                共 {{ totalCandidates }} 个候选要素
+              </p>
+            </div>
+            <button
+              type="button"
+              class="rounded-md p-1.5 text-gray-400 transition-colors hover:bg-gray-100 hover:text-gray-600"
+              @click="closeModal"
+            >
+              <svg class="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+              </svg>
+            </button>
+          </div>
+
+          <div class="min-h-0 flex-1 overflow-y-auto px-5 py-4">
+            <div v-if="(phase === 'preview' || phase === 'writing') && extractionResult" class="space-y-3">
+              <div v-for="bucket in BUCKETS" :key="bucket.key">
+                <button
+                  v-if="getItems(extractionResult, bucket.key).length > 0"
+                  type="button"
+                  class="flex w-full items-center gap-1.5 py-1.5 text-left text-sm font-medium text-gray-600"
+                  @click="toggleGroup(bucket.key)"
+                >
+                  <span class="shrink-0">{{ bucket.icon }}</span>
+                  <span>{{ bucket.label }}</span>
+                  <span class="text-gray-400">({{ getItems(extractionResult, bucket.key).length }})</span>
+                  <svg
+                    class="ml-auto h-3.5 w-3.5 text-gray-400 transition-transform"
+                    :class="{ 'rotate-180': expandedGroups.has(bucket.key) }"
+                    fill="none" stroke="currentColor" viewBox="0 0 24 24"
+                  >
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7" />
+                  </svg>
+                </button>
+                <ul
+                  v-if="expandedGroups.has(bucket.key) && getItems(extractionResult, bucket.key).length > 0"
+                  class="ml-5 space-y-2 border-l border-gray-200 pl-3"
+                >
+                  <li v-for="item in getItems(extractionResult, bucket.key)" :key="item.name" class="py-0.5">
+                    <p class="text-sm font-medium text-gray-700">{{ item.name }}</p>
+                    <p v-if="item.summary" class="text-xs leading-5 text-gray-500">{{ item.summary }}</p>
+                  </li>
+                </ul>
+              </div>
+            </div>
+
+            <div v-else-if="phase === 'done' && writeResult" class="space-y-1 text-sm text-gray-600">
+              <p>新增 {{ writeResult.created.length }} 个</p>
+              <p>更新 {{ writeResult.updated.length }} 个</p>
+              <p v-if="writeResult.skipped.length > 0">跳过 {{ writeResult.skipped.length }} 个（无变化）</p>
+              <p v-if="writeResult.staleIndex" class="mt-2 text-amber-600">RAG 索引已标记为过期，可在设置中重建。</p>
+            </div>
+
+            <div v-else-if="phase === 'error'" class="text-sm text-gray-600">
+              <p>{{ errorMessage }}</p>
+              <p class="mt-2 text-xs text-gray-400">请检查设置页的 LLM 配置是否正确。</p>
+            </div>
+          </div>
+
+          <div
+            v-if="phase === 'preview' || phase === 'writing'"
+            class="flex items-center justify-end gap-2 border-t border-gray-100 px-5 py-4"
+          >
+            <button
+              type="button"
+              class="rounded-md px-3 py-1.5 text-xs font-medium text-gray-600 transition-colors hover:bg-gray-100"
+              :disabled="isWriting"
+              @click="handleCancel"
+            >
+              取消
+            </button>
+            <button
+              type="button"
+              class="rounded-md bg-green-600 px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-green-700 disabled:cursor-not-allowed disabled:opacity-60"
+              :disabled="isWriting"
+              @click="emit('confirm')"
+            >
+              {{ isWriting ? '写入中...' : '确认写入' }}
+            </button>
+          </div>
+
+          <div v-else class="flex items-center justify-end border-t border-gray-100 px-5 py-4">
+            <button
+              type="button"
+              class="rounded-md bg-gray-900 px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-gray-800"
+              @click="handleDismiss"
+            >
+              关闭
+            </button>
+          </div>
+        </div>
+      </div>
+    </Teleport>
   </div>
 </template>
diff --git a/packages/app/src/components/chat/SceneCommandPopover.vue b/packages/app/src/components/chat/SceneCommandPopover.vue
index 6746465..ce3cac5 100644
--- a/packages/app/src/components/chat/SceneCommandPopover.vue
+++ b/packages/app/src/components/chat/SceneCommandPopover.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, watch } from 'vue'
+import { computed, ref, watch } from 'vue'
 import type { ProjectFileNodeView } from '@novai/core/services/types'
 
 /**
@@ -35,13 +35,13 @@ const filteredScenes = computed(() => {
 })
 
 /** 当前高亮项索引（仅键盘导航用） */
-let highlightIndex = 0
+const highlightIndex = ref(0)
 
 /** query 或列表变化时重置高亮到第一项 */
 watch(
   () => [props.query, props.scenes.length] as const,
   () => {
-    highlightIndex = 0
+    highlightIndex.value = 0
   },
 )
 
@@ -49,16 +49,16 @@ defineExpose({
   /** 键盘 ↑：高亮上移（循环） */
   moveUp() {
     if (filteredScenes.value.length === 0) return
-    highlightIndex = (highlightIndex - 1 + filteredScenes.value.length) % filteredScenes.value.length
+    highlightIndex.value = (highlightIndex.value - 1 + filteredScenes.value.length) % filteredScenes.value.length
   },
   /** 键盘 ↓：高亮下移（循环） */
   moveDown() {
     if (filteredScenes.value.length === 0) return
-    highlightIndex = (highlightIndex + 1) % filteredScenes.value.length
+    highlightIndex.value = (highlightIndex.value + 1) % filteredScenes.value.length
   },
   /** 键盘 Enter：选中当前高亮项 */
   confirm() {
-    const scene = filteredScenes.value[highlightIndex]
+    const scene = filteredScenes.value[highlightIndex.value]
     if (scene) emit('select', scene.path)
   },
 })
@@ -66,34 +66,47 @@ defineExpose({
 function displayName(name: string): string {
   return name.replace(/\.md$/i, '')
 }
+
+function displayDirectory(path: string): string {
+  const parts = path.split('/')
+  parts.pop()
+  return parts.length > 0 ? `${parts.join('/')}/` : ''
+}
 </script>
 
 <template>
   <div
-    class="absolute bottom-full left-0 z-50 mb-1 w-64 overflow-hidden rounded-lg border border-gray-200 bg-white shadow-lg"
+    class="absolute bottom-full left-0 right-0 z-50 mb-2 max-h-[min(360px,56vh)] overflow-hidden rounded-xl border border-gray-200 bg-white shadow-lg shadow-gray-900/10 ring-1 ring-gray-900/5"
   >
-    <ul v-if="filteredScenes.length > 0" class="max-h-60 overflow-y-auto py-1">
+    <ul v-if="filteredScenes.length > 0" class="max-h-72 overflow-y-auto px-1.5 py-1.5">
       <li v-for="(scene, index) in filteredScenes" :key="scene.path">
         <button
           type="button"
           :class="[
-            'flex w-full items-center gap-2 px-3 py-2 text-left text-sm transition-colors',
+            'flex min-h-11 w-full items-center gap-2.5 rounded-lg px-3 py-2 text-left transition-colors',
             index === highlightIndex ? 'bg-blue-50 text-blue-700' : 'text-gray-700 hover:bg-gray-50',
           ]"
           @click="emit('select', scene.path)"
         >
-          <span class="shrink-0">🎬</span>
-          <span class="flex-1 truncate">{{ displayName(scene.name) }}</span>
+          <span class="flex h-6 w-6 shrink-0 items-center justify-center rounded-md bg-blue-50 text-xs text-blue-400">M↓</span>
+          <span class="min-w-0 flex-1">
+            <span class="align-baseline text-sm font-semibold leading-5">{{ displayName(scene.name) }}</span>
+            <span class="ml-2 align-baseline text-xs font-medium text-gray-400">{{ displayDirectory(scene.path) }}</span>
+          </span>
           <span
             v-if="scene.path === activeScenePath"
-            class="shrink-0 text-xs text-green-500"
+            class="shrink-0 text-xs text-emerald-400"
             title="当前激活"
           >●</span>
         </button>
       </li>
     </ul>
-    <div v-else class="px-3 py-4 text-center text-xs text-gray-400">
+    <div v-else class="px-4 py-6 text-center text-xs font-medium text-gray-400">
       {{ query ? '没有匹配的场景' : '暂无场景提示词' }}
     </div>
+    <div class="flex items-center gap-2.5 border-t border-gray-100 px-4 py-3 text-xs font-semibold text-gray-400">
+      <span class="flex h-4 w-4 items-center justify-center rounded-full border border-gray-300 text-[10px] text-gray-500">i</span>
+      <span>输入内容以搜索场景</span>
+    </div>
   </div>
 </template>
diff --git a/packages/app/src/components/chat/SlashCommandMenu.vue b/packages/app/src/components/chat/SlashCommandMenu.vue
index abee991..8f47c48 100644
--- a/packages/app/src/components/chat/SlashCommandMenu.vue
+++ b/packages/app/src/components/chat/SlashCommandMenu.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, watch } from 'vue'
+import { computed, ref, watch } from 'vue'
 import { SLASH_COMMANDS, type SlashCommandId } from '../../constants/slash-commands'
 
 /**
@@ -33,26 +33,26 @@ const filteredCommands = computed(() => {
 })
 
 /** 当前高亮项索引（键盘导航用） */
-let highlightIndex = 0
+const highlightIndex = ref(0)
 
 watch(
   () => props.query,
   () => {
-    highlightIndex = 0
+    highlightIndex.value = 0
   },
 )
 
 defineExpose({
   moveUp() {
     if (filteredCommands.value.length === 0) return
-    highlightIndex = (highlightIndex - 1 + filteredCommands.value.length) % filteredCommands.value.length
+    highlightIndex.value = (highlightIndex.value - 1 + filteredCommands.value.length) % filteredCommands.value.length
   },
   moveDown() {
     if (filteredCommands.value.length === 0) return
-    highlightIndex = (highlightIndex + 1) % filteredCommands.value.length
+    highlightIndex.value = (highlightIndex.value + 1) % filteredCommands.value.length
   },
   confirm() {
-    const command = filteredCommands.value[highlightIndex]
+    const command = filteredCommands.value[highlightIndex.value]
     if (command) emit('select', command.id)
   },
 })
@@ -60,31 +60,35 @@ defineExpose({
 
 <template>
   <div
-    class="absolute bottom-full left-0 z-50 mb-1 w-72 overflow-hidden rounded-lg border border-gray-200 bg-white shadow-lg"
+    class="absolute bottom-full left-0 right-0 z-50 mb-2 max-h-[min(340px,56vh)] overflow-hidden rounded-xl border border-gray-200 bg-white shadow-lg shadow-gray-900/10 ring-1 ring-gray-900/5"
   >
-    <div class="border-b border-gray-100 px-3 py-1.5">
-      <p class="text-xs font-medium uppercase tracking-wide text-gray-400">命令</p>
+    <div class="px-4 pb-1.5 pt-3">
+      <p class="text-xs font-semibold text-gray-400">命令</p>
     </div>
-    <ul v-if="filteredCommands.length > 0" class="max-h-60 overflow-y-auto py-1">
+    <ul v-if="filteredCommands.length > 0" class="max-h-64 overflow-y-auto px-1.5 pb-1.5">
       <li v-for="(command, index) in filteredCommands" :key="command.id">
         <button
           type="button"
           :class="[
-            'flex w-full items-start gap-2 px-3 py-2 text-left text-sm transition-colors',
+            'flex min-h-11 w-full items-center gap-2.5 rounded-lg px-3 py-2 text-left transition-colors',
             index === highlightIndex ? 'bg-blue-50 text-blue-700' : 'text-gray-700 hover:bg-gray-50',
           ]"
           @click="emit('select', command.id)"
         >
-          <span class="mt-0.5 shrink-0">{{ command.icon }}</span>
+          <span class="flex h-6 w-6 shrink-0 items-center justify-center rounded-md bg-blue-50 text-sm">{{ command.icon }}</span>
           <div class="min-w-0 flex-1">
-            <p class="font-medium">{{ command.label }}</p>
-            <p class="truncate text-xs text-gray-400">{{ command.description }}</p>
+            <p class="text-sm font-semibold leading-5">{{ command.label }}</p>
+            <p class="truncate text-xs font-medium text-gray-400">{{ command.description }}</p>
           </div>
         </button>
       </li>
     </ul>
-    <div v-else class="px-3 py-4 text-center text-xs text-gray-400">
+    <div v-else class="px-4 py-6 text-center text-xs font-medium text-gray-400">
       没有匹配的命令
     </div>
+    <div class="flex items-center gap-2.5 border-t border-gray-100 px-4 py-3 text-xs font-semibold text-gray-400">
+      <span class="flex h-4 w-4 items-center justify-center rounded-full border border-gray-300 text-[10px] text-gray-500">i</span>
+      <span>输入内容以搜索命令</span>
+    </div>
   </div>
 </template>
diff --git a/packages/app/src/components/layout/ChatPanel.vue b/packages/app/src/components/layout/ChatPanel.vue
index b7f1551..dba7764 100644
--- a/packages/app/src/components/layout/ChatPanel.vue
+++ b/packages/app/src/components/layout/ChatPanel.vue
@@ -317,7 +317,7 @@ async function handleExtractionConfirm() {
 </script>
 
 <template>
-  <section class="flex min-w-0 flex-1 flex-col">
+  <section class="relative flex min-w-0 flex-1 flex-col">
     <!-- 头部 -->
     <header class="flex items-center justify-between border-b border-gray-200 px-4 py-3">
       <div class="flex items-center gap-2">

From 91ac1cedb972ebf902eb8440216642607d663564 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 20:23:12 +0800
Subject: [PATCH 29/36] =?UTF-8?q?feat(project):=20RAG=20=E5=8F=AC=E5=9B=9E?=
 =?UTF-8?q?=E9=93=BE=E8=B7=AF=E5=8D=87=E7=BA=A7=E4=B8=BA=20Orama=20?=
 =?UTF-8?q?=E5=90=91=E9=87=8F=E6=A3=80=E7=B4=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增 @orama/orama 依赖（core 包运行时依赖）
- 新增 orama-index.ts：维护每个 projectId 一个内存 Orama 实例的注册表，
  buildOramaIndex/getOramaIndex(懒构建)/dropOramaIndex/searchOrama，
  向量维度运行时确定，维度不匹配时降级为空召回
- search.ts 改写：searchRagCandidates 改走 searchOrama，删除本地
  cosineSimilarity 全量遍历与 matchesFilters 过滤逻辑
- indexer.ts 接入：buildProjectIndex 在 upsert 后基于 IndexedDB 全量
  当前状态重建内存 Orama（保证增量/全量一致）；markProjectIndexStale
  不 drop 内存索引（stale 仅改 meta 不改数据，drop 会触发无谓懒重建）
- 过滤策略：type/lastUpdatedChapter 交 Orama where 精确过滤；tags 因中文
  tokenizer 分词不稳定改为 Orama 多召回 + 本地精确兜底，避免 topK 截断
- 新增 orama-index.test.ts（10 例）与 search.test.ts（5 例）覆盖召回排序、
  topK、三类过滤、rebuild 不泄漏、维度降级、drop 清空
---
 packages/core/package.json                    |   3 +
 packages/core/src/core/rag/indexer.ts         |   8 +
 .../core/src/core/rag/orama-index.test.ts     | 186 ++++++++++++
 packages/core/src/core/rag/orama-index.ts     | 271 ++++++++++++++++++
 packages/core/src/core/rag/search.test.ts     | 155 ++++++++++
 packages/core/src/core/rag/search.ts          |  82 +-----
 pnpm-lock.yaml                                |  10 +
 7 files changed, 638 insertions(+), 77 deletions(-)
 create mode 100644 packages/core/src/core/rag/orama-index.test.ts
 create mode 100644 packages/core/src/core/rag/orama-index.ts
 create mode 100644 packages/core/src/core/rag/search.test.ts

diff --git a/packages/core/package.json b/packages/core/package.json
index d631770..e6df052 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -23,5 +23,8 @@
   "devDependencies": {
     "typescript": "^6.0.2",
     "vite": "^6.2.0"
+  },
+  "dependencies": {
+    "@orama/orama": "^3.1.18"
   }
 }
diff --git a/packages/core/src/core/rag/indexer.ts b/packages/core/src/core/rag/indexer.ts
index ef8156a..003b300 100644
--- a/packages/core/src/core/rag/indexer.ts
+++ b/packages/core/src/core/rag/indexer.ts
@@ -6,6 +6,7 @@ import { hashContent } from '../util/hash'
 import type { ProjectSnapshot, TreeNode } from '../../types/project'
 import type { IndexBuildRequest, IndexBuildResult, ProjectIndexMeta } from '../../types/rag'
 
+import { buildOramaIndex, dropOramaIndex } from './orama-index'
 import { createRagIndexStore } from './index-store'
 import { buildRetrievalText } from './retrieval-text'
 
@@ -98,6 +99,13 @@ export async function buildProjectIndex(
 
     await store.upsertDocuments(documents)
 
+    // 内存 Orama 索引必须与 IndexedDB 的全量当前状态保持一致：
+    // 增量更新时不 clear，IndexedDB 里是「旧 + 本次 upsert」的全集；
+    // 全量重建时已 clear，IndexedDB 里就是本次 documents 全集。
+    // 因此统一以 upsert 后的 IndexedDB 全量文档重建，避免增量场景下 Orama 丢失其他文档。
+    const allDocuments = await store.listProjectDocuments(project.id)
+    await buildOramaIndex(project.id, allDocuments)
+
     const meta: ProjectIndexMeta = {
       projectId: project.id,
       status: documents.length > 0 ? 'ready' : 'empty',
diff --git a/packages/core/src/core/rag/orama-index.test.ts b/packages/core/src/core/rag/orama-index.test.ts
new file mode 100644
index 0000000..3a12183
--- /dev/null
+++ b/packages/core/src/core/rag/orama-index.test.ts
@@ -0,0 +1,186 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+// 懒构建路径会读取 IndexedDB，node 测试环境没有 indexedDB。
+// mock 成本：让 listProjectDocuments 返回空，懒构建读到空 → getOramaIndex 返回 null → 空召回。
+vi.mock('./index-store', () => ({
+  createRagIndexStore: () => ({
+    listProjectDocuments: async () => [],
+  }),
+}))
+
+import { buildOramaIndex, dropOramaIndex, searchOrama } from './orama-index'
+
+import type { IndexedElementDocument, RetrievalQuery } from '../../types/rag'
+
+const PROJECT_ID = 'proj-test'
+
+afterEach(() => {
+  // 注册表是模块级单例，每个用例后清空避免互相污染。
+  dropOramaIndex(PROJECT_ID)
+})
+
+function makeDocument(overrides: Partial<IndexedElementDocument> & Pick<IndexedElementDocument, 'id' | 'name' | 'vector'>): IndexedElementDocument {
+  return {
+    projectId: PROJECT_ID,
+    sourcePath: `elements/characters/${overrides.id}.md`,
+    type: 'character',
+    summary: overrides.name,
+    retrievalText: overrides.name,
+    tags: [],
+    lastUpdatedChapter: '',
+    relatedChapters: [],
+    sourceModifiedAt: '',
+    indexedAt: '',
+    contentHash: '',
+    embeddingProvider: '',
+    embeddingModel: '',
+    embeddingDim: overrides.vector.length,
+    embeddingTextVersion: 1,
+    ...overrides,
+  } as IndexedElementDocument
+}
+
+function makeQuery(vector: number[], overrides?: Partial<RetrievalQuery>): RetrievalQuery {
+  return {
+    projectId: PROJECT_ID,
+    query: '测试查询',
+    topK: 10,
+    ...overrides,
+  }
+}
+
+describe('orama-index buildOramaIndex + searchOrama', () => {
+  it('returns empty result when no index has been built', async () => {
+    // 未构建任何索引（registry 为空），不应抛错，直接空召回。
+    const result = await searchOrama(PROJECT_ID, makeQuery([1, 0, 0]), [1, 0, 0])
+
+    expect(result.candidates).toEqual([])
+    expect(result.total).toBe(0)
+  })
+
+  it('recalls documents ranked by vector similarity', async () => {
+    // 三个文档向量方向不同，查询向量与第二个最接近。
+    await buildOramaIndex(PROJECT_ID, [
+      makeDocument({ id: 'a', name: '远离', vector: [0, 0, 1] }),
+      makeDocument({ id: 'b', name: '命中', vector: [1, 0, 0] }),
+      makeDocument({ id: 'c', name: '中间', vector: [0, 1, 0] }),
+    ])
+
+    const result = await searchOrama(PROJECT_ID, makeQuery([1, 0, 0], { topK: 10 }), [1, 0, 0])
+
+    expect(result.total).toBe(3)
+    expect(result.candidates[0].id).toBe('b')
+    expect(result.candidates[0].score).toBeGreaterThan(0)
+  })
+
+  it('respects topK limit', async () => {
+    await buildOramaIndex(PROJECT_ID, [
+      makeDocument({ id: 'a', name: '一', vector: [1, 0, 0] }),
+      makeDocument({ id: 'b', name: '二', vector: [0.9, 0.1, 0] }),
+      makeDocument({ id: 'c', name: '三', vector: [0, 1, 0] }),
+    ])
+
+    const result = await searchOrama(PROJECT_ID, makeQuery([1, 0, 0], { topK: 2 }), [1, 0, 0])
+
+    expect(result.candidates).toHaveLength(2)
+  })
+
+  it('filters by element type', async () => {
+    await buildOramaIndex(PROJECT_ID, [
+      makeDocument({ id: 'char', name: '人物', vector: [1, 0, 0], type: 'character' }),
+      makeDocument({ id: 'loc', name: '地点', vector: [1, 0, 0], type: 'location', sourcePath: 'elements/locations/loc.md' }),
+    ])
+
+    const result = await searchOrama(
+      PROJECT_ID,
+      makeQuery([1, 0, 0], { filters: { type: ['location'] } }),
+      [1, 0, 0],
+    )
+
+    expect(result.candidates).toHaveLength(1)
+    expect(result.candidates[0].id).toBe('loc')
+  })
+
+  it('filters by lastUpdatedChapter', async () => {
+    await buildOramaIndex(PROJECT_ID, [
+      makeDocument({ id: 'a', name: '一', vector: [1, 0, 0], lastUpdatedChapter: '第001章' }),
+      makeDocument({ id: 'b', name: '二', vector: [1, 0, 0], lastUpdatedChapter: '第002章' }),
+    ])
+
+    const result = await searchOrama(
+      PROJECT_ID,
+      makeQuery([1, 0, 0], { filters: { lastUpdatedChapter: '第002章' } }),
+      [1, 0, 0],
+    )
+
+    expect(result.candidates).toHaveLength(1)
+    expect(result.candidates[0].id).toBe('b')
+  })
+
+  it('filters by tags (matches if any document tag overlaps)', async () => {
+    await buildOramaIndex(PROJECT_ID, [
+      makeDocument({ id: 'a', name: '一', vector: [1, 0, 0], tags: ['主角', '剑修'] }),
+      makeDocument({ id: 'b', name: '二', vector: [1, 0, 0], tags: ['反派'] }),
+    ])
+
+    const result = await searchOrama(
+      PROJECT_ID,
+      makeQuery([1, 0, 0], { filters: { tags: ['主角'] } }),
+      [1, 0, 0],
+    )
+
+    expect(result.candidates).toHaveLength(1)
+    expect(result.candidates[0].id).toBe('a')
+  })
+
+  it('rebuild does not leak old documents', async () => {
+    await buildOramaIndex(PROJECT_ID, [
+      makeDocument({ id: 'old', name: '旧', vector: [1, 0, 0] }),
+    ])
+
+    // 用全新的文档集合重建，旧文档不应残留。
+    await buildOramaIndex(PROJECT_ID, [
+      makeDocument({ id: 'new', name: '新', vector: [1, 0, 0] }),
+    ])
+
+    const result = await searchOrama(PROJECT_ID, makeQuery([1, 0, 0]), [1, 0, 0])
+
+    expect(result.total).toBe(1)
+    expect(result.candidates[0].id).toBe('new')
+  })
+
+  it('building with empty documents drops the index and yields empty recall', async () => {
+    await buildOramaIndex(PROJECT_ID, [
+      makeDocument({ id: 'a', name: '一', vector: [1, 0, 0] }),
+    ])
+
+    await buildOramaIndex(PROJECT_ID, [])
+
+    const result = await searchOrama(PROJECT_ID, makeQuery([1, 0, 0]), [1, 0, 0])
+
+    expect(result.candidates).toEqual([])
+  })
+
+  it('returns empty recall when query vector dimension mismatches index', async () => {
+    await buildOramaIndex(PROJECT_ID, [
+      makeDocument({ id: 'a', name: '一', vector: [1, 0, 0] }),
+    ])
+
+    // 索引是 3 维，查询给 2 维：维度不匹配，降级为空召回而不是抛错。
+    const result = await searchOrama(PROJECT_ID, makeQuery([1, 0], { topK: 10 }), [1, 0])
+
+    expect(result.candidates).toEqual([])
+  })
+
+  it('dropOramaIndex clears an existing index', async () => {
+    await buildOramaIndex(PROJECT_ID, [
+      makeDocument({ id: 'a', name: '一', vector: [1, 0, 0] }),
+    ])
+
+    dropOramaIndex(PROJECT_ID)
+
+    const result = await searchOrama(PROJECT_ID, makeQuery([1, 0, 0]), [1, 0, 0])
+
+    expect(result.candidates).toEqual([])
+  })
+})
diff --git a/packages/core/src/core/rag/orama-index.ts b/packages/core/src/core/rag/orama-index.ts
new file mode 100644
index 0000000..ee9501e
--- /dev/null
+++ b/packages/core/src/core/rag/orama-index.ts
@@ -0,0 +1,271 @@
+import {
+  create,
+  insertMultiple,
+  MODE_VECTOR_SEARCH,
+  searchVector,
+  type AnyOrama,
+  type AnySchema,
+} from '@orama/orama'
+
+import type {
+  IndexedElementDocument,
+  RetrievalCandidate,
+  RetrievalQuery,
+  RetrievalResult,
+} from '../../types/rag'
+
+import { createRagIndexStore } from './index-store'
+
+/**
+ * Orama 内存索引注册表。
+ *
+ * 每个 projectId 对应一个常驻内存的 Orama 实例，负责该项目的向量相似度召回。
+ * IndexedDB 仍然是跨会话的真实持久层；Orama 实例只是「当前会话内的可重建缓存」，
+ * 在索引构建后填充，查询时零成本复用。
+ *
+ * 设计依据见 docs/architecture/向量索引与重排序设计.md「四、Orama 召回策略」。
+ */
+
+const VECTOR_PROPERTY = 'embedding'
+
+type OramaRegistryEntry = {
+  /** Orama 实例。schema 在构建时根据首条可用向量维度动态确定。 */
+  db: AnyOrama
+  documentCount: number
+  /** 记录 build 时的向量维度，用于校验后续查询向量是否兼容。 */
+  vectorDimension: number
+}
+
+const registry = new Map<string, OramaRegistryEntry>()
+
+/**
+ * 用一批已落盘的要素文档构建（或重建）某个项目的内存 Orama 索引。
+ *
+ * 传入的 documents 必须已包含向量（来自 Embedding 模型）。空列表会清除旧实例，
+ * 让该项目的后续查询走空召回，而不是带着过期数据继续返回。
+ */
+export async function buildOramaIndex(
+  projectId: string,
+  documents: IndexedElementDocument[],
+): Promise<void> {
+  // 重建语义：先丢弃旧实例，避免旧文档残留进新索引。
+  registry.delete(projectId)
+
+  if (documents.length === 0) {
+    return
+  }
+
+  const vectorDimension = documents[0]?.vector.length ?? 0
+  if (vectorDimension === 0) {
+    // 没有可用向量说明数据不完整，不要建立空壳索引。
+    return
+  }
+
+  const db = await create({
+    schema: {
+      id: 'string',
+      sourcePath: 'string',
+      type: 'string',
+      name: 'string',
+      summary: 'string',
+      retrievalText: 'string',
+      tags: 'string[]',
+      lastUpdatedChapter: 'string',
+      relatedChapters: 'string[]',
+      [VECTOR_PROPERTY]: `vector[${vectorDimension}]`,
+    } as AnySchema,
+  })
+
+  await insertMultiple(
+    db,
+    documents.map((document) => ({
+      id: document.id,
+      sourcePath: document.sourcePath,
+      type: document.type,
+      name: document.name,
+      summary: document.summary,
+      retrievalText: document.retrievalText,
+      tags: document.tags,
+      lastUpdatedChapter: document.lastUpdatedChapter,
+      relatedChapters: document.relatedChapters,
+      [VECTOR_PROPERTY]: document.vector,
+    })),
+  )
+
+  registry.set(projectId, {
+    db,
+    documentCount: documents.length,
+    vectorDimension,
+  })
+}
+
+/**
+ * 取得某个项目的内存 Orama 实例；不存在时从 IndexedDB 懒构建。
+ *
+ * 懒构建用于「会话首次查询、但本次尚未触发显式 build」的情况——例如用户直接
+ * 打开一个已有旧索引的项目就开始对话。读到 IndexedDB 文档即灌入 Orama。
+ */
+export async function getOramaIndex(projectId: string): Promise<AnyOrama | null> {
+  const entry = registry.get(projectId)
+  if (entry) {
+    return entry.db
+  }
+
+  // 内存里没有，尝试从 IndexedDB 重建。空项目直接返回 null，调用方据此走空召回。
+  const store = createRagIndexStore()
+  const documents = await store.listProjectDocuments(projectId)
+
+  if (documents.length === 0) {
+    return null
+  }
+
+  await buildOramaIndex(projectId, documents)
+  return registry.get(projectId)?.db ?? null
+}
+
+/**
+ * 清除某个项目的内存 Orama 实例。
+ *
+ * 用于全量重建（旧索引不可信）与项目关闭/删除（释放内存）。
+ * 不会删除 IndexedDB 中的持久数据。
+ */
+export function dropOramaIndex(projectId: string): void {
+  registry.delete(projectId)
+}
+
+/**
+ * 在某个项目的 Orama 索引上执行向量召回，返回与现有 RetrievalResult 兼容的结构。
+ *
+ * 过滤条件（type / tags / lastUpdatedChapter）翻译为 Orama where 子句。
+ * tags 在 schema 中声明为 string[]，Orama where 对其按「包含任一标签」匹配；
+ * 为稳妥起见，命中后再做一次本地校验，避免不同 Orama 版本语义差异带来误召回。
+ */
+export async function searchOrama(
+  projectId: string,
+  query: RetrievalQuery,
+  queryVector: number[],
+): Promise<RetrievalResult> {
+  const db = await getOramaIndex(projectId)
+
+  if (!db) {
+    return {
+      query: query.query,
+      candidates: [],
+      total: 0,
+    }
+  }
+
+  const entry = registry.get(projectId)
+  if (entry && queryVector.length !== entry.vectorDimension) {
+    // 查询向量维度与索引维度不一致（通常是 Embedding 模型切换后未重建），
+    // 直接返回空召回而不是抛错，让上层走「无上下文」兜底，避免阻塞生成。
+    return {
+      query: query.query,
+      candidates: [],
+      total: 0,
+    }
+  }
+
+  // 过滤策略：
+  // - type / lastUpdatedChapter 是稳定标量（ASCII 或受控取值），交给 Orama where 精确过滤。
+  // - tags 是用户自由文本（常含中文），Orama 的 where 基于 tokenizer 分词，中文会被切成
+  //   单字 token 导致匹配不稳定。因此 tags 不进 where，而是让 Orama 多召回，再用本地
+  //   精确匹配兜底。为避免 topK 截断掉本应被本地保留的候选，带 tags 时放大召回上限。
+  const where = buildWhereClause(query)
+  const needsLocalTagFilter = !!query.filters?.tags?.length
+  const recallLimit = needsLocalTagFilter ? Math.max(query.topK * 4, query.topK) : query.topK
+
+  const results = await searchVector(db, {
+    mode: MODE_VECTOR_SEARCH,
+    vector: {
+      value: queryVector,
+      property: VECTOR_PROPERTY,
+    },
+    similarity: 0,
+    where,
+    limit: recallLimit,
+  })
+
+  const candidates: RetrievalCandidate[] = []
+  for (const hit of results.hits) {
+    const document = hit.document as OramaHitDocument
+    if (!matchesFilters(document, query)) {
+      continue
+    }
+
+    candidates.push({
+      id: document.id,
+      projectId,
+      sourcePath: document.sourcePath,
+      type: document.type,
+      name: document.name,
+      summary: document.summary,
+      retrievalText: document.retrievalText,
+      tags: document.tags,
+      lastUpdatedChapter: document.lastUpdatedChapter,
+      relatedChapters: document.relatedChapters,
+      score: hit.score,
+    })
+
+    if (candidates.length >= query.topK) {
+      break
+    }
+  }
+
+  return {
+    query: query.query,
+    candidates,
+    total: candidates.length,
+  }
+}
+
+type OramaHitDocument = {
+  id: string
+  sourcePath: string
+  type: RetrievalCandidate['type']
+  name: string
+  summary: string
+  retrievalText: string
+  tags: string[]
+  lastUpdatedChapter: string
+  relatedChapters: string[]
+}
+
+function buildWhereClause(query: RetrievalQuery) {
+  const filters = query.filters
+  if (!filters) {
+    return undefined
+  }
+
+  const clauses: Record<string, unknown> = {}
+
+  if (filters.type?.length) {
+    clauses.type = filters.type
+  }
+
+  if (filters.lastUpdatedChapter) {
+    clauses.lastUpdatedChapter = filters.lastUpdatedChapter
+  }
+
+  // tags 不放入 where：中文 tag 经 tokenizer 分词后匹配不稳定，改由本地 matchesFilters 兜底。
+  return Object.keys(clauses).length > 0 ? clauses : undefined
+}
+
+function matchesFilters(
+  document: { type: RetrievalCandidate['type']; tags: string[]; lastUpdatedChapter: string },
+  query: RetrievalQuery,
+) {
+  if (query.filters?.type?.length && !query.filters.type.includes(document.type)) {
+    return false
+  }
+
+  if (query.filters?.tags?.length && !query.filters.tags.some((tag) => document.tags.includes(tag))) {
+    return false
+  }
+
+  if (query.filters?.lastUpdatedChapter && query.filters.lastUpdatedChapter !== document.lastUpdatedChapter) {
+    return false
+  }
+
+  return true
+}
diff --git a/packages/core/src/core/rag/search.test.ts b/packages/core/src/core/rag/search.test.ts
new file mode 100644
index 0000000..d5d65f2
--- /dev/null
+++ b/packages/core/src/core/rag/search.test.ts
@@ -0,0 +1,155 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// 空索引场景下 searchRagCandidates 会触发懒构建（读 IndexedDB），
+// node 测试环境没有 indexedDB，mock 成空列表让懒构建返回 null。
+vi.mock('./index-store', () => ({
+  createRagIndexStore: () => ({
+    listProjectDocuments: async () => [],
+  }),
+}))
+
+import { buildOramaIndex, dropOramaIndex } from './orama-index'
+import { searchRagCandidates } from './search'
+
+import type { ProjectConfig } from '../../types/project'
+import type { IndexedElementDocument } from '../../types/rag'
+
+const PROJECT_ID = 'proj-search-test'
+
+// 用一个稳定可区分的查询向量构造 embedding 响应。
+// 这些向量不经过真实模型，只用于验证召回链路：查询向量与文档向量的几何关系决定排序。
+const QUERY_VECTOR = [1, 0, 0]
+
+function mockEmbeddingFetch() {
+  const fetchMock = (input: string | URL | Request, init?: RequestInit) => {
+    const body = init?.body ? JSON.parse(init.body as string) : {}
+    const url = typeof input === 'string' ? input : input.toString()
+
+    if (url.endsWith('/embeddings')) {
+      return Promise.resolve(
+        new Response(
+          JSON.stringify({
+            data: [{ embedding: QUERY_VECTOR, index: 0 }],
+          }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        ),
+      )
+    }
+
+    return Promise.resolve(new Response('{}', { status: 200 }))
+  }
+
+  globalThis.fetch = fetchMock as typeof globalThis.fetch
+}
+
+function makeConfig(): ProjectConfig {
+  return {
+    embedding: {
+      baseUrl: 'https://embed.example.com',
+      apiKey: 'test-key',
+      model: 'test-embed',
+    },
+  } as ProjectConfig
+}
+
+function makeDocument(id: string, vector: number[]): IndexedElementDocument {
+  return {
+    id,
+    projectId: PROJECT_ID,
+    sourcePath: `elements/characters/${id}.md`,
+    type: 'character',
+    name: id,
+    summary: id,
+    retrievalText: id,
+    vector,
+    tags: [],
+    lastUpdatedChapter: '',
+    relatedChapters: [],
+    sourceModifiedAt: '',
+    indexedAt: '',
+    contentHash: '',
+    embeddingProvider: '',
+    embeddingModel: '',
+    embeddingDim: vector.length,
+    embeddingTextVersion: 1,
+  } as IndexedElementDocument
+}
+
+const originalFetch = globalThis.fetch
+
+beforeEach(() => {
+  mockEmbeddingFetch()
+})
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+  dropOramaIndex(PROJECT_ID)
+})
+
+describe('searchRagCandidates', () => {
+  it('returns empty result when no index exists', async () => {
+    const result = await searchRagCandidates(
+      { projectId: PROJECT_ID, query: '查询', topK: 10 },
+      makeConfig(),
+    )
+
+    expect(result.candidates).toEqual([])
+    expect(result.total).toBe(0)
+  })
+
+  it('returns ranked candidates from the Orama index', async () => {
+    await buildOramaIndex(PROJECT_ID, [
+      makeDocument('near', QUERY_VECTOR),
+      makeDocument('far', [0, 1, 0]),
+    ])
+
+    const result = await searchRagCandidates(
+      { projectId: PROJECT_ID, query: '查询', topK: 10 },
+      makeConfig(),
+    )
+
+    expect(result.total).toBe(2)
+    expect(result.candidates[0].id).toBe('near')
+  })
+
+  it('respects topK', async () => {
+    await buildOramaIndex(PROJECT_ID, [
+      makeDocument('a', QUERY_VECTOR),
+      makeDocument('b', QUERY_VECTOR),
+      makeDocument('c', QUERY_VECTOR),
+    ])
+
+    const result = await searchRagCandidates(
+      { projectId: PROJECT_ID, query: '查询', topK: 2 },
+      makeConfig(),
+    )
+
+    expect(result.candidates).toHaveLength(2)
+  })
+
+  it('passes type filter through to Orama', async () => {
+    await buildOramaIndex(PROJECT_ID, [
+      { ...makeDocument('char', QUERY_VECTOR), type: 'character' },
+      { ...makeDocument('loc', QUERY_VECTOR), type: 'location', sourcePath: 'elements/locations/loc.md' },
+    ])
+
+    const result = await searchRagCandidates(
+      { projectId: PROJECT_ID, query: '查询', topK: 10, filters: { type: ['character'] } },
+      makeConfig(),
+    )
+
+    expect(result.candidates).toHaveLength(1)
+    expect(result.candidates[0].id).toBe('char')
+  })
+
+  it('carries score on each candidate', async () => {
+    await buildOramaIndex(PROJECT_ID, [makeDocument('a', QUERY_VECTOR)])
+
+    const result = await searchRagCandidates(
+      { projectId: PROJECT_ID, query: '查询', topK: 10 },
+      makeConfig(),
+    )
+
+    expect(result.candidates[0].score).toBeGreaterThan(0)
+  })
+})
diff --git a/packages/core/src/core/rag/search.ts b/packages/core/src/core/rag/search.ts
index e88b0e5..caeb154 100644
--- a/packages/core/src/core/rag/search.ts
+++ b/packages/core/src/core/rag/search.ts
@@ -1,25 +1,14 @@
 import { createEmbedding } from '../embedding/client'
 
 import type { ProjectConfig } from '../../types/project'
-import type { RetrievalCandidate, RetrievalQuery, RetrievalResult } from '../../types/rag'
+import type { RetrievalQuery, RetrievalResult } from '../../types/rag'
 
-import { createRagIndexStore } from './index-store'
+import { searchOrama } from './orama-index'
 
 export async function searchRagCandidates(
   query: RetrievalQuery,
   config: ProjectConfig,
 ): Promise<RetrievalResult> {
-  const store = createRagIndexStore()
-  const documents = await store.listProjectDocuments(query.projectId)
-
-  if (documents.length === 0) {
-    return {
-      query: query.query,
-      candidates: [],
-      total: 0,
-    }
-  }
-
   const queryEmbedding = await createEmbedding({
     baseUrl: config.embedding.baseUrl,
     apiKey: config.embedding.apiKey,
@@ -27,68 +16,7 @@ export async function searchRagCandidates(
     text: query.query,
   })
 
-  const candidates: RetrievalCandidate[] = documents
-    .filter((document) => matchesFilters(document, query))
-    .map((document) => ({
-      id: document.id,
-      projectId: document.projectId,
-      sourcePath: document.sourcePath,
-      type: document.type,
-      name: document.name,
-      summary: document.summary,
-      retrievalText: document.retrievalText,
-      tags: document.tags,
-      lastUpdatedChapter: document.lastUpdatedChapter,
-      relatedChapters: document.relatedChapters,
-      score: cosineSimilarity(queryEmbedding.vector, document.vector),
-    }))
-    .sort((left, right) => (right.score ?? 0) - (left.score ?? 0))
-    .slice(0, query.topK)
-
-  return {
-    query: query.query,
-    candidates,
-    total: candidates.length,
-  }
-}
-
-function matchesFilters(
-  document: { type: RetrievalCandidate['type']; tags: string[]; lastUpdatedChapter: string },
-  query: RetrievalQuery,
-) {
-  if (query.filters?.type?.length && !query.filters.type.includes(document.type)) {
-    return false
-  }
-
-  if (query.filters?.tags?.length && !query.filters.tags.some((tag) => document.tags.includes(tag))) {
-    return false
-  }
-
-  if (query.filters?.lastUpdatedChapter && query.filters.lastUpdatedChapter !== document.lastUpdatedChapter) {
-    return false
-  }
-
-  return true
-}
-
-function cosineSimilarity(left: number[], right: number[]) {
-  if (left.length === 0 || right.length === 0 || left.length !== right.length) {
-    return 0
-  }
-
-  let dot = 0
-  let leftNorm = 0
-  let rightNorm = 0
-
-  for (let index = 0; index < left.length; index += 1) {
-    dot += left[index] * right[index]
-    leftNorm += left[index] * left[index]
-    rightNorm += right[index] * right[index]
-  }
-
-  if (leftNorm === 0 || rightNorm === 0) {
-    return 0
-  }
-
-  return dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm))
+  // 粗召回完全交给 Orama 内存索引（向量相似度 + metadata 过滤），
+  // 不再做本地 cosine 全量遍历。详见 orama-index.ts。
+  return searchOrama(query.projectId, query, queryEmbedding.vector)
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1dcd62c..e1baf3a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -77,6 +77,10 @@ importers:
         version: 3.3.1(typescript@6.0.3)
 
   packages/core:
+    dependencies:
+      '@orama/orama':
+        specifier: ^3.1.18
+        version: 3.1.18
     devDependencies:
       typescript:
         specifier: ^6.0.2
@@ -522,6 +526,10 @@ packages:
   '@jridgewell/trace-mapping@0.3.31':
     resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
 
+  '@orama/orama@3.1.18':
+    resolution: {integrity: sha512-a61ljmRVVyG5MC/698C8/FfFDw5a8LOIvyOLW5fztgUXqUpc1jOfQzOitSCbge657OgXXThmY3Tk8fpiDb4UcA==}
+    engines: {node: '>= 20.0.0'}
+
   '@parcel/watcher-android-arm64@2.5.6':
     resolution: {integrity: sha512-YQxSS34tPF/6ZG7r/Ih9xy+kP/WwediEUsqmtf0cuCV5TPPKw/PQHRhueUo6JdeFJaqV3pyjm0GdYjZotbRt/A==}
     engines: {node: '>= 10.0.0'}
@@ -2322,6 +2330,8 @@ snapshots:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.5.5
 
+  '@orama/orama@3.1.18': {}
+
   '@parcel/watcher-android-arm64@2.5.6':
     optional: true
 

From 9a0bdf09bdeb98ba372d99be25af697e0869bca0 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 20:28:12 +0800
Subject: [PATCH 30/36] =?UTF-8?q?docs(docs):=20=E6=9B=B4=E6=96=B0=20docs?=
 =?UTF-8?q?=20=E5=AD=90=E6=A8=A1=E5=9D=97=E4=BF=AE=E6=AD=A3=20stopRun=20?=
 =?UTF-8?q?=E8=BF=87=E6=97=B6=E6=8F=8F=E8=BF=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs b/docs
index 7aace5f..7899cac 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit 7aace5f8cf33c4b0d124ae8f905912e1e6cdab6b
+Subproject commit 7899cacbfadbed7afb2b427c6cb49ec882205b75

From 51fb981f1a71f9cacb26b1816ab5f06070b2ecd3 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 20:49:08 +0800
Subject: [PATCH 31/36] =?UTF-8?q?feat(project):=20RAG=20=E7=B4=A2=E5=BC=95?=
 =?UTF-8?q?=E7=8A=B6=E6=80=81=E6=A0=8F=E4=B8=8E=20contentHash=20=E5=A2=9E?=
 =?UTF-8?q?=E9=87=8F=E9=87=8D=E5=BB=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

将 RAG 索引状态/重建入口从设置页移到主工作区底部常驻状态栏，
要素写入后由事件总线自动反映 stale，用户点击状态栏才重建（控制权在用户）；
重建时用 contentHash 短路，未变文件复用旧向量，只对变更文件调 Embedding。

core:
- 新增 index-events.ts：EventTarget 事件总线，markProjectIndexStale /
  buildProjectIndex 写完 meta 后 dispatchIndexChange，跨 service 传播
- indexer.ts: buildProjectIndex 循环加 contentHash 短路（与 writer 的
  normalizeForComparison 口径对齐，排除 updatedAt 行避免误触发），
  旧文档 model/dim/version 全一致才复用向量跳过 Embedding；
  增量场景清理已删除要素（removeDocuments）；如实返回 skippedCount
- rag-service.ts: rebuildIndex 支持可选 sourcePaths（有则增量，无则全量）；
  新增 subscribeIndexChange 透传事件总线供 app 层订阅

app:
- 新建 useIndexStore (stores/index.ts)：持有响应式 indexMeta，
  init 订阅事件 + 首次 inspect，dispose 退订；rebuild 切 busy 态
- 新建 IndexStatusBar.vue：底部常驻状态栏，健康度指示点 + 状态文案，
  stale/error 可点击触发重建，hover 显示构建时间/错误
- ProjectView: 根容器改纵向 flex，四面板包进内层，状态栏挂底部；
  onMounted init / onUnmounted dispose；去掉要素写入的 stale toast
- SettingsModal: 移除向量索引卡片及相关逻辑（约 -90 行）
- ExtractionFlowPanel: stale 提示文案改为指向底部状态栏

测试：新增 indexer.test.ts（6 例 contentHash 短路/模型变化/删除清理）与
index-events.test.ts（3 例）；全量 121 测试通过，typecheck + build 干净
---
 .../components/chat/ExtractionFlowPanel.vue   |   2 +-
 .../src/components/layout/IndexStatusBar.vue  | 113 +++++++
 .../src/components/settings/SettingsModal.vue | 146 ---------
 packages/app/src/stores/index.ts              | 139 +++++++++
 packages/app/src/views/ProjectView.vue        | 174 ++++++-----
 .../core/src/core/rag/index-events.test.ts    |  53 ++++
 packages/core/src/core/rag/index-events.ts    |  51 ++++
 packages/core/src/core/rag/indexer.test.ts    | 283 ++++++++++++++++++
 packages/core/src/core/rag/indexer.ts         |  91 +++++-
 packages/core/src/services/rag-service.ts     |  30 +-
 10 files changed, 841 insertions(+), 241 deletions(-)
 create mode 100644 packages/app/src/components/layout/IndexStatusBar.vue
 create mode 100644 packages/app/src/stores/index.ts
 create mode 100644 packages/core/src/core/rag/index-events.test.ts
 create mode 100644 packages/core/src/core/rag/index-events.ts
 create mode 100644 packages/core/src/core/rag/indexer.test.ts

diff --git a/packages/app/src/components/chat/ExtractionFlowPanel.vue b/packages/app/src/components/chat/ExtractionFlowPanel.vue
index b8473c8..b9916a8 100644
--- a/packages/app/src/components/chat/ExtractionFlowPanel.vue
+++ b/packages/app/src/components/chat/ExtractionFlowPanel.vue
@@ -224,7 +224,7 @@ function handleDismiss() {
               <p>新增 {{ writeResult.created.length }} 个</p>
               <p>更新 {{ writeResult.updated.length }} 个</p>
               <p v-if="writeResult.skipped.length > 0">跳过 {{ writeResult.skipped.length }} 个（无变化）</p>
-              <p v-if="writeResult.staleIndex" class="mt-2 text-amber-600">RAG 索引已标记为过期，可在设置中重建。</p>
+              <p v-if="writeResult.staleIndex" class="mt-2 text-amber-600">索引已过期，可点底部状态栏重建。</p>
             </div>
 
             <div v-else-if="phase === 'error'" class="text-sm text-gray-600">
diff --git a/packages/app/src/components/layout/IndexStatusBar.vue b/packages/app/src/components/layout/IndexStatusBar.vue
new file mode 100644
index 0000000..9ccb1e7
--- /dev/null
+++ b/packages/app/src/components/layout/IndexStatusBar.vue
@@ -0,0 +1,113 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+import Tooltip from '../ui/Tooltip.vue'
+import { useIndexStore, getIndexStatusDotClass, getIndexStatusLabel } from '../../stores/index'
+import type { IndexStatusView } from '@novai/core/services/types'
+
+/**
+ * 底部常驻 RAG 索引状态栏。
+ *
+ * - 随项目激活时由 ProjectView 注入 projectId 并触发 init
+ * - 索引状态变化（要素写入标 stale / 重建完成）通过事件总线自动反映
+ * - stale / error 可点击触发增量重建（省 API：未变文件复用旧向量）
+ */
+const props = defineProps<{
+  projectId: string
+}>()
+
+const indexStore = useIndexStore()
+
+const status = computed<IndexStatusView | null>(() => indexStore.status)
+const isBusy = computed(() => indexStore.isBusy)
+
+/** 主文案：状态 + 项数。 */
+const label = computed(() => {
+  if (!status.value) {
+    return '索引未初始化'
+  }
+
+  const base = getIndexStatusLabel(status.value)
+  const count = indexStore.documentCount
+
+  if (status.value === 'building' || status.value === 'rebuilding') {
+    return `${base}…`
+  }
+  if (status.value === 'empty') {
+    return base
+  }
+  return `${base} · ${count} 项`
+})
+
+/** 点击态：仅 stale/error 且非 busy 时可触发重建。 */
+const actionable = computed(
+  () => !isBusy.value && (status.value === 'stale' || status.value === 'error'),
+)
+
+const dotClass = computed(() => {
+  if (isBusy.value) {
+    return 'bg-blue-500 animate-pulse'
+  }
+  return status.value ? getIndexStatusDotClass(status.value) : 'bg-gray-300'
+})
+
+/** tooltip 详情：构建时间 / 错误原因。 */
+const tooltipText = computed(() => {
+  const meta = indexStore.indexMeta
+  if (!meta) {
+    return '当前项目还没有索引记录'
+  }
+
+  const parts: string[] = []
+  if (meta.lastBuildAt) {
+    parts.push(`上次构建：${formatTime(meta.lastBuildAt)}`)
+  }
+  if (meta.embeddingModel) {
+    parts.push(`模型：${meta.embeddingModel}`)
+  }
+  if (status.value === 'stale' || status.value === 'error') {
+    parts.push(meta.lastError ?? '点击重新构建索引')
+  }
+  return parts.join('\n') || '点击查看索引详情'
+})
+
+function handleClick() {
+  if (!actionable.value) {
+    return
+  }
+  indexStore.rebuild(props.projectId)
+}
+
+function formatTime(iso: string) {
+  try {
+    return new Date(iso).toLocaleString('zh-CN', { hour12: false })
+  } catch {
+    return iso
+  }
+}
+</script>
+
+<template>
+  <div
+    class="flex h-7 shrink-0 items-center gap-2 border-t border-gray-200 bg-gray-50 px-3 text-xs text-gray-600"
+  >
+    <Tooltip
+      :text="tooltipText"
+      preferred-placement="top"
+      multiline
+    >
+      <button
+        type="button"
+        class="flex items-center gap-1.5 rounded px-1.5 py-0.5 transition-colors"
+        :class="actionable ? 'cursor-pointer hover:bg-gray-200 hover:text-gray-900' : 'cursor-default'"
+        :disabled="!actionable"
+        @click="handleClick"
+      >
+        <span :class="['h-2 w-2 rounded-full', dotClass]" />
+        <span>{{ label }}</span>
+      </button>
+    </Tooltip>
+
+    <span v-if="indexStore.errorMessage" class="text-red-500">{{ indexStore.errorMessage }}</span>
+  </div>
+</template>
diff --git a/packages/app/src/components/settings/SettingsModal.vue b/packages/app/src/components/settings/SettingsModal.vue
index 909dd99..ffdb9cd 100644
--- a/packages/app/src/components/settings/SettingsModal.vue
+++ b/packages/app/src/components/settings/SettingsModal.vue
@@ -1,8 +1,6 @@
 <script setup lang="ts">
 import { computed, onMounted, ref } from 'vue'
 import { useSettingsStore } from '../../stores/settings'
-import { inspectIndex, rebuildIndex } from '@novai/core/services/rag-service'
-import type { ProjectIndexMetaView } from '@novai/core/services/types'
 import PasswordInput from '../ui/PasswordInput.vue'
 
 const props = defineProps<{
@@ -52,9 +50,6 @@ const projectForm = ref({
 
 const isTesting = ref(false)
 const testResult = ref<{ ok: boolean; message: string } | null>(null)
-const isIndexBusy = ref(false)
-const indexMeta = ref<ProjectIndexMetaView | null>(null)
-const indexStatusMessage = ref('尚未读取索引状态')
 
 const projectId = computed(() => props.projectId)
 
@@ -91,8 +86,6 @@ onMounted(async () => {
       applyProjectSettings(settingsStore.config.settings)
     }
   }
-
-  await handleInspectIndex()
 })
 
 async function handleTestLlm() {
@@ -151,72 +144,6 @@ async function handleSaveProject() {
   }
 }
 
-async function handleInspectIndex() {
-  isIndexBusy.value = true
-  try {
-    indexMeta.value = await inspectIndex(projectId.value)
-    indexStatusMessage.value = indexMeta.value
-      ? `当前状态：${getIndexStatusLabel(indexMeta.value.status)}`
-      : '当前项目还没有索引记录'
-  } catch (error) {
-    indexStatusMessage.value = error instanceof Error ? error.message : '读取索引状态失败'
-  } finally {
-    isIndexBusy.value = false
-  }
-}
-
-async function handleRebuildIndex() {
-  isIndexBusy.value = true
-  testResult.value = null
-  indexStatusMessage.value = '正在重建向量索引...'
-
-  try {
-    const result = await rebuildIndex(projectId.value)
-    indexMeta.value = await inspectIndex(projectId.value)
-    indexStatusMessage.value = result.message
-    testResult.value = {
-      ok: result.status === 'ready' || result.status === 'empty',
-      message: result.message,
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : '重建索引失败'
-    indexStatusMessage.value = message
-    testResult.value = {
-      ok: false,
-      message,
-    }
-  } finally {
-    isIndexBusy.value = false
-  }
-}
-
-function getIndexStatusLabel(status: ProjectIndexMetaView['status']) {
-  switch (status) {
-    case 'ready': return '可用'
-    case 'empty': return '空索引'
-    case 'building': return '构建中'
-    case 'rebuilding': return '重建中'
-    case 'stale': return '已过期'
-    case 'error': return '错误'
-    default: return status
-  }
-}
-
-function getIndexStatusClass(status?: ProjectIndexMetaView['status']) {
-  switch (status) {
-    case 'ready': return 'bg-green-50 text-green-700 ring-green-200'
-    case 'stale': return 'bg-amber-50 text-amber-700 ring-amber-200'
-    case 'error': return 'bg-red-50 text-red-700 ring-red-200'
-    case 'building':
-    case 'rebuilding': return 'bg-blue-50 text-blue-700 ring-blue-200'
-    default: return 'bg-gray-50 text-gray-700 ring-gray-200'
-  }
-}
-
-function formatDate(value?: string) {
-  return value ? new Date(value).toLocaleString('zh-CN') : '暂无'
-}
-
 function applyProjectSettings(settings: NonNullable<typeof settingsStore.config>['settings']) {
   projectForm.value = {
     proofreadDefaultChapters: settings.proofreadDefaultChapters ?? 3,
@@ -452,79 +379,6 @@ function applyProjectSettings(settings: NonNullable<typeof settingsStore.config>
             <div>
               <h3 class="mb-3 text-sm font-semibold text-gray-800">RAG 设置</h3>
               <div class="space-y-4">
-                <div class="rounded-lg border border-gray-200 bg-white p-4">
-                  <div class="flex items-start justify-between gap-3">
-                    <div class="min-w-0">
-                      <div class="flex items-center gap-2">
-                        <h4 class="text-sm font-semibold text-gray-800">向量索引</h4>
-                        <span
-                          :class="[
-                            'rounded-full px-2 py-0.5 text-xs font-medium ring-1',
-                            getIndexStatusClass(indexMeta?.status),
-                          ]"
-                        >
-                          {{ indexMeta ? getIndexStatusLabel(indexMeta.status) : '未创建' }}
-                        </span>
-                      </div>
-                      <p class="mt-1 text-xs text-gray-500">{{ indexStatusMessage }}</p>
-                    </div>
-                    <div class="flex shrink-0 items-center gap-1">
-                      <button
-                        class="rounded-lg p-1.5 text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-800 disabled:opacity-40"
-                        :disabled="isIndexBusy"
-                        title="刷新索引状态"
-                        @click="handleInspectIndex"
-                      >
-                        <svg
-                          v-if="isIndexBusy"
-                          class="h-4 w-4 animate-spin"
-                          fill="none"
-                          viewBox="0 0 24 24"
-                        >
-                          <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4" />
-                          <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
-                        </svg>
-                        <svg v-else class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 4v6h6M20 20v-6h-6M5.5 15A7 7 0 0018 18.5M18.5 9A7 7 0 006 5.5" />
-                        </svg>
-                      </button>
-                      <button
-                        class="rounded-lg p-1.5 text-gray-500 transition-colors hover:bg-gray-100 hover:text-gray-800 disabled:opacity-40"
-                        :disabled="isIndexBusy"
-                        title="重建向量索引"
-                        @click="handleRebuildIndex"
-                      >
-                        <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4.5v15m7.5-7.5h-15" />
-                        </svg>
-                      </button>
-                    </div>
-                  </div>
-
-                  <div class="mt-3 grid grid-cols-2 gap-2 text-xs text-gray-600">
-                    <div class="rounded-md bg-gray-50 px-3 py-2">
-                      <div class="text-gray-400">文档数</div>
-                      <div class="mt-1 font-medium text-gray-800">{{ indexMeta?.documentCount ?? 0 }}</div>
-                    </div>
-                    <div class="rounded-md bg-gray-50 px-3 py-2">
-                      <div class="text-gray-400">向量维度</div>
-                      <div class="mt-1 font-medium text-gray-800">{{ indexMeta?.embeddingDim ?? 0 }}</div>
-                    </div>
-                    <div class="rounded-md bg-gray-50 px-3 py-2">
-                      <div class="text-gray-400">Embedding 模型</div>
-                      <div class="mt-1 truncate font-medium text-gray-800">{{ indexMeta?.embeddingModel || '暂无' }}</div>
-                    </div>
-                    <div class="rounded-md bg-gray-50 px-3 py-2">
-                      <div class="text-gray-400">最近构建</div>
-                      <div class="mt-1 truncate font-medium text-gray-800">{{ formatDate(indexMeta?.lastBuildAt) }}</div>
-                    </div>
-                  </div>
-
-                  <p v-if="indexMeta?.lastError" class="mt-3 text-xs text-red-600">
-                    {{ indexMeta.lastError }}
-                  </p>
-                </div>
-
                 <div>
                   <label class="mb-1 block text-sm font-medium text-gray-700">粗检索返回条数</label>
                   <p class="mb-1 text-xs text-gray-500">粗检索阶段返回的候选要素数量</p>
diff --git a/packages/app/src/stores/index.ts b/packages/app/src/stores/index.ts
new file mode 100644
index 0000000..160fc20
--- /dev/null
+++ b/packages/app/src/stores/index.ts
@@ -0,0 +1,139 @@
+import { computed, ref } from 'vue'
+import { defineStore } from 'pinia'
+
+import { inspectIndex, rebuildIndex, subscribeIndexChange } from '@novai/core/services/rag-service'
+import type {
+  IndexBuildResultView,
+  IndexStatusView,
+  ProjectIndexMetaView,
+} from '@novai/core/services/types'
+
+/**
+ * RAG 索引状态的响应式 store。
+ *
+ * 持有当前项目的索引 meta，订阅 core 层事件总线自动更新
+ * （要素写入标 stale / 重建完成 / 构建失败都会通过事件刷新）。
+ * 状态栏与设置页共享同一份状态，避免重复请求。
+ */
+export const useIndexStore = defineStore('rag-index', () => {
+  const indexMeta = ref<ProjectIndexMetaView | null>(null)
+  const isBusy = ref(false)
+  const errorMessage = ref('')
+
+  let unsubscribe: (() => void) | null = null
+
+  const status = computed<IndexStatusView | null>(() => indexMeta.value?.status ?? null)
+  const documentCount = computed(() => indexMeta.value?.documentCount ?? 0)
+
+  /** 索引是否处于「可点击重建」的过期/异常态。 */
+  const canRebuild = computed(
+    () => !isBusy.value && (status.value === 'stale' || status.value === 'error' || status.value === 'ready' || status.value === 'empty'),
+  )
+
+  async function init(projectId: string) {
+    // 重新 init 前先退订旧订阅，避免泄漏。
+    dispose()
+
+    unsubscribe = subscribeIndexChange(projectId, (meta) => {
+      indexMeta.value = meta
+    })
+
+    await refresh(projectId)
+  }
+
+  function dispose() {
+    if (unsubscribe) {
+      unsubscribe()
+      unsubscribe = null
+    }
+    indexMeta.value = null
+    isBusy.value = false
+    errorMessage.value = ''
+  }
+
+  async function refresh(projectId: string) {
+    try {
+      indexMeta.value = await inspectIndex(projectId)
+    } catch (error) {
+      errorMessage.value = error instanceof Error ? error.message : '读取索引状态失败'
+    }
+  }
+
+  /**
+   * 重建索引。不传 sourcePaths 为全量；传入则增量（仅重建指定文件，复用未变向量）。
+   * 重建过程中状态栏进入 busy 态，完成后由事件总线或显式 refresh 更新。
+   */
+  async function rebuild(projectId: string, sourcePaths?: string[]): Promise<IndexBuildResultView | null> {
+    if (isBusy.value) {
+      return null
+    }
+
+    errorMessage.value = ''
+    isBusy.value = true
+
+    try {
+      const result = await rebuildIndex(projectId, sourcePaths)
+      // 事件总线通常已更新 meta，这里兜底刷新一次保证一致。
+      await refresh(projectId)
+      return result
+    } catch (error) {
+      errorMessage.value = error instanceof Error ? error.message : '重建索引失败'
+      await refresh(projectId)
+      return null
+    } finally {
+      isBusy.value = false
+    }
+  }
+
+  return {
+    indexMeta,
+    isBusy,
+    errorMessage,
+    status,
+    documentCount,
+    canRebuild,
+    init,
+    dispose,
+    refresh,
+    rebuild,
+  }
+})
+
+const STATUS_LABELS: Record<IndexStatusView, string> = {
+  empty: '空索引',
+  building: '构建中',
+  ready: '索引就绪',
+  stale: '部分过期',
+  rebuilding: '重建中',
+  error: '索引异常',
+}
+
+const STATUS_CLASSES: Record<IndexStatusView, string> = {
+  empty: 'bg-gray-100 text-gray-500 ring-gray-200',
+  building: 'bg-blue-50 text-blue-600 ring-blue-200',
+  ready: 'bg-green-50 text-green-700 ring-green-200',
+  stale: 'bg-amber-50 text-amber-700 ring-amber-200',
+  rebuilding: 'bg-blue-50 text-blue-600 ring-blue-200',
+  error: 'bg-red-50 text-red-700 ring-red-200',
+}
+
+const STATUS_DOT_CLASSES: Record<IndexStatusView, string> = {
+  empty: 'bg-gray-400',
+  building: 'bg-blue-500 animate-pulse',
+  ready: 'bg-green-500',
+  stale: 'bg-amber-500',
+  rebuilding: 'bg-blue-500 animate-pulse',
+  error: 'bg-red-500',
+}
+
+export function getIndexStatusLabel(status: IndexStatusView): string {
+  return STATUS_LABELS[status]
+}
+
+export function getIndexStatusClass(status: IndexStatusView): string {
+  return STATUS_CLASSES[status]
+}
+
+export function getIndexStatusDotClass(status: IndexStatusView): string {
+  return STATUS_DOT_CLASSES[status]
+}
diff --git a/packages/app/src/views/ProjectView.vue b/packages/app/src/views/ProjectView.vue
index 3b96a86..9235998 100644
--- a/packages/app/src/views/ProjectView.vue
+++ b/packages/app/src/views/ProjectView.vue
@@ -1,13 +1,15 @@
 <script setup lang="ts">
-import { computed, onMounted, ref, watch } from 'vue'
+import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { useProjectStore } from '../stores/project'
 import { useChatStore } from '../stores/chat'
+import { useIndexStore } from '../stores/index'
 import { useToast } from '../composables/useToast'
 import ActivityBar from '../components/layout/ActivityBar.vue'
 import CategoryPanel from '../components/layout/CategoryPanel.vue'
 import ChatPanel from '../components/layout/ChatPanel.vue'
 import ContentPanel from '../components/layout/ContentPanel.vue'
+import IndexStatusBar from '../components/layout/IndexStatusBar.vue'
 import SettingsModal from '../components/settings/SettingsModal.vue'
 import Toast from '../components/ui/Toast.vue'
 import FirstTimeGuide from '../components/ui/FirstTimeGuide.vue'
@@ -18,6 +20,7 @@ const route = useRoute()
 const router = useRouter()
 const projectStore = useProjectStore()
 const chatStore = useChatStore()
+const indexStore = useIndexStore()
 const toast = useToast()
 
 const projectId = computed(() => route.params.id as string)
@@ -94,6 +97,9 @@ onMounted(async () => {
   // 初始化聊天会话（拉取历史列表，有历史则激活最近一条，否则新建）
   await chatStore.initSessions(projectId.value)
 
+  // 初始化 RAG 索引状态栏（订阅事件 + 首次读取 meta）
+  await indexStore.init(projectId.value)
+
   // 检查是否需要显示首次引导
   if (projectStore.currentProject) {
     const config = projectStore.currentProject.config
@@ -103,6 +109,10 @@ onMounted(async () => {
   }
 })
 
+onUnmounted(() => {
+  indexStore.dispose()
+})
+
 // 监听文件变更，自动刷新分类面板数据
 watch(
   () => chatStore.changedFiles.length,
@@ -220,88 +230,94 @@ function handleGoToSettings() {
 
 async function handleElementsWritten() {
   await projectStore.refreshTree()
-  toast.success('要素文件已写入，RAG 索引已标记为过期')
+  // 索引过期状态由底部 IndexStatusBar 经事件总线自动反映，无需再弹 toast。
+  toast.success('要素文件已写入')
 }
 </script>
 
 <template>
-  <div class="flex h-screen bg-white">
-    <!-- 移动端分类面板遮罩 -->
-    <div
-      v-if="isMobileCategoryOpen"
-      class="fixed inset-0 z-40 bg-black/50 lg:hidden"
-      @click="isMobileCategoryOpen = false"
-    />
-
-    <!-- Activity Bar（最左竖条） -->
-    <ActivityBar
-      :active-category="activeCategory"
-      @select="selectCategory"
-      @open-settings="handleOpenSettings"
-      @back-to-home="handleBackToHome"
-      @proofread="handleNotImplemented('校对')"
-      @organize="handleNotImplemented('章节整理')"
-      @version="handleNotImplemented('版本管理')"
-    />
-
-    <!-- 分类面板（随 Activity Bar 切换） -->
-    <CategoryPanel
-      :active-category="activeCategory"
-      :files="projectStore.currentProject?.files ?? []"
-      :active-file-path="projectStore.activeFile?.path"
-      :active-scene-prompt-path="activeScenePromptPath"
-      :sessions="chatStore.sessions"
-      :active-session-id="chatStore.activeSessionId"
-      :is-open="isCategoryOpen"
-      :is-mobile-open="isMobileCategoryOpen"
-      @select-file="handleSelectFile"
-      @change-scene="handleChangeScene"
-      @close-mobile="isMobileCategoryOpen = false"
-      @select-session="(sessionId) => chatStore.selectSession(projectId, sessionId)"
-      @create-session="chatStore.createNewSession(projectId)"
-      @rename-session="(sessionId, title) => chatStore.renameSession(projectId, sessionId, title)"
-      @delete-session="(sessionId) => chatStore.deleteSession(projectId, sessionId)"
-    />
-
-    <!-- 中间对话面板 -->
-    <ChatPanel
-      :project-id="projectId"
-      :is-sidebar-open="isCategoryOpen"
-      :is-content-panel-open="isContentPanelOpen"
-      :quote="selectionQuote"
-      :scenes="sceneList"
-      :active-scene-prompt-path="activeScenePromptPath"
-      :active-scene-name="activeSceneName"
-      :chapters="chapterList"
-      @toggle-sidebar="toggleSidebar"
-      @toggle-content-panel="toggleContentPanel"
-      @toggle-mobile-sidebar="toggleMobileSidebar"
-      @clear-quote="handleClearQuote"
-      @change-scene="handleChangeScene"
-      @elements-written="handleElementsWritten"
-    >
-      <!-- 首次使用引导 -->
-      <template #guide>
-        <FirstTimeGuide
-          v-if="showGuide"
-          @close="handleCloseGuide"
-          @go-to-settings="handleGoToSettings"
-        />
-      </template>
-    </ChatPanel>
-
-    <!-- 右侧内容面板 -->
-    <ContentPanel
-      :is-open="isContentPanelOpen"
-      :project-id="projectId"
-      :file="projectStore.activeFile"
-      :width="contentPanelWidth"
-      @close="isContentPanelOpen = false"
-      @save="handleSaveFile"
-      @select-quote="handleSelectQuote"
-      @resize="contentPanelWidth = $event"
-      @reset-width="contentPanelWidth = CONTENT_PANEL_DEFAULT"
-    />
+  <div class="flex h-screen flex-col bg-white">
+    <div class="flex min-h-0 flex-1">
+      <!-- 移动端分类面板遮罩 -->
+      <div
+        v-if="isMobileCategoryOpen"
+        class="fixed inset-0 z-40 bg-black/50 lg:hidden"
+        @click="isMobileCategoryOpen = false"
+      />
+
+      <!-- Activity Bar（最左竖条） -->
+      <ActivityBar
+        :active-category="activeCategory"
+        @select="selectCategory"
+        @open-settings="handleOpenSettings"
+        @back-to-home="handleBackToHome"
+        @proofread="handleNotImplemented('校对')"
+        @organize="handleNotImplemented('章节整理')"
+        @version="handleNotImplemented('版本管理')"
+      />
+
+      <!-- 分类面板（随 Activity Bar 切换） -->
+      <CategoryPanel
+        :active-category="activeCategory"
+        :files="projectStore.currentProject?.files ?? []"
+        :active-file-path="projectStore.activeFile?.path"
+        :active-scene-prompt-path="activeScenePromptPath"
+        :sessions="chatStore.sessions"
+        :active-session-id="chatStore.activeSessionId"
+        :is-open="isCategoryOpen"
+        :is-mobile-open="isMobileCategoryOpen"
+        @select-file="handleSelectFile"
+        @change-scene="handleChangeScene"
+        @close-mobile="isMobileCategoryOpen = false"
+        @select-session="(sessionId) => chatStore.selectSession(projectId, sessionId)"
+        @create-session="chatStore.createNewSession(projectId)"
+        @rename-session="(sessionId, title) => chatStore.renameSession(projectId, sessionId, title)"
+        @delete-session="(sessionId) => chatStore.deleteSession(projectId, sessionId)"
+      />
+
+      <!-- 中间对话面板 -->
+      <ChatPanel
+        :project-id="projectId"
+        :is-sidebar-open="isCategoryOpen"
+        :is-content-panel-open="isContentPanelOpen"
+        :quote="selectionQuote"
+        :scenes="sceneList"
+        :active-scene-prompt-path="activeScenePromptPath"
+        :active-scene-name="activeSceneName"
+        :chapters="chapterList"
+        @toggle-sidebar="toggleSidebar"
+        @toggle-content-panel="toggleContentPanel"
+        @toggle-mobile-sidebar="toggleMobileSidebar"
+        @clear-quote="handleClearQuote"
+        @change-scene="handleChangeScene"
+        @elements-written="handleElementsWritten"
+      >
+        <!-- 首次使用引导 -->
+        <template #guide>
+          <FirstTimeGuide
+            v-if="showGuide"
+            @close="handleCloseGuide"
+            @go-to-settings="handleGoToSettings"
+          />
+        </template>
+      </ChatPanel>
+
+      <!-- 右侧内容面板 -->
+      <ContentPanel
+        :is-open="isContentPanelOpen"
+        :project-id="projectId"
+        :file="projectStore.activeFile"
+        :width="contentPanelWidth"
+        @close="isContentPanelOpen = false"
+        @save="handleSaveFile"
+        @select-quote="handleSelectQuote"
+        @resize="contentPanelWidth = $event"
+        @reset-width="contentPanelWidth = CONTENT_PANEL_DEFAULT"
+      />
+    </div>
+
+    <!-- 底部 RAG 索引状态栏（常驻，随项目激活） -->
+    <IndexStatusBar :project-id="projectId" />
 
     <!-- 设置模态框（按需挂载：关闭时销毁，再次打开重新读取磁盘配置） -->
     <SettingsModal
diff --git a/packages/core/src/core/rag/index-events.test.ts b/packages/core/src/core/rag/index-events.test.ts
new file mode 100644
index 0000000..6cc07ea
--- /dev/null
+++ b/packages/core/src/core/rag/index-events.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+
+import { dispatchIndexChange, onRagIndexChange } from './index-events'
+
+import type { ProjectIndexMeta } from '../../types/rag'
+
+function makeMeta(projectId: string, overrides?: Partial<ProjectIndexMeta>): ProjectIndexMeta {
+  return {
+    projectId,
+    status: 'ready',
+    documentCount: 0,
+    embeddingProvider: 'p',
+    embeddingModel: 'm',
+    embeddingDim: 8,
+    embeddingTextVersion: 1,
+    ...overrides,
+  }
+}
+
+describe('rag index events', () => {
+  it('delivers meta to subscribers of the same project', () => {
+    const received: ProjectIndexMeta[] = []
+    const unsubscribe = onRagIndexChange('proj-a', (meta) => received.push(meta))
+
+    dispatchIndexChange('proj-a', makeMeta('proj-a', { status: 'stale' }))
+
+    expect(received).toHaveLength(1)
+    expect(received[0].status).toBe('stale')
+
+    unsubscribe()
+  })
+
+  it('filters out events for other projects', () => {
+    const received: ProjectIndexMeta[] = []
+    const unsubscribe = onRagIndexChange('proj-a', (meta) => received.push(meta))
+
+    dispatchIndexChange('proj-b', makeMeta('proj-b'))
+
+    expect(received).toHaveLength(0)
+    unsubscribe()
+  })
+
+  it('stops delivering after unsubscribe', () => {
+    const received: ProjectIndexMeta[] = []
+    const unsubscribe = onRagIndexChange('proj-a', (meta) => received.push(meta))
+
+    dispatchIndexChange('proj-a', makeMeta('proj-a'))
+    unsubscribe()
+    dispatchIndexChange('proj-a', makeMeta('proj-a'))
+
+    expect(received).toHaveLength(1)
+  })
+})
diff --git a/packages/core/src/core/rag/index-events.ts b/packages/core/src/core/rag/index-events.ts
new file mode 100644
index 0000000..6476023
--- /dev/null
+++ b/packages/core/src/core/rag/index-events.ts
@@ -0,0 +1,51 @@
+import type { ProjectIndexMeta } from '../../types/rag'
+
+/**
+ * RAG 索引状态变化事件总线。
+ *
+ * 独立于 AgentUiEvent——后者是 Agent Loop 专用通道，而索引状态变化可能来自
+ * 要素写入、手动重建等多条非 Agent 路径。用独立的 EventTarget 跨 service 传播，
+ * 让 app 层能在任意路径下感知到 status / documentCount 的变化。
+ */
+
+const EVENT_TYPE = 'rag-index-change'
+
+class RagIndexChangeEvent extends Event {
+  readonly projectId: string
+  readonly meta: ProjectIndexMeta
+
+  constructor(projectId: string, meta: ProjectIndexMeta) {
+    super(EVENT_TYPE)
+    this.projectId = projectId
+    this.meta = meta
+  }
+}
+
+const target = new EventTarget()
+
+/**
+ * 在索引 meta 被写入（构建完成 / 标记 stale / 构建失败）后调用，
+ * 通知订阅者刷新状态。
+ */
+export function dispatchIndexChange(projectId: string, meta: ProjectIndexMeta): void {
+  target.dispatchEvent(new RagIndexChangeEvent(projectId, meta))
+}
+
+/**
+ * 订阅某个项目的索引状态变化。回调只在该 projectId 的事件时触发。
+ * 返回取消订阅函数。
+ */
+export function onRagIndexChange(
+  projectId: string,
+  callback: (meta: ProjectIndexMeta) => void,
+): () => void {
+  const listener = (event: Event) => {
+    const custom = event as RagIndexChangeEvent
+    if (custom.projectId === projectId) {
+      callback(custom.meta)
+    }
+  }
+
+  target.addEventListener(EVENT_TYPE, listener)
+  return () => target.removeEventListener(EVENT_TYPE, listener)
+}
diff --git a/packages/core/src/core/rag/indexer.test.ts b/packages/core/src/core/rag/indexer.test.ts
new file mode 100644
index 0000000..69b7171
--- /dev/null
+++ b/packages/core/src/core/rag/indexer.test.ts
@@ -0,0 +1,283 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+/**
+ * indexer.ts 的 contentHash 增量短路与删除清理是纯逻辑，
+ * 但它依赖 IndexedDB（index-store）、Embedding（fetch）、项目文件系统（project-fs）。
+ * 这里全部 mock，用一个内存 store 观察写入/删除行为，并断言 createEmbedding 的调用次数。
+ */
+
+// 内存 store：记录 upsert / remove / meta，供断言。
+type StoredDoc = import('../../types/rag').IndexedElementDocument
+
+const storeState = {
+  meta: null as import('../../types/rag').ProjectIndexMeta | null,
+  docs: new Map<string, StoredDoc>(),
+  upsertCount: 0,
+  removeCount: 0,
+}
+
+vi.mock('./index-store', () => ({
+  createRagIndexStore: () => ({
+    async getProjectMeta() {
+      return storeState.meta
+    },
+    async saveProjectMeta(meta: import('../../types/rag').ProjectIndexMeta) {
+      storeState.meta = meta
+    },
+    async listProjectDocuments() {
+      return Array.from(storeState.docs.values())
+    },
+    async upsertDocuments(docs: StoredDoc[]) {
+      storeState.upsertCount += 1
+      for (const doc of docs) {
+        storeState.docs.set(`${doc.projectId}::${doc.id}`, doc)
+      }
+    },
+    async removeDocuments(_projectId: string, ids: string[]) {
+      storeState.removeCount += ids.length
+      for (const id of ids) {
+        for (const [key, doc] of storeState.docs) {
+          if (doc.id === id) {
+            storeState.docs.delete(key)
+          }
+        }
+      }
+    },
+    async clearProject(projectId: string) {
+      for (const key of [...storeState.docs.keys()]) {
+        if (key.startsWith(`${projectId}::`)) {
+          storeState.docs.delete(key)
+        }
+      }
+    },
+  }),
+}))
+
+// mock project-fs：用测试注入的文件内容映射。
+const files = new Map<string, { content: string; updatedAt: string }>()
+vi.mock('../fs/project-fs', () => ({
+  async readProjectFile(_project: unknown, path: string) {
+    const file = files.get(path)
+    if (!file) {
+      throw new Error(`测试未提供文件: ${path}`)
+    }
+    return { content: file.content, updatedAt: file.updatedAt }
+  },
+}))
+
+// mock embedding client：记录调用次数，返回可区分向量。
+const embeddingCalls: string[] = []
+vi.mock('../embedding/client', () => ({
+  async createEmbedding({ text }: { text: string }) {
+    embeddingCalls.push(text)
+    // 用文本长度伪造一个稳定可区分的向量，保证不同文本向量不同。
+    const vector = [text.length, text.length * 2, text.length * 3]
+    return { vector, dimension: 3 }
+  },
+}))
+
+import { buildProjectIndex } from './indexer'
+
+import type { ProjectSnapshot } from '../../types/project'
+import type { IndexedElementDocument } from '../../types/rag'
+
+const PROJECT_ID = 'proj-indexer'
+
+const baseConfig = {
+  embedding: {
+    baseUrl: 'https://embed.test',
+    apiKey: 'key',
+    model: 'embed-model',
+  },
+  rerank: { enabled: false, baseUrl: '', apiKey: '', model: '', mode: 'text' as const, topN: 8 },
+  settings: { ragCandidateLimit: 20, ragContextMaxItems: 8, embeddingTextVersion: 1 },
+} as ProjectSnapshot['config']
+
+function makeProject(tree: ProjectSnapshot['tree']): ProjectSnapshot {
+  return {
+    id: PROJECT_ID,
+    handle: {} as ProjectSnapshot['handle'],
+    config: baseConfig,
+    tree,
+  } as ProjectSnapshot
+}
+
+function fileNode(path: string): ProjectSnapshot['tree'][number] {
+  return { kind: 'file', name: path.split('/').pop()!, path, updatedAt: '' }
+}
+
+function elementMd(path: string, name: string, body = '正文内容'): string {
+  return `---\nname: ${name}\ntype: character\nupdatedAt: 2026-01-01T00:00:00.000Z\n---\n\n${body}\n`
+}
+
+function seedDoc(overrides: Partial<IndexedElementDocument> & Pick<IndexedElementDocument, 'id' | 'sourcePath'>): IndexedElementDocument {
+  return {
+    projectId: PROJECT_ID,
+    type: 'character',
+    name: overrides.id,
+    summary: '',
+    retrievalText: '',
+    vector: [9, 9, 9],
+    tags: [],
+    lastUpdatedChapter: '',
+    relatedChapters: [],
+    sourceModifiedAt: '',
+    indexedAt: '',
+    contentHash: '',
+    embeddingProvider: 'https://embed.test',
+    embeddingModel: 'embed-model',
+    embeddingDim: 3,
+    embeddingTextVersion: 1,
+    ...overrides,
+  }
+}
+
+beforeEach(() => {
+  storeState.meta = null
+  storeState.docs.clear()
+  storeState.upsertCount = 0
+  storeState.removeCount = 0
+  files.clear()
+  embeddingCalls.length = 0
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('buildProjectIndex contentHash 增量短路', () => {
+  it('全量重建：所有文件都调 Embedding，不短路', async () => {
+    files.set('elements/characters/a.md', { content: elementMd('elements/characters/a.md', '甲'), updatedAt: '' })
+    files.set('elements/characters/b.md', { content: elementMd('elements/characters/b.md', '乙'), updatedAt: '' })
+
+    const result = await buildProjectIndex(
+      makeProject([fileNode('elements/characters/a.md'), fileNode('elements/characters/b.md')]),
+      { projectId: PROJECT_ID, reason: 'manual-rebuild' },
+    )
+
+    expect(embeddingCalls).toHaveLength(2)
+    expect(result.indexedCount).toBe(2)
+    expect(result.skippedCount).toBe(0)
+  })
+
+  it('增量重建：未变文件复用旧向量，不调 Embedding', async () => {
+    // 先全量建一次，拿到 contentHash
+    files.set('elements/characters/a.md', { content: elementMd('elements/characters/a.md', '甲'), updatedAt: '' })
+    files.set('elements/characters/b.md', { content: elementMd('elements/characters/b.md', '乙'), updatedAt: '' })
+
+    await buildProjectIndex(
+      makeProject([fileNode('elements/characters/a.md'), fileNode('elements/characters/b.md')]),
+      { projectId: PROJECT_ID, reason: 'manual-rebuild' },
+    )
+
+    const docsAfterFirstBuild = Array.from(storeState.docs.values())
+    expect(docsAfterFirstBuild).toHaveLength(2)
+    const firstCallCount = embeddingCalls.length
+    expect(firstCallCount).toBe(2)
+
+    // 再次增量：内容完全不变，应全部短路。
+    embeddingCalls.length = 0
+    const result = await buildProjectIndex(
+      makeProject([fileNode('elements/characters/a.md'), fileNode('elements/characters/b.md')]),
+      { projectId: PROJECT_ID, reason: 'incremental-update' },
+    )
+
+    expect(embeddingCalls).toHaveLength(0)
+    expect(result.skippedCount).toBe(2)
+    expect(result.indexedCount).toBe(2)
+  })
+
+  it('仅刷新 updatedAt 不触发重算（hash 口径排除 updatedAt 行）', async () => {
+    files.set('elements/characters/a.md', { content: elementMd('elements/characters/a.md', '甲'), updatedAt: '' })
+
+    await buildProjectIndex(
+      makeProject([fileNode('elements/characters/a.md')]),
+      { projectId: PROJECT_ID, reason: 'manual-rebuild' },
+    )
+
+    // 改动 updatedAt 行，正文不变。
+    files.set('elements/characters/a.md', {
+      content: `---\nname: 甲\ntype: character\nupdatedAt: 2026-12-31T00:00:00.000Z\n---\n\n正文内容\n`,
+      updatedAt: '',
+    })
+
+    embeddingCalls.length = 0
+    const result = await buildProjectIndex(
+      makeProject([fileNode('elements/characters/a.md')]),
+      { projectId: PROJECT_ID, reason: 'incremental-update' },
+    )
+
+    expect(embeddingCalls).toHaveLength(0)
+    expect(result.skippedCount).toBe(1)
+  })
+
+  it('正文变化时重新 Embedding', async () => {
+    files.set('elements/characters/a.md', { content: elementMd('elements/characters/a.md', '甲', '旧正文'), updatedAt: '' })
+
+    await buildProjectIndex(
+      makeProject([fileNode('elements/characters/a.md')]),
+      { projectId: PROJECT_ID, reason: 'manual-rebuild' },
+    )
+
+    files.set('elements/characters/a.md', { content: elementMd('elements/characters/a.md', '甲', '全新的正文'), updatedAt: '' })
+
+    embeddingCalls.length = 0
+    const result = await buildProjectIndex(
+      makeProject([fileNode('elements/characters/a.md')]),
+      { projectId: PROJECT_ID, reason: 'incremental-update' },
+    )
+
+    expect(embeddingCalls).toHaveLength(1)
+    expect(result.skippedCount).toBe(0)
+    expect(result.indexedCount).toBe(1)
+  })
+
+  it('embedding 模型变化时即使内容相同也重算', async () => {
+    files.set('elements/characters/a.md', { content: elementMd('elements/characters/a.md', '甲'), updatedAt: '' })
+
+    await buildProjectIndex(
+      makeProject([fileNode('elements/characters/a.md')]),
+      { projectId: PROJECT_ID, reason: 'manual-rebuild' },
+    )
+
+    // 模拟旧文档是用旧模型索引的（与新配置 model 不同）。
+    for (const doc of storeState.docs.values()) {
+      doc.embeddingModel = 'old-model'
+    }
+
+    embeddingCalls.length = 0
+    const result = await buildProjectIndex(
+      makeProject([fileNode('elements/characters/a.md')]),
+      { projectId: PROJECT_ID, reason: 'incremental-update' },
+    )
+
+    expect(embeddingCalls).toHaveLength(1)
+    expect(result.skippedCount).toBe(0)
+  })
+
+  it('增量清理已删除的要素（旧文档不在新范围）', async () => {
+    files.set('elements/characters/a.md', { content: elementMd('elements/characters/a.md', '甲'), updatedAt: '' })
+    files.set('elements/characters/b.md', { content: elementMd('elements/characters/b.md', '乙'), updatedAt: '' })
+
+    await buildProjectIndex(
+      makeProject([fileNode('elements/characters/a.md'), fileNode('elements/characters/b.md')]),
+      { projectId: PROJECT_ID, reason: 'manual-rebuild' },
+    )
+
+    // 手动 seed 一个「已被删除的要素」旧文档（文件树里不再有它）。
+    storeState.docs.set(
+      `${PROJECT_ID}::gone`,
+      seedDoc({ id: 'gone', sourcePath: 'elements/characters/gone.md' }),
+    )
+    expect(storeState.docs.size).toBe(3)
+
+    await buildProjectIndex(
+      makeProject([fileNode('elements/characters/a.md'), fileNode('elements/characters/b.md')]),
+      { projectId: PROJECT_ID, reason: 'incremental-update' },
+    )
+
+    // gone 文档应被清理。
+    expect(storeState.docs.has(`${PROJECT_ID}::gone`)).toBe(false)
+    expect(storeState.removeCount).toBe(1)
+  })
+})
diff --git a/packages/core/src/core/rag/indexer.ts b/packages/core/src/core/rag/indexer.ts
index 003b300..415ae55 100644
--- a/packages/core/src/core/rag/indexer.ts
+++ b/packages/core/src/core/rag/indexer.ts
@@ -4,9 +4,10 @@ import { readProjectFile } from '../fs/project-fs'
 import { hashContent } from '../util/hash'
 
 import type { ProjectSnapshot, TreeNode } from '../../types/project'
-import type { IndexBuildRequest, IndexBuildResult, ProjectIndexMeta } from '../../types/rag'
+import type { IndexedElementDocument, IndexBuildRequest, IndexBuildResult, ProjectIndexMeta } from '../../types/rag'
 
-import { buildOramaIndex, dropOramaIndex } from './orama-index'
+import { dispatchIndexChange } from './index-events'
+import { buildOramaIndex } from './orama-index'
 import { createRagIndexStore } from './index-store'
 import { buildRetrievalText } from './retrieval-text'
 
@@ -42,16 +43,49 @@ export async function buildProjectIndex(
 
   try {
     const elementPaths = collectElementPaths(project.tree, request.sourcePaths)
+    const isFullRebuild = request.reason === 'full-rebuild' || request.reason === 'manual-rebuild' || request.reason === 'initial-build'
 
-    if (request.reason === 'full-rebuild' || request.reason === 'manual-rebuild' || request.reason === 'initial-build') {
+    if (isFullRebuild) {
       await store.clearProject(project.id)
     }
 
+    // 预拉旧文档用于 contentHash 短路：按 sourcePath 索引，命中且 hash/model/version
+    // 全一致时复用旧 vector，跳过 Embedding 调用。
+    // 全量重建已 clear，旧文档为空，短路自然失效（全部重新 embed），逻辑统一。
+    const existingDocs = isFullRebuild ? [] : await store.listProjectDocuments(project.id)
+    const existingByPath = new Map(existingDocs.map((doc) => [doc.sourcePath, doc]))
+
     const documents = []
     let embeddingDim = 0
+    let skippedCount = 0
 
     for (const path of elementPaths) {
       const file = await readProjectFile(project, path)
+      const contentHash = computeContentHash(file.content)
+      const existing = existingByPath.get(path)
+
+      // 短路：内容未变、且 embedding 模型/维度/模板版本一致 → 复用旧向量。
+      // 注意 contentHash 口径已对齐 writer 的 normalizeForComparison（排除 updatedAt 行），
+      // 因此仅刷新 updatedAt 不会误触发重算。
+      if (
+        existing
+        && existing.contentHash === contentHash
+        && existing.embeddingModel === embeddingModel
+        && existing.embeddingDim > 0
+        && existing.embeddingTextVersion === project.config.settings.embeddingTextVersion
+      ) {
+        embeddingDim = existing.embeddingDim
+        skippedCount += 1
+
+        documents.push({
+          ...existing,
+          // 这些字段随当前文件状态刷新，即使向量复用
+          sourceModifiedAt: file.updatedAt,
+          indexedAt: new Date().toISOString(),
+        })
+        continue
+      }
+
       const parsed = parseElementFile(path, file.content)
       const name = parsed.frontmatter.name || inferNameFromPath(path)
       const type = parsed.frontmatter.type || inferTypeFromPath(path)
@@ -89,7 +123,7 @@ export async function buildProjectIndex(
         tags: parsed.frontmatter.tags,
         sourceModifiedAt: file.updatedAt,
         indexedAt: new Date().toISOString(),
-        contentHash: hashContent(file.content),
+        contentHash,
         embeddingProvider,
         embeddingModel,
         embeddingDim: embedding.dimension,
@@ -99,6 +133,19 @@ export async function buildProjectIndex(
 
     await store.upsertDocuments(documents)
 
+    // 增量场景下清理已删除的要素：旧文档中 sourcePath 不在本次范围的移除。
+    // 全量重建已 clear，无需处理。
+    if (!isFullRebuild && existingDocs.length > 0) {
+      const currentPaths = new Set(elementPaths)
+      const removedIds = existingDocs
+        .filter((doc) => !currentPaths.has(doc.sourcePath))
+        .map((doc) => doc.id)
+
+      if (removedIds.length > 0) {
+        await store.removeDocuments(project.id, removedIds)
+      }
+    }
+
     // 内存 Orama 索引必须与 IndexedDB 的全量当前状态保持一致：
     // 增量更新时不 clear，IndexedDB 里是「旧 + 本次 upsert」的全集；
     // 全量重建时已 clear，IndexedDB 里就是本次 documents 全集。
@@ -108,8 +155,8 @@ export async function buildProjectIndex(
 
     const meta: ProjectIndexMeta = {
       projectId: project.id,
-      status: documents.length > 0 ? 'ready' : 'empty',
-      documentCount: documents.length,
+      status: allDocuments.length > 0 ? 'ready' : 'empty',
+      documentCount: allDocuments.length,
       embeddingProvider,
       embeddingModel,
       embeddingDim,
@@ -124,20 +171,21 @@ export async function buildProjectIndex(
     }
 
     await store.saveProjectMeta(meta)
+    dispatchIndexChange(project.id, meta)
 
     return {
       projectId: project.id,
       status: meta.status,
       indexedCount: documents.length,
-      skippedCount: 0,
+      skippedCount,
       failedCount: 0,
       message:
-        documents.length > 0
-          ? `索引构建完成，共写入 ${documents.length} 条要素文档`
+        allDocuments.length > 0
+          ? `索引构建完成，共写入 ${documents.length} 条要素文档${skippedCount > 0 ? `（复用 ${skippedCount} 条未变向量）` : ''}`
           : '索引构建完成，但当前项目下还没有可索引的要素文件',
     }
   } catch (error) {
-    await store.saveProjectMeta({
+    const errorMeta: ProjectIndexMeta = {
       projectId: project.id,
       status: 'error',
       documentCount: 0,
@@ -149,7 +197,9 @@ export async function buildProjectIndex(
       rerankModel: project.config.rerank.model || undefined,
       lastBuildAt: new Date().toISOString(),
       lastError: error instanceof Error ? error.message : '索引构建失败',
-    })
+    }
+    await store.saveProjectMeta(errorMeta)
+    dispatchIndexChange(project.id, errorMeta)
 
     throw error
   }
@@ -162,7 +212,7 @@ export async function markProjectIndexStale(
   const store = createRagIndexStore()
   const meta = await store.getProjectMeta(projectId)
 
-  await store.saveProjectMeta({
+  const updatedMeta: ProjectIndexMeta = {
     projectId,
     status: 'stale',
     documentCount: meta?.documentCount ?? 0,
@@ -175,7 +225,10 @@ export async function markProjectIndexStale(
     lastBuildAt: meta?.lastBuildAt,
     lastFullRebuildAt: meta?.lastFullRebuildAt,
     lastError: reason,
-  })
+  }
+
+  await store.saveProjectMeta(updatedMeta)
+  dispatchIndexChange(projectId, updatedMeta)
 }
 
 function collectElementPaths(tree: TreeNode[], preferredPaths?: string[]) {
@@ -243,3 +296,15 @@ function summarizeBody(body: string) {
 function createStableElementId(path: string) {
   return `element-${hashContent(path)}`
 }
+
+/**
+ * 计算用于增量比对的内容 hash。
+ *
+ * 口径与 writer.normalizeForComparison 对齐：把 frontmatter 的 updatedAt 行
+ * 归一为固定占位符后再算 hash，这样「只刷新 updatedAt」不会让 contentHash 变化，
+ * 避免要素写入时无条件触发 Embedding 重算。
+ */
+function computeContentHash(content: string) {
+  const normalized = content.replace(/^updatedAt: .*$/m, 'updatedAt: <ignored>').trim()
+  return hashContent(normalized)
+}
diff --git a/packages/core/src/services/rag-service.ts b/packages/core/src/services/rag-service.ts
index cbb88e6..1e512fa 100644
--- a/packages/core/src/services/rag-service.ts
+++ b/packages/core/src/services/rag-service.ts
@@ -1,9 +1,11 @@
 import { buildGenerationContextDraft, selectFinalContextItems } from '../core/rag/context'
 import { explainRetrievalCandidates } from '../core/rag/explain'
 import { buildProjectIndex, getProjectIndexMeta } from '../core/rag/indexer'
+import { onRagIndexChange } from '../core/rag/index-events'
 import { rerankRetrievalCandidates } from '../core/rag/rerank'
 import { searchRagCandidates } from '../core/rag/search'
 
+import type { ProjectIndexMeta } from '../types/rag'
 import { requireRuntimeProject } from './project-runtime'
 import type {
   GenerationContextDraftView,
@@ -17,12 +19,36 @@ export async function inspectIndex(projectId: string): Promise<ProjectIndexMetaV
   return getProjectIndexMeta(projectId)
 }
 
-export async function rebuildIndex(projectId: string): Promise<IndexBuildResultView> {
+/**
+ * 订阅某个项目的索引状态变化（要素写入标 stale / 重建完成 / 构建失败等）。
+ * 返回取消订阅函数。事件总线封装在 core 层，app 层通过本函数统一访问。
+ */
+export function subscribeIndexChange(
+  projectId: string,
+  callback: (meta: ProjectIndexMetaView) => void,
+): () => void {
+  // core 层事件用的是内部 ProjectIndexMeta，结构与 view 等价，直接透传。
+  const wrapped = (meta: ProjectIndexMeta) => callback(meta)
+  return onRagIndexChange(projectId, wrapped)
+}
+
+/**
+ * 重建索引。
+ *
+ * 不传 sourcePaths 时为全量重建（manual-rebuild，会 clearProject）；
+ * 传 sourcePaths 时为增量重建（incremental-update，不清空，且 buildProjectIndex
+ * 内部会用 contentHash 短路复用未变文档的向量，只对变更文件调 Embedding）。
+ */
+export async function rebuildIndex(
+  projectId: string,
+  sourcePaths?: string[],
+): Promise<IndexBuildResultView> {
   const project = requireRuntimeProject(projectId)
 
   return buildProjectIndex(project, {
     projectId,
-    reason: 'manual-rebuild',
+    reason: sourcePaths && sourcePaths.length > 0 ? 'incremental-update' : 'manual-rebuild',
+    sourcePaths,
   })
 }
 

From a58e6d5f6f30159047aa047990eced022699e246 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 20:51:38 +0800
Subject: [PATCH 32/36] =?UTF-8?q?docs(docs):=20=E6=9B=B4=E6=96=B0=20docs?=
 =?UTF-8?q?=20=E5=AD=90=E6=A8=A1=E5=9D=97=E5=90=8C=E6=AD=A5=20RAG=20?=
 =?UTF-8?q?=E7=B4=A2=E5=BC=95=E7=8A=B6=E6=80=81=E6=A0=8F=E8=90=BD=E5=9C=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs b/docs
index 7899cac..243e8eb 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit 7899cacbfadbed7afb2b427c6cb49ec882205b75
+Subproject commit 243e8ebb9507efd71407b7d6a307f1a0dc13316a

From f10dd02d78c326e17da90ebb7b24527d226be1b5 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Sat, 20 Jun 2026 21:09:27 +0800
Subject: [PATCH 33/36] =?UTF-8?q?docs(docs):=20=E5=90=88=E5=B9=B6=20Orama?=
 =?UTF-8?q?=20=E4=B8=8E=E7=8A=B6=E6=80=81=E6=A0=8F=E6=96=87=E6=A1=A3?=
 =?UTF-8?q?=E5=88=86=E6=94=AF=E5=88=B0=20docs=20=E5=AD=90=E6=A8=A1?=
 =?UTF-8?q?=E5=9D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs b/docs
index 243e8eb..efaf783 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit 243e8ebb9507efd71407b7d6a307f1a0dc13316a
+Subproject commit efaf783281350fede697ff8070170eaf03965dc0

From e21f883fd8c17fbe56ac103aa97889c5ce28a5a2 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Mon, 22 Jun 2026 23:13:36 +0800
Subject: [PATCH 34/36] =?UTF-8?q?feat(project):=20=E7=8A=B6=E6=80=81?=
 =?UTF-8?q?=E6=A0=8F=E6=8E=A5=E5=85=A5=20runStatus=20=E4=B8=8E=E5=9C=BA?=
 =?UTF-8?q?=E6=99=AF=E6=8F=90=E7=A4=BA=E8=AF=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- chat store 新增 runStatusType 状态机（idle/running/error），收口所有 runStatus 赋值点，UI 不再靠字符串匹配上色
- IndexStatusBar 升级为项目状态栏：左侧新增紧凑场景指示（📍 名称 ×，无壳内联），右侧新增本轮执行状态并按 type 上色
- ChatPanel 移除输入框上方 SceneChip 与底部 runStatus 行，清理 activeSceneName prop
- ProjectView 删除 watch runStatus 弹 toast（状态栏已常驻展示，重复）
---
 .../app/src/components/layout/ChatPanel.vue   |  13 +--
 .../src/components/layout/IndexStatusBar.vue  | 108 ++++++++++++++----
 packages/app/src/stores/chat.ts               |  45 +++++---
 packages/app/src/views/ProjectView.vue        |  23 ++--
 4 files changed, 126 insertions(+), 63 deletions(-)

diff --git a/packages/app/src/components/layout/ChatPanel.vue b/packages/app/src/components/layout/ChatPanel.vue
index dba7764..5bfe07b 100644
--- a/packages/app/src/components/layout/ChatPanel.vue
+++ b/packages/app/src/components/layout/ChatPanel.vue
@@ -6,7 +6,6 @@ import { shouldSubmitOnEnter } from '../../composables/keyboard'
 import { useElementExtraction, type ChapterPick } from '../../composables/useElementExtraction'
 import MessageItem from '../chat/MessageItem.vue'
 import SelectionChip from '../chat/SelectionChip.vue'
-import SceneChip from '../chat/SceneChip.vue'
 import SceneCommandPopover from '../chat/SceneCommandPopover.vue'
 import ChapterPicker from '../chat/ChapterPicker.vue'
 import ExtractionFlowPanel from '../chat/ExtractionFlowPanel.vue'
@@ -30,8 +29,6 @@ const props = defineProps<{
   scenes: ProjectFileNodeView[]
   /** 当前激活的场景路径，null 表示未激活 */
   activeScenePromptPath: string | null
-  /** 当前激活场景的显示名（已去扩展名），chip 展示用 */
-  activeSceneName: string | null
   /** 章节列表（chapters/*.txt|.md），供 /提取要素 选择（R6） */
   chapters: ProjectFileNodeView[]
 }>()
@@ -422,19 +419,14 @@ async function handleExtractionConfirm() {
     <!-- 输入区域 -->
     <div class="border-t border-gray-200 bg-white px-4 py-3">
       <div class="mx-auto max-w-3xl">
-        <!-- chip 区：引用 chip + 场景 chip -->
-        <div v-if="quote || activeSceneName" class="mb-2 flex flex-wrap items-center gap-2">
+        <!-- chip 区：引用 chip（场景 chip 已移至底部状态栏） -->
+        <div v-if="quote" class="mb-2 flex flex-wrap items-center gap-2">
           <SelectionChip
             v-if="quote"
             :file-name="quote.name"
             :text="quote.text"
             @remove="emit('clearQuote')"
           />
-          <SceneChip
-            v-if="activeSceneName"
-            :scene-name="activeSceneName"
-            @remove="emit('changeScene', null)"
-          />
         </div>
         <div class="relative flex gap-2">
           <!-- @场景 指令弹层（R4） -->
@@ -508,7 +500,6 @@ async function handleExtractionConfirm() {
             </svg>
           </button>
         </div>
-        <p class="mt-1 text-xs text-gray-500">{{ chatStore.runStatus }}</p>
       </div>
     </div>
   </section>
diff --git a/packages/app/src/components/layout/IndexStatusBar.vue b/packages/app/src/components/layout/IndexStatusBar.vue
index 9ccb1e7..5b697d1 100644
--- a/packages/app/src/components/layout/IndexStatusBar.vue
+++ b/packages/app/src/components/layout/IndexStatusBar.vue
@@ -3,17 +3,33 @@ import { computed } from 'vue'
 
 import Tooltip from '../ui/Tooltip.vue'
 import { useIndexStore, getIndexStatusDotClass, getIndexStatusLabel } from '../../stores/index'
+import type { RunStatusType } from '../../stores/chat'
 import type { IndexStatusView } from '@novai/core/services/types'
 
 /**
- * 底部常驻 RAG 索引状态栏。
+ * 底部常驻项目状态栏。
+ *
+ * 三段式布局（h-7 矮栏，与 VS Code 风格一致）：
+ * - 左：RAG 索引状态（项目层，慢变）。stale/error 可点击触发增量重建。
+ * - 左：当前激活场景提示词（项目层）。无壳内联样式，点 × 关闭。
+ * - 右：本轮 Agent 执行状态（会话层，瞬时）。按 type 上色（idle/running/error）。
  *
  * - 随项目激活时由 ProjectView 注入 projectId 并触发 init
  * - 索引状态变化（要素写入标 stale / 重建完成）通过事件总线自动反映
- * - stale / error 可点击触发增量重建（省 API：未变文件复用旧向量）
  */
 const props = defineProps<{
   projectId: string
+  /** 当前激活场景的显示名（已去扩展名），null 表示未激活 */
+  activeSceneName: string | null
+  /** 本轮执行状态文案（来自 chatStore.runStatus） */
+  runStatus: string
+  /** runStatus 的语义类型，用于上色 */
+  runStatusType: RunStatusType
+}>()
+
+const emit = defineEmits<{
+  /** 关闭当前激活场景（走 changeScene(null)） */
+  clearScene: []
 }>()
 
 const indexStore = useIndexStore()
@@ -21,8 +37,8 @@ const indexStore = useIndexStore()
 const status = computed<IndexStatusView | null>(() => indexStore.status)
 const isBusy = computed(() => indexStore.isBusy)
 
-/** 主文案：状态 + 项数。 */
-const label = computed(() => {
+/** 索引主文案：状态 + 项数。 */
+const indexLabel = computed(() => {
   if (!status.value) {
     return '索引未初始化'
   }
@@ -71,13 +87,29 @@ const tooltipText = computed(() => {
   return parts.join('\n') || '点击查看索引详情'
 })
 
-function handleClick() {
+/** runStatus 按 type 上色：error 红、running 蓝、idle 灰。 */
+const runStatusClass = computed(() => {
+  switch (props.runStatusType) {
+    case 'error':
+      return 'text-red-500'
+    case 'running':
+      return 'text-blue-500'
+    default:
+      return 'text-gray-500'
+  }
+})
+
+function handleIndexClick() {
   if (!actionable.value) {
     return
   }
   indexStore.rebuild(props.projectId)
 }
 
+function handleClearScene() {
+  emit('clearScene')
+}
+
 function formatTime(iso: string) {
   try {
     return new Date(iso).toLocaleString('zh-CN', { hour12: false })
@@ -89,25 +121,57 @@ function formatTime(iso: string) {
 
 <template>
   <div
-    class="flex h-7 shrink-0 items-center gap-2 border-t border-gray-200 bg-gray-50 px-3 text-xs text-gray-600"
+    class="flex h-7 shrink-0 items-center gap-3 border-t border-gray-200 bg-gray-50 px-3 text-xs text-gray-600"
   >
-    <Tooltip
-      :text="tooltipText"
-      preferred-placement="top"
-      multiline
-    >
-      <button
-        type="button"
-        class="flex items-center gap-1.5 rounded px-1.5 py-0.5 transition-colors"
-        :class="actionable ? 'cursor-pointer hover:bg-gray-200 hover:text-gray-900' : 'cursor-default'"
-        :disabled="!actionable"
-        @click="handleClick"
+    <!-- 左侧：项目层状态（索引 + 场景） -->
+    <div class="flex min-w-0 items-center gap-3">
+      <!-- 索引状态 -->
+      <Tooltip
+        :text="tooltipText"
+        preferred-placement="top"
+        multiline
+      >
+        <button
+          type="button"
+          class="flex items-center gap-1.5 rounded px-1.5 py-0.5 transition-colors"
+          :class="actionable ? 'cursor-pointer hover:bg-gray-200 hover:text-gray-900' : 'cursor-default'"
+          :disabled="!actionable"
+          @click="handleIndexClick"
+        >
+          <span :class="['h-2 w-2 rounded-full', dotClass]" />
+          <span>{{ indexLabel }}</span>
+        </button>
+      </Tooltip>
+
+      <!-- 当前激活场景（紧凑内联，无壳）：📍 名称 × -->
+      <div
+        v-if="activeSceneName"
+        class="flex min-w-0 items-center gap-1 text-green-600"
+        title="当前场景提示词"
       >
-        <span :class="['h-2 w-2 rounded-full', dotClass]" />
-        <span>{{ label }}</span>
-      </button>
-    </Tooltip>
+        <span class="shrink-0">📍</span>
+        <span class="truncate font-medium">{{ activeSceneName }}</span>
+        <button
+          type="button"
+          class="shrink-0 rounded p-0.5 text-green-500 transition-colors hover:bg-green-200 hover:text-green-800"
+          title="关闭场景"
+          @click="handleClearScene"
+        >
+          <svg class="h-3 w-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2.5" d="M6 18L18 6M6 6l12 12" />
+          </svg>
+        </button>
+      </div>
+    </div>
 
-    <span v-if="indexStore.errorMessage" class="text-red-500">{{ indexStore.errorMessage }}</span>
+    <!-- 右侧：会话层执行状态 -->
+    <div class="ml-auto flex items-center gap-2">
+      <span v-if="indexStore.errorMessage" class="text-red-500">{{ indexStore.errorMessage }}</span>
+      <span
+        class="truncate"
+        :class="runStatusClass"
+        :title="runStatus"
+      >{{ runStatus }}</span>
+    </div>
   </div>
 </template>
diff --git a/packages/app/src/stores/chat.ts b/packages/app/src/stores/chat.ts
index 04cd24a..0664a9a 100644
--- a/packages/app/src/stores/chat.ts
+++ b/packages/app/src/stores/chat.ts
@@ -24,11 +24,16 @@ import type {
 
 import { useProjectStore } from './project'
 
+/** runStatus 的语义类型，供状态栏按类型上色，避免 UI 靠字符串猜测 */
+export type RunStatusType = 'idle' | 'running' | 'error'
+
 export const useChatStore = defineStore('chat', () => {
   const sessionView = ref<ChatSessionView | null>(null)
   const agentEvents = ref<AgentUiEvent[]>([])
   const changedFiles = ref<ChangedFileView[]>([])
   const runStatus = ref('还没有开始执行。')
+  // runStatus 的语义类型，供状态栏按类型上色（idle 灰 / running 蓝 / error 红）
+  const runStatusType = ref<RunStatusType>('idle')
   const isRunning = ref(false)
   // 用户已请求停止、正在等待当前工具执行完成
   const isStopping = ref(false)
@@ -174,7 +179,7 @@ export const useChatStore = defineStore('chat', () => {
 
     agentEvents.value = []
     changedFiles.value = []
-    runStatus.value = '正在执行本轮 Agent...'
+    setRunStatus('正在执行本轮 Agent...', 'running')
     isRunning.value = true
     isStopping.value = false
 
@@ -194,13 +199,15 @@ export const useChatStore = defineStore('chat', () => {
 
       sessionView.value = result.session
       changedFiles.value = result.changedFiles
-      runStatus.value = result.changedFiles.length > 0
-        ? `本轮执行完成，变更 ${result.changedFiles.length} 个文件`
-        : '本轮执行完成，未修改任何文件'
+      setRunStatus(
+        result.changedFiles.length > 0
+          ? `本轮执行完成，变更 ${result.changedFiles.length} 个文件`
+          : '本轮执行完成，未修改任何文件',
+      )
 
       return result
     } catch (error) {
-      runStatus.value = error instanceof Error ? error.message : '执行会话失败'
+      setRunStatus(error instanceof Error ? error.message : '执行会话失败', 'error')
       throw error
     } finally {
       isRunning.value = false
@@ -222,19 +229,24 @@ export const useChatStore = defineStore('chat', () => {
       activeAbortController = null
       // 立即进入「停止中」态：UI 反馈 + 等待当前工具完成
       isStopping.value = true
-      runStatus.value = '已请求停止，等待当前工具执行完成…'
+      setRunStatus('已请求停止，等待当前工具执行完成…', 'running')
     }
   }
 
-  function setRunStatus(nextStatus: string) {
+  /**
+   * 统一的 runStatus 写入入口：同时设置文案与语义类型，
+   * UI（状态栏）按 type 上色，无需靠字符串匹配。
+   */
+  function setRunStatus(nextStatus: string, type: RunStatusType = 'idle') {
     runStatus.value = nextStatus
+    runStatusType.value = type
   }
 
   function handleAgentEvent(event: AgentUiEvent) {
     agentEvents.value = [...agentEvents.value, event]
 
     if (event.type === 'run-start') {
-      runStatus.value = 'Agent 正在执行...'
+      setRunStatus('Agent 正在执行...', 'running')
       return
     }
 
@@ -253,21 +265,23 @@ export const useChatStore = defineStore('chat', () => {
 
     if (event.type === 'confirmation-required') {
       pendingConfirmation.value = event.request
-      runStatus.value = '等待确认写入操作…'
+      setRunStatus('等待确认写入操作…')
       return
     }
 
     if (event.type === 'run-error') {
-      runStatus.value = event.error.message
+      setRunStatus(event.error.message, 'error')
       return
     }
 
     if (event.type === 'run-finish') {
       sessionView.value = event.result.session
       changedFiles.value = event.result.changedFiles
-      runStatus.value = event.result.changedFiles.length > 0
-        ? `本轮执行完成，变更 ${event.result.changedFiles.length} 个文件`
-        : '本轮执行完成，未修改任何文件'
+      setRunStatus(
+        event.result.changedFiles.length > 0
+          ? `本轮执行完成，变更 ${event.result.changedFiles.length} 个文件`
+          : '本轮执行完成，未修改任何文件',
+      )
     }
   }
 
@@ -295,7 +309,7 @@ export const useChatStore = defineStore('chat', () => {
     }
     pendingConfirmation.value = null
     respondAgentConfirmation(confirmation.id, true)
-    runStatus.value = 'Agent 正在执行...'
+    setRunStatus('Agent 正在执行...', 'running')
   }
 
   /** 用户拒绝当前待确认的写操作，Agent 收到拒绝结果后可调整。 */
@@ -306,7 +320,7 @@ export const useChatStore = defineStore('chat', () => {
     }
     pendingConfirmation.value = null
     respondAgentConfirmation(confirmation.id, false)
-    runStatus.value = 'Agent 正在执行...'
+    setRunStatus('Agent 正在执行...', 'running')
   }
 
   return {
@@ -321,6 +335,7 @@ export const useChatStore = defineStore('chat', () => {
     sessions,
     activeSessionId,
     runStatus,
+    runStatusType,
     hasSessionView,
     abortRun,
     confirmWriteTool,
diff --git a/packages/app/src/views/ProjectView.vue b/packages/app/src/views/ProjectView.vue
index 9235998..fe8ed87 100644
--- a/packages/app/src/views/ProjectView.vue
+++ b/packages/app/src/views/ProjectView.vue
@@ -124,18 +124,6 @@ watch(
   },
 )
 
-// 监听运行状态，显示 Toast 提示
-watch(
-  () => chatStore.runStatus,
-  (status) => {
-    if (status.includes('执行完成')) {
-      toast.success(status)
-    } else if (status.includes('失败') || status.includes('错误')) {
-      toast.error(status)
-    }
-  },
-)
-
 // 切换文件时清空选中引用（引用绑定当前文件，避免跨文件残留）
 watch(
   () => projectStore.activeFile?.path,
@@ -283,7 +271,6 @@ async function handleElementsWritten() {
         :quote="selectionQuote"
         :scenes="sceneList"
         :active-scene-prompt-path="activeScenePromptPath"
-        :active-scene-name="activeSceneName"
         :chapters="chapterList"
         @toggle-sidebar="toggleSidebar"
         @toggle-content-panel="toggleContentPanel"
@@ -316,8 +303,14 @@ async function handleElementsWritten() {
       />
     </div>
 
-    <!-- 底部 RAG 索引状态栏（常驻，随项目激活） -->
-    <IndexStatusBar :project-id="projectId" />
+    <!-- 底部项目状态栏：索引状态 + 当前场景 + 本轮执行状态（常驻，随项目激活） -->
+    <IndexStatusBar
+      :project-id="projectId"
+      :active-scene-name="activeSceneName"
+      :run-status="chatStore.runStatus"
+      :run-status-type="chatStore.runStatusType"
+      @clear-scene="handleChangeScene(null)"
+    />
 
     <!-- 设置模态框（按需挂载：关闭时销毁，再次打开重新读取磁盘配置） -->
     <SettingsModal

From f980e782e37dfc5a95edf9384cfbb878ec3ad170 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Mon, 22 Jun 2026 23:14:19 +0800
Subject: [PATCH 35/36] =?UTF-8?q?refactor(app):=20=E5=88=A0=E9=99=A4?=
 =?UTF-8?q?=E6=97=A0=E5=BC=95=E7=94=A8=E7=9A=84=20SceneChip=20=E7=BB=84?=
 =?UTF-8?q?=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

场景提示词展示已移至 IndexStatusBar，该组件无引用方，清理掉。
---
 .../app/src/components/chat/SceneChip.vue     | 34 -------------------
 1 file changed, 34 deletions(-)
 delete mode 100644 packages/app/src/components/chat/SceneChip.vue

diff --git a/packages/app/src/components/chat/SceneChip.vue b/packages/app/src/components/chat/SceneChip.vue
deleted file mode 100644
index 769669e..0000000
--- a/packages/app/src/components/chat/SceneChip.vue
+++ /dev/null
@@ -1,34 +0,0 @@
-<script setup lang="ts">
-/**
- * 场景激活态 chip（R4）。
- *
- * 与引用 SelectionChip 区分：📍 图标 + 绿色调，表示当前对话应用的场景提示词。
- * 常驻于输入框上方，点 × 关闭场景（走 changeScene(null)）。
- */
-defineProps<{
-  sceneName: string
-}>()
-
-const emit = defineEmits<{
-  remove: []
-}>()
-</script>
-
-<template>
-  <div
-    class="inline-flex max-w-full items-center gap-1.5 rounded-md border border-green-300 bg-green-50 px-2 py-1 text-xs text-green-700"
-  >
-    <span class="shrink-0">📍</span>
-    <span class="truncate font-medium">{{ sceneName }}</span>
-    <button
-      type="button"
-      class="shrink-0 rounded p-0.5 text-green-500 transition-colors hover:bg-green-200 hover:text-green-800"
-      title="关闭场景"
-      @click="emit('remove')"
-    >
-      <svg class="h-3 w-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2.5" d="M6 18L18 6M6 6l12 12" />
-      </svg>
-    </button>
-  </div>
-</template>

From a730025310087ccb9356d0965917c362efc29005 Mon Sep 17 00:00:00 2001
From: honlnk <jihongshen1@outlook.com>
Date: Tue, 23 Jun 2026 00:07:47 +0800
Subject: [PATCH 36/36] =?UTF-8?q?feat(project):=20=E5=BC=95=E5=85=A5=20pro?=
 =?UTF-8?q?mpts/NovAI.md=20=E9=A1=B9=E7=9B=AE=E6=80=BB=E8=A7=88=E4=B8=8E?=
 =?UTF-8?q?=20/=E7=94=9F=E6=88=90=E9=A1=B9=E7=9B=AE=E8=AE=B0=E5=BF=86=20?=
 =?UTF-8?q?=E5=91=BD=E4=BB=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

项目级累积记忆，对齐 Claude Code /init 模式：斜杠命令是一段驱动 prompt，
完全复用现有 Agent Loop 扫描项目并生成/更新项目总览，不做后台自动更新。

注入侧（每轮自动读到 NovAI.md）:
- core/fs/project-fs.ts: 新增 readNovAiOverview（照 readScenePrompt 模式，缺失返回空串）
- core/agent/prompt.ts: buildAgentSystemPrompt 加 novaiOverview 参，按
  user system prompt → 项目总览 → 场景提示词 顺序拼可变头部
- types/chat.ts + services/agent-service.ts + chat/session.ts: ChatTurnInput
  新增 novaiOverview 字段并一路透传到 buildAgentMessages 与 runChatTurn 两处
  buildAgentSystemPrompt 调用；复用 Step 6 hash 刷新机制，NovAI.md 变化即刷新

初始化与修复:
- core/project/defaults.ts: 新增 DEFAULT_NOVAI_OVERVIEW 空骨架（段落结构与
  驱动 prompt 的生成结构对齐，便于手动与自动两种维护方式衔接）
- core/fs/project-fs.ts: createProject 写骨架、repairProject 温和补齐
  （不纳入 inspectProject 强制检测，避免给旧项目报缺失）

触发侧（/生成项目记忆 斜杠命令）:
- app/constants/slash-commands.ts: 注册命令
- core/agent/init-novel-prompt.ts: 驱动 prompt（Phase 化：扫描 → 生成 → 汇报，
  照搬 Claude Code 删掉这行会犯错吗 质量判据，约束已存在文件先 ReadFile
  再 EditFile 不静默覆盖）
- services/agent-service.ts: re-export INIT_NOVEL_PROMPT
- app/components/layout/ChatPanel.vue: 选中命令后 sendMessage(INIT_NOVEL_PROMPT)

UI 入口:
- app/components/category/PromptList.vue: 新增项目总览块，显式渲染 prompts/NovAI.md
  （原 PromptList 用硬编码白名单只认 system.md 和 scenes/，NovAI.md 在根目录被漏掉）

测试: 新增 prompt.test.ts 7 用例（注入/段落顺序/空白兜底/hash 变化/固定规则保留）；
全量 104 测试通过，typecheck 零错误

对应决策 0004（推翻 0003），详见 docs submodule 更新
---
 docs                                          |  2 +-
 .../src/components/category/PromptList.vue    | 29 +++++++++
 .../app/src/components/layout/ChatPanel.vue   |  8 +++
 packages/app/src/constants/slash-commands.ts  |  8 ++-
 .../core/src/core/agent/init-novel-prompt.ts  | 49 ++++++++++++++
 packages/core/src/core/agent/prompt.test.ts   | 65 +++++++++++++++++++
 packages/core/src/core/agent/prompt.ts        | 27 ++++----
 packages/core/src/core/chat/session.ts        |  4 ++
 packages/core/src/core/fs/project-fs.ts       | 24 ++++++-
 packages/core/src/core/project/defaults.ts    | 45 +++++++++++++
 packages/core/src/services/agent-service.ts   | 12 +++-
 packages/core/src/types/chat.ts               |  2 +
 12 files changed, 260 insertions(+), 15 deletions(-)
 create mode 100644 packages/core/src/core/agent/init-novel-prompt.ts
 create mode 100644 packages/core/src/core/agent/prompt.test.ts

diff --git a/docs b/docs
index efaf783..6235aa2 160000
--- a/docs
+++ b/docs
@@ -1 +1 @@
-Subproject commit efaf783281350fede697ff8070170eaf03965dc0
+Subproject commit 6235aa206510e9926799118c13034df03c38c1ad
diff --git a/packages/app/src/components/category/PromptList.vue b/packages/app/src/components/category/PromptList.vue
index ef16827..c0c2ce7 100644
--- a/packages/app/src/components/category/PromptList.vue
+++ b/packages/app/src/components/category/PromptList.vue
@@ -29,6 +29,13 @@ const systemPrompt = computed<ProjectFileNodeView | null>(() => {
   ) ?? null
 })
 
+/** 项目总览：prompts/NovAI.md。每轮注入到 system prompt 的项目级累积记忆，可手动编辑或用 /生成项目记忆 刷新 */
+const novaiOverview = computed<ProjectFileNodeView | null>(() => {
+  return promptRootChildren.value.find(
+    n => n.kind === 'file' && n.path === 'prompts/NovAI.md',
+  ) ?? null
+})
+
 /** 场景提示词：prompts/scenes/ 目录下的所有 .md 文件（拉平） */
 const scenePrompts = computed<ProjectFileNodeView[]>(() => {
   const sceneChildren = pickDirectoryChildren(props.files, 'prompts/scenes')
@@ -69,6 +76,28 @@ function isSceneActive(path: string): boolean {
         </p>
       </div>
 
+      <!-- 项目总览 -->
+      <div class="mb-2">
+        <p class="px-2 py-1 text-xs font-medium uppercase tracking-wide text-gray-500">项目总览</p>
+        <button
+          v-if="novaiOverview"
+          :class="[
+            'flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-sm transition-colors',
+            novaiOverview.path === activeFilePath
+              ? 'bg-white/15 text-white'
+              : 'text-gray-400 hover:bg-white/10 hover:text-gray-200',
+          ]"
+          @click="emit('selectFile', novaiOverview.path)"
+        >
+          <span class="shrink-0">📋</span>
+          <span class="truncate">{{ novaiOverview.name }}</span>
+          <span class="ml-auto shrink-0 text-xs text-gray-500">恒注入</span>
+        </button>
+        <p v-else class="px-2 py-2 text-xs text-gray-600">
+          未找到项目总览（prompts/NovAI.md）
+        </p>
+      </div>
+
       <!-- 场景提示词 -->
       <div>
         <p class="px-2 py-1 text-xs font-medium uppercase tracking-wide text-gray-500">场景提示词</p>
diff --git a/packages/app/src/components/layout/ChatPanel.vue b/packages/app/src/components/layout/ChatPanel.vue
index 5bfe07b..6aae26a 100644
--- a/packages/app/src/components/layout/ChatPanel.vue
+++ b/packages/app/src/components/layout/ChatPanel.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { computed, nextTick, ref, watch } from 'vue'
 import type { ProjectFileNodeView } from '@novai/core/services/types'
+import { INIT_NOVEL_PROMPT } from '@novai/core/services/agent-service'
 import { useChatStore } from '../../stores/chat'
 import { shouldSubmitOnEnter } from '../../composables/keyboard'
 import { useElementExtraction, type ChapterPick } from '../../composables/useElementExtraction'
@@ -286,6 +287,13 @@ function handleSlashCommandSelect(id: SlashCommandId) {
   if (id === 'extract') {
     // 选中「提取要素」后展开章节多选
     isChapterPickerOpen.value = props.chapters.length > 0
+    return
+  }
+
+  if (id === 'init') {
+    // 选中「生成项目记忆」后，把驱动 prompt 直接作为用户意图发送，由 Agent 扫描项目并生成/更新 prompts/NovAI.md。
+    // 不需要二级交互界面，复用普通对话发送链路。
+    void chatStore.sendMessage(INIT_NOVEL_PROMPT)
   }
 }
 
diff --git a/packages/app/src/constants/slash-commands.ts b/packages/app/src/constants/slash-commands.ts
index 6158e88..af3b6ad 100644
--- a/packages/app/src/constants/slash-commands.ts
+++ b/packages/app/src/constants/slash-commands.ts
@@ -5,7 +5,7 @@
  * 每个命令选中后展开对应的二级交互界面（目前只有 extract）。
  * 后续可扩展 /校对、/整理 等。
  */
-export type SlashCommandId = 'extract'
+export type SlashCommandId = 'extract' | 'init'
 
 export type SlashCommand = {
   /** 命令唯一标识 */
@@ -26,4 +26,10 @@ export const SLASH_COMMANDS: SlashCommand[] = [
     description: '从章节中提取人物、地点、剧情等要素',
     icon: '✨',
   },
+  {
+    id: 'init',
+    label: '/生成项目记忆',
+    description: '扫描项目生成/更新 prompts/NovAI.md 项目总览',
+    icon: '📋',
+  },
 ]
diff --git a/packages/core/src/core/agent/init-novel-prompt.ts b/packages/core/src/core/agent/init-novel-prompt.ts
new file mode 100644
index 0000000..8415b98
--- /dev/null
+++ b/packages/core/src/core/agent/init-novel-prompt.ts
@@ -0,0 +1,49 @@
+/**
+ * /生成项目记忆 斜杠命令的驱动 prompt。
+ *
+ * 设计参照 Claude Code 的 /init 命令：斜杠命令本身不是扫描程序，而是一段注入对话的指令，
+ * 完全复用现有 Agent 循环和工具（ListDirectory / FindFiles / ReadFile / RagSearch / CreateFile / EditFile）。
+ * 选中 /生成项目记忆 后，这段文本作为用户意图发送，由模型自主扫描项目并生成或更新 prompts/NovAI.md。
+ *
+ * 与代码项目不同，小说项目的“总览”是创作维度的：章节进度、人物、伏笔、世界观、风格约定，
+ * 而不是 build/test/lint 命令。扫描目标因此改为 chapters/、elements/、prompts/ 和 RagSearch 语义召回。
+ */
+export const INIT_NOVEL_PROMPT = `请初始化并更新本小说项目的项目总览文件 prompts/NovAI.md。
+
+项目总览是项目级累积记忆，每轮 Agent 运行都会读取它作为上下文。它的作用是让 Agent 在任何一轮都知道“这部书写到哪了、有哪些人物和设定、哪些伏笔待回收、风格约定是什么”，而不必每次从零翻文件。
+
+请按下面的阶段执行。
+
+## 阶段 1：扫描项目，盘点现状
+
+先用工具摸清项目当前状态，不要凭空编造：
+
+- 用 ListDirectory 查看 chapters/、elements/、prompts/ 的目录结构，了解有哪些章节和要素。
+- 用 FindFiles（模式 chapters/*.txt）盘点已写章节的数量和命名规律。
+- 用 ReadFile 精读最近 2~3 章正文，掌握当前主线走向、最新出场人物和未解决的冲突。
+- 如果项目已有要素索引，用 RagSearch 按自然语言召回主要人物、地点、实体、剧情、世界观设定和已埋设的伏笔；对召回结果里有价值的 sourcePath 再用 ReadFile 精读补全。
+- 用 ReadFile 读取 prompts/system.md，了解已有的文风、人称、视角、格式约定。
+- 如果 prompts/NovAI.md 已存在，必须先用 ReadFile 读取它的现有内容，避免覆盖用户手动维护的部分。
+
+## 阶段 2：生成或更新 prompts/NovAI.md
+
+根据阶段 1 的发现，把项目总览写入 prompts/NovAI.md。必须包含以下段落，每段只写能从项目内容推导出来的事实：
+
+- 作品概述：一句话简介（logline）、题材类型（如玄幻/武侠/都市/科幻）、当前状态（连载中/已完结/停更）。
+- 章节进度：已完成章节数、当前主线（最近在推进什么剧情）、当前卡点或待解决的冲突。
+- 主要人物：列出已出场的主要人物，每人附核心身份、核心动机和当前的剧情弧光位置。只写已登场角色，不写计划中尚未出场的。
+- 世界观速览：作品涉及的核心世界观设定（时代背景、势力格局、修行或能力体系等）。只写已经在章节里建立起来的设定。
+- 伏笔追踪：列出已埋设但尚未回收的伏笔，以及已回收的伏笔。如果项目里还看不出明确伏笔，写“暂无明确伏笔”，不要编造。
+- 风格约定：从 system.md 和正文里总结的叙事人称、时态、文风倾向、禁用词或格式习惯。
+
+## 写作要求
+
+- 写文件用 CreateFile（文件不存在时）或 EditFile（文件已存在、阶段 1 已读取过原文时）。不要用 CreateFile 覆盖已存在的文件。
+- 如果 prompts/NovAI.md 已存在，基于阶段 1 读取的原文做增量 EditFile：只更新有变化的段落，保留用户手动维护、且仍然准确的内容。不要静默整篇覆盖。
+- 每一行都要经得起这个检验：“删掉这行，Agent 下一轮会不会犯错或不知情？”——经不起的就删掉。不要写“请保持剧情连贯”这类对谁都成立、对谁都没用的废话。
+- 不要把整章正文或大段原文复制进总览。总览是状态地图和索引，不是正文仓库。
+- 全部使用中文。
+
+## 阶段 3：简要汇报
+
+写完文件后，用简短的自然语言说明：本次扫描发现了多少章节和要素、更新或新建了哪些段落、有没有发现需要用户确认的不确定信息（例如无法判断某伏笔是否已回收）。不要在聊天里重复输出整个 NovAI.md 文件内容。`
diff --git a/packages/core/src/core/agent/prompt.test.ts b/packages/core/src/core/agent/prompt.test.ts
new file mode 100644
index 0000000..c27d441
--- /dev/null
+++ b/packages/core/src/core/agent/prompt.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+
+import { buildAgentSystemPrompt } from './prompt'
+import { hashContent } from '../util/hash'
+
+describe('buildAgentSystemPrompt', () => {
+  it('falls back to default opening when no variable inputs given', () => {
+    const prompt = buildAgentSystemPrompt()
+    expect(prompt).toContain('你是 NovAI')
+    // 项目总览 / 场景提示词段落不应出现
+    expect(prompt).not.toContain('项目总览')
+    expect(prompt).not.toContain('当前场景提示词')
+  })
+
+  it('injects novaiOverview into the prompt when provided', () => {
+    const prompt = buildAgentSystemPrompt({ novaiOverview: '这是一部武侠小说，主角是云溪。' })
+    expect(prompt).toContain('项目总览')
+    expect(prompt).toContain('这是一部武侠小说，主角是云溪。')
+  })
+
+  it('injects scenePrompt into the prompt when provided', () => {
+    const prompt = buildAgentSystemPrompt({ scenePrompt: '本章场景：鸿家庄灭门之夜' })
+    expect(prompt).toContain('当前场景提示词')
+    expect(prompt).toContain('本章场景：鸿家庄灭门之夜')
+  })
+
+  it('places novaiOverview before scenePrompt in the variable head', () => {
+    const prompt = buildAgentSystemPrompt({
+      novaiOverview: '总览占位 ABC',
+      scenePrompt: '场景占位 XYZ',
+    })
+    const overviewIndex = prompt.indexOf('总览占位 ABC')
+    const sceneIndex = prompt.indexOf('场景占位 XYZ')
+    expect(overviewIndex).toBeGreaterThan(-1)
+    expect(sceneIndex).toBeGreaterThan(-1)
+    // 项目总览（相对稳定的项目记忆）应在最具体的场景提示词之前
+    expect(overviewIndex).toBeLessThan(sceneIndex)
+  })
+
+  it('treats whitespace-only novaiOverview as absent', () => {
+    const prompt = buildAgentSystemPrompt({ novaiOverview: '   \n  ' })
+    expect(prompt).not.toContain('项目总览')
+  })
+
+  it('produces different hash when novaiOverview changes', () => {
+    // 这是 systemPromptHash 刷新机制的关键：NovAI.md 内容变化 → system prompt 文本变化 → hash 变化 → 下一轮刷新。
+    const withoutOverview = buildAgentSystemPrompt({ systemPrompt: '文风：冷峻' })
+    const withOverview = buildAgentSystemPrompt({
+      systemPrompt: '文风：冷峻',
+      novaiOverview: '主角已觉醒第二形态',
+    })
+    expect(hashContent(withoutOverview)).not.toBe(hashContent(withOverview))
+  })
+
+  it('always appends the fixed working principles regardless of inputs', () => {
+    const prompt = buildAgentSystemPrompt({
+      systemPrompt: '自定义',
+      novaiOverview: '总览',
+      scenePrompt: '场景',
+    })
+    // 固定规则文本（工具使用原则）必须在所有变量输入之后
+    expect(prompt).toContain('工作原则')
+    expect(prompt).toContain('要素分组规则')
+  })
+})
diff --git a/packages/core/src/core/agent/prompt.ts b/packages/core/src/core/agent/prompt.ts
index 522c8b3..162ded1 100644
--- a/packages/core/src/core/agent/prompt.ts
+++ b/packages/core/src/core/agent/prompt.ts
@@ -5,21 +5,26 @@ import { describeActivePolicy, type ToolPolicy } from './tool-policy'
 export function buildAgentSystemPrompt(input: {
   systemPrompt?: string
   scenePrompt?: string
+  novaiOverview?: string
 } = {}) {
   const userPrompt = input.systemPrompt?.trim()
   const scenePrompt = input.scenePrompt?.trim()
+  const overview = input.novaiOverview?.trim()
 
-  const head = scenePrompt
-    ? [
-        userPrompt || '你是 NovAI，一个通过工具读写本地小说项目文件的写作 Agent。',
-        '',
-        '---',
-        '',
-        '【当前场景提示词】',
-        '',
-        scenePrompt,
-      ].join('\n')
-    : userPrompt || '你是 NovAI，一个通过工具读写本地小说项目文件的写作 Agent。'
+  // 拼装可变头部：用户 system.md → 项目总览(NovAI.md) → 当前场景提示词。
+  // 项目总览是项目级累积记忆（写到哪了、人物、伏笔），相对稳定；
+  // 场景提示词是本轮最具体的上下文，放在最末。两者之后才是固定的 Agent 工作原则。
+  const headParts: string[] = [userPrompt || '你是 NovAI，一个通过工具读写本地小说项目文件的写作 Agent。']
+
+  if (overview) {
+    headParts.push('', '---', '', '【项目总览（prompts/NovAI.md）】', '', overview)
+  }
+
+  if (scenePrompt) {
+    headParts.push('', '---', '', '【当前场景提示词】', '', scenePrompt)
+  }
+
+  const head = headParts.join('\n')
 
   return [
     head,
diff --git a/packages/core/src/core/chat/session.ts b/packages/core/src/core/chat/session.ts
index cdf6e9a..fa0a87b 100644
--- a/packages/core/src/core/chat/session.ts
+++ b/packages/core/src/core/chat/session.ts
@@ -86,6 +86,7 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
   const newSystemContent = buildAgentSystemPrompt({
     systemPrompt: input.systemPrompt,
     scenePrompt: input.scenePrompt,
+    novaiOverview: input.novaiOverview,
   })
   const newSystemHash = hashContent(newSystemContent)
   if (session.agentMessages && session.systemPromptHash !== newSystemHash) {
@@ -99,6 +100,7 @@ export async function runChatTurn(options: RunChatTurnOptions): Promise<ChatTurn
     quote: input.quote,
     systemPrompt: input.systemPrompt,
     scenePrompt: input.scenePrompt,
+    novaiOverview: input.novaiOverview,
     project: input.project,
     target,
     toolPolicy: input.toolPolicy,
@@ -476,6 +478,7 @@ function buildAgentMessages(input: {
   quote?: string
   systemPrompt: string
   scenePrompt?: string
+  novaiOverview?: string
   project: ChatTurnInput['project']
   target: ChatTargetContext | null
   toolPolicy?: ChatTurnInput['toolPolicy']
@@ -501,6 +504,7 @@ function buildAgentMessages(input: {
       content: buildAgentSystemPrompt({
         systemPrompt: input.systemPrompt,
         scenePrompt: input.scenePrompt,
+        novaiOverview: input.novaiOverview,
       }),
     },
     nextUserMessage,
diff --git a/packages/core/src/core/fs/project-fs.ts b/packages/core/src/core/fs/project-fs.ts
index ad6068b..c694a8b 100644
--- a/packages/core/src/core/fs/project-fs.ts
+++ b/packages/core/src/core/fs/project-fs.ts
@@ -1,4 +1,4 @@
-import { createDefaultConfig, createDefaultManifest, DEFAULT_CONFIG, DEFAULT_SCENE_PROMPT, DEFAULT_SYSTEM_PROMPT } from '../project/defaults'
+import { createDefaultConfig, createDefaultManifest, DEFAULT_CONFIG, DEFAULT_NOVAI_OVERVIEW, DEFAULT_SCENE_PROMPT, DEFAULT_SYSTEM_PROMPT } from '../project/defaults'
 
 import type {
   ProjectInspection,
@@ -52,6 +52,7 @@ export async function createProject(projectName: string): Promise<ProjectSnapsho
   await writeJson(rootHandle, '.novel/manifest.json', createDefaultManifest(projectId))
   await writeText(rootHandle, 'prompts/system.md', DEFAULT_SYSTEM_PROMPT)
   await writeText(rootHandle, 'prompts/scenes/scene-001.md', DEFAULT_SCENE_PROMPT)
+  await writeText(rootHandle, 'prompts/NovAI.md', DEFAULT_NOVAI_OVERVIEW)
 
   return loadProjectFromHandle(rootHandle)
 }
@@ -164,6 +165,12 @@ export async function repairProject(
     await writeText(rootHandle, 'prompts/system.md', DEFAULT_SYSTEM_PROMPT)
   }
 
+  // 项目总览 NovAI.md 缺失时补空骨架。它是可选文件（缺失时读取返回空串，Agent 仍能正常工作），
+  // 因此不纳入 inspectProject 的强制检测项，只在这里温和补齐，避免给所有旧项目报“缺失”。
+  if (!(await pathExists(rootHandle, 'prompts/NovAI.md', 'file'))) {
+    await writeText(rootHandle, 'prompts/NovAI.md', DEFAULT_NOVAI_OVERVIEW)
+  }
+
   return loadProjectFromHandle(rootHandle)
 }
 
@@ -379,6 +386,21 @@ export async function readScenePrompt(
   }
 }
 
+/**
+ * 读取项目总览 `prompts/NovAI.md`。
+ *
+ * 该文件是项目级创作记忆，作用类似 Claude Code 的 CLAUDE.md：
+ * 每轮 Agent 运行时注入到 system prompt，让模型知道“写到哪了、有哪些人物、哪些伏笔待回收”。
+ * 文件缺失时返回空字符串，不抛错（旧项目或被删除的项目）。
+ */
+export async function readNovAiOverview(rootHandle: FileSystemDirectoryHandle): Promise<string> {
+  try {
+    return await readText(rootHandle, 'prompts/NovAI.md')
+  } catch {
+    return ''
+  }
+}
+
 /**
  * 写回项目中的 `prompts/system.md`。
  */
diff --git a/packages/core/src/core/project/defaults.ts b/packages/core/src/core/project/defaults.ts
index 892d0c8..cbca06e 100644
--- a/packages/core/src/core/project/defaults.ts
+++ b/packages/core/src/core/project/defaults.ts
@@ -13,6 +13,51 @@ export const DEFAULT_SCENE_PROMPT = `# Scene Prompt
 
 在这里为具体章节记录本场景目标、冲突、登场人物与氛围。`
 
+/**
+ * 项目总览 prompts/NovAI.md 的默认骨架。
+ *
+ * 作用类似 Claude Code 的 CLAUDE.md：项目级累积记忆，每轮注入到 Agent 的 system prompt。
+ * 它回答“写到哪了、有哪些人物、哪些伏笔待回收、风格约定是什么”，让 Agent 不必每轮从零重建项目上下文。
+ *
+ * 新建项目时写入空骨架，用户可手动补充，或用 /生成项目记忆 让 Agent 扫描后填充。
+ * 段落结构应与 init-novel-prompt.ts 的生成结构保持一致，便于手动与自动两种维护方式无缝衔接。
+ */
+export const DEFAULT_NOVAI_OVERVIEW = `# 项目总览（NovAI.md）
+
+这是本小说项目的项目级记忆。每轮 Agent 运行都会读取它作为上下文，让它知道“写到哪了、有哪些人物和设定、哪些伏笔待回收”。
+可以手动编辑，也可以在输入框用 /生成项目记忆 让 Agent 扫描全项目后自动更新。
+
+## 作品概述
+
+- 一句话简介：待补充
+- 题材类型：待补充
+- 当前状态：待补充
+
+## 章节进度
+
+- 已完成章节：待补充
+- 当前主线：待补充
+- 当前卡点：待补充
+
+## 主要人物
+
+- 待补充
+
+## 世界观速览
+
+- 待补充
+
+## 伏笔追踪
+
+- 已埋设：待补充
+- 已回收：待补充
+
+## 风格约定
+
+- 叙事人称：待补充
+- 时态：待补充
+- 文风：待补充`
+
 export const DEFAULT_CONFIG = {
   version: 1,
   project: {
diff --git a/packages/core/src/services/agent-service.ts b/packages/core/src/services/agent-service.ts
index 6de075b..a237658 100644
--- a/packages/core/src/services/agent-service.ts
+++ b/packages/core/src/services/agent-service.ts
@@ -11,12 +11,19 @@ import {
   listSessionMetas,
 } from '../core/chat/session-store'
 import { deriveChatTargetFromPath } from '../core/chat/target'
-import { readScenePrompt, readSystemPrompt } from '../core/fs/project-fs'
+import { readNovAiOverview, readScenePrompt, readSystemPrompt } from '../core/fs/project-fs'
 import type { ConfirmHandler } from '../core/agent/tool-execution'
 import { parseToolPolicy } from '../core/agent/tool-policy'
+import { INIT_NOVEL_PROMPT } from '../core/agent/init-novel-prompt'
 import type { FileChange, WriteConfirmation } from '../core/tools/types'
 import type { ChatMessage, ChatSessionState, ChatTargetContext } from '../types/chat'
 
+/**
+ * /生成项目记忆 斜杠命令的驱动 prompt。
+ * app 层通过 services 入口导入，选中命令后作为用户意图发送给 Agent，由 Agent 扫描项目并生成/更新 prompts/NovAI.md。
+ */
+export { INIT_NOVEL_PROMPT }
+
 import {
   requireRuntimeProject,
 } from './project-runtime'
@@ -247,6 +254,8 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
       project.handle,
       project.config.settings.activeScenePromptPath,
     )
+    // 项目总览（prompts/NovAI.md）：每轮注入 system prompt，让 Agent 知道写到哪了、有哪些人物和伏笔。
+    const novaiOverview = await readNovAiOverview(project.handle)
     // 写工具确认回调：构造预览 → 发 confirmation-required 事件 → 等 UI 调 respondConfirmation。
     const confirm: ConfirmHandler | undefined = input.onEvent
       ? (request) => requestConfirmation(input.projectId, request, input.onEvent!)
@@ -263,6 +272,7 @@ export async function runTurn(input: RunAgentTurnInput): Promise<RunAgentTurnRes
         config: project.config,
         systemPrompt,
         scenePrompt,
+        novaiOverview,
         activeFilePath: input.activeFilePath,
         signal: input.signal,
         confirm,
diff --git a/packages/core/src/types/chat.ts b/packages/core/src/types/chat.ts
index dfd395f..37b728e 100644
--- a/packages/core/src/types/chat.ts
+++ b/packages/core/src/types/chat.ts
@@ -140,6 +140,8 @@ export type ChatTurnInput = {
   config: ProjectConfig
   systemPrompt: string
   scenePrompt?: string
+  /** 项目总览（prompts/NovAI.md），每轮注入到 system prompt 的项目级累积记忆。 */
+  novaiOverview?: string
   activeFilePath?: string | null
   /** 用户停止信号，透传到 Agent Loop。 */
   signal?: AbortSignal