abworks-dev/readme-banner

readme-banner 是做什么的？

Generate dual-theme SVGs with a local CLI; only edit README when the user explicitly requests to insert or update a banner. See the configuration reference for config and specific constraints — do not invent CLI flags or config fields from memory.

Confirm the Scope of Work

1. Determine the absolute path of the target repository. The user's project repository may differ from the readme-banner tool source directory. Read the current working directory and verify against the target project's README / project metadata; the skill directory, tool checkout, and terminal default directory are not automatically the target.
2. If there is ambiguity about the target, ask the user first; do not add a banner to the tool itself just because the current directory happens to be readme-banner. Only generate configuration and images in the tool repository if the user explicitly selects it as the target.
3. Clarify whether it is "only generate assets / preview snippets" or "insert / update a specified README". Without an explicit README editing request, never pass --readme, and do not indirectly write the README via other file editing tools. Confirm the file name; do not automatically rewrite READMEs across all language versions or directories.
4. Check for existing configurations, images, managed blocks, and related uncommitted changes. Preserve unrelated modifications; do not reset, clean, delete old resources, or replace other user documents. Read and reuse existing configurations; overwriting requires additional confirmation — do not habitually use --force.

Choose the Appearance

• preset: Use ascii first; it is the first renderer, not the name of "all themes."
• theme: Choose independently: terminal (green terminal), ocean (blue-cyan), neon (purple-pink), minimal (monochrome). Follow user preference; if unspecified, suggest a short option based on the project's character, but do not invent custom theme IDs.
• Get the title, subtitle, and optional built-in art. Avoid using brand logos unrequested; donut is a non-brand example. Built-in pieces that depend on a live clock are rejected to keep output reproducible — do not bypass this validation.
• ASCII titles are limited to 120 characters and must be fully supported by the selected built-in font; Chinese characters, emoji, and unsupported punctuation must not be silently removed. Ask the user for an alternative English short title if needed; the original text can be placed in a plain tagline of up to 240 characters.
• mixed preserves English case; other fonts convert to uppercase. The upstream 20/60 character limit for URLs does not apply to the local CLI, but 120 characters are not a guarantee of visual quality. Long titles should be shortened, or consider slim / reduced art.
• Animated titles use glint or type; use still when the user requests a static banner. still also freezes built-in art, but the SVG still retains the art's animation frame data, so it does not guarantee a significantly smaller file size.

Use a Reliable CLI Entry Point

Requires Node.js >=22; check the available version first.

Within the Tool Source Checkout

If the task environment already has this tool's source code, use it directly — do not bootstrap the same tool over the network:

1. Run npm install in the tool source directory; prepare will compile TypeScript. Do not install dependencies for the build into the user's target project.
2. Verify the local entry point:

node "/absolute/path/readme-banner/bin/readme-banner.mjs" --help

3. Continue to use the local Node entry point and always pass the explicit target --cwd. Even if the command's working directory is the tool checkout, do not omit target isolation.

Without a Local Checkout

You can use the public repository abworks-dev/readme-banner at the fixed Git tag v0.1.0 as the entry point; this requires Git, network access, and user permission to install / run trusted third-party code:

npx --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner --help

@readme-banner/cli is just a local package name not yet published to npm — do not use npx @readme-banner/cli or invent other npm packages. On installation failure, report the actual error; do not fall back to unknown sources, the latest untagged version, or a remote SVG service.

If EALLOWGIT is reported, do not automatically modify npm global settings. Only if the user has authorized installation/running of this trusted repository and organizational policy permits it, a supporting npm version may use npx --allow-git=root --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner … once. If not authorized, ask first; if restricted by organizational policy, stop. Older npm versions that do not recognize this flag should use the normal command or authorized source installation.

The examples below use the local entry point; for the remote entry point, replace the entire node … prefix with the full npx --yes --package … readme-banner above, without altering the semantics of subsequent arguments.

Execution Flow: init → generate → check

1. Create or Reuse Configuration

node "/absolute/path/readme-banner/bin/readme-banner.mjs" init --cwd "/absolute/path/target-project" --config "banner.config.json" --preset ascii --theme ocean --title "MY PROJECT" --tagline "Build something useful" --art donut --effect glint

• init only creates configuration — it does not produce images or modify README; generate must be run next.
• If configuration already exists, read it first, then apply minimal changes according to the user's intent, or reuse it directly; do not automatically force-rebuild with --force. Omit subtitle or art parameters when they are not needed.
• Font, color, shadow, position, speed, background, etc., are set via supported JSON fields. Read the configuration reference first; do not invent options like init --font.
• Configuration must be JSON; do not create executable configurations, install arbitrary configuration plugins, or fetch/inject user-supplied remote SVGs.

2. Generate Assets (Default Mode)

node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json"

By default writes banner.light.svg and banner.dark.svg to the configured outputDir, and outputs a <picture> snippet. This command should not modify README. If the user only requests assets, stop here; do not secretly insert the snippet into README.

3. Insert Only When Authorized for README Editing

node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json" --readme "README.md"

--readme can only specify an existing .md file. The CLI maintains the block between <!-- readme-banner:start --> and <!-- readme-banner:end -->. Verify that content outside the block remains unchanged. In the same README, even if the complete markers appear inside a code example, they are conservatively treated as duplicate markers — do not insert additional demonstration marker pairs. On marker anomalies, investigate the error; do not delete unrelated text or extend the replacement range. Use actually generated snippets: URLs should be relative to the target README, segment-URI-encoded, alt text should be HTML-escaped, do not piece unescaped HTML yourself.

4. Check Results

# Tasks not authorized for README editing only check images
node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json" --check

# Only check the managed block when the task explicitly involves a specified README
node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json" --readme "README.md" --check

• --check does not write files; missing or outdated assets should fail. Report the reason on failure; do not ignore exit codes or claim an unexecuted check passed.
• Verify both SVGs exist and paths are correct; if a viewing tool is available, check the actual appearance of light/dark themes, long titles, and art. Do not treat successful SVG generation as equivalent to animation playback in all Markdown clients.
• Use generate --json for machine-readable results; metadata can be viewed via presets --json and themes --json.
• On path boundary errors, symlink/hardlink protection errors, confirm the user's target and choose a safe regular file within the root directory; existing files with nlink > 1 are rejected. Do not disable protections or "bypass" by moving files outside the root.

Command and File Safety

• All execution calls explicitly set the correct working directory and pass the target --cwd; do not rely on the agent's runtime default directory.
• Titles, paths, and subtitles are data parameters. Prefer execution APIs that accept parameter arrays; when using a shell, quote/escape each parameter according to that shell's rules. The sample double quotes are only suitable for simple placeholder values and do not defend against all shell interpolation; do not concatenate untrusted input into commands, eval, or unescaped scripts. Windows paths should also be individually quoted.
• Only modify user-authorized configuration, generated assets, and the specified managed block; do not change business code, unrelated documents, or existing user modifications.
• Do not automatically commit, push, create remote repositories, publish releases, upload images, publish npm packages, or trigger other remote publications. These require separate, explicit requests.

Delivery Notes

Provide a brief report: the target repository, selected preset/theme/title, the two generated images, whether README was modified and its location, and the actual check results. When there is no README authorization, explicitly state "README not modified" and may return the generated snippet for the user to choose. List any pending confirmations such as glyph substitutions, overly long titles, or viewer compatibility issues; do not claim tests that were not executed as passed.