---

它解决什么问题

你的笔记散落在几十个项目文件夹里：这个仓库一份 SPEC.md，那个 workspace 一堆 /teach 生成的课程。想集中翻阅？只能一个个开文件，或者复制到一处——然后副本开始过期。更别提想在沙发上用平板翻笔记：文件锁在台式机里。

lanbook 反着来：文件一个都不动。你告诉它去哪些目录找，它起一个常驻 Web 服务负责扫描、分类、渲染。原文件改了，浏览器里下一秒就变；服务挂着，同一局域网的电脑、手机、平板打开就是同一份知识库。

C:/Work/weldone/openspec/specs/...   ─┐
C:/Work/AI/lessons/*.html            ─┼─►  局域网 Web 服务  ─►  电脑 / 手机 / 平板
C:/Work/notes/*.md                   ─┘    （原地读取 · 实时刷新）

lanbook 前身是 ClaudeMd Tools，1.2.0 起以 npm 包 lanbook 发布，旧配置首次启动自动迁移。

长这样

📚 知识库视图 — 左侧目录树，右侧 Markdown 渲染 + 目录导航（TOC）

🎓 课程视图 — HTML 教学课程原样呈现

📱 跨设备 — 服务常驻，平板 / 手机连同一 Wi-Fi 随时打开

✨ 核心特性

📱 跨设备随时看（主场景）

• 服务监听所有网卡，常驻后，手机 / 平板连同一 Wi-Fi，浏览器打开 http://<电脑IP>:8080 就是完整知识库——无需同步、无需 app
• 文件在电脑上改，手机上打开的页面实时刷新（chokidar 监听 + WebSocket 推送）
• 前端三件套（marked / highlight.js / mermaid）随包本地分发，断网 / CDN 不可达也照常渲染

📚 知识库视图 — Markdown / HTML 文档

• 树形目录浏览 — 按根目录展开项目结构，空文件夹自动隐藏，多层折叠
• 原地渲染 — Markdown 带目录（TOC）、代码高亮、Mermaid 图表；HTML 用 iframe 原样展示（css/js/图片相对路径照常工作）
• 在线编辑 — 浏览器里改，保存直接写回原始文件
• 实时刷新 — 文件一变，页面自动更新（chokidar 监听 + WebSocket 推送）
• 互联 — 文档间 .md 链接可点击跳转，浏览器前进/后退正常回溯

🎓 课程视图 — /teach 生成的教学课程

• 为 Matt Pocock 的 /teach 技能生成的教学 workspace 设计：自动识别含 lessons/ 的目录，整个目录树托管（lessons/ + reference/ + assets/），课程间相对引用不断链
• 按 workspace 分组，课程 / 速查卡分类，可折叠——在平板上连载学习体验很好

🤖 AI 友好

给 AI 一个 URL，它就能自己发现并读取你的全部文档：

GET /kb                          # 列出所有文档路径（纯文本）
GET /kb/weldone                  # 列出某项目的文档
GET /kb/weldone/openspec/...md   # 直接拿到 markdown 原文

在项目的 CLAUDE.md / AGENTS.md 里加一行指向 http://localhost:8080/kb，Claude Code 等工具即可自行检索知识库——无需 JSON 解析、无需参数。

用 pi 的话还有更直接的方式：pi install npm:lanbook 后，/lanbook <文件> 直接产出可点击的渲染链接，/lanbook autostart 让服务常驻。

🚀 快速开始

两种装法，选一种就行——它们装的是同一个包，只是放在不同地方：

① 用 pi 的话（推荐）——一条命令，附带 /lanbook 命令与开机自启：

pi install npm:lanbook

然后在 pi 里：

/lanbook              # 弹出知识库文件选择器，选中即在浏览器打开
/lanbook autostart    # 注册开机自启（登录自启，崩溃自动重启，Win / macOS / Linux）
/lanbook status       # 查看服务与自启状态
/lanbook open         # 启动服务（未运行时）并打开浏览器首页
/lanbook stop         # 停止服务（先停自启守护防复活，验明身份后才杀进程）
/lanbook config       # 查看数据目录与配置文件路径；config port 8090 改端口
/lanbook autostart --prune  # 清理残留自启任务（Windows 孤儿计划任务）
/lanbook help         # 列出全部用法

pi 装的这份包里就带着完整的服务端与 CLI，不需要再 npm i -g lanbook。详见在 pi 里用 /lanbook。

② 不用 pi 的话——装成全局命令：

npm i -g lanbook
lanbook
# 打开 http://localhost:8080

不想安装？npx lanbook 先体验再决定。

首次启动是空的——点右上角 ⚙ 添加根目录（如 C:/Work），立即生效。手机 / 平板连同一 Wi-Fi，浏览器打开 http://<电脑局域网IP>:8080 即可（电脑 IP 用 ipconfig 查）。

命令行

以下命令需要装成全局（上面第 ② 种）。用 pi 装的话不必装全局——对应的 /lanbook 斜杠命令已经能做同样的事：

lanbook                    # 启动服务（默认行为）
lanbook open               # 服务未运行时后台启动，并打开浏览器
lanbook add <目录>          # 添加知识库根目录
lanbook add --teach <目录>  # 添加课程根目录
lanbook config             # 打印数据目录与三个配置文件路径（设 $EDITOR 时打开）
lanbook config port 8090   # 查看 / 设置服务配置（port、host），重启后生效
lanbook autostart          # 注册登录自启（--remove 卸载，--prune 清理残留）
lanbook stop               # 停止正在运行的服务
lanbook --version          # 显示版本号（lanbook help 查看完整帮助）

要做的事	装成全局	用 pi
开机自启	lanbook autostart	/lanbook autostart
添加根目录	lanbook add <目录>	/lanbook <目录> 或网页 ⚙
启动 / 打开	lanbook open	/lanbook open
停止服务	lanbook stop	/lanbook stop
看服务状态	—	/lanbook status
改端口 / 监听	lanbook config port 8090	/lanbook config port 8090

端口与监听地址

端口默认 8080。改端口：lanbook config port 8090；仅本机访问：lanbook config host 127.0.0.1（lanbook config <key> 可查看当前生效值与来源）。两者写入数据目录 settings.json，重启生效；临时改端口也可用环境变量 PORT=8090 lanbook。

在 pi 里用 /lanbook

包内自带 pi 扩展，装上后多一条 /lanbook 命令——既能生成浏览器链接，也能管理服务自启。

pi install npm:lanbook

/lanbook              # 弹出知识库文件选择器
/lanbook README.md    # 指定文件，输出可点击链接
/lanbook ~/docs       # 目录 → 输出知识库首页链接
/lanbook autostart    # 开启开机自启（登录自启，崩溃自动重启，Win / macOS / Linux）
/lanbook autostart --prune  # 清理残留自启任务（指向已删脚本的孤儿计划任务，Windows）
/lanbook open         # 启动服务并打开浏览器首页
/lanbook stop         # 停止服务
/lanbook status       # 查看服务与自启状态（服务没起来时先跑这个）
/lanbook config       # 查看数据目录与配置路径
/lanbook help         # 列出全部用法

只需装这一份包：pi 装的包里就带着完整的 lanbook 服务端与 CLI，因此 /lanbook autostart 一条命令即可注册开机自启，不需要再 npm i -g lanbook。自启脚本指向包内的 server.js，注册时自动写入正确路径。

链接主机名跟着服务配置走：host: 127.0.0.1 时只给回环地址并提示仅本机可用；默认 0.0.0.0 时自动挑一个局域网 IP（优先真实私网，192.168 > 10.x > 172.16-31 > Tailscale 100.64/10）。文件不在任何根目录下时会先问你要不要把它所在目录加为根目录。

升级 / 卸载后请重跑 /lanbook status：自启脚本里的 server.js 是绝对路径，若包被移除或换到另一份安装，路径会失效而任务仍显示「就绪」。/lanbook status 会直接指出路径不存在并给出修复命令（/lanbook autostart）。

从旧版手工扩展升级：早期 /lanbook 来自手工放在 ~/.pi/agent/extensions/lanbook-open.ts 的独立扩展。装上本包后请删掉它，否则同名命令会注册两次：

rm ~/.pi/agent/extensions/lanbook-open.ts

开发者选项（源码模式）

想改代码或从源码运行：

git clone https://github.com/Naoki326/ClaudeMdTools.git
cd ClaudeMdTools
npm install
npm start

源码模式与安装模式读写同一数据目录 ~/.lanbook/，两种身份一个真相；部署与常驻见 DEPLOY.md（仓库文件，npm 包内不含）。

🗂 数据目录

配置与元数据存放在用户主目录的数据目录 ~/.lanbook/（Windows 为 %USERPROFILE%\.lanbook\），不在安装目录——npm update -g lanbook 升级后配置原样保留：

~/.lanbook/
├── settings.json          # 服务配置（port / host）
├── knowledge.config.json  # 知识库根目录
├── teach.config.json      # 课程根目录
└── docs/                  # 对话元数据

• 源码模式与安装模式共用同一数据目录——git 仓库内 npm start 与全局 lanbook 看到的是同一份配置
• 自动迁移：1.1 及以前的源码用户首次以 1.2.0 启动时，安装目录里的旧配置自动拷入数据目录，旧文件原地改名 *.migrated.bak 留底，可随时回退
• 开发 / 测试隔离：环境变量 LANBOOK_HOME 可覆盖数据目录位置

🔐 安全须知：局域网读写

lanbook 默认监听 0.0.0.0，且没有鉴权。这意味着：

• 同一局域网内的任何设备都能打开页面——并且不止「读」：在线编辑会直接写回你配置的根目录里的文件，删改等同本机操作
• 适用环境：可信的家庭 / 办公内网。不要在咖啡馆、机场、会议公共 Wi-Fi 等不可信网络中运行，也不要通过端口转发、内网穿透等方式暴露到公网
• 每次启动横幅都会明示风险与全部局域网访问地址，请留意确认

如需收敛到仅本机访问：lanbook config host 127.0.0.1（等价于编辑数据目录 settings.json）：

{ "host": "127.0.0.1" }   // 重启生效；此后手机 / 平板将无法访问

⚙️ 配置根目录

三种方式，效果相同（配置写回数据目录、立即生效）：

方式一：网页里点 ⚙ — 配置对话框实时预览每个根目录扫到多少文件，加错路径当场看到（✗ 不存在 / 0 个）。

方式二：命令行 — lanbook add C:/Work（知识库）/ lanbook add --teach C:/Work/AI（课程）。

方式三：直接编辑配置文件 — lanbook config 打印路径，按需编辑：

// ~/.lanbook/knowledge.config.json
{
  "roots": ["C:/Work"],
  "excludeDirs": []   // 可选：额外排除的目录名，如 ["docs", "vendor"]
}

// ~/.lanbook/teach.config.json
{ "roots": ["C:/Work/AI"] }

仓库内的 knowledge.config.example.json / teach.config.example.json 是同内容的参考模板。

excludeDirs 说明：目录名匹配（不区分大小写、不分层级），与内置排除列表（node_modules、.git、dist 等）合并生效。适合隐藏 docs/、vendor/ 这类不想混入知识库的目录。注意它是全局的——对所有根目录生效；lanbook 自身的 docs/ 按绝对路径单独排除，不受影响。

🔁 常驻运行（开机自启）

一条命令注册，之后每次登录自动后台启动服务，进程崩溃后自动重启——不依赖 PM2 或任何外部守护进程，Windows / macOS / Linux 通用（机制映射见 ADR-0005）。

/lanbook autostart        # 用 pi 装的话（推荐）

lanbook autostart         # 装成全局的话

两种写法等价：都注册同一个自启任务（名字默认 lanbook-autostart，可用 LANBOOK_AUTOSTART_TASK 覆盖），只是自启脚本指向各自安装位置里的 server.js。注册是幂等的（重复执行覆盖旧任务；macOS / Linux 注册即启动）。

原理（三平台同一套语义，各自的系统原生机制）：

	Windows	macOS	Linux
注册产物	计划任务（登录 + 解锁双触发）+ 数据目录 VBS/CMD 守护	launchd LaunchAgent（KeepAlive 保活）	systemd user 单元（Restart=on-failure）
崩溃自愈	:loop 守护 3 秒重启（端口冲突按退出码退避）	KeepAlive 立即拉起	3 秒后重启（需 systemd >= 240）
lanbook stop	写停止标记防复活	launchctl bootout	systemctl --user stop
下次登录	任务再触发	launchd 再加载	default.target 再拉起

stdout/stderr 统一追加到 ~/.lanbook/logs/service.log；端口 / 监听地址由数据目录 settings.json 决定。stop 均为「本次停下、下次登录自启恢复」。

配套命令：

/lanbook status              # 查看服务与自启状态（含自启脚本指向是否有效）
/lanbook autostart --remove  # 卸载自启
/lanbook autostart --prune   # 清理残留自启任务（Windows，见下）

lanbook stop                  # 停止服务（先停自启守护，再按端口找进程，验证身份后才杀）
lanbook autostart --remove    # 卸载自启
lanbook autostart --prune     # 清理残留自启任务（见下）
schtasks /Run /TN lanbook-autostart        # Windows：手动立即启动一次
launchctl kickstart gui/$(id -u)/lanbook-autostart   # macOS：手动立即重启
systemctl --user restart lanbook-autostart.service   # Linux：手动立即重启

自启脚本里写的是绝对路径：卸载或换装 lanbook 后，路径可能失效，而自启任务仍显示「就绪」——故障要等到下次重启才暴露。/lanbook status 会直接报出这种状态并给出修复命令（/lanbook autostart）。

残留自启任务（Windows）

Windows 的注册产物分两半：系统侧的计划任务 + 数据目录侧的 autostart.vbs。如果数据目录先被删掉而任务还留着（Temp 被清理、LANBOOK_HOME 换位置、测试临时目录回收），就得到一个「每次登录 / 解锁都弹『无法找到脚本文件』」的孤儿任务：

Windows Script Host
  无法找到脚本文件 "C:\Users\...\AppData\Local\Temp\old-check\autostart.vbs"

lanbook autostart 注册时会自动清理这类残留；也可手动执行 lanbook autostart --prune 单独清理。认领规则是双签名 + 目标已失效——任务描述含 managed by lanbook（新注册写入），或动作是 wscript 拉起 autostart.vbs（历史任务），且目标脚本确实不存在。目标健在的任务一律不动。

崩溃自动重启由自带的守护机制提供。若需要「开机即起（无需登录）」或系统级服务，Windows 用 nssm 注册原生服务、Linux 用 systemctl --user + loginctl enable-linger，见 DEPLOY.md。

📡 API 参考

路径式 API（推荐 AI / 程序访问）

方法	路径	说明
GET	/kb	列出所有文档路径（纯文本）
GET	/kb/<project>	列出某项目的文档路径
GET	/kb/<project>/<path>	返回 .md 原文（text/plain）

知识库 JSON API

方法	路径	说明
GET	/api/knowledge	列出知识库文档（树形结构）
GET	/api/knowledge/file	读取单个 .md 文件内容
PUT	/api/knowledge/file	保存编辑（写回原始文件）
GET	/api/knowledge/view	渲染好的 HTML 页面（新窗口打开用）
GET/POST	/api/knowledge/config	读取 / 更新配置（roots + excludeDirs）
POST	/api/knowledge/preview	预览根目录扫描结果

课程 API

方法	路径	说明
GET	/api/courses	列出课程 workspace 及其课程/速查卡
GET/POST	/api/courses/config	读取 / 更新课程根目录配置
POST	/api/courses/preview	预览根目录扫描结果
GET	/teach/:wsId/*	托管课程 workspace 文件（HTML/CSS/JS）

文件变化通过 WebSocket 推送 knowledge-change / course-change 事件，前端自动刷新。

🛠 技术栈

后端 Express 5 · ws · chokidar · marked　前端 原生 HTML/CSS/JS · 本地 vendor（marked / highlight.js / mermaid 随包分发）　常驻 内置 autostart 命令 / nssm（可选）　AI 集成 pi 扩展（pi install npm:lanbook）

📁 项目结构

lanbook/
├── bin/lanbook.js                  # CLI 入口（open / add / config / autostart / stop）
├── extensions/lanbook-open.ts      # pi 扩展（/lanbook 命令，随包分发）
├── lib/                            # 数据目录、服务配置、链接主机解析
├── server.js                       # Express + WebSocket 服务端
├── public/                         # 单页前端 + vendor 静态资产
├── test/                           # 进程边界测试
├── knowledge.config.example.json   # 知识库配置参考模板
├── teach.config.example.json       # 课程配置参考模板
├── DEPLOY.md                       # 部署运维说明
└── package.json

链接

• 🐙 GitHub — 仓库主页
• 💬 LINUX DO — 开源社区，本项目在此分享交流

License

ISC