codex-image-to-eagle

1How It Works & Mechanism

The core is a Node script: it scans the Codex generated image directory, selects images, builds the item_add payload, and writes the image paths and prompts into the Eagle library.

There are two communication pathways to Eagle: by default, it uses a local HTTP loopback endpoint; if an Eagle stdio MCP entry exists in the local Codex configuration, it automatically switches to stdio (spawning a child process).

The HTTP path performs a POST /api/tools/call against a local loopback address, with a JSON request body of {tool, params}.

The stdio path uses child_process.spawn to launch the command defined in the config, passing the host's entire process.env through to the child process (overlaid with any env in the config).

Folder resolution relies on 'exact parent-child paths' rather than just names: it first resolves the root folder upward, then searches for date folders under the root by name+parentId to prevent accidental cross-linking between identically named folders.

Concurrency safety uses local file locks (a lock directory named after a parameter hash under os.tmpdir) to serialize the critical section of 'check folder → create folder'.

Prompts and provenance metadata are written into Eagle's annotation field using a fixed text template, establishing searchable review metadata.

Idempotency and deduplication: if multiple date folders with the same name already exist under the same root folder, it reuses the oldest one and reports duplicates instead of creating a new one.

2Core Capabilities

3External Dependencies

4Recommended Governance & Evidence

5Second-Pass Verification

• [ok] 每条外部依赖的反查 — Node 依赖：脚本 require 仅 fs/path/http/os/child_process，无 node_modules、无 package.json；Eagle 回环端点：DEFAULT_SERVER 常量 + callTool() 的 http.request 两处互证；stdio 子进程：spawn 调用点 + README 的 mcp-proxy.js 示例互证。
• [ok] 是否有被遗漏的网络调用 — 全文件仅 import http 一处，唯一 http.request 出现在 httpRequest()，被 callTool() 以 DEFAULT_SERVER 构造的 hostname/port 使用；无 fetch/https/axios/WebSocket。
• [ok] 凭证读取结论的反例搜索 — process.env 命中集中在配置项（图片目录/服务地址/文件夹 ID/MCP 参数/锁超时），未见读取密钥文件、keychain、.env 或打印敏感值；但 spawn 透传全量 env 确认成立，故归入橙档依据之一。
• [ok] 文件夹安全规则 vs 代码实现 — SKILL 第 1–5 条规则均可在代码定位：fixedFolderId 短路、folder_get(getAllHierarchy/fullDetails)、findFolderByNameAndParent(name+parentId)、folder_create(parentId)、复用最旧（按 createdAt 升序取 matches[0]）。
• [ok] 默认服务地址描述一致性 — SKILL.md/脚本为 127.0.0.1:41596 并说明优先 IPv4 回环的原因；README 写 localhost:41596。二者同端口不同写法，已分别作为独立条目取证，不视为出入。
• [ok] 功能声明与实现相符度 — description 承诺的 save/archive/import/sync + prompt/tags/folders 全部有对应实现（item_add 载荷含 tags/items、annotation、folders）；『不泛化为任意素材库迁移』与代码仅面向 Eagle 相符。
• [ok] dry-run 是否真的不写库 — resolveFolderPath() 在 dryRun 时直接返回伪造的 folder-path 字符串，main() 在 dryRun 分支提前 return，未调用 item_add —— 预览路径无写入，结论成立。

6Verdict & Scenarios