这篇笔记从 Python 的 module 与 package 基本模型切入，把“一个 .py 文件就是模块、目录可组织为包和子包”的关系先讲清楚，再延伸到 import 触发后的查找流程。正文重点解释了 Python 会先检查 sys.modules 缓存，命中则复用已加载模块，若对应值为 None 会抛出 ModuleNotFoundError；未命中时再遍历 sys.meta_path，由内置模块、冻结模块和基于路径的查找器继续解析。文章结合 sys.path 的实际输出，拆解了项目目录、脚本目录、PyCharm 辅助路径、标准库 zip 与动态库路径、虚拟环境 site-packages 在导入搜索中的作用，适合用来定位“为什么某个模块能或不能被导入”。相对导入与绝对导入部分对比了 import A.B、from A import B 以及 from . import B、from ..A import B 等写法，并指出直接运行脚本与使用 python -m 以模块方式运行时，放入 sys.path 的目录不同，可能影响导入结果。依赖管理部分补充了 pip install 后包目录、dist-info、扩展文件和元数据的组成，以及 pip freeze 生成完整环境依赖、pipreqs 扫描项目生成最小依赖列表的差异。最后还提到导包顺序通常按标准库、第三方库、自定义库分组并字母排序，可借助 usort 格式化，整体适合 Python 初学者、后端开发和需要排查导入路径问题的项目维护者阅读。

Python 开发

2025年12月6日1 分钟

关于“Python 开发”类别

“Python 开发”类别用于归档围绕 Python 语言、生态工具和工程实践展开的内容，帮助读者在同一入口下查找学习笔记、配置经验、框架应用和问题排查资料。它适合承载以 Python 为核心对象的文章，例如语言基础、项目结构、依赖与环境管理、自动化脚本、Web 或数据处理开发，以及开发过程中常见错误的定位与解决思路。分类边界应放在文章的主要问题上：只有当讨论重点是 Python 代码、Python 工具链、Python 框架或相关开发流程时，才应归入该类别。若文章只是偶尔使用 Python 示例，但核心主题属于 Linux、数据库、网络协议、AI 模型或通用架构设计，则更适合放入对应主题分类。这个类别的价值在于把零散的 Python 实践内容集中组织起来，降低后续检索和复盘成本，也便于读者按开发阶段逐步阅读。它更适合 Python 初学者、后端开发者、自动化脚本使用者，以及需要在项目中维护 Python 工程的技术读者。

Git

2025年12月6日4 分钟

cherry-pick命令

这篇笔记聚焦 git cherry-pick 在分支协作中的精确搬运能力：当只需要把其他分支上的某个小功能或少量提交带到当前分支，而不想合并整个分支时，可以直接在目标分支执行 cherry-pick。内容从单个提交开始，说明 cherry-pick 会在当前分支重新生成一个内容相同但哈希不同的新提交，并给出 -x 记录原始提交来源、-n 只把改动应用到工作区和暂存区而不自动提交等常用选项。对于多个提交，笔记区分了不连续提交逐个列出和连续范围选择两种写法，并解释 A..D 表示不含 A、包含 D，A^..D 则把 A 到 D 都纳入范围。文章也强调了使用前提和风险：一个小功能最好对应一次 commit，否则后续挑选会变得困难；cherry-pick 过程中可能发生冲突，同一个提交重复挑选还可能因为哈希不同而在历史中形成重复内容。与 merge、rebase 的对比进一步明确了适用边界：merge 适合合并整个分支并保留结构，rebase 用于重写基线和线性化历史，cherry-pick 则适合只引入必要提交。最后补充的 commit hash 说明解释了 Git 提交哈希由文件树、父提交、提交者、时间和说明等内容计算而来，完整 SHA-1 为 40 位十六进制，短哈希只要在仓库中足够长且唯一即可被识别。

Git

2025年12月6日11 分钟

gitflow 分支模型

这篇笔记围绕 Git Flow 分支模型梳理 main、dev、feature、release、hotfix 的职责边界：main 保持生产稳定，dev 承接日常集成，feature 从开发主线派生，release 用于发布前测试，hotfix 则面向线上紧急修复。文章同时对比了只保留 main、通过 Pull Request 快速合入并保持主干可发布的 GitHub Flow，指出它更适合小团队、持续部署或上线节奏很快的项目，而传统 Git Flow 更适合中大型项目的分工与发布控制。重点讨论的是一种容易踩坑的实践：从较慢的 main 切出 feature，却合入更新更快的 dev，此时 Git 并不会按时间、分支快慢或 HEAD 指针简单判断，而是寻找最近共同祖先，再基于祖先、目标分支 HEAD 和源分支 HEAD 做三方合并。只要双方从共同祖先以来修改的代码段不重叠，即使 feature 来自旧分支也可以自动合入；如果 dev 和 feature 都改了同一行或同一块逻辑，就会产生冲突。对于已合入 dev 的 feature 后续发现 bug，文章给出两种处理路径：继续在原 feature 上提交修复再合入，或从 dev 最新状态新建 hotfix/bugfix 分支提交 PR，后者在多人协作和分支归档场景下更清晰。最后还补充了 Git 的存储边界：分支本质只是指针，创建多个分支几乎不增加仓库体积，真正带来增长的是新增提交，尤其是大文件、图片等资源变更。

Git

2025年12月6日14 分钟

.git文件夹解析

这篇笔记围绕 .git 目录的可见方式、核心文件结构和分支切换机制，解释 Git 仓库状态并不只存在于工作区文件，而是由 HEAD、refs 和 objects 共同维护。内容先给出在 macOS 终端、Finder 与 VS Code 中查看隐藏 .git 文件夹的方法，再梳理 HEAD、config、refs、objects、hooks、logs 等条目的作用，其中 objects 被定位为 Git 存储提交、文件内容和目录结构的对象数据库。文章重点拆解 blob、tree、commit、tag 四类对象，说明对象文件经过压缩和哈希命名，不能直接用 cat 阅读，而应通过 git cat-file -t 和 -p 查看类型与内容。通过 commit hash 追踪到 tree，再从 tree 找到 blob 的示例，笔记解释了为什么 git cat-file -p commit 只能看到提交元信息、父提交和 tree 指针，而不会直接显示代码内容；若目标是查看一次提交的改动，应使用 git show 获取提交信息、diff 和文件变更。后半部分把 git switch 或 checkout 切换分支还原为 HEAD 指向变化、refs/heads 中提交哈希读取，以及对应 tree/blob 快照写入工作区的过程，并用 HEAD → refs → commit → tree → blob 的链路串起内部模型。文章也区分了 git switch 与 git checkout 的命令边界：前者语义更专注于分支切换，后者还能回滚文件或进入 detached HEAD，适合已经了解风险的场景。适合想从文件系统层面理解 Git 工作原理、排查提交对象疑惑，或希望更安全地区分分支切换与文件回滚命令的开发者阅读。

Git

2025年12月6日9 分钟

.gitattributes与git-lfs

这篇笔记聚焦 .gitattributes 与 Git LFS 在仓库文件管理中的分工：前者用于按文件匹配模式声明 Git 对不同文件的处理方式，后者用于把 Git 不擅长保存的大文件从普通仓库对象中分离出去。.gitattributes 的示例覆盖了 text=auto 处理跨平台换行符、为 lock 文件指定 merge=ours、为 Markdown 配置 diff 显示、用 filter/diff/merge=lfs 跟踪 psd 文件，以及将 png 标记为 binary 以避免错误的文本处理。Git LFS 部分说明了它适合设计稿、压缩包、媒体文件、机器学习模型和文档附件等场景，因为这些文件体积大、难以 diff，频繁修改会让普通 Git 仓库快速膨胀。文章通过普通 Git 与 LFS 的对比强调，本体文件进入 Git 会导致每次大文件变更都增加仓库负担，而 LFS 只在仓库中保存指针，真实内容上传到专用 LFS 存储，clone 或 pull 时再下载对应内容。操作流程也给出基本命令：先 git lfs install，再用 git lfs track 指定文件类型，提交生成的 .gitattributes，之后按正常 add、commit、push 工作。最后补充了 Git 快照存储的细节：提交看似记录完整快照，但未变化文件会复用相同哈希对象，只有内容变化的文件生成新的 blob；即便文本只改一个字，也会按文件生成新对象，而不是块级增量备份。适合需要理解 Git 仓库体积控制、大文件协作和 .gitattributes 配置作用的开发者或团队成员阅读。

Git

2025年12月6日5 分钟

Github 开源协议

这份笔记面向准备在 GitHub 上发布代码、库或文档的开发者，聚焦如何用开源许可证约束后续使用、修改、商用和再分发。内容用表格横向比较 MIT、Apache 2.0、GPL v3、LGPL v3、BSD、MPL、AGPL、Unlicense 与 Creative Commons，重点列出是否允许商用、是否要求衍生品开源、能否闭源使用以及是否允许修改等决策维度。它特别强调许可证“传染性”的差异：MIT、Apache、BSD 和 Unlicense 更宽松，通常允许闭源引用；GPL 与 AGPL 要求更强，AGPL 还覆盖网络部署和 SaaS 场景；LGPL 与 MPL 则分别以共享库和文件级开源形成折中。针对不同使用目的，笔记给出 MIT/Apache 2.0、GPL v3、LGPL/MPL、CC BY/CC0、Unlicense 等推荐取向，帮助读者在商业项目、自由软件、可闭源集成、文档内容和公共领域释放之间快速筛选。需要注意的是，Creative Commons 主要面向文章、文档等内容作品而非代码，选择时应区分代码许可证和内容授权。最后还提供 choosealicense.com 与 GitHub CLI 创建仓库时选择协议的入口，适合作为开源项目初始化前的速查清单。

github

Git

2025年12月6日9 分钟

Git删除敏感密钥

这篇记录面向“私钥、.env.dev 等敏感文件已经被提交并推到 GitHub，而后续提交还需要保留”的事故处理场景，目标是在不丢失最新提交的前提下，把敏感内容从整个 Git 历史中清除。处理流程以 git-filter-repo 为核心：先通过 brew 或 pip 安装工具，再用 `git branch backup-main` 备份当前分支，随后执行 `git filter-repo --force --path .env.dev --invert-paths` 将指定文件从历史里剔除。文章特别强调该操作会重写提交链，并可能清空 `.git/config` 中的 remote、抹除 reflog 和旧提交，因此执行后需要重新 `git remote add origin`、设置 main 追踪 `origin/main`，最后用 `git push origin main --force` 覆盖远程历史。对于重写历史后无法直接 merge、分支误删或改名等情况，记录给出通过 `git reflog` 查找旧引用并用 `git checkout -b` 恢复分支的思路。后半部分解释 Git 不能简单删除某个 commit hash：提交对象包含父提交、快照和元信息，后续提交依赖这些哈希引用，强行删除中间节点会破坏历史链。文章还对比 revert、reset、rebase 与 filter-repo，说明 revert 适合保留协作历史的普通撤销，而泄露密钥这类需要永久清除痕迹的问题，应使用重写历史工具并谨慎强推。

Git

2025年12月6日1 分钟

关于“Git”类别

Git 类别用于承载围绕版本控制工具 Git 的说明、规范与实践内容，帮助站点在开发工具和工程协作相关主题中保留一个清晰入口。该类别适合收录 Git 的日常使用、分支与提交规则、协作流程、仓库管理、问题排查，以及与版本历史、合并冲突、远程同步等直接相关的经验整理。它的边界应聚焦于 Git 本身及其使用场景，而不是泛化到所有开发工具、项目管理或软件工程方法；只有当文章的核心问题依赖 Git 概念、命令或工作流时，才应归入此类。分类维护时需要关注它与相邻类别的重叠程度，例如 CI/CD、代码托管平台或团队协作规范中的内容，若重点不在 Git，则更适合放入对应主题。这个类别的价值在于为开发者、维护者和技术写作者提供稳定的检索路径，使 Git 相关知识不会分散在过宽的工程实践分类中。若后续内容数量较少或主题长期与其他类别高度重复，也应重新评估是否保留独立分类或合并为更合适的上级主题。

AI 大模型开发

2025年12月6日15 分钟

FastAPI-MCP

这篇笔记聚焦 fastapi-mcp 在 FastAPI 与大模型工具调用之间的衔接方式，说明它如何把现有 API 端点转换为符合 MCP 的工具描述，让 Coze、通义、百川、智谱等平台更容易识别接口能力。内容先给出服务端示例：使用 FastApiMCP 挂载到 /mcp，接口通过 Pydantic 模型定义请求体，并显式设置 operation_id，同时可额外暴露 openapi.json 供客户端读取。文章强调 operation_id 是外部调用时定位接口的唯一标识，不能依赖 FastAPI 自动生成的冗长默认值；请求方法、请求体结构、description、summary 等信息也会影响大模型是否能准确理解参数。随后它拆解 MCPClient 的实际工作流程：先获取 openapi.json，根据 operation_id 找到路径和方法，再组装并发送普通 HTTP 请求，因此 MCP 并不是替代 HTTP 的新传输协议，而是面向大模型的 OpenAPI 子集和调用约定。后半部分用 OpenAI 兼容的 tool call 示例说明，大模型通常只生成函数名和参数，不会自动替开发者请求本地接口。要形成完整闭环，仍需要中转层或代理服务负责执行 HTTP 调用、把工具结果写回 messages，并再次请求模型生成最终回复；LangChain、Flowise 或自建代理可以承担这类自动执行逻辑。

fastapimcp

AI 大模型开发

2025年12月6日11 分钟

类openai基本对话代码

这份笔记围绕 Python 异步项目中封装类 OpenAI Chat 接口的基础用法展开，场景是通过 one-api 统一管理不同模型服务后，在业务代码里只需关注 model 参数切换具体模型。代码使用 AsyncOpenAI 初始化客户端，并提供两个常用方法：gpt_stream 以异步生成器方式开启 stream=True，逐块 yield 模型返回内容；gpt_chat_no_stream 则一次性获取回复，适合普通问答或需要结构化结果的调用。非流式函数还演示了 JSON 输出的处理方式，包括在 system 提示中强调只返回 JSON、设置 response_format，以及对返回内容执行 json.loads。文章同时说明 Chat 接口的 messages 结构由 system、user、assistant 三类角色组成，推荐将 system 放在最前，历史对话按时间顺序追加，再放入当前用户输入。需要注意的是，历史记录可以帮助模型延续上下文，但不应重复塞入 system 指令，过长历史也会增加 token 成本，因此应根据业务做裁剪或摘要。整体适合正在把大模型能力接入后端服务、需要同时支持流式输出和结构化返回的开发者参考。

openai对话代码

AI 大模型开发

2025年12月6日12 分钟

多段AI记忆拼接与上下文压缩(初步)

这份草稿围绕 AI 对话系统中的长期记忆与上下文压缩展开，目标是在多轮聊天中兼顾相关历史召回、上下文长度限制、响应延迟和存储成本。方案把一次请求链路拆成 MemoryRetriever、ContextManager、PromptBuilder、GPTClient、MemoryUpdater 等模块：先按用户输入检索多段记忆，再用滑动窗口裁剪近期对话，必要时调用 Summarizer 压缩溢出内容，最后拼接 system、memory、window、user 形成模型 messages，并把回复或摘要写回 MemoryStore。实现细节强调在消息记录中预存字符数或 token 数，从最近 5 轮对话取 5 条用户消息和 5 条 AI 回复，按时间排序后累加长度，以较低遍历成本避免单条长消息撑爆上下文。摘要策略部分比较了按回合生成 memory_segment、让主模型同次输出 answer 与 summary、以及后台 Worker 异步调用廉价模型摘要三种做法。草稿也指出工程上的取舍：同步摘要更简单但可能增加延迟，异步摘要能保留流式体验并通过固定条数淘汰控制规模，格式异常时还需要客户端校验和降级。它适合作为聊天产品、AI 应用后端或 Agent 记忆系统的初步设计参考，帮助评估上下文完整性、检索粒度、调用成本和实现复杂度之间的平衡。

上下文记忆拼接

文章归档

183 篇