AGENTS.md

1. Language

• Always reply in 简体中文。

2. Tool

• Use context7 for public library/API documentation.
• When given GitHub URLs, use gh cli to access it, not web fetch.
• Never use pip to install Python packages; always use uv.
• Search or browser online source code with gh.

3. Rules

• DON'T use package manager (e.g. pacman, apt) to install package unless asked. If needing some package, ask user to install it.
• DO check git status in Git repo before destructive actions (e.g., git restore, checkout, reset --hard).
• DON'T git commit unless asked.
• When git commit, DO use gpg sign; DO follow 3.1. Git Commit Style.
• DON'T write extra unit tests unless asked.
• When updating code per user request, DON'T adding comments that explain the history of the change (e.g., 'Changed A to B'). The final code should look as if it were written that way originally.
• When writing Markdown documentation files, DO use numeric titles (e.g., 1., 1.1., 1.2.1.)
• find or Glob or glob MUST be used with -print0 and xargs must be used with -0 to handle file names with spaces or special characters. MUST use -xdev to avoid descending into slow network filesystems. NEVER find or glob or search files without -xdev.
• DO check image file dimensions before reading them. If any dimension >= 2000, scale it down to < 2000 with convert before reading.
• When starting background processes from bash, always detach stdio: cmd > log 2>&1 < /dev/null &. If combining with && or ;, wrap the background launch in { ...; }, e.g. build && { cmd > log 2>&1 < /dev/null & printf '%s' "$!" > pid; }. Never use bare cmd & or build && cmd &, because inherited stdio or shell precedence can make the tool wait until the background process exits and can write an unreliable PID.

3.1. Git Commit Style

():

Details

shall be one of:

• feat: Implement new features (must be REAL new feature that isn't minor change. If minor, use misc)
• fix: Fix REAL bugs in the code. This means that corrections to documents, spelling, etc., do not count as fixes.
• docs: Changes to documentation (not include translation texts).
• update: Update translation texts.
• upgrade: Upgrade dependency, Flutter SDK version, etc.
• change / misc: Changes to the code that cannot be categorized. For example, modifying the color of a button or adjusting the layout boundaries.
• style: Changes to the code style, such as running the formatting tools, fixing typos, modifying variable names, removing unnecessary whitespace, etc.
• refactor: Refactor the code logic, without adding new features or fixing bugs.
• chore: Changes to the build process or auxiliary tool scripts.
• perf: Improve runtime performance.

is optional and ONLY used if you find historical commits all use it. It should be a noun that describes the area of the codebase that is affected by the change.

shall only describe WHY the changes are needed and WHAT has to be done after this change applies. DON'T describe what the change did plainly.