@downcity/city 1.1.1

package/src/shared/types/auth/AuthToken.ts

@@ -0,0 +1,47 @@
+/**
+ * 统一账户 Token 响应类型。
+ *
+ * 关键点（中文）
+ * - 明文 token 只在签发时返回一次。
+ * - 列表与详情接口一律只返回摘要，不返回明文。
+ */
+
+/**
+ * 对外返回的 token 摘要。
+ */
+export interface AuthTokenSummary {
+  /**
+   * token 记录 ID。
+   */
+  id: string;
+  /**
+   * token 名称。
+   */
+  name: string;
+  /**
+   * 过期时间（可选）。
+   */
+  expiresAt?: string;
+  /**
+   * 最近使用时间（可选）。
+   */
+  lastUsedAt?: string;
+  /**
+   * 创建时间（ISO 字符串）。
+   */
+  createdAt: string;
+  /**
+   * 更新时间（ISO 字符串）。
+   */
+  updatedAt: string;
+}
+
+/**
+ * 新签发 token 的一次性返回结构。
+ */
+export interface AuthIssuedToken extends AuthTokenSummary {
+  /**
+   * 明文 Bearer Token。
+   */
+  token: string;
+}

package/src/shared/types/auth/AuthTypes.ts

@@ -0,0 +1,235 @@
+/**
+ * 统一账户领域基础类型。
+ *
+ * 关键点（中文）
+ * - 这些类型描述的是 auth 表记录与运行时 principal，不承载路由细节。
+ * - 所有字段都保持可序列化，便于 API 响应与审计日志复用。
+ */
+
+import type { AuthPermissionKey } from "./AuthPermission.js";
+
+/**
+ * 用户状态。
+ */
+export type AuthUserStatus = "active" | "disabled";
+
+/**
+ * 用户记录。
+ */
+export interface AuthUser {
+  /**
+   * 用户主键 ID。
+   */
+  id: string;
+  /**
+   * 登录用户名。
+   */
+  username: string;
+  /**
+   * 密码哈希值。
+   */
+  passwordHash: string;
+  /**
+   * 展示名称。
+   */
+  displayName?: string;
+  /**
+   * 用户状态。
+   */
+  status: AuthUserStatus;
+  /**
+   * 创建时间（ISO 字符串）。
+   */
+  createdAt: string;
+  /**
+   * 更新时间（ISO 字符串）。
+   */
+  updatedAt: string;
+}
+
+/**
+ * 角色记录。
+ */
+export interface AuthRole {
+  /**
+   * 角色主键 ID。
+   */
+  id: string;
+  /**
+   * 角色名。
+   */
+  name: string;
+  /**
+   * 角色说明。
+   */
+  description?: string;
+  /**
+   * 创建时间（ISO 字符串）。
+   */
+  createdAt: string;
+  /**
+   * 更新时间（ISO 字符串）。
+   */
+  updatedAt: string;
+}
+
+/**
+ * 权限记录。
+ */
+export interface AuthPermission {
+  /**
+   * 权限主键 ID。
+   */
+  id: string;
+  /**
+   * 权限 key。
+   */
+  key: AuthPermissionKey;
+  /**
+   * 权限说明。
+   */
+  description?: string;
+  /**
+   * 创建时间（ISO 字符串）。
+   */
+  createdAt: string;
+  /**
+   * 更新时间（ISO 字符串）。
+   */
+  updatedAt: string;
+}
+
+/**
+ * Token 记录。
+ */
+export interface AuthTokenRecord {
+  /**
+   * token 记录主键 ID。
+   */
+  id: string;
+  /**
+   * 所属用户 ID。
+   */
+  userId: string;
+  /**
+   * token 名称。
+   */
+  name: string;
+  /**
+   * token 哈希值。
+   */
+  tokenHash: string;
+  /**
+   * 过期时间（可选）。
+   */
+  expiresAt?: string;
+  /**
+   * 吊销时间（可选）。
+   */
+  revokedAt?: string;
+  /**
+   * 最近使用时间（可选）。
+   */
+  lastUsedAt?: string;
+  /**
+   * 创建时间（ISO 字符串）。
+   */
+  createdAt: string;
+  /**
+   * 更新时间（ISO 字符串）。
+   */
+  updatedAt: string;
+}
+
+/**
+ * 审计日志记录。
+ */
+export interface AuthAuditLog {
+  /**
+   * 审计日志主键 ID。
+   */
+  id: string;
+  /**
+   * 操作人用户 ID。
+   */
+  actorUserId?: string;
+  /**
+   * 操作人 token ID。
+   */
+  actorTokenId?: string;
+  /**
+   * 资源类型。
+   */
+  resourceType: string;
+  /**
+   * 资源 ID。
+   */
+  resourceId?: string;
+  /**
+   * 动作名。
+   */
+  action: string;
+  /**
+   * 动作结果。
+   */
+  result: string;
+  /**
+   * 请求 ID。
+   */
+  requestId?: string;
+  /**
+   * 请求 IP。
+   */
+  ip?: string;
+  /**
+   * User-Agent。
+   */
+  userAgent?: string;
+  /**
+   * 附加元数据 JSON 字符串。
+   */
+  metaJson?: string;
+  /**
+   * 创建时间（ISO 字符串）。
+   */
+  createdAt: string;
+}
+
+/**
+ * 当前请求的认证主体。
+ */
+export interface AuthPrincipal {
+  /**
+   * 当前用户 ID。
+   */
+  userId: string;
+  /**
+   * 当前用户名。
+   */
+  username: string;
+  /**
+   * 当前展示名。
+   */
+  displayName?: string;
+  /**
+   * 当前用户状态。
+   */
+  status: AuthUserStatus;
+  /**
+   * 当前 token 记录 ID。
+   */
+  tokenId: string;
+  /**
+   * 当前 token 名称。
+   */
+  tokenName: string;
+  /**
+   * 当前用户角色列表。
+   */
+  roles: string[];
+  /**
+   * 当前用户权限列表。
+   */
+  permissions: AuthPermissionKey[];
+}
+

package/src/shared/utils/Id.ts

@@ -0,0 +1,13 @@
+/**
+ * ID 生成工具。
+ *
+ * 关键点（中文）
+ * - 提供跨层通用的唯一 ID 生成能力。
+ * - 放在 `utils`，避免 `core -> main` 反向依赖。
+ */
+
+import { nanoid } from "nanoid";
+
+export function generateId(): string {
+  return nanoid(16);
+}

package/src/shared/utils/README.md

@@ -0,0 +1,49 @@
+# utils
+
+## 模块定位
+
+`utils/` 放置可被多模块复用的基础工具实现。  
+当前主要包括日志、ConsoleStore、CLI 与时间等通用基础设施。
+
+## 实现概览
+
+1. `logger/Logger.ts`
+   - 提供进程级单例 logger。
+   - 支持控制台输出 + `.downcity/logs/YYYY-MM-DD.jsonl` 结构化落盘。
+   - 通过 `bindProjectRoot` 绑定当前工程的日志目录。
+2. `logger/Fetch.ts`
+   - 封装 `fetch`，在请求发往 LLM 前写入日志。
+   - 通过注入的 `getSessionRunScope` 回调读取并拼接 `sessionId/requestId`。
+3. `logger/Format.ts`
+   - 作为日志格式化 facade，对外保持稳定导出。
+4. `logger/FormatShared.ts`
+   - 负责 JSON/文本抽取、截断、消息块拼装等共享基础能力。
+5. `logger/FormatRequest.ts`
+   - 解析 provider request payload，提取 messages/system/tool 摘要与元信息。
+6. `logger/FormatResponse.ts`
+   - 解析 provider response / SSE payload，提取输出类型与 function call 摘要。
+7. `store/index.ts`
+   - 提供 `ConsoleStore` 门面。
+   - 对外统一暴露 provider/model、secure settings、env、channel account 存储能力。
+8. `store/StoreSchema.ts`
+   - 负责 SQLite 建表与轻量迁移。
+9. `store/StoreModelRepository.ts`
+   - 负责 provider/model 相关读写。
+10. `store/StoreSecureSettings.ts`
+   - 负责加密配置读写。
+11. `store/StoreEnvRepository.ts`
+   - 负责 global/agent env 单表读写。
+12. `store/StoreChannelAccountRepository.ts`
+   - 负责渠道账号存储与敏感字段加解密。
+
+## 关键调用链
+
+1. `main/model/CreateModel.ts` 创建模型时注入 `createLlmLoggingFetch`。
+2. `session/SessionRunScope.ts` 在运行期维护 `sessionId/requestId`。
+3. LLM 请求发出时，`utils/logger` 通过注入回调读取上下文并记录结构化日志。
+4. `main/modules/cli/Model*.ts`、`main/modules/console/*` 等控制面模块通过 `ConsoleStore` 访问 SQLite 配置数据。
+
+## 边界约束
+
+- `utils` 提供通用能力，不承载业务规则或流程编排。
+- 与业务强耦合的辅助函数应优先放回所属模块。

package/src/shared/utils/Template.ts

@@ -0,0 +1,28 @@
+/**
+ * 字符串模板渲染工具。
+ *
+ * 职责说明（中文）
+ * - 提供统一的 `{{variable}}` 占位符替换能力。
+ * - 供 init 模板与 runtime system prompt 渲染复用，避免重复实现。
+ */
+
+import type { TemplateVariableMap } from "@/shared/types/Template.js";
+
+/**
+ * 渲染模板中的 `{{variable}}` 占位符。
+ *
+ * 关键点（中文）
+ * - 变量名支持字母、数字、下划线，且允许写成 `{{ key }}`。
+ * - 未提供值的变量保持原样，便于排查模板与变量映射不一致问题。
+ */
+export function renderTemplateVariables(
+  template: string,
+  variables: TemplateVariableMap,
+): string {
+  if (!template) return template;
+  return template.replace(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (match, key) => {
+    return Object.prototype.hasOwnProperty.call(variables, key)
+      ? String(variables[key])
+      : match;
+  });
+}

package/src/shared/utils/Time.ts

@@ -0,0 +1,77 @@
+/**
+ * 时间格式工具模块。
+ *
+ * 职责说明：
+ * 1. 提供统一时间戳格式。
+ * 2. 提供耗时格式化，便于日志和 CLI 输出使用一致单位。
+ * 3. 提供 runtime 时区格式化，确保 prompt / message / task 共享同一时间口径。
+ */
+export function getTimestamp(): string {
+  return new Date().toISOString();
+}
+
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60000).toFixed(1)}m`;
+}
+
+export function resolveRuntimeTimezone(): string {
+  const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  return String(timezone || "").trim() || "UTC";
+}
+
+export function formatDateInTimezone(
+  date: Date = new Date(),
+  timezone: string = resolveRuntimeTimezone(),
+): string {
+  try {
+    // 关键点（中文）：sv-SE locale 默认输出 ISO 风格日期，便于模型稳定解析。
+    return new Intl.DateTimeFormat("sv-SE", {
+      timeZone: timezone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+    }).format(date);
+  } catch {
+    return date.toISOString().slice(0, 10);
+  }
+}
+
+export function formatDateTimeInTimezone(
+  date: Date = new Date(),
+  timezone: string = resolveRuntimeTimezone(),
+): string {
+  try {
+    // 关键点（中文）：使用固定格式，确保模型读取时区信息时稳定。
+    const formatted = new Intl.DateTimeFormat("sv-SE", {
+      timeZone: timezone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hour12: false,
+    })
+      .format(date)
+      .replace(" ", "T");
+    return `${formatted} (${timezone})`;
+  } catch {
+    return date.toISOString();
+  }
+}
+
+export function formatYearInTimezone(
+  date: Date = new Date(),
+  timezone: string = resolveRuntimeTimezone(),
+): string {
+  try {
+    return new Intl.DateTimeFormat("en-US", {
+      timeZone: timezone,
+      year: "numeric",
+    }).format(date);
+  } catch {
+    return String(date.getUTCFullYear());
+  }
+}

package/src/shared/utils/cli/CliOutput.ts

@@ -0,0 +1,170 @@
+/**
+ * CLI 输出工具（统一出口）。
+ *
+ * 关键点（中文）
+ * - 所有命令通过 printResult 输出，不再直接调用 emitCliBlock / emitCliList / console.log。
+ * - asJson=true → 结构化 JSON（脚本友好）；asJson=false → 委托 CliReporter 渲染人类可读文本。
+ * - 支持三种输出类型：block（单段落）、list（列表分组）、payload（旧版键值对，兼容过渡）。
+ */
+
+import {
+  emitCliBlock,
+  emitCliList,
+  formatCliBlock,
+} from "@/cli/CliReporter.js";
+import type {
+  CliReportBlock,
+  CliReportFact,
+  CliReportList,
+  CliReportListItem,
+  CliReportTone,
+} from "@/types/cli/CliReporter.js";
+
+/**
+ * printResult 统一参数。
+ *
+ * 说明（中文）
+ * - type 未传时走 payload 模式（key-value → block 转换，兼容旧调用方）。
+ * - type="block" 时直接按 CliReportBlock 渲染。
+ * - type="list" 时直接按 CliReportList 渲染。
+ */
+export type PrintResultParams = {
+  /** 是否以 JSON 格式输出（默认 true，保持历史行为）。 */
+  asJson?: boolean;
+  /** 当前操作是否成功（影响 JSON 的 success 字段和色调默认值）。 */
+  success: boolean;
+  /** 输出标题（JSON 中作为 title，人类可读中作为 heading）。 */
+  title: string;
+
+  /** 输出类型。 */
+  type?: "block" | "list";
+
+  // --- block / list 共享 ---
+  /** 视觉语气。 */
+  tone?: CliReportTone;
+  /** 标题右侧补充摘要。 */
+  summary?: string;
+
+  // --- block 专用 ---
+  /** 详情键值对。 */
+  facts?: CliReportFact[];
+  /** 附注文本。 */
+  note?: string;
+
+  // --- list 专用 ---
+  /** 列表项。 */
+  items?: CliReportListItem[];
+
+  // --- payload 模式（type 未传时使用，兼容过渡） ---
+  /** 键值对 payload。 */
+  payload?: Record<string, unknown>;
+};
+
+/**
+ * 判断值是否为 plain object。
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * 将 payload 转换为 facts 列表（用于人类可读渲染）。
+ */
+function payloadToFacts(payload: Record<string, unknown>): CliReportFact[] {
+  const entries = Object.entries(payload).filter(
+    ([key, value]) => key !== "success" && value !== undefined,
+  );
+  // error 置底，其余按字母序
+  const ordered = [...entries].sort((a, b) => {
+    if (a[0] === "error") return 1;
+    if (b[0] === "error") return -1;
+    return a[0].localeCompare(b[0]);
+  });
+
+  return ordered.map(([key, value]) => {
+    if (value === null || value === undefined) {
+      return { label: key, value: "null" };
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      return { label: key, value: String(value) };
+    }
+    return { label: key, value: JSON.stringify(value) };
+  });
+}
+
+/**
+ * 将 payload 展平为 JSON-safe 对象。
+ */
+function payloadToJson(payload: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(payload)) {
+    if (key === "success") continue;
+    if (value === undefined) continue;
+    result[key] = value;
+  }
+  return result;
+}
+
+/**
+ * 统一 CLI 输出入口。
+ *
+ * 行为（中文）
+ * - asJson=true：输出 `{ success, data?: {...}, error?: string }` 到 stdout。
+ * - asJson=false：
+ *   - type="block" → emitCliBlock
+ *   - type="list" → emitCliList
+ *   - 未传 type → 将 payload 转为 facts 后 emitCliBlock
+ */
+export function printResult(params: PrintResultParams): void {
+  const asJson = params.asJson !== false;
+
+  if (asJson) {
+    const output: Record<string, unknown> = { success: params.success };
+
+    if (params.type === "block") {
+      output.title = params.title;
+      if (params.summary) output.summary = params.summary;
+      if (params.facts && params.facts.length > 0) output.facts = params.facts;
+      if (params.note) output.note = params.note;
+    } else if (params.type === "list") {
+      output.title = params.title;
+      if (params.summary) output.summary = params.summary;
+      if (params.items && params.items.length > 0) output.items = params.items;
+    } else if (params.payload) {
+      Object.assign(output, payloadToJson(params.payload));
+    }
+
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  // --- 人类可读模式 ---
+  if (params.type === "block") {
+    emitCliBlock({
+      tone: params.tone || (params.success ? "success" : "error"),
+      title: params.title,
+      summary: params.summary,
+      facts: params.facts,
+      note: params.note,
+    });
+    return;
+  }
+
+  if (params.type === "list") {
+    emitCliList({
+      tone: params.tone || "accent",
+      title: params.title,
+      summary: params.summary,
+      items: params.items || [],
+    });
+    return;
+  }
+
+  // --- payload 兼容模式 ---
+  const facts = payloadToFacts(params.payload || {});
+  emitCliBlock({
+    tone: params.tone || (params.success ? "success" : "error"),
+    title: params.title,
+    facts,
+  });
+}