opty (Boj)

乐观

一个基于以下内容构建的代码智能工具 超维计算 （HDC）。它对函数签名、类型定义和从代码库中的导入进行索引，并提供语义搜索、跨文件引用、影响分析、更改检测和函数聚类——所有这些都在本地进行，无需网络调用或GPU。

例子

快速启动--一次性查询（无守护进程）：

$ opty oneshot "authentication error handling" --dir ~/projects/myapp
# indexed 1,247 units across 89 files
functions[5]{name,signature,file,line}:
handleAuthError,pub fn handleAuthError(err: AuthError) !Response {,src/auth.zig,156
validateTokenOrFail,fn validateTokenOrFail(token: []const u8) !User {,src/auth.zig,203
logAuthFailure,fn logAuthFailure(reason: []const u8, ip: []const u8) void {,src/logging.zig,78

启动即时查询守护进程：

$ opty daemon ~/projects/myapp &
opty daemon on http://127.0.0.1:7390

$ opty query "HTTP route handlers"
functions[8]{name,signature,file,line}:
handleGetUser,pub fn handleGetUser(req: *Request, res: *Response) !void {,src/routes/users.zig,12
handleCreatePost,pub fn handleCreatePost(req: *Request, res: *Response) !void {,src/routes/posts.zig,45
handleLogin,pub fn handleLogin(req: *Request, res: *Response) !void {,src/routes/auth.zig,23
...

$ opty query "database connection pooling"
functions[3]{name,signature,file,line}:
initPool,pub fn initPool(alloc: Allocator, config: PoolConfig) !Pool {,src/db/pool.zig,34
acquireConnection,pub fn acquireConnection(pool: *Pool) !*Connection {,src/db/pool.zig,67
releaseConnection,pub fn releaseConnection(pool: *Pool, conn: *Connection) void {,src/db/pool.zig,89

全局守护进程--适用于所有项目：

$ opty global --port 7390 &

$ cd ~/projects/api-server
$ opty query "error types"        # auto-indexes api-server

$ cd ~/projects/frontend
$ opty query "React components"   # auto-indexes frontend

$ opty status
Project: /home/you/projects/api-server
  Files: 142  Units: 2,891  Memory: 3.6 MB
Project: /home/you/projects/frontend  
  Files: 203  Units: 4,127  Memory: 5.1 MB

语义搜索按概念而非确切名称查找代码：

# Find authentication logic without knowing function names
$ opty query "user login session management"
→ handleLogin, createSession, validateSession, refreshToken

# Discover error handling patterns
$ opty query "handle failures and errors"  
→ handleError, tryParseOrFail, logFailure, unwrapOrDefault

# Explore data structures
$ opty query "user data models"
→ User struct, UserProfile struct, UserSettings struct

何时使用opty vs grep

opty和grep解决了不同的问题。使用适合工作的工具：

场景，opty，grep。 |---|---|---| |“索引是如何工作的？”|✅ 退货 scanAndIndex, IgnoreFilter, watchLoop | ❌ 你会做什么？ | |查找的所有用途 alloc.free | ❌ 过于语法化|✅ grep "alloc.free" | |“存在哪些类型？”|✅ opty_ast 为每种类型提供嵌套|⚠️ grep "pub const.*struct" 易碎| |查找端口7390的设置位置|❌ HDC不索引文字|✅ grep "7390" | |“什么是HTTP API表面？”|✅ 从语义上返回路由处理程序|⚠️ grep "router\." 有效但缺少上下文| |重命名变量|❌ 完全错误的工具|✅ grep查找，编辑替换|

经验法则： opty for *理解*，grep for *定位*，查看 *阅读*，编辑 *变化*.

• 乐观 回答概念性问题——“什么处理身份验证？”、“向我展示错误处理模式”、“项目结构是什么？”——在这些问题中，你不知道确切的符号名称。它从单个自然语言查询中返回多个文件的结果。
• 全局正则表达式打印 查找精确的文本——特定的字符串、正则表达式模式、符号引用、配置值。当你知道的时候，这是正确的工具 *什么* 你正在寻找。
• 选择_ast 在一次调用中给出项目或文件的完整结构框架（所有函数、类型、导入、字段、具有嵌套深度的变量），这对于在深入代码之前进行定位非常有用。

在实践中，opty查询使用 代币数量减少88-93% 与读取等效源文件相比，它在向LLM提供上下文时特别有用。

它做什么

opty提取物 代码单元骨架 --函数签名、类型/结构定义和导入声明——来自源文件。它将每一个编码为10000位二进制超容器，然后使用 混合搜索 （HDC+BM25通过互易排名融合）将自然语言查询与它们进行匹配。

除了搜索，opty还构建了一个 跨文件参考图 将导入链接到定义，实现影响分析、符号上下文查找和更改检测。

它擅长什么：

• 探索 --“什么处理身份验证？”找到 handleAuth, validateToken, refreshSession 即使您的查询没有共享精确的子字符串
• 发现 --按概念而不是名称浏览不熟悉的代码库
• 影响分析 --“如果我改变 handleAuth什么坏了？“显示了下游家属的信心得分
• 代码审查 --“此差异中更改了哪些符号？”将git更改映射到受影响的函数和类型
• 建筑 --“子系统是什么？”将相关符号分为功能组
• 简明概述 --结果出来了 TOON格式，它使用的令牌比JSON少约60%，在向LLM提供上下文时非常有用

它没有做什么：

• 索引函数体、注释或文档字符串——仅签名
• 替换grep以获得精确的字符串匹配或正则表达式模式
• 了解什么代码 *做* --它在名称、类型和结构标记上匹配

将其视为代码库的快速、智能的目录。你仍然需要阅读实际的代码来理解它。

运作原理

1. 解析 --扫描源文件并通过模式匹配或 树保姆
2. 编码 --使用HDC绑定/捆绑代数将每个代码单元映射到10000位二进制超容器。将标识符（camelCase、snake_case）拆分为子标记以进行部分匹配
3. 索引 --将向量存储在内存中的关联存储器中，构建BM25文本索引和跨文件引用图
4. 查询 --混合搜索通过倒排融合将HDC相似性与BM25关键字匹配相结合
5. 输出 --返回TOON格式的匹配代码签名

所有索引和查询都在本地进行。没有网络调用，没有LLM推理，没有GPU。

快速开始

# Build (requires Zig 0.15+)
zig build

# One-shot query (no daemon)
./zig-out/bin/opty oneshot "authentication error handling" --dir /path/to/project

# Or run as a daemon for instant queries
./zig-out/bin/opty daemon /path/to/project &
./zig-out/bin/opty query "functions that handle database errors"
./zig-out/bin/opty status
./zig-out/bin/opty stop

在Windows上，使用 .\zig-out\bin\opty.exe 而不是 ./zig-out/bin/opty.

全局多项目守护进程

这 全球 mode运行一个服务于所有项目的opty守护进程。项目在第一次查询时自动加载，并在内存中保持索引。

# Start the global daemon
opty global --port 7390 &

# Query from any project directory — opty auto-detects the project root
cd ~/projects/myapp
opty query "authentication flow"

cd ~/projects/api-server
opty query "database connection pool"

# Check all loaded projects
opty status

# Reindex current project
opty reindex

项目根检测 从CWD中走出来，寻找： .git, build.zig, Cargo.toml, package.json, go.mod, pyproject.toml, Makefile, CMakeLists.txt, .sln, Gemfile, pom.xml, build.gradle.

自动加载 意味着您永远不需要配置项目路径。就 cd 在任何项目和查询中，opty都会动态地对其进行索引（通常\ [--port N] |通过HTTP查询正在运行的守护进程| | opty status [--port N] |显示当前项目的索引文件/单位计数| | opty reindex [--port N] |强制对当前项目进行全面重新索引| | opty stop [--port N] |关闭守护进程| | opty oneshot [--dir D] |一次性索引+查询（无后台程序）| | opty version` |显示版本|

HTTP API

守护进程在上公开HTTP API http://127.0.0.1: :

curl -X POST http://localhost:7390/query \
  -d '{"cwd":"/path/to/project","query":"error handling"}'

curl http://localhost:7390/status

输出示例（TOON格式）

functions[3]{name,signature,file,line}:
handleAuth,pub fn handleAuth(req: Request) !Response {,src/auth.zig,42
validateToken,fn validateToken(token: []const u8) !bool {,src/auth.zig,87
refreshSession,pub fn refreshSession(id: SessionId) !Session {,src/session.zig,23

与等效的JSON相比（约多60%的令牌）：

{"functions":[{"name":"handleAuth","signature":"pub fn handleAuth(req: Request) !Response {","file":"src/auth.zig","line":42},{"name":"validateToken","signature":"fn validateToken(token: []const u8) !bool {","file":"src/auth.zig","line":87},{"name":"refreshSession","signature":"pub fn refreshSession(id: SessionId) !Session {","file":"src/session.zig","line":23}]}

MCP服务器（用于AI编码代理）

opty揭露了一个 主控程序 服务器，因此编码代理（Claude、Copilot、Cursor等）可以作为工具查询代码库索引。

这是最有用的作为 探索与分析工具 --帮助代理在代码库中定位，理解符号关系，并在做出更改之前评估影响。

工具

opty_ast 参数：

两者都省略 file 和 pattern 以获得完整的AST项目。你可以合并 file 和 pattern --结果是两者的结合。

工具示例

opty_refs --查找位置 handleAuth 已定义并由谁导入：

definitions[1]{name,kind,file,line}:
handleAuth,fn,src/auth.zig,42
references[2]{import_name,file,line}:
handleAuth,src/login.zig,1
handleAuth,src/middleware.zig,3

opty_impact --什么打破了如果 handleAuth 变化？

impact{source:"handleAuth",affected:4,max_depth:2}
depth_0[1]{name,kind,file,line,confidence}:
handleAuth,fn,src/auth.zig,42,1.000
depth_1[2]{name,kind,file,line,confidence}:
loginUser,fn,src/login.zig,15,0.500
checkMiddleware,fn,src/middleware.zig,33,0.500
depth_2[1]{name,kind,file,line,confidence}:
appMain,fn,src/main.zig,10,0.333

opty_context --一切关于 handleAuth 在一次通话中：

symbol{name:"handleAuth",kind:fn,file:"src/auth.zig",line:42}
signature: pub fn handleAuth(req: Request) !Response {
referenced_by[2]{name,kind,file,line}:
handleAuth,import,src/login.zig,1
handleAuth,import,src/middleware.zig,3
references[1]{name,kind,file,line}:
validateToken,fn,src/token.zig,8
siblings[2]{name,kind,line}:
refreshSession,fn,56
AuthError,type,12

opty_changes --哪些符号受到了最近变化的影响？

changes[3]{name,kind,file,line,change}:
handleAuth,fn,src/auth.zig,42,modified
UserConfig,type,src/config.zig,10,added
oldHelper,fn,src/utils.zig,88,deleted

opty_clusters --发现功能子系统：

clusters[3]{id,label,size}:
0,auth-handle-token,5
1,database-query-pool,4
2,config-parse-env,3
cluster_0[5]{name,kind,file,line}:
handleAuth,fn,src/auth.zig,42
validateToken,fn,src/auth.zig,87
refreshSession,fn,src/session.zig,23
AuthError,type,src/auth.zig,12
tokenStore,import,src/auth.zig,1

配置

放下一个 .mcp.json 在您的项目根目录中。全局守护进程运行时：

{
  "mcpServers": {
    "opty": {
      "type": "http",
      "url": "http://localhost:7390/mcp"
    }
  }
}

对于独立模式（无守护进程，通过stdio进行进程内索引）：

{
  "mcpServers": {
    "opty": {
      "command": "/path/to/opty",
      "args": ["mcp", "."]
    }
  }
}

这适用于Claude Desktop(~/.claude/claude_desktop_config.json)克劳德代码(~/.claude.json)，VS代码(.vscode/mcp.json)，以及任何兼容MCP的客户端。

混合搜索

查询使用 互易秩融合 （RRF）结合两种搜索方法：

• HDC相似性 --通过汉明距离在10000比特超容器上进行模糊概念匹配。善于发现 handleAuth 当你搜索“身份验证功能”时，因为子令牌像 auth 和 handle 重叠。
• BM25关键字搜索 --与TF-IDF加权的精确术语匹配。擅长提升包含准确查询词的结果，并处理仅HDC会遗漏的情况（例如，当代码使用“DB”而不是“数据库”时搜索“DB”）。

RRF使用公式合并两个排名列表 RRF(d) = Σ 1/(k + rank) 哪里 k=60，确保在两种方法中排名靠前的结果出现在顶部。

树保姆解析

opty包括一个可选 树保姆 解析后端，提供比默认的基于模式的解析器更准确的代码提取。Tree sitter正确地处理了逐行解析遗漏的多行签名、装饰器和其他构造。

目前通过树保姆支持： 之字形 和 python所有其他语言都使用基于模式的解析器。添加更多语言需要将语法的C源代码提供给 deps/.

树保姆运行时和语法作为C源代码提供，并由编译 build.zig --不需要系统依赖性。

支持的语言

Zig、TypeScript、JavaScript、Python、Go、Rust、C、C++、Java、Ruby、F#、C#

局限性

• 仅限签名 --函数体、注释和文档字符串没有索引。你可以找到 handleAuthError 但不是 if err != nil 里面。
• 基于模式的解析 --大多数语言使用逐行模式匹配（Zig和Python可以使用树形图以获得更好的准确性）。非树型语言中的多行签名等边缘情况可能会被忽略。
• 没有学习语义 --HDC使用随机投影，而不是训练嵌入。“数据库”和“DB”是不相关的向量。BM25混合搜索可以缓解精确关键字匹配的问题，但真正的同义词理解需要神经嵌入。
• 参考分辨率基于名称 --跨文件引用将导入名称与定义名称相匹配。它不会解析完整的模块路径或处理别名导入。

HDC编码的工作原理

超维计算 （HDC）使用三个操作将信息编码为非常高维的二进制向量：

• 地图 --为每个原子符号分配一个随机的超向量（基于哈希的确定性）
• 绑定 （XOR）-关联两个向量（例如。， role_name XOR "handleAuth")
• 捆绑 （多数票）——将多个信号组合成一个向量

每个代码单元都变成一个超容器，对其名称、子令牌、模块、文件路径和签名令牌进行编码：

function_hv = bundle(
    role_kind   XOR atom("function"),
    role_name   XOR atom("handleAuth"),
    role_name   XOR atom("handle"),       // camelCase split
    role_name   XOR atom("Auth"),         // camelCase split
    role_module XOR atom("auth"),
    role_file   XOR atom("src"),
    atom("Request"),                       // signature token
    atom("Response"),                      // signature token
)

查询匹配之所以有效，是因为查询向量与相关代码单元共享组件。“身份验证处理函数”匹配，因为它共享 atom("auth"), atom("handle")，以及 role_kind XOR atom("function").

相似性是通过汉明距离（硬件加速）计算的 popcount)，这就是为什么查询需要微秒。

HDC与神经嵌入

建筑

需要 Zig 0.15+.

zig build                           # Debug build
zig build -Doptimize=ReleaseFast    # Release build
zig build test                      # Run tests

视窗

zig build
.\zig-out\bin\opty.exe oneshot "error handling" --dir C:\Users\you\projects\myapp

Windows 子系统 for Linux

如果从WSL构建在Windows文件系统上，请使用基于tmpdir的缓存：

zig build --cache-dir /tmp/opty-zig-cache --global-cache-dir /tmp/opty-zig-global

作为systemd服务运行（Linux）

zig build
./systemd/install.sh
systemctl --user enable --now opty-daemon

默认服务运行 opty global --port 7390.

WSL： 如果WSL重启后服务未自动启动，请确保在中启用了systemd /etc/wsl.conf:

[boot]
systemd=true

然后验证linger是否已启用： loginctl show-user $USER | grep Linger=yes。更新的服务文件使用 Restart=always 并等待网络提高WSL兼容性。

Windows（任务计划程序）

$action = New-ScheduledTaskAction `
    -Execute "$env:USERPROFILE\.local\bin\opty.exe" `
    -Argument "global --port 7390"
$trigger = New-ScheduledTaskTrigger -AtLogOn
$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries
Register-ScheduledTask -TaskName "opty-daemon" -Action $action -Trigger $trigger -Settings $settings

建筑

src/
├── main.zig          CLI entry point and HTTP client
├── daemon.zig        Single-project HTTP daemon
├── global.zig        Multi-project HTTP daemon with auto-loading
├── mcp.zig           MCP JSON-RPC server (9 tools)
├── brain.zig         In-memory index (HDC + BM25 + RefMap)
├── hdc.zig           10,000-bit hypervectors, bind/bundle/similarity
├── encoder.zig       CodeUnit → HyperVector encoding
├── parser.zig        Line-by-line code extraction (12 languages)
├── treesitter.zig    Tree-sitter parsing backend (Zig, Python)
├── bm25.zig          BM25 text search + reciprocal rank fusion
├── refs.zig          Cross-file reference resolution
├── impact.zig        Blast radius analysis (BFS on ref graph)
├── context.zig       360° symbol context
├── changes.zig       Git diff → affected symbols
├── cluster.zig       Functional clustering via HDC similarity
├── toon.zig          TOON output formatting
└── ignore.zig        .gitignore support

参考文献

超维计算

1. Kanerva，P.（2009）。 超维计算：导论。 *认知计算*, 1(2), 139-159.
2. Kleyko，D.等人（2022年）。 超维计算综述。 *倒排索引综述*, 55(6), 1-51.
3. Kleyko，D.等人（2024年）。 超维计算：快速、稳健、可解释。 *计算生物学*.

实施

1. TOON格式规范
2. 模型上下文协议（MCP）
3. Zig程序设计语言
4. 树保姆

许可证

麻省理工学院