feat(analysis): add filename-guided Claude analysis

Enrich Claude metadata analysis with a lightweight filename hint:
- Prefer source filename from source.originalPath for imported assets
- Fall back to managed asset slug for generated assets
- Filter placeholder names like original.jpg or asset automatically
- Append guidance at runtime, applies to bundled and custom prompts

Treat as soft hint: visible image content takes precedence if filename conflicts.

Co-Authored-By: Hagicode <noreply@hagicode.com>

Author: newbe36524

.gitignore

@@ -11,3 +11,5 @@ library/
 .env.*
 !.env.example
 *.tsbuildinfo
+
+temp/

README.md

@@ -148,6 +148,8 @@ Notes:
 If `IMGBIN_ANALYSIS_PROMPT_PATH` is not set, ImgBin falls back to `prompts/default-analysis-prompt.txt`.
 If `IMGBIN_ANALYSIS_API_MODEL` is empty, ImgBin falls back to `ANTHROPIC_MODEL`.
 
+ImgBin also adds a runtime filename-guidance block to every Claude analysis request. Imported assets prefer the original source filename, generated assets fall back to the managed slug, and placeholder names such as `original.png` or `asset` are ignored. The filename is treated as a soft scene hint only; visible image evidence still wins when they disagree.
+
 ### General runtime
 
 - `IMGBIN_DEFAULT_OUTPUT_DIR`: optional default output root, defaults to `./library`
@@ -206,6 +208,16 @@ imgbin annotate ./library/2026-03/orange-dashboard-hero --overwrite
 
 This is useful after changing `IMGBIN_ANALYSIS_API_MODEL` or updating the analysis prompt.
 
+### Filename-guided analysis
+
+ImgBin now enriches Claude metadata analysis with a lightweight filename hint:
+
+- imported assets prefer the source filename from `source.originalPath`,
+- generated assets fall back to the managed asset slug or directory name, and
+- placeholder names such as `original.jpg` or `asset` are skipped automatically.
+
+This guidance is appended at runtime, so it applies to both the bundled default prompt and any `--analysis-prompt` override. Treat it as a soft hint: if the filename conflicts with the image itself, the visible image content should take precedence.
+
 ### Annotate an existing managed asset
 
 ```bash

hagindex.yml

@@ -0,0 +1,62 @@
+version: "1.0"
+name: "imgbin"
+displayName: "ImgBin"
+description: "CLI 工具 - 图像资源生成、标注和索引工具"
+indexedAt: "2026-03-12"
+generatedBy: "claude-code"
+
+quickRef:
+  catalogs:
+    - id: "entryPoints"
+      title: "入口点"
+      desc: "主要入口点和可执行程序"
+    - id: "configFiles"
+      title: "配置文件"
+      desc: "关键配置文件"
+    - id: "directories"
+      title: "目录结构"
+      desc: "重要目录"
+    - id: "features"
+      title: "功能模块"
+      desc: "主要功能模块"
+
+  entryPoints:
+    - title: "CLI 入口"
+      desc: "ImgBin CLI 主程序"
+      path: "src/cli.ts"
+
+  configFiles:
+    - title: "Package 配置"
+      desc: "NPM 包配置"
+      path: "package.json"
+    - title: "TypeScript 配置"
+      desc: "TypeScript 配置"
+      path: "tsconfig.json"
+
+  directories:
+    - title: "源代码"
+      desc: "源代码目录"
+      path: "src"
+    - title: "Library"
+      desc: "图像资源库"
+      path: "library"
+    - title: "Scripts"
+      desc: "自动化脚本"
+      path: "scripts"
+    - title: "Prompts"
+      desc: "提示词文件"
+      path: "prompts"
+
+  features:
+    - title: "图像生成"
+      desc: "图像资源生成功能"
+      path: "src"
+    - title: "图像标注"
+      desc: "图像元数据标注"
+      path: "src"
+    - title: "图像索引"
+      desc: "图像资源索引管理"
+      path: "library"
+    - title: "缩略图生成"
+      desc: "自动生成图像缩略图"
+      path: "src"

prompts/default-analysis-prompt.txt

@@ -11,4 +11,5 @@ Rules:
 - Use 2 to 8 lowercase kebab-case tags.
 - Keep the title under 80 characters.
 - Keep the description under 200 characters.
+- Filenames may be provided as auxiliary scene clues, but visible image evidence always takes precedence.
 - Do not include markdown fences or extra commentary.

src/__tests__/cli.test.ts

@@ -1,6 +1,9 @@
+import os from 'node:os';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
 import { describe, expect, it, vi } from 'vitest';
 import type { CliRuntime } from '../lib/runtime.js';
-import { buildCli, runCli } from '../cli.js';
+import { buildCli, isExecutedAsScript, runCli } from '../cli.js';
 
 function createRuntimeStub(): CliRuntime {
   return {
@@ -121,4 +124,22 @@ describe('CLI parsing', () => {
       reindex: true
     });
   });
+
+  it('treats a symlinked CLI entrypoint as the executed script', async () => {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'imgbin-cli-test-'));
+    const realScriptPath = path.join(tempDir, 'dist', 'cli.js');
+    const linkPath = path.join(tempDir, 'node_modules', '@hagicode', 'imgbin', 'dist', 'cli.js');
+
+    await fs.mkdir(path.dirname(realScriptPath), { recursive: true });
+    await fs.mkdir(path.dirname(linkPath), { recursive: true });
+    await fs.writeFile(realScriptPath, 'console.log("cli");\n', 'utf8');
+    await fs.symlink(realScriptPath, linkPath);
+
+    try {
+      const result = await isExecutedAsScript(new URL(`file://${realScriptPath}`).href, linkPath);
+      expect(result).toBe(true);
+    } finally {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    }
+  });
 });

src/__tests__/integration.test.ts

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { afterEach, describe, expect, it } from 'vitest';
+import { ClaudeMetadataProvider } from '../providers/claude-metadata-provider.js';
 import { AssetWriter } from '../services/asset-writer.js';
 import { JobRunner } from '../services/job-runner.js';
 import { ManagedAssetScanner } from '../services/managed-asset-scanner.js';
@@ -21,7 +22,7 @@ afterEach(async () => {
 
 function createRunner(options: {
   imageProvider?: FakeImageProvider;
-  visionProvider?: FakeVisionProvider;
+  visionProvider?: FakeVisionProvider | ClaudeMetadataProvider;
   now?: Date;
   defaultAnalysisPromptPath?: string;
 }) {
@@ -45,6 +46,37 @@ function createRunner(options: {
   });
 }
 
+async function createRecordingClaudeProvider(recordedPromptPath: string): Promise<ClaudeMetadataProvider> {
+  const binDir = await createTempDir('imgbin-claude-bin-');
+  cleanupDirs.push(binDir);
+  const scriptPath = path.join(binDir, 'fake-claude.mjs');
+  await fs.writeFile(
+    scriptPath,
+    `#!/usr/bin/env node
+import { promises as fs } from 'node:fs';
+
+const args = process.argv.slice(2);
+const promptIndex = args.indexOf('-p');
+const prompt = promptIndex >= 0 ? args[promptIndex + 1] ?? '' : '';
+const outputPath = ${JSON.stringify(recordedPromptPath)};
+await fs.writeFile(outputPath, prompt, 'utf8');
+
+process.stdout.write(JSON.stringify({
+  title: 'Recorded Claude Title',
+  tags: ['recorded', 'claude'],
+  description: 'Prompt recorder response.'
+}));
+`,
+    'utf8'
+  );
+  await fs.chmod(scriptPath, 0o755);
+  return new ClaudeMetadataProvider({
+    executable: scriptPath,
+    model: 'fake-claude-model',
+    timeoutMs: 5_000
+  });
+}
+
 describe('integration flows', () => {
   it('generates from a docs prompt file, writes metadata, and records prompt provenance', async () => {
     const dir = await createTempDir();
@@ -87,6 +119,8 @@ describe('integration flows', () => {
     expect(metadata.status.recognition).toBe('succeeded');
     expect(metadata.status.thumbnail).toBe('succeeded');
     expect(visionProvider.calls[0]?.prompt.toLowerCase()).toContain('return strict json');
+    expect(visionProvider.calls[0]?.filenameHint).toBe(path.basename(result.assetDir!));
+    expect(visionProvider.calls[0]?.filenameHintSource).toBe('slug');
   });
 
   it('imports a standalone image before analysis and preserves manual metadata on later annotate runs', async () => {
@@ -98,9 +132,10 @@ describe('integration flows', () => {
     await fs.writeFile(sourcePath, await createPngBuffer());
 
     const metadataService = new MetadataService();
+    const visionProvider = new FakeVisionProvider();
     const runner = new JobRunner({
       imageProvider: new FakeImageProvider(),
-      visionProvider: new FakeVisionProvider(),
+      visionProvider,
       assetWriter: new AssetWriter(),
       metadataService,
       thumbnailService: new ThumbnailService(),
@@ -130,6 +165,8 @@ describe('integration flows', () => {
     const metadata = await metadataService.load(imported.assetDir!);
     expect(metadata.source?.type).toBe('imported');
     expect(metadata.source?.originalPath).toBe(sourcePath);
+    expect(visionProvider.calls[0]?.filenameHint).toBe('standalone.png');
+    expect(visionProvider.calls[0]?.filenameHintSource).toBe('source.originalPath');
     metadata.manual = {
       title: 'Manual Title',
       tags: ['manual-tag']
@@ -152,9 +189,10 @@ describe('integration flows', () => {
   it('scans pending assets in the library and retries analysis', async () => {
     const dir = await createTempDir();
     cleanupDirs.push(dir);
+    const visionProvider = new FakeVisionProvider();
     const runner = createRunner({
       imageProvider: new FakeImageProvider(),
-      visionProvider: new FakeVisionProvider()
+      visionProvider
     });
 
     const generated = await runner.generate({
@@ -171,6 +209,8 @@ describe('integration flows', () => {
     expect(generated.success).toBe(true);
     expect(result.success).toBe(true);
     expect(result.total).toBe(1);
+    expect(visionProvider.calls[0]?.filenameHint).toBe('needs-later-analysis');
+    expect(visionProvider.calls[0]?.filenameHintSource).toBe('slug');
     const metadata = JSON.parse(await fs.readFile(path.join(generated.assetDir!, 'metadata.json'), 'utf8')) as { status: { recognition: string } };
     expect(metadata.status.recognition).toBe('succeeded');
   });
@@ -224,6 +264,116 @@ describe('integration flows', () => {
     expect(visionProvider.calls[0]?.promptMetadata.path).toContain('custom-analysis-prompt.txt');
   });
 
+  it('includes imported source filenames in the final Claude request', async () => {
+    const dir = await createTempDir();
+    cleanupDirs.push(dir);
+    const sourceDir = await createTempDir('imgbin-source-');
+    cleanupDirs.push(sourceDir);
+    const sourcePath = path.join(sourceDir, 'launch-hero.png');
+    const recordedPromptPath = path.join(dir, 'claude-imported-prompt.txt');
+    await fs.writeFile(sourcePath, await createPngBuffer());
+
+    const runner = createRunner({
+      visionProvider: await createRecordingClaudeProvider(recordedPromptPath)
+    });
+
+    const result = await runner.annotate({
+      assetPath: sourcePath,
+      importTo: dir,
+      overwrite: false,
+      dryRun: false
+    });
+
+    expect(result.success).toBe(true);
+    const recordedPrompt = await fs.readFile(recordedPromptPath, 'utf8');
+    expect(recordedPrompt).toContain('Filename guidance (soft scene hint):');
+    expect(recordedPrompt).toContain('launch-hero.png');
+    expect(recordedPrompt).toContain('imported source filename');
+    expect(recordedPrompt).toContain('trust the image');
+  });
+
+  it('falls back to the managed slug in the final Claude request when no source filename exists', async () => {
+    const dir = await createTempDir();
+    cleanupDirs.push(dir);
+    const recordedPromptPath = path.join(dir, 'claude-generated-prompt.txt');
+
+    const runner = createRunner({
+      imageProvider: new FakeImageProvider(),
+      visionProvider: await createRecordingClaudeProvider(recordedPromptPath)
+    });
+
+    const result = await runner.generate({
+      prompt: 'orange dashboard hero',
+      output: dir,
+      tags: [],
+      annotate: true,
+      thumbnail: false,
+      dryRun: false
+    });
+
+    expect(result.success).toBe(true);
+    const recordedPrompt = await fs.readFile(recordedPromptPath, 'utf8');
+    expect(recordedPrompt).toContain('Filename guidance (soft scene hint):');
+    expect(recordedPrompt).toContain('orange-dashboard-hero');
+    expect(recordedPrompt).toContain('managed asset slug');
+  });
+
+  it('filters placeholder filename hints out of the final Claude request', async () => {
+    const dir = await createTempDir();
+    cleanupDirs.push(dir);
+    const sourceDir = await createTempDir('imgbin-source-');
+    cleanupDirs.push(sourceDir);
+    const sourcePath = path.join(sourceDir, 'original.png');
+    const recordedPromptPath = path.join(dir, 'claude-placeholder-prompt.txt');
+    await fs.writeFile(sourcePath, await createPngBuffer());
+
+    const runner = createRunner({
+      visionProvider: await createRecordingClaudeProvider(recordedPromptPath)
+    });
+
+    const result = await runner.annotate({
+      assetPath: sourcePath,
+      importTo: dir,
+      slug: 'asset',
+      overwrite: false,
+      dryRun: false
+    });
+
+    expect(result.success).toBe(true);
+    const recordedPrompt = await fs.readFile(recordedPromptPath, 'utf8');
+    expect(recordedPrompt).not.toContain('Filename guidance (soft scene hint):');
+    expect(recordedPrompt).not.toContain('Candidate hint from');
+  });
+
+  it('keeps runtime filename guidance when using a custom analysis prompt', async () => {
+    const dir = await createTempDir();
+    cleanupDirs.push(dir);
+    const recordedPromptPath = path.join(dir, 'claude-custom-prompt.txt');
+
+    const runner = createRunner({
+      imageProvider: new FakeImageProvider(),
+      visionProvider: await createRecordingClaudeProvider(recordedPromptPath)
+    });
+
+    const result = await runner.generate({
+      prompt: 'custom prompt asset',
+      output: dir,
+      slug: 'marketing-hero',
+      tags: [],
+      annotate: true,
+      thumbnail: false,
+      dryRun: false,
+      analysisPromptPath: path.join(fixtureDir, 'custom-analysis-prompt.txt')
+    });
+
+    expect(result.success).toBe(true);
+    const recordedPrompt = await fs.readFile(recordedPromptPath, 'utf8');
+    expect(recordedPrompt).toContain('imported marketing image');
+    expect(recordedPrompt).toContain('Filename guidance (soft scene hint):');
+    expect(recordedPrompt).toContain('marketing-hero');
+    expect(recordedPrompt).toContain('managed asset slug');
+  });
+
   it('searches generated and imported assets through the persisted library index', async () => {
     const dir = await createTempDir();
     cleanupDirs.push(dir);

src/cli.ts

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { realpath } from 'node:fs/promises';
 import { Command, CommanderError } from 'commander';
 import { registerAnnotateCommand } from './commands/annotate.js';
 import { registerBatchCommand } from './commands/batch.js';
@@ -52,7 +55,30 @@ export async function runCli(argv = process.argv, options: RuntimeOptions = {}):
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+export async function isExecutedAsScript(importMetaUrl: string, argv1 = process.argv[1]): Promise<boolean> {
+  if (!argv1) {
+    return false;
+  }
+
+  const [scriptPath, invokedPath] = await Promise.all([
+    resolveExecutionPath(fileURLToPath(importMetaUrl)),
+    resolveExecutionPath(argv1)
+  ]);
+
+  return scriptPath === invokedPath;
+}
+
+async function resolveExecutionPath(targetPath: string): Promise<string> {
+  const resolvedPath = path.resolve(targetPath);
+
+  try {
+    return await realpath(resolvedPath);
+  } catch {
+    return resolvedPath;
+  }
+}
+
+if (await isExecutedAsScript(import.meta.url)) {
   const exitCode = await runCli();
   process.exit(exitCode);
 }