spar

在AI编写代码的同时，保持学习。

审查已完成且令人信服的代码几乎教不了你什么。你没有立场去评判它，所以你读一遍，点头，然后继续前进。

spar 将立场还给你。在代理编写任何内容之前，你先说明更改属于哪里、你会如何做，以及它会在哪里出错。然后它实现，向你展示差异，并记录下你的模型出错的每一个地方。

这些差距累积成一份你从未需要选择的课程。你最常遗漏的概念会自行浮出水面，摩擦也随之而来，因此你永远不必决定要努力。

它的样子

› add an endpoint for cancelling an order

  spar: level 2 (skeleton), 2 open gaps on "transaction boundaries in an ORM"

  Before I write anything:
    1. Where does this belong, and why there?
    2. How would you approach it? (two sentences)
    3. Where will this go wrong?

› 1. Orders controller, calling into the service
  2. load the order, set status, save
  3. no idea

  [writes the controller, the DI wiring and the error handling,
   and leaves the one line that matters]

  // TODO(spar: decide the transaction boundary. Who opens it,
  //             and what happens if the refund call fails halfway?)

你自己写那五行。然后 spar done 将它们与代理会写的内容进行比较，并将每个差异归入三类之一：你误解了某些东西，你打错了某些东西，或者你的版本更好。只有前两者被记录为差距。

三周后，在无关的工作中：

spar: one gap has come due. Ask them to explain "transaction boundaries in an ORM"
in their own words at the next natural pause. Do not show them the answer first.

顺便说一句，回答“不知道”也没关系。它会按原样记录，并且这是一个足够强的信号，表明下一个涉及该概念的任务会对你提出更多要求，而不是更少。

Related MCP server: Learning Assistant MCP Server

安装

npm i -g spar-agent
spar install                                       # finds your agents, backs up, merges
spar setup --project /path/to/repo --stack ".NET"

最后一行很重要：在你未指定的目录中，什么都不会发生。 全新安装是完全惰性的。它甚至不会创建 ~/.spar，直到你将其指向一个项目。

spar install 对非其写入的文件很谨慎。它会合并到已有内容中，先备份文件，并且只替换它自己放置的条目。运行两次，第二次运行不会改变任何东西。使用 --dry-run 查看它将执行的操作。

你的位置

spar stats        # in the terminal
spar dashboard    # one self-contained HTML file

CALIBRATION, share of predictions that held, by week
  2026-07-13  ███████▁▁▁   67%     4/6   clean   mean level 2.3
  2026-07-20  ████▁▁▁▁▁▁   44%     4/9   clean   mean level 2.3
  2026-08-03  ████████▁▁   83%    10/12  clean   mean level 0.8
  2026-08-17  ██████████  100%     9/9   clean   mean level 0.3

CURRICULUM, concepts by weakness. The top row is what to learn next.
  * idempotency in webhooks              3 open / 3   box 1.3
    transaction boundaries in an ORM     8 open / 8   box 2.0
    EF change tracking                   0 open / 3   box 5.0

重要的数字是校准：你的预测中完全没有产生误解的比例。故意不是差距计数，因为计数只会上升，并且会在你变得更好时被解读为下降。

六周的虚构 .NET 入职培训。页面跟随你的系统主题。

仪表板是一个永不接触网络的单文件。没有 CDN、没有网络字体、没有图表库，图表是手写 SVG。每个数字都位于标记中，因此页面在关闭脚本、严格 CSP 或附件预览下读取相同。脚本仅为焦点栏添加多选。它仍然可以在五年后，通过双击，离线打开。

其中没有任何连续记录、积分或徽章。在一个“不知道”是有用答案的工具中，计数器只会教会你假装能力。

用图片解释

spar card --layout chain --title "Predict before you're told" \
  --subtitle "The gap between your guess and what was true is worth writing down." \
  --step "you:You predict" --step "agent:AI implements" --step "you:You compare"

每张卡片一个概念，写入 ~/.spar/cards/。四种布局涵盖大多数解释：步骤链、扇出、两方之间的序列以及比较。

限制是强制执行的，而不是建议。超过五个步骤、超过三个要点或第四个颜色角色，命令将拒绝渲染。这是故意的，因为小图片的全部价值在于它保持小，而只存在于提示中的规则会漂移。如果它无法渲染，答案是两张卡片。

颜色标记某物是什么，而不是它是哪个步骤，因此 --step "you:..." 在你制作的每张卡片上保持 you 相同颜色。~/.spar/config.json 中的 cards.theme 选择外观：neon（默认，深色带轮廓框）或 plain。

级别

在级别 2 和 3，代理总是留下失败的测试，如果它没有，spar 会拒绝交接。没有测试的标记会给你一个猜测，并且没有东西可以检查它，因此找出你是否正确的唯一方法是询问代理，这正是整个工具旨在打破的依赖。测试是让你可以独自工作二十分钟并仍然知道的原因。

在项目上设置 testCommand，spar 也会在交接时运行测试套件，并期望它是红色的，因为一个已经通过空存根测试的测试没有固定任何东西：

spar setup --project "$(pwd)" --test-command "npm test"

该检查默认关闭。自动运行别人的测试套件是侵入性的，并且可能很慢。

没有关闭开关，只有级别 0。你自己的差距日志建议级别并告诉你原因，你总是可以否决它。否决会被计数，因为有人不断纠正建议是在告诉你阈值是错误的。

分步处理工单

spar plan --from docs/plan.md          # reads ## Task / ### Task headings
spar plan --step "..." --step "..."    # or name the steps yourself
spar plan                              # where am I
spar step done --session <id>

当计划处于活动状态时，步骤就是任务。门控每个步骤触发一次，而不是从静默中猜测，每个步骤从你的差距日志中获得自己的级别，并且你的预测附加到步骤而不是会话，因此它明天仍然存在。

这种粒度是关键。“哪里会出错？”是关于“添加取消端点”的真实问题，而“实现取消和退款”则是一个猜测，猜测会使校准数字停止测量任何东西。

spar 不计划。你的代理读取工单，你的规划器将其分解；spar 决定每个步骤中有多少是你的。计划位于项目中的 .spar/ 中，spar 在创建它的那一刻将其添加到你的 .gitignore 中。

每个代理获得什么

MCP 在 hooks 不标准化的地方是标准化的，因此服务器无需适配器即可到达每个 MCP 客户端。它唯一不能做的是门控，因为 MCP 服务器提供工具，并且永远不会拦截主机自己的写入。这种限制是维护每个代理 hook 适配器的全部论据，也是自愿层成为良好试用但糟糕替代品的原因。

将其安装为插件

/plugin marketplace add Lander-Parren/spar

这提供了两个插件。spar 是这个仓库。humanizer 是可选的，不是我的：它是 blader/humanizer，MIT，Copyright (c) 2025 Siqi Chen，固定到特定提交而不是跟踪其主分支。

它与 spar 并列列出，而不是复制到其中，因此它从自己的仓库更新并保留自己的作者。它存在的原因：spar 的整个生命都在向一个仍然困惑的人解释某事，而一个读起来像机器写的解释是失去他们的最快方式。spar 自己的技能为不安装它的人携带了该规则的简短版本。

它不会做什么

一切都留在你的机器上，在 ~/.spar/ 中。没有账户、没有遥测、没有网络调用、没有自己的 API 密钥。日志保存概念和误解，而不是你的业务逻辑，这就是为什么它可以安全地截图给同事。

并且它总是失败开放。缺少二进制文件、配置损坏、自身代码中的错误：门打开，你继续前进。学习工具永远不应该成为你无法交付的原因。

每个任务一次，而不是每个文件一次。一个预测背后的十五次编辑是一个门控。

它监视 shell 命令以及写入工具，因为代理使用 cat > file <<EOF 或 perl -0pi 的频率远高于专用写入工具，并且某些设置告诉它更喜欢这样。shell 命令只有在它实际写入跟踪项目内的某个位置时才会被停止：重定向、tee、就地 sed 和 perl、cp 和 mv 目标，以及打开文件进行写入的解释器单行。读取和测试运行不受影响。shell 无法通过正则表达式解析，因此这是故意保守的，会错过异国情调的形式，而不是停止普通工作。

只要其中有移动，任务就会保持活动状态，并在 30 分钟静默后失效（~/.spar/config.json 中的 idleMinutes）。这衡量的是空闲而不是年龄，因此长时间仔细的任务永远不会中途被打断。如果你在计时器用完之前开始新的事情，spar next --session <id> 会立即重新武装它。

这种偏差是故意的。在后续操作上重新武装会花费你三十秒，并促使你使用 spar rush，这就是这些工具死亡的方式。错过一个任务会花费一个差距，并且该概念会再次出现。

一个差距在会话开始时返回，为下一个自然暂停而措辞为问题。永远不是队列，永远不是中断。回答得好，它会向上移动一个框（1、3、7、16 和 35 天）。回答得不好，它会在明天重新开始。

没有单独的应用，也没有可以忽略的收件箱，因为它到达你已经在工作的会话中。

无需冒险即可试用

example/ 是一个没有依赖的小型 TypeScript 项目，旨在被指向。

cd example
spar setup --project "$(pwd)" --stack "TypeScript"

然后要求你的代理添加订单取消，并观察门控阻止它。example/README.md 解释了要查找的内容。

指令所在位置

命令发出事实。技能说如何处理它们。spar done 打印差异；什么算作误解而不是拼写错误在技能中。门控报告任务尚未被门控并命名命令；为什么你首先预测在技能中。

这种拆分存在，以便任何支持技能的客户端都可以读取该过程，并且无需发布即可更改。对于无法加载技能的代理，spar guide <topic> 从同一文件中打印相同的部分：

spar guide                       # list the topics
spar guide the-closing-review

一个来源，两种交付方式，因此两者不会漂移。测试断言 hook 指向的每个部分都存在，这意味着重命名标题会破坏构建，而不是将某人发送到不存在的页面。

npm install
npm test              # spar's own suite
npm run build
npm run emit          # regenerate the checked-in hook configs
npm run validate:example   # drive every hook end to end against example/

validate:example 是捕获接线问题的那个。单元测试证明各个部分；该脚本证明真实的 hook 负载在一次性 home 中，针对构建的二进制文件，产生它应该产生的决策。

相同的 hook 定义被检查了三次：Claude Code 的插件布局、Agent Plugins 命名空间和 Cursor 的。这两个标准在客户端特定文件的位置上存在分歧，因此没有单一位置可以同时满足两者。所有三个都由 npm run emit 从 src/core/hookconfig.ts 生成，并且测试在它们漂移时立即失败。

许可证

MIT