QMAI/.agents/AGENTS.md

项目基本逻辑

产品定位

QMAI 是长篇小说记忆型 AI 写作桌面系统（Tauri 2 + React 19 + TypeScript），不是普通聊天写作工具。目标场景：200 万～300 万字连载，解决 AI 遗忘前文、人设崩坏、时间线混乱、伏笔丢失。

核心理念：写前自动提取上下文 → 写后自动沉淀章节记忆 → 图谱追踪关系变化 → 审查防崩坏 → 人工确认定稿。

核心工作流（不可违背）

1. 写前：buildContextPack() 组装上下文包，按优先级裁剪 token（src/lib/novel/context-engine.ts）
2. 生成：LLM 输出默认为草稿，不写入正式记忆库
3. 写后：用户确认正式保存 → ingestChapter() 章节摄取 → 生成快照 JSON + 更新向量索引 + 增量更新图谱
4. 审查：六维审稿 + 连贯性 Lint + 角色一致性检查，草稿隔离直到人工确认

上下文包优先级

用户指定 > 章节细纲 > 上一章结尾 > Canon 正史 > 人物状态 > 伏笔 > 最近摘要 > 正文片段 > 图谱 > 向量/关键词检索

修改上下文逻辑时，保持 SECTION_PRIORITY 顺序，并考虑 token 预算二次裁剪。

代码分层

层级	路径	职责
UI	src/components/	React 组件，不含核心业务
状态	src/stores/	Zustand（wiki-store、review-store 等）
小说引擎	src/lib/novel/	记忆、上下文、摄取、审查、图谱、拆书
通用工具	src/lib/	LLM 客户端、搜索、嵌入、持久化
后端	src-tauri/	文件系统、向量存储、进程

小说相关逻辑优先放 src/lib/novel/，通过 mod.ts 导出；不要散落在 UI 组件里。

数据与隔离原则

• 本地存储：项目目录 = Markdown（章节正文）+ JSON（快照/状态）+ LanceDB（向量）
• 草稿 ≠ 正式章节：未确认内容不得触发摄取、不得污染记忆库
• 角色认知（knows / does_not_know）必须在校验和上下文中保持一致
• 图谱节点/边来自章节摄取快照，增量更新而非全量重建

改动时的检查清单

• 是否破坏草稿隔离？
• 是否影响上下文包优先级或 token 预算？
• 正式章节保存路径是否仍触发摄取 pipeline？
• 新增 LLM 调用是否走 resolveNovelModel() / resolveReviewModel()？
• UI 改动是否只需调 store，而非复制业务逻辑？