downcity 1.1.39 → 1.1.68

package/README.md

@@ -1,257 +1,16 @@
-# @downcity/city
+# downcity
 
-`@downcity/city` 是 Downcity 的平台层与多 Agent 宿主管理包。
+`downcity` 是 Downcity 的全局安装聚合包。
 
-它负责 CLI、控制面、city runtime 进程管理、全局配置存储，以及多个 agent 的注册与调度。  
-它依赖 `@downcity/agent` 提供单 Agent runtime、plugin、control API、sandbox 与执行能力，但不重复实现这些内核。
-
-## 包定位
-
-- 面向平台层和宿主管理层。
-- 管理多个 Agent 项目与后台进程。
-- 提供控制面 gateway / control plane。
-- 提供全局模型池、模型实例创建、全局环境变量、全局 chat channel account 存储。
-
-## 与其他包的边界
-
-- `@downcity/city`
-  - 多 Agent 管理。
-  - 平台 CLI。
-  - 控制面 gateway / control plane。
-  - 全局模型池与 city 宿主侧模型工厂。
-  - city 级全局 store。
-
-- `@downcity/agent`
-  - 单 Agent runtime。
-  - 单 Agent control API。
-  - plugin / sandbox / tool loop / session 执行。
-
-- `@downcity/ui`
-  - React UI 组件与前端展示层。
-
-## 根目录结构
-
-```text
-packages/city
-├── bin/                # 编译输出目录，CLI 实际执行入口
-├── public/             # 控制面前端静态资源
-├── scripts/            # 构建和发布辅助脚本
-├── src/                # 源码目录
-├── package.json        # 包信息、CLI bin、脚本
-└── tsconfig.json       # TypeScript 配置
+```bash
+npm install -g downcity
+city -v
+town -v
 ```
 
-## 源码结构树
-
-```text
-src
-├── cli/
-│   ├── agent/
-│   ├── control-plane/
-│   ├── model/
-│   │   └── preset/
-│   ├── shared/
-│   └── Index.ts
-├── config/
-├── control/
-│   ├── instant/
-│   └── gateway/
-├── http/
-│   └── auth/
-├── model/
-│   └── runtime/
-├── platform/
-│   └── store/
-├── process/
-│   ├── daemon/
-│   ├── registry/
-│   └── rpc/
-├── types/
-│   ├── chat/
-│   ├── contact/
-│   └── task/
-└── utils/
-    └── cli/
-```
-
-## 目录职责
-
-- `src/cli/`
-  - CLI 命令实现与装配。
-  - 已按子域拆分，避免扁平堆积。
-
-- `src/cli/agent/`
-  - `city agent ...` 命令。
-  - 包括 agent create、start、stop、restart、status、chat、history、交互式 manager。
-
-- `src/cli/control-plane/`
-  - `city` 顶层 runtime 命令与 `city console ...` 命令。
-  - 这层语义是 control plane / gateway 宿主管理，而不是单 Agent API。
-
-- `src/cli/model/`
-  - `city model ...` 命令。
-  - 面向 city 全局模型池的 CLI 管理。
-
-- `src/cli/model/preset/`
-  - city 侧模型预设目录。
-  - 只保留命令交互需要的预设定义，不再复制全局 store 实现。
-
-- `src/cli/shared/`
-  - 多个 CLI 子域共用的基础能力。
-  - 包括 reporter、错误类型、env、token、plugin、chat manager、命令参数辅助，以及托管 plugin action 命令桥接等。
-
-- `src/config/`
-  - city 自己的静态配置结构。
-  - 包括路径规则、schema 常量。
-
-- `src/control/`
-  - 平台控制面 HTTP gateway。
-  - 负责聚合多 Agent 视图、控制动作、前端资源、模型池与 channel account API。
-  - 这是 gateway / control plane，不是单 Agent control API。
-
-- `src/control/instant/`
-  - control plane 下的即时执行子域。
-  - 放置 instant-run 路由、临时 session runner 和即时 system composer。
-
-- `src/control/gateway/`
-  - gateway 的读写辅助模块。
-  - 包括 agent catalog、agent actions、proxy、frontend assets 等。
-
-## 命名说明
-
-- `city/cli/control-plane`
-  - 这里承载 city gateway / control plane 的命令面与进程管理面。
-  - CLI 命令对用户仍保留 `city console`，但源码结构已经按 control plane 语义命名。
-
-- `city/control`
-  - 这里承载的是多 agent 聚合控制面，不是单 agent control API。
-
-- `@downcity/agent` 内部的 `server/http/control`
-  - 这里承载的是 single-agent control API。
-  - 当前统一路径是 `/api/control/*`。
-
-- `src/http/auth/`
-  - city 控制面自己的鉴权体系。
-  - 包括 token、middleware、route policy、store。
-
-- `src/model/runtime/`
-  - city 宿主侧 `LanguageModel` 工厂。
-  - 负责把 `downcity.json.execution.modelId` 解析成 provider/model 配置，再创建可注入 Agent session 的模型实例。
-  - `@downcity/agent` 只消费 `LanguageModel`，不再负责模型池解析。
-
-- `src/platform/store/`
-  - city 平台持久化存储入口。
-  - 承载 provider、model、环境变量、channel account 等宿主级数据。
-
-- `src/process/`
-  - city runtime 进程侧能力。
-  - 统一承接 daemon、registry、local rpc，不再散落在顶层目录。
-
-- `src/process/daemon/`
-  - Agent daemon 的 pid/log/meta/启停管理。
-  - 负责后台拉起 agent 前台进程。
-
-- `src/process/registry/`
-  - city runtime 与多 Agent registry 状态。
-  - 记录哪些 agent 已登记、哪些 daemon 正在运行、Console/city pid 路径等。
-
-- `src/process/rpc/`
-  - city 侧 local RPC 客户端辅助。
-  - 用于本机调用 Agent 暴露的 IPC 接口。
-
-- `src/types/`
-  - 当前仅保留尚未进一步归位的领域类型。
-  - 目前主要是 `chat / contact / task` 三组。
-  - CLI、store、city 自己的高频类型已经贴回对应模块邻近位置。
-
-- `src/utils/`
-  - 平台层通用工具。
-
-- `src/utils/cli/`
-  - CLI 输出、spinner 等命令行体验辅助。
-
-## 关键调用关系
-
-### 1. CLI 主入口
-
-```text
-src/cli/Index.ts
-  -> control-plane/
-  -> agent/
-  -> model/
-  -> shared/
-```
-
-### 2. 启动 city runtime 与 Console
-
-```text
-city start
-  -> src/cli/control-plane/ControlPlaneCommand.ts
-  -> src/cli/control-plane/ControlPlaneProcess.ts
-  -> src/process/registry/*
-  -> src/control/ControlGateway.ts
-```
-
-### 3. 启动 Agent daemon
-
-```text
-city agent start
-  -> src/cli/agent/Start.ts
-  -> src/process/daemon/Manager.ts
-  -> detached child process
-  -> @downcity/agent runtime
-```
-
-### 4. 控制面读写 Agent
-
-```text
-browser / UI
-  -> src/control/ControlGateway.ts
-  -> src/control/gateway/*
-  -> src/process/registry/*
-  -> 转发到单 Agent HTTP / RPC
-```
-
-### 5. 全局模型池
-
-```text
-city model ...
-  -> src/cli/model/*
-  -> src/platform/store/*
-  -> src/model/runtime/CreateRuntimeModel.ts
-  -> src/cli/model/preset/*
-```
-
-## 当前最重要的入口文件
-
-- `src/cli/Index.ts`
-  - CLI 主入口。
-
-- `src/cli/control-plane/ControlPlaneCommand.ts`
-  - 顶层 city / control plane 命令装配。
-
-- `src/cli/shared/IndexAgentCommand.ts`
-  - `city agent` 命令树装配。
-
-- `src/control/ControlGateway.ts`
-  - 平台控制面 gateway 主入口。
-
-- `src/process/daemon/Manager.ts`
-  - agent daemon 生命周期管理核心。
-
-- `src/process/registry/CityRegistry.ts`
-  - 多 Agent registry 核心。
-
-- `src/model/runtime/CreateRuntimeModel.ts`
-  - city 宿主侧模型工厂，负责把项目 `execution.modelId` 转成 session 可用的 `LanguageModel`。
+安装后会得到两个命令：
 
-## 维护约定
+- `city`：管理已部署的 City、共享模型目录与服务资源。
+- `town`：在本机启动和管理 Agent 宿主环境。
 
-- 不要把单 Agent 执行逻辑重新实现到这个包里。
-- sandbox、tool loop、session 执行与 plugin runtime 内核统一来自 `@downcity/agent`。
-- 模型池、provider store 与模型创建逻辑留在 city 宿主层，不下沉回 `@downcity/agent`。
-- `control/` 是平台 gateway / control plane。
-- 单 Agent 的 HTTP control API 语义应该留在 `@downcity/agent`。
-- `process/` 统一放 city 的进程管理、registry、RPC，不要再散落回顶层。
-- `config/` 只放静态配置/schema/路径，不混入运行时 store 逻辑。
-- CLI 类型、store 类型、city 自有小类型优先就近放在对应模块旁边。
+`cli/city` 与 `cli/town` 是仓库内部构建单元；用户只需要安装 `downcity`。

package/bin/city/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * downcity 聚合包中的 city 命令入口。
+ *
+ * 关键点（中文）：`downcity` 是唯一对外安装包，city 命令构建产物
+ * 会在发布前复制到本包内部，避免泄漏内部 workspace 包名。
+ */
+import "../../city/index.js";

package/bin/town/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * downcity 聚合包中的 town 命令入口。
+ *
+ * 关键点（中文）：用户只需要 npm i -g downcity，也能得到 town 命令；
+ * town runtime 构建产物由本包构建脚本复制进来。
+ */
+import "../../town/index.js";

package/city/admin/auth-error.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Admin 鉴权错误工具。
+ *
+ * 关键说明（中文）
+ * - 当 admin key 不正确或已失效时，SDK 会把请求失败包装成带 `status` 的 Error。
+ * - 这里统一把 401 转成可识别的 AdminAuthError，方便外层清理缓存 session 并提示重新输入。
+ */
+/**
+ * admin key 无效时给用户展示的统一提示。
+ */
+export declare const ADMIN_AUTH_INVALID_MESSAGE = "Current server admin key is incorrect or expired. Please set it again.";
+/**
+ * 判断服务端是否缺少新接口。
+ */
+export declare function isAdminNotFoundError(error: unknown): boolean;
+/**
+ * admin 鉴权失效错误。
+ */
+export declare class AdminAuthError extends Error {
+    constructor(message?: string);
+}
+/**
+ * 判断当前错误是否是 admin 鉴权失效。
+ */
+export declare function isAdminAuthError(error: unknown): error is AdminAuthError;
+/**
+ * 如果底层错误是 401，则提升为 AdminAuthError。
+ */
+export declare function rethrowAdminAuthError(error: unknown): void;
+/**
+ * 提取可展示的错误文本。
+ */
+export declare function adminErrorMessage(error: unknown): string;
+//# sourceMappingURL=auth-error.d.ts.map

package/city/admin/auth-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-error.d.ts","sourceRoot":"","sources":["../../src/admin/auth-error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,eAAO,MAAM,0BAA0B,2EACmC,CAAC;AAO3E;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,SAA6B;CAIjD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAK1D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKxD"}

package/city/admin/auth-error.js

@@ -0,0 +1,51 @@
+/**
+ * Admin 鉴权错误工具。
+ *
+ * 关键说明（中文）
+ * - 当 admin key 不正确或已失效时，SDK 会把请求失败包装成带 `status` 的 Error。
+ * - 这里统一把 401 转成可识别的 AdminAuthError，方便外层清理缓存 session 并提示重新输入。
+ */
+/**
+ * admin key 无效时给用户展示的统一提示。
+ */
+export const ADMIN_AUTH_INVALID_MESSAGE = "Current server admin key is incorrect or expired. Please set it again.";
+/**
+ * 判断服务端是否缺少新接口。
+ */
+export function isAdminNotFoundError(error) {
+    return error?.status === 404;
+}
+/**
+ * admin 鉴权失效错误。
+ */
+export class AdminAuthError extends Error {
+    constructor(message = ADMIN_AUTH_INVALID_MESSAGE) {
+        super(message);
+        this.name = "AdminAuthError";
+    }
+}
+/**
+ * 判断当前错误是否是 admin 鉴权失效。
+ */
+export function isAdminAuthError(error) {
+    return error instanceof AdminAuthError;
+}
+/**
+ * 如果底层错误是 401，则提升为 AdminAuthError。
+ */
+export function rethrowAdminAuthError(error) {
+    const status = error?.status;
+    if (status === 401) {
+        throw new AdminAuthError();
+    }
+}
+/**
+ * 提取可展示的错误文本。
+ */
+export function adminErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+//# sourceMappingURL=auth-error.js.map

package/city/admin/auth-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-error.js","sourceRoot":"","sources":["../../src/admin/auth-error.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,0BAA0B,GACrC,wEAAwE,CAAC;AAO3E;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAQ,KAAqC,EAAE,MAAM,KAAK,GAAG,CAAC;AAChE,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAO,GAAG,0BAA0B;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,KAAK,YAAY,cAAc,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,MAAM,MAAM,GAAI,KAAqC,EAAE,MAAM,CAAC;IAC9D,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,MAAM,IAAI,cAAc,EAAE,CAAC;IAC7B,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC"}

package/city/admin/commands/accounts.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Admin Accounts 管理命令。
+ */
+import { City } from "@downcity/city";
+export declare function manageAccounts(a: City): Promise<void>;
+//# sourceMappingURL=accounts.d.ts.map

package/city/admin/commands/accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../../../src/admin/commands/accounts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAKtC,wBAAsB,cAAc,CAAC,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAkC3D"}

package/city/admin/commands/accounts.js

@@ -0,0 +1,44 @@
+/**
+ * Admin Accounts 管理命令。
+ */
+import { select, isCancel } from "@clack/prompts";
+import { showError } from "../../core/ui.js";
+import { adminErrorMessage, rethrowAdminAuthError } from "../auth-error.js";
+export async function manageAccounts(a) {
+    const svc = a.service("accounts");
+    while (true) {
+        const act = await select({
+            message: "Accounts",
+            options: [
+                { label: "List users", value: "users" },
+                { label: "List sessions", value: "sessions" },
+                { label: "Back", value: "back" },
+            ],
+        });
+        if (!act || isCancel(act) || act === "back")
+            return;
+        try {
+            if (act === "users") {
+                const b = await svc.get("users");
+                console.log(`\n${b.items.length} users:\n`);
+                for (const u of b.items) {
+                    console.log(`  ${u.user_id.padEnd(30)} ${u.email.padEnd(30)} ${u.created_at.slice(0, 10)}`);
+                }
+                console.log("");
+            }
+            else {
+                const b = await svc.get("sessions");
+                console.log(`\n${b.items.length} sessions:\n`);
+                for (const s of b.items) {
+                    console.log(`  ${s.session_id.padEnd(36)} ${s.user_id.padEnd(30)} [${s.status}]`);
+                }
+                console.log("");
+            }
+        }
+        catch (e) {
+            rethrowAdminAuthError(e);
+            showError(adminErrorMessage(e));
+        }
+    }
+}
+//# sourceMappingURL=accounts.js.map

package/city/admin/commands/accounts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.js","sourceRoot":"","sources":["../../../src/admin/commands/accounts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE5E,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,CAAO;IAC1C,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAClC,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC;YACvB,OAAO,EAAE,UAAU;YACnB,OAAO,EAAE;gBACP,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE;gBACvC,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,EAAE;gBAC7C,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE;aACjC;SACF,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,MAAM;YAAE,OAAO;QAEpD,IAAI,CAAC;YACH,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;gBACpB,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,GAAG,CAAsE,OAAO,CAAC,CAAC;gBACtG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,WAAW,CAAC,CAAC;gBAC5C,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;oBACxB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;gBAC9F,CAAC;gBACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAClB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,GAAG,CAAuE,UAAU,CAAC,CAAC;gBAC1G,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,cAAc,CAAC,CAAC;gBAC/C,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;oBACxB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;gBACpF,CAAC;gBACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,qBAAqB,CAAC,CAAC,CAAC,CAAC;YACzB,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;AACH,CAAC"}

package/city/admin/commands/balance.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Admin Balance 管理命令。
+ */
+import { City } from "@downcity/city";
+export declare function manageBalance(a: City): Promise<void>;
+//# sourceMappingURL=balance.d.ts.map

package/city/admin/commands/balance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.d.ts","sourceRoot":"","sources":["../../../src/admin/commands/balance.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAKtC,wBAAsB,aAAa,CAAC,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CA6I1D"}

package/city/admin/commands/balance.js

@@ -0,0 +1,153 @@
+/**
+ * Admin Balance 管理命令。
+ */
+import { isCancel, select } from "@clack/prompts";
+import { askText, showError, showSuccess } from "../../core/ui.js";
+import { adminErrorMessage, rethrowAdminAuthError } from "../auth-error.js";
+export async function manageBalance(a) {
+    while (true) {
+        const act = await select({
+            message: "Balance",
+            options: [
+                { label: "List users", value: "users" },
+                { label: "History", value: "history" },
+                { label: "Topups", value: "topups" },
+                { label: "Redeem codes", value: "redeem_codes" },
+                { label: "Add balance", value: "add" },
+                { label: "Subtract balance", value: "sub" },
+                { label: "Finish topup", value: "finish" },
+                { label: "Cancel topup", value: "cancel" },
+                { label: "Create redeem code", value: "create_redeem_code" },
+                { label: "Disable redeem code", value: "disable_redeem_code" },
+                { label: "Back", value: "back" },
+            ],
+        });
+        if (!act || isCancel(act) || act === "back")
+            return;
+        try {
+            if (act === "users") {
+                const items = await a.balance.listUsers(30);
+                console.log(`\n${items.length} balance accounts:\n`);
+                for (const item of items) {
+                    console.log(`  ${item.user_id.padEnd(28)} ${String(item.balance).padStart(8)} ${item.unit.padEnd(10)} ${item.updated_at.slice(0, 19)}`);
+                }
+                console.log("");
+                continue;
+            }
+            if (act === "history") {
+                const userId = await askText("user_id (optional)");
+                const items = await a.balance.listHistory({
+                    limit: 30,
+                    user_id: userId ?? "",
+                });
+                console.log(`\n${items.length} balance history entries:\n`);
+                for (const item of items) {
+                    console.log(`  ${item.created_at.slice(0, 19)}  ${item.user_id.padEnd(20)} ${item.kind.padEnd(8)} ${String(item.amount).padStart(6)} -> ${String(item.balance_after).padStart(6)}  ${item.note}`);
+                }
+                console.log("");
+                continue;
+            }
+            if (act === "topups") {
+                const userId = await askText("user_id (optional)");
+                const items = await a.balance.listTopups({
+                    limit: 30,
+                    user_id: userId ?? "",
+                });
+                console.log(`\n${items.length} topup orders:\n`);
+                for (const item of items) {
+                    console.log(`  ${item.topup_id.padEnd(24)} ${item.user_id.padEnd(20)} ${String(item.amount).padStart(6)} ${item.unit.padEnd(10)} [${item.status}] ${item.note}`);
+                }
+                console.log("");
+                continue;
+            }
+            if (act === "redeem_codes") {
+                const status = await askText("status (optional: active/redeemed/disabled)");
+                const userId = await askText("redeemed_by_user_id (optional)");
+                const items = await a.balance.redeemCodes.list({
+                    limit: 30,
+                    status: normalizeRedeemCodeStatus(status),
+                    user_id: userId ?? "",
+                });
+                console.log(`\n${items.length} redeem codes:\n`);
+                for (const item of items) {
+                    const owner = item.redeemed_by_user_id || "-";
+                    console.log(`  ${item.redeem_code_id.padEnd(24)} ${item.code_mask.padEnd(22)} ${String(item.amount).padStart(6)} ${item.unit.padEnd(10)} [${item.status.padEnd(8)}] ${owner.padEnd(20)} ${item.note}`);
+                }
+                console.log("");
+                continue;
+            }
+            if (act === "add" || act === "sub") {
+                const userId = await askText("user_id");
+                if (!userId)
+                    continue;
+                const rawAmount = await askText("amount");
+                if (!rawAmount)
+                    continue;
+                const amount = Number(rawAmount);
+                if (!Number.isInteger(amount) || amount <= 0) {
+                    showError("amount must be a positive integer");
+                    continue;
+                }
+                const note = await askText("note (optional)");
+                const account = act === "add"
+                    ? await a.balance.add({ user_id: userId, amount, note: note ?? "" })
+                    : await a.balance.sub({ user_id: userId, amount, note: note ?? "" });
+                showSuccess(`balance updated: ${account.user_id} -> ${account.balance} ${account.unit}`);
+                continue;
+            }
+            if (act === "create_redeem_code") {
+                const rawAmount = await askText("amount");
+                if (!rawAmount)
+                    continue;
+                const amount = Number(rawAmount);
+                if (!Number.isInteger(amount) || amount <= 0) {
+                    showError("amount must be a positive integer");
+                    continue;
+                }
+                const code = await askText("custom redeem_code (optional)");
+                const note = await askText("note (optional)");
+                const issued = await a.balance.redeemCodes.create({
+                    amount,
+                    code: code ?? "",
+                    note: note ?? "",
+                });
+                showSuccess(`redeem_code created: ${issued.redeem_code_id} -> ${issued.code} (+${issued.amount} ${issued.unit})`);
+                continue;
+            }
+            if (act === "disable_redeem_code") {
+                const redeemCodeId = await askText("redeem_code_id");
+                if (!redeemCodeId)
+                    continue;
+                const note = await askText("note (optional)");
+                const item = await a.balance.redeemCodes.disable({
+                    redeem_code_id: redeemCodeId,
+                    note: note ?? "",
+                });
+                showSuccess(`redeem_code updated: ${item.redeem_code_id} -> ${item.status}`);
+                continue;
+            }
+            const topupId = await askText("topup_id");
+            if (!topupId)
+                continue;
+            const note = await askText("note (optional)");
+            const topup = act === "finish"
+                ? await a.balance.finishTopup({ topup_id: topupId, note: note ?? "" })
+                : await a.balance.cancelTopup({ topup_id: topupId, note: note ?? "" });
+            showSuccess(`topup updated: ${topup.topup_id} -> ${topup.status}`);
+        }
+        catch (e) {
+            rethrowAdminAuthError(e);
+            showError(adminErrorMessage(e));
+        }
+    }
+}
+function normalizeRedeemCodeStatus(value) {
+    const normalized = String(value ?? "").trim();
+    if (!normalized)
+        return undefined;
+    if (normalized === "active" || normalized === "redeemed" || normalized === "disabled") {
+        return normalized;
+    }
+    throw new TypeError("status must be active, redeemed, or disabled");
+}
+//# sourceMappingURL=balance.js.map

package/city/admin/commands/balance.js.map

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

package/city/admin/commands/config.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 旧的 Admin Server URL 命令兼容壳。
+ *
+ * 关键说明（中文）
+ * - 新交互下，server 管理已经提升到顶层 Manage Servers
+ * - 这里保留空壳是为了避免历史导入直接报错
+ */
+import { type AdminSession } from "../../core/session.js";
+export declare function changeServerUrl(_session: AdminSession): Promise<boolean>;
+//# sourceMappingURL=config.d.ts.map

package/city/admin/commands/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/admin/commands/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,wBAAsB,eAAe,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,CAE9E"}

package/city/admin/commands/config.js

@@ -0,0 +1,11 @@
+/**
+ * 旧的 Admin Server URL 命令兼容壳。
+ *
+ * 关键说明（中文）
+ * - 新交互下，server 管理已经提升到顶层 Manage Servers
+ * - 这里保留空壳是为了避免历史导入直接报错
+ */
+export async function changeServerUrl(_session) {
+    return false;
+}
+//# sourceMappingURL=config.js.map

package/city/admin/commands/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/admin/commands/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,QAAsB;IAC1D,OAAO,KAAK,CAAC;AACf,CAAC"}

package/city/admin/commands/custom.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Admin Custom Service 命令。
+ */
+import { City } from "@downcity/city";
+export declare function manageCustom(a: City): Promise<void>;
+//# sourceMappingURL=custom.d.ts.map

package/city/admin/commands/custom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom.d.ts","sourceRoot":"","sources":["../../../src/admin/commands/custom.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAKtC,wBAAsB,YAAY,CAAC,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCzD"}