https://docs.ncatbot.xyz/assets/index.html-D3Hmb8AH.js

1import{_ as d,c as h,a as l,b as i,e as a,d as t,w as e,r as p,o as r}from"./app-X5ZAzaQf.js";const k={};function c(o,s){const n=p("RouteLink");return r(),h("div",null,[s[12]||(s[12]=l(`<blockquote><p>从零搭建 NcatBot 开发环境的完整指南。</p></blockquote><hr><h2 id="quick-reference" tabindex="-1"><a class="header-anchor" href="#quick-reference"><span>Quick Reference</span></a></h2><p>以下步骤可在 5 分钟内完成 NcatBot 开发环境搭建。</p><h3 id="_1-fork-clone" tabindex="-1"><a class="header-anchor" href="#_1-fork-clone"><span>1. Fork &amp; Clone</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 1. 在 GitHub 上 Fork https://github.com/ncatbot/ncatbot</span></span>
2<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 2. Clone 到本地</span></span>
3<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> clone</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> https://github.com/</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">&lt;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">你的用户</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">名</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">&gt;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">/ncatbot.git</span></span>
4<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">cd</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ncatbot</span></span>
5<span class="line"></span>
6<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 3. 添加上游远程仓库</span></span>
7<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> remote</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> add</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> upstream</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">

7 https://github.com/ncatbot/ncatbot.git</span></span>
8<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> fetch</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> upstream</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="_2-安装依赖" tabindex="-1"><a class="header-anchor" href="#_2-安装依赖"><span>2. 安装依赖</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> sync</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --extra</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> dev</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>该命令会自动完成：</p><ol><li>创建 <code>.venv/</code> 虚拟环境</li><li>安装 <code>pyproject.toml</code> 中的运行依赖</li><li>安装开发工具（pytest、ruff、mypy、tox、pre-commit 等）</li></ol><h3 id="_3-激活虚拟环境" tabindex="-1"><a class="header-anchor" href="#_3-激活虚拟环境"><span>3. 激活虚拟环境</span></a></h3><div class="language-powershell line-numbers-mode" data-ext="powershell" data-title="powershell"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># Windows PowerShell</span></span>
9<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.venv\\Scripts\\activate.ps1</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div></div></div><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># Linux / macOS</span></span>
10<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">source</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> .venv/bin/activate</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div></div></div><p>激活后终端提示符前缀显示 <code>(.venv)</code>。</p><h3 id="_4-验证安装" tabindex="-1"><a class="header-anchor" href="#_4-验证安装"><span>4. 验证安装</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">python</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> -c</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">import ncatbot; print(&#39;ncatbot 可用&#39;)</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span>
11<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> pytest</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --version</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="_5-安装-pre-commit-钩子" tabindex="-1"><a class="header-anchor" href="#_5-安装-pre-commit-钩子"><span>5. 安装 pre-commit 钩子</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> pre-commit</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> install</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="_6-创建功能分支并开始开发" tabindex="-1"><a class="header-anchor" href="#_6-创建功能分支并开始开发"><span>6. 创建功能分支并开始开发</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> fetch</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> upstream</span></span>
12<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> checkout</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> -b</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> feat/你的功能描述</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> upstream/main</span></span>
13<span class="line"></span>
14<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 编写代码...</span></span>
15<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> pytest</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">           # 运行测试</span></span>
16<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> add</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> .</span></span>
17<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> commit</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> -m</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">feat: 你的功能描述</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span>
18<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> push</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> origin</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> feat/你的功能描述</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>然后在 GitHub 上创建 Pull Request，目标分支为上游 <code>main</code>。</p><hr><h2 id="工具链速查" tabindex="-1"><a class="header-anchor" href="#工具链速查"><span>工具链速查</span></a></h2><h3 id="必需工具" tabindex="-1"><a class="header-anchor" href="#必需工具"><span>必需工具</span></a></h3><table><thead><tr><th>

18工具</th><th>最低版本</th><th>说明</th></tr></thead><tbody><tr><td><strong>Python</strong></td><td>≥ 3.12</td><td>推荐 3.12 或 3.13</td></tr><tr><td><strong>uv</strong></td><td>最新稳定版</td><td>Python 包管理器 + 虚拟环境管理</td></tr><tr><td><strong>Git</strong></td><td>≥ 2.30</td><td>版本控制</td></tr></tbody></table><h3 id="安装命令" tabindex="-1"><a class="header-anchor" href="#安装命令"><span>安装命令</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 安装 uv — Windows (PowerShell)</span></span>
19<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">powershell</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> -ExecutionPolicy</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ByPass</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> -c</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">irm https://astral.sh/uv/install.ps1 | iex</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span>
20<span class="line"></span>
21<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 安装 uv — Linux / macOS</span></span>
22<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">curl</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> -LsSf</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> https://astral.sh/uv/install.sh</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> |</span><span style="--shiki-light:#59873A;--shiki-dark:#80A665;"> sh</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="版本验证" tabindex="-1"><a class="header-anchor" href="#版本验证"><span>版本验证</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --version</span></span>
23<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">python</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --version</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">   # 确认 ≥ 3.12</span></span>
24<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --version</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="开发工具链-由-uv-sync-extra-dev-自动安装" tabindex="-1"><a class="header-anchor" href="#开发工具链-由-uv-sync-extra-dev-自动安装"><span>开发工具链（由 <code>uv sync --extra dev</code> 自动安装）</span></a></h3><table><thead><tr><th>工具</th><th>用途</th></tr></thead><tbody><tr><td><strong>pytest</strong></td><td>测试框架</td></tr><tr><td><strong>ruff</strong></td><td>代码 lint + 格式化</td></tr><tr><td><strong>mypy</strong></td><td>静态类型检查</td></tr><tr><td><strong>tox</strong></td><td>多版本测试</td></tr><tr><td><strong>pre-commit</strong></td><td>Git 提交前自动检查</td></tr><tr><td><strong>codespell</strong></td><td>拼写检查</td></tr></tbody></table><hr><h2 id="常用开发命令" tabindex="-1"><a class="header-anchor" href="#常用开发命令"><span>常用开发命令</span></a></h2><h3 id="代码格式化与检查" tabindex="-1">

24<a class="header-anchor" href="#代码格式化与检查"><span>代码格式化与检查</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># Ruff lint（自动修复）</span></span>
25<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ruff</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> check</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --fix</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> .</span></span>
26<span class="line"></span>
27<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># Ruff 格式化</span></span>
28<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ruff</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> format</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> .</span></span>
29<span class="line"></span>
30<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 类型检查</span></span>
31<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> mypy</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ncatbot/</span></span>
32<span class="line"></span>
33<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 拼写检查</span></span>
34<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> codespell</span></span>
35<span class="line"></span>
36<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># pre-commit 全量运行</span></span>
37<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> pre-commit</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --all-files</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="测试" tabindex="-1"><a class="header-anchor" href="#测试"><span>测试</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 运行全部测试（含覆盖率）</span></span>
38<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> pytest</span></span>
39<span class="line"></span>
40<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 覆盖率详情</span></span>
41<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> pytest</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --cov=ncatbot</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --cov-report=term-missing</span></span>
42<span class="line"></span>
43<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 多版本测试（tox）</span></span>
44<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> tox</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">              # 全部版本</span></span>
45<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> tox</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> -e</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> py312</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">     # 仅 Python 3.12</span></span>
46<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> run</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> tox</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> -e</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> py313</span><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">     # 仅 Python 3.13</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><blockquote><p>覆盖率 HTML 报告输出到 <code>htmlcov/</code>，浏览器打开 <code>htmlcov/index.html</code> 查看。</p></blockquote><h3 id="依赖管理" tabindex="-1"><a class="header-anchor" href="#依赖管理"><span>依赖管理</span></a></h3><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 添加依赖后重新锁定 + 同步</span></span>
47<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> lock</span></span>
48<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> sync</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --extra</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> dev</span></span>
49<span class="line"></span>
50<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 升级所有依赖</span></span>
51<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> lock</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --upgrade</span></span>
52<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">uv</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> sync</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> --extra</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> dev</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><table><thead><tr><th>

52文件</th><th>作用</th></tr></thead><tbody><tr><td><code>pyproject.toml</code></td><td>定义顶层依赖（宽泛版本范围）</td></tr><tr><td><code>uv.lock</code></td><td>自动生成的精确锁定版本（纳入版本控制）</td></tr></tbody></table><h3 id="项目结构速览" tabindex="-1"><a class="header-anchor" href="#项目结构速览"><span>项目结构速览</span></a></h3><div class="language-text line-numbers-mode" data-ext="text" data-title="text"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span>ncatbot/</span></span>
53<span class="line"><span>├── adapter/    协议适配器（NapCat、Mock）</span></span>
54<span class="line"><span>├── api/        Bot API 封装（IAPIClient / BotAPIClient）</span></span>
55<span class="line"><span>├── app/        应用编排层（BotClient 生命周期管理）</span></span>
56<span class="line"><span>├── cli/        命令行工具（ncatbot run / dev / config / plugin）</span></span>
57<span class="line"><span>├── core/       核心引擎（Dispatcher 事件分发 / Registry 处理器注册）</span></span>
58<span class="line"><span>├── event/      事件实体（MessageEvent / NoticeEvent / RequestEvent）</span></span>
59<span class="line"><span>├── plugin/     插件框架（NcatBotPlugin / Mixin / Loader）</span></span>
60<span class="line"><span>├── service/    服务层（RBAC / Schedule / FileWatcher）</span></span>
61<span class="line"><span>├── testing/    测试工具（TestHarness / 数据工厂）</span></span>
62<span class="line"><span>├── types/      Pydantic 数据模型（消息段 / 事件数据 / 枚举）</span></span>
63<span class="line"><span>└── utils/      公共工具（日志 / 配置 / 网络 / 错误定义）</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div>`,43)),i("p",null,[s[1]||(s[1]=a("各模块详细职责与数据流参阅 ")),t(n,{to:"/notes/guide/11.%20%E6%9E%B6%E6%9E%84%E4%B8%8E%E6%A6%82%E5%BF%B5/1.%20%E6%9E%B6%E6%9E%84%E6%80%BB%E8%A7%88.html"},{default:e(()=>s[0]||(s[0]=[a("架构文档")])),_:1}),s[2]||(s[2]=a("。"))]),s[13]||(s[13]=l(`<h3 id="代码规范速查" tabindex="-1"><a class="header-anchor" href="#代码规范速查"><span>代码规范速查</span></a></h3><ul><li>遵循 <strong>PEP 8</strong>（Ruff 自动格式化）</li><li><strong>尽量添加类型注解</strong>，尤其是函数签名和返回值</li><li>行尾统一 <strong>LF</strong>（pre-commit 自动转换）</li><li>提交信息遵循 <a href="https://www.conventionalcommits.org/zh-hans/v1.0.0/" target="_blank" rel="noopener noreferrer">Conventional Commits</a>：<code>&lt;type&gt;(&lt;scope&gt;): &lt;description&gt;</code></li></ul><table><thead><tr><th>类型</th><th>说明</th><th>示例</th></tr></thead><tbody><tr><td><code>feat</code></td><td>新功能</td><td><code>feat: 添加消息撤回功能</code></td></tr><tr><td><code>fix</code></td><td>Bug 修复</td><td><code>fix(api): 修复消息队列溢出 #123</code></td></tr><tr><td><code>docs</code></td><td>文档变更</td><td><code>docs: 更新安装指南</code></td></tr><tr><td><code>refactor</code></td><td>重构</td><td><code>refactor(core): 简化事件分发逻辑</code></td></tr><tr><td><code>test</code></td><td>测试</td><td><code>test: 补充 Registry 单元测试</code></td></tr><tr><td><code>chore</code></td><td>构建/工具</td><td><code>chore: 升级 ruff 版本</code></td></tr></tbody></table><h3 id="分支命名" tabindex="-1"><a class="header-anchor" href="#分支命名"><span>分支命名</span></a></h3><table><thead><tr><th>

63前缀</th><th>用途</th><th>示例</th></tr></thead><tbody><tr><td><code>feat/</code></td><td>新功能</td><td><code>feat/message-recall</code></td></tr><tr><td><code>fix/</code></td><td>Bug 修复</td><td><code>fix/queue-overflow</code></td></tr><tr><td><code>docs/</code></td><td>文档</td><td><code>docs/plugin-guide</code></td></tr><tr><td><code>refactor/</code></td><td>重构</td><td><code>refactor/dispatcher</code></td></tr><tr><td><code>test/</code></td><td>测试</td><td><code>test/registry-unit</code></td></tr></tbody></table><h3 id="pr-描述模板" tabindex="-1"><a class="header-anchor" href="#pr-描述模板"><span>PR 描述模板</span></a></h3><div class="language-markdown line-numbers-mode" data-ext="markdown" data-title="markdown"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#999999;--shiki-light-font-weight:bold;--shiki-dark:#666666;--shiki-dark-font-weight:bold;">##</span><span style="--shiki-light:#1C6B48;--shiki-light-font-weight:bold;--shiki-dark:#4D9375;--shiki-dark-font-weight:bold;"> 变更说明</span></span>
64<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">&lt;!-- 简要描述本次变更的内容和动机 --&gt;</span></span>
65<span class="line"></span>
66<span class="line"><span style="--shiki-light:#999999;--shiki-light-font-weight:bold;--shiki-dark:#666666;--shiki-dark-font-weight:bold;">##</span><span style="--shiki-light:#1C6B48;--shiki-light-font-weight:bold;--shiki-dark:#4D9375;--shiki-dark-font-weight:bold;"> 变更类型</span></span>
67<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [ ] 新功能 (feat)</span></span>
68<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [ ] Bug 修复 (fix)</span></span>
69<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [ ] 文档更新 (docs)</span></span>
70<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [ ] 重构 (refactor)</span></span>
71<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [ ] 测试 (test)</span></span>
72<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [ ] 其他 (chore / style / perf)</span></span>
73<span class="line"></span>
74<span class="line"><span style="--shiki-light:#999999;--shiki-light-font-weight:bold;--shiki-dark:#666666;--shiki-dark-font-weight:bold;">##</span><span style="--shiki-light:#1C6B48;--shiki-light-font-weight:bold;--shiki-dark:#4D9375;--shiki-dark-font-weight:bold;"> 关联 Issue</span></span>
75<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;">&lt;!-- Closes #xxx 或 Refs #xxx --&gt;</span></span>
76<span class="line"></span>
77<span class="line"><span style="--shiki-light:#999999;--shiki-light-font-weight:bold;--shiki-dark:#666666;--shiki-dark-font-weight:bold;">##</span><span style="--shiki-light:#1C6B48;--shiki-light-font-weight:bold;--shiki-dark:#4D9375;--shiki-dark-font-weight:bold;"> 检查清单</span></span>
78<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [ ] 代码通过 </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">\`</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">uv run pytest</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">\`</span></span>
79<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [ ] 代码通过 </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">\`</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">uv run ruff check .</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">\`</span></span>
80<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [ ] 已添加 / 更新相关测试（如适用）</span></span>
81<span class="line"><span style="--shiki-light:#A65E2B;--shiki-dark:#D4976C;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> [ ] 已更新相关文档（如适用）</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="pr-提交后" tabindex="-1"><a class="header-anchor" href="#pr-提交后"><span>PR 提交后</span></a></h3><ul><li><strong>CI 检查</strong>：GitHub Actions 自动运行 lint、测试和多版本验证</li><li><strong>Code Review</strong>：维护者审阅代码，可能要求修改</li><li><strong>同步上游</strong>：如果 PR 存在冲突：</li></ul><div class="language-bash line-numbers-mode" data-ext="bash" data-title="bash"><button class="copy" title="复制代码" data-copied="已复制"></button><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code><span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> fetch</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> upstream</span></span>
82<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> merge</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> upstream/main</span></span>
83<span class="line"><span style="--shiki-light:#A0ADA0;--shiki-dark:#758575DD;"># 解决冲突后</span></span>
84<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> add</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> .</span></span>
85<span class="line"><span style="--shiki-light:#59873A;--shiki-dark:#80A665;">git</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> commit</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> -m</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">chore: 合并上游变更</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><hr><h2 id="深入阅读" tabindex="-1"><a class="header-anchor" href="#深入阅读"><span>深入阅读</span></a></h2>`,12)),i("table",null,[s[11]||(s[11]=i("thead",null,[i("tr",null,[i("th",null,"文档"),i("th",null,"内容")])],-1)),i("tbody",null,[i("tr",null,[i("td",null,[t(n,{to:"/notes/contributing/1.%20%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83/1.%20%E9%AB%98%E7%BA%A7%E8%AE%BE%E7%BD%AE.html"},{default:e(()=>s[3]||(s[3]=[a("高级开发环境")])),_:1})]),s[4]||(s[4]=i("td",null,"IDE 配置（VSCode settings.json）、调试配置（launch.json）、CI/CD 本地模拟、NapCat 本地部署、常见问题排查",-1))]),i("tr",null,[i("td",null,[t(n,{to:"/notes/guide/11.%20%E6%9E%B6%E6%9E%84%E4%B8%8E%E6%A6%82%E5%BF%B5/1.%20%E6%9E%B6%E6%9E%84%E6%80%BB%E8%A7%88.html"},{default:e(()=>s[5]||(s[5]=[a("架构总览")])),_:1})]),s[6]||(s[6]=i("td",null,"项目整体架构、模块职责、数据流与生命周期",-1))]),i("tr",null,[i("td",null,[t(n,{to:"/notes/contributing/2.%20%E8%AE%BE%E8%AE%A1%E5%86%B3%E7%AD%96/"},{default:e(()=>s[7]||(s[7]=[a("设计决策")])),_:1})]),s[8]||(s[8]=i("td",null,"关键设计决策与取舍",-1))]),i("tr",null,[i("td",null,[t(n,{to:"/notes/contributing/3.%20%E6%A8%A1%E5%9D%97%E5%86%85%E9%83%A8%E5%AE%9E%E7%8E%B0/"},{default:e(()=>s[9]||(s[9]=[a("模块内部实现")])),_:1})]),s[10]||(s[10]=i("td",null,"各模块内部实现细节",-1))])])])])}const g=d(k,[["render",c],["__file","index.html.vue"]]),v=JSON.parse('{"path":"/contributing/afd9taf5/","title":"开发环境搭建","lang":"zh-CN","frontmatter":{"title":"开发环境搭建","createTime":"2026/03/19 17:26:45","permalink":"/contributing/afd9taf5/","de

85scription":"从零搭建 NcatBot 开发环境的完整指南。 Quick Reference 以下步骤可在 5 分钟内完成 NcatBot 开发环境搭建。 1. Fork & Clone 2. 安装依赖 该命令会自动完成： 创建 .venv/ 虚拟环境 安装 pyproject.toml 中的运行依赖 安装开发工具（pytest、ruff、mypy、tox、pre-...","head":[["meta",{"property":"og:url","content":"http://docs.ncatbot.xyz/contributing/afd9taf5/"}],["meta",{"property":"og:site_name","content":"NcatBot 文档"}],["meta",{"property":"og:title","content":"开发环境搭建"}],["meta",{"property":"og:description","content":"从零搭建 NcatBot 开发环境的完整指南。 Quick Reference 以下步骤可在 5 分钟内完成 NcatBot 开发环境搭建。 1. Fork & Clone 2. 安装依赖 该命令会自动完成： 创建 .venv/ 虚拟环境 安装 pyproject.toml 中的运行依赖 安装开发工具（pytest、ruff、mypy、tox、pre-..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"zh-CN"}],["meta",{"property":"og:updated_time","content":"2026-04-17T14:13:00.000Z"}],["meta",{"property":"article:modified_time","content":"2026-04-17T14:13:00.000Z"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"开发环境搭建\\",\\"image\\":[\\"\\"],\\"dateModified\\":\\"2026-04-17T14:13:00.000Z\\",\\"author\\":[]}"]]},"headers":[],"readingTime":{"minutes":4.32,"words":1296},"git":{"updatedTime":1776435180000,"contributors":[{"name":"GEYUANwuqi","username":"GEYUANwuqi","email":"[email protected]","commits":1,"avatar":"https://gravatar.com/avatar/1cf26d82e91dff657f3fa4d4911cdabcf7b76396339e886e69f99b15d4c8c808?d=retro"}]},"autoDesc":true,"filePathRelative":"notes/contributing/1. 开发环境/README.md"}');export{g as comp,v as data};