Ledge：能直接跑命令的 Markdown 笔记，把运维手册变成可执行 Notebook

记命令的笔记工具有很多，但大多数笔记里的 shell 块只是”长在 Markdown 里的代码”。Ledge（ledge.sh）要做的是反过来：让笔记本身就是一个能跑的工作环境。你在笔记里写下 shell、Python、SQL、redis 甚至一段 AI prompt，按 ⌘↩，输出就流式显示在代码块下方。数据是纯 Markdown 文件，没有账号、没有数据库，Apache-2.0 开源，覆盖 macOS（Apple Silicon）、Linux、Windows 11（WSL）以及 iPhone/iPad（Android beta）。

一、它到底是什么：可执行文档 + 持久 Shell

可执行文档并不新鲜——Jupyter Notebook、Runme 都做过。Ledge 的差异在于它瞄准的是开发者与 DevOps 的”命令笔记本”：你那些”周一检查上周注册量""发版前跑一下这个脚本”的备忘，过去只是文字，现在可以直接点运行。

核心机制：

• 每篇笔记有自己的持久 Shell：一个 cd、一个 export 变量、激活的 virtualenv，会带到下一次运行；⇧⌘↩ 还能把块送到一个可继续输入的终端抽屉；
• 运行中的块可以交互：遇到 sudo 密码或 [y/N] 提示，直接在输出面板里回答；
• frontmatter 控制环境：cwd: 设定起始目录，env: 注入变量，norun 给”只是引用、别执行”的代码块去掉运行按钮；
• 开箱语言：Python、Node、Ruby、PHP 直接跑，TypeScript 用应用内置的 Bun 运行，redis 块走 redis-cli 并按笔记的 REDIS_URL 指向环境，加解释器只需在设置里写一行。

二、远程执行：笔记在本地，命令跑在服务器上

这是 Ledge 最有运维味的设计。在 frontmatter 加一行 host:，笔记里的每次运行就通过 SSH 到那台主机执行，而笔记文件本身留在原地。

• 声明多个主机（如 host: staging, deploy@prod），每次运行 Ledge 问你选哪台，回车重复上次选择；
• 给块加 confirm（如 sh confirm="Flush the session cache?"），运行前它会亮出代码、点名机器、让你确认；
• 认证直接复用你自己的 ssh：密钥、agent、~/.ssh/config、2FA 都和终端里一样；
• 笔记的 cwd 和 env 跟着走，但 Profile 和密钥不走——秘密不进笔记、不随执行远程化。

更进一步，你可以把整套 Ledge 指向一台远程服务器：文件和 Shell 都在服务器上，笔记本只是”窗口”。合上笔记本，远端的块继续跑，下次打开输出还在；手机、第二台电脑同时连同一台服务器，各开各的标签。认证用 ssh key 或存在系统钥匙串的密码，Ledge 会固定服务器 host key。ledge backup 每小时把加密备份放进 S3 兼容桶。

三、密钥、锁定与 Agent：风险是怎么被约束的

Ledge 把”秘密留在笔记之外”做成了一等公民：

• Profile 是笔记文件夹之外的一份 dotenv（~/.config/ledge/profiles/deploy.env）。笔记在 frontmatter 里只写 profile: deploy，运行时才读入环境；笔记可以被同步、备份、被 Agent 读，而 Profile 的值始终留在本机；
• 锁定笔记：笔记正文在磁盘上用口令加密，Agent 永远看不到、同步服务只搬密文，解锁需口令；标题/frontmatter/标签仍可见以保持链接可用，15 分钟无操作自动重锁；
• 内置 MCP 服务器：claude mcp add ledge -- ledge mcp 即可让 Claude Code 等 MCP Agent 读写、搜索、创建、编辑你的笔记。但官方特意做了限制：没有删除工具，锁定笔记对所有 Agent 拒绝返回正文，prompt 块可以一键喂给 Agent 并流式看回复。

四、关键事实与口径

五、评测方法批判与局限

1. 它放大了误操作面，约束是”约定”而非”沙箱”：让 Agent 按笔记直接跑 redis-cli flushdb、make release，效率高、风险也高。官方用 confirm 块、norun、锁定笔记、无删除工具来对冲，但这些都靠你自觉加——没有容器/权限隔离，Agent 拿到的就是你 ssh 权限能做的一切。
2. 平台依赖：Windows 端要靠 WSL，移动端是”服务器窗口”而非本地笔记；Android 还是 beta。
3. 可执行文档的老问题依旧：笔记里的命令会过时、环境会变，Ledge 没有给出类似 CI 的断言/测试机制，输出”流式显示”不等于结果被校验。
4. 没有客观性能/规模基准：官方展示的是用法示例（几百毫秒到几秒的执行耗时），不是压测数据。

六、优势与适用人群

优势：

• 笔记即可执行：把零散的运维备忘、复盘、数据探查变成一键复现的工作流；
• 远程一等公民：host: + confirm 让”在 staging 验证、再 prod”的流程写进笔记且不会误点；
• 秘密与 Agent 边界清晰：Profile 外置、锁定笔记、MCP 无删除工具，是认真考虑过 Agent 安全的设计；
• 纯 Markdown、无锁定：文件就是普通文件夹，同步和版本管理随便你选。

适合谁：

• DevOps / SRE：把 oncall 手册、发版 runbook、巡检脚本写成能跑的笔记；
• 喜欢”文档即环境”的开发者：项目文件夹直接挂成 workspace，在项目目录里边记边跑；
• 已经在用 MCP Agent、又怕它乱动生产的人：Ledge 的权限约束比直接让 Agent 开终端要可控。

但如果你只需要纯文字笔记，或者对”Agent 能直接执行 shell”极度敏感，那它的可执行性反而会让你犹豫。

参考来源

• Ledge 官方站点
• Koala 项目库条目