Docs

文档

安装 快速开始 客户端接入 命令行 环境变量 工具参考 路由地图 语言支持 安全机制 自检 FAQ 更多资源

安装

两条路径功能完全一致，仅索引后端实现不同。要求 Node >= 20。

标准安装（推荐 · better-sqlite3 完整后端）
git clone <repo> liuhe && cd liuhe/malong && npm ci && node mcp-server.js --workspace .
免构建部署（离线 / 沙盒 · sql.js 后端）
tar -xzf malong-liuhe-0.4.5-linux-x86_64.tar.gz && cd malong && node mcp-server.js --workspace .

tar 包启动时会打印 SQLITE BACKEND 升级提示；有网环境 cd malong && npm ci 即可升级为完整版。

解析守护进程（malong-parse）

两种安装方式都内置 Rust 解析二进制，MCP 服务器启动时自动拉起，无需手动启动。
Linux / macOS 通过 Unix socket（默认 /tmp/malong-parse-$(id -u).sock）通信；Windows 走 TCP 127.0.0.1:31001，服务器会自动拉起 malong-parse.exe。
路径与二进制可用 MALONG_SOCKET / MALONG_PORT / MALONG_PARSE_BIN 覆盖（见环境变量）。

快速开始

01
获取工具集
clone 仓库进入 malong/ 后 npm ci；或解压平台 tar 包。
02
注册 MCP 客户端
opencode / Claude Desktop / Claude Code / codex 任选其一，见客户端接入。
03
建立索引
每个工作区先跑一次 reindex（可 blocking=true），符号搜索与影响分析才有索引可查。
04
直接提问
例如："search for the symbol 'handle' in my workspace"
典型工作流 · 从搜索到安全修改
reindex→ symbol_search→ impact_analysis→ edit_transaction→ test_bridge→ verify_pipeline

建索引 → 定位目标符号 → 评估爆炸半径 → 事务化修改（可回滚）→ 跑测试 → lint/typecheck 收尾。

客户端接入

MCP 层是标准 JSON-RPC over stdio，任何 MCP 客户端均可接入。以下均为已实测配置。

opencode（项目根 opencode.json）
opencode.json
{ "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "malong": {
      "type": "local",
      "command": ["node", "--max-old-space-size=512", "malong/mcp-server.js", "--workspace", "."],
      "enabled": true
    }
  }
}
Claude Desktop（Windows 已实测：%APPDATA%\Claude\claude_desktop_config.json）
claude_desktop_config.json
{ "mcpServers": {
    "malong": { "command": "node", "args": ["/path/to/malong/mcp-server.js"] }
  }
}
Claude Code（命令行注册，工具暴露为 mcp__liuhe__<tool>）
claude mcp add
claude mcp add liuhe -- node /path/to/malong/mcp-server.js --workspace /path/to/project
claude mcp list        # → "liuhe … ✔ Connected"

# 无头调用示例
claude -p "index the workspace with reindex, then find createDb with symbol_search" \
  --allowedTools "mcp__liuhe__reindex" "mcp__liuhe__symbol_search"
codex（~/.codex/config.toml，工具暴露为 liuhe.<tool>）
config.toml
model = "deepseek-v4-flash"
model_provider = "opencode-zen"

[model_providers.opencode-zen]
name = "OpenCode Zen"
base_url = "https://opencode.ai/zen/go/v1"   # 任意 OpenAI 兼容端点
wire_api = "chat"
env_key = "OPENCODE_ZEN_API_KEY"             # codex 从该环境变量读密钥

[mcp_servers.liuhe]
command = "node"
args = ["/path/to/malong/mcp-server.js", "--workspace", "/path/to/project"]

版本注意：新版 codex 强制 OpenAI Responses API，需使用仍支持 wire_api = "chat" 的版本（已实测 0.50.0）。

DeepSeek Harness（dsh web）— 可选便利项
bash malong/dsh/install-dsh.sh
bash malong/dsh/install-dsh.sh        # 幂等；编辑 ~/.dsh/profiles/web/cordis.patch.yml 并自动备份
pkill -f "dsh web"; dsh web --port 3456 --host 0.0.0.0 --trusted-host <LAN IP>

桥接插件把全部 38 个工具注册为 malong__<tool>，并自动从当前会话工作区填充 workspace_dir（显式路径仍然优先）。完整指南（含索引规则）：malong/dsh/DSH接入说明.md

命令行参数

参数 说明
--workspace <dir>索引与操作的工作区根目录
--concurrency <n>并行任务数
--max-old-space-size=<MB>V8 堆上限，建议 512；未设置且堆无上限时启动会打印警告
--expose-gc启用周期 GC + 内存监控（配合 health / gc 工具）

环境变量

全部可选，未设置时使用默认值。

变量 默认 说明
MALONG_STATE_DIR~/.config/malong使用/反馈/编辑统计写入目录；测试与沙箱环境可重定向
MALONG_SOCKET/tmp/malong-parse-$(id -u).sock解析守护进程 Unix socket 路径（Linux / macOS）
MALONG_PORT31001解析守护进程 TCP 端口（Windows）
MALONG_PARSE_BIN内置 / PATH自动拉起守护进程时使用的二进制
MALONG_PARSE_MODErust-service解析传输方式，当前版本仅支持 rust-service
MALONG_WS_GC_DAYS14health cleanup 修剪闲置工作区缓存的天数阈值；0 禁用

44 个 MCP 工具

全部工具纯正则 / AST 实现，零 LLM 调用，可复现、可审计、可 CI。点击分组展开工具说明。

I/O 原语 ×3 索引与搜索 ×5 分析理解 ×8 编辑与重构 ×7 质量与安全 ×8 工程与验证 ×8 依赖与系统 ×5
I/O 原语 3 ▸
read_symbol读取符号体与版本信息，写前必读的基准锚点
write_symbol受保护的符号级写入：版本 / 锁 / 冲突检测，防陈旧覆盖
write_symbols批量跨文件写入，全有或全无，死锁安全
索引与搜索 5 ▸
reindex全工作区符号索引，接入后每个工作区第一步必跑
symbol_search按符号名子串查找定义（含全限定路径）
code_search自然语言意图搜索代码，确定性实现零 LLM
repo_map文件 ↔ 符号项目地图，适合 100+ 文件代码库
outline_reader文件结构大纲（函数 / 类 / 签名），无需读全文
分析理解 8 ▸
impact_analysis修改 / 重命名前评估爆炸半径与调用者范围
call_chain定位到具体行，查看该行的调用者 / 被调者链
references符号跨文件引用清单与使用计数
dep_graph文件导入依赖图与循环依赖检测
inspect大纲 + 引用 + 调用链一次拿全，替代三次单独调用
trace_symbol常量值追踪 + 硬编码副本查找
active_todosTODO / FIXME 扫描并按当前工作优先级排序
code_quality技术债 / 架构 / 爆炸半径五维形状探针
编辑与重构 7 ▸
batch_edit单文件多处编辑原子应用，支持 dry-run 预览
edit_transaction多文件编辑事务：begin → edit → commit，可回滚 / 撤销
edit_collision_guard读后改前快照对比，检测外部并发编辑冲突
git_worktree隔离 git 分支批量改动，零工作区污染，失败自动回滚
rename_symbol跨文件符号重命名（词边界、字符串 / 注释感知）
fix_imports清理未用导入、补未定义符号、破除循环依赖
edit_sandbox编辑前预校验（语法 / 结构 dry-run）
质量与安全 8 ▸
code_review形状级代码检查：命名 / 注释 / 长函数 / 重复块
security_review注入 / XSS / 密钥 / CORS 模式扫描，严重度分级
dead_code_sweeper死代码检测：未用导入 / 孤儿文件（宁可漏删不误删）
guard_patternsAST 规则门禁：禁裸 except / debugger / eval
exception_guard检查项目使用自定义异常而非内建，配 test_bridge 修复验证
config_drift环境变量 / 数据表 / 服务与 .env.example 漂移检测
mock_syncer签名变更后的 mock / patch 失配检测
naming_consistency新符号命名与项目风格一致性校验
工程与验证 8 ▸
test_bridge运行测试并解析输出，失败附上下文增强
verify_pipeline按 package.json 一键跑 lint / test / typecheck
debug_runner跑命令 / 脚本，14 类错误模式自动分析
patch_parserSEARCH/REPLACE 补丁解析与 dry-run 预演
diff_facts编辑事务后的 AST 符号变更事实 + 测试同步提示
find_tests源文件反查测试（命名 + 导入双向查找）
spec_gen从源文件符号生成模块 / API 规格文档
style_sniffer嗅探项目代码风格，产出规范文档
依赖与系统 5 ▸
dependency_gatekeeper导入 vs 清单比对，未声明依赖 + 安装提示
tsc_checkTypeScript 类型检查（tsc --noEmit）
health系统检查与自愈（DB 完整性 / 内存 / 信号量）
gc手动触发 GC（需 --expose-gc 启动）
feedback工具问题 / 建议本地收集上报

工具路由地图

44 个工具拆成 4 份时序图——每一条 ok/err 去向都已画入（绿实线 = 成功，红虚线 = 出错）；虚线卡片 = 目标工具在另一份图里；粗绿线为主链。编辑→测试闭环（edit_transaction ↔ diff_facts ↔ test_bridge ↔ debug_runner）完整位于 2/4。

1/4 索引、读取与影响 2/4 编辑、提交与测试闭环 3/4 审核、验证与运维 4/4 清洁与整理

图例

── ok = ok（绿实线）= 成功 → 下一步去向（每条边来自 handler 实测 next_step）
╌╌ err = err（红虚线）= 出错 → 处理去向
粗绿线 = 层间主链

节点编号对照（T01–T44） (44)

T01 reindex
reindex
完成 → read_symbol / symbol_search / references
完成 → health(check) 自检
T02 active
active_todos
有高优 → 处理当前文件 TODO
T03 ss
symbol_search
命中 → impact_analysis
空结果 → reindex / glob
T04 cs
code_search
命中 → read_symbol / references
T05 ft
find_tests
找到 → test_bridge(scope)
无 → 新建测试
T06 rs
read_symbol
完成 → impact_analysis → edit_batch
改后 → test_bridge
T07 insp
inspect
完成 → impact_analysis
改后 → test_bridge
T08 ol
outline_reader
完成 → impact_analysis
T09 cc
call_chain
完成 → impact_analysis（完整半径）
T10 refs
references
完成 → find_tests（测试引用）
T11 tr
trace_symbol
有硬编码副本 → rename_symbol
T12 dg
dep_graph
有环 → fix_imports
完成 → impact_analysis
T13 repo_map
只读概览
T14 patch_parser
只读解析预览
T15 ia
impact_analysis
高危 → sandbox_validate
中危 → 审查 callers
完成 → 修改 · 改后 → test_bridge
T16 ecg
edit_collision_guard
安全 → edit_transaction / edit_batch
外部改动 → 重读 → record_read
T17 et
edit_transaction
提交 → diff_facts → test_bridge
失败 → debug_runner
T18 eb
edit_batch
完成 → test_bridge → debug_runner
经事务 → diff_facts · TS → tsc_check
T19 ws
write_symbol
完成 → test_bridge → debug_runner
经事务 → diff_facts
T20 wss
write_symbols
完成 → test_bridge → debug_runner
经事务 → diff_facts
T21 rn
rename_symbol
dry_run → 正式改名
完成 → test_bridge
T22 sv
sandbox_validate
通过 → edit_transaction
报错 → 修复 → 重新校验
T23 gw
git_worktree
提交 → revert / reset（撤销）
T24 ms
mock_syncer
失配 → 修复 → test_bridge
同步 → test_bridge
T25 df
diff_facts
陈旧测试 → test_bridge(scope)
caller 未同步 → impact_analysis
完成 → 无同步问题
T26 tb
test_bridge
超时 → 加大 timeout / inspect
失败 → debug_runner / verify_pipeline
全绿 → edit_transaction 提交
T27 dr
debug_runner
有错 → suggested_action（14 类）
成功 → 继续
T28 tc
tsc_check
有错 → 修复类型错误
通过 → 继续
T29 vp
verify_pipeline
超预算 → 单阶段 lint
或 test_bridge 分批
T30 cr
code_review
告警 → code_quality 深探
修复后 → test_bridge
T31 cq
code_quality
5 维形状分 → 人工确认
T32 sr
security_review
高危 → 修复注入 / 密钥
干净 → 非保证声明
T33 eg
exception_guard
问题 → edit_transaction → test_bridge
测试文件 → 跳过
T34 gp
guard_patterns
违规 → 修复 → 重跑
T35 nc
naming_consistency
问题 → edit_transaction
T36 fi
fix_imports
有误 → edit_transaction → test_bridge
干净 → sweep_dead_code
T37 sdc
sweep_dead_code
死代码 → edit_transaction
unused_guard → 人工 trace
T38 cd
config_drift
漂移 → edit_transaction → 重跑
完成 → 同步
T39 dk
dependency_gatekeeper
缺依赖 → 补 manifest → 重跑
T40 sg
spec_gen
完成 → read_symbol 逐导出
T41 st
style_sniffer
完成 → 审查规则 → 提交
T42 fb
feedback
有反馈 → 修复
完成 → health(stats) 用量
T43 hth
health
未登记 → 注册 Y004 矩阵
重启 → MCP host · 清理 → 重跑
T44 gcc
gc
内存回收（无 next_step）

语言支持

符号级读写（read / write_symbol）支持 10 种语言族，写后自动语法自检（node --check / py_compile）。

JavaScript (.js/.mjs/.cjs/.jsx) TypeScript (.ts) MTS / CTS (.mts/.cts) TSX Python Go Rust (impl/trait/enum) C / C++（含头文件） Java Bash

安全机制

行内抑制 malong-ignore
行尾追加 malong-ignore 抑制该行全部发现；malong-ignore[eval,exec-cmd] 指定规则；建议附原因。
声明式配置 .ai-patterns.json
在 securityIgnore 数组按 files / rules 声明式忽略（* / ** glob 均支持）；注入类规则（eval / exec / SQL / spawn）只能显式标记，绝无启发式自动抑制，被抑制项仍计入 suppressed 字段不消失。
撤销日志 .malong/journal/
每次安全写入（write_symbol / write_symbols / batch_edit）都在工作区 .malong/journal/ 留下回滚日志；已终止事务按 24h TTL 自动清理（每小时最多扫一次），进行中 / 待人工审查（needs_review）的日志永不删除；只清理工具自身的回滚备份，从不触碰源码。

自检

一键全链（需守护进程运行）
./scripts/ci.sh # cargo test + npm test + dogfood
npm test # 2013 断言 / 81 个测试文件
node tests/test-db-adapter.js # 22 断言：sql.js 后端 + 持久化
node tests/test-mcp-server.js # 25 断言：MCP stdio + 守护进程往返
cd malong-parse && cargo test # 92 断言：多语言提取 / 协议 / 缓存 / 调度

FAQ

MCP 服务器如何启动解析服务？
npm ci 或 tar 包均内置 Rust 解析二进制（malong-parse），服务器启动时自动拉起；解析崩溃由 catch_unwind 隔离，不影响 MCP 进程。
索引存哪里？
每个 workspace 独立 SQLite 文件（WAL 模式），位于 workspace 的 .malong/ 目录（gitignore 已排除）。损坏时 integrity_check 自动自愈重建。
哪些语言支持符号级写入？
read / write_symbol 支持 JS / TS / TSX / Python / Go / Rust / C-C++ / Java / Bash 共 10 种语言族；写后自动 node --check / py_compile 语法自检。
质量门禁工具会不会调用 LLM？
不会。全部质量 / 安全工具是纯正则 / AST 确定性实现，同一输入必然同一输出，可复现、可 CI、可审计。
解析守护进程没启动会怎样？
解析依赖类工具（symbol 提取等）降级；SQLite 系工具（repo-map / code-index / health-check）仍正常工作。MCP 服务器默认会自动拉起守护进程，仅在手工直连 API 时才需要手动启动。
Windows 上路径怎么写？
JSON 配置中反斜杠需转义为 \\；相对路径相对客户端启动目录解析，建议传绝对路径；tar -xzf 在 Win10+ 可直接使用。
两种 SQL 后端数据兼容吗？
兼容。better-sqlite3 与 sql.js 后端同为 SQLite，索引数据文件完全互通，可随时切换。
编辑可以撤销吗？
每次安全写入都在 .malong/journal/ 留回滚日志；已终止事务按 24h TTL 自动清理，进行中 / 待审查日志永不删除；只清理工具自身的备份，不碰源码。

更多资源

README（中英） 更新日志 贡献指南 安全说明 GitHub 仓库 第三方声明