open-index/open-npm huggingface dataset:
npm package: @lark-apaas/miaoda-data-cli
Description: 妙搭平台数据 CLI 工具
Latest version: 0.1.4

# miaoda-data-cli

妙搭平台数据 CLI 工具，支持 `db sql`（执行 SQL）和 `db schema`（查看表结构/DDL）。

## 使用方式

```bash
npx -y miaoda-data-cli db sql "SELECT 1"
npx -y miaoda-data-cli db schema
```

## 目录说明

本包仅包含 npm 分发文件（`package.json` + `bin/cli.js` + 编译后的二进制）。

Go 源码在 [apaas/paas-cli](https://code.byted.org/apaas/paas-cli) 仓库的 `miaoda/datapaas-cli/` 目录维护。

## 构建与发布

```bash
# 1. 编译 Go 二进制（需要本地有 paas-cli 仓库）
bash build.sh

# 2. 发布到 npm
cd . && npm publish
```
npm package: @lark-apaas/nestjs-authnpaas
Description: FullStack Nestjs authnpaas
Latest version: 1.0.3

# nestjs-authnpaas

`nestjs-authnpaas` 是一个轻量级的 NestJS 模块，用于处理身份验证检查。它提供了一个全局守卫，以确保用户在访问端点之前已经登录。

## 目录

- [功能](#功能)
- [安装](#安装)
- [快速开始](#快速开始)
- [装饰器](#装饰器)
  - [@NeedLogin()](#needlogin)
- [服务](#服务)
  - [AuthNPaasService](#authnpaasservice)
- [工作原理](#工作原理)

## 功能

- **身份验证检查**: 确保用户在访问受保护端点之前已经登录。
- **登录重定向**: 自动将未经身份验证的用户重定向到登录 URL。
- **用户 ID 转换**: 支持妙搭用户 ID 与飞书用户 ID 互转。

## 安装

```bash
npm install @lark-apaas/nestjs-authnpaas
# 或者
yarn add @lark-apaas/nestjs-authnpaas
```

## 快速开始

在您的根模块 `app.module.ts` 中导入并配置 `AuthNPaasModule`。

```typescript
import { Module } from '@nestjs/common';
import { AuthNPaasModule } from '@lark-apaas/nestjs-authnpaas';

@Module({
  imports: [
    AuthNPaasModule.forRoot(),
  ],
  controllers: [/* ... */],
  providers: [/* ... */],
})
export class AppModule {}
```


## 装饰器

### @NeedLogin()

使用 `@NeedLogin()` 装饰器在特定端点上强制执行身份验证。

#### 控制器级别

```typescript
import { Controller, Get } from '@nestjs/common';
import { NeedLogin } from '@lark-apaas/nestjs-authnpaas';

@Controller('dashboard')
@NeedLogin() // 此控制器中的所有路由都需要登录
export class DashboardController {
  @Get()
  getDashboard() {
    return '您的个人仪表板';
  }
}
```

#### 方法级别

```typescript
import { Controller, Get } from '@nestjs/common';
import { NeedLogin } from '@lark-apaas/nestjs-authnpaas';

@Controller('api')
export class ApiController {
  @Get('public-data')
  getPublicData() {
    // 此端点不需要身份验证
    return '一些公共数据';
  }

  @Get('private-data')
  @NeedLogin() // 此端点需要身份验证
  getPrivateData() {
    return '一些秘密数据';
  }
}
```

## 服务

### AuthNPaasService

`AuthNPaasService` 提供妙搭用户 ID 与飞书用户 ID 的转换能力。模块注册后即可通过依赖注入使用。

```typescript
import { Injectable } from '@nestjs/common';
import { AuthNPaasService } from '@lark-apaas/nestjs-authnpaas';

@Injectable()
export class MyService {
  constructor(private readonly authn: AuthNPaasService) {}

  async example() {
    // 获取当前登录用户的飞书 user_id
    const larkUserId = await this.authn.getCurrentUserLarkUserId();
    // => 'xxx' | null

    // 批量转换妙搭 userId → 飞书 user_id（最多 100 个）
    const larkUserIds = await this.authn.getBatchLarkUserIds(['uid1', 'uid2']);
    // => ['lark_id_1', 'lark_id_2']  顺序与输入对应，找不到的为 null
  }
}
```

#### getCurrentUserLarkUserId

从请求上下文获取当前妙搭 userId，调用平台接口转换为飞书 user_id。

- **返回值**: `Promise<string | null>` — 飞书 user_id，未登录或转换失败返回 `null`

#### getBatchLarkUserIds

批量将妙搭 userId 转换为飞书 user_id。

- **参数**: `userIds: string[]` — 妙搭用户 ID 列表，最多 100 个
- **返回值**: `Promise<(string | null)[]>` — 飞书 user_id 数组，与输入顺序一一对应，转换失败的项为 `null`
- **异常**: 当 `userIds` 超过 100 个时抛出错误

## 工作原理

### AuthNPaasGuard

此模块将 `AuthNPaasGuard` 注册为全局守卫。在每个传入的请求上，守卫会执行以下步骤：

1. **检查 `@NeedLogin()`**: 它首先检查端点是否需要登录。
2. **确认身份验证状态**: 如果端点需要登录，守卫会确认 `request.userContext` 对象上的 `userId` 是否存在。
3. **如果未通过身份验证则重定向**: 如果端点标有 `@NeedLogin()` 且缺少 `userId`，它会将用户重定向到 `request.userContext` 上的 `loginUrl`。
npm package: @lark-apaas/observable
Description: Observable SDK
Latest version: 1.0.6

# @lark-apaas/observable

`@lark-apaas/observable` 是一个面向服务端的链路追踪与日志观测 SDK。它基于 OpenTelemetry 构建，为 Monorepo 中的 Node.js 应用提供统一的、具备上下文感知的可观测性能力。

---

## 1. Project Context (项目背景与定位)

- **Architectural Role**: **Core Infrastructure** - 位于系统底层，作为服务端可观测性的基础库，屏蔽了 OpenTelemetry 的复杂配置。
- **Key Consumers (谁在用我)**:
    - 📦 `@lark-apaas/nestjs-observable`: NestJS 框架集成层，将其封装为 NestJS 模块和拦截器。
- **Core Dependencies (我依赖谁)**:
    - 🛠️ `OpenTelemetry APIs & SDKs`: 提供核心的 Trace 和 Logs 处理能力。
    - 🔗 `rxjs`: 用于处理流式数据的生命周期管理（如 Span 的自动结束）。

---

## 2. Real-world Scenarios (基于真实挖掘)

### Scenario A: The Standard Usage (Middleware 自动开启上下文)
这是在 `@lark-apaas/nestjs-observable` 中最标准的用法，用于在请求进入时自动开启根 Span，并从 Header 中透传 Trace 信息。

```typescript
import { appSdk } from '@lark-apaas/observable';

// 在中间件或拦截器中调用
appSdk.startContext(req.headers, 'GET /api/user', (span) => {
  // 此时上下文已建立，后续的 log 或 trace 会自动关联
  res.on('finish', () => {
    span.setAttributes({ 'http_status_code': res.statusCode });
    span.end();
  });
  next();
});
```

### Scenario B: Integration Example (业务代码手动打点)
展示如何在业务 Service 中进行手动链路追踪和日志记录，SDK 会自动从当前上下文中提取 Trace ID。

```typescript
import { appSdk } from '@lark-apaas/observable';

class UserService {
  async getUser(id: string) {
    // 自动关联到中间件开启的 Root Span 下
    return appSdk.trace('UserService.getUser', async (span) => {
      span.setAttribute('user.id', id);
      
      const user = await this.db.find(id);
      
      // 日志会自动带上当前 Trace 的上下文信息
      appSdk.log('info', 'Fetch user success', { userId: id });
      
      return user;
    });
  }
}
```

---

## 3. API Reference

### Core API (`appSdk`)

| 函数名 | 说明 | 参数类型 |
| :--- | :--- | :--- |
| `start()` | 初始化并启动 OTel SDK。 | `void` |
| `startContext()` | [框架专用] 根据 Header 开启一个活动的根上下文。 | `(headers, name, callback)` |
| `trace<T>()` | [用户专用] 手动创建一个子 Span，支持同步、Async 和 Observable。 | `(name, callback)` |
| `log()` | 记录结构化日志，自动关联当前 Trace 上下文。 | `(level, message, extra?)` |
| `flush()` | 强制刷新并导出内存中积压的 Trace 和 Logs 数据。 | `Promise<void>` |

### Configuration
SDK 默认采用以下配置：
- **Batch Processing**: 日志和 Trace 均采用批处理（BatchProcessor），延迟 2000ms 或达到批次上限时导出。
- **Resource Detection**: 内置 `PlatformDetector`，自动识别并添加平台相关的资源属性。
- **Log Format**: 自动将所有日志属性转换为字符串，确保在 ElasticSearch 等系统中索引一致性。
npm package: @lark-apaas/openclaw-dev-cli
Description: CLI tool for OpenClaw development
Latest version: 0.1.29

# @lark-apaas/openclaw-dev-cli

OpenClaw 应用开发 CLI，管理应用的创建、关联、检查和部署。

## 安装

无需安装，通过 npx 直接使用：

```bash
npx --yes @lark-apaas/openclaw-dev-cli <command> [options]
```

## 命令

### init — 初始化应用

```bash
# 创建全栈应用（Vite + React + Express + PostgreSQL）
npx --yes @lark-apaas/openclaw-dev-cli init --template apex --dir <path>

# 创建纯前端应用
npx --yes @lark-apaas/openclaw-dev-cli init --template <html|vite-react> --dir <path>

# clone 后初始化
npx --yes @lark-apaas/openclaw-dev-cli init --dir <path>
```

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--dir <path>` | 项目目录 | `.` |
| `--template <template>` | 模板类型（无代码时必须） | - |
| `--title <title>` | 应用名称 | 目录名 |
| `--description <desc>` | 应用描述 | `""` |
| `--template-version <version>` | 模板包版本 | `latest` |
| `--app-id <id>` | 使用已有应用 ID（跳过注册） | - |
| `--features <features...>` | 覆盖模板默认 features | 从模板 mclaw.features 读取 |
| `--skip-install` | 跳过依赖安装 | `false` |
| `--sync-install` | 同步等待依赖安装完成 | `false` |

默认异步安装依赖（后台运行），init 立即返回。用 `mclaw-dev check` 校验安装是否完成。

### check — 检查项目完整性

```bash
npx --yes @lark-apaas/openclaw-dev-cli check [--dir <path>]
```

检查规则：
- `node-modules` — node_modules 是否存在（检测后台安装状态）
- `meta-json` — .spark/meta.json 是否完整
- `package-json` — package.json 是否有 build 脚本

### link — 关联已有项目

```bash
npx --yes @lark-apaas/openclaw-dev-cli link --app-id <id> --template <type>
```

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--dir <path>` | 项目目录 | `.` |
| `--app-id <id>` | 要关联的应用 ID | 不传则自动注册 |
| `--template <template>` | 技术栈类型 | 从 package.json mclaw 字段读取 |
| `--title <title>` | 应用名称 | 目录名 |
| `--description <desc>` | 应用描述 | `""` |

### deploy — 部署应用

```bash
npx --yes @lark-apaas/openclaw-dev-cli deploy
```

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--dir <path>` | 项目目录 | `.` |
| `--skip-build` | 跳过构建 | `false` |

deploy 流程：check → createPublish → 获取凭证 → build → prune（全栈） → validate → upload → FaaS 部署（全栈） → updatePublish

全栈项目（archType=1）额外执行：
- **智能依赖裁剪**：@vercel/nft 追踪 + 选择性复制 node_modules
- **server.zip 打包**：服务端代码 + 裁剪后的 node_modules + run.sh
- **FaaS 部署**：触发 VeFaaS 部署并轮询状态

## 全局选项

| 选项 | 说明 |
|------|------|
| `--canary <env>` | 设置 canary 泳道 |
| `-V, --version` | 输出版本号 |

## 支持的技术栈

| 模板 | 类型 | 说明 |
|------|------|------|
| `html` | 纯前端 | 纯 HTML + Tailwind CDN |
| `vite-react` | 纯前端 | Vite + React 19 + Tailwind CSS + shadcn/ui |
| `apex` | 全栈 | Vite + React + Express + Drizzle + PostgreSQL |

## 环境配置

在项目目录下创建 `.env` 文件：

```
FORCE_AUTHN_INNERAPI_DOMAIN=<API域名>
FORCE_AUTHN_ACCESS_KEY=<AK>
FORCE_AUTHN_ACCESS_SECRET=<SK>
```

## License

MIT