nice-aos

nice-aos — 让 AI 与开发者毫秒级读懂任意代码仓库

把 React / Vue 2+3 / Flutter(Dart) / Go / Python / PHP / Kotlin / 油猴脚本 仓库，以及 MySQL 迁移脚本、Docker+K8s+nginx 部署配置、Java 后端本体快照、产品规划 PRD 文档，扫描为可查询的结构化本体快照——架构分层、功能域、组件/Store/路由、接口与调用链、四级死代码、健康度画像，一应俱全。一条命令建快照，之后每个结构问题都是一次毫秒级查询，替代逐文件 grep。

本体按概念范畴与抽象层级组织（L3 架构 → L0 审计事实），架构分层以内容信号推断而非目录名直译；聚合节点自动生成职责画像与自然语言总结。底层借鉴 asdm-aos（Java 本体分析）并针对前端生态重新建模。

30 秒上手

npm install -g nice-aos          # Node.js >= 18；免安装用 npx nice-aos ...
cd /path/to/your-project

# 1. 一条命令建快照（1000+ 文件约 3.5s → ./.nice-aos/data/snapshot.json）
nice-aos action refreshRepo --params '{"repoPath":"."}'

# 2. 用问题直接查答案
nice-aos query Project                                        # 项目画像 + 架构分层 + 健康度
nice-aos link importedBy --src "file:src/services/ai.ts"      # 谁导入了我（变更影响面）
nice-aos query Method --where "deadCandidate=true"            # 函数级死代码候选

# 3. 出一张给人看、给 AI 用的图与答案
nice-aos export --format html --output blueprint.html         # 离线可开的交互蓝图
nice-aos ask "这个项目的架构分层和功能域划分？"                # AI 自动带着全仓上下文回答

这只是 React 单页应用的冰山一角——Vue 2/3 中后台、Flutter App、Go CLI/Gin 后端与前后端融合仓库、PHP（zentaopms 类）与 Kotlin（Android/JVM）后端、油猴脚本安全审计、MySQL ER 图、部署拓扑各有专属章节，见 解析能力。

四个入口：问 / 出 / 服务 / 协议

nice-aos 的 13 个子命令收敛为 4 个面向"人与 AI agent"的入口 + N 个领域型命令：

领域型命令：db（数据库）/ deploy（部署）/ service（Java 后端）/ planning（PRD 规划）/ overview（多项目全景）；原子型：query / link / action；运维：update / storage。详见 nice-aos --help。

为什么需要它

在 1000+ 源文件的前端项目中，让 AI agent 直接 grep 全量源码，响应慢且结构理解易出错。nice-aos 将"文件"升维为"关系图谱"：

核心能力速览

• 多栈语义解析 —— React 19 / Vue 2 Options API（RuoYi 类中后台）/ Vue 3 SFC + Pinia / Flutter Widget + Riverpod / Go cobra+Gin 融合仓库 / Python FastAPI/Flask / PHP（zentaopms 类）/ Kotlin（Android/JVM）/ 油猴脚本，提取组件、Store（Zustand/Pinia/Vuex/Riverpod）、接口/类/Trait/方法、路由、静态数据资源（缓存注册表/存储键/IndexedDB/内联数据集）与 props 传递链等 39 种对象、58 种关系
• 关系图谱查询 —— link importedBy / renders / navigatesTo / implements / calls ... 双向遍历：变更影响分析、导航图、方法"声明+实现"一次命中
• 四级死代码 + 健康审计 —— 文件/导出/类型/函数级候选（保守判定宁漏报不误报）、Tarjan 循环依赖、未声明依赖治理，deadcode / duplicates / io 三个独立检测器开箱即用
• 五套领域审计器 —— 油猴安全（GM 越权/XSS 面/@connect）、数据库（7 大审计 + ER 图）、部署（安全/高可用/一致性/依赖/健康）、Java 服务（复杂度/数据层/测试/质量/依赖）、产品规划（PRD 四维健康）
• 油猴静态数据资源（v0.57） —— 缓存注册表逐键展开、localStorage/GM 存储键、IndexedDB 库/表、内联数据集、嵌入 JSON、@resource，统一为 DataResource 对象；query DataResource / link accessesDataResource 可直接回答"脚本把数据存在哪、谁读写这个缓存键"
• 自包含蓝图 HTML —— export --format html 一键产出零依赖可离线打开的可视化蓝图：领域蓝图、业务数据图、逻辑流向矩阵、路由导航链 SVG、Props 数据流图、UML 类图；三套主题随心切换
• AI agent 原生友好 —— ask 注入上下文问答（SQLite 预过滤 <50ms）、serve 开箱即用的 CORS 数据源、mcp 让 Claude Code/Cursor 直接调用，export --format viewmodel 输出聚合 JSON 供 agent 直接消费

更多上手姿势

# 单文件体检（不建快照，stdout 输出本体 JSON，可与 jq 管道组合）
nice-aos action analyzeFile --params '{"file":"Steam-License-Classifier.js"}' | jq '.ScriptFunction[] | select(.deadCandidate)'

# 结构完全相同的重复函数（AST fingerprint 分组）
nice-aos duplicates --min-size 20

# 敏感 API 使用扫描（fetch / eval / localStorage ...，数据驱动注册表）
nice-aos io --min-danger medium

# 版本升级（全局安装一键升级；--check 仅检测）
nice-aos update

# 本地数据源服务（AI agent / 油猴脚本跨源拉取）
nice-aos serve

快照目录解析优先级：--snapshot-dir 参数 > NICE_AOS_SNAPSHOT_DIR 环境变量 > cwd/.nice-aos/data > ~/.nice-aos/data。

深入

• 场景、本体、CLI、解析能力与已知限制：docs/guide.md
• 路线图（历史，0.33–0.36）：docs/plan/aos-three-core-roadmap.md
• 现行行为以 nice-aos --help 为准

体检不进日常入口：nice-aos check deadcode|duplicates|io。顶层 deadcode / duplicates / io 仍可用。

开发

npm install
npm test
node src/cli/index.js --help