@downcity/agent 1.1.1

package/src/config/Paths.ts

@@ -0,0 +1,260 @@
+/**
+ * City Env Paths：项目与运行目录路径规则模块。
+ *
+ * 关键点（中文）
+ * - 统一管理单个 agent 项目内 `.downcity` 及其子目录/文件路径规则。
+ * - 避免路径字符串在不同模块重复拼接，降低维护成本。
+ * - 这里描述的是“项目级路径约定”，与 `main/city/runtime/CityPaths.ts` 的全局路径约定分开。
+ */
+import path from "path";
+
+/**
+ * PROFILE.md 候选文件名（按优先级从高到低）。
+ *
+ * 关键点（中文）
+ * - 统一使用大写文件名：`PROFILE.md`。
+ * - 与 SOUL 一起作为静态 prompt 入口。
+ */
+export const PROFILE_MD_FILE_CANDIDATES = ["PROFILE.md"] as const;
+
+export function getProfileMdPath(cwd: string): string {
+  return path.join(cwd, PROFILE_MD_FILE_CANDIDATES[0]);
+}
+
+export function getProfileMdCandidatePaths(cwd: string): string[] {
+  return PROFILE_MD_FILE_CANDIDATES.map((filename) => path.join(cwd, filename));
+}
+
+/**
+ * SOUL.md 候选文件名（按优先级从高到低）。
+ *
+ * 关键点（中文）
+ * - 统一使用大写文件名：`SOUL.md`。
+ * - 统一由 Paths 模块暴露，避免调用方散落硬编码。
+ */
+export const SOUL_MD_FILE_CANDIDATES = ["SOUL.md"] as const;
+
+export function getSoulMdPath(cwd: string): string {
+  return path.join(cwd, SOUL_MD_FILE_CANDIDATES[0]);
+}
+
+export function getSoulMdCandidatePaths(cwd: string): string[] {
+  return SOUL_MD_FILE_CANDIDATES.map((filename) => path.join(cwd, filename));
+}
+
+export function getDowncityJsonPath(cwd: string): string {
+  return path.join(cwd, "downcity.json");
+}
+
+export function getDowncityDirPath(cwd: string): string {
+  return path.join(cwd, ".downcity");
+}
+
+export function getDowncitySchemaPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "schema", "downcity.schema.json");
+}
+
+export function getDowncityConfigDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "config");
+}
+
+export function getLogsDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "logs");
+}
+
+export function getCacheDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), ".cache");
+}
+
+export function getDowncityProfileDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "profile");
+}
+
+export function getDowncityProfilePrimaryPath(cwd: string): string {
+  return path.join(getDowncityProfileDirPath(cwd), "Primary.md");
+}
+
+export function getDowncityProfileOtherPath(cwd: string): string {
+  return path.join(getDowncityProfileDirPath(cwd), "other.md");
+}
+
+/**
+ * Memory 根目录（V2）。
+ *
+ * 关键点（中文）
+ * - `.downcity/memory` 为跨会话记忆目录。
+ */
+export function getDowncityMemoryDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "memory");
+}
+
+/**
+ * 长期记忆文件路径（V2）。
+ */
+export function getDowncityMemoryLongTermPath(cwd: string): string {
+  return path.join(getDowncityMemoryDirPath(cwd), "MEMORY.md");
+}
+
+/**
+ * 每日记忆目录路径（V2）。
+ */
+export function getDowncityMemoryDailyDirPath(cwd: string): string {
+  return path.join(getDowncityMemoryDirPath(cwd), "daily");
+}
+
+/**
+ * 每日记忆文件路径（V2）。
+ */
+export function getDowncityMemoryDailyPath(cwd: string, date: string): string {
+  const fileName = `${String(date || "").trim() || "unknown-date"}.md`;
+  return path.join(getDowncityMemoryDailyDirPath(cwd), fileName);
+}
+
+/**
+ * Memory 索引文件路径（V2）。
+ */
+export function getDowncityMemoryIndexPath(cwd: string): string {
+  return path.join(getDowncityMemoryDirPath(cwd), "index.sqlite");
+}
+
+/**
+ * Service Schedule SQLite 路径。
+ *
+ * 关键点（中文）
+ * - 调度任务属于项目 runtime 本地状态，因此放在项目 `.downcity/` 下。
+ */
+export function getDowncityScheduleDbPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "schedule.sqlite");
+}
+
+export function getDowncityDataDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "data");
+}
+
+export function getDowncitySessionRootDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "session");
+}
+
+export function getDowncitySessionDirPath(cwd: string, sessionId: string): string {
+  return path.join(getDowncitySessionRootDirPath(cwd), encodeURIComponent(sessionId));
+}
+
+/**
+ * Session Messages（会话消息，唯一事实源）。
+ *
+ * 关键点（中文）
+ * - `.downcity/session/<encodedSessionId>/messages/messages.jsonl`：每行一个 UIMessage（user/assistant）
+ * - compact 会把被折叠的原始段写入 `messages/archive/*`（可审计）
+ */
+export function getDowncitySessionMessagesDirPath(
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getDowncitySessionDirPath(cwd, sessionId), "messages");
+}
+
+export function getDowncitySessionMessagesPath(cwd: string, sessionId: string): string {
+  return path.join(getDowncitySessionMessagesDirPath(cwd, sessionId), "messages.jsonl");
+}
+
+export function getDowncitySessionHistoryMetaPath(cwd: string, sessionId: string): string {
+  return path.join(getDowncitySessionMessagesDirPath(cwd, sessionId), "meta.json");
+}
+
+export function getDowncitySessionMessagesArchiveDirPath(
+  cwd: string,
+  sessionId: string,
+): string {
+  return path.join(getDowncitySessionMessagesDirPath(cwd, sessionId), "archive");
+}
+
+export function getDowncitySessionMessagesArchivePath(
+  cwd: string,
+  sessionId: string,
+  archiveId: string,
+): string {
+  return path.join(
+    getDowncitySessionMessagesArchiveDirPath(cwd, sessionId),
+    `${encodeURIComponent(String(archiveId || "").trim())}.json`,
+  );
+}
+
+export function getDowncityPublicDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "public");
+}
+
+export function getDowncityTasksDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "task");
+}
+
+export function getDowncityDebugDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), ".debug");
+}
+
+/**
+ * Chat 元信息目录（由 services/chat 维护）。
+ *
+ * 关键点（中文）
+ * - 该目录存放 `sessionId -> chat` 的最近映射快照
+ * - 与 core session messages 分离，避免把平台路由细节耦合进 core
+ */
+export function getDowncityChatDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "chat");
+}
+
+/**
+ * Channel 目录（channel -> sessionId 映射）。
+ *
+ * 关键点（中文）
+ * - 专门承载渠道目标与内部 sessionId 的映射关系。
+ * - 与 `chat/` 审计事件目录分离，避免职责混淆。
+ */
+export function getDowncityChannelDirPath(cwd: string): string {
+  return path.join(getDowncityDirPath(cwd), "channel");
+}
+
+/**
+ * Channel 元信息文件路径。
+ *
+ * 关键点（中文）
+ * - 采用单文件 JSON（`meta.json`）存储映射表与最近路由信息。
+ */
+export function getDowncityChannelMetaPath(cwd: string): string {
+  return path.join(getDowncityChannelDirPath(cwd), "meta.json");
+}
+
+export function getDowncityChatMetaDirPath(cwd: string): string {
+  return path.join(getDowncityChatDirPath(cwd), "meta");
+}
+
+export function getDowncityChatMetaPath(cwd: string, sessionId: string): string {
+  return path.join(
+    getDowncityChatMetaDirPath(cwd),
+    `${encodeURIComponent(String(sessionId || "").trim())}.json`,
+  );
+}
+
+/**
+ * Chat 会话目录（按 sessionId 组织）。
+ *
+ * 关键点（中文）
+ * - 用于存放聊天事件流（history.jsonl）等审计向数据。
+ * - 与 `chat/meta` 分离，避免路由快照与事件流混在一起。
+ */
+export function getDowncityChatSessionDirPath(cwd: string, sessionId: string): string {
+  return path.join(
+    getDowncityChatDirPath(cwd),
+    encodeURIComponent(String(sessionId || "").trim()),
+  );
+}
+
+/**
+ * Chat 事件流文件路径（JSONL）。
+ *
+ * 关键点（中文）
+ * - 每行一条 chat 事件（当前为 inbound）。
+ * - 设计为 append-only，便于审计与回放。
+ */
+export function getDowncityChatHistoryPath(cwd: string, sessionId: string): string {
+  return path.join(getDowncityChatSessionDirPath(cwd, sessionId), "history.jsonl");
+}

package/src/daemon/Api.ts

@@ -0,0 +1,64 @@
+/**
+ * Daemon API 协议类型模块。
+ *
+ * 关键点（中文）
+ * - 这里描述的是 CLI 与 agent daemon 之间的远程访问契约，不包含具体 HTTP 实现。
+ * - service 等上层模块只依赖这些协议类型，不需要感知 city/daemon 的内部实现细节。
+ * - 该文件属于 `main/city/daemon/*` 的协议边界，而不是通用 HTTP 类型目录。
+ */
+
+import type { JsonValue } from "@/shared/types/Json.js";
+
+/**
+ * Daemon 服务端点。
+ */
+export type DaemonEndpoint = {
+  host: string;
+  port: number;
+  baseUrl: string;
+};
+
+/**
+ * Daemon HTTP 方法白名单。
+ */
+export type DaemonHttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+
+/**
+ * JSON API 调用参数。
+ *
+ * 关键点（中文）
+ * - `projectRoot` 用于解析 downcity.json 与默认 endpoint。
+ * - `host/port` 可显式覆盖自动解析结果。
+ */
+export type DaemonJsonApiCallParams = {
+  projectRoot: string;
+  path: string;
+  method?: DaemonHttpMethod;
+  body?: JsonValue;
+  /**
+   * 单次调用超时（毫秒）。
+   *
+   * 说明（中文）
+   * - 仅本地 IPC transport 当前会消费该参数。
+   * - 用于 `session execute`、`service command` 这类可能持续几十秒的请求，
+   *   避免被默认短超时误判成“Agent server 未启动”。
+   */
+  timeoutMs?: number;
+  host?: string;
+  port?: number;
+  authToken?: string;
+};
+
+/**
+ * JSON API 通用返回结构。
+ *
+ * 语义（中文）
+ * - `success=true` 时读取 `data`。
+ * - `success=false` 时读取 `error`（可选 `status`）。
+ */
+export type DaemonJsonApiCallResult<T> = {
+  success: boolean;
+  status?: number;
+  data?: T;
+  error?: string;
+};

package/src/daemon/Client.ts

@@ -0,0 +1,182 @@
+/**
+ * Daemon API 客户端（process 子模块）。
+ *
+ * 关键点（中文）
+ * - 业务模块统一通过 daemon API 与运行时通信。
+ * - 地址解析优先级：CLI 参数 > 环境变量 > daemon meta > 默认值。
+ */
+
+import fs from "fs-extra";
+import {
+  type DaemonEndpoint,
+  type DaemonJsonApiCallParams,
+  type DaemonJsonApiCallResult,
+} from "./Api.js";
+import {
+  formatCliBearerHeaderValue,
+  resolveCliAuthToken,
+} from "@/http/auth/CliAuthStateStore.js";
+import { getDaemonMetaPath } from "@/daemon/Manager.js";
+import type { JsonObject, JsonValue } from "@/shared/types/Json.js";
+
+/**
+ * 解析端口值。
+ *
+ * 关键点（中文）
+ * - 仅接受 1~65535 的整数；非法值返回 undefined。
+ */
+function parsePortLike(input: string | number | undefined): number | undefined {
+  if (input === undefined || input === null || input === "") return undefined;
+  const raw =
+    typeof input === "number" ? input : Number.parseInt(String(input), 10);
+  if (!Number.isFinite(raw) || Number.isNaN(raw)) return undefined;
+  if (!Number.isInteger(raw) || raw <= 0 || raw > 65535) return undefined;
+  return raw;
+}
+
+/**
+ * 归一化 host。
+ *
+ * 关键点（中文）
+ * - `0.0.0.0`/`::` 会转换为 `127.0.0.1`，避免客户端直连通配地址失败。
+ */
+function normalizeHost(input: string | undefined): string | undefined {
+  const host = typeof input === "string" ? input.trim() : "";
+  if (!host) return undefined;
+  if (host === "0.0.0.0" || host === "::") return "127.0.0.1";
+  return host;
+}
+
+function parseErrorMessageFromPayload(data: JsonValue | null): string | null {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+  const payload = data as JsonObject;
+  if (typeof payload.error === "string") return payload.error;
+  if (typeof payload.message === "string") return payload.message;
+  return null;
+}
+
+function pickArgValue(args: string[], key: string): string | undefined {
+  const idx = args.findIndex((item) => String(item).trim() === key);
+  if (idx < 0) return undefined;
+  const next = String(args[idx + 1] || "").trim();
+  return next || undefined;
+}
+
+/**
+ * 解析 daemon endpoint。
+ *
+ * 优先级（中文）
+ * 1) 显式入参 `host/port`
+ * 2) 环境变量 `DC_SERVER_*` / `DC_CTX_SERVER_*`
+ * 3) daemon meta args（`downcity.daemon.json`）
+ * 4) 默认 `127.0.0.1:5314`
+ */
+function resolveDaemonEndpoint(params: {
+  projectRoot: string;
+  host?: string;
+  port?: number;
+}): DaemonEndpoint {
+  const explicitHost = normalizeHost(params.host);
+  const explicitPort = parsePortLike(params.port);
+
+  const envHost =
+    normalizeHost(process.env.DC_SERVER_HOST) ||
+    normalizeHost(process.env.DC_CTX_SERVER_HOST);
+  const envPort =
+    parsePortLike(process.env.DC_SERVER_PORT) ||
+    parsePortLike(process.env.DC_CTX_SERVER_PORT);
+
+  let daemonArgHost: string | undefined;
+  let daemonArgPort: number | undefined;
+  try {
+    const metaPath = getDaemonMetaPath(params.projectRoot);
+    if (fs.existsSync(metaPath)) {
+      const raw = fs.readJsonSync(metaPath) as { args?: unknown };
+      const args = Array.isArray(raw?.args)
+        ? raw.args.map((item) => String(item))
+        : [];
+      daemonArgHost = normalizeHost(pickArgValue(args, "--host"));
+      daemonArgPort = parsePortLike(pickArgValue(args, "--port"));
+    }
+  } catch {
+    // ignore daemon meta errors, fallback to other sources
+  }
+
+  const host = explicitHost || envHost || daemonArgHost || "127.0.0.1";
+  const port = explicitPort || envPort || daemonArgPort || 5314;
+
+  return {
+    host,
+    port,
+    baseUrl: `http://${host}:${port}`,
+  };
+}
+
+/**
+ * 调用 daemon JSON API。
+ *
+ * 错误语义（中文）
+ * - 网络异常：`success=false` + `error`（无 status）。
+ * - HTTP 非 2xx：`success=false` + `status` + `error`。
+ */
+export async function callServer<T>(
+  params: DaemonJsonApiCallParams,
+): Promise<DaemonJsonApiCallResult<T>> {
+  const endpoint = resolveDaemonEndpoint({
+    projectRoot: params.projectRoot,
+    host: params.host,
+    port: params.port,
+  });
+
+  const url = new URL(params.path, endpoint.baseUrl).toString();
+  const method = params.method || "GET";
+  const hasBody = params.body !== undefined && method !== "GET";
+  const headers: Record<string, string> = {};
+  const authHeaderValue = formatCliBearerHeaderValue(
+    resolveCliAuthToken({
+      explicitToken: params.authToken,
+    }),
+  );
+  if (hasBody) {
+    headers["Content-Type"] = "application/json";
+  }
+  if (authHeaderValue) {
+    headers.Authorization = authHeaderValue;
+  }
+
+  try {
+    const response = await fetch(url, {
+      method,
+      headers: Object.keys(headers).length > 0 ? headers : undefined,
+      body: hasBody ? JSON.stringify(params.body) : undefined,
+    });
+
+    let data: JsonValue | null = null;
+    try {
+      data = (await response.json()) as JsonValue;
+    } catch {
+      data = null;
+    }
+
+    if (!response.ok) {
+      const messageFromData =
+        parseErrorMessageFromPayload(data) || `HTTP ${response.status}`;
+      return {
+        success: false,
+        status: response.status,
+        error: messageFromData,
+      };
+    }
+
+    return {
+      success: true,
+      status: response.status,
+      data: data as T,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: `Failed to call ${url}: ${String(error)}`,
+    };
+  }
+}