UditAkhourii/adhd 来源：https://github.com/UditAkhourii/adhd # ADHD —— 面向 Agent 的技能 CI（https://github.com/UditAkhourii/adhd/actions/workflows/ci.yml） npm（https://www.npmjs.com/package/adhd-agent） 许可证 Node 论文（https://adhdstack.github.io/） > 针对自回归推理中过早收敛的架构级修复方案。 📄 预印本： ADHD：面向编码 Agent 的并行发散式构思（https://adhdstack.github.io/） 👤 作者： Udit Akhouri —— @akhouriudit（https://x.com/akhouriudit）· LinkedIn（https://www.linkedin.com/in/udit-akhouri-10160a168/）· [email protected]

线性思维链会陷入局部最优：每个生成的 token 都会影响下一个，因此模型会锚定在最初生成的思路上。思维树虽然扩展了搜索空间，但仍然在共享的上下文中进行，因此锚定效应会跨分支持续存在。ADHD 将其视为一种架构问题，而非提示工程问题——它在刻意扭曲的认知框架下生成 N 个独立隔离的推理过程，在发散阶段零共享上下文，随后运行一个独立的评审环节，进行评分、聚类、剪除陷阱、并深化幸存方案。就像史蒂夫·乔布斯所说的“连点成线“——但这里的“点“是在刻意认知扭曲下先并行生成出来，并且评审功能被关闭，然后再对它们进行评估。

在创意工作、跨学科工作、设计决策、模糊调试、命名、API 表面设计、策略、定位，以及任何形如“给我几种方法…“的提示时，ADHD 是不需动脑就能直接使用的技能。

提供三种使用方式：作为 Agent 技能（skills/adhd/SKILL.md，通过 npx skills add UditAkhourii/adhd 直接集成，适用于 Claude Code、Cursor、Antigravity、Codex 及约 50 多个其他 Agent）；作为 Node/TS 库（adhd-agent（https://www.npmjs.com/package/adhd-agent），托管于 npm）；以及作为 CLI（adhd "你的问题描述这里"）。库和 CLI 均基于 Claude Agent SDK（https://docs.claude.com/en/api/agent-sdk）构建。

安装

一行命令，适用于所有 Agent

npx skills add UditAkhourii/adhd

就是这样。skills（https://github.com/vercel-labs/skills）CLI 会自动检测你使用的 Agent，并将 skills/adhd/SKILL.md 放入正确的位置。支持 Claude Code、Claude.ai、Antigravity、Cursor、Codex、Cline、Continue、Aider、Gemini CLI、Windsurf、Cody、Roo、Augment、OpenCode、Kilo、Kimi、Qwen、Trae、Replit、Warp 以及另外约 40 个 Agent。重启你的 Agent 即可。该技能会在遇到 brainstorm、ideate、design、naming、refactor 以及“给我几种方法“这类意图时自动触发。也可以手动调用：/adhd "设计一个能在 leader 选举中存活下来的限速器"。

有用的参数：

npx skills add UditAkhourii/adhd -g                                  # 全局安装（而非按项目安装）
npx skills add UditAkhourii/adhd -a claude-code -a cursor            # 指定目标 Agent
npx skills add UditAkhourii/adhd --copy                              # 复制文件而非创建符号链接
npx skills add UditAkhourii/adhd --list                              # 查看仓库中可用的技能

手动安装（如果你没有 npx）

技能文件位于 skills/adhd/SKILL.md。可以通过 curl 将其下载到你的 Agent 技能目录中：

# Claude Code（全局）
mkdir -p ~/.claude/skills/adhd
curl -fsSL https://raw.githubusercontent.com/UditAkhourii/adhd/main/skills/adhd/SKILL.md \
  -o ~/.claude/skills/adhd/SKILL.md

# Claude Code（按项目）
mkdir -p .claude/skills/adhd
curl -fsSL https://raw.githubusercontent.com/UditAkhourii/adhd/main/skills/adhd/SKILL.md \
  -o .claude/skills/adhd/SKILL.md

# Cursor（项目规则）
curl -fsSL https://raw.githubusercontent.com/UditAkhourii/adhd/main/skills/adhd/SKILL.md >> .cursorrules

对于 Claude.ai 网页版/桌面版：打开项目设置 → Skills → Add skill → 上传 skills/adhd/SKILL.md。

对于 Cline、Continue、Aider、Roo Code 及其他 Agent：将 SKILL.md 的内容（跳过 YAML 前言）粘贴到你的 Agent 的系统提示或规则字段中。

编程集成（Agent SDK）

import { query } from "@anthropic-ai/claude-agent-sdk";
import { readFileSync } from "node:fs";

const skill = readFileSync("./skills/adhd/SKILL.md", "utf8");

for await (const m of query({
  prompt: "设计一个针对 LLM 挂起 90 秒的 CLI 的重试策略",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code", append: skill },
    allowedTools: ["Task"],
  },
})) {
  // ...
}

作为 CLI 使用（终端使用，无需 Agent）

npm install -g adhd-agent
adhd "设计一个能在 leader 选举中存活下来的限速器"

认证：会从环境中读取 ANTHROPIC_API_KEY，或者继承本地 Claude Code 安装的认证信息。

作为库使用（集成到你自己的 Agent 中）

npm install adhd-agent

import { run } from "adhd-agent";

const result = await run({
  problem: "...",
  framesPerRun: 5,
  topK: 3,
});

从源码构建

git clone https://github.com/UditAkhourii/adhd.git
cd adhd && npm install && npm run build

快速上手指南

CLI

adhd "设计一个能在 leader 选举中存活下来的限速器"
adhd "给这个函数命名" --frames 3 --ideas 8 --top 2
adhd "我们有一个 CLI 在 LLM 调用时挂起 90 秒。正确的重试/用户体验策略是什么？" \
  --frames 5 --ideas 6 --top 3 --context ./client.ts
adhd "..." --json > result.json

库

import { run, renderText } from "adhd-agent";

const result = await run({
  problem: "在突发负载下，我们应该如何对这个队列进行分片？",
  context: readFileSync("./queue.ts", "utf8"),
  framesPerRun: 6,
  ideasPerFrame: 8,
  topK: 3,
  onEvent: (e) => console.error(e),
});

console.log(renderText(result));
// 或者操作：
// result.shortlist → 2-4 个最有前景的想法及其评分
// result.nonObviousPick → 新颖度最高且可行的那个方案
// result.traps → "看起来不错但实际上不可行"的列表，附带理由
// result.deepened → 前 K 个深化后的方案：草图 + 风险 + 第一步 + 子想法
// result.clusters → 想法空间的形态描述

ADHD 究竟是什么

一个两阶段的循环，两个阶段之间有严格的壁垒。混合这两个阶段会扼杀想法质量，因为评审会压制生成器。

阶段 1 —— 发散（ADHD 模式）

从框架库中选取 N 个认知框架。生成 N 个并行的 Agent SDK 查询，每个查询都是一个全新的独立会话。每个分支看到的是：

• 问题
• 一个框架的视角提示（例如：“你从延迟、内存布局和物理约束的角度思考。请把这个重新表述成一个硬件问题。”）
• 一个系统提示，禁止评估、排序或模棱两可 —— 纯生成，输出 JSON 数组，无文字叙述。

关键：各个分支互相不可见。“监管者“分支永远不会读到“速通者“分支写的内容。无锚定、无共享上下文、无收敛压力。

阶段 2 —— 聚焦

现在评审回归。分三步进行：

1. 评分 —— 对每个叶子节点按新颖性 / 可行性 / 匹配度进行评分。对陷阱进行标注并给出理由。
2. 聚类 —— 按底层角度（而非表面关键词）进行分组（例如“去掉服务器的方案“、“缓存型方案”）—— 揭示空间的形态。
3. 深化前 K 名 —— 对前 K 个进行深化：描述其工作原理，指出主要风险，命名第一个具体步骤，生成 3-5 个子想法（变体、混合、解锁方案）。

输出结果：

• 宽泛集合，已聚类
• 2-4 个候选方案的短名单
• 非显而易见但可行的选项被明确标记出来
• 陷阱列表，每个陷阱附有理由
• 深化后的分支 ——“连接起来的点”
• 一个挑衅性问题（通配卡问题）

架构 —— 并行发散在底层如何工作

面向研究人员和基础设施人员：机制本身，而非隐喻。

上下文窗口管理

每个发散分支都是针对 Claude Agent SDK（https://docs.claude.com/en/api/agent-sdk）的一次独立 query() 调用 —— 这是一个全新的、无状态的会话，没有共享 KV 缓存、没有共享消息历史、除了 claude_code 预设外没有共享的系统提示。进入一个分支的唯一 token 是：

system = 预设 + 框架视角提示 + "禁止评估/排序/模棱两可，JSON 数组输出"
user = 问题 + 可选上下文

Token 成本在分支数上呈线性增长（O(N × 每个分支)），而非二次增长——不存在将之前分支的内容广播给后续分支的情况。“ADHD“的扇出发散是真正的并发推理，而不是在共享轨迹上交错解码。请参见 src/llm.ts 和 src/diverge.ts。

剪枝与收敛标准

收敛是一个独立的 LLM 调用，使用相反的系统提示（评审姿态，强制评估）。它执行三个结构化步骤——请参见 src/score.ts、src/cluster.ts、src/deepen.ts：

1. 评分 —— 每个叶子节点按新颖性 / 可行性 / 匹配度（各 0-10 分）进行评分，输出结构化 JSON。陷阱会附上机制性理由（例如：“在多写者负载下，该搁架方案不是线程安全的”），而非模糊的风险标签。
2. 聚类 —— 按角度进行分组（“去掉服务器的方案”、“缓存型方案”），而非按表面关键词聚类。揭示设计空间的形态。
3. 深化前 K 名 —— 对于 K 个综合得分最高的非陷阱叶子节点，生成：草图、主要风险、第一个具体步骤、3-5 个子想法（变体/混合/解锁方案）。不使用启发式阈值，也不使用 logit 偏置引导。评审的结构化输出即为剪枝决策。默认 K=3；nonObviousPick 字段会标记出新颖度最高且可行的叶子节点，即使它的匹配度并非最高。

路由与编排

通过并行的 query() 调用实现多 Agent 编排，并通过可配置的信号量（concurrency，默认为 4）进行控制。框架选择（参见 src/frames.ts）按种子确定性进行，并在 codeMode 开启时偏向工程视角。每个框架都是一个系统提示载荷，会重新表述整个问题——“把这个重新表述成一个硬件问题”、“把这个重新表述成监管者会怎么想”、“把这个重新表述成 10 岁孩子的想法”——而不是在 logit 层面的干预。

// 关键调用形态 —— bench/run-evals.ts 和 src/diverge.ts
const branches = await Promise.all(
  frames.map(frame =>
    withSemaphore(concurrency, () =>
      callLLM({
        systemPrompt: `${frame.vantage}\n\n禁止：评估、排序、模棱两可。输出 JSON 数组。`,
        userPrompt: `${problem}\n\n${context ?? ""}`,
      })
    )
  )
);
// 在发散期间，branches[i] 永远不会看到 branches[j] —— 这是通过构造保证的。

生成器与评审的分离是机械性的（不同的 API 调用、不同的系统提示），而不是在同一个会话中通过提示来承诺的。这是 ADHD 区别于上下文内思维树的关键设计选择。

ADHD 与思维链（以及思维树）有何不同

很容易混淆。它们在结构上是不同的。

三个关键差异

1. 隔离，而非搜索。 思维链和思维树的分支共享一个上下文窗口——到第 4 步时，模型已经锚定在了前 3 步写的内容上。ADHD 的分支在发散期间互相不可见。锚定效应通过构造而非提示来消除。

2. 框架，而非下一步变体。 思维树的分支通常变化的是下一步动作（“试试这个数字 / 试试那个数字”）。ADHD 改变了生成器的整个视角。它不是“从这里出发的下一步是什么“，而是*“把整个问题重新问一遍，仿佛你是一个免疫系统。”* 这会产生结构上不同的想法，而非相近的想法——这正是跨学科工作所需要的。

3. 生成器与评审的分离是机械性的，而非承诺性的。 在思维链和思维树中，模型会边推理边评估。ADHD 让发散成为独立的 LLM 调用，其系统提示禁止评估。收敛则是另一个独立的调用，姿态相反。两种姿态、两次传递、互斥。

一句话总结

思维链让一个脑袋思考得更慢。思维树让一个脑袋搜索得更广。ADHD 让许多脑袋以不同的方式并行思考，然后让一个评审来挑选。

科普版

思维链是一个人在小心地推演。思维树是一个人下棋时会预想 N 步。ADHD 是一个头脑风暴房间，里面有一位硬件工程师、一位监管者、一个 10 岁孩子和一位速通者——然后隔壁还有一个编辑房间。

与思维树重叠之处

ADHD确实是思维树的一个变体：深化环节会显式地扩展前 K 个节点。新颖之处在于驱动分支的因素（框架而非下一步）以及生成器/评审分离的强制方式（独立的 LLM 调用、独立的系统提示、发散期间零共享上下文）。

为什么这是创意和跨学科工作不容置疑的技能

创意和跨领域工作正是过早收敛代价最大的场景。

• 正确答案往往不在任何一个领域的固定套路中——你需要移植一种机制。ADHD 的跨领域框架（生物学、物流、游戏设计、市场）正是为此设计的。
• 教科书式的答案通常是一个陷阱——它看起来正确是因为它很熟悉。ADHD 的独立评审环节会标注陷阱并给出命名理由，而不仅仅是“可能存在风险“。
• 有趣的想法存在于尴尬的中间地带——过了最初 3 个、但尚未进入荒诞之前。单次生成的思路永远到不了这里，因为每个 token 都受到前一个 token 的偏见影响。并行隔离的分支则能做到。
• 你并不总是知道什么样子才算好。ADHD 的聚类环节会揭示设计空间的形态，这样你就可以在角度层面进行讨论，而不是一个一个想法地争论。

一行总结：当单次输出的 Agent 只会给出一个合情合理但转眼即忘的答案时，ADHD 就是你要伸手去拿的工具。

框架（认知扭曲）

内置 15 个框架，在开启 --code-mode 时偏向工程视角。每个框架由一个视角提示 + 标签组成。部分示例：

• 硬件工程师 —— “你从延迟、内存布局、物理约束的角度思考。”
• 监管者 / 审计员 —— “什么是必须可证明、可追溯、可拒绝的？”
• 10 岁孩子 —— “忽略常规。什么是天真但不受约束的方法？”
• 试图破坏它的竞争对手 —— 对抗性视角；通过反转浮现想法
• 生物学 —— 免疫系统、神经可塑性、细胞信号传导、肠道菌群
• 物流 —— 队列、批处理、即时生产、中心与辐射、退货
• 游戏设计 —— 循环、奖励、摩擦、存档点、速通技巧
• 市场 —— 拍卖、期货合约、清算所
• 反转 —— 问相反的问题，然后取反
• 零预算 / 无限预算 —— 极端打破锚定
• 去掉承重假设 —— 如果框架/数据库/网络不存在，什么变得可能？
• 速通者 —— 漏洞、跳过、帧完美的快捷方式
• 蚁群 / 蜂群 —— 无中央规划者、局部规则、涌现行为
• 凌晨 3 点值班 —— 哪种设计能让你不会被呼叫？

编辑 src/frames.ts 可以添加你自己的框架。一个框架只需要 5 行代码。

何时使用 ADHD（以及何时不该用）

适合用于：

• 架构与设计决策（存储层、分片、认证模型、队列拓扑、重试策略）
• API / SDK / CLI 表面设计
• 模糊调试 —— 生成你未曾考虑过的假设类别
• 迁移与重构规划
• 命名 —— 函数、产品、服务、环境变量
• 代码重构 —— 在开始之前探索替代结构
• 策略与定位 —— 定义什么应该被构建以及为什么

不适合用于：

• 事实检索 —— 事实不会因为你有 5 个不同的认知框架而改变
• 翻译 —— 你不需要一种新的方式来重新表述翻译结果
• 简单的信息查找 —— 不会受益于跨领域视角
• 算术 / 逻辑 —— 你不需要让一个 10 岁孩子和一位硬件工程师同时参与数学运算
• 任何你需要可重现输出的场景 —— ADP 的输出可能因随机种子而不同
• 任何你希望输出简短、精确且没有替代方案的场景 —— 如果你已经知道你要什么，就不要使用 ADHD

一个简单的判断标准：如果你能想象出一个可能的答案，使用 ADHD 可能不会改变结果。如果你无法想象出好答案是什么样的，ADHD 可能会彻底改变结果。

在 Agent 事件循环中工作

使用 Agent-SDK 事件 来观察发散过程：

const result = await run({
  problem: "...",
  onEvent: (event) => {
    if (event.type === "branch_start") {
      console.log(`开始分支 ${event.index+1}/${event.total}`);
    }
    if (event.type === "branch_complete") {
      console.log(`完成分支 ${event.index+1}`);
    }
    if (event.type === "phase_complete") {
      console.log(`完成阶段 ${event.phase}: ${event.summary}`);
    }
  },
});

事件流：

1. phase_start { phase: “diverge” } —— 发散阶段开始
2. branch_start { index, frame, total }
3. branch_complete { index, ideaCount, tokenUsage }
4. （对所有分支重复）
5. phase_start { phase: “score” } —— 评审与评分
6. phase_start { phase: “cluster” }
7. phase_start { phase: “deepen” }
8. complete —— 完整结果，包含所有字段

配置参考

CLI 参数

adhd <problem>                                 # 必要：问题描述
  --frames, -f   <number>     # 要生成的发散发支数量（默认 5，基于问题复杂度自动调整）
  --ideas        <number>     # 每个分支生成的想法数量（默认 8）
  --top, -t      <number>     # 深化前 K 个最佳想法（默认 3）
  --context, -c  <path>       # 上下文文件（代码、现有设计等）
  --code-mode, -C             # 偏向工程/编码视角（默认开启）
  --concurrency  <number>     # 最大并发 LLM 调用数（默认 4）
  --seed, -s     <string>     # 框架选择的种子（默认随机）
  --json, -j                  # 以 JSON 格式输出结构化结果
  --quiet, -q                 # 仅输出最终结果
  --verbose, -v               # 详细日志输出（调试用）

库 API

interface ADHDConfig {
  problem: string;
  context?: string;
  framesPerRun?: number;          // 默认 5
  ideasPerFrame?: number;         // 默认 8
  topK?: number;                  // 默认 3
  codeMode?: boolean;             // 默认 true
  concurrency?: number;           // 默认 4
  seed?: string;                  // 默认随机
  onEvent?: (event: ADHDEvent) => void;
  model?: string;                 // 默认从环境变量读取
}

interface ADHDResult {
  shortlist: ScoredIdea[];
  nonObviousPick: ScoredIdea;
  traps: Trap[];
  deepened: DeepenedIdea[];
  clusters: IdeaCluster[];
  provocation: string;
  diagnostics: {
    branchesCreated: number;
    ideasGenerated: number;
    tokensUsed: number;
    totalTimeMs: number;
  };
}

基准测试与评估

仓库包含一个基准测试套件，用于衡量 ADHD 与标准提示在创意生成上的差异：

npm run bench

运行 10 个开放式问题的评估，并使用以下指标进行比较：

• 多样性 —— 在 8 个维度上对 top-K 想法进行语义距离评分
• 新颖性 —— 与典型解决方案的偏离程度
• 风险意识 —— 识别的陷阱数量及陷阱的特异性
• 跨领域迁移 —— 从非临近领域带来的想法比例
• 时间 —— 端到端延迟

结果见 bench/results/。

待添加

陷阱与常见误解

• “这不就是思维树吗？” —— 参见上面的对比表。差异性在于隔离性、框架驱动力以及机械的生成器/评审分离。
• “这不就是 fDiv 吗？” —— 在传统统计学中，f 发散衡量的是分布之间的差异。ADHD 使用发散来生成分布，而非衡量它们。
• “这只对简单问题有用。” —— 复杂性越高，过早收敛的成本越大。ADHD 在需要跨领域迁移时效果最佳。
• “这会浪费 token。” —— 发散阶段会最大化 token 利用率（每个分支都会生成结构化的输出）。评审阶段是有选择性的。总体而言，你在这一个调用中获得的覆盖范围，相当于通过自回归方式花费 10 倍 token 才能达到的效果。
• “它肯定会随机输出结果。” —— 种子固定时可确定性地重复，虽然输出的是高方差文本。

为什么叫“ADHD“？

这是一个苦乐参半的隐喻。实际的 ADHD（注意力缺陷多动症）并不是一种超能力，也不是一种增强——它是一种使人衰弱的疾病，当你希望专注时无法专注，当你需要聚焦时不停发散，并伴随执行功能障碍。这个库借用了这个名称作为隐喻，用于一种认知程序——这种程序会将发散和聚焦有意地分离开来——但这并不代表对这种疾病的现实体验的认可或美化。对于那些由于实际疾病而在这方面有困难的人，使用这个工具可能有助于完成他们原本难以开始的任务。它是一个技能，你可以选择何时使用它。

贡献

欢迎 PR！请先运行测试。

npm test          # 运行测试
npm run bench     # 运行基准测试
npm run lint      # 检查代码风格

行为准则 | 贡献指南

许可证

MIT —— 请参阅 LICENSE。