@downcity/agent 1.1.10 → 1.1.12

package/src/service/builtins/chat/runtime/ChatSendActionInput.ts

@@ -0,0 +1,255 @@
+/**
+ * Chat send action 输入映射。
+ *
+ * 关键点（中文）
+ * - 专门处理 `chat send` 的 CLI/API payload 标准化。
+ * - frontmatter metadata 与 `<file>` 协议在这里转换为统一正文。
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import type { ServiceActionCommandInput } from "@/service/types/Service.js";
+import type { ChatSendActionPayload } from "@/service/builtins/chat/types/ChatService.js";
+import {
+  buildChatMessageText,
+  parseChatMessageMarkup,
+} from "@/service/builtins/chat/runtime/ChatMessageMarkup.js";
+import { parseChatSendOptionsFromMetadata } from "@/service/builtins/chat/runtime/ChatSendMetadata.js";
+import {
+  normalizeChatSendText,
+  resolveChatKey,
+} from "@/service/builtins/chat/Action.js";
+import { getBooleanOpt, getStringOpt } from "./ChatActionInputSupport.js";
+
+/**
+ * 解析非负整数 option。
+ */
+function parseNonNegativeIntOptionOrThrow(
+  value: string,
+  fieldName: string,
+): number {
+  const text = String(value || "").trim();
+  if (!text) {
+    throw new Error(`${fieldName} is required`);
+  }
+  if (!/^\d+$/.test(text)) {
+    throw new Error(`Invalid ${fieldName}: ${value}`);
+  }
+  const parsed = Number.parseInt(text, 10);
+  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed < 0) {
+    throw new Error(`Invalid ${fieldName}: ${value}`);
+  }
+  return parsed;
+}
+
+/**
+ * 判断 ISO datetime 是否缺少时区。
+ */
+function looksLikeIsoDatetimeWithoutTimezone(value: string): boolean {
+  const text = String(value || "").trim();
+  if (!text) return false;
+  const isoLike = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(text);
+  if (!isoLike) return false;
+  return !/(?:Z|[+-]\d{2}:\d{2})$/i.test(text);
+}
+
+/**
+ * 解析定时发送时间。
+ *
+ * 支持格式（中文）
+ * - Unix 时间戳：秒或毫秒（纯数字）
+ * - ISO 时间字符串：例如 `2026-03-05T20:30:00+08:00`
+ */
+function parseSendTimeOptionOrThrow(value: string, fieldName: string): number {
+  const text = String(value || "").trim();
+  if (!text) {
+    throw new Error(`${fieldName} is required`);
+  }
+
+  if (/^\d+$/.test(text)) {
+    const parsed = Number.parseInt(text, 10);
+    if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+      throw new Error(`Invalid ${fieldName}: ${value}`);
+    }
+    // 关键点（中文）：10 位通常是秒级时间戳，统一转换为毫秒。
+    return parsed < 1_000_000_000_000 ? parsed * 1000 : parsed;
+  }
+  if (looksLikeIsoDatetimeWithoutTimezone(text)) {
+    throw new Error(
+      `Invalid ${fieldName}: ${value}. ISO datetime must include timezone offset (e.g. +08:00 or Z).`,
+    );
+  }
+
+  const parsed = Date.parse(text);
+  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+    throw new Error(
+      `Invalid ${fieldName}: ${value}. Use Unix timestamp (seconds/ms) or ISO datetime.`,
+    );
+  }
+  return parsed;
+}
+
+/**
+ * 解析 chat send 正文协议。
+ */
+function parseChatSendTextProtocol(params: {
+  rawText: string;
+  explicitChatKey?: string;
+  explicitDelayMs?: number;
+  explicitSendAtMs?: number;
+  explicitReplyToMessage?: boolean;
+  explicitMessageId?: string;
+}): ChatSendActionPayload {
+  const parsed = parseChatMessageMarkup(normalizeChatSendText(params.rawText));
+  const metadataOptions = parseChatSendOptionsFromMetadata({
+    metadata: parsed.metadata,
+    strict: true,
+  });
+
+  const delayMs =
+    typeof params.explicitDelayMs === "number"
+      ? params.explicitDelayMs
+      : metadataOptions.delayMs;
+  const sendAtMs =
+    typeof params.explicitSendAtMs === "number"
+      ? params.explicitSendAtMs
+      : metadataOptions.sendAtMs;
+  if (typeof delayMs === "number" && typeof sendAtMs === "number") {
+    throw new Error("`delay` and `time` cannot be used together.");
+  }
+
+  const chatKey = resolveChatKey({
+    chatKey: params.explicitChatKey || metadataOptions.chatKey,
+  });
+  const messageId = String(
+    params.explicitMessageId || metadataOptions.messageId || "",
+  ).trim();
+  const replyToMessage =
+    params.explicitReplyToMessage === true ||
+    metadataOptions.replyToMessage === true;
+
+  return {
+    text: buildChatMessageText({
+      segments: parsed.segments,
+    }),
+    ...(chatKey ? { chatKey } : {}),
+    ...(typeof delayMs === "number" ? { delayMs } : {}),
+    ...(typeof sendAtMs === "number" ? { sendAtMs } : {}),
+    ...(replyToMessage ? { replyToMessage: true } : {}),
+    ...(messageId ? { messageId } : {}),
+  };
+}
+
+/**
+ * 解析 `chat send` 的命令输入。
+ *
+ * 关键点（中文）
+ * - `--text / --stdin / --text-file` 三选一
+ * - 文本读取失败直接抛错，由上层统一输出
+ */
+export async function mapChatSendCommandInput(
+  input: ServiceActionCommandInput,
+): Promise<ChatSendActionPayload> {
+  const explicitText = getStringOpt(input.opts, "text");
+  const useStdin = getBooleanOpt(input.opts, "stdin");
+  const textFile = getStringOpt(input.opts, "textFile");
+  const inputSourcesCount =
+    (explicitText ? 1 : 0) + (useStdin ? 1 : 0) + (textFile ? 1 : 0);
+
+  if (inputSourcesCount !== 1) {
+    throw new Error(
+      "Exactly one text source is required: use one of --text, --stdin, or --text-file.",
+    );
+  }
+
+  let text = explicitText;
+  if (useStdin) {
+    const chunks: Buffer[] = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+    text = Buffer.concat(chunks).toString("utf8");
+  } else if (textFile) {
+    const filePath = path.resolve(process.cwd(), textFile);
+    text = await fs.readFile(filePath, "utf8");
+  }
+
+  const delayRaw = getStringOpt(input.opts, "delay");
+  const timeRaw = getStringOpt(input.opts, "time");
+  const replyToMessage = getBooleanOpt(input.opts, "reply");
+  const messageId = getStringOpt(input.opts, "messageId");
+  const delayMs = delayRaw
+    ? parseNonNegativeIntOptionOrThrow(delayRaw, "delay")
+    : undefined;
+  const sendAtMs = timeRaw ? parseSendTimeOptionOrThrow(timeRaw, "time") : undefined;
+  if (typeof delayMs === "number" && typeof sendAtMs === "number") {
+    throw new Error("`--delay` and `--time` cannot be used together.");
+  }
+  const payload = parseChatSendTextProtocol({
+    rawText: text,
+    explicitChatKey: getStringOpt(input.opts, "chatKey"),
+    ...(typeof delayMs === "number" ? { explicitDelayMs: delayMs } : {}),
+    ...(typeof sendAtMs === "number" ? { explicitSendAtMs: sendAtMs } : {}),
+    ...(replyToMessage ? { explicitReplyToMessage: true } : {}),
+    ...(messageId ? { explicitMessageId: messageId } : {}),
+  });
+  const chatKey = resolveChatKey({
+    chatKey: payload.chatKey,
+  });
+  if (!chatKey) {
+    throw new Error(
+      "Missing chatKey. Provide --chat-key or ensure DC_CTX_CHAT_KEY is injected in current shell context.",
+    );
+  }
+
+  return {
+    text: payload.text,
+    chatKey,
+    ...(typeof payload.delayMs === "number" ? { delayMs: payload.delayMs } : {}),
+    ...(typeof payload.sendAtMs === "number" ? { sendAtMs: payload.sendAtMs } : {}),
+    ...(payload.replyToMessage === true ? { replyToMessage: true } : {}),
+    ...(payload.messageId ? { messageId: payload.messageId } : {}),
+  };
+}
+
+/**
+ * 解析 `chat send` 的 API 输入。
+ */
+export function mapChatSendApiInput(body: JsonValue): ChatSendActionPayload {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    throw new Error("Invalid JSON body");
+  }
+  const payload = body as JsonObject;
+  const delayRaw = payload.delayMs ?? payload.delay;
+  const timeRaw = payload.sendAtMs ?? payload.sendAt ?? payload.time;
+  const replyRaw = payload.replyToMessage ?? payload.reply;
+  const delayText =
+    typeof delayRaw === "string" || typeof delayRaw === "number"
+      ? String(delayRaw).trim()
+      : "";
+  const timeText =
+    typeof timeRaw === "string" || typeof timeRaw === "number"
+      ? String(timeRaw).trim()
+      : "";
+  const delayMs = delayText
+    ? parseNonNegativeIntOptionOrThrow(delayText, "delayMs")
+    : undefined;
+  const sendAtMs = timeText
+    ? parseSendTimeOptionOrThrow(timeText, "sendAtMs")
+    : undefined;
+  if (typeof delayMs === "number" && typeof sendAtMs === "number") {
+    throw new Error("`delayMs` and `sendAtMs` cannot be used together.");
+  }
+  return parseChatSendTextProtocol({
+    rawText: String(payload.text ?? ""),
+    explicitChatKey:
+      typeof payload.chatKey === "string" ? payload.chatKey.trim() : undefined,
+    ...(typeof delayMs === "number" ? { explicitDelayMs: delayMs } : {}),
+    ...(typeof sendAtMs === "number" ? { explicitSendAtMs: sendAtMs } : {}),
+    ...(replyRaw === true ? { explicitReplyToMessage: true } : {}),
+    ...(typeof payload.messageId === "string" || typeof payload.messageId === "number"
+      ? { explicitMessageId: String(payload.messageId).trim() }
+      : {}),
+  });
+}

package/src/service/builtins/chat/runtime/ChatServiceActions.ts

@@ -25,7 +25,7 @@ import type {
   ChatStatusActionPayload,
   ChatTestActionPayload,
 } from "@/service/builtins/chat/types/ChatService.js";
-import type { JsonValue } from "@/utils/types/Json.js";
+import type { JsonValue } from "@/types/common/Json.js";
 import type { ChatChannelState } from "@/service/builtins/chat/types/ChatRuntime.js";
 import {
   mapChatChannelApiInput,

package/src/service/builtins/chat/runtime/ChatServiceSystem.ts

@@ -6,7 +6,7 @@
  * - 当前请求只注入当前 channel 的 prompt，避免平台规则串味。
  * - 该模块只负责 prompt 解析与拼装，不承担运行态控制职责。
  */
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import {
   buildCurrentChatEnvironmentPrompt,
   resolveCurrentChatEnvironmentPromptInput,

package/src/service/builtins/chat/runtime/ChatSessionDelete.ts

@@ -10,7 +10,7 @@
 
 import fs from "fs-extra";
 import path from "node:path";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import { resolveChatQueueStore } from "@/service/builtins/chat/runtime/ChatQueue.js";
 import { removeChatMetaBySessionId } from "@/service/builtins/chat/runtime/ChatMetaStore.js";
 

package/src/service/builtins/chat/runtime/ChatkeySend.ts

@@ -14,14 +14,14 @@ import type {
   ChatDispatchAction,
   ChatDispatchChannel,
 } from "@/service/builtins/chat/types/ChatDispatcher.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import { readChatMetaBySessionId } from "./ChatMetaStore.js";
 
 /**
  * 解析实际分发目标。
  *
  * 规则（中文）
- * - 仅使用 services/chat 维护的 session 路由映射。
+ * - 仅使用 service/builtins/chat 维护的 session 路由映射。
  * - 不再支持 legacy chatKey 字符串解析回退。
  */
 export async function resolveDispatchTargetByChatKey(params: {

package/src/service/builtins/chat/runtime/EnqueueDispatch.ts

@@ -6,12 +6,12 @@
  * - service 通过这里暴露 queue 生命周期，不直接散落调用细节。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type {
   ChatEnqueueEffectInput,
   ChatEnqueuePipelineInput,
 } from "@/service/builtins/chat/types/ChatPlugin.js";
-import type { JsonValue } from "@/utils/types/Json.js";
+import type { JsonValue } from "@/types/common/Json.js";
 import { CHAT_PLUGIN_POINTS } from "@/service/builtins/chat/runtime/PluginPoints.js";
 
 function normalizeText(value: string): string {

package/src/service/builtins/chat/runtime/InboundAugment.ts

@@ -6,9 +6,9 @@
  * - 最终拼装顺序固定为：attachmentText -> pluginSections -> bodyText。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type { ChatInboundAugmentInput } from "@/service/builtins/chat/types/ChatPlugin.js";
-import type { JsonValue } from "@/utils/types/Json.js";
+import type { JsonValue } from "@/types/common/Json.js";
 import { CHAT_PLUGIN_POINTS } from "@/service/builtins/chat/runtime/PluginPoints.js";
 
 function normalizeText(value: string | undefined): string | undefined {

package/src/service/builtins/chat/runtime/PluginDispatch.ts

@@ -6,8 +6,8 @@
  * - 这里封装 chat 领域的 plugin 点调用语义，保持 service 边界稳定。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type {
   AuthObservePrincipalPayload,
   ChatAuthorizationEvaluateInput,

package/src/service/builtins/chat/runtime/ReplyContextFormatter.ts

@@ -6,7 +6,7 @@
  * - 同时提供额外 metadata，便于 history / 调试链路查看。
  */
 
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type { InboundReplyContext } from "@/service/builtins/chat/types/ReplyContext.js";
 
 function normalizeReplyValue(value: string | undefined): string | undefined {

package/src/service/builtins/chat/runtime/ReplyDispatch.ts

@@ -6,9 +6,9 @@
  * - 仅服务 agent 执行生命周期，不覆盖手动 `chat send`。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type { ChatReplyDispatchInput, ChatReplyEffectInput } from "@/service/builtins/chat/types/ChatPlugin.js";
-import type { JsonValue } from "@/utils/types/Json.js";
+import type { JsonValue } from "@/types/common/Json.js";
 import type { ChatDispatchChannel } from "@/service/builtins/chat/types/ChatDispatcher.js";
 import { CHAT_PLUGIN_POINTS } from "@/service/builtins/chat/runtime/PluginPoints.js";
 import { resolveDispatchTargetByChatKey } from "@/service/builtins/chat/runtime/ChatkeySend.js";

package/src/service/builtins/chat/runtime/SystemPrompt.ts

@@ -8,7 +8,7 @@
  */
 
 import { getSessionRunScope } from "@session/SessionRunScope.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type { ChatEnvironmentPromptInput } from "@/service/builtins/chat/types/ChatPromptContext.js";
 import { readChatMetaBySessionId } from "@/service/builtins/chat/runtime/ChatMetaStore.js";
 

package/src/service/builtins/chat/runtime/UIMessageTransformer.ts

@@ -15,7 +15,7 @@ import {
   type UITools,
 } from "ai";
 import type { SessionMessageV1 } from "@/session/types/SessionMessages.js";
-import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 
 type AnyUiMessagePart = UIMessagePart<UIDataTypes, UITools>;
 type ToolNameReadablePart = Parameters<typeof getToolName>[0];

package/src/service/builtins/chat/types/ChannelAccount.ts

@@ -6,7 +6,7 @@
  * - 凭据明文只允许出现在写入输入中，读取结果必须是脱敏后的安全视图。
  */
 
-import type { StoredChannelAccountChannel } from "@/host/types/Store.js";
+import type { StoredChannelAccountChannel } from "@/types/host/Store.js";
 
 /**
  * 支持的 chat channel account 类型。

package/src/service/builtins/chat/types/ChatHistory.ts

@@ -6,7 +6,7 @@
  * - 支持入站（inbound）与出站（outbound）事件，便于完整回放对话链路。
  */
 
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type { ChatDispatchChannel } from "@/service/builtins/chat/types/ChatDispatcher.js";
 
 export type ChatHistoryIngressKind = "audit" | "exec";

package/src/service/builtins/chat/types/ChatMeta.ts

@@ -3,7 +3,7 @@
  *
  * 关键点（中文）
  * - 只描述“如何把 sessionId 路由回平台 chat”
- * - 由 services/chat 在接收入站消息时更新
+ * - 由 service/builtins/chat 在接收入站消息时更新
  * - 不属于 core context message schema
  */
 

package/src/service/builtins/chat/types/ChatQueue.ts

@@ -6,7 +6,7 @@
  * - 供 services 与 process 统一复用
  */
 
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { JsonObject } from "@/types/common/Json.js";
 
 export type ChatQueueItemKind = "exec" | "audit" | "control";
 

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

@@ -7,7 +7,7 @@
  * - 字段命名保持与 CLI/API 参数一致，降低映射心智负担。
  */
 
-import type { JsonValue } from "@/utils/types/Json.js";
+import type { JsonValue } from "@/types/common/Json.js";
 import type {
   ChatDeleteRequest,
   ChatHistoryRequest,