chatccc 0.2.26 → 0.2.27

package/im-skills/feishu-skill/download-video.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const DOWNLOAD_DIR = join(homedir(), ".chatccc", "videos", "downloads");
+
+function parseArgs(argv) {
+  const result = {};
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i];
+    if (!key.startsWith("--")) continue;
+    const value = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "true";
+    result[key.slice(2)] = value;
+  }
+  return result;
+}
+
+function walkUpForConfig(startDir) {
+  const result = [];
+  let dir = resolve(startDir);
+  for (let i = 0; i < 6; i++) {
+    result.push(join(dir, "config.json"));
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return result;
+}
+
+async function findConfig() {
+  const paths = [
+    join(homedir(), ".chatccc", "config.json"),
+    ...walkUpForConfig(SCRIPT_DIR),
+  ];
+
+  for (const path of paths) {
+    try {
+      const raw = await readFile(path, "utf-8");
+      const cfg = JSON.parse(raw);
+      const appId = cfg.feishu?.appId || "";
+      const appSecret = cfg.feishu?.appSecret || "";
+      if (appId && appSecret) {
+        console.error(`Using config: ${path}`);
+        return { appId, appSecret };
+      }
+    } catch {
+      // Try the next candidate.
+    }
+  }
+  throw new Error(`Could not find Feishu config. Tried: ${paths.slice(0, 3).join(", ")}...`);
+}
+
+async function getTenantAccessToken(appId, appSecret) {
+  const response = await fetch("https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal", {
+    method: "POST",
+    headers: { "Content-Type": "application/json; charset=utf-8" },
+    body: Buffer.from(JSON.stringify({ app_id: appId, app_secret: appSecret }), "utf8"),
+  });
+  const data = await response.json();
+  if (data.code !== 0) {
+    throw new Error(`Failed to get tenant_access_token: [${data.code}] ${data.msg}`);
+  }
+  return data.tenant_access_token;
+}
+
+async function findMessageId(token, chatId, fileKey) {
+  let pageToken = "";
+  for (let page = 0; page < 10; page++) {
+    const url = new URL("https://open.feishu.cn/open-apis/im/v1/messages");
+    url.searchParams.set("receive_id_type", "chat_id");
+    url.searchParams.set("receive_id", chatId);
+    url.searchParams.set("page_size", "50");
+    if (pageToken) url.searchParams.set("page_token", pageToken);
+
+    const response = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+    const data = await response.json();
+    if (data.code !== 0) {
+      throw new Error(`Failed to list messages: [${data.code}] ${data.msg}`);
+    }
+
+    for (const item of data.data?.items ?? []) {
+      try {
+        if (JSON.parse(item.body?.content ?? "{}").file_key === fileKey) {
+          return item.message_id;
+        }
+      } catch {
+        // Ignore non-file messages.
+      }
+    }
+
+    if (!data.data?.has_more) break;
+    pageToken = data.data?.page_token || "";
+  }
+  return null;
+}
+
+function safeFileName(name) {
+  return (name || "download.bin").replace(/[\\/:*?"<>|]/g, "_");
+}
+
+async function downloadResource(token, messageId, fileKey, fileName) {
+  const url = `https://open.feishu.cn/open-apis/im/v1/messages/${encodeURIComponent(messageId)}/resources/${encodeURIComponent(fileKey)}?type=file`;
+  console.error(`Downloading: ${url}`);
+
+  const response = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(`HTTP ${response.status}: ${text.slice(0, 200)}`);
+  }
+
+  await mkdir(DOWNLOAD_DIR, { recursive: true });
+  const localPath = resolve(DOWNLOAD_DIR, safeFileName(fileName));
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await writeFile(localPath, buffer);
+  return localPath;
+}
+
+function usage() {
+  console.error(`Usage:
+  node download-video.mjs --message-id <message_id> --file-key <file_key> [--name <file_name>]
+  node download-video.mjs --chat-id <chat_id> --file-key <file_key> [--name <file_name>]`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args["file-key"]) {
+    usage();
+    process.exit(1);
+  }
+
+  const { appId, appSecret } = await findConfig();
+  const token = await getTenantAccessToken(appId, appSecret);
+
+  let messageId = args["message-id"] || "";
+  if (!messageId && args["chat-id"]) {
+    messageId = await findMessageId(token, args["chat-id"], args["file-key"]);
+    if (!messageId) {
+      throw new Error(`No message found for file_key=${args["file-key"]}`);
+    }
+  }
+
+  if (!messageId) {
+    usage();
+    process.exit(1);
+  }
+
+  const localPath = await downloadResource(
+    token,
+    messageId,
+    args["file-key"],
+    args.name || "download.bin",
+  );
+  console.log(localPath);
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/im-skills/feishu-skill/send-file.md

@@ -0,0 +1,45 @@
+# Sending & Downloading Files/Videos
+
+## Send Files or Videos
+
+Videos are sent as regular files (not media), which looks cleaner in Feishu.
+
+### Script (recommended)
+
+```bash
+node "{{send_file_script}}" --url "{{send_file_url}}" --token "{{send_file_token}}" --path "<absolute file path>" --caption "<optional caption>"
+```
+
+### Direct HTTP
+
+```http
+POST {{send_file_url}}
+Authorization: Bearer {{send_file_token}}
+Content-Type: application/json; charset=utf-8
+
+{"path":"<absolute file path>","caption":"<optional caption>"}
+```
+
+### Rules
+
+- Save or choose a local file first.
+- Use an absolute local path.
+- Max file size: 100MB.
+- Supported formats: .mp4 .mov .avi .mkv .webm .flv .mp3 .wav .ogg .aac .m4a .pdf .doc .docx .xls .xlsx .csv .ppt .pptx .txt .zip .tar .gz.
+- Only send a file/video when the user asked for one or when it materially helps the answer.
+
+## Download Files or Videos
+
+When the user sends a file or video to the bot, the message contains `message_id` and `file_key`. Download it with:
+
+```bash
+node "{{download_video_script}}" --message-id <message_id> --file-key <file_key> --name <file_name>
+```
+
+If only `chat_id` and `file_key` are available:
+
+```bash
+node "{{download_video_script}}" --chat-id <chat_id> --file-key <file_key> --name <file_name>
+```
+
+Downloads are saved under `~/.chatccc/videos/downloads/`.

package/im-skills/feishu-skill/send-file.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { basename } from "node:path";
+
+function parseArgs(argv) {
+  const result = {};
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i];
+    if (!key.startsWith("--")) continue;
+    const value = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "true";
+    result[key.slice(2)] = value;
+  }
+  return result;
+}
+
+function usage() {
+  console.error(`Usage:
+  node ${basename(process.argv[1])} --url <url> --token <token> --path <absolute file path> [--caption <text>]`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const url = args.url || process.env.CHATCCC_SEND_FILE_URL;
+  const token = args.token || process.env.CHATCCC_SEND_FILE_TOKEN;
+  const path = args.path;
+  const caption = args.caption || "";
+
+  if (!url || !token || !path) {
+    usage();
+    process.exit(1);
+  }
+
+  const body = Buffer.from(JSON.stringify({ path, caption }), "utf8");
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json; charset=utf-8",
+    },
+    body,
+  });
+
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${text}`);
+  }
+  console.log(text);
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/im-skills/feishu-skill/send-image.md

@@ -0,0 +1,31 @@
+# Sending & Receiving Images
+
+## Send Images
+
+### Script (recommended)
+
+```bash
+node "{{send_image_script}}" --url "{{send_image_url}}" --token "{{send_image_token}}" --path "<absolute image path>" --caption "<optional caption>"
+```
+
+### Direct HTTP
+
+```http
+POST {{send_image_url}}
+Authorization: Bearer {{send_image_token}}
+Content-Type: application/json; charset=utf-8
+
+{"path":"<absolute image path>","caption":"<optional caption>"}
+```
+
+### Rules
+
+- Save or choose a local image file first.
+- Use an absolute local path.
+- Supported formats: .png, .jpg, .jpeg, .webp, .gif, .bmp.
+- Max image size: 10MB.
+- Only send an image when the user asked for one or when it materially helps the answer.
+
+## Receive Images
+
+Images sent to the bot are automatically downloaded to `~/.chatccc/images/downloads/`. The message contains an `image_key` that maps to the cached file.

package/im-skills/feishu-skill/send-image.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { basename } from "node:path";
+
+function parseArgs(argv) {
+  const result = {};
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i];
+    if (!key.startsWith("--")) continue;
+    const value = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "true";
+    result[key.slice(2)] = value;
+  }
+  return result;
+}
+
+function usage() {
+  console.error(`Usage:
+  node ${basename(process.argv[1])} --url <url> --token <token> --path <absolute image path> [--caption <text>]`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const url = args.url || process.env.CHATCCC_SEND_IMAGE_URL;
+  const token = args.token || process.env.CHATCCC_SEND_IMAGE_TOKEN;
+  const path = args.path;
+  const caption = args.caption || "";
+
+  if (!url || !token || !path) {
+    usage();
+    process.exit(1);
+  }
+
+  const body = Buffer.from(JSON.stringify({ path, caption }), "utf8");
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json; charset=utf-8",
+    },
+    body,
+  });
+
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${text}`);
+  }
+  console.log(text);
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/im-skills/feishu-skill/skill.md

@@ -0,0 +1,11 @@
+---
+name: feishu-skill
+description: Feishu IM local skills for sending and receiving images, files, and videos.
+---
+
+Current working directory: {{cwd}}
+
+Use local endpoints instead of calling Feishu Open Platform directly.
+
+- **Images** (send & receive): read `{{im_skills_cache_dir}}/feishu-skill/send-image.md`
+- **Files & Videos** (send & download): read `{{im_skills_cache_dir}}/feishu-skill/send-file.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.26",
+  "version": "0.2.27",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",
@@ -11,6 +11,7 @@
   "files": [
     "src/",
     "bin/",
+    "im-skills/",
     "images/img_readme_*.jpg",
     "images/img_readme_*.png",
     "images/avatars/status_*.png",

package/src/__tests__/agent-image-rpc.test.ts

@@ -60,6 +60,8 @@ describe("agent image RPC grants", () => {
 
     expect(prompt).toContain("POST http://127.0.0.1:18080/api/agent/send-image");
     expect(prompt).toContain("Authorization: Bearer tok_test");
+    expect(prompt).toContain("Content-Type: application/json; charset=utf-8");
+    expect(prompt).toContain("UTF-8 encoded JSON bytes");
     expect(prompt).toContain("\"path\"");
     expect(prompt).not.toContain("CHATCCC_SEND_IMAGE_URL");
     expect(prompt).not.toContain("CHATCCC_SEND_IMAGE_TOKEN");

package/src/__tests__/agent-rpc-body.test.ts

@@ -0,0 +1,41 @@
+import type { IncomingMessage } from "node:http";
+import { Readable } from "node:stream";
+
+import { describe, expect, it } from "vitest";
+
+import { getRequestCharset, readUtf8JsonBody } from "../agent-rpc-body.ts";
+
+function requestFrom(body: Buffer, contentType?: string): IncomingMessage {
+  const req = Readable.from([body]) as IncomingMessage;
+  req.headers = {};
+  if (contentType) req.headers["content-type"] = contentType;
+  return req;
+}
+
+describe("agent RPC body parsing", () => {
+  it("defaults JSON requests to UTF-8 and preserves Unicode captions", async () => {
+    const caption = "\u4e2d\u6587 caption";
+    const body = Buffer.from(JSON.stringify({ caption }), "utf8");
+    const req = requestFrom(body, "application/json");
+
+    await expect(readUtf8JsonBody(req, 1024)).resolves.toEqual({ caption });
+  });
+
+  it("reads charset from content-type", () => {
+    const req = requestFrom(Buffer.from("{}"), 'application/json; charset="utf-8"');
+
+    expect(getRequestCharset(req)).toBe("utf-8");
+  });
+
+  it("rejects non UTF-8 charsets", async () => {
+    const req = requestFrom(Buffer.from("{}"), "application/json; charset=gbk");
+
+    await expect(readUtf8JsonBody(req, 1024)).rejects.toThrow("Unsupported charset");
+  });
+
+  it("rejects invalid UTF-8 bytes", async () => {
+    const req = requestFrom(Buffer.from([0xff, 0xfe]), "application/json; charset=utf-8");
+
+    await expect(readUtf8JsonBody(req, 1024)).rejects.toThrow("valid UTF-8");
+  });
+});

package/src/__tests__/im-skills.test.ts

@@ -0,0 +1,50 @@
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { buildImSkillsPrompt } from "../im-skills.ts";
+
+let tempRoot: string | null = null;
+
+describe("IM skills prompt rendering", () => {
+  afterEach(async () => {
+    if (tempRoot) await rm(tempRoot, { recursive: true, force: true });
+    tempRoot = null;
+  });
+
+  it("loads skill.md files and renders runtime variables", async () => {
+    tempRoot = await mkdtemp(join(tmpdir(), "chatccc-im-skills-"));
+    const skillDir = join(tempRoot, "feishu-skill");
+    await mkdir(skillDir);
+    await writeFile(
+      join(skillDir, "skill.md"),
+      [
+        "---",
+        "name: feishu-skill",
+        "---",
+        "POST {{send_image_url}}",
+        "Authorization: Bearer {{send_image_token}}",
+        "Content-Type: application/json; charset=utf-8",
+        "cwd={{cwd}}",
+      ].join("\n"),
+      "utf-8",
+    );
+
+    const prompt = await buildImSkillsPrompt({
+      skillsDir: tempRoot,
+      variables: {
+        cwd: "C:/work",
+        send_image_url: "http://127.0.0.1:18080/api/agent/send-image",
+        send_image_token: "tok_test",
+      },
+    });
+
+    expect(prompt).toContain("[ChatCCC IM skill: feishu-skill]");
+    expect(prompt).toContain("POST http://127.0.0.1:18080/api/agent/send-image");
+    expect(prompt).toContain("Authorization: Bearer tok_test");
+    expect(prompt).toContain("Content-Type: application/json; charset=utf-8");
+    expect(prompt).toContain("cwd=C:/work");
+    expect(prompt).not.toContain("{{");
+  });
+});

package/src/agent-file-rpc.ts

@@ -0,0 +1,155 @@
+import { randomBytes } from "node:crypto";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { extname, isAbsolute, resolve } from "node:path";
+import { stat } from "node:fs/promises";
+
+import { getTenantAccessToken, sendFileReply, sendTextReply } from "./feishu-api.ts";
+import { ts } from "./config.ts";
+import { logTrace } from "./trace.ts";
+import { readUtf8JsonBody } from "./agent-rpc-body.ts";
+
+export const AGENT_SEND_FILE_PATH = "/api/agent/send-file";
+
+const DEFAULT_GRANT_TTL_MS = 30 * 60 * 1000;
+const MAX_REQUEST_BYTES = 64 * 1024;
+const MAX_FILE_BYTES = 100 * 1024 * 1024;
+const ALLOWED_FILE_EXTS = new Set([
+  ".mp4", ".mov", ".avi", ".mkv", ".webm", ".flv",
+  ".mp3", ".wav", ".ogg", ".aac", ".m4a",
+  ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".csv", ".ppt", ".pptx",
+  ".txt", ".zip", ".tar", ".gz",
+]);
+
+export interface AgentFileGrant {
+  token: string;
+  url: string;
+  chatId: string;
+  sessionId: string;
+  cwd: string;
+  expiresAt: number;
+  traceId: string;
+}
+
+const fileGrants = new Map<string, AgentFileGrant>();
+
+function createToken(): string {
+  return randomBytes(24).toString("base64url");
+}
+
+export function createAgentFileGrant(input: {
+  chatId: string;
+  sessionId: string;
+  cwd: string;
+  port: number;
+  traceId?: string;
+  nowMs?: number;
+  ttlMs?: number;
+}): AgentFileGrant {
+  const now = input.nowMs ?? Date.now();
+  const token = createToken();
+  const grant: AgentFileGrant = {
+    token,
+    url: `http://127.0.0.1:${input.port}${AGENT_SEND_FILE_PATH}`,
+    chatId: input.chatId,
+    sessionId: input.sessionId,
+    cwd: input.cwd,
+    expiresAt: now + (input.ttlMs ?? DEFAULT_GRANT_TTL_MS),
+    traceId: input.traceId ?? "",
+  };
+  fileGrants.set(token, grant);
+  if (grant.traceId) logTrace(grant.traceId, "FILE_GRANT_CREATED", { sessionId: grant.sessionId });
+  return grant;
+}
+
+export function revokeAgentFileGrant(token: string): void {
+  const grant = fileGrants.get(token);
+  if (grant?.traceId) logTrace(grant.traceId, "FILE_GRANT_REVOKED", {});
+  fileGrants.delete(token);
+}
+
+function getAgentFileGrantFromAuthorization(authorization: string | undefined, nowMs = Date.now()): AgentFileGrant | null {
+  const match = (authorization ?? "").match(/^Bearer\s+(.+)$/i);
+  if (!match) return null;
+  const grant = fileGrants.get(match[1]);
+  if (!grant) return null;
+  if (grant.expiresAt <= nowMs) { fileGrants.delete(match[1]); return null; }
+  return grant;
+}
+
+export function buildAgentFileCapabilityPrompt(input: { url: string; token: string; cwd?: string }): string {
+  const lines = [
+    "[ChatCCC local capability: send file]",
+    "You can send a file (video, audio, document, etc.) to the current Feishu chat in real time by calling this local endpoint.",
+    "",
+    `POST ${input.url}`,
+    `Authorization: Bearer ${input.token}`,
+    "Content-Type: application/json; charset=utf-8",
+    "",
+    'Body: {"path":"absolute file path","caption":"optional caption"}',
+    "",
+    "Rules:",
+    "- Save or choose a local file first, then call the endpoint.",
+    "- Use an absolute local file path. Do not call Feishu Open Platform directly.",
+    "- Request body must be UTF-8 encoded JSON bytes; caption supports Unicode text, including Chinese.",
+    "- Only call this endpoint when the user asked for a file/video or when a file is useful to the answer.",
+    "- Max file size: 100MB.",
+    "[/ChatCCC local capability: send file]",
+  ];
+  if (input.cwd) lines.splice(2, 0, `Current working directory: ${input.cwd}`);
+  return lines.join("\n");
+}
+
+function jsonReply(res: ServerResponse, status: number, data: unknown): void {
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(data));
+}
+
+async function resolveAndValidateFilePath(grant: AgentFileGrant, rawPath: unknown): Promise<string> {
+  if (typeof rawPath !== "string" || rawPath.trim() === "") throw new Error("path must be a non-empty string");
+  const sessionRoot = resolve(grant.cwd);
+  const filePath = isAbsolute(rawPath) ? resolve(rawPath) : resolve(sessionRoot, rawPath);
+  const ext = extname(filePath).toLowerCase();
+  if (!ALLOWED_FILE_EXTS.has(ext)) throw new Error(`unsupported file extension: ${ext || "(none)"}`);
+  const st = await stat(filePath);
+  if (!st.isFile()) throw new Error("file path is not a file");
+  if (st.size <= 0) throw new Error("file is empty");
+  if (st.size > MAX_FILE_BYTES) throw new Error(`file is larger than ${MAX_FILE_BYTES / 1024 / 1024}MB`);
+  return filePath;
+}
+
+export async function handleAgentFileRequest(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  const url = new URL(req.url ?? "/", "http://127.0.0.1");
+  if (url.pathname !== AGENT_SEND_FILE_PATH) return false;
+  if (req.method !== "POST") { jsonReply(res, 405, { ok: false, error: "Method not allowed" }); return true; }
+
+  const grant = getAgentFileGrantFromAuthorization(req.headers.authorization);
+  if (!grant) { jsonReply(res, 401, { ok: false, error: "Invalid or expired file-send token" }); return true; }
+  const tid = grant.traceId;
+
+  let payload: { path?: unknown; caption?: unknown };
+  try { payload = await readUtf8JsonBody(req, MAX_REQUEST_BYTES); } catch (err) {
+    if (tid) logTrace(tid, "FILE_REQ", { outcome: "invalid_json", error: (err as Error).message });
+    jsonReply(res, 400, { ok: false, error: (err as Error).message || "Invalid JSON" }); return true;
+  }
+
+  let filePath: string;
+  try { filePath = await resolveAndValidateFilePath(grant, payload.path); } catch (err) {
+    if (tid) logTrace(tid, "FILE_REQ", { outcome: "invalid_path", path: String(payload.path), error: (err as Error).message });
+    jsonReply(res, 400, { ok: false, error: (err as Error).message }); return true;
+  }
+
+  try {
+    const token = await getTenantAccessToken();
+    const caption = typeof payload.caption === "string" ? payload.caption.trim() : "";
+    await sendFileReply(token, grant.chatId, filePath);
+    if (caption) await sendTextReply(token, grant.chatId, caption);
+    if (tid) logTrace(tid, "FILE_REQ", { outcome: "sent", path: filePath, hasCaption: !!caption });
+    console.log(`[${ts()}] [AGENT-FILE] sent file chat=${grant.chatId} session=${grant.sessionId} path=${filePath}`);
+    jsonReply(res, 200, { ok: true });
+  } catch (err) {
+    if (tid) logTrace(tid, "FILE_REQ", { outcome: "send_failed", path: filePath!, error: (err as Error).message });
+    console.error(`[${ts()}] [AGENT-FILE] send failed: ${(err as Error).message}`);
+    jsonReply(res, 500, { ok: false, error: (err as Error).message });
+  }
+  return true;
+}

package/src/agent-image-rpc.ts

@@ -6,6 +6,7 @@ import { stat } from "node:fs/promises";
 import { getTenantAccessToken, sendImageReply, sendTextReply } from "./feishu-api.ts";
 import { ts } from "./config.ts";
 import { logTrace } from "./trace.ts";
+import { readUtf8JsonBody } from "./agent-rpc-body.ts";
 
 export const AGENT_SEND_IMAGE_PATH = "/api/agent/send-image";
 
@@ -89,13 +90,14 @@ export function buildAgentImageCapabilityPrompt(input: {
     "",
     `POST ${input.url}`,
     `Authorization: Bearer ${input.token}`,
-    "Content-Type: application/json",
+    "Content-Type: application/json; charset=utf-8",
     "",
     'Body: {"path":"absolute image file path","caption":"optional caption"}',
     "",
     "Rules:",
     "- Save or choose a local image file first, then call the endpoint.",
     "- Use an absolute local file path. Do not call Feishu Open Platform directly.",
+    "- Request body must be UTF-8 encoded JSON bytes; caption supports Unicode text, including Chinese.",
     "- Only call this endpoint when the user asked for an image or when an image is useful to the answer.",
     "[/ChatCCC local capability: send image]",
   ];
@@ -110,24 +112,6 @@ function jsonReply(res: ServerResponse, status: number, data: unknown): void {
   res.end(JSON.stringify(data));
 }
 
-function readLimitedBody(req: IncomingMessage): Promise<string> {
-  return new Promise((resolve, reject) => {
-    let body = "";
-    let size = 0;
-    req.on("data", (chunk: Buffer) => {
-      size += chunk.length;
-      if (size > MAX_REQUEST_BYTES) {
-        reject(new Error("Request body too large"));
-        req.destroy();
-        return;
-      }
-      body += chunk.toString("utf8");
-    });
-    req.on("end", () => resolve(body));
-    req.on("error", reject);
-  });
-}
-
 async function resolveAndValidateImagePath(grant: AgentImageGrant, rawPath: unknown): Promise<string> {
   if (typeof rawPath !== "string" || rawPath.trim() === "") {
     throw new Error("path must be a non-empty string");
@@ -171,7 +155,7 @@ export async function handleAgentImageRequest(
 
   let payload: { path?: unknown; caption?: unknown };
   try {
-    payload = JSON.parse(await readLimitedBody(req));
+    payload = await readUtf8JsonBody(req, MAX_REQUEST_BYTES);
   } catch (err) {
     if (tid) logTrace(tid, "IMAGE_REQ", { outcome: "invalid_json", error: (err as Error).message });
     jsonReply(res, 400, { ok: false, error: (err as Error).message || "Invalid JSON" });

package/src/agent-rpc-body.ts

@@ -0,0 +1,48 @@
+import type { IncomingMessage } from "node:http";
+import { TextDecoder } from "node:util";
+
+function normalizeHeaderValue(value: string | string[] | undefined): string {
+  if (Array.isArray(value)) return value.join("; ");
+  return value ?? "";
+}
+
+export function getRequestCharset(req: IncomingMessage): string {
+  const contentType = normalizeHeaderValue(req.headers["content-type"]);
+  const match = contentType.match(/(?:^|;)\s*charset\s*=\s*("?)([^";\s]+)\1/i);
+  return (match?.[2] ?? "utf-8").toLowerCase();
+}
+
+async function readLimitedBodyBuffer(req: IncomingMessage, maxBytes: number): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+
+  return new Promise((resolve, reject) => {
+    req.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > maxBytes) {
+        reject(new Error("Request body too large"));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks, size)));
+    req.on("error", reject);
+  });
+}
+
+export async function readUtf8JsonBody<T>(req: IncomingMessage, maxBytes: number): Promise<T> {
+  const charset = getRequestCharset(req);
+  if (charset !== "utf-8" && charset !== "utf8") {
+    throw new Error(`Unsupported charset: ${charset}. Use UTF-8 JSON.`);
+  }
+
+  const body = await readLimitedBodyBuffer(req, maxBytes);
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(body);
+  } catch {
+    throw new Error("Request body must be valid UTF-8 JSON");
+  }
+  return JSON.parse(text) as T;
+}

package/src/feishu-api.ts

@@ -621,6 +621,128 @@ export async function sendImageReply(
   }
 }
 
+function feishuFileType(ext: string): string {
+  const map: Record<string, string> = {
+    ".mp4": "mp4",
+    ".mp3": "opus", ".wav": "opus", ".ogg": "opus", ".aac": "opus", ".m4a": "opus",
+    ".pdf": "pdf", ".doc": "doc", ".docx": "doc",
+    ".xls": "xls", ".xlsx": "xls", ".csv": "xls",
+    ".ppt": "ppt", ".pptx": "ppt",
+  };
+  return map[ext] ?? "stream";
+}
+
+const VIDEO_EXTENSIONS = [".mp4", ".mov", ".avi", ".mkv", ".webm", ".flv"];
+
+function parseMediaDurationMs(buffer: Buffer): number {
+  try {
+    let offset = 0;
+    while (offset + 8 <= buffer.length) {
+      const size = buffer.readUInt32BE(offset);
+      const type = buffer.toString("ascii", offset + 4, offset + 8);
+      if (size < 8 || offset + size > buffer.length) break;
+      if (type === "moov") {
+        let mo = offset + 8;
+        const moEnd = offset + size;
+        while (mo + 8 <= moEnd) {
+          const s = buffer.readUInt32BE(mo);
+          const t = buffer.toString("ascii", mo + 4, mo + 8);
+          if (s < 8 || mo + s > moEnd) break;
+          if (t === "mvhd") {
+            const ds = mo + 8;
+            const ver = buffer[ds];
+            let timescale: number, duration: number;
+            if (ver === 1) {
+              timescale = buffer.readUInt32BE(ds + 20);
+              duration = Number(buffer.readBigUInt64BE(ds + 24));
+            } else {
+              timescale = buffer.readUInt32BE(ds + 12);
+              duration = buffer.readUInt32BE(ds + 16);
+            }
+            if (timescale <= 0) return 0;
+            return Math.round((duration / timescale) * 1000);
+          }
+          mo += s;
+        }
+      }
+      offset += size;
+    }
+  } catch {}
+  return 0;
+}
+
+async function uploadMessageFile(token: string, filePath: string): Promise<string> {
+  const ext = extname(filePath).toLowerCase();
+  const isVideo = VIDEO_EXTENSIONS.includes(ext);
+  const buffer = await readFile(filePath);
+  const fileName = filePath.split(/[\\/]/).pop() || "file";
+  const fileType = isVideo ? "stream" : feishuFileType(ext);
+  const blob = new Blob([new Uint8Array(buffer)], { type: isVideo ? "video/mp4" : "application/octet-stream" });
+  const form = new FormData();
+  form.append("file_type", fileType);
+  form.append("file_name", fileName);
+  // 音频文件传 duration（opus 需要）
+  if (fileType === "opus") {
+    const durationMs = parseMediaDurationMs(buffer);
+    if (durationMs > 0) form.append("duration", String(durationMs));
+  }
+  form.append("file", blob, fileName);
+
+  const resp = await fetch(`${BASE_URL}/im/v1/files`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}` },
+    body: form,
+  });
+  const text = await resp.text();
+  let data: { code: number; msg?: string; data?: { file_key?: string } };
+  try { data = JSON.parse(text); } catch {
+    throw new Error(`uploadMessageFile non-JSON response: ${text.slice(0, 200)}`);
+  }
+  if (data.code !== 0) throw new Error(`[${data.code}] ${data.msg}`);
+  const fileKey = data.data?.file_key;
+  if (!fileKey) throw new Error("uploadMessageFile response missing file_key");
+  return fileKey;
+}
+
+export async function sendFileReply(
+  token: string,
+  chatId: string,
+  filePath: string,
+): Promise<boolean> {
+  try {
+    const fileKey = await uploadMessageFile(token, filePath);
+    const fileName = filePath.split(/[\\/]/).pop() || "file";
+    const ext = extname(filePath).toLowerCase();
+    // 视频/音频用 msg_type: "media"，文档用 "file"
+    const isMedia = [".mp3", ".wav", ".ogg", ".aac", ".m4a"].includes(ext);
+    const msgType = isMedia ? "media" : "file";
+    const resp = await fetch(`${BASE_URL}/im/v1/messages?receive_id_type=chat_id`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        receive_id: chatId,
+        msg_type: msgType,
+        content: JSON.stringify({ file_key: fileKey }),
+      }),
+    });
+    const data = (await resp.json().catch(() => ({}))) as { code?: number; msg?: string; data?: { message_id?: string } };
+    if (data.code !== 0) {
+      console.error(`[${ts()}] [SEND] ${msgType} FAIL: chatId=${chatId} path=${filePath} code=${data.code} msg="${data.msg ?? ""}"`);
+      throw new Error(`[${data.code}] ${data.msg ?? "send file failed"}`);
+    }
+    console.log(`[${ts()}] [SEND] ${msgType} OK: chatId=${chatId} name=${fileName} msgId=${data.data?.message_id ?? "N/A"}`);
+    return true;
+  } catch (err) {
+    if (!(err instanceof Error && err.message.startsWith("["))) {
+      console.error(`[${ts()}] [SEND] file FAIL: chatId=${chatId} path=${filePath} ${(err as Error).message}`);
+    }
+    throw err;
+  }
+}
+
 export async function addReaction(
   token: string,
   messageId: string,

package/src/im-skills.ts

@@ -0,0 +1,109 @@
+import { readdir, readFile, mkdir, writeFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+
+import { PROJECT_ROOT } from "./config.ts";
+
+export const DEFAULT_IM_SKILLS_DIR = join(PROJECT_ROOT, "im-skills");
+
+export interface ImSkillVariableMap {
+  [key: string]: string | undefined;
+}
+
+export interface BuildImSkillsPromptInput {
+  skillsDir?: string;
+  variables: ImSkillVariableMap;
+}
+
+interface ImSkillDoc {
+  name: string;
+  content: string;
+}
+
+function renderTemplate(template: string, variables: ImSkillVariableMap): string {
+  return template.replace(/\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g, (_match, key: string) => {
+    return variables[key] ?? "";
+  });
+}
+
+async function loadSkillDocs(skillsDir: string): Promise<ImSkillDoc[]> {
+  let entries;
+  try {
+    entries = await readdir(skillsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const docs = await Promise.all(
+    entries
+      .filter((entry) => entry.isDirectory())
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map(async (entry): Promise<ImSkillDoc | null> => {
+        const skillPath = join(skillsDir, entry.name, "skill.md");
+        try {
+          const content = await readFile(skillPath, "utf-8");
+          return { name: entry.name, content };
+        } catch {
+          return null;
+        }
+      }),
+  );
+  return docs.filter((doc): doc is ImSkillDoc => doc !== null);
+}
+
+export async function buildImSkillsPrompt(input: BuildImSkillsPromptInput): Promise<string> {
+  const skillsDir = input.skillsDir ?? DEFAULT_IM_SKILLS_DIR;
+  const docs = await loadSkillDocs(skillsDir);
+  return docs
+    .map((doc) => {
+      const rendered = renderTemplate(doc.content, input.variables).trim();
+      return [
+        `[ChatCCC IM skill: ${doc.name}]`,
+        rendered,
+        `[/ChatCCC IM skill: ${doc.name}]`,
+      ].join("\n");
+    })
+    .join("\n\n");
+}
+
+/**
+ * 渲染技能目录下的子文档（skill.md 除外）并写入 outputDir。
+ * 返回写入的文件路径列表。通常在会话初始化时调用，写入的文档供 Agent 按需读取。
+ */
+export async function exportSkillSubDocs(
+  input: BuildImSkillsPromptInput,
+  outputDir: string,
+): Promise<string[]> {
+  const skillsDir = input.skillsDir ?? DEFAULT_IM_SKILLS_DIR;
+  const files: string[] = [];
+
+  let entries;
+  try {
+    entries = await readdir(skillsDir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillPath = join(skillsDir, entry.name);
+
+    let subFiles;
+    try {
+      subFiles = await readdir(skillPath);
+    } catch {
+      continue;
+    }
+
+    for (const sf of subFiles) {
+      if (sf === "skill.md" || !sf.endsWith(".md")) continue;
+      const content = await readFile(join(skillPath, sf), "utf-8");
+      const rendered = renderTemplate(content, input.variables);
+      const outPath = join(outputDir, entry.name, sf);
+      await mkdir(dirname(outPath), { recursive: true });
+      await writeFile(outPath, rendered, "utf-8");
+      files.push(outPath);
+    }
+  }
+
+  return files;
+}

package/src/index.ts

@@ -83,6 +83,7 @@ import {
 import { buildHelpCard, buildStatusCard, buildProgressCard, buildCdContent, buildCdCard, buildSessionsCard } from "./cards.ts";
 import { updateCardKitCard } from "./cardkit.ts";
 import { handleAgentImageRequest } from "./agent-image-rpc.ts";
+import { handleAgentFileRequest } from "./agent-file-rpc.ts";
 import { formatGitResult, gitResultHeaderTemplate, runGitCommand } from "./git-command.ts";
 import {
   MAX_PROCESSED,
@@ -160,7 +161,15 @@ async function formatMessageContent(message: { message_id?: string; message_type
     }
   }
 
-  // 其他类型（file, audio, media, sticker）直接给原始 JSON
+  if (message.message_type === "media") {
+    const fileKey = content.file_key as string | undefined;
+    const fileName = (content.file_name as string) || "video.mp4";
+    const messageId = message.message_id;
+    if (!fileKey || !messageId) return contentStr;
+    return `[视频] message_id=${messageId} file_key=${fileKey} file_name=${fileName}`;
+  }
+
+  // 其他类型（file, audio, sticker）直接给原始 JSON
   return contentStr;
 }
 
@@ -1048,7 +1057,9 @@ async function main(): Promise<void> {
       appIdMask: maskAppId(APP_ID),
     });
   });
-  setExtraApiHandler(handleAgentImageRequest);
+  setExtraApiHandler(async (req, res) => {
+    return (await handleAgentImageRequest(req, res)) || (await handleAgentFileRequest(req, res));
+  });
 
   console.log(`[启动 2/7] 环境与凭证检查`);
   reportEnvironmentVariableReadout();

package/src/session.ts

@@ -1,5 +1,5 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 
 import {
   CLAUDE_API_KEY,
@@ -7,7 +7,9 @@ import {
   CLAUDE_EFFORT,
   CLAUDE_MODEL,
   CHATCCC_PORT,
+  PROJECT_ROOT,
   SESSIONS_FILE,
+  USER_DATA_DIR,
   addRecentDir,
   anthropicConfigDisplay,
   config,
@@ -31,10 +33,14 @@ import { createClaudeAdapter } from "./adapters/claude-adapter.ts";
 import { createCursorAdapter } from "./adapters/cursor-adapter.ts";
 import { createCodexAdapter } from "./adapters/codex-adapter.ts";
 import {
-  buildAgentImageCapabilityPrompt,
   createAgentImageGrant,
   revokeAgentImageGrant,
 } from "./agent-image-rpc.ts";
+import {
+  createAgentFileGrant,
+  revokeAgentFileGrant,
+} from "./agent-file-rpc.ts";
+import { buildImSkillsPrompt, exportSkillSubDocs } from "./im-skills.ts";
 
 // ---------------------------------------------------------------------------
 // Shared state (imported by index.ts)
@@ -324,13 +330,31 @@ export async function resumeAndPrompt(
     port: CHATCCC_PORT,
     traceId: tid || undefined,
   });
+  const fileGrant = createAgentFileGrant({
+    chatId,
+    sessionId,
+    cwd,
+    port: CHATCCC_PORT,
+    traceId: tid || undefined,
+  });
+  const feishuSkillDir = join(PROJECT_ROOT, "im-skills", "feishu-skill");
+  const imSkillsCacheDir = join(USER_DATA_DIR, "im-skills");
+  const skillVariables = {
+    cwd,
+    im_skills_cache_dir: imSkillsCacheDir,
+    send_image_url: imageGrant.url,
+    send_image_token: imageGrant.token,
+    send_file_url: fileGrant.url,
+    send_file_token: fileGrant.token,
+    send_image_script: join(feishuSkillDir, "send-image.mjs"),
+    send_file_script: join(feishuSkillDir, "send-file.mjs"),
+    download_video_script: join(feishuSkillDir, "download-video.mjs"),
+  };
+  const imSkillsPrompt = await buildImSkillsPrompt({ variables: skillVariables });
+  // 渲染子文档到缓存目录，供 Agent 按需读取
+  await exportSkillSubDocs({ variables: skillVariables }, imSkillsCacheDir);
   const userTextWithCapabilities = [
-    buildAgentImageCapabilityPrompt({
-      url: imageGrant.url,
-      token: imageGrant.token,
-      cwd,
-    }),
-    "",
+    ...(imSkillsPrompt ? [imSkillsPrompt, ""] : []),
     "[User message]",
     userText,
     "[/User message]",
@@ -491,6 +515,7 @@ export async function resumeAndPrompt(
   } finally {
     if (sendInterval) clearInterval(sendInterval);
     revokeAgentImageGrant(imageGrant.token);
+    revokeAgentFileGrant(fileGrant.token);
   }
 
   const cEntry = chatSessionMap.get(chatId);