块（.lnb）

块包是名字以 .lnb 结尾的文件夹，在树中作为 单个项目处理（双击打开）。每个块都是磁盘上的真实文件； 顺序保存在包根目录的 blocks.json 中。它像一个 笔记本：堆叠的代码或文本单元格。Jupyter 笔记本从这里进入：在树中右键点击 .ipynb，选择作为块导入 (.lnb)。每个单元格变成一个真实文件 —— 可版本控制，也能被搜索读取 ——，而 .ipynb 留在原处，因为导入不是转换。笔记本中保存的输出不会一起过来：在这里运行单元格会生成带时刻和命令的真实结果。如果 blocks.json 无法读取（Git 冲突或写入中断），笔记本会给出提示并且不会重写它：在你修复之前，顺序、连接和会话都不会再保存。

单元格、笔记本栏和快捷键

每个单元格有名字、类型按钮（markdown、python、javascript、sql、shell、powershell、bat、r、julia、http、ia、mermaid、latex 和文本类型），以及复制、插入（点击：下方；小箭头：上方和复制单元格）、删除、上下移动和运行（小箭头提供运行到此处）的按钮。新单元格继承相邻单元格的类型。右侧按钮折叠单元格，标题栏只留下第一行；计数器 [n] 表示本次会话中单元格运行的顺序。从树（新建）或文件 → 新建创建笔记本。

顶部的笔记本栏作用于整个笔记本：全部运行按顺序运行代码单元格；停止中断正在运行的单元格并清空队列（该次运行以退出码 -1 进入历史）；清除输出关闭面板但不删除任何东西；更多菜单导出笔记本并删除历史。blocks.json 中的 timeoutSec 键设置每个单元格的时间限制（默认 0 表示不限制）。

焦点在单元格中时的快捷键：Ctrl+Enter 运行并停留；Shift+Enter 运行并移到下一个单元格（在最后一个上会新建一个）；Alt+Enter 运行并在正下方插入一个单元格。在文本单元格中，运行意味着渲染：有内容时以渲染状态打开，双击（或在其上按 Enter）回到编辑。

保存的结果、附件和历史

结果会被保存（像实验记录本一样）：运行结束时， 每次运行都变成包内 saida/<单元格>/ 下的一个 .md 文件 —— 包含时刻、退出码、 耗时、命令和输出本身。因为是 Markdown，可以在 任何编辑器中阅读，与笔记本一起用 Git 做版本控制，并通过 笔记搜索找回。重新打开包会在面板上方带回 上次运行条：点击它即可查看结果而无需 再次运行。

附件：每次运行在 .md 旁边都有自己的文件夹，其路径通过环境变量 LN_RUN_DIR 传给程序。单元格写在那里的东西 —— 一张 matplotlib 图、一个 CSV —— 会出现在输出下方（图片被绘制，其余作为指向文件夹的链接），并列在历史文件中。本身就是 Markdown 的输出（SELECT 的表格、AI 的回答、一个图表）以渲染状态打开；条上的文本/渲染按钮用于切换。

历史：该条旁边的历史按钮列出该单元格之前的 运行（时刻和退出码）—— 便于比较同一单元格 随时间返回了什么。我们为每个单元格保留最近 10 次； 要更改，请编辑包内 blocks.json 中的 historyLimit 键（0 关闭保存，附件也随之关闭）。过大的 输出会被截断（文件中写明 truncated: true）。重命名单元格或 更改其类型会带走历史；删除单元格会把历史送进 回收站。

持久会话

默认情况下每个单元格都是一个新进程：一个单元格定义的内容，下一个看不到。开启持久会话后（栏上的会话按钮；blocks.json 中的 session 键），Python、JavaScript、shell 和 PowerShell 单元格在一个运行之间保持存活的进程中执行 —— 一个单元格的变量、函数和导入在后续单元格中有效，就像 Jupyter 一样。在 Python 中，单元格结束时仍打开的 matplotlib 图形会自动保存到附件文件夹。重启会话会忘记一切；停止也是，因为中断就是结束进程。在 JavaScript 中，请用 var 声明（或不声明）：顶层的 let、const 和 class 不能再次声明 —— 即使再次运行同一个单元格也不行。

SQL 单元格

未指定连接时，sql 单元格在笔记本自身的 DuckDB 中运行（内存中）：一个单元格创建的表在后续单元格中有效，read_csv('data/sales.csv') 读取笔记本文件夹中的文件 —— 请把数据放在子文件夹中，因为笔记本文件夹中每个单独的文件都是一个单元格。要使用真实数据库，请通过连接条（它列出工作区的连接）把笔记本指向一个 .lnc 连接：单元格将在数据库上运行，使用与连接面板相同的连接 —— 记住的密码、SSH 隧道、重新读取 .lnc，以及任何写入前的生产环境确认。SELECT 的结果变成输出文件中的一张表格；INSERT/UPDATE 等报告改变了多少行，错误会中断脚本并记录失败的语句。每个查询最多取 100 行（blocks.json 中的 sqlMaxRows；有更多时文件会提示）。

@set name = value 定义一个笔记本作用域的变量，:name（或 ?）是运行时询问的参数，和 SQL 编辑器中一样。最后一个 SELECT 还会把 resultado.csv 写入附件文件夹（与表格相同的行，最多 sqlMaxRows 行），后续单元格通过 LN_LAST_SQL 收到它的路径 —— 在 Python 中：pd.read_csv(os.environ["LN_LAST_SQL"])。连接以相对路径保存在 blocks.json 中；放在包内的 .lnc 算作配置，不会变成单元格。

HTTP、AI、Mermaid 和 LaTeX

四种类型由 LightNote 自身运行，无需解释器：http 单元格是由与 API 测试器相同的执行器运行的 .lnh 测试（报告进入历史；环境由 blocks.json 的 httpEnv 键指定，请求发送的文件必须位于工作区内）；ai 单元格把提示词连同笔记本上下文 —— 前面单元格的源码和各自的最后输出，但不包括可能携带凭据的 http 单元格 —— 发送给默认助手，回答以渲染状态到达；mermaid 和 latex 单元格把图表或公式绘制成附件中的图片。停止取消前两种。

导出笔记本

栏上的更多菜单导出整个笔记本：导出为 Markdown（文本单元格原样内联，代码放在带语言的围栏中，最后的输出紧随其下，图片以链接形式），或导出为 Jupyter 笔记本（.ipynb，包含每个单元格的最后输出和内嵌图片；其他语言的单元格带有 VS Code 能读取的标记）。这是用于分享的副本 —— 笔记本仍然是那个文件夹。