Complexity Library：用确定性分析替代AI猜测代码复杂度

Complexity Library：用确定性分析替代AI猜测代码复杂度 | 前端进阶之旅

Full translation

完整中文译文

Complexity Library 是一个确定性优先的复杂度分析应用：开发者粘贴一段 Python、JavaScript 或 TypeScript 函数，应用返回一个带有类型的增长声明、可信度、局限性说明，以及一个交互式可视化图表。有趣之处不在于它给出"O(n log n)"这个答案，而在于结果是有界的、可审查的、无需执行用户代码或让模型临时发挥一个答案就已很有用的特性。

大多数复杂度解释都处于两个不太舒服的位置：无法审查你代码的静态文章，或者能给出看似合理但缺乏可靠证据链的解释。这个项目把代码分析当作一个独立的产品界面来对待。

设计前提很简单：

解析提交的内容，推导确定性事实，做出保守的声明，从经验证的数据中渲染出执行轨迹。

这一原则决定了 API 设计、数据建模和 UI 的走向。

Web 应用基于 Next.js 16 / React 19。FastAPI 负责分析、会话、请求守卫、SSE 和持久化决策。共享的可视化契约刻意保持精简且带版本控制，这样渲染器消费的是数据，而非动态编写的 UI 逻辑。

静态分析，而非执行

对于 Python，项目使用标准库的 ast 模块。JavaScript 和 TypeScript 使用 tree-sitter。引擎在做出复杂度声明之前先记录事实：循环深度、减半行为、排序操作、二分查找约定、递归、内存分配、分支以及已知调用。

def find(items, target):
    low, high = 0, len(items) - 1
    while low <= high:
        mid = (low + high) // 2
        if items[mid] == target:
            return mid
        if items[mid] < target:
            low = mid + 1
        else:
            high = mid - 1
    return -1

分析器识别出一个循环，不断围绕中点收窄 low/high 边界。这映射到一条有文档记录的二分查找规则，生成高可信度的 O(log n) 声明，辅助空间为 O(1)。

随后实现返回的是一个 Pydantic 模型，而非自由格式的叙述：

class ComplexityAnalysis(BaseModel):
    time_complexity: TimeComplexity
    space_complexity: SpaceComplexity
    confidence: float = Field(ge=0, le=1)
    pattern: AlgorithmPattern
    reasoning: str
    assumptions: list[str]
    limitations: list[str]
    signature: ComplexitySignature

这个区别很重要。消费者可以安全地渲染可信度和局限性，持久化一个可复现的结果，或者在不知道枚举值时直接拒绝，而无需解析自然语言。

保守规则胜于捏造的确定性

引擎已知一套实用的初始集合：简单操作、线性扫描、减半循环、嵌套循环、排序、二分查找、双指针和滑动窗口形态，以及直接递归模式。它不会假装去解决任意程序分析问题。

当遇到未解决的调用时，它会降低可信度并报告局限性。当看到提交的源码时，它永远不会执行它。这两个决策使得这个应用比一个总是能说会道的系统更值得信赖。

测试套件覆盖了所有主要的增长级别——从 O(1) 到 O(n!)——并检查精确的分析字段，而不仅仅是截取一段文字快照。

cd apps/api
uv run pytest

可视化是一份数据契约

下一个设计决策很容易被忽略：可视化不是截图也不是生成的 canvas 代码。API 构建了一个受限的 VisualizationSpec，包含模板类型、有界步骤、注解、无障碍摘要和输入控件。

{
  "schema_version": 1,
  "type": "logarithmic_halving",
  "input_size": 16,
  "operation_estimate": 4,
  "accessible_summary": "The search space halves from 16 until one item remains."
}

UI 可以在本地对这个数据进行动画播放、单步执行、重置和摘要。它不需要每帧都向后台请求，也永远不会把模型输出当作可执行的组件代码。

产品的首次使用不应该需要账号。API 发出一个不透明的 HttpOnly 匿名会话 cookie，并将处理状态/SSE 访问限定在该会话范围内。本地开发使用内存仓库；生产环境可以选择接入 Supabase 来实现持久化会话和函数记录。

在分析之前，服务会检查蜜罐字段、声明的请求体大小、schema 限制和进程本地的滑动窗口速率限制。这些是有意为之的确定性保护措施。基于 Redis 的配额、队列和进一步的滥用信号是公开路线图的一部分。

浏览器发起一个异步分析任务的请求，然后连接到 server-sent-events 端点。UI 将实际的 API 阶段名称——parsing、syntax facts、loop/recursion detection、complexity decision、visualization construction——映射为可见的进度。

const events = new EventSource(`${apiUrl}${payload.events_url}`, {
  withCredentials: true,
});

events.addEventListener("completed", (message) => {
  setResult(JSON.parse(message.data));
  events.close();
});

对于本地 MVP，任务是进程内的。持久化队列和重连语义是公开的 OSS 问题，而不是隐藏在"已就绪生产"声明背后的东西。

UI：一个学习工具，而非仪表盘

Web 设计使用类似方格纸的底色、紧凑的轨迹面板、编辑风格的展示字体和等宽数据标签。这种视觉方向不是装饰性的：网格为增长轨迹提供了尺度，而蓝色/珊瑚色/苔藓绿用于区分操作状态和结果。

工作台给用户一个清晰的任务——提供一个函数并审查其主要工作。回放有原生按钮、可见焦点、无障碍文字摘要和支持减少动画的行为。learn 路由将相同的视觉语言扩展到十个输入驱动的课程，而非静态文章。

# Install the web workspace
pnpm install

# Run the API
cd apps/api
uv sync --extra dev
uv run uvicorn app.main:app --reload --port 8000

# In another terminal, from the repository root
pnpm dev:web

项目在本地运行无需 LLM、Supabase 或 Redis 凭证。当需要持久化模式时，可以使用 Supabase 迁移和确定性精选的种子命令。

贡献者接下来可以构建什么

最有价值的下一个贡献不是外观上的。它们是正确性和产品深度的工作：

当提交的文件包含多个函数时提供显式选择。

更好的本地调用图和辅助空间分析。

游标分页、PostgreSQL 全文搜索，以及跨函数、算法、课程和标签的统一发现。

更多有界的可视化模板：排序、图遍历、立方级、指数级和阶乘级增长。

持久化队列/重连处理、Redis 配额、Supabase 迁移演练，以及 E2E/无障碍/性能测试。

对于真正模糊的分析，提供一个严格受限的、provider 中立的降级方案——但不削弱确定性优先原则。

所有剩余工作都分解为带标签的公开 issue。这个仓库适合关心开发者工具、静态分析、无障碍数据可视化或安全 AI 相关系统的贡献者。

Complexity Library 是一个关于不同类型开发者学习产品的 small argument：其输出不是自信的答案，而是一个可审查的 artifact。解析器告诉我们它看到了什么。规则解释了这个声明。轨迹让增长变得可见。在系统不确定的地方，它也会说出来。

这是一个更好的学习软件如何扩展的基础。

Code & more: https://www.dailybuild.xyz/project/218-complexity-library