@worldzb/agent-sync 1.4.0

package/README.md

@@ -0,0 +1,176 @@
+# ZMAI
+
+`zmai` 是一个本机多 Agent 历史会话工作台，同时提供 Claude API 配置管理能力。
+
+支持发现和管理本机的 **Claude Code**、**Codex**、**OpenCode**：浏览历史会话、按项目和 Agent 分类、续接会话、跨 Agent 导入历史、迁移附件，以及查看 plugins、Skills、MCP。
+
+## 安装
+
+```bash
+npm install -g @worldzb/zmai
+```
+
+安装后使用 `zmai` 命令。
+
+> 需要 Node.js 18 或更高版本。
+
+## 核心功能
+
+| 功能 | 说明 |
+| --- | --- |
+| Agent 发现 | 扫描 Claude Code、Codex、OpenCode 的安装状态、版本与本地数据目录 |
+| 历史会话 | 统一读取三个 Agent 的本地会话，按时间排序、分类和分页浏览 |
+| 项目筛选 | 区分当前项目会话与全部会话 |
+| Agent 筛选 | 按全部、Claude、Codex、OpenCode 分类显示 |
+| 会话续接 | 用原 Agent 继续历史会话 |
+| 跨 Agent 迁移 | 将历史转换为可移植上下文，并在目标 Agent 中创建新会话 |
+| 附件迁移 | 复制可读取的图片/文件，生成带校验值的迁移清单 |
+| 集成管理 | 查看 plugins、Skills、MCP，并调用 Agent 原生命令安装或移除 |
+| API 配置 | 管理 Claude API Key、Base URL、默认配置和临时环境变量 |
+
+## 扫描 Agent
+
+```bash
+zmai agents
+```
+
+输出每个 Agent 的：
+
+- 是否已安装及可执行命令路径
+- 版本号
+- 本地历史目录
+- 支持的会话、集成与配置能力
+
+## 历史会话
+
+```bash
+zmai history
+```
+
+交互界面由 React + Ink 渲染。初次加载会动态显示 Claude Code、Codex、OpenCode 的扫描进度。
+
+### 范围与分类
+
+- `Tab`、左方向键：当前项目 / 全部会话之间切换
+- 右方向键：切换至全部会话
+- `1`：全部 Agent
+- `2`：Claude Code 会话
+- `3`：Codex 会话
+- `4`：OpenCode 会话
+
+### 会话操作
+
+- 上下方向键：选择会话；在列表首尾可自动跨页
+- `Ctrl+U` 或 `-`：上一页
+- `Ctrl+D` 或 `=`：下一页
+- `Enter`：打开会话操作
+- `r`：重新扫描本地历史
+- `q`：退出
+
+非交互环境可使用文本输出：
+
+```bash
+zmai history --plain
+zmai history --plain --agent claude --page-size 30
+```
+
+## 续接与跨 Agent 迁移
+
+在历史会话中按 `Enter` 后：
+
+- **选择原 Agent**：在当前终端直接续接原生会话。
+- **选择其他 Agent**：创建迁移目录，转换旧会话内容，然后在当前终端启动目标 Agent。
+
+迁移时会：
+
+1. 将用户、助手与工具消息转换为可移植 Markdown 上下文；
+2. 复制可读取且不超过 20MB 的图片和文件；
+3. 为附件生成 SHA-256 校验值；
+4. 生成 `conversation.md` 和 `manifest.json`；
+5. 将完整历史复制到剪贴板，并将上下文交给目标 Agent 新会话。
+
+迁移文件保存于：
+
+```text
+~/.zmai/migrations/<migration-id>/
+```
+
+来源会话不会被修改或删除。
+
+也可通过命令迁移：
+
+```bash
+zmai migrate codex:<session-id> --to claude
+```
+
+## Plugins、Skills 与 MCP
+
+```bash
+# 查看全部 Agent 的资源
+zmai integrations
+
+# 仅查看某个 Agent，并包含项目级资源
+zmai integrations --agent claude --project /path/to/project
+
+# 安装插件
+zmai integrations --agent claude --install-plugin plugin@marketplace
+
+# 移除资源
+zmai integrations --remove claude:plugin:plugin-name
+```
+
+安装或移除前会要求明确确认。插件和 MCP 优先使用对应 Agent 的原生命令；不会自动执行未知远程脚本。
+
+## Claude API 配置
+
+```bash
+# 交互式添加配置
+zmai add -i
+
+# 命令行添加配置
+zmai add -n "官方 API" -k "sk-ant-api03-xxx" -u "https://api.anthropic.com"
+
+# 查看配置
+zmai list
+
+# 当前终端临时使用
+ eval $(zmai switch -n "官方 API" --temp --eval)
+
+# 设为 Claude Code 默认配置
+zmai switch -n "官方 API"
+
+# 查看当前 Claude 配置
+zmai current
+```
+
+默认配置会更新：
+
+```text
+~/.claude/settings.json
+~/.claude-switch-config/.claude-env
+```
+
+## 数据目录
+
+| 数据 | 路径 |
+| --- | --- |
+| Claude API 配置 | `~/.claude-switch-config/claude-configs.json` |
+| 临时环境变量 | `~/.claude-switch-config/.claude-env` |
+| Claude Code 设置 | `~/.claude/settings.json` |
+| 会话迁移上下文与附件 | `~/.zmai/migrations/` |
+| 旧版托管会话记录 | `~/.zmai/sessions.json` |
+
+## 开发
+
+```bash
+npm install
+npm run check
+npm test
+npm run build
+```
+
+源码在 `src/`，构建产物在 `dist/`。
+
+## 许可证
+
+MIT

package/dist/agents/abstract-file-adapter.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { findExecutable, getVersion, runCommand } from './process-runner.js';
+export class AbstractFileAdapter {
+    discover() {
+        const executable = findExecutable(this.command);
+        return {
+            id: this.id,
+            name: this.name,
+            installed: executable !== undefined,
+            ...(executable ? { executable, version: getVersion(executable) } : {}),
+            historyRoot: this.historyRoot,
+            capabilities: ['历史记录', '续接会话', '删除会话', '插件', 'Skills', 'MCP'],
+        };
+    }
+    listIntegrations(project) {
+        const roots = this.integrationRoots(project);
+        return roots.flatMap(({ directory, scope }) => scanIntegrationRoot(this.id, directory, scope));
+    }
+    execute(args, cwd) {
+        const executable = findExecutable(this.command);
+        if (!executable)
+            throw new Error(`${this.name} 未安装或不在 PATH 中。`);
+        return runCommand(executable, args, cwd);
+    }
+    removeLocalPath(location) {
+        if (!fs.existsSync(location))
+            throw new Error(`资源不存在：${location}`);
+        fs.rmSync(location, { recursive: true, force: false });
+    }
+}
+function scanIntegrationRoot(agent, directory, scope) {
+    if (!fs.existsSync(directory))
+        return [];
+    const candidates = [
+        { name: 'skills', kind: 'skill' },
+    ];
+    return candidates.flatMap(({ name, kind }) => {
+        const root = path.join(directory, name);
+        if (!fs.existsSync(root) || !fs.statSync(root).isDirectory())
+            return [];
+        return fs.readdirSync(root, { withFileTypes: true })
+            .filter((entry) => !entry.name.startsWith('.') && (entry.isDirectory() || entry.isFile()))
+            .map((entry) => ({
+            agent,
+            kind,
+            name: entry.name,
+            scope,
+            location: path.join(root, entry.name),
+            removable: true,
+        }));
+    });
+}

package/dist/agents/claude-adapter.js

@@ -0,0 +1,154 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { AbstractFileAdapter } from './abstract-file-adapter.js';
+import { asString, isRecord, readJsonLines } from './jsonl.js';
+import { normalizeMessage } from '../migration/transcript-normalizer.js';
+export class ClaudeAdapter extends AbstractFileAdapter {
+    homeDirectory;
+    id = 'claude';
+    name = 'Claude Code';
+    command = 'claude';
+    historyRoot;
+    constructor(homeDirectory) {
+        super();
+        this.homeDirectory = homeDirectory;
+        this.historyRoot = path.join(homeDirectory, '.claude', 'projects');
+    }
+    listSessions() {
+        return findFiles(this.historyRoot, (file) => file.endsWith('.jsonl')).flatMap((sourcePath) => {
+            const rows = readJsonLines(sourcePath).filter(isRecord);
+            const first = rows[0];
+            if (!first)
+                return [];
+            const id = asString(first.sessionId) || path.basename(sourcePath, '.jsonl');
+            const firstMessage = rows.map(extractMessage).find((message) => message?.role === 'user');
+            const cwd = rows.map((row) => asString(row.cwd)).find((value) => Boolean(value));
+            const updatedAt = asString(rows.at(-1)?.timestamp) || fs.statSync(sourcePath).mtime.toISOString();
+            return [{
+                    agent: this.id,
+                    id,
+                    title: sanitizeTitle(firstText(firstMessage)) || '未命名 Claude 会话',
+                    cwd: cwd || decodeProjectDirectory(path.dirname(sourcePath)),
+                    updatedAt,
+                    sourcePath,
+                }];
+        });
+    }
+    readTranscript(session) {
+        const messages = readJsonLines(session.sourcePath).flatMap((row) => {
+            const message = extractMessage(row);
+            return message ? [message] : [];
+        });
+        return { source: session, messages, warnings: [] };
+    }
+    createResumeLaunch(session) {
+        return { command: [this.command, '--resume', session.id], cwd: session.cwd || process.cwd() };
+    }
+    createNewLaunch(input) {
+        const assetArgument = input.assetDirectory ? ['--add-dir', input.assetDirectory] : [];
+        const promptArgument = input.prompt ? [input.prompt] : [];
+        return { command: [this.command, ...assetArgument, ...promptArgument], cwd: input.cwd || process.cwd() };
+    }
+    deleteSession(session) {
+        this.removeLocalPath(session.sourcePath);
+    }
+    integrationRoots(project) {
+        return [
+            { directory: path.join(this.homeDirectory, '.claude'), scope: 'user' },
+            ...(project ? [{ directory: project, scope: 'project' }] : []),
+        ];
+    }
+    listIntegrations(project) {
+        return [...super.listIntegrations(project), ...this.listInstalledPlugins(), ...this.listMcp(project)];
+    }
+    installPlugin(plugin) {
+        this.execute(['plugin', 'install', plugin]);
+    }
+    removeIntegration(item) {
+        if (item.kind === 'plugin') {
+            this.execute(['plugin', 'uninstall', item.name]);
+            return;
+        }
+        if (item.kind === 'mcp') {
+            this.execute(['mcp', 'remove', item.name]);
+            return;
+        }
+        this.removeLocalPath(item.location);
+    }
+    listInstalledPlugins() {
+        const file = path.join(this.homeDirectory, '.claude', 'plugins', 'installed_plugins.json');
+        if (!fs.existsSync(file))
+            return [];
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (!isRecord(parsed) || !isRecord(parsed.plugins))
+                return [];
+            return Object.keys(parsed.plugins).map((name) => ({
+                agent: this.id,
+                kind: 'plugin',
+                name,
+                scope: 'user',
+                location: file,
+                removable: true,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    listMcp(project) {
+        const configFiles = [
+            path.join(this.homeDirectory, '.claude.json'),
+            ...(project ? [path.join(project, '.mcp.json')] : []),
+        ];
+        return configFiles.flatMap((file) => {
+            if (!fs.existsSync(file))
+                return [];
+            try {
+                const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (!isRecord(parsed) || !isRecord(parsed.mcpServers))
+                    return [];
+                const scope = file.endsWith('.mcp.json') ? 'project' : 'user';
+                return Object.keys(parsed.mcpServers).map((name) => ({
+                    agent: this.id,
+                    kind: 'mcp',
+                    name,
+                    scope,
+                    location: file,
+                    removable: true,
+                }));
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+}
+function extractMessage(row) {
+    if (!isRecord(row))
+        return undefined;
+    return normalizeMessage(row.message);
+}
+function firstText(message) {
+    const text = message?.content.find((content) => content.type === 'text');
+    return text?.type === 'text' ? text.text.replaceAll(/\s+/g, ' ').slice(0, 100) : undefined;
+}
+function sanitizeTitle(value) {
+    if (!value || /<(local-command-caveat|system-reminder|command-message)>|^\s*[\[{]/i.test(value)) {
+        return undefined;
+    }
+    return value;
+}
+function decodeProjectDirectory(directory) {
+    return path.basename(directory).replaceAll('-', path.sep).replace(/^\/+/, path.sep);
+}
+function findFiles(directory, match) {
+    if (!fs.existsSync(directory))
+        return [];
+    return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        const entryPath = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            return findFiles(entryPath, match);
+        return entry.isFile() && match(entryPath) ? [entryPath] : [];
+    });
+}

package/dist/agents/codex-adapter.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { AbstractFileAdapter } from './abstract-file-adapter.js';
+import { asString, isRecord, readJsonLines } from './jsonl.js';
+import { normalizeMessage } from '../migration/transcript-normalizer.js';
+export class CodexAdapter extends AbstractFileAdapter {
+    homeDirectory;
+    id = 'codex';
+    name = 'Codex';
+    command = 'codex';
+    historyRoot;
+    constructor(homeDirectory) {
+        super();
+        this.homeDirectory = homeDirectory;
+        this.historyRoot = path.join(homeDirectory, '.codex', 'sessions');
+    }
+    listSessions() {
+        return findFiles(this.historyRoot).flatMap((sourcePath) => {
+            const rows = readJsonLines(sourcePath).filter(isRecord);
+            const metadata = rows.find((row) => row.type === 'session_meta' || row.type === 'session_metadata');
+            const payload = isRecord(metadata?.payload) ? metadata.payload : metadata || {};
+            const id = asString(payload.id) || sessionIdFromFile(sourcePath);
+            const messages = rows.map(extractMessage).filter((message) => message !== undefined);
+            return [{
+                    agent: this.id,
+                    id,
+                    title: sanitizeTitle(firstText(messages)) || '未命名 Codex 会话',
+                    cwd: asString(payload.cwd) || process.cwd(),
+                    updatedAt: asString(rows.at(-1)?.timestamp) || fs.statSync(sourcePath).mtime.toISOString(),
+                    sourcePath,
+                }];
+        });
+    }
+    readTranscript(session) {
+        const messages = readJsonLines(session.sourcePath)
+            .map(extractMessage)
+            .filter((message) => message !== undefined);
+        return { source: session, messages, warnings: [] };
+    }
+    createResumeLaunch(session) {
+        return { command: [this.command, 'resume', session.id], cwd: session.cwd || process.cwd() };
+    }
+    createNewLaunch(input) {
+        const imageArgs = input.assetDirectory ? imageArguments(input.assetDirectory) : [];
+        const promptArgument = input.prompt ? [input.prompt] : [];
+        return { command: [this.command, ...imageArgs, ...promptArgument], cwd: input.cwd || process.cwd() };
+    }
+    deleteSession(session) {
+        this.execute(['delete', '--force', session.id], session.cwd);
+    }
+    integrationRoots(project) {
+        return [
+            { directory: path.join(this.homeDirectory, '.codex'), scope: 'user' },
+            ...(project ? [{ directory: path.join(project, '.codex'), scope: 'project' }] : []),
+        ];
+    }
+    listIntegrations(project) {
+        return [...super.listIntegrations(project), ...this.listPlugins(), ...this.listMcp()];
+    }
+    installPlugin(plugin) {
+        this.execute(['plugin', 'add', plugin]);
+    }
+    removeIntegration(item) {
+        if (item.kind === 'plugin') {
+            this.execute(['plugin', 'remove', item.name]);
+            return;
+        }
+        if (item.kind === 'mcp') {
+            this.execute(['mcp', 'remove', item.name]);
+            return;
+        }
+        this.removeLocalPath(item.location);
+    }
+    listPlugins() {
+        try {
+            return toCommandItems(this.execute(['plugin', 'list']), this.id, 'plugin');
+        }
+        catch {
+            return [];
+        }
+    }
+    listMcp() {
+        try {
+            return toCommandItems(this.execute(['mcp', 'list']), this.id, 'mcp');
+        }
+        catch {
+            return [];
+        }
+    }
+}
+function extractMessage(row) {
+    if (!isRecord(row))
+        return undefined;
+    const payload = isRecord(row.payload) ? row.payload : row;
+    const direct = normalizeMessage(payload.message || payload);
+    if (direct)
+        return direct;
+    if (payload.type === 'response_item' && isRecord(payload.payload))
+        return normalizeMessage(payload.payload);
+    return undefined;
+}
+function firstText(messages) {
+    const message = messages.find((item) => item.role === 'user');
+    const text = message?.content.find((content) => content.type === 'text');
+    return text?.type === 'text' ? text.text.replaceAll(/\s+/g, ' ').slice(0, 100) : undefined;
+}
+function sanitizeTitle(value) {
+    if (!value || /<environment_context>|# AGENTS\.md instructions|^\s*[\[{]/i.test(value)) {
+        return undefined;
+    }
+    return value;
+}
+function sessionIdFromFile(sourcePath) {
+    const match = path.basename(sourcePath).match(/([0-9a-f]{8}-[0-9a-f-]{27,})\.jsonl$/i);
+    return match?.[1] || path.basename(sourcePath, '.jsonl');
+}
+function imageArguments(directory) {
+    if (!fs.existsSync(directory))
+        return [];
+    return fs.readdirSync(directory)
+        .filter((file) => /\.(png|jpe?g|gif|webp)$/i.test(file))
+        .flatMap((file) => ['--image', path.join(directory, file)]);
+}
+function toCommandItems(output, agent, kind) {
+    return output.split('\n')
+        .map((line) => line.trim().split(/\s+/)[0])
+        .filter((name) => Boolean(name) && !/^(name|no|installed)/i.test(name))
+        .map((name) => ({ agent, kind, name, scope: 'user', location: `codex ${kind}`, removable: true }));
+}
+function findFiles(directory) {
+    if (!fs.existsSync(directory))
+        return [];
+    return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        const entryPath = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            return findFiles(entryPath);
+        return entry.isFile() && entry.name.endsWith('.jsonl') ? [entryPath] : [];
+    });
+}

package/dist/agents/jsonl.js

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+export function readJsonLines(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf8')
+            .split('\n')
+            .flatMap((line) => {
+            if (!line.trim())
+                return [];
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}