@downcity/city 1.1.39 → 1.1.47

package/src/cli/agent/AgentChatTypes.ts

@@ -15,18 +15,16 @@ export const AGENT_CHAT_DEFAULT_SESSION_ID = "local-cli-chat-main";
  * `city agent chat` 命令选项。
  */
 export interface AgentChatCliOptions {
-  /** 目标 agent 名称。 */
+  /** 目标 agent id。 */
   to?: string;
   /** 一次性发送的消息文本。 */
   message?: string;
   /** 是否输出 JSON。 */
   json?: boolean;
-  /** 覆盖目标 runtime host。 */
+  /** 覆盖目标 RPC host。 */
   host?: string;
-  /** 覆盖目标 runtime port。 */
+  /** 覆盖目标 RPC port。 */
   port?: number;
-  /** 显式覆盖 Bearer Token。 */
-  token?: string;
 }
 
 /**
@@ -45,7 +43,7 @@ export interface AgentChatExecuteResult {
  * SDK prompt 响应体。
  */
 export interface AgentChatExecuteResponse {
-  /** HTTP 路由层是否成功处理请求。 */
+  /** 本轮 chat 执行是否成功。 */
   success: boolean;
   /** 实际执行使用的 sessionId。 */
   sessionId?: string;
@@ -59,20 +57,18 @@ export interface AgentChatExecuteResponse {
  * 复用 chat transport 时的基础选项。
  */
 export interface AgentChatTransportOptions {
-  /** 覆盖目标 runtime host。 */
+  /** 覆盖目标 RPC host。 */
   host?: string;
-  /** 覆盖目标 runtime port。 */
+  /** 覆盖目标 RPC port。 */
   port?: number;
-  /** 显式覆盖 Bearer Token。 */
-  token?: string;
 }
 
 /**
  * 单轮 chat 执行结果。
  */
 export interface AgentChatExecutionOutcome {
-  /** 目标 agent 名称。 */
-  agentName: string;
+  /** 目标 agent id。 */
+  agentId: string;
   /** 目标 agent 项目根目录。 */
   projectRoot?: string;
   /** 实际执行使用的 sessionId。 */

package/src/cli/agent/AgentHistory.ts

@@ -23,7 +23,7 @@ import type {
 } from "./AgentHistoryTypes.js";
 import { emitCliBlock } from "../shared/CliReporter.js";
 import { printResult } from "@/utils/cli/CliOutput.js";
-import { resolveAgentName } from "../shared/IndexSupport.js";
+import { resolveAgentId } from "../shared/IndexSupport.js";
 
 function normalizeText(input: unknown): string {
   return String(input || "").trim();
@@ -149,7 +149,7 @@ export async function agentHistoryCleanCommand(
 
   const sessionDir = getDowncitySessionDirPath(
     projectRoot,
-    resolveAgentName(projectRoot),
+    resolveAgentId(projectRoot),
     sessionId,
   );
   const chatDir = getDowncityChatSessionDirPath(projectRoot, sessionId);

package/src/cli/agent/AgentManager.ts

@@ -56,9 +56,8 @@ async function loadAgentSummaries(): Promise<AgentManagerAgentSummary[]> {
   const agents = await listRegisteredAgentsForCli();
   return agents.map((agent) => {
     const config = readAgentConfig(agent.projectRoot);
-    const configuredName = String(config?.name || "").trim();
     return {
-      name: configuredName || agent.name,
+      id: String(config?.id || "").trim() || agent.id,
       projectRoot: agent.projectRoot,
       status: agent.status,
       modelId: readAgentModelId(config),
@@ -149,7 +148,7 @@ async function emitAgentManagerList(): Promise<void> {
     summary: `${agents.length} registered`,
     items: agents.map((agent) => ({
       tone: agent.status === "running" ? "success" : "info",
-      title: agent.name,
+      title: agent.id,
       facts: [
         { label: "Status", value: agent.status },
         { label: "Model", value: agent.modelId || "not configured" },
@@ -219,7 +218,7 @@ async function promptAgentProjectRoot(): Promise<AgentManagerAgentSummary | null
     name: "projectRoot",
     message: "选择要管理的 Agent",
     choices: agents.map((agent) => ({
-      title: agent.name,
+      title: agent.id,
       description: `${formatAgentListDescription(agent)} · ${agent.projectRoot}`,
       value: agent.projectRoot,
     })),
@@ -237,7 +236,7 @@ async function promptAgentAction(
   const response = (await prompts({
     type: "select",
     name: "action",
-    message: `管理 agent · ${agent.name}`,
+    message: `管理 agent · ${agent.id}`,
     choices: [
       {
         title: "查看状态",
@@ -265,9 +264,9 @@ async function promptAgentAction(
         value: "chat",
       },
       {
-        title: "配置名称",
-        description: `当前：${agent.name}`,
-        value: "configureName",
+        title: "配置 ID",
+        description: `当前：${agent.id}`,
+        value: "configureId",
       },
       {
         title: "配置模型",
@@ -363,50 +362,50 @@ async function runStartFlow(): Promise<void> {
   await startAgentProject(projectRoot);
 }
 
-async function configureAgentName(agent: AgentManagerAgentSummary): Promise<AgentManagerAgentSummary> {
+async function configureAgentId(agent: AgentManagerAgentSummary): Promise<AgentManagerAgentSummary> {
   const response = (await prompts({
     type: "text",
-    name: "name",
-    message: "Agent 名称",
-    initial: agent.name,
+    name: "id",
+    message: "Agent ID",
+    initial: agent.id,
     validate: (value) =>
-      String(value || "").trim().length > 0 ? true : "Agent 名称不能为空",
-  })) as { name?: string };
+      String(value || "").trim().length > 0 ? true : "Agent ID 不能为空",
+  })) as { id?: string };
 
-  if (response.name === undefined) {
+  if (response.id === undefined) {
     emitCliBlock({
       tone: "info",
-      title: "Agent name unchanged",
+      title: "Agent id unchanged",
     });
     return agent;
   }
 
-  const nextName = String(response.name || "").trim();
-  if (nextName === agent.name) {
+  const nextId = String(response.id || "").trim();
+  if (nextId === agent.id) {
     emitCliBlock({
       tone: "info",
-      title: "Agent name unchanged",
-      summary: agent.name,
+      title: "Agent id unchanged",
+      summary: agent.id,
     });
     return agent;
   }
 
   const shipJsonPath = getDowncityJsonPath(agent.projectRoot);
   const raw = fs.readJsonSync(shipJsonPath) as DowncityConfig;
-  raw.name = nextName;
+  raw.id = nextId;
   await fs.writeJson(shipJsonPath, raw, { spaces: 2 });
   emitCliBlock({
     tone: "success",
-    title: "Agent name updated",
+    title: "Agent id updated",
     facts: [
-      { label: "previous", value: agent.name },
-      { label: "current", value: nextName },
+      { label: "previous", value: agent.id },
+      { label: "current", value: nextId },
       { label: "project", value: agent.projectRoot },
     ],
   });
   return {
     ...agent,
-    name: nextName,
+    id: nextId,
   };
 }
 
@@ -595,11 +594,11 @@ async function runSelectedAgentManager(): Promise<void> {
         continue;
       }
       if (action === "chat") {
-        await chatCommand({ to: agent.name });
+        await chatCommand({ to: agent.id });
         continue;
       }
-      if (action === "configureName") {
-        agent = await configureAgentName(agent);
+      if (action === "configureId") {
+        agent = await configureAgentId(agent);
         continue;
       }
       if (action === "configureModel") {

package/src/cli/agent/AgentManagerTypes.ts

@@ -15,13 +15,13 @@ export type AgentManagerAgentAction =
   | "stop"
   | "restart"
   | "chat"
-  | "configureName"
+  | "configureId"
   | "configureModel"
   | "connectChannels"
   | "back";
 
 export interface AgentManagerAgentSummary {
-  name: string;
+  id: string;
   projectRoot: string;
   status: "running" | "stopped";
   modelId?: string;

package/src/cli/agent/AgentReset.ts

@@ -14,7 +14,7 @@ import { getDowncityJsonPath } from "@/config/Paths.js";
 import { PlatformStore } from "@/platform/store/index.js";
 import { emitCliBlock } from "../shared/CliReporter.js";
 import { CliError } from "../shared/CliError.js";
-import { resolveAgentName } from "../shared/IndexSupport.js";
+import { resolveAgentId } from "../shared/IndexSupport.js";
 
 /**
  * 读取当前 agent 的 execution.modelId。
@@ -100,7 +100,7 @@ export async function agentResetCommand(cwd: string = "."): Promise<void> {
     emitCliBlock({
       tone: "info",
       title: "Agent reset cancelled",
-      summary: resolveAgentName(projectRoot),
+      summary: resolveAgentId(projectRoot),
     });
     return;
   }
@@ -109,7 +109,7 @@ export async function agentResetCommand(cwd: string = "."): Promise<void> {
     emitCliBlock({
       tone: "info",
       title: "Model unchanged",
-      summary: resolveAgentName(projectRoot),
+      summary: resolveAgentId(projectRoot),
       facts: [
         { label: "modelId", value: current },
         { label: "project", value: projectRoot },
@@ -126,7 +126,7 @@ export async function agentResetCommand(cwd: string = "."): Promise<void> {
   emitCliBlock({
     tone: "success",
     title: "Agent reconfigured",
-    summary: resolveAgentName(projectRoot),
+    summary: resolveAgentId(projectRoot),
     facts: [
       { label: "previous", value: current || "(none)" },
       { label: "current", value: nextModelId },

package/src/cli/agent/AgentSelection.ts

@@ -22,7 +22,7 @@ import type {
 import { emitCliBlock, emitCliList } from "../shared/CliReporter.js";
 import { printResult } from "@/utils/cli/CliOutput.js";
 import { CliError } from "../shared/CliError.js";
-import { resolveAgentName } from "../shared/IndexSupport.js";
+import { resolveAgentId } from "../shared/IndexSupport.js";
 import { resolveRunningManagedAgents } from "../control-plane/ControlPlaneProcess.js";
 
 /**
@@ -40,7 +40,7 @@ function toCliRegisteredAgentView(
 ): CliRegisteredAgentView {
   const projectRoot = resolve(String(entry.projectRoot || "").trim() || ".");
   return {
-    name: resolveAgentName(projectRoot),
+    id: resolveAgentId(projectRoot),
     projectRoot,
     status: entry.status === "stopped" ? "stopped" : "running",
   };
@@ -66,7 +66,7 @@ export async function listRegisteredAgentsForCli(): Promise<CliRegisteredAgentVi
       } satisfies CliRegisteredAgentView;
     })
     .sort((left, right) =>
-      left.name.localeCompare(right.name) || left.projectRoot.localeCompare(right.projectRoot),
+      left.id.localeCompare(right.id) || left.projectRoot.localeCompare(right.projectRoot),
     );
 }
 
@@ -77,7 +77,7 @@ export function buildCliAgentPromptChoices(
   agents: CliRegisteredAgentView[],
 ): CliAgentPromptChoice[] {
   return agents.map((agent) => ({
-    title: agent.name,
+    title: agent.id,
     value: agent.projectRoot,
     description: `${agent.status} · ${agent.projectRoot}`,
   }));
@@ -165,7 +165,7 @@ export async function emitRegisteredAgentList(): Promise<void> {
     summary: `${filteredAgents.length} registered`,
     items: filteredAgents.map((agent) => ({
       tone: agent.status === "running" ? "success" : "info",
-      title: agent.name,
+      title: agent.id,
       facts: [
         {
           label: "Project",
@@ -232,7 +232,7 @@ export async function emitRegisteredAgentListWithOptions(options?: {
       : `${agents.length} registered`,
     items: agents.map((agent) => ({
       tone: agent.status === "running" ? "success" : "info",
-      title: agent.name,
+      title: agent.id,
       facts: [
         {
           label: "Project",

package/src/cli/agent/AgentSelectionTypes.ts

@@ -3,7 +3,7 @@
  */
 
 export type CliRegisteredAgentView = {
-  name: string;
+  id: string;
   projectRoot: string;
   status: "running" | "stopped";
 };

package/src/cli/agent/Init.ts

@@ -18,7 +18,7 @@ import fg from "fast-glob";
 import { getProfileMdPath, getDowncityJsonPath, getSoulMdPath } from "@/config/Paths.js";
 import {
   initializeAgentProject,
-  normalizeDefaultAgentName,
+  normalizeDefaultAgentId,
 } from "@downcity/agent";
 import type { AgentProjectChannel } from "@downcity/agent";
 import type { ExecutionBindingConfig } from "@downcity/agent";
@@ -30,7 +30,7 @@ import {
 } from "@/model/runtime/ExecutionModelBinding.js";
 
 type InitPromptResponse = {
-  name?: string;
+  id?: string;
   primaryModelId?: string;
   channels?: string[];
 };
@@ -51,8 +51,8 @@ export async function initCommand(
 ): Promise<void> {
   const projectRoot = path.resolve(cwd);
   const projectBaseName = path.basename(projectRoot);
-  const defaultAgentName =
-    normalizeDefaultAgentName(projectBaseName) || projectBaseName;
+  const default_agent_id =
+    normalizeDefaultAgentId(projectBaseName) || projectBaseName;
   let allowOverwrite = Boolean(options.force);
 
   emitCliBlock({
@@ -96,13 +96,13 @@ export async function initCommand(
   }
 
   // Collect configuration information
-  // 交互采集（中文）：agent name + model + channels。
+  // 交互采集（中文）：agent id + model + channels。
   const response = (await prompts([
     {
       type: "text",
-      name: "name",
-      message: "Agent name",
-      initial: defaultAgentName,
+      name: "id",
+      message: "Agent id",
+      initial: default_agent_id,
     },
     {
       type: "select",
@@ -124,9 +124,9 @@ export async function initCommand(
     },
   ])) as InitPromptResponse;
 
-  // 关键点（中文）：agent_name 同时用于 `downcity.json.name` 与 init 模板变量渲染，避免两处来源不一致。
-  const agentName =
-    String(response.name || "").trim() || defaultAgentName;
+  // 关键点（中文）：agent_id 同时用于 `downcity.json.id` 与 init 模板变量渲染，避免两处来源不一致。
+  const agent_id =
+    String(response.id || "").trim() || default_agent_id;
   const primaryModelId =
     String(response.primaryModelId || "").trim() || "default";
   if (modelChoiceIds.length === 0) {
@@ -147,7 +147,7 @@ export async function initCommand(
   const initResult = await initializeAgentProject(
     {
       projectRoot,
-      agentName,
+      id: agent_id,
       execution,
       channels: selectedChannels,
       forceOverwriteShipJson: allowOverwrite,
@@ -172,7 +172,7 @@ export async function initCommand(
   emitCliBlock({
     tone: "success",
     title: "Initialization complete",
-    summary: agentName,
+    summary: agent_id,
   });
   emitCliList({
     tone: "accent",

package/src/cli/agent/Restart.ts

@@ -13,7 +13,7 @@ import { buildRunArgsFromOptions } from "@/process/daemon/CliArgs.js";
 import { startDaemonProcess, stopDaemonProcess } from "@/process/daemon/Manager.js";
 import type { StartOptions } from "@downcity/agent";
 import { emitCliBlock } from "../shared/CliReporter.js";
-import { resolveAgentName } from "../shared/IndexSupport.js";
+import { resolveAgentId } from "../shared/IndexSupport.js";
 import { checkAgentPreflight } from "../shared/PluginTargetSupport.js";
 import { CliError } from "../shared/CliError.js";
 
@@ -51,7 +51,7 @@ export async function restartCommand(
     emitCliBlock({
       tone: "success",
       title: "Agent daemon restarted",
-      summary: resolveAgentName(projectRoot),
+      summary: resolveAgentId(projectRoot),
       facts: [
         {
           label: "Project",

package/src/cli/agent/Run.ts

@@ -16,13 +16,15 @@ import {
   loadDowncityConfig,
   loadStaticSystemPrompts,
   shellTools,
+  startServer,
   StaticPromptCatalog,
 } from "@downcity/agent";
 import { createBuiltinPlugins } from "@downcity/plugins";
 import type { StartOptions } from "@downcity/agent";
 import { CliError } from "../shared/CliError.js";
 import { createRuntimeModel } from "@/model/runtime/CreateRuntimeModel.js";
-import { resolveAgentName } from "../shared/IndexSupport.js";
+import { readPlatformGlobalEnv } from "@/env/ProcessEnv.js";
+import { resolveAgentId } from "../shared/IndexSupport.js";
 
 /**
  * 前台启动入口（由 `agent start` 前台模式与内部 daemon 子进程复用）。
@@ -30,7 +32,7 @@ import { resolveAgentName } from "../shared/IndexSupport.js";
  * 职责（中文）
  * - 初始化 agent 状态（配置、日志、services 依赖）
  * - 解析并合并启动参数（CLI > downcity.json > 默认值）
- * - 启动主 HTTP 服务
+ * - 启动 agent 本机 RPC 与 city 托管的 HTTP gateway（双端口）
  * - 启动 services（例如 task cron）
  * - 统一处理进程信号并优雅停机
  */
@@ -39,6 +41,7 @@ export async function runCommand(
   options: StartOptions,
 ): Promise<void> {
   const projectRoot = path.resolve(cwd);
+  const hostEnv = readPlatformGlobalEnv();
   // 端口解析（中文）：允许 number / string；空值返回 undefined 以便走配置回退链。
   const parsePort = (
     value: string | number | undefined,
@@ -57,30 +60,41 @@ export async function runCommand(
   };
   // Resolve startup options: CLI flags override built-in defaults.
   let port: number;
+  let rpc_port: number;
   try {
     port = parsePort(options.port, "port") ?? 5314;
+    rpc_port = parsePort(options.rpcPort, "rpcPort") ?? 15314;
   } catch (error) {
     throw new CliError({
       title: "Invalid start options",
       note: error instanceof Error ? error.message : String(error),
     });
   }
+  if (port === rpc_port) {
+    throw new CliError({
+      title: "Invalid start options",
+      note: "port and rpcPort must be different",
+    });
+  }
 
   const host = (options.host ?? "0.0.0.0").trim();
-  const agentName = resolveAgentName(projectRoot);
+  const rpc_host = "127.0.0.1";
+  const agentId = resolveAgentId(projectRoot);
   let currentSystems = loadStaticSystemPrompts(projectRoot);
   const config = loadDowncityConfig(projectRoot);
   const model = await createRuntimeModel({
     config,
+    env: hostEnv,
   });
 
   const agent = new Agent({
-    id: agentName,
+    id: agentId,
     path: projectRoot,
     instruction: currentSystems,
     tools: shellTools,
     plugins: createBuiltinPlugins(),
     model,
+    env: hostEnv,
   });
 
   const promptCatalog = new StaticPromptCatalog({
@@ -94,30 +108,36 @@ export async function runCommand(
   });
   promptCatalog.start();
 
-  process.env.DC_SERVER_PORT = String(port);
-  process.env.DC_SERVER_HOST = host;
+  process.env.DC_CITY_PORT = String(port);
+  process.env.DC_CITY_HOST = host;
+  process.env.DC_AGENT_RPC_PORT = String(rpc_port);
+  process.env.DC_AGENT_RPC_HOST = rpc_host;
+  process.env.DC_AGENT_ID = agentId;
   process.env.DC_AGENT_PATH = projectRoot;
-  process.env.DC_AGENT_NAME = agentName;
 
   const startResult = await agent.start({
-    http: {
-      port,
-      host,
+    rpc: {
+      port: rpc_port,
+      host: rpc_host,
     },
-    rpc: true,
     plugins: true,
   });
-
-  const server = startResult.http?.server;
-  const localRpc = startResult.rpc?.server;
-  if (!server || !localRpc) {
-    throw new Error("Agent start did not return expected HTTP/RPC bindings");
+  if (!startResult.rpc?.server) {
+    throw new Error("Agent start did not return expected RPC binding");
   }
 
+  const server = await startServer({
+    host,
+    port,
+    getAgentRuntime: () => agent.getRuntime(),
+    getAgentContext: () => agent.getContext(),
+    sessionCollection: agent.getSessionCollection(),
+  });
+
   const agentLogger = agent.getLogger();
 
   // 处理进程信号
-  // 停机顺序（中文）：plugin runtimes -> API server -> flush logs。
+  // 停机顺序（中文）：HTTP gateway -> plugin runtimes / RPC server -> flush logs。
   let isShuttingDown = false;
   const shutdown = async (signal: string) => {
     if (isShuttingDown) return;
@@ -126,6 +146,7 @@ export async function runCommand(
     agentLogger.info(`Received ${signal} signal, shutting down...`);
     promptCatalog.stop();
 
+    await server.stop();
     await agent.stop();
 
     // Save logs

package/src/cli/agent/Start.ts

@@ -17,7 +17,7 @@ import { startDaemonProcess } from "@/process/daemon/Manager.js";
 import { buildRunArgsFromOptions } from "@/process/daemon/CliArgs.js";
 import type { StartOptions } from "@downcity/agent";
 import { emitCliBlock } from "../shared/CliReporter.js";
-import { resolveAgentName } from "../shared/IndexSupport.js";
+import { resolveAgentId } from "../shared/IndexSupport.js";
 import { checkAgentPreflight } from "../shared/PluginTargetSupport.js";
 import { CliError } from "../shared/CliError.js";
 
@@ -55,7 +55,7 @@ export async function startCommand(
     emitCliBlock({
       tone: "success",
       title: "Agent daemon started",
-      summary: resolveAgentName(projectRoot),
+      summary: resolveAgentId(projectRoot),
       facts: [
         {
           label: "Project",

package/src/cli/agent/Stop.ts

@@ -10,7 +10,7 @@
 import path from "path";
 import { stopDaemonProcess } from "@/process/daemon/Manager.js";
 import { emitCliBlock } from "../shared/CliReporter.js";
-import { resolveAgentName } from "../shared/IndexSupport.js";
+import { resolveAgentId } from "../shared/IndexSupport.js";
 
 /**
  * stop 命令执行流程。
@@ -26,7 +26,7 @@ export async function stopCommand(cwd: string = "."): Promise<void> {
   emitCliBlock({
     tone: result.stopped ? "success" : "info",
     title: result.stopped ? "Agent daemon stopped" : "Agent daemon not running",
-    summary: resolveAgentName(projectRoot),
+    summary: resolveAgentId(projectRoot),
     facts: [
       {
         label: "Project",

package/src/cli/control-plane/ControlPlaneProcess.ts

@@ -42,7 +42,7 @@ import { startCommand } from "../agent/Start.js";
 import type { StartOptions } from "@downcity/agent";
 import {
   injectAgentContext,
-  resolveAgentName,
+  resolveAgentId,
   sleep,
 } from "../shared/IndexSupport.js";
 import { buildRuntimePortFacts } from "../shared/PortHints.js";
@@ -202,11 +202,11 @@ export async function stopCityRuntimeCommand(params?: { timeoutMs?: number }): P
       try {
         const result = await runWithSpinner(
           () => stopDaemonProcess({ projectRoot: item.projectRoot }),
-          { text: `Stopping ${resolveAgentName(item.projectRoot)}...` },
+          { text: `Stopping ${resolveAgentId(item.projectRoot)}...` },
         );
         emitCliBlock({
           tone: result.stopped ? "success" : "info",
-          title: resolveAgentName(item.projectRoot),
+          title: resolveAgentId(item.projectRoot),
           summary: result.stopped ? "stopped" : "already stopped",
           facts: [{ label: "project", value: item.projectRoot }],
         });
@@ -214,7 +214,7 @@ export async function stopCityRuntimeCommand(params?: { timeoutMs?: number }): P
       } catch (error) {
         emitCliBlock({
           tone: "error",
-          title: resolveAgentName(item.projectRoot),
+          title: resolveAgentId(item.projectRoot),
           summary: "failed",
           facts: [
             { label: "project", value: item.projectRoot },
@@ -368,7 +368,7 @@ export async function restartManagedAgents(cliPath: string): Promise<void> {
       emitCliBlock({
         tone: "error",
         title: "Managed agent restart failed",
-        summary: resolveAgentName(item.projectRoot),
+        summary: resolveAgentId(item.projectRoot),
         facts: [
           {
             label: "Project",

package/src/cli/model/ModelCreateCommand.ts

@@ -102,7 +102,7 @@ async function runInteractiveProviderCreate(
     {
       type: "text",
       name: "apiKey",
-      message: "API Key（支持 ${ENV_VAR}）",
+      message: "API Key",
       validate: (value: string) =>
         String(value || "").trim().length > 0 ? true : "apiKey 不能为空",
     },