名称： endpoints
描述： "Endpoints 文档管理 API 工具包。利用 AI 提取扫描文档，并将结构化数据整理到分类的端点中。当用户要求进行以下操作时使用：扫描文档、上传文件、列出端点、查看端点数据、检查使用统计、创建或删除端点、获取文件 URL，或管理文档元数据。需要来自 endpoints.work 仪表板的 ENDPOINTS_API_KEY。"

Endpoints API 工具包

设置

安装依赖：

cd scripts && npm install

在项目根目录创建 .env 文件以配置凭证：

ENDPOINTS_API_URL=https://endpoints.work
ENDPOINTS_API_KEY=ep_your_api_key_here

前提条件：需要一个 Endpoints 账户及其 API 密钥。请从 API 密钥页面 生成您的密钥。

快速开始

通过从 scripts/src/index.ts 导入来执行函数：

import { listEndpoints, scanText, getStats } from './scripts/src/index.js';

const categories = await listEndpoints();
const result = await scanText('Meeting with John about Q1 goals', 'meeting tracker');
const stats = await getStats();

或者使用 tsx 直接运行：

npx tsx scripts/src/index.ts

工作流程模式

每次分析都遵循三个阶段：

1. 分析

运行 API 函数。每次调用都会访问 Endpoints API 并返回结构化数据。

2. 自动保存

所有结果都会自动保存为 JSON 文件到 results/{category}/ 目录。文件命名模式：
- 有名称的结果：{sanitized_name}.json
- 自动生成的结果：YYYYMMDD_HHMMSS__{operation}.json

3. 总结

分析完成后，读取保存的 JSON 文件并在 results/summaries/ 目录中创建 Markdown 总结，包含数据表、见解和提取的实体。

高级函数

独立 API 函数

如需精细控制，可导入特定函数。完整列表（包含参数、类型和示例）请参阅 references/api-reference.md。

端点函数

扫描函数

条目函数

文件函数

计费函数

数据结构

动态 JSON 模式

端点使用动态 JSON 模式来记录文档历史：

{
  endpoint: { path, category, slug },
  metadata: {
    oldMetadata: { ... },  // 历史条目
    newMetadata: { ... }   // 近期条目
  }
}

元数据条目

每个条目包含：
- 8 字符 ID - 唯一标识符（例如 abc12345）
- summary - AI 生成的描述
- entities - 提取的实体（人员、公司、日期等）
- filePath - 如果上传了文件，则为 S3 URL
- fileType - MIME 类型
- originalText - 源文本

错误处理

示例

列出与查看

// 获取所有端点
const { categories } = await listEndpoints();
console.log(`找到 ${categories.length} 个类别`);

// 查看特定端点
const details = await getEndpoint('/job-tracker/january');
console.log(`总条目数：${details.totalItems}`);

扫描文档

// 扫描文本内容
const result = await scanText(
  '来自 Acme Corp 的 John Smith 关于 Q1 合同续签的邮件',
  'business contacts'
);
console.log(`创建的端点：${result.endpoint.path}`);

// 扫描 PDF 文件
const fileResult = await scanFile('./invoice.pdf', 'invoice tracker');
console.log(`提取了 ${fileResult.entriesAdded} 个条目`);

检查使用情况

const stats = await getStats();
console.log(`解析次数：${stats.parsesUsed}/${stats.parsesLimit}`);
console.log(`存储空间：${stats.storageUsed} 字节`);