@yijiancaotang/cli 0.0.0-stage → 1.0.0

package/dist/platforms.js

@@ -0,0 +1,200 @@
+import { constants } from "node:fs";
+import { access, lstat, readdir, realpath, stat } from "node:fs/promises";
+import { delimiter, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { asRecord, CliError } from "./errors.js";
+const unsafe = () => new CliError("platform_path_unsafe", "平台目录未通过安全检查。", "请使用用户目录内的绝对路径，并检查目录和符号链接；不要提供目录中的配置内容。");
+const metadataError = (error) => {
+    const code = asRecord(error)?.code;
+    return code === "EACCES" || code === "EPERM"
+        ? new CliError("platform_permission_denied", "没有权限检查平台程序目录。", "请由本人检查程序目录的访问权限，不要自动提权或修改权限。", 4)
+        : code === "ELOOP" ? unsafe()
+            : new CliError("platform_detection_failed", "无法完成平台程序检查。", "请检查本地程序目录后重新执行只读检查，不要启动客户端或输出配置内容。");
+};
+const missing = (error) => ["ENOENT", "ENOTDIR"].includes(String(asRecord(error)?.code));
+const absolute = (path) => typeof path === "string" && isAbsolute(path) && !/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(path);
+const within = (home, path) => {
+    const part = relative(home, path);
+    return part !== ".." && !part.startsWith(`..${sep}`) && !isAbsolute(part);
+};
+async function executable(path) {
+    try {
+        const info = await stat(path);
+        if (!info.isFile() || (info.mode & 0o111) === 0)
+            return false;
+        try {
+            await access(path, constants.X_OK);
+        }
+        catch (error) {
+            if (["EACCES", "EPERM", "ENOENT", "ENOTDIR"].includes(String(asRecord(error)?.code)))
+                return false;
+            throw error;
+        }
+        return true;
+    }
+    catch (error) {
+        if (missing(error))
+            return false;
+        throw metadataError(error);
+    }
+}
+async function directories(path) {
+    try {
+        return (await readdir(path, { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+            .map((entry) => entry.name).sort();
+    }
+    catch (error) {
+        if (missing(error))
+            return [];
+        throw metadataError(error);
+    }
+}
+async function skillDirectory(home, canonicalHome, root) {
+    if (!absolute(root))
+        throw unsafe();
+    const target = resolve(root, "skills");
+    if (!within(home, resolve(root)) || !within(home, target))
+        throw unsafe();
+    // Check existing ancestry as metadata only, including symlink escapes before a missing leaf.
+    let current = home;
+    for (const component of relative(home, target).split(sep).filter(Boolean)) {
+        current = join(current, component);
+        try {
+            const info = await lstat(current);
+            if (info.isSymbolicLink()) {
+                let resolved;
+                try {
+                    resolved = await realpath(current);
+                }
+                catch (error) {
+                    if (missing(error))
+                        throw unsafe();
+                    throw error;
+                }
+                if (!within(canonicalHome, resolved) || !(await stat(current)).isDirectory())
+                    throw unsafe();
+            }
+            else if (!info.isDirectory())
+                throw unsafe();
+        }
+        catch (error) {
+            if (asRecord(error)?.code === "ENOENT")
+                break;
+            if (error instanceof CliError)
+                throw error;
+            throw metadataError(error);
+        }
+    }
+    return target;
+}
+async function claudeDesktop(home) {
+    const root = join(home, "Library", "Application Support", "Claude", "claude-code");
+    for (const version of await directories(root)) {
+        if (!/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(version))
+            continue;
+        for (const hash of await directories(join(root, version))) {
+            if (!/^[a-f0-9]{6,64}$/i.test(hash))
+                continue;
+            if (await executable(join(root, version, hash, "claude.app", "Contents", "MacOS", "claude")))
+                return true;
+        }
+    }
+    return false;
+}
+export async function detectPlatforms(options) {
+    if (!absolute(options.homeDir))
+        throw unsafe();
+    const home = resolve(options.homeDir);
+    let canonicalHome;
+    try {
+        canonicalHome = await realpath(home);
+        if (!(await stat(home)).isDirectory())
+            throw unsafe();
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw metadataError(error);
+    }
+    const { env } = options;
+    const roots = options.applicationRoots ?? ["/Applications", join(home, "Applications")];
+    if (!roots.every(absolute))
+        throw unsafe();
+    const selected = (id) => options.platformIds === undefined || options.platformIds.includes(id);
+    const targets = [];
+    const candidates = [
+        { id: "claude-code", root: () => env.CLAUDE_CONFIG_DIR ?? join(home, ".claude") },
+        { id: "codex", root: () => join(home, ".agents") },
+        { id: "openclaw", root: () => env.OPENCLAW_STATE_DIR ?? (env.OPENCLAW_HOME === undefined ? join(home, ".openclaw") : (() => {
+                if (!absolute(env.OPENCLAW_HOME) || !within(home, resolve(env.OPENCLAW_HOME)))
+                    throw unsafe();
+                return join(env.OPENCLAW_HOME, ".openclaw");
+            })()) },
+    ];
+    for (const candidate of candidates) {
+        if (selected(candidate.id))
+            targets.push({ id: candidate.id, detected: false, evidence: "none", skillDirectory: await skillDirectory(home, canonicalHome, candidate.root()) });
+    }
+    const pathRoots = (env.PATH ?? "").split(delimiter).filter(absolute);
+    for (const target of targets) {
+        const command = target.id === "claude-code" ? "claude" : target.id;
+        for (const root of pathRoots) {
+            if (await executable(join(root, command))) {
+                target.detected = true;
+                target.evidence = "executable";
+                break;
+            }
+        }
+        if (target.detected)
+            continue;
+        if (target.id === "claude-code") {
+            target.detected = await claudeDesktop(home);
+        }
+        else {
+            const app = target.id === "codex" ? "Codex" : "OpenClaw";
+            for (const root of roots) {
+                if (await executable(join(root, `${app}.app`, "Contents", "MacOS", app))
+                    || (target.id === "codex" && await executable(join(root, "ChatGPT.app", "Contents", "Resources", "codex-cli", "CodexCLI.app", "Contents", "MacOS", "codex")))) {
+                    target.detected = true;
+                    break;
+                }
+            }
+        }
+        if (target.detected)
+            target.evidence = "desktop";
+    }
+    if ((options.operatingSystem ?? process.platform) === "darwin") {
+        // Do not inspect an unselected new platform's personal paths. Without a
+        // selector, only a verified program makes its skill root relevant.
+        for (const [id, app, binary, rootPath, command] of [
+            ["kimi-code", "Kimi Code", "Kimi Code", env.KIMI_CODE_HOME ?? join(home, ".kimi-code"), "kimi"],
+            ["kimi-work", "Kimi", "Kimi", join(home, "Library/Application Support/kimi-desktop/daimon-share/daimon"), null],
+            ["workbuddy", "WorkBuddy", "Electron", join(home, ".workbuddy"), null],
+        ]) {
+            if (!selected(id))
+                continue;
+            let detected = false;
+            let evidence = "none";
+            if (command)
+                for (const root of pathRoots) {
+                    if (await executable(join(root, command))) {
+                        detected = true;
+                        evidence = "executable";
+                        break;
+                    }
+                }
+            if (!detected)
+                for (const root of roots) {
+                    if (await executable(join(root, `${app}.app`, "Contents", "MacOS", binary))) {
+                        detected = true;
+                        evidence = "desktop";
+                        break;
+                    }
+                }
+            if (!detected && options.platformIds === undefined)
+                continue;
+            targets.push({ id, detected, evidence, skillDirectory: await skillDirectory(home, canonicalHome, rootPath) });
+        }
+    }
+    return targets;
+}

package/dist/query-daily.js

@@ -0,0 +1,70 @@
+import { asRecord, CliError, expectOK } from "./errors.js";
+import { validDate } from "./query-validation.js";
+import { safeSearchWarnings } from "./query-search.js";
+const leap = (year) => year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+function ordinal(year, month, day) {
+    const prior = year - 1;
+    const months = [31, leap(year) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    return 365 * prior + Math.floor(prior / 4) - Math.floor(prior / 100) + Math.floor(prior / 400) + months.slice(0, month - 1).reduce((sum, value) => sum + value, 0) + day - 1;
+}
+export function validateDailyDates(flags) {
+    const start = flags["start-date"], end = flags["end-date"];
+    if (!validDate(start) || !validDate(end))
+        throw new CliError("invalid_arguments", "日汇总起止日期参数无效。", "必须同时提供 --start-date 和 --end-date，使用真实 YYYY-MM-DD（0001至9999年），不可为空。");
+    const [sy, sm, sd] = start.split("-").map(Number), [ey, em, ed] = end.split("-").map(Number);
+    // Use civil ordinals, not JS Date years 0..99, timezone offsets or 366 days.
+    // Internal year 10000 is valid for the exclusive bound of wire year 9999.
+    const nextMonth = sm === 2 && sd === 29 && !leap(sy + 1) ? 3 : sm;
+    const nextDay = nextMonth !== sm ? 1 : sd;
+    if (start > end || ordinal(ey, em, ed) + 1 > ordinal(sy + 1, nextMonth, nextDay))
+        throw new CliError("invalid_arguments", "日汇总日期范围无效。", "起始不得晚于结束；含首尾日期最多一个日历年，闰日周年按次年3月1日计算，不按固定366天计算。");
+}
+export function isDailyParameterError(value) {
+    return typeof value === "string" && ["start_date is required", "end_date is required", "date range exceeds one calendar year", "unsupported daily parameter", "invalid daily query", "invalid start_date", "invalid end_date", "invalid date range", "invalid limit", "invalid offset"].some(message => value === message || value === `${message}\n`);
+}
+const coverages = ["unavailable", "not_recorded", "partial", "complete"];
+function validDailyMetadata(value) {
+    const body = asRecord(value);
+    if (!body || !Array.isArray(body.days) || typeof body.partial !== "boolean" || (body.coverage_start !== null && typeof body.coverage_start !== "string"))
+        return false;
+    return body.days.every(day => {
+        const row = asRecord(day);
+        return row !== null && validDate(row.date) && typeof row.knowledge_growth_coverage === "string" && coverages.includes(row.knowledge_growth_coverage)
+            && ["progress", "knowledge_created", "knowledge_growth", "redacted_progress_count"].every(key => row[key] === null || typeof row[key] === "number" && Number.isSafeInteger(row[key]) && row[key] >= 0);
+    });
+}
+export function formatDailyNotice(value) {
+    const body = asRecord(value);
+    if (!body || body.timezone !== "Asia/Shanghai" || !Array.isArray(body.days))
+        return "";
+    const days = body.days.map(asRecord).filter((row) => row !== null);
+    let result = "每日数量是完整日期范围的统计，不是当前页明细数；明细total只含可读事件。\n";
+    if (days.some(row => [row.progress, row.knowledge_created, row.knowledge_growth, row.redacted_progress_count].includes(null)))
+        result += "null表示不可读取或未完整记录，不能当作0。\n";
+    if (days.some(row => row.knowledge_growth_coverage === "not_recorded"))
+        result += "知识长势覆盖起点之前未完整记录，不能据此判断没有变化。\n";
+    if (days.some(row => row.knowledge_growth_coverage === "partial"))
+        result += "知识长势覆盖起点当天仅部分记录，不代表完整一天。\n";
+    if (body.partial === true)
+        result += "本次结果不完整；草稿被过滤时数字不含草稿，不能理解成当天没有活动。\n";
+    if (days.some(row => typeof row.redacted_progress_count === "number" && row.redacted_progress_count > 0))
+        result += "部分知识应用进展仅保留匿名日计数，不返回身份、关联或正文。\n";
+    return result;
+}
+export function expectDailyOK(result) {
+    if (result.status === 400 && isDailyParameterError(result.body))
+        throw new CliError("invalid_arguments", "日汇总参数无效。", "仅支持必填起止日期与limit/offset；真实日期含首尾最多一个日历年，limit为1至50，offset为非负安全整数。", 2, { http_status: 400 });
+    if (result.status === 404)
+        throw new CliError("not_found", "当前日汇总入口不可用。", "请核对服务版本与访问范围；这不表示没有活动数据。", 2, { http_status: 404 });
+    const body = asRecord(result.body), code = body?.code ?? body?.error;
+    if (result.status === 403 && code === "capability_disabled" && (body?.code === undefined || body.code === code) && (body?.error === undefined || body.error === code)) {
+        const expected = [{ section: "daily_progress", required_capability: "read_projects", reason: "capability_disabled" }, { section: "daily_knowledge", required_capability: "read_knowledge", reason: "capability_disabled" }];
+        const rows = Array.isArray(body?.missing_sections) ? body.missing_sections : [];
+        if (!Object.hasOwn(body, "required_capability") && expected.every(want => rows.some(row => { const item = asRecord(row); return item?.section === want.section && item.required_capability === want.required_capability && item.reason === want.reason; })))
+            throw new CliError("capability_disabled", "“读取项目”和“读取知识”开关都未开启。", "请本人到网页的 Agent 管理核对并开启所需开关；不要重新授权、换入口或重试来绕过限制。", 4, { http_status: 403, missing_sections: expected });
+    }
+    const checked = expectOK(result, "read");
+    if (!validDailyMetadata(checked.body))
+        throw new CliError("invalid_response", "日汇总返回了无法确认的计数或覆盖信息。", "请核对服务返回合同；不要把未知计数当作0或输出未经确认的身份信息。", 7);
+    return { ...checked, body: safeSearchWarnings(checked.body) };
+}

package/dist/query-search.js

@@ -0,0 +1,42 @@
+import { asRecord, CliError } from "./errors.js";
+import { expectQueryOK } from "./query-validation.js";
+const trimSearch = (value) => value.replace(/^\p{White_Space}+|\p{White_Space}+$/gu, "");
+export function validateSearch(q, flags) {
+    if (q !== undefined && (q.includes("\0") || /[\uD800-\uDFFF]/u.test(q) || [...trimSearch(q)].length > 200)) {
+        throw new CliError("invalid_arguments", "搜索词参数无效。", "搜索词首尾空白不计，最多200个Unicode字符；不能含NUL或无效字符。可省略搜索词按日期浏览。");
+    }
+    if (["project", "topic"].some(key => flags[key] !== undefined && (typeof flags[key] !== "string" || !trimSearch(flags[key])))) {
+        throw new CliError("invalid_arguments", "知识分支筛选参数无效。", "--project 和 --topic 不可显式为空；这些参数只筛知识分支，不筛其它类型。");
+    }
+}
+export function isSearchParameterError(value) {
+    return typeof value === "string" && ["invalid q", "invalid status", "invalid topic", "invalid publication_status", "invalid project_id", "invalid core_only", "unsupported core filter"].some(message => value === message || value === `${message}\n`);
+}
+export const searchWarningNotice = "历史手写进展与项目进展存在无法唯一确认的镜像关系，已保留记录，结果中可能有少量重复。\n";
+export function safeSearchWarnings(value) {
+    const body = asRecord(value);
+    if (!body || !Object.hasOwn(body, "warnings"))
+        return value;
+    const { warnings, ...rest } = body;
+    return Array.isArray(warnings) && warnings.includes("historical_mirror_ambiguous") ? { ...rest, warnings: ["historical_mirror_ambiguous"] } : rest;
+}
+export function formatSearchWarnings(value) {
+    const warnings = asRecord(value)?.warnings;
+    return Array.isArray(warnings) && warnings.includes("historical_mirror_ambiguous") ? searchWarningNotice : "";
+}
+export function expectSearchOK(result) {
+    if (result.status === 400 && isSearchParameterError(result.body)) {
+        throw new CliError("invalid_arguments", "搜索参数无效。", "搜索词最多200个Unicode字符；status/topic/publication-status/project只筛知识且不可显式为空。只看核心请使用 --core-only。", 2, { http_status: 400 });
+    }
+    const body = asRecord(result.body), code = body?.code ?? body?.error;
+    if (result.status === 403 && code === "capability_disabled" && (body?.code === undefined || body.code === code) && (body?.error === undefined || body.error === code)) {
+        const expected = [{ section: "search_projects", required_capability: "read_projects", reason: "capability_disabled" }, { section: "search_knowledge", required_capability: "read_knowledge", reason: "capability_disabled" }];
+        const rows = Array.isArray(body?.missing_sections) ? body.missing_sections : [];
+        if (!Object.hasOwn(body, "required_capability") && expected.every(want => rows.some(row => { const item = asRecord(row); return item?.section === want.section && item.required_capability === want.required_capability && item.reason === want.reason; }))) {
+            throw new CliError("capability_disabled", "“读取项目”和“读取知识”开关都未开启。", "请本人到网页的 Agent 管理核对并开启所需开关；不要重新授权、换入口或重试来绕过限制。", 4, { http_status: 403, missing_sections: expected });
+        }
+    }
+    const checked = expectQueryOK(result);
+    const cleaned = safeSearchWarnings(checked.body);
+    return cleaned === checked.body ? checked : { ...checked, body: cleaned };
+}

package/dist/query-validation.js

@@ -0,0 +1,45 @@
+import { CliError, expectOK } from "./errors.js";
+export const dateFlags = ["start-date", "end-date", "date-field"];
+export function validDate(value) {
+    if (typeof value !== "string" || value.length !== 10 || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const [year, month, day] = value.split("-").map(Number);
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    return year >= 1 && month >= 1 && month <= 12 && day >= 1 && day <= days[month - 1];
+}
+export function validateDateFlags(flags, createdOnly = false) {
+    if ((flags["start-date"] !== undefined && !validDate(flags["start-date"]))
+        || (flags["end-date"] !== undefined && !validDate(flags["end-date"]))) {
+        throw new CliError("invalid_arguments", "日期参数无效。", "--start-date 和 --end-date 请使用真实的 YYYY-MM-DD 日期（0001 至 9999 年）；省略表示不设该侧边界，不可留空。按北京时间包含首尾两天。");
+    }
+    if (typeof flags["start-date"] === "string" && typeof flags["end-date"] === "string" && flags["start-date"] > flags["end-date"]) {
+        throw new CliError("invalid_arguments", "起止日期参数顺序无效。", "--start-date 不得晚于 --end-date；可以只提供一侧日期。");
+    }
+    const field = flags["date-field"];
+    if (field !== undefined && (createdOnly ? field !== "created_at" : field !== "created_at" && field !== "updated_at")) {
+        throw new CliError("invalid_arguments", "--date-field 参数无效。", createdOnly ? "项目进展和手写进展固定按 created_at 写入时间筛选；可省略 --date-field。" : "--date-field 请使用 created_at 或 updated_at；省略时按 updated_at 筛选，不可留空。");
+    }
+}
+export function isPagedQueryPath(path) {
+    return /^\/api\/v1\/agent\/(?:m1\/(?:projects(?:\/[^/]+\/updates)?|knowledge|checkins|search|activity\/daily)|pending-actions)$/.test(path);
+}
+export function isProjectIDParameterError(path, value) {
+    return /^\/api\/v1\/agent\/m1\/(?:projects\/[^/]+\/updates|knowledge)$/.test(path)
+        && (value === "invalid project_id" || value === "invalid project_id\n");
+}
+// Go http.Error has a narrow plain-text contract. Adopt exact known bodies only;
+// JSON messages, suffixes, and other server text are never reflected to users.
+export function isQueryParameterError(value) {
+    return typeof value === "string" && ["invalid limit", "invalid offset", "invalid start_date", "invalid end_date", "invalid date range", "invalid date_field"].some(message => value === message || value === `${message}\n`);
+}
+export function expectQueryOK(result, maxLimit = 50) {
+    if (result.status === 400 && isQueryParameterError(result.body)) {
+        const nextAction = result.body.startsWith("invalid limit")
+            ? maxLimit === 50 ? "--limit 必须是 1 至 50 的整数。" : "--limit 必须是 1 至 100 的整数。"
+            : result.body.startsWith("invalid offset") ? "--offset 必须是 0 至 9007199254740991 的整数。"
+                : "日期须为真实 YYYY-MM-DD，起始不得晚于结束且显式值不可为空；项目/知识可选 created_at 或 updated_at，进展固定 created_at。";
+        throw new CliError("invalid_arguments", "查询参数无效。", nextAction, 2, { http_status: 400 });
+    }
+    return expectOK(result, "read");
+}

package/dist/skill-assets.js

@@ -0,0 +1,136 @@
+import { agentIdentity, shellWord } from "./agent-identity.js";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { isAbsolute, join, parse, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { asRecord, CliError } from "./errors.js";
+// One release path allowlist, checked against the real package manifest.
+// Never use an arbitrary manifest entry as a filesystem installation target.
+export const skillNames = Object.freeze(["caotang-context", "caotang-save-knowledge", "caotang-project-progress", "caotang-search", "caotang-workday", "caotang-first-connect"]);
+export function completeSkillInventory(names) {
+    return names.length === skillNames.length && new Set(names).size === skillNames.length && names.every(name => skillNames.includes(name));
+}
+const manifestLimit = 16 * 1024;
+const contentLimit = 64 * 1024;
+const invalid = () => new CliError("skill_assets_invalid", "本包技能资源未通过安全或格式检查。", "请使用完整、未修改的一间草堂命令行安装包，不要复制不明技能文件。", 7);
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const unchanged = (a, b) => sameFile(a, b) && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs;
+async function addDirectory(directories, path) {
+    const stat = await lstat(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw invalid();
+    directories.push({ path, stat });
+}
+async function checkDirectories(directories) {
+    for (const directory of directories) {
+        const current = await lstat(directory.path);
+        if (!current.isDirectory() || current.isSymbolicLink() || !sameFile(directory.stat, current))
+            throw invalid();
+    }
+}
+function checkRegular(stat, limit) {
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size < 1 || stat.size > limit)
+        throw invalid();
+}
+async function readAsset(path, limit, directories) {
+    await checkDirectories(directories);
+    const before = await lstat(path);
+    checkRegular(before, limit);
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const opened = await handle.stat();
+        checkRegular(opened, limit);
+        if (!unchanged(before, opened))
+            throw invalid();
+        // Bound the read even if a regular file grows after fstat; never wait on a FIFO.
+        const buffer = Buffer.alloc(limit + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+            if (bytesRead === 0)
+                break;
+            length += bytesRead;
+        }
+        const after = await handle.stat();
+        const current = await lstat(path);
+        checkRegular(after, limit);
+        checkRegular(current, limit);
+        if (length > limit || length !== opened.size || !unchanged(opened, after) || !unchanged(after, current))
+            throw invalid();
+        await checkDirectories(directories);
+        const bytes = buffer.subarray(0, length);
+        const content = bytes.toString("utf8");
+        if (!Buffer.from(content, "utf8").equals(bytes))
+            throw invalid();
+        return content;
+    }
+    finally {
+        await handle.close();
+    }
+}
+function metadata(content) {
+    const manifest = asRecord(JSON.parse(content));
+    if (!manifest || Object.keys(manifest).sort().join(",") !== "formatVersion,skills" || manifest.formatVersion !== 1
+        || !Array.isArray(manifest.skills) || manifest.skills.length !== skillNames.length)
+        throw invalid();
+    const seen = new Set();
+    return manifest.skills.map((value) => {
+        const item = asRecord(value);
+        if (!item || Object.keys(item).sort().join(",") !== "description,name" || typeof item.name !== "string"
+            || !skillNames.some(name => name === item.name) || seen.has(item.name)
+            || typeof item.description !== "string" || !item.description.trim() || item.description.trim() !== item.description
+            || item.description.length > 1000 || /[\x00-\x1f\x7f]/.test(item.description))
+            throw invalid();
+        seen.add(item.name);
+        return { name: item.name, description: item.description };
+    });
+}
+export async function loadSkillAssets(packageRoot) {
+    try {
+        const requested = packageRoot ?? fileURLToPath(new URL("../", import.meta.url));
+        if (typeof requested !== "string" || !requested || !isAbsolute(requested) || requested.includes("\0"))
+            throw invalid();
+        const root = resolve(requested);
+        const directories = [];
+        let path = parse(root).root;
+        await addDirectory(directories, path);
+        for (const part of root.slice(path.length).split(sep).filter(Boolean)) {
+            path = join(path, part);
+            await addDirectory(directories, path);
+        }
+        const skills = join(root, "skills");
+        await addDirectory(directories, skills);
+        const entries = metadata(await readAsset(join(skills, "manifest.json"), manifestLimit, directories));
+        for (const name of skillNames)
+            await addDirectory(directories, join(skills, name));
+        const assets = [];
+        for (const item of entries) {
+            const content = await readAsset(join(skills, item.name, "SKILL.md"), contentLimit, directories);
+            // JSON strings are valid YAML double-quoted scalars; no general YAML parser is needed.
+            const prefix = `---\nname: ${item.name}\ndescription: ${JSON.stringify(item.description)}\n---\n`;
+            if (!content.startsWith(prefix) || !content.slice(prefix.length).trim())
+                throw invalid();
+            assets.push({ ...item, content, sha256: createHash("sha256").update(content, "utf8").digest("hex") });
+        }
+        await checkDirectories(directories);
+        return assets;
+    }
+    catch {
+        throw invalid();
+    }
+}
+// Bind only the files installed into one AI platform; the shared runtime bundle
+// remains byte-for-byte independent of the selected identity.
+export function bindSkillAgent(asset, name) {
+    if (name === undefined)
+        return asset;
+    const agent = agentIdentity(name), word = shellWord(agent.key);
+    const marker = asset.content.indexOf("\n---\n");
+    if (marker < 0)
+        throw invalid();
+    const prefix = asset.content.slice(0, marker + 5);
+    const body = asset.content.slice(marker + 5).replace(/\bcaotang(?=\s+(?:--|[a-z]))/g, `caotang --agent ${word}`);
+    const content = `${prefix}\n本技能使用的 AI 名字是 ${JSON.stringify(agent.key)}。每条草堂命令都必须保留 --agent，不能借用其它 AI 的连接。\n${body}`;
+    return { ...asset, content, sha256: createHash("sha256").update(content, "utf8").digest("hex") };
+}

package/dist/upload.js

@@ -0,0 +1,130 @@
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { CliError, expectOK, apiError, asRecord } from "./errors.js";
+import { validateInput, invalidInput, inputDetails } from "./input-validation.js";
+const maxBytes = 10485760;
+const contentType = "application/pdf";
+const runeLength = (value) => [...value].length;
+function invalidFile() {
+    throw new CliError("invalid_upload", "请选择1至10485760字节的本地普通PDF文件。", "请明确指定本地PDF，不接受符号链接、网址、目录或标准输入。");
+}
+const unverifiedError = (status) => new CliError("upload_unverified", "尚未取得匹配的上传完成回执。", "请先在网页核对文件和卡片；不要再次PUT或自动申请替代上传凭证。", 2, status === undefined ? {} : { http_status: status });
+function unverified(status) { throw unverifiedError(status); }
+async function readPDF(path) {
+    let handle;
+    try {
+        if (!path || path === "-" || /^[a-z][a-z0-9+.-]*:/i.test(path))
+            invalidFile();
+        const name = basename(path);
+        if (!/\.pdf$/i.test(name) || runeLength(name) < 5 || runeLength(name) > 180 || /[\x00-\x1f\x7f]/.test(name))
+            invalidFile();
+        if (await realpath(path) !== resolve(path))
+            invalidFile();
+        const before = await lstat(path);
+        if (before.isSymbolicLink() || !before.isFile() || before.size < 1 || before.size > maxBytes)
+            invalidFile();
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.size !== before.size)
+            invalidFile();
+        // One extra byte detects growth without an unbounded readFile allocation.
+        const bytes = Buffer.alloc(opened.size + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const read = await handle.read(bytes, length, bytes.length - length, null);
+            if (read.bytesRead === 0)
+                break;
+            length += read.bytesRead;
+        }
+        const after = await handle.stat();
+        const current = await lstat(path);
+        if (current.isSymbolicLink() || current.dev !== opened.dev || current.ino !== opened.ino || await realpath(path) !== resolve(path) || length !== opened.size || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs || bytes.subarray(0, 5).toString("ascii") !== "%PDF-")
+            invalidFile();
+        return { name, bytes: bytes.subarray(0, length) };
+    }
+    catch {
+        return invalidFile();
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+function grantFields(result, baseUrl, size) {
+    expectOK(result);
+    if (result.status !== 200 && result.status !== 201)
+        unverified(result.status);
+    const upload = asRecord(asRecord(result.body)?.upload);
+    if (!upload || typeof upload.file_key !== "string" || !upload.file_key || runeLength(upload.file_key) > 500 || /[\x00-\x1f\x7f]/.test(upload.file_key) || upload.method !== "PUT" || upload.size_bytes !== size || upload.content_type !== contentType || !Number.isSafeInteger(upload.max_bytes) || upload.max_bytes < size || upload.max_bytes > maxBytes || typeof upload.upload_url !== "string")
+        unverified();
+    try {
+        const url = new URL(upload.upload_url);
+        if (url.origin !== new URL(baseUrl).origin || url.username || url.password || url.search || url.hash || !/^\/api\/v1\/knowledge-files\/uploads\/[A-Za-z0-9_-]+$/.test(url.pathname))
+            unverified();
+    }
+    catch {
+        unverified();
+    }
+    const required = asRecord(upload.required_headers);
+    if (!required || Object.keys(required).length !== 2)
+        unverified();
+    const headers = {};
+    const seen = new Set();
+    for (const [name, value] of Object.entries(required)) {
+        const key = name.toLowerCase();
+        if (!["content-type", "x-opc-upload-token"].includes(key) || seen.has(key) || typeof value !== "string" || !value || value.length > 8192 || /[\s\x00-\x1f\x7f]/.test(value))
+            unverified();
+        if (key === "content-type" && value !== contentType)
+            unverified();
+        seen.add(key);
+        headers[name] = value;
+    }
+    if (!seen.has("content-type") || !seen.has("x-opc-upload-token"))
+        unverified();
+    return { fileKey: upload.file_key, url: upload.upload_url, headers };
+}
+export async function executeUpload(path, flags, ctx) {
+    const operationAudit = [];
+    try {
+        validateInput(Object.fromEntries(Object.entries(flags).filter(([, value]) => value !== undefined)), {
+            fields: {
+                card: value => typeof value === "string" && !!value.trim() && ![".", ".."].includes(value) && !/[\x00-\x1f\x7f]/.test(value),
+                "source-title": value => typeof value === "string" && runeLength(value) <= 300,
+                summary: value => typeof value === "string" && runeLength(value) <= 1200,
+            }, required: ["card"],
+        }, ["upload"]);
+        let card;
+        try {
+            card = encodeURIComponent(flags.card);
+        }
+        catch {
+            throw invalidInput(["upload"], { invalid: ["card"] });
+        }
+        const { name, bytes } = await readPDF(path);
+        const issued = await ctx.api.request("/api/v1/agent/m2/knowledge-files/upload-url", { method: "POST", token: ctx.token, body: { file_name: name, size_bytes: bytes.length } });
+        const grant = grantFields(issued, ctx.api.baseUrl, bytes.length);
+        const grantBody = asRecord(issued.body);
+        if (grantBody?.audit_pending === true) {
+            if (grantBody.audit_recovery !== "automatic" && grantBody.audit_recovery !== "manual_required")
+                throw new CliError("upload_audit_unverified", "无法确认上传凭证的审计状态。", "请先在网页核对再处理上传，不要自动申请替代凭证。", 7);
+            operationAudit.push({ stage: "upload_grant", http_status: issued.status, audit_pending: true, audit_recovery: grantBody.audit_recovery });
+        }
+        const stored = await ctx.api.upload(grant.url, grant.headers, bytes);
+        if (stored.status < 200 || stored.status >= 300)
+            throw apiError(stored);
+        const receipt = asRecord(stored.body);
+        if (![200, 201].includes(stored.status) || !receipt || Object.keys(receipt).length !== 3 || receipt.file_key !== grant.fileKey || receipt.size_bytes !== bytes.length || receipt.content_type !== contentType)
+            unverified(stored.status);
+        const attached = expectOK(await ctx.api.request(`/api/v1/agent/m2/knowledge-cards/${card}/file-source`, {
+            method: "POST", token: ctx.token,
+            body: { file_key: grant.fileKey, ...(flags["source-title"] === undefined ? {} : { source_title: flags["source-title"] }), ...(flags.summary === undefined ? {} : { summary: flags.summary }) }
+        }));
+        return operationAudit.length ? { ...attached, operationAudit } : attached;
+    }
+    catch (error) {
+        const safe = error instanceof CliError ? error : unverifiedError();
+        if (safe.code === "invalid_upload")
+            Object.assign(safe.details, inputDetails(["upload"], { invalid: ["<pdf>"] }));
+        throw operationAudit.length ? new CliError(safe.code, safe.message, safe.nextAction, safe.exitCode, { ...safe.details, operation_audit: operationAudit }) : safe;
+    }
+}