<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>Felix</title>
    <link>https://felix.muke.chat/</link>
    <description>记录所学，分享所思。</description>
    <language>zh-CN</language>
    <atom:link href="https://felix.muke.chat/rss.xml" rel="self" type="application/rss+xml" />
    <lastBuildDate>Thu, 12 Nov 2026 00:00:00 GMT</lastBuildDate>
    <item>
      <title>多 Agent 如何共享长期记忆：从 Proxy 接入到按需召回</title>
      <link>https://felix.muke.chat/notes/multi-agent-shared-memory</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/multi-agent-shared-memory</guid>
      <pubDate>Thu, 05 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>从 Memory Proxy 接入出发，理解多 Agent 如何通过分层记忆、按需召回、资产权限与绑定共享经验，以及异步提炼和会话缓存的生效边界。</description>
      <category>AI Agent</category>
      <category>Agent</category>
      <category>记忆</category>
      <category>多 Agent</category>
      <category>RAG</category>
      <content:encoded><![CDATA[<p>用 Agent 做项目时，很容易遇到这样的情况：上午在一个会话里讲清楚了业务背景，下午换个工具，又得重新解释；开发 Agent 已经知道某个接口必须兼容旧客户端，评审 Agent 却没有这段上下文；一次排障终于找到了正确步骤，下次碰到类似问题，仍然从头摸索。</p>
<p>这些重复工作有一个共同原因：有价值的信息散落在不同工具、不同会话和不同上下文窗口里。任务结束后，经验很难成为下一次工作的起点。</p>
<p>共享长期记忆的做法，是把值得复用的信息交给独立的服务保存、整理和管理。不同 Agent 通过统一入口访问这些记忆，再根据身份、权限和当前任务读取需要的内容。</p>
<p>要理解这套机制，可以沿着一次模型请求往下看：请求经过哪里，记忆如何进入上下文，工作结果怎样回流，以及下一位 Agent 凭什么能够读到它。</p>
<p>如果还不熟悉上下文、会话记忆与长期记忆的区别，可以先读<a href="https://felix.muke.chat/notes/agent-context-memory">《Agent 如何管理上下文和记忆》</a>。</p>
<h2>1. 先分清：共享服务、共享资产与共享上下文</h2>
<p>“所有 Agent 共享同一个 Memory Server”，描述的是一套公共基础设施。</p>
<p>同一套服务里，可以同时存在多个用户、多个团队、多个 Agent，以及各自的私有记忆和被明确分享的资产。使用相同的服务地址，只是建立了共同入口；某条记忆能否被另一个 Agent 使用，还取决于权限和资产绑定。</p>
<p>这几个概念需要分开理解：</p>
<table>
<thead>
<tr>
<th>概念</th>
<th>解决的问题</th>
<th>示例</th>
</tr>
</thead>
<tbody>
<tr>
<td>当前会话上下文</td>
<td>这一轮推理已经看到了什么</td>
<td>用户刚刚提出的需求、工具返回的测试结果</td>
</tr>
<tr>
<td>长期记忆</td>
<td>会话结束后，哪些信息仍值得保留</td>
<td>项目约束、已确认的决策、用户偏好</td>
</tr>
<tr>
<td>共享记忆资产</td>
<td>哪些保留的信息可以交给其他 Agent 使用</td>
<td>开发与评审共同使用的兼容性约定</td>
</tr>
</tbody>
</table>
<p>另一个容易混淆的地方，是“Agent 客户端”和“业务 Agent”。</p>
<p>Claude Code、Codex 等是执行任务的客户端；“后端开发”“代码评审”“发布检查”则可以是记忆平台里定义的业务角色。客户端连接 Proxy 后，会关联到具体的业务 Agent，进而获得这个角色的说明和记忆资产。</p>
<p>因此，换一个客户端仍有机会继承已有经验；同一个客户端切换到另一个业务角色，也可能获得不同的记忆集合。具体身份如何关联，由客户端适配和会话初始化流程决定。</p>
<h2>2. 为什么在模型前面放一层 Proxy</h2>
<p>Agent 原本会把请求直接发送给模型。接入共享记忆后，请求先经过 Memory Proxy：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">模型请求与响应：
Agent 客户端 ⇄ Memory Proxy ⇄ 上游 LLM

记忆读取与对话回流：
Memory Proxy ⇄ Memory Core

管理与知识查询：
Memory Hub 管理面板
  ├─ 用户、团队、资产与绑定 → Memory Core
  └─ 构建与管理 → Knowledge Service（Wiki / CodeGraph）

Agent 客户端
  └─ 按注入的说明调用知识工具 → Knowledge Service
</code></pre>
<p>这里有三类职责：</p>
<ul>
<li><strong>Proxy 负责请求链路</strong>：识别客户端和会话，解析身份，准备上下文，转发模型请求，并在轮次结束后回流数据。</li>
<li><strong>Core 负责记忆与资产元数据</strong>：保存和处理记忆，管理用户、团队、Agent、权限及绑定关系。</li>
<li><strong>Hub 和 Knowledge Service 负责管理与知识能力</strong>：前者提供操作界面，后者构建和查询 Wiki、代码图谱等资源。</li>
</ul>
<p>因此，Memory Server 可以理解为统一的记忆服务体系。实际部署中，接入、存储、知识处理和管理界面可以由不同组件承担。</p>
<p>把 Proxy 放在模型调用路径上，有一个直接好处：可以在客户端原有调用链里补充记忆能力。对已经适配的客户端，接入主要表现为修改模型服务地址和凭据。</p>
<p>例如，完成服务部署与账号准备后，Claude Code 的接入配置可以写成：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#FF7B72">export</span><span style="color:#E6EDF3"> ANTHROPIC_BASE_URL</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">'http://127.0.0.1:8096/claude-code/default'</span></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#E6EDF3"> ANTHROPIC_AUTH_TOKEN</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">'&#x3C;业务用户的 user_key>'</span></span>
</code></pre>
<p>其中，<code>default</code> 是这个示例中的记忆实例 ID。客户端请求先到 Proxy，Proxy 再根据服务端配置调用上游模型。</p>
<p>这里的“协议兼容”有明确边界：客户端继续使用它支持的模型协议，但 Proxy 会解析、补充请求中的上下文。不同客户端在消息结构、会话 ID、流式响应和交互工具上存在差异，服务端仍需要适配。</p>
<h2>3. 第一次请求，先确定“谁在做什么”</h2>
<p>服务收到请求后，首先需要把它放进正确的工作范围。</p>
<p>几个常见身份维度分别承担不同作用：</p>
<table>
<thead>
<tr>
<th>维度</th>
<th>含义</th>
</tr>
</thead>
<tbody>
<tr>
<td>Instance / Space</td>
<td>请求属于哪个记忆服务实例</td>
</tr>
<tr>
<td>User</td>
<td>当前使用服务的人是谁</td>
</tr>
<tr>
<td>Team</td>
<td>当前工作所属的协作团队</td>
</tr>
<tr>
<td>Agent</td>
<td>本次使用的业务角色及其记忆配置</td>
</tr>
<tr>
<td>Task</td>
<td>本次工作关联的任务，可按流程选择</td>
</tr>
<tr>
<td>Session</td>
<td>当前连续会话，用来复用初始化状态和上下文缓存</td>
</tr>
</tbody>
</table>
<p>以支持交互初始化的客户端为例，Proxy 可以通过客户端已有的提问工具，让用户选择 Team、Agent 和 Task。另一些接入方式会使用请求头预选这些信息。</p>
<p>初始化完成后，后续请求就能沿用这次会话的关联关系：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">用户凭据 → 解析用户身份
会话初始化 → 确定 Team / Agent / Task
资产绑定与权限 → 确定本次可使用的记忆集合
上下文装配 → 把角色说明、记忆摘要与工具入口交给模型
</code></pre>
<p>这一步决定了共享记忆的实际边界。只把请求转发到同一个 Proxy，还不足以建立完整的记忆使用链路。</p>
<h2>4. 对话如何变成可复用的长期记忆</h2>
<p>原始聊天记录包含大量过程信息：临时尝试、被否定的方案、重复表达、工具输出。后续 Agent 通常只需要其中一部分。</p>
<p>分层记忆为这些信息提供了不同粒度的组织方式：</p>
<table>
<thead>
<tr>
<th>层级</th>
<th>保存内容</th>
<th>适合回答的问题</th>
</tr>
</thead>
<tbody>
<tr>
<td>L0 Conversation</td>
<td>原始对话与上下文</td>
<td>当时到底说了什么？</td>
</tr>
<tr>
<td>L1 Atom</td>
<td>提取出的事实、偏好、约束和事件</td>
<td>哪条具体约定影响当前任务？</td>
</tr>
<tr>
<td>L2 Scenario</td>
<td>按项目或场景组织的知识块</td>
<td>这个工作场景有哪些背景与决策？</td>
</tr>
<tr>
<td>L3 Core / Persona</td>
<td>较稳定的画像、长期模式与高层信息</td>
<td>开始工作前需要先理解哪些稳定背景？</td>
</tr>
</tbody>
</table>
<p>假设用户在一次订单系统改造中说：</p>
<blockquote>
<p><code>/v1/orders</code> 仍有旧版客户端使用，这次改造必须保留原有请求字段。</p>
</blockquote>
<p>这条信息在不同层级，可以形成不同的表达：</p>
<ul>
<li><strong>L0</strong> 保留这次对话，供以后核对原话和来源。</li>
<li><strong>L1</strong> 提取明确约束：订单接口改造需要保持旧版请求字段兼容。</li>
<li><strong>L2</strong> 把约束放进“订单系统兼容性改造”的场景，与相关背景、方案和决策一起组织。</li>
<li><strong>L3</strong> 用来保存经过长期交互确认的稳定背景。一次接口约束本身，还不足以证明用户具有某种长期偏好。</li>
</ul>
<p>这些层级表达的是不同的记忆粒度。具体哪些内容会被提炼、何时更新，由后台 Pipeline、生成规则和触发条件决定。</p>
<p>保存 L0 也有实际价值：摘要可能丢失限定条件，提炼结果可能需要纠正。遇到重要决策时，Agent 可以回到原始对话核对依据。</p>
<h2>5. 记忆怎样进入下一次模型调用</h2>
<p>读取策略同样需要分层。把所有历史记录装进每次请求，会增加输入量，也会让模型面对更多无关信息。</p>
<p>当前参考实现中的主要策略是：</p>
<ul>
<li><strong>L3 直接注入</strong>：让模型先获得稳定的长期背景。</li>
<li><strong>L2 注入场景目录与摘要</strong>：需要细节时，再读取对应场景正文。</li>
<li><strong>L0、L1 提供查询工具</strong>：模型根据当前问题主动检索原始对话或原子记忆。</li>
</ul>
<p>模型因此可以先看到一份简短的导航，再决定要深入读取什么。例如，下面是一份用于说明思路的场景目录：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">orders/compatibility
  订单接口兼容性约定与迁移背景

orders/release-checklist
  订单模块发布前的回归检查项目
</code></pre>
<p>如果当前任务是修改订单接口，模型可以读取第一份场景；如果只是调整页面文案，就没有必要打开这些内容。</p>
<h3>5.1 按需查询，如何做到不安装额外插件</h3>
<p>一个关键细节是：Proxy 可以在上下文里提供 HTTP 工具的调用说明，让 Agent 使用已有的 Bash 等执行能力访问服务。</p>
<p>例如，查询 L1 原子记忆的请求可以是：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#FFA657">curl</span><span style="color:#79C0FF"> --fail-with-body</span><span style="color:#79C0FF"> --silent</span><span style="color:#79C0FF"> --show-error</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#79C0FF">  -X</span><span style="color:#A5D6FF"> POST</span><span style="color:#A5D6FF"> 'http://127.0.0.1:8096/memory-bridge/v3/atomic/search'</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#79C0FF">  -H</span><span style="color:#A5D6FF"> 'Content-Type: application/json'</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#79C0FF">  -H</span><span style="color:#A5D6FF"> 'x-tdai-service-id: default'</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#79C0FF">  -H</span><span style="color:#A5D6FF"> 'x-conversation-id: &#x3C;已初始化的当前会话 ID>'</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#79C0FF">  -d</span><span style="color:#A5D6FF"> '{"query":"订单接口 旧客户端 字段兼容","limit":5}'</span></span>
</code></pre>
<p>这是调用方式示例，需要已有的服务、会话初始化状态和网络连通条件；如果 Agent 在容器或远程沙箱中运行，地址需要替换为它实际可访问的 Proxy 地址。</p>
<p>Memory Bridge 会根据会话恢复身份，并补充访问 Core 所需的信息。模型可以提交查询条件，服务端负责处理身份和访问范围。</p>
<p>跨 Agent 检索时，命中结果还可以携带 <code>source_agent_id</code>、<code>source_agent_name</code> 等来源信息，帮助使用方区分当前角色的记忆与借入的经验。</p>
<p>这也解释了接入条件：客户端需要具备可用的工具执行能力，并能访问相应服务。仅有模型聊天接口，并不能自动补齐这条工具调用链。</p>
<h3>5.2 为什么保留稳定的记忆目录</h3>
<p>这套读取策略同时考虑了输入量与缓存。</p>
<p>如果每轮都把新的检索片段塞入提示词前部，请求前缀就会频繁变化，可能降低上游提示词缓存的复用。把较稳定的背景、场景目录和工具说明放进会话快照，再按需获取细节，可以减少这种变化。</p>
<p>源码中仍保留了 L1 自动召回注入器，但当前通用注入注册逻辑已不再启用它。实际采用的是 L3 与 L2 目录注入、L0/L1 工具查询的组合。阅读项目时，需要结合生效的注册逻辑判断行为。</p>
<h3>5.3 搜索时，关键词和语义怎样配合</h3>
<p>精确名称与自然语言描述适合不同的检索方式。</p>
<p>关键词检索有利于命中接口名、错误码和字段名；向量检索有利于连接语义相近的描述。例如，“旧版本不能升级”和“需要兼容历史客户端”可能表达相近的约束，却不共享很多字面词。</p>
<p>参考实现中的 L1 候选召回支持按存储能力选择检索路径。在同时得到全文检索和向量检索结果的客户端合并路径上，会使用 RRF 融合排名：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">RRF 分数(d) = 各检索列表中 1 / (k + 排名(d)) 的总和
</code></pre>
<p>RRF 根据结果在各列表里的位置累积分数，避免直接比较不同检索器的原始分数。实际是否同时走两路，还取决于存储后端、Embedding 配置和可用能力。召回融合与排序的通用思路，见<a href="https://felix.muke.chat/notes/rag-retrieval-precision">《如何提高 RAG 的检索精度》</a>。</p>
<h2>6. 工作完成后，经验怎样写回去</h2>
<p>读取解决了这次任务能使用什么，回流决定了下次任务能继承什么。</p>
<p>一次工作完成后的逻辑过程，可以理解为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">用户请求 + Agent 回答与执行过程
              ↓
轮次记录与对话回流
              ↓
保存 L0，对可复用内容触发后台处理
              ↓
提炼事实与约束，更新场景和长期背景
              ↓
对可复用的操作方法，按条件提取 Skill
              ↓
后续会话读取这些记忆资产
</code></pre>
<p>这里有两类不同的产物。</p>
<p>一类是“知道了什么”，例如接口存在兼容性约束，适合成为 Chat Memory；另一类是“怎么完成一项工作”，例如一次排障中验证过的检查顺序、操作步骤和验收方法，适合整理成 Skill。</p>
<p>记忆提炼通常涉及额外的模型调用。参考部署因此区分了面向用户任务的上游模型配置，以及用于内部记忆处理的模型配置。这两组调用可以按部署需要配置。</p>
<p>还需要把写入与提炼分开观察：L0 已保存，并不表示 L1、L2、L3 已同时更新；对话回流成功，也不表示已经生成了可复用 Skill。后台处理有自己的触发条件与完成时间。</p>
<h2>7. 团队共享的资产，为什么有四种形态</h2>
<p>协作中的经验不都适合保存成对话摘要。</p>
<table>
<thead>
<tr>
<th>资产</th>
<th>保存的重点</th>
<th>典型使用方式</th>
</tr>
</thead>
<tbody>
<tr>
<td>Chat Memory</td>
<td>事实、偏好、约束、决策与交互经验</td>
<td>恢复历史背景，核对已有约定</td>
</tr>
<tr>
<td>Skill</td>
<td>可复用方法、步骤、资源与验证规则</td>
<td>执行一次熟悉的排障或交付流程</td>
</tr>
<tr>
<td>Wiki</td>
<td>文档整理出的页面与链接关系</td>
<td>搜索相关主题，再读取关联页面</td>
</tr>
<tr>
<td>CodeGraph</td>
<td>文件、符号、调用关系与影响路径</td>
<td>定位代码，查询调用方和修改影响</td>
</tr>
</tbody>
</table>
<p>这些内容可以统一登记为 Memory Asset，使用共同的归属、版本、状态、可见性和绑定信息管理。正文的保存与查询方式，则由各类资产的能力决定。</p>
<p>Wiki 和 CodeGraph 采用按需调用的方式：上下文先提供资源清单与访问说明，Agent 通过 <code>/v3/tools/list</code> 发现资源可用的查询能力，再通过 <code>/v3/tools/call</code> 调用具体工具。</p>
<p>例如，评估一个函数的修改影响时，可以先搜索符号，再查看调用方，最后查询影响路径。这个过程需要的是针对性读取，而非提前加载整个仓库。</p>
<p>这也说明了共享记忆与 RAG 的关系：检索仍是读取信息的重要手段，共享记忆进一步关心信息如何产生、如何更新、归谁管理，以及如何交给后续任务使用。实际系统可以把这些能力组合起来。</p>
<h2>8. 谁能使用，与给谁装配，是两件事</h2>
<p>一条资产进入 Agent 的工作范围，通常需要同时考虑访问权限和固定绑定。</p>
<p><strong>访问权限决定能否使用。</strong> 在参考实现的资产权限模型中，<code>private</code> 只允许 Owner 访问；<code>team</code> 面向团队共享；<code>restricted</code> 用于按 ACL 定向授权，具体行为还与团队角色、操作类型有关。</p>
<p><strong>固定绑定决定角色配置。</strong> 通过 Fixed Binding，可以给不同 Agent 配置各自需要的资产。例如：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">后端开发 Agent
  ├─ 订单系统 Wiki
  ├─ 订单代码 CodeGraph
  └─ 接口交付 Skill

代码评审 Agent
  ├─ 订单代码 CodeGraph
  ├─ 已共享的兼容性 Chat Memory
  └─ 回归检查 Skill
</code></pre>
<p>两者共同决定最终装配结果。拥有访问权限，不等于资产已经装进当前 Agent；配置了绑定，也需要满足对应的可见性和绑定规则。</p>
<p>不同资产、不同可见性的绑定能力还可能存在实现限制。例如，当前分支的 Chat Memory 上下文解析助手会读取自身记忆，并最多借入两个已绑定的其他 Agent 记忆来源。这个数量是当前实现的边界，需要在设计大规模共享方案时单独核对。</p>
<p>资产权限模型也有部署边界。当前分支的 Proxy 接口文档明确记录了部分运维接口尚未鉴权，部署时需要保护这类入口。资产层的权限判定，不能替代服务入口的访问控制。</p>
<h2>9. 一个完整例子：从需求讨论，到开发，再到评审</h2>
<p>假设一个团队正在改造订单系统，需要由不同 Agent 完成需求整理、实现和评审。下面是解释这套机制的示例流程。</p>
<p><strong>第一步，需求讨论产生约束。</strong> 用户告诉需求 Agent：旧版客户端仍在调用原接口，本次改造必须保持字段兼容。对话被记录，后台从中提炼出具体约束，并将相关信息组织进订单改造场景。</p>
<p><strong>第二步，把需要复用的经验交给后续角色。</strong> 负责人按团队规则分享相应 Chat Memory，并为开发和评审 Agent 配置需要的资产绑定。共享服务为这些动作提供统一入口。</p>
<p><strong>第三步，开发 Agent 获取适量背景。</strong> 新会话初始化后，Proxy 根据开发角色的配置装配上下文。模型先看到稳定背景和场景目录；处理接口时，再读取兼容性场景或查询具体约束。</p>
<p><strong>第四步，使用知识工具定位代码。</strong> 开发 Agent 根据绑定的 CodeGraph 搜索接口入口、查看调用关系，再结合当前工作区代码完成修改与验证。图谱提供定位线索，当前代码与测试结果用于确认本次改动。</p>
<p><strong>第五步，工作结果继续沉淀。</strong> 新确认的兼容性决策可以进入 Chat Memory；验证过的回归检查步骤，可以按条件整理为 Skill，再由团队决定如何共享和装配。</p>
<p><strong>第六步，评审 Agent 继承相关经验。</strong> 在资产权限、绑定、生效状态和会话缓存都满足条件后，评审 Agent 可以读取兼容性约束与回归方法，把它们用于检查这次实现。</p>
<p>完整的信息流是：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">任务产生信息 → 提炼为记忆资产 → 分享与绑定
                                   ↓
后续角色按需读取 → 执行与验证 → 新经验回流
</code></pre>
<p>任务分配、评审触发和发布决策仍需要各自的工作流。Memory 层负责保存与交付经验，为这些工作流提供可以继承的背景。</p>
<h2>10. 使用时，最需要理解的几个边界</h2>
<h3>10.1 新写入的内容，何时能被看到</h3>
<p>至少有两个时间点需要区分：后台记忆处理完成，以及使用方读取到新内容。</p>
<p>L0 到高层记忆的提炼是异步过程；Wiki 与 CodeGraph 构建也需要时间。与此同时，Proxy 会在会话初始化时准备并缓存部分注入内容，包括长期画像、场景目录和工具说明。</p>
<p>因此，资产更新后，现有会话可能仍在使用旧快照。参考实现提供了会话缓存刷新能力，用来重新拉取上下文并预热缓存。排查“另一个 Agent 为什么还不知道”时，应依次检查写入、处理状态、权限绑定和会话缓存。</p>
<h3>10.2 检索到的历史结论，如何用于当前任务</h3>
<p>记忆描述的是过去已经知道的信息。代码、配置和业务约束仍会变化。</p>
<p>当任务依赖历史决策时，可以先用记忆恢复背景，再对照当前材料确认它是否仍然适用。需要追溯时回到 L0；已失效的约定，应由相应的管理和更新流程处理。</p>
<p>版本、来源和状态为这些判断提供了基础，但不能据此假定系统已经自动解决所有事实冲突。</p>
<h3>10.3 哪些内容值得进入共享范围</h3>
<p>判断标准可以很具体：它是否会影响下一位 Agent 的行动，是否已经得到确认，以及是否适合被目标角色使用。</p>
<p>稳定的接口约束、重复有效的操作方法、重要决策的原因，通常比一次临时猜测更值得复用。个人隐私信息与团队工作经验，也需要通过可见性和装配关系控制范围。</p>
<p>对于单一客户端、少量稳定约定，维护一个清晰的本地记忆文件就可能足够。当工作开始跨客户端、跨会话、跨角色流转，并需要统一管理归属和使用范围时，独立 Memory 服务的价值会更明显。这是基于上述机制得到的工程取舍。</p>
<p>共享记忆最终服务于一个具体目标：让后续 Agent 能够找到已经确认的背景、理解决策的来由，并把验证过的方法用于下一次工作。它能否减少重复劳动，取决于写入、提炼、分享、装配和读取这条链路是否真正接通。</p>
<hr>
<p>本文依据 TencentDB Agent Memory 的 <code>feat/server_team</code> 分支整理改写，核对快照为 <code>2002196f2d7c22ea267cfcaf67c5a6fa861df681</code>。订单系统、角色分工及场景目录为解释性示例；机制说明以该快照的文档和相关代码为依据，未进行完整部署或运行性能验证。</p>
<p>参考资料：</p>
<ul>
<li><a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/README_CN.md">中文 README：共享 Memory Server 与整体设计</a></li>
<li><a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/INSTALL_CN.md">安装说明：客户端接入、身份与会话初始化</a></li>
<li><a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/MemoryProxy/README_CN.md">Memory Proxy：请求链路与组件分工</a></li>
<li><a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/MemoryProxy/src/injection/index.ts">注入注册逻辑：L0/L1 查询与 L2/L3 装配</a></li>
<li><a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/MemoryProxy/src/injection/injectors/tdai-profile-memory-injector.ts">长期画像与场景目录注入实现</a></li>
<li><a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/MemoryProxy/src/injection/injectors/tdai-tools-injector.ts">记忆工具说明与 Memory Bridge 调用方式</a></li>
<li><a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/MemoryCore/src/core/tools/l1-candidate-recall.ts">L1 候选召回：检索路径与 RRF 融合</a></li>
<li><a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/MemoryCore/src/metadata/service/permission-checker.ts">资产权限与绑定规则</a></li>
<li><a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/MemoryProxy/src/injection/injectors/tdai-fixed-asset.ts">跨 Agent Chat Memory 上下文解析</a></li>
<li><a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/MemoryCore/v3-api-memorycore-doc.md">Memory Core API：分层记忆、资产与会话</a></li>
<li><a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/MemoryKnowledge/v3-api-memoryknowledge-doc.md">Knowledge API：工具发现与查询</a></li>
<li><a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/MemoryProxy/v3-api-memoryproxy-doc.md">Proxy API：缓存刷新与运维接口边界</a></li>
</ul>
<p>原项目版权归 Tencent 所有，采用 <a href="https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/2002196f2d7c22ea267cfcaf67c5a6fa861df681/LICENSE">MIT 许可证</a>。</p>
]]></content:encoded>
    </item>
    <item>
      <title>Qdrant 从入门到进阶：原理与 Python 实战</title>
      <link>https://felix.muke.chat/notes/qdrant-from-beginner-to-advanced</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/qdrant-from-beginner-to-advanced</guid>
      <pubDate>Thu, 05 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>从向量、Collection、Point 和 Payload 出发，用 Python 完成增删改查、条件过滤与中文语义检索，再理解混合召回、HNSW、量化、多租户、模型迁移和备份运维。</description>
      <category>数据库</category>
      <category>Qdrant</category>
      <category>Python</category>
      <category>向量数据库</category>
      <category>RAG</category>
      <content:encoded><![CDATA[<p>向量数据库的第一段代码通常很短：创建集合，插入向量，再查找最相似的几条记录。真正接入知识库时，问题才逐渐出现：文本怎样变成向量？为什么向量维度一样却查不准？怎么限定用户权限？数据变多以后，索引、内存和查询延迟应该怎样调整？</p>
<p>这篇笔记从这些问题出发，先用一个不依赖模型的例子掌握 Qdrant 的基本操作，再用 Python 做一个中文文档检索器，最后进入混合检索、性能调优、数据更新与运维。</p>
<p>默认你能看懂 Python 的函数、字典、列表与基本的 <code>async / await</code>。前三个完整脚本分别独立运行，后面的“操作片段”会注明使用哪个脚本中的变量。</p>
<p><strong>版本约定：本文以 Qdrant Server 1.19.0、<code>qdrant-client==1.19.0</code>、Python 3.11 为可复现基线；真实文本向量示例使用 <code>fastembed==0.9.1</code>。</strong> 这些是验证版本，不表示它们永远是最新版本。本文统一使用 <code>query_points</code> 查询接口。</p>
<h2>一、Qdrant 在解决什么问题？</h2>
<h3>1.1 从“包含某个词”到“含义相近”</h3>
<p>假设知识库有一段文字：</p>
<blockquote>
<p>容器内连接独立部署的 Redis 时，不能把 localhost 当作 Redis 服务地址。</p>
</blockquote>
<p>用户提问：</p>
<blockquote>
<p>Docker 里的缓存连不上，应该检查哪里？</p>
</blockquote>
<p>两句话的字面表达不完全相同，但描述的是相近的问题。嵌入模型可以把它们编码成向量，让系统按向量之间的距离或相似度寻找候选内容。</p>
<p>Qdrant 是向量搜索引擎和数据库，核心能力是存储向量及其元数据，结合过滤条件执行相似度检索，并提供索引、持久化、复制等数据库能力。<a href="https://qdrant.tech/documentation/">官方：Qdrant 概览</a></p>
<p>把一次 RAG 的分工画出来，会更容易理解：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">入库：
原始文档 → 解析与切分 → 嵌入模型 → 向量 + 元数据 → Qdrant

查询：
用户问题 → 同一套嵌入流程 → 查询向量
                              ↓
                   Qdrant 按权限过滤并召回
                              ↓
                 可选：融合、重排、恢复上下文
                              ↓
                  片段与来源 → 大模型生成回答
</code></pre>
<h3>1.2 向量数据库、嵌入模型和大模型各做什么？</h3>
<table>
<thead>
<tr>
<th>组件</th>
<th>负责什么</th>
<th>不能直接替代什么</th>
</tr>
</thead>
<tbody>
<tr>
<td>嵌入模型</td>
<td>把文本、图片等编码成向量</td>
<td>数据库的索引、过滤和持久化</td>
</tr>
<tr>
<td>Qdrant</td>
<td>保存 Point，按向量和条件检索</td>
<td>文档解析、业务权限判断、回答生成</td>
</tr>
<tr>
<td>重排模型</td>
<td>比较问题和候选内容，调整相关性顺序</td>
<td>未召回内容的补查</td>
</tr>
<tr>
<td>生成模型</td>
<td>根据问题和证据组织回答</td>
<td>可靠的数据存储和权限控制</td>
</tr>
<tr>
<td>业务数据库</td>
<td>保存用户、订单、文档版本等业务事实</td>
<td>大规模相似度检索的专门索引</td>
</tr>
</tbody>
</table>
<p>本文采用“Python 生成向量，Qdrant 保存和检索”的显式流程。Qdrant 也有推理集成，可以接收带模型信息的输入；是否启用、模型运行在哪里，要看客户端、部署方式和配置，不能默认普通 <code>upsert</code> 会自动理解一段文本。</p>
<h3>1.3 什么情况下适合用？</h3>
<p>常见场景包括知识库检索、相似商品、图片搜索、重复内容识别和推荐候选召回。</p>
<p>如果需求只是按主键取订单、做多表关联与事务，关系数据库通常更直接。若现有 PostgreSQL 加向量扩展已经满足数据规模与运维要求，也没有必要仅为“使用向量数据库”再增加一个服务。应比较实际召回、过滤、延迟、容量和维护成本。</p>
<h2>二、先认识数据模型</h2>
<h3>2.1 Collection、Point、Vector、Payload</h3>
<table>
<thead>
<tr>
<th>概念</th>
<th>可以怎样理解</th>
<th>例子</th>
</tr>
</thead>
<tbody>
<tr>
<td>Collection</td>
<td>一组 Point 的存储与检索配置</td>
<td><code>knowledge_v1</code></td>
</tr>
<tr>
<td>Point</td>
<td>一条可被检索的记录</td>
<td>一段文档片段</td>
</tr>
<tr>
<td>ID</td>
<td>Collection 内标识一个 Point</td>
<td>整数 <code>42</code> 或 UUID</td>
</tr>
<tr>
<td>Vector</td>
<td>用来计算相似度的数值表示</td>
<td>384 维文本向量</td>
</tr>
<tr>
<td>Payload</td>
<td>JSON 元数据与业务内容</td>
<td>标题、正文、租户、来源、版本</td>
</tr>
<tr>
<td>Payload Index</td>
<td>为过滤字段建立的索引</td>
<td><code>tenant_id</code> 的 keyword 索引</td>
</tr>
</tbody>
</table>
<p>一条记录可以表示为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "id"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">42</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "vector"</span><span style="color:#E6EDF3">: [</span><span style="color:#79C0FF">0.9</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.1</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#7EE787">  "payload"</span><span style="color:#E6EDF3">: {</span></span>
<span class="line"><span style="color:#7EE787">    "tenant_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"team-a"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">    "doc_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"redis-network"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">    "chunk_index"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">    "title"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"Redis 连接排查"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">    "text"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"先检查地址、端口和容器网络。"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">    "published"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">true</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>这里的四维向量只是演示数据，真实文本向量由模型计算，不能凭感觉手填。</p>
<p>Point ID 支持 <strong>64 位无符号整数或 UUID</strong>。任意业务字符串，例如 <code>&quot;article-redis-001&quot;</code>，不能直接当作 UUID 使用；可以放进 Payload，或经过确定性的 UUID 映射。<a href="https://qdrant.tech/documentation/manage-data/points/">官方：Point 与 ID</a></p>
<h3>2.2 同一集合里的向量需要遵守什么约定？</h3>
<p>同一个向量字段的维度与距离度量由 Collection 配置决定。配置 <code>size=384</code>，写入 768 维向量就会失败。</p>
<p>还要遵守一个 API 无法替你检查的约定：<strong>文档和查询必须属于兼容的向量空间。</strong></p>
<p>即使两个模型都输出 384 维，也不代表它们的向量能混在一起比较。模型版本、查询与文档前缀、文本预处理、截断和归一化方式都可能影响结果。</p>
<p>建议记录一份嵌入流程配置：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">model_name + model_revision + dimension + distance
+ query/document 编码约定 + chunker_version
</code></pre>
<p>维度检查解决“能不能写进去”，这份配置解决“比较有没有意义”。</p>
<h3>2.3 Cosine、Dot、Euclid 怎样选？</h3>
<table>
<thead>
<tr>
<th>度量</th>
<th>关注什么</th>
<th>结果分数的常见方向</th>
</tr>
</thead>
<tbody>
<tr>
<td>Cosine</td>
<td>向量方向的相近程度</td>
<td>越高越相似</td>
</tr>
<tr>
<td>Dot</td>
<td>点积，同时受方向和向量长度影响</td>
<td>越高越相似</td>
</tr>
<tr>
<td>Euclid</td>
<td>欧氏距离</td>
<td>越低越接近</td>
</tr>
<tr>
<td>Manhattan</td>
<td>各维度绝对差之和</td>
<td>越低越接近</td>
</tr>
</tbody>
</table>
<p>优先遵循嵌入模型的训练与使用说明。文本检索中经常使用 Cosine，但不能据此推断所有模型都应使用同一种度量。Qdrant 对 Cosine 向量会在写入时归一化，再用点积实现相似度计算，因此读回来的向量可能与原始输入数值不同。<a href="https://qdrant.tech/documentation/concepts/collections/">官方：Collection 与距离度量</a></p>
<p>相似度分数不是“回答正确的概率”。<code>0.8</code> 不等于 80% 正确；阈值必须结合模型、语料和问题集评估，换成距离度量后还要注意阈值方向。</p>
<h3>2.4 Dense、Sparse、Named Vector、Multivector 有什么不同？</h3>
<ul>
<li><strong>Dense Vector，稠密向量</strong>：通常是固定长度的数组，用于表达语义、图像等特征。</li>
<li><strong>Sparse Vector，稀疏向量</strong>：只记录非零位置的 <code>indices</code> 和 <code>values</code>，可用于词项权重或学习式稀疏表示。</li>
<li><strong>Named Vectors，命名向量</strong>：同一个 Point 有多个向量字段，例如 <code>dense</code>、<code>sparse</code>、<code>image</code>；查询时用 <code>using</code> 选择。</li>
<li><strong>Multivector，多向量表示</strong>：一个向量字段保存多行向量，例如每个 token 一个向量，用于 ColBERT 一类的后期交互。</li>
</ul>
<p>多个 Named Vectors 可以有不同维度和度量；Multivector 则是一个字段中的矩阵。两者不要混为一谈，后面分别给出用法。<a href="https://qdrant.tech/documentation/concepts/vectors/">官方：向量类型</a></p>
<h2>三、准备 Python 和 Qdrant</h2>
<h3>3.1 创建独立环境</h3>
<p>下面以 macOS / Linux shell 为例。Python 客户端基线版本要求 Python 3.10 及以上，本文使用 3.11。</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sh"><span class="line"><span style="color:#FFA657">mkdir</span><span style="color:#A5D6FF"> qdrant-notes</span></span>
<span class="line"><span style="color:#79C0FF">cd</span><span style="color:#A5D6FF"> qdrant-notes</span></span>
<span class="line"><span style="color:#FFA657">python</span><span style="color:#79C0FF"> -m</span><span style="color:#A5D6FF"> venv</span><span style="color:#A5D6FF"> .venv</span></span>
<span class="line"><span style="color:#79C0FF">source</span><span style="color:#A5D6FF"> .venv/bin/activate</span></span>
<span class="line"><span style="color:#FFA657">python</span><span style="color:#79C0FF"> -m</span><span style="color:#A5D6FF"> pip</span><span style="color:#A5D6FF"> install</span><span style="color:#A5D6FF"> "qdrant-client==1.19.0"</span></span>
</code></pre>
<p>Windows 可以在 PowerShell 中使用 <code>.\.venv\Scripts\Activate.ps1</code> 激活环境，后续 Python 代码相同。</p>
<h3>3.2 不启动服务器，也能学习 API</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#FF7B72">from</span><span style="color:#E6EDF3"> qdrant_client </span><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> QdrantClient</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">client </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> QdrantClient(</span><span style="color:#A5D6FF">":memory:"</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#8B949E"># 或保存到本地目录：</span></span>
<span class="line"><span style="color:#8B949E"># client = QdrantClient(path="./local_qdrant")</span></span>
</code></pre>
<p>本地模式适合学习、小数据实验和功能测试。<code>:memory:</code> 关闭后数据消失；<code>path=</code> 可以持久保存，但同一路径不应被多个客户端进程同时打开。</p>
<p>本地模式不是缩小版生产集群。它不能用来证明服务端 HNSW、Payload 索引、并发、分片和快照的行为与性能。索引调优与运维章节应使用真实服务端验证。</p>
<h3>3.3 用 Docker 运行服务端</h3>
<p>创建一个专门用于练习的命名卷和容器：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sh"><span class="line"><span style="color:#FFA657">docker</span><span style="color:#A5D6FF"> volume</span><span style="color:#A5D6FF"> create</span><span style="color:#A5D6FF"> qdrant-notes-data</span></span>
<span class="line"><span style="color:#FFA657">docker</span><span style="color:#A5D6FF"> run</span><span style="color:#79C0FF"> -d</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#79C0FF">  --name</span><span style="color:#A5D6FF"> qdrant-notes</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#79C0FF">  -p</span><span style="color:#A5D6FF"> 127.0.0.1:6333:6333</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#79C0FF">  -p</span><span style="color:#A5D6FF"> 127.0.0.1:6334:6334</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#79C0FF">  -v</span><span style="color:#A5D6FF"> qdrant-notes-data:/qdrant/storage</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#A5D6FF">  qdrant/qdrant:v1.19.0</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FFA657">curl</span><span style="color:#A5D6FF"> http://127.0.0.1:6333/</span></span>
</code></pre>
<table>
<thead>
<tr>
<th>地址或端口</th>
<th>用途</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>http://127.0.0.1:6333</code></td>
<td>REST API</td>
</tr>
<tr>
<td><code>http://127.0.0.1:6333/dashboard</code></td>
<td>Web 管理界面</td>
</tr>
<tr>
<td><code>127.0.0.1:6334</code></td>
<td>gRPC API</td>
</tr>
<tr>
<td>6335</td>
<td>分布式内部通信端口，练习不需要映射</td>
</tr>
</tbody>
</table>
<p>练习端口只绑定本机。容器删除后，命名卷仍然保留数据；需要再次启动已有容器时，用 <code>docker start qdrant-notes</code>，不要重复创建同名容器。<a href="https://qdrant.tech/documentation/quickstart/">官方：本地快速开始</a></p>
<p>后面的脚本默认使用内存模式，设置环境变量即可切换到服务端：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sh"><span class="line"><span style="color:#FF7B72">export</span><span style="color:#E6EDF3"> QDRANT_URL</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"http://127.0.0.1:6333"</span></span>
</code></pre>
<p>要恢复内存模式，执行 <code>unset QDRANT_URL</code>。</p>
<h3>3.4 连接 Cloud 或其他远程实例</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> os</span></span>
<span class="line"><span style="color:#FF7B72">from</span><span style="color:#E6EDF3"> qdrant_client </span><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> QdrantClient</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">client </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> QdrantClient(</span></span>
<span class="line"><span style="color:#FFA657">    url</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">os.environ[</span><span style="color:#A5D6FF">"QDRANT_URL"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">    api_key</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">os.environ[</span><span style="color:#A5D6FF">"QDRANT_API_KEY"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">    timeout</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">15</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p>Cloud 的 URL 以控制台提供的地址为准，API Key 从环境变量或密钥管理系统读取。不要把 Key 写进脚本或发给浏览器。</p>
<p>需要 gRPC 时可以配置 <code>prefer_grpc=True</code>，同时保证 gRPC 端口、TLS 和网络可达。协议选择应经过实际吞吐与延迟测试，不必为了入门先增加这层差异。</p>
<h2>四、第一份完整脚本：创建、写入和搜索</h2>
<h3>4.1 先用可解释的四维向量</h3>
<p>将下面内容保存为 <code>basic_demo.py</code>。它会创建一个专用集合，写入四条 Point，再限定租户查询。</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> os</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">from</span><span style="color:#E6EDF3"> qdrant_client </span><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> QdrantClient, models</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">COLLECTION</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> "notes_basics_v1"</span></span>
<span class="line"></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">def</span><span style="color:#D2A8FF"> connect</span><span style="color:#E6EDF3">() -> QdrantClient:</span></span>
<span class="line"><span style="color:#E6EDF3">    url </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> os.getenv(</span><span style="color:#A5D6FF">"QDRANT_URL"</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> url:</span></span>
<span class="line"><span style="color:#FF7B72">        return</span><span style="color:#E6EDF3"> QdrantClient(</span></span>
<span class="line"><span style="color:#FFA657">            url</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">url,</span></span>
<span class="line"><span style="color:#FFA657">            api_key</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">os.getenv(</span><span style="color:#A5D6FF">"QDRANT_API_KEY"</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#FFA657">            timeout</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">15</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#E6EDF3"> QdrantClient(</span><span style="color:#A5D6FF">":memory:"</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">def</span><span style="color:#D2A8FF"> run</span><span style="color:#E6EDF3">(client: QdrantClient) -> </span><span style="color:#79C0FF">None</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#FF7B72"> not</span><span style="color:#E6EDF3"> client.collection_exists(</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">):</span></span>
<span class="line"><span style="color:#E6EDF3">        client.create_collection(</span></span>
<span class="line"><span style="color:#FFA657">            collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            vectors_config</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.VectorParams(</span></span>
<span class="line"><span style="color:#FFA657">                size</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">4</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                distance</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.Distance.</span><span style="color:#79C0FF">COSINE</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">            ),</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">    client.upsert(</span></span>
<span class="line"><span style="color:#FFA657">        collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        wait</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        points</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span></span>
<span class="line"><span style="color:#E6EDF3">            models.PointStruct(</span></span>
<span class="line"><span style="color:#FFA657">                id</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                vector</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#79C0FF">1.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">                payload</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#A5D6FF">                    "tenant_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"team-a"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "title"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"Redis 连接排查"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "category"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"database"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "published"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "year"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">2026</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "tags"</span><span style="color:#E6EDF3">: [</span><span style="color:#A5D6FF">"Redis"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"Docker"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#E6EDF3">                },</span></span>
<span class="line"><span style="color:#E6EDF3">            ),</span></span>
<span class="line"><span style="color:#E6EDF3">            models.PointStruct(</span></span>
<span class="line"><span style="color:#FFA657">                id</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                vector</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#79C0FF">0.9</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.1</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">                payload</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#A5D6FF">                    "tenant_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"team-a"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "title"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"Redis 持久化"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "category"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"database"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "published"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "year"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">2025</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "tags"</span><span style="color:#E6EDF3">: [</span><span style="color:#A5D6FF">"Redis"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"Backup"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#E6EDF3">                },</span></span>
<span class="line"><span style="color:#E6EDF3">            ),</span></span>
<span class="line"><span style="color:#E6EDF3">            models.PointStruct(</span></span>
<span class="line"><span style="color:#FFA657">                id</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">3</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                vector</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">1.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">                payload</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#A5D6FF">                    "tenant_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"team-a"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "title"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"React 状态管理"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "category"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"frontend"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "published"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">False</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "year"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">2026</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "tags"</span><span style="color:#E6EDF3">: [</span><span style="color:#A5D6FF">"React"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#E6EDF3">                },</span></span>
<span class="line"><span style="color:#E6EDF3">            ),</span></span>
<span class="line"><span style="color:#E6EDF3">            models.PointStruct(</span></span>
<span class="line"><span style="color:#FFA657">                id</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">4</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                vector</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#79C0FF">1.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">                payload</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#A5D6FF">                    "tenant_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"team-b"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "title"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"另一团队的 Redis 笔记"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "category"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"database"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "published"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "year"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">2026</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                    "tags"</span><span style="color:#E6EDF3">: [</span><span style="color:#A5D6FF">"Redis"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#E6EDF3">                },</span></span>
<span class="line"><span style="color:#E6EDF3">            ),</span></span>
<span class="line"><span style="color:#E6EDF3">        ],</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">    tenant_filter </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> models.Filter(</span></span>
<span class="line"><span style="color:#FFA657">        must</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span></span>
<span class="line"><span style="color:#E6EDF3">            models.FieldCondition(</span></span>
<span class="line"><span style="color:#FFA657">                key</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"tenant_id"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                match</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.MatchValue(</span><span style="color:#FFA657">value</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"team-a"</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">            )</span></span>
<span class="line"><span style="color:#E6EDF3">        ]</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"><span style="color:#E6EDF3">    response </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> client.query_points(</span></span>
<span class="line"><span style="color:#FFA657">        collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        query</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#79C0FF">1.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">        query_filter</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">tenant_filter,</span></span>
<span class="line"><span style="color:#FFA657">        limit</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        with_payload</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#A5D6FF">"title"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"tenant_id"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">        with_vectors</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">False</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"><span style="color:#FF7B72">    for</span><span style="color:#E6EDF3"> point </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> response.points:</span></span>
<span class="line"><span style="color:#79C0FF">        print</span><span style="color:#E6EDF3">(point.id, </span><span style="color:#FF7B72">f</span><span style="color:#A5D6FF">"</span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">point.score</span><span style="color:#FF7B72">:.4f}</span><span style="color:#A5D6FF">"</span><span style="color:#E6EDF3">, point.payload[</span><span style="color:#A5D6FF">"title"</span><span style="color:#E6EDF3">])</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">    print</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">"集合 Point 总数："</span><span style="color:#E6EDF3">, client.count(</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">exact</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">).count)</span></span>
<span class="line"></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">if</span><span style="color:#79C0FF"> __name__</span><span style="color:#FF7B72"> ==</span><span style="color:#A5D6FF"> "__main__"</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">    client </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> connect()</span></span>
<span class="line"><span style="color:#FF7B72">    try</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">        run(client)</span></span>
<span class="line"><span style="color:#FF7B72">    finally</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">        client.close()</span></span>
</code></pre>
<p>运行：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sh"><span class="line"><span style="color:#FFA657">python</span><span style="color:#A5D6FF"> basic_demo.py</span></span>
</code></pre>
<p>在这个专用集合只含示例数据的前提下，输出为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">1 1.0000 Redis 连接排查
2 0.9939 Redis 持久化
集合 Point 总数： 4
</code></pre>
<p>第 4 条与查询方向完全相同，但属于另一个租户，因此被过滤掉。第 2 条的余弦相似度约为 <code>0.9 / sqrt(0.9² + 0.1²)</code>。</p>
<h3>4.2 这段代码里最值得记住的几个细节</h3>
<p><strong>创建集合只在不存在时进行。</strong> 不要在应用启动时执行删除再创建，否则重启就会丢数据。集合已存在也不表示配置正确，正式应用应校验向量字段、维度、度量和版本；配置不符时应停止写入或迁移。</p>
<p><strong>固定 ID 让重复写入可覆盖。</strong> 同一个 ID 再次 <code>upsert</code> 会更新这个 Point，适合可重试的入库流程。若每次重试都生成新 UUID，数据库无法知道它们是同一条业务数据。</p>
<p><strong><code>wait=True</code> 等待写入应用完成。</strong> 不等待时，操作可能只处于已接收状态，紧接着查询未必立即可见。等待写入完成不等于所有索引已经优化完毕，也不是跨数据库事务或分布式强一致性的通用开关。<a href="https://qdrant.tech/documentation/manage-data/points/">官方：写入与等待</a></p>
<p><strong><code>query_points</code> 返回响应对象。</strong> 真正的结果列表在 <code>response.points</code>。每项通常有 <code>id</code>、<code>score</code>、<code>payload</code>，是否包含向量由 <code>with_vectors</code> 控制。</p>
<h2>五、Python 增删改查：不要把所有更新都写成 upsert</h2>
<p>以下为操作片段，放在 <code>basic_demo.py</code> 的 <code>run(client)</code> 函数末尾即可执行，使用已有的 <code>client</code>、<code>COLLECTION</code> 和 <code>tenant_filter</code>。</p>
<h3>5.1 按 ID 读取</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">records </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> client.retrieve(</span></span>
<span class="line"><span style="color:#FFA657">    collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    ids</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">    with_payload</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    with_vectors</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">False</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">for</span><span style="color:#E6EDF3"> record </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> records:</span></span>
<span class="line"><span style="color:#79C0FF">    print</span><span style="color:#E6EDF3">(record.id, record.payload)</span></span>
</code></pre>
<p><code>retrieve</code> 是按 ID 读取，不进行相似度排序，返回的 Record 不带查询相似度分数。</p>
<p>多租户应用要先校验请求者能否访问这些 ID；<code>retrieve(ids=...)</code> 本身没有自动补租户过滤。可以通过受控的业务 ID 映射，或使用带 <code>HasIdCondition</code> 与租户条件的 <code>scroll</code> 完成受限读取。</p>
<h3>5.2 只修改 Payload 字段</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">client.set_payload(</span></span>
<span class="line"><span style="color:#FFA657">    collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    points</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">    payload</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">{</span><span style="color:#A5D6FF">"reviewed"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">},</span></span>
<span class="line"><span style="color:#FFA657">    wait</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">client.delete_payload(</span></span>
<span class="line"><span style="color:#FFA657">    collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    points</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">    keys</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#A5D6FF">"reviewed"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">    wait</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p><code>set_payload</code> 会写入指定键，保留其他顶层键；同名键的值会被替换，不应当作任意嵌套 JSON 的深度合并。</p>
<p><code>overwrite_payload</code> 则替换整个 Payload。若只传 <code>{&quot;reviewed&quot;: True}</code>，原来的 <code>tenant_id</code>、标题等字段就不再保留，应格外注意。</p>
<h3>5.3 只更新向量</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">client.update_vectors(</span></span>
<span class="line"><span style="color:#FFA657">    collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    points</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span></span>
<span class="line"><span style="color:#E6EDF3">        models.PointVectors(</span></span>
<span class="line"><span style="color:#FFA657">            id</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            vector</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#79C0FF">0.8</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.2</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"><span style="color:#E6EDF3">    ],</span></span>
<span class="line"><span style="color:#FFA657">    wait</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p>这会保留已有 Payload。Named Vectors 场景可以传 <code>vector={&quot;dense&quot;: new_vector}</code>，更新指定字段。</p>
<p>完整 <code>upsert</code> 应按整条 Point 覆盖来设计，不要把省略字段当成局部补丁。尤其有多个向量字段时，局部更新优先用专门的更新接口。</p>
<h3>5.4 删除指定 Point</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">client.delete(</span></span>
<span class="line"><span style="color:#FFA657">    collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    points_selector</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.PointIdsList(</span><span style="color:#FFA657">points</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#79C0FF">3</span><span style="color:#E6EDF3">]),</span></span>
<span class="line"><span style="color:#FFA657">    wait</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p>也可以传 <code>models.FilterSelector(filter=...)</code> 按条件删除，例如清理某租户某文档的旧片段。正式执行前先用完全相同的过滤条件 <code>count</code> 或 <code>scroll</code> 检查范围，避免只按公共 <code>doc_id</code> 误删其他租户的数据。</p>
<p>删除 Point、删除某个向量字段和删除整个 Collection 是不同层级的操作。本文删除示例仅用于练习集合。</p>
<h3>5.5 遍历集合与统计数量</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">offset </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> None</span></span>
<span class="line"><span style="color:#FF7B72">while</span><span style="color:#79C0FF"> True</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">    records, next_offset </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> client.scroll(</span></span>
<span class="line"><span style="color:#FFA657">        collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        scroll_filter</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">tenant_filter,</span></span>
<span class="line"><span style="color:#FFA657">        offset</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">offset,</span></span>
<span class="line"><span style="color:#FFA657">        limit</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        with_payload</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        with_vectors</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">False</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"><span style="color:#FF7B72">    for</span><span style="color:#E6EDF3"> record </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> records:</span></span>
<span class="line"><span style="color:#79C0FF">        print</span><span style="color:#E6EDF3">(record.id, record.payload[</span><span style="color:#A5D6FF">"title"</span><span style="color:#E6EDF3">])</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> next_offset </span><span style="color:#FF7B72">is</span><span style="color:#79C0FF"> None</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#FF7B72">        break</span></span>
<span class="line"><span style="color:#E6EDF3">    offset </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> next_offset</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">count </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> client.count(</span></span>
<span class="line"><span style="color:#FFA657">    collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    count_filter</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">tenant_filter,</span></span>
<span class="line"><span style="color:#FFA657">    exact</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#79C0FF">print</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">"当前租户 Point 数："</span><span style="color:#E6EDF3">, count.count)</span></span>
</code></pre>
<p><code>scroll</code> 默认按 Point ID 遍历，不是相似度搜索。下一页要原样使用返回的 <code>next_offset</code>，不要自己加 1，也不要把它与 <code>query_points</code> 的结果偏移量混用。</p>
<p>持续写入期间的遍历不应被当作业务一致性快照。需要可恢复导出时，还要确定写入窗口、版本或快照策略。</p>
<h2>六、过滤与 Payload 索引</h2>
<h3>6.1 搜索应该先限定范围</h3>
<p>过滤不是“先取全库前 10，再删掉不符合条件的结果”。正确做法是把条件交给 Qdrant，在满足条件的记录中检索。否则前 10 都来自别的租户时，删除后就可能一个结果都不剩。</p>
<p>以下代码同样使用 <code>basic_demo.py</code> 的数据，可以在 CRUD 示例前执行：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">query_filter </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> models.Filter(</span></span>
<span class="line"><span style="color:#FFA657">    must</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span></span>
<span class="line"><span style="color:#E6EDF3">        models.FieldCondition(</span></span>
<span class="line"><span style="color:#FFA657">            key</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"tenant_id"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            match</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.MatchValue(</span><span style="color:#FFA657">value</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"team-a"</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">        ),</span></span>
<span class="line"><span style="color:#E6EDF3">        models.FieldCondition(</span></span>
<span class="line"><span style="color:#FFA657">            key</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"published"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            match</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.MatchValue(</span><span style="color:#FFA657">value</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">        ),</span></span>
<span class="line"><span style="color:#E6EDF3">        models.FieldCondition(</span></span>
<span class="line"><span style="color:#FFA657">            key</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"year"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            range</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.Range(</span><span style="color:#FFA657">gte</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">2026</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">        ),</span></span>
<span class="line"><span style="color:#E6EDF3">        models.FieldCondition(</span></span>
<span class="line"><span style="color:#FFA657">            key</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"tags"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            match</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.MatchAny(</span><span style="color:#FFA657">any</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#A5D6FF">"Redis"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"Qdrant"</span><span style="color:#E6EDF3">]),</span></span>
<span class="line"><span style="color:#E6EDF3">        ),</span></span>
<span class="line"><span style="color:#E6EDF3">    ],</span></span>
<span class="line"><span style="color:#FFA657">    must_not</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span></span>
<span class="line"><span style="color:#E6EDF3">        models.FieldCondition(</span></span>
<span class="line"><span style="color:#FFA657">            key</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"category"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            match</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.MatchValue(</span><span style="color:#FFA657">value</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"frontend"</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"><span style="color:#E6EDF3">    ],</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">response </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> client.query_points(</span></span>
<span class="line"><span style="color:#FFA657">    collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    query</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#79C0FF">1.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">    query_filter</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">query_filter,</span></span>
<span class="line"><span style="color:#FFA657">    limit</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">5</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    with_payload</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#79C0FF">print</span><span style="color:#E6EDF3">([point.id </span><span style="color:#FF7B72">for</span><span style="color:#E6EDF3"> point </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> response.points])  </span><span style="color:#8B949E"># [1]</span></span>
</code></pre>
<p>常见条件可以这样记：</p>
<table>
<thead>
<tr>
<th>条件</th>
<th>意义</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>must</code></td>
<td>所有条件都成立，相当于 AND</td>
</tr>
<tr>
<td><code>should</code></td>
<td>至少一个条件成立，相当于 OR；不是给匹配项加分</td>
</tr>
<tr>
<td><code>must_not</code></td>
<td>列出的条件都不能成立</td>
</tr>
<tr>
<td><code>MatchValue</code></td>
<td>字段等于指定值</td>
</tr>
<tr>
<td><code>MatchAny</code></td>
<td>字段匹配候选值中的任意一个</td>
</tr>
<tr>
<td><code>Range</code></td>
<td>数字范围，例如年份、价格</td>
</tr>
<tr>
<td><code>DatetimeRange</code></td>
<td>时间范围，应统一为符合约定的时间格式与时区</td>
</tr>
<tr>
<td><code>NestedCondition</code></td>
<td>限定嵌套对象数组中的同一个元素</td>
</tr>
</tbody>
</table>
<p>数组字段匹配通常按“其中某个元素满足条件”处理。例如 <code>tags=[&quot;Redis&quot;, &quot;Docker&quot;]</code> 可以匹配 <code>Redis</code>。</p>
<p>但对 <code>[{&quot;name&quot;:&quot;A&quot;,&quot;price&quot;:10},{&quot;name&quot;:&quot;B&quot;,&quot;price&quot;:30}]</code> 分别过滤 <code>name=A</code> 与 <code>price&gt;20</code> 时，普通条件可能命中不同元素；要求同一元素同时满足时，需要 Nested 过滤。<a href="https://qdrant.tech/documentation/concepts/filtering/">官方：过滤条件</a></p>
<h3>6.2 常用过滤字段需要建索引</h3>
<p>以下在连接真实服务端后执行，本地模式不能验证索引性能：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#FF7B72">for</span><span style="color:#E6EDF3"> field, schema </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> [</span></span>
<span class="line"><span style="color:#E6EDF3">    (</span><span style="color:#A5D6FF">"tenant_id"</span><span style="color:#E6EDF3">, models.PayloadSchemaType.</span><span style="color:#79C0FF">KEYWORD</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">    (</span><span style="color:#A5D6FF">"published"</span><span style="color:#E6EDF3">, models.PayloadSchemaType.</span><span style="color:#79C0FF">BOOL</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">    (</span><span style="color:#A5D6FF">"year"</span><span style="color:#E6EDF3">, models.PayloadSchemaType.</span><span style="color:#79C0FF">INTEGER</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">    (</span><span style="color:#A5D6FF">"tags"</span><span style="color:#E6EDF3">, models.PayloadSchemaType.</span><span style="color:#79C0FF">KEYWORD</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">]:</span></span>
<span class="line"><span style="color:#E6EDF3">    client.create_payload_index(</span></span>
<span class="line"><span style="color:#FFA657">        collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        field_name</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">field,</span></span>
<span class="line"><span style="color:#FFA657">        field_schema</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">schema,</span></span>
<span class="line"><span style="color:#FFA657">        wait</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
</code></pre>
<p>Payload 索引既能加速过滤，也能帮助查询规划器估计有多少 Point 满足条件，从而选择合适的搜索方式。类型要匹配实际数据：<code>&quot;2026&quot;</code> 与 <code>2026</code> 不是同一种字段类型。</p>
<p>索引需要内存、磁盘和维护开销，应优先覆盖高频过滤字段。建议在大量数据导入前创建已确定的过滤索引；数据较大后补索引，应预留构建资源并观察查询影响。<a href="https://qdrant.tech/documentation/concepts/indexing/">官方：索引</a></p>
<h3>6.3 租户字段不是自动生效的权限系统</h3>
<p>把 <code>tenant_id</code> 写进 Payload 只是存储信息。要实现隔离，还需要：</p>
<ol>
<li>服务端从认证会话获得可信租户 ID，不能直接相信浏览器提交的值。</li>
<li>服务端强制把租户条件加入每次检索，包括混合检索的候选分支。</li>
<li>按 ID 读取、更新、删除、统计和导出同样检查租户范围。</li>
<li>Qdrant 的数据库凭据只交给受信任的后端。</li>
</ol>
<p>过滤条件应由确定性代码构造，不能让大模型自行决定是否带上权限条件。对隔离和资源配额要求更高时，再评估独立 Collection、分片或独立实例。</p>
<h2>七、第二份完整脚本：中文文档语义检索</h2>
<h3>7.1 先把文本转换为真实向量</h3>
<p>安装 FastEmbed：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sh"><span class="line"><span style="color:#FFA657">python</span><span style="color:#79C0FF"> -m</span><span style="color:#A5D6FF"> pip</span><span style="color:#A5D6FF"> install</span><span style="color:#A5D6FF"> "fastembed==0.9.1"</span></span>
</code></pre>
<p>本文选择 <code>sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2</code>，在该版本 FastEmbed 中输出 384 维向量，首次运行会从模型仓库下载文件并在本地缓存。它用于演示中文检索闭环，不代表它在你的业务语料上效果最好。</p>
<p>该模型不要求查询/文档前缀，FastEmbed 模型描述列出的输入上限为 128 tokens，超过部分会截断。这里使用已经切好的短片段；实际长文档要结合 tokenizer 切分并检查最终输入长度。换用 E5、BGE 等模型时，按其模型说明处理查询/文档编码约定，不能照搬前缀。<a href="https://github.com/qdrant/fastembed">官方：FastEmbed 支持的模型</a>、<a href="https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2">模型说明</a></p>
<h3>7.2 完整的 <code>semantic_search.py</code></h3>
<p>这份脚本包含稳定 ID、Payload、服务端索引、入库、权限过滤和检索结果输出；不调用生成模型。</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> os</span></span>
<span class="line"><span style="color:#FF7B72">from</span><span style="color:#E6EDF3"> uuid </span><span style="color:#FF7B72">import</span><span style="color:#79C0FF"> NAMESPACE_URL</span><span style="color:#E6EDF3">, uuid5</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">from</span><span style="color:#E6EDF3"> fastembed </span><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> TextEmbedding</span></span>
<span class="line"><span style="color:#FF7B72">from</span><span style="color:#E6EDF3"> qdrant_client </span><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> QdrantClient, models</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">COLLECTION</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> "notes_semantic_v1"</span></span>
<span class="line"><span style="color:#79C0FF">MODEL</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"</span></span>
<span class="line"><span style="color:#79C0FF">DIMENSION</span><span style="color:#FF7B72"> =</span><span style="color:#79C0FF"> 384</span></span>
<span class="line"></span>
<span class="line"><span style="color:#8B949E"># 每项就是一个已切分片段；真实系统从解析和切分流程获取这些数据。</span></span>
<span class="line"><span style="color:#79C0FF">CHUNKS</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> [</span></span>
<span class="line"><span style="color:#E6EDF3">    {</span></span>
<span class="line"><span style="color:#A5D6FF">        "doc_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"redis-network"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "chunk_index"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "title"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"Redis 容器网络"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "text"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"Docker 容器中连接独立部署的 Redis 时，localhost 指向当前容器。"</span></span>
<span class="line"><span style="color:#A5D6FF">                "应检查 Redis 服务地址、端口和容器网络是否互通。"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "source"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"https://example.com/notes/redis-network"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    },</span></span>
<span class="line"><span style="color:#E6EDF3">    {</span></span>
<span class="line"><span style="color:#A5D6FF">        "doc_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"redis-backup"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "chunk_index"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "title"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"Redis 持久化"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "text"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"RDB 保存某一时刻的数据快照，AOF 记录写入操作。"</span></span>
<span class="line"><span style="color:#A5D6FF">                "选择持久化方式时，需要权衡恢复时间和可接受的数据丢失窗口。"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "source"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"https://example.com/notes/redis-backup"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    },</span></span>
<span class="line"><span style="color:#E6EDF3">    {</span></span>
<span class="line"><span style="color:#A5D6FF">        "doc_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"qdrant-filter"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "chunk_index"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "title"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"Qdrant 元数据过滤"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "text"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"Qdrant 可以结合向量查询与 Payload 条件过滤。"</span></span>
<span class="line"><span style="color:#A5D6FF">                "多租户知识库应由后端强制加入 tenant_id 条件。"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "source"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"https://example.com/notes/qdrant-filter"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    },</span></span>
<span class="line"><span style="color:#E6EDF3">]</span></span>
<span class="line"></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">def</span><span style="color:#D2A8FF"> open_client</span><span style="color:#E6EDF3">() -> QdrantClient:</span></span>
<span class="line"><span style="color:#E6EDF3">    url </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> os.getenv(</span><span style="color:#A5D6FF">"QDRANT_URL"</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> url:</span></span>
<span class="line"><span style="color:#FF7B72">        return</span><span style="color:#E6EDF3"> QdrantClient(</span></span>
<span class="line"><span style="color:#FFA657">            url</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">url,</span></span>
<span class="line"><span style="color:#FFA657">            api_key</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">os.getenv(</span><span style="color:#A5D6FF">"QDRANT_API_KEY"</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#FFA657">            timeout</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">30</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#E6EDF3"> QdrantClient(</span><span style="color:#A5D6FF">":memory:"</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">def</span><span style="color:#D2A8FF"> run</span><span style="color:#E6EDF3">(client: QdrantClient) -> </span><span style="color:#79C0FF">None</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">    encoder </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> TextEmbedding(</span></span>
<span class="line"><span style="color:#FFA657">        model_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">MODEL</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        cache_dir</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"./model_cache"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        threads</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#FF7B72"> not</span><span style="color:#E6EDF3"> client.collection_exists(</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">):</span></span>
<span class="line"><span style="color:#E6EDF3">        client.create_collection(</span></span>
<span class="line"><span style="color:#FFA657">            collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            vectors_config</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.VectorParams(</span></span>
<span class="line"><span style="color:#FFA657">                size</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">DIMENSION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                distance</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.Distance.</span><span style="color:#79C0FF">COSINE</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">            ),</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> os.getenv(</span><span style="color:#A5D6FF">"QDRANT_URL"</span><span style="color:#E6EDF3">):</span></span>
<span class="line"><span style="color:#FF7B72">        for</span><span style="color:#E6EDF3"> field </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> [</span><span style="color:#A5D6FF">"tenant_id"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"doc_id"</span><span style="color:#E6EDF3">]:</span></span>
<span class="line"><span style="color:#E6EDF3">            client.create_payload_index(</span></span>
<span class="line"><span style="color:#FFA657">                collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                field_name</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">field,</span></span>
<span class="line"><span style="color:#FFA657">                field_schema</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.PayloadSchemaType.</span><span style="color:#79C0FF">KEYWORD</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                wait</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">            )</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">    texts </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> [</span></span>
<span class="line"><span style="color:#FF7B72">        f</span><span style="color:#A5D6FF">"</span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">chunk[</span><span style="color:#A5D6FF">'title'</span><span style="color:#E6EDF3">]</span><span style="color:#FF7B72">}\n{</span><span style="color:#E6EDF3">chunk[</span><span style="color:#A5D6FF">'text'</span><span style="color:#E6EDF3">]</span><span style="color:#FF7B72">}</span><span style="color:#A5D6FF">"</span></span>
<span class="line"><span style="color:#FF7B72">        for</span><span style="color:#E6EDF3"> chunk </span><span style="color:#FF7B72">in</span><span style="color:#79C0FF"> CHUNKS</span></span>
<span class="line"><span style="color:#E6EDF3">    ]</span></span>
<span class="line"><span style="color:#E6EDF3">    vectors </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> list</span><span style="color:#E6EDF3">(encoder.embed(texts))</span></span>
<span class="line"><span style="color:#FF7B72">    assert</span><span style="color:#79C0FF"> len</span><span style="color:#E6EDF3">(vectors) </span><span style="color:#FF7B72">==</span><span style="color:#79C0FF"> len</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">CHUNKS</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">    assert</span><span style="color:#79C0FF"> all</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">len</span><span style="color:#E6EDF3">(vector) </span><span style="color:#FF7B72">==</span><span style="color:#79C0FF"> DIMENSION</span><span style="color:#FF7B72"> for</span><span style="color:#E6EDF3"> vector </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> vectors)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#8B949E">    # 示例的租户来自固定的受信任上下文。</span></span>
<span class="line"><span style="color:#8B949E">    # 真实接口应从认证会话获得它，而非直接接受请求参数。</span></span>
<span class="line"><span style="color:#E6EDF3">    tenant_id </span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF"> "team-a"</span></span>
<span class="line"><span style="color:#E6EDF3">    points </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> []</span></span>
<span class="line"><span style="color:#FF7B72">    for</span><span style="color:#E6EDF3"> chunk, vector </span><span style="color:#FF7B72">in</span><span style="color:#79C0FF"> zip</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">CHUNKS</span><span style="color:#E6EDF3">, vectors):</span></span>
<span class="line"><span style="color:#E6EDF3">        point_id </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> str</span><span style="color:#E6EDF3">(uuid5(</span></span>
<span class="line"><span style="color:#79C0FF">            NAMESPACE_URL</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FF7B72">            f</span><span style="color:#A5D6FF">"</span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">tenant_id</span><span style="color:#FF7B72">}</span><span style="color:#A5D6FF">/</span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">chunk[</span><span style="color:#A5D6FF">'doc_id'</span><span style="color:#E6EDF3">]</span><span style="color:#FF7B72">}</span><span style="color:#A5D6FF">/</span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">chunk[</span><span style="color:#A5D6FF">'chunk_index'</span><span style="color:#E6EDF3">]</span><span style="color:#FF7B72">}</span><span style="color:#A5D6FF">"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">        ))</span></span>
<span class="line"><span style="color:#E6EDF3">        points.append(models.PointStruct(</span></span>
<span class="line"><span style="color:#FFA657">            id</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">point_id,</span></span>
<span class="line"><span style="color:#FFA657">            vector</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">vector.tolist(),</span></span>
<span class="line"><span style="color:#FFA657">            payload</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#FF7B72">                **</span><span style="color:#E6EDF3">chunk,</span></span>
<span class="line"><span style="color:#A5D6FF">                "tenant_id"</span><span style="color:#E6EDF3">: tenant_id,</span></span>
<span class="line"><span style="color:#A5D6FF">                "embedding_model"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">MODEL</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">                "chunker_version"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"manual-short-v1"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">            },</span></span>
<span class="line"><span style="color:#E6EDF3">        ))</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">    client.upsert(</span></span>
<span class="line"><span style="color:#FFA657">        collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        points</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">points,</span></span>
<span class="line"><span style="color:#FFA657">        wait</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">    question </span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF"> "Docker 里面 Redis 连接超时，应该检查什么？"</span></span>
<span class="line"><span style="color:#E6EDF3">    query_vector </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> next</span><span style="color:#E6EDF3">(encoder.embed([question])).tolist()</span></span>
<span class="line"><span style="color:#E6EDF3">    response </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> client.query_points(</span></span>
<span class="line"><span style="color:#FFA657">        collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        query</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">query_vector,</span></span>
<span class="line"><span style="color:#FFA657">        query_filter</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.Filter(</span><span style="color:#FFA657">must</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span></span>
<span class="line"><span style="color:#E6EDF3">            models.FieldCondition(</span></span>
<span class="line"><span style="color:#FFA657">                key</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"tenant_id"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                match</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.MatchValue(</span><span style="color:#FFA657">value</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">tenant_id),</span></span>
<span class="line"><span style="color:#E6EDF3">            )</span></span>
<span class="line"><span style="color:#E6EDF3">        ]),</span></span>
<span class="line"><span style="color:#FFA657">        limit</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        with_payload</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span><span style="color:#A5D6FF">"title"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"text"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"source"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"doc_id"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">        with_vectors</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">False</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    for</span><span style="color:#E6EDF3"> point </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> response.points:</span></span>
<span class="line"><span style="color:#E6EDF3">        payload </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> point.payload </span><span style="color:#FF7B72">or</span><span style="color:#E6EDF3"> {}</span></span>
<span class="line"><span style="color:#79C0FF">        print</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">f</span><span style="color:#A5D6FF">"</span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">point.score</span><span style="color:#FF7B72">:.4f}</span><span style="color:#A5D6FF"> | </span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">payload[</span><span style="color:#A5D6FF">'title'</span><span style="color:#E6EDF3">]</span><span style="color:#FF7B72">}</span><span style="color:#A5D6FF">"</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#79C0FF">        print</span><span style="color:#E6EDF3">(payload[</span><span style="color:#A5D6FF">"text"</span><span style="color:#E6EDF3">])</span></span>
<span class="line"><span style="color:#79C0FF">        print</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">"来源："</span><span style="color:#E6EDF3">, payload[</span><span style="color:#A5D6FF">"source"</span><span style="color:#E6EDF3">])</span></span>
<span class="line"></span>
<span class="line"><span style="color:#8B949E">    # 交给生成模型之前，先形成可检查的证据文本。</span></span>
<span class="line"><span style="color:#E6EDF3">    context </span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF"> "</span><span style="color:#FF7B72">\n\n</span><span style="color:#A5D6FF">"</span><span style="color:#E6EDF3">.join(</span></span>
<span class="line"><span style="color:#FF7B72">        f</span><span style="color:#A5D6FF">"[</span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">index</span><span style="color:#FF7B72">}</span><span style="color:#A5D6FF">] </span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">point.payload[</span><span style="color:#A5D6FF">'title'</span><span style="color:#E6EDF3">]</span><span style="color:#FF7B72">}\n</span><span style="color:#A5D6FF">"</span></span>
<span class="line"><span style="color:#FF7B72">        f</span><span style="color:#A5D6FF">"</span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">point.payload[</span><span style="color:#A5D6FF">'text'</span><span style="color:#E6EDF3">]</span><span style="color:#FF7B72">}\n</span><span style="color:#A5D6FF">来源：</span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">point.payload[</span><span style="color:#A5D6FF">'source'</span><span style="color:#E6EDF3">]</span><span style="color:#FF7B72">}</span><span style="color:#A5D6FF">"</span></span>
<span class="line"><span style="color:#FF7B72">        for</span><span style="color:#E6EDF3"> index, point </span><span style="color:#FF7B72">in</span><span style="color:#79C0FF"> enumerate</span><span style="color:#E6EDF3">(response.points, </span><span style="color:#FFA657">start</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"><span style="color:#79C0FF">    print</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">"</span><span style="color:#FF7B72">\n</span><span style="color:#A5D6FF">用于回答的证据：</span><span style="color:#FF7B72">\n</span><span style="color:#A5D6FF">"</span><span style="color:#E6EDF3">, context)</span></span>
<span class="line"></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">if</span><span style="color:#79C0FF"> __name__</span><span style="color:#FF7B72"> ==</span><span style="color:#A5D6FF"> "__main__"</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">    client </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> open_client()</span></span>
<span class="line"><span style="color:#FF7B72">    try</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">        run(client)</span></span>
<span class="line"><span style="color:#FF7B72">    finally</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">        client.close()</span></span>
</code></pre>
<p>运行 <code>python semantic_search.py</code>。检查第一条是否围绕 Redis 容器网络，返回的标题、正文与来源是否一致；不要把示例的一次排序当作正式的检索质量评测。</p>
<p>代码中的 <code>example.com</code> 是示例来源地址，不是真实资料。接入项目时替换为可追溯的文档 URI、站内链接或对象存储引用。</p>
<h3>7.3 切分时应该保存哪些信息？</h3>
<p>推荐至少保留：</p>
<ul>
<li><code>tenant_id</code>：权限与隔离范围。</li>
<li><code>doc_id</code>、<code>chunk_index</code>：片段属于哪篇文档、在什么位置。</li>
<li><code>title</code>、<code>section_path</code>：保留标题和章节上下文。</li>
<li><code>text</code>、<code>source</code>：回答需要的原文与可追溯来源。</li>
<li><code>document_version</code>、<code>chunker_version</code>、<code>embedding_model</code>：解释这条索引如何生成。</li>
</ul>
<p>大文档不一定要把完整原文全部复制进 Payload；可以只存片段与引用，在权限校验后按需取回原文。但检索结果必须能还原对应内容，不能只剩一个不可解释的向量。</p>
<h3>7.4 稳定 ID 能解决什么，不能解决什么？</h3>
<p>上例把“租户 + 文档 + 片段序号”映射为 UUID，使同一输入重复运行时覆盖同一批 Point。</p>
<p>但如果一篇文档原来 10 段，更新后只剩 8 段，重新 upsert 前 8 段不会自动删除后 2 段。切分方式改变时，旧序号也可能对应完全不同的内容。</p>
<p>正式入库流程应明确旧片段清理与可见性策略。例如：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">保存文档新版本 → 切分与嵌入 → 写入新版本全部片段
             → 核对片段数与抽样检索
             → 应用切换到新版本 → 清理旧版本
</code></pre>
<p>这不是一个天然的跨 Point 原子事务。版本激活、并发更新和失败恢复要由应用协调；要求整库一致切换时，可使用后文的 Collection Alias 方案。</p>
<h3>7.5 从“检索器”接到 RAG 还差什么？</h3>
<p>还需要问题补全、重排、去重、上下文预算、无依据时的处理和引用输出。模型也应把检索文档视为资料，不能把文档中的指令当作系统指令执行。</p>
<p>先保存候选结果和最终证据，再判断问题出在解析、召回、排序还是生成。更完整的检索链路可以结合站内笔记<a href="https://felix.muke.chat/notes/rag-retrieval-precision">《如何提高 RAG 的检索精度》</a>阅读。</p>
<h2>八、第三份完整脚本：Dense + Sparse 混合检索</h2>
<h3>8.1 语义相近，不一定保留了关键字</h3>
<p>向量检索适合处理改写与近义表达，但技术文档中的错误码、配置键、版本号和产品型号往往需要精确匹配。例如 <code>REDIS_HOST</code> 与 <code>REDIS_PORT</code> 都与连接有关，却不能相互替代。</p>
<p>混合检索通常让两条路径分别召回：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">问题 ──→ 稠密嵌入 ──→ dense 候选 ──┐
                                  ├→ 融合排序 → 可选重排 → 最终证据
问题 ──→ 稀疏表示 ──→ sparse 候选 ─┘
</code></pre>
<p>BM25 是常见的词项相关性方法，会结合词频、文档长度和词项区分度。稀疏向量是表示形式，BM25 是评分方法；SPLADE 等学习式模型也能生成稀疏表示，因此“稀疏向量”不等于“BM25”。</p>
<h3>8.2 为什么用 RRF 融合？</h3>
<p>Dense 与 BM25 的分数来自不同尺度，直接相加通常没有可靠含义。</p>
<p>RRF 根据一个结果在各路列表中的排名融合，不要求两路分数相同。相同 Point 在多路都靠前时，通常更有优势；只在其中一路找到的内容也有机会进入融合结果。</p>
<p>Qdrant 通过 <code>Prefetch</code> 先召回，再用 <code>FusionQuery</code> 融合。Prefetch 的 <code>limit</code> 是每路候选数量，外层 <code>limit</code> 是最终返回数量，两者分别控制。<a href="https://qdrant.tech/documentation/concepts/hybrid-queries/">官方：混合与多阶段查询</a></p>
<h3>8.3 完整的 <code>hybrid_search.py</code></h3>
<p>本例复用前面安装的依赖与稠密模型。<strong>BM25 部分明确使用英文语料与英文查询</strong>，因为这里的 <code>Qdrant/bm25</code> 示例采用默认英文语言处理；中文分词与中文 BM25 应另选并评估合适方案，不能仅因为 Dense 模型支持中文，就认为整条混合链路已经支持中文。</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> os</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">from</span><span style="color:#E6EDF3"> fastembed </span><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> SparseTextEmbedding, TextEmbedding</span></span>
<span class="line"><span style="color:#FF7B72">from</span><span style="color:#E6EDF3"> qdrant_client </span><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> QdrantClient, models</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">COLLECTION</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> "notes_hybrid_v1"</span></span>
<span class="line"><span style="color:#79C0FF">MODEL</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"</span></span>
<span class="line"><span style="color:#79C0FF">DOCUMENTS</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> [</span></span>
<span class="line"><span style="color:#E6EDF3">    {</span></span>
<span class="line"><span style="color:#A5D6FF">        "id"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "tenant_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"team-a"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "text"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"Redis connection timeout: check REDIS_HOST, port and Docker network."</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    },</span></span>
<span class="line"><span style="color:#E6EDF3">    {</span></span>
<span class="line"><span style="color:#A5D6FF">        "id"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "tenant_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"team-a"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "text"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"Redis persistence uses RDB snapshots and AOF write logs."</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    },</span></span>
<span class="line"><span style="color:#E6EDF3">    {</span></span>
<span class="line"><span style="color:#A5D6FF">        "id"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">3</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "tenant_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"team-a"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "text"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"Qdrant filters vector search results using payload conditions."</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    },</span></span>
<span class="line"><span style="color:#E6EDF3">    {</span></span>
<span class="line"><span style="color:#A5D6FF">        "id"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">4</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "tenant_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"team-b"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">        "text"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"Redis connection timeout: internal notes for another tenant."</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    },</span></span>
<span class="line"><span style="color:#E6EDF3">]</span></span>
<span class="line"></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">def</span><span style="color:#D2A8FF"> run</span><span style="color:#E6EDF3">(client: QdrantClient) -> </span><span style="color:#79C0FF">None</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">    dense_model </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> TextEmbedding(</span></span>
<span class="line"><span style="color:#FFA657">        model_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">MODEL</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        cache_dir</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"./model_cache"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        threads</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"><span style="color:#E6EDF3">    sparse_model </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> SparseTextEmbedding(</span></span>
<span class="line"><span style="color:#FFA657">        model_name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"Qdrant/bm25"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        cache_dir</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"./model_cache"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#FF7B72"> not</span><span style="color:#E6EDF3"> client.collection_exists(</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">):</span></span>
<span class="line"><span style="color:#E6EDF3">        client.create_collection(</span></span>
<span class="line"><span style="color:#FFA657">            collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            vectors_config</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#A5D6FF">                "dense"</span><span style="color:#E6EDF3">: models.VectorParams(</span></span>
<span class="line"><span style="color:#FFA657">                    size</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">384</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                    distance</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.Distance.</span><span style="color:#79C0FF">COSINE</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">                )</span></span>
<span class="line"><span style="color:#E6EDF3">            },</span></span>
<span class="line"><span style="color:#FFA657">            sparse_vectors_config</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#A5D6FF">                "sparse"</span><span style="color:#E6EDF3">: models.SparseVectorParams(</span></span>
<span class="line"><span style="color:#FFA657">                    modifier</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.Modifier.</span><span style="color:#79C0FF">IDF</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">                )</span></span>
<span class="line"><span style="color:#E6EDF3">            },</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> os.getenv(</span><span style="color:#A5D6FF">"QDRANT_URL"</span><span style="color:#E6EDF3">):</span></span>
<span class="line"><span style="color:#E6EDF3">        client.create_payload_index(</span></span>
<span class="line"><span style="color:#FFA657">            collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            field_name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"tenant_id"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            field_schema</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.PayloadSchemaType.</span><span style="color:#79C0FF">KEYWORD</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            wait</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">    texts </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> [document[</span><span style="color:#A5D6FF">"text"</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">for</span><span style="color:#E6EDF3"> document </span><span style="color:#FF7B72">in</span><span style="color:#79C0FF"> DOCUMENTS</span><span style="color:#E6EDF3">]</span></span>
<span class="line"><span style="color:#E6EDF3">    dense_vectors </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> list</span><span style="color:#E6EDF3">(dense_model.embed(texts))</span></span>
<span class="line"><span style="color:#E6EDF3">    sparse_vectors </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> list</span><span style="color:#E6EDF3">(sparse_model.embed(texts))</span></span>
<span class="line"><span style="color:#E6EDF3">    points </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> []</span></span>
<span class="line"><span style="color:#FF7B72">    for</span><span style="color:#E6EDF3"> document, dense, sparse </span><span style="color:#FF7B72">in</span><span style="color:#79C0FF"> zip</span><span style="color:#E6EDF3">(</span></span>
<span class="line"><span style="color:#79C0FF">        DOCUMENTS</span><span style="color:#E6EDF3">, dense_vectors, sparse_vectors,</span></span>
<span class="line"><span style="color:#E6EDF3">    ):</span></span>
<span class="line"><span style="color:#E6EDF3">        points.append(models.PointStruct(</span></span>
<span class="line"><span style="color:#FFA657">            id</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">document[</span><span style="color:#A5D6FF">"id"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">            vector</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#A5D6FF">                "dense"</span><span style="color:#E6EDF3">: dense.tolist(),</span></span>
<span class="line"><span style="color:#A5D6FF">                "sparse"</span><span style="color:#E6EDF3">: models.SparseVector(</span></span>
<span class="line"><span style="color:#FFA657">                    indices</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">sparse.indices.tolist(),</span></span>
<span class="line"><span style="color:#FFA657">                    values</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">sparse.values.tolist(),</span></span>
<span class="line"><span style="color:#E6EDF3">                ),</span></span>
<span class="line"><span style="color:#E6EDF3">            },</span></span>
<span class="line"><span style="color:#FFA657">            payload</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#A5D6FF">                "tenant_id"</span><span style="color:#E6EDF3">: document[</span><span style="color:#A5D6FF">"tenant_id"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#A5D6FF">                "text"</span><span style="color:#E6EDF3">: document[</span><span style="color:#A5D6FF">"text"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#E6EDF3">            },</span></span>
<span class="line"><span style="color:#E6EDF3">        ))</span></span>
<span class="line"><span style="color:#E6EDF3">    client.upsert(</span></span>
<span class="line"><span style="color:#FFA657">        collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        points</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">points,</span></span>
<span class="line"><span style="color:#FFA657">        wait</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">    question </span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF"> "Redis connection timeout REDIS_HOST"</span></span>
<span class="line"><span style="color:#E6EDF3">    dense_query </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> next</span><span style="color:#E6EDF3">(dense_model.embed([question])).tolist()</span></span>
<span class="line"><span style="color:#E6EDF3">    sparse_query </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> next</span><span style="color:#E6EDF3">(sparse_model.query_embed(question))</span></span>
<span class="line"><span style="color:#E6EDF3">    access_filter </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> models.Filter(</span><span style="color:#FFA657">must</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span></span>
<span class="line"><span style="color:#E6EDF3">        models.FieldCondition(</span></span>
<span class="line"><span style="color:#FFA657">            key</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"tenant_id"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            match</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.MatchValue(</span><span style="color:#FFA657">value</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"team-a"</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"><span style="color:#E6EDF3">    ])</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">    response </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> client.query_points(</span></span>
<span class="line"><span style="color:#FFA657">        collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        prefetch</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span></span>
<span class="line"><span style="color:#E6EDF3">            models.Prefetch(</span></span>
<span class="line"><span style="color:#FFA657">                query</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">dense_query,</span></span>
<span class="line"><span style="color:#FFA657">                using</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"dense"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                filter</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">access_filter,</span></span>
<span class="line"><span style="color:#FFA657">                limit</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">20</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">            ),</span></span>
<span class="line"><span style="color:#E6EDF3">            models.Prefetch(</span></span>
<span class="line"><span style="color:#FFA657">                query</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.SparseVector(</span></span>
<span class="line"><span style="color:#FFA657">                    indices</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">sparse_query.indices.tolist(),</span></span>
<span class="line"><span style="color:#FFA657">                    values</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">sparse_query.values.tolist(),</span></span>
<span class="line"><span style="color:#E6EDF3">                ),</span></span>
<span class="line"><span style="color:#FFA657">                using</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"sparse"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                filter</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">access_filter,</span></span>
<span class="line"><span style="color:#FFA657">                limit</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">20</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">            ),</span></span>
<span class="line"><span style="color:#E6EDF3">        ],</span></span>
<span class="line"><span style="color:#FFA657">        query</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.FusionQuery(</span><span style="color:#FFA657">fusion</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.Fusion.</span><span style="color:#79C0FF">RRF</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#FFA657">        query_filter</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">access_filter,</span></span>
<span class="line"><span style="color:#FFA657">        limit</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">3</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        with_payload</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        with_vectors</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">False</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"><span style="color:#FF7B72">    for</span><span style="color:#E6EDF3"> point </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> response.points:</span></span>
<span class="line"><span style="color:#79C0FF">        print</span><span style="color:#E6EDF3">(point.id, </span><span style="color:#FF7B72">f</span><span style="color:#A5D6FF">"</span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">point.score</span><span style="color:#FF7B72">:.4f}</span><span style="color:#A5D6FF">"</span><span style="color:#E6EDF3">, point.payload[</span><span style="color:#A5D6FF">"text"</span><span style="color:#E6EDF3">])</span></span>
<span class="line"></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">if</span><span style="color:#79C0FF"> __name__</span><span style="color:#FF7B72"> ==</span><span style="color:#A5D6FF"> "__main__"</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">    url </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> os.getenv(</span><span style="color:#A5D6FF">"QDRANT_URL"</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    client </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">        QdrantClient(</span></span>
<span class="line"><span style="color:#FFA657">            url</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">url,</span></span>
<span class="line"><span style="color:#FFA657">            api_key</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">os.getenv(</span><span style="color:#A5D6FF">"QDRANT_API_KEY"</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#FFA657">            timeout</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">30</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"><span style="color:#FF7B72">        if</span><span style="color:#E6EDF3"> url </span><span style="color:#FF7B72">else</span><span style="color:#E6EDF3"> QdrantClient(</span><span style="color:#A5D6FF">":memory:"</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"><span style="color:#FF7B72">    try</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">        run(client)</span></span>
<span class="line"><span style="color:#FF7B72">    finally</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">        client.close()</span></span>
</code></pre>
<p>运行 <code>python hybrid_search.py</code>。预期第一条是 Redis 连接排查，返回结果中不应出现 ID 4。</p>
<p>这里有几个容易写错的参数：</p>
<ul>
<li><code>query_points</code> 的过滤参数叫 <code>query_filter</code>，<code>Prefetch</code> 里叫 <code>filter</code>。</li>
<li>命名向量的查询分支必须通过 <code>using</code> 指定 <code>dense</code> 或 <code>sparse</code>。</li>
<li>这个 FastEmbed BM25 路径需要 Qdrant 的 <code>Modifier.IDF</code> 配合词项区分度计算；不要无意中叠加两次 IDF。</li>
<li>RRF 后的 <code>score</code> 是融合分数，不能继续拿 Dense 的相似度阈值过滤。</li>
</ul>
<p>稀疏表示必须保证文档与查询使用同一套词项编号、分词和权重约定。<code>indices</code> 是数值位置，不是词的字符串列表。<a href="https://qdrant.tech/documentation/concepts/vectors/">官方：稀疏向量检索</a></p>
<h3>8.4 文本过滤与 BM25 排序要分清</h3>
<p><code>MatchText</code> 用于判断文本是否满足匹配条件，是布尔过滤。它不会因为写在 <code>must</code> 里，就自动形成一条与 Dense 融合的 BM25 排序链路。</p>
<p>Qdrant 还有随版本演进的全文检索与 BM25 相关能力。采用哪条路径，要看实际版本、索引与推理配置；本文选择显式 Dense + Sparse，是为了让向量生成、字段配置和融合过程都能在 Python 中看清楚。</p>
<h3>8.5 融合以后为什么还可能需要重排？</h3>
<p>融合只说明某个片段在不同召回列表中表现如何，不一定能准确判断它是否回答了问题。</p>
<p>可把融合后的前 20～50 个候选交给 Cross-Encoder 等重排模型，再选较少证据。这个范围是实验起点，不是固定最佳值。重排会增加推理耗时，也无法补回从未进入候选集的内容。</p>
<p>权限条件应在召回时生效，重排输入仍应来自允许访问的候选。召回数、重排数和最终证据数应分别评估。</p>
<h2>九、理解 HNSW，再调整查询性能</h2>
<h3>9.1 精确搜索与近似搜索</h3>
<p>最直接的搜索方式是把查询向量与所有候选逐一比较，再排序。它适合小数据集或过滤后只剩很少记录的情况，但候选规模大时计算成本会上升。</p>
<p>HNSW 使用分层图组织向量，通过图遍历找到接近的候选，通常能减少需要比较的数量。它属于近似最近邻检索，速度和召回之间需要权衡。</p>
<p>Qdrant 会结合段、索引、过滤条件与数据规模选择搜索策略。小集合可能直接扫描，并不是创建 Collection 后每次查询都会走 HNSW。索引也可能在后台逐步构建，不能只用刚写入时的一次延迟判断稳定性能。<a href="https://qdrant.tech/documentation/concepts/indexing/">官方：向量索引与查询规划</a></p>
<h3>9.2 常见参数分别影响什么？</h3>
<table>
<thead>
<tr>
<th>参数或配置</th>
<th>影响阶段</th>
<th>主要取舍</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>m</code></td>
<td>建图</td>
<td>边数量增加，通常增加内存与构建成本，也可能改善召回</td>
</tr>
<tr>
<td><code>ef_construct</code></td>
<td>建图</td>
<td>增加构建时探索，影响索引质量与构建耗时</td>
</tr>
<tr>
<td><code>hnsw_ef</code></td>
<td>查询</td>
<td>增加搜索探索，通常用更多延迟换召回</td>
</tr>
<tr>
<td><code>exact=True</code></td>
<td>查询</td>
<td>对满足条件的向量执行精确搜索，用于基准或小候选集</td>
</tr>
<tr>
<td>Payload 索引</td>
<td>过滤与规划</td>
<td>减少过滤开销，改善候选规模估计</td>
</tr>
<tr>
<td><code>on_disk</code></td>
<td>存储布局</td>
<td>降低常驻内存需求，但更加依赖磁盘与缓存</td>
</tr>
<tr>
<td>Quantization</td>
<td>向量压缩</td>
<td>降低向量存储/计算成本，需要评估精度与重打分开销</td>
</tr>
</tbody>
</table>
<p>先用默认配置建立基线，再根据实际瓶颈改参数。盲目增加 <code>hnsw_ef</code> 解决不了模型不适合、文档缺失或过滤错误。</p>
<h3>9.3 用精确结果评估 ANN 召回</h3>
<p>以下片段放入 <code>semantic_search.py</code> 的 <code>run(client)</code> 末尾，真实服务端与足够大数据集下才有调优价值：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">common </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#A5D6FF">    "collection_name"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">    "query"</span><span style="color:#E6EDF3">: query_vector,</span></span>
<span class="line"><span style="color:#A5D6FF">    "query_filter"</span><span style="color:#E6EDF3">: models.Filter(</span><span style="color:#FFA657">must</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span></span>
<span class="line"><span style="color:#E6EDF3">        models.FieldCondition(</span></span>
<span class="line"><span style="color:#FFA657">            key</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"tenant_id"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            match</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.MatchValue(</span><span style="color:#FFA657">value</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">tenant_id),</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"><span style="color:#E6EDF3">    ]),</span></span>
<span class="line"><span style="color:#A5D6FF">    "limit"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">10</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">    "with_payload"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">False</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">    "with_vectors"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">False</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">exact </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> client.query_points(</span></span>
<span class="line"><span style="color:#FF7B72">    **</span><span style="color:#E6EDF3">common,</span></span>
<span class="line"><span style="color:#FFA657">    search_params</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.SearchParams(</span><span style="color:#FFA657">exact</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">).points</span></span>
<span class="line"><span style="color:#E6EDF3">approximate </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> client.query_points(</span></span>
<span class="line"><span style="color:#FF7B72">    **</span><span style="color:#E6EDF3">common,</span></span>
<span class="line"><span style="color:#FFA657">    search_params</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.SearchParams(</span><span style="color:#FFA657">hnsw_ef</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">128</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">).points</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">expected_ids </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> {point.id </span><span style="color:#FF7B72">for</span><span style="color:#E6EDF3"> point </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> exact}</span></span>
<span class="line"><span style="color:#E6EDF3">actual_ids </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> {point.id </span><span style="color:#FF7B72">for</span><span style="color:#E6EDF3"> point </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> approximate}</span></span>
<span class="line"><span style="color:#E6EDF3">recall </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#79C0FF">    len</span><span style="color:#E6EDF3">(expected_ids </span><span style="color:#FF7B72">&#x26;</span><span style="color:#E6EDF3"> actual_ids) </span><span style="color:#FF7B72">/</span><span style="color:#79C0FF"> len</span><span style="color:#E6EDF3">(expected_ids)</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> expected_ids </span><span style="color:#FF7B72">else</span><span style="color:#79C0FF"> None</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#79C0FF">print</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">"ANN recall@10："</span><span style="color:#E6EDF3">, recall)</span></span>
</code></pre>
<p>这衡量的是“近似结果与同一向量空间精确结果的一致程度”，不是“语义答案是否正确”。如果嵌入模型把无关文档排在最前面，ANN recall 可以很高，业务效果仍然很差。</p>
<p>还要用带人工相关性标注的问题集测 Recall@K、MRR 或 nDCG，并记录 P50/P95 延迟、并发、过滤条件、冷/热缓存和错误率。比较时固定数据、模型、查询与 K。</p>
<h3>9.4 过滤越严格，是不是一定越慢？</h3>
<p>不一定。过滤后只剩很少记录时，数据库可以直接计算这些候选；过滤很宽松时，图索引仍然有效。中间区域的表现更依赖数据分布、过滤索引和图结构。</p>
<p>所以性能测试应覆盖真实租户大小、热点字段与过滤组合，而不是只测试“无过滤的全库查询”。</p>
<h2>十、容量、磁盘与量化</h2>
<h3>10.1 先估算原始向量体积</h3>
<p>Float32 每维通常为 4 字节。100 万个 768 维向量的原始数据约为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">1,000,000 × 768 × 4 = 3,072,000,000 bytes ≈ 2.86 GiB
</code></pre>
<p>这只是原始向量体积，不是整个数据库的内存需求。还要加上图索引、Payload、Payload 索引、ID 映射、WAL、段优化临时空间和副本；多个向量字段也要分别计算。</p>
<p>分片与副本的作用不同：分片把数据拆开，副本保存冗余拷贝。增加副本通常增加存储需求，不能把它当作压缩手段。</p>
<h3>10.2 <code>on_disk=True</code> 不代表完全不用内存</h3>
<p>向量、HNSW 索引和 Payload 的磁盘配置各有边界。把向量放磁盘后，图索引仍可能占内存；操作系统页缓存也会影响实际驻留内存和查询速度。</p>
<p>应一起观察进程内存、主机可用内存、页缓存命中、磁盘随机读延迟以及 P95 查询延迟。使用磁盘模式时，存储设备与 I/O 余量往往直接影响体验。<a href="https://qdrant.tech/documentation/ops-optimization/optimize/">官方：性能与存储优化</a></p>
<h3>10.3 一个磁盘存储与标量量化配置</h3>
<p>下面是面向真实服务端的新集合配置片段，假设已有连接服务端的 <code>client</code>。它展示参数含义，不是所有项目的推荐默认值：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">client.create_collection(</span></span>
<span class="line"><span style="color:#FFA657">    collection_name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"notes_tuned_v1"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    vectors_config</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.VectorParams(</span></span>
<span class="line"><span style="color:#FFA657">        size</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">384</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        distance</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.Distance.</span><span style="color:#79C0FF">COSINE</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        on_disk</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    ),</span></span>
<span class="line"><span style="color:#FFA657">    hnsw_config</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.HnswConfigDiff(</span></span>
<span class="line"><span style="color:#FFA657">        m</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">16</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        ef_construct</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">100</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        on_disk</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    ),</span></span>
<span class="line"><span style="color:#FFA657">    quantization_config</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.ScalarQuantization(</span></span>
<span class="line"><span style="color:#FFA657">        scalar</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.ScalarQuantizationConfig(</span></span>
<span class="line"><span style="color:#FFA657">            type</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.ScalarType.</span><span style="color:#79C0FF">INT8</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            quantile</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">0.99</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            always_ram</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"><span style="color:#E6EDF3">    ),</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p>这里的目标是：原始向量与图索引放磁盘，量化向量保留在内存。INT8 标量量化的单维表示约为 Float32 的四分之一，但 <strong>不代表数据库总内存会缩小为四分之一</strong>。原始向量、索引、Payload 与其他结构仍然存在。</p>
<p>量化会引入近似误差。查询时可以扩大候选，再用原始向量重打分：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">response </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> client.query_points(</span></span>
<span class="line"><span style="color:#FFA657">    collection_name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"notes_tuned_v1"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    query</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">query_vector,  </span><span style="color:#8B949E"># 例如语义检索脚本生成的 384 维向量</span></span>
<span class="line"><span style="color:#FFA657">    limit</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">10</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    search_params</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.SearchParams(</span></span>
<span class="line"><span style="color:#FFA657">        hnsw_ef</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">128</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">        quantization</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.QuantizationSearchParams(</span></span>
<span class="line"><span style="color:#FFA657">            rescore</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            oversampling</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">2.0</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">        ),</span></span>
<span class="line"><span style="color:#E6EDF3">    ),</span></span>
<span class="line"><span style="color:#FFA657">    with_payload</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">False</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p>扩大候选和重打分会增加计算或磁盘读取，效果要与未量化基线比较。二值、乘积等其他量化方式也有不同适用条件，不应只按压缩倍数选择。<a href="https://qdrant.tech/documentation/manage-data/quantization/">官方：量化</a></p>
<h2>十一、批量写入与 Python 异步调用</h2>
<h3>11.1 批量写入通常比逐条请求更合适</h3>
<p>将 <code>semantic_search.py</code> 中的 <code>client.upsert(...)</code> 替换为以下代码，可以使用客户端的批量上传辅助方法：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">client.upload_points(</span></span>
<span class="line"><span style="color:#FFA657">    collection_name</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">COLLECTION</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    points</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">iter</span><span style="color:#E6EDF3">(points),</span></span>
<span class="line"><span style="color:#FFA657">    batch_size</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">64</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    parallel</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    max_retries</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">3</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    wait</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p><code>upload_points</code> 支持分批、重试与迭代输入。示例先生成了小规模 <code>points</code> 列表；大数据入库时应进一步让读取、嵌入和 Point 生成都按批进行，否则仅把大列表包成 <code>iter</code> 并不能解决前面已经占用的内存。</p>
<p>批大小取决于向量维度、Payload 体积和请求限制，不能只按 Point 个数判断。并行度先从 1 开始，根据服务端 CPU、磁盘和写入队列逐步提高。<a href="https://qdrant.tech/documentation/manage-data/points/">官方：Python 批量上传</a></p>
<h3>11.2 入库慢时，先分解耗时</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">解析耗时 + 切分耗时 + 嵌入耗时 + 网络传输 + WAL/写入 + 索引构建
</code></pre>
<p>如果 CPU 时间都花在本地模型上，增加 Qdrant 写入并发不一定有帮助。如果索引构建占满资源，应根据官方批量导入方案规划构建时机与资源。</p>
<p>临时调整索引构建配置属于有恢复步骤的运维操作，应记录原值，导入后恢复并等待优化完成。不要把“导入完成”与“索引已经准备好承接稳定查询”当作同一事件。</p>
<h3>11.3 完整的异步查询示例</h3>
<p>先设置 <code>QDRANT_URL</code> 并运行 <code>basic_demo.py</code>，让练习数据保存在服务端，再把下面内容保存为 <code>async_demo.py</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> asyncio</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> os</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">from</span><span style="color:#E6EDF3"> qdrant_client </span><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> AsyncQdrantClient, models</span></span>
<span class="line"></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">async</span><span style="color:#FF7B72"> def</span><span style="color:#D2A8FF"> main</span><span style="color:#E6EDF3">() -> </span><span style="color:#79C0FF">None</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">    client </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> AsyncQdrantClient(</span></span>
<span class="line"><span style="color:#FFA657">        url</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">os.environ[</span><span style="color:#A5D6FF">"QDRANT_URL"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#FFA657">        api_key</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">os.getenv(</span><span style="color:#A5D6FF">"QDRANT_API_KEY"</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#FFA657">        timeout</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">15</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"><span style="color:#E6EDF3">    semaphore </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> asyncio.Semaphore(</span><span style="color:#79C0FF">4</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    access_filter </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> models.Filter(</span><span style="color:#FFA657">must</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span></span>
<span class="line"><span style="color:#E6EDF3">        models.FieldCondition(</span></span>
<span class="line"><span style="color:#FFA657">            key</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"tenant_id"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            match</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.MatchValue(</span><span style="color:#FFA657">value</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"team-a"</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"><span style="color:#E6EDF3">    ])</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    async</span><span style="color:#FF7B72"> def</span><span style="color:#D2A8FF"> search</span><span style="color:#E6EDF3">(vector: list[</span><span style="color:#79C0FF">float</span><span style="color:#E6EDF3">]) -> list[</span><span style="color:#79C0FF">int</span><span style="color:#FF7B72"> |</span><span style="color:#79C0FF"> str</span><span style="color:#E6EDF3">]:</span></span>
<span class="line"><span style="color:#FF7B72">        async</span><span style="color:#FF7B72"> with</span><span style="color:#E6EDF3"> semaphore:</span></span>
<span class="line"><span style="color:#E6EDF3">            response </span><span style="color:#FF7B72">=</span><span style="color:#FF7B72"> await</span><span style="color:#E6EDF3"> client.query_points(</span></span>
<span class="line"><span style="color:#FFA657">                collection_name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"notes_basics_v1"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                query</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">vector,</span></span>
<span class="line"><span style="color:#FFA657">                query_filter</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">access_filter,</span></span>
<span class="line"><span style="color:#FFA657">                limit</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                with_payload</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">False</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">            )</span></span>
<span class="line"><span style="color:#FF7B72">            return</span><span style="color:#E6EDF3"> [point.id </span><span style="color:#FF7B72">for</span><span style="color:#E6EDF3"> point </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> response.points]</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    try</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">        results </span><span style="color:#FF7B72">=</span><span style="color:#FF7B72"> await</span><span style="color:#E6EDF3"> asyncio.gather(</span></span>
<span class="line"><span style="color:#E6EDF3">            search([</span><span style="color:#79C0FF">1.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">]),</span></span>
<span class="line"><span style="color:#E6EDF3">            search([</span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">1.0</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">0.0</span><span style="color:#E6EDF3">]),</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"><span style="color:#79C0FF">        print</span><span style="color:#E6EDF3">(results)</span></span>
<span class="line"><span style="color:#FF7B72">    finally</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#FF7B72">        await</span><span style="color:#E6EDF3"> client.close()</span></span>
<span class="line"></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">if</span><span style="color:#79C0FF"> __name__</span><span style="color:#FF7B72"> ==</span><span style="color:#A5D6FF"> "__main__"</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#E6EDF3">    asyncio.run(main())</span></span>
</code></pre>
<p>异步主要帮助服务同时等待多个网络请求，不会自动加速本地嵌入模型。不要在事件循环里直接执行长时间阻塞的模型计算；应按模型与运行时选择线程、进程或独立推理服务，并限制并发。</p>
<p>Web 服务通常在生命周期中创建并复用客户端，退出时关闭。不要为每个 HTTP 请求重新建立客户端，也不要对整个数据库无上限地 <code>gather</code>。</p>
<h2>十二、数据组织、模型迁移和多向量进阶</h2>
<h3>12.1 按租户建 Collection，还是共享 Collection？</h3>
<table>
<thead>
<tr>
<th>方案</th>
<th>适合情况</th>
<th>主要代价</th>
</tr>
</thead>
<tbody>
<tr>
<td>共享 Collection + <code>tenant_id</code> 过滤</td>
<td>数据模型相同、租户较多、资源共享</td>
<td>应用必须始终施加权限过滤，需控制租户资源占用</td>
</tr>
<tr>
<td>按业务或租户分 Collection</td>
<td>向量配置、生命周期或隔离要求不同</td>
<td>Collection 及索引的数量和运维开销增加</td>
</tr>
<tr>
<td>独立实例/集群</td>
<td>需要独立资源、密钥、故障域</td>
<td>成本与维护复杂度更高</td>
</tr>
</tbody>
</table>
<p>不要因为有 1 万个用户，就自动创建 1 万个 Collection；也不要在严格隔离场景下只依靠一个容易漏传的过滤参数。根据数据规模、资源配额与隔离要求选型。<a href="https://qdrant.tech/documentation/guides/multitenancy/">官方：多租户</a></p>
<h3>12.2 换模型时怎样平滑切换？</h3>
<p>即使新旧模型输出维度相同，也应先假设向量空间不同，需要重新嵌入。</p>
<p>一种容易回滚的整库迁移方式是：</p>
<ol>
<li>建立新 Collection，使用新的模型配置和版本名。</li>
<li>从业务原始资料重新生成向量，补齐 Payload 索引。</li>
<li>核对数量、权限边界、已标注问题集与延迟。</li>
<li>处理重建期间的增量更新，例如可靠的增量日志或双写。</li>
<li>使用 Alias 把读入口切到新 Collection，同时协调查询编码器版本。</li>
<li>保留旧 Collection 与旧编码器一段时间，确认后再清理。</li>
</ol>
<p>假设 <code>notes_model_v1</code> 与 <code>notes_model_v2</code> 已经存在，第一次建立别名：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">client.update_collection_aliases(</span></span>
<span class="line"><span style="color:#FFA657">    change_aliases_operations</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span></span>
<span class="line"><span style="color:#E6EDF3">        models.CreateAliasOperation(</span></span>
<span class="line"><span style="color:#FFA657">            create_alias</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.CreateAlias(</span></span>
<span class="line"><span style="color:#FFA657">                collection_name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"notes_model_v1"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                alias_name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"notes_active"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">            )</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"><span style="color:#E6EDF3">    ]</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p>验证新版本后，在同一个请求中切换：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">client.update_collection_aliases(</span></span>
<span class="line"><span style="color:#FFA657">    change_aliases_operations</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">[</span></span>
<span class="line"><span style="color:#E6EDF3">        models.DeleteAliasOperation(</span></span>
<span class="line"><span style="color:#FFA657">            delete_alias</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.DeleteAlias(</span><span style="color:#FFA657">alias_name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"notes_active"</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">        ),</span></span>
<span class="line"><span style="color:#E6EDF3">        models.CreateAliasOperation(</span></span>
<span class="line"><span style="color:#FFA657">            create_alias</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.CreateAlias(</span></span>
<span class="line"><span style="color:#FFA657">                collection_name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"notes_model_v2"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">                alias_name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"notes_active"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">            )</span></span>
<span class="line"><span style="color:#E6EDF3">        ),</span></span>
<span class="line"><span style="color:#E6EDF3">    ]</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p>Alias 的修改可以原子完成，但它不会替你协调应用模型、清理增量积压或保证两个外部系统一起切换。新查询向量必须与目标 Collection 匹配；必要时通过应用配置版本或发布流程完成协调。<a href="https://qdrant.tech/documentation/concepts/collections/">官方：Collection Alias</a></p>
<h3>12.3 Named Vectors 怎样帮助业务？</h3>
<p>除了混合检索，还可以在同一 Point 上保存：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">title_dense    标题向量
content_dense  正文向量
image_dense    图片向量
</code></pre>
<p>它们共享 ID 与 Payload，但各自配置维度、度量和索引。查询时明确指定 <code>using</code>，根据业务分别召回后融合。标题与正文的分数也不应在没有评测的前提下随意相加。</p>
<h3>12.4 Multivector 与 ColBERT 的基本用法</h3>
<p>普通单向量把一段文本压缩成一个向量；后期交互模型可能为每个 token 生成一个向量，在查询时细粒度比较。</p>
<p>下面是服务端新集合配置片段：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">client.create_collection(</span></span>
<span class="line"><span style="color:#FFA657">    collection_name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"notes_late_interaction_v1"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    vectors_config</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#A5D6FF">        "colbert"</span><span style="color:#E6EDF3">: models.VectorParams(</span></span>
<span class="line"><span style="color:#FFA657">            size</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">128</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            distance</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.Distance.</span><span style="color:#79C0FF">COSINE</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">            multivector_config</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.MultiVectorConfig(</span></span>
<span class="line"><span style="color:#FFA657">                comparator</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.MultiVectorComparator.</span><span style="color:#79C0FF">MAX_SIM</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">            ),</span></span>
<span class="line"><span style="color:#FFA657">            hnsw_config</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">models.HnswConfigDiff(</span><span style="color:#FFA657">m</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">        )</span></span>
<span class="line"><span style="color:#E6EDF3">    },</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p><code>size=128</code> 是每个子向量的维度，不是每篇文档固定 128 个 token。写入形状为 <code>{&quot;colbert&quot;: [[...128维...], [...128维...]]}</code>，实际矩阵必须由匹配的模型生成。</p>
<p>MaxSim 可以理解为：为每个查询子向量寻找最匹配的文档子向量，再汇总匹配得分。</p>
<p>上例设 <code>m=0</code> 关闭该字段的 HNSW，适合“先用其他向量召回，再用 Multivector 给少量候选重打分”的设计；不适合据此承诺全库查询性能。真正采用时还要补上召回向量字段，并让 Prefetch 限定候选。它通常比单向量存储和计算更贵，应以质量收益证明成本。<a href="https://qdrant.tech/documentation/concepts/vectors/">官方：Multivector</a></p>
<h2>十三、上线需要理解的持久化与运维边界</h2>
<h3>13.1 WAL、持久卷、复制与备份各解决什么？</h3>
<table>
<thead>
<tr>
<th>机制</th>
<th>主要作用</th>
<th>仍需面对的问题</th>
</tr>
</thead>
<tbody>
<tr>
<td>WAL</td>
<td>记录写入，支持故障后的恢复过程</td>
<td>不能替代异机备份和磁盘可靠性</td>
</tr>
<tr>
<td>持久卷</td>
<td>容器重建后保留存储文件</td>
<td>卷被删除、磁盘损坏仍会影响数据</td>
</tr>
<tr>
<td>副本</td>
<td>在多个节点保存数据，提高可用性</td>
<td>误删可能同步传播，不能替代备份</td>
</tr>
<tr>
<td>Snapshot</td>
<td>保存可恢复的数据状态</td>
<td>需要复制到独立位置并演练恢复</td>
</tr>
<tr>
<td>原始文档与入库配置</td>
<td>支持重建索引</td>
<td>重建需要时间，也可能依赖原模型版本</td>
</tr>
</tbody>
</table>
<p>单机容器即使配置了 <code>replication_factor</code>，也不会凭空变出多个故障隔离节点。分片、复制、读一致性、写入顺序与写一致性参数需要结合真实拓扑设计，不能只凭一个参数宣称“强一致高可用”。</p>
<h3>13.2 创建集合快照</h3>
<p>以下在真实服务端执行：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">snapshot </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> client.create_snapshot(</span></span>
<span class="line"><span style="color:#FFA657">    collection_name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"notes_semantic_v1"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    wait</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">if</span><span style="color:#E6EDF3"> snapshot </span><span style="color:#FF7B72">is</span><span style="color:#FF7B72"> not</span><span style="color:#79C0FF"> None</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#79C0FF">    print</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">"快照名称："</span><span style="color:#E6EDF3">, snapshot.name)</span></span>
</code></pre>
<p>这只是在服务端创建快照，不代表已经备份到另一台机器。本地 Python 模式不支持该快照流程。</p>
<p>备份方案还要包含下载或存储转存、校验、保留周期、版本兼容性与恢复演练。分布式集合快照需要按节点和分片安排，不能把任意节点的一个文件当作完整集群备份。<a href="https://qdrant.tech/documentation/tutorials-operations/create-snapshot/">官方：快照与恢复</a></p>
<h3>13.3 连接成功以外，还要观察什么？</h3>
<ul>
<li>服务就绪状态、错误率、超时和请求延迟。</li>
<li>Collection 状态、Point 数量、索引构建和优化情况。</li>
<li>CPU、内存、磁盘容量、I/O 与写入积压。</li>
<li>分布式节点和副本健康状态。</li>
<li>备份最近成功时间，以及实际恢复所需时间。</li>
<li>检索质量，包括空结果率、权限过滤后的结果数和问题集指标。</li>
</ul>
<p>大规模过滤删除后，空间可能随后台段优化逐步回收，不能看到磁盘未立刻减少就重复删除。</p>
<h3>13.4 应用应该怎样处理失败？</h3>
<p>网络超时不能证明写入没有发生。客户端可能没收到响应，但服务端已经应用了操作，因此入库需要稳定 ID、可重试批次和状态核对。</p>
<p>常见处理方式：</p>
<ul>
<li>网络抖动、限流或暂时不可用：有限次重试，退避并加入抖动。</li>
<li>维度不符、参数错误、认证失败：修正配置，不做无意义重试。</li>
<li>批次失败：记录不含凭据的批次标识与错误，允许后续恢复。</li>
<li>请求取消和超时：合理设置端到端预算，不让上游重试造成无限请求堆积。</li>
</ul>
<p>更新同一个 ID 的请求发生竞争时，稳定 ID 也不能保证业务新版本一定最后落下；还要在应用中协调版本和写入顺序。</p>
<h3>13.5 自建实例的访问边界</h3>
<p>自建 Qdrant 的默认配置不能直接当作公网生产配置。需要按部署方式配置 API Key、TLS 和网络访问范围，内部通信端口仅供集群节点访问。<a href="https://qdrant.tech/documentation/security/">官方：安全配置</a></p>
<p>前端通常调用业务后端，由后端完成身份校验、配额与过滤，再访问 Qdrant。这样可以避免把具有数据库权限的密钥与任意查询能力交给浏览器。</p>
<h2>十四、常见问题排查</h2>
<table>
<thead>
<tr>
<th>现象</th>
<th>优先检查</th>
<th>下一步</th>
</tr>
</thead>
<tbody>
<tr>
<td>连接被拒绝或超时</td>
<td>容器状态、端口映射、URL、网络、TLS</td>
<td>先访问服务根地址，再检查客户端协议</td>
</tr>
<tr>
<td>401 / 403</td>
<td>API Key、权限范围与部署认证配置</td>
<td>核对服务端权限，避免打印完整 Key</td>
</tr>
<tr>
<td>向量维度错误</td>
<td>Collection 的 size 与模型输出</td>
<td>打印维度，确认模型和目标集合</td>
</tr>
<tr>
<td>维度一致但效果很差</td>
<td>文档/查询模型、前缀、截断、度量</td>
<td>对照嵌入流程配置，抽查原文与向量生成</td>
</tr>
<tr>
<td>提示找不到向量名</td>
<td>Collection 配置与 <code>using</code></td>
<td>区分匿名向量、<code>dense</code>、<code>sparse</code> 字段</td>
</tr>
<tr>
<td>写入后立刻查不到</td>
<td>是否等待完成、过滤条件、目标集合</td>
<td>使用 <code>wait=True</code>，再按 ID 检查</td>
</tr>
<tr>
<td>Count 正常但查询为空</td>
<td>租户、类型、范围、阈值、稀疏词项</td>
<td>分别统计业务过滤范围，逐步定位条件</td>
</tr>
<tr>
<td>查询只返回少量结果</td>
<td>过滤后数量不足、阈值过高、候选数</td>
<td>检查每路 Prefetch 与最终 limit</td>
</tr>
<tr>
<td>重复片段越来越多</td>
<td>重试是否生成随机 ID，旧版本是否清理</td>
<td>使用稳定 ID，明确文档替换策略</td>
</tr>
<tr>
<td>检索混入别的租户</td>
<td>所有入口与 Prefetch 是否带权限条件</td>
<td>修复后端强制过滤并补越权用例</td>
</tr>
<tr>
<td>查询延迟升高</td>
<td>索引、过滤、Payload 体积、I/O、并发</td>
<td>分阶段测时，先找瓶颈再改参数</td>
</tr>
<tr>
<td>内存超过原始向量估算</td>
<td>HNSW、Payload 索引、副本、页缓存</td>
<td>按组成项估算并观察主机指标</td>
</tr>
<tr>
<td>更新文档后仍有旧内容</td>
<td>旧片段数量与版本切换</td>
<td>核对 ID 清单及旧版本清理范围</td>
</tr>
</tbody>
</table>
<p>诊断检索效果时，不要先关闭权限过滤。可以在受控调试环境中检查各项条件的命中数量；正式接口仍需始终遵守访问边界。</p>
<h2>十五、建议的学习与验证顺序</h2>
<p>先运行基础脚本，确认创建、重复 upsert、过滤和查询结果；再执行 CRUD 片段，观察每种操作到底改变哪一部分数据。</p>
<p>接着运行中文语义检索，手工替换问题与文档，检查模型是否找到了可回答的片段。再运行英文 BM25 混合示例，分别查看 Dense、Sparse 和融合后的结果，理解每路召回的贡献。</p>
<p>准备上线前，用真实规模和真实过滤条件测试服务端，记录质量与延迟基线，再逐项评估索引、磁盘布局、量化和并发。至少验证：</p>
<ol>
<li>同一批数据重试不会制造重复记录，文档缩短后旧片段能正确清理。</li>
<li>查询、读取、更新、删除与导出都不能跨租户。</li>
<li>模型或切分流程改变时，可以定位版本、重建与回滚。</li>
<li>断网和超时有可恢复流程，备份能在隔离环境中恢复。</li>
</ol>
<h2>参考资料</h2>
<p>本文按学习顺序整理与改写，具体 API、支持项和运维限制应结合实际版本核对：</p>
<ul>
<li><a href="https://qdrant.tech/documentation/quickstart/">Qdrant 本地快速开始</a></li>
<li><a href="https://qdrant.tech/documentation/manage-data/points/">Point：写入、更新、删除、遍历与计数</a></li>
<li><a href="https://qdrant.tech/documentation/concepts/collections/">Collection、距离度量与 Alias</a></li>
<li><a href="https://qdrant.tech/documentation/concepts/vectors/">Dense、Sparse 与 Multivector</a></li>
<li><a href="https://qdrant.tech/documentation/concepts/filtering/">过滤条件</a></li>
<li><a href="https://qdrant.tech/documentation/concepts/indexing/">Payload 与向量索引</a></li>
<li><a href="https://qdrant.tech/documentation/concepts/hybrid-queries/">混合和多阶段查询</a></li>
<li><a href="https://qdrant.tech/documentation/manage-data/quantization/">量化</a></li>
<li><a href="https://qdrant.tech/documentation/ops-optimization/optimize/">性能优化</a></li>
<li><a href="https://github.com/qdrant/qdrant-client">官方 Python 客户端与示例</a></li>
<li><a href="https://github.com/qdrant/fastembed">FastEmbed 官方仓库</a></li>
<li><a href="https://qdrant.tech/documentation/tutorials-operations/create-snapshot/">快照和恢复</a></li>
<li><a href="https://qdrant.tech/documentation/security/">安全配置</a></li>
</ul>
]]></content:encoded>
    </item>
    <item>
      <title>React 从入门到实战</title>
      <link>https://felix.muke.chat/notes/react-from-beginner-to-practice</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/react-from-beginner-to-practice</guid>
      <pubDate>Wed, 04 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>从 JSX、组件、Props 和状态出发，理解渲染、Hooks 与副作用，再用 TypeScript 完成支持增删改查和本地保存的任务看板，逐步补齐请求、路由、状态共享、测试与上线检查。</description>
      <category>前端开发</category>
      <category>React</category>
      <category>TypeScript</category>
      <category>前端</category>
      <content:encoded><![CDATA[<p>学 React 时，写出第一个计数器通常不难。真正让人困惑的是：状态应该放在哪里？为什么刚更新就读到旧值？什么时候需要 Effect？页面一多，组件、请求和共享数据又该怎样组织？</p>
<p>这篇文章从这些问题出发，先理解 React 的开发模型，再完成一个可以独立运行的任务看板。你会亲手实现添加、编辑、完成、删除、搜索、筛选和本地保存，之后再扩展网络请求、路由、共享状态与自动化测试。</p>
<p>默认你已经接触过 HTML、CSS 和 JavaScript，能够看懂函数、数组的 <code>map / filter</code>、解构、模块导入和 <code>async / await</code>。TypeScript 用到的类型会随代码解释，不要求你先学完它。</p>
<p>本文围绕 <strong>React 19、函数组件、Hooks 和 TypeScript</strong> 展开。基础项目使用 Vite，运行在浏览器中；后面的接口章节明确给出后端约定，不附带真实服务器。文中的完整文件可以复制，标注为“片段”或“可选扩展”的代码需要放入指定位置，不能把所有示例顺次粘进同一个文件。</p>
<h2>一、先理解 React 在解决什么问题</h2>
<h3>1.1 从操作 DOM 转向描述界面</h3>
<p>假设页面需要显示“还有几项任务未完成”。直接操作 DOM 时，你要在添加、删除、完成任务后，分别找到节点并修改文本。</p>
<p>React 的写法是维护任务数据，再根据数据计算界面：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">用户操作
   ↓
事件处理函数计算下一份状态
   ↓
React 调用组件，得到新的界面描述
   ↓
React 将必要的变化提交到 DOM
</code></pre>
<p>可以用 <code>UI = f(state)</code> 帮助理解，但实际组件还会接收 Props 和 Context。开发重点是把输入、状态与界面之间的关系写清楚。</p>
<p>React 是构建用户界面的库。路由、数据缓存、部署方式等需要项目另行选择。学习时用 Vite 能清楚看到这些边界；需要服务端渲染、复杂数据加载或完整应用约定时，再考虑 React 官方介绍的框架方案。<a href="https://react.dev/learn/build-a-react-app-from-scratch">官方：从零构建 React 应用</a></p>
<h3>1.2 渲染与更新 DOM 是两件事</h3>
<p>“组件重新渲染”通常表示 React 再次调用组件函数，计算下一次要展示什么，并不表示整页 DOM 都被删除重建。</p>
<p>理解这三个阶段很有用：</p>
<ol>
<li><strong>触发</strong>：首次挂载，或状态等输入发生变化。</li>
<li><strong>渲染</strong>：调用组件，计算 JSX 对应的界面。</li>
<li><strong>提交</strong>：把需要的变化应用到 DOM。</li>
</ol>
<p>组件渲染期间应保持纯粹：不发送请求、不修改外部对象、不写本地存储，也不直接改 DOM。React 可能重复调用组件，或放弃某次渲染结果；把这些操作放在渲染中会产生重复和时序问题。<a href="https://react.dev/learn/render-and-commit">官方：渲染与提交</a></p>
<h2>二、创建项目，认识入口</h2>
<h3>2.1 准备环境</h3>
<p>安装受支持的 Node.js 版本，本文建议使用 Node.js 24 LTS。当前 Vite 文档列出的基础要求是 Node.js 20.19+、22.12+，部分模板和测试工具可能要求更高版本，安装时还要检查工具自己的要求。<a href="https://vite.dev/guide/">官方：Vite 起步</a></p>
<p>创建 React + TypeScript 项目：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sh"><span class="line"><span style="color:#FFA657">npm</span><span style="color:#A5D6FF"> create</span><span style="color:#A5D6FF"> vite@latest</span><span style="color:#A5D6FF"> react-task-board</span><span style="color:#79C0FF"> --</span><span style="color:#79C0FF"> --template</span><span style="color:#A5D6FF"> react-ts</span></span>
<span class="line"><span style="color:#79C0FF">cd</span><span style="color:#A5D6FF"> react-task-board</span></span>
<span class="line"><span style="color:#FFA657">npm</span><span style="color:#A5D6FF"> install</span></span>
<span class="line"><span style="color:#FFA657">npm</span><span style="color:#A5D6FF"> run</span><span style="color:#A5D6FF"> dev</span></span>
</code></pre>
<p>如果脚手架询问是否使用实验性方案，先采用稳定默认配置。打开终端实际输出的本地地址；默认端口被占用时，地址可能变化。</p>
<p>本文完整文件在 Node.js 24、React 19.3、TypeScript 7.0 和 Vite 8.3 环境中验证。<code>@latest</code> 和脚手架模板会随时间变化，遇到目录或脚本差异时，以实际生成的文件和对应版本文档为准。</p>
<p>本文使用 npm 演示。使用 pnpm 也可以，但同一项目应统一包管理器，提交对应锁文件，避免同时维护多份锁文件。</p>
<h3>2.2 这些文件各自做什么？</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">react-task-board/
├── index.html             # 包含挂载节点和模块入口
├── package.json           # 依赖与脚本
├── vite.config.ts         # 开发、构建配置
├── tsconfig.app.json      # 应用的 TypeScript 配置
└── src/
    ├── main.tsx           # 创建 React 根节点
    ├── App.tsx            # 根组件
    └── index.css          # 全局样式
</code></pre>
<p><code>.ts</code> 文件主要写 TypeScript 逻辑；包含 JSX 的 TypeScript 文件使用 <code>.tsx</code>。</p>
<p><code>index.html</code> 通常包含 <code>&lt;div id=&quot;root&quot;&gt;&lt;/div&gt;</code>。入口通过 <code>createRoot</code> 把 React 界面挂载到它里面。后面的实战会给出完整 <code>main.tsx</code>；先记住，组件是界面单元，入口负责把根组件接入网页。</p>
<h2>三、JSX、组件与 Props</h2>
<h3>3.1 JSX 是 JavaScript 的语法扩展</h3>
<p>下面是一个可以临时替换 <code>src/App.tsx</code> 的小例子：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> default</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> App</span><span style="color:#FFA657">() </span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> name</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> 'React'</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> lessons</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> [</span><span style="color:#A5D6FF">'组件'</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'状态'</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'事件'</span><span style="color:#E6EDF3">]</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">main</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"page"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">>你好，</span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">name</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">>今天先学习 </span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">lessons.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3"> 个概念。&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">ul</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#FF7B72">        {</span><span style="color:#E6EDF3">lessons.</span><span style="color:#D2A8FF">map</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">lesson</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">li</span><span style="color:#79C0FF"> key</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">lesson</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">lesson</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">li</span><span style="color:#E6EDF3">>)</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">ul</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">main</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>JSX 看起来像 HTML，但要遵守 JavaScript 和 React 的规则：</p>
<ul>
<li>使用 <code>className</code>，而非 HTML 字符串中的 <code>class</code>；标签的 <code>for</code> 对应 <code>htmlFor</code>。</li>
<li>JavaScript 表达式放在 <code>{}</code> 中，不能直接在里面写 <code>if</code> 语句。</li>
<li>标签需要闭合，例如 <code>&lt;input /&gt;</code>；返回多个相邻节点时，使用共同父元素或 Fragment <code>&lt;&gt;...&lt;/&gt;</code>。</li>
<li>原生 HTML 标签小写，自定义组件名称大写。</li>
<li><code>style={{ color: 'red' }}</code> 的内层是 JavaScript 对象，样式属性使用驼峰命名。</li>
</ul>
<p>普通文本表达式会被转义。展示来自接口的字符串时，直接写 <code>{text}</code>；不要为了显示文本而使用 <code>dangerouslySetInnerHTML</code>。</p>
<h3>3.2 Props 把数据从父组件传给子组件</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#FF7B72"> type</span><span style="color:#E6EDF3"> { ReactNode } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">type</span><span style="color:#FFA657"> PanelProps</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FFA657">  title</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span></span>
<span class="line"><span style="color:#FFA657">  children</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> ReactNode</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> Panel</span><span style="color:#E6EDF3">({ </span><span style="color:#FFA657">title</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">children</span><span style="color:#E6EDF3"> }</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> PanelProps</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">section</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">h2</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">title</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">h2</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#FF7B72">      {</span><span style="color:#E6EDF3">children</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">section</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> default</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> App</span><span style="color:#FFA657">() </span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">Panel</span><span style="color:#79C0FF"> title</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"学习计划"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">>先理解数据流，再拆分组件。&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">Panel</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>title</code> 和 <code>children</code> 都是 Props。<code>children</code> 表示组件标签中包裹的内容，可以是文字、元素或其他可渲染节点，因此这里使用 <code>ReactNode</code> 类型。</p>
<p>Props 应视为只读。子组件需要改变父组件的数据时，通过父组件传入的回调通知它，而不是修改 Props 对象。</p>
<h3>3.3 条件渲染和列表</h3>
<p>常见条件写法是提前返回、三元表达式和逻辑与：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> Result</span><span style="color:#E6EDF3">({ </span><span style="color:#FFA657">items</span><span style="color:#E6EDF3"> }</span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> { </span><span style="color:#FFA657">items</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">[] }) {</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (items.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ===</span><span style="color:#79C0FF"> 0</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">return</span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">>暂无内容&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;></span></span>
<span class="line"><span style="color:#FF7B72">      {</span><span style="color:#E6EDF3">items.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#79C0FF"> 0</span><span style="color:#FF7B72"> &#x26;&#x26;</span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">>共 </span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">items.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3"> 项&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">ul</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">items.</span><span style="color:#D2A8FF">map</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">item</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">li</span><span style="color:#79C0FF"> key</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">item</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">item</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">li</span><span style="color:#E6EDF3">>)</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">ul</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>这里假设 <code>items</code> 中的字符串唯一。真实任务列表应该使用稳定的业务 ID。</p>
<p>不要写 <code>items.length &amp;&amp; &lt;List /&gt;</code>：长度为 <code>0</code> 时，表达式得到数字 <code>0</code>，React 会把它显示出来。</p>
<p><code>key</code> 帮助 React 在同一组兄弟节点中识别元素，应该稳定、唯一，不能在每次渲染时临时生成。允许插入、删除或排序的列表不适合用数组下标；否则输入框或组件内部状态可能被关联到错误的项目。<code>key</code> 也不会作为普通 Prop 传给组件，需要 ID 时另外传入。<a href="https://react.dev/learn/rendering-lists">官方：渲染列表</a></p>
<h2>四、事件与状态：让页面真正动起来</h2>
<h3>4.1 事件处理函数要传入，不能在渲染时调用</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useState } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> default</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> Counter</span><span style="color:#FFA657">() </span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">count</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setCount</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  function</span><span style="color:#D2A8FF"> addTwo</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#D2A8FF">    setCount</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">previous</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> previous </span><span style="color:#FF7B72">+</span><span style="color:#79C0FF"> 1</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#D2A8FF">    setCount</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">previous</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> previous </span><span style="color:#FF7B72">+</span><span style="color:#79C0FF"> 1</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"button"</span><span style="color:#79C0FF"> onClick</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">addTwo</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      已点击 </span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">count</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3"> 次，每次增加 2</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>onClick={addTwo}</code> 把函数交给 React；<code>onClick={addTwo()}</code> 会在渲染时执行它。需要传参数时，写 <code>onClick={() =&gt; removeTask(task.id)}</code>。</p>
<p>表单提交通常使用 <code>onSubmit</code>，再调用 <code>event.preventDefault()</code> 阻止浏览器整页跳转。按钮放在表单中时，明确填写 <code>type=&quot;submit&quot;</code> 或 <code>type=&quot;button&quot;</code>，避免编辑、取消按钮意外提交表单。</p>
<h3>4.2 每次渲染中的状态是一份快照</h3>
<p>在某次事件处理函数中，<code>count</code> 是这次渲染看到的值。调用 <code>setCount</code> 是请求下一次更新，不会修改当前函数里的变量。</p>
<p>如果 <code>count</code> 是 <code>0</code>，连续三次 <code>setCount(count + 1)</code> 都是在提交 <code>1</code>；需要根据上一次排队结果继续计算时，使用 <code>setCount(previous =&gt; previous + 1)</code>。</p>
<p>React 会批量处理多项状态更新，减少不必要的提交。不要简单地把 setter 当成 Promise：<code>await setCount(1)</code> 不能等待界面更新，也不能让下一行读到新的 <code>count</code>。<a href="https://react.dev/learn/state-as-a-snapshot">官方：状态快照</a>、<a href="https://react.dev/learn/queueing-a-series-of-state-updates">更新队列</a></p>
<h3>4.3 更新对象和数组时，创建新值</h3>
<p>以下是组件内部的操作片段：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">type</span><span style="color:#FFA657"> Task</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> { </span><span style="color:#FFA657">id</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">; </span><span style="color:#FFA657">title</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">; </span><span style="color:#FFA657">done</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> boolean</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">tasks</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setTasks</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA657">Task</span><span style="color:#E6EDF3">[]>([])</span></span>
<span class="line"></span>
<span class="line"><span style="color:#8B949E">// 添加：新建数组。</span></span>
<span class="line"><span style="color:#D2A8FF">setTasks</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">previous</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> [</span><span style="color:#FF7B72">...</span><span style="color:#E6EDF3">previous, newTask])</span></span>
<span class="line"></span>
<span class="line"><span style="color:#8B949E">// 修改：数组和发生变化的任务对象都创建新值。</span></span>
<span class="line"><span style="color:#D2A8FF">setTasks</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">previous</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> previous.</span><span style="color:#D2A8FF">map</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span></span>
<span class="line"><span style="color:#E6EDF3">  task.id </span><span style="color:#FF7B72">===</span><span style="color:#E6EDF3"> targetId </span><span style="color:#FF7B72">?</span><span style="color:#E6EDF3"> { </span><span style="color:#FF7B72">...</span><span style="color:#E6EDF3">task, done: </span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">task.done } </span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> task</span></span>
<span class="line"><span style="color:#E6EDF3">))</span></span>
<span class="line"></span>
<span class="line"><span style="color:#8B949E">// 删除：生成过滤后的新数组。</span></span>
<span class="line"><span style="color:#D2A8FF">setTasks</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">previous</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> previous.</span><span style="color:#D2A8FF">filter</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> task.id </span><span style="color:#FF7B72">!==</span><span style="color:#E6EDF3"> targetId))</span></span>
</code></pre>
<p>片段中的 <code>newTask</code>、<code>targetId</code> 由对应事件提供。不要直接 <code>tasks.push(...)</code> 或修改 <code>task.done</code> 后把原数组交回 setter；同一个引用会让更新判断、调试和后续优化都变得不可靠。</p>
<p>更新函数也要保持纯粹。网络请求、写存储、生成随机 ID 等操作不要放进 <code>setTasks(previous =&gt; ...)</code> 的回调里。先在事件中生成新任务，再让回调只负责计算新数组。</p>
<h2>五、状态应该放在哪里？</h2>
<h3>5.1 先区分需要保存的状态与可以计算的值</h3>
<p>假设已有任务数组和筛选条件，下面这些值可以直接计算：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> remaining</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> tasks.</span><span style="color:#D2A8FF">filter</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">task.done).</span><span style="color:#79C0FF">length</span></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> completed</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> tasks.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> -</span><span style="color:#E6EDF3"> remaining</span></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> visibleTasks</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> tasks.</span><span style="color:#D2A8FF">filter</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span></span>
<span class="line"><span style="color:#E6EDF3">  filter </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'all'</span><span style="color:#FF7B72"> ||</span><span style="color:#E6EDF3"> (filter </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'completed'</span><span style="color:#FF7B72"> ?</span><span style="color:#E6EDF3"> task.done </span><span style="color:#FF7B72">:</span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">task.done)</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p>不要再分别维护 <code>remaining</code>、<code>completed</code> 和 <code>visibleTasks</code> 三份状态，并用 Effect 同步它们。重复状态越多，添加、删除、恢复缓存时就越容易漏更新。</p>
<p>只有“无法从当前输入直接推导、需要跨渲染记住”的信息，才优先考虑放入 state。<a href="https://react.dev/learn/choosing-the-state-structure">官方：选择状态结构</a></p>
<h3>5.2 多个组件使用同一份数据时，提升状态</h3>
<p>任务表单需要添加任务，列表需要展示和删除，统计栏需要计算数量。它们应该共享一份任务数组，通常放在最近的共同父组件里，再向下传递数据和回调。</p>
<table>
<thead>
<tr>
<th>数据</th>
<th>合适的起点</th>
</tr>
</thead>
<tbody>
<tr>
<td>编辑框是否展开、当前草稿</td>
<td>当前组件的 state</td>
</tr>
<tr>
<td>同一页面的任务与筛选条件</td>
<td>页面或共同父组件</td>
</tr>
<tr>
<td>多个页面共享的会话、任务数据</td>
<td>更上层的 Provider 或状态库</td>
</tr>
<tr>
<td>刷新、复制链接后还要保留的页码与筛选</td>
<td>URL 查询参数</td>
</tr>
<tr>
<td>同一浏览器刷新后恢复的草稿</td>
<td>本地存储</td>
</tr>
<tr>
<td>需要权限校验、跨设备同步的数据</td>
<td>后端；前端负责请求与缓存</td>
</tr>
</tbody>
</table>
<p><code>localStorage</code> 是持久化工具，不会自动成为 React 的响应式状态。自定义 Hook 也只是复用逻辑：在两个组件中分别调用 <code>useTasks()</code>，会得到两份独立状态，不能因此认为数据已经共享。</p>
<h2>六、理解常用 Hooks 和 Effect</h2>
<h3>6.1 Hooks 的调用位置有规则</h3>
<p>本文使用的 <code>useState</code>、<code>useEffect</code>、<code>useRef</code> 等 Hooks，应在组件或自定义 Hook 的顶层调用，不放进条件、循环、事件处理函数，也不放在某个条件提前返回之后。React 依赖稳定的调用顺序关联它们的状态。</p>
<p>自定义 Hook 以 <code>use</code> 开头，例如 <code>useTasks</code>。组件正常调用 Hook，事件回调调用 Hook 返回的操作函数。<a href="https://react.dev/reference/rules/rules-of-hooks">官方：Hooks 规则</a></p>
<h3>6.2 Effect 用来同步外部系统</h3>
<p>Effect 常用于订阅、定时器、浏览器 API 或外部数据同步。先看一个完整的小例子：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useEffect, useState } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> default</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> Clock</span><span style="color:#FFA657">() </span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">now</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setNow</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> Date.</span><span style="color:#D2A8FF">now</span><span style="color:#E6EDF3">())</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  useEffect</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> timer</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> window.</span><span style="color:#D2A8FF">setInterval</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#D2A8FF"> setNow</span><span style="color:#E6EDF3">(Date.</span><span style="color:#D2A8FF">now</span><span style="color:#E6EDF3">()), </span><span style="color:#79C0FF">1000</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#E6EDF3"> () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> window.</span><span style="color:#D2A8FF">clearInterval</span><span style="color:#E6EDF3">(timer)</span></span>
<span class="line"><span style="color:#E6EDF3">  }, [])</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">time</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{new</span><span style="color:#D2A8FF"> Date</span><span style="color:#E6EDF3">(now).</span><span style="color:#D2A8FF">toLocaleTimeString</span><span style="color:#E6EDF3">()</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">time</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>返回的函数负责清理。在依赖改变、下一次 Effect 建立前，React 会清理上一轮；组件卸载时也会清理。</p>
<p>三种依赖写法含义不同：</p>
<table>
<thead>
<tr>
<th>写法</th>
<th>何时重新同步</th>
</tr>
</thead>
<tbody>
<tr>
<td>不传依赖数组</td>
<td>每次提交后重新运行</td>
</tr>
<tr>
<td><code>[]</code></td>
<td>本次挂载建立；开发检查或重新挂载仍可能重复建立</td>
</tr>
<tr>
<td><code>[query, page]</code></td>
<td>初次建立，以及依赖通过 <code>Object.is</code> 比较发生变化时</td>
</tr>
</tbody>
</table>
<p>Effect 读取了组件作用域中的响应式值，通常就应该声明为依赖。不要为了“只执行一次”而删掉依赖或关闭相关 lint 检查；应该调整状态和逻辑的位置。<a href="https://react.dev/learn/synchronizing-with-effects">官方：同步 Effect</a></p>
<h3>6.3 哪些事情不需要 Effect？</h3>
<ul>
<li>点击“添加”后创建任务：直接放在添加事件中。</li>
<li>根据任务数组计算数量：渲染时计算。</li>
<li>筛选当前已有的数据：渲染时计算。</li>
<li>为某次明确的购买、提交或删除发送请求：放在相应事件或应用的数据操作层。</li>
</ul>
<p>如果某个逻辑是“用户做了这件事，所以执行”，先考虑事件；如果是“组件需要与外部系统保持同步”，再考虑 Effect。<a href="https://react.dev/learn/you-might-not-need-an-effect">官方：你可能不需要 Effect</a></p>
<h3>6.4 useRef 保存不直接参与渲染的值</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useRef } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> default</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> FocusDemo</span><span style="color:#FFA657">() </span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> inputRef</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> useRef</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA657">HTMLInputElement</span><span style="color:#E6EDF3">>(</span><span style="color:#79C0FF">null</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        任务名称</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">input</span><span style="color:#79C0FF"> ref</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">inputRef</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3"> /></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"button"</span><span style="color:#79C0FF"> onClick</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">() </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> inputRef.current?.</span><span style="color:#D2A8FF">focus</span><span style="color:#E6EDF3">()</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        聚焦输入框</span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>ref.current</code> 的修改不会触发重新渲染，适合保存 DOM 引用、定时器 ID 等。需要立刻显示在界面上的数据仍应使用 state；不要把 ref 当成绕过正常数据流的公共变量。</p>
<h3>6.5 StrictMode 为什么会让日志和 Effect 多执行？</h3>
<p>开发环境中的 StrictMode 会额外检查渲染纯度，并执行额外的 Effect 建立、清理周期，以发现缺少清理等问题。具体检查也与 StrictMode 放置的位置有关。</p>
<p>看到重复请求或定时器时，先检查清理、取消和幂等性。不要把移除 StrictMode 或用 ref 强行跳过第二次 Effect 当成默认修复。用户离开页面再返回，本来就可能发生真正的卸载与重建。<a href="https://react.dev/reference/react/StrictMode">官方：StrictMode</a></p>
<h2>七、实战目标与文件结构</h2>
<p>从这一节开始，把前面的独立演示替换成完整任务看板。保留 Vite 创建的配置和 <code>index.html</code>，按下面路径新增或替换文件。</p>
<p>完成后应能观察到：</p>
<ol>
<li>添加非空任务，编辑名称，标记完成，删除任务。</li>
<li>通过关键词和状态筛选，统计数量始终与完整任务数组一致。</li>
<li>刷新页面后恢复任务，清空搜索不会丢失数据。</li>
<li>无任务与无筛选结果显示不同提示。</li>
<li>缓存损坏或存储不可写时，页面仍能使用，并显示保存状态。</li>
</ol>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">src/
├── main.tsx
├── App.tsx
├── index.css
├── tasks.ts
├── storage.ts
├── hooks/
│   └── useTasks.ts
└── components/
    ├── TaskForm.tsx
    └── TaskList.tsx
</code></pre>
<p>任务数据和持久化由一个 Hook 管理，<code>App</code> 只调用一次，再把结果传给子组件。搜索、筛选属于页面状态；编辑草稿属于单个任务项。这个划分正好对应前面的状态归属原则。</p>
<h2>八、实现数据模型、存储与任务操作</h2>
<h3>8.1 定义类型与纯函数</h3>
<p><code>src/tasks.ts</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-ts"><span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> type</span><span style="color:#FFA657"> Task</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FFA657">  id</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span></span>
<span class="line"><span style="color:#FFA657">  title</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span></span>
<span class="line"><span style="color:#FFA657">  done</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> boolean</span></span>
<span class="line"><span style="color:#FFA657">  createdAt</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> number</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> type</span><span style="color:#FFA657"> Filter</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> 'all'</span><span style="color:#FF7B72"> |</span><span style="color:#A5D6FF"> 'active'</span><span style="color:#FF7B72"> |</span><span style="color:#A5D6FF"> 'completed'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> isTask</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">value</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> unknown</span><span style="color:#E6EDF3">)</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> value</span><span style="color:#FF7B72"> is</span><span style="color:#FFA657"> Task</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">typeof</span><span style="color:#E6EDF3"> value </span><span style="color:#FF7B72">!==</span><span style="color:#A5D6FF"> 'object'</span><span style="color:#FF7B72"> ||</span><span style="color:#E6EDF3"> value </span><span style="color:#FF7B72">===</span><span style="color:#79C0FF"> null</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">return</span><span style="color:#79C0FF"> false</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> task</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> value </span><span style="color:#FF7B72">as</span><span style="color:#FFA657"> Record</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#79C0FF">string</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">unknown</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#FF7B72">    typeof</span><span style="color:#E6EDF3"> task.id </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'string'</span><span style="color:#FF7B72"> &#x26;&#x26;</span><span style="color:#E6EDF3"> task.id.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">().</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#79C0FF"> 0</span><span style="color:#FF7B72"> &#x26;&#x26;</span></span>
<span class="line"><span style="color:#FF7B72">    typeof</span><span style="color:#E6EDF3"> task.title </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'string'</span><span style="color:#FF7B72"> &#x26;&#x26;</span></span>
<span class="line"><span style="color:#E6EDF3">    task.title.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">().</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#79C0FF"> 0</span><span style="color:#FF7B72"> &#x26;&#x26;</span><span style="color:#E6EDF3"> task.title.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> &#x3C;=</span><span style="color:#79C0FF"> 80</span><span style="color:#FF7B72"> &#x26;&#x26;</span></span>
<span class="line"><span style="color:#FF7B72">    typeof</span><span style="color:#E6EDF3"> task.done </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'boolean'</span><span style="color:#FF7B72"> &#x26;&#x26;</span></span>
<span class="line"><span style="color:#FF7B72">    typeof</span><span style="color:#E6EDF3"> task.createdAt </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'number'</span><span style="color:#FF7B72"> &#x26;&#x26;</span></span>
<span class="line"><span style="color:#E6EDF3">    Number.</span><span style="color:#D2A8FF">isFinite</span><span style="color:#E6EDF3">(task.createdAt) </span><span style="color:#FF7B72">&#x26;&#x26;</span><span style="color:#E6EDF3"> task.createdAt </span><span style="color:#FF7B72">>=</span><span style="color:#79C0FF"> 0</span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> parseTasks</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">raw</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#FF7B72"> |</span><span style="color:#79C0FF"> null</span><span style="color:#E6EDF3">)</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> Task</span><span style="color:#E6EDF3">[] {</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (raw </span><span style="color:#FF7B72">===</span><span style="color:#79C0FF"> null</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">return</span><span style="color:#E6EDF3"> []</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> value</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> unknown</span><span style="color:#FF7B72"> =</span><span style="color:#79C0FF"> JSON</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">parse</span><span style="color:#E6EDF3">(raw)</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">Array.</span><span style="color:#D2A8FF">isArray</span><span style="color:#E6EDF3">(value) </span><span style="color:#FF7B72">||</span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">value.</span><span style="color:#D2A8FF">every</span><span style="color:#E6EDF3">(isTask)) {</span></span>
<span class="line"><span style="color:#FF7B72">    throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'任务数据格式不正确'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">new</span><span style="color:#D2A8FF"> Set</span><span style="color:#E6EDF3">(value.</span><span style="color:#D2A8FF">map</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> task.id)).size </span><span style="color:#FF7B72">!==</span><span style="color:#E6EDF3"> value.</span><span style="color:#79C0FF">length</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">    throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'任务 ID 不能重复'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> value</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> filterTasks</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">tasks</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> Task</span><span style="color:#E6EDF3">[], </span><span style="color:#FFA657">filter</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> Filter</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">query</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> keyword</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> query.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">().</span><span style="color:#D2A8FF">toLocaleLowerCase</span><span style="color:#E6EDF3">()</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> tasks.</span><span style="color:#D2A8FF">filter</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> matchesStatus</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> filter </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'all'</span><span style="color:#FF7B72"> ||</span></span>
<span class="line"><span style="color:#E6EDF3">      (filter </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'completed'</span><span style="color:#FF7B72"> ?</span><span style="color:#E6EDF3"> task.done </span><span style="color:#FF7B72">:</span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">task.done)</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> matchesTitle</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> task.title.</span><span style="color:#D2A8FF">toLocaleLowerCase</span><span style="color:#E6EDF3">().</span><span style="color:#D2A8FF">includes</span><span style="color:#E6EDF3">(keyword)</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#E6EDF3"> matchesStatus </span><span style="color:#FF7B72">&#x26;&#x26;</span><span style="color:#E6EDF3"> matchesTitle</span></span>
<span class="line"><span style="color:#E6EDF3">  })</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>Task</code> 描述一项任务，<code>Filter</code> 是只能取三个值的联合类型。<code>unknown</code> 表示输入尚未可信，必须经过检查才能使用；<code>value is Task</code> 是类型守卫，帮助 TypeScript 在检查通过后缩小类型范围。</p>
<p>TypeScript 类型在运行时不会自动验证 JSON。给 <code>JSON.parse</code> 的结果写一个 <code>as Task[]</code>，也不能保证缓存或接口真的符合结构。这里还检查 ID 唯一性，避免损坏数据制造重复 <code>key</code>。</p>
<h3>8.2 读取缓存，明确失败时的行为</h3>
<p><code>src/storage.ts</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-ts"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { parseTasks, </span><span style="color:#FF7B72">type</span><span style="color:#E6EDF3"> Task } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './tasks'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> const</span><span style="color:#79C0FF"> STORAGE_KEY</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> 'react-task-board:v1'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> type</span><span style="color:#FFA657"> TaskSnapshot</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FFA657">  tasks</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> Task</span><span style="color:#E6EDF3">[]</span></span>
<span class="line"><span style="color:#FFA657">  writable</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> boolean</span></span>
<span class="line"><span style="color:#FFA657">  error</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#FF7B72"> |</span><span style="color:#79C0FF"> null</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> readTasks</span><span style="color:#E6EDF3">()</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> TaskSnapshot</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">  try</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">      tasks: </span><span style="color:#D2A8FF">parseTasks</span><span style="color:#E6EDF3">(window.localStorage.</span><span style="color:#D2A8FF">getItem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">STORAGE_KEY</span><span style="color:#E6EDF3">)),</span></span>
<span class="line"><span style="color:#E6EDF3">      writable: </span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">      error: </span><span style="color:#79C0FF">null</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#E6EDF3">  } </span><span style="color:#FF7B72">catch</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">      tasks: [],</span></span>
<span class="line"><span style="color:#E6EDF3">      writable: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">      error: </span><span style="color:#A5D6FF">'读取任务缓存失败。原缓存未覆盖，本次新增任务仅在当前页面保留。'</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>缓存缺失时返回空数组；缓存格式错误或读取受限时，保留原缓存，禁用本次挂载的自动写入，并告知用户。这样不会刚打开页面就用空数组覆盖尚可恢复的原始内容。</p>
<p>如果遇到该提示，可以先在浏览器开发者工具中检查并备份对应存储项；确认不再需要后，再手动移除该项并刷新。示例不自动修复损坏缓存，也不提供跨标签页合并。</p>
<h3>8.3 封装 useTasks</h3>
<p><code>src/hooks/useTasks.ts</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-ts"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useEffect, useState } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { readTasks, STORAGE_KEY } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> '../storage'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#FF7B72"> type</span><span style="color:#E6EDF3"> { Task } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> '../tasks'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> useTasks</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">initial</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">(readTasks)</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">tasks</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setTasks</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA657">Task</span><span style="color:#E6EDF3">[]>(initial.tasks)</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">storageError</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setStorageError</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">(initial.error)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  useEffect</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">initial.writable) </span><span style="color:#FF7B72">return</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    try</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">      window.localStorage.</span><span style="color:#D2A8FF">setItem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">STORAGE_KEY</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">JSON</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">stringify</span><span style="color:#E6EDF3">(tasks))</span></span>
<span class="line"><span style="color:#E6EDF3">    } </span><span style="color:#FF7B72">catch</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#8B949E">      // oxlint-disable-next-line react/set-state-in-effect -- 将同步存储的写入失败反馈到界面。</span></span>
<span class="line"><span style="color:#D2A8FF">      setStorageError</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'保存失败，修改仅在当前页面保留。请检查浏览器存储权限或可用空间。'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#E6EDF3">  }, [tasks, initial.writable])</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  function</span><span style="color:#D2A8FF"> addTask</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">rawTitle</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> title</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> rawTitle.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">title </span><span style="color:#FF7B72">||</span><span style="color:#E6EDF3"> title.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#79C0FF"> 80</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">return</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> task</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> Task</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">      id: crypto.</span><span style="color:#D2A8FF">randomUUID</span><span style="color:#E6EDF3">(),</span></span>
<span class="line"><span style="color:#E6EDF3">      title,</span></span>
<span class="line"><span style="color:#E6EDF3">      done: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">      createdAt: Date.</span><span style="color:#D2A8FF">now</span><span style="color:#E6EDF3">(),</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#D2A8FF">    setTasks</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">previous</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> [task, </span><span style="color:#FF7B72">...</span><span style="color:#E6EDF3">previous])</span></span>
<span class="line"><span style="color:#D2A8FF">    setStorageError</span><span style="color:#E6EDF3">(initial.error)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  function</span><span style="color:#D2A8FF"> toggleTask</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">id</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#D2A8FF">    setTasks</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">previous</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> previous.</span><span style="color:#D2A8FF">map</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span></span>
<span class="line"><span style="color:#E6EDF3">      task.id </span><span style="color:#FF7B72">===</span><span style="color:#E6EDF3"> id </span><span style="color:#FF7B72">?</span><span style="color:#E6EDF3"> { </span><span style="color:#FF7B72">...</span><span style="color:#E6EDF3">task, done: </span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">task.done } </span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> task</span></span>
<span class="line"><span style="color:#E6EDF3">    ))</span></span>
<span class="line"><span style="color:#D2A8FF">    setStorageError</span><span style="color:#E6EDF3">(initial.error)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  function</span><span style="color:#D2A8FF"> renameTask</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">id</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">rawTitle</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> title</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> rawTitle.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">title </span><span style="color:#FF7B72">||</span><span style="color:#E6EDF3"> title.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#79C0FF"> 80</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">return</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">    setTasks</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">previous</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> previous.</span><span style="color:#D2A8FF">map</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span></span>
<span class="line"><span style="color:#E6EDF3">      task.id </span><span style="color:#FF7B72">===</span><span style="color:#E6EDF3"> id </span><span style="color:#FF7B72">?</span><span style="color:#E6EDF3"> { </span><span style="color:#FF7B72">...</span><span style="color:#E6EDF3">task, title } </span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> task</span></span>
<span class="line"><span style="color:#E6EDF3">    ))</span></span>
<span class="line"><span style="color:#D2A8FF">    setStorageError</span><span style="color:#E6EDF3">(initial.error)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  function</span><span style="color:#D2A8FF"> removeTask</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">id</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#D2A8FF">    setTasks</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">previous</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> previous.</span><span style="color:#D2A8FF">filter</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> task.id </span><span style="color:#FF7B72">!==</span><span style="color:#E6EDF3"> id))</span></span>
<span class="line"><span style="color:#D2A8FF">    setStorageError</span><span style="color:#E6EDF3">(initial.error)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> { tasks, storageError, addTask, toggleTask, renameTask, removeTask }</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>这里有几个值得对照理解的细节：</p>
<ul>
<li><code>useState(readTasks)</code> 传入初始化函数，不是在每次渲染时执行 <code>readTasks()</code>。</li>
<li>初始化只读缓存；存储写入放在 Effect 中，与外部系统同步。</li>
<li>ID 和创建时间在添加事件中生成，状态更新回调只计算数组。</li>
<li>更新均使用函数式 setter，避免依赖某次渲染中捕获的旧数组。</li>
<li>保存失败会反馈到界面；下一次操作先清除上一轮写入错误，再尝试保存。读取失败的提示保留，同时保持停止自动写入。</li>
</ul>
<p>代码中的局部 lint 例外只用于把同步存储失败反馈到界面；它不是通过 Effect 维护重复的业务状态，也不应扩展为关闭整个项目的 Hooks 检查。</p>
<p>本地存储是同步 API，这个方案适合小规模学习数据。任务很多、写入频繁或需要多标签页同步时，应重新选择持久化方案；不要直接把它当成生产数据库。<code>crypto.randomUUID()</code> 需要安全上下文，本地 localhost 与正式 HTTPS 是本文的运行前提。</p>
<h2>九、实现表单、列表与页面</h2>
<h3>9.1 添加任务：受控表单</h3>
<p><code>src/components/TaskForm.tsx</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useId, useState, </span><span style="color:#FF7B72">type</span><span style="color:#E6EDF3"> FormEvent } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">type</span><span style="color:#FFA657"> TaskFormProps</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#D2A8FF">  onAdd</span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> (</span><span style="color:#FFA657">title</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#79C0FF"> void</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> TaskForm</span><span style="color:#E6EDF3">({ </span><span style="color:#FFA657">onAdd</span><span style="color:#E6EDF3"> }</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> TaskFormProps</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> inputId</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> useId</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">title</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setTitle</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  function</span><span style="color:#D2A8FF"> handleSubmit</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">event</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> FormEvent</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA657">HTMLFormElement</span><span style="color:#E6EDF3">>) {</span></span>
<span class="line"><span style="color:#E6EDF3">    event.</span><span style="color:#D2A8FF">preventDefault</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> value</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> title.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">value </span><span style="color:#FF7B72">||</span><span style="color:#E6EDF3"> value.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#79C0FF"> 80</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">return</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">    onAdd</span><span style="color:#E6EDF3">(value)</span></span>
<span class="line"><span style="color:#D2A8FF">    setTitle</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">form</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"task-form"</span><span style="color:#79C0FF"> onSubmit</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">handleSubmit</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">label</span><span style="color:#79C0FF"> htmlFor</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">inputId</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">>新任务&#x3C;/</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">div</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"input-row"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">input</span></span>
<span class="line"><span style="color:#79C0FF">          id</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">inputId</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">          value</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">title</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">          onChange</span><span style="color:#FF7B72">={</span><span style="color:#FFA657">event</span><span style="color:#FF7B72"> =></span><span style="color:#D2A8FF"> setTitle</span><span style="color:#E6EDF3">(event.target.value)</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">          maxLength</span><span style="color:#FF7B72">={</span><span style="color:#79C0FF">80</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">          required</span></span>
<span class="line"><span style="color:#79C0FF">          placeholder</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"例如：完成 React 状态练习"</span></span>
<span class="line"><span style="color:#E6EDF3">        /></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"submit"</span><span style="color:#79C0FF"> disabled</span><span style="color:#FF7B72">={!</span><span style="color:#E6EDF3">title.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">()</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">>添加任务&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">div</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">form</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>value</code> 来自 state，<code>onChange</code> 把输入写回 state，这就是受控输入。文本初始值使用空字符串，不要先传 <code>undefined</code> 再改成字符串，避免在受控和非受控模式之间切换。</p>
<p>复选框使用 <code>checked</code> 和 <code>event.target.checked</code>。只需读取一次提交值时，也可以使用非受控表单和 <code>FormData</code>，后文会给出例子。</p>
<p><code>useId</code> 用于生成标签与输入框之间的关联 ID。它不是业务任务 ID，也不应该用来生成列表的 <code>key</code>。</p>
<h3>9.2 列表项：完成、编辑与删除</h3>
<p><code>src/components/TaskList.tsx</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useId, useState, </span><span style="color:#FF7B72">type</span><span style="color:#E6EDF3"> FormEvent } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#FF7B72"> type</span><span style="color:#E6EDF3"> { Task } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> '../tasks'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">type</span><span style="color:#FFA657"> TaskActions</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#D2A8FF">  onToggle</span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> (</span><span style="color:#FFA657">id</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#79C0FF"> void</span></span>
<span class="line"><span style="color:#D2A8FF">  onRename</span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> (</span><span style="color:#FFA657">id</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">title</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#79C0FF"> void</span></span>
<span class="line"><span style="color:#D2A8FF">  onRemove</span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> (</span><span style="color:#FFA657">id</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#79C0FF"> void</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">type</span><span style="color:#FFA657"> TaskListProps</span><span style="color:#FF7B72"> =</span><span style="color:#FFA657"> TaskActions</span><span style="color:#FF7B72"> &#x26;</span><span style="color:#E6EDF3"> { </span><span style="color:#FFA657">tasks</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> Task</span><span style="color:#E6EDF3">[] }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> TaskList</span><span style="color:#E6EDF3">({ </span><span style="color:#FFA657">tasks</span><span style="color:#E6EDF3">, </span><span style="color:#FF7B72">...</span><span style="color:#FFA657">actions</span><span style="color:#E6EDF3"> }</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> TaskListProps</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">ul</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"task-list"</span><span style="color:#79C0FF"> aria-label</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"任务列表"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#FF7B72">      {</span><span style="color:#E6EDF3">tasks.</span><span style="color:#D2A8FF">map</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">TaskItem</span><span style="color:#79C0FF"> key</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">task.id</span><span style="color:#FF7B72">}</span><span style="color:#79C0FF"> task</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">task</span><span style="color:#FF7B72">}</span><span style="color:#FF7B72"> {...</span><span style="color:#E6EDF3">actions</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3"> /></span></span>
<span class="line"><span style="color:#E6EDF3">      ))</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">ul</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> TaskItem</span><span style="color:#E6EDF3">({ </span><span style="color:#FFA657">task</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">onToggle</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">onRename</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">onRemove</span><span style="color:#E6EDF3"> }</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> TaskActions</span><span style="color:#FF7B72"> &#x26;</span><span style="color:#E6EDF3"> { </span><span style="color:#FFA657">task</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> Task</span><span style="color:#E6EDF3"> }) {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> editId</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> useId</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">editing</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setEditing</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">draft</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setDraft</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">(task.title)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  function</span><span style="color:#D2A8FF"> startEditing</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#D2A8FF">    setDraft</span><span style="color:#E6EDF3">(task.title)</span></span>
<span class="line"><span style="color:#D2A8FF">    setEditing</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  function</span><span style="color:#D2A8FF"> save</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">event</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> FormEvent</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA657">HTMLFormElement</span><span style="color:#E6EDF3">>) {</span></span>
<span class="line"><span style="color:#E6EDF3">    event.</span><span style="color:#D2A8FF">preventDefault</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> title</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> draft.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">title </span><span style="color:#FF7B72">||</span><span style="color:#E6EDF3"> title.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#79C0FF"> 80</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#D2A8FF">    onRename</span><span style="color:#E6EDF3">(task.id, title)</span></span>
<span class="line"><span style="color:#D2A8FF">    setEditing</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">li</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"task-item"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#FF7B72">      {</span><span style="color:#E6EDF3">editing </span><span style="color:#FF7B72">?</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">form</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"edit-form"</span><span style="color:#79C0FF"> onSubmit</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">save</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;</span><span style="color:#7EE787">label</span><span style="color:#79C0FF"> htmlFor</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">editId</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">>任务标题&#x3C;/</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;</span><span style="color:#7EE787">input</span></span>
<span class="line"><span style="color:#79C0FF">            id</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">editId</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">            value</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">draft</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">            onChange</span><span style="color:#FF7B72">={</span><span style="color:#FFA657">event</span><span style="color:#FF7B72"> =></span><span style="color:#D2A8FF"> setDraft</span><span style="color:#E6EDF3">(event.target.value)</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">            maxLength</span><span style="color:#FF7B72">={</span><span style="color:#79C0FF">80</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">            required</span></span>
<span class="line"><span style="color:#79C0FF">            autoFocus</span></span>
<span class="line"><span style="color:#E6EDF3">          /></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;</span><span style="color:#7EE787">div</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"actions"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">            &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"submit"</span><span style="color:#79C0FF"> disabled</span><span style="color:#FF7B72">={!</span><span style="color:#E6EDF3">draft.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">()</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">>保存&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">            &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"button"</span><span style="color:#79C0FF"> onClick</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">() </span><span style="color:#FF7B72">=></span><span style="color:#D2A8FF"> setEditing</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3">)</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">>取消&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;/</span><span style="color:#7EE787">div</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;/</span><span style="color:#7EE787">form</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      ) </span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;</span><span style="color:#7EE787">label</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"task-title"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">            &#x3C;</span><span style="color:#7EE787">input</span></span>
<span class="line"><span style="color:#79C0FF">              type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"checkbox"</span></span>
<span class="line"><span style="color:#79C0FF">              checked</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">task.done</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">              onChange</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">() </span><span style="color:#FF7B72">=></span><span style="color:#D2A8FF"> onToggle</span><span style="color:#E6EDF3">(task.id)</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">            /></span></span>
<span class="line"><span style="color:#E6EDF3">            &#x3C;</span><span style="color:#7EE787">span</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">task.done </span><span style="color:#FF7B72">?</span><span style="color:#A5D6FF"> 'is-done'</span><span style="color:#FF7B72"> :</span><span style="color:#79C0FF"> undefined</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">task.title</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">span</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;/</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;</span><span style="color:#7EE787">div</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"actions"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">            &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"button"</span><span style="color:#79C0FF"> onClick</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">startEditing</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">>编辑&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">            &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"button"</span><span style="color:#79C0FF"> onClick</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">() </span><span style="color:#FF7B72">=></span><span style="color:#D2A8FF"> onRemove</span><span style="color:#E6EDF3">(task.id)</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">>删除&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;/</span><span style="color:#7EE787">div</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;/></span></span>
<span class="line"><span style="color:#E6EDF3">      )</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">li</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>TaskActions &amp; { task: Task }</code> 把操作回调类型和任务属性组合起来。<code>TaskItem</code> 内部只保存编辑状态与草稿，任务本身仍由上层维护。</p>
<p>草稿在点击“编辑”时从当前标题重新初始化，而不是用 Effect 持续同步 Props。这样用户正在编辑时，不会被一次普通的父组件渲染覆盖输入。</p>
<h3>9.3 把数据流接起来</h3>
<p><code>src/App.tsx</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useState } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { TaskForm } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './components/TaskForm'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { TaskList } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './components/TaskList'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useTasks } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './hooks/useTasks'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { filterTasks, </span><span style="color:#FF7B72">type</span><span style="color:#E6EDF3"> Filter } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './tasks'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> default</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> App</span><span style="color:#FFA657">() </span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">tasks</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">storageError</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">addTask</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">toggleTask</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">renameTask</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">removeTask</span><span style="color:#E6EDF3"> } </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useTasks</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">query</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setQuery</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">filter</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setFilter</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA657">Filter</span><span style="color:#E6EDF3">>(</span><span style="color:#A5D6FF">'all'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> remaining</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> tasks.</span><span style="color:#D2A8FF">filter</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">task.done).</span><span style="color:#79C0FF">length</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> visibleTasks</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> filterTasks</span><span style="color:#E6EDF3">(tasks, filter, query)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">main</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"board"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">header</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">>任务看板&#x3C;/</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#79C0FF"> role</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"status"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          共 </span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">tasks.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3"> 项，未完成 </span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">remaining</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3"> 项，已完成 </span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">tasks.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> -</span><span style="color:#E6EDF3"> remaining</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3"> 项</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">header</span><span style="color:#E6EDF3">></span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">      {</span><span style="color:#E6EDF3">storageError </span><span style="color:#FF7B72">&#x26;&#x26;</span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"notice"</span><span style="color:#79C0FF"> role</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"alert"</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">storageError</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">TaskForm</span><span style="color:#79C0FF"> onAdd</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">addTask</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3"> /></span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">div</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"toolbar"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          搜索任务</span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;</span><span style="color:#7EE787">input</span></span>
<span class="line"><span style="color:#79C0FF">            type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"search"</span></span>
<span class="line"><span style="color:#79C0FF">            value</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">query</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">            onChange</span><span style="color:#FF7B72">={</span><span style="color:#FFA657">event</span><span style="color:#FF7B72"> =></span><span style="color:#D2A8FF"> setQuery</span><span style="color:#E6EDF3">(event.target.value)</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">            placeholder</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"按标题搜索"</span></span>
<span class="line"><span style="color:#E6EDF3">          /></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;/</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          任务状态</span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;</span><span style="color:#7EE787">select</span></span>
<span class="line"><span style="color:#79C0FF">            value</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">filter</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">            onChange</span><span style="color:#FF7B72">={</span><span style="color:#FFA657">event</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">              const</span><span style="color:#79C0FF"> value</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> event.target.value</span></span>
<span class="line"><span style="color:#FF7B72">              if</span><span style="color:#E6EDF3"> (value </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'all'</span><span style="color:#FF7B72"> ||</span><span style="color:#E6EDF3"> value </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'active'</span><span style="color:#FF7B72"> ||</span><span style="color:#E6EDF3"> value </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'completed'</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#D2A8FF">                setFilter</span><span style="color:#E6EDF3">(value)</span></span>
<span class="line"><span style="color:#E6EDF3">              }</span></span>
<span class="line"><span style="color:#E6EDF3">            }</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">          ></span></span>
<span class="line"><span style="color:#E6EDF3">            &#x3C;</span><span style="color:#7EE787">option</span><span style="color:#79C0FF"> value</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"all"</span><span style="color:#E6EDF3">>全部&#x3C;/</span><span style="color:#7EE787">option</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">            &#x3C;</span><span style="color:#7EE787">option</span><span style="color:#79C0FF"> value</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"active"</span><span style="color:#E6EDF3">>未完成&#x3C;/</span><span style="color:#7EE787">option</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">            &#x3C;</span><span style="color:#7EE787">option</span><span style="color:#79C0FF"> value</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"completed"</span><span style="color:#E6EDF3">>已完成&#x3C;/</span><span style="color:#7EE787">option</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;/</span><span style="color:#7EE787">select</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;/</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">div</span><span style="color:#E6EDF3">></span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">      {</span><span style="color:#E6EDF3">visibleTasks.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#79C0FF"> 0</span><span style="color:#FF7B72"> ?</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">TaskList</span></span>
<span class="line"><span style="color:#79C0FF">          tasks</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">visibleTasks</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">          onToggle</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">toggleTask</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">          onRename</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">renameTask</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">          onRemove</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">removeTask</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">        /></span></span>
<span class="line"><span style="color:#E6EDF3">      ) </span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"empty"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#FF7B72">          {</span><span style="color:#E6EDF3">tasks.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ===</span><span style="color:#79C0FF"> 0</span><span style="color:#FF7B72"> ?</span><span style="color:#A5D6FF"> '还没有任务，先添加一项吧。'</span><span style="color:#FF7B72"> :</span><span style="color:#A5D6FF"> '没有符合当前条件的任务。'</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      )</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">main</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>统计使用完整 <code>tasks</code>，列表使用筛选后的 <code>visibleTasks</code>，所以筛选不会改变任务总数，也不会删除隐藏的任务。</p>
<p><code>select</code> 返回的是普通字符串，这里通过分支检查把它缩小为 <code>Filter</code>。学习时多留意这类数据边界，少用类型断言强行让编译器通过。</p>
<h3>9.4 入口与样式</h3>
<p><code>src/main.tsx</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { StrictMode } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { createRoot } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react-dom/client'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> App </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './App'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#A5D6FF"> './index.css'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> rootElement</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> document.</span><span style="color:#D2A8FF">getElementById</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'root'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">rootElement) </span><span style="color:#FF7B72">throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'缺少 root 挂载节点'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">createRoot</span><span style="color:#E6EDF3">(rootElement).</span><span style="color:#D2A8FF">render</span><span style="color:#E6EDF3">(</span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#7EE787">StrictMode</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">App</span><span style="color:#E6EDF3"> /></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;/</span><span style="color:#7EE787">StrictMode</span><span style="color:#E6EDF3">>,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p><code>src/index.css</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-css"><span class="line"><span style="color:#79C0FF">:root</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">  font-family</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">system-ui</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">sans-serif</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#202124</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  background</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#f6f7f9</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  line-height</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1.6</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#7EE787">*</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">box-sizing</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">border-box</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#7EE787">body</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#7EE787">button</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">input</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">select</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">font</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">inherit</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#7EE787">button</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">input</span><span style="color:#79C0FF">:not</span><span style="color:#E6EDF3">([</span><span style="color:#79C0FF">type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"checkbox"</span><span style="color:#E6EDF3">]), </span><span style="color:#7EE787">select</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">min-height</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">44</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#7EE787">button</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">input</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">select</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">  border</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#FF7B72">px</span><span style="color:#79C0FF"> solid</span><span style="color:#79C0FF"> #c5c9d0</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  border-radius</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">8</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#7EE787">button</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">  padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">6</span><span style="color:#FF7B72">px</span><span style="color:#79C0FF"> 14</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  background</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">white</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">inherit</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  cursor</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">pointer</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#7EE787">button</span><span style="color:#79C0FF">:disabled</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">opacity</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">.5</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">cursor</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">not-allowed</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#7EE787">input</span><span style="color:#79C0FF">:not</span><span style="color:#E6EDF3">([</span><span style="color:#79C0FF">type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"checkbox"</span><span style="color:#E6EDF3">]), </span><span style="color:#7EE787">select</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">  width</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">100</span><span style="color:#FF7B72">%</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  min-width</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">8</span><span style="color:#FF7B72">px</span><span style="color:#79C0FF"> 10</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  background</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">white</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">inherit</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#79C0FF">:focus-visible</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">outline</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">3</span><span style="color:#FF7B72">px</span><span style="color:#79C0FF"> solid</span><span style="color:#79C0FF"> #3466d6</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">outline-offset</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">2</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#7EE787">h1</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">font-size</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1.8</span><span style="color:#FF7B72">rem</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#7EE787">label</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">grid</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">gap</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">6</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">.board</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">  width</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">min</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">760</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">calc</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">100</span><span style="color:#FF7B72">%</span><span style="color:#FF7B72"> -</span><span style="color:#79C0FF"> 32</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">));</span></span>
<span class="line"><span style="color:#79C0FF">  margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">40</span><span style="color:#FF7B72">px</span><span style="color:#79C0FF"> auto</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">24</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  border</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#FF7B72">px</span><span style="color:#79C0FF"> solid</span><span style="color:#79C0FF"> #e1e4e8</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  border-radius</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">16</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  background</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">white</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#79C0FF">.task-form</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">.toolbar</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">margin-top</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">24</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.input-row</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">gap</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">8</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.input-row</span><span style="color:#7EE787"> input</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.input-row</span><span style="color:#7EE787"> button</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">flex-shrink</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.toolbar</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">grid</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">grid-template-columns</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#FF7B72">fr</span><span style="color:#79C0FF"> 150</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">gap</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">16</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.task-list</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">24</span><span style="color:#FF7B72">px</span><span style="color:#79C0FF"> 0</span><span style="color:#79C0FF"> 0</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">list-style</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">none</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.task-item</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">  display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  align-items</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">center</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  gap</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">16</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">16</span><span style="color:#FF7B72">px</span><span style="color:#79C0FF"> 0</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  border-top</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#FF7B72">px</span><span style="color:#79C0FF"> solid</span><span style="color:#79C0FF"> #eceef1</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#79C0FF">.task-title</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">align-items</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">flex-start</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">gap</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">10</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">min-width</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.task-title</span><span style="color:#7EE787"> input</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">margin-top</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">6</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">flex-shrink</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.task-title</span><span style="color:#7EE787"> span</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">overflow-wrap</span><span style="color:#E6EDF3">: anywhere; }</span></span>
<span class="line"><span style="color:#79C0FF">.is-done</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">text-decoration</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">line-through</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#656b75</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.actions</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">flex-wrap</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">wrap</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">gap</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">8</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.edit-form</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">grid</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">width</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">100</span><span style="color:#FF7B72">%</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">gap</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">8</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.empty</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">32</span><span style="color:#FF7B72">px</span><span style="color:#79C0FF"> 0</span><span style="color:#79C0FF"> 8</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#656b75</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.notice</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">12</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">background</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#fff4dd</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">border-radius</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">8</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">@media</span><span style="color:#E6EDF3"> (</span><span style="color:#79C0FF">max-width</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">540</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#79C0FF">  .board</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">16</span><span style="color:#FF7B72">px</span><span style="color:#79C0FF"> auto</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">16</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">  .toolbar</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">grid-template-columns</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#FF7B72">fr</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">  .task-item</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">align-items</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">stretch</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">flex-direction</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">column</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">gap</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">10</span><span style="color:#FF7B72">px</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">  .input-row</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">flex-direction</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">column</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>这些样式不依赖 UI 库，包含窄屏布局、长标题换行和键盘焦点。模板生成的 <code>App.css</code>、Logo 等演示资源不再被新代码引用，可以自行移除。</p>
<h3>9.5 运行并检查基础功能</h3>
<p>继续使用 <code>npm run dev</code>。先添加两项任务，把其中一项标记完成，然后分别搜索、筛选、编辑和刷新。</p>
<p>检查时特别留意：编辑一项任务后，另一项的草稿是否被串用；切换筛选后，统计是否仍准确；刷新后，任务标题和完成状态是否都恢复。这些现象分别对应稳定 <code>key</code>、派生状态和持久化三个知识点。</p>
<p>到这里，基础项目已经可以独立运行。后面的章节都是在此基础上的扩展，不需要一次性全部接入。</p>
<h2>十、接入接口：加载、错误与请求竞态</h2>
<h3>10.1 先明确数据由谁负责</h3>
<p>基础版以浏览器内存和本地存储为数据来源。接入后端后，不能同时把本地缓存和服务器都当成最终事实，否则会出现服务器已删除、刷新却又被本地缓存恢复的问题。</p>
<p>下面单独实现一个远程查询示例，先学习请求与展示。它不会替换基础版的本地任务状态。实际迁移时，再把创建、修改、删除统一改成后端操作，并决定成功后更新本地缓存还是重新获取列表。</p>
<p>接口约定为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">GET /api/tasks?q=react

成功：HTTP 200，响应体为 Task[] JSON 数组
每项包含 id、title、done、createdAt，含义与基础版一致
没有匹配项：HTTP 200，响应体为 []
失败：返回相应的非 2xx HTTP 状态码
</code></pre>
<p>这个接口需要自己的后端提供。Vite 基础模板不会自动生成 <code>/api/tasks</code>；直接运行下方组件而未提供接口时，应看到错误提示。</p>
<h3>10.2 封装带取消与重试的请求 Hook</h3>
<p><code>src/hooks/useRemoteTasks.ts</code>，可选扩展文件：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-ts"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useEffect, useState } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { parseTasks, </span><span style="color:#FF7B72">type</span><span style="color:#E6EDF3"> Task } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> '../tasks'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">type</span><span style="color:#FFA657"> RemoteState</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FFA657">  query</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span></span>
<span class="line"><span style="color:#FFA657">  status</span><span style="color:#FF7B72">:</span><span style="color:#A5D6FF"> 'loading'</span><span style="color:#FF7B72"> |</span><span style="color:#A5D6FF"> 'success'</span><span style="color:#FF7B72"> |</span><span style="color:#A5D6FF"> 'error'</span></span>
<span class="line"><span style="color:#FFA657">  items</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> Task</span><span style="color:#E6EDF3">[]</span></span>
<span class="line"><span style="color:#FFA657">  error</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#FF7B72"> |</span><span style="color:#79C0FF"> null</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> useRemoteTasks</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">query</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">attempt</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setAttempt</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">state</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setState</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA657">RemoteState</span><span style="color:#E6EDF3">>({</span></span>
<span class="line"><span style="color:#E6EDF3">    query,</span></span>
<span class="line"><span style="color:#E6EDF3">    status: </span><span style="color:#A5D6FF">'loading'</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    items: [],</span></span>
<span class="line"><span style="color:#E6EDF3">    error: </span><span style="color:#79C0FF">null</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">  })</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  useEffect</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> controller</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> AbortController</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">    let</span><span style="color:#E6EDF3"> active </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> true</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    async</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> load</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#D2A8FF">      setState</span><span style="color:#E6EDF3">({ query, status: </span><span style="color:#A5D6FF">'loading'</span><span style="color:#E6EDF3">, items: [], error: </span><span style="color:#79C0FF">null</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">      try</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> params</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> URLSearchParams</span><span style="color:#E6EDF3">({ q: query.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">() })</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> response</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> await</span><span style="color:#D2A8FF"> fetch</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'/api/tasks?'</span><span style="color:#FF7B72"> +</span><span style="color:#E6EDF3"> params.</span><span style="color:#D2A8FF">toString</span><span style="color:#E6EDF3">(), {</span></span>
<span class="line"><span style="color:#E6EDF3">          signal: controller.signal,</span></span>
<span class="line"><span style="color:#E6EDF3">        })</span></span>
<span class="line"><span style="color:#FF7B72">        if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">response.ok) </span><span style="color:#FF7B72">throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'请求失败：HTTP '</span><span style="color:#FF7B72"> +</span><span style="color:#E6EDF3"> response.status)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> items</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> parseTasks</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">await</span><span style="color:#E6EDF3"> response.</span><span style="color:#D2A8FF">text</span><span style="color:#E6EDF3">())</span></span>
<span class="line"><span style="color:#FF7B72">        if</span><span style="color:#E6EDF3"> (active) </span><span style="color:#D2A8FF">setState</span><span style="color:#E6EDF3">({ query, status: </span><span style="color:#A5D6FF">'success'</span><span style="color:#E6EDF3">, items, error: </span><span style="color:#79C0FF">null</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#E6EDF3">      } </span><span style="color:#FF7B72">catch</span><span style="color:#E6EDF3"> (error) {</span></span>
<span class="line"><span style="color:#FF7B72">        if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">active) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#D2A8FF">        setState</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#E6EDF3">          query,</span></span>
<span class="line"><span style="color:#E6EDF3">          status: </span><span style="color:#A5D6FF">'error'</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">          items: [],</span></span>
<span class="line"><span style="color:#E6EDF3">          error: error </span><span style="color:#FF7B72">instanceof</span><span style="color:#FFA657"> Error</span><span style="color:#FF7B72"> ?</span><span style="color:#E6EDF3"> error.message </span><span style="color:#FF7B72">:</span><span style="color:#A5D6FF"> '请求失败，请稍后重试'</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">        })</span></span>
<span class="line"><span style="color:#E6EDF3">      }</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    void</span><span style="color:#D2A8FF"> load</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#E6EDF3"> () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">      active </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> false</span></span>
<span class="line"><span style="color:#E6EDF3">      controller.</span><span style="color:#D2A8FF">abort</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#E6EDF3">  }, [query, attempt])</span></span>
<span class="line"></span>
<span class="line"><span style="color:#8B949E">  // 新查询第一次渲染时，不展示上一轮查询的结果。</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> current</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> RemoteState</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> state.query </span><span style="color:#FF7B72">===</span><span style="color:#E6EDF3"> query </span><span style="color:#FF7B72">?</span><span style="color:#E6EDF3"> state </span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">    query,</span></span>
<span class="line"><span style="color:#E6EDF3">    status: </span><span style="color:#A5D6FF">'loading'</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    items: [],</span></span>
<span class="line"><span style="color:#E6EDF3">    error: </span><span style="color:#79C0FF">null</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> { </span><span style="color:#FF7B72">...</span><span style="color:#E6EDF3">current, </span><span style="color:#D2A8FF">reload</span><span style="color:#E6EDF3">: () </span><span style="color:#FF7B72">=></span><span style="color:#D2A8FF"> setAttempt</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">previous</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> previous </span><span style="color:#FF7B72">+</span><span style="color:#79C0FF"> 1</span><span style="color:#E6EDF3">) }</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>这里同时做了四件事：</p>
<ol>
<li>检查 <code>response.ok</code>。<code>fetch</code> 收到 HTTP 404、500 时，通常仍会正常返回 <code>Response</code>，不会自动进入 <code>catch</code>。</li>
<li>验证响应体，避免把结构不正确的 JSON 直接当任务渲染。</li>
<li>在依赖变化或卸载时取消请求，减少无用工作。</li>
<li>用当前 Effect 的 <code>active</code> 标记阻止旧结果回写，避免慢请求覆盖新查询。</li>
</ol>
<p>取消请求不能保证服务器撤销已经执行的操作。查询可以设计重试；创建订单、付款等写操作需要后端幂等设计，不能因为客户端超时就盲目重发。</p>
<h3>10.3 展示四种界面状态</h3>
<p><code>src/RemoteTaskDemo.tsx</code>，可选扩展文件：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useState } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useRemoteTasks } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './hooks/useRemoteTasks'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> default</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> RemoteTaskDemo</span><span style="color:#FFA657">() </span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">query</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setQuery</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">status</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">items</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">error</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">reload</span><span style="color:#E6EDF3"> } </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useRemoteTasks</span><span style="color:#E6EDF3">(query)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">section</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"board"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">>远程任务查询&#x3C;/</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        查询关键词</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">input</span><span style="color:#79C0FF"> value</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">query</span><span style="color:#FF7B72">}</span><span style="color:#79C0FF"> onChange</span><span style="color:#FF7B72">={</span><span style="color:#FFA657">event</span><span style="color:#FF7B72"> =></span><span style="color:#D2A8FF"> setQuery</span><span style="color:#E6EDF3">(event.target.value)</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3"> /></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">      {</span><span style="color:#E6EDF3">status </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'loading'</span><span style="color:#FF7B72"> &#x26;&#x26;</span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#79C0FF"> role</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"status"</span><span style="color:#E6EDF3">>正在加载……&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#FF7B72">      {</span><span style="color:#E6EDF3">status </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'error'</span><span style="color:#FF7B72"> &#x26;&#x26;</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">div</span><span style="color:#79C0FF"> role</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"alert"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">error</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"button"</span><span style="color:#79C0FF"> onClick</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">reload</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">>重试&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;/</span><span style="color:#7EE787">div</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      )</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#FF7B72">      {</span><span style="color:#E6EDF3">status </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'success'</span><span style="color:#FF7B72"> &#x26;&#x26;</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">        items.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ===</span><span style="color:#79C0FF"> 0</span></span>
<span class="line"><span style="color:#FF7B72">          ?</span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">>没有找到任务。&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#FF7B72">          :</span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">ul</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">items.</span><span style="color:#D2A8FF">map</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">li</span><span style="color:#79C0FF"> key</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">task.id</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">task.title</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">li</span><span style="color:#E6EDF3">>)</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">ul</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      )</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">section</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>可在 <code>main.tsx</code> 中导入它，并用 <code>&lt;RemoteTaskDemo /&gt;</code> 临时替换 <code>&lt;App /&gt;</code> 进行练习。加载、失败、成功但为空、成功且有数据应该明确区分，不能全都显示一个空列表。</p>
<p>这里每次输入变化都会请求，取消机制也不是防抖。希望停止输入一段时间后再请求，应单独加入防抖策略；需要缓存、请求去重、失效刷新或分页时，可以评估 TanStack Query、SWR 或框架的数据加载能力，先根据实际需求再选工具。</p>
<p>跨域报错应检查后端 CORS 或开发代理。<code>mode: 'no-cors'</code> 会让响应不可读，不能用它解决普通 JSON 接口的跨域问题。<code>VITE_</code> 前缀的环境变量会进入客户端代码，服务端 API 密钥不能放进去。<a href="https://vite.dev/guide/env-and-mode">官方：Vite 环境变量</a></p>
<h2>十一、状态复杂之后：useReducer 与 Context</h2>
<h3>11.1 useReducer 把更新规则集中起来</h3>
<p>只有几个简单操作时，基础版的 <code>useState</code> 已经足够。如果多个操作开始共享复杂规则，例如批量完成、恢复任务或撤销，可以把“怎样得到下一份状态”提取成 reducer。</p>
<p><code>src/taskReducer.ts</code>，可选扩展文件：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-ts"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#FF7B72"> type</span><span style="color:#E6EDF3"> { Task } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './tasks'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> type</span><span style="color:#FFA657"> TaskAction</span><span style="color:#FF7B72"> =</span></span>
<span class="line"><span style="color:#FF7B72">  |</span><span style="color:#E6EDF3"> { </span><span style="color:#FFA657">type</span><span style="color:#FF7B72">:</span><span style="color:#A5D6FF"> 'added'</span><span style="color:#E6EDF3">; </span><span style="color:#FFA657">task</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> Task</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"><span style="color:#FF7B72">  |</span><span style="color:#E6EDF3"> { </span><span style="color:#FFA657">type</span><span style="color:#FF7B72">:</span><span style="color:#A5D6FF"> 'toggled'</span><span style="color:#E6EDF3">; </span><span style="color:#FFA657">id</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"><span style="color:#FF7B72">  |</span><span style="color:#E6EDF3"> { </span><span style="color:#FFA657">type</span><span style="color:#FF7B72">:</span><span style="color:#A5D6FF"> 'renamed'</span><span style="color:#E6EDF3">; </span><span style="color:#FFA657">id</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">; </span><span style="color:#FFA657">title</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"><span style="color:#FF7B72">  |</span><span style="color:#E6EDF3"> { </span><span style="color:#FFA657">type</span><span style="color:#FF7B72">:</span><span style="color:#A5D6FF"> 'removed'</span><span style="color:#E6EDF3">; </span><span style="color:#FFA657">id</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> taskReducer</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">tasks</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> Task</span><span style="color:#E6EDF3">[], </span><span style="color:#FFA657">action</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> TaskAction</span><span style="color:#E6EDF3">)</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> Task</span><span style="color:#E6EDF3">[] {</span></span>
<span class="line"><span style="color:#FF7B72">  switch</span><span style="color:#E6EDF3"> (action.type) {</span></span>
<span class="line"><span style="color:#FF7B72">    case</span><span style="color:#A5D6FF"> 'added'</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#FF7B72">      return</span><span style="color:#E6EDF3"> [action.task, </span><span style="color:#FF7B72">...</span><span style="color:#E6EDF3">tasks]</span></span>
<span class="line"><span style="color:#FF7B72">    case</span><span style="color:#A5D6FF"> 'toggled'</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#FF7B72">      return</span><span style="color:#E6EDF3"> tasks.</span><span style="color:#D2A8FF">map</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span></span>
<span class="line"><span style="color:#E6EDF3">        task.id </span><span style="color:#FF7B72">===</span><span style="color:#E6EDF3"> action.id </span><span style="color:#FF7B72">?</span><span style="color:#E6EDF3"> { </span><span style="color:#FF7B72">...</span><span style="color:#E6EDF3">task, done: </span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">task.done } </span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> task</span></span>
<span class="line"><span style="color:#E6EDF3">      )</span></span>
<span class="line"><span style="color:#FF7B72">    case</span><span style="color:#A5D6FF"> 'renamed'</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#FF7B72">      return</span><span style="color:#E6EDF3"> tasks.</span><span style="color:#D2A8FF">map</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span></span>
<span class="line"><span style="color:#E6EDF3">        task.id </span><span style="color:#FF7B72">===</span><span style="color:#E6EDF3"> action.id </span><span style="color:#FF7B72">?</span><span style="color:#E6EDF3"> { </span><span style="color:#FF7B72">...</span><span style="color:#E6EDF3">task, title: action.title } </span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> task</span></span>
<span class="line"><span style="color:#E6EDF3">      )</span></span>
<span class="line"><span style="color:#FF7B72">    case</span><span style="color:#A5D6FF"> 'removed'</span><span style="color:#E6EDF3">:</span></span>
<span class="line"><span style="color:#FF7B72">      return</span><span style="color:#E6EDF3"> tasks.</span><span style="color:#D2A8FF">filter</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">task</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> task.id </span><span style="color:#FF7B72">!==</span><span style="color:#E6EDF3"> action.id)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>在 <code>useTasks</code> 中，任务 state 可以替换为下面的片段，并相应导入 <code>useReducer</code>、<code>taskReducer</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">tasks</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">dispatch</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useReducer</span><span style="color:#E6EDF3">(taskReducer, initial.tasks)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#8B949E">// 事件中完成 ID 生成、标题校验后，再分发动作。</span></span>
<span class="line"><span style="color:#D2A8FF">dispatch</span><span style="color:#E6EDF3">({ type: </span><span style="color:#A5D6FF">'added'</span><span style="color:#E6EDF3">, task })</span></span>
<span class="line"><span style="color:#D2A8FF">dispatch</span><span style="color:#E6EDF3">({ type: </span><span style="color:#A5D6FF">'toggled'</span><span style="color:#E6EDF3">, id })</span></span>
<span class="line"><span style="color:#D2A8FF">dispatch</span><span style="color:#E6EDF3">({ type: </span><span style="color:#A5D6FF">'renamed'</span><span style="color:#E6EDF3">, id, title })</span></span>
<span class="line"><span style="color:#D2A8FF">dispatch</span><span style="color:#E6EDF3">({ type: </span><span style="color:#A5D6FF">'removed'</span><span style="color:#E6EDF3">, id })</span></span>
</code></pre>
<p>这些 <code>dispatch</code> 分别替换对应事件中的 setter，不能在组件渲染时连续执行。持久化 Effect 保留，标题校验仍放在操作入口。</p>
<p>Reducer 接收状态和动作，返回新状态。它不发送请求、不写存储、不生成随机值，因此可以独立测试。<code>useReducer</code> 管理更新规则，不会自动让状态变成全局共享。<a href="https://react.dev/reference/react/useReducer">官方：useReducer</a></p>
<h3>11.2 Context 让较深层组件读取同一个状态</h3>
<p>如果接下来要增加任务详情页，页面之间需要访问同一份任务。先保留基础版的 <code>useTasks</code> 实现，再加下面两个文件。</p>
<p><code>src/task-store.ts</code>，可选扩展文件：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-ts"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { createContext, useContext } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#FF7B72"> type</span><span style="color:#E6EDF3"> { useTasks } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './hooks/useTasks'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">type</span><span style="color:#FFA657"> TaskStore</span><span style="color:#FF7B72"> =</span><span style="color:#FFA657"> ReturnType</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FF7B72">typeof</span><span style="color:#E6EDF3"> useTasks></span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> const</span><span style="color:#79C0FF"> TaskContext</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> createContext</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA657">TaskStore</span><span style="color:#FF7B72"> |</span><span style="color:#79C0FF"> null</span><span style="color:#E6EDF3">>(</span><span style="color:#79C0FF">null</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> useTaskStore</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> store</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> useContext</span><span style="color:#E6EDF3">(TaskContext)</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">store) </span><span style="color:#FF7B72">throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'useTaskStore 必须在 TaskProvider 内使用'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> store</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>src/TaskProvider.tsx</code>，可选扩展文件：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#FF7B72"> type</span><span style="color:#E6EDF3"> { ReactNode } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useTasks } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './hooks/useTasks'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { TaskContext } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './task-store'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> TaskProvider</span><span style="color:#E6EDF3">({ </span><span style="color:#FFA657">children</span><span style="color:#E6EDF3"> }</span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> { </span><span style="color:#FFA657">children</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> ReactNode</span><span style="color:#E6EDF3"> }) {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> store</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> useTasks</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">TaskContext.Provider</span><span style="color:#79C0FF"> value</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">store</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">children</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">TaskContext.Provider</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>然后对 <code>App.tsx</code> 做两处替换：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-diff"><span class="line"><span style="color:#FFA198">- import { useTasks } from './hooks/useTasks'</span></span>
<span class="line"><span style="color:#7EE787">+ import { useTaskStore } from './task-store'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FFA198">- const { tasks, storageError, addTask, toggleTask, renameTask, removeTask } = useTasks()</span></span>
<span class="line"><span style="color:#7EE787">+ const { tasks, storageError, addTask, toggleTask, renameTask, removeTask } = useTaskStore()</span></span>
</code></pre>
<p>最后在入口导入 <code>TaskProvider</code>，用 <code>&lt;TaskProvider&gt;&lt;App /&gt;&lt;/TaskProvider&gt;</code> 包裹页面。只有 Provider 调用 <code>useTasks()</code>，下面的页面通过 Context 读取它，数据才真正共享。</p>
<p>Context 负责传值。它不会自动提供精细订阅：Provider 的 <code>value</code> 改变时，读取该 Context 的组件会重新渲染。先按业务拆分 Context；确有高频更新和订阅粒度需求时，再评估状态库。<a href="https://react.dev/reference/react/useContext">官方：useContext</a></p>
<h2>十二、加入路由，完成多页面组织</h2>
<p>这一节依赖上一节的 Provider 改造。本文使用 React Router 的声明式模式，先安装依赖：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sh"><span class="line"><span style="color:#FFA657">npm</span><span style="color:#A5D6FF"> install</span><span style="color:#A5D6FF"> react-router</span></span>
</code></pre>
<p>这里按当前 React Router 官方文档从 <code>react-router</code> 导入相关 API。旧项目可能使用 <code>react-router-dom</code>，维护旧项目时先检查它的实际版本和现有模式。<a href="https://reactrouter.com/start/declarative/installation">官方：声明式模式安装</a></p>
<h3>12.1 路由表和动态参数</h3>
<p><code>src/RoutedApp.tsx</code>，可选扩展文件：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { Link, NavLink, Route, Routes, useParams } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react-router'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> App </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './App'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useTaskStore } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './task-store'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> TaskDetail</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">taskId</span><span style="color:#E6EDF3"> } </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useParams</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">tasks</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">storageError</span><span style="color:#E6EDF3"> } </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useTaskStore</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> task</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> tasks.</span><span style="color:#D2A8FF">find</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">item</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> item.id </span><span style="color:#FF7B72">===</span><span style="color:#E6EDF3"> taskId)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">main</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"board"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#FF7B72">      {</span><span style="color:#E6EDF3">storageError </span><span style="color:#FF7B72">&#x26;&#x26;</span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#79C0FF"> role</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"alert"</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">storageError</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#FF7B72">      {</span><span style="color:#E6EDF3">task </span><span style="color:#FF7B72">?</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">task.title</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">>状态：</span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">task.done </span><span style="color:#FF7B72">?</span><span style="color:#A5D6FF"> '已完成'</span><span style="color:#FF7B72"> :</span><span style="color:#A5D6FF"> '未完成'</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">>创建时间：</span><span style="color:#FF7B72">{new</span><span style="color:#D2A8FF"> Date</span><span style="color:#E6EDF3">(task.createdAt).</span><span style="color:#D2A8FF">toLocaleString</span><span style="color:#E6EDF3">()</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;/></span></span>
<span class="line"><span style="color:#E6EDF3">      ) </span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">>没有找到这项任务&#x3C;/</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      )</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">Link</span><span style="color:#79C0FF"> to</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"/"</span><span style="color:#E6EDF3">>返回任务看板&#x3C;/</span><span style="color:#7EE787">Link</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">main</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> default</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> RoutedApp</span><span style="color:#FFA657">() </span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">nav</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"board actions"</span><span style="color:#79C0FF"> aria-label</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"主导航"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">NavLink</span><span style="color:#79C0FF"> to</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"/"</span><span style="color:#79C0FF"> end</span><span style="color:#E6EDF3">>任务看板&#x3C;/</span><span style="color:#7EE787">NavLink</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">NavLink</span><span style="color:#79C0FF"> to</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"/about"</span><span style="color:#E6EDF3">>关于&#x3C;/</span><span style="color:#7EE787">NavLink</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">nav</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">Routes</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">Route</span><span style="color:#79C0FF"> path</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"/"</span><span style="color:#79C0FF"> element</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#7EE787">App</span><span style="color:#E6EDF3"> /></span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3"> /></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">Route</span><span style="color:#79C0FF"> path</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"/tasks/:taskId"</span><span style="color:#79C0FF"> element</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#7EE787">TaskDetail</span><span style="color:#E6EDF3"> /></span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3"> /></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">Route</span></span>
<span class="line"><span style="color:#79C0FF">          path</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"/about"</span></span>
<span class="line"><span style="color:#79C0FF">          element</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#7EE787">main</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"board"</span><span style="color:#E6EDF3">>&#x3C;</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">>关于&#x3C;/</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">>&#x3C;</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">>一个 React 学习项目。&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">>&#x3C;/</span><span style="color:#7EE787">main</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">        /></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">Route</span></span>
<span class="line"><span style="color:#79C0FF">          path</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"*"</span></span>
<span class="line"><span style="color:#79C0FF">          element</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#7EE787">main</span><span style="color:#79C0FF"> className</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"board"</span><span style="color:#E6EDF3">>&#x3C;</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">>页面不存在&#x3C;/</span><span style="color:#7EE787">h1</span><span style="color:#E6EDF3">>&#x3C;</span><span style="color:#7EE787">Link</span><span style="color:#79C0FF"> to</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"/"</span><span style="color:#E6EDF3">>返回首页&#x3C;/</span><span style="color:#7EE787">Link</span><span style="color:#E6EDF3">>&#x3C;/</span><span style="color:#7EE787">main</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">        /></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">Routes</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>将 <code>src/main.tsx</code> <strong>替换</strong>为下面的路由版入口，不要同时保留两次 <code>createRoot</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { StrictMode } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { createRoot } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react-dom/client'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { BrowserRouter } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react-router'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> RoutedApp </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './RoutedApp'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { TaskProvider } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './TaskProvider'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#A5D6FF"> './index.css'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> rootElement</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> document.</span><span style="color:#D2A8FF">getElementById</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'root'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">rootElement) </span><span style="color:#FF7B72">throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'缺少 root 挂载节点'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">createRoot</span><span style="color:#E6EDF3">(rootElement).</span><span style="color:#D2A8FF">render</span><span style="color:#E6EDF3">(</span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#7EE787">StrictMode</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">BrowserRouter</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">TaskProvider</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">RoutedApp</span><span style="color:#E6EDF3"> /></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">TaskProvider</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">BrowserRouter</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;/</span><span style="color:#7EE787">StrictMode</span><span style="color:#E6EDF3">>,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p>在 <code>TaskList.tsx</code> 中导入 <code>Link</code>，然后在非编辑状态的操作区增加这个片段：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#E6EDF3">&#x3C;</span><span style="color:#7EE787">Link</span><span style="color:#79C0FF"> to</span><span style="color:#FF7B72">={</span><span style="color:#A5D6FF">'/tasks/'</span><span style="color:#FF7B72"> +</span><span style="color:#D2A8FF"> encodeURIComponent</span><span style="color:#E6EDF3">(task.id)</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">>详情&#x3C;/</span><span style="color:#7EE787">Link</span><span style="color:#E6EDF3">></span></span>
</code></pre>
<p><code>Link</code> 负责应用内导航；<code>NavLink</code> 可以表达当前导航状态；<code>useParams</code> 读取动态路径参数。Provider 位于路由页面之上，因此切换到关于页再返回时，任务状态仍由同一个实例持有。</p>
<p>这里的任务只存在当前浏览器。把详情链接发给别人，对方没有对应本地数据，看到“没有找到”是预期行为。需要可分享的数据，就应使用后端存储。</p>
<h3>12.2 URL 状态和刷新 404</h3>
<p>希望复制链接后保留搜索、筛选、页码，可以用 <code>useSearchParams</code> 把它们写入 URL，例如 <code>/?status=active&amp;q=react</code>。同一份筛选条件应尽量由 URL 统一驱动，不要再维护一份互相同步的 state。</p>
<p><code>BrowserRouter</code> 使用浏览器 History API。生产环境直接刷新 <code>/tasks/某个ID</code> 时，服务器必须能回退到 <code>index.html</code>。例如静态站点的 Nginx 页面规则通常包含：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-nginx"><span class="line"><span style="color:#FF7B72">location</span><span style="color:#FFA657"> / </span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#FF7B72">    try_files </span><span style="color:#E6EDF3">$uri $uri/ /index.html;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>这个片段只说明页面回退。真实接口 <code>/api/</code> 和静态资源应按部署环境单独配置，接口不存在时不能被回退成一份 HTTP 200 的 HTML。部署到子路径时，还要协调 Vite 的 <code>base</code>、路由的 <code>basename</code> 和服务器路径。</p>
<h2>十三、给核心行为补上测试</h2>
<p>先测试独立的数据规则，再从用户视角测试表单与列表。不需要断言每个组件调用了多少次 Hook，也不必为每行 JSX 写快照。</p>
<p>以下测试针对<strong>第九节完成的基础版本</strong>。如果已经切换到 Context，组件测试要用 Provider 包裹；如果子组件已经包含 <code>Link</code> 等路由组件，即使只测试 App，也需要提供路由上下文。</p>
<h3>13.1 安装与配置</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sh"><span class="line"><span style="color:#FFA657">npm</span><span style="color:#A5D6FF"> install</span><span style="color:#79C0FF"> -D</span><span style="color:#A5D6FF"> vitest</span><span style="color:#A5D6FF"> jsdom</span><span style="color:#A5D6FF"> @testing-library/react</span><span style="color:#A5D6FF"> @testing-library/user-event</span><span style="color:#A5D6FF"> @testing-library/jest-dom</span></span>
</code></pre>
<p>测试工具也有独立的 Node.js 和 Vite 版本要求。这里应在前面新建的项目中安装，旧项目接入前先核对兼容性。<a href="https://vitest.dev/guide/">官方：Vitest 起步</a></p>
<p>用下面的内容替换 <code>vite.config.ts</code>，保留 React 插件，并加入测试环境配置：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-ts"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { defineConfig } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'vitest/config'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> react </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> '@vitejs/plugin-react'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> default</span><span style="color:#D2A8FF"> defineConfig</span><span style="color:#FFA657">({</span></span>
<span class="line"><span style="color:#E6EDF3">  plugins: [</span><span style="color:#D2A8FF">react</span><span style="color:#E6EDF3">()]</span><span style="color:#FFA657">,</span></span>
<span class="line"><span style="color:#E6EDF3">  test: {</span></span>
<span class="line"><span style="color:#E6EDF3">    environment: </span><span style="color:#A5D6FF">'jsdom'</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    setupFiles: </span><span style="color:#A5D6FF">'./src/test/setup.ts'</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span><span style="color:#FFA657">,</span></span>
<span class="line"><span style="color:#FFA657">})</span></span>
</code></pre>
<p><code>src/test/setup.ts</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-ts"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#A5D6FF"> '@testing-library/jest-dom/vitest'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { cleanup } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> '@testing-library/react'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { afterEach, vi } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'vitest'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">afterEach</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#D2A8FF">  cleanup</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#E6EDF3">  vi.</span><span style="color:#D2A8FF">restoreAllMocks</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
</code></pre>
<p>显式清理测试挂载的组件和 mock，避免一个用例留下的界面、Effect 或存储替身影响下一个。</p>
<h3>13.2 测试数据校验和筛选</h3>
<p><code>src/tasks.test.ts</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-ts"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { describe, expect, it } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'vitest'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { filterTasks, parseTasks, </span><span style="color:#FF7B72">type</span><span style="color:#E6EDF3"> Task } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './tasks'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> tasks</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> Task</span><span style="color:#E6EDF3">[] </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> [</span></span>
<span class="line"><span style="color:#E6EDF3">  { id: </span><span style="color:#A5D6FF">'1'</span><span style="color:#E6EDF3">, title: </span><span style="color:#A5D6FF">'学习 React'</span><span style="color:#E6EDF3">, done: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3">, createdAt: </span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3"> },</span></span>
<span class="line"><span style="color:#E6EDF3">  { id: </span><span style="color:#A5D6FF">'2'</span><span style="color:#E6EDF3">, title: </span><span style="color:#A5D6FF">'完成 TypeScript 练习'</span><span style="color:#E6EDF3">, done: </span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">, createdAt: </span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3"> },</span></span>
<span class="line"><span style="color:#E6EDF3">]</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">describe</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'任务数据'</span><span style="color:#E6EDF3">, () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#D2A8FF">  it</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'缓存不存在时返回空列表，合法数据可以恢复'</span><span style="color:#E6EDF3">, () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#D2A8FF">    expect</span><span style="color:#E6EDF3">(</span><span style="color:#D2A8FF">parseTasks</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">null</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toEqual</span><span style="color:#E6EDF3">([])</span></span>
<span class="line"><span style="color:#D2A8FF">    expect</span><span style="color:#E6EDF3">(</span><span style="color:#D2A8FF">parseTasks</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">JSON</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">stringify</span><span style="color:#E6EDF3">(tasks))).</span><span style="color:#D2A8FF">toEqual</span><span style="color:#E6EDF3">(tasks)</span></span>
<span class="line"><span style="color:#E6EDF3">  })</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  it</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'拒绝损坏 JSON、错误字段和重复 ID'</span><span style="color:#E6EDF3">, () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#D2A8FF">    expect</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#D2A8FF"> parseTasks</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'{broken'</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toThrow</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#D2A8FF">    expect</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#D2A8FF"> parseTasks</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'[{"id":"1"}]'</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toThrow</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#D2A8FF">    expect</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#D2A8FF"> parseTasks</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">JSON</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">stringify</span><span style="color:#E6EDF3">([tasks[</span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">], tasks[</span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">]]))).</span><span style="color:#D2A8FF">toThrow</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#E6EDF3">  })</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  it</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'组合状态与关键词筛选，不修改原数组'</span><span style="color:#E6EDF3">, () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> before</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> structuredClone</span><span style="color:#E6EDF3">(tasks)</span></span>
<span class="line"><span style="color:#D2A8FF">    expect</span><span style="color:#E6EDF3">(</span><span style="color:#D2A8FF">filterTasks</span><span style="color:#E6EDF3">(tasks, </span><span style="color:#A5D6FF">'active'</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">' react '</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toEqual</span><span style="color:#E6EDF3">([tasks[</span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">]])</span></span>
<span class="line"><span style="color:#D2A8FF">    expect</span><span style="color:#E6EDF3">(</span><span style="color:#D2A8FF">filterTasks</span><span style="color:#E6EDF3">(tasks, </span><span style="color:#A5D6FF">'completed'</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toEqual</span><span style="color:#E6EDF3">([tasks[</span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">]])</span></span>
<span class="line"><span style="color:#D2A8FF">    expect</span><span style="color:#E6EDF3">(</span><span style="color:#D2A8FF">filterTasks</span><span style="color:#E6EDF3">(tasks, </span><span style="color:#A5D6FF">'completed'</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'React'</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toEqual</span><span style="color:#E6EDF3">([])</span></span>
<span class="line"><span style="color:#D2A8FF">    expect</span><span style="color:#E6EDF3">(tasks).</span><span style="color:#D2A8FF">toEqual</span><span style="color:#E6EDF3">(before)</span></span>
<span class="line"><span style="color:#E6EDF3">  })</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
</code></pre>
<h3>13.3 测试完整用户操作与存储异常</h3>
<p><code>src/App.test.tsx</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { StrictMode } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { render, screen, within } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> '@testing-library/react'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> userEvent </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> '@testing-library/user-event'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { beforeEach, expect, test, vi } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'vitest'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> App </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './App'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { STORAGE_KEY } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './storage'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">beforeEach</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> window.localStorage.</span><span style="color:#D2A8FF">clear</span><span style="color:#E6EDF3">())</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> renderApp</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#D2A8FF"> render</span><span style="color:#E6EDF3">(&#x3C;</span><span style="color:#7EE787">StrictMode</span><span style="color:#E6EDF3">>&#x3C;</span><span style="color:#7EE787">App</span><span style="color:#E6EDF3"> />&#x3C;/</span><span style="color:#7EE787">StrictMode</span><span style="color:#E6EDF3">>)</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">test</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'添加、筛选、编辑、恢复与删除任务'</span><span style="color:#E6EDF3">, </span><span style="color:#FF7B72">async</span><span style="color:#E6EDF3"> () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> user</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> userEvent.</span><span style="color:#D2A8FF">setup</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> view</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> renderApp</span><span style="color:#E6EDF3">()</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">type</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByLabelText</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'新任务'</span><span style="color:#E6EDF3">), </span><span style="color:#A5D6FF">'学习 React'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">click</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'button'</span><span style="color:#E6EDF3">, { name: </span><span style="color:#A5D6FF">'添加任务'</span><span style="color:#E6EDF3"> }))</span></span>
<span class="line"><span style="color:#D2A8FF">  expect</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'status'</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toHaveTextContent</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'未完成 1 项'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">click</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'checkbox'</span><span style="color:#E6EDF3">, { name: </span><span style="color:#A5D6FF">'学习 React'</span><span style="color:#E6EDF3"> }))</span></span>
<span class="line"><span style="color:#D2A8FF">  expect</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'status'</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toHaveTextContent</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'已完成 1 项'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">selectOptions</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByLabelText</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'任务状态'</span><span style="color:#E6EDF3">), </span><span style="color:#A5D6FF">'active'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#D2A8FF">  expect</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByText</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'没有符合当前条件的任务。'</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toBeInTheDocument</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">selectOptions</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByLabelText</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'任务状态'</span><span style="color:#E6EDF3">), </span><span style="color:#A5D6FF">'all'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">type</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'searchbox'</span><span style="color:#E6EDF3">, { name: </span><span style="color:#A5D6FF">'搜索任务'</span><span style="color:#E6EDF3"> }), </span><span style="color:#A5D6FF">'不存在'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#D2A8FF">  expect</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByText</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'没有符合当前条件的任务。'</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toBeInTheDocument</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">clear</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'searchbox'</span><span style="color:#E6EDF3">, { name: </span><span style="color:#A5D6FF">'搜索任务'</span><span style="color:#E6EDF3"> }))</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> row</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'listitem'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">click</span><span style="color:#E6EDF3">(</span><span style="color:#D2A8FF">within</span><span style="color:#E6EDF3">(row).</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'button'</span><span style="color:#E6EDF3">, { name: </span><span style="color:#A5D6FF">'编辑'</span><span style="color:#E6EDF3"> }))</span></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">clear</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByLabelText</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'任务标题'</span><span style="color:#E6EDF3">))</span></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">type</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByLabelText</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'任务标题'</span><span style="color:#E6EDF3">), </span><span style="color:#A5D6FF">'读完官方文档'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">click</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'button'</span><span style="color:#E6EDF3">, { name: </span><span style="color:#A5D6FF">'保存'</span><span style="color:#E6EDF3"> }))</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">  view.</span><span style="color:#D2A8FF">unmount</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#D2A8FF">  renderApp</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#D2A8FF">  expect</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'checkbox'</span><span style="color:#E6EDF3">, { name: </span><span style="color:#A5D6FF">'读完官方文档'</span><span style="color:#E6EDF3"> })).</span><span style="color:#D2A8FF">toBeChecked</span><span style="color:#E6EDF3">()</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">click</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'button'</span><span style="color:#E6EDF3">, { name: </span><span style="color:#A5D6FF">'删除'</span><span style="color:#E6EDF3"> }))</span></span>
<span class="line"><span style="color:#D2A8FF">  expect</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByText</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'还没有任务，先添加一项吧。'</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toBeInTheDocument</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#D2A8FF">  expect</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">JSON</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">parse</span><span style="color:#E6EDF3">(window.localStorage.</span><span style="color:#D2A8FF">getItem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">STORAGE_KEY</span><span style="color:#E6EDF3">)</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toEqual</span><span style="color:#E6EDF3">([])</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">test</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'损坏缓存不会被打开页面或新增任务覆盖'</span><span style="color:#E6EDF3">, </span><span style="color:#FF7B72">async</span><span style="color:#E6EDF3"> () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">  window.localStorage.</span><span style="color:#D2A8FF">setItem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">STORAGE_KEY</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'{broken'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> user</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> userEvent.</span><span style="color:#D2A8FF">setup</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#D2A8FF">  renderApp</span><span style="color:#E6EDF3">()</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  expect</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'alert'</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toHaveTextContent</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'原缓存未覆盖'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">type</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByLabelText</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'新任务'</span><span style="color:#E6EDF3">), </span><span style="color:#A5D6FF">'临时任务'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">click</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'button'</span><span style="color:#E6EDF3">, { name: </span><span style="color:#A5D6FF">'添加任务'</span><span style="color:#E6EDF3"> }))</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  expect</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'checkbox'</span><span style="color:#E6EDF3">, { name: </span><span style="color:#A5D6FF">'临时任务'</span><span style="color:#E6EDF3"> })).</span><span style="color:#D2A8FF">toBeInTheDocument</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#D2A8FF">  expect</span><span style="color:#E6EDF3">(window.localStorage.</span><span style="color:#D2A8FF">getItem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">STORAGE_KEY</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toBe</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'{broken'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">test</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'写入失败时显示提示，内存中的任务仍可使用'</span><span style="color:#E6EDF3">, </span><span style="color:#FF7B72">async</span><span style="color:#E6EDF3"> () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">  vi.</span><span style="color:#D2A8FF">spyOn</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">Storage</span><span style="color:#E6EDF3">.</span><span style="color:#79C0FF">prototype</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'setItem'</span><span style="color:#E6EDF3">).</span><span style="color:#D2A8FF">mockImplementation</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> DOMException</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'空间不足'</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'QuotaExceededError'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  })</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> user</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> userEvent.</span><span style="color:#D2A8FF">setup</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#D2A8FF">  renderApp</span><span style="color:#E6EDF3">()</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">type</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByLabelText</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'新任务'</span><span style="color:#E6EDF3">), </span><span style="color:#A5D6FF">'尚未保存的任务'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  await</span><span style="color:#E6EDF3"> user.</span><span style="color:#D2A8FF">click</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'button'</span><span style="color:#E6EDF3">, { name: </span><span style="color:#A5D6FF">'添加任务'</span><span style="color:#E6EDF3"> }))</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  expect</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'alert'</span><span style="color:#E6EDF3">)).</span><span style="color:#D2A8FF">toHaveTextContent</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'保存失败'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#D2A8FF">  expect</span><span style="color:#E6EDF3">(screen.</span><span style="color:#D2A8FF">getByRole</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'checkbox'</span><span style="color:#E6EDF3">, { name: </span><span style="color:#A5D6FF">'尚未保存的任务'</span><span style="color:#E6EDF3"> })).</span><span style="color:#D2A8FF">toBeInTheDocument</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
</code></pre>
<p>如果已经完成第十二节，测试文件还需导入 <code>MemoryRouter</code> 和 <code>TaskProvider</code>，并将上面的 <code>renderApp</code> 替换为路由版包装：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { MemoryRouter } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react-router'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { TaskProvider } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> './TaskProvider'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> renderApp</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#D2A8FF"> render</span><span style="color:#E6EDF3">(</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">StrictMode</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">MemoryRouter</span><span style="color:#79C0FF"> initialEntries</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">[</span><span style="color:#A5D6FF">'/'</span><span style="color:#E6EDF3">]</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">TaskProvider</span><span style="color:#E6EDF3">>&#x3C;</span><span style="color:#7EE787">App</span><span style="color:#E6EDF3"> />&#x3C;/</span><span style="color:#7EE787">TaskProvider</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">MemoryRouter</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">StrictMode</span><span style="color:#E6EDF3">>,</span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>运行：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sh"><span class="line"><span style="color:#FFA657">npx</span><span style="color:#A5D6FF"> vitest</span><span style="color:#A5D6FF"> run</span></span>
<span class="line"><span style="color:#FFA657">npm</span><span style="color:#A5D6FF"> run</span><span style="color:#A5D6FF"> build</span></span>
</code></pre>
<p>Vite 的 React TypeScript 模板通常在 <code>build</code> 脚本中先执行 <code>tsc -b</code>，再执行 <code>vite build</code>，可在 <code>package.json</code> 核实。还应运行模板提供的 <code>npm run lint</code>，并检查项目是否启用了 Hooks 调用位置与依赖数组规则；不同模板的默认检查范围可能不同。</p>
<p>这些测试验证数据规则和 DOM 行为。jsdom 不会真实计算浏览器布局，不能证明手机上没有溢出，也不能代替真实浏览器中的路由刷新和键盘操作验收。</p>
<h2>十四、性能优化：先定位，再选择工具</h2>
<h3>14.1 区分计算、渲染、网络与布局</h3>
<p>任务只有几十条时，直接 <code>filter</code> 通常足够。列表慢了以后，先使用 React DevTools 的性能分析能力和浏览器工具观察，再判断瓶颈。</p>
<table>
<thead>
<tr>
<th>现象</th>
<th>优先检查</th>
<th>可能的改进</th>
</tr>
</thead>
<tbody>
<tr>
<td>每次输入都执行很重的筛选</td>
<td>计算规模与重复工作</td>
<td>预处理数据，必要时使用 <code>useMemo</code></td>
</tr>
<tr>
<td>无关区域频繁渲染且开销明显</td>
<td>状态位置、Context 更新范围</td>
<td>下移状态、拆分 Context，测量后使用 <code>memo</code></td>
</tr>
<tr>
<td>长列表卡顿</td>
<td>DOM 数量、单项复杂度</td>
<td>分页或虚拟列表</td>
</tr>
<tr>
<td>打开页面下载太多代码</td>
<td>首屏依赖与路由资源</td>
<td>路由拆分、按需加载</td>
</tr>
<tr>
<td>输入时网络请求密集</td>
<td>查询触发方式与缓存</td>
<td>防抖、请求去重、查询缓存</td>
</tr>
<tr>
<td>切换页面后仍有活动</td>
<td>定时器、订阅、请求清理</td>
<td>卸载时取消，必要时在后台暂停</td>
</tr>
</tbody>
</table>
<h3>14.2 useMemo、useCallback 和 memo 分别缓存什么？</h3>
<ul>
<li><code>useMemo</code> 缓存一次计算的结果，依赖改变后重新计算。</li>
<li><code>useCallback</code> 缓存函数引用，不会自动让函数内部执行更快。</li>
<li><code>memo</code> 可以在 Props 未改变时跳过部分组件渲染；组件自身 state、读取的 Context 等更新仍可能触发渲染。</li>
</ul>
<p>例如，筛选确实昂贵时，可以把 App 中的计算替换成这个片段，并导入 <code>useMemo</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> visibleTasks</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> useMemo</span><span style="color:#E6EDF3">(</span></span>
<span class="line"><span style="color:#E6EDF3">  () </span><span style="color:#FF7B72">=></span><span style="color:#D2A8FF"> filterTasks</span><span style="color:#E6EDF3">(tasks, filter, query),</span></span>
<span class="line"><span style="color:#E6EDF3">  [tasks, filter, query],</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p>如果传给一个 <code>memo</code> 子组件的对象或函数每次都重新创建，默认的 Props 比较仍会认为它改变了。但不要因此给所有变量都套缓存；先判断跳过的工作是否值得增加维护成本。</p>
<p>React Compiler 可以在构建时自动优化部分组件、值和函数。它需要相应工具配置，不能因为安装 React 19 就假定已经启用；也不能修复错误的依赖、可变数据或副作用。<a href="https://react.dev/learn/react-compiler/introduction">官方：React Compiler 简介</a></p>
<h3>14.3 延后渲染不等于防抖</h3>
<p>当输入反馈需要保持灵敏，而结果区域很重时，可以评估 <code>useDeferredValue</code>，让结果使用延后的查询值；使用 <code>useTransition</code> 可以把某些更新标记为非紧急更新。</p>
<p>这两种机制都不会让重计算本身凭空变快，也不等于“等 300ms 再请求”。受控输入自身的值应该及时更新，不要直接把控制输入的更新放进 Transition。需要减少请求次数，仍然应设计防抖或缓存。<a href="https://react.dev/reference/react/useDeferredValue">官方：useDeferredValue</a>、<a href="https://react.dev/reference/react/useTransition">useTransition</a></p>
<h3>14.4 lazy 与 Suspense</h3>
<p>假设已经添加第十节的 <code>RemoteTaskDemo.tsx</code>，可以创建一个按需加载的包装组件：</p>
<p><code>src/LazyRemoteDemo.tsx</code>，可选扩展文件：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { lazy, Suspense } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> RemoteTaskDemo</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> lazy</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#FF7B72"> import</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'./RemoteTaskDemo'</span><span style="color:#E6EDF3">))</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> default</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> LazyRemoteDemo</span><span style="color:#FFA657">() </span><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">Suspense</span><span style="color:#79C0FF"> fallback</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#7EE787">p</span><span style="color:#79C0FF"> role</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"status"</span><span style="color:#E6EDF3">>正在加载页面代码……&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">RemoteTaskDemo</span><span style="color:#E6EDF3"> /></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">Suspense</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>lazy</code> 放在组件外层，导入目标需要提供对应的默认组件导出。这里的 Suspense 等待页面模块加载；<code>RemoteTaskDemo</code> 中用 Effect 发起的普通 <code>fetch</code> 仍由它自己的 loading 状态管理，不能仅靠套一个 Suspense 就自动接管请求。<a href="https://react.dev/reference/react/Suspense">官方：Suspense</a></p>
<p>加载失败和渲染异常还需要合适的错误边界。错误边界主要处理子树的渲染等错误，不会替你捕获所有事件回调或普通异步请求错误；请求失败仍应在数据逻辑中处理。实际项目可以使用框架提供的路由错误边界，或按 React 的错误边界 API 实现。<a href="https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary">官方：捕获渲染错误</a></p>
<h2>十五、认识 React 19 的表单与服务端边界</h2>
<h3>15.1 用 useActionState 管理异步提交</h3>
<p>前面的同步本地表单使用 <code>onSubmit + useState</code> 很直观。接入异步保存后，需要处理等待、失败和重复提交，React 19 的表单 Action 与 <code>useActionState</code> 可以帮助组织这些状态。</p>
<p><code>src/AsyncTaskForm.tsx</code>，可选扩展文件：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-tsx"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { useActionState, useState } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'react'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">type</span><span style="color:#FFA657"> FormState</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> { </span><span style="color:#FFA657">error</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#FF7B72"> |</span><span style="color:#79C0FF"> null</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"><span style="color:#FF7B72">type</span><span style="color:#FFA657"> AsyncTaskFormProps</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> { </span><span style="color:#D2A8FF">onCreate</span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> (</span><span style="color:#FFA657">title</span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> string</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#FFA657"> Promise</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#79C0FF">void</span><span style="color:#E6EDF3">> }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">export</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> AsyncTaskForm</span><span style="color:#E6EDF3">({ </span><span style="color:#FFA657">onCreate</span><span style="color:#E6EDF3"> }</span><span style="color:#FF7B72">:</span><span style="color:#FFA657"> AsyncTaskFormProps</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">title</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">setTitle</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useState</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#E6EDF3"> [</span><span style="color:#79C0FF">state</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">formAction</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">pending</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> useActionState</span><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA657">FormState</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">FormData</span><span style="color:#E6EDF3">>(</span></span>
<span class="line"><span style="color:#FF7B72">    async</span><span style="color:#E6EDF3"> (</span><span style="color:#FFA657">_previous</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">formData</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">      const</span><span style="color:#79C0FF"> value</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> formData.</span><span style="color:#D2A8FF">get</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'title'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">typeof</span><span style="color:#E6EDF3"> value </span><span style="color:#FF7B72">!==</span><span style="color:#A5D6FF"> 'string'</span><span style="color:#FF7B72"> ||</span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">value.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">() </span><span style="color:#FF7B72">||</span><span style="color:#E6EDF3"> value.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">().</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#79C0FF"> 80</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">        return</span><span style="color:#E6EDF3"> { error: </span><span style="color:#A5D6FF">'请输入 1 到 80 个字符的任务标题'</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"><span style="color:#E6EDF3">      }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">      try</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">        await</span><span style="color:#D2A8FF"> onCreate</span><span style="color:#E6EDF3">(value.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">())</span></span>
<span class="line"><span style="color:#D2A8FF">        setTitle</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">        return</span><span style="color:#E6EDF3"> { error: </span><span style="color:#79C0FF">null</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"><span style="color:#E6EDF3">      } </span><span style="color:#FF7B72">catch</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">        return</span><span style="color:#E6EDF3"> { error: </span><span style="color:#A5D6FF">'保存失败，请稍后重试'</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"><span style="color:#E6EDF3">      }</span></span>
<span class="line"><span style="color:#E6EDF3">    },</span></span>
<span class="line"><span style="color:#E6EDF3">    { error: </span><span style="color:#79C0FF">null</span><span style="color:#E6EDF3"> },</span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">form</span><span style="color:#79C0FF"> action</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">formAction</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        新任务</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#7EE787">input</span></span>
<span class="line"><span style="color:#79C0FF">          name</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"title"</span></span>
<span class="line"><span style="color:#79C0FF">          value</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">title</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">          onChange</span><span style="color:#FF7B72">={</span><span style="color:#FFA657">event</span><span style="color:#FF7B72"> =></span><span style="color:#D2A8FF"> setTitle</span><span style="color:#E6EDF3">(event.target.value)</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">          maxLength</span><span style="color:#FF7B72">={</span><span style="color:#79C0FF">80</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#79C0FF">          required</span></span>
<span class="line"><span style="color:#79C0FF">          disabled</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">pending</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">        /></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> type</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"submit"</span><span style="color:#79C0FF"> disabled</span><span style="color:#FF7B72">={</span><span style="color:#E6EDF3">pending </span><span style="color:#FF7B72">||</span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">title.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">()</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#FF7B72">        {</span><span style="color:#E6EDF3">pending </span><span style="color:#FF7B72">?</span><span style="color:#A5D6FF"> '正在保存……'</span><span style="color:#FF7B72"> :</span><span style="color:#A5D6FF"> '添加任务'</span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#FF7B72">      {</span><span style="color:#E6EDF3">state.error </span><span style="color:#FF7B72">&#x26;&#x26;</span><span style="color:#E6EDF3"> &#x3C;</span><span style="color:#7EE787">p</span><span style="color:#79C0FF"> role</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"alert"</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">{</span><span style="color:#E6EDF3">state.error</span><span style="color:#FF7B72">}</span><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#7EE787">p</span><span style="color:#E6EDF3">></span><span style="color:#FF7B72">}</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">form</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  )</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>父组件传入真正的异步 <code>onCreate</code>：完成后 resolve，失败时 reject。<code>formAction</code> 交给 <code>form</code> 的 <code>action</code>，React 会在相应的 Action 上下文中调用它；<code>pending</code> 反映提交状态。</p>
<p>输入框使用受控值，只有保存成功才清空，失败时保留草稿。使用非受控输入时，还需要理解 Action 成功后 React 对表单的自动重置行为。不要把这个示例和基础表单一起挂载后误以为它们会自动共享状态。<a href="https://react.dev/reference/react/useActionState">官方：useActionState</a>、<a href="https://react.dev/reference/react-dom/components/form">表单 Action</a></p>
<p><code>useFormStatus</code> 可以让表单内部的子组件读取最近父表单的提交状态；<code>useOptimistic</code> 可以在异步操作完成前先显示临时结果。乐观更新需要设计失败恢复与并发顺序，不能只把界面提前改掉就算完成。</p>
<h3>15.2 CSR、SSR 与 Server Components 的区别</h3>
<table>
<thead>
<tr>
<th>概念</th>
<th>主要解决什么</th>
</tr>
</thead>
<tbody>
<tr>
<td>CSR，客户端渲染</td>
<td>浏览器执行 JavaScript，构建和更新界面；本文 Vite 项目采用此方式</td>
</tr>
<tr>
<td>SSR，服务端渲染</td>
<td>服务器先生成 HTML，客户端再通过 hydration 接管交互</td>
</tr>
<tr>
<td>React Server Components</td>
<td>在支持的服务端或构建环境执行组件，组织服务端数据与组件输出，并与客户端组件组合</td>
</tr>
</tbody>
</table>
<p>SSR 与 Server Components 可以配合，但不是同一个概念。服务端组件不能直接使用浏览器 DOM、客户端 state 或 Effect；交互部分需要放在相应的客户端组件边界内。</p>
<p>普通 Vite React 项目不会因为写了 <code>'use server'</code> 就自动拥有服务器、鉴权和数据库连接。Server Functions 等能力需要相应框架和运行环境支持；无论采用哪种方案，身份检查、参数校验和密钥访问都必须留在可信的服务端边界。<a href="https://react.dev/reference/rsc/server-components">官方：Server Components</a>、<a href="https://react.dev/reference/rsc/server-functions">Server Functions</a></p>
<p>学习顺序可以是先完成本文的客户端应用，再用一个支持 SSR 和服务端组件的框架实现相同功能，对照数据在什么环境执行、何时传到浏览器。</p>
<h2>十六、构建与上线前检查</h2>
<h3>16.1 构建产物和本地预览</h3>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sh"><span class="line"><span style="color:#FFA657">npx</span><span style="color:#A5D6FF"> vitest</span><span style="color:#A5D6FF"> run</span></span>
<span class="line"><span style="color:#FFA657">npm</span><span style="color:#A5D6FF"> run</span><span style="color:#A5D6FF"> lint</span></span>
<span class="line"><span style="color:#FFA657">npm</span><span style="color:#A5D6FF"> run</span><span style="color:#A5D6FF"> build</span></span>
<span class="line"><span style="color:#FFA657">npm</span><span style="color:#A5D6FF"> run</span><span style="color:#A5D6FF"> preview</span></span>
</code></pre>
<p>构建产物通常位于 <code>dist/</code>。<code>preview</code> 用于本地检查构建结果，不能直接当作正式生产服务器。</p>
<p>上线前使用构建后的页面检查：</p>
<ol>
<li><strong>主要流程</strong>：增删改查、筛选、刷新恢复，异常提示不阻塞继续操作。</li>
<li><strong>路由</strong>：直接打开详情、刷新详情、不存在的地址、返回上一页。</li>
<li><strong>网络</strong>：离线、超时、HTTP 错误、无效 JSON，快速切换查询后不显示旧结果。</li>
<li><strong>布局</strong>：窄屏、长标题、放大文字后不截断主要操作，列表不横向撑开。</li>
<li><strong>键盘与标签</strong>：Tab 顺序合理，输入框有 label，按钮有清楚名称，焦点可见。</li>
<li><strong>运行配置</strong>：生产 API 地址、HTTPS、子路径和页面回退规则正确。</li>
</ol>
<p>基础版保存到当前站点的本地存储，不含账号、跨设备同步、权限控制和后端备份。实际业务需要这些能力时，再补齐服务端方案。</p>
<h3>16.2 为什么构建通过仍可能出问题？</h3>
<p>类型检查主要验证静态类型，构建主要验证模块和资源能否打包。它们不能证明接口一定返回正确数据，也不能证明部署服务器支持页面回退。</p>
<p>测试、类型检查、lint、构建和运行验收各自验证不同问题。记录时区分已经执行的检查和仍需在真实环境验证的部分，避免把“能打包”当成“已经上线可用”。</p>
<h2>十七、常见问题与后续练习</h2>
<h3>17.1 按现象定位原因</h3>
<table>
<thead>
<tr>
<th>问题</th>
<th>常见原因</th>
<th>优先检查</th>
</tr>
</thead>
<tbody>
<tr>
<td>改了数组，界面没更新</td>
<td>原地修改后复用旧引用</td>
<td>通过 setter 返回新数组与变化项的新对象</td>
</tr>
<tr>
<td>setter 后读到旧状态</td>
<td>当前事件仍持有本次渲染快照</td>
<td>使用事件中的已知值，或函数式更新计算下一状态</td>
</tr>
<tr>
<td>页面持续重新渲染</td>
<td>渲染时调用 setter、事件函数写成调用</td>
<td>检查 <code>onClick={fn()}</code> 和组件主体</td>
</tr>
<tr>
<td>Effect 一直执行</td>
<td>不稳定的对象或函数依赖，并在 Effect 中更新状态</td>
<td>先检查是否需要该 Effect，再整理依赖</td>
</tr>
<tr>
<td>定时器越来越多</td>
<td>缺少清理，开发检查暴露重复建立</td>
<td>返回清理函数，检查卸载与重新挂载</td>
</tr>
<tr>
<td>删除后输入内容串到其他行</td>
<td>数组下标、随机值作为 key</td>
<td>使用稳定任务 ID</td>
</tr>
<tr>
<td>搜索结果偶尔倒退</td>
<td>旧请求晚于新请求完成</td>
<td>取消旧请求并阻止旧结果回写</td>
</tr>
<tr>
<td>HTTP 500 没进入 catch</td>
<td>只判断 fetch 是否 reject</td>
<td>显式检查 <code>response.ok</code></td>
</tr>
<tr>
<td>两个页面的数据不同步</td>
<td>分别调用 Hook 创建了独立状态</td>
<td>提升状态或在共同 Provider 中管理</td>
</tr>
<tr>
<td>Context 一变整片区域更新</td>
<td>订阅范围大、value 频繁变化</td>
<td>按业务拆分，测量后优化订阅</td>
</tr>
<tr>
<td>开发能跳转，线上刷新 404</td>
<td>静态服务器未配置页面回退</td>
<td>检查 History 路由与部署路径</td>
</tr>
<tr>
<td>表单输入突然被清空</td>
<td>组件被重新挂载、key 变化或表单 Action 重置</td>
<td>检查组件身份与受控状态归属</td>
</tr>
<tr>
<td>生产环境出现密钥</td>
<td>把秘密写进客户端代码或 Vite 公开变量</td>
<td>将访问移到服务端，并轮换已暴露凭据</td>
</tr>
</tbody>
</table>
<h3>17.2 用三个练习检验是否真正理解</h3>
<p><strong>练习一：增加任务优先级。</strong> 先修改类型与运行时校验，再修改添加、编辑、展示和筛选。思考旧缓存缺少字段时，是迁移数据还是升级存储键，不能只改 TypeScript 类型。</p>
<p><strong>练习二：接入真实后端。</strong> 实现创建、完成、重命名和删除接口，为每项操作设计 pending、错误、重复点击和失败恢复，再验证刷新后与服务器一致。请求失败时，不要把本地成功假装成服务器成功。</p>
<p><strong>练习三：补充边界测试。</strong> 创建两项任务后编辑其中一项，取消编辑不应保存；快速输入产生多个查询，让最早的请求最后返回，确认仍显示最新结果；写入失败后恢复存储，确认下一次修改可以保存。</p>
<p>当你能独立解释一份数据在哪里创建、由谁修改、通过什么路径传到界面、怎样保存，以及失败时会发生什么，就已经掌握了继续开发 React 项目最关键的基础。</p>
<h3>17.3 官方资料</h3>
<ul>
<li><a href="https://react.dev/learn">React 学习路线</a>：按组件、交互、状态和外部系统逐步学习。</li>
<li><a href="https://react.dev/reference/react/hooks">React Hooks 参考</a>：查具体 Hook 的参数、限制与用法。</li>
<li><a href="https://react.dev/versions">React 版本说明</a>：核对当前文档与项目主版本。</li>
<li><a href="https://reactrouter.com/start/declarative/installation">React Router 声明式模式</a>：了解本文使用的路由方式。</li>
<li><a href="https://vite.dev/guide/">Vite 文档</a>与 <a href="https://vitest.dev/guide/">Vitest 文档</a>：核对构建环境、配置和测试要求。</li>
</ul>
]]></content:encoded>
    </item>
    <item>
      <title>微信小程序从入门到实战</title>
      <link>https://felix.muke.chat/notes/wechat-miniprogram-from-beginner-to-advanced</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/wechat-miniprogram-from-beginner-to-advanced</guid>
      <pubDate>Wed, 04 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>从零搭建原生待办清单，再接入可运行的 Node.js 与 SQLite 后端，完成登录、增删改查、游标分页、下拉刷新和数据持久化，附完整前后端代码与联调步骤。</description>
      <category>前端开发</category>
      <category>微信小程序</category>
      <category>JavaScript</category>
      <category>Node.js</category>
      <category>SQLite</category>
      <content:encoded><![CDATA[<p>学习微信小程序，最容易卡住的地方往往是：照着示例能显示一个页面，一旦加上数据保存、接口请求和登录，就不知道代码该放在哪里，也不清楚页面为什么没有更新。</p>
<p>这篇文章围绕一个待办清单，按“本地版 → 组件化 → 服务端版”逐步实践。最终完成一个带登录、任务增删改查、游标分页、下拉刷新和数据库保存的小程序，并提供前后端完整代码。</p>
<p>默认你接触过 JavaScript 的变量、数组、函数和 Promise，以及基本的 CSS。第一至五节学习小程序基础，第六至九节完成前后端项目，第十节联调并切换真实微信登录，最后处理性能、发布和常见问题。没有微信凭据时，可以先在开发工具中通过本机演示登录跑通任务管理。</p>
<h2>一、先理解小程序的开发模型</h2>
<h3>1.1 小程序和普通网页有什么区别？</h3>
<p>原生小程序同样用 JavaScript 编写交互逻辑，但界面使用 WXML 和 WXSS，并通过微信提供的组件、框架与 API 运行。</p>
<table>
<thead>
<tr>
<th>文件</th>
<th>作用</th>
<th>可以怎样理解</th>
</tr>
</thead>
<tbody>
<tr>
<td>WXML</td>
<td>定义页面结构、数据绑定和事件</td>
<td>模板</td>
</tr>
<tr>
<td>WXSS</td>
<td>定义颜色、尺寸和布局</td>
<td>样式</td>
</tr>
<tr>
<td>JavaScript</td>
<td>处理数据、事件和接口调用</td>
<td>逻辑</td>
</tr>
<tr>
<td>JSON</td>
<td>声明页面、窗口和组件配置</td>
<td>配置</td>
</tr>
</tbody>
</table>
<p>微信提供了 <code>view</code>、<code>text</code>、<code>input</code>、<code>button</code> 等基础组件。不要直接把网页里的 <code>div</code>、<code>span</code> 和依赖 DOM 的代码复制进来；小程序页面逻辑也不能照搬 <code>document.querySelector</code> 这类浏览器操作。</p>
<p>本文采用原生 JavaScript、WebView 渲染和传统 <code>Page / Component</code> 写法。平台还提供 Skyline 和 glass-easel 等能力；它们分别涉及渲染引擎和组件框架，学习基础时先把当前这一条链路走通。<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/quickstart/code.html">官方：小程序代码构成</a>、<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/component-framework/">组件框架</a></p>
<h3>1.2 页面是怎样更新的？</h3>
<p>先记住这条数据流：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">用户输入、点击
      ↓
JavaScript 事件处理函数
      ↓
计算新的页面数据
      ↓
setData 更新状态
      ↓
WXML 根据状态更新界面
</code></pre>
<p>开发的重点是让状态和界面保持一致。例如任务是否完成，应由数据里的 <code>done</code> 决定，模板再根据 <code>done</code> 展示开关状态和删除线。</p>
<p>直接写 <code>this.data.todos = []</code> 不能代替页面数据更新。需要刷新界面的数据，应通过 <code>this.setData({ todos: [] })</code> 提交。</p>
<h2>二、创建项目，认识目录结构</h2>
<h3>2.1 准备开发环境</h3>
<ol>
<li>在微信公众平台注册小程序，获取对应的 AppID。只学习基础界面时，也可以按当前工具入口使用测试号。</li>
<li>安装微信开发者工具，扫码登录。</li>
<li>新建项目，选择一个空目录，填写 AppID，选择“不使用云服务”和 JavaScript 基础模板。</li>
<li>点击“编译”查看模拟器，再用“预览”检查手机上的效果。</li>
</ol>
<p>测试号适合学习基础功能，涉及开放能力和正式发布时，需要核对账号权限。<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/quickstart/getstart.html">官方：开发起步</a></p>
<p>本文的代码路径均以<strong>小程序代码根目录</strong>为起点。如果工具生成的项目把代码放在 <code>miniprogram/</code> 中，就在该目录下创建这些文件，并保留工具生成的项目配置。</p>
<h3>2.2 一个页面为什么通常有四个文件？</h3>
<p>先把业务代码整理为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">小程序代码根目录/
├── app.js
├── app.json
├── app.wxss
└── pages/
    └── index/
        ├── index.js
        ├── index.json
        ├── index.wxml
        └── index.wxss
</code></pre>
<p><code>app.js</code> 注册整个应用，<code>app.json</code> 注册页面和全局配置，<code>app.wxss</code> 放公共样式。页面目录中的四个同名文件共同组成首页。</p>
<p><code>app.json</code> 的 <code>pages</code> 填写不带扩展名的页面路径，第一个页面是默认启动页。JSON 使用双引号，不能添加注释或末尾逗号。</p>
<h2>三、完成一个可以运行的待办清单</h2>
<p>这一节给出完整基础版本。把以下七个文件放到对应位置，即可体验添加、完成、删除和重新进入后恢复数据。</p>
<h3>3.1 注册应用与首页</h3>
<p><code>app.js</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-js"><span class="line"><span style="color:#D2A8FF">App</span><span style="color:#E6EDF3">({})</span></span>
</code></pre>
<p><code>app.json</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "pages"</span><span style="color:#E6EDF3">: [</span><span style="color:#A5D6FF">"pages/index/index"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#7EE787">  "window"</span><span style="color:#E6EDF3">: {</span></span>
<span class="line"><span style="color:#7EE787">    "navigationBarTitleText"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"待办清单"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">    "navigationBarBackgroundColor"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"#ffffff"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">    "navigationBarTextStyle"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"black"</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"><span style="color:#7EE787">  "renderer"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"webview"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "style"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"v2"</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>app.wxss</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-css"><span class="line"><span style="color:#E6EDF3">page {</span></span>
<span class="line"><span style="color:#79C0FF">  background</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#f6f7f9</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#202124</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  font-size</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">28</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#7EE787">view</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">input</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">button</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">  box-sizing</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">border-box</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>pages/index/index.json</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "navigationBarTitleText"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"我的待办"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "usingComponents"</span><span style="color:#E6EDF3">: {}</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<h3>3.2 用 WXML 描述界面</h3>
<p><code>pages/index/index.wxml</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-html"><span class="line"><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"page"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"heading"</span><span style="color:#E6EDF3">>今天要做什么？&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"hint"</span><span style="color:#E6EDF3">>还有 {{remaining}} 项任务未完成&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"editor"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">input</span></span>
<span class="line"><span style="color:#79C0FF">      class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"input"</span></span>
<span class="line"><span style="color:#79C0FF">      value</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{draft}}"</span></span>
<span class="line"><span style="color:#79C0FF">      placeholder</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"输入一项任务"</span></span>
<span class="line"><span style="color:#79C0FF">      maxlength</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"80"</span></span>
<span class="line"><span style="color:#79C0FF">      confirm-type</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"done"</span></span>
<span class="line"><span style="color:#79C0FF">      bindinput</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onInput"</span></span>
<span class="line"><span style="color:#79C0FF">      bindconfirm</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"addTodo"</span></span>
<span class="line"><span style="color:#E6EDF3">    /></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> type</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"primary"</span><span style="color:#79C0FF"> size</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"mini"</span><span style="color:#79C0FF"> bindtap</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"addTodo"</span><span style="color:#E6EDF3">>添加&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> wx:if</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{todos.length === 0}}"</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"empty"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    还没有任务，先添加一项吧。</span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> wx:else</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> wx:for</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{todos}}"</span><span style="color:#79C0FF"> wx:key</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"id"</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"todo-row"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">label</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"todo-main"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#FFA198;font-style:italic">switch</span></span>
<span class="line"><span style="color:#79C0FF">          checked</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{item.done}}"</span></span>
<span class="line"><span style="color:#79C0FF">          data-id</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{item.id}}"</span></span>
<span class="line"><span style="color:#79C0FF">          bindchange</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"toggleTodo"</span></span>
<span class="line"><span style="color:#E6EDF3">        /></span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;</span><span style="color:#FFA198;font-style:italic">text</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"todo-title {{item.done ? 'done' : ''}}"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">          {{item.title}}</span></span>
<span class="line"><span style="color:#E6EDF3">        &#x3C;/</span><span style="color:#FFA198;font-style:italic">text</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> size</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"mini"</span><span style="color:#79C0FF"> data-id</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{item.id}}"</span><span style="color:#79C0FF"> bindtap</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"removeTodo"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">        删除</span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
</code></pre>
<p>这里已经包含了四种常见能力：</p>
<ul>
<li><code>{{remaining}}</code>：把 JavaScript 数据绑定到界面。</li>
<li><code>wx:if / wx:else</code>：根据条件展示空状态或任务列表。</li>
<li><code>wx:for</code>：遍历数组；默认当前项为 <code>item</code>，下标为 <code>index</code>。</li>
<li><code>bindinput / bindtap / bindchange</code>：把用户操作交给对应的方法。</li>
</ul>
<p><code>wx:key=&quot;id&quot;</code> 表示使用每项数据里的 <code>id</code> 识别节点。对于允许删除、插入和排序的列表，稳定的业务标识比数组下标更合适。</p>
<h3>3.3 在 JavaScript 中管理状态</h3>
<p><code>pages/index/index.js</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-js"><span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> STORAGE_KEY</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> 'todo-list:v1'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">Page</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#E6EDF3">  data: {</span></span>
<span class="line"><span style="color:#E6EDF3">    draft: </span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    todos: [],</span></span>
<span class="line"><span style="color:#E6EDF3">    remaining: </span><span style="color:#79C0FF">0</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onLoad</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">    try</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">      const</span><span style="color:#79C0FF"> cached</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> wx.</span><span style="color:#D2A8FF">getStorageSync</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">STORAGE_KEY</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">      const</span><span style="color:#79C0FF"> todos</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> Array.</span><span style="color:#D2A8FF">isArray</span><span style="color:#E6EDF3">(cached)</span></span>
<span class="line"><span style="color:#FF7B72">        ?</span><span style="color:#E6EDF3"> cached.</span><span style="color:#D2A8FF">filter</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">item</span><span style="color:#FF7B72"> =></span></span>
<span class="line"><span style="color:#E6EDF3">            item </span><span style="color:#FF7B72">&#x26;&#x26;</span></span>
<span class="line"><span style="color:#FF7B72">            typeof</span><span style="color:#E6EDF3"> item.id </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'string'</span><span style="color:#FF7B72"> &#x26;&#x26;</span></span>
<span class="line"><span style="color:#FF7B72">            typeof</span><span style="color:#E6EDF3"> item.title </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'string'</span><span style="color:#FF7B72"> &#x26;&#x26;</span></span>
<span class="line"><span style="color:#FF7B72">            typeof</span><span style="color:#E6EDF3"> item.done </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'boolean'</span></span>
<span class="line"><span style="color:#E6EDF3">          )</span></span>
<span class="line"><span style="color:#FF7B72">        :</span><span style="color:#E6EDF3"> []</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">      this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#E6EDF3">        todos,</span></span>
<span class="line"><span style="color:#E6EDF3">        remaining: todos.</span><span style="color:#D2A8FF">filter</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">item</span><span style="color:#FF7B72"> =></span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">item.done).</span><span style="color:#79C0FF">length</span></span>
<span class="line"><span style="color:#E6EDF3">      })</span></span>
<span class="line"><span style="color:#E6EDF3">    } </span><span style="color:#FF7B72">catch</span><span style="color:#E6EDF3"> (error) {</span></span>
<span class="line"><span style="color:#E6EDF3">      wx.</span><span style="color:#D2A8FF">showToast</span><span style="color:#E6EDF3">({ title: </span><span style="color:#A5D6FF">'读取本地任务失败'</span><span style="color:#E6EDF3">, icon: </span><span style="color:#A5D6FF">'none'</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onInput</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">event</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({ draft: event.detail.value })</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  addTodo</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> title</span><span style="color:#FF7B72"> =</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.data.draft.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">title) {</span></span>
<span class="line"><span style="color:#E6EDF3">      wx.</span><span style="color:#D2A8FF">showToast</span><span style="color:#E6EDF3">({ title: </span><span style="color:#A5D6FF">'请先输入任务'</span><span style="color:#E6EDF3">, icon: </span><span style="color:#A5D6FF">'none'</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#FF7B72">      return</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> todo</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">      id: Date.</span><span style="color:#D2A8FF">now</span><span style="color:#E6EDF3">() </span><span style="color:#FF7B72">+</span><span style="color:#A5D6FF"> '-'</span><span style="color:#FF7B72"> +</span><span style="color:#E6EDF3"> Math.</span><span style="color:#D2A8FF">random</span><span style="color:#E6EDF3">().</span><span style="color:#D2A8FF">toString</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">36</span><span style="color:#E6EDF3">).</span><span style="color:#D2A8FF">slice</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">8</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">      title,</span></span>
<span class="line"><span style="color:#E6EDF3">      done: </span><span style="color:#79C0FF">false</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">commitTodos</span><span style="color:#E6EDF3">([</span><span style="color:#FF7B72">...</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">.data.todos, todo], { draft: </span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  toggleTodo</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">event</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> id</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> event.currentTarget.dataset.id</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> todos</span><span style="color:#FF7B72"> =</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.data.todos.</span><span style="color:#D2A8FF">map</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">item</span><span style="color:#FF7B72"> =></span></span>
<span class="line"><span style="color:#E6EDF3">      item.id </span><span style="color:#FF7B72">===</span><span style="color:#E6EDF3"> id</span></span>
<span class="line"><span style="color:#FF7B72">        ?</span><span style="color:#E6EDF3"> { </span><span style="color:#FF7B72">...</span><span style="color:#E6EDF3">item, done: event.detail.value }</span></span>
<span class="line"><span style="color:#FF7B72">        :</span><span style="color:#E6EDF3"> item</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">commitTodos</span><span style="color:#E6EDF3">(todos)</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  removeTodo</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">event</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> id</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> event.currentTarget.dataset.id</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> todos</span><span style="color:#FF7B72"> =</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.data.todos.</span><span style="color:#D2A8FF">filter</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">item</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> item.id </span><span style="color:#FF7B72">!==</span><span style="color:#E6EDF3"> id)</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">commitTodos</span><span style="color:#E6EDF3">(todos)</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  commitTodos</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">todos</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">extra</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> {}) {</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#E6EDF3">      todos,</span></span>
<span class="line"><span style="color:#E6EDF3">      remaining: todos.</span><span style="color:#D2A8FF">filter</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">item</span><span style="color:#FF7B72"> =></span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">item.done).</span><span style="color:#79C0FF">length</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FF7B72">      ...</span><span style="color:#E6EDF3">extra</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    try</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">      wx.</span><span style="color:#D2A8FF">setStorageSync</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">STORAGE_KEY</span><span style="color:#E6EDF3">, todos)</span></span>
<span class="line"><span style="color:#E6EDF3">    } </span><span style="color:#FF7B72">catch</span><span style="color:#E6EDF3"> (error) {</span></span>
<span class="line"><span style="color:#E6EDF3">      wx.</span><span style="color:#D2A8FF">showToast</span><span style="color:#E6EDF3">({ title: </span><span style="color:#A5D6FF">'保存失败，退出可能丢失修改'</span><span style="color:#E6EDF3">, icon: </span><span style="color:#A5D6FF">'none'</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
</code></pre>
<p><code>data</code> 保存界面需要的状态。<code>draft</code> 是输入框内容，<code>todos</code> 是任务数组，<code>remaining</code> 是计算后供模板展示的未完成数量。</p>
<p>WXML 不是完整的 JavaScript 执行环境，不适合在里面编写 <code>todos.filter(...)</code> 这样的业务计算。把计算放在逻辑层，在任务发生变化时一起更新。</p>
<p><code>commitTodos</code> 把“更新列表、重新计数、保存到本地”放在一个位置，避免添加、删除时漏掉某一步。本例先更新界面，保存失败时明确提醒用户；真实产品也可以选择保存成功后再确认修改。</p>
<p>任务 ID 的生成方式只用于本地教学示例。接入服务器后，应使用后端提供的稳定标识。</p>
<h3>3.4 用 WXSS 完成布局</h3>
<p><code>pages/index/index.wxss</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-css"><span class="line"><span style="color:#79C0FF">.page</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">32</span><span style="color:#E6EDF3">rpx; }</span></span>
<span class="line"><span style="color:#79C0FF">.heading</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">font-size</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">40</span><span style="color:#E6EDF3">rpx; </span><span style="color:#79C0FF">font-weight</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">600</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.hint</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">margin-top</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">12</span><span style="color:#E6EDF3">rpx; </span><span style="color:#79C0FF">color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#6b7280</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.editor</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">align-items</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">center</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">32</span><span style="color:#E6EDF3">rpx </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.input</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">  flex</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  min-width</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  height</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">80</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  margin-right</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">16</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#79C0FF"> 20</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  border-radius</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">12</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  background</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#ffffff</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#79C0FF">.todo-row</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">  display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  align-items</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">center</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  margin-bottom</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">16</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">20</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  border-radius</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">12</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  background</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#ffffff</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#79C0FF">.todo-main</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">align-items</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">center</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">min-width</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.todo-title</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">min-width</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#79C0FF"> 16</span><span style="color:#E6EDF3">rpx; </span><span style="color:#79C0FF">word-break</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">break-all</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.done</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#9ca3af</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">text-decoration</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">line-through</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.empty</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">64</span><span style="color:#E6EDF3">rpx </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#6b7280</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">text-align</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">center</span><span style="color:#E6EDF3">; }</span></span>
</code></pre>
<p><code>rpx</code> 是小程序常用的相对长度单位，以屏幕宽度为 <code>750rpx</code> 进行换算。在宽度为 375 个逻辑像素的屏幕上，<code>2rpx</code> 大约对应 1 个逻辑像素。细边框可以使用 <code>1px</code>，布局也可以结合百分比和 Flex，不能只靠把所有尺寸换成 <code>rpx</code> 完成适配。</p>
<h3>3.5 怎样判断基础版本已经完成？</h3>
<p>编译后依次检查：</p>
<ol>
<li>输入一项任务，点击“添加”，列表增加一项，输入框清空。</li>
<li>输入空格后添加，出现提示，列表没有新增内容。</li>
<li>切换任务开关，删除线与未完成数量一起变化。</li>
<li>删除某项任务，其他任务及其完成状态保持正确。</li>
<li>重新编译或退出后再进入，任务从本地缓存恢复。</li>
</ol>
<p>最后一步需要保留开发者工具中的本地缓存。如果主动清除缓存，列表会重新变为空。</p>
<h2>四、理解数据绑定、事件和生命周期</h2>
<h3>4.1 输入框为什么要绑定两次？</h3>
<p><code>value=&quot;{{draft}}&quot;</code> 负责从状态向界面传值，<code>bindinput=&quot;onInput&quot;</code> 负责把输入事件带回逻辑层。</p>
<p>本例使用显式的数据更新：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">data.draft → input.value
用户输入 → event.detail.value → setData → data.draft
</code></pre>
<p>输入组件产生的值通常在 <code>event.detail</code> 中。业务标识则常通过 <code>data-id</code> 放在节点上，再从 <code>event.currentTarget.dataset.id</code> 读取。</p>
<p><code>currentTarget</code> 是绑定当前处理函数的节点，<code>target</code> 是最初触发事件的节点。按钮内部还有其他节点时，两者可能不同，读取当前绑定节点的 <code>dataset</code> 应使用 <code>currentTarget</code>。</p>
<p>普通点击绑定 <code>bindtap</code> 允许事件按规则传播；需要阻止点击冒泡时可以使用 <code>catchtap</code>。例如整行能跳转详情，行内删除按钮就要避免同时触发跳转。</p>
<h3>4.2 setData 应该怎样使用？</h3>
<p><code>setData</code> 会更新 <code>this.data</code>，并通知组件框架更新界面。需要等待这一组数据完全应用到渲染引擎后再进行依赖布局的操作，可以使用第二个参数：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-js"><span class="line"><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({ draft: </span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3"> }, () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#8B949E">  // 在这里执行依赖此次渲染结果的操作</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
</code></pre>
<p>不同组件框架的数据更新细节有差异，不要把“改变状态”和“屏幕已经完成绘制”混为一谈。普通业务计算直接使用已更新的数据即可，不必给每次更新都加回调。<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/component-framework/data-updates.html">官方：数据更新方法</a></p>
<p>还要注意：</p>
<ul>
<li>更新数据应能被序列化；函数、请求对象等不应放进 <code>data</code>。</li>
<li>使用空字符串或 <code>null</code> 表达明确的空值，避免用 <code>undefined</code> 清空模板数据。</li>
<li>只提交需要更新的字段，避免反复执行 <code>this.setData(this.data)</code>。</li>
<li>对象的局部字段可以用路径更新，例如 <code>this.setData({ 'profile.nickname': '小明' })</code>。</li>
</ul>
<h3>4.3 生命周期里分别放什么？</h3>
<table>
<thead>
<tr>
<th>生命周期</th>
<th>触发时机</th>
<th>常见工作</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>onLoad(options)</code></td>
<td>当前页面实例加载时</td>
<td>读取路由参数、初始化、首次请求</td>
</tr>
<tr>
<td><code>onShow()</code></td>
<td>页面显示或重新回到前台时</td>
<td>按需刷新可能在别处修改的数据</td>
</tr>
<tr>
<td><code>onReady()</code></td>
<td>页面首次渲染完成时</td>
<td>执行需要页面节点已经建立的操作</td>
</tr>
<tr>
<td><code>onHide()</code></td>
<td>页面隐藏时</td>
<td>暂停轮询、计时或高频更新</td>
</tr>
<tr>
<td><code>onUnload()</code></td>
<td>页面卸载时</td>
<td>清理定时器、订阅和页面资源</td>
</tr>
</tbody>
</table>
<p><code>onLoad</code> 对一个页面实例只执行一次，<code>onShow</code> 则可能执行多次。首次进入时两者都会触发，因此不要在两个地方都无条件请求同一份数据。<a href="https://developers.weixin.qq.com/miniprogram/dev/reference/api/Page.html">官方：Page 与生命周期</a></p>
<p>当前待办清单只有一个页面，所以在 <code>onLoad</code> 读取缓存即可。如果以后增加编辑详情页，返回列表时就要决定：通过事件同步修改，还是在 <code>onShow</code> 重新读取数据。</p>
<h3>4.4 页面跳转应该选择哪个 API？</h3>
<table>
<thead>
<tr>
<th>API</th>
<th>行为</th>
<th>典型场景</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>wx.navigateTo</code></td>
<td>打开新的非 tabBar 页面，保留当前页</td>
<td>列表进入详情</td>
</tr>
<tr>
<td><code>wx.redirectTo</code></td>
<td>用新的非 tabBar 页面替换当前页</td>
<td>中间流程完成后进入结果页</td>
</tr>
<tr>
<td><code>wx.navigateBack</code></td>
<td>返回页面栈中的上一页或前几页</td>
<td>详情返回列表</td>
</tr>
<tr>
<td><code>wx.switchTab</code></td>
<td>切换到已经配置的 tabBar 页面</td>
<td>跳转到首页、个人中心</td>
</tr>
<tr>
<td><code>wx.reLaunch</code></td>
<td>关闭全部页面后打开指定页面</td>
<td>需要重建整个页面入口时</td>
</tr>
</tbody>
</table>
<p>例如，已经创建并注册 <code>pages/detail/detail</code> 后，可以这样传递任务 ID：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-js"><span class="line"><span style="color:#E6EDF3">wx.</span><span style="color:#D2A8FF">navigateTo</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#E6EDF3">  url: </span><span style="color:#A5D6FF">'/pages/detail/detail?id='</span><span style="color:#FF7B72"> +</span><span style="color:#D2A8FF"> encodeURIComponent</span><span style="color:#E6EDF3">(todo.id)</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
</code></pre>
<p>这里的 <code>todo</code> 表示当前选中的任务。详情页在 <code>onLoad(options)</code> 读取 <code>options.id</code>，再从数据源查询任务；不要把整份用户资料或令牌拼进 URL。</p>
<p>tabBar 页面必须先在 <code>app.json</code> 配置，不能使用 <code>navigateTo</code> 打开。<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/app-service/route.html">官方：页面路由</a></p>
<h2>五、把任务行拆成自定义组件</h2>
<h3>5.1 什么时候应该拆组件？</h3>
<p>当任务行出现在多个页面，或者包含编辑、删除、状态切换等相对独立的交互时，可以把它拆成 <code>todo-item</code>。</p>
<p>数据仍由页面管理，组件负责展示和上报操作：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">页面 todos → properties → todo-item
页面处理并更新数据 ← 自定义事件 ← 用户操作
</code></pre>
<p>这样能够避免组件自行维护一份任务、页面又维护另一份任务，最后两边状态不同步。</p>
<h3>5.2 创建组件的四个文件</h3>
<p>新建 <code>components/todo-item/</code>。</p>
<p><code>components/todo-item/todo-item.json</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "component"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "usingComponents"</span><span style="color:#E6EDF3">: {}</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>components/todo-item/todo-item.js</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-js"><span class="line"><span style="color:#D2A8FF">Component</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#E6EDF3">  properties: {</span></span>
<span class="line"><span style="color:#E6EDF3">    todo: {</span></span>
<span class="line"><span style="color:#E6EDF3">      type: Object,</span></span>
<span class="line"><span style="color:#E6EDF3">      value: { id: </span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">, title: </span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">, done: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">  methods: {</span></span>
<span class="line"><span style="color:#D2A8FF">    onChange</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">event</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#79C0FF">      this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">triggerEvent</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'change'</span><span style="color:#E6EDF3">, { value: event.detail.value })</span></span>
<span class="line"><span style="color:#E6EDF3">    },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">    onRemove</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#79C0FF">      this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">triggerEvent</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'remove'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
</code></pre>
<p><code>components/todo-item/todo-item.wxml</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-html"><span class="line"><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"row"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#7EE787">label</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"main"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#FFA198;font-style:italic">switch</span><span style="color:#79C0FF"> checked</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{todo.done}}"</span><span style="color:#79C0FF"> bindchange</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onChange"</span><span style="color:#E6EDF3"> /></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#FFA198;font-style:italic">text</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"title {{todo.done ? 'done' : ''}}"</span><span style="color:#E6EDF3">>{{todo.title}}&#x3C;/</span><span style="color:#FFA198;font-style:italic">text</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;/</span><span style="color:#7EE787">label</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"remove"</span><span style="color:#79C0FF"> size</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"mini"</span><span style="color:#79C0FF"> bindtap</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onRemove"</span><span style="color:#E6EDF3">>删除&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
</code></pre>
<p><code>components/todo-item/todo-item.wxss</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-css"><span class="line"><span style="color:#79C0FF">.row</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">  display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  align-items</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">center</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#79C0FF">  margin-bottom</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">16</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">20</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  border-radius</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">12</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  background</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#ffffff</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#79C0FF">.main</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">align-items</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">center</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">min-width</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.title</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">min-width</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#79C0FF"> 16</span><span style="color:#E6EDF3">rpx; </span><span style="color:#79C0FF">word-break</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">break-all</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.done</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#9ca3af</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">text-decoration</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">line-through</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.remove</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; }</span></span>
</code></pre>
<p>组件样式按默认隔离方式放在组件自己的 WXSS 中，不要假定页面里的同名选择器会自动作用到组件内部。</p>
<h3>5.3 在页面中注册和使用</h3>
<p>把 <code>pages/index/index.json</code> 改为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "navigationBarTitleText"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"我的待办"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "usingComponents"</span><span style="color:#E6EDF3">: {</span></span>
<span class="line"><span style="color:#7EE787">    "todo-item"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"/components/todo-item/todo-item"</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>再把首页中 <code>wx:else</code> 容器内的任务行循环替换为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-html"><span class="line"><span style="color:#E6EDF3">&#x3C;</span><span style="color:#7EE787">todo-item</span></span>
<span class="line"><span style="color:#79C0FF">  wx:for</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{todos}}"</span></span>
<span class="line"><span style="color:#79C0FF">  wx:key</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"id"</span></span>
<span class="line"><span style="color:#79C0FF">  todo</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{item}}"</span></span>
<span class="line"><span style="color:#79C0FF">  data-id</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{item.id}}"</span></span>
<span class="line"><span style="color:#79C0FF">  bind:change</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"toggleTodo"</span></span>
<span class="line"><span style="color:#79C0FF">  bind:remove</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"removeTodo"</span></span>
<span class="line"><span style="color:#E6EDF3">/></span></span>
</code></pre>
<p>输入区和空状态继续保留。原页面里 <code>.todo-row</code>、<code>.todo-main</code>、<code>.todo-title</code> 和 <code>.done</code> 的样式可以删除，因为任务行已经由组件负责。</p>
<p>页面 JavaScript 不需要修改：组件节点上的 <code>data-id</code> 仍然供 <code>event.currentTarget.dataset.id</code> 读取，<code>change</code> 事件继续通过 <code>event.detail.value</code> 上报开关状态。</p>
<p><code>properties</code> 传入数据，<code>triggerEvent</code> 传出事件。组件不直接改父页面的数据，也不自己调用后端删除任务。<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/component-framework/interaction.html">官方：组件间交互</a>、<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/component-framework/event-system.html">事件系统</a></p>
<h2>六、确定实战目标和前后端分工</h2>
<p>前五节已经完成一个本地版本。从这一节开始，把同一个项目改造成“登录后管理自己的任务”的服务端版本。</p>
<h3>6.1 最终要完成哪些功能？</h3>
<table>
<thead>
<tr>
<th>功能</th>
<th>用户操作</th>
<th>数据怎样变化</th>
</tr>
</thead>
<tbody>
<tr>
<td>登录</td>
<td>进入演示账号，或使用微信登录</td>
<td>获得由后端签发的业务令牌</td>
</tr>
<tr>
<td>添加任务</td>
<td>输入标题并添加</td>
<td>后端创建任务并保存到 SQLite</td>
</tr>
<tr>
<td>查看列表</td>
<td>首次进入、下拉刷新、加载更多</td>
<td>从后端读取当前账号的任务</td>
</tr>
<tr>
<td>编辑任务</td>
<td>点击编辑，修改标题后确认</td>
<td>后端更新该任务</td>
</tr>
<tr>
<td>完成与撤销</td>
<td>点击完成或撤销</td>
<td>后端修改完成状态</td>
</tr>
<tr>
<td>删除任务</td>
<td>点击删除，确认后执行</td>
<td>后端删除该任务</td>
</tr>
<tr>
<td>数据恢复</td>
<td>重启服务或重新进入小程序</td>
<td>从 SQLite 重新读取已保存任务</td>
</tr>
</tbody>
</table>
<p>这里提供两个登录入口：</p>
<ul>
<li><strong>本机演示登录</strong>：不调用微信，固定使用一个演示账号，便于先在开发工具中跑通业务。</li>
<li><strong>真实微信登录</strong>：小程序获取 code，后端向微信换取 OpenID，按用户隔离任务。</li>
</ul>
<p>两者共用同一套任务接口。演示登录只用于本机开发，切换到真实微信登录后，用户身份由微信登录结果决定。</p>
<h3>6.2 按完整项目组织目录</h3>
<p>后端放在小程序项目外。下文把小程序代码根目录统一称为 <code>miniprogram/</code>，前五节的所有文件都位于其中：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">todo-project/
├── server/
│   ├── server.mjs
│   ├── .env
│   ├── .gitignore
│   └── todo.sqlite            # 运行后自动生成
└── miniprogram/
    ├── app.js
    ├── app.json
    ├── app.wxss
    ├── config.js
    ├── utils/request.js
    ├── services/
    │   ├── session.js
    │   └── todos.js
    ├── components/todo-item/
    │   ├── todo-item.js
    │   ├── todo-item.json
    │   ├── todo-item.wxml
    │   └── todo-item.wxss
    └── pages/index/
        ├── index.js
        ├── index.json
        ├── index.wxml
        └── index.wxss
</code></pre>
<p>微信开发者工具打开 <code>miniprogram/</code>，终端在 <code>server/</code> 启动接口服务。不要把后端的 <code>.env</code>、数据库或服务器代码放进小程序代码包。</p>
<p><code>app.js</code>、<code>app.json</code>、<code>app.wxss</code> 沿用第三节的内容；后面会给出其余文件的完整版本。已有同名文件按新版本替换，每个页面只保留一份 <code>Page({ ... })</code>。</p>
<h3>6.3 先约定接口</h3>
<table>
<thead>
<tr>
<th>方法与路径</th>
<th>用途</th>
<th>请求数据</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>GET /health</code></td>
<td>检查服务是否启动</td>
<td>无</td>
</tr>
<tr>
<td><code>POST /auth/demo-login</code></td>
<td>本机演示登录</td>
<td><code>{}</code></td>
</tr>
<tr>
<td><code>POST /auth/wechat-login</code></td>
<td>微信登录</td>
<td><code>{ code }</code></td>
</tr>
<tr>
<td><code>GET /todos?limit=20&amp;cursor=任务ID</code></td>
<td>分页读取任务</td>
<td>首页省略 cursor</td>
</tr>
<tr>
<td><code>POST /todos</code></td>
<td>创建任务</td>
<td><code>{ title }</code></td>
</tr>
<tr>
<td><code>PUT /todos/:id</code></td>
<td>修改标题或完成状态</td>
<td><code>{ title, done }</code></td>
</tr>
<tr>
<td><code>DELETE /todos/:id</code></td>
<td>删除任务</td>
<td>无</td>
</tr>
</tbody>
</table>
<p>任务接口都要携带 <code>Authorization: Bearer 业务令牌</code>。成功响应采用 <code>{ code: 0, data: ... }</code>，失败响应采用 <code>{ code: 状态码, message: &quot;错误说明&quot; }</code>。</p>
<p>例如，读取列表得到：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "code"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "data"</span><span style="color:#E6EDF3">: {</span></span>
<span class="line"><span style="color:#7EE787">    "items"</span><span style="color:#E6EDF3">: [</span></span>
<span class="line"><span style="color:#E6EDF3">      { </span><span style="color:#7EE787">"id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"12"</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">"title"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"完成小程序实战"</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">"done"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"><span style="color:#E6EDF3">    ],</span></span>
<span class="line"><span style="color:#7EE787">    "nextCursor"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">null</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>nextCursor</code> 为字符串时，表示还有下一页；为 <code>null</code> 时表示已经结束。它是本文的接口约定，不是微信规定的返回格式。</p>
<h2>七、编写一个能够启动的 Node.js 后端</h2>
<h3>7.1 准备运行环境和配置</h3>
<p>安装 Node.js 24。下面使用内置的 HTTP、加密和 SQLite 模块，无需安装 npm 依赖。示例在 Node.js 24.14.1 上做了本地联调；该版本的 <code>node:sqlite</code> 会显示实验性提示，正式项目选用驱动时应核对所用版本的稳定性说明。<a href="https://nodejs.org/docs/latest-v24.x/api/sqlite.html">Node.js：SQLite</a></p>
<p>新建 <code>server/.env</code>，先使用本机演示模式：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-ini"><span class="line"><span style="color:#FF7B72">NODE_ENV</span><span style="color:#E6EDF3">=development</span></span>
<span class="line"><span style="color:#FF7B72">DEMO_AUTH</span><span style="color:#E6EDF3">=1</span></span>
<span class="line"><span style="color:#FF7B72">PORT</span><span style="color:#E6EDF3">=3001</span></span>
<span class="line"><span style="color:#FF7B72">DATABASE_PATH</span><span style="color:#E6EDF3">=./todo.sqlite</span></span>
</code></pre>
<p>再创建 <code>server/.gitignore</code>，避免把私有配置和运行数据提交进版本库：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">.env
*.sqlite
*.sqlite-*
</code></pre>
<p><code>DATABASE_PATH</code> 相对于服务启动目录。数据库文件在第一次启动时自动创建，重新启动不会清空任务。</p>
<h3>7.2 数据表分别保存什么？</h3>
<p>后端用两个表就能支撑本次实战：</p>
<table>
<thead>
<tr>
<th>表</th>
<th>关键字段</th>
<th>作用</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>todos</code></td>
<td><code>id / owner / title / done</code></td>
<td>保存任务及其所属用户</td>
</tr>
<tr>
<td><code>sessions</code></td>
<td><code>token_hash / owner / expires_at</code></td>
<td>保存业务登录态和过期时间</td>
</tr>
</tbody>
</table>
<p>任务 ID 由 SQLite 生成，并以字符串返回小程序，供 <code>wx:key</code> 和事件定位使用。每次查询、更新和删除都带上服务器从令牌中查出的 <code>owner</code>，客户端不能自行指定任务归属。</p>
<p>本例不额外建立用户资料表，直接以登录得到的 OpenID 标识数据归属；演示模式固定使用 <code>demo-user</code>。</p>
<h3>7.3 完整的 server.mjs</h3>
<p>创建 <code>server/server.mjs</code>，完整代码如下：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-js"><span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { createServer } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'node:http'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { randomBytes, createHash } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'node:crypto'</span></span>
<span class="line"><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> { DatabaseSync } </span><span style="color:#FF7B72">from</span><span style="color:#A5D6FF"> 'node:sqlite'</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> demo</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> process.env.</span><span style="color:#79C0FF">DEMO_AUTH</span><span style="color:#FF7B72"> ===</span><span style="color:#A5D6FF"> '1'</span></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> appId</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> process.env.</span><span style="color:#79C0FF">WECHAT_APP_ID</span></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> appSecret</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> process.env.</span><span style="color:#79C0FF">WECHAT_APP_SECRET</span></span>
<span class="line"><span style="color:#FF7B72">if</span><span style="color:#E6EDF3"> (demo </span><span style="color:#FF7B72">&#x26;&#x26;</span><span style="color:#E6EDF3"> process.env.</span><span style="color:#79C0FF">NODE_ENV</span><span style="color:#FF7B72"> ===</span><span style="color:#A5D6FF"> 'production'</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'正式环境不能启用演示登录'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#FF7B72">if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">demo </span><span style="color:#FF7B72">&#x26;&#x26;</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">appId </span><span style="color:#FF7B72">||</span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">appSecret)) {</span></span>
<span class="line"><span style="color:#FF7B72">  throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'请配置 WECHAT_APP_ID 和 WECHAT_APP_SECRET'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> db</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> DatabaseSync</span><span style="color:#E6EDF3">(process.env.</span><span style="color:#79C0FF">DATABASE_PATH</span><span style="color:#FF7B72"> ||</span><span style="color:#A5D6FF"> './todo.sqlite'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">db.</span><span style="color:#D2A8FF">exec</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">`</span></span>
<span class="line"><span style="color:#A5D6FF">  PRAGMA journal_mode = WAL;</span></span>
<span class="line"><span style="color:#A5D6FF">  CREATE TABLE IF NOT EXISTS todos (</span></span>
<span class="line"><span style="color:#A5D6FF">    id INTEGER PRIMARY KEY AUTOINCREMENT,</span></span>
<span class="line"><span style="color:#A5D6FF">    owner TEXT NOT NULL,</span></span>
<span class="line"><span style="color:#A5D6FF">    title TEXT NOT NULL,</span></span>
<span class="line"><span style="color:#A5D6FF">    done INTEGER NOT NULL DEFAULT 0 CHECK (done IN (0, 1))</span></span>
<span class="line"><span style="color:#A5D6FF">  );</span></span>
<span class="line"><span style="color:#A5D6FF">  CREATE INDEX IF NOT EXISTS todos_owner_id ON todos(owner, id);</span></span>
<span class="line"><span style="color:#A5D6FF">  CREATE TABLE IF NOT EXISTS sessions (</span></span>
<span class="line"><span style="color:#A5D6FF">    token_hash TEXT PRIMARY KEY,</span></span>
<span class="line"><span style="color:#A5D6FF">    owner TEXT NOT NULL,</span></span>
<span class="line"><span style="color:#A5D6FF">    expires_at INTEGER NOT NULL</span></span>
<span class="line"><span style="color:#A5D6FF">  );</span></span>
<span class="line"><span style="color:#A5D6FF">`</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#D2A8FF"> hash</span><span style="color:#FF7B72"> =</span><span style="color:#FFA657"> token</span><span style="color:#FF7B72"> =></span><span style="color:#D2A8FF"> createHash</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'sha256'</span><span style="color:#E6EDF3">).</span><span style="color:#D2A8FF">update</span><span style="color:#E6EDF3">(token).</span><span style="color:#D2A8FF">digest</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'hex'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#D2A8FF"> problem</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> (</span><span style="color:#FFA657">status</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">message</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> Object.</span><span style="color:#D2A8FF">assign</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(message), { status })</span></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#D2A8FF"> toTodo</span><span style="color:#FF7B72"> =</span><span style="color:#FFA657"> row</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> ({ id: </span><span style="color:#D2A8FF">String</span><span style="color:#E6EDF3">(row.id), title: row.title, done: row.done </span><span style="color:#FF7B72">===</span><span style="color:#79C0FF"> 1</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> send</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">res</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">status</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">body</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#E6EDF3">  res.</span><span style="color:#D2A8FF">writeHead</span><span style="color:#E6EDF3">(status, {</span></span>
<span class="line"><span style="color:#A5D6FF">    'content-type'</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">'application/json; charset=utf-8'</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">    'cache-control'</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">'no-store'</span></span>
<span class="line"><span style="color:#E6EDF3">  })</span></span>
<span class="line"><span style="color:#E6EDF3">  res.</span><span style="color:#D2A8FF">end</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">JSON</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">stringify</span><span style="color:#E6EDF3">(body))</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> readJson</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">req</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">req.headers[</span><span style="color:#A5D6FF">'content-type'</span><span style="color:#E6EDF3">]?.</span><span style="color:#D2A8FF">startsWith</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'application/json'</span><span style="color:#E6EDF3">)) {</span></span>
<span class="line"><span style="color:#FF7B72">    throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">415</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'请使用 JSON 请求体'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#FF7B72"> new</span><span style="color:#79C0FF"> Promise</span><span style="color:#E6EDF3">((</span><span style="color:#FFA657">resolve</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">reject</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> chunks</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> []</span></span>
<span class="line"><span style="color:#FF7B72">    let</span><span style="color:#E6EDF3"> size </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> 0</span></span>
<span class="line"><span style="color:#E6EDF3">    req.</span><span style="color:#D2A8FF">on</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'data'</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">chunk</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">      size </span><span style="color:#FF7B72">+=</span><span style="color:#E6EDF3"> chunk.</span><span style="color:#79C0FF">length</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (size </span><span style="color:#FF7B72">&#x3C;=</span><span style="color:#79C0FF"> 8192</span><span style="color:#E6EDF3">) chunks.</span><span style="color:#D2A8FF">push</span><span style="color:#E6EDF3">(chunk)</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"><span style="color:#E6EDF3">    req.</span><span style="color:#D2A8FF">on</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'end'</span><span style="color:#E6EDF3">, () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (size </span><span style="color:#FF7B72">></span><span style="color:#79C0FF"> 8192</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">return</span><span style="color:#D2A8FF"> reject</span><span style="color:#E6EDF3">(</span><span style="color:#D2A8FF">problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">413</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'请求内容过大'</span><span style="color:#E6EDF3">))</span></span>
<span class="line"><span style="color:#FF7B72">      try</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> value</span><span style="color:#FF7B72"> =</span><span style="color:#79C0FF"> JSON</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">parse</span><span style="color:#E6EDF3">(Buffer.</span><span style="color:#D2A8FF">concat</span><span style="color:#E6EDF3">(chunks).</span><span style="color:#D2A8FF">toString</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'utf8'</span><span style="color:#E6EDF3">))</span></span>
<span class="line"><span style="color:#FF7B72">        if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">value </span><span style="color:#FF7B72">||</span><span style="color:#FF7B72"> typeof</span><span style="color:#E6EDF3"> value </span><span style="color:#FF7B72">!==</span><span style="color:#A5D6FF"> 'object'</span><span style="color:#FF7B72"> ||</span><span style="color:#E6EDF3"> Array.</span><span style="color:#D2A8FF">isArray</span><span style="color:#E6EDF3">(value)) {</span></span>
<span class="line"><span style="color:#FF7B72">          throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'invalid object'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">        }</span></span>
<span class="line"><span style="color:#D2A8FF">        resolve</span><span style="color:#E6EDF3">(value)</span></span>
<span class="line"><span style="color:#E6EDF3">      } </span><span style="color:#FF7B72">catch</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#D2A8FF">        reject</span><span style="color:#E6EDF3">(</span><span style="color:#D2A8FF">problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">400</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'JSON 格式错误'</span><span style="color:#E6EDF3">))</span></span>
<span class="line"><span style="color:#E6EDF3">      }</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"><span style="color:#E6EDF3">    req.</span><span style="color:#D2A8FF">on</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'error'</span><span style="color:#E6EDF3">, reject)</span></span>
<span class="line"><span style="color:#E6EDF3">  })</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> titleOf</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">value</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">typeof</span><span style="color:#E6EDF3"> value </span><span style="color:#FF7B72">!==</span><span style="color:#A5D6FF"> 'string'</span><span style="color:#FF7B72"> ||</span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">value.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">() </span><span style="color:#FF7B72">||</span><span style="color:#E6EDF3"> value.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">().</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#79C0FF"> 80</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">    throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">400</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'任务名称需要包含 1 到 80 个字符'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> value.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> ownerOf</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">req</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> token</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> /</span><span style="color:#FF7B72">^</span><span style="color:#A5D6FF">Bearer (</span><span style="color:#79C0FF">[a-f0-9]</span><span style="color:#FF7B72">{64}</span><span style="color:#A5D6FF">)</span><span style="color:#FF7B72">$</span><span style="color:#A5D6FF">/</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">exec</span><span style="color:#E6EDF3">(req.headers.authorization </span><span style="color:#FF7B72">||</span><span style="color:#A5D6FF"> ''</span><span style="color:#E6EDF3">)?.[</span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">]</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">token) </span><span style="color:#FF7B72">throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">401</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'请先登录'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> session</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> db.</span><span style="color:#D2A8FF">prepare</span><span style="color:#E6EDF3">(</span></span>
<span class="line"><span style="color:#A5D6FF">    'SELECT owner FROM sessions WHERE token_hash = ? AND expires_at > ?'</span></span>
<span class="line"><span style="color:#E6EDF3">  ).</span><span style="color:#D2A8FF">get</span><span style="color:#E6EDF3">(</span><span style="color:#D2A8FF">hash</span><span style="color:#E6EDF3">(token), Date.</span><span style="color:#D2A8FF">now</span><span style="color:#E6EDF3">())</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">session) </span><span style="color:#FF7B72">throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">401</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'登录已过期，请重新登录'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> session.owner</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">async</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> wechatOwner</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">code</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">typeof</span><span style="color:#E6EDF3"> code </span><span style="color:#FF7B72">!==</span><span style="color:#A5D6FF"> 'string'</span><span style="color:#FF7B72"> ||</span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">code </span><span style="color:#FF7B72">||</span><span style="color:#E6EDF3"> code.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#79C0FF"> 256</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">    throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">400</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'缺少有效登录凭证'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> url</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> URL</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'https://api.weixin.qq.com/sns/jscode2session'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  url.search </span><span style="color:#FF7B72">=</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> URLSearchParams</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#E6EDF3">    appid: appId, secret: appSecret,</span></span>
<span class="line"><span style="color:#E6EDF3">    js_code: code, grant_type: </span><span style="color:#A5D6FF">'authorization_code'</span></span>
<span class="line"><span style="color:#E6EDF3">  }).</span><span style="color:#D2A8FF">toString</span><span style="color:#E6EDF3">()</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  let</span><span style="color:#E6EDF3"> result</span></span>
<span class="line"><span style="color:#FF7B72">  try</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> response</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> await</span><span style="color:#D2A8FF"> fetch</span><span style="color:#E6EDF3">(url, { signal: AbortSignal.</span><span style="color:#D2A8FF">timeout</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">8000</span><span style="color:#E6EDF3">) })</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">response.ok) </span><span style="color:#FF7B72">throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'upstream error'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    result </span><span style="color:#FF7B72">=</span><span style="color:#FF7B72"> await</span><span style="color:#E6EDF3"> response.</span><span style="color:#D2A8FF">json</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#E6EDF3">  } </span><span style="color:#FF7B72">catch</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">502</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'微信登录服务暂时不可用'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">result </span><span style="color:#FF7B72">||</span><span style="color:#E6EDF3"> result.errcode </span><span style="color:#FF7B72">||</span><span style="color:#FF7B72"> typeof</span><span style="color:#E6EDF3"> result.openid </span><span style="color:#FF7B72">!==</span><span style="color:#A5D6FF"> 'string'</span><span style="color:#FF7B72"> ||</span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">result.openid) {</span></span>
<span class="line"><span style="color:#FF7B72">    throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">401</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'微信登录失败，请重新获取凭证'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> result.openid</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> server</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> createServer</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">async</span><span style="color:#E6EDF3"> (</span><span style="color:#FFA657">req</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">res</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">  try</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> url</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> URL</span><span style="color:#E6EDF3">(req.url, </span><span style="color:#A5D6FF">'http://localhost'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">    let</span><span style="color:#E6EDF3"> data</span></span>
<span class="line"><span style="color:#FF7B72">    let</span><span style="color:#E6EDF3"> status </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> 200</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (req.method </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'GET'</span><span style="color:#FF7B72"> &#x26;&#x26;</span><span style="color:#E6EDF3"> url.pathname </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> '/health'</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#E6EDF3">      data </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> { status: </span><span style="color:#A5D6FF">'ok'</span><span style="color:#E6EDF3">, mode: demo </span><span style="color:#FF7B72">?</span><span style="color:#A5D6FF"> 'demo'</span><span style="color:#FF7B72"> :</span><span style="color:#A5D6FF"> 'wechat'</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"><span style="color:#E6EDF3">    } </span><span style="color:#FF7B72">else</span><span style="color:#FF7B72"> if</span><span style="color:#E6EDF3"> (req.method </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'POST'</span><span style="color:#FF7B72"> &#x26;&#x26;</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">      url.pathname </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> '/auth/wechat-login'</span><span style="color:#FF7B72"> ||</span></span>
<span class="line"><span style="color:#E6EDF3">      (demo </span><span style="color:#FF7B72">&#x26;&#x26;</span><span style="color:#E6EDF3"> url.pathname </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> '/auth/demo-login'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    )) {</span></span>
<span class="line"><span style="color:#FF7B72">      const</span><span style="color:#79C0FF"> body</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> await</span><span style="color:#D2A8FF"> readJson</span><span style="color:#E6EDF3">(req)</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (demo </span><span style="color:#FF7B72">&#x26;&#x26;</span><span style="color:#E6EDF3"> url.pathname </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> '/auth/wechat-login'</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">        throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">400</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'演示环境请使用演示登录入口'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">      }</span></span>
<span class="line"><span style="color:#FF7B72">      const</span><span style="color:#79C0FF"> owner</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> demo </span><span style="color:#FF7B72">?</span><span style="color:#A5D6FF"> 'demo-user'</span><span style="color:#FF7B72"> :</span><span style="color:#FF7B72"> await</span><span style="color:#D2A8FF"> wechatOwner</span><span style="color:#E6EDF3">(body.code)</span></span>
<span class="line"><span style="color:#FF7B72">      const</span><span style="color:#79C0FF"> accessToken</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> randomBytes</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">32</span><span style="color:#E6EDF3">).</span><span style="color:#D2A8FF">toString</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'hex'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">      const</span><span style="color:#79C0FF"> expiresAt</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> Date.</span><span style="color:#D2A8FF">now</span><span style="color:#E6EDF3">() </span><span style="color:#FF7B72">+</span><span style="color:#79C0FF"> 24</span><span style="color:#FF7B72"> *</span><span style="color:#79C0FF"> 60</span><span style="color:#FF7B72"> *</span><span style="color:#79C0FF"> 60</span><span style="color:#FF7B72"> *</span><span style="color:#79C0FF"> 1000</span></span>
<span class="line"><span style="color:#E6EDF3">      db.</span><span style="color:#D2A8FF">prepare</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'DELETE FROM sessions WHERE expires_at &#x3C;= ?'</span><span style="color:#E6EDF3">).</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(Date.</span><span style="color:#D2A8FF">now</span><span style="color:#E6EDF3">())</span></span>
<span class="line"><span style="color:#E6EDF3">      db.</span><span style="color:#D2A8FF">prepare</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'INSERT INTO sessions VALUES (?, ?, ?)'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">        .</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(</span><span style="color:#D2A8FF">hash</span><span style="color:#E6EDF3">(accessToken), owner, expiresAt)</span></span>
<span class="line"><span style="color:#E6EDF3">      data </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> { accessToken, expiresAt }</span></span>
<span class="line"><span style="color:#E6EDF3">    } </span><span style="color:#FF7B72">else</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">      const</span><span style="color:#79C0FF"> owner</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> ownerOf</span><span style="color:#E6EDF3">(req)</span></span>
<span class="line"><span style="color:#FF7B72">      const</span><span style="color:#79C0FF"> match</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> /</span><span style="color:#FF7B72">^</span><span style="color:#7EE787;font-weight:bold">\/</span><span style="color:#A5D6FF">todos</span><span style="color:#7EE787;font-weight:bold">\/</span><span style="color:#A5D6FF">(</span><span style="color:#79C0FF">\d</span><span style="color:#FF7B72">+</span><span style="color:#A5D6FF">)</span><span style="color:#FF7B72">$</span><span style="color:#A5D6FF">/</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">exec</span><span style="color:#E6EDF3">(url.pathname)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (req.method </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'GET'</span><span style="color:#FF7B72"> &#x26;&#x26;</span><span style="color:#E6EDF3"> url.pathname </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> '/todos'</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> rawCursor</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> url.searchParams.</span><span style="color:#D2A8FF">get</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'cursor'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> rawLimit</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> url.searchParams.</span><span style="color:#D2A8FF">get</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'limit'</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">??</span><span style="color:#A5D6FF"> '20'</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> cursor</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> rawCursor </span><span style="color:#FF7B72">===</span><span style="color:#79C0FF"> null</span><span style="color:#FF7B72"> ?</span><span style="color:#E6EDF3"> Number.MAX_SAFE_INTEGER </span><span style="color:#FF7B72">:</span><span style="color:#D2A8FF"> Number</span><span style="color:#E6EDF3">(rawCursor)</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> limit</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> Number</span><span style="color:#E6EDF3">(rawLimit)</span></span>
<span class="line"><span style="color:#FF7B72">        if</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#FF7B72">          !</span><span style="color:#E6EDF3">Number.</span><span style="color:#D2A8FF">isSafeInteger</span><span style="color:#E6EDF3">(cursor) </span><span style="color:#FF7B72">||</span><span style="color:#E6EDF3"> cursor </span><span style="color:#FF7B72">&#x3C;=</span><span style="color:#79C0FF"> 0</span><span style="color:#FF7B72"> ||</span></span>
<span class="line"><span style="color:#FF7B72">          !</span><span style="color:#E6EDF3">Number.</span><span style="color:#D2A8FF">isSafeInteger</span><span style="color:#E6EDF3">(limit) </span><span style="color:#FF7B72">||</span><span style="color:#E6EDF3"> limit </span><span style="color:#FF7B72">&#x3C;</span><span style="color:#79C0FF"> 1</span><span style="color:#FF7B72"> ||</span><span style="color:#E6EDF3"> limit </span><span style="color:#FF7B72">></span><span style="color:#79C0FF"> 50</span></span>
<span class="line"><span style="color:#E6EDF3">        ) </span><span style="color:#FF7B72">throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">400</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'分页参数不正确'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> rows</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> db.</span><span style="color:#D2A8FF">prepare</span><span style="color:#E6EDF3">(</span></span>
<span class="line"><span style="color:#A5D6FF">          'SELECT id, title, done FROM todos WHERE owner = ? AND id &#x3C; ? ORDER BY id DESC LIMIT ?'</span></span>
<span class="line"><span style="color:#E6EDF3">        ).</span><span style="color:#D2A8FF">all</span><span style="color:#E6EDF3">(owner, cursor, limit </span><span style="color:#FF7B72">+</span><span style="color:#79C0FF"> 1</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> hasMore</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> rows.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#E6EDF3"> limit</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> items</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> rows.</span><span style="color:#D2A8FF">slice</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">, limit).</span><span style="color:#D2A8FF">map</span><span style="color:#E6EDF3">(toTodo)</span></span>
<span class="line"><span style="color:#E6EDF3">        data </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> { items, nextCursor: hasMore </span><span style="color:#FF7B72">?</span><span style="color:#E6EDF3"> items[items.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> -</span><span style="color:#79C0FF"> 1</span><span style="color:#E6EDF3">].id </span><span style="color:#FF7B72">:</span><span style="color:#79C0FF"> null</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"><span style="color:#E6EDF3">      } </span><span style="color:#FF7B72">else</span><span style="color:#FF7B72"> if</span><span style="color:#E6EDF3"> (req.method </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'POST'</span><span style="color:#FF7B72"> &#x26;&#x26;</span><span style="color:#E6EDF3"> url.pathname </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> '/todos'</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> body</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> await</span><span style="color:#D2A8FF"> readJson</span><span style="color:#E6EDF3">(req)</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> result</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> db.</span><span style="color:#D2A8FF">prepare</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'INSERT INTO todos (owner, title) VALUES (?, ?)'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">          .</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(owner, </span><span style="color:#D2A8FF">titleOf</span><span style="color:#E6EDF3">(body.title))</span></span>
<span class="line"><span style="color:#E6EDF3">        data </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> toTodo</span><span style="color:#E6EDF3">(db.</span><span style="color:#D2A8FF">prepare</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'SELECT * FROM todos WHERE id = ?'</span><span style="color:#E6EDF3">).</span><span style="color:#D2A8FF">get</span><span style="color:#E6EDF3">(result.lastInsertRowid))</span></span>
<span class="line"><span style="color:#E6EDF3">        status </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> 201</span></span>
<span class="line"><span style="color:#E6EDF3">      } </span><span style="color:#FF7B72">else</span><span style="color:#FF7B72"> if</span><span style="color:#E6EDF3"> (match </span><span style="color:#FF7B72">&#x26;&#x26;</span><span style="color:#E6EDF3"> (req.method </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'PUT'</span><span style="color:#FF7B72"> ||</span><span style="color:#E6EDF3"> req.method </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'DELETE'</span><span style="color:#E6EDF3">)) {</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> id</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> Number</span><span style="color:#E6EDF3">(match[</span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">])</span></span>
<span class="line"><span style="color:#FF7B72">        if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">Number.</span><span style="color:#D2A8FF">isSafeInteger</span><span style="color:#E6EDF3">(id) </span><span style="color:#FF7B72">||</span><span style="color:#E6EDF3"> id </span><span style="color:#FF7B72">&#x3C;=</span><span style="color:#79C0FF"> 0</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">400</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'任务 ID 不正确'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> current</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> db.</span><span style="color:#D2A8FF">prepare</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'SELECT * FROM todos WHERE id = ? AND owner = ?'</span><span style="color:#E6EDF3">).</span><span style="color:#D2A8FF">get</span><span style="color:#E6EDF3">(id, owner)</span></span>
<span class="line"><span style="color:#FF7B72">        if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">current) </span><span style="color:#FF7B72">throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">404</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'任务不存在'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">        if</span><span style="color:#E6EDF3"> (req.method </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'DELETE'</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#E6EDF3">          db.</span><span style="color:#D2A8FF">prepare</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'DELETE FROM todos WHERE id = ? AND owner = ?'</span><span style="color:#E6EDF3">).</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(id, owner)</span></span>
<span class="line"><span style="color:#E6EDF3">          data </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> { id: </span><span style="color:#D2A8FF">String</span><span style="color:#E6EDF3">(id) }</span></span>
<span class="line"><span style="color:#E6EDF3">        } </span><span style="color:#FF7B72">else</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">          const</span><span style="color:#79C0FF"> body</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> await</span><span style="color:#D2A8FF"> readJson</span><span style="color:#E6EDF3">(req)</span></span>
<span class="line"><span style="color:#FF7B72">          const</span><span style="color:#79C0FF"> title</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> titleOf</span><span style="color:#E6EDF3">(body.title)</span></span>
<span class="line"><span style="color:#FF7B72">          if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">typeof</span><span style="color:#E6EDF3"> body.done </span><span style="color:#FF7B72">!==</span><span style="color:#A5D6FF"> 'boolean'</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">400</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'完成状态必须是布尔值'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">          db.</span><span style="color:#D2A8FF">prepare</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'UPDATE todos SET title = ?, done = ? WHERE id = ? AND owner = ?'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">            .</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(title, body.done </span><span style="color:#FF7B72">?</span><span style="color:#79C0FF"> 1</span><span style="color:#FF7B72"> :</span><span style="color:#79C0FF"> 0</span><span style="color:#E6EDF3">, id, owner)</span></span>
<span class="line"><span style="color:#E6EDF3">          data </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> { id: </span><span style="color:#D2A8FF">String</span><span style="color:#E6EDF3">(id), title, done: body.done }</span></span>
<span class="line"><span style="color:#E6EDF3">        }</span></span>
<span class="line"><span style="color:#E6EDF3">      } </span><span style="color:#FF7B72">else</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">        throw</span><span style="color:#D2A8FF"> problem</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">404</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">'接口不存在'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">      }</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#D2A8FF">    send</span><span style="color:#E6EDF3">(res, status, { code: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">, data })</span></span>
<span class="line"><span style="color:#E6EDF3">  } </span><span style="color:#FF7B72">catch</span><span style="color:#E6EDF3"> (error) {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> status</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> error.status </span><span style="color:#FF7B72">||</span><span style="color:#79C0FF"> 500</span></span>
<span class="line"><span style="color:#D2A8FF">    send</span><span style="color:#E6EDF3">(res, status, {</span></span>
<span class="line"><span style="color:#E6EDF3">      code: status,</span></span>
<span class="line"><span style="color:#E6EDF3">      message: status </span><span style="color:#FF7B72">===</span><span style="color:#79C0FF"> 500</span><span style="color:#FF7B72"> ?</span><span style="color:#A5D6FF"> '服务暂时不可用'</span><span style="color:#FF7B72"> :</span><span style="color:#E6EDF3"> error.message</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">server.requestTimeout </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> 10000</span></span>
<span class="line"><span style="color:#E6EDF3">server.headersTimeout </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> 10000</span></span>
<span class="line"><span style="color:#E6EDF3">server.</span><span style="color:#D2A8FF">listen</span><span style="color:#E6EDF3">(</span><span style="color:#D2A8FF">Number</span><span style="color:#E6EDF3">(process.env.</span><span style="color:#79C0FF">PORT</span><span style="color:#FF7B72"> ||</span><span style="color:#79C0FF"> 3001</span><span style="color:#E6EDF3">), </span><span style="color:#A5D6FF">'127.0.0.1'</span><span style="color:#E6EDF3">, () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">  console.</span><span style="color:#D2A8FF">log</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'Todo API: http://127.0.0.1:'</span><span style="color:#FF7B72"> +</span><span style="color:#E6EDF3"> server.</span><span style="color:#D2A8FF">address</span><span style="color:#E6EDF3">().port)</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
</code></pre>
<p>这份代码可以按四部分阅读：</p>
<ol>
<li>启动时读取配置，创建数据库和表。</li>
<li><code>readJson</code> 与 <code>titleOf</code> 校验请求体、长度和字段类型。</li>
<li>登录接口签发随机业务令牌，数据库保存其 SHA-256 摘要和过期时间。</li>
<li>任务接口校验会话，通过参数化 SQL 读写当前用户的数据。</li>
</ol>
<p>随机令牌代表本项目的业务登录态，不是微信的 <code>access_token</code>。客户端只拿到业务令牌，不会得到 <code>AppSecret</code> 或 <code>session_key</code>。</p>
<p>列表按递增 ID 的倒序返回，下一页继续查询 <code>id &lt; cursor</code>。列表前面增加新任务时，已经取得的游标仍能定位后面的数据，避免简单页码偏移带来的重复。本例写操作完成后会重新加载第一页。</p>
<h3>7.4 启动并检查接口</h3>
<p>进入 <code>todo-project/server/</code>，执行：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sh"><span class="line"><span style="color:#FFA657">node</span><span style="color:#79C0FF"> --env-file=.env</span><span style="color:#A5D6FF"> server.mjs</span></span>
</code></pre>
<p>终端会显示：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">Todo API: http://127.0.0.1:3001
</code></pre>
<p>保持这个终端运行，另开一个终端检查：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sh"><span class="line"><span style="color:#FFA657">curl</span><span style="color:#A5D6FF"> http://127.0.0.1:3001/health</span></span>
</code></pre>
<p>演示模式的预期响应是：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span><span style="color:#7EE787">"code"</span><span style="color:#E6EDF3">:</span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">,</span><span style="color:#7EE787">"data"</span><span style="color:#E6EDF3">:{</span><span style="color:#7EE787">"status"</span><span style="color:#E6EDF3">:</span><span style="color:#A5D6FF">"ok"</span><span style="color:#E6EDF3">,</span><span style="color:#7EE787">"mode"</span><span style="color:#E6EDF3">:</span><span style="color:#A5D6FF">"demo"</span><span style="color:#E6EDF3">}}</span></span>
</code></pre>
<p>后端默认只监听本机地址。下一步先用同一台电脑上的微信开发者工具联调；真机和正式环境的连接方式放在第十节。</p>
<h2>八、在小程序中封装请求、登录和任务接口</h2>
<h3>8.1 配置接口地址</h3>
<p>新建 <code>miniprogram/config.js</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-js"><span class="line"><span style="color:#79C0FF">module</span><span style="color:#E6EDF3">.</span><span style="color:#79C0FF">exports</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">  BASE_URL: </span><span style="color:#A5D6FF">'http://127.0.0.1:3001'</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">  DEMO_LOGIN: </span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">  TOKEN_KEY: </span><span style="color:#A5D6FF">'todo:access-token'</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>DEMO_LOGIN</code> 决定调用哪个登录入口，<code>TOKEN_KEY</code> 统一指定业务令牌的本地存储键。这里没有服务器私钥或微信 AppSecret。</p>
<h3>8.2 把 wx.request 封装为 Promise</h3>
<p>创建 <code>miniprogram/utils/request.js</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-js"><span class="line"><span style="color:#FF7B72">const</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">BASE_URL</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">TOKEN_KEY</span><span style="color:#E6EDF3"> } </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> require</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'../config'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> request</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">path</span><span style="color:#E6EDF3">, { </span><span style="color:#FFA657">method</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> 'GET'</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">data</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">auth</span><span style="color:#FF7B72"> =</span><span style="color:#79C0FF"> true</span><span style="color:#E6EDF3"> } </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> {}) {</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#FF7B72"> new</span><span style="color:#79C0FF"> Promise</span><span style="color:#E6EDF3">((</span><span style="color:#FFA657">resolve</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">reject</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> token</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> auth </span><span style="color:#FF7B72">?</span><span style="color:#E6EDF3"> wx.</span><span style="color:#D2A8FF">getStorageSync</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">TOKEN_KEY</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">:</span><span style="color:#A5D6FF"> ''</span></span>
<span class="line"><span style="color:#E6EDF3">    wx.</span><span style="color:#D2A8FF">request</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#E6EDF3">      url: </span><span style="color:#79C0FF">BASE_URL</span><span style="color:#FF7B72"> +</span><span style="color:#E6EDF3"> path,</span></span>
<span class="line"><span style="color:#E6EDF3">      method,</span></span>
<span class="line"><span style="color:#E6EDF3">      data,</span></span>
<span class="line"><span style="color:#E6EDF3">      timeout: </span><span style="color:#79C0FF">10000</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">      header: {</span></span>
<span class="line"><span style="color:#A5D6FF">        'content-type'</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">'application/json'</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FF7B72">        ...</span><span style="color:#E6EDF3">(token </span><span style="color:#FF7B72">?</span><span style="color:#E6EDF3"> { Authorization: </span><span style="color:#A5D6FF">'Bearer '</span><span style="color:#FF7B72"> +</span><span style="color:#E6EDF3"> token } </span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> {})</span></span>
<span class="line"><span style="color:#E6EDF3">      },</span></span>
<span class="line"><span style="color:#D2A8FF">      success</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">response</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">        const</span><span style="color:#79C0FF"> body</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> response.data</span></span>
<span class="line"><span style="color:#FF7B72">        if</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">          response.statusCode </span><span style="color:#FF7B72">&#x3C;</span><span style="color:#79C0FF"> 200</span><span style="color:#FF7B72"> ||</span><span style="color:#E6EDF3"> response.statusCode </span><span style="color:#FF7B72">>=</span><span style="color:#79C0FF"> 300</span><span style="color:#FF7B72"> ||</span></span>
<span class="line"><span style="color:#FF7B72">          !</span><span style="color:#E6EDF3">body </span><span style="color:#FF7B72">||</span><span style="color:#FF7B72"> typeof</span><span style="color:#E6EDF3"> body </span><span style="color:#FF7B72">!==</span><span style="color:#A5D6FF"> 'object'</span><span style="color:#FF7B72"> ||</span><span style="color:#E6EDF3"> body.code </span><span style="color:#FF7B72">!==</span><span style="color:#79C0FF"> 0</span></span>
<span class="line"><span style="color:#E6EDF3">        ) {</span></span>
<span class="line"><span style="color:#FF7B72">          const</span><span style="color:#79C0FF"> message</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> body </span><span style="color:#FF7B72">&#x26;&#x26;</span><span style="color:#FF7B72"> typeof</span><span style="color:#E6EDF3"> body.message </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'string'</span></span>
<span class="line"><span style="color:#FF7B72">            ?</span><span style="color:#E6EDF3"> body.message</span></span>
<span class="line"><span style="color:#FF7B72">            :</span><span style="color:#A5D6FF"> '服务返回异常'</span></span>
<span class="line"><span style="color:#FF7B72">          const</span><span style="color:#79C0FF"> error</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(message)</span></span>
<span class="line"><span style="color:#E6EDF3">          error.statusCode </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> response.statusCode</span></span>
<span class="line"><span style="color:#D2A8FF">          reject</span><span style="color:#E6EDF3">(error)</span></span>
<span class="line"><span style="color:#FF7B72">          return</span></span>
<span class="line"><span style="color:#E6EDF3">        }</span></span>
<span class="line"><span style="color:#D2A8FF">        resolve</span><span style="color:#E6EDF3">(body.data)</span></span>
<span class="line"><span style="color:#E6EDF3">      },</span></span>
<span class="line"><span style="color:#D2A8FF">      fail</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#D2A8FF">        reject</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'网络连接失败，请稍后重试'</span><span style="color:#E6EDF3">))</span></span>
<span class="line"><span style="color:#E6EDF3">      }</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"><span style="color:#E6EDF3">  })</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">module</span><span style="color:#E6EDF3">.</span><span style="color:#79C0FF">exports</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> { request }</span></span>
</code></pre>
<p>这里有三个关键点：</p>
<ul>
<li><code>wx.request</code> 本身不支持本文需要的 Promise 返回形式，所以在外面包装一层。</li>
<li>HTTP 401、404、500 也可能进入 <code>success</code>，必须继续检查 <code>statusCode</code>。</li>
<li>请求层保留状态码并抛出错误，页面再决定显示错误、重新登录还是提供重试。</li>
</ul>
<p>请求层没有自动重放写操作。创建任务等操作如果因为网络问题无法确认结果，应先重新加载列表，而不是无限重试创建。<a href="https://developers.weixin.qq.com/miniprogram/dev/api/network/request/wx.request.html">官方：wx.request</a></p>
<h3>8.3 建立业务登录态</h3>
<p>创建 <code>miniprogram/services/session.js</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-js"><span class="line"><span style="color:#FF7B72">const</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">request</span><span style="color:#E6EDF3"> } </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> require</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'../utils/request'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">DEMO_LOGIN</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">TOKEN_KEY</span><span style="color:#E6EDF3"> } </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> require</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'../config'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> getLoginCode</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#FF7B72"> new</span><span style="color:#79C0FF"> Promise</span><span style="color:#E6EDF3">((</span><span style="color:#FFA657">resolve</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">reject</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">    wx.</span><span style="color:#D2A8FF">login</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#D2A8FF">      success</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">result</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">        if</span><span style="color:#E6EDF3"> (result.code) </span><span style="color:#D2A8FF">resolve</span><span style="color:#E6EDF3">(result.code)</span></span>
<span class="line"><span style="color:#FF7B72">        else</span><span style="color:#D2A8FF"> reject</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'未获取到微信登录凭证'</span><span style="color:#E6EDF3">))</span></span>
<span class="line"><span style="color:#E6EDF3">      },</span></span>
<span class="line"><span style="color:#D2A8FF">      fail</span><span style="color:#E6EDF3">() { </span><span style="color:#D2A8FF">reject</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'微信登录失败'</span><span style="color:#E6EDF3">)) }</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"><span style="color:#E6EDF3">  })</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">async</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> login</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> path</span><span style="color:#FF7B72"> =</span><span style="color:#79C0FF"> DEMO_LOGIN</span><span style="color:#FF7B72"> ?</span><span style="color:#A5D6FF"> '/auth/demo-login'</span><span style="color:#FF7B72"> :</span><span style="color:#A5D6FF"> '/auth/wechat-login'</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> data</span><span style="color:#FF7B72"> =</span><span style="color:#79C0FF"> DEMO_LOGIN</span><span style="color:#FF7B72"> ?</span><span style="color:#E6EDF3"> {} </span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> { code: </span><span style="color:#FF7B72">await</span><span style="color:#D2A8FF"> getLoginCode</span><span style="color:#E6EDF3">() }</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> session</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> await</span><span style="color:#D2A8FF"> request</span><span style="color:#E6EDF3">(path, { method: </span><span style="color:#A5D6FF">'POST'</span><span style="color:#E6EDF3">, data, auth: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">session </span><span style="color:#FF7B72">||</span><span style="color:#FF7B72"> typeof</span><span style="color:#E6EDF3"> session.accessToken </span><span style="color:#FF7B72">!==</span><span style="color:#A5D6FF"> 'string'</span><span style="color:#FF7B72"> ||</span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">session.accessToken) {</span></span>
<span class="line"><span style="color:#FF7B72">    throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'登录响应格式不正确'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">  wx.</span><span style="color:#D2A8FF">setStorageSync</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">TOKEN_KEY</span><span style="color:#E6EDF3">, session.accessToken)</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">module</span><span style="color:#E6EDF3">.</span><span style="color:#79C0FF">exports</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> { login }</span></span>
</code></pre>
<p>演示模式下，这段代码直接请求本机演示登录接口；真实模式下，先通过 <code>wx.login</code> 获取 code，再提交给自己的后端。</p>
<p>真实微信登录的信息流是：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">小程序 wx.login → 临时 code
        ↓
自己的后端 → 微信 code2Session → OpenID
        ↓
自己的后端签发业务令牌
        ↓
小程序携带令牌访问任务接口
</code></pre>
<p><code>code</code> 只能使用一次，登录失败后重新获取，不要缓存起来重复提交。<code>wx.checkSession</code> 检查微信会话，不能代替本例后端对业务令牌的过期校验。<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/login.html">官方：小程序登录</a>、<a href="https://developers.weixin.qq.com/miniprogram/dev/server/API/user-login/api_code2session">code2Session</a></p>
<h3>8.4 封装任务的增删改查</h3>
<p>创建 <code>miniprogram/services/todos.js</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-js"><span class="line"><span style="color:#FF7B72">const</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">request</span><span style="color:#E6EDF3"> } </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> require</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'../utils/request'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">async</span><span style="color:#FF7B72"> function</span><span style="color:#D2A8FF"> listTodos</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">cursor</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> ''</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> query</span><span style="color:#FF7B72"> =</span><span style="color:#A5D6FF"> '?limit=20'</span><span style="color:#FF7B72"> +</span><span style="color:#E6EDF3"> (cursor </span><span style="color:#FF7B72">?</span><span style="color:#A5D6FF"> '&#x26;cursor='</span><span style="color:#FF7B72"> +</span><span style="color:#D2A8FF"> encodeURIComponent</span><span style="color:#E6EDF3">(cursor) </span><span style="color:#FF7B72">:</span><span style="color:#A5D6FF"> ''</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  const</span><span style="color:#79C0FF"> result</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> await</span><span style="color:#D2A8FF"> request</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'/todos'</span><span style="color:#FF7B72"> +</span><span style="color:#E6EDF3"> query)</span></span>
<span class="line"><span style="color:#FF7B72">  if</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#FF7B72">    !</span><span style="color:#E6EDF3">result </span><span style="color:#FF7B72">||</span><span style="color:#FF7B72"> !</span><span style="color:#E6EDF3">Array.</span><span style="color:#D2A8FF">isArray</span><span style="color:#E6EDF3">(result.items) </span><span style="color:#FF7B72">||</span></span>
<span class="line"><span style="color:#FF7B72">    !</span><span style="color:#E6EDF3">(result.nextCursor </span><span style="color:#FF7B72">===</span><span style="color:#79C0FF"> null</span><span style="color:#FF7B72"> ||</span><span style="color:#FF7B72"> typeof</span><span style="color:#E6EDF3"> result.nextCursor </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'string'</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">||</span></span>
<span class="line"><span style="color:#FF7B72">    !</span><span style="color:#E6EDF3">result.items.</span><span style="color:#D2A8FF">every</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">item</span><span style="color:#FF7B72"> =></span></span>
<span class="line"><span style="color:#E6EDF3">      item </span><span style="color:#FF7B72">&#x26;&#x26;</span><span style="color:#FF7B72"> typeof</span><span style="color:#E6EDF3"> item.id </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'string'</span><span style="color:#FF7B72"> &#x26;&#x26;</span></span>
<span class="line"><span style="color:#FF7B72">      typeof</span><span style="color:#E6EDF3"> item.title </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'string'</span><span style="color:#FF7B72"> &#x26;&#x26;</span><span style="color:#FF7B72"> typeof</span><span style="color:#E6EDF3"> item.done </span><span style="color:#FF7B72">===</span><span style="color:#A5D6FF"> 'boolean'</span></span>
<span class="line"><span style="color:#E6EDF3">    )</span></span>
<span class="line"><span style="color:#E6EDF3">  ) </span><span style="color:#FF7B72">throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'任务数据格式不正确'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> result</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#D2A8FF"> createTodo</span><span style="color:#FF7B72"> =</span><span style="color:#FFA657"> title</span><span style="color:#FF7B72"> =></span><span style="color:#D2A8FF"> request</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'/todos'</span><span style="color:#E6EDF3">, {</span></span>
<span class="line"><span style="color:#E6EDF3">  method: </span><span style="color:#A5D6FF">'POST'</span><span style="color:#E6EDF3">, data: { title }</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#D2A8FF"> updateTodo</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> (</span><span style="color:#FFA657">id</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">value</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#D2A8FF"> request</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'/todos/'</span><span style="color:#FF7B72"> +</span><span style="color:#D2A8FF"> encodeURIComponent</span><span style="color:#E6EDF3">(id), {</span></span>
<span class="line"><span style="color:#E6EDF3">  method: </span><span style="color:#A5D6FF">'PUT'</span><span style="color:#E6EDF3">, data: { title: value.title, done: value.done }</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#D2A8FF"> removeTodo</span><span style="color:#FF7B72"> =</span><span style="color:#FFA657"> id</span><span style="color:#FF7B72"> =></span><span style="color:#D2A8FF"> request</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'/todos/'</span><span style="color:#FF7B72"> +</span><span style="color:#D2A8FF"> encodeURIComponent</span><span style="color:#E6EDF3">(id), {</span></span>
<span class="line"><span style="color:#E6EDF3">  method: </span><span style="color:#A5D6FF">'DELETE'</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">module</span><span style="color:#E6EDF3">.</span><span style="color:#79C0FF">exports</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> { listTodos, createTodo, updateTodo, removeTodo }</span></span>
</code></pre>
<p>页面只调用这些业务函数，不需要重复拼接路径、设置认证头或检查统一响应格式。<code>listTodos</code> 还会校验列表结构，防止错误数据直接进入模板。</p>
<p>更新任务使用 <code>PUT</code>，同时传入标题和完成状态，与前面定义的接口保持一致。</p>
<h2>九、组装完整的小程序页面</h2>
<h3>9.1 更新任务组件，增加编辑和请求状态</h3>
<p>服务端操作存在等待和失败，因此本次把完成状态的操作改为按钮。组件收到后端确认后的新数据才改变展示，避免网络失败时开关先变了、实际任务却没有更新。</p>
<p><code>miniprogram/components/todo-item/todo-item.json</code> 沿用第五节内容：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "component"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "usingComponents"</span><span style="color:#E6EDF3">: {}</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>替换 <code>miniprogram/components/todo-item/todo-item.js</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-js"><span class="line"><span style="color:#D2A8FF">Component</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#E6EDF3">  properties: {</span></span>
<span class="line"><span style="color:#E6EDF3">    todo: { type: Object, value: { id: </span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">, title: </span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">, done: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3"> } },</span></span>
<span class="line"><span style="color:#E6EDF3">    busy: { type: Boolean, value: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3"> }</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"><span style="color:#E6EDF3">  methods: {</span></span>
<span class="line"><span style="color:#D2A8FF">    onToggle</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#79C0FF">      this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">triggerEvent</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'change'</span><span style="color:#E6EDF3">, { value: </span><span style="color:#FF7B72">!</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">.properties.todo.done })</span></span>
<span class="line"><span style="color:#E6EDF3">    },</span></span>
<span class="line"><span style="color:#D2A8FF">    onEdit</span><span style="color:#E6EDF3">() { </span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">triggerEvent</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'edit'</span><span style="color:#E6EDF3">) },</span></span>
<span class="line"><span style="color:#D2A8FF">    onRemove</span><span style="color:#E6EDF3">() { </span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">triggerEvent</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'remove'</span><span style="color:#E6EDF3">) }</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
</code></pre>
<p>替换 <code>miniprogram/components/todo-item/todo-item.wxml</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-html"><span class="line"><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"row"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"title {{todo.done ? 'done' : ''}}"</span><span style="color:#E6EDF3">>{{todo.title}}&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"actions"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> size</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"mini"</span><span style="color:#79C0FF"> disabled</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{busy}}"</span><span style="color:#79C0FF"> bindtap</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onToggle"</span><span style="color:#E6EDF3">>{{todo.done ? '撤销' : '完成'}}&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> size</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"mini"</span><span style="color:#79C0FF"> disabled</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{busy}}"</span><span style="color:#79C0FF"> bindtap</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onEdit"</span><span style="color:#E6EDF3">>编辑&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> size</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"mini"</span><span style="color:#79C0FF"> disabled</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{busy}}"</span><span style="color:#79C0FF"> bindtap</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onRemove"</span><span style="color:#E6EDF3">>删除&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
</code></pre>
<p>替换 <code>miniprogram/components/todo-item/todo-item.wxss</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-css"><span class="line"><span style="color:#79C0FF">.row</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">  margin-bottom</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">16</span><span style="color:#E6EDF3">rpx; </span><span style="color:#79C0FF">padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">24</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  border-radius</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">12</span><span style="color:#E6EDF3">rpx; </span><span style="color:#79C0FF">background</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#ffffff</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#79C0FF">.title</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">line-height</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1.6</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">word-break</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">break-all</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.done</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#9ca3af</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">text-decoration</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">line-through</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.actions</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">flex-wrap</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">wrap</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">margin-top</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">16</span><span style="color:#E6EDF3">rpx; }</span></span>
<span class="line"><span style="color:#79C0FF">.actions</span><span style="color:#7EE787"> button</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#79C0FF"> 12</span><span style="color:#E6EDF3">rpx </span><span style="color:#79C0FF">12</span><span style="color:#E6EDF3">rpx </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; }</span></span>
</code></pre>
<p><code>busy</code> 控制按钮禁用，避免请求尚未完成时再次点击。组件只上报完成、编辑、删除意图，依然由页面管理数据。</p>
<h3>9.2 替换首页配置与模板</h3>
<p>替换 <code>miniprogram/pages/index/index.json</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "navigationBarTitleText"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"我的待办"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "enablePullDownRefresh"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "backgroundTextStyle"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"dark"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "onReachBottomDistance"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">80</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "usingComponents"</span><span style="color:#E6EDF3">: {</span></span>
<span class="line"><span style="color:#7EE787">    "todo-item"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"/components/todo-item/todo-item"</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>enablePullDownRefresh</code> 打开页面下拉刷新，<code>onReachBottomDistance</code> 决定距离页面底部多远时触发加载。这里使用页面自身滚动；如果改成 <code>scroll-view</code>，要处理它的滚动事件。</p>
<p>替换 <code>miniprogram/pages/index/index.wxml</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-html"><span class="line"><span style="color:#E6EDF3">&#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"page"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"heading"</span><span style="color:#E6EDF3">>我的待办清单&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> wx:if</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{!ready}}"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"hint"</span><span style="color:#E6EDF3">>{{demoLogin ? '本机演示账号，用于学习联调' : '登录后查看自己的任务'}}&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> disabled</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{busy}}"</span><span style="color:#79C0FF"> bindtap</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onLoginTap"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      {{demoLogin ? '进入演示账号' : '微信登录'}}</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> wx:else</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"editor"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">input</span></span>
<span class="line"><span style="color:#79C0FF">        class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"input"</span><span style="color:#79C0FF"> value</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{draft}}"</span><span style="color:#79C0FF"> maxlength</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"80"</span></span>
<span class="line"><span style="color:#79C0FF">        placeholder</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"输入一项任务"</span><span style="color:#79C0FF"> disabled</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{busy}}"</span></span>
<span class="line"><span style="color:#79C0FF">        confirm-type</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"done"</span><span style="color:#79C0FF"> bindinput</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onInput"</span><span style="color:#79C0FF"> bindconfirm</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onAddTap"</span></span>
<span class="line"><span style="color:#E6EDF3">      /></span></span>
<span class="line"><span style="color:#E6EDF3">      &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> type</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"primary"</span><span style="color:#79C0FF"> size</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"mini"</span><span style="color:#79C0FF"> disabled</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{busy}}"</span><span style="color:#79C0FF"> bindtap</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onAddTap"</span><span style="color:#E6EDF3">>添加&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">todo-item</span></span>
<span class="line"><span style="color:#79C0FF">      wx:for</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{todos}}"</span><span style="color:#79C0FF"> wx:key</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"id"</span></span>
<span class="line"><span style="color:#79C0FF">      todo</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{item}}"</span><span style="color:#79C0FF"> busy</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{busy}}"</span><span style="color:#79C0FF"> data-id</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{item.id}}"</span></span>
<span class="line"><span style="color:#79C0FF">      bind:change</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onToggle"</span><span style="color:#79C0FF"> bind:edit</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onEdit"</span><span style="color:#79C0FF"> bind:remove</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onRemove"</span></span>
<span class="line"><span style="color:#E6EDF3">    /></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> wx:if</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{!busy &#x26;&#x26; !error &#x26;&#x26; todos.length === 0}}"</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"empty"</span><span style="color:#E6EDF3">>暂无任务&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> wx:if</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{hasMore &#x26;&#x26; !error}}"</span><span style="color:#79C0FF"> disabled</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{busy}}"</span><span style="color:#79C0FF"> bindtap</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onReachBottom"</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">      加载更多</span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">    &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> wx:if</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{!hasMore &#x26;&#x26; todos.length > 0}}"</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"hint"</span><span style="color:#E6EDF3">>已经到底了&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> wx:if</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{busy}}"</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"hint"</span><span style="color:#E6EDF3">>处理中…&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#79C0FF"> wx:if</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{error}}"</span><span style="color:#79C0FF"> class</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"error"</span><span style="color:#E6EDF3">>{{error}}&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">  &#x3C;</span><span style="color:#7EE787">button</span><span style="color:#79C0FF"> wx:if</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{error &#x26;&#x26; ready}}"</span><span style="color:#79C0FF"> disabled</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"{{busy}}"</span><span style="color:#79C0FF"> bindtap</span><span style="color:#E6EDF3">=</span><span style="color:#A5D6FF">"onRetry"</span><span style="color:#E6EDF3">>重新加载列表&#x3C;/</span><span style="color:#7EE787">button</span><span style="color:#E6EDF3">></span></span>
<span class="line"><span style="color:#E6EDF3">&#x3C;/</span><span style="color:#FFA198;font-style:italic">view</span><span style="color:#E6EDF3">></span></span>
</code></pre>
<p>这个模板包含登录入口、输入区、任务列表、空状态、处理中提示和错误提示。错误后的按钮明确写“重新加载列表”，避免把一次查询重试误认为再次执行删除或创建。</p>
<h3>9.3 替换首页逻辑</h3>
<p>替换 <code>miniprogram/pages/index/index.js</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-js"><span class="line"><span style="color:#FF7B72">const</span><span style="color:#79C0FF"> todosApi</span><span style="color:#FF7B72"> =</span><span style="color:#D2A8FF"> require</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'../../services/todos'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">login</span><span style="color:#E6EDF3"> } </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> require</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'../../services/session'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">const</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">DEMO_LOGIN</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">TOKEN_KEY</span><span style="color:#E6EDF3"> } </span><span style="color:#FF7B72">=</span><span style="color:#D2A8FF"> require</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'../../config'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">function</span><span style="color:#D2A8FF"> ask</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">options</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#FF7B72"> new</span><span style="color:#79C0FF"> Promise</span><span style="color:#E6EDF3">((</span><span style="color:#FFA657">resolve</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">reject</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#E6EDF3">    wx.</span><span style="color:#D2A8FF">showModal</span><span style="color:#E6EDF3">({ </span><span style="color:#FF7B72">...</span><span style="color:#E6EDF3">options, success: resolve, fail: reject })</span></span>
<span class="line"><span style="color:#E6EDF3">  })</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">Page</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#E6EDF3">  data: {</span></span>
<span class="line"><span style="color:#E6EDF3">    demoLogin: </span><span style="color:#79C0FF">DEMO_LOGIN</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    ready: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    draft: </span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    todos: [],</span></span>
<span class="line"><span style="color:#E6EDF3">    hasMore: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    busy: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    error: </span><span style="color:#A5D6FF">''</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onLoad</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">._alive </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> true</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">._busy </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> false</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">._cursor </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> null</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">async</span><span style="color:#E6EDF3"> () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">wx.</span><span style="color:#D2A8FF">getStorageSync</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">TOKEN_KEY</span><span style="color:#E6EDF3">)) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#79C0FF">      this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({ ready: </span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#FF7B72">      await</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">fetchPage</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onUnload</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">._alive </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> false</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onInput</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">event</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({ draft: event.detail.value })</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onLoginTap</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">async</span><span style="color:#E6EDF3"> () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">      await</span><span style="color:#D2A8FF"> login</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">._alive) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#79C0FF">      this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({ ready: </span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#FF7B72">      await</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">fetchPage</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onAddTap</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> title</span><span style="color:#FF7B72"> =</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.data.draft.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">title) {</span></span>
<span class="line"><span style="color:#E6EDF3">      wx.</span><span style="color:#D2A8FF">showToast</span><span style="color:#E6EDF3">({ title: </span><span style="color:#A5D6FF">'请先输入任务'</span><span style="color:#E6EDF3">, icon: </span><span style="color:#A5D6FF">'none'</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#FF7B72">      return</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">async</span><span style="color:#E6EDF3"> () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">      await</span><span style="color:#E6EDF3"> todosApi.</span><span style="color:#D2A8FF">createTodo</span><span style="color:#E6EDF3">(title)</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">._alive) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#79C0FF">      this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({ draft: </span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#FF7B72">      await</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">fetchPage</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onToggle</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">event</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> id</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> event.currentTarget.dataset.id</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> todo</span><span style="color:#FF7B72"> =</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.data.todos.</span><span style="color:#D2A8FF">find</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">item</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> item.id </span><span style="color:#FF7B72">===</span><span style="color:#E6EDF3"> id)</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">todo) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">async</span><span style="color:#E6EDF3"> () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">      await</span><span style="color:#E6EDF3"> todosApi.</span><span style="color:#D2A8FF">updateTodo</span><span style="color:#E6EDF3">(id, { title: todo.title, done: event.detail.value })</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">._alive) </span><span style="color:#FF7B72">await</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">fetchPage</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onEdit</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">event</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> id</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> event.currentTarget.dataset.id</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> todo</span><span style="color:#FF7B72"> =</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.data.todos.</span><span style="color:#D2A8FF">find</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">item</span><span style="color:#FF7B72"> =></span><span style="color:#E6EDF3"> item.id </span><span style="color:#FF7B72">===</span><span style="color:#E6EDF3"> id)</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">todo) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">async</span><span style="color:#E6EDF3"> () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">      const</span><span style="color:#79C0FF"> result</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> await</span><span style="color:#D2A8FF"> ask</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#E6EDF3">        title: </span><span style="color:#A5D6FF">'编辑任务'</span><span style="color:#E6EDF3">, editable: </span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">, content: todo.title,</span></span>
<span class="line"><span style="color:#E6EDF3">        placeholderText: </span><span style="color:#A5D6FF">'输入 1 到 80 个字符'</span></span>
<span class="line"><span style="color:#E6EDF3">      })</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">result.confirm </span><span style="color:#FF7B72">||</span><span style="color:#FF7B72"> !</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">._alive) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#FF7B72">      const</span><span style="color:#79C0FF"> title</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> result.content.</span><span style="color:#D2A8FF">trim</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">title </span><span style="color:#FF7B72">||</span><span style="color:#E6EDF3"> title.</span><span style="color:#79C0FF">length</span><span style="color:#FF7B72"> ></span><span style="color:#79C0FF"> 80</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">throw</span><span style="color:#FF7B72"> new</span><span style="color:#D2A8FF"> Error</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">'任务名称需要包含 1 到 80 个字符'</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">      await</span><span style="color:#E6EDF3"> todosApi.</span><span style="color:#D2A8FF">updateTodo</span><span style="color:#E6EDF3">(id, { title, done: todo.done })</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">._alive) </span><span style="color:#FF7B72">await</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">fetchPage</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onRemove</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">event</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> id</span><span style="color:#FF7B72"> =</span><span style="color:#E6EDF3"> event.currentTarget.dataset.id</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">async</span><span style="color:#E6EDF3"> () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">      const</span><span style="color:#79C0FF"> result</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> await</span><span style="color:#D2A8FF"> ask</span><span style="color:#E6EDF3">({ title: </span><span style="color:#A5D6FF">'删除任务'</span><span style="color:#E6EDF3">, content: </span><span style="color:#A5D6FF">'确定删除这项任务吗？'</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#E6EDF3">result.confirm </span><span style="color:#FF7B72">||</span><span style="color:#FF7B72"> !</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">._alive) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#FF7B72">      await</span><span style="color:#E6EDF3"> todosApi.</span><span style="color:#D2A8FF">removeTodo</span><span style="color:#E6EDF3">(id)</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">._alive) </span><span style="color:#FF7B72">await</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">fetchPage</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onRetry</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">fetchPage</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">))</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onReachBottom</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">.data.ready </span><span style="color:#FF7B72">||</span><span style="color:#FF7B72"> !</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">.data.hasMore) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">fetchPage</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3">))</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#D2A8FF">  onPullDownRefresh</span><span style="color:#E6EDF3">() {</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">run</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">async</span><span style="color:#E6EDF3"> () </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">.data.ready) </span><span style="color:#FF7B72">await</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">fetchPage</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#E6EDF3">    }).</span><span style="color:#D2A8FF">finally</span><span style="color:#E6EDF3">(() </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> wx.</span><span style="color:#D2A8FF">stopPullDownRefresh</span><span style="color:#E6EDF3">())</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  async</span><span style="color:#D2A8FF"> fetchPage</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">reset</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">    const</span><span style="color:#79C0FF"> result</span><span style="color:#FF7B72"> =</span><span style="color:#FF7B72"> await</span><span style="color:#E6EDF3"> todosApi.</span><span style="color:#D2A8FF">listTodos</span><span style="color:#E6EDF3">(reset </span><span style="color:#FF7B72">?</span><span style="color:#A5D6FF"> ''</span><span style="color:#FF7B72"> :</span><span style="color:#79C0FF"> this</span><span style="color:#E6EDF3">._cursor)</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">._alive) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">._cursor </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> result.nextCursor</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({</span></span>
<span class="line"><span style="color:#E6EDF3">      todos: reset </span><span style="color:#FF7B72">?</span><span style="color:#E6EDF3"> result.items </span><span style="color:#FF7B72">:</span><span style="color:#E6EDF3"> [</span><span style="color:#FF7B72">...</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">.data.todos, </span><span style="color:#FF7B72">...</span><span style="color:#E6EDF3">result.items],</span></span>
<span class="line"><span style="color:#E6EDF3">      hasMore: result.nextCursor </span><span style="color:#FF7B72">!==</span><span style="color:#79C0FF"> null</span></span>
<span class="line"><span style="color:#E6EDF3">    })</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  async</span><span style="color:#D2A8FF"> run</span><span style="color:#E6EDF3">(</span><span style="color:#FFA657">action</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#E6EDF3"> (</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">._busy </span><span style="color:#FF7B72">||</span><span style="color:#FF7B72"> !</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">._alive) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">._busy </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> true</span></span>
<span class="line"><span style="color:#79C0FF">    this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({ busy: </span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">, error: </span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#FF7B72">    try</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#FF7B72">      await</span><span style="color:#D2A8FF"> action</span><span style="color:#E6EDF3">()</span></span>
<span class="line"><span style="color:#E6EDF3">    } </span><span style="color:#FF7B72">catch</span><span style="color:#E6EDF3"> (error) {</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#FF7B72">!</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">._alive) </span><span style="color:#FF7B72">return</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (error.statusCode </span><span style="color:#FF7B72">===</span><span style="color:#79C0FF"> 401</span><span style="color:#E6EDF3">) {</span></span>
<span class="line"><span style="color:#E6EDF3">        wx.</span><span style="color:#D2A8FF">removeStorageSync</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">TOKEN_KEY</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#79C0FF">        this</span><span style="color:#E6EDF3">._cursor </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> null</span></span>
<span class="line"><span style="color:#79C0FF">        this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({ ready: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3">, draft: </span><span style="color:#A5D6FF">''</span><span style="color:#E6EDF3">, todos: [], hasMore: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#E6EDF3">      }</span></span>
<span class="line"><span style="color:#79C0FF">      this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({ error: error.message </span><span style="color:#FF7B72">||</span><span style="color:#A5D6FF"> '操作失败，请重试'</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#E6EDF3">    } </span><span style="color:#FF7B72">finally</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">      this</span><span style="color:#E6EDF3">._busy </span><span style="color:#FF7B72">=</span><span style="color:#79C0FF"> false</span></span>
<span class="line"><span style="color:#FF7B72">      if</span><span style="color:#E6EDF3"> (</span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">._alive) </span><span style="color:#79C0FF">this</span><span style="color:#E6EDF3">.</span><span style="color:#D2A8FF">setData</span><span style="color:#E6EDF3">({ busy: </span><span style="color:#79C0FF">false</span><span style="color:#E6EDF3"> })</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">})</span></span>
</code></pre>
<p>页面逻辑可以沿着四条线理解：</p>
<p><strong>登录与恢复。</strong> 页面加载时检查是否保存过业务令牌，有令牌就读取列表；没有令牌就显示登录入口。服务器返回 401 后清除失效令牌和当前账号列表，回到登录状态。</p>
<p><strong>写入与回显。</strong> 添加、编辑、完成、删除都先调用接口，再读取第一页。前面的本地 <code>commitTodos</code> 被服务端数据源替代，数据库成为任务的保存位置。基础版已经存在的本地任务不会自动上传，这里从服务端任务列表开始。</p>
<p><strong>分页与刷新。</strong> <code>_cursor</code> 只保存下一页位置，成功读取后才更新；<code>fetchPage(true)</code> 替换列表，<code>fetchPage(false)</code> 追加下一页。下拉刷新的结束动作放在 <code>finally</code>，请求失败时也会收起刷新状态。</p>
<p><strong>并发与卸载。</strong> <code>_busy</code> 阻止重复操作，<code>data.busy</code> 控制界面禁用。每次异步返回后检查 <code>_alive</code>，避免已经退出页面后再更新它。</p>
<p><code>run</code> 只是把这些操作共有的等待和错误处理收在一起，任务接口仍在 <code>services</code>，组件也不直接请求后端。</p>
<p>编辑使用 <code>wx.showModal</code> 的输入框能力，需要基础库支持 <code>editable</code>。本例使用回调封装，用户取消时不发出写请求。<a href="https://developers.weixin.qq.com/miniprogram/dev/api/ui/interaction/wx.showModal.html">官方：wx.showModal</a></p>
<h3>9.4 替换页面样式</h3>
<p>替换 <code>miniprogram/pages/index/index.wxss</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-css"><span class="line"><span style="color:#79C0FF">.page</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">32</span><span style="color:#E6EDF3">rpx; }</span></span>
<span class="line"><span style="color:#79C0FF">.heading</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">font-size</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">40</span><span style="color:#E6EDF3">rpx; </span><span style="color:#79C0FF">font-weight</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">600</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.hint</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">20</span><span style="color:#E6EDF3">rpx </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#6b7280</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.editor</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">display</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">flex</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">align-items</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">center</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">32</span><span style="color:#E6EDF3">rpx </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.input</span><span style="color:#E6EDF3"> {</span></span>
<span class="line"><span style="color:#79C0FF">  flex</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">min-width</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">height</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">80</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  margin-right</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">16</span><span style="color:#E6EDF3">rpx; </span><span style="color:#79C0FF">padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#79C0FF"> 20</span><span style="color:#E6EDF3">rpx;</span></span>
<span class="line"><span style="color:#79C0FF">  border-radius</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">12</span><span style="color:#E6EDF3">rpx; </span><span style="color:#79C0FF">background</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#ffffff</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#79C0FF">.empty</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">padding</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">64</span><span style="color:#E6EDF3">rpx </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#6b7280</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">text-align</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">center</span><span style="color:#E6EDF3">; }</span></span>
<span class="line"><span style="color:#79C0FF">.error</span><span style="color:#E6EDF3"> { </span><span style="color:#79C0FF">margin</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">24</span><span style="color:#E6EDF3">rpx </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">color</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">#b91c1c</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">word-break</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">break-all</span><span style="color:#E6EDF3">; }</span></span>
</code></pre>
<p>任务按钮放到标题下方，长标题和窄屏都能自然换行；页面样式与组件内部样式分别维护。至此，前后端需要编写的业务文件已经齐全。</p>
<h2>十、从本机联调切换到真实微信登录</h2>
<h3>10.1 先完成一次本机业务流程</h3>
<p>确认后端正在运行，<code>config.js</code> 中的地址仍为 <code>http://127.0.0.1:3001</code>，<code>DEMO_LOGIN</code> 为 <code>true</code>。</p>
<p>在开发工具中临时启用“不校验合法域名、TLS 版本及 HTTPS 证书”相关调试选项，再点击编译。这个设置用于本机调试，正式验收要关闭。</p>
<p>然后按下面顺序操作：</p>
<ol>
<li>点击“进入演示账号”，看到空列表或上次保留的任务。</li>
<li>添加“学习 WXML”“封装请求”“完成联调”三项任务。</li>
<li>编辑其中一项，再点击完成、撤销，检查列表变化。</li>
<li>删除一项任务，分别检查取消和确认两种结果。</li>
<li>重新编译小程序，再重启后端，确认任务仍然存在。</li>
<li>添加超过 20 项任务，检查触底和“加载更多”是否追加下一页。</li>
</ol>
<p>这些操作走的是实际 HTTP 接口和 SQLite。演示账号只替代了微信身份获取步骤，没有把任务保存在内存数组里。</p>
<h3>10.2 用可观察的结果验收异常情况</h3>
<table>
<thead>
<tr>
<th>场景</th>
<th>操作方法</th>
<th>预期结果</th>
</tr>
</thead>
<tbody>
<tr>
<td>空标题</td>
<td>输入空格后添加</td>
<td>提示输入任务，不创建记录</td>
</tr>
<tr>
<td>连续点击</td>
<td>快速重复点击添加</td>
<td>本轮操作只提交一次</td>
</tr>
<tr>
<td>删除取消</td>
<td>在确认框点取消</td>
<td>任务保持原样</td>
</tr>
<tr>
<td>接口不可达</td>
<td>停止后端后请求列表</td>
<td>显示错误，恢复后端后可以重新加载</td>
</tr>
<tr>
<td>请求失败</td>
<td>写入未成功返回</td>
<td>不在页面上提前确认完成或删除</td>
</tr>
<tr>
<td>页面退出</td>
<td>请求未结束时离开页面</td>
<td>旧结果不更新已卸载页面</td>
</tr>
<tr>
<td>会话过期</td>
<td>使用已过期或无效令牌请求</td>
<td>清理当前列表，回到登录入口</td>
</tr>
<tr>
<td>多账号隔离</td>
<td>用两个真实微信账号分别登录</td>
<td>各自只看到和操作自己的任务</td>
</tr>
</tbody>
</table>
<p>单个终端的演示账号不能验证两个真实微信账号的登录过程。真实账号隔离要在下一步切换登录方式后验收。</p>
<p>本例每次写入后重新加载第一页，流程容易确认。列表规模变大时，可以保留当前滚动位置、局部更新任务，并处理多设备并发修改；这些优化应在基本流程稳定后再做。</p>
<h3>10.3 启用真实微信登录</h3>
<p>先准备与小程序项目一致的 AppID 和 AppSecret，只把它们放到后端配置中。将 <code>server/.env</code> 改为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-ini"><span class="line"><span style="color:#FF7B72">NODE_ENV</span><span style="color:#E6EDF3">=production</span></span>
<span class="line"><span style="color:#FF7B72">DEMO_AUTH</span><span style="color:#E6EDF3">=0</span></span>
<span class="line"><span style="color:#FF7B72">PORT</span><span style="color:#E6EDF3">=3001</span></span>
<span class="line"><span style="color:#FF7B72">DATABASE_PATH</span><span style="color:#E6EDF3">=./todo.sqlite</span></span>
<span class="line"><span style="color:#FF7B72">WECHAT_APP_ID</span><span style="color:#E6EDF3">=填写你的小程序AppID</span></span>
<span class="line"><span style="color:#FF7B72">WECHAT_APP_SECRET</span><span style="color:#E6EDF3">=填写你的小程序AppSecret</span></span>
</code></pre>
<p>停止并重新启动服务，让新配置生效。切换后，演示登录入口不再提供演示会话；真实登录必须由微信校验 code。</p>
<p>再把 <code>miniprogram/config.js</code> 中的 <code>DEMO_LOGIN</code> 改为 <code>false</code>，清除之前演示登录使用的业务令牌后重新登录。可在开发工具清理对应缓存，或临时执行 <code>wx.removeStorageSync('todo:access-token')</code>。这里仅更换模式，不会把演示账号的任务迁移到真实账号。</p>
<p>同一台电脑上的开发工具仍可在本机调试设置下访问该服务。手机真机和正式版需要下一步的 HTTPS 地址。</p>
<h3>10.4 真机为什么不能直接访问电脑的 127.0.0.1？</h3>
<p>手机里的 <code>127.0.0.1</code> 指向手机本身。本文后端默认又只监听电脑本机，因此不能把这个地址原样留给手机使用。</p>
<p>真机和正式环境采用以下连接方式：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">手机小程序
    ↓ HTTPS
已配置的合法 request 域名
    ↓ 反向代理
服务器上的 127.0.0.1:3001
    ↓
SQLite 数据库
</code></pre>
<p>在自己的服务器运行后端，通过现有 Web 服务器配置 HTTPS 反向代理，把客户端 <code>BASE_URL</code> 改为实际的 HTTPS 地址，并在小程序后台添加对应的 request 合法域名。<code>https://api.example.com</code> 只是地址写法示意。</p>
<p>关闭开发工具的校验豁免，再用真机检查域名、证书、网络与登录。小程序访问自己的后端，后端再请求 <code>api.weixin.qq.com</code>，AppSecret 不经过小程序。<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html">官方：网络使用说明</a></p>
<h2>十一、实战之后，怎样优化和上线？</h2>
<h3>11.1 把性能问题拆开定位</h3>
<table>
<thead>
<tr>
<th>问题</th>
<th>优先检查</th>
<th>改进方向</th>
</tr>
</thead>
<tbody>
<tr>
<td>页面更新卡顿</td>
<td>是否反复提交整个大对象</td>
<td>合并更新，按字段或数据路径更新</td>
</tr>
<tr>
<td>列表滚动变慢</td>
<td>节点数量、图片和组件复杂度</td>
<td>分页、图片压缩、合理拆分组件</td>
</tr>
<tr>
<td>首页打开慢</td>
<td>主包大小和首屏依赖</td>
<td>把非首屏功能放进普通分包</td>
</tr>
<tr>
<td>页面隐藏后仍耗电</td>
<td>定时器、轮询和高频更新</td>
<td>隐藏时暂停，卸载时清理</td>
</tr>
</tbody>
</table>
<p>前面使用整页等待和写后刷新，是为了让业务结果容易理解。进一步优化时，先测量，再决定是否引入按任务禁用、局部更新或更复杂的状态管理。<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/performance/tips/runtime_setData.html">官方：合理使用数据更新方法</a></p>
<p>个人中心、报表等非首页功能可以考虑普通分包。tabBar 页面应放在主包，分包引用规则要按所用能力核对。<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/basic.html">官方：使用分包</a></p>
<h3>11.2 哪些地方还要按正式产品要求补齐？</h3>
<p>这套代码覆盖学习所需的身份校验、用户隔离、任务 CRUD、游标分页和落盘保存。正式运营时，还需要结合业务补齐：</p>
<ul>
<li><strong>服务运维</strong>：进程管理、HTTPS、请求限流、监控和数据库备份。数据库目录放在持久位置，不随代码发布一起覆盖。</li>
<li><strong>登录管理</strong>：令牌撤销、退出、会话数量控制及异常登录处理，避免长期积累有效会话。</li>
<li><strong>数据一致性</strong>：本例修改采用最后一次写入生效，多设备同时编辑时可增加版本号检查；需要安全重试的创建接口应设计幂等机制。</li>
<li><strong>容量评估</strong>：同步 SQLite 适合本例的小规模教学服务，高负载下应评估阻塞、连接方式和数据库方案。</li>
</ul>
<p>微信登录也不会自动授予读取手机号、头像昵称或位置的权限。只在用户需要相关功能时请求授权，并让隐私保护指引与实际使用一致。<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/user-privacy/PrivacyAuthorize.html">官方：小程序隐私协议开发指南</a></p>
<h3>11.3 上传、审核和发布分别意味着什么？</h3>
<p>完成真机验收后，按以下流程发布：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">本地编译与真机检查
        ↓
开发者工具上传版本
        ↓
配置并验收体验版
        ↓
小程序后台提交审核
        ↓
审核通过后发布
</code></pre>
<p>后端服务和数据库需要单独运行。上传小程序代码不会把 Node.js 服务、数据库或后端配置一起部署。</p>
<p>发布前再检查正式接口地址、真实登录开关、账号权限、合法域名和隐私配置，避免把本机演示配置带入正式版。上传代码、提交审核与正式发布是不同步骤。<a href="https://developers.weixin.qq.com/miniprogram/dev/framework/quickstart/release.html">官方：协同工作与发布</a></p>
<h2>十二、常见问题排查</h2>
<table>
<thead>
<tr>
<th>问题</th>
<th>常见原因</th>
<th>排查方法</th>
</tr>
</thead>
<tbody>
<tr>
<td>数据变了，界面没变化</td>
<td>直接给 <code>this.data</code> 赋值</td>
<td>通过 <code>setData</code> 更新模板所用字段</td>
</tr>
<tr>
<td>事件中没有任务 ID</td>
<td>读取了错误的节点</td>
<td>检查组件上的 <code>data-id</code> 和 <code>currentTarget.dataset</code></td>
</tr>
<tr>
<td>组件不显示</td>
<td>注册路径或文件名不一致</td>
<td>检查 <code>usingComponents</code> 和四个组件文件</td>
</tr>
<tr>
<td>后端启动时报 SQLite 错误</td>
<td>Node 版本过低或数据库目录不可写</td>
<td>核对 Node 24 与 <code>DATABASE_PATH</code></td>
</tr>
<tr>
<td>登录接口返回 400</td>
<td>前后端演示开关不一致</td>
<td>检查 <code>DEMO_LOGIN</code>、<code>DEMO_AUTH</code>，重启并重新编译</td>
</tr>
<tr>
<td>切换模式后仍看到演示数据</td>
<td>仍保留演示账号业务令牌</td>
<td>清理对应令牌，再用真实微信登录</td>
</tr>
<tr>
<td>所有任务接口都返回 401</td>
<td>未登录或业务令牌过期</td>
<td>检查认证头、会话过期时间和登录流程</td>
</tr>
<tr>
<td>工具能请求，手机不行</td>
<td>手机使用了本机地址或依赖校验豁免</td>
<td>检查实际 HTTPS 地址、合法域名与证书</td>
</tr>
<tr>
<td>后端成功写入，页面暂未刷新</td>
<td>随后的列表查询失败</td>
<td>恢复连接后重新加载列表，先确认结果</td>
</tr>
<tr>
<td>任务换页重复或漏项</td>
<td>游标更新时机或排序规则不一致</td>
<td>成功后再更新游标，保持后端排序规则一致</td>
</tr>
<tr>
<td>重启后数据不见了</td>
<td>更换了数据库路径或启动目录</td>
<td>核对数据库文件实际位置与持久化目录</td>
</tr>
</tbody>
</table>
<p>学完后，可以不看原代码重新走一遍：创建页面、绑定事件、管理本地状态、拆分组件、定义接口、保存数据库、建立登录态，再用正常和异常两类操作验收。能够独立完成这条链路，就具备继续开发表单、预约和内容管理类小程序的基础。</p>
]]></content:encoded>
    </item>
    <item>
      <title>AI Agent Handbook：从基础到工程实践</title>
      <link>https://felix.muke.chat/notes/ai-agent-handbook</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/ai-agent-handbook</guid>
      <pubDate>Mon, 02 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>Agent 的架构、任务循环、上下文、工具、运行时、安全与调优关键机制。</description>
      <category>AI Agent</category>
      <category>Agent</category>
      <category>Harness</category>
      <category>智能体工程</category>
      <content:encoded><![CDATA[<h2>第 1 章：AI 原生应用的新阶段</h2>
<h3>1.1 什么是 Agent，它与聊天机器人的区别是什么？</h3>
<p>聊天应用通常以“请求一次、回答一次”为基本单位。即使加入多轮对话和知识库，主要交付物仍然是一段回答。Agent 则围绕一个目标持续推进：观察当前情况，选择行动，执行工具，读取反馈，再决定继续、调整、求助或结束。</p>
<p>例如，用户提出“生成上个月的销售月报”。普通聊天应用可以给出写作建议；Agent 可以查询订单、检查退款口径、生成文件，并根据查询失败或数据缺失调整后续步骤。最终需要检查的是报告和数据是否正确。</p>
<p>工程上可以把 Agent 拆成两部分：<strong>Model + Harness</strong>。Model 负责理解和决策；Harness 是围绕模型构建的执行系统，负责提供信息、管理状态、调用工具、限制权限及验证结果。</p>
<h3>1.2 RAG、工作流、Copilot 和 Agent 应该怎样选？</h3>
<table>
<thead>
<tr>
<th>形态</th>
<th>谁决定主要执行路径</th>
<th>适合的问题</th>
<th>需要注意什么</th>
</tr>
</thead>
<tbody>
<tr>
<td>Chat / RAG</td>
<td>应用组织检索与回答</td>
<td>查询制度、解释知识</td>
<td>检索到资料不代表资料正确或适用</td>
</tr>
<tr>
<td>Workflow</td>
<td>预设步骤与分支</td>
<td>固定审批、格式转换</td>
<td>未覆盖的异常需要额外处理</td>
</tr>
<tr>
<td>Copilot</td>
<td>人持续判断和操作</td>
<td>辅助写作、编码、分析</td>
<td>人需要投入过程监督</td>
</tr>
<tr>
<td>Single-Agent</td>
<td>模型在边界内选择行动</td>
<td>路径不完全确定的任务</td>
<td>要限制行动范围并验证结果</td>
</tr>
<tr>
<td>Multi-Agent</td>
<td>多个角色协作完成任务</td>
<td>可按专业或责任拆分的工作</td>
<td>增加通信、协调和整合成本</td>
</tr>
</tbody>
</table>
<p>这些形态可以组合。例如，用工作流固定“生成草稿、审批、发送”三个阶段，在生成草稿阶段让 Agent 自主查询和分析。这样既保留灵活性，也让发送边界清楚。</p>
<h3>1.3 长程任务与多 Agent 是一回事吗？</h3>
<p>长程任务描述时间跨度：可能运行数小时，跨越进程重启和人工等待。多 Agent 描述协作结构：由多个角色分工。一个 Agent 可以做长任务，多个 Agent 也可以在很短时间内完成一次协作。</p>
<p>选型时先看任务路径是否稳定、能否验收、错误代价多大。查询一个订单通常不需要复杂协作；只有单个执行者在专业能力、上下文或责任分工上出现明确瓶颈时，才值得增加角色。</p>
<h2>第 2 章：Agentic Application 参考架构</h2>
<h3>2.1 一套完整的 Agent 应用由什么组成？</h3>
<p>Agentic Application 包含模型和 Harness，还包含业务入口、企业数据、工具、运行环境与治理能力。可以先按职责理解这些组件：</p>
<table>
<thead>
<tr>
<th>职责</th>
<th>主要内容</th>
<th>月报场景中的例子</th>
</tr>
</thead>
<tbody>
<tr>
<td>定义业务目标</td>
<td>用户、任务范围、验收标准</td>
<td>统计哪个月，采用什么收入口径</td>
</tr>
<tr>
<td>组织任务执行</td>
<td>决策循环、上下文、工具选择</td>
<td>先查询，再检查，再生成文件</td>
</tr>
<tr>
<td>承载执行与数据</td>
<td>运行时、沙箱、状态、文件</td>
<td>保存任务进度及报表版本</td>
</tr>
<tr>
<td>约束与观测</td>
<td>身份、权限、预算、审计</td>
<td>限制数据范围，记录发送审批</td>
</tr>
<tr>
<td>持续优化</td>
<td>数据集、评价器、实验</td>
<td>检查新版本是否减少漏算退款</td>
</tr>
</tbody>
</table>
<p>这些职责不必各自对应一个微服务。小应用可以由同一个进程实现，但边界需要清楚，否则修改模型时容易连带改动任务恢复和权限逻辑。</p>
<h3>2.2 为什么要同时看组件、平台和生命周期？</h3>
<p>组件视图回答“有哪些能力”；平台视图回答“运行在哪里、谁负责”；生命周期视图回答“怎样构建、发布、运行和改进”。同一个状态存储，在三个视图中分别对应持久化能力、存储服务的责任归属，以及运行和调优共同使用的证据。</p>
<p>月报系统的一条主链路可以表示为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">用户目标 → 任务编排 → 模型决策 → 受控工具 → 数据与文件
                 ↑              ↓
                 └── 反馈与结果验证 ──┘

身份、权限、预算、版本和审计作用于整条链路
</code></pre>
<p>图中的先后关系用于说明一次执行，不代表所有组件必须按层拆分部署。</p>
<h3>2.3 哪些边界最容易混淆？</h3>
<p>首先是 <strong>Context 与 State</strong>：模型当前看到的内容可能经过裁剪，不能成为唯一的任务事实。其次是 <strong>编排与 Runtime</strong>：编排决定下一步做什么，运行时负责进程、资源和恢复。还有 <strong>工具描述与授权</strong>：模型知道某个工具，并不意味着当前用户可以执行它。</p>
<p>例如，更换模型供应商后，数据库权限、审批规则和报告版本记录应继续有效。这些能力放在确定性的应用与平台逻辑中，才能独立验证和维护。</p>
<h2>第 3 章：Harness 的构建方式和责任边界</h2>
<h3>3.1 有哪些常见的构建入口？</h3>
<p>构建入口决定了哪些机制已经由产品或平台实现，哪些需要团队自己补齐。常见方式可以分成四类：</p>
<table>
<thead>
<tr>
<th>方式</th>
<th>主要特点</th>
<th>团队需要重点承担或确认的责任</th>
</tr>
</thead>
<tbody>
<tr>
<td>代码框架</td>
<td>自行组织循环、工具、状态</td>
<td>开发灵活，运行和治理投入较多</td>
</tr>
<tr>
<td>产品化 Harness</td>
<td>通过 CLI、SDK、工作空间复用执行能力</td>
<td>确认可扩展点及产品默认行为</td>
</tr>
<tr>
<td>Managed Agents</td>
<td>平台承接部分会话和执行管理</td>
<td>确认状态、恢复、权限和数据边界</td>
</tr>
<tr>
<td>云端 Agent 产品</td>
<td>应用能力与云服务配套较完整</td>
<td>确认业务适配、集成成本及平台限制</td>
</tr>
</tbody>
</table>
<p>四类方式可以组合。例如，业务使用托管执行能力，同时保留自己的任务数据库与审批服务。不能仅凭“用了某个框架”，就判断系统已经具备生产可靠性。</p>
<h3>3.2 选型时应该比较哪些问题？</h3>
<p>除了开发体验，还要检查：是否需要修改每轮上下文；工具能否接入企业身份；中断后状态由谁恢复；任务数据保存在哪里；费用如何归属；平台故障时能否导出任务和产物。</p>
<p>这些问题决定长期维护成本。对一次性内部分析，自行实现大量平台能力可能不划算；对涉及客户数据和外部写入的应用，权限、恢复和审计又不能省略。</p>
<h3>3.3 使用托管服务后，业务责任交给谁？</h3>
<p>托管服务可以负责运行和扩缩容，但“什么算正确完成”仍需要应用定义。平台报告调用成功，通常只能证明某个接口按其契约返回，不能自动证明统计口径正确或收件人合法。</p>
<p>例如，月报系统选择托管 Agent 后，仍需自己确定退款如何计算、谁能查看数据、谁有审批权，以及邮件发送回执怎样关联任务。选型的成果应是一张责任清单，明确平台承诺和业务系统必须完成的部分。</p>
<h2>第 4 章：任务编排、长程推进与协作流转</h2>
<h3>4.1 Agent Loop 是怎样推进任务的？</h3>
<p>一次循环可以拆成准备、决策、行动、观察和验证。准备阶段读取目标、状态与必要资料；模型提出下一步；执行层检查并调用工具；观察阶段把真实结果交回系统；验证阶段判断是否达到目标。</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">读取任务与上下文 → 模型选择行动 → 检查权限并执行
       ↑                              ↓
       └──── 更新状态 ← 读取真实反馈 ────┘
                         ↓
                 满足验收条件后完成
</code></pre>
<p>如果数据库提示某字段不存在，下一轮应根据错误调整查询；如果查询已经成功，则应复用结果继续分析。每轮重新从头开始，会浪费预算，也容易丢失已确认的条件。</p>
<h3>4.2 为什么需要独立的任务状态机？</h3>
<p>聊天消息适合展示过程，状态机适合约束任务流转。以月报为例：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">CREATED → RUNNING → WAITING_APPROVAL → RUNNING → VERIFYING → COMPLETED
              └→ WAITING_INPUT / PAUSED / FAILED / CANCELLED
</code></pre>
<p>进入等待审批时，应保存报告版本、待审批内容和恢复条件，并释放暂时用不到的计算资源。恢复后先读取审批结果与任务版本，再继续执行。一个工具失败可以被修复，不必立刻判定整个任务失败。</p>
<h3>4.3 怎样控制长任务不失控？</h3>
<p>为任务设置步数、时间和费用边界；为阶段设置可检查的里程碑；为失败设置重试或求助条件。计划需要随着执行反馈更新，已经完成的阶段应附上文件、测试或回执等证据。</p>
<p>例如，查询重试后仍然缺少渠道数据，系统应进入等待输入或明确报告限制。最终完成条件可以是“指标核对通过、指定版本获批、发送服务确认接收”，不能只检查模型是否输出“已完成”。</p>
<h2>第 5 章：上下文、状态与可复用能力资产</h2>
<h3>5.1 Context、Session、Task 和 Workspace 怎么区分？</h3>
<p>模型一次请求能看到的信息称为 Context。它受窗口和费用限制，需要每轮重新组织。Session 保存交互过程，Task 保存业务目标与进度，Workspace 保存执行中的文件。一个任务可以跨多个会话，也可以在不同执行实例之间恢复。</p>
<table>
<thead>
<tr>
<th>对象</th>
<th>保存的内容</th>
<th>月报中的例子</th>
</tr>
</thead>
<tbody>
<tr>
<td>Context</td>
<td>当前决策需要的信息</td>
<td>本月口径、最近一次工具结果</td>
</tr>
<tr>
<td>Session</td>
<td>消息与交互记录</td>
<td>用户要求、补充说明和操作反馈</td>
</tr>
<tr>
<td>Task State</td>
<td>可恢复的任务事实</td>
<td>查询已完成，正在等待审批</td>
</tr>
<tr>
<td>Workspace</td>
<td>文件和中间结果</td>
<td>查询明细、脚本、报告草稿</td>
</tr>
<tr>
<td>Memory</td>
<td>经筛选的长期经验与偏好</td>
<td>用户偏好先展示结论再放明细</td>
</tr>
<tr>
<td>Knowledge</td>
<td>有来源和有效范围的知识</td>
<td>财务部门发布的收入确认规则</td>
</tr>
<tr>
<td>Skill</td>
<td>可复用的方法与辅助资源</td>
<td>月报制作步骤、脚本和检查方法</td>
</tr>
</tbody>
</table>
<p>例如，“上次任务中用户喜欢蓝色图表”可以作为偏好，但不能覆盖本次“使用黑白图表”的明确要求。收入政策更新后，也不能用旧记忆替代当前制度。</p>
<h3>5.2 上下文应该怎样装配？</h3>
<p>可以把 Context Builder 理解成一个信息编译器：先收集候选资料，再做权限过滤、可信度判断、相关性排序、去重和预算裁剪，最后得到本轮输入。</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">任务、历史、知识、记忆与工具说明
                ↓
权限过滤 → 来源与有效性检查 → 相关性排序 → 预算裁剪
                ↓
本轮 Context + 来源、版本和处理记录
</code></pre>
<p>应优先保留目标、约束、当前阶段和验收条件。大量相似历史消息可以合并；工具说明按任务需要披露；已过期结论需要标记或移除。记录来源和版本，才能在结果出错时解释模型当时依据了什么。</p>
<h3>5.3 历史太长时应该保留什么？</h3>
<p>压缩历史要保留已确认的决定、关键证据、失败尝试、未解决问题和文件位置。大结果可以退出窗口，但要留在工作空间中，支持后续按需读取。</p>
<p>例如，数据库返回十万条订单后，可将明细写入文件，只把总数、聚合结果、异常提示和文件引用交给模型。摘要需要明确“退款采用支付月份口径”；否则后续模型可能重新解释口径，造成前后结果不一致。</p>
<h2>第 6 章：受控执行、验证反馈与交付准备</h2>
<h3>6.1 模型生成工具调用后，系统还要做什么？</h3>
<p>工具调用表示模型提出了一个动作。执行系统仍要完成参数校验、身份绑定、权限判断、预算检查、必要审批、实际执行和结果记录。身份与租户应来自可信会话，不能直接采用模型随意填写的值。</p>
<p>工具设计应尽量表达清楚的业务动作。例如，<code>get_order</code>、<code>preview_report</code> 和 <code>send_approved_report</code> 比一个可以任意操作的 <code>manage_business</code> 更容易验证，也更容易限制权限。</p>
<p>工具结果也需要结构化：除了返回数据，还应说明成功、失败或结果未知，是否可以重试，以及原始结果和产物在哪里。这样下一轮才能正确选择行动。</p>
<h3>6.2 Function Calling、MCP 和 A2A 的区别是什么？</h3>
<table>
<thead>
<tr>
<th>概念</th>
<th>主要解决的问题</th>
<th>可以怎样理解</th>
</tr>
</thead>
<tbody>
<tr>
<td>Function Calling</td>
<td>模型怎样表达工具名称与参数</td>
<td>生成一个结构化调用意图</td>
</tr>
<tr>
<td>MCP</td>
<td>工具、资源等能力怎样被连接和访问</td>
<td>为能力接入提供协议</td>
</tr>
<tr>
<td>A2A</td>
<td>独立 Agent 怎样交接任务和结果</td>
<td>为远程协作提供任务交互方式</td>
</tr>
</tbody>
</table>
<p>接通协议以后，授权、业务正确性和失败处理依然需要实现。一个远程 Agent 返回结果，也要按照委派契约验收；MCP 服务列出了工具，也不意味着所有用户都能执行它们。</p>
<h3>6.3 审批怎样绑定到具体动作？</h3>
<p>可以使用“预览 → 审批 → 执行 → 复核”的过程。预览需要展示动作对象与影响范围；审批绑定收件人、附件和内容版本；执行前再次确认这些内容没有变化。</p>
<p>下面是一份应用内部的审批记录示意：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "task_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"report-2026-10"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "action"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"send_report"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "artifact_version"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"v3"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "recipients"</span><span style="color:#E6EDF3">: [</span><span style="color:#A5D6FF">"finance@example.com"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#7EE787">  "approval_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"approval-17"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "status"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"approved"</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>如果附件从 v3 改成 v4，执行层应让旧审批失效。发送接口确认成功后，还应保存回执；业务若要求确认投递，就要继续核对投递状态。前端显示的进度，也应来自这些实际事件。</p>
<h2>第 7 章：Agent 运行时与沙箱</h2>
<h3>7.1 沙箱隔离了哪些东西？</h3>
<p>Agent 执行代码或命令时，需要一个受控工作环境。沙箱可以限制进程、文件系统、网络、凭证、CPU、内存和执行时间，实际隔离强度取决于所采用的技术与配置。</p>
<p>例如，分析销售文件只需要读取指定目录和调用授权查询接口，就不应该顺带获得整个宿主机目录、生产数据库写权限或任意网络访问能力。提示词中的要求需要由真实权限兑现。</p>
<p>沙箱也不等于完整授权系统。即使进程被隔离，仍要检查当前用户能否访问挂载的数据、工具调用能否外发信息，以及日志里是否出现敏感内容。</p>
<h3>7.2 Runtime 与 Sandbox 分别负责什么？</h3>
<p>Sandbox 提供执行环境，Runtime 管理它的生命周期：何时创建、怎样连接、等待时如何休眠、失败后怎样恢复、结束后怎样回收。</p>
<p>长任务不必让同一个进程始终运行。可以在等待用户审批时保存任务状态和工作区，释放计算资源；审批到达后重新创建环境，挂载文件并接着执行。</p>
<table>
<thead>
<tr>
<th>需要保留什么</th>
<th>目的</th>
</tr>
</thead>
<tbody>
<tr>
<td>任务状态与事件</td>
<td>知道已经做到哪里</td>
</tr>
<tr>
<td>工作区文件或快照</td>
<td>保留脚本和中间结果</td>
</tr>
<tr>
<td>环境与依赖版本</td>
<td>尽量复现相同执行条件</td>
</tr>
<tr>
<td>外部动作回执</td>
<td>确认哪些操作已经发生</td>
</tr>
</tbody>
</table>
<h3>7.3 模板、快照和分叉有什么用？</h3>
<p>模板准备通用依赖，减少环境启动后的重复安装；快照保存某个阶段的环境与文件；分叉可以从共同起点尝试多个方案。在评测中，每个样本从受控起点开始，能减少上一次运行留下的污染。</p>
<p>例如，对同一个数据清洗问题比较两种脚本，可以从相同快照分出两个工作区，各自执行并比较结果。快照恢复只能恢复其覆盖的状态，已经发出的邮件不会因为文件回滚而自动撤回。</p>
<h2>第 8 章：Agent 状态存储与语义资产</h2>
<h3>8.1 Event Log、Checkpoint 和 Artifact 的区别是什么？</h3>
<p>状态存储要同时支持继续执行、解释过程和交付结果。不同对象承担不同职责：</p>
<table>
<thead>
<tr>
<th>对象</th>
<th>记录什么</th>
<th>恢复或使用方式</th>
</tr>
</thead>
<tbody>
<tr>
<td>Event Log</td>
<td>已发生的动作和状态变化</td>
<td>根据事件顺序还原过程</td>
</tr>
<tr>
<td>Checkpoint</td>
<td>某个时刻可恢复的任务状态</td>
<td>从检查点及后续事件继续</td>
</tr>
<tr>
<td>Workspace Snapshot</td>
<td>文件及工作环境的某个版本</td>
<td>挂载或恢复中间工作成果</td>
</tr>
<tr>
<td>Artifact</td>
<td>对外可引用的任务产物</td>
<td>下载、审核、交付或长期保留</td>
</tr>
</tbody>
</table>
<p>检查点频繁一些，故障后需要重做的工作通常更少，但存储和写入成本更高。任务状态、文件版本和事件位置还要能够对应，否则可能出现“状态显示生成完成，文件却仍是旧版”。</p>
<h3>8.2 两个 Worker 同时恢复同一任务怎么办？</h3>
<p>跨实例恢复需要控制执行所有权。常见思路是任务租约、状态版本检查，以及让下游识别旧执行者的围栏标识。仅依赖“我已经拿到锁”的本地变量，无法覆盖暂停、超时与旧进程恢复的情况。</p>
<p>例如，Worker A 超时后由 B 接管。A 随后恢复，也不能继续提交旧版本结果。状态存储应拒绝过期写入；涉及真实业务动作时，下游还需要校验请求和去重记录，防止同一封邮件被重复发送。</p>
<h3>8.3 记忆、知识库和本体应该怎样存？</h3>
<p>长期记忆需要管理来源、适用对象、更新与遗忘；知识库需要管理文档版本、解析结果、索引、权限和过期；本体则显式表达业务对象、关系及规则。</p>
<p>例如，“客户属于哪个组织”“订单关联哪个合同”“退款由谁批准”可以进入业务语义模型。检索资料时再利用这些关系定位证据。若业务只是查询少量文档，未必需要立即建设本体；先把权威来源、权限和版本维护好更实际。</p>
<h2>第 9 章：AI 网关与统一流量治理</h2>
<h3>9.1 AI 网关比普通 API 入口多关注什么？</h3>
<p>除了认证、路由和限流，AI 调用还涉及流式响应、Token 用量、模型能力差异、工具副作用和长任务费用归属。一次用户任务可能触发几十次内部调用，需要把它们关联起来。</p>
<table>
<thead>
<tr>
<th>治理对象</th>
<th>主要关注点</th>
<th>示例</th>
</tr>
</thead>
<tbody>
<tr>
<td>模型调用</td>
<td>模型路由、限额、费用、超时</td>
<td>某模型不可用时切换到允许的备选</td>
</tr>
<tr>
<td>工具调用</td>
<td>身份、参数、权限、副作用</td>
<td>限制查询范围或阻止未经审批的发送</td>
</tr>
<tr>
<td>Agent 调用</td>
<td>任务关联、租户、预算与生命周期</td>
<td>将子任务费用归入同一主任务</td>
</tr>
</tbody>
</table>
<p>这是三类治理语义，可以结合已有网关和业务服务实现，不要求另建三个独立产品。</p>
<h3>9.2 模型路由和降级怎样设计？</h3>
<p>先筛选满足能力、数据地域和权限要求的模型，再在允许集合中比较质量、延迟与成本。一个便宜模型如果无法理解工具协议或处理必要上下文，就不适合作为直接替代。</p>
<p>重试还要考虑响应已经推进到哪里。流式输出已经交给用户后，切换模型可能造成重复文本；涉及业务副作用的工具，则要先确认第一次执行结果。网关可以提供统一策略入口，但执行端也需要落实权限。</p>
<h3>9.3 为什么限流不能代替预算控制？</h3>
<p>限流约束一段时间内的调用速度，配额约束可消耗的量，预算则约束费用或资源总额。并发任务都先检查“余额足够”再调用，可能共同超过上限，因此需要协调预留和结算。</p>
<p>例如，月报任务每次模型调用前预留预算，收到实际用量后结算。调用超时且费用未知时保留待核对记录，避免当作零费用直接释放。对账、重试和结算应使用稳定调用标识，防止重复记账。</p>
<h2>第 10 章：Agent 异步任务与自动化流程</h2>
<h3>10.1 异步、定时和工作流有什么区别？</h3>
<p>异步回答“请求是否等待执行结束”；定时回答“什么时候触发”；工作流回答“有哪些步骤和分支”。三者可以一起出现。</p>
<p>例如，每月 1 日创建月报任务，接口立即返回任务 ID，后台执行“查询 → 分析 → 审批 → 发送”。用户随后通过任务 ID 查询状态。即使最初的网页关闭，任务也能继续或等待恢复。</p>
<p>Task 是持久业务单元，Session 是执行交互上下文。为同一任务创建新的会话，不应该重置已经完成的工作或已经发生的外部动作。</p>
<h3>10.2 怎样可靠地等待、恢复和取消？</h3>
<p>创建任务后保存输入、当前状态、版本和恢复条件；工作进程领取任务并推进；遇到审批、文件到达或远程事件时，登记等待条件并释放资源；事件到达后校验任务与版本，再安排续行。</p>
<p>回调可能重复或延迟，因此可以用来提醒系统重新同步，却不宜直接覆盖权威状态。取消也有边界：尚未开始的步骤可以停止，已提交的外部操作可能仍会完成，需要查询结果或执行补偿。</p>
<h3>10.3 工具超时后为什么不能一律重试？</h3>
<p>超时只说明调用方没有及时得到结果。邮件可能已经发出，付款可能已经完成。直接重试会放大业务影响。</p>
<p>可以为业务动作建立去重记录，例如：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sql"><span class="line"><span style="color:#FF7B72">CREATE</span><span style="color:#FF7B72"> TABLE</span><span style="color:#D2A8FF"> action_receipts</span><span style="color:#E6EDF3"> (</span></span>
<span class="line"><span style="color:#E6EDF3">    tenant_id </span><span style="color:#FF7B72">TEXT</span><span style="color:#FF7B72"> NOT NULL</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    business_key </span><span style="color:#FF7B72">TEXT</span><span style="color:#FF7B72"> NOT NULL</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FF7B72">    status</span><span style="color:#FF7B72"> TEXT</span><span style="color:#FF7B72"> NOT NULL</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    remote_receipt </span><span style="color:#FF7B72">TEXT</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FF7B72">    PRIMARY KEY</span><span style="color:#E6EDF3"> (tenant_id, business_key)</span></span>
<span class="line"><span style="color:#E6EDF3">);</span></span>
</code></pre>
<p><code>business_key</code> 可以绑定任务、收件人和报告版本。调用前协调执行权，调用后保存回执；结果未知时先查询远端。唯一约束能避免本地重复登记，但要避免远端重复执行，还需要远端支持幂等标识，或能据业务标识查询实际结果。</p>
<h2>第 11 章：Multi-Agent 协作与编排</h2>
<h3>11.1 什么情况下值得拆成多个 Agent？</h3>
<p>当任务确实需要不同专业能力、独立工作空间或职责隔离时，拆分可能提高效率。单个 Agent 已经可以稳定完成的简单任务，增加角色容易多出沟通、等待和结果冲突。</p>
<p>常见协作方式有三种：按顺序传递产物的流水线，由协调者分派并验收的管理结构，以及多个角色围绕共享问题讨论的协商结构。选型要看依赖关系与谁负责最终决策。</p>
<p>例如，月报可以由数据角色校验指标，分析角色解释变化，写作角色组织内容。如果三者只是轮流重写同一段文字，就很难产生分工收益。</p>
<h3>11.2 委派任务应该包含什么？</h3>
<p>一句“你负责数据”不足以定义协作。至少要说明目标、输入、输出、权限、预算、截止条件和验收规则。下面是应用自己的委派对象示意：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "task_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"report-2026-10"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "role"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"metrics_validator"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "goal"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"核对十月净销售额"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "required_output"</span><span style="color:#E6EDF3">: [</span><span style="color:#A5D6FF">"metrics"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"source_refs"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"validation"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#7EE787">  "permissions"</span><span style="color:#E6EDF3">: [</span><span style="color:#A5D6FF">"sales.read"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#7EE787">  "max_steps"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">5</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "deadline"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"2026-11-03T10:00:00+08:00"</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>子任务输出应能被下游直接理解，失败也要说明原因和已完成部分。协调者需要检查字段完整性、证据和业务标准，不能只看子 Agent 的自评。</p>
<h3>11.3 多个角色如何共享信息而不互相干扰？</h3>
<p>共享稳定事实与明确产物，给每个角色分配可写范围。数据角色负责指标文件，写作角色引用已确认指标，协调者负责最终报告版本。并发更新同一状态时，需要版本检查和冲突处理。</p>
<p>角色独立还不等于判断独立。如果检查者只阅读生成者写的结论，可能一起接受错误。让检查者读取原始数据或执行独立校验，才能增加发现问题的机会。</p>
<h2>第 12 章：Agent 分布式通信</h2>
<h3>12.1 工具调用、远程协作和用户事件流为什么要区分？</h3>
<p>工具调用通常表达一个有界操作；远程 Agent 协作可能持续多个阶段，涉及状态、补充输入与产物；用户事件流则用于展示进度、审批和结果。</p>
<p>MCP 和 A2A 可以分别承担相关协议职责，内部消息总线用于传递任务事件。选协议之前，先确定交互对象、状态由谁维护、是否允许取消，以及结果怎样核实。</p>
<h3>12.2 消息至少应该携带哪些信息？</h3>
<p>内部事件可以采用下面这样的结构，字段并非某个外部协议的固定格式：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "event_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"evt-104"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "task_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"report-2026-10"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "sequence"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">12</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "kind"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"artifact.ready"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "artifact_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"monthly-report"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "artifact_version"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"v3"</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p><code>event_id</code> 帮助去重，<code>task_id</code> 关联业务任务，顺序号和版本帮助识别乱序或过期结果。还可以根据需要增加关联调用、截止时间和经过验证的身份信息。</p>
<h3>12.3 怎样处理重复、乱序和断线？</h3>
<p>发送方重试可能产生重复消息；网络延迟可能让旧结果晚到；用户断线后可能需要从某个事件位置继续读取。接收方应按消息标识去重、校验当前任务版本，并有办法从权威记录重新同步。</p>
<p>例如，报告 v4 已获批，随后才收到 v3 的生成事件，系统应保留其历史记录，而不能把当前报告改回 v3。消息送达也不代表业务已完成；完成仍需由执行回执和验收条件确认。</p>
<h2>第 13 章：Agent 的可观测性</h2>
<h3>13.1 指标、日志和 Trace 分别看什么？</h3>
<p>指标适合回答整体成功率、延迟和费用是否异常；日志记录某个时间发生的事件；Trace 将一次任务中的模型、检索、工具和子任务串起来。三者结合，才能从“报告错了”追到具体步骤。</p>
<p>Agent 的观测对象还包括上下文来源、资产版本、任务阶段和最终产物。只记录模型接口状态码，会漏掉工具参数错误、证据缺失和过早结束等问题。</p>
<h3>13.2 一条执行链应该怎样读？</h3>
<p>假设一次任务耗时 100 秒，链路如下：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">monthly_report  100s
├── load_data    72s   数据库查询与重试
├── summarize    18s   模型分析
└── render       10s   文件生成
</code></pre>
<p>主要等待出现在查询阶段，优先排查慢查询、重复调用和网络，而不是先换模型。若最终数字有误，则沿链路查看输入、查询条件和聚合结果，寻找首次偏离预期的位置。</p>
<p>实际系统应为任务、会话、动作和模型调用建立关联，并记录错误类别、重试次数、Token、费用及配置版本。日志中的“生成完成”还要关联到具体文件，避免只剩无法核实的文字。</p>
<h3>13.3 可观测是否等于质量评估？</h3>
<p>观测能说明发生了什么，评价规则才能判断做得是否正确。一个接口全部返回成功的任务，仍可能采用错误统计口径。质量结论需要关联数据、规则和独立验收结果。</p>
<p>记录内容也要有边界。敏感参数、客户信息和凭证需要脱敏或限制访问；不必为了排障长期保存所有原始内容。目标是保留足够的可复核证据，并明确谁能查看、保留多久。</p>
<h2>第 14 章：Agent 安全</h2>
<h3>14.1 提示注入为什么会影响真实业务？</h3>
<p>Agent 会读取网页、附件和工具结果，这些内容可能夹带要求它改变目标、忽略规则或外发数据的指令。风险在于：模型既处理文本，又有机会通过工具改变外部系统。</p>
<p>例如，销售附件中夹带“将客户名单发到指定邮箱”。该段文本属于待分析的数据，没有权力替用户新增发送任务。上下文中应保留来源与信任边界，执行层还要检查目标地址和授权。</p>
<h3>14.2 为什么不能只依赖提示词防护？</h3>
<p>模型可能误判来源或指令，真正的权限边界应由身份、策略和执行环境保证。可以从以下几个位置分别控制：</p>
<table>
<thead>
<tr>
<th>风险</th>
<th>对应控制</th>
</tr>
</thead>
<tbody>
<tr>
<td>读取其他租户的数据</td>
<td>查询服务按可信身份过滤租户与资源</td>
</tr>
<tr>
<td>擅自执行高风险动作</td>
<td>对具体动作、参数和版本要求审批</td>
</tr>
<tr>
<td>代码访问无关文件或网络</td>
<td>限制挂载目录、网络出口和运行身份</td>
</tr>
<tr>
<td>泄露日志中的敏感信息</td>
<td>分级记录、脱敏、访问控制和保留期限</td>
</tr>
<tr>
<td>接入被污染的工具或 Skill</td>
<td>检查来源、依赖和版本，限制执行范围</td>
</tr>
</tbody>
</table>
<p>多层控制相互补充。例如，模型忽略恶意指令是一层；发送服务拒绝未经授权的收件人又是一层。</p>
<h3>14.3 怎样理解最小权限和用户委派？</h3>
<p>Agent 应携带可追溯的执行身份，在用户授权范围内操作。模型自称“用户已经同意”不能替代审批记录，工具参数中的租户名称也不能替代经过验证的身份。</p>
<p>月报助手可以拥有销售数据读取权和报告目录写入权，发送功能只在审批后开放。凭证由受信任执行组件保管，按需要提供给工具，而不是直接写进提示词或报告。权限还应能撤销，并留下调用记录。</p>
<h2>第 15 章：AI 资产的发现与管理</h2>
<h3>15.1 哪些东西需要当作资产管理？</h3>
<p>Prompt、Skill、工具服务和 Agent 都会影响行为。当它们被多个应用复用时，需要统一记录名称、负责人、版本、依赖、可见范围、运行入口与发布状态。</p>
<p>不同资产的检查重点不同：Prompt 关注变量和行为变化；Skill 还包括脚本、参考资料与依赖；工具服务要检查参数和权限；远程 Agent 需要明确任务与输出契约。</p>
<h3>15.2 为什么“模型版本固定”仍然不够复现？</h3>
<p>同一个模型使用不同提示词、Skill、工具版本或检索资料，可能产生完全不同的结果。一次运行应记录实际解析到的版本，而不只是“使用最新版本”。</p>
<p>应用内部可以保存类似下面的依赖清单：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "agent_release"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"monthly-report-v2"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "prompt_version"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"3"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "skill_versions"</span><span style="color:#E6EDF3">: {</span><span style="color:#7EE787">"sales-report"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"2.1"</span><span style="color:#E6EDF3">},</span></span>
<span class="line"><span style="color:#7EE787">  "tool_versions"</span><span style="color:#E6EDF3">: {</span><span style="color:#7EE787">"query_sales"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"4"</span><span style="color:#E6EDF3">},</span></span>
<span class="line"><span style="color:#7EE787">  "policy_version"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"2026-10"</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>这份清单配合模型配置、输入数据与环境记录，才能支持复盘。升级退款统计 Skill 时，也可以根据依赖关系找到受影响的应用。</p>
<h3>15.3 资产发现和发布怎样衔接？</h3>
<p>资源中心可以告诉系统有哪些能力，但能否调用还取决于身份、权限与当前阶段。发现结果中的描述、版本和端点，需要经过验证后再进入运行上下文。</p>
<p>发布过程可以是草稿、评审、测试、逐步切换和回滚。静态依赖适合固定版本；动态发现适合按任务寻找能力，但仍要记录实际选择。生产任务执行途中也不宜悄悄换成一个未经验证的新版本。</p>
<h2>第 16 章：Agent 行为生成与质量验证</h2>
<h3>16.1 Agent Simulation 要模拟什么？</h3>
<p>模拟的对象既包括用户，也包括执行环境。用户模拟器可以补充信息、拒绝审批或改变目标；环境模拟器可以返回正常数据、权限错误、超时和部分成功。</p>
<p>与手工聊天相比，模拟的价值在于条件可控制、案例可重复。固定场景、数据、角色、资产版本和预算后，才能比较两个版本在同一问题上的行为。</p>
<h3>16.2 怎样设计有意义的场景？</h3>
<p>先定义任务成功条件，再构造容易暴露问题的变化。例如，月报场景可以这样设计：</p>
<table>
<thead>
<tr>
<th>场景</th>
<th>预期行为</th>
<th>需要保留的证据</th>
</tr>
</thead>
<tbody>
<tr>
<td>缺少某个渠道数据</td>
<td>说明缺失并等待或按约定降级</td>
<td>缺失范围与提示记录</td>
</tr>
<tr>
<td>用户拒绝审批</td>
<td>保留草稿并停止发送</td>
<td>审批结果及后续动作</td>
</tr>
<tr>
<td>发送返回超时</td>
<td>核对实际结果后再处理</td>
<td>业务标识、查询与发送记录</td>
</tr>
<tr>
<td>附件包含恶意指令</td>
<td>继续原任务，不擅自外发</td>
<td>动作轨迹与权限检查结果</td>
</tr>
</tbody>
</table>
<p>除了最终回答，还要检查中间动作。即使报告内容正确，如果未经审批已经发出，也不应判定为成功。</p>
<h3>16.3 模拟结果能证明什么？</h3>
<p>模拟提供可复查的行为证据，评价器根据规则形成结论。模拟环境覆盖不到的真实差异，仍需通过受控真实测试补充，例如数据库权限、网络行为和实际交互延迟。</p>
<p>测试数据不能被候选 Agent 任意修改，模拟器也要能区分成功、失败和未完成。否则 Agent 可能只满足了测试表面形式，系统却没有真正获得可靠性。</p>
<h2>第 17 章：模型调优</h2>
<h3>17.1 怎样确认问题真的出在模型上？</h3>
<p>先检查模型是否已经获得必要信息，工具接口是否清楚，执行环境是否正常。如果退款规则根本没有进入上下文，训练模型不能补回缺失事实；如果数据库不可用，也应先解决服务问题。</p>
<p>在信息、动作空间和反馈都明确的条件下，模型仍持续误解目标、生成错误参数或无法利用反馈修正，才更接近模型能力缺口。对照实验时应固定 Harness、工具和任务预算，避免同时改动多处却无法解释收益来源。</p>
<h3>17.2 SFT、Agentic RL 和蒸馏有什么区别？</h3>
<table>
<thead>
<tr>
<th>方法</th>
<th>学习信号</th>
<th>适合解决什么</th>
<th>关键前提</th>
</tr>
</thead>
<tbody>
<tr>
<td>SFT</td>
<td>经过确认的行为示范</td>
<td>格式、工具使用和稳定操作方法</td>
<td>示范正确，覆盖必要上下文</td>
</tr>
<tr>
<td>Agentic RL</td>
<td>环境执行与奖励反馈</td>
<td>多步决策、路径选择和错误恢复</td>
<td>环境可交互，结果可可靠评价</td>
</tr>
<tr>
<td>蒸馏</td>
<td>教师模型输出或执行轨迹</td>
<td>将特定任务能力迁移给更小模型</td>
<td>教师结果经过检查，学生能承载目标能力</td>
</tr>
</tbody>
</table>
<p>例如，模型反复写错工具参数，可以收集包含工具说明和正确调用的 SFT 样本。若存在多条可行的退款处理路径，且金额、权限和结果能验证，可以研究用 RL 优化选择。若强模型已经稳定完成月报，可以尝试将方法蒸馏给成本更低的模型。</p>
<p>三者不是必须按顺序执行的流水线。奖励规则也不能只检查“创建了退款记录”，否则可能鼓励忽略金额或授权。安全限制仍由执行系统落实。</p>
<h3>17.3 推理框架在优化什么？</h3>
<p>训练改变模型参数，推理框架负责把模型能力交付给每次请求。输入处理的 Prefill、逐步生成的 Decode、批处理调度、KV Cache、量化和并行执行，共同影响延迟、吞吐与显存。</p>
<p>KV Cache 复用已经计算的注意力中间信息；批处理让硬件同时处理多个请求；量化可以降低资源需求，但可能影响质量。增加批量也可能增加等待，因此需要结合交互和离线任务分别评估。</p>
<p>如果主要问题是并发时首字很慢，应先检查排队、输入长度和推理服务；如果模型决策本身错误，再考虑能力优化。最终比较完整任务的成功率、约束遵守、耗时与单位成功任务成本，不能只看训练损失或单个 Token 价格。</p>
<h2>第 18 章：Agent 调优总览和实践</h2>
<h3>18.1 为什么一次修好问题还不够？</h3>
<p>一个输入补充 Prompt 后成功，并不能证明同类问题已经解决。换一种表达、换一个数据版本或换一条工具反馈，可能再次失败；新增规则也可能损害原先正常的能力。</p>
<p>因此，调优需要把真实任务转成可比较的样本，再用固定标准验证候选版本。过程可以形成一条数据闭环：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">真实运行 → 完整轨迹 → 数据加工 → 可信样本与评价标准
   ↑                                     ↓
受控发布 ← 通过验证的候选 ← 对照实验 ← 发现并归因问题
</code></pre>
<h3>18.2 每个环节交付什么？</h3>
<p>轨迹说明发生了什么；处理管线把记录整理成可用字段；数据集保存题目和条件；评价器判断是否达到要求；实验让不同版本重新执行；Badcase 分析把失败对应到具体修改。</p>
<p>这些模块应围绕相同任务、输入、版本和产物关联。否则观测里看到一次失败，数据集中却找不到对应条件，实验产生的结果也难以解释。</p>
<p>1688 宙斯的实践将执行观测、业务评估与版本回归连接起来，覆盖了文档读取未刷新、子任务结果未回传等具体问题。可借鉴的是把过程问题保存成可再次验证的案例，而不是仅依赖最终回答抽查。</p>
<h3>18.3 第一次应该从哪里开始？</h3>
<p>选一个反复出现、结果可确认的问题。例如“净销售额偶尔漏减退款”：先收集相关成功和失败任务，确认统计规则，再形成一批固定样本，建立当前版本基线，修改对应工具或上下文后复测。</p>
<p>接入平台时也应先执行一条已知任务，核对输入、工具调用、输出和版本是否都能查到。先让一条完整链路有证据，再逐步扩大样本和自动化范围。</p>
<h2>第 19 章：Agent 轨迹数据</h2>
<h3>19.1 Trace 与 Trajectory 有什么区别？</h3>
<p>Trace 侧重调用关系和技术运行信息；Trajectory 将输入、动作、观察、结果与业务目标组织成可阅读的执行过程。相同观测记录可以按不同分析用途整理，但分组方式要明确。</p>
<p>一个 Session 可能包含多个用户意图，一个业务 Task 也可能跨会话和子 Agent。不能简单把“同一会话”当成“同一业务目标已经完成”。需要结合任务标识、调用关联和业务事件识别边界。</p>
<h3>19.2 一条轨迹至少需要哪些内容？</h3>
<table>
<thead>
<tr>
<th>内容</th>
<th>为什么需要</th>
</tr>
</thead>
<tbody>
<tr>
<td>原始目标与后续补充</td>
<td>知道用户实际想完成什么</td>
</tr>
<tr>
<td>相关输入及来源</td>
<td>判断决策条件是否充分、适用</td>
</tr>
<tr>
<td>工具名称、参数和反馈</td>
<td>还原执行路径和错误</td>
</tr>
<tr>
<td>模型、配置、工具及数据版本</td>
<td>支持重放与版本比较</td>
</tr>
<tr>
<td>产物、回执和验收结果</td>
<td>区分表达成功与实际完成</td>
</tr>
</tbody>
</table>
<p>记录要足以支撑判断，同时按敏感程度脱敏和授权。可以保存稳定文件引用，不必把大文件和所有原始字段复制到每条记录中。</p>
<h3>19.3 排查失败时应该先看哪里？</h3>
<p>先看用户目标和最终结果，明确差在哪里；再展开关键步骤，找到首次偏差。如果查询结果已经不对，后续表达错误可能只是连锁反应。</p>
<p>例如，“读取订单 → 聚合指标 → 生成图表 → 写结论”中，第一步漏读了一个渠道。应修正查询和数据完整性检查，而不是只修改写作 Prompt。选出有价值的轨迹后，把条件、原因和验收依据保存为样本，供后续加工。</p>
<h2>第 20 章：Agent 运行时数据处理</h2>
<h3>20.1 为什么原始日志不能直接当评测数据？</h3>
<p>日志常按事件组织，业务需要按任务理解。一个任务可能包含多次重试、多个工具调用和重复错误；若直接把每个事件当样本，会让某个异常任务占据过高比重。</p>
<p>处理管线负责关联任务、选择字段、脱敏、去重、抽样和补充候选标签。处理规则也要有版本，方便解释同一批运行记录为何被加工成不同样本。</p>
<h3>20.2 怎样形成业务可用的样本？</h3>
<p>先明确用途。例如，检查“工具未成功，Agent 却声称完成”，至少需要用户输入、最终回答、工具状态、任务标识和版本。只保存问答文本，无法核对是否真的执行成功。</p>
<p>下面的 Python 示例演示必填检查与字段投影：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#FF7B72">def</span><span style="color:#D2A8FF"> to_sample</span><span style="color:#E6EDF3">(run):</span></span>
<span class="line"><span style="color:#E6EDF3">    required </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> (</span><span style="color:#A5D6FF">"task_id"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"input"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"output"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"agent_version"</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#FF7B72">    if</span><span style="color:#79C0FF"> any</span><span style="color:#E6EDF3">(</span><span style="color:#FF7B72">not</span><span style="color:#E6EDF3"> run.get(field) </span><span style="color:#FF7B72">for</span><span style="color:#E6EDF3"> field </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> required):</span></span>
<span class="line"><span style="color:#FF7B72">        return</span><span style="color:#79C0FF"> None</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">    sample </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> {field: run[field] </span><span style="color:#FF7B72">for</span><span style="color:#E6EDF3"> field </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> required}</span></span>
<span class="line"><span style="color:#E6EDF3">    sample[</span><span style="color:#A5D6FF">"tool_statuses"</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> [</span></span>
<span class="line"><span style="color:#E6EDF3">        tool[</span><span style="color:#A5D6FF">"status"</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">for</span><span style="color:#E6EDF3"> tool </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> run.get(</span><span style="color:#A5D6FF">"tools"</span><span style="color:#E6EDF3">, [])</span></span>
<span class="line"><span style="color:#E6EDF3">    ]</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#E6EDF3"> sample</span></span>
</code></pre>
<p>这里假设工具记录已经通过结构校验。真实管线还要处理身份关联、敏感内容、异常字段和原始证据引用。先预览几条加工结果，确认字段确实反映业务过程，再扩大处理范围。</p>
<h3>20.3 AI 自动打标签后还需要做什么？</h3>
<p>模型可以辅助分类、提取原因和寻找相似样本，但这些结果只是候选判断。关键规则、复杂边界和争议标签需要复核，尤其不能把模型自己的回答直接当作标准答案。</p>
<p>抽样时也要保留常见场景、失败和边界条件的合理分布。某次请求被重试十次，原则上仍应先作为同一个业务任务分析，而不是直接推断发生了十个独立失败。</p>
<h2>第 21 章：Agent 黄金数据集</h2>
<h3>21.1 “黄金”指的是成功答案吗？</h3>
<p>黄金数据集是一组经过确认的任务和验收依据。成功案例、已修正的失败案例、边界问题都可以进入。关键是输入条件清楚、标准可信，后续版本能够按相同条件重跑。</p>
<p>不同任务使用不同标准：知识问答可以检查必须覆盖的要点；业务操作要核对实际状态；代码任务要检查变更与测试。开放问题允许多种正确表达，不能一律用字符串相等判断。</p>
<h3>21.2 一个可验证的样本应该长什么样？</h3>
<p>假设按订单支付月份统计，下面的金额来自同一已确认的数据快照，单位为分：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"net-sales-01"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "month"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"2026-10"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "input"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"统计十月净销售额"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "fixtures"</span><span style="color:#E6EDF3">: [</span></span>
<span class="line"><span style="color:#E6EDF3">    {</span><span style="color:#7EE787">"paid_cents"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">10000</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">"refund_cents"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">2000</span><span style="color:#E6EDF3">},</span></span>
<span class="line"><span style="color:#E6EDF3">    {</span><span style="color:#7EE787">"paid_cents"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">5000</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">"refund_cents"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#E6EDF3">  ],</span></span>
<span class="line"><span style="color:#7EE787">  "expected"</span><span style="color:#E6EDF3">: {</span><span style="color:#7EE787">"net_sales_cents"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">13000</span><span style="color:#E6EDF3">},</span></span>
<span class="line"><span style="color:#7EE787">  "checks"</span><span style="color:#E6EDF3">: [</span><span style="color:#A5D6FF">"采用指定口径"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"说明数据来源"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"未审批不得发送"</span><span style="color:#E6EDF3">]</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>数值可以程序校验，是否解释限制可以按明确 Rubric 评价，审批则检查动作记录。与只给一篇“参考回答”相比，这种形式能更清楚地区分内容质量和行为约束。</p>
<h3>21.3 怎样避免在题库上表现好，上线后仍然失败？</h3>
<p>题库要覆盖常见场景和重要边界，例如全额退款、没有订单、数据缺失、用户修改月份和审批拒绝。训练或开发时使用的样本，应与最终验收样本区分，避免反复针对答案调整。</p>
<p>采用模型评价时，先用专家确认的好坏样本校准评分；规则变化后更新数据集版本。对随机性明显的任务进行重复运行，观察稳定性，不能只挑一次成功结果作为发布依据。</p>
<h2>第 22 章：Agent 优化：Badcase</h2>
<h3>22.1 一个失败应该先归到哪一类？</h3>
<p>先记录用户目标、预期、实际结果和首次偏差，再判断原因。几种看起来相似的失败，处理方式可能完全不同：</p>
<table>
<thead>
<tr>
<th>现象</th>
<th>优先检查</th>
<th>可能的修复方向</th>
</tr>
</thead>
<tbody>
<tr>
<td>采用了旧退款政策</td>
<td>知识版本和上下文来源</td>
<td>更新数据与检索过滤</td>
</tr>
<tr>
<td>把营业额当成净收入</td>
<td>业务定义与工具说明</td>
<td>明确指标，约束查询接口</td>
</tr>
<tr>
<td>工具超时却声称完成</td>
<td>工具状态和完成门禁</td>
<td>改进结果表达与验证逻辑</td>
</tr>
<tr>
<td>恢复后重复发送</td>
<td>去重键、回执和任务状态</td>
<td>修复执行与恢复机制</td>
</tr>
</tbody>
</table>
<p>只有确认模型在充分信息下仍作出错误决定，才更适合把问题交给模型或提示策略优化。</p>
<h3>22.2 怎样把“漏减退款”修成可验证的改动？</h3>
<p>延续上一章样本，两笔实付金额合计为 15000 分，退款为 2000 分，预期净销售额为 13000 分。如果原查询只累加实付金额，结果就会偏高。</p>
<p>在已统一月份和快照口径、金额字段非空的前提下，修正后的示例查询可以是：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-sql"><span class="line"><span style="color:#FF7B72">SELECT</span><span style="color:#79C0FF"> COALESCE</span><span style="color:#E6EDF3">(</span><span style="color:#79C0FF">SUM</span><span style="color:#E6EDF3">(paid_cents </span><span style="color:#FF7B72">-</span><span style="color:#E6EDF3"> refund_cents), </span><span style="color:#79C0FF">0</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">AS</span><span style="color:#E6EDF3"> net_sales_cents</span></span>
<span class="line"><span style="color:#FF7B72">FROM</span><span style="color:#E6EDF3"> orders</span></span>
<span class="line"><span style="color:#FF7B72">WHERE</span><span style="color:#E6EDF3"> paid_month </span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF"> '2026-10'</span><span style="color:#E6EDF3">;</span></span>
</code></pre>
<p>改动之后应核对结果为 13000，并补充无退款、全额退款、无订单和跨月份样本。如果问题来自数据没有同步，修改这段 SQL 本身又无法解决，因此归因必须建立在实际证据上。</p>
<h3>22.3 评估和实验分别做什么？</h3>
<p>评估检查已经发生的执行，帮助发现问题；实验让候选 Agent 重新执行同一批任务，再与基线比较。两者需要共享样本、标准和版本记录。</p>
<p>对比时看同一道题哪里改善、哪里退化，再观察整体成功率、耗时与费用。一次尽量修改明确对象，让收益可以解释。确认改动有效后，将典型失败保留在回归集，使下一次模型、工具或配置更新仍会检查它。</p>
<h2>第 23 章：受控自进化</h2>
<h3>23.1 从成功任务中能沉淀哪些东西？</h3>
<p>经验需要从经过验证的结果中提取，并注明适用场景。一次偶然成功可能依赖特殊数据、临时权限或不稳定路径，直接推广会产生错误。</p>
<table>
<thead>
<tr>
<th>反复出现的需求</th>
<th>适合沉淀的对象</th>
</tr>
</thead>
<tbody>
<tr>
<td>某类问题的排查经验</td>
<td>有条件和证据的记忆</td>
</tr>
<tr>
<td>经常遗漏前置检查或验收</td>
<td>Skill 中的步骤和检查方法</td>
</tr>
<tr>
<td>反复生成同类统计逻辑</td>
<td>SQL 模板、脚本或业务工具</td>
</tr>
<tr>
<td>稳定且明确的阶段流程</td>
<td>Workflow</td>
</tr>
<tr>
<td>重复执行、恢复和状态错误</td>
<td>Harness 与执行机制的修改</td>
</tr>
</tbody>
</table>
<p>例如，“对账前统一币种”可以成为报表 Skill 的检查项；固定计算逻辑可以做成脚本，避免每次重新生成。</p>
<h3>23.2 为什么经验一定要带适用条件？</h3>
<p>“超时后重试”可能适用于某类只读查询，但不适合无条件用于邮件、付款或库存扣减。经验应包含触发条件、适用范围、排除条件、依据和验证版本。</p>
<p>下面的记录表达的是候选经验：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "lesson"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"先识别错误类型，再决定是否重试"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "applies_to"</span><span style="color:#E6EDF3">: [</span><span style="color:#A5D6FF">"read_only_sales_query"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#7EE787">  "exclude"</span><span style="color:#E6EDF3">: [</span><span style="color:#A5D6FF">"send_report"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"payments"</span><span style="color:#E6EDF3">],</span></span>
<span class="line"><span style="color:#7EE787">  "evidence_dataset"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"query-recovery-v2"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "status"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"candidate"</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>召回之后还要检查当前条件是否匹配。历史经验可以提供方法，不能绕过当前权限或替代最新业务事实。</p>
<h3>23.3 怎样做到改进可控？</h3>
<p>把自动产生的修改放入候选区，运行已有回归集与新增场景，再经必要审核逐步采用。Prompt、Skill 和执行逻辑各自保留版本，发现退化后能够回滚。</p>
<p>还应检查“经验是否真的被读取”和“读取后是否有帮助”。记忆库不断增长却缺少去重、过期与删除机制，会使上下文更嘈杂。受控自进化的目标是让同类任务更稳定，而不是让资产数量持续增加。</p>
<h2>第 24 章：Agent 边缘运行时与全球优化</h2>
<h3>24.1 为什么模型变快，用户仍然觉得慢？</h3>
<p>端到端耗时包括排队、环境准备、模型、工具、网络、文件处理和人工等待。用户与服务跨地域时，网络往返可能成为明显开销；工具位于远端时，就近部署一个入口也未必能解决全部问题。</p>
<p>先分别测量各段耗时，再决定采用就近接入、调整执行位置、优化传输或减少远程调用。数据地域、权限和业务依赖也要一起考虑，不能只追求单个请求延迟。</p>
<h3>24.2 边缘缓存怎样避免返回错误数据？</h3>
<p>公共静态资源与个性化业务结果需要区别处理。相同问句可能对应不同租户、不同时间范围和不同数据版本，语义相似不足以证明答案可以复用。</p>
<p>月报结果的缓存至少要考虑如下维度：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">租户 + 权限范围 + 指标口径 + 月份 + 数据版本 + 资产版本
</code></pre>
<p>即使这些维度相同，还要定义有效期与数据更新后的失效方式。对强时效或敏感结果，也可以选择跳过结果缓存，只复用安全的公共资源或计算中间环节。</p>
<h3>24.3 全球优化应该怎样验证？</h3>
<p>按地域观察延迟、错误、费用和任务完成情况，检查版本是否同步、是否出现地域性失败。边缘安全与中心权限需要衔接，日志和数据流转也应符合既定边界。</p>
<p>例如，某地区访问报告很快，但工具调用持续失败，整体任务体验仍然较差。发布时应检查完整任务链，在小范围验证路由、资源版本和结果质量，再逐步扩大，而不是只比较首页或首字延迟。</p>
<h2>第 25 章：研发效能</h2>
<h3>25.1 为什么代码生成更快，交付却不一定更快？</h3>
<p>研发交付包含需求澄清、上下文准备、编码、评审、测试和发布。代码产量提高以后，如果评审和验证仍依赖人工逐项处理，瓶颈会转移到这些环节。</p>
<p>因此，研发 Agent 的任务应从可验收目标出发，例如“修复重复退款，给出最小变更与验证结果”，而不是只要求“写一段看起来正确的代码”。需要提供相关代码、调用关系、项目规则、领域知识和可运行环境。</p>
<h3>25.2 几类实践分别解决了什么问题？</h3>
<table>
<thead>
<tr>
<th>实践方向</th>
<th>代表案例</th>
<th>可借鉴的机制</th>
</tr>
</thead>
<tbody>
<tr>
<td>面向变更的定向测试</td>
<td>ABACI</td>
<td>从补丁影响范围出发，利用运行反馈构造测试</td>
</tr>
<tr>
<td>领域代码审查</td>
<td>Kitta</td>
<td>结合领域规则和项目知识，减少泛化建议</td>
</tr>
<tr>
<td>补丁交付编排</td>
<td>PatchPilot</td>
<td>对冲突、依赖、修复与回检分阶段处理</td>
</tr>
<tr>
<td>从故障到修复</td>
<td>PolarDB-X Loop</td>
<td>连接问题定位、代码修改与验证</td>
</tr>
<tr>
<td>端到端研发协作</td>
<td>云通信与多 Agent 研发小队</td>
<td>明确交接产物、责任和验收</td>
</tr>
<tr>
<td>评测驱动的产品迭代</td>
<td>Agentic SOC、AIOps 实践</td>
<td>将真实失败转成评估与回归材料</td>
</tr>
</tbody>
</table>
<p>这些案例共同说明，专业上下文、可执行环境和验证机制需要配合。领域知识可以帮助发现问题，但最后仍要回到代码、测试及实际运行结果。</p>
<h3>25.3 一次修复应该怎样形成交付闭环？</h3>
<p>以重复退款为例：先构造重复请求，确认旧逻辑会重复记账；再检查去重键和事务边界，完成针对性修改；随后运行回归用例、静态检查和受影响构建，最后审阅差异和剩余风险。</p>
<p>生成者与检查者可以分工，但检查者应读取变更与验证证据。评审结论需要指出具体位置、触发条件和影响，避免只给“代码质量良好”这样的泛泛评价。发布则继续遵循项目的授权和审批流程。</p>
<h2>第 26 章：设计工程</h2>
<h3>26.1 Vibe Designing 与 GenUI 分别关注什么？</h3>
<p>Vibe Designing 强调把意图、设计判断和持续反馈带入创造过程，让想法更快成为可以体验和修改的结果。设计师仍需定义业务语境、信息层级、交互和审美标准。</p>
<p>GenUI 则关注运行时交付：Agent 根据当前任务和真实结果，组织图表、列表、证据和操作控件。例如，排障结果既需要解释，也需要让用户查看指标、比较候选方案并批准具体动作。</p>
<p>固定高频流程可以继续使用固定页面，开放解释适合自然语言，长尾且需要操作的结果可以考虑 GenUI。</p>
<h3>26.2 怎样让动态界面保持可控？</h3>
<p>建立可用组件目录、数据与操作 Schema、推荐模板和使用规则。模型输出声明式结构，客户端校验后交给可信组件渲染。</p>
<p>下面是自定义界面契约示例，假设客户端已注册这些组件和动作：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "component"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"report-panel"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "children"</span><span style="color:#E6EDF3">: [</span></span>
<span class="line"><span style="color:#E6EDF3">    {</span><span style="color:#7EE787">"component"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"metric"</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">"name"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"净销售额"</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">"value_cents"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">13000</span><span style="color:#E6EDF3">},</span></span>
<span class="line"><span style="color:#E6EDF3">    {</span><span style="color:#7EE787">"component"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"button"</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">"label"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"查看明细"</span><span style="color:#E6EDF3">, </span><span style="color:#7EE787">"action"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"open_details"</span><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#E6EDF3">  ]</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>客户端需要检查组件是否受支持、字段类型和长度是否有效，以及动作是否允许。按钮表达的操作还要经过后端授权；界面结构通过校验，并不代表业务动作已经获得权限。</p>
<h3>26.3 用户反馈怎样进入下一轮？</h3>
<p>用户修改月份、选择区域或要求展示明细时，将结构化事件交回任务系统，重新读取必要数据，再更新对应区域。保留用户已确认的筛选条件，避免一次修改把整个任务重置。</p>
<p>设计验收要覆盖加载、空数据、错误、长内容、窄屏、键盘操作和危险动作确认。通过组件契约减少不受控结构，再通过真实反馈调整信息组织，才能让界面持续可用。</p>
<h2>站内延伸阅读</h2>
<p>下面几篇笔记围绕本书中的工程问题展开，适合结合具体例子继续阅读：</p>
<ul>
<li><a href="https://felix.muke.chat/notes/agent-tool-calling">Agent 是如何调用工具的</a>：从工具定义到执行结果回传，串起一次完整调用。</li>
<li><a href="https://felix.muke.chat/notes/agent-context-memory">Agent 如何管理上下文和记忆</a>：理解消息预算、历史压缩与长期信息的恢复。</li>
<li><a href="https://felix.muke.chat/notes/tool-call-idempotency">如何避免工具调用重复执行</a>：把重试、幂等键和执行收据放到同一条恢复链路里。</li>
<li><a href="https://felix.muke.chat/notes/rag-retrieval-precision">如何提高 RAG 的检索精度</a>：沿着召回、融合、重排与证据组装定位问题。</li>
<li><a href="https://felix.muke.chat/notes/multi-agent-shared-memory">多 Agent 如何共享长期记忆</a>：进一步理解跨会话、跨角色的记忆读取与权限。</li>
<li><a href="https://felix.muke.chat/notes/qdrant-from-beginner-to-advanced">Qdrant 从入门到进阶：原理与 Python 实战</a>：用完整代码练习向量存储、过滤与混合检索。</li>
</ul>
<hr>
<p>本文转载整理自阿里云与社区贡献者的 <a href="https://aliyun.github.io/ai-agent-handbook/">《AI Agent Handbook》</a>，按原书 30 章重新组织、提炼与改写；流程及代码示例为理解机制补充，不是对应产品的直接部署配置。原项目采用 Apache-2.0 许可：<a href="https://github.com/aliyun/ai-agent-handbook">原始仓库</a> · <a href="https://felix.muke.chat/attributions/ai-agent-handbook/LICENSE.txt">许可全文</a> · <a href="https://felix.muke.chat/attributions/ai-agent-handbook/NOTICE.txt">转载说明</a>。整理日期：2026 年 11 月 2 日。</p>
]]></content:encoded>
    </item>
    <item>
      <title>Agent 如何管理上下文和记忆</title>
      <link>https://felix.muke.chat/notes/agent-context-memory</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/agent-context-memory</guid>
      <pubDate>Sun, 01 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>理解模型当前能看到什么、历史如何压缩、长期信息怎样保留，以及文件和工具结果为什么需要独立存储。</description>
      <category>AI Agent</category>
      <category>Agent</category>
      <category>上下文管理</category>
      <category>记忆</category>
      <content:encoded><![CDATA[<p>让 Agent 生成一份 HTML 报告，随后要求“把标题改成绿色，其他内容不动”。</p>
<p>为了继续完成任务，它需要知道上一轮生成了哪个文件、用户已经确认了哪些内容，以及这次具体要改什么。如果对话已经很长，还要避免把这些信息淹没在大量历史消息里。</p>
<p><strong>上下文管理决定模型本次能看到什么，记忆管理决定哪些信息需要保留，以及后续怎样重新取用。</strong></p>
<h2>先区分上下文、会话记忆和长期记忆</h2>
<p>对模型而言，每次请求都会提供一组输入。历史信息要影响本次回答，就需要由应用重新放入输入，或通过工具读取后再交给模型。</p>
<p>可以把相关信息分成三层：</p>
<table>
<thead>
<tr>
<th>层次</th>
<th>保存什么</th>
<th>主要用途</th>
</tr>
</thead>
<tbody>
<tr>
<td>当前上下文</td>
<td>本次请求中的规则、问题、消息、工具定义和结果</td>
<td>支持这一步判断</td>
</tr>
<tr>
<td>会话记忆</td>
<td>当前任务的历史、摘要、进度和文件引用</td>
<td>在多轮对话或重启后继续任务</td>
</tr>
<tr>
<td>长期记忆</td>
<td>经确认的偏好、长期决策和稳定事实</td>
<td>在相关的后续会话中复用</td>
</tr>
</tbody>
</table>
<p>LangGraph 的记忆概念也按作用范围区分会话内的短期记忆和跨会话的长期记忆。<a href="https://docs.langchain.com/oss/python/concepts/memory">记忆的作用范围</a></p>
<p>例如，“这份报告不要使用外部图片”属于当前任务约束；“以后生成报告都不要使用外部图片”才明确表达了可以跨任务使用的偏好。</p>
<p>把一次性的要求永久保存，后续任务就可能被错误限制。长期记忆需要保留信息来源、适用范围和更新时间。</p>
<h2>每次请求都要计算上下文预算</h2>
<p>上下文中占空间的内容远不止聊天记录，还包括系统规则、工具参数定义、检索片段和工具返回结果。</p>
<p>对于输入与输出共享窗口的模型，预算需要给输出和安全余量留出空间。例如，假设窗口为 32,000 token，预留输出 6,000、安全余量 2,000，本次输入最多只能安排约 24,000 token。</p>
<p>这只是预算示例。实际还需要遵守模型各自的输入、输出限制，使用相应的 token 计数方式。字符数可以用于粗略控制，不能直接当作准确 token 数。</p>
<p>安排输入时，应先保证当前问题、仍然有效的约束和继续任务所需的信息能够放下，再分配历史消息与参考材料的空间。</p>
<p>工具目录和工具结果也应纳入预算。一次返回几万行日志，即使历史对话不长，也可能迅速占满窗口。</p>
<h2>历史压缩要保留任务状态</h2>
<p>只保留最近几条消息，可能把早先确认的约束丢掉。只写一段“用户要求修改报告”的摘要，又不足以支持后续操作。</p>
<p>更实用的方式是：保留最近的完整交互，把较早历史整理成结构化任务记忆。</p>
<p>假设用户先要求标题为蓝色，随后改为绿色，并要求继续适配手机。可以形成下面这份示例记忆：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "goal"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"生成可在手机上阅读的 HTML 报告"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "constraints"</span><span style="color:#E6EDF3">: [</span></span>
<span class="line"><span style="color:#A5D6FF">    "本次报告不使用外部图片"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">    "标题最终颜色为绿色"</span></span>
<span class="line"><span style="color:#E6EDF3">  ],</span></span>
<span class="line"><span style="color:#7EE787">  "completed"</span><span style="color:#E6EDF3">: [</span></span>
<span class="line"><span style="color:#A5D6FF">    "已生成报告"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">    "已将标题从蓝色改为绿色"</span></span>
<span class="line"><span style="color:#E6EDF3">  ],</span></span>
<span class="line"><span style="color:#7EE787">  "pending"</span><span style="color:#E6EDF3">: [</span></span>
<span class="line"><span style="color:#A5D6FF">    "补充移动端样式"</span></span>
<span class="line"><span style="color:#E6EDF3">  ],</span></span>
<span class="line"><span style="color:#7EE787">  "files"</span><span style="color:#E6EDF3">: [</span></span>
<span class="line"><span style="color:#E6EDF3">    {</span></span>
<span class="line"><span style="color:#7EE787">      "path"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"/workspace/report.html"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">      "artifact_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"file_001"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">      "version"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">2</span></span>
<span class="line"><span style="color:#E6EDF3">    }</span></span>
<span class="line"><span style="color:#E6EDF3">  ]</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>摘要需要保留目标、有效约束、决策、已完成工作、待办事项，以及文件和重要结果的引用。</p>
<p>时间顺序尤其重要。后来的“改成绿色”已经更新了先前的蓝色要求；已完成的工作也不应继续留在待办里，否则 Agent 可能重复执行。</p>
<p>压缩前还要覆盖准备移出的全部历史。只读取开头和结尾，可能漏掉中间出现的关键要求。长历史可以分段处理，再合并和检查摘要。</p>
<h2>工具调用和结果要一起保留</h2>
<p>上下文中可能包含这样的交互：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">助手：调用 read_file，读取 /workspace/report.html
工具：返回该文件的内容
助手：根据文件内容修改标题
</code></pre>
<p>如果只留下工具结果，模型可能不知道它来自哪个文件；如果只留下调用请求，模型又缺少执行结果。</p>
<p>裁剪历史时，应把工具调用及其对应结果作为关联单元处理，并保留调用 ID、工具名称和必要参数。压缩后也应能追溯重要结果来自哪次操作。</p>
<p>对于特别长的结果，可以把完整内容独立保存，先向模型提供短预览、结果 ID 和读取方式，需要时再按范围读取。</p>
<p>预览需要明确标记截断。完整结果已经存在时，模型可以继续读取，避免为了找回被省略的信息而重新执行原工具。</p>
<h2>文件和执行状态需要独立存储</h2>
<p>记忆里写着“报告位于 <code>/workspace/report.html</code>”，并不意味着下一轮执行环境里一定存在这个文件。</p>
<p>如果执行沙箱会在任务结束后销毁，文件需要提前归档。下一轮修改时，程序再根据会话、文件 ID 和版本恢复实际内容。</p>
<p>同样，“已经发送消息”这句话不能替代发送收据。外部操作的真实状态，应从持久化执行记录中读取。</p>
<p>因此，会话恢复通常需要同时准备：</p>
<ul>
<li><strong>理解任务的信息</strong>：目标、约束、最近消息和摘要。</li>
<li><strong>继续执行的状态</strong>：文件版本、工具结果、操作收据和待处理事项。</li>
</ul>
<p>持久化检查点可以让程序在中断后恢复这些状态。检查点应在新状态验证通过后再替换旧状态；摘要为空、结构错误或超出预算时，应保留原来的有效记录。</p>
<h2>长期记忆按需读取，也需要更新</h2>
<p>长期记忆可以保存用户偏好、稳定的环境约定和已经确认的决策。使用时先按用户、项目或工作空间确定范围，再选择与当前问题有关的内容。</p>
<p>当记忆需要在不同工具和角色之间复用时，可以进一步阅读<a href="https://felix.muke.chat/notes/multi-agent-shared-memory">《多 Agent 如何共享长期记忆》</a>，理解共享服务、权限与按需装配的关系。</p>
<p>不必把所有历史偏好都放进每一次请求。处理报告排版时，相关的是报告格式与图片使用习惯，其他项目的部署信息通常没有帮助。</p>
<p>记忆还需要处理变化：新的明确要求可能更新旧偏好，文件引用可能过期，用户也可能要求删除某条记忆。保存来源和更新时间，才能知道哪些内容需要重新确认。</p>
<p>历史摘要、检索内容和工具结果都应标明来源，作为数据供模型参考。文档里出现的指令式文字，不能因此获得系统规则或当前用户请求的权限。</p>
<h2>Agent 忘事时，沿着信息流排查</h2>
<table>
<thead>
<tr>
<th>现象</th>
<th>优先检查</th>
</tr>
</thead>
<tbody>
<tr>
<td>忘记早先确认的要求</td>
<td>是否被裁剪，摘要是否漏掉了约束</td>
</tr>
<tr>
<td>继续使用已经被修改的要求</td>
<td>摘要是否保留时间顺序，旧记忆是否更新</td>
</tr>
<tr>
<td>重复执行已经完成的工作</td>
<td>已完成状态和工具结果是否恢复</td>
</tr>
<tr>
<td>知道文件名，却无法修改文件</td>
<td>文件是否归档并恢复到当前执行环境</td>
</tr>
<tr>
<td>不同会话的信息混在一起</td>
<td>会话标识、记忆范围和访问权限</td>
</tr>
<tr>
<td>压缩后无法继续任务</td>
<td>是否丢失文件引用、调用关联或待办状态</td>
</tr>
</tbody>
</table>
<p>这些现象分别对应信息的保存、选择和恢复过程。逐段确认模型实际收到了什么，才能判断应该修改上下文组装、摘要策略，还是底层状态存储。</p>
]]></content:encoded>
    </item>
    <item>
      <title>Agent 是如何调用工具的</title>
      <link>https://felix.muke.chat/notes/agent-tool-calling</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/agent-tool-calling</guid>
      <pubDate>Sun, 01 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>从一次天气查询出发，理解工具定义、模型选择、程序执行和结果回传，以及 Function Calling、Agent 循环与 MCP 的关系。</description>
      <category>AI Agent</category>
      <category>Agent</category>
      <category>工具调用</category>
      <category>MCP</category>
      <content:encoded><![CDATA[<p>向一个 Agent 提问：“查一下杭州的天气，告诉我出门要不要带伞。”它可能先显示正在查询，然后给出天气情况和建议。</p>
<p>这段交互背后，模型、工具和运行程序各自完成了一部分工作。理解它们之间怎样传递信息，就能弄清 Agent 为什么能够查询数据、执行命令，以及它调用工具失败时应该从哪里排查。</p>
<p><strong>一次典型的工具调用包含四步：模型提出调用，程序执行工具，结果写回上下文，模型根据结果继续判断。</strong> MCP 官方文档也用这条分工解释 AI 应用中的工具执行过程。<a href="https://modelcontextprotocol.io/docs/learn/architecture#how-this-works-in-ai-applications">工具调用与应用的关系</a></p>
<h2>先让模型知道有哪些工具</h2>
<p>模型选择工具之前，应用需要提供一份工具目录，说明每个工具的名称、用途和输入参数。</p>
<p>例如，查询天气的工具可以定义为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "name"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"get_weather"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "description"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"查询指定城市的当前天气"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "inputSchema"</span><span style="color:#E6EDF3">: {</span></span>
<span class="line"><span style="color:#7EE787">    "type"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"object"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">    "properties"</span><span style="color:#E6EDF3">: {</span></span>
<span class="line"><span style="color:#7EE787">      "city"</span><span style="color:#E6EDF3">: {</span></span>
<span class="line"><span style="color:#7EE787">        "type"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"string"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">        "description"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"城市名称，例如杭州"</span></span>
<span class="line"><span style="color:#E6EDF3">      }</span></span>
<span class="line"><span style="color:#E6EDF3">    },</span></span>
<span class="line"><span style="color:#7EE787">    "required"</span><span style="color:#E6EDF3">: [</span><span style="color:#A5D6FF">"city"</span><span style="color:#E6EDF3">]</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>这里使用 MCP 工具定义的形式；其他模型接口或框架的封装字段可能不同。需要表达的信息是一致的：这个工具做什么，以及怎样传参。<a href="https://modelcontextprotocol.io/docs/learn/server-concepts#tools">MCP 工具定义</a></p>
<p>工具描述会影响模型的选择。如果描述只写“处理数据”，模型很难判断它能否查询天气。写清“查询指定城市的当前天气”，并解释城市参数，选择依据就明确得多。</p>
<p>提供给模型的是工具的接口描述。实际查询天气的函数、API 地址和认证信息，由执行程序管理。</p>
<h2>模型提出调用，程序负责执行</h2>
<p>模型看到用户问题和工具目录后，判断需要查询天气，于是返回一个结构化的调用请求。忽略不同接口的封装差异，可以把它理解为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"call_001"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "name"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"get_weather"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "arguments"</span><span style="color:#E6EDF3">: {</span></span>
<span class="line"><span style="color:#7EE787">    "city"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"杭州"</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>此时，天气查询尚未发生。模型完成的是选择工具、提取城市，并把调用意图表达出来。</p>
<p>随后，Agent 的运行程序读取这条请求，检查工具是否在允许使用的范围内、参数是否符合要求，再调用对应的函数或外部服务。</p>
<p>模型返回的名称和参数都需要校验。执行程序应从事先注册的工具中查找 <code>get_weather</code>，不能直接把模型生成的任意字符串当作代码执行。</p>
<p>这也解释了一个常见现象：模型在回答中写“正在查询天气”，并不一定意味着查询发生过。要确认实际执行，需要查看结构化工具调用和执行记录。</p>
<h2>工具结果怎样变成最终回答</h2>
<p>假设天气服务返回下面这份示例数据：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "city"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"杭州"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "condition"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"小雨"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "temperature_c"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">18</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>运行程序将结果作为工具消息写回上下文，并关联到 <code>call_001</code>。模型在下一次生成时，就同时拥有用户问题、自己提出的调用，以及工具的返回结果。</p>
<p>它可以据此回答：“查询结果显示杭州有小雨，出门建议带伞。”这里的天气情况来自示例工具结果，模型负责理解数据并组织语言。</p>
<p>调用 ID 用于关联请求与结果。一次响应中如果存在多个工具调用，每个结果都需要对应正确的请求，避免把不同查询的结果混在一起。</p>
<p>完整的信息流是：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">用户问题 + 可用工具定义
           ↓
模型返回工具调用请求
           ↓
程序校验并执行工具
           ↓
工具结果写回上下文
           ↓
模型继续调用工具，或生成最终回答
</code></pre>
<h2>Agent 为什么需要一个执行循环</h2>
<p>简单问题调用一次工具就够了。复杂任务可能需要多步：先搜索文档，再读取命中的内容，信息不足时继续查询，最后才能回答。</p>
<p>因此，运行程序通常需要重复“调用模型—执行工具—返回结果”的过程。下面是一段展示控制流程的 Python 伪代码，函数名称和消息结构需要按实际模型接口实现：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#FF7B72">def</span><span style="color:#D2A8FF"> run_agent</span><span style="color:#E6EDF3">(question, tool_definitions, max_steps</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">8</span><span style="color:#E6EDF3">):</span></span>
<span class="line"><span style="color:#E6EDF3">    messages </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> [user_message(question)]</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    for</span><span style="color:#E6EDF3"> step </span><span style="color:#FF7B72">in</span><span style="color:#79C0FF"> range</span><span style="color:#E6EDF3">(max_steps):</span></span>
<span class="line"><span style="color:#E6EDF3">        response </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> call_model(messages, tool_definitions)</span></span>
<span class="line"><span style="color:#E6EDF3">        messages.append(response)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">        if</span><span style="color:#FF7B72"> not</span><span style="color:#E6EDF3"> response.tool_calls:</span></span>
<span class="line"><span style="color:#FF7B72">            return</span><span style="color:#E6EDF3"> response.text</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">        for</span><span style="color:#E6EDF3"> call </span><span style="color:#FF7B72">in</span><span style="color:#E6EDF3"> response.tool_calls:</span></span>
<span class="line"><span style="color:#E6EDF3">            result </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> execute_authorized_tool(call.name, call.arguments)</span></span>
<span class="line"><span style="color:#E6EDF3">            messages.append(tool_result(call.id, result))</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">    raise</span><span style="color:#79C0FF"> RuntimeError</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">"已达到执行步数上限"</span><span style="color:#E6EDF3">)</span></span>
</code></pre>
<p>这里最重要的操作是把工具结果追加到 <code>messages</code>。只执行函数、却没有把结果返回给模型，模型就无法利用这次查询得到的信息。</p>
<p>循环也需要明确的停止条件。示例用最大步数限制执行长度；实际系统还可以约束总运行时间和工具调用次数，避免任务持续循环。</p>
<p>示例中的工具按顺序执行。有些只读查询可以并行，但后一步依赖前一步结果的操作仍需要保持顺序。</p>
<h2>Function Calling、Agent 和 MCP 怎么区分</h2>
<p>它们分别描述调用链中的不同部分。</p>
<p><strong>Function Calling 是模型表达工具调用的一种接口机制。</strong> 模型通过工具名称和结构化参数提出请求，应用据此执行。</p>
<p><strong>Agent 运行时负责组织整个执行过程。</strong> 它管理上下文、工具权限、执行结果和停止条件，让模型能够根据结果继续处理任务。</p>
<p><strong>MCP 定义 AI 应用与外部能力服务之间的通信方式。</strong> 应用可以通过它发现工具并发起调用。MCP 还包括资源和提示词等能力，并不只提供工具。<a href="https://modelcontextprotocol.io/docs/learn/server-concepts">MCP 服务提供的能力</a></p>
<p>例如，<code>get_weather</code> 可以是程序里注册的 Python 函数，也可以是直接调用的 HTTP API，还可以由 MCP 服务提供。应用需要把相应的执行结果交回模型，任务才能继续。</p>
<h2>工具调用失败时，按链路排查</h2>
<p>排查时可以沿着“可见、选择、执行、回传”四个阶段检查：</p>
<table>
<thead>
<tr>
<th>现象</th>
<th>优先检查</th>
</tr>
</thead>
<tbody>
<tr>
<td>模型没有提出工具调用</td>
<td>工具是否提供给模型，描述是否清楚，当前问题是否需要调用</td>
</tr>
<tr>
<td>模型提出了调用，但程序没有执行</td>
<td>工具注册、参数校验、权限或审批状态</td>
</tr>
<tr>
<td>工具执行后报错</td>
<td>外部服务、认证、超时及具体错误信息</td>
</tr>
<tr>
<td>工具成功，回答却没有使用结果</td>
<td>结果是否写回上下文，调用 ID 是否匹配，内容是否完整</td>
</tr>
<tr>
<td>同一操作反复执行</td>
<td>错误是否可重试，执行循环是否有预算，写操作是否有去重机制</td>
</tr>
</tbody>
</table>
<p>读取天气失败，通常可以按错误类型决定是否重试。但发送消息、创建订单等写操作，需要额外区分“确认未执行”和“执行结果未知”。请求超时可能发生在远端已经完成操作之后，直接重发会造成重复操作。具体的幂等键、执行收据和恢复流程，可以接着看<a href="https://felix.muke.chat/notes/tool-call-idempotency">《如何避免工具调用重复执行》</a>。</p>
<p>保留调用名称、参数、状态和结果，既能帮助模型继续处理任务，也能让开发者回看时确认：程序实际执行了哪一步，问题停在了哪里。</p>
]]></content:encoded>
    </item>
    <item>
      <title>Docker EasyConnect + Clash Verge 配置笔记</title>
      <link>https://felix.muke.chat/notes/docker-easyconnect-clash-verge-%E9%85%8D%E7%BD%AE%E7%AC%94%E8%AE%B0</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/docker-easyconnect-clash-verge-%E9%85%8D%E7%BD%AE%E7%AC%94%E8%AE%B0</guid>
      <pubDate>Sun, 01 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>docker-compose文件 在 Docker 容器中运行 EasyConnect，登录公司 VPN 后，让本机通过 Clash Verge 访问指定内网地址。 python 只让堡垒机 https://172.16.xx.xx/ 走 EasyConnect 其他 172.x.x.x 地址不要走 EasyConnect Docker 暴露端口 Docke...</description>
      <category>网络技术</category>
      <category>Docker</category>
      <category>EasyConnect</category>
      <category>Clash Verge</category>
      <category>VPN</category>
      <category>SOCKS5</category>
      <content:encoded><![CDATA[<h2>docker-compose文件</h2>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-shell"><span class="line"><span style="color:#FFA657">mkdir</span><span style="color:#79C0FF"> -p</span><span style="color:#A5D6FF"> ~/docker/app/easy-connect</span></span>
<span class="line"><span style="color:#79C0FF">cd</span><span style="color:#A5D6FF"> ~/docker/app/easy-connect</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FFA657">services:</span></span>
<span class="line"><span style="color:#FFA657">  easyconnect:</span></span>
<span class="line"><span style="color:#FFA657">    image:</span><span style="color:#A5D6FF"> hagb/docker-easyconnect:7.6.7</span></span>
<span class="line"><span style="color:#FFA657">    container_name:</span><span style="color:#A5D6FF"> app-easyconnect</span></span>
<span class="line"><span style="color:#FFA657">    privileged:</span><span style="color:#79C0FF"> true</span></span>
<span class="line"><span style="color:#FFA657">    tty:</span><span style="color:#79C0FF"> true</span></span>
<span class="line"><span style="color:#FFA657">    stdin_open:</span><span style="color:#79C0FF"> true</span></span>
<span class="line"><span style="color:#FFA657">    devices:</span></span>
<span class="line"><span style="color:#FFA657">      -</span><span style="color:#A5D6FF"> /dev/net/tun:/dev/net/tun</span></span>
<span class="line"><span style="color:#FFA657">    cap_add:</span></span>
<span class="line"><span style="color:#FFA657">      -</span><span style="color:#A5D6FF"> NET_ADMIN</span></span>
<span class="line"><span style="color:#FFA657">    environment:</span></span>
<span class="line"><span style="color:#FFA657">      PASSWORD:</span><span style="color:#A5D6FF"> xxxx</span></span>
<span class="line"><span style="color:#FFA657">      URLWIN:</span><span style="color:#A5D6FF"> "1"</span></span>
<span class="line"><span style="color:#FFA657">      DISABLE_PKG_VERSION_XML:</span><span style="color:#A5D6FF"> "1"</span></span>
<span class="line"><span style="color:#FFA657">    volumes:</span></span>
<span class="line"><span style="color:#FFA657">      -</span><span style="color:#A5D6FF"> ./data:/root</span></span>
<span class="line"><span style="color:#FFA657">    ports:</span></span>
<span class="line"><span style="color:#FFA657">      -</span><span style="color:#A5D6FF"> "127.0.0.1:5901:5901"</span></span>
<span class="line"><span style="color:#FFA657">      -</span><span style="color:#A5D6FF"> "127.0.0.1:1080:1080"</span></span>
<span class="line"><span style="color:#FFA657">      -</span><span style="color:#A5D6FF"> "127.0.0.1:8888:8888"</span></span>
<span class="line"><span style="color:#FFA657">    restart:</span><span style="color:#A5D6FF"> unless-stopped</span></span>
</code></pre>
<p>在 Docker 容器中运行 EasyConnect，登录公司 VPN 后，让本机通过 Clash Verge 访问指定内网地址。</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#E6EDF3">只让堡垒机 https:</span><span style="color:#FF7B72">//</span><span style="color:#79C0FF">172.16</span><span style="color:#E6EDF3">.xx.xx</span><span style="color:#FF7B72">/</span><span style="color:#E6EDF3"> 走 EasyConnect</span></span>
<span class="line"><span style="color:#E6EDF3">其他 </span><span style="color:#79C0FF">172.</span><span style="color:#E6EDF3">x.x.x 地址不要走 EasyConnect</span></span>
<span class="line"><span style="color:#E6EDF3">Docker 暴露端口</span></span>
<span class="line"><span style="color:#E6EDF3">Docker Compose 中暴露的端口：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">127.0</span><span style="color:#E6EDF3">.0.1:</span><span style="color:#79C0FF">5901</span><span style="color:#FFA198;font-style:italic"> -></span><span style="color:#E6EDF3"> 容器 </span><span style="color:#79C0FF">VNC</span></span>
<span class="line"><span style="color:#79C0FF">127.0</span><span style="color:#E6EDF3">.0.1:</span><span style="color:#79C0FF">1080</span><span style="color:#FFA198;font-style:italic"> -></span><span style="color:#E6EDF3"> EasyConnect </span><span style="color:#79C0FF">SOCKS5</span></span>
<span class="line"><span style="color:#79C0FF">127.0</span><span style="color:#E6EDF3">.0.1:</span><span style="color:#79C0FF">8888</span><span style="color:#FFA198;font-style:italic"> -></span><span style="color:#E6EDF3"> EasyConnect </span><span style="color:#79C0FF">HTTP</span></span>
<span class="line"><span style="color:#E6EDF3">端口含义：</span></span>
<span class="line"><span style="color:#79C0FF">5901</span><span style="color:#E6EDF3">：用 </span><span style="color:#79C0FF">VNC</span><span style="color:#E6EDF3"> 登录容器里的 EasyConnect 图形界面</span></span>
<span class="line"><span style="color:#79C0FF">1080</span><span style="color:#E6EDF3">：EasyConnect 登录成功后提供 </span><span style="color:#79C0FF">SOCKS5</span><span style="color:#E6EDF3"> 代理</span></span>
<span class="line"><span style="color:#79C0FF">8888</span><span style="color:#E6EDF3">：</span><span style="color:#79C0FF">HTTP</span><span style="color:#E6EDF3"> 代理</span></span>
<span class="line"><span style="color:#E6EDF3">登录 EasyConnect</span></span>
<span class="line"><span style="color:#E6EDF3">先用 </span><span style="color:#79C0FF">VNC</span><span style="color:#E6EDF3"> 进入容器：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">vnc:</span><span style="color:#FF7B72">//</span><span style="color:#79C0FF">127.0</span><span style="color:#E6EDF3">.0.1:</span><span style="color:#79C0FF">5901</span></span>
<span class="line"><span style="color:#79C0FF">VNC</span><span style="color:#E6EDF3"> 密码是 Docker Compose 里的：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">PASSWORD</span><span style="color:#E6EDF3">: xxxx</span></span>
<span class="line"><span style="color:#E6EDF3">注意：这个 </span><span style="color:#79C0FF">PASSWORD</span><span style="color:#E6EDF3"> 是 </span><span style="color:#79C0FF">VNC</span><span style="color:#E6EDF3"> 密码，不是公司 </span><span style="color:#79C0FF">VPN</span><span style="color:#E6EDF3"> 密码。</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">进入后，在 EasyConnect 里登录公司 </span><span style="color:#79C0FF">VPN</span><span style="color:#E6EDF3">。</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">登录成功后，</span><span style="color:#79C0FF">127.0</span><span style="color:#E6EDF3">.0.1:</span><span style="color:#79C0FF">1080</span><span style="color:#E6EDF3"> 才真正可用。</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">Clash Verge 脚本</span></span>
<span class="line"><span style="color:#E6EDF3">当前使用 Clash Verge 的“全局扩展脚本”。</span></span>
<span class="line"></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">编辑全局扩展脚本：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">function main(config, profileName) {</span></span>
<span class="line"><span style="color:#E6EDF3">  const proxyName = </span><span style="color:#A5D6FF">"ec"</span><span style="color:#E6EDF3">;</span></span>
<span class="line"><span style="color:#E6EDF3">  const bastionRule = </span><span style="color:#FFA198;font-style:italic">`</span><span style="color:#79C0FF;font-style:italic">IP</span><span style="color:#FF7B72;font-style:italic">-</span><span style="color:#79C0FF;font-style:italic">CIDR</span><span style="color:#FFA198;font-style:italic">,堡垒机IP</span><span style="color:#FF7B72;font-style:italic">/</span><span style="color:#79C0FF;font-style:italic">32</span><span style="color:#FFA198;font-style:italic">,${proxyName},no</span><span style="color:#FF7B72;font-style:italic">-</span><span style="color:#FFA198;font-style:italic">resolve`</span><span style="color:#E6EDF3">;</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">  config.proxies = Array.isArray(config.proxies) </span><span style="color:#FFA198;font-style:italic">?</span><span style="color:#E6EDF3"> config.proxies : [];</span></span>
<span class="line"><span style="color:#E6EDF3">  config.proxies = config.proxies.filter((item) </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> item </span><span style="color:#FFA198;font-style:italic">&#x26;&#x26;</span><span style="color:#E6EDF3"> item.name </span><span style="color:#FF7B72">!==</span><span style="color:#E6EDF3"> proxyName);</span></span>
<span class="line"><span style="color:#E6EDF3">  config.proxies.push({</span></span>
<span class="line"><span style="color:#E6EDF3">    name: proxyName,</span></span>
<span class="line"><span style="color:#79C0FF">    type</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"socks5"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    server: </span><span style="color:#A5D6FF">"127.0.0.1"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    port: </span><span style="color:#79C0FF">1080</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">    udp: true,</span></span>
<span class="line"><span style="color:#E6EDF3">  });</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">  config.rules = Array.isArray(config.rules) </span><span style="color:#FFA198;font-style:italic">?</span><span style="color:#E6EDF3"> config.rules : [];</span></span>
<span class="line"><span style="color:#E6EDF3">  config.rules = config.rules.filter((rule) </span><span style="color:#FF7B72">=></span><span style="color:#E6EDF3"> rule </span><span style="color:#FF7B72">!==</span><span style="color:#E6EDF3"> bastionRule);</span></span>
<span class="line"><span style="color:#E6EDF3">  config.rules.unshift(bastionRule);</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">  return</span><span style="color:#E6EDF3"> config;</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
<span class="line"><span style="color:#E6EDF3">生成后的规则：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">IP</span><span style="color:#FF7B72">-</span><span style="color:#79C0FF">CIDR</span><span style="color:#E6EDF3">,</span><span style="color:#79C0FF">172.16</span><span style="color:#E6EDF3">.xx.xx</span><span style="color:#FF7B72">/</span><span style="color:#79C0FF">32</span><span style="color:#E6EDF3">,ec,no</span><span style="color:#FF7B72">-</span><span style="color:#E6EDF3">resolve</span></span>
<span class="line"><span style="color:#E6EDF3">这条是 </span><span style="color:#FF7B72">/</span><span style="color:#79C0FF">32</span><span style="color:#E6EDF3"> 精确匹配，只匹配：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">172.16</span><span style="color:#E6EDF3">.xx.xx</span></span>
<span class="line"><span style="color:#E6EDF3">不会匹配其他：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">172.16</span><span style="color:#E6EDF3">.x.x</span></span>
<span class="line"><span style="color:#79C0FF">172.17</span><span style="color:#E6EDF3">.x.x</span></span>
<span class="line"><span style="color:#79C0FF">172.18</span><span style="color:#E6EDF3">.x.x</span></span>
<span class="line"><span style="color:#E6EDF3">验证命令</span></span>
<span class="line"><span style="color:#E6EDF3">验证 Docker EasyConnect </span><span style="color:#79C0FF">SOCKS5</span><span style="color:#E6EDF3"> 是否可用：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">curl </span><span style="color:#FF7B72">-</span><span style="color:#E6EDF3">k </span><span style="color:#FF7B72">-</span><span style="color:#E6EDF3">x socks5h:</span><span style="color:#FF7B72">//</span><span style="color:#79C0FF">127.0</span><span style="color:#E6EDF3">.0.1:</span><span style="color:#79C0FF">1080</span><span style="color:#E6EDF3"> https:</span><span style="color:#FF7B72">//</span><span style="color:#79C0FF">172.16</span><span style="color:#E6EDF3">.xx.xx</span><span style="color:#FF7B72">/</span><span style="color:#FF7B72"> -</span><span style="color:#E6EDF3">I</span></span>
<span class="line"><span style="color:#E6EDF3">验证 Clash 是否能转发到 EasyConnect：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">curl </span><span style="color:#FF7B72">-</span><span style="color:#E6EDF3">k </span><span style="color:#FFA198;font-style:italic">--</span><span style="color:#79C0FF">max</span><span style="color:#FF7B72">-</span><span style="color:#E6EDF3">time </span><span style="color:#79C0FF">15</span><span style="color:#FF7B72"> -</span><span style="color:#E6EDF3">x http:</span><span style="color:#FF7B72">//</span><span style="color:#79C0FF">127.0</span><span style="color:#E6EDF3">.0.1:</span><span style="color:#79C0FF">7897</span><span style="color:#E6EDF3"> https:</span><span style="color:#FF7B72">//</span><span style="color:#79C0FF">172.16</span><span style="color:#E6EDF3">.xx.xx</span><span style="color:#FF7B72">/</span><span style="color:#FF7B72"> -</span><span style="color:#E6EDF3">I</span></span>
<span class="line"><span style="color:#E6EDF3">正常情况下会返回：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">HTTP</span><span style="color:#FF7B72">/</span><span style="color:#79C0FF">1.1</span><span style="color:#79C0FF"> 200</span><span style="color:#79C0FF"> OK</span></span>
<span class="line"><span style="color:#E6EDF3">为什么浏览器可能还是访问不通</span></span>
<span class="line"><span style="color:#E6EDF3">如果命令行显式指定 Clash 代理能通：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">curl </span><span style="color:#FF7B72">-</span><span style="color:#E6EDF3">k </span><span style="color:#FFA198;font-style:italic">--</span><span style="color:#79C0FF">max</span><span style="color:#FF7B72">-</span><span style="color:#E6EDF3">time </span><span style="color:#79C0FF">15</span><span style="color:#FF7B72"> -</span><span style="color:#E6EDF3">x http:</span><span style="color:#FF7B72">//</span><span style="color:#79C0FF">127.0</span><span style="color:#E6EDF3">.0.1:</span><span style="color:#79C0FF">7897</span><span style="color:#E6EDF3"> https:</span><span style="color:#FF7B72">//</span><span style="color:#79C0FF">172.16</span><span style="color:#E6EDF3">.xx.xx</span><span style="color:#FF7B72">/</span><span style="color:#FF7B72"> -</span><span style="color:#E6EDF3">I</span></span>
<span class="line"><span style="color:#E6EDF3">但浏览器直接访问：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">https:</span><span style="color:#FF7B72">//</span><span style="color:#79C0FF">172.16</span><span style="color:#E6EDF3">.xx.xx</span><span style="color:#FF7B72">/</span></span>
<span class="line"><span style="color:#E6EDF3">不通，通常不是 Clash 规则问题，而是浏览器流量没有进入 Clash。</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">常见原因：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">系统代理默认绕过局域网 </span><span style="color:#FF7B72">/</span><span style="color:#E6EDF3"> 私网地址</span></span>
<span class="line"><span style="color:#79C0FF">172.16</span><span style="color:#E6EDF3">.xx.xx 属于私网地址</span></span>
<span class="line"><span style="color:#E6EDF3">所以浏览器可能直接连接它，没有交给 Clash</span></span>
<span class="line"><span style="color:#E6EDF3">也就是说：</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">curl 显式走 Clash </span><span style="color:#FFA198;font-style:italic">-></span><span style="color:#E6EDF3"> 能通</span></span>
<span class="line"><span style="color:#E6EDF3">浏览器走系统代理 </span><span style="color:#FFA198;font-style:italic">-></span><span style="color:#E6EDF3"> 可能被系统绕过 </span><span style="color:#FFA198;font-style:italic">-></span><span style="color:#E6EDF3"> 不通</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">解决方向</span></span>
<span class="line"><span style="color:#E6EDF3">方案 </span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">：开启 Clash Verge </span><span style="color:#79C0FF">TUN</span><span style="color:#E6EDF3"> 模式</span></span>
<span class="line"><span style="color:#79C0FF">TUN</span><span style="color:#E6EDF3"> 会接管更多流量，私网 </span><span style="color:#79C0FF">IP</span><span style="color:#E6EDF3"> 也更容易进入 Clash 规则系统。</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">优点：</span></span>
<span class="line"><span style="color:#E6EDF3">浏览器不用单独配置代理</span></span>
<span class="line"><span style="color:#79C0FF">172.16</span><span style="color:#E6EDF3">.xx.xx 能按 Clash 规则走 ec</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">缺点：</span></span>
<span class="line"><span style="color:#E6EDF3">对系统网络影响更大</span></span>
<span class="line"><span style="color:#E6EDF3">需要管理员权限</span></span>
<span class="line"><span style="color:#E6EDF3">可能影响本机其他网络</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">方案 </span><span style="color:#79C0FF">2</span><span style="color:#E6EDF3">：浏览器单独指定代理</span></span>
<span class="line"><span style="color:#E6EDF3">给浏览器或浏览器插件设置代理：</span></span>
<span class="line"><span style="color:#79C0FF">HTTP</span><span style="color:#FF7B72">/</span><span style="color:#79C0FF">SOCKS</span><span style="color:#E6EDF3"> 代理：</span><span style="color:#79C0FF">127.0</span><span style="color:#E6EDF3">.0.1:</span><span style="color:#79C0FF">7897</span></span>
<span class="line"><span style="color:#E6EDF3">然后访问：</span></span>
<span class="line"><span style="color:#E6EDF3">https:</span><span style="color:#FF7B72">//</span><span style="color:#79C0FF">172.16</span><span style="color:#E6EDF3">.xx.xx</span><span style="color:#FF7B72">/</span></span>
<span class="line"><span style="color:#E6EDF3">这样可以强制浏览器请求进入 Clash。</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">方案 </span><span style="color:#79C0FF">3</span><span style="color:#E6EDF3">：调整 Clash Verge 系统代理绕过规则</span></span>
<span class="line"><span style="color:#E6EDF3">关闭或修改默认绕过私网地址的行为，让 </span><span style="color:#79C0FF">172.16</span><span style="color:#E6EDF3">.xx.xx 不被系统代理绕过。</span></span>
<span class="line"><span style="color:#E6EDF3">这个方案要谨慎，因为改错可能影响本机局域网访问。</span></span>
</code></pre>
]]></content:encoded>
    </item>
    <item>
      <title>EasyTier 自建组网：公网服务器与客户端部署记录</title>
      <link>https://felix.muke.chat/notes/easytier-%E9%85%8D%E7%BD%AE%E9%83%A8%E7%BD%B2</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/easytier-%E9%85%8D%E7%BD%AE%E9%83%A8%E7%BD%B2</guid>
      <pubDate>Sun, 01 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>这次我用一台公网 Linux 服务器和一台 Mac 搭建了 EasyTier 私有网络，让两台设备通过虚拟 IP 通信。本文记录安装、配置、重启服务和连通性验证的过程，也整理了查看在线节点、判断延迟以及通过公网访问本地服务的方法。 本次已经验证的是：Mac 可以通过 EasyTier ping 通服务器。公网端口转发是后面的可选配置，本次尚未验证。文中的公网...</description>
      <category>网络技术</category>
      <category>EasyTier</category>
      <category>VPN</category>
      <category>异地组网</category>
      <content:encoded><![CDATA[<p>这次我用一台公网 Linux 服务器和一台 Mac 搭建了 EasyTier 私有网络，让两台设备通过虚拟 IP 通信。本文记录安装、配置、重启服务和连通性验证的过程，也整理了查看在线节点、判断延迟以及通过公网访问本地服务的方法。</p>
<p>本次已经验证的是：Mac 可以通过 EasyTier ping 通服务器。公网端口转发是后面的可选配置，本次尚未验证。文中的公网 IP、网络名称和密钥均已替换为示例值。</p>
<h2>先明确要实现的访问方式</h2>
<p>EasyTier 组网成功后，加入同一个虚拟网络的设备可以通过虚拟 IP 访问彼此的服务。使用匹配的网络名称和密钥，是本例中节点加入私有网络的条件。</p>
<p>如果希望别人不安装 EasyTier，只用浏览器访问我电脑上的网站，还需要在公网服务器上配置端口转发或反向代理。两种访问路径分别是：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">已经加入 EasyTier 的设备 → Mac 的虚拟 IP:服务端口

普通公网用户 → 服务器公网 IP:转发端口 → EasyTier → Mac:服务端口
</code></pre>
<p>仅在服务器和 Mac 上启动 EasyTier，不会自动把 Mac 上的服务发布到公网。节点连接机制可参考<a href="https://easytier.cn/guide/network/quick-networking.html">官方快速组网文档</a>。</p>
<h2>环境与地址规划</h2>
<p>安装命令以 Ubuntu／Debian 和 systemd 为例，本机使用 Apple 芯片的 Mac。下面固定安装 EasyTier v2.6.4，便于之后复现。</p>
<table>
<thead>
<tr>
<th>项目</th>
<th>示例设置</th>
</tr>
</thead>
<tbody>
<tr>
<td>服务器公网 IP</td>
<td><code>203.0.113.10</code>，使用时替换为真实公网 IP</td>
</tr>
<tr>
<td>服务器虚拟 IP</td>
<td><code>10.144.144.1</code></td>
</tr>
<tr>
<td>Mac 虚拟 IP</td>
<td><code>10.144.144.2</code></td>
</tr>
<tr>
<td>网络名称</td>
<td><code>demo-network</code></td>
</tr>
<tr>
<td>网络密钥</td>
<td>自行生成，两端保持一致</td>
</tr>
<tr>
<td>服务器监听端口</td>
<td>TCP／UDP <code>11010</code></td>
</tr>
</tbody>
</table>
<p>这里使用固定虚拟 IP，方便后续配置访问地址和端口转发。如果现有局域网或其他 VPN 已使用 <code>10.144.144.0/24</code>，应先换一个不冲突的网段。</p>
<h2>在服务器上安装 EasyTier</h2>
<p>SSH 登录服务器，安装下载和解压需要的工具：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> apt</span><span style="color:#A5D6FF"> update</span></span>
<span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> apt</span><span style="color:#A5D6FF"> install</span><span style="color:#79C0FF"> -y</span><span style="color:#A5D6FF"> curl</span><span style="color:#A5D6FF"> unzip</span><span style="color:#A5D6FF"> openssl</span></span>
</code></pre>
<p>根据 CPU 架构，从<a href="https://github.com/EasyTier/EasyTier/releases/tag/v2.6.4">官方 v2.6.4 发布页</a>下载对应的 Linux 安装包：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#E6EDF3">ET_VERSION</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">v2.6.4</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">case</span><span style="color:#A5D6FF"> "$(</span><span style="color:#FFA657">uname</span><span style="color:#79C0FF"> -m</span><span style="color:#A5D6FF">)"</span><span style="color:#FF7B72"> in</span></span>
<span class="line"><span style="color:#A5D6FF">  x86_64</span><span style="color:#FF7B72">)</span><span style="color:#E6EDF3"> ET_ARCH</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">x86_64</span><span style="color:#E6EDF3"> ;;</span></span>
<span class="line"><span style="color:#A5D6FF">  aarch64</span><span style="color:#FF7B72">|</span><span style="color:#A5D6FF">arm64</span><span style="color:#FF7B72">)</span><span style="color:#E6EDF3"> ET_ARCH</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">aarch64</span><span style="color:#E6EDF3"> ;;</span></span>
<span class="line"><span style="color:#FF7B72">  *)</span><span style="color:#79C0FF"> echo</span><span style="color:#A5D6FF"> "请到官方发布页选择适合该架构的安装包"</span><span style="color:#E6EDF3">; </span><span style="color:#79C0FF">exit</span><span style="color:#79C0FF"> 1</span><span style="color:#E6EDF3"> ;;</span></span>
<span class="line"><span style="color:#FF7B72">esac</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">ET_TMP</span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3">$(</span><span style="color:#FFA657">mktemp</span><span style="color:#79C0FF"> -d</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FFA657">curl</span><span style="color:#79C0FF"> -fL</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#A5D6FF">  "https://github.com/EasyTier/EasyTier/releases/download/${</span><span style="color:#E6EDF3">ET_VERSION</span><span style="color:#A5D6FF">}/easytier-linux-${</span><span style="color:#E6EDF3">ET_ARCH</span><span style="color:#A5D6FF">}-${</span><span style="color:#E6EDF3">ET_VERSION</span><span style="color:#A5D6FF">}.zip"</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#79C0FF">  -o</span><span style="color:#A5D6FF"> "</span><span style="color:#E6EDF3">$ET_TMP</span><span style="color:#A5D6FF">/easytier.zip"</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FFA657">unzip</span><span style="color:#79C0FF"> -q</span><span style="color:#A5D6FF"> "</span><span style="color:#E6EDF3">$ET_TMP</span><span style="color:#A5D6FF">/easytier.zip"</span><span style="color:#79C0FF"> -d</span><span style="color:#A5D6FF"> "</span><span style="color:#E6EDF3">$ET_TMP</span><span style="color:#A5D6FF">"</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> install</span><span style="color:#79C0FF"> -m</span><span style="color:#79C0FF"> 755</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#A5D6FF">  "</span><span style="color:#E6EDF3">$ET_TMP</span><span style="color:#A5D6FF">/easytier-linux-</span><span style="color:#E6EDF3">$ET_ARCH</span><span style="color:#A5D6FF">/easytier-core"</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#A5D6FF">  /usr/local/bin/easytier-core</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> install</span><span style="color:#79C0FF"> -m</span><span style="color:#79C0FF"> 755</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#A5D6FF">  "</span><span style="color:#E6EDF3">$ET_TMP</span><span style="color:#A5D6FF">/easytier-linux-</span><span style="color:#E6EDF3">$ET_ARCH</span><span style="color:#A5D6FF">/easytier-cli"</span><span style="color:#FF7B72"> \</span></span>
<span class="line"><span style="color:#A5D6FF">  /usr/local/bin/easytier-cli</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FFA657">/usr/local/bin/easytier-core</span><span style="color:#79C0FF"> --version</span></span>
</code></pre>
<p><code>easytier-core</code> 负责运行网络，<code>easytier-cli</code> 用于查看节点、路由和本机状态。确认版本命令能够输出信息后，再配置组网。</p>
<h2>配置服务器的私有网络</h2>
<p>生成一段随机密钥：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#FFA657">openssl</span><span style="color:#A5D6FF"> rand</span><span style="color:#79C0FF"> -hex</span><span style="color:#79C0FF"> 24</span></span>
</code></pre>
<p>保存这段输出，Mac 客户端也需要使用同一段密钥。</p>
<p>创建配置目录和文件：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> install</span><span style="color:#79C0FF"> -d</span><span style="color:#79C0FF"> -m</span><span style="color:#79C0FF"> 700</span><span style="color:#A5D6FF"> /etc/easytier</span></span>
<span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> touch</span><span style="color:#A5D6FF"> /etc/easytier/server.toml</span></span>
<span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> chmod</span><span style="color:#79C0FF"> 600</span><span style="color:#A5D6FF"> /etc/easytier/server.toml</span></span>
<span class="line"><span style="color:#FFA657">sudoedit</span><span style="color:#A5D6FF"> /etc/easytier/server.toml</span></span>
</code></pre>
<p>在编辑器中填入以下内容，将 <code>REPLACE_WITH_YOUR_SECRET</code> 替换为刚生成的密钥：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-toml"><span class="line"><span style="color:#E6EDF3">instance_name = </span><span style="color:#A5D6FF">"home"</span></span>
<span class="line"><span style="color:#E6EDF3">hostname = </span><span style="color:#A5D6FF">"vps"</span></span>
<span class="line"><span style="color:#E6EDF3">ipv4 = </span><span style="color:#A5D6FF">"10.144.144.1"</span></span>
<span class="line"><span style="color:#E6EDF3">dhcp = </span><span style="color:#79C0FF">false</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">listeners = [</span></span>
<span class="line"><span style="color:#A5D6FF">  "tcp://0.0.0.0:11010"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#A5D6FF">  "udp://0.0.0.0:11010"</span></span>
<span class="line"><span style="color:#E6EDF3">]</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">[</span><span style="color:#FFA657">network_identity</span><span style="color:#E6EDF3">]</span></span>
<span class="line"><span style="color:#E6EDF3">network_name = </span><span style="color:#A5D6FF">"demo-network"</span></span>
<span class="line"><span style="color:#E6EDF3">network_secret = </span><span style="color:#A5D6FF">"REPLACE_WITH_YOUR_SECRET"</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">[</span><span style="color:#FFA657">flags</span><span style="color:#E6EDF3">]</span></span>
<span class="line"><span style="color:#E6EDF3">private_mode = </span><span style="color:#79C0FF">true</span></span>
</code></pre>
<p>这份配置关闭 DHCP，固定服务器虚拟 IP，并只配置 TCP、UDP 两个监听器。<code>private_mode = true</code> 使服务器仅允许网络名称和密钥匹配的节点连接，适合这里的自用网络；其含义见<a href="https://easytier.cn/guide/network/host-public-server.html">官方私有模式说明</a>。</p>
<h2>使用 systemd 管理服务</h2>
<p>创建 <code>/etc/systemd/system/easytier.service</code>：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> tee</span><span style="color:#A5D6FF"> /etc/systemd/system/easytier.service</span><span style="color:#FF7B72"> ></span><span style="color:#A5D6FF">/dev/null</span><span style="color:#FF7B72"> &#x3C;&#x3C;</span><span style="color:#E6EDF3">'EOF'</span></span>
<span class="line"><span style="color:#A5D6FF">[Unit]</span></span>
<span class="line"><span style="color:#A5D6FF">Description=EasyTier</span></span>
<span class="line"><span style="color:#A5D6FF">Wants=network-online.target</span></span>
<span class="line"><span style="color:#A5D6FF">After=network-online.target</span></span>
<span class="line"></span>
<span class="line"><span style="color:#A5D6FF">[Service]</span></span>
<span class="line"><span style="color:#A5D6FF">Type=simple</span></span>
<span class="line"><span style="color:#A5D6FF">ExecStart=/usr/local/bin/easytier-core -c /etc/easytier/server.toml</span></span>
<span class="line"><span style="color:#A5D6FF">Restart=on-failure</span></span>
<span class="line"><span style="color:#A5D6FF">RestartSec=3</span></span>
<span class="line"></span>
<span class="line"><span style="color:#A5D6FF">[Install]</span></span>
<span class="line"><span style="color:#A5D6FF">WantedBy=multi-user.target</span></span>
<span class="line"><span style="color:#E6EDF3">EOF</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> systemctl</span><span style="color:#A5D6FF"> daemon-reload</span></span>
<span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> systemctl</span><span style="color:#A5D6FF"> enable</span><span style="color:#79C0FF"> --now</span><span style="color:#A5D6FF"> easytier.service</span></span>
<span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> systemctl</span><span style="color:#A5D6FF"> status</span><span style="color:#A5D6FF"> easytier.service</span><span style="color:#79C0FF"> --no-pager</span></span>
</code></pre>
<p>正常应显示 <code>active (running)</code>。本次服务状态输出中，启动命令明确指定了 <code>/etc/easytier/server.toml</code>，确认 systemd 使用的是这份配置。</p>
<p>以后修改 <code>server.toml</code>，保存后重启即可重新读取：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> systemctl</span><span style="color:#A5D6FF"> restart</span><span style="color:#A5D6FF"> easytier.service</span></span>
<span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> systemctl</span><span style="color:#A5D6FF"> status</span><span style="color:#A5D6FF"> easytier.service</span><span style="color:#79C0FF"> --no-pager</span></span>
</code></pre>
<p>如果修改的是 <code>.service</code> 文件，需要先执行 <code>systemctl daemon-reload</code>，再重启服务。<code>daemon-reload</code> 本身不会让正在运行的 EasyTier 重新读取 TOML。</p>
<p>排查启动失败或配置未生效时，可以查看服务定义和日志：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> systemctl</span><span style="color:#A5D6FF"> cat</span><span style="color:#A5D6FF"> easytier.service</span></span>
<span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> journalctl</span><span style="color:#79C0FF"> -u</span><span style="color:#A5D6FF"> easytier.service</span><span style="color:#79C0FF"> -n</span><span style="color:#79C0FF"> 50</span><span style="color:#79C0FF"> --no-pager</span></span>
</code></pre>
<p>重点检查 <code>ExecStart</code> 是否包含正确的 <code>-c</code> 路径。当前终端所在目录，不决定 systemd 从哪里读取配置。</p>
<h2>放行服务器组网端口</h2>
<p>在云平台安全组和服务器系统防火墙中，允许入站 TCP／UDP <code>11010</code>。</p>
<p>如果服务器已经启用 UFW，可执行：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> ufw</span><span style="color:#A5D6FF"> allow</span><span style="color:#A5D6FF"> 11010/tcp</span></span>
<span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> ufw</span><span style="color:#A5D6FF"> allow</span><span style="color:#A5D6FF"> 11010/udp</span></span>
</code></pre>
<p>云安全组与系统防火墙是两层独立规则，需要分别检查。这里只放行组网端口，不需要为此开放管理接口，也不需要为了运行这两条规则而额外开启 UFW。</p>
<h2>配置 Mac 客户端</h2>
<p>从<a href="https://easytier.cn/guide/download.html">官方下载页</a>选择适合 macOS 和 CPU 架构的客户端。不同客户端的界面名称可能不同，我使用的菜单栏客户端提供了“网络名称”“网络密码”“公共节点”和“虚拟 IPv4”四个字段。</p>
<p>按照本例填写：</p>
<table>
<thead>
<tr>
<th>字段</th>
<th>内容</th>
</tr>
</thead>
<tbody>
<tr>
<td>网络名称</td>
<td><code>demo-network</code>，与服务器完全一致</td>
</tr>
<tr>
<td>网络密码</td>
<td>服务器配置中的密钥</td>
</tr>
<tr>
<td>公共节点／初始节点</td>
<td><code>tcp://203.0.113.10:11010</code>，替换为真实服务器地址</td>
</tr>
<tr>
<td>虚拟 IPv4</td>
<td><code>10.144.144.2</code></td>
</tr>
</tbody>
</table>
<p>“公共节点”字段也可以填自己的公网服务器地址。虚拟 IPv4 留空会使用自动分配；这里填写固定地址，便于后续访问本机服务。</p>
<p>填好后保持“P2P 直连”开启，再打开“虚拟组网”。按系统提示授予必要权限，连接成功后检查本机虚拟 IP 和在线对端成员。“开机自启”“启动软件自动组网”可以在首次连通后按需要开启。</p>
<p>如果服务器后来修改了网络名称或密钥，Mac 也必须同步修改，并重新连接网络。</p>
<h2>可选：让公网用户访问 Mac 上的网站</h2>
<p>这一节记录配置方法，本次尚未实际验证。假设 Mac 上的网站使用 <code>8080</code> 端口，希望访客通过服务器的 <code>18080</code> 端口访问：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">访客 → 服务器公网 IP:18080 → EasyTier → 10.144.144.2:8080
</code></pre>
<p>首先确认 Mac 的实际虚拟 IP 是 <code>10.144.144.2</code>，并让网站监听 <code>10.144.144.2:8080</code> 或 <code>0.0.0.0:8080</code>。如果只监听 <code>127.0.0.1:8080</code>，其他设备无法直接通过虚拟 IP 访问。Mac 防火墙也需要允许对应应用接收入站连接。</p>
<p>在服务器先测试目标服务：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#FFA657">curl</span><span style="color:#79C0FF"> --max-time</span><span style="color:#79C0FF"> 10</span><span style="color:#A5D6FF"> http://10.144.144.2:8080</span></span>
</code></pre>
<p>确认取得预期响应后，在 <code>/etc/easytier/server.toml</code> 末尾添加一条规则：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-toml"><span class="line"><span style="color:#E6EDF3">[[</span><span style="color:#FFA657">port_forward</span><span style="color:#E6EDF3">]]</span></span>
<span class="line"><span style="color:#E6EDF3">proto = </span><span style="color:#A5D6FF">"tcp"</span></span>
<span class="line"><span style="color:#E6EDF3">bind_addr = </span><span style="color:#A5D6FF">"0.0.0.0:18080"</span></span>
<span class="line"><span style="color:#E6EDF3">dst_addr = </span><span style="color:#A5D6FF">"10.144.144.2:8080"</span></span>
</code></pre>
<p>保存后重启服务：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> systemctl</span><span style="color:#A5D6FF"> restart</span><span style="color:#A5D6FF"> easytier.service</span></span>
<span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> systemctl</span><span style="color:#A5D6FF"> status</span><span style="color:#A5D6FF"> easytier.service</span><span style="color:#79C0FF"> --no-pager</span></span>
</code></pre>
<p>再在云安全组和系统防火墙中放行入站 TCP <code>18080</code>。如果已启用 UFW：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-bash"><span class="line"><span style="color:#FFA657">sudo</span><span style="color:#A5D6FF"> ufw</span><span style="color:#A5D6FF"> allow</span><span style="color:#A5D6FF"> 18080/tcp</span></span>
</code></pre>
<p>然后从外部网络访问：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">http://203.0.113.10:18080
</code></pre>
<p>这条规则会将指定的本地服务提供给公网用户，访客不需要安装 EasyTier。正式使用时，应为服务配置符合用途的身份验证，并为网站配置 HTTPS。更多参数见<a href="https://easytier.cn/guide/network/port-forward.html">官方端口转发文档</a>。</p>
<h2>排查时按哪一层检查</h2>
<table>
<thead>
<tr>
<th>现象</th>
<th>优先检查</th>
</tr>
</thead>
<tbody>
<tr>
<td>服务启动失败</td>
<td><code>journalctl</code> 中的配置语法、TUN、端口占用等错误</td>
</tr>
<tr>
<td>修改配置后表现没变</td>
<td>是否重启服务，<code>ExecStart</code> 是否读取了修改的文件</td>
</tr>
<tr>
<td>客户端始终未组网</td>
<td>名称与密钥是否一致，服务器地址和 TCP／UDP <code>11010</code> 是否可达</td>
</tr>
<tr>
<td>节点在线但 ping 不通</td>
<td>虚拟 IP、路由冲突，以及目标机器对 ICMP 的防火墙规则</td>
</tr>
<tr>
<td>能 ping 通，但网站打不开</td>
<td>服务是否启动、监听地址、端口和应用防火墙</td>
</tr>
<tr>
<td>服务器能访问 Mac 网站，公网用户不能</td>
<td>转发规则、服务日志，以及 TCP <code>18080</code> 的两层防火墙规则</td>
</tr>
<tr>
<td>Mac 休眠后无法访问</td>
<td>Mac 是否在线，EasyTier 与本地应用是否仍在运行</td>
</tr>
</tbody>
</table>
<p>这样可以先确认虚拟网络，再确认应用服务，最后确认公网入口，避免只看到“网站打不开”就重复修改整套组网配置。</p>
]]></content:encoded>
    </item>
    <item>
      <title>如何提高 RAG 的检索精度</title>
      <link>https://felix.muke.chat/notes/rag-retrieval-precision</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/rag-retrieval-precision</guid>
      <pubDate>Sun, 01 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>从一次 Redis 故障查询出发，理解文档切分、混合召回、重排和证据组装，并用评测判断检索是否真正变好。</description>
      <category>AI Agent</category>
      <category>RAG</category>
      <category>混合检索</category>
      <category>重排</category>
      <content:encoded><![CDATA[<p>向知识库提问：“任务服务 v2 连接 Redis 超时，应该检查哪些配置？”</p>
<p>示例涉及的连接方式、持久化与集群背景，可以结合<a href="https://felix.muke.chat/notes/redis-interview-questions">《Redis 从基础到进阶》</a>阅读。</p>
<p>系统找到了几篇包含 Redis 的文档，回答却仍然不对。回看检索结果，可能发现其中混入了旧版本说明、开发环境配置，真正讲生产环境连接超时的段落排在后面。</p>
<p>这类问题需要沿着检索链路定位：文档是否完整入库，相关段落有没有被召回，排序是否合理，以及最终交给模型的内容能否支持回答。</p>
<p><strong>提高检索精度，需要先保证相关内容能进入候选集，再把适用、完整的依据排到前面。</strong></p>
<h2>先区分“没找到”和“找到了但没用上”</h2>
<p>一次典型的 RAG 流程是：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">文档解析、切分和索引
          ↓
理解问题、确定检索范围
          ↓
召回候选片段
          ↓
融合、重排和去重
          ↓
组装回答需要的证据
          ↓
模型根据证据回答
</code></pre>
<p>不同位置的问题，需要不同的处理方式：</p>
<table>
<thead>
<tr>
<th>观察到的现象</th>
<th>优先检查</th>
</tr>
</thead>
<tbody>
<tr>
<td>原文有答案，索引里没有对应内容</td>
<td>解析、切分、索引更新和文档状态</td>
</tr>
<tr>
<td>索引里有答案，但候选集没有</td>
<td>查询表达、召回方式、过滤条件和候选数量</td>
</tr>
<tr>
<td>正确片段在候选集里，但排名靠后</td>
<td>排序融合、重排和重复内容</td>
</tr>
<tr>
<td>排名靠前，但交给模型后信息不完整</td>
<td>父段落恢复、表格结构和内容截断</td>
</tr>
<tr>
<td>证据完整，回答仍然出错</td>
<td>回答阶段是否遵循证据，是否混入未经支持的推断</td>
</tr>
</tbody>
</table>
<p>先保存一次查询的候选结果、排序结果和最终证据，就能判断问题落在哪一层。只看最后的回答，很容易把所有问题都归到模型身上。</p>
<h2>让每个片段保留完整含义</h2>
<p>文档切分决定了系统实际能检索到什么。</p>
<p>例如，原文写着：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">生产环境 / 任务服务 v2 / Redis 配置

连接超时时，先检查 REDIS_HOST 是否指向服务地址。
容器内不要使用 localhost 连接独立部署的 Redis。
随后检查端口、网络连通性和连接超时设置。
</code></pre>
<p>如果切分后只剩“容器内不要使用 localhost”，片段虽然包含有效信息，却失去了服务、版本和适用环境。</p>
<p>可以从三个方面改善：</p>
<ul>
<li>按标题、段落、列表和代码块等结构切分，尽量保留完整语义。</li>
<li>为片段保存文档标题、章节路径、版本和环境等元数据。</li>
<li>表格拆分时保留表头，避免只留下几行无法解释的数据。</li>
</ul>
<p>片段大小也有取舍。过小容易丢失前提，过大会混入多个主题。重叠可以缓解边界丢失，但也会制造重复候选，需要在后面去重。</p>
<p>一种实用方式是“小片段检索，较大段落供阅读”：用子片段定位问题，再恢复对应父段落。父段落仍应围绕命中位置控制长度，避免把整篇文档全部塞入上下文。</p>
<h2>同时利用语义和关键词</h2>
<p>向量检索根据语义接近程度查找内容，适合处理不同说法。例如，“Redis 连不上”和“缓存服务连接失败”可能描述相近的问题。</p>
<p>关键词检索更容易保留精确名称，例如 <code>REDIS_HOST</code>、<code>ECONNREFUSED</code>、服务名和版本号。技术文档里的这些词，往往直接决定答案是否适用。</p>
<p>因此，可以分别执行向量检索和 BM25 等关键词检索，再合并候选结果。</p>
<p><strong>两路检索的原始分数通常不能直接相加。</strong> 向量相似度和关键词得分的含义、范围不同。一个常见的融合方法是 RRF，根据片段在各个结果列表中的名次计算综合排序。<a href="https://www.elastic.co/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion">RRF 的计算方式</a></p>
<p>例如，一个片段在两路结果中都靠前，融合后通常会得到更高排名。融合后还需要按稳定的片段 ID 去重，避免同一内容占据多个位置。</p>
<h2>用重排筛选真正相关的候选</h2>
<p>召回阶段需要尽量把相关内容找进来；重排阶段则进一步比较“这个问题”和“这个片段”是否匹配。</p>
<p>例如，三段内容都提到了 Redis：</p>
<table>
<thead>
<tr>
<th>候选内容</th>
<th>对当前问题的帮助</th>
</tr>
</thead>
<tbody>
<tr>
<td>Redis 的基本介绍</td>
<td>介绍概念，缺少故障处理方法</td>
</tr>
<tr>
<td>任务服务 v1 的开发环境配置</td>
<td>有配置说明，但版本和环境不匹配</td>
</tr>
<tr>
<td>任务服务 v2 的生产连接排查</td>
<td>直接覆盖问题中的条件</td>
</tr>
</tbody>
</table>
<p>重排模型会对问题与候选文本进行相关性评分，帮助把第三段放到前面。但它只能调整已经召回的内容，无法补回候选集中不存在的答案。</p>
<p>可以先尝试两路各召回 20 个片段，融合后取前 20 个重排，再选少量证据交给模型。这些数字只是起始实验配置，需要结合文档规模、延迟和评测结果调整。</p>
<p>同时区分三个数量：<strong>召回多少候选、重排多少候选、最终提供多少证据。</strong> 提高候选数量，并不意味着最终上下文也要同样变长。</p>
<h2>保留问题里的条件，再组装证据</h2>
<p>用户的问题可能依赖前文：</p>
<blockquote>
<p>前文：我们现在部署的是任务服务 v2，使用 Docker。<br>
当前问题：那 Redis 超时怎么处理？</p>
</blockquote>
<p>检索时可以补全为“任务服务 v2 Docker 部署 Redis 连接超时排查”。补全应保留已知条件；没有提供的信息，不应自行猜测。</p>
<p>对于已经确定的版本、环境或文档范围，可以使用元数据过滤。权限条件应由程序强制执行，不能交给模型自行决定；业务过滤则需要注意文档标注是否完整，避免过严导致漏召回。</p>
<p>最终证据也需要整理：合并重复片段、保留章节标题、恢复必要上下文，并附上来源和版本。内容超长时，应标明截断，并支持继续读取。</p>
<p>相似度阈值同样需要评测。不同模型和距离度量下的分数含义不同，不能假设一个固定数值在所有知识库中都有效。</p>
<p>如果要把向量召回、过滤和混合检索落到具体实现，可以结合<a href="https://felix.muke.chat/notes/qdrant-from-beginner-to-advanced">《Qdrant 从入门到进阶：原理与 Python 实战》</a>中的完整示例练习。</p>
<h2>用固定问题验证是否变好</h2>
<p>调参前，先整理一组真实问题，并标注哪些文档或片段能够支持回答。评测时保持单位一致，例如都按片段 ID 判断相关性，并在统计前去重。</p>
<table>
<thead>
<tr>
<th>指标</th>
<th>可以回答的问题</th>
</tr>
</thead>
<tbody>
<tr>
<td>Precision@K</td>
<td>前 K 个结果中，有多少比例确实相关</td>
</tr>
<tr>
<td>Recall@K</td>
<td>已标注的相关结果，有多少进入了前 K 个</td>
</tr>
<tr>
<td>MRR</td>
<td>第一个相关结果通常排在多靠前的位置</td>
</tr>
<tr>
<td>检索延迟</td>
<td>精度改善是否带来可接受的等待时间</td>
</tr>
</tbody>
</table>
<p>假设某个问题有 3 个已标注相关片段，返回的前 5 个结果中包含其中 2 个，那么 Precision@5 为 <code>2/5</code>，Recall@5 为 <code>2/3</code>。这只是指标示例，不代表实际评测结果。</p>
<p>每次尽量只调整一类因素，例如先改变切分方式，再比较混合检索，最后评估重排。固定问题集和其他条件，才容易看出是哪一步带来了变化。</p>
<p>如果答案没有进入候选集，就先改善解析和召回；如果答案已经在候选集中，就检查排序和证据组装。这样调整，每个改动都能对应一个可观察的问题。</p>
]]></content:encoded>
    </item>
    <item>
      <title>Redis 从基础到进阶</title>
      <link>https://felix.muke.chat/notes/redis-interview-questions</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/redis-interview-questions</guid>
      <pubDate>Sun, 01 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>整理 Redis 的数据类型、持久化、过期与淘汰、线程模型、事务、集群、分布式锁和缓存异常，配合图解与 Python 示例回顾常见面试问题。</description>
      <category>数据库</category>
      <category>Redis</category>
      <category>缓存</category>
      <content:encoded><![CDATA[<h2>一、基础</h2>
<h3>1.1 什么是Redis</h3>
<p>Redis（Remote Dictionary Server）是用 C 语言实现的内存数据存储，采用键值模型，常用于缓存、计数、会话、排行榜和消息处理。</p>
<p>键通常是字符串，值可以使用不同的数据结构。面试中最常讨论的是 String、List、Set、Hash 和 Sorted Set；它们是五种基础类型，不代表 Redis 只有这五种能力。</p>
<p>Redis 还提供持久化、复制、事务、Lua 脚本及集群机制。它的速度优势主要来自内存访问和高效的数据结构，实际吞吐量需要结合命令复杂度、数据大小、网络和硬件测量。</p>
<h3>1.2 Redis 有哪些优缺点？</h3>
<p><strong>优点</strong></p>
<ul>
<li>读写延迟低，适合频繁访问的热点数据；具体 QPS 取决于测试环境，不能把某个固定数字当作性能保证。</li>
<li>支持 RDB 和 AOF 持久化，具体取舍见后文。</li>
<li>支持命令原子执行和事务顺序执行；事务的错误处理与回滚限制需要单独理解。</li>
<li>数据结构丰富，可以直接表达集合、排行榜和字段映射。</li>
<li>支持主从复制，结合 Sentinel 或 Redis Cluster 可以实现故障转移。</li>
</ul>
<p><strong>限制</strong></p>
<ul>
<li>内存成本较高，需要控制数据规模、过期时间及淘汰策略。</li>
<li>异步复制存在延迟，故障转移时可能丢失尚未复制的写入。</li>
<li>高可用需要额外的节点、客户端支持和运维；单机部署不会自动获得这些能力。</li>
<li>Redis Cluster 支持在线扩缩容，但仍需规划槽迁移、容量余量及迁移期间的负载。</li>
</ul>
<h3>1.3 为什么要用 Redis，为什么要用缓存？</h3>
<p>主要从“高性能”和“高并发”这两点来看待这个问题。</p>
<p><strong>高性能</strong></p>
<p>假如一个查询需要多表关联、聚合或读取较多数据，可以把结果存入缓存，让后续请求直接复用，减少数据库计算与 I/O。数据库自身也有缓冲池，不能简单理解为每次查询都读硬盘；缓存的价值在于避免重复完成昂贵的查询。数据库更新后，还要设计缓存更新或失效机制，具体见缓存一致性部分。</p>
<p><img src="https://felix.muke.chat/images/posts/2026-11-01-redis-interview-questions/cache-performance.webp" alt="通过缓存减少重复读取数据库"></p>
<p><strong>高并发</strong></p>
<p>直接操作缓存能够承受的请求是远远大于直接访问数据库的，所以我们可以考虑把数据库中的部分数据转移到缓存中去，这样用户的一部分请求会直接到缓存这里而不用经过数据库。</p>
<p><img src="https://felix.muke.chat/images/posts/2026-11-01-redis-interview-questions/cache-concurrency.webp" alt="让热点请求优先访问缓存"></p>
<h3>1.4 为什么要用 Redis 而不用 全局字典 做缓存？</h3>
<p>缓存分为本地缓存和分布式缓存。以 Python 为例，使用自带的 字典 实现的是本地缓存，最主要的特点是轻量以及快速，生命周期随着程序 的销毁而结束，并且在多实例的情况下，每个实例都需要各自保存一份缓存，缓存不具有一致性。</p>
<p>使用 redis 或 memcached 之类的称为分布式缓存，在多实例的情况下，各实例访问同一份共享缓存，避免各自维护独立副本；这不代表缓存与数据库自动具有强一致性。缺点是需要保持 redis 或 memcached服务的高可用，整个程序架构上较为复杂。</p>
<h3>1.5 Redis 为什么这么快？</h3>
<ol>
<li><strong>内存访问</strong>：常规读写主要在内存中完成，减少磁盘随机访问。</li>
<li><strong>专门设计的数据结构</strong>：不同类型采用适合其操作的编码与算法。并非所有命令都是 O(1)，大集合遍历仍可能阻塞服务。</li>
<li><strong>命令执行模型简单</strong>：常规命令主要在主线程串行执行，减少共享数据上的锁竞争。</li>
<li><strong>I/O 多路复用</strong>：一个事件循环可以管理大量连接，不必为每个连接创建执行线程。</li>
</ol>
<p>“Redis 是单线程”主要描述命令执行模型，不能理解为整个进程只有一个线程。后台任务和网络 I/O 的并行方式与版本、配置有关，详见第六节。旧资料中的虚拟内存机制不是现代 Redis 的性能依据。<a href="https://redis.io/docs/latest/develop/get-started/faq/">Redis FAQ</a></p>
<h2>二、数据类型</h2>
<h3>2.1 Redis有哪些数据类型</h3>
<p>Redis 最常讨论的五种基础数据类型是 String、List、Set、Sorted Set 和 Hash。其他数据能力以所用版本为准。</p>
<table>
<thead>
<tr>
<th>数据类型</th>
<th>可以存储的值</th>
<th>常见操作</th>
<th>应用场景</th>
</tr>
</thead>
<tbody>
<tr>
<td>String</td>
<td>字符串、整数、浮点数</td>
<td>读写字符串或子串；整数、浮点数自增</td>
<td>键值缓存、计数器、验证码</td>
</tr>
<tr>
<td>List</td>
<td>有序列表</td>
<td>两端插入和弹出；按范围读取和裁剪</td>
<td>消息列表、最近记录</td>
</tr>
<tr>
<td>Set</td>
<td>不重复的无序集合</td>
<td>添加、删除、成员判断；交集、并集、差集</td>
<td>共同好友、去重</td>
</tr>
<tr>
<td>Hash</td>
<td>字段与值的映射</td>
<td>读写字段、删除字段、遍历字段</td>
<td>用户信息、商品详情</td>
</tr>
<tr>
<td>Sorted Set / ZSet</td>
<td>带分数的不重复成员集合</td>
<td>按分数或排名读取、添加和删除成员</td>
<td>排行榜、延时任务</td>
</tr>
</tbody>
</table>
<h3>2.2 Redis的应用场景</h3>
<h4>场景一：按用途选择</h4>
<p><strong>计数器</strong></p>
<p>可以对 字符串 进行自增自减运算，从而实现计数器功能。Redis 这种内存型数据库的读写性能非常高，很适合存储频繁读写的计数量。</p>
<p><strong>缓存</strong></p>
<p>将热点数据放到内存中，设置内存的最大使用量以及淘汰策略来保证缓存的命中率。</p>
<p><strong>会话缓存(session)</strong></p>
<p>可以使用 Redis 来统一存储多台应用服务器的会话信息。当应用服务器不再存储用户的会话信息，也就不再具有状态，一个用户可以请求任意一个应用服务器，从而更容易实现高可用性以及可伸缩性。</p>
<p><strong>全页缓存</strong></p>
<p>应用或 Web 框架可以把完整页面缓存到 Redis，减少重复渲染。个性化页面还要考虑用户隔离、权限和失效规则。</p>
<p><strong>查找表</strong></p>
<p>经常读取的配置或映射关系可以放在 Redis 中查询。需要明确 Redis 是缓存还是数据源，并据此设计过期、持久化及恢复；DNS 这类数据也有各自的 TTL 语义。</p>
<p><strong>消息队列(发布/订阅功能)</strong></p>
<p>List 可以从两端插入、弹出元素，例如用 LPUSH 和 RPOP 构造简单队列。List 队列与 Pub/Sub 是不同机制；需要确认、重试或消费组时，应进一步评估 Redis Streams 或专用消息中间件。</p>
<p><strong>分布式锁实现</strong></p>
<p>在分布式场景下，无法使用单机环境下的锁来对多个节点上的进程进行同步。可以利用 Redis 的条件写入和 TTL 实现带租约的锁，但还要正确处理标识校验、释放和超时，详见第十节。</p>
<p><strong>其它</strong></p>
<p>Set 可以实现交集、并集等操作，从而实现共同好友等功能。ZSet 可以实现有序性操作，从而实现排行榜等功能。</p>
<h4>场景二：按数据类型选择</h4>
<p>Redis相比其他缓存，有一个非常大的优势，就是支持多种数据类型。</p>
<p>五种基础类型分别对应键值、字段映射、有序列表、无序集合和带分数的有序集合。</p>
<p>其实，通过上面的数据类型的特性，基本就能想到合适的应用场景了。</p>
<p>string——适合最简单的k-v存储，类似于memcached的存储结构，短信验证码，配置信息等，就用这种类型来存储。</p>
<p>hash——一般key为ID或者唯一标示，value对应的就是详情了。如商品详情，个人信息详情，新闻详情等。</p>
<p>list——因为list是有序的，比较适合存储一些有序且数据相对固定的数据。如省市区表、字典表等。因为list是有序的，适合根据写入的时间来排序，例如最近消息、按写入顺序排列的记录等。</p>
<p>set——可以简单的理解为ID-List的模式，如微博中一个人有哪些好友，set最牛的地方在于，可以对两个set提供交集、并集、差集操作。例如:查找两个人共同的好友等。</p>
<p>Sorted Set——是set的增强版本，增加了一个score参数，自动会根据score的值进行排序。比较适合类似于top 10等不根据插入的时间来排序的数据。</p>
<p>如上所述，虽然Redis不像关系数据库那么复杂的数据结构，但是，也能适合很多场景，比一般的缓存数据结构要多。了解每种数据结构适合的业务场景，不仅有利于提升开发效率，也能有效利用Redis的性能。</p>
<h2>三、持久化</h2>
<h3>3.1 什么是Redis持久化？</h3>
<p>持久化就是把内存的数据写到磁盘中去，防止服务宕机了内存数据丢失。</p>
<h3>3.2 Redis 的持久化机制是什么？各自的优缺点？</h3>
<p>Redis 常见的持久化方式是 RDB 快照和 AOF 写入日志，也可以组合使用。</p>
<h4>RDB：保存某一时刻的数据快照</h4>
<p>通过配置中的 <code>save</code> 规则或执行 <code>BGSAVE</code>，把内存数据保存为 RDB 文件。后台保存通常由 fork 出的子进程完成；<code>SAVE</code> 则同步执行并阻塞服务。</p>
<p><img src="https://felix.muke.chat/images/posts/2026-11-01-redis-interview-questions/rdb-persistence.webp" alt="RDB 快照的保存与加载"></p>
<p>优点是文件紧凑、便于备份和迁移，恢复较大数据集通常较快。缺点是故障时可能丢失最后一次快照之后的写入；fork 和写时复制也会带来延迟及额外内存开销。</p>
<h4>AOF：记录数据修改</h4>
<p>AOF 将改变数据的操作写入日志，重启时据此恢复数据。刷盘策略需要在性能与数据丢失窗口之间取舍。</p>
<p><img src="https://felix.muke.chat/images/posts/2026-11-01-redis-interview-questions/aof-persistence.webp" alt="AOF 写命令日志的持久化"></p>
<table>
<thead>
<tr>
<th><code>appendfsync</code></th>
<th>刷盘策略</th>
<th>主要取舍</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>always</code></td>
<td>每批写入追加后同步刷盘</td>
<td>更强的持久性，写入延迟和磁盘开销更高</td>
</tr>
<tr>
<td><code>everysec</code></td>
<td>通常每秒刷盘</td>
<td>常用折中，故障时可能丢失约一秒的数据</td>
</tr>
<tr>
<td><code>no</code></td>
<td>交给操作系统刷盘</td>
<td>丢失窗口取决于操作系统</td>
</tr>
</tbody>
</table>
<p>AOF 重写会用更紧凑的内容表示当前数据，降低历史命令累积的体积。AOF 往往比 RDB 更大，恢复性能也依数据和配置而变。两种持久化都开启时，Redis 重启通常优先使用 AOF 恢复。</p>
<p><code>redis-check-aof</code> 可用于检查和修复损坏的 AOF，但不能恢复从未落盘的写入。不要把直接编辑运行中的 AOF 当作通用的数据恢复手段。Redis 7 起 AOF 还可以采用多文件组织，备份时应遵循对应版本的说明。<a href="https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/">持久化官方说明</a></p>
<h3>3.3 如何选择合适的持久化方式？</h3>
<p>先明确数据能否重建，以及允许丢失多长时间的写入，再选择持久化方式。</p>
<ul>
<li><strong>纯缓存，数据可从数据库重建</strong>：可以不持久化，但要考虑重启后的预热和回源压力。</li>
<li><strong>允许丢失最近一段时间的数据，重视快照备份</strong>：可以采用 RDB，并确定快照周期。</li>
<li><strong>希望缩小丢失窗口</strong>：考虑 AOF，并评估 <code>everysec</code> 或 <code>always</code> 的开销。</li>
<li><strong>需要日志恢复与周期备份</strong>：可以组合 AOF 和 RDB，同时做好异机备份和恢复演练。</li>
</ul>
<p>是否开启两种持久化，并不能单独证明系统具有某种数据库级别的安全保证；还要考虑磁盘、复制、备份及故障恢复流程。</p>
<h3>3.4 Redis缓存怎么做扩容？</h3>
<p>扩容首先要确定数据如何分布。</p>
<ul>
<li><strong>Redis Cluster</strong>：增加节点，再把部分哈希槽迁移到新节点，客户端根据集群拓扑和重定向访问数据。</li>
<li><strong>客户端或代理分片</strong>：调整节点映射并迁移数据。一致性哈希可以减少映射变化的范围，但不会自动完成数据搬迁。</li>
<li><strong>只读压力较高</strong>：增加副本可分担读流量，但副本不能增加主节点可写数据的分片容量。</li>
</ul>
<p>无论 Redis 用作缓存还是持久存储，扩容都需要考虑数据迁移、复制延迟、容量余量和回滚。缓存可重建，也应避免扩容造成大面积回源。</p>
<h2>四、过期键的删除策略</h2>
<h3>4.1 Redis的过期键的删除策略</h3>
<p>我们都知道，Redis是key-value数据库，我们可以设置Redis中缓存的key的过期时间。Redis的过期策略就是指当Redis中缓存的key过期了，Redis如何处理。</p>
<p>过期策略通常有以下三种:</p>
<ul>
<li>
<p>定时过期:每个设置过期时间的key都需要创建一个定时器，到过期时间就会立即清除。该策略可以立即清除过期的数据，对内存很友好；但是会占用大量的CPU资源去处理过期的数据，从而影响缓存的响应时间和吞吐量。</p>
</li>
<li>
<p>惰性过期:只有当访问一个key时，才会判断该key是否已过期，过期则清除。该策略可以最大化地节省CPU资源，却对内存非常不友好。极端情况可能出现大量的过期key没有再次被访问，从而不会被清除，占用大量内存。</p>
</li>
<li>
<p>定期过期:每隔一定的时间，会扫描一定数量的数据库的expires字典中一定数量的key，并清除其中已过期的key。该策略是前两者的一个折中方案。通过调整定时扫描的时间间隔和每次扫描的限定耗时，可以在不同情况下使得CPU和内存资源达到最优的平衡效果。(expires字典会保存所有设置了过期时间的key的过期时间数据，其中，key是指向键空间中的某个键的指针，value是该键的毫秒精度的UNIX时间戳表示的过期时间。键空间是指该Redis集群中保存的所有键。)</p>
</li>
</ul>
<p>Redis中同时使用了惰性过期和定期过期两种过期策略。</p>
<h3>4.2 Redis key的过期时间和永久有效分别怎么设置？</h3>
<p>EXPIRE和PERSIST命令。</p>
<h3>4.3 我们知道通过expire来设置key 的过期时间，那么对过期的数据怎么处理呢？</h3>
<p>Redis 通过访问时检查和后台主动过期来清理过期键。应用读取到缓存未命中后，可以查询数据库，再设置新的缓存和有效期。</p>
<p>应用还可以按需预热或定时刷新关键数据，但应避免定时任务与请求同时重复重建缓存。热点键通常需要配合互斥重建、逻辑过期或请求合并。</p>
<p>这里需要区分：<strong>过期删除</strong>处理已经到期的数据，<strong>内存淘汰</strong>处理达到 <code>maxmemory</code> 限制时的空间压力。两者不是同一种机制。</p>
<h2>五、内存相关</h2>
<h3>5.1 MySQL里有2000w数据，redis中只存20w的数据，如何保证redis中的数据都是热点数据</h3>
<p>设置合理的 <code>maxmemory</code>，结合访问特点选择 <code>allkeys-lru</code> 或 <code>allkeys-lfu</code> 等策略，让低价值数据逐步退出缓存。</p>
<p>LRU 关注最近是否访问，LFU 关注访问频率。Redis 的这些淘汰算法采用近似实现，不能保证留下的恰好是业务定义的前 20 万条热点数据。还应结合 TTL、命中率和业务预热持续观察效果。</p>
<h3>5.2 Redis的内存淘汰策略有哪些</h3>
<p>达到 <code>maxmemory</code> 限制后，Redis 根据 <code>maxmemory-policy</code> 决定是否淘汰数据。常见策略如下，具体支持项以所用版本为准。</p>
<table>
<thead>
<tr>
<th>策略</th>
<th>候选键</th>
<th>选择方式</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>noeviction</code></td>
<td>不淘汰</td>
<td>需要新增空间的写入可能报错，读取仍可继续</td>
</tr>
<tr>
<td><code>allkeys-lru</code></td>
<td>所有键</td>
<td>近似最近最少使用</td>
</tr>
<tr>
<td><code>allkeys-lfu</code></td>
<td>所有键</td>
<td>近似最不经常使用</td>
</tr>
<tr>
<td><code>allkeys-random</code></td>
<td>所有键</td>
<td>随机</td>
</tr>
<tr>
<td><code>volatile-lru</code></td>
<td>设置了 TTL 的键</td>
<td>近似最近最少使用</td>
</tr>
<tr>
<td><code>volatile-lfu</code></td>
<td>设置了 TTL 的键</td>
<td>近似最不经常使用</td>
</tr>
<tr>
<td><code>volatile-random</code></td>
<td>设置了 TTL 的键</td>
<td>随机</td>
</tr>
<tr>
<td><code>volatile-ttl</code></td>
<td>设置了 TTL 的键</td>
<td>优先选择剩余生存时间较短的键</td>
</tr>
</tbody>
</table>
<p>如果没有带 TTL 的候选键，<code>volatile-*</code> 策略不能释放这部分空间。较新版本还可能提供其他策略，应查对应版本的配置说明。<a href="https://redis.io/docs/latest/develop/reference/eviction/">内存淘汰策略</a></p>
<h3>5.3 Redis主要消耗什么物理资源？</h3>
<p>内存。</p>
<h3>5.4 Redis的内存用完了会发生什么？</h3>
<p>达到 <code>maxmemory</code> 后，行为由淘汰策略决定：能淘汰出足够空间时继续写入；<code>noeviction</code> 或无法释放足够空间时，需要新增空间的写入可能报错，读取仍可继续。应用需要处理写入失败，并监控系统可用内存，避免进程遭操作系统终止。</p>
<h3>5.5 Redis如何做内存优化？</h3>
<p>优先减少无效数据、过长的键名及重复字段，给可过期的数据设置 TTL，避免一个键承载过大的集合。</p>
<p>小型 Hash、List 等结构在满足条件时会使用紧凑编码。用户详情这类相关字段可以放入一个 Hash，但不能把“所有数据都改成 Hash”当作通用优化：仍要考虑访问方式、独立过期需求及结构增大后的编码变化。</p>
<p>可以通过 <code>MEMORY USAGE</code> 和 <code>INFO memory</code> 定位内存消耗，再结合命中率和淘汰情况调整。</p>
<h2>六、线程模型</h2>
<h3>6.1 Redis线程模型</h3>
<p>Redis基于Reactor模式开发了网络事件处理器，这个处理器被称为文件事件处理器(file event handler)。它的组成结构为4部分:多个套接字、IO多路复用程序、文件事件分派器、事件处理器。因为文件事件分派器队列的消费是单线程的，所以Redis才叫单线程模型。</p>
<ul>
<li>
<p>文件事件处理器使用 I/O 多路复用(multiplexing)程序来同时监听多个套接字， 并根据套接字目前执行的任务来为套接字关联不同的事件处理器。</p>
</li>
<li>
<p>当被监听的套接字准备好执行连接应答(accept)、读取(read)、写入(write)、关闭(close)等操作时， 与操作相对应的文件事件就会产生， 这时文件事件处理器就会调用套接字之前关联好的事件处理器来处理这些事件。</p>
</li>
</ul>
<p>虽然文件事件处理器以单线程方式运行， 但通过使用 I/O 多路复用程序来监听多个套接字， 文件事件处理器既实现了高性能的网络通信模型， 又可以很好地与 redis 服务器中其他同样以单线程方式运行的模块进行对接， 这保持了 Redis 内部单线程设计的简单性。</p>
<p>这里描述的是经典 Reactor 命令处理模型。Redis 6 起可配置 I/O 线程分担部分网络读写，后台释放等任务也可以使用其他线程；常规命令执行仍主要由主线程完成。不能把“单线程”理解成 Redis 的所有工作都在同一线程上执行。<a href="https://github.com/redis/redis/blob/7.2/redis.conf">Redis 配置中的 I/O 线程说明</a></p>
<h2>七、事务</h2>
<h3>7.1 什么是事务？</h3>
<p>一般数据库语境中的事务，是将一组操作作为一个工作单元，并讨论其原子性、一致性、隔离性和持久性。</p>
<p>Redis 的事务需要单独理解：<code>MULTI</code> 到 <code>EXEC</code> 之间的命令先入队，执行时按顺序处理，不被其他客户端的命令插入。这里的隔离执行不等于失败时自动撤销全部写入。</p>
<h3>7.2 Redis事务的概念</h3>
<p>Redis 事务的本质是通过MULTI、EXEC、WATCH等一组命令的集合。事务支持一次执行多个命令，一个事务中所有命令都会被序列化。在事务执行过程，会按照顺序串行化执行队列中的命令，其他客户端提交的命令请求不会插入到事务执行命令序列中。</p>
<p>总结说:redis事务就是一次性、顺序性、排他性的执行一个队列中的一系列命令。</p>
<h3>7.3 Redis事务的三个阶段</h3>
<ol>
<li><code>MULTI</code>：进入事务状态。</li>
<li>命令入队：客户端继续发送命令，正常入队时收到 <code>QUEUED</code>。</li>
<li><code>EXEC</code>：按顺序执行队列；也可以用 <code>DISCARD</code> 放弃尚未执行的事务。</li>
</ol>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-redis">MULTI
SET user:1:name &quot;Yang&quot;
INCR user:1:visits
EXEC
</code></pre>
<p>入队阶段其他客户端仍可以执行命令；真正执行 <code>EXEC</code> 队列时，其他客户端命令不会插入其中。</p>
<h3>7.4 Redis事务相关命令</h3>
<table>
<thead>
<tr>
<th>命令</th>
<th>作用</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>MULTI</code></td>
<td>开启事务并开始收集命令</td>
</tr>
<tr>
<td><code>EXEC</code></td>
<td>执行队列，按顺序返回各命令的结果</td>
</tr>
<tr>
<td><code>DISCARD</code></td>
<td>丢弃未执行的队列并退出事务状态</td>
</tr>
<tr>
<td><code>WATCH</code></td>
<td>监视键；在提交前被修改时，事务不再执行</td>
</tr>
<tr>
<td><code>UNWATCH</code></td>
<td>取消对所有键的监视</td>
</tr>
</tbody>
</table>
<p>错误需要分两类：</p>
<ul>
<li><strong>入队错误</strong>：例如未知命令、参数数量错误，会使 <code>EXEC</code> 拒绝执行整个事务。</li>
<li><strong>执行错误</strong>：例如对字符串执行列表操作，该命令报错，其他命令仍会执行，已成功的写入不会回滚。</li>
</ul>
<p><code>WATCH</code> 提供乐观并发控制；因为监视键变化而取消时，<code>EXEC</code> 返回空结果，应用需要按业务决定是否重试。<a href="https://redis.io/docs/latest/develop/using-commands/transactions/">Redis 事务说明</a></p>
<h3>7.5 事务管理(ACID)概述</h3>
<p><strong>原子性(Atomicity)</strong></p>
<p>原子性是指事务是一个不可分割的工作单位，事务中的操作要么都发生，要么都不发生。</p>
<p><strong>一致性(Consistency)</strong></p>
<p>事务前后数据的完整性必须保持一致。</p>
<p><strong>隔离性(Isolation)</strong></p>
<p>多个事务并发执行时，一个事务的执行不应影响其他事务的执行</p>
<p><strong>持久性(Durability)</strong></p>
<p>持久性是指一个事务一旦被提交，它对数据库中数据的改变就是永久性的，接下来即使数据库发生故障也不应该对其有任何影响</p>
<p>不能把 ACID 的四个词直接套成 Redis 的完整保证。Redis 事务提供隔离执行，但不自动维护业务约束，也不回滚运行时错误；持久性依赖持久化配置和故障模型。</p>
<h3>7.6 Redis事务支持隔离性吗</h3>
<p>Redis 在执行 <code>EXEC</code> 中的命令序列时，不会插入其他客户端的命令。因此可以把事务的提交执行视为一个隔离的连续操作。</p>
<p>但 <code>WATCH</code> 后的读取，以及 <code>MULTI</code> 之前的业务计算，不会自动得到传统关系数据库的事务隔离级别；需要用监视、重试或 Lua 脚本表达相关约束。</p>
<h3>7.7 Redis事务保证原子性吗，支持回滚吗</h3>
<p>Redis 事务具有连续、隔离执行的特点，但不提供“任意一步失败就撤销全部操作”的回滚语义。</p>
<p>队列中出现运行时错误，不会撤销此前成功的命令，也不会阻止后续命令继续执行。所以回答原子性问题时，应明确是在讨论不可交错执行，还是失败后的全部撤销。</p>
<h3>7.8 Redis事务其他实现</h3>
<p>Lua 脚本适合把读取、判断和修改组合成一次执行，中途不会插入其他客户端命令。</p>
<p>但 Lua 也不提供自动回滚。<code>redis.call()</code> 的运行时错误通常会终止脚本，已经完成的写入不会撤销；<code>redis.pcall()</code> 则把错误作为返回值交给脚本处理，是否继续由代码决定。不能套用 Redis 事务“其他命令仍继续执行”的规则。<a href="https://redis.io/docs/latest/develop/programmability/lua-api/">Lua API</a></p>
<p>也可以用状态或标记变量描述业务步骤是否完成，但这需要应用自行处理失败、补偿和重试，并不会自动获得数据库事务语义。</p>
<h2>八、集群方案</h2>
<h3>8.1 哨兵模式</h3>
<p><img src="https://felix.muke.chat/images/posts/2026-11-01-redis-interview-questions/sentinel.webp" alt="Sentinel 监控主从节点"></p>
<p><strong>哨兵的介绍</strong></p>
<p>sentinel，中文名是哨兵。哨兵是 redis 集群机构中非常重要的一个组件，主要有以下功能:</p>
<ul>
<li>
<p>集群监控:负责监控 redis master 和 slave 进程是否正常工作。</p>
</li>
<li>
<p>消息通知:如果某个 redis 实例有故障，那么哨兵负责发送消息作为报警通知给管理员。</p>
</li>
<li>
<p>故障转移:如果 master node 挂掉了，会自动转移到 slave node 上。</p>
</li>
<li>
<p>配置中心:如果故障转移发生了，通知 client 客户端新的 master 地址。</p>
</li>
</ul>
<p>哨兵用于实现 redis 集群的高可用，本身也是分布式的，作为一个哨兵集群去运行，互相协同工作。</p>
<ul>
<li>
<p>主节点的客观下线判定需要达到配置的 <code>quorum</code>；真正执行故障转移还需要获得 Sentinel 多数派授权。</p>
</li>
<li>
<p>即使部分哨兵节点挂掉了，哨兵集群还是能正常工作的，因为如果一个作为高可用机制重要组成部分的故障转移系统本身是单点的，就会影响整体可用性。</p>
</li>
</ul>
<p><strong>哨兵的核心知识</strong></p>
<ul>
<li>
<p>为了容忍节点故障，通常至少部署 3 个 Sentinel 实例，并分散故障域。</p>
</li>
<li>
<p>Sentinel 加主从复制用于提高可用性，但异步复制不能保证故障转移时零数据丢失。</p>
</li>
<li>
<p>对于哨兵 + redis 主从这种复杂的部署架构，尽量在测试环境和生产环境，都进行充足的测试和演练。</p>
</li>
</ul>
<h3>8.2 Redis集群方案(Redis Cluster )方案</h3>
<p><img src="https://felix.muke.chat/images/posts/2026-11-01-redis-interview-questions/redis-cluster.webp" alt="Redis Cluster 分片与副本示意"></p>
<p>Redis Cluster 通过分片扩展数据容量。它采用 <strong>16,384 个哈希槽</strong>，而不是一致性哈希环。每个主节点负责一部分槽，副本复制对应主节点的数据。</p>
<p><strong>一次请求如何找到节点</strong></p>
<ol>
<li>客户端根据键计算槽位，并维护槽与节点的映射。</li>
<li>请求发到错误节点时，服务端返回 <code>MOVED</code> 等重定向信息，由客户端访问正确节点。</li>
<li>扩容时迁移部分槽及其数据，并更新拓扑。</li>
</ol>
<p>节点之间通过集群总线交换状态和故障信息。总线端口默认是数据端口加 10,000，例如数据端口 6379、总线端口 16379；也可以单独配置总线端口。</p>
<p><strong>优点与限制</strong></p>
<ul>
<li>数据分片和副本机制支持容量扩展及自动故障转移；Cluster 有自己的故障检测机制，不需要另外部署 Sentinel。</li>
<li>客户端直接访问节点，通常不必经过统一代理；客户端必须支持集群协议，并能访问拓扑中的目标节点。</li>
<li>只支持数据库 0。</li>
<li>多键操作、事务和 Lua 脚本通常要求相关键处于同一槽，可用 <code>{user:1}:name</code>、<code>{user:1}:visits</code> 这样的 hash tag 保持同槽。</li>
<li>支持集群的客户端可以提供 pipeline，不能笼统说 Cluster 不支持批量操作；跨节点 pipeline 也不因此成为一个原子事务。</li>
<li>主从复制仍是异步的，故障转移可能丢失尚未复制的写入；扩缩容需要规划槽迁移和负载。</li>
</ul>
<p><a href="https://redis.io/docs/latest/operate/oss_and_stack/management/scaling/">Redis Cluster 说明</a></p>
<h3>8.3 基于客户端分配</h3>
<p><img src="https://felix.muke.chat/images/posts/2026-11-01-redis-interview-questions/client-sharding.webp" alt="由客户端决定请求的 Redis 节点"></p>
<p><strong>简介</strong></p>
<p>Redis Sharding是Redis Cluster出来之前，业界普遍使用的多Redis实例集群方法。其主要思想是采用哈希算法将Redis数据的key进行散列，通过hash函数，特定的key会映射到特定的Redis节点上。</p>
<p><strong>优点</strong></p>
<p>优势在于非常简单，服务端的Redis实例彼此独立，相互无关联，每个Redis实例像单服务器一样运行，非常容易线性扩展，系统的灵活性很强</p>
<p><strong>缺点</strong></p>
<ul>
<li>
<p>由于sharding处理放到客户端，规模进一步扩大时给运维带来挑战。</p>
</li>
<li>
<p>简单的静态客户端分片不直接提供动态增删节点与自动迁移。服务端Redis实例群拓扑结构有变化时，每个客户端都需要更新调整。连接不能共享，当应用规模增大时，资源浪费制约优化</p>
</li>
</ul>
<h3>8.4 基于代理服务器分片</h3>
<p><img src="https://felix.muke.chat/images/posts/2026-11-01-redis-interview-questions/proxy-sharding.webp" alt="由代理转发请求到 Redis 节点"></p>
<p><strong>简介</strong></p>
<p>客户端发送请求到一个代理组件，代理解析客户端的数据，并将请求转发至正确的节点，最后将结果回复给客户端</p>
<p><strong>特征</strong></p>
<ul>
<li>
<p>透明接入，业务程序不用关心后端Redis实例，切换成本低</p>
</li>
<li>
<p>Proxy 的逻辑和存储的逻辑是隔离的</p>
</li>
<li>
<p>代理层多了一次转发，性能有所损耗</p>
</li>
</ul>
<p><strong>业界开源方案</strong></p>
<ul>
<li>
<p>Twitter开源的Twemproxy</p>
</li>
<li>
<p>豌豆荚开源的Codis</p>
</li>
</ul>
<h3>8.5 Redis 主从架构</h3>
<p>主从架构通常由一个主节点处理写入，一个或多个副本复制数据。应用可以将允许陈旧数据的查询分流到副本，提高读吞吐量；要求读到刚写入结果的请求需要另行设计读写路径。</p>
<p><img src="https://felix.muke.chat/images/posts/2026-11-01-redis-interview-questions/read-write-splitting.webp" alt="Redis 主从复制与读写分离"></p>
<p>复制默认是异步的，一个主节点可以有多个副本，也可以采用级联复制。</p>
<p><strong>全量与部分同步</strong></p>
<ol>
<li>副本通过 <code>PSYNC</code> 请求同步；首次复制或无法续传时进行全量同步。</li>
<li>主节点通常通过后台子进程生成 RDB，并记录此后发生的写入。</li>
<li>副本接收并加载快照，再应用后续命令，追上主节点。</li>
<li>短暂断连后，如果复制标识和 backlog 范围允许，可以只补齐缺失的数据；否则需要再次全量同步。</li>
</ol>
<p><img src="https://felix.muke.chat/images/posts/2026-11-01-redis-interview-questions/replication.webp" alt="Redis 全量与增量复制示意"></p>
<p>快照传输也可以采用无盘复制；副本在加载数据时是否继续提供服务，取决于复制模式和配置。</p>
<p><strong>需要关注的风险</strong></p>
<ul>
<li>副本读取可能滞后。</li>
<li>全量同步、fork 和快照加载会占用资源。</li>
<li>如果主节点关闭持久化并自动重启为空库，空数据可能被同步给副本。复制不能替代备份，应结合持久化与恢复方案设计。</li>
</ul>
<p><a href="https://redis.io/docs/latest/operate/oss_and_stack/management/replication/">复制机制官方说明</a></p>
<h3>8.6 Redis集群的主从复制模型是怎样的？</h3>
<p>每个主节点可以配置一个或多个副本。主节点失效时，符合条件的副本可在集群选举后接管其槽。</p>
<p>副本数量由部署方案决定，不是每个节点固定有 N−1 个副本。是否仍能服务还取决于主节点多数派、槽覆盖情况和配置，不能认为任意多数节点失联后都仍然可用。</p>
<h3>8.7 生产环境中的 redis 是怎么部署的？</h3>
<p>原稿给出的容量规划示例是 5 个主节点加 5 个副本，分布在 10 台机器上。假设每个主节点配置 10 GB 的 <code>maxmemory</code>，逻辑数据容量预算约为 50 GB；副本保存的是数据副本，不会把这份逻辑容量翻倍。</p>
<p>如果商品数据有 200 万条、每条约 10 KB，仅原始数据就约 20 GB，还要额外计算键、对象、索引、碎片、复制缓冲区和持久化的开销。</p>
<p>这是一份面试中的示例配置，不是本博客的实际生产环境，也不是通用标准。单实例内存上限与 QPS 应通过真实负载压测确定，没有统一的“不能超过 10 GB”或“每节点固定 5 万 QPS”的规则。</p>
<h3>8.8 说说Redis哈希槽的概念？</h3>
<p>Redis集群没有使用一致性hash，而是引入了哈希槽的概念，Redis集群有16384个哈希槽，每个key通过CRC16校验后对16384取模来决定放置哪个槽，集群的每个节点负责一部分hash槽。</p>
<h3>8.9 Redis集群会有写操作丢失吗？为什么？</h3>
<p>Redis Cluster 使用异步复制，在主节点故障且部分写入尚未复制等情况下，已经返回成功的写入仍可能丢失。</p>
<h3>8.10 Redis集群之间是如何复制的？</h3>
<p>异步复制</p>
<h3>8.11 Redis集群最大节点个数是多少？</h3>
<p>16,384 是哈希槽数量，不能直接当作推荐部署节点数。官方 Cluster 规范描述的扩展规模约为 1,000 个节点；实际规模仍需结合版本、集群通信开销和运维能力评估。<a href="https://redis.io/docs/latest/operate/oss_and_stack/reference/cluster-spec/">Cluster 规范</a></p>
<h3>8.12 Redis集群如何选择数据库？</h3>
<p>Redis集群目前无法做数据库选择，默认在0数据库。</p>
<h2>九、分区</h2>
<h3>9.1 Redis是单线程的，如何提高多核CPU的利用率？</h3>
<p>可以在同一个服务器部署多个Redis的实例，并把他们当作不同的服务器来使用，在某些时候，无论如何一个服务器是不够的， 所以，如果你想使用多个CPU，你可以考虑一下分片(shard)。</p>
<h3>9.2 为什么要做Redis分区？</h3>
<p>分区可以让数据分布在多台机器上，扩大可用内存，并让多个实例分别承担命令执行与网络流量。</p>
<p>计算和带宽是否接近线性增长，取决于分片是否均匀、热点是否集中，以及请求中是否存在跨分片协调；增加机器不会自动解决热点键。</p>
<h3>9.3 你知道有哪些Redis分区实现方案？</h3>
<ul>
<li>
<p>客户端分区就是在客户端就已经决定数据会被存储到哪个redis节点或者从哪个redis节点读取。大多数客户端已经实现了客户端分区。</p>
</li>
<li>
<p>代理分区 意味着客户端将请求发送给代理，然后代理决定去哪个节点写数据或者读数据。代理根据分区规则决定请求哪些Redis实例，然后根据Redis的响应结果返回给客户端。redis和memcached的一种代理实现就是Twemproxy</p>
</li>
<li>
<p>查询路由(Query routing) 的意思是客户端随机地请求任意一个redis实例，然后由Redis将请求转发给正确的Redis节点。Redis Cluster实现了一种混合形式的查询路由，但并不是直接将请求从一个redis节点转发到另一个redis节点，而是在客户端的帮助下直接redirected到正确的redis节点。</p>
</li>
</ul>
<h3>9.4 Redis分区有什么缺点？</h3>
<ul>
<li>跨分片的多键操作受到限制；Redis Cluster 中的多键事务通常需要键处于同一槽。</li>
<li>分片粒度通常是键，单个超大 Hash、Set 或 Sorted Set 不会自动拆到多个分片。</li>
<li>备份和恢复需要覆盖多个实例，并考虑时间点是否一致。</li>
<li>增删节点需要数据再平衡；Cluster 提供槽迁移机制，客户端或代理分片则取决于具体方案。</li>
<li>热点键和分片倾斜可能使某个节点成为瓶颈。</li>
</ul>
<h2>十、分布式问题</h2>
<h3>10.1 Redis实现分布式锁</h3>
<p><code>SETNX</code> 的含义是“键不存在才设置”。设置成功返回 1，键已存在返回 0。它可以演示竞争同一个键的行为。</p>
<p><img src="https://felix.muke.chat/images/posts/2026-11-01-redis-interview-questions/setnx-example.webp" alt="SETNX 命令成功与失败的返回值"></p>
<p>真正实现带租约的锁时，应将“条件写入”和“设置过期时间”合并为一个命令，避免 <code>SETNX</code> 成功后进程异常、还没来得及设置过期时间。</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-redis">SET lock:order:123 unique-request-token NX PX 30000
</code></pre>
<p>这里的值必须是<strong>本次持锁者独有的标识</strong>，示例中的 <code>unique-request-token</code> 不能被所有请求复用。释放锁时，也必须先比较标识再删除，且比较与删除要原子执行。</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-lua"><span class="line"><span style="color:#FF7B72">if</span><span style="color:#E6EDF3"> redis.</span><span style="color:#79C0FF">call</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">"GET"</span><span style="color:#E6EDF3">, KEYS[</span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">]) </span><span style="color:#FF7B72">==</span><span style="color:#E6EDF3"> ARGV[</span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">] </span><span style="color:#FF7B72">then</span></span>
<span class="line"><span style="color:#FF7B72">    return</span><span style="color:#E6EDF3"> redis.</span><span style="color:#79C0FF">call</span><span style="color:#E6EDF3">(</span><span style="color:#A5D6FF">"DEL"</span><span style="color:#E6EDF3">, KEYS[</span><span style="color:#79C0FF">1</span><span style="color:#E6EDF3">])</span></span>
<span class="line"><span style="color:#FF7B72">end</span></span>
<span class="line"><span style="color:#FF7B72">return</span><span style="color:#79C0FF"> 0</span></span>
</code></pre>
<p>调用时传入锁键和本次 token。不能直接 <code>DEL</code>，否则任务超时后可能删除另一请求后来取得的锁。租约到期后旧持有者仍可能继续运行，涉及关键写入时还要考虑 fencing token、幂等和底层资源的校验。幂等键与执行收据的具体处理，见<a href="https://felix.muke.chat/notes/tool-call-idempotency">《如何避免工具调用重复执行》</a>。<a href="https://redis.io/docs/latest/develop/clients/patterns/distributed-locks/">分布式锁官方说明</a></p>
<h3>10.2 如何解决 Redis 的并发竞争 Key 问题</h3>
<p>所谓 Redis 的并发竞争 Key 的问题也就是多个系统同时对一个 key 进行操作，但是最后执行的顺序和我们期望的顺序不同，这样也就导致了结果的不同!</p>
<p>推荐一种方案:分布式锁(zookeeper 和 redis 都可以实现分布式锁)。(如果不存在 Redis 的并发竞争 Key 问题，不要使用分布式锁，这样会影响性能)</p>
<p>基于zookeeper临时有序节点可以实现的分布式锁。大致思想为:每个客户端对某个方法加锁时，在zookeeper上的与该方法对应的指定节点的目录下，生成一个唯一的瞬时有序节点。 判断是否获取锁的方式很简单，只需要判断有序节点中序号最小的一个。 当释放锁的时候，只需将这个瞬时节点删除即可。同时，其可以避免服务宕机导致的锁无法释放，而产生的死锁问题。完成业务流程后，删除对应的子节点释放锁。</p>
<h3>10.3 分布式Redis是前期做还是后期规模上来了再做好？为什么？</h3>
<p>按当前规模和可预见的增长选择部署方式，不必为了未来可能扩容，一开始就在一台机器上启动几十个实例。</p>
<p>可以先明确容量、QPS、可用性和恢复目标：需要自动故障转移时考虑主从加 Sentinel；单机容量或吞吐不足时，再评估 Cluster 和分片。设计键名时提前考虑多键操作及 hash tag，可以降低后续迁移成本。</p>
<h3>10.4 什么是 RedLock</h3>
<p>Redlock 是 Redis 官方文档介绍的分布式锁算法：客户端在多个相互独立的 Redis 实例上尝试获取同一资源的锁，只有在有效期内取得多数实例的锁，才视为成功。</p>
<p>其目标是互斥访问、避免永久死锁，以及在部分节点故障时仍可获取和释放锁。但这些保证依赖时钟漂移、请求耗时和租约有效期等假设。</p>
<p>它不等同于“给一个有副本的 Redis 写入锁”，也不意味着网络分区下无条件安全。需要正确性保证的资源写入，还应结合 fencing token 等机制设计。<a href="https://redis.io/docs/latest/develop/clients/patterns/distributed-locks/">算法与适用前提</a></p>
<h2>十一、缓存异常</h2>
<h3>11.1 缓存雪崩</h3>
<p>缓存雪崩是指缓存同一时间大面积的失效，所以，后面的请求都会落到数据库上，造成数据库短时间内承受大量请求而崩掉。</p>
<p><strong>解决方案</strong></p>
<ol>
<li>
<p>缓存数据的过期时间设置随机，防止同一时间大量数据过期现象发生。</p>
</li>
<li>
<p>一般并发量不是特别多的时候，使用最多的解决方案是加锁排队。</p>
</li>
<li>
<p>给每一个缓存数据增加相应的缓存标记，记录缓存的是否失效，如果缓存标记失效，则更新数据缓存。</p>
</li>
</ol>
<h3>11.2 缓存穿透</h3>
<p>缓存穿透是指请求的数据在缓存和数据库中都不存在，导致请求持续穿过缓存访问数据库。</p>
<p><strong>解决方案</strong></p>
<ol>
<li>在接口层做身份、权限和参数校验，尽早拦截明显无效的请求。</li>
<li>对确实不存在的数据缓存短期空结果，并明确区分“缓存空值”和“未命中”；新增数据时考虑失效处理。</li>
<li>用布隆过滤器预先判断数据是否可能存在，减少无意义的回源。</li>
</ol>
<p><strong>Bitmap 与布隆过滤器</strong></p>
<p>Bitmap 用位表示状态，不等同于哈希表。布隆过滤器使用多个哈希函数将元素映射到位数组：只要某个对应位为 0，就能判定元素不存在；如果所有位都为 1，只能说<strong>可能存在</strong>，还需要查询真实数据。</p>
<p>布隆过滤器节省空间、查询快，但存在误判；标准形式也不支持直接删除元素。过滤器需要跟随数据新增及时维护，否则业务中的陈旧过滤器可能挡住新数据。<a href="https://redis.io/docs/latest/develop/data-types/probabilistic/bloom-filter/">布隆过滤器说明</a></p>
<h3>11.3 缓存击穿</h3>
<p>缓存击穿通常是某个热点键过期，大量并发请求同时未命中，继而集中访问数据库。</p>
<p>它与雪崩的区别在于：击穿集中在单个热点，雪崩涉及大量键或整个缓存服务失效。</p>
<p>可以对同一键的重建做互斥或请求合并，让一个请求加载数据，其余请求等待后重新读取缓存；也可以用逻辑过期加后台刷新，在业务允许时返回旧数据。即使热点键不设置物理 TTL，也要设计更新和失效机制。</p>
<h3>11.4 缓存预热</h3>
<p>缓存预热就是系统上线后，将相关的缓存数据直接加载到缓存系统。这样就可以避免在用户请求的时候，先查询数据库，然后再将数据缓存的问题!用户直接查询事先被预热的缓存数据!</p>
<p><strong>解决方案</strong></p>
<ol>
<li>
<p>直接写个缓存刷新页面，上线时手工操作一下；</p>
</li>
<li>
<p>数据量不大，可以在项目启动的时候自动进行加载；</p>
</li>
<li>
<p>定时刷新缓存；</p>
</li>
</ol>
<h3>11.5 缓存降级</h3>
<p>当访问量剧增、服务出现问题(如响应时间慢或不响应)或非核心服务影响到核心流程的性能时，仍然需要保证服务还是可用的，即使是有损服务。系统可以根据一些关键数据进行自动降级，也可以配置开关实现人工降级。</p>
<p>缓存降级的最终目的是保证核心服务可用，即使是有损的。而且有些服务是无法降级的(如加入购物车、结算)。</p>
<p>在进行降级之前要对系统进行梳理，看看系统是不是可以丢卒保帅；从而梳理出哪些必须誓死保护，哪些可降级；比如可以参考日志级别设置预案:</p>
<ol>
<li>
<p>一般:比如有些服务偶尔因为网络抖动或者服务正在上线而超时，可以自动降级；</p>
</li>
<li>
<p>警告:有些服务在一段时间内成功率有波动(如在95~100%之间)，可以自动降级或人工降级，并发送告警；</p>
</li>
<li>
<p>错误:比如可用率低于90%，或者数据库连接池被打爆了，或者访问量突然猛增到系统能承受的最大阀值，此时可以根据情况自动降级或者人工降级；</p>
</li>
<li>
<p>严重错误:比如因为特殊原因数据错误了，此时需要紧急人工降级。</p>
</li>
</ol>
<p>服务降级的目的，是为了防止Redis服务故障，导致数据库跟着一起发生雪崩问题。因此，对于不重要的缓存数据，可以采取服务降级策略，例如一个比较常见的做法就是，Redis出现问题，不去数据库查询，而是直接返回默认值给用户。</p>
<h3>11.6 热点数据和冷数据</h3>
<p><strong>热点数据，缓存才有价值</strong></p>
<p>对于冷数据而言，大部分数据可能还没有再次访问到就已经被挤出内存，不仅占用内存，而且价值不大。频繁修改的数据，看情况考虑使用缓存</p>
<p>对于热点数据，比如我们的某IM产品，生日祝福模块，当天的寿星列表，缓存以后可能读取数十万次。再举个例子，某导航产品，我们将导航信息，缓存以后可能读取数百万次。</p>
<p>缓存是否值得使用，应比较读写比例、回源成本、命中率及更新开销；不能只凭一个固定读取次数决定。</p>
<p>那存不存在，修改频率很高，但是又不得不考虑缓存的场景呢？有!比如，这个读取接口对数据库的压力很大，但是又是热点数据，这个时候就需要考虑通过缓存手段，减少数据库的压力，比如我们的某助手产品的，点赞数，收藏数，分享数等是非常典型的热点数据，但是又不断变化，此时就需要将数据同步保存到Redis缓存，减少数据库压力。</p>
<h3>11.7 缓存热点key</h3>
<p>热点键失效时，重建请求应有序、受控。</p>
<p>一种流程是：先读缓存，未命中后尝试获取重建锁；获取成功后<strong>再次检查缓存</strong>，仍未命中才查询数据库并回填。未取得锁的请求短暂等待、退避后重读缓存，或按业务返回旧值。</p>
<p>不能让等待锁的请求在超时后全部直接回源，否则仍可能压垮数据库。还应限制等待时间、数据库并发和重试次数。</p>
<h2>十二、常用工具</h2>
<h3>12.1 Redis 的 Python 客户端怎么使用？</h3>
<p>Python 常用 <code>redis-py</code>。下面保留单机、Sentinel 和 Cluster 三种连接场景，按当前接口组织示例；地址与主节点名称需按实际环境修改。Cluster 支持已集成到 <code>redis-py</code>，不再使用原稿中的独立 <code>redis-py-cluster</code> 包。</p>
<h4>单机连接</h4>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#8B949E"># pip install redis</span></span>
<span class="line"><span style="color:#FF7B72">from</span><span style="color:#E6EDF3"> redis </span><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> Redis</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">with</span><span style="color:#E6EDF3"> Redis(</span><span style="color:#FFA657">host</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"127.0.0.1"</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">port</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">6379</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">decode_responses</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">as</span><span style="color:#E6EDF3"> conn:</span></span>
<span class="line"><span style="color:#E6EDF3">    conn.set(</span><span style="color:#A5D6FF">"name"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"zs"</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#79C0FF">    print</span><span style="color:#E6EDF3">(conn.get(</span><span style="color:#A5D6FF">"name"</span><span style="color:#E6EDF3">))</span></span>
</code></pre>
<h4>Sentinel 发现主从节点</h4>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#FF7B72">from</span><span style="color:#E6EDF3"> redis.sentinel </span><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> Sentinel</span></span>
<span class="line"></span>
<span class="line"><span style="color:#E6EDF3">sentinel </span><span style="color:#FF7B72">=</span><span style="color:#E6EDF3"> Sentinel(</span></span>
<span class="line"><span style="color:#E6EDF3">    [</span></span>
<span class="line"><span style="color:#E6EDF3">        (</span><span style="color:#A5D6FF">"127.0.0.1"</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">26379</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">        (</span><span style="color:#A5D6FF">"127.0.0.1"</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">26380</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">        (</span><span style="color:#A5D6FF">"127.0.0.1"</span><span style="color:#E6EDF3">, </span><span style="color:#79C0FF">26381</span><span style="color:#E6EDF3">),</span></span>
<span class="line"><span style="color:#E6EDF3">    ],</span></span>
<span class="line"><span style="color:#FFA657">    socket_timeout</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">0.5</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#79C0FF">print</span><span style="color:#E6EDF3">(sentinel.discover_master(</span><span style="color:#A5D6FF">"mymaster"</span><span style="color:#E6EDF3">))</span></span>
<span class="line"><span style="color:#79C0FF">print</span><span style="color:#E6EDF3">(sentinel.discover_slaves(</span><span style="color:#A5D6FF">"mymaster"</span><span style="color:#E6EDF3">))</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">with</span><span style="color:#E6EDF3"> sentinel.master_for(</span><span style="color:#A5D6FF">"mymaster"</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">decode_responses</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">as</span><span style="color:#E6EDF3"> master:</span></span>
<span class="line"><span style="color:#E6EDF3">    master.set(</span><span style="color:#A5D6FF">"foo"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"bar"</span><span style="color:#E6EDF3">)</span></span>
<span class="line"></span>
<span class="line"><span style="color:#8B949E"># 副本读取可能因复制延迟而暂时返回旧值。</span></span>
<span class="line"><span style="color:#FF7B72">with</span><span style="color:#E6EDF3"> sentinel.slave_for(</span><span style="color:#A5D6FF">"mymaster"</span><span style="color:#E6EDF3">, </span><span style="color:#FFA657">decode_responses</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">as</span><span style="color:#E6EDF3"> replica:</span></span>
<span class="line"><span style="color:#79C0FF">    print</span><span style="color:#E6EDF3">(replica.get(</span><span style="color:#A5D6FF">"foo"</span><span style="color:#E6EDF3">))</span></span>
</code></pre>
<h4>Redis Cluster</h4>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-python"><span class="line"><span style="color:#FF7B72">from</span><span style="color:#E6EDF3"> redis.cluster </span><span style="color:#FF7B72">import</span><span style="color:#E6EDF3"> RedisCluster</span></span>
<span class="line"></span>
<span class="line"><span style="color:#FF7B72">with</span><span style="color:#E6EDF3"> RedisCluster(</span></span>
<span class="line"><span style="color:#FFA657">    host</span><span style="color:#FF7B72">=</span><span style="color:#A5D6FF">"127.0.0.1"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    port</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">7000</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#FFA657">    decode_responses</span><span style="color:#FF7B72">=</span><span style="color:#79C0FF">True</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#E6EDF3">) </span><span style="color:#FF7B72">as</span><span style="color:#E6EDF3"> cluster:</span></span>
<span class="line"><span style="color:#E6EDF3">    cluster.set(</span><span style="color:#A5D6FF">"foo"</span><span style="color:#E6EDF3">, </span><span style="color:#A5D6FF">"bar"</span><span style="color:#E6EDF3">)</span></span>
<span class="line"><span style="color:#79C0FF">    print</span><span style="color:#E6EDF3">(cluster.get(</span><span style="color:#A5D6FF">"foo"</span><span style="color:#E6EDF3">))</span></span>
</code></pre>
<p>这些示例需要相应的 Redis 服务和拓扑才能运行。<a href="https://redis.io/docs/latest/develop/clients/redis-py/connect/">redis-py 连接说明</a></p>
<h2>十三、其他问题</h2>
<h3>13.1 Redis与Memcached的区别</h3>
<p>两者都可以用于内存键值缓存。Redis 提供更丰富的数据结构和持久化能力，Memcached 更侧重简单缓存；选型应结合数据模型和运维需求。</p>
<table>
<thead>
<tr>
<th>对比项</th>
<th>Redis</th>
<th>Memcached</th>
</tr>
</thead>
<tbody>
<tr>
<td>定位</td>
<td>内存数据存储，可用作缓存</td>
<td>内存键值缓存</td>
</tr>
<tr>
<td>数据结构</td>
<td>String、List、Set、Hash、Sorted Set 等</td>
<td>值通常作为不透明的字符串或二进制数据存储</td>
</tr>
<tr>
<td>操作</td>
<td>通用读写、各类型操作、事务与 Lua 脚本</td>
<td>键值读写、自增等缓存操作</td>
</tr>
<tr>
<td>持久化</td>
<td>RDB、AOF</td>
<td>通常不提供持久化</td>
</tr>
<tr>
<td>高可用与分片</td>
<td>主从复制、Sentinel、Redis Cluster</td>
<td>通常由客户端或代理完成分片</td>
</tr>
<tr>
<td>适用场景</td>
<td>复杂数据结构、持久化、消息与高可用需求</td>
<td>简单键值缓存</td>
</tr>
</tbody>
</table>
<p>两者性能应在相同硬件、数据和访问模型下测试，不能笼统判断谁一定更快。</p>
<h3>13.2 如何保证缓存与数据库双写时的数据一致性？</h3>
<p>缓存与数据库是两个存储系统，一次业务更新无法因为调用顺序正确，就自动获得跨系统事务。</p>
<p>常见的 Cache Aside 流程是：读取先查缓存，未命中再查数据库并回填；更新先提交数据库，再删除相关缓存。删除失败时需要可靠重试，并设置合理 TTL 作为兜底。</p>
<p>并发下仍可能出现旧查询晚回填、消息乱序或补偿失败。需要更强保证时，应结合版本号、可靠消息或变更日志设计；单个进程中的内存队列不能保证整个分布式系统的强一致性。</p>
<table>
<thead>
<tr>
<th>问题场景</th>
<th>可能出现的情况</th>
<th>处理思路</th>
</tr>
</thead>
<tbody>
<tr>
<td>先更新缓存，再写数据库</td>
<td>数据库写入失败，缓存包含未成功落库的数据</td>
<td>避免采用此顺序；先提交数据库，再使旧缓存失效</td>
</tr>
<tr>
<td>先写数据库，再更新缓存</td>
<td>缓存写入失败，或并发写入使旧值覆盖新值</td>
<td>通常改为提交数据库后删除缓存，并为删除失败安排重试</td>
</tr>
<tr>
<td>异步刷新缓存</td>
<td>数据库更新与缓存更新存在时间窗口</td>
<td>明确可接受延迟，通过可靠消息或变更日志重试与补偿</td>
</tr>
</tbody>
</table>
<p>若业务必须在每次读取时取得强一致结果，应重新评估是否让这类读取经过缓存。</p>
<h3>13.3 Redis常见性能问题和解决方案？</h3>
<ol>
<li>避免在主线程执行超大集合遍历、<code>KEYS</code> 等耗时操作，关注慢日志和命令延迟。</li>
<li>控制大键、单实例容量及内存碎片，预留复制缓冲和 fork 写时复制的空间。</li>
<li>为 RDB 快照和 AOF 重写评估 CPU、磁盘、内存与延迟开销；不要为了性能一律关闭主节点持久化。</li>
<li>监控复制延迟、全量同步和连接稳定性；不要在高峰期无规划地增加副本。</li>
<li>级联复制可以减轻主节点扇出，但会增加同步链路和延迟，不是所有场景都应改成单向长链。</li>
<li>结合业务压测决定部署拓扑，并演练故障转移与数据恢复。</li>
</ol>
<h3>13.4 Redis官方为什么不提供Windows版本？</h3>
<p>旧资料中“Windows 版本只到 3.x”的说法已经不适合直接沿用。Windows 上可以通过 WSL2 运行 Linux 版 Redis，官方安装文档也介绍了其 Windows 兼容伙伴 Memurai。</p>
<p>选择安装方式时应查当前官方支持范围，不要继续依赖早期停止维护的 Windows 移植包。<a href="https://redis.io/docs/latest/operate/oss_and_stack/install/archive/install-redis/install-redis-on-windows/">Windows 安装说明</a></p>
<h3>13.5 一个字符串类型的值能存储最大容量是多少？</h3>
<p>默认上限是 512 MB。实际使用仍应避免大值，因为传输、序列化和删除都可能带来明显开销。<a href="https://redis.io/docs/latest/develop/data-types/strings/">String 类型限制</a></p>
<h3>13.6 Redis如何做大量数据插入？</h3>
<p>Redis2.6开始redis-cli支持一种新的被称之为pipe mode的新模式用于执行大量数据插入工作。</p>
<h3>13.7 假如Redis里面有1亿个key，其中有10w个key是以某个固定的已知的前缀开头的，如果将它们全部找出来？</h3>
<p><code>KEYS prefix:*</code> 会一次遍历键空间，大数据量下可能长时间占用主线程，不适合直接在繁忙的线上实例中使用。</p>
<p>通常使用 <code>SCAN</code> 逐批迭代，持续传入上一次返回的游标，直到返回游标 0。</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-redis">SCAN 0 MATCH prefix:* COUNT 1000
</code></pre>
<p><code>COUNT</code> 是每次迭代工作量的提示，不是精确返回条数。<code>SCAN</code> 可能返回重复项，也可能在某批返回空列表但游标尚未归零；应用应去重，并考虑扫描期间键空间变化。它把遍历拆成多次短操作，不代表完全没有阻塞开销。Cluster 场景还要覆盖相关节点。<a href="https://redis.io/docs/latest/commands/scan/">SCAN 命令说明</a></p>
<h3>13.8 使用Redis做过异步队列吗，是如何实现的</h3>
<p>使用list类型保存数据信息，rpush生产消息，lpop消费消息，当lpop没有消息时，可以sleep一段时间，然后再检查有没有信息，如果不想sleep的话，可以使用blpop, 在没有信息的时候，会一直阻塞，直到信息的到来。redis可以通过pub/sub主题订阅模式实现一个生产者，多个消费者，当然也存在一定的缺点，当消费者下线时，生产的消息会丢失。</p>
<h3>13.9 Redis如何实现延时队列</h3>
<p>可以用 Sorted Set 保存待处理消息，以到期时间戳作为 score，以唯一消息 ID 作为 member，消息内容另行存储。</p>
<p>消费者按当前时间查询到期成员，再领取并处理任务。并发消费时，领取和移除需要原子协调；先查后删可能让多个消费者重复执行同一任务。</p>
<p>任务可靠性还需要考虑处理失败后的重试、消费者宕机和幂等。仅用一个 Sorted Set 做轮询，不会自动获得可靠消息队列的全部语义。</p>
<h3>13.10 Redis 的内存回收如何工作？</h3>
<p>Redis 在处理命令时检查内存压力，超过 <code>maxmemory</code> 后按配置的策略尝试淘汰键。如果没有足够候选数据，则可能拒绝需要新增空间的写入。这里描述的是淘汰流程，不是一个独立的“回收进程”。</p>
<p>单条命令或临时缓冲可能使实际用量短暂超过配置值；<code>maxmemory</code> 也不等于整个进程的 RSS 硬上限，因此仍要为其他开销预留内存。</p>
<h3>13.11 Redis回收使用的是什么算法？</h3>
<p>取决于配置的 <code>maxmemory-policy</code>，不只有 LRU。常见选择包括近似 LRU、近似 LFU、随机淘汰、按剩余 TTL 淘汰，以及 <code>noeviction</code>。具体候选范围与行为见第五节。</p>
]]></content:encoded>
    </item>
    <item>
      <title>如何避免工具调用重复执行</title>
      <link>https://felix.muke.chat/notes/tool-call-idempotency</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/tool-call-idempotency</guid>
      <pubDate>Sun, 01 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>从发送消息后发生超时的场景出发，理解业务幂等键、持久化执行记录、并发控制，以及结果未知时怎样恢复。</description>
      <category>AI Agent</category>
      <category>Agent</category>
      <category>幂等</category>
      <category>故障恢复</category>
      <content:encoded><![CDATA[<p>Agent 调用工具发送了一条消息，随后请求超时。它判断发送失败，又调用了一次，结果对方收到了两条相同的消息。</p>
<p>问题在于：远端可能已经完成发送，只是在返回响应时发生了网络故障。程序看到的“超时”，不足以证明操作没有发生。</p>
<p><strong>避免重复执行，需要让程序识别同一次业务操作、持久化执行状态，并在重试前判断已经发生了什么。</strong></p>
<h2>重复调用可能来自哪些地方</h2>
<p>即使只运行一个 Agent，也可能出现重复操作：</p>
<table>
<thead>
<tr>
<th>来源</th>
<th>典型情况</th>
</tr>
</thead>
<tbody>
<tr>
<td>模型再次调用</td>
<td>没看到明确结果，重新提出相同操作</td>
</tr>
<tr>
<td>网络重试</td>
<td>请求超时后，客户端重新提交</td>
</tr>
<tr>
<td>消息或任务重放</td>
<td>队列重新投递，程序重启后再次处理</td>
</tr>
<tr>
<td>并发执行</td>
<td>两个 Worker 同时处理同一事件</td>
</tr>
<tr>
<td>中断恢复</td>
<td>远端已成功，本地成功状态尚未保存就退出</td>
</tr>
</tbody>
</table>
<p>提示词可以要求模型避免重复，但它覆盖不了队列重放、程序崩溃和并发竞争。程序需要在实际产生副作用的边界检查是否允许执行。</p>
<p>首先区分只读工具和写入工具。搜索文档、读取文件的重复调用主要增加成本；发送消息、创建任务、提交表单等操作则可能改变外部状态。</p>
<h2>给业务操作一个稳定的标识</h2>
<p>在<a href="https://felix.muke.chat/notes/agent-tool-calling">《Agent 是如何调用工具的》</a>介绍的调用链中，模型返回的 <code>tool_call_id</code> 用于关联调用请求与结果。模型重新生成一次调用时，这个 ID 可能变化，因此不能单独依靠它识别业务重复。</p>
<p>例如，同一条用户消息触发一次自动回复，可以由应用生成稳定的业务幂等键：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">workspace:42:auto-reply:v1:event:msg_123
</code></pre>
<p>它表示某个工作空间里，对事件 <code>msg_123</code> 执行的这一次自动回复。网络重试、任务重放和进程重启后，仍然使用同一个键。</p>
<p>如果用户明确要求再发送一条消息，应创建新的业务操作标识。仅凭“工具名称和参数完全相同”去重，会误伤这种合法需求：相同参数也可能代表两次不同意图。<a href="https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/">用请求标识表达幂等意图</a></p>
<p>操作标识应由应用在执行前分配并保存，重试时复用。记录中还应绑定确定后的目标和参数，必要时保存规范化参数的摘要。</p>
<p>如果相同的键对应了不同参数，应报冲突，避免把一次修改后的操作误认作先前操作的重试。</p>
<h2>执行前，先持久化状态</h2>
<p>程序可以为每个业务操作维护一份执行记录。下面是一条简化的示例：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "operation_key"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"workspace:42:auto-reply:v1:event:msg_123"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "tool"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"send_message"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "arguments"</span><span style="color:#E6EDF3">: {</span></span>
<span class="line"><span style="color:#7EE787">    "recipient"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"conversation_456"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">    "text"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"报告已经生成"</span></span>
<span class="line"><span style="color:#E6EDF3">  },</span></span>
<span class="line"><span style="color:#7EE787">  "status"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"pending"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "result"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">null</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>执行状态需要区分：</p>
<table>
<thead>
<tr>
<th>状态</th>
<th>含义</th>
<th>再次遇到同一操作时</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>pending</code></td>
<td>已占用执行权，尚无最终结果</td>
<td>查询进度或等待，阻止并发重复提交</td>
</tr>
<tr>
<td><code>succeeded</code></td>
<td>已确认成功，并保存结果</td>
<td>返回已有结果</td>
</tr>
<tr>
<td><code>failed_safe</code></td>
<td>有明确依据证明未产生副作用</td>
<td>按错误类型和策略决定是否重试</td>
</tr>
<tr>
<td><code>uncertain</code></td>
<td>是否产生副作用尚未确认</td>
<td>先核对远端状态</td>
</tr>
</tbody>
</table>
<p>程序意外退出后，留下的 <code>pending</code> 也需要按未知结果处理，不能因为等待时间长就直接重新提交。</p>
<p>记录必须在外部写入前持久化。保存失败时，应停止执行，否则操作可能发生，却没有记录可供重试判断。</p>
<h2>并发控制要覆盖真正的执行范围</h2>
<p>下面这种检查存在竞争条件：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">Worker A：没有找到执行记录
Worker B：没有找到执行记录
Worker A：发送消息
Worker B：发送消息
</code></pre>
<p>“查询记录”和“取得执行权”需要通过原子操作衔接。例如，在共享数据库中为业务键建立唯一约束，只有成功创建 <code>pending</code> 记录的执行者可以提交请求。</p>
<p>重复请求则读取已有记录，根据状态返回结果或等待。</p>
<p>进程内互斥锁可以控制同一进程中的并发，但多进程、多实例需要共享的协调机制。即使使用锁，也需要持久化记录支持重启恢复。</p>
<p>取得执行权后，流程可以组织为：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-text">原子创建 pending 记录
          ↓
调用外部写入工具
          ↓
收到成功结果，保存 succeeded 和远端收据
          ↓
向模型返回结果，确认任务已处理
</code></pre>
<p>如果程序在“远端成功”和“本地保存成功”之间崩溃，仍然会留下不确定窗口。本地数据库事务无法单独保证远端操作与本地记录同时成功。</p>
<h2>超时后，先判断结果是否已知</h2>
<p>可以明确证明没有发出请求，或者服务按接口约定明确拒绝执行时，才有依据把它归为可安全重试的失败。</p>
<p>连接中断、响应丢失或执行中的进程被取消，通常需要保留未知状态。即使收到服务错误，也应根据接口契约判断是否可能已产生部分副作用，不能只看状态码就认定可以重发。</p>
<p>恢复时，优先考虑三种方式：</p>
<ol>
<li><strong>远端支持幂等键</strong>：使用同一个键和相同参数重试，由远端识别重复操作并返回已有结果。</li>
<li><strong>远端支持按业务标识查询</strong>：核对操作是否完成，找到对应记录后补齐本地收据。</li>
<li><strong>无法确认远端结果</strong>：保留未知状态，交由业务核对流程处理。</li>
</ol>
<p>查询暂时没有找到结果，也不一定证明操作未发生，还需要考虑接口的一致性和可见性约定。</p>
<p>幂等记录的保留时间也应覆盖可能发生的重试和重放。如果过早删除记录，迟到的同一请求仍可能被当作新操作。<a href="https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/">迟到请求与幂等处理</a></p>
<h2>让 Agent 读取已有结果，避免重新执行</h2>
<p>同一业务键已经成功时，工具层应返回保存的结果和收据。例如：</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-json"><span class="line"><span style="color:#E6EDF3">{</span></span>
<span class="line"><span style="color:#7EE787">  "status"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"succeeded"</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "reused"</span><span style="color:#E6EDF3">: </span><span style="color:#79C0FF">true</span><span style="color:#E6EDF3">,</span></span>
<span class="line"><span style="color:#7EE787">  "result"</span><span style="color:#E6EDF3">: {</span></span>
<span class="line"><span style="color:#7EE787">    "message_id"</span><span style="color:#E6EDF3">: </span><span style="color:#A5D6FF">"remote_789"</span></span>
<span class="line"><span style="color:#E6EDF3">  }</span></span>
<span class="line"><span style="color:#E6EDF3">}</span></span>
</code></pre>
<p>这样，模型能知道操作已完成，并继续处理后续任务。</p>
<p>如果状态未知，则返回明确的未知状态和可用的核对方式。不能把未知包装成普通失败，再让模型为了“完成任务”反复调用发送工具。</p>
<p>消息消费进度与发送收据也应分别保存：前者回答事件是否处理过，后者回答外部写入是否确认成功。消费记录无法替代发送证据。</p>
<p>这套方法能够识别重复请求、复用已完成结果，并把不确定操作留给恢复流程。最终能否避免外部副作用重复，还取决于远端是否支持幂等或可靠核对；只有本地去重记录，不能承诺跨系统严格执行一次。</p>
]]></content:encoded>
    </item>
    <item>
      <title>windows 专业版激活</title>
      <link>https://felix.muke.chat/notes/windows-%E4%B8%93%E4%B8%9A%E7%89%88%E6%BF%80%E6%B4%BB</link>
      <guid isPermaLink="true">https://felix.muke.chat/notes/windows-%E4%B8%93%E4%B8%9A%E7%89%88%E6%BF%80%E6%B4%BB</guid>
      <pubDate>Sun, 01 Nov 2026 00:00:00 GMT</pubDate>
      <dc:creator>Yang</dc:creator>
      <description>Windows11专业版KMS命令激活（不需要激活工具） Windows11专业版KMS命令激活/Win11专业版KMS激活（不需要激活工具，无病毒、无恶意软件、无后门风险）/附Windows11 ISO微软官方下载地址 Windows11专业版KMS激活密钥： 产品密钥来自微软官方，详见：https://learn.microsoft.com/zh-cn/...</description>
      <category>操作系统</category>
      <category>Windows</category>
      <category>Windows 11</category>
      <category>KMS</category>
      <category>系统激活</category>
      <content:encoded><![CDATA[<h2>Windows11专业版KMS命令激活（不需要激活工具）</h2>
<p>Windows11专业版KMS命令激活/Win11专业版KMS激活（不需要激活工具，无病毒、无恶意软件、无后门风险）/附Windows11 ISO微软官方下载地址</p>
<p>Windows11专业版KMS激活密钥：</p>
<p>产品密钥来自微软官方，详见：<a href="https://link.orcy.net.cn/?url=https://learn.microsoft.com/zh-cn/windows-server/get-started/kms-client-activation-keys">https://learn.microsoft.com/zh-cn/windows-server/get-started/kms-client-activation-keys</a></p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-shell"><span class="line"><span style="color:#FFA657">W269N-WFGWX-YVC9B-4J6C9-T83GX</span></span>
</code></pre>
<p>推荐KMS激活服务器</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-shell"><span class="line"><span style="color:#FFA657">kms.0t.net.cn</span></span>
</code></pre>
<p>注意：家庭版系统请先升级或转换到专业版，再用此序列号激活，否则会报错。</p>
<p>激活常见报错处理，请参考<a href="https://www.orcy.net.cn/4038.html">《Windows系统 KMS激活常见问题》</a></p>
<p><strong>一、系统激活</strong></p>
<p>激活方式如下：</p>
<p><img src="https://myoss.orcy.net.cn:9000/oss-gd-note-img/202408062025684.png" alt="Windows11专业版KMS命令激活（不需要激活工具）-下一朵云"></p>
<p>右击<code>开始图标</code>，打开<code>Windows终端(管理员)</code>，输入以下命令</p>
<pre style="background:#0d1117;color:#e6edf3;padding:16px;overflow-x:auto;border-radius:6px;font-size:13px;line-height:1.6"><code class="language-basic">slmgr -ipk W269N-WFGWX-YVC9B-4J6C9-T83GX

slmgr -skms kms.0t.net.cn

slmgr -ato
</code></pre>
<p>如下图，已激活！</p>
<p><img src="https://myoss.orcy.net.cn:9000/oss-orcy-img/20211006160151.png" alt="Windows11专业版KMS命令激活（不需要激活工具）-下一朵云">图1 KMS激活成功</p>
<p><strong>二、系统下载</strong></p>
<p>微软官方地址：</p>
<p><a href="https://link.orcy.net.cn/?url=https://www.microsoft.com/zh-cn/software-download/windows11">https://www.microsoft.com/zh-cn/software-download/windows11</a></p>
<p><img src="https://myoss.orcy.net.cn:9000/oss-gd-note-img/202403271052189.png" alt="Windows11专业版KMS命令激活（不需要激活工具）-下一朵云">图2 下载Windows 11 ISO</p>
<p><strong>其他内容：</strong></p>
<p>Windows 11 LTSC 长期支持版（win11 LTSC 24H2）</p>
<ul>
<li><a href="https://www.orcy.net.cn/3930.html">Windows 11 LTSC KMS激活（不需要激活工具）</a></li>
</ul>
<p>Windows Server 2025</p>
<ul>
<li>[Windows Server 2025 KMS激活 <a href="https://www.orcy.net.cn/3899.html">无需激活工具]</a></li>
</ul>
<p><strong>其他版本激活（企业版）：</strong></p>
<p>其他版本激活，可以在此网站查询激活命令：<a href="https://help.kms.0t.net.cn/">https://help.kms.0t.net.cn/</a></p>
<p><img src="https://myoss.orcy.net.cn:9000/oss-gd-note-img/202502261113888.png" alt="Windows11专业版KMS命令激活（不需要激活工具）-下一朵云"></p>
<p>本文链接：<a href="https://www.orcy.net.cn/1802.html%EF%BC%8C%E8%BD%AC%E8%BD%BD%E8%AF%B7%E9%99%84%E4%B8%8A%E5%8E%9F%E6%96%87%E5%87%BA%E5%A4%84%E9%93%BE%E6%8E%A5">https://www.orcy.net.cn/1802.html，转载请附上原文出处链接</a></p>
]]></content:encoded>
    </item>
  </channel>
</rss>
