agent-loft 0.0.0-stage → 0.2.7

package/src/core/types.ts

@@ -0,0 +1,213 @@
+// 核心类型：渠道（飞书 / Web / 以后的 Telegram）与 agent（Claude / Codex / 以后的 ACP）
+// 之间只通过这里的类型说话。渠道不认识 Claude，agent 不认识飞书。
+import type { AgentCommand } from "./command-catalog.js";
+
+// ---------- 用户输入 ----------
+
+export type AttachmentKind = "image" | "file" | "audio" | "video";
+
+/** 已经落盘的附件。各渠道负责下载 / 接收，agent 负责决定怎么喂给模型。 */
+export type SavedAttachment = {
+  kind: AttachmentKind;
+  path: string;
+  name: string;
+  size: number;
+  mediaType?: string;
+  durationMs?: number;
+};
+
+export type UserInput = { text: string; attachments: SavedAttachment[] };
+
+// ---------- 交互（审批 / 提问） ----------
+
+/**
+ * allow-session：本会话内后续的审批全部自动放行（不落盘）。会话重建
+ * （/new、切目录、切 agent、恢复历史、进程重启）后失效。
+ */
+export type ApprovalDecision = "allow-once" | "allow-always" | "allow-session" | "deny";
+
+/** 一个卡点的收束方式。timeout / cancelled 和 deny 一样都是「没放行」，但显示不同。 */
+export type Settlement = ApprovalDecision | "timeout" | "cancelled" | "answered" | "skipped";
+
+export type QuestionSpec = {
+  /** 回填答案时用的键：Claude 用问题原文，Codex 用问题 id */
+  id: string;
+  header: string;
+  question: string;
+  options: { label: string; description?: string }[];
+  multiSelect: boolean;
+  /** 允许自由输入（直接发一条消息作答） */
+  allowOther: boolean;
+};
+
+export type InteractionSpec =
+  | {
+      kind: "approval";
+      title: string;
+      /** markdown */
+      detail: string;
+      /** 「总是允许」按钮的文字；不给就没有这个按钮 */
+      alwaysLabel?: string;
+      /** 给了就显示「本会话全部允许」按钮。只有 agent 能真正兑现时才给 */
+      allowSession?: boolean;
+    }
+  | { kind: "question"; title: string; questions: QuestionSpec[] };
+
+export type InteractionOutcome = {
+  settlement: Settlement;
+  /** 仅提问：问题 id → 选中的答案（多选为多个） */
+  answers: Record<string, string[]>;
+};
+
+/** agent 向用户发起交互的入口，由核心实现。返回值是用户的决定。 */
+export type InteractionHost = (spec: InteractionSpec) => Promise<InteractionOutcome>;
+
+// ---------- agent 产生的事件 ----------
+
+export type StepKind = "thinking" | "tool" | "note" | "warning";
+
+export type TurnResult = {
+  text: string;
+  durationMs: number;
+  costUsd?: number;
+  tokens?: number;
+  /** 这条回复在 agent 记录里的位置，从这里分叉用（见 AgentDriver.forkAt） */
+  anchor?: string;
+};
+
+export type AgentEvents = {
+  /** 一轮开始（agent 真正开始处理） */
+  onTurnStart?: () => void;
+  /** 过程信息：思考、工具调用等，一行摘要 */
+  onStep: (kind: StepKind, text: string) => void;
+  /** 回复正文的流式片段（可选能力，飞书不用，Web 用来逐字显示） */
+  onTextDelta: (delta: string) => void;
+  /** 一段完整的回复正文 */
+  onText: (text: string) => void;
+  onResult: (result: TurnResult) => void;
+  onError: (err: unknown) => void;
+  /** 拿到 / 更新了 agent 侧的会话 id，持久化后用于 resume */
+  onSessionId: (id: string) => void;
+  /** 有 n 条排队中的输入被丢弃了（不会再有结果）：调用方据此结清「进行中」的计数 */
+  onDropped?: (n: number) => void;
+  /** 上下文窗口占用更新了（一般在每轮结束后） */
+  onContext?: (ctx: ContextUsage) => void;
+};
+
+/** 上下文窗口占用：used / window 都是 token 数，percent 是 0-100（可能略超 100） */
+export type ContextUsage = { used: number; window: number; percent: number };
+
+/** 账号额度（订阅的用量窗口）。没有订阅额度（API key 之类）时 driver 返回 null */
+export type QuotaInfo = {
+  plan?: string;
+  windows: {
+    /** 完整名称，如「5 小时」「7 天（Opus）」 */
+    label: string;
+    /** 紧凑显示用，如「5h」「7d」 */
+    short: string;
+    percent: number;
+    /** 重置时刻（毫秒时间戳） */
+    resetsAt?: number;
+  }[];
+  /** 额度包等附加说明 */
+  extra?: string;
+  /** 已撞上限 */
+  reached?: boolean;
+};
+
+// ---------- agent ----------
+
+export type RuntimeInfo = { model?: string; effort?: string };
+
+export type ModelInfo = {
+  id: string;
+  label: string;
+  description?: string;
+  efforts?: string[];
+  isDefault?: boolean;
+};
+
+export type SessionSummary = {
+  id: string;
+  title: string;
+  cwd?: string;
+  updatedAt: number;
+};
+
+export type HistoryMessage = {
+  role: "user" | "assistant";
+  text: string;
+  /** 助手这一条之前的过程摘要 */
+  steps?: string[];
+  /** 毫秒时间戳；助手消息是这一轮结束的时间 */
+  ts?: number;
+  /** 助手消息：从这条回复处分叉用的位置（见 AgentDriver.forkAt） */
+  anchor?: string;
+  /** 助手消息：这一轮的用时 / 费用 / tokens（agent-loft 自己记的，agent 记录里没有） */
+  footer?: string;
+};
+
+export type SessionOptions = {
+  cwd: string;
+  model?: string;
+  effort?: string;
+  resumeId?: string;
+  fork?: boolean;
+  /** 附件所在目录，agent 需要能直接读 */
+  uploadsDir: string;
+  /** 工作目录内改文件不再询问（/autoedit）。Bash 等照常询问 */
+  autoEdit?: boolean;
+};
+
+export interface AgentSession {
+  readonly sessionId: string | undefined;
+  send(input: UserInput): void;
+  interrupt(): Promise<void>;
+  setModel(model?: string, effort?: string): Promise<void>;
+  describeRuntime(): Promise<RuntimeInfo>;
+  /** 手上已知的模型 / 思考程度，同步返回：不拉起进程、不发请求 */
+  peekRuntime?(): RuntimeInfo;
+  dispose(): Promise<void>;
+  /** 运行中切换「自动允许改文件」；不支持的 agent 不实现 */
+  setAutoEdit?(on: boolean): Promise<void>;
+}
+
+export type Diagnosis = {
+  /** 发给用户看的一句人话 */
+  chatMessage: string;
+  /** 打在日志里的修复步骤 */
+  consoleHint: string;
+  kind: string;
+};
+
+export interface AgentDriver {
+  readonly id: string;
+  readonly label: string;
+  /** 能力声明：前端据此决定显示哪些控件 */
+  readonly capabilities: { effort: boolean; fork: boolean; cost: boolean; streaming: boolean };
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  createSession(opts: SessionOptions, events: AgentEvents, host: InteractionHost): AgentSession;
+  /** cwd 为 undefined 时列全部目录 */
+  listSessions(cwd: string | undefined, limit?: number): Promise<SessionSummary[]>;
+  sessionExists(id: string, cwd: string): Promise<boolean>;
+  readHistory(id: string, cwd: string): Promise<HistoryMessage[]>;
+  /**
+   * 把会话复制出一条新的、返回新会话 id。anchor（HistoryMessage / TurnResult 里的）给了就只保留到
+   * 那条回复为止（含），不给就整条复制。原会话不受影响。
+   */
+  forkAt?(id: string, cwd: string, anchor?: string): Promise<string>;
+  /** 有的 agent（Claude）要借一个活着的会话才能问到模型列表 */
+  listModels(session: AgentSession): Promise<ModelInfo[]>;
+  /** 不依赖会话的模型列表，设置页的下拉框用 */
+  catalog(): Promise<ModelInfo[]>;
+  /** agent 自己的斜杠命令（skills 之类），没有就不实现。cwd 影响项目级命令 */
+  commands?(cwd?: string): Promise<AgentCommand[]>;
+  /** 不建会话也能知道的默认模型 / 思考程度 */
+  defaults(): Promise<RuntimeInfo>;
+  /** /status 里额外的几行（比如 Codex 的额度） */
+  statusLines(): Promise<string[]>;
+  /** 账号额度，侧栏显示用；读不到 / 没有订阅额度时返回 null */
+  quota?(): Promise<QuotaInfo | null>;
+  diagnose(err: unknown): Diagnosis;
+}

package/src/core/uploads.ts

@@ -0,0 +1,200 @@
+// 附件落盘：每条会话一个上传目录，开新会话就整个删掉。
+//
+// 放在家目录下而不是项目目录里，免得弄脏用户的仓库。agent 需要能直接读这些文件：
+// Claude 通过 additionalDirectories 放行，Codex 的沙箱本来就允许读。
+import fs from "node:fs";
+import path from "node:path";
+import { dataDir } from "../home.js";
+import type { AttachmentKind, SavedAttachment } from "./types.js";
+
+const uploadsRoot = path.join(dataDir, "uploads");
+
+export function uploadsDirFor(key: string): string {
+  return path.join(uploadsRoot, encodeURIComponent(key));
+}
+
+export function ensureUploadsDir(key: string): string {
+  const dir = uploadsDirFor(key);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * keep：要保留的文件（绝对路径）。
+ * olderThan：只删修改时间早于它的（毫秒时间戳）—— 切换会话时用，保住切换途中刚收到的附件。
+ */
+export function clearUploads(key: string, keep: string[] = [], olderThan?: number): void {
+  try {
+    const dir = uploadsDirFor(key);
+    if (keep.length === 0 && olderThan === undefined) {
+      fs.rmSync(dir, { recursive: true, force: true });
+      return;
+    }
+    const kept = new Set(keep.map((p) => path.resolve(p)));
+    for (const entry of fs.readdirSync(dir)) {
+      const full = path.join(dir, entry);
+      if (kept.has(full)) continue;
+      if (olderThan !== undefined && fs.statSync(full).mtimeMs >= olderThan) continue;
+      fs.rmSync(full, { recursive: true, force: true });
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return;
+    console.warn(`[附件] 清理 ${key} 的上传目录失败:`, err);
+  }
+}
+
+/** 启动时清理：会话没了、或闲置过期的，目录一并删掉。 */
+export function sweepUploads(isAlive: (key: string) => boolean): void {
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(uploadsRoot);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    let key: string;
+    try {
+      key = decodeURIComponent(entry);
+    } catch {
+      continue;
+    }
+    if (isAlive(key)) continue;
+    fs.rmSync(path.join(uploadsRoot, entry), { recursive: true, force: true });
+  }
+}
+
+/** 去掉路径分隔符和控制字符，防止文件名把文件写到目录外面去。 */
+export function safeName(name: string): string {
+  const cleaned = path
+    .basename(name)
+    .replace(/[\u0000-\u001f/\\]/g, "_")
+    .trim();
+  return cleaned && cleaned !== "." && cleaned !== ".." ? cleaned.slice(0, 120) : "file";
+}
+
+/** 按文件头判断类型。飞书给的图片没有文件名，扩展名只能靠这个。 */
+export function sniff(buf: Buffer): { mediaType: string; ext: string } | undefined {
+  const hex = buf.subarray(0, 12).toString("hex");
+  if (hex.startsWith("89504e47")) return { mediaType: "image/png", ext: "png" };
+  if (hex.startsWith("ffd8ff")) return { mediaType: "image/jpeg", ext: "jpg" };
+  if (hex.startsWith("47494638")) return { mediaType: "image/gif", ext: "gif" };
+  if (hex.startsWith("52494646") && buf.subarray(8, 12).toString("ascii") === "WEBP") {
+    return { mediaType: "image/webp", ext: "webp" };
+  }
+  if (hex.startsWith("25504446")) return { mediaType: "application/pdf", ext: "pdf" };
+  if (buf.subarray(0, 4).toString("ascii") === "OggS") return { mediaType: "audio/ogg", ext: "opus" };
+  if (buf.subarray(4, 8).toString("ascii") === "ftyp") return { mediaType: "video/mp4", ext: "mp4" };
+  return undefined;
+}
+
+/** 同名文件不覆盖，加序号。 */
+export function uniquePath(dir: string, name: string): string {
+  let candidate = path.join(dir, name);
+  const ext = path.extname(name);
+  const stem = name.slice(0, name.length - ext.length);
+  for (let i = 2; fs.existsSync(candidate); i++) candidate = path.join(dir, `${stem}-${i}${ext}`);
+  return candidate;
+}
+
+function kindOf(mediaType: string | undefined): AttachmentKind {
+  if (mediaType?.startsWith("image/")) return "image";
+  if (mediaType?.startsWith("audio/")) return "audio";
+  if (mediaType?.startsWith("video/")) return "video";
+  return "file";
+}
+
+/**
+ * 把一段已在内存 / 临时文件里的内容存成附件。
+ * kind 不给就按文件头 / 声明的类型猜。
+ */
+export function saveBuffer(params: {
+  key: string;
+  data: Buffer;
+  name?: string;
+  kind?: AttachmentKind;
+  mediaType?: string;
+  durationMs?: number;
+  /** 存进上传目录下的这个子目录（Web 用上传 id：每次上传路径唯一，重置后旧 id 不会撞上同名新文件） */
+  subdir?: string;
+}): SavedAttachment {
+  const dir = params.subdir
+    ? path.join(ensureUploadsDir(params.key), safeName(params.subdir))
+    : ensureUploadsDir(params.key);
+  fs.mkdirSync(dir, { recursive: true });
+  const sniffed = sniff(params.data);
+  const mediaType = sniffed?.mediaType ?? params.mediaType;
+  const kind = params.kind ?? kindOf(mediaType);
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "");
+  const name = params.name ? safeName(params.name) : `${kind}-${stamp}${sniffed ? `.${sniffed.ext}` : ""}`;
+  const target = uniquePath(dir, name);
+  fs.writeFileSync(target, params.data);
+  return {
+    kind,
+    path: target,
+    name: path.basename(target),
+    size: params.data.length,
+    ...(mediaType ? { mediaType } : {}),
+    ...(params.durationMs ? { durationMs: params.durationMs } : {}),
+  };
+}
+
+/** 已经下载到临时文件的：探测类型后挪进上传目录。 */
+export function adoptFile(params: {
+  key: string;
+  tmpPath: string;
+  name?: string;
+  kind: AttachmentKind;
+  durationMs?: number;
+}): SavedAttachment {
+  const dir = ensureUploadsDir(params.key);
+  const head = Buffer.alloc(12);
+  const fd = fs.openSync(params.tmpPath, "r");
+  fs.readSync(fd, head, 0, 12, 0);
+  fs.closeSync(fd);
+  const sniffed = sniff(head);
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "");
+  const name = params.name
+    ? safeName(params.name)
+    : `${params.kind}-${stamp}${sniffed ? `.${sniffed.ext}` : ""}`;
+  const target = uniquePath(dir, name);
+  fs.renameSync(params.tmpPath, target);
+  return {
+    kind: params.kind,
+    path: target,
+    name: path.basename(target),
+    size: fs.statSync(target).size,
+    ...(sniffed ? { mediaType: sniffed.mediaType } : {}),
+    ...(params.durationMs ? { durationMs: params.durationMs } : {}),
+  };
+}
+
+export const KIND_LABEL: Record<AttachmentKind, string> = {
+  image: "图片",
+  file: "文件",
+  audio: "语音",
+  video: "视频",
+};
+
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}
+
+/** 附件清单的文字说明，两个 agent 都用它告诉模型文件在哪。 */
+export function describeAttachments(
+  saved: SavedAttachment[],
+  inlined: (a: SavedAttachment) => boolean,
+): string {
+  const counters: Partial<Record<AttachmentKind, number>> = {};
+  const lines = saved.map((a) => {
+    const n = (counters[a.kind] = (counters[a.kind] ?? 0) + 1);
+    const details = [
+      formatSize(a.size),
+      ...(a.durationMs ? [`时长 ${Math.round(a.durationMs / 1000)} 秒`] : []),
+      ...(inlined(a) ? ["内容已附在本消息中"] : []),
+    ];
+    return `- ${KIND_LABEL[a.kind]}${n}：${a.path}（${details.join("，")}）`;
+  });
+  return ["[用户发来了以下附件，已保存到本地，需要时可以直接读取或处理这些文件]", ...lines].join("\n");
+}

package/src/home.ts

@@ -0,0 +1,43 @@
+// 家目录定位。单独成模块：CLI 里有些命令在配置存在之前就要跑，
+// 它们只需要知道目录在哪，不该被配置校验挡住。
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * 配置与状态的家目录。AGENT_LOFT_HOME 可覆盖，默认 ~/.agent-loft。
+ * 兼容改名前（im-agent）：旧的 IM_AGENT_HOME 也认；新目录还不存在而 ~/.im-agent 在，就继续用旧目录，
+ * 不自动搬家 —— 正在跑的旧服务还在写它。
+ */
+export const home = (() => {
+  const explicit = (process.env.AGENT_LOFT_HOME ?? process.env.IM_AGENT_HOME)?.trim();
+  if (explicit) return path.resolve(explicit);
+  const current = path.join(os.homedir(), ".agent-loft");
+  const legacy = path.join(os.homedir(), ".im-agent");
+  if (!fs.existsSync(current) && fs.existsSync(legacy)) return legacy;
+  return current;
+})();
+
+export const configPath = path.join(home, "config.json");
+export const dataDir = path.join(home, "data");
+export const logsDir = path.join(home, "logs");
+
+export function ensureDirs(): void {
+  for (const dir of [home, dataDir, logsDir]) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+
+/** 原子写：先写临时文件再 rename，进程中途被杀也不会留下半截 JSON。 */
+export function writeJsonAtomic(file: string, value: unknown, mode = 0o600): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2), { mode });
+  fs.renameSync(tmp, file);
+}
+
+export function readJson<T>(file: string, fallback: T): T {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as T;
+  } catch {
+    return fallback;
+  }
+}

package/src/main.ts

@@ -0,0 +1,68 @@
+// 入口：拉起 agent 驱动、飞书机器人和 Web 服务。
+import { config, loadConfig, onConfigChange } from "./core/config.js";
+import { hub } from "./core/hub.js";
+import { flushStore, getConversation, isExpired } from "./core/store.js";
+import { sweepUploads } from "./core/uploads.js";
+import { ClaudeDriver } from "./agents/claude/driver.js";
+import { CodexDriver } from "./agents/codex/driver.js";
+import { startFeishu, stopFeishu } from "./channels/feishu/index.js";
+import { startWeb, stopWeb } from "./channels/web/server.js";
+import { home } from "./home.js";
+
+async function startDriver(id: "claude" | "codex"): Promise<void> {
+  const driver = hub.driver(id);
+  if (!driver) return;
+  try {
+    await driver.start();
+  } catch (err) {
+    const diagnosis = driver.diagnose(err);
+    console.error(`[${id}] 启动失败：${diagnosis.consoleHint}`);
+  }
+}
+
+async function main(): Promise<void> {
+  loadConfig();
+  console.log(`[启动] agent-loft，配置目录 ${home}`);
+
+  hub.registerDriver(new ClaudeDriver());
+  hub.registerDriver(new CodexDriver());
+  if (config().agents.claude.enabled) await startDriver("claude");
+  if (config().agents.codex.enabled) await startDriver("codex");
+  // Web 上新启用了 Codex：现拉 app-server
+  onConfigChange((next, prev) => {
+    if (next.agents.codex.enabled && !prev.agents.codex.enabled) void startDriver("codex");
+  });
+
+  sweepUploads((key) => {
+    const conv = getConversation(key);
+    return !!conv && !isExpired(conv);
+  });
+
+  startFeishu();
+  if (config().web.enabled) await startWeb();
+
+  console.log(`[启动] workspace=${config().workspaceRoot}`);
+  if (config().workspaceRoot === process.cwd()) {
+    console.warn("[启动] ⚠️ 工作目录就是 agent-loft 自身目录，agent 会在它的代码里干活。到设置里改 workspaceRoot。");
+  }
+
+  let stopping = false;
+  const shutdown = async (signal: string) => {
+    if (stopping) return;
+    stopping = true;
+    console.log(`[退出] 收到 ${signal}，正在收尾…`);
+    const force = setTimeout(() => process.exit(0), 8000);
+    force.unref();
+    stopFeishu();
+    await stopWeb();
+    await hub.shutdown().catch(() => {});
+    flushStore();
+    process.exit(0);
+  };
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("exit", (code) => console.log(`[退出] agent-loft 结束，退出码 ${code}`));
+  process.on("unhandledRejection", (err) => console.error("[未处理的异常]", err));
+}
+
+void main();