@kyun.si/agent2cursor 0.0.0-stage → 0.1.1

package/dist/mapping/foreign-tools.js

@@ -0,0 +1,33 @@
+const REPLACEMENTS = {
+    WebFetch: ["没有已核实的 SDK 抓取工具映射；请提供页面内容或人工实现受控抓取工具。此处仅报告名称引用，不改写正文。", "No verified SDK fetch-tool mapping; provide page content or implement a controlled fetch tool manually. This reports a name reference without rewriting the body."],
+    WebSearch: ["没有已核实的 SDK 搜索工具映射；请提供检索资料或人工配置搜索工具，并复核访问权限。", "No verified SDK search-tool mapping; provide search material or configure a search tool manually and review access permissions."],
+    AskUserQuestion: ["没有已验证的直接替代；在最终回复开头提问，等待人工确认。", "No verified direct equivalent; ask at the start of the final reply and await human confirmation."],
+    request_user_input: ["没有已验证的直接替代；在最终回复开头提问，等待人工确认。", "No verified direct equivalent; ask at the start of the final reply and await human confirmation."],
+    request_user_input_async: ["没有已验证的异步交互替代；改为明确提问并等待人工回复，不能按超时视作批准。", "No verified asynchronous input equivalent; ask explicitly and await the user's response. A timeout is not approval."],
+    spawn_agent: ["改为 task 和实际声明的 SDK 子代理；Codex 的 fork、模型覆盖与并发语义需人工适配。", "Use task with declared SDK subagents; adapt Codex fork, model overrides, and concurrency semantics manually."],
+    send_input: ["Codex 子代理续传消息没有已核实的直接映射；按 SDK task 的生命周期重写。", "No verified direct mapping for follow-up messages to Codex subagents; rewrite around the SDK task lifecycle."],
+    close_agent: ["Codex 子代理关闭没有已核实的直接映射；按 SDK task 的生命周期重写。", "No verified direct mapping for closing Codex subagents; rewrite around the SDK task lifecycle."],
+    resume_agent: ["Codex 子代理恢复没有已核实的直接映射；按 SDK task 的生命周期重写。", "No verified direct mapping for resuming Codex subagents; rewrite around the SDK task lifecycle."],
+    wait_agent: ["改为 SDK task 结果收集；后台等待和超时语义需人工适配。", "Collect SDK task results; adapt background waiting and timeout semantics manually."],
+    wait: ["Codex wait 调用需按 SDK task 的结果收集方式重写；等待和超时语义不能直接透传。", "Rewrite Codex wait calls around SDK task result collection; waiting and timeout semantics are not directly portable."],
+    list_agents: ["请用生成项目中实际声明的子代理清单；没有已核实的 Codex 活跃代理列表接口映射。", "Use the subagents declared in the generated project; no verified mapping exists for the Codex live-agent inventory."],
+    send_message: ["Codex 代理间消息没有已核实的直接映射；按 SDK task 的生命周期重写。", "No verified direct mapping for Codex inter-agent messages; rewrite around the SDK task lifecycle."],
+    followup_task: ["Codex 子代理后续任务没有已核实的直接映射；按 SDK task 的生命周期重写。", "No verified direct mapping for Codex follow-up tasks; rewrite around the SDK task lifecycle."],
+    interrupt_agent: ["Codex 子代理中断没有已核实的直接映射；按 SDK task 的生命周期重写。", "No verified direct mapping for interrupting Codex subagents; rewrite around the SDK task lifecycle."],
+    exec_command: ["需按 SDK shell 工具重写；会话 ID、PTY、超时和审批参数不能原样迁移，shell 可以写入。", "Rewrite for the SDK shell tool; session IDs, PTYs, timeouts, and approval parameters are not portable. Shell can write."],
+    write_stdin: ["Codex 终端会话续写没有已核实的直接映射；按目标 shell 会话接口重写。", "No verified direct mapping for Codex terminal session input; adapt to the target shell-session interface."],
+    apply_patch: ["需按 SDK edit 工具重写；补丁格式、路径约束及审批语义需重新验证。", "Rewrite for the SDK edit tool; revalidate patch format, path constraints, and approval semantics."],
+    update_plan: ["没有已核实的计划工具映射；可用普通进度文本表达，不能直接调用此工具名。", "No verified planning-tool equivalent; use ordinary progress text rather than calling this tool name."],
+    delegate_task: ["改为 task 委派，并声明实际存在的子代理；委派并发等语义需人工复核。", "Use task delegation with declared subagents; review concurrency and delegation semantics manually."],
+    orchestrator_capabilities: ["删除运行时能力探测依赖，明确声明可用子代理及能力。", "Replace runtime capability discovery with explicit available subagents and capabilities."],
+    watch_pull_request: ["可改为经人工启用的 pr_wait 工具；轮询不是事件订阅的等价实现。", "Consider an operator-enabled pr_wait tool; polling is not equivalent to event subscription."],
+    unwatch_pull_request: ["移除订阅取消逻辑；根据新轮询或 GitHub channel 的生命周期重写。", "Rewrite subscription cancellation for the polling or GitHub channel lifecycle."],
+    Monitor: ["需要显式实现监控流程或 GitHub channel；不能直接调用该工具名。", "Implement monitoring or a GitHub channel explicitly; this tool name is not directly available."],
+};
+export function scanForeignTools(body, source) {
+    return Object.entries(REPLACEMENTS).flatMap(([tool, [message, messageEn]]) => (tool === "wait"
+        // "wait" is also ordinary prose; require an explicit tool-like reference.
+        ? /(?:\bfunctions\.wait\b|(?<![A-Za-z0-9_])wait\s*\(|`wait`)/.test(body)
+        : new RegExp(`(?<![A-Za-z0-9_])${tool}(?![A-Za-z0-9_])`).test(body))
+        ? [{ source, field: `$prompt.${tool}`, status: "degraded", message, messageEn }] : []);
+}

package/dist/mapping/model.d.ts

@@ -0,0 +1,5 @@
+import type { ConvertOptions, Finding } from "../ir.js";
+export declare function mapModel(value: unknown, source: string, options: ConvertOptions): {
+    model?: string;
+    finding: Finding;
+};

package/dist/mapping/model.js

@@ -0,0 +1,14 @@
+export function mapModel(value, source, options) {
+    const base = { source, field: "model" };
+    if (value === "inherit")
+        return { finding: { ...base, status: "mapped", message: "已省略 model，继承父代理模型。", messageEn: "Omitted model to inherit the parent model." } };
+    if (typeof value === "string" && Object.hasOwn(options.modelMap, value) && options.modelMap[value])
+        return { model: options.modelMap[value], finding: {
+                ...base, status: "mapped", target: "agent.ts:model", message: "已按 --model-map 显式映射；可用性需用实际账号验证。", messageEn: "Explicitly mapped with --model-map; verify availability with your account.",
+            } };
+    if (typeof value === "string" && value.trim() && options.keepModel)
+        return { model: value, finding: {
+                ...base, status: "degraded", target: "agent.ts:model", message: "按 --keep-model 保留原 ID；validate 不能证明该模型可调用。", messageEn: "Kept the original ID with --keep-model; validate does not prove model availability.",
+            } };
+    return { finding: { ...base, status: "degraded", message: "已省略 model，继承父代理模型；使用 --model-map 显式指定目标模型。", messageEn: "Omitted model to inherit the parent model; use --model-map to select a target model explicitly." } };
+}

package/dist/mapping/names.d.ts

@@ -0,0 +1,2 @@
+export declare function slugName(value: string, fallback: string): string;
+export declare function scriptName(relativePath: string): string;

package/dist/mapping/names.js

@@ -0,0 +1,9 @@
+export function slugName(value, fallback) {
+    const slug = value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^A-Za-z0-9_-]+/g, "-")
+        .replace(/^[^A-Za-z0-9]+|[-_]+$/g, "").slice(0, 96).replace(/[-_]+$/g, "");
+    return slug || fallback;
+}
+export function scriptName(relativePath) {
+    const withoutExtension = relativePath.replace(/\.[^.\/]+$/, "");
+    return slugName(withoutExtension.replace(/[/\\-]+/g, "_"), "script").replace(/-/g, "_");
+}

package/dist/mapping/permissions.d.ts

@@ -0,0 +1,2 @@
+import type { Language, MigrationIR } from "../ir.js";
+export declare function permissionWarning(ir: MigrationIR, lang: Language): string | undefined;

package/dist/mapping/permissions.js

@@ -0,0 +1,21 @@
+export function permissionWarning(ir, lang) {
+    const affected = ir.agents.filter(agent => ["tools", "disallowedTools", "permissionMode"]
+        .some(field => Object.hasOwn(agent.frontmatter, field)));
+    const warnings = [];
+    if (affected.length)
+        warnings.push(lang === "zh"
+            ? `⚠️ 子代理限制未生效（${affected.length} 个）：源 tools / disallowedTools / permissionMode 未迁移。SDK 校验通过不代表只读；--root-tools 只设置根代理白名单。`
+            : `⚠️ Source subagent restrictions are not enforced (${affected.length} affected): tools / disallowedTools / permissionMode were not migrated. SDK validation does not establish read-only access; --root-tools sets only the root allowlist.`);
+    const codex = ir.agents.filter(agent => agent.sourceFormat === "codex" && ["features", "skills", "sandbox_mode", "approval_policy", "sandbox_workspace_write", "permissions"]
+        .some(field => Object.hasOwn(agent.frontmatter, field)));
+    if (codex.length)
+        warnings.push(lang === "zh"
+            ? `⚠️ Codex 权限/能力配置未迁移（${codex.length} 个）：features / skills 限制未生效，父会话权限未导入。SDK 校验通过不代表只读；--root-tools 只设置根代理白名单。`
+            : `⚠️ Codex permission/capability configuration was not migrated (${codex.length} affected): features / skills restrictions are not enforced and parent permissions are not imported. SDK validation does not establish read-only access; --root-tools sets only the root allowlist.`);
+    const policies = new Set(ir.findings.filter(finding => finding.field === "policy" && /[\\/]agents[\\/]openai\.yaml$/.test(finding.source)).map(finding => finding.source));
+    if (policies.size)
+        warnings.push(lang === "zh"
+            ? `⚠️ Codex skill 调用策略未生效（${policies.size} 个）：openai.yaml 的 policy 仅保留为元数据；请人工限制触发流程。`
+            : `⚠️ Codex skill invocation policy is not enforced (${policies.size} affected): openai.yaml policy is retained as metadata only; constrain routing manually.`);
+    return warnings.length ? warnings.join("\n") : undefined;
+}

package/dist/mapping/skill.d.ts

@@ -0,0 +1,3 @@
+import type { ConvertOptions, SkillAsset } from "../ir.js";
+import { type ParsedMarkdown } from "../scan/frontmatter.js";
+export declare function mapSkill(source: string, parsed: ParsedMarkdown, options: ConvertOptions, dependency: boolean): SkillAsset;

package/dist/mapping/skill.js

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { fieldPaths } from "../scan/frontmatter.js";
+import { scanForeignTools } from "./foreign-tools.js";
+import { slugName } from "./names.js";
+export function mapSkill(source, parsed, options, dependency) {
+    const { body, frontmatter } = parsed;
+    const directory = path.dirname(source);
+    const name = typeof frontmatter.name === "string" ? frontmatter.name : path.basename(directory);
+    const id = slugName(name, "skill");
+    const hasDescription = typeof frontmatter.description === "string" && !!frontmatter.description.trim();
+    const description = hasDescription ? frontmatter.description.trim()
+        : options.lang === "zh" ? `当用户要求使用 ${id} 时加载；请补充技能用途。` : `Load when the user requests ${id}; add the skill purpose.`;
+    const findings = fieldPaths(frontmatter).map((field) => {
+        const root = field.split(".")[0];
+        if (root === "name")
+            return { source, field, status: id === frontmatter.name ? "mapped" : "degraded", target: `bot/skills/${id}/SKILL.md`, message: "已统一 skill 目录与 name。", messageEn: "Normalized the skill directory and name." };
+        if (root === "description")
+            return { source, field, status: hasDescription ? "mapped" : "degraded", target: `bot/skills/${id}/SKILL.md`, message: hasDescription ? "已保留技能描述。" : "无效描述已替换为占位描述；请补充触发条件。", messageEn: hasDescription ? "Skill description preserved." : "Invalid description replaced with a placeholder; add triggers." };
+        if (root === "allowed-tools")
+            return { source, field, status: "degraded", message: "原字段保留，但不生成运行时权限限制；请人工审查根代理 tools。", messageEn: "Field preserved but no runtime permission restriction generated; review root tools manually." };
+        return { source, field, status: "mapped", target: `bot/skills/${id}/SKILL.md`, message: "原字段保留在 SKILL.md；仅保证内容保留，不保证 SDK 读取其语义。", messageEn: "Preserved in SKILL.md; content preservation does not imply SDK runtime support." };
+    });
+    if (!("name" in frontmatter))
+        findings.push({ source, field: "name", status: "degraded", message: "缺少 name，已从目录名生成。", messageEn: "Missing name; generated from the directory name." });
+    if (!("description" in frontmatter))
+        findings.push({ source, field: "description", status: "degraded", message: "缺少 description，已生成占位描述。", messageEn: "Missing description; generated a placeholder." });
+    findings.push({ source, field: "$body", status: "mapped", target: `bot/skills/${id}/SKILL.md`, message: "正文原样保留。", messageEn: "Body preserved unchanged." }, ...scanForeignTools(body, source));
+    return { id, source, directory, body, frontmatter: { ...frontmatter, name: id, description }, description, dependency, findings };
+}

package/dist/mapping/subagent.d.ts

@@ -0,0 +1,3 @@
+import type { AgentAsset, ConvertOptions } from "../ir.js";
+import { type ParsedMarkdown } from "../scan/frontmatter.js";
+export declare function mapSubagent(source: string, parsed: ParsedMarkdown, options: ConvertOptions): AgentAsset;

package/dist/mapping/subagent.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+import { fieldPaths } from "../scan/frontmatter.js";
+import { scanForeignTools } from "./foreign-tools.js";
+import { mapModel } from "./model.js";
+import { slugName } from "./names.js";
+import { mapToolNames } from "./tools-names.js";
+export function mapSubagent(source, parsed, options) {
+    const { frontmatter, body } = parsed;
+    const sourceName = typeof frontmatter.name === "string" ? frontmatter.name : path.basename(source, path.extname(source));
+    const id = slugName(sourceName, "agent");
+    const hasDescription = typeof frontmatter.description === "string" && !!frontmatter.description.trim();
+    const description = hasDescription ? frontmatter.description.trim()
+        : options.lang === "zh" ? `迁移的 ${id} 子代理；请补充具体用途和委派时机。` : `Migrated ${id} subagent; describe its purpose and when to delegate.`;
+    const findings = [];
+    let model;
+    const topRules = new Map();
+    for (const field of Object.keys(frontmatter)) {
+        let finding = { source, field, status: "dropped", message: "目标 SDK 无已核实的等价字段；未写入配置，请人工实现其语义。", messageEn: "No verified SDK equivalent; omitted from configuration. Implement its semantics manually." };
+        if (field === "name")
+            finding = { source, field, status: id === frontmatter.name ? "mapped" : "degraded", target: `bot/subagents/${id}/`, message: "用于子代理目录 ID；不合法字符已规范化。", messageEn: "Used as the subagent directory ID; unsupported characters are normalized." };
+        if (field === "description")
+            finding = { source, field, status: hasDescription ? "mapped" : "degraded", target: "agent.ts:description", message: hasDescription ? "已映射为委派描述。" : "原描述无效，已生成占位描述；请补充触发条件。", messageEn: hasDescription ? "Mapped to the delegation description." : "Invalid description replaced with a placeholder; add delegation triggers." };
+        if (field === "model") {
+            const mapped = mapModel(frontmatter.model, source, options);
+            model = mapped.model;
+            finding = mapped.finding;
+        }
+        if (field === "tools" || field === "disallowedTools") {
+            const tools = mapToolNames(frontmatter[field]);
+            const suggestions = tools.mapped.length ? ` (${tools.mapped.join(", ")})` : "";
+            finding = { source, field, status: "degraded", message: `危险：子代理工具限制未生效，task 子代理保留 harness 自己的工具集；不能假定根白名单会约束子代理。工具名参考映射${suggestions}；若必须强制只读，需使用独立代理或禁用 task，并另行约束执行环境；shell 可写入。`, messageEn: `Security boundary lost: task children retain the harness task-tool toolset; do not assume root allowlists constrain them. Reference name mapping${suggestions}. For enforced read-only access use separate agents or disable task and constrain execution separately; shell can write.` };
+            if (tools.unknown.length)
+                finding.message += " 部分工具名无已核实映射。";
+            if (tools.unknown.length)
+                finding.messageEn += " Some tool names have no verified mapping.";
+        }
+        if (field === "permissionMode")
+            finding = { source, field, status: "dropped", message: "Claude 权限模式未迁移。local.sandbox 和 tool 审批不等价，必须人工设置权限。", messageEn: "Claude permission mode was not migrated. local.sandbox and tool approval are not equivalents; configure permissions manually." };
+        if (field === "hooks")
+            finding = { source, field, status: "dropped", message: "未迁移 hooks；SDK 观察型 hook 不能复现 Claude 的拦截语义。", messageEn: "Hooks were not migrated; SDK observer hooks cannot reproduce Claude interception semantics." };
+        if (field === "mcpServers")
+            finding = { source, field, status: "dropped", message: "未创建 MCP connection；请在 bot/mcp-connections/ 人工配置并验证认证。", messageEn: "No MCP connection generated; configure bot/mcp-connections/ and verify authentication manually." };
+        if (field === "skills")
+            finding = { source, field, status: "degraded", message: "子代理不能单独预加载 skill；请一并转换依赖 skill，并明确提示根代理加载。", messageEn: "Per-subagent skill preloading is unavailable; convert dependencies and explicitly instruct the root agent to load them." };
+        if (field === "memory")
+            finding = { source, field, status: "dropped", message: "持久记忆未迁移；ctx.host.kv 需要重新设计数据和生命周期。", messageEn: "Persistent memory was not migrated; ctx.host.kv requires explicit data and lifecycle design." };
+        topRules.set(field, finding);
+    }
+    for (const field of fieldPaths(frontmatter)) {
+        const root = [...topRules.keys()].sort((a, b) => b.length - a.length).find((key) => field === key || field.startsWith(`${key}.`));
+        const rule = topRules.get(root);
+        findings.push({ ...rule, field });
+    }
+    if (!("name" in frontmatter))
+        findings.push({ source, field: "name", status: "degraded", target: `bot/subagents/${id}/`, message: "缺少 name，已从文件名生成 ID。", messageEn: "Missing name; generated the ID from the filename." });
+    if (!("description" in frontmatter))
+        findings.push({ source, field: "description", status: "degraded", target: "agent.ts:description", message: "缺少 description，已生成占位描述；请补充委派时机。", messageEn: "Missing description; generated a placeholder. Add delegation triggers." });
+    findings.push({ source, field: "$body", status: "mapped", target: `bot/subagents/${id}/instructions.md`, message: "正文原样迁移；工具和运行时引用需按下列提示复核。", messageEn: "Body preserved; review tool and runtime references below." }, ...scanForeignTools(body, source));
+    return { id, source, sourceFormat: "claude", body, frontmatter, description, model, findings };
+}

package/dist/mapping/tools-names.d.ts

@@ -0,0 +1,6 @@
+export declare const CLAUDE_TOOL_MAP: Readonly<Record<string, string>>;
+export declare const ROOT_TOOL_NAMES: Set<string>;
+export declare function mapToolNames(value: unknown): {
+    mapped: string[];
+    unknown: string[];
+};

package/dist/mapping/tools-names.js

@@ -0,0 +1,18 @@
+export const CLAUDE_TOOL_MAP = {
+    Read: "read", Grep: "grep", Glob: "glob", Bash: "shell", Edit: "edit", Write: "edit", Agent: "task", Task: "task",
+};
+export const ROOT_TOOL_NAMES = new Set(["read", "grep", "glob", "ls", "shell", "edit", "delete", "task"]);
+export function mapToolNames(value) {
+    const names = typeof value === "string" ? value.split(/[,\s]+/).filter(Boolean)
+        : Array.isArray(value) ? value.filter((name) => typeof name === "string") : [];
+    const mapped = new Set();
+    const unknown = new Set();
+    for (const name of names) {
+        const target = Object.hasOwn(CLAUDE_TOOL_MAP, name) ? CLAUDE_TOOL_MAP[name] : ROOT_TOOL_NAMES.has(name) ? name : undefined;
+        if (target)
+            mapped.add(target);
+        else
+            unknown.add(name);
+    }
+    return { mapped: [...mapped], unknown: [...unknown] };
+}

package/dist/scan/codex.d.ts

@@ -0,0 +1 @@
+export declare function parseCodexAgent(text: string, file: string): Record<string, unknown>;

package/dist/scan/codex.js

@@ -0,0 +1,19 @@
+import { parse } from "smol-toml";
+import { assertNoSensitiveKeys } from "./frontmatter.js";
+export function parseCodexAgent(text, file) {
+    let config;
+    try {
+        config = parse(text.replace(/^\uFEFF/, ""), { maxDepth: 30 });
+    }
+    catch {
+        // TOML parser diagnostics contain source excerpts. Never echo them.
+        throw new Error(`Invalid Codex agent TOML (or nesting exceeds 30 levels): ${file}`);
+    }
+    assertNoSensitiveKeys(config, file);
+    for (const field of ["name", "description", "developer_instructions"]) {
+        if (typeof config[field] !== "string" || !config[field].trim()) {
+            throw new Error(`Codex standalone agents require a non-empty string '${field}': ${file}`);
+        }
+    }
+    return config;
+}

package/dist/scan/frontmatter.d.ts

@@ -0,0 +1,11 @@
+export interface ParsedMarkdown {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export declare function assertNoSensitiveKeys(value: unknown, file: string, prefix?: string, depth?: number, budget?: {
+    fields: number;
+}): void;
+export declare function parseYamlMapping(text: string, file: string): Record<string, unknown>;
+export declare function parseMarkdown(text: string, file: string): ParsedMarkdown;
+/** Includes container keys and nested object keys; arrays retain their index for object entries. */
+export declare function fieldPaths(value: Record<string, unknown>): string[];

package/dist/scan/frontmatter.js

@@ -0,0 +1,62 @@
+import { parseDocument } from "yaml";
+export function assertNoSensitiveKeys(value, file, prefix = "", depth = 0, budget = { fields: 0 }) {
+    if (depth > 30)
+        throw new Error(`Frontmatter nesting exceeds 30 levels: ${file}`);
+    if (!value || typeof value !== "object")
+        return;
+    for (const [key, child] of Object.entries(value)) {
+        if (++budget.fields > 10_000)
+            throw new Error(`Frontmatter exceeds 10000 fields: ${file}`);
+        const field = prefix ? `${prefix}.${key}` : key;
+        if (/(?:^|[_-])(?:password|passwd|token|secret|credential|private[_-]?key|api[_-]?key)(?:$|[_-])/i.test(key)
+            || /^(?:apiKey|accessKey|accessToken|refreshToken|authToken|clientSecret|privateKey|authorization|bearer)$/i.test(key)) {
+            throw new Error(`Sensitive frontmatter field is not permitted (${field}): ${file}`);
+        }
+        assertNoSensitiveKeys(child, file, field, depth + 1, budget);
+    }
+}
+export function parseYamlMapping(text, file) {
+    const doc = parseDocument(text, { uniqueKeys: true, customTags: [], strict: true });
+    // YAML diagnostics may include source text, so never relay their raw messages.
+    if (doc.errors.length || doc.warnings.length)
+        throw new Error(`Invalid YAML frontmatter: ${file}`);
+    let value;
+    try {
+        value = doc.toJS({ maxAliasCount: 0 });
+    }
+    catch {
+        throw new Error(`YAML aliases are not supported: ${file}`);
+    }
+    if (value === null)
+        value = {};
+    if (typeof value !== "object" || Array.isArray(value))
+        throw new Error(`Frontmatter must be a mapping: ${file}`);
+    assertNoSensitiveKeys(value, file);
+    return value;
+}
+export function parseMarkdown(text, file) {
+    const normalized = text.replace(/^\uFEFF/, "");
+    const opening = /^(---)[ \t]*\r?\n/.exec(normalized);
+    if (!opening)
+        return { frontmatter: {}, body: normalized };
+    const rest = normalized.slice(opening[0].length);
+    const closing = /^(?:---|\.\.\.)[ \t]*(?:\r?\n|$)/m.exec(rest);
+    if (!closing)
+        throw new Error(`Unclosed YAML frontmatter: ${file}`);
+    return { frontmatter: parseYamlMapping(rest.slice(0, closing.index), file), body: rest.slice(closing.index + closing[0].length) };
+}
+/** Includes container keys and nested object keys; arrays retain their index for object entries. */
+export function fieldPaths(value) {
+    const result = [];
+    function visit(item, prefix) {
+        if (!item || typeof item !== "object")
+            return;
+        for (const [key, child] of Object.entries(item)) {
+            const field = prefix ? `${prefix}.${key}` : key;
+            result.push(field);
+            visit(child, field);
+        }
+    }
+    visit(value, "");
+    return result;
+}

package/dist/scan/index.d.ts

@@ -0,0 +1,2 @@
+import type { ConvertOptions, MigrationIR } from "../ir.js";
+export declare function scanInputs(inputs: string[], options: ConvertOptions): Promise<MigrationIR>;

package/dist/scan/index.js

@@ -0,0 +1,192 @@
+import path from "node:path";
+import os from "node:os";
+import { lstat, readdir } from "node:fs/promises";
+import { mapSubagent } from "../mapping/subagent.js";
+import { mapCodexAgent } from "../mapping/codex-agent.js";
+import { mapCodexSkillMetadata } from "../mapping/codex-skill.js";
+import { mapSkill } from "../mapping/skill.js";
+import { scriptName } from "../mapping/names.js";
+import { scanForeignTools } from "../mapping/foreign-tools.js";
+import { parseMarkdown, parseYamlMapping } from "./frontmatter.js";
+import { parseCodexAgent } from "./codex.js";
+import { assertSafePath, isSensitiveName, listSafeFiles, MAX_FILES, readSafeText, SKIP_DIRECTORIES } from "./safety.js";
+import { dependencyInfo } from "./tstack.js";
+function expandHome(input) { return input === "~" ? os.homedir() : input.startsWith("~/") ? path.join(os.homedir(), input.slice(2)) : input; }
+async function exists(file) {
+    try {
+        await lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export async function scanInputs(inputs, options) {
+    if (!inputs.length)
+        throw new Error("At least one input is required.");
+    const ir = { agents: [], skills: [], scripts: [], findings: [] };
+    const seen = new Map();
+    const visitedDirectories = new Set();
+    const claimedNames = new Map();
+    let visitedEntries = 0;
+    let assetFiles = 0;
+    function claim(kind, id, source) {
+        const key = `${kind}:${id.toLowerCase()}`;
+        const existing = claimedNames.get(key);
+        if (existing && existing !== source)
+            throw new Error(`Name collision after normalization (${key}): ${existing} and ${source}`);
+        claimedNames.set(key, source);
+    }
+    function addSkipped(file, reason) {
+        ir.findings.push({ source: file, field: "$files", status: "dropped", message: "已跳过生成文件、依赖、缓存、版本管理或敏感路径，未读取其内容。", messageEn: reason });
+    }
+    async function addAgent(file, format) {
+        const source = await assertSafePath(file);
+        if (seen.has(source))
+            return;
+        const text = await readSafeText(source);
+        const asset = format === "codex"
+            ? mapCodexAgent(source, parseCodexAgent(text, source), options)
+            : mapSubagent(source, parseMarkdown(text, source), options);
+        claim("agent", asset.id, source);
+        seen.set(source, "agent");
+        ir.agents.push(asset);
+        ir.findings.push(...asset.findings);
+    }
+    async function addSkill(directory, dependency = false) {
+        const source = await assertSafePath(path.join(directory, "SKILL.md"));
+        const existing = ir.skills.find((skill) => skill.source === source);
+        if (existing) {
+            if (!dependency)
+                existing.dependency = false;
+            return existing;
+        }
+        const asset = mapSkill(source, parseMarkdown(await readSafeText(source), source), options, dependency);
+        claim("skill", asset.id, source);
+        seen.set(source, "skill");
+        ir.skills.push(asset);
+        ir.findings.push(...asset.findings);
+        for (const file of await listSafeFiles(directory, addSkipped)) {
+            if (++assetFiles > MAX_FILES)
+                throw new Error(`Skill assets exceed ${MAX_FILES} files; select narrower inputs.`);
+            const relativePath = path.relative(directory, file).split(path.sep).join("/");
+            if (relativePath === "SKILL.md")
+                continue;
+            if (relativePath.startsWith("scripts/")) {
+                const id = scriptName(relativePath.slice("scripts/".length));
+                claim("script", id, file);
+                ir.scripts.push({ id, source: file, skillId: asset.id, relativePath });
+                ir.findings.push({ source: file, field: "$script", status: "degraded", target: `bot/tools/${id}.ts`, message: "保留原脚本并生成禁用的 JSON 工具存根；需人工实现 stdin/stdout 契约后启用，转换不会执行脚本。", messageEn: "Original script preserved and a disabled JSON tool stub generated; implement its stdin/stdout contract before enabling. Conversion never executes scripts." });
+                if ((await lstat(file)).mode & 0o111)
+                    ir.findings.push({ source: file, field: "$permissions", status: "degraded", message: "原脚本有可执行位；生成项目仅复制文件内容，不保留执行权限。若需直接运行脚本，请审核后恢复权限或显式调用解释器。", messageEn: "The source script is executable. Generated files preserve content but not executable permission; after review, restore permissions or invoke the interpreter explicitly." });
+            }
+            if (relativePath === "agents/openai.yaml") {
+                const metadata = parseYamlMapping(await readSafeText(file), file);
+                const mapped = mapCodexSkillMetadata(file, metadata, asset.id);
+                asset.trigger = mapped.trigger;
+                asset.findings.push(...mapped.findings);
+                ir.findings.push(...mapped.findings);
+            }
+            if (/\.md$/i.test(file))
+                ir.findings.push(...scanForeignTools(await readSafeText(file), file));
+            ir.findings.push({ source: file, field: "$file", status: "mapped", target: `bot/skills/${asset.id}/${relativePath}`, message: "附属文件原样保留；保留文件不代表自动赋予工具能力。", messageEn: "Supporting file preserved unchanged; copying does not make it a callable tool." });
+        }
+        return asset;
+    }
+    async function discover(file, inAgentTree, explicit, depth) {
+        if (depth > 32)
+            throw new Error(`Input nesting exceeds 32 directories: ${file}`);
+        const absolute = await assertSafePath(file);
+        const stat = await lstat(absolute);
+        if (stat.isFile()) {
+            if (path.basename(absolute) === "SKILL.md")
+                await addSkill(path.dirname(absolute));
+            else if (/\.md$/i.test(absolute) && (explicit || (inAgentTree && inAgentTree !== "codex")))
+                await addAgent(absolute, "claude");
+            else if (/\.toml$/i.test(absolute) && (explicit || (inAgentTree && inAgentTree !== "claude"))) {
+                if (path.basename(absolute) === "config.toml" && path.basename(path.dirname(absolute)) === ".codex")
+                    throw new Error(`Session config.toml is not supported; pass standalone Codex agent TOML files with name, description, and developer_instructions: ${absolute}`);
+                await addAgent(absolute, "codex");
+            }
+            else if (explicit)
+                throw new Error(`Expected a Markdown agent, standalone Codex TOML agent, or a skill directory: ${absolute}`);
+            return;
+        }
+        if (!stat.isDirectory())
+            throw new Error(`Special files are not permitted: ${absolute}`);
+        if (visitedDirectories.has(absolute))
+            return;
+        visitedDirectories.add(absolute);
+        if (await exists(path.join(absolute, "SKILL.md"))) {
+            await addSkill(absolute);
+            return;
+        }
+        // Also recognize a directly selected subdirectory such as .codex/agents/review/.
+        const ancestors = absolute.split(path.sep);
+        let agentTree = inAgentTree;
+        for (let index = ancestors.length - 1; index > 0; index--) {
+            if (ancestors[index] !== "agents")
+                continue;
+            if (ancestors[index - 1] === ".codex") {
+                agentTree = "codex";
+                break;
+            }
+            if (ancestors[index - 1] === ".claude") {
+                agentTree = "claude";
+                break;
+            }
+            agentTree ??= "mixed";
+        }
+        for (const entry of (await readdir(absolute, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            const child = path.join(absolute, entry.name);
+            if (++visitedEntries > MAX_FILES)
+                throw new Error(`Scan exceeds ${MAX_FILES} entries; select narrower inputs.`);
+            if (entry.isSymbolicLink())
+                throw new Error(`Symbolic links are not permitted: ${child}`);
+            if (isSensitiveName(entry.name)) {
+                addSkipped(child, "Sensitive path omitted from project discovery without reading it.");
+                continue;
+            }
+            if (entry.isDirectory() && SKIP_DIRECTORIES.has(entry.name)) {
+                addSkipped(child, "Generated, dependency, cache, or version-control directory omitted.");
+                continue;
+            }
+            if (entry.name === "config.toml" && path.basename(absolute) === ".codex") {
+                ir.findings.push({ source: child, field: "$session-config", status: "dropped",
+                    message: "未读取 Codex 父会话配置；仅支持独立子代理 TOML 和 skill 目录。旧式 agents.<name>.config_file 声明未解析。",
+                    messageEn: "Codex parent-session configuration was not read. Only standalone agent TOML and skill directories are supported; legacy agents.<name>.config_file declarations are not resolved." });
+                continue;
+            }
+            if (entry.isDirectory() || /\.md$/i.test(entry.name) || (agentTree && agentTree !== "claude" && /\.toml$/i.test(entry.name)))
+                await discover(child, agentTree, false, depth + 1);
+            else if (!entry.isFile())
+                throw new Error(`Special files are not permitted: ${child}`);
+        }
+    }
+    for (const input of inputs)
+        await discover(expandHome(input), undefined, true, 0);
+    if (options.withDeps) {
+        // The growing queue computes the transitive closure and seen sources break cycles.
+        for (let index = 0; index < ir.skills.length; index++) {
+            const skill = ir.skills[index];
+            const info = await dependencyInfo(skill.directory, skill.id);
+            if (!info.names.length)
+                continue;
+            ir.findings.push({ source: skill.source, field: "$dependencies", status: info.fallback ? "degraded" : "mapped", message: info.fallback ? `按已核实的 tstack 快照补齐同级依赖；源文件未附 README，需确认同名技能的来源。依据：${info.basis}` : `按源 README 补齐同级依赖。依据：${info.basis}`, messageEn: info.fallback ? `Resolved sibling dependencies using the pinned tstack graph; source README unavailable, so verify the provenance of same-named skills. Basis: ${info.basis}` : `Resolved sibling dependencies from the source README. Basis: ${info.basis}` });
+            for (const name of info.names) {
+                const directory = path.join(path.dirname(skill.directory), name);
+                if (!await exists(path.join(directory, "SKILL.md")))
+                    throw new Error(`Missing dependency '${name}' for '${skill.id}': ${directory}`);
+                await addSkill(directory, true);
+            }
+        }
+    }
+    if (!ir.agents.length && !ir.skills.length)
+        throw new Error("No Claude agents, Codex standalone agents, or SKILL.md directories found. Pass agent .md/.toml files explicitly or select .claude/agents or .codex/agents.");
+    ir.agents.sort((a, b) => a.id.localeCompare(b.id));
+    ir.skills.sort((a, b) => a.id.localeCompare(b.id));
+    ir.scripts.sort((a, b) => a.id.localeCompare(b.id));
+    return ir;
+}

package/dist/scan/safety.d.ts

@@ -0,0 +1,11 @@
+export declare const MAX_TEXT_BYTES: number;
+export declare const MAX_ASSET_BYTES: number;
+export declare const MAX_FILES = 5000;
+export declare const SKIP_DIRECTORIES: Set<string>;
+export declare function isSensitiveName(name: string): boolean;
+/** Never resolve a symlink before deciding whether it is safe to read. */
+export declare function assertSafePath(file: string): Promise<string>;
+export declare function readSafeFile(file: string, maxBytes?: number): Promise<Buffer>;
+export declare function readSafeText(file: string, maxBytes?: number): Promise<string>;
+/** Absolute, sorted regular files. Sensitive files fail closed instead of being copied. */
+export declare function listSafeFiles(directory: string, onSkip?: (file: string, reason: string) => void): Promise<string[]>;