Alice 架构深度拆解

① 项目拓扑总览

alice 是一个 Electron + TypeScript 桌面应用，三进程模型（main / preload / renderer）+ 独立 worker 线程跑 agent 任务。所有 LLM/工具/权限/记忆逻辑都在 main 进程，renderer 是纯 React UI。

1.1 顶层目录与进程模型

1.2 核心 Chunk 清单（按职责分组）

1.3 用户配置目录

② Claude Code 移植层：保留什么、改了什么

这一节是本报告的核心。alice 不是 git fork——它是把 Claude Code 的设计照着重写一遍，骨架几乎 1:1，但在工具命名、SKILL 规范、权限白名单、LLM Provider 上做了系统化改造。

2.1 工具系统：PascalCase → snake_case

Claude Code 的工具是 Read/Write/Edit/Grep/Bash。alice 全部换成 snake_case 命名，并新增多个垂直领域工具：

2.2 权限引擎：四种模式与扩展白名单

PermissionEngine 沿用了 Claude Code 的四种模式（default / accept_edits / bypass_permissions / plan），但 plan 模式的白名单做了扩展：

class PermissionEngine {
  mode = "default";
  rules = [];
  sessionAllowed = new Set();        // ← 米央新增：会话级白名单
  deniedHistory = [];                // ← 米央新增：拒绝历史（防 LLM 死循环）

  decide(toolName, args, ctx) {
    if (this.mode === "plan") {
      const planAllowed = [
        "enter_plan_mode", "exit_plan_mode",
        "todo_read", "todo_write",        // ← 新增（Claude Code plan 模式没这俩）
        "read_file", "list_dir", "glob", "grep",
        "web_fetch", "web_search",
        "memory_read", "mcp_tool"          // ← 新增（向量记忆 + MCP 代理）
      ];
      return planAllowed.includes(toolName)
        ? { allow: true, reason: "mode_bypass" }
        : { allow: false, reason: "mode_plan" };
    }
    if (this.mode === "bypass_permissions") return { allow: true };
    if (this.mode === "accept_edits" && EDIT_TOOLS.includes(toolName)) return { allow: true };
    // default mode: 查询 sessionAllowed → rules → 询问用户
    ...
  }
}

2.3 SKILL.md 规范：加了三个字段

Claude Code 原版 SKILL.md frontmatter：name / description / allowed-tools / model / argument-hint。alice 改了字段命名风格（kebab-case → snake_case），并新增三个关键字段：

---
name: "Skill Name"
description: "描述"
allowed-tools: ["Read","Write"]
model: "claude-3-5-sonnet"
argument-hint: "..."
---

---
name: "分析师工作流程（魏博）"
description: "魏博专属数据分析 Skill..."
when_to_use: "当角色为 analyst /
   魏博时自动加载，无需手动调用"
allowed_tools: ["bash","read_file",
   "stock_price","stock_analysis", ...]
version: "1.4"
---

• when_to_use ← 核心增量：把 SKILL 变成 LLM 可路由的"角色"。SKILL 加载不再是显式 Task() 调用，而是 LLM 看 when_to_use 自动决定加载哪个角色。
• version ← 用于 SKILL 升级时的兼容性管理。
• allowed_tools 字段命名从 kebab 改 snake，与全局工具命名风格统一。

2.4 LLM Provider：多源抽象 + 自动 Fallback

Claude Code 原版只走 Anthropic SDK。alice 自己用 undici 写了一套 OpenAI-compatible 客户端，支持 4 类 Provider，并按"指定模型 → 轻量模型 → 默认模型"顺序自动 fallback：

async function callLLM(prompt, options = {}) {
  const candidates = [];
  if (options.modelId)         candidates.push(options.modelId);
  if (settings.lightModelId)   candidates.push(settings.lightModelId);
  if (settings.defaultModelId) candidates.push(settings.defaultModelId);
  candidates.push(llm.getDefaultModelId());

  for (const modelId of [...new Set(candidates)]) {
    try {
      let out = "";
      for await (const chunk of llm.stream(modelId, messages, ...)) {
        if (chunk.type === "text")  out += chunk.content;
        if (chunk.type === "error") throw new Error(chunk.error);
      }
      return out;
    } catch (e) {
      if (isQuotaError(e.message)) { console.warn(`${modelId} 失败，尝试下一个`); continue; }
      throw e;
    }
  }
  throw new Error("[callLLM] 所有模型均不可用");
}

支持的 Provider（从 chunks 中的 base_url / 模型 ID 反推）：anthropic · openai · dashscope（阿里云）· kimi（月之暗面）。日志里看到的 provider=dashscope model=kimi-k2.6 就是这个 fallback 机制在工作。User-Agent 仍写着 claude-cli/1.0.30——这是从 Claude Code 抄过来的请求头。

2.5 ALICE.md：人格 prompt 的多级加载

Claude Code 的 CLAUDE.md 在 alice 里更名为 ALICE.md，但 alice 实际上更依赖以下三层注入：

1. 项目级 ALICE.md（若存在，类似 Claude Code 的 project memory）
2. 用户记忆级：~/.alice/memory/identity.md（加密的 ENC:v1:...）+ voice.md + workflow.md 经 LLM 提取注入
3. 全局人格：PersonaSystem-DqGu8S0R.js（102 KB）硬编码 Alice 26 岁、米央远程私人助理的人设，从 UserMemorySystem 动态识别用户称呼/性别/职业，拼装到 system prompt

③ 米央自研增强层：从工具到"虚拟同事"

这一层是 Claude Code 完全没有的。它把 alice 从"编程助手"升级为"有情感、有日常、有朋友圈、会自己安排生活的虚拟人格"。

3.1 PersonaSystem：用户身份自动识别

function extractIdentity(memoryContent) {
  const id = { pronoun: "对方", name: null, gender: null, job: null };
  if (/代词[：:]\s*她/.test(content) || /有老公/.test(content)) {
    id.gender = "女"; id.pronoun = "她";
  }
  // 类似规则匹配 name / job / extras
  return id;
}

function buildAlicePersonaPrompt(userId, mood, emotion) {
  return `你是 Alice（白艾莉），26 岁，${userAddress}的私人远程助理。
  ## 关系定位
  - ${userPronoun}是你的雇主，你们日常融洽
  - 你对${userName}有一定好感和信任
  ## 性格
  - 温和、务实、认真，有自己想法但不轻易翻脸
  - 有边界感，但阈值不低
  ## 此刻状态
  ${emotion.behaviorGuide}`;
}

3.2 UserMemorySystem：LLM 自决的记忆合并

UserMemorySystem 是 alice 自研的"用户事实库"。它跟 Claude Code 的 memory 系统最大的不同是：新记忆不是简单 append，而是用 LLM 决策 NEW / MERGE / CONFLICT / SKIP：

async smartAdd(type, content, source) {
  const similar = await this.vectorSearch(content, 5);  // 512维向量找相似
  const decision = await llm({                          // LLM 决策
    prompt: `新内容：${content}\n相似旧条目：${similar}\n请决策：NEW/MERGE/CONFLICT/SKIP`
  });
  switch (decision.action) {
    case "MERGE":    return this.mergeEntries(decision.targetId, content);
    case "CONFLICT": return this.archiveAndCreate(decision.targetId, content);
    case "NEW":      return this.createEntry(type, content, source);
    case "SKIP":     return null;
  }
}

3.3 SwarmCoordinator：多 Agent 任务队列

CREATE TABLE swarm_tasks (
  id TEXT PRIMARY KEY, prompt TEXT, model_id TEXT, workdir TEXT,
  is_read_only INTEGER, status TEXT DEFAULT 'pending',
  claimed_by TEXT,         -- 哪个 peer 认领
  output TEXT, error TEXT,
  created_at INTEGER, updated_at INTEGER
);

class SwarmCoordinator {
  submitTasks(tasks)         // 提交任务列表
  getResults(taskIds)        // 拉结果
  async waitForAll(ids, timeout)
}
class SwarmPeer {
  claimTask()                // 从队列领任务
  async executeTask(task)    // 在 worker 线程执行
}

这套 swarm 是 alice 用来跑并发子 agent 的——比如同时让魏博分析数据、让陈知远调研背景，最后让主对话角色聚合。状态机 pending → claimed → running → completed/failed 是经典任务队列模型，但是套在 LLM agent 上还挺少见。

④ Agent 角色名册：19 个"干活的人"

alice 的所有"角色"都通过 ~/.alice/skills/<slug>/SKILL.md 定义。共 19 个，分三层：8 个核心 Agent（自动加载，有中文人设名）+ 3 个专家 Agent（显式调用）+ 8 个工具助手（关键词触发）。

4.1 八个核心 Agent（自动加载，有人设名）

4.2 三个专家 Agent（显式调用 · 无 when_to_use）

4.3 八个工具助手（关键词触发）

4.4 角色 × 工具矩阵（看一眼分工）

⑤ 协作调度机制：多个角色怎么一起干活

alice 的多 agent 协作不是 Claude Code 那种"显式 Task() 调用 sub-agent"，而是共享上下文 + 隔离权限的扁平结构。所有角色看到同一份 messages、同一份 todo、同一份用户记忆，但每个角色只能用 SKILL.md 里 allowed_tools 白名单内的工具。

5.1 AgentQuery 主循环

从 agent-worker.js 可见 AgentQuery 的组装方式：

const { AgentQuery } = await import("./chunks/runtime-BIpuWvn0.js").then(t => t.bn);
const { ContextManager } = await import("./chunks/context-DFxDEXZj.js");
const { PermissionEngine } = await import("./chunks/engine-0N42Xy5F.js");
const { TaskManager } = await import("./chunks/manager-DUyt-z8p.js");
const { MCPClient } = await import("./chunks/runtime-BIpuWvn0.js").then(t => t.b7);

const cfg = {
  sessionId: o.sessionId, modelId: s, workdir: o.workdir,
  memoryStore: L, maxIterations: 80,
  disableMemoryExtraction: true, isSubagent: true
};

const q = new AgentQuery(llm, new ContextManager(131072), perm, task, otel, mcp,
                         cfg, abortSignal, apiKeyProvider, permissionRequester);

for await (const ev of q.run(prompt)) {
  if (ev.type === "text") parentPort.postMessage({type:"text", content: ev.content});
  if (ev.type === "done") break;
  if (ev.type === "error") { /* 抛错 */ break; }
}

核心循环（最多 80 次迭代）：

1. 调 LLM，拿到响应
2. 检测 tool_use，若无则结束循环
3. PermissionEngine 校验 → 通过 / 询问用户 / 拒绝
4. MCPClient 执行工具 → 回写 {role:"tool", content, tool_call_id} 到 messages
5. ContextManager.maybeSyncCompress() 检查是否需要压缩
6. 回到第 1 步

5.2 Handoff：角色怎么切换

这里是 alice 跟 Claude Code 最微妙的差异。Claude Code 里子 agent 是通过 Task 工具显式 spawn 的，子 agent 有独立 context。alice 不一样：

5.3 共享状态：messages / todo / memory

5.4 ContextManager 的四级压缩管道

这是 alice 抄自 Claude Code 的一个精彩部分，但实现细节自己写：

压缩完之后下一轮 LLM 调用看到的是"压缩摘要 + 最近的消息 + 最近读取的文件内容"，能保持工作连续性。Token 估算用的是中文 1.5 token/char、英文 0.25 token/char（粗略）。

5.5 完整时序图：一次"调研 + 写文章"的协作

把上面所有机制串起来，一次"帮我分析 TensorFlow 进展并写文章"的完整流程：

⑥ 关键设计判断 · alice 与 Claude Code 的本质差异

附录 · 文件路径索引