Look 是一款开源、跨平台的轻量级启动器，它的自定义数据源（Sources）功能让你只用一个 TOML 文件，就能把 Git 仓库、SSH 主机、部署脚本变成启动器里的可搜索行——无需安装插件、无需学习 API，改完文件按一次刷新键即可生效。

Look 开箱即用地索引了应用、文件和系统设置，而Sources 就是往同一份结果列表里加入你自己的行的机制：输入仓库名直接打开项目，输入主机名一键 SSH 登录，回车触发部署命令。官方完整指南在 docs/user-sources.md，格式解析实现位于 core/sources/src/lib.rs。

4 种块类型，先记住这张表

一个 Sources 文件由若干块（block）组成，每个[header]就是一个块。每个块必须声明恰好一个生产者键（producer key），它决定了块的类型：

⚠️ 版本要求：Sources 需要 Look v0.6.12 或更新版本，更早版本不会读取~/.look/sources/目录。

快速上手：三步建立第一个数据源

1️⃣ 创建目录：

mkdir -p ~/.look/sources

2️⃣ 放入任意命名的.toml文件，比如mine.toml：

[projects] name = "Projects" dir = "~/dev" only = "dirs" [work] name = "Work setup" do = [ "open -a Slack", "open -a Safari https://github.com", ]

3️⃣ 刷新 Look：macOS 按Cmd+Shift+;，Linux/Windows 按Ctrl+Shift+;。

完成。输入projects就能看到你的仓库，输入work setup回车一次打开所有应用。没有主文件、没有索引需要维护——Look 会读取目录里所有.toml并合并，文件名纯粹为了方便你自己。目录也可通过环境变量LOOK_SOURCES_DIR改到别处（适合 dotfiles 仓库软链场景）。

块 id（即[header]）在整个目录内必须唯一，重命名会丢失该块的使用排名历史，所以一次定好就别再动。

Git 仓库实战：dir 块 + then 钻取

先看最简单的场景——把~/dev下的仓库全部变成可搜索行：

[projects] name = "Projects" dir = "~/dev" only = "dirs" aliases = ["repo", "code"] open = "code {path}"

• depth = 1（默认）只取直接子项，设为 2 再深入一层；
• match/exclude按条目名做 glob 过滤，如exclude = ["archive*"]；
• 行按名称排序，目录变化时列表不会乱序。

这些行是真实的文件系统对象，所以预览、在文件管理器中显示、复制路径等 Look 对文件的所有能力都自动生效。

钻取到单个仓库的分支

真正的威力来自then：它让选中一行后可以"钻取"到别的块。选中项目按Cmd+K/Ctrl+K打开动作菜单，回车即可下钻，Esc返回：

[projects] name = "Projects" dir = "~/dev" only = "dirs" then = ["branches"] [branches] name = "Branches" run = "git -C {path} branch --format='%(refname:short)'" preview = "git -C {parent.path} log -10 --format='%h %s' {id}" open = "git -C {parent.path} switch {id}"

这里最容易踩的坑值得单独说明：

• run是生产者，运行时"选中的行"还是项目本身，所以它里面写{path}；
• open作用于run产出的分支行，此时项目变成了父级，要写{parent.path}，分支则是{id}。

这种层级最多可叠 5 层。run命令只在刷新时执行一次并缓存（缓存在~/.look/cache/rows/<块id>），搜索永远即时，无论你的命令多慢；命令失败或超时会保留上次的行，而不是清空。

SSH 主机实战：file 块 + 制表符三列

维护一份手工文本列表，每行一个主机。hosts.txt用 Tab 分隔三列：id<TAB>title<TAB>subtitle：

prod-web-1 Production web us-east-1 db-primary Primary database us-east-1

[hosts] name = "SSH hosts" file = "~/.look/hosts.txt" icon = "🖥️" open = "open -a Ghostty --args -e ssh {id}"

id是动作实际接收的值，title是你看到的显示文本——两者分开，行就可以"显示 A、操作 B"。Linux/Windows 上把open换成你系统的终端启动方式（如tmux new -x 0 ssh {id}）即可。

💡 故意选用 Tab 分隔是有讲究的：一个朴素的ls或awk一行命令的输出就已经是合法数据源。

部署脚本实战：do 块 + confirm 保险

部署是破坏性操作，Look 的哲学是"启动器让错误的回车变得很廉价，所以危险操作要重新变贵"。confirm键在动作执行前弹出一个 Yes/No 确认：

[deploy] name = "Deploy" confirm = "Deploy {parent.title} to staging?" do = ["make -C {parent.path} deploy"]

配合上面then = ["deploy"]，流程就是：搜出项目 → 选项目 → 动作菜单里点 Deploy → 确认弹窗写明"部署哪个项目" → 回车执行。

几个实战细节：

• do块的步骤按顺序执行，单步失败不中断后续——一个打开 4 个应用的包，即使少装一个也能打开剩下 3 个；
• 步骤也能读到环境变量LOOK_ID、LOOK_TITLE、LOOK_PATH，适合"逻辑复杂就写成脚本"的场景：

[deploy] name = "Deploy" do = ["~/bin/deploy.sh {path} --confirm"]

• 占位符永远不要自己加引号。所有值在替换时都会做 shell 转义，写open {path}就能正确处理叫My Project的文件夹；写成open "{path}"反而变成双重引号、解析失败。

给所有 PNG 加一个优化动作（applies）

applies让一个do块出现在任何匹配行的动作菜单里，包括 Look 原本就索引的文件——不需要为此建列表：

[optimize] name = "Optimize" applies = { ext = ["png"] } do = ["oxipng -o4 {path}"]

选中任意位置的.png按Cmd+K/Ctrl+K，Optimize 就在那里。

常用参数速查

可用占位符：{id}、{title}、{path}、{dir}、{query}，以及{parent.id}、{parent.path}等向上追溯的写法。

两点值得注意：

• 命令都通过你的登录 shell 执行，所以&&、|、$VAR都能用；但~/.zshrc这类交互式 rc 文件不会被读取——command not found多半是 PATH 没生效，把export PATH=...挪到~/.zshenv/~/.zprofile，或在块里写二进制全路径；
• run块没写cwd时工作目录是文件系统根/，不是家目录，相对路径都会错。用绝对路径、-C式参数，或干脆声明cwd = "~/dev/look"。

排障与完整示例

块不显示、显示旧数据时按此顺序排查：

1. 是否声明了恰好一个do/dir/file/run？零个或两个都会报错跳过；
2. 生产者或cwd里是否提到了{path}等占位符？那说明它被设计成then目标，永远不会出现在顶层；
3. enabled = false是否还留在块里？
4. 文件扩展名是否严格是.toml？

错误信息会逐行打印到 stderr（前缀look sources:），从终端启动 Look 就能看到。如果你手头有源码，仓库自带一个解析检查工具，会打印所有问题以及每个成功加载的块：

cargo run -p look-sources --example parse_check -- ~/.look/sources

该工具位于 core/sources/examples/parse_check.rs。

最后，仓库里有一个覆盖全部键的注释版示例文件，复制进~/.look/sources/删掉不用的部分即可：core/sources/example.toml。其他相关文档：docs/user-guide.md、docs/architecture.md。

写在最后

Look 的 Sources 本质是"一个目录 + 一种格式 + 四个键"：没有插件系统、没有 API，TOML 里写清楚块，回车就能干活。从 Git 仓库到 SSH 主机再到部署脚本，你的整套工作流都可以收敛到这个轻量启动器里，而且所有数据都留在本机，无遥测、无账号。