ideakit

ideakit

只维护一个创意仓库，每个创意单独放在一个文件夹里，并且一次只专注于其中一个。ideakit 会在创意出现时立即记录下来，开展讨论会话，报告每个创意的进展，将研究和验证工作分派给负责的工具包，并在用户要求保留答案时，把答案归入该创意自己的日志。

创意是某人想要思考的主题，而不是已经承诺要着手开发的项目。有些创意会成为产品。大多数只会留作笔记，这正是设计初衷。

随手记更小：它只是一闪而过的想法，没有文件夹、没有标识名，也不代表任何承诺。随手记事板随时接收任何主题，而某条随手记只有在反复出现时才会获得一个文件夹。

八种模式。jot 将零散想法记到随手记事板上。promote 将反复出现的随手记转成独立创意。capture 记录创意，然后停止。session 是用于思考的模式。status 报告状态，不写入任何内容。research 和 validate 将问题发出去（validate 通过用户发起，由用户启动 validatekit），再带回答案。close 记录结论。

jot、promote、capture 和 close 会自行写入。其他模式都会先询问是否写入，用户拒绝也会接受。 请参阅保存是请求，而非默认操作。

模式选择

根据意图判断，而不是根据措辞。

• “记下这个”“突然想到”“把这个加到随手记事板上”使用 jot。它只负责记录，然后停止。
• “把那条随手记转正”“这个值得单独建个文件夹”“把 j-042 设为创意”使用 promote。
• “我有个创意”“记录这个创意”“把这个写下来”使用 capture。它只负责记录，然后停止。
• “我们来想想 X”“围绕 X 头脑风暴”“继续讨论 X 创意”使用 session。
• “我的创意进展如何”“接下来该思考什么”“我之前对 X 想到哪了”使用 status。
• “还有谁在做这个”“这个需要用到哪个库”“这个类别的成本是多少”使用 research。
• “这能成为一门生意吗”“会有人愿意为此付费吗”“我该开发这个吗”使用 validate。
• “我不做这个了”“我要开发这个”“先搁置这个”使用 close。

如果请求想了解全貌或进行思考，却没有提到具体创意，就使用 status 或 session，不要猜。 status 会报告所有创意；session 会询问要打开哪个创意。请求想了解全貌时，运行 status。请求想进行思考时，运行 session 并询问具体创意。

如果请求确实无法判断应使用 capture 还是 session，先运行 capture。记录下来的创意随时可以接着进行会话；未记录的创意却不会留下任何东西。

如果请求确实无法判断应使用 capture 还是 jot，就使用 jot。 随手记不需要文件夹，也不需要永久标识名，而当它值得保留时，promote 可以随时将其升级。判断依据是“创意”这个词：用户把想法称为创意时，就使用 capture。

创意仓库

所有状态都存放在用户工作仓库之外的同一个仓库中，默认路径为 ~/ideas，除非 $IDEAKIT_HOME 指定了其他位置。

~/ideas/                            ← one git repo; $IDEAKIT_HOME overrides
  INDEX.md                          ← the router
  jotpad/
    INDEX.md                        ← the jot router
    YYYY-MM-DD.md                   ← that day's jots, append-only
  topics/<slug>/
    IDEA.md                         ← a stable head plus an ## Open block
    NOTES.md                        ← the dated log, append-only
    SOURCES.md                      ← collected links, created lazily
    docs/plans/                     ← a plan skill writes here
    docs/research/                  ← research answers, kept on request
    docs/validation/                ← validation write-ups, kept on request
    docs/sessions/                  ← full session records, on request only
    docs/adr/                       ← decision records
    assets/                         ← diagrams and screenshots

先解析 $IDEAKIT_HOME，并使用绝对路径。 任何模式都不会更改工作目录。从工作仓库中启动模式时，它不会触碰该仓库中的任何文件，因此宿主仓库自身的约定不适用于 ideakit 写入的内容。这样一来，即使在任务进行中出现创意，也能直接记入创意仓库。

首次使用时创建仓库，并在其中运行 git init。绝不自动提交。 会话结束时询问是否提交，并接受用户拒绝。

路由器

INDEX.md 为每个想法保留一行，并附上别名，这样遇到宽泛的请求时，无需打开任何文件即可完成路由：

| Idea | Slug | Also called | Summary | Open question | Status | Last touched |
|------|------|-------------|---------|---------------|--------|--------------|
| Agent memory substrate | `agent-memory` | memory layer, agent recall, context store | A shared store an agent writes facts to and reads back across sessions | Does retrieval beat a bigger window | active | 2026-08-19 |

状态为 active、building、parked 或 closed。building 表示实现在另一个仓库中进行，其单元格会注明该仓库：`building` · owner/repo。parked 表示用户已叫停。closed 表示已在该想法的 NOTES.md 中写下结论。

路由器单元格的边界：Summary 和 Open question 各占一行。 它们分别说明这个想法是什么，以及尚未解决的问题是什么。两者都不包含理由、立场或尚未成形的论点。Markdown 表格会被整体读取，因此无法通过选择性读取路由器来遵守下方的隔离规则；要遵守这条规则，就必须限制路由器可以容纳的内容。这样，路由 10 个想法只需读取 10 行，不会带入任何干扰。

只读一个想法文件夹，绝不同时读两个

这是最关键的规则。 读取 INDEX.md，将请求对应到唯一一个 slug。然后只读取 topics/<slug>/。绝不对 topics/ 使用通配符，也绝不在整个仓库中搜索上下文。列出 topics/ 的内容没有问题，因为列出目录不等于读取其中内容。

这条规则有两个支撑理由。想法之间会相互干扰：同一窗口中同时出现两个主题时，一个主题尚未成形的思路会渗入下一个主题，而第二个想法会在无人察觉的情况下继承第一个想法的框架。成本的增长方向也不合理：30 个想法只需读取约 30 行路由信息，而打开它们却要消耗数万个 token。

唯一的有限例外。 只有当用户在请求中点名另一个想法（“这和 Agent 记忆的想法有关联吗？”）时，才打开第二个主题文件夹。该文件夹在本次会话中为只读，关联内容只能写入主想法的 NOTES.md。一次会话，一个日志归属者。如果关联看起来显而易见，但用户没有询问，就用一句话说明关联，并保持该文件夹关闭。

这条规则在 pad 的两侧都适用。 主题模式不会打开 jotpad/ 下的任何文件，jotpad 模式也不会打开 topics/ 下的任何文件。关于 jot 会话如何限制自身的读取范围，请参阅《Jotpad》；关于唯一一个同时触及两者的模式，请参阅 promote。

三个主题文件

IDEA.md 是一份持续更新的说明，分为两部分。 开头部分说明这个想法是什么、面向谁，以及它要产生意义需要满足什么条件。下方的 ## Open 区块列出尚待解答的问题和可能的下一步。

如果某次会话改变了这个想法是什么，就重写开头部分。每次会话都必须拟写更新后的 ## Open 区块，并与对应的日志条目一起保存。这样的拆分提供了可核查的边界：## Open 区块与最新一条 NOTES.md 条目相符。 这也能避免无定论的会话在开头部分上反复折腾，却没有任何变化。

NOTES.md 是日志，只能追加。 每次保存的会话使用一个 ## YYYY-MM-DD 标题，记录作出了什么决定、否决了什么以及原因，还有会话结束时尚未解决的问题。不要改动之前的条目；改变主意时，新增一条带日期的记录。日志是记录，IDEA.md 是它的缓存，因此两者不一致时，应根据 NOTES.md 重写 IDEA.md。

SOURCES.md 用于收集链接，每个链接占一行，注明阅读日期，并用一行说明它解决了什么问题。首次使用时再创建，不要在记录想法时创建。搜索前先检查它。

随手记

jotpad/ 用来存放没有归入任何文件夹的想法。 主题不限，不设 slug，也不作承诺。文件夹意味着承诺，而大多数想法在刚冒出来的那个晚上都不值得拥有一个文件夹。随手记就是它们暂时停留的地方。

jotpad/INDEX.md 是随手记路由表，每条随手记占一行：

| Jot | Id | Summary | Entries | State |
|-----|----|---------|---------|-------|
| Cheap OCR for receipts | `j-042` | A phone photo of a receipt turned into a line-item table, run locally | 2026-08-24, 2026-09-02 | live |

状态为 live、promoted 或 dropped。promoted 单元格会注明它最终归属的 slug：`promoted` · `agent-memory`。dropped 行会保留，以免同一个想法又以新随手记的形式出现。Summary 单元格须为单行，且遵守与想法路由表相同的长度限制，因为这张表也会被整体读取。

jotpad/YYYY-MM-DD.md 存放当天的随手记，每条占一个区块：

## j-042 · Cheap OCR for receipts

Two to six lines in the user's own words: what the thought is, and what set it off.

带日期的文件只追加内容，和 NOTES.md 一样。 区块一旦写入，就绝不编辑；新建区块只能写入当天的文件。每次状态变更都写入 jotpad/INDEX.md。这样，随手记本就只有一个查阅位置和一个修复位置，而想法出现的日期也会留存下来，无论之后发生什么都不会改变。

ID 永久有效，绝不重复使用。 分别查看 jotpad/INDEX.md 和当天的文件，取两者中较大的最高 ID，再加一。查看当天的文件，也能避免某个区块的行尚未写入时，下一条随手记占用了它的 ID。用户在之后某天再次提起某条随手记时，应在当天的文件中以相同 ID 新建区块，并在对应行中添加该日期。同一天再次提起时，应在当天的文件中以相同 ID 追加第二个区块，Entries 单元格保持不变，因为该单元格统计的是天数。出现三条记录就意味着应当提升，因为用户已经在三个不同日期重新提起了它，这正是文件夹的用途。

丢弃一条随手记只需修改一个单元格。 用户表示某条随手记不重要时，将其状态设为 dropped，除此之外不作任何记录。它不需要模式，也不需要记录判定结果：随手记从未声称足够重要，因此不需要这些。

隔离保护也适用于随手记本。 jot 运行会读取 jotpad/INDEX.md 和 INDEX.md 这两个有长度限制的路由表，以及当天的带日期文件，并向其中追加内容。讨论某条随手记时，会读取上述文件，外加该条随手记对应行列出的带日期文件。两者都不会打开 topics/ 下的文件夹，任何主题模式也不会打开 jotpad/ 下的文件。唯一的跨界操作是 promote，它读取一条随手记，并写入一个主题文件夹。

带日期的文件确实会把互不相关的随手记并列存放，因此读取一条线索时，邻近的其他随手记也会进入上下文窗口。我们接受这一成本，而且它是有限的。随手记本按定义存放零散想法；如果某条线索重要到值得避免受到这些想法的干扰，那它就值得执行 promote。

路由表是缓存，因此要修复它

修复分为两个层级，每种模式只修复自己能看到的内容。

• 只要某种模式打开了某个主题文件夹并对其作出更改，就应主动提出重写该主题的路由行，并与更改内容的记录一并提供保存选项。capture 和 close 会直接写入对应行，无需询问。
• 发现未注册的文件夹时，应报告它，而不是打开它。 路由表中缺少的文件夹需要从其内部读取五个字段，而读取该文件夹会为了记账而违反隔离保护。因此，status 会指出该文件夹，并说明需要对其运行 session 来完成注册。
• 无需询问，直接修复随手记路由表。 其中的单元格记录 ID、条目日期和状态，属于记账，而非思考。某条随手记的行是其状态的唯一记录，因此每当某种模式更改其状态时，都应写入该行。

修复未完成的写入

每次多文件写入都会按固定顺序执行：先写记录，再写缓存。在主题文件夹中，顺序是 NOTES.md、IDEA.md，然后是路由器行。在便笺中，顺序是带日期的区块，然后是便笺路由器行。因此，如果一次运行中途停止，记录会领先于缓存，不会落后；每种情况都有对应的修复方式：

• IDEA.md 与最后一条 NOTES.md 记录不一致。 下次打开该文件夹的模式会在单独的保存提示中，提供根据日志重写的选项。
• 主题文件夹没有路由器行，说明 capture 或 promote 提前停止。status 会将其报告为未注册，而对其运行 session 会写入该行。
• 今天的文件中的区块没有便笺路由器行。 下次运行 jot 时，会在今天的文件中发现该 ID，并直接写入缺失的行，与其他便笺路由器修复一样，无需询问。

slug 是永久的

slug 简短、小写，采用 kebab-case，并取自想法的核心名词。capture 会提出 slug，并在创建任何内容前与用户确认，因为之后没有任何模式会重命名文件夹。这样，成本只在创建时发生一次，而不必为罕见情况构建重命名机制。路由器的 Idea 列保存当前的人类可读名称，并且可以随时修改。

产物保存在主题文件夹中

产物根目录是主题文件夹，而不是仓库根目录。 如果某个技能记录的路径位于 docs/ 下，则应改为写入 topics/<slug>/docs/ 下，同时保留其子路径和文件名约定。docs/plans/0001-plan-sso-2026-07-23.md 会变为 topics/<slug>/docs/plans/0001-plan-sso-2026-07-23.md。

这是根目录替换，因此适用于所有技能，包括本文件编写之后新增的技能。仓库根目录没有 docs/ 目录，也不会新增该目录。

文件名遵循 NNNN-<type>-<slug>-YYYY-MM-DD.md 格式，前面是四位序号，末尾是产物的创建日期。序号按主题文件夹内的目录分别计数：在该目录中，检查当前工作树、git worktree list 列出的每个其他工作树，以及主题文件夹位于 git 仓库中时的 origin/HEAD，取最高的前导序号并加一；从 0001 开始。必须检查这三处，否则并行工作树可能会取得相同序号。若某个来源不可用（例如没有远程），则跳过；没有 git 时只列出该目录。文件后续编辑时，整个文件名保持不变。

保存是一项要求，而不是默认行为

讨论本身就是交付成果。只有当讨论值得保存时，用户才会要求生成文件。 大多数会话都只是探索，然后就此结束。一个塞满了没人想要的条目的仓库，比内容稀少的仓库更糟，因为后续运行 status 时，会把每一行都当作用户有意保存的内容。

因此，每次写入都必须经过一道关卡：

1. 照常拟好要写入的内容。 完整起草 NOTES.md 条目、## Open 块和路由器行。
2. 将草稿放在代码块中打印出来，并在其上方注明它将写入的绝对路径。
3. 询问用户是保存、编辑还是丢弃。 用户拒绝时，就不要写入任何内容。

先拟好内容，用户答应保存时才会省事。如果什么都没附上，只问一句“要我保存吗？”，用户拒绝的理由就会不对。

这道关卡适用于每个文件，也包括路由器行。 INDEX.md 保存的是摘要和一个开放问题，属于思考内容，而不是记录事项，所以该行应与它描述的条目放在一起。用户没有保存的会话并未触及这个想法，因此 Last touched 应保持原样。

jot、promote、capture 和 close 不受此规则限制，因为在这些模式中，用户的要求本身就是写入。 “把这个记下来”、“给那个建个文件夹”、“把这个写下来”和“我不再继续这个了”都是用户已经提出的明确要求，而文件就是该模式的全部输出。把它们变成提议，相当于要求用户确认刚刚提出的要求。promote 仍会在创建任何内容前确认 slug，这是另一个问题：不是要不要写入，而是用什么永久名称。

用户随时都可以说“保存这个”。 到时就写入条目，然后继续。如果讨论在会话中途解决了某件事，且要重新构建它需要付出实质性工作，则主动提出保存，但每次会话最多一次。

明确说明代价。 session 会先显示状态报告，而 status 会优先列出带有开放问题、最久未更新的想法。两者都会读取 NOTES.md。未保存的会话会让这些读取结果无法反映用户的真实想法。每次运行时如果没有写入任何内容，交接说明都会明确指出这一点，因此内容稀少的日志不会被误认为是一个平静无事的月份。

各模式

每个模式的正文都单独存放在 modes/ 目录下的一个文件中。通过 模式选择 进行路由，读取相应文件并遵循其中的说明。此行以上的所有内容以及以下共享章节都适用于每种模式，因此不会在各模式文件中重复说明。

• 模式 jot → 读取 modes/jot.md，然后遵循其中的说明。
• 模式 promote → 读取 modes/promote.md，然后遵循其中的说明。
• 模式 capture → 读取 modes/capture.md，然后遵循其中的说明。
• 模式 session → 读取 modes/session.md，然后遵循其中的说明。
• 模式 status → 读取 modes/status.md，然后遵循其中的说明。
• 模式 research → 读取 modes/research.md，然后遵循其中的说明。
• 模式 validate → 读取 modes/validate.md，然后遵循其中的说明。
• 模式 close → 读取 modes/close.md，然后遵循其中的说明。

派发约定

research 会将问题发送给同级技能。validate 无法这样做，因为 validatekit 只能通过调用运行，因此由用户运行并带回答案；以下规则同样适用于该答案。每次派发都遵循四条规则：

• 让同级技能直接在对话中回答。 researchkit 和 validatekit 默认都在对话中作答且不保存任何内容，ideakit 也采用这一默认设置。不要代替用户回应它们的保存提示。
• 压下同级技能的交接内容，输出 ideakit 自己的交接内容。 派发只是一个子步骤，两条互相竞争的后续步骤提示对任何人都没有帮助。
• 回答之后再提供保存产物，绝不提前。 只询问一次是否保留。用户同意后，根据同级技能在对话中的回答自行写入文件，保存到 topics/<slug>/docs/…，并沿用同级技能自己的子路径和文件名约定。若重新运行同级技能来保存，文件会落在工作目录中，因为同级技能只说明自己的根目录，不会遵循任何宿主的约定。在派发前询问，就等于用户还不知道答案是否值得保留时便先行询问。
• 只将已保存的内容归档。 用户同意后，提供一条带日期的 NOTES.md 记录，其中写明问题、答案和产物路径，并同时更新 IDEA.md 和路由器。用户拒绝后，答案留在对话中，日志保持原样。

想法自己的日志会保存一条权威记录，涵盖用户保留的所有内容，因此之后的会话只需读取一个文件，就能找到每个已保存的答案。

交接

请用操作性语气撰写本节：每句话只包含一条指令，使用主动语态和现在时，不用比喻。

变更内容。 写明新增的记录、保存的产物和设定的状态。也要写明未发生的变更：用户拒绝保存的内容、你报告但未打开的文件夹、以精简版本运行的派发，以及你未说明理由而拒绝写下的结论。

说明本次运行未写入任何内容的情况。 用一行说明：本次会话未在仓库中留下任何记录。不要委婉表达，也不要暗示讨论已保存。仅当用户提出要求时，才再次提供保存选项。

保存位置。 给出主题文件夹路径。若某种模式写入了 jot，则给出 jot 文件路径和 jot id。若某种模式写入了产物，则给出产物路径。若本次运行创建了仓库，则给出仓库路径。

下一步。 根据状态指定一个优先操作：

从上到下，选择第一个符合条件的规则。

• 本次运行给某个 live jot 写入了第三条或后续记录 → 对该 jot 运行 promote。
• 本次运行写入了其他 jot → 说明没有下一步。不要提议就此开启会话。
• 该 jot 刚刚变为一个想法 → 对新的 slug 运行 session。
• 会话在一个未决问题上停止 → 针对该问题再次运行 session。
• 未决问题需要外部事实 → 运行 research。
• 该想法是一个尚无结论的商业构想 → 运行 validate。
• 该想法已明确到足以规划工作 → 在项目仓库中规划，使用规划技能（若已安装 plankit，则使用 plankit）。
• 没有未决事项 → 运行 close，并说明适用的结论。
• 该想法刚刚关闭 → 说明没有下一步。不要凭空编造后续操作。
• 本次运行是 validate，且用户选择运行 validatekit → 使用该想法的路径运行 /validatekit，然后让 ideakit 保留结论。

然后提供提交 ideas 仓库的选项。未经同意，绝不执行提交。若本次运行未写入任何内容，则跳过提交选项。

status 运行的交接方式不同。 它的全部输出都是交接内容，且仪表板已经指定了优先操作。说明没有任何变更。不要重复输出该操作，也不要提供提交选项。

备注

• 隔离防护优先于此处所有其他规则。 解析一个 slug，打开一个文件夹。status 会报告所有想法，但不会打开任何文件夹；这正是防护机制在发挥作用，并非例外。
• 保留什么由用户决定。 撰写内容、展示出来，然后等待。jot、promote、capture 和 close 是例外，没有其他例外。
• capture 和 jot 都会停止。 它们的任务是在想法于不合时宜的时刻出现时，不遗漏任何内容。把其中任何一个变成会话，反而会让想法被丢掉。
• 便笺区什么都收，文件夹里的内容则需要凭努力赢得。 jot 不需要主题、slug，也不必与现有想法相关。promote 是关卡，只有重新回到某个想法时才会打开。
• 绝不重命名 slug，也绝不重复使用 jot id。 创建时确认 slug，之后不要改动。名称变更应记录在路由表的 Idea 列中。
• 此仓库不包含任何代码。 ideakit 从不编写应用程序代码，也从不开启 issue。成为实际工作的想法应移至项目仓库，并在那里创建 issue。
• 绝不要单独提交 ideas 仓库。
• 如果没有可写文件系统（例如基于浏览器的 Agent），保存选项就改为打印。请明确说明这一点，并将 NOTES.md 条目和任何产物以代码块形式打印出来，供用户保存，同时给出它们应保存到的路径。不要声称完成了并未发生的写入。如果文件系统可读，status 仍会运行。