xtl/llm-wiki

Fork 0

Files

T

admin 9dd41afd48 first

2026-07-12 21:26:08 +08:00

103 KiB

Raw Blame History

llm-wiki-agent 产品文档

本文档是项目的思路锚点。当你（作者）或任何 AI 协作者思路断裂时，先读这份文档恢复上下文，再继续动手。

维护原则：决策或功能定义变化时，先改文档，再改代码。文档与实现冲突时以文档为准。

0. 这份文档怎么用

作者是 0 代码基础的产品设计者。开发由 AI 协作完成。
文档不写代码细节，只写意图、约定、决策理由。
每个章节相对独立，可以单独读。
章节末尾若有 ❗ 标记，表示"动手前一定要看这里"。

1. 产品定位

1.1 一句话定位

本地运行的知识库工作台。以对话为中心，通过 @ 引用知识库内容、/ 调用工具能力，把对话沉淀为可读可分享的产物（笔记、HTML、PPT、Word 等）。

1.2 核心场景

用户打开 llm-wiki-agent，看到自己的若干知识库列表，选一个进入。在对话框里和 agent 对话：

agent 知道当前在哪个知识库里，可以基于该库内容回答问题
输入 @ 弹出页面列表，引用具体 wiki 页面进 prompt
输入 / 弹出命令列表，调用工具（搜索、消化新素材、生成 HTML/PPT/Doc）
对话结束后一键"结晶"为新的 wiki 页面，写回知识库
产出物（HTML/PPT/Doc）在右抽屉直接预览，一键下载或分享

整个工具运行在本地，所有知识库数据是本地 markdown 文件，零云依赖。

1.3 与 llm-wiki-skill 的关系

维度	llm-wiki-skill（旧）	llm-wiki-agent（新）
形态	Anthropic Skill	独立 agent + web UI（未来 Tauri 桌面应用）
宿主	Claude Code / Codex / OpenClaw / Hermes	自有 runtime（基于 pi-agent）
数据	用户的 wiki 目录	完全沿用，结构不变
能力	Skill 内的脚本 + 模板	全部复用，agent 通过 pi-agent 原生 Skill 加载机制调用

关键事实：pi-agent 原生实现 Anthropic Skill 标准。llm-wiki-skill 一行不改就能被 agent 项目加载使用。

长期愿景（ADR-16，已由阶段四落地）：agent 形态并入 llm-wiki 仓库，作为 Skill 的升级版同时存在（保留 Skill 给纯 CLI 用户）。这次合并已在阶段四完成（见下）；本节保留 ADR-16 的原始意图脉络。

合并已完成（阶段四）：原 agent 仓库已 git subtree 搬入主仓库子目录 workbench/（monorepo，不发版不宣布），图谱引擎 @llm-wiki/graph-engine 是第一块两端共享代码。终局形态为"一个产品、两扇门"——产品 = 知识库格式 + 素材管线 + 方法论；门一 = Skill（嵌入用户已有 harness），门二 = 工作台。详见 ADR-20。

1.4 这个项目"不是什么"

为防止范围漂移，明确以下边界：

❌ 不是云端 SaaS（不部署线上、不替用户付 API 费用、不做多用户）
❌ 不是 Obsidian/Logseq 替代品（不做手写笔记编辑器，wiki 由 AI 维护）
❌ 不是通用 ChatGPT（必须基于知识库语境）
❌ 不是 Skill 的"加壳版"（是独立 agent 产品，Skill 只是能力来源之一）

2. 核心理念

2.1 Code is cheap，未来人视角

不为了"省事"做妥协的选型。技术栈按 5 年后仍说得通的标准来选。

2.2 桌面应用而非托管

托管 = 替用户烧 API 额度 = 必须先想清楚商业模式。本项目不走这条路。最终形态是 Tauri 打包的桌面应用。

2.3 Skill 即插即用

不重造轮子。任何符合 Anthropic Skill 标准的能力，丢到 skills 目录就生效：

llm-wiki-skill（自家，知识库主线）
anthropics/skills（17+ 个官方 Skill：docx / pdf / pptx / xlsx / doc-coauthoring / web-artifacts-builder / frontend-design / canvas-design / brand-guidelines / theme-factory / mcp-builder / claude-api / algorithmic-art / webapp-testing / skill-creator / internal-comms / slack-gif-creator）
pi-skills（web search、browser automation、transcription 等）
未来任何社区 Skill

2.4 对话中心

主屏永远是对话框。其他功能（图谱、库管理、产出预览）作为辅助面板，从对话发起或呼出。心智参考 Codex / Claude Desktop。

3. 架构总览

3.1 系统层次

┌─────────────────────────────────────────────┐
│ 前端 (Vite + React)                          │
│  浏览器 / 未来 Tauri webview                  │
│   ├─ 对话主区                                 │
│   ├─ 侧栏（知识库列表 / 历史 / 图谱入口）       │
│   ├─ 顶栏（当前知识库 / 搜索 / 模型 / 外观 / 设置）│
│   ├─ 右抽屉（产出预览 / 引用查看）             │
│   └─ @ / 自动补全                             │
└────────────────────┬────────────────────────┘
                     │ SSE (事件流) + HTTP POST (命令)
┌────────────────────▼────────────────────────┐
│ 后端 (Node + Hono)                           │
│  └─ pi-coding-agent SDK                     │
│      ├─ AgentSession  (对话/事件/会话管理)    │
│      ├─ Extension     (注入当前知识库等状态)   │
│      └─ Skills 加载                           │
│         ├─ llm-wiki-skill                   │
│         ├─ anthropics/skills                │
│         └─ pi-skills                        │
└────────────────────┬────────────────────────┘
                     │
┌────────────────────▼────────────────────────┐
│ 本地文件系统                                  │
│   ├─ ~/llm-wiki/<name>/  (知识库默认根，沿用 Skill 结构)│
│   ├─ 外部知识库路径       (用户登记的任意路径) │
│   ├─ ~/.llm-wiki-agent/                     │
│   │   ├─ config.json     (UI 偏好/外部库登记) │
│   │   ├─ sessions/                          │
│   │   ├─ skills/                            │
│   │   └─ logs/                              │
│   └─ ~/.pi/agent/auth.json (模型凭证，pi 管理)│
└─────────────────────────────────────────────┘

3.2 技术栈

层	选型	简要理由
前端框架	React + Vite	AI 协作样本量最大；新手坑最少；Tauri 零迁移
UI 组件库	暂定 shadcn/ui	不是黑盒、可读、复制粘贴风格、深色主题原生
后端框架	Hono	轻量、TS 友好、文档清晰
Agent runtime	@earendil-works/pi-coding-agent SDK	原生 Skill 支持；事件流；多 provider
通信	SSE + HTTP POST	agent→UI 单向流，SSE 足够；WebSocket 过度
数据	本地 markdown + JSON	无服务器；Obsidian 兼容
桌面打包（未来）	Tauri	用系统 webview + Rust 后端；二进制和内存占用通常显著低于 Electron（5-30 MB vs 100+ MB）
包管理	npm（统一）	不混用 pnpm/bun，避免新手版本混乱
Node 版本管理	mise 或 nvm	mise 是多语言版本管理（含 Node）；锁版本至少 `>=22.19.0`（pi-coding-agent 0.75.x 的最低要求）
Markdown 渲染（阶段二+）	react-markdown ^9 + remark-gfm ^4	生态最稳、类型完备、GFM 表格/任务列表/自动链接；shadcn 生态常用
命令/补全菜单（阶段二+）	cmdk ^1	shadcn `<Command>` 底层；键盘导航与 a11y 完备；同时承载 `/` 命令菜单和 `@` 引用菜单

3.3 关键流程：一次对话发生了什么

下列路径（/api/refs 等）为建议命名，最终以实现为准。

1. 用户在对话框输入文本（可能含 @页面 或 /命令）
2. 前端检测到 @ → 调 /api/refs 拿当前库页面列表 → 弹出菜单 → 用户选中
3. 前端检测到 / → 调 /api/commands 拿已加载命令 → 弹出菜单 → 用户选中
4. 前端 POST /api/prompt，body 是展开后的完整文本
5. 后端调用 session.prompt(text)
6. session 通过 subscribe 推 agent 事件
7. 后端把事件 SSE 推给前端 /api/events
8. 前端按事件类型渲染（文本流、工具调用、引用预览…）
9. 用户可选触发 /sediment 把本次对话沉淀为 wiki 页面

❗ 关键点：当前知识库的"上下文"不是通过 prompt 字符串拼接传递，而是通过 pi-agent 的 Extension 注入到 session state 里。这是干净做法。具体见 ADR-7。

3.4 pi-agent 的使用方式

结论：pi-agent 作为 npm 依赖引入，不 clone 源码，不做 fork。

具体含义：

llm-wiki-agent/                       ← 你的仓库
├── package.json                      ← 这里声明 "@earendil-works/pi-coding-agent": "^x.y.z"
├── node_modules/
│   └── @earendil-works/
│       └── pi-coding-agent/          ← pi 源码自动安装在这里，只读，不改
├── server/                           ← 你写的后端
│   ├── index.ts                      ← Hono 起服务
│   ├── agent.ts                      ← import { createAgentSession } from '@earendil-works/pi-coding-agent'
│   └── extensions/                   ← 你写的 Extension
└── web/                              ← 你写的前端

你"写"的代码：

后端把 pi SDK 包装成 HTTP/SSE 接口
一个或多个 Extension（注入"当前知识库"等应用状态）
前端 UI

你"用"但不写的代码（全在 npm 包里）：

agent runtime、Skill 加载、事件流、模型管理、会话持久化

升级 pi：改 package.json 里的版本号，npm install 重跑。

Extension 注入方式：pi-coding-agent CLI 会自动发现 ~/.pi/agent/extensions/*.ts 下的全局 extension。我们是 SDK 用户，不依赖那个机制——而是把 extension 代码放在自己仓库的 server/extensions/ 下，通过 SDK 暴露的 bindExtensions() 或自定义 ResourceLoader 显式注入 session。这样 extension 跟着我们项目走，不污染用户的 ~/.pi/。

❗ 永远不要直接修改 node_modules/ 里的 pi 源码。万一极端情况需要 patch（99% 用不到），用 patch-package 做局部补丁，保持升级路径干净。

❗ pi-coding-agent 0.75.x 要求 Node >=22.19.0。用 mise/nvm 锁定到合适版本，避免系统 Node 太旧。

4. 功能阶段路线

每个阶段：目标 → 范围 → 不包含 → 验收。验收不过不进下一阶段。

阶段一：主干打通（最小可用） ✅ 已完成 2026-05-26

目标：验证"前端 ↔ 后端 ↔ pi-agent ↔ Skill ↔ 文件系统"全链路。

范围：

一行命令拉起本地服务（npm run dev 启动后端 + 前端）
浏览器打开 localhost:xxxx，看到知识库列表
- 自动扫描 ~/llm-wiki/ 下含 .wiki-schema.md 的子目录
- 支持手动"添加现有库"指向任意路径（如 ~/Documents/AI学习知识库）
- 注册过的库存在 ~/.llm-wiki-agent/config.json
点击一个知识库进入对话界面
顶部状态条显示当前知识库名
同库内支持多个并行对话，侧栏列出，"+ 新对话"按钮在顶部
切库自动保存当前对话，打开目标库最近活跃的对话
对话框可输入，流式接收 agent 回复
agent 通过 Extension 知道当前知识库路径
对话历史持久化（pi-agent SDK 原生功能）

不包含：@ 补全、/ 命令、图谱、产出能力、消化新素材、新建知识库 UI。

验收标准：

在 "AI学习知识库" 里问"这个库里有哪些主题"，agent 调用 read 工具读 index.md，给出准确回答
切到另一个库再问，对话上下文完全切换
同一库内开两个对话，互不污染
关闭浏览器再打开，自动选中最近对话，历史完整

完成情况 ✅ 2026-05-26（最终 commit dd021bc）

8 个 step commit + 2 个 review 修补 commit，详见 §10 进度追踪
范围全部交付；4 项验收标准实测全通（验收 1 实测中 agent 用 list_knowledge_base_pages Extension 工具回答，效果等价于读 index.md，更精准）
接受的妥协（不阻塞阶段二）：
- §5.2 顶部 "⚙ 设置" 按钮仅占位（disabled + tooltip）—— 完整设置面板在阶段二
- §5.1 侧栏底部"图谱入口"未实现 —— 作者要重新构思图谱设计，推迟到阶段四
- 默认模型不强制 Sonnet，沿用 pi-agent 用户设置（见 TBD-2）
启动 & 运行速查（compact 后从这里恢复上下文）：

维度	值
一行启动	`npm run dev`（从仓库根；用 `concurrently` 同时起前后端）
后端端口	`8787`（`server/src/index.ts`，Hono）
前端端口	`5180`（`web/vite.config.ts`，`strictPort: true`，冲突直接报错而非漂移）
启动耗时	~2-5s（pi ResourceLoader + `bootstrapFromConfig` 自动恢复）
默认模型	由 `~/.pi/agent/settings.json` 决定（不由本项目强制；作者当前为 `zai/glm-5.1`）
自动恢复	`selectKb` 写 `~/.llm-wiki-agent/config.json` 的 `lastUsedKbPath`，server 启动 `await bootstrapFromConfig()`
知识库	默认根 `~/llm-wiki/` + 外部登记（`config.externalKnowledgeBases[]`）
会话目录	`~/.llm-wiki-agent/sessions/<sha256-of-kb-path>/*.jsonl`（pi `SessionManager` 管理）
Extension 工具	`current_knowledge_base()` / `list_knowledge_base_pages()`（仅这俩，阶段二补 `@`/`/`/`/sediment` 等）
已知 endpoints	13 个，列表见 `server/src/index.ts` 顶部注释
Node 版本要求	`>=22.19.0`（pi-coding-agent 0.75.x 硬要求，仓库根 `.mise.toml` / `.nvmrc` 锁定）

阶段二：核心循环（@、/、结晶、消化）✅ 已完成 2026-05-27

目标：让"对话 → 沉淀"形成闭环。

范围：

@ 补全菜单：弹出当前库的页面/实体/主题列表，选中后插入 wiki 链接
/ 命令菜单：列出所有已加载 Skill 命令 + 内置命令
内置命令 /sediment：把当前对话或选中片段沉淀为 wiki/synthesis/sessions/ 下的页面
内置命令 /new-wiki：app 内新建知识库（输入名字 + 研究方向 → 调用 llm-wiki-skill 的 init 流程 → 在 ~/llm-wiki/ 下生成完整目录）
引用预览：对话里出现的 wiki 链接可点击，右抽屉打开该页面
消化新素材：把链接或文件路径丢给 agent → 触发 llm-wiki-skill 的消化流程
设置面板 UI（三层认证 + 偏好）：
- 登录方式区：检测 pi CLI auth.json 状态 / 填 API key（写入 pi 的 auth.json）/ 显示环境变量状态
- 默认模型、UI 偏好、知识库根目录、外部库管理（添加/移除）

验收标准：完整跑通——

在 app 内点"+ 新建知识库"，输入名字和方向 → 自动创建 → 出现在列表里
丢一篇文章链接 → agent 消化进库 → 在对话里基于这篇讨论 → 一键结晶为新页面 → 在 wiki/synthesis/sessions/ 目录里能看到新文件
在 UI 里填一个 Anthropic API key → 测试连接成功 → key 出现在 ~/.pi/agent/auth.json，未泄露到 ~/.llm-wiki-agent/

阶段三：产出能力（产品亮点）✅ 已完成 2026-05-27

目标：把"内容产出"做成视觉冲击力强的功能，作为产品宣传点和小白吸引力来源。

范围：

挂载 anthropics/skills 中的产出类 Skill（docx / pdf / pptx / xlsx / web-artifacts-builder 等）
挂载或自建 HTML 产出 Skill（生成单文件分享 HTML）
对话中可要求 "把这次讨论做成 PPT" / "导出为 docx" / "生成分享 HTML"
右抽屉支持预览：
- HTML 直接 iframe 展示
- PPT 用浏览器内 PPTX 渲染库（如 PPTXjs 或类似方案，具体库阶段三选型时再定）
- docx 显示元数据 + 下载按钮（不强求浏览器内渲染）
一键导出到本地下载目录

验收标准：一次对话能产出 HTML、PPT、docx 三种格式，且 UI 内可直接预览或下载。

阶段 3.5：导航 UX 重构 + 多模型子代理批量消化 ✅ 已完成 2026-05-27

背景：阶段 1-3 完成后作者实际使用 app 发现两类痛点——

导航 UX 反直觉：侧栏强行把 KB 分成默认/外部两类（与"KB = 项目"心智冲突）、对话挂在侧栏中间看不出从属、"添加现有库"靠手输绝对路径常常失败、拖入非 wiki 目录直接报错
批量消化效率低：阶段二的消化是"一次喂一篇"；TBD-2"多模型路由"也一直挂着没有承载场景——批量消化正好是

目标：

导航统一：侧栏一栏到底、KB 可展开对话子树、拖拽优先添加路径、非 wiki 目录提供"一键初始化 + 批量消化"路径
子代理批量消化：基于 pi SDK 的 createAgentSession + 多模型注册落地"消化角色 → cheap / 聊天角色 → main"双角色路由；用一个 30 行的并发控制函数调度 N 个子代理并行处理 N 个文件，通过 SSE 推送进度

范围（7 step）：

侧栏重构：统一 KB 列表 + 折叠对话子树（去 default/external 分隔）
拖拽 + 输入框双通道：HTML5 drag 先探测能否拿到真实路径，输入框兜底 + inspect 端点判定是不是 wiki
非 wiki 目录初始化引导：弹窗提示 + 就地初始化 .wiki-schema.md + index.md
多模型双角色：config.json 新增 modelRoles: { main, digest } + 设置面板选择
后端子代理批量消化框架：30 行 mapWithConcurrencyLimit + SessionManager.inMemory() + 共享 authStorage/modelRegistry
批量消化 UI + SSE 进度推送：浮窗实时显示每个子代理的"排队/进行中/完成/失败"
总验收 + UX 体感打磨

不包含：图谱（阶段四）、Tauri 打包（阶段五）、媒体创作 / 浏览器扩展（阶段后规划）、子代理嵌套 / 工作树隔离（omp 那一套）

验收标准（5 条）：

侧栏统一：KB 列表一栏到底无 default/external 分隔；点当前 KB 名可展开/收起对话子树，点未选中 KB 会切换并展开；外部 KB 用文字 badge 而非分区
拖拽添加：从 Finder 拖文件夹到 dialog 拖拽区；若浏览器暴露真实 file://，路径自动填入输入框；若不暴露，UI 明确提示用户粘贴路径（不立即提交，给用户最后修改机会）
非 wiki 兜底：拖入无 .wiki-schema.md 的目录，弹"是否初始化并批量消化"对话框；选"是"→ 后台跑 init + 子代理并行消化
多模型双角色：设置面板新增"模型分配"区，main / digest 两个角色各自的 provider+model；digest 写入 config.json 后对新批量消化立即生效，main 写入后当前主对话立即重载并使用该模型
并发消化：批量消化 10 个 .md 文件能看到 ≥3 个子代理同时跑（默认并发=3），SSE 实时推送状态，全部完成后右抽屉刷新出新增的 wiki 页面

完成情况：

侧栏已统一为一栏 KB 列表，当前 KB 可点击展开/收起对话子树，外部库用 badge 标记
添加现有库支持拖拽探测、路径输入、目录检查；非 wiki 目录可就地初始化并可接着批量消化
设置面板新增 main / digest 角色选择；digest 角色用于批量消化，main 角色用于主对话并在切换后立即刷新生效
批量消化使用 pi SDK 原生 in-memory 子会话，并发档位为 1 / 3 / 5，通过 SSE 推送进度
新增依赖：无

阶段四：monorepo 合并 + 图谱活地图 ✅ 已完成 2026-06-12

背景：两条线汇合——(1) 战略上"一个产品、两扇门"已定，ADR-16 的合并需要启动时机；(2) 图谱引擎是两端共享的第一块代码，共享代码出现即合并时机成熟的信号。原"图谱集成"目标升级为"图谱活地图"：图谱后面站着 agent，这是所有竞品图谱（只能看不能问）给不了的。

目标：

monorepo 合并（工程部分）：本仓库 git subtree 整体搬入主仓库 workbench/，引擎落 packages/graph-engine/。不发版、不改 README、不对外宣布（品牌动作留给后续阶段）
图谱活地图：共享引擎双宿主（工作台 React / Skill 离线 HTML），工作台获得活模拟 + 钉扎 + 选区提问 + 生长动画；Skill 离线 HTML 最后一步切换引擎产物，老用户白拿升级

实施结果：阶段四已在主仓库 stage-4 分支完成，8 个 Step 全部落地。总验收的自动化检查已通过；视觉一致性、深色观感和拖动手感按设计文档要求保留截图/参数证据，交由验收人做最终主观判断。

范围（8 Step）：

Step 0：monorepo 搬家 + workspace 根 + 全链路冒烟
Step 1：引擎包骨架 + helpers 纯函数 TS 化 + 测试迁移（"新骨架、旧器官"的 A 级资产）
Step 2：工作台图谱视图静态复现（安全网基线）+ 山水/墨夜主题 token
Step 3：活模拟 + 钉扎（松手即钉/双击解钉）+ 持久化（.wiki-graph-layout.json，只存钉的、路径为 key）。2026-06-19 修订：双击解钉不再作为新主路径，固定/取消固定改为明确按钮或菜单动作
Step 4：选区系统（结构化四式，砍自由套索）+ 对话联动（选区 = 批量 @）
Step 5：文件监听 + 全量重算 + diff 生长动画（diff 队列，图谱可见时消费）
Step 6：build-graph-html.sh 切换引擎产物，旧 graph-wash 模板退役
Step 7：总验收 + 墨夜主题打磨

不包含：仓库改名 / 对外发布、Tauri 打包（推迟到工作台有真实外部用户后）、跨库图谱、自由套索、增量图计算、主题商店（完整"明确不做清单"见设计文档 §8）。

验收标准（7 条，细则见设计文档 §6）：

主仓库根一行 npm run dev 起工作台，Skill 主线测试全绿，两边互不破坏
工作台图谱与旧版离线 HTML 视觉一致（静态基线截图存档）
钉扎：拖动让位流畅、松手即钉、重启还原、Obsidian 旁路修改不破坏
选区四式可用，动作随选区性质变化；"两簇为何没联系 → agent 建链 → 重算后颜色真变"全闭环
批量消化后打开图谱补播生长动画；Obsidian 手改 ~5s 内自动反映
离线 HTML 新产物双击可用、钉位生效、无提问按钮（capabilities 注入生效）
工作台浅/深切换图谱跟随山水/墨夜

阶段 4.5：图谱可用性收尾 ✅ 已合入 2026-06-14

背景：阶段四交付后作者实测暴露五类问题（画布无缩放平移、点击语义被选区提问独占致阅读路径消失、Shift 多选不可发现、无搜索/图例、节点默认卡片过胖）+ 阶段四验收对离线 HTML 功能减配的裁决（补搜索与社区聚焦；学习系统三件套不做，待真实使用后按工作台语境重新设计）。与阶段 3.5 同型：真实使用驱动的收尾阶段。

范围（优先级序）：

P0 画布导航：指针中心滚轮缩放 / 空白拖拽平移 / 双击回全图 / 小地图联动（引擎层，两端同享）
P0 点击语义重构："点击即阅读，选区即升级"——单击 = 右抽屉阅读态，选区悬浮窗取消，抽屉一容器两状态；动作映射表补"单节点"行并修复 unlinked 误触发（修订 stage-4 D6）。2026-06-19 修订：全局单击改为轻量摘要优先，完整阅读必须通过明确动作进入社区阅读
P1 图谱搜索（Cmd+F，两端）；社区聚焦列表兼图例（两端）
P1 Shift 多选失效排查 + 可发现性提示
P2 节点默认态瘦身 + hover 预览卡（一行标题 + 类型色条；类型/权重/摘要移入悬停——预览卡显示正文首段摘要，配套补偿瘦身）
抽屉阅读态瘦身定稿：去学习队列/学习路径/札记笔记/置信度列表/邻居列表，摘要迁移至 hover 预览卡；保留收纳"查看原文"；原则——��屉负责内容，图谱负责关系，派生信息不重复

明确不做：学习系统三件套、抽屉历史栈、缩放惯性、hover 摘要 tooltip、移动端触控全套。

阶段 4.6：图谱演进第一批（看清关系 + 层层聚焦 + 控制工具条）✅ 已完成 2026-06-14

背景：4.5 收尾后推进「图谱演进候选池」。spark 脑暴把候选池按"就绪度"（而非"高价值低成本"）重排，锁定方向 = 日常可用性（让在用的人更顺手），美观 / 惊艳 demo 后移。详见 docs/graph-evolution-1-design.md。

当前状态：已落地并通过总验收。工作台与离线 HTML 同享顶部工具条、社区聚焦、类型筛选、关系边图例；关系边按关系类型着色、按置信度虚实；离线 HTML 不提供提问入口。

范围：

G1-1 关系类型上边（数据管线补齐关系类型 + 置信度；颜色 = 关系类型、矛盾避 ENTITY 红；虚实 = 置信度；全局低权重、聚焦才完整呈现）
G1-2 递进聚焦（点社区进聚焦视图 → 点节点高亮 + 阅读）+ 类型筛选
G1-3 顶部控制工具条取代左上角常驻浮层
G1-4 默认收起 + 半透明
G1-5 双宿主分工（离线 HTML 同享，无 onAsk 提问）

明确不做：路径查找 + 讲解、lint 上图、导出美图 / 工作台实时美观、时间筛选（缺 mtime）、图谱增强检索（移交 ADR-19）、远期池（嵌入布局 / LLM 推断边 / AI 摘要）。

实施：L 级 phased plan 已完成（P0 基线+完整边契约+web test 入口 → P1 工具条 → P2 聚焦 → P3 关系边 → P4 验收），分支 feat/graph-evolution-1，Codex /goal 执行（plan/progress 本地不入库，沿用 planning-docs local-only 惯例）。

与既有决策的关系：修订 ADR-21 / D4.5-6（社区交互：选中高亮 → 进入聚焦视图；左上浮层 → 顶部工具条）；关系边可视化记录为 ADR-23。

阶段 4.7：图谱交互地基重构 ✅ 已完成 2026-06-16

背景：4.6 后作者连续实测发现，图谱交互问题不是单个 bug：鼠标在社区或节点上滚轮缩放不一致、拖节点不跟手、节点被社区色块困住、悬停说明漂移。这些现象共同指向同一个产品问题：图谱必须像一张有相机的地图，而不是每个交互各算各的。

当前状态：已完成核心交互地基并通过工作台与离线 HTML 双宿主验证。现在滚轮缩放在空白、节点、社区色块和边上保持一致；拖动节点不会跳走，也不会误打开阅读抽屉；节点可以离开社区色块；悬停说明跟随节点；社区色块是视觉提示，不是拖动围栏。

范围：

统一图谱交互规则：缩放、平移、拖拽、点击、悬停、社区选择都按同一张地图心智工作。
社区色块改为软区域：节点可以被拖出色块，色块可以有限响应，但不会无限放大，也不会改变真实社区归属。
两个入口同享结果：工作台图谱和 Skill 离线 HTML 保持同一套行为。

明确不做：空间索引、Canvas/WebGL 重写、密度策略重做、小地图拖拽导航。这些只有在真实大库或产品使用证明需要时再启动；本阶段不把它们当作默认方向。

与既有决策的关系：强化 ADR-21 的“位置层/结构层分权”和 ADR-22 的“画布导航是地基能力”。本阶段不改变抽屉归属、不改变知识库结构、不改变社区和连线的真实来源。

阶段 4.8：图谱演进——全局社区高亮（spotlight）✅ 已落地

背景：4.7 把全局图统一成“一张有相机的地图”后，点社区需要地图本身给出“我正在看这个社区”的反馈，而不是只依赖右抽屉解释选择。

当前状态：已落地。全局 Sigma 点社区会停留在全局路线并进入社区高亮态，右抽屉继续负责摘要与动作；相机轻量动画和动画期间 overlay 轻量跟随策略均已接入。

范围：

全局 Sigma 点社区进入临时“社区高亮态”：当前社区强调、其他社区弱化但仍可见；停在全局、不进入社区视图。
回全图按层分行为：社区视图→切回全局；全局高亮态→退高亮 + 清选择关抽屉 + 回构图；普通全局→重置视角，保留筛选/Pin/搜索。
点空白处退出高亮（与回全图在高亮态等价，有意冗余）。
相机轻量构图动画（平移 + 受限缩放）；动画期间社区云团、节点命中框和标签共用轻量 overlay transform，稳定后精确校准，避免每帧重算全部社区云团。
叠加优先级：筛选 > 搜索命中 > 选中 > Pin > 高亮。

明确不做：社区阅读视图改造、把社区视图迁 Sigma、全局 hover 完整方案、节点详情卡片重做、社区内部布局重排、大图聚合、#70 标签长度兜底。

与既有决策的关系：增强 ADR-21 第 5 条 / ADR-22 的“点社区先摘要、再按钮进入”第一步（只补地图反馈，不改两步边界）；在 ADR-22 第 4 条“画布导航是地基能力”之上给回全图叠加“高亮态分层”。高亮社区复用 Sigma 全局现有 selection（社区）→selected 视觉链路（已驱动云团/标签/边 dim），本阶段只补其他社区节点弱化与相机轻量动画；不复用 focusCommunity() / 顶层 state.focus、不新增平行状态、不写知识库——遵守 ADR-21 第 4 条位置/结构分权与“浏览状态留本机”。

阶段五：桌面应用打包（Tauri）

目标：跨平台桌面应用安装包。

范围：

Tauri 项目初始化
后端嵌入 Tauri sidecar 进程
macOS / Windows / Linux 三平台构建
安装包自动化产出（CI 可选）
安装后开箱即用，无需用户配 Node 环境（API key 仍由用户填）

验收标准：双击 .dmg / .msi / .AppImage 安装即可使用。

阶段后规划（暂不锁定，记录想法）

浏览器扩展：当前页面一键消化进库
多模型路由：按任务类型自动切（消化用便宜模型、深度对话用强模型），与 pi-agent provider 体系打通
全局快捷键 / 系统托盘
主题与自定义样式
多端同步（如果未来真有需求）

图谱演进候选池（2026-06-13 全景分析沉淀；首批已落地为「阶段 4.6」，见上文 §阶段 4.6）

来源：阶段 4.5 设计期间的行业全景讨论。统领判断——行业两条尸检教训：全局图是营销图、局部图才是工具（Roam 弱化图谱、TheBrain 靠局部视图活了 20 年）；只能看不能动的图谱是玩具（Obsidian 图谱日活极低的根因）。llm-wiki 已踩对第二条的解法（图谱可问，全行业独一份），第一条靠下面的"局部图"接住。

推荐切片（按就绪度推进；首批 4.6 已完成日常可用性主线）：

项	一句话	为什么值得
局部图模式	✅ 首批已落地：点社区进入聚焦视图，只显示该社区节点；点节点高亮并阅读	接住教训一：大库日常视图应是局部图；与"+邻居"选区天然衔接
路径查找 + agent 讲解	选两节点高亮最短路，agent 沿路径讲故事	独有赛道杀手级演示：Neo4j 只能画路径，我们能讲
lint 健康上图	孤岛/断链/上帝节点图上标注 + 一键让 agent 修	stage-4 终局愿景一直没排期；lint 能力现成只差可视化
关系类型上边	✅ 首批已落地（颜色维待数据）：按关系词汇表给边颜色 + 按置信度给边虚实，"矛盾"边避开 ENTITY 红。置信度虚实维已真实生效；关系类型颜色维当前几乎全默认"依赖"=单色，待消化管线产出 `relation` 注释（见远期池）	关系词汇表与置信度体系已有；4.6 补齐契约与上色管道
类型/时间过滤器	✅ 类型已落地；⏸ 时间筛选二期（缺 mtime）	轻量；Obsidian 式语法属于过度设计
导出美图	当前视角一键导出带主题样式的 PNG/SVG	数字山水是最强传播资产，用户发图 = 免费获客，成本极低
图谱增强检索（后端暗改）	↪ 已移交 ADR-19 检索线，不占图谱候选池决策位	GraphRAG 核心思路：图谱不只给人看，是 agent 的检索结构；半天级工作量

远期池（依赖消化管线升级，同一批做）：

LLM 推断边：消化时让模型判断该页与库内哪些页相关，带置信度入图（EXTRACTED/INFERRED 体系现成承接；同名竞品与 GraphRAG 的两阶段建边）
AI 真摘要：消化时为每页生成一两句摘要写入页面元数据，hover 预览卡与社区摘要自动升级
社区摘要 hover：悬停团块显示这一簇的一句话摘要（GraphRAG 分层社区摘要思路）
嵌入布局（第二布局，不替代力导向）：页面 embedding 降维投影，"位置即语义"；与力导向的差异本身是洞察——语义很近却没连线 = 待建链盲区，将来可成独有功能
消化时提取关系类型注释（relation_type）：4.6 已铺好边数据契约与上色管道，但现有 wiki 页面只有  注释、无  注释，故 G1-1 颜色维当前几乎全默认"依赖"= 单色（置信度虚实维已真实生效）。消化时让模型判定关系类型并写入注释，即可点亮颜色维（与 LLM 推断边 / AI 真摘要同属管线升级，同一批做）

明确不做 / 已修订：

❌ 3D 图谱（行业著名伪需求，旋转酷炫三分钟，阅读效率负提升）
❌ 白板化 / 手动布局全图（Heptabase 路线；钉扎已是其轻量正解）
⚠️ 旧判断“❌ WebGL 渲染重写”已被 2026-06-19 大图谱性能方案修订：当前 DOM/SVG 不再承担万级全局图，后续全局大图主线走 Sigma/Graphology；DOM/SVG 继续服务小图、离线细节和社区阅读。

竞品技术参考存档：渲染梯子 DOM(<500)→Canvas(<5k)→WebGL(50k+，Obsidian 用 Pixi)；嵌入布局参考 Nomic Atlas；检索架构参考 Microsoft GraphRAG（社区检测 + 分层摘要，与 llm-wiki 的社区/digest 理念同构）；局部视图参考 TheBrain plex；语义相似边参考 Connected Papers。

5. UI 设计原则

5.1 三栏布局

[ 侧栏 270px / 52px 窄栏 ] [ 主区域 自适应 ] [ 右抽屉 0 / 可拖动宽度 / 全屏 ]

侧栏默认显示：
- 知识库列表（顶部，含"+ 新建知识库"按钮）
- 当前库的对话列表（中部，含"+ 新对话"按钮，按最近活跃排序）
- 图谱入口、设置入口（底部）
侧栏可折叠为窄图标栏：保留展开、当前知识库、刷新、新建、添加、设置入口；图标悬停显示文字提示。该状态保存在本机。
主区域永远是对话（除非用户主动切换到图谱）
右抽屉默认隐藏，呼出场景：产物预览、引用页面查看、设置面板。右抽屉宽度可拖动调整，双击拖动边缘恢复默认宽度；宽度保存在本机。小屏幕下不启用拖动，继续占满屏幕。

5.1.1 会话与切换行为

会话绑定到知识库：每个库有独立对话列表，不允许跨库会话
同库内多个并行对话：用户随时"+ 新对话"开新线程
切换知识库：当前对话自动保存 → 切到目标库 → 自动选中目标库最近活跃的对话
App 启动：自动选中"最后一次使用的库 + 该库内最近活跃的对话"
全程自动保存，无"是否保存"弹窗

5.2 顶栏

[📚 当前知识库]   [搜索 ⌘K] [🤖 模型 ▼] [新对话] [主题] [外观] [⚙ 设置]

永远可见，回答"我在哪里"，并承载跨对话 / 图谱两个视图共享的全局操作。

左侧知识库头只展示当前库名、来源和有效状态，不做下拉，不显示篇数
模型选择只在右侧控件里出现，读写 config.modelRoles.main
外观齿轮只管理 Paper 视觉偏好；侧栏"设置"仍打开现有配置面板
图谱专属操作（重置布局、重建图谱）留在图谱视图内部，不进入全局顶栏

5.3 `@` 与 `/` 的设计契约

符号	语义	弹出内容	选中后
`@`	引用	当前知识库的页面 / 实体 / 主题	在输入框插入 wiki 链接，agent 看到时会读这页
`/`	执行	所有已加载 Skill 命令 + 内置命令	在输入框插入命令调用，agent 收到时执行

两者必须有清晰区分。@ 是"找内容"，/ 是"做事情"，永远不要混用。

5.4 视觉风格

默认浅色暖纸主题，支持夜灯主题切换，用户选择只保存在本机
正文字体：Plus Jakarta Sans 优先，CJK 回落系统字体；手写点缀用 Caveat；等宽字体用 JetBrains Mono / SF Mono
视觉方向为 Paper 暖纸：克制、可读、温暖，但不改变三栏心智和对话中心定位
外观偏好是正式用户偏好：纸张质感、强调色、用户气泡、手写点缀、密度、主题均保存在本机
阶段 3.5 收尾吸收本地 UI 原型：统一侧栏、状态条、对话区、输入区、菜单、抽屉和设置面板的工作台视觉，不改变既有三栏心智和功能范围
对话区工具执行采用 omp 风格状态呈现：当前 assistant 回复内只保留一个动态工具条，工具完成后折叠为分组摘要；用户停止时保留清楚的取消状态，避免工具流水账挤占正文

5.5 严禁项

不做 onboarding 引导浮层
不做 emoji 滥用
不做"AI 正在思考..." 这种空白等待动画（用真实事件流：动态工具状态、流式文本）
不强制注册 / 登录（本地工具不需要账号）

6. 数据与目录约定

6.1 知识库存储策略（混合模式）

用户需要管理多个领域的知识库（AI 学习、工作材料、设计灵感等），不该被强制塞到一个固定位置。采用默认根目录 + 外部目录登记的混合模式：

类型	位置	说明
默认知识库根	`~/llm-wiki/`	App 首次启动自动创建；app 内"+ 新建知识库"在此建子文件夹
外部知识库	用户任意路径	用户手动"添加现有库"指向某路径，登记在 `config.json`
应用数据	`~/.llm-wiki-agent/`	配置、会话、日志、Skill，用户通常不直接碰

为什么默认是 ~/llm-wiki/ 而不是 ~/Documents/...：

macOS 的 ~/Documents/ 会被 iCloud Drive 自动同步，会撕坏 .wiki-cache.json 的文件锁和"写入即更新"逻辑
知识库是顶级资产，值得一个顶级目录，不该埋在 Documents 深处
短路径友好：终端 cd ~/llm-wiki 一秒到达

发现机制：

启动时扫描 ~/llm-wiki/ 下所有含 .wiki-schema.md 的子目录 → 自动注册
再读 config.json 里登记的外部库路径 → 加入列表
失效路径（外部库被删/移走）：UI 标记为灰色，提示用户移除登记

6.2 知识库目录结构（沿用 llm-wiki-skill）

每个知识库内部结构与 Skill 完全一致：

<某知识库>/
├── raw/                # 原始素材（子目录如 articles/tweets/wechat/xiaohongshu/zhihu/pdfs/notes/assets
│                       # 由 Skill init 时创建，agent 不强求子目录约定，沿用现有结构）
├── wiki/               # AI 生成内容
│   ├── overview.md     # 知识库总览（init 时生成）
│   ├── entities/       # 实体页
│   ├── topics/         # 主题页
│   ├── sources/        # 素材摘要
│   ├── comparisons/    # 对比分析
│   ├── synthesis/      # 综合分析
│   │   └── sessions/   # 对话结晶（agent 新增的对话沉淀都进这里）
│   └── queries/        # 保存的查询结果
├── purpose.md          # 研究方向
├── index.md            # 索引
├── log.md              # 操作日志
├── .wiki-schema.md     # 配置（识别"这是个知识库"的标志文件）
├── .wiki-cache.json    # 素材去重缓存
├── .wiki-tmp/          # Skill 运行时临时目录（agent 不读不写，Skill 的 .gitignore 已排除）
└── .gitignore          # init 时生成，至少排除 .wiki-tmp/

❗ agent 项目不重新设计这个结构。完全沿用 Skill 现有约定，确保两边互通。 ❗ 结构以 scripts/init-wiki.sh 为权威，不要在 PRODUCT.md 里手动维护差异。

6.3 应用数据目录

~/.llm-wiki-agent/
├── config.json         # UI 偏好、默认模型、外部库登记 —— 不存任何 API key
├── sessions/           # pi-agent 会话持久化（对话历史）
├── skills/             # 软链接或拷贝到此目录的 Skill
│   ├── llm-wiki/       # → 链接到 llm-wiki-skill 安装位置
│   ├── docx/           # 来自 anthropics/skills
│   └── ...
└── logs/

模型认证不在这里。所有模型凭证由 pi-agent 统一管理，存在：

~/.pi/agent/auth.json    # pi-agent 的认证文件，权限 0600

❗ 应用数据 ≠ 知识库数据 ≠ 模型凭证，三类彻底分离：

类型	位置	谁管
知识库数据	`~/llm-wiki/<name>/` 或外部路径	用户 + agent
应用数据	`~/.llm-wiki-agent/`	llm-wiki-agent
模型凭证	`~/.pi/agent/auth.json`	pi-agent SDK

❗ .gitignore 排除 ~/.llm-wiki-agent/。永远不要把 API key 写进任何源代码或仓库文件。详见 ADR-13。

6.4 Obsidian / 第三方工具共存规则

很多用户（包括作者本人）用 Obsidian 浏览同一份知识库。两者必须零冲突。

agent 读写的文件：

✅ raw/ 下任意文件
✅ wiki/ 下任意 .md 文件
✅ purpose.md / index.md / log.md
✅ .wiki-schema.md / .wiki-cache.json
✅ .wiki-graph-layout.json（阶段四起：图谱钉扎布局，工作台后端写、Skill 侧只读，见 ADR-21）

agent 完全忽略的文件 / 目录：

❌ .obsidian/（Obsidian 元数据）
❌ .DS_Store（macOS）
❌ *.base（Obsidian Bases）
❌ *.canvas（Obsidian Canvas）
❌ .wiki-tmp/（Skill 自用的临时目录）
❌ node_modules/、.git/、venv/ 等所有 dev 类目录
❌ 任何非 markdown、非 Skill 约定内的文件

用户用 Obsidian 编辑 markdown、画 Canvas、做 Base，agent 都不会碰。

6.5 运行时应用状态（由 Extension 持有）

currentKnowledgeBase：当前打开的知识库绝对路径
currentConversationId：当前对话的 ID（pi-agent 会话）
pinnedReferences：当前对话固定引用的页面列表
activeSkills（可选）：本次会话允许的 Skill 子集

6.6 中文路径与 UTF-8 铁律

用户的知识库名可能含中文（如 AI学习知识库）、空格、emoji。

❗ 铁律：所有路径处理代码必须用 UTF-8，绝不使用"路径转拼音"、"中文字符转码"等歪招。Node.js / Tauri 原生支持 UTF-8，正确写法即可。

6.7 边界场景行为约定

场景	行为
多实例启动	只允许单实例。第二次启动直接 focus 已有窗口（macOS Cmd+N 也不开新窗口）。原因：本地后端服务监听固定端口，多实例冲突；也避免对同一文件并发写
无网络 / 未配置 API key	启动不报错。库列表、对话历史、wiki 页面浏览仍可用。试图发新消息时给一个明确提示"未配置 API key，去设置面板"或"网络断开"
崩溃 / 异常退出后恢复	重启后：自动恢复"最后一次使用的库 + 最近活跃对话"；对话内容由 pi-agent session 持久化保证完整；侧栏折叠状态和右抽屉宽度保存在本机并恢复；右抽屉开关本身不恢复，避免恢复到"半坏"的 UI
后端服务未起	前端 UI 显示明显的"后端服务未连接"状态，不渲染对话区（避免误以为是 agent 卡死）
知识库目录被外部删除	列表里标灰，点击给出"目录已失效，是否从列表移除"提示，不崩溃

7. 关键决策记录（ADR）

决策一旦写下，未来要推翻必须明确说明"什么变化了"。

ADR-1：选 pi-agent 而非 Vercel AI SDK / Mastra

Vercel AI SDK 强项是云部署，本项目不部署
Mastra 偏企业向 dashboard，对单人本地工具偏重
pi-agent 原生支持 Anthropic Skill 标准，可零适配复用 llm-wiki-skill 和社区 Skill 生态
pi-agent SDK 和 RPC 模式都明确支持嵌入到 web / 桌面 UI

ADR-2：对话中心而非图谱中心

用户已有 Codex / Claude Desktop 的对话心智，零学习成本
@ / / 是 Skill 和工具集成的天然入口
图谱适合"探索"，不适合作为日常工作主屏；作辅助面板更合适

ADR-3：SSE 而非 WebSocket

agent → UI 是单向事件流
SSE 是 HTTP 标准，浏览器和 webview 原生支持，断线自动重连
WebSocket 需管理双向状态机，本场景过度

ADR-4：先 web 再 Tauri 打包

web 是验证产品逻辑最快的形态
Tauri 本质是 webview 容器，前端可直接装现成
一开始做桌面会让"前端开发"和"打包调试"两个复杂度叠加，0 代码起步必死

ADR-5：不用 MCP

MCP 是跨进程 RPC，每个能力一个独立 server，本地场景过重
Skill 是 markdown + scripts，进程内执行，简单一个量级
pi-agent 的 Skill 加载机制已足够
未来如果某个能力必须用 MCP（比如调云端服务），再单独接入

ADR-6：完全进化为 agent，不维护双通道

单人项目维护两个发行通道是开发者陷阱
pi-agent 能直接复用 Skill 内容，"完全进化"代价比想象的小
Skill 仓库进入维护模式，老用户照常使用

ADR-7：知识库上下文用 Extension 注入，不拼 prompt

拼 prompt 难以维护、容易污染、对模型不友好
pi-agent Extension 可以注册自定义 tool 并持有应用状态
让 agent 通过 tool 调用获取"当前在哪个库"、"库的元数据"，行为更可控
切库时 Extension 状态变化即可，不需要重建 session

ADR-8：React + Vite 而非 Next.js

Next.js 的 SSR / Edge / 部署优化在 Tauri 里全废
Vite 纯 SPA 路线打包简单，Tauri 一行命令吃下
React 生态对新手最友好

ADR-9：UI 用 shadcn/ui

组件是复制到本仓库的源代码，不是黑盒 npm 包，0 代码用户也能改
原生 Tailwind + 深色主题，符合工具感视觉风格
社区主流，AI 协作样本量大

ADR-10：pi-agent 作为 npm 依赖，不 fork、不 clone 源码

npm 依赖是现代 JS 项目用第三方库的标准方式，"不造轮子"正解
fork 会导致上游更新无法 merge，维护噩梦
submodule 对新手是地狱级体验，没有任何收益
极端情况需要 patch 时用 patch-package，保持升级路径干净

ADR-11：知识库采用混合存储策略（默认根 + 外部登记）

用户的知识天然分类，不该被强制塞到一个固定位置
默认根 ~/llm-wiki/ 给新用户零配置上手
外部库登记给已有库的用户（如 Obsidian vault 用户）零迁移成本
不选 ~/Documents/ 因为 macOS 的 iCloud Drive 会撕坏文件锁

ADR-12：会话绑定知识库，同库支持多并行对话

会话绑定库：防止跨库上下文污染（投资笔记不该混进 AI 研究）
同库多对话：符合 Claude Desktop / ChatGPT 的心智，用户切换思路不用清空历史
切库自动保存 + 自动选中目标库最近对话：零摩擦
全程自动保存，无确认弹窗

ADR-13：模型认证完全复用 pi-agent 的 auth 体系（三层 fallback）

不在 llm-wiki-agent 自己维护 API key 存储。所有凭证最终落到 pi-agent 的 ~/.pi/agent/auth.json，由 pi-agent SDK 统一读取与刷新。

三层 fallback（按推荐顺序）：

复用 pi CLI 登录态（推荐）
- 用户在终端跑 pi login，选择 Claude Pro/Max / ChatGPT Plus / GitHub Copilot OAuth，或填 Anthropic / OpenAI 等 API key
- 凭证由 pi CLI 写入 ~/.pi/agent/auth.json（权限 0600）
- 我们的 app 通过 AuthStorage.create() 自动读取
- UX 等价于 open-design 的"复用本地 CLI"：登录一次，到处可用
UI 内填 API key
- 设置面板里直接填 Anthropic / OpenAI 等 key
- app 写入 同一个 ~/.pi/agent/auth.json，不是我们自己的 config 文件
- 测试连接按钮验证有效
环境变量
- 用户在 shell 里 export ANTHROPIC_API_KEY=...
- pi-agent SDK 自动检测
- 设置面板只读显示当前环境变量状态

关键约束：

llm-wiki-agent 的 config.json 不存任何 key，只存 UI 偏好、外部库登记、默认模型等元数据
想用 Claude Pro/Max 订阅的用户零成本接入（这是 BYOK API key 路线给不了的礼物）
macOS Keychain / 1Password 等高级用法通过 auth.json 的 !shell command 语法支持，不需要我们额外做

ADR-13b：不抄 open-design 的"多 CLI 子进程"模式

open-design 通过启动 CLI 子进程（Claude Code / Codex / Cursor 等 16 个）来实现"复用本地 CLI"，因为它要兼容多家协议。

我们只用 pi-agent SDK，已经覆盖所有主流 provider（Anthropic / OpenAI / Google / DeepSeek / Bedrock / Azure / xAI / OpenRouter ...）。不需要再做 CLI 检测和子进程管理。

未来如果某用户极度想用某 CLI 驱动 llm-wiki，可作为可选适配层加进来，但不进阶段一-五主线。

ADR-14：app 内一键新建知识库

用户不应该被迫开终端才能创建新库
内置 /new-wiki 命令调用 llm-wiki-skill 的 init 流程
agent 自己跑自己的 Skill，闭环

ADR-15：Obsidian 共存（agent 忽略非 markdown 与第三方元数据）

大量用户用 Obsidian 浏览同一份知识库
agent 不碰 .obsidian/、*.canvas、*.base、.DS_Store 等
用户用 Obsidian 编辑 / 画 Canvas / 做 Base 不受影响

ADR-16：长期与 llm-wiki 仓库合并（agent 是 Skill 的升级版）

背景：作者的 llm-wiki-skill 是 1.7k 星的成熟项目，纯提示词系统形态，没有 agent 循环 / 子 agent 分工 / 多步工具链。本项目（llm-wiki-agent）是把 Skill 升级为 agent 形态的实验。

决策：agent 形态成熟后，本仓库代码并入 llm-wiki 主仓库，作为 Skill 的 agent 升级版同时存在（保留 Skill 给纯 CLI 用户）。当前仓库是临时仓库。

对架构的指导（"C 混合"归属原则）：

能力归属原则："Skill 已有的功能调 Skill，agent 工作台新能力用 Extension"。这条原则今天和合并后都成立——今天的"spawn 外部脚本"合并后变成"同仓库内调用"，调用关系不变
拒绝重复造轮子：llm-wiki-skill 已实现的消化能力（X / 微信 / 小红书 / 知乎 / YouTube / PDF / 本地文件）一律调 Skill，不在 agent 端重写
拒绝塞 agent 特有命令进 Skill：对话结晶、UI 元能力（列页面 / 读单页）、auth 管理这些"agent 工作台才有"的概念，用 Extension 实现，不污染 Skill 的"纯提示词系统"特质
代码组织模块化：agent 端目录结构保持清晰，未来可 lift-and-shift 直接挪进 llm-wiki/agent/ 子目录
不为合并提前优化：今天该用 npm workspaces + 独立仓库就用，合并是未来的事，今天保持工程简单

阶段 3.5 的明确例外：批量本地文件消化为了验证"便宜模型 + 并行子代理"路线，允许子代理不调用完整 llm-wiki Skill，而是只读单个文件并输出 wiki markdown，主进程负责写盘。这个例外只覆盖阶段 3.5 的 .md/.txt/.pdf 批量入库场景，不推翻"Skill 已有能力优先调 Skill"的长期原则。

未来扩展位：媒体创作（阶段三）/ 子 agent 分工 / 多模型路由都依赖 agent 形态，是 Skill 给不了的。这些是 agent 形态存在的根本理由。

与既有 ADR 的关系：

强化 ADR-7（知识库上下文用 Extension 注入，不拼 prompt）
强化 ADR-13b（不抄 open-design 的多 CLI 子进程模式，因为我们最终是同仓库 agent）
兼容 ADR-10（pi-agent 作 npm 依赖）和 ADR-14（app 内一键新建知识库）

ADR-17：阶段二新增前端依赖（react-markdown + cmdk）

背景：阶段二引入 markdown 渲染（右抽屉显示 wiki 页面）+ 命令补全菜单（/ 和 @）。两个能力都需要新依赖。

决策（已在 web/package.json 落地）：

依赖	版本	用途
`react-markdown`	^9	assistant 消息 + 右抽屉的 markdown 渲染
`remark-gfm`	^4	GFM 支持：表格、任务列表、自动链接
`cmdk`	^1	`/` 命令菜单 + `@` 引用菜单底层（即 shadcn `<Command>` 基础）

拒绝项：

marked / markdown-it：生态/类型/插件不如 react-markdown 稳
Radix Popover 自写：键盘导航与 a11y 都要重写，工作量大

与 ADR-9（shadcn/ui）的关系：cmdk 即 shadcn 官方 Command 底层；react-markdown 在 shadcn 生态里是社区主流选型。两者都与现有 UI 体系自然契合，无破坏性。

长期：阶段三引入产出类 Skill（docx / pdf / pptx）+ open-design 设计 Skill 时，UI 端会需要更多依赖（PPT 渲染、文件预览等）。届时再补 ADR-18+。

ADR-18：阶段 3.5 多模型双角色 + 轻量子代理框架

背景：阶段 1-3 完成后两个痛点同时浮现——TBD-2（多模型路由）一直没有承载场景；阶段二的"一次喂一篇"消化模式拦住了批量进库的用户。两件事在阶段 3.5 合并解决：批量消化天然需要"便宜模型 + 并行"，正好把多模型路由落地。

决策：

双角色而非 N 角色：只引入 main（聊天）+ digest（消化）两个角色。拒绝项："per-task 模型路由"（消化/沉淀/产出/对话各自一个）太复杂、用户配不动；"只有一个 default model"则无法承载阶段 3.5 的核心需求
角色配置存项目 config.json 不写 pi settings.json：跨工具污染坏处大于好处；~/.llm-wiki-agent/config.json 是我们自己的偏好文件
main 角色接管主对话：设置里的 main 角色用于主对话创建和切换；保存 main 后重载当前活跃对话，让右上角模型显示与设置保持一致。digest 角色强制走子代理，保证"消化用便宜模型"的承诺
子代理用 pi SDK 原生 API 而非自建框架：createAgentSession({ model, authStorage, modelRegistry, sessionManager: inMemory(), tools: ["read"] }) 已经够用。拒绝项：抄 omp 的 executor.ts / index.ts 那 3000 行（工作树隔离 / 嵌套子代理 / worker IPC 我们都不需要）；自建独立子代理 runtime 重复造轮子
并发控制自写 30 行：拒绝引入 p-limit / async-pool 等并发库（一个 while 循环就能做）；拒绝 Promise.all 一把开（N 个文件 = N 个并发模型请求会 429）
子代理不挂业务 extension：阶段 3.5 的批量本地文件消化是 ADR-16 的明确例外，消化是裸 prompt + 只读工具的简单任务，挂 KB / synthesis / artifacts extension 反而让 cheap 模型困惑
写盘归主进程：子代理只输出 wiki markdown 文本，主进程负责写到 wiki/synthesis/sessions/。让 cheap 模型决定文件路径风险大；主进程已知正确路径无需让 cheap 模型决策
SSE 沿用 ADR-3 路线：批量消化接口直接返回 text/event-stream，不为此开 WebSocket，也不做轮询
拖拽优先于输入，但不假设浏览器一定暴露绝对路径：阶段 3.5 先实测 macOS Finder 拖拽时 DataTransfer 是否提供 file://；若提供则自动填路径，若不提供则用输入框作为明确兜底。输入框不是降级体验，而是 web 沙箱下必须保留的可靠通道

与既有 ADR 的关系：

解决 TBD-2（多模型路由）：选项 B 落地——通过角色映射而非任务路由
兼容 ADR-3（SSE）：批量消化进度沿用 SSE
兼容 ADR-7（Extension 注入上下文）：子代理不需要 KB 上下文，直接 prompt 传入；主对话保持现有 extension 注入路径
兼容 ADR-16（Skill 优先）：本阶段对子代理批量本地文件消化做一次受控例外，不扩展到 Skill 已覆盖的完整素材消化流程
兼容 ADR-10（pi-agent 作 npm 依赖）：完全用 SDK 原生 API，不 fork 不 patch
强化 ADR-12（会话绑定知识库）：子代理是临时 inMemory session，不污染 KB 的对话历史
强化 ADR-13（凭证落 ~/.pi/agent/auth.json）：modelRoles 只存 {provider, modelId}，不存任何 key

何时重新评估：

main 角色切换后如果出现历史会话恢复异常 → 回退为仅对新会话生效
用户反馈"批量消化输出格式漂移" → 引入 schema 校验 + 重试
用户反馈"并发 3 还是太慢" → 提供更高档位 + 自适应降级（429 自动退避）

ADR-19：主对话引入“系统检索 + 上下文注入”

背景：阶段 3.5 批量消化后，用户进入当前知识库直接问“这些文章总结一下”，弱模型可能不会主动调用 list_knowledge_base_pages / read，而是反问用户提供文章内容。ADR-7 的“靠 Extension 工具让 agent 自觉获取上下文”在问答检索场景下不够稳定。

决策：

主对话 /api/prompt 路径破例采用“后端检索 + 拼隐藏上下文”模式。
ADR-7 的“应用状态用 Extension 注入”原则仍然成立；本破例只覆盖“问答类知识库检索”，不改变 current_knowledge_base 等状态工具。
同一份检索能力同时暴露为 query_knowledge_base 工具，保留 Extension 路径供强模型主动调用。
每个 user turn 独立判断并检索，不跨轮复用旧结果。
检索失败时降级为普通对话，同时通过 SSE 轻提示并写入 retrieval 日志，不中断用户输入。
阶段 4.6 补充：图谱增强检索不属于可见图谱交互，不占图谱候选池决策位；后续若做，归本 ADR 的检索质量演进线。

与既有 ADR 的关系：

破例 ADR-7：仅限主对话问答检索。
兼容 ADR-3：新增轻量 SSE 事件。
兼容 ADR-16：检索是 agent 工作台元能力，落在 server 端。
兼容 ADR-18：不影响 digest 子代理批量消化路径。

何时重新评估：

主流模型工具调用稳定性显著提升 → 考虑改回纯工具路径
用户大量反馈“参考页面被编造” → 强化 prompt 约束 + 引入后置校验
KB 规模超过 100 篇且本地文本检索变慢 → 引入向量检索

ADR-20：阶段四启动 monorepo 合并（丙方案）

背景：ADR-16 定了"agent 成熟后并入主仓库"，但没定时机。阶段四的图谱引擎是两端（工作台 / Skill 离线 HTML）共享的第一块代码——共享代码出现的那一刻，分居两仓库开始产生真实摩擦（跨仓库依赖、双份维护），即合并时机成熟的信号。另两个事实强化此决策：主仓库（1.8k+ star）自 2026-05-13 停更，单人双仓库 = 注意力分裂已被证实；llm-wiki-agent 名字与 SamurAIGPT 同名竞品（2.9k star、活跃）撞车，不可作为独立品牌发布。

决策：

丙方案：本仓库 git subtree add --prefix=workbench（保留全历史）整体搬入主仓库；引擎落 packages/graph-engine/；主仓库根建 workspace package.json
只做工程合并，不做品牌动作：不发版、不改主仓库 README、不 archive 旧仓库——改名（llm-wiki-skill → llm-wiki）、双形态叙事、对外发布留给后续品牌阶段
终局形态"一个产品、两扇门"：产品 = 知识库文件格式 + 中文素材管线 + 方法论；Skill 与工作台是同一份知识库的两个访问端。Skill 永不砍（获客漏斗 + 格式中立性证明）；工作台是长期重心（批量消化 / 多模型 / 产物 / 活图谱等 agent 形态独有能力的家）
Tauri 打包（原阶段五）推迟：打包是分发优化，先用 git clone + npm run dev 验证工作台的真实外部需求
❗ 主仓库测试是 CommonJS，monorepo 根 package.json 不设 "type": "module"，ESM 声明留在 workbench 子包内

拒绝项：双仓库长期并行（注意力分裂）；agent 另立品牌（撞名 + star 池分裂 + 格式话语权分裂）；引擎放 agent 仓库做完再搬（二次搬运纯损耗）。

与既有 ADR 的关系：落地 ADR-16（合并愿景 → 启动执行）；ADR-16 的"能力归属原则"继续生效（Skill 已有能力调 Skill，agent 元能力走 Extension）；ADR-10（pi-agent npm 依赖）不受影响。

ADR-21：图谱引擎与活地图（一个引擎、两个宿主）

背景：原阶段四"图谱集成"若做成 iframe 嵌 HTML，得到的是一个不能联动的孤岛。竞品图谱（Obsidian / Logseq）公认"好看不好用"，根因是图谱后面没有人——只能看不能问。llm-wiki 工作台的图谱后面站着 agent，这是整个设计的支点。另：Skill 仓库 PR #44/#45 证明在静态布局上嫁接手动拖动必然失败（死布局无让位、指纹机制致重算后全部作废、localStorage 与知识库分离）。

决策：

一个引擎、两个宿主：@llm-wiki/graph-engine（TS，双产物 ESM/IIFE）；宿主差异用 capabilities 能力注入表达，引擎核心零分叉
新骨架、旧器官：现有 graph-wash ~2300 行按 A（纯函数直接搬）/ B（画法拆开搬）/ C（样式抽主题 token）/ D（新写）四级处理；A 级 1:1 翻译禁止顺手优化；M1"静态复现旧版"为重构安全网
活模拟 + 钉扎：d3-force（单模块）；预计算起点 + 低温入睡的混合布局；拖动低温让位、松手即钉；钉扎存知识库根 .wiki-graph-layout.json（只存钉的、库内相对路径为 key、模型坐标）。原则：对知识的主观组织进库文件，浏览状态留本机。2026-06-19 修订：双击解钉不再作为主路径，固定/取消固定改为明确按钮或菜单动作。
位置层/结构层分权：拖动只改位置，颜色/社区/连线永远由真实 wikilink 决定；想改结构 → 通过选区提问让 agent 建链写回 wiki。图谱永不撒谎
选区 = 批量 @：结构化四式选择（点节点/点社区/+邻居/Shift 多选），砍自由套索（空间邻近无语义保证）；选区面板结构事实先行、动作随性质变；动作本质是已有工作流（digest/comparisons/lint/crystallize）的空间入口；沿用 /api/prompt 文本通道不加新参数。2026-06-19 修订：点社区不再直接进入社区聚焦，先显示社区摘要，再由明确按钮进入社区。2026-06-26 增补：全局图点社区在“显示社区摘要”的同时，进入临时“全局社区高亮态”（复用 Sigma 全局现有 selection→社区 selected 视觉链路、补节点弱化与相机动画，不复用 focusCommunity/顶层 focus、不新增平行状态），当前社区强调、其他社区弱化但仍可见；真正进入社区仍由抽屉按钮负责。见阶段 4.8。
重算链监听文件系统而非"消化"：变化源五个以上，只盯消化会让地图说谎；fs 监听 + 防抖 ~5s + 自家批量挂起；全量重算（子进程跑 build-graph-data.sh，不重写不做增量）+ 新旧 diff；diff 即动画剧本
生长动画 diff 队列：图谱可见时消费（不可见时徽标 + 打开补播）；语义锚点发芽、错峰、≤3s、可跳过、尊重 prefers-reduced-motion
图谱绑当前知识库：与 ADR-12 会话绑库同构，切库 = 换地图；跨库图谱不做
主题一对：浅「数字山水」+ 深「墨夜」跟随工作台主题；不做主题商店——视觉签名的价值在"所有人记得住"，不在"多数人喜欢"
顶部工具条替代左上浮层：阶段 4.6 后，社区列表、类型筛选、边图例、回全图等整图操作统一进入顶部工具条；工具条默认收起、半透明、浏览状态留本机。单节点操作仍留在右抽屉。

与既有 ADR 的关系：强化 ADR-2（对话中心：图谱是第二主屏，对话仍是第一）；沿用 ADR-3（SSE 推 graph_updated）；遵守 ADR-16 能力归属（数据管线调 Skill 脚本；选区/钉扎等工作台元能力走 server + 引擎）；兼容 ADR-19（选区注入与检索注入同属"后端拼上下文"路线）。

何时重新评估：

力模拟或当前 DOM/SVG 在真实大库实测掉帧 → 全局大图不继续硬撑 DOM/SVG；按 2026-06-19 大图谱性能方案进入 Sigma/Graphology 主线，社区阅读继续保留 DOM/SVG
fs.watch recursive 在 macOS 实测不可靠 → 引入 chokidar
选区注入大社区上下文超限 → 清单截断 + 提示 agent 分批读

ADR-22：图谱交互模型——点击即阅读，选区即升级

2026-06-19 修订：该 ADR 的“点击即阅读”已升级为“全局轻量摘要优先”。全局节点单击先打开轻量摘要；“打开详情 / 阅读”是明确动作，会进入所属社区并选中节点。社区色块/图例单击同样先显示社区摘要，再由按钮进入社区聚焦。

背景：阶段四把"点击节点"的默认响应做成了选区提问悬浮窗，作者实测确认这违背用户心智——点一个节点最常见的意图是"看它是什么"（阅读），不是"对它执行操作"（提问）；且 stage-4 D6 动作映射表缺"单节点"行，单节点内部链接恒为 0 被误判进"无链接多选"剧本，产生废话统计与错位动作。

决策：

单击 = 阅读：右抽屉阅读态（标题 + 元信息行 + 双动作 + 正文），无悬浮窗；选区是阅读的升级态（Shift 多选 / 点社区 / +邻居），同一抽屉切换状态
抽屉瘦身原则：抽屉负责内容，图谱负责关系，凡从正文派生的信息（摘要、置信度列表、邻居列表）不重复展示；学习系统三件套不做（待真实使用后按工作台语境重新设计）
动作映射表必须覆盖全部选区类型（含单节点与孤岛单节点），统计卡仅 ≥2 节点显示
画布导航是图谱的地基能力（缩放/平移/回全图/小地图联动），引擎层实现两端同享。2026-06-26 增补：回全图按当前层级分行为：社区视图→切回全局；全局高亮态→退高亮并清空选择/关抽屉/回构图；普通全局→重置视角且保留筛选/Pin/搜索（见阶段 4.8）。

与既有 ADR 的关系：修订 ADR-21 第 5 条的选区面板形态（悬浮窗 → 抽屉态）；强化 ADR-2（对话中心，图谱阅读复用工作台抽屉基建）；沿用 stage-4 D9 原则（视口/图例折叠等浏览状态留本机）。

ADR-23：关系边可视化采用“关系类型控制颜色、置信度控制虚实”

背景：阶段 4.6 要把关系词汇表真正画上图。执行前核验发现，旧边字段 type 实际承载的是 EXTRACTED / INFERRED / AMBIGUOUS 置信度，不是“实现 / 依赖 / 对比 / 矛盾 / 衍生”等关系类型。若直接拿旧 type 上色，会把两种语义混在一起。

决策：

边数据契约分两维：保留旧 type=confidence 兼容入口，同时显式输出 confidence 与 relation_type。数据管线可读取同一行  /  注释；旧链接默认 relation_type=依赖、confidence=EXTRACTED。
颜色只表达关系类型：矛盾用避开 ENTITY 红的品红系，对比用琥珀，顺承关系（实现 / 依赖 / 衍生）用主题中性色。
虚实只表达置信度：原文关系为实线，推断关系为虚线，待确认为弱虚线 / 点划，不再借颜色表达置信度。
全局克制、局部完整：全局图边保持低权重，避免大库变噪；进入社区聚焦视图后，边色与虚实完整呈现。
两个宿主同享：工作台与离线 HTML 都使用同一引擎渲染边、边图例和 hover 关系提示；离线 HTML 仍不注入提问能力。

与既有 ADR 的关系：强化 ADR-21 的“一个引擎、两个宿主”；延续 ADR-22 的“抽屉负责内容，图谱负责关系”；不改变 ADR-19 的检索演进线。

ADR-24：Paper 暖纸视觉方向与外观偏好

背景：工作台已经从最初的深色工具壳进入长期使用阶段。用户在对话、消化、导出和图谱之间反复切换，界面需要更像一张可读的工作纸面，而不是临时调试台。Paper v2 原型已通过多轮设计确认，方向不再重新讨论。

决策：

默认浅色暖纸：默认主题从深色改为浅色暖纸，夜灯主题保留为一键切换。
统一顶栏：跨视图共享的搜索、模型、新对话、主题和外观操作进入顶栏；对话区和图谱区不再各自维护重复状态条。
外观偏好本机持久化：纸张、强调色、气泡、手写点缀、密度和主题走 localStorage，不写后端，不进知识库目录。
单一 CSS 类系统：沿用并演进现有 .msg-* / .chat-* / .tool-* / .drawer-* 等类，不引入并行 .pw-* 类层。
强调色用预设属性：强调色通过 data-accent 预设驱动 CSS 变量，避免行内样式和外观状态双主漂移。
图谱画布内部后置：本次只统一图谱 Tab 外壳、工具条和图例；Sigma 画布内部配色另起任务。

与既有 ADR 的关系：修订 §5.2 / §5.4 的旧深色工具感方向；兼容 ADR-2（对话中心）、ADR-9（shadcn/ui）、ADR-21（图谱引擎与宿主分权）。

ADR-25：前端交互测试与 Paper 视觉回归栈

背景：现有前端测试以 node:test 和 renderToStaticMarkup 为主，只能证明静态输出，无法证明按钮点击、键盘快捷键、localStorage 外观偏好、抽屉拖拽和顶栏模型切换真的可用。Paper UI 迁移是高交互改动，继续只靠静态测试会漏掉真实用户路径。

决策：

引入 DOM 交互测试：前端 dev 依赖加入 jsdom 与 @testing-library/react，并提供统一 test setup，覆盖点击、键盘、localStorage 和 document dataset。
引入 Playwright 视觉回归脚本：为 Paper 主题组合、长对话、抽屉和响应式视口提供可重复截图入口。Playwright 只作为前端开发 / 验收依赖，不引入新 UI 框架。
阶段验收真实运行：每个阶段继续保留 typecheck / build / test；最终阶段必须运行 lint、浏览器主流程和 Paper 视觉截图脚本。
性能样本进入验收：长对话、搜索大列表、纸张纹理和字体兜底必须有固定样本，避免视觉迁移只验证空页面。

与既有 ADR 的关系：延续 ADR-8（React + Vite）、ADR-9（shadcn/ui）和 §5.5 的真实事件流原则；不改变后端、Skill 或图谱引擎测试策略。

ADR-26：两套图谱的分工（全局 Sigma vs 社区视图）

背景：全局图从 DOM/SVG 迁到 Sigma 后，两套图谱并存：全局 Sigma（WebGL 大图）+ 社区视图（DOM/SVG 聚焦图）。两者的边界其实已在代码和 ADR-21/22/23 里实现并落地，但散落各处、没有显式定义，导致每加一个图谱功能都要重新争论边界、靠反复写「明确不做」来防守。本 ADR 把已实现的边界正面固化，作为后续图谱演进的裁判。

决策：

全局 Sigma 是「总览图」：服务「整个库长什么样、我在哪、整体结构怎样」；关系边克制（低权重、不画虚实）——WebGL 大图逐条画 dash 不现实，且全局图目的是概览不是精读；强营销 + 导航属性。
社区视图是「关系工具」：服务「这一簇内部到底是什么关系」；完整呈现关系边（颜色=关系类型、虚实=置信度）、二跳关系聚焦、hover tooltip、键盘可聚焦——这些是 WebGL 大图给不了的；只对中小社区是完整工具，超大社区（>1000 节点）克制呈现为轮廓/轻量地图。
切分原则：凡是「对一组页面做事」（总结/找缺口/生成主题页/探索关系/对话）走抽屉（与渲染无关，本质是选区 = 批量 @）；凡是「看清一组页面之间的关系」走社区视图。全局 Sigma 负责「发现和圈选」，社区视图负责「细看关系」，抽屉负责「理解 + 动作」。
进入心智——两步、不直跳：全局图点社区先打开抽屉（摘要 + 结构状态），由抽屉的「进入社区」按钮才切到社区视图；全局侧点社区会进 spotlight 高亮态（阶段 4.8）给地图反馈，但不等于进入社区视图；抽屉是「是否进社区」的决策点，其结构状态（清晰/松散）是分流信号，具体分流实现见统一社区抽屉 plan。
演进红线：社区视图迁 Sigma 现在明确不做，除非 Sigma 能在中小图上低成本做出「二跳聚焦 + 虚实边 + 可访问性」同等富交互且不牺牲大图性能；全局 Sigma 上移社区视图能力只在某项能力证明全局也有高频价值且 WebGL 能承担时考虑；新增第三套图谱（如嵌入布局投影图）需先证明它解决的是前两套都解决不了的问题。

与既有 ADR 的关系：提炼并正面固化 ADR-21（一个引擎两宿主、选区=批量@）、ADR-22（图谱负责关系、抽屉负责内容）、ADR-23（全局克制、局部完整）里已隐含的分工；不改变任何已实现的代码边界，本 ADR 是把代码事实文档化。

何时重新评估：见决策第 5 条演进红线；另外若用户实测发现「进入社区」频次异常低、或社区视图的差异化能力长期无人使用，需重新审视切分原则是否成立。

8. 给 0 代码作者的盲区与协作规则

8.1 环境陷阱

macOS 默认 Node 版本可能旧。统一用 mise 或 nvm 管理 Node 版本，锁到 >=22.19.0（pi-coding-agent 0.75.x 的硬要求）。否则 npm install 就直接报错
不要全局 npm install -g。每个项目用 package.json 锁版本
API key 完全不进我们的仓库，也不进 ~/.llm-wiki-agent/。统一由 pi-agent SDK 管理，落到 ~/.pi/agent/auth.json（权限 0600）。详见 ADR-13

8.2 进度陷阱

"差一点就跑通了"是最危险的状态。验收标准要严格，跑不通就不进下一阶段
AI 协作最大的隐性风险：你不懂代码 → AI 改 A 引起 B 坏，你不知道 → 雪球越滚越大
- 对策：每阶段结束让 AI 主动列出"本次改了哪些文件、新增了什么依赖、为什么"，你看明白再确认
Git 是你的安全网。每个验收节点 commit 一次。

8.3 协作规则（AI 必须遵守）

不要自由发挥。每次动手前先说"打算改哪些文件、为什么这么改、对其他部分有什么影响"，作者确认后再动
任何要新增依赖（npm package、Skill、配置项），先问"这是 PRODUCT.md 里规划过的吗"
任何要修改 PRODUCT.md 之外的决策，先说明"这与 PRODUCT.md 第 X.Y 节冲突，建议修改文档为 Z"，等作者拍板
作者思路断了的时候，先读 PRODUCT.md，不要急着问"我们做到哪里了"——日志和 git 记录是事实，文档是意图，两个对照看
绝不主动跳阶段。阶段二验收不过，不允许动阶段三的代码

8.4 心态陷阱

0 代码做出本地工具是可行的，但**"做出来"和"做得好"差距很大**
阶段一跑通会有巨大成就感，但 80% 时间在阶段二-四
桌面打包（阶段五）是难度峰值，会卡很多坑
接受"中途某个设计要推倒重来"——写进 ADR 比硬撑下去更省力

9. 待决事项

记录尚未拍板但要在未来某阶段决定的事。决定后移到 ADR。

编号	事项	现状	何时定
~~TBD-1~~	~~项目正式名~~	已定：`llm-wiki-agent`。桌面应用显示名留到阶段五前再定	✅
TBD-2	默认模型	阶段 3.5 已落地：双角色 `modelRoles.{main, digest}` 写入 `~/.llm-wiki-agent/config.json`；main 角色用于主对话，digest 角色用于批量消化。详见 ADR-18	✅
~~TBD-3~~	~~多库会话隔离~~	已定：会话绑定知识库，同库支持多并行对话（见 ADR-12）	✅
TBD-4	危险操作确认	删除 / 覆盖类是否弹窗	阶段二
~~TBD-5~~	~~API key 配置 UI~~	已定：三层 fallback（pi CLI 登录 / UI 填 key / env var），统一存 `~/.pi/agent/auth.json`（见 ADR-13）	✅
TBD-6	知识库导入导出	是否需要打包导出格式	阶段四后
~~TBD-7~~	~~知识库根目录~~	已定：默认 `~/llm-wiki/` + 外部目录登记（见 ADR-11）	✅
TBD-8	HTML 产出 Skill	用现成的还是自建	阶段三

10. 进度追踪

阶段一：主干打通 ✅ 已完成 2026-05-26

#	任务	Commit
1	仓库骨架：`package.json` / `.gitignore` / `README.md` / `LICENSE` / `tsconfig.json`	`81ddb29`
2	后端骨架：Node + Hono，最小 `/api/echo`	`5ffd2c0`
3	前端骨架：Vite + React + shadcn/ui + SSE echo 排练	`3662b60`
4	接入 pi-coding-agent SDK，实现真 agent 对话	`c4e0dad`
5	第一个 Extension：注入 `currentKnowledgeBase` 上下文	`ebe054b`
6	知识库扫描接口：扫 `~/llm-wiki/` + 读 `config.json` 外部库	`daebc62`
7	前端知识库选择 UI + 三栏布局雏形	`49dc00e`
8	同库多对话 + 切换 + 持久化（阶段一完结）	`75e176b`
–	review 修补：一行 `npm run dev` / auto-restore / 默认深色 / 顶部状态条占位	`f835433`
–	TBD-2 删 Sonnet 表述 + 光标真闪烁	`dd021bc`

阶段一完成情况详见 §4 阶段一末尾的"完成情况"小节。

阶段二：核心循环（@、/、结晶、消化）✅ 已完成 2026-05-27

最终 PR：#1 feat: complete stage 2 core loop（base: main, head: stage-2）

8 step commit + 5 fix commit + 1 doc 修订 commit：

#	任务	Commit
1	`/sediment` Extension：结晶对话到 `wiki/synthesis/sessions/`	`fe54d47`
2	`/new-wiki` Extension：spawn `init-wiki.sh` 新建库	`5ab13dc`
3	`/api/refs`：候选页面列表（递归 fingerprint 缓存）	`b0802b8`
4	`/api/commands`：内置 + Skill 命令合并（TBD-1 方案 B）	`202bf4d`
5	设置面板：API key 三层认证 + 测试连接（TBD-2 方案 B）	`3654791`
6	`/` 命令补全 UI（cmdk）	`b6dffc0`
7	`@` 补全 + 右抽屉 + markdown 渲染（react-markdown）	`7801d2c`
8	消化新素材 chip	`7a46f4b`
–	fix: 设置面板可关闭	`c045b9e`
–	fix: `/api/commands` 包含 Claude skill	`791d73a`
–	fix: agent resource loader 加载 Claude skill 目录	`f990229`
–	fix: 新建库 UI 端点 + refs cache fingerprint 升级 + Sidebar 加按钮	`a088b97`
–	fix: 右抽屉支持 Esc 关闭	`2686b51`
–	docs(stage-2): 闭合验收 issue #2/#3/#4 + 标 TBD-3 已解决	`208ad4d`

阶段二完成情况 ✅ 2026-05-27（合并 PR #1 后）

范围 7 项全部交付（@、/、/sediment、/new-wiki、链接预览、消化、设置面板）
验收 3 条全过：建库 / 消化→讨论→结晶闭环 / API key 落 ~/.pi/agent/auth.json
关键架构决策：D9 能力归属原则（消化等知识库本职 → Skill；对话结晶等 agent 元能力 → Extension）落地，对应 ADR-16 长期合并愿景
超出原设计的增强：
- POST /api/knowledge-bases/new + NewWikiDialog（UI 直接建库，不必先与 agent 对话）
- pages.ts cache 升级 mtime → 递归 fingerprint（修了"嵌套新建后 refs 看不到"的潜在 bug）
- wiki-init.ts::findInitScript() 兼容 init-wiki.sh 在 skill 根目录或 scripts/ 两种位置
接受的妥协（不阻塞阶段三）：
- 设置面板只做认证 Tab（默认模型 / 根目录 / 外部库管理推迟）
- Anthropic 测试连接未跑（缺 key），但代码路径同 DeepSeek 一致
新增依赖：见 §3.2 + ADR-17

阶段三：产出能力（产品亮点）✅ 已完成 2026-05-27

最终分支：stage-3（base: main, head: 1f1f591）

8 step commit + 1 fix commit：

#	任务	Commit
1	vendor 4 个 anthropics Skills + 收紧命令源标签	`6d2e218`
2	产物 manifest 存储 + CRUD API	`f19687c`
3	导出按钮 + prompt 模板（3 通道触发）	`bf6b878`
4	产物右抽屉多 Tab 切换	`bc70b2c`
5	HtmlRenderer：iframe sandbox 预览	`862265a`
6	DownloadOnlyRenderer：元数据卡片 + 下载	`38006a7`
7	全局 Skill 可见性开关（settings toggle）	`1016601`
8	产物工作流 UX 打磨	`91a9761`
–	fix: 修复导出工作流 review 问题	`1f1f591`

阶段三完成情况 ✅ 2026-05-27（审查通过，合并到 main）

范围全部交付：5 个导出按钮（PDF/Word/PPT/Excel/HTML）+ 4 个 vendored Skills + 2 个 Extension 工具 + 6 个新 API + 1 个新 SSE event
关键架构决策：E13（D9 落地）——产出操作走 Skill，prepare_artifact / finalize_artifact 作为 agent 元能力 Extension；HTML 导出不依赖 Skill，由 agent 内置能力直接生成
新增 4 个端点：GET /api/artifacts、GET /api/artifacts/:id、GET /api/artifacts/:id/files/:filename、POST /api/config + GET /api/config 扩展 showUserGlobalSkills
安全验证通过：path traversal 防护、iframe sandbox（无 allow-same-origin）、UIID 验证、文件名净化
接受的妥协（不阻塞阶段四）：
- PPTX 在浏览器内无预览（DownloadOnlyRenderer），设计文档原定的 PPTXjs 方案未落地
- HTML 导出不依赖外部 Skill，由 agent 内置 fs 能力直接生成（TBD-5 方案）
新增依赖：无（0 个新 npm package）

阶段 3.5：导航 UX 重构 + 多模型子代理批量消化 ✅ 已完成 2026-05-27

当前状态：已合并到 main 并推送；阶段性分支已清理

7 step 概览：

#	任务	状态
1	侧栏重构：统一 KB 列表 + 折叠对话子树	✅
2	拖拽 + 输入框路径填充（含 inspect 端点）	✅
3	非 wiki 目录初始化引导	✅
4	多模型双角色（main / digest）	✅
5	后端子代理批量消化框架	✅
6	批量消化 UI + SSE 进度推送	✅
7	总验收 + UX 体感打磨	✅

关键风险：

TBD-3.5-1：子代理 session 共享 authStorage / modelRegistry 的资源生命周期未实测（codex 起手第一件事写 60 行验证）
TBD-3.5-2：init-wiki.sh 就地初始化会写入固定文件，必须先做冲突检测与备份（Step 3 起手看源码确认文件列表）
TBD-3.5-3：main 角色已接管主对话；设置切换后重载当前活跃对话

验收实况：

npm run --silent typecheck 通过
node --import tsx --test server/src/digest/concurrency.test.ts 通过
本地接口实测通过：目录 inspect、初始化冲突 409、就地初始化成功、模型列表、模型角色保存、批量消化参数校验
单文件批量消化真实跑通，SSE 返回 start / file_start / file_complete / done，并写入 wiki/synthesis/sessions/
验收后补强：批量消化改为逐文件失败隔离，进度面板显示每个文件状态、生成字数和结果入口；外部目录批量消化改用 inspect 扫描凭据，不再信任前端传任意 sourceRoot；初始化后批量消化可临时选择 digest 模型
收尾补强：当前知识库自动检索已落地；批量消化后直接提问会先检索当前知识库，普通寒暄和导出指令不会误触发检索
UI 视觉迁移补强：基于本地原型 index.html 统一工作台视觉，补齐浅色 / 深色主题切换；保持原有侧栏、对话、引用、命令、产物抽屉、设置、批量消化流程不变，不新增依赖
预览布局补强：侧栏可折叠为 52px 窄图标栏，右抽屉支持拖动调宽和双击恢复默认宽度；折叠状态与抽屉宽度保存在本机；移动端继续使用全屏抽屉
设置面板补强：设置弹窗限制最大高度，标题区保留在顶部，设置内容在弹窗内部滚动；底部 Skill 加载区在较矮屏幕下也可达

阶段四：monorepo 合并 + 图谱活地图 ✅ 已完成 2026-06-12

当前状态：已在主仓库 stage-4 分支完成。8 个 Step 均有提交或人工验收证据，最终自动化检查全绿；视觉一致性、拖动手感、墨夜观感保留为验收人主观判断项。

8 Step 概览：

#	任务	状态
0	monorepo 搬家（subtree + workspace 根 + 冒烟）	✅
1	引擎包骨架 + helpers TS 化 + 测试迁移	✅
2	工作台图谱视图静态复现（安全网基线）+ 主题 token	✅
3	活模拟 + 钉扎 + 持久化	✅
4	选区系统 + 对话联动	✅
5	文件监听 + 重算链 + 生长动画	✅
6	Skill 离线 HTML 切换引擎产物	✅
7	总验收 + 墨夜打磨	✅

关键风险处理结果（详见设计文档 §7）：根 package.json 未设置 type:module；手绘路径采用帧缓存；macOS Node 22 原生 fs.watch recursive 实测可用，未引入 chokidar；subtree 与提交前隐私路径检查均通过。

设计来源：2026-06-12 四轮设计对话（战略定位 → 选区 → 钉扎持久化 → 生长事件链 → 引擎抽取），关键结论沉淀为 ADR-20 / ADR-21。

阶段 4.5：图谱可用性收尾 ✅ 已合入 2026-06-14

当前状态：已合入。决策记录见 ADR-22。

设计来源：作者实测五问题（缩放缺失 / 点击语义错位 / Shift 不可发现 / 无搜索图例 / 节点过胖）+ 阶段四验收的离线功能减配裁决。两处上游盲区已在设计中修正：stage-4 plan 漏列画布导航 WU；stage-4 D6 映射表缺单节点行。

阶段 4.6：图谱演进第一批 ✅ 已完成 2026-06-14

当前状态：已完成并通过总验收。关系类型和置信度已分字段，渲染用关系类型控制颜色、置信度控制虚实；社区聚焦、类型筛选、顶部工具条、边图例、双宿主分工均已落地。决策记录见 ADR-23，ADR-21 已同步 4.6 对社区交互和工具条的修订。

阶段 4.7：图谱交互地基重构 ✅ 已完成 2026-06-16

当前状态：已完成核心交互地基。滚轮缩放、拖拽、点击、悬停、社区色块、小地图边界在工作台与离线 HTML 中保持同一套行为；社区色块是视觉提示，不是拖动围栏。

后续触发门：空间索引、Canvas/WebGL、密度策略重做、小地图拖拽导航都不属于本阶段；只有真实使用或性能证据证明需要时再启动。

阶段 4.8：图谱演进——全局社区高亮（spotlight）✅ 已落地

当前状态：已落地。点社区在全局高亮、不进入社区视图；复用现有 selection（社区）视觉链路补节点弱化 + 相机动画，不复用 focus、不新增平行状态。#75 已补齐动画期间 overlay 轻量跟随和结束后精确校准。

阶段五：未开始（Tauri 打包已决策推迟，见 ADR-20）

协作约定（持续生效）

每一步动手前 AI 都要先说计划，作者确认后再动。每完成一步：

AI 列改动清单（文件、依赖、决策）
作者确认理解
AI 创建 git commit（commit message 含本步范围 + 实测验收要点）
进入下一步

附录 A：术语表

术语	解释
Skill	Anthropic 提出的能力包格式：一个目录 + 一份 SKILL.md。详见 agentskills.io
pi-agent	TypeScript agent runtime，原生支持 Skill 标准。`@earendil-works/pi-coding-agent`
SSE	Server-Sent Events，服务器单向推送事件给浏览器的 HTTP 标准
Extension	pi-agent 的扩展机制：TS 模块，能注册自定义 tool / 命令 / 拦截事件 / 持有状态
Tauri	用系统 webview + Rust 后端打包跨平台桌面应用的框架，二进制和内存占用通常显著低于 Electron
Hono	轻量 TypeScript web 框架，跑 Node / Bun / Deno / Cloudflare 都行
shadcn/ui	组件库，但代码是直接复制到你仓库的（不是 npm 黑盒），方便修改
结晶 / 沉淀	把对话内容固化为 wiki 页面的动作（继承自 llm-wiki-skill 术语）

附录 B：参考链接

pi-agent 仓库：https://github.com/earendil-works/pi
pi-agent Skill 文档：packages/coding-agent/docs/skills.md
pi-agent SDK 文档：packages/coding-agent/docs/sdk.md
pi-agent Extension 文档：packages/coding-agent/docs/extensions.md
llm-wiki-skill 仓库：https://github.com/sdyckjq-lab/llm-wiki-skill
Anthropic Skill 标准：https://agentskills.io/specification
Anthropic 官方 Skills：https://github.com/anthropics/skills
pi-skills：https://github.com/badlogic/pi-skills
Tauri 文档：https://tauri.app/
shadcn/ui：https://ui.shadcn.com/

本文档第一版完成于 2026-05-26。后续更新请在文末追加 changelog。

Changelog

2026-06-27 v22（全局 Sigma 缩放手感修复 #73）：修掉全局图谱触控板/滚轮缩放的"按档位卡顿"
- 根因：wheel 路径在相机动画进行中时改走 animate({duration:1})，被 Sigma 的 rAF 重入切成离散跳变，违背设计 §5"滚轮直接更新相机、不排队动画"
- 修复：wheel 无条件走 camera.setState（即时）；handleSigmaWheelZoom 补 destroyed 守卫；同步更新测试断言与盲区注释
- 验证：单元 460 pass；浏览器生产回归 33 records / 3 shapes PASS；实机确认手感改善
- 已知局限：合成 wheel 事件测不准真实触控板"积压"，手感以实机为准（测试已加注释）
- 分支 codex/fix-global-graph-zoom-controls，9 个 commit（05be23d..9c897cf）
- 后续债务：sigma-global-renderer.ts 又涨到 1566 行，拆分已立项 #77（承接 #64）
2026-06-20 v21（Paper UI 立项与文档对齐）：确认工作台默认外观迁移为 Paper 暖纸
- §5.2 顶部状态条改为统一顶栏：知识库静态展示，搜索、模型、新对话、主题、外观和设置集中在全局操作区
- §5.4 视觉风格改为默认浅色暖纸、夜灯可切、Plus Jakarta Sans / Caveat / JetBrains Mono 字体组合
- §7 新增 ADR-24（Paper 暖纸视觉方向与外观偏好）与 ADR-25（前端交互测试与 Paper 视觉回归栈）
- 明确图谱画布内部 Paper 化和真实跨库 / 全文搜索后端后置
2026-06-16 v20（阶段 4.7 图谱交互地基完成）：补记图谱交互地基重构
- §4 新增阶段 4.7：记录缩放、拖拽、点击、悬停、社区色块、小地图边界统一为同一张地图心智
- 明确社区色块是视觉提示，不是拖动围栏；节点可离开色块，社区归属仍由真实链接决定
- 明确空间索引、Canvas/WebGL、密度策略重做、小地图拖拽导航均需真实使用或性能证据触发，不属于本阶段
- §10 新增阶段 4.7 状态，方便后续恢复上下文
2026-06-14 v19（阶段 4.6 实施完成）：图谱演进第一批完成并同步文档
- §4 / §10 阶段 4.6 状态改为已完成，记录工具条、社区聚焦、类型筛选、关系边图例、双宿主分工的验收结果
- §4 图谱演进候选池标注首批已落地项；图谱增强检索明确移交 ADR-19 检索线
- §7 ADR-19 增补检索线归属说明，ADR-21 增补社区聚焦与顶部工具条修订，新增 ADR-23（关系边可视化：关系类型控制颜色、置信度控制虚实）
2026-06-14 v18（阶段 4.6 立项 + plan 审查加固）：图谱演进第一批进入执行准备
- §4 新增/修正"阶段 4.6：图谱演进第一批"：G1-1 改为先补齐关系类型 + 置信度边契约，再用关系类型控制颜色、置信度控制虚实；G1-2/G1-3/G1-4/G1-5 保持日常可用性方向
- §10 新增阶段 4.6 状态；阶段 4.5 状态同步为已合入，避免后续执行误判基线
- 图谱演进候选池修正"关系类型上边"的现状描述：关系词汇表与置信度体系已有，但当前边 type 不是关系类型
2026-06-15 v18（对话工具状态体验）：补记 omp 风格动态工具状态已落地
- §5.4 增加工作台对话区工具状态原则：当前 assistant 回复只保留一个动态工具条，完成后折叠为分组摘要，停止时保留取消状态
- §5.5 更新等待状态表述：不做空白思考动画，改用动态工具状态和流式文本
2026-06-13 v17（图谱演进候选池）：行业全景分析沉淀进"阶段后规划"
- §4 阶段后规划新增"图谱演进候选池"：统领判断（两条行业尸检教训）+ 推荐切片 7 项（局部图/路径讲解/lint 上图/关系类型上边/过滤器/导出美图/图谱增强检索）+ 远期池 4 项（绑定消化管线升级批次）+ 明确不做 3 项（3D/白板化/WebGL 重写）+ 竞品技术参考存档
- 定位：4.5 之后再排期，防止思考成果丢失；4.5 范围不受影响
2026-06-13 v16（阶段 4.5 设计完成）：图谱可用性收尾设计定稿
- §4 新增"阶段 4.5：图谱可用性收尾"小节（P0 画布导航 + P0 点击语义重构 + P1 搜索/图例/Shift + P2 节点瘦身 + 抽屉瘦身定稿）
- §7 新增 ADR-22（图谱交互模型："点击即阅读，选区即升级"；抽屉负责内容、图谱负责关系、派生信息不重复；动作映射表必须全覆盖；画布导航为地基能力）——修订 ADR-21 第 5 条选区面板形态
- §10 新增阶段 4.5 小节
- 上游盲区修正记录：stage-4 plan 漏列画布导航；stage-4 D6 映射表缺单节点行
2026-06-12 v15（阶段四实施完成）：阶段四 8 Step 完成并回填进度
- §4 / §10 阶段四状态改为完成；记录总验收自动化检查通过，主观视觉/手感项交由验收人判断
- §10 阶段四 8 Step 全部打勾；补记 fs.watch、根 package 类型、路径隐私检查等关键风险处理结果
2026-06-12 v14（阶段四设计完成）：monorepo 合并 + 图谱活地图设计定稿
- §4 阶段四整节改写："图谱集成" → "monorepo 合并 + 图谱活地图"（8 Step + 7 条验收）
- §7 新增 ADR-20（阶段四启动 monorepo 合并丙方案：subtree 进 workbench/、引擎落 packages/graph-engine/、只做工程合并不做品牌动作、Tauri 推迟）与 ADR-21（图谱引擎与活地图：一个引擎两个宿主、新骨架旧器官、活模拟+钉扎、位置/结构分权、选区=批量@、文件监听重算链、diff 生长动画、山水/墨夜双主题）
- §1.3 补"阶段四起合并启动"段落（一个产品、两扇门）
- §10 阶段四小节：设计完成状态 + 8 Step 占位 + 4 项关键风险；阶段五标注 Tauri 推迟
- 阶段四设计细则已归档为本地资料
2026-05-28 v13（设置面板滚动修复）：补记设置弹窗高度与内部滚动修复
- 设置面板限制最大高度，避免底部设置被屏幕遮住
- 设置内容区改为内部滚动，标题和关闭按钮保留在顶部
- 设置面板滚动修复的设计与验证记录已归档为本地资料
2026-05-28 v12（阶段 3.5 预览布局收尾）：补记可拖动预览区与侧栏折叠
- 右抽屉支持拖动左边缘调整预览宽度，双击恢复默认宽度；宽度保存在本机
- 左侧栏支持折叠为 52px 窄图标栏，保留核心入口并提供悬停提示；折叠状态保存在本机
- 小屏幕下保持原有全屏抽屉方式，不启用拖动
- 可调预览布局的设计与验证记录已归档为本地资料
2026-05-28 v11（阶段 3.5 UI 收尾）：补记原计划外的 UI 原型迁移
- 基于本地原型 index.html 统一工作台视觉，覆盖侧栏、顶部状态条、对话区、输入区、@ / / 菜单、右抽屉、设置和批量消化面板
- 增加浅色 / 深色主题切换，默认深色，用户选择保存在本机
- 保持阶段 3.5 既有产品范围，不新增 npm 依赖；本次属于收尾视觉补强，不改变知识库和 agent 行为
2026-05-28 v10（阶段 3.5 收尾）：阶段 3.5 收尾补强完成，准备合并推送
- 新增当前知识库自动检索：主对话提问时后端先检索当前 KB 并注入上下文，避免批量消化后模型反问用户提供文章
- query_knowledge_base 工具与 /api/prompt 共用同一套检索逻辑，ADR-19 已写入 §7
- 检索失败降级为普通对话并写 retrieval 日志；寒暄、/ 命令、导出产物指令不会误触发检索
- 验证覆盖：检索单测、并发单测、类型检查、真实接口总结/寒暄/导出三条路径
2026-05-27 v9（阶段 3.5 完成）：阶段 3.5 实施完成并本地验证
- 侧栏统一、拖拽/输入路径检查、非 wiki 目录初始化、多模型角色、批量消化子代理、SSE 进度浮窗均已落地
- 保持零新增 npm 依赖；main 角色已接管主对话，digest 角色用于批量消化
2026-05-27 v8（阶段 3.5 设计完成）：阶段 3.5 设计完成，待 codex 实施
- §4 新增"阶段 3.5：导航 UX 重构 + 多模型子代理批量消化"小节，列出背景、7 step 范围、5 条验收标准、设计文档指引
- §7 新增 ADR-18：阶段 3.5 多模型双角色 + 轻量子代理框架（9 条核心决策 + 与既有 ADR 关系 + 重新评估触发条件）
- §9 TBD-2 状态更新："阶段三再做"→"阶段 3.5 落地中"
- §10 新增"阶段 3.5"小节：当前分支 stage-3.5、设计文档链接、7 step 占位、3 个关键风险
- 阶段 3.5 设计细则已归档为本地资料
2026-05-26 v7（阶段一完成标记）：阶段一全部 step + review 修补完成，作者确认 MVP 可用
- §4 阶段一标题加 ✅ 已完成 2026-05-26
- §4 阶段一末尾新增"完成情况"小节：含最终 commit、验收实况、接受的妥协、启动 & 运行速查表（compact 后从这里恢复上下文）
- §10 重命名 "下一步行动" → "进度追踪"：阶段一 8 step + 2 review commit 全部 ✅ + commit hash 表；阶段二预占骨架（7 项待办）；阶段三/四/五标 "未开始"
- 协作约定移到 §10 末尾，作为持续生效条款
2026-05-26 v6：
- TBD-2 表述改：删"阶段一固定 Claude Sonnet"，改为"沿用 pi-agent 默认设置"。实际作者通过 pi-agent 的 provider 体系接入了其他 provider（如 zai/glm-5.1），llm-wiki-agent 本不该假设固定 Sonnet
- §阶段后规划"多模型路由"措辞更通用，不锁死 Anthropic
- 微调：ChatPanel 流式光标 animate-pulse → 自定义 animate-cursor-blink（1s steps 真闪烁，原 pulse 在 ▍ 粗块上视觉太弱）
2026-05-26 v5（阶段一完结 review 修补）：实际 review 阶段一代码对照文档，发现并修复 3 项硬 gap、4 项偏差对齐
- 修 Gap 1：根 package.json 加 npm run dev 一行起两个服务（用 concurrently，符合 §4 阶段一范围第 1 条）
- 修 Gap 2：AppConfig 加 lastUsedKbPath；selectKb/selectConversation/createNewConversation 写入；agent.bootstrapFromConfig() 启动时 await 恢复（符合 §5.1.1）
- 修 Gap 3：web/index.html <html class="dark">（符合 §5.4 "默认深色"）
- §5.2 顶部状态条占位：ChatPanel header 加 🤖 模型 显示（disabled，从后端返回的 active.model 拿真实 provider/id）+ ⚙ 设置 占位按钮，tooltip 标注"阶段二/三补"
- §5.5 严禁项对齐：删除 "等待 agent 响应…" 文字提示；streaming 时最后一个 assistant 气泡显示 ▍ 光标
- §5.4 等宽字体：index.css 加 --font-mono (JetBrains Mono / SF Mono stack) 给 code/pre/kbd/samp 元素
- 后端 /api/knowledge-base GET/POST、/api/conversations POST、/api/conversations/new POST 全部在 active 上返回 model: { provider, id } | null
- 明确推迟到阶段二/三：§5.1 侧栏底部"图谱入口"延迟（阶段四，作者要重新构思）；"设置入口"占位放在 ChatPanel header（阶段二补完整面板）
2026-05-26 v4 (review pass)：基于源码/文档验证，修复 5 项事实错误 + 4 项精确化 + 3 项软化/标注
- 修：§3.1 架构图知识库路径 ~/wikis/ → ~/llm-wiki/，并补充 ~/.pi/agent/auth.json
- 修：§6.2 知识库目录补 wiki/comparisons/、wiki/overview.md、.wiki-tmp/、.gitignore（依据 scripts/init-wiki.sh 实际行为）
- 修：§8.1 删除"API key 走 config.json"过期描述，改为引用 ADR-13
- 修：§9 TBD-5 已定描述同步到 ADR-13 现状
- 加：Node 版本要求 >=22.19.0（pi-coding-agent 0.75.x 硬要求，写入 §3.2、§3.4、§8.1）
- 加：§3.4 补充 Extension 注入方式（SDK 用 bindExtensions / ResourceLoader，不依赖 CLI 全局发现）
- 加：§6.4 Obsidian 忽略列表补 .wiki-tmp/ 和 dev 类目录
- 加：§2.3 anthropics/skills 列出 17+ 个实际 Skill，不止"四件套"
- 软：§3.2 "Tauri 比 Electron 轻 10×" → "二进制和内存通常显著低于 Electron（5-30 MB vs 100+ MB）"
- 软：§3.2 mise 描述更准确为"多语言版本管理（含 Node）"
- 标：§3.3 流程中的 /api/* 路径标注为"建议命名，最终以实现为准"
- 标：§阶段三 PPTX 渲染库删除错误链接，明确"阶段三选型"
2026-05-26 v1：第一版完成，确立产品定位、5 阶段路线、9 条 ADR、协作规则。
2026-05-26 v2：
- 新增 3.4 节《pi-agent 的使用方式》，明确"npm 依赖，不 clone 不 fork"
- 新增 5.1.1 节《会话与切换行为》，定义并行对话与切库自动保存
- 重写 6.1 节《知识库存储策略》，从单一目录改为"默认 ~/llm-wiki/ + 外部登记"混合策略
- 新增 6.4 节《Obsidian 共存规则》，明确 agent 不碰的文件类型
- 新增 6.6 节《中文路径与 UTF-8 铁律》
- 新增 ADR-10 ~ ADR-15 六条决策
- TBD-1 / TBD-3 / TBD-5 / TBD-7 关闭并归档到 ADR
- TBD-2 改为阶段三才决定（阶段一固定 Sonnet）
- 阶段一范围补充：知识库扫描含外部库登记、多并行对话支持
- 阶段二范围补充：内置 /new-wiki 命令、设置面板 UI
2026-05-26 v3：
- 新增 6.7 节《边界场景行为约定》：单实例、无网络/无 key、崩溃恢复、后端未起、目录失效
- 重写 ADR-13：模型认证完全复用 pi-agent 的 ~/.pi/agent/auth.json，三层 fallback（pi CLI 登录 / UI 填 key / env var）；config.json 不再存任何凭证
- 新增 ADR-13b：明确不抄 open-design 的多 CLI 子进程模式
- 重写 6.3 应用数据目录，澄清"应用数据 / 知识库数据 / 模型凭证"三类彻底分离
- 阶段二范围细化：设置面板 UI 改为"三层认证 + 偏好"，验收标准更新
2026-05-27 v9（阶段三完成标记）：阶段三全部 8 step + 1 fix commit 完成，审查通过合并到 main
- §4 阶段三标题加 ✅ 已完成 2026-05-27
- §10 阶段三标记已完成，补充 9 commit 表 + 完成情况（范围、决策、妥协）
- CLAUDE.md 更新"项目当前阶段"：阶段二 → 阶段三

103 KiB Raw Blame History Unescape Escape

llm-wiki-agent 产品文档

0. 这份文档怎么用

1. 产品定位

1.1 一句话定位

1.2 核心场景

1.3 与 llm-wiki-skill 的关系

1.4 这个项目"不是什么"

2. 核心理念

2.1 Code is cheap，未来人视角

2.2 桌面应用而非托管

2.3 Skill 即插即用

2.4 对话中心

3. 架构总览

3.1 系统层次

3.2 技术栈

3.3 关键流程：一次对话发生了什么

3.4 pi-agent 的使用方式

4. 功能阶段路线

阶段一：主干打通（最小可用） ✅ 已完成 2026-05-26

阶段二：核心循环（@、/、结晶、消化）✅ 已完成 2026-05-27

阶段三：产出能力（产品亮点）✅ 已完成 2026-05-27

阶段 3.5：导航 UX 重构 + 多模型子代理批量消化 ✅ 已完成 2026-05-27

阶段四：monorepo 合并 + 图谱活地图 ✅ 已完成 2026-06-12

阶段 4.5：图谱可用性收尾 ✅ 已合入 2026-06-14

阶段 4.6：图谱演进第一批（看清关系 + 层层聚焦 + 控制工具条）✅ 已完成 2026-06-14

阶段 4.7：图谱交互地基重构 ✅ 已完成 2026-06-16

阶段 4.8：图谱演进——全局社区高亮（spotlight）✅ 已落地

阶段五：桌面应用打包（Tauri）

阶段后规划（暂不锁定，记录想法）

图谱演进候选池（2026-06-13 全景分析沉淀；首批已落地为「阶段 4.6」，见上文 §阶段 4.6）

5. UI 设计原则

5.1 三栏布局

5.1.1 会话与切换行为

5.2 顶栏

5.3 @ 与 / 的设计契约

5.4 视觉风格

5.5 严禁项

6. 数据与目录约定

6.1 知识库存储策略（混合模式）

6.2 知识库目录结构（沿用 llm-wiki-skill）

6.3 应用数据目录

6.4 Obsidian / 第三方工具共存规则

6.5 运行时应用状态（由 Extension 持有）

6.6 中文路径与 UTF-8 铁律

6.7 边界场景行为约定

7. 关键决策记录（ADR）

ADR-1：选 pi-agent 而非 Vercel AI SDK / Mastra

ADR-2：对话中心而非图谱中心

ADR-3：SSE 而非 WebSocket

ADR-4：先 web 再 Tauri 打包

ADR-5：不用 MCP

ADR-6：完全进化为 agent，不维护双通道

ADR-7：知识库上下文用 Extension 注入，不拼 prompt

ADR-8：React + Vite 而非 Next.js

ADR-9：UI 用 shadcn/ui

ADR-10：pi-agent 作为 npm 依赖，不 fork、不 clone 源码

ADR-11：知识库采用混合存储策略（默认根 + 外部登记）

ADR-12：会话绑定知识库，同库支持多并行对话

ADR-13：模型认证完全复用 pi-agent 的 auth 体系（三层 fallback）

ADR-13b：不抄 open-design 的"多 CLI 子进程"模式

ADR-14：app 内一键新建知识库

ADR-15：Obsidian 共存（agent 忽略非 markdown 与第三方元数据）

ADR-16：长期与 llm-wiki 仓库合并（agent 是 Skill 的升级版）

ADR-17：阶段二新增前端依赖（react-markdown + cmdk）

ADR-18：阶段 3.5 多模型双角色 + 轻量子代理框架

ADR-19：主对话引入“系统检索 + 上下文注入”

ADR-20：阶段四启动 monorepo 合并（丙方案）

ADR-21：图谱引擎与活地图（一个引擎、两个宿主）

ADR-22：图谱交互模型——点击即阅读，选区即升级

ADR-23：关系边可视化采用“关系类型控制颜色、置信度控制虚实”

ADR-24：Paper 暖纸视觉方向与外观偏好

ADR-25：前端交互测试与 Paper 视觉回归栈

ADR-26：两套图谱的分工（全局 Sigma vs 社区视图）

8. 给 0 代码作者的盲区与协作规则

8.1 环境陷阱

8.2 进度陷阱

8.3 协作规则（AI 必须遵守）

8.4 心态陷阱

9. 待决事项

103 KiB

Raw Blame History

5.3 `@` 与 `/` 的设计契约