在软件开发中，代码与相关知识往往分散在不同的位置。
实现逻辑保存在代码仓库，设计方案记录在飞书或 Notion，排错经验整理在 Obsidian，模块约定可能写在某个 Markdown 文件中。开发者能够找到代码，却不一定能快速找到实现背后的原因。
接手项目时，这种信息分散尤其明显：一段重试逻辑为什么这样设计？某个判断对应什么业务约定？代码修改后，原来的说明是否仍然适用？
CodeMori 是一个本地优先的开源 IDE 知识连接工具，提供 VS Code 和 JetBrains 插件，将已有文档、代码片段与项目源码关联起来。
代码在哪，文档就在哪。
将代码与文档关联，把设计思路、团队经验、复用片段，嵌入开发工作流。
一、在源码旁找到相关说明
阅读代码时，函数名和注释能够解释部分实现，但完整的业务背景通常需要查阅其他资料。
以支付模块为例，重试代码对应的设计文档可能包含以下约定：
- 哪些异常允许重试；
- 重试次数的设置依据；
- 如何避免重复扣款；
- 失败后应该进入哪种补偿流程。
通过 CodeMori，可以为源码文件关联一篇已有文档，并填写简短摘要，例如：
超时允许重试；业务拒绝不重试；重试前检查幂等状态。
再次打开这个文件时，开发者可以在 CodeMori 面板中查看关联标题、来源和摘要，需要详细信息时再打开原文。
文档正文继续保留在原来的平台，CodeMori 负责保存入口、摘要和代码关联。
目前支持的主要来源包括：
| 文档来源 | 使用方式 |
|---|---|
| 飞书 | 关联文档链接；支持的链接提供“在飞书中打开”入口 |
| Notion | 关联页面链接，通过浏览器打开原文 |
| Obsidian | 通过 obsidian://open 链接请求客户端打开笔记 |
| 本地 Markdown | 在 IDE 中打开，并提供只读预览 |
需要注意，CodeMori 不会自动抓取远程文档全文。知识搜索主要覆盖已保存的片段、标题、标签和手填摘要，原文档的访问权限仍由对应平台管理。
二、文件与目录都可以关联文档
部分知识属于单个文件，另一些则适用于整个模块。
例如，支付模块的幂等约定、接口层的异常处理规范、数据库访问层的事务规则，通常需要覆盖多个文件。
CodeMori 支持两种关联范围：
- 文件关联：为当前源码文件添加具体说明；
- 目录关联：让目录及其子目录中的源码继承模块说明。
目录关联可以减少重复维护。开发者打开模块中的文件时，就能查看继承的文档及其来源。
这种方式适合组织模块设计、接口规范、部署说明和排错手册等资料。代码旁的文档提示也可以按需显示或隐藏，关闭提示不会删除已有资料和关联。
三、建立代码与文档的双向连接
从源码打开设计说明，只完成了一个方向的连接。阅读文档时，同样需要快速定位对应实现。
CodeMori 提供“复制代码位置链接”功能，可以将源码位置链接粘贴到设计文档、技术笔记或排错记录中。
代码链接携带项目标识、相对路径等定位信息，在项目标识一致、对应项目已打开的情况下，可以定位到本机项目副本中的代码，减少对某一台电脑绝对路径的依赖。
例如，一篇接口设计说明可以同时包含：
- 接口的业务背景；
- 关键约束及处理规则；
- 对应实现的代码位置链接。
部分文档平台会限制自定义协议链接。遇到无法直接点击的情况，可以复制链接，在 IDE 中使用“打开代码位置链接”进行定位。
四、代码变化后，提醒复核关联文档
代码与文档关联之后，还需要处理内容逐渐不一致的问题。
CodeMori 会基于已保存代码的变化，提示相关说明需要复核。开发者可以检查当前实现，必要时查看可用的 Git 差异，再判断是否需要修改文档。
如果只是调整代码格式，确认说明仍然适用，可以一键确认当前文件的待复核关联，其中也包含继承的模块关联。
这一机制保留了人工判断：
代码发生变化，意味着说明需要检查，并不意味着说明一定错误。
确认后，CodeMori 更新对应的复核基线。如果操作过程中代码或资料又发生变化，旧的确认请求会被拒绝，避免将尚未检查的新变化标记为已复核。
对于目录关联，复核涉及整个模块的对应基线，需要留意其覆盖范围。
五、个人资料与团队知识分开管理
个人开发笔记与团队公共资料有不同的使用范围。
CodeMori 将两者分开保存：
| 范围 | 保存位置 | 适合的内容 |
|---|---|---|
| 个人资料 | 用户主目录下的 .codemori |
个人片段、收藏、临时排错笔记 |
| 项目共享 | 项目中的 .codemori/ |
模块说明、团队约定、公共片段和文档关联 |
同一台电脑上的 VS Code 与 JetBrains 插件可以共用个人资料库。
需要团队协作时，保存资料可选择“项目共享（随 Git）”。共享文件经过提交和拉取后，其他成员可以查看相关资料及代码关联。记录中保留创建者和最近修改者署名，便于了解资料来源。
这种方式沿用代码仓库已有的协作流程：修改实现、整理说明、检查共享文件，再一起提交。
当前团队共享基于 Git，不提供实时多人编辑或独立的账号权限系统。共享外部文档链接，也不会自动授予原文档的访问权限。
六、保存和检索可复用代码片段
除了文档关联，CodeMori 也支持保存代码片段。
开发者可以在编辑器中选中代码，填写标题、标签和使用说明，之后通过 IDE 内的搜索找回、查看和复制。
适合保存的内容包括：
- 常用的错误处理方式；
- 配置示例和命令片段；
- 某类问题的修复方法；
- 带有使用条件的复用实现。
片段保存的是当时的快照。原文件后续发生变化时，已保存片段不会被自动覆盖；来源信息可用于找回上下文。
此外，CodeMori 支持手动索引部分语言的源码注释，目前包括 Java、JavaScript／TypeScript 和 Python，为资料检索提供额外来源。
七、内置原生核心，也提供独立 CLI
CodeMori 将资料管理、搜索、共享和复核逻辑集中在 Rust 核心中，IDE 插件负责编辑器交互和界面展示。
插件内置核心程序，日常使用无需安装 Rust、配置数据库，也不需要单独启动 CodeMori 客户端。
对于命令行和自动化场景，项目提供独立 CLI，支持：
info：查看运行信息；init：初始化数据；- JSON RPC：供脚本和其他工具调用。
项目还提供 codemori-knowledge Skill，辅助 AI 查找源码、读取关联知识，并生成带来源依据的说明草稿。
这类接入可以为代码解释补充已有设计背景，但生成内容仍需人工检查。AI 生成草稿不会自动替用户确认关联文档仍然适用。
八、当前版本与使用方式
CodeMori 当前版本为 0.1.0，采用 MIT 许可证，源码已公开。
IDE 插件提供本地安装方式：
- VS Code：通过“从 VSIX 安装”加载对应插件包；
- JetBrains：通过 Plugins → Install Plugin from Disk 加载 ZIP，无需解压。
安装包供应和插件市场上架进度，以仓库说明为准，也可以按照开发文档自行构建。
JetBrains 插件的最低版本为 2024.2，不设置最高版本限制。当前安装包已通过 IDEA 2024.2、IDEA 2026.1 和 RustRover 2026.2 的二进制 API 兼容检查，但这不等同于所有 JetBrains 产品和未来版本都已完成桌面验收。
目前 macOS 是主要验证平台，Windows 的完整实机验收仍待补齐。
对于首次体验，可以从一个具体场景开始：为一个经常修改的源码文件，关联一篇真正有用的设计文档，再填写一句能够帮助理解实现的摘要。这个过程能够直观体现 CodeMori 的使用价值——让相关知识在阅读和修改代码时更容易被找到。
项目地址：Lusyne/CodeMori
