diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml index b75dcaa0..36720d06 100644 --- a/.github/workflows/pr-validation.yml +++ b/.github/workflows/pr-validation.yml @@ -27,12 +27,9 @@ jobs: ref: ${{ github.event.pull_request.head.sha }} fetch-depth: 0 - # 步骤 2: 智能文件变更检测 (可选，如果想每次都跑可以删掉这一步) - name: 🔍 智能文件变更检测 id: changes run: | - # 注意：我们将 'scripts/' 目录也加入到了检测模式中 - # 这样，如果只修改了 manage_tags.py 脚本本身，CI 也会运行 changed_files=$(git diff --name-only ${{ github.event.pull_request.base.sha }}...HEAD) build_patterns=("^docs/" "^mkdocs\.yml$" "^tools/" "^\.github/workflows/pr-validation\.yml$") echo "检查变更的文件列表:" @@ -73,13 +70,12 @@ jobs: - name: Install dependencies if: steps.changes.outputs.should-build == 'true' - # 假设你的依赖文件是 requirements.txt run: uv sync # 步骤 4.5: 标签规范性检查 - name: 🏷️ 标签规范性检查 if: steps.changes.outputs.should-build == 'true' # 并且我们使用 'check' 模式，它在发现问题时会以非零状态码退出，从而使工作流失败。 - run: uv run tools/manage_tags.py check + run: uv run mtag check # 步骤 5: 核心验证步骤 - 严格模式构建 # 只有在上面的标签检查通过后，这一步才会执行。 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..cd4265ff --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,134 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## 项目概览 +- 这是一个基于 **MkDocs + Material for MkDocs** 的文档站点仓库，站点内容是“寻路之南”。 +- Python 运行时要求是 **3.12+**，依赖通过 **uv** 管理。 +- 仓库的核心不是传统应用代码，而是： + - `docs/`：站点内容、静态资源、自定义样式与脚本 + - `mkdocs.yml`：站点导航、主题、插件、额外资源的中心配置 + - `tools/`：为内容仓库服务的自动化脚本（标签管理、完成度分析、原始数据库生成） + +## 常用命令 + +### 安装依赖 +```bash +uv sync +``` + +### 本地开发预览 +```bash +uv run mkdocs serve +``` +启动后访问命令行输出的本地地址（通常是 `http://127.0.0.1:8000`）。 + +### 严格模式构建（最接近 CI 的本地验证） +```bash +uv run mkdocs build --clean --strict --verbose +``` +`--strict` 很重要：构建警告会直接导致失败。 + +### 标签系统检查 +```bash +uv run mtag check +``` + +### 标签系统交互式同步 +```bash +uv run mtag sync +``` +该命令会扫描 `docs/` 下的 Markdown 文件，检查 frontmatter 中的标签，并在需要时更新标签词典与标签索引页。 + +### 内容完成度报告 +```bash +uv run cana +``` +可选静默模式： +```bash +uv run cana --quiet +``` + +### Docker 本地预览 +```bash +docker compose up --build +``` + +### 启用 git-committers 插件进行本地构建/预览 +默认本地关闭。只有在需要预览贡献者信息时才启用： +```bash +export ENABLE_COMMITTERS=true +export GITHUB_TOKEN=your_token +uv run mkdocs serve +``` + +### 关于“测试” +- 当前仓库**没有独立的单元测试目录或 pytest 测试套件**。 +- 最重要的验证方式是： + - `uv run mkdocs build --clean --strict --verbose` + - `uv run mtag check` +- 因此也不存在“运行单个测试文件”的标准命令；如果需要做最小范围验证，通常是修改后直接用 `mkdocs serve` 本地预览，或跑标签检查脚本。 + +## 高层架构 + +### 1. 内容站点层 +- `docs/` 是站点的主要内容源。 +- Markdown 页面通常带有 YAML frontmatter，尤其是 `tags:` 字段。 +- 站点内容按主题组织在 `docs/` 下的多个内容分区中，例如通识课程、技能模块、昌大专属内容、社区与共建等。 +- `docs/css/`、`docs/javascripts/`、`docs/assets/` 存放前端资源；这些资源由 `mkdocs.yml` 挂接到站点中。 + +### 2. 配置中心 +- `mkdocs.yml` 是整个站点的**单一配置中心**，负责： + - 导航树 `nav` + - Material 主题与功能开关 + - 插件配置（尤其是 `search`、`tags`、`git-committers`） + - `extra_css` / `extra_javascript` +- 任何新增页面如果要出现在站点导航中，通常都需要同步修改 `mkdocs.yml`。 + +### 3. 自动化脚本层 (`tools/`) +- `tools/manage_tags.py` + - 扫描 `docs/**/*.md` + - 校验 frontmatter 中的标签格式、大小写与词典合法性 + - `sync` 模式下可更新 `tag_dictionary.yml`，并重新生成生成文件 `docs/tags.md` +- `tools/completion_analyzer.py` + - 读取 `mkdocs.yml` 的 `nav` + - 统计页面内容量与完成度 + - 输出 CSV 和 Markdown 报告 + - Markdown 生成文件为 `docs/COMPLETION_REPORT.md` + - 输出路径和阈值在 `pyproject.toml` 的 `[tool.completion-analyzer]` 中配置 +- `tools/weaver_build_raw_db.py` + - 扫描文档与 frontmatter + - 提取标题、标签、摘要、标题层级等元数据 + - 生成文件 `tools/data/raw_database.json` + - 会遵守 `.weaverignore` + +### 4. CI / 部署层 +- `.github/workflows/pr-validation.yml` + - 针对发往 `main` 的 PR 运行 + - 先做文件变更检测 + - 然后执行 `uv sync` + - 运行 `uv run mtag check` + - 最后运行 `uv run mkdocs build --clean --strict --verbose` +- `.github/workflows/deploy-docs.yml` + - 在 `main` 分支 push 时部署 + - 也支持 `workflow_dispatch` + - 使用 GitHub Pages 发布 `site/` + - 部署时会启用 `git-committers` 插件（通过环境变量） + +## 重要约定 +- **不要手动维护 `tag_dictionary.yml`。** 标签规范文档明确要求通过 `uv run mtag sync` 进行管理。 +- **`docs/tags.md` 是生成文件。** 如果标签体系变更，优先通过标签脚本重建，而不是手工编辑。 +- **`docs/COMPLETION_REPORT.md` 是生成文件。** 如需更新，请运行 `uv run cana`。 +- **`tools/data/raw_database.json` 是生成文件。** 如需更新，请运行对应构建脚本，而不是手工编辑。 +- 标签遵循 `Prefix-Value` 格式，前缀来自五个固定维度：`Topic`、`Type`、`Level`、`Action`、`Context`。 +- 本仓库的很多“结构性信息”并不分散在目录命名里，而是集中在 `mkdocs.yml` 的 `nav` 中；理解内容结构时优先读 `mkdocs.yml`。 +- `tools/completion_analyzer.py` 依赖 `mkdocs.yml` 的导航结构，因此改动导航时要注意是否会影响完成度报告。 +- `git-committers` 插件本地默认关闭；如果本地构建时忘了配置 `ENABLE_COMMITTERS`/`GITHUB_TOKEN`，通常不是 bug。 +- 因为 CI 使用 `mkdocs build --strict`，所以**坏链接、无效引用、部分构建警告都应视为阻塞问题**。 + +## 修改内容时的工作方式 +- 纯内容修改：通常改 `docs/` 下对应页面，必要时更新 `mkdocs.yml` 导航。 +- 新增页面：除创建 Markdown 文件外，通常还要补充 frontmatter 标签，并把页面接入 `mkdocs.yml`。 +- 修改标签体系：优先查看 `docs/community/contributing/workflow/tag.md`，然后运行 `uv run mtag sync`。 +- 修改完成度分析逻辑：同时查看 `tools/completion_analyzer.py` 和 `pyproject.toml` 中的 `[tool.completion-analyzer]` 配置。 +- 修改部署/验证行为：查看 `.github/workflows/pr-validation.yml` 与 `.github/workflows/deploy-docs.yml`，因为它们定义了仓库的真实质量门槛与上线流程。 diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..d0958bb0 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 CS for NCU contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 21bf7d4e..d8655b66 100644 --- a/README.md +++ b/README.md @@ -1,139 +1,167 @@
- - +# 寻路之南 +### 写给普通人的大学成长指南 - # 寻路之南 - ### 写给普通人的大学成长指南 +由一群普通本科生发起的开源项目，试图为普通大学生整理一套从自我认知开始的成长方法论。我们始于南昌大学，但这份指南并不只写给南昌大学。 - 由一群普通本科生发起的开源项目，致力于分享一套从自我认知开始的成长方法论。
我们始于南昌大学，但这份指南属于每一位渴望主动把握大学生涯的你。 - - [![GitHub Stars](https://img.shields.io/github/stars/NCUSCC/cs4ncu.svg?style=flat-square)](https://github.com/NCUSCC/cs4ncu/stargazers) - [![GitHub Forks](https://img.shields.io/github/forks/NCUSCC/cs4ncu.svg?style=flat-square)](https://github.com/NCUSCC/cs4ncu/network/members) - [![GitHub Issues](https://img.shields.io/github/issues/NCUSCC/cs4ncu.svg?style=flat-square)](https://github.com/NCUSCC/cs4ncu/issues) - [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](/LICENSE) +[![GitHub Stars](https://img.shields.io/github/stars/NCUSCC/cs4ncu.svg?style=flat-square)](https://github.com/NCUSCC/cs4ncu/stargazers) +[![GitHub Forks](https://img.shields.io/github/forks/NCUSCC/cs4ncu.svg?style=flat-square)](https://github.com/NCUSCC/cs4ncu/network/members) +[![GitHub Issues](https://img.shields.io/github/issues/NCUSCC/cs4ncu.svg?style=flat-square)](https://github.com/NCUSCC/cs4ncu/issues) +[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](/LICENSE)
--- -### 我们的故事与初心 +## 这是什么项目 -我们曾仰望过《上海交通大学生存手册》那样的精英灯塔，但很快发现，他们的航线固然璀璨，其起点、风速、洋流都与我们不同。我们需要一份更具普适性的海图，一套更基础、更关注内在的航行方法。 +**寻路之南是一份写给普通大学生的开源成长指南。** -我们为这份初心，取名为“寻路之南” 。它是一份“寻路者的指南”，也是一场始于南昌大学的探索。它承载着我们的起点，也指向我们共同的目标：在迷雾中，为自己找到南方——那个温暖、清晰、充满生命力的方向。 +它想解决的，不是“怎么复制少数精英样本的成功路线”，而是一个更常见也更现实的问题： -这个位置，让我们得以摆脱纯粹的精英视角或自怨自艾的受害者心态。它让我们相信，我们的故事——**一个关于在还不错的平台上，如何通过自我认知与系统构建，来超越平台局限的故事**——对最广大的学生群体，具有最真实的参考意义。 +- 当你没有现成标准答案时，怎样理解自己？ +- 面对大量信息和建议时，怎样做判断？ +- 在迷茫、不确定和资源有限的情况下，怎样一步步开始行动？ -这就是我们的立足点：不仰望神坛，也不俯视深渊，只是脚踏实地，与每一个努力向上的你同行。 +所以，这里不会只做经验贴堆叠，也不会把项目做成单纯展示“成功案例”的橱窗。我们更关心的是：**普通学生如何建立自己的判断与行动系统。** --- -### 在线阅读 +## 第一次来，先看什么 + +如果你想最快进入正确入口，建议按这个顺序阅读： + +1. [第负一课：先别慌，我们聊聊](https://cs4ncu.space/growth-general-course/00-before-we-start/prologue-the-start/) +2. [核心原则：构建你的个人决策系统](https://cs4ncu.space/growth-general-course/01-the-zero-course/the-core/) +3. [完整课程导览](https://cs4ncu.space/growth-general-course/01-the-zero-course/) +4. [全站导览与官方推荐路径](https://cs4ncu.space/growth-general-course/00-before-we-start/overview/) -**我们强烈建议您在线阅读，以获得最佳体验。** +在线阅读入口： **➡️ [https://cs4ncu.space/](https://cs4ncu.space/)** --- -### 内容结构 +## 当前最推荐的 4 条阅读路径 -本指南主要由以下几个核心部分构成，我们建议您从“寻路指南”开始。 +### 1. 新读者起步路径 -| 模块 | 核心内容 | -| :--- | :--- | -| **开始之前** | **建议从这里开始。** 这里有写给新读者的第一封信 (`第负一课`)，以及一份网站的完整地图 (`全站导览`)。| -| **核心课程** | 本项目的主体。包括了作为基石的 **`本科生通识第零课`** 和作为拓展的 **`第零点五课堂`**。 | -| **昌大专属** | 沉淀了独属于南昌大学的实用信息与经验，例如转专业、保研考研等。 | -| **关于我们** | 你可以在这里找到我们的完整初心、项目共建指南和内容索引。 | +**适合谁：** 第一次接触项目、刚入学、最近比较乱、需要一个稳定起点的人。 ---- +**读完你能获得什么：** 先安顿情绪，再理解本站主线和后续阅读方式。 -### 本地开发与贡献 +- 首页 +- 第负一课：先别慌，我们聊聊 +- 核心原则：构建你的个人决策系统 +- 完整课程导览 -如果你希望在本地运行、修改网站，或参与项目共建，欢迎继续阅读。 +### 2. 决策与自我认知路径 -1. **环境准备** - * 安装 [Git](https://git-scm.com/) - * 安装 [uv](https://github.com/astral-sh/uv#installation) (一个极速的 Python 包管理器) +**适合谁：** 正在专业、方向、选择上反复摇摆的人。 -2. **克隆并进入项目** - ```bash - git clone https://github.com/NCUSCC/cs4ncu.git - cd cs4ncu - ``` +**读完你能获得什么：** 一个更清晰的自我认知和决策框架。 -3. **同步环境** - ```bash - uv sync - ``` +- 核心原则：构建你的个人决策系统 +- 第一部分：决策的基础 +- 第一章：思维模式转换 +- 第二章：自我认知方法 +- 第六章：低成本实践与验证 -4. **启动！** - ```bash - uv run mkdocs serve - ``` - 在浏览器中打开 `http://127.0.0.1:8000` 即可。 +### 3. 学习系统重建路径 -#### 使用 Docker 运行 +**适合谁：** 明明花了很多时间学习，但总觉得乱、散、累的人。 -无需安装本地 Python/uv，直接用 Docker 预览站点： +**读完你能获得什么：** 一个关于信息输入、学习方法和精力管理的学习系统雏形。 -```bash -# 方式一：docker compose（推荐，热更新） -docker compose up --build - -# 方式二：纯 docker -docker build -t cs4ncu-docs . -docker run --rm -it -p 8000:8000 -v $(pwd):/app \ - -e ENABLE_COMMITTERS=${ENABLE_COMMITTERS:-false} \ - -e GITHUB_TOKEN=${GITHUB_TOKEN:-} \ - cs4ncu-docs -``` +- 第四章：信息获取入门 +- 元学习 +- 精力管理 -打开 `http://127.0.0.1:8000` 访问。若需启用 `git-committers` 插件，请设置环境变量： +### 4. 从读者到参与者路径 -```bash -export ENABLE_COMMITTERS=true -export GITHUB_TOKEN=你的GitHubToken -``` +**适合谁：** 想先理解项目、再看看要不要参与共建的人。 -### 欢迎参与共建 +**读完你能获得什么：** 理解项目边界、社区氛围和参与入口。 -`寻路之南` 的成长离不开每一位社区成员的贡献。我们欢迎任何形式的帮助！ +- [我们的初心](https://cs4ncu.space/community/our-story/) +- [打卡教程](https://cs4ncu.space/community/how-to-check-in/) +- [路友打卡墙](https://cs4ncu.space/community/contributors/) +- [贡献流程](https://cs4ncu.space/community/contributing/how-to-contribute/) -| 贡献方式 | 如何开始 | +--- + +## 项目结构 + +目前站点主要由 4 个部分组成： + +| 模块 | 说明 | | :--- | :--- | -| **内容创作** | 修正错别字、完善现有章节、撰写全新内容。 | -| **提出建议** | 发现内容问题或有新的想法？请大胆地 [**提出 Issue**](https://github.com/NCUSCC/cs4ncu/issues/new/choose)！ | -| **代码贡献** | 帮助我们优化网站功能、修复 Bug、改进自动化流程。 | +| **开始之前** | 给第一次来的读者一个稳定入口，包括第负一课和全站导览。 | +| **寻路通识课** | 当前最核心的方法论主线，围绕“向内看 → 向外看 → 去行动”展开。 | +| **第零点五课堂** | 按主题补齐底层能力，涵盖学习、沟通、工具、成长等模块。 | +| **社区与共建 / 昌大专属** | 前者负责项目故事与参与入口，后者负责南昌大学场景下的经验入口。 | -不确定从哪里开始？我们为你准备了适合新手的任务 👉 [**`good first issue`**](https://github.com/NCUSCC/cs4ncu/labels/good%20first%20issue) +--- -> 每一次微小的贡献，都在点亮更多人前行的道路。 +## 这不是一个什么项目 -### 我们的贡献者 +为了避免误解，我们也想把边界说清楚： -我们由衷感谢每一位为本项目注入心血的贡献者。 +- **这不是鸡汤项目**：我们希望内容能帮助人理解问题和推进下一步，而不只是短暂被鼓舞。 +- **这不是学校官网替代品**：我们不替代通知系统，而是帮助普通学生理解制度、资源和机会。 +- **这不是只写精英样本的经验陈列馆**：我们更关心普通起点下可复用、可实践的成长方法。 - - Contributors - +如果你想看完整版本的项目故事，可以阅读： -*(由 [contrib.rocks](https://contrib.rocks) 自动生成)* +- [我们的初心](https://cs4ncu.space/community/our-story/) -## Star History +--- + +## 想参与的话，从哪里开始 -[![Star History Chart](https://api.star-history.com/svg?repos=NCUSCC/cs4ncu&type=Date)](https://www.star-history.com/#NCUSCC/cs4ncu&Date) +如果你想先低门槛试一次，可以按这条链路进入： -### 开源协议 +1. [我们的初心](https://cs4ncu.space/community/our-story/) +2. [打卡教程](https://cs4ncu.space/community/how-to-check-in/) +3. [路友打卡墙](https://cs4ncu.space/community/contributors/) +4. [贡献流程](https://cs4ncu.space/community/contributing/how-to-contribute/) -本项目基于 [**MIT License**](./LICENSE) 授权。 +你也可以直接查看适合新手的任务： + +- [good first issue](https://github.com/NCUSCC/cs4ncu/labels/good%20first%20issue) --- -
+## 本地开发 -*Crafted with ❤️ and ☕ by the community.* +如果你希望在本地运行或修改站点： -
+1. 安装 [Git](https://git-scm.com/) +2. 安装 [uv](https://github.com/astral-sh/uv#installation) +3. 克隆项目并进入目录 + +```bash +git clone https://github.com/NCUSCC/cs4ncu.git +cd cs4ncu +``` + +4. 同步环境 + +```bash +uv sync +``` + +5. 启动本地预览 + +```bash +uv run mkdocs serve +``` + +然后在浏览器打开 `http://127.0.0.1:8000`。 + +--- + +## 开源协议 + +本项目基于 [MIT License](./LICENSE) 授权。 diff --git a/docs/COMPLETION_REPORT.md b/docs/COMPLETION_REPORT.md index 587daec7..5fd1adad 100644 --- a/docs/COMPLETION_REPORT.md +++ b/docs/COMPLETION_REPORT.md @@ -1,30 +1,31 @@ # 内容完成情况报告 -> 报告生成时间：2025-08-31 22:12:42 +> 本页为生成文件，请勿手动编辑。如需更新，请运行 `uv run cana`。 +> 报告生成时间：2026-03-10 16:32:34 ## 报告上下文 -- **版本来源**: [`32994ab`](https://github.com/NCUSCC/cs4ncu/commit/32994ab49e6302f627f1ca7cece0d22f064009f7) - *Add NCU military training guide and update nav labels* +- **版本来源**: [`b2feb32`](https://github.com/NCUSCC/cs4ncu/commit/b2feb32dc1217ef64e4b6a0a210e6a8817517457) - *chore: regenerate generated documentation outputs* - **生成脚本**: `cana` ## 完成度概览 - `[ ]` 表示待办或内容不足 - `[x]` 表示已完成或内容充实 -- [x] **首页** (`index.md`) - *2857字，substantial* +- [x] **首页** (`index.md`) - *3647字，substantial* -## 寻路通识课 (12/13) +## 寻路通识课 (13/13) -### 开始之前 (1/2) -- [x] **先别慌，我们聊聊** (`growth-general-course/00-before-we-start/prologue-the-start.md`) - *1403字，substantial* -- [ ] **全站导览** (`growth-general-course/00-before-we-start/overview.md`) - *66字，basic* +### 开始之前 (2/2) +- [x] **先别慌，我们聊聊** (`growth-general-course/00-before-we-start/prologue-the-start.md`) - *1372字，substantial* +- [x] **全站导览与推荐路径** (`growth-general-course/00-before-we-start/overview.md`) - *3857字，substantial* ### 本科生通识第零课 (11/11) - [x] **核心原则** (`growth-general-course/01-the-zero-course/the-core.md`) - *1962字，substantial* - [x] **完整课程导览** (`growth-general-course/01-the-zero-course/index.md`) - *937字，substantial* #### 一：决策的基础 (3/3) -- [x] **本部分导览** (`growth-general-course/01-the-zero-course/part1/index.md`) - *620字，substantial* -- [x] **思维模式转换** (`growth-general-course/01-the-zero-course/part1/ch1-mindset.md`) - *1316字，substantial* -- [x] **自我认知方法** (`growth-general-course/01-the-zero-course/part1/ch2-the-self.md`) - *1917字，substantial* +- [x] **本部分导览** (`growth-general-course/01-the-zero-course/part1/index.md`) - *589字，substantial* +- [x] **思维模式转换** (`growth-general-course/01-the-zero-course/part1/ch1-mindset.md`) - *1285字，substantial* +- [x] **自我认知方法** (`growth-general-course/01-the-zero-course/part1/ch2-the-self.md`) - *1303字，substantial* #### 二：决策的依据 (3/3) - [x] **本部分导览** (`growth-general-course/01-the-zero-course/part2/index.md`) - *631字，substantial* @@ -36,11 +37,11 @@ - [x] **设定探索方向** (`growth-general-course/01-the-zero-course/part3/ch5-the-output.md`) - *995字，substantial* - [x] **低成本实践与验证** (`growth-general-course/01-the-zero-course/part3/ch6-the-test.md`) - *1248字，substantial* -## 第零点五课堂 (22/46) -- [x] **本部分导览** (`skills/index.md`) - *599字，substantial* +## 第零点五课堂 (41/47) +- [x] **本部分导览** (`skills/index.md`) - *1983字，substantial* -### 认知与心智 (10/12) -- [ ] **导览** (`skills/mindset/index.md`) - *11字，minimal* +### 认知与心智 (12/12) +- [x] **导览** (`skills/mindset/index.md`) - *735字，substantial* #### 思维定式 (3/3) - [x] **优绩主义** (`skills/mindset/fixed/meritocracy.md`) - *2102字，substantial* @@ -48,80 +49,81 @@ - [x] **做题家思维** (`skills/mindset/fixed/solver-mindset.md`) - *1931字，substantial* #### 认知偏差 (3/3) -- [x] **幸存者偏差** (`skills/mindset/bias/survivorship-bias.md`) - *2661字，substantial* -- [x] **确认偏差** (`skills/mindset/bias/confirmation-bias.md`) - *2480字，substantial* -- [x] **沉没成本** (`skills/mindset/bias/sunk-cost.md`) - *2363字，substantial* +- [x] **幸存者偏差** (`skills/mindset/bias/survivorship-bias.md`) - *2674字，substantial* +- [x] **确认偏差** (`skills/mindset/bias/confirmation-bias.md`) - *2734字，substantial* +- [x] **沉没成本** (`skills/mindset/bias/sunk-cost.md`) - *2377字，substantial* #### 心智模型 (2/2) - [x] **贝叶斯法则** (`skills/mindset/model/bayesian-thinking.md`) - *2510字，substantial* - [x] **合作与博弈** (`skills/mindset/model/collaboration.md`) - *2657字，substantial* -#### 心理健康 (2/3) -- [ ] **冒名顶替综合征** (`skills/mindset/mental/impostor-syndrome.md`) - *10字，minimal* +#### 心理健康 (3/3) +- [x] **冒名顶替综合征** (`skills/mindset/mental/impostor-syndrome.md`) - *2578字，substantial* - [x] **学会独处** (`skills/mindset/mental/learn-to-be-alone.md`) - *2391字，substantial* - [x] **焦虑与内耗** (`skills/mindset/mental/anxiety-impostor.md`) - *2862字，substantial* -### 学会学习 (0/5) -- [ ] **导览** (`skills/learning/index.md`) - *10字，minimal* -- [ ] **元学习** (`skills/learning/meta/meta-learning.md`) - *6字，minimal* -- [ ] **信息输入** (`skills/learning/intake/information-intake.md`) - *7字，minimal* -- [ ] **知识内化** (`skills/learning/consolidation/knowledge-consolidation.md`) - *7字，minimal* -- [ ] **精力管理** (`skills/learning/energy/energy-management.md`) - *0字，empty* +### 学会学习 (5/5) +- [x] **导览** (`skills/learning/index.md`) - *1674字，substantial* +- [x] **元学习** (`skills/learning/meta/meta-learning.md`) - *3089字，substantial* +- [x] **信息输入** (`skills/learning/intake/information-intake.md`) - *2731字，substantial* +- [x] **知识内化** (`skills/learning/consolidation/knowledge-consolidation.md`) - *2367字，substantial* +- [x] **精力管理** (`skills/learning/energy/energy-management.md`) - *2603字，substantial* -### 沟通与协作 (3/5) -- [ ] **导览** (`skills/communication/index.md`) - *11字，minimal* -- [ ] **沟通技巧** (`skills/communication/skills/communication.md`) - *0字，empty* +### 沟通与协作 (5/5) +- [x] **导览** (`skills/communication/index.md`) - *1438字，substantial* +- [x] **沟通技巧** (`skills/communication/skills/communication.md`) - *2337字，substantial* - [x] **构建人际关系网** (`skills/communication/skills/network-of-relationships.md`) - *3699字，substantial* - [x] **团队协作** (`skills/communication/teamwork/teamwork.md`) - *1592字，substantial* - [x] **人际矛盾处理** (`skills/communication/skills/dealing-conflicts.md`) - *3260字，substantial* -### 工具与系统 (6/15) -- [ ] **导览** (`skills/tools/index.md`) - *11字，minimal* +### 工具与系统 (13/16) +- [x] **导览** (`skills/tools/index.md`) - *1756字，substantial* #### 数字素养 (3/4) - [x] **电脑认知** (`skills/tools/literacy/computer-basics.md`) - *2642字，substantial* -- [x] **高效打字** (`skills/tools/literacy/typing.md`) - *1956字，substantial* +- [x] **高效打字** (`skills/tools/literacy/typing.md`) - *2179字，substantial* - [ ] **网络工具** (`skills/tools/literacy/network-proxy.md`) - *0字，empty* - [x] **版本选择** (`skills/tools/literacy/version-control.md`) - *3944字，substantial* -#### 信息管理 (0/3) -- [ ] **云笔记** (`skills/tools/pkm/cloud-notes.md`) - *6字，minimal* +#### 信息管理 (2/3) +- [x] **云笔记** (`skills/tools/pkm/cloud-notes.md`) - *2322字，substantial* - [ ] **协作文档** (`skills/tools/pkm/collaboration-docs.md`) - *7字，minimal* -- [ ] **任务管理** (`skills/tools/pkm/task-management.md`) - *7字，minimal* +- [x] **任务管理** (`skills/tools/pkm/task-management.md`) - *2329字，substantial* -#### 生产力工具 (3/5) -- [x] **Git** (`skills/tools/pro/git.md`) - *2424字，substantial* +#### 生产力工具 (6/6) +- [x] **Git** (`skills/tools/pro/git.md`) - *2434字，substantial* - [x] **Linux** (`skills/tools/pro/linux.md`) - *3568字，substantial* -- [ ] **LaTeX** (`skills/tools/pro/latex.md`) - *0字，empty* +- [x] **LaTeX** (`skills/tools/pro/latex.md`) - *4020字，substantial* - [x] **Prompt Engineering** (`skills/tools/pro/prompt-engineering.md`) - *4685字，substantial* -- [ ] **Docker** (`skills/tools/pro/docker.md`) - *0字，empty* +- [x] **Docker** (`skills/tools/pro/docker.md`) - *4232字，substantial* +- [x] **Premiere Pro** (`skills/tools/pro/premiere.md`) - *11573字，substantial* -#### VS Code 指南 (0/2) -- [ ] **导览与配置** (`skills/tools/vscode/index.md`) - *0字，empty* +#### VS Code 指南 (1/2) +- [x] **导览与配置** (`skills/tools/vscode/index.md`) - *2547字，substantial* - [ ] **插件推荐** (`skills/tools/vscode/extensions.md`) - *0字，empty* -### 成长与规划 (2/8) -- [ ] **导览** (`skills/growth/index.md`) - *11字，minimal* +### 成长与规划 (5/8) +- [x] **导览** (`skills/growth/index.md`) - *1642字，substantial* -#### 财务管理 (0/2) -- [ ] **财商启蒙** (`skills/growth/finance/financial-literacy.md`) - *7字，minimal* +#### 财务管理 (1/2) +- [x] **财商启蒙** (`skills/growth/finance/financial-literacy.md`) - *2258字，substantial* - [ ] **聪明消费** (`skills/growth/finance/smart-spending.md`) - *0字，empty* #### 身体健康 (1/1) - [x] **健康管理** (`skills/growth/health/healthy-management.md`) - *2561字，substantial* -#### 机遇探索 (1/4) +#### 机遇探索 (2/4) - [ ] **信息差** (`skills/growth/opportunity/information-gap.md`) - *0字，empty* - [ ] **开源之旅** (`skills/growth/opportunity/open-source-journey.md`) - *0字，empty* - [x] **实验班解读** (`skills/growth/opportunity/innovation-classes.md`) - *3017字，substantial* -- [ ] **职业规划** (`skills/growth/opportunity/career-planning.md`) - *7字，minimal* +- [x] **职业规划** (`skills/growth/opportunity/career-planning.md`) - *2621字，substantial* -## 昌大专属资源库 (3/11) -- [ ] **本部分导览** (`ncu-exclusive/index.md`) - *6字，minimal* +## 昌大专属 (5/11) +- [x] **入口与说明** (`ncu-exclusive/index.md`) - *1509字，substantial* -### 学业发展 (2/6) +### 学业发展 (3/6) - [ ] **培养方案全解** (`ncu-exclusive/academic-development/program-guide.md`) - *15字，minimal* -- [ ] **学分绩点体系** (`ncu-exclusive/academic-development/credits-and-gpa.md`) - *0字，empty* +- [x] **学分绩点体系** (`ncu-exclusive/academic-development/credits-and-gpa.md`) - *2758字，substantial* - [ ] **特色实验班** (`ncu-exclusive/academic-development/experimental-classes.md`) - *0字，empty* #### 转专业指南 (1/1) @@ -141,12 +143,13 @@ ### 校园生活 (1/3) - [ ] **通识课程体系** (`ncu-exclusive/campus-life/general-education-courses.md`) - *0字，empty* - [ ] **体育与体测** (`ncu-exclusive/campus-life/pe-and-fitness-tests.md`) - *0字，empty* -- [x] **新生军训** (`ncu-exclusive/campus-life/military-training.md`) - *1311字，substantial* +- [x] **新生军训** (`ncu-exclusive/campus-life/military-training.md`) - *1989字，substantial* -## 社区与共建 (18/19) -- [ ] **我们的初心** (`community/our-story.md`) - *11字，minimal* -- [x] **打卡教程** (`community/how-to-check-in.md`) - *2294字，substantial* -- [x] **路友打卡墙** (`community/contributors.md`) - *714字，substantial* +## 社区与共建 (20/20) +- [x] **我们的初心** (`community/our-story.md`) - *2634字，substantial* +- [x] **打卡教程** (`community/how-to-check-in.md`) - *2416字，substantial* +- [x] **路友打卡墙** (`community/contributors.md`) - *3346字，substantial* +- [x] **友联与推荐** (`community/friends.md`) - *1030字，substantial* ### 项目共建指南 (16/16) @@ -157,10 +160,10 @@ #### 开发环境与工作流 (6/6) - [x] **搭建基础环境** (`community/contributing/development-setup.md`) - *1987字，substantial* - [x] **分支保护策略** (`community/contributing/branch-protection.md`) - *1214字，substantial* -- [x] **网站部署** (`community/contributing/deployment.md`) - *1849字，substantial* -- [x] **智能 PR 验证系统** (`community/contributing/pr-workflow-guide.md`) - *3476字，substantial* -- [x] **Tag 系统** (`community/contributing/workflow/tag.md`) - *3255字，substantial* -- [x] **内容完成度分析** (`community/contributing/workflow/todo.md`) - *2151字，substantial* +- [x] **网站部署** (`community/contributing/deployment.md`) - *939字，substantial* +- [x] **PR 校验工作流** (`community/contributing/pr-workflow-guide.md`) - *1105字，substantial* +- [x] **Tag 系统** (`community/contributing/workflow/tag.md`) - *3272字，substantial* +- [x] **内容完成度分析** (`community/contributing/workflow/todo.md`) - *2169字，substantial* #### 开发实践指南 (4/4) - [x] **调整全局样式 (CSS)** (`community/contributing/styling.md`) - *3689字，substantial* @@ -177,5 +180,5 @@ - [x] **一份开发手记** (`community/contributing/development-log.md`) - *3868字，substantial* ## 索引 (2/2) -- [x] **标签索引** (`tags.md`) - *1512字，substantial* -- [x] **项目进度** (`COMPLETION_REPORT.md`) - *8266字，substantial* \ No newline at end of file +- [x] **标签索引** (`tags.md`) - *1581字，substantial* +- [x] **项目进度** (`COMPLETION_REPORT.md`) - *8642字，substantial* \ No newline at end of file diff --git a/docs/community/contributing/deployment.md b/docs/community/contributing/deployment.md index bf88f99e..c38f8c4f 100644 --- a/docs/community/contributing/deployment.md +++ b/docs/community/contributing/deployment.md @@ -8,61 +8,56 @@ tags: - Context-Project --- -# 网站部署指南：自动化与规范 +# 网站部署指南 -本文档解释了 `CS for NCU` 项目网站的部署流程。我们采用了一套基于 GitHub Actions 的自动化工作流，以确保每一次发布都是**安全、可靠且一致的**。 +本文档只描述仓库中当前**真实存在**的部署行为，事实来源为 `.github/workflows/deploy-docs.yml`。 ---- - -## 核心理念：发布权由“系统”而非“个人”掌管 - -在多人协作的项目中，如果允许任何人随时从自己的电脑上手动发布网站，将会导致一系列问题： +## 触发条件 -* **绕过审查**：未经同事 review 的内容可能被直接发布上线。 -* **环境不一致**：不同开发者的本地环境差异，可能导致构建出的网站效果千奇百怪。 -* **缺乏追溯**：难以清晰地追溯每一次线上更新对应的是哪一次代码提交。 +当前生产部署工作流支持两种触发方式： -!!! success "我们的解决方案" - 我们将发布权从“**不确定的个人**”手中，转移到了“**可靠的自动化系统**”上。只有当代码通过了审查并被合并到主分支 `main` 后，系统才会自动执行**最终的**正式发布。 - ---- +1. **推送到 `main` 分支 (`push`)** + - 当变更进入 `main` 后，会触发正式部署。 +2. **手动触发 (`workflow_dispatch`)** + - 维护者可在 GitHub Actions 页面手动执行一次部署。 -## 自动化部署工作流 (`deploy-docs.yml`) +除此之外，本文档不假定存在额外的预览部署工作流。 -我们的自动化部署流程定义在仓库的 `.github/workflows/deploy-docs.yml` 文件中。 +## 当前部署流程 -### 触发条件 +部署工作流会按如下顺序执行： -工作流由两种事件触发： +1. 检出仓库代码。 +2. 配置 Python 3.12 环境。 +3. 安装 `uv` 并恢复依赖缓存。 +4. 运行 `uv sync` 安装依赖。 +5. 启用 `git-committers` 相关环境变量后执行严格构建。 +6. 将生成的 `site/` 发布到 GitHub Pages。 -1. **推送到 `main` 分支 (`push`)**： - * **合并 PR 时**：当一个 Pull Request 被合并到 `main` 分支，此事件触发，执行**正式的网站发布**。 - * **直接推送到你自己的分支时**：当你将本地分支推送到你在 GitHub 上的 Fork 仓库时，此事件同样会触发。这会运行一套**预览部署**。 +其中，构建命令以严格模式为准： -2. **手动触发 (`workflow_dispatch`)**： - * 允许项目维护者在 GitHub Actions 页面手动运行部署，用于特殊情况。 +```bash +uv run mkdocs build --clean --strict --verbose +``` -### 核心步骤 - -无论由何种事件触发，工作流都将执行一套标准化的构建与部署流程： +## 这对贡献者意味着什么？ -1. **环境准备**：在一个纯净、统一的 `ubuntu-latest` 虚拟环境中，使用 `uv` 和缓存机制快速安装所有依赖。 -2. **构建网站**：运行 `uv run mkdocs build --strict` 命令。`--strict` 参数会确保任何构建警告（如错误的内部链接）都导致流程失败，从而提前暴露问题。 -3. **部署到 Pages**：将构建生成的 `site` 目录中的内容，安全地推送到触发工作流的那个仓库的 `gh-pages` 分支。 +- 贡献者**不需要**在本地执行部署命令。 +- 贡献者应重点关注本地预览与 PR 校验是否通过。 +- 真正影响线上站点的自动部署，发生在变更进入 `main` 之后，或由维护者手动触发时。 ---- +## 本地建议验证 -## 这对贡献者意味着什么？ +在发起 PR 前，建议至少执行以下命令： -!!! tip "你的工作流程：简单且带“预览”功能" - 作为贡献者，你**完全不需要在本地执行任何部署命令**。你的工作流程如下： +```bash +uv sync +uv run mtag check +uv run mkdocs build --clean --strict --verbose +``` - 1. **本地修改**：在你自己的分支上完成内容的创作和修改。 - 2. **推送进行“预部署”检查（可选但推荐）**： - * 将你的本地分支推送到你在 GitHub 上的 Fork 仓库 (`git push origin your-branch-name`)。 - * 这个 `push` 动作会触发你的 Fork 仓库中的 GitHub Actions 工作流。 - * **你可以进入你的 Fork 仓库的 Actions 页面，查看构建是否成功。** 这就像一次“彩排”，能帮你提前发现本地预览时没注意到的问题（比如链接错误），确保你的代码在真实的构建环境中是健康的。 - 3. **发起 Pull Request**：当你确认一切无误后，向我们的主仓库发起 PR。 - 4. **等待合并与正式发布**：一旦你的 PR 被审查并合并到 `main` 分支，主仓库的 GitHub Actions 会被再次触发，这一次，它将执行**最终的、正式的网站发布**。 +如果你修改了内容完成度分析相关逻辑，也可以补充执行： -这套流程不仅保证了项目质量，也为你提供了一个强大的“云端构建”工具，让你的贡献过程更加自信和顺畅 +```bash +uv run cana --quiet +``` diff --git a/docs/community/contributing/pr-workflow-guide.md b/docs/community/contributing/pr-workflow-guide.md index e2519e4d..bab11220 100644 --- a/docs/community/contributing/pr-workflow-guide.md +++ b/docs/community/contributing/pr-workflow-guide.md @@ -1,230 +1,72 @@ -# 智能 PR 验证工作流系统使用指南 +# Pull Request 校验工作流指南 -本文档介绍了新实现的智能 PR 验证工作流系统，这是一套符合生产级别标准的自动化解决方案。 +本文档描述仓库中当前真实存在的 PR 校验流程，事实来源为 `.github/workflows/pr-validation.yml`。 -## 🎯 系统概览 +## 触发条件 -我们的智能 PR 验证系统包含三个核心工作流： +PR 校验工作流会在以下场景运行： -1. **🔍 智能 PR 验证与预览** (`pr-preview.yml`) - 智能检测文件变更并自动构建预览 -2. **🚀 生产环境部署** (`deploy-docs.yml`) - 增强的生产部署，包含自动清理功能 -3. **🧹 清理 PR 预览环境** (`cleanup-pr-preview.yml`) - PR 关闭时自动清理预览资源 +- `pull_request` +- 事件类型：`opened`、`synchronize`、`reopened` +- 目标分支：`main` -## 🔍 智能文件检测机制 +## 校验目标 -### 会触发构建的文件类型 +当前工作流聚焦于三件事： -当你的 PR 包含以下文件变更时，系统会自动触发文档构建： +1. **变更检测**：只有当变更影响到文档、配置、工具或校验工作流本身时，才继续执行后续构建。 +2. **依赖同步**：运行 `uv sync`，确保 CI 环境与项目声明一致。 +3. **质量校验**：先执行标签检查，再执行严格模式构建。 -| 文件类型 | 模式 | 说明 | -|---------|------|------| -| 文档内容 | `docs/` | 所有文档目录下的文件 | -| 配置文件 | `mkdocs.yml` | MkDocs 主配置文件 | -| 依赖配置 | `pyproject.toml` | Python 项目依赖配置 | -| 主题覆盖 | `overrides/` | 自定义主题文件 | -| 工作流文件 | `.github/workflows/` | GitHub Actions 工作流 | -| 首页文档 | `README.md` | 项目首页文档 | +## 实际执行步骤 -### 会跳过构建的文件类型 +当工作流判断本次 PR 需要校验时，会按顺序执行： -以下文件变更不会触发文档构建，提高效率： - -| 文件类型 | 模式 | 说明 | -|---------|------|------| -| 课程作业 | `class0/` | 课程作业和练习文件 | -| 主程序 | `main.py` | 主要 Python 程序文件 | -| 草稿内容 | `drafts/` | 草稿和临时文档 | -| 配置文件 | `.gitignore`, `.mailmap`, `.markdownlint.yaml`, `.python-version` | 各种配置文件 | -| 锁定文件 | `uv.lock` | 依赖锁定文件 | -| 问题报告 | `issues/` | 问题报告和讨论 | - -### 安全策略 - -**对于未知文件类型，系统默认触发构建**，确保不遗漏任何可能影响文档的变更。 - -## 🚀 PR 工作流程 - -### 1. 创建 Pull Request - -当你创建 PR 后，智能检测系统会立即开始工作： +1. 检出 PR 对应代码。 +2. 计算与基线相比的变更文件。 +3. 判断是否命中文档站点相关路径。 +4. 设置 Python 3.12。 +5. 安装 `uv` 并恢复依赖缓存。 +6. 运行： ```bash -🔍 智能文件变更检测 - ├── 分析变更的文件列表 - ├── 应用检测模式 - └── 决定是否需要构建 +uv sync +uv run mtag check +uv run mkdocs build --clean --strict --verbose ``` -### 2. 自动状态通知 - -系统会在你的 PR 中自动添加状态评论： - -#### 开始构建 -``` -## 📋 PR 预览构建状态 - -🔄 **正在构建中...** - -📁 **检测到的相关文件变更:** -``` -docs/new-guide.md -mkdocs.yml -``` - -⏳ 请稍候，文档正在构建和部署中... -``` - -#### 构建成功 -``` -## 📋 PR 预览构建状态 - -✅ **构建成功！** - -🌐 **预览链接:** [查看预览网站](https://your-username.github.io/cs4ncu/pr-preview/pr-123/) - -🎉 恭喜！您的文档变更已成功构建并部署到预览环境。 -``` - -#### 智能跳过 -``` -## 📋 PR 预览构建状态 - -⏭️ **智能跳过构建** - -📁 **检测到的文件变更:** -``` -class0/assignment.py -main.py -``` - -🎯 **跳过原因:** 本次变更不涉及文档相关文件，无需构建预览。 -``` - -### 3. 严格构建验证 - -当触发构建时，系统执行严格的质量检查： - -- **📝 严格模式构建**: 使用 `--strict` 确保无警告 -- **📊 构建质量检查**: 验证必要文件生成、统计文件数量 -- **🔒 环境隔离验证**: 检查是否包含开发环境残留 -- **🌐 独立预览部署**: 部署到 `pr-preview/pr-{number}/` 子目录 - -### 4. 预览环境访问 +## 本地模拟 CI 的推荐命令 -构建成功后，你可以通过以下链接访问预览： +在提交 PR 前，建议你在本地按接近 CI 的方式验证： +```bash +uv sync +uv run mtag check +uv run mkdocs build --clean --strict --verbose ``` -https://{用户名}.github.io/{仓库名}/pr-preview/pr-{PR编号}/ -``` - -例如：`https://ywh555hhh.github.io/cs4ncu/pr-preview/pr-123/` - -## 🧹 自动清理机制 - -### PR 关闭时清理 - -当 PR 被关闭或合并时，系统会： - -1. **立即清理** PR 对应的预览环境 -2. **删除目录** `pr-preview/pr-{number}/` -3. **通知确认** 在 PR 中添加清理完成通知 - -### 定期清理 - -生产部署时，系统会： - -1. **扫描所有预览环境** -2. **检查对应 PR 状态** -3. **清理已关闭 PR 的预览** - -## 🔧 故障排除 - -### 构建失败 - -如果构建失败，检查以下常见问题： - -1. **Markdown 语法错误** - ```bash - # 本地验证 - uv run mkdocs build --strict - ``` - -2. **链接错误** - - 检查相对路径是否正确 - - 确认引用的文件是否存在 - -3. **图片路径错误** - - 验证图片文件是否提交 - - 检查路径大小写是否正确 -### 预览环境访问问题 +如果你的改动涉及完成度分析逻辑或其生成结果，也可以补充： -1. **404 错误**: 等待 2-3 分钟让 GitHub Pages 生效 -2. **样式问题**: 检查 `base_url` 配置是否正确 -3. **缓存问题**: 尝试强制刷新浏览器 (`Ctrl+F5`) - -## 📈 性能优化 - -### 智能缓存 - -系统使用多层缓存优化： - -- **依赖缓存**: 缓存 Python 虚拟环境 -- **构建缓存**: 区分生产和预览环境 -- **并发控制**: 同一 PR 多次推送只保留最新构建 - -### 资源管理 - -- **存储优化**: 自动清理过期预览环境 -- **构建优化**: 跳过不相关文件变更 -- **网络优化**: 预览环境独立部署，不影响生产 - -## 🛡️ 安全考虑 - -### 权限控制 - -工作流使用最小权限原则： - -```yaml -permissions: - contents: read # 读取仓库内容 - pull-requests: write # 写入 PR 评论 - pages: write # 部署到 GitHub Pages - id-token: write # 用于环境认证 +```bash +uv run cana --quiet ``` -### 环境隔离 - -- **完全独立**: 预览环境与生产环境完全隔离 -- **路径隔离**: 使用 `pr-preview/` 前缀防止冲突 -- **清理机制**: 确保敏感信息不会残留 - -## 💡 最佳实践 - -### 为贡献者 - -1. **小而频繁的提交**: 更容易触发增量构建 -2. **本地预览**: 推送前先本地验证 `mkdocs serve` -3. **描述性提交信息**: 帮助 reviewers 理解变更 -4. **关注构建状态**: 及时修复构建问题 - -### 为维护者 +## 常见关注点 -1. **及时审查**: 预览环境让审查更直观 -2. **合并策略**: 使用 Squash merge 保持历史清晰 -3. **定期维护**: 检查自动清理是否正常工作 +### 为什么有时 PR 不会继续构建？ -## 🔗 相关链接 +因为工作流先做了文件变更检测。若本次改动没有命中 `docs/`、`mkdocs.yml`、`tools/` 或 PR 校验工作流自身，就会跳过后续步骤。 -- [GitHub Actions 文档](https://docs.github.com/actions) -- [MkDocs 官方文档](https://www.mkdocs.org/) -- [GitHub Pages 部署指南](https://docs.github.com/pages) -- [项目贡献指南](../contributing/how-to-contribute.md) +### 当前并不存在什么？ ---- +为避免误解，这里明确说明： -测试新的流程 +- 当前仓库**没有** `pr-preview.yml` +- 当前仓库**没有** `cleanup-pr-preview.yml` +- 当前文档不再假定存在自动预览站点、PR 关闭后清理预览目录等能力 -🤖 本文档由智能 PR 验证工作流系统自动维护 +## 对贡献者的建议 ---- +- 文档改动优先本地预览：`uv run mkdocs serve` +- 提交前至少执行一次严格构建 +- 若修改标签相关内容，记得运行 `uv run mtag check` diff --git a/docs/community/contributing/workflow/tag.md b/docs/community/contributing/workflow/tag.md index 8a799c6d..a058f21f 100644 --- a/docs/community/contributing/workflow/tag.md +++ b/docs/community/contributing/workflow/tag.md @@ -51,13 +51,13 @@ tags: ### 单一事实来源 (Single Source of Truth) -项目中所有合法的、官方认可的标签都被统一记录在根目录下的 `tag_dictionary.yml` 文件中。这个文件是整个标签系统的“宪法”，所有自动化校验都以此为准。**任何时候都不应手动编辑此文件**，应通过我们提供的管理脚本进行维护。 +项目中所有合法的、官方认可的标签都被统一记录在根目录下的 `tag_dictionary.yml` 文件中。这个文件是整个标签系统的“宪法”，所有自动化校验都以此为准。**任何时候都不应手动编辑此文件**，应通过 `uv run mtag sync` 进行维护。 --- ## 自动化管理脚本使用指南 -为了让标签管理变得轻松，我们开发了 `tools/manage_tags.py` 脚本。它是一个强大的助手，能帮你完成所有检查和维护工作。 +为了让标签管理变得轻松，我们提供了统一命令入口 `mtag`。它对应的实现脚本是 `tools/manage_tags.py`，负责完成标签检查与维护。 ### 环境准备 @@ -81,7 +81,7 @@ uv sync **如何运行**： ```bash title="运行交互式同步" -uv run tools/manage_tags.py sync +uv run mtag sync ``` **工作流程**： @@ -93,7 +93,7 @@ uv run tools/manage_tags.py sync 3. **智能管理**： - **拼写建议**：如果某个未知标签与词典中的某个标签非常相似（例如 `Type-Guied` vs `Type-Guide`），它会**智能地询问你是否写错了**，并引导你进行修正。 - **添加新标签**：对于确认无误的新标签，它会询问你是否要将其添加到官方词典中。 -4. **自动更新**：在你确认添加新标签后，脚本会自动更新 `tag_dictionary.yml` 文件，并重新生成 `docs/tags.md` 索引页。 +4. **自动更新**：在你确认添加新标签后，脚本会自动更新 `tag_dictionary.yml` 文件，并重新生成生成文件 `docs/tags.md`。该文件不应手工编辑。 #### 模式二：自动化检查模式 (`check`) @@ -101,7 +101,7 @@ uv run tools/manage_tags.py sync **如何运行 (本地模拟)**： ```bash title="运行自动化检查" -uv run tools/manage_tags.py check +uv run mtag check ``` **工作流程**： @@ -116,6 +116,6 @@ uv run tools/manage_tags.py check !!! alert "安全须知：为何不自动替换？" 脚本在 `sync` 模式下，对于识别出的拼写错误，会引导你**手动修改**文件，而不是自动替换。这是一个安全措施，旨在防止脚本意外地、错误地修改你的文件内容，保证你对每一次修改都有最终的控制权。 -- **保持更新**: 如果你修改了 `tools/manage_tags.py` 脚本本身，请务必在本地运行 `sync` 和 `check` 模式，确保脚本逻辑的正确性。 +- **保持更新**: 如果你修改了 `tools/manage_tags.py` 脚本本身，请务必在本地运行 `uv run mtag sync` 和 `uv run mtag check`，确保脚本逻辑的正确性。 我们相信，通过这套规范的标签系统和强大的自动化工具，`CS4NCU` 知识库的质量和可用性将达到一个新的高度。感谢每一位遵循规范、严谨认真的贡献者！ \ No newline at end of file diff --git a/docs/community/contributing/workflow/todo.md b/docs/community/contributing/workflow/todo.md index a24d1e34..13a60f6d 100644 --- a/docs/community/contributing/workflow/todo.md +++ b/docs/community/contributing/workflow/todo.md @@ -7,7 +7,7 @@ tags: # 内容完成度分析脚本：使用与配置指南 -`tools/completion_analyzer.py` 是 `CS4NCU` 项目的一个内部质量保证工具，旨在自动化地分析整个知识库的内容完成情况。 +`cana` 是 `CS4NCU` 项目的一个内部质量保证工具，对应实现脚本为 `tools/completion_analyzer.py`，旨在自动化地分析整个知识库的内容完成情况。 !!! declaration "设计目的" 本脚本的核心任务是回答一个问题：“我们项目的哪些部分已经充实，哪些部分还是空架子？” @@ -41,7 +41,7 @@ uv sync 直接在项目根目录运行以下命令即可生成最新的报告： ```bash title="执行分析并生成报告" -uv run tools/completion_analyzer.py +uv run cana ``` 脚本执行完毕后，会打印出报告的保存路径和一份简要的完成情况汇总。 @@ -49,7 +49,7 @@ uv run tools/completion_analyzer.py **静默模式**：如果你只想生成报告文件而不在终端看到汇总信息，可以添加 `--quiet` 参数。 ```bash -uv run tools/completion_analyzer.py --quiet +uv run cana --quiet ``` --- @@ -62,7 +62,7 @@ uv run tools/completion_analyzer.py --quiet [tool.completion-analyzer] # --- 可选配置 --- -# Markdown 报告的输出路径 +# Markdown 报告的输出路径（生成文件，请勿手动编辑） md_output = "docs/COMPLETION_REPORT.md" # CSV 报告的输出路径 @@ -84,7 +84,7 @@ good_chars = 500 ## 解读报告 !!! info "如何解读 Markdown 报告？" - 生成的 Markdown 报告 (`COMPLETION_REPORT.md`) 是你了解项目进度的主要窗口。 + 生成的 Markdown 报告 (`COMPLETION_REPORT.md`) 是你了解项目进度的主要窗口。该文件为生成文件，请通过 `uv run cana` 更新，而不要手工修改。 - **层级结构**：报告的标题层级完全复制自 `mkdocs.yml` 中的 `nav` 结构，让你对项目全貌一目了然。 - **进度计数器**：每个章节标题后面都会有一个 `(x/y)` 格式的进度计数器，例如 `(5/12)`，表示该章节下共有 12 篇文章，其中 5 篇被判断为“内容充实”。 diff --git a/docs/community/contributors.md b/docs/community/contributors.md index 8907d7a5..01c262ff 100644 --- a/docs/community/contributors.md +++ b/docs/community/contributors.md @@ -6,19 +6,33 @@ tags: # 寻路人打卡墙 -!!! story "我们的起点故事" - 你好，新朋友！ +这里记录着每一位来过这里、愿意留下足迹的人。 - 这里是 `CS for NCU` 社区的留言板。我们相信，再远的路，也是从迈出第一步开始的。 +它不是成绩榜，也不是资历榜，而是一面很朴素的“第一步纪念墙”：提醒后来者，**开源参与不一定要从很大的事开始，你完全可以先从一次小而完整的贡献做起。** - 为了帮助你轻松迈出参与开源的“第一步”，我们设立了这面打卡墙。你可以在这里留下一句话，完成一次完整的 GitHub 贡献流程。这可能是你与开源世界的第一次握手，我们希望它能轻松、愉快，并给你带来一点小小的成就感。 +如果你是第一次来到这里，建议按这个顺序使用这几页： -这面墙记录着每一位来过这里的朋友。你的留言，不仅是对自己的一个纪念，也是对后来者的一种鼓励——**看，我做到了，你也可以！** +1. 先读 [我们的初心](./our-story.md)，了解这个项目为什么存在 +2. 再看 [打卡指南：完成你的第一次贡献](./how-to-check-in.md)，按步骤走完第一次 PR +3. 回到这面墙，看看大家是怎样留下第一句话的 +4. 如果你还想继续参与，再去看 [贡献流程](./contributing/how-to-contribute.md) -!!! tip "准备好留下你的足迹了吗？" - 我们为你准备了一份 5 分钟的打卡指南，请点击下方链接查阅： +--- + +## 这面墙的意义是什么 + +很多人第一次接触开源时，最大的障碍不是技术本身，而是： + +- 不知道从哪开始 +- 害怕把流程搞错 +- 觉得“自己现在还不够格参与” + +这面墙存在的目的，就是把第一次参与的门槛降到足够低。 - [**打卡指南：完成你的第一次贡献**](./how-to-check-in.md) +你不需要一开始就写长文、修复杂 bug、或者理解完整仓库结构。你只需要完成一次小但完整的协作流程，就已经迈出了很重要的一步。 + +!!! tip "如果你也想留下自己的足迹" + 请先阅读 [打卡指南：完成你的第一次贡献](./how-to-check-in.md)。 --- @@ -55,4 +69,12 @@ tags: * [@wuyanzu828-dev](https://github.com/wuyanzu828-dev) - 塔塔开 (2025-12-27) * [@beijiezaici](https://github.com/beijiezaici) -我是一只刚蜕壳，头一次以自己的声音嘶叫的蝉。 (2026-1-19) * [@AriaLEntropy](https://github.com/AriaLEntropy) - 勇敢为你，无畏地做白日梦。 (2026-2-07) -* [@xue274](https://github.com/xue274) - 来自惠州的打卡，认识你们我很开心。😘 (2026-2-23) \ No newline at end of file +* [@xue274](https://github.com/xue274) - 来自惠州的打卡，认识你们我很开心。😘 (2026-2-23) + +--- + +## 如果你读到这里，下一步可以做什么 + +- 想完成第一次参与：去看 [打卡指南：完成你的第一次贡献](./how-to-check-in.md) +- 想理解更完整的协作方式：去看 [贡献流程](./contributing/how-to-contribute.md) +- 想先理解我们为什么做这件事：回到 [我们的初心](./our-story.md) diff --git a/docs/community/friends.md b/docs/community/friends.md index 0e9bbd2c..43925f5b 100644 --- a/docs/community/friends.md +++ b/docs/community/friends.md @@ -6,24 +6,60 @@ tags: # 友联与推荐 -!!! quote "同行者" - 在寻路的旅程中，我们从不孤单。这里汇聚了与我们理念相近的伙伴们，他们同样在为普通学生的成长而努力。 +这一页不是主入口，而是一份补充性的“同行者清单”。 - 每一个链接背后，都是一个温暖的社区，一份真诚的分享，一次可能的相遇。我们相信，通过友联合作，能够为更多学生提供更全面的成长资源。 +当你已经理解了寻路之南在做什么，也愿意继续探索更多同类项目时，这里可以给你一些额外的方向。 --- -## :material-book-open-variant: Ac-Wiki 大学生的百科全书 +## 为什么有这页 -一个由大学生社区共建的综合性知识库，涵盖校园生活、学术资源、成长通道、通识技能等各个方面。与"寻路之南"理念高度契合，致力于为普通大学生提供实用的成长指南。 +我们并不认为一个项目就能覆盖普通大学生成长中的所有问题。 -**[:octicons-link-external-16: 访问项目](https://ac-wiki.org/)** +恰恰相反，很多值得看的内容，本来就分散在不同的社区、站点和共建项目里。把这些同样认真、同样长期主义的同行者整理出来，一方面是在表达感谢，另一方面也能帮助读者获得更广的视野。 + +所以，这页的职责不是替代本站主线，而是： + +- 给想继续扩展阅读的人提供补充入口 +- 给认同这种共建方式的人展示更多同行项目 +- 为项目之间的互相引用和连接留下空间 --- -## 添加友联 +## 推荐项目 + +### [Ac-Wiki](https://ac-wiki.org/)：大学生的百科全书 + +一个由大学生社区共建的综合性知识库，涵盖校园生活、学术资源、成长通道、通识技能等多个方面。 + +它与寻路之南的关系，不是“谁替代谁”，而更像是两种不同侧重点的互补： -如果你有与"寻路之南"理念相近的项目或资源，欢迎通过 Pull Request 的方式添加友联！ +- 寻路之南更强调普通大学生的成长方法、判断框架与行动路径 +- Ac-Wiki 更像一份覆盖面更广的大学生知识入口 + +如果你想在本站之外继续扩展阅读，这是一个很好的下一站。 + +**[:octicons-link-external-16: 访问 Ac-Wiki](https://ac-wiki.org/)** + +--- + +## 如果你想添加友联 + +如果你有与“寻路之南”理念相近的项目或资源，欢迎通过 Pull Request 的方式添加友联。 + +我们更欢迎这样的项目： + +- 面向普通学生，而不是只服务于极少数样本 +- 内容真实、长期可维护 +- 愿意把经验整理成可被后来者复用的公共资源 !!! note "友联说明" - 本页面的所有链接均为推荐性质，我们不对链接内容的质量和准确性负责。请在使用任何资源前，自行判断其适用性和可靠性。 + 本页面的所有链接都属于推荐性质。请在使用任何外部资源前，自行判断其适用性和可靠性。 + +--- + +## 从这里继续往哪里走 + +- 想回到本站主线：返回 [首页](../index.md) +- 想重新理解项目理念：查看 [我们的初心](./our-story.md) +- 想从围观变成参与：阅读 [打卡指南](./how-to-check-in.md) 与 [贡献流程](./contributing/how-to-contribute.md) diff --git a/docs/community/how-to-check-in.md b/docs/community/how-to-check-in.md index 6b9816ce..fc2b4387 100644 --- a/docs/community/how-to-check-in.md +++ b/docs/community/how-to-check-in.md @@ -8,96 +8,126 @@ tags: # 打卡指南：完成你的第一次贡献 -!!! reminder "欢迎加入我们！" - 你好！这份指南将手把手教你如何通过在“打卡墙”留言，来完成一次标准的 GitHub 开源贡献。 +如果你想从“我认同这个项目”走到“我真的参与了一次”，这页就是最低门槛入口。 - 别担心，整个过程并不复杂。我们会把步骤拆解得很详细，跟着做就行了。这不仅是一次简单的“打卡”，更是一次非常有用的技能练习。学会这个流程，你就能参与到许多其他优秀的开源项目中去。 +它不会要求你一上来就写很长的内容，也不要求你先掌握复杂的开源协作流程。你只需要完成一次最小但完整的 GitHub 贡献：**在打卡墙留下自己的一句话。** + +做完这件事，你至少会得到两样东西： + +1. 你会真实走完一次 Fork / 修改 / Commit / Push / Pull Request 的标准流程 +2. 你会从“围观者”变成“已经参与过一次的人” + +--- + +## 这一步适合谁 + +这份指南特别适合下面几类人： + +- 第一次接触 GitHub，不知道 PR 流程到底是什么 +- 认同项目，但不想一开始就承担太大压力 +- 想先试一次开源协作，建立一点行动感和熟悉度 + +如果你只是想先了解项目理念，建议先看 [我们的初心](./our-story.md)。 +如果你想看看别人是怎么迈出第一步的，可以先去 [路友打卡墙](./contributors.md)。 --- -## 准备工作 +## 开始前，你需要准备什么 !!! declaration "开始前的必备条件" 在开始之前，请确保你已准备好以下两项： - 1. **一个 GitHub 账号** - 整个贡献流程都将围绕 GitHub 进行。如果你还没有账号，可以前往 [GitHub 官网](https://github.com/signup) 免费注册。 + 1. **一个 GitHub 账号** + 如果你还没有账号，可以前往 [GitHub 官网](https://github.com/signup) 免费注册。 + + 2. **Git 环境** + 请确保你的电脑上已经安装了 [Git](https://git-scm.com/downloads)。它是参与开源协作的基础工具。 + +--- + +## 这次打卡你会改哪个文件 + +你需要修改的文件是： + +- `docs/community/contributors.md` + +也就是站内的 [路友打卡墙](./contributors.md)。 - 2. **Git 环境** - 请确保你的电脑上已经安装了 [Git](https://git-scm.com/downloads)。它是一个强大的版本控制工具，也是参与开源协作的基石。 +你只需要在“大家的足迹”下面，按统一格式加上一行自己的名字和一句话。 --- -## 分步指南：完成你的贡献 +## 分步指南：完成你的第一次贡献 -### 第 1 步：Fork 项目 (复制一份到你的名下) +### 第 1 步：Fork 项目 -1. 打开 `CS for NCU` 的 GitHub 仓库：[https://github.com/NCUSCC/cs4ncu](https://github.com/NCUSCC/cs4ncu) -2. 点击页面右上角的 **Fork** 按钮。 -3. 这会把整个项目复制一份到你自己的 GitHub 账号下。你可以把这个“副本”看作你的个人草稿本，可以随意修改，不会影响到原项目。 +1. 打开 `CS for NCU` 的 GitHub 仓库： +2. 点击页面右上角的 **Fork** 按钮。 +3. 这会把整个项目复制到你的 GitHub 账号下。你可以把它理解为“你自己的练习副本”。 -### 第 2 步：Clone 项目 (下载到你的电脑) +### 第 2 步：Clone 到本地 -打开你电脑的终端 (或 Git Bash)，输入下面的命令，把你的项目副本下载到本地。 +打开终端（或 Git Bash），执行： ```bash title="在终端中执行" # 把 "YourGitHubID" 换成你的 GitHub 用户名 git clone https://github.com/YourGitHubID/cs4ncu.git - -# 进入项目文件夹 cd cs4ncu ``` -### 第 3 步：创建分支并修改文件 +### 第 3 步：创建一个分支 -1. **新建一个分支**。在动手修改前新建一个分支是个好习惯，可以把你的改动和主线隔离开。 +```bash title="在终端中执行" +# 分支名可以自定义，比如 add-my-name +git checkout -b add-my-name +``` - ```bash title="在终端中执行" - # 分支名可以自定义，比如 add-my-name - git checkout -b add-my-name - ``` +### 第 4 步：修改打卡墙文件 -2. **找到打卡墙文件** `docs/community/contributors.md`，用你常用的文本编辑器 (比如 VS Code) 打开它。 +打开 `docs/community/contributors.md`，在“大家的足迹”下面加上一行： -3. **在文件末尾的“大家的足迹”下面，加上你的信息**。格式如下： +```markdown title="docs/community/contributors.md" +* [@你的 GitHubID](你的GitHub主页链接) - 随便说点什么 (YYYY-MM-DD) +``` - ```markdown title="docs/community/contributors.md" - * [@你的 GitHubID](你的GitHub主页链接) - 随便说点什么 (YYYY-MM-DD) +??? example "查看一个具体示例" + ```markdown + * [@liming](https://github.com/liming) - 大家好，我是小明，前来报到！ (2024-05-21) ``` - ??? example "查看一个具体示例" - ```markdown - * [@liming](https://github.com/liming) - 大家好，我是小明，前来报到！ (2024-05-21) - ``` +### 第 5 步：保存并提交修改 + +```bash title="在终端中执行" +git add docs/community/contributors.md +git commit -m "docs: add my signature to the wall" +``` -### 第 4 步：保存并提交你的修改 +### 第 6 步：推送到你的 GitHub 仓库 -1. **保存文件**。然后回到终端，用 `git add` 命令告诉 Git 你修改了这个文件： +```bash title="在终端中执行" +# "add-my-name" 是你刚刚创建的分支名 +git push origin add-my-name +``` - ```bash title="在终端中执行" - git add docs/community/contributors.md - ``` +### 第 7 步：发起 Pull Request -2. **提交你的修改**，并写一条说明（即引号内容），告诉别人你做了什么： +1. 回到你 GitHub 上的项目副本页面：`https://github.com/YourGitHubID/cs4ncu` +2. 页面上通常会出现黄色提示，点击 **Compare & pull request** +3. 检查信息无误后，点击 **Create pull request** - ```bash title="在终端中执行" - git commit -m "docs: add my signature to the wall" - ``` +!!! success "恭喜你，完成了" + 现在，你已经完成了一次标准的开源贡献流程。 -3. **把你的修改推送到 GitHub 上的个人副本**： + 维护者看到后会审核并合并。合并之后，你就能在 [路友打卡墙](./contributors.md) 上看到自己的留言。 - ```bash title="在终端中执行" - # "add-my-name" 是你刚刚创建的分支名 - git push origin add-my-name - ``` +--- -### 第 5 步：发起 Pull Request (请求合并) +## 完成这一步之后，接下来读什么 -1. 回到你在 GitHub 上的项目副本页面 (`https://github.com/YourGitHubID/cs4ncu`)。 -2. 页面上会出现一个黄色的提示，旁边有一个绿色的 **Compare & pull request** 按钮，点击它。 -3. 在新页面检查一下信息，然后点击 **Create pull request** 按钮。 +如果你做完打卡，想继续往前走，建议按这个顺序继续： -!!! success "恭喜你，完成了！🎉" - 现在，你已经成功地向 `CS for NCU` 项目提交了一个 Pull Request (PR)。项目的维护者会看到你的申请，并尽快把它合并（Merge）进去。之后，你就可以在打卡墙上看到你的留言了！ +1. [路友打卡墙](./contributors.md) +2. [贡献流程](./contributing/how-to-contribute.md) +3. [写作规范](./contributing/writing-guide.md) - 恭喜你解锁了开源贡献新技能！ +这样你会从“完成第一次参与”，过渡到“开始理解怎样持续贡献”。 diff --git a/docs/community/our-story.md b/docs/community/our-story.md index d38656f4..ce9eba76 100644 --- a/docs/community/our-story.md +++ b/docs/community/our-story.md @@ -1,3 +1,169 @@ -# 初心 +--- +tags: + - Type-Guide + - Level-Beginner + - Topic-MindsetModel + - Action-Thinking +--- -初心如此 +# 我们的初心 + +如果只用一句话概括，**寻路之南是一份写给普通大学生的开源成长指南**。 + +它想解决的，不是“怎样包装出一个漂亮履历”，而是一个更底层的问题：**当你没有现成路线、没有绝对优势、也没有人替你做决定时，你如何一点点建立自己的判断、行动和成长系统。** + +--- + +## 我们是谁 + +我们是一群普通本科生，也是这个项目最初的读者原型。 + +我们并不是站在已经功成名就的位置回头总结，也不是以“标准答案提供者”的姿态告诉别人该怎么活。相反，我们更接近大多数大学生真实会处在的位置： + +- 会迷茫 +- 会信息过载 +- 会在各种经验贴之间来回摇摆 +- 会一边羡慕别人，一边怀疑自己 +- 会想认真改变，但又不知道第一步该从哪里踩下去 + +所以，寻路之南从一开始就不是“过来人给后来人的训话”，而是**一群仍在路上的人，为同样在路上的人整理出的第一版地图。** + +--- + +## 为什么要做这件事 + +大学里最不缺的，是碎片化建议。 + +你会很容易看到很多内容在告诉你： + +- 该不该转专业 +- 要不要考研 +- 怎么卷实习 +- 什么比赛值得打 +- 哪种路线更有前途 + +但真正稀缺的是另一类内容： + +- 在做选择之前，怎么先看清自己？ +- 面对大量外部声音时，怎么判断哪些信息值得信？ +- 当你没有把握时，怎么用低成本方式先试一试？ +- 当你不是“天赋异禀的主角模板”时，怎么建立一条现实可行的路径？ + +我们想做的，就是把这些更底层、更普适、也更少被系统讲清楚的东西整理出来。 + +--- + +## 这不是一个什么项目 + +### 这不是鸡汤项目 + +我们当然相信鼓励有价值，但我们不想只提供情绪价值。 + +如果一段内容不能帮助读者更好地理解自己、理解世界、或推进下一步行动，那它就不够。 + +### 这不是学校官网替代品 + +学校官网、教务系统、学院通知各有自己的职责。寻路之南不会试图替代它们。 + +我们更关注的是：**普通学生该怎样理解这些制度、资源和机会，并把它们放回自己的成长路径里。** + +### 这不是只写精英样本的经验陈列馆 + +我们不会把项目做成“少数已经赢得很漂亮的人，向后来者展示自己的胜利轨迹”。 + +精英样本当然值得看，但它常常带着强烈的起点偏差、资源偏差与幸存者偏差。对多数人来说，真正有参考意义的不是“别人最辉煌的结果”，而是**在普通起点下，怎样一步步建立更稳的判断与行动能力。** + +--- + +## 它是写给谁的 + +这份站点首先写给这样的人： + +- 刚进入大学，还不知道该如何理解接下来的几年 +- 已经读了一段时间大学，但仍然常常觉得自己在被推着走 +- 不满足于“听别人说该怎么做”，想逐步建立自己的判断 +- 不一定是最耀眼的人，但愿意认真对待自己的成长 + +它也写给那些愿意帮助后来者的人： + +- 愿意把自己的经验整理成可复用内容的人 +- 愿意补全校园信息与行动指南的人 +- 愿意一起把这个项目做得更可靠、更开放的人 + +--- + +## 站点的内容结构与边界 + +目前站点主要有 4 个板块： + +1. **开始之前**：给第一次来的读者一个稳定起点 +2. **寻路通识课**：本站当前最核心的方法论主线 +3. **第零点五课堂**：按主题补齐学习、沟通、工具、成长等底层能力 +4. **社区与共建 / 昌大专属**：分别承担项目故事、参与入口与校园场景内容 + +但我们也想把边界说清楚： + +- 这不是一个已经“全都写完”的站点 +- 不是每个专题都已经成熟到可作为主推入口 +- 当前版本更关注把高曝光页面、核心路径和成熟内容先做稳 + +换句话说，**这是一个正在持续建设中的公共项目，而不是一份已经封箱定稿的手册。** + +--- + +## 为什么选择开源共建 + +因为这类内容不适合只由少数人长期垄断生产。 + +大学生的真实问题会变，校园环境会变，工具和机会会变，读者真正卡住的地方也会变。只有把它做成一个开源项目，才有可能不断吸收新的经验、纠错旧的叙述、补全遗漏的视角。 + +开源还有另外一层意义： + +- 它让内容可以被讨论，而不是只能被接受 +- 它让贡献门槛可以从很小的地方开始，而不是非得“很厉害才能参与” +- 它让这个项目更像一个共同维护的公共空间，而不是一个封闭品牌 + +我们希望这里既能成为一份指南，也能成为一条通往参与、协作和互助的入口。 + +--- + +## 读者和贡献者可以怎样参与 + +### 如果你先想作为读者开始 + +建议从下面这条链路进入： + +1. [首页](../index.md) +2. [第负一课：先别慌，我们聊聊](../growth-general-course/00-before-we-start/prologue-the-start.md) +3. [全站导览与官方推荐路径](../growth-general-course/00-before-we-start/overview.md) + +### 如果你想先感受社区氛围 + +可以继续阅读： + +1. [打卡教程](./how-to-check-in.md) +2. [路友打卡墙](./contributors.md) +3. [友联与推荐](./friends.md) +4. [贡献流程](./contributing/how-to-contribute.md) + +### 如果你想直接参与共建 + +你可以从这些最常见的方式开始： + +- 提交错别字、病句、失效链接修正 +- 补充某个专题页的基础信息 +- 分享一段对后来者真正有帮助的经验 +- 提出 Issue，告诉我们哪里还不够清楚、哪里仍然让人迷路 + +!!! tip "如果你是第一次参与开源" + 你不需要一上来就写很大的内容。先跟着 [打卡教程](./how-to-check-in.md) 走完第一次贡献流程，再去看 [贡献流程](./contributing/how-to-contribute.md)，会更容易进入状态。 + +--- + +## 最后，回到那句最重要的话 + +寻路之南并不承诺替你给出答案。 + +我们更想做的是另一件事：**帮你在纷乱的信息和不确定的现实里，慢慢长出自己的判断能力。** + +如果这件事也正是你在寻找的，那你已经在正确的入口上了。 \ No newline at end of file diff --git a/docs/css/05-404.css b/docs/css/05-404.css new file mode 100644 index 00000000..535edca9 --- /dev/null +++ b/docs/css/05-404.css @@ -0,0 +1,68 @@ +/* 404 页面样式 */ +.not-found-container { + max-width: 700px; + margin: 0 auto; + padding: 2rem 1rem; + text-align: center; +} + +.not-found-header h1 { + font-size: 6rem; + font-weight: 700; + margin: 0; + color: var(--md-default-fg-color--light); +} + +.not-found-header p { + font-size: 1.5rem; + margin-top: 0.5rem; + margin-bottom: 2.5rem; +} + +#countdown-container { + font-size: 1.1em; + padding: 1.5em; + margin-bottom: 2.5rem; + border: 1px solid var(--md-default-fg-color--lightest); + background-color: var(--md-code-bg-color); + border-radius: 0.2rem; + transition: opacity 0.3s ease-out; +} + +#countdown-timer { + font-size: 1.5em; + font-weight: 700; + color: var(--md-accent-fg-color); +} + +#cancel-redirect-link { + color: var(--md-accent-fg-color); + text-decoration: none; + border-bottom: 1px dashed var(--md-accent-fg-color); +} + +.reason-box { + padding: 1.5em; + border-radius: 0.2rem; + background-color: var(--md-admonition-bg-color); +} + +.reason-box h3 { + margin-top: 0; +} + +.reason-box ul { + list-style-type: none; + padding: 0; + margin-bottom: 0; +} + +#action-container { + margin-top: 2.5em; + padding-top: 1.5em; + border-top: 1px solid var(--md-default-fg-color--lightest); +} + +#action-links-container a { + margin: 0 0.75em; +} diff --git a/docs/css/extra.css b/docs/css/extra.css index 75083718..67c5d2d7 100644 --- a/docs/css/extra.css +++ b/docs/css/extra.css @@ -16,4 +16,5 @@ @import "02-components.css"; /* 组件：定义通用 UI 组件的样式，如链接、表格 */ @import "03-admonitions.css"; /* 插件：定义 admonition (提示框) 等插件的特定样式 */ @import "04-reading-progress.css"; /* 插件：定义阅读进度的样式 */ +@import "05-404.css"; /* 页面：定义 404 页面样式 */ @import "99-fixes.css"; /* 修复：包含高优先级的样式，用于修正或覆盖特定问题 */ diff --git a/docs/growth-general-course/00-before-we-start/overview.md b/docs/growth-general-course/00-before-we-start/overview.md index ba6db661..472be79f 100644 --- a/docs/growth-general-course/00-before-we-start/overview.md +++ b/docs/growth-general-course/00-before-we-start/overview.md @@ -1,6 +1,195 @@ -# 目录与导览 +--- +tags: + - Type-Guide + - Level-Beginner + - Action-Learning + - Action-Building +--- -等 第一个 公开 β 版本 准备公开时再弄，避免返工 +# 全站导览与官方推荐路径 -!!! danger "警告" - 本文仍属于草案阶段 \ No newline at end of file +如果你是第一次来到这里，可以把这一页当作本站的“地图 + 导航台”。 + +它会帮你快速回答 4 个问题： + +1. 这是什么项目？ +2. 这站内容大致分成哪几块？ +3. 我这种读者应该从哪里开始？ +4. 现在最值得优先读的官方路径有哪些？ + +!!! tip "如果你只想立刻开始" + - 想从最稳妥的起点开始：先读 [《第负一课：先别慌，我们聊聊》](./prologue-the-start.md) + - 想直接进入核心方法论：去看 [《核心原则》](../01-the-zero-course/the-core.md) + - 想按主题挑一条路线：直接跳到下方的[官方推荐路径](#官方推荐路径) + +--- + +## 本站的 4 大板块 + +### 1. 开始之前：帮助你找准起点 + +这一部分不是知识堆砌，而是“进入本站前的缓冲区”。 + +你会在这里看到： + +- [《第负一课：先别慌，我们聊聊》](./prologue-the-start.md)：适合刚进站、刚入学、刚陷入焦虑时先读 +- 当前这页“全站导览”：适合想先看全局、按路线阅读的人 + +如果你现在最需要的是一个不慌乱的开始，请从这里起步。 + +### 2. 寻路通识课：本站最核心的方法论主线 + +这是本站当前最应该优先阅读的主体内容。 + +它围绕一个核心问题展开：**普通大学生，如何在不确定里建立自己的判断与行动系统。** + +核心入口包括： + +- [《核心原则：构建你的个人决策系统》](../01-the-zero-course/the-core.md) +- [《完整课程导览》](../01-the-zero-course/index.md) +- 第一部分：决策的基础 +- 第二部分：决策的依据 +- 第三部分：决策的实践 + +如果你不知道该先想什么、先学什么、先做什么，这一块就是默认主路径。 + +### 3. 第零点五课堂：按主题补齐底层能力 + +这部分像一个不断扩展的能力模块区，覆盖那些学校往往讲得太晚、太散、或者根本不会系统讲的内容。 + +目前包含 5 个方向： + +- [认知与心智](../../skills/mindset/index.md) +- [学会学习](../../skills/learning/index.md) +- [沟通与协作](../../skills/communication/index.md) +- [工具与系统](../../skills/tools/index.md) +- [成长与规划](../../skills/growth/index.md) + +如果你已经有一个大方向，只想补某项能力，可以从这里按需进入。 + +### 4. 社区与共建 / 昌大专属 + +这两块承担的是不同职责： + +- [社区与共建](../../community/our-story.md)：适合想理解项目理念、参与共建、或看看社区氛围的人 +- [昌大专属](../../ncu-exclusive/index.md)：适合南昌大学同学查阅本校场景下的经验与入口信息 + +!!! note "关于内容边界" + 本站正在持续建设中。我们当前优先保证高曝光入口页、核心路径和成熟内容可稳定阅读；部分专题仍在补完中，因此你会看到一些区域还在逐步充实。 + +--- + +## 你属于哪一类读者？ + +### 如果你是第一次来的新读者 + +建议顺序： + +1. [第负一课：先别慌，我们聊聊](./prologue-the-start.md) +2. [核心原则：构建你的个人决策系统](../01-the-zero-course/the-core.md) +3. [完整课程导览](../01-the-zero-course/index.md) + +适合你，如果你现在最需要的是： + +- 搞清楚这个站到底在讲什么 +- 先建立一个不慌乱的判断框架 +- 不想一上来就被大量页面淹没 + +### 如果你已经有困惑，但希望系统思考 + +建议从 [本科生通识第零课](../01-the-zero-course/index.md) 开始，按“向内看 → 向外看 → 去行动”的顺序推进。 + +适合你，如果你正在面对： + +- 专业选择、方向迷茫 +- 信息太多，不知道怎么判断 +- 想从“听别人建议”切换到“自己做决策” + +### 如果你已经有明确问题，只想补一个能力点 + +可以直接进入 [第零点五课堂](../../skills/index.md)，按模块选读。 + +适合你，如果你现在更想解决的是： + +- 学习效率 +- 沟通协作 +- 工具使用 +- 成长规划 + +### 如果你想先了解这个项目是否值得信任 + +建议先读： + +1. [我们的初心](../../community/our-story.md) +2. [打卡教程](../../community/how-to-check-in.md) +3. [路友打卡墙](../../community/contributors.md) +4. [贡献流程](../../community/contributing/how-to-contribute.md) + +适合你，如果你关心的是： + +- 这个项目到底在做什么 +- 它和常见经验贴有什么不同 +- 如果认同理念，可以怎样参与 + +--- + +## 官方推荐路径 + +以下是当前第一批官方主推路线。它们只使用本站现阶段相对成熟、可连续阅读的内容，不会故意把你带进明显空白页。 + +### 路径一：新读者起步路径 + +**适合谁：** 第一次来到本站、刚入学、最近很乱、需要先找到一个稳定起点的人。 + +**你能获得什么：** 先安顿情绪，再理解本站的核心方法论，并知道后续该怎么继续读。 + +1. [首页](../../index.md) +2. [第负一课：先别慌，我们聊聊](./prologue-the-start.md) +3. [核心原则：构建你的个人决策系统](../01-the-zero-course/the-core.md) +4. [完整课程导览](../01-the-zero-course/index.md) + +### 路径二：决策与自我认知路径 + +**适合谁：** 对专业、方向、选择感到卡住，想先把“我是谁、我该怎么判断”想清楚的人。 + +**你能获得什么：** 建立一个基础决策框架，并把自我认知、思维模式和现实测试串起来。 + +1. [核心原则：构建你的个人决策系统](../01-the-zero-course/the-core.md) +2. [第一部分：决策的基础](../01-the-zero-course/part1/index.md) +3. [第一章：思维模式转换](../01-the-zero-course/part1/ch1-mindset.md) +4. [第二章：自我认知方法](../01-the-zero-course/part1/ch2-the-self.md) +5. [第六章：低成本实践与验证](../01-the-zero-course/part3/ch6-the-test.md) + +### 路径三：学习系统重建路径 + +**适合谁：** 明明很努力，但总觉得学得乱、记不住、精力不够的人。 + +**你能获得什么：** 重新搭建自己的学习输入、学习策略与精力管理系统。 + +1. [第四章：信息获取入门](../01-the-zero-course/part2/ch4-info-gathering.md) +2. [成为学霸的终极秘诀——掌握「元学习」](../../skills/learning/meta/meta-learning.md) +3. [精力管理](../../skills/learning/energy/energy-management.md) + +### 路径四：从读者到参与者路径 + +**适合谁：** 读完后认同项目理念，想进一步围观社区、尝试参与开源的人。 + +**你能获得什么：** 了解项目边界、认识社区氛围，并找到第一次参与的最低门槛入口。 + +1. [我们的初心](../../community/our-story.md) +2. [打卡教程](../../community/how-to-check-in.md) +3. [路友打卡墙](../../community/contributors.md) +4. [贡献流程](../../community/contributing/how-to-contribute.md) + +--- + +## 接下来怎么读最稳妥？ + +如果你不想做复杂选择，可以直接按下面这个顺序走： + +1. [第负一课：先别慌，我们聊聊](./prologue-the-start.md) +2. [核心原则：构建你的个人决策系统](../01-the-zero-course/the-core.md) +3. [完整课程导览](../01-the-zero-course/index.md) +4. 再根据你的问题，回到本页挑选一条官方路径 + +这会是目前最稳定、最不容易迷路的一条主线。 diff --git a/docs/growth-general-course/00-before-we-start/prologue-the-start.md b/docs/growth-general-course/00-before-we-start/prologue-the-start.md index 76d32825..0a5a8c60 100644 --- a/docs/growth-general-course/00-before-we-start/prologue-the-start.md +++ b/docs/growth-general-course/00-before-we-start/prologue-the-start.md @@ -7,9 +7,6 @@ tags: # 第负一课：先别慌，我们聊聊 -!!! danger "警告" - 本文仍属于草案阶段 - 你好，新同学。 欢迎来到大学——一片充满无限可能，也因此充满不确定性的原野。 diff --git a/docs/growth-general-course/01-the-zero-course/part1/ch1-mindset.md b/docs/growth-general-course/01-the-zero-course/part1/ch1-mindset.md index 924ed8c4..dfdab2d8 100644 --- a/docs/growth-general-course/01-the-zero-course/part1/ch1-mindset.md +++ b/docs/growth-general-course/01-the-zero-course/part1/ch1-mindset.md @@ -9,9 +9,6 @@ tags: # 第一章：思维模式转换 -!!! danger "警告" - 本文仍属于草案阶段 - 大学与高中的根本区别，在于你的角色变了：**你必须从一名“乘客”，切换为掌握方向盘的“司机”**。 过去的轨道已经消失，继续沿用“乘客”心态，你只会在原地等待指令。这门课的第一个核心要求，就是让你完成这次思维模式的根本转换。 diff --git a/docs/growth-general-course/01-the-zero-course/part1/ch2-the-self.md b/docs/growth-general-course/01-the-zero-course/part1/ch2-the-self.md index 8b4f6b3b..d57fa1a4 100644 --- a/docs/growth-general-course/01-the-zero-course/part1/ch2-the-self.md +++ b/docs/growth-general-course/01-the-zero-course/part1/ch2-the-self.md @@ -9,9 +9,6 @@ tags: # 第二章：自我认知方法 -!!! danger "警告" - 本文仍属于草案阶段 - 你已切换为“司机”模式。现在，你需要校准你的内部罗盘，为决策提供最核心的内部指引。 本章提供两个工具，帮你完成这次校准。 @@ -63,8 +60,3 @@ tags: 通过本章的工具，我们为“决策黑盒”校准了最关键的**内部罗盘**。但这还不够，一个只进行内部循环的系统是封闭的。 在下一部分，我们将探讨如何为你的决策黑盒，喂养高质量的“燃料”——来自外部世界的信息。 - - -https://ztm0929.cn/notes/geek-lab/advice-for-students/#:~:text=%E6%89%BE%E5%88%B0%E4%BD%A0%E7%9A%84%20ikigai%EF%BC%8C%E6%84%8F%E5%91%B3%E7%9D%80%E6%89%BE%E5%88%B0%E4%BD%A0%E7%83%AD%E7%88%B1%E7%9A%84%E4%BA%8B%E3%80%81%E4%BD%A0%E6%93%85%E9%95%BF%E7%9A%84%E4%BA%8B%E3%80%81%E8%BF%99%E4%B8%AA%E4%B8%96%E7%95%8C%E9%9C%80%E8%A6%81%E7%9A%84%E4%BA%8B%E3%80%81%E4%BB%A5%E5%8F%8A%E8%83%BD%E4%B8%BA%E4%BD%A0%E5%B8%A6%E6%9D%A5%E6%94%B6%E5%85%A5%E7%9A%84%E4%BA%8B%EF%BC%8C%E8%BF%99%E5%9B%9B%E8%80%85%E7%9A%84%E4%BA%A4%E9%9B%86%E3%80%82 - -找到你的 ikigai，意味着找到你热爱的事、你擅长的事、这个世界需要的事、以及能为你带来收入的事，这四者的交集。 \ No newline at end of file diff --git a/docs/growth-general-course/01-the-zero-course/part1/index.md b/docs/growth-general-course/01-the-zero-course/part1/index.md index 8d6ab448..06028710 100644 --- a/docs/growth-general-course/01-the-zero-course/part1/index.md +++ b/docs/growth-general-course/01-the-zero-course/part1/index.md @@ -9,9 +9,6 @@ tags: # 第一部分：决策的基础 -!!! danger "警告" - 本文仍属于草案阶段 - 要构建你的“决策黑盒”，我们必须先打下坚实的地基。 这台仪器需要两样东西才能启动：一个提供动力的**引擎 (你的思维模式)**，和一个指明方向的**罗盘 (你的自我认知)**。 diff --git a/docs/index.md b/docs/index.md index 9e10359f..286751fa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,116 +2,158 @@ *写给普通人的大学成长指南* -我们和你一样，是普通本科生。我们曾因信息壁垒而困惑，为未来方向而迷茫。 -这个开源项目，是我们尝试为自己，也为你，共同撰写的一份“大学使用说明书”。 +如果你第一次来到这里，可以先记住一句话：**这是一个写给普通大学生的开源成长指南。** + +它不试图给你一份万能答案，而是想帮你在信息混乱、选择很多、又常常缺少方向感的时候，先建立自己的判断和行动系统。 --- -## :material-compass-rose: 准备好迈出第一步了吗？ +## 第一次来，先从这里开始 + +如果你现在只想知道“我第一步该看什么”，请直接走这条主线： + +1. [第负一课：先别慌，我们聊聊](./growth-general-course/00-before-we-start/prologue-the-start.md) +2. [核心原则：构建你的个人决策系统](./growth-general-course/01-the-zero-course/the-core.md) +3. [完整课程导览](./growth-general-course/01-the-zero-course/index.md) -在被海量信息淹没之前，我们想邀请你先完成一次与自己的对话。 -这是我们为你准备的最重要的起点。 +这条路线最适合： -

- 翻开《第负一课：先别慌，我们聊聊》 :octicons-arrow-right-24: -

+- 刚入学，信息很多，脑子很乱 +- 不确定自己是不是适合继续读下去 +- 想先快速理解本站到底在讲什么 --- -## :material-map-search-outline: 地图索引 +## 这是什么项目 -当你准备好开始真正的探索时，这里是你随时可以查阅的地图索引。 +寻路之南是一个由普通本科生发起、持续共建中的开源项目。 -
+我们想解决的，不是“怎么复制少数精英样本的成功轨迹”，而是一个更普遍的问题： -- :material-map-search: **“我想看本站的完整结构”** +**当你没有现成标准答案时，普通大学生怎样一步步完成自我认知、信息判断和现实行动。** - --- - 如果你想快速了解本站的全貌，这里有一份完整的**内容导览**。它像一张世界地图，清晰地展示了所有知识点的位置，**并为你推荐了几条浏览路线**。 +所以这里不会只堆经验贴，也不会把成长理解成单一赛道上的竞速。我们更关注的是那些更底层的问题： - **[:octicons-arrow-right-24: 查看全站导览](./growth-general-course/00-before-we-start/overview.md)** +- 我是谁 +- 我该如何做选择 +- 我该如何获取和判断信息 +- 我怎样用低成本方式开始实践 -- :material-road-variant: **“我需要一条清晰的路线图”** +--- - --- - 这里是我们为你精心设计的**核心成长路径**，它会像一位向导，带你从重塑思维开始，一步步构建起应对大学挑战的完整能力体系。**这，就是我们的‘本科生通识第零课’。** +## 你可以怎样使用这个站 - **[:octicons-arrow-right-24: 浏览通识第零课](./growth-general-course/01-the-zero-course/index.md)** +### 方式一：按主线读 -- :material-treasure-chest: **“我想自由探索特定技能”** +如果你想系统理解本站，优先读： - --- - 这里是不断丰富的**第零点五课堂**。从硬核技术到软性实力，你可以像在宝库中一样，按需取用，随时为自己的工具箱充电。 +- [第负一课：先别慌，我们聊聊](./growth-general-course/00-before-we-start/prologue-the-start.md) +- [全站导览与官方推荐路径](./growth-general-course/00-before-we-start/overview.md) +- [本科生通识第零课](./growth-general-course/01-the-zero-course/index.md) - **[:octicons-arrow-right-24: 进入技能宝库](./skills/index.md)** +### 方式二：按问题选一条官方推荐路径 -- :material-school-outline: **“我是昌大学生，需要‘内部情报’”** +当前第一批官方主推路径如下： - --- - 这里沉淀了独属于南昌大学的**实用信息与经验**。无论是转专业、保研考研，还是如何用好校园资源，这里都有最接地气的答案。 +#### 1. 新读者起步路径 - **[:octicons-arrow-right-24: 查看昌大专属](./ncu-exclusive/index.md)** +**适合谁：** 第一次来、需要稳定起点的人。 -
+**读完你能获得什么：** 先安顿情绪，再理解本站主线和后续阅读方式。 ---- +- [首页](./index.md) +- [第负一课：先别慌，我们聊聊](./growth-general-course/00-before-we-start/prologue-the-start.md) +- [核心原则：构建你的个人决策系统](./growth-general-course/01-the-zero-course/the-core.md) +- [完整课程导览](./growth-general-course/01-the-zero-course/index.md) -## :material-thought-bubble-outline: 我们的故事与初心 +#### 2. 决策与自我认知路径 -### 写一本真正属于普通人的“大学说明书” +**适合谁：** 正在专业、方向、选择上卡住的人。 -我们曾仰望过《上交求生指南》那样的精英灯塔，但很快发现，他们的航线固然璀璨，其起点、风速、洋流都与我们不同。我们需要一份更具普适性的海图，一套更基础、更关注内在的航行方法。 -我们为这份初心，取名为**“寻路之南”**。它是一份“寻路者的指南”，也是一场始于南昌大学的探索。它承载着我们的起点，也指向我们共同的目标：在迷雾中，为自己找到南方——那个温暖、清晰、充满生命力的方向。 -于是，cs4ncu 这个最初的代号，便有了它真正的名字。 +**读完你能获得什么：** 一个更清晰的自我认知和决策框架。 -### 让我们坦诚地面对起点 +- [核心原则：构建你的个人决策系统](./growth-general-course/01-the-zero-course/the-core.md) +- [第一部分：决策的基础](./growth-general-course/01-the-zero-course/part1/index.md) +- [第一章：思维模式转换](./growth-general-course/01-the-zero-course/part1/ch1-mindset.md) +- [第二章：自我认知方法](./growth-general-course/01-the-zero-course/part1/ch2-the-self.md) +- [第六章：低成本实践与验证](./growth-general-course/01-the-zero-course/part3/ch6-the-test.md) -高考，是一次相对苍白的评价，它绝不该完全定义你的人生。但它也是一次现实的筛选。它决定了我们脚下平台的初始高度，我们必须正视由此带来的视野与资源的差距。更重要的，它像一面镜子，邀请我们反思：**是什么样的思维模式、学习习惯，让我们走到了这里？** +#### 3. 学习系统重建路径 -我们探讨这个，不是为了回味一次考试的成败，而是为了完成一次关键的**自我剖析**。这，才是我们这本指南真正的“第零课”。 +**适合谁：** 努力很多，但学习总觉得乱、散、累的人。 -### 我们代表的，是广阔的中间地带 +**读完你能获得什么：** 一个关于输入、方法和精力管理的学习系统雏形。 -也许有人会说，“211”这个标签，谈不上顶尖，却也算不上普通。是的，我们正处在这样一个位置：向上，能看到精英航线的璀璨，并理解那份渴望；向下，也未曾忘记一路走来的崎岖，并懂得其中的挣扎。 +- [第四章：信息获取入门](./growth-general-course/01-the-zero-course/part2/ch4-info-gathering.md) +- [元学习](./skills/learning/meta/meta-learning.md) +- [精力管理](./skills/learning/energy/energy-management.md) -这个位置，让我们得以摆脱纯粹的精英视角或自怨自艾的受害者心态。它让我们相信，我们的故事——一个关于**“在还不错的平台上，如何通过自我认知与系统构建，来超越平台局限”**的故事——对最广大的学生群体，具有最真实的参考意义。 +#### 4. 从读者到参与者路径 -这就是我们的立足点：不仰望神坛，也不俯视深渊，只是脚踏实地，与每一个努力向上的你同行。 +**适合谁：** 想理解项目、看看社区、甚至尝试参与共建的人。 + +**读完你能获得什么：** 知道这个项目在做什么、如何参与，以及社区目前长什么样。 + +- [我们的初心](./community/our-story.md) +- [打卡教程](./community/how-to-check-in.md) +- [路友打卡墙](./community/contributors.md) +- [贡献流程](./community/contributing/how-to-contribute.md) --- -## :material-handshake-outline: 这份指南，期待你来续写 +## 本站主要有什么内容 + +### 1. 开始之前 + +给第一次来的读者一个稳定入口。 -这是一个开源项目，意味着它永远处在“未完成”状态，等待着你的参与和贡献，让它变得更好。 -如果你认同我们的理念，欢迎你加入我们，不只是作为读者，更是作为共建者。 +- [第负一课：先别慌，我们聊聊](./growth-general-course/00-before-we-start/prologue-the-start.md) +- [全站导览与官方推荐路径](./growth-general-course/00-before-we-start/overview.md) -
+### 2. 寻路通识课 -- :material-book-open-page-variant-outline: **阅读贡献指南** +这是本站当前最核心的方法论主线，适合想系统建立判断与行动框架的人。 - --- - 我们建议您首先阅读项目的 **[项目共建指南](./community/contributing/how-to-contribute.md)**，以了解协作的基本流程。 +- [核心原则：构建你的个人决策系统](./growth-general-course/01-the-zero-course/the-core.md) +- [完整课程导览](./growth-general-course/01-the-zero-course/index.md) -- :fontawesome-brands-github-alt: **从 Issue 开始** +### 3. 第零点五课堂 - --- - 您可以从解决一个标记为 **[good first issue](https://github.com/NCUSCC/cs4ncu/labels/good%20first%20issue)** 的任务开始，迈出贡献的第一步。 +适合按主题补能力： -- :simple-qq: **加入 QQ 群讨论** +- [本部分导览](./skills/index.md) +- [认知与心智](./skills/mindset/index.md) +- [学会学习](./skills/learning/index.md) +- [沟通与协作](./skills/communication/index.md) +- [工具与系统](./skills/tools/index.md) +- [成长与规划](./skills/growth/index.md) - --- - 想和我们直接讨论项目？欢迎加入我们的官方项目 **[QQ 交流群](https://qm.qq.com/q/VLuObOsLg4)**。 +### 4. 社区与共建 / 昌大专属 -- :simple-discord: **加入 Discord 社群** +- [我们的初心](./community/our-story.md)：完整理解项目理念与边界 +- [昌大专属](./ncu-exclusive/index.md)：南昌大学场景下的经验入口 - --- - 觉得我们是群很有趣很棒的人？欢迎加入我们的 **[Discord 社区](https://discord.gg/Rux6DHRStP)**，与更多伙伴交流。 +--- + +## 一个更简短的故事版本 + +我们做这个项目，是因为发现大学里最不缺的是碎片化建议，最缺的是一套真正适合普通学生的底层方法。 + +它不是鸡汤，也不是学校官网替代品，更不是只展示精英样本的经验陈列馆。 + +它更像一份还在持续完善的公共地图：先帮你找到起点，再陪你一点点把路走清楚。 + +如果你想看完整版本，可以继续读：[我们的初心](./community/our-story.md)。 + +--- -- :material-handshake: **友联与推荐** +## 想参与的话，从哪里开始 - --- - 在寻路的旅程中，我们从不孤单。这里汇聚了与我们理念相近的伙伴们，他们同样在为普通学生的成长而努力。 +如果你想先了解社区，再决定要不要参与，可以按这条链路走： - **[:octicons-arrow-right-24: 查看友联推荐](./community/friends.md)** +1. [我们的初心](./community/our-story.md) +2. [打卡教程](./community/how-to-check-in.md) +3. [路友打卡墙](./community/contributors.md) +4. [贡献流程](./community/contributing/how-to-contribute.md) -
+如果你只是想从一个低门槛入口开始，也可以直接去看 GitHub 上的 [good first issue](https://github.com/NCUSCC/cs4ncu/labels/good%20first%20issue)。 diff --git a/docs/javascripts/404.js b/docs/javascripts/404.js new file mode 100644 index 00000000..5a90731b --- /dev/null +++ b/docs/javascripts/404.js @@ -0,0 +1,180 @@ +/** + * @file 404.js + * @description 404 页面交互逻辑。 + */ + +(function () { + 'use strict'; + + function joinUrl(base, path) { + return base.replace(/\/+$/, '') + '/' + path.replace(/^\/+/, ''); + } + + function createElement(tagName, options) { + var element = document.createElement(tagName); + if (!options) { + return element; + } + + if (options.text) { + element.textContent = options.text; + } + if (options.href) { + element.href = options.href; + } + if (options.id) { + element.id = options.id; + } + if (options.className) { + element.className = options.className; + } + if (options.target) { + element.target = options.target; + } + if (options.rel) { + element.rel = options.rel; + } + return element; + } + + function appendInternalLinkMessage(container, issueUrl) { + var heading = createElement('h3', { text: '情况分析' }); + var paragraph = createElement('p'); + paragraph.append('我们发现您可能是通过我们网站内部的一个链接到达这里的。'); + paragraph.append(document.createElement('br')); + paragraph.append('这很可能是我们的一个疏忽，非常抱歉！'); + + var helpText = createElement('p', { text: '如果您愿意花些时间帮助我们改进，我们将不胜感激：' }); + var reportLink = createElement('a', { + href: issueUrl, + target: '_blank', + rel: 'noopener' + }); + var strong = createElement('strong', { text: '点击此处提交错误报告' }); + reportLink.appendChild(strong); + + var note = createElement('p'); + var small = createElement('small', { text: '提示：点击后，请在新打开的页面中填写来源和目标链接，感谢！' }); + note.appendChild(small); + + container.replaceChildren(heading, paragraph, helpText, reportLink, note); + } + + function appendGenericMessage(container, currentPath) { + var heading = createElement('h3', { text: '情况分析' }); + var paragraph = createElement('p'); + paragraph.append('您尝试访问的地址 '); + var code = createElement('code', { text: currentPath }); + paragraph.appendChild(code); + paragraph.append(' 无法找到。'); + + var intro = createElement('p', { text: '您可以：' }); + var list = createElement('ul'); + var item1 = createElement('li', { text: '检查地址栏中的拼写是否正确。' }); + var item2 = createElement('li', { text: '使用页面顶部的搜索功能查找相关内容。' }); + list.append(item1, item2); + + container.replaceChildren(heading, paragraph, intro, list); + } + + function renderActions(container, homepageUrl, repoUrl, onRandomClick) { + var heading = createElement('h3', { text: '接下来您想？' }); + var links = createElement('div', { id: 'action-links-container' }); + var homeLink = createElement('a', { href: homepageUrl, text: '返回首页' }); + var repoLink = createElement('a', { + href: repoUrl, + text: '查看项目源码', + target: '_blank', + rel: 'noopener' + }); + var randomLink = createElement('a', { + href: '#', + text: '随便逛逛 (Feeling Lucky?)', + id: 'random-page-link' + }); + + randomLink.addEventListener('click', onRandomClick); + + links.append(homeLink, ' | ', repoLink, ' | ', randomLink); + container.replaceChildren(heading, links); + } + + function init404Page() { + var page = document.querySelector('[data-404-page]'); + if (!page) { + return; + } + + var reasonContainer = document.getElementById('reason-container'); + var countdownContainer = document.getElementById('countdown-container'); + var countdownTimer = document.getElementById('countdown-timer'); + var actionContainer = document.getElementById('action-container'); + var cancelLink = document.getElementById('cancel-redirect-link'); + + if (!reasonContainer || !countdownContainer || !countdownTimer || !actionContainer || !cancelLink) { + return; + } + + var currentPath = window.location.pathname; + var referrer = document.referrer; + var homepageUrl = page.dataset.homeUrl; + var repoUrl = page.dataset.repoUrl; + var searchIndexUrl = page.dataset.searchIndexUrl; + var issueUrl = repoUrl + '/issues/new?template=bug_report.md'; + + if (referrer && referrer.startsWith(window.location.origin)) { + appendInternalLinkMessage(reasonContainer, issueUrl); + } else { + appendGenericMessage(reasonContainer, currentPath); + } + + var countdown = 10; + var timer = setInterval(function () { + countdown -= 1; + countdownTimer.textContent = countdown; + if (countdown <= 0) { + clearInterval(timer); + window.location.href = homepageUrl; + } + }, 1000); + + cancelLink.addEventListener('click', function (event) { + event.preventDefault(); + clearInterval(timer); + + countdownContainer.style.opacity = '0'; + setTimeout(function () { + countdownContainer.style.display = 'none'; + }, 300); + + renderActions(actionContainer, homepageUrl, repoUrl, function (e) { + e.preventDefault(); + var randomPageLink = e.currentTarget; + randomPageLink.textContent = '正在寻找有趣的页面...'; + + fetch(searchIndexUrl) + .then(function (response) { + return response.json(); + }) + .then(function (data) { + if (data.docs && data.docs.length > 0) { + var randomIndex = Math.floor(Math.random() * data.docs.length); + var randomPage = data.docs[randomIndex]; + window.location.href = joinUrl(homepageUrl, randomPage.location); + return; + } + window.location.href = homepageUrl; + }) + .catch(function () { + window.location.href = homepageUrl; + }); + }); + }); + } + + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', init404Page); + } else { + init404Page(); + } +})(); diff --git a/docs/ncu-exclusive/index.md b/docs/ncu-exclusive/index.md index 24b96f4f..a71d3edb 100644 --- a/docs/ncu-exclusive/index.md +++ b/docs/ncu-exclusive/index.md @@ -1,4 +1,92 @@ -# NCU +--- +tags: + - Level-Beginner + - Type-Guide +--- -这是一个故意设置的坏链接，点它就会触发 404： -[点我测试内部错误链接](/zhe-ge-ye-mian-bu-cun-zai/) \ No newline at end of file +# 昌大专属 + +这一部分是写给南昌大学同学的场景化入口。 + +但它当前的定位需要先说清楚：**这里不是一个已经完整成型的“资源库”，而是一个正在持续补全的校内经验入口。** + +我们更希望它先做到两件事： + +1. 帮你知道哪些问题值得优先关注 +2. 给你一个不容易迷路的起读入口 + +而不是制造“这里已经什么都有了”的假象。 + +--- + +## 这里主要在覆盖什么 + +目前这部分主要围绕 3 类校园议题展开： + +### 1. 学业发展 + +包括： + +- [培养方案全解](./academic-development/program-guide.md) +- [学分绩点体系](./academic-development/credits-and-gpa.md) +- [特色实验班](./academic-development/experimental-classes.md) +- 转专业、保研、考研等专题入口 + +**适合谁：** 想先搞清楚学校制度、培养路径和一些关键节点的人。 + +### 2. 资源与机会 + +包括： + +- [社团与组织：计算机相关](./clubs-and-organizations/cs.md) + +**适合谁：** 想了解校内有哪些组织、社群和尝试空间的人。 + +### 3. 校园生活 + +包括： + +- [通识课程体系](./campus-life/general-education-courses.md) +- [体育与体测](./campus-life/pe-and-fitness-tests.md) +- [新生军训](./campus-life/military-training.md) + +**适合谁：** 刚入学或还不熟悉校园运行方式的人。 + +--- + +## 建议你怎么使用这一部分 + +### 如果你是新生 + +建议先看： + +1. [培养方案全解](./academic-development/program-guide.md) +2. [学分绩点体系](./academic-development/credits-and-gpa.md) +3. [通识课程体系](./campus-life/general-education-courses.md) + +### 如果你在思考学业路径 + +建议优先关注： + +- [特色实验班](./academic-development/experimental-classes.md) +- 转专业相关入口 +- 保研 / 考研相关入口 + +### 如果你还不知道要不要深入这一区 + +先记住一个原则：**只有当问题明确是“南昌大学场景特有”时，再优先来这里找答案。** + +如果你现在卡住的是更普适的成长、决策、学习问题，建议先回到： + +- [首页](../index.md) +- [全站导览与官方推荐路径](../growth-general-course/00-before-we-start/overview.md) +- [核心原则：构建你的个人决策系统](../growth-general-course/01-the-zero-course/the-core.md) + +--- + +## 当前边界说明 + +!!! note "当前版本说明" + 这一部分仍在逐步建设中。现阶段它更适合作为“校内议题入口”，而不是一个已经穷尽所有资源的完整资料库。 + +如果你发现某个专题还不够完整，这并不代表它不重要，而只是说明这部分还在补充中。欢迎后续通过社区共建一起完善。 diff --git a/docs/skills/communication/index.md b/docs/skills/communication/index.md index 149868c0..59b18143 100644 --- a/docs/skills/communication/index.md +++ b/docs/skills/communication/index.md @@ -1 +1,84 @@ -# 沟通与协作 导览 +--- +tags: + - Level-Beginner + - Type-Guide + - Action-Building +--- + +# 沟通与协作导览 + +这个模块关注的不是“会说话”这么简单，而是**你如何与他人建立有效连接、推进合作，并在关系中减少无效内耗**。 + +很多大学里的关键机会，最后都不只取决于你会不会做事，也取决于你能不能： + +- 把自己的想法说清楚 +- 和别人顺畅协作 +- 处理误解、冲突与边界问题 +- 在关系里建立长期可信度 + +--- + +## 这个模块在解决什么问题 + +当我们说“沟通能力”时，真正包含的通常是 3 件事： + +1. **表达**：把意思说明白，而不是让对方猜 +2. **连接**：建立健康、稳定、互相尊重的关系 +3. **协作**：在共同目标下推进事情，而不是各做各的 + +这也是为什么这个模块不只讲技巧，还会涉及关系、团队和冲突。 + +--- + +## 建议先读什么 + +### 1. [沟通技巧](./skills/communication.md) + +**适合谁：** 想把话说清楚、减少误解、提升日常表达效果的人。 + +**你能获得什么：** 对沟通这件事建立一个更基础的认识，避免“明明说了，但没有真的传达”。 + +### 2. [构建人际关系网](./skills/network-of-relationships.md) + +**适合谁：** 不想把关系理解成“混圈子”，但又知道人际支持系统很重要的人。 + +**你能获得什么：** 更现实地理解关系的建立、维护与互相支持，而不是把社交看成表演。 + +### 3. [团队协作](./teamwork/teamwork.md) + +**适合谁：** 参与社团、项目、课程作业或开源协作时，常常感到配合混乱的人。 + +**你能获得什么：** 更清楚地理解团队里角色、配合与推进的基本逻辑。 + +### 4. [人际矛盾处理](./skills/dealing-conflicts.md) + +**适合谁：** 容易在关系冲突里回避、爆炸或长期内耗的人。 + +**你能获得什么：** 学会识别矛盾类型，并尝试用更稳定的方式处理边界和分歧。 + +--- + +## 推荐阅读路线 + +### 如果你想先提升日常表达 + +1. [沟通技巧](./skills/communication.md) +2. [人际矛盾处理](./skills/dealing-conflicts.md) + +### 如果你更关心合作与团队 + +1. [团队协作](./teamwork/teamwork.md) +2. [构建人际关系网](./skills/network-of-relationships.md) + +### 如果你想把它放回成长主线里理解 + +建议先看 [核心原则：构建你的个人决策系统](../../growth-general-course/01-the-zero-course/the-core.md)，再回到这个模块补具体能力。 + +--- + +## 读完这一模块后，你可以去哪里 + +- 想先补“学习系统”：去看 [学会学习](../learning/index.md) +- 想补“认知与判断”：去看 [认知与心智](../mindset/index.md) +- 想补“工具能力”：去看 [工具与系统](../tools/index.md) +- 想补“长期规划”：去看 [成长与规划](../growth/index.md) diff --git a/docs/skills/communication/skills/communication.md b/docs/skills/communication/skills/communication.md index e69de29b..2bff53fc 100644 --- a/docs/skills/communication/skills/communication.md +++ b/docs/skills/communication/skills/communication.md @@ -0,0 +1,119 @@ +--- +tags: + - Topic-Communication + - Topic-InterpersonalSkills + - Type-Guide + - Level-Beginner + - Action-Practical +--- + +# 沟通技巧 + +沟通不是“多说一点”或者“嘴甜一点”，而是**让对方真正理解你的意思，并让事情因此更顺利地往前推进**。 + +这页适合这样的人： + +- 经常觉得“我明明说了”，但对方还是没接收到重点 +- 一到表达需求、提出不同意见、和人协作时就容易慌 +- 想减少误解、内耗和无效解释 + +如果你更关心关系边界，可以继续看 [构建人际关系网](./network-of-relationships.md)；如果你现在正在处理矛盾与摩擦，也建议配合阅读 [理性应对人际矛盾](./dealing-conflicts.md)。 + +--- + +## 这页主要解决什么问题 + +很多人把沟通理解成“表达自己”，但在真实场景里，沟通至少同时在做三件事： + +- 把信息说明白 +- 让对方理解你在意什么 +- 让双方更容易形成下一步动作 + +所以，沟通的好坏，不只看你说得多不多、自然不自然，而要看结果：对方是否理解了重点、预期是否一致、事情是否更容易推进。 + +这也是为什么很多沟通失败，不是因为人不真诚，而是因为内容太散、情绪太重、或者默认了对方会自动懂你。 + +--- + +## 1. 先说清目的，再展开细节 + +最常见的低效沟通，是一上来就铺很多背景，却迟迟不说重点。对方听了半天，仍然不知道你到底是想求助、同步信息、表达不同意，还是只是想倾诉。 + +更稳的做法是：先把这次沟通的目的说出来，再补充必要细节。 + +比如你要找同学协作，不如先说“我想和你确认一下分工和时间”，再解释背景；你要向老师请教，不如先说“我卡在这个问题上，想请您帮我判断思路是不是偏了”；你要和舍友沟通边界，也可以先说“我想聊一下最近作息对彼此的影响”。 + +这样做有两个好处。第一，对方更容易进入正确接收状态。第二，你自己也更不容易在说的过程中越说越散。很多表达焦虑，其实不是不会说，而是还没想清楚“我这次想得到什么”。 + +如果你总觉得自己一开口就乱，可以先在心里过一遍：**我这次沟通的目标是什么？我希望对方听完之后知道什么、做什么？** 这一步会大大降低无效解释。 + +--- + +## 2. 少一点模糊感受，多一点具体信息 + +沟通里另一个常见问题，是说了很多感受，却没有提供足够具体的信息。比如“你最近总是不配合”“这个安排不太行”“我觉得你这样不太好”，这些话虽然表达了情绪，但对方往往不知道你具体指什么，更不知道该怎么改。 + +你可以尝试把表达拆成四部分： + +- 发生了什么具体事情 +- 这件事对你造成了什么影响 +- 你的真实需求是什么 +- 你希望对方接下来怎么配合 + +例如，不说“你总是拖我后腿”，可以改成：“我们原本约好昨天晚上同步材料，但你那部分今天中午还没发，所以我没法继续整理整份文档。我希望咱们今晚能把新的截止时间重新对齐，后面延迟时提前说一声。” + +这种表达并不会让你显得更强硬，反而更容易减少误解。因为你不是在评价对方这个人，而是在描述一个具体问题和你需要的配合方式。 + +这在学习、宿舍、社团、项目里都很重要。越是长期要打交道的人，越值得用清楚、具体的表达来减少重复摩擦。 + +--- + +## 3. 沟通不是压过对方，而是形成可执行的下一步 + +很多人以为一次成功沟通，等于“我把话讲赢了”。但现实里，更重要的是双方有没有形成下一步动作。 + +尤其在协作场景中，单纯把道理讲明白并不够。如果没有把结论落到行动上，沟通很容易结束在“彼此都懂了”，然后什么也没发生。 + +所以，每次重要沟通的结尾，可以尽量收束到一个明确结果上： + +- 谁来做什么 +- 什么时间前完成 +- 如果遇到问题，怎么再同步 +- 这次先按什么方案试一轮 + +比如讨论小组作业，不要只停在“那我们之后抓紧点”，而是落到“今晚十点前每个人交自己的部分，明早统一合并”；比如表达不同意见，不要只说“我觉得这个方案风险更大”，而是补一句“要不我们先列一下时间成本，再决定选哪个”。 + +这会让沟通从情绪交换，变成真正推动事情的工具。 + +--- + +## 立即可做：用一次更清楚的表达替代含糊沟通 + +你今天就可以挑一个正在发生的小场景，按这个顺序试一次： + +1. 先用一句话说清这次沟通的目的。 +2. 用具体事件替代笼统评价。 +3. 明确说出你的需求，而不是让对方猜。 +4. 在结尾补上一个可执行的下一步。 + +哪怕只是一次消息回复，你都会感受到沟通质量的差别。 + +--- + +## 常见误区、边界与下一步 + +### 常见误区 + +- **误区一：只要真诚就够了。** 真诚很重要，但没有结构和具体信息，真诚也可能传不到位。 +- **误区二：会说就是会沟通。** 真正有效的沟通还包括倾听、确认理解和推进下一步。 +- **误区三：沟通成功等于说服对方。** 很多时候，沟通的目标是对齐信息、明确边界，而不是赢。 + +### 不适用范围 + +这页讲的是日常学习与协作中的基础沟通技巧，不替代高冲突场景、权力不对等场景下的更专业应对。遇到长期霸凌、恶意操控或制度性问题时，需要及时寻求更正式的支持。 + +### 接下来去哪里 + +- 想处理更复杂的摩擦：读 [理性应对人际矛盾](./dealing-conflicts.md) +- 想理解关系边界与人脉建设：读 [构建人际关系网](./network-of-relationships.md) +- 想把沟通放进团队场景：读 [团队协作](../teamwork/teamwork.md) diff --git a/docs/skills/growth/finance/financial-literacy.md b/docs/skills/growth/finance/financial-literacy.md index 45f97c15..f3844ca5 100644 --- a/docs/skills/growth/finance/financial-literacy.md +++ b/docs/skills/growth/finance/financial-literacy.md @@ -1 +1,114 @@ +--- +tags: + - Topic-SelfManagement + - Type-Guide + - Level-Beginner + - Action-Practical +--- + # 财商启蒙 + +财商不是教你一夜之间“赚很多钱”，而是帮你建立一种更基础也更重要的能力：**理解钱是怎么流动的、自己的支出为什么会失控，以及怎样让生活不总被钱推着走。** + +这页适合这样的人： + +- 刚开始自己管理生活费，却总在月底不知道钱花去哪了 +- 容易被消费情绪、同辈比较或平台活动带着走 +- 想先把大学阶段最基本的财务感建立起来 + +如果你更想看具体消费判断，可以接着读 [聪明消费](./smart-spending.md)；如果你正在补整个长期生活底盘，也可以顺路看 [健康管理](../health/healthy-management.md)。 + +--- + +## 这页主要解决什么问题 + +大学里第一次自己管钱，很多人并不是不想克制，而是之前从没真正建立过财务视角。生活费、奖学金、兼职收入、活动支出、临时大件、社交消费全挤在一起，很容易让你每次都只凭当下感觉做决定。 + +财商启蒙想解决的，不是教你复杂投资，而是先建立三个最基础的认知： + +- 钱是有限资源，需要有基本分配意识 +- 每次花钱不只是“买到一个东西”，也是在给自己的优先级投票 +- 稳定的财务感，会直接影响你的情绪、学习状态和选择自由度 + +很多大学阶段的财务问题，看起来只是“花多了”，本质上却常常和冲动消费、面子压力、缺少记录、没有预留缓冲有关。先把这些基础盘稳住，比学很多进阶概念更重要。 + +--- + +## 1. 先知道自己的钱从哪里来、往哪里去 + +很多财务失控，不是因为收入太少，而是因为对资金流向几乎没有感知。钱在一笔笔小额支付里慢慢流掉，最后只剩下一句“我也不知道怎么花没的”。 + +所以财商启蒙的第一步，不是省钱技巧，而是建立最基本的可见性。你至少要知道： + +- 自己每月大致可支配金额是多少 +- 固定支出有哪些 +- 哪些钱常常花在临时情绪、社交顺手单或碎片小额里 + +你不一定要做得很精细，但至少要有一个最基础的记录习惯。因为只有当流向被看见，你才能判断问题到底出在哪：是日常开销偏高，还是偶发消费太多；是必要支出本来就重，还是自己在无意识地反复泄漏。 + +财务感的建立，本质上和学习里的信息输入很像：先看清，再决策。看不清的时候，人会本能地用感觉补位，而感觉在消费场景里往往不太可靠。 + +--- + +## 2. 区分“需要、想要、跟风想要” + +很多大学消费不是简单的“想买就买”，而是夹杂着情绪、身份和比较。你可能不是因为真正需要，而是因为： + +- 最近很累，想靠买点东西补偿自己 +- 看到别人都在用，担心自己显得落后 +- 平台促销制造了“不买就亏”的错觉 + +所以，比起一味压抑消费，更重要的是学会区分不同类型的购买动机。 + +一个很实用的判断方式是问自己三句： + +- 这个东西是在解决真实问题，还是只是在缓解短期情绪？ +- 如果一周后再买，我还会觉得有必要吗？ +- 它会给我带来长期使用价值，还是只是一阵新鲜感？ + +这并不是要求你把所有非必要消费都砍掉，而是让你逐渐从“被刺激牵着买”转向“我知道自己为什么买”。只要这个意识建立起来，你的很多消费决策就会开始变得更稳。 + +--- + +## 3. 给自己留缓冲，而不是把生活过成走钢丝 + +财务上很容易被忽视的一点，是缓冲区。 + +很多人平时看起来没什么问题，真正难受的是一旦遇到突发情况——临时买教材、设备出问题、往返出行、身体不适、社交支出集中出现——整个生活节奏立刻被打乱。问题不一定是你平时花得特别夸张，而是你没有给自己留任何回旋空间。 + +所以，哪怕每个月金额不大，也尽量给自己留出一点“不可预期支出”的缓冲。这不是为了制造焦虑，而是为了让你在面对现实波动时更有稳定感。 + +财商启蒙最核心的一层，其实就是：不要把自己推到每个月都必须靠运气不出意外才能过下去。哪怕只是很小的缓冲，也会显著降低那种被生活追着跑的感觉。 + +--- + +## 立即可做：先建立你的基础财务感 + +你现在就可以做这 4 步： + +1. 估一下自己本月大致可支配金额。 +2. 回看最近一周支出，标出固定支出和冲动支出。 +3. 选一个最容易漏钱的场景，给自己加一条提醒规则。 +4. 从这个月开始，先留出一小笔缓冲，不把钱算到刚刚好。 + +不需要一步到位。只要你开始看清流向，财务感就已经在建立。 + +--- + +## 常见误区、边界与下一步 + +### 常见误区 + +- **误区一：财商等于投资理财。** 对大学阶段来说，先学会管理自己的现金流更重要。 +- **误区二：会记账就够了。** 记录只是起点，关键是看见模式并调整行为。 +- **误区三：控制消费只能靠忍。** 真正有效的是理解自己的消费触发点，而不是单纯硬扛。 + +### 不适用范围 + +这页是大学阶段的财商启蒙，不提供投资、借贷、金融产品选择建议。涉及高风险理财、分期、借款等问题时，务必单独谨慎判断，不要把基础财商页当作操作指导。 + +### 接下来去哪里 + +- 想看更贴近日常的消费判断：读 [聪明消费](./smart-spending.md) +- 想补长期生活稳定性：读 [健康管理](../health/healthy-management.md) +- 想把长期选择放回成长路径：读 [职业规划](../opportunity/career-planning.md) diff --git a/docs/skills/growth/index.md b/docs/skills/growth/index.md index 585386d8..426bd0da 100644 --- a/docs/skills/growth/index.md +++ b/docs/skills/growth/index.md @@ -1 +1,94 @@ -# 成长与规划 导览 +--- +tags: + - Level-Beginner + - Type-Guide + - Action-Building +--- + +# 成长与规划导览 + +这个模块讨论的是那些**不会立刻出现在考试里，却会持续影响你大学四年乃至更久的长期议题**。 + +它适合这样的人： + +- 不想只把大学理解成“上课 + 考试” +- 开始意识到财务、健康、机会选择这些问题迟早要自己面对 +- 想让自己的成长更可持续，而不是一阵热血、一阵崩盘 + +--- + +## 这个模块在解决什么问题 + +很多大学生的问题，不是不会努力，而是没有把“长期运行”当作一个系统来对待。 + +比如： + +- 你会不会管理自己的钱 +- 你有没有基本的身体维护意识 +- 你如何识别值得抓住的机会 +- 你如何把短期选择放回更长的路径里看 + +这个模块要补的，就是这些容易被忽视、却迟早会追上你的现实问题。 + +--- + +## 建议先读什么 + +### 1. 财务管理 + +适合想先建立基础生活掌控感的人。建议优先看： + +- [财商启蒙](./finance/financial-literacy.md) +- [聪明消费](./finance/smart-spending.md) + +**你能获得什么：** 对花钱、储蓄、消费判断更有意识，避免长期被无计划支出拖着走。 + +### 2. 身体健康 + +入口： + +- [健康管理](./health/healthy-management.md) + +**适合谁：** 常常熬夜、透支、忽视身体信号，直到状态明显下滑的人。 + +**你能获得什么：** 开始把健康当作成长能力的一部分，而不是“有空再说”。 + +### 3. 机遇探索 + +适合想理解“我还可以尝试什么”的人。建议按需阅读： + +- [信息差](./opportunity/information-gap.md) +- [开源之旅](./opportunity/open-source-journey.md) +- [实验班解读](./opportunity/innovation-classes.md) +- [职业规划](./opportunity/career-planning.md) + +**你能获得什么：** 更现实地看待机会，不盲目追风口，也不在信息差里长期被动。 + +--- + +## 推荐阅读路线 + +### 如果你想先把生活底盘稳住 + +1. [财商启蒙](./finance/financial-literacy.md) +2. [聪明消费](./finance/smart-spending.md) +3. [健康管理](./health/healthy-management.md) + +### 如果你想扩大视野，看看可能的路径 + +1. [信息差](./opportunity/information-gap.md) +2. [开源之旅](./opportunity/open-source-journey.md) +3. [职业规划](./opportunity/career-planning.md) + +### 如果你已经在思考长期方向 + +建议先回看 [核心原则：构建你的个人决策系统](../../growth-general-course/01-the-zero-course/the-core.md)，再来读这个模块，会更容易把这些议题放回自己的主线里。 + +--- + +## 读完这一模块后，你可以去哪里 + +- 想先补“学习能力”：去看 [学会学习](../learning/index.md) +- 想补“关系与协作”：去看 [沟通与协作](../communication/index.md) +- 想补“数字与工具”：去看 [工具与系统](../tools/index.md) +- 想回到核心主线：去看 [完整课程导览](../../growth-general-course/01-the-zero-course/index.md) diff --git a/docs/skills/growth/opportunity/career-planning.md b/docs/skills/growth/opportunity/career-planning.md index d43a15bb..32ad3c46 100644 --- a/docs/skills/growth/opportunity/career-planning.md +++ b/docs/skills/growth/opportunity/career-planning.md @@ -1 +1,122 @@ +--- +tags: + - Topic-CareerPlanning + - Topic-SelfManagement + - Type-Guide + - Level-Beginner + - Action-Building +--- + # 职业规划 + +职业规划不是让你大一就决定一辈子做什么，而是帮助你在不确定里建立一种能力：**知道自己正在往哪个方向试、为什么试，以及下一步该怎么验证。** + +这页适合这样的人： + +- 一想到未来方向就容易焦虑，要么空想很多，要么干脆不想 +- 看别人实习、考研、竞赛、转方向时，常常跟着摇摆 +- 想先建立一个更现实的职业思考框架，而不是立刻选终局 + +如果你现在更需要理解学校里的“特殊路径”，可以补看 [实验班解读](./innovation-classes.md)；如果你还在打基础，也建议先回到 [核心原则：构建你的个人决策系统](../../../growth-general-course/01-the-zero-course/the-core.md)。 + +--- + +## 这页主要解决什么问题 + +很多人一听到“职业规划”，脑子里就只剩两个极端： + +- 要么觉得必须尽快确定终局，不然就是落后 +- 要么觉得现在想这些太早，干脆完全不想 + +这两个极端都容易把人困住。前者容易让你被焦虑和外界声音推着走，后者则会让你长期停留在被动状态，直到真正要选的时候才发现准备不够。 + +所以职业规划更现实的目标，不是现在就把未来彻底定死，而是逐步建立三件事： + +- 对自己当前状态的基本认识 +- 对外部路径差异的基本理解 +- 一个可以不断试错、不断修正的行动节奏 + +真正有用的规划，往往不是一次想明白出来的，而是在一次次低成本尝试里慢慢长出来的。 + +--- + +## 1. 先别急着选答案，先看清自己现在的位置 + +职业焦虑很大一部分，来自总想直接回答“我以后到底干什么”，却没有先回答更基础的问题：我现在擅长什么、在乎什么、受不了什么、愿意为什么长期投入。 + +这并不是让你做一份完美的人生剖析，而是至少先有一些现实感。比如： + +- 你更喜欢抽象分析，还是偏向具体执行？ +- 你是在和人协作中更有状态，还是更适合独立推进？ +- 你更看重稳定、收入、成长速度，还是自主空间？ + +这些问题没有标准答案，但它们能帮助你把“别人都在做什么”慢慢转换成“哪些路径更可能适合我”。如果连这一步都没有，职业规划就很容易沦为社会比较：看谁火就想跟，听谁厉害就想试。 + +如果你发现自己对“我是谁、我适合什么”还非常模糊，建议先回到通识主线里读 [第二章：自我认知方法](../../../growth-general-course/01-the-zero-course/part1/ch2-the-self.md)。规划不是跳过自我认知直接开始的。 + +--- + +## 2. 把职业路径看成可比较的选项，而不是唯一正确答案 + +大学里常见的外部路径很多：考研、就业、考公、实习、竞赛、科研、转方向、考证、出国……问题不在于选项太多，而在于很多人用很模糊的方式理解这些词，只看到表面的“听起来不错”，却没看到它们背后的真实要求。 + +更稳的做法，是把每条路径都当成一个待比较的选项，至少问清几件事： + +- 这条路的主要回报是什么？ +- 它对能力、时间、资源的要求是什么？ +- 哪些人会更适合，哪些人可能只是被氛围推着走？ +- 我现在离它有多远，需要先补什么？ + +比如你想考研，就不能只停在“好像很多人都考”；如果你想找实习，也不能只停在“先投了再说”。路径一旦具体化，你就更容易判断自己是在主动选择，还是被模糊想象驱动。 + +职业规划最怕的，不是暂时没答案，而是你以为自己在规划，实际上只是在追逐一个没有拆开看过的标签。 + +--- + +## 3. 用低成本验证代替空想和一次性豪赌 + +很多职业选择真正卡住的地方，不是信息太少，而是迟迟没有验证。你想做产品、想走开发、想试科研、想考研、想进体制，但如果一直停在想象层面，任何路径都会被你脑补得很理想或者很可怕。 + +所以，比起反复空想，更重要的是尽快做一些低成本验证。验证不一定很大，它可以很小： + +- 和已经在路上的学长学姐聊一次真实体验 +- 试做一个相关方向的小项目或作品 +- 去看岗位描述、培养方案、考试要求，而不是只听口号 +- 用一段时间体验这条路对你的节奏、兴趣和承受力是否匹配 + +只要你开始验证，很多模糊焦虑会迅速转化成更具体的问题。具体问题才有办法继续解决。职业规划真正有效的部分，不是想象得多完整，而是你有没有通过现实反馈不断修正。 + +这也和通识主线里强调的“低成本实践与验证”是一致的。你不需要先拥有完美判断才行动，很多判断就是在行动后才逐步长出来的。 + +--- + +## 立即可做：把职业规划从空想拉回现实 + +你现在就可以从这 4 步开始： + +1. 写下你当前最在意的 2-3 个职业相关因素，比如稳定、收入、兴趣、成长空间。 +2. 选一条你最近最常想到的路径，拆出它的真实要求。 +3. 找一个低成本验证动作，本周内完成一次。 +4. 记录结果：这条路让你更笃定了，还是暴露了新的疑问？ + +这样，你的职业规划就不再只是焦虑，而开始变成有反馈的过程。 + +--- + +## 常见误区、边界与下一步 + +### 常见误区 + +- **误区一：越早定终局越好。** 过早锁死方向，反而可能让你失去必要的探索空间。 +- **误区二：规划等于搜集很多信息。** 没有比较和验证，信息再多也不等于规划。 +- **误区三：别人走得快，说明自己落后。** 职业选择本来就高度个体化，关键是你是否在真实推进。 + +### 不适用范围 + +这页是职业规划的入门框架，不替代具体行业分析、研究生报考建议、求职辅导或公务员备考方案。进入具体路径后，仍然需要进一步做针对性研究。 + +### 接下来去哪里 + +- 想把选择放回更完整的判断框架：读 [核心原则：构建你的个人决策系统](../../../growth-general-course/01-the-zero-course/the-core.md) +- 想理解学校里常见的特殊机会叙事：读 [实验班解读](./innovation-classes.md) +- 想先补稳定生活底盘：读 [财商启蒙](../finance/financial-literacy.md) diff --git a/docs/skills/index.md b/docs/skills/index.md index 67318222..30a53bc5 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -8,23 +8,115 @@ tags: # 本部分导览 +《第零点五课堂》是本站的“能力模块区”。 + +如果说 [本科生通识第零课](../growth-general-course/01-the-zero-course/index.md) 更像一条核心主线，帮助你建立“向内看 → 向外看 → 去行动”的决策框架，那么《第零点五课堂》更像一个按主题展开的工具箱：你可以在这里补齐那些**本应更早学会、却常常没人系统讲清楚的底层能力**。 + +--- + ## 为什么叫《第零点五课堂》？ -在大学里，我们习惯于划分“第一课堂”（传统课程）和“第二课堂”（社会实践）。但我们发现，存在着一类至关重要的知识，它们既不完全属于前者，也远比后者更基础。 +在大学里，我们习惯于把内容分成“第一课堂”和“第二课堂”。但我们发现，还有一类知识卡在两者之间： + +- 它不属于标准专业课 +- 它也不只是课外活动经验 +- 它往往比具体专业技能更基础 +- 它会直接决定你能不能更稳地学习、合作、行动和成长 + +我们把这部分内容称为**《第零点五课堂》**。 + +“零点五”的意思，不是它不重要，恰恰相反：**它是很多事情正式展开之前，就应该先拥有的一批前置能力。** + +--- + +## 这一部分适合谁 + +如果你现在的状态更像下面这些描述，这一部分会比“继续盲目刷经验贴”更适合你： + +- 你已经知道自己要努力，但不知道先补哪种底层能力 +- 你不是完全没有方向，而是卡在“学不动、做不稳、配合不好、工具太乱”这些具体问题上 +- 你不想只看宏大叙事，而是想按主题补齐一部分实际可用的能力 + +--- + +## 这部分现在有哪些模块 + +### 1. [认知与心智](./mindset/index.md) + +**适合谁：** 想减少内耗、看清思维陷阱、建立更稳判断底盘的人。 + +**你能获得什么：** 对偏差、定式、心理状态与基本心智模型更清楚的理解。 + +### 2. [学会学习](./learning/index.md) + +**适合谁：** 明明花了很多时间学习，但总觉得乱、散、累的人。 + +**你能获得什么：** 重建自己的学习系统，包括输入、方法、复盘与精力节奏。 + +### 3. [沟通与协作](./communication/index.md) + +**适合谁：** 想把表达、关系与团队合作做得更顺的人。 + +**你能获得什么：** 更清晰地理解如何沟通、协作、处理关系和冲突。 -我们称之为**《第零点五课堂》**。 +### 4. [工具与系统](./tools/index.md) -**“零点五”** 的含义在于它的特殊位置： +**适合谁：** 经常被数字环境、资料管理、工具折腾拖慢节奏的人。 -它包含了那些**本应在一切开始之前就教会你，但学校却教得太晚、甚至从不教的东西**。这些东西，小到如何高效打字，大到如何摆脱思维陷阱，其重要性远远超乎你的想象。 +**你能获得什么：** 建立更稳定的数字基础与个人工作流。 + +### 5. [成长与规划](./growth/index.md) + +**适合谁：** 开始意识到财务、健康、机会选择这些长期议题同样重要的人。 + +**你能获得什么：** 更长期地理解大学生活该如何持续运行，而不是只靠短期爆发。 + +--- + +## 推荐你怎么进入这一部分 + +### 如果你完全不知道从哪块开始 + +优先顺序建议是： + +1. [认知与心智](./mindset/index.md) +2. [学会学习](./learning/index.md) +3. [工具与系统](./tools/index.md) + +这是当前最稳的一条“先修底盘”路线。 + +### 如果你最想解决“效率和状态”问题 + +建议先看： + +1. [学会学习](./learning/index.md) +2. [成长与规划](./growth/index.md) + +### 如果你最想解决“做事和协作”问题 + +建议先看： + +1. [沟通与协作](./communication/index.md) +2. [工具与系统](./tools/index.md) + +--- + +## 和主线的关系是什么 + +《第零点五课堂》不是为了替代主线，而是为了给主线提供补给。 + +如果你还没读过 [核心原则：构建你的个人决策系统](../growth-general-course/01-the-zero-course/the-core.md)，建议先去看那一页。它会帮助你理解：为什么这些能力模块最终都服务于“更好地做判断，并把判断变成行动”。 + +如果你已经有了基本框架，再回到这里按主题补能力，体验会更好。 + +--- -从根本上说，它们是你在大学这场旅途中，**进行高效学习、做出明智决策、保持身心健康所依赖的底层能力**。 +## 当前阅读建议 -!!! declaration "本课堂的核心原则" - 这里的内容包罗万象，但都遵循一个原则：**它们比专业知识更基础** +如果你不想在很多页面之间自己判断，可以直接从这里开始： -- 我们探讨**思维认知**，帮你避开那些看不见的陷阱。 -- 我们分享**工具技能**，让你在这个时代如虎添翼。 -- 我们提供**成长指南**，伴你走过大学四年的迷茫与挑战。 +1. [学会学习](./learning/index.md) +2. [工具与系统](./tools/index.md) +3. [沟通与协作](./communication/index.md) -《第零点五课堂》是你**正式开启大学生活前，最值阅览的一堂“前置课”**。它关乎基础，更关乎未来。 +这会是当前版本里最实用、也最不容易迷路的一种进入方式。 diff --git a/docs/skills/learning/consolidation/knowledge-consolidation.md b/docs/skills/learning/consolidation/knowledge-consolidation.md index f189ac38..07f147d5 100644 --- a/docs/skills/learning/consolidation/knowledge-consolidation.md +++ b/docs/skills/learning/consolidation/knowledge-consolidation.md @@ -1 +1,114 @@ +--- +tags: + - Topic-InformationLiteracy + - Topic-Productivity + - Type-Guide + - Level-Beginner + - Action-Building +--- + # 知识内化 + +信息进脑子不等于知识真正变成了你的。所谓知识内化，指的是：**你能把看过的内容重新组织、讲出来、用起来，并在需要时调得出来。** + +这页适合这样的人： + +- 上课听懂了、文章也看完了，但过几天就只剩模糊印象 +- 做了很多笔记，却很少再回看，更谈不上真正使用 +- 常常感觉自己“接触过很多”，但输出时说不清楚 + +如果你现在的问题更偏前端，建议先看 [信息输入](../intake/information-intake.md)；如果你发现自己总是没精力做整理和复盘，也可以顺路读 [精力管理](../energy/energy-management.md)。 + +--- + +## 这页主要解决什么问题 + +很多学习挫败感，来自一种很常见的错觉：以为“我当时看懂了”，就等于“我以后还能调用”。 + +但真正的内化，需要至少经过三个过程： + +- 从接收信息，变成自己能复述的理解 +- 从零散片段，变成有结构的组织 +- 从纸面认知，变成可以在题目、项目、表达里用出来的能力 + +所以知识内化不是再看一遍资料，也不是把所有内容抄进笔记软件，而是主动做一点加工。你不用把每份材料都处理得很复杂，但要让重要内容经过你的脑子，而不是只经过你的眼睛。 + +--- + +## 1. 不要追求“抄完整”，先追求“讲明白” + +很多人做笔记时最容易掉进的坑，就是想把原文尽量记录得完整。看起来很认真，实际上却可能只是把资料换了个地方存了一遍。 + +如果一段内容你只能照着原话重复，说明它大概率还没有真正变成你的理解。更有效的做法是：看完之后，先合上资料，尝试用自己的话回答两个问题： + +- 这段内容在说什么？ +- 它为什么重要，或者它能解决什么问题？ + +只要你能用更简单的话把概念讲给“昨天的自己”，内化就已经开始发生了。这个过程不要求表达很漂亮，但要求你真的做了一次重新组织。 + +特别是面对课程概念、学习方法、软件操作逻辑时，费曼式复述很有用。你会很快发现哪些地方只是“看着懂”，哪些地方其实还卡着。一旦卡住，就回去补最关键的缺口，而不是继续机械往下看。 + +--- + +## 2. 把零散内容连成结构，别让笔记只堆不连 + +内化失败的另一个原因，是信息彼此孤立。今天记了一页课堂笔记，明天收藏了一篇教程，后天又在群里保存了一个经验贴，但它们之间没有关系。久而久之，你手里有很多材料，却没有形成可调用的知识地图。 + +更稳的方式，是每学一块内容就尝试回答： + +- 它属于哪个主题？ +- 它和我已经知道的哪件事有关？ +- 它是原则、方法，还是具体案例？ + +你不一定要画很复杂的脑图，但最好能让内容有归属、有连接。比如同样是“写作业效率低”，你可以把它拆开看：信息输入是否混乱、知识是否没内化、任务是否没拆分、精力是否已经透支。这样你就不会把所有问题都模糊地归因于“我不够自律”。 + +如果你在用笔记工具，建议少建一堆看似高级却长期不用的层级，多保留“主题页 + 关键结论 + 关联链接”这种简单结构。内化的重点不是系统多漂亮，而是你之后能找回、能继续接着用。 + +--- + +## 3. 给知识一个使用场景，才更容易留下来 + +真正留得住的知识，往往不是“看过很多次”的知识，而是“被你用过几次”的知识。 + +所以，当你学完一个概念、一套方法或一条经验，最好立刻问自己：它接下来要在哪儿用？ + +- 是拿去解释给同学听？ +- 是用在下一次作业、项目或考试里？ +- 是变成一条操作规则，帮你减少以后重复犯错？ + +只要知识进入过真实场景，它的留存率通常就会高很多。比如看完一篇关于信息筛选的内容后，你马上去清理自己的收藏夹；学完一个写作结构后，你下一次发言或写总结时就刻意试用。这样的“轻量使用”，比单纯重复阅读更容易形成长期记忆。 + +如果你暂时没有真实应用场景，也可以自己制造一个最小输出：写一段总结、做三张抽认卡、讲给朋友听，或者把核心步骤整理成清单。重点不是形式，而是让知识从输入流出一次。 + +--- + +## 立即可做：把今天学到的一件事真正留下来 + +你现在就可以拿今天学过的任意一件内容，做这 4 步： + +1. 合上原文，用自己的话写下 3-5 句总结。 +2. 补一句“它能解决什么问题”。 +3. 关联到你已有的一条笔记、课程主题或真实任务。 +4. 在 24 小时内安排一次最小使用：讲、写、做题、套用其一即可。 + +哪怕只完成一轮，你也会明显感觉到“看过”和“留下来”之间的差别。 + +--- + +## 常见误区、边界与下一步 + +### 常见误区 + +- **误区一：笔记越多越说明学得好。** 如果不能复述和调用，笔记再多也只是资料仓库。 +- **误区二：内化必须很重。** 实际上，很多时候一句复述、一次应用就足够启动内化。 +- **误区三：等学完再整理。** 很多内容一旦拖久了，就只剩下再次返工。 + +### 不适用范围 + +这页讲的是通用学习中的知识内化框架，不会替代具体学科里的记忆训练、题型训练或科研方法。面对需要大量刷题、实验、长期积累的领域，内化仍然要结合对应训练方式。 + +### 接下来去哪里 + +- 想先把前端输入整理好：读 [信息输入](../intake/information-intake.md) +- 想补整个学习循环：读 [元学习](../meta/meta-learning.md) +- 想减少因为疲惫导致的“学了也留不住”：读 [精力管理](../energy/energy-management.md) diff --git a/docs/skills/learning/index.md b/docs/skills/learning/index.md index 54ff8c39..05df50e9 100644 --- a/docs/skills/learning/index.md +++ b/docs/skills/learning/index.md @@ -1 +1,97 @@ -# 学会学习 导览 +--- +tags: + - Level-Beginner + - Type-Guide + - Action-Learning +--- + +# 学会学习导览 + +这个模块关注的不是“多学一点”，而是**把学习这件事本身重新搭起来**。 + +如果你经常遇到这些情况，这一部分大概率适合你： + +- 明明花了很多时间，却总觉得没学进去 +- 资料越看越多，反而越来越乱 +- 学一阵就很疲惫，难以稳定持续 +- 知道努力重要，但不知道怎样建立自己的学习系统 + +--- + +## 这个模块在解决什么问题 + +大学里的一个常见误区是：以为只要更努力，学习问题就会自然消失。 + +但很多时候，真正卡住你的不是意志力，而是学习系统本身： + +- 你如何获取信息 +- 你如何组织理解 +- 你如何管理注意力与精力 +- 你如何复盘并调整自己的方法 + +所以这个模块更像一个“学习操作系统”区，帮助你把学习从临时冲刺，变成可以长期运行的能力。 + +--- + +## 建议先读什么 + +### 1. [元学习](./meta/meta-learning.md) + +**适合谁：** 觉得自己一直在学，但不确定有没有学对的人。 + +**你能获得什么：** 建立“规划 → 学习 → 反思 → 调整”的学习循环，开始把自己当作学习系统的设计者，而不只是执行者。 + +### 2. [信息输入](./intake/information-intake.md) + +**适合谁：** 经常被信息洪流淹没，不知道什么该看、什么不该看的人。 + +**你能获得什么：** 更清楚地理解自己应该如何筛选资料、控制输入噪音、避免被低质量信息牵着走。 + +### 3. [知识内化](./consolidation/knowledge-consolidation.md) + +**适合谁：** 看了很多内容，却总觉得记不住、讲不出、用不上的人。 + +**你能获得什么：** 把“看过”逐步变成“理解过、整理过、能复述、能调用”。 + +### 4. [精力管理](./energy/energy-management.md) + +**适合谁：** 想学很多，但常常在分心、疲惫、任务堆积中失速的人。 + +**你能获得什么：** 识别精力被什么消耗，并逐步建立更稳的任务安排和节奏感。 + +--- + +## 推荐阅读路线 + +### 如果你想重建整个学习系统 + +按这个顺序读： + +1. [元学习](./meta/meta-learning.md) +2. [信息输入](./intake/information-intake.md) +3. [知识内化](./consolidation/knowledge-consolidation.md) +4. [精力管理](./energy/energy-management.md) + +### 如果你现在最困扰的是“学不进去” + +建议先读： + +1. [精力管理](./energy/energy-management.md) +2. [元学习](./meta/meta-learning.md) + +### 如果你想把它放回本站主线里理解 + +可以和这些内容连起来读： + +1. [第四章：信息获取入门](../../growth-general-course/01-the-zero-course/part2/ch4-info-gathering.md) +2. [元学习](./meta/meta-learning.md) +3. [精力管理](./energy/energy-management.md) + +--- + +## 读完这一模块后，你可以去哪里 + +- 想补“判断与心智”底层：去看 [认知与心智](../mindset/index.md) +- 想补“表达与协作”：去看 [沟通与协作](../communication/index.md) +- 想补“工具能力”：去看 [工具与系统](../tools/index.md) +- 想补“长期成长规划”：去看 [成长与规划](../growth/index.md) diff --git a/docs/skills/learning/intake/information-intake.md b/docs/skills/learning/intake/information-intake.md index 389059f6..f93918eb 100644 --- a/docs/skills/learning/intake/information-intake.md +++ b/docs/skills/learning/intake/information-intake.md @@ -1 +1,118 @@ +--- +tags: + - Topic-InformationLiteracy + - Topic-Productivity + - Type-Guide + - Level-Beginner + - Action-Practical +--- + # 信息输入 + +信息输入不是“看得越多越好”，而是**建立一套能长期帮你筛选、理解、保留重点的输入机制**。 + +这页适合这样的人： + +- 收藏了很多文章和视频，却很少真正看完 +- 每天被公众号、短视频、群消息和 AI 回答拉着走 +- 明明花了很多时间找资料，却总觉得没有形成稳定判断 + +如果你还没建立学习系统，建议先读 [元学习](../meta/meta-learning.md)；如果你想先练习搜索与 AI 的使用方式，也可以配合阅读 [第四章：信息获取入门](../../../growth-general-course/01-the-zero-course/part2/ch4-info-gathering.md)。 + +--- + +## 这页主要解决什么问题 + +很多人的学习卡住，不是因为不努力，而是因为输入链路已经失控了： + +- 看到什么都想保存，结果笔记库越来越乱 +- 资料来源很多，但没有判断标准 +- 读完之后没有留下任何可调用的结论 + +所以，信息输入的重点不是“接触更多”，而是把输入变成一个有门槛、有节奏、有出口的过程。你需要的不是更大的信息量，而是更清楚地回答三个问题：**我为什么看、我该看什么、我看完后要留下什么。** + +--- + +## 1. 先定义“我要解决什么问题”，再决定看什么 + +最容易让人失控的输入方式，就是漫无目的地刷。 + +比如你本来只是想弄懂一个概念，结果顺着推荐流看了三个视频、五篇帖子、两段评论区争论，最后不仅没更清楚，反而更混乱。问题不在于你不够认真，而在于你从一开始就没有定义输入目标。 + +更稳的做法是：每次开始搜资料前，先把问题写成一句话。 + +- 我是想了解全貌，还是只想解决一个具体卡点？ +- 我需要的是入门解释，还是可直接操作的步骤？ +- 我今天读完之后，希望自己能做到什么？ + +目标越具体，输入越容易收敛。比如“我要学会数据库”太大，但“我要弄明白 SQL 里的 `JOIN` 是做什么的，并能看懂一段基础查询”就足够具体。这样你就更容易判断哪些资料值得看，哪些只是把你继续带偏。 + +如果你发现自己总是在不同材料之间来回跳，可以先回到 [元学习](../meta/meta-learning.md) 里的“规划 → 学习 → 反思 → 调整”循环。输入不是单独存在的一段时间，它应该服务于你当前的学习任务。 + +--- + +## 2. 给信息源分级，而不是一视同仁地相信 + +信息输入的第二个关键，是建立信息源优先级。 + +不是所有内容都要被同等对待。对于同一个问题，课程讲义、官方文档、一本系统写成的文章、路人短帖、AI 即时回答，它们的可靠性、适用性、表达深度都不同。如果你没有分级意识，就很容易把“最容易看到的内容”误当成“最值得信任的内容”。 + +你可以用一个很简单的顺序来判断： + +1. **优先看第一手或结构化来源**：课程材料、官方文档、成熟教程、系统文章。 +2. **再看经验型补充**：论坛讨论、学长经验、案例分享。 +3. **最后把 AI 当作助手，不当作事实终点**：让它帮你解释、总结、列提纲，但要二次核实关键信息。 + +这并不是说短内容都没用，而是它们更适合当提醒或入口，不适合当定论。特别是当你正在做课程任务、写作业、准备面试或搭环境时，错误信息带来的返工成本很高。 + +如果你已经知道自己容易被“讲得很像那么回事”的内容带跑，可以直接给自己加一条规则：**只要是事实性判断、工具操作、制度要求、版本兼容这类内容，都尽量回到原始来源确认。** 这会慢一点，但长期会帮你省下更多时间。 + +--- + +## 3. 输入要有出口：留下可复用的最小记录 + +很多人以为自己输入无效，是因为记性差。其实更常见的原因是：输入结束后，没有留下任何能被后续调用的痕迹。 + +你不一定要写长笔记，但最好给每次重要输入留下一个最小出口。这个出口可以非常简单： + +- 一句话总结这份资料最重要的结论 +- 两三个关键词，方便以后再搜回来 +- 一个“我接下来要做什么”的动作 +- 一个“这份资料适用于什么场景 / 不适用于什么场景”的判断 + +这样的记录方式有两个好处。第一，它逼你确认自己是不是真的看懂了。第二，它能让你未来少掉很多“明明看过但找不回来”的重复劳动。 + +如果你已经在用云笔记或任务工具，可以把这一步和 [云笔记](../../tools/pkm/cloud-notes.md)、[任务管理](../../tools/pkm/task-management.md) 连起来：资料的结论放进笔记，下一步动作进任务系统。这样输入就不再停留在“我好像看过”，而是能真正推进事情。 + +--- + +## 立即可做：把输入从失控拉回可管理 + +如果你想马上开始，不需要重建整套系统，只要先做这 4 步： + +1. 今天挑一个你正在处理的问题，用一句话写清楚本次输入目标。 +2. 只选 1-2 个优先级更高的来源开始看，不要同时开一堆标签页。 +3. 看完后写下“一个结论 + 一个下一步动作”。 +4. 把暂时无关的收藏、稍后再看和推荐流内容先关掉，不在本次处理。 + +做到这一步，你就已经把“被信息推着走”变成“我主动使用信息”。 + +--- + +## 常见误区、边界与下一步 + +### 常见误区 + +- **误区一：收藏等于学习。** 收藏只是延后决策，不代表已经理解。 +- **误区二：看得多就更稳。** 当资料过量时，很多时候你只是更难做判断。 +- **误区三：AI 能代替核实。** AI 很适合辅助理解，但不该直接替你下最终结论。 + +### 不适用范围 + +这页讲的是通用的信息输入框架，不会替代具体学科里的专业资料判断。像科研检索、法律条文、学校政策、软件版本兼容这种场景，仍然要回到更正式的一手来源。 + +### 接下来去哪里 + +- 想继续解决“看过但用不上”：读 [知识内化](../consolidation/knowledge-consolidation.md) +- 想先把学习循环搭起来：读 [元学习](../meta/meta-learning.md) +- 想补搜索与 AI 的基础用法：读 [第四章：信息获取入门](../../../growth-general-course/01-the-zero-course/part2/ch4-info-gathering.md) diff --git a/docs/skills/tools/index.md b/docs/skills/tools/index.md index 7a8d755f..69736239 100644 --- a/docs/skills/tools/index.md +++ b/docs/skills/tools/index.md @@ -1 +1,104 @@ -# 工具与系统 导览 +--- +tags: + - Level-Beginner + - Type-Guide + - Action-Practical +--- + +# 工具与系统导览 + +这个模块不是单纯罗列软件，而是关注：**哪些工具和系统能力，能真实降低你在大学里的摩擦成本。** + +它适合这样的人： + +- 经常被电脑、文件、环境配置、资料整理这些事情卡住 +- 明明花了很多时间在“折腾”，但没有形成稳定工作流 +- 想建立一套更长期可复用的数字能力，而不是只会临时凑合 + +--- + +## 这个模块在解决什么问题 + +很多人会把工具理解成“会不会用某个软件”，但更关键的是： + +- 你是否理解数字环境的基本逻辑 +- 你是否有能力管理文件、资料、任务和版本 +- 你是否能让工具为自己节省时间，而不是制造新的负担 + +所以这里讲的是“工具 + 系统”。工具是器，系统是你使用它们的方式。 + +--- + +## 建议先读什么 + +### 1. 数字素养 + +适合刚开始建立数字基础的人。建议优先看： + +- [电脑认知](./literacy/computer-basics.md) +- [高效打字](./literacy/typing.md) +- [网络工具](./literacy/network-proxy.md) +- [版本选择](./literacy/version-control.md) + +**你能获得什么：** 对自己的数字环境更有掌控感，少被基础问题反复卡住。 + +### 2. 信息管理 + +适合资料越来越多、任务越来越杂的人。建议优先看： + +- [云笔记](./pkm/cloud-notes.md) +- [协作文档](./pkm/collaboration-docs.md) +- [任务管理](./pkm/task-management.md) + +**你能获得什么：** 把信息和任务放回一个更清晰、可持续维护的结构里。 + +### 3. 生产力工具 + +适合已经有基础，希望进一步扩展能力边界的人。可按需选择： + +- [Git](./pro/git.md) +- [Linux](./pro/linux.md) +- [LaTeX](./pro/latex.md) +- [Prompt Engineering](./pro/prompt-engineering.md) +- [Docker](./pro/docker.md) +- [Premiere Pro](./pro/premiere.md) + +**你能获得什么：** 根据自己的方向需要，逐步积累更强的“可迁移工具力”。 + +### 4. VS Code 指南 + +适合希望把常用开发/写作环境调顺的人。入口： + +- [导览与配置](./vscode/index.md) +- [插件推荐](./vscode/extensions.md) + +--- + +## 推荐阅读路线 + +### 如果你刚开始补数字基础 + +1. [电脑认知](./literacy/computer-basics.md) +2. [高效打字](./literacy/typing.md) +3. [版本选择](./literacy/version-control.md) + +### 如果你更想建立个人工作流 + +1. [云笔记](./pkm/cloud-notes.md) +2. [协作文档](./pkm/collaboration-docs.md) +3. [任务管理](./pkm/task-management.md) + +### 如果你想进入更进阶的工具能力 + +1. [Git](./pro/git.md) +2. [Linux](./pro/linux.md) +3. [Docker](./pro/docker.md) + +--- + +## 读完这一模块后，你可以去哪里 + +- 想补“学习系统”：去看 [学会学习](../learning/index.md) +- 想补“心智与判断”：去看 [认知与心智](../mindset/index.md) +- 想补“合作沟通”：去看 [沟通与协作](../communication/index.md) +- 想补“长期成长”：去看 [成长与规划](../growth/index.md) diff --git a/docs/skills/tools/pkm/cloud-notes.md b/docs/skills/tools/pkm/cloud-notes.md index 6b7a801f..9e77ef37 100644 --- a/docs/skills/tools/pkm/cloud-notes.md +++ b/docs/skills/tools/pkm/cloud-notes.md @@ -1 +1,113 @@ +--- +tags: + - Topic-Productivity + - Topic-InformationLiteracy + - Type-Guide + - Level-Beginner + - Action-Building +--- + # 云笔记 + +云笔记的价值，不在于把一切都记下来，而在于帮你把**会反复用到的信息放在一个容易找回、容易更新、容易继续接着用的地方**。 + +这页适合这样的人： + +- 收藏夹、聊天记录、备忘录、截图散落各处，找东西总靠运气 +- 想开始用笔记软件，但又怕一上来搭太复杂的系统 +- 做了不少记录，却很少真的回看和复用 + +如果你现在首先想解决“看什么”的问题，建议先看 [信息输入](../../learning/intake/information-intake.md)；如果你更想处理“事情怎么推进”，可以接着看 [任务管理](./task-management.md)。 + +--- + +## 这页主要解决什么问题 + +很多人开始用云笔记，是因为感觉信息越来越多了。但如果只是把内容从别的地方搬进笔记软件，而没有明确用途，云笔记很快也会变成另一个杂物间。 + +所以，云笔记真正要解决的，不是“我能不能记很多”，而是： + +- 重要信息能不能被稳定收纳 +- 以后需要时能不能快速找回 +- 这份记录能不能继续更新、连接和复用 + +对大多数大学场景来说，云笔记最适合承接三类内容：长期资料、个人总结、可复用清单。像课程要点、项目记录、常见问题整理、申请材料经验、自己的阶段性复盘，都很适合放进云笔记。它不一定替代所有工具，但很适合作为你的“长期外脑”。 + +--- + +## 1. 先明确“什么值得记”，不要把云笔记当回收站 + +云笔记最常见的误区，就是见什么都想存。文章转存、群聊截图、灵感片段、网页摘录全都往里丢，结果几周之后根本不知道里面有什么。 + +更稳的原则是：**只记录那些未来大概率还会再用一次的信息。** + +你可以优先记这些内容： + +- 会反复参考的课程、项目和工具笔记 +- 你自己加工过的理解、总结和模板 +- 重要但零散、以后不想再重找一遍的资料 + +反过来，如果一条信息只是“也许有用”“看着挺想保存”，但你暂时没有明确使用场景，那它未必值得立刻进入云笔记。很多内容放进收藏夹或稍后阅读区就够了，不必一上来全部结构化。 + +云笔记不是为了证明你很努力，而是为了降低以后再次找到、再次理解的成本。 + +--- + +## 2. 结构越简单，越容易长期维护 + +很多人刚接触笔记软件时，会沉迷于搭系统：层级目录、标签矩阵、双向链接、各种模板一口气全上。短期很有成就感，长期却容易因为维护成本太高而放弃。 + +对大多数学生来说，一个够用的云笔记结构其实很简单。你只要能让笔记大致落在几个稳定区块里，就已经足够： + +- **课程 / 学习**：课程要点、作业记录、复盘 +- **项目 / 实践**：做过什么、踩过什么坑、以后怎么复用 +- **个人 / 长期积累**：申请信息、经验总结、清单模板 + +结构的目标不是“看起来像知识管理大神”，而是让你三周后还能看懂自己当初为什么这么记。只要能做到这一点，系统就已经是有效的。 + +如果你已经有一定记录习惯，建议把“主题页 + 关键链接 + 一句话总结”作为默认组织方式。这样比起建很多空目录，更容易让内容真正连起来。 + +--- + +## 3. 让笔记持续活着，而不是写完即埋 + +一条真正有价值的笔记，通常不是一次写完的，而是在后续使用中不断补充出来的。 + +比如你第一次写下某个工具的基本操作，下一次踩坑时可以补一条“常见问题”；第三次再用时，也许会加上一条“适合什么场景 / 不适合什么场景”。这样，笔记会慢慢从摘录变成经验。 + +所以，写笔记时不妨给自己保留一点“以后继续接着写”的空间。比起一次性追求完整，更重要的是让它能随着使用不断变得更好。 + +这也是为什么云笔记特别适合和真实行动配合使用。你在课程、项目、协作里遇到的问题，正好会反过来给你的笔记提供更新材料。时间一长，你积累下来的就不只是信息，而是一套越来越贴合自己的使用经验。 + +--- + +## 立即可做：搭一个不会很快废掉的最小笔记系统 + +你现在就可以从这 4 步开始： + +1. 只建 3 个一级区块：学习、项目、个人积累。 +2. 从最近正在处理的一门课或一个项目开始记，不要试图回填所有历史内容。 +3. 每条笔记至少写下“这条记录为什么值得以后再看”。 +4. 本周找一条旧笔记补充一次，让它从存档变成可更新资料。 + +做到这一步，你的云笔记就已经开始发挥作用，而不是停留在“装了一个软件”。 + +--- + +## 常见误区、边界与下一步 + +### 常见误区 + +- **误区一：先搭复杂系统再开始记。** 很多系统不是失败在设计差，而是失败在太难持续。 +- **误区二：什么都值得进笔记。** 没有使用预期的信息，往往只会增加噪音。 +- **误区三：笔记写完就结束。** 真正常用的笔记，会在使用中不断更新。 + +### 不适用范围 + +这页讲的是个人云笔记的基础策略，不会替代团队协作文档、正式知识库或学术管理工具。多人协作场景下，仍然要区分公共文档与个人笔记的边界。 + +### 接下来去哪里 + +- 想把“看到的东西”变成可积累记录：读 [信息输入](../../learning/intake/information-intake.md) +- 想让行动与记录联动：读 [任务管理](./task-management.md) +- 想先搭顺手的日常工作环境：读 [VS Code 导览与配置](../vscode/index.md) diff --git a/docs/skills/tools/pkm/task-management.md b/docs/skills/tools/pkm/task-management.md index 88b2bb97..17889575 100644 --- a/docs/skills/tools/pkm/task-management.md +++ b/docs/skills/tools/pkm/task-management.md @@ -1 +1,112 @@ +--- +tags: + - Topic-Productivity + - Topic-GoalSetting + - Type-Guide + - Level-Beginner + - Action-Practical +--- + # 任务管理 + +任务管理不是把待办事项记得更满，而是让你知道：**现在最该做什么、下一步是什么、哪些事情暂时不该占用你的注意力。** + +这页适合这样的人： + +- 脑子里一直挂着很多事，结果越想越乱，越乱越不想动 +- 任务一多就靠临时记忆和情绪推动，常常漏事或拖到最后 +- 用过一些待办工具，但很快就因为太复杂而放弃 + +如果你现在更缺的是信息整理，可以先看 [云笔记](./cloud-notes.md)；如果你经常被信息流打断，也建议配合阅读 [信息输入](../../learning/intake/information-intake.md)。 + +--- + +## 这页主要解决什么问题 + +很多人真正的问题，不是不会努力，而是每天面对的事情太多：上课、作业、实验、社团、比赛、生活杂事、突发消息，全都在抢注意力。只靠脑子记，很快就会出现两种结果： + +- 重要事情被挤到最后才想起来 +- 一直在忙，但始终没有推进真正关键的事 + +任务管理的作用，就是把“混在一起的压力”拆成可以处理的顺序。它不保证你马上变得特别自律，但能明显减少那种“脑子很满、手上却不知道先干嘛”的状态。 + +--- + +## 1. 先把任务从脑子里搬出来，再谈执行力 + +很多拖延并不是懒，而是因为脑子一直在后台同时挂着太多未处理事项。你不断提醒自己“别忘了那个作业”“这个周末还要交表”“要去问老师一件事”，注意力就会被持续切碎。 + +所以任务管理的第一步不是分类、排序、打标签，而是先把任务从脑子里卸下来，放到一个固定容器里。 + +这个容器可以很简单：待办软件、备忘录、纸质清单都行。关键不是工具多高级，而是你愿不愿意让所有待处理的事都进入同一个入口，而不是一半记在脑子里，一半藏在聊天记录里，一半写在别处。 + +只要你把任务都放进一个稳定入口，你就会明显感觉到脑内负担下降。事情还没变少，但你终于不用靠“怕忘记”来维持紧绷状态了。 + +--- + +## 2. 任务要拆到“现在就能开始”，而不是只写大标题 + +很多待办之所以越写越不想看，不是因为事情多，而是因为任务写得太大。 + +像“复习高数”“准备比赛”“改简历”“做项目”这种标题，看起来像任务，实际上更像一个领域。它们没有明确起点，也没有清楚的下一步，于是每次看到都会有心理阻力。 + +更有效的方式，是把任务写成一个你现在就能开始的动作： + +- 不写“复习高数”，改成“做完第 3 章例题 1-5” +- 不写“准备比赛”，改成“今晚确认题目方向并列出 3 个分工” +- 不写“改简历”，改成“更新项目经历的第一条描述” + +这种拆分有一个非常现实的好处：你不再需要靠情绪蓄力很久才能启动。任务越具体，开始动作的门槛越低，推进感也越明确。 + +任务管理不是为了把事情描述得很宏大，而是为了让你真的能动起来。 + +--- + +## 3. 每天只抓最重要的少数，不要让系统变成压力源 + +很多人一开始用任务系统很有热情，过几天就放弃，是因为他们把系统本身做成了新的压力来源。列表越攒越长，今天没做完就更焦虑，最后连打开都不想打开。 + +更稳的原则是：**保留完整清单，但每天只抓少数关键任务。** + +你可以把任务粗分成三层： + +- **必须处理**：有明确截止时间，或者不做会带来直接后果 +- **应该推进**：重要但不一定今天到期的长期事项 +- **可以稍后**：临时想到、低优先级、未来再处理也行的事 + +每天真正盯紧的，往往只需要 1-3 件最关键任务。剩下的存在系统里就好，不必假装今天全能做完。任务系统是为了帮你做取舍，不是为了提醒你永远落后。 + +如果你发现自己总是在执行中被打断，也可以把任务管理和 [精力管理](../../learning/energy/energy-management.md) 结合起来：在精力更好的时段做高认知任务，把杂事留给低负荷时段。这样系统才更贴近现实，而不是纸面自律。 + +--- + +## 立即可做：搭一个能坚持一周的最小任务系统 + +你现在就可以做这 4 步： + +1. 选一个固定入口，作为你唯一的任务收集处。 +2. 把脑子里挂着的所有待办先全部倒进去，不排序也可以。 +3. 从中挑出今天最重要的 1-3 件事，并拆成具体动作。 +4. 晚上花 5 分钟看一眼：哪些完成了，哪些需要改到明天。 + +只要能稳定做一周，你就已经比“全靠记忆和情绪推动”前进了一大步。 + +--- + +## 常见误区、边界与下一步 + +### 常见误区 + +- **误区一：工具越复杂越专业。** 多数人真正需要的是稳定入口和低摩擦使用。 +- **误区二：任务写得越大越有气势。** 任务越具体，越容易开始。 +- **误区三：每天要清空列表才算高效。** 更现实的目标是抓住真正关键的少数。 + +### 不适用范围 + +这页讲的是个人学习与生活中的基础任务管理，不涉及复杂项目管理、多人协作看板或正式团队流程。等你真的进入团队型项目，再按实际需求升级即可。 + +### 接下来去哪里 + +- 想把资料与行动连起来：读 [云笔记](./cloud-notes.md) +- 想减少输入噪音带来的分心：读 [信息输入](../../learning/intake/information-intake.md) +- 想更现实地安排节奏：读 [精力管理](../../learning/energy/energy-management.md) diff --git a/docs/skills/tools/vscode/index.md b/docs/skills/tools/vscode/index.md index e69de29b..608e468f 100644 --- a/docs/skills/tools/vscode/index.md +++ b/docs/skills/tools/vscode/index.md @@ -0,0 +1,123 @@ +--- +tags: + - Topic-ComputerLiteracy + - Topic-Productivity + - Type-Guide + - Level-Beginner + - Action-Optimizing +--- + +# VS Code 导览与配置 + +VS Code 不是只有“装上就能用”的编辑器，它更像一个可以陪你走很久的工作台。你不需要一开始把它折腾得很花，但至少应该把它调到**顺手、稳定、能支撑你日常学习与写作**。 + +这页适合这样的人： + +- 已经在用 VS Code，但界面、文件、终端总让自己有点乱 +- 刚接触开发或文档写作，想先建立一个稳定入口 +- 容易把编辑器越装越重，最后反而更卡、更乱 + +如果你连电脑和文件系统都还不太熟，建议先看 [电脑认知](../literacy/computer-basics.md)；如果你之后想补插件选择，再去看 [插件推荐](./extensions.md)。 + +--- + +## 这页主要解决什么问题 + +很多人初次接触 VS Code 时，会把重点放在“别人装了什么插件”或者“界面怎么更酷”。但对大多数大学场景来说，真正先要解决的是三个问题： + +- 你能不能快速打开、定位和管理自己的项目或资料 +- 你能不能在一个环境里稳定完成编辑、搜索、终端操作 +- 你有没有把编辑器调到足够顺手，而不是每次都被小摩擦打断 + +所以，VS Code 的入门重点不是炫技，而是让它成为一个低摩擦的工作环境。只要这件事做好，它既能服务写代码，也能服务写 Markdown、整理文本和处理轻量项目。 + +--- + +## 1. 先把工作区用明白，而不是到处双击单文件 + +VS Code 最值得建立的习惯之一，是尽量以“文件夹 / 项目”为单位打开内容，而不是零散地双击单个文件。 + +因为一旦你只打开一个文件，很多能力就很难形成：侧边栏结构看不清、全局搜索不好用、相对路径容易混乱、终端默认位置也不稳定。长期来看，这会让你一直停留在“临时改点东西”的使用方式里。 + +更推荐的做法是： + +- 给每门课、每个项目、每段文档整理一个清晰的文件夹 +- 用 “Open Folder” 打开整个目录 +- 在侧边栏中管理文件，而不是反复去系统文件管理器里找 + +这样你会很快习惯一种更清楚的工作方式：文件在哪、相关内容有哪些、自己现在正在改什么，一眼都能看出来。对于经常写 Markdown、管理课程材料或做小项目的人，这比任何花哨配置都更值。 + +--- + +## 2. 优先配好最常用的三块：搜索、终端、自动保存 + +如果只选三件最值得先调顺的功能，我会建议是：**全局搜索、内置终端、自动保存。** + +### 全局搜索 + +很多初学者遇到内容找不到、配置不知道在哪儿改，就会回到系统里一个文件一个文件翻。其实 VS Code 的搜索面板非常适合日常定位： + +- 找某个关键词出现在哪里 +- 找一段配置是在哪个文件里定义的 +- 快速理解一个项目中相同内容的分布 + +只要你开始用工作区方式打开内容，全局搜索就会变得非常顺手。 + +### 内置终端 + +内置终端的意义，不只是少开一个窗口，而是把“编辑”和“执行”放在一个上下文里。你在改 Markdown、跑命令、看目录结构时，不需要不断切换环境，心智负担会小很多。 + +在这个仓库里，本地预览和校验本来就依赖命令，比如 `uv run mkdocs serve`、`uv run mkdocs build --clean --strict --verbose`。如果你习惯在 VS Code 里直接打开终端，很多操作会更连贯。 + +### 自动保存 + +这不是高阶功能，却很实用。对刚开始建立工作流的人来说，自动保存可以明显减少“忘记保存、结果没生效”的低级摩擦。你不需要因为每次小改动都担心自己是不是漏按了保存键。 + +--- + +## 3. 克制地配置，而不是把编辑器越装越重 + +VS Code 最大的诱惑，就是“好像什么都能装一点”。但对初学者来说，过早追求复杂主题、海量插件和各种高级配置，往往只会把环境变得更乱。 + +一个更稳的原则是：**先把默认能力用到七成，再按真实痛点补配置。** + +比如： + +- 如果你经常写 Markdown，再考虑补和 Markdown 直接相关的能力 +- 如果你常常管理 Git 仓库，再针对版本控制补工具 +- 如果你发现某类文件总是格式混乱，再加对应的格式化支持 + +而不是一上来安装十几个“别人说很好用”的插件。插件一多，不仅会拖慢启动、制造冲突，还会让你很难判断到底哪部分功能来自哪里。对多数学生来说，稳定和清楚，比“功能堆满”更重要。 + +--- + +## 立即可做：把 VS Code 调成可长期使用的基础状态 + +你现在就可以做这 4 步： + +1. 用文件夹而不是单文件方式打开你常用的一份资料或项目。 +2. 试一次全局搜索，找到一个关键词在整个目录中的位置。 +3. 打开内置终端，在当前目录执行一次你常用的命令。 +4. 打开自动保存，让基础编辑摩擦先降下来。 + +做完这几步，VS Code 就已经从“偶尔打开的编辑器”变成“可以稳定工作的环境”。 + +--- + +## 常见误区、边界与下一步 + +### 常见误区 + +- **误区一：先装很多插件才算会用。** 真正重要的是先把工作区、搜索和终端用顺。 +- **误区二：界面越花越专业。** 对长期使用来说，清楚、稳定、低干扰更重要。 +- **误区三：只把 VS Code 当代码编辑器。** 它同样很适合 Markdown、文档、配置与轻量项目管理。 + +### 不适用范围 + +这页是 VS Code 的可发布 MVP 导览，不会覆盖调试器、远程开发、复杂语言配置或团队级工程实践。等你真的遇到对应场景，再按需补即可。 + +### 接下来去哪里 + +- 想看按需安装的扩展方向：读 [插件推荐](./extensions.md) +- 想先补数字基础：读 [电脑认知](../literacy/computer-basics.md) +- 想理解版本与环境选择：读 [版本选择](../literacy/version-control.md) diff --git a/docs/tags.md b/docs/tags.md index 4ad5a3b7..f5b51a26 100644 --- a/docs/tags.md +++ b/docs/tags.md @@ -1,3 +1,4 @@ + # 标签索引 这里是本站点的所有内容标签，按不同维度进行分类展示。您可以点击任意标签，查看所有关联的文章。 diff --git a/mkdocs.yml b/mkdocs.yml index 4ad73030..a6ab5385 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,86 +1,66 @@ # mkdocs.yml -# --- 网站基本信息 --- site_name: 寻路之南 site_url: https://cs4ncu.space/ site_author: NCUSCC & Community Contributors site_description: '寻路之南——写给普通人的大学成长指南。我们由一群普通本科生发起，致力于分享一套从自我认知开始的成长方法论。' -# --- 仓库信息 --- repo_name: NCUSCC/cs4ncu repo_url: https://github.com/NCUSCC/cs4ncu -edit_uri: 'edit/main/docs/' # 允许用户直接在 GitHub 上编辑页面 +edit_uri: 'edit/main/docs/' -# 版权信息 copyright: Copyright © cs4ncu 2024 ~ now | 南昌大学超算俱乐部 NCUSCC -# --- 主题配置 --- theme: name: material - language: zh # 设置语言为中文 + language: zh favicon: assets/ncuscc-logo.svg custom_dir: overrides icon: logo: my-logo/logo - # --- 外观与功能 --- - # 我们在这里配置日夜间模式切换器。 - # 具体的颜色将由 extra.css 文件精确控制。 palette: - scheme: default - primary: custom # <-- 激活自定义颜色 - accent: custom # <-- 激活自定义颜色 + primary: custom + accent: custom toggle: icon: material/brightness-7 name: 切换到夜间模式 - # 夜间模式：告诉主题使用你在 CSS 中定义的 'slate' 方案 - scheme: slate - primary: custom # <-- 激活自定义颜色 - accent: custom # <-- 激活自定义颜色 + primary: custom + accent: custom toggle: icon: material/brightness-4 name: 切换到日间模式 - # 字体配置 (你的设置很好，予以保留) font: text: 'Roboto' code: 'JetBrains Mono' - # Logo 和 Favicon (建议添加) - # logo: assets/images/logo.svg - # favicon: assets/images/favicon.png - - # 增强功能 features: - - navigation.tabs # 启用顶部标签页导航 - - navigation.sections # 左侧导航自动展开子章节 - - content.code.copy # 为所有代码块添加“复制”按钮 - - content.code.annotate # 允许代码块注释 - - search.suggest # 搜索时提供建议 - - navigation.tags + - navigation.tabs + - navigation.sections + - content.code.copy + - content.code.annotate + - search.suggest + - navigation.tags - content.action.view - navigation.top - - navigation.footer # 显示文档底部区域（导航指示器依赖此区域） + - navigation.footer - navigation.prev_next -# --- 插件配置 (强烈建议添加) --- plugins: - search: - lang: zh # 启用中文搜索支持 - - tags # 启用标签系统 + lang: zh + - tags - git-committers: repository: NCUSCC/cs4ncu branch: main token: !ENV GITHUB_TOKEN - # 仅当环境变量 ENABLE_COMMITTERS=true 时才启用此插件 - # 默认情况下 (本地开发), 此插件是禁用的 enabled: !ENV [ENABLE_COMMITTERS, false] -# --- Markdown 扩展 (增强内容显示) --- -# 合并后的 mkdocs.yml 配置 - markdown_extensions: # --- 基础与美化扩展 --- @@ -114,10 +94,9 @@ markdown_extensions: - pymdownx.inlinehilite - # Highlight: 为代码块提供语法高亮 (合并了两个列表的配置) - pymdownx.highlight: - anchor_linenums: true # 允许链接到代码的特定行 - line_spans: __span # (来自第二个列表) 方便 CSS 进行更细致的样式控制 + anchor_linenums: true + line_spans: __span pygments_lang_class: true # InlineHilite: 支持行内代码高亮 @@ -145,7 +124,7 @@ nav: - '寻路通识课': - '开始之前': - '先别慌，我们聊聊': 'growth-general-course/00-before-we-start/prologue-the-start.md' - - '全站导览': 'growth-general-course/00-before-we-start/overview.md' + - '全站导览与推荐路径': 'growth-general-course/00-before-we-start/overview.md' - '本科生通识第零课': - '核心原则': 'growth-general-course/01-the-zero-course/the-core.md' - '完整课程导览': 'growth-general-course/01-the-zero-course/index.md' @@ -236,9 +215,8 @@ nav: - # 顶层导航 4: 昌大专属附录 - - '昌大专属资源库': - - '本部分导览': 'ncu-exclusive/index.md' + - '昌大专属': + - '入口与说明': 'ncu-exclusive/index.md' - '学业发展': # --- 以下为普适性单页内容 --- - '培养方案全解': 'ncu-exclusive/academic-development/program-guide.md' @@ -262,7 +240,7 @@ nav: - '社区与共建': - '我们的初心': 'community/our-story.md' - '打卡教程': 'community/how-to-check-in.md' - - '路友打卡墙': 'community/contributors.md' # <- 我将'打卡墙'改成了更标准的'路友打卡墙' + - '路友打卡墙': 'community/contributors.md' - '友联与推荐': 'community/friends.md' - '项目共建指南': - '核心准则': @@ -272,7 +250,7 @@ nav: - '搭建基础环境': 'community/contributing/development-setup.md' - '分支保护策略': 'community/contributing/branch-protection.md' - '网站部署': 'community/contributing/deployment.md' - - '智能 PR 验证系统': 'community/contributing/pr-workflow-guide.md' + - 'PR 校验工作流': 'community/contributing/pr-workflow-guide.md' - 'Tag 系统': 'community/contributing/workflow/tag.md' - '内容完成度分析': 'community/contributing/workflow/todo.md' - '开发实践指南': @@ -290,12 +268,12 @@ nav: - '标签索引': 'tags.md' - '项目进度': 'COMPLETION_REPORT.md' -# --- 自定义文件链接 (你的设置很好，予以保留) --- extra_css: - 'css/extra.css' - https://unpkg.com/katex@0/dist/katex.min.css extra_javascript: - javascripts/readingProgress.js + - javascripts/404.js - javascripts/katex.js - https://unpkg.com/katex@0/dist/katex.min.js - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js @@ -306,14 +284,13 @@ extra: social: - icon: simple/github link: https://github.com/NCUSCC - - icon: fontawesome/brands/qq # <--- 示例 + - icon: fontawesome/brands/qq link: https://qm.qq.com/q/VLuObOsLg4 - - icon: fontawesome/brands/discord # <--- 示例 + - icon: fontawesome/brands/discord link: https://discord.gg/Rux6DHRStP -extra: analytics: provider: google - property: G-LGCE6HDLE5 # 替换为您的 Google Analytics ID + property: G-LGCE6HDLE5 feedback: title: 这个页面对你有帮助吗？ ratings: diff --git a/overrides/404.html b/overrides/404.html index 5cde8b1a..39d68f73 100644 --- a/overrides/404.html +++ b/overrides/404.html @@ -1,90 +1,15 @@ {% extends "main.html" %} {% block content %} - - -
-
- +

404

Page Not Found

@@ -99,88 +24,9 @@

404

您访问的页面不存在

别担心，让我们帮您找到正确的方向。

-
- -
- -
- -
- +
+
- - - -{% endblock %} \ No newline at end of file +{% endblock %} diff --git a/pyproject.toml b/pyproject.toml index 242e4e5f..39ff1d53 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,3 +1,7 @@ +[build-system] +requires = ["setuptools>=61"] +build-backend = "setuptools.build_meta" + [project] name = "cs4ncu" version = "0.1.0" @@ -17,9 +21,11 @@ dependencies = [ "typer>=0.16.1", ] -[tool.completion-analyzer] -# --- 可选配置 --- +[tool.uv] +package = true +[tool.completion-analyzer] +# Markdown 报告为生成文件，默认输出到 docs/COMPLETION_REPORT.md md_output = "docs/COMPLETION_REPORT.md" csv_output = "reports/completion_report.csv" @@ -31,6 +37,7 @@ min_chars = 50 good_chars = 500 [project.scripts] +# 对外统一命令入口 mtag = "tools.manage_tags:main" cana = "tools.completion_analyzer:main" diff --git a/reports/completion_report.csv b/reports/completion_report.csv index cb55a490..c6d13bfa 100644 --- a/reports/completion_report.csv +++ b/reports/completion_report.csv @@ -1,93 +1,95 @@ -title,file_path,category,exists,char_count,word_count,line_count,status,completion_level,manual_status,final_status,size_assessment -首页,index.md,其他,True,2857,323,110,substantial,high,,substantial,非常丰富 -先别慌，我们聊聊,growth-general-course/00-before-we-start/prologue-the-start.md,其他,True,1403,151,75,substantial,high,,substantial,丰富 -全站导览,growth-general-course/00-before-we-start/overview.md,其他,True,66,11,6,basic,medium,,basic,较少 -核心原则,growth-general-course/01-the-zero-course/the-core.md,其他,True,1962,221,86,substantial,high,,substantial,丰富 -完整课程导览,growth-general-course/01-the-zero-course/index.md,其他,True,937,100,44,substantial,high,,substantial,较多 -本部分导览,growth-general-course/01-the-zero-course/part1/index.md,其他,True,620,61,35,substantial,high,,substantial,较多 -思维模式转换,growth-general-course/01-the-zero-course/part1/ch1-mindset.md,其他,True,1316,132,63,substantial,high,,substantial,丰富 -自我认知方法,growth-general-course/01-the-zero-course/part1/ch2-the-self.md,其他,True,1917,308,70,substantial,high,,substantial,丰富 -本部分导览,growth-general-course/01-the-zero-course/part2/index.md,其他,True,631,66,34,substantial,high,,substantial,较多 -信息辨析能力,growth-general-course/01-the-zero-course/part2/ch3-information-filter.md,其他,True,1324,129,62,substantial,high,,substantial,丰富 -信息获取入门,growth-general-course/01-the-zero-course/part2/ch4-info-gathering.md,其他,True,1262,142,58,substantial,high,,substantial,丰富 -本部分导览,growth-general-course/01-the-zero-course/part3/index.md,其他,True,591,63,31,substantial,high,,substantial,较多 -设定探索方向,growth-general-course/01-the-zero-course/part3/ch5-the-output.md,其他,True,995,116,44,substantial,high,,substantial,较多 -低成本实践与验证,growth-general-course/01-the-zero-course/part3/ch6-the-test.md,其他,True,1248,142,62,substantial,high,,substantial,丰富 -本部分导览,skills/index.md,第零点五课堂,True,599,61,30,substantial,high,,substantial,较多 -导览,skills/mindset/index.md,认知与心智,True,11,2,1,minimal,low,,minimal,极少 -优绩主义,skills/mindset/fixed/meritocracy.md,认知与心智,True,2102,217,69,substantial,high,,substantial,非常丰富 -名校情节,skills/mindset/fixed/elite-complex.md,认知与心智,True,2827,307,94,substantial,high,,substantial,非常丰富 -做题家思维,skills/mindset/fixed/solver-mindset.md,认知与心智,True,1931,215,62,substantial,high,,substantial,丰富 -幸存者偏差,skills/mindset/bias/survivorship-bias.md,认知与心智,True,2661,254,59,substantial,high,,substantial,非常丰富 -确认偏差,skills/mindset/bias/confirmation-bias.md,认知与心智,True,2480,212,58,substantial,high,,substantial,非常丰富 -沉没成本,skills/mindset/bias/sunk-cost.md,认知与心智,True,2363,219,62,substantial,high,,substantial,非常丰富 -贝叶斯法则,skills/mindset/model/bayesian-thinking.md,认知与心智,True,2510,289,89,substantial,high,,substantial,非常丰富 -合作与博弈,skills/mindset/model/collaboration.md,认知与心智,True,2657,301,94,substantial,high,,substantial,非常丰富 -冒名顶替综合征,skills/mindset/mental/impostor-syndrome.md,认知与心智,True,10,1,1,minimal,low,,minimal,极少 -学会独处,skills/mindset/mental/learn-to-be-alone.md,认知与心智,True,2391,261,67,substantial,high,,substantial,非常丰富 -焦虑与内耗,skills/mindset/mental/anxiety-impostor.md,认知与心智,True,2862,334,71,substantial,high,,substantial,非常丰富 -导览,skills/learning/index.md,学会学习,True,10,2,1,minimal,low,,minimal,极少 -元学习,skills/learning/meta/meta-learning.md,学会学习,True,6,1,1,minimal,low,,minimal,极少 -信息输入,skills/learning/intake/information-intake.md,学会学习,True,7,1,1,minimal,low,,minimal,极少 -知识内化,skills/learning/consolidation/knowledge-consolidation.md,学会学习,True,7,1,1,minimal,low,,minimal,极少 -精力管理,skills/learning/energy/energy-management.md,学会学习,True,0,0,0,empty,none,,empty,空白 -导览,skills/communication/index.md,沟通与协作,True,11,2,1,minimal,low,,minimal,极少 -沟通技巧,skills/communication/skills/communication.md,沟通与协作,True,0,0,0,empty,none,,empty,空白 -构建人际关系网,skills/communication/skills/network-of-relationships.md,沟通与协作,True,3699,431,100,substantial,high,,substantial,非常丰富 -团队协作,skills/communication/teamwork/teamwork.md,沟通与协作,True,1592,180,52,substantial,high,,substantial,丰富 -人际矛盾处理,skills/communication/skills/dealing-conflicts.md,沟通与协作,True,3260,383,98,substantial,high,,substantial,非常丰富 -导览,skills/tools/index.md,工具与系统,True,11,2,1,minimal,low,,minimal,极少 -电脑认知,skills/tools/literacy/computer-basics.md,工具与系统,True,2642,308,113,substantial,high,,substantial,非常丰富 -高效打字,skills/tools/literacy/typing.md,工具与系统,True,1956,215,75,substantial,high,,substantial,丰富 -网络工具,skills/tools/literacy/network-proxy.md,工具与系统,True,0,0,0,empty,none,,empty,空白 -版本选择,skills/tools/literacy/version-control.md,工具与系统,True,3944,392,130,substantial,high,,substantial,非常丰富 -云笔记,skills/tools/pkm/cloud-notes.md,工具与系统,True,6,1,1,minimal,low,,minimal,极少 -协作文档,skills/tools/pkm/collaboration-docs.md,工具与系统,True,7,1,1,minimal,low,,minimal,极少 -任务管理,skills/tools/pkm/task-management.md,工具与系统,True,7,1,1,minimal,low,,minimal,极少 -Git,skills/tools/pro/git.md,工具与系统,True,2424,334,92,substantial,high,,substantial,非常丰富 -Linux,skills/tools/pro/linux.md,工具与系统,True,3568,403,107,substantial,high,,substantial,非常丰富 -LaTeX,skills/tools/pro/latex.md,工具与系统,True,0,0,0,empty,none,,empty,空白 -Prompt Engineering,skills/tools/pro/prompt-engineering.md,工具与系统,True,4685,514,126,substantial,high,,substantial,非常丰富 -Docker,skills/tools/pro/docker.md,工具与系统,True,0,0,0,empty,none,,empty,空白 -导览与配置,skills/tools/vscode/index.md,工具与系统,True,0,0,0,empty,none,,empty,空白 -插件推荐,skills/tools/vscode/extensions.md,工具与系统,True,0,0,0,empty,none,,empty,空白 -导览,skills/growth/index.md,成长与规划,True,11,2,1,minimal,low,,minimal,极少 -财商启蒙,skills/growth/finance/financial-literacy.md,成长与规划,True,7,1,1,minimal,low,,minimal,极少 -聪明消费,skills/growth/finance/smart-spending.md,成长与规划,True,0,0,0,empty,none,,empty,空白 -健康管理,skills/growth/health/healthy-management.md,成长与规划,True,2561,242,97,substantial,high,,substantial,非常丰富 -信息差,skills/growth/opportunity/information-gap.md,成长与规划,True,0,0,0,empty,none,,empty,空白 -开源之旅,skills/growth/opportunity/open-source-journey.md,成长与规划,True,0,0,0,empty,none,,empty,空白 -实验班解读,skills/growth/opportunity/innovation-classes.md,成长与规划,True,3017,339,95,substantial,high,,substantial,非常丰富 -职业规划,skills/growth/opportunity/career-planning.md,成长与规划,True,7,1,1,minimal,low,,minimal,极少 -本部分导览,ncu-exclusive/index.md,其他,True,6,1,1,minimal,low,,minimal,极少 -培养方案全解,ncu-exclusive/academic-development/program-guide.md,其他,True,15,3,1,minimal,low,,minimal,极少 -学分绩点体系,ncu-exclusive/academic-development/credits-and-gpa.md,其他,True,0,0,0,empty,none,,empty,空白 -特色实验班,ncu-exclusive/academic-development/experimental-classes.md,其他,True,0,0,0,empty,none,,empty,空白 -计算机转专业,ncu-exclusive/major-transfer/cs.md,其他,True,3150,350,183,substantial,high,,substantial,非常丰富 -计科保研,ncu-exclusive/postgraduate-recommendation/cs.md,其他,True,2925,308,113,substantial,high,,substantial,非常丰富 -11408 备考,ncu-exclusive/postgraduate-exam/cs.md,其他,True,14,3,1,minimal,low,,minimal,极少 -计算机相关,ncu-exclusive/clubs-and-organizations/cs.md,其他,True,0,0,0,empty,none,,empty,空白 -通识课程体系,ncu-exclusive/campus-life/general-education-courses.md,其他,True,0,0,0,empty,none,,empty,空白 -体育与体测,ncu-exclusive/campus-life/pe-and-fitness-tests.md,其他,True,0,0,0,empty,none,,empty,空白 -新生军训,ncu-exclusive/campus-life/military-training.md,其他,True,1311,140,49,substantial,high,,substantial,丰富 -我们的初心,community/our-story.md,其他,True,11,2,3,minimal,low,,minimal,极少 -打卡教程,community/how-to-check-in.md,其他,True,2294,302,103,substantial,high,,substantial,非常丰富 -路友打卡墙,community/contributors.md,其他,True,714,87,31,substantial,high,,substantial,较多 -行为准则,community/contributing/code-of-conduct.md,其他,True,1802,170,93,substantial,high,,substantial,丰富 -贡献流程,community/contributing/how-to-contribute.md,其他,True,3222,416,103,substantial,high,,substantial,非常丰富 -搭建基础环境,community/contributing/development-setup.md,其他,True,1987,235,85,substantial,high,,substantial,丰富 -分支保护策略,community/contributing/branch-protection.md,其他,True,1214,150,58,substantial,high,,substantial,丰富 -网站部署,community/contributing/deployment.md,其他,True,1849,218,68,substantial,high,,substantial,丰富 -智能 PR 验证系统,community/contributing/pr-workflow-guide.md,其他,True,3476,411,230,substantial,high,,substantial,非常丰富 -Tag 系统,community/contributing/workflow/tag.md,其他,True,3255,346,121,substantial,high,,substantial,非常丰富 -内容完成度分析,community/contributing/workflow/todo.md,其他,True,2151,231,96,substantial,high,,substantial,非常丰富 -调整全局样式 (CSS),community/contributing/styling.md,其他,True,3689,424,140,substantial,high,,substantial,非常丰富 -调整项目配色,community/contributing/colors.md,其他,True,1415,167,60,substantial,high,,substantial,丰富 -调整提示框样式,community/contributing/admonitions.md,其他,True,3019,339,111,substantial,high,,substantial,非常丰富 -调整图片样式,community/contributing/figure.md,其他,True,841,103,47,substantial,high,,substantial,较多 -写作规范,community/contributing/writing-guide.md,其他,True,7456,808,308,substantial,high,,substantial,非常丰富 -写作指令 (prompt),community/contributing/writing-prompt.md,其他,True,7028,741,246,substantial,high,,substantial,非常丰富 -提示框样式样例,community/contributing/admonitions-examples.md,其他,True,7951,1085,161,substantial,high,,substantial,非常丰富 -一份开发手记,community/contributing/development-log.md,其他,True,3868,436,137,substantial,high,,substantial,非常丰富 -标签索引,tags.md,其他,True,1512,142,53,substantial,high,,substantial,丰富 -项目进度,COMPLETION_REPORT.md,其他,True,8266,1051,180,substantial,high,,substantial,非常丰富 +title,file_path,category,exists,char_count,word_count,line_count,status,completion_level,manual_status,final_status,size_assessment +首页,index.md,其他,True,3647,476,159,substantial,high,,substantial,非常丰富 +先别慌，我们聊聊,growth-general-course/00-before-we-start/prologue-the-start.md,其他,True,1372,148,72,substantial,high,,substantial,丰富 +全站导览与推荐路径,growth-general-course/00-before-we-start/overview.md,其他,True,3857,508,195,substantial,high,,substantial,非常丰富 +核心原则,growth-general-course/01-the-zero-course/the-core.md,其他,True,1962,221,86,substantial,high,,substantial,丰富 +完整课程导览,growth-general-course/01-the-zero-course/index.md,其他,True,937,100,44,substantial,high,,substantial,较多 +本部分导览,growth-general-course/01-the-zero-course/part1/index.md,其他,True,589,58,32,substantial,high,,substantial,较多 +思维模式转换,growth-general-course/01-the-zero-course/part1/ch1-mindset.md,其他,True,1285,129,60,substantial,high,,substantial,丰富 +自我认知方法,growth-general-course/01-the-zero-course/part1/ch2-the-self.md,其他,True,1303,137,62,substantial,high,,substantial,丰富 +本部分导览,growth-general-course/01-the-zero-course/part2/index.md,其他,True,631,66,34,substantial,high,,substantial,较多 +信息辨析能力,growth-general-course/01-the-zero-course/part2/ch3-information-filter.md,其他,True,1324,129,62,substantial,high,,substantial,丰富 +信息获取入门,growth-general-course/01-the-zero-course/part2/ch4-info-gathering.md,其他,True,1262,142,58,substantial,high,,substantial,丰富 +本部分导览,growth-general-course/01-the-zero-course/part3/index.md,其他,True,591,63,31,substantial,high,,substantial,较多 +设定探索方向,growth-general-course/01-the-zero-course/part3/ch5-the-output.md,其他,True,995,116,44,substantial,high,,substantial,较多 +低成本实践与验证,growth-general-course/01-the-zero-course/part3/ch6-the-test.md,其他,True,1248,142,62,substantial,high,,substantial,丰富 +本部分导览,skills/index.md,第零点五课堂,True,1983,233,122,substantial,high,,substantial,丰富 +导览,skills/mindset/index.md,认知与心智,True,735,87,21,substantial,high,,substantial,较多 +优绩主义,skills/mindset/fixed/meritocracy.md,认知与心智,True,2102,217,69,substantial,high,,substantial,非常丰富 +名校情节,skills/mindset/fixed/elite-complex.md,认知与心智,True,2827,307,94,substantial,high,,substantial,非常丰富 +做题家思维,skills/mindset/fixed/solver-mindset.md,认知与心智,True,1931,215,62,substantial,high,,substantial,丰富 +幸存者偏差,skills/mindset/bias/survivorship-bias.md,认知与心智,True,2674,253,59,substantial,high,,substantial,非常丰富 +确认偏差,skills/mindset/bias/confirmation-bias.md,认知与心智,True,2734,252,58,substantial,high,,substantial,非常丰富 +沉没成本,skills/mindset/bias/sunk-cost.md,认知与心智,True,2377,217,62,substantial,high,,substantial,非常丰富 +贝叶斯法则,skills/mindset/model/bayesian-thinking.md,认知与心智,True,2510,289,89,substantial,high,,substantial,非常丰富 +合作与博弈,skills/mindset/model/collaboration.md,认知与心智,True,2657,301,94,substantial,high,,substantial,非常丰富 +冒名顶替综合征,skills/mindset/mental/impostor-syndrome.md,认知与心智,True,2578,270,71,substantial,high,,substantial,非常丰富 +学会独处,skills/mindset/mental/learn-to-be-alone.md,认知与心智,True,2391,261,67,substantial,high,,substantial,非常丰富 +焦虑与内耗,skills/mindset/mental/anxiety-impostor.md,认知与心智,True,2862,334,71,substantial,high,,substantial,非常丰富 +导览,skills/learning/index.md,学会学习,True,1674,206,97,substantial,high,,substantial,丰富 +元学习,skills/learning/meta/meta-learning.md,学会学习,True,3089,285,118,substantial,high,,substantial,非常丰富 +信息输入,skills/learning/intake/information-intake.md,学会学习,True,2731,322,118,substantial,high,,substantial,非常丰富 +知识内化,skills/learning/consolidation/knowledge-consolidation.md,学会学习,True,2367,256,114,substantial,high,,substantial,非常丰富 +精力管理,skills/learning/energy/energy-management.md,学会学习,True,2603,226,55,substantial,high,,substantial,非常丰富 +导览,skills/communication/index.md,沟通与协作,True,1438,172,84,substantial,high,,substantial,丰富 +沟通技巧,skills/communication/skills/communication.md,沟通与协作,True,2337,236,119,substantial,high,,substantial,非常丰富 +构建人际关系网,skills/communication/skills/network-of-relationships.md,沟通与协作,True,3699,431,100,substantial,high,,substantial,非常丰富 +团队协作,skills/communication/teamwork/teamwork.md,沟通与协作,True,1592,180,52,substantial,high,,substantial,丰富 +人际矛盾处理,skills/communication/skills/dealing-conflicts.md,沟通与协作,True,3260,383,98,substantial,high,,substantial,非常丰富 +导览,skills/tools/index.md,工具与系统,True,1756,222,104,substantial,high,,substantial,丰富 +电脑认知,skills/tools/literacy/computer-basics.md,工具与系统,True,2642,308,113,substantial,high,,substantial,非常丰富 +高效打字,skills/tools/literacy/typing.md,工具与系统,True,2179,234,86,substantial,high,,substantial,非常丰富 +网络工具,skills/tools/literacy/network-proxy.md,工具与系统,True,0,0,0,empty,none,,empty,空白 +版本选择,skills/tools/literacy/version-control.md,工具与系统,True,3944,392,130,substantial,high,,substantial,非常丰富 +云笔记,skills/tools/pkm/cloud-notes.md,工具与系统,True,2322,248,113,substantial,high,,substantial,非常丰富 +协作文档,skills/tools/pkm/collaboration-docs.md,工具与系统,True,7,1,1,minimal,low,,minimal,极少 +任务管理,skills/tools/pkm/task-management.md,工具与系统,True,2329,253,112,substantial,high,,substantial,非常丰富 +Git,skills/tools/pro/git.md,工具与系统,True,2434,334,96,substantial,high,,substantial,非常丰富 +Linux,skills/tools/pro/linux.md,工具与系统,True,3568,403,107,substantial,high,,substantial,非常丰富 +LaTeX,skills/tools/pro/latex.md,工具与系统,True,4020,464,133,substantial,high,,substantial,非常丰富 +Prompt Engineering,skills/tools/pro/prompt-engineering.md,工具与系统,True,4685,514,126,substantial,high,,substantial,非常丰富 +Docker,skills/tools/pro/docker.md,工具与系统,True,4232,511,158,substantial,high,,substantial,非常丰富 +Premiere Pro,skills/tools/pro/premiere.md,工具与系统,True,11573,1115,348,substantial,high,,substantial,非常丰富 +导览与配置,skills/tools/vscode/index.md,工具与系统,True,2547,301,123,substantial,high,,substantial,非常丰富 +插件推荐,skills/tools/vscode/extensions.md,工具与系统,True,0,0,0,empty,none,,empty,空白 +导览,skills/growth/index.md,成长与规划,True,1642,195,94,substantial,high,,substantial,丰富 +财商启蒙,skills/growth/finance/financial-literacy.md,成长与规划,True,2258,226,114,substantial,high,,substantial,非常丰富 +聪明消费,skills/growth/finance/smart-spending.md,成长与规划,True,0,0,0,empty,none,,empty,空白 +健康管理,skills/growth/health/healthy-management.md,成长与规划,True,2561,242,97,substantial,high,,substantial,非常丰富 +信息差,skills/growth/opportunity/information-gap.md,成长与规划,True,0,0,0,empty,none,,empty,空白 +开源之旅,skills/growth/opportunity/open-source-journey.md,成长与规划,True,0,0,0,empty,none,,empty,空白 +实验班解读,skills/growth/opportunity/innovation-classes.md,成长与规划,True,3017,339,95,substantial,high,,substantial,非常丰富 +职业规划,skills/growth/opportunity/career-planning.md,成长与规划,True,2621,278,122,substantial,high,,substantial,非常丰富 +入口与说明,ncu-exclusive/index.md,其他,True,1509,173,92,substantial,high,,substantial,丰富 +培养方案全解,ncu-exclusive/academic-development/program-guide.md,其他,True,15,3,1,minimal,low,,minimal,极少 +学分绩点体系,ncu-exclusive/academic-development/credits-and-gpa.md,其他,True,2758,291,90,substantial,high,,substantial,非常丰富 +特色实验班,ncu-exclusive/academic-development/experimental-classes.md,其他,True,0,0,0,empty,none,,empty,空白 +计算机转专业,ncu-exclusive/major-transfer/cs.md,其他,True,3150,350,183,substantial,high,,substantial,非常丰富 +计科保研,ncu-exclusive/postgraduate-recommendation/cs.md,其他,True,2925,308,113,substantial,high,,substantial,非常丰富 +11408 备考,ncu-exclusive/postgraduate-exam/cs.md,其他,True,14,3,1,minimal,low,,minimal,极少 +计算机相关,ncu-exclusive/clubs-and-organizations/cs.md,其他,True,0,0,0,empty,none,,empty,空白 +通识课程体系,ncu-exclusive/campus-life/general-education-courses.md,其他,True,0,0,0,empty,none,,empty,空白 +体育与体测,ncu-exclusive/campus-life/pe-and-fitness-tests.md,其他,True,0,0,0,empty,none,,empty,空白 +新生军训,ncu-exclusive/campus-life/military-training.md,其他,True,1989,196,60,substantial,high,,substantial,丰富 +我们的初心,community/our-story.md,其他,True,2634,260,169,substantial,high,,substantial,非常丰富 +打卡教程,community/how-to-check-in.md,其他,True,2416,326,133,substantial,high,,substantial,非常丰富 +路友打卡墙,community/contributors.md,其他,True,3346,422,80,substantial,high,,substantial,非常丰富 +友联与推荐,community/friends.md,其他,True,1030,109,65,substantial,high,,substantial,丰富 +行为准则,community/contributing/code-of-conduct.md,其他,True,1802,170,93,substantial,high,,substantial,丰富 +贡献流程,community/contributing/how-to-contribute.md,其他,True,3222,416,103,substantial,high,,substantial,非常丰富 +搭建基础环境,community/contributing/development-setup.md,其他,True,1987,235,85,substantial,high,,substantial,丰富 +分支保护策略,community/contributing/branch-protection.md,其他,True,1214,150,58,substantial,high,,substantial,丰富 +网站部署,community/contributing/deployment.md,其他,True,939,121,63,substantial,high,,substantial,较多 +PR 校验工作流,community/contributing/pr-workflow-guide.md,其他,True,1105,154,72,substantial,high,,substantial,丰富 +Tag 系统,community/contributing/workflow/tag.md,其他,True,3272,352,121,substantial,high,,substantial,非常丰富 +内容完成度分析,community/contributing/workflow/todo.md,其他,True,2169,238,96,substantial,high,,substantial,非常丰富 +调整全局样式 (CSS),community/contributing/styling.md,其他,True,3689,424,140,substantial,high,,substantial,非常丰富 +调整项目配色,community/contributing/colors.md,其他,True,1415,167,60,substantial,high,,substantial,丰富 +调整提示框样式,community/contributing/admonitions.md,其他,True,3019,339,111,substantial,high,,substantial,非常丰富 +调整图片样式,community/contributing/figure.md,其他,True,841,103,47,substantial,high,,substantial,较多 +写作规范,community/contributing/writing-guide.md,其他,True,7456,808,308,substantial,high,,substantial,非常丰富 +写作指令 (prompt),community/contributing/writing-prompt.md,其他,True,7028,741,246,substantial,high,,substantial,非常丰富 +提示框样式样例,community/contributing/admonitions-examples.md,其他,True,7951,1085,161,substantial,high,,substantial,非常丰富 +一份开发手记,community/contributing/development-log.md,其他,True,3868,436,137,substantial,high,,substantial,非常丰富 +标签索引,tags.md,其他,True,1581,152,54,substantial,high,,substantial,丰富 +项目进度,COMPLETION_REPORT.md,其他,True,8642,1098,184,substantial,high,,substantial,非常丰富 diff --git a/tools/completion_analyzer.py b/tools/completion_analyzer.py index 6a000bd1..a52a88cc 100644 --- a/tools/completion_analyzer.py +++ b/tools/completion_analyzer.py @@ -2,6 +2,9 @@ """ 内容完成情况分析脚本 (v2.1) +标准命令入口：`uv run cana` +生成文件：`docs/COMPLETION_REPORT.md`，请勿手动编辑。 + 从 mkdocs.yml 和 docs 目录分析每个小节的完成情况， 统计字数并做简单判断，输出 CSV 和 Markdown 格式的报告。 @@ -47,7 +50,7 @@ def load_config(repo_path: Path, args: argparse.Namespace) -> Dict[str, Any]: """加载配置，优先级：命令行参数 > pyproject.toml > 默认值""" # 1. 默认值 defaults = { - "md_output": "docs/reports/COMPLETION_REPORT.md", + "md_output": "docs/COMPLETION_REPORT.md", "csv_output": "reports/completion_report.csv", "min_chars": 50, "good_chars": 500, @@ -118,6 +121,8 @@ def load_mkdocs_config(self) -> Dict: with open(self.mkdocs_path, "r", encoding="utf-8") as f: content = f.read() content = re.sub(r"!!python/name:[^\s\n]+", '""', content) + content = re.sub(r"!ENV\s+\[[^\]]+\]", 'false', content) + content = re.sub(r"!ENV\s+[^\s\n]+", '""', content) return yaml.safe_load(content) except Exception as e: print(f"错误：无法加载或解析 mkdocs.yml: {e}", file=sys.stderr) @@ -317,7 +322,8 @@ def save_to_markdown( output_path.parent.mkdir(parents=True, exist_ok=True) header = [ - f"# 内容完成情况报告", + "# 内容完成情况报告", + "> 本页为生成文件，请勿手动编辑。如需更新，请运行 `uv run cana`。", f"> 报告生成时间：{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n", ] if "error" not in commit_info: diff --git a/tools/manage_tags.py b/tools/manage_tags.py index 1850d219..31a2b7b3 100644 --- a/tools/manage_tags.py +++ b/tools/manage_tags.py @@ -4,6 +4,9 @@ # Author: GitHub Copilot (guided by ywh555hhh) # Date: 2025-08-27 # +# Standard entrypoint: `uv run mtag` +# Generated output: `docs/tags.md`，请勿手动编辑。 +# # Features: # - Strict format and prefix validation. # - Canonical case validation for all tags. @@ -222,7 +225,8 @@ def interactive_unknown_tag_management(unknown_tags: dict, dictionary: dict) -> def generate_index_file(dictionary: dict): """根据标签词典重新生成 docs/tags.md。""" print(f"\n🚀 正在生成新的标签索引文件：{TAGS_INDEX_FILE}...") - content = """# 标签索引 + content = """ +# 标签索引 这里是本站点的所有内容标签，按不同维度进行分类展示。您可以点击任意标签，查看所有关联的文章。 @@ -270,8 +274,12 @@ def main_sync(): if not unknown: print("\n✨ 未发现新的未知标签。所有标签均符合规范。") - choice = input(" 是否需要强制重新生成 tags.md 文件？([y]es/[n]o): ").lower() - if choice == "y": + if sys.stdin.isatty(): + choice = input(" 是否需要强制重新生成 tags.md 文件？([y]es/[n]o): ").lower() + if choice == "y": + generate_index_file(dictionary) + else: + print(" 检测到非交互环境，自动重新生成 tags.md 文件。") generate_index_file(dictionary) return @@ -307,7 +315,7 @@ def main_check(): if has_critical_errors or has_unknown: print( - "\n💡 检查失败。请在本地运行 `uv run tools/manage_tags.py sync` 来处理这些问题。" + "\n💡 检查失败。请在本地运行 `uv run mtag sync` 来处理这些问题。" ) sys.exit(1) else: diff --git a/tools/weaver_build_raw_db.py b/tools/weaver_build_raw_db.py index 32aec652..528460cb 100644 --- a/tools/weaver_build_raw_db.py +++ b/tools/weaver_build_raw_db.py @@ -1,3 +1,10 @@ +""" +原始数据库构建脚本。 + +生成文件：`tools/data/raw_database.json`，请勿手动编辑。 +如需更新，请运行本脚本重新生成。 +""" + import typer import json import re @@ -100,7 +107,7 @@ def extract_headings(content: str) -> list[str]: @app.command(help="构建原始数据库，提取所有文章的元数据和摘要。") def build_raw_db(): - """扫描 docs/ 目录，提取每篇文章的关键信息，生成 raw_database.json。""" + """扫描 docs/ 目录，提取每篇文章的关键信息，生成 `tools/data/raw_database.json`。""" # (主函数逻辑保持不变，此处省略以保持简洁) # ... 你可以从上一个版本复制 build_raw_db 函数的完整内容 ... database = [] diff --git a/uv.lock b/uv.lock index d1d6a1f5..ab981de9 100644 --- a/uv.lock +++ b/uv.lock @@ -1,5 +1,5 @@ version = 1 -revision = 2 +revision = 3 requires-python = ">=3.12" [[package]] @@ -100,7 +100,7 @@ wheels = [ [[package]] name = "cs4ncu" version = "0.1.0" -source = { virtual = "." } +source = { editable = "." } dependencies = [ { name = "gitpython" }, { name = "mkdocs" },