asklokesh/loki-mode · 上手攻略

仓库：asklokesh/loki-mode
链接：https://github.com/asklokesh/loki-mode
分类：engineering / AI 编码 Agent · 可验证交付 · 本地优先
作者：spark
更新：2026-11-02

一、它是什么

loki-mode 是一个自治软件工厂（autonomous software factory），TypeScript 编写，仓库自我描述是：

Give it a GitHub issue, a spec or a one-line task; get back a pull request with a signed receipt anyone can re-check offline. Runs on your machine with your own keys: Claude, Codex, OpenCode.

它跟常见的 Claude Code / Cursor 这类编码 Agent 的差别，是引入了一个可审计的交付契约层：

每次运行先从你的任务派生出一份 delivery contract（交付契约）；
在碰代码之前先从任务本身写出检查项（checks）；
然后实现 → 验证 → 封存一份 签名收据（signed receipt）；
运行以恰好一种结局结束：VERIFIED / ALREADY_SATISFIED / FAILED / BUDGET_STOP / BLOCKED / STALLED。

收据写在 .loki/runs/<run-id>/receipt.json，用首次运行时本地生成的 Ed25519 密钥签名。任何人拿到这个 JSON 都能离线重新验证：loki verify 会重算哈希、校验签名、比对运行事件日志。

它由 Autonomi（autonomi.dev）开发，许可是 Business Source License 1.1：个人、内部、学术与非商业用途免费，2030 年 3 月 19 日自动转为 Apache 2.0。

README 有一个很少见的自我描述，把整篇 README 的立意说得很清楚：

Your agent says done. Loki proves it.

二、解决什么问题

编码 Agent 现在最大的痛点不是"写不出来"，而是"写完了但你不敢信"：

Agent 说"测试通过了"，你无法验证它跑的是不是真测试；
Agent 悄悄把某个失败的测试改成 skip，报告依然全绿；
Agent 改了 30 个文件，没人知道哪些行为被证明、哪些没被证明；
出了问题无法追责——没有签名、没有事件日志、没有可离线复检的凭据。

loki-mode 的解法是把"自证"做成一等公民：

fail-to-pass 是硬要求。声明了行为变更的 run，必须有一个 Wall test 在旧代码上失败、在新代码上通过，否则结论停留在 PARTIAL。用 LOKI_MUTATION_STRICT=0 可以退出这个要求（别在生产用这个开关）。
收据明说"什么没被证明"。一次成功运行的输出长这样：

Outcome: VERIFIED
PR: https://github.com/owner/repo/pull/1
Receipt: sha256:2f9a41c7e0b3...
NOT PROVEN: full suite, app boot, security scan
Cost: $0.42 (claude, 212k tokens)
Time: 4m12s (intake 11s, plan 20s, implement 3m10s, verify 31s)

"NOT PROVEN" 这一行是刻意设计的——它把"没测到的"显式列出来，而不是让人误以为绿灯等于全绿。

PR 的写法本身带免责声明。VERIFIED 开一个正式 PR；PARTIAL 开一个标题带 [PARTIAL] 的 draft PR，开头就写"什么没被证明"；其它结局则不开 PR，只把分支留在本地并打印位置。
可离线跨机验证。在另一台机器上 loki keys export 导出公钥，再 loki verify --pubkey <file> 就能验。README 明确说得很克制："A receipt claims only what its checks ran, and lists what they did not; signing proves who produced it, not that the code is bug-free."

三、快速安装

3.1 主路径：npm（推荐）

npm install -g loki-mode

npm 包会把引擎需要的 Bun 运行时作为可选依赖一起装上。其它装法：

bun install -g loki-mode
brew tap asklokesh/tap && brew install loki-mode
docker pull asklokesh/loki-mode:latest

升级用 loki self-update。

3.2 先看效果，不花钱

README 专门为"想先看看效果"设计了两个命令：

npx loki-mode start   # 不在 git 仓库里：给一份真收据，不需 key、不花钱
npx loki-mode tour    # 已在仓库里：展示同样的收据（离线）
npx loki-mode wow     # provider 就绪时：在临时仓库跑一个极小的真任务，给它自己的收据

npx 首次需要网络下载包；收据本身可离线复检，不需要 provider 也不需要 key。这是评估这个工具时最省事的入口。

3.3 依赖（`loki doctor` 会逐项检查）

必需： - Claude Code（claude），默认 provider，是唯一功能齐全的。或者只设 ANTHROPIC_API_KEY——此时 loki "" 走内置 Agent SDK，不需要 CLI、不需要额外设置；但 loki edit 和 loki chat 仍会调 claude CLI。 - Node.js 20+（README 口径；CI 目标为 22 LTS） - Git 2.x、curl - Bun 1.3+（npm 包已自带）

可选：Python 3.8+（深度扫描、Python 仓库、group run 用）、jq（loki status 与 bash 回退 CLI 用）、其它编码 CLI（Codex / Cline / Aider / opencode）、Docker。

支持平台：macOS 和 Linux（README 未提 Windows）。

3.4 首次配置

cd your-repo
loki setup              # 首次向导：工具检查、Claude 登录、provider、模型路由、消费上限
loki setup --yes        # 接受默认
loki doctor --fix       # 创建状态目录和默认配置，打印缺失项的精确命令；绝不跑 sudo

四、核心用法

4.1 主路径：start

loki start "add rate limiting to /api/login"
loki start prd.md                  # 从 PRD 文件
loki start owner/repo#123          # 从 GitHub / GitLab / Jira issue
loki "<task>"                      # 同 start 的简写
loki quick "<task>"                # 小任务，带 verify loop，不开 PR

常用开关：

开关	作用
`--no-pr`	只构建与验证，不开 PR
`--max-cost <usd>`	封顶消费
`--provider <name>`	换 provider（codex / cline / aider / opencode）
`--haiku`	首次实现切到 haiku 模型
`--deploy`	配合策略允许部署
`--explain-route`	只看路由不执行

loki route start prd.md 可以不执行地预览这次会走哪个引擎、provider、模型和原因。

消费上限默认值：ANTHROPIC_API_KEY 或 OPENAI_API_KEY 存在时默认 $100；用订阅账号登录时默认不设美元上限。loki.yaml 里的 budgets.per_run 也能设。

4.2 验证收据

loki verify                # 验证最新一次 run
loki verify <run-id>

退出码（README 表格）：

码	含义
0	VERIFIED
1	TAMPERED（被篡改）
2	UNCHECKED
3	UNSIGNED（默认拒绝，除非 `--allow-unsigned`）
4	运行结果本身未通过验证
66	没有 run

README 给了一句很实在的提醒：[ $rc -eq 0 ] 是唯一"已验证"的可靠判据，其它非零码都意味着"没验成"。

4.3 验证的前提：分支要对

loki verify 会检查你当前的 checkout 是否仍与封存的代码一致。而 loki start 开完 PR 后会把工作区切回起始分支，所以直接在原分支上跑 verify 会读到 UNCHECKED。正确做法：

git fetch origin loki/<run-id> && git checkout --detach FETCH_HEAD
loki verify <run-id>

4.4 跨机验证

loki keys export                  # 导出公钥
loki verify --pubkey <file>       # 在另一台机器上验证

4.5 小改动：edit

loki edit "rename fooBar to foo_bar"
loki edit src/foo.ts "rename X to Y"
loki edit --verify --commit src/a.ts "add null checks"

一趟完成，不走 plan、不走评审团、不开 PR，打印 diff 加一行成本与耗时。

4.6 交互式：chat

loki chat              # 默认进 Plan 模式（只读），/build 允许编辑
loki chat --attach     # 加入正在运行或最近一次 loki start 的会话

chat 内的斜杠命令：/status、/steer <text>、/diff、/verify、/receipt、/stop。/run <brief> 会用 chat 的模型和 provider 发起一次正常的 loki start。

4.7 其它 provider 与本地模型

loki start --provider codex prd.md
loki models --local                                  # 探测 Ollama / LM Studio / llama.cpp / vLLM
LOKI_MODEL_ROUTE=ollama/qwen3-coder loki start prd.md
LOKI_MODEL_ROUTE=openrouter/deepseek/deepseek-v3.2 loki start prd.md   # 需 OPENROUTER_API_KEY

路由种类：openrouter、ollama、lmstudio、llamacpp、vllm、custom（配 LOKI_MODEL_BASE_URL）。注意：即使走本地模型，仍然经过 Claude harness，所以消费统计、kill 阻塞、收据机制依然生效。

4.8 自主度策略

.loki/policies.json 里：

{ "autonomy": "propose" }

三档：propose（什么都不开）、execute（开 PR）、operate（还允许部署）。没有该文件则沿用当前行为。loki trust 会根据你的收据给出建议性的"毕业"路径，但它从不写入策略文件——升级自主度必须由人显式决定。

4.9 部署

loki deploy --execute（或 loki start --deploy）需要三件事同时满足：策略允许、有一份 VERIFIED 且锚定 HEAD 的收据、显式的 --execute。--health-url 加部署后探针，--auto-rollback 加带记录的 provider 回滚。

4.10 Control Plane（本地 UI / API）

loki control serve     # http://127.0.0.1:47821（--port N, --db PATH）
loki dashboard         # 打开 UI，必要时自动启动
loki control backfill .   # 载入已有的 ./.loki/runs
loki control status       # 通不通？有多少 run？

默认开启（LOKI_CONTROL=0 关闭），只监听 127.0.0.1。

4.11 集成

MCP：loki mcp 暴露 48 个 stdio 工具（启动 run、读状态、验证收据等）。一键安装：loki mcp install --client claude|cursor|vscode|windsurf。
Claude Code 插件：claude plugin marketplace add asklokesh/loki-mode 然后 claude plugin install loki-mode@loki-mode。同一 marketplace 还提供 loki-seal——一个 Stop hook，当测试新增失败或被削弱时拒绝"完成"。
CI 门禁：loki verify || fail（用法错误退出码是 64）。
Issue → PR：docs/examples/loki-issue-to-pr.yml.example 给了 GitHub Actions 模板，无需托管服务。
Jira / Linear 接入：docs/trackers.md；双向 Slack：docs/slack.md；Sentry 告警 webhook 可入队一个"收据门禁"的修复 PR（docs/sentry-intake.md）。

4.12 多仓库：workspace 与 composite

loki start --workspace <name> "<brief>"
loki verify <run-dir>/composite.json

多仓库改动会封存一份签名的 composite.json，覆盖每个子收据。规则很直白：复合收据的等级不会高于最弱的那个子收据；任一子项 SPEC_CONFLICT 则复合也 SPEC_CONFLICT，任一子项 FAILED 则复合 FAILED。

五、典型适用场景

给 AI 生成代码做合规验收的团队：把 loki verify 塞进 CI，"验证过"不再是一句口头保证，而是可离线复检的签名凭据。
Issue 驱动的批量修复：接 GitHub / GitLab / Jira，配合 Actions 模板，从 issue 直接出 PR。
外包与供应商交付审计：对方交回的是一串可验证收据，而不是一段"已完成"的描述。
有安全审计要求的行业：签名 + 事件日志 + "NOT PROVEN" 明示，适合需要留痕的环境。
想先评估再付费：npx loki-mode tour / wow 可以在不烧钱的前提下看到收据长什么样。

六、坑与注意

Node 版本要求两处不一致。README 的 "Requirements" 写 Node.js 20+（CI 目标 22 LTS），而 docs/QUICKSTART.md 写 Node.js 18+（推荐 20+）。稳妥按 20+ 装。
许可不是 Apache-2.0。卡片里许可字段是 NOASSERTION，实际是 BSL 1.1：个人 / 内部 / 学术 / 非商业免费，2030-03-19 转 Apache 2.0。商业使用要先看清条款或联系 founder@autonomi.dev——这是最容易踩的坑。
订阅登录时默认无消费上限。只有设了 ANTHROPIC_API_KEY / OPENAI_API_KEY 才默认 $100。用 Claude 订阅账号跑一个循环任务，可能烧掉你预期的钱。上线前务必 --max-cost 或 budgets.per_run。
verify 必须在正确的分支上跑。loki start 开完 PR 会切回起始分支，直接 verify 会得到 UNCHECKED（退出码 2），容易被误读成"验证失败"。用 git checkout --detach FETCH_HEAD 或对 composite 直接 verify。
PARTIAL 不是失败，但也不是成功。声明了行为变更却没有 fail-to-pass 的 Wall test，结论就停在 PARTIAL。此时会开 [PARTIAL] 标题的 draft PR。别把 draft PR 当成可合并的交付。
两套词表别搞混。收据结论只有 5 种：VERIFIED、PARTIAL、ALREADY_SATISFIED、SPEC_CONFLICT、FAILED；运行结局有 8 种，多了 BUDGET_STOP、BLOCKED、STALLED、CANCELLED。BUDGET_STOP / BLOCKED / STALLED / CANCELLED 永远不是收据结论，它们的收据是 "none"。混用会让 CI 判断写错。
签名只证明"谁做的"，不证明"代码没 bug"。README 原文已经写明。这条限制要主动告诉下游使用者。
默认会往 GitHub 发 PR / 评论，用的是你自己的 gh auth login 凭据。对无推送权限的仓库，它会推到你的 fork 再向上游开 PR——那个分支在你的 fork 上是公开的；LOKI_PR_FORK=0 可关掉这个回退。这种 fork 回退在处理私有代码时要特别小心。
Windows 未列在支持平台。README 只说 "macOS and Linux are supported"。WSL 未提及。
只有 Claude 是"全功能" provider。其它编码 CLI（codex / cline / aider / opencode）功能会打折；README 原文是 "the default provider and the only one with every feature"。用 --provider codex 前先确认少了哪些能力。
loki edit / loki chat 硬依赖 claude CLI。即使你只配了 ANTHROPIC_API_KEY 走 Agent SDK，这两个命令仍会调 CLI。
BLOCKED 需要人介入。用 loki answer <run-id> "..." 回答，它会在同一个 run id 下继续。契约写不成立时它会停下来问一个问题，而不是猜——这是好设计，但意味着自动化流水线要处理这个交互。
自动部署有前置条件。loki deploy --execute 需要 VERIFIED + HEAD 锚定的收据 + 策略权限三者齐备，缺一不部署。别指望 loki start 顺手就把生产改了。

七、与同类对比

维度	loki-mode	Claude Code / Cursor	opencode	SWE-agent	Devin
运行位置	本机，自带 key	本机	本机	多为容器/云	云端托管
可验证交付	签名收据 + 事件日志 + 离线复检	无内建机制	无内建机制	无	平台内报告
fail-to-pass	强制（可关）	无	无	评测框架内	不确定
明示"未证明"	NOT PROVEN 段	无	无	无	不确定
消费上限	内建（`--max-cost` / `budgets.per_run`）	依赖 CLI	依赖 CLI	依赖宿主	平台计费
自主度策略	三档显式策略（propose/execute/operate）	无	无	无	全自动
部署	有（`--health-url` / `--auto-rollback` / Sentry 回环）	无	无	无	平台内
许可	BSL 1.1（2030 转 Apache 2.0）	商业	开源	开源	商业

与 opencode 的差异，官方自己在 docs/COMPARE-OPENCODE.md 里做了对比（README 称之为 "Honest comparison with opencode"）。核心区别不在编码能力，而在交付可信度层：收据、签名、NOT PROVEN、fail-to-pass 这些机制 opencode 没有。

八、一句话推荐

loki-mode 不是又一个编码 Agent，而是给编码 Agent 套上"可签字交付"外壳——如果你需要向第三方证明"这次改动确实被验证过、且明确知道什么没被验证"，它的收据机制目前开源界几乎没有替代；代价是要装 Claude Code、吃本机资源，而且商业场景前必须先读懂 BSL 1.1 的许可条款。

附：来源与核验说明

已 fetch：https://github.com/asklokesh/loki-mode（README 全文）
已 fetch：https://raw.githubusercontent.com/asklokesh/loki-mode/main/docs/QUICKSTART.md（全文）
仓库卡片 organized/repo_cards/4805-asklokesh-loki-mode.md：Stars 1114、语言 TypeScript、许可 NOASSERTION、最近提交 2026-11-01、成熟度 research

不确定处（已在上文标注） - Node 版本要求在 README（20+）与 QUICKSTART（18+）之间不一致 → 已并列标出，建议按 20+。 - loki verify 的完整退出码表中"运行结果本身未通过验证 = 4"与退出码 66（无 runs）的边界，README 有表格但未逐条展开语义 → 以官方 docs/exit-codes.md 为准。 - .loki/policies.json 的实际 schema、三档之外是否有更多字段 → 未核实（README 只给了 autonomy 一项）。 - Control Plane 默认端口 47821 引自 README；是否可配、是否有鉴权 → 未核实。 - npm 包当前版本号与 changelog 内容未核对（README 只说 npm badge 追踪当前 release）→ 未核实。 - 未核实 Windows / WSL 支持情况（README 仅声明 macOS + Linux）。 - 未核实 BSL 1.1 的完整条款细节（"非商业"定义、衍生作品条款）；商业使用前请自行阅读 LICENSE 全文。