@lwmxiaobei/xbcode 1.0.0

package/dist/session-store.js

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+const XB_CONFIG_DIR = path.join(os.homedir(), ".xbcode");
+/**
+ * 返回 session transcript 的根目录。
+ *
+ * 为什么支持环境变量覆写：
+ * - 生产环境默认仍然应该落在 `~/.xbcode/sessions`，方便和 settings 放在一起。
+ * - 测试和受限沙箱里，home 目录不一定可写，硬编码会让本地持久化能力无法验证。
+ * - 用一个集中 helper 做覆写点，可以避免把“测试专用路径”散落到业务逻辑里。
+ */
+function getSessionRootDir() {
+    const override = process.env.XBCODE_SESSION_DIR?.trim();
+    if (override) {
+        return override;
+    }
+    return path.join(XB_CONFIG_DIR, "sessions");
+}
+/**
+ * 为 CLI 会话生成一个可读且稳定的本地 ID。
+ *
+ * 为什么不用纯随机 UUID：
+ * - 会话 ID 会直接展示给用户做 `/resume <id>`，太长会明显影响可输入性。
+ * - 我们仍然需要足够低的冲突概率，因此保留时间戳前缀，再拼接短随机串。
+ * - 这个 ID 只用于本地文件命名和恢复，不承担安全边界，所以短 ID 足够。
+ */
+export function createSessionId(now = new Date()) {
+    const timestamp = now.toISOString().replaceAll(/[-:.TZ]/g, "").slice(0, 14);
+    const suffix = crypto.randomBytes(3).toString("hex");
+    return `${timestamp}-${suffix}`;
+}
+/**
+ * 计算当前 workspace 对应的 session 目录。
+ *
+ * 为什么要按 workspace 分目录：
+ * - Claude Code 的 transcript 恢复是“当前项目视角”的；用户恢复时只应该看到
+ *   当前工程下的历史会话，而不是所有项目的混合列表。
+ * - 目录名如果直接使用绝对路径会包含斜杠和空格，不适合作为文件系统路径。
+ * - 这里保留 basename 方便人工识别，再拼接 hash 保证不同同名目录不冲突。
+ */
+function getWorkspaceSessionDir(workspace) {
+    const base = path.basename(workspace) || "workspace";
+    const safeBase = base.replaceAll(/[^A-Za-z0-9._-]/g, "_");
+    const hash = crypto.createHash("sha1").update(workspace).digest("hex").slice(0, 12);
+    return path.join(getSessionRootDir(), `${safeBase}-${hash}`);
+}
+/**
+ * 返回某个 session 对应的 JSONL transcript 路径。
+ *
+ * 为什么统一通过 helper：
+ * - 创建、列出、恢复都会用到同一套路径规则，集中在这里可以避免散落的拼接逻辑。
+ * - 未来如果要把单文件拆成目录结构，只需要改这一处，不必全局替换。
+ */
+function getSessionPath(workspace, sessionId) {
+    return path.join(getWorkspaceSessionDir(workspace), `${sessionId}.jsonl`);
+}
+/**
+ * 以追加写方式持久化当前会话快照。
+ *
+ * 为什么选择 append-only JSONL 而不是反复覆盖一个 JSON：
+ * - 这和 Claude Code 的 transcript 思路一致，写入路径更简单，也更抗意外中断。
+ * - 追加一行比重写整个文件更稳妥，尤其是在消息越来越多之后。
+ * - 当前实现只在 checkpoint 级别恢复，因此读取时只需要最后一个 checkpoint，
+ *   但保留历史增量可以给后续调试和回溯留下空间。
+ */
+export function appendSessionCheckpoint(workspace, snapshot) {
+    const filePath = getSessionPath(workspace, snapshot.state.sessionId);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    if (!fs.existsSync(filePath)) {
+        const meta = {
+            kind: "meta",
+            sessionId: snapshot.state.sessionId,
+            workspace,
+            createdAt: new Date(snapshot.state.launchedAt).toISOString(),
+        };
+        fs.appendFileSync(filePath, `${JSON.stringify(meta)}\n`, "utf8");
+    }
+    const entry = {
+        kind: "checkpoint",
+        sessionId: snapshot.state.sessionId,
+        savedAt: snapshot.savedAt,
+        snapshot,
+    };
+    fs.appendFileSync(filePath, `${JSON.stringify(entry)}\n`, "utf8");
+}
+/**
+ * 读取当前 workspace 下最近的历史会话摘要。
+ *
+ * 为什么这里接受“读全文件再找最后 checkpoint”的简化实现：
+ * - `code-agent` 目前还没有 Claude Code 那种超大 transcript 和分页恢复需求。
+ * - 先把恢复闭环做通，比过早引入 head/tail 扫描、锁文件、lite metadata 更重要。
+ * - 当 session 文件明显变大时，再把这里替换成轻量扫描即可，不影响上层接口。
+ */
+export function listRecentSessions(workspace, limit = 10) {
+    const dir = getWorkspaceSessionDir(workspace);
+    if (!fs.existsSync(dir)) {
+        return [];
+    }
+    const items = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith(".jsonl")) {
+            continue;
+        }
+        const loaded = loadSessionFromFile(path.join(dir, entry.name));
+        if (!loaded) {
+            continue;
+        }
+        const title = extractSessionTitle(loaded.snapshot.messages);
+        items.push({
+            sessionId: loaded.snapshot.state.sessionId,
+            createdAt: loaded.createdAt,
+            savedAt: loaded.snapshot.savedAt,
+            title,
+            turnCount: loaded.snapshot.state.turnCount,
+            model: loaded.snapshot.model,
+            providerName: loaded.snapshot.providerName,
+        });
+    }
+    return items
+        .sort((left, right) => right.savedAt.localeCompare(left.savedAt))
+        .slice(0, Math.max(0, limit));
+}
+/**
+ * 加载一个指定的历史会话，并返回最后一次 checkpoint。
+ *
+ * 为什么只恢复最后 checkpoint：
+ * - 当前恢复目标是“把模型上下文和界面消息恢复到可继续工作的最近状态”。
+ * - 既然 checkpoint 已经包含完整 `AgentState` 和 UI 消息，就没有必要重放整个日志。
+ * - 这也让恢复过程保持确定性，避免中途存在半写入流式消息时的复杂合并。
+ */
+export function loadSession(workspace, sessionId) {
+    const filePath = getSessionPath(workspace, sessionId);
+    const loaded = loadSessionFromFile(filePath);
+    return loaded?.snapshot ?? null;
+}
+function loadSessionFromFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf8");
+        const lines = content.split(/\r?\n/).filter((line) => line.trim().length > 0);
+        let createdAt = "";
+        let lastSnapshot = null;
+        for (const line of lines) {
+            const parsed = JSON.parse(line);
+            if (parsed.kind === "meta") {
+                createdAt = parsed.createdAt;
+                continue;
+            }
+            if (parsed.kind === "checkpoint") {
+                lastSnapshot = parsed.snapshot;
+            }
+        }
+        if (!lastSnapshot) {
+            return null;
+        }
+        return {
+            createdAt: createdAt || new Date(lastSnapshot.state.launchedAt).toISOString(),
+            snapshot: lastSnapshot,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 从已持久化消息里提取会话标题。
+ *
+ * 为什么优先看第一条用户消息：
+ * - Claude Code 在 session 列表里也依赖“第一条有意义的用户输入”来帮助识别会话。
+ * - 这比模型自动命名更稳定，也不需要额外一次生成或保存专门标题字段。
+ * - 工具、系统提示、thinking 内容都不是用户真正想恢复的主题，所以应跳过。
+ */
+function extractSessionTitle(messages) {
+    for (const message of messages) {
+        if (message.kind !== "user") {
+            continue;
+        }
+        const compact = message.text.replaceAll(/\s+/g, " ").trim();
+        if (!compact) {
+            continue;
+        }
+        return compact.length > 80 ? `${compact.slice(0, 80).trim()}...` : compact;
+    }
+    return "(untitled session)";
+}

package/dist/skills/frontmatter.js

@@ -0,0 +1,85 @@
+function stripWrappingQuotes(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function parseListValue(value) {
+    return stripWrappingQuotes(value)
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+export function parseSkillFile(text) {
+    const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match) {
+        return { meta: {}, body: text.trim() };
+    }
+    const meta = {};
+    const lines = (match[1] ?? "").split(/\r?\n/);
+    let currentListKey = null;
+    for (const rawLine of lines) {
+        const line = rawLine.trimEnd();
+        if (!line.trim() || line.trimStart().startsWith("#")) {
+            continue;
+        }
+        const listMatch = line.match(/^\s*-\s+(.+)$/);
+        if (listMatch && currentListKey) {
+            const existing = meta[currentListKey];
+            const nextValue = stripWrappingQuotes(listMatch[1] ?? "");
+            if (Array.isArray(existing)) {
+                existing.push(nextValue);
+            }
+            else if (typeof existing === "string" && existing.length > 0) {
+                meta[currentListKey] = [existing, nextValue];
+            }
+            else {
+                meta[currentListKey] = [nextValue];
+            }
+            continue;
+        }
+        const colonIndex = line.indexOf(":");
+        if (colonIndex === -1) {
+            currentListKey = null;
+            continue;
+        }
+        const key = line.slice(0, colonIndex).trim();
+        const rawValue = line.slice(colonIndex + 1).trim();
+        if (!rawValue) {
+            meta[key] = [];
+            currentListKey = key;
+            continue;
+        }
+        if (key === "allowed-tools") {
+            meta[key] = parseListValue(rawValue);
+        }
+        else {
+            meta[key] = stripWrappingQuotes(rawValue);
+        }
+        currentListKey = null;
+    }
+    return {
+        meta: meta,
+        body: (match[2] ?? "").trim(),
+    };
+}
+export function buildSkillDescriptor(meta, body, fallbackName, filePath, baseDir) {
+    const allowedTools = Array.isArray(meta["allowed-tools"])
+        ? meta["allowed-tools"]
+        : typeof meta["allowed-tools"] === "string"
+            ? parseListValue(meta["allowed-tools"])
+            : [];
+    return {
+        name: meta.name || fallbackName,
+        description: meta.description || "No description",
+        tags: meta.tags,
+        whenToUse: meta.when_to_use,
+        allowedTools,
+        argumentHint: meta["argument-hint"],
+        body,
+        filePath,
+        baseDir,
+    };
+}

package/dist/skills/index.js

@@ -0,0 +1,2 @@
+export { SkillLoader } from "./loader.js";
+export { renderPromptCommand, renderSkillContent } from "./render.js";

package/dist/skills/loader.js

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+import path from "node:path";
+import { debugLog } from "../utils.js";
+import { buildSkillDescriptor, parseSkillFile } from "./frontmatter.js";
+import { renderPromptCommand } from "./render.js";
+export class SkillLoader {
+    commands = new Map();
+    constructor(skillsDirs) {
+        for (const dir of skillsDirs) {
+            this.loadAll(dir);
+        }
+    }
+    loadAll(skillsDir) {
+        if (!fs.existsSync(skillsDir))
+            return;
+        const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory())
+                continue;
+            const baseDir = path.join(skillsDir, entry.name);
+            const filePath = path.join(baseDir, "SKILL.md");
+            if (!fs.existsSync(filePath))
+                continue;
+            const text = fs.readFileSync(filePath, "utf8");
+            const { meta, body } = parseSkillFile(text);
+            const descriptor = buildSkillDescriptor(meta, body, entry.name, filePath, baseDir);
+            this.commands.set(descriptor.name, this.toPromptCommand(descriptor));
+        }
+    }
+    toPromptCommand(skill) {
+        return {
+            name: skill.name,
+            description: skill.description,
+            tags: skill.tags,
+            whenToUse: skill.whenToUse,
+            allowedTools: [...skill.allowedTools],
+            argumentHint: skill.argumentHint,
+            content: skill.body,
+            filePath: skill.filePath,
+            baseDir: skill.baseDir,
+            source: "skill",
+        };
+    }
+    getPromptCommands() {
+        return [...this.commands.values()];
+    }
+    getDescriptions() {
+        const commands = this.getPromptCommands();
+        debugLog("promptCommands=%s", commands);
+        if (commands.length === 0)
+            return "(no skills available)";
+        return commands
+            .map((command) => {
+            let line = ` - ${command.name}: ${command.description}`;
+            if (command.tags)
+                line += ` [${command.tags}]`;
+            return line;
+        })
+            .join("\n");
+    }
+    getSkill(name) {
+        const command = this.commands.get(name);
+        if (!command) {
+            return undefined;
+        }
+        return {
+            name: command.name,
+            description: command.description,
+            tags: command.tags,
+            whenToUse: command.whenToUse,
+            allowedTools: [...command.allowedTools],
+            argumentHint: command.argumentHint,
+            body: command.content,
+            filePath: command.filePath,
+            baseDir: command.baseDir,
+        };
+    }
+    getCommand(name) {
+        return this.commands.get(name);
+    }
+    renderSkill(name, args) {
+        const command = this.commands.get(name);
+        if (!command) {
+            return `Error: Unknown skill '${name}'. Available: ${[...this.commands.keys()].join(", ")}`;
+        }
+        return renderPromptCommand(command, args);
+    }
+}

package/dist/skills/render.js

@@ -0,0 +1,35 @@
+export function renderPromptCommand(command, args) {
+    const parts = [`<skill name="${command.name}">`];
+    if (command.baseDir) {
+        parts.push(`Base directory for this skill: ${command.baseDir}`);
+    }
+    if (command.whenToUse) {
+        parts.push(`When to use: ${command.whenToUse}`);
+    }
+    if (command.allowedTools.length > 0) {
+        parts.push(`Allowed tools: ${command.allowedTools.join(", ")}`);
+    }
+    if (command.argumentHint) {
+        parts.push(`Argument hint: ${command.argumentHint}`);
+    }
+    if (args && args.trim()) {
+        parts.push(`User args:\n${args.trim()}`);
+    }
+    parts.push(command.content);
+    parts.push("</skill>");
+    return parts.join("\n\n");
+}
+export function renderSkillContent(skill, args) {
+    return renderPromptCommand({
+        name: skill.name,
+        description: skill.description,
+        tags: skill.tags,
+        whenToUse: skill.whenToUse,
+        allowedTools: skill.allowedTools,
+        argumentHint: skill.argumentHint,
+        content: skill.body,
+        filePath: skill.filePath,
+        baseDir: skill.baseDir,
+        source: "skill",
+    }, args);
+}

package/dist/skills/types.js

@@ -0,0 +1 @@
+export {};

package/dist/subagents.js

@@ -0,0 +1,64 @@
+// 两个内置子代理：
+export const SUBAGENT_DEFINITIONS = [
+    {
+        name: "general-purpose",
+        whenToUse: "Default worker for implementation, editing, and focused subtasks inside the current workspace.",
+        systemPrompt: "You are a general-purpose sub-agent handling a specific task. Complete it thoroughly, use tools directly, and end with a concise summary of what you changed or found.",
+        allowedTools: [
+            "bash",
+            "read_file",
+            "write_file",
+            "edit_file",
+            "glob",
+            "grep",
+            "task_create",
+            "task_update",
+            "task_list",
+            "task_get",
+            "list_mcp_resources",
+            "read_mcp_resource",
+            "mcp_call",
+            "load_skill",
+        ],
+        maxRounds: 30,
+        readOnlyShell: false,
+    },
+    {
+        name: "explore",
+        whenToUse: "Read-only codebase exploration, searching, tracing behavior, and answering implementation questions without changing files.",
+        systemPrompt: `You are a read-only exploration sub-agent.
+Your only job is to inspect the workspace, search code, read files, and report findings clearly.
+You must not modify files.
+You must not run shell commands that change files, install dependencies, create directories, or alter git state.
+Prefer glob for file discovery, grep for content search, and read_file for targeted inspection. Use bash for read-only commands such as ls, find, cat, git status, and git diff.
+Return findings as a concise factual summary.`,
+        allowedTools: [
+            "bash",
+            "read_file",
+            "glob",
+            "grep",
+            "task_list",
+            "task_get",
+            "list_mcp_resources",
+            "read_mcp_resource",
+            "mcp_call",
+            "load_skill",
+        ],
+        maxRounds: 20,
+        readOnlyShell: true,
+    },
+];
+// 这里提供统一入口，而不是让调用方自己遍历数组，
+// 这样后续如果 agent 定义改成从文件或配置加载，调用方不需要改。
+export function getSubagentDefinition(name) {
+    if (!name) {
+        return SUBAGENT_DEFINITIONS[0];
+    }
+    return SUBAGENT_DEFINITIONS.find((agent) => agent.name === name) ?? SUBAGENT_DEFINITIONS[0];
+}
+// Task 工具描述里直接暴露可选 agent，有助于主 agent 在不额外读文档的情况下学会委派。
+export function describeSubagentsForHumans() {
+    return SUBAGENT_DEFINITIONS
+        .map((agent) => `- ${agent.name}: ${agent.whenToUse}`)
+        .join("\n");
+}

package/dist/supervisor.js

@@ -0,0 +1,58 @@
+import { taskManager, teammateManager } from "./tools.js";
+function updateTeammateFromEvent(event) {
+    if (!event.from || event.from === "lead") {
+        return;
+    }
+    const task = typeof event.taskId === "number" ? taskManager.getTask(event.taskId) : null;
+    const threadId = event.threadId ?? task?.threadId;
+    if (event.eventType === "task_started") {
+        teammateManager.setCurrentWork(event.from, event.taskId, threadId, event.content);
+        teammateManager.markWorking(event.from);
+        return;
+    }
+    if (event.eventType === "task_blocked") {
+        teammateManager.setCurrentWork(event.from, event.taskId, threadId, event.content);
+        teammateManager.markBlocked(event.from, event.content);
+        return;
+    }
+    if (event.eventType === "task_completed" || event.eventType === "task_failed") {
+        teammateManager.setCurrentWork(event.from, event.taskId, threadId, event.content);
+        teammateManager.markIdle(event.from);
+    }
+}
+function applyTaskEvent(event) {
+    if (typeof event.taskId !== "number") {
+        return null;
+    }
+    const task = taskManager.getTask(event.taskId);
+    if (!task) {
+        return null;
+    }
+    updateTeammateFromEvent(event);
+    switch (event.eventType) {
+        case "task_started":
+            taskManager.update(task.id, "in_progress");
+            return `task_started #${task.id}`;
+        case "task_blocked":
+            taskManager.update(task.id, "blocked", undefined, undefined, undefined, undefined, event.content);
+            return `task_blocked #${task.id}`;
+        case "task_completed":
+            taskManager.update(task.id, "completed", undefined, undefined, undefined, event.content);
+            return `task_completed #${task.id}`;
+        case "task_failed":
+            taskManager.update(task.id, "failed", undefined, undefined, undefined, event.content);
+            return `task_failed #${task.id}`;
+        default:
+            return null;
+    }
+}
+export function processLeadInboxEvents(events) {
+    const applied = [];
+    for (const event of events) {
+        const result = applyTaskEvent(event);
+        if (result) {
+            applied.push(result);
+        }
+    }
+    return { applied };
+}