@xuanyue202/shared 2026.3.21

package/src/cli/index.ts

@@ -0,0 +1,2 @@
+export * from "./china-setup.js";
+export * from "./install-hint.js";

package/src/cli/install-hint.ts

@@ -0,0 +1,97 @@
+import type { ChannelId } from "./china-setup.js";
+
+type LoggerLike = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+export type ChinaInstallHintApiLike = {
+  logger?: LoggerLike;
+  config?: unknown;
+  [key: string]: unknown;
+};
+
+const PROJECT_REPO = "https://github.com/BytePioneer-AI/openclaw-china";
+const INSTALL_SETUP_COMMAND = "openclaw china setup";
+const START_GATEWAY_COMMAND = "openclaw gateway --port 18789 --verbose";
+const ANSI_RESET = "\u001b[0m";
+const ANSI_BOLD = "\u001b[1m";
+const ANSI_LINK = "\u001b[1;4;96m";
+const ANSI_BORDER = "\u001b[92m";
+const SUPPORTED_CHANNELS: readonly ChannelId[] = [
+  "dingtalk",
+  "feishu-china",
+  "wecom",
+  "wecom-app",
+  "wecom-kf",
+  "wechat-mp",
+  "qqbot",
+];
+const CHINA_INSTALL_HINT_SHOWN_KEY = Symbol.for("@xuanyue202/china-install-hint-shown");
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasAnyEnabledChinaChannel(config: unknown): boolean {
+  if (!isRecord(config)) {
+    return false;
+  }
+
+  const channels = config.channels;
+  if (!isRecord(channels)) {
+    return false;
+  }
+
+  return SUPPORTED_CHANNELS.some((channelId) => {
+    const channelConfig = channels[channelId];
+    return isRecord(channelConfig) && channelConfig.enabled === true;
+  });
+}
+
+function hasShownInstallHint(): boolean {
+  const root = globalThis as Record<PropertyKey, unknown>;
+  return root[CHINA_INSTALL_HINT_SHOWN_KEY] === true;
+}
+
+function markInstallHintShown(): void {
+  const root = globalThis as Record<PropertyKey, unknown>;
+  root[CHINA_INSTALL_HINT_SHOWN_KEY] = true;
+}
+
+export function showChinaInstallHint(api: ChinaInstallHintApiLike): void {
+  if (hasShownInstallHint() || hasAnyEnabledChinaChannel(api.config)) {
+    return;
+  }
+  markInstallHintShown();
+
+  const lines = [
+    `${ANSI_BORDER}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${ANSI_RESET}`,
+    "  OpenClaw China Channels 已就绪!",
+    `${ANSI_BORDER}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${ANSI_RESET}`,
+    "",
+    "项目仓库:",
+    `  ${ANSI_LINK}${PROJECT_REPO}${ANSI_RESET}`,
+    "",
+    "⭐ 如果这个项目对你有帮助，请给我们一个 Star！⭐",
+    "",
+    "下一步（配置引导）:",
+    "  1. 运行交互式配置向导",
+    `     ${ANSI_BOLD}${INSTALL_SETUP_COMMAND}${ANSI_RESET}`,
+    "  2. 按提示填写渠道凭据并保存配置",
+    "  3. 启动网关并观察日志",
+    `     ${START_GATEWAY_COMMAND}`,
+  ];
+
+  if (api.logger?.info) {
+    for (const line of lines) {
+      api.logger.info(line);
+    }
+    return;
+  }
+  if (api.logger?.warn) {
+    for (const line of lines) {
+      api.logger.warn(line);
+    }
+  }
+}

package/src/cron/index.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import {
+  appendCronHiddenPrompt,
+  applyCronHiddenPromptToContext,
+  shouldInjectCronHiddenPrompt,
+  splitCronHiddenPrompt,
+} from "./index.js";
+
+describe("cron hidden prompt", () => {
+  it("injects fixed delivery guidance for reminder-like messages", () => {
+    const text = "请帮我每小时提醒喝水";
+    const next = appendCronHiddenPrompt(text);
+
+    expect(shouldInjectCronHiddenPrompt(text)).toBe(true);
+    expect(next).not.toBe(text);
+    expect(next).toContain('sessionTarget="isolated"');
+    expect(next).toContain('payload.kind="agentTurn"');
+    expect(next).toContain("Use the built-in cron tool (action=add/update)");
+    expect(next).toContain("payload.message must be plain user-visible reminder text only");
+    expect(next).toContain('delivery.mode="announce"');
+    expect(next).toContain("delivery.channel=<OriginatingChannel>");
+    expect(next).toContain("delivery.to=<OriginatingTo>");
+    expect(next).toContain('Never set delivery.channel="last"');
+  });
+
+  it("does not inject for documentation-style questions", () => {
+    const text = "cron 文档怎么用？";
+    const next = appendCronHiddenPrompt(text);
+
+    expect(shouldInjectCronHiddenPrompt(text)).toBe(false);
+    expect(next).toBe(text);
+  });
+
+  it("is idempotent when called repeatedly", () => {
+    const text = "每分钟提醒我伸展一下";
+    const once = appendCronHiddenPrompt(text);
+    const twice = appendCronHiddenPrompt(once);
+
+    expect(twice).toBe(once);
+  });
+
+  it("can split injected prompt from body", () => {
+    const injected = appendCronHiddenPrompt("set a reminder every day at 9am");
+    const result = splitCronHiddenPrompt(injected);
+
+    expect(result.base).toBe("set a reminder every day at 9am");
+    expect(result.prompt).toBeDefined();
+  });
+
+  it("applies to context command body only when needed", () => {
+    const ctx: { Body?: string; CommandBody?: string } = { Body: "每天 18:00 提醒我下班喝水" };
+    const changed = applyCronHiddenPromptToContext(ctx);
+
+    expect(changed).toBe(true);
+    expect(ctx.CommandBody).toContain("delivery.mode=\"announce\"");
+  });
+});

package/src/cron/index.ts

@@ -0,0 +1,130 @@
+const CRON_HIDDEN_PROMPT = `
+When creating or updating a cron task, always store a fixed delivery target in the job itself.
+- Use the built-in cron tool (action=add/update). Do not run shell commands.
+- Must use sessionTarget="isolated" for reminder jobs.
+- payload.kind="agentTurn"
+- payload.message must be plain user-visible reminder text only.
+- You must encode runtime guardrails directly into payload.message so the cron run can follow them without extra context.
+- Runtime guardrails to encode in payload.message:
+  - return plain text only
+  - never call any tool
+  - never call the message tool
+  - never send manually; delivery is handled by cron delivery settings
+- Do not include tool directives, "NO_REPLY", or heartbeat markers in payload.message.
+- Job name is never a message target.
+- During cron run, must return plain text only and never call the message tool.
+- Use top-level delivery with announce mode:
+  delivery.mode="announce"
+  delivery.channel=<OriginatingChannel> (example: "qqbot")
+  delivery.to=<OriginatingTo> (examples: "user:<openid>" / "group:<group_openid>")
+  delivery.accountId=<AccountId> when available
+- Never set delivery.channel="last" for multi-channel environments.
+- If OriginatingChannel/OriginatingTo are unavailable, ask a concise follow-up for channel and target.
+- Do not call the message tool to send`;
+
+const CRON_TRIGGER_KEYWORDS = [
+  "定时",
+  "提醒",
+  "每分钟",
+  "每小时",
+  "每天",
+  "每周",
+  "几点",
+  "早上",
+  "晚上",
+  "工作日",
+  "cron",
+  "remind",
+  "reminder",
+  "schedule",
+  "scheduled",
+  "every minute",
+  "every hour",
+  "every day",
+  "daily",
+  "every week",
+  "weekly",
+  "weekday",
+  "workday",
+  "morning",
+  "evening",
+];
+
+const CRON_TRIGGER_PATTERNS = [
+  /提醒我/u,
+  /帮我定时/u,
+  /每.+提醒/u,
+  /每天.+发/u,
+  /remind me/iu,
+  /set (a )?reminder/iu,
+  /every .+ remind/iu,
+  /every day .+ (send|post|notify)/iu,
+  /schedule .+ (reminder|message|notification)/iu,
+];
+
+const CRON_EXCLUDE_PATTERNS = [
+  /是什么意思/u,
+  /区别/u,
+  /为什么/u,
+  /\bhelp\b/iu,
+  /文档/u,
+  /怎么用/u,
+  /what does|what's|meaning of/iu,
+  /difference/iu,
+  /why/iu,
+  /\bdocs?\b/iu,
+  /documentation/iu,
+  /how to/iu,
+  /usage/iu,
+];
+
+export function shouldInjectCronHiddenPrompt(text: string): boolean {
+  const normalized = text.trim();
+  if (!normalized) return false;
+  const lowered = normalized.toLowerCase();
+
+  for (const pattern of CRON_EXCLUDE_PATTERNS) {
+    if (pattern.test(lowered)) return false;
+  }
+
+  for (const keyword of CRON_TRIGGER_KEYWORDS) {
+    if (lowered.includes(keyword.toLowerCase())) return true;
+  }
+
+  return CRON_TRIGGER_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+
+export function splitCronHiddenPrompt(text: string): { base: string; prompt?: string } {
+  const idx = text.indexOf(CRON_HIDDEN_PROMPT);
+  if (idx === -1) {
+    return { base: text };
+  }
+  const base = text.slice(0, idx).trimEnd();
+  return { base, prompt: CRON_HIDDEN_PROMPT };
+}
+
+export function appendCronHiddenPrompt(text: string): string {
+  if (!shouldInjectCronHiddenPrompt(text)) return text;
+  if (text.includes(CRON_HIDDEN_PROMPT)) return text;
+  return `${text}\n\n${CRON_HIDDEN_PROMPT}`;
+}
+
+export function applyCronHiddenPromptToContext<
+  T extends { Body?: string; RawBody?: string; CommandBody?: string }
+>(ctx: T): boolean {
+  const base =
+    (typeof ctx.RawBody === "string" && ctx.RawBody) ||
+    (typeof ctx.Body === "string" && ctx.Body) ||
+    (typeof ctx.CommandBody === "string" && ctx.CommandBody) ||
+    "";
+
+  if (!base) return false;
+
+  const next = appendCronHiddenPrompt(base);
+  if (next === base) return false;
+
+  ctx.CommandBody = next;
+  return true;
+}
+
+export { CRON_HIDDEN_PROMPT };

package/src/file/file-utils.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Unit Tests for File Utilities
+ * 
+ * Feature: dingtalk-media-receive
+ * Validates: Requirements 5.1-5.8, 6.1-6.6
+ */
+
+import { describe, it, expect } from "vitest";
+import { resolveFileCategory, resolveExtension } from "./file-utils.js";
+
+describe("resolveFileCategory", () => {
+  // Image categorization (Requirement 5.1)
+  it("should categorize image MIME types", () => {
+    expect(resolveFileCategory("image/jpeg")).toBe("image");
+    expect(resolveFileCategory("image/png")).toBe("image");
+    expect(resolveFileCategory("image/gif")).toBe("image");
+    expect(resolveFileCategory("image/webp")).toBe("image");
+    expect(resolveFileCategory("image/bmp")).toBe("image");
+  });
+
+  // Audio categorization (Requirement 5.2)
+  it("should categorize audio MIME types", () => {
+    expect(resolveFileCategory("audio/mpeg")).toBe("audio");
+    expect(resolveFileCategory("audio/wav")).toBe("audio");
+    expect(resolveFileCategory("audio/ogg")).toBe("audio");
+    expect(resolveFileCategory("audio/amr")).toBe("audio");
+  });
+
+  // Video categorization (Requirement 5.3)
+  it("should categorize video MIME types", () => {
+    expect(resolveFileCategory("video/mp4")).toBe("video");
+    expect(resolveFileCategory("video/quicktime")).toBe("video");
+    expect(resolveFileCategory("video/webm")).toBe("video");
+  });
+
+  // Document categorization (Requirement 5.4)
+  it("should categorize document MIME types", () => {
+    expect(resolveFileCategory("application/pdf")).toBe("document");
+    expect(resolveFileCategory("application/msword")).toBe("document");
+    expect(resolveFileCategory("text/plain")).toBe("document");
+    expect(resolveFileCategory("text/markdown")).toBe("document");
+  });
+
+  // Archive categorization (Requirement 5.5)
+  it("should categorize archive MIME types", () => {
+    expect(resolveFileCategory("application/zip")).toBe("archive");
+    expect(resolveFileCategory("application/x-rar-compressed")).toBe("archive");
+    expect(resolveFileCategory("application/x-7z-compressed")).toBe("archive");
+  });
+
+  // Code categorization (Requirement 5.6)
+  it("should categorize code MIME types", () => {
+    expect(resolveFileCategory("application/json")).toBe("code");
+    expect(resolveFileCategory("text/html")).toBe("code");
+    expect(resolveFileCategory("text/css")).toBe("code");
+    expect(resolveFileCategory("text/javascript")).toBe("code");
+  });
+
+  // Extension fallback (Requirement 5.8)
+  it("should use extension fallback when MIME type is unknown", () => {
+    expect(resolveFileCategory("application/octet-stream", "photo.jpg")).toBe("image");
+    expect(resolveFileCategory("application/octet-stream", "song.mp3")).toBe("audio");
+    expect(resolveFileCategory("application/octet-stream", "movie.mp4")).toBe("video");
+    expect(resolveFileCategory("application/octet-stream", "doc.pdf")).toBe("document");
+    expect(resolveFileCategory("application/octet-stream", "archive.zip")).toBe("archive");
+    expect(resolveFileCategory("application/octet-stream", "script.py")).toBe("code");
+  });
+
+  // Other category (Requirement 5.7)
+  it("should return 'other' for unknown types", () => {
+    expect(resolveFileCategory("application/octet-stream")).toBe("other");
+    expect(resolveFileCategory("application/unknown")).toBe("other");
+    expect(resolveFileCategory("application/octet-stream", "file.xyz")).toBe("other");
+  });
+
+  // MIME type normalization
+  it("should handle MIME types with parameters", () => {
+    expect(resolveFileCategory("image/jpeg; charset=utf-8")).toBe("image");
+    expect(resolveFileCategory("text/plain; charset=utf-8")).toBe("document");
+  });
+});
+
+describe("resolveExtension", () => {
+  // Image extensions (Requirement 6.1)
+  it("should resolve image MIME types to extensions", () => {
+    expect(resolveExtension("image/jpeg")).toBe(".jpg");
+    expect(resolveExtension("image/png")).toBe(".png");
+    expect(resolveExtension("image/gif")).toBe(".gif");
+    expect(resolveExtension("image/webp")).toBe(".webp");
+    expect(resolveExtension("image/bmp")).toBe(".bmp");
+  });
+
+  // Audio extensions (Requirement 6.2)
+  it("should resolve audio MIME types to extensions", () => {
+    expect(resolveExtension("audio/mpeg")).toBe(".mp3");
+    expect(resolveExtension("audio/wav")).toBe(".wav");
+    expect(resolveExtension("audio/ogg")).toBe(".ogg");
+    expect(resolveExtension("audio/amr")).toBe(".amr");
+    expect(resolveExtension("audio/x-m4a")).toBe(".m4a");
+  });
+
+  // Video extensions (Requirement 6.3)
+  it("should resolve video MIME types to extensions", () => {
+    expect(resolveExtension("video/mp4")).toBe(".mp4");
+    expect(resolveExtension("video/quicktime")).toBe(".mov");
+    expect(resolveExtension("video/x-msvideo")).toBe(".avi");
+    expect(resolveExtension("video/webm")).toBe(".webm");
+  });
+
+  // Document extensions (Requirement 6.4)
+  it("should resolve document MIME types to extensions", () => {
+    expect(resolveExtension("application/pdf")).toBe(".pdf");
+    expect(resolveExtension("application/msword")).toBe(".doc");
+    expect(resolveExtension("application/vnd.openxmlformats-officedocument.wordprocessingml.document")).toBe(".docx");
+  });
+
+  // Default extension (Requirement 6.5)
+  it("should return .bin for unknown MIME types", () => {
+    expect(resolveExtension("application/unknown")).toBe(".bin");
+    expect(resolveExtension("application/octet-stream")).toBe(".bin");
+  });
+
+  // fileName precedence (Requirement 6.6)
+  it("should use fileName extension when provided", () => {
+    expect(resolveExtension("application/octet-stream", "photo.jpg")).toBe(".jpg");
+    expect(resolveExtension("image/png", "custom.jpeg")).toBe(".jpeg");
+    expect(resolveExtension("application/unknown", "document.pdf")).toBe(".pdf");
+  });
+
+  // MIME type normalization
+  it("should handle MIME types with parameters", () => {
+    expect(resolveExtension("image/jpeg; charset=utf-8")).toBe(".jpg");
+    expect(resolveExtension("audio/mpeg; bitrate=320")).toBe(".mp3");
+  });
+
+  // Edge cases
+  it("should handle fileName without extension", () => {
+    expect(resolveExtension("image/jpeg", "photo")).toBe(".jpg");
+    expect(resolveExtension("application/unknown", "noext")).toBe(".bin");
+  });
+});