1. 项目概述从沉睡的对话记录到可搜索的知识库如果你和我一样每天花大量时间与Claude Code、Cursor、GitHub Copilot这类AI编程助手对话那么你的电脑里一定散落着成百上千个.jsonl格式的会话文件。它们静静地躺在~/.claude/projects/、~/.codex/sessions/这些目录里记录了你每一次的提问、每一次的代码修改、每一次的调试过程。这些文件是宝贵的知识矿藏但绝大多数时候它们只是硬盘上的一堆“数字灰尘”——你几乎不会再回头去看更别提从中系统地提取知识了。llm-wiki就是为了解决这个问题而生的。它是一个纯Python编写的开源工具核心使命就一句话把你和AI助手的所有对话历史自动转换成一个结构清晰、可搜索、可链接的静态知识库网站。这个想法并非凭空而来它严格遵循了AI领域知名研究者Andrej Karpathy提出的“LLM Wiki”模式。Karpathy在他的 著名gist 中勾勒了一个三层知识管理架构而llm-wiki就是这个架构的一个完整、可运行的生产级实现。想象一下你不再需要手动整理笔记。每次与Claude讨论完一个复杂的API设计或者用Cursor重构了一个模块相关的对话、代码片段、决策理由都会被自动捕获、清洗、归类并融入到你的个人知识图谱中。几天或几周后当你在另一个项目中遇到类似问题时你可以像使用维基百科一样通过全局搜索、分类浏览或内部链接瞬间找到当初的解决方案和上下文。这不仅仅是“搜索历史记录”而是将碎片化的对话升维成了结构化的、可生长的知识体。这个工具特别适合三类人一是重度依赖AI编程助手的开发者他们需要管理海量的技术对话二是知识管理爱好者或研究者他们希望系统化地沉淀与AI协作产生的见解三是任何希望将自己的数字工作流“产品化”的人他们不满足于工具只是工具更希望工具能产出可复用的知识资产。接下来我将带你深入这个项目的肌理看看它是如何工作的以及你如何能将它无缝集成到自己的日常开发流程中。2. 核心架构与设计哲学拆解要理解llm-wiki必须从它的“三层架构”说起。这是Karpathy模式的核心也是llm-wiki区别于简单日志查看器的根本。2.1 三层架构从原始数据到智慧结晶第一层是raw/原始源。这一层是神圣不可侵犯的“事实层”。llm-wiki会从你配置的各种AI助手目录中找到原始的.jsonl会话文件并将它们原样但经过必要的敏感信息脱敏转换为Markdown格式按项目和日期组织在raw/sessions/目录下。这些文件是只读的代表了最原始、未经加工的对话记录。它们的存在保证了知识的可追溯性——你永远可以回到最初的对话去核对细节。第二层是wiki/维基层。这是知识的“加工层”和“连接层”。llm-wiki或者更准确地说由它驱动的一个AI智能体会读取raw/层的内容并按照预设的认知框架自动生成一系列相互链接的维基页面。这个框架通常包括sources/: 对原始会话的摘要和提炼。entities/: 识别出的具体实体如User用户类、PaymentService支付服务类。concepts/: 抽象出的概念如RESTful API DesignRESTful API设计、Database Migration Strategy数据库迁移策略。syntheses/: 对多个相关会话或概念的综合性分析文章。comparisons/: 对不同技术方案、工具或模型的对比分析。questions/: 将对话中提出的有价值问题单独提炼成页面便于后续追踪和解答。这些页面之间通过[[wikilinks]]双中括号链接紧密相连形成了一个网状的知识结构。这是知识从“记录”走向“体系”的关键一步。第三层是导航与模式文件。这包括CLAUDE.md、AGENTS.md、MEMORY.md等文件。它们的作用是“教导”你的AI助手如Claude Code如何与这个维基系统互动。例如CLAUDE.md会告诉Claude“当你需要为我编写代码时请先查阅wiki/目录下的相关页面了解我们之前达成的共识和设计决策。” 这相当于为你的AI助手植入了“公司记忆”或“项目上下文”让每次协作都能站在历史经验的肩膀上。设计考量为什么坚持静态生成动态数据库不是更强大吗llm-wiki选择静态站点生成site/目录的HTML文件是基于几个核心考量极致的可移植性和零运维成本。生成的site/文件夹可以扔到任何静态托管服务GitHub Pages, Netlify, Vercel上立即拥有一个可公开或私密访问的知识库。没有数据库意味着没有迁移、备份、性能调优的烦恼。隐私与安全所有数据处理都在本地完成敏感信息在raw/层即被脱敏最终生成的静态站不包含任何动态逻辑或API密钥。版本控制友好wiki/目录下的Markdown文件本身就是纯文本完美契合Git知识库的每一次演进都可以被清晰地记录和回溯。2.2 适配器模式连接多元化的AI工作流现代开发者的AI工作流是碎片化的。你可能在VS Code里用GitHub Copilot在独立窗口用Claude Code思考架构在终端用Codex CLI快速生成脚本又在Obsidian里记录灵感。llm-wiki通过“适配器Adapter”模式优雅地解决了多数据源的问题。每一个适配器都是一个独立的Python模块如llmwiki.adapters.claude_code它只做两件事1.知道去哪里找数据例如Claude Code适配器知道会话文件在~/.claude/projects/project_name/sessions/目录下2.知道如何解析数据将特定格式的.jsonl转换为llm-wiki内部统一的会话对象。这种设计带来了巨大的灵活性扩展容易为一个新的AI工具比如未来某款新出的IDE插件添加支持通常只需要实现一个几十行代码的适配器类。互不干扰各适配器独立工作一个解析失败不会影响其他数据源的导入。配置清晰在config.json中你可以为每个适配器单独配置路径、过滤规则等。目前官方支持的适配器几乎覆盖了主流选择Claude Code、Codex CLI、Cursor、GitHub CopilotChat和CLI、Gemini CLI甚至还能直接读取Obsidian笔记库和PDF文件作为知识源。这种广度的支持确保了无论你的技术栈如何组合llm-wiki都能成为那个统一的“知识收集中枢”。2.3 双格式输出为人也为AI这是llm-wiki从v0.4版本开始的一个革命性特性。传统的知识库工具只考虑人类读者但llm-wiki认为在AI时代知识库的消费者同样包括其他AI智能体。对于每一个生成的HTML页面例如site/sessions/my-project/2024-04-10-api-design.htmlllm-wiki会同时生成两个“兄弟文件”page.txt: 纯文本版本移除了所有HTML标签和样式只保留最核心的文本内容。这非常适合直接粘贴到LLM的上下文窗口中进行问答。page.json: 结构化的元数据正文内容采用机器易于解析的格式如JSON-LD。这为AI Agent提供了编程式访问内容的接口。不仅如此在站点根目录它还提供了一系列AI友好的入口点/llms.txt: 遵循 llmstxt.org 规范提供一个简明的站点内容索引告诉AI“这个网站里有什么”。/llms-full.txt: 一个扁平化的、包含所有页面核心文本的巨型文件通常有容量上限如5MB可以作为RAG检索增强生成系统的知识源直接使用。/graph.jsonld: 整个知识图谱的结构化表示使用Schema.org词汇表描述实体、概念和来源之间的关系。/ai-readme.md: 专门写给AI看的导航说明。这意味着你构建的这个知识库不仅可以通过浏览器供你查阅还可以通过MCPModel Context Protocol服务器让你桌面上的Claude Desktop、Cursor等AI客户端直接查询、检索其中的知识。你的个人知识库成了一个可以被AI调用的“外部大脑”。3. 从零开始安装、配置与首次构建实战理论说再多不如亲手跑一遍。下面我将以macOS/Linux环境为例带你完成一次完整的llm-wiki部署和初体验。Windows用户过程类似只需将脚本后缀从.sh改为.bat。3.1 环境准备与一键安装首先确保你的系统已经安装了Python 3.9或更高版本以及Git。然后打开终端执行以下命令# 1. 克隆仓库 git clone https://github.com/Pratiyush/llm-wiki.git cd llm-wiki # 2. 运行安装脚本 ./setup.sh这个setup.sh脚本做了以下几件关键事情创建数据目录在项目根目录下初始化raw/、wiki/、site/三个核心文件夹。安装Python包以“可编辑”模式-e安装llmwiki包及其依赖。这意味着你对源码的修改会立即生效便于开发调试。探测并配置适配器脚本会自动扫描你的系统寻找已安装的AI工具如Claude Code、Cursor的默认数据目录。如果找到它会提示你是否要启用对应的适配器。安装SessionStart钩子可选对于Claude Code用户脚本会询问你是否要将一个同步钩子安装到~/.claude/settings.json中。如果同意此后每次启动Claude Code它都会在后台自动运行一次llmwiki sync实现会话的实时同步。这是一个极大提升体验的功能建议开启。执行首次同步脚本最后会运行一次初始同步让你立刻能看到一些输出确认安装成功。安装过程是幂等的你可以安全地多次运行./setup.sh它不会破坏已有的数据。3.2 核心配置文件详解安装完成后你需要关注一个核心文件config.json。llm-wiki的所有行为都由此文件控制。项目提供了一个模板examples/sessions_config.json你需要将其复制并自定义cp examples/sessions_config.json config.json让我们打开这个config.json看看几个关键配置项{ filters: { live_session_minutes: 60, exclude_projects: [temp, playground] }, redaction: { real_username: your_github_username, replacement_username: USER, extra_patterns: [ (?i)(api[_-]?key|secret|token|bearer|password)\\s*[:]\\s*[\\\][^\\\][\\\], sk-[A-Za-z0-9]{20,}, \\b[A-Za-z0-9._%-][A-Za-z0-9.-]\\.[A-Z|a-z]{2,}\\b ] }, truncation: { tool_result_chars: 500, bash_stdout_lines: 5 }, adapters: { obsidian: { vault_paths: [/path/to/your/Obsidian Vault] }, claude_code: { session_path_pattern: ~/.claude/projects/*/sessions/*.jsonl } }, build: { auto_lint: true, theme: dark } }filters.live_session_minutes: 这个参数非常实用。假设你设置值为60那么只有过去60分钟内更新过的会话才会被纳入本次同步。这避免了每次构建都全量处理成百上千的历史文件极大提升了增量同步的速度。对于日常使用设置为60或1202小时是个不错的起点。redaction:这是隐私保护的基石。real_username是你的系统用户名或GitHub用户名llm-wiki会在输出中将其统一替换为replacement_username如“USER”。extra_patterns是正则表达式列表用于匹配并替换敏感信息如API密钥、密码、电子邮件等。强烈建议你根据自己项目的实际情况仔细审查和补充这里的正则表达式。truncation: AI会话中经常包含大段的工具执行结果如终端输出。全部展示会淹没重点。这里可以设置截断长度例如工具结果只显示前500个字符bash命令输出只显示前5行。adapters: 在这里为每个适配器指定精确的路径。例如如果你的Obsidian仓库不在默认位置就在这里修改vault_paths。build.auto_lint: 如果设为true每次构建静态站点前会自动对wiki/目录运行一次lint检查检查死链、孤立页面等确保输出质量。实操心得配置的优先级llm-wiki的配置加载顺序是1. 代码内默认值 - 2.config.json- 3. 环境变量 - 4. 命令行参数。这意味着你可以通过命令行临时覆盖配置例如llmwiki sync --live-session-minutes 30。灵活利用这个特性可以在不同场景下快速切换配置。3.3 执行首次构建与本地预览配置完成后构建你的第一个知识库网站就只需要两行命令# 1. 同步数据并构建网站 ./build.sh # 或者分步执行 # llmwiki sync # 同步原始会话到 raw/并触发AI生成 wiki/ # llmwiki build # 将 wiki/ 编译成静态网站到 site/ # 2. 启动本地服务器预览 ./serve.sh # 这会在 http://127.0.0.1:8765 启动一个本地HTTP服务器打开浏览器访问http://127.0.0.1:8765你应该就能看到你的知识库网站了。如果这是第一次运行wiki/目录可能还是空的因为AI生成层需要你手动触发或配置自动处理。别急我们稍后会解决。此时你的目录结构应该大致如下llm-wiki/ ├── config.json ├── raw/ # 第一层原始会话 (Markdown格式) │ └── sessions/ │ └── your-project/ │ └── 2024-04-10-some-chat.md ├── wiki/ # 第二层AI生成的维基 │ ├── sources/ │ ├── entities/ │ ├── concepts/ │ ├── syntheses/ │ ├── comparisons/ │ ├── questions/ │ ├── CLAUDE.md │ └── AGENTS.md └── site/ # 第三层生成的静态网站 ├── index.html ├── sessions/ │ └── your-project/ │ └── 2024-04-10-some-chat.html ├── llms.txt ├── graph.jsonld └── ... (其他静态资源)3.4 连接AI生成层让知识自动生长到目前为止我们只完成了数据同步raw/和静态发布site/。最关键的“知识提炼”层wiki/还是空的。llm-wiki的设计是这一层应由一个AI智能体比如Claude Code来填充。你需要“教导”你的AI助手如何完成这个工作。项目在wiki/目录下预置了几个关键的导航文件尤其是CLAUDE.md和AGENTS.md。你需要做的是在Claude Code或其他AI助手中打开llm-wiki项目。将wiki/CLAUDE.md的内容作为系统提示词或上下文提供给AI。这个文件详细说明了AI的任务读取raw/sessions/下的新文件按照指定的模板和规则在wiki/的相应子目录下创建或更新页面并使用[[wikilinks]]建立链接。你可以直接对AI下指令比如“请根据CLAUDE.md的指引处理raw/sessions/中所有尚未被处理的会话文件生成维基页面。”更自动化的方式是使用llm-wiki提供的MCP服务器。如前所述配置好MCP后你的AI桌面客户端可以直接调用wiki_sync等工具。或者你可以设置一个定时任务如每小时一次自动运行一个脚本该脚本调用AI API如OpenAI API、Anthropic API并附上CLAUDE.md作为指令让AI处理新增的raw/文件。注意事项AI生成层的成本与可控性让AI自动生成维基内容会消耗API调用产生费用。建议先从少量会话开始测试确保生成质量符合预期。此外AI的生成具有不确定性。虽然CLAUDE.md提供了详细的规则和模板但输出仍需人工审阅。llm-wiki的“lint”功能后面会讲可以帮助你检查一些结构性问题但内容的准确性和深度最终需要你自己把关。可以将此视为一个“AI辅助的知识整理”过程而非全自动流水线。4. 核心功能深度解析与日常使用当你的知识库运行起来后llm-wiki提供的远不止一个简单的文件列表。它是一套完整的知识管理和检索系统。4.1 丰富的站点功能与用户体验访问本地服务后你会发现这个静态网站的功能异常丰富全局模糊搜索CmdK按下CmdK或CtrlK会唤出一个命令面板支持模糊搜索所有页面标题和内容。这是最常用的导航方式。活动热力图主页上展示了一个类似GitHub贡献图的热力图直观显示你在不同日期的知识产出密度。会话详情页每个会话都被渲染成清晰的对话形式代码块由highlight.js进行语法高亮工具调用结果可以折叠/展开。页面底部还有“相关页面”推荐。模型信息卡片与对比页自动从会话元数据中提取使用的AI模型信息生成结构化的卡片并可以生成不同模型之间的对比页面。响应式设计与深色模式网站完美适配手机和桌面并支持跟随系统或手动切换深色/浅色主题。键盘导航除了搜索还可以用g h跳转首页g p跳转项目页j/k在列表间上下移动?查看所有快捷键。这些功能共同打造了一个不亚于专业Wiki软件的用户体验而这一切都通过静态HTML实现无需任何后端服务器。4.2 强大的命令行接口CLIllm-wiki的核心是一个功能丰富的CLI工具llmwiki。除了最基础的sync,build,serve还有许多高级命令# 查看所有可用命令 llmwiki --help # 1. 质量评估与检查 llmwiki eval # 对wiki进行7个维度的结构质量评分满分100 llmwiki lint # 运行11条lint规则检查8条基础3条LLM驱动的语义检查 llmwiki check-links # 检查site/中的所有内部链接是否有效 # 2. 导出与集成 llmwiki export-obsidian # 将整个wiki目录符号链接或复制到Obsidian仓库 llmwiki export qmd # 导出为Quarto Markdown文档集合 llmwiki export marp # 导出为Marp幻灯片 # 3. 高级知识操作 llmwiki graph # 重新生成知识图谱graph.jsonld llmwiki synthesize # 运行自动摘要与合成管道需要AI参与 llmwiki watch # 启动文件监视器raw/或源目录有变化时自动同步 # 4. 系统维护 llmwiki adapters # 列出所有适配器及其配置状态 llmwiki install-skills # 将.claude/skills/下的技能文件同步到其他AI助手目录 llmwiki schedule # 生成操作系统级的定时任务配置launchd, systemd, Task Scheduler每个子命令都有详细的--help信息。例如想了解lint具体检查什么可以运行llmwiki lint --help。4.3 与Obsidian深度集成v1.0核心特性对于Obsidian用户来说llm-wiki的v1.0版本带来了近乎原生的集成体验。这不仅仅是导出文件而是双向的工作流融合。一键链接运行llmwiki link-obsidian它会在你的Obsidian仓库中创建一个指向llm-wiki/wiki/目录的符号链接或快捷方式。这样你在Obsidian的图谱视图、反向链接面板、全局搜索中就能直接操作和查询llm-wiki生成的所有页面。任何在Obsidian中对链接文件的修改也会实时反映在wiki/目录中。Dataview仪表盘llm-wiki为Obsidian的Dataview插件预置了10个开箱即用的查询模板。你可以在Obsidian中创建一个笔记嵌入类似下面的查询立刻得到一个动态仪表盘dataview TABLE file.mtime as Last Updated, confidence as Confidence FROM wiki WHERE lifecycle draft SORT file.mtime DESC LIMIT 10 这个查询会列出所有状态为“草稿”的页面及其最后修改时间和置信度评分。Templater模板llm-wiki提供了4个针对不同页面类型来源、实体、概念、综合的Templater模板。当你在Obsidian中通过快捷键创建新页面时可以选择这些模板它们会自动填充好Frontmatter如confidence: 0.75、lifecycle: draft、created: {{date}}让你快速遵循llm-wiki的页面规范。分类页面无论是通过Dataview动态生成还是通过llmwiki build生成静态页面你都可以基于标签tags来浏览内容。例如所有标记为#python的页面会自动聚合在一个分类页下。这种深度集成意味着你可以继续使用你最熟悉的Obsidian进行知识的日常管理和编辑同时享受llm-wiki在自动化采集、结构化生成和静态发布方面的强大能力。两者形成了一个完美的互补闭环。4.4 基于MCP的AI原生查询MCPModel Context Protocol是一个新兴的协议旨在标准化AI应用与工具之间的通信。llm-wiki内置了一个MCP服务器这意味着任何支持MCP的客户端如Claude Desktop、Cursor、Cline都可以直接查询你的知识库。配置好MCP后通常在客户端的配置文件中添加几行你就可以在AI助手的对话窗口中直接使用自然语言查询你的wiki。例如你可以问“在我的知识库里关于‘用户认证’我们都讨论过哪些方案” AI助手会通过MCP调用wiki_query或wiki_search工具获取相关页面内容并基于此给你一个综合性的回答。这彻底改变了知识库的访问方式。你不再需要离开编程环境或聊天窗口去手动搜索你的AI助手本身就成为了知识库最自然的交互界面。5. 质量保障、自动化与维护策略一个无人维护的知识库很快就会变成数字废墟。llm-wiki内置了一系列机制来保障知识库的质量和活性。5.1 置信度评分与生命周期管理llm-wiki为每个维基页面引入了两个核心元数据置信度Confidence和生命周期Lifecycle。四因子置信度评分这不是一个主观评分而是基于四个客观因素的计算结果来源数量Source Count支撑这个页面结论的原始会话raw/中的文件有多少个越多越可信。来源质量Source Quality这些原始会话是否来自可靠的上下文如详细的代码评审对话 vs. 随意的提问系统会根据会话长度、工具使用情况等赋予权重。时效性Recency信息是否过时基于艾宾浩斯遗忘曲线时间越久远置信度衰减越多。交叉引用Cross-references是否有其他高置信度的页面引用了此页面被引用越多可信度越高。最终置信度是一个0到1之间的分数在页面Frontmatter中以confidence: 0.82的形式呈现。你可以在搜索和浏览时以此排序优先关注高置信度内容。五状态生命周期机每个页面都处于以下一种状态并在Frontmatter中用lifecycle: reviewed标记draft草稿AI初步生成尚未经人审阅。reviewed已审阅经过人工快速检查基本无误。verified已验证经过严格验证或在实际工作中被成功应用。stale陈旧超过90天未更新系统自动标记。提示内容可能已过时。archived已归档明确不再适用或已被新方案取代。这套机制让知识库具备了“自我管理”的雏形。你可以编写一个简单的脚本定期找出stale或低confidence的页面推送到你的待办清单中进行复审。5.2 自动化Lint与质量检查手动维护链接和页面状态是痛苦的。llm-wiki的llmwiki lint命令自动化了这项工作。它包含14条规则分为三类8条结构性规则检查Frontmatter完整性、内部链接是否断裂、是否存在孤立页面无入链、页面新鲜度、重复内容、索引同步等。3条LLM驱动的语义规则实验性利用AI需要配置API来检查页面间是否存在矛盾陈述、关键事实是否需要验证、摘要是否准确反映了原文。这部分虽然强大但运行成本较高建议在关键页面或定期如每周运行。3条高级规则如stale_candidates识别可能陈旧的页面、tags_topics_convention检查标签命名规范、stale_reference_detection检测页面是否引用了陈旧的内容。定期运行lint可以配置在build前自动运行就像为你的知识库做“代码健康检查”能提前发现并修复许多问题。5.3 “自动织梦”与导航文件“Auto Dream”是llm-wiki一个颇具诗意的功能。它本质上是一个知识压缩与记忆巩固的过程。当wiki/目录下的页面数量超过一定阈值例如24小时内新增了5个以上会话系统会自动触发一个后台任务读取MEMORY.md文件如果存在。扫描wiki/中所有新生成的或高优先级的页面。使用AI需配置对这些内容进行总结、去重、提炼并将关键信息以结构化的方式追加到MEMORY.md中。同时它会尝试解决相对日期如“昨天”、“上周”并移除过时或已被覆盖的信息。最终MEMORY.md文件会被限制在200行以内保持简洁。MEMORY.md、CLAUDE.md、AGENTS.md、CRITICAL_FACTS.md等9个导航文件共同构成了你知识库的“元知识”或“操作手册”。它们告诉AI也提醒你这个知识库的重点是什么、如何与它互动、哪些是最关键不容出错的事实。5.4 设置自动化同步流水线为了让知识库真正“活”起来你需要建立自动化的数据流水线。llm-wiki提供了多种方式SessionStart钩子最推荐如前所述在Claude Code等工具的配置中设置每次启动工具时自动同步。文件监视器运行llmwiki watch它会持续监控配置的源目录如~/.claude/projects/一旦检测到新的.jsonl文件在防抖延迟后自动触发sync和build。系统定时任务使用llmwiki schedule命令它可以为你生成对应操作系统的定时任务配置文件。macOS: 生成launchd.plist文件用launchctl加载。Linux: 生成systemd.timer和.service文件。Windows: 生成task.xml文件可通过任务计划程序导入。 你可以设置每小时、每天或每周同步一次。一个健壮的组合是SessionStart钩子用于实时性要求高的场景 每日一次的定时任务用于全面扫描和构建。这样既能保证新对话及时入库又能通过每日构建运行完整的lint检查和站点更新。6. 高级主题定制化、问题排查与社区贡献当你熟练使用基础功能后可能会需要一些更高级的定制或遇到一些问题。本章节将探讨这些进阶话题。6.1 自定义适配器与数据源llm-wiki的适配器框架是开放的。假设你使用一个叫“DeepSeek Coder”的新工具它将会话保存在~/.deepseek/sessions/目录下格式是.json。为其添加支持非常简单在llmwiki/adapters/目录下创建一个新文件例如deepseek_coder.py。定义一个继承自BaseAdapter的类。实现几个关键方法get_session_files(): 返回该工具所有会话文件的路径列表。parse_session_file(filepath): 将.json文件解析为llm-wiki内部统一的Session对象。SUPPORTED_SCHEMA_VERSIONS: 声明支持的会话模式版本。# llmwiki/adapters/deepseek_coder.py from pathlib import Path from .base import BaseAdapter, Session class DeepSeekCoderAdapter(BaseAdapter): NAME deepseek_coder DISPLAY_NAME DeepSeek Coder SUPPORTED_SCHEMA_VERSIONS {1.0, 1.1} def get_session_files(self): # 实现查找~/.deepseek/sessions/下所有.json文件的逻辑 deepseek_path Path.home() / .deepseek / sessions return list(deepseek_path.glob(**/*.json)) def parse_session_file(self, filepath): # 实现解析逻辑返回Session对象 with open(filepath, r) as f: data json.load(f) # ... 将data转换为Session ... return session在llmwiki/adapters/__init__.py中注册这个新适配器。在config.json的adapters部分添加配置。通过这种方式你可以将任何能导出结构化对话记录的工具接入llm-wiki不断扩展你的个人知识网络。6.2 常见问题与排查指南即使设计再完善在实际使用中也可能遇到问题。以下是一些常见场景及其解决方法问题一运行./build.sh后site/目录是空的或者页面显示“No sessions found”。可能原因1sync过程没有找到任何会话文件。排查运行llmwiki adapters检查各个适配器的状态是否为“enabled”以及“sessions found”数量是否大于0。如果为0检查config.json中对应适配器的路径配置是否正确或者你的AI工具是否确实生成了会话文件。可能原因2filters.live_session_minutes设置过小过滤掉了所有历史会话。排查临时修改config.json将live_session_minutes设置为一个很大的数如525600一年重新运行sync和build。可能原因3wiki/目录为空导致build时无内容可编译。排查检查wiki/目录下是否有CLAUDE.md等导航文件。如果没有运行llmwiki init重新初始化。然后你需要按照前面所述手动或通过AI生成层来填充wiki/的内容。问题二生成的HTML页面中代码没有语法高亮。可能原因页面无法加载highlight.js CDN资源网络问题或者构建时未正确识别代码块语言。排查打开浏览器开发者工具查看Console和Network标签页确认https://cdnjs.cloudflare.com/ajax/libs/highlight.js/...这个资源是否加载成功。如果因网络问题失败可以考虑修改构建模板使用本地托管的highlight.js或者直接禁用高亮在配置中设置syntax_highlighting: false。问题三llmwiki lint报告大量“Broken wikilink”错误。可能原因AI在生成[[wikilinks]]时链接的目标页面尚未创建或者页面标题/文件名后来发生了变更。解决这是一个知识库演进过程中的正常现象。你可以运行llmwiki check-links获取更详细的报告。手动修复那些确实重要的断裂链接。或者接受一定程度的断裂链接将其视为“待创建页面”的待办事项。llm-wiki的搜索功能足够强大即使链接断裂用户仍能通过搜索找到内容。问题四同步速度很慢尤其是历史会话很多时。优化建议合理设置filters.live_session_minutes只同步近期活跃的会话。使用.llmwikiignore文件忽略那些你确定不需要纳入知识库的项目或日期范围的会话。考虑将sync和build分离。可以设置一个高频的sync如每小时只更新raw/和wiki/而build生成静态站点则可以每天或每周运行一次因为这部分计算开销较大。6.3 参与贡献与扩展生态llm-wiki是一个活跃的开源项目欢迎贡献。在动手之前请务必阅读CONTRIBUTING.md文件。其中几个关键原则保持PR的专注性一个PR只解决一个问题或添加一个功能。使用规范的提交前缀如feat:新功能、fix:修复bug、docs:文档更新、chore:维护任务、test:测试相关。绝对不要提交真实会话数据raw/目录已被.gitignore忽略测试请使用examples/demo-sessions/下的模拟数据。确保CI通过项目有完善的单元测试和端到端测试你的代码需要通过所有检查。你可以从以下几个方面入手贡献修复Bug在GitHub Issues中寻找标记为good first issue或bug的问题。改进文档翻译文档目前已有中文、日文、西班牙文翻译、完善教程、修复错别字。开发新适配器为你常用的、尚未被支持的工具编写适配器。增强现有功能例如为搜索增加更多筛选器为图表增加新的可视化类型或者优化构建性能。项目的维护结构非常清晰docs/maintainers/目录下有一整套维护者指南包括架构决策、代码审查清单、发布流程等确保了项目在快速发展中仍能保持高质量和一致性。7. 总结与展望构建属于你的第二大脑回顾整个llm-wiki的旅程它本质上是在做一件事将你与AI协作过程中产生的、非结构化的对话流转化为结构化的、可检索的、可生长的知识资产。它不是一个要你改变工作流的工具而是一个在你现有工作流下游默默工作的“知识炼金术士”。从技术角度看它巧妙地结合了Karpathy的前瞻性设计模式、静态站点生成的简洁可靠、适配器模式的扩展性以及对AI原生工作流如MCP的深度支持。从用户体验看它提供了从命令行到Web界面从人类浏览到AI查询的全方位交互方式。我个人在深度使用几个月后最大的体会是它极大地降低了我“害怕遗忘”的焦虑。以前一个复杂的解决方案讨论完就沉没在聊天历史中下次遇到类似问题要么凭模糊记忆重试要么花大量时间重新搜索和实验。现在我知道所有这些对话都被妥善地整理、链接、评分并可以通过自然语言随时召回。它成了我技术决策的“外部验证库”和“灵感来源”。最后分享一个我自己的小技巧我将llmwiki serve生成的本地站点地址添加到了浏览器的“常用搜索引擎”中。这样当我在地址栏输入wiki加空格再输入关键词就能直接在我的个人知识库中搜索就像使用Google一样自然。这个小小的集成让知识检索变成了肌肉记忆的一部分。llm-wiki仍然在快速演进中v1.1.0的路线图上已经规划了交互式图谱查看器、Ollama集成、提示词缓存等令人兴奋的功能。无论你是想立即用它来管理你的AI对话历史还是对其架构设计感兴趣想学习借鉴抑或是想参与一个充满活力的开源项目这个仓库都值得你投入时间。开始构建你的“第二大脑”吧它或许会成为你未来生产力提升中最关键的一块拼图。