面向AI的极简输出协议：Ix --format llm格式深度解析

面向AI的极简输出协议：Ix --format llm格式深度解析

【免费下载链接】IxUnderstand any codebase instantly. System intelligence for codebases, built for humans and AI.项目地址: https://gitcode.com/gh_mirrors/ix8/Ix

Ix 是一款面向代码库的"系统智能"命令行工具：它用 tree-sitter 解析 26 种语言，把整个仓库构建成可查询的符号图谱，让开发者与 AI 助手都能瞬间理解任何代码库。而--format llm正是 Ix 专为 AI 编程助手（Claude、Cursor、Codex 等）设计的极简输出协议——它把每次查询结果压缩成一行一记录的紧凑格式，通常比 JSON 输出节省2-4 倍 token。本文带你深度解析这套协议的设计思想、语法规则与实战用法。

为什么 AI 编程助手需要一套专门的输出格式？

AI 助手在一次会话中会调用ix几十上百次，每次返回的文本都要计入上下文窗口。传统的两种格式各有短板：

在树形和表格类输出上，--format llm比json平均减少 2-4 倍字节。这意味着同样的上下文窗口，AI 能读到 4 倍的信息量。😎

Ix llm格式的三大设计原则

这套格式的完整规范写在 docs/llm-format.md，核心设计只有三条：

1. 一行一条记录：换行分隔，绝不嵌套，天然抗截断
2. key=value扁平键值：标量用空格分隔，表格行用"记录类型 + 键值对"
3. 丢掉所有装饰：没有表头、没有分隔线、没有缩进

llm输出格式语法规则详解

1. 标量与记录行

标量就是空格分隔的key=value对，比如ix stats的输出：

nodes total=98979 method=49180 module=38199 class=6833 file=3285

表格类输出前面会加一个"记录类型"标记，比如ix subsystems --list：

region id=cli-client label="Cli / Client" kind=subsystem level=2 files=87

2. 空值直接省略

null、undefined和空字符串一律不输出——"没有的东西就不占 token"。0 和默认值如果没有信息量也会被丢弃。

3. 值含特殊字符时自动加引号

一旦值里出现空格、=、"、\或控制字符，就用双引号包裹，内部转义\n、\r、\t。这保证了一条记录永远不会跨行，消费端可以放心按行切分。

4. 错误也是统一格式

出错时输出一行error记录，进程仍以非零码退出：

error code=unknown_target message="No entity named 'IngestionService' found"

AI 助手解析这一行就能判断失败原因，无需读取 stderr。

树形数据如何用一行行记录表达？

层级结构（比如ix map的 region 树）会被拍平成扁平记录，用显式的parent=<id>字段表达父子关系：

region id=root kind=system label="Cli" region id=cli kind=subsystem label="Client" parent=root region id=srv kind=subsystem label="Server" parent=root

消费端只凭id和parent=就能重建整棵树。这个设计妙在两点：保持"无缩进"不变量，而且即使输出被管道截断，每一条记录依然独立成立。💡

实战：explain 命令的 llm 格式输出

explain是 AI 插件调用最频繁的命令，它的 prose 渲染（解释、上下文、重要性）是最耗 token 的部分。Ix 的做法是：prose 本来就是"事实的渲染"，直接输出事实本身，让模型自己总结。

entity id=verify_token name=verify_token kind=function path=src/auth.ts rev=3 role role=validator confidence=0.92 importance level=high category=boundary edges callers=14 callees=3 dependents=5 importers=2 members=0 downstream=9 depth=3 history=12

对比原来的散文式输出，这套记录大约缩小55%。实现代码见 ix-cli/src/cli/explain/llm.ts。

llm格式的设计例外：read 与 status

设计者留下了两个"故意不遵守规则"的例外，非常值得玩味：

• read的正文不是记录：AI 要源码就要逐字节的源码，所以正文原样输出，前面加一行content lines=<n>让数据块自定界——这是唯一放宽"一行一记录"的地方。
• status并不更小：它只有几个标量，大小和 JSON 差不多。但它提供了显式的stale=true|false字段，这正是 AI 最想知道的问题答案。

哪些命令支持 --format llm？

所有接受--format的命令都接受llm，共分五个层级逐步覆盖：

• Tier 1：map、subsystems、impact、smells、overview、stats
• Tier 2：inventory、rank、depends、trace、contains、callers、callees、imports、imported-by
• Tier 3：search、text、history、patches
• Tier 4：entity、locate、diff、conflicts
• Tier 5：explain、read、status、doctor、savings

没有专属渲染器的命令会自动路由到最紧凑的既有格式（通常是text），所以消费端可以无条件传--format llm，无需逐命令查表。所有渲染逻辑集中在 ix-cli/src/cli/llm.ts。

快速上手：让 AI 助手用上 llm 格式

1. 安装 Ix：按官方脚本安装 CLI，仓库内置安装脚本在 scripts/install/（支持 sh、ps1、cmd）
2. 构建图谱：进入项目目录运行ix map .
3. 给 AI 插件配置格式：在 Claude、Cursor 等工具的 Ix 插件配置中指定--format llm，或在命令末尾直接追加
4. 开始提问：ix impact verify_token --format llm、ix callers parseFile --format llm

总结

--format llm是 Ix 送给 AI 编程生态的一份"极简礼物"：它不追求面面俱到，而是精准回答一个问题——如何用最少的 token 传递最完整的结构信息。对于正在搭建 AI 编码工作流的开发者，这套协议值得直接借鉴；对于普通用户，只要记住一句话：想让 AI 助手更省钱更聪明，就在 Ix 命令后面加上--format llm。🚀

【免费下载链接】IxUnderstand any codebase instantly. System intelligence for codebases, built for humans and AI.项目地址: https://gitcode.com/gh_mirrors/ix8/Ix