0xsarwagya/ontoly

# Ontoly [](https://github.com/0xsarwagya/ontoly/actions/workflows/semantic-evaluation.yml) [](https://www.npmjs.com/package/@0xsarwagya/ontoly-cli) [](LICENSE) [](https://www.typescriptlang.org/) Ontoly 是一个原生支持 JavaScript 和 TypeScript 的软件智能引擎，它将源代码转化为确定性的 Software Graph。 开发者工具不应该一遍又一遍地重新解析同一个仓库结构。Ontoly 构建了一个共享的语义表示，使得 agents、MCP servers、SDK generators、文档工具、架构工具、静态分析工具和 IDE 都可以进行查询，而无需重复搜索文件或重建部分的 AST 上下文。 Ontoly 构建的是理解能力。它不回答问题，不调用语言模型，不生成 embeddings，也不做概率性的猜测。 ## 状态 Ontoly `v1.0.0` 是第一个稳定版本。当前的 alpha 版本：`v1.1.0-alpha.2`。 公开契约已冻结，该仓库包含： - Software Graph 规范 - 确定性的编译器 pipeline - 由 TypeScript Compiler API 驱动的 JavaScript 和 TypeScript 语义前端 - 查询引擎 - MCP 功能 - 用于 artifact 生成的确定性 Enhancers - 用于特性归属、意图词汇和概念图的派生 Semantics artifact - 用于归属、热点、协同变更、变动率和漂移的派生 History artifact - 可移植的 Agent Skills - 验证和语义评估基础设施 - 针对文档、打包、skills、示例和回归检查的发布关卡 ## 链接 - 网站：[oss.sarwagya.wtf/ontoly](https://oss.sarwagya.wtf/ontoly) - 文档：[oss.sarwagya.wtf/ontoly/docs](https://oss.sarwagya.wtf/ontoly/docs) - Agent Skills 目录：[oss.sarwagya.wtf/ontoly/docs/skills](https://oss.sarwagya.wtf/ontoly/docs/skills) - Enhancers：[oss.sarwagya.wtf/ontoly/docs/enhancers](https://oss.sarwagya.wtf/ontoly/docs/enhancers) - 仓库：[github.com/0xsarwagya/ontoly](https://github.com/0xsarwagya/ontoly) - 更新日志：[CHANGELOG.md](CHANGELOG.md) - 路线图：[ROADMAP.md](ROADMAP.md) - 架构：[ARCHITECTURE.md](ARCHITECTURE.md) - RFC 索引：[RFC_INDEX.md](RFC_INDEX.md) - 治理：[GOVERNANCE.md](GOVERNANCE.md) - 第三方声明：[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) - HOL Guard：[](https://hol.org/go/guard/sarwagyasingh69?dest=%2Fguard%2Fbilling%3Fpromo%3DGUARD20-SARWAGYASINGH69%23upgrade&link_id=8aab4f0e-d950-4ba5-89f1-5689b7c867c8&utm_source=insights_share&utm_medium=affiliate_cta&utm_campaign=share20) ## 什么是 Ontoly Ontoly 是软件仓库与每一个需要理解它的工具之间的语义层。 ``` Repository -> Compiler Frontends -> Semantic Model -> Software Graph -> Enhancers -> Semantics -> Query Engine -> MCP, Skills, SDKs, Docs, IDEs, Analysis ``` Software Graph 就是产品本身。其他一切都是围绕它的消费者、插件、pass 或验证层。 ## 什么不是 Ontoly - 不是聊天界面。 - 不是编程 agent。 - 不是 copilot。 - 不是向量搜索。 - 不是 embeddings pipeline。 - 不是托管的 SaaS。 - 默认不是代码生成器。 - 不能替代 TypeScript、ESLint 或测试套件。 AI 工具可以通过 MCP 和 Skills 使用 Ontoly，但该图从不依赖于 AI 输出。任何面向 LLM 的 Ontoly 使用都必须通过 [LLM Enhancement](docs/llm-enhancement.md) 进行，以确保图证据、置信度和兜底规则保持明确。 ## 为什么使用 Software Graphs 大多数开发者工具都在重复做同样昂贵的工作： - agents 搜索文件 - 文档工具解析符号 - 架构工具重建依赖图 - SDK generators 推断 API 形状 - 静态分析工具重建调用和导入关系 Ontoly 将这些重复的工作转化为一个可重用的图： - 确定性 ID - 图原生诊断 - 明确的来源 - 稳定的序列化 - 查询索引 - 语义概念索引 - 验证报告 - 扩展元数据 目标很简单：每一个需要理解软件的工具都应该首先询问 Ontoly 是否已经知道。 ## 从源码快速开始 从源码构建时请使用此路径。 ``` git clone https://github.com/0xsarwagya/ontoly.git cd ontoly corepack enable pnpm install --frozen-lockfile pnpm build ``` 为包含的基础示例构建图： ``` pnpm ontoly build examples/basic ``` 检查生成的 artifacts： ``` ls examples/basic/ontoly-output pnpm ontoly inspect src/service.ts --root examples/basic pnpm ontoly search UserService --root examples/basic pnpm ontoly impact UserService --root examples/basic pnpm ontoly stats examples/basic ``` 运行主要的发布关卡： ``` pnpm check-types pnpm test pnpm docs:check-links pnpm skills:validate pnpm validate:packages ``` 在发布前运行完整关卡： ``` pnpm release:gates ``` ## 包安装 公共包名均在 `@0xsarwagya` 作用域下。 使用以下命令安装： ``` pnpm add -D @0xsarwagya/ontoly-cli pnpm exec ontoly build . ``` 在交互式终端中，不带路径的 `ontoly build` 会询问要索引哪个文件夹。按 Enter 键选择当前目录，粘贴相对、绝对或 `~/` 路径，或者显式传递路径： ``` pnpm exec ontoly build pnpm exec ontoly build apps/api pnpm exec ontoly build --no-prompt ``` 如果您的环境中不可用 npm，请使用上方的源码检出流程。 ## 构建 Artifacts `ontoly build ` 默认会写入内容丰富的 `ontoly-output/` 捆绑包： ``` ontoly-output/ SoftwareGraph.json manifest.json coverage.json quality.json semantic-model.json reports/ architecture.json api.json dependencies.json configuration.json frameworks.json workspace.json nodes/ all.json by-type/ relationships/ all.json by-type/ communities/ communities.json community-000.json html/ graph.html architecture.html ``` 输出捆绑包是确定性的，适用于人类、agents、网站、发布 artifacts 以及调试 Ontoly 自身的理解能力。 如需紧凑的缓存式 artifact 目录，请传入 `--output .ontoly`： ``` ontoly build . --output .ontoly ``` ``` .ontoly/ SoftwareGraph.json diagnostics.json indexes.json metadata.json statistics.json ``` JSON 图是规范的序列化格式。在 Software Graph 规范稳定之前，二进制格式被刻意排除在范围之外。 可以直接编译远程仓库： ``` ontoly build --remote https://github.com/0xsarwagya/ontoly.git ontoly output --remote git@github.com:0xsarwagya/ontoly.git ``` 远程构建会克隆到一个临时检出目录中，将相对输出路径写入您运行 Ontoly 的目录，并将 git URL 记录在输出清单中。 ## Software Graph Software Graph 是一个版本化的 JSON 模型，包含： - 仓库元数据 - 节点 - 边 - 诊断 - 索引 - 统计信息 - 来源 - 扩展元数据 核心节点家族包括模块、包、函数、方法、类、接口、类型别名、枚举、路由、控制器、服务、提供者、配置、环境变量、事件和资源。 核心关系家族包括 `IMPORTS`、`EXPORTS`、`CONTAINS`、`CALLS`、`DEPENDS_ON`、`USES`、`READS`、`WRITES`、`IMPLEMENTS`、`EXTENDS`、`HANDLES`、`MOUNTS`、`INJECTS`、`AUTHORIZES`、`REGISTERED_IN`、`PUBLISHES` 和 `SUBSCRIBES`。 请阅读 [RFC-0001](rfcs/0001-software-graph.md) 中的规范说明。 ## 确定性 ID Ontoly 分配稳定的 ID，以便图输出可以进行缓存、差异对比、测试和跨构建比较。 示例： ``` module:src/auth/service.ts fn:src/auth/service.ts:login class:src/auth/user-service.ts:UserService route:POST:/login model:User ``` 只要语义标识留存，ID 就应在重建中保持不变。 ## Compiler Pipeline 编译器是一个确定性的多阶段 pipeline： ``` Repository Discovery -> Frontend Parsing -> Symbol Emission -> Semantic Model Generation -> Relationship Extraction -> Graph Construction -> Diagnostics -> Validation -> Indexing -> Serialization ``` 编译器前端发出结构化事实。编译器负责图的构建。这使得解析器包保持小巧，并将图兼容性集中在中央管理。 请阅读 [RFC-0002](rfcs/0002-compiler-pipeline.md) 中的架构说明。 ## 查询引擎 查询引擎提供确定性的图推理原语： - 按 ID、名称、类型、文件和标签查找 - 邻域扩展 - 图遍历 - 依赖遍历 - 调用者和被调用者查找 - 路径查找 - 影响分析 - 过滤 - 模式匹配 - 基于索引的遍历 请阅读 [RFC-0003](rfcs/0003-query-engine.md) 中的查询设计。 示例： ``` import { buildSoftwareGraph } from "@0xsarwagya/ontoly-compiler"; import { createQueryEngine } from "@0xsarwagya/ontoly-query"; const graph = await buildSoftwareGraph({ root: process.cwd() }); const query = createQueryEngine(graph); const services = query.services(); const callers = query.callers("fn:src/auth/service.ts:login"); const dependencies = query.dependencies("class:src/auth/user-service.ts:UserService"); ``` ## CLI 源码检出通过根目录的 `ontoly` 脚本暴露 CLI： ``` pnpm ontoly --help ``` 常用命令： | 命令 | 用途 | | --- | --- | | `pnpm ontoly build ` | 构建 Software Graph。 | | `pnpm ontoly output ` | 生成包含 JSON 报告、图社区和 HTML 浏览器的 `ontoly-output/`。 | | `pnpm ontoly inspect ` | 检查图 artifacts 或实体。 | | `pnpm ontoly search ` | 将自然概念解析为排名靠前的图实体。 | | `pnpm ontoly find ` | 查找符号、缩写、特性或配置术语。 | | `pnpm ontoly locate ` | 定位特性级别的图触点。 | | `pnpm ontoly evidence ` | 为 agents 和审查生成由图支持的紧凑型证据包。 | | `pnpm ontoly semantics build ` | 生成派生的 Semantics artifact 和概念图。 | | `pnpm ontoly history build ` | 生成仓库历史、归属、热点、协同变更和漂移 artifacts。 | | `pnpm ontoly ownership ` | 检查确定性的 Git 派生的仓库归属。 | | `pnpm ontoly hotspots` | 列出高变动率/高修改频率的图热点。 | | `pnpm ontoly trace ` | 追踪图关系。 | | `pnpm ontoly coverage ` | 报告语义覆盖率。 | | `pnpm ontoly mcp` | 启动 MCP 功能。 | | `pnpm ontoly skills list` | 列出打包的 Agent Skills。 | | `pnpm ontoly skills validate` | 验证 skill 元数据、链接、模板和示例。 | | `pnpm ontoly validate all` | 运行验证实验室。 | | `pnpm ontoly evaluate` | 运行语义评估。 | | `pnpm ontoly leaderboard` | 生成语义排行榜输出。 | | `pnpm ontoly benchmark performance` | 运行性能基准测试报告。 | | `pnpm ontoly diff base.graph head.graph` | 根据文档 [RFC 0005](rfcs/0005-graph-diffing.md) 进行确定性的 Software Graph 差异对比。 | 请参阅 [docs/cli.md](docs/cli.md) 和 [docs/reference/cli.mdx](docs/reference/cli.mdx)。 ## MCP Ontoly MCP 在 Software Graph 之上公开了结构化的功能。这些功能在执行前会验证输入，并针对缺失、歧义或不支持的请求返回结构化的诊断信息。 当 LLM 使用 Ontoly MCP 响应时，必须使用 LLM Enhancement。非 LLM 工具可以直接调用 MCP，但 LLM 生成的答案必须保留 Ontoly 的证据、置信度和兜底边界。 ``` pnpm ontoly mcp --list pnpm ontoly mcp ``` 代表性功能： - `GraphStatistics` - `ExplainArchitecture` - `FindDependencies` - `ImpactAnalysis` - `TraceExecution` - `FindConfigurationUsage` - `FindAuthenticationFlow` - `FindFeatureOwner` - `SemanticContext` 每个功能都是确定性的，并且由证据支持。置信度是根据图证据推导出来的，而非猜测。 请参阅 [docs/mcp.md](docs/mcp.md) 和 [docs/getting-started/mcp.mdx](docs/getting-started/mcp.mdx)。 ## Agent Skills Ontoly 在 [skills](skills) 下提供了可移植的 Agent Skills。这些 Skills 教导编程 agents 在回退到仓库搜索之前如何使用 Ontoly。 每一个官方 Skill 都声明了 `ontoly.enhancement: "LLM Enhancement"`。对于任何使用 Ontoly 且具备 LLM 能力的 agent 来说，这是强制要求的，而不是可选的标签。 每个 Skill 都遵循相同的工作流程： 1. 确认已安装的工作流程声明了 LLM Enhancement。 2. 验证是否存在 Ontoly 图。 3. 如果缺失，使用 `ontoly build .` 构建一个。 4. 检查图的信任度和诊断信息。 5. 首先使用 Ontoly MCP 功能。 6. 仅当图无法回答时才检查源文件。 7. 在最终响应中引用证据和置信度。 包含的 Skills： - 架构审查 - 影响分析 - 代码库引导 - 请求追踪 - 依赖分析 - 安全审查 - 配置分析 - 框架分析 - 文档生成 - 重构 - 性能分析 - 死代码分析 - 迁移分析 - SDK 生成 验证已发布的 Skills： ``` pnpm skills:validate pnpm skills:validate-installed ``` 请阅读公开的 [Agent Skills 目录](https://oss.sarwagya.wtf/ontoly/docs/skills)、 [skills/SKILL_CATALOG.md](skills/SKILL_CATALOG.md)、[docs/agent-skills.md](docs/agent-skills.md) 和 [docs/skills-validation.md](docs/skills-validation.md)。 ## 验证实验室 oly 包含一个永久的验证实验室。它会在真实的仓库和测试夹具中衡量正确性、确定性、图质量、语义覆盖率、信任度、诊断、性能和回归。 ``` pnpm validate pnpm evaluate pnpm benchmark:performance ``` 验证输出位于 [validation](validation) 下： - 仓库注册表 - 各仓库报告 - 语义排行榜 - 回归基线 - 发布关卡 - 性能报告 - 网站资产 - 徽章 请阅读 [docs/validation-lab.md](docs/validation-lab.md) 和 [docs/semantic-evaluation-harness.md](docs/semantic-evaluation-harness.md)。 ## 发布证据 发布证据报告是本地验证套件生成的 artifacts，而不是营销宣传。 | 领域 | 证据 | | --- | --- | | 验证摘要 | [validation/lab-summary.md](validation/lab-summary.md) | | 语义排行榜 | [validation/semantic/leaderboard.md](validation/semantic/leaderboard.md) | | 发布关卡 | [validation/release-gates/report.md](validation/release-gates/report.md) | | Skills 评估 | [validation/skills/report.md](validation/skills/report.md) | ## 包 | 包 | 用途 | | --- | --- | | `@0xsarwagya/ontoly-cli` | CLI 和公共便捷 API。 | | `@0xsarwagya/ontoly-core` | Software Graph schema、稳定 ID、索引、图辅助工具和 Semantic Index APIs。 | | `@0xsarwagya/ontoly-compiler` | 仓库发现、图构建 pipeline、验证和监听模式。 | | `@0xsarwagya/ontoly-parser-typescript` | JavaScript 和 TypeScript 前端及关系提取。 | | `@0xsarwagya/ontoly-parser-openapi` | 用于 Software Graph 事实的 OpenAPI 前端。 | | `@0xsarwagya/ontoly-typescript` | 纯 TypeScript 语义模型分析器。 | | `@0xsarwagya/ontoly-semantic` | 语义生成器和框架分析器注册表。 | | `@0xsarwagya/ontoly-analyzers` | 语义覆盖率和图质量分析器。 | | `@0xsarwagya/ontoly-query` | 确定性 Software Graph 查询引擎。 | | `@0xsarwagya/ontoly-enhancer` | 用于不可变图 artifact 转换的公共 Enhancer API。 | | `@0xsarwagya/ontoly-enhancer-history` | 用于归属、热点、协同变更、变动率和架构漂移的确定性 History enhancer。 | | `@0xsarwagya/ontoly-enhancer-semantics` | 用于特性归属、词汇、邻域和概念图的确定性 Semantics enhancer。 | | `@0xsarwagya/ontoly-intelligence` | 基于 Software Graph、Semantic Index、Semantics 和 History artifacts 的确定性智能 API。 | | `@0xsarwagya/ontoly-diagnostics` | 共享诊断构造函数。 | | `@0xsarwagya/ontoly-cache` | 本地图 artifact 持久化。 | | `@0xsarwagya/ontoly-mcp` | 面向 AI agents 和工具的结构化图功能。 | | `@0xsarwagya/ontoly-plugin-mermaid` | 图可视化插件示例。 | | `@0xsarwagya/ontoly-plugin-html` | 交互式离线 HTML 图可视化插件。 | 包名刻意使用了 `@0xsarwagya/ontoly-*`。 ## 仓库布局 ``` packages/ core/ compiler/ parser-typescript/ parser-openapi/ typescript/ semantic/ analyzers/ query/ diagnostics/ cache/ mcp/ cli/ plugins/ mermaid/ html/ skills/ docs/ rfcs/ examples/ validation/ site/ ``` ## 示例 可运行的示例位于 [examples](examples) 中： | 示例 | 用途 | | --- | --- | | [examples/basic](examples/basic) | 小型 TypeScript 图构建。 | | [examples/typescript-library](examples/typescript-library) | 库结构的 TypeScript 项目。 | | [examples/nestjs-api](examples/nestjs-api) | 框架式 API 结构。 | | [examples/turborepo](examples/turborepo) | 工作区和包图行为。 | | [examples/cli-usage](examples/cli-usage) | CLI 工作流程示例。 | | [examples/mcp](examples/mcp) | MCP 功能用法。 | | [examples/semantic-queries](examples/semantic-queries) | 查询引擎示例。 | ## 文档地图 根目录 `docs/` 树是事实来源。`site/` 下的 OSS 网站快照即由此生成： ``` pnpm site:docs ``` 该命令会为网站重写 Markdown 链接，将 MDX 输出到 `site/docs/`，并添加页面级的 SEO frontmatter，如规范 URL、关键字和来源出处。着陆页和项目级别的 SEO 位于 `site/landing.mdx` 和 `site/manifest.json` 中。 在 `main` 分支上，`.github/workflows/publish-site.yml` 会运行相同的生成和验证流程，然后调用 `0xsarwagya/internet/scripts/oss-sync.mjs` 将 `site/manifest.json`、`site/landing.mdx`、`site/docs/**` 和 `site/assets/**` 复制到 `https://oss.sarwagya.wtf/ontoly` 的 OSS 网站内容快照中。 专门的网站位于 `https://ontoly.sarwagya.wtf`，OSS 文档镜像位于 `https://oss.sarwagya.wtf/ontoly`。 从这里开始： - [docs/index.mdx](docs/index.mdx) - [docs/getting-started/installation.mdx](docs/getting-started/installation.mdx) - [docs/getting-started/build-a-graph.mdx](docs/getting-started/build-a-graph.mdx) - [docs/getting-started/query-the-graph.mdx](docs/getting-started/query-the-graph.mdx) - [docs/getting-started/mcp.mdx](docs/getting-started/mcp.mdx) - [docs/concepts/software-graph.mdx](docs/concepts/software-graph.mdx) - [docs/concepts/compiler-pipeline.mdx](docs/concepts/compiler-pipeline.mdx) - [docs/concepts/plugin-system.mdx](docs/concepts/plugin-system.mdx) - [docs/query-engine.md](docs/query-engine.md) - [docs/typescript-semantic-model.md](docs/typescript-semantic-model.md) - [docs/framework-detection.md](docs/framework-detection.md) - [docs/agent-skills.md](docs/agent-skills.md) - [docs/skills-overview.md](docs/skills-overview.md) - [skills/SKILL_CATALOG.md](skills/SKILL_CATALOG.md) - [docs/validation-lab.md](docs/validation-lab.md) - [docs/faq.md](docs/faq.md) - [docs/troubleshooting.md](docs/troubleshooting.md) ## RFCs Ontoly 使用 RFCs 来管理影响公共图、编译器、插件、查询和类型契约的变更。 - [RFC-0001: Software Graph](rfcs/0001-software-graph.md) - [RFC-0002: Compiler Pipeline](rfcs/0002-compiler-pipeline.md) - [RFC-0003: Query Engine](rfcs/0003-query-engine.md) - [RFC-0004: Plugin and Compiler Pass System](rfcs/0004-plugin-and-compiler-pass-system.md) ## 发布工程 发布关卡包括： - 构建 - 类型检查 - 测试 - 包验证 - 文档链接检查 - Markdown 样式检查 - 许可证检查 - skill 验证 - 已安装 artifact 的 skill 验证 - npm pack 验证 - 全新的首用户冒烟测试 - 验证实验室 - 语义评估 - 回归关卡 - 通过 `.github/workflows/publish-site.yml` 发布 OSS 网站 使用以下命令运行所有内容： ``` pnpm release:gates ``` ## 已知限制 - JavaScript 和 TypeScript 通过一个确定性的 ECMAScript 前端提供支持。 - 某些框架分析器刻意是不完整的。 - 未实现二进制图格式。 - 托管 SaaS、向量搜索和 LLM 推理属于非目标。 - 自 v1.0.0 起，Software Graph schema 已趋于稳定。 - MCP 功能仅根据可用的图证据进行回答。 - 面向 LLM 的使用需要 LLM Enhancement；Ontoly 本身保持无 AI 状态。 请阅读 [docs/known-limitations.md](docs/known-limitations.md)。 ## 贡献 贡献应该保持确定性和图兼容性。 在发起 pull request 之前： ``` pnpm install --frozen-lockfile pnpm build pnpm check-types pnpm test pnpm release:gates ``` 公共契约变更需要先提交 RFC。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 安全 请私下报告安全问题。请参阅 [SECURITY.md](SECURITY.md)。 ## 支持 使用 GitHub issues 反馈 bug，使用 GitHub discussions 讨论设计问题。请参阅 [SUPPORT.md](SUPPORT.md)。 ## 许可证 Ontoly 采用 GNU Affero General Public License v3.0 提供授权。 为需要专有使用、私人修改、商业再分发、无 AGPL 义务的托管服务使用或合同条款的团队提供商业许可。 如需商业许可，请联系 [hello@sarwagya.wtf](mailto:hello@sarwagya.wtf)。 请参阅 [LICENSE](LICENSE)、[COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md)、 [CONTRIBUTOR_LICENSE_AGREEMENT.md](CONTRIBUTOR_LICENSE_AGREEMENT.md) 和 [TRADEMARK_POLICY.md](TRADEMARK_POLICY.md)。

标签：TypeScript, 云安全监控, 代码分析, 凭证管理, 威胁情报, 安全插件, 开发者工具, 数据管道, 暗色界面, 自动化攻击, 软件工程, 静态分析