@downcity/agent 1.1.8 → 1.1.11

package/src/server/http/static/static.ts

@@ -0,0 +1,104 @@
+/**
+ * 静态资源路由模块。
+ *
+ * 职责说明：
+ * 1. 提供根目录前端静态文件访问。
+ * 2. 提供 `.downcity/public` 的受限文件暴露。
+ * 3. 只处理静态资源协议，不承载业务逻辑。
+ */
+
+import { Hono } from "hono";
+import fs from "fs-extra";
+import path from "path";
+import { getDowncityPublicDirPath } from "@/config/Paths.js";
+import { getAgentRuntime } from "@/runtime/AgentRuntime.js";
+
+/**
+ * 静态资源路由。
+ */
+export const staticRouter = new Hono();
+
+staticRouter.get("/", async (c) => {
+  const indexPath = path.join(getAgentRuntime().rootPath, "public", "index.html");
+  if (await fs.pathExists(indexPath)) {
+    const content = await fs.readFile(indexPath, "utf-8");
+    return c.body(content, 200, {
+      "Content-Type": "text/html; charset=utf-8",
+      "Cache-Control": "no-cache",
+    });
+  }
+  return c.text("Downcity Agent Server", 200);
+});
+
+staticRouter.get("/styles.css", async (c) => {
+  const cssPath = path.join(getAgentRuntime().rootPath, "public", "styles.css");
+  if (await fs.pathExists(cssPath)) {
+    const content = await fs.readFile(cssPath, "utf-8");
+    return c.body(content, 200, {
+      "Content-Type": "text/css; charset=utf-8",
+      "Cache-Control": "no-cache",
+    });
+  }
+  return c.text("Not Found", 404);
+});
+
+staticRouter.get("/app.js", async (c) => {
+  const jsPath = path.join(getAgentRuntime().rootPath, "public", "app.js");
+  if (await fs.pathExists(jsPath)) {
+    const content = await fs.readFile(jsPath, "utf-8");
+    return c.body(content, 200, {
+      "Content-Type": "application/javascript; charset=utf-8",
+      "Cache-Control": "no-cache",
+    });
+  }
+  return c.text("Not Found", 404);
+});
+
+staticRouter.get("/downcity/public/*", async (c) => {
+  const root = getDowncityPublicDirPath(getAgentRuntime().rootPath);
+  const prefix = "/downcity/public/";
+  const requestPath = c.req.path;
+  const rel = requestPath.startsWith(prefix)
+    ? requestPath.slice(prefix.length)
+    : "";
+  if (!rel) return c.text("Not Found", 404);
+
+  const full = path.resolve(root, rel);
+  const rootResolved = path.resolve(root);
+  if (full !== rootResolved && !full.startsWith(rootResolved + path.sep)) {
+    return c.text("Forbidden", 403);
+  }
+
+  try {
+    const stat = await fs.stat(full);
+    if (!stat.isFile()) return c.text("Not Found", 404);
+  } catch {
+    return c.text("Not Found", 404);
+  }
+
+  const ext = path.extname(full).toLowerCase();
+  const contentType =
+    ext === ".html"
+      ? "text/html; charset=utf-8"
+      : ext === ".css"
+        ? "text/css; charset=utf-8"
+        : ext === ".js"
+          ? "application/javascript; charset=utf-8"
+          : ext === ".json"
+            ? "application/json; charset=utf-8"
+            : ext === ".txt" || ext === ".md"
+              ? "text/plain; charset=utf-8"
+              : ext === ".pdf"
+                ? "application/pdf"
+                : ext === ".png"
+                  ? "image/png"
+                  : ext === ".jpg" || ext === ".jpeg"
+                    ? "image/jpeg"
+                    : "application/octet-stream";
+
+  const buf = await fs.readFile(full);
+  return c.body(buf, 200, {
+    "Content-Type": contentType,
+    "Cache-Control": "no-cache",
+  });
+});

package/src/server/rpc/Server.ts

@@ -0,0 +1,395 @@
+/**
+ * Local RPC server。
+ *
+ * 关键点（中文）
+ * - 只服务本地受信任进程，不暴露 HTTP 协议。
+ * - 这里承接本机 CLI 访问 agent runtime 的 IPC 路由，并与 HTTP 能力保持语义一致。
+ */
+
+import fs from "fs-extra";
+import net, { type Server } from "node:net";
+import path from "node:path";
+import type { AgentRuntime } from "@/runtime/AgentRuntimeTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { JsonValue } from "@/types/common/Json.js";
+import type { LocalRpcRequest, LocalRpcResponse, LocalRpcServerHandle } from "@/types/rpc/LocalRpc.js";
+import type { ControlSessionExecuteRequestBody } from "@/server/http/control/types/ControlSessionExecute.js";
+import type {
+  PluginActionResponse,
+  PluginAvailabilityResponse,
+  PluginListResponse,
+} from "@/plugin/types/PluginApi.js";
+import type {
+  ServiceControlAction,
+  ServiceCommandResponse,
+  ServiceControlResponse,
+  ServiceListResponse,
+} from "@/service/types/Services.js";
+import { listServiceStates, controlServiceState } from "@/service/core/ServiceStateController.js";
+import { runServiceCommand } from "@/service/core/ServiceActionRunner.js";
+import { executeBySessionId } from "@/server/http/control/ExecuteBySession.js";
+import { getLocalRpcEndpoint } from "@/transport/rpc/Paths.js";
+
+async function isSocketEndpointActive(endpoint: string): Promise<boolean> {
+  return await new Promise<boolean>((resolve) => {
+    const socket = net.createConnection(endpoint);
+    let settled = false;
+    const finish = (value: boolean): void => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(value);
+    };
+    socket.setTimeout(200);
+    socket.on("connect", () => finish(true));
+    socket.on("timeout", () => finish(false));
+    socket.on("error", () => finish(false));
+  });
+}
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function createSuccessResponse(
+  requestId: string,
+  data: JsonValue,
+  status = 200,
+): LocalRpcResponse {
+  return {
+    requestId,
+    status,
+    success: true,
+    data,
+  };
+}
+
+function createErrorResponse(
+  requestId: string,
+  status: number,
+  error: string,
+): LocalRpcResponse {
+  return {
+    requestId,
+    status,
+    success: false,
+    error,
+  };
+}
+
+async function handleServiceControl(params: {
+  requestId: string;
+  body: JsonValue | undefined;
+  context: AgentContext;
+}): Promise<LocalRpcResponse> {
+  const body = isObjectRecord(params.body) ? params.body : {};
+  const serviceName = String(body.serviceName || "").trim();
+  const action = String(body.action || "").trim() as ServiceControlAction;
+  if (!serviceName || !action) {
+    return createErrorResponse(params.requestId, 400, "serviceName and action are required");
+  }
+  const result = await controlServiceState({
+    serviceName,
+    action,
+    context: params.context,
+  });
+  const payload: ServiceControlResponse = {
+    success: result.success,
+    ...(result.service ? { service: result.service } : {}),
+    ...(result.error ? { error: result.error } : {}),
+  };
+  return createSuccessResponse(params.requestId, payload as unknown as JsonValue);
+}
+
+async function handleServiceCommand(params: {
+  requestId: string;
+  body: JsonValue | undefined;
+  context: AgentContext;
+}): Promise<LocalRpcResponse> {
+  const body = isObjectRecord(params.body) ? params.body : {};
+  const serviceName = String(body.serviceName || "").trim();
+  const command = String(body.command || "").trim();
+  if (!serviceName || !command) {
+    return createErrorResponse(params.requestId, 400, "serviceName and command are required");
+  }
+  const result = await runServiceCommand({
+    serviceName,
+    command,
+    payload: (body.payload ?? {}) as JsonValue,
+    ...(body.schedule !== undefined ? { schedule: body.schedule as JsonValue } : {}),
+    context: params.context,
+  });
+  const payload: ServiceCommandResponse = {
+    success: result.success,
+    ...(result.service ? { service: result.service } : {}),
+    ...(result.data !== undefined ? { data: result.data } : {}),
+    ...(result.message ? { message: result.message } : {}),
+    ...(result.success ? {} : { error: result.message || "service command failed" }),
+  };
+  return createSuccessResponse(params.requestId, payload as unknown as JsonValue);
+}
+
+async function handlePluginAvailability(params: {
+  requestId: string;
+  body: JsonValue | undefined;
+  context: AgentContext;
+}): Promise<LocalRpcResponse> {
+  const body = isObjectRecord(params.body) ? params.body : {};
+  const pluginName = String(body.pluginName || "").trim();
+  if (!pluginName) {
+    return createErrorResponse(params.requestId, 400, "pluginName is required");
+  }
+  const availability = await params.context.plugins.availability(pluginName);
+  const payload: PluginAvailabilityResponse = {
+    success: true,
+    pluginName,
+    availability,
+  };
+  return createSuccessResponse(params.requestId, payload as unknown as JsonValue);
+}
+
+async function handlePluginAction(params: {
+  requestId: string;
+  body: JsonValue | undefined;
+  context: AgentContext;
+}): Promise<LocalRpcResponse> {
+  const body = isObjectRecord(params.body) ? params.body : {};
+  const pluginName = String(body.pluginName || "").trim();
+  const actionName = String(body.actionName || "").trim();
+  if (!pluginName) {
+    return createErrorResponse(params.requestId, 400, "pluginName is required");
+  }
+  if (!actionName) {
+    return createErrorResponse(params.requestId, 400, "actionName is required");
+  }
+  const result = await params.context.plugins.runAction({
+    plugin: pluginName,
+    action: actionName,
+    payload: body.payload,
+  });
+  const payload: PluginActionResponse = {
+    success: result.success,
+    pluginName,
+    actionName,
+    ...(result.data !== undefined ? { data: result.data } : {}),
+    ...(result.message ? { message: result.message } : {}),
+    ...(result.error ? { error: result.error } : {}),
+  };
+  return createSuccessResponse(
+    params.requestId,
+    payload as unknown as JsonValue,
+    result.success ? 200 : 400,
+  );
+}
+
+function matchControlSessionExecutePath(pathname: string): string | null {
+  const match = /^\/api\/control\/sessions\/([^/]+)\/execute$/.exec(
+    String(pathname || "").trim(),
+  );
+  if (!match) return null;
+  try {
+    return decodeURIComponent(match[1] || "").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function handleControlSessionExecute(params: {
+  requestId: string;
+  body: JsonValue | undefined;
+  context: AgentContext;
+  runtime?: AgentRuntime;
+  sessionId: string;
+}): Promise<LocalRpcResponse> {
+  if (!params.runtime) {
+    return createErrorResponse(
+      params.requestId,
+      500,
+      "Local RPC control execute requires agent runtime",
+    );
+  }
+  const body = isObjectRecord(params.body) ? params.body : {};
+  const instructions = String(body.instructions || "").trim();
+  const attachments = Array.isArray(body.attachments)
+    ? (body.attachments as ControlSessionExecuteRequestBody["attachments"])
+    : undefined;
+  if (!params.sessionId) {
+    return createErrorResponse(params.requestId, 400, "sessionId is required");
+  }
+  if (!instructions) {
+    return createErrorResponse(params.requestId, 400, "instructions are required");
+  }
+  try {
+    const result = await executeBySessionId({
+      agentState: params.runtime,
+      executionContext: params.context,
+      sessionId: params.sessionId,
+      instructions,
+      attachments,
+    });
+    return createSuccessResponse(
+      params.requestId,
+      {
+        success: true,
+        sessionId: params.sessionId,
+        result,
+      } as unknown as JsonValue,
+    );
+  } catch (error) {
+    return createErrorResponse(params.requestId, 500, String(error));
+  }
+}
+
+async function dispatchRequest(params: {
+  request: LocalRpcRequest;
+  context: AgentContext;
+  runtime?: AgentRuntime;
+}): Promise<LocalRpcResponse> {
+  const { request } = params;
+  if (request.method === "GET" && request.path === "/api/services/list") {
+    const payload: ServiceListResponse = {
+      success: true,
+      services: listServiceStates(),
+    };
+    return createSuccessResponse(request.requestId, payload as unknown as JsonValue);
+  }
+  if (request.method === "POST" && request.path === "/api/services/control") {
+    return await handleServiceControl({
+      requestId: request.requestId,
+      body: request.body,
+      context: params.context,
+    });
+  }
+  if (request.method === "POST" && request.path === "/api/services/command") {
+    return await handleServiceCommand({
+      requestId: request.requestId,
+      body: request.body,
+      context: params.context,
+    });
+  }
+  if (request.method === "GET" && request.path === "/api/plugins/list") {
+    const payload: PluginListResponse = {
+      success: true,
+      plugins: params.context.plugins.list(),
+    };
+    return createSuccessResponse(request.requestId, payload as unknown as JsonValue);
+  }
+  if (request.method === "POST" && request.path === "/api/plugins/availability") {
+    return await handlePluginAvailability({
+      requestId: request.requestId,
+      body: request.body,
+      context: params.context,
+    });
+  }
+  if (request.method === "POST" && request.path === "/api/plugins/action") {
+    return await handlePluginAction({
+      requestId: request.requestId,
+      body: request.body,
+      context: params.context,
+    });
+  }
+  const controlSessionId =
+    request.method === "POST"
+      ? matchControlSessionExecutePath(request.path)
+      : null;
+  if (controlSessionId) {
+    return await handleControlSessionExecute({
+      requestId: request.requestId,
+      body: request.body,
+      context: params.context,
+      runtime: params.runtime,
+      sessionId: controlSessionId,
+    });
+  }
+  return createErrorResponse(
+    request.requestId,
+    404,
+    `Unknown local RPC path: ${request.method} ${request.path}`,
+  );
+}
+
+async function ensureEndpointReady(endpoint: string): Promise<void> {
+  if (process.platform === "win32") return;
+  await fs.ensureDir(path.dirname(endpoint));
+  const exists = await fs.pathExists(endpoint);
+  if (!exists) return;
+  if (await isSocketEndpointActive(endpoint)) {
+    throw new Error(`Local RPC endpoint already in use: ${endpoint}`);
+  }
+  await fs.remove(endpoint);
+}
+
+function writeResponse(socket: net.Socket, response: LocalRpcResponse): void {
+  socket.end(`${JSON.stringify(response)}\n`);
+}
+
+function bindConnectionHandler(params: {
+  server: Server;
+  context: AgentContext;
+  runtime?: AgentRuntime;
+}): void {
+  const { server, context, runtime } = params;
+  server.on("connection", (socket) => {
+    let buffered = "";
+    socket.setEncoding("utf8");
+    socket.on("data", async (chunk) => {
+      buffered += String(chunk || "");
+      const newlineIndex = buffered.indexOf("\n");
+      if (newlineIndex < 0) return;
+      const raw = buffered.slice(0, newlineIndex).trim();
+      if (!raw) {
+        writeResponse(socket, createErrorResponse("unknown", 400, "Empty local RPC payload"));
+        return;
+      }
+      try {
+        const request = JSON.parse(raw) as LocalRpcRequest;
+        const response = await dispatchRequest({
+          request,
+          context,
+          runtime,
+        });
+        writeResponse(socket, response);
+      } catch (error) {
+        writeResponse(
+          socket,
+          createErrorResponse("unknown", 400, `Invalid local RPC request: ${String(error)}`),
+        );
+      }
+    });
+  });
+}
+
+/**
+ * 启动本地 RPC server。
+ */
+export async function startLocalRpcServer(params: {
+  context: AgentContext;
+  runtime?: AgentRuntime;
+}): Promise<LocalRpcServerHandle> {
+  const endpoint = getLocalRpcEndpoint(params.context.rootPath);
+  await ensureEndpointReady(endpoint);
+
+  const server = net.createServer();
+  bindConnectionHandler({
+    server,
+    context: params.context,
+    runtime: params.runtime,
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(endpoint, () => resolve());
+  });
+
+  return {
+    endpoint,
+    async stop() {
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      });
+      if (process.platform !== "win32") {
+        await fs.remove(endpoint);
+      }
+    },
+  };
+}

package/src/service/builtins/BaseService.ts

@@ -6,14 +6,14 @@
  * - 各 service 的长期状态应归属于实例本身，而不是模块级单例。
  */
 
-import type { AgentRuntime } from "@/agent/AgentRuntimeTypes.js";
+import type { AgentRuntime } from "@/runtime/AgentRuntimeTypes.js";
 import type {
   Service,
   ServiceActions,
   ServiceLifecycle,
-} from "@/shared/types/Service.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { ServiceStateRecord } from "@/shared/types/ServiceState.js";
+} from "@/service/types/Service.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { ServiceStateRecord } from "@/service/types/ServiceState.js";
 
 /**
  * BaseService 抽象基类。

package/src/service/builtins/README.md

@@ -2,20 +2,20 @@
 
 ## 模块定位
 
-`services/` 是 Downcity 的主动业务层。  
+`service/builtins/` 是 Downcity 的内建主动业务层。  
 每个 service 对外暴露统一的 `Service` 契约，但在运行时已经逐步迁移为 `BaseService` 子类，由 agent 在启动时创建 `per-agent service instance`。
 
 ## 当前整体模型
 
-1. `main/service/Services.ts`
+1. `service/core/Services.ts`
    - 维护 service 的静态注册清单。
-2. `main/registries/ServiceClassRegistry.ts`
+2. `service/core/ServiceClassRegistry.ts`
    - 负责把静态 service 定义实例化为 `BaseService` 子类。
-3. `agent/AgentRuntime.ts`
+3. `runtime/AgentRuntime.ts`
    - agent 持有当前运行中的 service 实例集合。
-4. `main/service/Manager.ts`
+4. `service/core/Manager.ts`
    - 统一做 service lifecycle、action 调度、CLI/API 桥接。
-5. `src/types/Service.ts`
+5. `service/types/Service.ts`
    - 作为 service 共享契约的单一事实源。
 
 ## 当前内建 service
@@ -31,7 +31,9 @@
    - `runtime/ChatChannelConfig.ts` 负责状态快照与配置落盘。
    - `runtime/ChatChannelActions.ts` 负责渠道类 action 执行。
    - `runtime/ChatChannelFacade.ts` 只保留门面导出。
-   - `runtime/ChatActionInput.ts` 负责 CLI/API 输入映射。
+   - `runtime/ChatActionInput.ts` 负责非 send 类 CLI/API 输入映射与统一导出。
+   - `runtime/ChatSendActionInput.ts` 负责 `chat send` 正文协议、stdin/file 与定时发送输入映射。
+   - `runtime/ChatActionInputSupport.ts` 负责 chat action 输入映射共享解析辅助。
    - `runtime/ChatActionExecution.ts` 负责消息类 action 执行。
    - `runtime/ChatQueueSessionBridge.ts` 负责 queue 与 session 的桥接写入协议。
    - `runtime/ChatQueueWorkerSupport.ts` 负责 worker 辅助能力。
@@ -41,17 +43,24 @@
    - `channels/BaseChatChannelSupport.ts` 负责 session 映射、history 与 chat meta 辅助。
    - `channels/BaseChatChannelQueue.ts` 负责 audit/exec 入队编排。
    - `channels/telegram/Bot.ts` 现在只保留 Telegram 渠道门面与编排。
+   - `channels/telegram/TelegramMessageHandler.ts` 负责 Telegram 普通消息授权、附件与执行入队。
+   - `channels/telegram/TelegramPendingUpdates.ts` 负责 Telegram 积压 updates 的 audit 补录。
    - `channels/telegram/TelegramPlatformClient.ts` 负责 Telegram polling/API/发送主逻辑。
    - `channels/telegram/TelegramInbound.ts` 负责 Telegram 入站归一化辅助。
    - `channels/feishu/Feishu.ts` 现在只保留 Feishu 渠道门面与编排。
+   - `channels/feishu/FeishuMessageHandler.ts` 负责 Feishu 入站去重、授权、附件与执行入队。
    - `channels/feishu/FeishuPlatformClient.ts` 负责 Feishu runtime 宿主与 token/cache 状态。
    - `channels/feishu/FeishuPlatformLookup.ts` 负责 Feishu 用户/群聊/reply 查询与入站附件下载。
    - `channels/feishu/FeishuPlatformMessaging.ts` 负责 Feishu 消息发送与附件上传。
    - `channels/feishu/FeishuInbound.ts` 负责 Feishu 入站归一化辅助。
    - `channels/qq/QQ.ts` 现在只保留 QQ 渠道门面与编排。
+   - `channels/qq/QQMessageHandler.ts` 负责 QQ group/c2c/channel 入站主流程。
    - `channels/qq/QQSupport.ts` 负责 QQ READY 身份解析、命令映射与入站增强组装。
-  - `channels/qq/QQGatewayClient.ts` 负责 QQ Gateway runtime 宿主、WS 编排与重连调度。
-  - `channels/qq/QQGatewaySupport.ts` 负责 QQ Gateway 状态快照、心跳判断与 payload 解析。
+   - `channels/qq/QQGatewayClient.ts` 负责 QQ Gateway runtime 宿主、WS 编排与重连调度。
+   - `channels/qq/QQGatewayConnection.ts` 负责 QQ Gateway WebSocket 创建与事件绑定。
+   - `channels/qq/QQGatewayProtocol.ts` 负责 QQ Gateway op code 协议路由与 Identify。
+   - `channels/qq/QQGatewayHeartbeat.ts` 负责 QQ Gateway heartbeat payload 发送。
+   - `channels/qq/QQGatewaySupport.ts` 负责 QQ Gateway 状态快照、心跳判断与 payload 解析。
    - `channels/qq/QQGatewayAuth.ts` 负责 QQ 鉴权、Gateway URL 与 HTTP 连通性测试。
    - `channels/qq/QQGatewaySend.ts` 负责 QQ 回发请求构造、超时与自动重试。
    - `channels/qq/QQInbound.ts` 负责 QQ 入站归一化辅助。
@@ -65,6 +74,7 @@
    - `runtime/TaskRunnerProgress.ts` 负责 progress 快照与文本辅助。
    - `runtime/TaskRunnerSession.ts` 负责 task 专用 session runtime。
    - `runtime/TaskRunnerRound.ts` 负责单轮执行与模拟用户判定。
+   - `runtime/TaskRunnerScript.ts` 负责 script 类型任务的 one-shot 执行与校验分支。
    - `runtime/TaskRunArtifacts.ts` 负责 run 产物写入与 markdown/json 摘要格式。
    - `runtime/Runner.ts` 负责主编排并协调 run 产物写入。
 3. `memory/`
@@ -75,9 +85,20 @@
    - `ShellService.ts` 持有实例级 shell session 状态。
    - `runtime/ShellActionRuntime.ts` 负责公开 action 编排。
    - `runtime/ShellActionRuntimeSupport.ts` 负责持久化、waiter 与 session 查找等共享运行时细节。
+   - `runtime/ShellRuntimeEnvironment.ts` 负责 shell cwd、env 与 owner context 解析。
+   - `runtime/ShellActionResponse.ts` 负责输出游标裁剪与标准 action response 构造。
+   - `runtime/ShellProcessEvents.ts` 负责 shell 子进程输出、错误与 close 事件绑定。
    - `session/tools/shell/ShellToolDefinition.ts` 作为 session tool facade，只做协议适配。
    - `session/tools/shell/ShellToolSchemas.ts` 负责 shell tool schema。
    - `session/tools/shell/ShellToolBridge.ts` 负责 runtime bridge 与响应整理。
+5. `contact/`
+   - 负责 agent 点对点关系、长期 contact chat、内容分享与 inbox 接收。
+   - `ContactService.ts` 是实例入口，只保留 service 骨架与 contact 业务动作。
+   - `Action.ts` 负责 CLI/API action 注册表与输入映射。
+   - `runtime/ContactPayload.ts` 负责远端 HTTP payload 与 contact token 读取。
+   - `runtime/ContactStore.ts`、`LinkStore.ts`、`InboxStore.ts` 负责 contact/link/inbox 落盘。
+   - `runtime/LinkApproval.ts`、`ApproveCallback.ts` 负责建联与双向回连确认。
+   - `runtime/ShareBundle.ts` 负责分享内容打包与接收。
 
 ## 统一服务模式
 
@@ -86,11 +107,11 @@
 2. `<Domain>Service.ts`
    - 作为真正的 class service 实现。
 3. `Action.ts`
-   - 保留该领域的核心业务 helper，供 service/runtime 复用。
+   - 负责 action 注册表、CLI/API 输入映射与 handler 注入。
 4. `runtime/`
    - 承载具体运行时实现、状态管理与输入映射。
 5. `types/`
-   - 存放领域内部协议；跨层共享契约统一提升到 `src/types/`。
+   - 存放领域内部协议；跨层共享契约统一提升到 `service/types/` 或包级 `types/`。
 
 ## 边界约束
 

package/src/service/builtins/chat/Action.ts

@@ -6,7 +6,7 @@
  * - 通过 SessionRunScope（ALS）读取当前请求上下文
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import { getSessionRunScope } from "@session/SessionRunScope.js";
 import {
   sendActionByChatKey,

package/src/service/builtins/chat/ChatService.ts

@@ -8,13 +8,13 @@
  * - action 注册表已经拆到独立模块，当前文件只保留实例骨架。
  */
 
-import type { AgentRuntime } from "@/agent/AgentRuntimeTypes.js";
+import type { AgentRuntime } from "@/runtime/AgentRuntimeTypes.js";
 import { BaseService } from "@/service/builtins/BaseService.js";
-import type { ServiceActions } from "@/shared/types/Service.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { ChatChannelState } from "@/shared/types/ChatRuntime.js";
-import type { StoredChannelAccount } from "@/shared/types/Store.js";
-import type { ChatQueueWorkerConfig } from "@/shared/types/ChatQueueWorker.js";
+import type { ServiceActions } from "@/service/types/Service.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { ChatChannelState } from "@/service/builtins/chat/types/ChatRuntime.js";
+import type { StoredChannelAccount } from "@/types/host/Store.js";
+import type { ChatQueueWorkerConfig } from "@/service/builtins/chat/types/ChatQueueWorker.js";
 import type {
   ChatServiceFeishuOptions,
   ChatServiceOptions,

package/src/service/builtins/chat/ChatServiceTypes.ts

@@ -7,9 +7,9 @@
  * - 若未显式注入，则 ChatService 仍可回退到现有 `downcity.json + PlatformStore` 读取路径。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { ChatQueueWorkerConfig } from "@/shared/types/ChatQueueWorker.js";
-import type { StoredChannelAccount } from "@/shared/types/Store.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { ChatQueueWorkerConfig } from "@/service/builtins/chat/types/ChatQueueWorker.js";
+import type { StoredChannelAccount } from "@/types/host/Store.js";
 import type { ChatChannelName } from "@/service/builtins/chat/types/ChannelStatus.js";
 
 /**

package/src/service/builtins/chat/PROMPT.direct.ts

@@ -0,0 +1,9 @@
+/**
+ * 自动生成文件，请勿手改。
+ * 源文件：由同路径 `*.ts.txt` 生成。
+ */
+
+// Source: src/service/builtins/chat/PROMPT.direct.ts.txt
+const TEXT_MODULE_CONTENT = "# Chat Service 使用说明\n\n## 用户可见回复规则\n\n- 当前模式下，直接输出，即会发送消息给到用户对应的channel\n\n## 输出协议\n\n- 需要普通回复时，直接输出文本即可。文本顶部可用 frontmatter metadata (optional)，字段语义与 `city chat send` 保持一致：\n\n- `delay` / `delayMs`：延迟发送毫秒数。\n- `time` / `sendAt` / `sendAtMs`：定时发送时间。\n- `reply`：是否使用 reply 语义发送。\n- `messageId`：目标 `message_id`（群聊推荐）。\n- `react`：发送表情反应。\n  - 单个字符串：`react: \"👍\"`\n  - 或对象/数组：`emoji/big`\n  - 设置 `messageId` 时，`react` 会优先复用该消息作为目标消息。\n- 附件使用 `<file type=\"...\">path</file>`（支持 `document/photo/voice/audio/video`）。\n- 附件路径必须是项目内可访问的相对路径。多附件可输出多个 `<file>` 标签。\n\n### 示例\n\n```text\n---\nreply: true\nmessageId: \"128\"\nreact:\n  - emoji: \"✅\"\n---\n这是今天的报告。\n<file type=\"document\">reports/daily.md</file>\n```\n\n### 协议约束\n\n- frontmatter 必须位于文本最开头（`---` 包裹）。\n- 除 `<file>` 附件标签外，不要使用尖括号格式做控制参数。\n\n## 跨协议/跨平台操作\n\n- 当任务需要跨会话、跨平台或复杂路由，必须使用 `city chat send` / `city chat react`。\n- metadata 只适用于当前会话内的 direct 出站，不要拿 metadata 做跨 chat 路由。\n- 如果需要跨 chat 发送，或者不清楚怎么发送，直接先调用 `city chat --help` 查看方法。\n- 如不确定参数或正文协议，先自行调用：\n  - `city chat --help`\n  - `city chat send --help`\n  - `city chat react --help`\n\n## 入站消息结构（仅供内部理解）\n\n- 每条入队用户消息包含 `<info>...</info>` 元信息块 + 用户正文。\n- `<info>` 仅保留 user/request 元信息，例如 `user_id`、`username`、`message_id`、`permissions`、`received_at`。\n- 当前 chat 路由环境（例如 `channel`、`session_id`、`chat_key`、`chat_id`）会通过 system prompt 单独注入，不再混在 `<info>` 里。\n- `<info>` 不要原样回传给用户。\n";
+
+export default TEXT_MODULE_CONTENT;