Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* scope-resolver.ts — resolveMemoryScopeKey: Maker Memory scope key 的 async
* 归一化入口 (#2379 问题一)。
*
* 背景: buildMemoryScopeKey (storage.ts) 是纯同步函数, 本地会话原样透传 workdir
* 绝对路径。git linked worktree 的 cwd ≠ 主仓路径 → 同一仓库被拆成多个独立
* Store, worktree 会话 memory_search 恒 0 命中 (实测主仓分片 80 条记录,
* worktree 分片是空库基线)。
*
* 本模块只做一件事: 本地会话取 scope key 前先做 worktree 归一化 ——
* linked worktree 的 cwd → `主仓根 + cwd 相对 worktree 根的子路径`
* 例: /repo/.cindy-worktrees/feat-x/apps/a → /repo/apps/a
* 即保留「按 cwd 隔离」的既有语义 (子目录仍是独立 scope), 只把 worktree 根
* 替换回主仓根。「整个仓库共用一份 memory」是 scope 语义变更, 明确不在
* 本模块做 (#2379 评论收敛)。
*
* 分工:
* - buildMemoryScopeKey (同步): SSH 复合键规则 + 本地原样透传的既有契约, 不变。
* - resolveMemoryScopeKey (async, 本模块): 所有 getStore 调用方的统一入口。
* SSH 直接委托 buildMemoryScopeKey (不在控制端解析远端 git); 本地先归一化。
*
* 回落 (一律返回 cwd 原样, 与既有行为完全一致): 非 git 目录 / git 不可用 /
* 探测超时 / bare repo / 非 linked-worktree 布局 (普通 clone /
* --separate-git-dir checkout, gitdir == common-dir 且无 superproject) /
* 非常规 common-dir 布局 / cwd 不在 toplevel 下。
* 特例: linked worktree 内初始化过的 submodule 的 gitdir == common-dir
* (都是 `<主仓>/.git/worktrees/<wt>/modules/<sub>`), 不能当普通 clone 回落;
* `--show-superproject-working-tree` 只给直接父仓库, 二级 submodule 的父是
* 另一层 submodule 而不是 worktree — 必须沿 superproject 链走到最外层
* (linked worktree 或主仓) 再归一, 否则 `git worktree list` 会把 `.git`
* 元数据目录报成唯一 worktree。
* 非仓库目录由 `.git` 标记上溯预检直接短路, 连 git 进程都不 spawn
* (hasGitMarkerUpward, 与 rev-parse 上溯语义一致)。
*
* 缓存: lizi-mcps withStore 在每次 memory 工具调用都经本函数, 不能每次 spawn
* git 子进程 — 进程内 Map 缓存 (正/负结果同 TTL, in-flight promise 去重)。
* TTL 兜底「目录身份在进程生命周期内变化」(目录后变成 worktree 等) 的极端
* 场景; 归一化本身幂等 (主仓路径再解析返回自身), 缓存不破坏正确性。
*/
import { execFile } from 'node:child_process';
import { promises as fs } from 'node:fs';
import * as path from 'node:path';
import { promisify } from 'node:util';
import { buildMemoryScopeKey, SSH_SCOPE_KEY_PREFIX } from './storage.js';
const BOT_SCOPE_KEY_PREFIX = 'bot:';
/** git 探测抽象: 跑一条 git 命令, resolve stdout。失败 (非 git 目录/超时/无 git) reject。 */
export type GitProbe = (args: string[], cwd: string) => Promise<string>;
export interface ResolveMemoryScopeKeyDeps {
/**
* 测试注入: 替代真实 git 调用 (fake 驱动失败/超时/缓存断言)。
* 注入 execGit 时跳过 .git 标记预检 — 调用方显式接管探测, 预检无意义。
*/
execGit?: GitProbe;
/** 测试注入: 时钟 (TTL 过期路径)。 */
now?: () => number;
}
/** 单次 git 探测超时。会话启动路径, 宁可回落也不卡 spawn。 */
const GIT_PROBE_TIMEOUT_MS = 3_000;
/** 缓存 TTL (正/负结果一致)。目录身份中途变化是极端场景, 60s 收敛足够。 */
const CACHE_TTL_MS = 60_000;
const execFileAsync = promisify(execFile);
/**
* 预检: cwd 或任一祖先目录存在 `.git` 才值得 spawn git。非仓库目录 (dialogue
* 一次性目录、临时 cwd) 直接跳过 — 与 git rev-parse 的上溯查找语义一致, 但把
* 两次进程 spawn 换成几次 stat。对 Windows 还有一层必要收益: 短命子进程引用
* 临时目录会跟 teardown 删目录撞出 EPERM。
*/
async function hasGitMarkerUpward(cwd: string): Promise<boolean> {
let dir = cwd;
for (;;) {
try {
await fs.access(path.join(dir, '.git'));
return true;
} catch {
/* 不在这一层, 继续上溯 */
}
const parent = path.dirname(dir);
if (parent === dir) return false;
dir = parent;
}
}
async function defaultExecGit(args: string[], cwd: string): Promise<string> {
// 用 `git -C <dir>` 而不是 child 的 cwd 选项: Windows 上子进程的 CWD 会锁住
// 该目录, 会话用临时 cwd 的测试/短命场景在 teardown 删目录时 EPERM。
// 相对路径输出 (--git-common-dir) 相对 -C 目录解析, 与 cwd 选项语义一致。
const { stdout } = await execFileAsync('git', ['-C', cwd, ...args], {
timeout: GIT_PROBE_TIMEOUT_MS,
maxBuffer: 1024 * 1024,
windowsHide: true,
});
return stdout;
}
interface CacheEntry {
value: Promise<string>;
expiresAt: number;
}
const scopeKeyCache = new Map<string, CacheEntry>();
/** 测试专用: 清空进程内缓存。生产代码不应调用。 */
export function __clearMemoryScopeKeyCacheForTests(): void {
scopeKeyCache.clear();
}
/**
* 取 scope key 的统一入口 (async)。所有 getStore 调用方 (agent 启动注入 /
* MCP withStore / manager 兜底) 必须经本函数, 不得各自拼 key 或自行探测 git。
*/
export async function resolveMemoryScopeKey(
workingDir: string,
remoteHostId?: string | null,
deps?: ResolveMemoryScopeKeyDeps,
): Promise<string> {
// SSH remote: 复合键规则不变 (单射性质经过 review, 见 storage.ts),
// 远端路径是远端机器上的字符串, 控制端不解析远端 git。
if (remoteHostId) return buildMemoryScopeKey(workingDir, remoteHostId);
if (!workingDir) return workingDir;
// 已经是复合键 (bot: / ssh:) 时不得再当本地路径做 git worktree 归一化。
// Bot scope 由 host 显式注入; SSH 复合键若被二次传入同样原样透传。
if (workingDir.startsWith(BOT_SCOPE_KEY_PREFIX) || workingDir.startsWith(SSH_SCOPE_KEY_PREFIX)) {
return workingDir;
}
const execGit = deps?.execGit;
const now = deps?.now ?? (() => Date.now());
// Windows 路径大小写不敏感, 缓存 key 统一小写 (返回值保留原始大小写)。
const cacheKey = process.platform === 'win32' ? workingDir.toLowerCase() : workingDir;
const hit = scopeKeyCache.get(cacheKey);
if (hit && hit.expiresAt > now()) return hit.value;
const value = (async () => {
// 非仓库目录预检 (默认探测路径): 没有 .git 标记时 git rev-parse 必然失败,
// 直接回落, 省掉一次进程 spawn (也避开 Windows 临时目录的 EPERM 竞争)。
// 注入了 execGit 的调用方显式接管探测, 跳过预检。
if (!execGit && !(await hasGitMarkerUpward(path.normalize(workingDir)).catch(() => true))) {
return workingDir;
}
// 任何失败都回落 cwd 原样 — 归一化是纯增强, 绝不让 git 探测故障阻断 memory。
return canonicalizeLocalWorkdir(workingDir, execGit ?? defaultExecGit).catch(() => workingDir);
})();
scopeKeyCache.set(cacheKey, { value, expiresAt: now() + CACHE_TTL_MS });
return value;
}
/**
* linked worktree cwd → `主仓根 + cwd 相对 worktree 根的子路径`。
* 探测方式与 desktop WorktreeManager 同模式: rev-parse + path.resolve
* 解析相对输出 (兼容不支持 --path-format 的旧 git)。单次 rev-parse 拿
* toplevel / git-dir / git-common-dir / superproject 四个值 (输出顺序与
* 参数一致; 无 superproject 时第四行为空); 确认是 linked worktree 或
* worktree 内 submodule 后再用一次 `worktree list --porcelain` 取主仓根。
* 失败抛错由调用方回落。
*/
async function canonicalizeLocalWorkdir(workingDir: string, execGit: GitProbe): Promise<string> {
const cwd = path.normalize(workingDir);
const out = await execGit(
[
'rev-parse',
'--show-toplevel',
'--git-dir',
'--git-common-dir',
'--show-superproject-working-tree',
],
cwd,
);
const [toplevelRaw, gitDirRaw, commonDirRaw, superRaw] = out.split('\n');
const toplevel = resolveGitDirOutput(toplevelRaw ?? '', cwd);
const gitDir = resolveGitDirOutput(gitDirRaw ?? '', cwd);
const commonDir = resolveGitDirOutput(commonDirRaw ?? '', cwd);
const directSuper = resolveGitDirOutput(superRaw ?? '', cwd);
if (!toplevel || !gitDir || !commonDir) return workingDir;
// 判定链 (Codex #2399 P1, linked-worktree submodule):
// 1. gitdir ≠ common-dir → 真 linked worktree, 归一到主仓根 + 相对路径。
// 2. gitdir == common-dir 且有 superproject → cwd 是 submodule。
// 主仓内 submodule 的 superproject == 主仓根, 原样返回 (与 round-1 契约一致)。
// linked worktree 内 submodule 的 gitdir == common-dir (都是
// `<主仓>/.git/worktrees/<wt>/modules/<sub>`), 不能当普通 clone 回落;
// 把**最外层** superproject (walk 链, 不是直接父) 当 mapping 根再走
// 同一套主仓映射, 得到 `/main/<nested-rel>` 而不是 `.git` 元数据目录。
// 3. gitdir == common-dir 且无 superproject → 普通 clone /
// --separate-git-dir checkout, 原样返回。separate-git-dir 的 common-dir
// basename 恰好也是 `.git`, 不先排除会把主仓根错误推导到 git 存储目录
// (Codex review on #2399)。
const outermostSuper = directSuper
? await walkOutermostSuperproject(directSuper, execGit)
: null;
if (samePath(gitDir, commonDir)) {
if (!outermostSuper) return workingDir;
} else if (path.basename(commonDir) !== '.git') {
// bare repo 的 linked worktree (common-dir 是 `<name>.git`) 等非常规布局
// 无法可靠推断主仓根, 回落原样。submodule 走上面 superproject 分支,
// 不看这一条 (其 gitdir == common-dir)。
return workingDir;
}
const mappingRoot = outermostSuper ?? toplevel;
// 主仓根不能从 common-dir 推导: 主 checkout 本身用 --separate-git-dir 建
// 时 common-dir 是 git 存储目录, dirname 不一定是工作树 (Codex review on
// #2399 第二轮)。统一用 `git worktree list --porcelain` 第一条记录 — git
// 保证主工作树排第一; 布局带 core.worktree 指针时取到真实主 checkout。
//
// 已知限制: `git clone --separate-git-dir` 不写 core.worktree, git 自身
// 也无法从 gitdir 反推真实 checkout (`git worktree list` 直接把 gitdir
// 父目录报为主工作树, 连从真实 checkout 里跑都一样)。这种布局下本函数
// 跟随 git 的 canonical 答案; 主 checkout 会话按 round-1 契约不归一化,
// 即该极端布局下主 checkout 与 worktree 的 memory 不共享 (与 PR 前行为
// 一致, 不回归)。
const mainRoot = await resolveMainWorktreeRoot(mappingRoot, execGit);
if (!mainRoot) return workingDir;
// 防御: 映射根即主仓根时无需归一化 (主仓内 cwd / 主仓内 submodule),
// 原样返回, 保持「本地原样返回」契约。
if (samePath(mappingRoot, mainRoot)) return workingDir;
// linked worktree (含其内 submodule): 子路径映射回主仓根下
// (该路径在主仓可以不存在 — scope key 只是身份字符串, 落盘目录名经
// memoryScopeDirName 派生)。
const rel = path.relative(mappingRoot, cwd);
if (rel === '') return mainRoot;
// cwd 不在映射根下 (symlink/大小写风格不一致等) — 不猜, 回落。
if (rel.startsWith('..') || path.isAbsolute(rel)) return workingDir;
return path.join(mainRoot, rel);
}
/** git rev-parse 输出 → 绝对路径。空输出返 null (调用方回落)。 */
function resolveGitDirOutput(raw: string, cwd: string): string | null {
const trimmed = raw.trim();
if (!trimmed) return null;
return path.normalize(path.resolve(cwd, trimmed));
}
/**
* `git worktree list --porcelain` 第一条 `worktree ` 记录 = 主工作树路径
* (git 保证主工作树排第一)。取不到返 null (调用方回落)。
*/
async function resolveMainWorktreeRoot(cwd: string, execGit: GitProbe): Promise<string | null> {
const out = await execGit(['worktree', 'list', '--porcelain'], cwd);
const line = out.split('\n').find((l) => l.startsWith('worktree '));
if (!line) return null;
return resolveGitDirOutput(line.slice('worktree '.length), cwd);
}
function samePath(a: string, b: string): boolean {
return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
}
/**
* `--show-superproject-working-tree` 只给直接父仓库。二级 submodule 的父是
* 另一层 submodule, 在那一层跑 `git worktree list` 会把
* `<main>/.git/worktrees/<wt>/modules/<parent>` 报成唯一 worktree, 把
* scope 映射进 .git 元数据目录 (Codex #2399 P1)。沿链走到没有 superproject
* 的最外层 (linked worktree 或主仓) 再交给 resolveMainWorktreeRoot。
*/
async function walkOutermostSuperproject(start: string, execGit: GitProbe): Promise<string> {
let current = start;
const seen = new Set<string>();
for (let i = 0; i < 16; i += 1) {
const key = process.platform === 'win32' ? current.toLowerCase() : current;
if (seen.has(key)) return current;
seen.add(key);
// 与 canonicalize 同一条 4 行 rev-parse, 让既有 cwd-agnostic fake probe
// 仍返回 superproject 在第四行; 单字段 --show-superproject-working-tree
// 会被 probeFor 的第一行 toplevel 误当成父仓。
const out = await execGit(
[
'rev-parse',
'--show-toplevel',
'--git-dir',
'--git-common-dir',
'--show-superproject-working-tree',
],
current,
).catch(() => '');
const parent = resolveGitDirOutput(out.split('\n')[3] ?? '', current);
if (!parent || samePath(parent, current)) return current;
current = parent;
}
return current;
}