# 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](https://www.npmjs.com/package/@leansoftx/asdm-aos)（Java 本体分析）并针对前端生态重新建模。

[![npm](https://img.shields.io/npm/v/nice-aos.svg)](https://www.npmjs.com/package/nice-aos) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) [![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)

**本地优先**：全部解析与查询在本机完成，快照落在 `./.nice-aos/data/`，不上传任何源码；AI 问答走你已有的 CLI / 模型服务配置。

## 30 秒上手

```bash
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 output --format html --output blueprint.html       # 离线可开的交互蓝图
nice-aos ask "这个项目的架构分层和功能域划分？"             # AI 自动带着全仓上下文回答
nice-aos output --format table --output .nice-aos/tables    # 15 张表（CSV/Excel），给二次分析
nice-aos panorama                                          # 跨域知识全景矩阵 + 跨域断链候选
nice-aos knowledge build --root C:\knowledge-md            # 扫描知识资产库（同时投影进 SQLite 镜像）
nice-aos knowledge export --format html --output kb.html   # 打开分类/标签/来源图谱
nice-aos query KnowledgeEntry --kind knowledge --limit 5   # 知识对象与代码对象同一张查询面
nice-aos graph impact "mod:src/analyzers" --local --json  # 改这里会波及哪些知识卡片（不连 Neo4j）
nice-aos knowledge doc-ingest --dry-run                   # 把仓内 docs/adr·plan·SKILL.md 扫成可检索知识对象（先看账本再落库）
nice-aos knowledge doc-impact kc:knowledge.card-to-code-linking   # 这张卡落在哪些代码对象上（只读正向牵动）
nice-aos export docs && nice-aos check docs --gate        # 说明书产物锚定知识快照；四检 + 三条指标进 CI（退出码 0/1/2）
npm run eval:knowledge                                    # 35 条四类检索/注入评测基线（manual，不在 npm test 里）
```

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

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

nice-aos 的 **22 个子命令**（`help` 为 commander 内建；另有 4 个顶层兼容别名 `deadcode` / `duplicates` / `io` / `matrix` 在帮助里隐藏）收敛为 **4 个面向"人与 AI agent"的入口 + N 个领域型命令**：

| 命令 | 角色 | 一句话 |
|------|------|--------|
| `ask` | **输入** | 基于本体快照向 AI CLI 或模型服务提问；上下文 SQLite 预过滤毫秒级构建，CLI 超时自动降级到模型服务 |
| `output` | **输出** | Markdown 全景报告 / JSON / 自包含 HTML 蓝图 / viewmodel 视图模型 / 架构图画布 / **表格 CSV·Excel**（15 张表 + manifest 对账）/ **分层上下文文档树**（`output docs` → `.nice-aos/context/`，三明治 L1/L2/L3 md + docs.html 浏览器）（`output` 是 `export` 别名，两名等价） |
| `serve` | **服务** | 一行启动本地 HTTP 数据源（CORS `*`）：快照 JSON、蓝图 HTML、**`/docs` 项目文档在线浏览**、`/api/*` 数据端点、`/ws/snapshot` 推送，供 agent / 油猴脚本 / 网页跨源拉取 |
| `mcp` | **协议** | 以 [MCP server](https://modelcontextprotocol.io) 把 16 个能力暴露为 tools，Claude Code / Cursor 等客户端**直接调用**——零上下文复制 |

领域型命令：`db`（数据库）/ `deploy`（部署）/ `service`（Java 后端）/ `planning`（PRD 规划）/ `overview`（多项目全景）/ `panorama`（跨域知识全景）/ `knowledge`（知识资产图谱）/ `portfolio`（项目集组合分析）/ `propose`（本体改进提案包）；原子型：`query` / `count` / `link` / `action` / `vocabulary`（能力发现）；运维：`update` / `storage` / `check`。详见 `nice-aos --help`。

## 命令全景

| 分组 | 命令 | 用途 |
|------|------|------|
| 核心 | `ask` / `output`（`export`）/ `serve` / `mcp` | 输入 / 输出 / 服务 / 协议四大入口 |
| 原子 | `query` | 按类型查对象（39 种类型），支持 `--where` 四形态过滤 |
| 原子 | `count` | 按类型计数，单行 JSON，给 agent 聚合用 |
| 原子 | `link` | 遍历 58 种关系，支持 `--depth 1..3` 多跳影响面 |
| 原子 | `action` | 受控动作：`refreshRepo` / `analyzeFile` / `markReviewed` / `addNote` |
| 原子 | `vocabulary` | 能力发现：能查的类型、能走的关系、能调的动作，标出「本图可达」子集（无需快照也能用） |
| 体检 | `check deadcode\|duplicates\|io\|matrix\|impact\|diff` | 不可达导出 / 结构重复 / 敏感 API / 结构坐标 / 影响面 / 版本差异 |
| 领域 | `db` | MySQL 迁移脚本 → 数据库模型 + ER 图 + 9 大审计 |
| 领域 | `deploy` | Dockerfile / compose / K8s / nginx → 部署模型 + 5 场景审计 |
| 领域 | `service` | Java 后端（asdm-aos 快照）→ 服务模型 + 五维健康审计 |
| 领域 | `planning` | PRD / 模块 / 迭代 / Roadmap → 规划模型 + 规划蓝图 |
| 领域 | `overview` | 多项目快照聚合 + 5 层架构图 + 跨项目依赖矩阵 |
| 领域 | `panorama` | 融合五类快照 → 知识矩阵（8×8）+ 跨域断链候选 + 知识缺口行动 |
| 领域 | `knowledge` | 外部知识资产图谱 + 项目 OKF-lite 卡片 + 仓内存量文档入库（`doc-ingest` / `doc-impact`）+ FTS5/RRF 混合检索；正文默认脱敏，凭据门禁可进 CI |
| 领域 | `portfolio` | 多项目组合分析：跨项目调用轨迹 / 全家桶蓝图 / 变更集驱动的代码评审 |
| 治理 | `propose` | 把测量 → 诊断 → 差异 → 门禁串成一份可评审的提案文档 |
| 运维 | `update` | 检测 npm 最新版本并一键升级（`--check` 仅检测） |
| 运维 | `storage` | SQLite 存储层：init / status / rebuild / vacuum / drop |
| 运维 | `graph` | Neo4j 远端图 sink：push / status / query / schema / impact / deps / delete |

## 为什么需要它

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

| 传统方式 | nice-aos |
|---------|----------|
| grep 谁导入了 ai.ts（遍历全部文件） | `link importedBy --src file:src/services/ai.ts`（毫秒） |
| 人工追页面跳转关系 | `link navigatesTo --src route:dietary_health` |
| 不知道哪些文件是死代码 | 快照内置四级死代码（文件/导出/类型/函数级） |
| 单个独立脚本/文件想快速体检（不建快照） | `action analyzeFile` 不落盘直接输出本体 JSON |
| 循环依赖靠运气发现 | 快照内置 Tarjan SCC（`_meta.cycles`） |
| 不知道 store 被谁用了 | `link usesStore --src store:useThemeStore` |
| 接口方法有哪些实现类（实现关系记录在实现类里，正向查不到） | `link implementedBy --src "iface:src/types/storage.ts#IStorage"` |
| 找某个方法的所有声明与实现 | `query Method --where "name~createinterface"`（一次命中签名+实现） |
| 审计油猴脚本是否越权调 GM API | `query GmApiUsage --where "declared=false"` |
| 想看油猴脚本把数据存在哪（缓存键/IndexedDB/内联数据集） | `query DataResource --where "storage=indexedDB"` |
| 不知道油猴脚本往页面哪里注入了 DOM | `link injectsInto --src us:demo.user.js` |
| 说不清项目架构和功能划分 | `query Project` 看 summary/architecture（分层画像 + 功能域清单 + 健康度） |
| 不知道某目录的职责 | `query Module --where "archLayer=state"` 看职责画像 |
| 想按功能域浏览代码 | `link belongsTo --src dom:health` 列出该域全部成员 |
| 前端调的接口后端到底有没有实现 | `output --format json` 看 `_meta.unmatchedFrontendCalls`；`Route.frontendCalls` 溯源到文件行号 |
| 说不清这套系统哪些知识已产出、哪些还是盲区 | `nice-aos panorama`（8×8 知识矩阵 + 跨域断链候选） |
| 有一份知识库，想看分类、标签、来源怎么连在一起 | `nice-aos knowledge build --root <知识库>` 然后 `knowledge export --format html` |
| 想知道"这份 ADR / 这张卡落在哪些代码上"，或"动这段代码要复核哪份决策" | `nice-aos knowledge doc-impact <kc:或kd:id>`（正向牵动）；反查表在 `export docs` 的 `knowledge.md` 里 |
| 想问"知识产物还能信吗 / 检索有没有退化" | `nice-aos check docs --gate`（四检 + 三条指标，退出码 0/1/2）｜`npm run eval:knowledge`（35 条四类评测基线） |
| 想要一张可交互的项目蓝图给人看 | `output --format html --output blueprint.html`（浏览器直接打开，无需服务） |
| 想给 AI agent / 油猴脚本一个 HTTP 数据源 | `nice-aos serve`（一行启动，CORS 就绪，暴露快照与蓝图） |
| 想让 codebuddy / opencode 带着项目上下文回答问题 | `nice-aos ask "这个项目有哪些功能域？"`（自动注入快照上下文） |
| 想知道"这次改动会波及什么" | `nice-aos check impact src/services/ai.ts`（本地快照重算，无需 Neo4j） |
| 想知道"这次改动让本体变好还是变差" | `nice-aos check diff --base <基线快照>`（客观差异 + 改善/退化判定） |
| CI 里要卡住"本体质量退步" | `nice-aos propose --gate nice-aos.gates.json`（门禁可执行，不通过退出码非 0） |

## 核心能力速览

- **多栈语义解析** —— 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 循环依赖、未声明依赖治理，`check deadcode` / `duplicates` / `io` 三个独立检测器开箱即用
- **五套领域审计器** —— 油猴安全（GM 越权/XSS 面/@connect）、数据库（9 大审计 + ER 图）、部署（安全/高可用/一致性/依赖/健康）、Java 服务（复杂度/数据层/测试/质量/依赖）、产品规划（PRD 四维健康）
- **前后端链路对账（v0.58）** —— 前端 API 调用点（Vue SFC / React / Flutter-Dart / Kotlin-Retrofit，含 `apiGet → request → fetch` 封装层）与后端路由（Go / Python / Next.js / Node Express-Fastify-Koa-Nest）跨语言匹配，`Route.frontendCalls` 溯源到文件行号；`_meta.resolutionStats` 建立恒等式 `sites = matched + unmatched + unexamined`——`unexamined` 正常恒为 0，>0 即"该语言压根没进匹配循环"的静默丢数据信号
- **油猴静态数据资源（v0.57）** —— 缓存注册表逐键展开、localStorage/GM 存储键、IndexedDB 库/表、内联数据集、嵌入 JSON、@resource，统一为 `DataResource` 对象；`query DataResource` / `link accessesDataResource` 可直接回答"脚本把数据存在哪、谁读写这个缓存键"
- **自包含蓝图 HTML** —— `output --format html` 一键产出零依赖可离线打开的可视化蓝图：领域蓝图、业务数据图、逻辑流向矩阵、路由导航链 SVG、Props 数据流图、UML 类图；三套主题随心切换（`output theme add/list/remove` 可自定义）
- **AI agent 原生友好** —— `ask` 注入上下文问答（SQLite 预过滤 <50ms）、`serve` 开箱即用的 CORS 数据源、`mcp` 让 Claude Code/Cursor 直接调用，`output --format viewmodel` 输出聚合 JSON 供 agent 直接消费
- **跨域知识全景** —— `panorama` 把代码 / 数据库 / 部署 / 后端服务 / 产品规划五类快照融合成「知识类别 × 生命周期阶段」矩阵（8×8），每格给出证据条数、置信度与取证渠道，并列出**跨域断链候选**（孤岛表、未匹配调用、孤立部署服务、无对应实现的规划特性）——回答「这套系统哪些知识已产出、哪些还只是潜在」
- **知识资产图谱** —— `knowledge build --root <目录>` 扫描知识库（`exports/entries.json` 或 `db/knowledge.db`，或至少两份 Markdown），抽出分类、标签、来源、资产台账和文档互链，`knowledge export --format html` 打开图谱。快照不写正文、命令和绝对路径
- **知识进存储与图谱（v0.61，K0）** —— `knowledge` 是第七类快照：`build` 除写 JSON 主源外自动投影进 SQLite 镜像（实测 10822 条目 → 11047 对象 / 64621 条边，含按条目展开的归属边），于是 `storage status` / `storage rebuild --kind knowledge` / `vocabulary --kind knowledge` / `query <Type> --kind knowledge` / `graph push --kind knowledge` 全部可用。投影只发生在边界一次，快照文件与 HTML 蓝图的键名不变；正文类字段在投影层整行拒绝，泄露即告警
- **项目卡片与混合检索（v0.61，K1/K2）** —— `knowledge/cards/**.md` 作为项目知识 SoT，Profile 驱动 OKF-lite 校验，`knowledge lint --gate` 把断链、缺章节、取代环与凭据命中左移到 CI。schema v3 FTS5 结合中文单字/bigram、结构化筛选与知识图扩散做 RRF(k=60)，`knowledge search/show/trace/stats` 与 4 个 MCP 工具、3 个 HTTP 端点共用查询面。卡片快照只存 redacted `indexText`；`raw` 只影响当次 FTS，rebuild 后恢复脱敏检索；无 SQLite 时显式返回无相关性排序的降级结果
- **知识与代码接成一张图（v0.62，K3）** —— 卡片 `references[]` / `entities[]` 经**共享解析器**连到代码对象（`documents` / `constrains` 边，命中才建边），逐边强度分三档（显式 id 1.0 / 路径 0.9 / 标题模糊 0.7，落在 `aos_links.confidence`，schema v4）。`graph impact --local` 走**代码+知识混合图**，改代码能算出「哪些卡片要复核」（`affected[].type` 出现 `KnowledgeCard`）；`graph deps --local` 输出「模块 × 规范」耦合。`ask` 默认注入 RRF Top-K 卡片片段（`--no-knowledge` 可关），`/api/ask/context?knowledge=1` 增 `knowledge` 段。全景矩阵的卡片数进 `facets`，`latent` / `no-channel` 缺口可反查「该补哪类卡片」
- **仓内文档成为知识、说明书真的有内容（v0.63，D0–D2）** —— 第三类知识对象 `KnowledgeDoc`（前缀 `kd:`）：`knowledge doc-ingest` 把 `docs/adr`、`docs/plan`、`skills/**/SKILL.md`、`docs/guide.md` 按标题层级自适应分块扫成「文件行 + 块行」，块行只存脱敏 `indexText`，正文里的引用串经与卡片**同一个解析器**连到代码对象（本仓实测 55 份 → 828 行、引用命中率 46.9%（语料随文档增删漂移，见 ADR 0032 D8））。`export docs` 的文档树接知识：L1 一行域覆盖、每个 L2 多一节「本域知识」、新增汇总页 `knowledge.md`（与 `knowledge export --format markdown` **同一份渲染器**，7 节 / 81 KB 的决策台账 + 反查表 + 闸门拒收计数）；字节预算是契约（`DOCS_BUDGET_BYTES`），缺数据的小节照样出场并给出补救命令（**不谎报缺失**）。反查用 `knowledge doc-impact <id>`（只读正向牵动：卡片/文档作**终点**进 `graph impact`，作**起点**走这条）。地基：镜像新鲜度水位改成「先比 mtime 再比字节数」，内容没变就不再重投影（`storage status --verify` 才付全文件 sha256 的成本），自定义快照目录不再被误判成「永远新鲜 / 永远落后」；`search`/`show`/`trace`/`stats` 不许静默空集，一律带 `source`/`stale`/`reason` 把「镜像落后」和「库里真没这条」分开说；`npm run test:isolation` 守住「跑测试不许污染工作区镜像」
- **知识门禁与评测基线（v0.63，D3–D4）** —— `check docs` 把知识质量变成 CI 可判定：`grounding.js` 确定性**四检**（符号存在 / 快照锚定 / 凭据 / 坐标可回）+ 新鲜度守卫，三条指标 `groundingViolations`、`knowledgeStaleness` 可配阈值（本仓已配 `== 0`），`knowledgeCoverage` 首轮**只观测**（68.4% = 13/19 域；归域是借来的事实，`noKnowledge[]` 与 `unattributed[]` 分开报）；规则读 `nice-aos.gates.json` 的新 `knowledge` 段，退出码 **0 通过 / 1 知识没达标 / 2 门禁配置有误**（配错时一条门禁都不执行），`check diff` 的本体段 8 条一字未动。每份 docs 产物 frontmatter 锚 `knowledgeSnapshot` / `knowledgeScannedAt` / `cardsHash`，`corpus` 段直说「产物锚定的语料 ≠ 当前白名单」并给下一步命令。评测侧：`ask eval --mode search` + `npm run eval:knowledge` 跑 `test/eval/knowledge-search.jsonl` **35 条四类**（宽松 vs AND / 卡片 vs 文档 / ask 注入开关 / 降级路径），首轮 35/35 —— 阈值全是本仓自测值，**它是防退化的地板不是质量结论**，人评 10 条标定样本尚未开始（不承诺「人评 ≥90%」），真实检索不进 `npm test`。

- **图数据库 sink（可选）** —— `nice-aos graph push / status / query / impact / deps / delete` 把本体图谱再写一份到 Neo4j，供多仓库聚合查询与 Cypher 直查；MCP 另暴露 `graph_impact` / `graph_deps` / `graph_query` / `graph_status` 四个工具。未配置 Neo4j 时静默降级为 no-op，不影响 JSON / SQLite 主数据源
- **能力发现（v0.59）** —— `nice-aos vocabulary` 列出能查的对象类型、能走的链接类型、能调的动作，并标出「本图可达」的子集（纯 Go 仓会看到 `passesProps` 标为不可达）；与 MCP `get_schema`、serve `/api/schema` 同一事实源，**无快照也能用**
- **统一输出契约（v0.59）** —— 加 `--envelope`（或 `NICE_AOS_ENVELOPE=1`）后成功输出统一为 `{ok:true,data:{...}}`、失败统一为 `{ok:false,error:{code,message,hint}}`；默认模式保持历史形状（jq 管道与既有脚本零影响）。未知类型 / 未知 linkType 的错误自带 `errorCode` + 相似候选 + 修复提示，agent 不必反复试错
- **导出可对账（v0.59）** —— `output --format table` 把单快照压成 **15 张表（CSV / Excel）**：schema 字典 / 实例层 / 项目集维度三层同源定义，边数据与 Neo4j 入库同一 `extractLinks` 口径；统一 `manifest.json` 记录源快照、参数与文件哈希，离开本机仍可回答"从哪导的、怎么导的、改没改过"；流式写盘支撑大快照
- **结构体检与影响面（v0.54~0.59）** —— `check matrix` 输出模块坐标矩阵（ca/ce/depth + 架构规则诊断）；`check impact` 在本地快照上做变更影响面分析（无需 Neo4j，与远端图路径共用 `extractLinks` 语义零漂移）；`check diff` 做本体版本差异与改善/退化判定；`--envelope` 同契约
- **质量门禁与改进提案（v0.59）** —— Act 步验收：门禁规则可执行（`nice-aos.gates.json`）、本体改进提案包可评审（`nice-aos propose`，ADR 0028/29），与本体版本 diff（ADR 0027）、知识缺口行动推导（ADR 0026）构成"诊断→建议→验收"闭环
- **项目集组合分析（v0.55~0.59）** —— `nice-aos portfolio` 扫描多项目合集：跨项目调用轨迹（A 真的在调 B）、全家桶蓝图、变更集驱动的跨项目代码评审（ADR 0024/25），扫描结果可导出 CSV / Excel 二次分析
- **查询防呆（v0.59）** —— `--where` 列名先校验：拼错的列名过去静默返回空数组，现在给 stderr 警告（`--strict-where` 可升级为报错）；`link --depth 1..3` 支持多跳影响面，与 MCP `traverse_links` 同一实现

## 更多上手姿势

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

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

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

# 入口可达性：导出但从入口不可达的 class
nice-aos check deadcode

# 前端接口与后端路由对账
nice-aos output --format json | jq '._meta.resolutionStats.frontendCallMatchRate'

# 能力发现：这个快照能查什么类型 / 能走什么关系
nice-aos vocabulary --active-only

# 统一输出契约（给程序消费）：{ok:true,data:{...}} / {ok:false,error:{code,message,hint}}
nice-aos --envelope count Method

# 导出成可二次分析的表格（15 张表 + manifest.json 对账清单）
nice-aos output --format table --output .nice-aos/tables --table-format both

# 变更影响面 / 本体版本差异（纯本地快照，不依赖 Neo4j）
nice-aos check impact src/services/ai.ts        # 或传对象 id：file:src/services/ai.ts
nice-aos check diff --base .nice-aos/data/snapshot.base.json

# CI 门禁：本体质量退步即不通过（退出码非 0）
nice-aos propose --gate nice-aos.gates.json --output proposal.md

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

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

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

## 输出形态与产物契约

| 形态 | 命令 | 产物 |
|------|------|------|
| Markdown 全景报告 | `output --format markdown` | 人读的层级化报告（8MB 快照可压成 ~100KB） |
| JSON | `output --format json` | 完整本体快照（对象 + 边 + `_meta` 对账统计） |
| 自包含 HTML 蓝图 | `output --format html` | 零依赖离线可开的可视化蓝图 |
| 视图模型 | `output --format viewmodel` | 供 agent 直接消费的聚合 JSON |
| 架构图画布 | `output --format canvas` | 自包含 HTML+SVG 画布 |
| 表格数据包 | `output --format table` | 15 张 CSV/Excel 表 + `manifest.json` |
| 三件套 | `output --format all --output base` | `base.md` + `base.html` + `base.viewmodel.json` |
| 分层文档树 | `output docs` | `.nice-aos/context/`（L1/L2/L3 md + `knowledge.md` + `tree.json` + `docs.html`；L2 带「本域知识」小节） |
| 知识说明书 | `knowledge export --format markdown` | 卡片/文档的七节台账（要点+证据+反查表+闸门拒收计数），与 `knowledge.md` **同一份渲染器** |

**manifest 对账**：任何写文件的导出都会旁落一份 `manifest.json`（`schema: nice-aos/export-manifest/v1`），记录源快照指纹（sha256 + commit/branch）、本次参数、对象/边/表行数与每个产物的 `bytes`/`sha256`——哈希与写盘同一次遍历算出，避免"写完再回读"的篡改窗口。

**统一输出契约**：`--envelope`（或 `NICE_AOS_ENVELOPE=1`）后成功为 `{ok:true,data:{...}}`、失败为 `{ok:false,error:{code,message,hint}}`；不加则保持历史输出形状，既有 jq 管道与脚本零影响。

## 集成方式

- **MCP（stdio）** —— `nice-aos mcp` 把 16 个能力暴露为 tools：`get_stats` / `get_schema` / `list_types` / `query_objects` / `get_node` / `traverse_links` / `get_health` / `panorama_matrix` / `graph_impact` / `graph_deps` / `graph_query` / `graph_status` / `knowledge_search` / `knowledge_show` / `knowledge_trace` / `knowledge_stats`。v0.52 起快照缺失自动 build，不 fail-fast。
- **HTTP 数据源** —— `nice-aos serve`（默认 `127.0.0.1:8420`，CORS `*`）提供：静态 `/snapshot.json` `/blueprint.html` `/overview.html` `/docs` `/context/*` `/openapi.json`；数据 `/api/objects/:type` `/api/ask/context` `/api/schema` `/api/stats` `/api/status` `/api/panorama` `/api/graph/*` `/api/knowledge/*`；动作 `POST /api/ask` `POST /action`；推送 `/ws/snapshot`。鉴权 `--token admin-secret`（角色分级 read<write<admin，静态端点豁免）、限流 `--rate-limit`。
- **Skills** —— 随包分发 **14 个 SKILL.md**（`skills/**/SKILL.md`），覆盖全量扫描、代码评审、死代码、数据库、部署、后端服务、规划、画布、上下文构建、油猴脚本、知识资产、项目集等场景工作流，与 CLI 共用同一份快照，无独立安装步骤。
- **Contrib（按需取用，不进 npm 包）** —— `contrib/blueprint-ai-agent`、`contrib/project-blueprint-ai-agent`：油猴脚本形态的蓝图页 AI 分析助手（多模型接入、工具循环驱动）。

## 数据与安全边界

- **本地优先**：解析、快照、索引全在本机；快照落在 `./.nice-aos/data/`，不上传源码。
- **不写敏感内容**：外部知识资产图谱只落结构（分类/标签/来源/互链），不写正文、命令行与绝对路径，带"敏感凭据"标签的条目只计数；项目卡片快照只存经门禁脱敏的 `indexText`，导出与普通查询始终是 redacted 视图。`raw` 是显式自负风险开关，不改变快照与导出边界。仓内文档入库同理：`summary`/`body`/`commands`/`source_path` 这类正文字段**整行拒绝**（泄露计数必须为 0），只有脱敏后的 `indexText` 进检索面，资产标识与来源绝对路径在导出里只出计数。
- **尊重 .gitignore**：构建产物与敏感文件不进快照；扫描根目录由 `--params roots` 显式指定。
- **Neo4j 可选**：图数据库只是可牺牲派生索引，JSON 快照始终是唯一权威事实源；未配置即静默 no-op。
- **服务默认只监听本机**：`serve` 默认 `127.0.0.1`，对外暴露需显式 `--host` 并配 `--token`。

## 环境要求与安装

- **Node.js >= 18**（推荐 20+；用到内置 `node:test` 与 ESM）
- 无原生编译依赖：`better-sqlite3` 与 `neo4j-driver` 为 **可选依赖**，装不上时 SQLite 自动降级为 JSON 存储、Neo4j 功能关闭，其余能力不受影响。

```bash
npm install -g nice-aos      # 全局安装
npx nice-aos --help          # 免安装试用
nice-aos update              # 已是全局安装 → 检测并一键升级到最新版
nice-aos update --check      # 只检测不升级
npm uninstall -g nice-aos    # 卸载（数据留在 ./.nice-aos/，需自行删除）
```

## 深入

- 场景、本体、CLI、解析能力与已知限制：[docs/guide.md](docs/guide.md)
- 设计决策（ADR 0001–0032）：[docs/adr/](docs/adr/) —— 本体元模型与 envelope、linkDefs、converter 钩子、MCP 工具化、跨域知识全景、前后端链路对账、质量门禁、项目集组合分析、知识资产图谱与项目知识索引、存量文档入库与 docs 导出接知识的取舍与坑
- 架构评审与整改计划：[docs/arch-review/](docs/arch-review/)
- 路线图（历史，0.33–0.36）：[docs/plan/aos-three-core-roadmap.md](docs/plan/aos-three-core-roadmap.md)
- 变更历史：[CHANGELOG.md](CHANGELOG.md)
- 现行行为以 `nice-aos --help` 为准；能力发现以 `nice-aos vocabulary` 与 MCP `get_schema` 为准

体检不进日常入口：`nice-aos check deadcode|duplicates|io`。顶层 `deadcode` / `duplicates` / `io` 仍可用（帮助里隐藏）。

## 开发

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

源码结构：`src/cli`（命令与输出契约）/ `src/ontology`（本体模型与图谱）/ `src/analyzers`（多语言解析）/ `src/storage`（JSON + SQLite 存储层与迁移账本）/ `src/database` `src/deployment` `src/service` `src/planning` `src/overview` `src/panorama` `src/knowledge` `src/portfolio`（领域域）/ `src/themes`（蓝图主题）。

## 许可证

[MIT](./LICENSE) © nice-aos contributors