The toolchain rebuild: from loose scripts to a real CLI

.gitattributes

@@ -0,0 +1,2 @@
+# Keep formatter-sensitive Markdown stable across platforms.
+*.md text eol=lf

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: ["main", "dev"]
+  pull_request:
+
+jobs:
+  ci:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    permissions: {}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies (frozen)
+        run: uv sync --frozen
+
+      - name: Run quality checks
+        run: uv run nmteam check
+
+      - name: Verify POSIX launcher
+        if: runner.os != 'Windows'
+        run: scripts/nmteam.sh --help
+
+      - name: Verify PowerShell launcher
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: .\scripts\nmteam.ps1 --help
+
+      - name: Verify Batch launcher
+        if: runner.os == 'Windows'
+        shell: cmd
+        run: scripts\nmteam.bat --help

.gitignore

@@ -81,9 +81,6 @@ target/
 profile_default/
 ipython_config.py
 
-# pyenv
-.python-version
-
 # pipenv
 #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
 #   However, in case of collaboration, if having platform-specific dependencies or dependencies
@@ -131,4 +128,12 @@ dmypy.json
 # nmTeam Doc Generator
 /generated
 /cache
-/mkdocs.yml
+/mkdocs.yml
+
+# uv / ruff
+.ruff_cache/
+
+# Local design and implementation artifacts
+/docs/superpowers/
+
+.DS_Store

.mdformat.toml

@@ -0,0 +1,11 @@
+# mdformat 配置：仓库根目录，适用于 docs/ 下所有 .md 文件
+# 插件（mdformat-mkdocs、mdformat-front-matters）通过 entry point 自动启用，
+# 因此 admonition、content tabs、YAML frontmatter 均受保护，无需 extensions 列表。
+wrap = "keep"
+number = false
+end_of_line = "lf"
+validate = true
+
+[plugin.mkdocs]
+# 保持 mdformat-mkdocs 默认行为（4 空格列表缩进、admonition 保护）；
+# 如后续需要 --align-semantic-breaks-in-lists 等开关，在此追加配置项。

.python-version

@@ -0,0 +1 @@
+3.14

README.md

@@ -1,67 +1,150 @@
 # Support
-[**nmTeam 支持**](https://support.nmteam.xyz)官方网站。使用 `mkdocs-material` 进行构建。
 
-# 快速开始
+[**nmTeam 支持**](https://support.nmteam.xyz)官方网站。使用 `mkdocs-material` 构建；项目由 `uv` 初始化并管理依赖，通过 Typer 提供统一的跨平台命令行入口。
 
-## 安装依赖
-```bash
-# 方式1: 使用管理脚本自动安装
-python manage.py install
+## 环境要求
+
+- Python 3.14+（由 `uv` 按 `.python-version` 自动管理）
+- [uv](https://docs.astral.sh/uv/)（`curl -LsSf https://astral.sh/uv/install.sh | sh`）
+
+## 快速开始
 
-# 方式2: 手动安装
-pip install -r requirements.txt
+### 安装依赖
+
+```bash
+uv sync
 ```
 
-## 开发模式 (推荐)
+也可以使用统一 CLI：
+
 ```bash
-# 启动开发服务器 (支持热更新)
-python manage.py dev
+uv run nmteam install
+```
 
-# 或使用便捷脚本 (Windows)
-.\dev.ps1 dev
-dev.bat dev
+### 开发模式
 
-# 或使用便捷脚本 (Linux/macOS)
-./dev.sh dev
+```bash
+uv run nmteam dev
 ```
 
 开发模式会：
-- 自动生成文档结构
-- 启动 MkDocs 开发服务器 (http://127.0.0.1:8000)
-- 监听 `docs/` 目录文件变化并自动重新生成
-- 支持热更新，修改后自动刷新页面
 
-## 构建生产版本
+- 自动生成文档结构（`cache/`、`generated/`、`mkdocs.yml`）
+- 启动 MkDocs 开发服务器（<http://127.0.0.1:8000>）
+- 监听 `docs/`、`assets/` 和 MkDocs 模板变化并自动重新生成，浏览器热更新
+
+### 构建生产版本
+
 ```bash
-# 构建静态站点
-python manage.py build
+uv run nmteam build
+```
+
+构建结果输出到 `site/` 目录。
+
+最终 HTML 会由 `mkdocs-minify-plugin` 压缩；生成器元标签仅保留 MkDocs
+版本，不暴露主题及其版本。
+
+## 静态资源
+
+仓库内资源统一存放在：
+
+- `assets/images/`：PNG、JPEG 图片母版
+- `assets/icons/`：SVG 图标
+- `assets/styles/`：站点样式
+
+文档使用 `/assets/...` 引用这些资源。生成文档时，每张 PNG 或 JPEG
+图片会同时产生：
+
+- WebP 优先版本：质量 80
+- 原格式 fallback：JPEG 使用质量 80；PNG 使用 256 色有损量化
+
+Markdown 中仍使用普通图片语法，构建工具会自动输出 WebP
+优先的 `<picture>` 元素。外部 URL 不会被下载或镜像。
+
+## AI 支持
+
+站点面向语言模型提供以下能力：
 
-# 或使用便捷脚本
-.\dev.ps1 build
+- `/llms.txt`：按 [llmstxt.org](https://llmstxt.org/) 规范生成的站点索引，
+    每个链接指向页面的 Markdown 版本。
+- 每页 Markdown 版本：`nmteam build` 时在每个页面旁生成同路径的 `.md` 文件
+    （如 `/nmbot-telegram/mcp.md`）。
+- 页面顶部的文章操作区（首页不显示）：**复制 Markdown** 直接复制当前页面
+    原文；**使用［品牌图标］打开** 菜单提供 GitHub 源文件、Markdown 版本，
+    以及 Perplexity、Grok、ChatGPT、Claude Web、Claude Desktop、
+    Claude Code、OpenAI Codex、Cursor 八种 AI 打开方式。
+
+注意：`llms.txt` 与 `.md` 版本由 `nmteam build` 输出到 `site/`；开发模式
+（`nmteam dev`）下复制和 View as Markdown 会提示先构建，AI 操作仍可通过
+当前页面 URL 打开。
+
+### 其他命令
+
+```bash
+uv run nmteam generate # 仅重新生成文档结构
+uv run nmteam clean    # 清理 cache/、generated/ 和 site/
+uv run nmteam serve    # 预览 site/（.md 以 text/plain; charset=utf-8 提供）
+uv run nmteam --help   # 显示完整命令帮助
 ```
 
-构建过程会：
-1. 运行 `generate.py` 生成文档结构
-2. 执行 `mkdocs build` 生成静态站点到 `site/` 目录
+`nmteam serve` 默认监听 `127.0.0.1:8124`，可用 `--port` / `--bind`
+调整。与裸 `python -m http.server` 不同，它把 `.md` 文件的
+`Content-Type` 显式设为 `text/plain; charset=utf-8`（Python 3.13+ 的
+`mimetypes` 会把 `.md` 判为 `text/markdown`，部分客户端会下载而非内联
+显示），保证每页 Markdown 版本在任何浏览器中都能直接阅读。
+
+## 平台启动器
+
+直接运行 `uv run nmteam` 是推荐方式。`scripts/` 也提供不包含业务逻辑的薄启动器；它们会自动定位仓库根目录并原样传递参数。
+
+=== "Linux / macOS"
+
+    ```bash
+    scripts/nmteam.sh dev
+    ```
+
+=== "PowerShell"
+
+    ```powershell
+    .\scripts\nmteam.ps1 dev
+    ```
+
+=== "Windows Batch"
+
+    ```batch
+    scripts\nmteam.bat dev
+    ```
+
+## 质量检查
+
+一条命令运行 Ruff lint、Ruff format check、pytest、mdformat 和 MkDocs strict build：
 
-## 其他命令
 ```bash
-# 清理生成的文件
-python manage.py clean
+uv run nmteam check
+```
 
-# 查看帮助
-python manage.py help
+也可以单独运行：
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+uv run mdformat --check README.md docs/
+uv run nmteam build
 ```
 
-# 传统部署方式
+以上检查由 CI（`.github/workflows/ci.yml`）自动执行。
+
+## 重定向管理
 
-如果你更喜欢传统的分步操作：
+```bash
+uv run nmteam redirects list
+uv run nmteam redirects add "/old-path/" "/new-path/"
+uv run nmteam redirects remove "/old-path/"
+```
 
-- 安装依赖 `pip install -r requirements.txt`
-- 启动本地服务器 `python -m mkdocs serve`
-- 构建生成目录 `python generate.py`
-- 构建静态界面 `python -m mkdocs build`
+管理命令不会用空配置覆盖损坏的 `redirects.json`；修复配置后再重试即可。
 
-# 贡献
+## 贡献
 
 欢迎您在 GitHub 上提出问题并贡献文档。