From 21f33e0a4729c65f8b149c74da2cc8a6e2ef7ff4 Mon Sep 17 00:00:00 2001 From: hqhq1025 <1506751656@qq.com> Date: Wed, 12 Aug 2026 23:10:05 +0800 Subject: [PATCH 1/2] feat: add SEO and AI visibility foundation --- .github/workflows/deploy.yml | 4 + DESIGN.md | 8 +- HOMEPAGE_BRIEF.md | 6 +- PRODUCT.md | 10 +- README.md | 5 + astro.config.mjs | 6 +- package.json | 3 +- public/.well-known/security.txt | 4 + src/components/DocumentHeader.astro | 31 ++ src/layouts/BaseLayout.astro | 44 ++- src/layouts/ContentLayout.astro | 67 +++++ src/lib/github.ts | 83 ++++++ src/pages/404.astro | 1 + src/pages/architecture.astro | 82 ++++++ src/pages/architecture.md.ts | 26 ++ src/pages/docs.astro | 78 +++++ src/pages/docs.md.ts | 33 +++ src/pages/download.astro | 111 +++++++ src/pages/download.md.ts | 30 ++ src/pages/index.astro | 65 ++++- src/pages/llms-full.txt.ts | 93 ++++++ src/pages/llms.txt.ts | 42 +++ src/pages/project.md.ts | 41 +++ src/pages/releases.astro | 63 ++++ src/pages/releases.md.ts | 27 ++ src/pages/security.astro | 71 +++++ src/pages/security.md.ts | 27 ++ src/pages/site.json.ts | 42 +++ src/pages/zh.md.ts | 26 ++ src/pages/zh/index.astro | 56 ++++ src/styles/document.css | 435 ++++++++++++++++++++++++++++ tests/seo_contract.mjs | 86 ++++++ 32 files changed, 1676 insertions(+), 30 deletions(-) create mode 100644 public/.well-known/security.txt create mode 100644 src/components/DocumentHeader.astro create mode 100644 src/layouts/ContentLayout.astro create mode 100644 src/lib/github.ts create mode 100644 src/pages/architecture.astro create mode 100644 src/pages/architecture.md.ts create mode 100644 src/pages/docs.astro create mode 100644 src/pages/docs.md.ts create mode 100644 src/pages/download.astro create mode 100644 src/pages/download.md.ts create mode 100644 src/pages/llms-full.txt.ts create mode 100644 src/pages/llms.txt.ts create mode 100644 src/pages/project.md.ts create mode 100644 src/pages/releases.astro create mode 100644 src/pages/releases.md.ts create mode 100644 src/pages/security.astro create mode 100644 src/pages/security.md.ts create mode 100644 src/pages/site.json.ts create mode 100644 src/pages/zh.md.ts create mode 100644 src/pages/zh/index.astro create mode 100644 src/styles/document.css create mode 100644 tests/seo_contract.mjs diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 7a55e43..1a4e1ff 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -3,6 +3,8 @@ name: Deploy website to GitHub Pages on: push: branches: [main] + schedule: + - cron: "23 4 * * *" workflow_dispatch: permissions: @@ -32,6 +34,8 @@ jobs: - name: Build run: npm run build + env: + GITHUB_TOKEN: ${{ github.token }} - name: Configure Pages uses: actions/configure-pages@v5 diff --git a/DESIGN.md b/DESIGN.md index c275d24..7ec8210 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -232,10 +232,10 @@ The system is flat by default. Depth comes from tonal separation, full-perimeter ### Buttons - **Shape:** Compact instrument control with a restrained curve (6px). -- **Primary:** Zinc Ink with Clear Surface text, 14×18px padding, used for **View source**. +- **Primary:** Zinc Ink with Clear Surface text, 14×18px padding, used for **Download Maka**. - **Signal:** Maka Blue with high-contrast Zinc Ink, reserved for the single active path when appropriate. - **Hover / Focus:** Color shifts in 140–220ms; focus uses a 2px Maka-blue outline with 3px offset. No bounce, glow, or elastic motion. -- **Ghost:** Working Plane with a full hairline boundary, used for **Read architecture**. +- **Ghost:** Working Plane with a full hairline boundary, used for **View source**. ### Chips @@ -252,13 +252,13 @@ The system is flat by default. Depth comes from tonal separation, full-perimeter ### Navigation -The fixed desktop navigation uses a compact wordmark, two evidence-led destinations, and one GitHub action. Mobile navigation keeps the GitHub action visible and collapses secondary anchors into a native `
` disclosure. All targets remain at least 44×44px. +The fixed desktop navigation uses a compact wordmark, four scene destinations, a documentation path, and one GitHub action. Mobile navigation keeps the scene controls and primary actions visible. All targets remain at least 44×44px. The active single-viewport site exposes Overview, Product, Runtime, and Surfaces as `[1]`–`[4]` commands in the fixed shell. The visible hints and keyboard behavior must stay identical; Arrow keys remain a sequential alternative. Vertical wheel/trackpad gestures and touch swipes advance the same ordered state machine with an accumulator, one-step gesture lock, and non-looping edge resistance. Initial shell items reveal as one short orchestrated sequence, while `prefers-reduced-motion` renders them immediately. The shell also exposes one `THEME [T]` command beside the GitHub action. It flips the whole stage between the daylight system and a Night system built from the product's own Night Surface tokens: deep night-blue Overview atmosphere with dimmed light bands and lowered renderer exposure, Night Surface paper for Product and Surfaces, and unchanged near-black Runtime. The preference persists in `localStorage`, seeds from `prefers-color-scheme`, keeps WCAG AA contrast (verified by Axe in both themes), and follows the product's Dark Restraint Rule—tonal separation, no neon, no lifted-everything styling. -Surfaces is the closing state. It returns the stage to paper, decodes the "Same runtime. Every surface." statement through a constrained glyph pool as if a recorded execution were being replayed into words, and projects one record into four asymmetric outputs: a dominant authentic Desktop crop, a TUI panel, a single CLI strip, and a compact Headless TaskRun ledger. The semantic four-entry index remains aligned to those projections, while the final source action and colophon close the story. The decode animation is Maka-original: glyphs resolve left-to-right per character, reduced motion settles the text instantly, and the semantic statement stays available to assistive technology through a static `aria-label`. +Surfaces is the closing state. It returns the stage to paper, decodes the "Same runtime. Every surface." statement through a constrained glyph pool as if a recorded execution were being replayed into words, and projects one authority into four asymmetric outputs: a dominant authentic Desktop crop, a TUI panel, a single CLI strip, and a compact Eval cell record. The semantic four-entry index remains aligned to those projections, while the final source action and colophon close the story. The decode animation is Maka-original: glyphs resolve left-to-right per character, reduced motion settles the text instantly, and the semantic statement stays available to assistive technology through a static `aria-label`. ### Persistent Telemetry diff --git a/HOMEPAGE_BRIEF.md b/HOMEPAGE_BRIEF.md index 6156fa1..10fd819 100644 --- a/HOMEPAGE_BRIEF.md +++ b/HOMEPAGE_BRIEF.md @@ -2,11 +2,11 @@ ## 1. Feature Summary -A production-ready, responsive brand homepage for Maka and `maka-agent.com`. It introduces a skeptical technical audience to Maka's local-first execution model, supports claims with real product and architecture evidence, and routes qualified visitors to the public GitHub repository. +A production-ready, responsive brand homepage for Maka and `maka-agent.com`. It introduces a skeptical technical audience to Maka's local-first execution model, supports claims with real product and architecture evidence, and routes qualified visitors to the current download, documentation, and public source. ## 2. Primary User Action -Understand that Maka turns agent conversations into inspectable, recoverable work, then choose **View source**. **Read architecture** is the evidence-first alternative. +Understand that Maka turns agent conversations into inspectable, recoverable work, then choose **Download Maka**. **View source** is the evidence-first alternative. ## 3. Design Direction @@ -41,7 +41,7 @@ The renderer treats pointer position as coordinates, highlights one task path, a ## 8. Content Requirements -Use only claims verifiable in the official README, architecture, security, and design documentation. Required media are official screenshots of the Artifact pane, first-run provider setup, and error handling. Required copy covers local-first storage, Event Log recovery, Tool Calls and permissions, artifacts, Desktop/TUI/CLI/Headless surfaces, source-first maturity, and the GitHub/architecture CTAs. No fake customer proof, metrics, downloads, or availability promises. +Use only claims verifiable in the official README, architecture, security, release record, and design documentation. Required media are official screenshots of the Artifact pane, first-run provider setup, and error handling. Required copy covers local-first storage, Event Log recovery, Tool Calls and permissions, artifacts, Desktop/TUI/CLI clients, Eval through Runtime Host, source-first maturity, and the download/source/architecture paths. No fake customer proof, metrics, or unsupported availability promises. ## 9. Recommended References diff --git a/PRODUCT.md b/PRODUCT.md index f828add..dad389b 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -16,7 +16,7 @@ The secondary audience is open-source contributors who need a fast path into Mak ## Product Purpose -The homepage explains Maka as a local-first workspace for directing, supervising, and completing real work with agents. It must distinguish Maka from disposable chat interfaces, show how conversation, Tool Calls, permissions, artifacts, and durable task state stay connected, and make the project's current source-first maturity explicit. +The homepage explains Maka as a local-first workspace for directing, supervising, and completing real work with agents. It must distinguish Maka from disposable chat interfaces, show how conversation, Tool Calls, permissions, artifacts, and durable execution state stay connected, and make the project's current source-first maturity explicit. Success means a visitor can understand Maka's trust model and execution model within one pass, verify the claims through real product imagery and architecture links, and confidently continue to the GitHub repository. @@ -26,11 +26,11 @@ Maka turns agent work into inspectable, recoverable local execution—not dispos ## Conversion & proof -- Primary CTA: **View source** at `maka-agent/maka-agent`. -- Secondary CTA: **Read architecture** in the official repository. +- Primary CTA: **Download Maka** from the current GitHub Release. +- Secondary CTA: **View source** at `maka-agent/maka-agent`; architecture remains a first-class proof link. - The line a visitor remembers after 10 seconds: **A local-first Agent workspace built for real work.** -- Belief ladder: Maka is more than chat → work runs locally by default → Tool Calls and permissions remain inspectable → outputs become real artifacts → event logs make progress recoverable → the implementation is open for inspection. -- Proof on hand: the public source repository, `ARCHITECTURE.md`, `DESIGN.md`, security documentation, and official product screenshots for the Artifact pane, first-run provider setup, and honest error states. No testimonials, customer logos, adoption metrics, or release claims are available and none may be fabricated. +- Belief ladder: Maka is more than chat → work runs locally by default → Tool Calls and permissions remain inspectable → outputs become real artifacts → event logs make progress recoverable → reproducible Eval subjects use the same Runtime Host → the implementation is open for inspection. +- Proof on hand: the public source repository, current GitHub Release, `ARCHITECTURE.md`, `DESIGN.md`, security documentation, and official product screenshots for the Artifact pane, first-run provider setup, and honest error states. No testimonials, customer logos, adoption metrics, or unsupported availability claims may be fabricated. ## Brand Personality diff --git a/README.md b/README.md index 78137a1..979101a 100644 --- a/README.md +++ b/README.md @@ -14,10 +14,15 @@ npm run dev ```sh npm run check npm run build +npm run test:seo ``` The site is an Astro static build. GitHub Actions publishes `dist/` to GitHub Pages after changes land on `main`. Cloudflare provides authoritative DNS for the custom domain; GitHub Pages terminates HTTPS. +The production workflow also rebuilds daily. Release pages and machine-readable endpoints read the latest published `maka-agent/maka-agent` GitHub Release during the build, so version and installer facts remain aligned with the canonical release record. + +Public machine-readable endpoints include `/llms.txt`, `/llms-full.txt`, `/site.json`, and Markdown alternates for the main project pages. + ## Design evidence - [`PRODUCT.md`](./PRODUCT.md) captures audience, positioning, proof, and accessibility requirements. diff --git a/astro.config.mjs b/astro.config.mjs index 8c35f47..c8cbb5a 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -8,7 +8,11 @@ export default defineConfig({ }, output: "static", compressHTML: true, - integrations: [sitemap()], + integrations: [ + sitemap({ + filter: (page) => !/\.(json|md|txt)$/.test(new URL(page).pathname), + }), + ], build: { inlineStylesheets: "always", }, diff --git a/package.json b/package.json index 796e49b..f947bfc 100644 --- a/package.json +++ b/package.json @@ -5,10 +5,11 @@ "type": "module", "scripts": { "dev": "astro dev", - "build": "astro check && astro build", + "build": "astro check && astro build && node tests/seo_contract.mjs", "check": "astro check", "preview": "astro preview", "test:e2e": "node tests/e2e_site.mjs", + "test:seo": "node tests/seo_contract.mjs", "capture:initial-load": "node tests/capture_initial_load.mjs", "capture:transitions": "node tests/capture_transition_loop.mjs", "capture:hover": "node tests/capture_product_hover.mjs" diff --git a/public/.well-known/security.txt b/public/.well-known/security.txt new file mode 100644 index 0000000..92df586 --- /dev/null +++ b/public/.well-known/security.txt @@ -0,0 +1,4 @@ +Contact: https://github.com/maka-agent/maka-agent/security/advisories/new +Expires: 2027-08-12T00:00:00Z +Canonical: https://maka-agent.com/.well-known/security.txt +Policy: https://github.com/maka-agent/maka-agent/security/policy diff --git a/src/components/DocumentHeader.astro b/src/components/DocumentHeader.astro new file mode 100644 index 0000000..29610ab --- /dev/null +++ b/src/components/DocumentHeader.astro @@ -0,0 +1,31 @@ +--- +const githubUrl = "https://github.com/maka-agent/maka-agent"; +const path = Astro.url.pathname; +const links = [ + ["/download/", "Download"], + ["/docs/", "Docs"], + ["/architecture/", "Architecture"], + ["/security/", "Security"], + ["/releases/", "Releases"], +] as const; +--- + +
+ + + MAKA AGENT + + + + + + Source + +
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro index ed6f4e8..62f6108 100644 --- a/src/layouts/BaseLayout.astro +++ b/src/layouts/BaseLayout.astro @@ -8,27 +8,54 @@ import geistMonoLatinUrl from "@fontsource-variable/geist-mono/files/geist-mono- interface Props { title: string; description: string; + lang?: string; + pageClass?: string; + canonicalPath?: string; + robots?: string; + markdownPath?: string; + alternateLanguages?: Array<{ lang: string; href: string }>; + structuredData?: Record; } -const { title, description } = Astro.props; -const canonical = new URL(Astro.url.pathname, Astro.site); +const { + title, + description, + lang = "en", + pageClass, + canonicalPath = Astro.url.pathname, + robots = "index, follow", + markdownPath, + alternateLanguages = [], + structuredData, +} = Astro.props; +const canonical = new URL(canonicalPath, Astro.site); --- - + + + + + + {alternateLanguages.map((alternate) => ( + + ))} + {markdownPath && ( + + )} @@ -37,7 +64,18 @@ const canonical = new URL(Astro.url.pathname, Astro.site); + + + + {structuredData && ( +