AOS CLI

AOS（ASDM Ontology Service）是 ASDM（AI-First System Development Methodology）的代码本体分析组件。

企业私有化部署场景下，大模型能力受限（上下文窗口小、token/s 低），直接扫描大型代码库会导致响应极慢且分析质量严重下降。AOS 通过预构建语义层，将"逐文件扫描 + LLM 推理"降级为"毫秒级查询"，在企业级超大型代码项目中保障 AI agent 的响应速度和分析准确度。

0.0.11 版本亮点

0.0.11 打通"代码 ↔ 数据库"：AI agent 现在可以一条指令追踪从 Controller 方法到数据库表列的完整全栈链路（此前链路在 Mapper 层断裂，数据库完全不可见）。

• 数据库 DDL 解析：.sql 文件中的表/列/主键/外键/中文注释解析为 Table 对象
• 外键关系图谱：fkReferences 链接 + fkDetails 明细，支撑"删表影响分析"等跨表场景
• MyBatis Mapper XML 解析：namespace / resultMap / 动态 SQL 表名引用 / 嵌套映射
• Mapper 对象与双链接：mapperMapsTable / mapperMapsEntity 关联数据访问层与表、POJO
• MyBatis POJO 识别：无 @Entity 注解的 POJO 也被标记为数据模型（MyBatis POJO）
• JPA 注解参数提取：@Table(name) / @Column(name) 建立 JPA 实体 ↔ 表/列映射
• DDL ↔ 代码融合：审计字段补全 + 类型冲突（以 DDL 为准）与 FK 冲突（以 JPA 为准）记录
• 零影响：无 DDL / MyBatis 的项目，构建结果与 0.0.10 完全一致

这是什么

AOS 是面向企业级超大型代码项目的语义层。它将 Java 仓库的全量源码、编译产物、数据库 DDL 与 MyBatis Mapper XML 预先分析为结构化本体快照，把"代码文件"转化为 AI agent 可直接查询的"关系图谱"——包含包、类、接口、方法、依赖、数据库表、MyBatis Mapper 和 10 种链接关系。

核心价值：大幅提升 AI coding agent 在超大型工程项目上的语义理解效率和准确度。

为什么 AI agent 需要语义层

AI coding agent 直接读源码时，本质上是在做"文本理解"——它能读懂单个文件的逻辑，但无法可靠地回答跨文件的关系型问题：

• "修改这个方法会影响哪些代码？" → 需要反向调用链，agent 逐文件追踪会遗漏
• "这个接口有哪些实现类？" → 需要继承关系图，agent 文本搜索会漏匹配
• "这个方法调用了哪些 Spring 框架方法？" → 框架源码不在仓库中，agent 看不到

AOS 语义层将这些关系预计算并索引，agent 一次查询即可获得 100% 准确的结果，从"猜测"变为"查询"。

准确度问题的严重性

在企业级项目中，AI agent 的不准确回答不仅是效率问题，更是安全问题：

| 场景 | AI agent 直接读源码的风险 | AOS 语义层的保障 | |---|---|---| | 变更影响分析 | 遗漏 50% 调用者 → 未覆盖的代码路径可能引发线上故障 | 反向调用链 100% 完整，零遗漏 | | 架构理解 | 文本搜索匹配注释和字符串 → 75% 噪音 → 误导决策 | 精确的结构化关系，零噪音 | | 框架调用追踪 | Spring/MyBatis 调用不可见 → 影响范围评估不完整 | 编译产物分析还原全部框架调用 | | 代码 Review | 遗漏 package 可见性方法 → Review 不完整 | 完整方法清单，零遗漏 |

一句话定位：AOS 是企业级代码项目的"语义索引层"，让 AI agent 从"读文件猜关系"升级为"查图谱得结论"。

为什么需要 AOS

大型代码库中，AI coding agent 面临三个硬约束，AOS 专为绕过这些约束而设计。

1. 上下文窗口有限：大仓库塞不进 LLM

LLM 的上下文窗口有物理上限，而 Java 仓库的源码体积随规模线性增长：

| 仓库规模 | 代码文件数 | 代码行数 | 全量源码 | 能否塞入主流 LLM 上下文 | |---|---|---|---|---| | 小型 | ~50 | ~1 万行 | ~200KB | ✅ 可以 | | 中型 | ~500 | ~8 万行 | ~3MB | ❌ 超 4 倍 | | 大型 | ~5,000 | ~80 万行 | ~32MB | ❌ 超 40 倍 | | 超大型 | ~10,000 | ~160 万行 | ~64MB | ❌ 超 80 倍 | | 企业级 | ~50,000 | ~800 万行 | ~320MB | ❌ 超 400 倍 |

业务影响：当仓库超过 500 个文件时，AI agent 无法在一次对话中理解项目全貌。开发者问"这个模块怎么工作"，agent 只能盲人摸象——读到哪个文件就理解哪个，无法建立全局视角。

AOS 的价值：预构建快照后，agent 每次查询只返回相关片段（~2KB），而非全量源码（~200KB）。agent 可以在有限的上下文窗口内，精准获取回答问题所需的结构信息。

2. 全量扫描太慢：私有化部署下能力受限，问题极度恶化

AI agent 每次回答代码结构问题都需要扫描文件，耗时随仓库规模线性增长。在公有云大模型场景下这已是瓶颈，在企业私有化部署场景下问题会极度恶化：

公有云 vs 私有化部署的能力差距

| 能力维度 | 公有云大模型（GPT-4 / Claude 3.5） | 企业私有化部署（典型 7B-14B 模型） | |---|---|---| | 上下文窗口 | 128K-200K token（~500KB-800KB） | 8K-32K token（~30KB-120KB） | | 推理速度 | 50-100 token/s | 5-20 token/s（受 GPU 资源限制） | | 单次可读源码量 | ~500KB（约 500 文件） | ~30KB（约 30 文件） | | 万级文件扫描后的分析质量 | 降级（上下文溢出截断） | 严重降级（30 文件即占满上下文，超出部分完全丢失） |

私有化部署下的查询耗时（推导）

| 查询方式 | 500 文件 | 5,000 文件 | 10,000 文件 | 50,000 文件 | |---|---|---|---|---| | 逐文件扫描 + 公有云 LLM | ~8 秒 | ~80 秒 | ~160 秒 | ~13 分钟 | | 逐文件扫描 + 私有化 LLM | ~40 秒 | ~400 秒 | ~800 秒 | ~65 分钟 | | AOS 快照查询 | ~2 秒 | ~6 秒 | ~11 秒 | ~55 秒 |

业务影响：

• 公有云场景：万级文件仓库中，每问一个问题等 2-3 分钟，一次 Review 等待 10-30 分钟
• 私有化场景：同样问题等待 15-65 分钟，且 30 文件即占满上下文——agent 只能"看到"极小片段，分析质量严重降级，遗漏和错误率大幅上升，直接影响代码 Review 和变更影响分析的可靠性和安全性
• 质量问题传导：私有化部署下 agent 为节省 token 会跳过部分文件，导致变更影响分析遗漏关键调用链——这不仅是效率问题，更是线上事故的隐患

AOS 的价值：

• 速度保障：预构建快照后查询仅几秒，私有化部署下也比逐文件扫描快 100 倍以上
• 质量保障：每次查询只返回精简 JSON（~2KB），远小于私有化模型 30KB 的上下文上限，agent 有充足空间理解结果并组织回答
• 安全兜底：AOS 保证 100% 准确的结构化数据，不依赖 LLM 的推理能力——即使私有化模型推理能力较弱，也能给出可靠的变更影响分析

3. 关系推理不可靠：AI 会遗漏和出错

AI agent 追踪调用链和继承关系时存在系统性误差：

| 任务类型 | AI agent 原生方式 | 准确率问题 | |---|---|---| | 方法清单 | 文本搜索函数定义 | ❌ 遗漏约 50% 的方法（package 可见性方法不匹配） | | 依赖分析 | 解析构建文件 | ❌ 解析失败时返回空结果 | | 调用链追踪 | 文本搜索函数调用 | ⚠️ 约 75% 结果是噪音（匹配到注释和字符串） | | 框架代码 | 源码中不可见 | ❌ Spring / MyBatis 调用完全遗漏 | | 注解生成代码 | 源码中只有注解 | ❌ Lombok 生成的 getter/setter 不可见 |

业务影响：开发者问"修改这个方法会影响哪些代码"，AI agent 如果遗漏了 50% 的调用者，变更影响分析就是不完整的——可能导致线上事故。

AOS 的价值：通过源码解析 + 编译产物分析双通道，保证 100% 准确率。实测中，仅用源码解析时调用关系覆盖率只有 0.08%，加入编译产物分析后提升到 79.87%，并新增 2,697 条框架调用。在大型仓库中这一差距会更显著——框架和注解的使用密度通常随项目规模增加而上升。

数据说明：以上数据基于中型仓库（500 文件 / 8 万行）实测，大型 / 超大型仓库数据按线性模型推导。

使用场景

| 场景 | 典型问题 | AI agent 直接读源码 | AOS 语义层 | |---|---|---|---| | 了解陌生项目 | "这个项目有哪些模块？" | 万级文件扫描 ~160 秒，无法保证全貌 | ~11 秒，100% 完整 | | 正向调用链 | "OrderController.create 调用了哪些方法？" | 逐跳追踪，约 75% 噪音 | 一步直达，零噪音 | | 反向调用链 | "修改 UserService.login 会影响哪些代码？" | ❌ 无法直接回答，遗漏 50% 调用者 | ✅ 一步返回，100% 完整 | | 继承 / 实现分析 | "UserRepository 接口有哪些实现？" | ❌ 文本匹配漏匹配内部类 | ✅ 精确查询，含内部类继承链 | | 框架调用追踪 | "调用了哪些 Spring 框架方法？" | ❌ 框架源码不在仓库中，完全不可见 | ✅ 编译产物还原，覆盖率 0.08% → 79.87% | | 注解生成代码 | "@Data 类有哪些 getter/setter？" | ❌ 源码只有注解，无方法签名 | ✅ 还原全部生成方法 + 完整签名 | | 包间依赖 | "controller 包依赖了哪些包？" | 构建文件解析可能失败，含标准库噪音 | 100% 准确，仅返回业务包 | | 代码复杂度分析 | "哪些方法复杂度最高？需要优先 review？" | ❌ 需逐文件分析控制流 | ✅ complexity 属性直接查询，含圈复杂度/嵌套深度/分支数 | | 测试方法识别 | "项目有哪些测试方法？测试覆盖率怎样？" | 文本搜索 @Test，约 75% 噪音 | ✅ isTest/testType 精确识别，区分单元/集成测试 | | API 端点检测 | "项目暴露了哪些 API？Spring 还是 JAX-RS？" | ❌ 需逐文件扫描注解 | ✅ endpointInfo 直接查询，含 HTTP 方法/路径/框架 | | 数据模型识别 | "项目有哪些 JPA Entity？哪些是 Lombok 数据类？" | 文本搜索注解，漏匹配嵌套类 | ✅ isDataModel/dataModelType 精确分类（JPA Entity + MyBatis POJO） | | Javadoc 查询 | "这个方法的文档说明是什么？" | 需回查源码文件 | ✅ description 属性直接获取 | | Lambda 分析 | "哪些方法用了 Stream/Lambda？" | ❌ 需逐文件分析方法体 | ✅ lambdaCount 直接查询 | | 数据库表结构查询 | "数据库有哪些表？这张表有哪些列/主键/注释？" | ❌ DDL 从未解析 | ✅ Table 对象直接查询（974 表实测） | | 外键关系分析 | "这张表引用了哪些表？删这张表影响哪些表？" | ❌ 人工读 DDL 的 CONSTRAINT | ✅ fkReferences 链接 + fkDetails 明细 | | 实体↔表映射 | "Loan 实体映射哪张表？审计字段在数据库叫什么？" | ❌ @Table 参数不提取 | ✅ Class.tableName（@Table(name) 提取）+ 列补全 | | MyBatis POJO 识别 | "OmsCartItem 是数据模型吗？" | ❌ 无 @Entity 注解，全部漏判 | ✅ dataModelType="MyBatis POJO"（resultMap 反查，97 个实测） | | Mapper 数据访问分析 | "这个 Mapper 操作哪张表？哪些表没有数据访问层？" | ❌ Mapper 是普通接口，零关联 | ✅ mapperMapsTable/mapperMapsEntity 链接（100% 映射） | | 列名↔属性名映射 | "product_sku_id 列对应哪个 Java 属性？" | ❌ 人工读 resultMap XML | ✅ Mapper 对象（sourceFile + resultMapId 定位） | | 全栈链路追踪 | "从 Controller 到数据库表的完整链路？" | ❌ 链路在 Mapper 层断裂 | ✅ calls + mapperMapsTable 组合贯穿 | | schema 变更影响 | "给这张表加列要改哪些代码？" | ❌ 全文搜索 XML | ✅ query Table + 反查 Mapper/POJO 结构化影响面 | | 技术栈判定 | "这个项目是 JPA 还是 MyBatis？" | ❌ 只能看 pom 依赖文本 | ✅ POJO/Mapper/Table 量化证据链 |

如何使用

1. 安装

npm install -g @leansoftx/asdm-aos
aos --version

2. 分析你的 Java 项目

cd my-java-project
aos action refreshRepo --params '{"repoPath":"."}'

生成 data/snapshot.json，包含整个项目的结构化本体。

0.0.10 新增：项目根目录自动检测。repoPath 支持三种传入方式：

• 目录路径（默认）："repoPath": "/path/to/project"
• 文件路径："repoPath": "src/main/java/com/example/UserService.java" — 自动向上查找 pom.xml/build.gradle 确定项目根目录
• 不传：从当前工作目录自动检测

0.0.11 新增：数据库 DDL 与 MyBatis 自动分析。refreshRepo 自动检测仓库内 .sql 文件（DDL）与 MyBatis Mapper XML 并纳入快照，无需额外参数：

• 检测到 .sql → 解析 CREATE TABLE / ALTER TABLE / CREATE INDEX（MySQL 方言），生成 Table 对象与 fkReferences 外键链接
• 检测到 Mapper XML → 解析 namespace / resultMap / 动态 SQL 表名引用，生成 Mapper 对象与 mapperMapsTable/mapperMapsEntity 链接
• 两者再与 Java 分析结果融合（JPA @Table(name) 匹配 + MyBatis resultMap 反查 + 审计字段补全）
• 无 DDL / Mapper XML 的项目自动跳过，对既有结果零影响

也可单独导入 DDL（只解析 SQL 不扫描代码）：

aos import-ddl --sql-dir ./sql --dialect mysql

3. 查询代码结构

# 项目有多少个包
aos query Package --all --pretty

# 某个包下有哪些类和接口
aos link contains --src pkg:com.example.user --pretty

# 某个类的方法
aos link contains --src cls:com.example.UserService --pretty

4. 分析调用关系

# 正向：这个方法调用了哪些方法？
aos link calls --src "mtd:com.example.UserService.login(:String:String)" --pretty

# 反向：谁调用了这个方法？（变更影响分析）
aos link calledBy --src "mtd:com.example.UserService.login(:String:String)" --pretty

# 继承关系
aos link extends --src cls:com.example.AdminUserService --pretty

# 接口实现
aos link implements --src cls:com.example.UserRepository --pretty

4.5 分析数据库关系（0.0.11 新增）

# 表的外键引用（这张表引用了哪些表）
aos link fkReferences --src table:m_loan --pretty

# Mapper → 数据库表 / Mapper → POJO 实体
aos link mapperMapsTable --src mapper:com.macro.mall.mapper.OmsCartItemMapper --pretty
aos link mapperMapsEntity --src mapper:com.macro.mall.mapper.OmsCartItemMapper --pretty

# 外键明细（列名/引用表/引用列/约束名）
aos query Table --where "name=m_loan" --pretty
#   → fkDetails: [{columnName:"client_id", refTable:"m_client", refColumn:"id", name:"fk_loan_client"}]

# 对象 ID 格式：table:<表名>  mapper:<XML namespace>

5. 代码特征查询（0.0.10 新增）

# 复杂度分析：找出高复杂度方法（需配合 jq）
aos query Method --all | jq '[.[] | select(.complexity != null) | {name, cc: .complexity.cyclomaticComplexity, depth: .complexity.maxNestingDepth}] | sort_by(-.cc) | .[0:20]'

# 测试方法：查询所有 @Test 方法
aos query Method --all | jq '[.[] | select(.isTest == true) | {name, testType}]'

# API 端点：查询所有 API 端点方法
aos query Method --all | jq '[.[] | select(.endpointInfo != null) | {name, httpMethod: .endpointInfo.httpMethod, path: .endpointInfo.path, framework: .endpointInfo.framework}]'

# 数据模型：查询所有数据模型类
aos query Class --all | jq '[.[] | select(.isDataModel == true) | {name, dataModelType}]'

# Javadoc：查询有文档注释的方法
aos query Method --all | jq '[.[] | select(.description != "") | {name, description}]'

# Lambda：查询含 Lambda 表达式的方法
aos query Method --all | jq '[.[] | select(.lambdaCount > 0) | {name, lambdaCount}]'

5.5 数据库特征查询（0.0.11 新增）

# 数据库表全景：全量表名与数量
aos query Table --all | jq '[.[].name] | length'
aos query Table --all | jq '[.[].name] | sort'

# 单表结构：列/类型/注释/主键/外键
aos query Table --where "name=oms_cart_item" --pretty
aos query Table --where "name=oms_cart_item" | jq '.[0].columns | map({name, sqlType, comment, isPrimaryKey, isNullable})'

# 复合主键表（primaryKey 为逗号分隔字符串，如 "menu_id,role_id"）
aos query Table --all | jq '[.[] | select((.primaryKey | split(",") | length) > 1) | {name, primaryKey}]'

# 孤儿表：无任何实体映射的表（纯查找表/调度框架表）
aos query Table --all | jq '[.[] | select(.matchedEntityClass == "") | .name]'

# 删表影响分析：谁引用了这张表
aos query Table --all | jq '[.[] | select(.fkDetails[]?.refTable == "m_client") | .name]'

# MyBatis POJO：无 @Entity 注解但被 resultMap 引用的数据模型
aos query Class --where "dataModelType=MyBatis POJO" --all | jq '[.[].name] | length'

# JPA 实体映射表名（@Table(name=...) 提取）
aos query Class --all | jq '[.[] | select(.tableName != null) | {name, tableName}]'

# Mapper 全景与数据访问层覆盖率
aos query Mapper --all | jq '[.[] | {name, mappedTable, mappedEntityClass, resultMapId}]'
aos query Mapper --where "mappedTable=oms_order" --pretty

# 持久化技术栈判定（POJO/Mapper/Table 量化证据链）
aos query Class --all | jq '[.[] | select(.isDataModel == true) | .dataModelType] | group_by(.) | map({type: .[0], count: length})'

6. 配合 AI Agent 使用（推荐）

AOS CLI 是底层工具。如果你在 AI coding agent 中使用，推荐安装 AOS Skill，让 agent 自动理解何时调用 CLI。

# 将 Skill 复制到项目的 .codebuddy/skills/ 目录
mkdir -p .codebuddy/skills
cp -r node_modules/@leansoftx/asdm-aos/skills/asdm-aos-skill .codebuddy/skills/

安装后可直接用自然语言提问，agent 自动调用 AOS CLI：

"谁调用了 UserService.login？"
"修改这个方法会影响哪些代码？"
"项目有哪些模块？"
"哪些方法复杂度最高？需要优先 review？"
"项目有哪些 API 端点？用的是 Spring 还是 JAX-RS？"
"项目有哪些 JPA Entity？"
"哪些方法是测试方法？"
"数据库有哪些表？这张表的列和注释是什么？"（0.0.11）
"删除这张表会影响哪些表？"（0.0.11）
"Loan 实体映射哪张表？"（0.0.11）
"OmsCartItemMapper 操作哪张表？"（0.0.11）
"product_sku_id 列对应哪个 Java 属性？"（0.0.11）
"这个项目是 JPA 还是 MyBatis 技术栈？"（0.0.11）

技术限制

| 限制 | 说明 | 影响 | |---|---|---| | 仅支持 Java | Maven 和 Gradle 项目，不支持其他语言 | 非 Java 项目无法使用 | | 单次全量加载 | 每次命令调用全量加载 JSON 快照到内存 | 建议 < 1,000 个代码文件（含 DDL 后快照增大约 2-7%） | | 无并发写保护 | 多个 CLI/Agent 同时执行 action 会互相覆盖 | 刷新快照期间不要并发执行其他写操作 | | 全表扫描查询 | 过滤查询为全表扫描，无索引 | 万级方法仓库查询约 100ms | | 快照需手动刷新 | 代码变更后需手动重建快照 | 不会自动感知代码变更 | | .class only 方法属性受限 | 仅有字节码、无源码的方法（如 Lombok 生成、内部类继承）的 complexity/description/isTest/endpointInfo/lambdaCount 为 null 或默认值 | 部分方法的代码特征属性不可用 | | 增量解析未启用 | IncrementalParser 已实现但 refreshRepo 仍为全量解析 | 增量模式将在后续版本启用 | | DDL 仅支持 MySQL 方言 | CREATE TABLE / ALTER / CREATE INDEX；存储过程 DELIMITER 块自动跳过 | Oracle/PG/SQLServer 方言文件解析报错（多方言过滤为后续改进项） | | MyBatis 仅解析 XML | resultMap / 动态 SQL 表名引用 / 嵌套映射 | MyBatis-Plus 注解 SQL（@TableName/@TableId）不在 XML 中，暂不覆盖 | | Liquibase changelog 不解析 | 变更日志型 XML DDL 不在快照范围 | 后续版本预留 |

发版记录

| 版本 | 日期 | 说明 | |---|---|---| | 0.0.12 | 2026-08-19 | 文档修复：npm 展示 README 与 CLI 文档同步（build:cli 自动同步根 README）；功能与 0.0.11 一致 | | 0.0.11 | 2026-08-19 | 打通"代码 ↔ 数据库"：DDL 解析（Table 对象/fkReferences 外键链接）、MyBatis Mapper XML 解析（Mapper 对象/双链接）、MyBatis POJO 识别、JPA @Table 参数提取、DDL ↔ 代码融合与审计字段补全；分析器目录重构（shared/java/sql 分层）；全栈链路（Controller → 数据库表）首次贯穿 | | 0.0.10 | 2026-08-13 | 代码特征深度分析（tree-sitter）：复杂度分析、Javadoc 提取、测试方法识别（@Test/@ParameterizedTest）、API 端点检测（Spring/JAX-RS）、数据模型识别（JPA Entity/Record/Lombok）、Lambda 提取、项目根目录自动检测；测试体系建立（107 测试） | | 0.0.8 | 2026-08-12 | 链接完整性增强：calledBy 反向调用链（变更影响分析）、ext: 外部库虚拟对象（外部依赖调用可见性）、contains 包含 Interface；Skill 触发场景与 Agent 行为规范完善 | | 0.0.4 | 2026-08-12 | npm 正式发布：CLI 结构化日志与结果统计、findClassFiles 收集 test-classes、Lambda 调用合并、方法重载 ID 区分、内部类方法归属修正——调用链覆盖率 4.32% → 79.87% 系列修复 | | 0.0.3 | 2026-08-10 | npm 发布准备：README 完善（项目目标/价值/架构/使用方式）、CLI 日志输出优化 | | 0.0.1 | 2026-08-07 | 初始 MVP：Java 源码 + 字节码分析，包/类/接口/方法/依赖 6 种对象与 contains/dependsOn/calls/extends/implements/usesDependency 链接，本体快照与 query/link CLI |

了解更多

• ASDM 官网：https://asdm.ai — AI-First System Development Methodology，面向 AI 时代的系统开发方法论，致力于让 AI coding agent 在企业级超大型代码项目中高效、准确地理解和分析代码结构
• AOS CLI npm 包：https://www.npmjs.com/package/@leansoftx/asdm-aos — 本 CLI 的完整命令列表、参数说明和版本历史

© 2026 ASDM. All rights reserved.