@kobinflow/canvas-agent 0.6.0

package/dist/skills/store.d.ts

@@ -0,0 +1,54 @@
+export type ManagedSkillInterface = {
+    displayName?: string;
+    shortDescription?: string;
+    defaultPrompt?: string;
+};
+export type ManagedSkillDetail = {
+    name: string;
+    description: string;
+    instructions: string;
+    interface?: ManagedSkillInterface;
+    path: string;
+    revision: string;
+    managed: true;
+};
+export type CreateManagedSkillInput = {
+    name: string;
+    description: string;
+    instructions: string;
+    interface?: ManagedSkillInterface | null;
+};
+export type UpdateManagedSkillInput = {
+    description: string;
+    instructions: string;
+    interface?: ManagedSkillInterface | null;
+    expectedRevision: string;
+};
+export declare class SkillStoreError extends Error {
+    readonly statusCode: 400 | 404 | 409 | 500;
+    name: string;
+    constructor(message: string, statusCode: 400 | 404 | 409 | 500);
+}
+/** 只管理站点工作空间下 `.agents/skills` 中的画布专属 Skill。 */
+export declare class SkillStore {
+    readonly workspacePath: string;
+    readonly skillsPath: string;
+    private writeQueue;
+    constructor(workspacePath: string);
+    /** 判断 Codex 返回的绝对路径是否属于本 Store 的标准 Skill 入口。 */
+    isManagedPath(filePath: string): boolean;
+    /** 读取一个可编辑 Skill 的正文与界面元数据。 */
+    get(name: string): Promise<ManagedSkillDetail>;
+    /** 创建新的画布专属 Skill。 */
+    create(input: CreateManagedSkillInput): Promise<ManagedSkillDetail>;
+    /** 通过 revision 防止覆盖已被其他窗口或外部编辑器修改的内容。 */
+    update(nameValue: string, input: UpdateManagedSkillInput): Promise<ManagedSkillDetail>;
+    /** 删除 revision 仍匹配的画布专属 Skill。 */
+    delete(nameValue: string, expectedRevisionValueInput: string): Promise<void>;
+    private mutate;
+    private ensureRoot;
+    private safeExistingPaths;
+    private assertExistingRoot;
+    private readDetail;
+    private writeOpenAi;
+}

package/dist/skills/store.js

@@ -0,0 +1,426 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import matter from "gray-matter";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+const NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+const MAX_INSTRUCTIONS_BYTES = 256 * 1024;
+const MAX_DISPLAY_NAME_LENGTH = 64;
+const MIN_SHORT_DESCRIPTION_LENGTH = 25;
+const MAX_SHORT_DESCRIPTION_LENGTH = 64;
+const MAX_DEFAULT_PROMPT_LENGTH = 1024;
+export class SkillStoreError extends Error {
+    statusCode;
+    name = "SkillStoreError";
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+/** 只管理站点工作空间下 `.agents/skills` 中的画布专属 Skill。 */
+export class SkillStore {
+    workspacePath;
+    skillsPath;
+    writeQueue = Promise.resolve();
+    constructor(workspacePath) {
+        this.workspacePath = path.resolve(workspacePath);
+        this.skillsPath = path.join(this.workspacePath, ".agents", "skills");
+    }
+    /** 判断 Codex 返回的绝对路径是否属于本 Store 的标准 Skill 入口。 */
+    isManagedPath(filePath) {
+        if (!path.isAbsolute(filePath))
+            return false;
+        const relative = path.relative(this.skillsPath, path.resolve(filePath));
+        const segments = relative.split(path.sep);
+        return segments.length === 2 && validName(segments[0]) && segments[1].toLowerCase() === "skill.md";
+    }
+    /** 读取一个可编辑 Skill 的正文与界面元数据。 */
+    async get(name) {
+        try {
+            await this.writeQueue.catch(() => undefined);
+            const paths = await this.safeExistingPaths(name);
+            return await this.readDetail(name, paths.skillFile, paths.openAiFile);
+        }
+        catch (error) {
+            throw storeError(error, "读取 Skill 失败");
+        }
+    }
+    /** 创建新的画布专属 Skill。 */
+    create(input) {
+        return this.mutate(async () => {
+            const name = skillName(input?.name);
+            const description = skillDescription(input?.description);
+            const instructions = skillInstructions(input?.instructions);
+            const skillInterface = skillInterfaceValue(input?.interface, name);
+            await this.ensureRoot();
+            const skillDir = path.join(this.skillsPath, name);
+            const existing = await lstatOptional(skillDir);
+            if (existing) {
+                if (existing.isSymbolicLink())
+                    throw new SkillStoreError("Skill 目录不能是符号链接或目录联接", 400);
+                throw new SkillStoreError("同名 Skill 已存在", 409);
+            }
+            await fs.mkdir(skillDir);
+            try {
+                const skillFile = path.join(skillDir, "SKILL.md");
+                await writeFileAtomic(skillFile, serializeSkill({ name, description }, instructions));
+                const openAiFile = path.join(skillDir, "agents", "openai.yaml");
+                if (skillInterface)
+                    await this.writeOpenAi(openAiFile, {}, skillInterface);
+                return await this.readDetail(name, skillFile, openAiFile);
+            }
+            catch (error) {
+                await fs.rm(skillDir, { recursive: true, force: true }).catch(() => undefined);
+                throw error;
+            }
+        });
+    }
+    /** 通过 revision 防止覆盖已被其他窗口或外部编辑器修改的内容。 */
+    update(nameValue, input) {
+        return this.mutate(async () => {
+            const name = skillName(nameValue);
+            const description = skillDescription(input?.description);
+            const instructions = skillInstructions(input?.instructions);
+            const expectedRevision = expectedRevisionValue(input?.expectedRevision);
+            const interfaceInput = input?.interface;
+            const skillInterface = interfaceInput === undefined ? undefined : skillInterfaceValue(interfaceInput, name);
+            const paths = await this.safeExistingPaths(name);
+            const currentSkill = await readSkill(paths.skillFile, name);
+            const currentOpenAi = await readOpenAi(paths.openAiFile, name);
+            assertRevision(expectedRevision, revision(currentSkill.raw, currentOpenAi.raw));
+            const frontmatter = { ...currentSkill.frontmatter, name, description };
+            await writeFileAtomic(paths.skillFile, serializeSkill(frontmatter, instructions));
+            if (interfaceInput !== undefined) {
+                try {
+                    await this.writeOpenAi(paths.openAiFile, currentOpenAi.data, skillInterface);
+                }
+                catch (error) {
+                    if (!await restoreSkillFiles(paths.skillFile, currentSkill.raw, paths.openAiFile, currentOpenAi.raw)) {
+                        throw new SkillStoreError("Skill 更新失败且无法完全恢复，请检查本地文件", 500);
+                    }
+                    throw error;
+                }
+            }
+            return await this.readDetail(name, paths.skillFile, paths.openAiFile);
+        });
+    }
+    /** 删除 revision 仍匹配的画布专属 Skill。 */
+    delete(nameValue, expectedRevisionValueInput) {
+        return this.mutate(async () => {
+            const name = skillName(nameValue);
+            const expectedRevision = expectedRevisionValue(expectedRevisionValueInput);
+            const paths = await this.safeExistingPaths(name);
+            const currentSkill = await readSkill(paths.skillFile, name);
+            const currentOpenAi = await readOpenAi(paths.openAiFile, name);
+            assertRevision(expectedRevision, revision(currentSkill.raw, currentOpenAi.raw));
+            await assertTreeHasNoLinks(paths.skillDir);
+            const realRoot = await fs.realpath(this.skillsPath);
+            const realSkill = await fs.realpath(paths.skillDir);
+            if (!inside(realRoot, realSkill))
+                throw new SkillStoreError("Skill 路径不安全", 400);
+            await fs.rm(realSkill, { recursive: true });
+        });
+    }
+    mutate(operation) {
+        const result = this.writeQueue.catch(() => undefined).then(operation).catch((error) => { throw storeError(error, "修改 Skill 失败"); });
+        this.writeQueue = result.catch(() => undefined);
+        return result;
+    }
+    async ensureRoot() {
+        const workspace = await lstatOptional(this.workspacePath);
+        if (!workspace)
+            throw new SkillStoreError("站点工作空间不存在", 409);
+        if (workspace.isSymbolicLink())
+            throw new SkillStoreError("站点工作空间不能是符号链接或目录联接", 400);
+        if (!workspace.isDirectory())
+            throw new SkillStoreError("站点工作空间不是目录", 409);
+        const agentsPath = path.join(this.workspacePath, ".agents");
+        await ensurePlainDirectory(agentsPath);
+        await ensurePlainDirectory(this.skillsPath);
+        const realWorkspace = await fs.realpath(this.workspacePath);
+        const realRoot = await fs.realpath(this.skillsPath);
+        if (!inside(realWorkspace, realRoot))
+            throw new SkillStoreError("Skill 根目录不安全", 400);
+    }
+    async safeExistingPaths(nameValue) {
+        const name = skillName(nameValue);
+        await this.assertExistingRoot();
+        const skillDir = path.join(this.skillsPath, name);
+        const directory = await lstatOptional(skillDir);
+        if (!directory)
+            throw new SkillStoreError("找不到指定 Skill", 404);
+        if (directory.isSymbolicLink() || !directory.isDirectory())
+            throw new SkillStoreError("Skill 目录不安全", 400);
+        const realRoot = await fs.realpath(this.skillsPath);
+        const realSkill = await fs.realpath(skillDir);
+        if (!inside(realRoot, realSkill))
+            throw new SkillStoreError("Skill 路径不安全", 400);
+        const skillFile = path.join(skillDir, "SKILL.md");
+        const skillEntry = await lstatOptional(skillFile);
+        if (!skillEntry)
+            throw new SkillStoreError("Skill 缺少 SKILL.md", 404);
+        if (skillEntry.isSymbolicLink() || !skillEntry.isFile())
+            throw new SkillStoreError("SKILL.md 路径不安全", 400);
+        const agentsDir = path.join(skillDir, "agents");
+        const agentsEntry = await lstatOptional(agentsDir);
+        if (agentsEntry && (agentsEntry.isSymbolicLink() || !agentsEntry.isDirectory()))
+            throw new SkillStoreError("Skill agents 目录不安全", 400);
+        const openAiFile = path.join(agentsDir, "openai.yaml");
+        const openAiEntry = await lstatOptional(openAiFile);
+        if (openAiEntry && (openAiEntry.isSymbolicLink() || !openAiEntry.isFile()))
+            throw new SkillStoreError("openai.yaml 路径不安全", 400);
+        return { skillDir, skillFile, openAiFile };
+    }
+    async assertExistingRoot() {
+        const workspace = await lstatOptional(this.workspacePath);
+        if (!workspace)
+            throw new SkillStoreError("找不到指定 Skill", 404);
+        if (workspace.isSymbolicLink())
+            throw new SkillStoreError("站点工作空间不能是符号链接或目录联接", 400);
+        if (!workspace.isDirectory())
+            throw new SkillStoreError("找不到指定 Skill", 404);
+        const agentsPath = path.join(this.workspacePath, ".agents");
+        const agents = await lstatOptional(agentsPath);
+        const root = await lstatOptional(this.skillsPath);
+        if (!agents || !root)
+            throw new SkillStoreError("找不到指定 Skill", 404);
+        if (agents.isSymbolicLink() || !agents.isDirectory() || root.isSymbolicLink() || !root.isDirectory())
+            throw new SkillStoreError("Skill 路径中存在符号链接或目录联接", 400);
+        const realWorkspace = await fs.realpath(this.workspacePath);
+        const realRoot = await fs.realpath(this.skillsPath);
+        if (!inside(realWorkspace, realRoot))
+            throw new SkillStoreError("Skill 根目录不安全", 400);
+    }
+    async readDetail(name, skillFile, openAiFile) {
+        const skill = await readSkill(skillFile, name);
+        const openAi = await readOpenAi(openAiFile, name);
+        return {
+            name,
+            description: skill.description,
+            instructions: skill.instructions,
+            ...(openAi.interface ? { interface: openAi.interface } : {}),
+            path: skillFile,
+            revision: revision(skill.raw, openAi.raw),
+            managed: true,
+        };
+    }
+    async writeOpenAi(filePath, current, skillInterface) {
+        const agentsDir = path.dirname(filePath);
+        const existing = recordValue(current.interface);
+        delete existing.display_name;
+        delete existing.short_description;
+        delete existing.default_prompt;
+        const interfaceYaml = {
+            ...existing,
+            ...(skillInterface?.displayName ? { display_name: skillInterface.displayName } : {}),
+            ...(skillInterface?.shortDescription ? { short_description: skillInterface.shortDescription } : {}),
+            ...(skillInterface?.defaultPrompt ? { default_prompt: skillInterface.defaultPrompt } : {}),
+        };
+        const next = { ...current };
+        if (Object.keys(interfaceYaml).length)
+            next.interface = interfaceYaml;
+        else
+            delete next.interface;
+        if (Object.keys(next).length) {
+            await ensurePlainDirectory(agentsDir);
+            await writeFileAtomic(filePath, stringifyYaml(next, { defaultKeyType: "PLAIN", defaultStringType: "QUOTE_DOUBLE" }));
+        }
+        else {
+            await fs.unlink(filePath).catch((error) => {
+                if (nodeErrorCode(error) !== "ENOENT")
+                    throw error;
+            });
+        }
+    }
+}
+function validName(value) {
+    return Boolean(value && value.length <= MAX_NAME_LENGTH && NAME_PATTERN.test(value));
+}
+function skillName(value) {
+    const name = typeof value === "string" ? value : "";
+    if (!validName(name))
+        throw new SkillStoreError("Skill 名称只能包含小写字母、数字和连字符", 400);
+    return name;
+}
+function skillDescription(value) {
+    const description = typeof value === "string" ? value.trim() : "";
+    if (!description)
+        throw new SkillStoreError("请输入 Skill 描述", 400);
+    if (description.length > MAX_DESCRIPTION_LENGTH)
+        throw new SkillStoreError("Skill 描述过长", 400);
+    if (description.includes("<") || description.includes(">"))
+        throw new SkillStoreError("Skill 描述不能包含尖括号", 400);
+    return description;
+}
+function skillInstructions(value) {
+    const instructions = typeof value === "string" ? value.trim() : "";
+    if (!instructions)
+        throw new SkillStoreError("请输入 Skill 正文", 400);
+    if (Buffer.byteLength(instructions, "utf8") > MAX_INSTRUCTIONS_BYTES)
+        throw new SkillStoreError("Skill 正文不能超过 256KiB", 400);
+    return instructions;
+}
+function skillInterfaceValue(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "object" || Array.isArray(value))
+        throw new SkillStoreError("Skill 界面元数据无效", 400);
+    const interfaceValue = value;
+    const displayName = optionalText(interfaceValue.displayName, "显示名称", MAX_DISPLAY_NAME_LENGTH);
+    const shortDescription = optionalText(interfaceValue.shortDescription, "简短描述", MAX_SHORT_DESCRIPTION_LENGTH);
+    const defaultPrompt = optionalText(interfaceValue.defaultPrompt, "默认提示词", MAX_DEFAULT_PROMPT_LENGTH);
+    if (shortDescription && shortDescription.length < MIN_SHORT_DESCRIPTION_LENGTH)
+        throw new SkillStoreError(`简短描述不能少于 ${MIN_SHORT_DESCRIPTION_LENGTH} 个字符`, 400);
+    if (defaultPrompt && !new RegExp(`\\$${name}(?![A-Za-z0-9_-]|:[A-Za-z0-9_-])`).test(defaultPrompt))
+        throw new SkillStoreError(`默认提示词必须包含 $${name}`, 400);
+    return displayName || shortDescription || defaultPrompt ? { ...(displayName ? { displayName } : {}), ...(shortDescription ? { shortDescription } : {}), ...(defaultPrompt ? { defaultPrompt } : {}) } : undefined;
+}
+function optionalText(value, label, maxLength) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    if (typeof value !== "string")
+        throw new SkillStoreError(`${label}格式无效`, 400);
+    const text = value.trim();
+    if (text.length > maxLength)
+        throw new SkillStoreError(`${label}过长`, 400);
+    return text || undefined;
+}
+function expectedRevisionValue(value) {
+    const expected = typeof value === "string" ? value : "";
+    if (!/^[a-f0-9]{64}$/.test(expected))
+        throw new SkillStoreError("Skill revision 无效，请重新加载后再试", 400);
+    return expected;
+}
+function assertRevision(expected, current) {
+    if (expected !== current)
+        throw new SkillStoreError("Skill 已被其他窗口或外部编辑器修改，请重新加载后再试", 409);
+}
+function serializeSkill(frontmatter, instructions) {
+    return matter.stringify(`${instructions.trim()}\n`, frontmatter);
+}
+async function readSkill(filePath, expectedName) {
+    const raw = await fs.readFile(filePath, "utf8");
+    let parsed;
+    try {
+        parsed = matter(raw);
+    }
+    catch {
+        throw new SkillStoreError("SKILL.md frontmatter 格式无效", 409);
+    }
+    const frontmatter = recordValue(parsed.data);
+    if (frontmatter.name !== expectedName)
+        throw new SkillStoreError("SKILL.md 中的名称与目录不一致", 409);
+    return {
+        raw,
+        frontmatter,
+        description: skillDescription(frontmatter.description),
+        instructions: skillInstructions(parsed.content),
+    };
+}
+async function readOpenAi(filePath, expectedName) {
+    const entry = await lstatOptional(filePath);
+    if (!entry)
+        return { raw: "", data: {} };
+    const raw = await fs.readFile(filePath, "utf8");
+    let data;
+    try {
+        const parsed = parseYaml(raw);
+        if (parsed !== null && parsed !== undefined && (typeof parsed !== "object" || Array.isArray(parsed)))
+            throw new Error("invalid document");
+        data = recordValue(parsed);
+    }
+    catch {
+        throw new SkillStoreError("agents/openai.yaml 格式无效", 409);
+    }
+    if (data.interface !== undefined && data.interface !== null && (typeof data.interface !== "object" || Array.isArray(data.interface))) {
+        throw new SkillStoreError("agents/openai.yaml interface 格式无效", 409);
+    }
+    const value = data.interface;
+    const skillInterface = skillInterfaceValue({ displayName: value?.display_name, shortDescription: value?.short_description, defaultPrompt: value?.default_prompt }, expectedName);
+    return { raw, data, ...(skillInterface ? { interface: skillInterface } : {}) };
+}
+async function restoreSkillFiles(skillFile, skillRaw, openAiFile, openAiRaw) {
+    try {
+        await writeFileAtomic(skillFile, skillRaw);
+        if (openAiRaw) {
+            await ensurePlainDirectory(path.dirname(openAiFile));
+            await writeFileAtomic(openAiFile, openAiRaw);
+        }
+        else {
+            await fs.unlink(openAiFile).catch((error) => {
+                if (nodeErrorCode(error) !== "ENOENT")
+                    throw error;
+            });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeFileAtomic(filePath, content) {
+    const temporary = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    try {
+        await fs.writeFile(temporary, content, { encoding: "utf8", flag: "wx" });
+        await fs.rename(temporary, filePath);
+    }
+    finally {
+        await fs.unlink(temporary).catch((error) => {
+            if (nodeErrorCode(error) !== "ENOENT")
+                throw error;
+        });
+    }
+}
+function revision(skillRaw, openAiRaw) {
+    return crypto.createHash("sha256").update(skillRaw).update("\0").update(openAiRaw).digest("hex");
+}
+async function ensurePlainDirectory(directory) {
+    const entry = await lstatOptional(directory);
+    if (!entry) {
+        await fs.mkdir(directory);
+        return;
+    }
+    if (entry.isSymbolicLink() || !entry.isDirectory())
+        throw new SkillStoreError("Skill 路径中存在符号链接或目录联接", 400);
+}
+async function assertTreeHasNoLinks(directory) {
+    for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
+        const entryPath = path.join(directory, entry.name);
+        const metadata = await fs.lstat(entryPath);
+        if (metadata.isSymbolicLink())
+            throw new SkillStoreError("Skill 目录中存在符号链接或目录联接，无法删除", 400);
+        if (metadata.isDirectory())
+            await assertTreeHasNoLinks(entryPath);
+    }
+}
+function inside(parent, child) {
+    const relative = path.relative(parent, child);
+    return Boolean(relative && !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+async function lstatOptional(filePath) {
+    try {
+        return await fs.lstat(filePath);
+    }
+    catch (error) {
+        if (nodeErrorCode(error) === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? { ...value } : {};
+}
+function nodeErrorCode(error) {
+    return error && typeof error === "object" && "code" in error ? String(error.code || "") : "";
+}
+function storeError(error, fallback) {
+    if (error instanceof SkillStoreError)
+        return error;
+    if (nodeErrorCode(error) === "ENOENT")
+        return new SkillStoreError("找不到指定 Skill", 404);
+    if (["EEXIST", "ENOTEMPTY", "EPERM", "EACCES"].includes(nodeErrorCode(error)))
+        return new SkillStoreError("Skill 文件当前无法修改", 409);
+    return new SkillStoreError(fallback, 500);
+}

package/dist/utils/agent-runtime.d.ts

@@ -0,0 +1,8 @@
+/** Redact bearer tokens, sk- keys, and explicit credential assignments before a string is logged or sent to the browser. */
+export declare function redactAgentLog(text: string): string;
+/** Buffer stderr by line so credentials split across chunks are redacted as one value. */
+export declare function createAgentLogWriter(emit: (text: string) => void, normalize?: (text: string) => string): {
+    write(text: string): void;
+    flush(): void;
+    clear(): void;
+};

package/dist/utils/agent-runtime.js

@@ -0,0 +1,33 @@
+import stripAnsi from "strip-ansi";
+/** Redact bearer tokens, sk- keys, and explicit credential assignments before a string is logged or sent to the browser. */
+export function redactAgentLog(text) {
+    return text
+        .replace(/(authorization\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\r\n,;]+)/gi, "$1[REDACTED]")
+        .replace(/(Bearer\s+)[A-Za-z0-9._~+\/-]+=*/gi, "$1[REDACTED]")
+        .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "[REDACTED]")
+        .replace(/((?:api[ _-]*key|token)\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;]+)/gi, "$1[REDACTED]");
+}
+/** Buffer stderr by line so credentials split across chunks are redacted as one value. */
+export function createAgentLogWriter(emit, normalize = (text) => text) {
+    let buffer = "";
+    const send = (text) => emit(redactAgentLog(normalize(stripAnsi(text))));
+    return {
+        write(text) {
+            buffer += text;
+            let newline = buffer.indexOf("\n");
+            while (newline >= 0) {
+                send(buffer.slice(0, newline + 1));
+                buffer = buffer.slice(newline + 1);
+                newline = buffer.indexOf("\n");
+            }
+        },
+        flush() {
+            if (buffer)
+                send(buffer);
+            buffer = "";
+        },
+        clear() {
+            buffer = "";
+        },
+    };
+}

package/dist/utils/date.d.ts

@@ -0,0 +1,2 @@
+/** 将日期格式化为适合文件名使用的本地日期字符串。 */
+export declare function formatDateForFilename(date?: Date): string;

package/dist/utils/date.js

@@ -0,0 +1,7 @@
+/** 将日期格式化为适合文件名使用的本地日期字符串。 */
+export function formatDateForFilename(date = new Date()) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,17 @@
+/** 管理 Canvas Agent 的终端与文件 Debug 日志。 */
+export declare class Logger {
+    readonly enabled: boolean;
+    readonly filePath: string;
+    private readonly logger;
+    /** 普通模式输出 Info 以上日志，Debug 模式额外输出 Debug 并写入文件。 */
+    constructor();
+    /** 输出 Debug 级别日志。 */
+    debug(message: string, details?: unknown): void;
+    /** 输出 Info 级别日志。 */
+    info(message: string, details?: unknown): void;
+    /** 输出 Warn 级别日志。 */
+    warn(message: string, details?: unknown): void;
+    /** 输出 Error 级别日志。 */
+    error(message: string, details?: unknown): void;
+}
+export declare const logger: Logger;

package/dist/utils/logger.js

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { inspect } from "node:util";
+import winston, { format, transports } from "winston";
+import { formatDateForFilename } from "./date.js";
+/** 管理 Canvas Agent 的终端与文件 Debug 日志。 */
+export class Logger {
+    enabled = process.argv.includes("--debug");
+    filePath = this.enabled ? path.join(os.homedir(), ".infinite-canvas", "logs", `canvas-agent-${formatDateForFilename()}.log`) : "";
+    logger;
+    /** 普通模式输出 Info 以上日志，Debug 模式额外输出 Debug 并写入文件。 */
+    constructor() {
+        const line = format.printf(({ level, message, timestamp, details }) => `${timestamp} ${level.toUpperCase()} ${message}${formatDetails(details)}`);
+        const output = format.combine(format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }), line);
+        if (this.enabled)
+            fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        this.logger = winston.createLogger({
+            level: this.enabled ? "debug" : "info",
+            transports: [
+                new transports.Console({ format: output }),
+                ...(this.enabled ? [new transports.File({ filename: this.filePath, format: output })] : []),
+            ],
+        });
+    }
+    /** 输出 Debug 级别日志。 */
+    debug(message, details) {
+        if (details === undefined)
+            this.logger.debug(message);
+        else
+            this.logger.debug(message, { details: sanitize(details) });
+    }
+    /** 输出 Info 级别日志。 */
+    info(message, details) {
+        if (details === undefined)
+            this.logger.info(message);
+        else
+            this.logger.info(message, { details: sanitize(details) });
+    }
+    /** 输出 Warn 级别日志。 */
+    warn(message, details) {
+        if (details === undefined)
+            this.logger.warn(message);
+        else
+            this.logger.warn(message, { details: sanitize(details) });
+    }
+    /** 输出 Error 级别日志。 */
+    error(message, details) {
+        if (details === undefined)
+            this.logger.error(message);
+        else
+            this.logger.error(message, { details: sanitize(details) });
+    }
+}
+/** 将日志详情格式化为紧凑的单行文本。 */
+function formatDetails(details) {
+    if (details === undefined)
+        return "";
+    if (!details || typeof details !== "object" || Array.isArray(details))
+        return ` ${inspect(details, { depth: null, breakLength: Infinity })}`;
+    const text = Object.entries(details).filter(([, value]) => value !== undefined).map(([key, value]) => `${key}=${inspect(value, { depth: null, breakLength: Infinity })}`).join(" ");
+    return text ? ` ${text}` : "";
+}
+/** 清理日志内容中的敏感数据和不可序列化引用。 */
+function sanitize(value, key = "", seen = new WeakSet()) {
+    if (/token|authorization|api.?key|dataurl/i.test(key))
+        return "[REDACTED]";
+    if (typeof value === "string" && value.startsWith("data:"))
+        return `[DATA URL ${value.length} chars]`;
+    if (value instanceof Error)
+        return { name: value.name, message: value.message, stack: value.stack };
+    if (!value || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return "[CIRCULAR]";
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((item) => sanitize(item, key, seen));
+    return Object.fromEntries(Object.entries(value).map(([field, item]) => [field, sanitize(item, field, seen)]));
+}
+export const logger = new Logger();

package/dist/utils/value.d.ts

@@ -0,0 +1,5 @@
+export type JsonRecord = Record<string, unknown>;
+/** 安全读取未知对象中的指定字段。 */
+export declare function field(value: unknown, key: string): unknown;
+/** 将未知异常转换为可展示的错误信息。 */
+export declare function errorMessage(error: unknown): string;

package/dist/utils/value.js

@@ -0,0 +1,8 @@
+/** 安全读取未知对象中的指定字段。 */
+export function field(value, key) {
+    return value && typeof value === "object" ? value[key] : undefined;
+}
+/** 将未知异常转换为可展示的错误信息。 */
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/version-check.d.ts

@@ -0,0 +1,2 @@
+/** 输出当前版本，并在后台检查 npm 最新版本。 */
+export declare function checkVersions(): void;