notra

Notra

Notra 是一套面向 Codex 与 Claude Code 的项目知识沉淀工具。它把长期项目里的代码实践、推荐方案、会话结论和证据关系保存到项目自己的 .notra/ 目录中，让后续对话可以先查已有实践，再决定是否扫描项目代码。

它的目标不是替代代码仓库，也不是保存完整代码片段，而是让 AI 在多轮任务中逐步形成“这个项目通常怎么做”的可检索知识库。

解决的问题

长期项目里，AI 协作常见几个问题：

• 每次对话都像第一次看项目，重复翻同一批代码。
• 同一类场景会出现多个实现，缺少稳定推荐。
• 任务结束后的决策没有沉淀，下次无法复用。
• 知识库越来越大后，直接塞进上下文会浪费 token。
• 临时计划文件、worktree 文件和会被删除的文档容易污染长期证据。

Notra 的做法是：

• 任务开始前用 notra:notra-preflight 查已有实践和推荐方案。
• 任务结束后用 notra:notra-auto-crystallize 自动记录采纳和孵化知识。
• 用采纳次数、分数和治理规则维护推荐池。
• 每个实践最多保留 3 个推荐方案，其余退回孵化或等待处理。
• 只返回 Top-K 实践和 evidence 预览，避免把整个知识库放进上下文。

核心模型

.notra/ 是项目级知识库，也是 Markdown 事实源。图谱、索引、Obsidian 视图都是从这些 Markdown 文件生成出来的。

主要节点类型：

• project_profile：项目画像，记录技术栈、默认规则和偏好方案。
• practice：可复用实践，例如“HTTP 调用应统一封装”。
• option：实践下的候选方案，例如“统一 client”或“直接调用”。
• rule：约束性规则。
• context / constraint：适用场景和限制条件。
• session：一次任务的历史记录。

知识生命周期：

• 新知识默认进入 incubating。
• 多次被采纳后成为转正候选。
• 推荐池最多保留 3 个方案。
• 被淘汰或人工打回的方案不会直接删除，会退回孵化区并标记状态。

证据规则

source_evidence 只应该指向长期存在的项目源码相对路径，例如：

src/api/client.ts
src/runtime/scheduler.ts

这些路径不会作为长期证据：

• .worktrees/
• .notra/
• .agents/
• .codex/
• node_modules/
• docs/
• task_plan.md
• findings.md
• progress.md

原因是这些内容经常是临时计划、协作过程文件、生成物或后续可能被清理的文档。它们可以帮助当前对话理解上下文，但不能支撑长期推荐实践。

项目也不保存完整代码片段作为主证据。推荐的证据形态是：

• 稳定源码相对路径
• 实践摘要
• 方案摘要
• 采纳次数
• 必要时由后续版本扩展 symbol、hash 或短摘要

安装

1. 获取仓库并安装依赖

git clone <repository-url>
cd <repository-directory>

安装后可以先运行测试确认环境可用：

npm test

2. 作为普通 CLI 使用

不安装 Codex plugin 也可以直接通过 npm 脚本使用：

npm run notra:init -- <project-root>
npm run notra:preflight -- <project-root> "实现 HTTP 调用"
npm run notra:auto-crystallize -- <project-root> <auto-crystallize-input.json>

这种方式适合手动执行脚本，或者在其它自动化流程里调用。

3. 安装为 Codex 技能包

如果希望在 Codex 对话中直接使用 notra:* 技能，执行：

npm run codex:install

该命令会：

• 在 ~/plugins/notra 创建指向当前仓库 plugins/notra/ 的本地插件链接。
• 在 ~/.agents/plugins/marketplace.json 写入 notra marketplace 条目。
• 使用 INSTALLED_BY_DEFAULT，让 Codex 启动时自动发现技能包。

安装后需要完全重启 Codex。重启后在技能列表中应该能看到：

notra:notra-init
notra:notra-preflight
notra:notra-status
notra:notra-graph
notra:notra-crystallize
notra:notra-auto-crystallize
notra:notra-lint
notra:notra-govern
notra:notra-serve

升级当前仓库后，可以重新执行：

npm run codex:install

卸载：

npm run codex:uninstall

4. 安装为 Claude Code 插件

在 Claude Code 对话中直接使用 notra 技能：

/plugin marketplace add <repository-root>
/plugin install notra@snailuu

例如：

/plugin marketplace add /path/to/notra
/plugin install notra@snailuu

该命令会：

• 注册 snailuu marketplace。
• 从 marketplace 安装 notra 插件。
• 在 ~/.claude/plugins/installed_plugins.json 注册 notra 插件。
• 在 ~/.claude/settings.json 的 enabledPlugins 中启用 notra 插件。

安装后需要完全重启 Claude Code，让插件在启动时被加载。重启后在技能列表中应该能看到：

notra-init
notra-preflight
notra-status
notra-graph
notra-crystallize
notra-auto-crystallize
notra-lint
notra-govern
notra-serve

升级当前仓库后，重新执行：

/plugin update notra@snailuu

卸载：

/plugin uninstall notra@snailuu

5. 初始化目标项目

安装工具后，还需要对目标项目执行初始化：

npm run notra:init -- <project-root>

或者在 Codex 中使用：

notra:notra-init

初始化后，目标项目根目录会出现 .notra/。只有存在这个目录的项目才会进入知识库流程；未初始化项目会返回 mode: no-knowledge 并跳过扫描和沉淀。

快速开始

初始化后，可以直接用 npm 脚本操作：

npm test
npm run notra:init -- <project-root>
npm run notra:preflight -- <project-root> "实现 HTTP 调用"
npm run notra:auto-crystallize -- <project-root> <auto-crystallize-input.json>
npm run notra:lint -- <project-root>
npm run notra:govern -- <project-root>
npm run notra:serve -- <project-root> 8124

如果命令不传 <project-root>，脚本会使用当前工作目录。

技能包

仓库同时内置 Codex plugin 技能包与 Claude Code 技能包。

Codex 技能

技能名如下：

notra:notra-init
notra:notra-preflight
notra:notra-status
notra:notra-graph
notra:notra-crystallize
notra:notra-auto-crystallize
notra:notra-lint
notra:notra-govern
notra:notra-serve

推荐安装方式：

npm run codex:install

它会把 plugins/notra/ 接入 Codex 的插件发现路径，并写入 marketplace 配置。安装后需要完全重启 Codex，技能列表中才会出现 notra:* 技能。

卸载：

npm run codex:uninstall

Claude Code 插件

技能名如下：

notra-init
notra-preflight
notra-status
notra-graph
notra-crystallize
notra-auto-crystallize
notra-lint
notra-govern
notra-serve

推荐安装方式：

/plugin marketplace add <repository-root>
/plugin install notra@snailuu

安装后需要完全重启 Claude Code。

卸载：

/plugin uninstall notra@snailuu

常用流程

1. 初始化项目知识库

npm run notra:init -- <project-root>

会在目标项目中创建 .notra/，包括：

• project-profile.md
• practices/
• options/
• rules/
• incubating/
• sessions/
• state/
• graph/
• _views/
• .obsidian/
• open-graph.cmd

如果项目没有初始化，notra:preflight 和 notra:auto-crystallize 会返回 mode: no-knowledge，不会扫描代码，也不会创建知识库。

2. 任务开始前预检

npm run notra:preflight -- <project-root> "实现 HTTP 调用"

预检会优先查 .notra/：