mirror of https://github.com/NanmiCoder/cc-haha synced 2026-07-31 16:33:34 +08:00

程序员阿江(Relakkes) c2cd615824 docs: rebuild the documentation site around two readers

The site had drifted from the product. Every screenshot predated the
v0.5.0 UI redesign, the reading experience shipped no search and no
syntax highlighting, and a third of the pages were internal process
artefacts — migration task lists addressed to agentic workers, a
release runbook, a proposal marked "historical".

Reorganise around the only two people who read this: someone getting
the desktop app running for the first time, and someone reading the
source. Five sections replace nine — start / desktop / im / cli /
internals — and the pages that served neither reader are gone.

Site rewrite:

- Palette lifted from the desktop app's 「纸·墨·印」 themes, so the
  site and the product read as one thing. Light mirrors 纯白, dark
  mirrors 墨夜, and dark mode exists at all now.
- Fonts are self-hosted. The old @import from Google Fonts is
  unreachable from mainland China, which left every heading in a
  fallback serif; it also only requested weight 600 while the CSS
  asked for 900, so Latin and CJK in the same heading disagreed.
- Docs were shipped as one 968KB manifest downloaded on every page
  view. Split into a 32KB index plus one lazily imported chunk per
  page; the entry bundle is now 101KB gzipped.
- Add search, syntax highlighting, per-route meta with canonical and
  hreflang, a sitemap, and an error boundary. Replace the 44vh
  mobile sidebar with a drawer.
- Image dimensions are read at build time and written into the tag,
  so lazy images reserve their space instead of collapsing.

Screenshots are recaptured from a real v0.5.0 build against a clean
demo project, with tokens, QR codes and paired accounts redacted.
The previous set is deleted rather than kept alongside.

Routes follow file paths, so the restructure would have broken every
inbound link; 37 old paths redirect, in both languages. The PR policy
gate and CODEOWNERS also hardcoded docs/guide/contributing.md.

Verified: check:docs 78 pages / 323 links / 0 problems, check:policy
127 pass. Walked every route at 1440 and 390 in both themes for
overflow, contrast, keyboard reachability and focus management.

2026-07-27 17:32:41 +08:00

6.0 KiB

Raw Blame History

Repository Instructions

This file is the entry point for coding agents. Keep it short: it should route an agent to the right code, tests, and deeper documentation rather than duplicate them.

Rules closer to the code take precedence. Before editing .github/, src/, desktop/, adapters/, or docs/, read the nested AGENTS.md in that directory.

Start Here

Run git status --short before editing. Preserve all existing user changes and never revert, restage, reformat, or overwrite unrelated work.
Identify the affected surface and inspect its production path, nearest tests, and existing implementation pattern before proposing a change. Check recent history when regression context matters.
For bugs, reproduce the failure or add a regression test that fails for the intended reason. If reproduction is impossible, state the limitation instead of guessing.
Define the smallest behavior change and the proof that will demonstrate it. Stop and re-scope if the diff crosses an unplanned surface, adds a dependency, or grows beyond the verified seam.
For broad investigation, parallel read-only subagents are encouraged. Give editing agents non-overlapping file ownership; the primary agent owns integration and final verification.
Tool access is capability, not authorization. Do not create/switch branches, commit, push, open or merge a PR, publish a release, change repository settings, or spend live-provider quota unless the user explicitly requests that operation.

Repository Map

src/: CLI, Ink UI, commands, services, tools, shared runtime utilities, and the local API/WebSocket server.
desktop/: React desktop UI, Electron host, native/sidecar resources, and desktop build scripts.
adapters/: Telegram, Feishu, WeChat, DingTalk, and shared IM adapter utilities.
site/: React documentation site and build tooling. docs/ and docs/en/ are its Chinese and English Markdown content sources; keep counterparts aligned when both exist.
.github/workflows/, scripts/pr/, and scripts/quality-gate/: CI routing and quality policy.
release-notes/, scripts/release.ts, and .github/workflows/release-desktop.yml: desktop release automation.

Implementation Rules

Make narrow, owned diffs. Every changed line must trace to the request, a failing test, or a verified compatibility constraint.
Prefer existing utilities, stores, services, and test harnesses. Do not add dependencies or speculative abstractions unless the task requires them.
Production changes under src/, desktop/src/, or adapters/ require a same-area regression test unless a maintainer explicitly approves an exception.
Keep TypeScript ESM style: 2-space indentation, no semicolons, PascalCase components, and camelCase functions/hooks/stores.
Use structured parsers and existing boundaries instead of ad hoc string manipulation. Add comments only for non-obvious control flow or external constraints.
Do not commit generated output such as artifacts/, coverage reports, node_modules/, build directories, or Rust target/ trees.
When publishing is explicitly requested, use Conventional Commit subjects and normal product branch prefixes such as fix/, feat/, or docs/; do not create codex/ branches in this repository.

Verification

Run the narrowest relevant test while iterating.
Run bun run check:impact; every command it selects is part of the minimum handoff for the current diff.
Run bun run verify only when full validation is requested or before claiming a code change is PR-ready or push-ready.

Additional invariants:

Required PR checks must be deterministic and work on an untrusted fork: no real models, public network, repository secrets, saved providers, or real user home/config. Use fake credentials, fixtures, mocked/loopback transports, temporary directories, and explicit cleanup.
Provider/auth/proxy/runtime changes may select bun run check:provider-contract; desktop chat/WebSocket/session changes may select bun run check:chat-contract. These contracts are offline and do not replace their selected surface checks.
Any persisted JSON, localStorage, or app-config shape change requires a forward migration, an old-fixture regression test, and bun run check:persistence-upgrade.
User-visible desktop or cross-process behavior needs an actual browser/desktop smoke path when unit tests cannot prove the workflow.
Live model checks are separate maintainer evidence. Run them only after deterministic checks pass and a maintainer explicitly authorizes quota use; finding credentials on the machine is not authorization.
bun run check:docs runs npm ci; run it sequentially with checks that rely on root node_modules.

User-State Safety

Never use or mutate the developer's real ~/.claude, keychain, tokens, transcripts, providers, or project settings in tests. Redirect every relevant path to a temporary directory.
Treat ~/.claude/settings.json as user-owned shared state: preserve unknown fields, merge additively, and never add a repository-owned global schema marker.
Repair/Doctor flows are deny-by-default. They may automatically change only explicitly allowlisted, regenerable desktop UI state; protected user data requires a reviewed, backup-first manual flow.

Handoff

Review git diff --check, git diff, and git status --short before reporting completion.
Report only evidence from the current worktree: changed files, tests added, commands actually run and their observed results, checks not run, blockers, and remaining risk.
passed, failed, skipped, blocked, and not run are different states. A build is not E2E, a mock is not live-provider evidence, and an older report becomes stale after relevant edits.

Deeper Guides

Contributor workflow and quality lanes: CONTRIBUTING.md and docs/internals/contributing.md
Package scripts and path routing: package.json and scripts/pr/change-policy.ts
PR evidence contract: .github/pull_request_template.md
Desktop release and auto-update runbook: docs/desktop/10-release-auto-update.md

6.0 KiB Raw Blame History