入口模块

@ageniti/core 同时提供根导出和更细粒度的 subpath export。

推荐默认方式

大多数应用直接从根包导入即可：

import { createAgenitiApp, defineAction, s } from "@ageniti/core";

这样最简单，也和文档示例保持一致。

可用导出

根导出

@ageniti/core

当你希望用一个入口拿到主要 authoring API 时，优先用根导出。

根导出也是较高层打包能力和 project helper 的主要入口，包括：

• buildArtifacts()
• packageArtifacts()
• publishArtifacts()
• initProject()
• doctorProject()
• findDefaultAppModule()
• loadProjectConfig()
• detectTypeScriptRuntime()

Subpath Export

@ageniti/core/ai-sdk
@ageniti/core/adapters
@ageniti/core/app
@ageniti/core/cli
@ageniti/core/core
@ageniti/core/dev
@ageniti/core/http
@ageniti/core/json-runner
@ageniti/core/lint
@ageniti/core/manifest
@ageniti/core/mcp
@ageniti/core/react
@ageniti/core/schema

每个 Subpath 暴露什么

• @ageniti/core/ai-sdk：OpenAI-compatible tools、Responses tools、AI SDK tools 和组合 manifest。
• @ageniti/core/adapters：内建 surface adapter 与 adapter helper。
• @ageniti/core/app：createAgenitiApp()。
• @ageniti/core/cli：createCli()。
• @ageniti/core/core：defineAction()、createRuntime() 等 runtime 和 action 原语。
• @ageniti/core/dev：createDevServer()。
• @ageniti/core/http：createHttpHandler() 和 createHttpServer()。
• @ageniti/core/json-runner：createJsonRunner()。
• @ageniti/core/lint：lintActions()。
• @ageniti/core/manifest：describeAction()、createSurfaceManifest()、diffActionManifests() 等 manifest helper。
• @ageniti/core/mcp：MCP manifest、handler 和 stdio server。
• @ageniti/core/react：createReactActionAdapter()。
• @ageniti/core/schema：s、toJSONSchema() 和 SchemaValidationError。

常见导入模式

编写 action：

import { defineAction, s } from "@ageniti/core";

只构建 MCP server 包装层：

import { createMcpHandler } from "@ageniti/core/mcp";

运行 lint 或工具链检查：

import { lintActions } from "@ageniti/core/lint";

只生成 AI tool 定义：

import { createAISDKTools, createOpenAITools } from "@ageniti/core/ai-sdk";

什么时候更适合用 Subpath

优先使用 subpath 的情况：

• 你在做边界明确的集成层
• 你希望 import 直接表达模块职责
• 你的包或服务只暴露单一 surface
• 你在写围绕 manifest、lint 或 schema 的工具

优先使用根导出的情况：

• 你在写主应用集成代码
• 你希望 onboarding 尽可能简单
• 你不需要显式的模块级分层
• 你需要 build helper 或 project setup helper，而它们没有单独的 subpath export

类型声明

所有公开入口共享同一套类型声明。runtime contract、result envelope、action 元数据和 schema 类型在各个导出路径上保持一致。