@downcity/agent 1.1.1 → 1.1.5

package/src/host/sdk/SessionMetadata.ts

@@ -0,0 +1,178 @@
+/**
+ * SDK Session 元数据辅助。
+ *
+ * 关键点（中文）
+ * - 统一负责 `.downcity/agents/<agentId>/sessions/<sessionId>/messages/meta.json` 的 SDK 字段读写。
+ * - 仅处理轻量配置摘要与索引信息，不负责消息 JSONL 的读写。
+ */
+
+import fs from "fs-extra";
+import type { LanguageModel } from "ai";
+import type {
+  SessionHistoryMetaV1,
+  SessionHistorySdkConfigV1,
+} from "@/types/session/SessionHistoryMeta.js";
+import { getSdkAgentSessionMetaPath } from "@/host/sdk/Paths.js";
+
+type ReadSessionMetadataInput = {
+  /**
+   * 项目根目录。
+   */
+  projectRoot: string;
+
+  /**
+   * 当前 agentId。
+   */
+  agentId: string;
+
+  /**
+   * 当前 sessionId。
+   */
+  sessionId: string;
+};
+
+function normalizeModelLabel(input: unknown): string | undefined {
+  const label = typeof input === "string" ? input.trim() : "";
+  return label || undefined;
+}
+
+/**
+ * 从模型实例推导轻量可读标签。
+ */
+export function inferModelLabel(
+  model: LanguageModel | undefined,
+): string | undefined {
+  if (!model || typeof model !== "object") return undefined;
+  const record = model as Record<string, unknown>;
+  const candidates = [
+    record.modelId,
+    record.model,
+    record.id,
+    record.name,
+    record.label,
+  ];
+  for (const candidate of candidates) {
+    const text = normalizeModelLabel(candidate);
+    if (text) return text;
+  }
+  const constructorName =
+    model.constructor && typeof model.constructor.name === "string"
+      ? model.constructor.name.trim()
+      : "";
+  return constructorName || "configured-model";
+}
+
+/**
+ * 读取当前 session 的 meta.json。
+ */
+export async function readSdkSessionMetadata(
+  input: ReadSessionMetadataInput,
+): Promise<SessionHistoryMetaV1> {
+  const filePath = getSdkAgentSessionMetaPath(
+    input.projectRoot,
+    input.agentId,
+    input.sessionId,
+  );
+  try {
+    const raw = (await fs.readJson(filePath)) as Partial<SessionHistoryMetaV1>;
+    return {
+      v: 1,
+      sessionId: input.sessionId,
+      agentId: input.agentId,
+      createdAt:
+        typeof raw.createdAt === "number" && Number.isFinite(raw.createdAt)
+          ? raw.createdAt
+          : Date.now(),
+      updatedAt:
+        typeof raw.updatedAt === "number" && Number.isFinite(raw.updatedAt)
+          ? raw.updatedAt
+          : 0,
+      pinnedSkillIds: Array.isArray(raw.pinnedSkillIds)
+        ? raw.pinnedSkillIds
+            .map((item) => (typeof item === "string" ? item.trim() : ""))
+            .filter(Boolean)
+        : [],
+      ...(typeof raw.lastArchiveId === "string" && raw.lastArchiveId.trim()
+        ? { lastArchiveId: raw.lastArchiveId.trim() }
+        : {}),
+      ...(typeof raw.keepLastMessages === "number" &&
+      Number.isFinite(raw.keepLastMessages)
+        ? { keepLastMessages: raw.keepLastMessages }
+        : {}),
+      ...(typeof raw.maxInputTokensApprox === "number" &&
+      Number.isFinite(raw.maxInputTokensApprox)
+        ? { maxInputTokensApprox: raw.maxInputTokensApprox }
+        : {}),
+      ...(typeof raw.compactRatio === "number" && Number.isFinite(raw.compactRatio)
+        ? { compactRatio: raw.compactRatio }
+        : {}),
+      ...(raw.sdkConfig && typeof raw.sdkConfig === "object"
+        ? { sdkConfig: raw.sdkConfig as SessionHistorySdkConfigV1 }
+        : {}),
+    };
+  } catch {
+    return {
+      v: 1,
+      sessionId: input.sessionId,
+      agentId: input.agentId,
+      createdAt: Date.now(),
+      updatedAt: 0,
+      pinnedSkillIds: [],
+    };
+  }
+}
+
+/**
+ * 写回当前 session 的 meta.json。
+ */
+export async function writeSdkSessionMetadata(
+  input: ReadSessionMetadataInput & {
+    /**
+     * 下一份 meta 数据。
+     */
+    meta: SessionHistoryMetaV1;
+  },
+): Promise<void> {
+  const filePath = getSdkAgentSessionMetaPath(
+    input.projectRoot,
+    input.agentId,
+    input.sessionId,
+  );
+  await fs.ensureFile(filePath);
+  await fs.writeJson(filePath, input.meta, { spaces: 2 });
+}
+
+/**
+ * 更新当前 session 的 SDK 配置摘要。
+ */
+export async function patchSdkSessionModelLabel(
+  input: ReadSessionMetadataInput & {
+    /**
+     * 当前模型实例。
+     */
+    model?: LanguageModel;
+  },
+): Promise<SessionHistoryMetaV1> {
+  const current = await readSdkSessionMetadata(input);
+  const modelLabel = inferModelLabel(input.model);
+  const next: SessionHistoryMetaV1 = {
+    ...current,
+    agentId: input.agentId,
+    createdAt:
+      typeof current.createdAt === "number" ? current.createdAt : Date.now(),
+    updatedAt: Date.now(),
+    ...(modelLabel
+      ? {
+          sdkConfig: {
+            ...(current.sdkConfig || {}),
+            modelLabel,
+          },
+        }
+      : {}),
+  };
+  await writeSdkSessionMetadata({
+    ...input,
+    meta: next,
+  });
+  return next;
+}

package/src/host/sdk/StreamEvents.ts

@@ -0,0 +1,95 @@
+/**
+ * SDK Stream 事件映射辅助。
+ *
+ * 关键点（中文）
+ * - 把底层 AI SDK `UIMessageChunk` 归一到 `AgentSessionStreamEvent`。
+ * - 仅保留 SDK 当前需要的稳定事件，不把所有底层细节直接暴露出去。
+ */
+
+import type { UIMessageChunk } from "ai";
+import type { JsonValue } from "@/shared/types/Json.js";
+import type { AgentSessionStreamEvent } from "@/host/sdk/AgentSdkTypes.js";
+
+function toJsonValue(value: unknown): JsonValue {
+  if (value === undefined) return null;
+  if (value === null) return null;
+  if (
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return value;
+  }
+  try {
+    return JSON.parse(JSON.stringify(value)) as JsonValue;
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * 把单个 UI chunk 映射为 SDK stream 事件。
+ */
+export function mapUiMessageChunkToSdkEvent(
+  chunk: UIMessageChunk,
+): AgentSessionStreamEvent | null {
+  switch (chunk.type) {
+    case "text-delta":
+      return {
+        type: "text-delta",
+        text: chunk.delta,
+      };
+    case "reasoning-delta":
+      return {
+        type: "reasoning-delta",
+        text: chunk.delta,
+      };
+    case "tool-input-available":
+      return {
+        type: "tool-call",
+        toolCallId: chunk.toolCallId,
+        toolName: chunk.toolName,
+        args: toJsonValue(chunk.input),
+      };
+    case "tool-output-available":
+      return {
+        type: "tool-result",
+        toolCallId: chunk.toolCallId,
+        toolName: "unknown",
+        result: toJsonValue(chunk.output),
+      };
+    case "tool-output-error":
+      return {
+        type: "tool-error",
+        toolCallId: chunk.toolCallId,
+        toolName: "unknown",
+        error: chunk.errorText,
+      };
+    case "tool-input-error":
+      return {
+        type: "tool-error",
+        toolCallId: chunk.toolCallId,
+        toolName: chunk.toolName,
+        error: chunk.errorText,
+      };
+    case "finish":
+      return {
+        type: "finish",
+        ...(typeof chunk.finishReason === "string"
+          ? { finishReason: chunk.finishReason }
+          : {}),
+      };
+    case "error":
+      return {
+        type: "error",
+        error: chunk.errorText,
+      };
+    case "abort":
+      return {
+        type: "error",
+        error: String(chunk.reason || "stream aborted"),
+      };
+    default:
+      return null;
+  }
+}

package/src/http/Server.ts

@@ -20,7 +20,7 @@ import {
 } from "@/http/services/services.js";
 import { pluginsRouter } from "@/http/plugins/plugins.js";
 import { staticRouter } from "@/http/static/static.js";
-import { dashboardRouter } from "@/http/dashboard/Router.js";
+import { controlRouter } from "@/http/control/ControlRouter.js";
 import { registerAuthRoutes } from "@/http/auth/AuthRoutes.js";
 import { AuthService } from "@/http/auth/AuthService.js";
 import {
@@ -86,7 +86,7 @@ export function createServerApp(): Hono {
   app.route("/", servicesRouter);
   app.route("/", pluginsRouter);
   app.route("/", executeRouter);
-  app.route("/", dashboardRouter);
+  app.route("/", controlRouter);
   registerBuiltinPluginHttpRoutes({
     app,
     getContext: getAgentContext,

package/src/http/auth/AuthStore.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 该模块只负责 `auth_*` 表的读写，不处理密码校验与 HTTP 语义。
- * - 数据仍落在 console 的 SQLite 中，与现有控制面共享底层存储。
+ * - 数据仍落在控制面全局 SQLite 中，与现有平台配置共享底层存储。
  */
 
 import fs from "fs-extra";
@@ -11,7 +11,7 @@ import path from "node:path";
 import Database from "better-sqlite3";
 import { drizzle } from "drizzle-orm/better-sqlite3";
 import { nanoid } from "nanoid";
-import { getConsoleShipDbPath } from "@/runtime/CityPaths.js";
+import { getPlatformStoreDbPath } from "@/host/runtime/CityPaths.js";
 import type { AuthIssuedToken, AuthTokenSummary } from "@/shared/types/auth/AuthToken.js";
 import {
   AUTH_DEFAULT_ROLES,
@@ -27,12 +27,12 @@ import type {
   AuthTokenRecord,
   AuthUser,
 } from "@/shared/types/auth/AuthTypes.js";
-import { ensureConsoleStoreSchema } from "@/shared/utils/store/StoreSchema.js";
+import { ensurePlatformStoreSchema } from "@/shared/utils/store/StoreSchema.js";
 import {
   nowIso,
   normalizeNonEmptyText,
   optionalTrimmedText,
-  type ConsoleStoreContext,
+  type PlatformStoreContext,
 } from "@/shared/utils/store/StoreShared.js";
 
 /**
@@ -52,10 +52,10 @@ type SqliteRow = Record<string, unknown>;
  */
 export class AuthStore {
   private readonly sqlite: Database.Database;
-  private readonly context: ConsoleStoreContext;
+  private readonly context: PlatformStoreContext;
 
   constructor(options: AuthStoreOptions = {}) {
-    const dbPath = path.resolve(options.dbPath || getConsoleShipDbPath());
+    const dbPath = path.resolve(options.dbPath || getPlatformStoreDbPath());
     fs.ensureDirSync(path.dirname(dbPath));
     this.sqlite = new Database(dbPath);
     this.sqlite.pragma("journal_mode = WAL");
@@ -63,7 +63,7 @@ export class AuthStore {
       sqlite: this.sqlite,
       db: drizzle(this.sqlite),
     };
-    ensureConsoleStoreSchema(this.context);
+    ensurePlatformStoreSchema(this.context);
   }
 
   /**

package/src/http/auth/RoutePolicy.ts

@@ -62,34 +62,34 @@ export const SERVER_AUTH_ROUTE_POLICIES: AuthRoutePolicy[] = [
     anyPermissions: ["plugin.write"],
   },
   {
-    path: "/api/dashboard/authorization",
+    path: "/api/control/authorization",
     method: "GET",
     requireAuth: true,
     anyPermissions: ["auth.read"],
   },
   {
-    path: "/api/dashboard/authorization/config",
+    path: "/api/control/authorization/config",
     method: "POST",
     requireAuth: true,
     anyPermissions: ["auth.write"],
   },
   {
-    path: "/api/dashboard/authorization/action",
+    path: "/api/control/authorization/action",
     method: "POST",
     requireAuth: true,
     anyPermissions: ["auth.write"],
   },
   {
-    path: "/api/dashboard/*",
+    path: "/api/control/*",
     method: "*",
     requireAuth: true,
   },
 ];
 
 /**
- * Console 网关侧路由权限矩阵。
+ * 控制面网关侧路由权限矩阵。
  */
-export const CONSOLE_AUTH_ROUTE_POLICIES: AuthRoutePolicy[] = [
+export const CONTROL_PLANE_AUTH_ROUTE_POLICIES: AuthRoutePolicy[] = [
   { path: "/api/auth/*", method: "*", requireAuth: false },
   { path: "/health", method: "GET", requireAuth: false },
   {

package/src/http/control/AuthControlService.ts

@@ -0,0 +1,161 @@
+/**
+ * Control Authorization Service。
+ *
+ * 关键点（中文）
+ * - 这是 control 侧的 auth 管理面 facade。
+ * - 它通过 auth plugin action 读取与写入授权数据，但自身不属于 plugin 内核。
+ * - 这样调用方不需要知道 plugin action 名称，也不需要依赖 `plugins/auth/*` 目录。
+ */
+
+import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { JsonObject } from "@/shared/types/Json.js";
+import type { AuthControlPayload } from "@/shared/types/AuthControl.js";
+import type {
+  AuthSetUserRolePayload,
+  AuthWriteConfigPayload,
+  ChatAuthorizationConfig,
+  ChatAuthorizationSnapshot,
+} from "@/shared/types/AuthPlugin.js";
+import {
+  AUTH_ACTIONS,
+  AUTH_PLUGIN_NAME,
+  CHAT_AUTHORIZATION_CATALOG,
+} from "@/shared/types/AuthPlugin.js";
+
+function toRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return value as Record<string, unknown>;
+}
+
+function readSnapshot(value: unknown): ChatAuthorizationSnapshot {
+  const record = toRecord(value);
+  return {
+    config: toRecord(record.config) as unknown as ChatAuthorizationConfig,
+    users: (Array.isArray(record.users) ? record.users : []) as ChatAuthorizationSnapshot["users"],
+    chats: (Array.isArray(record.chats) ? record.chats : []) as ChatAuthorizationSnapshot["chats"],
+  };
+}
+
+/**
+ * 读取 auth plugin 快照。
+ */
+async function readAuthorizationSnapshotViaPlugin(
+  context: AgentContext,
+): Promise<ChatAuthorizationSnapshot> {
+  const result = await context.plugins.runAction({
+    plugin: AUTH_PLUGIN_NAME,
+    action: AUTH_ACTIONS.snapshot,
+  });
+  if (!result.success) {
+    throw new Error(result.error || result.message || "auth snapshot failed");
+  }
+  return readSnapshot(result.data);
+}
+
+/**
+ * 读取 auth plugin 配置。
+ */
+async function readAuthorizationConfigViaPlugin(
+  context: AgentContext,
+): Promise<ChatAuthorizationConfig> {
+  const result = await context.plugins.runAction({
+    plugin: AUTH_PLUGIN_NAME,
+    action: AUTH_ACTIONS.readConfig,
+  });
+  if (!result.success) {
+    throw new Error(result.error || result.message || "auth read-config failed");
+  }
+  return toRecord(result.data) as unknown as ChatAuthorizationConfig;
+}
+
+/**
+ * 通过 auth plugin 覆盖写入授权配置。
+ */
+async function writeAuthorizationConfigViaPlugin(params: {
+  context: AgentContext;
+  config: ChatAuthorizationConfig;
+}): Promise<ChatAuthorizationConfig> {
+  const result = await params.context.plugins.runAction({
+    plugin: AUTH_PLUGIN_NAME,
+    action: AUTH_ACTIONS.writeConfig,
+    payload: {
+      config: params.config,
+    } as AuthWriteConfigPayload as unknown as JsonObject,
+  });
+  if (!result.success) {
+    throw new Error(result.error || result.message || "auth write-config failed");
+  }
+  return toRecord(result.data) as unknown as ChatAuthorizationConfig;
+}
+
+/**
+ * 通过 auth plugin 设置用户角色。
+ */
+async function setAuthorizationUserRoleViaPlugin(params: {
+  context: AgentContext;
+  channel: string;
+  userId: string;
+  roleId: string;
+}): Promise<ChatAuthorizationConfig> {
+  const result = await params.context.plugins.runAction({
+    plugin: AUTH_PLUGIN_NAME,
+    action: AUTH_ACTIONS.setUserRole,
+    payload: {
+      channel: params.channel,
+      userId: params.userId,
+      roleId: params.roleId,
+    } as AuthSetUserRolePayload as unknown as JsonObject,
+  });
+  if (!result.success) {
+    throw new Error(result.error || result.message || "auth set-user-role failed");
+  }
+  return toRecord(result.data) as unknown as ChatAuthorizationConfig;
+}
+
+/**
+ * 读取 authorization 页面所需的完整数据。
+ */
+export async function readAuthControlPayload(
+  context: AgentContext,
+): Promise<AuthControlPayload> {
+  const [config, snapshot] = await Promise.all([
+    readAuthorizationConfigViaPlugin(context),
+    readAuthorizationSnapshotViaPlugin(context),
+  ]);
+  return {
+    catalog: CHAT_AUTHORIZATION_CATALOG,
+    config,
+    users: snapshot.users,
+    chats: snapshot.chats,
+  };
+}
+
+/**
+ * 覆盖写入授权配置，并返回最新 control payload。
+ */
+export async function writeAuthControlConfig(params: {
+  context: AgentContext;
+  config: ChatAuthorizationConfig;
+}): Promise<AuthControlPayload> {
+  await writeAuthorizationConfigViaPlugin({
+    context: params.context,
+    config: params.config,
+  });
+  return readAuthControlPayload(params.context);
+}
+
+/**
+ * 设置用户角色，并返回最新 control payload。
+ */
+export async function setAuthControlUserRole(params: {
+  context: AgentContext;
+  input: AuthSetUserRolePayload;
+}): Promise<AuthControlPayload> {
+  await setAuthorizationUserRoleViaPlugin({
+    context: params.context,
+    channel: params.input.channel,
+    userId: params.input.userId,
+    roleId: params.input.roleId,
+  });
+  return readAuthControlPayload(params.context);
+}

package/src/http/control/CommonHelpers.ts

@@ -0,0 +1,69 @@
+/**
+ * 单 agent control API 通用 helper。
+ *
+ * 关键点（中文）
+ * - 聚合 control 路由、query/path/文本裁剪等基础工具。
+ * - 单 agent 控制面统一收敛到 `/api/control/*`。
+ * - 不依赖任何业务状态。
+ */
+
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+
+/**
+ * 单 agent control API 的公开路由前缀。
+ *
+ * 说明（中文）
+ * - 单 agent 控制面只暴露 `/api/control/*`。
+ */
+export const CONTROL_API_ROUTE_PREFIXES = ["/api/control"] as const;
+
+/**
+ * 为同一个 control 端点生成公开路径别名。
+ */
+export function buildControlRouteAliases(suffix: string): string[] {
+  const normalizedSuffix = String(suffix || "").startsWith("/")
+    ? String(suffix || "")
+    : `/${String(suffix || "")}`;
+  return CONTROL_API_ROUTE_PREFIXES.map((prefix) => `${prefix}${normalizedSuffix}`);
+}
+
+/**
+ * 解析 limit 参数并做边界裁剪。
+ */
+export function toLimit(
+  raw: string | undefined,
+  fallback = DEFAULT_LIMIT,
+): number {
+  const n = Number.parseInt(String(raw || "").trim(), 10);
+  if (!Number.isFinite(n) || Number.isNaN(n)) return fallback;
+  return Math.max(1, Math.min(MAX_LIMIT, n));
+}
+
+/**
+ * 转成可选字符串。
+ */
+export function toOptionalString(input: unknown): string | undefined {
+  const value = typeof input === "string" ? input.trim() : "";
+  return value ? value : undefined;
+}
+
+/**
+ * 安全 decodeURIComponent。
+ */
+export function decodeMaybe(value: string): string {
+  try {
+    return decodeURIComponent(String(value || ""));
+  } catch {
+    return String(value || "");
+  }
+}
+
+/**
+ * 文本截断。
+ */
+export function truncateText(text: string, maxChars: number): string {
+  const normalized = String(text || "");
+  if (normalized.length <= maxChars) return normalized;
+  return normalized.slice(0, Math.max(0, maxChars - 3)) + "...";
+}

package/src/http/control/ControlApiRoutes.ts

@@ -0,0 +1,31 @@
+/**
+ * Agent Control API 路由聚合入口。
+ *
+ * 关键点（中文）
+ * - 本文件只做模块装配，不再承载具体业务逻辑。
+ * - 单 agent control API 子路由按 overview/session/model/task/auth 五类拆分，便于继续维护。
+ * - 单 agent control API 统一暴露在 `/api/control/*` 下。
+ */
+
+import type { ControlRouteRegistrationParams } from "@/shared/types/ControlRoutes.js";
+import { registerControlAuthorizationRoutes } from "@/http/control/ControlAuthorizationRoutes.js";
+import { registerControlSessionRoutes } from "@/http/control/SessionRoutes.js";
+import { registerControlModelRoutes } from "@/http/control/ModelRoutes.js";
+import { registerControlOverviewRoutes } from "@/http/control/OverviewRoutes.js";
+import { registerControlTaskRoutes } from "@/http/control/TaskRoutes.js";
+
+/**
+ * 注册单 agent control API 路由。
+ */
+export function registerControlApiRoutes(
+  params: ControlRouteRegistrationParams,
+): void {
+  registerControlAuthorizationRoutes({
+    app: params.app,
+    getAgentContext: params.getAgentContext,
+  });
+  registerControlOverviewRoutes(params);
+  registerControlSessionRoutes(params);
+  registerControlModelRoutes(params);
+  registerControlTaskRoutes(params);
+}