企业官网建设流程全解析

一、环境安装

1、claude code 安装命令

npm install -g @anthropic-ai/claude-code

2、绕过登陆——windows

步骤1：定位配置文件
首先需要找到Claude Code的配置文件。在Windows系统中，配置文件位于：
# 配置文件路径
C:\Users\{用户名}\.claude.json
步骤2：编辑配置文件
使用文本编辑器（如Notepad 、VS Code等）打开配置文件，添加或修改以下配置项：
{ "hasCompletedOnboarding": true }
macOS系统
在macOS系统中，配置文件位于
# 配置文件路径
~/.claude.json

3、安装node

3.1 更改镜像站为国内地址

npm config set registry https://registry.npmmirror.com

3.2 验证

npm -V # 验证是否安装成功
npm config get registry #验证镜像站是否更改成功

4、安装CC Switch

5、在CC Switch更改对应大模型为deepseek

6、终端中命令行：重启claude

命令行输入：claude

二、ai编程实现步骤

1. 进入终端，在工程目录启动claude
2. 整体的项目概况，和整体的约束，不能过长，精简内容/init 生成claud.md，自己审视，做调整
3. 先进入plan模式，先规划 审核没问题之后再让ai执行
   1. /init 生成claud.md，自己审视，做调整
   2. claud.md 通用指导：约束
4. 修改ai生成的规划，自己需要审视看一下是否合理
5. 上下文管理：
   • 上下文压缩：上下文过多时，只保留重要信息
   • 上下文清理(/clear): 上下步骤之前的实现没有关联时

6. 有异常时直接打断(esc) 退出

三、快捷键、常用操作

/init # 代码执行前，生成claud.md
/clear ：上下文没有关联时清空上下文
/compact ：对上下文进行压缩
shift+tab 进入plan 模式
CTRL + G 修改ai生成的规划

四、如何提高Claude code成功率

1.让claude自己进行验证

给出一些测试用例，当claude完成coding之后，可以自己进行验证。

Claude 会反复跑测试、读报错、改代码、再跑——直到测试全过。整个过程不用你介入。

例如：claude实现手机号验证案例：

写一个validatePhone函数。

测试用例：

• 13812345678 → true

• 1381234567（10 位）→ false

• +8613812345678（带国家码）→ true

• 138-1234-5678（带分隔符）→ true

• 12345678901（不是 1 开头）→ false

写完后跑一下这些用例，全部通过再交给我。

其它验证方式：

2.先探索 → 再规划 → 最后写代码

概念：prompt -> 规划 -> 查看规划是否正确、可行 -> ctrl + g 修改规划 -> claud执行

规划是否正确标准：

• 【重要】是否更改了其它额外的文件
• 实现的逻辑是否正确、可行
• 调用api，查询的数据文件，实现用到的包、方法 是否是你想要的

实现步骤：

1. shift + tab 切换到规划模式，确认下边为: "plan mode on"
2. 查看claude生成的规划是否正确
3. 确认规划没有问题，让claud进行执行

3.发现错了立刻打断

概念：当发现claude执行异常，执行跑偏时，立刻打断执行，修改、细化 提示词再次执行

打断方式：

• esc(按一次)：Claude 干活的时候，按 Esc，它立刻停。上下文保留，你可以重新引导。
• esc(连按两次): 按两次 Esc（或者输入 /rewind），打开回退菜单：

✅只回退对话（保留代码）

✅只回退代码（保留对话）

✅都回退到某个检查点

✅从某条消息开始重新总结

• Undo that: 直接输入"Undo that" 或 "撤销刚才的改动"。简单粗暴，最常用

4.做好上下文管理

前边的对话信息，会影响模型对之后对话的处理。Claude Code 现在确实支持 100 万 token，但上下文越满，模型表现越差。

要求：

• 历史会话信息及时 /clear，不让长时间保留
• 任务执行结束，之后没有相关任务，及时/clear
• 纠正超过两次还没改对，立刻 /clear 重来
• 长任务到 60-70% 主动 /compact。/compact 会把历史对话总结成摘要，腾出空间
• /statusline状态栏：输入/statusline，让 Claude 帮你生成一个状态栏脚本，把"当前目录、Git 分支、上下文使用率"实时显示在终端底部

5.写一份精简的 CLAUDE.md

5.1 为什么要claude.md要尽可能精简？

claude位于项目的根目录，作为项目专属的上下文和指令，claude每次启动时都会自动读它，索引放置的信息不能过多，一般不超800行。

5.2 需包含哪些信息：

项目级：一个团队的开发规范

一个合格claud.md就像给新同事的一个 项目速查卡，包含 项目意图、架构和可执行细节，—必须让Claude时刻注意的才写进去。

• 项目概览：项目是干什么的、面向谁、核心价值

• 技术栈与依赖：使用什么环境，特定的版本

• 目录结构速览

• 常用命令

• 代码规范和约定

• 架构原则与涉及准测

• 环境变量和配置

• 测试验证策略

• 外部服务依赖

• 注意事项

6.别说"我不要什么"，要说"我要什么"

不要说"你做错了"，而是告诉大模型"应该怎么做，及具体实现步骤"

使用技巧：

技巧 1：用 @ 引用具体文件

例如："对照@src/types/order.ts里的类型，给 OrderService 加上类型注解"

技巧 2：用 ! 直接执行命令

例如：

！netstate -autlp | grep 8080 ：查看端口运行状态

! git status ：查看工作目录和暂存区的文件状态

技巧 3：粘贴截图

看到 Bug 的页面 →截图 → Cmd+V 直接粘进去。Claude 能看图。比你打一段描述准确十倍——尤其是 UI 问题。

7. 【重要】进阶玩法：让 Claude 来"面试"你

适用情况：当需求复杂，或你也不清楚具体实现时，可以让claud反问你

示例：

我想做一个"购物车合并"功能（用户登录

时把游客购物车合并到账号）。

请你用 AskUserQuestion 工具来面试我，把

技术实现、UI/UX、边界情况都问一遍。

不要问太显而易见的问题，挖那些我可能

没考虑到的难点（比如商品下架、库存变化、

价格变化怎么办）。

所有问题问完后，把完整规格写到 SPEC.md。

8.让 Subagent（子代理） 替你干"读很多文件"的苦差

8.1 为什么需要subagent？

例如，你接手了一个老项目，里面充斥着屎山代码。你想让 Claude 先帮你了解：{这个项目里订单状态是怎么流转的？哪些地方会修改订单状态？}

Claude 一头扎进代码库，读了 30 个文件——每个文件都进了你的上下文

等它读完出结论，你的上下文已经用掉一半了。然后你想让它真正动手改个 Bug——上下文不够用了。

8.2 subagent使用：

在请求前面加一句"用 subagent"，之后claud就会开启一个或多个子任务去执行，不会影响主对话的上下文

示例：

用一个 subagent 调研：

我们项目里订单状态是怎么流转的？

哪些地方会修改订单状态？

最后给我一份订单状态机图（Mermaid 格式）

+ 涉及文件清单。

8.3 适用场景

✅调研类：「看看 X 是怎么实现的」

✅大范围搜索：「找出所有用了过期 API 的地方」

✅验证类：「用一个 subagent 检查这段代码的边界情况」

✅输出长但结论短的任务

8.4 进阶玩法

分两轮或多轮实现，第一轮先执行具体需求，第二轮任务再去对第一轮的结果进行验证、筛选出正确、有效的。

示例：

第一轮：

用三个 subagent 分别实现：

检查代码风格

翻项目历史，看类似改动有没有踩过坑

查明显 Bug

第二轮：

用五个subagent 去验证上边的子任务的输出，把假阳性筛掉。

五、具体实现示例

1. claud.md

claud.md 放什么：项目级的主要放置团队的开发规范、易踩坑点、使用什么环境

EduRAG 开发指南

1. 项目目标

本项目是面向教育咨询场景的集成问答系统。目标是把结构化 FAQ 检索与非结构化知识库 RAG 组合为可评估、可服务化、可部署的完整应用。

开发必须基于仓库当前事实渐进推进。本文记录的实现状态是 2026-07-18 的快照；每次修改前都要重新读取相关文件，不得仅凭本文假设代码仍未变化。

优先保证：安全、正确、可运行、可验证。不要为追求架构完整而一次性重写项目。

2. 目标架构

在线查询主链路：

用户请求
-> 参数校验与会话上下文
-> Redis 缓存 / MySQL FAQ / BM25 + Softmax
-> FAQ 置信度足够：直接返回
-> FAQ 未命中：Query 分类与检索策略选择
-> Milvus 稠密 + 稀疏混合检索
-> BGE reranker 重排并恢复父块
-> Prompt 组装上下文、问题与会话历史
-> LLM 生成有依据的回答
-> 返回答案、来源和必要的诊断信息

离线知识入库链路：

PDF / DOCX / PPTX / 图片 / Markdown
-> 文档解析与 OCR
-> 文本清洗
-> 父块与子块切分
-> 元数据标准化
-> BGE-M3 稠密/稀疏向量
-> Milvus upsert

外部依赖包括 MySQL、Redis、Milvus、本地 BERT/BGE 模型和兼容 OpenAI SDK 的 LLM 服务。代码不得假设这些服务始终在线。

3. 目录职责

• base/：全局配置与日志。

• mysql_qa/：MySQL FAQ、Redis 缓存、中文预处理和 BM25 检索。

• rag_qa/core/：分类、策略、向量检索、Prompt 与 RAG 编排。

• rag_qa/edu_document_loaders/：PDF、Word、PPT、图片及 OCR 加载器。

• rag_qa/edu_text_spliter/：中文递归切分和模型辅助切分。

• rag_qa/data/：知识库原始数据；不要在测试中覆盖。

• rag_qa/models/：本地模型文件；不要复制、改写或提交新的大模型权重。

• rag_qa/main.py：预定的集成问答入口，当前为空。

• verify_vector_store.py：文档处理、Milvus 入库和检索的三级验证脚本，依赖本地模型与 Milvus。

• requirements.txt：当前 Python 依赖基线。

新增模块应放进职责最接近的目录。不要继续通过随意修改sys.path掩盖包结构问题。

4. 统一配置使用规范

生成或修改代码前，必须先读取base/config.py，确认项目已有的配置项及其命名；需要了解具体部署值或配置来源时，再检查仓库根目录的config.ini和对应环境变量。仓库当前没有base/conf.py，不得根据习惯臆造该文件或从中导入配置。

• 业务代码统一通过from base.config import config（或现有的from base import config）使用配置，不得在业务模块中重复创建Config实例。

• 文件与目录路径优先使用config.PROJECT_ROOT、config.LOG_DIR、config.DATA_DIR、config.MODELS_DIR、config.EDU_DOCUMENT_LOADERS_DIR和config.LOG_FILE，不得硬编码本机绝对路径，也不要依赖当前工作目录拼接项目资源。

• 大模型调用必须复用config.LLM_MODEL、config.DASHSCOPE_BASE_URL和config.DASHSCOPE_API_KEY；不得在调用处另写模型名、服务地址或密钥。单元测试应注入 fake client 或显式测试配置，不能调用真实模型服务。

• MySQL、Redis 和 Milvus 连接参数必须分别复用config.MYSQL_*、config.REDIS_*和config.MILVUS_*；检索、切分和候选数量使用config.PARENT_CHUNK_SIZE、config.CHILD_CHUNK_SIZE、config.CHUNK_OVERLAP、config.RETRIEVAL_K、config.CANDIDATE_M。

• 新需求所需配置已存在时直接复用，不得创建同义常量或复制默认值。配置缺失时，先在base/config.py中增加语义明确的配置属性，并按“环境变量优先、config.ini次之、安全默认值最后”的顺序读取，再由业务模块引用。

• 密码、API Key 等敏感值只能来自环境变量；新增配置不得提供真实凭据或可用密钥作为 fallback，也不得把敏感值写入日志、测试夹具或示例文件。

• 函数参数若允许调用方显式覆盖配置，应使用None作为默认值并在函数内部读取config，避免在导入阶段固化配置；同时保留依赖注入能力，便于测试。

• 若配置名、类型或来源不确定，先用rg检查base/config.py和现有调用方，不得凭记忆猜测。配置变化需要验证默认值、环境变量覆盖、类型转换以及缺失配置时的行为。

5. 当前实现状态

已实现

• MySQL 连接、FAQ 表操作和 CSV 导入。

• Redis 基础读写与答案缓存。

• 中文分词、BM25 + Softmax FAQ 检索。

• 配置读取和日志记录。

• 多格式文档加载器、OCR 和中文文本切分器。

• 统一文档处理入口：递归发现文件、选择加载器、补充元数据并进行父子分块。

• BGE-M3 稠密/稀疏向量、Milvus schema 与混合检索的基础代码。

• BGE reranker 基础调用。

• RAG Prompt、HyDE、子查询和回溯 Prompt 模板。

“已实现”只表示存在主体代码，不代表已通过端到端验证。

部分实现或已知故障

• rag_qa/core/document_processor.py已存在，但缺少测试；加载异常目前只记日志并继续，父块 ID 只基于遍历序号，尚未验证重复入库的稳定性。

• process_documents()当前只接收directory_path，切分参数直接读取全局配置；后续公开接口需先由测试固定。

• rag_qa/core/vector_store.py中父块去重错误地追加了列表自身，应先用测试复现再修复。

• hybrid_search_with_rerank()的k与部分 limit 配置没有形成一致行为。

• verify_vector_store.py已能找到文档处理模块，但会加载大型本地模型、连接/创建 Milvus 数据库并写入 collection；不能把它当作无副作用的基础测试。

• 配置文件包含凭据，base/config.py还存在敏感默认值与eval()，必须优先治理。

尚未实现

• rag_qa/core/query_classifier.py为空，Query 分类尚未实现。

• rag_qa/core/rag_system.py为空，RAG 检索与生成编排尚未实现。

• rag_qa/core/strategy_selector.py为空。

• rag_qa/main.py为空，正式集成入口尚未实现。

• 可靠的 FAQ -> RAG 回退编排与错误隔离。

• 会话创建、最近历史、历史查询、更新和清除。

• FastAPI 请求/响应模型、非流式接口和 WebSocket 流式接口。

• 健康检查、学科列表和静态资源服务。

• RAGAS 评估脚本、固定评估集和指标基线。

• Dockerfile、部署脚本和 API 使用说明。

• 自动化测试目录及稳定的单元/集成测试基线。

• Query 改写 Prompt 对应的实际执行与检索融合。

6. 实现路线图

除非用户明确指定任务，按以下顺序选择最靠前、尚未完成且可独立验证的一项：

1. 安全与运行基线：移除源码中的敏感默认值，使用环境变量，替换eval()，建立最小测试框架。

2. 文档处理基线：为文件发现、加载失败、父子分块和元数据补测试，统一process_documents()调用接口。

3. 向量检索修复：修复父块去重、参数传递、空结果、过滤表达式和重排稳定性。

4. Query 分类与策略：实现可独立训练/加载/预测的分类器及确定性的策略选择，定义模型缺失时的降级行为。

5. RAG 核心：实现直接检索、HyDE、子查询、回溯检索、上下文组装、LLM 调用和无答案兜底。

6. 集成问答：实现正式入口，融合 FAQ 优先与 RAG 回退，并保证数据库、缓存和模型资源正确关闭。

7. 会话能力：实现有界历史存储、读取、更新、清理和历史相关性控制。

8. API 服务：实现 FastAPI 非流式查询、WebSocket 流式查询、会话、健康检查和学科接口。

9. 质量评估：建立固定数据集与 RAGAS 指标基线，保存可比较的结果。

10. 生产部署：补充 Dockerfile、启动方式、健康检查、配置注入和接口说明。

11. 可选增强：Query 改写、多查询融合、评估集生成和性能优化。

不要同时推进多个阶段。后续阶段依赖前序接口时，先固定接口并用测试锁定行为。

7. 每次任务的强制流程

1. 检查：阅读目标文件、调用方、配置和现有验证脚本；用rg确认真实引用关系。

2. 定界：用 3～6 行说明目标、非目标、涉及文件、外部依赖与风险。

3. 验证失败：优先补充能复现问题的最小测试；没有测试框架时使用不依赖生产数据的独立验证。

4. 最小实现：只修改当前目标需要的代码，保持现有公开接口，除非接口本身就是问题。

5. 分层验证：先做静态与单元检查，再做组件集成，最后才运行完整外部服务链路。

6. 复查：检查异常路径、资源释放、日志泄密、硬编码路径和无关改动。

7. 汇报：列出改动、实际运行的命令、结果、未验证项和下一优先事项。

修改前不要大段复述项目背景。若用户请求明确且安全，直接执行；只有会显著改变架构或数据时才询问。

8. 编码与安全约束

• Python 代码保持职责单一；优先小函数、显式类型和依赖注入。

• 不新增全局单例来隐藏数据库、模型或网络依赖。

• 导入模块不得自动连接服务、创建数据库、加载大型模型或写入数据；重操作放入显式函数或入口。

• 所有连接、游标、文件、模型调用和 WebSocket 都要有明确的异常处理与释放路径。

• 不使用裸except，日志要保留可诊断上下文，但不得记录密码、API Key、完整 Prompt、私人数据或整篇文档。

• 密钥只从环境变量读取。提交配置示例时只能使用明确无效的示例值。

• 禁止使用eval()解析配置；使用 JSON、ast.literal_eval或明确的列表解析。

• 不修改或删除用户数据、Milvus collection、MySQL 表和 Redis 全库，除非用户明确授权。

• 测试使用临时目录、mock/fake 客户端或专用测试库，不依赖现有业务数据。

• 不提交__pycache__、日志、IDE 状态、密钥、模型权重、生成数据或本地数据库文件。

• 新增依赖前先确认现有依赖不能满足需求；同步更新依赖文件并说明原因。

• 遵循当前锁定版本的 API。遇到版本差异时先检查本地包签名或官方文档，不凭记忆猜测。

• 不以“顺手优化”为由改写无关模块，不做无验收标准的大规模重构。

9. 验证要求

从仓库根目录运行命令。优先使用当前 Python 环境，不擅自重装全部依赖。

基础检查：

python -m compileall base mysql_qa rag_qa
python -m pytest -q

如果尚无tests/或 pytest 未安装，要明确报告，而不是声称测试通过。新增首个测试时再补充最小测试依赖。

按需执行组件检查：

• 配置/纯函数：不得连接任何外部服务。

• MySQL/Redis：分别验证连接失败、空数据、缓存命中与缓存未命中。

• 文档处理：使用小型 fixture 验证格式识别、父子块关系和元数据完整性。

• Milvus：验证建库/加载、幂等 upsert、空检索、source 过滤、去重和重排顺序。

• LLM：单元测试使用 fake callable；真实 API 调用只能作为显式集成测试。

• FastAPI：使用测试客户端验证状态码、schema、错误响应和会话隔离。

• WebSocket：验证正常流、客户端断开和生成异常后的关闭行为。

• RAGAS：使用固定数据集和确定的配置，结果需带时间、模型与检索参数。

MySQL、Redis、Milvus、本地模型或 LLM 服务不可用时：

1. 不要降低断言或吞掉异常来制造通过结果。

2. 完成可运行的静态、单元和 fake-client 验证。

3. 明确列出未执行的集成测试及其所需条件。

verify_vector_store.py是有外部依赖且会写 Milvus 的手动集成检查，不是单元测试。运行前先确认目标 host、database、collection 和数据目录，未经用户授权不得对现有业务 collection 执行写入。

10. RAG 专项验收标准

• 检索结果必须保留source、timestamp、parent_id和父块内容等必要元数据。

• 父块去重应稳定且保持最相关顺序；相同父块不能重复进入 Prompt。

• 稠密、稀疏检索和 reranker 的候选数、权重与最终数量必须来自配置且可测试。

• source 过滤必须使用白名单校验，不能直接拼接任意用户输入。

• 没有检索结果时不得崩溃；应执行明确的直答或无答案策略。

• 专业咨询进入知识库链路；分类模型未训练或加载失败时必须有可观察的降级策略。

• 回答应忠于上下文，信息不足时使用统一兜底，不得编造培训项目、价格、教师或联系方式。

• FAQ 命中、RAG 回退和直答路径必须能从结构化日志或返回元数据中区分。

• 性能优化必须同时记录质量指标；不能只凭耗时降低就认定改进有效。

11. 完成任务时的输出

最终回复保持简洁，并包含：

• 完成了什么，以及关键文件。

• 实际运行的验证命令和结果。

• 哪些外部集成未验证及原因。

• 是否存在数据迁移、配置变化或兼容性风险。

• 最合理的下一项工作；不要擅自开始下一阶段。

禁止使用“应该可以”“理论上通过”代替验证证据。没有运行，就明确写“未运行”。

2. 实现QueryClassifier

需规定文件、接口名称、返回值，需要和外部进行对接，接口方法名称一般是固定的

需明确已经构建的，配置文件路径、用到的方法名

明确实现的功能，按步骤书写，有需要的工具、方法可以指定

实现 QueryClassifier

请先阅读项目根目录的CLAUDE.md，并检查：

• base/config.py

• base/logger.py

• base/__init__.py

• 项目中现有的配置与日志调用方式

• 当前 Transformers 版本的TrainingArguments参数

然后在：

rag_qa/core/query_classifier.py

中实现基于本地中文 BERT 的 Query 二分类器，将问题分类为：

• 通用知识

• 专业咨询

要求实现以下功能：

1. 从项目现有配置中获取基础 BERT 模型路径、训练数据路径和训练模型保存路径，不重复硬编码已有配置。

2. 仅加载本地模型，禁止联网。

3. 如果已有训练模型则自动加载，否则从基础 BERT 初始化二分类模型。

4. 读取 JSONL 训练数据，按 8:2 划分训练集和验证集。

5. 使用 Hugging FaceTrainer完成训练。

6. 使用验证集输出 accuracy、classification report 和 confusion matrix。

7. 保存训练后的模型和 tokenizer。

8. 自动支持 CUDA、MPS 和 CPU。

9. 模型未训练或加载失败时，提供明确日志和安全降级策略。

10. 提供公开方法：

classifier = QueryClassifier() classifier.train_model() category = classifier.predict_category("人工智能课程多少钱？")

其中：

predict_category(query: str) -> str

返回通用知识或专业咨询。

要完整实现以上功能。不要修改无关文件。

完成后按CLAUDE.md要求执行静态检查；能运行的验证必须实际运行，并报告结果，未运行的测试要明确说明原因。