{"_id":"@aincore/sdk","_rev":"3-6cb6f7f3ee5bf541095780a668e25535","name":"@aincore/sdk","dist-tags":{"latest":"1.1.0"},"versions":{"0.4.1":{"name":"@aincore/sdk","version":"0.4.1","keywords":["mindvault","ai","llm","local-ai","mindvault-core","mcp","oauth","pkce"],"license":"MIT","_id":"@aincore/sdk@0.4.1","maintainers":[{"name":"bzda404","email":"wanq090@gmail.com"}],"homepage":"https://github.com/bzda404/mindvault-sdk#readme","bugs":{"url":"https://github.com/bzda404/mindvault-sdk/issues"},"dist":{"shasum":"53916cbe5a8414099111efefdef6b6b2c6293918","tarball":"https://registry.npmjs.org/@aincore/sdk/-/sdk-0.4.1.tgz","fileCount":15,"integrity":"sha512-fmErBucgvsPZzXAM2LRJ8X0++EQdFm/CE7qb797Xg8jQOxjxvMDN4nlDEA6Ocl3I3p0mhvslFCKxnYrWc/lE3w==","signatures":[{"sig":"MEUCICR1/0koUMsGOcBcXa1gNMkHY4cEi9cLJ9SHdi5rNX9GAiEA9fRFov0rMHYSm/UKchORLMx2C1iGcAD61xTjcuSEC6I=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46851},"main":"./dist/index.js","type":"module","_from":"file:aincore-sdk-0.4.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"private":false,"scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsc","format":"prettier --write .","test:watch":"vitest"},"_npmUser":{"name":"bzda404","email":"wanq090@gmail.com"},"_resolved":"/tmp/b4af66a76fee79a6558169bcd6ed28fe/aincore-sdk-0.4.1.tgz","_integrity":"sha512-fmErBucgvsPZzXAM2LRJ8X0++EQdFm/CE7qb797Xg8jQOxjxvMDN4nlDEA6Ocl3I3p0mhvslFCKxnYrWc/lE3w==","repository":{"url":"git+https://github.com/bzda404/mindvault-sdk.git","type":"git"},"_npmVersion":"10.9.8","description":"MindVault Client SDK — 将您的应用快速接入 MindVault Core 本地 AI 生态","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.6","prettier":"^3.8.3","typescript":"^5.9.3","@types/node":"^22.19.19"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.4.1_1781189146836_0.08295408207657418","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@aincore/sdk","version":"1.0.0","keywords":["aincore","ai","llm","local-ai","aincore-core","mcp","oauth","pkce"],"license":"MIT","_id":"@aincore/sdk@1.0.0","maintainers":[{"name":"bzda404","email":"wanq090@gmail.com"}],"homepage":"https://github.com/bzda404/aincore-cdk#readme","bugs":{"url":"https://github.com/bzda404/aincore-cdk/issues"},"dist":{"shasum":"9c5ce34f42af51befe40036429e4879586de65c0","tarball":"https://registry.npmjs.org/@aincore/sdk/-/sdk-1.0.0.tgz","fileCount":15,"integrity":"sha512-Kx66jNa/XOwl23RE6AYN6OSVfocRvdTBIIKWR5j8LUOw/XPphm3WW/RelkxSyx4a3yvi/jzEALWCkZek3tillQ==","signatures":[{"sig":"MEYCIQCoc0OyxoL0+OASbSoDtUq/+JsAQktHj8FZOa/GmpyZQwIhAMwfpBXhkoyxexro3woJByG7H7+iA2i+y2AjZlW0S9I4","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":53004},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"gitHead":"f9cf92bce5e41f43c906086c04090dc5a580ea36","private":false,"scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsc","format":"prettier --write .","test:watch":"vitest","prepublishOnly":"tsc"},"_npmUser":{"name":"bzda404","email":"wanq090@gmail.com"},"repository":{"url":"git+https://github.com/bzda404/aincore-cdk.git","type":"git"},"_npmVersion":"10.9.8","description":"AinCore Client SDK — 将您的应用快速接入 AinCore 本地 AI 生态","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.6","prettier":"^3.8.3","typescript":"^5.9.3","@types/node":"^22.19.19"},"_npmOperationalInternal":{"tmp":"tmp/sdk_1.0.0_1781194496448_0.470123838537045","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aincore/sdk","version":"1.1.0","description":"AinCore Client SDK — 将您的应用快速接入 AinCore 本地 AI 生态","license":"MIT","type":"module","private":false,"publishConfig":{"access":"public"},"main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"keywords":["aincore","ai","llm","local-ai","aincore-core","mcp","oauth","pkce"],"repository":{"type":"git","url":"git+https://github.com/bzda404/aincore-cdk.git"},"homepage":"https://github.com/bzda404/aincore-cdk#readme","bugs":{"url":"https://github.com/bzda404/aincore-cdk/issues"},"devDependencies":{"@types/node":"^22.19.19","prettier":"^3.8.3","typescript":"^5.9.3","vitest":"^3.2.6"},"scripts":{"build":"tsc","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit","format":"prettier --write ."},"_id":"@aincore/sdk@1.1.0","_integrity":"sha512-uEQtW6QZc6s5Xsw3Jix7GB6X3pUJV9TAR/vad1ES9xp29E664a34oKJi9TSFZGcFqhZ68uxt7noFPWXX3EghNg==","_resolved":"/tmp/e3be448752c24e86952fbd7f6d789b2c/aincore-sdk-1.1.0.tgz","_from":"file:aincore-sdk-1.1.0.tgz","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-uEQtW6QZc6s5Xsw3Jix7GB6X3pUJV9TAR/vad1ES9xp29E664a34oKJi9TSFZGcFqhZ68uxt7noFPWXX3EghNg==","shasum":"b6092f21858d5c840264cd68285101dc2f6496c7","tarball":"https://registry.npmjs.org/@aincore/sdk/-/sdk-1.1.0.tgz","fileCount":15,"unpackedSize":53811,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCL4TCZOldI0MgIBf8+krKjvI+BFwkdX4GuRblsRbXMHQIhAJKnjNlG7br27JbmIHJJfnIB4Rm4mO86vRerS2VmprUf"}]},"_npmUser":{"name":"bzda404","email":"wanq090@gmail.com"},"directories":{},"maintainers":[{"name":"bzda404","email":"wanq090@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.1.0_1781279112931_0.8768294572320701"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-11T14:45:46.546Z","modified":"2026-06-12T15:45:13.208Z","0.4.1":"2026-06-11T14:45:47.005Z","1.0.0":"2026-06-11T16:14:56.599Z","1.1.0":"2026-06-12T15:45:13.056Z"},"bugs":{"url":"https://github.com/bzda404/aincore-cdk/issues"},"license":"MIT","homepage":"https://github.com/bzda404/aincore-cdk#readme","keywords":["aincore","ai","llm","local-ai","aincore-core","mcp","oauth","pkce"],"repository":{"type":"git","url":"git+https://github.com/bzda404/aincore-cdk.git"},"description":"AinCore Client SDK — 将您的应用快速接入 AinCore 本地 AI 生态","maintainers":[{"name":"bzda404","email":"wanq090@gmail.com"}],"readme":"# @aincore/sdk\n\n> 将您的应用快速接入 AinCore 本地 AI 生态\n\n`@aincore/sdk` 是 AinCore 平台的官方 TypeScript 客户端 SDK。它为第三方开发者提供零配置的连接体验：一行代码完成 UDS 传输连接，一个方法完成 OAuth 2.0 PKCE 授权，统一的 API 封装覆盖推理、模型管理、知识库操作和用户画像等全部 17 个 JSON-RPC 方法。\n\n```bash\nnpm install @aincore/sdk\n```\n\n## 核心定位\n\n`@aincore/sdk` 在 AinCore Hub-and-Spoke 架构中充当 **Spoke 侧的桥梁**：\n\n```\n您的应用\n   │\n   │  @aincore/sdk\n   │  ├── AinCoreClient        ← 统一入口\n   │  ├── OAuthClient          ← OAuth 2.0 PKCE 封装\n   │  └── UDSTransport         ← Unix Domain Socket 传输层\n   │\n   ▼\nAinCore (Core Hub)\n   ├── llama.cpp 推理引擎\n   ├── OAuth 2.0 授权中心\n   ├── 隐私哨兵\n   └── SQLite 持久化\n```\n\n## 设计原则\n\n- **零运行时依赖** — 仅使用 Node.js 内置模块（`net` · `os` · `crypto`），无第三方运行时\n- **完整 TypeScript 类型** — 16 个导出接口，严格类型推断，`strict` 模式编译\n- **双认证兼容** — 同时支持 OAuth 2.0 PKCE（推荐）和遗留 Session Token 两种认证模式\n- **ESM 原生** — `\"type\": \"module\"`，ES2022 target，Node16 module resolution\n\n## 快速开始\n\n### 最小示例：OAuth + 推理\n\n```typescript\nimport { AinCoreClient, generatePKCE } from '@aincore/sdk'\n\nconst client = new AinCoreClient({\n  name: 'My App',\n  vendor: 'my-company',\n  icon: '🚀'\n})\n\n// 1. 发现 Core 服务\nconst discovery = await client.discover()\nif (!discovery) throw new Error('AinCore not running')\n\n// 2. OAuth 2.0 PKCE 授权\nclient.registerOAuth()\nconst { verifier, challenge } = generatePKCE()\nconst { authorizationCode } = await client.authorize(\n  'inference:read offline_access', challenge\n)\nawait client.exchangeCode(authorizationCode, verifier)\n\n// 3. 调用推理\nconst result = await client.chat({\n  messages: [{ role: 'user', content: 'Hello!' }],\n  max_tokens: 256,\n  temperature: 0.7\n})\nconsole.log(result.content)\n\nclient.disconnect()\n```\n\n### 知识库操作\n\n```typescript\n// 搜索笔记\nconst results = await client.search('机器学习笔记', 'my-kb', 10)\n\n// 读取笔记\nconst { content, metadata } = await client.readNote('/notes/ai/intro.md')\n\n// 写入笔记\nawait client.writeNote('/notes/ai/new-note.md', '# New Note\\n\\nContent here.')\n\n// 列出知识库内容\nconst notes = await client.listNotes('my-kb', true) // recursive\n```\n\n### 用户画像\n\n```typescript\n// 读取当前用户画像\nconst profile = await client.getProfile()\nconsole.log(profile.display_name, profile.language)\n\n// 更新偏好\nawait client.updateProfile({\n  communication_style: 'technical',\n  custom_instructions: '偏好代码示例和简洁回答'\n})\n```\n\n## API 参考\n\n### `AinCoreClient`\n\n统一入口类，封装传输层和认证逻辑。\n\n```typescript\nnew AinCoreClient(options: AinCoreClientOptions)\n```\n\n| 参数 | 类型 | 说明 |\n|---|---|---|\n| `name` | `string` | **必填** — 应用名称，显示在授权弹窗中 |\n| `vendor` | `string` | 应用供应商 |\n| `icon` | `string` | 应用图标（emoji 或 URL） |\n| `socketPath` | `string` | 覆盖默认 UDS 路径 |\n\n#### 发现与注册\n\n| 方法 | 返回类型 | 说明 |\n|---|---|---|\n| `discover()` | `DiscoveryResult \\| null` | 探测 Core 服务是否运行，连接失败返回 `null` |\n| `register()` | `string` | 注册应用，返回 `app_id` |\n\n#### OAuth 2.0 授权（7 个方法）\n\n| 方法 | 说明 |\n|---|---|\n| `generatePKCE()` | 生成 S256 PKCE 密钥对（`verifier` + `challenge`） |\n| `registerOAuth()` | 注册 OAuth 客户端，返回 `client_id` + `client_secret` |\n| `authorize(scopes, challenge, state?)` | 发起授权码请求，返回 `authorizationCode` |\n| `exchangeCode(code, verifier)` | 交换授权码为 Token 对（access + refresh） |\n| `refreshOAuthToken()` | 刷新 access_token（需 `offline_access` 作用域） |\n| `introspectOAuthToken(token?)` | 验证 Token 有效性 |\n| `restoreOAuthConfig(config)` / `restoreOAuthTokenSet(tokenSet)` | 从持久化存储恢复 OAuth 状态 |\n\n#### AI 推理\n\n| 方法 | 返回类型 | 说明 |\n|---|---|---|\n| `chat(params)` | `ChatResult` | 调用模型推理（OpenAI 兼容格式） |\n| `listModels()` | `ModelInfo[]` | 列出已安装模型 |\n| `getStatus()` | `CoreStatus` | 获取 Core 运行状态 |\n\n#### 知识库操作\n\n| 方法 | 说明 |\n|---|---|\n| `search(query, kb?, limit?)` | BM25 全文搜索，默认 Top-20 |\n| `readNote(path)` | 读取笔记内容与元数据 |\n| `listNotes(kb, recursive?)` | 列出知识库文件 |\n| `writeNote(path, content)` | 创建/覆盖笔记 |\n| `getContext(path, range?)` | 获取行范围上下文 |\n\n#### 用户画像\n\n| 方法 | 说明 |\n|---|---|\n| `getProfile()` | 读取用户画像（无需认证） |\n| `updateProfile(partial)` | 更新用户画像字段 |\n\n#### 生命周期\n\n| 方法 | 说明 |\n|---|---|\n| `disconnect()` | 关闭 UDS 连接 |\n\n### `OAuthClient`\n\n独立的 OAuth 2.0 子客户端，可通过 `client.oauth` 直接访问，也支持独立使用。\n\n**支持的 JSON-RPC 方法：**\n`oauth.register` · `oauth.authorize` · `oauth.token` · `oauth.revoke` · `oauth.revoke_client` · `oauth.introspect`\n\n**Token 自动续期：** `getAccessToken()` 在 Token 过期前 5 分钟自动触发 `refreshToken()`（需 `offline_access` 作用域）。\n\n### 传输层：`UDSTransport`\n\n底层 Unix Domain Socket 传输，零外部依赖：\n\n| 特性 | 实现 |\n|---|---|\n| **Socket 路径** | macOS/Linux: `/tmp/aincore.sock` · Windows: `\\\\.\\pipe\\aincore` |\n| **消息帧** | 换行分隔 JSON（`\\n` delimiter） |\n| **请求 ID** | 单调递增整数，支持并发多路复用 |\n| **连接管理** | `call()` 方法懒重连（断开后下次调用自动重连） |\n| **关闭语义** | socket 关闭时 reject 所有 pending Promise |\n\n### 类型定义\n\n16 个导出接口覆盖所有 API 交互：\n\n```typescript\n// 客户端配置\nAinCoreClientOptions\n\n// 认证\nAuthRequest · AuthResult · DiscoveryResult · KnowledgeBaseGrant · KnowledgeBaseAuthRequest\n\n// 推理\nChatParams · ChatResult · ModelInfo · CoreStatus\n\n// 知识库\nSearchResult · NoteListItem · NoteContext\n\n// 用户画像\nUserProfile\n\n// OAuth（来自 OAuthClient）\nOAuthClientConfig · OAuthTokenSet · OAuthIntrospection\n```\n\n## 支持的 JSON-RPC 方法\n\nSDK 封装了以下 17 个 AinCore JSON-RPC 方法：\n\n| 类别 | 方法 | SDK 调用 |\n|---|---|---|\n| 发现 | `app.ping` | `discover()` |\n| 注册 | `app.register` | `register()` |\n| OAuth | `oauth.register` · `authorize` · `token` · `revoke` · `revoke_client` · `introspect` | `registerOAuth()` · `authorize()` · `exchangeCode()` · `refreshOAuthToken()` · `revokeToken()` · `revokeClient()` · `introspectOAuthToken()` |\n| 遗留认证 | `app.request_auth` · `app.list_grants` · `app.revoke_auth` | `requestAuth()` · `listGrants()` · `revokeAuth()` |\n| 推理 | `chat.completions` | `chat()` |\n| 模型 | `models.list` · `app.list_models` | `listModels()` |\n| 状态 | `status` | `getStatus()` |\n| 知识库 | `search_notes` · `read_note` · `list_notes` · `write_note` · `get_context` | `search()` · `readNote()` · `listNotes()` · `writeNote()` · `getContext()` |\n| 画像 | `profile.get` · `profile.update` | `getProfile()` · `updateProfile()` |\n\n## 授权作用域\n\n| 作用域 | 说明 |\n|---|---|\n| `inference:read` | 调用模型推理 |\n| `models:read` | 列出已安装模型 |\n| `models:manage` | 加载/卸载模型 |\n| `knowledge:read` | 读取知识库 |\n| `knowledge:write` | 写入知识库（隐含 `knowledge:read`） |\n| `system:status` | 读取系统状态 |\n| `offline_access` | 允许 refresh_token（长期访问） |\n\n## 技术规格\n\n| 项目 | 规格 |\n|---|---|\n| 运行时依赖 | **零**（仅 Node.js 内置模块） |\n| 语言 | TypeScript 5.9 (strict) |\n| 编译目标 | ES2022 · Node16 module |\n| 模块格式 | ESM（`\"type\": \"module\"`） |\n| 测试 | Vitest（16 个单元测试） |\n| 包大小 | 13.6 kB (tgz) · 51.6 kB (unpacked) |\n| 发布文件 | `dist/` + `README.md` |\n\n## 开发\n\n```bash\ngit clone https://github.com/bzda404/aincore-cdk.git\ncd aincore-cdk\npnpm install\npnpm build          # tsc 编译\npnpm test           # 运行 16 个单元测试\npnpm lint           # 类型检查\n```\n\n## 生态\n\n| 项目 | 说明 |\n|---|---|\n| [AinCore](https://github.com/bzda404/aincore) | 本地 AI 算力平台核心枢纽（llama.cpp 推理 + OAuth 授权 + 隐私哨兵） |\n| [AinCore Notes](https://github.com/bzda404/aincore-notes) | AI 知识管理应用（Markdown 编辑器 + MCP 协议 + 隐私拦截器） |\n\n## 许可证\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}