@downcity/city 1.1.39 → 1.1.47

package/src/terminal/agent/pi-agent.ts

@@ -0,0 +1,180 @@
+/**
+ * Pi SDK agent 封装模块。
+ *
+ * 关键说明（中文）
+ * - 封装 @mariozechner/pi-coding-agent 的会话创建与多轮对话。
+ * - pi-agent 通过 server 的 /chat/completions 端点调用 AI，
+ *   client 只需要 server 地址 + user token，不需要 AI provider 的 API key。
+ */
+import type { Model } from "@mariozechner/pi-ai";
+import {
+  AuthStorage,
+  createAgentSession,
+  createExtensionRuntime,
+  ModelRegistry,
+  SessionManager,
+  SettingsManager,
+  type ResourceLoader,
+} from "@mariozechner/pi-coding-agent";
+import type { ModelHandle } from "@downcity/conduit";
+
+// ============================================================
+// 类型
+// ============================================================
+
+/** Pi-agent 会话 */
+export type PiAgentSession = {
+  ask(prompt: string): Promise<string>;
+};
+
+// ============================================================
+// 会话创建
+// ============================================================
+
+/** 创建 pi-agent 会话，通过 server 端点调用 AI */
+export async function createPiAgentSession(options: {
+  /** 模型句柄（来自 server model catalog） */
+  model: ModelHandle;
+  tools?: string;
+  onText?: (text: string) => void;
+  onToolStart?: (toolName: string, args: unknown) => void;
+  onToolEnd?: (toolName: string, isError: boolean) => void;
+}): Promise<PiAgentSession> {
+  const { model: handle, tools: toolsOpt, onText, onToolStart, onToolEnd } = options;
+
+  if (!handle.token) {
+    throw new Error("User token is required for agent. Please login first.");
+  }
+
+  const authStorage = AuthStorage.inMemory();
+  authStorage.setRuntimeApiKey("openai-compatible", handle.token);
+  const tools = resolveTools(toolsOpt);
+
+  const { session } = await createAgentSession({
+    cwd: process.cwd(),
+    model: createModel(handle),
+    thinkingLevel: "off",
+    authStorage,
+    modelRegistry: ModelRegistry.inMemory(authStorage),
+    resourceLoader: createMinimalResourceLoader(),
+    sessionManager: SessionManager.inMemory(process.cwd()),
+    settingsManager: SettingsManager.inMemory({
+      compaction: { enabled: false },
+      retry: { enabled: false },
+    }),
+    noTools: tools.length === 0 ? "all" : undefined,
+    tools: tools.length > 0 ? tools : undefined,
+  });
+
+  let activeTurn: { text: string; streamedText: boolean; assistantError?: string } | undefined;
+
+  session.subscribe((event) => {
+    if (!activeTurn) return;
+
+    if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+      activeTurn.text += event.assistantMessageEvent.delta;
+      activeTurn.streamedText = true;
+      onText?.(event.assistantMessageEvent.delta);
+      return;
+    }
+
+    if (event.type === "message_end") {
+      activeTurn.assistantError = extractAssistantError(event.message) ?? activeTurn.assistantError;
+      const finalText = extractAssistantText(event.message);
+      if (finalText) {
+        activeTurn.text = finalText;
+        if (!activeTurn.streamedText) onText?.(finalText);
+      }
+      return;
+    }
+
+    if (event.type === "tool_execution_start") {
+      onToolStart?.(event.toolName, event.args);
+      return;
+    }
+
+    if (event.type === "tool_execution_end") {
+      onToolEnd?.(event.toolName, event.isError);
+    }
+  });
+
+  return {
+    ask: async (prompt: string) => {
+      activeTurn = { text: "", streamedText: false };
+      await session.prompt(prompt, { expandPromptTemplates: false });
+      const completedTurn = activeTurn;
+      activeTurn = undefined;
+      if (completedTurn?.assistantError) {
+        throw new Error(`Pi agent request failed: ${completedTurn.assistantError}`);
+      }
+      return completedTurn?.text.trim() ?? "";
+    },
+  };
+}
+
+// ============================================================
+// 内部函数
+// ============================================================
+
+function createModel(handle: ModelHandle): Model<"openai-completions"> {
+  return {
+    id: handle.id,
+    name: handle.name,
+    api: "openai-completions" as const,
+    provider: "openai-compatible",
+    baseUrl: handle.endpoint,
+    reasoning: false,
+    input: ["text" as const],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 262144,
+    maxTokens: 4096,
+    compat: {
+      supportsStore: false,
+      supportsDeveloperRole: false,
+      supportsReasoningEffort: false,
+      supportsStrictMode: false,
+      maxTokensField: "max_tokens" as const,
+    },
+  };
+}
+
+function resolveTools(value: string | undefined): string[] {
+  const mode = value ?? "agent";
+  if (mode === "none") return [];
+  if (mode === "read-only") return ["read", "grep", "find", "ls"];
+  if (mode === "agent") return ["read", "grep", "find", "ls", "bash"];
+  if (mode === "coding") return ["read", "grep", "find", "ls", "bash", "edit", "write"];
+  return mode.split(",").map((t) => t.trim()).filter(Boolean);
+}
+
+function extractAssistantText(message: unknown): string {
+  if (!isRecord(message) || message.role !== "assistant" || !Array.isArray(message.content)) return "";
+  return message.content
+    .filter(isRecord)
+    .filter((c) => c.type === "text" && typeof c.text === "string")
+    .map((c) => String(c.text))
+    .join("");
+}
+
+function extractAssistantError(message: unknown): string | undefined {
+  if (!isRecord(message) || message.role !== "assistant" || message.stopReason !== "error") return undefined;
+  return typeof message.errorMessage === "string" ? message.errorMessage : "unknown error";
+}
+
+function createMinimalResourceLoader(): ResourceLoader {
+  return {
+    getExtensions: () => ({ extensions: [], errors: [], runtime: createExtensionRuntime() }),
+    getSkills: () => ({ skills: [], diagnostics: [] }),
+    getPrompts: () => ({ prompts: [], diagnostics: [] }),
+    getThemes: () => ({ themes: [], diagnostics: [] }),
+    getAgentsFiles: () => ({ agentsFiles: [] }),
+    getSystemPrompt: () => "You are a minimal test assistant. Answer the user directly.",
+    getAppendSystemPrompt: () => [],
+    extendResources: () => {},
+    reload: async () => {},
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/terminal/app.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+/**
+ * Downcity Agent 入口与状态机调度。
+ *
+ * 状态流转：
+ *   selectIdentity → Admin → adminLoop → selectIdentity (switch identity)
+ *   selectIdentity → User  → userLoop  → selectIdentity (switch identity)
+ *   selectIdentity → Manage Servers → selectIdentity
+ *
+ * 不再持有 config 快照，每次需要时从磁盘 readConfig()。
+ */
+
+import { readFileSync } from "node:fs";
+import { intro } from "./core/ui.js";
+import { readActiveServer, readConfig, writeConfig } from "./core/session.js";
+import { parseArgs } from "./core/env.js";
+import { selectIdentity } from "./auth/mode-select.js";
+import { adminAuth } from "./auth/admin.js";
+import { userAuth } from "./auth/user.js";
+import { ensureServerConfigured, manageServersMenu } from "./auth/server-switch.js";
+import { userLoop } from "./user/loop.js";
+import { adminLoop } from "./admin/loop.js";
+import { show, showError, showSuccess } from "./core/ui.js";
+import { updateCityCLI } from "./core/update.js";
+
+export async function runTerminalApp(argv: string[] = []): Promise<void> {
+  const cli = parseArgs(argv);
+  if (cli.command === "update") {
+    await runSelfUpdate();
+    return;
+  }
+
+  intro(`Downcity Terminal v${readCityVersion()} (Esc to go back, Ctrl+C to exit)`);
+  if (!(await ensureServerConfigured())) {
+    return;
+  }
+
+  let identity = await selectIdentity();
+
+  while (identity !== "quit") {
+    if (identity === "update") {
+      await runSelfUpdate();
+      return;
+    }
+
+    if (identity === "servers") {
+      await manageServersMenu();
+      if (!(await ensureServerConfigured())) {
+        return;
+      }
+      identity = await selectIdentity();
+      continue;
+    }
+
+    // 每次从磁盘读取最新 config，不持快照
+    const cfg = readConfig();
+    const activeServer = readActiveServer();
+    if (!activeServer) {
+      if (!(await ensureServerConfigured())) {
+        return;
+      }
+      identity = await selectIdentity();
+      continue;
+    }
+    writeConfig({ ...cfg, last_identity: identity });
+
+    if (identity === "admin") {
+      const session = await adminAuth(activeServer);
+      if (!session) { identity = await selectIdentity(); continue; }
+      const result = await adminLoop(session);
+      if (result === "quit") break;
+      if (result === "switch_identity") { identity = await selectIdentity(); continue; }
+      identity = await selectIdentity();
+      continue;
+    }
+
+    // identity === "user"
+    const ctx = await userAuth(activeServer.base_url);
+    if (!ctx) { identity = await selectIdentity(); continue; }
+    const result = await userLoop(ctx);
+    if (result === "quit") break;
+    if (result === "switch_identity") { identity = await selectIdentity(); continue; }
+    identity = await selectIdentity();
+  }
+}
+
+/**
+ * 读取当前 city 包版本。
+ *
+ * 关键说明（中文）
+ * - 运行源码时从仓库 package.json 读取
+ * - 发布后的全局安装同样从包根目录 package.json 读取
+ * - 读取失败时回退到 unknown，避免 CLI 启动被版本展示阻断
+ */
+function readCityVersion(): string {
+  try {
+    const packageJsonPath = new URL("../../package.json", import.meta.url);
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+      version?: string;
+    };
+    return String(packageJson.version ?? "unknown");
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * 执行 CLI 自更新，并提示用户重新启动。
+ */
+async function runSelfUpdate(): Promise<void> {
+  try {
+    show("Updating downcity CLI...");
+    const result = await updateCityCLI();
+    showSuccess(`downcity updated via ${result.mode} mode -> v${result.version}`);
+    show("Please run `downcity` again to use the updated CLI.");
+  } catch (error) {
+    showError(error instanceof Error ? error.message : String(error));
+  }
+}

package/src/terminal/auth/admin.ts

@@ -0,0 +1,21 @@
+/**
+ * Admin 鉴权模块。
+ *
+ * 当前版本直接复用当前 active server 上保存的 admin_secret_key。
+ */
+
+import { type AdminSession, type ServerProfile } from "../core/session.js";
+import { showError } from "../core/ui.js";
+
+export async function adminAuth(server: ServerProfile): Promise<AdminSession | undefined> {
+  const adminSecretKey = String(server.admin_secret_key ?? "").trim();
+  if (!adminSecretKey) {
+    showError("Current server is missing admin_secret_key. Use Manage Servers -> Edit Server.");
+    return undefined;
+  }
+
+  return {
+    base_url: server.base_url,
+    admin_token: adminSecretKey,
+  };
+}

package/src/terminal/auth/mode-select.ts

@@ -0,0 +1,38 @@
+/**
+ * 身份选择模块。
+ *
+ * 始终显示菜单，围绕当前 active server 进入身份或 server 管理。
+ */
+
+import { readActiveServer, readConfig, readUserSession } from "../core/session.js";
+import { select, isCancel } from "@clack/prompts";
+
+export type Identity = "admin" | "user" | "servers" | "update" | "quit";
+
+/**
+ * 选择身份。始终显示菜单，已有 session 的身份标注 ★。
+ */
+export async function selectIdentity(): Promise<Identity> {
+  const config = readConfig();
+  const activeServer = readActiveServer();
+
+  const hasAdmin = !!String(activeServer?.admin_secret_key ?? "").trim();
+  const hasUser = activeServer ? !!readUserSession(activeServer.base_url) : false;
+  const title = activeServer
+    ? `Identity [${activeServer.name}]`
+    : "Identity [No servers configured]";
+
+  const selected = await select({
+    message: title,
+    options: [
+      { label: hasAdmin ? "★ Admin" : "   Admin", value: "admin", hint: hasAdmin ? activeServer?.base_url ?? "" : "Admin management" },
+      { label: hasUser ? "★ User" : "   User", value: "user", hint: hasUser ? "session active" : "Login or register" },
+      { label: "Manage Servers", value: "servers", hint: `${config.servers.length} configured` },
+      { label: "Update CLI", value: "update", hint: "Refresh global downcity command" },
+      { label: "Quit", value: "quit" },
+    ],
+  });
+
+  if (!selected || isCancel(selected)) return "quit";
+  return selected as Identity;
+}

package/src/terminal/auth/server-switch.ts

@@ -0,0 +1,275 @@
+/**
+ * Server 管理模块。
+ *
+ * 关键说明（中文）
+ * - 不再提供“切换当前 server”的临时入口
+ * - 所有 server 操作都统一收口到 Manage Servers
+ * - 没有 server 时，CLI 会先强制进入添加流程
+ */
+
+import { AdminClient } from "@downcity/conduit";
+import { isCancel, password, select, text } from "@clack/prompts";
+import {
+  addServer,
+  readActiveServer,
+  readConfig,
+  readServer,
+  removeServer,
+  setActiveServer,
+  type ServerProfile,
+  updateServer,
+} from "../core/session.js";
+import { show, showError, showSuccess } from "../core/ui.js";
+
+/**
+ * 确保至少存在一个 server。
+ */
+export async function ensureServerConfigured(): Promise<boolean> {
+  if (readConfig().servers.length > 0) {
+    return true;
+  }
+
+  show("No servers configured. Add a server before continuing.");
+  const created = await promptAddServer();
+  if (!created) {
+    showError("No server configured. Exiting.");
+    return false;
+  }
+  return true;
+}
+
+/**
+ * 顶层 server 管理菜单。
+ */
+export async function manageServersMenu(): Promise<void> {
+  while (true) {
+    const config = readConfig();
+    const active = readActiveServer();
+
+    const selected = await select({
+      message: active
+        ? `Manage Servers [current: ${active.name}]`
+        : "Manage Servers [no active server]",
+      options: [
+        { label: "List Servers", value: "list", hint: `${config.servers.length} configured` },
+        { label: "Add Server", value: "add", hint: "Create a new Infra server profile" },
+        { label: "Select Active Server", value: "select", hint: active ? active.base_url : "Choose current server" },
+        { label: "Edit Server", value: "edit", hint: "Update name, server URL, or admin key" },
+        { label: "Remove Server", value: "remove", hint: "Delete a server profile" },
+        { label: "Back", value: "back", hint: "Return to main menu" },
+      ],
+    });
+
+    if (!selected || isCancel(selected) || selected === "back") {
+      return;
+    }
+
+    if (selected === "list") {
+      printServers(config.servers, active?.base_url);
+      continue;
+    }
+
+    if (selected === "add") {
+      await promptAddServer();
+      continue;
+    }
+
+    if (selected === "select") {
+      await promptSelectActiveServer();
+      continue;
+    }
+
+    if (selected === "edit") {
+      await promptEditServer();
+      continue;
+    }
+
+    if (selected === "remove") {
+      await promptRemoveServer();
+    }
+  }
+}
+
+/**
+ * 添加 server。
+ */
+export async function promptAddServer(): Promise<ServerProfile | undefined> {
+  const baseUrl = await text({
+    message: "Server URL",
+    placeholder: "https://downcity.wangenius.workers.dev",
+  });
+  if (!baseUrl || isCancel(baseUrl) || !String(baseUrl).trim()) {
+    return undefined;
+  }
+
+  const adminSecretKey = await password({ message: "admin_secret_key" });
+  if (!adminSecretKey || isCancel(adminSecretKey) || !String(adminSecretKey).trim()) {
+    return undefined;
+  }
+
+  const server = addServer({
+    base_url: String(baseUrl).trim(),
+    admin_secret_key: String(adminSecretKey).trim(),
+  });
+
+  const verified = await verifyServerAdminAccess(server);
+  if (verified) {
+    showSuccess(`Server added and activated: ${server.name}`);
+  } else {
+    showError(`Server saved, but admin verification failed: ${server.name}`);
+  }
+
+  return server;
+}
+
+async function promptSelectActiveServer(): Promise<void> {
+  const config = readConfig();
+  if (config.servers.length === 0) {
+    showError("No servers configured.");
+    return;
+  }
+
+  const selected = await select({
+    message: "Select active server",
+    options: config.servers.map((server) => ({
+      label: server.base_url === config.active_server_url ? `★ ${server.name}` : `   ${server.name}`,
+      value: server.base_url,
+      hint: server.base_url,
+    })),
+  });
+
+  if (!selected || isCancel(selected)) {
+    return;
+  }
+
+  setActiveServer(String(selected));
+  showSuccess(`Active server: ${String(selected)}`);
+}
+
+async function promptEditServer(): Promise<void> {
+  const config = readConfig();
+  if (config.servers.length === 0) {
+    showError("No servers configured.");
+    return;
+  }
+
+  const targetBaseUrl = await select({
+    message: "Edit server",
+    options: config.servers.map((server) => ({
+      label: server.base_url === config.active_server_url ? `★ ${server.name}` : `   ${server.name}`,
+      value: server.base_url,
+      hint: server.base_url,
+    })),
+  });
+  if (!targetBaseUrl || isCancel(targetBaseUrl)) {
+    return;
+  }
+
+  const current = readServer(String(targetBaseUrl));
+  if (!current) {
+    showError("Selected server no longer exists.");
+    return;
+  }
+
+  const field = await select({
+    message: `Edit ${current.name}`,
+    options: [
+      { label: "Name", value: "name", hint: current.name },
+      { label: "Server URL", value: "base_url", hint: current.base_url },
+      { label: "Admin secret key", value: "admin_secret_key", hint: maskSecret(current.admin_secret_key) },
+      { label: "Cancel", value: "cancel", hint: "Return without changes" },
+    ],
+  });
+  if (!field || isCancel(field) || field === "cancel") {
+    return;
+  }
+
+  const next = { ...current };
+
+  if (field === "name") {
+    const name = await text({ message: "Display name", initialValue: current.name });
+    if (!name || isCancel(name)) return;
+    next.name = String(name).trim() || current.name;
+  } else if (field === "base_url") {
+    const baseUrl = await text({ message: "Server URL", initialValue: current.base_url });
+    if (!baseUrl || isCancel(baseUrl)) return;
+    next.base_url = String(baseUrl).trim() || current.base_url;
+  } else if (field === "admin_secret_key") {
+    const adminSecretKey = await password({ message: "admin_secret_key" });
+    if (!adminSecretKey || isCancel(adminSecretKey)) return;
+    next.admin_secret_key = String(adminSecretKey).trim();
+  }
+
+  const updated = updateServer(current.base_url, next);
+  const verified = await verifyServerAdminAccess(updated);
+  if (verified) {
+    showSuccess(`Server updated: ${updated.name}`);
+  } else {
+    showError(`Server updated, but admin verification failed: ${updated.name}`);
+  }
+}
+
+async function promptRemoveServer(): Promise<void> {
+  const config = readConfig();
+  if (config.servers.length === 0) {
+    showError("No servers configured.");
+    return;
+  }
+
+  const selected = await select({
+    message: "Remove server",
+    options: [
+      ...config.servers.map((server) => ({
+        label: `${server.base_url === config.active_server_url ? "★ " : ""}${server.name}`,
+        value: server.base_url,
+        hint: server.base_url,
+      })),
+      { label: "Cancel", value: "cancel", hint: "Return without changes" },
+    ],
+  });
+  if (!selected || isCancel(selected) || selected === "cancel") {
+    return;
+  }
+
+  removeServer(String(selected));
+  const nextActive = readActiveServer();
+  showSuccess(
+    nextActive
+      ? `Server removed. Current server: ${nextActive.name}`
+      : "Server removed. No servers configured.",
+  );
+}
+
+async function verifyServerAdminAccess(server: ServerProfile): Promise<boolean> {
+  try {
+    const admin = new AdminClient({
+      base_url: server.base_url,
+      admin_secret_key: server.admin_secret_key,
+    });
+    await admin.listServices();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function printServers(servers: ServerProfile[], activeBaseUrl: string | undefined): void {
+  if (servers.length === 0) {
+    show("No servers configured.");
+    return;
+  }
+
+  console.log(`\n${servers.length} servers:\n`);
+  for (const server of servers) {
+    const marker = server.base_url === activeBaseUrl ? "★" : " ";
+    console.log(` ${marker} ${server.name.padEnd(24)} ${server.base_url}  admin=${maskSecret(server.admin_secret_key)}`);
+  }
+  console.log("");
+}
+
+function maskSecret(value: string): string {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) return "(missing)";
+  if (normalized.length <= 8) return `${normalized.slice(0, 2)}***`;
+  return `${normalized.slice(0, 4)}***${normalized.slice(-2)}`;
+}