notabene：实践指南

准备试用notabene之前，先别急着安装；这个项目提供的是在存储库文档的页边空白处留释，然后让您的 AI 代理应用它们、解决线程并记录更改的内容和原因。这类文档与演示交付工具真正难在内容结构和版式在转换后容易走样，仓库说明只能作为第一层证据。与其反复读介绍，不如拿一份结构复杂的真实文档完成转换，再依据标题层级、表格图片、字体版式和可编辑性做取舍。编辑判断上，经常交付正式文档或演示稿的团队可以优先研究它；其他团队不必为了热门标签勉强接入。

notabene

nota bene - 边距标记，表示 “请注意这一点。”

Leave 在存储库文档的页边空白处注释 - 位于渲染页面上 -

然后让您的 AI 代理应用它们，解析线程，并更改日志 what 和 why.

English · Français · Documentation

使用 LLM 迭代您的文档 - 在任何地方留下反馈，而不是挤在一个提示中。 具有多用户评论的可导航文档网站，在 git 中自行托管 - 没有 SaaS，没有 数据库。锚定评论是指令：定位、明确、无任何内容 报价。您的代理人阅读它，编辑来源，并记录更改内容和原因。

工作原理（30 秒）

1. npx notabene dev → 打开网站，选择任意文字 → 发表评论（或评论 整个页面、图表或图像）。
2. 告诉您的代理人：“解决文档评论。”
3. 代理读取 .notabene/，忠实地编辑文档，标记每条评论 已解决，并附加一个日志条目（什么/为什么/哪些评论）。
4. 阅读 /journal 的跟踪 - 或自己验证每个 真正的 git diff 批准模式。

尝试一下

npm install -D @z29k/notabene   # or pnpm / bun
npx notabene init               # writes the config, the .notabene store + the agent protocol
npx notabene dev                # → http://localhost:3009

使用克劳德代码？ /plugin marketplace add z29k/notabene 那么 /plugin install notabene@z29k - 只需说“设置 notabene”*。 → 完整安装指南

特点

每一个都是 文档 的链接 - 深入了解 仅在您好奇的地方：

• 锚定评论 - 选择 渲染页面上的文本，或评论整个页面、图表或图像。线程， 解析、按住、全局 /comments 视图，移动设备上触摸优先。
• 在页面中编辑 - 中的 ✎ margin 在您正在阅读的位置打开任何块；同样的保存关闭评论 它回答并记录变化。仅限开发，并且它拒绝写入文件 git 不是 跟踪。
• 代理审核循环 - a 任何代理都可以遵循 file-I/O-first 协议（无服务器、无端口、无 MCP）。船舶作为 克劳德密码技能；技能文件是规范。
• 两阶段审核 - 批准 模式：代理建议，您根据其真实的 git diff 验证每个编辑 （包括级联）位于 /review。
• 一个真正的文档网站 - 空格， frontmatter 驱动的侧边栏、搜索、可评论 美人鱼 图表，带有 pan/zoom 灯箱，light/dark 切换开关，反应灵敏。
• MDX 和 CommonMark/GFM - 宽松的 .md，严格的 .mdx，每个扩展可混合 - 并且 mdxComponents 发布 您自己的组件到这些页面，全局或每个空间。
• 多语言文档 - 干净 前缀 URLs，语言切换器，每种语言的注释，EN/FR/…。
• PDF 导出 - 任何页面、文件夹、 空间或整个文档：封面+浏览器中可点击的TOC，或加书签的PDF 通过 notabene pdf。
• 让它成为您的 - 定制 主页, 徽标+图标+社交卡， 导航链接 （顶栏、侧边栏块、网站页脚），并通过稳定的 --nb-* 设计代币进行主题化， 您自己的字体、代码主题或您自己的样式表（级联层安全：您的 CSS 总是赢）。
• 发布公共站点 - 一个 具有代理可读表面的只读静态构建（llms.txt，每页 Markdown 双胞胎、站点地图、OpenGraph)、私有内容范围、可选 全文 搜索（Pagefind：每种语言的词干，突出显示的摘录 - 在开发应用程序中 也），包括 GitHub 页面工作流程。 文档站点 是 notabene 自行出版。
• 链接验证 - notabene lint 根据上次构建实际发出的检查每个内部链接 - 与你的意思是建议的死链接，加上公开→私人泄露 build --public.
• git 原生商店 - 评论 + 日志作为版本 JSON 在您的存储库中：PRs 中的差异，无冲突合并， 代理可以依赖的架构。
• 默认安全 - 写入 API 仅限开发，受环回限制，CSRF/rebinding-gated；公共构建不包含任何内容。

仓库布局

• packages/renderer - @z29k/notabene npm 包（Astro 渲染器 + CLI）。
• packages/claude-plugin - 克劳德代码插件（设置 + 审查 skill/protocol）。
• docs/ - 本文档由 notabene 自己审核和发布。