---

name: add-core-function description: 向 Catalyst-Relay 添加核心业务逻辑功能。适用于创建纯函数、ADT操作或可供库使用的代码。

添加核心功能

何时使用

• 创建新的 ADT 操作（CRAUD、发现、预览）
• 添加纯业务逻辑函数
• 实现可供库使用的功能

一个文件一个函数

每个核心功能都有自己的文件。不要创建多函数文件。

位置： src/core/{domain}/{function}.ts

core/adt/
├── index.ts              # 桶导出文件
├── types.ts              # 共享类型（AdtRequestor, ObjectConfig）
├── helpers.ts            # 内部辅助函数（不从桶中导出）
│
├── craud/
│   ├── read.ts           → readObject()
│   ├── create.ts         → createObject()
│   └── ...
│
└── discovery/
    ├── packages.ts       → getPackages()
    └── ...

导入层次结构

文件必须遵循此层次结构（无循环依赖）：

types.ts           （共享类型，不从包中导入）
    ↓
helpers.ts         （内部工具，导入类型）
    ↓
子文件夹文件        （导入 ../types 和 ../helpers）
    ↓
index.ts           （桶导出文件，从子文件夹导入）

相对路径模式：

• ../types — 共享类型
• ../helpers — 共享辅助函数
• ../../utils/xml — 核心工具
• ../../../types/result — 全局类型

函数文件模式

// src/core/adt/discovery/packages.ts

import type { AdtRequestor } from '../types';
import type { AsyncResult } from '../../../types/result';

export interface Package {
    name: string;
    description: string;
}

export async function getPackages(
    requestor: AdtRequestor,
    filter?: string
): AsyncResult<Package[]> {
    // 实现
    const response = await requestor.get('/packages', { params: { filter } });

    if (response.error) {
        return [null, response.error];
    }

    return [parsePackages(response.data), null];
}

// 内部辅助函数（不导出）
function parsePackages(xml: string): Package[] {
    // ...
}

返回类型约定

使用 Go 风格的错误元组：

import type { AsyncResult } from '../../../types/result';

// 成功时返回 [data, null]，失败时返回 [null, error]
export async function someOperation(): AsyncResult<Data> {
    // ...
}

桶导出

添加到 index.ts 作为公共 API：

// src/core/adt/index.ts

// 类型
export type { AdtRequestor, ObjectConfig } from './types';

// 发现
export { getPackages } from './discovery/packages';
export { getTree } from './discovery/tree';

// CRAUD
export { readObject } from './craud/read';
export { createObject } from './craud/create';

内部辅助函数

不从桶中导出的辅助函数放在 helpers.ts 中：

// src/core/adt/helpers.ts

import type { AdtRequestor } from './types';

// 内部函数 - 不从 index.ts 导出
export function buildObjectUri(name: string, extension: string): string {
    // ...
}

检查清单

- [ ] 在 src/core/{domain}/{subfolder}/ 中创建函数文件
- [ ] 在文件顶部或 ../types.ts 中定义类型
- [ ] 异步函数使用 AsyncResult 返回类型
- [ ] 遵循导入层次结构（无循环依赖）
- [ ] 如果是公共 API，则从 index.ts 导出
- [ ] 将内部辅助函数放在 helpers.ts 中
- [ ] 运行类型检查：bun run typecheck