Monako AI Atlas

面向 PPT 主题深搜和投研内容生产的 TypeScript SDK。项目包含两部分：

• src/: 可通过 tsup 打包发布到 NPM 的 SDK
• demo/ + scripts/demo-server.ts: 用 Vite + React 展示流式运行效果的本地演示页

能力链路

1. 初始化 SDK，注入博查与 LLM 配置
2. 用户提交主题
3. SDK 调用博查 web-search，拿到网页数组与摘要
4. 按网页数量启动并发 Agent，抓取页面正文并做主题摘要
5. 把所有 Agent 摘要在内存中合并
6. 将合并结果和博查摘要交给 LLM，经 pi-ai provider 生成最终投研报告
7. 以事件流形式把阶段进度、网页摘要和最终报告持续返回给上层应用

环境变量

在仓库根目录准备 .env。

DashScope / Qwen

BOCHA_API_KEY=...
DASHSCOPE_API_KEY=...
LLM_PROVIDER=dashscope
LLM_MODEL=qwen3.6-plus
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
ENABLE_RUN_LOGGING=true
RUN_STORE_DIR=.runs

也可以不用 DASHSCOPE_API_KEY，改为统一写法：

BOCHA_API_KEY=...
LLM_API_KEY=...
LLM_PROVIDER=dashscope
LLM_MODEL=qwen3.6-plus
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

MiniMax

BOCHA_API_KEY=...
LLM_API_KEY=...
LLM_PROVIDER=minimax-cn
LLM_MODEL=MiniMax-M2.7

说明：

• atlasConfigFromEnv() 当前要求存在 BOCHA_API_KEY
• DashScope 场景下，LLM_API_KEY 和 DASHSCOPE_API_KEY 二选一即可
• LLM_PROVIDER 可选；SDK 会根据 LLM_BASE_URL 或 LLM_MODEL 自动推断
• LLM_BASE_URL 在 DashScope 场景建议显式填写
• ENABLE_RUN_LOGGING=true 时，每次运行会把事件流和最终结果写到 RUN_STORE_DIR

初始化方式

1. 通过 .env 初始化

推荐服务端直接使用 atlasConfigFromEnv()：

import { MonakoAtlasSdk, atlasConfigFromEnv } from 'monako-ai-atlas';

const sdk = new MonakoAtlasSdk(atlasConfigFromEnv(process.env));

2. 手动初始化 DashScope / Qwen

import { MonakoAtlasSdk } from 'monako-ai-atlas';

const sdk = new MonakoAtlasSdk({
  bochaApiKey: process.env.BOCHA_API_KEY!,
  llmApiKey: process.env.LLM_API_KEY!,
  llmProvider: 'dashscope',
  llmModel: 'qwen3.6-plus',
  llmBaseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1'
});

3. 手动初始化 MiniMax

import { MonakoAtlasSdk } from 'monako-ai-atlas';

const sdk = new MonakoAtlasSdk({
  bochaApiKey: process.env.BOCHA_API_KEY!,
  llmApiKey: process.env.LLM_API_KEY!,
  llmProvider: 'minimax-cn',
  llmModel: 'MiniMax-M2.7'
});

当前 MonakoAtlasSdk 的最小必填项：

• bochaApiKey
• llmApiKey
• llmModel

代码使用方法

1. 流式研究

适合前端展示阶段进度和流式报告输出：

import { MonakoAtlasSdk, atlasConfigFromEnv } from 'monako-ai-atlas';

const sdk = new MonakoAtlasSdk(atlasConfigFromEnv(process.env));

for await (const event of sdk.researchStream('中国具身智能机器人产业链未来18个月的投资机会', {
  count: 4,
  maxSources: 4,
  agentConcurrency: 3
})) {
  if (event.type === 'stage') {
    console.log(`[${event.stage}] ${event.status}: ${event.message}`);
  }

  if (event.type === 'search_result') {
    console.log(event.bocha.summary);
  }

  if (event.type === 'report_delta') {
    process.stdout.write(event.delta);
  }

  if (event.type === 'done') {
    console.log('\n研究完成');
    console.log(event.result.report);
  }

  if (event.type === 'error') {
    throw new Error(event.message);
  }
}

2. 非流式研究

适合后端一次性拿完整结果：

import { MonakoAtlasSdk, atlasConfigFromEnv } from 'monako-ai-atlas';

const sdk = new MonakoAtlasSdk(atlasConfigFromEnv(process.env));

const result = await sdk.research('中国具身智能机器人产业链未来18个月的投资机会', {
  count: 4,
  maxSources: 4,
  agentConcurrency: 3
});

console.log(result.report);
console.log(result.bocha.summary);
console.log(result.agentSummaries.length);

3. 获取运行时配置

const descriptor = sdk.runtimeDescriptor();

console.log(descriptor.llmProvider);
console.log(descriptor.llmModel);
console.log(descriptor.bochaBaseUrl);

4. 依赖注入

适合测试、mock 或自定义抓取/搜索实现：

import { MonakoAtlasSdk } from 'monako-ai-atlas';

const sdk = new MonakoAtlasSdk(
  {
    bochaApiKey: 'bocha',
    llmApiKey: 'dashscope',
    llmModel: 'qwen3.6-plus'
  },
  {
    fetchFn: fetch,
    llmProvider: myCustomLlmProvider,
    searchClient: mySearchClient,
    pageReader: myPageReader
  }
);

开发命令

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm dev:demo
pnpm test:live

默认端口：

• Demo UI: http://localhost:5173
• Demo Server: http://localhost:3030

测试说明

• pnpm test: 单元测试，覆盖 Bocha 结果兼容、网页正文抽取、事件流编排、降级路径
• pnpm test:live: 使用当前 .env 做真实端到端 smoke test
• pnpm test:prepublish: 从 dist 产物导入 SDK，执行发布前的初始化、普通调用、流式调用检查
• pnpm release:check: 执行类型检查、单测、预发布检查和 pack --dry-run

版本发布流程

推荐在发布 NPM 前按下面顺序执行：

pnpm release:check
pnpm release:patch   # 或 release:minor / release:major
git push origin main
git push origin --tags

如果要创建 GitHub Release，常见做法是：

gh auth login
gh release create v0.1.1 --title "v0.1.1" --notes "Release v0.1.1"

确认已经登录 npm：

npm whoami

最后执行发布：

pnpm publish:npm

补充说明：

• npm version patch/minor/major 会同时更新 package.json、创建 commit 和 tag
• 发布前务必确认 .env 没有被提交，pnpm pack --dry-run 的打包清单符合预期

实现说明

• 博查当前实测的 web-search 返回并不总是包含顶层 summary 字段，所以 SDK 做了兼容
• LLM 统一走 PiAiLlmProvider
• DashScope/Qwen 通过 pi-ai 的 OpenAI-compatible provider 调用
• MiniMax 通过同一套 LLM_* 配置接入
• 前端 demo 不直接调用 SDK，也不持有任何密钥；所有真实请求都在本地 demo-server 中完成