CodeOutline

English | 简体中文

CodeOutline 是由 Lua 实现的代码探索工具（code_explore）和 LSP Server。

• 面向编程智能体的代码探索：通过 MCP 工具 codeoutline_explore 查询符号、带行号的源码、调用路径和上下游关系；终端中可使用 codeoutline explore 完成同类查询。
• 面向编辑器的 LSP Server：通过 codeoutline lsp --stdio 提供符号、定义跳转、引用、悬停、调用层级、补全和签名提示；安装内置的 VS Code、Cursor 或 Zed 客户端即可在编辑器中使用。

面向编程智能体的轻量代码索引与查询服务：按符号查询带行号的源码、调用路径和上下游关系，自动增量刷新并缓存到磁盘。编辑器通过 LSP 使用同一套索引，获得符号、定义跳转、引用、调用层级和补全。MCP 协议（含 stdio 与 Streamable HTTP 传输）和语言服务器均由 Lua 实现，运行不依赖 Node；npm 包中的 Node 只负责找到对应平台的程序并启动。

安装与配置

需要 Node.js 20 或更新版本。npm 会按系统自动下载对应平台的运行时，无需编译器或 Lua。请全局安装，不要在客户端配置里写 npx -y：npx 会在它启动的每个服务旁边常驻一个完整的 npm 进程。

npm install -g codeoutline
codeoutline --version
codeoutline --help

如需在全局安装时对检测到的每个 AI 工具和 Zed、VS Code、Cursor 逐项确认， 请使用 npm 的前台模式。每项默认安装，随后自动启动共享服务，无需再次执行安装命令：

npm install -g codeoutline --foreground-scripts

安装过程中会按两个阶段依次检测，并对每个应用单独确认：

1. 检测 AI 工具，逐个提示是否安装代码探索功能（通过 MCP 提供 codeoutline_explore），例如 Install code_explore (MCP) for Codex (codex)? [Y/n]。
2. 检测 Zed、VS Code、Cursor，逐个提示是否安装 LSP 客户端，例如 Install CodeOutline LSP for Zed (zed)? [Y/n]。

每项默认安装：直接回车或输入 y/yes 即安装，输入 n/no 只跳过当前应用。 每项都回车即可安装全部检测结果；输入结束（EOF）则跳过剩余项目，不会自动接受默认值。 指定 --target、--editors 列表或对应环境变量时，直接按指定范围处理，不逐项询问。 交互移除配置时默认不移除，需明确输入 y。 随后会自动启动共享服务并登记自启动。重启所选 AI 工具、重载或重启编辑器后即可使用， 无需再次执行 codeoutline install。 npm 默认在后台运行安装脚本并重定向输入输出；启动器只在继承的输入输出均为终端时询问， 不会在 npm 占用终端时重新打开控制台，避免显示提示却无法输入。 未加 --foreground-scripts、在 CI 或没有可用终端时，自动安装全部检测到的集成；环境变量选择仍然优先。 普通项目级 npm install codeoutline 不会配置全局集成，请使用上面的全局安装命令完成这套流程。 以后也可以再次交互选择，或直接指定编辑器：

codeoutline editors                             # 检测并交互选择
codeoutline editors --list                      # 只查看检测结果
codeoutline editors --editors all               # 为全部检测到的编辑器安装
codeoutline editors --editors vscode            # 只安装 VS Code 客户端
codeoutline editors --editors cursor            # 只安装 Cursor 客户端
codeoutline editors --editors zed               # 只安装 Zed 客户端
codeoutline editors --editors vscode,cursor      # 指定多个编辑器，用逗号分隔

无人值守的全局 npm 安装可设置环境变量 CODEOUTLINE_EDITORS 为同样的选择，none 表示跳过。 没有交互终端时不会等待输入，本地 npm 安装不会修改编辑器安装。 发布包内置客户端，无需 Rust 工具链或从扩展市场下载。 完成后重载 VS Code/Cursor 窗口或重启 Zed。检测覆盖 PATH 和常见安装位置； 自定义位置请把编辑器 CLI 加入 PATH。Zed 使用默认用户数据目录，已有编辑器设置会保留。 VS Code/Cursor 客户端默认启用完整导航；如只需工作区符号搜索，可将 codeoutline.mode 设为 auxiliary。服务端能力见 LSP.md。

推荐：共享一个 HTTP 服务

stdio 服务是客户端的子进程，每个智能体会话（每个 Claude Code 会话、每个 Cursor 窗口）都会各自启动一份，并各自建一份内存索引。HTTP 服务只用一个进程、一份索引，供所有会话共用。

通过 npm 全局安装时，会在后台启动这个服务，并登记为登录时自动启动：Windows 写入注册表 Run 项，macOS 添加 LaunchAgent，Linux 添加 systemd 用户单元；没有 systemd 用户管理器时（WSL、容器），请自行在登录时运行 codeoutline daemon。服务会自行安装更新并重启到新版本。Agent 只需注册一次：

codeoutline install --yes                         # 自动检测 Agent、配置 MCP 并启动服务
codeoutline install --target cursor,claude,codex   # 指定需要配置的 Agent
codeoutline agents                               # 交互选择，不重启服务
codeoutline agents --list                         # 查看检测结果和配置路径
codeoutline agents --target all                   # 为全部检测到的 Agent 配置 MCP
codeoutline agents --print codex                  # 只预览配置，不写文件
codeoutline agents --target cursor --remove       # 只移除 CodeOutline 的 MCP 配置项

支持的目标标识：claude、cursor、codex、gemini、opencode、hermes、 kiro、antigravity、copilot-vscode、copilot-cli、copilot-jetbrains。 检测依据为已有应用配置目录、配置文件或 PATH 上的 CLI；未检测到时也可显式指定标识。 all、auto 表示全部检测到的目标，none 表示跳过。 install --yes 默认不安装 LSP 客户端，需要时另加 --editors all 或指定编辑器。

默认写入用户级配置；使用 --location local --project PATH 可写入项目级配置， Hermes、Antigravity、Copilot CLI 和 Copilot JetBrains 仅支持用户级。 --port 同时指定注册地址和服务启动端口。agents 只编辑配置，install 还会启动服务并登记自启动。 完成后重启对应 Agent，即可发现 codeoutline_explore 等 MCP 工具；应用自身的工具审批仍然有效。 安装器不会添加提示钩子或自动放行权限。

Claude、Codex、Gemini 和 OpenCode 的对应 CLAUDE.md、AGENTS.md 或 GEMINI.md 会加入简短的 CODEOUTLINE_START/END 使用说明。 若其中存在完整的 CODEGRAPH_START/END 块，会将其原文备份为同目录的 codegraph.md， 再从活动说明中移走。其他说明保持不变；重复安装不会重复添加。 已有不同内容的备份、残缺或重复标记会使安装停止，避免覆盖用户文件。 卸载时移除自己的说明；仅向原先提供 CodeGraph 块的文件恢复备份，且要求 PATH 仍能找到 codegraph、活动说明中没有 CodeGraph 块。 备份会保留，以便手动恢复；全局安装不扫描或修改各项目的说明文件。 codegraph.md 不是默认说明文件名，但被显式引用或主动读取时仍可能进入上下文。

已有其他设置和 JSONC 注释会保留；首次修改非空配置文件前，会保存原始文件到 <配置文件>.codeoutline.bak。 重复安装同样配置不会重写文件；已有不同的 codeoutline 配置会保留，需要显式加 --force 才替换。 不能安全编辑的复杂 TOML/YAML 布局会提示使用 agents --print 标识 手动配置。 无人值守的全局 npm 安装可设置 CODEOUTLINE_AGENTS 为 auto、all、none 或逗号分隔的目标标识； 没有终端且未指定选择时，全局 npm 安装默认处理全部检测到的 Agent 和编辑器。 将 CODEOUTLINE_AGENTS 和 CODEOUTLINE_EDITORS 都设为 none 可跳过集成安装， 或使用 --ignore-scripts 跳过整个安装配置流程。本地 npm 安装不会注册 Agent。

也可以手动配置：

Claude Code（全局添加，在任意项目中可用）：

claude mcp add --transport http codeoutline --scope user http://127.0.0.1:19876/mcp

Cursor（~/.cursor/mcp.json）：

{ "mcpServers": { "codeoutline": { "url": "http://127.0.0.1:19876/mcp" } } }

原生安装或使用 --ignore-scripts 安装后，运行 codeoutline install 完成同样的操作；--port 可指定 19876 以外的端口。安装时设置 CODEOUTLINE_AUTOSTART=0 可不登记自启动。服务日志位于 ~/.codeoutline/logs。

npm 全局安装可直接运行 codeoutline remove：先清理集成和默认用户数据， 等待运行时退出后再卸载 npm 包；清理失败时保留包，以便重试。 使用 codeoutline remove --project PATH 可同时清理指定项目的 MCP 注册。

如需分步操作，先运行 codeoutline uninstall，再运行 npm uninstall -g codeoutline。 第一步停止服务、移除自启动项、用户级 Agent MCP 配置及 VS Code/Cursor/Zed 客户端。 同时清理 VS Code/Cursor 用户设置及命名配置档中的 codeoutline.* 配置， 包括语言专属设置，保留其他设置和注释。 添加 --purge 同时清理 ~/.codeoutline 下的缓存、更新和日志； 使用 --service-only 则仅移除服务，保留集成。 添加 --project PATH 可同时移除指定项目的 MCP 注册。 删除包文件前请关闭或重载编辑器，以释放运行中的 LSP 进程。 工作区设置、编辑器自定义数据目录、远程安装和原始配置备份需单独清理。 npm 7+ 不执行卸载钩子，仅运行 npm uninstall 不会清理集成或停止服务。 发布包仍提供 preuninstall 兼容钩子，供支持它的包管理器调用； 仅在全局卸载时尝试清理集成，保留用户数据，并跳过升级及本地安装流程。 当前 npm 请使用 codeoutline remove 完成完整清理。

服务监听 127.0.0.1:19876，可访问本机任意位置的项目，在不同盘的项目之间切换无需额外配置；只有本机进程能连到它，而本机进程本来就有你的文件访问权限。共享服务没有自己的项目：客户端提供 roots 时使用 roots，否则由智能体传入 projectPath，缺少时工具会提示需要它。

如需自行运行 HTTP 服务（例如只允许访问部分目录），启动 codeoutline serve --http，并为每个允许的目录树重复一次 --allow-root；启动时不可用的目录（如未挂载的盘）只会给出提示，出现后即可使用。这样的服务会安装更新，但在重启前继续运行旧版本；Windows 上请托管原生启动器而不是 npm 启动器，原因见 DISTRIBUTION.md。

备选：stdio，每个会话一个进程

不想常驻服务时使用 stdio，每个会话自行启动和关闭自己的服务进程。

claude mcp add codeoutline --scope user -- codeoutline serve --stdio

Windows 上 Claude Code 无法直接启动 codeoutline.cmd，请改用 -- cmd /c codeoutline serve --stdio。Cursor 配置为 "command": "codeoutline", "args": ["serve", "--stdio"]。客户端不带参数启动 codeoutline（0.1.7 推荐的写法）时，得到的也是这个 stdio 服务。

未指定项目时，服务依次使用：调用参数 projectPath、启动参数 --project、客户端 roots（roots/list 返回的第一个目录）、服务启动目录。客户端通常在项目目录中启动 stdio 服务，因此全局配置无需写项目路径。访问范围默认为 --project 或启动目录，可用可重复的 --allow-root 扩大。

提供五个工具：

不使用 Node 时，可从 GitHub Releases 下载对应平台的原生压缩包，解压后直接运行 codeoutline（Windows 为 codeoutline.cmd）。

编辑器集成（LSP）

codeoutline lsp --stdio 是基于同一索引器的语言服务器。每个编辑器窗口各自启动一个服务进程、各建一份索引，不连接共享的 MCP 服务；MCP 地址也不能当作 LSP 地址使用。

解析基于名称，与 codeoutline_explore 相同，不做类型检查；不提供重命名、诊断和格式化，适合与语言自身的服务器并用，或用于没有语言服务器的场景。每次请求都会带上未保存的修改。工作区根目录的 .codeoutline.json 可以把 Lua 调用参数映射到注册位置，用于跳转定义。具体行为、限制和选项见 LSP.md。

仓库内提供轻量客户端：VS Code 与 Cursor 共用的 VSIX，以及 Zed 扩展。它们尚未发布到扩展市场，请按各自 README 安装。其他编辑器可通过通用 LSP 支持启动同一命令；目前只在 VS Code、Cursor 和 Zed 上验证过。

客户端不经过 shell 直接启动服务器：

• Linux 与 macOS：npm 安装会在 PATH 中放一个可执行的 codeoutline，客户端默认配置（codeoutline 加 lsp --stdio）即可使用。从桌面启动的编辑器可能拿不到 shell 配置文件里追加的 PATH（例如 nvm），此时请配置 command -v codeoutline 输出的绝对路径。
• Windows：npm 安装的是批处理文件 codeoutline.cmd。VS Code/Cursor 客户端会自行找到 npm 安装；Zed 会从 PATH 找到 codeoutline.cmd 并通过 cmd.exe 启动，两者都无需设置。无法启动批处理文件的客户端，请把命令配置为 node，参数为 <npm 全局目录>/codeoutline/launcher/codeoutline.cjs、lsp、--stdio；npm root -g 可输出全局目录，通常为 C:\Users\<用户名>\AppData\Roaming\npm\node_modules。使用原生压缩包时，运行其中的 bin/xnet.exe，参数为 <解压目录>/scripts/codeoutline/command.lua、LOG_STDERR=1、LOG_FILE=0、lsp、--stdio。

服务器启动时使用已安装的最新版本，自身不安装更新；后台服务安装的更新在编辑器下次启动服务器时生效。直接从原生压缩包启动时，始终运行该压缩包的版本。

系统要求

Linux 上解码 GBK 源码需要系统 iconv 的 GBK 模块；EL8/EL9 最小安装与容器镜像需另行安装：dnf install glibc-gconv-extra。缺少时 UTF-8 项目不受影响，codeoutline doctor 会给出提示。

支持的语言

C、C++、C#、Go、Java、JavaScript / TypeScript（含 JSX/TSX）、ArkTS（.ets）、Kotlin（.kt / .kts）、Lua、Python、Rust。

调用关系、导航与补全共用查询期接收者入口，由各语言提供绑定和成员查找规则。 支持 Lua 方法接收者、Python 参数及重新赋值、JS/TS/ArkTS 箭头函数的词法 this 与普通函数的动态 this、Kotlin 扩展和作用域接收者、Rust self/Self，并复用 C/C++、C#、Java 和 Go 的声明类型解析。普通变量即使命名为 self 或 cls， 也按其声明类型处理。详细绑定仅保留在有容量限制、经源码校验的内存缓存中； 未知接收者不会退回同名方法猜测。运行时修改成员、任意动态调用和无法证明的泛型约束 仍超出静态分析范围。

ArkTS 复用 JS/TS 解析器，将组件 struct 按类索引，支持带装饰器的字段、方法、 本地模块导入和 ArkUI 调用；声明式 UI 块不会被当作方法声明。 这是启发式索引，不执行 ArkTS 类型检查；尚不解析 SDK @kit.*/@ohos.*、资源引用， 也不模拟生成的 UI 生命周期或状态行为。Zed 需要另外安装 ArkTS 语言扩展。

Kotlin 支持声明、主构造器属性、扩展函数、表达式函数体、包导入与别名，以及普通、泛型和尾随 lambda 调用。 关系解析仍是启发式的；不建模编译器生成成员、lambda 隐式接收者、字符串模板内的表达式、Java 互操作或协程/框架分派。

C++ 支持具名类型别名、命名空间别名、using ns::Type、using ns::function，以及所包含头文件中有界的 using namespace 导入链。调用关系、导航和补全共用解析；局部导入遵循声明位置和块作用域， 有歧义的导入名称保留为未解析。详细导入证据按需生成，不写入索引。 这仍是启发式解析，不建模预处理与 include 顺序、编译器头文件搜索配置、依赖模板、ADL 或完整重载决议。

C#、Java、Kotlin 的实现关系依据显式继承和匹配的具名参数类型生成。Explore 与 callers 将这类边标为 implementation，表示可能的实现，不表示该方法调用了实现方法，也不证明运行时接收者的类型。 “转到实现”共用这套解析，“转到定义”仍返回声明。详细方法证据按查询生成，不写入索引； 候选、结果或继承层次达到限制时会报告结果不完整。暂不处理泛型替换、仅由继承成员满足的接口实现、 默认接口实现冲突。C++ 虚方法的支持范围见英文 README。

TypeScript 接口和显式抽象方法复用同一套有界查询，只关联顶层具名类型之间显式的 implements / extends。导入别名、默认导入、命名空间导入、重导出、workspace 包和 tsconfig 路径复用现有模块定位；参数及返回类型须显式标注，解析后完全一致，支持简单数组， 具名类型按声明模块区分。暂不处理泛型继承或方法、类型别名、联合类型、可选/剩余/默认参数、 访问器、箭头函数字段、声明合并、嵌套类型、返回类型推断和结构化实现。类的普通重载声明不作为 抽象契约；这不是 TypeScript 可赋值性检查。证据按查询生成，索引不保存额外实现关系。

JS/TS 还可无需配置地识别有限的 Node EventEmitter 模式：显式导入内置构造器、当前文件的 未导出 const 实例、字面量事件名和具名处理器。Explore/callers 用 automatic:event 标注可能的 事件投递，按实例隔离；遇到对象转交、重赋值、移除监听器、未知作用域或动态事件名时保守跳过。 详细证据只在查询时生成，不写入索引。支持范围、数量限制及排除情况见 间接调用文档。

Lua 还可自动关联本文件 local 回调数组：由具名局部函数、字面量数组或 table.insert 注册， 再在内置 pairs / ipairs 循环中直接调用值变量。Explore/callers 用 automatic:callback-loop 标注可能调用，复用静态注册表的作用域和别名解析；遇到集合转交、 修改、未知来源或作用域不确定时保守跳过。详细证据按查询生成，不新增持久化索引字段。 支持范围和限制见间接调用文档。

命令行

codeoutline serve --stdio [--project PATH] [--allow-root PATH ...]
codeoutline serve --http [--host HOST] [--port PORT] [--project PATH] [--allow-root PATH ...]
codeoutline lsp --stdio [--project PATH]
codeoutline explore --project PATH --query QUERY [--budget BYTES]
codeoutline status [--project PATH]
codeoutline rebuild [--project PATH]
codeoutline doctor [--project PATH]

status、rebuild、doctor 输出 JSON；诊断失败返回非零退出码。一次性命令的项目默认为当前目录。lsp --stdio 由编辑器启动，通过 stdin/stdout 收发 LSP 消息，不是交互式命令；工作区由编辑器提供，编辑器未提供时才使用 --project。

运行时只把警告和错误输出到 stderr，不写日志文件，在项目中启动不会留下任何文件。排查问题时可设置 CODEOUTLINE_LOG_LEVEL（DEBUG、INFO、WARN、ERROR 等）调整级别，设置 CODEOUTLINE_LOG_DIR 将日志文件写到该目录。

MCP 服务细节

协议基线为 MCP 2025-06-18。查询预算为 256–262144 字节，默认 16000；超限输出保持 UTF-8 有效并附截断提示。路径均指服务所在机器。

stdio 模式下 stdout 只输出 MCP 消息，日志写入 stderr。HTTP 默认只监听本机，客户端地址为 http://127.0.0.1:19876/mcp。远程监听需设置至少 16 字节的 CODEOUTLINE_TOKEN 并用 --allow-host 显式允许主机，客户端使用 Authorization: Bearer ...；与本机 HTTP 不同，远程服务未传 --allow-root 时只允许访问 --project 或启动目录；--allow-origin 可重复指定允许的完整 Origin，未配置的浏览器 Origin 被拒绝。远程部署应由 TLS 反向代理保护令牌。

主线程处理协议，常驻索引线程串行处理查询。请求含进度 token 时每秒报告进度，HTTP 使用 SSE；没有独立的 GET/SSE 订阅端点（返回 405）。最多 64 个会话、64 个排队或执行中的任务；任务期限 120 秒，会话空闲 15 分钟过期。取消在显式检查点生效，单个文件的原生解析期间无法中断（单文件上限 1.5 MB）。更新被取消时回滚至上一份完整的内存索引；取消只读查询不会丢弃索引。

索引行为与限制

全量扫描有至少 32 个文件需要读取时，服务按需启动解析线程，由索引线程统一提交结果。Windows 默认使用 8 个解析线程，其他平台使用 6 个；可通过 CODEOUTLINE_INDEX_THREADS 覆盖，设为 0 禁用。线程复用至所有在途批次返回，空闲 60 秒后关闭，下次需要时重新创建。

缓存位于用户目录 .codeoutline/cache/<路径 SHA-256>.idx，带完整性校验，损坏后自动重建；每次写入独立临时文件再原子替换，失败时保留旧文件。默认最多驻留 8 个项目，空闲 15 分钟淘汰。服务使用真实绝对路径统一目录别名与链接，Windows 上忽略 ASCII 大小写。

进行隔离缓存或内存实验时，可将 CODEOUTLINE_MEMORY_CACHE 设为缓存文件路径。 非空值优先于嵌入 API 的 cache_path 和默认路径；空值或未设置时沿用正常路径选择。 它为该进程的所有项目指定同一个文件，因此只适用于单项目运行，不适用于共享多项目服务。 缓存仍会校验源项目并使用原子写入。

源码编码按需确认：首次索引不逐个检查编码，查询涉及文件时才确认，UTF-8（含 BOM）优先，失败后严格转码 GBK，重新解析并更新该文件的符号后再执行本次查询，不修改原文件。编码结果随缓存保存，文件改变后失效；无法解码的命中文件会明确报错。两种编码都合法时默认 UTF-8。未被查询过的 GBK 文件仍可能有误解析，中文标识符可能漏匹配；用文件名查询可触发该文件的修正。

优先用 ripgrep（rg）枚举文件并遵守各级 .gitignore；未安装 rg 时改用目录遍历，只支持根目录 .gitignore 的常见规则（不支持否定规则与嵌套忽略文件），并跳过隐藏目录、node_modules、__pycache__ 与符号链接。项目根路径不能包含 "、%、!、$、反引号、反斜杠或换行。

从源码构建

运行时来自 xnet2lua 子模块：

git submodule update --init --recursive

构建脚本编译 LuaJIT 运行时（开启 xproc、MPSCQ 与 HTTPS），复制到仓库根目录的 bin/。Windows 在 MSVC 开发者终端执行，产物静态链接 CRT；macOS 生成最低支持 macOS 11 的通用程序。

.\tools\build-runtime.ps1

sh tools/build-runtime.sh

从源码运行时需显式带 LOG_STDERR=1，安装后的 codeoutline 会自动添加：

.\bin\xnet.exe scripts/codeoutline/command.lua LOG_STDERR=1 serve --stdio --project C:/src/project

测试：

.\bin\xnet.exe tests/lua/codeoutline_spec.lua
.\bin\xnet.exe tests/lua/stability_spec.lua
.\bin\xnet.exe tests/lua/parse_pool_spec.lua
.\bin\xnet.exe tests/lua/lsp_spec.lua
npm ci
npm test
npm run test:package

npm test 使用官方 MCP SDK 验证 stdio 与 HTTP 两种传输；npm run test:package 生成真实安装包并在仓库外安装验证。设置 XSCAN_PURE_LUA=1 可验证纯 Lua 扫描器路径。打包与发布流程见 分发说明。

嵌入调用

package.path = 'scripts/?.lua;' .. package.path
local service = require('codeoutline.service')
local text, info = service.explore('C:/src/project', 'Session.save', { budget = 16000 })

get、explore、status 自动刷新；forget 只清除内存索引，rebuild 绕过磁盘缓存完整重建；service.configure 可调整驻留项目数与空闲时间。嵌入 Android 时，宿主须在启动工作线程前调用一次 xutils_android_init(JavaVM*)，否则 GBK 转换会明确报错。

来源与许可

代码提取自 Codua，命名空间为 codeoutline.*。项目采用 BSD-2-Clause，第三方依赖声明见 第三方说明。