# CONTEXT 本项目领域术语表。只收录术语与含义，不含实现细节。 ## 术语 ### 主题（Topic） 笔记的唯一归类维度，扁平一层。创建入口在首页标题栏、侧栏主题列表底部与 设置 → 主题管理，三处共用同一接口。其中**未分类**是系统内置主题，不可删除、不可重命名。删除普通主题时，其下笔记回落到未分类。 ### 未分类 / 收件箱（Inbox） 同一事物的两个称呼：AI 拿不准归属的笔记暂存地，也是主题建议的素材池。 ### 删除（笔记） 删除即移入**回收站**（软删除）：笔记随即从列表、搜索、计数与 AI 流水线中消失，30 天内可恢复。只有「彻底删除」——在回收站手动执行，或满 30 天被自动清扫——才物理删除且不可恢复。 ### 回收站（Trash） 已删除笔记的暂存地，入口在 设置 → 数据。保留期固定 30 天，到期随每日清扫彻底删除；清扫只在每日备份成功之后执行（先备份后销毁），并顺带回收孤儿图片（以全库正文引用为准判定，新上传图片有 24 小时宽限期）与失去归属对象的 AI 会话。恢复时搜索索引重建，被打断的 AI 整理自动重新入队。删除主题时，其回收站笔记与正常笔记一样回落到未分类。相关决策见 [docs/adr/0007-soft-delete-trash.md](docs/adr/0007-soft-delete-trash.md)。 ### 导出（Export） 把全部有效笔记（不含回收站）打包为 zip 下载：目录结构为 `主题名/标题-id.md`，frontmatter 携带 id/主题/标签/时间/摘要，被引用的图片集中放在顶层 `assets/`，正文图片引用改写为相对路径。入口在 设置 → 数据。 ### 导入（Import） 从 zip 批量写入笔记。自家导出包按 id 恢复主题、标签、时间、摘要与图片；普通 Markdown 的标题按 front-matter `title`、首个 H1、文件名依次推断，主题按 `topic`、`category`、直接父目录依次推断。没有 id 时用文件内容指纹判重：同一内容重复导入会跳过，内容变化则保守地视为新笔记。默认不跑 AI 整理。 ### 锁字段（Locked） 笔记的主题/标题/标签任一字段被用户手动修改过即"上锁"，AI 后续处理不再覆盖该字段。 ### AI 状态（aiStatus） 笔记的 AI 处理进度：pending（待整理）→ processing（整理中）→ done / failed / skipped。失败可手动"重新处理"。 ### AI 任务队列 数据库持久化的异步任务队列，由同进程的轮询 worker 消费，重启不丢任务。 ### 手写摄取 单张手写图片可追加到已有笔记并进入 `handwriting_transcribe` 队列；原图保留在正文中，转写结果以“待核对”块追加，完成后再进入 `note_process`。独立新笔记入口复用同一任务。视觉调用期间若正文发生变化，结果保存为候选稿，用户明确接受后才追加。 ### 转写审核状态与公式块 笔记独立记录 `unreviewed/reviewed/needs_review` 转写审核状态及告警。数学公式使用 `$...$`/`$$...$$` Markdown 源码，阅读态 KaTeX 渲染，源码始终可导出和往返编辑。 ### 主题建议 未分类笔记积攒后，AI 聚类产出的"新建/归入主题"建议，用户可逐条采纳或全部忽略。采纳是**逐项**的：只消费当前这一项，其余建议继续待处理，其中已被迁走的笔记自动剔除，剩不到 2 条笔记的建议随之作废（同一条笔记可能同时出现在多个候选主题里）。 ### 体验模式（Demo） 零门槛的产品演示形态：应用带着一组内置演示数据与本地模拟 AI 启动，无需任何 API Key。仅在显式开启且数据库为空时生效，演示数据与正式数据完全隔离；演示中的 AI 判断按关键词模拟，不代表真实模型效果。 ### LLM 配置 调用 AI 服务所需的接入点（base URL）、API Key、模型名三元组。读取顺序：**设置页保存的值（数据库）优先，环境变量兜底**；超时时间仅由环境变量控制。相关决策见 [docs/adr/0001-llm-config-in-db.md](docs/adr/0001-llm-config-in-db.md)。 ### Embedding 配置 语义检索专用的第五组模型配置（`embedding_base_url` / `embedding_api_key` / `embedding_model`）。三项必须全部显式配置，**不回落**文本 LLM；供应商需提供 OpenAI 兼容的 `/embeddings` 接口。笔记保存单笔记单向量，模型标识与维度随向量落库；模型变更时旧向量只参与 BM25，补算完成后才重新参与语义检索。 ### 视觉模型（Vision） AI 读图专用的第二组 LLM 配置（`vision_base_url` / `vision_api_key` / `vision_model`）。接入点与 Key 留空时回落文本模型配置；仅在显式配置了视觉模型名时"AI 看图"功能才可用。发送前只在内存中生成高质量 WebP 副本，原图不变；最多 6 张，并按单图与总字节双重限额，避免 Base64 多图请求触发代理防火墙。视觉回答可由用户直接存成新笔记。相关决策见 [docs/adr/0013-vision-image-payload.md](docs/adr/0013-vision-image-payload.md)。 ### 图像模型（Image） AI 画图专用的第三组 LLM 配置（`image_base_url` / `image_api_key` / `image_model`），回落语义同视觉模型。未配置模型名时助手不下发生图工具。 ### 深度思考（Deep Thinking） 助手输入框上的**消息级开关**：本次消息改用第四组独立配置的推理模型（`reasoning_base_url` / `reasoning_api_key` / `reasoning_model`）作答，回落语义同视觉模型。开关**不持久化**，每条消息重置——推理模型贵且慢，不该被无意间一直开着。深度思考只是「换一个更强的模型」，**工具能力不缩水**：知识库工具照常下发，能不能用由它自己那份探测结论决定，与文本模型的结论互不干涉（两者常常不是同一家供应商）。请求超时放宽到 300 秒并省略 `temperature`（推理模型普遍拒绝该参数）。相关决策见 [docs/adr/0015-deep-thinking-tools-and-trace.md](docs/adr/0015-deep-thinking-tools-and-trace.md)。 ### 思考过程（Reasoning Trace） 推理模型在给出答案前吐出的推演文本。三种线格式都认：`reasoning_content`、`reasoning`、以及内联在正文里的 `…`。随消息落库，在回答上方以折叠栏呈现——模型还在想时自动展开，正文一开始吐就自动收起。**绝不回灌进后续请求的上下文**（供应商明确要求，带上会 400 拒绝整个请求），「存为新笔记」时也不带上。 ### AI 助手（Assistant） 全局的对话式入口：任意页面右下角均可唤起，面向整个知识库，可通过**工具调用**检索与改写笔记。当前打开的笔记/主题以**上下文附件**形式带入，可随时摘除。会话与消息持久化，回答走 SSE 流式并按 Markdown 渲染（走与笔记同一套**正文排版层**，不套气泡）；模型不支持工具调用时自动降级为纯问答。桌面端面板是三栏布局最右的一栏：打开时把正文**推窄而不是盖住**，与侧栏一样贴顶、自身高一屏，宽度可拖拽调整并记住；因此它不是模态，没有遮罩，也没有「点外部关闭」，关闭走 ✕、`Esc` 或 `⌘J`。手机端仍是覆盖全屏的浮层。输入框上另有**看图**与**深度思考**两个消息级开关，各自切到对应的独立模型。相关决策见 [docs/adr/0008-assistant-tool-calling.md](docs/adr/0008-assistant-tool-calling.md)（上下文注入时期的决策见 [docs/adr/0003-chat-context-injection.md](docs/adr/0003-chat-context-injection.md)）。 笔记编辑页在正文稳定输入后，会在桌面侧栏展示最多 8 条混合检索相关笔记；已配置聊天模型时，另做一次候选内冲突判断。该辅助请求失败不影响正文编辑与保存，模型返回的冲突笔记 ID 必须来自真实召回候选。详见 [docs/adr/0022-writing-related-notes.md](docs/adr/0022-writing-related-notes.md)。 ### 工具调用（Tool Calling） 助手读写知识库的唯一途径，共 9 个：检索笔记、读取全文、列出主题、新建笔记、追加内容、修改元数据、删除笔记、抓取网页、生成图片。**不存在覆盖正文的工具**——项目不做版本历史，正文覆盖是唯一不可恢复的操作。单次对话最多 8 轮、每轮最多 20 个调用。`fetch_url` 只能抓取用户消息中出现过的网址，相关决策见 [docs/adr/0009-fetch-url-safety.md](docs/adr/0009-fetch-url-safety.md)；`generate_image` 每条用户消息最多 2 次，见 [docs/adr/0011-image-generation.md](docs/adr/0011-image-generation.md)。 ### 正文续读 长笔记通过 `read_note` 分次读取正文。每次读取都给出下一段的位置或读完标记，并重新遵守来源集与回收站边界。未读到末尾或受对话预算限制时，只能说明尚未完成读取，不能把未读到的内容断言为笔记中不存在。续读不修改正文，也不创建正文快照。 ### 上下文附件（Context Attachment） 挂在助手面板顶部的一份当前材料：用户正在看的笔记或主题。摘除后助手面向全库。它是**会话创建时的上下文快照**，不再是会话的归属维度——会话列表按最近更新倒序列出全部，不按附件切分，旧会话标注「围绕 XX」。与**来源集**的区别：附件跟着页面自动来去、只是给助手的一份参考材料，助手仍可自由使用全库与自身知识；来源集是用户显式挑定的知识边界，一旦设定，整场会话都受**严格接地**约束。二者互斥，来源问答期间不带附件。 ### 来源问答（Grounded Chat） 一种会话类型：用户先挑一组笔记/主题作为**来源集**，整场对话都遵守**严格接地**。可从助手面板新建，也可在笔记页/主题页用「以此为来源提问」直接以当前对象开启。来源集在会话进行中可随时增删，改动从下一条消息起生效，已产生的回答不追溯重算。 ### 来源集（Source Set） 来源问答里用户勾选的笔记与主题的集合，单个成员称**来源**。来源集属于某场会话，不是可复用的独立实体。主题作为来源时是**活引用**——之后新增到该主题的笔记自动进入来源范围，而非选定时刻的快照。回收站中的笔记仍留在来源集里但不参与回答，恢复后自动重新生效。 ### 严格接地（Strict Grounding） 来源问答的会话级不变量：回答只能依据来源集中的内容，来源里没有的一律回答「来源笔记中没有相关内容」，不用模型自身知识补充。**用户在对话中要求破例也不放行**，只能新建一场普通对话——允许例外就等于用户再也无法确信任何一条回答是否真的出自他的笔记。为此该模式下不提供抓取网页的能力（外部内容不属于来源），检索与读取工具也被限定在来源集范围内。 ### 操作卡片（Action Card） 助手每执行一次写操作，在对话中留下的一张卡片：写明改动内容，并提供撤销按钮。重开会话时按落库的撤销载荷重建。撤销失败（笔记已被改动、已不存在）时按钮置灰并显示原因。 ### 确认卡片（Confirmation Card） 执行前必须由用户点「允许 / 拒绝」的卡片，**仅用于删除笔记**——其余写操作直接执行、事后撤销。卡片上写的是笔记标题而非 id。拒绝后助手会接着回应，不留悬空调用。 ### 状态指纹（Fingerprint） 撤销时的乐观锁判据：对该工具真正改动过的字段做哈希，与写入时的值比对，不一致即视为「笔记已被改动」，撤销按钮置灰。**不能用 `updatedAt` 代替**——后台 AI 处理完成时会自行刷新它，助手新建的笔记几秒后就会永远撤销不了。 ### 引用溯源（Citation） 助手在结论后标注的 `[^noteId]`，渲染为可跳转对应笔记的上标链接。**只有工具真的返回过的 id 才渲染成链接**，模型编造的 id 保持纯文本，不生成打不开的死链。来源问答中，来源集里的笔记同样放行——它们的正文直接进入上下文，没有经过工具。 ### 富文本图片属性 笔记中调整过宽度/对齐/说明的图片，以内嵌 HTML `` 形式存于 Markdown 正文，与纯 Markdown 图片 `![alt](url)` 混存。相关决策见 [docs/adr/0002-image-attrs-inline-html.md](docs/adr/0002-image-attrs-inline-html.md)。 ### 图像生成（Image Generation） 助手按描述画图并落盘为笔记图片的能力。生成结果以卡片呈现，可「插入当前笔记」或「存为新笔记」。**不设确认卡片**（仅删除需确认这条不变量不破例），改以每条用户消息最多 2 张封顶——失败也计数，防「再试一次」绕过。生成卡片没有撤销按钮：文件能删，那次调用的钱撤不回。来源问答中禁用。相关决策见 [docs/adr/0011-image-generation.md](docs/adr/0011-image-generation.md)。 ### 每周回顾（Weekly Review） 每周一凌晨把上一自然周（周一至周日）新建的笔记梳理成一篇脉络回顾，产物是一条普通笔记，归入自动创建的普通主题「每周回顾」。默认开启，设置页可关，另有「立即生成上周回顾」手动补。调度不是日历定时器而是**每小时对表**：settings 记已安排的周，进入新的一周即入队，因此停机期间错过的周开机后会自动补上。空周不产报告。按服务器本地时区分周（容器默认 UTC，需设 `TZ`）。相关决策见 [docs/adr/0012-weekly-review.md](docs/adr/0012-weekly-review.md)。 ### Mermaid 图表 笔记正文中语言标为 `mermaid` 的代码块，在编辑器里渲染成图：光标离开时出图，点图或把光标移进去变回源码，渲染失败则显示源码与错误。存储形态仍是原生 Markdown 代码块，导出后 Obsidian 等工具可直接读。助手回答里只当普通代码块显示，不出图。 ### 正文排版层（Prose） 笔记编辑器与助手回答共用的唯一一套正文排版：段落间距、标题上下留白、列表节奏、等宽代码块、约 40 字的行宽上限。颜色与圆角全部取自既有设计 token，因此暗色自动跟随。共用而非各写一份，是为了不让两处排版漂移。相关决策见 [docs/adr/0016-shared-prose-layer.md](docs/adr/0016-shared-prose-layer.md)。 ### 斜杠命令（Slash Command） 在笔记正文输入 `/` 唤出的块级插入菜单：标题、列表、引用、代码块、Mermaid 图、表格、分隔线。斜杠须在块首或紧跟空白才触发，`and/or` 这类正常输入不受影响。 ### FTS 影子表 笔记的全文搜索索引副本。删除、修改或移入回收站时必须同步更新，否则搜索会出现"幽灵结果"；回收站中的笔记不在索引内，恢复时重建。