# @eddydesk/core 中文文档

规范地址：https://npmcn.com/package/%40eddydesk/core/

版本：0\.13\.4
npm 元数据更新时间：2026-09-16T15:05:09.222Z
中文译文更新时间：2026-11-13T06:25:54.892Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eddydesk/core
原文对照：https://npmcn.com/package/%40eddydesk/core/?lang=original
项目主页：https://github.com/Bear-Eddy/eddydesk#readme
源码仓库：https://github.com/Bear-Eddy/eddydesk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：477 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-04-30T19:16:20.034Z
- 最新版本发布：2026-09-16T15:05:08.995Z
- 近 30 天下载量：4603（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

EddyDesk QA平台的核心公用事业和类型

## 安装

```sh
npm install @eddydesk/core
```

也可以使用：`pnpm add @eddydesk/core`、`yarn add @eddydesk/core`、`bun add @eddydesk/core`

## README

# @ eddydesk/ 核心

EddyDesk QA平台的核心客户端和公用事业.

> **说明:** 大多数用户应安装 `@eddydesk/react` 或者说 `@eddydesk/react-native` 而不是自动包含此软件包.

## 安装

```bash
npm install @eddydesk/core
```

## 使用量

```typescript
import { createEddyDesk } from '@eddydesk/core';

const eddydesk = createEddyDesk({
  projectId: 'your-project-id',
  getCurrentUser: async () => ({
    id: 'user-123',
    email: 'user@example.com',
    name: 'Jane Doe', // Optional, used for reporter identity
  }),
});

// Submit a report
await eddydesk.submitReport({
  type: 'bug',
  description: 'Button does not work',
  severity: 'high',
  appContext: { currentRoute: '/dashboard' },
});

// Check if user is a tester
const isTester = await eddydesk.isTester();

// Get assigned test cases
const assignments = await eddydesk.getAssignedTests();
```

## 配置

```typescript
interface EddyDeskConfig {
  // Required
  projectId: string;
  getCurrentUser: () => Promise<{ id: string; email: string; name?: string } | null>;

  // Optional — context
  getAppContext?: () => AppContext;          // Rich app context (userRole, etc.)
  getNavigationHistory?: () => string[];    // Custom navigation tracking

  // Optional — callbacks
  onReportSubmitted?: (report: EddyDeskReport) => void;
  onNavigate?: (route: string) => void;     // Deep linking from test cases

  // Optional — self-hosted
  supabaseUrl?: string;
  supabaseAnonKey?: string;
}
```

### 附录

提供 `getAppContext` 在每份错误报告中附加丰富的上下文。 这有助于开发者修复错误 理解用户的状态 :

```typescript
const eddydesk = createEddyDesk({
  projectId: 'your-project-id',
  getCurrentUser: async () => ({ id: user.id, email: user.email }),
  getAppContext: () => ({
    currentRoute: window.location.pathname,
    userRole: currentUser?.role,       // e.g. 'owner', 'manager', 'guest'
    propertyId: currentProperty?.id,   // App-specific context
    custom: {                          // Any additional context
      theme: 'dark',
      locale: 'en-US',
    },
  }),
});
```

## 自动上下文抓取

EddyDesk 初始化时自动抓取调试上下文 `EddyDeskProvider` (反应或反应原生). 不需要手动设置 .

**自动捕获的东西:**

| 数据 | 细节 |
| --- | --- |
| **控制台日志** | 倒数 50 `console.log/warn/error/info` 电话 |
| **网络请求** | 最后20个 `fetch()` 有方法、 URL、 状态、 持续时间的呼叫 |
| **失败的应对机构** | 4xx/5xxx错误的首500个响应对象字符 |
| **导航历史** | 最后20条路由变化(通过) `pushState`编号 :`replaceState`编号 :`popstate`(中文(简体) ) |
| **业绩计量** | 页面加载时间、内存使用( Chrome) |
| **环境** | 语言、时区、在线状态、饼干、本地Storage |

此数据作为附件附于每份错误报告 `enhanced_context` 并可供 MCP 服务器使用 `get_report_context` 工具.

### 手动抓取(框架作者)

如果你没有用 `EddyDeskProvider`,手动开始抓取 :

```typescript
import { contextCapture } from '@eddydesk/core';

// Start capturing (call once at app init)
contextCapture.startCapture();

// For React Native: manually track screen changes
contextCapture.trackNavigation('/home');
contextCapture.trackNavigation('/settings');

// Get captured data (automatically included in submitReport)
const context = contextCapture.getEnhancedContext();
```

## 客户方法

| 方法 | 说明 |
| --- | --- |
| `submitReport(report)` | 提交错误报告、反馈或测试结果 |
| `isTester()` | 检查当前用户是否是注册测试器 |
| `isQAEnabled()` | 检查工程是否启用 QA 模式 |
| `shouldShowWidget()` | 检查部件是否可见( QA 启用 + 是测试器) |
| `getTesterInfo()` | 获取当前测试者的信息 |
| `getAssignedTests()` | 获取指定给当前测试器的测试例 |
| `getAppContext()` | 获取当前应用程序上下文( 使用配置回调或自动抓取) |
| `getNavigationHistory()` | 获取导航历史( 配置调回 > 手动 > 自动抓取) |
| `trackNavigation(route)` | 手动跟踪路由更改 |
| `getIssueCounts()` | 按类别进行问题清点( 打开、 完成、 重新打开) |
| `getIssues(category)` | 以校验证明和原始错误上下文来丰富问题列表 |
| `uploadScreenshot(file)` | 上传截图 |

## 类型

```typescript
interface EddyDeskReport {
  type: 'bug' | 'feedback' | 'suggestion' | 'test_pass' | 'test_fail';
  description: string;
  title?: string;
  severity?: 'critical' | 'high' | 'medium' | 'low';
  screenshots?: string[];
  appContext?: AppContext;
  enhancedContext?: EnhancedBugContext;
}

interface AppContext {
  currentRoute: string;
  screenName?: string;
  userRole?: string;
  propertyId?: string;
  custom?: Record<string, unknown>;
}

interface TesterInfo {
  id: string;
  name: string;
  email: string;
  assignedTests: number;
  completedTests: number;
}

interface TestAssignment {
  id: string;
  status: string;
  testCase: {
    id: string;
    title: string;
    description: string;
    steps: TestStep[];
    expectedResult: string;
    priority: string;
  };
}

type IssueCategory = 'open' | 'done' | 'reopened';

interface IssueCounts {
  open: number;
  done: number;
  reopened: number;
}

interface TesterIssue {
  id: string;
  title: string;
  description: string;
  reportType: ReportType;
  severity: Severity | null;
  status: ReportStatus;
  screenshotUrls: string[];
  route?: string;
  reporterName?: string;
  createdAt: string;
  updatedAt: string;
  verifiedByName?: string;   // Who retested (done issues)
  verifiedAt?: string;       // When verification passed (done issues)
  originalBugId?: string;    // Original report ID (reopened issues)
  originalBugTitle?: string; // Original bug title (reopened issues)
}
```

## 问题跟踪

SDK为测试者提供了跟踪其bug生命周期的方法:

```typescript
// Get counts for issue cards (open, done, reopened)
const counts = await eddydesk.getIssueCounts();
// { open: 3, done: 12, reopened: 1 }

// Get enriched issue list by category
const openIssues = await eddydesk.getIssues('open');
const doneIssues = await eddydesk.getIssues('done');
const reopenedIssues = await eddydesk.getIssues('reopened');

// Done issues include verification proof
doneIssues[0].verifiedByName;  // "Jane Doe"
doneIssues[0].verifiedAt;      // "2026-02-05T12:00:00Z"

// Reopened issues include original bug context
reopenedIssues[0].originalBugTitle;  // "Login button unresponsive"
reopenedIssues[0].originalBugId;     // "uuid-of-original-report"
```

## 对于框架作者

如果您正在为不同的框架(Vue, Svelte等)构建一个 EddyDesk 集成, 请使用此包作为基础 :

```typescript
import { EddyDeskClient, createEddyDesk, contextCapture, EddyDeskConfig } from '@eddydesk/core';

// Start context capture at app init
contextCapture.startCapture();

// Create your framework-specific wrapper around the client
const client = createEddyDesk(config);
```

## 常见问题

### @eddydesk/core 是什么？

EddyDesk QA平台的核心公用事业和类型

### 如何安装 @eddydesk/core？

在项目目录运行 npm install @eddydesk/core，或使用 pnpm add / yarn add / bun add。

### @eddydesk/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @eddydesk/core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @eddydesk/core 可以商用吗？

@eddydesk/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eddydesk/core 的下载量有多少？

根据 npm 官方下载统计，@eddydesk/core 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,603 次，日均约 153 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eddydesk/core 还在维护吗？

最新版本 0\.13\.4 发布于 2026/09/16（1 个月前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/05/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。