# AGENTS.md

## 构建、代码检查和测试命令

### 核心命令

```bash
# 开发
bun run dev                           # 运行主入口 (src/run.ts)
bun run dev:server                    # 启动服务器（热重载）
bun run dev:cnb                       # 使用自定义配置目录启动服务器
bun run dev:share                     # 测试远程应用

# 构建
bun run build                         # 完整生产构建（先清理 dist）
bun run build:lib                     # 构建库文件
bun run postbuild:lib                 # 生成 TypeScript 类型定义

# 包管理
pnpm install                          # 安装依赖（使用 pnpm v10.28.0）
```

### 环境要求

- **Node.js**: >=22.0.0
- **运行时**: Bun（开发环境）/ Node.js（生产环境）
- **包管理器**: pnpm@10.28.0（强制要求）

### 环境变量

- `ASSISTANT_CONFIG_DIR`: 覆盖助手配置文件目录路径
- `BUN_PATH`: 覆盖 Bun 可执行文件路径

---

## 代码风格规范

### TypeScript

- **严格模式**: 通过扩展配置启用（`@kevisual/types/json/backend.json`）
- **模块格式**: 仅 ESM（`package.json` 中的 `"type": "module"`）
- **目标**: NodeNext 模块解析
- **路径别名**: 使用 `@/*` 作为本地导入别名（如 `import { Foo } from '@/module/foo'`）

### 导入规则

```typescript
// Node.js 内置模块必须使用 node: 协议
import fs from 'node:fs';
import path from 'node:path';
import { execSync } from 'node:child_process';

// 外部包（不使用路径别名）
import chalk from 'chalk';
import { program } from 'commander';

// 本地模块（使用 @ 别名）
import { AssistantInit } from '@/services/init/index.ts';

// 类型导入
import type { AssistantConfig } from '@/module/assistant/index.ts';
```

### 命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| 类 | PascalCase | `AssistantInit`, `AssistantApp`, `AssistantQuery` |
| 接口 | PascalCase | `ProxyInfo`, `AssistantInitOptions` |
| 类型 | PascalCase | `AssistantConfigData` |
| 函数 | camelCase | `getBunPath`, `checkFileExists`, `parseHomeArg` |
| 变量 | camelCase | `configDir`, `assistantConfig`, `isPortAvailable` |
| 私有字段 | `#` 前缀 + camelCase | `#query`, `#config` |
| 常量 | UPPER_SNAKE_CASE 或 camelCase | `commonPaths`, `randomId` |
| 文件名 | kebab-case | `proxy-page-index.ts`, `query-login.ts` |
| 目录名 | kebab-case | `query-login`, `hot-api` |

### 代码模式

#### 错误处理

```typescript
// 同步操作包装
try {
  const result = fs.readFileSync(path);
  return result;
} catch (error) {
  console.error('读取文件错误:', error.message);
  continue; // 或 return/throw
}

// 异步操作包装
try {
  const result = await someAsyncOperation();
  return result;
} catch (error) {
  console.error('操作失败:', error.message);
  process.exit(1); // 或 throw/return undefined
}
```

#### 上下文/依赖注入

使用 `@kevisual/use-config` 进行上下文管理：

```typescript
export const assistantConfig = useContextKey<AssistantInit>('assistantConfig', () => {
  return new AssistantInit({
    path: configDir,
    init: isInit,
  });
});
```

#### 路由模式

使用 `@kevisual/router` 的 App 和 SimpleRouter：

```typescript
app.route({
  path: 'router',
  key: 'list',
  description: '获取路由列表',
}).define(async (ctx) => {
  ctx.body = { list };
}).addTo(app);
```

### JSDoc 文档

为公共 API、复杂函数和类型添加文档：

```typescript
/**
 * 助手初始化类
 * @class AssistantInit
 */
export class AssistantInit extends AssistantConfig {}

/**
 * @param {string} p - 要解析的路径
 * @returns {string} 解析后的绝对路径
 */
export const w = (p: string) => path.join(__dirname, p);
```

### 文件组织

- **路由**: `src/routes/` 和 `src/routes-simple/`
- **模块**: `src/module/`（功能模块）
- **服务**: `src/services/`（公共服务）
- **命令**: `src/command/`（CLI 命令）
- **查询**: `src/query/`（API/查询逻辑）
- **入口文件**:
  - `src/index.ts` - 主 CLI 入口
  - `src/server.ts` - 服务器入口
  - `src/run.ts` - 开发运行器
  - `src/run-server.ts` - 服务器运行器

### 控制台输出

使用 `chalk` 实现彩色输出：

```typescript
console.log(chalk.blue('助手路径不存在，正在创建...'));
console.log(chalk.yellow('助手路径已存在'), chalk.green(assistantConfig.configDir));
console.error(chalk.red('启动服务器错误:'), error.message);
```

### 系统检测

```typescript
const isWindows = process.platform === 'win32';
const bunExecutableName = isWindows ? 'bun.exe' : 'bun';
```

### 端口处理

```typescript
import getPort, { portNumbers } from 'get-port';

const port = await getPort({ port: 51515 });
const availablePort = await getPort({ port: portNumbers(51515, 52000) });
```

### 关键依赖

- `@kevisual/router` - 应用路由
- `@kevisual/query` - API 查询
- `@kevisual/use-config` - 配置/上下文
- `commander` - CLI 参数解析
- `chalk` - 终端颜色
- `ws` - WebSocket（通过 `@kevisual/ws`）
- `pm2` - 进程管理（生产环境）

### 重要说明

1. 开发时始终使用 `bun`，但构建输出以 Node.js 为目标
2. 打包时外部包必须在 `bun.config.mjs` 的 `external` 数组中声明
3. 库构建排除 `pm2`
4. 以 `ENVISION_*` 为前缀的环境变量在构建时可用
5. 项目在业务逻辑中广泛使用中文注释
6. 私有类成员应使用 `#` 前缀语法
7. 操作前始终使用 `checkFileExists` 检查文件是否存在