面向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 text | 人类可读、有装饰 | 空白缩进、彩色符号全是"无效 token" |
--format json | 结构完备、可解析 | 括号、引号、键名重复，开销巨大 |
--format llm | 极简、省 token | 不适合人类阅读（本来就是给模型看的） |
在树形和表格类输出上，--format llm比json平均减少 2-4 倍字节。这意味着同样的上下文窗口，AI 能读到 4 倍的信息量。😎
Ix llm格式的三大设计原则
这套格式的完整规范写在 docs/llm-format.md，核心设计只有三条：
- 一行一条记录：换行分隔，绝不嵌套，天然抗截断
key=value扁平键值：标量用空格分隔，表格行用"记录类型 + 键值对"- 丢掉所有装饰：没有表头、没有分隔线、没有缩进
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=872. 空值直接省略
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 格式
- 安装 Ix：按官方脚本安装 CLI，仓库内置安装脚本在 scripts/install/（支持 sh、ps1、cmd）
- 构建图谱：进入项目目录运行
ix map . - 给 AI 插件配置格式：在 Claude、Cursor 等工具的 Ix 插件配置中指定
--format llm，或在命令末尾直接追加 - 开始提问：
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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
