RubyMetric · Mikachu2333 · May 27, 2026 · May 27, 2026 · May 27, 2026 · May 27, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -1,32 +1,110 @@
-# chsrc Project Rules for AI Assistants
+# chsrc — Change Source Everywhere
 
-## 项目概述
+Cross-platform CLI tool and framework for switching software repository mirrors. Written in **C11** (recommend C17+), single-file compilation from `src/chsrc-main.c`. Targets Linux, Windows (native/MSYS2/Cygwin), macOS, BSD, Android. Licensed GPL-3.0-or-later (main) and MIT (`lib/xy.h`).
 
-这是 chsrc 项目，一个用 C 语言编写的跨平台命令行换源工具，帮助用户在不同的镜像之间切换，适用于编程语言、操作系统、其他软件。它的最强大之处在于它是一个框架，能够帮助用户轻松地为不同的目标换源。
+## Build & Test
 
+Single entry point: `src/chsrc-main.c` `#include`s all framework and recipe files. No build orchestration needed.
 
-## 架构
+```
+# Build (just — recommended for native Windows)
+just build            # DEV mode → chsrc.exe
+just bd               # DEBUG mode (-DXY_DEBUG) → chsrc-debug.exe
+just br               # RELEASE mode (-O2) → chsrc-release.exe
 
-- **Framework**: 在目录 `src/framework/` 中，包含了核心实现，支持 recipe
+# Build (make — Linux/macOS/MSYS2)
+make build / bd / br
+make STATIC=1 br      # static linking
 
-  - `struct.h` 里定义了各种数据结构和宏，这是整个 chsrc 的核心，也是 chef DSL 的核心
-  - `chef.c` 里实现了 chef DSL，你可以使用它来确定正确的使用方法
+# Test
+just test             # xy.h + framework unit tests
+just test-cli         # CLI integration tests (Perl)
+```
 
-- **Recipes**: 在目录 `src/recipe/` 中，包含了针对不同目标的具体实现
+DEBUG mode (`-DXY_DEBUG`) enables runtime validation — all `_prelude()` functions are called after every recipe operation to verify integrity.
 
-  - `lang/` - 编程语言 (Ruby, JavaScript 等等)
-  - `os/`   - 操作系统 (Ubuntu, Arch Linux 等等)
-  - `ware/` - 软件工具和应用 (Docker, Homebrew 等等)
+## Architecture
 
+### Single-file compilation
 
-## Coding Guidelines
+Everything funnels through `src/chsrc-main.c` via `#include`. No object files, no link step beyond the initial compilation.
 
-### C Coding Style:
+### Directory layout
 
-请阅读 `doc/03-为什么拒绝使用代码格式化工具.md`
+| Path                           | Role                                                                                            |
+| ------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `src/chsrc-main.c`             | Entry point: `main()`, CLI parsing, display                                                     |
+| `src/framework/`               | Core: global state, Chef DSL, type definitions, mirror registry, helpers                        |
+| `src/framework/struct.h`       | `Target_t`, `Source_t`, `MirrorSite_t`, Chef DSL macros — **the backbone of chsrc**             |
+| `src/framework/chef.c`         | Chef DSL implementation for recipe authors                                                      |
+| `src/recipe/lang/`             | Programming language recipes (Ruby, Python, Rust, Go, JS, …)                                    |
+| `src/recipe/os/`               | OS recipes (APT/Debian, YUM/Fedora, pacman/Arch, BSD, …)                                        |
+| `src/recipe/ware/`             | Software recipes (Homebrew, Docker, Flatpak, …)                                                 |
+| `src/recipe/menu.c`            | Registry wiring all recipes into three category lists (`pl`, `os`, `wr`)                        |
+| `src/recipe/recipe-template.c` | Template for new recipe authors                                                                 |
+| `lib/xy.h`                     | Standalone C11 utility library (MIT): strings, OS detection, logging, data structures, file I/O |
+| `test/`                        | `xy.c` (xy.h tests), `fw.c` (framework tests), `cli.pl` (CLI integration)                       |
+| `doc/`                         | Developer and user documentation (Chinese)                                                      |
 
-### Important Project Concepts:
+### Core abstractions
 
-请阅读 `doc/10-如何编写recipe.md`
+- **`Target_t`** — A change-source target. Fields: aliases, function pointers (`getfn`, `setfn`, `resetfn`, `preludefn`), source list, scope capabilities, contributor metadata.
+- **`SourceProvider_t` / `MirrorSite_t`** — Mirror or upstream provider. Types: `IS_GeneralMirrorSite`, `IS_DedicatedMirrorSite`, `IS_UpstreamProvider`, `IS_UserDefinedProvider`.
+- **Chef DSL** — Macro-based API: `chef_prep_this()`, `chef_set_chef/cooks/sauciers()`, `chef_set_scope_cap()`, `def_sources_begin()/end()`, `chef_set_smURL()`, `chef_set_smURL_with_postfix()`, etc.
+- **xy.h** — Cross-platform runtime: `xy_on_windows`, string ops (`xy_str_gsub`, `xy_2strcat`), `XySeq_t` (linked list), `XyMap_t` (hash map), command execution, file I/O. Memory convention: `return caller-free` means caller must free.
 
-## Important: 一定要保持注释，因为它记录了重要的维护信息
+### Execution flow
+
+1. `main()` → `chsrc_init_framework()` → `chsrc_init_menu()` (populate targets)
+2. Parse CLI → search menus for matching target → call `preludefn()` → dispatch to `getfn`/`setfn`/`resetfn`
+3. For `set`: auto-measure mirror speeds via `curl`, select fastest, recipe's `_setsrc()` performs the change
+
+### Recipe pattern
+
+Each target is a `.c` file with:
+
+- `_prelude()` — **Required.** Initializes metadata and sources via Chef DSL.
+- `_setsrc()` — **Required.** Performs the source change. Must call `chsrc_use_this_source(target)` to inject the selected source.
+- `_getsrc()` / `_resetsrc()` — Optional.
+
+Reference: `src/recipe/recipe-template.c`, `doc/10-如何编写recipe.md`, `doc/11-如何设置换源链接与测速链接.md`.
+
+### Naming conventions
+
+- `pl*` = programming **l**anguage → `src/recipe/lang/`
+- `os*` = **o**perating **s**ystem → `src/recipe/os/`
+- `wr*` = soft**w**a**r**e → `src/recipe/ware/`
+- Type names: `PascalCase_t`
+- Space between function name and `()` in definitions and calls
+
+## Code Style
+
+- Based on GNU style with project-specific refinements (see `doc/03-为什么拒绝使用代码格式化工具.md`).
+- **No code formatters.** Deliberate manual formatting (alignment, preprocessor indentation, etc.).
+- **Preserve existing comments** — they record important maintenance metadata.
+- Convention over Configuration. NO UFO principle: the tool produces no config/data files in user directories.
+- Contributors are registered in code via `chef_register_contributor()` in `src/chsrc-main.c`, not just in git history.
+
+## Memory Management Rules
+
+**Recipes (`src/recipe/**`):**
+Do NOT use `free()`in recipe code. The project's single-invocation CLI model means the OS reclaims memory on exit. Adding`free()`to recipes creates noise without benefit. Code review should not flag missing`free()` in recipe files.
+
+**Framework (`lib/xy.h`, `src/framework/**`):**
+Strictly check all memory allocations for leaks. Functions marked `return caller-free`in xy.h require callers to free the returned pointer. Every`xy_malloc0`, `xy_strdup`, `xy_str_gsub`, `xy_strcat`, `xy_2strcat`, `xy_file_read` result must be freed or returned to a caller that takes ownership.
+
+## Code Review Checklist
+
+When performing a code review, check:
+
+1. **Pointers, bounds & memory** — NULL dereferences, buffer overflows, use-after-free.
+2. **Logic flaws & structural design** — Incorrect assumptions, fragile coupling, missing edge cases.
+3. **Race conditions** — The tool is single-threaded; flag any introduced concurrency.
+4. **Deadlocks** — Similarly, flag any introduced locking.
+5. **Permission issues** — File/directory access, privilege requirements.
+6. **Deprecated functions or standards** — Must target C11 (prefer C17). No POSIX-only APIs without `#ifdef` guards.
+7. **Comment-code mismatch** — Comments must accurately describe the code they document.
+8. **Redundant code** — Dead code, unreachable branches, duplicate logic.
+9. **Inadequate error handling** — Silent failures, missing NULL checks on fallible operations.
+10. **Undefined behavior** — Integer overflow, out-of-bounds access, use of uninitialized memory, strict aliasing violations.
+11. **Compatibility** — Must compile on Linux (GCC/Clang), macOS (Clang), Windows (MinGW). No C11-incompatible constructs.
diff --git a/.github/workflows/PR-test.yml b/.github/workflows/PR-test.yml
@@ -1,7 +1,7 @@
 # ---------------------------------------------------------------
 # Workflow File : PR-test.yml
-# File Authors  : 曾奥然 <ccmywish@qq.com>
-# Contributors  : Mikachu2333 <mikachu2333@zohomail.com>
+# File Authors  : 曾奥然      <ccmywish@qq.com>
+# Contributors  : Mikachu2333 <linkchou@yandex.com>
 #               |
 # Created On    : <2025-06-19>
 # Last Modified : <2025-08-17>

diff --git a/doc/10-如何编写recipe.md b/doc/10-如何编写recipe.md
@@ -3,8 +3,9 @@
  ! -------------------------------------------------------------
  ! Doc Type      : Markdown
  ! Doc Name      : 10-如何编写recipe.md
- ! Doc Authors   : 曾奥然 <ccmywish@qq.com>
- ! Contributors  : Nul None <nul@none.org>
+ ! Doc Authors   : 曾奥然        <ccmywish@qq.com>
+ ! Contributors  : Nul None      <nul@none.org>
+                   Mikachu2333   <linkchou@yandex.com>
  !               |
  ! Created On    : <2024-08-19>
  ! Last Modified : <2026-01-21>
@@ -116,6 +117,8 @@
 
     `chsrc` 主程序不提供配置文件，不提供数据文件，干净无污染。那么在实现 `recipe` 的时候，除了备份文件外，也不要污染用户环境。
 
+4. 逻辑精炼简洁，
+
 <br>
 
 [rawstr4c]: https://github.com/RubyMetric/rawstr4c

diff --git a/lib/xy.h b/lib/xy.h
@@ -2,9 +2,9 @@
  * Copyright © 2023-2026 曾奥然, 郭恒
  * SPDX-License-Identifier: MIT
  * -------------------------------------------------------------
- * Lib Authors   :  曾奥然 <ccmywish@qq.com>
- *               |   郭恒  <2085471348@qq.com>
- * Contributors  : Mikachu2333  <mikachu.23333@zohomail.com>
+ * Lib Authors   :  曾奥然      <ccmywish@qq.com>
+ *               |   郭恒       <2085471348@qq.com>
+ * Contributors  : Mikachu2333  <linkchou@yandex.com>
  *               | juzeon       <skyjuzheng@gmail.com>
  *               | BingChunMoLi <bingchunmoli@bingchunmoli.com>
  *               | AnonTokio    <anontokio@163.com>

diff --git a/src/chsrc-main.c b/src/chsrc-main.c
@@ -69,7 +69,7 @@ chsrc_register_contributors ()
   chef_register_contributor ("@Kattos",         "ccy",            "icuichengyi@gmail.com",          NULL);
   chef_register_contributor ("@xrgzs",          "MadDogOwner",    "xiaoran@xrgzs.top",              NULL);
   chef_register_contributor ("@sanchuanhehe",   "sanchuanhehe",   "wyihe5520@gmail.com",            NULL);
-  chef_register_contributor ("@Mikachu2333",    "Mikachu2333",    "mikachu.23333@zohomail.com",     NULL);
+  chef_register_contributor ("@Mikachu2333",    "Mikachu2333",    "linkchou@yandex.com",     NULL);
   chef_register_contributor ("@techoc",         "Rui Yang",       "techoc@foxmail.com",             NULL);
   chef_register_contributor ("@BingChunMoLi",   "BingChunMoLi",   "bingchunmoli@bingchunmoli.com",  NULL);
   chef_register_contributor ("@wcbing",         "wcbing",         "i@wcbing.top",                   NULL);