@downcity/city 0.2.17

package/README.md

@@ -0,0 +1,182 @@
+# @downcity/city
+
+`@downcity/city` 是 Downcity 的服务端运行时内核。
+
+它负责这些共用能力：
+
+- 挂载 `Service` / `AIService`
+- 初始化内置 `studios` / `env` 表
+- 校验 `user_token` 和 `admin_secret_key`
+- 暴露统一的 `/v1/*` HTTP 路由
+- 提供 env、数据库、hook 和鉴权上下文
+
+## 安装
+
+```bash
+pnpm add @downcity/city
+```
+
+## 最小示例
+
+```ts
+import { City, AIService } from "@downcity/city";
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+
+const sqlite = new Database("./data.sqlite");
+sqlite.pragma("journal_mode = WAL");
+
+const db = Object.assign(drizzle(sqlite), {
+  $client: { exec: (sql: string) => sqlite.exec(sql) },
+});
+
+const city = new City({ db, dialect: "sqlite", raw: sqlite });
+
+const ai = new AIService();
+ai.use({
+  id: "local-echo",
+  name: "Local Echo",
+  default: ["text"],
+  actions: {
+    text: async (ctx) => ({
+      id: crypto.randomUUID(),
+      role: "assistant",
+      parts: [
+        {
+          type: "text",
+          text: String(ctx.input.prompt ?? ""),
+          state: "done",
+        },
+      ],
+    }),
+  },
+});
+
+city.use(ai);
+```
+
+启动 HTTP 服务：
+
+```ts
+import { serve } from "@hono/node-server";
+
+await city.health();
+serve({ fetch: city.router().fetch, port: 43127, hostname: "127.0.0.1" });
+```
+
+## City 说明文档
+
+`city.instruction()` 会返回当前 City 实例的聚合说明文档字符串，内容包含：
+
+- City 的基本使用方式
+- 当前已挂载的 service
+- 每个模块需要的 env 配置
+- 每个模块补充的使用说明
+
+```ts
+const text = await city.instruction();
+console.log(text);
+```
+
+如果你需要从远程管理端读取同一份说明，可以请求：
+
+```txt
+GET /v1/city/instruction
+```
+
+这个接口只允许 `admin_secret_key` 访问，返回 `text/plain`。
+
+## Service
+
+`Service` 是一组 `Action` 的容器：
+
+```ts
+import { Service } from "@downcity/city";
+
+const notes = new Service({ id: "notes", name: "Notes" });
+
+notes.action("create", async (ctx) => {
+  return {
+    ok: true,
+    title: String(ctx.input.title ?? ""),
+  };
+});
+
+notes.action("list", async () => {
+  return { items: [] };
+}, { method: "GET", auth: ["admin"] });
+
+city.use(notes);
+```
+
+City 会自动映射为：
+
+- `POST /v1/notes/create`
+- `GET /v1/notes/list`
+
+## AIService
+
+`AIService` 负责模型目录和模态路由：
+
+```ts
+import { AIService, Provider } from "@downcity/city";
+
+const deepseek = new Provider("deepseek", {
+  baseURL: "https://api.deepseek.com/v1",
+  envKey: "DEEPSEEK_API_KEY",
+  text: myTextAction,
+  stream: myStreamAction,
+});
+
+const ai = new AIService();
+ai.use(
+  deepseek.model({
+    id: "deepseek-v4-flash",
+    name: "DeepSeek V4 Flash",
+    default: ["text", "stream"],
+  }),
+);
+
+city.use(ai);
+```
+
+## 官方服务
+
+官方服务用于封装多 studio 复用能力：
+
+```ts
+import { accountsService } from "@downcity/services";
+import { usageService } from "@downcity/services";
+
+city.use(accountsService());
+city.use(usageService());
+```
+
+服务路由当前只支持：
+
+- `GET`
+- `POST`
+
+## 鉴权语义
+
+- 默认 action 需要 `user_token`
+- `auth: ["admin"]` 只允许 `admin_secret_key`
+- `auth: []` 表示免登录
+
+对于用户侧请求，`user_token` 绑定 studio 身份。如果请求体或 query 中传了 `studio_id`，它必须与 token 里的 studio 一致。
+
+## 主要导出
+
+- `City`
+- `Service`
+- `ServiceDefinition`
+- `AIService`
+- `Provider`
+- `TokenSigner`
+- `EnvService`
+- `StudiosService`
+
+## 文档
+
+- 仓库首页：[downcity](https://github.com/wangenius/downcity)
+- 文档目录：[homepage/content/docs](https://github.com/wangenius/downcity/tree/main/homepage/content/docs)

package/bin/core/auth/authenticator.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 统一鉴权模块。
+ *
+ * Authenticator 统一处理 admin（secret key）和 user（JWT token）两种鉴权方式。
+ * 所有鉴权失败统一抛出 httpError（ErrorWithStatus）。
+ *
+ * TokenSigner 实例通过 getSigner() 缓存，避免重复 new TokenSigner(key)。
+ */
+import { type RouteAuth, type RouteIdentity } from "../../service/service.js";
+import type { EnvProvider } from "../runtime.js";
+import type { CreateUserTokenInput, UserTokenPayload, UserTokenIssueResult, RuntimeUser } from "./types.js";
+/** 鉴权级别 */
+/** 鉴权结果 */
+export interface AuthResult {
+    /** 鉴权后的实际级别 */
+    level: RouteIdentity;
+    /** 解析出的用户信息（user 级别时可用） */
+    user?: RuntimeUser;
+    /** 解析出的 Studio 信息（user 级别时可用） */
+    studio?: {
+        studio_id: string;
+        status: string;
+    };
+}
+/** 统一鉴权器 */
+export declare class Authenticator {
+    private env;
+    private store;
+    /** 缓存的 TokenSigner 实例 */
+    private tokenSigner?;
+    constructor(env: EnvProvider, store: () => Promise<{
+        studio: {
+            get(id: string): Promise<{
+                studio_id: string;
+                status: string;
+            } | undefined>;
+        };
+    }>);
+    /**
+     * 获取（或创建）TokenSigner 单例。
+     *
+     * 首次调用时从 env 读取 DOWNCITY_CITY_TOKEN_SIGNING_KEY 创建实例并缓存。
+     */
+    private getSigner;
+    /**
+     * 解析请求身份。
+     *
+     * @param request - 原始 HTTP Request
+     * @returns 当前请求身份；无 token 或 token 无效时返回 guest
+     */
+    resolve(request: Request): Promise<AuthResult>;
+    /**
+     * 根据 action 的 auth 配置判断当前身份是否允许继续。
+     *
+     * @param result - 当前已解析身份
+     * @param required - action 声明的允许身份集合
+     * @returns 通过授权后的身份结果
+     */
+    authorize(result: AuthResult, required?: RouteAuth): AuthResult;
+    /**
+     * 对请求执行鉴权并强制满足 action 的 auth 配置。
+     */
+    authenticate(request: Request, required?: RouteAuth): Promise<AuthResult>;
+    /**
+     * 签发 user_token（验证 studio 状态后签发）。
+     *
+     * @param input - token 创建参数
+     * @returns 签发结果（含 token 字符串）
+     */
+    createToken(input: CreateUserTokenInput): Promise<UserTokenIssueResult>;
+    /**
+     * 校验 user_token 并返回载荷。
+     *
+     * @param token - user_token 字符串
+     * @returns 解析出的 token 载荷
+     */
+    verifyToken(token: string): Promise<UserTokenPayload>;
+}
+//# sourceMappingURL=authenticator.d.ts.map

package/bin/core/auth/authenticator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticator.d.ts","sourceRoot":"","sources":["../../../src/core/auth/authenticator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAsB,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAClG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE5G,WAAW;AACX,WAAW;AACX,MAAM,WAAW,UAAU;IACzB,eAAe;IACf,KAAK,EAAE,aAAa,CAAC;IACrB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,iCAAiC;IACjC,MAAM,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAChD;AAED,YAAY;AACZ,qBAAa,aAAa;IAKtB,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,KAAK;IALf,yBAAyB;IACzB,OAAO,CAAC,WAAW,CAAC,CAAc;gBAGxB,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,MAAM,OAAO,CAAC;QAAE,MAAM,EAAE;YAAE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;gBAAE,SAAS,EAAE,MAAM,CAAC;gBAAC,MAAM,EAAE,MAAM,CAAA;aAAE,GAAG,SAAS,CAAC,CAAA;SAAE,CAAA;KAAE,CAAC;IAG3H;;;;OAIG;IACH,OAAO,CAAC,SAAS;IASjB;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IA0BpD;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,UAAU;IAY/D;;OAEG;IACG,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAI/E;;;;;OAKG;IACG,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAiB7E;;;;;OAKG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAG5D"}

package/bin/core/auth/authenticator.js

@@ -0,0 +1,125 @@
+/**
+ * 统一鉴权模块。
+ *
+ * Authenticator 统一处理 admin（secret key）和 user（JWT token）两种鉴权方式。
+ * 所有鉴权失败统一抛出 httpError（ErrorWithStatus）。
+ *
+ * TokenSigner 实例通过 getSigner() 缓存，避免重复 new TokenSigner(key)。
+ */
+import { bearerToken, httpError } from "../../utils/helpers.js";
+import { TokenSigner } from "./token-signer.js";
+import { normalizeRouteAuth } from "../../service/service.js";
+/** 统一鉴权器 */
+export class Authenticator {
+    env;
+    store;
+    /** 缓存的 TokenSigner 实例 */
+    tokenSigner;
+    constructor(env, store) {
+        this.env = env;
+        this.store = store;
+    }
+    /**
+     * 获取（或创建）TokenSigner 单例。
+     *
+     * 首次调用时从 env 读取 DOWNCITY_CITY_TOKEN_SIGNING_KEY 创建实例并缓存。
+     */
+    getSigner() {
+        if (!this.tokenSigner) {
+            const signingKey = this.env.get("DOWNCITY_CITY_TOKEN_SIGNING_KEY");
+            if (!signingKey)
+                throw new Error("DOWNCITY_CITY_TOKEN_SIGNING_KEY is required");
+            this.tokenSigner = new TokenSigner(signingKey);
+        }
+        return this.tokenSigner;
+    }
+    /**
+     * 解析请求身份。
+     *
+     * @param request - 原始 HTTP Request
+     * @returns 当前请求身份；无 token 或 token 无效时返回 guest
+     */
+    async resolve(request) {
+        const token = bearerToken(request);
+        if (!token)
+            return { level: "guest" };
+        const adminKey = this.env.get("DOWNCITY_CITY_ADMIN_SECRET_KEY");
+        if (adminKey && token === adminKey) {
+            return { level: "admin" };
+        }
+        try {
+            const payload = await this.getSigner().verify(token);
+            const store = await this.store();
+            const studio = await store.studio.get(payload.studio_id);
+            if (!studio)
+                return { level: "guest" };
+            if (studio.status !== "active")
+                return { level: "guest" };
+            return {
+                level: "user",
+                user: { user_id: payload.user_id, metadata: payload.metadata ?? {} },
+                studio,
+            };
+        }
+        catch {
+            return { level: "guest" };
+        }
+    }
+    /**
+     * 根据 action 的 auth 配置判断当前身份是否允许继续。
+     *
+     * @param result - 当前已解析身份
+     * @param required - action 声明的允许身份集合
+     * @returns 通过授权后的身份结果
+     */
+    authorize(result, required) {
+        const allowed = normalizeRouteAuth(required);
+        if (allowed.length === 0)
+            return result;
+        if (result.level !== "guest" && allowed.includes(result.level))
+            return result;
+        if (result.level === "guest") {
+            throw httpError(401, "Authentication required");
+        }
+        throw httpError(403, `Forbidden for identity: ${result.level}`);
+    }
+    /**
+     * 对请求执行鉴权并强制满足 action 的 auth 配置。
+     */
+    async authenticate(request, required) {
+        return this.authorize(await this.resolve(request), required);
+    }
+    /**
+     * 签发 user_token（验证 studio 状态后签发）。
+     *
+     * @param input - token 创建参数
+     * @returns 签发结果（含 token 字符串）
+     */
+    async createToken(input) {
+        const store = await this.store();
+        const studio = await store.studio.get(input.studio_id);
+        if (!studio)
+            throw httpError(404, `Unknown studio: ${input.studio_id}`);
+        if (studio.status !== "active")
+            throw httpError(403, `Studio is not active: ${input.studio_id}`);
+        const user_token = await this.getSigner().sign(input);
+        return {
+            user_token,
+            studio_id: input.studio_id,
+            user_id: input.user_id,
+            ...(input.ttl
+                ? { expires_at: new Date(Date.now() + TokenSigner.parseTTL(input.ttl) * 1000).toISOString() }
+                : {}),
+        };
+    }
+    /**
+     * 校验 user_token 并返回载荷。
+     *
+     * @param token - user_token 字符串
+     * @returns 解析出的 token 载荷
+     */
+    async verifyToken(token) {
+        return this.getSigner().verify(token);
+    }
+}
+//# sourceMappingURL=authenticator.js.map

package/bin/core/auth/authenticator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticator.js","sourceRoot":"","sources":["../../../src/core/auth/authenticator.ts"],"names":[],"mappings":"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"}

package/bin/core/auth/token-signer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * user_token 签发与校验模块。
+ *
+ * Downcity 使用 Web Crypto API 的 HMAC-SHA256 生成最小可用的 user_token。
+ * 零 Node.js 依赖，兼容所有现代运行时（Node、Workers、Deno、Bun、浏览器）。
+ */
+import type { CreateUserTokenInput, UserTokenPayload } from "./types.js";
+export declare class TokenSigner {
+    readonly signingKey: string;
+    /** 缓存的 CryptoKey，避免每次签名都重新 import */
+    private cryptoKey?;
+    constructor(signingKey: string);
+    /**
+     * 获取（或缓存）HMAC CryptoKey。
+     *
+     * 使用 Web Crypto API 的 crypto.subtle.importKey，
+     * 首次调用时创建并缓存 Promise，后续复用。
+     */
+    private getCryptoKey;
+    /** 签发 user_token */
+    sign(input: CreateUserTokenInput): Promise<string>;
+    /** 校验并解析 user_token，失败抛 httpError(401) */
+    verify(token: string): Promise<UserTokenPayload>;
+    /** 把 ttl 解析成秒数 */
+    static parseTTL(ttl: string | number): number;
+}
+//# sourceMappingURL=token-signer.d.ts.map

package/bin/core/auth/token-signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-signer.d.ts","sourceRoot":"","sources":["../../../src/core/auth/token-signer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEzE,qBAAa,WAAW;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,qCAAqC;IACrC,OAAO,CAAC,SAAS,CAAC,CAAqB;gBAE3B,UAAU,EAAE,MAAM;IAO9B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAcpB,oBAAoB;IACd,IAAI,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BxD,0CAA0C;IACpC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA6BtD,kBAAkB;IAClB,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;CAyB9C"}

package/bin/core/auth/token-signer.js

@@ -0,0 +1,116 @@
+/**
+ * user_token 签发与校验模块。
+ *
+ * Downcity 使用 Web Crypto API 的 HMAC-SHA256 生成最小可用的 user_token。
+ * 零 Node.js 依赖，兼容所有现代运行时（Node、Workers、Deno、Bun、浏览器）。
+ */
+import { httpError, base64UrlEncode, base64UrlDecode, base64UrlEncodeBytes, base64UrlDecodeBytes, timingSafeEqualBytes } from "../../utils/helpers.js";
+export class TokenSigner {
+    signingKey;
+    /** 缓存的 CryptoKey，避免每次签名都重新 import */
+    cryptoKey;
+    constructor(signingKey) {
+        if (!signingKey) {
+            throw new Error("TokenSigner requires a signing key");
+        }
+        this.signingKey = signingKey;
+    }
+    /**
+     * 获取（或缓存）HMAC CryptoKey。
+     *
+     * 使用 Web Crypto API 的 crypto.subtle.importKey，
+     * 首次调用时创建并缓存 Promise，后续复用。
+     */
+    getCryptoKey() {
+        if (!this.cryptoKey) {
+            const encoder = new TextEncoder();
+            this.cryptoKey = crypto.subtle.importKey("raw", encoder.encode(this.signingKey), { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
+        }
+        return this.cryptoKey;
+    }
+    /** 签发 user_token */
+    async sign(input) {
+        if (!input || typeof input.studio_id !== "string" || input.studio_id.length === 0) {
+            throw new TypeError("studio_id is required");
+        }
+        if (typeof input.user_id !== "string" || input.user_id.length === 0) {
+            throw new TypeError("user_id is required");
+        }
+        const ttl = input.ttl;
+        const now = Math.floor(Date.now() / 1000);
+        const payload = {
+            aud: "downcity:user",
+            studio_id: input.studio_id,
+            user_id: input.user_id,
+            metadata: input.metadata ?? {},
+            iat: now,
+        };
+        if (ttl) {
+            payload.exp = now + TokenSigner.parseTTL(ttl);
+        }
+        const encodedPayload = base64UrlEncode(JSON.stringify(payload));
+        const signature = await signPayload(await this.getCryptoKey(), encodedPayload);
+        return `ub_${encodedPayload}.${signature}`;
+    }
+    /** 校验并解析 user_token，失败抛 httpError(401) */
+    async verify(token) {
+        const rawToken = token.startsWith("ub_") ? token.slice(3) : token;
+        const [encodedPayload, signature] = rawToken.split(".");
+        if (!encodedPayload || !signature) {
+            throw httpError(401, "Invalid user token");
+        }
+        if (!await verifyPayload(await this.getCryptoKey(), encodedPayload, signature)) {
+            throw httpError(401, "Invalid user token signature");
+        }
+        const payload = JSON.parse(base64UrlDecode(encodedPayload));
+        const now = Math.floor(Date.now() / 1000);
+        if (payload.exp && payload.exp <= now) {
+            throw httpError(401, "User token expired");
+        }
+        if (payload.aud !== "downcity:user") {
+            throw httpError(401, "Invalid user token audience");
+        }
+        if (!payload.studio_id || !payload.user_id) {
+            throw httpError(401, "Invalid user token payload");
+        }
+        return payload;
+    }
+    /** 把 ttl 解析成秒数 */
+    static parseTTL(ttl) {
+        if (typeof ttl === "number" && Number.isFinite(ttl) && ttl > 0) {
+            return ttl;
+        }
+        if (typeof ttl !== "string") {
+            throw new TypeError("ttl must be a positive number of seconds or a string like 1h");
+        }
+        const match = ttl.match(/^(\d+)(s|m|h|d)$/);
+        if (!match) {
+            throw new Error(`Invalid ttl: ${ttl}`);
+        }
+        const value = Number(match[1]);
+        const unit = match[2];
+        const multipliers = {
+            s: 1,
+            m: 60,
+            h: 60 * 60,
+            d: 24 * 60 * 60,
+        };
+        return value * multipliers[unit];
+    }
+}
+/**
+ * 使用 HMAC-SHA256 对 payload 签名，返回 base64url 编码的签名。
+ */
+async function signPayload(cryptoKey, encodedPayload) {
+    const signature = await crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(encodedPayload));
+    return base64UrlEncodeBytes(new Uint8Array(signature));
+}
+/**
+ * 验证 HMAC-SHA256 签名是否匹配。
+ */
+async function verifyPayload(cryptoKey, encodedPayload, signature) {
+    const expected = base64UrlDecodeBytes(signature);
+    const actual = await crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(encodedPayload));
+    return timingSafeEqualBytes(new Uint8Array(actual), expected);
+}
+//# sourceMappingURL=token-signer.js.map

package/bin/core/auth/token-signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-signer.js","sourceRoot":"","sources":["../../../src/core/auth/token-signer.ts"],"names":[],"mappings":"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"}

package/bin/core/auth/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Auth 域公共类型。
+ *
+ * 包含 token 相关的用户、载荷和签发结果类型。
+ */
+/**
+ * Runtime 中的终端用户信息。
+ */
+export interface RuntimeUser {
+    /**
+     * 开发者系统中的用户主键。
+     */
+    user_id: string;
+    /**
+     * 附带在 token 中的业务元数据。
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 签发 user_token 的输入。
+ */
+export interface CreateUserTokenInput {
+    /**
+     * token 所属的 Studio ID。
+     */
+    studio_id: string;
+    /**
+     * token 所属的终端用户 ID。
+     */
+    user_id: string;
+    /**
+     * 附带进 token 的业务元数据。
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * token 有效期。
+     *
+     * 支持 `30m`、`1h`、`7d` 或秒数。
+     */
+    ttl?: string | number;
+}
+/**
+ * user_token 的标准载荷。
+ */
+export interface UserTokenPayload {
+    /**
+     * token 受众。
+     */
+    aud: "downcity:user";
+    /**
+     * token 所属 Studio ID。
+     */
+    studio_id: string;
+    /**
+     * token 所属用户 ID。
+     */
+    user_id: string;
+    /**
+     * 业务元数据。
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * 签发时间。
+     */
+    iat: number;
+    /**
+     * 过期时间。
+     */
+    exp?: number;
+}
+/**
+ * City 返回给管理端的发 token 结果。
+ */
+export interface UserTokenIssueResult {
+    /**
+     * 可交给 UserClient 使用的 token。
+     */
+    user_token: string;
+    /**
+     * token 所属 Studio ID。
+     */
+    studio_id: string;
+    /**
+     * token 所属用户 ID。
+     */
+    user_id: string;
+    /**
+     * token 过期时间。
+     *
+     * 未设置 ttl 时省略。
+     */
+    expires_at?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/bin/core/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/auth/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,GAAG,EAAE,eAAe,CAAC;IAErB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/bin/core/auth/types.js

@@ -0,0 +1,7 @@
+/**
+ * Auth 域公共类型。
+ *
+ * 包含 token 相关的用户、载荷和签发结果类型。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/bin/core/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/auth/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/bin/core/base/base-env-catalog.d.ts

@@ -0,0 +1,13 @@
+/**
+ * City env requirement 聚合模块。
+ *
+ * 负责把 service.env 与 AI 模型 env requirement 汇总成统一目录。
+ */
+import type { Service } from "../../service/service.js";
+import type { EnvCatalogScope } from "../../service/env/types.js";
+import type { EnvProvider } from "../runtime.js";
+/**
+ * 聚合当前 City 暴露的 env requirement。
+ */
+export declare function collect_city_env_catalog(services: Service[], env_provider: EnvProvider): EnvCatalogScope[];
+//# sourceMappingURL=base-env-catalog.d.ts.map

package/bin/core/base/base-env-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-env-catalog.d.ts","sourceRoot":"","sources":["../../../src/core/base/base-env-catalog.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAwB,MAAM,4BAA4B,CAAC;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,OAAO,EAAE,EACnB,YAAY,EAAE,WAAW,GACxB,eAAe,EAAE,CAsBnB"}