diff --git a/.kiro/specs/i18n-readme-tagline-and-assets/design.md b/.kiro/specs/i18n-readme-tagline-and-assets/design.md new file mode 100644 index 00000000..b3061b1b --- /dev/null +++ b/.kiro/specs/i18n-readme-tagline-and-assets/design.md @@ -0,0 +1,222 @@ +# Design Document — i18n-readme-tagline-and-assets + +## Overview + +**Purpose**: Eliminate the remaining Chinese surface text from the project's English-facing entry points (`README.md`, `README-EN.md`, `package.json`, `backend/pyproject.toml`) and replace Chinese-named image assets under `static/image/` with ASCII-only equivalents, so that visitors landing on the GitHub repo or installing the npm package see English-only metadata and so that asset URLs are tooling- and CDN-friendly. + +**Users**: Non-Chinese-reading visitors arriving at the GitHub README, downstream consumers reading `package.json` / `backend/pyproject.toml` metadata, and any tool (CDNs, link-rotters, screenshot-rendering bots) that handles repo asset URLs. + +**Impact**: Documentation surface and static image filenames change; no runtime, API, or pipeline behavior is affected. The Chinese-language entry point (`README-ZH.md`) keeps its Chinese body text but its asset references are updated to point at the renamed files. + +### Goals + +- Replace the Chinese tagline with English on `README.md`, `README-EN.md`, `package.json`, `backend/pyproject.toml`. +- Rename nine Chinese-named assets under `static/image/` to ASCII filenames, preserving byte content. +- Update every `` reference in `README.md`, `README-EN.md`, and `README-ZH.md` to the new ASCII paths. +- Verifiable acceptance: a Chinese-character scan over `README.md` and `README-EN.md` returns zero matches outside the language-switcher line. + +### Non-Goals + +- Translating the body of `README-ZH.md` (Chinese variant by design). +- Changing the Chinese tagline value in `locales/zh.json` (legitimate Chinese locale content). +- Re-encoding or re-cropping any image (rename only). +- Adding a CI guard that enforces ASCII filenames or no-Chinese-in-EN-README (tracked separately as #26). + +## Boundary Commitments + +### This Spec Owns + +- The English-language tagline string used in `README.md`, `README-EN.md`, `package.json`, `backend/pyproject.toml`. +- The ASCII filenames for the nine renamed assets under `static/image/`. +- All `` references inside the three READMEs that point to the renamed files. + +### Out of Boundary + +- Any asset under `static/image/` that already uses an ASCII name (`MiroFish_logo*.jpeg`, `shanda_logo.png`). +- Code-level i18n initiatives (frontend strings, backend logs, agent prompts) — those are owned by sibling i18n specs. +- README content beyond the lines explicitly identified in §"Modified Files". + +### Allowed Dependencies + +- Git (`git mv` for rename-with-history). +- No new project dependencies. + +### Revalidation Triggers + +- Any future change that adds another Chinese-named asset under `static/image/` referenced from a README — the verification scan in this spec must be re-run. +- Any future change to the structure of the language-switcher line — the R4 verification regex tolerance for `[中文文档]` may need adjusting. + +## Architecture + +### Existing Architecture Analysis + +This is a documentation- and asset-rename change. There is no architectural component to extend or replace. The relevant existing patterns to respect: + +- **Per `.claude/rules/file-paths.md`**: shell commands that touch paths with non-ASCII characters must quote the paths. +- **Per `.kiro/steering/structure.md`**: `static/` is the project's image asset root; READMEs reference it via relative paths from repo root. +- **Per `.claude/rules/commits.md`**: Conventional Commits, lowercase, imperative, max 72 chars, no `Co-Authored-By:` watermark. + +### Architecture Pattern & Boundary Map + +No new architecture is introduced. The flow is a one-shot edit: + +```mermaid +flowchart LR + A[Chinese-named
asset files] -->|git mv| B[ASCII-named
asset files] + C[README.md / README-EN.md /
README-ZH.md / package.json /
backend/pyproject.toml] -->|Edit tool| D[Updated text +
updated img src paths] + B --> D + D --> E[Verify: rg Chinese-char scan
returns only language-switcher line] +``` + +### Technology Stack + +| Layer | Choice / Version | Role in Feature | Notes | +|-------|------------------|-----------------|-------| +| Frontend / CLI | — | n/a | No code changes. | +| Backend / Services | — | n/a | No code changes. | +| Data / Storage | — | n/a | No data model changes. | +| Messaging / Events | — | n/a | n/a | +| Infrastructure / Runtime | git ≥ 2.x | `git mv` for renames | Already a project prerequisite. | +| Documentation | Markdown / HTML-in-MD | Edit READMEs, `package.json`, `backend/pyproject.toml` | No new tooling. | + +## File Structure Plan + +### Directory Structure + +No new files or directories are created. The existing layout is preserved: + +``` +static/image/ +├── MiroFish_logo.jpeg (unchanged) +├── MiroFish_logo_compressed.jpeg (unchanged) +├── shanda_logo.png (unchanged) +├── qq-group.png (renamed from "QQ群.png") +├── wuhan-university-simulation-cover.png (renamed from "武大模拟演示封面.png") +├── dream-of-the-red-chamber-simulation-cover.jpg (renamed from "红楼梦模拟推演封面.jpg") +└── Screenshot/ + ├── screenshot1.png (renamed from "运行截图1.png") + ├── screenshot2.png (renamed from "运行截图2.png") + ├── screenshot3.png (renamed from "运行截图3.png") + ├── screenshot4.png (renamed from "运行截图4.png") + ├── screenshot5.png (renamed from "运行截图5.png") + └── screenshot6.png (renamed from "运行截图6.png") +``` + +### Modified Files + +- `README.md` + - Lines 7–8: delete the Chinese tagline line and the `
` separator; the existing `` line on (former) line 9 becomes the lone tagline. + - Lines 52, 53, 56, 57, 60, 61: replace `Screenshot/运行截图{N}.png` with `Screenshot/screenshot{N}.png`. + - Line 71: replace `武大模拟演示封面.png` with `wuhan-university-simulation-cover.png`. + - Line 79: replace `红楼梦模拟推演封面.jpg` with `dream-of-the-red-chamber-simulation-cover.jpg`. + - Line 220: replace `QQ群.png` with `qq-group.png`. +- `README-EN.md` — identical edit set as `README.md`. +- `README-ZH.md` + - Lines 52, 53, 56, 57, 60, 61, 71, 79, 220: same nine `` replacements as above. Tagline and Chinese body text unchanged. +- `package.json` + - Line 4: replace the `description` value with `MiroFish - A Simple and Universal Swarm Intelligence Engine, Predicting Anything`. +- `backend/pyproject.toml` + - Line 4: replace the `description` value with `MiroFish - A Simple and Universal Swarm Intelligence Engine, Predicting Anything`. + +### Renamed Files (via `git mv`) + +| Old (quoted) | New | +|---|---| +| `"static/image/QQ群.png"` | `static/image/qq-group.png` | +| `"static/image/武大模拟演示封面.png"` | `static/image/wuhan-university-simulation-cover.png` | +| `"static/image/红楼梦模拟推演封面.jpg"` | `static/image/dream-of-the-red-chamber-simulation-cover.jpg` | +| `"static/image/Screenshot/运行截图1.png"` | `static/image/Screenshot/screenshot1.png` | +| `"static/image/Screenshot/运行截图2.png"` | `static/image/Screenshot/screenshot2.png` | +| `"static/image/Screenshot/运行截图3.png"` | `static/image/Screenshot/screenshot3.png` | +| `"static/image/Screenshot/运行截图4.png"` | `static/image/Screenshot/screenshot4.png` | +| `"static/image/Screenshot/运行截图5.png"` | `static/image/Screenshot/screenshot5.png` | +| `"static/image/Screenshot/运行截图6.png"` | `static/image/Screenshot/screenshot6.png` | + +## System Flows + +Not applicable. No runtime flows are introduced or changed. + +## Requirements Traceability + +| Requirement | Summary | Components | Interfaces | Flows | +|-------------|---------|------------|------------|-------| +| 1.1 | English tagline in README.md | README.md L7–9 edit | n/a | n/a | +| 1.2 | English tagline in README-EN.md | README-EN.md L7–9 edit | n/a | n/a | +| 1.3 | English description in package.json | package.json L4 edit | n/a | n/a | +| 1.4 | English description in backend/pyproject.toml | backend/pyproject.toml L4 edit | n/a | n/a | +| 1.5 | README-ZH.md tagline preserved | README-ZH.md (no L7 edit) | n/a | n/a | +| 2.1 | Rename screenshot{1..6} | `git mv` of six files | n/a | n/a | +| 2.2 | Rename Wuhan video cover | `git mv` of one file | n/a | n/a | +| 2.3 | Rename Red Chamber video cover | `git mv` of one file | n/a | n/a | +| 2.4 | Rename QQ group image | `git mv` of one file | n/a | n/a | +| 2.5 | Byte-preserving rename | `git mv` mechanism choice | n/a | n/a | +| 2.6 | No duplicate copies | `git mv` (atomic rename) + `git status` verification | n/a | n/a | +| 3.1 | README.md image references updated | README.md L52–61, 71, 79, 220 edits | n/a | n/a | +| 3.2 | README-EN.md image references updated | README-EN.md L52–61, 71, 79, 220 edits | n/a | n/a | +| 3.3 | README-ZH.md image references updated | README-ZH.md L52–61, 71, 79, 220 edits | n/a | n/a | +| 3.4 | No broken images on render | Post-edit verification step | n/a | n/a | +| 4.1 | No Chinese chars in README.md body (excl. switcher) | Verification scan | n/a | n/a | +| 4.2 | No Chinese chars in README-EN.md body (excl. switcher) | Verification scan | n/a | n/a | +| 4.3 | Reviewer-runnable scan returns zero matches | `rg` command in design + commit message | n/a | n/a | + +## Components and Interfaces + +This spec has no software components, services, or APIs. The "components" reduce to two textual operations (translate + rename) and one verification. + +| Operation | Layer | Intent | Req Coverage | Key Dependencies | Contracts | +|-----------|-------|--------|--------------|------------------|-----------| +| Tagline translation | Docs / Metadata | Replace Chinese tagline with English in 4 files | 1.1, 1.2, 1.3, 1.4 | Edit tool | n/a | +| Asset rename + reference update | Static assets / Docs | Rename 9 files; update `` in 3 READMEs | 2.1–2.6, 3.1–3.4 | `git mv`, Edit tool | n/a | +| Verification scan | Acceptance gate | Confirm no residual Chinese in EN READMEs body | 4.1, 4.2, 4.3 | ripgrep | Commit message records the scan command and result | + +### Verification Contract + +The acceptance gate is a single ripgrep invocation, runnable by any reviewer: + +``` +rg --pcre2 '[\x{4e00}-\x{9fff}]' README.md README-EN.md \ + | rg -v 'README-ZH\.md' +``` + +**Preconditions**: All edits and renames committed. +**Postconditions**: The pipeline returns zero lines (the only Chinese characters left are in `[中文文档](./README-ZH.md)`, which the second `rg` filters out by matching the `README-ZH.md` substring on the same line). +**Invariants**: `README-ZH.md` body is not modified by this scan logic; the language-switcher line in the EN READMEs is the sole expected exemption. + +## Data Models + +Not applicable. No data structures are added or modified. + +## Error Handling + +### Error Strategy + +Failure modes are limited to (a) a `git mv` failing because a path was mistyped (immediately visible at command-execution time) and (b) a `` left pointing at an old Chinese-named filename (caught by the verification scan). + +### Error Categories and Responses + +- **Mistyped rename target**: `git mv` fails with a clear error; re-run with the correct path. +- **Missed reference update**: Verification scan returns the offending file/line; fix and re-scan. +- **Accidental binary re-encoding**: `git diff --stat` of the asset file shows non-zero content delta; abandon the change and redo with `git mv`. + +### Monitoring + +Not applicable for a one-shot docs change. The PR diff plus the verification-scan output in the PR description serve as the audit trail. + +## Testing Strategy + +This is a documentation/asset change with no executable code. Testing is review-time: + +- **Verification scan (mandatory)**: Run the ripgrep command in §"Verification Contract" against the working tree before commit; expect zero output. Re-run once more in CI / on the PR branch. +- **Rendered-preview check (mandatory)**: Open `README.md`, `README-EN.md`, `README-ZH.md` in GitHub's rendered-markdown view (or a local Markdown previewer) on the feature branch and confirm: + 1. The tagline appears once, in English, on `README.md` and `README-EN.md`. + 2. All six screenshot tiles render. + 3. Both video-cover thumbnails render. + 4. The QQ group image renders. + 5. `README-ZH.md` still renders identically except for the new ASCII image URLs. +- **`git diff --stat` check (mandatory)**: For each of the nine asset files, the stat must show `0 insertions(+), 0 deletions(-)` (pure rename). If any asset shows a content delta, the rename was performed incorrectly. + +## Optional Sections + +### Migration Strategy + +No data migration. The "migration" is a single PR containing all renames + edits. There is no rollback step beyond a normal `git revert` of the merge commit if a broken image is reported post-merge. diff --git a/.kiro/specs/i18n-readme-tagline-and-assets/gap-analysis.md b/.kiro/specs/i18n-readme-tagline-and-assets/gap-analysis.md new file mode 100644 index 00000000..18f4dd9f --- /dev/null +++ b/.kiro/specs/i18n-readme-tagline-and-assets/gap-analysis.md @@ -0,0 +1,131 @@ +# Gap Analysis — i18n-readme-tagline-and-assets + +## 1. Current State Investigation + +### Scope ground truth + +Ripgrep `[\x{4e00}-\x{9fff}]` over `README.md`, `README-EN.md`, `package.json`, and `backend/pyproject.toml` returns the following Chinese-character lines that fall under this feature's mandate: + +| File | Line | Content (excerpt) | Category | +| --- | ---: | --- | --- | +| `README.md` | 7 | `简洁通用的群体智能引擎,预测万物` | Tagline | +| `README.md` | 23 | `[English](./README.md) \| [中文文档](./README-ZH.md)` | Language switcher (allowed) | +| `README.md` | 52–61 | `./static/image/Screenshot/运行截图{1..6}.png` (×6) | Asset path | +| `README.md` | 71 | `./static/image/武大模拟演示封面.png` | Asset path | +| `README.md` | 79 | `./static/image/红楼梦模拟推演封面.jpg` | Asset path | +| `README.md` | 220 | `./static/image/QQ群.png` | Asset path (not listed in ticket scope, see Gap §3) | +| `README-EN.md` | 7, 23, 52–61, 71, 79, 220 | identical structure to README.md | Same categories | +| `package.json` | 4 | `"description": "MiroFish - 简洁通用的群体智能引擎,预测万物"` | Tagline | +| `backend/pyproject.toml` | 4 | `description = "MiroFish - 简洁通用的群体智能引擎,预测万物"` | Tagline (twin string, not in original ticket) | + +`README-ZH.md` carries Chinese body text by design (out of scope) but its asset paths must still be updated to point at the renamed ASCII files. + +### Tracked image files (`git ls-files static/image/`) + +``` +static/image/MiroFish_logo.jpeg +static/image/MiroFish_logo_compressed.jpeg +static/image/QQ群.png +static/image/Screenshot/运行截图{1..6}.png +static/image/shanda_logo.png +static/image/武大模拟演示封面.png +static/image/红楼梦模拟推演封面.jpg +``` + +Nine files have Chinese names: six screenshots + `QQ群.png` + `武大模拟演示封面.png` + `红楼梦模拟推演封面.jpg`. + +### Tagline structure observation + +`README.md` lines 7–9 currently read: + +``` +简洁通用的群体智能引擎,预测万物 +
+A Simple and Universal Swarm Intelligence Engine, Predicting Anything +``` + +The English equivalent already exists immediately below the Chinese as italic subtitle. Naive replacement would produce a duplicate (English in plain text + the same English in italic). The natural i18n collapse is to delete the Chinese line plus the `
` separator and let the existing `` line stand alone. `README-EN.md` has the identical structure. + +### Conventions to respect (from steering) + +- `tech.md`: 4-space indent, no enforced linter, "match the surrounding file's style". Shell scripts must quote paths with spaces / non-ASCII characters per `.claude/rules/file-paths.md`. +- `commits.md`: Conventional Commits, lowercase, imperative, max 72 chars, no `Co-Authored-By:` footer. Branch `/-` — ticket dictates `chore/i18n-12-readme-tagline-and-assets` (or similar). +- `dev-guidelines.md`: kebab-case filenames for assets is consistent with the project's frontend file conventions. + +### Existing precedent in the same i18n epic + +Recently merged child issues of epic #11 (`#7`, `#9`, `#3`, `#5`, `#6`) have all been small, focused docs/tooling PRs. This is consistent with treating #12 as an S-effort docs cleanup. + +## 2. Requirements Feasibility Analysis + +### Per-requirement asset map + +| Req | What it needs | Where it lives | Gap | +| --- | --- | --- | --- | +| R1 (tagline) | English tagline | `README.md:7-9`, `README-EN.md:7-9`, `package.json:4`, `backend/pyproject.toml:4` | **Editorial** — straight string edit. No code paths affected. | +| R2 (asset rename) | Rename 8 files (6 screenshots + 2 video covers) | `static/image/Screenshot/`, `static/image/` | **`git mv`** — preserves history. No callers outside READMEs found by grep. | +| R3 (README references updated) | Update `` paths | `README.md`, `README-EN.md`, `README-ZH.md` | **Editorial** — straight string edits. | +| R4 (no residual Chinese in EN READMEs) | Verifiable scan | Both `README.md` and `README-EN.md` | **Constraint surfaces extra asset** — `QQ群.png` (line 220) is not in the explicit ticket asset list but its src path contains Chinese, which would fail R4's verification. See Gap §3. | + +### Gaps tagged + +- **Constraint:** `static/image/QQ群.png` is referenced by all three READMEs but is **not explicitly listed in the ticket's scope bullets**, while the ticket's own acceptance criterion ("No Chinese characters in `README.md`, `README-EN.md` body text") would still flag its src path. Either we (a) expand scope to rename it as well or (b) accept a deviation. Recommendation: expand scope — same shape of fix, trivial cost, satisfies the literal acceptance criterion. +- **Constraint:** `backend/pyproject.toml:4` carries the identical Chinese tagline string as `package.json:4`. Not in original ticket bullets but is the obvious twin and would surprise a reviewer reading the diff. Already incorporated into requirements.md R1 acceptance criterion 4. +- **Unknown / Research Needed (minor):** Confirm GitHub Pages, the live demo site, and any external link to the screenshots do not deep-link into Chinese-named asset URLs. Quick `gh` / web check during design phase will resolve. + +## 3. Implementation Approach Options + +This is a docs/asset-rename feature. There is no algorithm to design — the only real decision is whether the renames go through `git mv` (preserves history) or `git rm`/`git add` (loses history). And whether to expand scope to `QQ群.png`. + +### Option A — Strict ticket scope (no QQ群.png rename) + +- Rename only the eight assets explicitly listed: `运行截图{1..6}.png`, `武大模拟演示封面.png`, `红楼梦模拟推演封面.jpg`. +- Translate taglines in `README.md`, `README-EN.md`, `package.json`, `backend/pyproject.toml`. +- Skip `QQ群.png`. + +**Trade-offs:** +- ✅ Smallest possible diff; no scope creep. +- ❌ Acceptance criterion R4 ("no Chinese characters in README body outside language switcher") fails because line 220 still contains `QQ群` in the src path. + +### Option B — Expanded scope including QQ群.png (RECOMMENDED) + +- Same as Option A, plus rename `static/image/QQ群.png` → `static/image/qq-group.png` (or similar) and update its three references. + +**Trade-offs:** +- ✅ Satisfies the ticket's own R4 acceptance criterion literally. +- ✅ One additional `git mv` + 3 string edits — negligible cost. +- ❌ Slightly broader than the ticket bullets (but explicitly justified by the ticket's own acceptance criteria). + +### Option C — Hybrid (rename listed + leave QQ群 + edit alt-only) + +Not viable: there is no way to leave the file in place and still satisfy R4 without renaming. + +### Decision direction + +Recommend Option B. Update requirements R2/R3 to include `QQ群.png` explicitly so the spec is internally consistent with R4. + +## 4. Out-of-Scope for Gap Analysis + +- Choice of exact ASCII filename slugs (decided in design phase). +- Whether to re-encode any image (No — bytes-preserving rename only, per R2.4). + +## 5. Implementation Complexity & Risk + +- **Effort:** **S (≈ half-day).** All work is text edits + `git mv` of 9 files + 3 README string-substitution passes + 2 description-field edits. No code changes, no tests. +- **Risk:** **Low.** Single failure mode is broken image links; mitigated by a simple grep + rendered-preview check before commit. No runtime, dependency, or pipeline impact. `git mv` preserves history. + +## 6. Recommendations for Design Phase + +- Adopt **Option B** (expanded scope including `QQ群.png`). +- Use `git mv` for all renames so history follows. +- Pick deterministic ASCII slugs; propose: + - `Screenshot/screenshot{1..6}.png` + - `wuhan-university-simulation-cover.png` + - `dream-of-the-red-chamber-simulation-cover.jpg` + - `qq-group.png` +- Collapse the duplicated tagline lines in `README.md` / `README-EN.md`: delete the Chinese line + `
` separator and let the existing `` English subtitle become the lone tagline (avoids a verbatim-duplicate line). +- Verification step: re-run `rg '[\x{4e00}-\x{9fff}]' README.md README-EN.md package.json backend/pyproject.toml` after edits and confirm only the language-switcher line on each README returns a hit. + +## Research items to carry forward + +- (Light) confirm no off-repo deep-link into the renamed assets (live demo site, social cards). If a deep link is found, decide whether to leave a redirect / note in the PR. diff --git a/.kiro/specs/i18n-readme-tagline-and-assets/requirements.md b/.kiro/specs/i18n-readme-tagline-and-assets/requirements.md new file mode 100644 index 00000000..761c952e --- /dev/null +++ b/.kiro/specs/i18n-readme-tagline-and-assets/requirements.md @@ -0,0 +1,65 @@ +# Requirements Document + +## Project Description (Input) +Translate the Chinese tagline in README.md, README-EN.md, and package.json to English, and rename Chinese-named image asset files in static/image/Screenshot/ to ASCII filenames (Option A from the ticket), updating all references in README.md and README-ZH.md. Acceptance: no Chinese characters in README.md or README-EN.md body text (except the language switcher link to README-ZH.md); package.json description in English; all image links work. Source: GitHub issue #12 (.ticket/12.md). + +## Introduction + +This feature removes the remaining Chinese surface text from the English documentation entry points (`README.md`, `README-EN.md`) and from the npm package metadata (`package.json`), and replaces Chinese-named image asset filenames under `static/image/` with ASCII equivalents so that asset URLs are CDN- and tooling-friendly. References to those assets are updated in all three READMEs (`README.md`, `README-EN.md`, `README-ZH.md`) so that the Chinese-language entry point continues to render correctly. The Chinese-language README (`README-ZH.md`) keeps its Chinese body text by design. + +## Boundary Context + +- **In scope**: + - English tagline replacing Chinese tagline in `README.md`, `README-EN.md`, and `package.json` `description`. + - Renaming `static/image/Screenshot/运行截图{1..6}.png` to ASCII filenames. + - Renaming `static/image/武大模拟演示封面.png` and `static/image/红楼梦模拟推演封面.jpg` to ASCII filenames. + - Renaming `static/image/QQ群.png` to an ASCII filename (added per gap-analysis: required by R4 because the existing src path on README.md:220 / README-EN.md:220 contains Chinese characters and would fail the "no Chinese characters in body text" check). + - Updating all `` references to those renamed files in `README.md`, `README-EN.md`, and `README-ZH.md`. + - Updating `backend/pyproject.toml` `description` field, which carries an identical Chinese tagline string (adjacent twin of `package.json`). +- **Out of scope**: + - Translating the body of `README-ZH.md` (Chinese variant by design). + - Translating the language switcher link label `[中文文档]` (allowed by acceptance criteria). + - Touching `locales/zh.json` Chinese tagline value (legitimate Chinese locale content). +- **Adjacent expectations**: + - The ticket recommends Option A (rename to ASCII). This spec adopts Option A. + - This work is a child of the i18n epic (#11) and follows the project's existing `i18n-*` spec naming. + +## Requirements + +### Requirement 1: English tagline in English-facing documentation +**Objective:** As a non-Chinese-reading visitor landing on the GitHub repo or installing the npm package, I want the tagline in the English README files and the npm package metadata to be in English, so that I am not surprised by untranslated Chinese strings on the entry surface. + +#### Acceptance Criteria +1. The README.md file shall contain the English tagline `A Simple and Universal Swarm Intelligence Engine, Predicting Anything` in place of the Chinese tagline `简洁通用的群体智能引擎,预测万物` on the same line. +2. The README-EN.md file shall contain the same English tagline replacement on the corresponding line. +3. The package.json `description` field shall contain an English description (no Chinese characters). +4. The backend/pyproject.toml `description` field shall contain the same English description used in package.json. +5. The README-ZH.md file shall keep its Chinese tagline unchanged. + +### Requirement 2: ASCII filenames for screenshot and video-cover assets +**Objective:** As a developer cloning the repo or a CDN serving these assets, I want all image filenames under `static/image/` referenced from the READMEs to be ASCII, so that paths are URL-safe, copy-pasteable, and friendly to tools that mishandle non-ASCII filenames. + +#### Acceptance Criteria +1. The `static/image/Screenshot/运行截图{N}.png` files (for N from 1 to 6) shall be renamed to `static/image/Screenshot/screenshot{N}.png`. +2. The `static/image/武大模拟演示封面.png` file shall be renamed to `static/image/wuhan-university-simulation-cover.png`. +3. The `static/image/红楼梦模拟推演封面.jpg` file shall be renamed to `static/image/dream-of-the-red-chamber-simulation-cover.jpg`. +4. The `static/image/QQ群.png` file shall be renamed to `static/image/qq-group.png`. +5. The renamed asset files shall preserve the original byte content (rename only, no re-encoding). +6. The static/image/ directory shall not contain duplicate copies of the renamed files (the original Chinese-named files are removed, not kept alongside). + +### Requirement 3: All README references updated to the ASCII filenames +**Objective:** As a reader of any README variant, I want the screenshot and video-cover images to render correctly, so that the documentation remains visually intact after the rename. + +#### Acceptance Criteria +1. The README.md file shall reference each renamed image at its new ASCII path; no `` in the file shall point to a Chinese-named file under `static/image/`. +2. The README-EN.md file shall reference each renamed image at its new ASCII path; no `` in the file shall point to a Chinese-named file under `static/image/`. +3. The README-ZH.md file shall reference each renamed image at its new ASCII path; no `` in the file shall point to a Chinese-named file under `static/image/`. +4. When a reader views the rendered README on GitHub after the change, the system shall display every screenshot and video-cover image without a broken-image placeholder. + +### Requirement 4: No residual Chinese in English README body text +**Objective:** As a reviewer verifying acceptance, I want a single objective check that confirms `README.md` and `README-EN.md` body text contains no Chinese characters (apart from the explicit allowance for the language-switcher link), so that the acceptance criteria from the ticket are unambiguously satisfied. + +#### Acceptance Criteria +1. The README.md file shall contain no Chinese characters (Unicode CJK Unified Ideographs blocks U+4E00–U+9FFF and adjacent CJK punctuation) outside of the language-switcher link `[中文文档](./README-ZH.md)`. +2. The README-EN.md file shall contain no Chinese characters outside of the same language-switcher link. +3. If a reviewer runs a Chinese-character scan over `README.md` and `README-EN.md` excluding the language-switcher line, the scan shall report zero matches. diff --git a/.kiro/specs/i18n-readme-tagline-and-assets/research.md b/.kiro/specs/i18n-readme-tagline-and-assets/research.md new file mode 100644 index 00000000..4f784d32 --- /dev/null +++ b/.kiro/specs/i18n-readme-tagline-and-assets/research.md @@ -0,0 +1,107 @@ +# Research & Design Decisions — i18n-readme-tagline-and-assets + +## Summary +- **Feature**: `i18n-readme-tagline-and-assets` +- **Discovery Scope**: Simple Addition (docs cleanup + asset rename, no runtime code paths) +- **Key Findings**: + - The duplicate Chinese-tagline / English-`` structure on lines 7–9 of `README.md` and `README-EN.md` means a verbatim translation produces a duplicate; a structural collapse is preferable. + - `git ls-files` shows nine Chinese-named assets under `static/image/`; only the eight visible in READMEs need renaming for this spec (the `MiroFish_logo` files and `shanda_logo.png` already use ASCII names). + - `backend/pyproject.toml:4` is a twin of `package.json:4` (identical Chinese tagline string); leaving it untranslated would visibly contradict the spec's intent. + +## Research Log + +### Topic — Inventory of Chinese-named assets and references + +- **Context**: Confirm the full set of files and references the spec must touch so no broken-image regression slips in. +- **Sources Consulted**: `git ls-files static/image/`, `rg '[\x{4e00}-\x{9fff}]'` over `README.md`, `README-EN.md`, `README-ZH.md`, `package.json`, `backend/pyproject.toml`. +- **Findings**: + - Tracked Chinese-named files (9): `QQ群.png`, six `Screenshot/运行截图{N}.png`, `武大模拟演示封面.png`, `红楼梦模拟推演封面.jpg`. + - Each Chinese-named asset is referenced exactly three times — once in each README. No code path or test references them. + - `locales/zh.json:36` contains the tagline as a Chinese-locale value (legitimate, out of scope). +- **Implications**: The rename is a closed set: 9 file moves + (3 README × N references) edits. No runtime impact. + +### Topic — Tagline structure on lines 7–9 + +- **Context**: Decide the cleanest replacement for the Chinese tagline on the English-facing READMEs. +- **Sources Consulted**: `README.md:7-9`, `README-EN.md:7-9`. +- **Findings**: The current structure is `\n
\nEnglish equivalent`. The English subtitle already exists. Naive replacement (substitute Chinese with English on line 7) produces `\n
\nEnglish` — visible duplicate. +- **Implications**: Collapse to the single existing `` line by deleting the Chinese tagline line and the `
` separator on both files. + +### Topic — `git mv` vs. `rm`/`add` for renames + +- **Context**: Choose a rename mechanism that preserves blame/history on the assets. +- **Sources Consulted**: Project commit history shows `git mv` usage for prior renames (no formal rule, but consistent practice). +- **Findings**: `git mv "old" "new"` records a rename in the index. Git's heuristic file-move detection also picks up `rm + add` of identical bytes, but `git mv` is unambiguous and preserves rename detection across thresholds. +- **Implications**: Use `git mv` for all nine renames. Quote source paths (rule from `.claude/rules/file-paths.md`) since they contain non-ASCII characters. + +### Topic — Off-repo deep links to renamed assets (light check) + +- **Context**: The ticket's gap analysis flagged a research item: confirm no external pages deep-link the Chinese-named files. +- **Sources Consulted**: `git grep` of repo (no off-repo references). The bilibili links in the READMEs point to videos, not to the cover images. The `mirofish-live-demo` site and `Trendshift` badge are independent assets hosted elsewhere. +- **Findings**: No in-repo references outside the READMEs. Out-of-repo deep links are not enumerable from inside the repo; the cost of a broken external deep link is low (a missing image on someone else's page) and accepted. If a deep link surfaces post-merge, a same-day re-add of a redirect symlink resolves it. +- **Implications**: Proceed with hard renames; no redirect/copy-on-rename needed. + +## Architecture Pattern Evaluation + +| Option | Description | Strengths | Risks / Limitations | Notes | +|--------|-------------|-----------|---------------------|-------| +| Strict ticket scope | Rename only the 8 explicitly listed assets; leave `QQ群.png` | Smallest diff | Fails the ticket's own R4 acceptance criterion | Rejected | +| Expanded scope (selected) | Also rename `QQ群.png` and update `backend/pyproject.toml` | Internally consistent with R4; trivial cost | Slightly broader than ticket bullets | Selected | +| Hybrid (allow exception in R4) | Rename the 8 listed, exempt `QQ群` in the verification scan | Preserves the ticket bullets exactly | Adds an explicit ad-hoc exception that future readers must decode | Rejected | + +## Design Decisions + +### Decision: Rename `static/image/QQ群.png` to ASCII despite not being in the ticket's bullet list + +- **Context**: Acceptance criterion R4 ("no Chinese characters in `README.md` / `README-EN.md` body") would fail because `QQ群` appears in the `` path on line 220 of both files. +- **Alternatives Considered**: + 1. Strict scope — leave `QQ群.png` and accept R4 fail. + 2. Expand scope — rename and update. + 3. Exempt `QQ群.png` in R4's verification scope with explicit allow-list. +- **Selected Approach**: Expand scope. Rename `static/image/QQ群.png` → `static/image/qq-group.png`, update three references. +- **Rationale**: Trivial cost; same fix shape as the listed assets; the ticket's own acceptance criterion is the source of truth. +- **Trade-offs**: One extra file move. None material. +- **Follow-up**: None. + +### Decision: Translate `backend/pyproject.toml:4` description in the same PR + +- **Context**: `backend/pyproject.toml` carries the identical Chinese tagline as `package.json`. Leaving it untranslated produces a half-finished diff. +- **Alternatives Considered**: + 1. Leave it for a follow-up ticket. + 2. Translate it now alongside `package.json`. +- **Selected Approach**: Translate now. +- **Rationale**: Identical string, identical fix, same review surface. Splitting would create needless coordination. +- **Trade-offs**: One additional one-line diff. None material. +- **Follow-up**: None. + +### Decision: Collapse duplicate tagline structure rather than substitute in place + +- **Context**: Lines 7–9 of `README.md` and `README-EN.md` would yield a verbatim duplicate after a one-for-one Chinese-to-English substitution. +- **Alternatives Considered**: + 1. Substitute Chinese line in place (produces duplicate). + 2. Delete Chinese line + `
` separator; let the existing `` line stand alone. + 3. Delete the existing `` line; keep a single non-italic English tagline on line 7. +- **Selected Approach**: Option 2 — delete lines 7 and 8, keep line 9 (`` English tagline). +- **Rationale**: Preserves the existing visual treatment (italic subtitle below the Trendshift badge). Avoids style drift on a docs-only PR. +- **Trade-offs**: Slightly different visual weight (italic only) vs. the prior bilingual stack (plain Chinese + italic English). Acceptable for an English-facing doc. +- **Follow-up**: None. + +### Decision: Use `git mv` for all renames + +- **Context**: Need to preserve rename detection. +- **Alternatives Considered**: `git mv` vs. shell `mv` + `git rm` / `git add`. +- **Selected Approach**: `git mv "old" "new"` with quoted paths. +- **Rationale**: Unambiguous record in the index; matches existing project practice. +- **Trade-offs**: None. +- **Follow-up**: None. + +## Risks & Mitigations + +- **Risk:** Broken images on rendered GitHub README after merge. **Mitigation:** Post-edit grep to confirm zero remaining Chinese-named asset references in any README; preview rendered markdown locally or on a branch before merge. +- **Risk:** Off-repo deep links to old asset URLs (Trendshift cards, social previews). **Mitigation:** Accepted; cost is a single missing image on an external page. +- **Risk:** Diff churn from accidentally re-encoding a binary on macOS or Windows checkout. **Mitigation:** Use `git mv` (no content transform); verify `git diff --stat` shows only renames for the asset files (no content delta). + +## References +- Ticket source: `.ticket/12.md` / GitHub issue #12. +- Project rule on quoting paths: `.claude/rules/file-paths.md`. +- Project commit conventions: `.claude/rules/commits.md` and `.kiro/steering/structure.md`. diff --git a/.kiro/specs/i18n-readme-tagline-and-assets/spec.json b/.kiro/specs/i18n-readme-tagline-and-assets/spec.json new file mode 100644 index 00000000..604baeb4 --- /dev/null +++ b/.kiro/specs/i18n-readme-tagline-and-assets/spec.json @@ -0,0 +1,23 @@ +{ + "feature_name": "i18n-readme-tagline-and-assets", + "created_at": "2026-05-07T19:24:24Z", + "updated_at": "2026-05-07T19:32:00Z", + "language": "en", + "phase": "tasks-generated", + "ticket": "12", + "approvals": { + "requirements": { + "generated": true, + "approved": true + }, + "design": { + "generated": true, + "approved": true + }, + "tasks": { + "generated": true, + "approved": false + } + }, + "ready_for_implementation": true +} diff --git a/.kiro/specs/i18n-readme-tagline-and-assets/tasks.md b/.kiro/specs/i18n-readme-tagline-and-assets/tasks.md new file mode 100644 index 00000000..6b93f638 --- /dev/null +++ b/.kiro/specs/i18n-readme-tagline-and-assets/tasks.md @@ -0,0 +1,47 @@ +# Implementation Plan + +- [x] 1. Translate Chinese taglines to English in the project's English-facing metadata + - In `README.md`, delete the Chinese tagline line and the immediately following `
` line so the existing italic English subtitle on the next line stands as the lone tagline; verify the result still renders with one tagline visible above the Shanda badge + - Apply the identical edit to `README-EN.md` + - In `package.json`, set the `description` value to `MiroFish - A Simple and Universal Swarm Intelligence Engine, Predicting Anything` + - In `backend/pyproject.toml`, set the `description` value to the same English string used in `package.json` + - Leave `README-ZH.md` line 7 (the Chinese tagline) untouched + - Observable completion: a ripgrep scan for `[\x{4e00}-\x{9fff}]` over `README.md`, `README-EN.md`, `package.json`, and `backend/pyproject.toml` returns hits **only** on the language-switcher line of the two READMEs + - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5_ + +- [x] 2. (P) Rename Chinese-named static image assets to ASCII filenames using git mv + - Move the six screenshot files `static/image/Screenshot/运行截图{1..6}.png` to `static/image/Screenshot/screenshot{1..6}.png` + - Move `static/image/武大模拟演示封面.png` to `static/image/wuhan-university-simulation-cover.png` + - Move `static/image/红楼梦模拟推演封面.jpg` to `static/image/dream-of-the-red-chamber-simulation-cover.jpg` + - Move `static/image/QQ群.png` to `static/image/qq-group.png` + - Quote source paths in shell invocations because they contain non-ASCII characters + - Use `git mv` (not shell `mv` + `git add`) so rename detection is recorded directly in the index + - Observable completion: `git status` reports nine `renamed:` entries with no other file modifications; `git diff --stat -M` shows zero content-line delta for each asset + - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6_ + - _Boundary: static/image/_ + +- [x] 3. Update README image references to point at the renamed ASCII asset paths + - In `README.md`, rewrite the nine `` paths on lines 52–61, 71, 79, and 220 so each points at the corresponding ASCII filename from task 2 + - Apply the identical nine edits to `README-EN.md` + - Apply the identical nine edits to `README-ZH.md` (asset path updates only — Chinese body text and Chinese alt attributes preserved) + - Observable completion: a ripgrep search for `运行截图|武大模拟演示封面|红楼梦模拟推演封面|QQ群` in `README.md`, `README-EN.md`, and `README-ZH.md` returns zero matches + - _Requirements: 3.1, 3.2, 3.3_ + - _Depends: 2_ + +- [x] 4. Verify acceptance gates before commit +- [x] 4.1 Run the Chinese-character verification scan and confirm zero residual hits in the EN READMEs body + - Execute `rg --pcre2 '[\x{4e00}-\x{9fff}]' README.md README-EN.md | rg -v 'README-ZH\.md'` from the repo root + - Observable completion: the pipeline produces zero output lines, confirming the only Chinese characters left in the EN READMEs are inside the language-switcher link to `README-ZH.md` + - _Requirements: 4.1, 4.2, 4.3_ + +- [x] 4.2 Confirm asset renames are byte-preserving and unambiguous + - Run `git diff --stat -M` and verify each of the nine asset files appears as a pure rename (no `+` or `-` line counts) + - Run `git status` and confirm there are no untracked Chinese-named files left behind in `static/image/` or `static/image/Screenshot/` + - Observable completion: nine `renamed:` entries in `git status`; zero untracked Chinese-named asset files; zero content delta on the asset rows of `git diff --stat` + - _Requirements: 2.5, 2.6, 3.4_ + +- [x] 4.3 Confirm rendered images by spot-checking the README in a Markdown previewer + - Open `README.md`, `README-EN.md`, and `README-ZH.md` in a Markdown preview (GitHub preview on the feature branch or local previewer) and inspect the screenshot grid, the two video-cover thumbnails, and the QQ group image on each file + - Observable completion: every `` element renders an actual image (no broken-image placeholder) on all three READMEs + - _Requirements: 3.4_ + - **Note**: This task ran in an autonomous environment where no Markdown previewer was available; instead, every `` path in all three READMEs was cross-checked against the working tree and all 33 references resolved to existing files (zero broken paths). A reviewer should still spot-check on the GitHub-rendered PR preview. diff --git a/README-EN.md b/README-EN.md index b45efa3d..9dd3742b 100644 --- a/README-EN.md +++ b/README-EN.md @@ -4,8 +4,6 @@ 666ghj%2FMiroFish | Trendshift -简洁通用的群体智能引擎,预测万物 -
A Simple and Universal Swarm Intelligence Engine, Predicting Anything 666ghj%2MiroFish | Shanda @@ -49,16 +47,16 @@ Welcome to visit our online demo environment and experience a prediction simulat
- - + + - - + + - - + +
Screenshot 1Screenshot 2Screenshot 1Screenshot 2
Screenshot 3Screenshot 4Screenshot 3Screenshot 4
Screenshot 5Screenshot 6Screenshot 5Screenshot 6
@@ -68,7 +66,7 @@ Welcome to visit our online demo environment and experience a prediction simulat ### 1. Wuhan University Public Opinion Simulation + MiroFish Project Introduction
-MiroFish Demo Video +MiroFish Demo Video Click the image to watch the complete demo video for prediction using BettaFish-generated "Wuhan University Public Opinion Report"
@@ -76,7 +74,7 @@ Click the image to watch the complete demo video for prediction using BettaFish- ### 2. Dream of the Red Chamber Lost Ending Simulation
-MiroFish Demo Video +MiroFish Demo Video Click the image to watch MiroFish's deep prediction of the lost ending based on hundreds of thousands of words from the first 80 chapters of "Dream of the Red Chamber"
@@ -217,7 +215,7 @@ npm run frontend # Start frontend only ## 📬 Join the Conversation
-QQ Group +QQ Group
  diff --git a/README-ZH.md b/README-ZH.md index e9ea806d..71dac560 100644 --- a/README-ZH.md +++ b/README-ZH.md @@ -49,16 +49,16 @@ MiroFish 致力于打造映射现实的群体智能镜像,通过捕捉个体
- - + + - - + + - - + +
截图1截图2截图1截图2
截图3截图4截图3截图4
截图5截图6截图5截图6
@@ -68,7 +68,7 @@ MiroFish 致力于打造映射现实的群体智能镜像,通过捕捉个体 ### 1. 武汉大学舆情推演预测 + MiroFish项目讲解
-MiroFish Demo Video +MiroFish Demo Video 点击图片查看使用微舆BettaFish生成的《武大舆情报告》进行预测的完整演示视频
@@ -76,7 +76,7 @@ MiroFish 致力于打造映射现实的群体智能镜像,通过捕捉个体 ### 2. 《红楼梦》失传结局推演预测
-MiroFish Demo Video +MiroFish Demo Video 点击图片查看基于《红楼梦》前80回数十万字,MiroFish深度预测失传结局
@@ -217,7 +217,7 @@ npm run frontend # 仅启动前端 ## 📬 更多交流
-QQ交流群 +QQ交流群
  diff --git a/README.md b/README.md index 383a036d..dee52eb6 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,6 @@ 666ghj%2FMiroFish | Trendshift -简洁通用的群体智能引擎,预测万物 -
A Simple and Universal Swarm Intelligence Engine, Predicting Anything 666ghj%2MiroFish | Shanda @@ -49,16 +47,16 @@ Welcome to visit our online demo environment and experience a prediction simulat
- - + + - - + + - - + +
Screenshot 1Screenshot 2Screenshot 1Screenshot 2
Screenshot 3Screenshot 4Screenshot 3Screenshot 4
Screenshot 5Screenshot 6Screenshot 5Screenshot 6
@@ -68,7 +66,7 @@ Welcome to visit our online demo environment and experience a prediction simulat ### 1. Wuhan University Public Opinion Simulation + MiroFish Project Introduction
-MiroFish Demo Video +MiroFish Demo Video Click the image to watch the complete demo video for prediction using BettaFish-generated "Wuhan University Public Opinion Report"
@@ -76,7 +74,7 @@ Click the image to watch the complete demo video for prediction using BettaFish- ### 2. Dream of the Red Chamber Lost Ending Simulation
-MiroFish Demo Video +MiroFish Demo Video Click the image to watch MiroFish's deep prediction of the lost ending based on hundreds of thousands of words from the first 80 chapters of "Dream of the Red Chamber"
@@ -217,7 +215,7 @@ npm run frontend # Start frontend only ## 📬 Join the Conversation
-QQ Group +QQ Group
  diff --git a/backend/pyproject.toml b/backend/pyproject.toml index 50848022..ade33eb0 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "mirofish-backend" version = "0.1.0" -description = "MiroFish - 简洁通用的群体智能引擎,预测万物" +description = "MiroFish - A Simple and Universal Swarm Intelligence Engine, Predicting Anything" requires-python = ">=3.11" license = { text = "AGPL-3.0" } authors = [ diff --git a/package.json b/package.json index 63ace21a..c9f651ae 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "mirofish", "version": "0.1.0", - "description": "MiroFish - 简洁通用的群体智能引擎,预测万物", + "description": "MiroFish - A Simple and Universal Swarm Intelligence Engine, Predicting Anything", "scripts": { "setup": "npm install && cd frontend && npm install", "setup:backend": "cd backend && uv sync", diff --git a/static/image/Screenshot/运行截图1.png b/static/image/Screenshot/screenshot1.png similarity index 100% rename from static/image/Screenshot/运行截图1.png rename to static/image/Screenshot/screenshot1.png diff --git a/static/image/Screenshot/运行截图2.png b/static/image/Screenshot/screenshot2.png similarity index 100% rename from static/image/Screenshot/运行截图2.png rename to static/image/Screenshot/screenshot2.png diff --git a/static/image/Screenshot/运行截图3.png b/static/image/Screenshot/screenshot3.png similarity index 100% rename from static/image/Screenshot/运行截图3.png rename to static/image/Screenshot/screenshot3.png diff --git a/static/image/Screenshot/运行截图4.png b/static/image/Screenshot/screenshot4.png similarity index 100% rename from static/image/Screenshot/运行截图4.png rename to static/image/Screenshot/screenshot4.png diff --git a/static/image/Screenshot/运行截图5.png b/static/image/Screenshot/screenshot5.png similarity index 100% rename from static/image/Screenshot/运行截图5.png rename to static/image/Screenshot/screenshot5.png diff --git a/static/image/Screenshot/运行截图6.png b/static/image/Screenshot/screenshot6.png similarity index 100% rename from static/image/Screenshot/运行截图6.png rename to static/image/Screenshot/screenshot6.png diff --git a/static/image/红楼梦模拟推演封面.jpg b/static/image/dream-of-the-red-chamber-simulation-cover.jpg similarity index 100% rename from static/image/红楼梦模拟推演封面.jpg rename to static/image/dream-of-the-red-chamber-simulation-cover.jpg diff --git a/static/image/QQ群.png b/static/image/qq-group.png similarity index 100% rename from static/image/QQ群.png rename to static/image/qq-group.png diff --git a/static/image/武大模拟演示封面.png b/static/image/wuhan-university-simulation-cover.png similarity index 100% rename from static/image/武大模拟演示封面.png rename to static/image/wuhan-university-simulation-cover.png