# adhd

> 来源：[GitHub](https://github.com/UditAkhourii/adhd) · ⭐ 463 stars

# ADHD：为 AI 编码智能体注入"发散-收敛"思维技能

## 项目简介

在 AI 编程助手遍地开花的今天，大多数工具仍停留在"单线程思考"模式：接收提示、生成代码、结束对话。这种线性推理在面对复杂架构设计或跨领域问题时，往往陷入局部最优陷阱。**ADHD** 项目另辟蹊径，将认知科学中的"树状思维"（Tree-of-Thought）机制引入 Claude Agent SDK，让 AI 智能体具备类人的多路径探索能力。

项目命名颇具巧思——ADHD 并非医学术语的消极借用，而是对注意力"多线程跳跃"特质的正向重构。核心价值在于构建了一个**认知框架编排系统**：智能体不再沿着单一思路埋头苦干，而是主动"分神"到多个思维框架下并行推演，通过评分机制筛选优质路径，再对胜出者进行深度挖掘。这种"先发散、后收敛"的策略，本质上是对人类创意工作者头脑风暴过程的算法化模拟。463 个 Star 的背后，是开发者社区对"如何让 AI 真正具备创造性思维"这一命题的集体关注。

## 核心特性

- **多框架并行发散（Cognitive Framing）**：支持同时启动多个"认知框架"（如架构师视角、安全审计视角、性能优化视角），每个框架独立生成推理路径，避免单一思维定式的遮蔽效应

- **动态评分与剪枝（Scoring & Pruning）**：内置评估函数对各路推理实时打分，自动淘汰低质量或陷入循环的分支，将计算资源集中于高潜力方向

- **幸存者深度强化（Deepening）**：对经过筛选的优质思维路径进行递归深化，支持多轮迭代精炼，直至产出可执行的最终方案

- **Claude Agent SDK 原生集成**：深度绑定 Anthropic 官方 SDK，利用其工具调用（Tool Use）和上下文管理特性，而非外部胶合层的粗糙拼接

- **TypeScript 全栈类型安全**：从框架定义到评分策略，完整的类型推导确保复杂编排逻辑的可维护性

## 技术实现

ADHD 的技术架构呈现出清晰的分层设计。底层依赖 **Claude Agent SDK** 的 `AgentLoop` 与 `Tool` 抽象，但关键创新在于中间层的**思维状态机**实现。

项目将单次推理任务建模为树形结构中的节点，每个节点携带三个核心属性：`frame`（认知框架标识）、`score`（当前路径评分）、`depth`（递归深度）。框架调度器（Frame Dispatcher）采用**广度优先的受控并发**策略：初始节点被复制到 N 个并行框架中，各框架通过 SDK 的异步工具调用独立执行。这里的技术难点在于上下文隔离——ADHD 通过为每个分支维护独立的 `MessageParam[]` 历史栈，避免不同思维路径的"交叉污染"。

评分模块的设计尤为精巧。项目并未采用简单的 LLM-as-Judge 模式，而是引入**多维度加权矩阵**：代码可执行性（通过沙箱预检）、认知覆盖度（与问题维度的匹配率）、新颖性（与已有路径的编辑距离）共同构成评分向量。剪枝触发条件采用自适应阈值——当某分支连续两轮评分增长低于 5% 时，即标记为"陷阱"并终止资源投入。这种**早期停止机制**（Early Stopping）显著降低了 token 消耗。

TypeScript 的类型系统被充分利用于框架契约定义。开发者通过实现 `CognitiveFrame<TContext, TOutput>` 接口即可扩展自定义思维框架，泛型约束确保上下文数据与输出结构的类型一致性，这在复杂多步推理场景中大幅减少了运行时错误。

## 快速上手

```typescript
import { ADHD } from 'adhd';
import { z } from 'zod';

// 1. 定义认知框架
const frames = [
  {
    id: 'architect',
    prompt: '从系统架构角度分析：扩展性、模块边界、依赖关系',
    weight: 1.2
  },
  {
    id: 'security',
    prompt: '从安全审计角度分析：攻击面、输入验证、权限边界',
    weight: 1.0
  },
  {
    id: 'performance',
    prompt: '从性能工程角度分析：时间复杂度、内存模式、热点预测',
    weight: 0.9
  }
];

// 2. 初始化 ADHD 实例
const thinker = new ADHD({
  model: 'claude-3-5-sonnet-20241022',
  maxParallelFrames: 3,
  pruneThreshold: 0.6,
  maxDepth: 3,
  frames
});

// 3. 执行树状推理
const result = await thinker.solve({
  problem: '设计一个支持 10万 QPS 的实时排行榜系统',
  outputSchema: z.object({
    architecture: z.string(),
    tradeoffs: z.array(z.string()),
    risks: z.array(z.string())
  })
});

// 4. 查看思维演进路径
console.log(result.winningPath.frame); // 'architect' | 'security' | 'performance'
console.log(result.prunedPaths.length); // 被剪枝的低质量路径数
console.log(result.depthReached); // 实际达到的递归深度
```

上述代码展示了典型的工作流：定义多重视角框架 → 配置剪枝与深度参数 → 注入结构化问题 → 获取带完整元数据的结果。`outputSchema` 通过 Zod 约束确保输出可用性，这是生产环境集成的关键。

## 应用场景

**复杂技术方案选型**：在微服务拆分、数据库选型等"没有标准答案"的架构决策中，ADHD 可并行推演 CAP 权衡、团队技能匹配、迁移成本等维度，避免决策者被单一技术博客的片面观点带偏。某团队曾用其在 3 轮深度迭代中，从 12 个初始方向收敛到 2 个可行方案，决策周期从两周压缩至两天。

**安全漏洞挖掘与修复**：将"攻击者视角"与"防御者视角"设为对立框架，让 AI 在自我对抗中发现边界情况。评分模块中的可执行性检查可自动验证 PoC 代码，避免 LLM 生成"看似合理却无法运行"的虚假漏洞利用。

**跨学科创意生成**：产品功能设计时，同步启动"用户心理学""商业模式""技术可行性"三个框架，让通常由不同角色承担的视角碰撞在单次推理中完成。这对资源有限的初创团队尤为珍贵——相当于用代码实现了迷你版的"设计冲刺"（Design Sprint）。

## 总结

ADHD 的价值不在于又一个 LLM 包装工具，而在于**将认知科学方法论转化为可工程化的智能体技能**。它适合那些已越过"让 AI 写 CURD"阶段、开始探索复杂问题求解的开发者与团队。当前 463 Star 的体量意味着项目仍处于早期验证期，核心架构的稳定性与更多框架生态的丰富度，将是决定其能否从"有趣的实验"进化为"基础设施"的关键。对于追求 AI 智能体"深度思考"而非"快速应答"的工程师，ADHD 提供了一个值得深入研究的 TypeScript 实现范式。