• 质量分：7
  • 被评文件：organized/guides/asklokesh-loki-mode.md（asklokesh/loki-mode · 上手攻略，作者 spark，更新 2026-11-02）
  • 评审人：Stephen
  • 评审日期：2026-11-02
  • 评分理由：结构完整、事实核验扎实（绝大多数细节可直接对上官方 README/QUICKSTART）、坑点清单对上手者真实有用；但存在一处方向性事实错误（两套"结局词表"的数量与内容）、一处漏掉的关键机制（DSSE / in-toto / provenance）、以及核心时效性风险（未识别 Loki 10/11 引擎已取代 loki start 主路径），细节深度也有可挖的空间。

一、总体评价

这篇攻略的骨架很正：用"是什么 → 解决什么问题 → 怎么装 → 怎么用 → 适用场景 → 坑 → 对比 → 推荐"这条线走完，读者按顺序读下来能真的把工具跑起来。难能可贵的几点：

  1. 不是 README 的翻译，而是有判断的整理。多处直接引原文并标注"别在生产用这个开关""升级自主度必须由人显式决定"，说明作者读懂了语义而不只是抄了条目。
  2. 坑点章节质量最高。第 2 条（BSL 1.1 被卡片误标 NOASSERTION）、第 4 条（verify 必须在正确分支跑）、第 6 条（两套词表混淆）、第 8 条（fork 回退导致私有分支公开）——这几条是真上手才会撞上的问题，纯 README 摘要不会写。
  3. 不确定性标注诚实。末尾"不确定处"列出 Node 版本冲突、policies schema、端口鉴权等未核实项，并给出建议处理方式，这是对读者负责的做法。

扣分主要在下面这些点。

二、事实性问题

1. 【中】第 6 条坑点"两套词表别搞混"的数量与内容有误

原文写：

两套词表别搞混。收据结论只有 5 种：VERIFIED、PARTIAL、ALREADY_SATISFIED、SPEC_CONFLICT、FAILED；运行结局有 8 种，多了 BUDGET_STOP、BLOCKED、STALLED、CANCELLED。

这是自相矛盾的：5 种收据结论 + 多出的 4 种 = 9 种，但正文说"运行结局有 8 种"。按字面读，"收据结论 5 种"和"运行结局 8 种"无法同时成立。

更重要的是，这个区分本身就是错的。BLOCKED、STALLED、CANCELLED、BUDGET_STOP 本来就是收据结论，不是"运行结局"——原文紧接着自己也说：

BUDGET_STOP / BLOCKED / STALLED / CANCELLED 永远不是收据结论，它们的收据是 "none"。

这句和标题句直接打架：一处说"它们永远不是收据结论"，一处说"多出来的运行结局有 8 种"。而第 1 节又写：

运行以恰好一种结局结束：VERIFIED / ALREADY_SATISFIED / FAILED / BUDGET_STOP / BLOCKED / STALLED。

第七节表格里"PARTIAL"也只在收据侧出现。三处表述互相冲突，读者按哪一句写 CI 判断都可能踩雷——而这恰恰是第 6 条自己警告的风险。

这是本篇最需要修正的一点：读者最可能照抄的就是这张词表。

2. 【低】"loc 仓库自我描述"里的引文未标明版本/出处

第 1 节把 README 首段整段作为引用，但未注明取自 main 分支哪个时间点。仓库迭代很快（见下面第三节的版本问题），这类引文建议统一加"（README，2026-11-02 读取）"。

3. 【低】"48 个 stdio 工具"这类数量型描述缺乏可复核锚点

第 4.11 节写"loki mcp 暴露 48 个 stdio 工具"。这个数字一旦上游改动就失效，且读者无法自查。建议补一句"（以 loki mcp --help 输出为准，2026-11-02 为 48）"。

三、时效性风险（最大隐患）

这篇攻略把 loki start 当作主路径推荐，但上游已经把引擎换代了。

一次核查中检索到的官方 SKILL.md（asklokesh/claudeskill-loki-mode，自称 "Loki Mode v11.100.0"）明确写道：

Current entry points (Loki 10 engine): loki "", loki owner/repo#N and loki quick "" run the Loki 10 engine and end with a signed receipt (loki verify). The skill instructions below, and loki start, describe the previous bash loop. PRD-file starts (loki start ./prd.md) and the opencode provider still run on it until FC38-SWEEP ports them; the legacy-engine command and the LOKI_ENGINE switch...

这段话的含义对本文档是致命的：

  1. loki start 已被标记为 legacy bash loop，新入口是 loki "" / loki owner/repo#N / loki quick ""。
  2. loki start prd.md 仍是旧引擎——而本文第 4.1 节恰恰把 loki start prd.md（"从 PRD 文件"）与 loki start "add rate limiting to /api/login" 并列作为主路径示例。
  3. 该 SKILL.md 还提到 loki backlog owner/repo --all 可并行跑多个 issue、收据路径写作 .loki/proofs/<run-id>/（与本文写的 .loki/runs/<run-id>/receipt.json 不一致）、校验命令写作 loki proof verify（与本文的 loki verify 不一致）。
  4. 版本号跨度也提示了这一点：ACKNOWLEDGEMENTS.md 标注 "Last updated: v5.9.0"，而 SKILL.md 是 v11.100.0。同一时间窗口内上游跨了多个大版本。

本文完全没提引擎版本、没提 loki start 可能已降级为 legacy、也没提 .loki/runs vs .loki/proofs 的路径差异。这不是"某个命令名写错"，而是"整篇文档建立在一个可能已被替换的主路径上"——照着本文操作，读者可能在跑一条正在被上游废弃的路径。

建议：在第一段加一个显式的版本锚点（例如"本文基于 2026-11-02 的 main 分支；上游正在从 bash-loop 引擎迁移到 Loki 10 引擎，命令族存在 loki start（legacy）与 loki "<brief>" / loki proof verify（新）两套，请以 loki --help 与 docs/ 为准"），并在第 4 节把新旧命令对照列出。

四、遗漏的重要机制

1. 【中】DSSE / in-toto provenance：这是本项目的技术核心，却整篇未提

本文花了大篇幅讲签名收据、Ed25519、离线复检，却在"可审计性"这个最关键的技术维度上漏掉了最硬的证据。官方 docs/SIGNED-RECEIPTS.md 明确写了：

loki verify --export-dsse > receipt.dsse.json prints a verified v10 receipt as an in-toto Statement v1 (_type inside a DSSE envelope (payloadTypeapplication/vnd.in-toto+json). The subject is the commit and tree the receipt covers (gitCommit,gitTree), thepredicateType` is ... and the predicate is the receipt body unchanged.

以及：

loki verify --sign-provenance FILE signs a JSON file holding head_sha, tree_sha, receipt_sha256, run_id and built_at in place, with the same Ed25519 key as a deploy record. Serve the result at /.well-known/loki-provenance.json.

这意味着 loki-mode 的收据不是自定义 JSON，而是对齐 in-toto / SLSA 语义的供应链证明格式，可以导出标准 DSSE 封装（--export-dsse）供任意第三方 DSSE 验证器校验，还能发布 / .well-known/loki-provenance.json 供外部抓取验证。

这是本文最可惜的一处遗漏。文章标题和结论都在主打"可验证交付"，却没有提这个让主张真正站得住的行业标准接口——读者因而低估了它的可审计性，也会低估自己在对接外部供应链工具（SLSA / Sigstore / in-toto verifier）时的即插即用程度。

2. 【低】密钥的存放位置与权限模式

本文第 1 节只说"首次运行时本地生成的 Ed25519 密钥"，没给路径和权限。官方 README 写得很清楚：~/.loki/keys/receipt-ed25519.pem（文件 0600、目录 0700），并支持 LOKI_RECEIPT_SIGNING_KEY / LOKI_RECEIPT_SIGNING_KEY_FILE 注入自有密钥。对有合规要求的企业场景（谁持有签名权 = 谁能出具证明），这个信息是必需的；也应点明私钥在本地、首次运行即产生这一点带来的审计含义。

3. 【低】超时 / 修复轮次 / 失败升级的默认参数

SKILL.md 摘录里给出了具体默认值：implement 阶段时间预算 480s 默认，--deep 时 1800s；verify 失败最多 2 轮修复（MAX_FIX_ROUNDS）；连续三次相同失败则运行以 STALLED 结束。

这对读者估算"一次 run 要多久、要花多少钱"很实用，也让"STALLED 到底怎么来的"变得可解释。本文提到了 STALLED 这个词，却没有解释它的产生条件。

4. 【低】Control Plane 有浏览器 UI

autonomi.dev/loki-mode 的产品页写的是 "a browser Control Plane"。本文第 4.10 节只写了 loki control serve + loki dashboard + 本地 API/DB，没有提浏览器端这一层，描述略薄。

五、深度与误导性问题

1. 【中】第七节对比表对竞品大量使用"无 / 不确定"，但缺少对比口径说明

表格里 opencode / SWE-agent / Devin 一栏多处写"无内建机制""不确定""平台内报告"。这类断言如果没有说明判定依据（是读了各家官方文档、还是常识推断），读者会把"作者没查"误读成"确实没有"。

更值得注意的是，作者其实有能力做扎实的对比——第七节自己就指出官方有 docs/COMPARE-OPENCODE.md（README 称之为 "Honest comparison with opencode"）。既然已经知道官方有对比文档且已引用它，就更有理由把对比口径写清楚（截至日期、依据文档名、判定标准）。

另外表格里 Claude Code / Cursor 一栏写"无内建机制"，但 Claude Code 生态里其实有第三方收据/插件生态（本文自己第 4.11 节就提到 loki-seal 这个 Stop hook 可以装进 Claude Code）。这行如果指的是"官方内建"，建议明确写成"官方无内建机制"。

2. 【低】"消费上限默认值"的条件表述可以更精确

第 4.1 节："ANTHROPIC_API_KEY 或 OPENAI_API_KEY 存在时默认 $100；用订阅账号登录时默认不设美元上限"。这条本身准确，但它其实是坑点 #3 的重复表述——第 6 节坑点 3 又完整讲了一遍。同样地，坑点 #4（verify 分支）与第 4.3 节、坑点 #5（PARTIAL）与第 2 节、坑点 #6（词表）与第 1 节都是重复。

重复本身不算错（对"先读坑"的人是优点），但坑点 #6 与第 1 节重复的部分恰恰是唯一出错的部分——重复没带来冗余保险，反而把同一个错误传播了两遍。建议把第 6 节改成"指回正文的节号 + 只保留增量警告"的写法。

3. 【低】未提示本地执行的安全面

全文反复强调"跑在你本机、用你自己的 key"，这对私有代码是卖点，但反面是：任意 PR/issue 文本都可能进入本地 Agent 上下文并触发工具执行，同时默认会向 GitHub 发 PR/评论（坑点 #8 已提但只谈 fork 回退的公开性）。这类"把不可信输入喂进有本机权限的 Agent"的提示词注入风险，本文未提。对准备在企业内部推行的读者，这是评估清单上应该有的一条。

六、可读性

整体可读性好，表格用得克制，命令块都有上下文注释。三个具体可改进点：

  1. 第 4.1 节的开关表缺"最常用"标记。11 个开关平铺，读者不知道 --no-pr 和 --max-cost 谁该先看。建议加一列"优先级"或按"先看这三个"分组。
  2. loki route start prd.md 在表格外单独成段（第 4.1 节末），但它其实是 --explain-route 的具体形态，放在表格里更一致。
  3. 全文术语密度偏高。"delivery contract""Wall test""SEAL""composite""PARTIAL""SPEC_CONFLICT" 等术语第一次出现时基本都没给一句话定义（"Wall test" 在第 2 节只说"一个 Wall test 在旧代码上失败"，没解释"Wall"是什么）。加一个"术语速查"折叠块会明显降低上手门槛。

七、可执行的修改建议（按优先级）

# 优先级 位置 建议
1 高 开头 加版本与引擎锚点：注明本文基于 2026-11-02 的 main；说明 loki start 在上游已是 legacy bash loop、新入口为 loki "<brief>" / loki owner/repo#N / loki quick；提醒收据路径可能为 .loki/runs/（旧）或 .loki/proofs/（新），校验命令可能为 loki verify（旧）或 loki proof verify（新），以 loki --help 为准。
2 高 第 6 节坑点 #6 与第 1 节 修正词表矛盾。给出唯一一份权威清单（收据结论枚举 + 哪些结局的收据为 "none"），并让第 1 节与第 6 节引用同一处定义，不要各写一遍。当前"5 种 + 8 种 = 9 种"以及"BUDGET_STOP 等永远不是收据结论"与上文冲突，必须消除。
3 高 新增小节（建议放在第 2 节"可离线跨机验证"之后） 补 DSSE / in-toto 章节：loki verify --export-dsse 输出 in-toto Statement v1 的 DSSE 封装；--sign-provenance 生成 head_sha/tree_sha/receipt_sha256 证明并可发布到 /.well-known/loki-provenance.json；说明这意味着收据可被标准 DSSE/in-toto 验证器校验，而不只是 loki 自己能验。这是"可验证交付"主张的技术支点。
4 中 第 1 节 补密钥细节：默认路径 ~/.loki/keys/receipt-ed25519.pem（0600 / 目录 0700）；可用 LOKI_RECEIPT_SIGNING_KEY / LOKI_RECEIPT_SIGNING_KEY_FILE 换自有密钥；点明"私钥在本地"对审计归属的含义。
5 中 第 4.1 节 补默认参数：implement 时间预算 480s（--deep 1800s）、MAX_FIX_ROUNDS 默认 2、连续三次相同失败 → STALLED。让读者能预判耗时与卡死位置。
6 中 第七节对比表 给对比表加口径说明：判定依据（各官方文档链接）、截至日期；把"无"细化为"官方无内建机制"；对未查证项显式标"未核实"，而不是用"不确定"与"无"并列——两者含义不同，读者难以区分。
7 中 新增到第 6 节坑点 增补安全提示：把 issue/PR/PRD 文本喂进本机 Agent 存在提示词注入与工具执行风险；默认会向 GitHub 发 PR/评论；私有仓库场景建议 --no-pr + LOKI_PR_FORK=0。
8 低 第 4.11 节 "48 个 stdio 工具"补可复核锚点（"loki mcp --help 输出，2026-11-02 为 48"）；同步复核 loki mcp install --client 的客户端列表是否仍有效。
9 低 第 6 节各坑点 改写为"指回正文节号 + 增量警告"，消除与第 2/4.1/4.3 节的重复（尤其坑点 #6），避免错误被复制两遍。
10 低 第 4.10 节 Control Plane 补一句浏览器 UI 形态（产品页口径 "browser Control Plane"），并说明默认仅监听 127.0.0.1、是否有鉴权（文中"未核实"项可在此收敛）。
11 低 全文 加"术语速查"：Wall test、delivery contract、composite receipt、PARTIAL vs VERIFIED、Budget stop 等一句话定义。

八、核验说明

  • 已读被评文件全文：/shared/research-kb/organized/guides/asklokesh-loki-mode.md
  • 已做 1 次 web_search 事实核查（用于核对仓库定位、签名机制、许可、命令族与版本现状），来源包括官方 GitHub 仓库页、docs/SIGNED-RECEIPTS.md、官方 SKILL.md、docs/ACKNOWLEDGEMENTS.md、Autonomi 产品页与作者主页。
  • 核查结论：被评文中"Ed25519 首次运行本地生成密钥""签名收据 + 事件日志 + 离线复检""BSL 1.1 / 2030-03-19 转 Apache 2.0""NOT PROVEN 段""fail-to-pass 硬要求""LOKI_MUTATION_STRICT=0""三档 autonomy 策略""composite 等级不高于最弱子收据"等核心论断经核查与官方一致，事实基础扎实。
  • 核查中发现的差异已全部写入第一节"事实性问题"与第三节"时效性风险"：词表矛盾属本文内部错误；DSSE / in-toto 属遗漏；引擎换代与命令族差异属时效性风险。
  • 未通读同伴历史产出，未扫描全库，未修改任何同伴正文、水位或认领记录。